---
title: "Custom Template Loader"
weight: 10
date: 2023-07-14T16:57:50.756Z
showtoc: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->

# Custom Template Loader
<div class="symbol">


# TemplateLoader

{{< generation-info sourceFile="packages/email-plugin/src/types.ts" sourceLine="390" packageName="@vendure/email-plugin">}}

Load an email template based on the given request context, type and template name
and return the template as a string.

*Example*

```TypeScript
import { EmailPlugin, TemplateLoader } from '@vendure/email-plugin';

class MyTemplateLoader implements TemplateLoader {
     loadTemplate(injector, ctx, { type, templateName, templateVars }){
         return myCustomTemplateFunction(ctx);
     }
}

// In vendure-config.ts:
...
EmailPlugin.init({
    templateLoader: new MyTemplateLoader()
    ...
})
```

## Signature

```TypeScript
interface TemplateLoader {
  loadTemplate(injector: Injector, ctx: RequestContext, input: LoadTemplateInput): Promise<string>;
  loadPartials?(): Promise<Partial[]>;
}
```
## Members

### loadTemplate

{{< member-info kind="method" type="(injector: <a href='/typescript-api/common/injector#injector'>Injector</a>, ctx: <a href='/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: LoadTemplateInput) => Promise&#60;string&#62;"  >}}

{{< member-description >}}{{< /member-description >}}

### loadPartials

{{< member-info kind="method" type="() => Promise&#60;Partial[]&#62;"  >}}

{{< member-description >}}{{< /member-description >}}


</div>


---

---
title: TODO
---
This part still needs to be written! 

```
( ° ᴗ°)~ð (/❛o❛\)
```


---

---
title: 'Auth'
---

**Authentication** is the process of determining the identity of a user. Common ways of authenticating a user are by asking the user for secret credentials (username & password) or by a third-party authentication provider such as Facebook or Google login.

**Authorization** is a related concept, which means that once we have verified the identity of a user, we can then determine what that user is allowed to do. For example, a user may be authorized to view a product, but not to edit it.

The term **auth** is shorthand for _both_ authentication and authorization.

Auth in Vendure applies to both **administrators** and **customers**. Authentication is controlled by the configured `AuthenticationStrategies`, and authorization is controlled by the configured `Roles` and `Permissions`.

## Administrator auth

Administrators are required to authenticate before they can perform any operations in the Admin API.

Here is a diagram of the parts that make up Administrator authentication:

![Administrator authentication](./admin.webp)

Roles can be created to allow fine-grained control over what a particular administrator has access to (see the section below).

## Customer auth

Customer only need to authenticate if they want to access a restricted operation related to their account, such as 
viewing past orders or updating an address.

Here are the parts that make up Customer authentication:

![Customer authentication](./customer.webp)

### Guest customers

Vendure also supports **guest customers**, meaning that a customer can place an order without needing to register an account, and thus not getting an
associated user or role. A guest customer, having no roles and thus no permissions, is then unable to view past orders or access any other restricted API
operations.

However, a guest customer can at a later point register an account using the same email address, at which point they will get a user with the "Customer" role,
and be able to view their past orders.


## Roles & Permissions

Both the `Customer` and `Administrator` entities relate to a single [`User`](/reference/typescript-api/entities/user/) entity which in turn has one or more [`Roles`](/reference/typescript-api/entities/role/) for controlling permissions.


![Administrators & Roles](./admin-role.webp)

In the example above, the administrator Sam Bailey has two roles assigned: "Order Manager" and "Catalog Manager". An administrator
can have any number of roles assigned, and the permissions of all roles are combined to determine the permissions of the
administrator. In this way, you can have fine-grained control over which administrators can perform which actions.

There are 2 special roles which are created by default and cannot be changed:

- **SuperAdmin**: This role has all permissions, and cannot be edited or deleted. It is assigned to the first administrator
  created when the server is started.
- **Customer**: This role is assigned to all registered customers.


All other roles can be user-defined. Here's an example of an "Inventory Manager" role being defined in the Admin UI:

![Inventory Manager role](./roles.webp)



## Native authentication

By default, Vendure uses a username/email address and password to authenticate users, which is implemented by the [`NativeAuthenticationStrategy`](/reference/typescript-api/auth/native-authentication-strategy/).

There is a `login` mutation available in both the Shop API and Admin API which allows a customer or administrator to authenticate using
native authentication:

```graphql title="Admin API"
mutation {
  login(username: "superadmin", password: "superadmin") {
    ...on CurrentUser {
      id
      identifier
    }
    ...on ErrorResult {
      errorCode
      message
    }
  }
}
```

:::info
See the [Managing Sessions guide](/guides/storefront/connect-api/#managing-sessions) for how to manage authenticated sessions in your storefront/client applications.
:::

## External authentication

In addition to the built-in `NativeAuthenticationStrategy`, it is possible to define a custom [`AuthenticationStrategy`](/reference/typescript-api/auth/authentication-strategy) which allows your Vendure server to support other authentication methods such as:

- Social logins (Facebook, Google, GitHub, etc.)
- Single Sign-On (SSO) providers such as Keycloak, Auth0, etc.
- Alternative factors such as SMS, TOTP, etc.

Custom authentication strategies are set via the [`VendureConfig.authOptions` object](/reference/typescript-api/auth/auth-options/#shopauthenticationstrategy):

```ts title="src/vendure-config.ts"
import { VendureConfig, NativeAuthenticationStrategy } from '@vendure/core';

import { FacebookAuthenticationStrategy } from './plugins/authentication/facebook-authentication-strategy';
import { GoogleAuthenticationStrategy } from './plugins/authentication/google-authentication-strategy';
import { KeycloakAuthenticationStrategy } from './plugins/authentication/keycloak-authentication-strategy';

export const config: VendureConfig = {
  authOptions: {
      shopAuthenticationStrategy: [
        new NativeAuthenticationStrategy(),
        new FacebookAuthenticationStrategy(),
        new GoogleAuthenticationStrategy(),
      ],
      adminAuthenticationStrategy: [
        new NativeAuthenticationStrategy(),
        new KeycloakAuthenticationStrategy(),
      ],
  }
}
```

In the above example, we define the strategies available for authenticating in the Shop API and the Admin API. The `NativeAuthenticationStrategy` is the only one actually provided by Vendure out-of-the-box, and this is the default username/email + password strategy.

The other strategies would be custom-built (or provided by future npm packages) by creating classes that implement the [`AuthenticationStrategy` interface](/reference/typescript-api/auth/authentication-strategy).

Let's take a look at a couple of examples of what a custom AuthenticationStrategy implementation would look like.

## Custom authentication examples

### Google authentication

This example demonstrates how to implement a Google login flow.

#### Storefront setup

In your storefront, you need to integrate the Google sign-in button as described in ["Integrating Google Sign-In into your web app"](https://developers.google.com/identity/sign-in/web/sign-in). Successful authentication will result in a `onSignIn` function being called in your app. It will look something like this:

```ts
function onSignIn(googleUser) {
  graphQlQuery(
    `mutation Authenticate($token: String!) {
        authenticate(input: {
          google: { token: $token }
        }) {
        ...on CurrentUser {
            id
            identifier
        }
      }
    }`,
    { token: googleUser.getAuthResponse().id_token }
  ).then(() => {
    // redirect to account page
  });
}
```

#### Backend

On the backend, you'll need to define an AuthenticationStrategy to take the authorization token provided by the
storefront in the `authenticate` mutation, and use it to get the necessary personal information on that user from
Google.

To do this you'll need to install the `google-auth-library` npm package as described in the ["Authenticate with a backend server" guide](https://developers.google.com/identity/sign-in/web/backend-auth).

```ts title="src/plugins/authentication/google-authentication-strategy.ts"
import {
    AuthenticationStrategy,
    ExternalAuthenticationService,
    Injector,
    RequestContext,
    User,
} from '@vendure/core';
import { OAuth2Client } from 'google-auth-library';
import { DocumentNode } from 'graphql';
import gql from 'graphql-tag';

export type GoogleAuthData = {
    token: string;
};

export class GoogleAuthenticationStrategy implements AuthenticationStrategy<GoogleAuthData> {
    readonly name = 'google';
    private client: OAuth2Client;
    private externalAuthenticationService: ExternalAuthenticationService;

    constructor(private clientId: string) {
        // The clientId is obtained by creating a new OAuth client ID as described
        // in the Google guide linked above.
        this.client = new OAuth2Client(clientId);
    }

    init(injector: Injector) {
        // The ExternalAuthenticationService is a helper service which encapsulates much
        // of the common functionality related to dealing with external authentication
        // providers.
        this.externalAuthenticationService = injector.get(ExternalAuthenticationService);
    }

    defineInputType(): DocumentNode {
        // Here we define the expected input object expected by the `authenticate` mutation
        // under the "google" key.
        return gql`
        input GoogleAuthInput {
            token: String!
        }
    `;
    }

    async authenticate(ctx: RequestContext, data: GoogleAuthData): Promise<User | false> {
        // Here is the logic that uses the token provided by the storefront and uses it
        // to find the user data from Google.
        const ticket = await this.client.verifyIdToken({
            idToken: data.token,
            audience: this.clientId,
        });
        const payload = ticket.getPayload();
        if (!payload || !payload.email) {
            return false;
        }

        // First we check to see if this user has already authenticated in our
        // Vendure server using this Google account. If so, we return that
        // User object, and they will be now authenticated in Vendure.
        const user = await this.externalAuthenticationService.findCustomerUser(ctx, this.name, payload.sub);
        if (user) {
            return user;
        }

        // If no user was found, we need to create a new User and Customer based
        // on the details provided by Google. The ExternalAuthenticationService
        // provides a convenience method which encapsulates all of this into
        // a single method call.
        return this.externalAuthenticationService.createCustomerAndUser(ctx, {
            strategy: this.name,
            externalIdentifier: payload.sub,
            verified: payload.email_verified || false,
            emailAddress: payload.email,
            firstName: payload.given_name,
            lastName: payload.family_name,
        });
    }
}
```

### Facebook authentication

This example demonstrates how to implement a Facebook login flow.

#### Storefront setup

In this example, we are assuming the use of the [Facebook SDK for JavaScript](https://developers.facebook.com/docs/javascript/) in the storefront.

An implementation in React might look like this:

```tsx title="/storefront/src/components/FacebookLoginButton.tsx"
/**
 * Renders a Facebook login button.
 */
export const FBLoginButton = () => {
    const fnName = `onFbLoginButtonSuccess`;
    const router = useRouter();
    const [error, setError] = useState('');
    const [socialLoginMutation] = useMutation(AuthenticateDocument);

    useEffect(() => {
        (window as any)[fnName] = function() {
            FB.getLoginStatus(login);
        };
        return () => {
            delete (window as any)[fnName];
        };
    }, []);

    useEffect(() => {
        window?.FB?.XFBML.parse();
    }, []);

    const login = async (response: any) => {
        const {status, authResponse} = response;
        if (status === 'connected') {
            const result = await socialLoginMutation({variables: {token: authResponse.accessToken}});
            if (result.data?.authenticate.__typename === 'CurrentUser') {
                // The user has logged in, refresh the browser
                trackLogin('facebook');
                router.reload();
                return;
            }
        }
        setError('An error occurred!');
    };

    return (
        <div className="text-center" style={{ width: 188, height: 28 }}>
            <FacebookSDK />
            <div
                className="fb-login-button"
                data-width=""
                data-size="medium"
                data-button-type="login_with"
                data-layout="default"
                data-auto-logout-link="false"
                data-use-continue-as="false"
                data-scope="public_profile,email"
                data-onlogin={`${fnName}();`}
            />
            {error && <div className="text-sm text-red-500">{error}</div>}
        </div>
  );
};
```

#### Backend

```ts title="/src/plugins/authentication/facebook-authentication-strategy.ts"
import {
    AuthenticationStrategy,
    ExternalAuthenticationService,
    Injector,
    Logger,
    RequestContext,
    User,
    UserService,
} from '@vendure/core';

import { DocumentNode } from 'graphql';
import gql from 'graphql-tag';
import fetch from 'node-fetch';

export type FacebookAuthData = {
    token: string;
};

export type FacebookAuthConfig = {
    appId: string;
    appSecret: string;
    clientToken: string;
};

export class FacebookAuthenticationStrategy implements AuthenticationStrategy<FacebookAuthData> {
    readonly name = 'facebook';
    private externalAuthenticationService: ExternalAuthenticationService;
    private userService: UserService;

    constructor(private config: FacebookAuthConfig) {
    }

    init(injector: Injector) {
        // The ExternalAuthenticationService is a helper service which encapsulates much
        // of the common functionality related to dealing with external authentication
        // providers.
        this.externalAuthenticationService = injector.get(ExternalAuthenticationService);
        this.userService = injector.get(UserService);
    }

    defineInputType(): DocumentNode {
        // Here we define the expected input object expected by the `authenticate` mutation
        // under the "google" key.
        return gql`
      input FacebookAuthInput {
        token: String!
      }
    `;
    }

    private async getAppAccessToken() {
        const resp = await fetch(
            `https://graph.facebook.com/oauth/access_token?client_id=${this.config.appId}&client_secret=${this.config.appSecret}&grant_type=client_credentials`,
        );
        return await resp.json();
    }

    async authenticate(ctx: RequestContext, data: FacebookAuthData): Promise<User | false> {
        const {token} = data;
        const {access_token} = await this.getAppAccessToken();
        const resp = await fetch(
            `https://graph.facebook.com/debug_token?input_token=${token}&access_token=${access_token}`,
        );
        const result = await resp.json();

        if (!result.data) {
            return false;
        }

        const uresp = await fetch(`https://graph.facebook.com/me?access_token=${token}&fields=email,first_name,last_name`);
        const uresult = (await uresp.json()) as { id?: string; email: string; first_name: string; last_name: string };

        if (!uresult.id) {
            return false;
        }

        const existingUser = await this.externalAuthenticationService.findCustomerUser(ctx, this.name, uresult.id);

        if (existingUser) {
            // This will select all the auth methods
            return (await this.userService.getUserById(ctx, existingUser.id))!;
        }

        Logger.info(`User Create: ${JSON.stringify(uresult)}`);
        const user = await this.externalAuthenticationService.createCustomerAndUser(ctx, {
            strategy: this.name,
            externalIdentifier: uresult.id,
            verified: true,
            emailAddress: uresult.email,
            firstName: uresult.first_name,
            lastName: uresult.last_name,
        });

        user.verified = true;
        return user;
    }
}
```

### Keycloak authentication

Here's an example of an AuthenticationStrategy intended to be used on the Admin API. The use-case is when the company has an existing identity server for employees, and you'd like your Vendure shop admins to be able to authenticate with their existing accounts.

This example uses [Keycloak](https://www.keycloak.org/), a popular open-source identity management server. To get your own Keycloak server up and running in minutes, follow the [Keycloak on Docker](https://www.keycloak.org/getting-started/getting-started-docker) guide.

#### Configure a login page & Admin UI

In this example, we'll assume the login page is hosted at `http://intranet/login`. We'll also assume that a "login to Vendure" button has been added to that page and that the page is using the [Keycloak JavaScript adapter](https://www.keycloak.org/docs/latest/securing_apps/index.html#_javascript_adapter), which can be used to get the current user's authorization token:

```js title="/login/index.html"
const vendureLoginButton = document.querySelector('#vendure-login-button');

vendureLoginButton.addEventListener('click', () => {
  return graphQlQuery(`
    mutation Authenticate($token: String!) {
      authenticate(input: {
        keycloak: {
          token: $token
        }
      }) {
        ...on CurrentUser { id }
      }
    }`,
    { token: keycloak.token },
  )
  .then((result) => {
      if (result.data?.authenticate.user) {
          // successfully authenticated - redirect to Vendure Admin UI
          window.location.replace('http://localhost:3000/admin');
      }
  });
});
```

We also need to tell the Admin UI application about the custom login URL, since we have no need for the default "username/password" login form. This can be done by setting the [`loginUrl` property](/reference/typescript-api/common/admin-ui/admin-ui-config#loginurl) in the AdminUiConfig:

```ts title="/src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';
import { AdminUiPlugin } from '@vendure/admin-ui-plugin';

export const config: VendureConfig = {
    // ...
    plugins: [
        AdminUiPlugin.init({
            port: 5001,
            adminUiConfig: {
                loginUrl: 'http://intranet/login',
            },
        }),
    ],
};
```

#### Backend

First we will need to be making an HTTP call to our Keycloak server to validate the token and get the user's details. We'll use the [`node-fetch`](https://www.npmjs.com/package/node-fetch) library to make the HTTP call:

```bash
npm install node-fetch
```

The strategy is very similar to the Google authentication example (they both use the OpenID Connect standard), so we'll not duplicate the explanatory comments here:

```ts title="/src/plugins/authentication/keycloak-authentication-strategy.ts"
import fetch from 'node-fetch';
import {
    AuthenticationStrategy,
    ExternalAuthenticationService,
    Injector,
    Logger,
    RequestContext,
    RoleService,
    User,
} from '@vendure/core';
import { DocumentNode } from 'graphql';
import gql from 'graphql-tag';

export type KeycloakAuthData = {
    token: string;
};

export class KeycloakAuthenticationStrategy implements AuthenticationStrategy<KeycloakAuthData> {
    readonly name = 'keycloak';
    private externalAuthenticationService: ExternalAuthenticationService;
    private httpService: HttpService;
    private roleService: RoleService;

    init(injector: Injector) {
        this.externalAuthenticationService = injector.get(ExternalAuthenticationService);
        this.httpService = injector.get(HttpService);
        this.roleService = injector.get(RoleService);
    }

    defineInputType(): DocumentNode {
        return gql`
      input KeycloakAuthInput {
        token: String!
      }
    `;
    }

    async authenticate(ctx: RequestContext, data: KeycloakAuthData): Promise<User | false> {
        const { data: userInfo } = await fetch(
            'http://localhost:9000/auth/realms/myrealm/protocol/openid-connect/userinfo', {
                headers: {
                    Authorization: `Bearer ${data.token}`,
                },
            }).then(res => res.json());

        if (!userInfo) {
            return false;
        }
        const user = await this.externalAuthenticationService.findAdministratorUser(ctx, this.name, userInfo.sub);
        if (user) {
            return user;
        }

        // When creating an Administrator, we need to know what Role(s) to assign.
        // In this example, we've created a "merchant" role and assign that to all
        // new Administrators. In a real implementation, you can have more complex
        // logic to map an external user to a given role.
        const roles = await this.roleService.findAll();
        const merchantRole = roles.items.find((r) => r.code === 'merchant');
        if (!merchantRole) {
            Logger.error(`Could not find "merchant" role`);
            return false;
        }

        return this.externalAuthenticationService.createAdministratorAndUser(ctx, {
            strategy: this.name,
            externalIdentifier: userInfo.sub,
            identifier: userInfo.preferred_username,
            emailAddress: userInfo.email,
            firstName: userInfo.given_name,
            lastName: userInfo.family_name,
            roles: [merchantRole],
        });
    }
}
```


---

---
title: "Channels"
---

Channels are a feature of Vendure which allows multiple sales channels to be represented in a single Vendure instance. A Channel allows you to:

* Set Channel-specific currency, language, tax and shipping defaults
* Assign only specific products to the channel (with channel-specific prices)
* Create administrator roles limited to one or more channels
* Assign specific stock locations, assets, facets, collections, promotions, and other entities to the channel
* Have orders and customers associated with specific channels.

This is useful for a number of use-cases, including:

- **Multi-tenancy**: Each channel can be configured with its own set of products, shipping methods, payment methods, etc. This
  allows you to run multiple shops from a single Vendure server.
- **Multi-vendor**: Each channel can represent a distinct vendor or seller, which can be used to implement a marketplace.
- **Region-specific stores**: Each channel can be configured with its own set of languages, currencies, tax rates, etc. This
  allows you to run multiple stores for different regions from a single Vendure server.
- **Distinct sales channels**: Each channel can represent a sales channel of a single business, with one channel for the online
  store, one for selling via Amazon, one for selling via Facebook etc.


Every Vendure server always has a **default Channel**, which contains _all_ entities. Subsequent channels can then contain a subset of channel-aware entities.

![Channels high level](./channels.webp)

## Channel-aware entities

Many entities are channel-aware, meaning that they can be associated with a multiple channels. The following entities are channel-aware:

- [`Asset`](/reference/typescript-api/entities/asset/)
- [`Collection`](/reference/typescript-api/entities/collection/)
- [`Customer`](/reference/typescript-api/entities/customer/)
- [`Facet`](/reference/typescript-api/entities/facet/)
- [`FacetValue`](/reference/typescript-api/entities/facet-value/)
- [`Order`](/reference/typescript-api/entities/order/)
- [`PaymentMethod`](/reference/typescript-api/entities/payment-method/)
- [`Product`](/reference/typescript-api/entities/product/)
- [`ProductVariant`](/reference/typescript-api/entities/product-variant/)
- [`Promotion`](/reference/typescript-api/entities/promotion/)
- [`Role`](/reference/typescript-api/entities/role/)
- [`ShippingMethod`](/reference/typescript-api/entities/shipping-method/)
- [`StockLocation`](/reference/typescript-api/entities/stock-location/)

## Channels & Sellers

Each channel is also assigned a single [`Seller`](/reference/typescript-api/entities/seller/). This entity is used to represent
the vendor or seller of the products in the channel. This is useful for implementing a marketplace, where each channel represents
a distinct vendor. The `Seller` entity can be extended with [custom fields](/guides/developer-guide/custom-fields/) to store additional information about the seller, such as a logo, contact details etc.

## Channels, Currencies & Prices

Each Channel has a set of `availableCurrencyCodes`, and one of these is designated as the `defaultCurrencyCode`, which sets the default currency for all monetary values in that channel.

![Default currencies](./default-currency.webp)

Internally, there is a one-to-many relation from [`ProductVariant`](/reference/typescript-api/entities/product-variant/) to [`ProductVariantPrice`](/reference/typescript-api/entities/product-variant-price). So the ProductVariant does _not_ hold a price for the product - this is actually stored on the `ProductVariantPrice` entity, and there will be at least one for each Channel to which the ProductVariant has been assigned.

![Product variant prices](./variant-prices.webp)

In this diagram we can see that every channel has at least 1 `ProductVariantPrice`. In the case of the UK Channel, there are 2 prices assigned - one for
GBP and one for USD. This means that you are able to define multiple prices in different currencies on a single product variant for a single channel.

:::info
**Note:** in the diagram above that the ProductVariant is **always assigned to the default Channel**, and thus will have a price in the default channel too. Likewise, the default Channel also has a defaultCurrencyCode. Depending on your requirements, you may or may not make use of the default Channel.
:::

### Keeping prices synchronized

When you have products assigned to multiple channels, updates to the price of a product in one channel will not automatically
be reflected in other channels. For instance, in the diagram above, both the Default channel and the UK channel have a price
in USD for the same product variant. 

If an administrator of the UK channel changes the USD price to $20, the price in the Default channel will remain at $30. This
is the default behavior, and is controlled by the [ProductVariantPriceUpdateStrategy](/reference/typescript-api/configuration/product-variant-price-update-strategy).

If you want to keep prices synchronized across all channels, you can set the `syncPricesAcrossChannels` property of the
[DefaultProductVariantPriceUpdateStrategy](/reference/typescript-api/configuration/product-variant-price-update-strategy#defaultproductvariantpriceupdatestrategy)
to `true`. This will ensure that when the price of a product variant is updated in one channel, the price in all other channels
(of that particular currency) will be updated to match.

```ts
import { DefaultProductVariantPriceUpdateStrategy, VendureConfig } from '@vendure/core';

export const config: VendureConfig = {
    // ...
    // highlight-start
    productVariantPriceUpdateStrategy: new DefaultProductVariantPriceUpdateStrategy({
        syncPricesAcrossChannels: true,
    }),
    // highlight-end
    // ...
};
```

You may however require even more sophisticated logic. For instance, you may want a one-way synchronization, where the price
in the Default channel is always the master price, and the prices in other channels are updated to match. In this case, you
can create a custom `ProductVariantPriceUpdateStrategy` which implements the desired logic.

## Use cases

### Single shop

This is the simplest set-up. You just use the default Channel for everything.

### Multiple separate shops

Let's say you are running multiple distinct businesses, each with its own distinct inventory and possibly different currencies. In this case, you set up a Channel for each shop and create the Product & Variants in the relevant shop's Channel.

The default Channel can then be used by the superadmin for administrative purposes, but other than that the default Channel would not be used. Storefronts would only target a specific shop's Channel.

### Multiple shops sharing inventory

Let's say you have a single inventory but want to split it between multiple shops. There might be overlap in the inventory, e.g. the US & EU shops share 80% of inventory, and then the rest is specific to either shop.

In this case, you can create the entire inventory in the default Channel and then assign the Products & ProductVariants to each Channel as needed, setting the price as appropriate for the currency used by each shop.

:::caution
**Note:** When creating a new Product & ProductVariants inside a sub-Channel, it will also **always get assigned to the default Channel**. If your sub-Channel uses a different currency from the default Channel, you should be aware that in the default Channel, that ProductVariant will be assigned the **same price** as it has in the sub-Channel. If the currency differs between the Channels, you need to make sure to set the correct price in the default Channel if you are exposing it to Customers via a storefront. 
:::

### Multi-vendor marketplace

This is the most advanced use of channels. For a detailed guide to this use-case, see our [Multi-vendor marketplace guide](/guides/how-to/multi-vendor-marketplaces/).


## Specifying channel in the GraphQL API

To specify which channel to use when making an API call, set the `'vendure-token'` header to match the token of the desired Channel.

For example, if we have a UK Channel with the token set to "uk-channel" as shown in this screenshot:

![UK Channel](./channel-token.webp)

Then we can make a GraphQL API call to the UK Channel by setting the `'vendure-token'` header to `'uk-channel'`:

```ts title="GraphQL API call to UK Channel"
const { loading, error, data } = useQuery(GET_PRODUCT_LIST, {
    context: {
        // highlight-start
        headers: {
            'vendure-token': 'uk-channel',
        },
        // highlight-end
    },
});
```

:::note
This is an example using Apollo Client in React. The same principle applies to any GraphQL client library - set the `'vendure-token'` header to the token of the desired Channel.
:::

With the above header set, the API call will be made to the UK Channel, and the response will contain only the entities which are assigned to that Channel.


---

---
title: 'Collections'
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

[`Collections`](/reference/typescript-api/entities/collection/) are used to categorize and organize your catalog. A collection
contains multiple product variants, and a product variant can belong to multiple collections. Collections can be nested to
create a hierarchy of categories, which is typically used to create a menu structure in the storefront.

![Collections](./collections.webp)

Collections are not _only_ used as the basis of storefront navigation. They are a general-purpose organization tool which can be used
for many purposes, such as:

- Creating a collection of "new arrivals" which is used on the homepage.
- Creating a collection of "best sellers" which is used to display a list of popular products.
- Creating a collection of "sale items" which is used to apply a discount to all products in the collection, via a promotion.

## Collection filters

The specific product variants that belong to a collection are determined by the collection's [`CollectionFilters`](/reference/typescript-api/configuration/collection-filter/).
A collection filter is a piece of logic which is used to determine whether a product variant should be included in the collection. By default, Vendure
includes a number of collection filters:

- **Filter by facet values**: Include all product variants which have a specific set of facet values.
- **Filter by product variant name**: Include all product variants whose name matches a specific string.
- **Manually select product variants**: Allows manual selection of individual product variants.
- **Manually select products**: Allows manual selection of entire products, and then includes all variants of those products.

![Collection filters](./collection-filters.webp)

It is also possible to create your own custom collection filters, which can be used to implement more complex logic. See the section on [creating a collection filter](#creating-a-collection-filter) for more details.

### Filter inheritance

When a collection is nested within another collection, the child collection can inherit the parent's collection filters. This means that the child collection
will _combine_ its own filters with the parent's filters.

![Filter inheritance](./filter-inheritance.webp)

In the example above, we have a parent collection "Menswear", with a child collection "Mens' Casual". The parent collection has a filter which includes all
product variants with the "clothing" and "mens" facet values. The child collection is set to inherit the parent's filters, and has an additional filter which
includes all product variants with the "casual" facet value.

Thus, the child collection will include all product variants which have the "clothing", "mens" and "casual" facet values.

:::note
When filter inheritance is enabled, a child collection will contain a **subset** of the product variants of its parent collection.

In order to create a child collection which contains product variants _not_ contained by the parent collection, you must disable filter inheritance
in the child collection.
:::

### Creating a collection filter

You can create your own custom collection filters with the [`CollectionFilter`](/reference/typescript-api/configuration/collection-filter/) class. This class
is a [configurable operation](/guides/developer-guide/strategies-configurable-operations/#configurable-operations) where the specific
filtering logic is implemented in the `apply()` method passed to its constructor.

The `apply()` method receives an instance of the [TypeORM SelectQueryBuilder](https://typeorm.io/select-query-builder) which should have filtering logic
added to it using the `.andWhere()` method.

Here's an example of a collection filter which filters by SKU:

```ts title="src/config/sku-collection-filter.ts"
import { CollectionFilter, LanguageCode } from '@vendure/core';

export const skuCollectionFilter = new CollectionFilter({
    args: {
        // The `args` object defines the user-configurable arguments
        // which will get passed to the filter's `apply()` function.
        sku: {
            type: 'string',
            label: [{ languageCode: LanguageCode.en, value: 'SKU' }],
            description: [
                {
                    languageCode: LanguageCode.en,
                    value: 'Matches any product variants with an SKU containing this value',
                },
            ],
        },
    },
    code: 'variant-sku-filter',
    description: [{ languageCode: LanguageCode.en, value: 'Filter by matching SKU' }],

    // This is the function that defines the logic of the filter.
    apply: (qb, args) => {
        // Sometimes syntax differs between database types, so we use
        // the `type` property of the connection options to determine
        // which syntax to use.
        const LIKE = qb.connection.options.type === 'postgres' ? 'ILIKE' : 'LIKE';

        return qb.andWhere(`productVariant.sku ${LIKE} :sku`, {
            sku: `%${args.sku}%`
        });
    },
});
```

In the `apply()` method, the product variant entity is aliased as `'productVariant'`.

This custom filter is then added to the defaults in your config:

```ts title="src/vendure-config.ts"
import { defaultCollectionFilters, VendureConfig } from '@vendure/core';
import { skuCollectionFilter } from './config/sku-collection-filter';

export const config: VendureConfig = {
    // ...
    catalogOptions: {
        collectionFilters: [
            ...defaultCollectionFilters,
            // highlight-next-line
            skuCollectionFilter
        ],
    },
};
```

:::info
To see some more advanced collection filter examples, you can look at the source code of the
[default collection filters](https://github.com/vendure-ecommerce/vendure/blob/master/packages/core/src/config/catalog/default-collection-filters.ts).
:::


---

---
title: "Customers"
---

A [`Customer`](/reference/typescript-api/entities/customer/) is a person who can buy from your shop. A customer can have one or more
[`Addresses`](/reference/typescript-api/entities/address/), which are used for shipping and billing.

If a customer has registered an account, they will have an associated [`User`](/reference/typescript-api/entities/user/). The user
entity is used for authentication and authorization. **Guest checkouts** are also possible, in which case a customer will not have a user.

:::info
See the [Auth guide](/guides/core-concepts/auth/#customer-auth) for a detailed explanation of the relationship between
customers and users.
:::

![Customer](./customer.webp)

Customers can be organized into [`CustomerGroups`](/reference/typescript-api/entities/customer-group/). These groups can be used in
logic relating to promotions, shipping rules, payment rules etc. For example, you could create a "VIP" customer group and then create
a promotion which grants members of this group free shipping. Or a "B2B" group which is used in a custom tax calculator to
apply a different tax rate to B2B customers.


---

---
title: "Email & Notifications"
---

A typical ecommerce application needs to notify customers of certain events, such as when they place an order or
when their order has been shipped. This is usually done via email, but can also be done via SMS or push notifications.

## Email

Email is the most common way to notify customers of events, so a default Vendure installation includes our [EmailPlugin](/reference/core-plugins/email-plugin).

The EmailPlugin by default uses [Nodemailer](https://nodemailer.com/about/) to send emails via a variety of
different transports, including SMTP, SendGrid, Mailgun, and more.
The plugin is configured with a list of [EmailEventHandlers](/reference/core-plugins/email-plugin/email-event-handler) which are responsible for
sending emails in response to specific events.

:::note
This guide will cover some of the main concepts of the EmailPlugin, but for a more in-depth look at how to configure
and use it, see the [EmailPlugin API docs](/reference/core-plugins/email-plugin).
:::

Here's an illustration of the flow of an email being sent:

![Email plugin flow](./email-plugin-flow.webp)

All emails are triggered by a particular [Event](/guides/developer-guide/events/) - in this case when the state of an
Order changes. The EmailPlugin ships with a set of [default email handlers](https://github.com/vendure-ecommerce/vendure/blob/master/packages/email-plugin/src/default-email-handlers.ts),
one of which is responsible for sending "order confirmation" emails.

### EmailEventHandlers

Let's take a closer look at a simplified version of the `orderConfirmationHandler`:

```ts
import { OrderStateTransitionEvent } from '@vendure/core';
import { EmailEventListener, transformOrderLineAssetUrls, hydrateShippingLines } from '@vendure/email-plugin';

// The 'order-confirmation' string is used by the EmailPlugin to identify
// which template to use when rendering the email.
export const orderConfirmationHandler = new EmailEventListener('order-confirmation')
    .on(OrderStateTransitionEvent)
    // Only send the email when the Order is transitioning to the
    // "PaymentSettled" state and the Order has a customer associated with it.
    .filter(
        event =>
            event.toState === 'PaymentSettled'
            && !!event.order.customer,
    )
    // We commonly need to load some additional data to be able to render the email
    // template. This is done via the `loadData()` method. In this method we are
    // mutating the Order object to ensure that product images are correctly
    // displayed in the email, as well as fetching shipping line data from the database.
    .loadData(async ({ event, injector }) => {
        transformOrderLineAssetUrls(event.ctx, event.order, injector);
        const shippingLines = await hydrateShippingLines(event.ctx, event.order, injector);
        return { shippingLines };
    })
    // Here we are setting the recipient of the email to be the
    // customer's email address.
    .setRecipient(event => event.order.customer!.emailAddress)
    // We can interpolate variables from the EmailPlugin's configured
    // `globalTemplateVars` object.
    .setFrom('{{ fromAddress }}')
    // We can also interpolate variables made available by the
    // `setTemplateVars()` method below
    .setSubject('Order confirmation for #{{ order.code }}')
    // The object returned here defines the variables which are
    // available to the email template.
    .setTemplateVars(event => ({ order: event.order, shippingLines: event.data.shippingLines }))
```

To recap:

- The handler listens for a specific event
- It optionally filters those events to determine whether an email should be sent
- It specifies the details of the email to be sent, including the recipient, subject, template variables, etc.

The full range of methods available when setting up an EmailEventHandler can be found in the [EmailEventHandler API docs](/reference/core-plugins/email-plugin/email-event-handler).

### Email variables

In the example above, we used the `setTemplateVars()` method to define the variables which are available to the email template.
Additionally, there are global variables which are made available to _all_ email templates & EmailEventHandlers. These are
defined in the `globalTemplateVars` property of the EmailPlugin config:

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';
import { EmailPlugin } from '@vendure/email-plugin';

export const config: VendureConfig = {
    // ...
    plugins: [
        EmailPlugin.init({
            // ...
            // highlight-start
            globalTemplateVars: {
                fromAddress: '"MyShop" <noreply@myshop.com>',
                verifyEmailAddressUrl: 'https://www.myshop.com/verify',
                passwordResetUrl: 'https://www.myshop.com/password-reset',
                changeEmailAddressUrl: 'https://www.myshop.com/verify-email-address-change'
            },
            // highlight-end
        }),
    ],
};
```

### Email integrations

The EmailPlugin is designed to be flexible enough to work with many different email services. The default
configuration uses Nodemailer to send emails via SMTP, but you can easily configure it to use a different
transport. For instance:

- [AWS SES](https://www.vendure.io/marketplace/aws-ses)
- [SendGrid](https://www.vendure.io/marketplace/sendgrid)

## Other notification methods

The pattern of listening for events and triggering some action in response is not limited to emails. You can
use the same pattern to trigger other actions, such as sending SMS messages or push notifications. For instance,
let's say you wanted to create a plugin which sends an SMS message to the customer when their order is shipped.

:::note
This is just a simplified example to illustrate the pattern.
:::

```ts title="src/plugins/sms-plugin/sms-plugin.ts"
import { OnModuleInit } from '@nestjs/common';
import { PluginCommonModule, VendurePlugin, EventBus } from '@vendure/core';
import { OrderStateTransitionEvent } from '@vendure/core';

// A custom service which sends SMS messages
// using a third-party SMS provider such as Twilio.
import { SmsService } from './sms.service';

@VendurePlugin({
    imports: [PluginCommonModule],
    providers: [SmsService],
})
export class SmsPlugin implements OnModuleInit {
    constructor(
        private eventBus: EventBus,
        private smsService: SmsService,
    ) {}

    onModuleInit() {
        this.eventBus
            .ofType(OrderStateTransitionEvent)
            .filter(event => event.toState === 'Shipped')
            .subscribe(event => {
                this.smsService.sendOrderShippedMessage(event.order);
            });
    }
}
```

---

---
title: "Images & Assets"
---

[`Assets`](/reference/typescript-api/entities/asset/) are used to store files such as images, videos, PDFs, etc. Assets can be
assigned to **products**, **variants** and **collections** by default. By using [custom fields](/guides/developer-guide/custom-fields/) it is
possible to assign assets to other entities. For example, for implementing customer profile images.

The handling of assets in Vendure is implemented in a modular way, allowing you full control over the way assets
are stored, named, imported and previewed.

![Asset creation and retrieval](./asset-flow.webp)

1. An asset is created by uploading an image. Internally the [`createAssets` mutation](/reference/graphql-api/admin/mutations/#createassets) will be executed.
2. The [`AssetNamingStrategy`](/reference/typescript-api/assets/asset-naming-strategy/) is used to generate file names for the source image and the preview. This is useful for normalizing file names as well as handling name conflicts.
3. The [`AssetPreviewStrategy`](/reference/typescript-api/assets/asset-preview-strategy) generates a preview image of the asset. For images, this typically involves creating a version with constraints on the maximum dimensions. It could also be used to e.g. generate a preview image for uploaded PDF files, videos or other non-image assets (such functionality would require a custom `AssetPreviewStrategy` to be defined).
4. The source file as well as the preview image are then passed to the [`AssetStorageStrategy`](/reference/typescript-api/assets/asset-storage-strategy) which stores the files to some form of storage. This could be the local disk or an object store such as AWS S3 or Minio.
5. When an asset is later read, e.g. when a customer views a product detail page which includes an image of the product, the `AssetStorageStrategy` can be used to
read the file from the storage location.


## AssetServerPlugin

Vendure comes with the `@vendure/asset-server-plugin` package pre-installed. This provides the [`AssetServerPlugin`](/reference/core-plugins/asset-server-plugin/) which provides many advanced features to make working with
assets easier.

The plugin provides a ready-made set of strategies for handling assets, but also allows you to replace these defaults with
your own implementations. For example, here are instructions on how to replace the default storage strategy with one
that stores your assets on AWS S3 or Minio: [configure S3 asset storage](/reference/core-plugins/asset-server-plugin/s3asset-storage-strategy#configures3assetstorage)

It also features a powerful image transformation API, which allows you to specify the dimensions, crop, and image format
using query parameters.

:::info
See the [AssetServerPlugin docs](/reference/core-plugins/asset-server-plugin/) for a detailed description of all the features.
:::

## Asset Tags

Assets can be tagged. A [`Tag`](/reference/typescript-api/entities/tag/) is a simple text label that can be applied to an asset. An asset can have multiple tags or none. Tags are useful for organizing assets, since assets are otherwise organized as a flat list with no concept of a directory structure.

![Asset tags](./asset-tags.webp)


---

---
title: "Money & Currency"
---

In Vendure, monetary values are stored as **integers** using the **minor unit** of the selected currency.
For example, if the currency is set to USD, then the integer value `100` would represent $1.00.
This is a common practice in financial applications, as it avoids the rounding errors that can occur when using floating-point numbers.

For example, here's the response from a query for a product's variant prices:



```json
{
  "data": {
    "product": {
      "id": "42",
      "variants": [
        {
          "id": "74",
          "name": "Bonsai Tree",
          "currencyCode": "USD",
          // highlight-start
          "price": 1999,
          "priceWithTax": 2399,
          // highlight-end
        }
      ]
    }
  }
}
```

In this example, the tax-inclusive price of the variant is `$23.99`.

:::info
To illustrate the problem with storing money as decimals, imagine that we want to add the price of two items:

- Product A: `$1.21`
- Product B: `$1.22`

We should expect the sum of these two amounts to equal `$2.43`. However, if we perform this addition in JavaScript (and the same
holds true for most common programming languages), we will instead get `$2.4299999999999997`!

For a more in-depth explanation of this issue, see [this StackOverflow answer](https://stackoverflow.com/a/3730040/772859)
:::

## Displaying monetary values

When you are building your storefront, or any other client that needs to display monetary values in a human-readable form,
you need to divide by 100 to convert to the major currency unit and then format with the correct decimal & grouping dividers.

In JavaScript environments such as browsers & Node.js, we can take advantage of the excellent [`Intl.NumberFormat` API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat).

Here's a function you can use in your projects:

```ts title="src/utils/format-currency.ts"
export function formatCurrency(value: number, currencyCode: string, locale?: string) {
    const majorUnits = value / 100;
    try {
        // Note: if no `locale` is provided, the browser's default
        // locale will be used.
        return new Intl.NumberFormat(locale, {
            style: 'currency',
            currency: currencyCode,
        }).format(majorUnits);
    } catch (e: any) {
        // A fallback in case the NumberFormat fails for any reason
        return majorUnits.toFixed(2);
    }
}
```

If you are building an Admin UI extension, you can use the built-in [`LocaleCurrencyPipe`](/reference/admin-ui-api/pipes/locale-currency-pipe/):

```html title="src/plugins/my-plugin/ui/components/my-component/my.component.html"
<div>
    Variant price: {{ variant.price | localeCurrency : variant.currencyCode }}
</div>
```

## Support for multiple currencies

Vendure supports multiple currencies out-of-the-box. The available currencies must first be set at the Channel level
(see the [Channels, Currencies & Prices section](/guides/core-concepts/channels/#channels-currencies--prices)), and then
a price may be set on a `ProductVariant` in each of the available currencies.

When using multiple currencies, the [ProductVariantPriceSelectionStrategy](/reference/typescript-api/configuration/product-variant-price-selection-strategy/)
is used to determine which of the available prices to return when fetching the details of a `ProductVariant`. The default strategy
is to return the price in the currency of the current session request context, which is determined firstly by any `?currencyCode=XXX` query parameter
on the request, and secondly by the `defaultCurrencyCode` of the Channel.

## The GraphQL `Money` scalar

In the GraphQL APIs, we use a custom [`Money` scalar type](/reference/graphql-api/admin/object-types/#money) to represent
all monetary values. We do this for two reasons:

1. The built-in `Int` type is that the GraphQL spec imposes an upper limit of
`2147483647`, which in some cases (especially currencies with very large amounts) is not enough.
2. Very advanced use-cases might demand more precision than is possible with an integer type. Using our own custom
scalar gives us the possibility of supporting more precision.

Here's how the `Money` scalar is used in the `ShippingLine` type:

```graphql
type ShippingLine {
    id: ID!
    shippingMethod: ShippingMethod!
    // highlight-start
    price: Money!
    priceWithTax: Money!
    discountedPrice: Money!
    discountedPriceWithTax: Money!
    // highlight-end
    discounts: [Discount!]!
}
```

If you are defining custom GraphQL types, or adding fields to existing types (see the [Extending the GraphQL API doc](/guides/developer-guide/extend-graphql-api/)),
then you should also use the `Money` scalar for any monetary values.


## The `@Money()` decorator

When [defining new database entities](/guides/developer-guide/database-entity), if you need to store a monetary value, then rather than using the TypeORM `@Column()`
decorator, you should use Vendure's [`@Money()` decorator](/reference/typescript-api/money/money-decorator).

Using this decorator allows Vendure to correctly store the value in the database according to the configured `MoneyStrategy` (see below).

```ts title="src/plugins/quote/entities/quote.entity.ts"
import { DeepPartial } from '@vendure/common/lib/shared-types';
import { VendureEntity, Order, EntityId, Money, CurrencyCode, ID } from '@vendure/core';
import { Column, Entity, ManyToOne } from 'typeorm';

@Entity()
class Quote extends VendureEntity {
    constructor(input?: DeepPartial<Quote>) {
        super(input);
    }

    @ManyToOne(type => Order)
    order: Order;

    @EntityId()
    orderId: ID;

    @Column()
    text: string;

    // highlight-start
    @Money()
    value: number;
    // highlight-end

    // Whenever you store a monetary value, it's a good idea to also
    // explicitly store the currency code too. This makes it possible
    // to support multiple currencies and correctly format the amount
    // when displaying the value.
    @Column('varchar')
    currencyCode: CurrencyCode;

    @Column()
    approved: boolean;
}
```

## Advanced configuration: MoneyStrategy

For advanced use-cases, it is possible to configure aspects of how Vendure handles monetary values internally by defining
a custom [`MoneyStrategy`](/reference/typescript-api/money/money-strategy/).

The `MoneyStrategy` allows you to define:

- How the value is stored and retrieved from the database
- How rounding is applied internally
- The precision represented by the monetary value (since v2.2.0)

For example, in addition to the [`DefaultMoneyStrategy`](/reference/typescript-api/money/default-money-strategy), Vendure
also provides the [`BigIntMoneyStrategy`](/reference/typescript-api/money/big-int-money-strategy) which stores monetary values
using the `bigint` data type, allowing much larger amounts to be stored.

Here's how you would configure your server to use this strategy:

```ts title="src/vendure-config.ts"
import { VendureConfig, BigIntMoneyStrategy } from '@vendure/core';

export const config: VendureConfig = {
    // ...
    entityOptions: {
        moneyStrategy: new BigIntMoneyStrategy(),
    }
}
```

### Example: supporting three decimal places

Let's say you have a B2B store which sells products in bulk, and you want to support prices with three decimal places.
For example, you want to be able to sell a product for `$1.234` per unit. To do this, you would need to:

1. Configure the `MoneyStrategy` to use three decimal places

```ts
import { DefaultMoneyStrategy, VendureConfig } from '@vendure/core';

export class ThreeDecimalPlacesMoneyStrategy extends DefaultMoneyStrategy {
    // highlight-next-line
    readonly precision = 3;
}

export const config: VendureConfig = {
    // ...
    entityOptions: {
        moneyStrategy: new ThreeDecimalPlacesMoneyStrategy(),
    }
};
```

2. Set up your storefront to correctly convert the integer value to a decimal value with three decimal places. Using the
`formatCurrency` example above, we can modify it to divide by 1000 instead of 100:

```ts title="src/utils/format-currency.ts"
export function formatCurrency(value: number, currencyCode: string, locale?: string) {
    // highlight-next-line
    const majorUnits = value / 1000;
    try {
        return new Intl.NumberFormat(locale, {
            style: 'currency',
            currency: currencyCode,
            // highlight-start
            minimumFractionDigits: 3,
            maximumFractionDigits: 3,
            // highlight-end
        }).format(majorUnits);
    } catch (e: any) {
         // highlight-next-line
        return majorUnits.toFixed(3);
    }
}
```


---

---
title: 'Orders'
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';


In Vendure, the [`Order`](/reference/typescript-api/entities/order/) entity represents the entire lifecycle of an order, from the moment a customer adds an item to their cart, through to the point where the order is completed and the customer has received their goods.

An [`Order`](/reference/typescript-api/entities/order/) is composed of one or more [`OrderLines`](/reference/typescript-api/entities/order-line/).
Each order line represents a single product variant, and contains information such as the quantity, price, tax rate, etc.

In turn, the order is associated with a [`Customer`](/reference/typescript-api/entities/customer/) and contains information such as
the shipping address, billing address, shipping method, payment method, etc.

![Order](./order.webp)


## The Order Process

Vendure defines an order process which is based on a [finite state machine](/reference/typescript-api/state-machine/fsm/) (a method of precisely controlling how the order moves from one state to another). This means that the [`Order.state` property](/reference/typescript-api/entities/order/#state) will be one of a set of [pre-defined states](/reference/typescript-api/orders/order-process/#orderstate). From the current state, the Order can then transition (change) to another state, and the available next states depend on what the current state is.

:::note
In Vendure, there is no distinction between a "cart" and an "order". The same entity is used for both. A "cart" is simply an order
which is still "active" according to its current state.
:::

You can see the current state of an order via `state` field on the `Order` type:

<Tabs>
<TabItem value="Request" label="Request" default>

```graphql title="Shop API"
query ActiveOrder {
    activeOrder {
        id
        // highlight-next-line
        state
    }
}
```

</TabItem>
<TabItem value="Response" label="Response">

```json
{
  "data": {
    "activeOrder": {
      "id": "4",
      // highlight-next-line
      "state": "AddingItems"
    }
  }
}
```

</TabItem>
</Tabs>

The next possible states can be queried via the [`nextOrderStates`](/reference/graphql-api/shop/queries/#nextorderstates) query:

<Tabs>
<TabItem value="Request" label="Request" default>

```graphql title="Shop API"
query NextStates {
  nextOrderStates
}
```

</TabItem>
<TabItem value="Response" label="Response">

```json
{
  "data": {
    "nextOrderStates": [
      "ArrangingPayment",
      "Cancelled"
    ]
  }
}
```

</TabItem>
</Tabs>



The available states and the permissible transitions between them are defined by the configured [`OrderProcess`](/reference/typescript-api/orders/order-process/). By default, Vendure defines a [`DefaultOrderProcess`](/reference/typescript-api/orders/order-process/#defaultorderprocess) which is suitable for typical B2C use-cases. Here's a simplified diagram of the default order process:

![Default order process](./order-process.webp)

Let's take a look at each of these states, and the transitions between them:

* **`AddingItems:`** All orders begin in the `AddingItems` state. This means that the customer is adding items to his or her shopping cart. This is the state an order would be in as long as the customer is still browsing the store.
* **`ArrangingPayment:`** From there, the Order can transition to the `ArrangingPayment`, which will prevent any further modifications to the order, which ensures the price that is sent to the payment provider is the same as the price that the customer saw when they added the items to their cart. At this point, the storefront will execute the [`addPaymentToOrder` mutation](/reference/graphql-api/shop/mutations/#addpaymenttoorder).
* **`PaymentAuthorized:`** Depending on the configured payment method, the order may then transition to the `PaymentAuthorized` state, which indicates that the payment has been successfully authorized by the payment provider. This is the state that the order will be in if the payment is not captured immediately. Once the payment is captured, the order will transition to the `PaymentSettled` state.
* **`PaymentSettled:`** If the payment captured immediately, the order will transition to the `PaymentSettled` state once the payment succeeds.
* At this point, one or more fulfillments can be created. A `Fulfillment` represents the process of shipping one or more items to the customer ("shipping" applies equally to physical or digital goods - it just means getting the product to the customer by any means). A fulfillment can be created via the [`addFulfillmentToOrder` mutation](/reference/graphql-api/admin/mutations/#addfulfillmenttoorder), or via the Admin UI. If multiple fulfillments are created, then the order can end up partial states - `PartiallyShipped` or `PartiallyDelivered`. If there is only a single fulfillment which includes the entire order, then partial states are not possible.
* **`Shipped:`** When all fulfillments have been shipped, the order will transition to the `Shipped` state. This means the goods have left the warehouse and are en route to the customer.
* **`Delivered:`** When all fulfillments have been delivered, the order will transition to the `Delivered` state. This means the goods have arrived at the customer's address. This is the final state of the order.

## Customizing the Default Order Process

It is possible to customize the [defaultOrderProcess](/reference/typescript-api/orders/order-process/#defaultorderprocess) to better match your business needs. For example, you might want to disable some of the constraints that are imposed by the default process, such as the requirement that a customer must have a shipping address before the Order can be completed.

This can be done by creating a custom version of the default process using the [configureDefaultOrderProcess](/reference/typescript-api/orders/order-process/#configuredefaultorderprocess) function, and then passing it to the [`OrderOptions.process`](/reference/typescript-api/orders/order-options/#process) config property.

```ts title="src/vendure-config.ts"
import { configureDefaultOrderProcess, VendureConfig } from '@vendure/core';

const myCustomOrderProcess = configureDefaultOrderProcess({
  // Disable the constraint that requires
  // Orders to have a shipping method assigned
  // before payment.
  arrangingPaymentRequiresShipping: false,
    
  // Other constraints which can be disabled. See the
  // DefaultOrderProcessOptions interface docs for full
  // explanations.
  //  
  // checkModificationPayments: false,
  // checkAdditionalPaymentsAmount: false,
  // checkAllVariantsExist: false,
  // arrangingPaymentRequiresContents: false,
  // arrangingPaymentRequiresCustomer: false,
  // arrangingPaymentRequiresStock: false,
  // checkPaymentsCoverTotal: false,
  // checkAllItemsBeforeCancel: false,
  // checkFulfillmentStates: false,
});

export const config: VendureConfig = {
  orderOptions: {
    process: [myCustomOrderProcess],
  },
};
```

## Custom Order Processes

Sometimes you might need to extend things beyond what is provided by the default Order process to better match your business needs. This is done by defining one or more [`OrderProcess`](/reference/typescript-api/orders/order-process#orderprocess) objects and passing them to the [`OrderOptions.process`](/reference/typescript-api/orders/order-options/#process) config property.

### Adding a new state

Let's say your company can only sell to customers with a valid EU tax ID. We'll assume that you've already used a [custom field](/guides/developer-guide/custom-fields/) to store that code on the Customer entity.

Now you want to add a step _before_ the customer handles payment, where we can collect and verify the tax ID.

So we want to change the default process of:

```text
AddingItems -> ArrangingPayment
```

to instead be:

```text
AddingItems -> ValidatingCustomer -> ArrangingPayment
```

Here's how we would define the new state:

```ts title="src/plugins/tax-id/customer-validation-process.ts"
import { OrderProcess } from '@vendure/core';

export const customerValidationProcess: OrderProcess<'ValidatingCustomer'> = {
  transitions: {
    AddingItems: {
      to: ['ValidatingCustomer'],
      mergeStrategy: 'replace',
    },
    ValidatingCustomer: {
      to: ['ArrangingPayment', 'AddingItems'],
    },
  },
};
```

This object means:

* the `AddingItems` state may _only_ transition to the `ValidatingCustomer` state (`mergeStrategy: 'replace'` tells Vendure to discard any existing transition targets and replace with this one). 
* the `ValidatingCustomer` may transition to the `ArrangingPayment` state (assuming the tax ID is valid) or back to the `AddingItems` state.

And then add this configuration to our main VendureConfig:

```ts title="src/vendure-config.ts"
import { defaultOrderProcess, VendureConfig } from '@vendure/core';
import { customerValidationProcess } from './plugins/tax-id/customer-validation-process';

export const config: VendureConfig = {
  // ...
  orderOptions: {
    process: [defaultOrderProcess, customerValidationProcess],
  },
};
```

Note that we also include the `defaultOrderProcess` in the array, otherwise we will lose all the default states and transitions.

To add multiple new States you need to extend the generic type like this:

 ```ts
import { OrderProcess } from '@vendure/core';

export const customerValidationProcess: OrderProcess<'ValidatingCustomer'|'AnotherState'> = {...}
 ```
This way multiple custom states get defined.

### Intercepting a state transition

Now we have defined our new `ValidatingCustomer` state, but there is as yet nothing to enforce that the tax ID is valid. To add this constraint, we'll use the [`onTransitionStart` state transition hook](/reference/typescript-api/state-machine/state-machine-config#ontransitionstart).

This allows us to perform our custom logic and potentially prevent the transition from occurring. We will also assume that we have a provider named `TaxIdService` available which contains the logic to validate a tax ID.

```ts title="src/plugins/tax-id/customer-validation-process.ts"
import { OrderProcess } from '@vendure/core';
import { TaxIdService } from './services/tax-id.service';

let taxIdService: TaxIdService;

const customerValidationProcess: OrderProcess<'ValidatingCustomer'> = {
  transitions: {
    AddingItems: {
      to: ['ValidatingCustomer'],
      mergeStrategy: 'replace',
    },
    ValidatingCustomer: {
      to: ['ArrangingPayment', 'AddingItems'],
    },
  },

  init(injector) {
    taxIdService = injector.get(TaxIdService);
  },

  // The logic for enforcing our validation goes here
  async onTransitionStart(fromState, toState, data) {
    if (fromState === 'ValidatingCustomer' && toState === 'ArrangingPayment') {
      const isValid = await taxIdService.verifyTaxId(data.order.customer);
      if (!isValid) {
        // Returning a string is interpreted as an error message.
        // The state transition will fail.
        return `The tax ID is not valid`;
      }
    }
  },
};
```

:::info
For an explanation of the `init()` method and `injector` argument, see the guide on [injecting dependencies in configurable operations](/guides/developer-guide/strategies-configurable-operations/#injecting-dependencies).
:::

### Responding to a state transition

Once an order has successfully transitioned to a new state, the [`onTransitionEnd` state transition hook](/reference/typescript-api/state-machine/state-machine-config#ontransitionend) is called. This can be used to perform some action
upon successful state transition.

In this example, we have a referral service which creates a new referral for a customer when they complete an order. We want to create the referral only if the customer has a referral code associated with their account.

```ts
import { OrderProcess, OrderState } from '@vendure/core';

import { ReferralService } from '../service/referral.service';

let referralService: ReferralService;

export const referralOrderProcess: OrderProcess<OrderState> = {
    init: (injector) => {
        referralService = injector.get(ReferralService);
    },
    onTransitionEnd: async (fromState, toState, data) => {
        const { order, ctx } = data;
        if (toState === 'PaymentSettled') {
            if (order.customFields.referralCode) {
                await referralService.createReferralForOrder(ctx, order);
            }
        }
    },
};
```

:::caution
Use caution when modifying an order inside the `onTransitionEnd` function. The `order` object that gets passed in to this function
will later be persisted to the database. Therefore any changes must be made to that `order` object, otherwise the changes might be lost.

As an example, let's say we want to add a Surcharge to the order. The following code **will not work as expected**:

```ts
export const myOrderProcess: OrderProcess<OrderState> = {
    async onTransitionEnd(fromState, toState, data) {
        if (fromState === 'AddingItems' && toState === 'ArrangingPayment') {
            // highlight-start
            // WARNING: This will not work!  
            await orderService.addSurchargeToOrder(ctx, order.id, {
                description: 'Test',
                listPrice: 42,
                listPriceIncludesTax: false,
            });
            // highlight-end
        }
    }
};
```

Instead, you need to ensure you **mutate the `order` object**:

```ts
export const myOrderProcess: OrderProcess<OrderState> = {
    async onTransitionEnd(fromState, toState, data) {
        if (fromState === 'AddingItems' && toState === 'ArrangingPayment') {
            // highlight-start
            const {surcharges} = await orderService.addSurchargeToOrder(ctx, order.id, {
                description: 'Test',
                listPrice: 42,
                listPriceIncludesTax: false,
            });
            // Important: mutate the order object
            order.surcharges = surcharges;
            // highlight-end
        }
    },
}
```


:::

## TypeScript Typings

To make your custom states compatible with standard services you should declare your new states in the following way:

```ts title="src/plugins/tax-id/types.ts"
import { CustomOrderStates } from '@vendure/core';

declare module '@vendure/core' {
  interface CustomOrderStates {
    ValidatingCustomer: never;
  }
}
```

This technique uses advanced TypeScript features - [declaration merging](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#merging-interfaces) and  [ambient modules](https://www.typescriptlang.org/docs/handbook/modules.html#ambient-modules).

## Controlling custom states in the Admin UI

If you have defined custom order states, the Admin UI will allow you to manually transition an 
order from one state to another:

![./custom-order-ui.webp](./custom-order-ui.webp)

## Order Interceptors

Vendure v3.1 introduces the concept of [Order Interceptors](/reference/typescript-api/orders/order-interceptor/). 
These are a way to intercept operations that add, modify or remove order lines. Examples use-cases include:

* Preventing certain products from being added to the order based on some criteria, e.g. if the  product is already in another active order.
* Enforcing a minimum or maximum quantity of a given product in the order
* Using a CAPTCHA to prevent automated order creation

Check the [Order Interceptor](/reference/typescript-api/orders/order-interceptor/) docs for more information as well as a complete
example of how to implement an interceptor.


---

---
title: 'Payment'
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Vendure can support many kinds of payment workflows, such as authorizing and capturing payment in a single step upon checkout or authorizing on checkout and then capturing on fulfillment.

:::info
For complete working examples of real payment integrations, see the [payments-plugins](https://github.com/vendure-ecommerce/vendure/tree/master/packages/payments-plugin/src)
:::

## Authorization & Settlement

Typically, there are 2 parts to an online payment: **authorization** and **settlement**:

-   **Authorization** is the process by which the customer's bank is contacted to check whether the transaction is allowed. At this stage, no funds are removed from the customer's account.
-   **Settlement** (also known as "capture") is the process by which the funds are transferred from the customer's account to the merchant.

Some merchants do both of these steps at once, when the customer checks out of the store. Others do the authorize step at checkout, and only do the settlement at some later point, e.g. upon shipping the goods to the customer.

This two-step workflow can also be applied to other non-card forms of payment: e.g. if providing a "payment on delivery" option, the authorization step would occur on checkout, and the settlement step would be triggered upon delivery, either manually by an administrator of via an app integration with the Admin API.

## Creating an integration

Payment integrations are created by defining a new [PaymentMethodHandler](/reference/typescript-api/payment/payment-method-handler/) and passing that handler into the [`paymentOptions.paymentMethodHandlers`](/reference/typescript-api/payment/payment-options#paymentmethodhandlers) array in the VendureConfig.

```ts title="src/plugins/payment-plugin/my-payment-handler.ts"
import {
    CancelPaymentResult,
    CancelPaymentErrorResult,
    PaymentMethodHandler,
    VendureConfig,
    CreatePaymentResult,
    SettlePaymentResult,
    SettlePaymentErrorResult
} from '@vendure/core';
import { sdk } from 'payment-provider-sdk';

/**
 * This is a handler which integrates Vendure with an imaginary
 * payment provider, who provide a Node SDK which we use to
 * interact with their APIs.
 */
const myPaymentHandler = new PaymentMethodHandler({
    code: 'my-payment-method',
    description: [{
        languageCode: LanguageCode.en,
        value: 'My Payment Provider',
    }],
    args: {
        apiKey: {type: 'string'},
    },

    /** This is called when the `addPaymentToOrder` mutation is executed */
    createPayment: async (ctx, order, amount, args, metadata): Promise<CreatePaymentResult> => {
        try {
            const result = await sdk.charges.create({
                amount,
                apiKey: args.apiKey,
                source: metadata.token,
            });
            return {
                amount: order.total,
                state: 'Authorized' as const,
                transactionId: result.id.toString(),
                metadata: {
                    cardInfo: result.cardInfo,
                    // Any metadata in the `public` field
                    // will be available in the Shop API,
                    // All other metadata is private and
                    // only available in the Admin API.
                    public: {
                        referenceCode: result.publicId,
                    }
                },
            };
        } catch (err) {
            return {
                amount: order.total,
                state: 'Declined' as const,
                metadata: {
                    errorMessage: err.message,
                },
            };
        }
    },

    /** This is called when the `settlePayment` mutation is executed */
    settlePayment: async (ctx, order, payment, args): Promise<SettlePaymentResult | SettlePaymentErrorResult> => {
        try {
            const result = await sdk.charges.capture({
                apiKey: args.apiKey,
                id: payment.transactionId,
            });
            return {success: true};
        } catch (err) {
            return {
                success: false,
                errorMessage: err.message,
            }
        }
    },

    /** This is called when a payment is cancelled. */
    cancelPayment: async (ctx, order, payment, args): Promise<CancelPaymentResult | CancelPaymentErrorResult> => {
        try {
            const result = await sdk.charges.cancel({
                apiKey: args.apiKey,
                id: payment.transactionId,
            });
            return {success: true};
        } catch (err) {
            return {
                success: false,
                errorMessage: err.message,
            }
        }
    },
});
```

We can now add this handler to our configuration:

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';
import { myPaymentHandler } from './plugins/payment-plugin/my-payment-handler';

export const config: VendureConfig = {
    // ...
    paymentOptions: {
        paymentMethodHandlers: [myPaymentHandler],
    },
};
```

:::info
If your PaymentMethodHandler needs access to the database or other providers, see the [configurable operation dependency injection guide](/guides/developer-guide/strategies-configurable-operations/#injecting-dependencies).
:::

## The PaymentMethod entity

Once the PaymentMethodHandler is defined as above, you can use it to create a new [`PaymentMethod`](/reference/typescript-api/entities/payment-method/) via the Admin UI (_Settings_ -> _Payment methods_, then _Create new payment method_) or via the Admin API `createPaymentMethod` mutation.

A payment method consists of an optional [`PaymentMethodEligibilityChecker`](/reference/typescript-api/payment/payment-method-eligibility-checker/), which is used to determine whether the payment method is available to the customer, and a [`PaymentMethodHandler`](/reference/typescript-api/payment/payment-method-handler).

The payment method also has a **code**, which is a string identifier used to specify this method when adding a payment to an order.

![Payment method](./payment-method.webp)

## Payment flow

### Eligible payment methods

Once the active Order has been transitioned to the `ArrangingPayment` state (see the [Order guide](/guides/core-concepts/orders/)), we can query the available payment methods by executing the [`eligiblePaymentMethods` query](/reference/graphql-api/shop/queries#eligiblepaymentmethods).

<Tabs>
<TabItem value="Request" label="Request" default>

```graphql title="Shop API"
query GetEligiblePaymentMethods {
    eligiblePaymentMethods {
        code
        name
        isEligible
        eligibilityMessage
    }
}
```

</TabItem>
<TabItem value="Response" label="Response">

```json
{
  "data": {
    "eligiblePaymentMethods": [
      {
        "code": "my-payment-method",
        "name": "My Payment Method",
        "isEligible": true,
        "eligibilityMessage": null
      }
    ]
  }
}
```

</TabItem>
</Tabs>


### Add payment to order

One or more Payments are created by executing the [`addPaymentToOrder` mutation](/reference/graphql-api/shop/mutations#addpaymenttoorder). This mutation has a required `method` input field, which _must_ match the `code` of an eligible `PaymentMethod`. In the case above, this would be set to `"my-payment-method"`.
 

<Tabs>
<TabItem value="Request" label="Request" default>

```graphql title="Shop API"
mutation {
    addPaymentToOrder(
        input: {
            method: "my-payment-method"
            metadata: { token: "<some token from the payment provider>" }
        }
    ) {
        ... on Order {
            id
            code
            state
            # ... etc
        }
        ... on ErrorResult {
            errorCode
            message
        }
        ...on PaymentFailedError {
            paymentErrorMessage
        }
        ...on PaymentDeclinedError {
            paymentErrorMessage
        }
        ...on IneligiblePaymentMethodError {
            eligibilityCheckerMessage
        }
    }
}

```

</TabItem>
<TabItem value="Response" label="Response">

```json
{
  "data": {
    "addPaymentToOrder": {
      "id": "12345",
      "code": "J9AC5PY13BQGRKTF",
      "state": "PaymentAuthorized"
    }
  }
}
```

</TabItem>
</Tabs>

:::info
The `metadata` field is used to store the specific data required by the payment provider. E.g. some providers have a client-side part which begins the transaction and returns a token which must then be verified on the server side.

The `metadata` field is required, so if your payment provider does not require any additional data, you can simply pass an empty object: `metadata: {}`.
:::

3. This mutation internally invokes the [PaymentMethodHandler's `createPayment()` function](/reference/typescript-api/payment/payment-method-config-options/#createpayment). This function returns a [CreatePaymentResult object](/reference/typescript-api/payment/payment-method-types#createpaymentfn) which is used to create a new [Payment](/reference/typescript-api/entities/payment). If the Payment amount equals the order total, then the Order is transitioned to either the `PaymentAuthorized` or `PaymentSettled` state and the customer checkout flow is complete.

### Single-step

If the `createPayment()` function returns a result with the state set to `'Settled'`, then this is a single-step ("authorize & capture") flow, as illustrated below:

![./payment_sequence_one_step.png](./payment_sequence_one_step.png)

### Two-step

If the `createPayment()` function returns a result with the state set to `'Authorized'`, then this is a two-step flow, and the settlement / capture part is performed at some later point, e.g. when shipping the goods, or on confirmation of payment-on-delivery.

![./payment_sequence_two_step.png](./payment_sequence_two_step.png)

## Custom Payment Flows

If you need to support an entirely different payment flow than the above, it is also possible to do so by configuring a [PaymentProcess](/reference/typescript-api/payment/payment-process). This allows new Payment states and transitions to be defined, as well as allowing custom logic to run on Payment state transitions.

Here's an example which adds a new "Validating" state to the Payment state machine, and combines it with a [OrderProcess](/reference/typescript-api/orders/order-process), [PaymentMethodHandler](/reference/typescript-api/payment/payment-method-handler) and [OrderPlacedStrategy](/reference/typescript-api/orders/order-placed-strategy).

```text
├── plugins
    └── my-payment-plugin
        ├── payment-process.ts
        ├── payment-method-handler.ts
        ├── order-process.ts
        └── order-placed-strategy.ts
```

```ts title="src/plugins/my-payment-plugin/payment-process.ts"
import { PaymentProcess } from '@vendure/core';

/**
 * Declare your custom state in special interface to make it type-safe
 */
declare module '@vendure/core' {
    interface PaymentStates {
        Validating: never;
    }
}

/**
 * Define a new "Validating" Payment state, and set up the
 * permitted transitions to/from it.
 */
const customPaymentProcess: PaymentProcess<'Validating'> = {
    transitions: {
        Created: {
            to: ['Validating'],
            mergeStrategy: 'replace',
        },
        Validating: {
            to: ['Settled', 'Declined', 'Cancelled'],
        },
    },
};
```

```ts title="src/plugins/my-payment-plugin/order-process.ts"
import { OrderProcess } from '@vendure/core';
/**
 * Define a new "ValidatingPayment" Order state, and set up the
 * permitted transitions to/from it.
 */
const customOrderProcess: OrderProcess<'ValidatingPayment'> = {
    transitions: {
        ArrangingPayment: {
            to: ['ValidatingPayment'],
            mergeStrategy: 'replace',
        },
        ValidatingPayment: {
            to: ['PaymentAuthorized', 'PaymentSettled', 'ArrangingAdditionalPayment'],
        },
    },
};
```

```ts title="src/plugins/my-payment-plugin/payment-method-handler.ts"
import { LanguageCode, PaymentMethodHandler } from '@vendure/core';

/**
 * This PaymentMethodHandler creates the Payment in the custom "Validating"
 * state.
 */
const myPaymentHandler = new PaymentMethodHandler({
    code: 'my-payment-handler',
    description: [{languageCode: LanguageCode.en, value: 'My payment handler'}],
    args: {},
    createPayment: (ctx, order, amount, args, metadata) => {
        // payment provider logic omitted
        return {
            state: 'Validating' as any,
            amount,
            metadata,
        };
    },
    settlePayment: (ctx, order, payment) => {
        return {
            success: true,
        };
    },
});
```

```ts title="src/plugins/my-payment-plugin/order-placed-strategy.ts"
import { OrderPlacedStrategy, OrderState, RequestContext } from '@vendure/core';

/**
 * This OrderPlacedStrategy tells Vendure to set the Order as "placed"
 * when it transitions to the custom "ValidatingPayment" state.
 */
class MyOrderPlacedStrategy implements OrderPlacedStrategy {
    shouldSetAsPlaced(ctx: RequestContext, fromState: OrderState, toState: OrderState): boolean | Promise<boolean> {
        return fromState === 'ArrangingPayment' && toState === ('ValidatingPayment' as any);
    }
}
```

```ts title="src/vendure-config.ts"
import { defaultOrderProcess, defaultPaymentProcess, VendureConfig } from '@vendure/core';
import { customOrderProcess } from './plugins/my-payment-plugin/order-process';
import { customPaymentProcess } from './plugins/my-payment-plugin/payment-process';
import { myPaymentHandler } from './plugins/my-payment-plugin/payment-method-handler';
import { MyOrderPlacedStrategy } from './plugins/my-payment-plugin/order-placed-strategy';

// Combine the above in the VendureConfig
export const config: VendureConfig = {
    // ...
    orderOptions: {
        process: [defaultOrderProcess, customOrderProcess],
        orderPlacedStrategy: new MyOrderPlacedStrategy(),
    },
    paymentOptions: {
        process: [defaultPaymentProcess, customPaymentProcess],
        paymentMethodHandlers: [myPaymentHandler],
    },
};
```

### Integration with hosted payment pages

A hosted payment page is a system that works similar to [Stripe checkout](https://stripe.com/payments/checkout). The idea behind this flow is that the customer does not enter any credit card data anywhere on the merchant's site which waives the merchant from the responsibility to take care of sensitive data.

The checkout flow works as follows:

1. The user makes a POST to the card processor's URL via a Vendure served page
2. The card processor accepts card information from the user and authorizes a payment
3. The card processor redirects the user back to Vendure via a POST which contains details about the processed payment
4. There is a pre-shared secret between the merchant and processor used to sign cross-site POST requests

When integrating with a system like this, you would need to create a Controller to accept POST redirects from the payment processor (usually a success and a failure URL), as well as serve a POST form on your store frontend.

With a hosted payment form the payment is already authorized by the time the card processor makes the POST request to Vendure, possibly settled even, so the payment handler won't do anything in particular - just return the data it has been passed. The validation of the POST request is done in the controller or service and the payment amount and payment reference are just passed to the payment handler which passes them on.


---

---
title: "Products"
---

Your catalog is composed of [`Products`](/reference/typescript-api/entities/product/) and [`ProductVariants`](/reference/typescript-api/entities/product-variant/).
A `Product` always has _at least one_ `ProductVariant`. You can think of the product as a "container" which includes a name, description, and images that apply to all of
its variants.

Here's a visual example, in which we have a "Hoodie" product which is available in 3 sizes. Therefore, we have
3 variants of that product:

![Products and ProductVariants](./products-variants.webp)

Multiple variants are made possible by adding one or more [`ProductOptionGroups`](/reference/typescript-api/entities/product-option-group) to
the product. These option groups then define the available [`ProductOptions`](/reference/typescript-api/entities/product-option)

If we were to add a new option group to the example above for "Color", with 2 options, "Black" and "White", then in total
we would be able to define up to 6 variants:

- Hoodie Small Black
- Hoodie Small White
- Hoodie Medium Black
- Hoodie Medium White
- Hoodie Large Black
- Hoodie Large White

:::info
When a customer adds a product to their cart, they are adding a specific `ProductVariant` to their cart, not the `Product` itself.
It is the `ProductVariant` that contains the SKU ("stock keeping unit", or product code) and price information.
:::

## Product price and stock

The `ProductVariant` entity contains the price and stock information for a product. Since a given product variant can have more
than one price, and more than one stock level (in the case of multiple warehouses), the `ProductVariant` entity contains
relations to one or more [`ProductVariantPrice`](/reference/typescript-api/entities/product-variant-price) entities and
one or more [`StockLevel`](/reference/typescript-api/entities/stock-level) entities.

![Price and stock](./product-relations.webp)

## Facets

[`Facets`](/reference/typescript-api/entities/facet/) are used to add structured labels to products and variants. A facet has
one or more [`FacetValues`](/reference/typescript-api/entities/facet-value/). Facet values can be assigned to products or
product variants.

For example, a "Brand" facet could be used to label products with the brand name, with each facet value representing a different brand. You can
also use facets to add other metadata to products and variants such as "New", "Sale", "Featured", etc.

![Facets and FacetValues](./facets.webp)

These are the typical uses of facets in Vendure:

- As the **basis of [Collections](/guides/core-concepts/collections)**, in order to categorize your catalog.
- To **filter products** in the storefront, also known as "faceted search". For example, a customer is on the "hoodies" collection
page and wants to filter to only show Nike hoodies.
- For **internal logic**, such as a promotion that applies to all variants with the "Summer Sale" facet value, or a shipping calculation
that applies a surcharge to all products with the "Fragile" facet value. Such facets can be set to be private so that they
are not exposed to the storefront.


---

---
title: 'Promotions'
---

Promotions are a means of offering discounts on an order based on various criteria. A Promotion consists of _conditions_ and _actions_.

- **conditions** are the rules which determine whether the Promotion should be applied to the order.
- **actions** specify exactly how this Promotion should modify the order.

## Parts of a Promotion

### Constraints

All Promotions can have the following constraints applied to them:

- **Date range** Using the "starts at" and "ends at" fields, the Promotion can be scheduled to only be active during the given date range.
- **Coupon code** A Promotion can require a coupon code first be activated using the [`applyCouponCode` mutation](/reference/graphql-api/shop/mutations/#applycouponcode) in the Shop API.
- **Per-customer limit** A Promotion coupon may be limited to a given number of uses per Customer.

### Conditions

A Promotion may be additionally constrained by one or more conditions. When evaluating whether a Promotion should be applied, each of the defined conditions is checked in turn. If all the conditions evaluate to `true`, then any defined actions are applied to the order.

Vendure comes with some built-in conditions, but you can also create your own conditions (see section below).

### Actions

A promotion action defines exactly how the order discount should be calculated. **At least one** action must be specified for a valid Promotion.

Vendure comes with some built-in actions, but you can also create your own actions (see section below).

## Creating custom conditions

To create a custom condition, you need to define a new [`PromotionCondition` object](/reference/typescript-api/promotions/promotion-condition/).
A promotion condition is an example of a [configurable operation](/guides/developer-guide/strategies-configurable-operations/#configurable-operations).
Here is an annotated example of one of the built-in PromotionConditions.

```ts
import { LanguageCode, PromotionCondition } from '@vendure/core';

export const minimumOrderAmount = new PromotionCondition({
    /** A unique identifier for the condition */
    code: 'minimum_order_amount',

    /**
     * A human-readable description. Values defined in the
     * `args` object can be interpolated using the curly-braces syntax.
     */
    description: [
        {languageCode: LanguageCode.en, value: 'If order total is greater than { amount }'},
    ],

    /**
     * Arguments which can be specified when configuring the condition
     * in the Admin UI. The values of these args are then available during
     * the execution of the `check` function.
     */
    args: {
        amount: {
            type: 'int',
            // The optional `ui` object allows you to customize
            // how this arg is rendered in the Admin UI.
            ui: {component: 'currency-form-input'},
        },
        taxInclusive: {type: 'boolean'},
    },

    /**
     * This is the business logic of the condition. It is a function that
     * must resolve to a boolean value indicating whether the condition has
     * been satisfied.
     */
    check(ctx, order, args) {
        if (args.taxInclusive) {
            return order.subTotalWithTax >= args.amount;
        } else {
            return order.subTotal >= args.amount;
        }
    },
});
```

Custom promotion conditions are then passed into the VendureConfig [PromotionOptions](/reference/typescript-api/promotions/promotion-options/) to make them available when setting up Promotions:

```ts title="src/vendure-config.ts"
import { defaultPromotionConditions, VendureConfig } from '@vendure/core';
import { minimumOrderAmount } from './minimum-order-amount';

export const config: VendureConfig = {
    // ...
    promotionOptions: {
        promotionConditions: [
            ...defaultPromotionConditions,
            minimumOrderAmount,
        ],
    }
}
```

## Creating custom actions

There are three kinds of PromotionAction:

- [`PromotionItemAction`](/reference/typescript-api/promotions/promotion-action#promotionitemaction) applies a discount on the `OrderLine` level, i.e. it would be used for a promotion like "50% off USB cables".
- [`PromotionOrderAction`](/reference/typescript-api/promotions/promotion-action#promotionorderaction) applies a discount on the `Order` level, i.e. it would be used for a promotion like "5% off the order total".
- [`PromotionShippingAction`](/reference/typescript-api/promotions/promotion-action#promotionshippingaction) applies a discount on the shipping, i.e. it would be used for a promotion like "free shipping".

The implementations of each type is similar, with the difference being the arguments passed to the `execute()`.

Here's an example of a simple PromotionOrderAction.

```ts
import { LanguageCode, PromotionOrderAction } from '@vendure/core';

export const orderPercentageDiscount = new PromotionOrderAction({
    // See the custom condition example above for explanations
    // of code, description & args fields.
    code: 'order_percentage_discount',
    description: [{languageCode: LanguageCode.en, value: 'Discount order by { discount }%'}],
    args: {
        discount: {
            type: 'int',
            ui: {
                component: 'number-form-input',
                suffix: '%',
            },
        },
    },

    /**
     * This is the function that defines the actual amount to be discounted.
     * It should return a negative number representing the discount in
     * pennies/cents etc. Rounding to an integer is handled automatically.
     */
    execute(ctx, order, args) {
        const orderTotal = ctx.channel.pricesIncludeTax ? order.subTotalWithTax : order.subTotal;
        return -orderTotal * (args.discount / 100);
    },
});
```

Custom PromotionActions are then passed into the VendureConfig [PromotionOptions](/reference/typescript-api/promotions/promotion-options) to make them available when setting up Promotions:

```ts title="src/vendure-config.ts"
import { defaultPromotionActions, VendureConfig } from '@vendure/core';
import { orderPercentageDiscount } from './order-percentage-discount';

export const config: VendureConfig = {
    // ...
    promotionOptions: {
        promotionActions: [
            ...defaultPromotionActions,
            orderPercentageDiscount,
        ],
    }
};
```

## Free gift promotions

Vendure v1.8 introduced a new **side effect API** to PromotionActions, which allow you to define some additional action to be performed when a Promotion becomes active or inactive.

A primary use-case of this API is to add a free gift to the Order. Here's an example of a plugin which implements a "free gift" action:

```ts title="src/plugins/free-gift/free-gift.plugin.ts"
import {
	ID, idsAreEqual, isGraphQlErrorResult, LanguageCode, Logger,
	OrderLine, OrderService, PromotionItemAction, VendurePlugin,
} from "@vendure/core";
import { createHash } from "crypto";

let orderService: OrderService;
export const freeGiftAction = new PromotionItemAction({
	code: "free_gift",
	description: [{ languageCode: LanguageCode.en, value: "Add free gifts to the order" }],
	args: {
		productVariantIds: {
			type: "ID",
			list: true,
			ui: { component: "product-selector-form-input" },
			label: [{ languageCode: LanguageCode.en, value: "Gift product variants" }],
		},
	},
	init(injector) {
		orderService = injector.get(OrderService);
	},
	execute(ctx, orderLine, args) {
		// This part is responsible for ensuring the variants marked as
		// "free gifts" have their price reduced to zero
		if (lineContainsIds(args.productVariantIds, orderLine)) {
			const unitPrice = orderLine.productVariant.listPriceIncludesTax
				? orderLine.unitPriceWithTax
				: orderLine.unitPrice;
			return -unitPrice;
		}
		return 0;
	},
	// The onActivate function is part of the side effect API, and
	// allows us to perform some action whenever a Promotion becomes active
	// due to it's conditions & constraints being satisfied.
	async onActivate(ctx, order, args, promotion) {
		for (const id of args.productVariantIds) {
			if (
				!order.lines.find(
					(line) =>
						idsAreEqual(line.productVariant.id, id) &&
						line.customFields.freeGiftPromotionId == null
				)
			) {
				// The order does not yet contain this free gift, so add it
				const result = await orderService.addItemToOrder(ctx, order.id, id, 1, {
					freeGiftPromotionId: promotion.id.toString(),
				});
				if (isGraphQlErrorResult(result)) {
					Logger.error(`Free gift action error for variantId "${id}": ${result.message}`);
				}
			}
		}
	},
	// The onDeactivate function is the other part of the side effect API and is called
	// when an active Promotion becomes no longer active. It should reverse any
	// side effect performed by the onActivate function.
	async onDeactivate(ctx, order, args, promotion) {
		const linesWithFreeGift = order.lines.filter(
			(line) => line.customFields.freeGiftPromotionId === promotion.id.toString()
		);
		for (const line of linesWithFreeGift) {
			await orderService.removeItemFromOrder(ctx, order.id, line.id);
		}
	},
});

function lineContainsIds(ids: ID[], line: OrderLine): boolean {
	return !!ids.find((id) => idsAreEqual(id, line.productVariant.id));
}

@VendurePlugin({
	configuration: (config) => {
		config.customFields.OrderLine.push({
			name: "freeGiftPromotionId",
			type: "string",
			public: true,
			readonly: true,
			nullable: true,
		});
		config.customFields.OrderLine.push({
			name: "freeGiftDescription",
			type: "string",
			public: true,
			readonly: true,
			nullable: true,
		});
		config.promotionOptions.promotionActions.push(freeGiftAction);
		return config;
	},
})
export class FreeGiftPromotionPlugin {}
```

## Dependency relationships

It is possible to establish dependency relationships between a PromotionAction and one or more PromotionConditions.

For example, if we want to set up a "buy 1, get 1 free" offer, we need to:

1. Establish whether the Order contains the particular ProductVariant under offer (done in the PromotionCondition)
2. Apply a discount to the qualifying OrderLine (done in the PromotionAction)

In this scenario, we would have to repeat the logic for checking the Order contents in _both_ the PromotionCondition _and_ the PromotionAction. Not only is this duplicated work for the server, it also means that setting up the promotion relies on the same parameters being input into the PromotionCondition and the PromotionAction.

Note the use of `PromotionItemAction` to get a reference to the `OrderLine` as opposed to the `Order`.

Instead, we can say that the PromotionAction _depends_ on the PromotionCondition:

```ts
export const buy1Get1FreeAction = new PromotionItemAction({
    code: 'buy_1_get_1_free',
    description: [{
        languageCode: LanguageCode.en,
        value: 'Buy 1, get 1 free',
    }],
    args: {},
    // highlight-next-line
    conditions: [buyXGetYFreeCondition],
    execute(ctx, orderLine, args, state) {
        // highlight-next-line
        const freeItemIds = state.buy_x_get_y_free.freeItemIds;
        if (idsContainsItem(freeItemIds, orderLine)) {
            const unitPrice = ctx.channel.pricesIncludeTax ? orderLine.unitPriceWithTax : orderLine.unitPrice;
            return -unitPrice;
        }
        return 0;
    },
});
```

In the above code, we are stating that this PromotionAction _depends_ on the `buyXGetYFreeCondition` PromotionCondition. Attempting to create a Promotion using the `buy1Get1FreeAction` without also using the `buyXGetYFreeCondition` will result in an error.

In turn, the `buyXGetYFreeCondition` can return a _state object_ with the type `{ [key: string]: any; }` instead of just a `true` boolean value. This state object is then passed to the PromotionConditions which depend on it, as part of the last argument (`state`).

```ts
export const buyXGetYFreeCondition = new PromotionCondition({
    code: 'buy_x_get_y_free',
    description: [{
        languageCode: LanguageCode.en,
        value: 'Buy { amountX } of { variantIdsX } products, get { amountY } of { variantIdsY } products free',
    }],
    args: {
        // omitted for brevity
    },
    async check(ctx, order, args) {
        // logic omitted for brevity
        if (freeItemIds.length === 0) {
            return false;
        }
        // highlight-next-line
        return {freeItemIds};
    },
});
```

## Injecting providers

If your PromotionCondition or PromotionAction needs access to the database or other providers, they can be injected by defining an `init()` function in your PromotionAction or PromotionCondition. See the [configurable operation guide](/guides/developer-guide/strategies-configurable-operations/#injecting-dependencies) for details.


---

---
title: "Shipping & Fulfillment"
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Shipping in Vendure is handled by [ShippingMethods](/reference/typescript-api/entities/shipping-method/). 
A ShippingMethod is composed of a **checker** and a **calculator**. 

* The [`ShippingEligibilityChecker`](/reference/typescript-api/shipping/shipping-eligibility-checker/) determines whether the order is eligible for the ShippingMethod. It can contain custom logic such as checking the total weight of the order, or whether the order is being shipped to a particular country.
* The [`ShippingCalculator`](/reference/typescript-api/shipping/shipping-calculator/) calculates the cost of shipping the order. The calculation can be performed directly by the calculator itself, or it could call out to a third-party API to determine the cost.

![Shipping method](./shipping-method.webp)

Multiple shipping methods can be set up and then your storefront can query [`eligibleShippingMethods`](/reference/graphql-api/shop/queries/#eligibleshippingmethods) to find out which ones can be applied to the active order.

When querying `eligibleShippingMethods`, each of the defined ShippingMethods' checker functions is executed to find out whether the order is eligible for that method, and if so, the calculator is executed to determine what the cost of shipping will be for that method.


<Tabs>
<TabItem value="Request" label="Request" default>

```graphql title="Shop API"
query GetEligibleShippingMethods {
    eligibleShippingMethods {
        id
        name
        price
        priceWithTax
    }
}
```

</TabItem>
<TabItem value="Response" label="Response">

```json
{
  "data": {
    "eligibleShippingMethods": [
      {
        "id": "1",
        "name": "Standard Shipping",
        "price": 500,
        "priceWithTax": 500
      },
      {
        "id": "2",
        "name": "Express Shipping",
        "price": 1000,
        "priceWithTax": 1000
      }
    ]
  }
}
```

</TabItem>
</Tabs>



## Creating a custom checker

Custom checkers can be created by defining a [`ShippingEligibilityChecker` object](/reference/typescript-api/shipping/shipping-eligibility-checker/).

For example, you could create a checker which works with a custom "weight" field to only apply to orders below a certain weight:

```ts title="src/shipping-methods/max-weight-checker.ts"
import { LanguageCode, ShippingEligibilityChecker } from '@vendure/core';

export const maxWeightChecker = new ShippingEligibilityChecker({
    code: 'max-weight-checker',
    description: [
        {languageCode: LanguageCode.en, value: 'Max Weight Checker'}
    ],
    args: {
        maxWeight: {
            type: 'int',
            ui: {component: 'number-form-input', suffix: 'grams'},
            label: [{languageCode: LanguageCode.en, value: 'Maximum order weight'}],
            description: [
                {
                    languageCode: LanguageCode.en,
                    value: 'Order is eligible only if its total weight is less than the specified value',
                },
            ],
        },
    },

    /**
     * Must resolve to a boolean value, where `true` means that the order is
     * eligible for this ShippingMethod.
     *
     * (This example assumes a custom field "weight" is defined on the
     * ProductVariant entity)
     */
    check: (ctx, order, args) => {
        const totalWeight = order.lines
            .map(l => l.productVariant.customFields.weight ?? 0 * l.quantity)
            .reduce((total, lineWeight) => total + lineWeight, 0);

        return totalWeight <= args.maxWeight;
    },
});
```

Custom checkers are then passed into the VendureConfig [ShippingOptions](/reference/typescript-api/shipping/shipping-options/#shippingeligibilitycheckers) to make them available when setting up new ShippingMethods:

```ts title="src/vendure-config.ts"
import { defaultShippingEligibilityChecker, VendureConfig } from '@vendure/core';
import { maxWeightChecker } from './shipping-methods/max-weight-checker';

export const config: VendureConfig = {
    // ...
    shippingOptions: {
        shippingEligibilityCheckers: [
            defaultShippingEligibilityChecker,
            maxWeightChecker,
        ],
    }
}
```

## Creating a custom calculator

Custom calculators can be created by defining a [`ShippingCalculator` object](/reference/typescript-api/shipping/shipping-calculator/).

For example, you could create a calculator which consults an external data source (e.g. a spreadsheet, database or 3rd-party API) to find out the cost and estimated delivery time for the order.

```ts title="src/shipping-methods/external-shipping-calculator.ts"
import { LanguageCode, ShippingCalculator } from '@vendure/core';
import { shippingDataSource } from './shipping-data-source';

export const externalShippingCalculator = new ShippingCalculator({
    code: 'external-shipping-calculator',
    description: [{languageCode: LanguageCode.en, value: 'Calculates cost from external source'}],
    args: {
        taxRate: {
            type: 'int',
            ui: {component: 'number-form-input', suffix: '%'},
            label: [{languageCode: LanguageCode.en, value: 'Tax rate'}],
        },
    },
    calculate: async (ctx, order, args) => {
        // `shippingDataSource` is assumed to fetch the data from some
        // external data source.
        const { rate, deliveryDate, courier } = await shippingDataSource.getRate({
            destination: order.shippingAddress,
            contents: order.lines,
        });

        return {
            price: rate,
            priceIncludesTax: ctx.channel.pricesIncludeTax,
            taxRate: args.taxRate,
            // metadata is optional but can be used to pass arbitrary
            // data about the shipping estimate to the storefront.
            metadata: { courier, deliveryDate },
        };
    },
});
```

Custom calculators are then passed into the VendureConfig [ShippingOptions](/reference/typescript-api/shipping/shipping-options/#shippingcalculators) to make them available when setting up new ShippingMethods:

```ts
import { defaultShippingCalculator, VendureConfig } from '@vendure/core';
import { externalShippingCalculator } from './external-shipping-calculator';

export const config: VendureConfig = {
  // ...
  shippingOptions: {
    shippingCalculators: [
      defaultShippingCalculator,
      externalShippingCalculator,
    ],
  }
}
```

:::info
If your ShippingEligibilityChecker or ShippingCalculator needs access to the database or other providers, see the [configurable operation dependency injection guide](/guides/developer-guide/strategies-configurable-operations/#injecting-dependencies).
:::

## Fulfillments

Fulfillments represent the actual shipping status of items in an order. When an order is placed and payment has been settled, the order items are then delivered to the customer in one or more Fulfillments.

* **Physical goods:** A fulfillment would represent the actual boxes or packages which are shipped to the customer. When the package leaves the warehouse, the fulfillment is marked as `Shipped`. When the package arrives with the customer, the fulfillment is marked as `Delivered`.
* **Digital goods:** A fulfillment would represent the means of delivering the digital goods to the customer, e.g. a download link or a license key. For example, when the link is sent to the customer, the fulfillment can be marked as `Shipped` and then `Delivered`.

### FulfillmentHandlers

It is often required to integrate your fulfillment process, e.g. with an external shipping API which provides shipping labels or tracking codes. This is done by defining [FulfillmentHandlers](/reference/typescript-api/fulfillment/fulfillment-handler/) (click the link for full documentation) and passing them in to the `shippingOptions.fulfillmentHandlers` array in your config.

By default, Vendure uses a manual fulfillment handler, which requires the Administrator to manually enter the method and tracking code of the Fulfillment.

### Fulfillment state machine

Like Orders, Fulfillments are governed by a [finite state machine](/reference/typescript-api/state-machine/fsm/) and by default, a Fulfillment can be in one of the [following states](/reference/typescript-api/fulfillment/fulfillment-state#fulfillmentstate):

* `Pending` The Fulfillment has been created
* `Shipped` The Fulfillment has been shipped
* `Delivered` The Fulfillment has arrived with the customer
* `Cancelled` The Fulfillment has been cancelled 

These states cover the typical workflow for fulfilling orders. However, it is possible to customize the fulfillment workflow by defining a [FulfillmentProcess](/reference/typescript-api/fulfillment/fulfillment-process) and passing it to your VendureConfig:

```ts title="src/vendure-config.ts"
import { FulfillmentProcess, VendureConfig } from '@vendure/core';
import { myCustomFulfillmentProcess } from './my-custom-fulfillment-process';

export const config: VendureConfig = {
  // ...
  shippingOptions: {
    process: [myCustomFulfillmentProcess],
  },
};
```

:::info
For a more detailed look at how custom processes are used, see the [custom order processes guide](/guides/core-concepts/orders/#custom-order-processes).
:::


---

---
title: "Stock Control"
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Vendure includes features to help manage your stock levels, stock allocations and back orders. The basic purpose is to help you keep track of how many of a given ProductVariant you have available to sell.

Stock control is enabled globally via the Global Settings:

![./global-stock-control.webp](./global-stock-control.webp)

It can be disabled if, for example, you manage your stock with a separate inventory management system and synchronize stock levels into Vendure automatically. The setting can also be overridden at the individual ProductVariant level.

## Stock Locations

Vendure uses the concept of [`StockLocations`](/reference/typescript-api/entities/stock-location/) to represent the physical locations where stock is stored. This could be a warehouse, a retail store, or any other location. If you do not have multiple stock locations, then you can simply use the default location which is created automatically.

![Stock levels](./stock-levels.webp)

### Selecting a stock location

When you have multiple stock locations set up, you need a way to determine which location to use when querying stock levels and when allocating stock to orders. This is handled by the [`StockLocationStrategy`](/reference/typescript-api/products-stock/stock-location-strategy/). This strategy exposes a number of methods which are used to determine which location (or locations) to use when:

- querying stock levels (`getAvailableStock`)
- allocating stock to orders (`forAllocation`)
- releasing stock from orders (`forRelease`)
- creating sales upon fulfillment (`forSale`)
- returning items to stock upon cancellation (`forCancellation`)

The default strategy is the [`DefaultStockLocationStrategy`](/reference/typescript-api/products-stock/default-stock-location-strategy), which simply uses the default location for all of the above methods. This is suitable for all cases where there is just a single stock location.

If you have multiple stock locations, you'll need to implement a custom strategy which uses custom logic to determine which stock location to use. For instance, you could:

- Use the location with the most stock available
- Use the location closest to the customer
- Use the location which has the cheapest shipping cost

### Displaying stock levels in the storefront

The [`StockDisplayStrategy`](/reference/typescript-api/products-stock/stock-display-strategy/) is used to determine how stock levels are displayed in the storefront. The default strategy is the [`DefaultStockDisplayStrategy`](/reference/typescript-api/products-stock/default-stock-display-strategy), which will only display one of three states: `'IN_STOCK'`, `'OUT_OF_STOCK'` or `'LOW_STOCK'`. This is to avoid exposing your exact stock levels to the public, which can sometimes be undesirable.

You can implement a custom strategy to display stock levels in a different way. Here's how you would implement a custom strategy to display exact stock levels:

```ts title="src/exact-stock-display-strategy.ts"
import { RequestContext, StockDisplayStrategy, ProductVariant } from '@vendure/core';

export class ExactStockDisplayStrategy implements StockDisplayStrategy {
    getStockLevel(ctx: RequestContext, productVariant: ProductVariant, saleableStockLevel: number): string {
        return saleableStockLevel.toString();
    }
}
```

This strategy is then used in your config:

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';
import { ExactStockDisplayStrategy } from './exact-stock-display-strategy';

export const config: VendureConfig = {
    // ...
    catalogOptions: {
        stockDisplayStrategy: new ExactStockDisplayStrategy(),
    },
};
```

## Stock Control Concepts

* **Stock on hand:** This refers to the number of physical units of a particular variant which you have in stock right now. This can be zero or more, but not negative.
* **Allocated:** This refers to the number of units which have been assigned to Orders, but which have not yet been fulfilled.
* **Out-of-stock threshold:** This value determines the stock level at which the variant is considered "out of stock". This value is set globally, but can be overridden for specific variants. It defaults to `0`.
* **Saleable:** This means the number of units that can be sold right now. The formula is:
    `saleable = stockOnHand - allocated - outOfStockThreshold`

Here's a table to better illustrate the relationship between these concepts:

Stock on hand | Allocated | Out-of-stock threshold | Saleable
--------------|-----------|------------------------|----------
10            | 0         | 0                      | 10
10            | 0         | 3                      | 7
10            | 5         | 0                      | 5
10            | 5         | 3                      | 2
10            | 10        | 0                      | 0
10            | 10        | -5                     | 5

The saleable value is what determines whether the customer is able to add a variant to an order. If there is 0 saleable stock, then any attempt to add to the order will result in an [`InsufficientStockError`](/reference/graphql-api/admin/object-types/#insufficientstockerror).


<Tabs>
<TabItem value="Request" label="Request" default>

```graphql title="Shop API"
query AddItemToOrder {
    addItemToOrder(productVariantId: 123, quantity: 150) {
        ...on Order {
            id
            code
            totalQuantity
        }
        ...on ErrorResult {
            errorCode
            message
        }
        ...on InsufficientStockError {
            errorCode
            message
            quantityAvailable
            order {
                id
                totalQuantity
            }
        }
    }
}
```

</TabItem>
<TabItem value="Response" label="Response">

```json
{
  "data": {
    "addItemToOrder": {
      "errorCode": "INSUFFICIENT_STOCK_ERROR",
      "message": "Only 105 items were added to the order due to insufficient stock",
      "quantityAvailable": 105,
      "order": {
        "id": "2",
        "totalQuantity": 106
      }
    }
  }
}
```

</TabItem>
</Tabs>

### Stock allocation

Allocation mean we are setting stock aside because it has been purchased but not yet shipped. It prevents us from selling more of a particular item than we are able to deliver. 

By default, stock gets allocated to an order once the order transitions to the `PaymentAuthorized` or `PaymentSettled` state. This is defined by the [`DefaultStockAllocationStrategy`](/reference/typescript-api/orders/default-stock-allocation-strategy). Using a custom [`StockAllocationStrategy`](/reference/typescript-api/orders/stock-allocation-strategy/) you can define your own rules for when stock is allocated.

With the [`defaultFulfillmentProcess`](/reference/typescript-api/fulfillment/fulfillment-process/#defaultfulfillmentprocess), allocated stock will be converted to **sales** and minused from the `stockOnHand` value when a Fulfillment is created.


### Back orders

You may have noticed that the `outOfStockThreshold` value can be set to a negative number. This allows you to sell variants even when you don't physically have them in stock. This is known as a "back order". 

Back orders can be really useful to allow orders to keep flowing even when stockOnHand temporarily drops to zero. For many businesses with predictable re-supply schedules they make a lot of sense.

Once a customer completes checkout, those variants in the order are marked as `allocated`. When a Fulfillment is created, those allocations are converted to Sales and the `stockOnHand` of each variant is adjusted. Fulfillments may only be created if there is sufficient stock on hand.

### Stock movements

There is a [`StockMovement`](/reference/typescript-api/entities/stock-movement/) entity which records the history of stock changes. `StockMovement` is actually an abstract class, with the following concrete implementations:

- [`Allocation`](/reference/typescript-api/entities/stock-movement/#allocation): When stock is allocated to an order, before the order is fulfilled. Adds stock to `allocated`, which reduces the saleable stock.
- [`Sale`](/reference/typescript-api/entities/stock-movement/#sale): When allocated stock gets fulfilled. Removes stock from `allocated` as well as `stockOnHand`.
- [`Cancellation`](/reference/typescript-api/entities/stock-movement/#cancellation): When items from a fulfilled order are cancelled, the stock is returned to `stockOnHand`. Adds stock to `stockOnHand`.
- [`Release`](/reference/typescript-api/entities/stock-movement/#release): When items which have been allocated (but not yet converted to sales via the creation of a Fulfillment) are cancelled. Removes stock from `allocated`.
- [`StockAdjustment`](/reference/typescript-api/entities/stock-movement/#stockadjustment): A general-purpose stock adjustment. Adds or removes stock from `stockOnHand`. Used when manually setting stock levels via the Admin UI, for example.

Stock movements can be queried via the `ProductVariant.stockMovements`. Here's an example where we query the stock levels and stock movements of a particular variant:


<Tabs>
<TabItem value="Request" label="Request" default>

```graphql title="Admin API"
query GetStockMovements {
    productVariant(id: 1) {
        id
        name
        stockLevels {
            stockLocation {
                name
            }
            stockOnHand
            stockAllocated
        }
        stockMovements {
            items {
                ...on StockMovement {
                    createdAt
                    type
                    quantity
                }
            }
        }
    }
}
```

</TabItem>
<TabItem value="Response" label="Response">

```json
{
  "data": {
    "productVariant": {
      "id": "1",
      "name": "Laptop 13 inch 8GB",
      "stockLevels": [
        {
          "stockLocation": {
            "name": "Default Stock Location"
          },
          "stockOnHand": 100,
          "stockAllocated": 0
        }
      ],
      "stockMovements": {
        "items": [
          {
            "createdAt": "2023-07-13T13:21:10.000Z",
            "type": "ADJUSTMENT",
            "quantity": 100
          }
        ]
      }
    }
  }
}
```

</TabItem>
</Tabs>


---

---
title: "Taxes"
showtoc: true
---

E-commerce applications need to correctly handle taxes such as sales tax or value added tax (VAT). In Vendure, tax handling consists of:

* **Tax categories** Each ProductVariant is assigned to a specific TaxCategory. In some tax systems, the tax rate differs depending on the type of good. For example, VAT in the UK has 3 rates, "standard" (most goods), "reduced" (e.g. child car seats) and "zero" (e.g. books).
* **Tax rates** This is the tax rate applied to a specific tax category for a specific [Zone](/reference/typescript-api/entities/zone/). E.g., the tax rate for "standard" goods in the UK Zone is 20%.
* **Channel tax settings** Each Channel can specify whether the prices of product variants are inclusive of tax or not, and also specify the default Zone to use for tax calculations.
* **TaxZoneStrategy** Determines the active tax Zone used when calculating what TaxRate to apply. By default, it uses the default tax Zone from the Channel settings.
* **TaxLineCalculationStrategy** This determines the taxes applied when adding an item to an Order. If you want to integrate a 3rd-party tax API or other async lookup, this is where it would be done.

## API conventions

In the GraphQL API, any type which has a taxable price will split that price into two fields: `price` and `priceWithTax`. This pattern also holds for other price fields, e.g.

```graphql
query {
  activeOrder {
    ...on Order {
      lines {
        linePrice
        linePriceWithTax
      }
      subTotal
      subTotalWithTax
      shipping
      shippingWithTax
      total
      totalWithTax
    }
  }
}
```

In your storefront, you can therefore choose whether to display the prices with or without tax, according to the laws and conventions of the area in which your business operates.

## Calculating tax on order lines

When a customer adds an item to the Order, the following logic takes place:

1. The price of the item, and whether that price is inclusive of tax, is determined according to the configured [OrderItemPriceCalculationStrategy](/reference/typescript-api/orders/order-item-price-calculation-strategy/).
2. The active tax Zone is determined based on the configured [TaxZoneStrategy](/reference/typescript-api/tax/tax-zone-strategy/). By default, Vendure will use the default tax Zone from the Channel settings.
  However, you often want to use the customer's address as the basis for determining the tax Zone. In this case, you should use the [AddressBasedTaxZoneStrategy](/reference/typescript-api/tax/address-based-tax-zone-strategy).
3. The applicable TaxRate is fetched based on the ProductVariant's TaxCategory and the active tax Zone determined in step 1.
4. The `TaxLineCalculationStrategy.calculate()` of the configured [TaxLineCalculationStrategy](/reference/typescript-api/tax/tax-line-calculation-strategy/) is called, which will return one or more [TaxLines](/reference/graphql-api/admin/object-types/#taxline).
5. The final `priceWithTax` of the order line is calculated based on all the above.

## Calculating tax on shipping

The taxes on shipping is calculated by the [ShippingCalculator](/reference/typescript-api/shipping/shipping-calculator/) of the Order's selected [ShippingMethod](/reference/typescript-api/entities/shipping-method/).

## Configuration

This example shows the default configuration for taxes (you don't need to specify this in your own config, as these are the defaults):

```ts title="src/vendure-config.ts"
import {
    DefaultTaxLineCalculationStrategy,
    DefaultTaxZoneStrategy,
    DefaultOrderItemPriceCalculationStrategy,
    VendureConfig
} from '@vendure/core';

export const config: VendureConfig = {
  taxOptions: {
    taxZoneStrategy: new DefaultTaxZoneStrategy(),
    taxLineCalculationStrategy: new DefaultTaxLineCalculationStrategy(),
  },
  orderOptions: {
    orderItemPriceCalculationStrategy: new DefaultOrderItemPriceCalculationStrategy()
  }
}

```


---

---
title: "Deploying to Digital Ocean"
---

![Deploy to Digital Ocean App Platform](./deploy-to-do-app-platform.webp)

[App Platform](https://www.digitalocean.com/products/app-platform) is a fully managed platform which allows you to deploy and scale your Vendure server and infrastructure with ease.

:::note
The configuration in this guide will cost around $22 per month to run.
:::

## Prerequisites

First of all you'll need to [create a new Digital Ocean account](https://cloud.digitalocean.com/registrations/new) if you
don't already have one.

For this guide you'll need to have your Vendure project in a git repo on either GitHub or GitLab. App Platform also supports
deploying from docker registries, but that is out of the scope of this guide.

:::info
If you'd like to quickly get started with a ready-made Vendure project which includes sample data, you can clone our
[Vendure one-click-deploy repo](https://github.com/vendure-ecommerce/one-click-deploy).
:::

## Configuration

### Database connection

:::info
The following is already pre-configured if you are using the one-click-deploy repo.
:::

Make sure your DB connection options uses the following environment variables:

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';

export const config: VendureConfig = {
    // ...
    dbConnectionOptions: {
        // ...
        type: 'postgres',
        database: process.env.DB_NAME,
        host: process.env.DB_HOST,
        port: +process.env.DB_PORT,
        username: process.env.DB_USERNAME,
        password: process.env.DB_PASSWORD,
        ssl: process.env.DB_CA_CERT ? {
            ca: process.env.DB_CA_CERT,
        } : undefined,
    },
};
```
### Asset storage

:::info
The following is already pre-configured if you are using the one-click-deploy repo.
:::

Since App Platform services do not include any persistent storage, we need to configure Vendure to use Digital Ocean's
Spaces service, which is an S3-compatible object storage service. This means you'll need to make sure to have the
following packages installed:

```
npm install @aws-sdk/client-s3 @aws-sdk/lib-storage
```


and set up your AssetServerPlugin like this:

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';
import { AssetServerPlugin, configureS3AssetStorage } from '@vendure/asset-server-plugin';

export const config: VendureConfig = {
    // ...
    plugins: [
        AssetServerPlugin.init({
            route: 'assets',
            assetUploadDir: process.env.ASSET_UPLOAD_DIR || path.join(__dirname, '../static/assets'),
            // highlight-start
            // If the MINIO_ENDPOINT environment variable is set, we'll use
            // Minio as the asset storage provider. Otherwise, we'll use the
            // default local provider.
            storageStrategyFactory: process.env.MINIO_ENDPOINT ?  configureS3AssetStorage({
                bucket: 'vendure-assets',
                credentials: {
                    accessKeyId: process.env.MINIO_ACCESS_KEY,
                    secretAccessKey: process.env.MINIO_SECRET_KEY,
                },
                nativeS3Configuration: {
                    endpoint: process.env.MINIO_ENDPOINT,
                    forcePathStyle: true,
                    signatureVersion: 'v4',
                    // The `region` is required by the AWS SDK even when using MinIO,
                    // so we just use a dummy value here.
                    region: 'eu-west-1',
                },
            }) : undefined,
            // highlight-end
        }),
    ],
    // ...
};
```

## Create Spaces Object Storage

First we'll create a Spaces bucket to store our assets. Click the "Spaces Object Storage" nav item and
create a new space and call it "vendure-assets".

![Create Spaces Object Storage](./01-create-space.webp)

Next we need to create an access key and secret. Click the "API" nav item and generate a new key.

![Create API key](./02-space-access-keys.webp)

Name the key something meaningful like "vendure-assets-key" and then **make sure to copy the secret as it will only be
shown once**. Store the access key and secret key in a safe place for later - we'll be using it when we set up our 
app's environment variables.

:::caution
If you forget to copy the secret key, you'll need to delete the key and create a new one.
:::

## Create the server resource

Now we're ready to create our app infrastructure! Click the "Create" button in the top bar and select "Apps".

![Create App](./03-create-app.webp)

Now connect to your git repo, and select the repo of your Vendure project.

Depending on your repo, App Platform may suggest more than one app: in this screenshot we are using the one-click-deploy
repo which contains a Dockerfile, so App Platform is suggesting two different ways to deploy the app. We'll select the
Dockerfile option, but either option should work fine. Delete the unused resource.

We need to edit the details of the server app. Click the "Edit" button and set the following:

* **Resource Name**: "vendure-server"
* **Resource Type**: Web Service
* **Run Command**: `node ./dist/index.js`
* **HTTP Port**: 3000

At this point you can also click the "Edit Plan" button to select the resource allocation for the server, which will
determine performance and price. For testing purposes the smallest Basic server (512MB, 1vCPU) is fine. This can also be changed later.

### Add a database 

Next click "Add Resource", select **Database** and click "Add", and then accept the default Postgres database. Click the
"Create and Attach" to create the database and attach it to the server app.

Your config should now look like this:

![App setup](./04-configure-server.webp)

## Set up environment variables

Next we need to set up the environment variables. Since these will be shared by both the server and worker apps, we'll create
them at the Global level. 

You can use the "bulk editor" to paste in the following variables (making sure to replace the values in `<angle brackets>` with
your own values):

```sh
DB_NAME=${db.DATABASE}
DB_USERNAME=${db.USERNAME}
DB_PASSWORD=${db.PASSWORD}
DB_HOST=${db.HOSTNAME}
DB_PORT=${db.PORT}
DB_CA_CERT=${db.CA_CERT}
// highlight-next-line
COOKIE_SECRET=<add some random characters>
SUPERADMIN_USERNAME=superadmin
// highlight-next-line
SUPERADMIN_PASSWORD=<create some strong password>
// highlight-start
MINIO_ACCESS_KEY=<use the key generated earlier>
MINIO_SECRET_KEY=<use the secret generated earlier>
MINIO_ENDPOINT=<use the endpoint of your spaces bucket>
// highlight-end
```

:::note
The values starting with `${db...}` are automatically populated by App Platform and should not be changed, unless you chose
to name your database something other than `db`.
:::

:::note
When using the App Platform with a Dev Database, DigitalOcean only provides a self-signed SSL certificate. This may prevent the Vendure app from starting. As a workaround, you can add the environment variable `NODE_TLS_REJECT_UNAUTHORIZED` and set it to `0`.
:::

After saving your environment variables you can click through the confirmation screens to create the app.

## Create the worker resource

Now we need to set up the [Vendure worker](/guides/developer-guide/worker-job-queue/) which will handle background tasks. From the dashboard of your newly-created
app, click the "Create" button and then select "Create Resources From Source Code".

You will be prompted to select the repo again, and then you'll need to set up a new single resource with the following 
settings:

* **Resource Name**: "vendure-worker"
* **Resource Type**: Worker
* **Run Command**: `node ./dist/index-worker.js`

Again you can edit the plan, and the smallest Basic plan is fine for testing purposes.

No new environment variables are needed since we'll be sharing the Global variables with the worker.

## Enable access to the required routes

To be able to access the UI and other routes, we need to declare them first.

1. In the app dashboard, click on the **Settings** tab.
2. Click on the **vendure-server** component.

   ![Open server settings](./05-open-server-settings.webp)

3. Scroll down to **HTTP Request Routes**.
4. Click on **Edit**.
5. Click on **+ Add new route** and fill in the form like this:

   ![Admin app route](./06-admin-app-route.webp)

6. Make sure to check the **Preserve Path Prefix** option.

You need to do this for the following routes:
- `/admin`
- `/assets`
- `/health`
- `/admin-api`
- `/shop-api`

7. Click on **Save**.

## Test your Vendure server

Once everything has finished deploying, you can click the app URL to open your Vendure server in a new tab. 

![Open app](./07-open-app.webp)

:::info
Append `/admin` to the URL to access the admin UI, and log in with the superadmin credentials you set in the environment variables.
:::


---

---
title: "Deploying to Google Cloud Run"
images: 
    - "/docs/deployment/deploy-to-google-cloud-run/deploy-to-gcr.webp"
---

![./deploy-to-gcr.webp](./deploy-to-gcr.webp)

[Google Cloud Run](https://cloud.google.com/run) is a fully managed platform which allows you to run containerized apps and only pay while your app code is actually running.

This guide was written by Martijn from [Pinelab](https://pinelab.studio/), who have been successfully running multiple Vendure projects on Google Cloud Run. The step by step commands can be found here on GitHub: 
- https://github.com/Pinelab-studio/vendure-google-cloud-run-starter/blob/main/README.md.

## Prerequisites
This guide assumes you have:

* Google cloud's `gcloud` cli installed locally
* Created a Google Cloud project and enabled the API's we need: https://github.com/Pinelab-studio/vendure-google-cloud-run-starter/blob/main/README.md#create-a-google-cloud-project 

## Setting up a MySQL database with Google Cloud SQL
Google Cloud SQL is a fully-managed relational database service that makes it easy to set up, maintain, and manage databases in the cloud. 
Vendure requires an SQL database to store its data, and Google Cloud SQL is a great option for this because it provides a reliable, scalable, and secure way to host our database.

You can find the `gcloud` commands to create a MySQL database here: https://github.com/Pinelab-studio/vendure-google-cloud-run-starter/blob/main/README.md#create-a-mysql-database

## Google Cloud Storage for assets
Vendure stores assets such as product images on file system by default. However, Google Cloud Run does not have internal file storage, so we need to use an external storage service. 
Google Cloud Storage is a great option for this because it provides a scalable and reliable way to store our assets in the cloud.

Use these `gcloud` [commands](https://github.com/Pinelab-studio/vendure-google-cloud-run-starter/blob/main/README.md#asset-storage) to create a storage bucket for our assets.

## Google Cloud Tasks for Vendure's worker
Vendure uses a worker process to perform asynchronous tasks such as sending emails. To communicate between the main application and the worker process, we need a message queue. Google Cloud Tasks is a great option for this because it provides a fully-managed, scalable, and reliable way to send and receive messages between applications.

You don't need to do anything to enable Cloud Tasks: [this plugin](https://github.com/Pinelab-studio/vendure-google-cloud-run-starter/blob/8fd342c15fa7b38e3662311f176901a5d38cde3d/src/vendure-config.ts#L88) automatically creates task queues for you.

## Running locally
Let's test out our application locally before deploying to Cloud Run. Copy [this](https://github.com/Pinelab-studio/vendure-google-cloud-run-starter/blob/main/.env.example) `.env.example` to `.env` and fill in your variables. You can skip the `WORKER_HOST` variable, because we don't have it yet.

## Dockerize Vendure
Google Cloud Run allows us to deploy containerized applications without worrying about the underlying infrastructure. To deploy Vendure to Google Cloud Run, we need to Dockerize it. Dockerizing Vendure means packaging the application and its dependencies into a container that can be easily deployed to Google Cloud Run.

The setup for containerizing Vendure is already done: [This file](https://github.com/Pinelab-studio/vendure-google-cloud-run-starter/blob/main/Dockerfile) and [this file](https://github.com/Pinelab-studio/vendure-google-cloud-run-starter/blob/main/build-docker.sh) will build your container.

## Deployment
The example repository contains GitHub action definitions to automatically deploy your app to Cloud Run when you push to the `main` branch.

Follow [these steps](https://github.com/Pinelab-studio/vendure-google-cloud-run-starter/blob/main/build-docker.sh) to create a service account and set your variables as repository secret in GitHub.

## Keep alive
As final improvement, you can use Google Cloud Scheduler to poll your Cloud Run instance to prevent cold starts with [this command](https://github.com/Pinelab-studio/vendure-google-cloud-run-starter/blob/main/build-docker.sh).

That's it! Feel free to reach out for any questions, or create a [Pull Request in the repository](https://github.com/Pinelab-studio/vendure-google-cloud-run-starter/pulls) if you have any improvements.


---

---
title: "Deploying to Northflank"
showtoc: true
images: 
  - "/docs/deployment/deploy-to-northflank/deploy-to-northflank.webp"
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

![./deploy-to-northflank.webp](./deploy-to-northflank.webp)

[Northflank](https://northflank.com) is a comprehensive developer platform to build and scale your apps. It has an outstanding developer experience and has a free tier for small projects, and is well-suited for deploying and scaling Vendure applications.

This guide will walk you through the steps to deploy [a sample Vendure application](https://github.com/vendure-ecommerce/one-click-deploy) to Northflank.

## Set up a Northflank account

Go to the Northflank [sign up page](https://app.northflank.com/signup) to create a new account. As part of the sign-up you'll be asked for credit card details, but you won't be charged unless you upgrade to a paid plan.

## Create a custom template

A template defines the infrastructure that is needed to run your Vendure server. Namely, a **server**, a **worker**, 
**MinIO object storage** for assets and a **Postgres database**.

Click the templates menu item in the navbar and click the "Create template" button.

![./01-create-template-screen.webp](./01-create-template-screen.webp)

Now paste the following configuration into the editor in the "code" tab:

![./02-paste-config.webp](./02-paste-config.webp)

<Tabs>
<TabItem label="Full Template" value="Full Template">

:::note
This template configures a production-like setup for Vendure, with the server and worker running in separate processes
and a separate MinIO instance for asset storage.

The resources configured here will cost around $20 per month.

If you want to use the free plan, use the "Lite Template".
:::

<div class="limited-height-code-block">

```json
{
  "apiVersion": "v1.2",
  "spec": {
    "kind": "Workflow",
    "spec": {
      "type": "sequential",
      "steps": [
        {
          "kind": "Project",
          "ref": "project",
          "spec": {
            "name": "Vendure",
            "region": "europe-west",
            "description": "Vendure is a modern, open-source composable commerce platform",
            "color": "#17b9ff"
          }
        },
        {
          "kind": "Workflow",
          "spec": {
            "type": "parallel",
            "context": {
              "projectId": "${refs.project.id}"
            },
            "steps": [
              {
                "kind": "Addon",
                "ref": "database",
                "spec": {
                  "name": "database",
                  "type": "postgres",
                  "version": "14-latest",
                  "billing": {
                    "deploymentPlan": "nf-compute-20",
                    "storageClass": "ssd",
                    "storage": 4096,
                    "replicas": 1
                  },
                  "tlsEnabled": false,
                  "externalAccessEnabled": false,
                  "ipPolicies": [],
                  "pitrEnabled": false
                }
              },
              {
                "kind": "Addon",
                "ref": "storage",
                "spec": {
                  "name": "minio",
                  "type": "minio",
                  "version": "latest",
                  "billing": {
                    "deploymentPlan": "nf-compute-20",
                    "storageClass": "ssd",
                    "storage": 4096,
                    "replicas": 1
                  },
                  "tlsEnabled": true,
                  "externalAccessEnabled": false,
                  "ipPolicies": [],
                  "pitrEnabled": false,
                  "typeSpecificSettings": {},
                  "backupSchedules": []
                }
              }
            ]
          }
        },
        {
          "kind": "SecretGroup",
          "spec": {
            "projectId": "${refs.project.id}",
            "secretType": "environment-arguments",
            "priority": 10,
            "name": "secrets",
            "secrets": {
              "variables": {
                "APP_ENV": "production",
                "COOKIE_SECRET": "${fn.randomSecret(32)}",
                "SUPERADMIN_USERNAME": "superadmin",
                "SUPERADMIN_PASSWORD": "${fn.randomSecret(16)}",
                "DB_SCHEMA": "public"
              },
              "files": {}
            },
            "addonDependencies": [
              {
                "addonId": "${refs.database.id}",
                "keys": [
                  {
                    "keyName": "HOST",
                    "aliases": [
                      "DB_HOST"
                    ]
                  },
                  {
                    "keyName": "PORT",
                    "aliases": [
                      "DB_PORT"
                    ]
                  },
                  {
                    "keyName": "DATABASE",
                    "aliases": [
                      "DB_NAME"
                    ]
                  },
                  {
                    "keyName": "USERNAME",
                    "aliases": [
                      "DB_USERNAME"
                    ]
                  },
                  {
                    "keyName": "PASSWORD",
                    "aliases": [
                      "DB_PASSWORD"
                    ]
                  }
                ]
              },
              {
                "addonId": "${refs.storage.id}",
                "keys": [
                  {
                    "keyName": "MINIO_ENDPOINT",
                    "aliases": [
                      "MINIO_ENDPOINT"
                    ]
                  },
                  {
                    "keyName": "ACCESS_KEY",
                    "aliases": [
                      "MINIO_ACCESS_KEY"
                    ]
                  },
                  {
                    "keyName": "SECRET_KEY",
                    "aliases": [
                      "MINIO_SECRET_KEY"
                    ]
                  }
                ]
              }
            ],
            "restrictions": {
              "restricted": false,
              "nfObjects": [],
              "tags": []
            }
          }
        },
        {
          "kind": "BuildService",
          "ref": "builder",
          "spec": {
            "name": "builder",
            "projectId": "${refs.project.id}",
            "billing": {
              "deploymentPlan": "nf-compute-20"
            },
            "vcsData": {
              "projectUrl": "https://github.com/vendure-ecommerce/one-click-deploy",
              "projectType": "github"
            },
            "buildSettings": {
              "dockerfile": {
                "buildEngine": "kaniko",
                "dockerFilePath": "/Dockerfile",
                "dockerWorkDir": "/",
                "useCache": false
              }
            },
            "disabledCI": false,
            "buildArguments": {}
          }
        },
        {
          "kind": "Build",
          "spec": {
            "id": "${refs.builder.id}",
            "projectId": "${refs.project.id}",
            "type": "service",
            "branch": "master",
            "buildOverrides": {
              "buildArguments": {}
            },
            "reuseExistingBuilds": true
          },
          "condition": "success",
          "ref": "build"
        },
        {
          "kind": "Workflow",
          "spec": {
            "type": "parallel",
            "context": {
              "projectId": "${refs.project.id}"
            },
            "steps": [
              {
                "kind": "DeploymentService",
                "spec": {
                  "deployment": {
                    "instances": 1,
                    "storage": {
                      "ephemeralStorage": {
                        "storageSize": 1024
                      },
                      "shmSize": 64
                    },
                    "docker": {
                      "configType": "customCommand",
                      "customCommand": "node ./dist/index.js"
                    },
                    "internal": {
                      "id": "${refs.builder.id}",
                      "branch": "master",
                      "buildSHA": "latest"
                    }
                  },
                  "name": "server",
                  "billing": {
                    "deploymentPlan": "nf-compute-20"
                  },
                  "ports": [
                    {
                      "name": "app",
                      "internalPort": 3000,
                      "public": true,
                      "protocol": "HTTP",
                      "security": {
                        "credentials": [],
                        "policies": []
                      },
                      "domains": [],
                      "disableNfDomain": false
                    }
                  ],
                  "runtimeEnvironment": {},
                  "runtimeFiles": {}
                },
                "ref": "server"
              },
              {
                "kind": "DeploymentService",
                "spec": {
                  "deployment": {
                    "instances": 1,
                    "storage": {
                      "ephemeralStorage": {
                        "storageSize": 1024
                      },
                      "shmSize": 64
                    },
                    "docker": {
                      "configType": "customCommand",
                      "customCommand": "node ./dist/index-worker.js"
                    },
                    "internal": {
                      "id": "${refs.builder.id}",
                      "branch": "master",
                      "buildSHA": "latest"
                    }
                  },
                  "name": "worker",
                  "billing": {
                    "deploymentPlan": "nf-compute-10"
                  },
                  "ports": [],
                  "runtimeEnvironment": {},
                  "runtimeFiles": {}
                },
                "ref": "worker"
              }
            ]
          }
        }
      ]
    }
  }
}
```

</div>

</TabItem>


<TabItem label="Lite Template" value="Lite Template">

:::note
This template runs the Vendure server & worker in a single process, and as such will fit within the
resource limits of the Northflank free plan. Local disk storage is used for assets, which means that
horizontal scaling is not possible.

This setup is suitable for testing purposes, but is not recommended for production use.
:::


<div class="limited-height-code-block">

```json
{
  "apiVersion": "v1.2",
  "spec": {
    "kind": "Workflow",
    "spec": {
      "type": "sequential",
      "steps": [
        {
          "kind": "Project",
          "ref": "project", 
          "spec": {
            "name": "Vendure Lite",
            "region": "europe-west",
            "description": "Vendure is a modern, open-source composable commerce platform",
            "color": "#17b9ff"
          }
        },
        {
          "kind": "Addon",
          "spec": {
            "name": "database",
            "type": "postgres",
            "version": "14-latest",
            "billing": {
              "deploymentPlan": "nf-compute-20",
              "storageClass": "ssd",
              "storage": 4096,
              "replicas": 1
            },
            "tlsEnabled": false,
            "externalAccessEnabled": false,
            "ipPolicies": [],
            "pitrEnabled": false
          }
        },
        {
          "kind": "SecretGroup",
          "spec": {
            "projectId": "${refs.project.id}",
            "name": "secrets",
            "secretType": "environment-arguments",
            "priority": 10,
            "secrets": {
              "variables": {
                "APP_ENV": "production",
                "COOKIE_SECRET": "${fn.randomSecret(32)}",
                "SUPERADMIN_USERNAME": "superadmin",
                "SUPERADMIN_PASSWORD": "${fn.randomSecret(16)}",
                "DB_SCHEMA": "public",
                "ASSET_UPLOAD_DIR": "/data",
                "RUN_JOB_QUEUE_FROM_SERVER": "true"
              }
            },
            "addonDependencies": [
              {
                "addonId": "database",
                "keys": [
                  {
                    "keyName": "HOST",
                    "aliases": [
                      "DB_HOST"
                    ]
                  },
                  {
                    "keyName": "PORT",
                    "aliases": [
                      "DB_PORT"
                    ]
                  },
                  {
                    "keyName": "DATABASE",
                    "aliases": [
                      "DB_NAME"
                    ]
                  },
                  {
                    "keyName": "USERNAME",
                    "aliases": [
                      "DB_USERNAME"
                    ]
                  },
                  {
                    "keyName": "PASSWORD",
                    "aliases": [
                      "DB_PASSWORD"
                    ]
                  }
                ]
              }
            ],
            "restrictions": {
              "restricted": false,
              "nfObjects": [],
              "tags": []
            }
          }
        },
        {
          "kind": "BuildService",
          "spec": {
            "name": "builder",
            "projectId": "${refs.project.id}",
            "billing": {
              "deploymentPlan": "nf-compute-10"
            },
            "vcsData": {
              "projectUrl": "https://github.com/vendure-ecommerce/one-click-deploy",
              "projectType": "github"
            },
            "buildSettings": {
              "dockerfile": {
                "buildEngine": "kaniko",
                "dockerFilePath": "/Dockerfile",
                "dockerWorkDir": "/",
                "useCache": false
              }
            },
            "disabledCI": false,
            "buildArguments": {}
          }
        },
        {
          "kind": "Build",
          "ref": "build",
          "spec": {
            "id": "${refs.builder.id}",
            "projectId": "${refs.project.id}",
            "type": "service",
            "branch": "master",
            "reuseExistingBuilds": true
          },
          "condition": "success"
        },
        {
          "kind": "DeploymentService",
          "ref": "server",
          "spec": {
            "name": "server",
            "billing": {
              "deploymentPlan": "nf-compute-20"
            },
            "deployment": {
              "instances": 1,
              "storage": {
                "ephemeralStorage": {
                  "storageSize": 1024
                },
                "shmSize": 64
              },
              "docker": {
                "configType": "customCommand",
                "customCommand": "yarn start:server"
              },
              "internal": {
                "id": "${refs.builder.id}",
                "branch": "master",
                "buildSHA": "latest"
              }
            },
            "ports": [
              {
                "name": "app",
                "internalPort": 3000,
                "public": true,
                "protocol": "HTTP",
                "security": {
                  "credentials": [],
                  "policies": []
                },
                "domains": []
              }
            ],
            "runtimeEnvironment": {}
          }
        },
        {
          "kind": "Volume",
          "spec": {
            "spec": {
              "storageSize": 5120,
              "accessMode": "ReadWriteOnce",
              "storageClassName": "ssd"
            },
            "name": "storage",
            "mounts": [
              {
                "containerMountPath": "/data",
                "volumeMountPath": ""
              }
            ],
            "attachedObjects": [
              {
                "id": "${refs.server.id}",
                "type": "service"
              }
            ]
          }
        }
      ]
    }
  }
}
```

</div>

</TabItem>
</Tabs>

Then click the "Create template" button.

## Run the template

Next, click the "run template" button to start the deployment process.

![./03-run-template.webp](./03-run-template.webp)

Once the template run has completed, you should be able to see the newly-created project in the project selector.

![./04-find-project.webp](./04-find-project.webp)

## Find the public URL

Click the "Services" menu item in the left sidebar and then click the "Server" service.

![./05-server-service.webp](./05-server-service.webp)

In the top right corner you'll see the public URL of your new Vendure server!

Note that it may take a few minutes for the server to start up and populate all the test data because the free tier has limited CPU and memory resources.

Once it is ready, you can navigate to the public URL and append `/admin` to the end of the URL to access the admin panel. 


![./06-find-url.webp](./06-find-url.webp)

:::note
The superadmin password was generated for you by the template, and can be found in the "Secrets" section from the project nav bar
as `SUPERADMIN_PASSWORD`.
:::

Congratulations on deploying your Vendure server!


## Next steps

Now that you have a basic Vendure server up and running, you can explore some of the other features offered by Northflank 
that you might need for a full production setup:

- Configure [health checks](https://northflank.com/docs/v1/application/observe/configure-health-checks) to ensure any container crashes are rapidly detected and restarted. Also see the
[Vendure health check docs](/guides/deployment/using-docker#healthreadiness-checks).
- [Set up a Redis instance](https://northflank.com/docs/v1/application/databases-and-persistence/deploy-databases-on-northflank/deploy-redis-on-northflank) so that you can take advantage of our highly performant [BullMQJobQueuePlugin](/reference/core-plugins/job-queue-plugin/bull-mqjob-queue-plugin) and set up [Redis-based session caching](/reference/typescript-api/auth/session-cache-strategy/) to handle multi-instance deployments.
- With the above in place, you can safely start to [scale your server instances](https://northflank.com/docs/v1/application/scale/scaling-replicas) to handle more traffic. 
- [Add a custom domain](https://northflank.com/docs/v1/application/domains/add-a-domain-to-your-account) using Northflank's powerful DNS management system.
- Set up [infrastructure alerts](https://northflank.com/docs/v1/application/observe/set-infrastructure-alerts) to be notified when any of your containers crash or experience load spikes.


---

---
title: "Deploying to Railway"
---

![Deploy to Railway](./deploy-to-railway.webp)

[Railway](https://railway.app/) is a managed hosting platform which allows you to deploy and scale your Vendure server and infrastructure with ease.

:::note
This guide should be runnable on the Railway free trial plan, which means you can deploy it for free and thereafter
pay only for the resources you use, which should be around $5 per month.
:::

## Prerequisites

First of all you'll need to create a new Railway account (click "login" on the website and enter your email address) if you
don't already have one.

You'll also need a GitHub account and you'll need to have your Vendure project hosted there. 

In order to use the Railway trial plan, you'll need to connect your GitHub account to Railway via the Railway dashboard.

:::info
If you'd like to quickly get started with a ready-made Vendure project which includes sample data, you can clone our
[Vendure one-click-deploy repo](https://github.com/vendure-ecommerce/one-click-deploy).
:::

## Configuration

### Port

Railway defines the port via the `PORT` environment variable, so make sure your Vendure Config uses this variable:

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';

export const config: VendureConfig = {
    apiOptions: {
        // highlight-next-line
        port: +(process.env.PORT || 3000),
        // ...
    },
    // ...
};
```

### Database connection

:::info
The following is already pre-configured if you are using the one-click-deploy repo.
:::

Make sure your DB connection options uses the following environment variables:

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';

export const config: VendureConfig = {
    // ...
    dbConnectionOptions: {
        // ...
        database: process.env.DB_NAME,
        host: process.env.DB_HOST,
        port: +process.env.DB_PORT,
        username: process.env.DB_USERNAME,
        password: process.env.DB_PASSWORD,
    },
};
```
### Asset storage

:::info
The following is already pre-configured if you are using the one-click-deploy repo.
:::

In this guide we will use the AssetServerPlugin's default local disk storage strategy. Make sure you use the
`ASSET_UPLOAD_DIR` environment variable to set the path to the directory where the uploaded assets will be stored.

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';
import { AssetServerPlugin } from '@vendure/asset-server-plugin';

export const config: VendureConfig = {
    // ...
    plugins: [
        AssetServerPlugin.init({
            route: 'assets',
            // highlight-next-line
            assetUploadDir: process.env.ASSET_UPLOAD_DIR || path.join(__dirname, '../static/assets'),
        }),
    ],
    // ...
};
```

## Create a new Railway project

From the Railway dashboard, click "New Project" and select "Empty Project". You'll be taken to a screen where you can
add the first service to your project. 

## Create the database

Click the "Add a Service" button and select "database". Choose a database that matches the one you are using in your
Vendure project. If you are following along using the one-click-deploy repo, then choose "Postgres".

## Create the Vendure server

Click the "new" button to create a new service, and select "GitHub repo". Select the repository which contains your
Vendure project. You may need to configure access to this repo if you haven't already done so.

![Create new service](./01-new-service.webp)

### Configure the server service

You should then see a card representing this service in the main area of the dashboard. Click the card and go to the
"settings" tab.

* Scroll to the "Service" section and rename the service to "vendure-server".
* Check the "Build" section and make sure the build settings make sense for your repo. If you are using
the one-click-deploy repo, then it should detect the Dockerfile.
* In the "Deploy" section, set the "Custom start command" to `node ./dist/index.js`.
* Finally, scroll up to the "Networking" section and click "Generate domain" to set up a temporary domain for your
Vendure server.

### Create a Volume

In order to persist the uploaded product images, we need to create a volume. Click the "new" button and select "Volume".
Attach it to the "vendure-server" service and set the mount path to `/vendure-assets`.

### Configure server env vars

Click on the "vendure-server" service and go to the "Variables" tab. This is where we will set up the environment
variables which are used in our Vendure Config. You can use the raw editor to add the following variables, making
sure to replace the highlighted values with your own:

```sh
DB_NAME=${{Postgres.PGDATABASE}}
DB_USERNAME=${{Postgres.PGUSER}}
DB_PASSWORD=${{Postgres.PGPASSWORD}}
DB_HOST=${{Postgres.PGHOST}}
DB_PORT=${{Postgres.PGPORT}}
ASSET_UPLOAD_DIR=/vendure-assets
// highlight-next-line
COOKIE_SECRET=<add some random characters>
SUPERADMIN_USERNAME=superadmin
// highlight-next-line
SUPERADMIN_PASSWORD=<create some strong password>
```

![Setting env vars](./02-env-vars.webp) 

:::note
The variables starting with `${{Postgres...}}` assume that your database service is called "Postgres". If you have
named it differently, then you'll need to change these variables accordingly.
:::

## Create the Vendure worker

Finally, we need to define the worker process which will run the background tasks. Click the "new" button and select
"GitHub repo". Select again the repository which contains your Vendure project. 

### Configure the worker service

You should then see a card representing this service in the main area of the dashboard. Click the card and go to the
"settings" tab.

* Scroll to the "Service" section and rename the service to "vendure-worker".
* Check the "Build" section and make sure the build settings make sense for your repo. If you are using
  the one-click-deploy repo, then it should detect the Dockerfile.
* In the "Deploy" section, set the "Custom start command" to `node ./dist/index-worker.js`.

### Configure worker env vars

The worker will need to know how to connect to the database, so add the following variables to the "Variables" tab:

```sh
DB_NAME=${{Postgres.PGDATABASE}}
DB_USERNAME=${{Postgres.PGUSER}}
DB_PASSWORD=${{Postgres.PGPASSWORD}}
DB_HOST=${{Postgres.PGHOST}}
DB_PORT=${{Postgres.PGPORT}}
```

## Test your Vendure server

To test that everything is working, click the "vendure-server" card and then the link to the temporary domain.

![Test server](./03-test-server.webp)

## Next Steps

This setup gives you a basic Vendure server to get started with. When moving to a more production-ready setup, you'll
want to consider the following:

- Use MinIO for asset storage. This is a more robust and scalable solution than the local disk storage used here. 
  - [MinIO template for Railway](https://railway.app/template/SMKOEA), 
  - [Configuring the AssetServerPlugin for MinIO](/reference/core-plugins/asset-server-plugin/s3asset-storage-strategy/#usage-with-minio)
- Use Redis to power the job queue and session cache. This is not only more performant, but will enable horizontal scaling of your
server and worker instances.
  - [Railway Redis docs](https://docs.railway.app/guides/redis)
  - [Vendure horizontal scaling docs](/guides/deployment/horizontal-scaling)
  

---

---
title: "Deploying to Render"
---

![Deploy to Render](./deploy-to-render.webp)

[Render](https://render.com/) is a managed hosting platform which allows you to deploy and scale your Vendure server and infrastructure with ease.

:::note
The configuration in this guide will cost from around $12 per month to run.
:::

## Prerequisites

First of all you'll need to [create a new Render account](https://dashboard.render.com/register) if you
don't already have one.

For this guide you'll need to have your Vendure project in a git repo on either GitHub or GitLab.

:::info
If you'd like to quickly get started with a ready-made Vendure project which includes sample data, you can use our
[Vendure one-click-deploy repo](https://github.com/vendure-ecommerce/one-click-deploy), which means you won't have
to set up your own git repo.
:::

## Configuration

### Port

Render defines the port via the `PORT` environment variable and [defaults to `10000`](https://docs.render.com/web-services#host-and-port-configuration), so make sure your Vendure Config uses this variable:

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';

export const config: VendureConfig = {
    apiOptions: {
        // highlight-next-line
        port: +(process.env.PORT || 3000),
        // ...
    },
    // ...
};
```

### Database connection

:::info
The following is already pre-configured if you are using the one-click-deploy repo.
:::

Make sure your DB connection options uses the following environment variables:

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';

export const config: VendureConfig = {
    // ...
    dbConnectionOptions: {
        // ...
        database: process.env.DB_NAME,
        host: process.env.DB_HOST,
        port: +process.env.DB_PORT,
        username: process.env.DB_USERNAME,
        password: process.env.DB_PASSWORD,
    },
};
```
### Asset storage

:::info
The following is already pre-configured if you are using the one-click-deploy repo.
:::

In this guide we will use the AssetServerPlugin's default local disk storage strategy. Make sure you use the
`ASSET_UPLOAD_DIR` environment variable to set the path to the directory where the uploaded assets will be stored.

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';
import { AssetServerPlugin } from '@vendure/asset-server-plugin';

export const config: VendureConfig = {
    // ...
    plugins: [
        AssetServerPlugin.init({
            route: 'assets',
            // highlight-next-line
            assetUploadDir: process.env.ASSET_UPLOAD_DIR || path.join(__dirname, '../static/assets'),
        }),
    ],
    // ...
};
```

## Create a database

From the Render dashboard, click the "New" button and select "PostgreSQL" from the list of services:

![Create a new PostgreSQL database](./01-create-db.webp)

Give the database a name (e.g. "postgres"), select a region close to you, select an appropriate plan
and click "Create Database".

## Create the Vendure server

Click the "New" button again and select "Web Service" from the list of services. Choose the "Build and deploy from a Git repository" option.

In the next step you will be prompted to connect to either GitHub or GitLab. Select the appropriate option and follow the instructions
to connect your account and grant access to the repository containing your Vendure project.

:::info
If you are using the one-click-deploy repo, you should instead use the "Public Git repository" option and enter the URL of the repo:

```
https://github.com/vendure-ecommerce/one-click-deploy
```
:::

### Configure the server service

In the next step you will configure the server:

- **Name**: "vendure-server"
- **Region**: Select a region close to you
- **Branch**: Select the branch you want to deploy, usually "main" or "master"
- **Runtime**: If you have a Dockerfile then it should be auto-detected. If not you should select "Node" and enter the appropriate build and start commands. For a
typical Vendure project these would be:
  - **Build Command**: `yarn; yarn build` or `npm install; npm run build`
  - **Start Command**: `node ./dist/index.js`
- **Instance Type**: Select the appropriate instance type. Since we want to use a persistent volume to store our assets, we need to
use at least the "Starter" instance type or higher.

Click the "Advanced" button to expand the advanced options:

- Click "Add Disk" to set up a persistent volume for the assets and use the following settings:
  - **Name**: "vendure-assets"
  - **Mount Path**: `/vendure-assets`
  - **Size**: As appropriate. For testing purposes you can use the smallest size (1GB)
- **Health Check Path**: `/health`
- **Docker Command**: `node ./dist/index.js` (if you are _not_ using a Dockerfile this option will not be available)

Click "Create Web Service" to create the service.

:::note
If you have not already set up payment, you will be prompted to enter credit card details at this point.
:::

## Configure environment variables

Next we need to set up the environment variables which will be used by both the server and worker. Click the "Env Groups" tab
and then click the "New Environment Group" button.

Name the group "vendure configuration" and add the following variables. The database variables can be found by navigating
to the database service, clicking the "Info" tab and scrolling to the "Connections" section:

![Database connection settings](./03-db-connection.webp)

```shell
DB_NAME=<database "Database">
DB_USERNAME=<database "Username">
DB_PASSWORD=<database "Password">
DB_HOST=<database "Hostname">
DB_PORT=<database "Port">
ASSET_UPLOAD_DIR=/vendure-assets
// highlight-next-line
COOKIE_SECRET=<add some random characters>
SUPERADMIN_USERNAME=superadmin
// highlight-next-line
SUPERADMIN_PASSWORD=<create some strong password>
```
Once the correct values have been entered, click "Create Environment Group".

Next, click the "vendure-server" service and go to the "Environment" tab to link the environment group to the service:

![Link environment group](./04-link-env-group.webp)

## Create the Vendure worker

Finally, we need to define the worker process which will run the background tasks. Click the "New" button and select
"Background Worker".

Select the same git repo as before, and in the next step configure the worker:

- **Name**: "vendure-worker"
- **Region**: Same as the server
- **Branch**: Select the branch you want to deploy, usually "main" or "master"
- **Runtime**: If you have a Dockerfile then it should be auto-detected. If not you should select "Node" and enter the appropriate build and start commands. For a
  typical Vendure project these would be:
  - **Build Command**: `yarn; yarn build` or `npm install; npm run build`
  - **Start Command**: `node ./dist/index-worker.js`
- **Instance Type**: Select the appropriate instance type. The Starter size is fine to get started.

Click the "Advanced" button to expand the advanced options:

- **Docker Command**: `node ./dist/index-worker.js` (if you are _not_ using a Dockerfile this option will not be available)

Click "Create Background Worker" to create the worker.

Finally, click the "Environment" tab and link the "vendure configuration" environment group to the worker.

## Test your Vendure server

Navigate back to the dashboard, click the "vendure-server" service, and you should see a link to the temporary domain:

![Test server](./05-server-url.webp)

Click the link and append `/admin` to the URL to open the Admin UI. Log in with the username and password you set in the
environment variables.

## Next Steps

This setup gives you a basic Vendure server to get started with. When moving to a more production-ready setup, you'll
want to consider the following:

- Use MinIO for asset storage. This is a more robust and scalable solution than the local disk storage used here.
  - [Deploying MinIO to Render](https://docs.render.com/deploy-minio),
  - [Configuring the AssetServerPlugin for MinIO](/reference/core-plugins/asset-server-plugin/s3asset-storage-strategy/#usage-with-minio)
- Use Redis to power the job queue and session cache. This is not only more performant, but will enable horizontal scaling of your
  server and worker instances.
  - [Render Redis docs](https://docs.render.com/redis#creating-a-redis-instance)
  - [Vendure horizontal scaling docs](/guides/deployment/horizontal-scaling)
  

---

---
title: "Deploying the Admin UI"
showtoc: true
---

## Compiling the Admin UI

If you have customized the Admin UI with extensions, you should compile your custom Admin UI app ahead of time
before deploying it. This will bundle the app into a set of static files which are then served by the AdminUiPlugin.

- [Guide: Compiling the Admin UI as a deployment step](/guides/extending-the-admin-ui/getting-started/#compiling-as-a-deployment-step).

:::warning

It is not recommended to compile the Admin UI on the server at runtime, as this can be slow and resource-intensive.
Instead, compile the Admin UI ahead of time and deploy the compiled assets, as covered in the guide linked above.
:::

## Setting the API host & port

When running in development mode, the Admin UI app will "guess" the API host and port based on the current URL in the browser. Typically, this will
be `http://localhost:3000`. For production deployments where the Admin UI app is served from a different host or port than the Vendure server, you'll need to
configure the Admin UI app to point to the correct API host and port.

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';
import { AdminUiPlugin } from '@vendure/admin-ui-plugin';

const config: VendureConfig = {
    // ...
    plugins: [
        AdminUiPlugin.init({
            port: 3001,
            route: 'admin',
            adminUiConfig: {
                apiHost: 'https://api.example.com',
                apiPort: 443,
            },
        }),
    ],
};
```

## Deploying a stand-alone Admin UI

Usually, the Admin UI is served from the Vendure server via the AdminUiPlugin. However, you may wish to deploy the Admin UI app elsewhere. Since it is just a static Angular app, it can be deployed to any static hosting service such as Vercel or Netlify.

#### Metrics

The AdminUiPlugin not only serves the Admin UI app, but also provides a `metricSummary` query which is used to display the order metrics on the dashboard. If you wish to deploy the Admin UI app stand-alone (not served by the AdminUiPlugin), but still want to display the metrics on the dashboard, you'll need to include the AdminUiPlugin in your server's plugins array, but do not call `init()`:

```ts title="src/vendure-config.ts"
import { AdminUiPlugin } from '@vendure/admin-ui-plugin';

const config: VendureConfig = {
    plugins: [
        AdminUiPlugin, // <== include the plugin, but don't call init()
    ],
    // ...
};
```

#### Example Script

Here's an example script that can be run as part of your host's `build` command, which will generate a stand-alone app bundle and configure it to point to your remote server API.

This example is for Vercel, and assumes:

* A `BASE_HREF` environment variable to be set to `/`
* A public (output) directory set to `build/dist`
* A build command set to `npm run build` or `yarn build`
* A package.json like this:
    ```json title="package.json"
    {
      "name": "standalone-admin-ui",
      "version": "0.1.0",
      "private": true,
      "scripts": {
        "build": "ts-node compile.ts"
      },
      "devDependencies": {
        "@vendure/ui-devkit": "^1.4.5",
        "ts-node": "^10.2.1",
        "typescript": "~4.3.5"
      }
    }
    ```

```ts title="compile.ts"
import { compileUiExtensions } from '@vendure/ui-devkit/compiler';
import { DEFAULT_BASE_HREF } from '@vendure/ui-devkit/compiler/constants';
import path from 'path';
import { promises as fs } from 'fs';

/**
 * Compiles the Admin UI. If the BASE_HREF is defined, use that.
 * Otherwise, go back to the default admin route.
 */
compileUiExtensions({
    outputPath: path.join(__dirname, 'build'),
    baseHref: process.env.BASE_HREF ?? DEFAULT_BASE_HREF,
    extensions: [
        /* any UI extensions would go here, or leave empty */
    ],
})
    .compile?.()
    .then(() => {
        // If building for Vercel deployment, replace the config to make 
        // api calls to api.example.com instead of localhost.
        if (process.env.VERCEL) {
            console.log('Overwriting the vendure-ui-config.json for Vercel deployment.');
            return fs.writeFile(
                path.join(__dirname, 'build', 'dist', 'vendure-ui-config.json'),
                JSON.stringify({
                    apiHost: 'https://api.example.com',
                    apiPort: '443',
                    adminApiPath: 'admin-api',
                    tokenMethod: 'cookie',
                    defaultLanguage: 'en',
                    availableLanguages: ['en', 'de'],
                    hideVendureBranding: false,
                    hideVersion: false,
                }),
            );
        }
    })
    .then(() => {
        process.exit(0);
    });
```


---

---
title: "Getting data into production"
showtoc: true
weight: 4
---

# Getting data into production

Once you have set up your production deployment, you'll need some way to get your products and other data into the system.

The main tasks will be:

1. Creation of the database schema
2. Importing initial data like roles, tax rates, countries etc.
3. Importing catalog data like products, variants, options, facets
4. Importing other data used by your application

## Creating the database schema

The first item - creation of the schema - can be automatically handled by TypeORM's `synchronize` feature. Switching it on for the initial
run will automatically create the schema. This can be done by using an environment variable:

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';

export const config: VendureConfig = {
    // ...
    dbConnectionOptions: {
        type: 'postgres',
        // highlight-next-line
        synchronize: process.env.DB_SYNCHRONIZE,
        host: process.env.DB_HOST,
        port: process.env.DB_PORT,
        username: process.env.DB_USER,
        password: process.env.DB_PASSWORD,
        database: process.env.DB_DATABASE,
    },
    // ...
};
```

Set the `DB_SYNCHRONIZE` variable to `true` on first start, and then after the schema is created, set it to `false`.

## Importing initial & catalog data

Importing initial and catalog data can be handled by Vendure `populate()` helper function - see the [Importing Product Data guide](/guides/developer-guide/importing-data/).

## Importing other data

Any kinds of data not covered by the `populate()` function can be imported using a custom script, which can use any Vendure service or service defined by your custom plugins to populate data in any way you like. See the [Stand-alone scripts guide](/guides/developer-guide/stand-alone-scripts/).


---

---
title: "Horizontal scaling"
showtoc: true
weight: 2
---

# Horizontal scaling

"Horizontal scaling" refers to increasing the performance capacity of your application by running multiple instances.

This type of scaling has two main advantages:

1. It can enable increased throughput (requests/second) by distributing the incoming requests between multiple instances.
2. It can increase resilience because if a single instance fails, the other instances will still be able to service requests.

As discussed in the [Server resource requirements guide](/guides/deployment/server-resource-requirements), horizontal scaling can be the most cost-effective way of deploying your Vendure server due to the single-threaded nature of Node.js.

In Vendure, both the server and the worker can be scaled horizontally. Scaling the server will increase the throughput of the GraphQL APIs, whereas scaling the worker can increase the speed with which the job queue is processed by allowing more jobs to be run in parallel.

## Multi-instance configuration

In order to run Vendure in a multi-instance configuration, there are some important configuration changes you'll need to make. The key consideration in configuring Vendure for this scenario is to ensure that any persistent state is managed externally from the Node process, and is shared by all instances. Namely:

* The JobQueue should be stored externally using the [DefaultJobQueuePlugin](/reference/typescript-api/job-queue/default-job-queue-plugin/) (which stores jobs in the database) or the [BullMQJobQueuePlugin](/reference/core-plugins/job-queue-plugin/bull-mqjob-queue-plugin) (which stores jobs in Redis), or some other custom JobQueueStrategy. **Note:** the BullMQJobQueuePlugin is much more efficient than the DefaultJobQueuePlugin, and is recommended for production applications.
* An appropriate [CacheStrategy](/reference/typescript-api/cache/cache-strategy/) must be used which stores the cache externally. Both the [DefaultCachePlugin](/reference/typescript-api/cache/default-cache-plugin/) and the [RedisCachePlugin](/reference/typescript-api/cache/redis-cache-plugin/) are suitable 
  for multi-instance setups. The DefaultCachePlugin uses the database to store the cache data, which is simple and effective, while the RedisCachePlugin uses a Redis server to store the cache data and can have better performance characteristics.
* If you are on a version prior to v3.1, a custom [SessionCacheStrategy](/reference/typescript-api/auth/session-cache-strategy/) must be used which stores the session cache externally (such as in the database or Redis), since the default strategy stores the cache in-memory and will cause inconsistencies in multi-instance setups. [Example Redis-based SessionCacheStrategy](/reference/typescript-api/auth/session-cache-strategy/).
  From v3.1 the session cache is handled by the underlying cache strategy, so you normally don't need to define a custom SessionCacheStrategy.
* When using cookies to manage sessions, make sure all instances are using the _same_ cookie secret:
    ```ts title="src/vendure-config.ts"
    const config: VendureConfig = {
      authOptions: {
        cookieOptions: {
          secret: 'some-secret'
        }
      }
    }
    ```
* Channel and Zone data gets cached in-memory as this data is used in virtually every request. The cache time-to-live defaults to 30 seconds, which is probably fine for most cases, but it can be configured in the [EntityOptions](/reference/typescript-api/configuration/entity-options/#channelcachettl).

## Using Docker or Kubernetes

One way of implementing horizontal scaling is to use Docker to wrap your Vendure server & worker in a container, which can then be run as multiple instances.

Some hosting providers allow you to provide a Docker image and will then run multiple instances of that image. Kubernetes can also be used to manage multiple instances
of a Docker image.

For a more complete guide, see the [Using Docker guide](/guides/deployment/using-docker).

## Using PM2

[PM2](https://pm2.keymetrics.io/) is a process manager which will spawn multiple instances of your server or worker, as well as re-starting any instances that crash. PM2 can be used on VPS hosts to manage multiple instances of Vendure without needing Docker or Kubernetes.

PM2 must be installed on your server:

```sh
npm install pm2@latest -g
```

Your processes can then be run in [cluster mode](https://pm2.keymetrics.io/docs/usage/cluster-mode/) with the following command:

```sh
pm2 start ./dist/index.js -i 4
```

The above command will start a cluster of 4 instances. You can also instruct PM2 to use the maximum number of available CPUs with `-i max`.

Note that if you are using pm2 inside a Docker container, you should use the `pm2-runtime` command:

```dockerfile
# ... your existing Dockerfile config
RUN npm install pm2 -g

CMD ["pm2-runtime", "app.js", "-i", "max"]
```


---

---
title: 'Production configuration'
showtoc: true
weight: 0
---

# Production configuration

This is a guide to the recommended configuration for a production Vendure application.

## Environment variables

Keep sensitive information or context-dependent settings in environment variables. In local development you can store the values in a `.env` file. For production, you should use the mechanism provided by your hosting platform to set the values for production.

The default `@vendure/create` project scaffold makes use of environment variables already. For example:

```ts
const IS_DEV = process.env.APP_ENV === 'dev';
```

The `APP_ENV` environment variable can then be set using the admin dashboard of your hosting provider:

![A typical UI for setting env vars](./env-var-ui.webp)

If you are using [Docker or Kubernetes](/guides/deployment/using-docker), they include their own methods of setting environment variables.

## Superadmin credentials

Ensure you set the superadmin credentials to something other than the default of `superadmin:superadmin`. Use your hosting platform's environment variables to set a **strong** password for the Superadmin account.

```ts
import { VendureConfig } from '@vendure/core';

export const config: VendureConfig = {
  authOptions: {
    tokenMethod: ['bearer', 'cookie'],
    superadminCredentials: {
      identifier: process.env.SUPERADMIN_USERNAME,
      password: process.env.SUPERADMIN_PASSWORD,
    },
  },
  // ...
};
```

## API hardening

It is recommended that you install and configure the [HardenPlugin](/reference/core-plugins/harden-plugin/) for all production deployments. This plugin locks down your schema (disabling introspection and field suggestions) and protects your Shop API against malicious queries that could otherwise overwhelm your server.

Install the plugin: 

```sh
npm install @vendure/harden-plugin

# or

yarn add @vendure/harden-plugin
```

Then add it to your VendureConfig:

```ts
import { VendureConfig } from '@vendure/core';
import { HardenPlugin } from '@vendure/harden-plugin';

const IS_DEV = process.env.APP_ENV === 'dev';

export const config: VendureConfig = {
  // ...
  plugins: [
    HardenPlugin.init({
      maxQueryComplexity: 500,
      apiMode: IS_DEV ? 'dev' : 'prod',
    }),
    // ...
  ]
};
```

:::info
For a detailed explanation of how to best configure this plugin, see the [HardenPlugin docs](/reference/core-plugins/harden-plugin/).
:::

## ID Strategy

By default, Vendure uses auto-increment integer IDs as entity primary keys. While easier to work with in development, sequential primary keys can leak information such as the number of orders or customers in the system.

For this reason you should consider using the UuidIdStrategy for production.

```ts title="src/vendure-config.ts"
import { UuidIdStrategy, VendureConfig } from '@vendure/core';

export const config: VendureConfig = {
    entityOptions: {
        entityIdStrategy: new UuidIdStrategy(),
    },
    // ...
}
```

Another option, if you wish to stick with integer IDs, is to create a custom [EntityIdStrategy](/reference/typescript-api/configuration/entity-id-strategy/) which uses the `encodeId()` and `decodeId()` methods to obfuscate the sequential nature of the ID.

## Database Timezone

Vendure internally treats all dates & times as UTC. However, you may sometimes run into issues where dates are offset by some fixed amount of hours. E.g. you place an order at 17:00, but it shows up in the Admin UI as being placed at 19:00. Typically, this is caused by the timezone of your database not being set to UTC.

You can check the timezone in **MySQL/MariaDB** by executing:

```SQL
SELECT TIMEDIFF(NOW(), UTC_TIMESTAMP);
```
and you should expect to see `00:00:00`.

In **Postgres**, you can execute:
```SQL
show timezone;
```
and you should expect to see `UTC` or `Etc/UTC`.

## Trust proxy

When deploying your Vendure application behind a reverse proxy (usually the case with most hosting services), consider configuring Express's `trust proxy` setting. This allows you to retrieve the original IP address from the `X-Forwarded-For` header, which proxies use to forward the client's IP address.

You can set the `trustProxy` option in your `VendureConfig`:

```ts
import { VendureConfig } from '@vendure/core';

export const config: VendureConfig = {
    apiOptions: {
        trustProxy: 1, // Trust the first proxy in front of your app
    },
};
```

For more details on configuring `trust proxy`, refer to the [Express documentation](https://expressjs.com/en/guide/behind-proxies.html).

## Security Considerations

Please read over the [Security](/guides/developer-guide/security) section of the Developer Guide for more information on how to secure your Vendure application.


---

---
title: 'Server resource requirements'
showtoc: true
weight: 1
---

## Server resource requirements

### RAM

The Vendure server and worker process each use around 200-300MB of RAM when idle. This figure will increase under load.

The total RAM required by a single instance of the server depends on your project size (the number of products, variants, customers, orders etc.) as well as expected load (the number of concurrent users you expect). As a rule, 512MB per process would be a practical minimum for a smaller project with low expected load.

### CPU

CPU resources are generally measured in "cores" or "vCPUs" (virtual CPUs) depending on the type of hosting. The exact relationship between vCPUs and physical CPU cores is out of the scope of this guide, but for our purposes we will use "CPU" to refer to both physical and virtual CPU resources.

Because Node.js is single-threaded, a single instance of the Vendure server or worker will not be able to take advantage of multiple CPUs. For example, if you set up a server instance running with 4 CPUs, the server will only use 1 of those CPUs and the other 3 will be wasted.

Therefore, when looking to optimize performance (for example, the number of requests that can be serviced per second), it makes sense to scale horizontally by running multiple instances of the Vendure server. See the [Horizontal Scaling guide](/guides/deployment/horizontal-scaling).

## Load testing

It is important to test whether your current server configuration will be able to handle the loads you expect when you go into production. There are numerous tools out there to help you load test your application, such as:

- [k6](https://k6.io/)
- [Artillery](https://www.artillery.io/)
- [jMeter](https://jmeter.apache.org/)


---

---
title: "Using docker"
showtoc: true
weight: 3
---

# Using Docker

[Docker](https://docs.docker.com/) is a technology which allows you to run your Vendure application inside a [container](https://docs.docker.com/get-started/#what-is-a-container).
The default installation with `@vendure/create` includes a sample Dockerfile:

```dockerfile title="Dockerfile"
FROM node:22

WORKDIR /usr/src/app

COPY package.json ./
COPY package-lock.json ./ 
RUN npm install --production
COPY . .
RUN npm run build
```

This Dockerfile can then be built into an "image" using:

```sh
docker build -t vendure .
```

This same image can be used to run both the Vendure server and the worker:

```sh
# Run the server
docker run -dp 3000:3000 --name vendure-server vendure npm run start:server

# Run the worker
docker run -dp 3000:3000 --name vendure-worker vendure npm run start:worker
```

Here is a breakdown of the command used above:

- `docker run` - run the image we created with `docker build`
- `-dp 3000:3000` - the `-d` flag means to run in "detached" mode, so it runs in the background and does not take control of your terminal. `-p 3000:3000` means to expose port 3000 of the container (which is what Vendure listens on by default) as port 3000 on your host machine.
- `--name vendure-server` - we give the container a human-readable name.
- `vendure` - we are referencing the tag we set up during the build.
- `npm run start:server` - this last part is the actual command that should be run inside the container.

## Docker Compose

Managing multiple docker containers can be made easier using [Docker Compose](https://docs.docker.com/compose/). In the below example, we use 
the same Dockerfile defined above, and we also define a Postgres database to connect to:

```yaml
version: "3"
services:
  server:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - 3000:3000
    command: ["npm", "run", "start:server"]
    volumes:
      - /usr/src/app
    environment:
      DB_HOST: database
      DB_PORT: 5432
      DB_NAME: vendure
      DB_USERNAME: postgres
      DB_PASSWORD: password
  worker:
    build:
      context: .
      dockerfile: Dockerfile
    command: ["npm", "run", "start:worker"]
    volumes:
      - /usr/src/app
    environment:
      DB_HOST: database
      DB_PORT: 5432
      DB_NAME: vendure
      DB_USERNAME: postgres
      DB_PASSWORD: password
  database:
    image: postgres
    volumes:
      - /var/lib/postgresql/data
    ports:
      - 5432:5432
    environment:
      POSTGRES_PASSWORD: password
      POSTGRES_DB: vendure
```

## Kubernetes

[Kubernetes](https://kubernetes.io/) is used to manage multiple containerized applications. 
This deployment starts the shop container we created above as both worker and server.

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: vendure-shop
spec:
  selector:
    matchLabels:
      app: vendure-shop
  replicas: 1
  template:
    metadata:
      labels:
        app: vendure-shop
    spec:
      containers:
        - name: server
          image: vendure-shop:latest
          command:
            - node
          args:
            - "dist/index.js"
          env:
          # your env config here
          ports:
            - containerPort: 3000

        - name: worker
          image: vendure-shop:latest
          imagePullPolicy: Always
          command:
            - node
          args:
            - "dist/index-worker.js"
          env:
          # your env config here
          ports:
            - containerPort: 3000
```

## Health/Readiness Checks

If you wish to deploy with Kubernetes or some similar system, you can make use of the health check endpoints. 

### Server

This is a regular REST route (note: _not_ GraphQL), available at `/health`.

```text 
REQUEST: GET http://localhost:3000/health
```
 
```json
{
  "status": "ok",
  "info": {
    "database": {
      "status": "up"
    }
  },
  "error": {},
  "details": {
    "database": {
      "status": "up"
    }
  }
}
```

Health checks are built on the [Nestjs Terminus module](https://docs.nestjs.com/recipes/terminus). You can also add your own health checks by creating plugins that make use of the [HealthCheckRegistryService](/reference/typescript-api/health-check/health-check-registry-service/).

### Worker

Although the worker is not designed as an HTTP server, it contains a minimal HTTP server specifically to support HTTP health checks. To enable this, you need to call the `startHealthCheckServer()` method after bootstrapping the worker:

```ts
bootstrapWorker(config)
    .then(worker => worker.startJobQueue())
    .then(worker => worker.startHealthCheckServer({ port: 3020 }))
    .catch(err => {
        console.log(err);
    });
```
This will make the `/health` endpoint available. When the worker instance is running, it will return the following:

```text 
REQUEST: GET http://localhost:3020/health
```

```json
{
  "status": "ok"
}
```


---

---
title: "Cache"
---

Caching is a technique to improve performance of a system by saving the results of expensive
operations and reusing them when the same operation is requested again.

Vendure uses caching in a number of places to improve performance, and the same caching
mechanism is available for use in custom plugins.

## Setting up the cache

In order to take advantage of Vendure distributed caching, you need to enable a cache plugin.

:::note
If no cache plugin is specified, Vendure uses an in-memory cache which is not shared between instances.
This is suitable for development, but not recommended for production use.
:::

### DefaultCachePlugin

The [DefaultCachePlugin](/reference/typescript-api/cache/default-cache-plugin) uses the database to store the cache data.
This is a simple and effective cache strategy which has the advantage of not requiring any additional
infrastructure.

```ts title="vendure-config.ts"
import { DefaultCachePlugin, VendureConfig } from '@vendure/core';

export const config: VendureConfig = {
    // ...
    plugins: [
        DefaultCachePlugin.init({
            // optional maximum number of items to
            // store in the cache. Defaults to 10,000
            cacheSize: 20_000,
        }),
    ],
};
```

After enabling the `DefaultCachePlugin`, you will need to [generate a migration](/guides/developer-guide/migrations/) to add the necessary
tables to the database.

### RedisCachePlugin

Vendure also provides a [RedisCachePlugin](/reference/typescript-api/cache/redis-cache-plugin) which uses a Redis
server to store the cache data and can have better performance characteristics.

```ts title="vendure-config.ts"
import { RedisCachePlugin, VendureConfig } from '@vendure/core';

export const config: VendureConfig = {
    // ...
    plugins: [
        RedisCachePlugin.init({
            redisOptions: {
                host: 'localhost',
                port: 6379,
            },
        }),
    ],
};
```

## CacheService

The [`CacheService`](/reference/typescript-api/cache/cache-service) is the general-purpose API for interacting with the cache.
It provides methods for setting, getting and deleting cache entries.

![CacheService](./cache-service.webp)

Internally, the `CacheService` uses a [CacheStrategy](/reference/typescript-api/cache/cache-strategy) to store the data. The cache strategy is responsible for
the actual storage and retrieval of the data. The `CacheService` provides a consistent API which can be used
regardless of the underlying cache strategy.

:::info
From Vendure v3.1, new projects are created with the [DefaultCachePlugin](/reference/typescript-api/cache/default-cache-plugin) enabled by default. This plugin
uses the database to store the cache data. This is a simple and effective cache strategy which is suitable
for most use-cases.

For more advanced use-cases, you can use the [RedisCachePlugin](/reference/typescript-api/cache/redis-cache-plugin) which uses a Redis
server to store the cache data and can have better performance characteristics.
:::

### Multi-instance use

It is common to run Vendure in a multi-instance setup, where multiple instances of the server and worker are
running in parallel.

The `CacheService` is designed to work in this environment. Both the [DefaultCachePlugin](/reference/typescript-api/cache/default-cache-plugin)
and the [RedisCachePlugin](/reference/typescript-api/cache/redis-cache-plugin) use a single shared cache across all
instances.

This means that if one instance sets a cache entry, it will be available to all other instances. Likewise,
if one instance deletes a cache entry, it will be deleted for all other instances.

### Usage

The `CacheService` can be injected into any service, resolver, strategy or configurable operation.

```ts
import { Injectable } from '@nestjs/common';
import { CacheService } from '@vendure/core';

@Injectable()
export class MyService {
    constructor(private cacheService: CacheService) {}

    async myMethod() {
        const cacheKey = 'MyService.myMethod';
        const cachedValue = await this.cacheService.get(cacheKey);
        if (cachedValue) {
            return cachedValue;
        }
        const newValue = await this.expensiveOperation();
        // Cache the result for 1 minute (60 * 1000 milliseconds)
        await this.cacheService.set(cacheKey, newValue, { ttl: 60 * 1000 });
        return newValue;
    }

    private async expensiveOperation() {
        // Do something expensive
    }
}
```

:::info

The data stored in the cache must be serializable. This means you cannot store instances of classes,
functions, or other non-serializable data types.

:::

### Cache key naming

When setting a cache entry, it is important to choose a unique key which will not conflict
with other cache entries. The key should be namespaced to avoid conflicts. For example,
you can use the name of the class & method as part of the key. If there is an identifier
which is unique to the operation, that can be used as well.

```ts
getVariantIds(productId: ID): Promise<ID[]> {
    const cacheKey = `ProductService.getVariantIds:${productId}`;
    const cachedValue = await this.cacheService.get(cacheKey);
    if (cachedValue) {
        return cachedValue;
    }
    const newValue = await this.expensiveOperation(productId);
    await this.cacheService.set(cacheKey, newValue, { ttl: 60 * 1000 });
    return newValue;
}
```

### Cache eviction

The cache is not infinite, and entries will be evicted after a certain time. The time-to-live (TTL)
of a cache entry can be set when calling `set()`. If no TTL is set, the cache entry will remain
in the cache indefinitely.

Cache entries can also be manually deleted using the `delete()` method:

```ts
await this.cacheService.delete(cacheKey);
```

### Cache tags

When setting a cache entry, you can also specify a list of tags. This allows you to invalidate
all cache entries which share a tag. For example, if you have a cache entry which is related to
a Product, you can tag it with the Product's ID. When the Product is updated, you can invalidate
all cache entries which are tagged with that Product ID.

```ts
const cacheKey = `ProductService.getVariantIds:${productId}`;

await this.cacheService.set(cacheKey, newValue, {
    tags: [`Product:${productId}`]
});

// later

await this.cacheService.invalidateTags([`Product:${productId}`]);
```

### createCache Helper

The `createCache` helper function can be used to create a [Cache](/reference/typescript-api/cache) instance
which is a convenience wrapper around the `CacheService` APIs:

```ts
import { Injectable } from '@nestjs/common';
import { CacheService, ID, EventBus, ProductEvent,RequestContext } from '@vendure/core';

@Injectable()
export class FacetValueChecker {
    // Create a Cache instance with a 1-day TTL
    private facetValueCache = this.cacheService.createCache({
        getKey: (productId: ID) => `FacetValueChecker.${productId}`,
        options: { ttl: 1000 * 60 * 60 * 24 },
    });

    constructor(private cacheService: CacheService, private eventBus: EventBus) {
        this.eventBus.ofType(ProductEvent).subscribe(event => {
            if (event.type !== 'created') {
                // Invalidate the cache entry when a Product is updated or deleted
                this.facetValueCache.delete(event.entity.id);
            }
        });
    }

    async getFacetValueIdsForProduct(ctx: RequestContext, productId: ID): Promise<ID[]> {
        return this.facetValueCache.get(productId, () =>
            // This function will only be called if the cache entry does not exist
            // or has expired. It will set the result in the cache automatically.
            this.calculateFacetValueIdsForProduct(ctx, productId));
    }

    async calculateFacetValueIdsForProduct(ctx: RequestContext, productId: ID): Promise<ID[]> {
        // Do something expensive
    }
}
```

## RequestContextCache

The [RequestContextCacheService](/reference/typescript-api/cache/request-context-cache-service) is a specialized
cache service which is scoped to the current request. This is useful when you want to cache data
for the duration of a single request, but not across multiple requests.

This can be especially useful in resolvers, where you may want to cache the result of a specific resolved
field which may be requested multiple times within the same request.

For example, in Vendure core, when dealing with product lists, there's a particular very hot
code path that is used to calculate the correct prices to return for each product. As part of this
calculation, we need to know the active tax zone, which can be expensive to calculate newly
for each product. We use the `RequestContextCacheService` to cache the active tax zone for the
duration of the request.

```ts
const activeTaxZone = await this.requestContextCache.get(
    ctx,
    'activeTaxZone',
    () => taxZoneStrategy
        .determineTaxZone(ctx, zones, ctx.channel, order),
);
```

Internally, the `RequestContextCacheService` makes used of the WeakMap data structure which means the cached
data will be automatically garbage-collected when the request is finished. It is also able to store
any kind of data, not just serializable data.

## Session Cache

There is an additional cache which is specifically used to cache session data, since this data is commonly
accessed on almost all requests. Since v3.1, the default is to use the [DefaultSessionCacheStrategy](/reference/typescript-api/auth/default-session-cache-strategy)
which internally just uses whatever the current `CacheStrategy` is to store the data.

This means that in most cases you don't need to worry about the session cache, but if you have specific
requirements, you can create a custom session cache strategy and set it via the `authOptions.sessionCacheStrategy`
config property.

## SelfRefreshingCache
The [SelfRefreshingCache](/reference/typescript-api/cache/self-refreshing-cache) is a specialized in-memory cache which automatically
refreshes itself if the value is found to be stale. This is useful to cache a single frequently-accessed value, that don't change often.

It is created using the [createSelfRefreshingCache](/reference/typescript-api/cache/self-refreshing-cache#createselfrefreshingcache) function, which takes a configuration object that specifies the
name of the cache, the time-to-live (TTL) for the cache entries, and a refresh function that will be called to update the value when it is stale.

```ts title="SelfRefreshingCache Example"
import {
  Channel,
  createSelfRefreshingCache,
  EventBus,
  InitializerEvent,
  InternalServerError,
  Logger,
  RequestContext
  SelfRefreshingCache,
  TransactionalConnection,
} from '@vendure/core';

@Injectable()
export class PublicChannelService {
// highlight-start
  private publicChannel: SelfRefreshingCache<Channel, [RequestContext]>;
// highlight-end
  private readonly logCtx = 'PublicChannelService';

  constructor(
    private connection: TransactionalConnection,
    private eventBus: EventBus,
  ) {
    this.eventBus.ofType(InitializerEvent).subscribe(async () => {
      // highlight-start
      this.publicChannel = await createSelfRefreshingCache({
        name: 'PublicChannelService.publicChannel',
        ttl: 1000 * 60 * 5, // 5min
        refresh: { fn: ctx => this.findPublicChannel(ctx), defaultArgs: [RequestContext.empty()] },
      });
      // highlight-end
    });
  }

  async getPublicChannel(): Promise<Channel> {
    // highlight-start
    const publicChannel = await this.publicChannel.value();
    // highlight-end
    if (!publicChannel) {
      throw new InternalServerError(`error.public-channel-not-found`);
    }
    return publicChannel;
  }

  private async findPublicChannel(ctx: RequestContext): Promise<Channel> {
    const publicChannel = await this.connection.getRepository(ctx, Channel).findOne({
      where: { code: DEFAULT_PUBLIC_CHANNEL_CODE },
      relations: ['defaultShippingZone', 'defaultTaxZone'],
    });

    if (!publicChannel) {
      Logger.error('Could not find public channel!', this.logCtx);
      throw new InternalServerError(`error.public-channel-not-found`);
    }
    return publicChannel;
  }
}
```

---

---
title: "Implementing ChannelAware"
showtoc: true
---

## Defining channel-aware entities

Making an entity channel-aware means that it can be associated with a specific [Channel](/reference/typescript-api/entities/channel).
This is useful when you want to have different data or features for different channels. First you will have to create
an entity ([Define a database entity](/guides/developer-guide/database-entity/)) that implements the `ChannelAware` interface.
This interface requires the entity to provide a `channels` property

```ts title="src/plugins/requests/entities/product-request.entity.ts"
import { DeepPartial } from '@vendure/common/lib/shared-types';
import { VendureEntity, Product, EntityId, ID, ChannelAware } from '@vendure/core';
import { Column, Entity, ManyToOne } from 'typeorm';

@Entity()
class ProductRequest extends VendureEntity implements ChannelAware {
    constructor(input?: DeepPartial<ProductRequest>) {
        super(input);
    }

    @ManyToOne(type => Product)
    product: Product;

    @EntityId()
    productId: ID;

    @Column()
    text: string;
    
    // highlight-start
    @ManyToMany(() => Channel)
    @JoinTable()
    channels: Channel[];
    // highlight-end
}
```

## Creating channel-aware entities

Creating a channel-aware entity is similar to creating a regular entity. The only difference is that you need to assign the entity to the current channel.
This can be done by using the `ChannelService` which provides the `assignToCurrentChannel` helper function. 

:::info
The `assignToCurrentChannel` function will only assign the `channels` property of the entity. You will still need to save the entity to the database.
:::

```ts title="src/plugins/requests/service/product-request.service.ts"
import { ChannelService } from '@vendure/core';

export class RequestService {

    constructor(private channelService: ChannelService) {}

    async create(ctx: RequestContext, input: CreateRequestInput): Promise<ProductRequest> {
        const request = new ProductRequest(input);
        // Now we need to assign the request to the current channel (+ default channel)
// highlight-next-line
        await this.channelService.assignToCurrentChannel(input, ctx);
        
        return await this.connection.getRepository(ProductRequest).save(request);
    }
}
```
For [Translatable entities](/guides/developer-guide/translations/), the best place to assign the channels is inside the `beforeSave` input of the [TranslateableSave](/reference/typescript-api/service-helpers/translatable-saver/) helper class.


## Querying channel-aware entities

When querying channel-aware entities, you can use the [ListQueryBuilder](/reference/typescript-api/data-access/list-query-builder/#extendedlistqueryoptions) or
the [TransactionalConnection](/reference/typescript-api/data-access/transactional-connection/#findoneinchannel) to automatically filter entities based on the provided channel id.


```ts title="src/plugins/requests/service/product-request.service.ts"
import { ChannelService, ListQueryBuilder, TransactionalConnection } from '@vendure/core';

export class RequestService {

    constructor(
        private connection: TransactionalConnection,
        private listQueryBuilder: ListQueryBuilder,
        private channelService: ChannelService) {}

    findOne(ctx: RequestContext,
            requestId: ID,
            relations?: RelationPaths<ProductRequest>) {
// highlight-start
        return this.connection.findOneInChannel(ctx, ProductRequest, requestId, ctx.channelId, {
            relations: unique(effectiveRelations)
        });
// highlight-end
    }

    findAll(
        ctx: RequestContext,
        options?: ProductRequestListOptions,
        relations?: RelationPaths<ProductRequest>,
    ): Promise<PaginatedList<ProductRequest>> {
        return this.listQueryBuilder
            .build(ProductRequest, options, {
                ctx,
                relations,
// highlight-next-line
                channelId: ctx.channelId,
            })
            .getManyAndCount()
            .then(([items, totalItems]) => {
                return {
                    items,
                    totalItems,
                };
            });
    }
}
```


---

---
title: "CLI"
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

The Vendure CLI is a command-line tool for boosting your productivity as a developer by automating common tasks
such as creating new plugins, entities, API extensions and more.

It is much more than just a scaffolding tool - it is able to analyze your project and intelligently modify your existing
codebase to integrate new functionality.

## Installation

:::info
The Vendure CLI comes installed with a new Vendure project by default from v2.2.0+
:::

To manually install the CLI, run:

<Tabs groupId="package-manager">
<TabItem value="npm" label="npm" default>

```bash
npm install -D @vendure/cli
```

</TabItem>
<TabItem value="yarn" label="yarn">

```bash
yarn add -D @vendure/cli
```

</TabItem>
</Tabs>

## Interactive vs Non-Interactive Mode

The Vendure CLI supports both **interactive** and **non-interactive** modes:

- **Interactive mode**: Provides guided prompts and menus for easy use during development
- **Non-interactive mode**: Allows direct command execution with arguments and options, perfect for automation, CI/CD, and AI agents

## The Add Command

The `add` command is used to add new entities, resolvers, services, plugins, and more to your Vendure project.

### Interactive Mode

From your project's **root directory**, run:

<Tabs groupId="package-manager">
<TabItem value="npm" label="npm" default>

```bash
npx vendure add
```

</TabItem>
<TabItem value="yarn" label="yarn">

```bash
yarn vendure add
```

</TabItem>
</Tabs>

![Add command](./add-command.webp)

The CLI will guide you through the process of adding new functionality to your project. 

The `add` command is much more than a simple file generator. It is able to
analyze your project source code to deeply understand and correctly update your project files.

### Non-Interactive Mode

For automation or when you know exactly what you need to add, you can use the non-interactive mode with specific arguments and options:

<Tabs groupId="package-manager">
<TabItem value="npm" label="npm" default>

```bash
# Create a new plugin
npx vendure add -p MyPlugin

# Add an entity to a plugin
npx vendure add -e MyEntity --selected-plugin MyPlugin

# Add an entity with features
npx vendure add -e MyEntity --selected-plugin MyPlugin --custom-fields --translatable

# Add a service to a plugin
npx vendure add -s MyService --selected-plugin MyPlugin

# Add a service with specific type
npx vendure add -s MyService --selected-plugin MyPlugin --type entity

# Add job queue support to a plugin
npx vendure add -j MyPlugin --name my-job --selected-service MyService

# Add GraphQL codegen to a plugin
npx vendure add -c MyPlugin

# Add API extension to a plugin
npx vendure add -a MyPlugin --queryName getCustomData --mutationName updateCustomData

# Add UI extensions to a plugin
npx vendure add -u MyPlugin

# Use custom config file
npx vendure add -p MyPlugin --config ./custom-vendure.config.ts
```

</TabItem>
<TabItem value="yarn" label="yarn">

```bash
# Create a new plugin
yarn vendure add -p MyPlugin

# Add an entity to a plugin
yarn vendure add -e MyEntity --selected-plugin MyPlugin

# Add an entity with features
yarn vendure add -e MyEntity --selected-plugin MyPlugin --custom-fields --translatable

# Add a service to a plugin
yarn vendure add -s MyService --selected-plugin MyPlugin

# Add a service with specific type
yarn vendure add -s MyService --selected-plugin MyPlugin --type entity

# Add job queue support to a plugin
yarn vendure add -j MyPlugin --name my-job --selected-service MyService

# Add GraphQL codegen to a plugin
yarn vendure add -c MyPlugin

# Add API extension to a plugin
yarn vendure add -a MyPlugin --queryName getCustomData --mutationName updateCustomData

# Add UI extensions to a plugin
yarn vendure add -u MyPlugin

# Use custom config file
yarn vendure add -p MyPlugin --config ./custom-vendure.config.ts
```

</TabItem>
</Tabs>

#### Add Command Options

| Flag | Long Form | Description | Example |
|------|-----------|-------------|---------|
| `-p` | `--plugin <n>` | Create a new plugin | `vendure add -p MyPlugin` |
| `-e` | `--entity <n>` | Add a new entity to a plugin | `vendure add -e MyEntity --selected-plugin MyPlugin` |
| `-s` | `--service <n>` | Add a new service to a plugin | `vendure add -s MyService --selected-plugin MyPlugin` |
| `-j` | `--job-queue [plugin]` | Add job queue support | `vendure add -j MyPlugin --name job-name --selected-service ServiceName` |
| `-c` | `--codegen [plugin]` | Add GraphQL codegen configuration | `vendure add -c MyPlugin` |
| `-a` | `--api-extension [plugin]` | Add API extension scaffold | `vendure add -a MyPlugin --queryName getName --mutationName setName` |
| `-u` | `--ui-extensions [plugin]` | Add UI extensions setup | `vendure add -u MyPlugin` |
| | `--config <path>` | Specify custom Vendure config file | `--config ./custom-config.ts` |

#### Sub-options for specific commands

**Entity (`-e`) additional options:**
- `--selected-plugin <n>`: Name of the plugin to add the entity to (required)
- `--custom-fields`: Add custom fields support to the entity
- `--translatable`: Make the entity translatable

**Service (`-s`) additional options:**
- `--selected-plugin <n>`: Name of the plugin to add the service to (required)
- `--type <type>`: Type of service: basic or entity (default: basic)

**Job Queue (`-j`) additional options:**
- `--name <name>`: Name for the job queue (required)
- `--selected-service <name>`: Service to add the job queue to (required)

**API Extension (`-a`) additional options: (requires either)**
- `--queryName <n>`: Name for the GraphQL query
- `--mutationName <n>`: Name for the GraphQL mutation

:::info
**Validation**: Entity and service commands validate that the specified plugin exists in your project. If the plugin is not found, the command will list all available plugins in the error message. Both commands require the `--selected-plugin` parameter when running in non-interactive mode.
:::

## The Migrate Command

The `migrate` command is used to generate and manage [database migrations](/guides/developer-guide/migrations) for your Vendure project.

### Interactive Mode

From your project's **root directory**, run:

<Tabs groupId="package-manager">
<TabItem value="npm" label="npm" default>

```bash
npx vendure migrate
```

</TabItem>
<TabItem value="yarn" label="yarn">

```bash
yarn vendure migrate
```

</TabItem>
</Tabs>

![Migrate command](./migrate-command.webp)

### Non-Interactive Mode

For migration operations, use specific arguments and options:

<Tabs groupId="package-manager">
<TabItem value="npm" label="npm" default>

```bash
# Generate a new migration
npx vendure migrate -g my-migration-name

# Run pending migrations
npx vendure migrate -r

# Revert the last migration
npx vendure migrate --revert

# Generate migration with custom output directory
npx vendure migrate -g my-migration -o ./custom/migrations
```

</TabItem>
<TabItem value="yarn" label="yarn">

```bash
# Generate a new migration
yarn vendure migrate -g my-migration-name

# Run pending migrations
yarn vendure migrate -r

# Revert the last migration
yarn vendure migrate --revert

# Generate migration with custom output directory
yarn vendure migrate -g my-migration -o ./custom/migrations
```

</TabItem>
</Tabs>

#### Migrate Command Options

| Flag | Long Form | Description | Example |
|------|-----------|-------------|---------|
| `-g` | `--generate <name>` | Generate a new migration | `vendure migrate -g add-user-table` |
| `-r` | `--run` | Run all pending migrations | `vendure migrate -r` |
| | `--revert` | Revert the last migration | `vendure migrate --revert` |
| `-o` | `--output-dir <path>` | Custom output directory for migrations | `vendure migrate -g my-migration -o ./migrations` |

## Getting Help

To see all available commands and options:

```bash
npx vendure --help
npx vendure add --help
npx vendure migrate --help
```


---

---
title: "Configuration"
sidebar_position: 3
---

# Configuration

Every aspect of the Vendure server is configured via a single, central [`VendureConfig`](/reference/typescript-api/configuration/vendure-config/) object. This object is passed into the [`bootstrap`](/reference/typescript-api/common/bootstrap/) and [`bootstrapWorker`](/reference/typescript-api/worker/bootstrap-worker/) functions to start up the Vendure server and worker respectively.

The `VendureConfig` object is organised into sections, grouping related settings together. For example, [`VendureConfig.apiOptions`](/reference/typescript-api/configuration/api-options/) contains all the config for the GraphQL APIs, whereas [`VendureConfig.authOptions`](/reference/typescript-api/auth/auth-options/) deals with authentication.

## Important Configuration Settings

In this guide, we will take a look at those configuration options needed for getting the server up and running.

:::tip
A description of every available configuration option can be found in the [`VendureConfig` reference docs](/reference/typescript-api/configuration/vendure-config/).
:::

### Specifying API hostname & port etc

The [`VendureConfig.apiOptions`](/reference/typescript-api/configuration/api-options/) object is used to set the hostname, port, as well as other API-related concerns. Express middleware and Apollo Server plugins may also be specified here.

Example:

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';

export const config: VendureConfig = {
  apiOptions: {
    hostname: 'localhost',
    port: 3000,
    adminApiPath: '/admin',
    shopApiPath: '/shop',
    middleware: [{
      // add some Express middleware to the Shop API route
      handler: timeout('5s'),
      route: 'shop',
    }]
  },
  // ...
}
```

### Connecting to the database

The database connection is configured with the `VendureConfig.dbConnectionOptions` object. This object is actually the [TypeORM DataSourceOptions object](https://typeorm.io/data-source-options) and is passed directly to TypeORM.

Example:

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';

export const config: VendureConfig = {
  dbConnectionOptions: {
    type: 'postgres',
    host: process.env.DB_HOST,
    port: process.env.DB_PORT,
    synchronize: false,
    username: process.env.DB_USERNAME,
    password: process.env.DB_PASSWORD,
    database: 'vendure',
    migrations: [path.join(__dirname, 'migrations/*.ts')],
  },
  // ...
}
```

### Configuring authentication

Authentication settings are configured with [`VendureConfig.authOptions`](/reference/typescript-api/auth/auth-options/). The most important setting here is whether the storefront client will use cookies or bearer tokens to manage user sessions. For more detail on this topic, see [the Managing Sessions guide](/guides/storefront/connect-api/#managing-sessions).

The username and default password of the superadmin user can also be specified here. In production, it is advisable to use environment variables for these settings (see the following section on usage of environment variables).

Example:

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';

export const config: VendureConfig = {
  authOptions: {
    tokenMethod: 'cookie',
    requireVerification: true,
    cookieOptions: {
      secret: process.env.COOKIE_SESSION_SECRET,
    },
    superadminCredentials: {
      identifier: process.env.SUPERADMIN_USERNAME,
      password: process.env.SUPERADMIN_PASSWORD,
    },
  },
  // ...
}
```

## Working with the VendureConfig object

Since the `VendureConfig` is just a JavaScript object, it can be managed and manipulated according to your needs. For example:

### Using environment variables

Environment variables can be used when you don't want to hard-code certain values which may change, e.g. depending on whether running locally, in staging or in production:

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';

export const config: VendureConfig = {
  apiOptions: {
    hostname: process.env.HOSTNAME,
    port: process.env.PORT,
  }
  // ...
};
```

They are also useful so that sensitive credentials do not need to be hard-coded and committed to source control:

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';

export const config: VendureConfig = {
  dbConnectionOptions: {
    type: 'postgres',
    username: process.env.DB_USERNAME,
    password: process.env.DB_PASSWORD,
    database: 'vendure',
  },
  // ...
}
```

When you create a Vendure project with `@vendure/create`, it comes with the [dotenv](https://www.npmjs.com/package/dotenv) package installed, which allows you to store environment variables in a `.env` file in the root of your project.

To define new environment variables, you can add them to the `.env` file. For instance, if you are using a plugin that requires
an API key, you can

```txt title=".env"
APP_ENV=dev
COOKIE_SECRET=toh8soqdlj
SUPERADMIN_USERNAME=superadmin
SUPERADMIN_PASSWORD=superadmin
// highlight-next-line
MY_API_KEY=12345
```

In order to tell TypeScript about the existence of this new variable, you can add it to the `src/environment.d.ts` file:

```ts title="src/environment.d.ts"
export {};

// Here we declare the members of the process.env object, so that we
// can use them in our application code in a type-safe manner.
declare global {
    namespace NodeJS {
        interface ProcessEnv {
            APP_ENV: string;
            COOKIE_SECRET: string;
            SUPERADMIN_USERNAME: string;
            SUPERADMIN_PASSWORD: string;
            // highlight-next-line
            MY_API_KEY: string;
        }
    }
}
````

You can then use the environment variable in your config file:

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';

export const config: VendureConfig = {
  plugins: [
    MyPlugin.init({
      apiKey: process.env.MY_API_KEY,
    }),
  ],
  // ...
}
```

:::info

In production, the way you manage environment variables will depend on your hosting provider. Read more about this in our [Production Configuration guide](/guides/deployment/production-configuration/).

:::



### Splitting config across files

If the config object grows too large, you can split it across several files. For example, the `plugins` array in a real-world project can easily grow quite big:

```ts title="src/vendure-config-plugins.ts"
import { AssetServerPlugin, DefaultJobQueuePlugin, VendureConfig } from '@vendure/core';
import { ElasticsearchPlugin } from '@vendure/elasticsearch-plugin';
import { EmailPlugin } from '@vendure/email-plugin';
import { CustomPlugin } from './plugins/custom-plugin';

export const plugins: VendureConfig['plugins'] = [
  CustomPlugin,
  AssetServerPlugin.init({
      route: 'assets',
      assetUploadDir: path.join(__dirname, 'assets'),
      port: 5002,
  }),
  DefaultJobQueuePlugin,
  ElasticsearchPlugin.init({
      host: 'localhost',
      port: 9200,
  }),
  EmailPlugin.init({
    // ...lots of lines of config
  }),
];
```

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';
import { plugins } from './vendure-config-plugins';

export const config: VendureConfig = {
  plugins,
  // ...
}
```


---

---
title: 'Custom Fields'
sidebar_position: 3
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import CustomFieldProperty from '@site/src/components/CustomFieldProperty';

Custom fields allow you to add your own custom data properties to almost every Vendure entity. The entities which may have custom fields defined are listed in the [CustomFields interface documentation](/reference/typescript-api/custom-fields/).

Some use-cases for custom fields include:

* Storing the weight, dimensions or other product-specific data on the `ProductVariant` entity.
* Storing additional product codes on the `ProductVariant` entity such as ISBN or GTIN.
* Adding a `downloadable` flag to the `Product` entity to indicate whether the product is a digital download.
* Storing an external identifier (e.g. from a payment provider) on the `Customer` entity.
* Adding a longitude and latitude to the `StockLocation` for use in selecting the closest location to a customer.

:::note
Custom fields are not solely restricted to Vendure's native entities though, it's also possible to add support for custom fields to your own custom entities. See: [Supporting custom fields](/guides/developer-guide/database-entity/#supporting-custom-fields)
:::

## Defining custom fields

Custom fields are specified in the VendureConfig:

```ts
const config = {
    // ...
    customFields: {
        Product: [
            { name: 'infoUrl', type: 'string' },
            { name: 'downloadable', type: 'boolean' },
            { name: 'shortName', type: 'localeString' },
        ],
        User: [
            { name: 'socialLoginToken', type: 'string', unique: true },
        ],
    },
};
```

With the example config above, the following will occur:

1. The database schema will be altered, and a column will be added for each custom field. **Note: changes to custom fields require a database migration**. See the [Migrations guide](/guides/developer-guide/migrations/).
2. The GraphQL APIs will be modified to add the custom fields to the `Product` and `User` types respectively.
3. If you are using the [AdminUiPlugin](/reference/core-plugins/admin-ui-plugin/), the Admin UI detail pages will now contain form inputs to allow the custom field data to be added or edited, and the list view data tables will allow custom field columns to be added, sorted and filtered.

![custom-fields-data-table.webp](custom-fields-data-table.webp)

The values of the custom fields can then be set and queried via the GraphQL APIs:


<Tabs>
<TabItem value="Request" label="Request" default>

```graphql
mutation {
    updateProduct(input: {
        id: 1
        // highlight-start
        customFields: {
        infoUrl: "https://some-url.com",
        downloadable: true,
        }
        // highlight-end
        translations: [
        // highlight-next-line
        { languageCode: en, customFields: { shortName: "foo" } }
        ]
        }) {
        id
        name
        // highlight-start
        customFields {
            infoUrl
            downloadable
            shortName
        }
        // highlight-end
    }
}
```

</TabItem>
<TabItem value="Response" label="Response">

```json
{
    "data": {
        "product": {
            "id": "1",
            "name": "Laptop",
            "customFields": {
                "infoUrl": "https://some-url.com",
                "downloadable": true,
                "shortName": "foo"
            }
        }
    }
}
```

</TabItem>
</Tabs>

The custom fields will also extend the filter and sort options available to the `products` list query:

```graphql
query {
    products(options: {
        // highlight-start
    filter: {
        infoUrl: { contains: "new" },
        downloadable: { eq: true }
        },
        sort: {
            infoUrl: ASC
        }
        // highlight-end
        }) {
        items {
            id
            name
            // highlight-start
            customFields {
                infoUrl
                downloadable
                shortName
            }
            // highlight-end
        }
    }
}
```

## Available custom field types

The following types are available for custom fields:

| Type           | Description                  | Example                                                  |
|----------------|------------------------------|----------------------------------------------------------|
| `string`       | Short string data            | url, label                                               |
| `localeString` | Localized short strings      | localized url                                            |
| `text`         | Long text data               | extended product info, json config object                |
| `localeText`   | Localized long text          | localized extended product info                          |
| `int`          | Integer                      | product weight, customer loyalty points, monetary values |
| `float`        | Floating point number        | product review rating                                    |
| `boolean`      | Boolean                      | isDownloadable flag on product                           |
| `datetime`     | A datetime                   | date that variant is back in stock                       |
| `struct`       | Structured json-like data    | Key-value attributes with additional data for products   |
| `relation`     | A relation to another entity | Asset used as a customer avatar, related Products        |

To see the underlying DB data type and GraphQL type used for each, see the [CustomFieldType doc](/reference/typescript-api/custom-fields/custom-field-type).

#### Relations

It is possible to set up custom fields that hold references to other entities using the `'relation'` type:

```ts
const config = {
    // ...
    customFields: {
        Customer: [
            {
                name: 'avatar',
                // highlight-start
                type: 'relation',
                entity: Asset,
                // highlight-end
            },
        ],
    },
};
```

In this example, we set up a many-to-one relationship from Customer to Asset, allowing us to specify an avatar image for each Customer. Relation custom fields are unique in that the input and output names are not the same - the input will expect an ID and will be named `'<field name>Id'` or `'<field name>Ids'` for list types.

```graphql
mutation {
    updateCustomer(input: {
        id: 1
        customFields: {
            avatarId: 42,
        }
    }) {
        id
        customFields {
            avatar {
                id
                name
                preview
            }
        }
    }
}
```

## Accessing custom fields in TypeScript

As well as exposing custom fields via the GraphQL APIs, you can also access them directly in your TypeScript code. This is useful for plugins which need to access custom field data.

Given the following custom field configuration:

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';

const config: VendureConfig = {
    // ...
    customFields: {
        Customer: [
            { name: 'externalId', type: 'string' },
            { name: 'avatar', type: 'relation', entity: Asset },
        ],
    },
};
```

the `externalId` will be available whenever you access a `Customer` entity:

```ts
const customer = await this.connection.getRepository(ctx, Customer).findOne({
    where: { id: 1 },
});
console.log(customer.externalId);
```

The `avatar` relation will require an explicit join to be performed in order to access the data, since it is not
eagerly loaded by default:

```ts
const customer = await this.connection.getRepository(ctx, Customer).findOne({
    where: { id: 1 },
    relations: {
        customFields: {
            avatar: true,
        }
    }
});
console.log(customer.avatar);
```

or if using the QueryBuilder API:

```ts
const customer = await this.connection.getRepository(ctx, Customer).createQueryBuilder('customer')
    .leftJoinAndSelect('customer.customFields.avatar', 'avatar')
    .where('customer.id = :id', { id: 1 })
    .getOne();
console.log(customer.avatar);
```

or using the EntityHydrator:

```ts
const customer = await this.customerService.findOne(ctx, 1);
await this.entityHydrator.hydrate(ctx, customer, { relations: ['customFields.avatar'] });
console.log(customer.avatar);
```

## Custom field config properties

### Common properties

All custom fields share some common properties:

- [`name`](#name)
- [`type`](#type)
- [`list`](#list)
- [`label`](#label)
- [`description`](#description)
- [`public`](#public)
- [`readonly`](#readonly)
- [`internal`](#internal)
- [`defaultValue`](#defaultvalue)
- [`nullable`](#nullable)
- [`unique`](#unique)
- [`validate`](#validate)
- [`requiresPermission`](#requirespermission)
- [`deprecated`](#deprecated)

#### name

<CustomFieldProperty required={true} type="string"/>

The name of the field. This is used as the column name in the database, and as the GraphQL field name. The name should not contain spaces and by convention should be camelCased.

```ts title="src/vendure-config.ts"
const config = {
    // ...
    customFields: {
        Product: [
            {
                // highlight-next-line
                name: 'infoUrl',
                type: 'string'
            },
        ]
    }
};
```

#### type

<CustomFieldProperty required={true} type="CustomFieldType" typeLink="/reference/typescript-api/custom-fields/custom-field-type"/>

The type of data that will be stored in the field.

#### list

<CustomFieldProperty required={false} type="boolean" />

If set to `true`, then the field will be an array of the specified type. Defaults to `false`.

```ts title="src/vendure-config.ts"
const config = {
    // ...
    customFields: {
        Product: [
            {
                name: 'infoUrls',
                type: 'string',
                // highlight-next-line
                list: true,
            },
        ]
    }
};
```

Setting a custom field to be a list has the following effects:

* The GraphQL type will be an array of the specified type.
* The Admin UI will display a list of inputs for the field.
* For lists of primitive types (anything except `relation`), the database type will be set to `simple-json` which serializes the data into a JSON string. For lists of `relation` types, a separate many-to-many table will be created.

#### label

<CustomFieldProperty required={false} type="LocalizedStringArray" typeLink="/reference/typescript-api/configurable-operation-def/localized-string-array"/>

An array of localized labels for the field. These are used in the Admin UI to label the field.

```ts title="src/vendure-config.ts"
import { LanguageCode } from '@vendure/core';

const config = {
    // ...
    customFields: {
        Product: [
            {
                name: 'infoUrl',
                type: 'string',
                // highlight-start
                label: [
                    { languageCode: LanguageCode.en, value: 'Info URL' },
                    { languageCode: LanguageCode.de, value: 'Info-URL' },
                    { languageCode: LanguageCode.es, value: 'URL de información' },
                ],
                // highlight-end
            },
        ]
    }
};
```

#### description

<CustomFieldProperty required={false} type="LocalizedStringArray" typeLink="/reference/typescript-api/configurable-operation-def/localized-string-array"/>

An array of localized descriptions for the field. These are used in the Admin UI to describe the field.

```ts title="src/vendure-config.ts"
import { LanguageCode } from '@vendure/core';

const config = {
    // ...
    customFields: {
        Product: [
            {
                name: 'infoUrl',
                type: 'string',
                // highlight-start
                description: [
                    { languageCode: LanguageCode.en, value: 'A URL to more information about the product' },
                    { languageCode: LanguageCode.de, value: 'Eine URL zu weiteren Informationen über das Produkt' },
                    { languageCode: LanguageCode.es, value: 'Una URL con más información sobre el producto' },
                ],
                // highlight-end
            },
        ]
    }
};
```

#### public

<CustomFieldProperty required={false} type="boolean" />

Whether the custom field is available via the Shop API. Defaults to `true`.

```ts title="src/vendure-config.ts"
const config = {
    // ...
    customFields: {
        Product: [
            {
                name: 'profitMargin',
                type: 'int',
                // highlight-next-line
                public: false,
            },
        ]
    }
};
```

#### readonly

<CustomFieldProperty required={false} type="boolean" />

Whether the custom field can be updated via the GraphQL APIs. Defaults to `false`. If set to `true`, then the field
can only be updated via direct manipulation via TypeScript code in a plugin.

```ts title="src/vendure-config.ts"
const config = {
    // ...
    customFields: {
        Product: [
            {
                name: 'profitMargin',
                type: 'int',
                // highlight-next-line
                readonly: true,
            },
        ]
    }
};
```

#### internal

<CustomFieldProperty required={false} type="boolean" />

Whether the custom field is exposed at all via the GraphQL APIs. Defaults to `false`. If set to `true`, then the field will not be available
via the GraphQL API, but can still be used in TypeScript code in a plugin. Internal fields are useful for storing data which is not intended
to be exposed to the outside world, but which can be used in plugin logic.

```ts title="src/vendure-config.ts"
const config = {
    // ...
    customFields: {
        OrderLine: [
            {
                name: 'referralId',
                type: 'string',
                // highlight-next-line
                internal: true,
            },
        ]
    }
};
```

#### defaultValue

<CustomFieldProperty required={false} type="any" />

The default value when an Entity is created with this field. If not provided, then the default value will be `null`. Note that if you set `nullable: false`, then
you should also provide a `defaultValue` to avoid database errors when creating new entities.

```ts title="src/vendure-config.ts"
const config = {
    // ...
    customFields: {
        Product: [
            {
                name: 'reviewRating',
                type: 'float',
                // highlight-next-line
                defaultValue: 0,
            },
        ]
    }
};
```

#### nullable

<CustomFieldProperty required={false} type="boolean" />

Whether the field is nullable in the database. If set to `false`, then a `defaultValue` should be provided.

```ts title="src/vendure-config.ts"
const config = {
    // ...
    customFields: {
        Product: [
            {
                name: 'reviewRating',
                type: 'float',
                // highlight-start
                nullable: false,
                defaultValue: 0,
                // highlight-end
            },
        ]
    }
};
```

#### unique

<CustomFieldProperty required={false} type="boolean" />

Whether the value of the field should be unique. When set to `true`, a UNIQUE constraint is added to the column. Defaults
to `false`.

```ts title="src/vendure-config.ts"
const config = {
    // ...
    customFields: {
        Customer: [
            {
                name: 'externalId',
                type: 'string',
                // highlight-next-line
                unique: true,
            },
        ]
    }
};
```

#### validate

<CustomFieldProperty required={false} type="(value: any, injector: Injector, ctx: RequestContext) => string | LocalizedString[] | void" />

A custom validation function. If the value is valid, then the function should not return a value. If a string or LocalizedString array is returned, this is interpreted as an error message.

Note that string, number and date fields also have some built-in validation options such as `min`, `max`, `pattern` which you can read about in the following sections.

```ts title="src/vendure-config.ts"
import { LanguageCode } from '@vendure/core';

const config = {
    // ...
    customFields: {
        Product: [
            {
                name: 'infoUrl',
                type: 'string',
                // highlight-start
                validate: (value: any) => {
                    if (!value.startsWith('http')) {
                        // If a localized error message is not required, a simple string can be returned.
                        // return 'The URL must start with "http"';

                        // If a localized error message is required, return an array of LocalizedString objects.
                        return [
                            { languageCode: LanguageCode.en, value: 'The URL must start with "http"' },
                            { languageCode: LanguageCode.de, value: 'Die URL muss mit "http" beginnen' },
                            { languageCode: LanguageCode.es, value: 'La URL debe comenzar con "http"' },
                        ];
                    }
                },
                // highlight-end
            },
        ]
    }
};
```

This function can even be asynchronous and may use the [Injector](/reference/typescript-api/common/injector/) to access providers.

```ts title="src/vendure-config.ts"
const config = {
    // ...
    customFields: {
        ProductVariant: [
            {
                name: 'partCode',
                type: 'string',
                // highlight-start
                validate: async (value, injector, ctx) => {
                    const partCodeService = injector.get(PartCodeService);
                    const isValid = await partCodeService.validateCode(value);
                    if (!isValid) {
                        return `Part code ${value} is not valid`;
                    }
                },
                // highlight-end
            },
        ]
    }
};
```

#### requiresPermission

<CustomFieldProperty required={false} type="Permission | Permission[] | string | string[]" />

Since v2.2.0, you can restrict access to custom field data by specifying a permission or permissions which are required to read and update the field.
For instance, you might want to add a particular custom field to the `Product` entity, but you do not want all administrators to be able
to view or update the field.

In the Admin UI, the custom field will not be displayed if the current administrator lacks the required permission.

In the GraphQL API, if the current user does not have the required permission, then the field will always return `null`.
Attempting to set the value of a field for which the user does not have the required permission will cause the mutation to fail
with an error.

```ts title="src/vendure-config.ts"
import { Permission } from '@vendure/core';

const config = {
    // ...
    customFields: {
        Product: [
            {
                name: 'internalNotes',
                type: 'text',
                // highlight-start
                requiresPermission: Permission.SuperAdmin,
                // highlight-end
            },
            {
                name: 'shippingType',
                type: 'string',
                // highlight-start
                // You can also use an array of permissions, 
                // and the user must have at least one of the permissions
                // to access the field.
                requiresPermission: [
                    Permission.SuperAdmin,
                    Permission.ReadShippingMethod,
                ],
                // highlight-end
            },
        ]
    }
};
```

:::note

The `requiresPermission` property only affects the _Admin API_. Access to a custom field via the _Shop API_ is controlled by the `public` property.

If you need special logic to control access to a custom field in the Shop API, you can set `public: false` and then implement
a custom [field resolver](/guides/developer-guide/extend-graphql-api/#add-fields-to-existing-types) which contains the necessary logic, and returns
the entity's custom field value if the current customer meets the requirements.

:::

#### deprecated

<CustomFieldProperty required={false} type="boolean | string" />

Marks the custom field as deprecated in the GraphQL schema. When set to `true`, the field will be marked with the `@deprecated` directive. When set to a string, that string will be used as the deprecation reason.

This is useful for API evolution - you can mark fields as deprecated to signal to API consumers that they should migrate to newer alternatives, while still maintaining backward compatibility.

```ts title="src/vendure-config.ts"
const config = {
    // ...
    customFields: {
        Product: [
            {
                name: 'oldField',
                type: 'string',
                // highlight-next-line
                deprecated: true,
            },
            {
                name: 'legacyUrl',
                type: 'string',
                // highlight-next-line
                deprecated: 'Use the new infoUrl field instead',
            },
        ]
    }
};
```

When querying the GraphQL schema, deprecated fields will be marked accordingly:

```graphql
type ProductCustomFields {
    oldField: String @deprecated
    legacyUrl: String @deprecated(reason: "Use the new infoUrl field instead")
    infoUrl: String
}
```

### Properties for `string` fields

In addition to the common properties, the `string` custom fields have some type-specific properties:

- [`pattern`](#pattern)
- [`options`](#options)
- [`length`](#length)

#### pattern

<CustomFieldProperty required={false} type="string" />

A regex pattern which the field value must match. If the value does not match the pattern, then the validation will fail.

```ts title="src/vendure-config.ts"
const config = {
    // ...
    customFields: {
        ProductVariant: [
            {
                name: 'gtin',
                type: 'string',
                // highlight-next-line
                pattern: '^\d{8}(?:\d{4,6})?$',
            },
        ]
    }
};
```

#### options

<CustomFieldProperty required={false} type="{ value: string; label?: LocalizedString[]; }[]" />

An array of pre-defined options for the field. This is useful for fields which should only have a limited set of values. The `value` property is the value which will be stored in the database, and the `label` property is an optional array of localized strings which will be displayed in the admin UI.

```ts title="src/vendure-config.ts"
import { LanguageCode } from '@vendure/core';

const config = {
    // ...
    customFields: {
        ProductVariant: [
            {
                name: 'condition',
                type: 'string',
                // highlight-start
                options: [
                    { value: 'new', label: [{ languageCode: LanguageCode.en, value: 'New' }] },
                    { value: 'used', label: [{ languageCode: LanguageCode.en, value: 'Used' }] },
                ],
                // highlight-end
            },
        ]
    }
};
```

Attempting to set the value of the field to a value which is not in the `options` array will cause the validation to fail.

#### length

<CustomFieldProperty required={false} type="number" />

The max length of the varchar created in the database. Defaults to 255. Maximum is 65,535.

```ts title="src/vendure-config.ts"
const config = {
    // ...
    customFields: {
        ProductVariant: [
            {
                name: 'partCode',
                type: 'string',
                // highlight-next-line
                length: 20,
            },
        ]
    }
};
```

### Properties for `localeString` fields

In addition to the common properties, the `localeString` custom fields have some type-specific properties:

- [`pattern`](#pattern-1)
- [`length`](#length-1)

#### pattern

<CustomFieldProperty required={false} type="string" />

Same as the `pattern` property for `string` fields.

#### length

<CustomFieldProperty required={false} type="number" />

Same as the `length` property for `string` fields.

### Properties for `int` & `float` fields

In addition to the common properties, the `int` & `float` custom fields have some type-specific properties:

- [`min`](#min)
- [`max`](#max)
- [`step`](#step)

#### min

<CustomFieldProperty required={false} type="number" />

The minimum permitted value. If the value is less than this, then the validation will fail.

```ts title="src/vendure-config.ts"
const config = {
    // ...
    customFields: {
        ProductVariant: [
            {
                name: 'reviewRating',
                type: 'int',
                // highlight-next-line
                min: 0,
            },
        ]
    }
};
```

#### max

<CustomFieldProperty required={false} type="number" />

The maximum permitted value. If the value is greater than this, then the validation will fail.

```ts title="src/vendure-config.ts"
const config = {
    // ...
    customFields: {
        ProductVariant: [
            {
                name: 'reviewRating',
                type: 'int',
                // highlight-next-line
                max: 5,
            },
        ]
    }
};
```

#### step

<CustomFieldProperty required={false} type="number" />

The step value. This is used in the Admin UI to determine the increment/decrement value of the input field.

```ts title="src/vendure-config.ts"
const config = {
    // ...
    customFields: {
        ProductVariant: [
            {
                name: 'reviewRating',
                type: 'int',
                // highlight-next-line
                step: 0.5,
            },
        ]
    }
};
```

### Properties for `datetime` fields

In addition to the common properties, the `datetime` custom fields have some type-specific properties.
The min, max & step properties for datetime fields are intended to be used as described in
[the MDN datetime-local docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/datetime-local#Additional_attributes)

- [`min`](#min-1)
- [`max`](#max-1)
- [`step`](#step-1)

#### min

<CustomFieldProperty required={false} type="string" />

The earliest permitted date. If the value is earlier than this, then the validation will fail.

```ts title="src/vendure-config.ts"
const config = {
    // ...
    customFields: {
        ProductVariant: [
            {
                name: 'releaseDate',
                type: 'datetime',
                // highlight-next-line
                min: '2019-01-01T00:00:00.000Z',
            },
        ]
    }
};
```

#### max

<CustomFieldProperty required={false} type="string" />

The latest permitted date. If the value is later than this, then the validation will fail.

```ts title="src/vendure-config.ts"
const config = {
    // ...
    customFields: {
        ProductVariant: [
            {
                name: 'releaseDate',
                type: 'datetime',
                // highlight-next-line
                max: '2019-12-31T23:59:59.999Z',
            },
        ]
    }
};
```

#### step

<CustomFieldProperty required={false} type="string" />

The step value. See [the MDN datetime-local docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/datetime-local#step) to understand how this is used.

### Properties for `struct` fields

:::info
The `struct` custom field type is available from Vendure v3.1.0.
:::

In addition to the common properties, the `struct` custom fields have some type-specific properties:

- [`fields`](#fields)

#### fields

<CustomFieldProperty required={true} type="StructFieldConfig[]" typeLink="/reference/typescript-api/custom-fields/struct-field-config" />

A `struct` is a data structure comprising a set of named fields, each with its own type. The `fields` property is an array of `StructFieldConfig` objects, each of which defines a field within the struct.

```ts title="src/vendure-config.ts"
const config = {
    // ...
    customFields: {
        Product: [
            {
                name: 'dimensions',
                type: 'struct',
                // highlight-start
                fields: [
                    { name: 'length', type: 'int' },
                    { name: 'width', type: 'int' },
                    { name: 'height', type: 'int' },
                ],
                // highlight-end
            },
        ]
    }
};
```

When querying the `Product` entity, the `dimensions` field will be an object with the fields `length`, `width` and `height`:

```graphql
query {
    product(id: 1) {
        customFields {
            dimensions {
                length
                width
                height
            }
        }
    }
}
```

Struct fields support many of the same properties as other custom fields, such as `list`, `label`, `description`, `validate`, `ui` and
type-specific properties such as `options` and `pattern` for string types.

:::note
The following properties are **not** supported for `struct` fields: `public`, `readonly`, `internal`, `defaultValue`, `nullable`, `unique`, `requiresPermission`.
:::

```ts title="src/vendure-config.ts"
import { LanguageCode } from '@vendure/core';

const config = {
    // ...
    customFields: {
        OrderLine: [
            {
                name: 'customizationOptions',
                type: 'struct',
                fields: [
                    {
                        name: 'color',
                        type: 'string',
                        // highlight-start
                        options: [
                            { value: 'red', label: [{ languageCode: LanguageCode.en, value: 'Red' }] },
                            { value: 'blue', label: [{ languageCode: LanguageCode.en, value: 'Blue' }] },
                        ],
                        // highlight-end
                    },
                    {
                        name: 'engraving',
                        type: 'string',
                        // highlight-start
                        validate: (value: any) => {
                            if (value.length > 20) {
                                return 'Engraving text must be 20 characters or fewer';
                            }
                        },
                    },
                    {
                        name: 'notifyEmailAddresses',
                        type: 'string',
                        // highlight-start
                        list: true,
                        // highlight-end
                    }
                ],
            },
        ]
    }
};
```

### Properties for `relation` fields

In addition to the common properties, the `relation` custom fields have some type-specific properties:

- [`entity`](#entity)
- [`eager`](#eager)
- [`graphQLType`](#graphqltype)
- [`inverseSide`](#inverseside)

#### entity

<CustomFieldProperty required={true} type="VendureEntity" typeLink="/reference/typescript-api/entities/vendure-entity" />


The entity which this custom field is referencing. This can be one of the built-in entities, or a custom entity. If the entity is a custom entity, it must extend the `VendureEntity` class.

```ts title="src/vendure-config.ts"
import { Product } from '\@vendure/core';

const config = {
    // ...
    customFields: {
        Product: [
            {
                name: 'relatedProducts',
                list: true,
                // highlight-next-line
                type: 'relation',
                // highlight-next-line
                entity: Product,
            },
        ]
    }
};
```

#### eager

<CustomFieldProperty required={false} type="boolean" />

Whether to [eagerly load](https://typeorm.io/#/eager-and-lazy-relations) the relation. Defaults to false. Note that eager loading has performance implications, so should only be used when necessary.

```ts title="src/vendure-config.ts"
import { Product } from '\@vendure/core';

const config = {
    // ...
    customFields: {
        Product: [
            {
                name: 'relatedProducts',
                list: true,
                type: 'relation',
                entity: Product,
                // highlight-next-line
                eager: true,
            },
        ]
    }
};
```

#### graphQLType

<CustomFieldProperty required={false} type="string" />

The name of the GraphQL type that corresponds to the entity. Can be omitted if the GraphQL type name is the same as the entity name, which is the case for all of the built-in entities.

```ts title="src/vendure-config.ts"
import { CmsArticle } from './entities/cms-article.entity';

const config = {
    // ...
    customFields: {
        Product: [
            {
                name: 'blogPosts',
                list: true,
                type: 'relation',
                entity: CmsArticle,
                // highlight-next-line
                graphQLType: 'BlogPost',
            },
        ]
    }
};
```

In the above example, the `CmsArticle` entity is being used as a related entity. However, the GraphQL type name is `BlogPost`, so we must specify this in the `graphQLType` property, otherwise Vendure will try to extend the GraphQL schema with reference to a non-existent "CmsArticle" type.

#### inverseSide

<CustomFieldProperty required={false} type="string | ((object: VendureEntity) => any)" />

Allows you to specify the [inverse side of the relation](https://typeorm.io/#inverse-side-of-the-relationship). Let's say you are adding a relation from `Product`
to a custom entity which refers back to the product. You can specify this inverse relation like so:

```ts title="src/vendure-config.ts"
import { Product } from '\@vendure/core';
import { ProductReview } from './entities/product-review.entity';

const config = {
    // ...
    customFields: {
        Product: [
            {
                name: 'reviews',
                list: true,
                type: 'relation',
                entity: ProductReview,
                // highlight-start
                inverseSide: (review: ProductReview) => review.product,
                // highlight-end
            },
        ]
    }
};
```

This then allows you to query the `ProductReview` entity and include the `product` relation:

```ts
const { productReviews } = await this.connection.getRepository(ProductReview).findOne({
    where: { id: 1 },
    relations: ['product'],
});
```

## Custom Field UI

In the Admin UI, an appropriate default form input component is used for each custom field type. The Admin UI comes with a set of ready-made form input components, but it is also possible to create custom form input components. The ready-made components are:

- `text-form-input`: A single-line text input
- `password-form-input`: A single-line password input
- `select-form-input`: A select input
- `textarea-form-input`: A multi-line textarea input
- `rich-text-form-input`: A rich text editor input that saves the content as HTML
- `json-editor-form-input`: A simple JSON editor input
- `html-editor-form-input`: A simple HTML text editor input
- `number-form-input`: A number input
- `currency-form-input`: A number input with currency formatting
- `boolean-form-input`: A checkbox input
- `date-form-input`: A date input
- `relation-form-input`: A generic entity relation input which allows an ID to be manually specified
- `customer-group-form-input`: A select input for selecting a CustomerGroup
- `facet-value-form-input`: A select input for selecting a FacetValue
- `product-selector-form-input`: A select input for selecting a Product from an autocomplete list
- `product-multi-form-input`: A modal dialog for selecting multiple Products or ProductVariants

#### Default form inputs

This table shows the default form input component used for each custom field type:

| Type                     | Form input component                                                                         |
|--------------------------|----------------------------------------------------------------------------------------------|
| `string`, `localeString` | `text-form-input` or, if options are defined, `select-form-input`                            |
| `text`, `localeText`     | `textarea-form-input`                                                                        |
| `int`, `float`           | `number-form-input`                                                                          |
| `boolean`                | `boolean-form-input`                                                                         |
| `datetime`               | `date-form-input`                                                                            |
| `relation`               | Depends on related entity, defaults to `relation-form-input` if no specific component exists |

:::info
**UI for relation type**

The Admin UI app has built-in selection components for "relation" custom fields that reference certain common entity types, such as Asset, Product, ProductVariant and Customer. If you are relating to an entity not covered by the built-in selection components, you will see a generic relation component which allows you to manually enter the ID of the entity you wish to select.

If the generic selector is not suitable, or is you wish to replace one of the built-in selector components, you can create a UI extension that defines a custom field control for that custom field. You can read more about this in the [custom form input guide](/guides/extending-the-admin-ui/custom-form-inputs/)
:::

### Specifying the input component

The defaults listed above can be overridden by using the `ui` property of the custom field config object. For example, if we want a number to be displayed as a currency input:

```ts title="src/vendure-config.ts"
const config = {
    // ...
    customFields: {
        ProductVariant: [
            {
                name: 'rrp',
                type: 'int',
                // highlight-next-line
                ui: { component: 'currency-form-input' },
            },
        ]
    }
}
```

Here's an example config demonstrating several ways to customize the UI controls for custom fields:

```ts
import { LanguageCode, VendureConfig } from '@vendure/core';

const config: VendureConfig = {
    // ...
    customFields: {
        Product: [
            // Rich text editor
            { name: 'additionalInfo', type: 'text', ui: { component: 'rich-text-form-input' } },
            // JSON editor
            { name: 'specs', type: 'text', ui: { component: 'json-editor-form-input' } },
            // Numeric with suffix
            {
                name: 'weight',
                type: 'int',
                ui: { component: 'number-form-input', suffix: 'g' },
            },
            // Currency input
            {
                name: 'RRP',
                type: 'int',
                ui: { component: 'currency-form-input' },
            },
            // Select with options
            {
                name: 'pageType',
                type: 'string',
                ui: {
                    component: 'select-form-input',
                    options: [
                        { value: 'static', label: [{ languageCode: LanguageCode.en, value: 'Static' }] },
                        { value: 'dynamic', label: [{ languageCode: LanguageCode.en, value: 'Dynamic' }] },
                    ],
                },
            },
            // Text with prefix
            {
                name: 'link',
                type: 'string',
                ui: {
                    component: 'text-form-input',
                    prefix: 'https://',
                },
            },
        ],
    },
};
```

and the resulting UI:

![custom-fields-ui.webp](custom-fields-ui.webp)

:::info

The various configuration options for each of the built-in form input  (e.g. `suffix`) is documented in the [`DefaultFormConfigHash` object](/reference/typescript-api/configurable-operation-def/default-form-config-hash/).

:::

### Custom form input components

If none of the built-in form input components are suitable, you can create your own. This is a more advanced topic which is covered in detail in the [Custom Form Input Components](/guides/extending-the-admin-ui/custom-form-inputs/) guide.

## Tabbed custom fields

With a large, complex project, it's common for lots of custom fields to be required. This can get visually noisy in the UI, so Vendure supports tabbed custom fields. Just specify the tab name in the `ui` object, and those fields with the same tab name will be grouped in the UI! The tab name can also be a translation token if you need to support multiple languages.

:::note

Tabs will only be displayed if there is more than one tab name used in the custom fields. A lack of a `tab` property is counted as a tab (the "general" tab).

:::

```ts title="src/vendure-config.ts"
const config = {
    // ...
    customFields: {
        Product: [
            { name: 'additionalInfo', type: 'text', ui: { component: 'rich-text-form-input' } },
            { name: 'specs', type: 'text', ui: { component: 'json-editor-form-input' } },
            { name: 'width', type: 'int', ui: { tab: 'Shipping' } },
            { name: 'height', type: 'int', ui: { tab: 'Shipping' } },
            { name: 'depth', type: 'int', ui: { tab: 'Shipping' } },
            { name: 'weight', type: 'int', ui: { tab: 'Shipping' } },
        ],
    },
}
```

## TypeScript Typings

Because custom fields are generated at run-time, TypeScript has no way of knowing about them based on your
VendureConfig. Consider the example above - let's say we have a [plugin](/guides/developer-guide/plugins/) which needs to
access the custom field values on a Product entity.

Attempting to access the custom field will result in a TS compiler error:

```ts {hl_lines=[12,13]}
import { RequestContext, TransactionalConnection, ID, Product } from '@vendure/core';

export class MyService {
    constructor(private connection: TransactionalConnection) {
    }

    async getInfoUrl(ctx: RequestContext, productId: ID) {
        const product = await this.connection
            .getRepository(ctx, Product)
            .findOne(productId);

        return product.customFields.infoUrl;
    }                           // ^ TS2339: Property 'infoUrl'
}                             // does not exist on type 'CustomProductFields'.
```

The "easy" way to solve this is to assert the `customFields` object as `any`:

```ts
return (product.customFields as any).infoUrl;
```

However, this sacrifices type safety. To make our custom fields type-safe we can take advantage of a couple of more advanced TypeScript features - [declaration merging](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#merging-interfaces) and [ambient modules](https://www.typescriptlang.org/docs/handbook/modules.html#ambient-modules). This allows us to extend the built-in `CustomProductFields` interface to add our custom fields to it:

```ts
// types.ts

// Note: we are using a deep import here, rather than importing from `@vendure/core` due to
// a possible bug in TypeScript (https://github.com/microsoft/TypeScript/issues/46617) which
// causes issues when multiple plugins extend the same custom fields interface.
import { CustomProductFields } from '@vendure/core/dist/entity/custom-entity-fields';

declare module '@vendure/core/dist/entity/custom-entity-fields' {
    interface CustomProductFields {
        infoUrl: string;
        downloadable: boolean;
        shortName: string;
    }
}
```

When this file is then imported into our service file (either directly or indirectly), TypeScript will know about our custom fields, and we do not need to do any type assertions.

```ts
return product.customFields.infoUrl;
// no error, plus TS autocomplete works.
```

:::caution
Note that for the typings to work correctly, **order of imports matters**.

One way to ensure that your custom field typings always get imported first is to include them as the first item in the tsconfig "include" array.
:::

:::tip
For a working example of this setup, see the [real-world-vendure repo](https://github.com/vendure-ecommerce/real-world-vendure/blob/master/src/plugins/reviews/types.ts)
:::

## Special cases

Beyond adding custom fields to the corresponding GraphQL types, and updating paginated list sort & filter options, there are a few special cases where adding custom fields to certain entities will result in further API changes.

### OrderLine custom fields

When you define custom fields on the `OrderLine` entity, the following API changes are also automatically provided by Vendure:

- Shop API: [addItemToOrder](/reference/graphql-api/shop/mutations#additemtoorder) will have a 3rd input argument, `customFields`, which allows custom field values to be set when adding an item to the order.
- Shop API: [adjustOrderLine](/reference/graphql-api/shop/mutations#additemtoorder) will have a 3rd input argument, `customFields`, which allows custom field values to be updated.
- Admin API: the equivalent mutations for manipulating draft orders and for modifying and order will also have inputs to allow custom field values to be set.

:::info
To see an example of this in practice, see the [Configurable Product guide](/guides/how-to/configurable-products/)
:::

### Order custom fields

When you define custom fields on the `Order` entity, the following API changes are also automatically provided by Vendure:

- Admin API: [modifyOrder](/reference/graphql-api/admin/mutations#modifyorder) will have a `customFields` field on the input object.

### ShippingMethod custom fields

When you define custom fields on the `ShippingMethod` entity, the following API changes are also automatically provided by Vendure:

- Shop API: [eligibleShippingMethods](/reference/graphql-api/shop/queries#eligibleshippingmethods) will have public custom fields available on the result.

### PaymentMethod custom fields

When you define custom fields on the `PaymentMethod` entity, the following API changes are also automatically provided by Vendure:

- Shop API: [eligiblePaymentMethods](/reference/graphql-api/shop/queries#eligiblepaymentmethods) will have public custom fields available on the result.

### Customer custom fields

When you define custom fields on the `Customer` entity, the following API changes are also automatically provided by Vendure:

- Shop API: [registerCustomerAccount](/reference/graphql-api/shop/mutations#registercustomeraccount) will have have a `customFields` field on the input
  object.



---

---
title: "Define custom permissions"
showtoc: true
---

Vendure uses a fine-grained access control system based on roles & permissions. This is described in detail in the [Auth guide](/guides/core-concepts/auth/). The built-in [`Permission` enum](/reference/typescript-api/common/permission/) includes a range of permissions to control create, read, update, and delete access to the built-in entities.

When building plugins, you may need to define new permissions to control access to new functionality. This guide explains how to do so.

## Defining a single permission

For example, let's imagine you are creating a plugin which exposes a new mutation that can be used by remote services to sync your inventory. First of all we will define the new permission using the [`PermissionDefinition`](/reference/typescript-api/auth/permission-definition/) class:

```ts title="src/plugins/inventory-sync/constants.ts"
import { PermissionDefinition } from '@vendure/core';

export const sync = new PermissionDefinition({
    name: 'SyncInventory',
    description: 'Allows syncing stock levels via Admin API'
});
```

This permission can then be used in conjuction with the [@Allow() decorator](/reference/typescript-api/request/allow-decorator/) to limit access to the mutation:

```ts title="src/plugins/inventory-sync/api/inventory-sync.resolver.ts"
import { Mutation, Resolver } from '@nestjs/graphql';
import { Allow } from '@vendure/core';
import { sync } from '../constants';

@Resolver()
export class InventorySyncResolver {

    // highlight-next-line
    @Allow(sync.Permission)
    @Mutation()
    syncInventory(/* ... */) {
        // ...
    }
}
```

Finally, the `sync` PermissionDefinition must be passed into the VendureConfig so that Vendure knows about this new custom permission:

```ts title="src/plugins/inventory-sync/inventory-sync.plugin.ts"
import gql from 'graphql-tag';
import { VendurePlugin } from '@vendure/core';

import { InventorySyncResolver } from './api/inventory-sync.resolver'
import { sync } from './constants';

@VendurePlugin({
    adminApiExtensions: {
        schema: gql`
            input InventoryDataInput {
              # omitted for brevity
            }
        
            extend type Mutation {
              syncInventory(input: InventoryDataInput!): Boolean!
            }
        `,
        resolvers: [InventorySyncResolver]
    },
    configuration: config => {
        // highlight-next-line
        config.authOptions.customPermissions.push(sync);
        return config;
    },
})
export class InventorySyncPlugin {}
```

On starting the Vendure server, this custom permission will now be visible in the Role detail view of the Admin UI, and can be assigned to Roles.

## Custom CRUD permissions

Quite often your plugin will define a new entity on which you must perform create, read, update and delete (CRUD) operations. In this case, you can use the [CrudPermissionDefinition](/reference/typescript-api/auth/permission-definition/#crudpermissiondefinition) which simplifies the creation of the set of 4 CRUD permissions. 

For example, let's imagine we are creating a plugin which adds a new entity called `ProductReview`. We can define the CRUD permissions like so:

```ts title="src/plugins/product-review/constants.ts"
import { CrudPermissionDefinition } from '@vendure/core';

export const productReviewPermission = new CrudPermissionDefinition('ProductReview');
```

These permissions can then be used in our resolver:

```ts title="src/plugins/product-review/api/product-review.resolver.ts"
import { Mutation, Resolver } from '@nestjs/graphql';
import { Allow, Transaction } from '@vendure/core';
import { productReviewPermission } from '../constants';

@Resolver()
export class ProductReviewResolver {

    // highlight-next-line
    @Allow(productReviewPermission.Read)
    @Query()
    productReviews(/* ... */) {
        // ...
    }
    
    // highlight-next-line
    @Allow(productReviewPermission.Create)
    @Mutation()
    @Transaction()
    createProductReview(/* ... */) {
        // ...
    }
    
    // highlight-next-line
    @Allow(productReviewPermission.Update)
    @Mutation()
    @Transaction()
    updateProductReview(/* ... */) {
        // ...
    }
    
    // highlight-next-line
    @Allow(productReviewPermission.Delete)
    @Mutation()
    @Transaction()
    deleteProductReview(/* ... */) {
        // ...
    }
}
```

Finally, the `productReview` CrudPermissionDefinition must be passed into the VendureConfig so that Vendure knows about this new custom permission:

```ts title="src/plugins/product-review/product-review.plugin.ts"
import gql from 'graphql-tag';
import { VendurePlugin } from '@vendure/core';

import { ProductReviewResolver } from './api/product-review.resolver'
import { productReviewPermission } from './constants';

@VendurePlugin({
    adminApiExtensions: {
        schema: gql`
            # omitted for brevity
        `,
        resolvers: [ProductReviewResolver]
    },
    configuration: config => {
        // highlight-next-line
        config.authOptions.customPermissions.push(productReviewPermission);
        return config;
    },
})
export class ProductReviewPlugin {}
```

## Custom permissions for custom fields

Since Vendure v2.2.0, it is possible to define custom permissions for custom fields. This is useful when you want to 
control access to specific custom fields on an entity. For example, imagine a "product reviews" plugin which adds a
`rating` custom field to the `Product` entity. 

You may want to restrict access to this custom field to only those roles which have permissions on the product review
plugin.

```ts title="src/plugins/product-review.plugin.ts"
import { VendurePlugin } from '@vendure/core';
import { productReviewPermission } from './constants';

@VendurePlugin({
    configuration: config => {
        config.authOptions.customPermissions.push(productReviewPermission);
        
        config.customFields.Product.push({
            name: 'rating',
            type: 'int',
            // highlight-start
            requiresPermission: [
                productReviewPermission.Read, 
                productReviewPermission.Update,
            ],
            // highlight-end
        });
        return config;
    },
})
export class ProductReviewPlugin {}
```

---

---
title: 'Custom Strategies in Plugins'
---

When building Vendure plugins, you often need to provide extensible, pluggable implementations for specific features. The **strategy pattern** is the perfect tool for this, allowing plugin users to customize behavior by providing their own implementations.

This guide shows you how to implement custom strategies in your plugins, following Vendure's established patterns and best practices.

## Overview

A strategy in Vendure is a way to provide a pluggable implementation of a particular feature. Custom strategies in plugins allow users to:

- Override default behavior with their own implementations
- Inject dependencies and services through the `init()` lifecycle method
- Clean up resources using the `destroy()` lifecycle method
- Configure the strategy through the plugin's init options

## Creating a Strategy Interface

First, define the interface that your strategy must implement. All strategy interfaces should extend `InjectableStrategy` to support dependency injection and lifecycle methods.

```ts title="src/strategies/my-custom-strategy.ts"
import { InjectableStrategy, RequestContext } from '@vendure/core';

export interface MyCustomStrategy extends InjectableStrategy {
    /**
     * Process some data and return a result
     */
    processData(ctx: RequestContext, data: any): Promise<string>;

    /**
     * Validate the input data
     */
    validateInput(data: any): boolean;
}
```

## Implementing a Default Strategy

Create a default implementation that users can extend or replace:

```ts title="src/strategies/default-my-custom-strategy.ts"
import { Injector, RequestContext, Logger } from '@vendure/core';
import { MyCustomStrategy } from './my-custom-strategy';
import { SomeOtherService } from '../services/some-other.service';
import { loggerCtx } from '../constants';

export class DefaultMyCustomStrategy implements MyCustomStrategy {
    private someOtherService: SomeOtherService;

    async init(injector: Injector): Promise<void> {
        // Inject dependencies during the init phase
        this.someOtherService = injector.get(SomeOtherService);

        // Perform any setup logic
        Logger.info('DefaultMyCustomStrategy initialized', loggerCtx);
    }

    async destroy(): Promise<void> {
        // Clean up resources if needed
        Logger.info('DefaultMyCustomStrategy destroyed', loggerCtx);
    }

    async processData(ctx: RequestContext, data: any): Promise<string> {
        // Validate input first
        if (!this.validateInput(data)) {
            throw new Error('Invalid input data');
        }

        // Use injected service to process data
        const result = await this.someOtherService.doSomething(ctx, data);
        // ... do something with the result
        return result;
    }

    validateInput(data: any): boolean {
        return data != null && typeof data === 'object';
    }
}
```

## Adding Strategy to Plugin Options

Define your plugin's initialization options to include the strategy:

```ts title="src/types.ts"
import { MyCustomStrategy } from './strategies/my-custom-strategy';

export interface MyPluginInitOptions {
    /**
     * Custom strategy for processing data
     * @default DefaultMyCustomStrategy
     */
    processingStrategy?: MyCustomStrategy;

    /**
     * Other plugin options
     */
    someOtherOption?: string;
}
```

## Configuring the Plugin

In your plugin definition, provide the default strategy and allow users to override it:

```ts title="src/my-plugin.ts"
import { PluginCommonModule, VendurePlugin, Injector } from '@vendure/core';
import { OnApplicationBootstrap, OnApplicationShutdown } from '@nestjs/common';
import { ModuleRef } from '@nestjs/core';

import { MY_PLUGIN_OPTIONS } from './constants';
import { MyPluginInitOptions } from './types';
import { DefaultMyCustomStrategy } from './strategies/default-my-custom-strategy';
import { MyPluginService } from './services/my-plugin.service';
import { SomeOtherService } from './services/some-other.service';

@VendurePlugin({
    imports: [PluginCommonModule],
    providers: [
        MyPluginService,
        SomeOtherService,
        {
            provide: MY_PLUGIN_OPTIONS,
            useFactory: () => MyPlugin.options,
        },
    ],
    configuration: config => {
        // You can also configure core Vendure strategies here if needed
        return config;
    },
    compatibility: '^3.0.0',
})
export class MyPlugin implements OnApplicationBootstrap, OnApplicationShutdown {
    static options: MyPluginInitOptions;

    constructor(private moduleRef: ModuleRef) {}

    static init(options: MyPluginInitOptions) {
        this.options = {
            // Provide default strategy if none specified
            processingStrategy: new DefaultMyCustomStrategy(),
            ...options,
        };
        return MyPlugin;
    }

    async onApplicationBootstrap() {
        await this.initStrategy();
    }

    async onApplicationShutdown() {
        await this.destroyStrategy();
    }

    private async initStrategy() {
        const strategy = MyPlugin.options.processingStrategy;
        if (strategy && typeof strategy.init === 'function') {
            const injector = new Injector(this.moduleRef);
            await strategy.init(injector);
        }
    }

    private async destroyStrategy() {
        const strategy = MyPlugin.options.processingStrategy;
        if (strategy && typeof strategy.destroy === 'function') {
            await strategy.destroy();
        }
    }
}
```

## Using the Strategy in Services

Access the strategy through dependency injection in your services:

```ts title="src/services/my-plugin.service.ts"
import { Injectable, Inject } from '@nestjs/common';
import { RequestContext } from '@vendure/core';

import { MY_PLUGIN_OPTIONS } from '../constants';
import { MyPluginInitOptions } from '../types';

@Injectable()
export class MyPluginService {
    constructor(@Inject(MY_PLUGIN_OPTIONS) private options: MyPluginInitOptions) {}

    async processUserData(ctx: RequestContext, userData: any): Promise<string> {
        // Delegate to the configured strategy
        return this.options.processingStrategy.processData(ctx, userData);
    }

    validateUserInput(data: any): boolean {
        return this.options.processingStrategy.validateInput(data);
    }
}
```

## User Implementation Example

Plugin users can now provide their own strategy implementations:

```ts title="src/my-custom-implementation.ts"
import { Injector, RequestContext, Logger } from '@vendure/core';
import { MyCustomStrategy } from '@my-org/my-plugin';
import { ExternalApiService } from './external-api.service';
import { loggerCtx } from '../constants';

export class CustomProcessingStrategy implements MyCustomStrategy {
    private externalApi: ExternalApiService;

    async init(injector: Injector): Promise<void> {
        this.externalApi = injector.get(ExternalApiService);

        // Initialize external API connection
        await this.externalApi.connect();
        Logger.info('Custom processing strategy initialized', loggerCtx);
    }

    async destroy(): Promise<void> {
        // Clean up external connections
        if (this.externalApi) {
            await this.externalApi.disconnect();
        }
        Logger.info('Custom processing strategy destroyed', loggerCtx);
    }

    async processData(ctx: RequestContext, data: any): Promise<string> {
        if (!this.validateInput(data)) {
            throw new Error('Invalid data format');
        }

        // Use external API for processing
        const result = await this.externalApi.processData(data);
        return `Processed: ${result}`;
    }

    validateInput(data: any): boolean {
        // Custom validation logic
        return data && data.type === 'custom' && data.value;
    }
}
```

## Plugin Configuration by Users

Users configure the plugin with their custom strategy:

```ts title="vendure-config.ts"
import { VendureConfig } from '@vendure/core';
import { MyPlugin } from '@my-org/my-plugin';
import { CustomProcessingStrategy } from './my-custom-implementation';

export const config: VendureConfig = {
    plugins: [
        MyPlugin.init({
            processingStrategy: new CustomProcessingStrategy(),
            someOtherOption: 'custom-value',
        }),
    ],
    // ... other config
};
```

## Strategy with Options

You can also create strategies that accept configuration options:

```ts title="src/strategies/configurable-strategy.ts"
import { Injector, RequestContext } from '@vendure/core';
import { MyCustomStrategy } from './my-custom-strategy';

export interface ConfigurableStrategyOptions {
    timeout: number;
    retries: number;
    apiKey: string;
}

export class ConfigurableStrategy implements MyCustomStrategy {
    constructor(private options: ConfigurableStrategyOptions) {}

    async init(injector: Injector): Promise<void> {
        // Use options during initialization
        console.log(`Strategy configured with timeout: ${this.options.timeout}ms`);
    }

    async destroy(): Promise<void> {
        // Cleanup logic
    }

    async processData(ctx: RequestContext, data: any): Promise<string> {
        // Use configuration options
        const timeout = this.options.timeout;
        const retries = this.options.retries;

        // Implementation using these options...
        return 'processed with options';
    }

    validateInput(data: any): boolean {
        return true;
    }
}
```

Usage:

```ts title="vendure-config.ts"
import { ConfigurableStrategy } from './strategies/configurable-strategy';

// In plugin configuration
MyPlugin.init({
    processingStrategy: new ConfigurableStrategy({
        timeout: 5000,
        retries: 3,
        apiKey: process.env.API_KEY,
    }),
});
```

## Multiple Strategies in One Plugin

For complex plugins, you might need multiple strategies:

```ts title="src/types.ts"
export interface ComplexPluginOptions {
    dataProcessingStrategy?: DataProcessingStrategy;
    validationStrategy?: ValidationStrategy;
    cacheStrategy?: CacheStrategy;
}
```

```ts title="src/complex-plugin.ts"
@VendurePlugin({
    // ... plugin config
})
export class ComplexPlugin implements OnApplicationBootstrap, OnApplicationShutdown {
    static options: ComplexPluginOptions;

    static init(options: ComplexPluginOptions) {
        this.options = {
            dataProcessingStrategy: new DefaultDataProcessingStrategy(),
            validationStrategy: new DefaultValidationStrategy(),
            cacheStrategy: new DefaultCacheStrategy(),
            ...options,
        };
        return ComplexPlugin;
    }

    async onApplicationBootstrap() {
        await this.initAllStrategies();
    }

    async onApplicationShutdown() {
        await this.destroyAllStrategies();
    }

    private async initAllStrategies() {
        const injector = new Injector(this.moduleRef);
        const strategies = [
            ComplexPlugin.options.dataProcessingStrategy,
            ComplexPlugin.options.validationStrategy,
            ComplexPlugin.options.cacheStrategy,
        ];

        for (const strategy of strategies) {
            if (strategy && typeof strategy.init === 'function') {
                await strategy.init(injector);
            }
        }
    }

    private async destroyAllStrategies() {
        const strategies = [
            ComplexPlugin.options.dataProcessingStrategy,
            ComplexPlugin.options.validationStrategy,
            ComplexPlugin.options.cacheStrategy,
        ];

        for (const strategy of strategies) {
            if (strategy && typeof strategy.destroy === 'function') {
                await strategy.destroy();
            }
        }
    }
}
```

## Best Practices

### 1. Always Extend InjectableStrategy

```ts
export interface MyStrategy extends InjectableStrategy {
    // ... strategy methods
}
```

### 2. Provide Sensible Defaults

Always provide a default implementation so users can use your plugin out-of-the-box:

```ts
static init(options: MyPluginOptions) {
    this.options = {
        myStrategy: new DefaultMyStrategy(),
        ...options,
    };
    return MyPlugin;
}
```

### 3. Handle Lifecycle Properly

Always implement proper init/destroy handling in your plugin:

```ts
async onApplicationBootstrap() {
    await this.initStrategies();
}

async onApplicationShutdown() {
    await this.destroyStrategies();
}
```

### 4. Use TypeScript for Better DX

Provide strong typing for better developer experience:

```ts
export interface MyStrategy extends InjectableStrategy {
    processData<T>(ctx: RequestContext, data: T): Promise<ProcessedResult<T>>;
}
```

### 5. Document Your Strategy Interface

Provide comprehensive JSDoc comments:

```ts
export interface MyStrategy extends InjectableStrategy {
    /**
     * @description
     * Processes the input data and returns a transformed result.
     * This method is called for each data processing request.
     *
     * @param ctx - The current request context
     * @param data - The input data to process
     * @returns Promise resolving to the processed result
     */
    processData(ctx: RequestContext, data: any): Promise<string>;
}
```

## Summary

Custom strategies in plugins provide a powerful way to make your plugins extensible and configurable. By following the patterns outlined in this guide, you can:

- Define clear strategy interfaces that extend `InjectableStrategy`
- Provide default implementations that work out-of-the-box
- Allow users to inject dependencies through the `init()` method
- Properly manage strategy lifecycle with `init()` and `destroy()` methods
- Enable users to provide their own implementations
- Support configuration options for strategies

This approach ensures your plugins are flexible, maintainable, and follow Vendure's established conventions.


---

---
title: "Define a database entity"
showtoc: true
---

:::cli
Use `npx vendure add` to easily add a new entity to a plugin.
:::

Your plugin can define new database entities to model the data it needs to store. For instance, a product
review plugin would need a way to store reviews. This would be done by defining a new database entity.

This example shows how new [TypeORM database entities](https://typeorm.io/entities) can be defined by plugins.

## Create the entity class

```ts title="src/plugins/reviews/entities/product-review.entity.ts"
import { DeepPartial } from '@vendure/common/lib/shared-types';
import { VendureEntity, Product, EntityId, ID } from '@vendure/core';
import { Column, Entity, ManyToOne } from 'typeorm';

@Entity()
class ProductReview extends VendureEntity {
    constructor(input?: DeepPartial<ProductReview>) {
        super(input);
    }

    @ManyToOne(type => Product)
    product: Product;
    
    @EntityId()
    productId: ID;

    @Column()
    text: string;

    @Column()
    rating: number;
}
```

:::note
Any custom entities *must* extend the [`VendureEntity`](/reference/typescript-api/entities/vendure-entity/) class.
:::

In this example, we are making use of the following TypeORM decorators:

* [`@Entity()`](https://typeorm.io/decorator-reference#entity) - defines the entity as a TypeORM entity. This is **required** for all entities. It tells TypeORM to create a new table in the database for this entity.
* [`@Column()`](https://typeorm.io/decorator-reference#column) - defines a column in the database table. The data type of the column is inferred from the TypeScript type of the property, but can be overridden by passing an options object to the decorator. The `@Column()` also supports many other options for defining the column, such as `nullable`, `default`, `unique`, `primary`, `enum` etc.
* [`@ManyToOne()`](https://typeorm.io/decorator-reference#manytoone) - defines a many-to-one relationship between this entity and another entity. In this case, many  `ProductReview` entities can be associated with a given `Product`. There are other types of relations that can be defined - see the [TypeORM relations docs](https://typeorm.io/relations).

There is an additional Vendure-specific decorator:

* [`@EntityId()`](/reference/typescript-api/configuration/entity-id-decorator) marks a property as the ID of another entity. In this case, the `productId` property is the ID of the `Product` entity. The reason that we have a special decorator for this is that Vendure supports both numeric and string IDs, and the `@EntityId()` decorator will automatically set the database column to be the correct type. This `productId` is not _necessary_, but it is a useful convention to allow access to the ID of the associated entity without having to perform a database join.

## Register the entity

The new entity is then passed to the `entities` array of the VendurePlugin metadata:

```ts title="src/plugins/reviews/reviews-plugin.ts"
import { VendurePlugin } from '@vendure/core';
import { ProductReview } from './entities/product-review.entity';

@VendurePlugin({
    // highlight-next-line
    entities: [ProductReview],
})
export class ReviewsPlugin {}
```

:::note
Once you have added a new entity to your plugin, and the plugin has been added to your VendureConfig plugins array, you must create a [database migration](/guides/developer-guide/migrations/) to create the new table in the database.
:::

## Using the entity

The new entity can now be used in your plugin code. For example, you might want to create a new product review when a customer submits a review via the storefront:

```ts title="src/plugins/reviews/services/review.service.ts"
import { Injectable } from '@nestjs/common';
import { RequestContext, Product, TransactionalConnection } from '@vendure/core';

import { ProductReview } from '../entities/product-review.entity';

@Injectable()
export class ReviewService {
    constructor(private connection: TransactionalConnection) {}

    async createReview(ctx: RequestContext, productId: string, rating: number, text: string) {
        const product = await this.connection.getEntityOrThrow(ctx, Product, productId);
        // highlight-start
        const review = new ProductReview({
            product,
            rating,
            text,
        });
        return this.connection.getRepository(ctx, ProductReview).save(review);
        // highlight-end
    }
}
```

## Available entity decorators

In addition to the decorators described above, there are many other decorators provided by TypeORM. Some commonly used ones are:

- [`@OneToOne()`](https://typeorm.io/decorator-reference#onetoone)
- [`@OneToMany()`](https://typeorm.io/decorator-reference#onetomany)
- [`@ManyToMany()`](https://typeorm.io/decorator-reference#manytomany)
- [`@Index()`](https://typeorm.io/decorator-reference#index)
- [`@Unique()`](https://typeorm.io/decorator-reference#unique)

There is also another Vendure-specific decorator for representing monetary values specifically:

- [`@Money()`](/reference/typescript-api/money/money-decorator): This works together with the [`MoneyStrategy`](/reference/typescript-api/money/money-strategy) to allow configurable control over how monetary values are stored in the database. For more information see the [Money & Currency guide](/guides/core-concepts/money/#the-money-decorator).

:::info
The full list of TypeORM decorators can be found in the [TypeORM decorator reference](https://typeorm.io/decorator-reference)
:::


## Corresponding GraphQL type

Once you have defined a new DB entity, it is likely that you want to expose it in your GraphQL API. Here's how to [define a new type in your GraphQL API](/guides/developer-guide/extend-graphql-api/#defining-a-new-type).

## Supporting custom fields

From Vendure v2.2, it is possible to add support for [custom fields](/guides/developer-guide/custom-fields/) to your custom entities. This
is useful when you are defining a custom entity as part of a plugin which is intended to be used by other developers. For example, a plugin
which defines a new entity for storing product reviews might want to allow the developer to add custom fields to the review entity.

First you need to update your entity class to implement the `HasCustomFields` interface, and provide an empty class
which will be used to store the custom field values:

```ts title="src/plugins/reviews/entities/product-review.entity.ts"
import {
    DeepPartial,
    HasCustomFields,
    Product,
    VendureEntity,
} from '@vendure/core';
import { Column, Entity, ManyToOne } from 'typeorm';

// highlight-next-line
export class CustomProductReviewFields {}

@Entity()
// highlight-next-line
export class ProductReview extends VendureEntity implements HasCustomFields {
    constructor(input?: DeepPartial<ProductReview>) {
        super(input);
    }

    // highlight-start
    @Column(type => CustomProductReviewFields)
    customFields: CustomProductReviewFields;
    // highlight-end
    
    @ManyToOne(type => Product)
    product: Product;

    @EntityId()
    productId: ID;

    @Column()
    text: string;

    @Column()
    rating: number;
}
```

Now you'll be able to add custom fields to the `ProductReview` entity via the VendureConfig:

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';

export const config: VendureConfig = {
    // ...
    customFields: {
        ProductReview: [
            { name: 'reviewerName', type: 'string' },
            { name: 'reviewerLocation', type: 'string' },
        ],
    },
};
```

---

---
title: "GraphQL Dataloaders"
showtoc: true
---

[Dataloaders](https://github.com/graphql/dataloader) are used in GraphQL to solve the so called N+1 problem. This is an advanced performance optimization technique you may
want to use in your application if you find certain custom queries are slow or inefficient.

## N+1 problem

Imagine a cart with 20 items. Your implementation requires you to perform an `async` calculation `isSubscription` for each cart item which executes one or more queries each time it is called, and it takes pretty long on each execution. It works fine for a cart with 1 or 2 items. But with more than 15 items, suddenly the cart takes a **lot** longer to load. Especially when the site is busy.

The reason: the N+1 problem. Your cart is firing of 20 or more queries almost at the same time, adding **significantly** to the GraphQL request. It's like going to the McDonald's drive-in to get 10 hamburgers and getting in line 10 times to get 1 hamburger at a time. It's not efficient.

## The solution: dataloaders

Dataloaders allow you to say: instead of loading each field in the `grapqhl` tree one at a time, aggregate all the `ids` you want to execute the `async` calculation for, and then execute this for all the `ids` in one efficient `request`.

Dataloaders are generally used on `fieldResolver`s. Often, you will need a specific dataloader for each field resolver.

A Dataloader can return anything: `boolean`, `ProductVariant`, `string`, etc.

## Performance implications

Dataloaders can have a huge impact on performance. If your `fieldResolver` executes queries, and you log these queries, you should see a cascade of queries before the implementation of the dataloader, change to a single query using multiple `ids` after you implement it.

## Do I need this for `CustomField` relations? 

No, not normally. `CustomField` relations are automatically added to the root query for the `entity` that they are part of. So, they are loaded as part of the query that loads that entity.

## Example

We will provide a complete example here for you to use as a starting point. The skeleton created can handle multiple dataloaders across multiple channels. We will implement a `fieldResolver` called `isSubscription` for an `OrderLine` that will return a `true/false` for each incoming `orderLine`, to indicate whether the `orderLine` represents a subscription.


```ts title="src/plugins/my-plugin/api/api-extensions.ts"
import gql from 'graphql-tag';

export const shopApiExtensions = gql`
    extend type OrderLine {
        isSubscription: Boolean!
    }
`
```

This next part import the `dataloader` package, which you can install with

```sh
npm install dataloader
```

**Dataloader skeleton**

```ts title="src/plugins/my-plugin/api/dataloader.ts"
import DataLoader from 'dataloader'

const LoggerCtx = 'SubscriptionDataloaderService'

@Injectable({ scope: Scope.REQUEST }) // Important! Dataloaders live at the request level
export class DataloaderService {

  /**
   * first level is channel identifier, second level is dataloader key
   */
  private loaders = new Map<string, Map<string, DataLoader<ID, any>>>()

  constructor(private service: SubscriptionExtensionService) {}

  getLoader(ctx: RequestContext, dataloaderKey: string) {
    const token = ctx.channel?.code ?? `${ctx.channelId}`
    
    Logger.debug(`Dataloader retrieval: ${token}, ${dataloaderKey}`, LoggerCtx)

    if (!this.loaders.has(token)) {
      this.loaders.set(token, new Map<string, DataLoader<ID, any>>())
    }

    const channelLoaders = this.loaders.get(token)!
    if (!channelLoaders.get(dataloaderKey)) {
      let loader: DataLoader<ID, any>

      switch (dataloaderKey) {
        case 'is-subscription':
          loader = new DataLoader<ID, any>((ids) =>
            this.batchLoadIsSubscription(ctx, ids as ID[]),
          )
          break
        // Implement cases for your other dataloaders here
        default:
          throw new Error(`Unknown dataloader key ${dataloaderKey}`)
      }

      channelLoaders.set(dataloaderKey, loader)
    }
    return channelLoaders.get(dataloaderKey)!
  }

  private async batchLoadIsSubscription(
    ctx: RequestContext,
    ids: ID[],
  ): Promise<Boolean[]> {
    // Returns an array of ids that represent those input ids that are subscriptions
    // Remember: this array can be smaller than the input array
    const subscriptionIds = await this.service.whichSubscriptions(ctx, ids)

    Logger.debug(`Dataloader is-subscription: ${ids}: ${subscriptionIds}`, LoggerCtx)

    return ids.map((id) => subscriptionIds.includes(id)) // Important! preserve order and size of input ids array
  }
}
```


```ts title="src/plugins/my-plugin/api/entity-resolver.ts"
@Resolver(() => OrderLine)
export class MyPluginOrderLineEntityResolver {
  constructor(
    private dataloaderService: DataloaderService,
  ) {}

  @ResolveField()
  isSubscription(@Ctx() ctx: RequestContext, @Parent() parent: OrderLine) {
    const loader = this.dataloaderService.getLoader(ctx, 'is-subscription')
    return loader.load(parent.id)
  }
}
```

To make it all work, ensure that the `DataLoaderService` is loaded in your `plugin` as a provider.

:::tip
Dataloaders map the result in the same order as the `ids` you send to the dataloader. 
Dataloaders expect the same order and array size in the return result. 

In other words: ensure that the order of your returned result is the same as the incoming `ids` and don't omit values!
:::



---

---
title: "Database subscribers"
---

# Defining database subscribers

TypeORM allows us to define [subscribers](https://typeorm.io/listeners-and-subscribers#what-is-a-subscriber). With a subscriber, we can listen to specific entity events and take actions based on inserts, updates, deletions and more.

If you need lower-level access to database changes that you get with the [Vendure EventBus system](/reference/typescript-api/events/event-bus/), TypeORM subscribers can be useful.

## Simple subscribers

The simplest way to register a subscriber is to pass it to the `dbConnectionOptions.subscribers` array:

```ts title="src/plugins/my-plugin/product-subscriber.ts"
import { Product, VendureConfig } from '@vendure/core';
import { EntitySubscriberInterface, EventSubscriber, UpdateEvent } from 'typeorm';

@EventSubscriber()
export class ProductSubscriber implements EntitySubscriberInterface<Product> {
  listenTo() {
    return Product;
  }
  
  beforeUpdate(event: UpdateEvent<Product>) {
    console.log(`BEFORE PRODUCT UPDATED: `, event.entity);
  }
}
```

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';
import { ProductSubscriber } from './plugins/my-plugin/product-subscriber';

// ...
export const config: VendureConfig = {
  dbConnectionOptions: {
    // ...
    subscribers: [ProductSubscriber],
  }
}
```

The limitation of this method is that the `ProductSubscriber` class cannot make use of dependency injection, since it is not known to the underlying NestJS application and is instead instantiated by TypeORM directly.

If you need to make use of providers in your subscriber class, you'll need to use the following pattern.

## Injectable subscribers

By defining the subscriber as an injectable provider, and passing it to a Vendure plugin, you can take advantage of Nest's dependency injection inside the subscriber methods.

```ts title="src/plugins/my-plugin/product-subscriber.ts"
import {
  PluginCommonModule,
  Product,
  TransactionalConnection,
  VendureConfig,
  VendurePlugin,
} from '@vendure/core';
import { Injectable } from '@nestjs/common';
import { EntitySubscriberInterface, EventSubscriber, UpdateEvent } from 'typeorm';
import { MyService } from './services/my.service';

@Injectable()
@EventSubscriber()
export class ProductSubscriber implements EntitySubscriberInterface<Product> {
    constructor(private connection: TransactionalConnection,
                private myService: MyService) {
        // This is how we can dynamically register the subscriber
        // with TypeORM
        connection.rawConnection.subscribers.push(this);
    }

    listenTo() {
        return Product;
    }

    async beforeUpdate(event: UpdateEvent<Product>) {
        console.log(`BEFORE PRODUCT UPDATED: `, event.entity);
        // Now we can make use of our injected provider
        await this.myService.handleProductUpdate(event);
    }
}
```

```ts title="src/plugins/my-plugin/my.plugin.ts"
@VendurePlugin({
    imports: [PluginCommonModule],
    providers: [ProductSubscriber, MyService],
})
class MyPlugin {
}
```

```ts title="src/vendure-config.ts"
// ...
export const config: VendureConfig = {
    dbConnectionOptions: {
        // We no longer need to pass the subscriber here
        // subscribers: [ProductSubscriber],
    },
    plugins: [
        MyPlugin,
    ],
}
```

## Troubleshooting subscribers

An important factor when working with TypeORM subscribers is that they are very low-level and require some understanding of the Vendure schema.

For example consider the `ProductSubscriber` above. If an admin changes a product's name in the Admin UI, this subscriber **will not fire**. The reason is that the `name` property is actually stored on the `ProductTranslation` entity, rather than on the `Product` entity.

So if your subscribers do not seem to work as expected, check your database schema and make sure you are really targeting the correct entity which has the property that you are interested in.



---

---
title: "Error Handling"
showtoc: true
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import Stackblitz from '@site/src/components/Stackblitz';

Errors in Vendure can be divided into two categories:

* Unexpected errors
* Expected errors

These two types have different meanings and are handled differently from one another.

## Unexpected Errors

This type of error occurs when something goes unexpectedly wrong during the processing of a request. Examples include internal server errors, database connectivity issues, lacking permissions for a resource, etc. In short, these are errors that are *not supposed to happen*.

Internally, these situations are handled by throwing an Error:

```ts
const customer = await this.findOneByUserId(ctx, user.id);
// in this case, the customer *should always* be found, and if
// not then something unknown has gone wrong...
if (!customer) {
    throw new InternalServerError('error.cannot-locate-customer-for-user');
}
```

In the GraphQL APIs, these errors are returned in the standard `errors` array:

```json
{
  "errors": [
    {
      "message": "You are not currently authorized to perform this action",
      "locations": [
        {
          "line": 2,
          "column": 2
        }
      ],
      "path": [
        "me"
      ],
      "extensions": {
        "code": "FORBIDDEN"
      }
    }
  ],
  "data": {
    "me": null
  }
}
```
So your client applications need a generic way of detecting and handling this kind of error. For example, many http client libraries support "response interceptors" which can be used to intercept all API responses and check the `errors` array.

:::note
GraphQL will return a `200` status even if there are errors in the `errors` array. This is because in GraphQL it is still possible to return good data _alongside_ any errors.
:::

Here's how it might look in a simple Fetch-based client:

```ts title="src/client.ts"
export function query(document: string, variables: Record<string, any> = {}) {
    return fetch(endpoint, {
        method: 'POST',
        headers,
        credentials: 'include',
        body: JSON.stringify({
            query: document,
            variables,
        }),
    })
        .then(async (res) => {
            if (!res.ok) {
                const body = await res.json();
                throw new Error(body);
            }
            const newAuthToken = res.headers.get('vendure-auth-token');
            if (newAuthToken) {
                localStorage.setItem(AUTH_TOKEN_KEY, newAuthToken);
            }
            return res.json();
        })
        .catch((err) => {
            // This catches non-200 responses, such as malformed queries or
            // network errors. Handle this with your own error handling logic.
            // For this demo we just show an alert.
            window.alert(err.message);
        })
        .then((result) => {
            // highlight-start
            // We check for any GraphQL errors which would be in the
            // `errors` array of the response body:
            if (Array.isArray(result.errors)) {
                // It looks like we have an unexpected error.
                // At this point you could take actions like:
                // - logging the error to a remote service
                // - displaying an error popup to the user
                // - inspecting the `error.extensions.code` to determine the
                //   type of error and take appropriate action. E.g. a
                //   in response to a FORBIDDEN_ERROR you can redirect the
                //   user to a login page.

                // In this example we just display an alert:
                const errorMessage = result.errors.map((e) => e.message).join('\n');
                window.alert(`Unexpected error caught:\n\n${errorMessage}`);
            }
            // highlight-end
            return result;
        });
}
```

## Expected errors (ErrorResults)

This type of error represents a well-defined result of (typically) a GraphQL mutation which is not considered "successful". For example, when using the `applyCouponCode` mutation, the code may be invalid, or it may have expired. These are examples of "expected" errors and are named in Vendure "ErrorResults". These ErrorResults are encoded into the GraphQL schema itself.

ErrorResults all implement the `ErrorResult` interface:

```graphql
interface ErrorResult {
  errorCode: ErrorCode!
  message: String!
}
```

Some ErrorResults add other relevant fields to the type:

```graphql
"Returned if there is an error in transitioning the Order state"
type OrderStateTransitionError implements ErrorResult {
  errorCode: ErrorCode!
  message: String!
  transitionError: String!
  fromState: String!
  toState: String!
}
```

Operations that may return ErrorResults use a GraphQL `union` as their return type:

```graphql
type Mutation {
  "Applies the given coupon code to the active Order"
  applyCouponCode(couponCode: String!): ApplyCouponCodeResult!
}

union ApplyCouponCodeResult = Order
  | CouponCodeExpiredError
  | CouponCodeInvalidError
  | CouponCodeLimitError
```

### Querying an ErrorResult union

When performing an operation of a query or mutation which returns a union, you will need to use the [GraphQL conditional fragment](https://graphql.org/learn/schema/#union-types) to select the desired fields:

```graphql
mutation ApplyCoupon($code: String!) {
  applyCouponCode(couponCode: $code) {
    __typename
    ...on Order {
      id
      couponCodes
      totalWithTax
    }
    # querying the ErrorResult fields
    # "catches" all possible errors
    ...on ErrorResult {
      errorCode
      message
    }
    # you can also specify particular fields
    # if your client app needs that specific data
    # as part of handling the error.
    ...on CouponCodeLimitError {
      limit
    }
  }
}
```

:::note
The `__typename` field is added by GraphQL to _all_ object types, so we can include it no matter whether the result will end up being
an `Order` object or an `ErrorResult` object. We can then use the `__typename` value to determine what kind of object we have received.

Some clients such as Apollo Client will automatically add the `__typename` field to all queries and mutations. If you are using a client which does not do this, you will need to add it manually.
:::

Here's how a response would look in both the success and error result cases:

<Tabs>
<TabItem value="Success case" label="Success case" >

```json
{
  "data": {
    "applyCouponCode": {
      // highlight-next-line
      "__typename": "Order",
      "id": "123",
      "couponCodes": ["VALID-CODE"],
      "totalWithTax": 12599,
    }
  }
}
```

</TabItem>
<TabItem value="Error case" label="Error case" >

```json
{
  "data": {
    "applyCouponCode": {
      // highlight-next-line
      "__typename": "CouponCodeLimitError",
      "errorCode": "COUPON_CODE_LIMIT_ERROR",
      "message": "Coupon code cannot be used more than once per customer",
      // highlight-next-line
      "limit": 1
    }
  }
}
```

</TabItem>
</Tabs>

### Handling ErrorResults in plugin code

If you are writing a plugin which deals with internal Vendure service methods that may return ErrorResults,
then you can use the `isGraphQlErrorResult()` function to check whether the result is an ErrorResult:

```ts
import { Injectable} from '@nestjs/common';
import { isGraphQlErrorResult, Order, OrderService, OrderState, RequestContext } from '@vendure/core';

@Injectable()
export class MyService {

    constructor(private orderService: OrderService) {}

    async myMethod(ctx: RequestContext, order: Order, newState: OrderState) {
        const transitionResult = await this.orderService.transitionToState(ctx, order.id, newState);
        if (isGraphQlErrorResult(transitionResult)) {
            // The transition failed with an ErrorResult
            throw transitionResult;
        } else {
            // TypeScript will correctly infer the type of `transitionResult` to be `Order`
            return transitionResult;
        }
    }
}
```

### Handling ErrorResults in client code

Because we know all possible ErrorResult that may occur for a given mutation, we can handle them in an exhaustive manner. In other
words, we can ensure our storefront has some sensible response to all possible errors. Typically this will be done with
a `switch` statement:

```ts
const result = await query(APPLY_COUPON_CODE, { code: 'INVALID-CODE' });

switch (result.applyCouponCode.__typename) {
    case 'Order':
        // handle success
        break;
    case 'CouponCodeExpiredError':
        // handle expired code
        break;
    case 'CouponCodeInvalidError':
        // handle invalid code
        break;
    case 'CouponCodeLimitError':
        // handle limit error
        break;
    default:
        // any other ErrorResult can be handled with a generic error message
}
```

If we combine this approach with [GraphQL code generation](/guides/storefront/codegen/), then TypeScript will even be able to
help us ensure that we have handled all possible ErrorResults:

```ts
// Here we are assuming that the APPLY_COUPON_CODE query has been generated
// by the codegen tool, and therefore has the
// type `TypedDocumentNode<ApplyCouponCode, ApplyCouponCodeVariables>`.
const result = await query(APPLY_COUPON_CODE, { code: 'INVALID-CODE' });

switch (result.applyCouponCode.__typename) {
    case 'Order':
        // handle success
        break;
    case 'CouponCodeExpiredError':
        // handle expired code
        break;
    case 'CouponCodeInvalidError':
        // handle invalid code
        break;
    case 'CouponCodeLimitError':
        // handle limit error
        break;
    default:
        // highlight-start
        // this line will cause a TypeScript error if there are any
        // ErrorResults which we have not handled in the switch cases
        // above.
        const _exhaustiveCheck: never = result.applyCouponCode;
        // highlight-end
}
```

## Live example

Here is a live example which the handling of unexpected errors as well as ErrorResults:

<Stackblitz id='vendure-docs-error-handling' />


---

---
title: 'Events'
---

Vendure emits events which can be subscribed to by plugins. These events are published by the [EventBus](/reference/typescript-api/events/event-bus/) and
likewise the `EventBus` is used to subscribe to events.

An event exists for virtually all significant actions which occur in the system, such as:

-   When entities (e.g. `Product`, `Order`, `Customer`) are created, updated or deleted
-   When a user registers an account
-   When a user logs in or out
-   When the state of an `Order`, `Payment`, `Fulfillment` or `Refund` changes

A full list of the available events follows.

## Event types

<div class="row">
<div class="col col--6">

-   [`AccountRegistrationEvent`](/reference/typescript-api/events/event-types#accountregistrationevent)
-   [`AccountVerifiedEvent`](/reference/typescript-api/events/event-types#accountverifiedevent)
-   [`AdministratorEvent`](/reference/typescript-api/events/event-types#administratorevent)
-   [`AssetChannelEvent`](/reference/typescript-api/events/event-types#assetchannelevent)
-   [`AssetEvent`](/reference/typescript-api/events/event-types#assetevent)
-   [`AttemptedLoginEvent`](/reference/typescript-api/events/event-types#attemptedloginevent)
-   [`ChangeChannelEvent`](/reference/typescript-api/events/event-types#changechannelevent)
-   [`ChannelEvent`](/reference/typescript-api/events/event-types#channelevent)
-   [`CollectionEvent`](/reference/typescript-api/events/event-types#collectionevent)
-   [`CollectionModificationEvent`](/reference/typescript-api/events/event-types#collectionmodificationevent)
-   [`CountryEvent`](/reference/typescript-api/events/event-types#countryevent)
-   [`CouponCodeEvent`](/reference/typescript-api/events/event-types#couponcodeevent)
-   [`CustomerAddressEvent`](/reference/typescript-api/events/event-types#customeraddressevent)
-   [`CustomerEvent`](/reference/typescript-api/events/event-types#customerevent)
-   [`CustomerGroupChangeEvent`](/reference/typescript-api/events/event-types#customergroupchangeevent)
-   [`CustomerGroupEvent`](/reference/typescript-api/events/event-types#customergroupevent)
-   [`FacetEvent`](/reference/typescript-api/events/event-types#facetevent)
-   [`FacetValueEvent`](/reference/typescript-api/events/event-types#facetvalueevent)
-   [`FulfillmentEvent`](/reference/typescript-api/events/event-types#fulfillmentevent)
-   [`FulfillmentStateTransitionEvent`](/reference/typescript-api/events/event-types#fulfillmentstatetransitionevent)
-   [`GlobalSettingsEvent`](/reference/typescript-api/events/event-types#globalsettingsevent)
-   [`HistoryEntryEvent`](/reference/typescript-api/events/event-types#historyentryevent)
-   [`IdentifierChangeEvent`](/reference/typescript-api/events/event-types#identifierchangeevent)
-   [`IdentifierChangeRequestEvent`](/reference/typescript-api/events/event-types#identifierchangerequestevent)
-   [`InitializerEvent`](/reference/typescript-api/events/event-types#initializerevent)
-   [`LoginEvent`](/reference/typescript-api/events/event-types#loginevent)
-   [`LogoutEvent`](/reference/typescript-api/events/event-types#logoutevent)
-   [`OrderEvent`](/reference/typescript-api/events/event-types#orderevent)

</div>
<div class="col col--6">

-   [`OrderLineEvent`](/reference/typescript-api/events/event-types#orderlineevent)
-   [`OrderPlacedEvent`](/reference/typescript-api/events/event-types#orderplacedevent)
-   [`OrderStateTransitionEvent`](/reference/typescript-api/events/event-types#orderstatetransitionevent)
-   [`PasswordResetEvent`](/reference/typescript-api/events/event-types#passwordresetevent)
-   [`PasswordResetVerifiedEvent`](/reference/typescript-api/events/event-types#passwordresetverifiedevent)
-   [`PaymentMethodEvent`](/reference/typescript-api/events/event-types#paymentmethodevent)
-   [`PaymentStateTransitionEvent`](/reference/typescript-api/events/event-types#paymentstatetransitionevent)
-   [`ProductChannelEvent`](/reference/typescript-api/events/event-types#productchannelevent)
-   [`ProductEvent`](/reference/typescript-api/events/event-types#productevent)
-   [`ProductOptionEvent`](/reference/typescript-api/events/event-types#productoptionevent)
-   [`ProductOptionGroupChangeEvent`](/reference/typescript-api/events/event-types#productoptiongroupchangeevent)
-   [`ProductOptionGroupEvent`](/reference/typescript-api/events/event-types#productoptiongroupevent)
-   [`ProductVariantChannelEvent`](/reference/typescript-api/events/event-types#productvariantchannelevent)
-   [`ProductVariantEvent`](/reference/typescript-api/events/event-types#productvariantevent)
-   [`PromotionEvent`](/reference/typescript-api/events/event-types#promotionevent)
-   [`ProvinceEvent`](/reference/typescript-api/events/event-types#provinceevent)
-   [`RefundStateTransitionEvent`](/reference/typescript-api/events/event-types#refundstatetransitionevent)
-   [`RoleChangeEvent`](/reference/typescript-api/events/event-types#rolechangeevent)
-   [`RoleEvent`](/reference/typescript-api/events/event-types#roleevent)
-   [`SearchEvent`](/reference/typescript-api/events/event-types#searchevent)
-   [`SellerEvent`](/reference/typescript-api/events/event-types#sellerevent)
-   [`ShippingMethodEvent`](/reference/typescript-api/events/event-types#shippingmethodevent)
-   [`StockMovementEvent`](/reference/typescript-api/events/event-types#stockmovementevent)
-   [`TaxCategoryEvent`](/reference/typescript-api/events/event-types#taxcategoryevent)
-   [`TaxRateEvent`](/reference/typescript-api/events/event-types#taxrateevent)
-   [`TaxRateModificationEvent`](/reference/typescript-api/events/event-types#taxratemodificationevent)
-   [`ZoneEvent`](/reference/typescript-api/events/event-types#zoneevent)
-   [`ZoneMembersEvent`](/reference/typescript-api/events/event-types#zonemembersevent)

</div>
</div>

## Subscribing to events

To subscribe to an event, use the `EventBus`'s `.ofType()` method. It is typical to set up subscriptions in the `onModuleInit()` or `onApplicationBootstrap()`
lifecycle hooks of a plugin or service (see [NestJS Lifecycle events](https://docs.nestjs.com/fundamentals/lifecycle-events)).

Here's an example where we subscribe to the `ProductEvent` and use it to trigger a rebuild of a static storefront:

```ts title="src/plugins/storefront-build/storefront-build.plugin.ts"
import { OnModuleInit } from '@nestjs/common';
import { EventBus, ProductEvent, PluginCommonModule, VendurePlugin } from '@vendure/core';

import { StorefrontBuildService } from './services/storefront-build.service';

@VendurePlugin({
    imports: [PluginCommonModule],
})
export class StorefrontBuildPlugin implements OnModuleInit {
    constructor(
        // highlight-next-line
        private eventBus: EventBus,
        private storefrontBuildService: StorefrontBuildService,
    ) {}

    onModuleInit() {
        // highlight-start
        this.eventBus.ofType(ProductEvent).subscribe(event => {
            this.storefrontBuildService.triggerBuild();
        });
        // highlight-end
    }
}
```

:::info
The `EventBus.ofType()` and related `EventBus.filter()` methods return an RxJS `Observable`.
This means that you can use any of the [RxJS operators](https://rxjs-dev.firebaseapp.com/guide/operators) to transform the stream of events.

For example, to debounce the stream of events, you could do this:

```ts
// highlight-next-line
import { debounceTime } from 'rxjs/operators';

// ...

this.eventBus
    .ofType(ProductEvent)
    // highlight-next-line
    .pipe(debounceTime(1000))
    .subscribe(event => {
        this.storefrontBuildService.triggerBuild();
    });
```

:::

### Subscribing to multiple event types

Using the `.ofType()` method allows us to subscribe to a single event type. If we want to subscribe to multiple event types, we can use the `.filter()` method instead:

```ts title="src/plugins/my-plugin/my-plugin.plugin.ts"
import { Injectable, OnModuleInit } from '@nestjs/common';
import {
    EventBus,
    PluginCommonModule,
    VendurePlugin,
    ProductEvent,
    ProductVariantEvent,
} from '@vendure/core';

@VendurePlugin({
    imports: [PluginCommonModule],
})
export class MyPluginPlugin implements OnModuleInit {
    constructor(private eventBus: EventBus) {}

    onModuleInit() {
        this.eventBus
            // highlight-start
            .filter(event => event instanceof ProductEvent || event instanceof ProductVariantEvent)
            // highlight-end
            .subscribe(event => {
                // the event will be a ProductEvent or ProductVariantEvent
            });
    }
}
```

## Publishing events

You can publish events using the `EventBus.publish()` method. This is useful if you want to trigger an event from within a plugin or service.

For example, to publish a `ProductEvent`:

```ts title="src/plugins/my-plugin/services/my-plugin.service.ts"
import { Injectable } from '@nestjs/common';
import { EventBus, ProductEvent, RequestContext, Product } from '@vendure/core';

@Injectable()
export class MyPluginService {
    constructor(private eventBus: EventBus) {}

    async doSomethingWithProduct(ctx: RequestContext, product: Product) {
        // ... do something
        // highlight-next-line
        await this.eventBus.publish(new ProductEvent(ctx, product, 'updated'));
    }
}
```

## Creating custom events

You can create your own custom events by extending the [`VendureEvent`](/reference/typescript-api/events/vendure-event) class. For example, to create a custom event which is triggered when a customer submits a review, you could do this:

```ts title="src/plugins/reviews/events/review-submitted.event.ts"
import { ID, RequestContext, VendureEvent } from '@vendure/core';
import { ProductReviewInput } from '../types';

/**
 * @description
 * This event is fired whenever a ProductReview is submitted.
 */
export class ReviewSubmittedEvent extends VendureEvent {
    constructor(
        public ctx: RequestContext,
        public input: ProductReviewInput,
    ) {
        super();
    }
}
```

The event would then be published from your plugin's `ProductReviewService`:

```ts title="src/plugins/reviews/services/product-review.service.ts"
import { Injectable } from '@nestjs/common';
import { EventBus, ProductReviewService, RequestContext } from '@vendure/core';

import { ReviewSubmittedEvent } from '../events/review-submitted.event';
import { ProductReviewInput } from '../types';

@Injectable()
export class ProductReviewService {
    constructor(
        private eventBus: EventBus,
        private productReviewService: ProductReviewService,
    ) {}

    async submitReview(ctx: RequestContext, input: ProductReviewInput) {
        // highlight-next-line
        this.eventBus.publish(new ReviewSubmittedEvent(ctx, input));
        // handle creation of the new review
        // ...
    }
}
```

### Entity events

There is a special event class [`VendureEntityEvent`](/reference/typescript-api/events/vendure-entity-event) for events relating to the creation, update or deletion of entities. Let's say you have a custom entity (see [defining a database entity](/guides/developer-guide/database-entity)) `BlogPost` and you want to trigger an event whenever a new `BlogPost` is created, updated or deleted:

```ts title="src/plugins/blog/events/blog-post-event.ts"
import { ID, RequestContext, VendureEntityEvent } from '@vendure/core';
import { BlogPost } from '../entities/blog-post.entity';
import { CreateBlogPostInput, UpdateBlogPostInput } from '../types';

type BlogPostInputTypes = CreateBlogPostInput | UpdateBlogPostInput | ID | ID[];

/**
 * This event is fired whenever a BlogPost is added, updated
 * or deleted.
 */
export class BlogPostEvent extends VendureEntityEvent<BlogPost, BlogPostInputTypes> {
    constructor(
        ctx: RequestContext,
        entity: BlogPost,
        type: 'created' | 'updated' | 'deleted',
        input?: BlogPostInputTypes,
    ) {
        super(entity, type, ctx, input);
    }
}
```

Using this event, you can subscribe to all `BlogPost` events, and for instance filter for only the `created` events:

```ts title="src/plugins/blog/blog-plugin.ts"
import { Injectable, OnModuleInit } from '@nestjs/common';
import { EventBus, PluginCommonModule, VendurePlugin } from '@vendure/core';
import { filter } from 'rxjs/operators';

import { BlogPostEvent } from './events/blog-post-event';

@VendurePlugin({
    imports: [PluginCommonModule],
    // ...
})
export class BlogPlugin implements OnModuleInit {
    constructor(private eventBus: EventBus) {}

    onModuleInit() {
        this.eventBus
            // highlight-start
            .ofType(BlogPostEvent)
            .pipe(filter(event => event.type === 'created'))
            .subscribe(event => {
                const blogPost = event.entity;
                // do something with the newly created BlogPost
            });
        // highlight-end
    }
}
```

## Blocking event handlers

:::note
The following section is an advanced topic.

The API described in this section was added in Vendure v2.2.0.
:::

When using the `.ofType().subscribe()` pattern, the event handler is non-blocking. This means that the code that publishes
the event (the "publishing code") will have no knowledge of any subscribers, and in fact any subscribers will be executed after the code that
published the event has completed (technically, any ongoing database transactions are completed before the event gets
emitted to the subscribers). This follows the typical [Observer pattern](https://en.wikipedia.org/wiki/Observer_pattern) and is a good fit for most use-cases.

However, there may be certain situations in which you want the event handler to cause the publishing code to block
until the event handler has completed. This is done by using a "blocking event handler", which does _not_ follow the
Observer pattern, but rather it behaves more like a synchronous function call occurring within the publishing code.

You may want to use a blocking event handler in the following situations:

-   The event handler is so critical that you need to ensure that it has completed before the publishing code continues. For
    example, if the event handler must manipulate some financial records.
-   Errors in the event handler code should cause the publishing code to fail (and any database transaction to be rolled back).
-   You want to guard against the edge case that a server instance gets shut down (due to e.g. a fatal error or an auto-scaling event)
    before event subscribers have been invoked.

In these cases, you can use the `EventBus.registerBlockingEventHandler()` method:

```ts title="src/plugins/my-plugin/my-plugin.plugin.ts"
import { Injectable, OnModuleInit } from '@nestjs/common';
import { EventBus, PluginCommonModule, VendurePlugin, CustomerEvent } from '@vendure/core';
import { CustomerSyncService } from './services/customer-sync.service';

@VendurePlugin({
    imports: [PluginCommonModule],
})
export class MyPluginPlugin implements OnModuleInit {
    constructor(
        private eventBus: EventBus,
        private customerSyncService: CustomerSyncService,
    ) {}

    onModuleInit() {
        // highlight-start
        this.eventBus.registerBlockingEventHandler({
            event: CustomerEvent,
            id: 'sync-customer-details-handler',
            handler: async event => {
                // This hypothetical service method would do nothing
                // more than adding a new job to the job queue. This gives us
                // the guarantee that the job is added before the publishing
                // code is able to continue, while minimizing the time spent
                // in the event handler.
                await this.customerSyncService.triggerCustomerSyncJob(event);
            },
        });
        // highlight-end
    }
}
```

Key differences between event subscribers and blocking event handlers:


Aspect | Event subscribers | Blocking event handlers |
|---|---|---|
| **Execution** | Executed _after_ publishing code completes | Execute _during_ the publishing code |
| **Error handling** | Errors do not affect publishing code | Errors propagated to publishing code |
| **Transactions** | Guaranteed to execute only after the publishing code transaction has completed | Executed within the transaction of the publishing code |
| **Performance** | Non-blocking: subscriber function performance has no effect on publishing code | Blocking: handler function will block execution of publishing code. Handler must be fast. |

### Performance considerations

Since blocking event handlers execute within the same transaction as the publishing code, it is important to ensure that they are fast.
If a single handler takes longer than 100ms to execute, a warning will be logged. Ideally they should be much faster than that - you can
set your Logger's `logLevel` to `LogLevel.DEBUG` to see the execution time of each handler.

If multiple handlers are registered for a single event, they will be executed sequentially, so the publishing code will be blocked until
all handlers have completed.

### Order of execution

If you register multiple handlers for the same event, they will be executed in the order in which they were registered.
If you need more control over this order, i.e. to _guarantee_ that a particular handler will execute before another, you can use
the `before` or `after` options:

```ts
// In one part of your code base
this.eventBus.registerBlockingEventHandler({
    type: CustomerEvent,
    id: 'sync-customer-details-handler',
    handler: async event => {
        // ...
    },
});


// In another part of your code base
this.eventBus.registerBlockingEventHandler({
    type: CustomerEvent,
    id: 'check-customer-details-handler',
    handler: async event => {
        // ...
    },
    // highlight-next-line
    before: 'sync-customer-details-handler',
});
```


---

---
title: "Extend the GraphQL API"
showtoc: true
---

Extension to the GraphQL API consists of two parts:

1. **Schema extensions**. These define new types, fields, queries and mutations.
2. **Resolvers**. These provide the logic that backs up the schema extensions.

The Shop API and Admin APIs can be extended independently:

```ts title="src/plugins/top-products/top-products.plugin.ts"
import { PluginCommonModule, VendurePlugin } from '@vendure/core';
import gql from 'graphql-tag';
import { TopSellersResolver } from './api/top-products.resolver';

const schemaExtension = gql`
  extend type Query {
    topProducts: [Product!]!
  }
`

@VendurePlugin({
    imports: [PluginCommonModule],
    // highlight-start
    // We pass our schema extension and any related resolvers
    // to our plugin metadata  
    shopApiExtensions: {
        schema: schemaExtension,
        resolvers: [TopProductsResolver],
    },
    // Likewise, if you want to extend the Admin API,
    // you would use `adminApiExtensions` in exactly the
    // same way.  
    // adminApiExtensions: {
    //     schema: someSchemaExtension
    //     resolvers: [SomeResolver],
    // },
    // highlight-end
})
export class TopProductsPlugin {
}
```

There are a number of ways the GraphQL APIs can be modified by a plugin.

## Adding a new Query

Let's take a simple example where we want to be able to display a banner in our storefront.

First let's define a new query in the schema:

```ts title="src/plugins/banner/api/api-extensions.ts"
import gql from 'graphql-tag';

export const shopApiExtensions = gql`
  extend type Query {
    // highlight-next-line
    activeBanner(locationId: String!): String
  }
`;
```

This defines a new query called `activeBanner` which takes a `locationId` string argument and returns a string. 

:::tip
`!` = non-nullable

In GraphQL, the `!` in `locationId: String!` indicates that the argument is required, and the lack of a `!` on the return type indicates that the return value can be `null`.
:::

We can now define the resolver for this query:

```ts title="src/plugins/banner/api/banner-shop.resolver.ts"
import { Args, Query, Resolver } from '@nestjs/graphql';
import { Ctx, RequestContext } from '@vendure/core';
import { BannerService } from '../services/banner.service.ts';

@Resolver()
class BannerShopResolver {
    constructor(private bannerService: BannerService) {}

    // highlight-start
    @Query()
    activeBanner(@Ctx() ctx: RequestContext, @Args() args: { locationId: string; }) {
        return this.bannerService.getBanner(ctx, args.locationId);
    }
    // highlight-end
}
```

The `BannerService` would implement the actual logic for fetching the banner text from the database.

Finally, we need to add the resolver to the plugin metadata:

```ts title="src/plugins/banner/banner.plugin.ts"
import { PluginCommonModule, VendurePlugin } from '@vendure/core';
import { BannerService } from './services/banner.service';
import { BannerShopResolver } from './api/banner-shop.resolver';
import { shopApiExtensions } from './api/api-extensions';

@VendurePlugin({
    imports: [PluginCommonModule],
    // highlight-start
    shopApiExtensions: {
        schema: shopApiExtensions,
        resolvers: [BannerShopResolver],
    },
    // highlight-end
    providers: [BannerService],
})
export class BannerPlugin {}
```

## Adding a new Mutation

Let's continue the `BannerPlugin` example and now add a mutation which allows the administrator to set the banner text.

First we define the mutation in the schema:

```ts title="src/plugins/banner/api/api-extensions.ts"
import gql from 'graphql-tag';

export const adminApiExtensions = gql`
  extend type Mutation {
    // highlight-next-line
    setBannerText(locationId: String!, text: String!): String!
  }
`;
```

Here we are defining a new mutation called `setBannerText` which takes two arguments, `locationId` and `text`, both of which are required strings. The return type is a non-nullable string.

Now let's define a resolver to handle that mutation:

```ts title="src/plugins/banner/api/banner-admin.resolver.ts"
import { Args, Mutation, Resolver } from '@nestjs/graphql';
import { Allow, Ctx, RequestContext, Permission, Transaction } from '@vendure/core';
import { BannerService } from '../services/banner.service.ts';

@Resolver()
class BannerAdminResolver {
    constructor(private bannerService: BannerService) {}

    // highlight-start
    @Allow(Permission.UpdateSettings)
    @Transaction()
    @Mutation()
    setBannerText(@Ctx() ctx: RequestContext, @Args() args: { locationId: string; text: string; }) {
        return this.bannerService.setBannerText(ctx, args.locationId, args.text);
    }
    // highlight-end
}
```

Note that we have used the `@Allow()` decorator to ensure that only users with the `UpdateSettings` permission can call this mutation. We have also wrapped the resolver in a transaction using `@Transaction()`, which is a good idea for any mutation which modifies the database.

:::info
For more information on the available decorators, see the [API Layer "decorators" guide](/guides/developer-guide/the-api-layer/#api-decorators).
:::

Finally, we add the resolver to the plugin metadata:

```ts title="src/plugins/banner/banner.plugin.ts"
import { PluginCommonModule, VendurePlugin } from '@vendure/core';
import { BannerService } from './services/banner.service';
import { BannerShopResolver } from './api/banner-shop.resolver';
import { BannerAdminResolver } from './api/banner-admin.resolver';
import { shopApiExtensions, adminApiExtensions } from './api/api-extensions';

@VendurePlugin({
    imports: [PluginCommonModule],
    shopApiExtensions: {
        schema: shopApiExtensions,
        resolvers: [BannerShopResolver],
    },
    // highlight-start
    adminApiExtensions: {
        schema: adminApiExtensions,
        resolvers: [BannerAdminResolver],
    },
    // highlight-end
    providers: [BannerService],
})
export class BannerPlugin {}
```


## Defining a new type

If you have defined a new database entity, it is likely that you'll want to expose this entity in your GraphQL API. To do so, you'll need to define a corresponding GraphQL type.

Using the `ProductReview` entity from the [Define a database entity guide](/guides/developer-guide/database-entity), let's see how we can expose it as a new type in the API.

As a reminder, here is the `ProductReview` entity:

```ts title="src/plugins/reviews/product-review.entity.ts"
import { DeepPartial } from '@vendure/common/lib/shared-types';
import { VendureEntity, Product, EntityId, ID } from '@vendure/core';
import { Column, Entity, ManyToOne } from 'typeorm';

@Entity()
class ProductReview extends VendureEntity {
    constructor(input?: DeepPartial<ProductReview>) {
        super(input);
    }

    @ManyToOne(type => Product)
    product: Product;
    
    @EntityId()
    productId: ID;

    @Column()
    text: string;

    @Column()
    rating: number;
}
```
Let's define a new GraphQL type which corresponds to this entity:

```ts title="src/plugins/reviews/api/api-extensions.ts"
import gql from 'graphql-tag';

export const apiExtensions = gql`
  // highlight-start
  type ProductReview implements Node {
    id: ID!
    createdAt: DateTime!
    updatedAt: DateTime!
    product: Product!
    productId: ID!
    text: String!
    rating: Float!
  }
  // highlight-end
`;
```

:::info
Assuming the entity is a standard `VendureEntity`, it is good practice to always include the `id`, `createdAt` and `updatedAt` fields in the GraphQL type.

Additionally, we implement `Node` which is a built-in GraphQL interface.
:::

Now we can add this type to both the Admin and Shop APIs:

```ts title="src/plugins/reviews/reviews.plugin.ts"
import gql from 'graphql-tag';
import { PluginCommonModule, VendurePlugin } from '@vendure/core';
import { ReviewsResolver } from './api/reviews.resolver';
import { apiExtensions } from './api/api-extensions';
import { ProductReview } from './entities/product-review.entity';

@VendurePlugin({
    imports: [PluginCommonModule],
    shopApiExtensions: {
        // highlight-next-line
        schema: apiExtensions,
    },
    entities: [ProductReview],
})
export class ReviewsPlugin {}
```

## Add fields to existing types

Let's say you want to add a new field to the `ProductVariant` type to allow the storefront to display some indication of how long a particular product variant would take to deliver, based on data from some external service. 

First we extend the `ProductVariant` GraphQL type:

```ts title="src/plugins/delivery-time/api/api-extensions.ts"
import gql from 'graphql-tag';

export const shopApiExtensions = gql`
  type DeliveryEstimate {
    from: Int!
    to: Int!
  }

  // highlight-start
  extend type ProductVariant {
    delivery: DeliveryEstimate!
  }
  // highlight-end
}`;
```

This schema extension says that the `delivery` field will be added to the `ProductVariant` type, and that it will be of type `DeliveryEstimate!`, i.e. a non-nullable
instance of the `DeliveryEstimate` type.

Next we need to define an "entity resolver" for this field. Unlike the resolvers we have seen above, this resolver will be handling fields on the `ProductVariant` type _only_. This is done by scoping the resolver class that type by passing the type name to the `@Resolver()` decorator:

```ts title="src/plugins/delivery-time/product-variant-entity.resolver.ts"
import { Parent, ResolveField, Resolver } from '@nestjs/graphql';
import { Ctx, RequestContext, ProductVariant } from '@vendure/core';
import { DeliveryEstimateService } from '../services/delivery-estimate.service';

// highlight-next-line
@Resolver('ProductVariant')
export class ProductVariantEntityResolver {
    constructor(private deliveryEstimateService: DeliveryEstimateService) { }

    // highlight-start
    @ResolveField()
    delivery(@Ctx() ctx: RequestContext, @Parent() variant: ProductVariant) {
        return this.deliveryEstimateService.getEstimate(ctx, variant.id);
    }
    // highlight-end
}
```

Finally we need to pass these schema extensions and the resolver to our plugin metadata:

```ts title="src/plugins/delivery-time/delivery-time.plugin.ts"
import gql from 'graphql-tag';
import { PluginCommonModule, VendurePlugin } from '@vendure/core';
import { ProductVariantEntityResolver } from './api/product-variant-entity.resolver';
import { shopApiExtensions } from './api/api-extensions';

@VendurePlugin({
    imports: [PluginCommonModule],
    shopApiExtensions: {
        // highlight-start
        schema: shopApiExtensions,
        resolvers: [ProductVariantEntityResolver]
        // highlight-end
    }
})
export class DeliveryTimePlugin {}
```

## Override built-in resolvers

It is also possible to override an existing built-in resolver function with one of your own. To do so, you need to define a resolver with the same name as the query or mutation you wish to override. When that query or mutation is then executed, your code, rather than the default Vendure resolver, will handle it.

```ts
import { Args, Query, Mutation, Resolver } from '@nestjs/graphql';
import { Ctx, RequestContext } from '@vendure/core'

@Resolver()
class OverrideExampleResolver {

    @Query()
    products(@Ctx() ctx: RequestContext, @Args() args: any) {
        // when the `products` query is executed, this resolver function will
        // now handle it.
    }

    @Transaction()
    @Mutation()
    addItemToOrder(@Ctx() ctx: RequestContext, @Args() args: any) {
        // when the `addItemToOrder` mutation is executed, this resolver function will
        // now handle it.
    }

}
```

The same can be done for resolving fields:

```ts
import { Parent, ResolveField, Resolver } from '@nestjs/graphql';
import { Ctx, RequestContext, Product } from '@vendure/core';

@Resolver('Product')
export class FieldOverrideExampleResolver {

    @ResolveField()
    description(@Ctx() ctx: RequestContext, @Parent() product: Product) {
        return this.wrapInFormatting(ctx, product.id);
    }

    private wrapInFormatting(ctx: RequestContext, id: ID): string {
        // implementation omitted, but wraps the description
        // text in some special formatting required by the storefront
    }
}
```

## Resolving union results

When dealing with operations that return a GraphQL union type, there is an extra step needed.

Union types are commonly returned from mutations in the Vendure APIs. For more detail on this see the section on [ErrorResults](/guides/developer-guide/error-handling#expected-errors-errorresults). For example: 

```graphql
type MyCustomErrorResult implements ErrorResult {
  errorCode: ErrorCode!
  message: String!
}

union MyCustomMutationResult = Order | MyCustomErrorResult

extend type Mutation {
  myCustomMutation(orderId: ID!): MyCustomMutationResult!
}
```

In this example, the resolver which handles the `myCustomMutation` operation will be returning either an `Order` object or a `MyCustomErrorResult` object. The problem here is that the GraphQL server has no way of knowing which one it is at run-time. Luckily Apollo Server (on which Vendure is built) has a means to solve this:

> To fully resolve a union, Apollo Server needs to specify which of the union's types is being returned. To achieve this, you define a `__resolveType` function for the union in your resolver map.
> 
> The `__resolveType` function is responsible for determining an object's corresponding GraphQL type and returning the name of that type as a string.
> 
-- <cite>Source: [Apollo Server docs](https://www.apollographql.com/docs/apollo-server/schema/unions-interfaces/#resolving-a-union)</cite>

In order to implement a `__resolveType` function as part of your plugin, you need to create a dedicated Resolver class with a single field resolver method which will look like this:

```ts
import { Parent, ResolveField, Resolver } from '@nestjs/graphql';
import { Ctx, RequestContext, ProductVariant } from '@vendure/core';

@Resolver('MyCustomMutationResult')
export class MyCustomMutationResultResolver {
  
  @ResolveField()
  __resolveType(value: any): string {
    // If it has an "id" property we can assume it is an Order.  
    return value.hasOwnProperty('id') ? 'Order' : 'MyCustomErrorResult';
  }
}
```

This resolver is then passed in to your plugin metadata like any other resolver:

```ts
@VendurePlugin({
  imports: [PluginCommonModule],
  shopApiExtensions: {
    schema: apiExtensions,
    resolvers: [/* ... */, MyCustomMutationResultResolver]
  }
})
export class MyPlugin {}
```

Sticking to this example of `myCustomMutation`, you'll also want to use the [ErrorResultUnion](/reference/typescript-api/errors/error-result-union) in your `MyCustomMutationResolver` and corresponding service like so:

```ts
import { Args, Mutation, Resolver } from "@nestjs/graphql";
import { Ctx, ErrorResultUnion, ID, Order, RequestContext, Transaction } from "@vendure/core";

@Resolver()
export class MyCustomMutationResolver {
  constructor(private myCustomService: MyCustomService) {}

  @Mutation()
  @Transaction()
  async myCustomMutation(
    @Ctx() ctx: RequestContext,
    @Args() args: { orderId: ID }
  ): Promise<ErrorResultUnion<MyCustomMutationResult, Order>> {
    return this.myCustomService.doMyCustomMutation(ctx, args.orderId);
  }
}
```

This is because Typescript entities do not correspond 1-to-1 with their GraphQL type counterparts, which results in an error when you're returning the `Order`-Object because it is not assignable to `MyCustomMutationResult`.

## Defining custom scalars

By default, Vendure bundles `DateTime` and a `JSON` custom scalars (from the [graphql-scalars library](https://github.com/Urigo/graphql-scalars)). From v1.7.0, you can also define your own custom scalars for use in your schema extensions:

```ts
import { GraphQLScalarType} from 'graphql';
import { GraphQLEmailAddress } from 'graphql-scalars';

// Scalars can be custom-built as like this one,
// or imported from a pre-made scalar library like
// the GraphQLEmailAddress example.
const FooScalar = new GraphQLScalarType({
  name: 'Foo',
  description: 'A test scalar',
  serialize(value) {
    // ...
  },
  parseValue(value) {
    // ...
  },
});

@VendurePlugin({
  imports: [PluginCommonModule],
  shopApiExtensions: {
    schema: gql`
      scalar Foo
      scalar EmailAddress
    `,
    scalars: { 
      // The key must match the scalar name
      // given in the schema  
      Foo: FooScalar,
      EmailAddress: GraphQLEmailAddress,
    },
  },
})
export class CustomScalarsPlugin {}
```


---

---
title: "Importing Data"
showtoc: true
---

If you have hundreds, thousands or more products, inputting all the data by hand via the Admin UI can be too inefficient. To solve this, Vendure supports bulk-importing product and other data.

Data import is also useful for setting up test or demo environments, and is also used by the `@vendure/testing` package for end-to-end tests.

## Product Import Format

Vendure uses a flat **.csv** format for importing product data. The format encodes data about:

* products
* product variants
* product & variant assets
* product & variant facets
* product & variant custom fields

Here's an example which defines 2 products, "Laptop" and "Clacky Keyboard". The laptop has 4 variants, and the keyboard only a single variant. 

```csv
name            , slug            , description               , assets                      , facets                              , optionGroups    , optionValues , sku         , price   , taxCategory , stockOnHand , trackInventory , variantAssets , variantFacets
Laptop          , laptop          , "Description of laptop"   , laptop_01.jpg|laptop_02.jpg , category:electronics|brand:Apple    , screen size|RAM , 13 inch|8GB  , L2201308    , 1299.00 , standard    , 100         , false          ,               , 
                ,                 ,                           ,                             ,                                     ,                 , 15 inch|8GB  , L2201508    , 1399.00 , standard    , 100         , false          ,               , 
                ,                 ,                           ,                             ,                                     ,                 , 13 inch|16GB , L2201316    , 2199.00 , standard    , 100         , false          ,               , 
                ,                 ,                           ,                             ,                                     ,                 , 15 inch|16GB , L2201516    , 2299.00 , standard    , 100         , false          ,               , 
Clacky Keyboard , clacky-keyboard , "Description of keyboard" , keyboard_01.jpg             , category:electronics|brand:Logitech ,                 ,              , A4TKLA45535 , 74.89   , standard    , 100         , false          ,               ,
```

Here's an explanation of each column:

* `name`: The name of the product. Rows with an empty "name" are interpreted as variants of the preceeding product row.
* `slug`: The product's slug. Can be omitted, in which case will be generated from the name.
* `description`: The product description.
* `assets`: One or more asset file names separated by the pipe (`|`) character. The files can be located on the local file system, in which case the path is interpreted as being relative to the [`importAssetsDir`](/reference/typescript-api/import-export/import-export-options/#importassetsdir) as defined in the VendureConfig. Files can also be urls which will be fetched from a remote http/https url. If you need more control over how assets are imported, you can implement a custom [AssetImportStrategy](/reference/typescript-api/import-export/asset-import-strategy#assetimportstrategy). The first asset will be set as the featuredAsset.
* `facets`: One or more facets to apply to the product separated by the pipe (`|`) character. A facet has the format `<facet-name>:<facet-value>`.
* `optionGroups`: OptionGroups define what variants make up the product. Applies only to products with more than one variant. 
* `optionValues`: For each optionGroup defined, a corresponding value must be specified for each variant. Applies only to products with more than one variant.
* `sku`: The Stock Keeping Unit (unique product code) for this product variant.
* `price`: The price can be either with or without taxes, depending on your channel settings (can be set later).
* `taxCategory`: The name of an existing tax category. Tax categories can be also be imported using the InitialData object.
* `stockOnHand`: The number of units in stock.
* `trackInventory`: Whether this variant should have its stock level tracked, i.e. the stock level is automatically decreased for each unit ordered.
* `variantAssets`: Same as `assets` but applied to the product variant.
* `variantFacets`: Same as `facets` but applied to the product variant.

### Importing Custom Field Data

If you have [CustomFields](/guides/developer-guide/custom-fields/) defined on your Product or ProductVariant entities, this data can also be encoded in the import csv:

* `product:<customFieldName>`: The value of this column will populate `Product.customFields[customFieldName]`. 
* `variant:<customFieldName>`: The value of this column will populate `ProductVariant.customFields[customFieldName]`. 

:::info 
For a real example, see the [products.csv file used to populate the Vendure demo data](https://github.com/vendure-ecommerce/vendure/blob/master/packages/core/mock-data/data-sources/products.csv)
:::

#### Importing `relation` custom fields

To import custom fields with the type `relation`, the value in the CSV must be a stringified object with an `id` property:

```csv
... ,product:featuredReview
... ,"{ ""id"": 123 }"
```

#### Importing `list` custom fields

To import custom fields with `list` set to `true`, the data should be separated with a pipe (`|`) character:

```csv
... ,product:keywords
... ,tablet|pad|android
```

#### Importing data in multiple languages

If a field is translatable (i.e. of `localeString` type), you can use column names with an appended language code (e.g. `name:en`, `name:de`, `product:keywords:en`, `product:keywords:de`) to specify its value in multiple languages.

Use of language codes has to be consistent throughout the file. You don't have to translate every translatable field. If there are no translated columns for a field, the generic column's value will be used for all languages. But when you do translate columns, the set of languages for each of them needs to be the same. As an example, you cannot use `name:en` and `name:de`, but only provide `slug:en` (it's okay to use only a `slug` column though, in which case this slug will be used for both the English and the German version).

## Initial Data

As well as product data, other initialization data can be populated using the [`InitialData` object](/reference/typescript-api/import-export/initial-data/). **This format is intentionally limited**; more advanced requirements (e.g. setting up ShippingMethods that use custom checkers & calculators) should be carried out via [custom populate scripts](#populating-the-server).

```ts
import { InitialData, LanguageCode } from '@vendure/core';

export const initialData: InitialData = {
    paymentMethods: [
        {
            name: 'Standard Payment',
            handler: {
                code: 'dummy-payment-handler',
                arguments: [{ name: 'automaticSettle', value: 'false' }],
            },
        },
    ],
    roles: [
        {
            code: 'administrator',
            description: 'Administrator',
            permissions: [
                Permission.CreateCatalog,
                Permission.ReadCatalog,
                Permission.UpdateCatalog,
                Permission.DeleteCatalog,
                Permission.CreateSettings,
                Permission.ReadSettings,
                Permission.UpdateSettings,
                Permission.DeleteSettings,
                Permission.CreateCustomer,
                Permission.ReadCustomer,
                Permission.UpdateCustomer,
                Permission.DeleteCustomer,
                Permission.CreateCustomerGroup,
                Permission.ReadCustomerGroup,
                Permission.UpdateCustomerGroup,
                Permission.DeleteCustomerGroup,
                Permission.CreateOrder,
                Permission.ReadOrder,
                Permission.UpdateOrder,
                Permission.DeleteOrder,
                Permission.CreateSystem,
                Permission.ReadSystem,
                Permission.UpdateSystem,
                Permission.DeleteSystem,
            ],
        },
    ],
    defaultLanguage: LanguageCode.en,
    countries: [
        { name: 'Austria', code: 'AT', zone: 'Europe' },
        { name: 'Malaysia', code: 'MY', zone: 'Asia' },
        { name: 'United Kingdom', code: 'GB', zone: 'Europe' },
    ],
    defaultZone: 'Europe',
    taxRates: [
        { name: 'Standard Tax', percentage: 20 },
        { name: 'Reduced Tax', percentage: 10 },
        { name: 'Zero Tax', percentage: 0 },
    ],
    shippingMethods: [{ name: 'Standard Shipping', price: 500 }, { name: 'Express Shipping', price: 1000 }],
    collections: [
        {
            name: 'Electronics',
            filters: [
                {
                    code: 'facet-value-filter',
                    args: { facetValueNames: ['Electronics'], containsAny: false },
                },
            ],
            assetPaths: ['jakob-owens-274337-unsplash.jpg'],
        },
    ],
};
```

* `paymentMethods`: Defines which payment methods are available.
  * `name`: Name of the payment method.
  * `handler`: Payment plugin handler information.
* `roles`: Defines which user roles are available.
  * `code`: Role code name.
  * `description`: Role description.
  * `permissions`: List of permissions to apply to the role.
* `defaultLanguage`: Sets the language that will be used for all translatable entities created by the initial data e.g. Products, ProductVariants, Collections etc. Should correspond to the language used in your product csv file.
* `countries`: Defines which countries are available.
  * `name`: The name of the country in the language specified by `defaultLanguage`
  * `code`: A standardized code for the country, e.g. [ISO 3166-1](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes)
  * `zone`: A [Zone](/reference/typescript-api/entities/zone) to which this country belongs.
* `defaultZone`: Sets the default shipping & tax zone for the default Channel. The zone must correspond to a value of `zone` set in the `countries` array. 
* `taxRates`: For each item, a new [TaxCategory](/reference/typescript-api/entities/tax-category/) is created, and then a [TaxRate](/reference/typescript-api/entities/tax-rate) is created for each unique zone defined in the `countries` array. 
* `shippingMethods`: Allows simple flat-rate [ShippingMethods](/reference/typescript-api/entities/shipping-method) to be defined.
* `collections`: Allows Collections to be created. Currently, only collections based on facet values can be created (`code: 'facet-value-filter'`). The `assetPaths` and `facetValueNames` values must correspond to a value specified in the products csv file. The name should match the value specified in the product csv file (or can be a normalized - lower-case & hyphenated - version thereof). If there are FacetValues in multiple Facets with the same name, the facet may be specified with a colon delimiter, e.g. `brand:apple`, `flavour: apple`.

## Populating The Server

### The `populate()` function
The `@vendure/core` package exposes a [`populate()` function](/reference/typescript-api/import-export/populate/) which can be used along with the data formats described above to populate your Vendure server:

```ts title="src/my-populate-script.ts"
import { bootstrap, DefaultJobQueuePlugin } from '@vendure/core';
import { populate } from '@vendure/core/cli';
import path from "path";

import { config } from './vendure-config';
import { initialData } from './my-initial-data';

const productsCsvFile = path.join(__dirname, 'path/to/products.csv')

const populateConfig = {
    ...config,
    plugins: (config.plugins || []).filter(
        // Remove your JobQueuePlugin during populating to avoid
        // generating lots of unnecessary jobs as the Collections get created.
        plugin => plugin !== DefaultJobQueuePlugin,
    ),
}

populate(
    () => bootstrap(populateConfig),
    initialData,
    productsCsvFile,
    'my-channel-token' // optional - used to assign imported 
)                      // entities to the specified Channel

    .then(app => {
        return app.close();
    })
    .then(
        () => process.exit(0),
        err => {
            console.log(err);
            process.exit(1);
        },
    );
```

:::note
When removing the `DefaultJobQueuePlugin` from the plugins list as in the code snippet above, one should manually rebuild the search index in order for the newly added products to appear.
In the Admin UI, this can be done by navigating to the product list view and clicking the three icon next to the search input:

![Rebuild search index](./reindex.webp)
:::

### Populating test data

When installing with @vendure/create, you have the option of populating test data (products, payment methods, countries, zones, tax rates etc).

This guide illustrates how to populate that test data again on an existing Vendure installation, without needing to re-install from scratch.

1. `npm install --save-dev @vendure/create`. This installs the "create" package, which contains the test data we will need.
2. drop all tables from your database, but leave the actual database there.
3. create a script that looks like this:

```ts title="src/populate-test-data.ts"
import { populate } from '@vendure/core/cli';
import { bootstrap, VendureConfig } from '@vendure/core';
import { config } from './vendure-config';

populate(
    () => bootstrap({
        ...config,
        importExportOptions: {
            importAssetsDir: path.join(
                require.resolve('@vendure/create/assets/products.csv'),
                '../images'
            ),
        },
        dbConnectionOptions: {...config.dbConnectionOptions, synchronize: true}
    }),
    require('@vendure/create/assets/initial-data.json'),
    require.resolve('@vendure/create/assets/products.csv')
)
    .then(app => app.close())
    .catch(err => {
        console.log(err);
        process.exit(1);
    });
```

Running this script will populate the database with the test data like when you first installed Vendure.

### Custom populate scripts

If you require more control over how your data is being imported - for example if you also need to import data into custom entities, or import customer or order information - you can create your own CLI script to do this: see [Stand-Alone CLI Scripts](/guides/developer-guide/stand-alone-scripts/).

In addition to all the services available in the [Service Layer](/guides/developer-guide/the-service-layer/), the following specialized import services are available:

* [`ImportParser`](/reference/typescript-api/import-export/import-parser): Used to parse the CSV file into an array of objects.
* [`FastImporterService`](/reference/typescript-api/import-export/fast-importer-service): Used to create new products & variants in bulk, optimized for speed.
* [`Populator`](/reference/typescript-api/import-export/populator): Used to populate the initial data.
* [`AssetImporter`](/reference/typescript-api/import-export/asset-importer): Creates new Assets in bulk, using the configured [`AssetImportStrategy`](/reference/typescript-api/import-export/asset-import-strategy).
* [`Importer`](/reference/typescript-api/import-export/importer/): Uses all of the above services in combination - this is the basis of the `populate()` function described above.

Using these specialized import services is preferable to using the normal service-layer services (`ProductService`, `ProductVariantService` etc.) for bulk imports. This is because these import services are optimized for bulk imports (they omit unnecessary checks, use optimized SQL queries) and also do not publish events when creating new entities.

However, it is still possible to use the normal service-layer services if you prefer. For example, the following code snippet shows how to create a new ProductVariant using the `ProductVariantService`:

```ts title="src/create-new-variant-service.ts"
import { INestApplicationContext } from '@nestjs/common';
import {
    ProductVariantService,
    TransactionalConnection,
    LanguageCode,
    RequestContext,
    RequestContextService,
    bootstrapWorker,
    ConfigService,
    ID,
    User,
    SearchService,
} from '@vendure/core';

import { config } from './vendure-config';

async function createNewVariantService() {
    // We use the bootstrapWorker() function instead of bootstrap() because we don't
    // need to start the server, we just need access to the services.
    const { app } = await bootstrapWorker(config);

    // Most service methods require a RequestContext, so we'll create one here.
    const ctx = await getSuperadminContext(app);

    // Get the ProductVariantService instance from the application
    const productVariantService = app.get(ProductVariantService);

    // To reindex after importing products
    const searchService = app.get(SearchService);

    // Example: Creating a new ProductVariant for an existing product with ID 1
    const productId = '1' as ID;
    // Create input data for the new variant
    const variantInput = {
        productId,
        translations: [
            {
                languageCode: LanguageCode.en,
                name: 'New Variant 1',
            },
        ],
        sku: 'NEW-VARIANT-001',
        // Specify additional variant properties...
    };

    // Create the variant
    const newVariants = await productVariantService.create(ctx, [variantInput]);

    console.log('Created new product variants:', newVariants);

    // Rebuild search index to include the new variant
    await searchService.reindex(ctx);

    await app.close();
}

/**
 * Creates a RequestContext configured for the default Channel with the activeUser set
 * as the superadmin user.
 */
export async function getSuperadminContext(app: INestApplicationContext): Promise<RequestContext> {
    const {superadminCredentials} = app.get(ConfigService).authOptions;
    const superAdminUser = await app.get(TransactionalConnection)
        .getRepository(User)
        .findOneOrFail({where: {identifier: superadminCredentials.identifier}});
    return app.get(RequestContextService).create({
        apiType: 'admin',
        user: superAdminUser,
    });
}
```

## Importing from other platforms

If you are migrating from another platform, you can create a custom import script to import your data into Vendure.

Your existing platform may provide an API which you can use to fetch the data, or it may provide a mechanism for exporting
the data to a file.

Therefore, you have a couple of options:

1. Export the data to a file, and then transform this into the Vendure CSV format for import as above.
2. Write a script which import the data via the other platform's API, and then import this data into Vendure using the services described above, or any other of the Vendure core services.

The first option is the simplest, but may not be possible if the other platform does not provide a suitable export format.

The second option is more complex, but allows for more flexibility and can be used to import data from any source, as well as allowing the import of other data such as customer and order information.

As an illustrative example, let's imagine we are migrating away from an imaginary commerce platform, "OldCommerce", and we want to import our data into Vendure.

Luckily, OldCommerce provides a client package which allows us to easily interact with their API.

:::note
This is a much-simplified example, but it should serve to illustrate the general approach.
:::

```ts title="src/import-from-other-platform.ts"
import { INestApplicationContext } from '@nestjs/common';
import {
    bootstrapWorker,
    ConfigService,
    Importer,
    LanguageCode,
    ParsedProductWithVariants,
    RequestContext, RequestContextService,
    TransactionalConnection, User,
    SearchService,
} from '@vendure/core';
import { createClient, OldCommerceProduct } from '@old-commerce/client';

import { config } from './vendure-config';

if (require.main === module) {
    importData().then(
        () => process.exit(0),
        err => {
            console.log(err);
            process.exit(1);
        },
    );
}

async function importData() {
    // We use the bootstrapWorker() function instead of bootstrap() because we don't 
    // need to start the server, we just need access to the services.
    const {app} = await bootstrapWorker(config);

    // Create an instace of the client we'll be using to interact with the
    // OldCommerce API
    const client = createClient({
        // OldCommerce client config
    });

    // Let's grab a reference to each of the Vendure services we'll need.
    const importer = app.get(Importer);

    // Most service methods require a RequestContext, so we'll create one here.
    const ctx = await getSuperadminContext(app);

    // To reindex after importing products
    const searchService = app.get(SearchService);

    // Fetch all the products to import from the OldCommerce API
    const productsToImport: OldCommerceProduct[] = await client.getAllProducts();

    // Transform the OldCommerce products into the format expected by the Importer
    const importRows: ParsedProductWithVariants[] = productsToImport.map(product => ({
        product: {
            translations: [
                {
                    languageCode: LanguageCode.en,
                    name: product.name,
                    slug: product.slug,
                    description: product.description,
                    customFields: {},
                },
            ],
            assetPaths: product.images.map(image => image.sourceUrl),
            facets: [],
            optionGroups: product.options.map(option => ({
                translations: [
                    {
                        languageCode: LanguageCode.en,
                        name: option.name,
                        values: option.values.map(value => value.name),
                    },
                ],
            })),
        },
        variants: product.variations.map(variation => {
            const optionValues = variation.options.map(option => option.value);
            return {
                sku: variation.productCode,
                price: variation.price,
                stockOnHand: variation.stock,
                translations: [{languageCode: LanguageCode.en, optionValues}],
            };
        }),
    }));

    // Import the products
    await importer.importProducts(ctx, importRows, progress => {
        console.log(`Imported ${progress.imported} of ${importRows.length} products`);
    });

    // Rebuild search index 
    await searchService.reindex(ctx);

    // Close the app
    await app.close();
}

/**
 * Creates a RequestContext configured for the default Channel with the activeUser set
 * as the superadmin user.
 */
export async function getSuperadminContext(app: INestApplicationContext): Promise<RequestContext> {
    const {superadminCredentials} = app.get(ConfigService).authOptions;
    const superAdminUser = await app.get(TransactionalConnection)
        .getRepository(User)
        .findOneOrFail({where: {identifier: superadminCredentials.identifier}});
    return app.get(RequestContextService).create({
        apiType: 'admin',
        user: superAdminUser,
    });
}
```


---

---
title: "Logging"
showtoc: true
---

# Logging

Logging allows you to see what is happening inside the Vendure server. It is useful for debugging and for monitoring the health of the server in production.

In Vendure, logging is configured using the `logger` property of the [VendureConfig](/reference/typescript-api/configuration/vendure-config/#logger) object. The logger must implement the [VendureLogger](/reference/typescript-api/logger/vendure-logger) interface.

:::info
To implement a custom logger, see the [Implementing a custom logger](/reference/typescript-api/logger/#implementing-a-custom-logger) guide.
:::

## Log levels

Vendure uses 5 log levels, in order of increasing severity:

| Level     | Description                                                                                              |
|-----------|----------------------------------------------------------------------------------------------------------|
| `Debug`   | The most verbose level, used for debugging purposes. The output can be very noisy at this level          |
| `Verbose` | More information than the Info level, but less than `Debug`                                              |
| `Info`    | General information about the normal running of the server                                               |
| `Warning` | Issues which might need attention or action, but which do not prevent the server from continuing to run. |
| `Error`   | Errors which should be investigated and handled; something has gone wrong.                               |


## DefaultLogger

Vendure ships with a [DefaultLogger](/reference/typescript-api/logger/default-logger) which logs to the console (process.stdout). It can be configured with the desired log level:

```ts title="src/vendure-config.ts"
import { DefaultLogger, VendureConfig } from '@vendure/core';

const config: VendureConfig = {
    // ...
    logger: new DefaultLogger({ level: LogLevel.Debug }),
};
```

## Logging database queries

To log database queries, set the `logging` property of the `dbConnectionOptions` as well as setting the logger to `Debug` level.

```ts title="src/vendure-config.ts"
import { DefaultLogger, LogLevel, VendureConfig } from '@vendure/core';

const config: VendureConfig = {
    // ...
    logger: new DefaultLogger({ level: LogLevel.Debug }),
    dbConnectionOptions: {
        // ... etc
        logging: true,
        
        // You can also specify which types of DB events to log:
        // logging: ['error', 'warn', 'schema', 'query', 'info', 'log'],
    },
};
```

More information about the `logging` option can be found in the [TypeORM logging documentation](https://typeorm.io/logging).

## Logging in your own plugins

When you extend Vendure by creating your own plugins, it's a good idea to log useful information about what your plugin is doing. To do this, you need to import the [Logger](/reference/typescript-api/logger/) class from `@vendure/core` and use it in your plugin:

```ts title="src/plugins/my-plugin/my.plugin.ts"
import { Logger } from '@vendure/core';

// It is customary to define a logger context for your plugin
// so that the log messages can be easily identified.
const loggerCtx = 'MyPlugin';

// somewhere in your code
Logger.info(`My plugin is doing something!`, loggerCtx);
```


---

---
title: "Breaking API Changes"
sidebar_position: 3
---

# Breaking API Changes

## Breaks from updated dependencies

### TypeScript
- v2 is built on TypeScript **v4.9.5**. You should update your TypeScript version to match this. Doing so is quite likely to reveal new compiler errors (as is usual with TypeScript minor release updates).
- If you are using `ts-node`, update it to the latest version
- If you are targeting `ES2022` or `ESNEXT` in your `tsconfig.json`, you'll need to set `"useDefineForClassFields": false`. See [this issue](https://github.com/vendure-ecommerce/vendure/issues/2099) for more context.

### Apollo Server & GraphQL
If you have any custom ApolloServerPlugins, the plugin methods must now return a Promise. Example:

```diff
export class TranslateErrorsPlugin implements ApolloServerPlugin {
   constructor(private i18nService: I18nService) {}

-  requestDidStart(): GraphQLRequestListener {
+  async requestDidStart(): Promise<GraphQLRequestListener> {
     return {
-      willSendResponse: requestContext => {
+      willSendResponse: async requestContext => {
         const { errors, context } = requestContext;
         if (errors) {
           (requestContext.response as any).errors = errors.map(err => {
             return this.i18nService.translateError(context.req, err as GraphQLError) as any;
           });
         }
       },
     };
   }
}
```

With the update to GraphQL v16, you might run into issues with other packages in the GraphQL ecosystem that also depend on the `graphql` package, such as `graphql-code-generator`. In this case these packages will also need to be updated.

For instance, if you are using the "typescript-compatibility" plugin to generate namespaced types, you'll need to drop this, as it is [no longer maintained](https://the-guild.dev/blog/whats-new-in-graphql-codegen-v2#typescript-compatibility).

### TypeORM
TypeORM 0.3.x introduced a large number of breaking changes. For a complete guide, see the [TypeORM v0.3.0 release notes](https://github.com/typeorm/typeorm/releases/tag/0.3.0). 

Here are the main API changes you'll likely need to make:

- You can no longer compare to `null`, you need to use the new `IsNull()` helper:
    ```diff
    + import { IsNull } from 'typeorm';

    - .find({ where: { deletedAt: null } })
    + .find({ where: { deletedAt: IsNull() } })
    ```
- The `findOne()` method returns `null` rather than `undefined` if a record is not found.
- The `findOne()` method no longer accepts an id argument. Lookup based on id must be done with a `where` clause:
    ```diff
    - .findOne(variantId)
    + .findOne({ where: { id: variantId } })
    ```
- Where clauses must use an entity id rather than passing an entity itself:
    ```diff
    - .find({ where: { user } })
    + .find({ where: { user: { id: user.id } } })
    ```
- The `findByIds()` method has been deprecated. Use the new `In` helper instead:
    ```diff
    + import { In } from 'typeorm';

    - .findByIds(ids)
    + .find({ where: { id: In(ids) } })
    ```

## Vendure TypeScript API Changes

### Custom Order / Fulfillment / Payment processes

In v2, the hard-coded states & transition logic for the Order, Fulfillment and Payment state machines has been extracted from the core services and instead reside in a default `OrderProcess`, `FulfillmentProcess` and `PaymentProcess` object. This allows you to _fully_ customize these flows without having to work around the assumptions & logic implemented by the default processes.

What this means is that if you are defining a custom process, you'll now need to explicitly add the default process to the array.

```diff
+ import { defaultOrderProcess } from '@vendure/core';

orderOptions: {
-  process: [myCustomOrderProcess],
+  process: [defaultOrderProcess, myCustomOrderProcess],
}
```

Also note that `shippingOptions.customFulfillmentProcess` and `paymentOptions.customPaymentProcess` are both now renamed to `process`. The old names are still usable but are deprecated.

### OrderItem no longer exists

As a result of [#1981](https://github.com/vendure-ecommerce/vendure/issues/1981), the `OrderItem` entity no longer exists. The function and data of `OrderItem` is now transferred to `OrderLine`. As a result, the following APIs which previously used OrderItem arguments have now changed:

- `FulfillmentHandler`
- `ChangedPriceHandlingStrategy`
- `PromotionItemAction`
- `TaxLineCalculationStrategy`

If you have implemented any of these APIs, you'll need to check each one, remove the `OrderItem` argument from any methods that are using it,
and update any logic as necessary.

You may also be joining the OrderItem relation in your own TypeORM queries, so you'll need to check for code like this:

```diff
const order = await this.connection
  .getRepository(Order)
  .createQueryBuilder('order')
  .leftJoinAndSelect('order.lines', 'line')
- .leftJoinAndSelect('line.items', 'items')
```

or 

```diff
const order = await this.connection
  .getRepository(Order)
  .findOne(ctx, orderId, {
-    relations: ['lines', 'lines.items'],
+    relations: ['lines'],
  });
```

### ProductVariant stock changes

With [#1545](https://github.com/vendure-ecommerce/vendure/issues/1545) we have changed the way we model stock levels in order to support multiple stock locations. This means that the `ProductVariant.stockOnHand` and `ProductVariant.stockAllocated` properties no longer exist on the `ProductVariant` entity in TypeScript.

Instead, this information is now located at `ProductVariant.stockLevels`, which is an array of [StockLevel](/reference/typescript-api/entities/stock-level) entities.

### New return type for Channel, TaxCategory & Zone lists

- The `ChannelService.findAll()` method now returns a `PaginatedList<Channel>` instead of `Channel[]`. 
- The `channels` GraphQL query now returns a `PaginatedList` rather than a simple array of Channels.
- The `TaxCategoryService.findAll()` method now returns a `PaginatedList<TaxCategory>` instead of `TaxCategory[]`.
- The `taxCategories` GraphQL query now returns a `PaginatedList` rather than a simple array of TaxCategories.
- The `ZoneService.findAll()` method now returns a `PaginatedList<Zone>` instead of `Zone[]`. The old behaviour of `ZoneService.findAll()` (all Zones, cached for rapid access) can now be found under the new `ZoneService.getAllWithMembers()` method.
- The `zones` GraphQL query now returns a `PaginatedList` rather than a simple array of Zones. 

### Admin UI changes

If you are using the `@vendure/ui-devkit` package to generate custom ui extensions, here are the breaking changes to be aware of:

- As part of the major refresh to the Admin UI app, certain layout elements had be changed which can cause your custom routes to look bad. Wrapping all your custom pages in `<vdr-page-block>` (or `<div class="page-block">` if not built with Angular components) will improve things. There will soon be a comprehensive guide published on how to create seamless ui extensions that look just like the built-in screens.
- If you use any of the scoped method of the Admin UI `DataService`, you might find that some no longer exist. They are now deprecated and will eventually be removed. Use the `dataService.query()` and `dataService.mutation()` methods only, passing your own GraphQL documents:
   ```ts
    // Old way
   this.dataService.product.getProducts().single$.subscribe(...);
   ```
   ```ts
    // New way
   const GET_PRODUCTS = gql`
     query GetProducts {
       products {
         items {
           id
           name
           # ... etc
         }
       }
     }
   `;
   this.dataService.query(GET_PRODUCTS).single$.subscribe(...);
   ```
- The Admin UI component `vdr-product-selector` has been renamed to `vdr-product-variant-selector` to more accurately represent what it does. If you are using `vdr-product-selector` if any ui extensions code, update it to use the new selector.

### Other breaking API changes
- **End-to-end tests using Jest** will likely run into issues due to our move towards using some dependencies that make use of ES modules. We have found the best solution to be to migrate tests over to [Vitest](https://vitest.dev), which can handle this and is also significantly faster than Jest. See the updated [Testing guide](/guides/developer-guide/testing) for instructions on getting started with Vitest.
- Internal `ErrorResult` classes now take a single object argument rather than multiple args.
- All monetary values are now represented in the GraphQL APIs with a new `Money` scalar type. If you use [graphql-code-generator](https://the-guild.dev/graphql/codegen), you'll want to tell it to treat this scalar as a number:
    ```ts
    import { CodegenConfig } from '@graphql-codegen/cli'
 
    const config: CodegenConfig = {
      schema: 'http://localhost:3000/shop-api',
      documents: ['src/**/*graphql.ts'],
      config: {
        scalars: {
          Money: 'number',
        },
      },
      generates: {
        // .. 
      }
    };
    ```
- A new `Region` entity has been introduced, which is a base class for `Country` and the new `Province` entity. The `Zone.members` property is now an array of `Region` rather than `Country`, since Zones may now be composed of both countries and provinces. If you have defined any custom fields on `Country`, you'll need to change it to `Region` in your custom fields config.
- If you are using the **s3 storage strategy** of the AssetServerPlugin, it has been updated to use v3 of the AWS SDKs. This update introduces an [improved modular architecture to the AWS sdk](https://aws.amazon.com/blogs/developer/modular-packages-in-aws-sdk-for-javascript/), resulting in smaller bundle sizes. You need to install the `@aws-sdk/client-s3` & `@aws-sdk/lib-storage` packages, and can remove the `aws-sdk` package. If you are using it in combination with MinIO, you'll also need to rename a config property and provide a region:
   ```diff
   nativeS3Configuration: {
      endpoint: 'http://localhost:9000',
   -  s3ForcePathStyle: true,
   +  forcePathStyle: true,
      signatureVersion: 'v4',
   +  region: 'eu-west-1',
   }
   ```
- The **Stripe plugin** has been made channel aware. This means your api key and webhook secret are now stored in the database, per channel, instead of environment variables.
   To migrate to v2 of the Stripe plugin from @vendure/payments you need to:
  1. Remove the apiKey and webhookSigningSecret from the plugin initialization in vendure-config.ts:
       ```diff
       StripePlugin.init({
       -  apiKey: process.env.YOUR_STRIPE_SECRET_KEY,
       -  webhookSigningSecret: process.env.YOUR_STRIPE_WEBHOOK_SIGNING_SECRET,
          storeCustomersInStripe: true,
       }),
       ```
  2. Start the server and login as administrator. For each channel that you'd like to use Stripe payments, you need to create a payment method with payment handler Stripe payment and the apiKey and webhookSigningSecret belonging to that channel's Stripe account.
- If you are using the **BullMQJobQueuePlugin**, the minimum Redis recommended version is 6.2.0.
- The `WorkerHealthIndicator` which was deprecated in v1.3.0 has been removed, as well as the `jobQueueOptions.enableWorkerHealthCheck` config option.
- The `CustomerGroupEntityEvent` (fired on creation, update or deletion of a CustomerGroup) has been renamed to `CustomerGroupEvent`, and the former `CustomerGroupEvent` (fired when Customers are added to or removed from a group) has been renamed to `CustomerGroupChangeEvent`.
- We introduced the [plugin compatibility API](/guides/developer-guide/plugins/#step-7-specify-compatibility) to allow plugins to indicate what version of Vendure they are compatible with. To avoid bootstrap messages you should add this property to your plugins.


---

---
title: "Database Migration"
sidebar_position: 2
---

# v2 Database Migration

Vendure v2 introduces a number of breaking changes to the database schema, some of which require quite complex migrations in order to preserve existing data. To make this process as smooth as possible, we have created a migration tool which will handle the hard parts for you!

:::warning
**Important!** It is _critical_ that you back up your production data prior to attempting this migration.

**Note for MySQL/MariaDB users:** transactions for migrations are [not supported by these databases](https://dev.mysql.com/doc/refman/5.7/en/cannot-roll-back.html). This means that if the migration fails for some reason, the statements that have executed will not get rolled back, and your DB schema can be left in an inconsistent state from which is it can be hard to recover. Therefore, it is doubly critical that you have a good backup that you can easily restore prior to attempting this migration.
:::

1. Make sure all your Vendure packages to the latest v2 versions.
2. Use your package manager to install the [v2 migration tool](https://github.com/vendure-ecommerce/v2-migration-tool): `npm install @vendure/migrate-v2`
    - Note, if you run into the error `"Cannot find module '@ardatan/aggregate-error'"`, delete node_modules and the lockfile and reinstall.
3. Add the `MigrationV2Plugin` to your plugins array:
   ```ts
   import { MigrationV2Plugin } from '@vendure/migrate-v2';
   
   //...
   const config: VendureConfig = {
     //..
     plugins: [
       MigrationV2Plugin,
     ]
   }
   ```
   The sole function of this plugin is to temporarily remove some "NOT NULL" constraints from certain columns, which allows us to run the next part of the migration.
4. Generate a new migration file, `npm run migration:generate v2`
5. Edit the newly-created migration file by following the comments in these examples: 
    - [postgres](https://github.com/vendure-ecommerce/v2-migration-tool/blob/master/src/migrations/1686649098749-v201-postgres.ts)
    - [mysql](https://github.com/vendure-ecommerce/v2-migration-tool/blob/master/src/migrations/1686655918823-v201-mysql.ts)

   In your migrations files, you'll import the `vendureV2Migrations` from `@vendure/migrate-v2`.
6. Run the migration with `npm run migration:run`.
7. Upon successful migration, remove the `MigrationV2Plugin` from your plugins array, and generate _another_ migration. This one will add back the missing "NOT NULL" constraints now that all your data has been successfully migrated.


---

---
title: "Migrating from v1"
weight: 2
sidebar_position: 1
---

# Migrating from Vendure 1 to 2

This section contains guides for migrating from Vendure v1 to v2.

There are a number of breaking changes between the two versions, which are due to a few major factors:

1. To support new features such as multi-vendor marketplace APIs and multiple stock locations, we had to make some changes to the database schema and some of the internal APIs.
2. We have updated all of our major dependencies to their latest versions. Some of these updates involve breaking changes in the dependencies themselves, and in those cases where you are using those dependencies directly (most notably TypeORM), you will need to make the corresponding changes to your code.
3. We have removed some old APIs which were previously marked as "deprecated".

## Migration steps

Migration will consist of these main steps:

1. **Update your Vendure dependencies** to the latest versions
   ```diff
   {
     // ...
     "dependencies": {
   -    "@vendure/common": "1.9.7",
   -    "@vendure/core": "1.9.7",
   +    "@vendure/common": "2.0.0",
   +    "@vendure/core": "2.0.0",
        // etc.
     },
     "devDependencies": {
   -    "typescript": "4.3.5",
   +    "typescript": "4.9.5",
        // etc.
     }
   }
   ```
2. **Migrate your database**. This is covered in detail in the [database migration section](/guides/developer-guide/migrating-from-v1/database-migration).
3. **Update your custom code** (configuration, plugins, admin ui extensions) to handle the breaking changes. Details of these changes are covered in the [breaking API changes section](/guides/developer-guide/migrating-from-v1/breaking-api-changes).
4. **Update your storefront** to handle some small breaking changes in the Shop GraphQL API. See the [storefront migration section](/guides/developer-guide/migrating-from-v1/storefront-migration) for details.


---

---
title: "Storefront Migration"
sidebar_position: 4
---

# Storefront migration

There are relatively few breaking changes that will affect the storefront.

- The `setOrderShippingMethod` mutation now takes an array of shipping method IDs rather than just a single one. This is so we can support multiple shipping methods per Order.
   ```diff
   -mutation setOrderShippingMethod($shippingMethodId: ID!) {
   +mutation setOrderShippingMethod($shippingMethodId: [ID!]!) {
     setOrderShippingMethod(shippingMethodId: $shippingMethodId) {
       # ... etc
     }
   } 
   ```
- The `OrderLine.fulfillments` field has been changed to `OrderLine.fulfillmentLines`. Your storefront may be using this when displaying the details of an Order.
- If you are using the `graphql-code-generator` package to generate types for your storefront, all monetary values such as `Order.totalWithTax` or `ProductVariant.priceWithTax` are now represented by the new `Money` scalar rather than by an `Int`. You'll need to tell your codegen about this scalar and configure it to be interpreted as a number type:
   ```diff
   documents:
     - "app/**/*.{ts,tsx}"
     - "!app/generated/*"
   +config:
   +  scalars:
   +    Money: number
   generates:
     # ... etc
   ```


---

---
title: "Migrations"
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Database migrations are needed whenever the database schema changes. This can be caused by:

* changes to the [custom fields](/guides/developer-guide/custom-fields/) configuration
* new [database entities defined by plugins](/guides/developer-guide/database-entity/)
* occasional changes to the core Vendure database schema when updating to newer versions

## Synchronize vs migrate

TypeORM (which Vendure uses to interact with the database) has a `synchronize` option which, when set to `true`, will automatically update your database schema to reflect the current Vendure configuration. This is equivalent to automatically generating and running a migration _every time_ the server starts up.

This is convenient while developing, but **should not be used in production**, since a misconfiguration could potentially delete production data. In this case, migrations should be used.

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';

export const config: VendureConfig = {
    // ...
    dbConnectionOptions: {
        // ...
        // highlight-next-line
        synchronize: false,
    }
};
```

## Migration workflow

This section assumes a standard Vendure installation based on `@vendure/create`. 

Let's assume you have defined a new "keywords" custom field on the Product entity. The next time you start your server you'll see a message like this:

```bash
[server] Your database schema does not match your current configuration. Generate a new migration for the following changes:
[server]  - ALTER TABLE "product" ADD "customFieldsKeywords" character varying(255)
```

Since we have `synchronize` set to `false`, we need to generate a migration to apply these changes to the database. The workflow for this is as follows:

### 1. Generate a migration

:::cli
Run `npx vendure migrate` and select "Generate a new migration"
:::

### 2. Check the migration file

This will have created a new migration file in the `src/migrations` directory. Open this file and check that it looks correct. It should look something like this:

```ts title="src/migrations/1690558104092-add-keywords-field.ts"
import {MigrationInterface, QueryRunner} from "typeorm";

export class addKeywordsField1690558104092 implements MigrationInterface {

   public async up(queryRunner: QueryRunner): Promise<any> {
        await queryRunner.query(`ALTER TABLE "product" ADD "customFieldsKeywords" character varying(255)`, undefined);
   }

   public async down(queryRunner: QueryRunner): Promise<any> {
        await queryRunner.query(`ALTER TABLE "product" DROP COLUMN "customFieldsKeywords"`, undefined);
   }

}
```

The `up()` function is what will be executed when the migration is run. The `down()` function is what will be executed if the migration is reverted. In this case, the `up()` function is adding a new column to the `product` table, and the `down()` function is removing it.

:::note
The exact query will depend on the database you are using. The above example is for PostgreSQL.
:::

### 3. Run the migration

Assuming the migration file looks correct, the next time you start the server, the migration will
be run automatically. This is because the `runMigrations` function is called in the `src/index.ts` file:

```ts title="src/index.ts"
import { bootstrap, runMigrations } from '@vendure/core';
import { config } from './vendure-config';

// highlight-next-line
runMigrations(config)
    .then(() => bootstrap(config))
    .catch(err => {
        console.log(err);
    });
```

It is also possible to run the migration manually without starting the server:

:::cli
Run `npx vendure migrate` and select "Run pending migrations"
:::

:::caution
TypeORM will attempt to run each migration inside a transaction. This means that if one of the migration commands fails, then the entire transaction will be rolled back to its original state.

_However_ this is **not supported by MySQL / MariaDB**. This means that when using MySQL or MariaDB, errors in your migration script could leave your database in a broken or inconsistent state. Therefore it is **critical** that you first create a backup of your database before running a migration.

You can read more about this issue in [typeorm/issues/7054](https://github.com/typeorm/typeorm/issues/7054)
:::

## Migrations in-depth

Now we'll dive into what's going on under the hood.

Vendure exposes a some helper function which wrap around the underlying [TypeORM migration functionality](https://typeorm.io/migrations). The 
reason for using these helper functions rather than using the TypeORM CLI directly is that Vendure generates additional 
schema information based on custom fields and plugin configurations which are not available to the TypeORM CLI.

In a standard Vendure installation prior to v2.2.0, you'll see the following migration script in your project root directory.
Running the `vendure migrate` command also uses a very similar script internally.

```ts title="migration.ts"
import { generateMigration, revertLastMigration, runMigrations } from '@vendure/core';
import { Command } from 'commander';

import { config } from './src/vendure-config';

const program = new Command();

program
    .command('generate <name>')
    .description('Generate a new migration file with the given name')
    .action(name => {
        return generateMigration(config, { name, outputDir: './src/migrations' });
    });

program
    .command('run')
    .description('Run all pending migrations')
    .action(() => {
        return runMigrations(config);
    });

program
    .command('revert')
    .description('Revert the last applied migration')
    .action(() => {
        return revertLastMigration(config);
    });

program.parse(process.argv);
```

and a set of scripts in your `package.json` file:

```json
{
  // ...
  "scripts": {
    "migration:generate": "ts-node migration.ts generate",
    "migration:run": "ts-node migration.ts run",
    "migration:revert": "ts-node migration.ts revert"
  }
}
```

When running and reverting migrations, Vendure is looking for migration files in the directory specified by the `dbConnectionOptions.migrations` option is set in your VendureConfig:

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';
import path from 'path';

export const config: VendureConfig = {
    // ...
    dbConnectionOptions: {
        // ...
        // highlight-next-line
        migrations: [path.join(__dirname, './migrations/*.+(js|ts)')],
    }
};
```

TypeORM keeps track of which migrations have been run by creating a new `migrations` table in your database, and each time a migration is successfully run
it adds a row to this table with the name of the migration class and a timestamp. This prevents the same migration from being run twice, and also allows
TypeORM to know which migration to revert when the `revertLastMigration` function is called.

![Migrations table](./migration.webp)

These are the underlying function exposed by Vendure which are used to generate, run and revert migrations:

- [`generateMigration` function](/reference/typescript-api/migration/generate-migration/)
- [`runMigrations` function](/reference/typescript-api/migration/run-migrations/)
- [`revertLastMigration` function](/reference/typescript-api/migration/revert-last-migration/)

### Reverting a migration

The `revertLastMigration` function will revert the last applied migration by applying the `down()` method. If run again it will then revert the one before that, and so on.
In doing so, it will also remove the corresponding row from the `migrations` table.



---

---
title: "Nest Devtools"
---

The NestJS core team have built a [powerful set of dev tools](https://docs.nestjs.com/devtools/overview) which can be used to inspect, analyze and debug NestJS applications.
Since a Vendure server is a NestJS application, these tools can be used to debug your Vendure application.

:::note
Nest Devtools is a paid service. You can [sign up for a free trial](https://devtools.nestjs.com/).
:::

## Installation

First you'll need to install the `@nestjs/devtools-integration` package:

```bash
npm i @nestjs/devtools-integration
```

## Configuration

Next you need to create a plugin which imports the `DevToolsModule` and adds it to the `imports` array:

```ts title="src/plugins/devtools/devtools-plugin.ts"
import { VendurePlugin } from '@vendure/core';
import { DevtoolsModule } from '@nestjs/devtools-integration';

@VendurePlugin({
    imports: [
        DevtoolsModule.register({
            // The reason we are checking the NODE_ENV environment 
            // variable here is that you should never use this module in production!
            http: process.env.NODE_ENV !== 'production',
        }),
    ],
})
class DevtoolsPlugin {}
```

Now we need to add this plugin to the `plugins` array in the `VendureConfig`. We need to make sure we are
only adding it to the server config, and not the worker, otherwise we will get a port config when
running the server and worker at the same time.

Lastly we must set the `snapshot` option when bootstrapping the server. Note: this is only possible
with Vendure v2.2 or later.

```ts title="src/index.ts"
import { bootstrap } from '@vendure/core';
import { config } from './vendure-config';

const configWithDevtools = {
    ...config,
    plugins: [
        ...config.plugins,
        DevtoolsPlugin,
    ],
};

bootstrap(configWithDevtools, {
    nestApplicationOptions: { snapshot: true } 
})
    .catch(err => {
        console.log(err);
        process.exit(1);
    });
```

## Usage

Now you can start the server, and navigate to [devtools.nestjs.com](https://devtools.nestjs.com/) to start view your
Vendure server in the Nest Devtools dashboard.

![Nest Devtools graphql explorer](./nest-devtools-graph.webp)
![Nest Devtools bootstrap performance](./nest-devtools-bootstrap-perf.webp)

---

---
title: "Vendure Overview"
sidebar_position: 2
---

Read this page to gain a high-level understanding of Vendure and concepts you will need to know to build your application.

## Architecture

Vendure is a headless e-commerce platform. By "headless" we mean that it exposes all of its functionality via APIs. Specifically, Vendure features two GraphQL APIs: one for storefronts (Shop API) and the other for administrative functions (Admin API).

These are the major parts of a Vendure application:

* **Server**: The Vendure server is the part that handles requests coming in to the GraphQL APIs. It serves both the [Shop API](/reference/graphql-api/shop/queries) and [Admin API](/reference/graphql-api/admin/queries), and can send jobs to the Job Queue to be processed by the Worker.
* **Worker**: The Worker runs in the background and deals with tasks such as updating the search index, sending emails, and other tasks which may be long-running, resource-intensive or require retries.
* **Admin UI**: The Admin UI is how shop administrators manage orders, customers, products, settings and so on. It is not actually part of the Vendure core, but is provided as a plugin (the [AdminUiPlugin](/reference/core-plugins/admin-ui-plugin/)) which is installed for you in a standard Vendure installation. The Admin UI can be further extended to support custom functionality, as detailed in the [Extending the Admin UI](/guides/extending-the-admin-ui/getting-started/) section
* **Storefront**: With headless commerce, you are free to implement your storefront exactly as you see fit, unconstrained by the back-end, using any technologies that you like. To make this process easier, we have created a number of [storefront starter kits](/guides/storefront/storefront-starters/), as well as [guides on building a storefront](/guides/storefront/connect-api/).

![./Vendure_docs-architecture.webp](./Vendure_docs-architecture.webp) 

## Technology stack

Vendure is built on the following open-source technologies:

- **SQL Database**: Vendure requires an SQL database compatible with [TypeORM](https://typeorm.io/). Officially we support **PostgreSQL**, **MySQL/MariaDB** and **SQLite** but Vendure can also be used with API-compatible variants such [Amazon Aurora](https://aws.amazon.com/rds/aurora/), [CockroachDB](https://www.cockroachlabs.com/), or [PlanetScale](https://planetscale.com/).
- **TypeScript & Node.js**: Vendure is written in [TypeScript](https://www.typescriptlang.org/) and runs on [Node.js](https://nodejs.org).
- **NestJS**: The underlying framework is [NestJS](https://nestjs.com/), which is a full-featured application development framework for Node.js. Building on NestJS means that Vendure benefits from the well-defined structure and rich feature-set and ecosystem that NestJS provides.
- **GraphQL**: The Shop and Admin APIs use [GraphQL](https://graphql.org/), which is a modern API technology which allows you to specify the exact data that your client application needs in a convenient and type-safe way. Internally we use [Apollo Server](https://www.apollographql.com/docs/apollo-server/) to power our GraphQL APIs.
- **Angular**: The Admin UI is built with [Angular](https://angular.io/), a popular, stable application framework from Google. Note that you do not need to know Angular to use Vendure, and UI extensions can even be written in the front-end framework of your choice, such as React or Vue.

## Design principles

Vendure is designed to be:

- **Flexible**: Vendure is designed to be flexible enough to support a wide range of e-commerce use-cases, while taking care of the common functionality for you. It is not a "one-size-fits-all" solution, but rather a framework which you can extend and customize to suit your needs.
- **Extensible**: A typical e-commerce application needs to integrate with many external systems for payments, shipping, inventory management, email sending, and so on. Vendure makes heavy use of the **strategy pattern** - a software design pattern which allows you to replace default behaviors with your own custom implementations as needed.
- **Modular**: Vendure is built with a modular architecture, where each unit of functionality of your application is encapsulated in a **plugin**. This makes it easy to add or remove functionality as needed, and to share plugins with the community.
- **Type-safe**: Vendure is written in TypeScript, which means that you get the benefits of static type-checking and code completion in your IDE. Our use of GraphQL for our APIs brings static typing to the API layer, enabling rapid development with type-safety across the entire stack.




---

---
title: 'Plugins'
sidebar_position: 6
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

The heart of Vendure is its plugin system. Plugins not only allow you to instantly add new functionality to your
Vendure server via third-part npm packages, they are also the means by which you build out the custom business
logic of your application.

Plugins in Vendure allow one to:

- Modify the VendureConfig object, such as defining custom fields on existing entities.
- Extend the GraphQL APIs, including modifying existing types and adding completely new queries and mutations.
- Define new database entities and interact directly with the database.
- Interact with external systems that you need to integrate with.
- Respond to events such as new orders being placed.
- Trigger background tasks to run on the worker process.

… and more!

In a typical Vendure application, custom logic and functionality is implemented as a set of plugins
which are usually independent of one another. For example, there could be a plugin for each of the following:
wishlists, product reviews, loyalty points, gift cards, etc.
This allows for a clean separation of concerns and makes it easy to add or remove functionality as needed.

## Core Plugins

Vendure provides a set of core plugins covering common functionality such as assets handling,
email sending, and search. For documentation on these, see the [Core Plugins reference](/reference/core-plugins/).

## Plugin basics

Here's a bare-minimum example of a plugin:

```ts title="src/plugins/avatar-plugin/avatar.plugin.ts"
import { LanguageCode, PluginCommonModule, VendurePlugin } from '@vendure/core';

@VendurePlugin({
    imports: [PluginCommonModule],
    configuration: config => {
        config.customFields.Customer.push({
            type: 'string',
            name: 'avatarUrl',
            label: [{ languageCode: LanguageCode.en, value: 'Avatar URL' }],
            list: true,
        });
        return config;
    },
})
export class AvatarPlugin {}
```

This plugin does one thing only: it adds a new custom field to the `Customer` entity.

The plugin is then imported into the `VendureConfig`:

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';
import { AvatarPlugin } from './plugins/avatar-plugin/avatar.plugin';

export const config: VendureConfig = {
    // ...
    // highlight-next-line
    plugins: [AvatarPlugin],
};
```

The key feature is the `@VendurePlugin()` decorator, which marks the class as a Vendure plugin and accepts a configuration
object on the type [`VendurePluginMetadata`](/reference/typescript-api/plugin/vendure-plugin-metadata/).

A VendurePlugin is actually an enhanced version of a [NestJS Module](https://docs.nestjs.com/modules), and supports
all the metadata properties that NestJS modules support:

- `imports`: Allows importing other NestJS modules in order to make use of their exported providers.
- `providers`: The providers (services) that will be instantiated by the Nest injector and that may
    be shared across this plugin.
- `controllers`: Controllers allow the plugin to define REST-style endpoints.
- `exports`: The providers which will be exported from this plugin and made available to other plugins.

Additionally, the `VendurePlugin` decorator adds the following Vendure-specific properties:

- `configuration`: A function which can modify the `VendureConfig` object before the server bootstraps.
- `shopApiExtensions`: Allows the plugin to extend the GraphQL Shop API with new queries, mutations, resolvers & scalars.
- `adminApiExtensions`: Allows the plugin to extend the GraphQL Admin API with new queries, mutations, resolvers & scalars.
- `entities`: Allows the plugin to define new database entities.
- `compatibility`: Allows the plugin to declare which versions of Vendure it is compatible with.

:::info
Since a Vendure plugin is a superset of a NestJS module, this means that many NestJS modules are actually
valid Vendure plugins!
:::

## Plugin lifecycle

Since a VendurePlugin is built on top of the NestJS module system, any plugin (as well as any providers it defines)
can make use of any of the [NestJS lifecycle hooks](https://docs.nestjs.com/fundamentals/lifecycle-events):

- onModuleInit
- onApplicationBootstrap
- onModuleDestroy
- beforeApplicationShutdown
- onApplicationShutdown

:::caution
Note that lifecycle hooks are run in both the server and worker contexts.
If you have code that should only run either in the server context or worker context,
you can inject the [ProcessContext provider](/reference/typescript-api/common/process-context/).
:::

### Configure

Another hook that is not strictly a lifecycle hook, but which can be useful to know is the [`configure` method](https://docs.nestjs.com/middleware#applying-middleware) which is
used by NestJS to apply middleware. This method is called _only_ for the server and _not_ for the worker, since middleware relates
to the network stack, and the worker has no network part.

```ts
import { MiddlewareConsumer, NestModule } from '@nestjs/common';
import { EventBus, PluginCommonModule, VendurePlugin } from '@vendure/core';
import { MyMiddleware } from './api/my-middleware';

@VendurePlugin({
    imports: [PluginCommonModule]
})
export class MyPlugin implements NestModule {

  configure(consumer: MiddlewareConsumer) {
    consumer
      .apply(MyMiddleware)
      .forRoutes('my-custom-route');
  }
}
```

## Create a Plugin via CLI

:::cli
Run the `npx vendure add` command, and select "Create a new Vendure plugin".

This will guide you through the creation of a new plugin and automate all aspects of the process.

This is the recommended way of creating a new plugin.
:::

## Writing a plugin from scratch

Although the [Vendure CLI](/guides/developer-guide/cli/) is the recommended way to create a new plugin, it can be useful to understand the process of creating
a plugin manually.

Vendure **plugins** are used to extend the core functionality of the server. Plugins can be pre-made functionality that you can install via npm, or they can be custom plugins that you write yourself.

For any unit of functionality that you need to add to your project, you'll be creating a Vendure plugin. By convention, plugins are stored in the `plugins` directory of your project. However, this is not a requirement, and you are free to arrange your plugin files in any way you like.

```txt
├──src
    ├── index.ts
    ├── vendure-config.ts
    ├── plugins
        ├── reviews-plugin
        ├── cms-plugin
        ├── wishlist-plugin
        ├── stock-sync-plugin
```

:::info
For a complete working example of a Vendure plugin, see the [real-world-vendure Reviews plugin](https://github.com/vendure-ecommerce/real-world-vendure/tree/master/src/plugins/reviews)

You can also use the [Vendure CLI](/guides/developer-guide/cli) to quickly scaffold a new plugin.
:::

In this guide, we will implement a simple but fully-functional **wishlist plugin** step-by-step. The goal of this plugin is to allow signed-in customers to add products to a wishlist, and to view and manage their wishlist.

### Step 1: Create the plugin file

We'll start by creating a new directory to house our plugin, add create the main plugin file:

```txt
├──src
    ├── index.ts
    ├── vendure-config.ts
    ├── plugins
        // highlight-next-line
        ├── wishlist-plugin
            // highlight-next-line
            ├── wishlist.plugin.ts
```

```ts title="src/plugins/wishlist-plugin/wishlist.plugin.ts"
import { PluginCommonModule, VendurePlugin } from '@vendure/core';

@VendurePlugin({
    imports: [PluginCommonModule],
})
export class WishlistPlugin {}
```

The `PluginCommonModule` will be required in all plugins that you create. It contains the common services that are exposed by Vendure Core, allowing you to inject them into your plugin's services and resolvers.

### Step 2: Define an entity

Next we will define a new database entity to store the wishlist items. Vendure uses [TypeORM](https://typeorm.io/) to manage the database schema, and an Entity corresponds to a database table.

First let's create the file to house the entity:

```txt
├── wishlist-plugin
    ├── wishlist.plugin.ts
    ├── entities
        // highlight-next-line
        ├── wishlist-item.entity.ts
```

By convention, we'll store the entity definitions in the `entities` directory of the plugin. Again, this is not a requirement, but it is a good way to keep your plugin organized.

```ts title="src/plugins/wishlist-plugin/entities/wishlist-item.entity.ts"
import { DeepPartial, ID, ProductVariant, VendureEntity, EntityId } from '@vendure/core';
import { Entity, ManyToOne } from 'typeorm';

@Entity()
export class WishlistItem extends VendureEntity {
    constructor(input?: DeepPartial<WishlistItem>) {
        super(input);
    }

    @ManyToOne(type => ProductVariant)
    productVariant: ProductVariant;

    @EntityId()
    productVariantId: ID;
}
```

Let's break down what's happening here:

-   The `WishlistItem` entity extends the [`VendureEntity` class](/reference/typescript-api/entities/vendure-entity/). This is a base class which provides the `id`, `createdAt` and `updatedAt` fields, and all custom entities should extend it.
-   The `@Entity()` decorator marks this class as a TypeORM entity.
-   The `@ManyToOne()` decorator defines a many-to-one relationship with the `ProductVariant` entity. This means that each `WishlistItem` will be associated with a single `ProductVariant`.
-   The `productVariantId` column is not strictly necessary, but it allows us to always have access to the ID of the related `ProductVariant` without having to load the entire `ProductVariant` entity from the database.
-   The `constructor()` is used to create a new instance of the entity. This is not strictly necessary, but it is a good practice to define a constructor which takes a `DeepPartial` of the entity as an argument. This allows us to create new instances of the entity using the `new` keyword, passing in a plain object with the desired properties.

Next we need to register this entity with our plugin:

```ts title="src/plugins/wishlist-plugin/wishlist.plugin.ts"
import { PluginCommonModule, VendurePlugin } from '@vendure/core';
import { WishlistItem } from './entities/wishlist-item.entity';

@VendurePlugin({
    imports: [PluginCommonModule],
    entities: [WishlistItem],
})
export class WishlistPlugin {}
```

### Step 3: Add a custom field to the Customer entity

We'll now define a new custom field on the Customer entity which will store a list of WishlistItems. This will allow us to easily query for all wishlist items associated with a particular customer.

Custom fields are defined in the VendureConfig object, and in a plugin we use the `configuration` function to modify the config object:

```ts title="src/plugins/wishlist-plugin/wishlist.plugin.ts"
import { PluginCommonModule, VendurePlugin } from '@vendure/core';
import { WishlistItem } from './entities/wishlist-item.entity';

@VendurePlugin({
    imports: [PluginCommonModule],
    entities: [WishlistItem],
    configuration: config => {
        config.customFields.Customer.push({
            name: 'wishlistItems',
            type: 'relation',
            list: true,
            entity: WishlistItem,
            internal: true,
        });
        return config;
    },
})
export class WishlistPlugin {}
```

In this snippet we are pushing a new custom field definition onto the `Customer` entity's `customFields` array, and defining this new field as a list (array) of `WishlistItem` entities. Internally, this will tell TypeORM to update the database schema to store this new field. We set `internal: true` to indicate that this field should not be directly exposed to the GraphQL API as `Customer.customFields.wishlistItems`, but instead should be accessed via a custom resolver we will define later.

In order to make use of this custom field in a type-safe way, we can tell TypeScript about this field in a new file:

```txt
├── wishlist-plugin
    ├── wishlist.plugin.ts
    // highlight-next-line
    ├── types.ts
```

```ts title="src/plugins/wishlist-plugin/types.ts"
import { WishlistItem } from './entities/wishlist-item.entity';

declare module '@vendure/core/dist/entity/custom-entity-fields' {
  interface CustomCustomerFields {
    wishlistItems: WishlistItem[];
  }
}
```

We can then import this types file in our plugin's main file:

```ts title="src/plugins/wishlist-plugin/wishlist.plugin.ts"
// highlight-next-line
import './types';
```

:::note
Custom fields are not solely restricted to Vendure's native entities though, it's also possible to add support for custom fields to your own custom entities. This way other plugins would be able to extend our example `WishlistItem`. See: [Supporting custom fields](/guides/developer-guide/database-entity/#supporting-custom-fields) 
:::

### Step 4: Create a service

A "service" is a class which houses the bulk of the business logic of any plugin. A plugin can define multiple services if needed, but each service should be responsible for a single unit of functionality, such as dealing with a particular entity, or performing a particular task.

Let's create a service to handle the wishlist functionality:

```txt
├── wishlist-plugin
    ├── wishlist.plugin.ts
    ├── services
        // highlight-next-line
        ├── wishlist.service.ts
```

```ts title="src/plugins/wishlist-plugin/services/wishlist.service.ts"
import { Injectable } from '@nestjs/common';
import {
    Customer,
    ForbiddenError,
    ID,
    InternalServerError,
    ProductVariantService,
    RequestContext,
    TransactionalConnection,
    UserInputError,
} from '@vendure/core';

import { WishlistItem } from '../entities/wishlist-item.entity';

@Injectable()
export class WishlistService {
    constructor(
        private connection: TransactionalConnection,
        private productVariantService: ProductVariantService,
    ) {}

    async getWishlistItems(ctx: RequestContext): Promise<WishlistItem[]> {
        try {
            const customer = await this.getCustomerWithWishlistItems(ctx);
            return customer.customFields.wishlistItems;
        } catch (err: any) {
            return [];
        }
    }

    /**
     * Adds a new item to the active Customer's wishlist.
     */
    async addItem(ctx: RequestContext, variantId: ID): Promise<WishlistItem[]> {
        const customer = await this.getCustomerWithWishlistItems(ctx);
        const variant = await this.productVariantService.findOne(ctx, variantId);
        if (!variant) {
            throw new UserInputError(`No ProductVariant with the id ${variantId} could be found`);
        }
        const existingItem = customer.customFields.wishlistItems.find(i => i.productVariantId === variantId);
        if (existingItem) {
            // Item already exists in wishlist, do not
            // add it again
            return customer.customFields.wishlistItems;
        }
        const wishlistItem = await this.connection
            .getRepository(ctx, WishlistItem)
            .save(new WishlistItem({ productVariantId: variantId }));
        customer.customFields.wishlistItems.push(wishlistItem);
        await this.connection.getRepository(ctx, Customer).save(customer, { reload: false });
        return this.getWishlistItems(ctx);
    }

    /**
     * Removes an item from the active Customer's wishlist.
     */
    async removeItem(ctx: RequestContext, itemId: ID): Promise<WishlistItem[]> {
        const customer = await this.getCustomerWithWishlistItems(ctx);
        const itemToRemove = customer.customFields.wishlistItems.find(i => i.id === itemId);
        if (itemToRemove) {
            await this.connection.getRepository(ctx, WishlistItem).remove(itemToRemove);
            customer.customFields.wishlistItems = customer.customFields.wishlistItems.filter(
                i => i.id !== itemId,
            );
        }
        await this.connection.getRepository(ctx, Customer).save(customer);
        return this.getWishlistItems(ctx);
    }

    /**
     * Gets the active Customer from the context and loads the wishlist items.
     */
    private async getCustomerWithWishlistItems(ctx: RequestContext): Promise<Customer> {
        if (!ctx.activeUserId) {
            throw new ForbiddenError();
        }
        const customer = await this.connection.getRepository(ctx, Customer).findOne({
            where: { user: { id: ctx.activeUserId } },
            relations: {
                customFields: {
                    wishlistItems: {
                        productVariant: true,
                    },
                },
            },
        });
        if (!customer) {
            throw new InternalServerError(`Customer was not found`);
        }
        return customer;
    }
}
```

Let's break down what's happening here:

- The `WishlistService` class is decorated with the `@Injectable()` decorator. This is a standard NestJS decorator which tells the NestJS dependency injection (DI) system that this class can be injected into other classes. All your services should be decorated with this decorator.
- The arguments passed to the constructor will be injected by the NestJS DI system. The `connection` argument is a [TransactionalConnection](/reference/typescript-api/data-access/transactional-connection/) instance, which is used to access and manipulate data in the database. The [`ProductVariantService`](/reference/typescript-api/services/product-variant-service/) argument is a built-in Vendure service which contains methods relating to ProductVariants.
- The [`RequestContext`](/reference/typescript-api/request/request-context/) object is usually the first argument to any service method, and contains information and context about the current request as well as any open database transactions. It should always be passed to the methods of the `TransactionalConnection`.

The service is then registered with the plugin metadata as a provider:

```ts title="src/plugins/wishlist-plugin/wishlist.plugin.ts"
import { PluginCommonModule, VendurePlugin } from '@vendure/core';
import { WishlistService } from './services/wishlist.service';

@VendurePlugin({
    imports: [PluginCommonModule],
    // highlight-next-line
    providers: [WishlistService],
    entities: [WishlistItem],
    configuration: config => {
        // ...
    },
})
export class WishlistPlugin {}
```

### Step 5: Extend the GraphQL API

This plugin will need to extend the Shop API, adding new mutations and queries to enable the customer to view and manage their wishlist.

First we will create a new file to hold the GraphQL schema extensions:

```txt
├── wishlist-plugin
    ├── wishlist.plugin.ts
    ├── api
        // highlight-next-line
        ├── api-extensions.ts
```

```ts title="src/plugins/wishlist-plugin/api/api-extensions.ts"
import gql from 'graphql-tag';

export const shopApiExtensions = gql`
    type WishlistItem implements Node {
        id: ID!
        createdAt: DateTime!
        updatedAt: DateTime!
        productVariant: ProductVariant!
        productVariantId: ID!
    }

    extend type Query {
        activeCustomerWishlist: [WishlistItem!]!
    }

    extend type Mutation {
        addToWishlist(productVariantId: ID!): [WishlistItem!]!
        removeFromWishlist(itemId: ID!): [WishlistItem!]!
    }
`;
```

:::note

The `graphql-tag` package is a dependency of the Vendure core package. Depending on the package manager you are using, you may need to install it separately with `yarn add graphql-tag` or `npm install graphql-tag`.

:::

The `api-extensions.ts` file is where we define the extensions we will be making to the Shop API GraphQL schema. We are defining a new `WishlistItem` type; a new query: `activeCustomerWishlist`; and two new mutations: `addToWishlist` and `removeFromWishlist`. This definition is written in [schema definition language](https://graphql.org/learn/schema/) (SDL), a convenient syntax for defining GraphQL schemas.

Next we need to pass these extensions to our plugin's metadata:

```ts title="src/plugins/wishlist-plugin/wishlist.plugin.ts"
import { PluginCommonModule, VendurePlugin } from '@vendure/core';
import { shopApiExtensions } from './api/api-extensions';

@VendurePlugin({
    imports: [PluginCommonModule],
    shopApiExtensions: {
        schema: shopApiExtensions,
        resolvers: [],
    },
})
export class WishlistPlugin {}
```

### Step 6: Create a resolver

Now that we have defined the GraphQL schema extensions, we need to create a resolver to handle the new queries and mutations. A resolver in GraphQL is a function which actually implements the query or mutation defined in the schema. This is done by creating a new file in the `api` directory:

```txt
├── wishlist-plugin
    ├── wishlist.plugin.ts
    ├── api
        ├── api-extensions.ts
        // highlight-next-line
        ├── wishlist.resolver.ts
```

```ts title="src/plugins/wishlist-plugin/api/wishlist.resolver.ts"
import { Args, Mutation, Query, Resolver } from '@nestjs/graphql';
import { Allow, Ctx, Permission, RequestContext, Transaction } from '@vendure/core';

import { WishlistService } from '../services/wishlist.service';

@Resolver()
export class WishlistShopResolver {
    constructor(private wishlistService: WishlistService) {}

    @Query()
    @Allow(Permission.Owner)
    async activeCustomerWishlist(@Ctx() ctx: RequestContext) {
        return this.wishlistService.getWishlistItems(ctx);
    }

    @Mutation()
    @Transaction()
    @Allow(Permission.Owner)
    async addToWishlist(
        @Ctx() ctx: RequestContext,
        @Args() { productVariantId }: { productVariantId: string },
    ) {
        return this.wishlistService.addItem(ctx, productVariantId);
    }

    @Mutation()
    @Transaction()
    @Allow(Permission.Owner)
    async removeFromWishlist(@Ctx() ctx: RequestContext, @Args() { itemId }: { itemId: string }) {
        return this.wishlistService.removeItem(ctx, itemId);
    }
}
```

Resolvers are usually "thin" functions that delegate the actual work to a service. Vendure, like NestJS itself, makes heavy use of decorators at the API layer to define various aspects of the resolver. Let's break down what's happening here:

- The `@Resolver()` decorator tells the NestJS DI system that this class is a resolver. Since a Resolver is part of the NestJS DI system, we can also inject dependencies into its constructor. In this case we are injecting the `WishlistService` which we created in the previous step.
- The `@Mutation()` decorator tells Vendure that this is a mutation resolver. Similarly, `@Query()` decorator defines a query resolver. The name of the method is the name of the query or mutation in the schema.
- The `@Transaction()` decorator tells Vendure that this resolver method should be wrapped in a database transaction. This is important because we are performing multiple database operations in this method, and we want them to be atomic.
- The `@Allow()` decorator tells Vendure that this mutation is only allowed for users with the `Owner` permission. The `Owner` permission is a special permission which indicates that the active user should be the owner of this operation.
- The `@Ctx()` decorator tells Vendure that this method requires access to the `RequestContext` object. Every resolver should have this as the first argument, as it is required throughout the Vendure request lifecycle.

This resolver is then registered with the plugin metadata:

```ts title="src/plugins/wishlist-plugin/wishlist.plugin.ts"
import { PluginCommonModule, VendurePlugin } from '@vendure/core';
import { shopApiExtensions } from './api/api-extensions';
import { WishlistShopResolver } from './api/wishlist.resolver';

@VendurePlugin({
    imports: [PluginCommonModule],
    shopApiExtensions: {
        schema: shopApiExtensions,
        // highlight-next-line
        resolvers: [WishlistShopResolver],
    },
    configuration: config => {
        // ...
    },
})
export class WishlistPlugin {}
```

:::info

More information about resolvers can be found in the [NestJS docs](https://docs.nestjs.com/graphql/resolvers).

:::

### Step 7: Specify compatibility

Since Vendure v2.0.0, it is possible for a plugin to specify which versions of Vendure core it is compatible with. This is especially important if the plugin is intended to be made publicly available via npm or another package registry.

The compatibility is specified via the `compatibility` property in the plugin metadata:

```ts title="src/plugins/wishlist-plugin/wishlist.plugin.ts"
@VendurePlugin({
    // ...
    // highlight-next-line
    compatibility: '^2.0.0',
})
export class WishlistPlugin {}
```

The value of this property is a [semver range](https://docs.npmjs.com/about-semantic-versioning) which specifies the range of compatible versions. In this case, we are saying that this plugin is compatible with any version of Vendure core which is `>= 2.0.0 < 3.0.0`.

### Step 8: Add the plugin to the VendureConfig

The final step is to add the plugin to the `VendureConfig` object. This is done in the `vendure-config.ts` file:

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';
import { WishlistPlugin } from './plugins/wishlist-plugin/wishlist.plugin';

export const config: VendureConfig = {
    // ...
    plugins: [
        // ...
        // highlight-next-line
        WishlistPlugin,
    ],
};
```

### Test the Plugin

Now that the plugin is installed, we can test it out. Since we have defined a custom field, we'll need to generate and run a migration to add the new column to the database.

1. **Generate the Migration File**

   Run the following command to generate a migration file for the `wishlist-plugin`:

   ```bash
   npx vendure migrate wishlist-plugin
   ```

When prompted, select the "Generate a new migration" option. This will create a new migration file in the `src/migrations` folder.

2. **Run the Migration**

After generating the migration file, apply the changes to the database by running the same command again:

   ```bash
   npx vendure migrate wishlist-plugin
   ```

Then start the server:

```bash
npm run dev
```

Once the server is running, we should be able to log in as an existing Customer, and then add a product to the wishlist:

<Tabs>
<TabItem value="Login mutation" label="Login mutation" default>

```graphql
mutation Login {
    login(username: "alec.breitenberg@gmail.com", password: "test") {
        ... on CurrentUser {
            id
            identifier
        }
        ... on ErrorResult {
            errorCode
            message
        }
    }
}
```

</TabItem>
<TabItem value="Response" label="Response">

```json
{
  "data": {
    "login": {
      "id": "9",
      "identifier": "alec.breitenberg@gmail.com"
    }
  }
}
```

  </TabItem>
</Tabs>


<Tabs>
<TabItem value="AddToWishlist mutation" label="AddToWishlist mutation" default>

```graphql
mutation AddToWishlist {
    addToWishlist(productVariantId: "7") {
        id
        productVariant {
            id
            name
        }
    }
}
```

</TabItem>
<TabItem value="Response" label="Response">

```json
{
  "data": {
    "addToWishlist": [
      {
        "id": "4",
        "productVariant": {
          "id": "7",
          "name": "Wireless Optical Mouse"
        }
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

We can then query the wishlist items:


<Tabs>
<TabItem value="GetWishlist query" label="GetWishlist query" default>

```graphql
query GetWishlist {
    activeCustomerWishlist {
        id
        productVariant {
            id
            name
        }
    }
}
```

</TabItem>
<TabItem value="Response" label="Response">

```json
{
  "data": {
    "activeCustomerWishlist": [
      {
        "id": "4",
        "productVariant": {
          "id": "7",
          "name": "Wireless Optical Mouse"
        }
      }
    ]
  }
}
```

  </TabItem>
</Tabs>

And finally, we can test removing an item from the wishlist:

<Tabs>
<TabItem value="RemoveFromWishlist mutation" label="RemoveFromWishlist mutation" default>

```graphql
mutation RemoveFromWishlist {
    removeFromWishlist(itemId: "4") {
        id
        productVariant {
            id
            name
        }
    }
}
```

</TabItem>
<TabItem value="Response" label="Response">

```json
{
  "data": {
    "removeFromWishlist": []
  }
}
```

  </TabItem>
</Tabs>

## Publishing plugins

If you have created a plugin that you would like to share with the community, you can publish it to npm, and even
have it listed on the [Vendure Hub](https://vendure.io/hub).

For a full guide to publishing plugins, see the [Publishing a Plugin how-to guide](/guides/how-to/publish-plugin/).


---

---
title: "Add a REST endpoint"
showtoc: true
---

REST-style endpoints can be defined as part of a [plugin](/guides/developer-guide/plugins/).

:::info
REST endpoints are implemented as NestJS Controllers. For comprehensive documentation, see the [NestJS controllers documentation](https://docs.nestjs.com/controllers).
:::

In this guide we will define a plugin that adds a single REST endpoint at `http://localhost:3000/products` which returns a list of all products.

## Create a controller

First let's define the controller:

```ts title="src/plugins/rest-plugin/api/products.controller.ts"
// products.controller.ts
import { Controller, Get } from '@nestjs/common';
import { Ctx, ProductService, RequestContext } from '@vendure/core';

@Controller('products')
export class ProductsController {
    constructor(private productService: ProductService) {
    }

    @Get()
    findAll(@Ctx() ctx: RequestContext) {
        return this.productService.findAll(ctx);
    }
}
```

The key points to note here are:

- The `@Controller()` decorator defines the base path for all endpoints defined in this controller. In this case, all endpoints will be prefixed with `/products`.
- The `@Get()` decorator defines a GET endpoint at the base path. The method name `findAll` is arbitrary.
- The `@Ctx()` decorator injects the [RequestContext](/reference/typescript-api/request/request-context/) which is required for all service methods.

## Register the controller with the plugin

```ts title="src/plugins/rest-plugin/rest.plugin.ts"
import { PluginCommonModule, VendurePlugin } from '@vendure/core';
import { ProductsController } from './api/products.controller';

@VendurePlugin({
  imports: [PluginCommonModule],
  controllers: [ProductsController],
})
export class RestPlugin {}
```

:::info
**Note:** [The `PluginCommonModule`](/reference/typescript-api/plugin/plugin-common-module/) should be imported to gain access to Vendure core providers - in this case it is required in order to be able to inject `ProductService` into our controller.
:::

The plugin can then be added to the `VendureConfig`:

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';
import { RestPlugin } from './plugins/rest-plugin/rest.plugin';

export const config: VendureConfig = {
    // ...
    plugins: [
        // ...
        // highlight-next-line
        RestPlugin,
    ],
};
```

## Controlling access to REST endpoints

You can use the [`@Allow()` decorator](/reference/typescript-api/request/allow-decorator/) to declare the permissions required to access a REST endpoint:

```ts title="src/plugins/rest-plugin/api/products.controller.ts"
import { Controller, Get } from '@nestjs/common';
import { Allow, Permission, Ctx, ProductService, RequestContext } from '@vendure/core';

@Controller('products')
export class ProductsController {
    constructor(private productService: ProductService) {}

    // highlight-next-line
    @Allow(Permission.ReadProduct)
    @Get()
    findAll(@Ctx() ctx: RequestContext) {
        return this.productService.findAll(ctx);
    }
}
```

:::tip
The following Vendure [API decorators](/guides/developer-guide/the-api-layer/#api-decorators) can also be used with NestJS controllers: `@Allow()`, `@Transaction()`, `@Ctx()`.

Additionally, NestJS supports a number of other REST decorators detailed in the [NestJS controllers guide](https://docs.nestjs.com/controllers#request-object)
:::


---

---
title: 'Scheduled Tasks'
showtoc: true
---

Scheduled tasks are a way of executing some code at pre-defined intervals. There are many examples of work that can be done using scheduled tasks,
such as:

- Generating a sitemap
- Synchronizing data between different systems
- Sending abandoned cart emails
- Cleaning up old data

Since Vendure v3.3, there is a built-in mechanism which allows you to define scheduled tasks in a convenient and powerful way.

:::info
All the information on page applies to Vendure v3.3+

For older versions, there is no built-in support for scheduled tasks, but you can
instead use a [stand-alone script](/guides/developer-guide/stand-alone-scripts/) triggered by a cron job.
:::

## Setting up the DefaultSchedulerPlugin

In your Vendure config, import and add the [DefaultSchedulerPlugin](/reference/typescript-api/scheduled-tasks/default-scheduler-plugin) to your
plugins array. If you created your project with a version newer than v3.3, this should already be configured.

```ts title="vendure-config.ts"
import { DefaultSchedulerPlugin, VendureConfig } from '@vendure/core';

export const config: VendureConfig = {
    // ...
    plugins: [DefaultSchedulerPlugin.init()],
};
```

When you first add this plugin to your config, you'll need to [generate a migration](/guides/developer-guide/migrations/) because the
plugin will make use of a new database table in order to guarantee only-once execution of tasks.

You can then start adding tasks. Vendure ships with a task that will clean up old sessions from the database.

:::note
The `cleanSessionsTask` task is actually configured by default from v3.3+, so normally you won't have to specify this
manually unless you wish to change any of the default configuration using the `.configure()` method.
:::

```ts title="vendure-config.ts"
import { cleanSessionsTask, DefaultSchedulerPlugin, VendureConfig } from '@vendure/core';

export const config: VendureConfig = {
    // ...
    schedulerOptions: {
        tasks: [
            // Use the task as is
            cleanSessionsTask,
            // or further configure the task
            cleanSessionsTask.configure({
                // Run the task every day at 3:00am
                // The default schedule is every day at 00:00am
                schedule: cron => cron.everyDayAt(3, 0),
                params: {
                    // How many sessions to process in each batch
                    // Default: 10_000
                    batchSize: 5_000,
                },
            }),
        ],
    },
    plugins: [DefaultSchedulerPlugin.init()],
};
```

## Creating a Scheduled Task

Let's imagine that you have created a `SitemapPlugin` that exposes a `SitemapService` which generates a sitemap for your store. You want to run this
task every night at midnight.

Inside the plugin, you would first define a new [ScheduledTask](/reference/typescript-api/scheduled-tasks/scheduled-task) instance:

```ts title="/plugins/sitemap/config/generate-sitemap-task.ts"
import { ScheduledTask, RequestContextService } from '@vendure/core';

import { SitemapService } from '../services/sitemap.service';

export const generateSitemapTask = new ScheduledTask({
    // Give your task a unique ID
    id: 'generate-sitemap',
    // A human-readable description of the task
    description: 'Generates a sitemap file',
    // Params can be used to further configure aspects of the
    // task. They get passed in to the `execute` function as the
    // second argument.
    // They can be later modified using the `.configure()` method on the instance
    params: {
        shopBaseUrl: 'https://www.myshop.com',
    },
    // Define a default schedule. This can be modified using the
    // `.configure()` method on the instance later.
    schedule: cron => cron.everyDayAt(0, 0),
    // This is the function that will be executed per the schedule.
    async execute({injector, params}) {
        // Using `injector.get()` we can grab an instance of _any_ provider defined in the
        // Vendure core as well as by our plugins.
        const sitemapService = injector.get(SitemapService);

        // For most service methods, we'll need to pass a RequestContext object.
        // We can use the RequestContextService to create one.
        const ctx = await injector.get(RequestContextService).create({
            apiType: 'admin',
        });

        // Here's the actual work we want to perform.
        const result = await sitemapService.generateSitemap(ctx);

        // The return value from the `execute` function will be available
        // as the `lastResult` property when viewing tasks.
        return { result };
    },
});
```

## Using a task

Now that the task has been defined, we need to tell Vendure to use it.

To do so we need to add it to the [schedulerOptions.tasks](/reference/typescript-api/scheduled-tasks/scheduler-options#tasks) array.

### Adding directly in Vendure config

This can be done directly in your Vendure config file:

```ts title="vendure-config.ts"
import { cleanSessionsTask, DefaultSchedulerPlugin, VendureConfig } from '@vendure/core';

// highlight-next-line
import { SitemapPlugin, generateSitemapTask } from './plugins/sitemap';

export const config: VendureConfig = {
    // ...
    schedulerOptions: {
        tasks: [
            cleanSessionsTask,
            // highlight-start
            // Here's an example of overriding the
            // default params using the `configure()` method.
            generateSitemapTask.configure({
                params: {
                    shopBaseUrl: 'https://www.shoes.com'
                }
            }),
            // highlight-end
        ],
    },
    plugins: [
        // highlight-next-line
        SitemapPlugin,
        DefaultSchedulerPlugin.init()
    ],
};
```

### Adding in plugin configuration function

An alternative is that a plugin can automatically add the task to the config using the
plugin's [configuration function](/reference/typescript-api/plugin/vendure-plugin-metadata#configuration), which allows plugins to alter the Vendure config.

This allows a plugin to encapsulate any scheduled tasks so that the plugin consumer only needs to add the plugin, and not worry about
separately adding the task to the tasks array.

```ts title="src/plugins/sitemap/sitemap.plugin.ts"
import { VendurePlugin, PluginCommonModule, Type, ScheduledTask, VendureConfig } from '@vendure/core';

import { PLUGIN_OPTIONS } from './constants';
import { SitemapPluginOptions } from './types';
import { SitemapService } from './services/sitemap.service';
import { generateSitemapTask } from './config/generate-sitemap-task';

@VendurePlugin({
    imports: [PluginCommonModule],
    providers: [SitemapService],
    configuration: (config: VendureConfig) => {
        // highlight-start
        // Add the task to the schedulerOptions.tasks array
        config.schedulerOptions.tasks.push(
            generateSitemapTask.configure({
                params: {
                    shopBaseUrl: SitemapPlugin.options.shopBaseUrl,
                }
            })
        );
        // highlight-end
        return config;
    },
})
export class SitemapPlugin {
    static options: SitemapPluginOptions;

    static init(options?: SitemapPluginOptions) {
        this.options = {
            shopBaseUrl: '',
            ...(options ?? {}),
        }
    }
}
```

This plugin can now be consumed like this:

```ts title="vendure-config.ts"
import { DefaultSchedulerPlugin, VendureConfig } from '@vendure/core';

// highlight-next-line
import { SitemapPlugin } from './plugins/sitemap';

export const config: VendureConfig = {
    // ...
    plugins: [
        // highlight-start
        SitemapPlugin.init({
            shopBaseUrl: 'https://www.shoes.com'
        }),
        // highlight-end
        DefaultSchedulerPlugin.init()
    ],
};
```

## How scheduled tasks work

The key problems solved by Vendure's task scheduler are:

- Ensuring that a task is only run a single time per scheduled execution, even when you have multiple instances of servers and workers running.
- Keeping scheduled task work away from the server instances, so that it does not affect API responsiveness.

The first problem is handled by the [SchedulerStrategy](/reference/typescript-api/scheduled-tasks/scheduler-strategy), which implements a locking
mechanism to ensure that the task is executed only once.

The second problem is handled by having tasks only executed on worker processes.

## Scheduled tasks vs job queue

There is some overlap between the use of a scheduled task and a [job queue job](/guides/developer-guide/worker-job-queue/). They both perform some
task on the worker, independent of requests coming in to the server.

The first difference is that jobs must be triggered explicitly, whereas scheduled tasks are triggered automatically according to the schedule.

Secondly, jobs are put in a _queue_ and executed once any prior pending jobs have been processed. On the other hand, scheduled tasks are executed
as soon as the schedule dictates.

It is possible to combine the two: namely, you can define a scheduled task which adds a job to the job queue. This is, for instance, how the
built-in [cleanSessionsTask](/reference/typescript-api/scheduled-tasks/clean-sessions-task) works. This pattern is something you should
consider if the scheduled task may take a significant amount of time or resources and you want to let the job queue manage that.

It also has the advantage of giving you a record of results for that work that has been put on the job queue, whereas scheduled tasks
only record that result of the last execution.


## A note on @nestjs/schedule

NestJS provides a [dedicated package for scheduling tasks](https://docs.nestjs.com/techniques/task-scheduling), called `@nestjs/schedule`.

You can also use this approach to schedule tasks, but you need to aware of a very important caveat:

:::warning
When using `@nestjs/schedule`, any method decorated with the `@Cron()` decorator will run
on _all_ instances of the application. This means it will run on the server _and_ on the
worker. If you are running multiple instances, then it will run on all instances.

This is the specific issue solved by the built-in ScheduledTask system described above.
Therefore it is not recommended to use the `@nestjs/schedule` package under normal
circumstances.
:::

You can, for instance, inject the [ProcessContext](/reference/typescript-api/common/process-context) into the service and check if the current instance is the worker or the server.

```ts
import { Injectable } from '@nestjs/common';
import { Cron } from '@nestjs/schedule';

@Injectable()
export class SitemapService {
    constructor(private processContext: ProcessContext) {}

    @Cron('0 0 * * *')
    async generateSitemap() {
        // highlight-start
        if (this.processContext.isWorker) {
            // Only run on the worker
            await this.triggerGenerate();
        }
        // highlight-end
    }
}
```

The above code will run the `generateSitemap()` method every night at midnight, but only on the worker instance.

Again, if you have multiple worker instances running, it would run on all instances.


---

---
title: "Security"
---

Security of your Vendure application includes considering how to prevent and protect against common security threats such as:

- Data breaches
- Unauthorized access
- Attacks aimed at disrupting the service

Vendure itself is designed with security in mind, but you must also consider the security of your own application code, the server environment, and the network architecture.

## Basics

Here are some basic measures you should use to secure your Vendure application. These are not exhaustive, but they are a good starting point.

### Change the default credentials

Do not deploy any public Vendure instance with the default superadmin credentials (`superadmin:superadmin`). Use your hosting platform's environment variables to set a **strong** password for the Superadmin account.

```ts
import { VendureConfig } from '@vendure/core';

export const config: VendureConfig = {
  authOptions: {
    tokenMethod: ['bearer', 'cookie'],
    superadminCredentials: {
      identifier: process.env.SUPERADMIN_USERNAME,
      password: process.env.SUPERADMIN_PASSWORD,
    },
  },
  // ...
};
```

### Use the HardenPlugin

It is recommended that you install and configure the [HardenPlugin](/reference/core-plugins/harden-plugin/) for all production deployments. This plugin locks down your schema 
(disabling introspection and field suggestions) and protects your Shop API against malicious queries that could otherwise overwhelm your server.

Install the plugin:

```sh
npm install @vendure/harden-plugin

# or

yarn add @vendure/harden-plugin
```

Then add it to your VendureConfig:

```ts
import { VendureConfig } from '@vendure/core';
import { HardenPlugin } from '@vendure/harden-plugin';

const IS_DEV = process.env.APP_ENV === 'dev';

export const config: VendureConfig = {
  // ...
  plugins: [
    HardenPlugin.init({
      maxQueryComplexity: 500,
      apiMode: IS_DEV ? 'dev' : 'prod',
    }),
    // ...
  ]
};
```

:::info
For a detailed explanation of how to best configure this plugin, see the [HardenPlugin docs](/reference/core-plugins/harden-plugin/).
:::

### Harden the AssetServerPlugin

If you are using the [AssetServerPlugin](/reference/core-plugins/asset-server-plugin/), it is possible by default to use the dynamic
image transform feature to overload the server with requests for new image sizes & formats. To prevent this, you can
configure the plugin to only allow transformations for the preset sizes, and limited quality levels and formats.
Since v3.1 we ship the [PresetOnlyStrategy](/reference/core-plugins/asset-server-plugin/preset-only-strategy/) for this purpose, and
you can also create your own strategies.

```ts
import { VendureConfig } from '@vendure/core';
import { AssetServerPlugin, PresetOnlyStrategy } from '@vendure/asset-server-plugin';

export const config: VendureConfig = {
  // ...
  plugins: [
    AssetServerPlugin.init({
      // ...
      // highlight-start  
      imageTransformStrategy: new PresetOnlyStrategy({
        defaultPreset: 'large',
        permittedQuality: [0, 50, 75, 85, 95],
        permittedFormats: ['jpg', 'webp', 'avif'],
        allowFocalPoint: false,
      }),
      // highlight-end
    }),
  ]
};
```

## OWASP Top Ten Security Assessment

The Open Worldwide Application Security Project (OWASP) is a nonprofit foundation that works to improve the security of software.

It publishes a top 10 list of common web application vulnerabilities: https://owasp.org/Top10

This section assesses Vendure against this list, stating what is covered **out of the box** (built in to the framework or easily configurable) and what needs to be **additionally considered.**

### 1. Broken Access Control

Reference: https://owasp.org/Top10/A01_2021-Broken_Access_Control/

Out of the box:

- Vendure uses role-based access control
- We deny by default for non-public API requests
- Built-in CORS controls for session cookies
- Directory listing is not possible via default configuration (e.g. exposing web root dir contents)
- Stateful session identifiers should be invalidated on the server after logout. On logout we delete all session records from the DB & session cache.

To consider:

- Rate limit API and controller access to minimize the harm from automated attack tooling.

### 2. Cryptographic Failures

Reference: https://owasp.org/Top10/A02_2021-Cryptographic_Failures/

Out of the box:

- Vendure defaults to bcrypt with 12 salt rounds for storing passwords. This strategy is configurable if security requirements mandate alternative algorithms.
- No deprecated hash functions (SHA1, MD5) are used in security-related contexts (only for things like creating cache keys).
- Payment information is not stored in Vendure by default. Payment integrations rely on the payment provider to store all sensitive data.

To consider:

- The Vendure server will not use TLS be default. The usual configuration is to handle this at the gateway level on your production platform.
- If a network caching layer is used (e.g. Stellate), ensure it is configured to not cache user-related data (customer details, active order etc)

### 3. Injection

Reference: https://owasp.org/Top10/A03_2021-Injection/

Out of the box:

- GraphQL has built-in validation of incoming data
- All database operations are parameterized - no string concatenation using user-supplied data.
- List queries apply default limits to prevent mass disclosure of records.

To consider:

- If using custom fields, you should consider defining a validation function to prevent bad data from getting into the database.

### 4. Insecure Design

Reference: https://owasp.org/Top10/A04_2021-Insecure_Design/

Out of the box:

- Use of established libraries for the critical underlying components: NestJS, TypeORM, Angular.
- End-to-end tests of security-related flows such as authentication, verification, and RBAC permissions controls.
- Harden plugin provides pre-configured protections against common attack vectors targeting GraphQL APIs.

To consider:

- Tiered exposure such as an API gateway which prevents exposure of the Admin API to the public internet.
- Limit resource usage of Vendure server & worker instances via containerization.
- Rate limiting & other network-level protections (such as Cloudflare) should be considered.

### 5. Security Misconfiguration

Reference: https://owasp.org/Top10/A05_2021-Security_Misconfiguration/

Out of the box:

- Single point of configuration for the entire application, reducing the chance of misconfiguration.
- A default setup only requires a database, which means there are few components to configure and harden.
- Stack traces are not leaked in API errors

To consider:

- Ensure the default superadmin credentials are not used in production
- Use environment variables to turn off development features such as the GraphQL playground
- Use the HardenPlugin in production to automatically turn of development features and restrict system information leaking via API.
- Use fine-grained permissions and roles for your administrator accounts to reduce the attack surface if an account is compromised.

### 6. Vulnerable and Outdated Components

Reference: https://owasp.org/Top10/A06_2021-Vulnerable_and_Outdated_Components/

Out of the box:

- All dependencies are updated to current versions with each minor release
- Modular design limits the number of dependencies for core packages.
- Automated code & dependency scanning is used in the Vendure repo

To consider:

- Run your own audits on your code base.
- Use version override mechanisms if needed to patch and critical Vendure dependencies that did not yet get updated.

### 7. Identification and Authentication Failures

Reference: https://owasp.org/Top10/A07_2021-Identification_and_Authentication_Failures/

Out of the box:

- Valid usernames are not leaked via mechanisms such as account reset
- Does not permit "knowlege-based" account recovery
- Uses strong password hashing (bcrypt with 12 salt rounds)
- Session identifiers are not exposed in API urls (instead we use headers/cookies)
- New session tokens always regenerated after successful login
- Sessions deleted during logout
- Cryptographically-strong, high-entropy session tokens are used (crypto.randomBytes API)

To consider:

- Implementing a multi-factor authentication flow
- Do not use default superadmin credentials in production
- Implementing a custom PasswordValidationStrategy to disallow weak/common passwords
- Subscribe to AttemptedLoginEvent to implement detection of brute-force attacks

### 8. Software and Data Integrity Failures

Reference: https://owasp.org/Top10/A08_2021-Software_and_Data_Integrity_Failures/

To consider:

- Exercise caution when introducing new dependencies to your project.
- Do not use untrusted Vendure plugins. Where possible review the code prior to use.
- Exercise caution if using auto-updating mechanisms for dependencies.
- If storing serialized data in custom fields, implement validation to prevent untrusted data getting into the database.
- Evaluate your CI/CD pipeline against the OWASP recommendations for this point

### 9. Security Logging and Monitoring Failures

Reference: https://owasp.org/Top10/A09_2021-Security_Logging_and_Monitoring_Failures/

Out of the box:

- APIs for integrating logging & monitoring tools & services, e.g. configurable Logger interface & ErrorHandlerStrategy
- Official Sentry integration for application performance monitoring

To consider:

- Integrate with dedicated logging tools for improved log management
- Integrate with monitoring tools such as Sentry
- Use the EventBus to monitor events such as repeated failed login attempts and high-value orders

### 10. Server-Side Request Forgery (SSRF)

Reference: [https://owasp.org/Top10/A10_2021-Server-Side_Request_Forgery_(SSRF)/](https://owasp.org/Top10/A10_2021-Server-Side_Request_Forgery_%28SSRF%29/)

Out of the box:

- By default Vendure does not rely on requests to remote servers for core functionality

To consider:

- Review the OWASP recommendations against your network architecture


---

---
title: 'Settings Store'
showtoc: true
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Settings Store

The Settings Store is a flexible system for storing configuration data with support for scoping, permissions,
and validation. It allows plugins and the core system to store and retrieve arbitrary JSON data with
fine-grained control over access and isolation.

It provides a robust, secure, and flexible system for managing configuration data in your Vendure 
application. Use it to store user preferences, plugin settings, feature flags, and any other 
settings data your application needs.


:::info
The APIs in this guide were introduced in Vendure v3.4
:::

## Overview

The Settings Store provides:

- **Scoped Storage**: Data can be scoped globally, per-user, per-channel, or with custom scope
- **Permission Control**: Fields can require specific permissions to access
- **Validation**: Custom validation functions for field values
- **GraphQL API**: Admin API for reading and writing values
- **Service API**: Programmatic access via the [SettingsStoreService](/reference/typescript-api/services/settings-store-service)
- **Automatic Cleanup**: Scheduled task to remove orphaned entries

## Settings Store vs Custom Fields

Settings fields share some similarities to custom fields, but the important differences are:

- Custom fields are attached to particular Vendure entities. Settings fields are not.
- Defining a custom field adds a new column in the database, whereas settings fields do not.
- Custom fields are reflected in corresponding GraphQL APIs and in the Admin UI & Dashboard UIs.
- Custom fields are statically typed, whereas settings fields store any kind of JSON-serializable data.

Settings fields are best suited to storing config-like values that are global in scope, or which
configure data for a particular plugin.

## Defining Settings Fields

Settings fields are defined in your Vendure configuration using the `settingsStoreFields` option:

<Tabs>
    <TabItem value="basic" label="Basic Example">

        ```ts
        import { VendureConfig, SettingsStoreScopes } from '@vendure/core';

        export const config: VendureConfig = {
          // ... other config
          settingsStoreFields: {
            dashboard: [
                {
                  name: 'theme',
                  scope: SettingsStoreScopes.user,
                },
                {
                  name: 'companyName',
                  scope: SettingsStoreScopes.global,
                }
              ]
            }
          };
        ```

    </TabItem>
    <TabItem value="advanced" label="Advanced Example">

        ```ts
        import { VendureConfig, SettingsStoreScopes, Permission } from '@vendure/core';

        export const config: VendureConfig = {
          // ... other config
          settingsStoreFields: {
            dashboard: [
              {
                name: 'theme',
                scope: SettingsStoreScopes.user,
              },
              {
                name: 'tableFilters',
                scope: SettingsStoreScopes.userAndChannel,
              }
            ],
            payment: [
              {
                name: 'stripeApiKey',
                scope: SettingsStoreScopes.global,
                readonly: true, // Cannot be modified via GraphQL API
                requiresPermission: Permission.SuperAdmin,
                validate: (value, injector, ctx) => {
                  if (typeof value !== 'string' || !value.startsWith('sk_')) {
                    return 'Stripe API key must be a string starting with "sk_"';
                  }
                }
              }
            ],
            ui: [
              {
                name: 'welcomeMessage',
                scope: SettingsStoreScopes.channel,
                validate: async (value, injector, ctx) => {
                  if (typeof value !== 'string' || value.length > 500) {
                    return 'Welcome message must be a string with max 500 characters';
                  }
                }
              }
            ]
          }
        };
        ```

    </TabItem>

</Tabs>

### Field Configuration Options

Each field supports the following configuration options:

| Option               | Type                         | Description                                                 |
| -------------------- | ---------------------------- | ----------------------------------------------------------- |
| `name`               | `string`                     | The field name (combined with namespace to create full key) |
| `scope`              | `SettingsStoreScopeFunction`      | How the field should be scoped (see scoping section)        |
| `readonly`           | `boolean`                    | If true, field cannot be modified via GraphQL API           |
| `requiresPermission` | `Permission \| Permission[]` | Permissions required to access this field                   |
| `validate`           | `function`                   | Custom validation function for field values                 |

### Scoping

The Settings Store supports four built-in scoping strategies:

```ts
import { SettingsStoreScopes } from '@vendure/core';

// Global - single value for entire system
SettingsStoreScopes.global;

// User-specific - separate values per user
SettingsStoreScopes.user;

// Channel-specific - separate values per channel
SettingsStoreScopes.channel;

// User and channel specific - separate values per user per channel
SettingsStoreScopes.userAndChannel;
```

You can also create custom scope functions:

```ts
const customScope: SettingsStoreScopeFunction = ({ key, value, ctx }) => {
    // Custom scoping logic
    const env = process.env.NODE_ENV === 'production' ? 'prod' : 'dev';
    return `env:${env}`;
};

export const config: VendureConfig = {
    settingsStoreFields: {
        myNamespace: [
            {
                name: 'customField',
                // The value will be saved with the scope
                // "env:prod" or "env:dev"
                scope: customScope,
            },
        ],
    },
};
```

## GraphQL API

The Settings Store provides GraphQL queries and mutations in the Admin API:

### Queries

```graphql
# Get a single value
query GetSettingsStoreValue($key: String!) {
    getSettingsStoreValue(key: $key)
}

# Get multiple values
query GetSettingsStoreValues($keys: [String!]!) {
    getSettingsStoreValues(keys: $keys)
}
```

### Mutations

Any kind of JSON-serializable data can be set as the value. For example: strings, numbers,
arrays, or even deeply-nested objects and arrays.

```graphql
# Set a single value
mutation SetSettingsStoreValue($input: SettingsStoreInput!) {
    setSettingsStoreValue(input: $input) {
        key
        result
        error
    }
}

# Set multiple values
mutation SetSettingsStoreValues($inputs: [SettingsStoreInput!]!) {
    setSettingsStoreValues(inputs: $inputs) {
        key
        result
        error
    }
}
```

:::note
By default, the Settings Store is not exposed in the Shop API. 
However, you can expose this functionality via a custom mutations & queries
that internally use the `SettingsStoreService` (see next section).
:::

### Usage Examples

<Tabs>
    <TabItem value="single" label="Single Value">

        ```ts
        // Setting a value
        const result = await adminClient.query(gql`
            mutation SetSettingsStoreValue($input: SettingsStoreInput!) {
                setSettingsStoreValue(input: $input) {
                    key
                    result
                    error
                }
            }
        `, {
            input: {
                key: 'dashboard.theme',
                value: 'dark'
            }
        });

        // Getting a value
        const theme = await adminClient.query(gql`
            query GetSettingsStoreValue($key: String!) {
                getSettingsStoreValue(key: $key)
            }
        `, {
            key: 'dashboard.theme'
        });
        ```

    </TabItem>
    <TabItem value="multiple" label="Multiple Values">

        ```ts
        // Setting multiple values
        const results = await adminClient.query(gql`
            mutation SetSettingsStoreValues($inputs: [SettingsStoreInput!]!) {
                setSettingsStoreValues(inputs: $inputs) {
                    key
                    result
                    error
                }
            }
        `, {
            inputs: [
                { key: 'dashboard.theme', value: 'dark' },
                { key: 'dashboard.language', value: 'en' }
            ]
        });

        // Getting multiple values
        const settings = await adminClient.query(gql`
            query GetSettingsStoreValues($keys: [String!]!) {
                getSettingsStoreValues(keys: $keys)
            }
        `, {
            keys: ['dashboard.theme', 'dashboard.language']
        });

        // Returns: {"dashboard.theme": "dark", "dashboard.language": "en"}
        ```

    </TabItem>

</Tabs>

## Using the SettingsStoreService

For programmatic access within plugins or services, use the [SettingsStoreService](/reference/typescript-api/services/settings-store-service):

<Tabs>
    <TabItem value="basic-service" label="Basic Usage">

        ```ts
        import { Injectable } from '@nestjs/common';
        import { SettingsStoreService, RequestContext } from '@vendure/core';

        @Injectable()
        export class MyService {
            constructor(private settingsStoreService: SettingsStoreService) {}

            async getUserTheme(ctx: RequestContext): Promise<string> {
                const theme = await this.settingsStoreService.get<string>('dashboard.theme', ctx);
                return theme || 'light'; // Default fallback
            }

            async setUserTheme(ctx: RequestContext, theme: string): Promise<boolean> {
                const result = await this.settingsStoreService.set('dashboard.theme', theme, ctx);
                return result.result;
            }
        }
        ```

    </TabItem>
    <TabItem value="advanced-service" label="Advanced Usage">

        ```ts
        import { Injectable } from '@nestjs/common';
        import { SettingsStoreService, RequestContext } from '@vendure/core';

        interface DashboardSettings {
            theme: 'light' | 'dark';
            language: string;
            notifications: boolean;
        }

        @Injectable()
        export class DashboardService {
            constructor(private settingsStoreService: SettingsStoreService) {}

            async getDashboardSettings(ctx: RequestContext): Promise<DashboardSettings> {
                const settings = await this.settingsStoreService.getMany([
                    'dashboard.theme',
                    'dashboard.language',
                    'dashboard.notifications'
                ], ctx);

                return {
                    theme: settings['dashboard.theme'] || 'light',
                    language: settings['dashboard.language'] || 'en',
                    notifications: settings['dashboard.notifications'] ?? true,
                };
            }

            async updateDashboardSettings(
                ctx: RequestContext,
                settings: Partial<DashboardSettings>
            ): Promise<{ success: boolean; errors: string[] }> {
                const updates: Record<string, any> = {};

                if (settings.theme) updates['dashboard.theme'] = settings.theme;
                if (settings.language) updates['dashboard.language'] = settings.language;
                if (settings.notifications !== undefined) {
                    updates['dashboard.notifications'] = settings.notifications;
                }

                const results = await this.settingsStoreService.setMany(updates, ctx);

                return {
                    success: results.every(r => r.result),
                    errors: results.filter(r => !r.result).map(r => r.error || 'Unknown error')
                };
            }
        }
        ```

    </TabItem>

</Tabs>

### SettingsStoreService Methods

| Method                    | Description                                         |
| ------------------------- | --------------------------------------------------- |
| `get<T>(key, ctx)`        | Get a single value with optional type parameter     |
| `getMany(keys, ctx)`      | Get multiple values efficiently in a single query   |
| `set<T>(key, value, ctx)` | Set a value with structured result feedback         |
| `setMany(values, ctx)`    | Set multiple values with individual result feedback |
| `getFieldDefinition(key)` | Get the field configuration for a key               |

## Orphaned Entries Cleanup

When field definitions are removed from your configuration, the corresponding 
database entries become "orphaned". The Settings Store includes an automatic cleanup system to handle this.

### Manual Cleanup

You can also perform cleanup manually via the service:

```ts
// Find orphaned entries
const orphanedEntries = await settingsStoreService.findOrphanedEntries({
    olderThan: '7d',
    maxDeleteCount: 1000,
});

// Clean them up
const cleanupResult = await settingsStoreService.cleanupOrphanedEntries({
    olderThan: '7d',
    dryRun: false,
    batchSize: 100,
});
```

## Best Practices

1. **Use appropriate scoping**: Choose the most restrictive scope that meets your needs
2. **Implement validation**: Add validation for fields that accept user input
3. **Set permissions**: Use`requiresPermission` for sensitive configuration data
4. **Mark sensitive fields readonly**: Prevent GraphQL modification of critical settings
5. **Consider value size limits**: Large values can impact performance

## Examples

### Plugin Integration

```ts
import { VendurePlugin, SettingsStoreScopes } from '@vendure/core';

@VendurePlugin({
    configuration: config => {
        config.settingsStoreFields = {
            ...config.settingsStoreFields,
            myPlugin: [
                {
                    name: 'apiEndpoint',
                    scope: SettingsStoreScopes.global,
                    requiresPermission: Permission.UpdateSettings,
                    validate: value => {
                        if (typeof value !== 'string' || !value.startsWith('https://')) {
                            return 'API endpoint must be a valid HTTPS URL';
                        }
                    },
                },
                {
                    name: 'userPreferences',
                    scope: SettingsStoreScopes.userAndChannel,
                },
            ],
        };
        return config;
    },
})
export class MyPlugin {}
```

### Frontend usage

```tsx
import React from 'react';
import { useQuery, useMutation } from '@apollo/client';
import gql from 'graphql-tag';

const GET_THEME = gql`
    query GetTheme {
        getSettingsStoreValue(key: "dashboard.theme")
    }
`;

const SET_THEME = gql`
    mutation SetTheme($theme: String!) {
        setSettingsStoreValue(input: { key: "dashboard.theme", value: $theme }) {
            result
            error
        }
    }
`;

export function ThemeSelector() {
    const { data } = useQuery(GET_THEME);
    const [setTheme] = useMutation(SET_THEME, {
        refetchQueries: [GET_THEME],
    });

    const currentTheme = data?.getSettingsStoreValue || 'light';

    const handleThemeChange = (theme: string) => {
        setTheme({ variables: { theme } });
    };

    return (
        <select value={currentTheme} onChange={e => handleThemeChange(e.target.value)}>
            <option value="light">Light</option>
            <option value="dark">Dark</option>
        </select>
    );
}
```


---

---
title: "Stand-alone CLI Scripts"
---

# Stand-alone CLI Scripts

It is possible to create stand-alone scripts that can be run from the command-line by using the [bootstrapWorker function](/reference/typescript-api/worker/bootstrap-worker/). This can be useful for a variety of use-cases such as running cron jobs or importing data.

## Minimal example

Here's a minimal example of a script which will bootstrap the Vendure Worker and then log the number of products in the database:

```ts title="src/get-product-count.ts"
import { bootstrapWorker, Logger, ProductService, RequestContextService } from '@vendure/core';

import { config } from './vendure-config';

if (require.main === module) {
    getProductCount()
        .then(() => process.exit(0))
        .catch(err => {
            Logger.error(err);
            process.exit(1);
        });
}

async function getProductCount() {
    // This will bootstrap an instance of the Vendure Worker, providing
    // us access to all of the services defined in the Vendure core.
    // (but without the unnecessary overhead of the API layer).
    const { app } = await bootstrapWorker(config);

    // Using `app.get()` we can grab an instance of _any_ provider defined in the
    // Vendure core as well as by our plugins.
    const productService = app.get(ProductService);

    // For most service methods, we'll need to pass a RequestContext object.
    // We can use the RequestContextService to create one.
    const ctx = await app.get(RequestContextService).create({
        apiType: 'admin',
    });

    // We use the `findAll()` method to get the total count. Since we aren't
    // interested in the actual product objects, we can set the `take` option to 0.
    const { totalItems } = await productService.findAll(ctx, {take: 0});

    Logger.info(
        [
            '\n-----------------------------',
            `There are ${totalItems} products`,
            '------------------------------',
        ].join('\n'),
    )
}
``` 

This script can then be run from the command-line:

```shell
npx ts-node src/get-product-count.ts

# or

yarn ts-node src/get-product-count.ts
```

resulting in the following output:

```shell
info 01/08/23, 11:50 - [Vendure Worker] Bootstrapping Vendure Worker (pid: 4428)...
info 01/08/23, 11:50 - [Vendure Worker] Vendure Worker is ready
info 01/08/23, 11:50 - [Vendure Worker]
-----------------------------------------
There are 56 products in the database
-----------------------------------------
```

## The `app` object

The `app` object returned by the `bootstrapWorker()` function is an instance of the [NestJS Application Context](https://docs.nestjs.com/standalone-applications). It has full access to the NestJS dependency injection container, which means that you can use the `app.get()` method to retrieve any of the services defined in the Vendure core or by any plugins.

```ts title="src/import-customer-data.ts"
import { bootstrapWorker, CustomerService } from '@vendure/core';
import { config } from './vendure-config';

// ...

async function importCustomerData() {
    const { app } = await bootstrapWorker(config);
    
    // highlight-start
    const customerService = app.get(CustomerService);
    // highlight-end
}
```

## Creating a RequestContext

Almost all the methods exposed by Vendure's core services take a `RequestContext` object as the first argument. Usually, this object is created in the [API Layer](/guides/developer-guide/the-api-layer/#resolvers) by the `@Ctx()` decorator, and contains information related to the current API request.

When running a stand-alone script, we aren't making any API requests, so we need to create a `RequestContext` object manually. This can be done using the [`RequestContextService`](/reference/typescript-api/request/request-context-service/):

```ts title="src/get-product-count.ts"
// ...
import { RequestContextService } from '@vendure/core';

async function getProductCount() {
    const { app } = await bootstrapWorker(config);
    const productService = app.get(ProductService);
    
    // highlight-start
    const ctx = await app.get(RequestContextService).create({
        apiType: 'admin',
    });
    // highlight-end
    
    const { totalItems } = await productService.findAll(ctx, {take: 0});
}
```


---

---
title: 'Strategies & Configurable Operations'
sidebar_position: 4
---

Vendure is built to be highly configurable and extensible. Two methods of providing this extensibility are **strategies** and **configurable operations**.

## Strategies

A strategy is named after the [Strategy Pattern](https://en.wikipedia.org/wiki/Strategy_pattern), and is a way of providing
a pluggable implementation of a particular feature. Vendure makes heavy use of this pattern to delegate the implementation
of key points of extensibility to the developer.

Examples of strategies include:

- [`OrderCodeStrategy`](/reference/typescript-api/orders/order-code-strategy/) - determines how order codes are generated
- [`StockLocationStrategy`](/reference/typescript-api/products-stock/stock-location-strategy/) - determines which stock locations are used to fulfill an order
- [`ActiveOrderStrategy`](/reference/typescript-api/orders/active-order-strategy/) - determines how the active order in the Shop API is selected
- [`AssetStorageStrategy`](/reference/typescript-api/assets/asset-storage-strategy/) - determines where uploaded assets are stored
- [`GuestCheckoutStrategy`](/reference/typescript-api/orders/guest-checkout-strategy/) - defines rules relating to guest checkouts
- [`OrderItemPriceCalculationStrategy`](/reference/typescript-api/orders/order-item-price-calculation-strategy/) - determines how items are priced when added to the order
- [`TaxLineCalculationStrategy`](/reference/typescript-api/tax/tax-line-calculation-strategy/) - determines how tax is calculated for an order line

As an example, let's take the [`OrderCodeStrategy`](/reference/typescript-api/orders/order-code-strategy/). This strategy
determines how codes are generated when new orders are created. By default, Vendure will use the built-in `DefaultOrderCodeStrategy`
which generates a random 16-character string.

What if you need to change this behavior? For instance, you might have an existing back-office system that is responsible
for generating order codes, which you need to integrate with. Here's how you would do this:

```ts title="src/config/my-order-code-strategy.ts"
import { OrderCodeStrategy, RequestContext } from '@vendure/core';
import { OrderCodeService } from '../services/order-code.service';

export class MyOrderCodeStrategy implements OrderCodeStrategy {

    private orderCodeService: OrderCodeService;

    init(injector) {
        this.orderCodeService = injector.get(OrderCodeService);
    }

    async generate(ctx: RequestContext): string {
        return this.orderCodeService.getNewOrderCode();
    }
}
```

:::info

All strategies can make use of existing services by using the `init()` method. This is because all strategies
extend the underlying [`InjectableStrategy` interface](/reference/typescript-api/common/injectable-strategy). In
this example we are assuming that we already created an `OrderCodeService` which contains all the specific logic for
connecting to our backend service which generates the order codes.

:::

We then need to pass this custom strategy to our config:

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';
import { MyOrderCodeStrategy } from '../config/my-order-code-strategy';

export const config: VendureConfig = {
    // ...
    orderOptions: {
        // highlight-next-line
        orderCodeStrategy: new MyOrderCodeStrategy(),
    },
}
```

### Strategy lifecycle

Strategies can use two optional lifecycle methods:

- `init(injector: Injector)` - called during the bootstrap phase when the server or worker is starting up.
This is where you can inject any services which you need to use in the strategy. You can also perform any other setup logic
needed, such as instantiating a connection to an external service.
- `destroy()` - called during the shutdown of the server or worker. This is where you can perform any cleanup logic, such as
closing connections to external services.

### Passing options to a strategy

Sometimes you might want to pass some configuration options to a strategy.
For example, imagine you want to create a custom [`StockLocationStrategy`](/reference/typescript-api/products-stock/stock-location-strategy/) which
selects a location within a given proximity to the customer's address. You might want to pass the maximum distance to the strategy
in your config:

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';
import { MyStockLocationStrategy } from '../config/my-stock-location-strategy';

export const config: VendureConfig = {
    // ...
    catalogOptions: {
        // highlight-next-line
        stockLocationStrategy: new MyStockLocationStrategy({ maxDistance: 100 }),
    },
}
```

This config will be passed to the strategy's constructor:

```ts title="src/config/my-stock-location-strategy.ts"
import  { ID, ProductVariant, RequestContext, StockLevel, StockLocationStrategy } from '@vendure/core';

export class MyStockLocationStrategy implements StockLocationStrategy {

    constructor(private options: { maxDistance: number }) {}

    getAvailableStock(
        ctx: RequestContext,
        productVariantId: ID,
        stockLevels: StockLevel[]
    ): ProductVariant[] {
        const maxDistance = this.options.maxDistance;
        // ... implementation omitted
    }
}
```

## Configurable Operations

Configurable operations are similar to strategies in that they allow certain aspects of the system to be customized. However,
the main difference is that they can also be _configured_ via the Admin UI. This allows the store owner to make changes to the
behavior of the system without having to restart the server.

So they are typically used to supply some custom logic that needs to accept configurable arguments which can change
at runtime.

Vendure uses the following configurable operations:

- [`CollectionFilter`](/reference/typescript-api/configuration/collection-filter/) - determines which products are included in a collection
- [`PaymentMethodHandler`](/reference/typescript-api/payment/payment-method-handler/) - determines how payments are processed
- [`PromotionCondition`](/reference/typescript-api/promotions/promotion-condition/) - determines whether a promotion is applicable
- [`PromotionAction`](/reference/typescript-api/promotions/promotion-action/) - determines what happens when a promotion is applied
- [`ShippingEligibilityChecker`](/reference/typescript-api/shipping/shipping-eligibility-checker/) - determines whether a shipping method is available
- [`ShippingCalculator`](/reference/typescript-api/shipping/shipping-calculator/) - determines how shipping costs are calculated

Whereas strategies are typically used to provide a single implementation of a particular feature, configurable operations
are used to provide a set of implementations which can be selected from at runtime.

For example, Vendure ships with a set of default CollectionFilters:

```ts title="default-collection-filters.ts"
export const defaultCollectionFilters = [
    facetValueCollectionFilter,
    variantNameCollectionFilter,
    variantIdCollectionFilter,
    productIdCollectionFilter,
];
```

When setting up a Collection, you can choose from these available default filters:

![CollectionFilters](./collection-filters.webp)

When one is selected, the UI will allow you to configure the arguments for that filter:

![CollectionFilters args](./collection-filters-args.webp)

Let's take a look at a simplified implementation of the `variantNameCollectionFilter`:

```ts title="variant-name-collection-filter.ts"
import { CollectionFilter, LanguageCode } from '@vendure/core';

export const variantNameCollectionFilter = new CollectionFilter({
    args: {
        operator: {
            type: 'string',
            ui: {
                component: 'select-form-input',
                options: [
                    { value: 'startsWith' },
                    { value: 'endsWith' },
                    { value: 'contains' },
                    { value: 'doesNotContain' },
                ],
            },
        },
        term: { type: 'string' },
    },
    code: 'variant-name-filter',
    description: [{ languageCode: LanguageCode.en, value: 'Filter by product variant name' }],
    apply: (qb, args) => {
        // ... implementation omitted
    },
});
```

Here are the important parts:

- Configurable operations are **instances** of a pre-defined class, and are instantiated before being passed to your config.
- They must have a `code` property which is a unique string identifier.
- They must have a `description` property which is a localizable, human-readable description of the operation.
- They must have an `args` property which defines the arguments which can be configured via the Admin UI. If the operation has no arguments,
then this would be an empty object.
- They will have one or more methods that need to be implemented, depending on the type of operation. In this case, the `apply()` method
is used to apply the filter to the query builder.

### Configurable operation args

The `args` property is an object which defines the arguments which can be configured via the Admin UI. Each property of the `args`
object is a key-value pair, where the key is the name of the argument, and the value is an object which defines the type of the argument
and any additional configuration.

As an example let's look at the `dummyPaymentMethodHandler`, a test payment method which we ship with Vendure core:

```ts title="dummy-payment-method.ts"
import { PaymentMethodHandler, LanguageCode } from '@vendure/core';

export const dummyPaymentHandler = new PaymentMethodHandler({
    code: 'dummy-payment-handler',
    description: [/* omitted for brevity */],
    args: {
        automaticSettle: {
            type: 'boolean',
            label: [
                {
                    languageCode: LanguageCode.en,
                    value: 'Authorize and settle in 1 step',
                },
            ],
            description: [
                {
                    languageCode: LanguageCode.en,
                    value: 'If enabled, Payments will be created in the "Settled" state.',
                },
            ],
            required: true,
            defaultValue: false,
        },
    },
    createPayment: async (ctx, order, amount, args, metadata, method) => {
        // Inside this method, the `args` argument is type-safe and will be
        // an object with the following shape:
        // {
        //   automaticSettle: boolean
        // }

        // ... implementation omitted
    },
})
```

The following properties are used to configure the argument:

#### type

<span class="badge badge--primary">Required</span>

[`ConfigArgType`](/reference/typescript-api/configurable-operation-def/config-arg-type)

The following types are available: `string`, `int`, `float`, `boolean`, `datetime`, `ID`.

#### label

<span class="badge badge--secondary">Optional</span>

[`LocalizedStringArray`](/reference/typescript-api/configurable-operation-def/localized-string-array/)

A human-readable label for the argument. This is used in the Admin UI.

#### description

<span class="badge badge--secondary">Optional</span>

[`LocalizedStringArray`](/reference/typescript-api/configurable-operation-def/localized-string-array/)

A human-readable description for the argument. This is used in the Admin UI as a tooltip.

#### required

<span class="badge badge--secondary">Optional</span>

`boolean`

Whether the argument is required. If `true`, then the Admin UI will not allow the user to save the configuration
unless a value has been provided for this argument.

#### defaultValue

<span class="badge badge--secondary">Optional</span>

`any` (depends on the `type`)

The default value for the argument. If not provided, then the argument will be `undefined` by default.

#### list

<span class="badge badge--secondary">Optional</span>

`boolean`

Whether the argument is a list of values. If `true`, then the Admin UI will allow the user to add multiple values
for this argument. Defaults to `false`.

#### ui

<span class="badge badge--secondary">Optional</span>

Allows you to specify the UI component that will be used to render the argument in the Admin UI, by specifying
a `component` property, and optional properties to configure that component.

```ts
{
    args: {
        operator: {
            type: 'string',
            ui: {
                component: 'select-form-input',
                options: [
                    { value: 'startsWith' },
                    { value: 'endsWith' },
                    { value: 'contains' },
                    { value: 'doesNotContain' },
                ],
            },
        },
    }
}
```

A full description of the available UI components can be found in the [Custom Fields guide](/guides/developer-guide/custom-fields/#custom-field-ui).

### Injecting dependencies

Configurable operations are instantiated before being passed to your config, so the mechanism for injecting dependencies
is similar to that of strategies: namely you use an optional `init()` method to inject dependencies into the operation instance.

The main difference is that the injected dependency cannot then be stored as a class property, since you are not defining
a class when you define a configurable operation. Instead, you can store the dependency as a closure variable.

Here’s an example of a ShippingCalculator that injects a service which has been defined in a plugin:

```ts title="src/config/custom-shipping-calculator.ts"
import { Injector, ShippingCalculator } from '@vendure/core';
import { ShippingRatesService } from './shipping-rates.service';

// We keep reference to our injected service by keeping it
// in the top-level scope of the file.
let shippingRatesService: ShippingRatesService;

export const customShippingCalculator = new ShippingCalculator({
    code: 'custom-shipping-calculator',
    description: [],
    args: {},

    init(injector: Injector) {
        // The init function is called during bootstrap, and allows
        // us to inject any providers we need.
        shippingRatesService = injector.get(ShippingRatesService);
    },

    calculate: async (order, args) => {
        // We can now use the injected provider in the business logic.
        const { price, priceWithTax } = await shippingRatesService.getRate({
            destination: order.shippingAddress,
            contents: order.lines,
        });

        return {
            price,
            priceWithTax,
        };
    },
});
```






---

---
title: "Testing"
showtoc: true
---

# Testing

Vendure plugins allow you to extend all aspects of the standard Vendure server. When a plugin gets somewhat complex (defining new entities, extending the GraphQL schema, implementing custom resolvers), you may wish to create automated tests to ensure your plugin is correct.

The `@vendure/testing` package gives you some simple but powerful tooling for creating end-to-end tests for your custom Vendure code.

By "end-to-end" we mean we are testing the _entire server stack_ - from API, to services, to database - by making a real API request, and then making assertions about the response. This is a very effective way to ensure that _all_ parts of your plugin are working correctly together.

:::info
For a working example of a Vendure plugin with e2e testing, see the [real-world-vendure Reviews plugin](https://github.com/vendure-ecommerce/real-world-vendure/tree/master/src/plugins/reviews)
:::

## Usage

### Install dependencies

* [`@vendure/testing`](https://www.npmjs.com/package/@vendure/testing)
* [`vitest`](https://vitest.dev/) You'll need to install a testing framework. In this example, we will use [Vitest](https://vitest.dev/) as it has very good support for the modern JavaScript features that Vendure uses, and is very fast.
* [`graphql-tag`](https://www.npmjs.com/package/graphql-tag) This is not strictly required but makes it much easier to create the DocumentNodes needed to query your server.
* We also need to install some packages to allow us to compile TypeScript code that uses decorators:
  - `@swc/core`
  - `unplugin-swc`

```sh
npm install --save-dev @vendure/testing vitest graphql-tag @swc/core unplugin-swc
```

### Configure Vitest

Create a `vitest.config.mts` file in the root of your project:

```ts title="vitest.config.mts"
import path from 'path';
import swc from 'unplugin-swc';
import { defineConfig } from 'vitest/config';

export default defineConfig({
    test: {
        include: ['**/*.e2e-spec.ts'],
        typecheck: {
            tsconfig: path.join(__dirname, 'tsconfig.e2e.json'),
        },
    },
    plugins: [
        // SWC required to support decorators used in test plugins
        // See https://github.com/vitest-dev/vitest/issues/708#issuecomment-1118628479
        // Vite plugin
        swc.vite({
            jsc: {
                transform: {
                    // See https://github.com/vendure-ecommerce/vendure/issues/2099
                    useDefineForClassFields: false,
                },
            },
        }),
    ],
});
```

and a `tsconfig.e2e.json` tsconfig file for the tests:

```json title="tsconfig.e2e.json"
{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "types": ["node"],
    "lib": ["es2015"],
    "useDefineForClassFields": false,
    "skipLibCheck": true,
    "inlineSourceMap": false,
    "sourceMap": true,
    "allowSyntheticDefaultImports": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "esModuleInterop": true
  }
}

```

### Register database-specific initializers

The `@vendure/testing` package uses "initializers" to create the test databases and populate them with initial data. We ship with initializers for `sqljs`, `postgres` and `mysql`. Custom initializers can be created to support running e2e tests against other databases supported by TypeORM. See the [`TestDbInitializer` docs](/reference/typescript-api/testing/test-db-initializer/) for more details.

```ts title="src/plugins/my-plugin/e2e/my-plugin.e2e-spec.ts"
import {
    MysqlInitializer,
    PostgresInitializer,
    SqljsInitializer,
    registerInitializer,
} from '@vendure/testing';

const sqliteDataDir = path.join(__dirname, '__data__');

registerInitializer('sqljs', new SqljsInitializer(sqliteDataDir));
registerInitializer('postgres', new PostgresInitializer());
registerInitializer('mysql', new MysqlInitializer());
```

:::info
Note re. the `sqliteDataDir`: The first time this test suite is run with the `SqljsInitializer`, the populated data will be saved into an SQLite file, stored in the directory specified by this constructor arg. On subsequent runs of the test suite, the data-population step will be skipped and the initial data directly loaded from the SQLite file. This method of caching significantly speeds up the e2e test runs. All the .sqlite files created in the `sqliteDataDir` can safely be deleted at any time.
:::

### Create a test environment

The `@vendure/testing` package exports a [`createTestEnvironment` function](/reference/typescript-api/testing/create-test-environment/) which is used to set up a Vendure server and GraphQL clients to interact with both the Shop and Admin APIs:

```ts title="src/plugins/my-plugin/e2e/my-plugin.e2e-spec.ts"
import { createTestEnvironment, testConfig } from '@vendure/testing';
import { describe } from 'vitest';
import { MyPlugin } from '../my-plugin.ts';

describe('my plugin', () => {

    const {server, adminClient, shopClient} = createTestEnvironment({
        ...testConfig,
        plugins: [MyPlugin],
    });

});
```

Notice that we pass a [`VendureConfig`](/reference/typescript-api/configuration/vendure-config/) object into the `createTestEnvironment` function. The testing package provides a special [`testConfig`](/reference/typescript-api/testing/test-config/) which is pre-configured for e2e tests, but any aspect can be overridden for your tests. Here we are configuring the server to load the plugin under test, `MyPlugin`. 

:::caution
**Note**: If you need to deeply merge in some custom configuration, use the [`mergeConfig` function](/reference/typescript-api/configuration/merge-config/) which is provided by `@vendure/core`.
:::

### Initialize the server

The [`TestServer`](/reference/typescript-api/testing/test-server/) needs to be initialized before it can be used. The `TestServer.init()` method takes an options object which defines how to populate the server:

```ts title="src/plugins/my-plugin/e2e/my-plugin.e2e-spec.ts"
import { beforeAll, afterAll } from 'vitest';
import { myInitialData } from './fixtures/my-initial-data.ts';

// ...

beforeAll(async () => {
    await server.init({
        productsCsvPath: path.join(__dirname, 'fixtures/e2e-products.csv'),
        initialData: myInitialData,
        customerCount: 2,
    });
    await adminClient.asSuperAdmin();
}, 60000);

afterAll(async () => {
    await server.destroy();
});
```

An explanation of the options:

* `productsCsvPath` This is a path to an optional CSV file containing product data. See [Product Import Format](/guides/developer-guide/importing-data/#product-import-format). You can see [an example used in the Vendure e2e tests](https://github.com/vendure-ecommerce/vendure/blob/master/packages/core/e2e/fixtures/e2e-products-full.csv) to get an idea of how it works. To start with you can just copy this file directly and use it as-is.
* `initialData` This is an object which defines how other non-product data (Collections, ShippingMethods, Countries etc.) is populated. See [Initial Data Format](/guides/developer-guide/importing-data/#initial-data). You can [copy this example from the Vendure e2e tests](https://github.com/vendure-ecommerce/vendure/blob/master/e2e-common/e2e-initial-data.ts)
* `customerCount` Specifies the number of fake Customers to create. Defaults to 10 if not specified.

### Write your tests

Now we are all set up to create a test. Let's test one of the GraphQL queries used by our fictional plugin:

```ts title="src/plugins/my-plugin/e2e/my-plugin.e2e-spec.ts"
import gql from 'graphql-tag';
import { it, expect, beforeAll, afterAll } from 'vitest';
import { myInitialData } from './fixtures/my-initial-data.ts';

it('myNewQuery returns the expected result', async () => {
    adminClient.asSuperAdmin(); // log in as the SuperAdmin user

    const query = gql`
    query MyNewQuery($id: ID!) {
      myNewQuery(id: $id) {
        field1
        field2
      }
    }
  `;
    const result = await adminClient.query(query, {id: 123});

    expect(result.myNewQuery).toEqual({ /* ... */})
});
```

Running the test will then assert that your new query works as expected.

### Run your tests

All that's left is to run your tests to find out whether your code behaves as expected!

:::caution
**Note:** When using **Vitest** with multiple test suites (multiple `.e2e-spec.ts` files), it will attempt to run them in parallel. If all the test servers are running
on the same port (the default in the `testConfig` is `3050`), then this will cause a port conflict. To avoid this, you can manually set a unique port for each test suite. Be aware that `mergeConfig` is used here:

```ts title="src/plugins/my-plugin/e2e/my-plugin.e2e-spec.ts"
import { createTestEnvironment, testConfig } from '@vendure/testing';
import { mergeConfig } from "@vendure/core";
import { describe } from 'vitest';
import { MyPlugin } from '../my-plugin.ts';

describe('my plugin', () => {

    const {server, adminClient, shopClient} = createTestEnvironment(mergeConfig(testConfig, {
        // highlight-start
        apiOptions: {
            port: 3051,
        },
        // highlight-end
        plugins: [MyPlugin],
    }));

});
```
:::

## Accessing internal services

It is possible to access any internal service of the Vendure server via the `server.app` object, which is an instance of the NestJS `INestApplication`.

For example, to access the `ProductService`:

```ts title="src/plugins/my-plugin/e2e/my-plugin.e2e-spec.ts"
import { createTestEnvironment, testConfig } from '@vendure/testing';
import { describe, beforeAll } from 'vitest';
import { MyPlugin } from '../my-plugin.ts';

describe('my plugin', () => {
    
    const { server, adminClient, shopClient } = createTestEnvironment({
        ...testConfig,
        plugins: [MyPlugin],
    });
    
    // highlight-next-line
    let productService: ProductService;
    
    beforeAll(async () => {
        await server.init({
            productsCsvPath: path.join(__dirname, 'fixtures/e2e-products.csv'),
            initialData: myInitialData,
            customerCount: 2,
        });
        await adminClient.asSuperAdmin();
        // highlight-next-line
        productService = server.app.get(ProductService);
    }, 60000);

});
```


---

---
title: 'The API Layer'
sidebar_position: 1
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Vendure is a headless platform, which means that all functionality is exposed via GraphQL APIs. The API can be thought of
as a number of layers through which a request will pass, each of which is responsible for a different aspect of the
request/response lifecycle.

## The journey of an API call

Let's take a basic API call and trace its journey from the client to the server and back again.


<Tabs>
<TabItem value="Request" label="Request" default>

```graphql title="GraphQL Playground Shop API"
query {
    product(id: "1") {
        id
        name
        description
    }
}
```

This query is asking for the `id`, `name` and `description` of a `Product` with the id of `1`.

</TabItem>
<TabItem value="Response" label="Response">

```json
{
  "data": {
    "product": {
      "id": "1",
      "name": "Laptop",
      "description": "Now equipped with seventh-generation Intel Core processors, Laptop is snappier than ever. From daily tasks like launching apps and opening files to more advanced computing, you can power through your day thanks to faster SSDs and Turbo Boost processing up to 3.6GHz."
    }
  }
}
```

GraphQL returns only the specific fields you ask for in your query.

</TabItem>
</Tabs>


:::note

If you have your local development server running, you can try this out by opening the GraphQL Playground in your browser:

[http://localhost:3000/shop-api](http://localhost:3000/shop-api)

:::

![./Vendure_docs-api_request.webp](./Vendure_docs-api_request.webp)


## Middleware

"Middleware" is a term for a function which is executed before or after the main logic of a request. In Vendure, middleware
is used to perform tasks such as authentication, logging, and error handling. There are several types of middleware:

### Express middleware

At the lowest level, Vendure makes use of the popular Express server library. [Express middleware](https://expressjs.com/en/guide/using-middleware.html)
can be added to the sever via the [`apiOptions.middleware`](/reference/typescript-api/configuration/api-options#middleware) config property. There are hundreds of tried-and-tested Express
middleware packages available, and they can be used to add functionality such as CORS, compression, rate-limiting, etc.

Here's a simple example demonstrating Express middleware which will log a message whenever a request is received to the
Admin API:

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';
import { RequestHandler } from 'express';

/**
* This is a custom middleware function that logs a message whenever a request is received.
*/
const myMiddleware: RequestHandler = (req, res, next) => {
    console.log('Request received!');
    next();
};

export const config: VendureConfig = {
    // ...
    apiOptions: {
        middleware: [
            {
                // We will execute our custom handler only for requests to the Admin API
                route: 'admin-api',
                handler: myMiddleware,
            }
        ],
    },
};
```

### NestJS middleware

You can also define [NestJS middleware](https://docs.nestjs.com/middleware) which works like Express middleware but also
has access to the NestJS dependency injection system.

```ts title="src/vendure-config.ts"
import { VendureConfig, ConfigService } from '@vendure/core';
import { Injectable, NestMiddleware } from '@nestjs/common';
import { Request, Response, NextFunction } from 'express';


@Injectable()
class MyNestMiddleware implements NestMiddleware {
    // Dependencies can be injected via the constructor
    constructor(private configService: ConfigService) {}

    use(req: Request, res: Response, next: NextFunction) {
        console.log(`NestJS middleware: current port is ${this.configService.apiOptions.port}`);
        next();
    }
}

export const config: VendureConfig = {
    // ...
    apiOptions: {
        middleware: [
            {
                route: 'admin-api',
                handler: MyNestMiddleware,
            }
        ],
    },
};
```

NestJS allows you to define specific types of middleware including [Guards](https://docs.nestjs.com/guards),
[Interceptors](https://docs.nestjs.com/interceptors), [Pipes](https://docs.nestjs.com/pipes) and [Filters](https://docs.nestjs.com/exception-filters).

Vendure uses a number of these mechanisms internally to handle authentication, transaction management, error handling and
data transformation.

### Global NestJS middleware

Guards, interceptors, pipes and filters can be added to your own custom resolvers and controllers
using the NestJS decorators as given in the NestJS docs. However, a common pattern is to register them globally via a
[Vendure plugin](/guides/developer-guide/plugins/):

```ts title="src/plugins/my-plugin/my-plugin.ts"
import { VendurePlugin } from '@vendure/core';
import { APP_GUARD, APP_FILTER, APP_INTERCEPTOR  } from '@nestjs/core';

// Some custom NestJS middleware classes which we want to apply globally
import { MyCustomGuard, MyCustomInterceptor, MyCustomExceptionFilter } from './my-custom-middleware';

@VendurePlugin({
    // ...
    providers: [
        // This is the syntax needed to apply your guards,
        // interceptors and filters globally
        {
            provide: APP_GUARD,
            useClass: MyCustomGuard,
        },
        {
            provide: APP_INTERCEPTOR,
            useClass: MyCustomInterceptor,
        },
        {
            // Note: registering a global "catch all" exception filter
            // must be used with caution as it will override the built-in
            // Vendure exception filter. See https://github.com/nestjs/nest/issues/3252
            // To implement custom error handling, it is recommended to use
            // a custom ErrorHandlerStrategy instead.
            provide: APP_FILTER,
            useClass: MyCustomExceptionFilter,
        },
    ],
})
export class MyPlugin {}
```

Adding this plugin to your Vendure config `plugins` array will now apply these middleware classes to all requests.

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';
import { MyPlugin } from './plugins/my-plugin/my-plugin';

export const config: VendureConfig = {
    // ...
    plugins: [
        MyPlugin,
    ],
};
```



### Apollo Server plugins
Apollo Server (the underlying GraphQL server library used by Vendure) allows you to define
[plugins](https://www.apollographql.com/docs/apollo-server/integrations/plugins/) which can be used to hook into various
stages of the GraphQL request lifecycle and perform tasks such as data transformation. These are defined via the
[`apiOptions.apolloServerPlugins`](/reference/typescript-api/configuration/api-options#apolloserverplugins) config property.



## Resolvers

A "resolver" is a GraphQL concept, and refers to a function which is responsible for returning the data for a particular
field. In Vendure, a resolver can also refer to a class which contains multiple resolver functions. For every query or
mutation, there is a corresponding resolver function which is responsible for returning the requested data (and performing
side-effect such as updating data in the case of mutations).

Here's a simplified example of a resolver function for the `product` query:

```ts
import { Query, Resolver, Args } from '@nestjs/graphql';
import { Ctx, RequestContext, ProductService } from '@vendure/core';

@Resolver()
export class ShopProductsResolver {

     constructor(private productService: ProductService) {}

     @Query()
     product(@Ctx() ctx: RequestContext, @Args() args: { id: string }) {
         return this.productService.findOne(ctx, args.id);
     }
}
```

- The `@Resolver()` decorator marks this class as a resolver.
- The `@Query()` decorator marks the `product()` method as a resolver function.
- The `@Ctx()` decorator injects the [`RequestContext` object](/reference/typescript-api/request/request-context/), which contains information about the
current request, such as the current user, the active channel, the active language, etc. The `RequestContext` is a key part
of the Vendure architecture, and is used throughout the application to provide context to the various services and plugins. In general, your
resolver functions should always accept a `RequestContext` as the first argument, and pass it through to the services.
- The `@Args()` decorator injects the arguments passed to the query, in this case the `id` that we provided in our query.

As you can see, the resolver function is very simple, and simply delegates the work to the `ProductService` which is
responsible for fetching the data from the database.

:::tip
In general, resolver functions should be kept as simple as possible,
and the bulk of the business logic should be delegated to the service layer.
:::

## API Decorators

Following the pattern of NestJS, Vendure makes use of decorators to control various aspects of the API. Here are the
important decorators to be aware of:

### `@Resolver()`

This is exported by the `@nestjs/graphql` package. It marks a class as a resolver, meaning that its methods can be used
to resolve the fields of a GraphQL query or mutation.

```ts title="src/plugins/wishlist/api/wishlist.resolver.ts"
import { Resolver } from '@nestjs/graphql';

// highlight-next-line
@Resolver()
export class WishlistResolver {
    // ...
}
```

### `@Query()`

This is exported by the `@nestjs/graphql` package. It marks a method as a resolver function for a query. The method name
should match the name of the query in the GraphQL schema, or if the method name is different, a name can be provided as
an argument to the decorator.

```ts title="src/plugins/wishlist/api/wishlist.resolver.ts"
import { Query, Resolver } from '@nestjs/graphql';

@Resolver()
export class WishlistResolver {

    // highlight-next-line
    @Query()
    wishlist() {
        // ...
    }
}
```

### `@Mutation()`

This is exported by the `@nestjs/graphql` package. It marks a method as a resolver function for a mutation. The method name
should match the name of the mutation in the GraphQL schema, or if the method name is different, a name can be provided as
an argument to the decorator.

```ts title="src/plugins/wishlist/api/wishlist.resolver.ts"
import { Mutation, Resolver } from '@nestjs/graphql';

@Resolver()
export class WishlistResolver {

    // highlight-next-line
    @Mutation()
    addItemToWishlist() {
        // ...
    }
}
```

### `@Allow()`

The [`Allow` decorator](/reference/typescript-api/request/allow-decorator) is exported by the `@vendure/core` package. It is used to control access to queries and mutations. It takes a list
of [Permissions](/reference/typescript-api/common/permission/) and if the current user does not have at least one of the
permissions, then the query or mutation will return an error.

```ts title="src/plugins/wishlist/api/wishlist.resolver.ts"
import { Mutation, Resolver } from '@nestjs/graphql';
import { Allow, Permission } from '@vendure/core';

@Resolver()
export class WishlistResolver {

    @Mutation()
    // highlight-next-line
    @Allow(Permission.UpdateCustomer)
    updateCustomerWishlist() {
        // ...
    }
}
```

### `@Transaction()`

The [`Transaction` decorator](/reference/typescript-api/request/transaction-decorator/) is exported by the `@vendure/core` package. It is used to wrap a resolver function in a database transaction. It is
normally used with mutations, since queries typically do not modify data.

```ts title="src/plugins/wishlist/api/wishlist.resolver.ts"
import { Mutation, Resolver } from '@nestjs/graphql';
import { Transaction } from '@vendure/core';

@Resolver()
export class WishlistResolver {

    // highlight-next-line
    @Transaction()
    @Mutation()
    addItemToWishlist() {
        // if an error is thrown here, the
        // entire transaction will be rolled back
    }
}
```

:::note
The `@Transaction()` decorator _only_ works when used with a `RequestContext` object (see the `@Ctx()` decorator below).

This is because the `Transaction` decorator stores the transaction context on the `RequestContext` object, and by passing
this object to the service layer, the services and thus database calls can access the transaction context.
:::

### `@Ctx()`

The [`Ctx` decorator](/reference/typescript-api/request/ctx-decorator/) is exported by the `@vendure/core` package. It is used to inject the
[`RequestContext` object](/reference/typescript-api/request/request-context/) into a resolver function. The `RequestContext` contains information about the
current request, such as the current user, the active channel, the active language, etc. The `RequestContext` is a key part
of the Vendure architecture, and is used throughout the application to provide context to the various services and plugins.

```ts title="src/plugins/wishlist/api/wishlist.resolver.ts"
import { Mutation, Resolver } from '@nestjs/graphql';
import { Ctx, RequestContext } from '@vendure/core';

@Resolver()
export class WishlistResolver {

    @Mutation()
    // highlight-next-line
    addItemToWishlist(@Ctx() ctx: RequestContext) {
        // ...
    }
}
```

:::tip
As a general rule, _always_ use the `@Ctx()` decorator to inject the `RequestContext` into your resolver functions.
:::

### `@Args()`

This is exported by the `@nestjs/graphql` package. It is used to inject the arguments passed to a query or mutation.

Given the a schema definition like this:

```graphql
extend type Mutation {
    addItemToWishlist(variantId: ID!): Wishlist
}
```

The resolver function would look like this:

```ts title="src/plugins/wishlist/api/wishlist.resolver.ts"
import { Mutation, Resolver, Args } from '@nestjs/graphql';
import { Ctx, RequestContext, ID } from '@vendure/core';

@Resolver()
export class WishlistResolver {

    @Mutation()
    addItemToWishlist(
        @Ctx() ctx: RequestContext,
        // highlight-next-line
        @Args() args: { variantId: ID }
    ) {
        // ...
    }
}
```

As you can see, the `@Args()` decorator injects the arguments passed to the query, in this case the `variantId` that we provided in our query.

## Field resolvers

So far, we've seen examples of resolvers for queries and mutations. However, there is another type of resolver which is
used to resolve the fields of a type. For example, given the following schema definition:

```graphql
type WishlistItem {
    id: ID!
    // highlight-next-line
    product: Product!
}
```

The `product` field is a relation to the `Product` type. The `product` field resolver
would look like this:

```ts title="src/plugins/wishlist/api/wishlist-item.resolver.ts"
import { Parent, ResolveField, Resolver } from '@nestjs/graphql';
import { Ctx, RequestContext } from '@vendure/core';

import { WishlistItem } from '../entities/wishlist-item.entity';

// highlight-next-line
@Resolver('WishlistItem')
export class WishlistItemResolver {

    // highlight-next-line
    @ResolveField()
    product(
        @Ctx() ctx: RequestContext,
        // highlight-next-line
        @Parent() wishlistItem: WishlistItem
    ) {
        // ...
    }
}
```

Note that in this example, the `@Resolver()` decorator has an argument of `'WishlistItem'`. This tells NestJS that
this resolver is for the `WishlistItem` type, and that when we use the `@ResolveField()` decorator, we are defining
a resolver for a field of that type.

In this example we're defining a resolver for the `product` field of the `WishlistItem` type. The
`@ResolveField()` decorator is used to mark a method as a field resolver. The method name should match the name of the
field in the GraphQL schema, or if the method name is different, a name can be provided as an argument to the decorator.

## REST endpoints

Although Vendure is primarily a GraphQL-based API, it is possible to add REST endpoints to the API. This is useful if
you need to integrate with a third-party service or client application which only supports REST, for example.

Creating a REST endpoint is covered in detail in the [Add a REST endpoint
guide](/guides/developer-guide/rest-endpoint/).


---

---
title: 'The Service Layer'
sidebar_position: 2
---

The service layer is the core of the application. This is where the business logic is implemented, and where
the application interacts with the database. When a request comes in to the API, it gets routed to a resolver
which then calls a service method to perform the required operation.

![../the-api-layer/Vendure_docs-api_request.webp](../the-api-layer/Vendure_docs-api_request.webp)

:::info
Services are classes which, in NestJS terms, are [providers](https://docs.nestjs.com/providers#services). They
follow all the rules of NestJS providers, including dependency injection, scoping, etc.
:::

Services are generally scoped to a specific domain or entity. For instance, in the Vendure core, there is a [`Product` entity](/reference/typescript-api/entities/product),
and a corresponding [`ProductService`](/reference/typescript-api/services/product-service) which contains all the methods for interacting with products.

Here's a simplified example of a `ProductService`, including an implementation of the `findOne()` method that was
used in the example in the [previous section](/guides/developer-guide/the-api-layer/#resolvers):

```ts title="src/services/product.service.ts"
import { Injectable } from '@nestjs/common';
import { IsNull } from 'typeorm';
import { ID, Product, RequestContext, TransactionalConnection, TranslatorService } from '@vendure/core';

@Injectable()
export class ProductService {

    constructor(private connection: TransactionalConnection,
                private translator: TranslatorService){}

    /**
     * @description
     * Returns a Product with the given id, or undefined if not found.
     */
    async findOne(ctx: RequestContext, productId: ID): Promise<Product | undefined> {
        const product = await this.connection.findOneInChannel(ctx, Product, productId, ctx.channelId, {
            where: {
                deletedAt: IsNull(),
            },
        });
        if (!product) {
            return;
        }
        return this.translator.translate(product, ctx);
    }

    // ... other methods
    findMany() {}
    create() {}
    update() {}
}
```

- The `@Injectable()` decorator is a [NestJS](https://docs.nestjs.com/providers#services) decorator which allows the service
    to be injected into other services or resolvers.
- The `constructor()` method is where the dependencies of the service are injected. In this case, the `TransactionalConnection`
    is used to access the database, and the `TranslatorService` is used to translate the Product entity into the current
    language.

## Using core services

All the internal Vendure services can be used in your own plugins and scripts. They are listed in the [Services API reference](/reference/typescript-api/services/) and
can be imported from the `@vendure/core` package.

To make use of a core service in your own plugin, you need to ensure your plugin is importing the `PluginCommonModule` and
then inject the desired service into your own service's constructor:

```ts title="src/my-plugin/my.plugin.ts"
import { PluginCommonModule, VendurePlugin } from '@vendure/core';
import { MyService } from './services/my.service';

@VendurePlugin({
    // highlight-start
    imports: [PluginCommonModule],
    providers: [MyService],
    // highlight-end
})
export class MyPlugin {}
```

```ts title="src/my-plugin/services/my.service.ts"
import { Injectable } from '@nestjs/common';
import { ProductService } from '@vendure/core';

@Injectable()
export class MyService {

    // highlight-next-line
    constructor(private productService: ProductService) {}

    // you can now use the productService methods
}
```

## Accessing the database

One of the main responsibilities of the service layer is to interact with the database. For this, you will be using
the [`TransactionalConnection` class](/reference/typescript-api/data-access/transactional-connection/), which is a wrapper
around the [TypeORM `DataSource` object](https://typeorm.io/data-source-api). The primary purpose of the `TransactionalConnection`
is to ensure that database operations can be performed within a transaction (which is essential for ensuring data integrity), even
across multiple services. Furthermore, it exposes some helper methods which make it easier to perform common operations.

:::info

Always pass the `RequestContext` (`ctx`) to the `TransactionalConnection` methods. This ensures the operation occurs within
any active transaction.

:::

There are two primary APIs for accessing data provided by TypeORM: the **Find API** and the **QueryBuilder API**.

### The Find API

This API is the most convenient and type-safe way to query the database. It provides a powerful type-safe way to query
including support for eager relations, pagination, sorting, filtering and more.

Here are some examples of using the Find API:

```ts title="src/services/item.service.ts"
import { Injectable } from '@nestjs/common';
import { ID, RequestContext, TransactionalConnection } from '@vendure/core';
import { IsNull } from 'typeorm';
import { Item } from '../entities/item.entity';

@Injectable()
export class ItemService {

    constructor(private connection: TransactionalConnection) {}

    findById(ctx: RequestContext, itemId: ID): Promise<Item | null> {
        return this.connection.getRepository(ctx, Item).findOne({
            where: { id: itemId },
        });
    }

    findByName(ctx: RequestContext, name: string): Promise<Item | null> {
        return this.connection.getRepository(ctx, Item).findOne({
            where: {
                // Multiple where clauses can be specified,
                // which are joined with AND
                name,
                deletedAt: IsNull(),
            },
        });
    }

    findWithRelations() {
        return this.connection.getRepository(ctx, Item).findOne({
            where: { name },
            relations: {
                // Join the `item.customer` relation
                customer: true,
                product: {
                    // Here we are joining a nested relation `item.product.featuredAsset`
                    featuredAsset: true,
                },
            },
        });
    }

    findMany(ctx: RequestContext): Promise<Item[]> {
        return this.connection.getRepository(ctx, Item).find({
            // Pagination
            skip: 0,
            take: 10,
            // Sorting
            order: {
                name: 'ASC',
            },
        });
    }
}
```

:::info

Further examples can be found in the [TypeORM Find Options documentation](https://typeorm.io/find-options).

:::

### The QueryBuilder API

When the Find API is not sufficient, the QueryBuilder API can be used to construct more complex queries. For instance,
if you want to have a more complex `WHERE` clause than what can be achieved with the Find API, or if you want to perform
sub-queries, then the QueryBuilder API is the way to go.

Here are some examples of using the QueryBuilder API:

```ts title="src/services/item.service.ts"
import { Injectable } from '@nestjs/common';
import { ID, RequestContext, TransactionalConnection } from '@vendure/core';
import { Brackets, IsNull } from 'typeorm';
import { Item } from '../entities/item.entity';

@Injectable()
export class ItemService {

    constructor(private connection: TransactionalConnection) {}

    findById(ctx: RequestContext, itemId: ID): Promise<Item | null> {
        // This is simple enough that you should prefer the Find API,
        // but here is how it would be done with the QueryBuilder API:
        return this.connection.getRepository(ctx, Item).createQueryBuilder('item')
            .where('item.id = :id', { id: itemId })
            .getOne();
    }

    findManyWithSubquery(ctx: RequestContext, name: string) {
        // Here's a more complex query that would not be possible using the Find API:
        return this.connection.getRepository(ctx, Item).createQueryBuilder('item')
            .where('item.name = :name', { name })
            .andWhere(
                new Brackets(qb1 => {
                    qb1.where('item.state = :state1', { state1: 'PENDING' })
                       .orWhere('item.state = :state2', { state2: 'RETRYING' });
                }),
            )
            .orderBy('item.createdAt', 'ASC')
            .getMany();
    }
}
```

:::info

Further examples can be found in the [TypeORM QueryBuilder documentation](https://typeorm.io/select-query-builder).

:::

### Working with relations

One limitation of TypeORM's typings is that we have no way of knowing at build-time whether a particular relation will be
joined at runtime. For instance, the following code will build without issues, but will result in a runtime error:

```ts
const product = await this.connection.getRepository(ctx, Product).findOne({
    where: { id: productId },
});
if (product) {
    // highlight-start
    console.log(product.featuredAsset.preview);
    // ^ Error: Cannot read property 'preview' of undefined
    // highlight-end
}
```

This is because the `featuredAsset` relation is not joined by default. The simple fix for the above example is to use
the `relations` option:

```ts
const product = await this.connection.getRepository(ctx, Product).findOne({
    where: { id: productId },
    // highlight-next-line
    relations: { featuredAsset: true },
});
```
or in the case of the QueryBuilder API, we can use the `leftJoinAndSelect()` method:

```ts
const product = await this.connection.getRepository(ctx, Product).createQueryBuilder('product')
    // highlight-next-line
    .leftJoinAndSelect('product.featuredAsset', 'featuredAsset')
    .where('product.id = :id', { id: productId })
    .getOne();
```

### Using the EntityHydrator

But what about when we do not control the code which fetches the entity from the database? For instance, we might be implementing
a function which gets an entity passed to it by Vendure. In this case, we can use the [`EntityHydrator`](/reference/typescript-api/data-access/entity-hydrator/)
to ensure that a given relation is "hydrated" (i.e. joined) before we use it:

```ts
import { EntityHydrator, ShippingCalculator } from '@vendure/core';

let entityHydrator: EntityHydrator;

const myShippingCalculator = new ShippingCalculator({
    // ... rest of config omitted for brevity
    init(injector) {
        entityHydrator = injector.get(EntityHydrator);
    },
    calculate: (ctx, order, args) => {
      // highlight-start
      // ensure that the customer and customer.groups relations are joined
      await entityHydrator.hydrate(ctx, order, { relations: ['customer.groups' ]});
      // highlight-end

      if (order.customer?.groups?.some(g => g.name === 'VIP')) {
        // ... do something special for VIP customers
      } else {
        // ... do something else
      }
    },
});
```

### Joining relations in built-in service methods

Many of the core services allow an optional `relations` argument in their `findOne()` and `findMany()` and related methods.
This allows you to specify which relations should be joined when the query is executed. For instance, in the [`ProductService`](/reference/typescript-api/services/product-service)
there is a `findOne()` method which allows you to specify which relations should be joined:

```ts
const productWithAssets = await this.productService
    .findOne(ctx, productId, ['featuredAsset', 'assets']);
```



---

---
title: "Implementing Translatable"
showtoc: true
---

## Defining translatable entities

Making an entity translatable means that string properties of the entity can have a different values for multiple languages.
To make an entity translatable, you need to implement the [`Translatable`](/reference/typescript-api/entities/interfaces/#translatable) interface and add a `translations` property to the entity.

```ts title="src/plugins/requests/entities/product-request.entity.ts"
import { DeepPartial } from '@vendure/common/lib/shared-types';
import { VendureEntity, Product, EntityId, ID, Translatable } from '@vendure/core';
import { Column, Entity, ManyToOne } from 'typeorm';

import { ProductRequestTranslation } from './product-request-translation.entity';

@Entity()
class ProductRequest extends VendureEntity implements Translatable {
    constructor(input?: DeepPartial<ProductRequest>) {
        super(input);
    }
// highlight-start
    text: LocaleString;
// highlight-end
    
    @ManyToOne(type => Product)
    product: Product;

    @EntityId()
    productId: ID;


// highlight-start
    @OneToMany(() => ProductRequestTranslation, translation => translation.base, { eager: true })
    translations: Array<Translation<ProductRequest>>;
// highlight-end
}
```

The `translations` property is a `OneToMany` relation to the translations. Any fields that are to be translated are of type `LocaleString`, and **do not have a `@Column()` decorator**.
This is because the `text` field here does not in fact exist in the database in the `product_request` table. Instead, it belongs to the `product_request_translations` table of the `ProductRequestTranslation` entity:

```ts title="src/plugins/requests/entities/product-request-translation.entity.ts"
import { DeepPartial } from '@vendure/common/lib/shared-types';
import { HasCustomFields, Translation, VendureEntity, LanguageCode } from '@vendure/core';
import { Column, Entity, Index, ManyToOne } from 'typeorm';

import { ProductRequest } from './release-note.entity';

@Entity()
export class ProductRequestTranslation
    extends VendureEntity
    implements Translation<ProductRequest>, HasCustomFields
{
    constructor(input?: DeepPartial<Translation<ProductRequestTranslation>>) {
        super(input);
    }

    @Column('varchar')
    languageCode: LanguageCode;

    @Column('varchar')
// highlight-start
    text: string; // same name as the translatable field in the base entity
// highlight-end
    @Index()
    @ManyToOne(() => ProductRequest, base => base.translations, { onDelete: 'CASCADE' })
    base: ProductRequest;
}
```

Thus there is a one-to-many relation between `ProductRequest` and `ProductRequestTranslation`, which allows Vendure to handle multiple translations of the same entity. The `ProductRequestTranslation` entity also implements the `Translation` interface, which requires the `languageCode` field and a reference to the base entity.

### Translations in the GraphQL schema
Since the `text` field is getting hydrated with the translation it should be exposed in the GraphQL Schema. Additionally, the `ProductRequestTranslation` type should
be defined as well, to access other translations as well:
```graphql title="src/plugins/requests/api/types.ts"
type ProductRequestTranslation {
    id: ID!
    createdAt: DateTime!
    updatedAt: DateTime!
// highlight-start
    languageCode: LanguageCode!
    text: String!
// highlight-end
}

type ProductRequest implements Node {
    id: ID!
    createdAt: DateTime!
    updatedAt: DateTime!
    # Will be filled with the translation for the current language
    text: String!
// highlight-next-line
    translations: [ProductRequestTranslation!]!
}

```

## Creating translatable entities

Creating a translatable entity is usually done by using the [`TranslateableSaver`](/reference/typescript-api/service-helpers/translatable-saver/). This injectable service provides a `create` and `update` method which can be used to save or update a translatable entity.

```ts title="src/plugins/requests/service/product-request.service.ts"
export class RequestService {

    constructor(private translatableSaver: TranslatableSaver) {}

    async create(ctx: RequestContext, input: CreateProductRequestInput): Promise<ProductRequest> {
        const request = await this.translatableSaver.create({
            ctx,
            input,
            entityType: ProductRequest,
            translationType: ProductRequestTranslation,
            beforeSave: async f => {
                // Assign relations here
            },
        });
        return request;
    }
}
```

Important for the creation of translatable entities is the input object. The input object should contain a `translations` array with the translations for the entity. This can be done
by defining the types like `CreateRequestInput` inside the GraphQL schema:

```graphql title="src/plugins/requests/api/types.ts"
input ProductRequestTranslationInput {
    # Only defined for update mutations
    id: ID
// highlight-start
    languageCode: LanguageCode!
    text: String!
// highlight-end
}

input CreateProductRequestInput {
    text: String!
// highlight-next-line
    translations: [ProductRequestTranslationInput!]!
}
```

## Updating translatable entities

Updating a translatable entity is done in a similar way as creating one. The [`TranslateableSaver`](/reference/typescript-api/service-helpers/translatable-saver/) provides an `update` method which can be used to update a translatable entity.

```ts title="src/plugins/requests/service/product-request.service.ts"
export class RequestService {

    constructor(private translatableSaver: TranslatableSaver) {}

    async update(ctx: RequestContext, input: UpdateProductRequestInput): Promise<ProductRequest> {
        const updatedEntity = await this.translatableSaver.update({
            ctx,
            input,
            entityType: ProductRequest,
            translationType: ProductRequestTranslation,
            beforeSave: async f => {
                // Assign relations here
            },
        });
        return updatedEntity;
    }
}
```

Once again it's important to provide the `translations` array in the input object. This array should contain the translations for the entity.

```graphql title="src/plugins/requests/api/types.ts"

input UpdateProductRequestInput {
    text: String
// highlight-next-line
    translations: [ProductRequestTranslationInput!]
}
```

## Loading translatable entities

If your plugin needs to load a translatable entity, you will need to use the [`TranslatorService`](/reference/typescript-api/service-helpers/translator-service/) to hydrate all the `LocaleString` fields will the actual translated values from the correct translation.

```ts title="src/plugins/requests/service/product-request.service.ts"
export class RequestService {

    constructor(private translator: TranslatorService) {}

    findAll(
        ctx: RequestContext,
        options?: ListQueryOptions<ProductRequest>,
        relations?: RelationPaths<ProductRequest>,
    ): Promise<PaginatedList<Translated<ProductRequest>>> {
        return this.listQueryBuilder
            .build(ProductRequest, options, {
                relations,
                ctx,
            })
            .getManyAndCount()
            .then(([items, totalItems]) => {
                return {
// highlight-next-line
                    items: items.map(item => this.translator.translate(item, ctx)),
                    totalItems,
                };
            });
    }
    
    findOne(
        ctx: RequestContext,
        id: ID,
        relations?: RelationPaths<ProductRequest>,
    ): Promise<Translated<ProductRequest> | null> {
        return this.connection
            .getRepository(ctx, ProductRequest)
            .findOne({
                where: { id },
                relations,
            })
// highlight-next-line
            .then(entity => entity && this.translator.translate(entity, ctx));
    }
}
```


---

---
title: "Translations"
showtoc: true
---

The following items in Vendure can be translated:

- Entities which implement the [`Translatable`](/reference/typescript-api/entities/interfaces/#translatable) interface.
- Admin UI text labels and messages
- Server error message

## Translatable entities

The following entities implement the `Translatable` interface:

- [Collection](/reference/typescript-api/entities/collection/)
- [Country](/reference/typescript-api/entities/country/)
- [Facet](/reference/typescript-api/entities/facet/)
- [FacetValue](/reference/typescript-api/entities/facet-value/)
- [PaymentMethod](/reference/typescript-api/entities/payment-method/)
- [Product](/reference/typescript-api/entities/product/)
- [ProductOption](/reference/typescript-api/entities/product-option/)
- [ProductOptionGroup](/reference/typescript-api/entities/product-option-group/)
- [ProductVariant](/reference/typescript-api/entities/product-variant/)
- [Promotion](/reference/typescript-api/entities/promotion/)
- [Province](/reference/typescript-api/entities/province/)
- [Region](/reference/typescript-api/entities/region/)
- [ShippingMethod](/reference/typescript-api/entities/shipping-method/)

To understand how translatable entities are implemented, let's take a look at a simplified version of the `Facet` entity:

```ts
@Entity()
export class Facet extends VendureEntity implements Translatable {
    
    // highlight-next-line
    name: LocaleString;

    @Column({ unique: true })
    code: string;

    // highlight-next-line
    @OneToMany(type => FacetTranslation, translation => translation.base, { eager: true })
    // highlight-next-line
    translations: Array<Translation<Facet>>;
}
```

All translatable entities have a `translations` field which is a relation to the translations. Any fields that are to be translated are of type `LocaleString`, and **do note have a `@Column()` decorator**. This is because the `name` field here does not in fact exist in the database in the `facet` table. Instead, it belongs to the `facet_translations` table, which brings us to the `FacetTranslation` entity (again simplified for clarity):

```ts
@Entity()
export class FacetTranslation extends VendureEntity implements Translation<Facet> {

    @Column('varchar') languageCode: LanguageCode;

    // highlight-next-line
    @Column() name: string;

    @Index()
    @ManyToOne(type => Facet, base => base.translations, { onDelete: 'CASCADE' })
    base: Facet;
}
```

Thus there is a one-to-many relation between `Facet` and `FacetTranslation`, which allows Vendure to handle multiple translations of the same entity. The `FacetTranslation` entity also implements the `Translation` interface, which requires the `languageCode` field and a reference to the base entity.

### Loading translatable entities

If your plugin needs to load a translatable entity, you will need to use the [`TranslatorService`](/reference/typescript-api/service-helpers/translator-service/) to hydrate all the `LocaleString` fields will the actual translated values from the correct translation.

For example, if you are loading a `Facet` entity, you would do the following:

```ts
import { Facet } from '@vendure/core';
import { LanguageCode, RequestContext, TranslatorService, TransactionalConnection } from '@vendure/core';

@Injectable()
export class MyService {
    
    constructor(private connection: TransactionalConnection, private translator: TranslatorService) {}

    async getFacet(ctx: RequestContext, id: ID): Promise<Facet | undefined> {
        const facet = await this.connection.getRepository(ctx, Facet).findOne(id);
        if (facet) {
            // highlight-next-line
            return this.translatorService.translate(facet, ctx);
        }
    }
    
    async getFacets(ctx: RequestContext): Promise<Facet[]> {
        // highlight-next-line
        const facets = await this.connection.getRepository(ctx, Facet).find();
        // highlight-next-line
        return Promise.all(facets.map(facet => this.translatorService.translate(facet, ctx)));
    }
}
```
## Admin UI translations

See the [Adding Admin UI Translations guide](/guides/extending-the-admin-ui/adding-ui-translations/).

## Server message translations

Let's say you've implemented some custom server-side functionality as part of a plugin. You may be returning custom errors or other messages. Here's how you can
provide these messages in multiple languages.

Using [`addTranslation`](/reference/typescript-api/common/i18n-service/#addtranslation) inside the `onApplicationBootstrap` ([Nestjs lifecycle hooks](https://docs.nestjs.com/fundamentals/lifecycle-events)) of a Plugin is the easiest way to add new translations.
While Vendure is only using `error`, `errorResult` and `message` resource keys you are free to use your own.

### Translatable Error
This example shows how to create a custom translatable error
```ts
/**
 * Custom error class
 */
class CustomError extends ErrorResult {
    readonly __typename = 'CustomError';
    readonly errorCode = 'CUSTOM_ERROR';
    readonly message = 'CUSTOM_ERROR'; //< looks up errorResult.CUSTOM_ERROR
}

@VendurePlugin({
    imports: [PluginCommonModule],
    providers: [I18nService],
    // ...
})
export class TranslationTestPlugin implements OnApplicationBootstrap {

    constructor(private i18nService: I18nService) {

    }

    onApplicationBootstrap(): any {
        this.i18nService.addTranslation('en', {
            errorResult: {
                CUSTOM_ERROR: 'A custom error message',
            },
            anything: {
                foo: 'bar'
            }
        });

        this.i18nService.addTranslation('de', {
            errorResult: {
                CUSTOM_ERROR: 'Eine eigene Fehlermeldung',
            },
            anything: {
                foo: 'bar'
            }
        });

    }
}
```

To receive an error in a specific language you need to use the `languageCode` query parameter
`query(QUERY_WITH_ERROR_RESULT, { variables }, { languageCode: LanguageCode.de });`

### Use translations

Vendure uses the internationalization-framework [i18next](https://www.i18next.com/).

Therefore you are free to use the i18next translate function to [access keys](https://www.i18next.com/translation-function/essentials#accessing-keys) \
`i18next.t('error.any-message');`


---

---
title: "Updating Vendure"
showtoc: true
---

# Updating Vendure

This guide provides guidance for updating the Vendure core framework to a newer version.

## How to update

First, check the [changelog](https://github.com/vendure-ecommerce/vendure/blob/master/CHANGELOG.md) for an overview of the changes and any breaking changes in the next version.

In your project's `package.json` file, find all the `@vendure/...` packages and change the version
to the latest. All the Vendure packages have the same version, and are all released together.

```diff
{
  // ...
  "dependencies": {
-    "@vendure/common": "1.1.5",
+    "@vendure/common": "1.2.0",
-    "@vendure/core": "1.1.5",
+    "@vendure/core": "1.2.0",
     // etc.
  }
}
```

Then run `npm install` or `yarn install` depending on which package manager you prefer.

## Admin UI changes

If you are using UI extensions to create your own custom Admin UI using the [`compileUiExtensions`](/reference/admin-ui-api/ui-devkit/compile-ui-extensions/) function, then you'll need to **delete and re-compile your admin-ui directory after upgrading** (this is the directory specified by the [`outputPath`](/reference/admin-ui-api/ui-devkit/ui-extension-compiler-options#outputpath) property).

If you also have an `.angular` directory in your project, you should delete this too after the update to ensure that any stale cached files are removed.


## Versioning Policy & Breaking changes

Vendure generally follows the [SemVer convention](https://semver.org/) for version numbering. This means that breaking API changes will only be introduced with changes to the major version (the first of the 3 digits in the version).

However, there are some exceptions to this rule:

- In minor versions, (e.g. v2.0 to v2.1) we may update underlying dependencies to new major versions, which may in turn introduce breaking changes. These will be clearly noted in the changelog.
- In minor versions we may also occasionally introduce non-destructive changes to the database schema. For instance, we may add a new column which would then require a database migration. We will _not_ introduce database schema changes that could potentially result in data loss in a minor version.

Any instances of these exceptions will be clearly indicated in the [Changelog](https://github.com/vendure-ecommerce/vendure/blob/master/CHANGELOG.md). The reasoning for these exceptions is discussed in the [Versioning policy RFC](https://github.com/vendure-ecommerce/vendure/issues/1846).

### What kinds of breaking changes can be expected?

Major version upgrades (e.g. v1.x to v2.x) can include:

* Changes to the database schema
* Changes to the GraphQL schema
* Updates of major underlying libraries, such as upgrading NestJS to a new major version

Every release will be accompanied by an entry in the [changelog](https://github.com/vendure-ecommerce/vendure/blob/master/CHANGELOG.md), listing the changes in that release. And breaking changes are clearly listed under a **BREAKING CHANGE** heading.

### Database migrations

Database changes are one of the most common causes for breaking changes. In most cases, the changes are minor (such as the addition of a new column) and non-destructive (i.e. performing the migration has no risk of data loss).

However, some more fundamental changes occasionally require a careful approach to database migration in order to preserve existing data.

The key rule is **never run your production instance with the `synchronize` option set to `true`**. Doing so can cause inadvertent data loss in rare cases.

For any database schema changes, it is advised to:

1. Read the changelog breaking changes entries to see what changes to expect
2. **Important:** Make a backup of your database!
3. Create a new database migration as described in the [Migrations guide](/guides/developer-guide/migrations/)
4. Manually check the migration script. In some cases manual action is needed to customize the script in order to correctly migrate your existing data.
5. Test the migration script against non-production data.
6. Only when you have verified that the migration works as expected, run it against your production database.

### GraphQL schema changes

If you are using a code-generation tool (such as [graphql-code-generator](https://graphql-code-generator.com/)) for your custom plugins or storefront, it is a good idea to re-generate after upgrading, which will catch any errors caused by changes to the GraphQL schema.

### TypeScript API changes

If you are using Vendure providers (services, JobQueue, EventBus etc.) in your custom plugins, you should look out for breakages caused by changes to those services. Major changes will be listed in the changelog, but occasionally internal changes may also impact your code. 

The best way to check whether this is the case is to build your entire project after upgrading, to see if any new TypeScript compiler errors emerge.



---

---
title: "Uploading Files"
showtoc: true
---

# Uploading Files 

Vendure handles file uploads with the [GraphQL multipart request specification](https://github.com/jaydenseric/graphql-multipart-request-spec). Internally, we use the [graphql-upload package](https://github.com/jaydenseric/graphql-upload). Once uploaded, a file is known as an [Asset](/guides/core-concepts/images-assets/). Assets are typically used for images, but can represent any kind of binary data such as PDF files or videos.

## Upload clients

Here is a [list of client implementations](https://github.com/jaydenseric/graphql-multipart-request-spec#client) that will allow you to upload files using the spec. If you are using Apollo Client, then you should install the [apollo-upload-client](https://github.com/jaydenseric/apollo-upload-client) npm package.

For testing, it is even possible to use a [plain curl request](https://github.com/jaydenseric/graphql-multipart-request-spec#single-file).

## The `createAssets` mutation

The [createAssets mutation](/reference/graphql-api/admin/mutations/#createassets) in the Admin API is the only means of uploading files by default. 

Here's an example of how a file upload would look using the `apollo-upload-client` package:

```tsx
import { gql, useMutation } from "@apollo/client";

const MUTATION = gql`
  mutation CreateAssets($input: [CreateAssetInput!]!) {
    createAssets(input: $input) {
      ... on Asset {
        id
        name
        fileSize
      }
      ... on ErrorResult {
        message
      }
    }
  }
`;

function UploadFile() {
    const [mutate] = useMutation(MUTATION);

    function onChange(event) {
        const {target} = event;
        if (target.validity.valid) {
            mutate({
                variables: {
                    input: Array.from(target.files).map((file) => ({file}));
                }
            });
        }
    }

    return <input type="file" required onChange={onChange}/>;
}
```

## Custom upload mutations

How about if you want to implement a custom mutation for file uploads? Let's take an example where we want to allow customers to set an avatar image. To do this, we'll add a [custom field](/guides/developer-guide/custom-fields/) to the Customer entity and then define a new mutation in the Shop API.

### Configuration

Let's define a custom field to associate the avatar `Asset` with the `Customer` entity. To keep everything encapsulated, we'll do all of this in a [plugin](/guides/developer-guide/plugins/)

```ts title="src/plugins/customer-avatar/customer-avatar.plugin.ts"
import { Asset, LanguageCode, PluginCommonModule, VendurePlugin } from '@vendure/core';

@VendurePlugin({
    imports: [PluginCommonModule],
    configure: config => {
        // highlight-start
        config.customFields.Customer.push({
            name: 'avatar',
            type: 'relation',
            label: [{languageCode: LanguageCode.en, value: 'Customer avatar'}],
            entity: Asset,
            nullable: true,
        });
        // highlight-end
        return config;
    },
})
export class CustomerAvatarPlugin {}
```

### Schema definition

Next, we will define the schema for the mutation:

```ts title="src/plugins/customer-avatar/api/api-extensions.ts"
import gql from 'graphql-tag';

export const shopApiExtensions = gql`
extend type Mutation {
  setCustomerAvatar(file: Upload!): Asset
}`
```

### Resolver

The resolver will make use of the built-in [AssetService](/reference/typescript-api/services/asset-service) to handle the processing of the uploaded file into an Asset.

```ts title="src/plugins/customer-avatar/api/customer-avatar.resolver.ts"
import { Args, Mutation, Resolver } from '@nestjs/graphql';
import { Asset } from '@vendure/common/lib/generated-types';
import {
    Allow, AssetService, Ctx, CustomerService, isGraphQlErrorResult,
    Permission, RequestContext, Transaction
} from '@vendure/core';

@Resolver()
export class CustomerAvatarResolver {
    constructor(private assetService: AssetService, private customerService: CustomerService) {}

    @Transaction()
    @Mutation()
    @Allow(Permission.Authenticated)
    async setCustomerAvatar(
        @Ctx() ctx: RequestContext,
        @Args() args: { file: any },
    ): Promise<Asset | undefined> {
        const userId = ctx.activeUserId;
        if (!userId) {
            return;
        }
        const customer = await this.customerService.findOneByUserId(ctx, userId);
        if (!customer) {
            return;
        }
        // Create an Asset from the uploaded file
        const asset = await this.assetService.create(ctx, {
            file: args.file,
            tags: ['avatar'],
        });
        // Check to make sure there was no error when
        // creating the Asset
        if (isGraphQlErrorResult(asset)) {
            // MimeTypeError
            throw asset;
        }
        // Asset created correctly, so assign it as the
        // avatar of the current Customer
        await this.customerService.update(ctx, {
            id: customer.id,
            customFields: {
                avatarId: asset.id,
            },
        });

        return asset;
    }
}
```

### Complete Customer Avatar Plugin

Let's put all these parts together into the plugin:

```ts
import { Asset, PluginCommonModule, VendurePlugin } from '@vendure/core';

import { shopApiExtensions } from './api/api-extensions';
import { CustomerAvatarResolver } from './api/customer-avatar.resolver';

@VendurePlugin({
    imports: [PluginCommonModule],
    shopApiExtensions: {
        schema: shopApiExtensions,
        resolvers: [CustomerAvatarResolver],
    },
    configuration: config => {
        config.customFields.Customer.push({
            name: 'avatar',
            type: 'relation',
            label: [{languageCode: LanguageCode.en, value: 'Customer avatar'}],
            entity: Asset,
            nullable: true,
        });
        return config;
    },
})
export class CustomerAvatarPlugin {
}
```

### Uploading a Customer Avatar

In our storefront, we would then upload a Customer's avatar like this:

```tsx
import { gql, useMutation } from "@apollo/client";

const MUTATION = gql`
  mutation SetCustomerAvatar($file: Upload!) {
    setCustomerAvatar(file: $file) {
      id
      name
      fileSize
    }
  }
`;

function UploadAvatar() {
  const [mutate] = useMutation(MUTATION);

  function onChange(event) {
    const { target } = event;  
    if (target.validity.valid && target.files.length === 1) {
      mutate({ 
        variables: {
          file: target.files[0],
        }  
      });
    }
  }

  return <input type="file" required onChange={onChange} />;
}
```


---

---
title: 'Worker & Job Queue'
sidebar_position: 5
---

The Vendure Worker is a Node.js process responsible for running computationally intensive
or otherwise long-running tasks in the background. For example, updating a
search index or sending emails. Running such tasks in the background allows
the server to stay responsive, since a response can be returned immediately
without waiting for the slower tasks to complete.

Put another way, the Worker executes **jobs** which have been placed in the **job queue**.

![Worker & Job Queue](./worker-job-queue.webp)

## The worker

The worker is started by calling the [`bootstrapWorker()`](/reference/typescript-api/worker/bootstrap-worker/) function with the same
configuration as is passed to the main server `bootstrap()`. In a standard Vendure installation, this is found
in the `index-worker.ts` file:

```ts title="src/index-worker.ts"
import { bootstrapWorker } from '@vendure/core';
import { config } from './vendure-config';

bootstrapWorker(config)
    .then(worker => worker.startJobQueue())
    .catch(err => {
        console.log(err);
    });
```

### Underlying architecture

The Worker is a NestJS standalone application. This means it is almost identical to the main server app,
but does not have any network layer listening for requests. The server communicates with the worker
via a “job queue” architecture. The exact implementation of the job queue is dependent on the
configured [`JobQueueStrategy`](/reference/typescript-api/job-queue/job-queue-strategy/), but by default
the worker polls the database for new jobs.

### Multiple workers

It is possible to run multiple workers in parallel to better handle heavy loads. Using the
[`JobQueueOptions.activeQueues`](/reference/typescript-api/job-queue/job-queue-options#activequeues) configuration, it is even possible to have particular workers dedicated
to one or more specific types of jobs. For example, if your application does video transcoding,
you might want to set up a dedicated worker just for that task:

```ts title="src/transcoder-worker.ts"
import { bootstrapWorker, mergeConfig } from '@vendure/core';
import { config } from './vendure-config';

const transcoderConfig = mergeConfig(config, {
    jobQueueOptions: {
      activeQueues: ['transcode-video'],
    }
});

bootstrapWorker(transcoderConfig)
  .then(worker => worker.startJobQueue())
  .catch(err => {
    console.log(err);
  });
```

### Running jobs on the main process

It is possible to run jobs from the Job Queue on the main server. This is mainly used for testing
and automated tasks, and is not advised for production use, since it negates the benefits of
running long tasks off of the main process. To do so, you need to manually start the JobQueueService:

```ts title="src/index.ts"
import { bootstrap, JobQueueService } from '@vendure/core';
import { config } from './vendure-config';

bootstrap(config)
    .then(app => app.get(JobQueueService).start())
    .catch(err => {
        console.log(err);
        process.exit(1);
    });
```

### ProcessContext

Sometimes your code may need to be aware of whether it is being run as part of a server or worker process.
In this case you can inject the [`ProcessContext`](/reference/typescript-api/common/process-context/) provider and query it like this:

```ts title="src/plugins/my-plugin/services/my.service.ts"
import { Injectable, OnApplicationBootstrap } from '@nestjs/common';
import { ProcessContext } from '@vendure/core';

@Injectable()
export class MyService implements OnApplicationBootstrap {
    constructor(private processContext: ProcessContext) {}

    onApplicationBootstrap() {
        if (this.processContext.isServer) {
            // code which will only execute when running in
            // the server process
        }
    }
}
```

## The job queue

Vendure uses a [job queue](https://en.wikipedia.org/wiki/Job_queue) to handle the processing of certain tasks which are typically too slow to run in the
normal request-response cycle. A normal request-response looks like this:

![Regular request response](./Vendure_docs-job-queue.webp)

In the normal request-response, all intermediate tasks (looking up data in the database, performing business logic etc.)
occur before the response can be returned. For most operations this is fine, since those intermediate tasks are very fast.

Some operations however will need to perform much longer-running tasks. For example, updating the search index on
thousands of products could take up to a minute or more. In this case, we certainly don’t want to delay the response
until that processing has completed. That’s where a job queue comes in:

![Request response with job queue](./Vendure_docs-job-queue-2.webp)

### What does Vendure use the job queue for?

By default, Vendure uses the job queue for the following tasks:

- Re-building the search index
- Updating the search index when changes are made to Products, ProductVariants, Assets etc.
- Updating the contents of Collections
- Sending transactional emails

### How does the Job Queue work?

This diagram illustrates the job queue mechanism:

![Job queue sequence](./Vendure_docs-job-queue-3.webp)

The server adds jobs to the queue. The worker then picks up these jobs from the queue and processes them in sequence,
one by one (it is possible to increase job queue throughput by running multiple workers or by increasing the concurrency
of a single worker).

### JobQueueStrategy

The actual queue part is defined by the configured [`JobQueueStrategy`](/reference/typescript-api/job-queue/job-queue-strategy/).

If no strategy is defined, Vendure uses an [in-memory store](/reference/typescript-api/job-queue/in-memory-job-queue-strategy/)
of the contents of each queue. While this has the advantage
of requiring no external dependencies, it is not suitable for production because when the server is stopped, the entire
queue will be lost and any pending jobs will never be processed. Moreover, it cannot be used when running the worker
as a separate process.

A better alternative is to use the [DefaultJobQueuePlugin](/reference/typescript-api/job-queue/default-job-queue-plugin/)
(which will be used in a standard `@vendure/create` installation), which configures Vendure to use the [SqlJobQueueStrategy](/reference/typescript-api/job-queue/sql-job-queue-strategy).
This strategy uses the database as a queue, and means that even if the Vendure server stops, pending jobs will be persisted and upon re-start, they will be processed.

It is also possible to implement your own JobQueueStrategy to take advantage of other technologies.
Examples include RabbitMQ, Google Cloud Pub Sub & Amazon SQS. It may make sense to implement a custom strategy based on
one of these if the default database-based approach does not meet your performance requirements.

### Job Queue Performance

It is common for larger Vendure projects to define multiple custom job queues, When using the [DefaultJobQueuePlugin](/reference/typescript-api/job-queue/default-job-queue-plugin/)
with many queues, performance may be impacted. This is because the `SqlJobQueueStrategy` uses polling to check for
new jobs in the database. Each queue will (by default) query the database every 200ms. So if there are 10 queues,
this will result in a constant 50 queries/second.

In this case it is recommended to try the [BullMQJobQueuePlugin](/reference/core-plugins/job-queue-plugin/bull-mqjob-queue-plugin/),
which uses an efficient push-based strategy built on Redis.

## Using Job Queues in a plugin

If your plugin involves long-running tasks, you can also make use of the job queue.

:::info
A real example of this can be seen in the [EmailPlugin source](https://github.com/vendure-ecommerce/vendure/blob/master/packages/email-plugin/src/plugin.ts)
:::

Let's say you are building a plugin which allows a video URL to be specified, and then that video gets transcoded into a format suitable for streaming on the storefront. This is a long-running task which should not block the main thread, so we will use the job queue to run the task on the worker.

First we'll add a new mutation to the Admin API schema:

```ts title="src/plugins/product-video/api/api-extensions.ts"
import gql from 'graphql-tag';

export const adminApiExtensions = gql`
  extend type Mutation {
    addVideoToProduct(productId: ID! videoUrl: String!): Job!
  }
`;
```

The resolver looks like this:


```ts title="src/plugins/product-video/api/product-video.resolver.ts"
import { Args, Mutation, Resolver } from '@nestjs/graphql';
import { Allow, Ctx, RequestContext, Permission, RequestContext } from '@vendure/core'
import { ProductVideoService } from '../services/product-video.service';

@Resolver()
export class ProductVideoResolver {

    constructor(private productVideoService: ProductVideoService) {}

    @Mutation()
    @Allow(Permission.UpdateProduct)
    addVideoToProduct(@Ctx() ctx: RequestContext, @Args() args: { productId: ID; videoUrl: string; }) {
        return this.productVideoService.transcodeForProduct(
            args.productId,
            args.videoUrl,
        );
    }
}
```
The resolver just defines how to handle the new `addVideoToProduct` mutation, delegating the actual work to the `ProductVideoService`.

### Creating a job queue

:::cli
Use `npx vendure add` to easily add a job queue to a service.
:::

The [`JobQueueService`](/reference/typescript-api/job-queue/job-queue-service/) creates and manages job queues. The queue is created when the
application starts up (see [NestJS lifecycle events](https://docs.nestjs.com/fundamentals/lifecycle-events)), and then we can use the `add()` method to add jobs to the queue.

```ts title="src/plugins/product-video/services/product-video.service.ts"
import { Injectable, OnModuleInit } from '@nestjs/common';
import { JobQueue, JobQueueService, ID, Product, TransactionalConnection } from '@vendure/core';
import { transcode } from 'third-party-video-sdk';

@Injectable()
class ProductVideoService implements OnModuleInit {

    private jobQueue: JobQueue<{ productId: ID; videoUrl: string; }>;

    constructor(private jobQueueService: JobQueueService,
                private connection: TransactionalConnection) {
    }

    async onModuleInit() {
        this.jobQueue = await this.jobQueueService.createQueue({
            name: 'transcode-video',
            process: async job => {
                // Inside the `process` function we define how each job
                // in the queue will be processed.
                // In this case we call out to some imaginary 3rd-party video
                // transcoding API, which performs the work and then
                // returns a new URL of the transcoded video, which we can then
                // associate with the Product via the customFields.
                const result = await transcode(job.data.videoUrl);
                await this.connection.getRepository(Product).save({
                    id: job.data.productId,
                    customFields: {
                        videoUrl: result.url,
                    },
                });
                // The value returned from the `process` function is stored as the "result"
                // field of the job (for those JobQueueStrategies that support recording of results).
                //
                // Any error thrown from this function will cause the job to fail.
                return result;
            },
        });
    }

    transcodeForProduct(productId: ID, videoUrl: string) {
        // Add a new job to the queue and immediately return the
        // job itself.
        return this.jobQueue.add({productId, videoUrl}, {retries: 2});
    }
}
```

Notice the generic type parameter of the `JobQueue`:

```ts
JobQueue<{ productId: ID; videoUrl: string; }>
```

This means that when we call `jobQueue.add()` we must pass in an object of this type. This data will then be available in the `process` function as the `job.data` property.

:::note
The data passed to `jobQueue.add()` must be JSON-serializable, because it gets serialized into a string when stored in the job queue. Therefore you should
avoid passing in complex objects such as `Date` instances, `Buffer`s, etc.
:::

The `ProductVideoService` is in charge of setting up the JobQueue and adding jobs to that queue. Calling

```ts
productVideoService.transcodeForProduct(id, url);
```

will add a transcoding job to the queue.

:::tip
Plugin code typically gets executed on both the server _and_ the worker. Therefore, you sometimes need to explicitly check
what context you are in. This can be done with the [ProcessContext](/reference/typescript-api/common/process-context/) provider.
:::

Finally, the `ProductVideoPlugin` brings it all together, extending the GraphQL API, defining the required CustomField to store the transcoded video URL, and registering our service and resolver. The [PluginCommonModule](/reference/typescript-api/plugin/plugin-common-module/) is imported as it exports the `JobQueueService`.

```ts title="src/plugins/product-video/product-video.plugin.ts"
import gql from 'graphql-tag';
import { PluginCommonModule, VendurePlugin } from '@vendure/core';
import { ProductVideoService } from './services/product-video.service';
import { ProductVideoResolver } from './api/product-video.resolver';
import { adminApiExtensions } from './api/api-extensions';

@VendurePlugin({
    imports: [PluginCommonModule],
    providers: [ProductVideoService],
    adminApiExtensions: {
        schema: adminApiExtensions,
        resolvers: [ProductVideoResolver]
    },
    configuration: config => {
        config.customFields.Product.push({
            name: 'videoUrl',
            type: 'string',
        });
        return config;
    }
})
export class ProductVideoPlugin {}
```

### Passing the RequestContext

Sometimes you need to pass the [RequestContext object](/reference/typescript-api/request/request-context) to the `process` function of a job, since `ctx` is required by many Vendure
service methods that you may be using inside your `process` function. However, the `RequestContext` object itself is not serializable,
so it cannot be passed directly to the `JobQueue.add()` method. Instead, you can serialize the `RequestContext` using the [`ctx.serialize()` method](/reference/typescript-api/request/request-context/#serialize),
 and then deserialize it in the `process` function using the static `deserialize` method.


```ts
import { Injectable, OnModuleInit } from '@nestjs/common';
import { JobQueue, JobQueueService, Product, TransactionalConnection,
    SerializedRequestContext, RequestContext } from '@vendure/core';

@Injectable()
class ProductExportService implements OnModuleInit {

    // highlight-next-line
    private jobQueue: JobQueue<{ ctx: SerializedRequestContext; }>;

    constructor(private jobQueueService: JobQueueService,
                private connection: TransactionalConnection) {
    }

    async onModuleInit() {
        this.jobQueue = await this.jobQueueService.createQueue({
            name: 'export-products',
            process: async job => {
                // highlight-next-line
                const ctx = RequestContext.deserialize(job.data.ctx);
                const allProducts = await this.connection.getRepository(ctx, Product).find();
                // ... logic to export the product omitted for brevity
            },
        });
    }

    exportAllProducts(ctx: RequestContext) {
        // highlight-next-line
        return this.jobQueue.add({ ctx: ctx.serialize() });
    }
}
```

:::warning
Serializing the RequestContext should be done with caution, since it is a relatively large object and will significantly increase the size of the job data.

In cases where the job is created in large quantities (hundreds or thousands of jobs per day), this can lead to performance issues. Especially
when using the [BullMQJobQueuePlugin](/reference/core-plugins/job-queue-plugin/bull-mqjob-queue-plugin/), which stores the job data in Redis, the
size of the job data can lead to too much memory usage which can cause the Redis server to crash.
:::

Instead of serializing the entire RequestContext, consider passing only the necessary data you need and then reconstructing the RequestContext in the `process` function:

```ts
import { Injectable, OnModuleInit } from '@nestjs/common';
import { JobQueue, JobQueueService,
    RequestContext, ID, LanguageCode, RequestContextService } from '@vendure/core';

@Injectable()
class ProductExportService implements OnModuleInit {

    // highlight-next-line
    private jobQueue: JobQueue<{ channelToken: string; languageCode: LanguageCode; }>;

    constructor(private jobQueueService: JobQueueService,
                private requestContextService: RequestContextService) {
    }

    async onModuleInit() {
        this.jobQueue = await this.jobQueueService.createQueue({
            name: 'export-products',
            process: async job => {
                // highlight-start
                // Reconstruct the RequestContext from the passed data
                const ctx = await this.requestContextService.create({
                    channelOrToken: job.data.channelToken,
                    languageCode: job.data.languageCode,
                })
                // highlight-end
                // ... logic to export the product omitted for brevity
            },
        });
    }

    exportAllProducts(ctx: RequestContext) {
        // highlight-start
        // Pass only the necessary data
        return this.jobQueue.add({
            channelId: ctx.channel.token,
            languageCode: ctx.languageCode
        });
        // highlight-end
    }
}
```

### Handling job cancellation

It is possible for an administrator to cancel a running job. Doing so will cause the configured job queue strategy to mark the job as cancelled, but
on its own this will not stop the job from running. This is because the job queue itself has no direct control over the `process` function once
it has been started.

It is up to the `process` function to check for cancellation and stop processing if the job has been cancelled. This can be done by checking the
`job.state` property, and if the job is cancelled, the `process` function can throw an error to indicate that the job was interrupted
by early cancellation:

```ts
import { Injectable, OnModuleInit } from '@nestjs/common';
import { JobQueue, JobQueueService, Product, TransactionalConnection,
    SerializedRequestContext, RequestContext } from '@vendure/core';
import { JobState } from '@vendure/common/lib/generated-types';
import { IsNull } from 'typeorm';

@Injectable()
class ProductExportService implements OnModuleInit {

    private jobQueue: JobQueue<{ ctx: SerializedRequestContext; }>;

    constructor(private jobQueueService: JobQueueService,
                private connection: TransactionalConnection) {
    }

    async onModuleInit() {
        this.jobQueue = await this.jobQueueService.createQueue({
            name: 'export-products',
            process: async job => {
                const ctx = RequestContext.deserialize(job.data.ctx);
                const allProducts = await this.connection.getRepository(ctx, Product).find({
                    where: { deletedAt: IsNull() }
                });
                let successfulExportCount = 0;
                for (const product of allProducts) {
                    // highlight-start
                    if (job.state === JobState.CANCELLED) {
                        // If the job has been cancelled, stop processing
                        // to prevent unnecessary work.
                        throw new Error('Job was cancelled');
                    }
                    // highlight-end

                    // ... logic to export the product omitted for brevity
                    successfulExportCount++;
                }
                return { successfulExportCount };
            },
        });
    }

    exportAllProducts(ctx: RequestContext) {
        return this.jobQueue.add({ ctx: ctx.serialize() });
    }
}
```


### Subscribing to job updates

When creating a new job via `JobQueue.add()`, it is possible to subscribe to updates to that Job (progress and status changes). This allows you, for example, to create resolvers which are able to return the results of a given Job.

In the video transcoding example above, we could modify the `transcodeForProduct()` call to look like this:

```ts title="src/plugins/product-video/services/product-video.service.ts"
import { Injectable, OnModuleInit } from '@nestjs/common';
import { of } from 'rxjs';
import { map, catchError } from 'rxjs/operators';
import { ID, Product, TransactionalConnection } from '@vendure/core';

@Injectable()
class ProductVideoService implements OnModuleInit {
    // ... omitted (see above)

    transcodeForProduct(productId: ID, videoUrl: string) {
        const job = await this.jobQueue.add({productId, videoUrl}, {retries: 2});

        return job.updates().pipe(
            map(update => {
                // The returned Observable will emit a value for every update to the job
                // such as when the `progress` or `status` value changes.
                Logger.info(`Job ${update.id}: progress: ${update.progress}`);
                if (update.state === JobState.COMPLETED) {
                    Logger.info(`COMPLETED ${update.id}: ${update.result}`);
                }
                return update.result;
            }),
            catchError(err => of(err.message)),
        );
    }
}
```

If you prefer to work with Promises rather than Rxjs Observables, you can also convert the updates to a promise:

```ts
const job = await this.jobQueue.add({ productId, videoUrl }, { retries: 2 });

return job.updates().toPromise()
  .then(/* ... */)
  .catch(/* ... */);
```


---

---
title: 'Page ActionBar Buttons'
weight: 5
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

The `ActionBar` is the horizontal area at the top of each list or detail page, which contains the main buttons for that page.
This guide explains how to add new buttons and dropdown menu items to the ActionBar.

For example, consider an "order invoice" extension that allows you to print invoices for orders. You can add a "print invoice" 
button to the ActionBar of the order detail page, either as a button or as a dropdown menu item.

## ActionBar button example

Adding a button is done using the [`addActionBarItem`](/reference/admin-ui-api/action-bar/add-action-bar-item/) function.

```ts title="src/plugins/invoice/ui/providers.ts"
import { addActionBarItem } from '@vendure/admin-ui/core';

export default [
    addActionBarItem({
        id: 'print-invoice',
        locationId: 'order-detail',
        label: 'Print invoice',
        icon: 'printer',
        routerLink: route => {
            const id = route.snapshot.params.id;
            return ['./extensions/order-invoices', id];
        },
        requiresPermission: 'ReadOrder',
    }),
];
```

![./ui-extensions-actionbar.webp](./ui-extensions-actionbar.webp)

In each list or detail view in the app, the ActionBar has a unique `locationId` which is how the app knows in which view to place your button.
The complete list of available locations into which you can add new ActionBar can be found in the [PageLocationId docs](/reference/admin-ui-api/action-bar/page-location-id/).
You can also press `ctrl + u` when in development mode to see the location of all UI extension points.

## ActionBar dropdown menu example

Vendure v2.2.0 introduced the ability to add dropdown menu items to the ActionBar. If you want to add an action which is
less commonly used, or want to take up less space in the action bar, then a dropdown menu item is a good choice.
This is done using the [`addActionBarDropdownMenuItem`](/reference/admin-ui-api/action-bar/add-action-bar-dropdown-menu-item/) function.

Let's re-work the "print invoice" button example to display it instead as a dropdown menu item:

```ts title="src/plugins/invoice/ui/providers.ts"
import { addActionBarDropdownMenuItem } from '@vendure/admin-ui/core';

export default [
    addActionBarDropdownMenuItem({
        id: 'print-invoice',
        locationId: 'order-detail',
        label: 'Print invoice',
        icon: 'printer',
        routerLink: route => {
            const id = route.snapshot.params.id;
            return ['./extensions/order-invoices', id];
        },
        requiresPermission: 'ReadOrder',
        // When set to `true`, a horizontal divider will be
        // displayed above this item in the dropdown menu.
        hasDivider: true,
    }),
];
```

![./ui-extensions-actionbar-dropdown.webp](./ui-extensions-actionbar-dropdown.webp)

## Handling button clicks

There are two ways to handle the click event of an ActionBar button or dropdown menu item:

1. Use the `routerLink` property to navigate to a new route when the button is clicked.
2. Use the `onClick` property to execute a function when the button is clicked.

### Using routerLink

The `routerLink` property allows you to specify a route to navigate to when the button is clicked. The route can be a constant value, or it can be a function which receives the current route as well as a [`context` object](/reference/admin-ui-api/action-bar/action-bar-context) as arguments.

<Tabs>
<TabItem value="routerLink constant" label="routerLink constant" default>

```ts title="src/plugins/invoice/ui/providers.ts"
import { addActionBarItem } from '@vendure/admin-ui/core';

export default [
    addActionBarItem({
        id: 'print-invoice',
        label: 'Print invoice',
        locationId: 'order-detail',
        // highlight-start
        // The route can be a constant value...
        routerLink: ['./extensions/order-invoices'],
        // highlight-end
    }),
];
```

</TabItem>
<TabItem value="routerLink function" label="routerLink function">

```ts title="src/plugins/invoice/ui/providers.ts"
import { addActionBarItem } from '@vendure/admin-ui/core';

export default [
    addActionBarItem({
        id: 'print-invoice',
        label: 'Print invoice',
        locationId: 'order-detail',
        // highlight-start
        // The route can be a function
        routerLink: route => {
            const id = route.snapshot.params.id;
            return ['./extensions/order-invoices', id];
        },
        // highlight-end
    }),
];
```

</TabItem>
</Tabs>

### Using onClick

The onClick property of the addActionBarItem function allows you to define a function that will be executed when the ActionBar button is clicked. This function receives two arguments: the click event and the current context.

The context object provides access to commonly-used services, which allows you to perform GraphQL queries and mutations, and the current route, which can be used to get parameters from the URL.

Here's an example of how to use the onClick property to perform a GraphQL mutation when the ActionBar button is clicked:

```ts title="src/plugins/invoice/ui/providers.ts"
import gql from 'graphql-tag';
import { firstValueFrom } from 'rxjs';
import { addActionBarItem } from '@vendure/admin-ui/core';

const mutation = gql`
    mutation MyMutation($orderId: ID!) {
        myMutation(orderId: $orderId)
    }
`;

export default [
    addActionBarItem({
        id: 'myButtonId',
        label: 'My Button Label',
        locationId: 'order-detail',
        // highlight-start
        onClick: async (event, context) => {
            try {
                const orderId = context.route.snapshot.params.id;
                await firstValueFrom(context.dataService.mutate(mutation, { orderId }));
            } catch (error) {
                context.notificationService.error('Error executing mutation: ' + error.message);
            }
        },
        // highlight-end
    }),
];
```

In this example, clicking the ActionBar button triggers a GraphQL mutation. The `context.dataService` is utilized to execute the mutation. It can also be employed to retrieve additional information about the current order if needed. The `context.route` is used to extract the ID of the current order from the URL.

The utility function `firstValueFrom` from the RxJS library is used in this example to convert the Observable returned by `context.dataService.mutate(...)` into a Promise. This conversion allows the use of the `await` keyword to pause execution until the Observable emits its first value or completes.

## Setting visibility & disabled state

Use the `buttonState` property (added in v2.1) to control the visibility and disabled state of the button. This property is a function which receives the current context as an argument and returns an Observable of the button state:

```ts title="src/plugins/invoice/ui/providers.ts"
import { map, switchMap } from 'rxjs/operators';
import { addActionBarItem } from '@vendure/admin-ui/core';

export default [
    addActionBarItem({
        id: 'print-invoice',
        label: 'Print invoice',
        locationId: 'order-detail',
        buttonState: context => {
            // For any of the detail pages, we can get an observable stream
            // of the entity via `context.entity$`:
            return context.entity$.pipe(
                map(order => ({
                    disabled: order?.state === 'AddingItems',
                    visible: true,
                })),
            );
        },
    }),
];
```

:::note
The `context.entity$` property was introduced in Vendure v2.2. If you are using v2.1, you can achieve equivalent functionality
with this code:

```ts
buttonState: context => {
    return context.route.data.pipe(
        switchMap(data => data.detail.entity),
        map((order: any) => ({
            disabled: order.state === 'AddingItems',
            visible: true,
        })),
    );
}
```

:::

## Restricting access by permissions

You can use the `requiresPermission` property to restrict access to the button by permission. This property accepts a single permission string or an array of permission strings. If the current user does not have the required permission, the button will not be visible.

```ts title="src/plugins/invoice/ui/providers.ts"
import { addActionBarItem } from '@vendure/admin-ui/core';

export default [
    addActionBarItem({
        id: 'print-invoice',
        label: 'Print invoice',
        locationId: 'order-detail',
        routerLink: ['./extensions/order-invoices'],
        // highlight-next-line
        requiresPermission: 'CreateInvoice',
    }),
];
```


---

---
title: 'Adding UI Translations'
---

The Vendure Admin UI is fully localizable, allowing you to:

* create custom translations for your UI extensions
* override existing translations
* add complete translations for whole new languages

![The UI language is set from the User menu](./ui-translations-01.webp)

## Translation format

The Admin UI uses the [Messageformat](https://messageformat.github.io/messageformat/) specification to convert i18n tokens to localized strings in the browser. Each language should have a corresponding JSON file containing the translations for that language.

Here is an excerpt from the `en.json` file that ships with the Admin UI:

```JSON title="en.json"
{
  "admin": {
    "create-new-administrator": "Create new administrator"
  },
  "asset": {
    "add-asset": "Add asset",
    "add-asset-with-count": "Add {count, plural, 0 {assets} one {1 asset} other {{count} assets}}",
    "assets-selected-count": "{ count } assets selected",
    "dimensions": "Dimensions"
  }
}
```

The translation tokens are grouped into a single-level deep nested structure. In the Angular code, these are referenced like this: 

```HTML
<label>{{ 'asset.assets-selected-count' | translate:{ count } }}</label>
```

That is, the `{ ... }` represent variables that are passed from the application code and interpolated into the final localized string.

## Adding a new language

The Admin UI ships with built-in support for many languages, but allows you to add support for any other language without the need to modify the package internals.

1. **Create your translation file**

     Start by copying the contents of the [English language file](https://github.com/vendure-ecommerce/vendure/blob/master/packages/admin-ui/src/lib/static/i18n-messages/en.json) into a new file, `<languageCode>.json`, where `languageCode` is the 2-character [ISO 639-1 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) for the language. Replace the strings with the translation for the new language.
2. **Install `@vendure/ui-devkit`**

    If not already installed, install the `@vendure/ui-devkit` package, which allows you to create custom builds of the Admin UI.
3. **Register the translation file**
  
    Here's a minimal directory structure and sample code to add your new translation:
    
    ```text
    /src
    ├─ vendure-config.ts
    └─ translations/
        └─ ms.json
    ```
    
    And the config code to register the translation file:
    
    ```ts title="src.vendure-config.ts"
    import path from 'path';
    import { VendureConfig } from '@vendure/core';
    import { AdminUiPlugin } from '@vendure/admin-ui-plugin';
    import { compileUiExtensions } from '@vendure/ui-devkit/compiler';
    
    export const config: VendureConfig = {
        // ...
        plugins: [
            AdminUiPlugin.init({
                port: 3002,
                app: compileUiExtensions({
                    outputPath: path.join(__dirname, '../admin-ui'),
                    extensions: [{
                        translations: {
                            ms: path.join(__dirname, 'translations/ms.json'),
                        }
                    }],
                }),
                adminUiConfig:{
                    defaultLanguage: LanguageCode.ms,
                    availableLanguages: [LanguageCode.ms, LanguageCode.en],
                }
            }),
        ],
    };
    ```

## Translating UI Extensions

You can also create translations for your own UI extensions, in much the same way as outlined above in "Adding a new language". Your translations can be split over several files, since the `translations` config object can take a glob, e.g.:

```ts
translations: {
  de: path.join(__dirname, 'ui-extensions/my-extension/**/*.de.json'),
}
```

This allows you, if you wish, to co-locate your translation files with your components.

Care should be taken to uniquely namespace your translation tokens, as conflicts with the base translation file will cause your translations to overwrite the defaults. This can be solved by using a unique section name, e.g.:

```JSON
{
  "my-reviews-plugin": {
    "all-reviews": "All reviews",
    "approve review": "Approve review"
  }
}
```


---

---
title: 'Admin UI Theming & Branding'
---

The Vendure Admin UI can be themed to your company's style and branding.
    
## AdminUiPlugin branding settings

The `AdminUiPlugin` allows you to specify your "brand" name, and allows you to control whether to display the Vendure name and version in the UI. Specifying a brand name will also set it as the title of the Admin UI in the browser.

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';
import { AdminUiPlugin } from '@vendure/admin-ui-plugin';

export const config: VendureConfig = {
    // ...
    plugins: [
        AdminUiPlugin.init({
            // ...
            adminUiConfig:{
                brand: 'My Store',
                hideVendureBranding: false,
                hideVersion: false,
            }
        }),
    ],
};
```

:::note
For the simple level of branding shown above, the `@vendure/ui-devkit` package is not required.
:::

## Specifying custom logos

You can replace the Vendure logos and favicon with your own brand logo:

1. Install `@vendure/ui-devkit`
2. Configure the AdminUiPlugin to compile a custom build featuring your logos:
    ```ts title="src/vendure-config.ts"
    import path from 'path';
    import { AdminUiPlugin } from '@vendure/admin-ui-plugin';
    import { VendureConfig } from '@vendure/core';
    import { compileUiExtensions, setBranding } from '@vendure/ui-devkit/compiler';
    
    export const config: VendureConfig = {
        // ...
        plugins: [
            AdminUiPlugin.init({
                app: compileUiExtensions({
                    outputPath: path.join(__dirname, '../admin-ui'),
                    extensions: [
                        setBranding({
                            // The small logo appears in the top left of the screen  
                            smallLogoPath: path.join(__dirname, 'images/my-logo-sm.png'),
                            // The large logo is used on the login page  
                            largeLogoPath: path.join(__dirname, 'images/my-logo-lg.png'),
                            faviconPath: path.join(__dirname, 'images/my-favicon.ico'),
                        }),
                    ],
                }),
            }),
        ],
    }
    ```

## Theming

Much of the visual styling of the Admin UI can be customized by providing your own themes in a Sass stylesheet. For the most part, the Admin UI uses [CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*) to control colors and other styles. Here's a simple example which changes the color of links:

1. Install `@vendure/ui-devkit`
2. Create a custom stylesheet which overrides one or more of the CSS custom properties used in the Admin UI:
    ```css title="my-theme.scss"
    :root {
      --clr-link-active-color: hsl(110, 65%, 57%);
      --clr-link-color: hsl(110, 65%, 57%);
      --clr-link-hover-color: hsl(110, 65%, 57%);
      --clr-link-visited-color: hsl(110, 55%, 75%);
    }
    ```
   To get an idea of which custom properties are available for theming, take a look at the source of the [Default theme](https://github.com/vendure-ecommerce/vendure/tree/master/packages/admin-ui/src/lib/static/styles/theme/default.scss) and the [Dark theme](https://github.com/vendure-ecommerce/vendure/tree/master/packages/admin-ui/src/lib/static/styles/theme/dark.scss)
3. Set this as a globalStyles extension:   
    ```ts title="src/vendure-config.ts"
    import path from 'path';
    import { AdminUiPlugin } from '@vendure/admin-ui-plugin';
    import { VendureConfig } from '@vendure/core';
    import { compileUiExtensions } from '@vendure/ui-devkit/compiler';
    
    export const config: VendureConfig = {
        // ...
        plugins: [
            AdminUiPlugin.init({
                app: compileUiExtensions({
                    outputPath: path.join(__dirname, '../admin-ui'),
                    extensions: [{
                        globalStyles: path.join(__dirname, 'my-theme.scss')
                    }],
                }),
            }),
        ],
    }
    ```

Some customizable styles in [Clarity](https://clarity.design/), the Admin UI's underlying UI framework, are controlled by Sass variables, which can be found on the [project's GitHub page](https://github.com/vmware-clarity/ng-clarity/blob/689a572344149aea90df1676eae04479795754f3/projects/angular/src/utils/_variables.clarity.scss). Similar to above, you can also provide your own values, which will override defaults set by the framework. Here's an example which changes the [height of the main header](https://github.com/vmware-clarity/ng-clarity/blob/689a572344149aea90df1676eae04479795754f3/projects/angular/src/layout/main-container/_variables.header.scss#L10):

1. Install `@vendure/ui-devkit` if not already installed
2. Create a custom stylesheet which overrides the target variable(s):
    ```css title="my-variables.scss"
    $clr-header-height: 4rem;
    ```
3. Set this as a `sassVariableOverrides` extension:
    ```ts title="src/vendure-config.ts"
    import path from 'path';
    import { AdminUiPlugin } from '@vendure/admin-ui-plugin';
    import { VendureConfig } from '@vendure/core';
    import { compileUiExtensions } from '@vendure/ui-devkit/compiler';

    export const config: VendureConfig = {
        // ...
        plugins: [
            AdminUiPlugin.init({
                app: compileUiExtensions({
                    outputPath: path.join(__dirname, 'admin-ui'),
                    extensions: [{
                        sassVariableOverrides: path.join(__dirname, 'my-variables.scss')
                    }],
                }),
            }),
        ],
    }
    ```

`globalStyles` and `sassVariableOverrides` extensions can be used in conjunction or separately.


---

---
title: 'Alerts'
---

Alerts appear in the top bar of the Admin UI and provide a way of notifying the administrator of important information
that may require action.

You can define custom alerts with the [`registerAlert` function](/reference/admin-ui-api/alerts/register-alert/).

Let's say you have a custom order process where certain orders require manual review & approval. You could define an
alert to notify the administrator when there are orders that require review:

```ts title="src/plugins/manual-order-review/ui/providers.ts"
import { registerAlert } from '@vendure/admin-ui/core';
import { Router } from '@angular/router';
import { interval } from 'rxjs';

import { ManualOrderReviewService } from './providers/manual-order-review.service';

export default [
    ManualOrderReviewService,
    registerAlert({
        id: 'orders-require-approval',
        // This function is responsible for fetching the data needed to determine
        // whether the alert should be displayed.
        check: ({ injector }) => {
            const manualOrderReviewService = injector.get(ManualOrderReviewService);
            return manualOrderReviewService.getOrdersRequiringApproval()
                .then(orders => orders.length);
        },
        // This function is responsible for determining whether and how often the
        // `check` function should be called. In this case, we will check every 60 seconds.
        recheck: () => interval(60_000),
        // This function gets passed the data returned by the `check` function and
        // should return `true` if the alert should be displayed.
        isAlert: orderCount => orderCount > 0,
        // This function is called when the alert is clicked. Here, we will navigate to
        // a new route to display the orders requiring approval.
        action: (orderCount, { injector }) => {
            injector.get(Router).navigate(['/extensions/manual-order-review']);
        },
        // This function is called to determine the label of the alert.
        label: (orderCount) => ({
            text: `${orderCount} ${orderCount === 1 ? 'order' : 'orders'} require approval`,
        }),
    }),
];
```

With this example, a check will be performed every 60 seconds to see if there are any orders requiring approval. The actual
implementation of the check is left to the `ManualOrderReviewService` which in this case would make a request to the 
Vendure server to fetch the required data.

If there are orders requiring approval, the alert will appear in the Admin UI like this:

![Alerts](./alerts-01.webp)


---

---
title: 'Bulk Actions for List Views'
---

List views in the Admin UI support bulk actions, which are performed on any selected items in the list. There are a default set of bulk actions that are defined by the Admin UI itself (e.g. delete, assign to channels), but using the `@vendure/ui-devit` package you are also able to define your own bulk actions.

![./bulk-actions-screenshot.webp](./bulk-actions-screenshot.webp)

Use cases for bulk actions include things like:

- Sending multiple products to a 3rd-party localization service
- Exporting selected products to csv
- Bulk-updating custom field data

### Bulk Action Example

Bulk actions are declared using the [`registerBulkAction` function](/reference/admin-ui-api/bulk-actions/register-bulk-action/)

```ts title="src/plugins/translation/ui/providers.ts"
import { ModalService, registerBulkAction } from '@vendure/admin-ui/core';
import { ProductDataTranslationService } from './product-data-translation.service';

export default [
    ProductDataTranslationService,
    // Here is where we define our bulk action
    // for sending the selected products to a 3rd-party
    // translation API
    registerBulkAction({
        // This tells the Admin UI that this bulk action should be made
        // available on the product list view.
        location: 'product-list',
        label: 'Send to translation service',
        icon: 'language',
        // Here is the logic that is executed when the bulk action menu item
        // is clicked.
        onClick: ({injector, selection}) => {
            const modalService = injector.get(ModalService);
            const translationService = injector.get(ProductDataTranslationService);
            modalService
                .dialog({
                    title: `Send ${selection.length} products for translation?`,
                    buttons: [
                        {type: 'secondary', label: 'cancel'},
                        {type: 'primary', label: 'send', returnValue: true},
                    ],
                })
                .subscribe(response => {
                    if (response) {
                        translationService.sendForTranslation(selection.map(item => item.productId));
                    }
                });
        },
    }),
];
```

### Conditionally displaying bulk actions

Sometimes a bulk action only makes sense in certain circumstances. For example, the "assign to channel" action only makes sense when your server has multiple channels set up.

We can conditionally control the display of a bulk action with the `isVisible` function, which should return a Promise resolving to a boolean:

```ts title="src/plugins/my-plugin/ui/providers.ts"
import { registerBulkAction, DataService } from '@vendure/admin-ui/core';

export default [
    registerBulkAction({
        location: 'product-list',
        label: 'Assign to channel',
        // Only display this action if there are multiple channels
        isVisible: ({ injector }) => injector.get(DataService).client
            .userStatus()
            .mapSingle(({ userStatus }) => 1 < userStatus.channels.length)
            .toPromise(),
        // ...
    }),
];
```


---

---
title: 'Creating Detail Views'
---

# Creating Detail Views

The two most common type of components you'll be creating in your UI extensions are list components and detail components.

In Vendure, we have standardized the way you write these components so that your ui extensions can be made to fit seamlessly into the rest of the app.

:::note
The specific pattern described here is for Angular-based components. It is also possible to create detail views using React components, but 
in that case you won't be able to use the built-in Angular-specific components.
:::

## Example: Creating a Product Detail View

Let's say you have a plugin which adds a new entity to the database called `ProductReview`. You have already created a [list view](/guides/extending-the-admin-ui/creating-list-views/), and
now you need a detail view which can be used to view and edit individual reviews.

### Extend the TypedBaseDetailComponent class

The detail component itself is an Angular component which extends the [BaseDetailComponent](/reference/admin-ui-api/list-detail-views/base-detail-component/) or [TypedBaseDetailComponent](/reference/admin-ui-api/list-detail-views/typed-base-detail-component) class.

This example assumes you have set up your project to use code generation as described in the [GraphQL code generation guide](/guides/how-to/codegen/#codegen-for-admin-ui-extensions).

```ts title="src/plugins/reviews/ui/components/review-detail/review-detail.component.ts"
import { ResultOf } from '@graphql-typed-document-node/core';
import { ChangeDetectionStrategy, Component, OnInit, OnDestroy } from '@angular/core';
import { FormBuilder } from '@angular/forms';
import { TypedBaseDetailComponent, LanguageCode, NotificationService, SharedModule } from '@vendure/admin-ui/core';

// This is the TypedDocumentNode & type generated by GraphQL Code Generator
import { graphql } from '../../gql';

export const reviewDetailFragment = graphql(`
  fragment ReviewDetail on ProductReview {
    id
    createdAt
    updatedAt
    title
    rating
    text
    authorName
    productId
  }
`);

export const getReviewDetailDocument = graphql(`
  query GetReviewDetail($id: ID!) {
    review(id: $id) {
      ...ReviewDetail
    }
  }
`);

export const createReviewDocument = graphql(`
  mutation CreateReview($input: CreateProductReviewInput!) {
    createProductReview(input: $input) {
      ...ReviewDetail
    }
  }
`);

export const updateReviewDocument = graphql(`
  mutation UpdateReview($input: UpdateProductReviewInput!) {
    updateProductReview(input: $input) {
      ...ReviewDetail
    }
  }
`);

@Component({
    selector: 'review-detail',
    templateUrl: './review-detail.component.html',
    styleUrls: ['./review-detail.component.scss'],
    changeDetection: ChangeDetectionStrategy.OnPush,
    standalone: true,
    imports: [SharedModule],
})
export class ReviewDetailComponent extends TypedBaseDetailComponent<typeof getReviewDetailDocument, 'review'> implements OnInit, OnDestroy {
    detailForm = this.formBuilder.group({
        title: [''],
        rating: [1],
        authorName: [''],
    });

    constructor(private formBuilder: FormBuilder, private notificationService: NotificationService) {
        super();
    }

    ngOnInit() {
        this.init();
    }

    ngOnDestroy() {
        this.destroy();
    }

    create() {
        const { title, rating, authorName } = this.detailForm.value;
        if (!title || rating == null || !authorName) {
            return;
        }
        this.dataService
            .mutate(createReviewDocument, {
                input: { title, rating, authorName },
            })
            .subscribe(({ createProductReview }) => {
                if (createProductReview.id) {
                    this.notificationService.success('Review created');
                    this.router.navigate(['extensions', 'reviews', createProductReview.id]);
                }
            });
    }

    update() {
        const { title, rating, authorName } = this.detailForm.value;
        this.dataService
            .mutate(updateReviewDocument, {
                input: { id: this.id, title, rating, authorName },
            })
            .subscribe(() => {
                this.notificationService.success('Review updated');
            });
    }

    protected setFormValues(entity: NonNullable<ResultOf<typeof getReviewDetailDocument>['review']>, languageCode: LanguageCode): void {
        this.detailForm.patchValue({
            title: entity.name,
            rating: entity.rating,
            authorName: entity.authorName,
            productId: entity.productId,
        });
    }
}
```

### Create the template

Here is the standard layout for detail views:

```html
<vdr-page-block>
    <vdr-action-bar>
        <vdr-ab-left></vdr-ab-left>
        <vdr-ab-right>
            <button
                class="button primary"
                *ngIf="isNew$ | async; else updateButton"
                (click)="create()"
                [disabled]="detailForm.pristine || detailForm.invalid"
            >
                {{ 'common.create' | translate }}
            </button>
            <ng-template #updateButton>
                <button
                    class="btn btn-primary"
                    (click)="update()"
                    [disabled]="detailForm.pristine || detailForm.invalid"
                >
                    {{ 'common.update' | translate }}
                </button>
            </ng-template>
        </vdr-ab-right>
    </vdr-action-bar>
</vdr-page-block>

<form class="form" [formGroup]="detailForm">
    <vdr-page-detail-layout>
        <!-- The sidebar is used for displaying "metadata" type information about the entity -->
        <vdr-page-detail-sidebar>
            <vdr-card *ngIf="entity$ | async as entity">
                <vdr-page-entity-info [entity]="entity" />
            </vdr-card>
        </vdr-page-detail-sidebar>

        <!-- The main content area is used for displaying the entity's fields -->
        <vdr-page-block>
            <!-- The vdr-card is the container for grouping items together on a page -->
            <!-- it can also take an optional [title] property to display a title -->
            <vdr-card>
                <!-- the form-grid class is used to lay out the form fields -->
                <div class="form-grid">
                    <vdr-form-field label="Title" for="title">
                        <input id="title" type="text" formControlName="title" />
                    </vdr-form-field>
                    <vdr-form-field label="Rating" for="rating">
                        <input id="rating" type="number" min="1" max="5" formControlName="rating" />
                    </vdr-form-field>

                    <!-- etc -->
                </div>
            </vdr-card>
        </vdr-page-block>
    </vdr-page-detail-layout>
</form>
```

### Route config

Here's how the routing would look for a typical list & detail view:

```ts title="src/plugins/reviews/ui/routes.ts"
import { registerRouteComponent } from '@vendure/admin-ui/core';

import { ReviewDetailComponent, getReviewDetailDocument } from './components/review-detail/review-detail.component';
import { ReviewListComponent } from './components/review-list/review-list.component';

export default [
    // List view
    registerRouteComponent({
        path: '',
        component: ReviewListComponent,
        breadcrumb: 'Product reviews',
    }),
    // highlight-start
    // Detail view
    registerRouteComponent({
        path: ':id',
        component: ReviewDetailComponent,
        query: getReviewDetailDocument,
        entityKey: 'productReview',
        getBreadcrumbs: entity => [
            {
                label: 'Product reviews',
                link: ['/extensions', 'product-reviews'],
            },
            {
                label: `#${entity?.id} (${entity?.product.name})`,
                link: [],
            },
        ],
    }),
    // highlight-end
]
```

## Supporting custom fields

From Vendure v2.2, it is possible for your [custom entities to support custom fields](/guides/developer-guide/database-entity/#supporting-custom-fields).

If you have set up your entity to support custom fields, and you want custom fields to be available in the Admin UI detail view,
you need to add the following to your detail component:

```ts title="src/plugins/reviews/ui/components/review-detail/review-detail.component.ts"
// highlight-next-line
import { getCustomFieldsDefaults } from '@vendure/admin-ui/core';

@Component({
    selector: 'review-detail',
    templateUrl: './review-detail.component.html',
    styleUrls: ['./review-detail.component.scss'],
    changeDetection: ChangeDetectionStrategy.OnPush,
    standalone: true,
    imports: [SharedModule],
})
export class ReviewDetailComponent extends TypedBaseDetailComponent<typeof getReviewDetailDocument, 'review'> implements OnInit, OnDestroy {

    // highlight-next-line
    customFields = this.getCustomFieldConfig('ProductReview');

    detailForm = this.formBuilder.group({
        title: [''],
        rating: [1],
        authorName: [''],
        // highlight-next-line
        customFields: this.formBuilder.group(getCustomFieldsDefaults(this.customFields)),
    });

    protected setFormValues(entity: NonNullable<ResultOf<typeof getReviewDetailDocument>['review']>, languageCode: LanguageCode): void {
        this.detailForm.patchValue({
            title: entity.name,
            rating: entity.rating,
            authorName: entity.authorName,
            productId: entity.productId,
        });
        // highlight-start
        if (this.customFields.length) {
            this.setCustomFieldFormValues(this.customFields, this.detailForm.get('customFields'), entity);
        }
        // highlight-end
    }
}
```

Then add a card for your custom fields to the template:

```html title="src/plugins/reviews/ui/components/review-detail/review-detail.component.html"
<form class="form" [formGroup]="detailForm">
    <vdr-page-detail-layout>
        <!-- The sidebar is used for displaying "metadata" type information about the entity -->
        <vdr-page-detail-sidebar>
            <vdr-card *ngIf="entity$ | async as entity">
                <vdr-page-entity-info [entity]="entity" />
            </vdr-card>
        </vdr-page-detail-sidebar>

        <!-- The main content area is used for displaying the entity's fields -->
        <vdr-page-block>
            <!-- The vdr-card is the container for grouping items together on a page -->
            <!-- it can also take an optional [title] property to display a title -->
            <vdr-card>
                <!-- the form-grid class is used to lay out the form fields -->
                <div class="form-grid">
                    <vdr-form-field label="Title" for="title">
                        <input id="title" type="text" formControlName="title" />
                    </vdr-form-field>
                    <vdr-form-field label="Rating" for="rating">
                        <input id="rating" type="number" min="1" max="5" formControlName="rating" />
                    </vdr-form-field>

                    <!-- etc -->
                </div>
            </vdr-card>
            // highlight-start
            <vdr-card
                    formGroupName="customFields"
                    *ngIf="customFields.length"
                    [title]="'common.custom-fields' | translate"
            >
                <vdr-tabbed-custom-fields
                        entityName="ProductReview"
                        [customFields]="customFields"
                        [customFieldsFormGroup]="detailForm.get('customFields')"
                ></vdr-tabbed-custom-fields>
            </vdr-card>
            // highlight-end
        </vdr-page-block>
    </vdr-page-detail-layout>
</form>
```


---

---
title: 'Creating List Views'
---

The two most common type of components you'll be creating in your UI extensions are list components and detail components.

In Vendure, we have standardized the way you write these components so that your ui extensions can be made to fit seamlessly into the rest of the app.

:::note
The specific pattern described here is for Angular-based components. It is also possible to create list views using React components, but 
in that case you won't be able to use the built-in data table & other Angular-specific components.
:::

## Example: Creating a Product Reviews List

Let's say you have a plugin which adds a new entity to the database called `ProductReview`. You want to create a new list view in the Admin UI which displays all the reviews submitted.

### Use the PaginatedList interface

To use the standardized list component, you need to make sure your plugin exposes this list in the GraphQL API following the [PaginatedList interface](/reference/typescript-api/common/paginated-list/):

```graphql
type ProductReview implements Node {
  id: ID!
  createdAt: DateTime!
  updatedAt: DateTime!
  title: String!
  rating: Int!
  text: String!
  authorName: String!
  product: Product!
  productId: ID!  
}

type ProductReviewList implements PaginatedList {
  items: [ProductReview!]!
  totalItems: Int!
}
```

:::info
See the [Paginated Lists guide](/guides/how-to/paginated-list/) for details on how to implement this in your server plugin code.
:::

### Create the list component

The list component itself is an Angular component which extends the [BaseListComponent](/reference/admin-ui-api/list-detail-views/base-list-component/) or [TypedBaseListComponent](/reference/admin-ui-api/list-detail-views/typed-base-list-component) class.

This example assumes you have set up your project to use code generation as described in the [GraphQL code generation guide](/guides/how-to/codegen/#codegen-for-admin-ui-extensions).

```ts title="src/plugins/reviews/ui/components/review-list/review-list.component.ts"
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { TypedBaseListComponent, SharedModule } from '@vendure/admin-ui/core';
// This is the TypedDocumentNode generated by GraphQL Code Generator
import { graphql } from '../../gql';

const getReviewListDocument = graphql(`
  query GetReviewList($options: ReviewListOptions) {
    reviews(options: $options) {
      items {
        id
        createdAt
        updatedAt
        title
        rating
        text
        authorName
        productId
      }
      totalItems
    }
  }
`);

@Component({
    selector: 'review-list',
    templateUrl: './review-list.component.html',
    styleUrls: ['./review-list.component.scss'],
    changeDetection: ChangeDetectionStrategy.OnPush,
    standalone: true,
    imports: [SharedModule],
})
export class ReviewListComponent extends TypedBaseListComponent<typeof getReviewListDocument, 'reviews'> {

    // Here we set up the filters that will be available
    // to use in the data table
    readonly filters = this.createFilterCollection()
        .addIdFilter()
        .addDateFilters()
        .addFilter({
            name: 'title',
            type: {kind: 'text'},
            label: 'Title',
            filterField: 'title',
        })
        .addFilter({
            name: 'rating',
            type: {kind: 'number'},
            label: 'Rating',
            filterField: 'rating',
        })
        .addFilter({
            name: 'authorName',
            type: {kind: 'text'},
            label: 'Author',
            filterField: 'authorName',
        })
        .connectToRoute(this.route);

    // Here we set up the sorting options that will be available
    // to use in the data table
    readonly sorts = this.createSortCollection()
        .defaultSort('createdAt', 'DESC')
        .addSort({name: 'createdAt'})
        .addSort({name: 'updatedAt'})
        .addSort({name: 'title'})
        .addSort({name: 'rating'})
        .addSort({name: 'authorName'})
        .connectToRoute(this.route);

    constructor() {
        super();
        super.configure({
            document: getReviewListDocument,
            getItems: data => data.reviews,
            setVariables: (skip, take) => ({
                options: {
                    skip,
                    take,
                    filter: {
                        title: {
                            contains: this.searchTermControl.value,
                        },
                        ...this.filters.createFilterInput(),
                    },
                    sort: this.sorts.createSortInput(),
                },
            }),
            refreshListOnChanges: [this.filters.valueChanges, this.sorts.valueChanges],
        });
    }
}
```

### Create the template

This is the standard layout for any list view. The main functionality is provided by the [DataTable2Component](/reference/admin-ui-api/components/data-table2component/).

```html title="src/plugins/reviews/ui/components/review-list/review-list.component.html"
<!-- optional if you want some buttons at the top -->
<vdr-page-block>
    <vdr-action-bar>
        <vdr-ab-left></vdr-ab-left>
        <vdr-ab-right>
            <a class="btn btn-primary" *vdrIfPermissions="['CreateReview']" [routerLink]="['./', 'create']">
                <clr-icon shape="plus"></clr-icon>
                Create a review
            </a>
        </vdr-ab-right>
    </vdr-action-bar>
</vdr-page-block>

<!-- The data table -->
<vdr-data-table-2
        id="review-list"
        [items]="items$ | async"
        [itemsPerPage]="itemsPerPage$ | async"
        [totalItems]="totalItems$ | async"
        [currentPage]="currentPage$ | async"
        [filters]="filters"
        (pageChange)="setPageNumber($event)"
        (itemsPerPageChange)="setItemsPerPage($event)"
>
    <!-- optional if you want to support bulk actions -->
    <vdr-bulk-action-menu
            locationId="review-list"
            [hostComponent]="this"
            [selectionManager]="selectionManager"
    />
    
    <!-- Adds a search bar -->
    <vdr-dt2-search
            [searchTermControl]="searchTermControl"
            searchTermPlaceholder="Filter by title"
    />
    
    <!-- Here we define all the available columns -->
    <vdr-dt2-column id="id" [heading]="'common.id' | translate" [hiddenByDefault]="true">
        <ng-template let-review="item">
            {{ review.id }}
        </ng-template>
    </vdr-dt2-column>
    <vdr-dt2-column
            id="created-at"
            [heading]="'common.created-at' | translate"
            [hiddenByDefault]="true"
            [sort]="sorts.get('createdAt')"
    >
        <ng-template let-review="item">
            {{ review.createdAt | localeDate : 'short' }}
        </ng-template>
    </vdr-dt2-column>
    <vdr-dt2-column
            id="updated-at"
            [heading]="'common.updated-at' | translate"
            [hiddenByDefault]="true"
            [sort]="sorts.get('updatedAt')"
    >
        <ng-template let-review="item">
            {{ review.updatedAt | localeDate : 'short' }}
        </ng-template>
    </vdr-dt2-column>
    <vdr-dt2-column id="title" heading="Title" [optional]="false" [sort]="sorts.get('title')">
        <ng-template let-review="item">
            <a class="button-ghost" [routerLink]="['./', review.id]"
            ><span>{{ review.title }}</span>
                <clr-icon shape="arrow right"></clr-icon>
            </a>
        </ng-template>
    </vdr-dt2-column>
    <vdr-dt2-column id="rating" heading="Rating" [sort]="sorts.get('rating')">
        <ng-template let-review="item"><my-star-rating-component [rating]="review.rating"    /></ng-template>
    </vdr-dt2-column>
    <vdr-dt2-column id="author" heading="Author" [sort]="sorts.get('authorName')">
        <ng-template let-review="item">{{ review.authorName }}</ng-template>
    </vdr-dt2-column>
</vdr-data-table-2>
```

### Route config

```ts title="src/plugins/reviews/ui/routes.ts"
import { registerRouteComponent } from '@vendure/admin-ui/core';

import { ReviewListComponent } from './components/review-list/review-list.component';

export default [
    // highlight-start
    registerRouteComponent({
        path: '',
        component: ReviewListComponent,
        breadcrumb: 'Product reviews',
    }),
    // highlight-end
]
```

## Supporting custom fields

From Vendure v2.2, it is possible for your [custom entities to support custom fields](/guides/developer-guide/database-entity/#supporting-custom-fields).

If you have set up your entity to support custom fields, and you want custom fields to be available in the Admin UI list view,
you need to add the following to your list component:

```ts title="src/plugins/reviews/ui/components/review-list/review-list.component.ts"
@Component({
    selector: 'review-list',
    templateUrl: './review-list.component.html',
    styleUrls: ['./review-list.component.scss'],
    changeDetection: ChangeDetectionStrategy.OnPush,
    standalone: true,
    imports: [SharedModule],
})
export class ReviewListComponent extends TypedBaseListComponent<typeof getReviewListDocument, 'reviews'> {

    // highlight-next-line
    customFields = this.getCustomFieldConfig('ProductReview');

    readonly filters = this.createFilterCollection()
        .addIdFilter()
        .addDateFilters()
        .addFilter({
            name: 'title',
            type: {kind: 'text'},
            label: 'Title',
            filterField: 'title',
        })
        .addFilter({
            name: 'rating',
            type: {kind: 'number'},
            label: 'Rating',
            filterField: 'rating',
        })
        .addFilter({
            name: 'authorName',
            type: {kind: 'text'},
            label: 'Author',
            filterField: 'authorName',
        })
        // highlight-next-line
        .addCustomFieldFilters(this.customFields)
        .connectToRoute(this.route);

    readonly sorts = this.createSortCollection()
        .defaultSort('createdAt', 'DESC')
        .addSort({name: 'createdAt'})
        .addSort({name: 'updatedAt'})
        .addSort({name: 'title'})
        .addSort({name: 'rating'})
        .addSort({name: 'authorName'})
        // highlight-next-line
        .addCustomFieldSorts(this.customFields)
        .connectToRoute(this.route);
    
    // rest of class omitted for brevity
}
```

and then add the `vdr-dt2-custom-field-column` component to your data table:

```html title="src/plugins/reviews/ui/components/review-list/review-list.component.html"
<vdr-data-table-2
    id="review-list"
    [items]="items$ | async"
    [itemsPerPage]="itemsPerPage$ | async"
    [totalItems]="totalItems$ | async"
    [currentPage]="currentPage$ | async"
    [filters]="filters"
    (pageChange)="setPageNumber($event)"
    (itemsPerPageChange)="setItemsPerPage($event)"
>
    <!-- rest of data table omitted for brevity -->
    // highlight-start
    <vdr-dt2-custom-field-column
            *ngFor="let customField of customFields"
            [customField]="customField"
            [sorts]="sorts"
    />
    // highlight-end
</vdr-data-table-2>
```

---

---
title: 'Custom DataTable Components'
weight: 6
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

The Admin UI list views are powered by a data table component which features sorting, advanced filtering, pagination and more. It will also give you the option of displaying any configured [custom fields](/guides/developer-guide/custom-fields/) for the entity in question.

With Admin UI extensions, you can specify custom components to use in rendering any column of any data table - both custom fields _and_ built-in fields, using either Angular or React components.

Let's say we want to make the product "slug" column link to the matching product detail page in our storefront.

### 1. Define a component

First we'll define the component we will use to render the "slug" column:

<Tabs groupId="framework">
<TabItem value="angular" label="Angular">

Angular components will receive the value of the current column as the `rowItem` input. In this case, the `rowItem` will be the Product entity, because we will be adding this to the product list data table.

```ts title="src/plugins/slug-link/ui/components/slug-link/slug-link.component.ts"
import { Component, Input } from '@angular/core';
import { CustomColumnComponent } from '@vendure/admin-ui/core';

@Component({
    selector: 'slug-link',
    template: `
        <a [href]="'https://example.com/products/' + rowItem.slug" target="_blank">{{ rowItem.slug }}</a>
    `,
    standalone: true,
})
export class SlugLinkComponent implements CustomColumnComponent {
    @Input() rowItem: { slug: string };
}
```

</TabItem>
<TabItem value="react" label="React">

React components will receive the value of the current column as the `rowItem` prop. In this case, the `rowItem` will be the Product entity, because we will be adding this to the product list data table.

```tsx title="src/plugins/slug-link/ui/components/SlugLink.tsx"
import { ReactDataTableComponentProps } from '@vendure/admin-ui/react';
import React from 'react';

export function SlugLink({ rowItem }: ReactDataTableComponentProps<{ slug: string }>) {
    const slug = rowItem.slug;
    return (
        <a href={`https://example.com/category/${slug}`} target="_blank">
            {slug}
        </a>
    );
}
```

</TabItem>
</Tabs>

### 2. Register the component

Next we need to register the component in out `providers.ts` file. We need to pass both a `tableId` and a `columnId` to identify the table and column to which the component should be added. The values for these IDs can be found by pressing the `ctrl + u` shortcut when the Admin UI is in dev mode, and then clicking the extension point icon at the top of the column in question:

![Extension locations](./custom-data-table-location.webp)

In this case we want to target the `product-list` table and the `slug` column.

<Tabs groupId="framework">
<TabItem value="angular" label="Angular">

```ts title="src/plugins/slug-link/ui/providers.ts"
import { registerDataTableComponent } from '@vendure/admin-ui/core';
import { SlugLinkComponent } from './components/slug-link/slug-link.component';

export default [
    registerDataTableComponent({
        component: SlugWithLinkComponent,
        tableId: 'product-list',
        columnId: 'slug',
    }),
];
```

</TabItem>
<TabItem value="react" label="React">

```ts title="src/plugins/slug-link/ui/providers.ts"
import { registerReactDataTableComponent } from '@vendure/admin-ui/react';
import { SlugLink } from './components/SlugLink';

export default [
    registerReactDataTableComponent({
        component: SlugWithLink,
        tableId: 'product-list',
        columnId: 'slug',
        props: {
            // Additional props may be passed to the component
            foo: 'bar',
        },
    }),
];
```

</TabItem>
</Tabs>

When running the Admin UI, the product list slug should now be rendered as a link:

![Product list with slug link](./custom-data-table.webp)


---

---
title: 'Custom Detail Components'
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Detail views can be extended with custom Angular or React components using the [`registerCustomDetailComponent`](/reference/admin-ui-api/custom-detail-components/register-custom-detail-component/) and [`registerReactCustomDetailComponent`](/reference/admin-ui-api/react-extensions/register-react-custom-detail-component) functions.

Any components registered in this way will appear below the main detail form.

:::info
The valid locations for embedding custom detail components can be found in the [CustomDetailComponentLocationId docs](/reference/admin-ui-api/custom-detail-components/custom-detail-component-location-id).
:::

Let's imagine that your project has an external content management system (CMS) which is used to store additional details about products. You might want to display some of this information in the product detail page. We will demonstrate the same component in both Angular and React.

### 1. Create a component


<Tabs groupId="framework">
<TabItem value="Angular" label="Angular" default>

```ts title="src/plugins/cms/ui/components/product-info/product-info.component.ts"
import { Component, OnInit } from '@angular/core';
import { Observable, switchMap } from 'rxjs';
import { FormGroup } from '@angular/forms';
import { DataService, CustomDetailComponent, SharedModule } from '@vendure/admin-ui/core';
import { CmsDataService } from '../../providers/cms-data.service';

@Component({
    template: `
        <vdr-card title="CMS Info">
            <pre>{{ extraInfo$ | async | json }}</pre>
        </vdr-card>`,
    standalone: true,
    providers: [CmsDataService],
    imports: [SharedModule],
})
export class ProductInfoComponent implements CustomDetailComponent, OnInit {
    // These two properties are provided by Vendure and will vary
    // depending on the particular detail page you are embedding this
    // component into. In this case, it will be a "product" entity.
    entity$: Observable<any>
    detailForm: FormGroup;

    extraInfo$: Observable<any>;

    constructor(private cmsDataService: CmsDataService) {
    }

    ngOnInit() {
        this.extraInfo$ = this.entity$.pipe(
            switchMap(entity => this.cmsDataService.getDataFor(entity.id))
        );
    }
}
```

</TabItem>
<TabItem value="React" label="React">

When using React, we can use the [`useDetailComponentData` hook](/reference/admin-ui-api/react-hooks/use-detail-component-data) to access the entity and form data.

```tsx title="src/plugins/cms/ui/components/ProductInfo.tsx"
import React, { useEffect, useState } from 'react';
import { Card, useDetailComponentData, useInjector } from '@vendure/admin-ui/react';
import { CmsDataService } from '../providers/cms-data.service';

export function ProductInfo() {
    // The "entity" will vary depending on which detail page this component
    // is embedded in. In this case, it will be a "product" entity.
    const { entity, detailForm } = useDetailComponentData();
    const cmsDataService = useInjector(CmsDataService);
    const [extraInfo, setExtraInfo] = useState<any>();
    
    useEffect(() => {
        if (!entity?.id) {
            return;
        }
        const subscription = cmsDataService.getDataFor(entity?.id).subscribe(data => {
            setExtraInfo(data);
        });
        return () => subscription.unsubscribe();
    }, [entity?.id]);
    
    return (
        <Card title="CMS Info">
            <pre>{JSON.stringify(extraInfo, null, 2)}</pre>
        </Card>
    );
}
```

</TabItem>
</Tabs>

### 2. Register the component

We can then register the component in our `providers.ts` file:

<Tabs groupId="framework">
<TabItem value="Angular" label="Angular" default>

```ts title="src/plugins/cms/ui/providers.ts"
import { registerCustomDetailComponent } from '@vendure/admin-ui/core';
import { ProductInfoComponent } from './components/product-info/product-info.component';

export default [
    registerCustomDetailComponent({
        locationId: 'product-detail',
        component: ProductInfoComponent,
    }),
];
```

</TabItem>
<TabItem value="React" label="React">

```ts title="src/plugins/cms/ui/providers.ts"
import { registerReactCustomDetailComponent } from '@vendure/admin-ui/react';
import { ProductInfo } from './components/ProductInfo';

export default [
    registerReactCustomDetailComponent({
        locationId: 'product-detail',
        component: ProductInfo,
    }),
];
```

</TabItem>
</Tabs>

When running the Admin UI, the component should now appear in the product detail page:

![Product detail with custom component](./detail-component.webp)

## Manipulating the detail form

The `detailForm` property is an instance of the Angular [FormGroup](https://angular.io/api/forms/FormGroup) which can be used to manipulate the form fields, set the validity of the form, mark the form as dirty etc. For example, we could add a button which updates the `description` field of the product:

<Tabs groupId="framework">
<TabItem value="Angular" label="Angular" default>

```ts title="src/plugins/cms/ui/components/product-info/product-info.component.ts"
import { Component, OnInit } from '@angular/core';
import { FormGroup } from '@angular/forms';
import { CustomDetailComponent } from '@vendure/admin-ui/core';

@Component({
    template: `<button class="button secondary" (click)="updateDescription()">Update description</button>`,
    standalone: true,
})
export class ProductInfoComponent implements CustomDetailComponent, OnInit {
    entity$: Observable<any>
    detailForm: FormGroup;
    
    // highlight-start
    updateDescription() {
        const descriptionControl = this.detailForm.get('description');
        if (descriptionControl) {
            descriptionControl.setValue('New description');
            descriptionControl.markAsDirty();
        }        
    }
    // highlight-end
}
```

</TabItem>
<TabItem value="React" label="React">

```tsx title="src/plugins/cms/ui/components/ProductInfo.tsx"
import React from 'react';
import { Card, useDetailComponentData } from '@vendure/admin-ui/react';

export function ProductInfo() {
    const { detailForm } = useDetailComponentData();

    // highlight-start
    const updateDescription = () => {
        const descriptionControl = detailForm.get('description');
        if (descriptionControl) {
            descriptionControl.setValue('New description');
            descriptionControl.markAsDirty();
        }
    };
    // highlight-end

    return (
        <button className="button secondary" onClick={updateDescription}>Update description</button>
    );
}
```

</TabItem>
</Tabs>


---

---
title: 'Custom Form Inputs'
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

You can define custom Angular or React components which can be used to render [Custom Fields](/guides/developer-guide/custom-fields/) you have defined on your entities as well as [configurable args](/reference/typescript-api/configurable-operation-def/config-args/) used by custom [Configurable Operations](/guides/developer-guide/strategies-configurable-operations/#configurable-operations).

## For Custom Fields

Let's say you define a custom "intensity" field on the Product entity:

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';

export const config: VendureConfig = {
    // ...
    customFields: {
        Product: [
            { name: 'intensity', type: 'int', min: 0, max: 100, defaultValue: 0 },
        ],
    },
}
```

By default, the "intensity" field will be displayed as a number input:

![./ui-extensions-custom-field-default.webp](./ui-extensions-custom-field-default.webp)

But let's say we want to display a **range slider** instead.

### 1. Define a component

First we need to define a new Angular or React component to render the slider:

<Tabs groupId="framework">
<TabItem value="Angular" label="Angular" default>

Angular components will have the `readonly`, `config` and `formControl` properties populated automatically.

```ts title="src/plugins/common/ui/components/slider-form-input/slider-form-input.component.ts"
import { Component } from '@angular/core';
import { FormControl } from '@angular/forms';
import { IntCustomFieldConfig, SharedModule, FormInputComponent } from '@vendure/admin-ui/core';

@Component({
    template: `
      <input
          type="range"
          [min]="config.min || 0"
          [max]="config.max || 100"
          [formControl]="formControl" />
      {{ formControl.value }}
  `,
    standalone: true,
    imports: [SharedModule],
})
export class SliderControlComponent implements FormInputComponent<IntCustomFieldConfig> {
    readonly: boolean;
    config: IntCustomFieldConfig;
    formControl: FormControl;
}
```

</TabItem>
<TabItem value="React" label="React">

React components can use the [`useFormControl`](/reference/admin-ui-api/react-hooks/use-form-control) hook to access the form control and set its value. The 
component will also receive `config` and `readonly` data as props. 

```tsx title="src/plugins/common/ui/components/SliderFormInput.tsx"
import React from 'react';
import { useFormControl, ReactFormInputOptions, useInjector } from '@vendure/admin-ui/react';

export function SliderFormInput({ readonly, config }: ReactFormInputOptions) {
    const { value, setFormValue } = useFormControl();
    const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
        const val = +e.target.value;
        setFormValue(val);
    };
    return (
        <>
            <input
                type="range"
                readOnly={readonly}
                min={config.min || 0}
                max={config.max || 100}
                value={value}
                onChange={handleChange}
            />
            {value}
        </>
    );
};
```

</TabItem>
</Tabs>

### 2. Register the component

Next we will register this component in our `providers.ts` file and give it a unique ID, `'slider-form-input'`:

<Tabs groupId="framework">
<TabItem value="Angular" label="Angular" default>

```ts title="src/plugins/common/ui/providers.ts"
import { registerFormInputComponent } from '@vendure/admin-ui/core';
import { SliderControlComponent } from './components/slider-form-input/slider-form-input.component';

export default [
    registerFormInputComponent('slider-form-input', SliderControlComponent),
];
```

</TabItem>
<TabItem value="React" label="React">

```ts title="src/plugins/common/ui/providers.ts"
import { registerReactFormInputComponent } from '@vendure/admin-ui/react';
import { SliderControl } from './components/SliderFormInput';

export default [
    registerReactFormInputComponent('slider-form-input', SliderFormInput),
];
```

</TabItem>
</Tabs>

### 3. Register the providers

The `providers.ts` is then passed to the `compileUiExtensions()` function as described in the [UI Extensions Getting Started guide](/guides/extending-the-admin-ui/getting-started/):

```ts title="src/vendure-config.ts"
import * as path from 'path';
import { VendureConfig } from '@vendure/core';
import { AdminUiPlugin } from '@vendure/admin-ui-plugin';
import { compileUiExtensions } from '@vendure/ui-devkit/compiler';

export const config: VendureConfig = {
    // ...
    plugins: [
        AdminUiPlugin.init({
            port: 3302,
            app: compileUiExtensions({
                outputPath: path.join(__dirname, '../admin-ui'),
                extensions: [{
                    id: 'common',
                    // highlight-start
                    extensionPath: path.join(__dirname, 'plugins/common/ui'),
                    providers: ['providers.ts'],
                    // highlight-end
                }],
            }),
        }),
    ],
};
```

### 4. Update the custom field config

Once registered, this new slider input can be used in our custom field config:

```ts title="src/vendure-config.ts"
customFields: {
    Product: [
        {
            name: 'intensity', type: 'int', min: 0, max: 100, defaultValue: 0,
            // highlight-next-line
            ui: {component: 'slider-form-input'}
        },
    ],
}
```

As we can see, adding the `ui` property to the custom field config allows us to specify our custom slider component.
The component id _'slider-form-input'_ **must match** the string passed as the first argument to `registerFormInputComponent()`.

:::info
If we want, we can also pass any other arbitrary data in the `ui` object, which will then be available in our component as `this.config.ui.myField`. Note that only JSON-compatible data types are permitted, so no functions or class instances.
:::


Re-compiling the Admin UI will result in our SliderControl now being used for the "intensity" custom field:

![./ui-extensions-custom-field-slider.webp](./ui-extensions-custom-field-slider.webp)

## Custom Field Controls for Relations

If you have a custom field of the `relation` type (which allows you to relate entities with one another), you can also define custom field controls for them. The basic mechanism is exactly the same as with primitive custom field types (i.e. `string`, `int` etc.), but there are a couple of important points to know:

1. The value of the `formControl` will be the _related entity object_ rather than an id. The Admin UI will internally take care of converting the entity object into an ID when performing the create/update mutation.
2. Your control will most likely need to fetch data in order to display a list of selections for the user.

Here's an example of a custom field control for a `relation` field which relates a Product to a custom `ProductReview` entity:

```ts title="src/plugins/reviews/ui/components/relation-review-input/relation-review-input.component.ts"
import { Component, OnInit } from '@angular/core';
import { FormControl } from '@angular/forms';
import { ActivatedRoute } from '@angular/router';
import { RelationCustomFieldConfig } from '@vendure/common/lib/generated-types';
import { FormInputComponent, DataService, SharedModule } from '@vendure/admin-ui/core';
import { Observable } from 'rxjs';
import { switchMap } from 'rxjs/operators';

import { GET_REVIEWS_FOR_PRODUCT } from '../product-reviews-list/product-reviews-list.graphql';

@Component({
    selector: 'relation-review-input',
    template: `
        <div *ngIf="formControl.value as review">
            <vdr-chip>{{ review.rating }} / 5</vdr-chip>
            {{ review.summary }}
            <a [routerLink]="['/extensions', 'product-reviews', review.id]">
                <clr-icon shape="link"></clr-icon>
            </a>
        </div>
        <select [formControl]="formControl" [compareWith]="compareFn">
            <option [ngValue]="null">Select a review...</option>
            <option *ngFor="let item of reviews$ | async" [ngValue]="item">
                <b>{{ item.summary }}</b>
                {{ item.rating }} / 5
            </option>
        </select>
    `,
    standalone: true,
    imports: [SharedModule],
})
export class RelationReviewInputComponent implements OnInit, FormInputComponent<RelationCustomFieldConfig> {
    readonly: boolean;
    formControl: FormControl;
    config: RelationCustomFieldConfig;

    reviews$: Observable<any[]>;

    constructor(private dataService: DataService, private route: ActivatedRoute) {}

    ngOnInit() {
        this.reviews$ = this.route.data.pipe(
            switchMap(data => data.entity),
            switchMap((product: any) => {
                return this.dataService
                    .query(GET_REVIEWS_FOR_PRODUCT, { productId: product.id })
                    .mapSingle(({ product }) => product?.reviews.items ?? []);
            }),
        );
    }

    compareFn(item1: { id: string } | null, item2: { id: string } | null) {
        return item1 && item2 ? item1.id === item2.id : item1 === item2;
    }
}
```

## For ConfigArgs

[ConfigArgs](/reference/typescript-api/configurable-operation-def/config-args/) are used by classes which extend [Configurable Operations](/guides/developer-guide/strategies-configurable-operations/#configurable-operations) (such as ShippingCalculator or PaymentMethodHandler). These ConfigArgs allow user-input values to be passed to the operation's business logic.

They are configured in a very similar way to custom fields, and likewise can use custom form inputs by specifying the `ui` property. 

Here's an example:

```ts title="src/config/order-fixed-discount-action.ts"
export const orderFixedDiscount = new PromotionOrderAction({
    code: 'order_fixed_discount',
    args: {
        discount: {
            type: 'int',
            // highlight-start
            ui: {
                component: 'currency-form-input',
            },
            // highlight-end
        },
    },
    execute(ctx, order, args) {
        return -args.discount;
    },
    description: [{languageCode: LanguageCode.en, value: 'Discount order by fixed amount'}],
});
```




---

---
title: 'Custom History Timeline Components'
---

The Order & Customer detail pages feature a timeline of history entries. Since v1.9.0 it is possible to define custom history entry types - see the [HistoryService docs](/reference/typescript-api/services/history-service/) for an example.

You can also define a custom Angular component to render any timeline entry using the [registerHistoryEntryComponent function](/reference/admin-ui-api/custom-history-entry-components/register-history-entry-component/).

![./timeline-entry.webp](./timeline-entry.webp)

:::note
Currently it is only possible to define new tabs using Angular components.
:::

Following the example used in the HistoryService docs, we can define a component to render the tax ID verification
entry in our Customer timeline:

```ts title="src/plugins/tax-id/ui/components/tax-id-history-entry/tax-id-history-entry.component.ts"
import { Component } from '@angular/core';
import {
    CustomerFragment,
    CustomerHistoryEntryComponent,
    SharedModule,
    TimelineDisplayType,
    TimelineHistoryEntry,
} from '@vendure/admin-ui/core';

@Component({
    selector: 'tax-id-verification-entry',
    template: `
        <div *ngIf="entry.data.valid">
            Tax ID <strong>{{ entry.data.taxId }}</strong> was verified
            <vdr-history-entry-detail *ngIf="entry.data">
                <vdr-object-tree [value]="entry.data"></vdr-object-tree>
            </vdr-history-entry-detail>
        </div>
        <div *ngIf="!entry.data.valid">Tax ID {{ entry.data.taxId }} could not be verified</div>
    `,
    standalone: true,
    imports: [SharedModule],
})
export class TaxIdHistoryEntryComponent implements CustomerHistoryEntryComponent {
    entry: TimelineHistoryEntry;
    customer: CustomerFragment;

    getDisplayType(entry: TimelineHistoryEntry): TimelineDisplayType {
        return entry.data.valid ? 'success' : 'error';
    }

    getName(entry: TimelineHistoryEntry): string {
        return 'Tax ID Verification Plugin';
    }

    isFeatured(entry: TimelineHistoryEntry): boolean {
        return true;
    }

    getIconShape(entry: TimelineHistoryEntry) {
        return entry.data.valid ? 'check-circle' : 'exclamation-circle';
    }
}
```

We can then register this component in the `providers.ts` file:

```ts title="src/plugins/tax-id/ui/providers.ts"
import { registerHistoryEntryComponent } from '@vendure/admin-ui/core';
import { TaxIdHistoryEntryComponent } from './components/tax-id-history-entry/tax-id-history-entry.component';

export default [
    registerHistoryEntryComponent({
        type: 'CUSTOMER_TAX_ID_VERIFICATION',
        component: TaxIdHistoryEntryComponent,
    }),
];
```

Then we need to add the `providers.ts` file to the `uiExtensions` array as described in the [UI Extensions Getting Started guide](/guides/extending-the-admin-ui/getting-started/).



---

---
title: 'Dashboard Widgets'
---

Dashboard widgets are components which can be added to the Admin UI dashboard. These widgets are useful for displaying information which is commonly required by administrations, such as sales summaries, lists of incomplete orders, notifications, etc.

The Admin UI comes with a handful of widgets, and you can also create your own widgets.

![Dashboard widgets](./dashboard-widgets.webp)

:::note
Currently it is only possible to define new widgets using Angular components.
:::

## Example: Reviews Widget

In this example we will use a hypothetical reviews plugin, which allows customers to write product reviews. These reviews then get approved by an Administrator before being displayed in the storefront.

To notify administrators about new reviews that need approval, we'll create a dashboard widget.

### Create the widget

A dashboard widget is an Angular component. This example features a simplified UI, just to illustrate the overall structure:

```ts title="src/plugins/reviews/ui/components/reviews-widget/reviews-widget.component.ts"
import { Component, OnInit } from '@angular/core';
import { DataService, SharedModule } from '@vendure/admin-ui/core';
import { Observable } from 'rxjs';

@Component({
    selector: 'reviews-widget',
    template: `
        <ul>
            <li *ngFor="let review of pendingReviews$ | async">
                <a [routerLink]="['/extensions', 'product-reviews', review.id]">{{ review.summary }}</a>
                <span class="rating">{{ review.rating }} / 5</span>
            </li>
        </ul>
    `,
    standalone: true,
    imports: [SharedModule],
})
export class ReviewsWidgetComponent implements OnInit {
    pendingReviews$: Observable<any[]>;

    constructor(private dataService: DataService) {}

    ngOnInit() {
        this.pendingReviews$ = this.dataService.query(gql`
            query GetAllReviews($options: ProductReviewListOptions) {
                productReviews(options: $options) {
                    items {
                        id
                        createdAt
                        authorName
                        summary
                        rating
                    }
                }
            }`, {
                options: {
                    filter: { state: { eq: 'new' } },
                    take: 10,
                },
            })
            .mapStream(data => data.productReviews.items);
    }
}
```

:::note
We also need to define an `NgModule` for this component. This is because we will be lazy-loading the component at run-time, and the NgModule is required for us to use shared providers (e.g. `DataService`) and any shared components, directives or pipes defined in the `@vendure/admin-ui/core` package.
:::

### Register the widget

Our widget now needs to be registered in our [providers file](/guides/extending-the-admin-ui/getting-started/#providers):

```ts title="src/plugins/reviews/ui/providers.ts"
import { registerDashboardWidget } from '@vendure/admin-ui/core';

export default [
    // highlight-start
    registerDashboardWidget('reviews', {
        title: 'Latest reviews',
        supportedWidths: [4, 6, 8, 12],
        requiresPermissions: ['ReadReview'],
        loadComponent: () =>
            import('./reviews-widget/reviews-widget.component').then(
                m => m.ReviewsWidgetComponent,
            ),
    }),
    // highlight-end
];
```

* **`title`** This is the title of the widget that will be displayed in the widget header.
* **`supportedWidths`** This indicated which widths are supported by the widget. The number indicates columns in a Bootstrap-style 12-column grid. So `12` would be full-width, `6` half-width, etc. In the UI, the administrator will be able to re-size the widget to one of the supported widths. If not provided, all widths will be allowed.
* **`requiresPermissions`** This allows an array of Permissions to be specified which limit the display of the widget to administrators who possess all of those permissions. If not provided, all administrators will be able to use the widget.
* **`loadComponent`** This function defines how to load the component. Using the dynamic `import()` syntax will enable the Angular compiler to intelligently generate a lazy-loaded JavaScript bundle just for that component. This means that your widget can, for example, include 3rd-party dependencies (such as a charting library) without increasing the bundle size (and therefore load-times) of the main Admin UI app. The widget-specific code will _only_ be loaded when the widget is rendered on the dashboard.

Once registered, the reviews widget will be available to select by administrators with the appropriate permissions.

## Setting the default widget layout

While administrators can customize which widgets they want to display on the dashboard, and the layout of those widgets, you can also set a default layout:

```ts title="src/plugins/reviews/ui/providers.ts"
import { registerDashboardWidget, setDashboardWidgetLayout } from '@vendure/admin-ui/core';

export default [
    registerDashboardWidget('reviews', {
        // omitted for brevity
    }),
    // highlight-start
    setDashboardWidgetLayout([
        { id: 'welcome', width: 12 },
        { id: 'orderSummary', width: 4 },
        { id: 'latestOrders', width: 8 },
        { id: 'reviews', width: 6 },
    ]),
    // highlight-end
];
```

This defines the order of widgets with their default widths. The actual layout in terms of rows and columns will be calculated at run-time based on what will fit on each row.

## Overriding default widgets

The Admin UI comes with a set of default widgets, such as the order summary and latest orders widgets (they can be found in [the default-widgets.ts file](https://github.com/vendure-ecommerce/vendure/blob/master/packages/admin-ui/src/lib/dashboard/src/default-widgets.ts)).

Sometimes you may wish to alter the permissions settings of the default widgets to better control which of your Administrators is able to access it.

For example, the "order summary" widget has a default permission requirement of "ReadOrder". If you want to limit the availability to e.g. the SuperAdmin role, you can do so by overriding the definition like this:

```ts title="src/plugins/reviews/ui/providers.ts"
import { registerDashboardWidget } from '@vendure/admin-ui/core';
import { OrderSummaryWidgetComponent } from '@vendure/admin-ui/dashboard';

export default [
    // highlight-start
    registerDashboardWidget('orderSummary', {
        title: 'dashboard.orders-summary',
        loadComponent: () => OrderSummaryWidgetComponent,
        requiresPermissions: ['SuperAdmin'],
    }),
    // highlight-end
];
```


---

---
title: 'Defining routes'
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Routes allow you to mount entirely custom components at a given URL in the Admin UI. New routes will appear in this area of the Admin UI:

![Route area](./route-area.webp)

Routes can be defined natively using either **Angular** or **React**. It is also possible to [use other frameworks](/guides/extending-the-admin-ui/using-other-frameworks/) in a more limited capacity.

## Example: Creating a "Greeter" route

### 1. Create a plugin

We will first quickly scaffold a new plugin to house our UI extensions:

- Run `npx vendure add` from your project root
- Select `Create a new Vendure plugin` and when prompted for a name, name it **"greeter"**
- After the plugin is created, you will be prompted to add features to the plugin. Select `[Plugin: UI] Set up Admin UI extensions`

You should now have a new plugin scaffolded at `./src/plugins/greeter`, with some empty UI extension files in the `ui` 
directory. If you check your `vendure-config.ts` file you should also see that your `AdminUiPlugin.init()` call has been modified
to compile the UI extensions:

```ts
AdminUiPlugin.init({
    route: 'admin',
    port: serverPort + 2,
    adminUiConfig: {
        apiPort: serverPort,
    },
    // highlight-start
    app: compileUiExtensions({
        outputPath: path.join(__dirname, '../admin-ui'),
        extensions: [
            GreeterPlugin.ui,
        ],
        devMode: true,
    }),
    // highlight-end
}),
```

### 2. Create the route component

First we need to create the component which will be mounted at the route. This component can be either an Angular component or a React component.

<Tabs groupId="framework">
<TabItem value="Angular" label="Angular" default>


```ts title="src/plugins/greeter/ui/components/greeter/greeter.component.ts"
import { SharedModule } from '@vendure/admin-ui/core';
import { Component } from '@angular/core';

@Component({
    selector: 'greeter',
    template: `
        <vdr-page-block>
            <h2>{{ greeting }}</h2>
        </vdr-page-block>`,
    standalone: true,
    imports: [SharedModule],
})
export class GreeterComponent {
    greeting = 'Hello!';
}
```

</TabItem>
<TabItem value="React" label="React">

```ts title="src/plugins/greeter/ui/components/greeter/Greeter.tsx"
import React from 'react';

export function Greeter() {
    const greeting = 'Hello!';
    return (
        <div className="page-block">
            <h2>{greeting}</h2>
        </div>
    );
}
```

</TabItem>
</Tabs>

:::note
The `<vdr-page-block>` (Angular) and `<div className="page-block">` (React) is a wrapper that sets the layout and max width of your component to match the rest of the Admin UI. You should usually wrap your component in this element.
:::


### 3. Define the route

Next we need to define a route in our `routes.ts` file. Note that this file can have any name, but "routes.ts" is a convention.

<Tabs groupId="framework">
<TabItem value="Angular" label="Angular" default>

Using [`registerRouteComponent`](/reference/admin-ui-api/routes/register-route-component) you can define a new route based on an Angular component.

```ts title="src/plugins/greeter/ui/routes.ts"
import { registerRouteComponent } from '@vendure/admin-ui/core';
import { GreeterComponent } from './components/greeter/greeter.component';

export default [
    registerRouteComponent({
        component: GreeterComponent,
        path: '',
        title: 'Greeter Page',
        breadcrumb: 'Greeter',
    }),
];
```

</TabItem>
<TabItem value="React" label="React">

Here's the equivalent example using React and [`registerReactRouteComponent`](/reference/admin-ui-api/react-extensions/register-react-route-component):

```ts title="src/plugins/greeter/ui/routes.ts"
import { registerReactRouteComponent } from '@vendure/admin-ui/react';
import { Greeter } from './components/Greeter';

export default [
    registerReactRouteComponent({
        component: Greeter,
        path: '',
        title: 'Greeter Page',
        breadcrumb: 'Greeter',
    }),
];
```

</TabItem>
</Tabs>

The `path: ''` is actually optional, since `''` is the default value. But this is included here to show that you can mount different components at different paths. See the section on route parameters below.

### 4. Add the route to the extension config

Since you have used the CLI to scaffold your plugin, this part has already been done for you. But for the sake of completeness
this is the part of your plugin which is configured to point to your routes file:

```ts title="src/plugins/greeter/greeter.plugin.ts"
// ...
export class GreeterPlugin {
    static options: PluginInitOptions;

    static init(options: PluginInitOptions): Type<GreeterPlugin> {
        this.options = options;
        return GreeterPlugin;
    }

    // highlight-start
    static ui: AdminUiExtension = {
        id: 'greeter-ui',
        extensionPath: path.join(__dirname, 'ui'),
        routes: [{ route: 'greeter', filePath: 'routes.ts' }],
        providers: ['providers.ts'],
    };
    // highlight-end
}

```

Note that by specifying `route: 'greeter'`, we are "mounting" the routes at the `/extensions/greeter` path.

:::info

The `/extensions/` prefix is used to avoid conflicts with built-in routes. From Vendure v2.2.0 it is possible to customize
this prefix using the `prefix` property. See the section on [overriding built-in routes](#overriding-built-in-routes) for 
more information.

:::

The `filePath` property is relative to the directory specified in the `extensionPath` property. In this case, the `routes.ts` file is located at `src/plugins/greeter/ui/routes.ts`.

### 5. Test it out

Now run your app with `npm run dev`. Wait for it to compile the Admin UI extensions.

Now go to the Admin UI app in your browser and log in. You should now be able to manually enter the URL `http://localhost:3000/admin/extensions/greeter` and you should see the component with the "Hello!" header:

![./ui-extensions-greeter.webp](./ui-extensions-greeter.webp)


## Links

To link to other routes, you must use the `routerLink` directive for Angular, or the `Link` component for React:


<Tabs groupId="framework">
<TabItem value="Angular" label="Angular" default>

```html
<a class="button-ghost" [routerLink]="['/extensions/my-plugin/my-custom-route']">
    John Smith
</a>
```

</TabItem>
<TabItem value="React" label="React">

```tsx
import React from 'react';
import { Link } from '@vendure/admin-ui/react';

export function DemoComponent() {
    return (
        <Link className="button-ghost" href="/extensions/my-plugin/my-custom-route">
            John Smith
        </Link>
    );
}
```

</TabItem>
</Tabs>

## Route parameters

The `path` property is used to specify the path to a specific component. This path can contain parameters, which will then be made available to the component. Parameters are defined using the `:` prefix. For example:

<Tabs groupId="framework">
<TabItem value="Angular" label="Angular" default>

```ts title="src/plugins/my-plugin/ui/routes.ts"
import { registerRouteComponent } from '@vendure/admin-ui/core';
import { TestComponent } from './components/test/test.component';

export default [
    registerRouteComponent({
        component: TestComponent,
        // highlight-next-line
        path: ':id',
        title: 'Test',
        breadcrumb: 'Test',
    }),
];
```

</TabItem>
<TabItem value="React" label="React">

```ts title="src/plugins/my-plugin/ui/routes.ts"
import { registerReactRouteComponent } from '@vendure/admin-ui/react';
import { Test } from './components/Test';

export default [
    registerReactRouteComponent({
        component: Test,
        // highlight-next-line
        path: ':id',
        title: 'Test',
        breadcrumb: 'Test',
    }),
];
```

</TabItem>
</Tabs>

The `id` parameter will then be available in the component:

<Tabs groupId="framework">
<TabItem value="Angular" label="Angular" default>

```ts title="src/plugins/my-plugin/ui/components/test/test.component.ts"
import { SharedModule } from '@vendure/admin-ui/core';
import { Component } from '@angular/core';
import { ActivatedRoute } from '@angular/router';

@Component({
    selector: 'test',
    template: `
        <vdr-page-block>
            // highlight-next-line
            <p>id: {{ id }}</p>
        </vdr-page-block>`,
    standalone: true,
    imports: [SharedModule],
})
export class TestComponent {
    id: string;

    constructor(private route: ActivatedRoute) {
        // highlight-next-line
        this.id = this.route.snapshot.paramMap.get('id');
    }
}
```

</TabItem>
<TabItem value="React" label="React">

```tsx title="src/plugins/my-plugin/ui/components/Test.tsx"
import React from 'react';
import { useRouteParams } from '@vendure/admin-ui/react';

export function Test() {
    // highlight-next-line
    const { params } = useRouteParams();
    return (
        <div className="page-block">
            // highlight-next-line
            <p>id: {params.id}</p>
        </div>
    );
}
```

</TabItem>
</Tabs>

Loading the route `/extensions/test/123` will then display the id "123".

## Injecting services

It is possible to inject services into your components. This includes both the [built-in services](/reference/admin-ui-api/services/) for things like data fetching, notifications and modals, as well as any custom services you have defined in your UI extension.

Here's an example of injecting the built-in `NotificationService` into a component to display a toast notification:


<Tabs groupId="framework">
<TabItem value="Angular" label="Angular" default>

In Angular, we can use either the constructor to inject the service (as shown below), or the `inject()` function. See the [Angular dependency injection guide](https://angular.io/guide/dependency-injection#injecting-a-dependency) for more information.

```ts title="src/plugins/my-plugin/ui/components/test/test.component.ts"
import { SharedModule, NotificationService } from '@vendure/admin-ui/core';
import { Component } from '@angular/core';

@Component({
    selector: 'test',
    template: `
        <vdr-page-block>
            <button class="button primary" (click)="showNotification()">Click me</button>
        </vdr-page-block>`,
    standalone: true,
    imports: [SharedModule],
})
export class TestComponent {
    // highlight-next-line
    constructor(private notificationService: NotificationService) {}
    
    showNotification() {
        // highlight-next-line
        this.notificationService.success('Hello!');
    }
}
```

</TabItem>
<TabItem value="React" label="React">

In React, we use the [`useInjector()`](/reference/admin-ui-api/react-hooks/use-injector) hook to inject the service:

```tsx title="src/plugins/my-plugin/ui/components/Test.tsx"
import { NotificationService } from '@vendure/admin-ui/core';
// highlight-next-line
import { useInjector } from '@vendure/admin-ui/react';
import React from 'react';

export function Test() {
    // highlight-next-line
    const notificationService = useInjector(NotificationService);
    
    function showNotification() {
        // highlight-next-line
        notificationService.success('Hello!');
    }
    return (
        <div className="page-block">
            <button className="button primary" onClick={showNotification}>Click me</button>
        </div>
    );
}
```

</TabItem>
</Tabs>

## Setting page title

The `title` property is used to set the page title. This is displayed in the browser tab as well as in the page header.

### In the route definition

The page title can be set in the route definition:

<Tabs groupId="framework">
<TabItem value="Angular" label="Angular" default>

```ts title="src/plugins/my-plugin/ui/routes.ts"
import { registerRouteComponent } from '@vendure/admin-ui/core';
import { TestComponent } from './components/test/test.component';

export default [
    registerRouteComponent({
        component: TestComponent,
        // highlight-next-line
        title: 'Test',
        breadcrumb: 'Test',
    }),
];
```

</TabItem>
<TabItem value="React" label="React">

```ts title="src/plugins/my-plugin/ui/routes.ts"
import { registerReactRouteComponent } from '@vendure/admin-ui/react';
import { Test } from './components/Test';

export default [
    registerReactRouteComponent({
        component: Test,
        // highlight-next-line
        title: 'Test',
        breadcrumb: 'Test',
    }),
];
```

</TabItem>
</Tabs>

### Dynamically from the component

It is also possible to update the page title dynamically from the route component itself:

<Tabs groupId="framework">
<TabItem value="Angular" label="Angular" default>

```ts title="src/plugins/my-plugin/ui/components/test/test.component.ts"
import { PageMetadataService, SharedModule } from '@vendure/admin-ui/core';
import { Component } from '@angular/core';

@Component({
    selector: 'test',
    template: `
        <vdr-page-block>
            <vdr-card>
                // highlight-next-line
                <button class="button primary" (click)="handleClick()">Update title</button>
            </vdr-card>
        </vdr-page-block>`,
    standalone: true,
    imports: [SharedModule],
})
export class TestComponent {
    // highlight-next-line
    constructor(private pageMetadataService: PageMetadataService) {}

    handleClick() {
        // highlight-next-line
        pageMetadataService.setTitle('New title');
    }
}
```

</TabItem>
<TabItem value="React" label="React">

```tsx title="src/plugins/my-plugin/ui/components/Test.tsx"
import { Card, usePageMetadata } from '@vendure/admin-ui/react';
import React from 'react';

export function Test() {
    // highlight-next-line
    const { setTitle } = usePageMetadata();

    function handleClick() {
        // highlight-next-line
        setTitle('New title');
    }
    return (
        <div className="page-block">
            <Card>
                <button className="button primary" onClick={handleClick}>
                    Update title
                </button>
            </Card>
        </div>
    );
}
```

</TabItem>
</Tabs>

## Setting breadcrumbs

### In the route definition

The page breadcumbs can be set in the route definition in a couple of ways. The simplest is to specify the `breadcumb` property:


<Tabs groupId="framework">
<TabItem value="Angular" label="Angular" default>

```ts title="src/plugins/my-plugin/ui/routes.ts"
import { registerRouteComponent } from '@vendure/admin-ui/core';
import { TestComponent } from './components/test/test.component';

export default [
    registerRouteComponent({
        component: TestComponent,
        title: 'Test',
        locationId: 'my-location-id'
        // highlight-next-line
        breadcrumb: 'Test',
    }),
];
```

</TabItem>
<TabItem value="React" label="React">

```ts title="src/plugins/my-plugin/ui/routes.ts"
import { registerReactRouteComponent } from '@vendure/admin-ui/react';
import { Test } from './components/Test';

export default [
    registerReactRouteComponent({
        component: Test,
        title: 'Test',
        // highlight-next-line
        breadcrumb: 'Test',
    }),
];
```

</TabItem>
</Tabs>

This can be a string (as above), a link/label pair, or an array of link/label pairs:

```ts title="src/plugins/my-plugin/ui/routes.ts"
import { registerRouteComponent } from '@vendure/admin-ui/core';
import { TestComponent } from './components/test/test.component';

export default [
    registerRouteComponent({
        component: TestComponent,
        path: 'test-1',
        title: 'Test 1',
        // highlight-start
        breadcrumb: { label: 'Test', link: '/extensions/test' },
        // highlight-end
    }),
    registerRouteComponent({
        component: TestComponent,
        path: 'test-2',
        title: 'Test 2',
        // highlight-start
        breadcrumb: [
            { label: 'Parent', link: '/extensions/test' },
            { label: 'Child', link: '/extensions/test/test-2' },
        ],
        // highlight-end
    }),
];
```

A more powerful way to set the breadcrumbs is by using the `getBreadcrumbs` property. This is a function that receives any resolved detail data and returns an array of link/label pairs. An example of its use can be seen in the [Creating detail views guide](/guides/extending-the-admin-ui/creating-detail-views/#route-config).

### Dynamically from the component

Similar to setting the title, the breadcrumbs can also be updated dynamically from the route component itself:

<Tabs groupId="framework">
<TabItem value="Angular" label="Angular" default>

```ts title="src/plugins/my-plugin/ui/components/test/test.component.ts"
import { PageMetadataService, SharedModule } from '@vendure/admin-ui/core';
import { Component } from '@angular/core';

@Component({
    selector: 'test',
    template: `
        <vdr-page-block>
            <vdr-card>
                // highlight-next-line
                <button class="button primary" (click)="handleClick()">Update breadcrumb</button>
            </vdr-card>
        </vdr-page-block>`,
    standalone: true,
    imports: [SharedModule],
})
export class TestComponent {
    // highlight-next-line
    constructor(private pageMetadataService: PageMetadataService) {}

    handleClick() {
        // highlight-next-line
        pageMetadataService.setBreadcrumb('New breadcrumb');
    }
}
```

</TabItem>
<TabItem value="React" label="React">

```tsx title="src/plugins/my-plugin/ui/components/Test.tsx"
import { Card, usePageMetadata } from '@vendure/admin-ui/react';
import React from 'react';

export function Test() {
    // highlight-next-line
    const { setBreadcrumb } = usePageMetadata();

    function handleClick() {
        // highlight-next-line
        setBreadcrumb('New breadcrumb');
    }
    return (
        <div className="page-block">
            <Card>
                <button className="button primary" onClick={handleClick}>
                    Update title
                </button>
            </Card>
        </div>
    );
}
```

</TabItem>
</Tabs>

## Overriding built-in routes

From Vendure v2.2.0, it is possible to override any of the built-in Admin UI routes. This is useful if you want to completely
replace a built-in route with your own custom component.

To do so, you'll need to specify the route `prefix` to be `''`, and then specify a `route` property which matches
a built-in route. 

For example, let's say we want to override the product detail page. The full path of that route is:

```
/catalog/products/:id
```

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';
import { AdminUiPlugin } from '@vendure/admin-ui-plugin';
import { compileUiExtensions } from '@vendure/ui-devkit/compiler';
import * as path from 'path';

export const config: VendureConfig = {
    // ...
    plugins: [
        AdminUiPlugin.init({
            port: 3002,
            app: compileUiExtensions({
                outputPath: path.join(__dirname, '../admin-ui'),
                extensions: [
                    {
                        id: 'my-plugin',
                        extensionPath: path.join(__dirname, 'plugins/my-plugin/ui'),
                        routes: [
                            {
                                // Setting the prefix to '' means that we won't add the
                                // default `/extensions/` prefix to the route
                                prefix: '',
                                // This part matches the built-in route path for the 
                                // "catalog" module
                                route: 'catalog',
                                filePath: 'routes.ts',
                            },
                        ],
                    },
                ],
            }),
        }),
    ],
};
```

Then in the `routes.ts` file, you can define a route which matches the built-in route:

<Tabs groupId="framework">
<TabItem value="Angular" label="Angular" default>

```ts title="src/plugins/my-plugin/ui/routes.ts"
import { GetProductDetailDocument, registerRouteComponent } from '@vendure/admin-ui/core';
import { MyProductDetailComponent } from './components/product-detail/product-detail.component';

export default [
    registerRouteComponent({
        component: MyProductDetailComponent,
        // The path must then match the remainder
        // of the built-in route path
        path: 'products/:id',
        // We can re-use the GraphQL query from the core to get
        // access to the same data in our component
        query: GetProductDetailDocument,
        entityKey: 'product',
        getBreadcrumbs: entity => [
            { label: 'breadcrumb.products', link: ['/catalog/products'] },
            { label: entity?.name ?? 'catalog.create-new-product', link: ['.'] },
        ],
    }),
];
```

</TabItem>
<TabItem value="React" label="React">

```ts title="src/plugins/my-plugin/ui/routes.ts"
import { GetProductDetailDocument } from '@vendure/admin-ui/core';
import { registerReactRouteComponent } from '@vendure/admin-ui/react';
import { MyProductDetail } from './components/ProductDetail';

export default [
    registerReactRouteComponent({
        component: MyProductDetail,
        // The path must then match the remainder
        // of the built-in route path
        path: 'products/:id',
        // We can re-use the GraphQL query from the core to get
        // access to the same data in our component
        query: GetProductDetailDocument,
        entityKey: 'product',
        getBreadcrumbs: entity => [
            { label: 'breadcrumb.products', link: ['/catalog/products'] },
            { label: entity?.name ?? 'catalog.create-new-product', link: ['.'] },
        ],
    }),
];
```

</TabItem>
</Tabs>

## Advanced configuration

The Admin UI app routing is built on top of the [Angular router](https://angular.io/guide/routing-overview) - a very advanced and robust router. As such, you are able to tap into all the advanced features it provides by using the `routeConfig` property, which takes an Angular [`Route` definition object](https://angular.io/api/router/Route) and passes it directly to the router.

```ts title="src/plugins/my-plugin/ui/routes.ts"
import { registerRouteComponent } from '@vendure/admin-ui/core';
import { inject } from '@angular/core';
import { ActivatedRouteSnapshot } from '@angular/router';
import { TestComponent } from './components/test/test.component';
import { PermissionsService } from './services';

export default [
    registerRouteComponent({
        component: TestComponent,
        path: ':id',
        title: 'Test',
        breadcrumb: 'Test',
        // highlight-start
        routeConfig: {
            pathMatch: 'full',
            canActivate: [(route: ActivatedRouteSnapshot) => {
                return inject(PermissionsService).canActivate(route.params.id);
            }],
        },
        // highlight-end
    }),
];
```

This allows you to leverage advanced features such as:

- [Route guards](https://angular.io/api/router/CanActivateFn)
- [Data resolvers](https://angular.io/api/router/ResolveFn)
- [Nested routes](https://angular.io/guide/router#nesting-routes)
- [Redirects](https://angular.io/guide/router#setting-up-redirects)


---

---
title: 'Getting Started'
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

:::warning Angular Admin UI Deprecation
The Angular-based Admin UI has been replaced by the new [React Admin Dashboard](/guides/extending-the-dashboard/getting-started/). The Angular Admin UI will not be maintained after **July 2026**. Until then, we will continue patching critical bugs and security issues. Community contributions will always be merged and released.

The first stable release of the React Admin Dashboard is targeted for **the end of July 2025**.

**For new projects, we strongly recommend using the [React Admin Dashboard](/guides/extending-the-dashboard/getting-started/) instead.**

If you want to use the Admin UI and the Dashboard together please change the [compatibilityMode](/reference/core-plugins/admin-ui-plugin/admin-ui-plugin-options#compatibilitymode) to true.
:::

When creating a plugin, you may wish to extend the Admin UI in order to expose a graphical interface to the plugin's functionality, or to add new functionality to the Admin UI itself. The UI can be extended with custom components written in [Angular](https://angular.io/) or [React](https://react.dev/).

:::note
The APIs described in this section were introduced in Vendure v2.1.0. For the legacy APIs, see the [Legacy API section](#legacy-api--v210).
:::

UI extensions fall into two categories:

- **Providers**: these are used to add new functionality to the Admin UI, such as adding buttons to pages, adding new nav menu items, or defining custom form inputs. They would typically be defined in a file named `providers.ts`.
- **Routes**: these are used to define new pages in the Admin UI, such as a new page for managing a custom entity. They would typically be defined in a file named `routes.ts`.

## Setup

:::cli
Use `npx vendure add` and select "Set up Admin UI extensions".

If you don't already have any plugins in your project, first create a plugin to house your
UI extensions. Then select:

```sh
[Plugin: UI] Set up Admin UI extensions
```

Then follow the prompts, which will guide you through the process of
setting up the necessary files and folders for your UI extensions.
:::

### Manual setup

It is recommended to use the `vendure add` command as described above, but if you prefer to set up the
Admin UI extensions manually, or just want to get a better understanding of what the CLI is doing, follow these steps:

First, install the [`@vendure/ui-devkit` package](https://www.npmjs.com/package/@vendure/ui-devkit) as a dev dependency:

<Tabs>
<TabItem value="npm" label="npm" default>

```bash
npm install --save-dev @vendure/ui-devkit
```

</TabItem>
<TabItem value="yarn" label="yarn">

```bash
yarn add --dev @vendure/ui-devkit
```

</TabItem>
</Tabs>

:::info
If you plan to use React components in your UI extensions, you should also install the `@types/react` package:

<Tabs>
<TabItem value="npm" label="npm" default>

```bash
npm install --save-dev @types/react
```

</TabItem>
<TabItem value="yarn" label="yarn">

```bash
yarn add --dev @types/react
```

</TabItem>
</Tabs>

:::

You can then create the following folder structure to hold your UI extensions:

```
src
├── vendure-config.ts
└── plugins
    └── my-plugin
        └── ui
            ├── routes.ts
            └── providers.ts
```

Let's add a simple UI extension that adds a new button to the "order list" page. We'll leave the routes file empty for now.

```ts title="src/plugins/my-plugin/ui/providers.ts"
import { addActionBarItem } from '@vendure/admin-ui/core';

export default [
    addActionBarItem({
        id: 'test-button',
        label: 'Test Button',
        locationId: 'order-list',
    }),
];
```

Now we can configure the paths to your UI extension files. By convention, we will add this config object as a
static property on your plugin class:

```ts title="src/plugins/my-plugin/my.plugin.ts"
import * as path from 'path';
import { PluginCommonModule, Type, VendurePlugin } from '@vendure/core';
// highlight-next-line
import { AdminUiExtension } from '@vendure/ui-devkit/compiler';

@VendurePlugin({
    imports: [PluginCommonModule],
    compatibility: '^3.0.0',
})
export class MyPlugin {
    // highlight-start
    static ui: AdminUiExtension = {
        id: 'my-plugin-ui',
        extensionPath: path.join(__dirname, 'ui'),
        routes: [{ route: 'my-plugin', filePath: 'routes.ts' }],
        providers: ['providers.ts'],
    };
    // highlight-end
}
```

You can then use the [`compileUiExtensions` function](/reference/admin-ui-api/ui-devkit/compile-ui-extensions/) to compile your UI extensions and add them to the Admin UI app bundle.

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';
import { AdminUiPlugin } from '@vendure/admin-ui-plugin';
// highlight-next-line
import { compileUiExtensions } from '@vendure/ui-devkit/compiler';
import { MyPlugin } from './plugins/greeter/my.plugin';

export const config: VendureConfig = {
    // ...
    plugins: [
        AdminUiPlugin.init({
            port: 3002,
            // highlight-start
            app: compileUiExtensions({
                outputPath: path.join(__dirname, '../admin-ui'),
                extensions: [MyPlugin.ui],
                devMode: true,
            }),
            // highlight-end
            adminUiConfig: {
                apiPort: 3000,
            },
        }),
    ],
};
```

Everything above will be automatically done for you when you use the CLI.

Now when you start the server, the following will happen:

1. A new folder called `admin-ui` will be created in the root of your project (as specified by the `outputPath` option). This is a temporary directory (it should not be added to version control) which will contain the source files of your custom Admin UI app.
2. During bootstrap, the `compileUiExtensions` function will be called, which will compile the Admin UI app and serve it in development mode. The dev server will be listening on port `4200` but this port will also be proxied to port `3000` (as specified by `apiOptions.port`). This step can take up to a minute or two, depending on the speed of your machine.

:::caution
**Note:** the TypeScript source files of your UI extensions **must not** be compiled by your regular TypeScript build task.
This is because they will instead be compiled by the Angular compiler when you run `compileUiExtensions()`.

You can exclude them in your main `tsconfig.json` by adding a line to the "exclude" array (this is already defined on a default Vendure project):

```json title="tsconfig.json"
{
    "exclude": [
        "node_modules",
        "migration.ts",
        // highlight-start
        "src/plugins/**/ui/*",
        "admin-ui"
        // highlight-end
    ]
}
```

:::

:::info
**How It Works:** The Admin UI is an Angular application, and to generate a custom UI including your extensions, it is internally using the powerful [Angular CLI](https://angular.io/cli) to compile the app into an optimized bundle, including code-splitting and lazy-loading any routes which you define.
:::

## Providers

Your `providers.ts` file exports an array of objects known as "providers" in Angular terminology. These providers are passed to the application on startup to configure new functionality.

With providers you can:

- Add new buttons to the action bar of existing pages (the top bar containing the primary actions for a page) using [`addActionBarItem`](/reference/admin-ui-api/action-bar/add-action-bar-item).
- Add new menu items to the left-hand navigation menu using [`addNavMenuItem`](/reference/admin-ui-api/nav-menu/add-nav-menu-item) and [`addNavMenuSection`](/reference/admin-ui-api/nav-menu/add-nav-menu-section).
- Define bulk actions for list views using [`registerBulkAction`](/reference/admin-ui-api/bulk-actions/register-bulk-action).
- Define arbitrary components to be rendered in a detail view page using [`registerCustomDetailComponent`](/reference/admin-ui-api/custom-detail-components/register-custom-detail-component) or [`registerReactCustomDetailComponent`](/reference/admin-ui-api/react-extensions/register-react-custom-detail-component)
- Add custom widgets to the dashboard using [`registerDashboardWidget`](/reference/admin-ui-api/dashboard-widgets/register-dashboard-widget)
- Define custom components for rendering data table cells using [`registerDataTableComponent`](/reference/admin-ui-api/custom-table-components/register-data-table-component) or [`registerReactDataTableComponent`](/reference/admin-ui-api/react-extensions/register-react-data-table-component)
- Define custom form input components for custom fields and configurable operation arguments using [`registerFormInputComponent`](/reference/admin-ui-api/custom-input-components/register-form-input-component) or [`registerReactFormInputComponent`](/reference/admin-ui-api/react-extensions/register-react-form-input-component)
- Define custom components to render customer/order history timeline entries using [`registerHistoryEntryComponent`](/reference/admin-ui-api/custom-history-entry-components/register-history-entry-component)

### Providers format

A providers file should have a **default export** which is an array of providers:

```ts title="src/plugins/my-plugin/ui/providers.ts"
import { addActionBarItem } from '@vendure/admin-ui/core';

export default [
    addActionBarItem({
        id: 'test-button',
        label: 'Test Button',
        locationId: 'order-list',
    }),
];
```

### Specifying providers

When defining UI extensions in the `compileUiExtensions()` function, you must specify at least one providers file.
This is done by passing an array of file paths, where each file path is relative to the directory specified by the `extensionPath` option.

```ts title="src/vendure-config.ts"
import { compileUiExtensions } from '@vendure/ui-devkit/compiler';
import * as path from 'path';

// ... omitted for brevity

compileUiExtensions({
    outputPath: path.join(__dirname, '../admin-ui'),
    extensions: [
        // Note: this object will usually be
        // found in the `ui` static property
        // of a plugin like `MyPlugin.ui`.
        {
            id: 'test-extension',
            extensionPath: path.join(__dirname, 'plugins/my-plugin/ui'),
            // highlight-next-line
            providers: ['providers.ts'],
        },
    ],
    devMode: true,
});
```

:::info
When running the Admin UI in dev mode, you can use the `ctrl + u` keyboard shortcut to see the location of all UI extension points.

Clicking on an extension point will display a code snippet which you can copy and paste into your `providers.ts` file.

![Provider extension points](./provider-extension-points.webp)
:::

In addition to the specialized UI extension providers listed above, the providers array can also contain any kind of Angular providers which you want to use inside your custom logic. For example, we can define a custom service, add it to the providers array and then consume it from within another provider:

```ts title="src/plugins/my-plugin/ui/providers.ts"
import { Injectable } from '@angular/core';
import { addActionBarItem } from '@vendure/admin-ui/core';

// highlight-start
@Injectable()
class MyService {
    greet() {
        return 'Hello!';
    }
}
// highlight-end

export default [
    MyService,
    addActionBarItem({
        id: 'print-invoice',
        label: 'Print invoice',
        locationId: 'order-detail',
        onClick: (event, context) => {
            // highlight-start
            const myService = context.injector.get(MyService);
            console.log(myService.greet());
            // logs "Hello!"
            // highlight-end
        },
    }),
];
```

## Routes

Routes allow you to define completely custom views in the Admin UI.

![Custom route](../defining-routes/route-area.webp)

Your `routes.ts` file exports an array of objects which define new routes in the Admin UI. For example, imagine you have created a plugin which implements a simple content management system. You can define a route for the list of articles, and another for the detail view of an article.

For a detailed instructions, see the [Defining Routes guide](/guides/extending-the-admin-ui/defining-routes/).

## Dev vs Prod mode

When you are developing your Admin UI extension, you can set the `devMode` option to `true` which will compile the Admin UI app in development mode, and recompile and auto-refresh the browser on any changes to your extension source files.

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';
import { AdminUiPlugin } from '@vendure/admin-ui-plugin';
import { compileUiExtensions } from '@vendure/ui-devkit/compiler';
import * as path from 'path';

export const config: VendureConfig = {
    // ...
    plugins: [
        AdminUiPlugin.init({
            port: 3002,
            app: compileUiExtensions({
                outputPath: path.join(__dirname, '../admin-ui'),
                extensions: [
                    {
                        // ...
                    },
                ],
                devMode: true,
            }),
        }),
    ],
};
```

## Compiling as a deployment step

Although the examples so far all use the `compileUiExtensions` function in conjunction with the AdminUiPlugin, it is also possible to use it on its own:

```ts title="src/compile-admin-ui.ts"
import { compileUiExtensions } from '@vendure/ui-devkit/compiler';
import * as path from 'path';

compileUiExtensions({
    outputPath: path.join(__dirname, '../admin-ui'),
    extensions: [
        /* ... */
    ],
})
    .compile?.()
    .then(() => {
        process.exit(0);
    });
```

This can then be run from the command line:

<Tabs>
<TabItem value="npm" label="npm" default>

```bash
npx ts-node src/compile-admin-ui.ts
```

</TabItem>
<TabItem value="yarn" label="yarn">

```bash
yarn ts-node src/compile-admin-ui.ts
```

</TabItem>
</Tabs>

Once complete, the production-ready app bundle will be output to `admin-ui/dist/browser`. This method is suitable for a production setup, so that the Admin UI can be compiled ahead-of-time as part of your deployment process. This ensures that your Vendure server starts up as quickly as possible. In this case, you can pass the path of the compiled app to the AdminUiPlugin:

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';
import { AdminUiPlugin } from '@vendure/admin-ui-plugin';
import * as path from 'path';

export const config: VendureConfig = {
    // ...
    plugins: [
        AdminUiPlugin.init({
            port: 3002,
            app: {
                path: path.join(__dirname, '../admin-ui/dist/browser'),
            },
        }),
    ],
};
```

:::info
To compile the angular app ahead of time (for production) and copy the dist folder to
Vendure's output dist folder, include the following commands in your package.json scripts:

```json
{
    "scripts": {
        "copy": "npx copyfiles -u 1 'admin-ui/dist/**/*' dist",
        "build": "tsc && yarn copy",
        "build:admin": "rimraf admin-ui && npx ts-node src/compile-admin-ui.ts"
    }
}
```

"build:admin" will remove the admin-ui folder and run the compileUiExtensions function to generate the admin-ui Angular app.
Make sure to install `copyfiles` before running the "copy" command:

<Tabs>
<TabItem value="npm" label="npm" default>

```bash
npm install copyfiles
```

</TabItem>
<TabItem value="yarn" label="yarn">

```bash
yarn add copyfiles
```

</TabItem>
</Tabs>

:::

## Using other frameworks

While the Admin UI natively supports extensions written with Angular or React, it is still possible to create extensions using other front-end frameworks such as Vue or Solid. Note that creating extensions in this way is much more limited, with only the ability to define new routes, and limited access to internal services such as data fetching and notifications. See [UI extensions in other frameworks](/guides/extending-the-admin-ui/using-other-frameworks/).

## IDE Support

### WebStorm

If you are using Angular in your UI extensions and WebStorm is not recognizing the Angular templates, you can
add an `angular.json` file to the `/src/plugins/<my-plugin>/ui` directory:

```json title="angular.json"
{
    "$schema": "../../../../node_modules/@angular/cli/lib/config/schema.json",
    "version": 1,
    "newProjectRoot": "projects",
    "projects": {
        "ui-extensions": {
            "root": "",
            "sourceRoot": "src",
            "projectType": "application"
        }
    }
}
```

This allows WebStorm's built-in Angular support to recognize the Angular templates in your UI extensions. Note that depending
on your folder structure, you may need to adjust the path to the schema file in the `$schema` property.

### VS Code

If you are using Angular in your UI extensions and VS Code is not recognizing the Angular templates, you can
add an empty `tsconfig.json` file to the `/src/plugins/<my-plugin>/ui` directory:

```json title="tsconfig.json"
{}
```

This works around the fact that your main `tsconfig.json` file excludes the `src/plugins/**/ui` directory,
which would otherwise prevent the Angular Language Service from working correctly.

## Legacy API < v2.1.0

Prior to Vendure v2.1.0, the API for extending the Admin UI was more verbose and less flexible (React components were not supported at all, for instance). This API is still supported, but from v2.1 is marked as deprecated and will be removed in a future major version.

This section describes the legacy API.

### Lazy vs Shared Modules

Angular uses the concept of modules ([NgModules](https://angular.io/guide/ngmodules)) for organizing related code. These modules can be lazily loaded, which means that the code is not loaded when the app starts, but only later once that code is required. This keeps the main bundle small and improves performance.

When creating your UI extensions, you can set your module to be either `lazy` or `shared`. Shared modules are loaded _eagerly_, i.e. their code is bundled up with the main app and loaded as soon as the app loads.

As a rule, modules defining new routes should be lazily loaded (so that the code is only loaded once that route is activated), and modules defining [new navigations items](/guides/extending-the-admin-ui/nav-menu/) and [custom form input](/guides/extending-the-admin-ui/custom-form-inputs/) should be set to `shared`.

:::info
"lazy" modules are equivalent to the new "routes" API, and "shared" modules are equivalent to the new "providers" API. In fact, behind the scenes,
the new APIs are automatically creating these modules for you.
:::

### Example lazy module

Here's a very simple Angular component which displays a greeting:

```ts title="src/plugins/greeter/ui/components/greeter/greeter.component.ts"
import { Component } from '@angular/core';

@Component({
    selector: 'greeter',
    template: `<vdr-page-block
        ><h1>{{ greeting }}</h1></vdr-page-block
    >`,
})
export class GreeterComponent {
    greeting = 'Hello!';
}
```

Next we need to declare an Angular module to house the component:

```ts title="src/plugins/greeter/ui/greeter.module.ts"
import { NgModule } from '@angular/core';
import { RouterModule } from '@angular/router';
import { SharedModule } from '@vendure/admin-ui/core';
import { GreeterComponent } from './greeter.component';

@NgModule({
    imports: [
        SharedModule,
        RouterModule.forChild([
            {
                path: '',
                pathMatch: 'full',
                component: GreeterComponent,
                data: { breadcrumb: 'Greeter' },
            },
        ]),
    ],
    declarations: [GreeterComponent],
})
export class GreeterModule {}
```

:::note
The `SharedModule` should, in general, always be imported by your extension modules. It provides the basic Angular
directives and other common functionality that any extension would require.
:::

Now we need to tell the `compileUiExtensions` function where to find the extension, and which file contains the NgModule itself (since a non-trivial UI extension will likely contain multiple files).

```ts title="src/vendure-config.ts"
import path from 'path';
import { AdminUiPlugin } from '@vendure/admin-ui-plugin';
import { VendureConfig } from '@vendure/core';
import { compileUiExtensions } from '@vendure/ui-devkit/compiler';

export const config: VendureConfig = {
    // ...
    plugins: [
        AdminUiPlugin.init({
            port: 3002,
            app: compileUiExtensions({
                outputPath: path.join(__dirname, '../admin-ui'),
                extensions: [
                    {
                        extensionPath: path.join(__dirname, 'plugins/greeter/ui'),
                        // highlight-start
                        ngModules: [
                            {
                                type: 'lazy',
                                route: 'greet',
                                ngModuleFileName: 'greeter.module.ts',
                                ngModuleName: 'GreeterModule',
                            },
                        ],
                        // highlight-end
                    },
                ],
            }),
        }),
    ],
};
```

### Example shared module

Here's an example of the legacy API for defining a shared module:

```ts title="src/plugins/invoices/ui/invoice-shared.module.ts"
import { NgModule } from '@angular/core';
import { SharedModule, addActionBarItem } from '@vendure/admin-ui/core';

@NgModule({
    imports: [SharedModule],
    providers: [
        addActionBarItem({
            id: 'print-invoice',
            label: 'Print invoice',
            locationId: 'order-detail',
            routerLink: route => {
                const id = route.snapshot.params.id;
                return ['./extensions/order-invoices', id];
            },
            requiresPermission: 'ReadOrder',
        }),
    ],
})
export class InvoiceSharedModule {}
```

```ts title="src/vendure-config.ts"
import path from 'path';
import { AdminUiPlugin } from '@vendure/admin-ui-plugin';
import { VendureConfig } from '@vendure/core';
import { compileUiExtensions } from '@vendure/ui-devkit/compiler';

export const config: VendureConfig = {
    // ...
    plugins: [
        AdminUiPlugin.init({
            port: 3002,
            app: compileUiExtensions({
                outputPath: path.join(__dirname, '../admin-ui'),
                extensions: [
                    {
                        extensionPath: path.join(__dirname, 'plugins/invoices/ui'),
                        // highlight-start
                        ngModules: [
                            {
                                type: 'shared',
                                ngModuleFileName: 'invoice-shared.module.ts',
                                ngModuleName: 'InvoiceSharedModule',
                            },
                        ],
                        // highlight-end
                    },
                ],
            }),
        }),
    ],
};
```

### Migrating to the new API

If you have existing UI extensions written using the legacy API, you can migrate them to the new API as follows:

1. Convert all components to be [standalone components](https://angular.io/guide/standalone-components). Standalone components were introduced in recent versions of Angular and allow components to be defined without the need for a module. To convert an existing component, you need to set `standalone: true` and add an `imports` array containing any components, directives or pipes you are using in that component. Typically, you can import `SharedModule` to get access to all the common Angular directives and pipes, as well as the shared Admin UI components.

```ts
import { Component } from '@angular/core';
// highlight-next-line
import { SharedModule } from '@vendure/admin-ui/core';

@Component({
    selector: 'greeter',
    template: `<vdr-page-block
        ><h1>{{ greeting }}</h1></vdr-page-block
    >`,
    // highlight-start
    standalone: true,
    imports: [SharedModule],
    // highlight-end
})
export class GreeterComponent {
    greeting = 'Hello!';
}
```

2. In templates for page components, remove the `<vdr-page-header>` and `<vdr-page-body>` components, as they are included by default now when using
   the `registeRouteComponent()` function:
    ```html
    // highlight-start
    <vdr-page-header>
        <vdr-page-title></vdr-page-title>
    </vdr-page-header>
    <vdr-page-body>
        // highlight-end
        <vdr-page-block>This content should remain</vdr-page-block>
        // highlight-next-line
    </vdr-page-body>
    ```
3. Remove any `NgModule` files, and replace lazy modules with `routes.ts`, and shared modules with `providers.ts` (see above).


---

---
title: 'Modify the Nav Menu'
weight: 5
---

The Nav Menu is the main navigation for the Admin UI, located on the left-hand side when in desktop mode. It is used to provide top-level
access to routes in the app, and can be extended and modified by UI extensions.

## Extending the NavMenu

Once you have defined some custom routes, you need some way for the administrator to access them. For this you will use the [addNavMenuItem](/reference/admin-ui-api/nav-menu/add-nav-menu-item/) and [addNavMenuSection](/reference/admin-ui-api/nav-menu/add-nav-menu-section) functions.

Let's add a new section to the Admin UI main nav bar containing a link to the "greeter" module from the [Getting Started guide](/guides/extending-the-admin-ui/getting-started/#routes) example:

```ts title="src/plugins/greeter/ui/providers.ts"
import { addNavMenuSection } from '@vendure/admin-ui/core';

export default [
    addNavMenuSection({
        id: 'greeter',
        label: 'My Extensions',
        items: [{
            id: 'greeter',
            label: 'Greeter',
            routerLink: ['/extensions/greet'],
            // Icon can be any of https://core.clarity.design/foundation/icons/shapes/
            icon: 'cursor-hand-open',
        }],
    },
    // Add this section before the "settings" section
    'settings'),
];
```

Now we must also register these providers with the compiler:

```ts title="src/vendure-config.ts"
import path from 'path';
import { VendureConfig } from '@vendure/core';
import { AdminUiPlugin } from '@vendure/admin-ui-plugin';
import { compileUiExtensions } from '@vendure/ui-devkit/compiler';

export const config: VendureConfig = {
    // ...
    plugins: [
        AdminUiPlugin.init({
            port: 3002,
            app: compileUiExtensions({
                outputPath: path.join(__dirname, '../admin-ui'),
                extensions: [
                    {
                        id: 'greeter',
                        extensionPath: path.join(__dirname, 'plugins/greeter/ui'),
                        routes: [{ route: 'greet', filePath: 'routes.ts' }],
                        // highlight-start
                        providers: ['providers.ts']
                        // highlight-end
                    },
                ],
            }),
        }),
    ],
};
```

Running the server will compile our new shared module into the app, and the result should look like this:

![./ui-extensions-navbar.webp](./ui-extensions-navbar.webp)

## Overriding existing nav items

It is also possible to override one of the default (built-in) nav menu sections or items. This can be useful for example if you wish to provide a completely different implementation of the product list view.

This is done by setting the `id` property to that of an existing nav menu section or item. The `id` can be found by inspecting the link element in your browser's dev tools for the `data-item-id` attribute:

![Navbar menu id](./nav-menu-id.webp)

## Removing existing nav items

If you would like to remove an existing nav item, you can do so by overriding it and setting the `requiresPermission` property to an invalid value:

```ts title="src/plugins/greeter/ui/providers.ts"
import { SharedModule, addNavMenuItem} from '@vendure/admin-ui/core';

export default [
    addNavMenuItem({
        id: 'collections',  // <-- we will override the "collections" menu item
        label: 'Collections',
        routerLink: ['/catalog', 'collections'],
        // highlight-start
        // we use an invalid permission which ensures it is hidden from all users
        requiresPermission: '__disable__'
        // highlight-end
    },
    'catalog'),
];
```


---

---
title: 'Page Tabs'
weight: 5
---

You can add your own tabs to any of the Admin UI's list or detail pages using the [registerPageTab](/reference/admin-ui-api/tabs/register-page-tab/) function. For example, to add a new tab to the product detail page for displaying product reviews:

```ts title="src/plugins/reviews/ui/providers.ts"
import { registerPageTab } from '@vendure/admin-ui/core';

import { ReviewListComponent } from './components/review-list/review-list.component';

export default [
    registerPageTab({
        location: 'product-detail',
        tab: 'Reviews',
        route: 'reviews',
        tabIcon: 'star',
        component: ReviewListComponent,
    }),
];
```

![./ui-extensions-tabs.webp](./ui-extensions-tabs.webp)

If you want to add page tabs to a custom admin page, specify the `locationId` property:

```ts title="src/plugins/my-plugin/ui/routes.ts"
import { registerRouteComponent } from '@vendure/admin-ui/core';
import { TestComponent } from './components/test/test.component';

export default [
    registerRouteComponent({
        component: TestComponent,
        title: 'Test',
        // highlight-next-line
        locationId: 'my-location-id'
    }),
];
```

:::note
Currently it is only possible to define new tabs using Angular components.
:::


---

---
title: "UI Component Library"
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

The Admin UI is built on a customized version of the [Clarity Design System](https://clarity.design/documentation/get-started). This means that if you are writing Angular-based UI extensions, you can use the same components that are used in the rest of the Admin UI. If you are using React, we are gradually exporting the most-used components for use with React.

## Buttons

![Buttons](./buttons.webp)

There are three types of button:

- **Regular**: These are general-purpose buttons available in a number of styles. They are used in the action bar and as confirmation buttons for dialogs.
- **Ghost**: This style is primarily used to indicate a column in a table which is a link to a detail view.
- **Small**: This style is used for secondary actions of less prominence than a standard button, or when the button must fit in a small space.


<Tabs groupId="framework">
<TabItem value="Angular" label="Angular" default>


```html
<button class="button primary">Primary</button>
<button class="button secondary">Secondary</button>
<button class="button success">Success</button>
<button class="button warning">Warning</button>
<button class="button danger">Danger</button>

<button class="button-ghost">Ghost</button>
<a class="button-ghost" [routerLink]="['/extensions/my-plugin/my-custom-route']">
    <clr-icon shape="arrow" dir="right"></clr-icon>
    John Smith
</a>

<button class="button-small">Small</button>
<button class="button-small">
    <clr-icon shape="layers"></clr-icon>
    Assign to channel
</button>
```

</TabItem>
<TabItem value="React" label="React">

```tsx
import React from 'react';
import { CdsIcon, Link } from '@vendure/admin-ui/react';

export function DemoComponent() {
    return (
        <>
            <button className="button primary">Primary</button>
            <button className="button secondary">Secondary</button>
            <button className="button success">Success</button>
            <button className="button warning">Warning</button>
            <button className="button danger">Danger</button>
            
            <button className="button-ghost">Ghost</button>
            <Link className="button-ghost" href="/extensions/my-plugin/my-custom-route">
                <CdsIcon icon={arrowIcon} direction="right" />
                John Smith
            </Link>
            
            <button className="button-small">Small</button>
            <button className="button-small">
                <CdsIcon icon={layersIcon} />
                Assign to channel
            </button>
        </>
    );
}
```

</TabItem>
</Tabs>


## Icons

You can use the built-in [Clarity Icons](https://core.clarity.design/foundation/icons/shapes/) for a consistent look-and-feel with the rest of the 
Admin UI app.

![Icons](./icons.webp)



<Tabs groupId="framework">
<TabItem value="Angular" label="Angular" default>


```html
<clr-icon shape="star" size="8"></clr-icon>
<clr-icon shape="star" size="16"></clr-icon>
<clr-icon shape="star" size="24"></clr-icon>
<clr-icon shape="star" size="36"></clr-icon>
<clr-icon shape="star" size="48"></clr-icon>
<clr-icon shape="star" size="56"></clr-icon>

<clr-icon shape="user" class="has-badge--success"></clr-icon>
<clr-icon shape="user" class="has-alert"></clr-icon>
<clr-icon shape="user" class="has-badge--info"></clr-icon>
<clr-icon shape="user" class="has-badge--error"></clr-icon>

<clr-icon shape="user" class="is-success"></clr-icon>
<clr-icon shape="user" class="is-info"></clr-icon>
<clr-icon shape="user" class="is-warning"></clr-icon>
<clr-icon shape="user" class="is-error"></clr-icon>
```

</TabItem>
<TabItem value="React" label="React">

```tsx
import React from 'react';
import { starIcon, userIcon } from '@cds/core/icon';
import { CdsIcon } from '@vendure/admin-ui/react';

export function DemoComponent() {
    return (
        <>
            <CdsIcon icon={starIcon} size="xs" />
            <CdsIcon icon={starIcon} size="sm" />
            <CdsIcon icon={starIcon} size="md" />
            <CdsIcon icon={starIcon} size="lg" />
            <CdsIcon icon={starIcon} size="xl" />
            <CdsIcon icon={starIcon} size="xxl" />
            
            <CdsIcon icon={userIcon} badge="success" />
            <CdsIcon icon={userIcon} badge="info" />
            <CdsIcon icon={userIcon} badge="warning" />
            <CdsIcon icon={userIcon} badge="danger" />
            
            <CdsIcon icon={userIcon} status="success" />
            <CdsIcon icon={userIcon} status="info" />
            <CdsIcon icon={userIcon} status="warning" />
            <CdsIcon icon={userIcon} status="danger" />
        </>
    );
}
```

</TabItem>
</Tabs>

## Form inputs

Form inputs are styled globally, so you don't need to use special components for these. The label & tooltip styling is controlled by the
"form field" wrapper component.

![Form input](./form-inputs.webp)


<Tabs groupId="framework">
<TabItem value="Angular" label="Angular" default>


```html
<div class="form-grid">
    <vdr-form-field label="Page title">
        <input type="text" />
    </vdr-form-field>
    <vdr-form-field label="Select input">
        <select>
            <option>Option 1</option>
            <option>Option 2</option>
        </select>
    </vdr-form-field>
    <vdr-form-field label="Checkbox input">
        <input type="checkbox" />
    </vdr-form-field>
    <vdr-form-field label="Textarea input">
        <textarea></textarea>
    </vdr-form-field>
    <vdr-form-field label="With tooltip" tooltip="This is a tooltip for the form input">
        <input type="text" />
    </vdr-form-field>
    <vdr-form-field label="Invalid with error">
        <input type="text" [formControl]="invalidFormControl" />
    </vdr-form-field>
    <vdr-rich-text-editor
        class="form-grid-span"
        label="Description"
    ></vdr-rich-text-editor>
</div>
```

</TabItem>
<TabItem value="React" label="React">

```tsx
import React from 'react';
import { starIcon, userIcon } from '@cds/core/icon';
import { FormField, RichTextEditor } from '@vendure/admin-ui/react';

export function DemoComponent() {
    return (
        <div className="form-grid">
            <FormField label="Page title">
                <input type="text" />
            </FormField>
            <FormField label="Select input">
                <select>
                    <option>Option 1</option>
                    <option>Option 2</option>
                </select>
            </FormField>
            <FormField label="Checkbox input">
                <input type="checkbox" />
            </FormField>
            <FormField label="Textarea input">
                <textarea />
            </FormField>
            <FormField label="With tooltip" tooltip="This is a tooltip for the form input">
                <input type="text" />
            </FormField>
            <FormField label="Invalid with error" invalid>
                <input type="text" />
            </FormField>
            <RichTextEditor className="form-grid-span" label="Description" readOnly={false} />
        </div>
    );
}
```

</TabItem>
</Tabs>

The `form-grid` class is used to lay out the form fields into a 2-column grid on larger screens, and a single column on smaller screens.
If you want to force a particular field to always take up the full width (i.e. to span 2 columns at all screen sizes), you can add the
`form-grid-span` class to that form field.

```html
<div class="form-grid">
    // highlight-next-line
    <vdr-form-field label="Page title" class="form-grid-span">
        <input type="text" />
    </vdr-form-field>
</div>
```

## Cards

Cards are used as a general-purpose container for page content, as a way to visually group related sets of components.

![Card](./card.webp)


<Tabs groupId="framework">
<TabItem value="Angular" label="Angular" default>


```html
<vdr-card title="Card">
    This is a card. On a detail page, content should usually be placed inside a card.
</vdr-card>
```

</TabItem>
<TabItem value="React" label="React">

```tsx
import React from 'react';
import { Card } from '@vendure/admin-ui/react';

export function DemoComponent() {
    return (
        <Card title="Card">
            This is a card. On a detail page, content should usually be placed inside a card.
        </Card>
    );
}
```

</TabItem>
</Tabs>

## Layout

The following layout components are available:

- Page block: This is a wrapper which applies consistent margins and max-width to the contents of the page. In general, the contents of a page should always be wrapped in this component except when using the DataTable2 component, which has its own styling for margins and width.
- Action bar: This is a wrapper for the top area of the page, just below the header section. This is where the primary action buttons for the page should be located.
- Page detail layout: For detail views, this wrapper provides a two-column layout with a main content area and a sidebar.

![Layout](./layout.webp)


<Tabs groupId="framework">
<TabItem value="Angular" label="Angular" default>


```html
<vdr-page-block>
    <vdr-action-bar>
        <vdr-ab-left>Action bar left contents</vdr-ab-left>
        <vdr-ab-right>
            <button class="button primary">Primary action</button>
        </vdr-ab-right>
    </vdr-action-bar>
</vdr-page-block>
<vdr-page-detail-layout>
    <vdr-page-detail-sidebar>
        <vdr-card>Sidebar content</vdr-card>
    </vdr-page-detail-sidebar>
    <vdr-page-block>
        <vdr-card title="Card">
            This is a card. On a detail page, content should usually be placed inside a card.
        </vdr-card>
    </vdr-page-block>
</vdr-page-detail-layout>
```

</TabItem>
<TabItem value="React" label="React">

```tsx
import React from 'react';
import { 
    ActionBar,
    Card,
    PageBlock,
    PageDetailLayout,
} from '@vendure/admin-ui/react';

export function DemoComponent() {
    return (
        <>
            <PageBlock>
                <ActionBar leftContent={<div>Action bar left contents</div>}>
                    <button className="button primary">Primary action</button>
                </ActionBar>
            </PageBlock>

            <PageDetailLayout
                sidebar={
                    <div>
                        <Card>Sidebar content</Card>
                    </div>
                }
            >
                <PageBlock>
                    <Card title="Card">
                        This is a card. On a detail page, content should usually be placed inside a card.
                    </Card>
                </PageBlock>
            </PageDetailLayout>
        </>
    );
}
```

</TabItem>
</Tabs>


---

---
title: 'Using Other Frameworks'
weight: 1
---

From version 2.1.0, Admin UI extensions can be written in either Angular or React. Prior to v2.1.0, only Angular was natively supported. 

It is, however, possible to extend the Admin UI using other frameworks such as Vue, Svelte, Solid etc. Note that the extension experience is much more limited than with Angular or React, but depending on your needs it may be sufficient.

:::info
For working examples of a UI extensions built with **Vue**, see the [real-world-vendure ui extensions](https://github.com/vendure-ecommerce/real-world-vendure/tree/master/src/ui-extensions)
:::

There is still a small amount of Angular "glue code" needed to let the compiler know how to integrate your extension, so let's take a look at how this is done.

## 1. Install `@vendure/ui-devkit`

To create UI extensions, you'll need to install the `@vendure/ui-devkit` package. This package contains a compiler for building your customized version of the Admin UI, as well as the Angular dependencies you'll need to create your extensions.

```bash
yarn add @vendure/ui-devkit

# or

npm install @vendure/ui-devkit
```

## 2. Create the folder structure

In this example, we will work with the following folder structure, and use Create React App our example.

```text
src
└─plugins
  └─ my-plugin
    └─ ui
      ├─ routes.ts
      └─ vue-app
        └─ (directory created by `vue create`, for example)
```

## 3. Create an extension module

Here's the Angular code needed to tell the compiler where to find your extension:

```ts title="src/plugins/my-plugin/ui/routes.ts"
import { hostExternalFrame } from '@vendure/admin-ui/core';

export default [
    hostExternalFrame({
        path: '',

        // You can also use parameters which allow the app
        // to have dynamic routing, e.g.
        // path: ':slug'
        // Then you can use the getActivatedRoute() function from the
        // UiDevkitClient in order to access the value of the "slug"
        // parameter.

        breadcrumbLabel: 'Vue App',
        // This is the URL to the compiled React app index.
        // The next step will explain the "assets/react-app" path.
        extensionUrl: './assets/vue-app/index.html',
        openInNewTab: false,
    })
];
```

## 4. Define the AdminUiExtension config

Next we will define an [AdminUiExtension](/reference/admin-ui-api/ui-devkit/admin-ui-extension/) object which is passed to the `compileUiExtensions()` function in your Vendure config:

```ts title="src/vendure-config.ts"
import path from 'path';
import { VendureConfig } from '@vendure/core';
import { AdminUiPlugin } from '@vendure/admin-ui-plugin';
import { compileUiExtensions } from '@vendure/ui-devkit/compiler';

export const config: VendureConfig = {
    // ...
    plugins: [
        AdminUiPlugin.init({
            route: 'admin',
            port: 3002,
            app: compileUiExtensions({
                outputPath: path.join(__dirname, '../admin-ui'),
                extensions: [{
                    // Points to the path containing our Angular "glue code" module
                    extensionPath: path.join(__dirname, 'plugins/my-plugin/ui'),
                    routes: [{ route: 'vue-ui', filePath: 'routes.ts' }],
                    staticAssets: [
                        // This is where we tell the compiler to copy the compiled Vue app
                        // artifacts over to the Admin UI's `/static` directory. In this case we
                        // also rename "build" to "vue-app". This is why the `extensionUrl`
                        // in the module config points to './assets/vue-app/index.html'.
                        {path: path.join(__dirname, 'plugins/my-plugin/ui/vue-app/dist'), rename: 'vue-app'},
                    ],
                }],
                devMode: true,
            }),
        }),
    ]
};
```

## 5. Build your extension

To ensure things are working we can now build our Vue app by running `yarn build` in the `vue-app` directory. This will build and output the app artifacts to the `vue-app/build` directory - the one we pointed to in the `staticAssets` array above.

Once build, we can start the Vendure server.

The `compileUiExtensions()` function returns a `compile()` function which will be invoked by the AdminUiPlugin upon server bootstrap. During this compilation process, a new directory will be generated at `/admin-ui` (as specified by the `outputPath` option) which will contains the un-compiled sources of your new Admin UI app.

Next, these source files will be run through the Angular compiler, the output of which will be visible in the console.

Now go to the Admin UI app in your browser and log in. You should now be able to manually enter the URL `http://localhost:3000/admin/extensions/vue-ui` and you should see the Vue app rendered in the Admin UI.

## Integrate with the Admin UI

### Styling
The `@vendure/admin-ui` package (which will be installed alongside the ui-devkit) provides a stylesheet to allow your extension to fit visually with the rest of the Admin UI.

If you have a build step, you can import it into your app like this:

```ts
import '@vendure/admin-ui/static/theme.min.css';
```

If your extension does not have a build step, you can still include the theme stylesheet as a local resource:

```HTML
<!-- src/ui-extension/plain-js-app/index.html -->
<head>
  <link rel="stylesheet" href="../../theme.min.css" />
</head>
```

### UiDevkitClient

The `@vendure/ui-devkit` package provides a number of helper methods which allow your extension to seamlessly interact with the underlying Admin UI infrastructure, collectively known as the [UiDevkitClient](/reference/admin-ui-api/ui-devkit/ui-devkit-client/). The client allows your extension to:

* Make GraphQL queries & mutations, without the need for your own HTTP or GraphQL client, with full integration with the Admin UI client-side GraphQL cache.
* Display toast notifications.

#### setTargetOrigin

The UiDevkitClient uses the browser's [postMessage API](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) to communicate between the Admin UI app and your extension. For security reasons this communication channel is restricted to a specific domain (where your extension app will be running from). To configure this, use the [setTargetOrigin](/reference/admin-ui-api/ui-devkit/ui-devkit-client/#settargetorigin) function:

```ts
import { setTargetOrigin } from '@vendure/ui-devkit';

setTargetOrigin('http://my-domain.com');

```

If this is mis-configured you will see an error along the lines of "Failed to execute 'postMessage' on 'DOMWindow'".

For apps with a build step, you can use these functions like this:

```ts
import { graphQlMutation, notify } from '@vendure/ui-devkit';

// somewhere in your component
const disableProduct = (id: string) => {
  graphQlMutation(`
    mutation DisableProduct($id: ID!) {
      updateProduct(input: { id: $id, enabled: false }) {
        id
        enabled
      }
    }`, { id }).then(result => {
     notify({
       message: 'Updated Product',
     });
  })
}
```

If your extension does not have a build step, you can still include the UiDevkitClient as a local resource, which will expose a `VendureUiClient` global object:

```html
<!-- src/ui-extension/plain-js-app/index.html -->
<head>
  <script src="../devkit/ui-devkit.js"></script>
</head>
<script>
  const disableProduct = id => {
    VendureUiClient.graphQlMutation(`
      mutation DisableProduct($id: ID!) {
        updateProduct(input: { id: $id, enabled: false }) {
          id
          enabled
        }
      }`, { id }).then(result => {
       VendureUiClient.notify({
         message: 'Updated Product',
       });
    })
  }
</script>
```

## Next Steps

Now you have created your extension, you need a way for your admin to access it. See [Adding Navigation Items](/guides/extending-the-admin-ui/nav-menu/)


---

---
title: 'Action Bar Items'
---

Like in the old Admin UI, we have the concept of the "action bar", which is the bar at the top of the page where you can add
buttons and other actions.

Currently, we only support adding buttons, but dropdown menu support is coming soon.

## Basic Action Bar Item

Here's a simple example of adding a button to the action bar:

```tsx title="src/plugins/my-plugin/dashboard/index.tsx"
import { Button, defineDashboardExtension } from '@vendure/dashboard';
import { useState } from 'react';

export default defineDashboardExtension({
    actionBarItems: [
        {
            pageId: 'product-detail',
            component: ({ context }) => {
                const [count, setCount] = useState(0);
                return (
                    <Button type="button" variant="secondary" onClick={() => setCount(x => x + 1)}>
                        Counter: {count}
                    </Button>
                );
            },
        },
    ],
});
```

## Context Data

The `context` prop provides access to:

- **`entity`**: The current entity being viewed/edited (e.g., Product, Customer, etc.)
- **`form`**: The React Hook Form instance for the current page (if applicable)
- **`route`**: Route information and parameters

## Practical Examples

### Export Button

```tsx title="src/plugins/my-plugin/dashboard/index.tsx"
import { Button, defineDashboardExtension } from '@vendure/dashboard';
import { DownloadIcon } from 'lucide-react';

export default defineDashboardExtension({
    actionBarItems: [
        {
            pageId: 'product-detail',
            component: ({ context }) => {
                const product = context.entity;

                const handleExport = async () => {
                    // Export product data
                    const data = JSON.stringify(product, null, 2);
                    const blob = new Blob([data], { type: 'application/json' });
                    const url = URL.createObjectURL(blob);

                    const a = document.createElement('a');
                    a.href = url;
                    a.download = `product-${product.id}.json`;
                    a.click();

                    URL.revokeObjectURL(url);
                };

                return (
                    <Button variant="outline" onClick={handleExport} disabled={!product}>
                        <DownloadIcon className="mr-2 h-4 w-4" />
                        Export
                    </Button>
                );
            },
        },
    ],
});
```

### Sync Button with Loading State

```tsx title="src/plugins/my-plugin/dashboard/index.tsx"
import { Button, defineDashboardExtension } from '@vendure/dashboard';
import { RefreshCwIcon } from 'lucide-react';
import { useState } from 'react';
import { toast } from 'sonner';

export default defineDashboardExtension({
    actionBarItems: [
        {
            pageId: 'product-detail',
            component: ({ context }) => {
                const [isSyncing, setIsSyncing] = useState(false);
                const product = context.entity;

                const handleSync = async () => {
                    if (!product) return;

                    setIsSyncing(true);
                    try {
                        // Simulate API call to external system
                        await fetch(`/api/sync-product/${product.id}`, {
                            method: 'POST',
                        });
                        toast.success('Product synced successfully');
                    } catch (error) {
                        toast.error('Failed to sync product');
                    } finally {
                        setIsSyncing(false);
                    }
                };

                return (
                    <Button variant="outline" onClick={handleSync} disabled={!product || isSyncing}>
                        <RefreshCwIcon className={`mr-2 h-4 w-4 ${isSyncing ? 'animate-spin' : ''}`} />
                        {isSyncing ? 'Syncing...' : 'Sync to ERP'}
                    </Button>
                );
            },
        },
    ],
});
```

### Conditional Action Bar Items

You can conditionally show action bar items based on the entity or user permissions:

```tsx title="src/plugins/my-plugin/dashboard/index.tsx"
import { Button, defineDashboardExtension, PermissionGuard } from '@vendure/dashboard';
import { SendIcon } from 'lucide-react';

export default defineDashboardExtension({
    actionBarItems: [
        {
            pageId: 'customer-detail',
            component: ({ context }) => {
                const customer = context.entity;

                // Only show for customers with email addresses
                if (!customer?.emailAddress) {
                    return null;
                }

                const handleSendEmail = () => {
                    // Open email composer or trigger email send
                    console.log('Sending email to:', customer.emailAddress);
                };

                return (
                    <PermissionGuard requires={['UpdateCustomer']}>
                        <Button variant="outline" onClick={handleSendEmail}>
                            <SendIcon className="mr-2 h-4 w-4" />
                            Send Email
                        </Button>
                    </PermissionGuard>
                );
            },
        },
    ],
});
```

## Multiple Action Bar Items

You can add multiple action bar items to the same page:

```tsx title="src/plugins/my-plugin/dashboard/index.tsx"
import { Button, defineDashboardExtension } from '@vendure/dashboard';
import { DownloadIcon, RefreshCwIcon, SendIcon } from 'lucide-react';

export default defineDashboardExtension({
    actionBarItems: [
        {
            pageId: 'product-detail',
            component: ({ context }) => (
                <Button variant="outline">
                    <DownloadIcon className="mr-2 h-4 w-4" />
                    Export
                </Button>
            ),
        },
        {
            pageId: 'product-detail',
            component: ({ context }) => (
                <Button variant="outline">
                    <RefreshCwIcon className="mr-2 h-4 w-4" />
                    Sync
                </Button>
            ),
        },
        {
            pageId: 'product-detail',
            component: ({ context }) => (
                <Button variant="outline">
                    <SendIcon className="mr-2 h-4 w-4" />
                    Share
                </Button>
            ),
        },
    ],
});
```

## Available Button Variants

The dashboard provides several button variants you can use:

- `default` - Primary button style
- `secondary` - Secondary button style
- `outline` - Outlined button style
- `ghost` - Minimal button style
- `destructive` - For destructive actions (delete, etc.)

```tsx
<Button variant="default">Primary</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="outline">Outline</Button>
<Button variant="ghost">Ghost</Button>
<Button variant="destructive">Delete</Button>
```

## Best Practices

1. **Use appropriate icons**: Icons help users quickly understand the action
2. **Provide loading states**: Show loading indicators for async operations
3. **Handle errors gracefully**: Use toast notifications for feedback
4. **Consider permissions**: Use `PermissionGuard` for actions that require specific permissions
5. **Keep labels concise**: Use short, descriptive labels for buttons
6. **Group related actions**: Consider the order and grouping of multiple action items
7. **Test thoroughly**: Verify your actions work correctly across different entity states

## Finding Page IDs

To find the `pageId` for your action bar items:

1. Enable [Dev Mode](/guides/extending-the-dashboard/extending-overview/#dev-mode) in the dashboard
2. Navigate to the page where you want to add your action
3. The page ID will be shown in the dev mode overlay
4. Use this ID in your action bar item configuration


---

---
title: 'Tutorial: Building a CMS Plugin'
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Follow this guide to see how to extend the dashboard with custom pages, blocks, and components.

We will create a brand new `CmsPlugin` that implements a simple content management system (CMS) for Vendure in
order to demonstrate how to extend the dashboard.

## Creating the plugin

Let's create the plugin:

```bash
npx vendure add --plugin cms
```

Now let's add an entity to the plugin:

```bash
npx vendure add --entity Article --selected-plugin CmsPlugin
```

You now have your `CmsPlugin` created with a new `Article` entity. You can find the plugin in the `./src/plugins/cms` directory.

Let's edit the entity to add the appropriate fields:

```ts title="src/plugins/cms/entities/article.entity.ts"
import { DeepPartial, HasCustomFields, VendureEntity } from '@vendure/core';
import { Column, Entity } from 'typeorm';

export class ArticleCustomFields {}

@Entity()
export class Article extends VendureEntity implements HasCustomFields {
    constructor(input?: DeepPartial<Article>) {
        super(input);
    }

    @Column()
    slug: string;

    @Column()
    title: string;

    @Column('text')
    body: string;

    @Column()
    isPublished: boolean;

    @Column(type => ArticleCustomFields)
    customFields: ArticleCustomFields;
}
```

Now let's create a new `ArticleService` to handle the business logic of our new entity:

```bash
npx vendure add --service ArticleService --selected-plugin CmsPlugin --selected-entity Article
```

The service will be created in the `./src/plugins/cms/services` directory.

Finally, we'll extend the GraphQL API to expose those CRUD operations:

```bash
npx vendure add --api-extension CmsPlugin --selected-service ArticleService --query-name ArticleQuery
```

Now the api extensions and resolver has been created in the `./src/plugins/cms/api-extensions` directory.

The last step is to create a migration for our newly-created entity:

```bash
npx vendure migrate --generate article
```

## Setting up Dashboard extensions

Dashboard extensions are declared directly on the plugin metadata. Unlike the old AdminUiPlugin, you do not need to separately
declare ui extensions anywhere except on the plugin itself.

```ts title="src/plugins/cms/cms.plugin.ts"
@VendurePlugin({
    // ...
    entities: [Article],
    adminApiExtensions: {
        schema: adminApiExtensions,
        resolvers: [ArticleAdminResolver],
    },
    // highlight-next-line
    dashboard: './dashboard/index.tsx',
})
export class CmsPlugin {
    // ...
}
```

Now we'll create the entry point of our dashboard extension:

```tsx title="src/plugins/cms/dashboard/index.tsx"
import { defineDashboardExtension } from '@vendure/dashboard';

export default defineDashboardExtension({
    // Let's add a simple test page to check things are working
    routes: [
        {
            component: () => <div>Test Page Works!</div>,
            path: '/test',
            navMenuItem: {
                id: 'test',
                title: 'Test Page',
                sectionId: 'catalog',
            },
        },
    ],
});
```

Restart the Vite server (`q, enter` to quit if still running), and then you should be able to see your new test page!

![Test Page](../getting-started/test-page.webp)

## Creating a list page

Now that the test page is working, let's create a list page for our `Article` entity.

First we'll create a new `article-list.tsx` file in the `./src/plugins/cms/dashboard` directory:

```tsx title="src/plugins/cms/dashboard/article-list.tsx"
import {
    Button,
    DashboardRouteDefinition,
    ListPage,
    PageActionBarRight,
    DetailPageButton,
} from '@vendure/dashboard';
import { Link } from '@tanstack/react-router';
import { PlusIcon } from 'lucide-react';

// This function is generated for you by the `vendureDashboardPlugin` in your Vite config.
// It uses gql-tada to generate TypeScript types which give you type safety as you write
// your queries and mutations.
import { graphql } from '@/gql';

// The fields you select here will be automatically used to generate the appropriate columns in the
// data table below.
const getArticleList = graphql(`
    query GetArticles($options: ArticleListOptions) {
        articles(options: $options) {
            items {
                id
                createdAt
                updatedAt
                isPublished
                title
                slug
                body
                customFields
            }
        }
    }
`);

const deleteArticleDocument = graphql(`
    mutation DeleteArticle($id: ID!) {
        deleteArticle(id: $id) {
            result
        }
    }
`);

export const articleList: DashboardRouteDefinition = {
    navMenuItem: {
        sectionId: 'catalog',
        id: 'articles',
        url: '/articles',
        title: 'CMS Articles',
    },
    path: '/articles',
    loader: () => ({
        breadcrumb: 'Articles',
    }),
    component: route => (
        <ListPage
            pageId="article-list"
            title="Articles"
            listQuery={getArticleList}
            deleteMutation={deleteArticleDocument}
            route={route}
            customizeColumns={{
                title: {
                    cell: ({ row }) => {
                        const post = row.original;
                        return <DetailPageButton id={post.id} label={post.title} />;
                    },
                },
            }}
        >
            <PageActionBarRight>
                <Button asChild>
                    <Link to="./new">
                        <PlusIcon className="mr-2 h-4 w-4" />
                        New article
                    </Link>
                </Button>
            </PageActionBarRight>
        </ListPage>
    ),
};
```

Let's register this route (and we can also remove the test page) in our `index.tsx` file:

```tsx title="src/plugins/cms/dashboard/index.tsx"
import { defineDashboardExtension } from '@vendure/dashboard';

// highlight-next-line
import { articleList } from './article-list';

export default defineDashboardExtension({
    routes: [
        // highlight-next-line
        articleList,
    ],
});
```

You should now be able to see the list view, which will be empty:

![Empty List](../getting-started/list-view-empty.webp)

## Creating a detail page

Now let's create a detail page so we can start adding articles.

We'll begin with the simplest approach, where the form will be auto-generated for us based on the GraphQL schema
using the [DetailPage](/reference/dashboard/components/detail-page) component.
This is useful for quickly getting started, but you will probably want to customize the form later on.

Create a new file called `article-detail.tsx` in the `./src/plugins/cms/dashboard` directory:

```tsx title="src/plugins/cms/dashboard/article-detail.tsx"
import { DashboardRouteDefinition, DetailPage, detailPageRouteLoader } from '@vendure/dashboard';
import { graphql } from '@/gql';

const articleDetailDocument = graphql(`
    query GetArticleDetail($id: ID!) {
        article(id: $id) {
            id
            createdAt
            updatedAt
            isPublished
            title
            slug
            body
            customFields
        }
    }
`);

const createArticleDocument = graphql(`
    mutation CreateArticle($input: CreateArticleInput!) {
        createArticle(input: $input) {
            id
        }
    }
`);

const updateArticleDocument = graphql(`
    mutation UpdateArticle($input: UpdateArticleInput!) {
        updateArticle(input: $input) {
            id
        }
    }
`);

export const articleDetail: DashboardRouteDefinition = {
    path: '/articles/$id',
    loader: detailPageRouteLoader({
        queryDocument: articleDetailDocument,
        breadcrumb: (isNew, entity) => [
            { path: '/articles', label: 'Articles' },
            isNew ? 'New article' : entity?.title,
        ],
    }),
    component: route => {
        return (
            <DetailPage
                pageId="article-detail"
                queryDocument={articleDetailDocument}
                createDocument={createArticleDocument}
                updateDocument={updateArticleDocument}
                route={route}
                title={article => article?.title ?? 'New article'}
                setValuesForUpdate={article => {
                    return {
                        id: article?.id ?? '',
                        isPublished: article?.isPublished ?? false,
                        title: article?.title ?? '',
                        slug: article?.slug ?? '',
                        body: article?.body ?? '',
                    };
                }}
            />
        );
    },
};
```

Now we can register this route in our `index.tsx` file:

```tsx title="src/plugins/cms/dashboard/index.tsx"
import { defineDashboardExtension } from '@vendure/dashboard';

import { articleList } from './article-list';
// highlight-next-line
import { articleDetail } from './article-detail';

export default defineDashboardExtension({
    routes: [
        articleList,
        // highlight-next-line
        articleDetail,
    ],
});
```

You should now be able to click on the "New article" button in the list view, and see the detail page:
![Detail Page](../getting-started/detail-view.webp)

Congratulations! You can now add, edit and delete articles in the dashboard.

![List view with entries](../getting-started/list-view-full.webp)

## Customizing the detail page

The auto-generated [DetailPage](/reference/dashboard/components/detail-page) is a great way to get started and quickly be able
to interact with your entities. But let's now see how we can fully customize the layout and form fields.

```tsx title="src/plugins/cms/dashboard/article-detail.tsx"
import {
    DashboardRouteDefinition,
    detailPageRouteLoader,
    useDetailPage,
    Page,
    PageTitle,
    PageActionBar,
    PageActionBarRight,
    PermissionGuard,
    Button,
    PageLayout,
    PageBlock,
    FormFieldWrapper,
    DetailFormGrid,
    Switch,
    Input,
    RichTextInput,
    CustomFieldsPageBlock,
} from '@vendure/dashboard';
import { AnyRoute, useNavigate } from '@tanstack/react-router';
import { toast } from 'sonner';

import { graphql } from '@/gql';

const articleDetailDocument = graphql(`
    query GetArticleDetail($id: ID!) {
        article(id: $id) {
            id
            createdAt
            updatedAt
            isPublished
            title
            slug
            body
            customFields
        }
    }
`);

const createArticleDocument = graphql(`
    mutation CreateArticle($input: CreateArticleInput!) {
        createArticle(input: $input) {
            id
        }
    }
`);

const updateArticleDocument = graphql(`
    mutation UpdateArticle($input: UpdateArticleInput!) {
        updateArticle(input: $input) {
            id
        }
    }
`);

export const articleDetail: DashboardRouteDefinition = {
    path: '/articles/$id',
    loader: detailPageRouteLoader({
        queryDocument: articleDetailDocument,
        breadcrumb: (isNew, entity) => [
            { path: '/articles', label: 'Articles' },
            isNew ? 'New article' : entity?.title,
        ],
    }),
    component: route => {
        return <ArticleDetailPage route={route} />;
    },
};

function ArticleDetailPage({ route }: { route: AnyRoute }) {
    const params = route.useParams();
    const navigate = useNavigate();
    const creatingNewEntity = params.id === 'new';

    const { form, submitHandler, entity, isPending, resetForm } = useDetailPage({
        queryDocument: articleDetailDocument,
        createDocument: createArticleDocument,
        updateDocument: updateArticleDocument,
        setValuesForUpdate: article => {
            return {
                id: article?.id ?? '',
                isPublished: article?.isPublished ?? false,
                title: article?.title ?? '',
                slug: article?.slug ?? '',
                body: article?.body ?? '',
            };
        },
        params: { id: params.id },
        onSuccess: async data => {
            toast('Successfully updated article');
            resetForm();
            if (creatingNewEntity) {
                await navigate({ to: `../$id`, params: { id: data.id } });
            }
        },
        onError: err => {
            toast('Failed to update article', {
                description: err instanceof Error ? err.message : 'Unknown error',
            });
        },
    });

    return (
        <Page pageId="article-detail" form={form} submitHandler={submitHandler}>
            <PageTitle>{creatingNewEntity ? 'New article' : (entity?.title ?? '')}</PageTitle>
            <PageActionBar>
                <PageActionBarRight>
                    <PermissionGuard requires={['UpdateProduct', 'UpdateCatalog']}>
                        <Button
                            type="submit"
                            disabled={!form.formState.isDirty || !form.formState.isValid || isPending}
                        >
                            Update
                        </Button>
                    </PermissionGuard>
                </PageActionBarRight>
            </PageActionBar>
            <PageLayout>
                <PageBlock column="side" blockId="publish-status">
                    <FormFieldWrapper
                        control={form.control}
                        name="isPublished"
                        label="Is Published"
                        render={({ field }) => (
                            <Switch checked={field.value} onCheckedChange={field.onChange} />
                        )}
                    />
                </PageBlock>
                <PageBlock column="main" blockId="main-form">
                    <DetailFormGrid>
                        <FormFieldWrapper
                            control={form.control}
                            name="title"
                            label="Title"
                            render={({ field }) => <Input {...field} />}
                        />
                        <FormFieldWrapper
                            control={form.control}
                            name="slug"
                            label="Slug"
                            render={({ field }) => <Input {...field} />}
                        />
                    </DetailFormGrid>
                    <FormFieldWrapper
                        control={form.control}
                        name="body"
                        label="Content"
                        render={({ field }) => (
                            <RichTextInput value={field.value ?? ''} onChange={field.onChange} />
                        )}
                    />
                </PageBlock>
                <CustomFieldsPageBlock column="main" entityType="Article" control={form.control} />
            </PageLayout>
        </Page>
    );
}
```

In the above example, we have:

- Used the [Page](/reference/dashboard/components/page), [PageTitle](/reference/dashboard/components/page-title),
  [PageActionBar](/reference/dashboard/components/page-action-bar) and [PageLayout](/reference/dashboard/components/page-layout) components to create a layout for our page.
- Used [PageBlock](/reference/dashboard/components/page-block) components to structure the page into blocks.
- Used custom form components (such as the `RichTextInput`) to better represent the data.

## API Reference

A partial API reference of the new Dashboard API can be found here:

- [Dashboard API Reference](/reference/dashboard/extensions/)


---

---
title: 'Form Component Examples'
---


import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

## Email Input with Validation

This example uses the `react-hook-form` validation state in order to display an icon indicating
the validity of the email address, as defined by the custom field "pattern" option:

![Email input](./example-email-input.webp)


<Tabs>
<TabItem value="Component" label="Component" default>
    ```tsx title="src/plugins/my-plugin/dashboard/components/email-input.tsx"
    import {AffixedInput, DashboardFormComponent} from '@vendure/dashboard';
    import {Mail, Check, X} from 'lucide-react';
    import {useFormContext} from 'react-hook-form';

    export const EmailInputComponent: DashboardFormComponent = ({name, value, onChange, disabled}) => {
        // highlight-start
        const {getFieldState} = useFormContext();
        const isValid = getFieldState(name).invalid === false;
        // highlight-end

        return (
            <AffixedInput
                prefix={<Mail className="h-4 w-4 text-muted-foreground" />}
                suffix={
                    value &&
                    // highlight-start
                    (isValid ? (
                        <Check className="h-4 w-4 text-green-500" />
                    ) : (
                        <X className="h-4 w-4 text-red-500" />
                    ))
                    // highlight-end
                }
                value={value || ''}
                onChange={e => onChange(e.target.value)}
                disabled={disabled}
                placeholder="Enter email address"
                className="pl-10 pr-10"
                name={name}
            />
        );
    };
    ```
</TabItem>
<TabItem value="Registration" label="Registration">
    ```tsx title="src/plugins/my-plugin/dashboard/index.tsx"
    import { defineDashboardExtension } from '@vendure/dashboard';

    import { EmailInputComponent } from './components/email-input';

    defineDashboardExtension({
        customFormComponents: {
            customFields: [
                {
                    // highlight-start
                    id: 'custom-email',
                    component: EmailInputComponent,
                    // highlight-end
                },
            ],
        }
    });
    ```
</TabItem>
<TabItem value="Custom field definition" label="Custom field definition">
    ```ts title="src/plugins/my-plugin/my.plugin.ts"
    @VendureConfig({
        configuration: config => {
            config.customFields.Seller.push({
                name: 'supplierEmail',
                type: 'string',
                label: [{ languageCode: LanguageCode.en, value: 'Supplier Email' }],
                // highlight-start
                pattern: '^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$',
                ui: { component: 'custom-email' },
                // highlight-end
            });
            return config;
        }
    })
    export class MyPlugin {}
    ```
</TabItem>
</Tabs>

## Multi-Currency Price Input

This example demonstrates a component with its own state (using `useState`) and more complex
internal logic.

![Currency input](./example-currency-input.webp)

<Tabs>
<TabItem value="Component" label="Component" default>
    ```tsx title="src/plugins/my-plugin/dashboard/components/price-input.tsx"
    import {
        AffixedInput,
        DashboardFormComponent,
        Select,
        SelectContent,
        SelectItem,
        SelectTrigger,
        SelectValue,
        useLocalFormat,
    } from '@vendure/dashboard';
    import { useState } from 'react';

    export const MultiCurrencyInputComponent: DashboardFormComponent = ({ value, onChange, disabled, name }) => {
        const [currency, setCurrency] = useState('USD');
        const { formatCurrencyName } = useLocalFormat();

        const currencies = [
            { code: 'USD', symbol: '$', rate: 1 },
            { code: 'EUR', symbol: '€', rate: 0.85 },
            { code: 'GBP', symbol: '£', rate: 0.73 },
            { code: 'JPY', symbol: '¥', rate: 110 },
        ];

        const selectedCurrency = currencies.find(c => c.code === currency) || currencies[0];

        // Convert price based on exchange rate
        const displayValue = value ? (value * selectedCurrency.rate).toFixed(2) : '';

        const handleChange = (val: string) => {
            const numericValue = parseFloat(val) || 0;
            // Convert back to base currency (USD) for storage
            const baseValue = numericValue / selectedCurrency.rate;
            onChange(baseValue);
        };

        return (
            <div className="flex space-x-2">
                <Select value={currency} onValueChange={setCurrency} disabled={disabled}>
                    <SelectTrigger className="w-24">
                        <SelectValue>
                            <div className="flex items-center gap-1">{currency}</div>
                        </SelectValue>
                    </SelectTrigger>
                    <SelectContent>
                        {currencies.map(curr => {
                            return (
                                <SelectItem key={curr.code} value={curr.code}>
                                    <div className="flex items-center gap-2">{formatCurrencyName(curr.code)}</div>
                                </SelectItem>
                            );
                        })}
                    </SelectContent>
                </Select>
                <AffixedInput
                    prefix={selectedCurrency.symbol}
                    value={displayValue}
                    onChange={e => onChange(e.target.value)}
                    disabled={disabled}
                    placeholder="0.00"
                    name={name}
                />
            </div>
        );
    };
    ```
</TabItem>
<TabItem value="Registration" label="Registration">
    ```tsx title="src/plugins/my-plugin/dashboard/index.tsx"
    import { defineDashboardExtension } from '@vendure/dashboard';

    import { MultiCurrencyInputComponent } from './components/price-input';

    defineDashboardExtension({
        customFormComponents: {
            customFields: [
                {
                    id: 'custom-price',
                    component: MultiCurrencyInputComponent,
                },
            ],
        }
    });
    ```
</TabItem>
<TabItem value="Custom field definition" label="Custom field definition">
    ```ts title="src/plugins/my-plugin/my.plugin.ts"
    @VendureConfig({
        configuration: config => {
            config.customFields.Product.push({
                name: 'rrp',
                type: 'int',
                label: [{ languageCode: LanguageCode.en, value: 'RRP' }],
                // highlight-start
                ui: { component: 'custom-price' },
                // highlight-end
            });
            return config;
        }
    })
    export class MyPlugin {}
    ```
</TabItem>
</Tabs>

## Tags Input Component

This component brings better UX to a simple comma-separated tags custom field.

![Tags input](./example-tags-input.webp)


<Tabs>
<TabItem value="Component" label="Component" default>
    ```tsx title="src/plugins/my-plugin/dashboard/components/tags-input.tsx"
    import { Input, Badge, Button, DashboardFormComponent } from '@vendure/dashboard';
    import { useState, KeyboardEvent } from 'react';
    import { X } from 'lucide-react';

    export const TagsInputComponent: DashboardFormComponent = ({ value, onChange, disabled, name, onBlur }) => {
        const [inputValue, setInputValue] = useState('');

        // Parse tags from string value (comma-separated)
        const tags: string[] = value ? value.split(',').filter(Boolean) : [];

        const addTag = (tag: string) => {
            const trimmedTag = tag.trim();
            if (trimmedTag && !tags.includes(trimmedTag)) {
                const newTags = [...tags, trimmedTag];
                onChange(newTags.join(','));
            }
            setInputValue('');
        };

        const removeTag = (tagToRemove: string) => {
            const newTags = tags.filter(tag => tag !== tagToRemove);
            onChange(newTags.join(','));
        };

        const handleKeyDown = (e: KeyboardEvent<HTMLInputElement>) => {
            if (e.key === 'Enter' || e.key === ',') {
                e.preventDefault();
                addTag(inputValue);
            } else if (e.key === 'Backspace' && inputValue === '' && tags.length > 0) {
                removeTag(tags[tags.length - 1]);
            }
        };

        return (
            <div className="space-y-2">
                {/* Tags Display */}
                <div className="flex flex-wrap gap-1">
                    {tags.map((tag, index) => (
                        <Badge key={index} variant="secondary" className="gap-1">
                            {tag}
                            <Button
                                type="button"
                                variant="ghost"
                                size="icon"
                                className="h-4 w-4 p-0 hover:bg-transparent"
                                onClick={() => removeTag(tag)}
                                disabled={disabled}
                            >
                                <X className="h-3 w-3" />
                            </Button>
                        </Badge>
                    ))}
                </div>

                {/* Input */}
                <Input
                    value={inputValue}
                    onChange={e => setInputValue(e.target.value)}
                    onKeyDown={handleKeyDown}
                    onBlur={onBlur}
                    disabled={disabled}
                    placeholder="Type a tag and press Enter or comma"
                    name={name}
                />
            </div>
        );
    };
    ```
</TabItem>
<TabItem value="Registration" label="Registration">
    ```tsx title="src/plugins/my-plugin/dashboard/index.tsx"
    import { defineDashboardExtension } from '@vendure/dashboard';

    import { TagsInputComponent } from './components/tags-input';

    defineDashboardExtension({
        customFormComponents: {
            customFields: [
                {
                    id: 'custom-tags',
                    component: TagsInputComponent,
                },
            ],
        }
    });
    ```
</TabItem>
<TabItem value="Custom field definition" label="Custom field definition">
    ```ts title="src/plugins/my-plugin/my.plugin.ts"
    @VendureConfig({
        configuration: config => {
            config.customFields.Product.push({
                name: 'tags',
                type: 'string',
                label: [{ languageCode: LanguageCode.en, value: 'Tags' }],
                // highlight-start
                ui: { component: 'custom-tags' },
                // highlight-end
            });
            return config;
        }
    })
    export class MyPlugin {}
    ```
</TabItem>
</Tabs>

## Auto-generating Slug Input

This example demonstrates a component that automatically generates a slug from the product name.
It uses the `react-hook-form` `watch` method to get the value of another field in the form and 
react to changes in that field.

![Slug input](./example-slug-input.webp)

<Tabs>
<TabItem value="Component" label="Component" default>
```tsx title="src/plugins/my-plugin/dashboard/components/slug-input.tsx"
    import { Input, Button, Switch, DashboardFormComponent } from '@vendure/dashboard';
    import { useFormContext } from 'react-hook-form';
    import { useState, useEffect } from 'react';
    import { RefreshCw, Lock, Unlock } from 'lucide-react';

    export const SlugInputComponent: DashboardFormComponent = ({ value, onChange, disabled, name }) => {
        const [autoGenerate, setAutoGenerate] = useState(!value);
        const [isGenerating, setIsGenerating] = useState(false);
        const { watch } = useFormContext();
        const nameValue = watch('translations.0.name');

        const generateSlug = (text: string) => {
            return text
                .toLowerCase()
                .replace(/[^a-z0-9 -]/g, '') // Remove special characters
                .replace(/\s+/g, '-') // Replace spaces with hyphens
                .replace(/-+/g, '-') // Replace multiple hyphens with single
                .trim('-'); // Remove leading/trailing hyphens
        };

        useEffect(() => {
            if (autoGenerate && nameValue) {
                const newSlug = generateSlug(nameValue);
                if (newSlug !== value) {
                    onChange(newSlug);
                }
            }
        }, [nameValue, autoGenerate, onChange, value]);

        const handleManualGenerate = async () => {
            if (!nameValue) return;

            setIsGenerating(true);
            // Simulate API call for slug validation/generation
            await new Promise(resolve => setTimeout(resolve, 500));

            const newSlug = generateSlug(nameValue);
            onChange(newSlug);
            setIsGenerating(false);
        };

        return (
            <div className="space-y-2">
                <div className="flex items-center space-x-2">
                    <Input
                        value={value || ''}
                        onChange={e => onChange(e.target.value)}
                        disabled={disabled || autoGenerate}
                        placeholder="product-slug"
                        className="flex-1"
                        name={name}
                    />

                    <Button
                        type="button"
                        variant="outline"
                        size="icon"
                        disabled={disabled || !nameValue || isGenerating}
                        onClick={handleManualGenerate}
                    >
                        <RefreshCw className={`h-4 w-4 ${isGenerating ? 'animate-spin' : ''}`} />
                    </Button>
                </div>

                <div className="flex items-center space-x-2">
                    <Switch checked={autoGenerate} onCheckedChange={setAutoGenerate} disabled={disabled} />
                    <div className="flex items-center space-x-1 text-sm text-muted-foreground">
                        {autoGenerate ? <Lock className="h-3 w-3" /> : <Unlock className="h-3 w-3" />}
                        <span>Auto-generate from name</span>
                    </div>
                </div>
            </div>
        );
    };
    ```
</TabItem>
<TabItem value="Registration" label="Registration">
    ```tsx title="src/plugins/my-plugin/dashboard/index.tsx"
    import { defineDashboardExtension } from '@vendure/dashboard';

    import { SlugInputComponent } from './components/slug-input';

    defineDashboardExtension({
        detailForms: [
            {
                // highlight-start
                pageId: 'product-detail',
                inputs: [
                    {
                        blockId: 'main-form',
                        field: 'slug',
                        component: SlugInputComponent,
                    },
                ],
                // highlight-end
            },
        ]
    });
    ```
</TabItem>
</Tabs>

:::note
Input components completely replace the default input for the targeted field. Make sure your component handles all the data types and scenarios that the original input would have handled.
:::

## Related Guides

- **[Custom Form Elements Overview](./)** - Learn about the unified system for custom field components, input components, and display components


---

---
title: 'Custom Form Elements'
---

The dashboard allows you to create custom form elements that provide complete control over how data is rendered and how users
interact with forms. This includes:

- **Custom Field Components** - Globally-registered components that can be used to render **custom fields** and **configurable operation arguments**
- **Detail Form Components** - Form input components that target specific fields of detail pages.

## Anatomy of a Form Component

All form components must implement the [DashboardFormComponent type](/reference/dashboard/forms/dashboard-form-component).

This type is based on the props that are made available from `react-hook-form`, which is the
underlying form library used by the Dashboard.

Here's an example custom form component that has been annotated to explain the typical parts you will be working with:

```tsx title="src/plugins/my-plugin/dashboard/components/color-picker.tsx"
import { Button, Card, CardContent, cn, DashboardFormComponent, Input } from '@vendure/dashboard';
import { useState } from 'react';
import { useFormContext } from 'react-hook-form';

// By typing your component as DashboardFormComponent, the props will be correctly typed
export const ColorPickerComponent: DashboardFormComponent = ({ value, onChange, name }) => {
    // You can use any of the built-in React hooks as usual
    const [isOpen, setIsOpen] = useState(false);

    // To access the react-hook-form context, use this hook.
    // This is useful for getting information about the current
    // field, or even other fields in the form, which allows you
    // to create advanced components that depend on the state of
    // other fields in the form.
    const { getFieldState } = useFormContext();
    // The current field name is always passed in as a prop, allowing
    // you to look up the field state
    const error = getFieldState(name).error;

    const colors = ['#FF6B6B', '#4ECDC4', '#45B7D1', '#96CEB4', '#FECA57', '#FF9FF3', '#54A0FF', '#5F27CD'];

    return (
        <div className="space-y-2">
            <div className="flex items-center space-x-2">
                <Button
                    type="button"
                    variant="outline"
                    size="icon"
                    className={cn('w-8 h-8 border-2 border-gray-300 p-0', error && 'border-red-500')}
                    style={{ backgroundColor: error ? 'transparent' : value || '#ffffff' }}
                    onClick={() => setIsOpen(!isOpen)}
                />
                <Input value={value || ''} onChange={e => onChange(e.target.value)} placeholder="#ffffff" />
            </div>

            {isOpen && (
                <Card>
                    <CardContent className="grid grid-cols-4 gap-2 p-2">
                        {colors.map(color => (
                            <Button
                                key={color}
                                type="button"
                                variant="outline"
                                size="icon"
                                className="w-8 h-8 border-2 border-gray-300 hover:border-gray-500 p-0"
                                style={{ backgroundColor: color }}
                                onClick={() => {
                                    onChange(color);
                                    setIsOpen(false);
                                }}
                            />
                        ))}
                    </CardContent>
                </Card>
            )}
        </div>
    );
};
```

Here's how this component will look when rendered in your form:

![Color picker component](./color-picker.webp)

## Custom Field Components

Let's configure a [custom field](/guides/developer-guide/custom-fields/) which uses the `ColorPickerComponent` as its form component.

First we need to register the component with the `defineDashboardExtension` function:

```tsx title="src/plugins/my-plugin/dashboard/index.tsx"
import { defineDashboardExtension } from '@vendure/dashboard';
import { ColorPickerComponent } from './components/color-picker';

export default defineDashboardExtension({
    customFormComponents: {
        // Custom field components for custom fields
        customFields: [
            {
                // highlight-start
                // The "id" is a global identifier for this custom component. We will
                // reference it in the next step.
                id: 'color-picker',
                component: ColorPickerComponent,
                // highlight-end
            },
        ],
    },
    // ... other extension properties
});
```

Now that we've registered it as a custom field component, we can use it in our custom field definition.

```tsx title="src/plugins/my-plugin/my.plugin.ts"
@VendurePlugin({
    // ...
    configuration: config => {
        config.customFields.Product.push({
            name: 'color',
            type: 'string',
            pattern: '^#[A-Fa-f0-9]{6}$',
            label: [{ languageCode: LanguageCode.en, value: 'Color' }],
            description: [{ languageCode: LanguageCode.en, value: 'Main color for this product' }],
            ui: {
                // highlight-start
                // This is the ID of the custom field
                // component we registered above.
                component: 'color-picker',
                // highlight-end
            },
        });
        return config;
    },
})
export class MyPlugin {}
```

## Configurable Operation Components

The `ColorPickerComponent` can also be used as a [configurable operation argument](/guides/developer-guide/strategies-configurable-operations/#configurable-operations) component. For example, we can add a color code
to a shipping calculator:

```tsx title="src/plugins/my-plugin/config/custom-shipping-calculator.ts"
const customShippingCalculator = new ShippingCalculator({
    code: 'custom-shipping-calculator',
    description: [{ languageCode: LanguageCode.en, value: 'Custom Shipping Calculator' }],
    args: {
        color: {
            type: 'string',
            label: [{ languageCode: LanguageCode.en, value: 'Color' }],
            description: [
                { languageCode: LanguageCode.en, value: 'Color code for this shipping calculator' },
            ],
            // highlight-start
            ui: { component: 'color-picker' },
            // highlight-end
        },
    },
    calculate: (ctx, order, args) => {
        // ...
    },
});
```

## Detail Form Components

Detail form components allow you to replace specific input fields in existing dashboard forms with custom implementations. They are targeted to specific pages, blocks, and fields.

Let's say we want to use a plain text editor for the product description field rather than the default
html-based editor.

```tsx title="src/plugins/my-plugin/dashboard/components/markdown-editor.tsx"
import { DashboardFormComponent, Textarea } from '@vendure/dashboard';

// This is a simplified example - a real markdown editor should use
// a library that handles markdown rendering and editing.
export const MarkdownEditorComponent: DashboardFormComponent = props => {
    return (
        <Textarea
            className="font-mono"
            ref={props.ref}
            onBlur={props.onBlur}
            value={props.value}
            onChange={e => props.onChange(e.target.value)}
            disabled={props.disabled}
        />
    );
};
```

You can then use this component in your detail form definition:

```tsx title="src/plugins/my-plugin/dashboard/index.tsx"
import { defineDashboardExtension } from '@vendure/dashboard';
import { MarkdownEditorComponent } from './components/markdown-editor';

export default defineDashboardExtension({
    detailForms: [
        {
            // highlight-start
            pageId: 'product-detail',
            inputs: [
                {
                    blockId: 'main-form',
                    field: 'description',
                    component: MarkdownEditorComponent,
                },
            ],
            // highlight-end
        },
    ],
});
```

### Targeting Input Components

Input components are targeted using three properties:

- **pageId**: The ID of the page (e.g., 'product-detail', 'customer-detail')
- **blockId**: The ID of the form block (e.g., 'product-form', 'customer-info')
- **field**: The name of the field to replace (e.g., 'price', 'email')

```tsx
inputs: [
    {
        pageId: 'product-variant-detail',
        blockId: 'main-form',
        field: 'price',
        component: PriceInputComponent,
    },
    {
        pageId: 'customer-detail',
        blockId: 'main-form',
        field: 'emailAddress',
        component: EmailInputComponent,
    },
];
```

You can discover the required IDs by turning on dev mode:

![Dev mode](./dev-mode.webp)

and then hovering over any of the form elements will allow you to view the IDs:

![Form element IDs](./locator.webp)

## Form Validation

Form validation is handled by the `react-hook-form` library, which is used by the Dashboard. Internally,
the Dashboard uses the `zod` library to validate the form data, based on the configuration of the custom field or
operation argument.

You can access validation data for the current field or the whole form by using the `useFormContext` hook.

:::note Error Messages
Your component does not need to handle standard error messages - the Dashboard will handle them for you.

For example, if your custom field specifies a `pattern` property, the Dashboard will automatically display an error message
if the input does not match the pattern.
:::

```tsx title="src/plugins/my-plugin/dashboard/components/validated-input.tsx"
import { DashboardFormComponent, Input, Alert, AlertDescription } from '@vendure/dashboard';
import { useFormContext } from 'react-hook-form';
import { CheckCircle2 } from 'lucide-react';

export const ValidatedInputComponent: DashboardFormComponent = ({ value, onChange, name }) => {
    const { getFieldState } = useFormContext();
    const fieldState = getFieldState(name);

    console.log(fieldState);
    // will log something like this:
    // {
    //     "invalid": false,
    //     "isDirty": false,
    //     "isValidating": false,
    //     "isTouched": false
    // }
    // You can use this data to display validation errors, etc.

    return (
        <div className="space-y-2">
            <Input
                value={field.value || ''}
                onChange={e => field.onChange(e.target.value)}
                onBlur={field.onBlur}
                className={fieldState.error ? 'border-destructive' : ''}
            />

            {fieldState.error && (
                <Alert variant="destructive">
                    <AlertDescription>{fieldState.error.message}</AlertDescription>
                </Alert>
            )}

            {fieldState.isTouched && !fieldState.error && (
                <div className="flex items-center gap-1 text-sm text-green-600">
                    <CheckCircle2 className="h-4 w-4" />
                    Valid input
                </div>
            )}
        </div>
    );
}
```

:::tip Best Practices

1. **Always use Shadcn UI components** from the `@vendure/dashboard` package for consistent styling
2. **Handle React Hook Form events properly** - call `onChange` and `onBlur` appropriately for custom field components
3. **Display validation errors** from `fieldState.error` when they exist (custom field components)
4. **Use dashboard design tokens** - leverage `text-destructive`, `text-muted-foreground`, etc.
5. **Provide clear visual feedback** for user interactions
6. **Handle disabled states** by using the `disabled` prop
7. **Target components precisely** using pageId, blockId, and field for input components
:::


:::important Design System Consistency
Always import UI components from the `@vendure/dashboard` package rather than creating custom inputs or buttons. This ensures your components follow the dashboard's design system and remain consistent with future updates.
:::

The unified custom form elements system gives you complete flexibility in how data is presented and edited in the dashboard, while maintaining seamless integration with React Hook Form and the dashboard's design system.

## Relation Selectors

The dashboard includes powerful relation selector components for selecting related entities with built-in search and pagination:

```tsx title="src/plugins/my-plugin/dashboard/components/product-selector.tsx"
import {
    SingleRelationInput,
    createRelationSelectorConfig,
    graphql,
    CustomFormComponentInputProps,
} from '@vendure/dashboard';

const productConfig = createRelationSelectorConfig({
    listQuery: graphql(`
        query GetProductsForSelection($options: ProductListOptions) {
            products(options: $options) {
                items {
                    id
                    name
                }
                totalItems
            }
        }
    `),
    idKey: 'id',
    labelKey: 'name',
    placeholder: 'Search products...',
    buildSearchFilter: (term: string) => ({
        name: { contains: term },
    }),
});

export function ProductSelectorComponent({ value, onChange }: CustomFormComponentInputProps) {
    return <SingleRelationInput value={value} onChange={onChange} config={productConfig} />;
}
```

Features include:

- **Real-time search** with debounced input
- **Infinite scroll pagination** loading 25 items by default
- **Single and multi-select modes** with type safety
- **Customizable GraphQL queries** and search filters
- **Built-in UI components** using the dashboard design system

## Further Reading

For detailed information about specific types of custom form elements, see these dedicated guides:

- **[Form component examples](./form-component-examples)** - Detailed examples of how to use the APIs available for custom form components.
- **[Relation selectors](./relation-selectors)** - Build powerful entity selection components with search, pagination, and multi-select capabilities for custom fields and form inputs


---

---
title: 'Relation Selectors'
---

Relation selector components provide a powerful way to select related entities in your dashboard forms. They support both single and multi-selection modes with built-in search, infinite scroll pagination, and complete TypeScript type safety.

## Features

- **Real-time Search**: Debounced search with customizable filters
- **Infinite Scroll**: Automatic pagination loading 25 items by default
- **Single/Multi Select**: Easy toggle between selection modes
- **Type Safe**: Full TypeScript support with generic types
- **Customizable**: Pass your own GraphQL queries and field mappings
- **Accessible**: Built with Radix UI primitives

## Components Overview

The relation selector system consists of three main components:

- **`RelationSelector`**: The abstract base component that handles all core functionality
- **`SingleRelationInput`**: Convenient wrapper for single entity selection
- **`MultiRelationInput`**: Convenient wrapper for multiple entity selection

## Basic Usage

### Single Selection

```tsx title="src/plugins/my-plugin/dashboard/components/product-selector.tsx"
import {
    SingleRelationInput,
    createRelationSelectorConfig,
    graphql,
    ResultOf,
    CustomFormComponentInputProps,
} from '@vendure/dashboard';

// Define your GraphQL query
const productListQuery = graphql(`
    query GetProductsForSelection($options: ProductListOptions) {
        products(options: $options) {
            items {
                id
                name
                slug
                featuredAsset {
                    id
                    preview
                }
            }
            totalItems
        }
    }
`);

// Create the configuration
const productConfig = createRelationSelectorConfig({
    listQuery: productListQuery,
    idKey: 'id',
    labelKey: 'name',
    placeholder: 'Search products...',
    buildSearchFilter: (term: string) => ({
        name: { contains: term },
    }),
});

export function ProductSelectorComponent({ value, onChange, disabled }: CustomFormComponentInputProps) {
    return (
        <SingleRelationInput value={value} onChange={onChange} config={productConfig} disabled={disabled} />
    );
}
```

### Multi Selection

```tsx title="src/plugins/my-plugin/dashboard/components/product-multi-selector.tsx"
import { MultiRelationInput, CustomFormComponentInputProps } from '@vendure/dashboard';

export function ProductMultiSelectorComponent({ value, onChange, disabled }: CustomFormComponentInputProps) {
    return (
        <MultiRelationInput
            value={value || []}
            onChange={onChange}
            config={productConfig} // Same config as above
            disabled={disabled}
        />
    );
}
```

## Configuration Options

The `createRelationSelectorConfig` function accepts these options:

```tsx
interface RelationSelectorConfig<T> {
    /** The GraphQL query document for fetching items */
    listQuery: DocumentNode;
    /** The property key for the entity ID */
    idKey: keyof T;
    /** The property key for the display label (used as fallback when label function not provided) */
    labelKey: keyof T;
    /** Number of items to load per page (default: 25) */
    pageSize?: number;
    /** Placeholder text for the search input */
    placeholder?: string;
    /** Whether to enable multi-select mode */
    multiple?: boolean;
    /** Custom filter function for search */
    buildSearchFilter?: (searchTerm: string) => any;
    /** Custom label renderer function for rich display */
    label?: (item: T) => React.ReactNode;
}
```

## Rich Label Display

The `label` prop allows you to customize how items are displayed in both the dropdown and selected item chips. This enables rich content like images, badges, and multi-line information.

### Product Selector with Images and Pricing

```tsx title="src/plugins/my-plugin/dashboard/components/rich-product-selector.tsx"
import {
    SingleRelationInput,
    createRelationSelectorConfig,
    graphql,
    ResultOf,
    CustomFormComponentInputProps,
} from '@vendure/dashboard';

const productListQuery = graphql(`
    query GetProductsWithDetails($options: ProductListOptions) {
        products(options: $options) {
            items {
                id
                name
                slug
                featuredAsset {
                    id
                    preview
                }
                variants {
                    id
                    price
                    currencyCode
                }
            }
            totalItems
        }
    }
`);

const richProductConfig = createRelationSelectorConfig<
    ResultOf<typeof productListQuery>['products']['items'][0]
>({
    listQuery: productListQuery,
    idKey: 'id',
    labelKey: 'name', // Used as fallback
    placeholder: 'Search products...',
    label: product => (
        <div className="flex items-center gap-3 py-1">
            {product.featuredAsset?.preview && (
                <img
                    src={product.featuredAsset.preview}
                    alt={product.name}
                    className="w-10 h-10 rounded object-cover"
                />
            )}
            <div className="flex-1 min-w-0">
                <div className="font-medium truncate">{product.name}</div>
                <div className="text-sm text-muted-foreground">
                    {product.variants[0] && (
                        <span>
                            {product.variants[0].price / 100} {product.variants[0].currencyCode}
                        </span>
                    )}
                </div>
            </div>
        </div>
    ),
    buildSearchFilter: (term: string) => ({
        name: { contains: term },
    }),
});

export function RichProductSelectorComponent({ value, onChange, disabled }: CustomFormComponentInputProps) {
    return (
        <SingleRelationInput
            value={value}
            onChange={onChange}
            config={richProductConfig}
            disabled={disabled}
        />
    );
}
```

### Customer Selector with Status Badges

```tsx title="src/plugins/my-plugin/dashboard/components/customer-selector-with-status.tsx"
import {
    MultiRelationInput,
    createRelationSelectorConfig,
    graphql,
    ResultOf,
    CustomFormComponentInputProps,
} from '@vendure/dashboard';

const customerListQuery = graphql(`
    query GetCustomersWithStatus($options: CustomerListOptions) {
        customers(options: $options) {
            items {
                id
                firstName
                lastName
                emailAddress
                user {
                    verified
                    lastLogin
                }
                orders {
                    totalQuantity
                }
            }
            totalItems
        }
    }
`);

const customerConfig = createRelationSelectorConfig<
    ResultOf<typeof customerListQuery>['customers']['items'][0]
>({
    listQuery: customerListQuery,
    idKey: 'id',
    labelKey: 'emailAddress',
    placeholder: 'Search customers...',
    label: customer => (
        <div className="flex items-center justify-between py-1 w-full">
            <div className="flex-1 min-w-0">
                <div className="font-medium truncate">
                    {customer.firstName} {customer.lastName}
                </div>
                <div className="text-sm text-muted-foreground truncate">{customer.emailAddress}</div>
            </div>
            <div className="flex items-center gap-2 ml-2">
                {customer.user?.verified ? (
                    <span className="inline-flex items-center px-2 py-1 text-xs font-medium rounded-full bg-green-100 text-green-800">
                        Verified
                    </span>
                ) : (
                    <span className="inline-flex items-center px-2 py-1 text-xs font-medium rounded-full bg-gray-100 text-gray-800">
                        Unverified
                    </span>
                )}
                <span className="text-xs text-muted-foreground">{customer.orders.totalQuantity} orders</span>
            </div>
        </div>
    ),
    buildSearchFilter: (term: string) => ({
        or: [
            { emailAddress: { contains: term } },
            { firstName: { contains: term } },
            { lastName: { contains: term } },
        ],
    }),
});

export function CustomerSelectorWithStatusComponent({
    value,
    onChange,
    disabled,
}: CustomFormComponentInputProps) {
    return (
        <MultiRelationInput
            value={value || []}
            onChange={onChange}
            config={customerConfig}
            disabled={disabled}
        />
    );
}
```

## Advanced Examples

### Custom Entity with Complex Search

```tsx title="src/plugins/review-plugin/dashboard/components/review-selector.tsx"
import {
    SingleRelationInput,
    createRelationSelectorConfig,
    graphql,
    ResultOf,
    CustomFormComponentInputProps,
} from '@vendure/dashboard';

const reviewFragment = graphql(`
    fragment ReviewForSelector on ProductReview {
        id
        title
        rating
        summary
        state
        product {
            name
        }
    }
`);

const reviewListQuery = graphql(
    `
        query GetReviewsForSelection($options: ProductReviewListOptions) {
            productReviews(options: $options) {
                items {
                    ...ReviewForSelector
                }
                totalItems
            }
        }
    `,
    [reviewFragment],
);

const reviewConfig = createRelationSelectorConfig<ResultOf<typeof reviewFragment>>({
    listQuery: reviewListQuery,
    idKey: 'id',
    labelKey: 'title',
    placeholder: 'Search reviews by title or summary...',
    pageSize: 20, // Custom page size
    buildSearchFilter: (term: string) => ({
        // Search across multiple fields
        or: [
            { title: { contains: term } },
            { summary: { contains: term } },
            { product: { name: { contains: term } } },
        ],
    }),
});

export function ReviewSelectorComponent({ value, onChange }: CustomFormComponentInputProps) {
    return <SingleRelationInput value={value} onChange={onChange} config={reviewConfig} />;
}
```

### Asset Selector with Type Filtering

```tsx title="src/plugins/my-plugin/dashboard/components/image-selector.tsx"
import {
    graphql,
    createRelationSelectorConfig,
    SingleRelationInput,
    CustomFormComponentInputProps,
} from '@vendure/dashboard';

const assetListQuery = graphql(`
    query GetAssetsForSelection($options: AssetListOptions) {
        assets(options: $options) {
            items {
                id
                name
                preview
                type
                fileSize
            }
            totalItems
        }
    }
`);

const imageAssetConfig = createRelationSelectorConfig({
    listQuery: assetListQuery,
    idKey: 'id',
    labelKey: 'name',
    placeholder: 'Search images...',
    buildSearchFilter: (term: string) => ({
        and: [
            { type: { eq: 'IMAGE' } }, // Only show images
            {
                or: [{ name: { contains: term } }, { preview: { contains: term } }],
            },
        ],
    }),
});

export function ImageSelectorComponent({ value, onChange }: CustomFormComponentInputProps) {
    return <SingleRelationInput value={value} onChange={onChange} config={imageAssetConfig} />;
}
```

### Multi-Select with Status Filtering

```tsx title="src/plugins/my-plugin/dashboard/components/active-customer-selector.tsx"
import {
    MultiRelationInput,
    createRelationSelectorConfig,
    graphql,
    CustomFormComponentInputProps,
} from '@vendure/dashboard';

const customerListQuery = graphql(`
    query GetCustomersForSelection($options: CustomerListOptions) {
        customers(options: $options) {
            items {
                id
                firstName
                lastName
                emailAddress
                user {
                    verified
                }
            }
            totalItems
        }
    }
`);

const activeCustomerConfig = createRelationSelectorConfig({
    listQuery: customerListQuery,
    idKey: 'id',
    labelKey: 'emailAddress',
    placeholder: 'Search verified customers...',
    pageSize: 30,
    buildSearchFilter: (term: string) => ({
        and: [
            { user: { verified: { eq: true } } }, // Only verified customers
            {
                or: [
                    { emailAddress: { contains: term } },
                    { firstName: { contains: term } },
                    { lastName: { contains: term } },
                ],
            },
        ],
    }),
});

export function ActiveCustomerSelectorComponent({ value, onChange }: CustomFormComponentInputProps) {
    return <MultiRelationInput value={value || []} onChange={onChange} config={activeCustomerConfig} />;
}
```

## Registration

Register your relation selector components in your dashboard extension:

```tsx title="src/plugins/my-plugin/dashboard/index.tsx"
import { defineDashboardExtension } from '@vendure/dashboard';
import {
    ProductSelectorComponent,
    ReviewSelectorComponent,
    ImageSelectorComponent,
    ActiveCustomerSelectorComponent,
} from './components';

export default defineDashboardExtension({
    detailForms: [
        {
            pageId: 'product-detail',
            inputs: [
                {
                    blockId: 'product-form',
                    field: 'featuredProductId',
                    component: ProductSelectorComponent,
                },
                {
                    blockId: 'product-form',
                    field: 'relatedCustomerIds',
                    component: ActiveCustomerSelectorComponent,
                },
            ],
        },
        {
            pageId: 'collection-detail',
            inputs: [
                {
                    blockId: 'collection-form',
                    field: 'featuredImageId',
                    component: ImageSelectorComponent,
                },
                {
                    blockId: 'collection-form',
                    field: 'featuredReviewId',
                    component: ReviewSelectorComponent,
                },
            ],
        },
    ],
});
```

## Built-in Configurations

The relation selector package includes pre-configured setups for common Vendure entities:

```tsx
import {
    productRelationConfig,
    customerRelationConfig,
    collectionRelationConfig,
    SingleRelationInput,
    MultiRelationInput,
    CustomFormComponentInputProps,
} from '@vendure/dashboard';

// Use pre-built configurations
export function QuickProductSelector({ value, onChange }: CustomFormComponentInputProps) {
    return <SingleRelationInput value={value} onChange={onChange} config={productRelationConfig} />;
}

export function QuickCustomerMultiSelector({ value, onChange }: CustomFormComponentInputProps) {
    return <MultiRelationInput value={value || []} onChange={onChange} config={customerRelationConfig} />;
}
```

## Best Practices

### Query Optimization

1. **Select only needed fields**: Include only the fields you actually use to improve performance
2. **Use fragments**: Create reusable fragments for consistent data fetching
3. **Optimize search filters**: Use database indexes for the fields you search on

```tsx
// Good: Minimal required fields
const productListQuery = graphql(`
    query GetProductsForSelection($options: ProductListOptions) {
        products(options: $options) {
            items {
                id
                name
                # Only include what you need
            }
            totalItems
        }
    }
`);

// Avoid: Over-fetching unnecessary data
const productListQuery = graphql(`
    query GetProductsForSelection($options: ProductListOptions) {
        products(options: $options) {
            items {
                id
                name
                description
                featuredAsset { ... } # Only if you display it
                variants { ... }      # Usually not needed for selection
                # etc.
            }
            totalItems
        }
    }
`);
```

### Performance Tips

1. **Appropriate page sizes**: Balance between fewer requests and faster initial loads
2. **Debounced search**: The default 300ms debounce prevents excessive API calls
3. **Caching**: Queries are automatically cached by TanStack Query

```tsx
const config = createRelationSelectorConfig({
    listQuery: myQuery,
    idKey: 'id',
    labelKey: 'name',
    pageSize: 25, // Good default, adjust based on your data
    buildSearchFilter: (term: string) => ({
        // Use indexed fields for better performance
        name: { contains: term },
    }),
});
```

### Type Safety

Leverage TypeScript generics for full type safety:

```tsx
interface MyEntity {
    id: string;
    title: string;
    status: 'ACTIVE' | 'INACTIVE';
}

const myEntityConfig = createRelationSelectorConfig<MyEntity>({
    listQuery: myEntityQuery,
    idKey: 'id', // ✅ TypeScript knows this must be a key of MyEntity
    labelKey: 'title', // ✅ TypeScript validates this field exists
    buildSearchFilter: (term: string) => ({
        title: { contains: term }, // ✅ Auto-completion and validation
    }),
});
```

### Rich Label Design

When using the `label` prop for custom rendering:

1. **Keep it simple**: Avoid overly complex layouts that might impact performance
2. **Handle missing data**: Always check for optional fields before rendering
3. **Maintain accessibility**: Use proper semantic HTML and alt text for images
4. **Consider mobile**: Ensure labels work well on smaller screens

```tsx
// Good: Simple, robust label design
label: item => (
    <div className="flex items-center gap-2">
        {item.image && <img src={item.image} alt={item.name} className="w-8 h-8 rounded object-cover" />}
        <div className="flex-1 min-w-0">
            <div className="font-medium truncate">{item.name}</div>
            {item.status && <div className="text-sm text-muted-foreground">{item.status}</div>}
        </div>
    </div>
);

// Avoid: Overly complex layouts
label: item => (
    <div className="complex-grid-layout-with-many-nested-elements">
        {/* Too much complexity can hurt performance */}
    </div>
);
```

## Troubleshooting

### Common Issues

**1. "Cannot query field X on type Query"**

```
Error: Cannot query field "myEntities" on type "Query"
```

**Solution**: Ensure your GraphQL query field name matches your schema definition exactly.

**2. Empty results despite data existing**

```tsx
// Problem: Wrong field used for search
buildSearchFilter: (term: string) => ({
    wrongField: { contains: term }, // This field doesn't exist
});

// Solution: Use correct field names
buildSearchFilter: (term: string) => ({
    name: { contains: term }, // Correct field name
});
```

**3. TypeScript errors with config**

```tsx
// Problem: Missing type parameter
const config = createRelationSelectorConfig({
    // TypeScript can't infer the entity type
});

// Solution: Provide explicit type or use proper typing
const config = createRelationSelectorConfig<MyEntityType>({
    // Now TypeScript knows the shape of your entity
});
```

### Performance Issues

If you experience slow loading:

1. **Check your GraphQL query**: Ensure it's optimized and uses appropriate filters
2. **Verify database indexes**: Make sure searched fields are indexed
3. **Adjust page size**: Try smaller page sizes for faster initial loads
4. **Optimize buildSearchFilter**: Use efficient query patterns

```tsx
// Efficient search filter
buildSearchFilter: (term: string) => ({
    name: { contains: term }, // Simple, indexed field
});

// Less efficient
buildSearchFilter: (term: string) => ({
    or: [
        { name: { contains: term } },
        { description: { contains: term } },
        { deepNestedField: { someComplexFilter: term } }, // Avoid deep nesting
    ],
});
```


---

---
title: 'Deployment'
---

The Vendure Dashboard offers flexible deployment options. You can either serve it directly through your Vendure Server using the `DashboardPlugin`, or host it independently as a static site.

## Deployment Options

### Option 1: Serve with DashboardPlugin

The `DashboardPlugin` integrates seamlessly with your Vendure Server by:

- Serving the React dashboard as static files
- Handling routing for the dashboard UI
- Providing a unified deployment experience

### Option 2: Standalone Hosting

The Vendure Dashboard can be hosted independently as a static site, since the build produces standard web assets (index.html, CSS, and JS files). This approach offers maximum flexibility for deployment on any static hosting service.

## Serving with DashboardPlugin

To configure the DashboardPlugin, follow these steps:

### 1. Configure Vite Base Path

Update your `vite.config.mts` to set the base path where the dashboard will be served:

```typescript title="vite.config.mts"
import { vendureDashboardPlugin } from '@vendure/dashboard/vite';
import path from 'path';
import { pathToFileURL } from 'url';
import { defineConfig } from 'vite';

export default defineConfig({
    // highlight-start
    base: '/dashboard/',
    // highlight-end
    plugins: [
        vendureDashboardPlugin({
            vendureConfigPath: pathToFileURL('./src/vendure-config.ts'),
            api: {
                host: 'http://localhost',
                port: 3000,
            },
            gqlOutputPath: path.resolve(__dirname, './src/gql/'),
        }),
    ],
});
```

### 2. Add DashboardPlugin to Vendure Config

:::warning Angular Admin UI compatibilityMode
If you want to use the Admin UI and the Dashboard together please change the [compatibilityMode](/reference/core-plugins/admin-ui-plugin/admin-ui-plugin-options#compatibilitymode) to true.
:::


Add the DashboardPlugin to your `vendure-config.ts`:

```typescript title="src/vendure-config.ts"
import { DashboardPlugin } from '@vendure/dashboard/plugin';
import path from 'path';

export const config: VendureConfig = {
    // ... other config
    plugins: [
        // ... other plugins
        DashboardPlugin.init({
            // highlight-start
            // Important: This must match the base path from vite.config.mts (without slashes)
            route: 'dashboard',
            // highlight-end
            // Path to the Vite build output directory
            appDir: path.join(__dirname, './dist'),
        }),
    ],
};
```

## Building for Production

Before deploying your Vendure application, build the dashboard:

```bash
npx vite build
```

This command creates optimized production files in the `dist` directory that the DashboardPlugin will serve.

## Accessing the Dashboard

Once configured and built, your dashboard will be accessible at:

```
http://your-server-url/dashboard/
```

## Configuration Options

### DashboardPlugin Options

| Option   | Type     | Description                                                                   |
| -------- | -------- | ----------------------------------------------------------------------------- |
| `route`  | `string` | The URL path where the dashboard will be served (must match Vite's base path) |
| `appDir` | `string` | Path to the directory containing the built dashboard files                    |

## Best Practices

1. **Consistent Paths**: Always ensure the `route` in DashboardPlugin matches the `base` in your Vite config
2. **Build Before Deploy**: Add the Vite build step to your deployment pipeline
3. **Production Builds**: Use `npx vite build` for optimized production builds

## Example Deployment Script

```json title="package.json"
{
    "scripts": {
        "build": "npm run build:server && npm run build:dashboard",
        "build:server": "tsc",
        "build:dashboard": "vite build",
        "start:prod": "node ./dist/index.js"
    }
}
```

## Standalone Hosting

The dashboard can be hosted independently from your Vendure Server on any static hosting service (Netlify, Vercel, AWS S3, etc.).

### Configuration

When hosting standalone, you must configure the dashboard to connect to your Admin API endpoint:

```typescript title="vite.config.mts"
import { vendureDashboardPlugin } from '@vendure/dashboard/vite';
import { defineConfig } from 'vite';

export default defineConfig({
    plugins: [
        vendureDashboardPlugin({
            vendureConfigPath: pathToFileURL('./src/vendure-config.ts'),
            // highlight-start
            api: {
                host: process.env.VENDURE_API_HOST || 'https://api.mystore.com',
                port: parseInt(process.env.VENDURE_API_PORT || '443'),
            },
            // highlight-end
            gqlOutputPath: path.resolve(__dirname, './src/gql/'),
        }),
    ],
});
```

:::warning Build-Time Variables
Environment variables are resolved at **build time** and embedded as static strings in the final bundles. Ensure these variables are available during the build process, not just at runtime.
:::

### Build and Deploy

1. **Build the dashboard:**
   ```bash
   npx vite build
   ```

2. **Deploy the contents of the `dist` directory to your hosting service**

### CORS Configuration

When hosting the dashboard separately, configure CORS on your Vendure Server:

```typescript title="src/vendure-config.ts"
export const config: VendureConfig = {
    apiOptions: {
        cors: {
            origin: ['https://dashboard.mystore.com'],
            credentials: true,
        },
    },
    // ... other config
};
```

## Troubleshooting

### Dashboard Not Loading (DashboardPlugin)

- Verify the `route` matches the `base` path in Vite config
- Check that the build output exists in the specified `appDir`
- Ensure the DashboardPlugin is properly initialized in your plugins array

### 404 Errors on Dashboard Routes

- Confirm the base path includes trailing slashes where needed
- Verify the server is running and the plugin is loaded

### Connection Issues (Standalone)

- Verify the API host and port are correct
- Check CORS configuration on your Vendure Server
- Ensure environment variables were available during build


---

---
title: 'Extending the Dashboard'
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

This guide covers the core concepts and best practices for extending the Vendure Dashboard. Understanding these fundamentals will help you build robust and maintainable dashboard extensions.

## Dev Mode

Once you have logged in to the dashboard, you can toggle on "Dev Mode" using the user menu in the bottom left:

![Dev Mode](./dev-mode.webp)

In Dev Mode, hovering any block in the dashboard will allow you to find the corresponding `pageId` and `blockId` values, which you can later use when customizing the dashboard. This is essential for:

- Identifying where to place custom page blocks
- Finding action bar locations
- Understanding the page structure
- Debugging your extensions

![Finding the location ids](./location-id.webp)

## Recommended Folder Structure

While you can organize your dashboard extensions however you prefer (it's a standard React application), we recommend following this convention for consistency and maintainability:

```
src/plugins/my-plugin/
└── dashboard/
    ├── index.tsx           # Main entrypoint linked in plugin decorator
    ├── pages/              # Top-level page components
    ├── routes/             # Route definitions
    ├── form-components/    # Input, custom fields, and display components
    ├── detail-forms/       # Detail form definitions
    └── action-bar/         # Action bar items
```

### Entry Point (index.tsx)

The main entry point that is linked in your plugin decorator:

```tsx title="src/plugins/my-plugin/dashboard/index.tsx"
import { defineDashboardExtension } from '@vendure/dashboard';

export default defineDashboardExtension({
    routes: [],
    navSections: [],
    pageBlocks: [],
    actionBarItems: [],
    alerts: [],
    widgets: [],
    customFormComponents: {},
    dataTables: [],
    detailForms: [],
    login: {},
});
```

:::tip
This folder structure is particularly important when open-sourcing Vendure plugins. Following the official conventions makes it easier for other developers to understand and contribute to your plugin.
:::

## Form Handling

Form handling in the dashboard is powered by [react-hook-form](https://react-hook-form.com/), which is also the foundation for Shadcn's form components. This provides:

- Excellent performance with minimal re-renders
- Built-in validation
- TypeScript support
- Easy integration with the dashboard's UI components

### Basic Form Example

```tsx
import { useForm } from 'react-hook-form';
import { Form, FormFieldWrapper, Input, Button } from '@vendure/dashboard';

function MyForm() {
    const form = useForm({
        defaultValues: {
            name: '',
            email: '',
        },
    });

    const onSubmit = data => {
        console.log(data);
    };

    return (
        <Form {...form}>
            <form onSubmit={form.handleSubmit(onSubmit)}>
                <FormFieldWrapper
                    control={form.control}
                    name="name"
                    label="Name"
                    render={({ field }) => <Input {...field} />}
                />
                <FormFieldWrapper
                    control={form.control}
                    name="email"
                    label="Email"
                    render={({ field }) => <Input type="email" {...field} />}
                />
                <Button type="submit">Submit</Button>
            </form>
        </Form>
    );
}
```

### Advanced Example

For a comprehensive example of advanced form handling, including complex validation, dynamic fields, and custom components, check out the [order detail page implementation](https://github.com/vendure-ecommerce/vendure/blob/master/packages/dashboard/src/app/routes/_authenticated/_orders/orders_.%24id.tsx) in the Vendure source code.

## API Client

The API client is the primary way to send queries and mutations to the Vendure backend. It handles channel tokens and authentication automatically.

### Importing the API Client

```tsx
import { api } from '@vendure/dashboard';
```

The API client exposes two main methods:

- `query` - For GraphQL queries
- `mutate` - For GraphQL mutations

### Using with TanStack Query

The API client is designed to work seamlessly with TanStack Query for optimal data fetching and caching:

#### Query Example

```tsx
import { useQuery } from '@tanstack/react-query';
import { api } from '@vendure/dashboard';
import { graphql } from '@/gql';

const getProductsQuery = graphql(`
    query GetProducts($options: ProductListOptions) {
        products(options: $options) {
            items {
                id
                name
                slug
            }
            totalItems
        }
    }
`);

function ProductList() {
    const { data, isLoading, error } = useQuery({
        queryKey: ['products'],
        queryFn: () =>
            api.query(getProductsQuery, {
                options: {
                    take: 10,
                    skip: 0,
                },
            }),
    });

    if (isLoading) return <div>Loading...</div>;
    if (error) return <div>Error: {error.message}</div>;

    return <ul>{data?.products.items.map(product => <li key={product.id}>{product.name}</li>)}</ul>;
}
```

#### Mutation Example

```tsx
import { useMutation, useQueryClient } from '@tanstack/react-query';
import { api } from '@vendure/dashboard';
import { graphql } from '@/gql';
import { toast } from 'sonner';

const updateProductMutation = graphql(`
    mutation UpdateProduct($input: UpdateProductInput!) {
        updateProduct(input: $input) {
            id
            name
            slug
        }
    }
`);

function ProductForm({ product }) {
    const queryClient = useQueryClient();

    const mutation = useMutation({
        mutationFn: input => api.mutate(updateProductMutation, { input }),
        onSuccess: () => {
            // Invalidate and refetch product queries
            queryClient.invalidateQueries({ queryKey: ['products'] });
            toast.success('Product updated successfully');
        },
        onError: error => {
            toast.error('Failed to update product', {
                description: error.message,
            });
        },
    });

    const handleSubmit = data => {
        mutation.mutate({
            id: product.id,
            ...data,
        });
    };

    return (
        // Form implementation
        <form onSubmit={handleSubmit}>{/* Form fields */}</form>
    );
}
```

## Best Practices

1. **Follow the folder structure**: It helps maintain consistency, especially when sharing plugins
2. **Use TypeScript**: Take advantage of the generated GraphQL types for type safety
3. **Leverage TanStack Query**: Use it for all data fetching to benefit from caching and optimistic updates
4. **Handle errors gracefully**: Always provide user feedback for both success and error states
5. **Use the dashboard's UI components**: Maintain visual consistency with the rest of the dashboard
6. **Test in Dev Mode**: Use Dev Mode to verify your extensions are placed correctly

## What's Next?

Now that you understand the fundamentals of extending the dashboard, explore these specific guides:

- [Navigation](/guides/extending-the-dashboard/navigation/) - Add custom navigation sections
- [Page Blocks](/guides/extending-the-dashboard/page-blocks/) - Enhance existing pages
- [Action Bar Items](/guides/extending-the-dashboard/action-bar-items/) - Add custom actions
- [Custom Form Components](/guides/extending-the-dashboard/custom-form-components/) - Build specialized inputs
- [CMS Tutorial](/guides/extending-the-dashboard/cms-tutorial/) - Complete walkthrough example


---

---
title: 'Getting Started'
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

:::warning
The `@vendure/dashboard` package is currently **RC.1** (release candiate) and can be used in production. 
There won't be any _major_ breaking API changes anymore. **The official release is targeted for the end of September 2025.**
:::

Our new React-based dashboard is currently in the release candidate phase, and you can try it out now!

The goal of the new dashboard:

- Improve the developer experience to make it significantly easier and faster to build customizations
- Reduce boilerplate (repetitive code) by using schema-driven UI generation
- Modern, AI-ready stack using React, Tailwind & Shadcn.
- Built-in type-safety with zero extra configuration

Because the dashboard is in the release candidate phase, not all planned features are available yet. However, enough has been implemented that
you can try it out and give us feedback.

## Installation & Setup

:::note
This guide assumes an existing project based on the `@vendure/create` folder structure.
If you have a different setup (e.g. an Nx monorepo), you may need to adapt the instructions accordingly.
:::

First install the `@vendure/dashboard` package:

```bash
npm install @vendure/dashboard
```

Then create a `vite.config.mts` file in the root of your project (on the same level as your `package.json`) with the following content:

```ts title="vite.config.mts"
import { vendureDashboardPlugin } from '@vendure/dashboard/vite';
import { pathToFileURL } from 'url';
import { defineConfig } from 'vite';
import { resolve, join } from 'path';

export default defineConfig({
    build: {
        outDir: join(__dirname, 'dist/dashboard'),
    },
    plugins: [
        vendureDashboardPlugin({
            // The vendureDashboardPlugin will scan your configuration in order
            // to find any plugins which have dashboard extensions, as well as
            // to introspect the GraphQL schema based on any API extensions
            // and custom fields that are configured.
            vendureConfigPath: pathToFileURL('./src/vendure-config.ts'),
            // Points to the location of your Vendure server.
            api: { host: 'http://localhost', port: 3000 },
            // When you start the Vite server, your Admin API schema will
            // be introspected and the types will be generated in this location.
            // These types can be used in your dashboard extensions to provide
            // type safety when writing queries and mutations.
            gqlOutputPath: './src/gql',
        }),
    ],
    resolve: {
        alias: {
            // This allows all plugins to reference a shared set of
            // GraphQL types.
            '@/gql': resolve(__dirname, './src/gql/graphql.ts'),
        },
    },
});
```

You should also add the following to your existing `tsconfig.json` file to exclude the dashboard extensions and Vite config
from your build.

```json title="tsconfig.json"
{
    // ... existing options
    "exclude": [
        "node_modules",
        "migration.ts",
        "src/plugins/**/ui/*",
        "admin-ui",
        // highlight-start
        "src/plugins/**/dashboard/*",
        "vite.*.*ts"
        // highlight-end
    ],
    "references": [
        {
            "path": "./tsconfig.dashboard.json"
        }
    ]
}
```

Now create a new `tsconfig.dashboard.json` to allow your IDE
to correctly resolve imports of GraphQL types & interpret JSX in your dashboard extensions:

```json title="tsconfig.dashboard.json"
{
    "compilerOptions": {
        "module": "nodenext",
        "moduleResolution": "nodenext",
        "jsx": "react-jsx",
        "paths": {
            // Import alias for the GraphQL types
            // Please adjust to the location that you have set in your `vite.config.mts`
            "@/gql": ["./src/gql/graphql.ts"],
            // This line allows TypeScript to properly resolve internal
            // Vendure Dashboard imports, which is necessary for
            // type safety in your dashboard extensions.
            // This path assumes a root-level tsconfig.json file.
            // You may need to adjust it if your project structure is different.
            "@/vdb/*": ["./node_modules/@vendure/dashboard/src/lib/*"]
        }
    },
    "include": ["src/plugins/**/dashboard/*", "src/gql/**/*.ts"]
}
```

## Running the Dashboard

Now you can run the dashboard in development mode with:

```bash
npx vite
```

To stop the running dashboard, type `q` and hit enter.

## What's Next?

Now that you have the dashboard up and running, you can start extending it:

- [Extending the Dashboard](/guides/extending-the-dashboard/extending-overview/) - Core concepts and best practices
- [Navigation](/guides/extending-the-dashboard/navigation/) - Add custom navigation sections and menu items
- [Page Blocks](/guides/extending-the-dashboard/page-blocks/) - Add custom blocks to existing pages
- [Action Bar Items](/guides/extending-the-dashboard/action-bar-items/) - Add custom buttons to page action bars
- [Tech Stack](/guides/extending-the-dashboard/tech-stack/) - Learn about the technologies used in the dashboard
- [Dashboard Theming](/guides/extending-the-dashboard/theming) - Customize the look and feel of the dashboard
- [CMS Tutorial](/guides/extending-the-dashboard/cms-tutorial/) - Complete tutorial showing how to build a CMS plugin with custom pages and forms

## Still to come

We hope this gives you a taste of what is possible with the new dashboard.

We're still working to bring feature-parity with the existing Admin UI - so support for things like:

- history timeline components
- translations of the dashboard itself

The final release (expected Q3 2025) will also include much more extensive documentation & guides.


---

---
title: 'Navigation'
---

The dashboard provides a flexible navigation system that allows you to add custom navigation sections and menu items. Navigation items are organized into sections that can be placed in either the "Platform" (top) or "Administration" (bottom) areas of the sidebar.

## Adding Navigation Items to Existing Sections

The simplest way to add navigation is to add menu items to existing sections. This is done automatically when you define routes with `navMenuItem` properties.

```tsx title="src/plugins/my-plugin/dashboard/index.tsx"
import { defineDashboardExtension } from '@vendure/dashboard';

export default defineDashboardExtension({
    routes: [
        {
            path: '/my-custom-page',
            component: () => <div>My Custom Page</div>,
            navMenuItem: {
                // The section where this item should appear
                sectionId: 'catalog',
                // Unique identifier for this menu item
                id: 'my-custom-page',
                // Display text in the navigation
                title: 'My Custom Page',
                // Optional: URL if different from path
                url: '/my-custom-page',
            },
        },
    ],
});
```

### Available Section IDs

The dashboard comes with several built-in sections:

- **`catalog`** - For product-related functionality
- **`orders`** - For order management
- **`customers`** - For customer management
- **`marketing`** - For promotions and marketing tools
- **`settings`** - For configuration and admin settings

## Creating Custom Navigation Sections

You can create entirely new navigation sections with their own icons and ordering:

```tsx title="src/plugins/my-plugin/dashboard/index.tsx"
import { defineDashboardExtension } from '@vendure/dashboard';
import { FileTextIcon, SettingsIcon } from 'lucide-react';

export default defineDashboardExtension({
    // Define custom navigation sections
    navSections: [
        {
            id: 'content-management',
            title: 'Content',
            icon: FileTextIcon,
            placement: 'top', // Platform area
            order: 350, // After Customers (400), before Marketing (500)
        },
        {
            id: 'integrations',
            title: 'Integrations',
            icon: SettingsIcon,
            placement: 'bottom', // Administration area
            order: 150, // Between System (100) and Settings (200)
        },
    ],
    routes: [
        {
            path: '/articles',
            component: () => <div>Articles</div>,
            navMenuItem: {
                sectionId: 'content-management', // Use our custom section
                id: 'articles',
                title: 'Articles',
            },
        },
        {
            path: '/pages',
            component: () => <div>Pages</div>,
            navMenuItem: {
                sectionId: 'content-management',
                id: 'pages',
                title: 'Pages',
            },
        },
    ],
});
```

## Navigation Section Properties

### Required Properties

- **`id`**: Unique identifier for the section
- **`title`**: Display name shown in the navigation

### Optional Properties

- **`icon`**: Lucide React icon component to display next to the section title
- **`order`**: Number controlling the position of the section within its placement area (lower numbers appear first)
- **`placement`**: Either `'top'` or `'bottom'` - determines which area of the sidebar the section appears in

## Navigation Item Properties

### Required Properties

- **`sectionId`**: ID of the section where this item should appear
- **`id`**: Unique identifier for the menu item
- **`title`**: Display text for the menu item

### Optional Properties

- **`url`**: Custom URL if different from the route path
- **`icon`**: Icon for the individual menu item (rarely used as sections typically have icons)

## Section Placement and Ordering

The navigation sidebar is divided into two areas:

- **Top Placement (`'top'`)**: The "Platform" area for core functionality (Dashboard, Catalog, Sales, etc.)
- **Bottom Placement (`'bottom'`)**: The "Administration" area for system and configuration sections (System, Settings)

### Placement Examples

```tsx
export default defineDashboardExtension({
    navSections: [
        {
            id: 'reports',
            title: 'Reports',
            icon: BarChartIcon,
            placement: 'top', // Appears in Platform area
            order: 150, // Positioned within top sections
        },
        {
            id: 'integrations',
            title: 'Integrations',
            icon: PlugIcon,
            placement: 'bottom', // Appears in Administration area
            order: 150, // Positioned within bottom sections
        },
    ],
});
```

### Order Scoping

:::important Order Scoping
Order values are scoped within each placement area. This means:

- Top sections compete only with other top sections for positioning
- Bottom sections compete only with other bottom sections for positioning
- You can use the same order value in both top and bottom without conflict
  :::

### Default Section Orders

**Top Placement (Platform):**

- Dashboard: 100
- Catalog: 200
- Sales: 300
- Customers: 400
- Marketing: 500

**Bottom Placement (Administration):**

- System: 100
- Settings: 200

This means if you want to add a section between Catalog and Sales in the top area, you might use `order: 250`. If you want to add a section before Settings in the bottom area, you could use `order: 150`.

:::note Default Placement
If you don't specify a `placement`, sections default to `'top'` placement.
:::

## Complete Example

Here's a comprehensive example showing how to create a complete navigation structure for a content management system:

```tsx title="src/plugins/cms/dashboard/index.tsx"
import { defineDashboardExtension } from '@vendure/dashboard';
import { FileTextIcon, ImageIcon, TagIcon, FolderIcon, SettingsIcon } from 'lucide-react';

export default defineDashboardExtension({
    // Create custom navigation sections
    navSections: [
        {
            id: 'content',
            title: 'Content',
            icon: FileTextIcon,
            placement: 'top', // Platform area
            order: 250, // Between Catalog (200) and Sales (300)
        },
        {
            id: 'media',
            title: 'Media',
            icon: ImageIcon,
            placement: 'top', // Platform area
            order: 275, // After Content section
        },
    ],

    routes: [
        // Content section items
        {
            path: '/articles',
            component: () => <div>Articles List</div>,
            navMenuItem: {
                sectionId: 'content',
                id: 'articles',
                title: 'Articles',
            },
        },
        {
            path: '/pages',
            component: () => <div>Pages List</div>,
            navMenuItem: {
                sectionId: 'content',
                id: 'pages',
                title: 'Pages',
            },
        },
        {
            path: '/categories',
            component: () => <div>Categories List</div>,
            navMenuItem: {
                sectionId: 'content',
                id: 'categories',
                title: 'Categories',
            },
        },

        // Media section items
        {
            path: '/media-library',
            component: () => <div>Media Library</div>,
            navMenuItem: {
                sectionId: 'media',
                id: 'media-library',
                title: 'Library',
            },
        },
        {
            path: '/media-folders',
            component: () => <div>Media Folders</div>,
            navMenuItem: {
                sectionId: 'media',
                id: 'media-folders',
                title: 'Folders',
            },
        },

        // Add to existing settings section
        {
            path: '/cms-settings',
            component: () => <div>CMS Settings</div>,
            navMenuItem: {
                sectionId: 'settings',
                id: 'cms-settings',
                title: 'CMS Settings',
            },
        },
    ],
});
```

## Icons

The dashboard uses [Lucide React](https://lucide.dev/) icons. You can import any icon from the library:

```tsx
import {
    HomeIcon,
    ShoppingCartIcon,
    UsersIcon,
    SettingsIcon,
    FileTextIcon,
    ImageIcon,
    BarChartIcon,
    // ... any other Lucide icon
} from 'lucide-react';
```

Common icons for navigation sections:

- **Content**: `FileTextIcon`, `EditIcon`, `BookOpenIcon`
- **Media**: `ImageIcon`, `FolderIcon`, `UploadIcon`
- **Analytics**: `BarChartIcon`, `TrendingUpIcon`, `PieChartIcon`
- **Tools**: `WrenchIcon`, `SettingsIcon`, `CogIcon`
- **Integrations**: `LinkIcon`, `ZapIcon`, `PlugIcon`

## Best Practices

:::tip Navigation Design Guidelines

1. **Use descriptive section names**: Choose clear, concise names that indicate the section's purpose
2. **Group related functionality**: Keep logically related menu items in the same section
3. **Choose appropriate icons**: Select icons that clearly represent the section's function
4. **Consider ordering carefully**: Place frequently used sections earlier in the navigation
5. **Keep section counts reasonable**: Avoid creating too many sections as it can clutter the navigation
6. **Use consistent naming**: Follow consistent patterns for menu item names within sections
   :::

## Finding Existing Sections

:::info Discovering Section IDs
To see what navigation sections are available, you can:

1. Enable [Dev Mode](/guides/extending-the-dashboard/extending-overview/#dev-mode) in the dashboard
2. Examine the navigation sidebar to see section IDs
3. Look at other plugins' navigation configuration for examples
   :::

This gives you complete control over how your dashboard extensions integrate with the navigation system, allowing you to create a cohesive and well-organized user experience.


---

---
title: 'Page Blocks'
---

In the Dashboard, all pages are built from blocks. Every block has a `pageId` and a `blockId` which uniquely locates it in the
app (see [Dev Mode](/guides/extending-the-dashboard/extending-overview/#dev-mode) section).

You can also define your own blocks, which can be added to any page and can even replace the default blocks.

## Basic Page Block Example

Here's an example of how to define a custom page block:

```tsx title="src/plugins/my-plugin/dashboard/index.tsx"
import { defineDashboardExtension } from '@vendure/dashboard';

export default defineDashboardExtension({
    pageBlocks: [
        {
            id: 'related-articles',
            title: 'Related Articles',
            location: {
                // This is the pageId of the page where this block will be
                pageId: 'product-detail',
                // can be "main" or "side"
                column: 'side',
                position: {
                    // Blocks are positioned relative to existing blocks on
                    // the page.
                    blockId: 'facet-values',
                    // Can be "before", "after" or "replace"
                    // Here we'll place it after the `facet-values` block.
                    order: 'after',
                },
            },
            component: ({ context }) => {
                // In the component, you can use the `context` prop to
                // access the entity and the form instance.
                return <div className="text-sm">Articles related to {context.entity.name}</div>;
            },
        },
    ],
});
```

This will add a "Related Articles" block to the product detail page:

![Related Articles page block](../getting-started/page-block.webp)

## Block Positioning

Page blocks can be positioned in three ways relative to existing blocks:

### Before

Places the block before the specified `blockId`:

```tsx
position: {
    blockId: 'product-variants',
    order: 'before'
}
```

### After

Places the block after the specified `blockId`:

```tsx
position: {
    blockId: 'product-variants',
    order: 'after'
}
```

### Replace

Replaces the existing block entirely:

```tsx
position: {
    blockId: 'product-variants',
    order: 'replace'
}
```

## Block Columns

Blocks can be placed in two columns:

- **`main`**: The main content area (wider column on the left)
- **`side`**: The sidebar area (narrower column on the right)

## Context Data

The `context` prop provides access to:

- **`entity`**: The current entity being viewed/edited (e.g., Product, Customer, etc.)
- **`form`**: The React Hook Form instance for the current page (if applicable)
- **`route`**: Route information and parameters

## Advanced Example

Here's a more complex example that shows different types of blocks:

```tsx title="src/plugins/my-plugin/dashboard/index.tsx"
import { defineDashboardExtension, Button } from '@vendure/dashboard';
import { useState } from 'react';

export default defineDashboardExtension({
    pageBlocks: [
        // Analytics block for product page
        {
            id: 'product-analytics',
            title: 'Product Analytics',
            location: {
                pageId: 'product-detail',
                column: 'side',
                position: {
                    blockId: 'product-assets',
                    order: 'after',
                },
            },
            component: ({ context }) => {
                const product = context.entity;
                return (
                    <div className="space-y-2">
                        <div className="text-sm text-muted-foreground">Last 30 days</div>
                        <div className="grid grid-cols-2 gap-4">
                            <div>
                                <div className="text-2xl font-bold">142</div>
                                <div className="text-xs text-muted-foreground">Views</div>
                            </div>
                            <div>
                                <div className="text-2xl font-bold">23</div>
                                <div className="text-xs text-muted-foreground">Orders</div>
                            </div>
                        </div>
                    </div>
                );
            },
        },
        // Quick actions block
        {
            id: 'quick-actions',
            title: 'Quick Actions',
            location: {
                pageId: 'product-detail',
                column: 'main',
                position: {
                    blockId: 'product-variants',
                    order: 'after',
                },
            },
            component: ({ context }) => {
                const [isProcessing, setIsProcessing] = useState(false);

                const handleSync = async () => {
                    setIsProcessing(true);
                    // Simulate API call
                    await new Promise(resolve => setTimeout(resolve, 2000));
                    setIsProcessing(false);
                };

                return (
                    <div className="flex gap-2">
                        <Button variant="outline" onClick={handleSync} disabled={isProcessing}>
                            {isProcessing ? 'Syncing...' : 'Sync to External System'}
                        </Button>
                        <Button variant="outline">Generate QR Code</Button>
                    </div>
                );
            },
        },
    ],
});
```

## Finding Block IDs

To find the `pageId` and `blockId` values for positioning your blocks:

1. Enable [Dev Mode](/guides/extending-the-dashboard/extending-overview/#dev-mode) in the dashboard
2. Navigate to the page where you want to add your block
3. Hover over existing blocks to see their IDs
4. Use these IDs in your block positioning configuration

## TypeScript Support

The dashboard provides full TypeScript support for page blocks. The `context` prop is typed based on the page you're targeting, giving you autocomplete and type safety for the entity properties.

## Best Practices

1. **Use descriptive IDs**: Choose clear, unique IDs for your blocks
2. **Position thoughtfully**: Consider the user experience when placing blocks
3. **Handle loading states**: Show appropriate loading indicators for async operations
4. **Follow design patterns**: Use the dashboard's existing UI components for consistency
5. **Test thoroughly**: Verify your blocks work correctly on different screen sizes


---

---
title: 'Tech Stack'
---

The Vendure Dashboard is built on a modern stack of technologies that provide a great developer experience and powerful capabilities for building custom extensions.

## Core Technologies

### React 19

The dashboard is built with React 19, giving you access to all the latest React features including:

- React Compiler optimizations
- Improved concurrent features
- Actions and form handling improvements
- Enhanced automatic batching
- Better TypeScript support
- New hooks like `useOptimistic` and `useFormStatus`

```tsx
import { useOptimistic, useFormStatus } from 'react';

function OptimisticUpdateExample() {
    const [optimisticState, addOptimistic] = useOptimistic(state, (currentState, optimisticValue) => {
        // Return new state with optimistic update
        return [...currentState, optimisticValue];
    });

    return (
        <div>
            {optimisticState.map(item => (
                <div key={item.id}>{item.name}</div>
            ))}
        </div>
    );
}

function SubmitButton() {
    const { pending } = useFormStatus();

    return (
        <button type="submit" disabled={pending}>
            {pending ? 'Saving...' : 'Save'}
        </button>
    );
}
```

### TypeScript

Full TypeScript support throughout the dashboard provides:

- Type safety for your custom components
- IntelliSense and autocomplete in your IDE
- Compile-time error checking
- Generated types from your GraphQL schema

### Vite 6

Vite 6 powers the development experience with:

- Lightning-fast hot module replacement (HMR)
- Optimized build process with Rollup 4
- Modern ES modules support
- Rich plugin ecosystem
- Environment API for better multi-environment support

## UI Framework

### Tailwind CSS v4

The dashboard uses Tailwind CSS v4 for styling:

- Utility-first CSS framework
- Improved performance with Rust-based engine
- Enhanced CSS-first configuration
- Responsive design system
- Built-in dark mode support
- Customizable design tokens

```tsx
// Example using Tailwind classes
function MyComponent() {
    return (
        <div className="p-4 bg-white dark:bg-gray-800 rounded-lg shadow-md">
            <h2 className="text-lg font-semibold text-gray-900 dark:text-white">My Custom Component</h2>
        </div>
    );
}
```

### Shadcn/ui

Built on top of Radix UI primitives, Shadcn/ui provides:

- Accessible components out of the box
- Consistent design system
- Customizable component library
- Copy-and-paste component approach

```tsx
import { Button, Input, Card } from '@vendure/dashboard';

function MyForm() {
    return (
        <Card className="p-6">
            <Input placeholder="Enter your text" />
            <Button className="mt-4">Submit</Button>
        </Card>
    );
}
```

## State Management

### TanStack Query v5

TanStack Query v5 handles all server state management:

- Automatic caching and synchronization
- Background updates
- Optimistic updates
- Error handling and retry logic

```tsx
import { useQuery } from '@tanstack/react-query';
import { graphql } from '@/gql';

const getProductsQuery = graphql(`
    query GetProducts {
        products {
            items {
                id
                name
                slug
            }
        }
    }
`);

function ProductList() {
    const { data, isLoading, error } = useQuery({
        queryKey: ['products'],
        queryFn: () => client.request(getProductsQuery),
    });

    if (isLoading) return <div>Loading...</div>;
    if (error) return <div>Error: {error.message}</div>;

    return (
        <ul>
            {data.products.items.map(product => (
                <li key={product.id}>{product.name}</li>
            ))}
        </ul>
    );
}
```

## Routing

### TanStack Router v1

Type-safe routing with:

- File-based routing
- 100% type-safe navigation
- Automatic route validation
- Search params handling
- Built-in caching and preloading
- Route-level code splitting

```tsx
import { Link, useNavigate } from '@tanstack/react-router';

function Navigation() {
    const navigate = useNavigate();

    return (
        <div>
            <Link to="/products">Products</Link>
            <button onClick={() => navigate({ to: '/customers' })}>Go to Customers</button>
        </div>
    );
}
```

## Forms

### React Hook Form

Powerful form handling with:

- Minimal re-renders
- Built-in validation
- TypeScript support
- Easy integration with UI libraries

```tsx
import { useForm } from 'react-hook-form';
import { FormFieldWrapper, Input, Button } from '@vendure/dashboard';

interface FormData {
    name: string;
    email: string;
}

function MyForm() {
    const form = useForm<FormData>();

    const onSubmit = (data: FormData) => {
        console.log(data);
    };

    return (
        <form onSubmit={form.handleSubmit(onSubmit)}>
            <FormFieldWrapper
                control={form.control}
                name="name"
                label="Name"
                render={({ field }) => <Input {...field} />}
            />
            <FormFieldWrapper
                control={form.control}
                name="email"
                label="Email"
                render={({ field }) => <Input type="email" {...field} />}
            />
            <Button type="submit">Submit</Button>
        </form>
    );
}
```

## GraphQL Integration

### gql.tada

Type-safe GraphQL with:

- Generated TypeScript types
- IntelliSense for queries and mutations
- Compile-time validation
- Schema introspection

```tsx
import { graphql } from '@/gql';
import { useMutation } from '@tanstack/react-query';

const createProductMutation = graphql(`
    mutation CreateProduct($input: CreateProductInput!) {
        createProduct(input: $input) {
            id
            name
            slug
        }
    }
`);

function CreateProductForm() {
    const mutation = useMutation({
        mutationFn: (input: CreateProductInput) => client.request(createProductMutation, { input }),
    });

    // TypeScript knows the exact shape of the input and response
    const handleSubmit = (data: CreateProductInput) => {
        mutation.mutate(data);
    };

    return (
        // Form implementation
        <div>Create Product Form</div>
    );
}
```

## Notifications

### Sonner

Toast notifications with:

- Beautiful animations
- Customizable appearance
- Promise-based notifications
- Stacking support

```tsx
import { toast } from 'sonner';

function MyComponent() {
    const handleSave = async () => {
        try {
            await saveData();
            toast.success('Data saved successfully!');
        } catch (error) {
            toast.error('Failed to save data', {
                description: error.message,
            });
        }
    };

    // Promise-based toasts
    const handleAsyncAction = () => {
        toast.promise(performAsyncAction(), {
            loading: 'Saving...',
            success: 'Saved successfully!',
            error: 'Failed to save',
        });
    };

    return (
        <div>
            <button onClick={handleSave}>Save</button>
            <button onClick={handleAsyncAction}>Async Save</button>
        </div>
    );
}
```

## Icons

### Lucide React

Beautiful, customizable icons:

- Consistent design
- Tree-shakeable
- Customizable size and color
- Accessible by default

```tsx
import { ShoppingCartIcon, UserIcon, SettingsIcon } from 'lucide-react';

function Navigation() {
    return (
        <nav className="flex space-x-4">
            <a href="/products" className="flex items-center">
                <ShoppingCartIcon className="mr-2 h-4 w-4" />
                Products
            </a>
            <a href="/customers" className="flex items-center">
                <UserIcon className="mr-2 h-4 w-4" />
                Customers
            </a>
            <a href="/settings" className="flex items-center">
                <SettingsIcon className="mr-2 h-4 w-4" />
                Settings
            </a>
        </nav>
    );
}
```

## Animations

### Motion

Smooth animations powered by Motion (successor to Framer Motion):

- High-performance animations
- Declarative API
- Spring-based animations
- Layout animations
- Gesture support

```tsx
import { motion } from 'motion/react';

function AnimatedCard({ children }) {
    return (
        <motion.div
            initial={{ opacity: 0, y: 20 }}
            animate={{ opacity: 1, y: 0 }}
            exit={{ opacity: 0, y: -20 }}
            className="bg-white p-6 rounded-lg shadow"
        >
            {children}
        </motion.div>
    );
}
```

## Internationalization

### Lingui

Powerful i18n solution for React:

- ICU MessageFormat support
- Automatic message extraction
- TypeScript integration
- Pluralization support
- Compile-time optimization

```tsx
import { Trans, useLingui } from '@/lib/trans.js';

function MyComponent() {
    const { t } = useLingui();

    return (
        <div>
            <h1>
                <Trans>Welcome to Dashboard</Trans>
            </h1>
            <p>{t`Click here to continue`}</p>
        </div>
    );
}
```

## Development Tools

### ESLint & Prettier

Code quality and formatting:

- Consistent code style
- Error prevention
- Automatic formatting
- TypeScript support

### Hot Module Replacement

Development experience:

- Instant updates without page refresh
- Preserves component state
- Error overlay
- Fast development cycle

## Best Practices

### Component Composition

Build reusable components:

```tsx
import { Card, Button } from '@vendure/dashboard';

function ProductCard({ product, onEdit, onDelete }) {
    return (
        <Card className="p-4">
            <h3 className="font-semibold">{product.name}</h3>
            <p className="text-sm text-gray-600">{product.description}</p>
            <div className="flex space-x-2 mt-4">
                <Button variant="outline" onClick={() => onEdit(product)}>
                    Edit
                </Button>
                <Button variant="destructive" onClick={() => onDelete(product)}>
                    Delete
                </Button>
            </div>
        </Card>
    );
}
```

### Custom Hooks

Extract reusable logic:

```tsx
import { useState, useEffect } from 'react';
import { useQuery } from '@tanstack/react-query';

function useProduct(productId: string) {
    const { data, isLoading, error } = useQuery({
        queryKey: ['product', productId],
        queryFn: () => fetchProduct(productId),
    });

    return {
        product: data,
        isLoading,
        error,
    };
}

function ProductDetail({ productId }: { productId: string }) {
    const { product, isLoading, error } = useProduct(productId);

    if (isLoading) return <div>Loading...</div>;
    if (error) return <div>Error: {error.message}</div>;

    return <div>{product.name}</div>;
}
```

## Performance Considerations

1. **React.memo()** for expensive components
2. **useMemo()** and **useCallback()** for expensive calculations
3. **React Query caching** for server state
4. **Code splitting** with dynamic imports
5. **Image optimization** with proper formats and sizes

The dashboard's modern tech stack provides a solid foundation for building powerful, maintainable extensions while ensuring a great developer experience.


---

---
title: 'Dashboard Theming'
---

The Vendure dashboard uses a modern theming system based on **CSS custom properties** and [Tailwind CSS](https://tailwindcss.com/) . This guide shows you how to customize the colors and styles by modifying the theme variables in the Vite plugin.

The dashboard also uses the same theming methodology as [shadcn/ui](https://ui.shadcn.com/docs/theming)

It also uses the [shadcn theme provider implementation](https://ui.shadcn.com/docs/dark-mode/vite) for Vite

## Using Themes in Your Components

The Vendure dashboard provides a simple way to access theme variables in your components. Here's how to use them:

### Using Tailwind Classes

The easiest way to use theme colors is through Tailwind variable CSS classes:

```tsx
function ProductIdWidgetComponent() {
    return (
        <div className="text-sm">
            <p>
                This is a custom widget for the product:
                <strong className="ml-1 text-foreground">{product.name}</strong>
            </p>
            <p className="mt-2 text-muted-foreground">Product ID: {product.id}</p>
        </div>
    );
}
```

## Customizing Theme Colors

You can customize the dashboard theme colors by modifying the `theme` configuration in your `vite.config.mts` file. Here's an example showing how to change the primary brand colors:

```typescript
// vite.config.mts
import { vendureDashboardPlugin } from "@vendure/dashboard/plugin";
import { defineConfig } from "vite";
// ...other imports


export default defineConfig({
  plugins: [
    vendureDashboardPlugin({
      vendureConfigPath: "./src/vendure-config.ts",
      adminUiConfig: { apiHost: "http://localhost", apiPort: 3000 },
      gqlOutputPath: "./src/gql",

      // Theme section
      theme: {
        light: {
          // Change the primary brand color to blue
          primary: "oklch(0.55 0.18 240)",
          "primary-foreground": "oklch(0.98 0.01 240)",
          
          // Update the brand colors to match
          brand: "#2563eb", // Blue-600
          "brand-lighter": "#93c5fd", // Blue-300
        },
        dark: {
          // Corresponding dark mode colors
          primary: "oklch(0.65 0.16 240)",
          "primary-foreground": "oklch(0.12 0.03 240)",
          
          // Same brand colors work for both themes
          brand: "#2563eb",
          "brand-lighter": "#93c5fd",
        },
      },

    }),
  ],
});
```

## Inspecting element colors in the browser

To identify the exact color values used by dashboard elements, you can use your browser's developer tools:

- Right-click on any element and select "Inspect" to open the developer panel.
- Navigate to the **Styles** tab.
- From there, you can examine the CSS properties and see the actual color values (hex codes, RGB values, or CSS custom properties) being applied to that element.

![inspection-gif](show-colour-value-inspection.gif)

## Available Theme Variables

The dashboard defines comprehensive theme variables that are automatically available as Tailwind classes:

### Core Colors

| Variable | Description |
|----------|-------------|
| `--background` | Main background |
| `--foreground` | Main text color |
| `--card` | Card background |
| `--card-foreground` | Card text |
| `--popover` | Popover background |
| `--popover-foreground` | Popover text |

### Interactive Colors

| Variable | Description |
|----------|-------------|
| `--primary` | Primary brand color |
| `--primary-foreground` | Text on primary |
| `--secondary` | Secondary actions |
| `--secondary-foreground` | Text on secondary |
| `--accent` | Accent elements |
| `--accent-foreground` | Text on accent |

### Semantic Colors

| Variable | Description |
|----------|-------------|
| `--destructive` | Error/danger actions |
| `--destructive-foreground` | Text on destructive |
| `--success` | Success states |
| `--success-foreground` | Text on success |
| `--muted` | Muted elements |
| `--muted-foreground` | Muted text |

### Border and Input Colors

| Variable | Description |
|----------|-------------|
| `--border` | Border color |
| `--input` | Input background |
| `--ring` | Focus ring color |

### Chart Colors

| Variable | Description |
|----------|-------------|
| `--chart-1` | Chart color 1 |
| `--chart-2` | Chart color 2 |
| `--chart-3` | Chart color 3 |
| `--chart-4` | Chart color 4 |
| `--chart-5` | Chart color 5 |

### Sidebar Colors

| Variable | Description |
|----------|-------------|
| `--sidebar` | Sidebar background |
| `--sidebar-foreground` | Sidebar text |
| `--sidebar-primary` | Sidebar primary |
| `--sidebar-primary-foreground` | Text on sidebar primary |
| `--sidebar-accent` | Sidebar accent |
| `--sidebar-accent-foreground` | Text on sidebar accent |
| `--sidebar-border` | Sidebar border |
| `--sidebar-ring` | Sidebar focus ring |

### Brand Colors

| Variable | Description |
|----------|-------------|
| `--brand` | Primary brand color |
| `--brand-lighter` | Lighter brand variant |
| `--brand-darker` | Darker brand variant |

| Variable | Description |
|----------|-------------|
| `dev-mode` | Dev-mode ring |
| `dev-mode-foreground` | Dev-mode foreground |

### Typography

| Variable | Description |
|----------|-------------|
| `--font-sans` | Sans-serif font |
| `--font-mono` | Monospace font |

### Border Radius

| Variable | Description |
|----------|-------------|
| `--radius` | Base border radius |


---

---
title: Introducing GraphQL
---
import Playground from '@site/src/components/Playground';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

:::info

Vendure uses [GraphQL](https://graphql.org/) as its API layer.

This is an introduction to GraphQL for those who are new to it. If you are already familiar with GraphQL, you may choose
to skip this section.

:::

## What is GraphQL?

From [graphql.org](https://graphql.org/):

> GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.

To put it simply: GraphQL allows you to fetch data from an API via _queries_, and to update data via _mutations_.

Here's a GraphQL query which fetches the product with the slug "football":

<Playground api="shop" document={`
query GetProduct {
    product(slug: "football") {
      id
      name
      slug
    }
}
`} />


## GraphQL vs REST

If you are familiar with REST-style APIs, you may be wondering how GraphQL differs. Here are the key ways in which GraphQL differs from REST:

- GraphQL uses **a single endpoint**, whereas REST uses a different endpoint for each resource.
- GraphQL allows you to **specify exactly which fields** you want to fetch, whereas REST APIs usually return all fields by default.
- GraphQL allows you to fetch data from **multiple resources** in a single request (e.g. "fetch a customer including their last 5 orders"), whereas REST APIs usually require you to make multiple requests.
- GraphQL APIs are always defined by a **statically typed schema**, whereas REST APIs do not have this guarantee.

## Why GraphQL?

Both GraphQL and REST are valid approaches to building an API. These are some of the reasons we chose GraphQL when building Vendure:

- **No over-fetching**: With REST, you often end up fetching more data than you need. For example, if you want to fetch a list of products, you might end up fetching the product name, description, price, and other fields. With GraphQL, you can specify exactly which fields you want to fetch, so you only fetch the data you need. This
    can result in a significant reduction in the amount of data transferred over the network.
- **Many resources in a single request**: Very often, a single page in a web app will need to fetch data from multiple resources. For example, a product detail page might need to fetch the product, the product's variants, the product's collections, the product's reviews, and the product's images. With REST, this would require multiple requests. With GraphQL, you can fetch all of this data in a single request.
- **Static typing**: GraphQL APIs are always defined by a statically typed schema. This means that you can be sure that the data you receive from the API will always be in the format you expect.
- **Developer tooling**: The schema definition allows for powerful developer tooling. For example, the GraphQL Playground above with auto-complete and full documentation is generated automatically from the schema definition. You can also get auto-complete and type-checking directly in your IDE.
- **Code generation**: TypeScript types can be generated automatically from the schema definition. This means that you can be sure that your frontend code is always in sync with the API. This end-to-end type safety is extremely valuable, especially when working on large projects or with teams. See the [GraphQL Code Generation guide](/guides/storefront/codegen/)
- **Extensible**: Vendure is designed with extensibility in mind, and GraphQL is a perfect fit. You can extend the GraphQL API with your own custom queries, mutations, and types. You can also extend the built-in types with your own custom fields, or supply you own custom logic to resolve existing fields. See the [Extend the GraphQL API guide](/guides/developer-guide/extend-graphql-api/)

## GraphQL Terminology

Let's clear up some of the terminology used in GraphQL.

### Types & Fields

GraphQL has a type system which works in a similar way to other statically typed languages like TypeScript.

Here is an example of a GraphQL type:

```graphql
type Customer {
  id: ID!
  name: String!
  email: String!
}
```

The `Customer` is an **object type**, and it has three **fields**: `id`, `name`, and `email`. Each field has a **type** (e.g. `ID!` or `String!`), which
can refer to either a **scalar type** (a "primitive" type which does not have any fields, but represents a single value) or another object type.

GraphQL has a number of built-in scalar types, including `ID`, `String`, `Int`, `Float`, `Boolean`. Vendure further defines a few custom scalar types: `DateTime`, `JSON`, `Upload` & `Money`.
It is also possible to define your own custom scalar types if required.

The `!` symbol after the type name indicates that the field is **required** (it cannot be `null`). If a field does not have the `!` symbol, it is **optional** (it can be `null`).

Here's another example of a couple of types:

```graphql
type Order {
  id: ID!
  orderPlacedAt: DateTime
  isActive: Boolean!
  customer: Customer!
  lines: [OrderLine!]!
}

type OrderLine {
  id: ID!
  productId: ID!
  quantity: Int!
}
```

Here the `Order` type has a field called `customer` which is of type `Customer`. The `Order` type also has a field called `lines` which is a list (an array) of `OrderLine` objects.

In GraphQL, lists are denoted by square brackets (`[]`). The `!` symbol inside the square brackets indicates that the list cannot contain `null` values.

:::note
The types given here are not the actual types used in the Vendure GraphQL schema, but are used here for illustrative purposes.
:::

### Query & Mutation types

There are two special types in GraphQL: `Query` and `Mutation`. These are the entry points into the API.

The `Query` type is used for fetching data, and the `Mutation` type is used for updating data.

Here is an example of a query type:

```graphql
type Query {
  customers: [Customer!]!
}
```

This defines a `customers` field on the `Query` type. This field returns a list of `Customer` objects.

Here's a mutation type:

```graphql
type Mutation {
  updateCustomerEmail(customerId: ID!, email: String!): Customer!
}
```

This defines a `updateCustomerEmail` field on the `Mutation` type. This field takes two arguments, `customerId` and `email`, and returns a `Customer` object.
It would be used to update the name of the specified customer.

### Input types

Input types are used to pass complex (non-scalar) data to queries or mutations. For example, the `updateCustomerEmail` mutation above could be re-written
to use an input type:

```graphql
type Mutation {
  updateCustomerEmail(input: UpdateCustomerEmailInput!): Customer!
}

input UpdateCustomerEmailInput {
  customerId: ID!
  email: String!
}
```

Input types look just like object types, but with the `input` keyword rather than `type`.

### Schema

The schema is the complete definition of the GraphQL API. It defines the types, fields, queries and mutations which are available.

In a GraphQL API like Vendure, you can only query data according to the fields which are defined in the schema.

Here is a complete, minimal schema:

```graphql
schema {
  query: Query
  mutation: Mutation
}

type Query {
  customers: [Customer!]!
}

type Mutation {
  updateCustomerEmail(input: UpdateCustomerEmailInput!): Customer!
}

input UpdateCustomerEmailInput {
  customerId: ID!
  email: String!
}

type Customer {
  id: ID!
  name: String!
  email: String!
}
```

The schema above tells you _everything_ that you can do with the API. You can fetch a list of customers, and you can update a customer's name.

:::info
The schema is one of the key benefits of GraphQL. It allows advanced tooling to be built around the API, such as autocomplete in IDEs, and
automatic code generation.

It also ensures that only valid queries can be made against the API.
:::

### Operations

An **operation** is the general name for a GraphQL query or mutation. When you are building your client application, you will
be defining operations which you can then send to the server.

Here's an example of a query operation based on the schema above:

<Tabs>
<TabItem value="Query" label="Query" default>

```graphql
query {
  customers {
    id
    name
    email
  }
}
```

</TabItem>
<TabItem value="Response" label="Response" >

```json
{
  "data": {
    "customers": [
        {
            "id": "1",
            "name": "John Smith",
            "email": "j.smith@email.com"
        },
        {
            "id": "2",
            "name": "Jane Doe",
            "email": "j.doe@email.com"
        }
    ]
  }
}
```

</TabItem>
</Tabs>

Here's an example mutation operation to update the first customer's email:

<Tabs>
<TabItem value="Query" label="Query" default>

```graphql
mutation {
  updateCustomerEmail(input: {
    customerId: "1",
    email: "john.smith@email.com"
  }) {
    id
    name
    email
  }
}
```

</TabItem>
<TabItem value="Response" label="Response" >

```json
{
  "data": {
    "updateCustomerEmail": {
      "id": "1",
      "name": "John Smith",
      // highlight-next-line
      "email": "john.smith@email.com"
    }
  }
}
```

</TabItem>
</Tabs>

Operations can also have a **name**, which, while not required, is recommended for real applications as it makes debugging easier
(similar to having named vs anonymous functions in JavaScript), and also allows you to take advantage of code generation tools.

Here's the above query with a name:

```graphql
// highlight-next-line
query GetCustomers {
  customers {
    id
    name
    email
  }
}
```

### Variables

Operations can also have **variables**. Variables are used to pass input values into the operation. In the example `updateCustomerEmail` mutation
operation above, we are passing an input object specifying the `customerId` and `email`. However, in that example they are hard-coded into the
operation. In a real application, you would want to pass those values in dynamically.

Here's how we can re-write the above mutation operation to use variables:

<Tabs>
<TabItem value="Mutation" label="Mutation" default>

```graphql
// highlight-next-line
mutation UpdateCustomerEmail($input: UpdateCustomerEmailInput!) {
  // highlight-next-line
  updateCustomerEmail(input: $input) {
    id
    name
    email
  }
}
```

</TabItem>
<TabItem value="Variables" label="Variables" >

```json
{
  "input": {
    "customerId": "1",
    "email": "john.smith@email.com"
  }
}
```

</TabItem>
<TabItem value="Response" label="Response" >

```json
{
  "data": {
    "updateCustomerEmail": {
      "id": "1",
      "name": "John Smith",
      // highlight-next-line
      "email": "john.smith@email.com"
    }
  }
}
```

</TabItem>
</Tabs>

### Fragments

A **fragment** is a reusable set of fields on an object type. Let's define a fragment for the `Customer` type that
we can re-use in both the query and the mutation:

```graphql
fragment CustomerFields on Customer {
  id
  name
  email
}
```

Now we can re-write the query and mutation operations to use the fragment:

```graphql
query GetCustomers{
  customers {
    ...CustomerFields
  }
}
```

```graphql
mutation UpdateCustomerEmail($input: UpdateCustomerEmailInput!) {
  updateCustomerEmail(input: $input) {
    ...CustomerFields
  }
}
```

You can think of the syntax as similar to the JavaScript object spread operator (`...`).

### Union types

A **union type** is a special type which can be one of a number of other types. Let's say for example that when attempting to update a customer's
email address, we want to return an error type if the email address is already in use. We can update our schema to model this as a union type:

```graphql
type Mutation {
  updateCustomerEmail(input: UpdateCustomerEmailInput!): UpdateCustomerEmailResult!
}

// highlight-next-line
union UpdateCustomerEmailResult = Customer | EmailAddressInUseError

type EmailAddressInUseError {
  errorCode: String!
  message: String!
}
```

:::info
In Vendure, we use this pattern for almost all mutations. You can read more about it in the [Error Handling guide](/guides/developer-guide/error-handling/).
:::

Now, when we perform this mutation, we need alter the way we select the fields in the response, since the response could be one of two types:

<Tabs>
<TabItem value="Mutation" label="Mutation" default>

```graphql
mutation UpdateCustomerEmail($input: UpdateCustomerEmailInput!) {
  updateCustomerEmail(input: $input) {
    __typename
    ... on Customer {
      id
      name
      email
    }
    ... on EmailAddressInUseError {
      errorCode
      message
    }
  }
}
```

</TabItem>
<TabItem value="Success case" label="Success case" >

```json
{
  "data": {
    "updateCustomerEmail": {
      "__typename": "Customer",
      "id": "1",
      "name": "John Smith",
      "email": "john.smith@email.com"
    }
  }
}
```

</TabItem>
<TabItem value="Error case" label="Error case" >

```json
{
  "data": {
    "updateCustomerEmail": {
      "__typename": "EmailAddressInUseError",
      "errorCode": "EMAIL_ADDRESS_IN_USE",
      "message": "The email address is already in use"
    }
  }
}
```

</TabItem>
</Tabs>

The `__typename` field is a special field available on all types which returns the name of the type. This is useful for
determining which type was returned in the response in your client application.

:::tip
The above operation could also be written to use the `CustomerFields` fragment we defined earlier:
```graphql
mutation UpdateCustomerEmail($input: UpdateCustomerEmailInput!) {
  updateCustomerEmail(input: $input) {
    // highlight-next-line
    ...CustomerFields
    ... on EmailAddressInUseError {
      errorCode
      message
    }
  }
}
```
:::

### Resolvers

The schema defines the _shape_ of the data, but it does not define _how_ the data is fetched. This is the job of the resolvers.

A resolver is a function which is responsible for fetching the data for a particular field. For example, the `customers` field on the `Query` type
would be resolved by a function which fetches the list of customers from the database.

To get started with Vendure's APIs, you don't need to know much about resolvers beyond this basic understanding. However,
later on you may want to write your own custom resolvers to extend the API. This is covered in the [Extending the GraphQL API guide](/guides/developer-guide/extend-graphql-api/).

## Querying data

Now that we have a basic understanding of the GraphQL type system, let's look at how we can use it to query data from the Vendure API.

In REST terms, a GraphQL query is equivalent to a GET request. It is used to fetch data from the API. Queries should not change any
data on the server.

This is a GraphQL Playground running on a real Vendure server. You can run the query by clicking the "play" button in the
middle of the two panes.

<Playground api="shop" document={`
query GetProduct {
    product(slug: "football") {
      id
      name
      slug
    }
}
`} />

Let's get familiar with the schema:

1. Hover your mouse over any field to see its type, and in the case of the `product` field itself, you'll see documentation about what it does.
2. Add a new line after `slug` and press `Ctrl / ⌘` + `space` to see the available fields. At the bottom of the field list, you'll see the type of that field.
3. Try adding the `description` field and press play. You should see the product's description in the response.
4. Try adding `variants` to the field list. You'll see a red warning in the left edge, and hovering over `variants` will inform
you that it must have a selection of subfields. This is because the `variants` field refers to an **object type**, so we must select
which fields of that object type we want to fetch. For example:
  ```graphql
  query {
    product(slug: "football") {
      id
      name
      slug
      variants {
        // highlight-start
        # Sub-fields are required for object types
        sku
        priceWithTax
        // highlight-end
      }
    }
  }
  ```

## IDE plugins

Plugins are available for most popular IDEs & editors which provide auto-complete and type-checking for GraphQL operations
as you write them. This is a huge productivity boost, and is **highly recommended**.

- [GraphQL extension for VS Code](https://marketplace.visualstudio.com/items?itemName=GraphQL.vscode-graphql)
- [GraphQL plugin for IntelliJ](https://plugins.jetbrains.com/plugin/8097-graphql) (including WebStorm)

## Code generation

Code generation means the automatic generation of TypeScript types based on your GraphQL schema and your GraphQL operations. This is a very powerful feature that allows you to write your code in a type-safe manner, without you needing to manually write any types for your API calls.

For more information see the [GraphQL Code Generation guide](/guides/storefront/codegen).

## Further reading

This is just a very brief overview, intended to introduce you to the main concepts you'll need to build with Vendure.
There are many more language features and best practices to learn about which we did not cover here.

Here are some resources you can use to gain a deeper understanding of GraphQL:

- The official [Introduction to GraphQL on graphql.org](https://graphql.org/learn/) is comprehensive and easy to follow.
- For a really fundamental understanding, see the [GraphQL language spec](https://spec.graphql.org/).
- If you like to learn from videos, the [graphql.wtf](https://graphql.wtf/) series is a great resource.


---

---
title: 'Installation'
sidebar_position: 1
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

## Requirements

- [Node.js](https://nodejs.org/en/) **v20**, **v22** and **v24** - these versions are tested and supported. (Odd-numbered versions above v20 should still work but are not officially supported.)

### Optional

- [Docker Desktop](https://www.docker.com/products/docker-desktop/): If you want to use the quick start with Postgres, you must have Docker Desktop installed. If you do not have Docker Desktop installed, then SQLite will be used for your database.
- If you want to use an existing MySQL, MariaDB, or Postgres server as your data store, then you'll need an instance available locally. However, **if you are just testing out Vendure, we recommend the quick start option, which handles the database for you**.

## @vendure/create

The recommended way to get started with Vendure is by using the [@vendure/create](https://github.com/vendure-ecommerce/vendure/tree/master/packages/create) tool. This is a command-line tool which will scaffold and configure your new Vendure project and install all dependencies.

### Quick Start

First, run the following command in your terminal, replacing `my-shop` with the name of your project:

```bash
npx @vendure/create my-shop
```

Next, choose the "Quick Start" option. This is the fastest way to get a Vendure server up and running and will handle all the configuration for you. If you have Docker Desktop installed, it will create and configure a Postgres database for you. If not, it will use SQLite.

```text
┌  Let's create a Vendure App ✨
│
◆  How should we proceed?
// highlight-next-line
│  ● Quick Start (Get up and running in a single step)
│  ○ Manual Configuration
└
```

And that's it! After a minute or two, you'll have a **fully-functional Vendure server** installed locally.

Once the installation is done, your terminal will output a message indicating a successful installation with:

- The URL to access the **Admin UI**
- Your admin log-in credentials
- The project file path

Proceed to the [Start the server](#start-the-server) section below to run your Vendure server.

### Manual Configuration

If you'd rather have more control over the configuration, you can choose the "Manual Configuration" option. This will prompt you to select a database and whether to populate the database with sample data.

#### 1. Select a database

Vendure supports a number of different databases. The `@vendure/create` tool will prompt you to select one.

**To quickly test out Vendure, we recommend using SQLite**, which requires no external dependencies. You can always switch to a different database later [by changing your configuration file](/guides/developer-guide/configuration/#connecting-to-the-database).

![Vendure Create step 1](./create-1.webp)

:::tip
If you select MySQL, MariaDB, or Postgres, you need to make sure you:

1. **Have the database server running**: You can either install the database locally on your machine, use a cloud provider, or run it via Docker. For local development with Docker, you can use the provided `docker-compose.yml` file in your project.

2. **Have created a database**: Use your database client to create an empty database (e.g., `CREATE DATABASE vendure;` in most SQL databases).

3. **Have database credentials**: You need the username and password for a database user that has full permissions (CREATE, ALTER, DROP, INSERT, UPDATE, DELETE, SELECT) on the database you created.

For detailed database configuration examples, see the [Configuration guide](/guides/developer-guide/configuration/#connecting-to-the-database).

:::

#### 2. Populate with data

The final prompt will ask whether to populate your new Vendure server with some sample product data.

**We recommend you do so**, as it will give you a good starting point for exploring the APIs, which we will cover in the [Try the API section](/guides/getting-started/try-the-api/), as well as providing some data to use when building your own storefront.

![Vendure Create step 2](./create-2.webp)

#### 3. Complete setup

Next, a project scaffold will be created and dependencies installed. This may take a few minutes.

Once complete, you'll see a message like this:

![Vendure Create step 3](./create-3.webp)

### Start the server

Follow the instructions to move into the new directory created for your project, and start the server:

```bash
cd my-shop

npm run dev
```

You should now be able to access:

- The Vendure Admin GraphQL API: [http://localhost:3000/admin-api](http://localhost:3000/admin-api)
- The Vendure Shop GraphQL API: [http://localhost:3000/shop-api](http://localhost:3000/shop-api)
- The Vendure Admin UI: [http://localhost:3000/admin](http://localhost:3000/admin)

Congratulations! 🥳 You now have a fully-functional Vendure server running locally.

Now you can explore Vendure by following our [Try the API guide](/guides/getting-started/try-the-api/) to learn how to interact with the server.

If you are new to GraphQL, you should also check out our [Introducing GraphQL guide](/guides/getting-started/graphql-intro/).

:::tip
Open the Admin UI at [http://localhost:3000/admin](http://localhost:3000/admin) in your browser and log in with the superadmin credentials you specified, which default to:

- **username**: superadmin
- **password**: superadmin

:::

:::cli
Use `npx vendure add` to start adding plugins & custom functionality to your Vendure server.
:::

### Troubleshooting

- If you encounter any issues during installation, you can get a more detailed output by setting the log level to `verbose`:

    ```sh
    npx @vendure/create my-shop --log-level verbose
    ```

- The [supported TypeScript version](https://github.com/vendure-ecommerce/vendure/blob/master/packages/create/src/constants.ts#L7) is set upon installation. Upgrading to a newer version of TypeScript might result in compilation errors because TypeScript sometimes introduces stricter checks in newer versions.
- If you want to use **Yarn**, from Vendure v2.2.0+, you'll need to use **Yarn 2** (Berry) or above.

## Set up a storefront

Once you have a Vendure server running, you can set up a storefront to interact with it!

We have a number of storefront starter kits available for you to use—head over to the [Storefront Starters](/guides/storefront/storefront-starters/) page to learn more.

![Remix storefront](../../storefront/storefront-starters/remix-storefront.webp)


---

---
title: 'Try the API'
---

import Playground from '@site/src/components/Playground';

Once you have successfully installed Vendure locally following the [installation guide](/guides/getting-started/installation),
it's time to try out the API!

:::note
This guide assumes you chose to populate sample data when installing Vendure.

You can also follow along with these example using the public demo playground at [demo.vendure.io/graphiql/shop](https://demo.vendure.io/graphiql/shop)
:::

## GraphiQL Interface

Vendure comes with GraphiQL - a powerful UI for exploring and testing GraphQL APIs. It allows you to run queries and mutations
against both the Shop and Admin APIs, making it easy to explore the API and understand how it works.

In this guide, we'll be using GraphiQL to run queries and mutations. At each step, you paste the query or mutation into the
editor pane, and then click the "Play" button to run it. You'll then see the response in the right-hand pane.

![GraphiQL interface](./graphiql.jpeg)

## Shop API

The Shop API is the public-facing API which is used by the storefront application.

Open the GraphiQL Shop API interface at [http://localhost:3000/graphiql/shop](http://localhost:3000/graphiql/shop).

### Fetch a list of products

Let's start with a **query**. Queries are used to fetch data. We will make a query to get a list of products.

<Playground
    api="shop"
    document={`
query GetProducts {
    products {
      totalItems
      items {
        id
        name
      }
    }
}
`}
/>

Note that the response only includes the properties we asked for in our query (id and name). This is one of the key benefits
of GraphQL - the client can specify exactly which data it needs, and the server will only return that data!

Let's add a few more properties to the query:

<Playground
    api="shop"
    document={`
query GetProducts {
    products {
      totalItems
      items {
        id
        name
        slug
        description
        featuredAsset {
          id
          preview
        }
      }
    }
}
`}
/>

You should see that the response now includes the `slug`, `description` and `featuredAsset` properties. Note that the
`featuredAsset` property is itself an object, and we can specify which properties of that object we want to include in the
response. This is another benefit of GraphQL - you can "drill down" into the data and specify exactly which properties you
want to include.

Now let's add some arguments to the query. Some queries (and most mutations) can accept argument, which you put in parentheses
after the query name. For example, let's fetch the first 5 products:

<Playground
    api="shop"
    document={`
query GetProducts {
    products(options: { take: 5 }) {
      totalItems
      items {
        id
        name
      }
    }
}
`}
/>

On running this query, you should see just the first 5 results being returned.

Let's add a more complex argument: this time we'll filter for only those products which contain the string "shoe" in the
name:

<Playground
    api="shop"
    document={`
query GetProducts {
    products(options: {
      filter: {
        name: {
          contains: "shoe"
        }
      }
    }) {
      totalItems
      items {
        id
        name
      }
    }
}
`}
/>

### Add a product to an order

Next, let's look at a **mutation**. Mutations are used to modify data on the server.

Here's a mutation which adds a product to an order:

<Playground
    api="shop"
    document={`
mutation AddItemToOrder {
    addItemToOrder(productVariantId: 42, quantity: 1) {
      ...on Order {
        id
        code
        totalQuantity
        totalWithTax
        lines {
          productVariant {
            name
          }
          quantity
          linePriceWithTax
        }
      }
      ...on ErrorResult {
        errorCode
        message
      }
    }
}
`}
/>

This mutation adds a product variant with ID `42` to the order. The response will either be an `Order` object, or an `ErrorResult`.
We use a special syntax called a **fragment** to specify which properties we want to include in the response. In this case,
we are saying that if the response is an `Order`, we want to include the `id`, `code`, `totalQuantity`, `totalWithTax` etc., and
if the response is an `ErrorResult`, we want to include the `errorCode` and `message`.

Running this mutation a second time should show that the quantity of the product in the order has increased by 1.

:::info
For more information about `ErrorResult` and the handling of errors in Vendure, see the [Error Handling guide](/guides/developer-guide/error-handling).
:::

## Admin API

The Admin API exposes all the functionality required to manage the store. It is used by the Admin UI, but can also be used
by integrations and custom scripts.

:::note
The examples in this section are not interactive, due to security settings on our demo server,
but you can paste them into your local GraphiQL interface.
:::

Open the GraphiQL Admin API interface at [http://localhost:3000/graphiql/admin](http://localhost:3000/graphiql/admin).

### Logging in

Most Admin API operations are restricted to authenticated users. So first of all we'll need to log in.

```graphql title="Admin API"
mutation Login {
    login(username: "superadmin", password: "superadmin") {
        ... on CurrentUser {
            id
            identifier
        }
        ... on ErrorResult {
            errorCode
            message
        }
    }
}
```

### Fetch a product

The Admin API exposes a lot more information about products than you can get from the Shop API:

```graphql title="Admin API"
query GetProduct {
  product(id: 42) {
    // highlight-next-line
    enabled
    name
    variants {
      id
      name
      // highlight-next-line
      enabled
      prices {
        currencyCode
        price
      }
      // highlight-start
      stockLevels {
        stockLocationId
        stockOnHand
        stockAllocated
      }
      // highlight-end
    }
  }
}
```

:::info
GraphQL is statically typed and uses a **schema** containing information about all the available queries, mutations and types. In GraphiQL,
you can explore the schema by clicking the Docs icon (first icon from the top) on the right side of the interface.

![GraphiQL docs explorer](./graphiql-docs.jpeg)
:::


---

---
title: "GraphQL Code Generation"
---

Code generation means the automatic generation of TypeScript types based on your GraphQL schema and your GraphQL operations.
This is a very powerful feature that allows you to write your code in a type-safe manner, without you needing to manually
write any types for your API calls.

To do this, we will use [Graphql Code Generator](https://the-guild.dev/graphql/codegen).

:::cli
Use `npx vendure add` and select "Set up GraphQL code generation" to quickly set up code generation.
:::

:::note
This guide is for adding codegen to your Vendure plugins & Admin UI extensions. For a guide on adding codegen to your storefront, see the [Storefront Codegen](/guides/storefront/codegen/) guide.
:::

## Installation

It is recommended to use the `vendure add` CLI command as detailed above to set up codegen. 
If you prefer to set it up manually, follow the steps below.

First, install the required dependencies:

```bash
npm install -D @graphql-codegen/cli @graphql-codegen/typescript
```

## Configuration

Add a `codegen.ts` file to your project root with the following contents:

```ts title="codegen.ts"
import type {CodegenConfig} from '@graphql-codegen/cli';

const config: CodegenConfig = {
    overwrite: true,
    // This assumes your server is running on the standard port
    // and with the default admin API path. Adjust accordingly.
    schema: 'http://localhost:3000/admin-api',
    config: {
        // This tells codegen that the `Money` scalar is a number
        scalars: { Money: 'number' },
        // This ensures generated enums do not conflict with the built-in types.
        namingConvention: { enumValues: 'keep' },
    },
    generates: {
        // The path to the generated type file in your
        // plugin directory. Adjust accordingly.
        'src/plugins/organization/gql/generated.ts': {
            plugins: ['typescript'],
        },
    },
};

export default config;
```

This assumes that we have an "organization" plugin which adds support for grouping customers into organizations, e.g. for B2B use-cases.

## Running codegen

You can now add a script to your package.json to run codegen:

```json title="package.json"
{
  "scripts": {
    "codegen": "graphql-codegen --config codegen.ts"
  }
}
```

**Ensure your server is running**, then run the codegen script:

```bash
npm run codegen
```

This will generate a file at `src/plugins/organization/gql/generated.ts` which contains all the GraphQL types corresponding to your schema.

## Using generated types in resolvers & services

You would then use these types in your resolvers and service methods, for example:

```ts title="src/plugins/organization/services/organization.service.ts"
import { Args, Mutation, Query, Resolver } from '@nestjs/graphql';
import { Allow, Ctx, PaginatedList, RequestContext, Transaction } from '@vendure/core';

import { organizationPermission } from '../constants';
import { Organization } from '../entities/organization.entity';
import { OrganizationService } from '../services/organization.service';
// highlight-next-line
import { QueryOrganizationArgs, MutationCreateOrganizationArgs } from '../gql/generated';

@Resolver()
export class AdminResolver {
    constructor(private organizationService: OrganizationService) {}

    @Query()
    @Allow(organizationPermission.Read)
    // highlight-next-line
    organization(@Ctx() ctx: RequestContext, @Args() args: QueryOrganizationArgs): Promise<Organization> {
        return this.organizationService.findOne(ctx, args.id);
    }
    
    @Transaction()
    @Mutation()
    @Allow(organizationPermission.Create)
    createOrganization(
        @Ctx() ctx: RequestContext,
        // highlight-next-line
        @Args() args: MutationCreateOrganizationArgs,
    ): Promise<Organization> {
        return this.organizationService.create(ctx, args.input);
    }

    // ... etc
}
```

In your service methods you can directly use any input types defined in your schema:

```ts title="src/plugins/organization/services/organization.service.ts"
import { Injectable } from '@nestjs/common';
import { RequestContext, TransactionalConnection } from '@vendure/core';

import { Organization } from '../entities/organization.entity';
// highlight-next-line
import { CreateOrganizationInput, UpdateOrganizationInput } from "../gql/generated";

@Injectable()
export class OrganizationService {
    constructor(private connection: TransactionalConnection) {}

    // highlight-next-line
    async create(ctx: RequestContext, input: CreateOrganizationInput): Promise<Organization> {
        return this.connection.getRepository(ctx, Organization).save(new Organization(input));
    }

    // highlight-next-line
    async update(ctx: RequestContext, input: UpdateOrganizationInput): Promise<Organization> {
        const example = await this.connection.getEntityOrThrow(ctx, Organization, input.id);
        const updated = {...example, ...input};
        return this.connection.getRepository(ctx, Organization).save(updated);
    }
}
```

## Codegen for Admin UI extensions

When you create Admin UI extensions, very often those UI components will be making API calls to the Admin API. In this case, you can use codegen to generate the types for those API calls.

To do this, we will use the ["client preset" plugin](https://the-guild.dev/graphql/codegen/plugins/presets/preset-client). Assuming you have already completed the setup above, you'll need to install the following additional dependency:

```bash
npm install -D @graphql-codegen/client-preset
```

Then add the following to your `codegen.ts` file:

```ts title="codegen.ts"
import type { CodegenConfig } from '@graphql-codegen/cli';

const config: CodegenConfig = {
    overwrite: true,
    schema: 'http://localhost:3000/admin-api',
    config: {
        scalars: { Money: 'number' },
        namingConvention: { enumValues: 'keep' },
    },
    generates: {
        // highlight-start
        'apps/marketplace/src/plugins/marketplace/ui/gql/': {
            preset: 'client',
            documents: 'apps/marketplace/src/plugins/marketplace/ui/**/*.ts',
            // This disables the "fragment masking" feature. Fragment masking
            // can improve component isolation but introduces some additional
            // complexity that we will avoid for now.
            presetConfig: {
                fragmentMasking: false,
            },
        },
        // highlight-end
        'apps/marketplace/src/plugins/marketplace/gql/generated.ts': {
            plugins: ['typescript'],
        },
    },
};

export default config;
```

For the client preset plugin, we need to specify a _directory_ (`.../ui/gql/`) because a number of files will get generated.

### Use the `graphql()` function

In your Admin UI components, you can now use the `graphql()` function exported from the generated file to define your
GraphQL operations. For example:

```ts title="apps/marketplace/src/plugins/marketplace/ui/components/organization-list/organization-list.component.ts"
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { SharedModule, TypedBaseListComponent } from '@vendure/admin-ui/core';
import { graphql } from '../../gql';

// highlight-start
const getOrganizationListDocument = graphql(`
    query GetOrganizationList($options: OrganizationListOptions) {
        organizations(options: $options) {
            items {
                id
                createdAt
                updatedAt
                name
                invoiceEmailAddresses
            }
            totalItems
        }
    }
`);
// highlight-end

@Component({
    selector: 'organization-list',
    templateUrl: './organization-list.component.html',
    styleUrls: ['./organization-list.component.scss'],
    changeDetection: ChangeDetectionStrategy.OnPush,
    standalone: true,
    imports: [SharedModule],
})
export class OrganizationListComponent extends TypedBaseListComponent<
    // highlight-start
    typeof getOrganizationListDocument,
    'organizations'
    // highlight-end
> {
    
    // Sort & filter definitions omitted for brevity.
    // For a complete ListComponent example, see the 
    // "Creating List Views" guide.

    constructor() {
        super();
        super.configure({
            // highlight-next-line
            document: getOrganizationListDocument,
            getItems: (data) => data.organizations,
            setVariables: (skip, take) => ({
                options: {
                    skip,
                    take,
                    filter: {
                        name: {
                            contains: this.searchTermControl.value,
                        },
                        ...this.filters.createFilterInput(),
                    },
                    sort: this.sorts.createSortInput(),
                },
            }),
            refreshListOnChanges: [this.filters.valueChanges, this.sorts.valueChanges],
        });
    }
}
```

Whenever you write a new GraphQL operation, or change an existing one, you will need to re-run the codegen script to generate the types for that operation.

## Codegen watch mode

You can also set up file watching as described in the [Graphql Code Generator watch mode docs](https://the-guild.dev/graphql/codegen/docs/getting-started/development-workflow#watch-mode).


---

---
title: "Configurable Products"
---

A "configurable product" is one where aspects can be configured by the customer, and are unrelated to the product's variants. Examples include:

- Engraving text on an item
- A gift message inserted with the packaging
- An uploaded image to be printed on a t-shirt

In Vendure this is done by defining one or more [custom fields](/guides/developer-guide/custom-fields/) on the [OrderLine](/reference/typescript-api/entities/order-line/) entity.

## Defining custom fields

Let's take the example of an engraving service. Some products can be engraved, others cannot. We will record this information in a custom field on the [ProductVariant](/reference/typescript-api/entities/product-variant/) entity:

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';

export const config: VendureConfig = {
    // ...
    customFields: {
        ProductVariant: [
            {
                name: 'engravable',
                type: 'boolean',
                defaultValue: false,
                label: [
                    { languageCode: LanguageCode.en, value: 'Engravable' },
                ],
            },
        ],
    },
};
```

For those variants that _are_ engravable, we need to be able to record the text to be engraved. This is done by defining a custom field on the [OrderLine](/reference/typescript-api/entities/order-line/) entity:

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';

export const config: VendureConfig = {
    // ...
    customFields: {
        OrderLine: [
            {
                name: 'engravingText',
                type: 'string',
                validate: value => {
                    if (value.length > 100) {
                        return 'Engraving text must be less than 100 characters';
                    }
                },
                label: [
                    { languageCode: LanguageCode.en, value: 'Engraving text' },
                ],
            },
        ]
    },
};
```

## Setting the custom field value

Once the custom fields are defined, the [addItemToOrder mutation](/reference/graphql-api/shop/mutations/#additemtoorder) will have a third argument available, which accepts values for the custom field defined above:

```graphql
mutation {
    addItemToOrder(
        productVariantId: "42"
        quantity: 1
        // highlight-start
        customFields: {
            engravingText: "Thanks for all the fish!"
        }
        // highlight-end
    ) {
        ...on Order {
            id
            lines {
                id
                quantity
                customFields {
                    engravingText
                }
            }
        }
    }
}
```

Your storefront application will need to provide a `<textarea>` for the customer to enter the engraving text, which would be displayed conditionally depending on the value of the `engravable` custom field on the `ProductVariant`. 

## Modifying the price

The values of these OrderLine custom fields can even be used to modify the price. This is done by defining a custom [OrderItemPriceCalculationStrategy](/reference/typescript-api/orders/order-item-price-calculation-strategy/). 

Let's say that our engraving service costs and extra $10 on top of the regular price of the product variant. Here's a strategy to implement this:

```ts title="src/engraving-price-calculation-strategy.ts"
import {
    RequestContext, PriceCalculationResult,
    ProductVariant, OrderItemPriceCalculationStrategy
} from '@vendure/core';

export class EngravingPriceStrategy implements OrderItemPriceCalculationStrategy {

    calculateUnitPrice(
        ctx: RequestContext,
        productVariant: ProductVariant,
        customFields: { engravingText?: string },
    ) {
        let price = productVariant.listPrice;
        if (customFields.engravingText) {
            // Add $10 for engraving
            price += 1000;
        }
        return {
            price,
            priceIncludesTax: productVariant.listPriceIncludesTax,
        };
    }
}
```

This is then added to the config:

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';
import { EngravingPriceStrategy } from './engraving-price-calculation-strategy';

export const config: VendureConfig = {
    // ...
    orderOptions: {
        orderItemPriceCalculationStrategy: new EngravingPriceStrategy(),
    },
};
```


---

---
title: "Digital Products"
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Digital products include things like ebooks, online courses, and software. They are products that are delivered to the customer electronically, and do not require
physical shipping.

This guide will show you how you can add support for digital products to Vendure.

## Creating the plugin

:::info
The complete source of the following example plugin can be found here: [example-plugins/digital-products](https://github.com/vendure-ecommerce/vendure/tree/master/packages/dev-server/example-plugins/digital-products)
:::

### Define custom fields

If some products are digital and some are physical, we can distinguish between them by adding a customField to the ProductVariant entity.

```ts title="src/plugins/digital-products/digital-products.plugin.ts"
import { LanguageCode, PluginCommonModule, VendurePlugin } from '@vendure/core';

@VendurePlugin({
    imports: [PluginCommonModule],
    configuration: config => {
        // highlight-start
        config.customFields.ProductVariant.push({
            type: 'boolean',
            name: 'isDigital',
            defaultValue: false,
            label: [{ languageCode: LanguageCode.en, value: 'This product is digital' }],
            public: true,
        });
        // highlight-end
        return config;
    },
})
export class DigitalProductsPlugin {}
```

:::note
You will need to **create a migration** after adding this custom field.
See the [Migrations](/guides/developer-guide/migrations/) guide for more information.
:::

We will also define a custom field on the `ShippingMethod` entity to indicate that this shipping method is only available for digital products:

```ts title="src/plugins/digital-products/digital-products.plugin.ts"
import { LanguageCode, PluginCommonModule, VendurePlugin } from '@vendure/core';

@VendurePlugin({
    imports: [PluginCommonModule],
    configuration: config => {
        // config.customFields.ProductVariant.push({ ... omitted
        // highlight-start
        config.customFields.ShippingMethod.push({
            type: 'boolean',
            name: 'digitalFulfilmentOnly',
            defaultValue: false,
            label: [{ languageCode: LanguageCode.en, value: 'Digital fulfilment only' }],
            public: true,
        });
        // highlight-end
        return config;
    },
})
```

Lastly we will define a custom field on the `Fulfillment` entity where we can store download links for the digital products. If your own implementation you may
wish to handle this part differently, e.g. storing download links on the `Order` entity or in a custom entity.

```ts title="src/plugins/digital-products/digital-products.plugin.ts"
import { LanguageCode, PluginCommonModule, VendurePlugin } from '@vendure/core';

@VendurePlugin({
    imports: [PluginCommonModule],
    configuration: config => {
        // config.customFields.ProductVariant.push({ ... omitted
        // config.customFields.ShippingMethod.push({ ... omitted
        // highlight-start
        config.customFields.Fulfillment.push({
            type: 'string',
            name: 'downloadUrls',
            nullable: true,
            list: true,
            label: [{ languageCode: LanguageCode.en, value: 'Urls of any digital purchases' }],
            public: true,
        });
        // highlight-end
        return config;
    },
})
```

### Create a custom FulfillmentHandler

The `FulfillmentHandler` is responsible for creating the `Fulfillment` entities when an Order is fulfilled. We will create a custom handler which
is responsible for performing the logic related to generating the digital download links.

In your own implementation, this may look significantly different depending on your requirements.

```ts title="src/plugins/digital-products/config/digital-fulfillment-handler.ts"
import { FulfillmentHandler, LanguageCode, OrderLine, TransactionalConnection } from '@vendure/core';
import { In } from 'typeorm';

let connection: TransactionalConnection;

/**
 * @description
 * This is a fulfillment handler for digital products which generates a download url
 * for each digital product in the order.
 */
export const digitalFulfillmentHandler = new FulfillmentHandler({
    code: 'digital-fulfillment',
    description: [
        {
            languageCode: LanguageCode.en,
            value: 'Generates product keys for the digital download',
        },
    ],
    args: {},
    init: injector => {
        connection = injector.get(TransactionalConnection);
    },
    createFulfillment: async (ctx, orders, lines) => {
        const digitalDownloadUrls: string[] = [];

        const orderLines = await connection.getRepository(ctx, OrderLine).find({
            where: {
                id: In(lines.map(l => l.orderLineId)),
            },
            relations: {
                productVariant: true,
            },
        });
        for (const orderLine of orderLines) {
            if (orderLine.productVariant.customFields.isDigital) {
                // This is a digital product, so generate a download url
                const downloadUrl = await generateDownloadUrl(orderLine);
                digitalDownloadUrls.push(downloadUrl);
            }
        }
        return {
            method: 'Digital Fulfillment',
            trackingCode: 'DIGITAL',
            customFields: {
                downloadUrls: digitalDownloadUrls,
            },
        };
    },
});

function generateDownloadUrl(orderLine: OrderLine) {
    // This is a dummy function that would generate a download url for the given OrderLine
    // by interfacing with some external system that manages access to the digital product.
    // In this example, we just generate a random string.
    const downloadUrl = `https://example.com/download?key=${Math.random().toString(36).substring(7)}`;
    return Promise.resolve(downloadUrl);
}
```

This fulfillment handler should then be added to the `fulfillmentHandlers` array the config ShippingOptions:

```ts title="src/plugins/digital-products/digital-products.plugin.ts"

import { LanguageCode, PluginCommonModule, VendurePlugin } from '@vendure/core';
import { digitalFulfillmentHandler } from './config/digital-fulfillment-handler';

@VendurePlugin({
    imports: [PluginCommonModule],
    configuration: config => {
        // config.customFields.ProductVariant.push({ ... omitted
        // config.customFields.ShippingMethod.push({ ... omitted
        // config.customFields.Fulfillment.push({ ... omitted
        // highlight-start
        config.shippingOptions.fulfillmentHandlers.push(digitalFulfillmentHandler);
        // highlight-end
        return config;
    },
})
export class DigitalProductsPlugin {}
```

### Create a custom ShippingEligibilityChecker

We want to ensure that the digital shipping method is only applicable to orders containing at least one digital product.
We do this with a custom ShippingEligibilityChecker:

```ts title="src/plugins/digital-products/config/digital-shipping-eligibility-checker.ts"
import { LanguageCode, ShippingEligibilityChecker } from '@vendure/core';

export const digitalShippingEligibilityChecker = new ShippingEligibilityChecker({
    code: 'digital-shipping-eligibility-checker',
    description: [
        {
            languageCode: LanguageCode.en,
            value: 'Allows only orders that contain at least 1 digital product',
        },
    ],
    args: {},
    check: (ctx, order, args) => {
        const digitalOrderLines = order.lines.filter(l => l.productVariant.customFields.isDigital);
        return digitalOrderLines.length > 0;
    },
});
```

### Create a custom ShippingLineAssignmentStrategy

When adding shipping methods to the order, we want to ensure that digital products are correctly assigned to the digital shipping
method, and physical products are not.

```ts title="src/plugins/digital-products/config/digital-shipping-line-assignment-strategy.ts"
import {
    Order,
    OrderLine,
    RequestContext,
    ShippingLine,
    ShippingLineAssignmentStrategy,
} from '@vendure/core';

/**
 * @description
 * This ShippingLineAssignmentStrategy ensures that digital products are assigned to a
 * ShippingLine which has the `isDigital` flag set to true.
 */
export class DigitalShippingLineAssignmentStrategy implements ShippingLineAssignmentStrategy {
    assignShippingLineToOrderLines(
        ctx: RequestContext,
        shippingLine: ShippingLine,
        order: Order,
    ): OrderLine[] | Promise<OrderLine[]> {
        if (shippingLine.shippingMethod.customFields.isDigital) {
            return order.lines.filter(l => l.productVariant.customFields.isDigital);
        } else {
            return order.lines.filter(l => !l.productVariant.customFields.isDigital);
        }
    }
}
```

### Define a custom OrderProcess

In order to automatically fulfill any digital products as soon as the order completes, we can define a custom OrderProcess:

```ts title="src/plugins/digital-products/config/digital-order-process.ts"
import { OrderProcess, OrderService } from '@vendure/core';

import { digitalFulfillmentHandler } from './digital-fulfillment-handler';

let orderService: OrderService;

/**
 * @description
 * This OrderProcess ensures that when an Order transitions from ArrangingPayment to
 * PaymentAuthorized or PaymentSettled, then any digital products are automatically
 * fulfilled.
 */
export const digitalOrderProcess: OrderProcess<string> = {
    init(injector) {
        orderService = injector.get(OrderService);
    },
    async onTransitionEnd(fromState, toState, data) {
        if (
            fromState === 'ArrangingPayment' &&
            (toState === 'PaymentAuthorized' || toState === 'PaymentSettled')
        ) {
            const digitalOrderLines = data.order.lines.filter(l => l.productVariant.customFields.isDigital);
            if (digitalOrderLines.length) {
                await orderService.createFulfillment(data.ctx, {
                    lines: digitalOrderLines.map(l => ({ orderLineId: l.id, quantity: l.quantity })),
                    handler: { code: digitalFulfillmentHandler.code, arguments: [] },
                });
            }
        }
    },
};
```

### Complete plugin & add to config

The complete plugin can be found here: [example-plugins/digital-products](https://github.com/vendure-ecommerce/vendure/tree/master/packages/dev-server/example-plugins/digital-products)

We can now add the plugin to the VendureConfig:

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';
import { DigitalProductsPlugin } from './plugins/digital-products/digital-products.plugin';

const config: VendureConfig = {
    // ... other config omitted
    plugins: [
        // ... other plugins omitted
        // highlight-next-line
        DigitalProductsPlugin,
    ],
};
```

## Create the ShippingMethod

Once these parts have been defined and bundled up in a Vendure plugin, we can create a new ShippingMethod via the Admin UI, and
make sure to check the "isDigital" custom field, and select the custom fulfillment handler and eligibility checker:

![Create ShippingMethod](./shipping-method.webp)

## Mark digital products

We can now also set any digital product variants by checking the custom field:

![Digital product variant](./product-variant.webp)

## Storefront integration

In the storefront, when the customer is checking out, we can use the `eligibleShippingMethods` query to determine which shipping methods
are available to the customer. If the customer has any digital products in the order, the "digital-download" shipping method will be available:


<Tabs>
<TabItem value="Query" label="Query" default>

```graphql
query {
  eligibleShippingMethods {
    id
    name
    price
    priceWithTax
    customFields {
      isDigital
    }
  }
}
```

</TabItem>
<TabItem value="Response" label="Response" >

```json
{
  "data": {
    "eligibleShippingMethods": [
      // highlight-start
      {
        "id": "3",
        "name": "Digital Download",
        "price": 0,
        "priceWithTax": 0,
        "customFields": {
          "isDigital": true
        }
      },
      // highlight-end
      {
        "id": "1",
        "name": "Standard Shipping",
        "price": 500,
        "priceWithTax": 500,
        "customFields": {
          "isDigital": false
        }
      },
      {
        "id": "2",
        "name": "Express Shipping",
        "price": 1000,
        "priceWithTax": 1000,
        "customFields": {
          "isDigital": false
        }
      }
    ]
  }
}
```

</TabItem>
</Tabs>

If the "digital download" shipping method is eligible, it should be set as a shipping method along with any other method
required by any physical products in the order.

<Tabs>
<TabItem value="Query" label="Query" default>

```graphql
mutation SetShippingMethod {
  setOrderShippingMethod(
      // highlight-next-line
      shippingMethodId: ["3", "1"]
    ) {
    ... on Order {
      id
      code
      total
      lines {
        id
        quantity
        linePriceWithTax
        productVariant {
          name
          sku
          customFields {
            isDigital
          }
        }
      }
      shippingLines {
        id
        shippingMethod {
          name
        }
        priceWithTax
      }
    }
  }
}
```

</TabItem>
<TabItem value="Response" label="Response" >

```json
{
  "data": {
    "setOrderShippingMethod": {
      "id": "11",
      "code": "C6H3UZ6WQ62LAPS8",
      "total": 5262,
      "lines": [
        {
          "id": "16",
          "quantity": 1,
          "linePriceWithTax": 1458,
          "productVariant": {
            "name": "Jeff Buckley Grace mp3 download",
            "sku": "1231241241231",
            "customFields": {
              // highlight-next-line
              "isDigital": true
            }
          }
        },
        {
          "id": "17",
          "quantity": 1,
          "linePriceWithTax": 4328,
          "productVariant": {
            "name": "Basketball",
            "sku": "WTB1418XB06",
            "customFields": {
              "isDigital": false
            }
          }
        }
      ],
      "shippingLines": [
        // highlight-start
        {
          "id": "13",
          "shippingMethod": {
            "name": "Digital Download"
          },
          "priceWithTax": 0
        },
        // highlight-end
        {
          "id": "14",
          "shippingMethod": {
            "name": "Standard Shipping"
          },
          "priceWithTax": 500
        }
      ]
    }
  }
}
```

</TabItem>
</Tabs>


---

---
title: "GitHub OAuth Authentication"
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

:::info
The complete source of the following example plugin can be found here: [example-plugins/github-auth-plugin](https://github.com/vendure-ecommerce/examples/tree/master/examples/shop-github-auth)
:::

GitHub OAuth authentication allows customers to sign in using their GitHub accounts, eliminating the need for password-based registration.

This is particularly valuable for developer-focused stores or B2B marketplaces.

This guide shows you how to add GitHub OAuth support to your Vendure store using a custom [AuthenticationStrategy](/reference/typescript-api/auth/authentication-strategy/).

## Creating the Plugin

First, use the Vendure CLI to create a new plugin for GitHub authentication:

```bash
npx vendure add -p GitHubAuthPlugin
```

This creates a basic plugin structure with the necessary files.

## Creating the Authentication Strategy

Now create the GitHub authentication strategy. This handles the OAuth flow and creates customer accounts using GitHub profile data:

```ts title="src/plugins/github-auth-plugin/github-auth-strategy.ts"
import { AuthenticationStrategy, ExternalAuthenticationService, Injector, RequestContext, User } from '@vendure/core';
import { DocumentNode } from 'graphql';
import gql from 'graphql-tag';

export interface GitHubAuthData {
  code: string;
  state: string;
}

export interface GitHubAuthOptions {
  clientId: string;
  clientSecret: string;
}

export class GitHubAuthenticationStrategy implements AuthenticationStrategy<GitHubAuthData> {
  readonly name = 'github';
  private externalAuthenticationService: ExternalAuthenticationService;

  constructor(private options: GitHubAuthOptions) {}

  init(injector: Injector) {
    // Get the service we'll use to create/find customer accounts
    this.externalAuthenticationService = injector.get(ExternalAuthenticationService);
  }

  defineInputType(): DocumentNode {
    // Define the GraphQL input type for the authenticate mutation
    return gql`
      input GitHubAuthInput {
        code: String!
        state: String!
      }
    `;
  }

  async authenticate(ctx: RequestContext, data: GitHubAuthData): Promise<User | false> {
    const { code, state } = data;

    // Step 1: Exchange the authorization code for an access token
    const tokenResponse = await fetch('https://github.com/login/oauth/access_token', {
      method: 'POST',
      headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        client_id: this.options.clientId,
        client_secret: this.options.clientSecret,
        code,
        state,
      }),
    });

    const tokenData = await tokenResponse.json();
    if (tokenData.error) {
      throw new Error(`GitHub OAuth error: ${tokenData.error_description}`);
    }

    // Step 2: Use the access token to get user info from GitHub
    const userResponse = await fetch('https://api.github.com/user', {
      headers: {
        'Authorization': `Bearer ${tokenData.access_token}`,
        'Accept': 'application/vnd.github.v3+json',
      },
    });

    const user = await userResponse.json();
    if (!user.login) {
      throw new Error('Unable to retrieve user information from GitHub');
    }

    // Step 3: Check if this GitHub user already has a Vendure account
    const existingCustomer = await this.externalAuthenticationService.findCustomerUser(
      ctx,
      this.name,
      user.login, // GitHub username as external identifier
    );

    if (existingCustomer) {
      // User exists, log them in
      return existingCustomer;
    }

    // Step 4: Create a new customer account for first-time GitHub users
    const newCustomer = await this.externalAuthenticationService.createCustomerAndUser(ctx, {
      strategy: this.name,
      externalIdentifier: user.login, // Store GitHub username
      verified: true, // GitHub accounts are pre-verified
      emailAddress: `${user.login}-github@vendure.io`, // Unique email to avoid conflicts
      firstName: user.name?.split(' ')[0] || user.login,
      lastName: user.name?.split(' ').slice(1).join(' ') || '',
    });

    return newCustomer;
  }
}
```

The strategy uses Vendure's [ExternalAuthenticationService](/reference/typescript-api/auth/external-authentication-service/) to handle customer creation.

It generates a unique email address for each GitHub user to avoid conflicts, and stores the GitHub username as the external identifier for future logins.

## Registering the Strategy

Now update the generated plugin file to register your authentication strategy:

```ts title="src/plugins/github-auth-plugin/github-auth-plugin.plugin.ts"
import { PluginCommonModule, VendurePlugin } from '@vendure/core';

import { GitHubAuthenticationStrategy, GitHubAuthOptions } from './github-auth-strategy';

@VendurePlugin({
  imports: [PluginCommonModule],
  configuration: config => {
    config.authOptions.shopAuthenticationStrategy.push(new GitHubAuthenticationStrategy(GitHubAuthPlugin.options));
    return config;
  },
})
export class GitHubAuthPlugin {
  static options: GitHubAuthOptions;

  static init(options: GitHubAuthOptions) {
    this.options = options;
    return GitHubAuthPlugin;
  }
}
```

## Adding to Vendure Config

Add the plugin to your Vendure configuration:

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';
import { GitHubAuthPlugin } from './plugins/github-auth-plugin/github-auth-plugin.plugin';

export const config: VendureConfig = {
  // ... other config
  plugins: [
    // ... other plugins
    GitHubAuthPlugin.init({
      clientId: process.env.GITHUB_CLIENT_ID!,
      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
    }),
  ],
  // ... rest of config
};
```

## Setting up GitHub OAuth App

Before you can test the integration, you need to create a GitHub OAuth App:

1. Go to [GitHub Settings → Developer settings → OAuth Apps](https://github.com/settings/developers)
2. Click "New OAuth App"
3. Fill in the required fields:
   - **Application name**: Your app name (e.g., "My Vendure Store")
   - **Homepage URL**: `http://localhost:3001` (your storefront URL)
   - **Authorization callback URL**: `http://localhost:3001/auth/github/callback`
4. Click "Register application"
5. Copy the Client ID and generate a Client Secret

:::note
The localhost URLs shown here are for local development only. In production, replace `localhost:3001` with your actual domain (e.g., `https://mystore.com`).
:::

Add these credentials to your environment:

```bash title=".env"
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
```

## Frontend Integration

### Creating the Sign-in URL

In your storefront, create a function to generate the GitHub authorization URL:

```typescript title="utils/github-auth.ts"
export function createGitHubSignInUrl(): string {
  const clientId = process.env.NEXT_PUBLIC_GITHUB_CLIENT_ID;
  const redirectUri = encodeURIComponent('http://localhost:3001/auth/github/callback');
  const state = Math.random().toString(36).substring(2);

  // Store state for CSRF protection
  sessionStorage.setItem('github_oauth_state', state);

  return `https://github.com/login/oauth/authorize?client_id=${clientId}&redirect_uri=${redirectUri}&scope=read:user&state=${state}`;
}
```

### Handling the Callback

Create a callback handler to process the GitHub response and authenticate with Vendure:

```typescript title="pages/auth/github/callback.ts"
import { gql } from 'graphql-request';

const AUTHENTICATE_MUTATION = gql`
  mutation Authenticate($input: GitHubAuthInput!) {
    authenticate(input: { github: $input }) {
      ... on CurrentUser {
        id
        identifier
        channels {
          code
          token
          permissions
        }
      }
      ... on InvalidCredentialsError {
        authenticationError
        errorCode
        message
      }
    }
  }
`;

export async function handleGitHubCallback(code: string, state: string) {
  // Verify CSRF protection
  const storedState = sessionStorage.getItem('github_oauth_state');
  if (state !== storedState) {
    throw new Error('Invalid state parameter');
  }

  sessionStorage.removeItem('github_oauth_state');

  // Authenticate with Vendure
  const result = await vendureClient.request(AUTHENTICATE_MUTATION, {
    input: { code, state }
  });

  if (result.authenticate.__typename === 'CurrentUser') {
    // Authentication successful - redirect to account page
    return result.authenticate;
  } else {
    // Handle authentication error
    throw new Error(result.authenticate.message);
  }
}
```

The OAuth flow follows these steps:

1. User clicks "Sign in with GitHub" → redirected to GitHub
2. User authorizes your app → GitHub redirects back with code and state
3. Your callback exchanges the code for user data → creates Vendure session

## Using the GraphQL API

Once your plugin is running, the GitHub authentication will be available in your shop API:

<Tabs>
<TabItem value="Mutation" label="Mutation" default>

```graphql
mutation AuthenticateWithGitHub {
  authenticate(input: {
    github: {
      code: "authorization_code_from_github",
      state: "csrf_protection_state"
    }
  }) {
    ... on CurrentUser {
      id
      identifier
      channels {
        code
        token
        permissions
      }
    }
    ... on InvalidCredentialsError {
      authenticationError
      errorCode
      message
    }
  }
}
```

</TabItem>
<TabItem value="Response" label="Response">

```json
{
  "data": {
    "authenticate": {
      "id": "1",
      "identifier": "github-user-github@vendure.io",
      "channels": [
        {
          "code": "__default_channel__",
          "token": "session_token_here",
          "permissions": ["Authenticated"]
        }
      ]
    }
  }
}
```

</TabItem>
</Tabs>

## Customer Data Management

GitHub-authenticated customers are managed like any other Vendure [Customer](/reference/typescript-api/entities/customer/):

- **Email**: Generated as `{username}-github@vendure.io` to avoid conflicts
- **Verification**: Automatically verified (GitHub handles email verification)
- **External ID**: GitHub username stored for future authentication
- **Profile**: Name extracted from GitHub profile when available

This means GitHub users work seamlessly with Vendure's [order management](/guides/core-concepts/orders/), [promotions](/guides/core-concepts/promotions/), and customer workflows.

## Testing the Integration

To test your GitHub OAuth integration:

1. Start your Vendure server with the plugin configured
2. Navigate to your storefront and click the GitHub sign-in link
3. Authorize your GitHub app when prompted
4. Verify that a new customer is created in the Vendure Admin UI
5. Check that subsequent logins find the existing customer account


---

---
title: "Google OAuth Authentication"
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

:::info
The complete source of the following example plugin can be found here: [example-plugins/google-auth-plugin](https://github.com/vendure-ecommerce/examples/tree/master/examples/shop-google-auth)
:::

**Google OAuth authentication** allows customers to sign in using their Google accounts, providing a seamless experience that eliminates the need for password-based registration.

This is particularly valuable for **consumer-facing stores** where users prefer the convenience and security of Google's authentication system, or for **B2B platforms** where organizations use Google Workspace.

This guide shows you how to **add Google OAuth support** to your Vendure store using a custom [AuthenticationStrategy](/reference/typescript-api/auth/authentication-strategy/) and Google Identity Services.

An **AuthenticationStrategy** in Vendure defines how users can log in to your store. Learn more about [authentication in Vendure](/guides/core-concepts/auth/).

## Creating the Plugin

**First, use the Vendure CLI** to create a new plugin for Google authentication:

```bash
npx vendure add -p GoogleAuthPlugin
```

This creates a basic [plugin](/guides/developer-guide/plugins/) structure with the necessary files.

## Installing Dependencies

**Google authentication requires** the Google Auth Library for token verification:

```bash
npm install google-auth-library
```

This library handles ID token verification securely on the server side, ensuring the tokens received from Google are authentic.

## Creating the Authentication Strategy

**Now create the Google authentication strategy.** Unlike traditional OAuth flows that use authorization codes, Google Identity Services provides **ID tokens directly**, which we verify server-side:

```ts title="src/plugins/google-auth-plugin/google-auth-strategy.ts"
import {
  AuthenticationStrategy,
  ExternalAuthenticationService,
  Injector,
  Logger,
  RequestContext,
  User,
} from '@vendure/core';
import { OAuth2Client } from 'google-auth-library';
import { DocumentNode } from 'graphql';
import { gql } from 'graphql-tag';

export type GoogleAuthData = {
  token: string;
}

export interface GoogleAuthOptions {
  googleClientId: string;
  onUserCreated?: (ctx: RequestContext, injector: Injector, user: User) => void;
  onUserFound?: (ctx: RequestContext, injector: Injector, user: User) => void;
}

export class GoogleAuthStrategy implements AuthenticationStrategy<GoogleAuthData> {
  readonly name = 'google';
  private client: OAuth2Client;
  private externalAuthenticationService: ExternalAuthenticationService;
  private logger: Logger;
  private injector: Injector;

  constructor(private options: GoogleAuthOptions) {
    // Initialize Google OAuth2Client for token verification
    this.client = new OAuth2Client(options.googleClientId);
    this.logger = new Logger();
  }

  init(injector: Injector) {
    // Get services we'll use for customer management
    this.externalAuthenticationService = injector.get(ExternalAuthenticationService);
    this.injector = injector;
  }

  defineInputType(): DocumentNode {
    // Define the GraphQL input type for the authenticate mutation
    return gql`
      input GoogleAuthInput {
        token: String!
      }
    `;
  }

  async authenticate(ctx: RequestContext, data: GoogleAuthData): Promise<User | false> {
    try {
      // Step 1: Verify the Google ID token
      const ticket = await this.client.verifyIdToken({
        idToken: data.token,
        audience: this.options.googleClientId,
      });

      const payload = ticket.getPayload();

      if (!payload || !payload.email) {
        this.logger.error('Invalid Google token or missing email', 'GoogleAuthStrategy');
        return false;
      }

      // Step 2: Check if this Google user already has a Vendure account
      const existingUser = await this.externalAuthenticationService.findCustomerUser(
        ctx,
        this.name,
        payload.sub, // Google's unique user ID
      );

      if (existingUser) {
        // User exists, log them in
        this.logger.verbose(`User found: ${existingUser.identifier}`, 'GoogleAuthStrategy');
        this.options.onUserFound?.(ctx, this.injector, existingUser);
        return existingUser;
      }

      // Step 3: Create a new customer account for first-time Google users
      const createdUser = await this.externalAuthenticationService.createCustomerAndUser(ctx, {
        strategy: this.name,
        externalIdentifier: payload.sub, // Store Google user ID
        verified: payload.email_verified || false, // Use Google's verification status
        emailAddress: payload.email,
        firstName: payload.given_name || 'Google',
        lastName: payload.family_name || 'User',
      });

      this.options.onUserCreated?.(ctx, this.injector, createdUser);

      return createdUser;
    } catch (error) {
      this.logger.error(`Google authentication failed: ${error.message}`, 'GoogleAuthStrategy');
      return false;
    }
  }
}
```

The strategy uses Google's [OAuth2Client](https://googleapis.dev/nodejs/google-auth-library/latest/classes/OAuth2Client.html) to verify ID tokens and Vendure's [ExternalAuthenticationService](/reference/typescript-api/auth/external-authentication-service/) to handle customer creation.

Key differences from other OAuth flows:
- **ID Token Verification**: Google provides signed JWT tokens that we verify directly
- **No Code Exchange**: Unlike GitHub OAuth, there's no authorization code to exchange
- **Email Verification**: We respect Google's email verification status
- **Fallback Names**: Provides defaults if Google profile lacks name information

## Registering the Strategy

**Now update the generated plugin file** to register your authentication strategy:

```ts title="src/plugins/google-auth-plugin/google-auth-plugin.plugin.ts"
import { PluginCommonModule, VendurePlugin } from '@vendure/core';

import { GoogleAuthStrategy } from './google-auth-strategy';

export interface GoogleAuthPluginOptions {
  googleClientId: string;
}

@VendurePlugin({
  imports: [PluginCommonModule],
  configuration: (config) => {
    const options = GoogleAuthPlugin.options;
    
    if (options?.googleClientId) {
      config.authOptions.shopAuthenticationStrategy.push(
        new GoogleAuthStrategy({ googleClientId: options.googleClientId })
      );
    }
    return config;
  },
})
export class GoogleAuthPlugin {
  static options: GoogleAuthPluginOptions;

  static init(options: GoogleAuthPluginOptions) {
    this.options = options;
    return GoogleAuthPlugin;
  }
}
```

## Adding to Vendure Config

**Add the plugin** to your Vendure configuration:

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';
import { GoogleAuthPlugin } from './plugins/google-auth-plugin/google-auth-plugin.plugin';

export const config: VendureConfig = {
  // ... other config
  plugins: [
    // ... other plugins
    GoogleAuthPlugin.init({
      googleClientId: process.env.GOOGLE_CLIENT_ID!,
    }),
  ],
  // ... rest of config
};
```

## Setting up Google OAuth App

**Before you can test the integration,** you need to create a Google OAuth 2.0 Client:

1. **Go to** the [Google Cloud Console](https://console.cloud.google.com/)
2. **Create a new project** or select an existing one
3. **Navigate to** **APIs & Services → Credentials**
4. **Click** **"Create Credentials" → "OAuth 2.0 Client ID"**
5. **Select** **"Web application"** as the application type
6. **Configure the client:**
   - **Name**: Your app name (e.g., "My Vendure Store")
   - **Authorized JavaScript origins**: `http://localhost:3001`
   - **Authorized redirect URIs**: `http://localhost:3001/sign-in`

:::note
The **localhost URLs** shown here are for **local development only.** In production, replace `localhost:3001` with your actual domain (e.g., `https://mystore.com`).
:::

7. **Click "Create"** and copy the Client ID

**Add the client ID** to your environment:

```bash title=".env"
GOOGLE_CLIENT_ID=your_google_client_id.apps.googleusercontent.com
```

## Frontend Integration

### Creating the Sign-in Component

**For the frontend,** we'll use Google's official Identity Services library, which provides a **secure and user-friendly sign-in experience:**

```typescript title="components/GoogleSignInButton.tsx"
'use client';

import { useEffect, useState } from 'react';
import { useRouter } from 'next/navigation';

const GOOGLE_CLIENT_ID = process.env.NEXT_PUBLIC_GOOGLE_CLIENT_ID;

declare global {
  interface Window {
    google: any;
    handleCredentialResponse?: (response: any) => void;
  }
}

export function GoogleSignInButton() {
  const router = useRouter();
  const [pending, setPending] = useState(false);

  useEffect(() => {
    // Define the callback function globally
    window.handleCredentialResponse = async (response: any) => {
      setPending(true);
      try {
        const result = await authenticateWithGoogle(response.credential);

        if (result?.success) {
          router.replace('/account');
        } else {
          console.error('Authentication failed:', result?.message);
        }
      } catch (error) {
        console.error('Google authentication error:', error);
      } finally {
        setPending(false);
      }
    };

    // Load Google Identity Services
    if (!window.google && GOOGLE_CLIENT_ID) {
      const script = document.createElement('script');
      script.src = 'https://accounts.google.com/gsi/client';
      script.async = true;
      script.onload = () => {
        window.google.accounts.id.initialize({
          client_id: GOOGLE_CLIENT_ID,
          callback: window.handleCredentialResponse,
        });
      };
      document.head.appendChild(script);
    }

    return () => {
      delete window.handleCredentialResponse;
    };
  }, [router]);

  const handleGoogleSignIn = () => {
    if (!GOOGLE_CLIENT_ID) {
      console.error('Google Client ID not configured');
      return;
    }

    if (window.google) {
      window.google.accounts.id.prompt();
    } else {
      console.error('Google SDK not loaded');
    }
  };

  return (
    <button
      onClick={handleGoogleSignIn}
      disabled={pending}
      className="flex items-center justify-center w-full px-4 py-2 border border-gray-300 rounded-md shadow-sm text-sm font-medium text-gray-700 bg-white hover:bg-gray-50 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-indigo-500"
    >
      {pending ? (
        'Authenticating...'
      ) : (
        <>
          <svg className="w-5 h-5 mr-2" viewBox="0 0 24 24">
            <path fill="#4285F4" d="M22.56 12.25c0-.78-.07-1.53-.2-2.25H12v4.26h5.92c-.26 1.37-1.04 2.53-2.21 3.31v2.77h3.57c2.08-1.92 3.28-4.74 3.28-8.09z"/>
            <path fill="#34A853" d="M12 23c2.97 0 5.46-.98 7.28-2.66l-3.57-2.77c-.98.66-2.23 1.06-3.71 1.06-2.86 0-5.29-1.93-6.16-4.53H2.18v2.84C3.99 20.53 7.7 23 12 23z"/>
            <path fill="#FBBC05" d="M5.84 14.09c-.22-.66-.35-1.36-.35-2.09s.13-1.43.35-2.09V7.07H2.18C1.43 8.55 1 10.22 1 12s.43 3.45 1.18 4.93l2.85-2.22.81-.62z"/>
            <path fill="#EA4335" d="M12 5.38c1.62 0 3.06.56 4.21 1.64l3.15-3.15C17.45 2.09 14.97 1 12 1 7.7 1 3.99 3.47 2.18 7.07l3.66 2.84c.87-2.6 3.3-4.53 6.16-4.53z"/>
          </svg>
          Continue with Google
        </>
      )}
    </button>
  );
}
```

### Creating the Authentication Function

**Create a server action** to handle the Google authentication:

```typescript title="actions/auth.ts"
'use server';

import { gql } from 'graphql-request';

const AUTHENTICATE_MUTATION = gql`
  mutation AuthenticateWithGoogle($input: AuthenticationInput!) {
    authenticate(input: $input) {
      ... on CurrentUser {
        id
        identifier
        channels {
          code
          token
          permissions
        }
      }
      ... on InvalidCredentialsError {
        authenticationError
        errorCode
        message
      }
      ... on NotVerifiedError {
        errorCode
        message
      }
    }
  }
`;

export async function authenticateWithGoogle(token: string) {
  try {
    const result = await vendureClient.request(AUTHENTICATE_MUTATION, {
      input: {
        google: {
          token
        }
      }
    });

    if (result.authenticate.__typename === 'CurrentUser') {
      // Authentication successful
      return { success: true, user: result.authenticate };
    } else {
      // Handle authentication error
      return {
        success: false,
        message: result.authenticate.message
      };
    }
  } catch (error) {
    console.error('Google authentication error:', error);
    return {
      success: false,
      message: 'Authentication failed'
    };
  }
}
```

**Add your Google Client ID** to the frontend environment:

```bash title=".env.local"
NEXT_PUBLIC_GOOGLE_CLIENT_ID=your_google_client_id.apps.googleusercontent.com
VENDURE_API_ENDPOINT=http://localhost:3000/shop-api
```

**The Google Identity Services flow works as follows:**

1. **User clicks "Continue with Google"** → Google popup appears
2. **User signs in with Google** → Google returns an ID token  
3. **Frontend sends the token to Vendure** → Vendure verifies token with Google
4. **If valid, Vendure creates/finds customer** → User is logged in

## Using the GraphQL API

**Once your plugin is running,** Google authentication will be **available in your shop API:**

<Tabs>
<TabItem value="Mutation" label="Mutation" default>

```graphql
mutation AuthenticateWithGoogle {
  authenticate(input: {
    google: {
      token: "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
  }) {
    ... on CurrentUser {
      id
      identifier
      channels {
        code
        token
        permissions
      }
    }
    ... on InvalidCredentialsError {
      authenticationError
      errorCode
      message
    }
    ... on NotVerifiedError {
      errorCode
      message
    }
  }
}
```

</TabItem>
<TabItem value="Response" label="Response">

```json
{
  "data": {
    "authenticate": {
      "id": "1",
      "identifier": "user@gmail.com",
      "channels": [
        {
          "code": "__default_channel__",
          "token": "session_token_here",
          "permissions": ["Authenticated"]
        }
      ]
    }
  }
}
```

</TabItem>
</Tabs>

## Customer Data Management

**Google-authenticated customers** are managed like any other Vendure [Customer](/reference/typescript-api/entities/customer/):

- **Email**: Uses the user's actual Google email address
- **Verification**: Inherits Google's email verification status
- **External ID**: Google's unique user ID (`sub` claim) for future authentication
- **Profile**: First and last names from Google profile, with fallbacks
- **Security**: No password stored - authentication handled entirely by Google

This means **Google users work seamlessly** with Vendure's [order management](/guides/core-concepts/orders/), [promotions](/guides/core-concepts/promotions/), and all customer workflows.

## Testing the Integration

**To test your Google OAuth integration:**

1. **Start your Vendure server** with the plugin configured
2. **Navigate to your storefront** and click "Continue with Google"  
3. **Complete the Google OAuth flow** when prompted
4. **Verify customer creation** in the Vendure Admin UI
5. **Test repeat logins** to ensure existing customers are found correctly


---

---
title: "Multi-vendor Marketplaces"
---

# Multi-vendor Marketplaces

Vendure v2.0 introduced a number of changes and new APIs to enable developers to build multi-vendor marketplace apps.

This is a type of application in which multiple sellers are able to list products, and then customers can create orders containing products from one or more of these sellers. Well-known examples include Amazon, Ebay, Etsy and Airbnb.

This guide introduces the major concepts & APIs you will need to understand in order to implement your own multi-vendor marketplace application. 

## Multi-vendor plugin

All the concepts presented here have been implemented in our [example multi-vendor plugin](https://github.com/vendure-ecommerce/vendure/tree/master/packages/dev-server/example-plugins/multivendor-plugin). The guides here will refer to specific parts of this plugin which you should consult to get a full understanding of how an implementation would look.

:::caution
**Note:** the [example multi-vendor plugin](https://github.com/vendure-ecommerce/vendure/tree/master/packages/dev-server/example-plugins/multivendor-plugin) is for educational purposes only, and for the sake of clarity leaves out several parts that would be required in a production-ready solution, such as email verification and setup of a real payment solution.
:::

![The Admin UI Aggregate Order screen](./aggregate-order.webp)

## Sellers, Channels & Roles

The core of Vendure's multi-vendor support is Channels. Read the [Channels guide](/guides/core-concepts/channels/) to get a more detailed understanding of how they work.

Each Channel is assigned to a [Seller](/reference/typescript-api/entities/seller/), which is another term for the vendor who is selling things in our marketplace.

So the first thing to do is to implement a way to create a new Channel and Seller.

In the multi-vendor plugin, we have defined a new mutation in the Shop API which allows a new seller to register on our marketplace:

```graphql title="Shop API"
mutation RegisterSeller {
  registerNewSeller(input: {
    shopName: "Bob's Parts",
    seller: {
      firstName: "Bob"
      lastName: "Dobalina"
      emailAddress: "bob@bobs-parts.com"
      password: "test",
    }
  }) {
    id
    code
    token
  }
}
```

Executing the `registerNewSeller` mutation does the following:

- Create a new [Seller](/reference/typescript-api/entities/seller/) representing the shop "Bob's Parts"
- Create a new [Channel](/reference/typescript-api/entities/channel) and associate it with the new Seller
- Create a [Role](/reference/typescript-api/entities/role) & [Administrator](/reference/typescript-api/entities/administrator) for Bob to access his shop admin account
- Create a [ShippingMethod](/reference/typescript-api/entities/shipping-method) for Bob's shop
- Create a [StockLocation](/reference/typescript-api/entities/stock-location) for Bob's shop

Bob can now log in to the Admin UI using the provided credentials and begin creating products to sell!

### Keeping prices synchronized

In some marketplaces, the same product may be sold by multiple sellers. When this is the case, the product and its variants
will be assigned not only to the default channel, but to multiple other channels as well - see the 
[Channels, Currencies & Prices section](/guides/core-concepts/channels/#channels-currencies--prices) for a visual explanation of how this works.

This means that there will be multiple ProductVariantPrice entities per variant, one for each channel. 
 
In order
to keep prices synchronized across all channels, the example multi-vendor plugin sets the `syncPricesAcrossChannels` property
of the [DefaultProductVariantPriceUpdateStrategy](/reference/typescript-api/configuration/product-variant-price-update-strategy#defaultproductvariantpriceupdatestrategy)
to `true`. Your own multi-vendor implementation may require more sophisticated price synchronization logic, in which case
you can implement your own custom [ProductVariantPriceUpdateStrategy](/reference/typescript-api/configuration/product-variant-price-update-strategy).

## Assigning OrderLines to the correct Seller

In order to correctly split the Order later, we need to assign each added OrderLine to the correct Seller. This is done with the [OrderSellerStrategy](/reference/typescript-api/orders/order-seller-strategy/) API, and specifically the `setOrderLineSellerChannel()` method.

The following logic will run any time the `addItemToOrder` mutation is executed from our storefront:

```ts
export class MultivendorSellerStrategy implements OrderSellerStrategy {
  // other properties omitted for brevity   
    
  async setOrderLineSellerChannel(ctx: RequestContext, orderLine: OrderLine) {
    await this.entityHydrator.hydrate(ctx, orderLine.productVariant, { relations: ['channels'] });
    const defaultChannel = await this.channelService.getDefaultChannel();
  
    // If a ProductVariant is assigned to exactly 2 Channels, then one is the default Channel
    // and the other is the seller's Channel.
    if (orderLine.productVariant.channels.length === 2) {
      const sellerChannel = orderLine.productVariant.channels.find(
        c => !idsAreEqual(c.id, defaultChannel.id),
      );
      if (sellerChannel) {
        return sellerChannel;
      }
    }
  }
}
```

The end result is that each OrderLine in the Order will have its `sellerChannelId` property set to the correct Channel for the Seller.

## Shipping

When it comes time to choose a ShippingMethod for the Order, we need to ensure that the customer can only choose from the ShippingMethods which are supported by the Seller. To do this, we need to implement a [ShippingEligibilityChecker](/reference/typescript-api/shipping/shipping-eligibility-checker/) which will filter the available ShippingMethods based on the `sellerChannelId` properties of the OrderLines.

Here's how we do it in the example plugin:

```ts
export const multivendorShippingEligibilityChecker = new ShippingEligibilityChecker({
  // other properties omitted for brevity   
    
  check: async (ctx, order, args, method) => {
    await entityHydrator.hydrate(ctx, method, { relations: ['channels'] });
    await entityHydrator.hydrate(ctx, order, { relations: ['lines.sellerChannel'] });
    const sellerChannel = method.channels.find(c => c.code !== DEFAULT_CHANNEL_CODE);
    if (!sellerChannel) {
      return false;
    }
    for (const line of order.lines) {
      if (idsAreEqual(line.sellerChannelId, sellerChannel.id)) {
        return true;
      }
    }
    return false;
  },
});
```

In the storefront, when it comes time to assign ShippingMethods to the Order, we need to ensure that
every OrderLine is covered by a valid ShippingMethod. We pass the ids of the eligible ShippingMethods to the `setOrderShippingMethod` mutation:

```graphql
mutation SetShippingMethod($ids: [ID!]!) {
  setOrderShippingMethod(shippingMethodId: $ids) {
    ... on Order {
      id
      state
      # ...etc
    }
    ... on ErrorResult {
      errorCode
      message
    }
  }
}
```

Now we need a way to assign the correct method to each line in an Order. This is done with the [ShippingLineAssignmentStrategy](/reference/typescript-api/shipping/shipping-line-assignment-strategy/) API.

We will again be relying on the `sellerChannelId` property of the OrderLines to determine which ShippingMethod to assign to each line. Here's how we do it in the example plugin:

```ts
export class MultivendorShippingLineAssignmentStrategy implements ShippingLineAssignmentStrategy {
  // other properties omitted for brevity   
    
  async assignShippingLineToOrderLines(ctx: RequestContext, shippingLine: ShippingLine, order: Order) {
    // First we need to ensure the required relations are available
    // to work with.
    const defaultChannel = await this.channelService.getDefaultChannel();
    await this.entityHydrator.hydrate(ctx, shippingLine, { relations: ['shippingMethod.channels'] });
    const { channels } = shippingLine.shippingMethod;
  
    // We assume that, if a ShippingMethod is assigned to exactly 2 Channels,
    // then one is the default Channel and the other is the seller's Channel.
    if (channels.length === 2) {
      const sellerChannel = channels.find(c => !idsAreEqual(c.id, defaultChannel.id));
      if (sellerChannel) {
        // Once we have established the seller's Channel, we can filter the OrderLines
        // that belong to that Channel. The `sellerChannelId` was previously established
        // in the `OrderSellerStrategy.setOrderLineSellerChannel()` method.
        return order.lines.filter(line => idsAreEqual(line.sellerChannelId, sellerChannel.id));
      }
    }
    return order.lines;
  }
}
```

## Splitting orders & payment

When it comes to payments, there are many different ways that a multi-vendor marketplace might want to handle this. For example, the marketplace may collect all payments and then later disburse the funds to the Sellers. Or the marketplace may allow each Seller to connect their own payment gateway and collect payments directly.

In the example plugin, we have implemented a simplified version of a service like [Stripe Connect](https://stripe.com/connect), whereby each Seller has a `connectedAccountId` (we auto-generate a random string for the example when registering the Seller). When configuring the plugin we also specify a "platform fee" percentage, which is the percentage of the total Order value which the marketplace will collect as a fee. The remaining amount is then split between the Sellers.

The [OrderSellerStrategy](/reference/typescript-api/orders/order-seller-strategy/) API contains two methods which are used to first split the Order from a single order into one _Aggregate Order_ and multiple _Seller Orders_, and then to calculate the platform fee for each of the Seller Orders:

- `OrderSellerStrategy.splitOrder`: Splits the OrderLines and ShippingLines of the Order into multiple groups, one for each Seller.
- `OrderSellerStrategy.afterSellerOrdersCreated`: This method is run on every Seller Order created after the split, and we can use this to assign the platform fees to the Seller Order.

## Custom OrderProcess

Finally, we need a custom [OrderProcess](/reference/typescript-api/orders/order-process/) which will help keep the state of the resulting Aggregate Order and its Seller Orders in sync. For example, we want to make sure that the Aggregate Order cannot be transitioned to the `Shipped` state unless all of its Seller Orders are also in the `Shipped` state.

Conversely, we can automatically set the state of the Aggregate Order to `Shipped` once all of its Seller Orders are in the `Shipped` state.


---

---
title: "Paginated lists"
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Vendure's list queries follow a set pattern which allows for pagination, filtering & sorting. This guide will demonstrate how
to implement your own paginated list queries.

## API definition

Let's start with defining the GraphQL schema for our query. In this example, we'll image that we have defined a [custom entity](/guides/developer-guide/database-entity/) to
represent a `ProductReview`. We want to be able to query a list of reviews in the Admin API. Here's how the schema definition
would look:

```ts title="src/plugins/reviews/api/api-extensions.ts"
import gql from 'graphql-tag';

export const adminApiExtensions = gql`
type ProductReview implements Node {
  id: ID!
  createdAt: DateTime!
  updatedAt: DateTime!
  product: Product!
  productId: ID!
  text: String!
  rating: Float!
}

type ProductReviewList implements PaginatedList {
  items: [ProductReview!]!
  totalItems: Int!
}

# Generated at run-time by Vendure
input ProductReviewListOptions

extend type Query {
   productReviews(options: ProductReviewListOptions): ProductReviewList!
}
`;
```

Note that we need to follow these conventions:

- The type must implement the `Node` interface, i.e. it must have an `id: ID!` field.
- The list type must be named `<EntityName>List` and must implement the `PaginatedList` interface.
- The list options input type must be named `<EntityName>ListOptions`.

Given this schema, at runtime Vendure will automatically generate the `ProductReviewListOptions` input type, including all the
filtering & sorting fields. This means that we don't need to define the input type ourselves.

## Resolver

Next, we need to define the resolver for the query.

```ts title="src/plugins/reviews/api/admin.resolver.ts"
import { Args, Query, Resolver } from '@nestjs/graphql';
import { Ctx, PaginatedList, RequestContext } from '@vendure/core';

import { ProductReview } from '../entities/product-review.entity';
import { ProductReviewService } from '../services/product-review.service';

@Resolver()
export class ProductReviewAdminResolver {
    constructor(private productReviewService: ProductReviewService) {}

    @Query()
    async productReviews(
        @Ctx() ctx: RequestContext,
        @Args() args: any,
    ): Promise<PaginatedList<ProductReview>> {
        return this.productReviewService.findAll(ctx, args.options || undefined);
    }
}
```

## Service

Finally, we need to implement the `findAll()` method on the `ProductReviewService`. Here we will use the
[`ListQueryBuilder`](/reference/typescript-api/data-access/list-query-builder/) to build the list query. The
`ListQueryBuilder` will take care of

```ts title="src/plugins/reviews/services/product-review.service.ts"
import { Injectable } from '@nestjs/common';
import { InjectConnection } from '@nestjs/typeorm';
import { ListQueryBuilder, ListQueryOptions, PaginatedList, RequestContext } from '@vendure/core';

import { ProductReview } from '../entities/product-review.entity';

@Injectable()
export class ProductReviewService {
    constructor(
        private listQueryBuilder: ListQueryBuilder,
    ) {}

    findAll(ctx: RequestContext, options?: ListQueryOptions<ProductReview>): Promise<PaginatedList<ProductReview>> {
        return this.listQueryBuilder
            .build(ProductReview, options, { relations: ['product'], ctx })
            .getManyAndCount()
            .then(([items, totalItems]) => ({ items, totalItems }));
    }
}
```

## Usage

Given the above parts of the plugin, we can now query the list of reviews in the Admin API:


<Tabs>
<TabItem value="Query" label="Query" default>

```graphql
query {
  productReviews(
    options: {
      // highlight-start
      skip: 0
      take: 10
      sort: {
        createdAt: DESC
      }
      filter: {
        rating: {
          between: { start: 3, end: 5 }
        }
      }
      // highlight-end
    }) {
    totalItems
    items {
      id
      createdAt
      product {
        name
      }
      text
      rating
    }
  }
}
```

</TabItem>
<TabItem value="Response" label="Response" >

```json
{
  "data": {
    "productReviews": {
      "totalItems": 3,
      "items": [
        {
          "id": "12",
          "createdAt": "2023-08-23T12:00:00Z",
          "product": {
            "name": "Smartphone X"
          },
          "text": "The best phone I've ever had!",
          "rating": 5
        },
        {
          "id": "42",
          "createdAt": "2023-08-22T15:30:00Z",
          "product": {
            "name": "Laptop Y"
          },
          "text": "Impressive performance and build quality.",
          "rating": 4
        },
        {
          "id": "33",
          "createdAt": "2023-08-21T09:45:00Z",
          "product": {
            "name": "Headphones Z"
          },
          "text": "Decent sound quality but uncomfortable.",
          "rating": 3
        }
      ]
    }
  }
}
```

</TabItem>
</Tabs>

In the above example, we are querying the first 10 reviews, sorted by `createdAt` in descending order, and filtered to only
include reviews with a rating between 3 and 5.

## Advanced filtering

Vendure v2.2.0 introduced the ability to construct complex nested filters on any PaginatedList query. For example, we could
filter the above query to only include reviews for products with a name starting with "Smartphone":

<Tabs>
<TabItem value="Query" label="Query" default>

```graphql
query {
  productReviews(
    options: {
    skip: 0
    take: 10
    // highlight-start
    filter: {
      _and: [
        { text: { startsWith: "phone" } },
        {
          _or: [
            { rating: { gte: 4 } },
            { rating: { eq: 0 } }
          ]
        }
      ]
    }
    // highlight-end
    }) {
    totalItems
    items {
      id
      createdAt
      product {
        name
      }
      text
      rating
    }
  }
}
```

</TabItem>
<TabItem value="Response" label="Response" >

```json
{
  "data": {
    "productReviews": {
      "totalItems": 3,
      "items": [
        {
          "id": "12",
          "createdAt": "2023-08-23T12:00:00Z",
          "product": {
            "name": "Smartphone X"
          },
          "text": "The best phone I've ever had!",
          "rating": 5
        },
        {
          "id": "42",
          "createdAt": "2023-08-22T15:30:00Z",
          "product": {
            "name": "Smartphone Y"
          },
          "text": "Not a very good phone at all.",
          "rating": 0
        }
      ]
    }
  }
}
```

</TabItem>
</Tabs>

In the example above, we are filtering for reviews of products with the word "phone" and a rating of 4 or more,
or a rating of 0. The `_and` and `_or` operators can be nested to any depth, allowing for arbitrarily complex filters.

## Filtering by custom properties

By default, the `ListQueryBuilder` will only allow filtering by properties which are defined on the entity itself.
So in the case of the `ProductReview`, we can filter by `rating` and `text` etc., but not by `product.name`.

However, it is possible to extend your GraphQL type to allow filtering by custom properties. Let's implement filtering
but the `product.name` property. First, we need to manually add the `productName` field to
the `ProductReviewFilterParameter` type:

```ts title="src/plugins/reviews/api/api-extensions.ts"
import gql from 'graphql-tag';

export const adminApiExtensions = gql`
# ... existing definitions from earlier example omitted

// highlight-start
input ProductReviewFilterParameter {
  productName: StringOperators
}
// highlight-end
`;
```

Next we need to update our `ProductReviewService` to be able to handle filtering on this new field using the
[customPropertyMap](/reference/typescript-api/data-access/list-query-builder/#custompropertymap) option:

```ts title="src/plugins/reviews/services/product-review.service.ts"
import { Injectable } from '@nestjs/common';
import { InjectConnection } from '@nestjs/typeorm';
import { ListQueryBuilder, ListQueryOptions, PaginatedList, RequestContext } from '@vendure/core';

import { ProductReview } from '../entities/product-review.entity';

@Injectable()
export class ProductReviewService {
    constructor(
        private listQueryBuilder: ListQueryBuilder,
    ) {}

    findAll(ctx: RequestContext, options?: ListQueryOptions<ProductReview>): Promise<PaginatedList<ProductReview>> {
        return this.listQueryBuilder
            .build(ProductReview, options, {
                // highlight-next-line
                relations: ['product'],
                ctx,
                // highlight-start
                customPropertyMap: {
                    productName: 'product.name',
                }
                // highlight-end
            })
            .getManyAndCount()
            .then(([items, totalItems]) => ({ items, totalItems }));
    }
}
```

Upon restarting your server, you should now be able to filter by `productName`:

```graphql
query {
  productReviews(
    options: {
      skip: 0
      take: 10
      // highlight-start
      filter: {
        productName: {
          contains: "phone"
        }
      }
      // highlight-end
  }) {
    totalItems
    items {
      id
      createdAt
      product {
        name
      }
      text
      rating
    }
  }
}
```

---

---
title: "Publishing a Plugin"
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Vendure's [plugin-based architecture](/guides/developer-guide/plugins/) means you'll be writing a lot of plugins.
Some of those plugins may be useful to others, and you may want to share them with the community.

We have created [Vendure Hub](https://vendure.io/hub) as a central listing for high-quality Vendure plugins.

This guide will walk you through the process of publishing a plugin to npm and submitting it to Vendure Hub.

## Project setup

There are a couple of ways you can structure your plugin project:

### Repo structure

We recommend that you use a "monorepo" structure to develop your plugins. This means that you have a single repository
which contains all your plugins, each in its own subdirectory. This makes it easy to manage dependencies between plugins,
and to share common code such as utility functions & dev tooling.

Even if you only have a single plugin at the moment, it's a good idea to set up your project in this way from the start.

To that end, we provide a [monorepo plugin starter template](https://github.com/vendure-ecommerce/plugin-template)
which you can use as a starting point for your plugin development.

This starter template includes support for:

- Development & build scripts already set up
- Admin UI extensions already configured
- End-to-end testing infrastructure fully configured
- Code generation for your schema extensions

### Plugin naming

We recommend that you use [scoped packages](https://docs.npmjs.com/cli/v10/using-npm/scope#publishing-scoped-packages) for your plugins, which means
they will be named like `@<scope>/<plugin-name>`. For example, if your company is called `acme`, and you are publishing a plugin that
implements a loyalty points system, you could name it `@acme/vendure-plugin-loyalty-points`.

### Dependencies

Your plugin should **not** include Vendure packages as dependencies in the `package.json` file. You _may_ declare them as a peer dependencies, but this is not
a must. The same goes for any of the transitive dependencies of Vendure core such as `@nestjs/graphql`, `@nestjs/common`, `typeorm` etc. You can assume
that these dependencies will be available in the Vendure project that uses your plugin.

As for version compatibility, you should use the
[compatibility property](/guides/developer-guide/plugins/#step-7-specify-compatibility) in your plugin definition to ensure that the Vendure project
is using a compatible version of Vendure.

### License

You are free to license your plugin as you wish. Although Vendure itself is licensed under the GPLv3, there is
a special exception for plugins which allows you to distribute them under a different license. See the
[plugin exception](https://github.com/vendure-ecommerce/vendure/blob/master/license/plugin-exception.txt) for more details.

## Publishing to npm

Once your plugin is ready, you can publish it to npm. This is covered in the [npm documentation on publishing packages](https://docs.npmjs.com/creating-and-publishing-scoped-public-packages).

## Requirements for Vendure Hub

[Vendure Hub](https://vendure.io/hub) is a curated list of high-quality plugins. To be accepted into Vendure Hub, we require some additional
requirements be satisfied.

### Changelog

Your plugin package **must** include a `CHANGELOG.md` file which looks like this:

```md
# Changelog

## 1.6.1 (2024-06-07)

- Fix a bug where the `foo` was not correctly bar (Fixes [#123](https://github.com/myorg/my-repo/issues/31))

## 1.6.0 (2024-03-11)

- Add a new feature to the `bar` service
- Update the `baz` service to use the new `qux` method

... etc
```

The exact format of the entries is up to you - you can e.g. use [Keep a Changelog](https://keepachangelog.com/) format, grouping by type of change, using tooling
to help generate the entries, etc. The important thing is that the `CHANGELOG.md` file is present and up-to-date, and published as part of your
package by specifying it in the `files` field of your `package.json` file.

```json
{
 "files": [
    "dist",
    "README.md",
    // highlight-next-line
    "CHANGELOG.md"
  ]
}
```

Vendure Hub will read the contents of your changelog to display the latest changes in your plugin listing.

### Documentation

Good documentation is a key criteria for acceptance into Vendure Hub.

#### README.md

Your plugin package **must** include a `README.md` file which contains full instructions on how to install and use your plugin. Here's a template you can use:

<div class="limited-height-code-block">

````md
# Acme Loyalty Points Plugin

This plugin adds a loyalty points system to your Vendure store.

## Installation

```bash
npm install @acme/vendure-plugin-loyalty-points
```

Add the plugin to your Vendure config:

```ts
// vendure-config.ts
import { LoyaltyPointsPlugin } from '@acme/vendure-plugin-loyalty-points';

export const config = {
    //...
    plugins: [
        LoyaltyPointsPlugin.init({
            enablePartialRedemption: true,
        }),
    ],
};
```

[If your plugin includes UI extensions]
If not already installed, install the `@vendure/ui-devkit` package:

```bash
npm install @vendure/ui-devkit
```

Then set up the compilation of the UI extensions for the Admin UI:

```ts
// vendure-config.ts
import { compileUiExtensions } from '@vendure/ui-devkit/compiler';
import { LoyaltyPointsPlugin } from '@acme/vendure-plugin-loyalty-points';

// ...
plugins: [
  AdminUiPlugin.init({
    route: 'admin',
    port: 3002,
    app: compileUiExtensions({
      outputPath: path.join(__dirname, '../admin-ui'),
      extensions: [LoyaltyPointsPlugin.uiExtensions],
      devMode: false,
    })
  }),
],
```
[/If your plugin includes UI extensions]

## Usage

Describe how to use your plugin here. Make sure to cover the key
functionality and any configuration options. Include examples
where possible.

Make sure to document any extensions made to the GraphQL APIs,
as well as how to integrate the plugin with a storefront app.
````

</div>

#### JS Docs

All publicly-exposed services, entities, strategies, interfaces etc should be documented using JSDoc comments.
Not only does this improve the developer experience for your users, but it also allows Vendure Hub to auto-generate
documentation pages for your plugin.

Here are some examples of well-documented plugin code (implementation details omitted for brevity):

<Tabs>
<TabItem value="plugin" label="Plugin">

- Tag the plugin with `@category Plugin`. This will be used when generating the docs pages to group plugins together.
- Usually the `.init()` method is the thing that users will call to configure the plugin. Document this method with an example of how to use it.
- The constructor and any lifecycle methods should be tagged with `@internal`.

<div class="limited-height-code-block">

```ts
/**
 * Advanced search and search analytics for Vendure.
 *
 * @category Plugin
 */
@VendurePlugin({
    imports: [PluginCommonModule],
    // ...
})
export class LoyaltyPointsPlugin implements OnApplicationBootstrap {
    /** @internal */
    static options: LoyaltyPointsPluginInitOptions;

    /**
     * The static `init()` method is called with the options to
     * configure the plugin.
     *
     * @example
     * ```ts
     * LoyaltyPointsPlugin.init({
     *     enablePartialRedemption: true
     * }),
     * ```
     */
    static init(options: LoyaltyPointsPluginInitOptions) {
        this.options = options;
        return AdvancedSearchPlugin;
    }

    /**
     * The static `uiExtensions` property is used to provide the
     * necessary UI extensions to the Admin UI
     * in order to display the loyalty points admin features.
     * This property is used in the `AdminUiPlugin` initialization.
     *
     * @example
     * ```ts
     * import { compileUiExtensions } from '@vendure/ui-devkit/compiler';
     * import { AdvancedSearchPlugin } from '@acme/vendure-plugin-loyalty-points';
     *
     * // ...
     * plugins: [
     *   AdminUiPlugin.init({
     *     route: 'admin',
     *     port: 3002,
     *     app: compileUiExtensions({
     *       outputPath: path.join(__dirname, '../admin-ui'),
     *       extensions: [LoyaltyPointsPlugin.uiExtensions],
     *       devMode: false,
     *     })
     *   }),
     * ],
     * ```
     */
    static uiExtensions = advancedSearchPluginUi;

    /** @internal */
    constructor(/* ... */) {}

    /** @internal */
    async onApplicationBootstrap() {
        // Logic to set up event subscribers etc.
    }
}
```

</div>
</TabItem>
<TabItem value="plugin-options" label="Plugin options">
- Tag the options interface with `@category Plugin`.
- Document any default values for optional properties.

```ts
/**
 * Configuration options for the LoyaltyPointsPlugin.
 *
 * @category Plugin
 */
export interface LoyaltyPointsPluginInitOptions {
    /**
     * Whether to allow partial redemption of points.
     *
     * @default true
     */
    enablePartialRedemption?: boolean;
}
```

</TabItem>
<TabItem value="services" label="Services">

- Only services that are exported in the plugin's `exports` array need to be documented. Internal services can be left undocumented.
- Tag services with `@category Services`. This will be used when generating the docs pages to group services together.
- By default all non-private methods are included in the docs. If you want to exclude a method, tag it with `@internal`.

```ts
/**
 * The LoyaltyPointsService provides methods for managing a
 * customer's loyalty points balance.
 *
 * @category Services
 */
@Injectable()
export class LoyaltyPointsService {

    /** @internal */
    constructor(private connection: TransactionalConnection) {}

    /**
     * Adds the given number of points to the customer's balance.
     */
    addPoints(ctx: RequestContext, customerId: ID, points: number): Promise<LoyaltyPointsTransaction> {
        // implementation...
    }

    /**
     * Deducts the given number of points from the customer's balance.
     */
    deductPoints(customerId: ID, points: number): Promise<LoyaltyPointsTransaction> {
        // implementation...
    }
}
```

</TabItem>
<TabItem value="entities" label="Entities">

- Tag entities with `@category Entities`. This will be used when generating the docs pages to group entities together.

```ts
/**
 * Represents a transaction of loyalty points,
 * when points are added or deducted.
 *
 * @category Entities
 */
@Entity()
export class LoyaltyPointsTransaction extends VendureEntity {

    /**
     * The number of points added or deducted.
     * A negative value indicates points deducted.
     */
    @Column()
    points: number;

    /**
     * The Customer to whom the points were added or deducted.
     */
    @ManyToOne(type => Customer)
    customer: Customer;

    /**
     * The reason for the points transaction.
     */
    @Column()
    reason: string;
}
```

</TabItem>
<TabItem value="events" label="Events">

- Tag events with `@category Events`. This will be used when generating the docs pages to group events together.

```ts
/**
 * This event is fired whenever a LoyaltyPointsTransaction is created.
 *
 * @category Events
 */
export class LoyaltyPointsTransactionEvent extends VendureEvent {
    constructor(public ctx: RequestContext, public transaction: LoyaltyPointsTransaction) {
        super();
    }
}
```

</TabItem>
</Tabs>

### Tests

Testing is an important part of ensuring the quality of your plugin, as well as preventing regressions when you make
changes.

For plugins of any complexity, you should aim to have a suite of end-to-end tests as covered in the [testing docs](/guides/developer-guide/testing/).

In future we may use the test results to help determine the quality of a plugin.

## Submitting to Vendure Hub

Once your plugin is published to npm and satisfies the requirements above, you can submit it to Vendure Hub
via our [contact form](https://vendure.io/contact?interested_in=publish_paid_plugins), making sure to include
a link to the npm package and the GitHub repository.

## Publishing a paid plugin

Vendure Hub supports the listing of paid plugins. If you would like to sell plugins through Vendure Hub,
    please [contact us](https://vendure.io/contact?interested_in=publish_paid_plugins) and provide
details about the plugins you would like to sell.




---

---
title: "Integrating S3-Compatible Asset Storage"
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

This guide demonstrates how to integrate S3-compatible asset storage into your Vendure application using multiple cloud storage platforms. You'll learn to configure a single, platform-agnostic storage solution that works seamlessly with AWS S3, DigitalOcean Spaces, MinIO, CloudFlare R2, and Supabase Storage.

## Working Example Repository

:::info
This guide is based on the [s3-file-storage](https://github.com/vendure-ecommerce/examples/tree/master/examples/s3-file-storage) example.
Refer to the complete working code for full implementation details.
:::

## Prerequisites

- Node.js 20+ with npm package manager
- An existing Vendure project created with the [Vendure create command](http://localhost:3001/guides/getting-started/installation/)
- An account with one of the supported S3-compatible storage providers

## S3-Compatible Storage Provider Setup

Configure your chosen storage provider by following the setup instructions for your preferred platform:

<Tabs>
<TabItem value="aws-s3" label="AWS S3">

### Setting up AWS S3

1. **Create an S3 Bucket**
   - Navigate to [AWS S3 Console](https://console.aws.amazon.com/s3/)
   - Click "Create bucket"
   - Enter a unique bucket name (e.g., `my-vendure-assets`)
   - Choose your preferred AWS region
   - Configure permissions as needed for public asset access

2. **Create IAM User with S3 Permissions**
   - Go to [AWS IAM Console](https://console.aws.amazon.com/iam/)
   - Navigate to "Users" and click "Create user"
   - Enter username and proceeed to `Set Permissions`
   - Select the `Attach existing policies directly` option
   - Attach the `AmazonS3FullAccess` policy (or create a custom policy with minimal permissions)

3. **Generate Access Keys**
   - After creating the user, click on the user name
   - Go to "Security credentials" tab
   - Click "Create access key" and select "Application running on AWS service"
   - Copy the Access Key ID and Secret Access Key (Download the CSV file if needed)

4. **Environment Variables**

   ```bash
   # AWS S3 Configuration
   S3_BUCKET=my-vendure-assets
   S3_ACCESS_KEY_ID=AKIA...
   S3_SECRET_ACCESS_KEY=wJalrXUtn...
   S3_REGION=us-east-1
   # Leave S3_ENDPOINT empty for AWS S3
   # Leave S3_FORCE_PATH_STYLE empty for AWS S3
   ```

   ![AWS S3 Setup](https://cdn.vendure.io/learn/s3-guides/aws-bucket-iam.gif)

</TabItem>
<TabItem value="supabase" label="Supabase Storage">

### Setting up Supabase S3 Storage

1. **Create Supabase Project**
   - Sign up at [Supabase](https://supabase.com/)
   - Click "New project" and fill in project details
   - Wait for project initialization to complete

2. **Navigate to Storage**
   - Go to "Storage" section in your project dashboard
   - Click "Create a new bucket"
   - Enter bucket name: `assets` (or your preferred name)
   - Configure bucket to be public if you need direct asset access
   - Click "Create bucket"

3. **Generate Service Role Key**
   - Navigate to "Settings" → "API"
   - Copy your **Project URL** and **Project Reference ID**
   - Copy the **service_role** key (keep this secure)
   - The service_role key provides full access to your project

4. **Environment Variables**

   ```bash
   # Supabase Storage Configuration
   S3_BUCKET=assets
   S3_ACCESS_KEY_ID=your-supabase-access-key-id
   S3_SECRET_ACCESS_KEY=your-service-role-key
   S3_REGION=us-east-1
   S3_ENDPOINT=https://your-project-ref.supabase.co/storage/v1/s3
   S3_FORCE_PATH_STYLE=true
   ```

   :::info
   Replace `your-project-ref` with your actual Supabase project reference ID found in your project settings.
   :::

   ![Supabase Storage Setup](https://cdn.vendure.io/learn/s3-guides/Supabase-create-bucket.gif)

</TabItem>
<TabItem value="digitalocean" label="DigitalOcean Spaces">

### Setting up DigitalOcean Spaces

1. **Create a DigitalOcean Account**
   - Sign up at [DigitalOcean](https://www.digitalocean.com/)
   - Navigate to the Spaces section in your dashboard

2. **Create a Space**
   - Click "Create a Space"
   - Choose your datacenter region (e.g., `fra1` for Frankfurt)
   - Enter a unique Space name (e.g., `my-vendure-assets`)
   - Choose File Listing permissions based on your needs
   - Optionally enable CDN to improve global asset delivery

3. **Generate Spaces Access Keys**
   - Go to [API Tokens page](https://cloud.digitalocean.com/account/api/tokens)
   - Click "Generate New Key" in the Spaces Keys section
   - Enter a name for your key
   - Copy the generated Key and Secret

4. **Configure CORS Policy (Optional)**
   For browser-based uploads, configure CORS in your Space settings:

   ```json
   [
     {
       "allowed_origins": ["https://yourdomain.com"],
       "allowed_methods": ["GET", "POST", "PUT"],
       "allowed_headers": ["*"],
       "max_age": 3000
     }
   ]
   ```

5. **Environment Variables**

   ```bash
   # DigitalOcean Spaces Configuration
   S3_BUCKET=my-vendure-assets
   S3_ACCESS_KEY_ID=DO00...
   S3_SECRET_ACCESS_KEY=wJalrXUtn...
   S3_REGION=fra1
   S3_ENDPOINT=https://fra1.digitaloceanspaces.com
   S3_FORCE_PATH_STYLE=false
   ```

   :::tip
   Use the regional endpoint (e.g., `https://fra1.digitaloceanspaces.com`) not the CDN endpoint. The AWS SDK constructs URLs automatically.
   :::

   ![DigitalOcean Spaces Setup](https://cdn.vendure.io/learn/s3-guides/digital-ocean-create-bucket.gif)

</TabItem>
<TabItem value="cloudflare-r2" label="CloudFlare R2">

### Setting up CloudFlare R2

1. **Create CloudFlare Account**
   - Sign up at [CloudFlare](https://www.cloudflare.com/)
   - Complete account verification process

2. **Enable R2 Object Storage**
   - Navigate to R2 Object Storage in your dashboard
   - You may need to provide payment information (R2 has generous free tier)
   - Accept the R2 terms of service

3. **Create R2 Bucket**
   - Click "Create bucket"
   - Enter a globally unique bucket name: `vendure-assets`
   - Select "Automatic" for location optimization
   - Choose "Standard" storage class for most use cases
   - Click "Create bucket" to finalize

4. **Generate API Tokens**
   - Go to "Manage R2 API tokens" section
   - Click "Create API token"
   - Configure token name: "Vendure R2 Token"
   - Under Permissions, select "Object Read & Write"
   - Optionally restrict to specific buckets under "Account resources"
   - Click "Create API token"

5. **Retrieve Credentials**
   - Copy the **Access Key ID** and **Secret Access Key**
   - Copy the **jurisdiction-specific endpoint** for S3 clients
   - Note your **account ID** from the URL or dashboard

6. **Environment Variables**

   ```bash
   # CloudFlare R2 Configuration
   S3_BUCKET=vendure-assets
   S3_ACCESS_KEY_ID=your-r2-access-key
   S3_SECRET_ACCESS_KEY=your-r2-secret-key
   S3_REGION=auto
   S3_ENDPOINT=https://your-account-id.r2.cloudflarestorage.com
   S3_FORCE_PATH_STYLE=true
   ```

   :::warning
   Replace `your-account-id` with your actual CloudFlare account ID. If using a custom domain, update `S3_FILE_URL` to point to your custom domain with `https://`.
   :::

   ![CloudFlare R2 Setup](https://cdn.vendure.io/learn/s3-guides/cloudflareR2-bucket.gif)

</TabItem>
<TabItem value="hetzner" label="Hetzner Object Storage">

### Setting up Hetzner Object Storage

1. **Create Hetzner Cloud Account**
   - Sign up at [Hetzner Cloud](https://www.hetzner.com/cloud)
   - Complete account verification and billing setup
   - Navigate to the Hetzner Cloud Console

2. **Access Object Storage Service**
   - In the Hetzner Cloud Console, navigate to **"Object Storage"** in the left sidebar
   - If Object Storage is not visible, you may need to request access (service availability varies by region)
   - Accept the Object Storage terms of service when prompted

3. **Create Storage Bucket**
   - Click **"Create Bucket"** in the Object Storage section
   - Enter a globally unique bucket name (e.g., `vendure-assets-yourname`)
   - Select your preferred location (e.g., `fsn1` for Falkenstein, Germany)
   - Choose bucket visibility:
     - **Private**: Requires authentication for all access
     - **Public**: Allows public read access for assets
   - Click **"Create"** to create the bucket

4. **Generate S3 API Credentials**
   - In the Object Storage section, navigate to **"API Credentials"** or **"Access Keys"**
   - Click **"Generate new credentials"** or **"Create access key"**
   - Provide a name for the credentials (e.g., "Vendure API Key")
   - Copy the generated **Access Key** and **Secret Key**
   - ⚠️ **Important**: Save the Secret Key immediately as it cannot be viewed again

5. **Environment Variables**

   ```bash
   # Hetzner Object Storage Configuration
   S3_BUCKET=vendure-assets-yourname
   S3_ACCESS_KEY_ID=your-hetzner-access-key
   S3_SECRET_ACCESS_KEY=your-hetzner-secret-key
   S3_REGION=fsn1
   S3_ENDPOINT=https://fsn1.your-objectstorage.com
   S3_FORCE_PATH_STYLE=true
   ```

   :::note
   Replace `fsn1` with your chosen location (e.g., `nbg1` for Nuremberg). The endpoint URL will match your bucket's location. Ensure the region and endpoint location match.
   :::

   ![Hetzner Object Storage Setup](https://cdn.vendure.io/learn/s3-guides/hetzner-create-storage.gif)

</TabItem>
<TabItem value="minio" label="MinIO">

### Setting up MinIO (Self-Hosted)

1. **Install MinIO Server**

   **Option A: Using Docker (Recommended)**
   ```bash
   # Create a docker-compose.yml file
   docker compose up -d minio
   ```

   **Option B: Direct Installation**
   - Download MinIO from [MinIO Downloads](https://min.io/download)
   - Follow installation instructions for your operating system
   - Start MinIO server with: `minio server /data --console-address ":9001"`

2. **Access MinIO Console**
   - Open [http://localhost:9001](http://localhost:9001) in your browser
   - Default credentials: `minioadmin` / `minioadmin`
   - Change these credentials in production environments

3. **Create Access Keys**

   The MinIO web console in development setups typically only shows bucket management. For access key creation, use the MinIO CLI:

   **Install MinIO Client (if not already installed):**
   ```bash
   # macOS
   brew install minio/stable/mc

   # Linux
   curl https://dl.min.io/client/mc/release/linux-amd64/mc \
     --create-dirs -o $HOME/minio-binaries/mc
   chmod +x $HOME/minio-binaries/mc
   export PATH=$PATH:$HOME/minio-binaries/

   # Windows
   # Download mc.exe from https://dl.min.io/client/mc/release/windows-amd64/mc.exe
   ```

   **Configure and create access keys:**
   ```bash
   # Set up MinIO client alias (replace with your MinIO server details)
   mc alias set local http://localhost:9000 minioadmin minioadmin

   # Create a service account (access key pair)
   mc admin user svcacct add local minioadmin

   # This will output something like:
   # Access Key: AKIAIOSFODNN7EXAMPLE
   # Secret Key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
   ```

   ⚠️ **Important**: Save both keys immediately as the Secret Key won't be shown again

4. **Create Storage Bucket**
   - In the MinIO console, you should see a "Buckets" section showing available buckets
   - Click **"Create Bucket"** (usually a + icon or button)
   - Enter bucket name: `vendure-assets`
   - Click "Create" to create the bucket

   **Alternative using CLI:**
   ```bash
   # Create bucket using MinIO client
   mc mb local/vendure-assets
   ```

5. **Configure Public Access Policy**

   For public asset access, set the bucket policy using the MinIO CLI (console UI may not have policy editor):

   ```bash
   # Create a policy file for public read access
   cat > public-read-policy.json << EOF
   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Principal": "*",
         "Action": "s3:GetObject",
         "Resource": "arn:aws:s3:::vendure-assets/*"
       }
     ]
   }
   EOF

   # Apply the policy to the bucket
   mc anonymous set download local/vendure-assets

   # Or apply the JSON policy directly
   mc admin policy create local public-read public-read-policy.json
   ```

   **Alternative simple approach:**
   ```bash
   # Make bucket publicly readable (simpler method)
   mc anonymous set download local/vendure-assets
   ```

6. **Environment Variables**

   ```bash
   # MinIO Configuration
   S3_BUCKET=vendure-assets
   S3_ACCESS_KEY_ID=minio-access-key
   S3_SECRET_ACCESS_KEY=minio-secret-key
   S3_REGION=us-east-1
   S3_ENDPOINT=http://localhost:9000
   S3_FORCE_PATH_STYLE=true
   ```

</TabItem>
</Tabs>

## Vendure Configuration

Configure your Vendure application to use S3-compatible asset storage by modifying your `vendure-config.ts`:

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';
// highlight-start
import {
  AssetServerPlugin,
  configureS3AssetStorage
} from '@vendure/asset-server-plugin';
// highlight-end
import 'dotenv/config';
import path from 'path';

const IS_DEV = process.env.APP_ENV === 'dev';

export const config: VendureConfig = {
  // ... other configuration options

  plugins: [
    // highlight-start
    AssetServerPlugin.init({
      route: 'assets',
      assetUploadDir: path.join(__dirname, '../static/assets'),
      assetUrlPrefix: IS_DEV ? undefined : 'https://www.my-shop.com/assets/',

      // S3-Compatible Storage Configuration
      // Dynamically switches between local storage and S3 based on environment
      storageStrategyFactory: process.env.S3_BUCKET
        ? configureS3AssetStorage({
            bucket: process.env.S3_BUCKET,
            credentials: {
              accessKeyId: process.env.S3_ACCESS_KEY_ID!,
              secretAccessKey: process.env.S3_SECRET_ACCESS_KEY!,
            },
            nativeS3Configuration: {
              // Platform-specific endpoint configuration
              endpoint: process.env.S3_ENDPOINT,
              region: process.env.S3_REGION,
              forcePathStyle: process.env.S3_FORCE_PATH_STYLE === 'true',
              signatureVersion: 'v4',
            },
          })
        : undefined, // Fallback to local storage when S3 not configured
    }),
    // highlight-end

    // ... other plugins
  ],
};
```

:::note
**IMPORTANT**: The configuration uses a conditional approach - when `S3_BUCKET` is set, it activates S3 storage; otherwise, it falls back to local file storage. This enables seamless development-to-production transitions.
:::

## Environment Configuration

Create a `.env` file in your project root with your chosen storage provider configuration:

```bash title=".env"
# Basic Vendure Configuration
APP_ENV=dev
SUPERADMIN_USERNAME=superadmin
SUPERADMIN_PASSWORD=superadmin
COOKIE_SECRET=your-cookie-secret-32-characters-min

# S3-Compatible Storage Configuration
S3_BUCKET=your-bucket-name
S3_ACCESS_KEY_ID=your-access-key-id
S3_SECRET_ACCESS_KEY=your-secret-access-key
S3_REGION=your-region
S3_ENDPOINT=your-endpoint-url
S3_FORCE_PATH_STYLE=true-or-false
```

:::cli
Preconfigured environment examples for each storage provider are available in the [s3-file-storage example repository](https://github.com/vendure-ecommerce/examples/tree/master/examples/s3-file-storage).
:::

## Testing Your Configuration

Verify your S3 storage configuration works correctly:

1. **Start your Vendure server**:
   ```bash
   npm run dev:server
   ```

2. **Access the Admin UI**:
   - Open [http://localhost:3000/admin](http://localhost:3000/admin)
   - Log in with your superadmin credentials

3. **Test asset upload**:
   - Navigate to "Catalog" → "Assets"
   - Click "Upload assets"
   - Select a test image and upload
   - Verify the image appears in the asset gallery

4. **Verify storage backend**:
   - Check your S3 bucket/storage service for the uploaded file
   - Confirm the asset URL is accessible


## Advanced Configuration

### Custom Asset URL Prefix

For production deployments with CDN or custom domains:

```ts title="src/vendure-config.ts"
AssetServerPlugin.init({
  route: 'assets',
  // highlight-next-line
  assetUrlPrefix: 'https://cdn.yourdomain.com/assets/',
  storageStrategyFactory: process.env.S3_BUCKET
    ? configureS3AssetStorage({
        // ... S3 configuration
      })
    : undefined,
});
```

### Environment-Specific Configuration

Use different buckets for different environments:

```bash
# Development
S3_BUCKET=vendure-dev-assets

# Staging
S3_BUCKET=vendure-staging-assets

# Production
S3_BUCKET=vendure-prod-assets
```

### Migration Between Platforms

Switching between storage providers requires updating only the environment variables:

```bash
# From AWS S3 to CloudFlare R2
# Change these variables:
S3_ENDPOINT=https://account-id.r2.cloudflarestorage.com
S3_FORCE_PATH_STYLE=true
# Keep the same bucket name and credentials structure
```

## Troubleshooting

### Common Issues

1. **"Access Denied" Errors**:
   - Verify your access key has proper permissions
   - Check bucket policies allow the required operations
   - Ensure credentials are correctly set in environment variables

2. **"Bucket Not Found" Errors**:
   - Verify bucket name matches exactly (case-sensitive)
   - Check that `S3_REGION` matches your bucket's region
   - For MinIO/R2, ensure `S3_FORCE_PATH_STYLE=true`

3. **Assets Not Loading**:
   - Verify bucket has public read access (if needed)
   - Check CORS configuration for browser-based access
   - Ensure `assetUrlPrefix` matches your actual domain

4. **Connection Timeout Issues**:
   - Verify `S3_ENDPOINT` URL is correct and accessible
   - Check firewall settings for outbound connections
   - For self-hosted MinIO, ensure server is running and accessible


## Conclusion

You now have a robust, platform-agnostic S3-compatible asset storage solution integrated with your Vendure application. This configuration provides:

- **Seamless switching** between storage providers via environment variables
- **Development-to-production** workflow with local storage fallback
- **Built-in compatibility** with major S3-compatible services
- **Production-ready** configuration patterns

The unified approach eliminates the need for custom storage plugins while maintaining flexibility across different cloud storage platforms. Your assets will be reliably stored and served regardless of which S3-compatible provider you choose.

## Next Steps

- Set up CDN integration for improved global asset delivery
- Implement backup strategies for critical assets
- Configure monitoring and alerting for storage operations
- Consider implementing asset optimization and transformation workflows


---

---
title: "Open Telemetry"
---

[Open Telemetry](https://opentelemetry.io/) is a set of APIs, libraries, agents, and instrumentation to provide observability for applications. 
It provides a standard way to collect and export telemetry data such as traces, metrics, and logs from applications.

From Vendure v3.3, Vendure has built-in support for Open Telemetry, via the `@vendure/telemetry-plugin` package. 
This package provides a set of decorators and utilities to instrument Vendure services and entities with Open Telemetry.

In this guide we will set up a local Vendure server with Open Telemetry, collecting traces and logs
using the following parts:

- [Open Telemetry](https://opentelemetry.io/): The standard for observability.
- [Vendure Telemetry Plugin](/reference/core-plugins/telemetry-plugin/): Instruments the Vendure server & worker for Open Telemetry.
- [Jaeger](https://www.jaegertracing.io/): A distributed tracing system that can be used to collect and visualize traces.
- [Loki](https://grafana.com/oss/loki/): A log aggregation system that can be used to collect and visualize logs.
- [Grafana](https://grafana.com/oss/grafana/): A visualization tool that can be used to visualize traces and logs from Jaeger and Loki.

:::info
There are many other tools and services that can be used with Open Telemetry, such as Prometheus, Zipkin, Sentry, Dynatrace and others.

In this guide we have chosen some widely-used and open-source tools to demonstrate the capabilities of Open Telemetry.
:::

## Setup

### Set up Jaeger, Loki & Grafana

We will be using Docker to run Jaeger, Loki, and Grafana locally. Create a file called `docker-compose.yml` 
in the root of your project (standard Vendure installations already have one) and add the following contents:

```yaml
services:
    jaeger:
        image: jaegertracing/all-in-one:latest
        ports:
            - '4318:4318' # OTLP HTTP receiver
            - '16686:16686' # Web UI
        environment:
            - COLLECTOR_OTLP_ENABLED=true
        volumes:
            - jaeger_data:/badger
        networks:
            - jaeger

    loki:
        image: grafana/loki:3.4
        ports:
            - '3100:3100'
        networks:
            - loki

    grafana:
        environment:
            - GF_PATHS_PROVISIONING=/etc/grafana/provisioning
            - GF_AUTH_ANONYMOUS_ENABLED=true
            - GF_AUTH_ANONYMOUS_ORG_ROLE=Admin
            - GF_FEATURE_TOGGLES_ENABLE=alertingSimplifiedRouting,alertingQueryAndExpressionsStepMode
        image: grafana/grafana:latest
        ports:
            - '3200:3000'
        networks:
            - loki
            - jaeger
        volumes:
            - grafana-storage:/var/lib/grafana

    networks:
        loki:
            driver: bridge
        jaeger:
            driver: bridge

    volumes:
        jaeger_data:
            driver: local
        grafana-storage:
            driver: local
```

You can start the services using the following command:

```bash
docker-compose up -d jaeger loki grafana
```

Once the images have downloaded and the containers are running, you can access:

- Jaeger at [http://localhost:16686](http://localhost:16686)
- Grafana at [http://localhost:3200](http://localhost:3200)

### Install the Telemetry Plugin

```bash
npm install @vendure/telemetry-plugin
```

Add the plugin to your Vendure config:

```ts
import { VendureConfig, LogLevel } from '@vendure/core';
import { TelemetryPlugin } from '@vendure/telemetry-plugin';

export const config: VendureConfig = {
    // ... other config options
    plugins: [
        TelemetryPlugin.init({
            loggerOptions: {
                // Optional: log to the console as well as
                // sending to the telemetry server. Can be
                // useful for debugging.
                logToConsole: LogLevel.Verbose,
            },
        }),
    ],
};
```

### Set environment variables

In order to send telemetry data to the Jaeger and Loki services, you need to set some environment variables.
In a standard Vendure installation, there is an `.env` file in the root of the project. We will add the following:

```env
# Open Telemetry
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:3100/otlp
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4318/v1/traces
OTEL_LOGS_EXPORTER=otlp
```

### Create a preload script

The Open Telemetry libraries for Node.js instrument underlying libraries such as NestJS, GraphQL,
Redis, database drivers, etc. to collect telemetry data. In order to do this, they need to be
preloaded before any of the Vendure application code. This is done by means of a preload script.

Create a file called `preload.ts` in the src dir of your project with the following contents:

```ts title="src/preload.ts"
import { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-proto';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { BatchLogRecordProcessor } from '@opentelemetry/sdk-logs';
import { NodeSDK } from '@opentelemetry/sdk-node';
import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
import { getSdkConfiguration } from '@vendure/telemetry-plugin/preload';
import 'dotenv/config';

const traceExporter = new OTLPTraceExporter();
const logExporter = new OTLPLogExporter();

const config = getSdkConfiguration({
    config: {
        spanProcessors: [new BatchSpanProcessor(traceExporter)],
        logRecordProcessors: [new BatchLogRecordProcessor(logExporter)],
    },
});

const sdk = new NodeSDK(config);

sdk.start();
```

:::info
There are many, many configuration options available for Open Telemetry. The above is an example that works
with the services used in this guide. The important things is to make sure the use the
`getSdkConfiguration` function from the `@vendure/telemetry-plugin/preload` package, as this will ensure that
the Vendure core is instrumented correctly.
:::

To run the preload script, you need to set the `--require` flag when starting the Vendure server. We will 
also set an environment variable to distinguish the server from the worker process.

You can do this by adding the following script to your `package.json`:

```json
{
    "scripts": {
        // highlight-start
        "dev:server": "OTEL_RESOURCE_ATTRIBUTES=service.name=vendure-server ts-node --require ./src/preload.ts ./src/index.ts",
        "dev:worker": "OTEL_RESOURCE_ATTRIBUTES=service.name=vendure-worker ts-node --require ./src/preload.ts ./src/index-worker.ts",
        // highlight-end
        "dev": "concurrently npm:dev:*",
        "build": "tsc",
        // highlight-start
        "start:server": "OTEL_RESOURCE_ATTRIBUTES=service.name=vendure-server node --require ./dist/preload.js ./dist/index.js",
        "start:worker": "OTEL_RESOURCE_ATTRIBUTES=service.name=vendure-worker node --require ./dist/preload.js ./dist/index-worker.js",
        // highlight-end
        "start": "concurrently npm:start:*"
    },
}
```

## Viewing Logs

Once you have started up your server with the preload script, Loki should start receiving logs.

Let's take a look at the logs in Grafana.

Open the Grafana dashboard at [http://localhost:3200](http://localhost:3200) and
select **Connections** > **Data Sources** from the left-hand menu. Then click the "Add data source" button.

Find "Loki" and select it. In the config form that opens, set the URL to `http://loki:3100` and click "Save & Test".

Now you can select **Drilldown** > **Logs** from the left-hand menu. In the "Data source" dropdown, select "Loki".

![Grafana logs](./grafana-logs.webp)

## Viewing Traces

You can view traces in Jaeger by going to [http://localhost:16686](http://localhost:16686).

Select the "vendure-dev-server" service from the dropdown and click "Find Traces".

Clicking a trace will show you the details of the trace.

![Jaeger traces](./jaeger-trace.webp)

You can also view traces in Grafana by connecting it to Jaeger.

To do this, go to the Grafana dashboard at [http://localhost:3200](http://localhost:3200) and
select **Connections** > **Data Sources** from the left-hand menu. Then click the "Add data source" button.

Find "Jaeger" and select it. In the config form that opens, set the URL to `http://jaeger:16686` and click "Save & Test".

Now you can select **Explore** from the left-hand menu, select "Jaeger" from the dropdown and then click the 
"search" tab and select the "vendure-dev-server" service from the dropdown.

Clicking the blue "Run Query" button will show you the traces for that service.

![Grafana traces](./grafana-trace.webp)

## Instrumenting Your Plugins

You can also instrument your own plugins and services with Open Telemetry. To do so,
add the [Instrument decorator](/reference/typescript-api/telemetry/instrument) to your service class:

```ts
import { Injectable } from '@nestjs/common';
// highlight-next-line
import { Instrument } from '@vendure/core';

// highlight-next-line
@Instrument()
@Injectable()
export class MyService {

    async myMethod() {
        // ...
    }
}
```

You should now be able to see calls to `MyService.myMethod` in your traces.


---

---
title: "Managing the Active Order"
---

import Stackblitz from '@site/src/components/Stackblitz';

The "active order" is what is also known as the "cart" - it is the order that is currently being worked on by the customer.

An order remains active until it is completed, and during this time it can be modified by the customer in various ways:

- Adding an item
- Removing an item
- Changing the quantity of items
- Applying a coupon
- Removing a coupon

This guide will cover how to manage the active order.

## Define an Order fragment

Since all the mutations that we will be using in this guide require an `Order` object, we will define a fragment that we can
reuse in all of our mutations.

```ts title="src/fragments.ts"
const ACTIVE_ORDER_FRAGMENT = /*GraphQL*/`
fragment ActiveOrder on Order {
  __typename
  id
  code
  couponCodes
  state
  currencyCode
  totalQuantity
  subTotalWithTax
  shippingWithTax
  totalWithTax
  discounts {
    description
    amountWithTax
  }
  lines {
    id
    unitPriceWithTax
    quantity
    linePriceWithTax
    productVariant {
      id
      name
      sku
    }
    featuredAsset {
      id
      preview
    }
  }
  shippingLines {
    shippingMethod {
      description
    }
    priceWithTax
  }
}`
```

:::note
The `__typename` field is used to determine the type of the object returned by the GraphQL server. In this case, it will always be `'Order'`.

Some GraphQL clients such as Apollo Client will automatically add the `__typename` field to all queries and mutations, but if you are using a different client you may need to add it manually.
:::

This fragment can then be used in subsequent queries and mutations by using the `...` spread operator in the place where an `Order` object is expected.
You can then embed the fragment in the query or mutation by using the `${ACTIVE_ORDER_FRAGMENT}` syntax:

```ts title="src/queries.ts"
import { ACTIVE_ORDER_FRAGMENT } from './fragments';

export const GET_ACTIVE_ORDER = /*GraphQL*/`
  query GetActiveOrder {
    activeOrder {
      // highlight-next-line
      ...ActiveOrder
    }
  }
  // highlight-next-line
  ${ACTIVE_ORDER_FRAGMENT}
`;
```

For the remainder of this guide, we will list just the body of the query or mutation, and assume that the fragment is defined and imported as above.

## Get the active order

This fragment can then be used in subsequent queries and mutations. Let's start with a query to get the active order using the [`activeOrder` query](/reference/graphql-api/shop/queries#activeorder):

```graphql
query GetActiveOrder {
  activeOrder {
    ...ActiveOrder
  }
}
```

## Add an item

To add an item to the active order, we use the [`addItemToOrder` mutation](/reference/graphql-api/shop/mutations/#additemtoorder), as we have seen in the [Product Detail Page guide](/guides/storefront/product-detail/).

```graphql
mutation AddItemToOrder($productVariantId: ID!, $quantity: Int!) {
  addItemToOrder(productVariantId: $productVariantId, quantity: $quantity) {
    ...ActiveOrder
    ... on ErrorResult {
      errorCode
      message
    }
    ... on InsufficientStockError {
      quantityAvailable
      order {
        ...ActiveOrder
      }
    }
  }
}
```

:::info
If you have defined any custom fields on the `OrderLine` entity, you will be able to pass them as a `customFields` argument to the `addItemToOrder` mutation.
See the [Configurable Products guide](/guides/how-to/configurable-products/) for more information.
:::

## Remove an item

To remove an item from the active order, we use the [`removeOrderLine` mutation](/reference/graphql-api/shop/mutations/#removeorderline),
and pass the `id` of the `OrderLine` to remove.

```graphql
mutation RemoveItemFromOrder($orderLineId: ID!) {
  removeOrderLine(orderLineId: $orderLineId) {
    ...ActiveOrder
    ... on ErrorResult {
      errorCode
      message
    }
  }
}
```

## Change the quantity of an item

To change the quantity of an item in the active order, we use the [`adjustOrderLine` mutation](/reference/graphql-api/shop/mutations/#adjustorderline).

```graphql
mutation AdjustOrderLine($orderLineId: ID!, $quantity: Int!) {
  adjustOrderLine(orderLineId: $orderLineId, quantity: $quantity) {
    ...ActiveOrder
    ... on ErrorResult {
        errorCode
        message
    }
  }
}
```

:::info
If you have defined any custom fields on the `OrderLine` entity, you will be able to update their values by passing a `customFields` argument to the `adjustOrderLine` mutation.
See the [Configurable Products guide](/guides/how-to/configurable-products/) for more information.
:::

## Applying a coupon code

If you have defined any [Promotions](/guides/core-concepts/promotions/) which use coupon codes, you can apply the a coupon code to the active order
using the [`applyCouponCode` mutation](/reference/graphql-api/shop/mutations/#applycouponcode).

```graphql
mutation ApplyCouponCode($couponCode: String!) {
  applyCouponCode(couponCode: $couponCode) {
    ...ActiveOrder
    ... on ErrorResult {
      errorCode
      message
    }
  }
}
```

## Removing a coupon code

To remove a coupon code from the active order, we use the [`removeCouponCode` mutation](/reference/graphql-api/shop/mutations/#removecouponcode).

```graphql
mutation RemoveCouponCode($couponCode: String!) {
  removeCouponCode(couponCode: $couponCode) {
    ...ActiveOrder
  }
}
```

## Live example

Here is a live example which demonstrates adding, updating and removing items from the active order:

<Stackblitz id='vendure-docs-active-order' />


---

---
title: "Checkout Flow"
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Once the customer has added the desired products to the active order, it's time to check out.

This guide assumes that you are using the [default OrderProcess](/guides/core-concepts/orders/#the-order-process), so
if you have defined a custom process, some of these steps may be slightly different.

:::note
In this guide, we will assume that an `ActiveOrder` fragment has been defined, as detailed in the
[Managing the Active Order guide](/guides/storefront/active-order/#define-an-order-fragment), but for the purposes of
checking out the fragment should also include `customer` `shippingAddress` and `billingAddress` fields.
:::

## Add a customer

Every order must be associated with a customer. If the customer is not logged in, then the [`setCustomerForOrder`](/reference/graphql-api/shop/mutations/#setcustomerfororder) mutation must be called. This will create a new Customer record if the provided email address does not already exist in the database.

:::note
If the customer is already logged in, then this step is skipped.
:::

<Tabs>
<TabItem value="Mutation" label="Mutation" default>

```graphql
mutation SetCustomerForOrder($input: CreateCustomerInput!) {
  setCustomerForOrder(input: $input) {
    ...ActiveOrder
    ...on ErrorResult {
      errorCode
      message
    }
  }
}
```

</TabItem>
<TabItem value="Variables" label="Variables">

```json
{
  "input": {
    "title": "Mr.",
    "firstName": "Bob",
    "lastName": "Dobalina",
    "phoneNumber": "1234556",
    "emailAddress": "b.dobalina@email.com",
  }
}
```

</TabItem>
</Tabs>

## Set the shipping address

The [`setOrderShippingAddress`](/reference/graphql-api/shop/mutations/#setordershippingaddress) mutation must be called to set the shipping address for the order.


<Tabs>
<TabItem value="Mutation" label="Mutation" default>

```graphql
mutation SetOrderShippingAddress($input: CreateAddressInput!) {
  setOrderShippingAddress(input: $input) {
    ...ActiveOrder
    ...on ErrorResult {
      errorCode
      message
    }
  }
}
```

</TabItem>
<TabItem value="Variables" label="Variables">

```json
{
  "input": {
    "fullName": "John Doe",
    "company": "ABC Inc.",
    "streetLine1": "123 Main St",
    "streetLine2": "Apt 4B",
    "city": "New York",
    "province": "NY",
    "postalCode": "10001",
    "countryCode": "US",
    "phoneNumber": "123-456-7890",
    "defaultShippingAddress": true,
    "defaultBillingAddress": false
  }
}
```

</TabItem>
</Tabs>

If the customer is logged in, you can check their existing addresses and pre-populate an address form if an existing address is found.


<Tabs>
<TabItem value="Query" label="Query" default>

```graphql
query GetCustomerAddresses {
  activeCustomer {
    id
    addresses {
      id
      fullName
      company
      streetLine1
      streetLine2
      city
      province
      postalCode
      country {
        code
        name
      }
      phoneNumber
      defaultShippingAddress
      defaultBillingAddress
    }
  }
}
```

</TabItem>
<TabItem value="Result" label="Result">

```json
{
  "data": {
    "activeCustomer": {
      "id": "123456",
      "addresses": [
        {
          "id": "123",
          "fullName": "John Doe",
          "company": "",
          "streetLine1": "123 Main St",
          "streetLine2": "Apt 4B",
          "city": "New York",
          "province": "NY",
          "postalCode": "10001",
          "country": {
            "code": "US",
            "name": "United States"
          },
          "phoneNumber": "123-456-7890",
          "defaultShippingAddress": true,
          "defaultBillingAddress": false
        },
        {
          "id": "124",
          "fullName": "John Doe",
          "company": "",
          "streetLine1": "456 Elm St",
          "streetLine2": "",
          "city": "Los Angeles",
          "province": "CA",
          "postalCode": "90001",
          "country": {
            "code": "US",
            "name": "United States"
          },
          "phoneNumber": "987-654-3210",
          "defaultShippingAddress": false,
          "defaultBillingAddress": true
        }
      ]
    }
  }
}
```

</TabItem>
</Tabs>

## Set the shipping method

Now that we know the shipping address, we can check which shipping methods are available with the [`eligibleShippingMethods`](/reference/graphql-api/shop/queries/#eligibleshippingmethods) query.

<Tabs>
<TabItem value="Query" label="Query" default>

```graphql
query GetShippingMethods {
  eligibleShippingMethods {
    id
    price
    description
  }
}
```

</TabItem>
<TabItem value="Result" label="Result">

```json
{
  "data": {
    "eligibleShippingMethods": [
      {
        "id": "1",
        "price": 545,
        "description": "Standard Shipping"
      },
      {
        "id": "2",
        "price": 1250,
        "description": "Expedited Shipping"
      },
      {
        "id": "3",
        "price": 1695,
        "description": "Overnight Shipping"
      }
    ]
  }
}
```

</TabItem>
</Tabs>

The results can then be displayed to the customer so they can choose the desired shipping method. If there is only a single
result, then it can be automatically selected.

The desired shipping method's id is then passed to the [`setOrderShippingMethod`](/reference/graphql-api/shop/mutations/#setordershippingmethod) mutation.

```graphql
mutation SetShippingMethod($id: [ID!]!) {
    setOrderShippingMethod(shippingMethodId: $id) {
        ...ActiveOrder
        ...on ErrorResult {
            errorCode
            message
        }
    }
}
```

## Add payment

The [`eligiblePaymentMethods`](/reference/graphql-api/shop/queries/#eligiblepaymentmethods) query can be used to get a list of available payment methods.
This list can then be displayed to the customer, so they can choose the desired payment method.


<Tabs>
<TabItem value="Query" label="Query" default>

```graphql
query GetPaymentMethods {
  eligiblePaymentMethods {
    id
    name
    code
    isEligible
  }
}
```

</TabItem>
<TabItem value="Result" label="Result">

```json
{
  "data": {
    "eligiblePaymentMethods": [
      {
        "id": "1",
        "name": "Stripe",
        "code": "stripe",
        "isEligible": true
      },
      {
        "id": "2",
        "name": "Apple Pay",
        "code": "apple-pay",
        "isEligible": true
      }
      {
        "id": "3",
        "name": "Pay on delivery",
        "code": "pay-on-delivery",
        "isEligible": false
      }
    ]
  }
}
```

</TabItem>
</Tabs>

Next, we need to transition the order to the `ArrangingPayment` state. This state ensures that no other changes can be made to the order
while the payment is being arranged. The [`transitionOrderToState`](/reference/graphql-api/shop/mutations/#transitionordertostate) mutation is used to transition the order to the `ArrangingPayment` state.

<Tabs>
<TabItem value="Query" label="Query" default>

```graphql
mutation TransitionToState($state: String!) {
  transitionOrderToState(state: $state) {
    ...ActiveOrder
    ...on OrderStateTransitionError {
      errorCode
      message
      transitionError
      fromState
      toState
    }
  }
}
```

</TabItem>
<TabItem value="Variables" label="Variables">

```json
{
  "state": "ArrangingPayment"
}
```

</TabItem>
</Tabs>

At this point, your storefront will use an integration with the payment provider to collect the customer's payment details, and then
the exact sequence of API calls will depend on the payment integration.

The [`addPaymentToOrder`](/reference/graphql-api/shop/mutations/#addpaymenttoorder) mutation is the general-purpose mutation for adding a payment to an order.
It accepts a `method` argument which must corresponde to the `code` of the selected payment method, and a `metadata` argument which is a JSON object containing any additional information required by that particular integration.

For example, the demo data populated in a new Vendure installation includes a "Standard Payment" method, which uses the [`dummyPaymentHandler`](/reference/typescript-api/payment/dummy-payment-handler) to simulate a payment provider. Here's how you would add a payment using this method:


<Tabs>
<TabItem value="Mutation" label="Mutation" default>

```graphql
mutation AddPaymentToOrder($input: PaymentInput!) {
  addPaymentToOrder(input: $input) {
    ...ActiveOrder
    ...on ErrorResult {
      errorCode
      message
    }
  }
}
```

</TabItem>
<TabItem value="Variables" label="Variables">

```json
{
  "method": "standard-payment",
  "metadata": {
    "shouldDecline": false,
    "shouldError": false,
    "shouldErrorOnSettle": false,
  }
}
```

</TabItem>
</Tabs>

Other payment integrations have specific setup instructions you must follow:

### Stripe

Our [`StripePlugin docs`](/reference/core-plugins/payments-plugin/stripe-plugin/) describe how to set up your checkout to use Stripe.

### Braintree

Our [`BraintreePlugin` docs](/reference/core-plugins/payments-plugin/braintree-plugin/) describe how to set up your checkout to use Braintree.

### Mollie

Our [`MolliePlugin` docs](/reference/core-plugins/payments-plugin/mollie-plugin/) describe how to set up your checkout to use Mollie.

### Other payment providers

For more information on how to integrate with a payment provider, see the [Payment](/guides/core-concepts/payment/) guide.

## Display confirmation

Once the checkout has completed, the order will no longer be considered "active" (see the [`OrderPlacedStrategy`](/reference/typescript-api/orders/order-placed-strategy/)) and so the [`activeOrder`](/reference/graphql-api/shop/queries/#activeorder) query will return `null`. Instead, the [`orderByCode`](/reference/graphql-api/shop/queries/#orderbycode) query can be used to retrieve the order by its code to display a confirmation page.

<Tabs>
<TabItem value="Query" label="Query" default>

```graphql
query GetOrderByCode($code: String!) {
  orderByCode(code: $code) {
    ...Order
  }
}
```

</TabItem>
<TabItem value="Variables" label="Variables">

```json
{
  "code": "PJGY46GCB1EDU9YH"
}
```

</TabItem>
</Tabs>

:::info
By default Vendure will only allow access to the order by code for the first 2 hours after the order is placed if the customer is not logged in.
This is to prevent a malicious user from guessing order codes and viewing other customers' orders. This can be configured via the [`OrderByCodeAccessStrategy`](/reference/typescript-api/orders/order-by-code-access-strategy/).
:::




---

---
title: "Storefront GraphQL Code Generation"
---

Code generation means the automatic generation of TypeScript types based on your GraphQL schema and your GraphQL operations.
This is a very powerful feature that allows you to write your code in a type-safe manner, without you needing to manually
write any types for your API calls.

To do this, we will use [Graphql Code Generator](https://the-guild.dev/graphql/codegen).

:::note
This guide is for adding codegen to your storefront. For a guide on adding codegen to your backend Vendure plugins or UI extensions, see the [Plugin Codegen](/guides/how-to/codegen/) guide.
:::

## Installation

Follow the installation instructions in the [GraphQL Code Generator Quick Start](https://the-guild.dev/graphql/codegen/docs/getting-started/installation).

Namely:

```bash
npm i graphql
npm i -D typescript @graphql-codegen/cli

npx graphql-code-generator init

npm install
```

During the `init` step, you'll be prompted to select various options about how to configure the code generation.

- Where is your schema?: Use `http://localhost:3000/shop-api` (unless you have configured a different GraphQL API URL)
- Where are your operations and fragments?: Use the appropriate glob pattern for you project. For example, `src/**/*.{ts,tsx}`.
- Select `codegen.ts` as the name of the config file.

## Configuration

The `init` step above will create a `codegen.ts` file in your project root. Add the highlighted lines:

```ts title="codegen.ts"

import type { CodegenConfig } from '@graphql-codegen/cli';

const config: CodegenConfig = {
  overwrite: true,
  schema: 'http://localhost:3000/shop-api',
  documents: 'src/**/*.graphql.ts',
  generates: {
    'src/gql/': {
      preset: 'client',
      plugins: [],
      // highlight-start
      config: {
        scalars: {
            // This tells codegen that the `Money` scalar is a number
            Money: 'number',
        },
        namingConvention: {
            // This ensures generated enums do not conflict with the built-in types.
            enumValues: 'keep',
        },
      }
      // highlight-end
    },
  }
};

export default config;
```

## Running Codegen

During the `init` step, you will have installed a `codegen` script in your `package.json`. You can run this script to
generate the TypeScript types for your GraphQL operations.

:::note
Ensure you have the Vendure server running before running the codegen script.
:::

```bash
npm run codegen
```

This will generate a `src/gql` directory containing the TypeScript types for your GraphQL operations.

## Use the `graphql()` function

If you have existing GraphQL queries and mutations in your application, you can now use the `graphql()` function
exported by the `src/gql/index.ts` file to execute them. If you were previously using the `gql` tagged template function,
replace it with the `graphql()` function.

```ts title="src/App.tsx"
import { useQuery } from '@tanstack/react-query';
import request from 'graphql-request'
// highlight-next-line
import { graphql } from './gql';

// highlight-start
// GET_PRODUCTS will be a `TypedDocumentNode` type,
// which encodes the types of the query variables and the response data.
const GET_PRODUCTS = graphql(`
// highlight-end
    query GetProducts($options: ProductListOptions) {
        products(options: $options) {
            items {
                id
                name
                slug
                featuredAsset {
                    preview
                }
            }
        }
    }
`);

export default function App() {
  // highlight-start
  // `data` will now be correctly typed
  const { isLoading, data } = useQuery({
  // highlight-end
    queryKey: ['products'],
    queryFn: async () =>
      request(
        'http://localhost:3000/shop-api',
        // highlight-start
        GET_PRODUCTS,
        {
        // The variables will also be correctly typed
        options: { take: 3 },
        }
        // highlight-end
      ),
  });

  if (isLoading) return <p>Loading...</p>;

  return data ? (
    data.products.items.map(({ id, name, slug, featuredAsset }) => (
      <div key={id}>
        <h3>{name}</h3>
        <img src={`${featuredAsset.preview}?preset=small`} alt={name} />
      </div>
    ))
  ) : (
    <>Loading...</>
  );
}
```

In the above example, the type information all works out of the box because the `graphql-request` library from v5.0.0
has built-in support for the [`TypedDocumentNode`](https://github.com/dotansimha/graphql-typed-document-node) type,
as do the latest versions of most of the popular GraphQL client libraries, such as Apollo Client & Urql.

:::note
In the documentation examples on other pages, we do not assume the use of code generation in order to keep the examples as simple as possible.
:::


---

---
title: Connect to the API
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import Stackblitz from '@site/src/components/Stackblitz';

The first thing you'll need to do is to connect your storefront app to the **Shop API**. The Shop API is a GraphQL API
that provides access to the products, collections, customer data, and exposes mutations that allow you to add items to
the cart, checkout, manage customer accounts, and more.

:::tip
You can explore the Shop API by opening the GraphQL Playground in your browser at
[`http://localhost:3000/shop-api`](http://localhost:3000/shop-api) when your Vendure
server is running locally.
:::

## Select a GraphQL client

GraphQL requests are made over HTTP, so you can use any HTTP client such as the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) to make requests to the Shop API. However, there are also a number of specialized GraphQL clients which can make working with GraphQL APIs easier. Here are some popular options:

* [Apollo Client](https://www.apollographql.com/docs/react): A full-featured client which includes a caching layer and React integration.
* [urql](https://formidable.com/open-source/urql/): The highly customizable and versatile GraphQL client for React, Svelte, Vue, or plain JavaScript
* [graphql-request](https://github.com/jasonkuhrt/graphql-request): Minimal GraphQL client supporting Node and browsers for scripts or simple apps
* [TanStack Query](https://tanstack.com/query/latest): Powerful asynchronous state management for TS/JS, React, Solid, Vue and Svelte, which can be combined with `graphql-request`.


## Managing Sessions

Vendure supports two ways to manage user sessions: **cookies** and **bearer token**. The method you choose depends on your requirements, and is specified by the [`authOptions.tokenMethod` property](/reference/typescript-api/auth/auth-options/#tokenmethod) of the VendureConfig. By default, both are enabled on the server:

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';

export const config: VendureConfig = {
    // ...
    authOptions: {
        // highlight-next-line
        tokenMethod: ['bearer', 'cookie'],
    },
};
```

### Cookie-based sessions

Using cookies is the simpler approach for browser-based applications, since the browser will manage the cookies for you automatically.

1. Enable the `credentials` option in your HTTP client. This allows the browser to send the session cookie with each request.

    For example, if using a fetch-based client (such as [Apollo client](https://www.apollographql.com/docs/react/recipes/authentication/#cookie)) you would set `credentials: 'include'` or if using [XMLHttpRequest](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/withCredentials), you would set `withCredentials: true`

2. When using cookie-based sessions, you should set the [`authOptions.cookieOptions.secret` property](/reference/typescript-api/auth/cookie-options#secret) to some secret string which will be used to sign the cookies sent to clients to prevent tampering. This string could be hard-coded in your config file, or (better) reside in an environment variable:

    ```ts title="src/vendure-config.ts"
    import { VendureConfig } from '@vendure/core';

    export const config: VendureConfig = {
        // ...
        authOptions: {
            tokenMethod: ['bearer', 'cookie'],
            // highlight-start
            cookieOptions: {
                secret: process.env.COOKIE_SESSION_SECRET
            }
            // highlight-end
        }
    }
    ```

:::caution
**SameSite cookies**

When using cookies to manage sessions, you need to be aware of the SameSite cookie policy. This policy is designed to prevent cross-site request forgery (CSRF) attacks, but can cause problems when using a headless storefront app which is hosted on a different domain to the Vendure server. See [this article](https://web.dev/samesite-cookies-explained/) for more information.
:::

### Bearer-token sessions

Using bearer tokens involves a bit more work on your part: you'll need to manually read response headers to get the token, and once you have it you'll have to manually add it to the headers of each request.

The workflow would be as follows:

1. Certain mutations and queries initiate a session (e.g. logging in, adding an item to an order etc.). When this happens, the response will contain a HTTP header which [by default is called `'vendure-auth-token'`](/reference/typescript-api/auth/auth-options#authtokenheaderkey).
2. So your http client would need to check for the presence of this header each time it receives a response from the server.
3. If the `'vendure-auth-token'` header is present, read the value and store it because this is your bearer token.
4. Attach this bearer token to each subsequent request as `Authorization: Bearer <token>`.

Here's a simplified example of how that would look:

```ts
let token: string | undefined = localStorage.getItem('token')

export async function request(query: string, variables: any) {
     // If we already know the token, set the Authorization header.
     const headers = token ? { Authorization: `Bearer ${token}` } : {};

     const response = await someGraphQlClient(query, variables, headers);

     // Check the response headers to see if Vendure has set the
     // auth token. The header key "vendure-auth-token" may be set to
     // a custom value with the authOptions.authTokenHeaderKey config option.
     const authToken = response.headers.get('vendure-auth-token');
     if (authToken != null) {
         token = authToken;
     }
     return response.data;
}
```

There are some concrete examples of this approach in the examples later on in this guide.

### Session duration

The duration of a session is determined by the [AuthOptions.sessionDuration](/reference/typescript-api/auth/auth-options#sessionduration) config
property. Sessions will automatically extend (or "refresh") when a user interacts with the API, so in effect the `sessionDuration` signifies the
length of time that a session will stay valid since the last API call.

## Specifying a channel

If your project has multiple [channels](/guides/core-concepts/channels/), you can specify the active channel by setting
the `vendure-token` header on each request to match the `channelToken` for the desired channel.

Let's say you have a channel with the token `uk-channel` and you want to make a request to the Shop API to get the
products in that channel. You would set the `vendure-token` header to `uk-channel`:

```ts title="src/client.ts"
export function query(document: string, variables: Record<string, any> = {}) {
    return fetch('https://localhost:3000/shop-api', {
        method: 'POST',
        headers: {
            'content-type': 'application/json',
            // highlight-start
            'vendure-token': 'uk-channel',
            // highlight-end
        },
        credentials: 'include',
        body: JSON.stringify({
          query: document,
          variables,
        }),
    })
      .then((res) => res.json())
      .catch((err) => console.log(err));
}
```

:::note
If no channel token is specified, then the **default channel** will be used.
:::

:::info
The header name `vendure-token` is the default, but can be changed using the [`apiOptions.channelTokenKey`](/reference/typescript-api/configuration/api-options/#channeltokenkey) config option.
:::

## Setting language

If you have translations of your products, collections, facets etc, you can specify the language for the request by setting the `languageCode` query string on the request. The value should be one of the ISO 639-1 codes defined by the [`LanguageCode` enum](/reference/typescript-api/common/language-code/).

```
POST http://localhost:3000/shop-api?languageCode=de
```

## Code generation

If you are building your storefront with TypeScript, we highly recommend you set up code generation to ensure
that the responses from your queries & mutation are always correctly typed according the fields you request.

See the [GraphQL Code Generation guide](/guides/storefront/codegen/) for more information.

## Examples

Here are some examples of how to set up clients to connect to the Shop API. All of these examples include functions for setting the language and channel token.

### Fetch

First we'll look at a plain [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)-based implementation, to show you that there's no special magic to a GraphQL request - it's just a POST request with a JSON body.

Note that we also include a React hook in this example, but that's just to make it more convenient to use the client
in a React component - it is not required.


<Tabs>
<TabItem value="client.ts" label="client.ts" default>

```ts title="src/client.ts"
import { useState, useEffect } from 'react';

// If using bearer-token based session management, we'll store the token
// in localStorage using this key.
const AUTH_TOKEN_KEY = 'auth_token';

const API_URL = 'https://readonlydemo.vendure.io/shop-api';

let languageCode: string | undefined;
let channelToken: string | undefined;

export function setLanguageCode(value: string | undefined) {
    languageCode = value;
}

export function setChannelToken(value: string | undefined) {
    channelToken = value;
}

export function query(document: string, variables: Record<string, any> = {}) {
    const authToken = localStorage.getItem(AUTH_TOKEN_KEY);
    const headers = new Headers({
        'content-type': 'application/json',
    });
    if (authToken) {
        headers.append('authorization', `Bearer ${authToken}`);
    }
    if (channelToken) {
        headers.append('vendure-token', channelToken);
    }
    let endpoint = API_URL;
    if (languageCode) {
        endpoint += `?languageCode=${languageCode}`;
    }
    // highlight-start
    return fetch(endpoint, {
        method: 'POST',
        headers,
        credentials: 'include',
        body: JSON.stringify({
            query: document,
            variables,
        }),
    // highlight-end
    }).then((res) => {
        if (!res.ok) {
            throw new Error(`An error ocurred, HTTP status: ${res.status}`);
        }
        const newAuthToken = res.headers.get('vendure-auth-token');
        if (newAuthToken) {
            localStorage.setItem(AUTH_TOKEN_KEY, newAuthToken);
        }
        return res.json();
    });
}

/**
 * Here we have wrapped the `query` function into a React hook for convenient use in
 * React components.
 */
 export function useQuery(
    document: string,
    variables: Record<string, any> = {}
) {
    const [data, setData] = useState(null);
    const [loading, setLoading] = useState(true);
    const [error, setError] = useState(null);

    useEffect(() => {
        query(document, variables)
            .then((result) => {
                setData(result.data);
                setError(null);
            })
            .catch((err) => {
                setError(err.message);
                setData(null);
            })
            .finally(() => {
                setLoading(false);
            });
    }, []);

    return { data, loading, error };
}
```

</TabItem>
<TabItem value="App.tsx" label="App.tsx" default>

```ts title="src/App.tsx"
import { useQuery } from './client';
import './style.css';

const GET_PRODUCTS = /*GraphQL*/ `
    query GetProducts($options: ProductListOptions) {
        products(options: $options) {
            items {
                id
                name
                slug
                featuredAsset {
                    preview
                }
            }
        }
    }
`;

export default function App() {
    const { data, loading, error } = useQuery(GET_PRODUCTS, {
        options: { take: 3 },
    });

    if (loading) return <p>Loading...</p>;
    if (error) return <p>Error : {error.message}</p>;

    return data.products.items.map(({ id, name, slug, featuredAsset }) => (
        <div key={id}>
            <h3>{name}</h3>
            <img src={`${featuredAsset.preview}?preset=small`} alt={name} />
        </div>
    ));
}

```

</TabItem>
<TabItem value="index.ts" label="index.ts" default>

```ts title="src/index.ts"
 import * as React from 'react';
 import { StrictMode } from 'react';
 import { createRoot } from 'react-dom/client';

 import App from './App';

 const rootElement = document.getElementById('root');
 const root = createRoot(rootElement);

 root.render(
     <StrictMode>
         <App />
     </StrictMode>
 );
```

</TabItem>
</Tabs>

Here's a live version of this example:

<Stackblitz id='vendure-docs-fetch-react' />

As you can see, the basic implementation with `fetch` is quite straightforward. However, it is also lacking some features that other,
dedicated client libraries will provide.

### Apollo Client

Here's an example configuration for [Apollo Client](https://www.apollographql.com/docs/react/) with a React app.

Follow the [getting started instructions](https://www.apollographql.com/docs/react/get-started) to install the required
packages.


<Tabs>
<TabItem value="client.ts" label="client.ts" default>

```ts title="src/client.ts"
import {
    ApolloClient,
    ApolloLink,
    HttpLink,
    InMemoryCache,
} from '@apollo/client';
import { setContext } from '@apollo/client/link/context';

const API_URL = `https://demo.vendure.io/shop-api`;

// If using bearer-token based session management, we'll store the token
// in localStorage using this key.
const AUTH_TOKEN_KEY = 'auth_token';

let channelToken: string | undefined;
let languageCode: string | undefined;

const httpLink = new HttpLink({
    uri: () => {
        if (languageCode) {
            return `${API_URL}?languageCode=${languageCode}`;
        } else {
            return API_URL;
        }
    },
    // This is required if using cookie-based session management,
    // so that any cookies get sent with the request.
    credentials: 'include',
});

// This part is used to check for and store the session token
// if it is returned by the server.
const afterwareLink = new ApolloLink((operation, forward) => {
    return forward(operation).map((response) => {
        const context = operation.getContext();
        const authHeader = context.response.headers.get('vendure-auth-token');
        if (authHeader) {
            // If the auth token has been returned by the Vendure
            // server, we store it in localStorage
            localStorage.setItem(AUTH_TOKEN_KEY, authHeader);
        }
        return response;
    });
});

/**
 * Used to specify a channel token for projects that use
 * multiple Channels.
 */
export function setChannelToken(value: string | undefined) {
    channelToken = value;
}

/**
 * Used to specify a language for any localized results.
 */
export function setLanguageCode(value: string | undefined) {
    languageCode = value;
}

export const client = new ApolloClient({
    link: ApolloLink.from([
        // If we have stored the authToken from a previous
        // response, we attach it to all subsequent requests.
        setContext((request, operation) => {
            const authToken = localStorage.getItem(AUTH_TOKEN_KEY);
            let headers: Record<string, any> = {};
            if (authToken) {
                headers.authorization = `Bearer ${authToken}`;
            }
            if (channelToken) {
                headers['vendure-token'] = channelToken;
            }
            return { headers };
        }),
        afterwareLink,
        httpLink,
    ]),
    cache: new InMemoryCache(),
});
```

</TabItem>
<TabItem value='index.tsx' label='index.tsx'>

```tsx title="src/index.tsx"
import React from 'react';
import * as ReactDOM from 'react-dom/client';
import { ApolloProvider } from '@apollo/client';
import App from './App';
import { client } from './client';

// Supported in React 18+
const root = ReactDOM.createRoot(document.getElementById('root'));

root.render(
    <ApolloProvider client={client}>
        <App />
    </ApolloProvider>,
);
```

</TabItem>
<TabItem value="App.tsx" label="App.tsx">

```tsx title="src/App.tsx"
import { useQuery, gql } from '@apollo/client';

const GET_PRODUCTS = gql`
    query GetProducts($options: ProductListOptions) {
        products(options: $options) {
            items {
                id
                name
                slug
                featuredAsset {
                    preview
                }
            }
        }
    }
`;

export default function App() {
    const { loading, error, data } = useQuery(GET_PRODUCTS, {
        variables: { options: { take: 3 } },
    });

    if (loading) return <p>Loading...</p>;
    if (error) return <p>Error : {error.message}</p>;

    return data.products.items.map(({ id, name, slug, featuredAsset }) => (
        <div key={id}>
            <h3>{name}</h3>
            <img src={`${featuredAsset.preview}?preset=small`} alt={name} />
        </div>
    ));
}
```

</TabItem>
</Tabs>


Here's a live version of this example:

<Stackblitz id='vendure-docs-apollo-client' />

### TanStack Query

Here's an example using [@tanstack/query](https://tanstack.com/query/latest) in combination with [graphql-request](https://github.com/jasonkuhrt/graphql-request) based on [this guide](https://tanstack.com/query/v4/docs/react/graphql).

Note that in this example we have also installed the [`@graphql-typed-document-node/core` package](https://github.com/dotansimha/graphql-typed-document-node), which allows the
client to work with TypeScript code generation for type-safe queries.

<Tabs>

<TabItem value="client.ts" label="client.ts" default>

```tsx title="src/client.ts"
import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
import {
    GraphQLClient,
    RequestDocument,
    RequestMiddleware,
    ResponseMiddleware,
    Variables,
} from 'graphql-request';

// If using bearer-token based session management, we'll store the token
// in localStorage using this key.
const AUTH_TOKEN_KEY = 'auth_token';

const API_URL = 'http://localhost:3000/shop-api';

// If we have a session token, add it to the outgoing request
const requestMiddleware: RequestMiddleware = async (request) => {
    const authToken = localStorage.getItem(AUTH_TOKEN_KEY);
    return {
        ...request,
        headers: {
            ...request.headers,
            ...(authToken ? { authorization: `Bearer ${authToken}` } : {}),
        },
    };
};

// Check all responses for a new session token
const responseMiddleware: ResponseMiddleware = (response) => {
    if (!(response instanceof Error) && !response.errors) {
        const authHeader = response.headers.get('vendure-auth-token');
        if (authHeader) {
            // If the session token has been returned by the Vendure
            // server, we store it in localStorage
            localStorage.setItem(AUTH_TOKEN_KEY, authHeader);
        }
    }
};

const client = new GraphQLClient(API_URL, {
    // Required for cookie-based sessions
    credentials: 'include',
    requestMiddleware,
    responseMiddleware,
});

/**
 * Sets the languageCode to be used for all subsequent requests.
 */
export function setLanguageCode(languageCode: string | undefined) {
    if (!languageCode) {
        client.setEndpoint(API_URL);
    } else {
        client.setEndpoint(`${API_URL}?languageCode=${languageCode}`);
    }
}

/**
 * Sets the channel token to be used for all subsequent requests.
 */
export function setChannelToken(channelToken: string | undefined) {
    if (!channelToken) {
        client.setHeader('vendure-token', undefined);
    } else {
        client.setHeader('vendure-token', channelToken);
    }
}

/**
 * Makes a GraphQL request using the `graphql-request` client.
 */
export function request<T, V extends Variables = Variables>(
    document: RequestDocument | TypedDocumentNode<T, V>,
    variables: Record<string, any> = {}
) {
    return client.request(document, variables);
}
```

</TabItem>

<TabItem value="App.tsx" label="App.tsx">

```tsx title="src/App.tsx"
import * as React from 'react';
import { gql } from 'graphql-request';
import { useQuery } from '@tanstack/react-query';
import { request } from './client';

const GET_PRODUCTS = gql`
    query GetProducts($options: ProductListOptions) {
        products(options: $options) {
            items {
                id
                name
                slug
                featuredAsset {
                    preview
                }
            }
        }
    }
`;

export default function App() {
    const { isLoading, data } = useQuery({
        queryKey: ['products'],
        queryFn: async () =>
            request(GET_PRODUCTS, {
                options: { take: 3 },
            }),
    });

    if (isLoading) return <p>Loading...</p>;

    return data ? (
        data.products.items.map(({ id, name, slug, featuredAsset }) => (
            <div key={id}>
                <h3>{name}</h3>
                <img src={`${featuredAsset.preview}?preset=small`} alt={name} />
            </div>
        ))
    ) : (
        <>Loading...</>
    );
}
```

</TabItem>


<TabItem value="index.tsx" label="index.tsx" default>

```ts title="src/index.tsx"
import * as React from 'react';
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

import App from './App';

// Create a client
const queryClient = new QueryClient();

const rootElement = document.getElementById('root');
const root = createRoot(rootElement);

root.render(
    <StrictMode>
        <QueryClientProvider client={queryClient}>
            <App />
        </QueryClientProvider>
    </StrictMode>
);
```

</TabItem>
</Tabs>

Here's a live version of this example:

<Stackblitz id='vendure-docs-tanstack-query' />



---

---
title: "Customer Accounts"
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Customers can register accounts and thereby gain the ability to:

- View past orders
- Store multiple addresses
- Maintain an active order across devices
- Take advantage of plugins that expose functionality to registered customers only, such as wishlists & loyalty points.

## Querying the active customer

The [`activeCustomer` query](/reference/graphql-api/shop/queries/#activecustomer) will return a [`Customer`](/reference/graphql-api/shop/object-types#customer) object if the customer is registered and logged in, otherwise it will return `null`. This can be used in the storefront header for example to
determine whether to display a "sign in" or "my account" link.


<Tabs>
<TabItem value="Query" label="Query" default>

```graphql
query GetCustomerAddresses {
  activeCustomer {
    id
    title
    firstName
    lastName
    emailAddress
  }
}
```

</TabItem>
<TabItem value="Result" label="Result">

```json
{
  "data": {
    "activeCustomer": {
      "id": "12345",
      "title": "Mr.",
      "firstName": "John",
      "lastName": "Doe",
      "emailAddress": "john.doe@email.com"
    }
  }
}
```

</TabItem>
</Tabs>

## Logging in and out

The [`login` mutation](/reference/graphql-api/shop/mutations#login) is used to attempt to log in using email address and password.
Given correct credentials, a new authenticated session will begin for that customer.



<Tabs>
<TabItem value="Query" label="Query" default>

```graphql
mutation LogIn($emailAddress: String!, $password: String!, $rememberMe: Boolean!) {
  login(username: $emailAddress, password: $password, rememberMe: $rememberMe) {
    ... on  CurrentUser {
      id
      identifier
    }
    ... on ErrorResult {
      errorCode
      message
    }
  }
}
```

</TabItem>
<TabItem value="Variables" label="Variables">

```json
{
  "emailAddress": "john.doe@email.com",
  "password": "**********",
  "rememberMe": true,
}
```

</TabItem>
<TabItem value="Result" label="Result">

```json
{
  "data": {
    "login": {
      "id": "12345",
      "identifier": "john.doe@email.com"
    }
  }
}
```

</TabItem>
</Tabs>

The [`logout` mutation](/reference/graphql-api/shop/mutations#logout) will end an authenticated customer session.


<Tabs>
<TabItem value="Query" label="Query" default>

```graphql
mutation LogOut {
  logout {
    success
  }
}
```

</TabItem>
<TabItem value="Result" label="Result">

```json
{
  "data": {
    "logout": {
      "success": true,
    }
  }
}
```

</TabItem>
</Tabs>

:::note
The `login` mutation, as well as the following mutations related to registration & password recovery only
apply when using the built-in [`NativeAuthenticationStrategy`](/reference/typescript-api/auth/native-authentication-strategy/).

If you are using alternative authentication strategies in your storefront, you would use the [`authenticate` mutation](/reference/graphql-api/shop/mutations/#authenticate) as covered in the [External Authentication guide](/guides/core-concepts/auth/#external-authentication).
:::

## Registering a customer account

The [`registerCustomerAccount` mutation](/reference/graphql-api/shop/mutations/#registercustomeraccount) is used to register a new customer account.

There are three possible registration flows:
If [`authOptions.requireVerification`](/reference/typescript-api/auth/auth-options/#requireverification) is set to `true` (the default):

1. **The Customer is registered _with_ a password**. A verificationToken will be created (and typically emailed to the Customer). That
verificationToken would then be passed to the verifyCustomerAccount mutation _without_ a password. The Customer is then
verified and authenticated in one step.
2. **The Customer is registered _without_ a password**. A verificationToken will be created (and typically emailed to the Customer). That
verificationToken would then be passed to the verifyCustomerAccount mutation _with_ the chosen password of the Customer. The Customer is then
verified and authenticated in one step.

If `authOptions.requireVerification` is set to `false`:

3. The Customer _must_ be registered _with_ a password. No further action is needed - the Customer is able to authenticate immediately.

Here's a diagram of the second scenario, where the password is supplied during the _verification_ step.

![Verification flow](./verification.webp)

Here's how the mutations would look for the above flow:


<Tabs>
<TabItem value="Mutation" label="Mutation" default>

```graphql
mutation Register($input: RegisterCustomerInput!) {
  registerCustomerAccount(input: $input) {
    ... on Success {
      success
    }
    ...on ErrorResult {
      errorCode
      message
    }
  }
}
```

</TabItem>
<TabItem value="Variables" label="Variables">

```json
{
  "input: {
    "title": "Mr."
    "firstName": "Nicky",
    "lastName": "Wire",
    "emailAddress": "nicky@example.com",
    "phoneNumber": "1234567",
  }
}
```

</TabItem>
<TabItem value="Result" label="Result">

```json
{
  "data": {
    "registerCustomerAccount": {
      "success": true,
    }
  }
}
```

</TabItem>
</Tabs>

Note that in the variables above, we did **not** specify a password, as this will be done at the verification step.
If a password _does_ get passed at this step, then it won't be needed at the verification step. This is a decision
you can make based on the desired user experience of your storefront.

Upon registration, the [EmailPlugin](/reference/core-plugins/email-plugin/) will generate an email to the
customer containing a link to the verification page. In a default Vendure installation this is set in the vendure config file:

```ts title="src/vendure-config.ts"
EmailPlugin.init({
    route: 'mailbox',
    handlers: defaultEmailHandlers,
    templatePath: path.join(__dirname, '../static/email/templates'),
    outputPath: path.join(__dirname, '../static/email/output'),
    globalTemplateVars: {
        fromAddress: '"Vendure Demo Store" <noreply@vendure.io>',
        // highlight-next-line
        verifyEmailAddressUrl: 'https://demo.vendure.io/storefront/account/verify',
        passwordResetUrl: 'https://demo.vendure.io/storefront/account/reset-password',
        changeEmailAddressUrl: 'https://demo.vendure.io/storefront/account/change-email-address'
    },
    devMode: true,
}),
```

The verification page needs to get the token from the query string, and pass it to the [`verifyCustomerAccount` mutation](/reference/graphql-api/shop/mutations/#verifycustomeraccount):


<Tabs>
<TabItem value="Mutation" label="Mutation" default>

```graphql
mutation Verify($password: String!, $token: String!) {
  verifyCustomerAccount(password: $password, token: $token) {
    ...on CurrentUser {
      id
      identifier
    }
    ...on ErrorResult {
      errorCode
      message
    }
  }
}
```

</TabItem>
<TabItem value="Variables" label="Variables">

```json
{
  "password": "*********",
  "token": "MjAxOS0xMC0wMlQxNToxOTo1NC45NDVa_1DYEWYAB7S3S82JT"
}
```

</TabItem>
<TabItem value="Result" label="Result">

```json
{
  "data": {
    "verifyCustomerAccount": {
      "id": "123",
      "identifier": "nicky@example.com"
    }
  }
}
```

</TabItem>
</Tabs>

## Password reset

Here's how to implement a password reset flow. It is conceptually very similar to the verification flow described above.

![Password reset flow](./pw-reset.webp)

A password reset is triggered by the [`requestPasswordReset` mutation](/reference/graphql-api/shop/mutations/#requestpasswordreset):

<Tabs>
<TabItem value="Mutation" label="Mutation" default>

```graphql
mutation RequestPasswordReset($emailAddress: String!) {
  requestPasswordReset(emailAddress: $emailAddress) {
    ... on Success {
      success
    }
    ... on ErrorResult {
      errorCode
      message
    }
  }
}
```

</TabItem>
<TabItem value="Variables" label="Variables">

```json
{
  "emailAddress": "nicky@example.com",
}
```

</TabItem>
<TabItem value="Result" label="Result">

```json
{
  "data": {
    "requestPasswordReset": {
      "success": true,
    }
  }
}
```

</TabItem>
</Tabs>

Again, this mutation will trigger an event which the EmailPlugin's default email handlers will pick up and send
an email to the customer. The password reset page then needs to get the token from the url and pass it to the
[`resetPassword` mutation](/reference/graphql-api/shop/mutations/#resetpassword):


<Tabs>
<TabItem value="Mutation" label="Mutation" default>

```graphql
mutation ResetPassword($token: String! $password: String!) {
  resetPassword(token: $token password: $password) {
    ...on CurrentUser {
      id
      identifier
    }
    ... on ErrorResult {
      errorCode
      message
    }
  }
}
```

</TabItem>
<TabItem value="Variables" label="Variables">

```json
{
  "token": "MjAxOS0xMC0wMlQxNToxOTo1NC45NDVa_1DYEWYAB7S3S82JT",
  "password": "************"
}
```

</TabItem>
<TabItem value="Result" label="Result">

```json
{
  "data": {
    "resetPassword": {
      "id": "123",
      "identifier": "nicky@example.com"
    }
  }
}
```

</TabItem>
</Tabs>


---

---
title: "Listing Products"
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import Stackblitz from '@site/src/components/Stackblitz';

Products are listed when:

- Displaying the contents of a collection
- Displaying search results

In Vendure, we usually use the `search` query for both of these. The reason is that the `search` query is optimized
for high performance, because it is backed by a dedicated search index. Other queries such as `products` or `Collection.productVariants` _can_ also
be used to fetch a list of products, but they need to perform much more complex database queries, and are therefore slower.

## Listing products in a collection

Following on from the [navigation example](/guides/storefront/navigation-menu/), let's assume that a customer has
clicked on a collection item from the menu, and we want to display the products in that collection.

Typically, we will know the `slug` of the selected collection, so we can use the `collection` query to fetch the
details of this collection:

<Tabs>
<TabItem value="Query" label="Query" default>

```graphql
query GetCollection($slug: String!) {
  collection(slug: $slug) {
    id
    name
    slug
    description
    featuredAsset {
      id
      preview
    }
  }
}
```

</TabItem>
<TabItem value="Variables" label="Variables">

```json
{
  "slug": "electronics"
}
```

</TabItem>
<TabItem value="Response" label="Response" >

```json
{
  "data": {
    "collection": {
      "id": "2",
      "name": "Electronics",
      "slug": "electronics",
      "description": "",
      "featuredAsset": {
        "id": "16",
        "preview": "https://demo.vendure.io/assets/preview/5b/jakob-owens-274337-unsplash__preview.jpg"
      }
    }
  }
}
```

</TabItem>
</Tabs>

The collection data can be used to render the page header.

Next, we can use the `search` query to fetch the products in the collection:


<Tabs>
<TabItem value="Query" label="Query" default>

```graphql
query GetCollectionProducts($slug: String!, $skip: Int, $take: Int) {
  search(
    input: {
      // highlight-next-line
      collectionSlug: $slug,
      groupByProduct: true,
      skip: $skip,
      take: $take }
  ) {
    totalItems
    items {
      productName
      slug
      productAsset {
        id
        preview
      }
      priceWithTax {
        ... on SinglePrice {
          value
        }
        ... on PriceRange {
          min
          max
        }
      }
      currencyCode
    }
  }
}
```

</TabItem>
<TabItem value="Variables" label="Variables">

```json
{
  "slug": "electronics",
  "skip": 0,
  "take": 10
}
```

</TabItem>
<TabItem value="Response" label="Response" >

(the following data has been truncated for brevity)

```json
{
  "data": {
    "search": {
      "totalItems": 20,
      "items": [
        {
          "productName": "Laptop",
          "slug": "laptop",
          "productAsset": {
            "id": "1",
            "preview": "https://demo.vendure.io/assets/preview/71/derick-david-409858-unsplash__preview.jpg"
          },
          "priceWithTax": {
            "min": 155880,
            "max": 275880
          },
          "currencyCode": "USD"
        },
        {
          "productName": "Tablet",
          "slug": "tablet",
          "productAsset": {
            "id": "2",
            "preview": "https://demo.vendure.io/assets/preview/b8/kelly-sikkema-685291-unsplash__preview.jpg"
          },
          "priceWithTax": {
            "min": 39480,
            "max": 53400
          },
          "currencyCode": "USD"
        },
      ],
    },
  },
}
```


</TabItem>
</Tabs>

:::note
The key thing to note here is that we are using the `collectionSlug` input to the `search` query. This ensures
that the results all belong to the selected collection.
:::

Here's a live demo of the above code in action:

<Stackblitz id='vendure-docs-listing-collection-products' />

## Product search

The `search` query can also be used to perform a full-text search of the products in the catalog by passing the
`term` input:

<Tabs>
<TabItem value="Query" label="Query">

```graphql
query SearchProducts($term: String!, $skip: Int, $take: Int) {
  search(
    input: {
      // highlight-next-line
      term: $term,
      groupByProduct: true,
      skip: $skip,
      take: $take }
  ) {
    totalItems
    items {
      productName
      slug
      productAsset {
        id
        preview
      }
      priceWithTax {
        ... on SinglePrice {
          value
        }
        ... on PriceRange {
          min
          max
        }
      }
      currencyCode
    }
  }
}
```

</TabItem>
<TabItem value="Variables" label="Variables">

```json
{
  "term": "camera",
  "skip": 0,
  "take": 10
}
```

</TabItem>
<TabItem value="Response" label="Response" >

(the following data has been truncated for brevity)

```json
{
  "data": {
    "search": {
      "totalItems": 8,
      "items": [
        {
          "productName": "Instant Camera",
          "slug": "instant-camera",
          "productAsset": {
            "id": "12",
            "preview": "https://demo.vendure.io/assets/preview/b5/eniko-kis-663725-unsplash__preview.jpg"
          },
          "priceWithTax": {
            "min": 20999,
            "max": 20999
          },
          "currencyCode": "USD"
        },
        {
          "productName": "Camera Lens",
          "slug": "camera-lens",
          "productAsset": {
            "id": "13",
            "preview": "https://demo.vendure.io/assets/preview/9b/brandi-redd-104140-unsplash__preview.jpg"
          },
          "priceWithTax": {
            "min": 12480,
            "max": 12480
          },
          "currencyCode": "USD"
        }
      ]
    }
  }
}
```

</TabItem>
</Tabs>

:::tip
You can also limit the full-text search to a specific collection by passing the
`collectionSlug` or `collectionId` input.
:::

## Faceted search

The `search` query can also be used to perform faceted search. This is a powerful feature which allows customers
to filter the results according to the facet values assigned to the products & variants.

By using the `facetValues` field, the search query will return a list of all the facet values which are present
in the result set. This can be used to render a list of checkboxes or other UI elements which allow the customer
to filter the results.

<Tabs>
<TabItem value="Query" label="Query">

```graphql
query SearchProducts($term: String!, $skip: Int, $take: Int) {
  search(
    input: {
      term: $term,
      groupByProduct: true,
      skip: $skip,
      take: $take }
  ) {
    totalItems
    // highlight-start
    facetValues {
      count
      facetValue {
        id
        name
        facet {
          id
          name
        }
      }
    }
    // highlight-end
    items {
      productName
      slug
      productAsset {
        id
        preview
      }
      priceWithTax {
        ... on SinglePrice {
          value
        }
        ... on PriceRange {
          min
          max
        }
      }
      currencyCode
    }
  }
}
```

</TabItem>
<TabItem value="Variables" label="Variables" default>

```json
{
  "term": "camera",
  "skip": 0,
  "take": 10
}
```

</TabItem>
<TabItem value="Response" label="Response" >

(the following data has been truncated for brevity)

```json
{
  "data": {
    "search": {
      "totalItems": 8,
      // highlight-start
      "facetValues": [
        {
          "facetValue": {
            "id": "1",
            "name": "Electronics",
            "facet": {
              "id": "1",
              "name": "category"
            }
          },
          "count": 8
        },
        {
          "facetValue": {
            "id": "9",
            "name": "Photo",
            "facet": {
              "id": "1",
              "name": "category"
            }
          },
          "count": 8
        },
        {
          "facetValue": {
            "id": "10",
            "name": "Polaroid",
            "facet": {
              "id": "2",
              "name": "brand"
            }
          },
          "count": 1
        },
        {
          "facetValue": {
            "id": "11",
            "name": "Nikkon",
            "facet": {
              "id": "2",
              "name": "brand"
            }
          },
          "count": 2
        },
        {
          "facetValue": {
            "id": "12",
            "name": "Agfa",
            "facet": {
              "id": "2",
              "name": "brand"
            }
          },
          "count": 1
        },
        {
          "facetValue": {
            "id": "14",
            "name": "Kodak",
            "facet": {
              "id": "2",
              "name": "brand"
            }
          },
          "count": 1
        },
        {
          "facetValue": {
            "id": "15",
            "name": "Sony",
            "facet": {
              "id": "2",
              "name": "brand"
            }
          },
          "count": 1
        },
        {
          "facetValue": {
            "id": "16",
            "name": "Rolleiflex",
            "facet": {
              "id": "2",
              "name": "brand"
            }
          },
          "count": 1
        }
      ],
      // highlight-end
      "items": [
        {
          "productName": "Instant Camera",
          "slug": "instant-camera",
          "productAsset": {
            "id": "12",
            "preview": "https://demo.vendure.io/assets/preview/b5/eniko-kis-663725-unsplash__preview.jpg"
          },
          "priceWithTax": {
            "min": 20999,
            "max": 20999
          },
          "currencyCode": "USD"
        },
        {
          "productName": "Camera Lens",
          "slug": "camera-lens",
          "productAsset": {
            "id": "13",
            "preview": "https://demo.vendure.io/assets/preview/9b/brandi-redd-104140-unsplash__preview.jpg"
          },
          "priceWithTax": {
            "min": 12480,
            "max": 12480
          },
          "currencyCode": "USD"
        },
        {
          "productName": "Vintage Folding Camera",
          "slug": "vintage-folding-camera",
          "productAsset": {
            "id": "14",
            "preview": "https://demo.vendure.io/assets/preview/3c/jonathan-talbert-697262-unsplash__preview.jpg"
          },
          "priceWithTax": {
            "min": 642000,
            "max": 642000
          },
          "currencyCode": "USD"
        }
      ]
    }
  }
}
```

</TabItem>
</Tabs>

These facet values can then be used to filter the results by passing them to the `facetValueFilters` input

For example, let's filter the results to only include products which have the "Nikkon" brand. Based on our last
request we know that there should be 2 such products, and that the `facetValue.id` for the "Nikkon" brand is `11`.

```json
{
  "facetValue": {
    // highlight-next-line
    "id": "11",
    "name": "Nikkon",
    "facet": {
      "id": "2",
      "name": "brand"
    }
  },
  // highlight-next-line
  "count": 2
}
```

Here's how we can use this information to filter the results:

:::note
In the next example, rather than passing each individual variable (skip, take, term) as a separate argument,
we are passing the entire `SearchInput` object as a variable. This allows us more flexibility in how
we use the query, as we can easily add or remove properties from the input object without having to
change the query itself.
:::


<Tabs>
<TabItem value="Query" label="Query">

```graphql
query SearchProducts($input: SearchInput!) {
  // highlight-next-line
  search(input: $input) {
    totalItems
    facetValues {
      count
      facetValue {
        id
        name
        facet {
          id
          name
        }
      }
    }
    items {
      productName
      slug
      productAsset {
        id
        preview
      }
      priceWithTax {
        ... on SinglePrice {
          value
        }
        ... on PriceRange {
          min
          max
        }
      }
      currencyCode
    }
  }
}
```

</TabItem>
<TabItem value="Variables" label="Variables" default>

```json
{
  "input": {
    "term": "camera",
    "skip": 0,
    "take": 10,
    "groupByProduct": true,
    // highlight-start
    "facetValueFilters": [
      { "and": "11" }
    ]
    // highlight-end
  }
}
```

</TabItem>
<TabItem value="Response" label="Response" >

```json
{
  "data": {
    "search": {
      "totalItems": 2,
      "facetValues": [
        {
          "facetValue": {
            "id": "1",
            "name": "Electronics",
            "facet": {
              "id": "1",
              "name": "category"
            }
          },
          "count": 2
        },
        {
          "facetValue": {
            "id": "9",
            "name": "Photo",
            "facet": {
              "id": "1",
              "name": "category"
            }
          },
          "count": 2
        },
        {
          "facetValue": {
            "id": "11",
            "name": "Nikkon",
            "facet": {
              "id": "2",
              "name": "brand"
            }
          },
          "count": 2
        }
      ],
      "items": [
        {
          "productName": "Camera Lens",
          "slug": "camera-lens",
          "productAsset": {
            "id": "13",
            "preview": "https://demo.vendure.io/assets/preview/9b/brandi-redd-104140-unsplash__preview.jpg"
          },
          "priceWithTax": {
            "value": 12480
          },
          "currencyCode": "USD"
        },
        {
          "productName": "Nikkormat SLR Camera",
          "slug": "nikkormat-slr-camera",
          "productAsset": {
            "id": "18",
            "preview": "https://demo.vendure.io/assets/preview/95/chuttersnap-324234-unsplash__preview.jpg"
          },
          "priceWithTax": {
            "value": 73800
          },
          "currencyCode": "USD"
        }
      ]
    }
  }
}
```

</TabItem>
</Tabs>

:::info
The `facetValueFilters` input can be used to specify multiple filters, combining each with either `and` or `or`.

For example, to filter by both the "Camera" **and** "Nikkon" facet values, we would use:

```json
{
  "facetValueFilters": [
    { "and": "9" },
    { "and": "11" }
  ]
}
```

To filter by "Nikkon" **or** "Sony", we would use:

```json
{
  "facetValueFilters": [
    { "or": ["11", "15"] }
  ]
}
```
:::

Here's a live example of faceted search. Try searching for terms like "shoe", "plant" or "ball".

<Stackblitz id="vendure-docs-faceted-search"></Stackblitz>

## Listing custom product data

If you have defined custom fields on the `Product` or `ProductVariant` entity, you might want to include these in the
search results. With the [`DefaultSearchPlugin`](/reference/typescript-api/default-search-plugin/) this is
not possible, as this plugin is designed to be a minimal and simple search implementation.

Instead, you can use the [`ElasticsearchPlugin`](/reference/core-plugins/elasticsearch-plugin/) which
provides advanced features which allow you to index custom data. The Elasticsearch plugin is designed as a drop-in
replacement for the `DefaultSearchPlugin`, so you can simply swap out the plugins in your `vendure-config.ts` file.


---

---
title: "Navigation Menu"
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import Stackblitz from '@site/src/components/Stackblitz';

A navigation menu allows your customers to navigate your store and find the products they are looking for.

Typically, navigation is based on a hierarchy of [collections](/guides/core-concepts/collections/). We can get the top-level
collections using the `collections` query with the `topLevelOnly` filter:


<Tabs>
<TabItem value="Query" label="Query" default>

```graphql
query GetTopLevelCollections {
  collections(options: { topLevelOnly: true }) {
    items {
      id
      slug
      name
      featuredAsset {
        id
        preview
      }
    }
  }
}
```

</TabItem>
<TabItem value="Response" label="Response" >

```json
{
  "data": {
    "collections": {
      "items": [
        {
          "id": "2",
          "slug": "electronics",
          "name": "Electronics",
          "featuredAsset": {
            "id": "16",
            "preview": "https://demo.vendure.io/assets/preview/5b/jakob-owens-274337-unsplash__preview.jpg"
          }
        },
        {
          "id": "5",
          "slug": "home-garden",
          "name": "Home & Garden",
          "featuredAsset": {
            "id": "47",
            "preview": "https://demo.vendure.io/assets/preview/3e/paul-weaver-1120584-unsplash__preview.jpg"
          }
        },
        {
          "id": "8",
          "slug": "sports-outdoor",
          "name": "Sports & Outdoor",
          "featuredAsset": {
            "id": "24",
            "preview": "https://demo.vendure.io/assets/preview/96/michael-guite-571169-unsplash__preview.jpg"
          }
        }
      ]
    }
  }
}
```

</TabItem>
</Tabs>

## Building a navigation tree

The `collections` query returns a flat list of collections, but we often want to display them in a tree-like structure.
This way, we can build up a navigation menu which reflects the hierarchy of collections.

First of all we need to ensure that we have the `parentId` property on each collection.

```graphql title="Shop API"
query GetAllCollections {
  collections(options: { topLevelOnly: true }) {
    items {
      id
      slug
      name
      // highlight-next-line
      parentId
      featuredAsset {
        id
        preview
      }
    }
  }
}
```

Then we can use this data to build up a tree structure. The following code snippet shows how this can be done in TypeScript:

```ts title="src/utils/array-to-tree.ts"
export type HasParent = { id: string; parentId: string | null };
export type TreeNode<T extends HasParent> = T & {
    children: Array<TreeNode<T>>;
};
export type RootNode<T extends HasParent> = {
    id?: string;
    children: Array<TreeNode<T>>;
};

/**
 * Builds a tree from an array of nodes which have a parent.
 * Based on https://stackoverflow.com/a/31247960/772859, modified to preserve ordering.
 */
export function arrayToTree<T extends HasParent>(nodes: T[]): RootNode<T> {
    const topLevelNodes: Array<TreeNode<T>> = [];
    const mappedArr: { [id: string]: TreeNode<T> } = {};

    // First map the nodes of the array to an object -> create a hash table.
    for (const node of nodes) {
        mappedArr[node.id] = { ...(node as any), children: [] };
    }

    for (const id of nodes.map((n) => n.id)) {
        if (mappedArr.hasOwnProperty(id)) {
            const mappedElem = mappedArr[id];
            const parentId = mappedElem.parentId;
            if (!parent) {
                continue;
            }
            // If the element is not at the root level, add it to its parent array of children.
            const parentIsRoot = !mappedArr[parentId];
            if (!parentIsRoot) {
                if (mappedArr[parentId]) {
                    mappedArr[parentId].children.push(mappedElem);
                } else {
                    mappedArr[parentId] = { children: [mappedElem] } as any;
                }
            } else {
                topLevelNodes.push(mappedElem);
            }
        }
    }
    const rootId = topLevelNodes.length ? topLevelNodes[0].parentId : undefined;
    return { id: rootId, children: topLevelNodes };
}
```

## Live example

Here's a live demo of the above code in action:

<Stackblitz id='vendure-docs-collection-tree' />


---

---
title: "Order Workflow"
showtoc: true
---

# Order Workflow

An Order is a collection of one or more ProductVariants which can be purchased by a Customer. Orders are represented internally by the [Order entity](/reference/typescript-api/entities/order/) and in the GraphQL API by the [Order type](/reference/graphql-api/admin/enums/#ordertype).

## Order State

Every Order has a `state` property of type [`OrderState`](/reference/typescript-api/orders/order-process/#orderstate). The following diagram shows the default states and how an Order transitions from one to the next.

:::note
Note that this default workflow can be modified to better fit your business processes. See the [Customizing the Order Process guide](/guides/core-concepts/orders/#custom-order-processes).
:::

![./order_state_diagram.png](./order_state_diagram.png)

## Structure of an Order

In Vendure an [Order](/reference/typescript-api/entities/order) consists of one or more [OrderLines](/reference/typescript-api/entities/order-line) (representing a given quantity of a particular SKU).

Here is a simplified diagram illustrating this relationship:

![./order_class_diagram.png](./order_class_diagram.png)

## Shop client order workflow

The [GraphQL Shop API Guide](/guides/storefront/active-order) lists the GraphQL operations you will need to implement this workflow in your storefront client application.

In this section, we'll cover some examples of how these operations would look in your storefront.

### Manipulating the Order

First, let's define a fragment for our Order that we can re-use in subsequent operations:

```graphql
fragment ActiveOrder on Order {
  id
  code
  state
  couponCodes
  subTotalWithTax
  shippingWithTax
  totalWithTax
  totalQuantity
  lines {
    id
    productVariant {
      id
      name
    }
    featuredAsset {
      id
      preview
    }
    quantity
    linePriceWithTax
  }
}
```

Then we can add an item to the Order:

```graphql
mutation AddItemToOrder($productVariantId: ID! $quantity: Int!){
  addItemToOrder(productVariantId: $productVariantId, quantity: $quantity) {
    ... ActiveOrder
    ... on ErrorResult {
      errorCode
      message
    }
  }
}
```

To remove an item from the order

```graphql
mutation RemoveItemFromOrder($orderLineId: ID!){
  removeOrderLine(orderLineId: $orderLineId) {
    ... ActiveOrder
    ... on ErrorResult {
      errorCode
      message
    }
  }
}
```

To alter the quantity of an existing OrderLine

```graphql
mutation AdjustOrderLine($orderLineId: ID! $quantity: Int!){
  adjustOrderLine(orderLineId: $orderLineId, quantity: $quantity) {
    ... ActiveOrder
    ... on ErrorResult {
      errorCode
      message
    }
  }
}
```

At any time we can query the contents of the active Order:

```graphql
query ActiveOrder {
  activeOrder {
    ... ActiveOrder
  }  
}
```

### Checking out

During the checkout process, we'll need to make sure a Customer is assigned to the Order. If the Customer is already signed in, then this can be skipped since Vendure will have already assigned them. If not, then you'd execute:

```graphql
mutation SetCustomerForOrder($input: CreateCustomerInput!){
  setCustomerForOrder(input: $input) {
    ... ActiveOrder
    ... on ErrorResult {
      errorCode
      message
    }
  }
}
```

Then we need to set the shipping address:

```graphql
mutation SetShippingAddress($input: CreateAddressInput!){
  setOrderShippingAddress(input: $input) {
    ... ActiveOrder
    ... on ErrorResult {
      errorCode
      message
    }
  }
}
```

Once the shipping address is set, we can find out which ShippingMethods can be used on this Order:

```graphql
query GetShippingMethods{
  eligibleShippingMethods {
    id
    name
    code
    description
    priceWithTax
  }
}
```

The Customer can then choose one of the available ShippingMethods, and we then set it on the Order:

```graphql
mutation SetShippingMethod($shippingMethodId: ID!){
  setOrderShippingMethod(shippingMethodId: $shippingMethodId) {
    ... ActiveOrder
    ... on ErrorResult {
      errorCode
      message
    }
  }
}
```

We can now do the same for PaymentMethods:

```graphql
query GetPaymentMethods{
  eligiblePaymentMethods {
    id
    name
    code
    description
    isEligible
    eligibilityMessage
  }
}
```

Once the customer is ready to pay, we need to transition the Order to the `ArrangingPayment` state. In this state, no further modifications are permitted. If you _do_ need to modify the Order contents, you can always transition back to the `AddingItems` state:

```graphql
mutation TransitionOrder($state: String!){
  transitionOrderToState(state: $state) {
    ... ActiveOrder
    ... on ErrorResult {
      errorCode
      message
    }
  }
}
```

Finally, add a Payment to the Order:

```graphql
mutation AddPayment($input: PaymentInput!){
  addPaymentToOrder(input: $input) {
    ... ActiveOrder
    ... on ErrorResult {
      errorCode
      message
    }
  }
}
```

If the Payment is successful, the Order will now be complete. You can forward the Customer to a confirmation page using the Order's `code`:

```graphql
query OrderByCode($code: String!) {
  orderByCode(code: $code) {
    ...ActiveOrder
  }
}
```

## ActiveOrderStrategy

In the above examples, the active Order is always associated with the current session and is therefore implicit - which is why there is no need to pass an ID to each of the above operations.

Sometimes you _do_ want to be able to explicitly specify the Order you wish to operate on. In this case, you need to define a custom [ActiveOrderStrategy](/reference/typescript-api/orders/active-order-strategy).


---

---
title: "Product Detail Page"
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import Stackblitz from '@site/src/components/Stackblitz';

The product detail page (often abbreviated to PDP) is the page that shows the details of a product and allows the user to add it to their cart.

Typically, the PDP should include:

- Product name
- Product description
- Available product variants
- Images of the product and its variants
- Price information
- Stock information
- Add to cart button

## Fetching product data

Let's create a query to fetch the required data. You should have either the product's `slug` or `id` available from the
url. We'll use the `slug` in this example.

<Tabs>
<TabItem value="Query" label="Query" default>

```graphql
query GetProductDetail($slug: String!) {
  product(slug: $slug) {
    id
    name
    description
    featuredAsset {
      id
      preview
    }
    assets {
      id
      preview
    }
    variants {
      id
      name
      sku
      stockLevel
      currencyCode
      price
      priceWithTax
      featuredAsset {
        id
        preview
      }
      assets {
        id
        preview
      }
    }
  }
}
```

</TabItem>
<TabItem value="Variables" label="Variables">

```json
{
  "slug": "laptop"
}
```

</TabItem>
<TabItem value="Response" label="Response" >

```json
{
  "data": {
    "product": {
      "id": "1",
      "name": "Laptop",
      "description": "Now equipped with seventh-generation Intel Core processors, Laptop is snappier than ever. From daily tasks like launching apps and opening files to more advanced computing, you can power through your day thanks to faster SSDs and Turbo Boost processing up to 3.6GHz.",
      "featuredAsset": {
        "id": "1",
        "preview": "https://demo.vendure.io/assets/preview/71/derick-david-409858-unsplash__preview.jpg"
      },
      "assets": [
        {
          "id": "1",
          "preview": "https://demo.vendure.io/assets/preview/71/derick-david-409858-unsplash__preview.jpg"
        }
      ],
      "variants": [
        {
          "id": "1",
          "name": "Laptop 13 inch 8GB",
          "sku": "L2201308",
          "stockLevel": "IN_STOCK",
          "currencyCode": "USD",
          "price": 129900,
          "priceWithTax": 155880,
          "featuredAsset": null,
          "assets": []
        },
        {
          "id": "2",
          "name": "Laptop 15 inch 8GB",
          "sku": "L2201508",
          "stockLevel": "IN_STOCK",
          "currencyCode": "USD",
          "price": 139900,
          "priceWithTax": 167880,
          "featuredAsset": null,
          "assets": []
        },
        {
          "id": "3",
          "name": "Laptop 13 inch 16GB",
          "sku": "L2201316",
          "stockLevel": "IN_STOCK",
          "currencyCode": "USD",
          "price": 219900,
          "priceWithTax": 263880,
          "featuredAsset": null,
          "assets": []
        },
        {
          "id": "4",
          "name": "Laptop 15 inch 16GB",
          "sku": "L2201516",
          "stockLevel": "IN_STOCK",
          "currencyCode": "USD",
          "price": 229900,
          "priceWithTax": 275880,
          "featuredAsset": null,
          "assets": []
        }
      ]
    }
  }
}
```


</TabItem>
</Tabs>

This single query provides all the data we need to display our PDP.

## Formatting prices

As explained in the [Money & Currency guide](/guides/core-concepts/money/), the prices are returned as integers in the
smallest unit of the currency (e.g. cents for USD). Therefore, when we display the price, we need to divide by 100 and
format it according to the currency's formatting rules.

In the demo at the end of this guide, we'll use the [`formatCurrency` function](/guides/core-concepts/money/#displaying-monetary-values)
which makes use of the browser's `Intl` API to format the price according to the user's locale.

## Displaying images

If we are using the [`AssetServerPlugin`](/reference/core-plugins/asset-server-plugin/) to serve our product images (as is the default), then we can take advantage
of the dynamic image transformation abilities in order to display the product images in the correct size and in
and optimized format such as WebP.

This is done by appending a query string to the image URL. For example, if we want to use the `'large'` size preset (800 x 800)
and convert the format to WebP, we'd use a url like this:

```tsx
<img src={product.featuredAsset.preview + '?preset=large&format=webp'} />
```

An even more sophisticated approach would be to make use of the HTML [`<picture>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/picture) to provide multiple image sources
so that the browser can select the optimal format. This can be wrapped in a component to make it easier to use. For example:

```tsx title="src/components/VendureAsset.tsx"
interface VendureAssetProps {
    preview: string;
    preset: 'tiny' | 'thumb' | 'small' | 'medium' | 'large';
    alt: string;
}

export function VendureAsset({ preview, preset, alt }: VendureAssetProps) {
    return (
        <picture>
            <source type="image/avif" srcSet={preview + `?preset=${preset}&format=avif`} />
            <source type="image/webp" srcSet={preview + `?preset=${preset}&format=webp`} />
            <img src={preview + `?preset=${preset}&format=jpg`} alt={alt} />
        </picture>
    );
}
```

## Adding to the order

To add a particular product variant to the order, we need to call the [`addItemToOrder`](/reference/graphql-api/shop/mutations/#additemtoorder) mutation.
This mutation takes the `productVariantId` and the `quantity` as arguments.


<Tabs>
<TabItem value="Mutation" label="Mutation" default>

```graphql
mutation AddItemToOrder($variantId: ID!, $quantity: Int!) {
  addItemToOrder(productVariantId: $variantId, quantity: $quantity) {
    __typename
    ...UpdatedOrder
    ... on ErrorResult {
      errorCode
      message
    }
    ... on InsufficientStockError {
      quantityAvailable
      order {
        ...UpdatedOrder
      }
    }
  }
}

fragment UpdatedOrder on Order {
  id
  code
  state
  totalQuantity
  totalWithTax
  currencyCode
  lines {
    id
    unitPriceWithTax
    quantity
    linePriceWithTax
    productVariant {
      id
      name
    }
  }
}
```

</TabItem>
<TabItem value="Variables" label="Variables">

```json
{
  "variantId": "4",
  "quantity": 1
}
```

</TabItem>
<TabItem value="Response" label="Response" >

```json
{
  "data": {
    "addItemToOrder": {
      "__typename": "Order",
      "id": "5",
      "code": "KE5FJPVV3Y3LX134",
      "state": "AddingItems",
      "totalQuantity": 1,
      "totalWithTax": 275880,
      "lines": [
        {
          "id": "14",
          "unitPriceWithTax": 275880,
          "quantity": 1,
          "linePriceWithTax": 275880
        }
      ]
    }
  }
}
```

</TabItem>
</Tabs>

There are some important things to note about this mutation:

- Because the `addItemToOrder` mutation returns a union type, we need to use a [fragment](/guides/getting-started/graphql-intro/#fragments) to specify the fields we want to return.
In this case we have defined a fragment called `UpdatedOrder` which contains the fields we are interested in.
- If any [expected errors](/guides/developer-guide/error-handling/) occur, the mutation will return an `ErrorResult` object. We'll be able to
see the `errorCode` and `message` fields in the response, so that we can display a meaningful error message to the user.
- In the special case of the `InsufficientStockError`, in addition to the `errorCode` and `message` fields, we also get the `quantityAvailable` field
which tells us how many of the requested quantity are available (and have been added to the order). This is useful information to display to the user.
The `InsufficientStockError` object also embeds the updated `Order` object, which we can use to update the UI.
- The `__typename` field can be used by the client to determine which type of object has been returned. Its value will equal the name
of the returned type. This means that we can check whether `__typename === 'Order'` in order to determine whether the mutation was successful.

## Live example

Here's an example that brings together all of the above concepts:

<Stackblitz id="vendure-docs-product-detail" />


---

---
title: "Storefront Starters"
---

Since building an entire Storefront from scratch can be a daunting task, we have prepared a few starter projects that you can use as a base for your own storefront.

These starters provide basic functionality including:

- Product listing
- Product details
- Search with facets
- Cart functionality
- Checkout flow
- Account management
- Styling with Tailwind

The idea is that you clone the starter project and then customize it to your needs.

:::note
Prefer to build your own solution? Follow the rest of the guides in this section to learn how to build a Storefront from scratch.
:::

## Remix Storefront

- 🔗 [remix-storefront.vendure.io](https://remix-storefront.vendure.io/)
- 💻 [github.com/vendure-ecommerce/storefront-remix-starter](https://github.com/vendure-ecommerce/storefront-remix-starter)

[Remix](https://remix.run/) is a React-based full-stack JavaScript framework which focuses on web standards, modern web app UX, and which helps you build better websites.

Our official Remix Storefront starter provides you with a lightning-fast, modern storefront solution which can be deployed to any of the popular cloud providers like Vercel, Netlify, or Cloudflare Pages.

![Remix Storefront](./remix-storefront.webp)

## Qwik Storefront

- 🔗 [qwik-storefront.vendure.io](https://qwik-storefront.vendure.io/)
- 💻 [github.com/vendure-ecommerce/storefront-qwik-starter](https://github.com/vendure-ecommerce/storefront-qwik-starter)

[Qwik](https://qwik.builder.io/) is a cutting-edge web framework that offers unmatched performance.

Our official Qwik Storefront starter provides you with a lightning-fast, modern storefront solution which can be deployed to any of the popular cloud providers like Vercel, Netlify, or Cloudflare Pages.

![Qwik Storefront](./qwik-storefront.webp)

## Angular Storefront

- 🔗 [angular-storefront.vendure.io](https://angular-storefront.vendure.io/)
- 💻 [github.com/vendure-ecommerce/storefront-angular-starter](https://github.com/vendure-ecommerce/storefront-angular-starter)

[Angular](https://angular.io/) is a popular, stable, enterprise-grade framework made by Google.

Our official Angular Storefront starter is a modern Progressive Web App that uses Angular Universal server-side rendering.

![Angular Storefront](./angular-storefront.webp)



---

---
title: "ActionBarContext"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ActionBarContext

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/providers/nav-builder/nav-builder-types.ts" sourceLine="90" packageName="@vendure/admin-ui" />

Providers & data available to the `onClick` & `buttonState` functions of an <a href='/reference/admin-ui-api/action-bar/action-bar-item#actionbaritem'>ActionBarItem</a>,
<a href='/reference/admin-ui-api/action-bar/action-bar-dropdown-menu-item#actionbardropdownmenuitem'>ActionBarDropdownMenuItem</a> or <a href='/reference/admin-ui-api/nav-menu/nav-menu-item#navmenuitem'>NavMenuItem</a>.

```ts title="Signature"
interface ActionBarContext {
    route: ActivatedRoute;
    injector: Injector;
    dataService: DataService;
    notificationService: NotificationService;
    entity$: Observable<Record<string, any> | undefined>;
}
```

<div className="members-wrapper">

### route

<MemberInfo kind="property" type={`ActivatedRoute`}   />

The router's [ActivatedRoute](https://angular.dev/guide/routing/router-reference#activated-route) object for
the current route. This object contains information about the route, its parameters, and additional data
associated with the route.
### injector

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/injector#injector'>Injector</a>`}   />

The Angular [Injector](https://angular.dev/api/core/Injector) which can be used to get instances
of services and other providers available in the application.
### dataService

<MemberInfo kind="property" type={`<a href='/reference/admin-ui-api/services/data-service#dataservice'>DataService</a>`}   />

The [DataService](/reference/admin-ui-api/services/data-service), which provides methods for querying the
server-side data.
### notificationService

<MemberInfo kind="property" type={`<a href='/reference/admin-ui-api/services/notification-service#notificationservice'>NotificationService</a>`}   />

The [NotificationService](/reference/admin-ui-api/services/notification-service), which provides methods for
displaying notifications to the user.
### entity$

<MemberInfo kind="property" type={`Observable&#60;Record&#60;string, any&#62; | undefined&#62;`}  since="2.2.0"  />

An observable of the current entity in a detail view. In a list view the observable will not emit any values.

*Example*

```ts
addActionBarDropdownMenuItem({
    id: 'print-invoice',
    locationId: 'order-detail',
    label: 'Print Invoice',
    icon: 'printer',
    buttonState: context => {
        // highlight-start
        return context.entity$.pipe(
            map((order) => {
                return order?.state === 'PaymentSettled'
                    ? { disabled: false, visible: true }
                    : { disabled: true, visible: true };
            }),
        );
        // highlight-end
    },
    requiresPermission: ['UpdateOrder'],
}),
```


</div>


---

---
title: "ActionBarDropdownMenuItem"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ActionBarDropdownMenuItem

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/providers/nav-builder/nav-builder-types.ts" sourceLine="227" packageName="@vendure/admin-ui" since="2.2.0" />

A dropdown menu item in the ActionBar area at the top of one of the list or detail views.

```ts title="Signature"
interface ActionBarDropdownMenuItem {
    id: string;
    label: string;
    locationId: ActionBarLocationId;
    hasDivider?: boolean;
    buttonState?: (context: ActionBarContext) => Observable<ActionBarButtonState | undefined>;
    onClick?: (event: MouseEvent, context: ActionBarContext) => void;
    routerLink?: RouterLinkDefinition;
    icon?: string;
    requiresPermission?: string | string[];
}
```

<div className="members-wrapper">

### id

<MemberInfo kind="property" type={`string`}   />

A unique identifier for the item.
### label

<MemberInfo kind="property" type={`string`}   />

The label to display for the item. This can also be a translation token,
e.g. `invoice-plugin.print-invoice`.
### locationId

<MemberInfo kind="property" type={`<a href='/reference/admin-ui-api/action-bar/action-bar-location-id#actionbarlocationid'>ActionBarLocationId</a>`}   />

The location in the UI where this menu item should be displayed.
### hasDivider

<MemberInfo kind="property" type={`boolean`}   />

Whether to render a divider above this item.
### buttonState

<MemberInfo kind="property" type={`(context: <a href='/reference/admin-ui-api/action-bar/action-bar-context#actionbarcontext'>ActionBarContext</a>) =&#62; Observable&#60;ActionBarButtonState | undefined&#62;`}   />

A function which returns an observable of the button state, allowing you to
dynamically enable/disable or show/hide the button.
### onClick

<MemberInfo kind="property" type={`(event: MouseEvent, context: <a href='/reference/admin-ui-api/action-bar/action-bar-context#actionbarcontext'>ActionBarContext</a>) =&#62; void`}   />


### routerLink

<MemberInfo kind="property" type={`<a href='/reference/admin-ui-api/action-bar/router-link-definition#routerlinkdefinition'>RouterLinkDefinition</a>`}   />


### icon

<MemberInfo kind="property" type={`string`}   />

An optional icon to display with the item. The icon
should be a valid shape name from the [Clarity Icons](https://core.clarity.design/foundation/icons/shapes/)
set.
### requiresPermission

<MemberInfo kind="property" type={`string | string[]`}   />

Control the display of this item based on the user permissions. Note: if you attempt to pass a
<a href='/reference/typescript-api/auth/permission-definition#permissiondefinition'>PermissionDefinition</a> object, you will get a compilation error. Instead, pass the plain
string version. For example, if the permission is defined as:

```ts
export const MyPermission = new PermissionDefinition('ProductReview');
```
then the generated permission strings will be:

- `CreateProductReview`
- `ReadProductReview`
- `UpdateProductReview`
- `DeleteProductReview`


</div>


---

---
title: "ActionBarItem"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ActionBarItem

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/providers/nav-builder/nav-builder-types.ts" sourceLine="158" packageName="@vendure/admin-ui" />

A button in the ActionBar area at the top of one of the list or detail views.

```ts title="Signature"
interface ActionBarItem {
    id: string;
    label: string;
    locationId: ActionBarLocationId;
    disabled?: Observable<boolean>;
    buttonState?: (context: ActionBarContext) => Observable<ActionBarButtonState>;
    onClick?: (event: MouseEvent, context: ActionBarContext) => void;
    routerLink?: RouterLinkDefinition;
    buttonColor?: 'primary' | 'success' | 'warning';
    buttonStyle?: 'solid' | 'outline' | 'link';
    icon?: string;
    requiresPermission?: string | string[];
}
```

<div className="members-wrapper">

### id

<MemberInfo kind="property" type={`string`}   />

A unique identifier for the item.
### label

<MemberInfo kind="property" type={`string`}   />

The label to display for the item. This can also be a translation token,
e.g. `invoice-plugin.print-invoice`.
### locationId

<MemberInfo kind="property" type={`<a href='/reference/admin-ui-api/action-bar/action-bar-location-id#actionbarlocationid'>ActionBarLocationId</a>`}   />

The location in the UI where this button should be displayed.
### disabled

<MemberInfo kind="property" type={`Observable&#60;boolean&#62;`}   />

Deprecated since v2.1.0 - use `buttonState` instead.
### buttonState

<MemberInfo kind="property" type={`(context: <a href='/reference/admin-ui-api/action-bar/action-bar-context#actionbarcontext'>ActionBarContext</a>) =&#62; Observable&#60;ActionBarButtonState&#62;`}  since="2.1.0"  />

A function which returns an observable of the button state, allowing you to
dynamically enable/disable or show/hide the button.
### onClick

<MemberInfo kind="property" type={`(event: MouseEvent, context: <a href='/reference/admin-ui-api/action-bar/action-bar-context#actionbarcontext'>ActionBarContext</a>) =&#62; void`}   />


### routerLink

<MemberInfo kind="property" type={`<a href='/reference/admin-ui-api/action-bar/router-link-definition#routerlinkdefinition'>RouterLinkDefinition</a>`}   />


### buttonColor

<MemberInfo kind="property" type={`'primary' | 'success' | 'warning'`}   />


### buttonStyle

<MemberInfo kind="property" type={`'solid' | 'outline' | 'link'`}   />


### icon

<MemberInfo kind="property" type={`string`}   />

An optional icon to display in the button. The icon
should be a valid shape name from the [Clarity Icons](https://core.clarity.design/foundation/icons/shapes/)
set.
### requiresPermission

<MemberInfo kind="property" type={`string | string[]`}   />

Control the display of this item based on the user permissions. Note: if you attempt to pass a
<a href='/reference/typescript-api/auth/permission-definition#permissiondefinition'>PermissionDefinition</a> object, you will get a compilation error. Instead, pass the plain
string version. For example, if the permission is defined as:

```ts
export const MyPermission = new PermissionDefinition('ProductReview');
```

then the generated permission strings will be:

- `CreateProductReview`
- `ReadProductReview`
- `UpdateProductReview`
- `DeleteProductReview`


</div>


---

---
title: "ActionBarLocationId"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ActionBarLocationId

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/common/component-registry-types.ts" sourceLine="107" packageName="@vendure/admin-ui" />

The valid locationIds for registering action bar items. For a list of
values, see <a href='/reference/admin-ui-api/action-bar/page-location-id#pagelocationid'>PageLocationId</a>.

```ts title="Signature"
type ActionBarLocationId = PageLocationId
```


---

---
title: "AddActionBarDropdownMenuItem"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## addActionBarDropdownMenuItem

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/extension/add-action-bar-dropdown-menu-item.ts" sourceLine="27" packageName="@vendure/admin-ui" since="2.2.0" />

Adds a dropdown menu item to the ActionBar at the top right of each list or detail view. The locationId can
be determined by pressing `ctrl + u` when running the Admin UI in dev mode.

*Example*

```ts title="providers.ts"
import { addActionBarDropdownMenuItem } from '@vendure/admin-ui/core';

export default [
    addActionBarDropdownMenuItem({
        id: 'print-invoice',
        label: 'Print Invoice',
        locationId: 'order-detail',
        routerLink: ['/extensions/invoicing'],
    }),
];
```

```ts title="Signature"
function addActionBarDropdownMenuItem(config: ActionBarDropdownMenuItem): void
```
Parameters

### config

<MemberInfo kind="parameter" type={`<a href='/reference/admin-ui-api/action-bar/action-bar-dropdown-menu-item#actionbardropdownmenuitem'>ActionBarDropdownMenuItem</a>`} />



---

---
title: "AddActionBarItem"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## addActionBarItem

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/extension/add-action-bar-item.ts" sourceLine="23" packageName="@vendure/admin-ui" />

Adds a button to the ActionBar at the top right of each list or detail view. The locationId can
be determined by pressing `ctrl + u` when running the Admin UI in dev mode.

*Example*

```ts title="providers.ts"
export default [
    addActionBarItem({
        id: 'print-invoice',
        label: 'Print Invoice',
        locationId: 'order-detail',
        routerLink: ['/extensions/invoicing'],
    }),
];
```

```ts title="Signature"
function addActionBarItem(config: ActionBarItem): void
```
Parameters

### config

<MemberInfo kind="parameter" type={`<a href='/reference/admin-ui-api/action-bar/action-bar-item#actionbaritem'>ActionBarItem</a>`} />



---

---
title: "Action Bar"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "PageLocationId"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## PageLocationId

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/common/component-registry-types.ts" sourceLine="52" packageName="@vendure/admin-ui" />

The valid locationIds for registering action bar items or tabs.

```ts title="Signature"
type PageLocationId = | 'administrator-detail'
    | 'administrator-list'
    | 'asset-detail'
    | 'asset-list'
    | 'channel-detail'
    | 'channel-list'
    | 'collection-detail'
    | 'collection-list'
    | 'country-detail'
    | 'country-list'
    | 'customer-detail'
    | 'customer-list'
    | 'customer-group-list'
    | 'customer-group-detail'
    | 'draft-order-detail'
    | 'facet-detail'
    | 'facet-list'
    | 'global-setting-detail'
    | 'system-status'
    | 'job-list'
    | 'order-detail'
    | 'order-list'
    | 'modify-order'
    | 'payment-method-detail'
    | 'payment-method-list'
    | 'product-detail'
    | 'product-list'
    | 'product-variant-detail'
    | 'product-variant-list'
    | 'profile'
    | 'promotion-detail'
    | 'promotion-list'
    | 'role-detail'
    | 'role-list'
    | 'seller-detail'
    | 'seller-list'
    | 'shipping-method-detail'
    | 'shipping-method-list'
    | 'stock-location-detail'
    | 'stock-location-list'
    | 'tax-category-detail'
    | 'tax-category-list'
    | 'tax-rate-detail'
    | 'tax-rate-list'
    | 'zone-detail'
    | 'zone-list'
```


---

---
title: "RouterLinkDefinition"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## RouterLinkDefinition

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/providers/nav-builder/nav-builder-types.ts" sourceLine="289" packageName="@vendure/admin-ui" />

A function which returns the router link for an <a href='/reference/admin-ui-api/action-bar/action-bar-item#actionbaritem'>ActionBarItem</a> or <a href='/reference/admin-ui-api/nav-menu/nav-menu-item#navmenuitem'>NavMenuItem</a>.

```ts title="Signature"
type RouterLinkDefinition = ((route: ActivatedRoute, context: ActionBarContext) => any[]) | any[]
```


---

---
title: "AlertConfig"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## AlertConfig

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/providers/alerts/alerts.service.ts" sourceLine="63" packageName="@vendure/admin-ui" since="2.2.0" />

A configuration object for an Admin UI alert.

```ts title="Signature"
interface AlertConfig<T = any> {
    id: string;
    check: (context: AlertContext) => T | Promise<T> | Observable<T>;
    recheck?: (context: AlertContext) => Observable<any>;
    isAlert: (data: T, context: AlertContext) => boolean;
    action: (data: T, context: AlertContext) => void;
    label: (
        data: T,
        context: AlertContext,
    ) => { text: string; translationVars?: { [key: string]: string | number } };
    requiredPermissions?: Permission[];
}
```

<div className="members-wrapper">

### id

<MemberInfo kind="property" type={`string`}   />

A unique identifier for the alert.
### check

<MemberInfo kind="property" type={`(context: <a href='/reference/admin-ui-api/alerts/alert-context#alertcontext'>AlertContext</a>) =&#62; T | Promise&#60;T&#62; | Observable&#60;T&#62;`}   />

A function which is gets the data used to determine whether the alert should be shown.
Typically, this function will query the server or some other remote data source.

This function will be called once when the Admin UI app bootstraps, and can be also
set to run at regular intervals by setting the `recheckIntervalMs` property.
### recheck

<MemberInfo kind="property" type={`(context: <a href='/reference/admin-ui-api/alerts/alert-context#alertcontext'>AlertContext</a>) =&#62; Observable&#60;any&#62;`} default={`undefined`}   />

A function which returns an Observable which is used to determine when to re-run the `check`
function. Whenever the observable emits, the `check` function will be called again.

A basic time-interval-based recheck can be achieved by using the `interval` function from RxJS.

*Example*

```ts
import { interval } from 'rxjs';

// ...
recheck: () => interval(60_000)
```

If this is not set, the `check` function will only be called once when the Admin UI app bootstraps.
### isAlert

<MemberInfo kind="property" type={`(data: T, context: <a href='/reference/admin-ui-api/alerts/alert-context#alertcontext'>AlertContext</a>) =&#62; boolean`}   />

A function which determines whether the alert should be shown based on the data returned by the `check`
function.
### action

<MemberInfo kind="property" type={`(data: T, context: <a href='/reference/admin-ui-api/alerts/alert-context#alertcontext'>AlertContext</a>) =&#62; void`}   />

A function which is called when the alert is clicked in the Admin UI.
### label

<MemberInfo kind="property" type={`(         data: T,         context: <a href='/reference/admin-ui-api/alerts/alert-context#alertcontext'>AlertContext</a>,     ) =&#62; { text: string; translationVars?: { [key: string]: string | number } }`}   />

A function which returns the text used in the UI to describe the alert.
### requiredPermissions

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/permission#permission'>Permission</a>[]`}   />

A list of permissions which the current Administrator must have in order. If the current
Administrator does not have these permissions, none of the other alert functions will be called.


</div>


---

---
title: "AlertContext"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## AlertContext

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/providers/alerts/alerts.service.ts" sourceLine="29" packageName="@vendure/admin-ui" since="2.2.0" />

The context object which is passed to the `check`, `isAlert`, `label` and `action` functions of an
<a href='/reference/admin-ui-api/alerts/alert-config#alertconfig'>AlertConfig</a> object.

```ts title="Signature"
interface AlertContext {
    injector: Injector;
    dataService: DataService;
    notificationService: NotificationService;
    modalService: ModalService;
}
```

<div className="members-wrapper">

### injector

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/injector#injector'>Injector</a>`}   />

The Angular [Injector](https://angular.dev/api/core/Injector) which can be used to get instances
of services and other providers available in the application.
### dataService

<MemberInfo kind="property" type={`<a href='/reference/admin-ui-api/services/data-service#dataservice'>DataService</a>`}   />

The [DataService](/reference/admin-ui-api/services/data-service), which provides methods for querying the
server-side data.
### notificationService

<MemberInfo kind="property" type={`<a href='/reference/admin-ui-api/services/notification-service#notificationservice'>NotificationService</a>`}   />

The [NotificationService](/reference/admin-ui-api/services/notification-service), which provides methods for
displaying notifications to the user.
### modalService

<MemberInfo kind="property" type={`<a href='/reference/admin-ui-api/services/modal-service#modalservice'>ModalService</a>`}   />

The [ModalService](/reference/admin-ui-api/services/modal-service), which provides methods for
opening modal dialogs.


</div>


---

---
title: "Alerts"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "RegisterAlert"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## registerAlert

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/extension/register-alert.ts" sourceLine="12" packageName="@vendure/admin-ui" since="2.2.0" />

Registers an alert which can be displayed in the Admin UI alert dropdown in the top bar.
The alert is configured using the <a href='/reference/admin-ui-api/alerts/alert-config#alertconfig'>AlertConfig</a> object.

```ts title="Signature"
function registerAlert(config: AlertConfig): void
```
Parameters

### config

<MemberInfo kind="parameter" type={`<a href='/reference/admin-ui-api/alerts/alert-config#alertconfig'>AlertConfig</a>`} />



---

---
title: "BulkAction"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## BulkAction

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/providers/bulk-action-registry/bulk-action-types.ts" sourceLine="99" packageName="@vendure/admin-ui" since="1.8.0" />

Configures a bulk action which can be performed on all selected items in a list view.

For a full example, see the <a href='/reference/admin-ui-api/bulk-actions/register-bulk-action#registerbulkaction'>registerBulkAction</a> docs.

```ts title="Signature"
interface BulkAction<ItemType = any, ComponentType = any> {
    location: BulkActionLocationId;
    label: string;
    getTranslationVars?: (
        context: BulkActionFunctionContext<ItemType, ComponentType>,
    ) => Record<string, string | number> | Promise<Record<string, string | number>>;
    icon?: string;
    iconClass?: string;
    onClick: (context: BulkActionClickContext<ItemType, ComponentType>) => void;
    isVisible?: (context: BulkActionFunctionContext<ItemType, ComponentType>) => boolean | Promise<boolean>;
    requiresPermission?: string | ((userPermissions: string[]) => boolean);
}
```

<div className="members-wrapper">

### location

<MemberInfo kind="property" type={`<a href='/reference/admin-ui-api/bulk-actions/bulk-action#bulkactionlocationid'>BulkActionLocationId</a>`}   />


### label

<MemberInfo kind="property" type={`string`}   />


### getTranslationVars

<MemberInfo kind="property" type={`(         context: <a href='/reference/admin-ui-api/bulk-actions/bulk-action#bulkactionfunctioncontext'>BulkActionFunctionContext</a>&#60;ItemType, ComponentType&#62;,     ) =&#62; Record&#60;string, string | number&#62; | Promise&#60;Record&#60;string, string | number&#62;&#62;`}   />

An optional function that should resolve to a map of translation variables which can be
used when translating the `label` string.
### icon

<MemberInfo kind="property" type={`string`}   />

A valid [Clarity Icons](https://core.clarity.design/foundation/icons/shapes/) icon shape, e.g.
"cog", "user", "info-standard".
### iconClass

<MemberInfo kind="property" type={`string`}   />

A class to be added to the icon element. Examples:

- is-success
- is-danger
- is-warning
- is-info
- is-highlight
### onClick

<MemberInfo kind="property" type={`(context: <a href='/reference/admin-ui-api/bulk-actions/bulk-action#bulkactionclickcontext'>BulkActionClickContext</a>&#60;ItemType, ComponentType&#62;) =&#62; void`}   />

Defines the logic that executes when the bulk action button is clicked.
### isVisible

<MemberInfo kind="property" type={`(context: <a href='/reference/admin-ui-api/bulk-actions/bulk-action#bulkactionfunctioncontext'>BulkActionFunctionContext</a>&#60;ItemType, ComponentType&#62;) =&#62; boolean | Promise&#60;boolean&#62;`}   />

A function that determines whether this bulk action item should be displayed in the menu.
If not defined, the item will always be displayed.

This function will be invoked each time the selection is changed, so try to avoid expensive code
running here.

*Example*

```ts
import { registerBulkAction, DataService } from '@vendure/admin-ui/core';

registerBulkAction({
  location: 'product-list',
  label: 'Assign to channel',
  // Only display this action if there are multiple channels
  isVisible: ({ injector }) => injector.get(DataService).client
    .userStatus()
    .mapSingle(({ userStatus }) => 1 < userStatus.channels.length)
    .toPromise(),
  // ...
});
```
### requiresPermission

<MemberInfo kind="property" type={`string | ((userPermissions: string[]) =&#62; boolean)`}   />

Control the display of this item based on the user permissions.

*Example*

```ts
registerBulkAction({
  // Can be specified as a simple string
  requiresPermission: Permission.UpdateProduct,

  // Or as a function that returns a boolean if permissions are satisfied
  requiresPermission: userPermissions =>
    userPermissions.includes(Permission.UpdateCatalog) ||
    userPermissions.includes(Permission.UpdateProduct),
  // ...
})
```


</div>


## BulkActionLocationId

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/providers/bulk-action-registry/bulk-action-types.ts" sourceLine="12" packageName="@vendure/admin-ui" since="1.8.0" />

A valid location of a list view that supports the bulk actions API.

```ts title="Signature"
type BulkActionLocationId = | 'product-list'
    | 'facet-list'
    | 'collection-list'
    | 'customer-list'
    | 'customer-group-list'
    | 'customer-group-members-list'
    | 'customer-group-members-picker-list'
    | 'promotion-list'
    | 'seller-list'
    | 'channel-list'
    | 'administrator-list'
    | 'role-list'
    | 'shipping-method-list'
    | 'stock-location-list'
    | 'payment-method-list'
    | 'tax-category-list'
    | 'tax-rate-list'
    | 'zone-list'
    | 'zone-members-list'
    | string
```


## BulkActionFunctionContext

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/providers/bulk-action-registry/bulk-action-types.ts" sourceLine="43" packageName="@vendure/admin-ui" since="1.8.0" />

This is the argument which gets passed to the `getTranslationVars` and `isVisible` functions
of the BulkAction definition.

```ts title="Signature"
interface BulkActionFunctionContext<ItemType, ComponentType> {
    selection: ItemType[];
    hostComponent: ComponentType;
    injector: Injector;
    route: ActivatedRoute;
}
```

<div className="members-wrapper">

### selection

<MemberInfo kind="property" type={`ItemType[]`}   />

An array of the selected items from the list.
### hostComponent

<MemberInfo kind="property" type={`ComponentType`}   />

The component instance that is hosting the list view. For instance,
`ProductListComponent`. This can be used to call methods on the instance,
e.g. calling `hostComponent.refresh()` to force a list refresh after
deleting the selected items.
### injector

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/injector#injector'>Injector</a>`}   />

The Angular [Injector](https://angular.io/api/core/Injector) which can be used
to get service instances which might be needed in the click handler.
### route

<MemberInfo kind="property" type={`ActivatedRoute`}   />




</div>


## BulkActionClickContext

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/providers/bulk-action-registry/bulk-action-types.ts" sourceLine="74" packageName="@vendure/admin-ui" since="1.8.0" />

This is the argument which gets passed to the `onClick` function of a BulkAction.

```ts title="Signature"
interface BulkActionClickContext<ItemType, ComponentType> extends BulkActionFunctionContext<ItemType, ComponentType> {
    clearSelection: () => void;
    event: MouseEvent;
}
```
* Extends: <code><a href='/reference/admin-ui-api/bulk-actions/bulk-action#bulkactionfunctioncontext'>BulkActionFunctionContext</a>&#60;ItemType, ComponentType&#62;</code>



<div className="members-wrapper">

### clearSelection

<MemberInfo kind="property" type={`() =&#62; void`}   />

Clears the selection in the active list view.
### event

<MemberInfo kind="property" type={`MouseEvent`}   />

The click event itself.


</div>


---

---
title: "Bulk Actions"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "RegisterBulkAction"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## registerBulkAction

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/extension/register-bulk-action.ts" sourceLine="52" packageName="@vendure/admin-ui" since="1.8.0" />

Registers a custom <a href='/reference/admin-ui-api/bulk-actions/bulk-action#bulkaction'>BulkAction</a> which can be invoked from the bulk action menu
of any supported list view.

This allows you to provide custom functionality that can operate on any of the selected
items in the list view.

In this example, imagine we have an integration with a 3rd-party text translation service. This
bulk action allows us to select multiple products from the product list view, and send them for
translation via a custom service which integrates with the translation service's API.

*Example*

```ts title="providers.ts"
import { ModalService, registerBulkAction, SharedModule } from '@vendure/admin-ui/core';
import { ProductDataTranslationService } from './product-data-translation.service';

export default [
    ProductDataTranslationService,
    registerBulkAction({
        location: 'product-list',
        label: 'Send to translation service',
        icon: 'language',
        onClick: ({ injector, selection }) => {
            const modalService = injector.get(ModalService);
            const translationService = injector.get(ProductDataTranslationService);
            modalService
                .dialog({
                    title: `Send ${selection.length} products for translation?`,
                    buttons: [
                        { type: 'secondary', label: 'cancel' },
                        { type: 'primary', label: 'send', returnValue: true },
                    ],
                })
                .subscribe(response => {
                    if (response) {
                        translationService.sendForTranslation(selection.map(item => item.productId));
                    }
                });
        },
    }),
];
```

```ts title="Signature"
function registerBulkAction(bulkAction: BulkAction): void
```
Parameters

### bulkAction

<MemberInfo kind="parameter" type={`<a href='/reference/admin-ui-api/bulk-actions/bulk-action#bulkaction'>BulkAction</a>`} />



---

---
title: "AssetPickerDialogComponent"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## AssetPickerDialogComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/components/asset-picker-dialog/asset-picker-dialog.component.ts" sourceLine="51" packageName="@vendure/admin-ui" />

A dialog which allows the creation and selection of assets.

*Example*

```ts
selectAssets() {
  this.modalService
    .fromComponent(AssetPickerDialogComponent, {
        size: 'xl',
    })
    .subscribe(result => {
        if (result && result.length) {
            // ...
        }
    });
}
```

```ts title="Signature"
class AssetPickerDialogComponent implements OnInit, AfterViewInit, OnDestroy, Dialog<Asset[]> {
    assets$: Observable<AssetLike[]>;
    allTags$: Observable<TagFragment[]>;
    paginationConfig: PaginationInstance = {
        currentPage: 1,
        itemsPerPage: 25,
        totalItems: 1,
    };
    multiSelect = true;
    initialTags: string[] = [];
    resolveWith: (result?: Asset[]) => void;
    selection: Asset[] = [];
    searchTerm$ = new BehaviorSubject<string | undefined>(undefined);
    filterByTags$ = new BehaviorSubject<TagFragment[] | undefined>(undefined);
    uploading = false;
    constructor(dataService: DataService, notificationService: NotificationService)
    ngOnInit() => ;
    ngAfterViewInit() => ;
    ngOnDestroy() => void;
    pageChange(page: number) => ;
    itemsPerPageChange(itemsPerPage: number) => ;
    cancel() => ;
    select() => ;
    createAssets(files: File[]) => ;
}
```
* Implements: <code>OnInit</code>, <code>AfterViewInit</code>, <code>OnDestroy</code>, <code><a href='/reference/admin-ui-api/services/modal-service#dialog'>Dialog</a>&#60;<a href='/reference/typescript-api/entities/asset#asset'>Asset</a>[]&#62;</code>



<div className="members-wrapper">

### assets$

<MemberInfo kind="property" type={`Observable&#60;AssetLike[]&#62;`}   />


### allTags$

<MemberInfo kind="property" type={`Observable&#60;TagFragment[]&#62;`}   />


### paginationConfig

<MemberInfo kind="property" type={`PaginationInstance`}   />


### multiSelect

<MemberInfo kind="property" type={``}   />


### initialTags

<MemberInfo kind="property" type={`string[]`}   />


### resolveWith

<MemberInfo kind="property" type={`(result?: <a href='/reference/typescript-api/entities/asset#asset'>Asset</a>[]) =&#62; void`}   />


### selection

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/asset#asset'>Asset</a>[]`}   />


### searchTerm$

<MemberInfo kind="property" type={``}   />


### filterByTags$

<MemberInfo kind="property" type={``}   />


### uploading

<MemberInfo kind="property" type={``}   />


### constructor

<MemberInfo kind="method" type={`(dataService: <a href='/reference/admin-ui-api/services/data-service#dataservice'>DataService</a>, notificationService: <a href='/reference/admin-ui-api/services/notification-service#notificationservice'>NotificationService</a>) => AssetPickerDialogComponent`}   />


### ngOnInit

<MemberInfo kind="method" type={`() => `}   />


### ngAfterViewInit

<MemberInfo kind="method" type={`() => `}   />


### ngOnDestroy

<MemberInfo kind="method" type={`() => void`}   />


### pageChange

<MemberInfo kind="method" type={`(page: number) => `}   />


### itemsPerPageChange

<MemberInfo kind="method" type={`(itemsPerPage: number) => `}   />


### cancel

<MemberInfo kind="method" type={`() => `}   />


### select

<MemberInfo kind="method" type={`() => `}   />


### createAssets

<MemberInfo kind="method" type={`(files: File[]) => `}   />




</div>


---

---
title: "ChipComponent"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ChipComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/components/chip/chip.component.ts" sourceLine="16" packageName="@vendure/admin-ui" />

A chip component for displaying a label with an optional action icon.

*Example*

```HTML
<vdr-chip [colorFrom]="item.value"
          icon="close"
          (iconClick)="clear(item)">
{{ item.value }}</vdr-chip>
```

```ts title="Signature"
class ChipComponent {
    @Input() icon: string;
    @Input() invert = false;
    @Input() colorFrom = '';
    @Input() colorType: 'error' | 'success' | 'warning';
    @Output() iconClick = new EventEmitter<MouseEvent>();
}
```

<div className="members-wrapper">

### icon

<MemberInfo kind="property" type={`string`}   />

The icon should be the name of one of the available Clarity icons: https://clarity.design/foundation/icons/shapes/
### invert

<MemberInfo kind="property" type={``}   />


### colorFrom

<MemberInfo kind="property" type={``}   />

If set, the chip will have an auto-generated background
color based on the string value passed in.
### colorType

<MemberInfo kind="property" type={`'error' | 'success' | 'warning'`}   />

The color of the chip can also be one of the standard status colors.
### iconClick

<MemberInfo kind="property" type={``}   />




</div>


---

---
title: "CurrencyInputComponent"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## CurrencyInputComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/components/currency-input/currency-input.component.ts" sourceLine="33" packageName="@vendure/admin-ui" />

A form input control which displays currency in decimal format, whilst working
with the integer cent value in the background.

*Example*

```HTML
<vdr-currency-input
    [(ngModel)]="entityPrice"
    [currencyCode]="currencyCode"
></vdr-currency-input>
```

```ts title="Signature"
class CurrencyInputComponent implements ControlValueAccessor, OnInit, OnChanges, OnDestroy {
    @Input() disabled = false;
    @Input() readonly = false;
    @Input() value: number;
    @Input() currencyCode = '';
    @Output() valueChange = new EventEmitter();
    prefix$: Observable<string>;
    suffix$: Observable<string>;
    hasFractionPart = true;
    onChange: (val: any) => void;
    onTouch: () => void;
    _inputValue: string;
    readonly precision: number;
    readonly precisionFactor: number;
    constructor(dataService: DataService, currencyService: CurrencyService)
    ngOnInit() => ;
    ngOnChanges(changes: SimpleChanges) => ;
    ngOnDestroy() => ;
    registerOnChange(fn: any) => ;
    registerOnTouched(fn: any) => ;
    setDisabledState(isDisabled: boolean) => ;
    onInput(value: string) => ;
    onFocus() => ;
    writeValue(value: any) => void;
}
```
* Implements: <code>ControlValueAccessor</code>, <code>OnInit</code>, <code>OnChanges</code>, <code>OnDestroy</code>



<div className="members-wrapper">

### disabled

<MemberInfo kind="property" type={``}   />


### readonly

<MemberInfo kind="property" type={``}   />


### value

<MemberInfo kind="property" type={`number`}   />


### currencyCode

<MemberInfo kind="property" type={``}   />


### valueChange

<MemberInfo kind="property" type={``}   />


### prefix$

<MemberInfo kind="property" type={`Observable&#60;string&#62;`}   />


### suffix$

<MemberInfo kind="property" type={`Observable&#60;string&#62;`}   />


### hasFractionPart

<MemberInfo kind="property" type={``}   />


### onChange

<MemberInfo kind="property" type={`(val: any) =&#62; void`}   />


### onTouch

<MemberInfo kind="property" type={`() =&#62; void`}   />


### _inputValue

<MemberInfo kind="property" type={`string`}   />


### precision

<MemberInfo kind="property" type={`number`}   />


### precisionFactor

<MemberInfo kind="property" type={`number`}   />


### constructor

<MemberInfo kind="method" type={`(dataService: <a href='/reference/admin-ui-api/services/data-service#dataservice'>DataService</a>, currencyService: CurrencyService) => CurrencyInputComponent`}   />


### ngOnInit

<MemberInfo kind="method" type={`() => `}   />


### ngOnChanges

<MemberInfo kind="method" type={`(changes: SimpleChanges) => `}   />


### ngOnDestroy

<MemberInfo kind="method" type={`() => `}   />


### registerOnChange

<MemberInfo kind="method" type={`(fn: any) => `}   />


### registerOnTouched

<MemberInfo kind="method" type={`(fn: any) => `}   />


### setDisabledState

<MemberInfo kind="method" type={`(isDisabled: boolean) => `}   />


### onInput

<MemberInfo kind="method" type={`(value: string) => `}   />


### onFocus

<MemberInfo kind="method" type={`() => `}   />


### writeValue

<MemberInfo kind="method" type={`(value: any) => void`}   />




</div>


---

---
title: "DataTableComponent"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DataTableComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/components/data-table/data-table.component.ts" sourceLine="86" packageName="@vendure/admin-ui" />

A table for displaying PaginatedList results. It is designed to be used inside components which
extend the <a href='/reference/admin-ui-api/list-detail-views/base-list-component#baselistcomponent'>BaseListComponent</a> class.

**Deprecated** This component is deprecated. Use the <a href='/reference/admin-ui-api/components/data-table2component#datatable2component'>DataTable2Component</a> instead.

*Example*

```HTML
<vdr-data-table
  [items]="items$ | async"
  [itemsPerPage]="itemsPerPage$ | async"
  [totalItems]="totalItems$ | async"
  [currentPage]="currentPage$ | async"
  (pageChange)="setPageNumber($event)"
  (itemsPerPageChange)="setItemsPerPage($event)"
>
  <!-- The header columns are defined first -->
  <vdr-dt-column>{{ 'common.name' | translate }}</vdr-dt-column>
  <vdr-dt-column></vdr-dt-column>
  <vdr-dt-column></vdr-dt-column>

  <!-- Then we define how a row is rendered -->
  <ng-template let-taxRate="item">
    <td class="left align-middle">{{ taxRate.name }}</td>
    <td class="left align-middle">{{ taxRate.category.name }}</td>
    <td class="left align-middle">{{ taxRate.zone.name }}</td>
    <td class="left align-middle">{{ taxRate.value }}%</td>
    <td class="right align-middle">
      <vdr-table-row-action
        iconShape="edit"
        [label]="'common.edit' | translate"
        [linkTo]="['./', taxRate.id]"
      ></vdr-table-row-action>
    </td>
    <td class="right align-middle">
      <vdr-dropdown>
        <button type="button" class="btn btn-link btn-sm" vdrDropdownTrigger>
          {{ 'common.actions' | translate }}
          <clr-icon shape="caret down"></clr-icon>
        </button>
        <vdr-dropdown-menu vdrPosition="bottom-right">
          <button
              type="button"
              class="delete-button"
              (click)="deleteTaxRate(taxRate)"
              [disabled]="!(['DeleteSettings', 'DeleteTaxRate'] | hasPermission)"
              vdrDropdownItem
          >
              <clr-icon shape="trash" class="is-danger"></clr-icon>
              {{ 'common.delete' | translate }}
          </button>
        </vdr-dropdown-menu>
      </vdr-dropdown>
    </td>
  </ng-template>
</vdr-data-table>
```

```ts title="Signature"
class DataTableComponent<T> implements AfterContentInit, OnChanges, OnInit, OnDestroy {
    @Input() items: T[];
    @Input() itemsPerPage: number;
    @Input() currentPage: number;
    @Input() totalItems: number;
    @Input() emptyStateLabel: string;
    @Input() selectionManager?: SelectionManager<T>;
    @Output() pageChange = new EventEmitter<number>();
    @Output() itemsPerPageChange = new EventEmitter<number>();
    @Input() allSelected: boolean;
    @Input() isRowSelectedFn: ((item: T) => boolean) | undefined;
    @Output() allSelectChange = new EventEmitter<void>();
    @Output() rowSelectChange = new EventEmitter<{ event: MouseEvent; item: T }>();
    @ContentChildren(DataTableColumnComponent) columns: QueryList<DataTableColumnComponent>;
    @ContentChildren(TemplateRef) templateRefs: QueryList<TemplateRef<any>>;
    rowTemplate: TemplateRef<any>;
    currentStart: number;
    currentEnd: number;
    disableSelect = false;
    constructor(changeDetectorRef: ChangeDetectorRef)
    ngOnInit() => ;
    ngOnChanges(changes: SimpleChanges) => ;
    ngOnDestroy() => ;
    ngAfterContentInit() => void;
    trackByFn(index: number, item: any) => ;
    onToggleAllClick() => ;
    onRowClick(item: T, event: MouseEvent) => ;
}
```
* Implements: <code>AfterContentInit</code>, <code>OnChanges</code>, <code>OnInit</code>, <code>OnDestroy</code>



<div className="members-wrapper">

### items

<MemberInfo kind="property" type={`T[]`}   />


### itemsPerPage

<MemberInfo kind="property" type={`number`}   />


### currentPage

<MemberInfo kind="property" type={`number`}   />


### totalItems

<MemberInfo kind="property" type={`number`}   />


### emptyStateLabel

<MemberInfo kind="property" type={`string`}   />


### selectionManager

<MemberInfo kind="property" type={`SelectionManager&#60;T&#62;`}   />


### pageChange

<MemberInfo kind="property" type={``}   />


### itemsPerPageChange

<MemberInfo kind="property" type={``}   />


### allSelected

<MemberInfo kind="property" type={`boolean`}   />


### isRowSelectedFn

<MemberInfo kind="property" type={`((item: T) =&#62; boolean) | undefined`}   />


### allSelectChange

<MemberInfo kind="property" type={``}   />


### rowSelectChange

<MemberInfo kind="property" type={``}   />


### columns

<MemberInfo kind="property" type={`QueryList&#60;DataTableColumnComponent&#62;`}   />


### templateRefs

<MemberInfo kind="property" type={`QueryList&#60;TemplateRef&#60;any&#62;&#62;`}   />


### rowTemplate

<MemberInfo kind="property" type={`TemplateRef&#60;any&#62;`}   />


### currentStart

<MemberInfo kind="property" type={`number`}   />


### currentEnd

<MemberInfo kind="property" type={`number`}   />


### disableSelect

<MemberInfo kind="property" type={``}   />


### constructor

<MemberInfo kind="method" type={`(changeDetectorRef: ChangeDetectorRef) => DataTableComponent`}   />


### ngOnInit

<MemberInfo kind="method" type={`() => `}   />


### ngOnChanges

<MemberInfo kind="method" type={`(changes: SimpleChanges) => `}   />


### ngOnDestroy

<MemberInfo kind="method" type={`() => `}   />


### ngAfterContentInit

<MemberInfo kind="method" type={`() => void`}   />


### trackByFn

<MemberInfo kind="method" type={`(index: number, item: any) => `}   />


### onToggleAllClick

<MemberInfo kind="method" type={`() => `}   />


### onRowClick

<MemberInfo kind="method" type={`(item: T, event: MouseEvent) => `}   />




</div>


---

---
title: "DataTable2Component"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DataTable2Component

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/components/data-table-2/data-table2.component.ts" sourceLine="101" packageName="@vendure/admin-ui" />

A table for displaying PaginatedList results. It is designed to be used inside components which
extend the <a href='/reference/admin-ui-api/list-detail-views/base-list-component#baselistcomponent'>BaseListComponent</a> or <a href='/reference/admin-ui-api/list-detail-views/typed-base-list-component#typedbaselistcomponent'>TypedBaseListComponent</a> class.

*Example*

```html
<vdr-data-table-2
    id="product-review-list"
    [items]="items$ | async"
    [itemsPerPage]="itemsPerPage$ | async"
    [totalItems]="totalItems$ | async"
    [currentPage]="currentPage$ | async"
    [filters]="filters"
    (pageChange)="setPageNumber($event)"
    (itemsPerPageChange)="setItemsPerPage($event)"
>
    <vdr-bulk-action-menu
        locationId="product-review-list"
        [hostComponent]="this"
        [selectionManager]="selectionManager"
    />
    <vdr-dt2-search
        [searchTermControl]="searchTermControl"
        searchTermPlaceholder="Filter by title"
    />
    <vdr-dt2-column [heading]="'common.id' | translate" [hiddenByDefault]="true">
        <ng-template let-review="item">
            {{ review.id }}
        </ng-template>
    </vdr-dt2-column>
    <vdr-dt2-column
        [heading]="'common.created-at' | translate"
        [hiddenByDefault]="true"
        [sort]="sorts.get('createdAt')"
    >
        <ng-template let-review="item">
            {{ review.createdAt | localeDate : 'short' }}
        </ng-template>
    </vdr-dt2-column>
    <vdr-dt2-column
        [heading]="'common.updated-at' | translate"
        [hiddenByDefault]="true"
        [sort]="sorts.get('updatedAt')"
    >
        <ng-template let-review="item">
            {{ review.updatedAt | localeDate : 'short' }}
        </ng-template>
    </vdr-dt2-column>
    <vdr-dt2-column [heading]="'common.name' | translate" [optional]="false" [sort]="sorts.get('name')">
        <ng-template let-review="item">
            <a class="button-ghost" [routerLink]="['./', review.id]"
                ><span>{{ review.name }}</span>
                <clr-icon shape="arrow right"></clr-icon>
            </a>
        </ng-template>
    </vdr-dt2-column>
</vdr-data-table-2>
```

```ts title="Signature"
class DataTable2Component<T> implements AfterContentInit, OnChanges, OnDestroy {
    @Input() id: DataTableLocationId;
    @Input() items: T[];
    @Input() itemsPerPage: number;
    @Input() currentPage: number;
    @Input() totalItems: number;
    @Input() emptyStateLabel: string;
    @Input() filters: DataTableFilterCollection;
    @Input() activeIndex = -1;
    @Input() trackByPath = 'id';
    @Output() pageChange = new EventEmitter<number>();
    @Output() itemsPerPageChange = new EventEmitter<number>();
    @Output() visibleColumnsChange = new EventEmitter<Array<DataTable2ColumnComponent<T>>>();
    @ContentChildren(DataTable2ColumnComponent) columns: QueryList<DataTable2ColumnComponent<T>>;
    @ContentChildren(DataTableCustomFieldColumnComponent)
    customFieldColumns: QueryList<DataTableCustomFieldColumnComponent<T>>;
    @ContentChild(DataTable2SearchComponent) searchComponent: DataTable2SearchComponent;
    @ContentChild(BulkActionMenuComponent) bulkActionMenuComponent: BulkActionMenuComponent;
    @ContentChild('vdrDt2CustomSearch') customSearchTemplate: TemplateRef<any>;
    @ContentChildren(TemplateRef) templateRefs: QueryList<TemplateRef<any>>;
    injector = inject(Injector);
    route = inject(ActivatedRoute);
    filterPresetService = inject(FilterPresetService);
    dataTableCustomComponentService = inject(DataTableCustomComponentService);
    dataTableConfigService = inject(DataTableConfigService);
    protected customComponents = new Map<string, { config: DataTableComponentConfig; injector: Injector }>();
    rowTemplate: TemplateRef<any>;
    currentStart: number;
    currentEnd: number;
    disableSelect = false;
    showSearchFilterRow = false;
    protected uiLanguage$: Observable<LanguageCode>;
    protected destroy$ = new Subject<void>();
    constructor(changeDetectorRef: ChangeDetectorRef, dataService: DataService)
    selectionManager: void
    allColumns: void
    visibleSortedColumns: void
    sortedColumns: void
    ngOnChanges(changes: SimpleChanges) => ;
    ngOnDestroy() => ;
    ngAfterContentInit() => void;
    onColumnReorder(event: { column: DataTable2ColumnComponent<any>; newIndex: number }) => ;
    onColumnsReset() => ;
    toggleSearchFilterRow() => ;
    trackByFn(index: number, item: any) => ;
    onToggleAllClick() => ;
    onRowClick(item: T, event: MouseEvent) => ;
}
```
* Implements: <code>AfterContentInit</code>, <code>OnChanges</code>, <code>OnDestroy</code>



<div className="members-wrapper">

### id

<MemberInfo kind="property" type={`DataTableLocationId`}   />


### items

<MemberInfo kind="property" type={`T[]`}   />


### itemsPerPage

<MemberInfo kind="property" type={`number`}   />


### currentPage

<MemberInfo kind="property" type={`number`}   />


### totalItems

<MemberInfo kind="property" type={`number`}   />


### emptyStateLabel

<MemberInfo kind="property" type={`string`}   />


### filters

<MemberInfo kind="property" type={`DataTableFilterCollection`}   />


### activeIndex

<MemberInfo kind="property" type={``}   />


### trackByPath

<MemberInfo kind="property" type={``}   />


### pageChange

<MemberInfo kind="property" type={``}   />


### itemsPerPageChange

<MemberInfo kind="property" type={``}   />


### visibleColumnsChange

<MemberInfo kind="property" type={``}   />


### columns

<MemberInfo kind="property" type={`QueryList&#60;DataTable2ColumnComponent&#60;T&#62;&#62;`}   />


### customFieldColumns

<MemberInfo kind="property" type={`QueryList&#60;DataTableCustomFieldColumnComponent&#60;T&#62;&#62;`}   />


### searchComponent

<MemberInfo kind="property" type={`DataTable2SearchComponent`}   />


### bulkActionMenuComponent

<MemberInfo kind="property" type={`BulkActionMenuComponent`}   />


### customSearchTemplate

<MemberInfo kind="property" type={`TemplateRef&#60;any&#62;`}   />


### templateRefs

<MemberInfo kind="property" type={`QueryList&#60;TemplateRef&#60;any&#62;&#62;`}   />


### injector

<MemberInfo kind="property" type={``}   />


### route

<MemberInfo kind="property" type={``}   />


### filterPresetService

<MemberInfo kind="property" type={``}   />


### dataTableCustomComponentService

<MemberInfo kind="property" type={``}   />


### dataTableConfigService

<MemberInfo kind="property" type={``}   />


### customComponents

<MemberInfo kind="property" type={``}   />


### rowTemplate

<MemberInfo kind="property" type={`TemplateRef&#60;any&#62;`}   />


### currentStart

<MemberInfo kind="property" type={`number`}   />


### currentEnd

<MemberInfo kind="property" type={`number`}   />


### disableSelect

<MemberInfo kind="property" type={``}   />


### showSearchFilterRow

<MemberInfo kind="property" type={``}   />


### uiLanguage$

<MemberInfo kind="property" type={`Observable&#60;<a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a>&#62;`}   />


### destroy$

<MemberInfo kind="property" type={``}   />


### constructor

<MemberInfo kind="method" type={`(changeDetectorRef: ChangeDetectorRef, dataService: <a href='/reference/admin-ui-api/services/data-service#dataservice'>DataService</a>) => DataTable2Component`}   />


### selectionManager

<MemberInfo kind="property" type={``}   />


### allColumns

<MemberInfo kind="property" type={``}   />


### visibleSortedColumns

<MemberInfo kind="property" type={``}   />


### sortedColumns

<MemberInfo kind="property" type={``}   />


### ngOnChanges

<MemberInfo kind="method" type={`(changes: SimpleChanges) => `}   />


### ngOnDestroy

<MemberInfo kind="method" type={`() => `}   />


### ngAfterContentInit

<MemberInfo kind="method" type={`() => void`}   />


### onColumnReorder

<MemberInfo kind="method" type={`(event: { column: DataTable2ColumnComponent&#60;any&#62;; newIndex: number }) => `}   />


### onColumnsReset

<MemberInfo kind="method" type={`() => `}   />


### toggleSearchFilterRow

<MemberInfo kind="method" type={`() => `}   />


### trackByFn

<MemberInfo kind="method" type={`(index: number, item: any) => `}   />


### onToggleAllClick

<MemberInfo kind="method" type={`() => `}   />


### onRowClick

<MemberInfo kind="method" type={`(item: T, event: MouseEvent) => `}   />




</div>


---

---
title: "DatetimePickerComponent"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DatetimePickerComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/components/datetime-picker/datetime-picker.component.ts" sourceLine="39" packageName="@vendure/admin-ui" />

A form input for selecting datetime values.

*Example*

```HTML
<vdr-datetime-picker [(ngModel)]="startDate"></vdr-datetime-picker>
```

```ts title="Signature"
class DatetimePickerComponent implements ControlValueAccessor, AfterViewInit, OnInit, OnDestroy {
    @Input() yearRange;
    @Input() weekStartDay: DayOfWeek = 'mon';
    @Input() timeGranularityInterval = 5;
    @Input() min: string | null = null;
    @Input() max: string | null = null;
    @Input() readonly = false;
    @ViewChild('dropdownComponent', { static: true }) dropdownComponent: DropdownComponent;
    @ViewChild('datetimeInput', { static: true }) datetimeInput: ElementRef<HTMLInputElement>;
    @ViewChild('calendarTable') calendarTable: ElementRef<HTMLTableElement>;
    disabled = false;
    calendarView$: Observable<CalendarView>;
    current$: Observable<CurrentView>;
    selected$: Observable<Date | null>;
    selectedHours$: Observable<number | null>;
    selectedMinutes$: Observable<number | null>;
    years: number[];
    weekdays: string[] = [];
    hours: number[];
    minutes: number[];
    constructor(changeDetectorRef: ChangeDetectorRef, datetimePickerService: DatetimePickerService)
    ngOnInit() => ;
    ngAfterViewInit() => void;
    ngOnDestroy() => void;
    registerOnChange(fn: any) => ;
    registerOnTouched(fn: any) => ;
    setDisabledState(isDisabled: boolean) => ;
    writeValue(value: string | null) => ;
    prevMonth() => ;
    nextMonth() => ;
    selectToday() => ;
    setYear(event: Event) => ;
    setMonth(event: Event) => ;
    selectDay(day: DayCell) => ;
    clearValue() => ;
    handleCalendarKeydown(event: KeyboardEvent) => ;
    setHour(event: Event) => ;
    setMinute(event: Event) => ;
    closeDatepicker() => ;
}
```
* Implements: <code>ControlValueAccessor</code>, <code>AfterViewInit</code>, <code>OnInit</code>, <code>OnDestroy</code>



<div className="members-wrapper">

### yearRange

<MemberInfo kind="property" type={``}   />

The range above and below the current year which is selectable from
the year select control. If a min or max value is set, these will
override the yearRange.
### weekStartDay

<MemberInfo kind="property" type={`DayOfWeek`}   />

The day that the week should start with in the calendar view.
### timeGranularityInterval

<MemberInfo kind="property" type={``}   />

The granularity of the minutes time picker
### min

<MemberInfo kind="property" type={`string | null`}   />

The minimum date as an ISO string
### max

<MemberInfo kind="property" type={`string | null`}   />

The maximum date as an ISO string
### readonly

<MemberInfo kind="property" type={``}   />

Sets the readonly state
### dropdownComponent

<MemberInfo kind="property" type={`<a href='/reference/admin-ui-api/components/dropdown-component#dropdowncomponent'>DropdownComponent</a>`}   />


### datetimeInput

<MemberInfo kind="property" type={`ElementRef&#60;HTMLInputElement&#62;`}   />


### calendarTable

<MemberInfo kind="property" type={`ElementRef&#60;HTMLTableElement&#62;`}   />


### disabled

<MemberInfo kind="property" type={``}   />


### calendarView$

<MemberInfo kind="property" type={`Observable&#60;CalendarView&#62;`}   />


### current$

<MemberInfo kind="property" type={`Observable&#60;CurrentView&#62;`}   />


### selected$

<MemberInfo kind="property" type={`Observable&#60;Date | null&#62;`}   />


### selectedHours$

<MemberInfo kind="property" type={`Observable&#60;number | null&#62;`}   />


### selectedMinutes$

<MemberInfo kind="property" type={`Observable&#60;number | null&#62;`}   />


### years

<MemberInfo kind="property" type={`number[]`}   />


### weekdays

<MemberInfo kind="property" type={`string[]`}   />


### hours

<MemberInfo kind="property" type={`number[]`}   />


### minutes

<MemberInfo kind="property" type={`number[]`}   />


### constructor

<MemberInfo kind="method" type={`(changeDetectorRef: ChangeDetectorRef, datetimePickerService: DatetimePickerService) => DatetimePickerComponent`}   />


### ngOnInit

<MemberInfo kind="method" type={`() => `}   />


### ngAfterViewInit

<MemberInfo kind="method" type={`() => void`}   />


### ngOnDestroy

<MemberInfo kind="method" type={`() => void`}   />


### registerOnChange

<MemberInfo kind="method" type={`(fn: any) => `}   />


### registerOnTouched

<MemberInfo kind="method" type={`(fn: any) => `}   />


### setDisabledState

<MemberInfo kind="method" type={`(isDisabled: boolean) => `}   />


### writeValue

<MemberInfo kind="method" type={`(value: string | null) => `}   />


### prevMonth

<MemberInfo kind="method" type={`() => `}   />


### nextMonth

<MemberInfo kind="method" type={`() => `}   />


### selectToday

<MemberInfo kind="method" type={`() => `}   />


### setYear

<MemberInfo kind="method" type={`(event: Event) => `}   />


### setMonth

<MemberInfo kind="method" type={`(event: Event) => `}   />


### selectDay

<MemberInfo kind="method" type={`(day: DayCell) => `}   />


### clearValue

<MemberInfo kind="method" type={`() => `}   />


### handleCalendarKeydown

<MemberInfo kind="method" type={`(event: KeyboardEvent) => `}   />


### setHour

<MemberInfo kind="method" type={`(event: Event) => `}   />


### setMinute

<MemberInfo kind="method" type={`(event: Event) => `}   />


### closeDatepicker

<MemberInfo kind="method" type={`() => `}   />




</div>


---

---
title: "DropdownComponent"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DropdownComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/components/dropdown/dropdown.component.ts" sourceLine="28" packageName="@vendure/admin-ui" />

Used for building dropdown menus.

*Example*

```HTML
<vdr-dropdown>
  <button class="btn btn-outline" vdrDropdownTrigger>
      <clr-icon shape="plus"></clr-icon>
      Select type
  </button>
  <vdr-dropdown-menu vdrPosition="bottom-left">
    <button
      *ngFor="let typeName of allTypes"
      type="button"
      vdrDropdownItem
      (click)="selectType(typeName)"
    >
      typeName
    </button>
  </vdr-dropdown-menu>
</vdr-dropdown>
```

```ts title="Signature"
class DropdownComponent {
    isOpen = false;
    public trigger: ElementRef;
    @Input() manualToggle = false;
    onClick() => ;
    toggleOpen() => ;
    onOpenChange(callback: (isOpen: boolean) => void) => ;
    setTriggerElement(elementRef: ElementRef) => ;
}
```

<div className="members-wrapper">

### isOpen

<MemberInfo kind="property" type={``}   />


### trigger

<MemberInfo kind="property" type={`ElementRef`}   />


### manualToggle

<MemberInfo kind="property" type={``}   />


### onClick

<MemberInfo kind="method" type={`() => `}   />


### toggleOpen

<MemberInfo kind="method" type={`() => `}   />


### onOpenChange

<MemberInfo kind="method" type={`(callback: (isOpen: boolean) =&#62; void) => `}   />


### setTriggerElement

<MemberInfo kind="method" type={`(elementRef: ElementRef) => `}   />




</div>


---

---
title: "FacetValueSelectorComponent"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## FacetValueSelectorComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/components/facet-value-selector/facet-value-selector.component.ts" sourceLine="34" packageName="@vendure/admin-ui" />

A form control for selecting facet values.

*Example*

```HTML
<vdr-facet-value-selector
  (selectedValuesChange)="selectedValues = $event"
></vdr-facet-value-selector>
```
The `selectedValuesChange` event will emit an array of `FacetValue` objects.

```ts title="Signature"
class FacetValueSelectorComponent implements OnInit, OnDestroy, ControlValueAccessor {
    @Output() selectedValuesChange = new EventEmitter<FacetValueFragment[]>();
    @Input() readonly = false;
    @Input() transformControlValueAccessorValue: (value: FacetValueFragment[]) => any[] = value => value;
    searchInput$ = new Subject<string>();
    searchLoading = false;
    searchResults$: Observable<FacetValueFragment[]>;
    selectedIds$ = new Subject<string[]>();
    onChangeFn: (val: any) => void;
    onTouchFn: () => void;
    disabled = false;
    value: Array<string | FacetValueFragment>;
    constructor(dataService: DataService, changeDetectorRef: ChangeDetectorRef)
    ngOnInit() => void;
    ngOnDestroy() => ;
    onChange(selected: FacetValueFragment[]) => ;
    registerOnChange(fn: any) => ;
    registerOnTouched(fn: any) => ;
    setDisabledState(isDisabled: boolean) => void;
    focus() => ;
    writeValue(obj: string | FacetValueFragment[] | Array<string | number> | null) => void;
}
```
* Implements: <code>OnInit</code>, <code>OnDestroy</code>, <code>ControlValueAccessor</code>



<div className="members-wrapper">

### selectedValuesChange

<MemberInfo kind="property" type={``}   />


### readonly

<MemberInfo kind="property" type={``}   />


### transformControlValueAccessorValue

<MemberInfo kind="property" type={`(value: FacetValueFragment[]) =&#62; any[]`}   />


### searchInput$

<MemberInfo kind="property" type={``}   />


### searchLoading

<MemberInfo kind="property" type={``}   />


### searchResults$

<MemberInfo kind="property" type={`Observable&#60;FacetValueFragment[]&#62;`}   />


### selectedIds$

<MemberInfo kind="property" type={``}   />


### onChangeFn

<MemberInfo kind="property" type={`(val: any) =&#62; void`}   />


### onTouchFn

<MemberInfo kind="property" type={`() =&#62; void`}   />


### disabled

<MemberInfo kind="property" type={``}   />


### value

<MemberInfo kind="property" type={`Array&#60;string | FacetValueFragment&#62;`}   />


### constructor

<MemberInfo kind="method" type={`(dataService: <a href='/reference/admin-ui-api/services/data-service#dataservice'>DataService</a>, changeDetectorRef: ChangeDetectorRef) => FacetValueSelectorComponent`}   />


### ngOnInit

<MemberInfo kind="method" type={`() => void`}   />


### ngOnDestroy

<MemberInfo kind="method" type={`() => `}   />


### onChange

<MemberInfo kind="method" type={`(selected: FacetValueFragment[]) => `}   />


### registerOnChange

<MemberInfo kind="method" type={`(fn: any) => `}   />


### registerOnTouched

<MemberInfo kind="method" type={`(fn: any) => `}   />


### setDisabledState

<MemberInfo kind="method" type={`(isDisabled: boolean) => void`}   />


### focus

<MemberInfo kind="method" type={`() => `}   />


### writeValue

<MemberInfo kind="method" type={`(obj: string | FacetValueFragment[] | Array&#60;string | number&#62; | null) => void`}   />




</div>


---

---
title: "Components"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "ObjectTreeComponent"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ObjectTreeComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/components/object-tree/object-tree.component.ts" sourceLine="22" packageName="@vendure/admin-ui" />

This component displays a plain JavaScript object as an expandable tree.

*Example*

```HTML
<vdr-object-tree [value]="payment.metadata"></vdr-object-tree>
```

```ts title="Signature"
class ObjectTreeComponent implements OnChanges {
    @Input() value: { [key: string]: any } | string;
    @Input() isArrayItem = false;
    depth: number;
    expanded: boolean;
    valueIsArray: boolean;
    entries: Array<{ key: string; value: any }>;
    constructor(parent: ObjectTreeComponent)
    ngOnChanges() => ;
    isObject(value: any) => boolean;
}
```
* Implements: <code>OnChanges</code>



<div className="members-wrapper">

### value

<MemberInfo kind="property" type={`{ [key: string]: any } | string`}   />


### isArrayItem

<MemberInfo kind="property" type={``}   />


### depth

<MemberInfo kind="property" type={`number`}   />


### expanded

<MemberInfo kind="property" type={`boolean`}   />


### valueIsArray

<MemberInfo kind="property" type={`boolean`}   />


### entries

<MemberInfo kind="property" type={`Array&#60;{ key: string; value: any }&#62;`}   />


### constructor

<MemberInfo kind="method" type={`(parent: <a href='/reference/admin-ui-api/components/object-tree-component#objecttreecomponent'>ObjectTreeComponent</a>) => ObjectTreeComponent`}   />


### ngOnChanges

<MemberInfo kind="method" type={`() => `}   />


### isObject

<MemberInfo kind="method" type={`(value: any) => boolean`}   />




</div>


---

---
title: "OrderStateLabelComponent"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## OrderStateLabelComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/components/order-state-label/order-state-label.component.ts" sourceLine="13" packageName="@vendure/admin-ui" />

Displays the state of an order in a colored chip.

*Example*

```HTML
<vdr-order-state-label [state]="order.state"></vdr-order-state-label>
```

```ts title="Signature"
class OrderStateLabelComponent {
    @Input() state: string;
    chipColorType: void
}
```

<div className="members-wrapper">

### state

<MemberInfo kind="property" type={`string`}   />


### chipColorType

<MemberInfo kind="property" type={``}   />




</div>


---

---
title: "ProductVariantSelectorComponent"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ProductVariantSelectorComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/components/product-variant-selector/product-variant-selector.component.ts" sourceLine="21" packageName="@vendure/admin-ui" />

A component for selecting product variants via an autocomplete-style select input.

*Example*

```HTML
<vdr-product-variant-selector
  (productSelected)="selectResult($event)"></vdr-product-variant-selector>
```

```ts title="Signature"
class ProductVariantSelectorComponent implements OnInit {
    searchInput$ = new Subject<string>();
    searchLoading = false;
    searchResults$: Observable<ProductSelectorSearchQuery['search']['items']>;
    @Output() productSelected = new EventEmitter<ProductSelectorSearchQuery['search']['items'][number]>();
    constructor(dataService: DataService)
    ngOnInit() => void;
    selectResult(product?: ProductSelectorSearchQuery['search']['items'][number]) => ;
}
```
* Implements: <code>OnInit</code>



<div className="members-wrapper">

### searchInput$

<MemberInfo kind="property" type={``}   />


### searchLoading

<MemberInfo kind="property" type={``}   />


### searchResults$

<MemberInfo kind="property" type={`Observable&#60;ProductSelectorSearchQuery['search']['items']&#62;`}   />


### productSelected

<MemberInfo kind="property" type={``}   />


### constructor

<MemberInfo kind="method" type={`(dataService: <a href='/reference/admin-ui-api/services/data-service#dataservice'>DataService</a>) => ProductVariantSelectorComponent`}   />


### ngOnInit

<MemberInfo kind="method" type={`() => void`}   />


### selectResult

<MemberInfo kind="method" type={`(product?: ProductSelectorSearchQuery['search']['items'][number]) => `}   />




</div>


---

---
title: "RichTextEditorComponent"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## RichTextEditorComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/components/rich-text-editor/rich-text-editor.component.ts" sourceLine="32" packageName="@vendure/admin-ui" />

A rich text (HTML) editor based on Prosemirror (https://prosemirror.net/)

*Example*

```HTML
<vdr-rich-text-editor
    [(ngModel)]="description"
    label="Description"
></vdr-rich-text-editor>
```

```ts title="Signature"
class RichTextEditorComponent implements ControlValueAccessor, AfterViewInit, OnDestroy {
    @Input() label: string;
    @HostBinding('class.readonly')
    _readonly = false;
    onChange: (val: any) => void;
    onTouch: () => void;
    constructor(changeDetector: ChangeDetectorRef, prosemirrorService: ProsemirrorService, viewContainerRef: ViewContainerRef, contextMenuService: ContextMenuService)
    menuElement: HTMLDivElement | null
    ngAfterViewInit() => ;
    ngOnDestroy() => ;
    registerOnChange(fn: any) => ;
    registerOnTouched(fn: any) => ;
    setDisabledState(isDisabled: boolean) => ;
    writeValue(value: any) => ;
}
```
* Implements: <code>ControlValueAccessor</code>, <code>AfterViewInit</code>, <code>OnDestroy</code>



<div className="members-wrapper">

### label

<MemberInfo kind="property" type={`string`}   />


### _readonly

<MemberInfo kind="property" type={``}   />


### onChange

<MemberInfo kind="property" type={`(val: any) =&#62; void`}   />


### onTouch

<MemberInfo kind="property" type={`() =&#62; void`}   />


### constructor

<MemberInfo kind="method" type={`(changeDetector: ChangeDetectorRef, prosemirrorService: ProsemirrorService, viewContainerRef: ViewContainerRef, contextMenuService: ContextMenuService) => RichTextEditorComponent`}   />


### menuElement

<MemberInfo kind="property" type={`HTMLDivElement | null`}   />


### ngAfterViewInit

<MemberInfo kind="method" type={`() => `}   />


### ngOnDestroy

<MemberInfo kind="method" type={`() => `}   />


### registerOnChange

<MemberInfo kind="method" type={`(fn: any) => `}   />


### registerOnTouched

<MemberInfo kind="method" type={`(fn: any) => `}   />


### setDisabledState

<MemberInfo kind="method" type={`(isDisabled: boolean) => `}   />


### writeValue

<MemberInfo kind="method" type={`(value: any) => `}   />




</div>


---

---
title: "ZoneSelectorComponent"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ZoneSelectorComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/components/zone-selector/zone-selector.component.ts" sourceLine="40" packageName="@vendure/admin-ui" />

A form control for selecting zones.

```ts title="Signature"
class ZoneSelectorComponent implements ControlValueAccessor {
    @Output() selectedValuesChange = new EventEmitter<Zone>();
    @Input() readonly = false;
    @Input() transformControlValueAccessorValue: (value: Zone | undefined) => any = value => value?.id;
    selectedId$ = new Subject<string>();
    onChangeFn: (val: any) => void;
    onTouchFn: () => void;
    disabled = false;
    value: string | Zone;
    zones$ = this.dataService
        .query(GetZoneSelectorListDocument, { options: { take: 999 } })
        .mapSingle(result => result.zones.items);
    constructor(dataService: DataService, changeDetectorRef: ChangeDetectorRef)
    onChange(selected: Zone) => ;
    registerOnChange(fn: any) => ;
    registerOnTouched(fn: any) => ;
    setDisabledState(isDisabled: boolean) => void;
    focus() => ;
    writeValue(obj: string | Zone | null) => void;
}
```
* Implements: <code>ControlValueAccessor</code>



<div className="members-wrapper">

### selectedValuesChange

<MemberInfo kind="property" type={``}   />


### readonly

<MemberInfo kind="property" type={``}   />


### transformControlValueAccessorValue

<MemberInfo kind="property" type={`(value: <a href='/reference/typescript-api/entities/zone#zone'>Zone</a> | undefined) =&#62; any`}   />


### selectedId$

<MemberInfo kind="property" type={``}   />


### onChangeFn

<MemberInfo kind="property" type={`(val: any) =&#62; void`}   />


### onTouchFn

<MemberInfo kind="property" type={`() =&#62; void`}   />


### disabled

<MemberInfo kind="property" type={``}   />


### value

<MemberInfo kind="property" type={`string | <a href='/reference/typescript-api/entities/zone#zone'>Zone</a>`}   />


### zones$

<MemberInfo kind="property" type={``}   />


### constructor

<MemberInfo kind="method" type={`(dataService: <a href='/reference/admin-ui-api/services/data-service#dataservice'>DataService</a>, changeDetectorRef: ChangeDetectorRef) => ZoneSelectorComponent`}   />


### onChange

<MemberInfo kind="method" type={`(selected: <a href='/reference/typescript-api/entities/zone#zone'>Zone</a>) => `}   />


### registerOnChange

<MemberInfo kind="method" type={`(fn: any) => `}   />


### registerOnTouched

<MemberInfo kind="method" type={`(fn: any) => `}   />


### setDisabledState

<MemberInfo kind="method" type={`(isDisabled: boolean) => void`}   />


### focus

<MemberInfo kind="method" type={`() => `}   />


### writeValue

<MemberInfo kind="method" type={`(obj: string | <a href='/reference/typescript-api/entities/zone#zone'>Zone</a> | null) => void`}   />




</div>


---

---
title: "CustomDetailComponentConfig"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## CustomDetailComponentConfig

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/providers/custom-detail-component/custom-detail-component-types.ts" sourceLine="25" packageName="@vendure/admin-ui" />

Configures a <a href='/reference/admin-ui-api/custom-detail-components/custom-detail-component#customdetailcomponent'>CustomDetailComponent</a> to be placed in the given location.

```ts title="Signature"
interface CustomDetailComponentConfig {
    locationId: CustomDetailComponentLocationId;
    component: Type<CustomDetailComponent>;
    providers?: Provider[];
}
```

<div className="members-wrapper">

### locationId

<MemberInfo kind="property" type={`<a href='/reference/admin-ui-api/custom-detail-components/custom-detail-component-location-id#customdetailcomponentlocationid'>CustomDetailComponentLocationId</a>`}   />


### component

<MemberInfo kind="property" type={`Type&#60;<a href='/reference/admin-ui-api/custom-detail-components/custom-detail-component#customdetailcomponent'>CustomDetailComponent</a>&#62;`}   />


### providers

<MemberInfo kind="property" type={`Provider[]`}   />




</div>


---

---
title: "CustomDetailComponentLocationId"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## CustomDetailComponentLocationId

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/common/component-registry-types.ts" sourceLine="115" packageName="@vendure/admin-ui" />

The valid locations for embedding a <a href='/reference/admin-ui-api/custom-detail-components/custom-detail-component#customdetailcomponent'>CustomDetailComponent</a>.

```ts title="Signature"
type CustomDetailComponentLocationId = | 'administrator-profile'
    | 'administrator-detail'
    | 'channel-detail'
    | 'collection-detail'
    | 'country-detail'
    | 'customer-detail'
    | 'customer-group-detail'
    | 'draft-order-detail'
    | 'facet-detail'
    | 'global-settings-detail'
    | 'order-detail'
    | 'payment-method-detail'
    | 'product-detail'
    | 'product-variant-detail'
    | 'promotion-detail'
    | 'seller-detail'
    | 'shipping-method-detail'
    | 'stock-location-detail'
    | 'tax-category-detail'
    | 'tax-rate-detail'
    | 'zone-detail'
```


---

---
title: "CustomDetailComponent"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## CustomDetailComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/providers/custom-detail-component/custom-detail-component-types.ts" sourceLine="14" packageName="@vendure/admin-ui" />

CustomDetailComponents allow any arbitrary Angular components to be embedded in entity detail
pages of the Admin UI.

```ts title="Signature"
interface CustomDetailComponent {
    entity$: Observable<any>;
    detailForm: UntypedFormGroup;
}
```

<div className="members-wrapper">

### entity$

<MemberInfo kind="property" type={`Observable&#60;any&#62;`}   />


### detailForm

<MemberInfo kind="property" type={`UntypedFormGroup`}   />




</div>


---

---
title: "Custom Detail Components"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "RegisterCustomDetailComponent"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## registerCustomDetailComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/extension/register-custom-detail-component.ts" sourceLine="57" packageName="@vendure/admin-ui" />

Registers a <a href='/reference/admin-ui-api/custom-detail-components/custom-detail-component#customdetailcomponent'>CustomDetailComponent</a> to be placed in a given location. This allows you
to embed any type of custom Angular component in the entity detail pages of the Admin UI.

*Example*

```ts
import { Component, OnInit } from '@angular/core';
import { switchMap } from 'rxjs';
import { FormGroup } from '@angular/forms';
import { CustomFieldConfig } from '@vendure/common/lib/generated-types';
import {
    DataService,
    SharedModule,
    CustomDetailComponent,
    registerCustomDetailComponent,
    GetProductWithVariants
} from '@vendure/admin-ui/core';

@Component({
    template: `{{ extraInfo$ | async | json }}`,
    standalone: true,
    imports: [SharedModule],
})
export class ProductInfoComponent implements CustomDetailComponent, OnInit {
    // These two properties are provided by Vendure and will vary
    // depending on the particular detail page you are embedding this
    // component into.
    entity$: Observable<GetProductWithVariants.Product>
    detailForm: FormGroup;

    extraInfo$: Observable<any>;

    constructor(private cmsDataService: CmsDataService) {}

    ngOnInit() {
        this.extraInfo$ = this.entity$.pipe(
            switchMap(entity => this.cmsDataService.getDataFor(entity.id))
        );
    }
}

export default [
    registerCustomDetailComponent({
        locationId: 'product-detail',
        component: ProductInfoComponent,
    }),
];
```

```ts title="Signature"
function registerCustomDetailComponent(config: CustomDetailComponentConfig): void
```
Parameters

### config

<MemberInfo kind="parameter" type={`<a href='/reference/admin-ui-api/custom-detail-components/custom-detail-component-config#customdetailcomponentconfig'>CustomDetailComponentConfig</a>`} />



---

---
title: "CustomerHistoryEntryComponent"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## CustomerHistoryEntryComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/providers/custom-history-entry-component/history-entry-component-types.ts" sourceLine="64" packageName="@vendure/admin-ui" since="1.9.0" />

Used to implement a <a href='/reference/admin-ui-api/custom-history-entry-components/history-entry-component#historyentrycomponent'>HistoryEntryComponent</a> which requires access to the Customer object.

```ts title="Signature"
interface CustomerHistoryEntryComponent extends HistoryEntryComponent {
    customer: CustomerFragment;
}
```
* Extends: <code><a href='/reference/admin-ui-api/custom-history-entry-components/history-entry-component#historyentrycomponent'>HistoryEntryComponent</a></code>



<div className="members-wrapper">

### customer

<MemberInfo kind="property" type={`CustomerFragment`}   />




</div>


---

---
title: "HistoryEntryComponent"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## HistoryEntryComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/providers/custom-history-entry-component/history-entry-component-types.ts" sourceLine="16" packageName="@vendure/admin-ui" since="1.9.0" />

This interface should be implemented by components intended to display a history entry in the
Order or Customer history timeline. If the component needs access to the Order or Customer object itself,
you should implement <a href='/reference/admin-ui-api/custom-history-entry-components/order-history-entry-component#orderhistoryentrycomponent'>OrderHistoryEntryComponent</a> or <a href='/reference/admin-ui-api/custom-history-entry-components/customer-history-entry-component#customerhistoryentrycomponent'>CustomerHistoryEntryComponent</a> respectively.

```ts title="Signature"
interface HistoryEntryComponent {
    entry: TimelineHistoryEntry;
    getDisplayType: (entry: TimelineHistoryEntry) => TimelineDisplayType;
    isFeatured: (entry: TimelineHistoryEntry) => boolean;
    getName?: (entry: TimelineHistoryEntry) => string | undefined;
    getIconShape?: (entry: TimelineHistoryEntry) => string | string[] | undefined;
}
```

<div className="members-wrapper">

### entry

<MemberInfo kind="property" type={`TimelineHistoryEntry`}   />

The HistoryEntry data.
### getDisplayType

<MemberInfo kind="property" type={`(entry: TimelineHistoryEntry) =&#62; TimelineDisplayType`}   />

Defines whether this entry is highlighted with a "success", "error" etc. color.
### isFeatured

<MemberInfo kind="property" type={`(entry: TimelineHistoryEntry) =&#62; boolean`}   />

Featured entries are always expanded. Non-featured entries start of collapsed and can be clicked
to expand.
### getName

<MemberInfo kind="property" type={`(entry: TimelineHistoryEntry) =&#62; string | undefined`}   />

Returns the name of the person who did this action. For example, it could be the Customer's name
or "Administrator".
### getIconShape

<MemberInfo kind="property" type={`(entry: TimelineHistoryEntry) =&#62; string | string[] | undefined`}   />

Optional Clarity icon shape to display with the entry. Examples: `'note'`, `['success-standard', 'is-solid']`


</div>


---

---
title: "HistoryEntryConfig"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## HistoryEntryConfig

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/providers/custom-history-entry-component/history-entry-component-types.ts" sourceLine="75" packageName="@vendure/admin-ui" since="1.9.0" />

Configuration for registering a custom <a href='/reference/admin-ui-api/custom-history-entry-components/history-entry-component#historyentrycomponent'>HistoryEntryComponent</a>.

```ts title="Signature"
interface HistoryEntryConfig {
    type: string;
    component: Type<HistoryEntryComponent>;
}
```

<div className="members-wrapper">

### type

<MemberInfo kind="property" type={`string`}   />

The type should correspond to the custom HistoryEntryType string.
### component

<MemberInfo kind="property" type={`Type&#60;<a href='/reference/admin-ui-api/custom-history-entry-components/history-entry-component#historyentrycomponent'>HistoryEntryComponent</a>&#62;`}   />

The component to be rendered for this history entry type.


</div>


---

---
title: "Custom History Entry Components"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "OrderHistoryEntryComponent"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## OrderHistoryEntryComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/providers/custom-history-entry-component/history-entry-component-types.ts" sourceLine="53" packageName="@vendure/admin-ui" since="1.9.0" />

Used to implement a <a href='/reference/admin-ui-api/custom-history-entry-components/history-entry-component#historyentrycomponent'>HistoryEntryComponent</a> which requires access to the Order object.

```ts title="Signature"
interface OrderHistoryEntryComponent extends HistoryEntryComponent {
    order: OrderDetailFragment;
}
```
* Extends: <code><a href='/reference/admin-ui-api/custom-history-entry-components/history-entry-component#historyentrycomponent'>HistoryEntryComponent</a></code>



<div className="members-wrapper">

### order

<MemberInfo kind="property" type={`OrderDetailFragment`}   />




</div>


---

---
title: "RegisterHistoryEntryComponent"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## registerHistoryEntryComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/extension/register-history-entry-component.ts" sourceLine="68" packageName="@vendure/admin-ui" since="1.9.0" />

Registers a <a href='/reference/admin-ui-api/custom-history-entry-components/history-entry-component#historyentrycomponent'>HistoryEntryComponent</a> for displaying history entries in the Order/Customer
history timeline.

*Example*

```ts
import { Component } from '@angular/core';
import {
    CustomerFragment,
    CustomerHistoryEntryComponent,
    registerHistoryEntryComponent,
    SharedModule,
    TimelineDisplayType,
    TimelineHistoryEntry,
} from '@vendure/admin-ui/core';

@Component({
    selector: 'tax-id-verification-component',
    template: `
        <div *ngIf="entry.data.valid">
          Tax ID <strong>{{ entry.data.taxId }}</strong> was verified
          <vdr-history-entry-detail *ngIf="entry.data">
            <vdr-object-tree [value]="entry.data"></vdr-object-tree>
          </vdr-history-entry-detail>
        </div>
        <div *ngIf="entry.data.valid">Tax ID {{ entry.data.taxId }} could not be verified</div>
    `,
    standalone: true,
    imports: [SharedModule],
})
class TaxIdHistoryEntryComponent implements CustomerHistoryEntryComponent {
    entry: TimelineHistoryEntry;
    customer: CustomerFragment;

    getDisplayType(entry: TimelineHistoryEntry): TimelineDisplayType {
        return entry.data.valid ? 'success' : 'error';
    }

    getName(entry: TimelineHistoryEntry): string {
        return 'Tax ID Verification Plugin';
    }

    isFeatured(entry: TimelineHistoryEntry): boolean {
        return true;
    }

    getIconShape(entry: TimelineHistoryEntry) {
        return entry.data.valid ? 'check-circle' : 'exclamation-circle';
    }
}

export default [
    registerHistoryEntryComponent({
        type: 'CUSTOMER_TAX_ID_VERIFICATION',
        component: TaxIdHistoryEntryComponent,
    }),
];
```

```ts title="Signature"
function registerHistoryEntryComponent(config: HistoryEntryConfig): void
```
Parameters

### config

<MemberInfo kind="parameter" type={`<a href='/reference/admin-ui-api/custom-history-entry-components/history-entry-config#historyentryconfig'>HistoryEntryConfig</a>`} />



---

---
title: "Default Inputs"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## BooleanFormInputComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/dynamic-form-inputs/boolean-form-input/boolean-form-input.component.ts" sourceLine="14" packageName="@vendure/admin-ui" />

A checkbox input. The default input component for `boolean` fields.

```ts title="Signature"
class BooleanFormInputComponent implements FormInputComponent {
    static readonly id: DefaultFormComponentId = 'boolean-form-input';
    readonly: boolean;
    formControl: UntypedFormControl;
    config: DefaultFormComponentConfig<'boolean-form-input'>;
}
```
* Implements: <code><a href='/reference/admin-ui-api/custom-input-components/form-input-component#forminputcomponent'>FormInputComponent</a></code>



<div className="members-wrapper">

### id

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/configurable-operation-def/default-form-component-id#defaultformcomponentid'>DefaultFormComponentId</a>`}   />


### readonly

<MemberInfo kind="property" type={`boolean`}   />


### formControl

<MemberInfo kind="property" type={`UntypedFormControl`}   />


### config

<MemberInfo kind="property" type={`DefaultFormComponentConfig&#60;'boolean-form-input'&#62;`}   />




</div>


## HtmlEditorFormInputComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/dynamic-form-inputs/code-editor-form-input/html-editor-form-input.component.ts" sourceLine="23" packageName="@vendure/admin-ui" />

A JSON editor input with syntax highlighting and error detection. Works well
with `text` type fields.

```ts title="Signature"
class HtmlEditorFormInputComponent extends BaseCodeEditorFormInputComponent implements FormInputComponent, AfterViewInit, OnInit {
    static readonly id: DefaultFormComponentId = 'html-editor-form-input';
    constructor(changeDetector: ChangeDetectorRef)
    ngOnInit() => ;
}
```
* Extends: <code>BaseCodeEditorFormInputComponent</code>


* Implements: <code><a href='/reference/admin-ui-api/custom-input-components/form-input-component#forminputcomponent'>FormInputComponent</a></code>, <code>AfterViewInit</code>, <code>OnInit</code>



<div className="members-wrapper">

### id

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/configurable-operation-def/default-form-component-id#defaultformcomponentid'>DefaultFormComponentId</a>`}   />


### constructor

<MemberInfo kind="method" type={`(changeDetector: ChangeDetectorRef) => HtmlEditorFormInputComponent`}   />


### ngOnInit

<MemberInfo kind="method" type={`() => `}   />




</div>


## JsonEditorFormInputComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/dynamic-form-inputs/code-editor-form-input/json-editor-form-input.component.ts" sourceLine="33" packageName="@vendure/admin-ui" />

A JSON editor input with syntax highlighting and error detection. Works well
with `text` type fields.

```ts title="Signature"
class JsonEditorFormInputComponent extends BaseCodeEditorFormInputComponent implements FormInputComponent, AfterViewInit, OnInit {
    static readonly id: DefaultFormComponentId = 'json-editor-form-input';
    constructor(changeDetector: ChangeDetectorRef)
    ngOnInit() => ;
}
```
* Extends: <code>BaseCodeEditorFormInputComponent</code>


* Implements: <code><a href='/reference/admin-ui-api/custom-input-components/form-input-component#forminputcomponent'>FormInputComponent</a></code>, <code>AfterViewInit</code>, <code>OnInit</code>



<div className="members-wrapper">

### id

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/configurable-operation-def/default-form-component-id#defaultformcomponentid'>DefaultFormComponentId</a>`}   />


### constructor

<MemberInfo kind="method" type={`(changeDetector: ChangeDetectorRef) => JsonEditorFormInputComponent`}   />


### ngOnInit

<MemberInfo kind="method" type={`() => `}   />




</div>


## CombinationModeFormInputComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/dynamic-form-inputs/combination-mode-form-input/combination-mode-form-input.component.ts" sourceLine="17" packageName="@vendure/admin-ui" />

A special input used to display the "Combination mode" AND/OR toggle.

```ts title="Signature"
class CombinationModeFormInputComponent implements FormInputComponent, OnInit {
    static readonly id: DefaultFormComponentId = 'combination-mode-form-input';
    readonly: boolean;
    formControl: UntypedFormControl;
    config: DefaultFormComponentConfig<'combination-mode-form-input'>;
    selectable$: Observable<boolean>;
    constructor(configurableInputComponent: ConfigurableInputComponent)
    ngOnInit() => ;
    setCombinationModeAnd() => ;
    setCombinationModeOr() => ;
}
```
* Implements: <code><a href='/reference/admin-ui-api/custom-input-components/form-input-component#forminputcomponent'>FormInputComponent</a></code>, <code>OnInit</code>



<div className="members-wrapper">

### id

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/configurable-operation-def/default-form-component-id#defaultformcomponentid'>DefaultFormComponentId</a>`}   />


### readonly

<MemberInfo kind="property" type={`boolean`}   />


### formControl

<MemberInfo kind="property" type={`UntypedFormControl`}   />


### config

<MemberInfo kind="property" type={`DefaultFormComponentConfig&#60;'combination-mode-form-input'&#62;`}   />


### selectable$

<MemberInfo kind="property" type={`Observable&#60;boolean&#62;`}   />


### constructor

<MemberInfo kind="method" type={`(configurableInputComponent: ConfigurableInputComponent) => CombinationModeFormInputComponent`}   />


### ngOnInit

<MemberInfo kind="method" type={`() => `}   />


### setCombinationModeAnd

<MemberInfo kind="method" type={`() => `}   />


### setCombinationModeOr

<MemberInfo kind="method" type={`() => `}   />




</div>


## CurrencyFormInputComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/dynamic-form-inputs/currency-form-input/currency-form-input.component.ts" sourceLine="17" packageName="@vendure/admin-ui" />

An input for monetary values. Should be used with `int` type fields.

```ts title="Signature"
class CurrencyFormInputComponent implements FormInputComponent {
    static readonly id: DefaultFormComponentId = 'currency-form-input';
    @Input() readonly: boolean;
    formControl: UntypedFormControl;
    currencyCode$: Observable<CurrencyCode>;
    config: DefaultFormComponentConfig<'currency-form-input'>;
    constructor(dataService: DataService)
}
```
* Implements: <code><a href='/reference/admin-ui-api/custom-input-components/form-input-component#forminputcomponent'>FormInputComponent</a></code>



<div className="members-wrapper">

### id

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/configurable-operation-def/default-form-component-id#defaultformcomponentid'>DefaultFormComponentId</a>`}   />


### readonly

<MemberInfo kind="property" type={`boolean`}   />


### formControl

<MemberInfo kind="property" type={`UntypedFormControl`}   />


### currencyCode$

<MemberInfo kind="property" type={`Observable&#60;<a href='/reference/typescript-api/common/currency-code#currencycode'>CurrencyCode</a>&#62;`}   />


### config

<MemberInfo kind="property" type={`DefaultFormComponentConfig&#60;'currency-form-input'&#62;`}   />


### constructor

<MemberInfo kind="method" type={`(dataService: <a href='/reference/admin-ui-api/services/data-service#dataservice'>DataService</a>) => CurrencyFormInputComponent`}   />




</div>


## CustomerGroupFormInputComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/dynamic-form-inputs/customer-group-form-input/customer-group-form-input.component.ts" sourceLine="20" packageName="@vendure/admin-ui" />

Allows the selection of a Customer via an autocomplete select input.
Should be used with `ID` type fields which represent Customer IDs.

```ts title="Signature"
class CustomerGroupFormInputComponent implements FormInputComponent, OnInit {
    static readonly id: DefaultFormComponentId = 'customer-group-form-input';
    @Input() readonly: boolean;
    formControl: FormControl<string | { id: string }>;
    customerGroups$: Observable<GetCustomerGroupsQuery['customerGroups']['items']>;
    config: DefaultFormComponentConfig<'customer-group-form-input'>;
    constructor(dataService: DataService)
    ngOnInit() => ;
    selectGroup(group: ItemOf<GetCustomerGroupsQuery, 'customerGroups'>) => ;
    compareWith(o1: T, o2: T) => ;
}
```
* Implements: <code><a href='/reference/admin-ui-api/custom-input-components/form-input-component#forminputcomponent'>FormInputComponent</a></code>, <code>OnInit</code>



<div className="members-wrapper">

### id

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/configurable-operation-def/default-form-component-id#defaultformcomponentid'>DefaultFormComponentId</a>`}   />


### readonly

<MemberInfo kind="property" type={`boolean`}   />


### formControl

<MemberInfo kind="property" type={`FormControl&#60;string | { id: string }&#62;`}   />


### customerGroups$

<MemberInfo kind="property" type={`Observable&#60;GetCustomerGroupsQuery['customerGroups']['items']&#62;`}   />


### config

<MemberInfo kind="property" type={`DefaultFormComponentConfig&#60;'customer-group-form-input'&#62;`}   />


### constructor

<MemberInfo kind="method" type={`(dataService: <a href='/reference/admin-ui-api/services/data-service#dataservice'>DataService</a>) => CustomerGroupFormInputComponent`}   />


### ngOnInit

<MemberInfo kind="method" type={`() => `}   />


### selectGroup

<MemberInfo kind="method" type={`(group: ItemOf&#60;GetCustomerGroupsQuery, 'customerGroups'&#62;) => `}   />


### compareWith

<MemberInfo kind="method" type={`(o1: T, o2: T) => `}   />




</div>


## DateFormInputComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/dynamic-form-inputs/date-form-input/date-form-input.component.ts" sourceLine="14" packageName="@vendure/admin-ui" />

Allows selection of a datetime. Default input for `datetime` type fields.

```ts title="Signature"
class DateFormInputComponent implements FormInputComponent {
    static readonly id: DefaultFormComponentId = 'date-form-input';
    @Input() readonly: boolean;
    formControl: UntypedFormControl;
    config: DefaultFormComponentConfig<'date-form-input'>;
    min: void
    max: void
    yearRange: void
}
```
* Implements: <code><a href='/reference/admin-ui-api/custom-input-components/form-input-component#forminputcomponent'>FormInputComponent</a></code>



<div className="members-wrapper">

### id

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/configurable-operation-def/default-form-component-id#defaultformcomponentid'>DefaultFormComponentId</a>`}   />


### readonly

<MemberInfo kind="property" type={`boolean`}   />


### formControl

<MemberInfo kind="property" type={`UntypedFormControl`}   />


### config

<MemberInfo kind="property" type={`DefaultFormComponentConfig&#60;'date-form-input'&#62;`}   />


### min

<MemberInfo kind="property" type={``}   />


### max

<MemberInfo kind="property" type={``}   />


### yearRange

<MemberInfo kind="property" type={``}   />




</div>


## FacetValueFormInputComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/dynamic-form-inputs/facet-value-form-input/facet-value-form-input.component.ts" sourceLine="16" packageName="@vendure/admin-ui" />

Allows the selection of multiple FacetValues via an autocomplete select input.
Should be used with `ID` type **list** fields which represent FacetValue IDs.

```ts title="Signature"
class FacetValueFormInputComponent implements FormInputComponent {
    static readonly id: DefaultFormComponentId = 'facet-value-form-input';
    readonly isListInput = true;
    readonly: boolean;
    formControl: UntypedFormControl;
    config: InputComponentConfig;
    valueTransformFn = (values: FacetValueFragment[]) => {
        const isUsedInConfigArg = this.config.__typename === 'ConfigArgDefinition';
        if (isUsedInConfigArg) {
            return JSON.stringify(values.map(s => s.id));
        } else {
            return values;
        }
    };
}
```
* Implements: <code><a href='/reference/admin-ui-api/custom-input-components/form-input-component#forminputcomponent'>FormInputComponent</a></code>



<div className="members-wrapper">

### id

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/configurable-operation-def/default-form-component-id#defaultformcomponentid'>DefaultFormComponentId</a>`}   />


### isListInput

<MemberInfo kind="property" type={``}   />


### readonly

<MemberInfo kind="property" type={`boolean`}   />


### formControl

<MemberInfo kind="property" type={`UntypedFormControl`}   />


### config

<MemberInfo kind="property" type={`InputComponentConfig`}   />


### valueTransformFn

<MemberInfo kind="property" type={``}   />




</div>


## NumberFormInputComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/dynamic-form-inputs/number-form-input/number-form-input.component.ts" sourceLine="14" packageName="@vendure/admin-ui" />

Displays a number input. Default input for `int` and `float` type fields.

```ts title="Signature"
class NumberFormInputComponent implements FormInputComponent {
    static readonly id: DefaultFormComponentId = 'number-form-input';
    @Input() readonly: boolean;
    formControl: UntypedFormControl;
    config: DefaultFormComponentConfig<'number-form-input'>;
    prefix: void
    suffix: void
    min: void
    max: void
    step: void
}
```
* Implements: <code><a href='/reference/admin-ui-api/custom-input-components/form-input-component#forminputcomponent'>FormInputComponent</a></code>



<div className="members-wrapper">

### id

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/configurable-operation-def/default-form-component-id#defaultformcomponentid'>DefaultFormComponentId</a>`}   />


### readonly

<MemberInfo kind="property" type={`boolean`}   />


### formControl

<MemberInfo kind="property" type={`UntypedFormControl`}   />


### config

<MemberInfo kind="property" type={`DefaultFormComponentConfig&#60;'number-form-input'&#62;`}   />


### prefix

<MemberInfo kind="property" type={``}   />


### suffix

<MemberInfo kind="property" type={``}   />


### min

<MemberInfo kind="property" type={``}   />


### max

<MemberInfo kind="property" type={``}   />


### step

<MemberInfo kind="property" type={``}   />




</div>


## PasswordFormInputComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/dynamic-form-inputs/password-form-input/password-form-input.component.ts" sourceLine="14" packageName="@vendure/admin-ui" />

Displays a password text input. Should be used with `string` type fields.

```ts title="Signature"
class PasswordFormInputComponent implements FormInputComponent {
    static readonly id: DefaultFormComponentId = 'password-form-input';
    readonly: boolean;
    formControl: UntypedFormControl;
    config: InputComponentConfig;
}
```
* Implements: <code><a href='/reference/admin-ui-api/custom-input-components/form-input-component#forminputcomponent'>FormInputComponent</a></code>



<div className="members-wrapper">

### id

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/configurable-operation-def/default-form-component-id#defaultformcomponentid'>DefaultFormComponentId</a>`}   />


### readonly

<MemberInfo kind="property" type={`boolean`}   />


### formControl

<MemberInfo kind="property" type={`UntypedFormControl`}   />


### config

<MemberInfo kind="property" type={`InputComponentConfig`}   />




</div>


## ProductSelectorFormInputComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/dynamic-form-inputs/product-selector-form-input/product-selector-form-input.component.ts" sourceLine="20" packageName="@vendure/admin-ui" />

Allows the selection of multiple ProductVariants via an autocomplete select input.
Should be used with `ID` type **list** fields which represent ProductVariant IDs.

```ts title="Signature"
class ProductSelectorFormInputComponent implements FormInputComponent, OnInit {
    static readonly id: DefaultFormComponentId = 'product-selector-form-input';
    readonly isListInput = true;
    readonly: boolean;
    formControl: FormControl<Array<string | { id: string }>>;
    config: DefaultFormComponentUiConfig<'product-selector-form-input'>;
    selection$: Observable<Array<GetProductVariantQuery['productVariant']>>;
    constructor(dataService: DataService)
    ngOnInit() => ;
    addProductVariant(product: ProductSelectorSearchQuery['search']['items'][number]) => ;
    removeProductVariant(id: string) => ;
}
```
* Implements: <code><a href='/reference/admin-ui-api/custom-input-components/form-input-component#forminputcomponent'>FormInputComponent</a></code>, <code>OnInit</code>



<div className="members-wrapper">

### id

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/configurable-operation-def/default-form-component-id#defaultformcomponentid'>DefaultFormComponentId</a>`}   />


### isListInput

<MemberInfo kind="property" type={``}   />


### readonly

<MemberInfo kind="property" type={`boolean`}   />


### formControl

<MemberInfo kind="property" type={`FormControl&#60;Array&#60;string | { id: string }&#62;&#62;`}   />


### config

<MemberInfo kind="property" type={`DefaultFormComponentUiConfig&#60;'product-selector-form-input'&#62;`}   />


### selection$

<MemberInfo kind="property" type={`Observable&#60;Array&#60;GetProductVariantQuery['productVariant']&#62;&#62;`}   />


### constructor

<MemberInfo kind="method" type={`(dataService: <a href='/reference/admin-ui-api/services/data-service#dataservice'>DataService</a>) => ProductSelectorFormInputComponent`}   />


### ngOnInit

<MemberInfo kind="method" type={`() => `}   />


### addProductVariant

<MemberInfo kind="method" type={`(product: ProductSelectorSearchQuery['search']['items'][number]) => `}   />


### removeProductVariant

<MemberInfo kind="method" type={`(id: string) => `}   />




</div>


## RelationFormInputComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/dynamic-form-inputs/relation-form-input/relation-form-input.component.ts" sourceLine="17" packageName="@vendure/admin-ui" />

The default input component for `relation` type custom fields. Allows the selection
of a ProductVariant, Product, Customer or Asset. For other entity types, a custom
implementation will need to be defined. See <a href='/reference/admin-ui-api/custom-input-components/register-form-input-component#registerforminputcomponent'>registerFormInputComponent</a>.

```ts title="Signature"
class RelationFormInputComponent implements FormInputComponent {
    static readonly id: DefaultFormComponentId = 'relation-form-input';
    @Input() readonly: boolean;
    formControl: UntypedFormControl;
    config: RelationCustomFieldConfig;
}
```
* Implements: <code><a href='/reference/admin-ui-api/custom-input-components/form-input-component#forminputcomponent'>FormInputComponent</a></code>



<div className="members-wrapper">

### id

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/configurable-operation-def/default-form-component-id#defaultformcomponentid'>DefaultFormComponentId</a>`}   />


### readonly

<MemberInfo kind="property" type={`boolean`}   />


### formControl

<MemberInfo kind="property" type={`UntypedFormControl`}   />


### config

<MemberInfo kind="property" type={`RelationCustomFieldConfig`}   />




</div>


## RichTextFormInputComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/dynamic-form-inputs/rich-text-form-input/rich-text-form-input.component.ts" sourceLine="14" packageName="@vendure/admin-ui" />

Uses the <a href='/reference/admin-ui-api/components/rich-text-editor-component#richtexteditorcomponent'>RichTextEditorComponent</a> as in input for `text` type fields.

```ts title="Signature"
class RichTextFormInputComponent implements FormInputComponent {
    static readonly id: DefaultFormComponentId = 'rich-text-form-input';
    readonly: boolean;
    formControl: UntypedFormControl;
    config: DefaultFormComponentConfig<'rich-text-form-input'>;
}
```
* Implements: <code><a href='/reference/admin-ui-api/custom-input-components/form-input-component#forminputcomponent'>FormInputComponent</a></code>



<div className="members-wrapper">

### id

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/configurable-operation-def/default-form-component-id#defaultformcomponentid'>DefaultFormComponentId</a>`}   />


### readonly

<MemberInfo kind="property" type={`boolean`}   />


### formControl

<MemberInfo kind="property" type={`UntypedFormControl`}   />


### config

<MemberInfo kind="property" type={`DefaultFormComponentConfig&#60;'rich-text-form-input'&#62;`}   />




</div>


## SelectFormInputComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/dynamic-form-inputs/select-form-input/select-form-input.component.ts" sourceLine="18" packageName="@vendure/admin-ui" />

Uses a select input to allow the selection of a string value. Should be used with
`string` type fields with options.

```ts title="Signature"
class SelectFormInputComponent implements FormInputComponent, OnInit {
    static readonly id: DefaultFormComponentId = 'select-form-input';
    @Input() readonly: boolean;
    formControl: UntypedFormControl;
    config: DefaultFormComponentConfig<'select-form-input'> & CustomFieldConfigFragment;
    uiLanguage$: Observable<LanguageCode>;
    options: void
    constructor(dataService: DataService)
    ngOnInit() => ;
    trackByFn(index: number, item: any) => ;
}
```
* Implements: <code><a href='/reference/admin-ui-api/custom-input-components/form-input-component#forminputcomponent'>FormInputComponent</a></code>, <code>OnInit</code>



<div className="members-wrapper">

### id

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/configurable-operation-def/default-form-component-id#defaultformcomponentid'>DefaultFormComponentId</a>`}   />


### readonly

<MemberInfo kind="property" type={`boolean`}   />


### formControl

<MemberInfo kind="property" type={`UntypedFormControl`}   />


### config

<MemberInfo kind="property" type={`DefaultFormComponentConfig&#60;'select-form-input'&#62; &#38; CustomFieldConfigFragment`}   />


### uiLanguage$

<MemberInfo kind="property" type={`Observable&#60;<a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a>&#62;`}   />


### options

<MemberInfo kind="property" type={``}   />


### constructor

<MemberInfo kind="method" type={`(dataService: <a href='/reference/admin-ui-api/services/data-service#dataservice'>DataService</a>) => SelectFormInputComponent`}   />


### ngOnInit

<MemberInfo kind="method" type={`() => `}   />


### trackByFn

<MemberInfo kind="method" type={`(index: number, item: any) => `}   />




</div>


## StructFormInputComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/dynamic-form-inputs/struct-form-input/struct-form-input.component.ts" sourceLine="18" packageName="@vendure/admin-ui" />

A checkbox input. The default input component for `boolean` fields.

```ts title="Signature"
class StructFormInputComponent implements FormInputComponent, OnInit, OnDestroy {
    static readonly id: DefaultFormComponentId = 'struct-form-input';
    readonly: boolean;
    formControl: UntypedFormControl;
    config: DefaultFormComponentConfig<'struct-form-input'>;
    uiLanguage$: Observable<LanguageCode>;
    protected structFormGroup = new FormGroup({});
    protected fields: Array<{
        def: StructCustomFieldFragment['fields'][number];
        formControl: FormControl;
    }>;
    constructor(dataService: DataService)
    ngOnInit() => ;
    ngOnDestroy() => ;
}
```
* Implements: <code><a href='/reference/admin-ui-api/custom-input-components/form-input-component#forminputcomponent'>FormInputComponent</a></code>, <code>OnInit</code>, <code>OnDestroy</code>



<div className="members-wrapper">

### id

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/configurable-operation-def/default-form-component-id#defaultformcomponentid'>DefaultFormComponentId</a>`}   />


### readonly

<MemberInfo kind="property" type={`boolean`}   />


### formControl

<MemberInfo kind="property" type={`UntypedFormControl`}   />


### config

<MemberInfo kind="property" type={`DefaultFormComponentConfig&#60;'struct-form-input'&#62;`}   />


### uiLanguage$

<MemberInfo kind="property" type={`Observable&#60;<a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a>&#62;`}   />


### structFormGroup

<MemberInfo kind="property" type={``}   />


### fields

<MemberInfo kind="property" type={`Array&#60;{         def: StructCustomFieldFragment['fields'][number];         formControl: FormControl;     }&#62;`}   />


### constructor

<MemberInfo kind="method" type={`(dataService: <a href='/reference/admin-ui-api/services/data-service#dataservice'>DataService</a>) => StructFormInputComponent`}   />


### ngOnInit

<MemberInfo kind="method" type={`() => `}   />


### ngOnDestroy

<MemberInfo kind="method" type={`() => `}   />




</div>


## TextFormInputComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/dynamic-form-inputs/text-form-input/text-form-input.component.ts" sourceLine="14" packageName="@vendure/admin-ui" />

Uses a regular text form input. This is the default input for `string` and `localeString` type fields.

```ts title="Signature"
class TextFormInputComponent implements FormInputComponent {
    static readonly id: DefaultFormComponentId = 'text-form-input';
    readonly: boolean;
    formControl: UntypedFormControl;
    config: DefaultFormComponentConfig<'text-form-input'>;
    prefix: void
    suffix: void
}
```
* Implements: <code><a href='/reference/admin-ui-api/custom-input-components/form-input-component#forminputcomponent'>FormInputComponent</a></code>



<div className="members-wrapper">

### id

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/configurable-operation-def/default-form-component-id#defaultformcomponentid'>DefaultFormComponentId</a>`}   />


### readonly

<MemberInfo kind="property" type={`boolean`}   />


### formControl

<MemberInfo kind="property" type={`UntypedFormControl`}   />


### config

<MemberInfo kind="property" type={`DefaultFormComponentConfig&#60;'text-form-input'&#62;`}   />


### prefix

<MemberInfo kind="property" type={``}   />


### suffix

<MemberInfo kind="property" type={``}   />




</div>


## TextareaFormInputComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/dynamic-form-inputs/textarea-form-input/textarea-form-input.component.ts" sourceLine="14" packageName="@vendure/admin-ui" />

Uses textarea form input. This is the default input for `text` type fields.

```ts title="Signature"
class TextareaFormInputComponent implements FormInputComponent {
    static readonly id: DefaultFormComponentId = 'textarea-form-input';
    readonly: boolean;
    formControl: UntypedFormControl;
    config: DefaultFormComponentConfig<'textarea-form-input'>;
    spellcheck: boolean
}
```
* Implements: <code><a href='/reference/admin-ui-api/custom-input-components/form-input-component#forminputcomponent'>FormInputComponent</a></code>



<div className="members-wrapper">

### id

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/configurable-operation-def/default-form-component-id#defaultformcomponentid'>DefaultFormComponentId</a>`}   />


### readonly

<MemberInfo kind="property" type={`boolean`}   />


### formControl

<MemberInfo kind="property" type={`UntypedFormControl`}   />


### config

<MemberInfo kind="property" type={`DefaultFormComponentConfig&#60;'textarea-form-input'&#62;`}   />


### spellcheck

<MemberInfo kind="property" type={`boolean`}   />




</div>


---

---
title: "FormInputComponent"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## FormInputComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/common/component-registry-types.ts" sourceLine="11" packageName="@vendure/admin-ui" />

This interface should be implemented by any component being used as a custom input. For example,
inputs for custom fields, or for configurable arguments.

```ts title="Signature"
interface FormInputComponent<C = InputComponentConfig> {
    isListInput?: boolean;
    readonly: boolean;
    formControl: FormControl;
    config: C;
}
```

<div className="members-wrapper">

### isListInput

<MemberInfo kind="property" type={`boolean`}   />

Should be set to `true` if this component is designed to handle lists.
If `true` then the formControl value will be an array of all the
values in the list.
### readonly

<MemberInfo kind="property" type={`boolean`}   />

This is set by the Admin UI when consuming this component, indicating that the
component should be rendered in a read-only state.
### formControl

<MemberInfo kind="property" type={`FormControl`}   />

This controls the actual value of the form item. The current value is available
as `this.formControl.value`, and an Observable stream of value changes is available
as `this.formControl.valueChanges`. To update the value, use `.setValue(val)` and then
`.markAsDirty()`.

Full documentation can be found in the [Angular docs](https://angular.io/api/forms/FormControl).
### config

<MemberInfo kind="property" type={`C`}   />

The `config` property contains the full configuration object of the custom field or configurable argument.


</div>


---

---
title: "Custom Input Components"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "RegisterFormInputComponent"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## registerFormInputComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/extension/register-form-input-component.ts" sourceLine="53" packageName="@vendure/admin-ui" />

Registers a custom FormInputComponent which can be used to control the argument inputs
of a <a href='/reference/typescript-api/configurable-operation-def/#configurableoperationdef'>ConfigurableOperationDef</a> (e.g. CollectionFilter, ShippingMethod etc.) or for
a custom field.

*Example*

```ts title="providers.ts"
import { registerFormInputComponent } from '@vendure/admin-ui/core';

export default [
    // highlight-next-line
    registerFormInputComponent('my-custom-input', MyCustomFieldControl),
];
```

This input component can then be used in a custom field:

*Example*

```ts title="src/vendure-config.ts"
import { VendureConfig } from '@vendure/core';

const config: VendureConfig = {
  // ...
  customFields: {
    ProductVariant: [
      {
        name: 'rrp',
        type: 'int',
        // highlight-next-line
        ui: { component: 'my-custom-input' },
      },
    ]
  }
}
```

or with an argument of a <a href='/reference/typescript-api/configurable-operation-def/#configurableoperationdef'>ConfigurableOperationDef</a>:

*Example*

```ts
args: {
  rrp: { type: 'int', ui: { component: 'my-custom-input' } },
}
```

```ts title="Signature"
function registerFormInputComponent(id: string, component: Type<FormInputComponent>): void
```
Parameters

### id

<MemberInfo kind="parameter" type={`string`} />

### component

<MemberInfo kind="parameter" type={`Type&#60;<a href='/reference/admin-ui-api/custom-input-components/form-input-component#forminputcomponent'>FormInputComponent</a>&#62;`} />



---

---
title: "CustomColumnComponent"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## CustomColumnComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/components/data-table-2/data-table-custom-component.service.ts" sourceLine="44" packageName="@vendure/admin-ui" />

Components which are to be used to render custom cells in a data table should implement this interface.

The `rowItem` property is the data object for the row, e.g. the `Product` object if used
in the `product-list` table.

```ts title="Signature"
interface CustomColumnComponent {
    rowItem: any;
}
```

<div className="members-wrapper">

### rowItem

<MemberInfo kind="property" type={`any`}   />




</div>


---

---
title: "DataTableComponentConfig"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DataTableComponentConfig

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/components/data-table-2/data-table-custom-component.service.ts" sourceLine="54" packageName="@vendure/admin-ui" />

Configures a <a href='/reference/admin-ui-api/custom-detail-components/custom-detail-component#customdetailcomponent'>CustomDetailComponent</a> to be placed in the given location.

```ts title="Signature"
interface DataTableComponentConfig {
    tableId: DataTableLocationId;
    columnId: DataTableColumnId;
    component: Type<CustomColumnComponent>;
    providers?: Provider[];
}
```

<div className="members-wrapper">

### tableId

<MemberInfo kind="property" type={`DataTableLocationId`}   />

The location in the UI where the custom component should be placed.
### columnId

<MemberInfo kind="property" type={`DataTableColumnId`}   />

The column in the table where the custom component should be placed.
### component

<MemberInfo kind="property" type={`Type&#60;<a href='/reference/admin-ui-api/custom-table-components/custom-column-component#customcolumncomponent'>CustomColumnComponent</a>&#62;`}   />

The component to render in the table cell. This component should implement the
<a href='/reference/admin-ui-api/custom-table-components/custom-column-component#customcolumncomponent'>CustomColumnComponent</a> interface.
### providers

<MemberInfo kind="property" type={`Provider[]`}   />




</div>


---

---
title: "Custom Table Components"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "RegisterDataTableComponent"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## registerDataTableComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/extension/register-data-table-component.ts" sourceLine="45" packageName="@vendure/admin-ui" />

Allows you to override the default component used to render the data of a particular column in a DataTable.
The component should implement the <a href='/reference/admin-ui-api/custom-table-components/custom-column-component#customcolumncomponent'>CustomColumnComponent</a> interface. The tableId and columnId can
be determined by pressing `ctrl + u` when running the Admin UI in dev mode.

*Example*

```ts title="components/custom-table.component.ts"
import { Component, Input } from '@angular/core';
import { CustomColumnComponent } from '@vendure/admin-ui/core';

@Component({
    selector: 'custom-slug-component',
    template: `
        <a [href]="'https://example.com/products/' + rowItem.slug" target="_blank">{{ rowItem.slug }}</a>
    `,
    standalone: true,
})
export class CustomTableComponent implements CustomColumnComponent {
    @Input() rowItem: any;
}
```

```ts title="providers.ts"
import { registerDataTableComponent } from '@vendure/admin-ui/core';
import { CustomTableComponent } from './components/custom-table.component';

export default [
    registerDataTableComponent({
        component: CustomTableComponent,
        tableId: 'product-list',
        columnId: 'slug',
    }),
];
```

```ts title="Signature"
function registerDataTableComponent(config: DataTableComponentConfig): void
```
Parameters

### config

<MemberInfo kind="parameter" type={`<a href='/reference/admin-ui-api/custom-table-components/data-table-component-config#datatablecomponentconfig'>DataTableComponentConfig</a>`} />



---

---
title: "DashboardWidgetConfig"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DashboardWidgetConfig

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/providers/dashboard-widget/dashboard-widget-types.ts" sourceLine="11" packageName="@vendure/admin-ui" />

A configuration object for a dashboard widget.

```ts title="Signature"
interface DashboardWidgetConfig {
    loadComponent: () => Promise<Type<any>> | Type<any>;
    title?: string;
    supportedWidths?: DashboardWidgetWidth[];
    requiresPermissions?: string[];
}
```

<div className="members-wrapper">

### loadComponent

<MemberInfo kind="property" type={`() =&#62; Promise&#60;Type&#60;any&#62;&#62; | Type&#60;any&#62;`}   />

Used to specify the widget component. Supports both eager- and lazy-loading.

*Example*

```ts
// eager-loading
loadComponent: () => MyWidgetComponent,

// lazy-loading
loadComponent: () => import('./path-to/widget.component').then(m => m.MyWidgetComponent),
```
### title

<MemberInfo kind="property" type={`string`}   />

The title of the widget. Can be a translation token as it will get passed
through the `translate` pipe.
### supportedWidths

<MemberInfo kind="property" type={`DashboardWidgetWidth[]`}   />

The supported widths of the widget, in terms of a Bootstrap-style 12-column grid.
If omitted, then it is assumed the widget supports all widths.
### requiresPermissions

<MemberInfo kind="property" type={`string[]`}   />

If set, the widget will only be displayed if the current user has all the
specified permissions.


</div>


---

---
title: "Dashboard Widgets"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "RegisterDashboardWidget"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## registerDashboardWidget

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/extension/register-dashboard-widget.ts" sourceLine="16" packageName="@vendure/admin-ui" />

Registers a dashboard widget. Once registered, the widget can be set as part of the default
(using <a href='/reference/admin-ui-api/dashboard-widgets/set-dashboard-widget-layout#setdashboardwidgetlayout'>setDashboardWidgetLayout</a>).

```ts title="Signature"
function registerDashboardWidget(id: string, config: DashboardWidgetConfig): void
```
Parameters

### id

<MemberInfo kind="parameter" type={`string`} />

### config

<MemberInfo kind="parameter" type={`<a href='/reference/admin-ui-api/dashboard-widgets/dashboard-widget-config#dashboardwidgetconfig'>DashboardWidgetConfig</a>`} />



---

---
title: "SetDashboardWidgetLayout"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## setDashboardWidgetLayout

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/extension/register-dashboard-widget.ts" sourceLine="31" packageName="@vendure/admin-ui" />

Sets the default widget layout for the Admin UI dashboard.

```ts title="Signature"
function setDashboardWidgetLayout(layoutDef: WidgetLayoutDefinition): void
```
Parameters

### layoutDef

<MemberInfo kind="parameter" type={`<a href='/reference/admin-ui-api/dashboard-widgets/widget-layout-definition#widgetlayoutdefinition'>WidgetLayoutDefinition</a>`} />



---

---
title: "WidgetLayoutDefinition"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## WidgetLayoutDefinition

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/providers/dashboard-widget/dashboard-widget-types.ts" sourceLine="51" packageName="@vendure/admin-ui" />

A configuration object for the default dashboard widget layout.

```ts title="Signature"
type WidgetLayoutDefinition = Array<{ id: string; width: DashboardWidgetWidth }>
```


---

---
title: "IfMultichannelDirective"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## IfMultichannelDirective

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/directives/if-multichannel.directive.ts" sourceLine="21" packageName="@vendure/admin-ui" />

Structural directive that displays the given element if the Vendure instance has multiple channels
configured.

*Example*

```html
<div *vdrIfMultichannel class="channel-selector">
  <!-- ... -->
</ng-container>
```

```ts title="Signature"
class IfMultichannelDirective extends IfDirectiveBase<[]> {
    constructor(_viewContainer: ViewContainerRef, templateRef: TemplateRef<any>, dataService: DataService)
}
```
* Extends: <code>IfDirectiveBase&#60;[]&#62;</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(_viewContainer: ViewContainerRef, templateRef: TemplateRef&#60;any&#62;, dataService: <a href='/reference/admin-ui-api/services/data-service#dataservice'>DataService</a>) => IfMultichannelDirective`}   />




</div>


---

---
title: "IfPermissionsDirective"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## IfPermissionsDirective

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/directives/if-permissions.directive.ts" sourceLine="26" packageName="@vendure/admin-ui" />

Conditionally shows/hides templates based on the current active user having the specified permission.
Based on the ngIf source. Also support "else" templates:

*Example*

```html
<button *vdrIfPermissions="'DeleteCatalog'; else unauthorized">Delete Product</button>
<ng-template #unauthorized>Not allowed!</ng-template>
```

The permission can be a single string, or an array. If an array is passed, then _all_ of the permissions
must match (logical AND)

```ts title="Signature"
class IfPermissionsDirective extends IfDirectiveBase<Array<Permission[] | null>> {
    constructor(_viewContainer: ViewContainerRef, templateRef: TemplateRef<any>, changeDetectorRef: ChangeDetectorRef, permissionsService: PermissionsService)
}
```
* Extends: <code>IfDirectiveBase&#60;Array&#60;<a href='/reference/typescript-api/common/permission#permission'>Permission</a>[] | null&#62;&#62;</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(_viewContainer: ViewContainerRef, templateRef: TemplateRef&#60;any&#62;, changeDetectorRef: ChangeDetectorRef, permissionsService: PermissionsService) => IfPermissionsDirective`}   />




</div>


---

---
title: "Directives"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "Admin UI API"
weight: 10
showtoc: false
---

# Vendure Admin UI API Docs

These APIs are used when building your own custom extensions to the Admin UI provided by the AdminUiPlugin.

:::note
All documentation in this section is auto-generated from the TypeScript & HTML source of the Vendure Admin UI package.
:::


---

---
title: "BaseDetailComponent"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## BaseDetailComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/common/base-detail.component.ts" sourceLine="57" packageName="@vendure/admin-ui" />

A base class for entity detail views. It should be used in conjunction with the
<a href='/reference/admin-ui-api/list-detail-views/base-entity-resolver#baseentityresolver'>BaseEntityResolver</a>.

*Example*

```ts
@Component({
  selector: 'app-my-entity',
  templateUrl: './my-entity.component.html',
  styleUrls: ['./my-entity.component.scss'],
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class GlobalSettingsComponent extends BaseDetailComponent<MyEntityFragment> implements OnInit {
  detailForm: FormGroup;

  constructor(
    router: Router,
    route: ActivatedRoute,
    serverConfigService: ServerConfigService,
    protected dataService: DataService,
    private formBuilder: FormBuilder,
  ) {
    super(route, router, serverConfigService, dataService);
    this.detailForm = this.formBuilder.group({
      name: [''],
    });
  }

  protected setFormValues(entity: MyEntityFragment, languageCode: LanguageCode): void {
    this.detailForm.patchValue({
      name: entity.name,
    });
  }
}
```

```ts title="Signature"
class BaseDetailComponent<Entity extends { id: string; updatedAt?: string }> implements DeactivateAware {
    entity$: Observable<Entity>;
    availableLanguages$: Observable<LanguageCode[]>;
    languageCode$: Observable<LanguageCode>;
    languageCode: LanguageCode;
    isNew$: Observable<boolean>;
    id: string;
    abstract detailForm: UntypedFormGroup;
    protected destroy$ = new Subject<void>();
    constructor(route: ActivatedRoute, router: Router, serverConfigService: ServerConfigService, dataService: DataService, permissionsService: PermissionsService)
    init() => ;
    setUpStreams() => ;
    destroy() => ;
    setLanguage(code: LanguageCode) => ;
    canDeactivate() => boolean;
    setFormValues(entity: Entity, languageCode: LanguageCode) => void;
    setCustomFieldFormValues(customFields: CustomFieldConfig[], formGroup: AbstractControl | null, entity: T, currentTranslation?: TranslationOf<T>) => ;
    getCustomFieldConfig(key: Exclude<keyof CustomFields, '__typename'>) => CustomFieldConfig[];
    setQueryParam(key: string, value: any) => ;
}
```
* Implements: <code>DeactivateAware</code>



<div className="members-wrapper">

### entity$

<MemberInfo kind="property" type={`Observable&#60;Entity&#62;`}   />


### availableLanguages$

<MemberInfo kind="property" type={`Observable&#60;<a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a>[]&#62;`}   />


### languageCode$

<MemberInfo kind="property" type={`Observable&#60;<a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a>&#62;`}   />


### languageCode

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a>`}   />


### isNew$

<MemberInfo kind="property" type={`Observable&#60;boolean&#62;`}   />


### id

<MemberInfo kind="property" type={`string`}   />


### detailForm

<MemberInfo kind="property" type={`UntypedFormGroup`}   />


### destroy$

<MemberInfo kind="property" type={``}   />


### constructor

<MemberInfo kind="method" type={`(route: ActivatedRoute, router: Router, serverConfigService: ServerConfigService, dataService: <a href='/reference/admin-ui-api/services/data-service#dataservice'>DataService</a>, permissionsService: PermissionsService) => BaseDetailComponent`}   />


### init

<MemberInfo kind="method" type={`() => `}   />


### setUpStreams

<MemberInfo kind="method" type={`() => `}   />


### destroy

<MemberInfo kind="method" type={`() => `}   />


### setLanguage

<MemberInfo kind="method" type={`(code: <a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a>) => `}   />


### canDeactivate

<MemberInfo kind="method" type={`() => boolean`}   />


### setFormValues

<MemberInfo kind="method" type={`(entity: Entity, languageCode: <a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a>) => void`}   />


### setCustomFieldFormValues

<MemberInfo kind="method" type={`(customFields: <a href='/reference/typescript-api/custom-fields/custom-field-config#customfieldconfig'>CustomFieldConfig</a>[], formGroup: AbstractControl | null, entity: T, currentTranslation?: TranslationOf&#60;T&#62;) => `}   />


### getCustomFieldConfig

<MemberInfo kind="method" type={`(key: Exclude&#60;keyof <a href='/reference/typescript-api/custom-fields/#customfields'>CustomFields</a>, '__typename'&#62;) => <a href='/reference/typescript-api/custom-fields/custom-field-config#customfieldconfig'>CustomFieldConfig</a>[]`}   />


### setQueryParam

<MemberInfo kind="method" type={`(key: string, value: any) => `}   />




</div>


---

---
title: "BaseEntityResolver"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## BaseEntityResolver

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/common/base-entity-resolver.ts" sourceLine="55" packageName="@vendure/admin-ui" />

A base resolver for an entity detail route. Resolves to an observable of the given entity, or a "blank"
version if the route id equals "create". Should be used together with details views which extend the
<a href='/reference/admin-ui-api/list-detail-views/base-detail-component#basedetailcomponent'>BaseDetailComponent</a>.

*Example*

```ts
@Injectable({
  providedIn: 'root',
})
export class MyEntityResolver extends BaseEntityResolver<MyEntityFragment> {
  constructor(router: Router, dataService: DataService) {
    super(
      router,
      {
        __typename: 'MyEntity',
        id: '',
        createdAt: '',
        updatedAt: '',
        name: '',
      },
      id => dataService.query(GET_MY_ENTITY, { id }).mapStream(data => data.myEntity),
    );
  }
}
```

```ts title="Signature"
class BaseEntityResolver<T> {
    constructor(router: Router, emptyEntity: T, entityStream: (id: string) => Observable<T | null | undefined>)
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(router: Router, emptyEntity: T, entityStream: (id: string) =&#62; Observable&#60;T | null | undefined&#62;) => BaseEntityResolver`}   />




</div>


---

---
title: "BaseListComponent"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## BaseListComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/common/base-list.component.ts" sourceLine="43" packageName="@vendure/admin-ui" />

This is a base class which implements the logic required to fetch and manipulate
a list of data from a query which returns a PaginatedList type.

It is normally used in combination with the <a href='/reference/admin-ui-api/components/data-table2component#datatable2component'>DataTable2Component</a>.

```ts title="Signature"
class BaseListComponent<ResultType, ItemType, VariableType extends Record<string, any> = any> implements OnInit, OnDestroy {
    searchTermControl = new FormControl('');
    selectionManager = new SelectionManager<any>({
        multiSelect: true,
        itemsAreEqual: (a, b) => a.id === b.id,
        additiveMode: true,
    });
    result$: Observable<ResultType>;
    items$: Observable<ItemType[]>;
    totalItems$: Observable<number>;
    itemsPerPage$: Observable<number>;
    currentPage$: Observable<number>;
    protected destroy$ = new Subject<void>();
    protected refresh$ = new BehaviorSubject<undefined>(undefined);
    protected visibleCustomFieldColumnChange$ = new Subject<
        Array<DataTableCustomFieldColumnComponent<any>>
    >();
    constructor(router: Router, route: ActivatedRoute)
    setQueryFn(listQueryFn: ListQueryFn<ResultType>, mappingFn: MappingFn<ItemType, ResultType>, onPageChangeFn?: OnPageChangeFn<VariableType>, defaults?: { take: number; skip: number }) => ;
    refreshListOnChanges(streams: Array<Observable<any>>) => ;
    setPageNumber(page: number) => ;
    setItemsPerPage(perPage: number) => ;
    setVisibleColumns(columns: Array<DataTable2ColumnComponent<any>>) => ;
    refresh() => ;
    setQueryParam(hash: { [key: string]: any }, options?: { replaceUrl?: boolean; queryParamsHandling?: QueryParamsHandling }) => ;
    setQueryParam(key: string, value: any, options?: { replaceUrl?: boolean; queryParamsHandling?: QueryParamsHandling }) => ;
    setQueryParam(keyOrHash: string | { [key: string]: any }, valueOrOptions?: any, maybeOptions?: { replaceUrl?: boolean; queryParamsHandling?: QueryParamsHandling }) => ;
}
```
* Implements: <code>OnInit</code>, <code>OnDestroy</code>



<div className="members-wrapper">

### searchTermControl

<MemberInfo kind="property" type={``}   />


### selectionManager

<MemberInfo kind="property" type={``}   />


### result$

<MemberInfo kind="property" type={`Observable&#60;ResultType&#62;`}   />


### items$

<MemberInfo kind="property" type={`Observable&#60;ItemType[]&#62;`}   />


### totalItems$

<MemberInfo kind="property" type={`Observable&#60;number&#62;`}   />


### itemsPerPage$

<MemberInfo kind="property" type={`Observable&#60;number&#62;`}   />


### currentPage$

<MemberInfo kind="property" type={`Observable&#60;number&#62;`}   />


### destroy$

<MemberInfo kind="property" type={``}   />


### refresh$

<MemberInfo kind="property" type={``}   />


### visibleCustomFieldColumnChange$

<MemberInfo kind="property" type={``}   />


### constructor

<MemberInfo kind="method" type={`(router: Router, route: ActivatedRoute) => BaseListComponent`}   />


### setQueryFn

<MemberInfo kind="method" type={`(listQueryFn: ListQueryFn&#60;ResultType&#62;, mappingFn: MappingFn&#60;ItemType, ResultType&#62;, onPageChangeFn?: OnPageChangeFn&#60;VariableType&#62;, defaults?: { take: number; skip: number }) => `}   />

Sets the fetch function for the list being implemented.
### refreshListOnChanges

<MemberInfo kind="method" type={`(streams: Array&#60;Observable&#60;any&#62;&#62;) => `}   />

Accepts a list of Observables which will trigger a refresh of the list when any of them emit.
### setPageNumber

<MemberInfo kind="method" type={`(page: number) => `}   />

Sets the current page number in the url.
### setItemsPerPage

<MemberInfo kind="method" type={`(perPage: number) => `}   />

Sets the number of items per page in the url.
### setVisibleColumns

<MemberInfo kind="method" type={`(columns: Array&#60;DataTable2ColumnComponent&#60;any&#62;&#62;) => `}   />


### refresh

<MemberInfo kind="method" type={`() => `}   />

Re-fetch the current page of results.
### setQueryParam

<MemberInfo kind="method" type={`(hash: { [key: string]: any }, options?: { replaceUrl?: boolean; queryParamsHandling?: QueryParamsHandling }) => `}   />


### setQueryParam

<MemberInfo kind="method" type={`(key: string, value: any, options?: { replaceUrl?: boolean; queryParamsHandling?: QueryParamsHandling }) => `}   />


### setQueryParam

<MemberInfo kind="method" type={`(keyOrHash: string | { [key: string]: any }, valueOrOptions?: any, maybeOptions?: { replaceUrl?: boolean; queryParamsHandling?: QueryParamsHandling }) => `}   />




</div>


---

---
title: "DetailComponentWithResolver"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## detailComponentWithResolver

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/common/base-detail.component.ts" sourceLine="256" packageName="@vendure/admin-ui" />

A helper function for creating tabs that point to a <a href='/reference/admin-ui-api/list-detail-views/typed-base-detail-component#typedbasedetailcomponent'>TypedBaseDetailComponent</a>. This takes
care of the route resolver parts so that the detail component automatically has access to the
correct resolved detail data.

*Example*

```ts
@NgModule({
  imports: [ReviewsSharedModule],
  declarations: [/* ... *\/],
  providers: [
    registerPageTab({
      location: 'product-detail',
      tab: 'Specs',
      route: 'specs',
      component: detailComponentWithResolver({
        component: ProductSpecDetailComponent,
        query: GetProductSpecsDocument,
        entityKey: 'spec',
      }),
    }),
  ],
})
export class ProductSpecsUiExtensionModule {}
```

```ts title="Signature"
function detailComponentWithResolver<T extends TypedDocumentNode<any, { id: string }>, Field extends keyof ResultOf<T>, R extends Field>(config: {
    component: Type<TypedBaseDetailComponent<T, Field>>;
    query: T;
    entityKey: R;
    getBreadcrumbs?: (entity: ResultOf<T>[R]) => BreadcrumbValue;
    variables?: T extends TypedDocumentNode<any, infer V> ? Omit<V, 'id'> : never;
}): void
```
Parameters

### config

<MemberInfo kind="parameter" type={`{     component: Type&#60;<a href='/reference/admin-ui-api/list-detail-views/typed-base-detail-component#typedbasedetailcomponent'>TypedBaseDetailComponent</a>&#60;T, Field&#62;&#62;;     query: T;     entityKey: R;     getBreadcrumbs?: (entity: ResultOf&#60;T&#62;[R]) =&#62; BreadcrumbValue;     variables?: T extends TypedDocumentNode&#60;any, infer V&#62; ? Omit&#60;V, 'id'&#62; : never; }`} />



---

---
title: "List Detail Views"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "TypedBaseDetailComponent"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## TypedBaseDetailComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/common/base-detail.component.ts" sourceLine="186" packageName="@vendure/admin-ui" />

A version of the <a href='/reference/admin-ui-api/list-detail-views/base-detail-component#basedetailcomponent'>BaseDetailComponent</a> which is designed to be used with a
[TypedDocumentNode](https://the-guild.dev/graphql/codegen/plugins/typescript/typed-document-node).

```ts title="Signature"
class TypedBaseDetailComponent<T extends TypedDocumentNode<any, any>, Field extends keyof ResultOf<T>> extends BaseDetailComponent<NonNullable<ResultOf<T>[Field]>> {
    protected result$: Observable<ResultOf<T>>;
    protected entity: ResultOf<T>[Field];
    constructor()
    init() => ;
}
```
* Extends: <code><a href='/reference/admin-ui-api/list-detail-views/base-detail-component#basedetailcomponent'>BaseDetailComponent</a>&#60;NonNullable&#60;ResultOf&#60;T&#62;[Field]&#62;&#62;</code>



<div className="members-wrapper">

### result$

<MemberInfo kind="property" type={`Observable&#60;ResultOf&#60;T&#62;&#62;`}   />


### entity

<MemberInfo kind="property" type={`ResultOf&#60;T&#62;[Field]`}   />


### constructor

<MemberInfo kind="method" type={`() => TypedBaseDetailComponent`}   />


### init

<MemberInfo kind="method" type={`() => `}   />




</div>


---

---
title: "TypedBaseListComponent"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## TypedBaseListComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/common/base-list.component.ts" sourceLine="217" packageName="@vendure/admin-ui" />

A version of the <a href='/reference/admin-ui-api/list-detail-views/base-list-component#baselistcomponent'>BaseListComponent</a> which is designed to be used with a
[TypedDocumentNode](https://the-guild.dev/graphql/codegen/plugins/typescript/typed-document-node).

```ts title="Signature"
class TypedBaseListComponent<T extends TypedDocumentNode<any, Vars>, Field extends keyof ResultOf<T>, Vars extends { options: { filter: any; sort: any } } = VariablesOf<T>> extends BaseListComponent<ResultOf<T>, ItemOf<ResultOf<T>, Field>, VariablesOf<T>> implements OnInit {
    availableLanguages$: Observable<LanguageCode[]>;
    contentLanguage$: Observable<LanguageCode>;
    protected dataService = inject(DataService);
    protected router = inject(Router);
    protected serverConfigService = inject(ServerConfigService);
    protected permissionsService = inject(PermissionsService);
    protected dataTableConfigService = inject(DataTableConfigService);
    protected dataTableListId: string | undefined;
    constructor()
    configure(config: {
        document: T;
        getItems: (data: ResultOf<T>) => { items: Array<ItemOf<ResultOf<T>, Field>>; totalItems: number };
        setVariables?: (skip: number, take: number) => VariablesOf<T>;
        refreshListOnChanges?: Array<Observable<any>>;
    }) => ;
    ngOnInit() => ;
    createFilterCollection() => DataTableFilterCollection<NonNullable<NonNullable<Vars['options']>['filter']>>;
    createSortCollection() => DataTableSortCollection<NonNullable<NonNullable<Vars['options']>['sort']>>;
    setLanguage(code: LanguageCode) => ;
    getCustomFieldConfig(key: Exclude<keyof CustomFields, '__typename'> | string) => CustomFieldConfig[];
}
```
* Extends: <code><a href='/reference/admin-ui-api/list-detail-views/base-list-component#baselistcomponent'>BaseListComponent</a>&#60;ResultOf&#60;T&#62;, ItemOf&#60;ResultOf&#60;T&#62;, Field&#62;, VariablesOf&#60;T&#62;&#62;</code>


* Implements: <code>OnInit</code>



<div className="members-wrapper">

### availableLanguages$

<MemberInfo kind="property" type={`Observable&#60;<a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a>[]&#62;`}   />


### contentLanguage$

<MemberInfo kind="property" type={`Observable&#60;<a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a>&#62;`}   />


### dataService

<MemberInfo kind="property" type={``}   />


### router

<MemberInfo kind="property" type={``}   />


### serverConfigService

<MemberInfo kind="property" type={``}   />


### permissionsService

<MemberInfo kind="property" type={``}   />


### dataTableConfigService

<MemberInfo kind="property" type={``}   />


### dataTableListId

<MemberInfo kind="property" type={`string | undefined`}   />


### constructor

<MemberInfo kind="method" type={`() => TypedBaseListComponent`}   />


### configure

<MemberInfo kind="method" type={`(config: {         document: T;         getItems: (data: ResultOf&#60;T&#62;) =&#62; { items: Array&#60;ItemOf&#60;ResultOf&#60;T&#62;, Field&#62;&#62;; totalItems: number };         setVariables?: (skip: number, take: number) =&#62; VariablesOf&#60;T&#62;;         refreshListOnChanges?: Array&#60;Observable&#60;any&#62;&#62;;     }) => `}   />


### ngOnInit

<MemberInfo kind="method" type={`() => `}   />


### createFilterCollection

<MemberInfo kind="method" type={`() => DataTableFilterCollection&#60;NonNullable&#60;NonNullable&#60;Vars['options']&#62;['filter']&#62;&#62;`}   />


### createSortCollection

<MemberInfo kind="method" type={`() => DataTableSortCollection&#60;NonNullable&#60;NonNullable&#60;Vars['options']&#62;['sort']&#62;&#62;`}   />


### setLanguage

<MemberInfo kind="method" type={`(code: <a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a>) => `}   />


### getCustomFieldConfig

<MemberInfo kind="method" type={`(key: Exclude&#60;keyof <a href='/reference/typescript-api/custom-fields/#customfields'>CustomFields</a>, '__typename'&#62; | string) => <a href='/reference/typescript-api/custom-fields/custom-field-config#customfieldconfig'>CustomFieldConfig</a>[]`}   />




</div>


---

---
title: "AddNavMenuItem"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## addNavMenuItem

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/extension/add-nav-menu-item.ts" sourceLine="66" packageName="@vendure/admin-ui" />

Add a menu item to an existing section specified by `sectionId`. The id of the section
can be found by inspecting the DOM and finding the `data-section-id` attribute.
Providing the `before` argument will move the item before any existing item with the specified id.
If omitted (or if the name is not found) the item will be appended to the
end of the section.

This should be used in the NgModule `providers` array of your ui extension module.

*Example*

```ts title="providers.ts"
import { addNavMenuItem } from '@vendure/admin-ui/core';

export default [
    addNavMenuItem({
        id: 'reviews',
        label: 'Product Reviews',
        routerLink: ['/extensions/reviews'],
        icon: 'star',
    },
    'marketing'),
];
```

```ts title="Signature"
function addNavMenuItem(config: NavMenuItem, sectionId: string, before?: string): void
```
Parameters

### config

<MemberInfo kind="parameter" type={`<a href='/reference/admin-ui-api/nav-menu/nav-menu-item#navmenuitem'>NavMenuItem</a>`} />

### sectionId

<MemberInfo kind="parameter" type={`string`} />

### before

<MemberInfo kind="parameter" type={`string`} />



---

---
title: "AddNavMenuSection"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## addNavMenuSection

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/extension/add-nav-menu-item.ts" sourceLine="30" packageName="@vendure/admin-ui" />

Add a section to the main nav menu. Providing the `before` argument will
move the section before any existing section with the specified id. If
omitted (or if the id is not found) the section will be appended to the
existing set of sections.
This should be used in the NgModule `providers` array of your ui extension module.

*Example*

```ts title="providers.ts"
import { addNavMenuSection } from '@vendure/admin-ui/core';

export default [
    addNavMenuSection({
        id: 'reports',
        label: 'Reports',
        items: [{
            // ...
        }],
    },
    'settings'),
];
```

```ts title="Signature"
function addNavMenuSection(config: NavMenuSection, before?: string): void
```
Parameters

### config

<MemberInfo kind="parameter" type={`<a href='/reference/admin-ui-api/nav-menu/nav-menu-section#navmenusection'>NavMenuSection</a>`} />

### before

<MemberInfo kind="parameter" type={`string`} />



---

---
title: "Nav Menu"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "NavMenuItem"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## NavMenuItem

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/providers/nav-builder/nav-builder-types.ts" sourceLine="37" packageName="@vendure/admin-ui" />

A NavMenuItem is a menu item in the main (left-hand side) nav
bar.

```ts title="Signature"
interface NavMenuItem {
    id: string;
    label: string;
    routerLink: RouterLinkDefinition;
    onClick?: (event: MouseEvent) => void;
    icon?: string;
    requiresPermission?: string | ((userPermissions: string[]) => boolean);
    statusBadge?: Observable<NavMenuBadge>;
}
```

<div className="members-wrapper">

### id

<MemberInfo kind="property" type={`string`}   />


### label

<MemberInfo kind="property" type={`string`}   />


### routerLink

<MemberInfo kind="property" type={`<a href='/reference/admin-ui-api/action-bar/router-link-definition#routerlinkdefinition'>RouterLinkDefinition</a>`}   />


### onClick

<MemberInfo kind="property" type={`(event: MouseEvent) =&#62; void`}   />


### icon

<MemberInfo kind="property" type={`string`}   />


### requiresPermission

<MemberInfo kind="property" type={`string | ((userPermissions: string[]) =&#62; boolean)`}   />


### statusBadge

<MemberInfo kind="property" type={`Observable&#60;<a href='/reference/admin-ui-api/nav-menu/navigation-types#navmenubadge'>NavMenuBadge</a>&#62;`}   />




</div>


---

---
title: "NavMenuSection"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## NavMenuSection

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/providers/nav-builder/nav-builder-types.ts" sourceLine="57" packageName="@vendure/admin-ui" />

A NavMenuSection is a grouping of links in the main
(left-hand side) nav bar.

```ts title="Signature"
interface NavMenuSection {
    id: string;
    label: string;
    items: NavMenuItem[];
    icon?: string;
    displayMode?: 'regular' | 'settings';
    requiresPermission?: string | ((userPermissions: string[]) => boolean);
    collapsible?: boolean;
    collapsedByDefault?: boolean;
}
```

<div className="members-wrapper">

### id

<MemberInfo kind="property" type={`string`}   />


### label

<MemberInfo kind="property" type={`string`}   />


### items

<MemberInfo kind="property" type={`<a href='/reference/admin-ui-api/nav-menu/nav-menu-item#navmenuitem'>NavMenuItem</a>[]`}   />


### icon

<MemberInfo kind="property" type={`string`}   />


### displayMode

<MemberInfo kind="property" type={`'regular' | 'settings'`}   />


### requiresPermission

<MemberInfo kind="property" type={`string | ((userPermissions: string[]) =&#62; boolean)`}   />

Control the display of this item based on the user permissions. Note: if you attempt to pass a
<a href='/reference/typescript-api/auth/permission-definition#permissiondefinition'>PermissionDefinition</a> object, you will get a compilation error. Instead, pass the plain
string version. For example, if the permission is defined as:
```ts
export const MyPermission = new PermissionDefinition('ProductReview');
```
then the generated permission strings will be:

- `CreateProductReview`
- `ReadProductReview`
- `UpdateProductReview`
- `DeleteProductReview`
### collapsible

<MemberInfo kind="property" type={`boolean`}   />


### collapsedByDefault

<MemberInfo kind="property" type={`boolean`}   />




</div>


---

---
title: "Navigation Types"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## NavMenuBadge

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/providers/nav-builder/nav-builder-types.ts" sourceLine="19" packageName="@vendure/admin-ui" />

A color-coded notification badge which will be displayed by the
NavMenuItem's icon.

```ts title="Signature"
interface NavMenuBadge {
    type: NavMenuBadgeType;
    propagateToSection?: boolean;
}
```

<div className="members-wrapper">

### type

<MemberInfo kind="property" type={`NavMenuBadgeType`}   />


### propagateToSection

<MemberInfo kind="property" type={`boolean`}   />

If true, the badge will propagate to the NavMenuItem's
parent section, displaying a notification badge next
to the section name.


</div>


---

---
title: "AssetPreviewPipe"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## AssetPreviewPipe

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/pipes/asset-preview.pipe.ts" sourceLine="19" packageName="@vendure/admin-ui" />

Given an Asset object (an object with `preview` and optionally `focalPoint` properties), this pipe
returns a string with query parameters designed to work with the image resize capabilities of the
AssetServerPlugin.

*Example*

```HTML
<img [src]="asset | assetPreview:'tiny'" />
<img [src]="asset | assetPreview:150" />
```

```ts title="Signature"
class AssetPreviewPipe implements PipeTransform {
    transform(asset?: AssetFragment, preset: string | number = 'thumb') => string;
}
```
* Implements: <code>PipeTransform</code>



<div className="members-wrapper">

### transform

<MemberInfo kind="method" type={`(asset?: AssetFragment, preset: string | number = 'thumb') => string`}   />




</div>


---

---
title: "DurationPipe"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DurationPipe

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/pipes/duration.pipe.ts" sourceLine="18" packageName="@vendure/admin-ui" />

Displays a number of milliseconds in a more human-readable format,
e.g. "12ms", "33s", "2:03m"

*Example*

```ts
{{ timeInMs | duration }}
```

```ts title="Signature"
class DurationPipe implements PipeTransform {
    constructor(i18nService: I18nService)
    transform(value: number) => string;
}
```
* Implements: <code>PipeTransform</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(i18nService: <a href='/reference/typescript-api/common/i18n-service#i18nservice'>I18nService</a>) => DurationPipe`}   />


### transform

<MemberInfo kind="method" type={`(value: number) => string`}   />




</div>


---

---
title: "FileSizePipe"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## FileSizePipe

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/pipes/file-size.pipe.ts" sourceLine="14" packageName="@vendure/admin-ui" />

Formats a number into a human-readable file size string.

*Example*

```ts
{{ fileSizeInBytes | filesize }}
```

```ts title="Signature"
class FileSizePipe implements PipeTransform {
    transform(value: number, useSiUnits:  = true) => any;
}
```
* Implements: <code>PipeTransform</code>



<div className="members-wrapper">

### transform

<MemberInfo kind="method" type={`(value: number, useSiUnits:  = true) => any`}   />




</div>


---

---
title: "HasPermissionPipe"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## HasPermissionPipe

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/pipes/has-permission.pipe.ts" sourceLine="16" packageName="@vendure/admin-ui" />

A pipe which checks the provided permission against all the permissions of the current user.
Returns `true` if the current user has that permission.

*Example*

```HTML
<button [disabled]="!('UpdateCatalog' | hasPermission)">Save Changes</button>
```

```ts title="Signature"
class HasPermissionPipe implements PipeTransform, OnDestroy {
    constructor(permissionsService: PermissionsService, changeDetectorRef: ChangeDetectorRef)
    transform(input: string | string[]) => any;
    ngOnDestroy() => ;
}
```
* Implements: <code>PipeTransform</code>, <code>OnDestroy</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(permissionsService: PermissionsService, changeDetectorRef: ChangeDetectorRef) => HasPermissionPipe`}   />


### transform

<MemberInfo kind="method" type={`(input: string | string[]) => any`}   />


### ngOnDestroy

<MemberInfo kind="method" type={`() => `}   />




</div>


---

---
title: "Pipes"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "LocaleCurrencyNamePipe"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## LocaleCurrencyNamePipe

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/pipes/locale-currency-name.pipe.ts" sourceLine="18" packageName="@vendure/admin-ui" />

Displays a human-readable name for a given ISO 4217 currency code.

*Example*

```HTML
{{ order.currencyCode | localeCurrencyName }}
```

```ts title="Signature"
class LocaleCurrencyNamePipe extends LocaleBasePipe implements PipeTransform {
    constructor(dataService?: DataService, changeDetectorRef?: ChangeDetectorRef)
    transform(value: any, display: 'full' | 'symbol' | 'name' = 'full', locale?: unknown) => any;
}
```
* Extends: <code>LocaleBasePipe</code>


* Implements: <code>PipeTransform</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(dataService?: <a href='/reference/admin-ui-api/services/data-service#dataservice'>DataService</a>, changeDetectorRef?: ChangeDetectorRef) => LocaleCurrencyNamePipe`}   />


### transform

<MemberInfo kind="method" type={`(value: any, display: 'full' | 'symbol' | 'name' = 'full', locale?: unknown) => any`}   />




</div>


---

---
title: "LocaleCurrencyPipe"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## LocaleCurrencyPipe

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/pipes/locale-currency.pipe.ts" sourceLine="20" packageName="@vendure/admin-ui" />

Formats a Vendure monetary value (in cents) into the correct format for the configured currency and display
locale.

*Example*

```HTML
{{ variant.priceWithTax | localeCurrency }}
```

```ts title="Signature"
class LocaleCurrencyPipe extends LocaleBasePipe implements PipeTransform {
    readonly precisionFactor: number;
    constructor(currencyService: CurrencyService, dataService?: DataService, changeDetectorRef?: ChangeDetectorRef)
    transform(value: unknown, args: unknown[]) => string | unknown;
}
```
* Extends: <code>LocaleBasePipe</code>


* Implements: <code>PipeTransform</code>



<div className="members-wrapper">

### precisionFactor

<MemberInfo kind="property" type={`number`}   />


### constructor

<MemberInfo kind="method" type={`(currencyService: CurrencyService, dataService?: <a href='/reference/admin-ui-api/services/data-service#dataservice'>DataService</a>, changeDetectorRef?: ChangeDetectorRef) => LocaleCurrencyPipe`}   />


### transform

<MemberInfo kind="method" type={`(value: unknown, args: unknown[]) => string | unknown`}   />




</div>


---

---
title: "LocaleDatePipe"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## LocaleDatePipe

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/pipes/locale-date.pipe.ts" sourceLine="19" packageName="@vendure/admin-ui" />

A replacement of the Angular DatePipe which makes use of the Intl API
to format dates according to the selected UI language.

*Example*

```HTML
{{ order.orderPlacedAt | localeDate }}
```

```ts title="Signature"
class LocaleDatePipe extends LocaleBasePipe implements PipeTransform {
    constructor(dataService?: DataService, changeDetectorRef?: ChangeDetectorRef)
    transform(value: unknown, args: unknown[]) => unknown;
}
```
* Extends: <code>LocaleBasePipe</code>


* Implements: <code>PipeTransform</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(dataService?: <a href='/reference/admin-ui-api/services/data-service#dataservice'>DataService</a>, changeDetectorRef?: ChangeDetectorRef) => LocaleDatePipe`}   />


### transform

<MemberInfo kind="method" type={`(value: unknown, args: unknown[]) => unknown`}   />




</div>


---

---
title: "LocaleLanguageNamePipe"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## LocaleLanguageNamePipe

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/pipes/locale-language-name.pipe.ts" sourceLine="18" packageName="@vendure/admin-ui" />

Displays a human-readable name for a given ISO 639-1 language code.

*Example*

```HTML
{{ 'zh_Hant' | localeLanguageName }}
```

```ts title="Signature"
class LocaleLanguageNamePipe extends LocaleBasePipe implements PipeTransform {
    constructor(dataService?: DataService, changeDetectorRef?: ChangeDetectorRef)
    transform(value: any, locale?: unknown) => string;
}
```
* Extends: <code>LocaleBasePipe</code>


* Implements: <code>PipeTransform</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(dataService?: <a href='/reference/admin-ui-api/services/data-service#dataservice'>DataService</a>, changeDetectorRef?: ChangeDetectorRef) => LocaleLanguageNamePipe`}   />


### transform

<MemberInfo kind="method" type={`(value: any, locale?: unknown) => string`}   />




</div>


---

---
title: "LocaleRegionNamePipe"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## LocaleRegionNamePipe

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/pipes/locale-region-name.pipe.ts" sourceLine="18" packageName="@vendure/admin-ui" />

Displays a human-readable name for a given region.

*Example*

```HTML
{{ 'GB' | localeRegionName }}
```

```ts title="Signature"
class LocaleRegionNamePipe extends LocaleBasePipe implements PipeTransform {
    constructor(dataService?: DataService, changeDetectorRef?: ChangeDetectorRef)
    transform(value: any, locale?: unknown) => string;
}
```
* Extends: <code>LocaleBasePipe</code>


* Implements: <code>PipeTransform</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(dataService?: <a href='/reference/admin-ui-api/services/data-service#dataservice'>DataService</a>, changeDetectorRef?: ChangeDetectorRef) => LocaleRegionNamePipe`}   />


### transform

<MemberInfo kind="method" type={`(value: any, locale?: unknown) => string`}   />




</div>


---

---
title: "TimeAgoPipe"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## TimeAgoPipe

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/shared/pipes/time-ago.pipe.ts" sourceLine="18" packageName="@vendure/admin-ui" />

Converts a date into the format "3 minutes ago", "5 hours ago" etc.

*Example*

```HTML
{{ order.orderPlacedAt | timeAgo }}
```

```ts title="Signature"
class TimeAgoPipe implements PipeTransform {
    constructor(i18nService: I18nService)
    transform(value: string | Date, nowVal?: string | Date) => string;
}
```
* Implements: <code>PipeTransform</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(i18nService: <a href='/reference/typescript-api/common/i18n-service#i18nservice'>I18nService</a>) => TimeAgoPipe`}   />


### transform

<MemberInfo kind="method" type={`(value: string | Date, nowVal?: string | Date) => string`}   />




</div>


---

---
title: "ActionBar"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ActionBar

<GenerationInfo sourceFile="packages/admin-ui/src/lib/react/src/react-components/ActionBar.tsx" sourceLine="22" packageName="@vendure/admin-ui" />

A container for the primary actions on a list or detail page

*Example*

```ts
import { ActionBar } from '@vendure/admin-ui/react';

export function MyComponent() {
  return (
    <ActionBar leftContent={<div>Optional left content</div>}>
      <button className='button primary'>Primary action</button>
    </ActionBar>
  );
}
```

```ts title="Signature"
function ActionBar(props: PropsWithChildren<{ leftContent?: ReactNode }>): void
```
Parameters

### props

<MemberInfo kind="parameter" type={`PropsWithChildren&#60;{ leftContent?: ReactNode }&#62;`} />



---

---
title: "Card"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## Card

<GenerationInfo sourceFile="packages/admin-ui/src/lib/react/src/react-components/Card.tsx" sourceLine="22" packageName="@vendure/admin-ui" />

A card component which can be used to group related content.

*Example*

```ts
import { Card } from '@vendure/admin-ui/react';

export function MyComponent() {
  return (
    <Card title='My Title'>
      <p>Some content</p>
    </Card>
  );
}
```

```ts title="Signature"
function Card(props: PropsWithChildren<{ title?: string; paddingX?: boolean }>): void
```
Parameters

### props

<MemberInfo kind="parameter" type={`PropsWithChildren&#60;{ title?: string; paddingX?: boolean }&#62;`} />



---

---
title: "CdsIcon"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## CdsIcon

<GenerationInfo sourceFile="packages/admin-ui/src/lib/react/src/react-components/CdsIcon.tsx" sourceLine="47" packageName="@vendure/admin-ui" />

A React wrapper for the Clarity UI icon component.

*Example*

```ts
import { userIcon } from '@cds/core/icon';
import { CdsIcon } from '@vendure/admin-ui/react';

registerCdsIcon(userIcon);
export function MyComponent() {
   return <CdsIcon icon={userIcon} badge="warning" solid size="lg"></CdsIcon>;
}
```

```ts title="Signature"
function CdsIcon(props: { icon: IconShapeTuple; className?: string } & Partial<CdsIconProps>): void
```
Parameters

### props

<MemberInfo kind="parameter" type={`{ icon: IconShapeTuple; className?: string } &#38; Partial&#60;CdsIconProps&#62;`} />



---

---
title: "FormField"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## FormField

<GenerationInfo sourceFile="packages/admin-ui/src/lib/react/src/react-components/FormField.tsx" sourceLine="22" packageName="@vendure/admin-ui" />

A wrapper around form fields which provides a label, tooltip and error message.

*Example*

```ts
import { FormField } from '@vendure/admin-ui/react';

export function MyReactComponent() {
    return (
       <FormField label="My field" tooltip="This is a tooltip" invalid errorMessage="This field is invalid">
           <input type="text" />
       </FormField>
    );
}
```

```ts title="Signature"
function FormField(props: PropsWithChildren<{
        for?: string;
        label?: string;
        tooltip?: string;
        invalid?: boolean;
        errorMessage?: string;
    }>): void
```
Parameters

### props

<MemberInfo kind="parameter" type={`PropsWithChildren&#60;{         for?: string;         label?: string;         tooltip?: string;         invalid?: boolean;         errorMessage?: string;     }&#62;`} />



---

---
title: "React Components"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "Link"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## Link

<GenerationInfo sourceFile="packages/admin-ui/src/lib/react/src/react-components/Link.tsx" sourceLine="22" packageName="@vendure/admin-ui" />

A React component which renders an anchor tag and navigates to the specified route when clicked.
This is useful when you want to use a React component in a Vendure UI plugin which navigates to
a route in the admin-ui.

*Example*

```ts
import { Link } from '@vendure/admin-ui/react';

export const MyReactComponent = () => {
    return <Link href="/extensions/my-extension">Go to my extension</Link>;
}
```

```ts title="Signature"
function Link(props: PropsWithChildren<{ href: string; [props: string]: any }>): void
```
Parameters

### props

<MemberInfo kind="parameter" type={`PropsWithChildren&#60;{ href: string; [props: string]: any }&#62;`} />



---

---
title: "PageBlock"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## PageBlock

<GenerationInfo sourceFile="packages/admin-ui/src/lib/react/src/react-components/PageBlock.tsx" sourceLine="22" packageName="@vendure/admin-ui" />

A container for page content which provides a consistent width and spacing.

*Example*

```ts
import { PageBlock } from '@vendure/admin-ui/react';

export function MyComponent() {
  return (
    <PageBlock>
      ...
    </PageBlock>
  );
}
```

```ts title="Signature"
function PageBlock(props: PropsWithChildren): void
```
Parameters

### props

<MemberInfo kind="parameter" type={`PropsWithChildren`} />



---

---
title: "PageDetailLayout"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## PageDetailLayout

<GenerationInfo sourceFile="packages/admin-ui/src/lib/react/src/react-components/PageDetailLayout.tsx" sourceLine="22" packageName="@vendure/admin-ui" />

A responsive container for detail views with a main content area and an optional sidebar.

*Example*

```ts
import { PageDetailLayout } from '@vendure/admin-ui/react';

export function MyComponent() {
  return (
    <PageDetailLayout sidebar={<div>Sidebar content</div>}>
      <div>Main content</div>
    </PageDetailLayout>
  );
}
```

```ts title="Signature"
function PageDetailLayout(props: PropsWithChildren<{ sidebar?: ReactNode }>): void
```
Parameters

### props

<MemberInfo kind="parameter" type={`PropsWithChildren&#60;{ sidebar?: ReactNode }&#62;`} />



---

---
title: "RichTextEditor"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## RichTextEditor

<GenerationInfo sourceFile="packages/admin-ui/src/lib/react/src/react-components/RichTextEditor.tsx" sourceLine="60" packageName="@vendure/admin-ui" />

A rich text editor component which uses ProseMirror (rich text editor) under the hood.

*Example*

```ts
import { RichTextEditor } from '@vendure/admin-ui/react';
import React from 'react';

export function MyComponent() {
  const onSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    const form = new FormData(e.target as HTMLFormElement);
    const content = form.get("content");
    console.log(content);
  };

  return (
    <form className="w-full" onSubmit={onSubmit}>
      <RichTextEditor
        name="content"
        readOnly={false}
        onMount={(e) => console.log("Mounted", e)}
      />
      <button type="submit" className="btn btn-primary">
        Submit
      </button>
    </form>
  );
}
```



---

---
title: "React Extensions"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "ReactCustomDetailComponentConfig"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ReactCustomDetailComponentConfig

<GenerationInfo sourceFile="packages/admin-ui/src/lib/react/src/register-react-custom-detail-component.ts" sourceLine="15" packageName="@vendure/admin-ui" />

Configures a React-based component to be placed in a detail page in the given location.

```ts title="Signature"
interface ReactCustomDetailComponentConfig {
    locationId: CustomDetailComponentLocationId;
    component: ElementType;
    props?: Record<string, any>;
}
```

<div className="members-wrapper">

### locationId

<MemberInfo kind="property" type={`<a href='/reference/admin-ui-api/custom-detail-components/custom-detail-component-location-id#customdetailcomponentlocationid'>CustomDetailComponentLocationId</a>`}   />

The id of the detail page location in which to place the component.
### component

<MemberInfo kind="property" type={`ElementType`}   />

The React component to render.
### props

<MemberInfo kind="property" type={`Record&#60;string, any&#62;`}   />

Optional props to pass to the React component.


</div>


---

---
title: "ReactDataTableComponentConfig"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ReactDataTableComponentConfig

<GenerationInfo sourceFile="packages/admin-ui/src/lib/react/src/register-react-data-table-component.ts" sourceLine="19" packageName="@vendure/admin-ui" />

Configures a <a href='/reference/admin-ui-api/custom-detail-components/custom-detail-component#customdetailcomponent'>CustomDetailComponent</a> to be placed in the given location.

```ts title="Signature"
interface ReactDataTableComponentConfig {
    tableId: DataTableLocationId;
    columnId: DataTableColumnId;
    component: ElementType;
    props?: Record<string, any>;
}
```

<div className="members-wrapper">

### tableId

<MemberInfo kind="property" type={`DataTableLocationId`}   />

The location in the UI where the custom component should be placed.
### columnId

<MemberInfo kind="property" type={`DataTableColumnId`}   />

The column in the table where the custom component should be placed.
### component

<MemberInfo kind="property" type={`ElementType`}   />

The component to render in the table cell. This component will receive the `rowItem` prop
which is the data object for the row, e.g. the `Product` object if used in the `product-list` table.
### props

<MemberInfo kind="property" type={`Record&#60;string, any&#62;`}   />

Optional props to pass to the React component.


</div>


---

---
title: "RegisterReactCustomDetailComponent"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## registerReactCustomDetailComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/react/src/register-react-custom-detail-component.ts" sourceLine="40" packageName="@vendure/admin-ui" />

Registers a React component to be rendered in a detail page in the given location.
Components used as custom detail components can make use of the <a href='/reference/admin-ui-api/react-hooks/use-detail-component-data#usedetailcomponentdata'>useDetailComponentData</a> hook.

```ts title="Signature"
function registerReactCustomDetailComponent(config: ReactCustomDetailComponentConfig): void
```
Parameters

### config

<MemberInfo kind="parameter" type={`<a href='/reference/admin-ui-api/react-extensions/react-custom-detail-component-config#reactcustomdetailcomponentconfig'>ReactCustomDetailComponentConfig</a>`} />



---

---
title: "RegisterReactDataTableComponent"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## registerReactDataTableComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/react/src/register-react-data-table-component.ts" sourceLine="90" packageName="@vendure/admin-ui" />

Registers a React component to be rendered in a data table in the given location.
The component will receive the `rowItem` prop which is the data object for the row,
e.g. the `Product` object if used in the `product-list` table.

*Example*

```ts title="components/SlugWithLink.tsx"
import { ReactDataTableComponentProps } from '@vendure/admin-ui/react';
import React from 'react';

export function SlugWithLink({ rowItem }: ReactDataTableComponentProps<{ slug: string }>) {
    return (
        <a href={`https://example.com/products/${rowItem.slug}`} target="_blank">
            {rowItem.slug}
        </a>
    );
}
```

```ts title="providers.ts"
import { registerReactDataTableComponent } from '@vendure/admin-ui/react';
import { SlugWithLink } from './components/SlugWithLink';

export default [
    registerReactDataTableComponent({
        component: SlugWithLink,
        tableId: 'product-list',
        columnId: 'slug',
        props: {
          foo: 'bar',
        },
    }),
];
```

```ts title="Signature"
function registerReactDataTableComponent(config: ReactDataTableComponentConfig): void
```
Parameters

### config

<MemberInfo kind="parameter" type={`<a href='/reference/admin-ui-api/react-extensions/react-data-table-component-config#reactdatatablecomponentconfig'>ReactDataTableComponentConfig</a>`} />



---

---
title: "RegisterReactFormInputComponent"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## registerReactFormInputComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/react/src/register-react-form-input-component.ts" sourceLine="15" packageName="@vendure/admin-ui" />

Registers a React component to be used as a <a href='/reference/admin-ui-api/custom-input-components/form-input-component#forminputcomponent'>FormInputComponent</a>.

```ts title="Signature"
function registerReactFormInputComponent(id: string, component: ElementType): void
```
Parameters

### id

<MemberInfo kind="parameter" type={`string`} />

### component

<MemberInfo kind="parameter" type={`ElementType`} />



---

---
title: "RegisterReactRouteComponentOptions"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## RegisterReactRouteComponentOptions

<GenerationInfo sourceFile="packages/admin-ui/src/lib/react/src/register-react-route-component.ts" sourceLine="15" packageName="@vendure/admin-ui" />

Configuration for a React-based route component.

```ts title="Signature"
type RegisterReactRouteComponentOptions<Entity extends { id: string; updatedAt?: string }, T extends DocumentNode | TypedDocumentNode<any, { id: string }>, Field extends keyof ResultOf<T>, R extends Field> = RegisterRouteComponentOptions<ElementType, Entity, T, Field, R> & {
    props?: Record<string, any>;
}
```


---

---
title: "RegisterReactRouteComponent"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## registerReactRouteComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/react/src/register-react-route-component.ts" sourceLine="30" packageName="@vendure/admin-ui" />

Registers a React component to be used as a route component.

```ts title="Signature"
function registerReactRouteComponent<Entity extends { id: string; updatedAt?: string }, T extends DocumentNode | TypedDocumentNode<any, { id: string }>, Field extends keyof ResultOf<T>, R extends Field>(options: RegisterReactRouteComponentOptions<Entity, T, Field, R>): Route
```
Parameters

### options

<MemberInfo kind="parameter" type={`<a href='/reference/admin-ui-api/react-extensions/register-react-route-component-options#registerreactroutecomponentoptions'>RegisterReactRouteComponentOptions</a>&#60;Entity, T, Field, R&#62;`} />



---

---
title: "React Hooks"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "UseDetailComponentData"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## useDetailComponentData

<GenerationInfo sourceFile="packages/admin-ui/src/lib/react/src/react-hooks/use-detail-component-data.ts" sourceLine="34" packageName="@vendure/admin-ui" />

Provides the data available to React-based CustomDetailComponents.

*Example*

```ts
import { Card, useDetailComponentData } from '@vendure/admin-ui/react';
import React from 'react';

export function CustomDetailComponent(props: any) {
    const { entity, detailForm } = useDetailComponentData();
    const updateName = () => {
        detailForm.get('name')?.setValue('New name');
        detailForm.markAsDirty();
    };
    return (
        <Card title={'Custom Detail Component'}>
            <button className="button" onClick={updateName}>
                Update name
            </button>
            <pre>{JSON.stringify(entity, null, 2)}</pre>
        </Card>
    );
}
```

```ts title="Signature"
function useDetailComponentData<T = any>(): void
```


---

---
title: "UseFormControl"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## useFormControl

<GenerationInfo sourceFile="packages/admin-ui/src/lib/react/src/react-hooks/use-form-control.ts" sourceLine="31" packageName="@vendure/admin-ui" />

Provides access to the current FormControl value and a method to update the value.

*Example*

```ts
import { useFormControl, ReactFormInputProps } from '@vendure/admin-ui/react';
import React from 'react';

export function ReactNumberInput({ readonly }: ReactFormInputProps) {
    const { value, setFormValue } = useFormControl();

    const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
        setFormValue(val);
    };
    return (
        <div>
            <input readOnly={readonly} type="number" onChange={handleChange} value={value} />
        </div>
    );
}
```

```ts title="Signature"
function useFormControl(): void
```


---

---
title: "UseInjector"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## useInjector

<GenerationInfo sourceFile="packages/admin-ui/src/lib/react/src/react-hooks/use-injector.ts" sourceLine="27" packageName="@vendure/admin-ui" />

Exposes the Angular injector which allows the injection of services into React components.

*Example*

```ts
import { useInjector } from '@vendure/admin-ui/react';
import { NotificationService } from '@vendure/admin-ui/core';

export const MyComponent = () => {
    const notificationService = useInjector(NotificationService);

    const handleClick = () => {
        notificationService.success('Hello world!');
    };
    // ...
    return <div>...</div>;
}
```

```ts title="Signature"
function useInjector<T = any>(token: ProviderToken<T>): T
```
Parameters

### token

<MemberInfo kind="parameter" type={`ProviderToken&#60;T&#62;`} />



---

---
title: "UseLazyQuery"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## useLazyQuery

<GenerationInfo sourceFile="packages/admin-ui/src/lib/react/src/react-hooks/use-query.ts" sourceLine="119" packageName="@vendure/admin-ui" since="2.2.0" />

A React hook which allows you to execute a GraphQL query lazily.

*Example*

```ts
import { useLazyQuery } from '@vendure/admin-ui/react';
import { gql } from 'graphql-tag';

const GET_PRODUCT = gql`
   query GetProduct($id: ID!) {
     product(id: $id) {
       id
       name
       description
     }
   }`;
type ProductResponse = {
    product: {
        name: string
        description: string
    }
}

export const MyComponent = () => {
    const [getProduct, { data, loading, error }] = useLazyQuery<ProductResponse>(GET_PRODUCT, { refetchOnChannelChange: true });

   const handleClick = () => {
        getProduct({
             id: '1',
        }).then(result => {
            // do something with the result
        });
    };

    if (loading) return <div>Loading...</div>;
    if (error) return <div>Error! { error }</div>;

    return (
    <div>
        <button onClick={handleClick}>Get product</button>
        {data && (
             <div>
                 <h1>{data.product.name}</h1>
                 <p>{data.product.description}</p>
             </div>)}
    </div>
    );
};
```

```ts title="Signature"
function useLazyQuery<T, V extends Record<string, any> = Record<string, any>>(query: DocumentNode | TypedDocumentNode<T, V>, options: { refetchOnChannelChange: boolean } = { refetchOnChannelChange: false }): void
```
Parameters

### query

<MemberInfo kind="parameter" type={`DocumentNode | TypedDocumentNode&#60;T, V&#62;`} />

### options

<MemberInfo kind="parameter" type={`{ refetchOnChannelChange: boolean }`} />



---

---
title: "UseMutation"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## useMutation

<GenerationInfo sourceFile="packages/admin-ui/src/lib/react/src/react-hooks/use-query.ts" sourceLine="181" packageName="@vendure/admin-ui" />

A React hook which allows you to execute a GraphQL mutation.

*Example*

```ts
import { useMutation } from '@vendure/admin-ui/react';
import { gql } from 'graphql-tag';

const UPDATE_PRODUCT = gql`
  mutation UpdateProduct($input: UpdateProductInput!) {
    updateProduct(input: $input) {
    id
    name
  }
}`;

export const MyComponent = () => {
    const [updateProduct, { data, loading, error }] = useMutation(UPDATE_PRODUCT);

    const handleClick = () => {
        updateProduct({
            input: {
                id: '1',
                name: 'New name',
            },
        }).then(result => {
            // do something with the result
        });
    };

    if (loading) return <div>Loading...</div>;
    if (error) return <div>Error! { error }</div>;

    return (
    <div>
        <button onClick={handleClick}>Update product</button>
        {data && <div>Product updated!</div>}
    </div>
    );
};
```

```ts title="Signature"
function useMutation<T, V extends Record<string, any> = Record<string, any>>(mutation: DocumentNode | TypedDocumentNode<T, V>): void
```
Parameters

### mutation

<MemberInfo kind="parameter" type={`DocumentNode | TypedDocumentNode&#60;T, V&#62;`} />



---

---
title: "UsePageMetadata"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## usePageMetadata

<GenerationInfo sourceFile="packages/admin-ui/src/lib/react/src/react-hooks/use-page-metadata.ts" sourceLine="31" packageName="@vendure/admin-ui" />

Provides functions for setting the current page title and breadcrumb.

*Example*

```ts
import { usePageMetadata } from '@vendure/admin-ui/react';
import { useEffect } from 'react';

export const MyComponent = () => {
    const { setTitle, setBreadcrumb } = usePageMetadata();
    useEffect(() => {
        setTitle('My Page');
        setBreadcrumb([
            { link: ['./parent'], label: 'Parent Page' },
            { link: ['./'], label: 'This Page' },
        ]);
    }, []);
    // ...
    return <div>...</div>;
}
```

```ts title="Signature"
function usePageMetadata(): void
```


---

---
title: "UseQuery"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## useQuery

<GenerationInfo sourceFile="packages/admin-ui/src/lib/react/src/react-hooks/use-query.ts" sourceLine="43" packageName="@vendure/admin-ui" />

A React hook which provides access to the results of a GraphQL query.

*Example*

```ts
import { useQuery } from '@vendure/admin-ui/react';
import { gql } from 'graphql-tag';

const GET_PRODUCT = gql`
   query GetProduct($id: ID!) {
     product(id: $id) {
       id
       name
       description
     }
   }`;

export const MyComponent = () => {
    const { data, loading, error } = useQuery(GET_PRODUCT, { id: '1' }, { refetchOnChannelChange: true });

    if (loading) return <div>Loading...</div>;
    if (error) return <div>Error! { error }</div>;
    return (
        <div>
            <h1>{data.product.name}</h1>
            <p>{data.product.description}</p>
        </div>
    );
};
```

```ts title="Signature"
function useQuery<T, V extends Record<string, any> = Record<string, any>>(query: DocumentNode | TypedDocumentNode<T, V>, variables?: V, options: { refetchOnChannelChange: boolean } = { refetchOnChannelChange: false }): void
```
Parameters

### query

<MemberInfo kind="parameter" type={`DocumentNode | TypedDocumentNode&#60;T, V&#62;`} />

### variables

<MemberInfo kind="parameter" type={`V`} />

### options

<MemberInfo kind="parameter" type={`{ refetchOnChannelChange: boolean }`} />



---

---
title: "UseRichTextEditor"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## useRichTextEditor

<GenerationInfo sourceFile="packages/admin-ui/src/lib/react/src/react-hooks/use-rich-text-editor.ts" sourceLine="40" packageName="@vendure/admin-ui" />

Provides access to the ProseMirror (rich text editor) instance.

*Example*

```ts
import { useRichTextEditor } from '@vendure/admin-ui/react';
import React from 'react';

export function Component() {
    const { ref, editor } = useRichTextEditor({
       attributes: { class: '' },
       onTextInput: (text) => console.log(text),
       isReadOnly: () => false,
    });

    return <div className="w-full" ref={ref} />
}
```



---

---
title: "UseRouteParams"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## useRouteParams

<GenerationInfo sourceFile="packages/admin-ui/src/lib/react/src/react-hooks/use-route-params.ts" sourceLine="23" packageName="@vendure/admin-ui" />

Provides access to the current route params and query params.

*Example*

```ts
import { useRouteParams } from '@vendure/admin-ui/react';
import React from 'react';

export function MyComponent() {
    const { params, queryParams } = useRouteParams();
    // ...
    return <div>{ params.id }</div>;
}
```

```ts title="Signature"
function useRouteParams(): void
```


---

---
title: "Routes"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "RegisterRouteComponentOptions"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## RegisterRouteComponentOptions

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/extension/register-route-component.ts" sourceLine="19" packageName="@vendure/admin-ui" />

Configuration for a route component.

```ts title="Signature"
type RegisterRouteComponentOptions<Component extends any | BaseDetailComponent<Entity>, Entity extends { id: string; updatedAt?: string }, T extends DocumentNode | TypedDocumentNode<any, { id: string }>, Field extends keyof ResultOf<T>, R extends Field> = {
    component: Type<Component> | Component;
    title?: string;
    locationId?: string;
    description?: string;
    breadcrumb?: BreadcrumbValue;
    path?: string;
    query?: T;
    getBreadcrumbs?: (entity: Exclude<ResultOf<T>[R], 'Query'>) => BreadcrumbValue;
    entityKey?: Component extends BaseDetailComponent<any> ? R : string;
    variables?: T extends TypedDocumentNode<any, infer V> ? Omit<V, 'id'> : never;
    routeConfig?: Route;
} & (Component extends BaseDetailComponent<any> ? { entityKey: R } : unknown)
```


---

---
title: "RegisterRouteComponent"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## registerRouteComponent

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/extension/register-route-component.ts" sourceLine="79" packageName="@vendure/admin-ui" />

Registers an Angular standalone component to be rendered in a route.

*Example*

```ts title="routes.ts"
import { registerRouteComponent } from '@vendure/admin-ui/core';
import { registerReactRouteComponent } from '@vendure/admin-ui/react';

import { ProductReviewDetailComponent } from './components/product-review-detail/product-review-detail.component';
import { AllProductReviewsList } from './components/all-product-reviews-list/all-product-reviews-list.component';
import { GetReviewDetailDocument } from './generated-types';

export default [
    registerRouteComponent({
        path: '',
        component: AllProductReviewsList,
        breadcrumb: 'Product reviews',
    }),
    registerRouteComponent({
        path: ':id',
        component: ProductReviewDetailComponent,
        query: GetReviewDetailDocument,
        entityKey: 'productReview',
        getBreadcrumbs: entity => [
            {
                label: 'Product reviews',
                link: ['/extensions', 'product-reviews'],
            },
            {
                label: `#${entity?.id} (${entity?.product.name})`,
                link: [],
            },
        ],
    }),
];
```

```ts title="Signature"
function registerRouteComponent<Component extends any | BaseDetailComponent<Entity>, Entity extends { id: string; updatedAt?: string }, T extends DocumentNode | TypedDocumentNode<any, { id: string }>, Field extends keyof ResultOf<T>, R extends Field>(options: RegisterRouteComponentOptions<Component, Entity, T, Field, R>): void
```
Parameters

### options

<MemberInfo kind="parameter" type={`<a href='/reference/admin-ui-api/routes/register-route-component-options#registerroutecomponentoptions'>RegisterRouteComponentOptions</a>&#60;Component, Entity, T, Field, R&#62;`} />



---

---
title: "DataService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DataService

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/data/providers/data.service.ts" sourceLine="34" packageName="@vendure/admin-ui" />

Used to interact with the Admin API via GraphQL queries. Internally this service uses the
Apollo Client, which means it maintains a normalized entity cache. For this reason, it is
advisable to always select the `id` field of any entity, which will allow the returned data
to be effectively cached.

```ts title="Signature"
class DataService {
    query(query: DocumentNode | TypedDocumentNode<T, V>, variables?: V, fetchPolicy: WatchQueryFetchPolicy = 'cache-and-network', options: ExtendedQueryOptions = {}) => QueryResult<T, V>;
    mutate(mutation: DocumentNode | TypedDocumentNode<T, V>, variables?: V, update?: MutationUpdaterFunction<T, V, any, any>, options: ExtendedQueryOptions = {}) => Observable<T>;
}
```

<div className="members-wrapper">

### query

<MemberInfo kind="method" type={`(query: DocumentNode | TypedDocumentNode&#60;T, V&#62;, variables?: V, fetchPolicy: WatchQueryFetchPolicy = 'cache-and-network', options: ExtendedQueryOptions = {}) => <a href='/reference/admin-ui-api/services/data-service#queryresult'>QueryResult</a>&#60;T, V&#62;`}   />

Perform a GraphQL query. Returns a <a href='/reference/admin-ui-api/services/data-service#queryresult'>QueryResult</a> which allows further control over
they type of result returned, e.g. stream of values, single value etc.

*Example*

```ts
const result$ = this.dataService.query(gql`
  query MyQuery($id: ID!) {
    product(id: $id) {
      id
      name
      slug
    }
  },
  { id: 123 },
).mapSingle(data => data.product);
```
### mutate

<MemberInfo kind="method" type={`(mutation: DocumentNode | TypedDocumentNode&#60;T, V&#62;, variables?: V, update?: MutationUpdaterFunction&#60;T, V, any, any&#62;, options: ExtendedQueryOptions = {}) => Observable&#60;T&#62;`}   />

Perform a GraphQL mutation.

*Example*

```ts
const result$ = this.dataService.mutate(gql`
  mutation MyMutation($Codegen.UpdateEntityInput!) {
    updateEntity(input: $input) {
      id
      name
    }
  },
  { Codegen.updateEntityInput },
);
```


</div>


## QueryResult

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/data/query-result.ts" sourceLine="31" packageName="@vendure/admin-ui" />

This class wraps the Apollo Angular QueryRef object and exposes some getters
for convenience.

```ts title="Signature"
class QueryResult<T, V extends Record<string, any> = Record<string, any>> {
    constructor(queryRef: QueryRef<T, V>, apollo: Apollo, customFieldMap: Map<string, CustomFieldConfig[]>)
    refetchOnChannelChange() => QueryResult<T, V>;
    refetchOnCustomFieldsChange(customFieldsToInclude$: Observable<string[]>) => QueryResult<T, V>;
    single$: Observable<T>
    stream$: Observable<T>
    ref: QueryRef<T, V>
    mapSingle(mapFn: (item: T) => R) => Observable<R>;
    mapStream(mapFn: (item: T) => R) => Observable<R>;
    destroy() => ;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(queryRef: QueryRef&#60;T, V&#62;, apollo: Apollo, customFieldMap: Map&#60;string, <a href='/reference/typescript-api/custom-fields/custom-field-config#customfieldconfig'>CustomFieldConfig</a>[]&#62;) => QueryResult`}   />


### refetchOnChannelChange

<MemberInfo kind="method" type={`() => <a href='/reference/admin-ui-api/services/data-service#queryresult'>QueryResult</a>&#60;T, V&#62;`}   />

Re-fetch this query whenever the active Channel changes.
### refetchOnCustomFieldsChange

<MemberInfo kind="method" type={`(customFieldsToInclude$: Observable&#60;string[]&#62;) => <a href='/reference/admin-ui-api/services/data-service#queryresult'>QueryResult</a>&#60;T, V&#62;`}  since="3.0.4"  />

Re-fetch this query whenever the custom fields change, updating the query to include the
specified custom fields.
### single$

<MemberInfo kind="property" type={`Observable&#60;T&#62;`}   />

Returns an Observable which emits a single result and then completes.
### stream$

<MemberInfo kind="property" type={`Observable&#60;T&#62;`}   />

Returns an Observable which emits until unsubscribed.
### ref

<MemberInfo kind="property" type={`QueryRef&#60;T, V&#62;`}   />


### mapSingle

<MemberInfo kind="method" type={`(mapFn: (item: T) =&#62; R) => Observable&#60;R&#62;`}   />

Returns a single-result Observable after applying the map function.
### mapStream

<MemberInfo kind="method" type={`(mapFn: (item: T) =&#62; R) => Observable&#60;R&#62;`}   />

Returns a multiple-result Observable after applying the map function.
### destroy

<MemberInfo kind="method" type={`() => `}   />

Signals to the internal Observable subscriptions that they should complete.


</div>


---

---
title: "Services"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "ModalService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ModalService

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/providers/modal/modal.service.ts" sourceLine="21" packageName="@vendure/admin-ui" />

This service is responsible for instantiating a ModalDialog component and
embedding the specified component within.

```ts title="Signature"
class ModalService {
    constructor(overlayHostService: OverlayHostService)
    fromComponent(component: Type<T> & Type<Dialog<R>>, options?: ModalOptions<T>) => Observable<R | undefined>;
    dialog(config: DialogConfig<T>) => Observable<T | undefined>;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(overlayHostService: OverlayHostService) => ModalService`}   />


### fromComponent

<MemberInfo kind="method" type={`(component: Type&#60;T&#62; &#38; Type&#60;<a href='/reference/admin-ui-api/services/modal-service#dialog'>Dialog</a>&#60;R&#62;&#62;, options?: <a href='/reference/admin-ui-api/services/modal-service#modaloptions'>ModalOptions</a>&#60;T&#62;) => Observable&#60;R | undefined&#62;`}   />

Create a modal from a component. The component must implement the <a href='/reference/admin-ui-api/services/modal-service#dialog'>Dialog</a> interface.
Additionally, the component should include templates for the title and the buttons to be
displayed in the modal dialog. See example:

*Example*

```ts
class MyDialog implements Dialog {
 resolveWith: (result?: any) => void;

 okay() {
   doSomeWork().subscribe(result => {
     this.resolveWith(result);
   })
 }

 cancel() {
   this.resolveWith(false);
 }
}
```

*Example*

```html
<ng-template vdrDialogTitle>Title of the modal</ng-template>

<p>
  My Content
</p>

<ng-template vdrDialogButtons>
  <button type="button"
          class="btn"
          (click)="cancel()">Cancel</button>
  <button type="button"
          class="btn btn-primary"
          (click)="okay()">Okay</button>
</ng-template>
```
### dialog

<MemberInfo kind="method" type={`(config: <a href='/reference/admin-ui-api/services/modal-service#dialogconfig'>DialogConfig</a>&#60;T&#62;) => Observable&#60;T | undefined&#62;`}   />

Displays a modal dialog with the provided title, body and buttons.


</div>


## Dialog

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/providers/modal/modal.types.ts" sourceLine="9" packageName="@vendure/admin-ui" />

Any component intended to be used with the ModalService.fromComponent() method must implement
this interface.

```ts title="Signature"
interface Dialog<R = any> {
    resolveWith: (result?: R) => void;
}
```

<div className="members-wrapper">

### resolveWith

<MemberInfo kind="property" type={`(result?: R) =&#62; void`}   />

Function to be invoked in order to close the dialog when the action is complete.
The Observable returned from the .fromComponent() method will emit the value passed
to this method and then complete.


</div>


## DialogConfig

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/providers/modal/modal.types.ts" sourceLine="33" packageName="@vendure/admin-ui" />

Configures a generic modal dialog.

```ts title="Signature"
interface DialogConfig<T> {
    title: string;
    body?: string;
    translationVars?: { [key: string]: string | number };
    buttons: Array<DialogButtonConfig<T>>;
    size?: 'sm' | 'md' | 'lg' | 'xl';
}
```

<div className="members-wrapper">

### title

<MemberInfo kind="property" type={`string`}   />


### body

<MemberInfo kind="property" type={`string`}   />


### translationVars

<MemberInfo kind="property" type={`{ [key: string]: string | number }`}   />


### buttons

<MemberInfo kind="property" type={`Array&#60;DialogButtonConfig&#60;T&#62;&#62;`}   />


### size

<MemberInfo kind="property" type={`'sm' | 'md' | 'lg' | 'xl'`}   />




</div>


## ModalOptions

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/providers/modal/modal.types.ts" sourceLine="48" packageName="@vendure/admin-ui" />

Options to configure the behaviour of the modal.

```ts title="Signature"
interface ModalOptions<T> {
    size?: 'sm' | 'md' | 'lg' | 'xl';
    verticalAlign?: 'top' | 'center' | 'bottom';
    closable?: boolean;
    locals?: Partial<T>;
}
```

<div className="members-wrapper">

### size

<MemberInfo kind="property" type={`'sm' | 'md' | 'lg' | 'xl'`}   />

Sets the width of the dialog
### verticalAlign

<MemberInfo kind="property" type={`'top' | 'center' | 'bottom'`}   />

Sets the vertical alignment of the dialog
### closable

<MemberInfo kind="property" type={`boolean`}   />

When true, the "x" icon is shown
and clicking it or the mask will close the dialog
### locals

<MemberInfo kind="property" type={`Partial&#60;T&#62;`}   />

Values to be passed directly to the component being instantiated inside the dialog.


</div>


---

---
title: "NotificationService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## NotificationService

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/providers/notification/notification.service.ts" sourceLine="54" packageName="@vendure/admin-ui" />

Provides toast notification functionality.

*Example*

```ts
class MyComponent {
  constructor(private notificationService: NotificationService) {}

  save() {
    this.notificationService
        .success(_('asset.notify-create-assets-success'), {
          count: successCount,
        });
  }
}

```ts title="Signature"
class NotificationService {
    constructor(i18nService: I18nService, resolver: ComponentFactoryResolver, overlayHostService: OverlayHostService)
    success(message: string, translationVars?: { [key: string]: string | number }) => void;
    info(message: string, translationVars?: { [key: string]: string | number }) => void;
    warning(message: string, translationVars?: { [key: string]: string | number }) => void;
    error(message: string, translationVars?: { [key: string]: string | number }) => void;
    notify(config: ToastConfig) => void;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(i18nService: <a href='/reference/typescript-api/common/i18n-service#i18nservice'>I18nService</a>, resolver: ComponentFactoryResolver, overlayHostService: OverlayHostService) => NotificationService`}   />


### success

<MemberInfo kind="method" type={`(message: string, translationVars?: { [key: string]: string | number }) => void`}   />

Display a success toast notification
### info

<MemberInfo kind="method" type={`(message: string, translationVars?: { [key: string]: string | number }) => void`}   />

Display an info toast notification
### warning

<MemberInfo kind="method" type={`(message: string, translationVars?: { [key: string]: string | number }) => void`}   />

Display a warning toast notification
### error

<MemberInfo kind="method" type={`(message: string, translationVars?: { [key: string]: string | number }) => void`}   />

Display an error toast notification
### notify

<MemberInfo kind="method" type={`(config: <a href='/reference/admin-ui-api/services/notification-service#toastconfig'>ToastConfig</a>) => void`}   />

Display a toast notification.


</div>


## NotificationType

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/providers/notification/notification.service.ts" sourceLine="14" packageName="@vendure/admin-ui" />

The types of notification available.

```ts title="Signature"
type NotificationType = 'info' | 'success' | 'error' | 'warning'
```


## ToastConfig

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/providers/notification/notification.service.ts" sourceLine="23" packageName="@vendure/admin-ui" />

Configuration for a toast notification.

```ts title="Signature"
interface ToastConfig {
    message: string;
    translationVars?: { [key: string]: string | number };
    type?: NotificationType;
    duration?: number;
}
```

<div className="members-wrapper">

### message

<MemberInfo kind="property" type={`string`}   />


### translationVars

<MemberInfo kind="property" type={`{ [key: string]: string | number }`}   />


### type

<MemberInfo kind="property" type={`<a href='/reference/admin-ui-api/services/notification-service#notificationtype'>NotificationType</a>`}   />


### duration

<MemberInfo kind="property" type={`number`}   />




</div>


---

---
title: "Tabs"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "PageTabConfig"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## PageTabConfig

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/providers/page/page.service.ts" sourceLine="14" packageName="@vendure/admin-ui" />

The object used to configure a new page tab.

```ts title="Signature"
interface PageTabConfig {
    location: PageLocationId;
    tabIcon?: string;
    route: string;
    tab: string;
    priority?: number;
    component: Type<any> | ReturnType<typeof detailComponentWithResolver>;
    routeConfig?: Route;
}
```

<div className="members-wrapper">

### location

<MemberInfo kind="property" type={`<a href='/reference/admin-ui-api/action-bar/page-location-id#pagelocationid'>PageLocationId</a>`}   />

A valid location representing a list or detail page.
### tabIcon

<MemberInfo kind="property" type={`string`}   />

An optional icon to display in the tab. The icon
should be a valid shape name from the [Clarity Icons](https://core.clarity.design/foundation/icons/shapes/)
set.
### route

<MemberInfo kind="property" type={`string`}   />

The route path to the tab. This will be appended to the
route of the parent page.
### tab

<MemberInfo kind="property" type={`string`}   />

The name of the tab to display in the UI.
### priority

<MemberInfo kind="property" type={`number`}   />

The priority of the tab. Tabs with a lower priority will be displayed first.
### component

<MemberInfo kind="property" type={`Type&#60;any&#62; | ReturnType&#60;typeof <a href='/reference/admin-ui-api/list-detail-views/detail-component-with-resolver#detailcomponentwithresolver'>detailComponentWithResolver</a>&#62;`}   />

The component to render at the route of the tab.
### routeConfig

<MemberInfo kind="property" type={`Route`}   />

You can optionally provide any native Angular route configuration options here.
Any values provided here will take precedence over the values generated
by the `route` and `component` properties.


</div>


---

---
title: "RegisterPageTab"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## registerPageTab

<GenerationInfo sourceFile="packages/admin-ui/src/lib/core/src/extension/register-page-tab.ts" sourceLine="24" packageName="@vendure/admin-ui" />

Add a tab to an existing list or detail page.

*Example*

```ts title="providers.ts"
import { registerPageTab } from '@vendure/admin-ui/core';
import { DeletedProductListComponent } from './components/deleted-product-list/deleted-product-list.component';

export default [
    registerPageTab({
        location: 'product-list',
        tab: 'Deleted Products',
        route: 'deleted',
        component: DeletedProductListComponent,
    }),
];
```

```ts title="Signature"
function registerPageTab(config: PageTabConfig): void
```
Parameters

### config

<MemberInfo kind="parameter" type={`<a href='/reference/admin-ui-api/tabs/page-tab-config#pagetabconfig'>PageTabConfig</a>`} />



---

---
title: "AdminUiExtension"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## AdminUiExtension

<GenerationInfo sourceFile="packages/ui-devkit/src/compiler/types.ts" sourceLine="130" packageName="@vendure/ui-devkit" />

Defines extensions to the Admin UI application by specifying additional
Angular [NgModules](https://angular.io/guide/ngmodules) which are compiled
into the application.

See [Extending the Admin UI](/guides/extending-the-admin-ui/getting-started/) for
detailed instructions.

```ts title="Signature"
interface AdminUiExtension extends Partial<TranslationExtension>,
        Partial<StaticAssetExtension>,
        Partial<GlobalStylesExtension> {
    id?: string;
    extensionPath: string;
    ngModules?: Array<AdminUiExtensionSharedModule | AdminUiExtensionLazyModule>;
    providers?: string[];
    routes?: UiExtensionRouteDefinition[];
    pathAlias?: string;
    exclude?: string[];
}
```
* Extends: <code>Partial&#60;<a href='/reference/admin-ui-api/ui-devkit/admin-ui-extension#translationextension'>TranslationExtension</a>&#62;</code>, <code>Partial&#60;<a href='/reference/admin-ui-api/ui-devkit/admin-ui-extension#staticassetextension'>StaticAssetExtension</a>&#62;</code>, <code>Partial&#60;<a href='/reference/admin-ui-api/ui-devkit/admin-ui-extension#globalstylesextension'>GlobalStylesExtension</a>&#62;</code>



<div className="members-wrapper">

### id

<MemberInfo kind="property" type={`string`}   />

An optional ID for the extension module. Only used internally for generating
import paths to your module. If not specified, a unique hash will be used as the id.
### extensionPath

<MemberInfo kind="property" type={`string`}   />

The path to the directory containing the extension module(s). The entire contents of this directory
will be copied into the Admin UI app, including all TypeScript source files, html templates,
scss style sheets etc.
### ngModules

<MemberInfo kind="property" type={`Array&#60;<a href='/reference/admin-ui-api/ui-devkit/admin-ui-extension#adminuiextensionsharedmodule'>AdminUiExtensionSharedModule</a> | <a href='/reference/admin-ui-api/ui-devkit/admin-ui-extension#adminuiextensionlazymodule'>AdminUiExtensionLazyModule</a>&#62;`}   />

One or more Angular modules which extend the default Admin UI.
### providers

<MemberInfo kind="property" type={`string[]`}   />

Defines the paths to a file that exports an array of shared providers such as nav menu items, custom form inputs,
custom detail components, action bar items, custom history entry components.
### routes

<MemberInfo kind="property" type={`<a href='/reference/admin-ui-api/ui-devkit/admin-ui-extension#uiextensionroutedefinition'>UiExtensionRouteDefinition</a>[]`}   />

Defines routes that will be lazy-loaded at the `/extensions/` route. The filePath should point to a file
relative to the `extensionPath` which exports an array of Angular route definitions.
### pathAlias

<MemberInfo kind="property" type={`string`}   />

An optional alias for the module so it can be referenced by other UI extension modules.

By default, Angular modules declared in an AdminUiExtension do not have access to code outside the directory
defined by the `extensionPath`. A scenario in which that can be useful though is in a monorepo codebase where
a common NgModule is shared across different plugins, each defined in its own package. An example can be found
below - note that the main `tsconfig.json` also maps the target module but using a path relative to the project's
root folder. The UI module is not part of the main TypeScript build task as explained in
[Extending the Admin UI](https://www.vendure.io/docs/plugins/extending-the-admin-ui/) but having `paths`
properly configured helps with usual IDE code editing features such as code completion and quick navigation, as
well as linting.

*Example*

```ts title="packages/common-ui-module/src/ui/ui-shared.module.ts"
import { NgModule } from '@angular/core';
import { SharedModule } from '@vendure/admin-ui/core';
import { CommonUiComponent } from './components/common-ui/common-ui.component';

export { CommonUiComponent };

@NgModule({
 imports: [SharedModule],
 exports: [CommonUiComponent],
 declarations: [CommonUiComponent],
})
export class CommonSharedUiModule {}
```

```ts title="packages/common-ui-module/src/index.ts"
import path from 'path';

import { AdminUiExtension } from '@vendure/ui-devkit/compiler';

export const uiExtensions: AdminUiExtension = {
  // highlight-next-line
  pathAlias: '@common-ui-module',     // this is the important part
  extensionPath: path.join(__dirname, 'ui'),
  ngModules: [
    {
      type: 'shared' as const,
      ngModuleFileName: 'ui-shared.module.ts',
      ngModuleName: 'CommonSharedUiModule',
    },
  ],
};
```

```json title="tsconfig.json"
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      // highlight-next-line
      "@common-ui-module/*": ["packages/common-ui-module/src/ui/*"]
    }
  }
}
```

```ts title="packages/sample-plugin/src/ui/ui-extension.module.ts"
import { NgModule } from '@angular/core';
import { SharedModule } from '@vendure/admin-ui/core';
// highlight-start
// the import below works both in the context of the custom Admin UI app as well as the main project
// '@common-ui-module' is the value of "pathAlias" and 'ui-shared.module' is the file we want to reference inside "extensionPath"
import { CommonSharedUiModule, CommonUiComponent } from '@common-ui-module/ui-shared.module';
// highlight-end

@NgModule({
  imports: [
    SharedModule,
    CommonSharedUiModule,
    RouterModule.forChild([
      {
        path: '',
        pathMatch: 'full',
        component: CommonUiComponent,
      },
    ]),
  ],
})
export class SampleUiExtensionModule {}
```
### exclude

<MemberInfo kind="property" type={`string[]`}   />

Optional array specifying filenames or [glob](https://github.com/isaacs/node-glob) patterns that should
be skipped when copying the directory defined by `extensionPath`.

*Example*

```ts
exclude: ['**/*.spec.ts']
```


</div>


## TranslationExtension

<GenerationInfo sourceFile="packages/ui-devkit/src/compiler/types.ts" sourceLine="18" packageName="@vendure/ui-devkit" />

Defines extensions to the Admin UI translations. Can be used as a stand-alone extension definition which only adds translations
without adding new UI functionality, or as part of a full <a href='/reference/admin-ui-api/ui-devkit/admin-ui-extension#adminuiextension'>AdminUiExtension</a>.

```ts title="Signature"
interface TranslationExtension {
    translations: { [languageCode in LanguageCode]?: string };
}
```

<div className="members-wrapper">

### translations

<MemberInfo kind="property" type={`{ [languageCode in <a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a>]?: string }`}   />

Optional object defining any translation files for the Admin UI. The value should be an object with
the key as a 2-character [ISO 639-1 language code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes),
and the value being a [glob](https://github.com/isaacs/node-glob) for any relevant
translation files in JSON format.

*Example*

```ts
translations: {
  en: path.join(__dirname, 'translations/*.en.json'),
  de: path.join(__dirname, 'translations/*.de.json'),
}
```


</div>


## StaticAssetExtension

<GenerationInfo sourceFile="packages/ui-devkit/src/compiler/types.ts" sourceLine="44" packageName="@vendure/ui-devkit" />

Defines extensions which copy static assets to the custom Admin UI application source asset directory.

```ts title="Signature"
interface StaticAssetExtension {
    staticAssets: StaticAssetDefinition[];
}
```

<div className="members-wrapper">

### staticAssets

<MemberInfo kind="property" type={`<a href='/reference/admin-ui-api/ui-devkit/admin-ui-extension#staticassetdefinition'>StaticAssetDefinition</a>[]`}   />

Optional array of paths to static assets which will be copied over to the Admin UI app's `/static`
directory.


</div>


## GlobalStylesExtension

<GenerationInfo sourceFile="packages/ui-devkit/src/compiler/types.ts" sourceLine="60" packageName="@vendure/ui-devkit" />

Defines extensions which add global styles to the custom Admin UI application.

```ts title="Signature"
interface GlobalStylesExtension {
    globalStyles: string[] | string;
}
```

<div className="members-wrapper">

### globalStyles

<MemberInfo kind="property" type={`string[] | string`}   />

Specifies a path (or array of paths) to global style files (css or Sass) which will be
incorporated into the Admin UI app global stylesheet.


</div>


## SassVariableOverridesExtension

<GenerationInfo sourceFile="packages/ui-devkit/src/compiler/types.ts" sourceLine="76" packageName="@vendure/ui-devkit" />

Defines an extension which allows overriding Clarity Design System's Sass variables used in styles on the Admin UI.

```ts title="Signature"
interface SassVariableOverridesExtension {
    sassVariableOverrides: string;
}
```

<div className="members-wrapper">

### sassVariableOverrides

<MemberInfo kind="property" type={`string`}   />

Specifies a path to a Sass style file containing variable declarations, which will take precedence over
default values defined in Clarity.


</div>


## UiExtensionRouteDefinition

<GenerationInfo sourceFile="packages/ui-devkit/src/compiler/types.ts" sourceLine="92" packageName="@vendure/ui-devkit" />

Defines a route which will be added to the Admin UI application.

```ts title="Signature"
interface UiExtensionRouteDefinition {
    route: string;
    filePath: string;
    prefix?: string;
}
```

<div className="members-wrapper">

### route

<MemberInfo kind="property" type={`string`}   />

The name of the route. This will be used as the path in the URL.
### filePath

<MemberInfo kind="property" type={`string`}   />

The path to the file which exports an array of Angular route definitions.
### prefix

<MemberInfo kind="property" type={`string`}  since="2.2.0"  />

All extensions will be mounted under the `/extensions/` route. This option allows you to specify a
custom prefix rather than `/extensions/`. For example, setting this to `custom` would cause the extension
to be mounted at `/custom/<route>` instead.

A common use case for this is to mount the extension at the root of the Admin UI, by setting this to an empty string.
This is useful when the extension is intended to replace the default Admin UI, rather than extend it.


</div>


## StaticAssetDefinition

<GenerationInfo sourceFile="packages/ui-devkit/src/compiler/types.ts" sourceLine="280" packageName="@vendure/ui-devkit" />

A static asset can be provided as a path to the asset, or as an object containing a path and a new
name, which will cause the compiler to copy and then rename the asset.

```ts title="Signature"
type StaticAssetDefinition = string | { path: string; rename: string }
```


## AdminUiExtensionSharedModule

<GenerationInfo sourceFile="packages/ui-devkit/src/compiler/types.ts" sourceLine="289" packageName="@vendure/ui-devkit" />

Configuration defining a single NgModule with which to extend the Admin UI.

```ts title="Signature"
interface AdminUiExtensionSharedModule {
    type: 'shared';
    ngModuleFileName: string;
    ngModuleName: string;
}
```

<div className="members-wrapper">

### type

<MemberInfo kind="property" type={`'shared'`}   />

Shared modules are directly imported into the main AppModule of the Admin UI
and should be used to declare custom form components and define custom
navigation items.
### ngModuleFileName

<MemberInfo kind="property" type={`string`}   />

The name of the file containing the extension module class.
### ngModuleName

<MemberInfo kind="property" type={`string`}   />

The name of the extension module class.


</div>


## AdminUiExtensionLazyModule

<GenerationInfo sourceFile="packages/ui-devkit/src/compiler/types.ts" sourceLine="316" packageName="@vendure/ui-devkit" />

Configuration defining a single NgModule with which to extend the Admin UI.

```ts title="Signature"
interface AdminUiExtensionLazyModule {
    type: 'lazy';
    route: string;
    ngModuleFileName: string;
    ngModuleName: string;
}
```

<div className="members-wrapper">

### type

<MemberInfo kind="property" type={`'lazy'`}   />

Lazy modules are lazy-loaded at the `/extensions/` route and should be used for
modules which define new views for the Admin UI.
### route

<MemberInfo kind="property" type={`string`}   />

The route specifies the route at which the module will be lazy-loaded. E.g. a value
of `'foo'` will cause the module to lazy-load when the `/extensions/foo` route
is activated.
### ngModuleFileName

<MemberInfo kind="property" type={`string`}   />

The name of the file containing the extension module class.
### ngModuleName

<MemberInfo kind="property" type={`string`}   />

The name of the extension module class.


</div>


---

---
title: "CompileUiExtensions"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## compileUiExtensions

<GenerationInfo sourceFile="packages/ui-devkit/src/compiler/compile.ts" sourceLine="36" packageName="@vendure/ui-devkit" />

Compiles the Admin UI app with the specified extensions.

```ts title="Signature"
function compileUiExtensions(options: UiExtensionCompilerOptions): AdminUiAppConfig | AdminUiAppDevModeConfig
```
Parameters

### options

<MemberInfo kind="parameter" type={`<a href='/reference/admin-ui-api/ui-devkit/ui-extension-compiler-options#uiextensioncompileroptions'>UiExtensionCompilerOptions</a>`} />



---

---
title: "Helpers"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## setBranding

<GenerationInfo sourceFile="packages/ui-devkit/src/compiler/helpers.ts" sourceLine="26" packageName="@vendure/ui-devkit" />

A helper function to simplify the process of setting custom branding images.

*Example*

```ts
compileUiExtensions({
  outputPath: path.join(__dirname, '../admin-ui'),
  extensions: [
    setBranding({
      // This is used as the branding in the top-left above the navigation
      smallLogoPath: path.join(__dirname, 'images/my-logo-sm.png'),
      // This is used on the login page
      largeLogoPath: path.join(__dirname, 'images/my-logo-lg.png'),
      faviconPath: path.join(__dirname, 'images/my-favicon.ico'),
    }),
  ],
});
```

```ts title="Signature"
function setBranding(options: BrandingOptions): StaticAssetExtension
```
Parameters

### options

<MemberInfo kind="parameter" type={`BrandingOptions`} />



---

---
title: "Ui Devkit"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "UiDevkitClient"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## setTargetOrigin

<GenerationInfo sourceFile="packages/ui-devkit/src/client/devkit-client-api.ts" sourceLine="24" packageName="@vendure/ui-devkit" />

Set the [window.postMessage API](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage)
`targetOrigin`. The Vendure ui-devkit uses the postMessage API to
enable cross-frame and cross-origin communication between the ui extension code and the Admin UI
app. The `targetOrigin` is a security feature intended to provide control over where messages are sent.

```ts title="Signature"
function setTargetOrigin(value: string): void
```
Parameters

### value

<MemberInfo kind="parameter" type={`string`} />



## getActivatedRoute

<GenerationInfo sourceFile="packages/ui-devkit/src/client/devkit-client-api.ts" sourceLine="43" packageName="@vendure/ui-devkit" />

Retrieves information about the current route of the host application, since it is not possible
to otherwise get this information from within the child iframe.

*Example*

```ts
import { getActivatedRoute } from '@vendure/ui-devkit';

const route = await getActivatedRoute();
const slug = route.params.slug;
```

```ts title="Signature"
function getActivatedRoute(): Promise<ActiveRouteData>
```


## graphQlQuery

<GenerationInfo sourceFile="packages/ui-devkit/src/client/devkit-client-api.ts" sourceLine="70" packageName="@vendure/ui-devkit" />

Perform a GraphQL query and returns either an Observable or a Promise of the result.

*Example*

```ts
import { graphQlQuery } from '@vendure/ui-devkit';

const productList = await graphQlQuery(`
  query GetProducts($skip: Int, $take: Int) {
      products(options: { skip: $skip, take: $take }) {
          items { id, name, enabled },
          totalItems
      }
  }`, {
    skip: 0,
    take: 10,
  }).then(data => data.products);
```

```ts title="Signature"
function graphQlQuery<T, V extends { [key: string]: any }>(document: string, variables?: { [key: string]: any }, fetchPolicy?: WatchQueryFetchPolicy): {
    then: Promise<T>['then'];
    stream: Observable<T>;
}
```
Parameters

### document

<MemberInfo kind="parameter" type={`string`} />

### variables

<MemberInfo kind="parameter" type={`{ [key: string]: any }`} />

### fetchPolicy

<MemberInfo kind="parameter" type={`WatchQueryFetchPolicy`} />



## graphQlMutation

<GenerationInfo sourceFile="packages/ui-devkit/src/client/devkit-client-api.ts" sourceLine="112" packageName="@vendure/ui-devkit" />

Perform a GraphQL mutation and returns either an Observable or a Promise of the result.

*Example*

```ts
import { graphQlMutation } from '@vendure/ui-devkit';

const disableProduct = (id: string) => {
  return graphQlMutation(`
    mutation DisableProduct($id: ID!) {
      updateProduct(input: { id: $id, enabled: false }) {
        id
        enabled
      }
    }`, { id })
    .then(data => data.updateProduct)
}
```

```ts title="Signature"
function graphQlMutation<T, V extends { [key: string]: any }>(document: string, variables?: { [key: string]: any }): {
    then: Promise<T>['then'];
    stream: Observable<T>;
}
```
Parameters

### document

<MemberInfo kind="parameter" type={`string`} />

### variables

<MemberInfo kind="parameter" type={`{ [key: string]: any }`} />



## notify

<GenerationInfo sourceFile="packages/ui-devkit/src/client/devkit-client-api.ts" sourceLine="147" packageName="@vendure/ui-devkit" />

Display a toast notification.

*Example*

```ts
import { notify } from '@vendure/ui-devkit';

notify({
  message: 'Updated Product',
  type: 'success'
});
```

```ts title="Signature"
function notify(options: NotificationMessage['data']): void
```
Parameters

### options

<MemberInfo kind="parameter" type={`NotificationMessage['data']`} />



---

---
title: "UiExtensionBuildCommand"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## UiExtensionBuildCommand

<GenerationInfo sourceFile="packages/ui-devkit/src/compiler/types.ts" sourceLine="356" packageName="@vendure/ui-devkit" />

The package manager to use when invoking the Angular CLI to build UI extensions.

```ts title="Signature"
type UiExtensionBuildCommand = 'npm' | 'yarn' | 'pnpm'
```


---

---
title: "UiExtensionCompilerOptions"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## UiExtensionCompilerOptions

<GenerationInfo sourceFile="packages/ui-devkit/src/compiler/types.ts" sourceLine="364" packageName="@vendure/ui-devkit" />

Options to configure how the Admin UI should be compiled.

```ts title="Signature"
interface UiExtensionCompilerOptions {
    outputPath: string;
    extensions: Extension[];
    ngCompilerPath?: string | undefined;
    devMode?: boolean;
    baseHref?: string;
    watchPort?: number;
    command?: UiExtensionBuildCommand;
    additionalProcessArguments?: UiExtensionCompilerProcessArgument[];
}
```

<div className="members-wrapper">

### outputPath

<MemberInfo kind="property" type={`string`}   />

The directory into which the sources for the extended Admin UI will be copied.
### extensions

<MemberInfo kind="property" type={`Extension[]`}   />

An array of objects which configure Angular modules and/or
translations with which to extend the Admin UI.
### ngCompilerPath

<MemberInfo kind="property" type={`string | undefined`}  since="2.1.0"  />

Allows you to manually specify the path to the Angular CLI compiler script. This can be useful in scenarios
where for some reason the built-in start/build scripts are unable to locate the `ng` command.

This option should not usually be required.

*Example*

```ts
compileUiExtensions({
    ngCompilerPath: path.join(__dirname, '../../node_modules/@angular/cli/bin/ng.js'),
    outputPath: path.join(__dirname, '../admin-ui'),
    extensions: [
      // ...
    ],
})
```
### devMode

<MemberInfo kind="property" type={`boolean`} default={`false`}   />

Set to `true` in order to compile the Admin UI in development mode (using the Angular CLI
[ng serve](https://angular.io/cli/serve) command). When in dev mode, any changes to
UI extension files will be watched and trigger a rebuild of the Admin UI with live
reloading.
### baseHref

<MemberInfo kind="property" type={`string`} default={`'/admin/'`}   />

Allows the baseHref of the compiled Admin UI app to be set. This determines the prefix
of the app, for example with the default value of `'/admin/'`, the Admin UI app
will be configured to be served from `http://<host>/admin/`.

Note: if you are using this in conjunction with the <a href='/reference/core-plugins/admin-ui-plugin/#adminuiplugin'>AdminUiPlugin</a> then you should
also set the `route` option to match this value.

*Example*

```ts
AdminUiPlugin.init({
  route: 'my-route',
  port: 5001,
  app: compileUiExtensions({
    baseHref: '/my-route/',
    outputPath: path.join(__dirname, './custom-admin-ui'),
    extensions: [],
    devMode: true,
  }),
}),
```
### watchPort

<MemberInfo kind="property" type={`number`} default={`4200 | undefined`}   />

In watch mode, allows the port of the dev server to be specified. Defaults to the Angular CLI default
of `4200`.
### command

<MemberInfo kind="property" type={`<a href='/reference/admin-ui-api/ui-devkit/ui-extension-build-command#uiextensionbuildcommand'>UiExtensionBuildCommand</a>`}  since="1.5.0"  />

Internally, the Angular CLI will be invoked as an npm script. By default, the compiler will use Yarn
to run the script if it is detected, otherwise it will use npm. This setting allows you to explicitly
set which command to use, including pnpm, rather than relying on the default behavior.
### additionalProcessArguments

<MemberInfo kind="property" type={`<a href='/reference/admin-ui-api/ui-devkit/ui-extension-compiler-process-argument#uiextensioncompilerprocessargument'>UiExtensionCompilerProcessArgument</a>[]`} default={`undefined`}  since="1.5.0"  />

Additional command-line arguments which will get passed to the [ng build](https://angular.io/cli/build)
command (or [ng serve](https://angular.io/cli/serve) if `devMode = true`).

*Example*

['--disable-host-check'] // to disable host check


</div>


---

---
title: "UiExtensionCompilerProcessArgument"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## UiExtensionCompilerProcessArgument

<GenerationInfo sourceFile="packages/ui-devkit/src/compiler/types.ts" sourceLine="348" packageName="@vendure/ui-devkit" />

Argument to configure process (watch or compile)

```ts title="Signature"
type UiExtensionCompilerProcessArgument = string | [string, any]
```


---

---
title: "AdminUiPluginOptions"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## AdminUiPluginOptions

<GenerationInfo sourceFile="packages/admin-ui-plugin/src/plugin.ts" sourceLine="44" packageName="@vendure/admin-ui-plugin" />

Configuration options for the <a href='/reference/core-plugins/admin-ui-plugin/#adminuiplugin'>AdminUiPlugin</a>.

```ts title="Signature"
interface AdminUiPluginOptions {
    route: string;
    port: number;
    hostname?: string;
    app?: AdminUiAppConfig | AdminUiAppDevModeConfig;
    adminUiConfig?: Partial<AdminUiConfig>;
    compatibilityMode?: boolean;
}
```

<div className="members-wrapper">

### route

<MemberInfo kind="property" type={`string`}   />

The route to the Admin UI.

Note: If you are using the `compileUiExtensions` function to compile a custom version of the Admin UI, then
the route should match the `baseHref` option passed to that function. The default value of `baseHref` is `/admin/`,
so it only needs to be changed if you set this `route` option to something other than `"admin"`.
### port

<MemberInfo kind="property" type={`number`}   />

The port on which the server will listen. This port will be proxied by the AdminUiPlugin to the same port that
the Vendure server is running on.
### hostname

<MemberInfo kind="property" type={`string`} default={`'localhost'`}   />

The hostname of the server serving the static admin ui files.
### app

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/admin-ui/admin-ui-app-config#adminuiappconfig'>AdminUiAppConfig</a> | <a href='/reference/typescript-api/common/admin-ui/admin-ui-app-dev-mode-config#adminuiappdevmodeconfig'>AdminUiAppDevModeConfig</a>`}   />

By default, the AdminUiPlugin comes bundles with a pre-built version of the
Admin UI. This option can be used to override this default build with a different
version, e.g. one pre-compiled with one or more ui extensions.
### adminUiConfig

<MemberInfo kind="property" type={`Partial&#60;<a href='/reference/typescript-api/common/admin-ui/admin-ui-config#adminuiconfig'>AdminUiConfig</a>&#62;`}   />

Allows the contents of the `vendure-ui-config.json` file to be set, e.g.
for specifying the Vendure GraphQL API host, available UI languages, etc.
### compatibilityMode

<MemberInfo kind="property" type={`boolean`}  since="3.4.0"  />

If you are running the AdminUiPlugin at the same time as the new `DashboardPlugin`, you should
set this to `true` in order to avoid a conflict caused by both plugins defining the same
schema extensions.


</div>


---

---
title: "AdminUiPlugin"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## AdminUiPlugin

<GenerationInfo sourceFile="packages/admin-ui-plugin/src/plugin.ts" sourceLine="139" packageName="@vendure/admin-ui-plugin" />

This plugin starts a static server for the Admin UI app, and proxies it via the `/admin/` path of the main Vendure server.

The Admin UI allows you to administer all aspects of your store, from inventory management to order tracking. It is the tool used by
store administrators on a day-to-day basis for the management of the store.

## Installation

`yarn add @vendure/admin-ui-plugin`

or

`npm install @vendure/admin-ui-plugin`

*Example*

```ts
import { AdminUiPlugin } from '@vendure/admin-ui-plugin';

const config: VendureConfig = {
  // Add an instance of the plugin to the plugins array
  plugins: [
    AdminUiPlugin.init({ port: 3002 }),
  ],
};
```

## Metrics

This plugin also defines a `metricSummary` query which is used by the Admin UI to display the order metrics on the dashboard.

If you are building a stand-alone version of the Admin UI app, and therefore don't need this plugin to server the Admin UI,
you can still use the `metricSummary` query by adding the `AdminUiPlugin` to the `plugins` array, but without calling the `init()` method:

*Example*

```ts
import { AdminUiPlugin } from '@vendure/admin-ui-plugin';

const config: VendureConfig = {
  plugins: [
    AdminUiPlugin, // <-- no call to .init()
  ],
  // ...
};
```

```ts title="Signature"
class AdminUiPlugin implements NestModule {
    constructor(configService: ConfigService, processContext: ProcessContext)
    init(options: AdminUiPluginOptions) => Type<AdminUiPlugin>;
    configure(consumer: MiddlewareConsumer) => ;
}
```
* Implements: <code>NestModule</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(configService: ConfigService, processContext: <a href='/reference/typescript-api/common/process-context#processcontext'>ProcessContext</a>) => AdminUiPlugin`}   />


### init

<MemberInfo kind="method" type={`(options: <a href='/reference/core-plugins/admin-ui-plugin/admin-ui-plugin-options#adminuipluginoptions'>AdminUiPluginOptions</a>) => Type&#60;<a href='/reference/core-plugins/admin-ui-plugin/#adminuiplugin'>AdminUiPlugin</a>&#62;`}   />

Set the plugin options
### configure

<MemberInfo kind="method" type={`(consumer: MiddlewareConsumer) => `}   />




</div>


---

---
title: "AssetServerOptions"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## AssetServerOptions

<GenerationInfo sourceFile="packages/asset-server-plugin/src/types.ts" sourceLine="74" packageName="@vendure/asset-server-plugin" />

The configuration options for the AssetServerPlugin.

```ts title="Signature"
interface AssetServerOptions {
    route: string;
    assetUploadDir: string;
    assetUrlPrefix?: string | ((ctx: RequestContext, identifier: string) => string);
    previewMaxWidth?: number;
    previewMaxHeight?: number;
    presets?: ImageTransformPreset[];
    imageTransformStrategy?: ImageTransformStrategy | ImageTransformStrategy[];
    namingStrategy?: AssetNamingStrategy;
    previewStrategy?: AssetPreviewStrategy;
    storageStrategyFactory?: (
        options: AssetServerOptions,
    ) => AssetStorageStrategy | Promise<AssetStorageStrategy>;
    cacheHeader?: CacheConfig | string;
}
```

<div className="members-wrapper">

### route

<MemberInfo kind="property" type={`string`}   />

The route to the asset server.
### assetUploadDir

<MemberInfo kind="property" type={`string`}   />

The local directory to which assets will be uploaded when using the <a href='/reference/core-plugins/asset-server-plugin/local-asset-storage-strategy#localassetstoragestrategy'>LocalAssetStorageStrategy</a>.
### assetUrlPrefix

<MemberInfo kind="property" type={`string | ((ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, identifier: string) =&#62; string)`}   />

The complete URL prefix of the asset files. For example, "https://demo.vendure.io/assets/". A
function can also be provided to handle more complex cases, such as serving multiple domains
from a single server. In this case, the function should return a string url prefix.

If not provided, the plugin will attempt to guess based off the incoming
request and the configured route. However, in all but the simplest cases,
this guess may not yield correct results.
### previewMaxWidth

<MemberInfo kind="property" type={`number`} default={`1600`}   />

The max width in pixels of a generated preview image.
### previewMaxHeight

<MemberInfo kind="property" type={`number`} default={`1600`}   />

The max height in pixels of a generated preview image.
### presets

<MemberInfo kind="property" type={`<a href='/reference/core-plugins/asset-server-plugin/image-transform-preset#imagetransformpreset'>ImageTransformPreset</a>[]`}   />

An array of additional <a href='/reference/core-plugins/asset-server-plugin/image-transform-preset#imagetransformpreset'>ImageTransformPreset</a> objects.
### imageTransformStrategy

<MemberInfo kind="property" type={`<a href='/reference/core-plugins/asset-server-plugin/image-transform-strategy#imagetransformstrategy'>ImageTransformStrategy</a> | <a href='/reference/core-plugins/asset-server-plugin/image-transform-strategy#imagetransformstrategy'>ImageTransformStrategy</a>[]`} default={`[]`}  since="3.1.0"  />

The strategy or strategies to use to determine the parameters for transforming an image.
This can be used to implement custom image transformation logic, for example to
limit transform parameters to a known set of presets.

If multiple strategies are provided, they will be executed in the order in which they are defined.
If a strategy throws an error, the image transformation will be aborted and the error
will be logged, with an HTTP 400 response sent to the client.
### namingStrategy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/assets/asset-naming-strategy#assetnamingstrategy'>AssetNamingStrategy</a>`} default={`<a href='/reference/core-plugins/asset-server-plugin/hashed-asset-naming-strategy#hashedassetnamingstrategy'>HashedAssetNamingStrategy</a>`}   />

Defines how asset files and preview images are named before being saved.
### previewStrategy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/assets/asset-preview-strategy#assetpreviewstrategy'>AssetPreviewStrategy</a>`}  since="1.7.0"  />

Defines how previews are generated for a given Asset binary. By default, this uses
the <a href='/reference/core-plugins/asset-server-plugin/sharp-asset-preview-strategy#sharpassetpreviewstrategy'>SharpAssetPreviewStrategy</a>
### storageStrategyFactory

<MemberInfo kind="property" type={`(         options: <a href='/reference/core-plugins/asset-server-plugin/asset-server-options#assetserveroptions'>AssetServerOptions</a>,     ) =&#62; <a href='/reference/typescript-api/assets/asset-storage-strategy#assetstoragestrategy'>AssetStorageStrategy</a> | Promise&#60;<a href='/reference/typescript-api/assets/asset-storage-strategy#assetstoragestrategy'>AssetStorageStrategy</a>&#62;`} default={`() =&#62; <a href='/reference/core-plugins/asset-server-plugin/local-asset-storage-strategy#localassetstoragestrategy'>LocalAssetStorageStrategy</a>`}   />

A function which can be used to configure an <a href='/reference/typescript-api/assets/asset-storage-strategy#assetstoragestrategy'>AssetStorageStrategy</a>. This is useful e.g. if you wish to store your assets
using a cloud storage provider. By default, the <a href='/reference/core-plugins/asset-server-plugin/local-asset-storage-strategy#localassetstoragestrategy'>LocalAssetStorageStrategy</a> is used.
### cacheHeader

<MemberInfo kind="property" type={`<a href='/reference/core-plugins/asset-server-plugin/cache-config#cacheconfig'>CacheConfig</a> | string`} default={`'public, max-age=15552000'`}  since="1.9.3"  />

Configures the `Cache-Control` directive for response to control caching in browsers and shared caches (e.g. Proxies, CDNs).
Defaults to publicly cached for 6 months.


</div>


---

---
title: "CacheConfig"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## CacheConfig

<GenerationInfo sourceFile="packages/asset-server-plugin/src/types.ts" sourceLine="54" packageName="@vendure/asset-server-plugin" />

A configuration option for the Cache-Control header in the AssetServerPlugin asset response.

```ts title="Signature"
type CacheConfig = {
    maxAge: number;
    restriction?: 'public' | 'private';
}
```

<div className="members-wrapper">

### maxAge

<MemberInfo kind="property" type={`number`}   />

The max-age=N response directive indicates that the response remains fresh until N seconds after the response is generated.
### restriction

<MemberInfo kind="property" type={`'public' | 'private'`}   />

The `private` response directive indicates that the response can be stored only in a private cache (e.g. local caches in browsers).
The `public` response directive indicates that the response can be stored in a shared cache.


</div>


---

---
title: "HashedAssetNamingStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## HashedAssetNamingStrategy

<GenerationInfo sourceFile="packages/asset-server-plugin/src/config/hashed-asset-naming-strategy.ts" sourceLine="20" packageName="@vendure/asset-server-plugin" />

An extension of the <a href='/reference/typescript-api/assets/default-asset-naming-strategy#defaultassetnamingstrategy'>DefaultAssetNamingStrategy</a> which prefixes file names with
the type (`'source'` or `'preview'`) as well as a 2-character sub-directory based on
the md5 hash of the original file name.

This is an implementation of the technique knows as "hashed directory" file storage,
and the purpose is to reduce the number of files in a single directory, since a very large
number of files can lead to performance issues when reading and writing to that directory.

With this strategy, even with 200,000 total assets stored, each directory would
only contain less than 800 files.

```ts title="Signature"
class HashedAssetNamingStrategy extends DefaultAssetNamingStrategy {
    generateSourceFileName(ctx: RequestContext, originalFileName: string, conflictFileName?: string) => string;
    generatePreviewFileName(ctx: RequestContext, originalFileName: string, conflictFileName?: string) => string;
}
```
* Extends: <code><a href='/reference/typescript-api/assets/default-asset-naming-strategy#defaultassetnamingstrategy'>DefaultAssetNamingStrategy</a></code>



<div className="members-wrapper">

### generateSourceFileName

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, originalFileName: string, conflictFileName?: string) => string`}   />


### generatePreviewFileName

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, originalFileName: string, conflictFileName?: string) => string`}   />




</div>


---

---
title: "ImageTransformMode"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ImageTransformMode

<GenerationInfo sourceFile="packages/asset-server-plugin/src/types.ts" sourceLine="23" packageName="@vendure/asset-server-plugin" />

Specifies the way in which an asset preview image will be resized to fit in the
proscribed dimensions:

* crop: crops the image to cover both provided dimensions
* resize: Preserving aspect ratio, resizes the image to be as large as possible
while ensuring its dimensions are less than or equal to both those specified.

```ts title="Signature"
type ImageTransformMode = 'crop' | 'resize'
```


---

---
title: "ImageTransformPreset"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ImageTransformPreset

<GenerationInfo sourceFile="packages/asset-server-plugin/src/types.ts" sourceLine="41" packageName="@vendure/asset-server-plugin" />

A configuration option for an image size preset for the AssetServerPlugin.

Presets allow a shorthand way to generate a thumbnail preview of an asset. For example,
the built-in "tiny" preset generates a 50px x 50px cropped preview, which can be accessed
by appending the string `preset=tiny` to the asset url:

`http://localhost:3000/assets/some-asset.jpg?preset=tiny`

is equivalent to:

`http://localhost:3000/assets/some-asset.jpg?w=50&h=50&mode=crop`

```ts title="Signature"
interface ImageTransformPreset {
    name: string;
    width: number;
    height: number;
    mode: ImageTransformMode;
}
```

<div className="members-wrapper">

### name

<MemberInfo kind="property" type={`string`}   />


### width

<MemberInfo kind="property" type={`number`}   />


### height

<MemberInfo kind="property" type={`number`}   />


### mode

<MemberInfo kind="property" type={`<a href='/reference/core-plugins/asset-server-plugin/image-transform-mode#imagetransformmode'>ImageTransformMode</a>`}   />




</div>


---

---
title: "ImageTransformStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ImageTransformStrategy

<GenerationInfo sourceFile="packages/asset-server-plugin/src/config/image-transform-strategy.ts" sourceLine="56" packageName="@vendure/asset-server-plugin" since="3.1.0" />

An injectable strategy which is used to determine the parameters for transforming an image.
This can be used to implement custom image transformation logic, for example to
limit transform parameters to a known set of presets.

This is set via the `imageTransformStrategy` option in the AssetServerOptions. Multiple
strategies can be defined and will be executed in the order in which they are defined.

If a strategy throws an error, the image transformation will be aborted and the error
will be logged, with an HTTP 400 response sent to the client.

```ts title="Signature"
interface ImageTransformStrategy extends InjectableStrategy {
    getImageTransformParameters(
        args: GetImageTransformParametersArgs,
    ): Promise<ImageTransformParameters> | ImageTransformParameters;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### getImageTransformParameters

<MemberInfo kind="method" type={`(args: <a href='/reference/core-plugins/asset-server-plugin/image-transform-strategy#getimagetransformparametersargs'>GetImageTransformParametersArgs</a>) => Promise&#60;<a href='/reference/core-plugins/asset-server-plugin/image-transform-strategy#imagetransformparameters'>ImageTransformParameters</a>&#62; | <a href='/reference/core-plugins/asset-server-plugin/image-transform-strategy#imagetransformparameters'>ImageTransformParameters</a>`}   />

Given the input parameters, return the parameters which should be used to transform the image.


</div>


## ImageTransformParameters

<GenerationInfo sourceFile="packages/asset-server-plugin/src/config/image-transform-strategy.ts" sourceLine="14" packageName="@vendure/asset-server-plugin" since="3.1.0" />

Parameters which are used to transform the image.

```ts title="Signature"
interface ImageTransformParameters {
    width: number | undefined;
    height: number | undefined;
    mode: ImageTransformMode | undefined;
    quality: number | undefined;
    format: ImageTransformFormat | undefined;
    fpx: number | undefined;
    fpy: number | undefined;
    preset: string | undefined;
}
```

<div className="members-wrapper">

### width

<MemberInfo kind="property" type={`number | undefined`}   />


### height

<MemberInfo kind="property" type={`number | undefined`}   />


### mode

<MemberInfo kind="property" type={`<a href='/reference/core-plugins/asset-server-plugin/image-transform-mode#imagetransformmode'>ImageTransformMode</a> | undefined`}   />


### quality

<MemberInfo kind="property" type={`number | undefined`}   />


### format

<MemberInfo kind="property" type={`ImageTransformFormat | undefined`}   />


### fpx

<MemberInfo kind="property" type={`number | undefined`}   />


### fpy

<MemberInfo kind="property" type={`number | undefined`}   />


### preset

<MemberInfo kind="property" type={`string | undefined`}   />




</div>


## GetImageTransformParametersArgs

<GenerationInfo sourceFile="packages/asset-server-plugin/src/config/image-transform-strategy.ts" sourceLine="33" packageName="@vendure/asset-server-plugin" since="3.1.0" />

The arguments passed to the `getImageTransformParameters` method of an ImageTransformStrategy.

```ts title="Signature"
interface GetImageTransformParametersArgs {
    req: Request;
    availablePresets: ImageTransformPreset[];
    input: ImageTransformParameters;
}
```

<div className="members-wrapper">

### req

<MemberInfo kind="property" type={`Request`}   />


### availablePresets

<MemberInfo kind="property" type={`<a href='/reference/core-plugins/asset-server-plugin/image-transform-preset#imagetransformpreset'>ImageTransformPreset</a>[]`}   />


### input

<MemberInfo kind="property" type={`<a href='/reference/core-plugins/asset-server-plugin/image-transform-strategy#imagetransformparameters'>ImageTransformParameters</a>`}   />




</div>


---

---
title: "AssetServerPlugin"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## AssetServerPlugin

<GenerationInfo sourceFile="packages/asset-server-plugin/src/plugin.ts" sourceLine="176" packageName="@vendure/asset-server-plugin" />

The `AssetServerPlugin` serves assets (images and other files) from the local file system, and can also be configured to use
other storage strategies (e.g. <a href='/reference/core-plugins/asset-server-plugin/s3asset-storage-strategy#s3assetstoragestrategy'>S3AssetStorageStrategy</a>. It can also perform on-the-fly image transformations
and caches the results for subsequent calls.

## Installation

`yarn add @vendure/asset-server-plugin`

or

`npm install @vendure/asset-server-plugin`

*Example*

```ts
import { AssetServerPlugin } from '@vendure/asset-server-plugin';

const config: VendureConfig = {
  // Add an instance of the plugin to the plugins array
  plugins: [
    AssetServerPlugin.init({
      route: 'assets',
      assetUploadDir: path.join(__dirname, 'assets'),
    }),
  ],
};
```

The full configuration is documented at [AssetServerOptions](/reference/core-plugins/asset-server-plugin/asset-server-options)

## Image transformation

Asset preview images can be transformed (resized & cropped) on the fly by appending query parameters to the url:

`http://localhost:3000/assets/some-asset.jpg?w=500&h=300&mode=resize`

The above URL will return `some-asset.jpg`, resized to fit in the bounds of a 500px x 300px rectangle.

### Preview mode

The `mode` parameter can be either `crop` or `resize`. See the [ImageTransformMode](/reference/core-plugins/asset-server-plugin/image-transform-mode) docs for details.

### Focal point

When cropping an image (`mode=crop`), Vendure will attempt to keep the most "interesting" area of the image in the cropped frame. It does this
by finding the area of the image with highest entropy (the busiest area of the image). However, sometimes this does not yield a satisfactory
result - part or all of the main subject may still be cropped out.

This is where specifying the focal point can help. The focal point of the image may be specified by passing the `fpx` and `fpy` query parameters.
These are normalized coordinates (i.e. a number between 0 and 1), so the `fpx=0&fpy=0` corresponds to the top left of the image.

For example, let's say there is a very wide landscape image which we want to crop to be square. The main subject is a house to the far left of the
image. The following query would crop it to a square with the house centered:

`http://localhost:3000/assets/landscape.jpg?w=150&h=150&mode=crop&fpx=0.2&fpy=0.7`

### Format

Since v1.7.0, the image format can be specified by adding the `format` query parameter:

`http://localhost:3000/assets/some-asset.jpg?format=webp`

This means that, no matter the format of your original asset files, you can use more modern formats in your storefront if the browser
supports them. Supported values for `format` are:

* `jpeg` or `jpg`
* `png`
* `webp`
* `avif`

The `format` parameter can also be combined with presets (see below).

### Quality

Since v2.2.0, the image quality can be specified by adding the `q` query parameter:

`http://localhost:3000/assets/some-asset.jpg?q=75`

This applies to the `jpg`, `webp` and `avif` formats. The default quality value for `jpg` and `webp` is 80, and for `avif` is 50.

The `q` parameter can also be combined with presets (see below).

### Transform presets

Presets can be defined which allow a single preset name to be used instead of specifying the width, height and mode. Presets are
configured via the AssetServerOptions [presets property](/reference/core-plugins/asset-server-plugin/asset-server-options/#presets).

For example, defining the following preset:

```ts
AssetServerPlugin.init({
  // ...
  presets: [
    { name: 'my-preset', width: 85, height: 85, mode: 'crop' },
  ],
}),
```

means that a request to:

`http://localhost:3000/assets/some-asset.jpg?preset=my-preset`

is equivalent to:

`http://localhost:3000/assets/some-asset.jpg?w=85&h=85&mode=crop`

The AssetServerPlugin comes pre-configured with the following presets:

name | width | height | mode
-----|-------|--------|-----
tiny | 50px | 50px | crop
thumb | 150px | 150px | crop
small | 300px | 300px | resize
medium | 500px | 500px | resize
large | 800px | 800px | resize

### Caching
By default, the AssetServerPlugin will cache every transformed image, so that the transformation only needs to be performed a single time for
a given configuration. Caching can be disabled per-request by setting the `?cache=false` query parameter.

### Limiting transformations

By default, the AssetServerPlugin will allow any transformation to be performed on an image. However, it is possible to restrict the transformations
which can be performed by using an <a href='/reference/core-plugins/asset-server-plugin/image-transform-strategy#imagetransformstrategy'>ImageTransformStrategy</a>. This can be used to limit the transformations to a known set of presets, for example.

This is advisable in order to prevent abuse of the image transformation feature, as it can be computationally expensive.

Since v3.1.0 we ship with a <a href='/reference/core-plugins/asset-server-plugin/preset-only-strategy#presetonlystrategy'>PresetOnlyStrategy</a> which allows only transformations using a known set of presets.

*Example*

```ts
import { AssetServerPlugin, PresetOnlyStrategy } from '@vendure/core';

// ...

AssetServerPlugin.init({
  //...
  imageTransformStrategy: new PresetOnlyStrategy({
    defaultPreset: 'thumbnail',
    permittedQuality: [0, 50, 75, 85, 95],
    permittedFormats: ['jpg', 'webp', 'avif'],
    allowFocalPoint: false,
  }),
});
```

```ts title="Signature"
class AssetServerPlugin implements NestModule, OnApplicationBootstrap, OnApplicationShutdown {
    init(options: AssetServerOptions) => Type<AssetServerPlugin>;
    constructor(options: AssetServerOptions, processContext: ProcessContext, moduleRef: ModuleRef, assetServer: AssetServer)
    configure(consumer: MiddlewareConsumer) => ;
}
```
* Implements: <code>NestModule</code>, <code>OnApplicationBootstrap</code>, <code>OnApplicationShutdown</code>



<div className="members-wrapper">

### init

<MemberInfo kind="method" type={`(options: <a href='/reference/core-plugins/asset-server-plugin/asset-server-options#assetserveroptions'>AssetServerOptions</a>) => Type&#60;<a href='/reference/core-plugins/asset-server-plugin/#assetserverplugin'>AssetServerPlugin</a>&#62;`}   />

Set the plugin options.
### constructor

<MemberInfo kind="method" type={`(options: <a href='/reference/core-plugins/asset-server-plugin/asset-server-options#assetserveroptions'>AssetServerOptions</a>, processContext: <a href='/reference/typescript-api/common/process-context#processcontext'>ProcessContext</a>, moduleRef: ModuleRef, assetServer: AssetServer) => AssetServerPlugin`}   />


### configure

<MemberInfo kind="method" type={`(consumer: MiddlewareConsumer) => `}   />




</div>


---

---
title: "LocalAssetStorageStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## LocalAssetStorageStrategy

<GenerationInfo sourceFile="packages/asset-server-plugin/src/config/local-asset-storage-strategy.ts" sourceLine="15" packageName="@vendure/asset-server-plugin" />

A persistence strategy which saves files to the local file system.

```ts title="Signature"
class LocalAssetStorageStrategy implements AssetStorageStrategy {
    toAbsoluteUrl: ((reqest: Request, identifier: string) => string) | undefined;
    constructor(uploadPath: string, toAbsoluteUrlFn?: (reqest: Request, identifier: string) => string)
    writeFileFromStream(fileName: string, data: ReadStream) => Promise<string>;
    writeFileFromBuffer(fileName: string, data: Buffer) => Promise<string>;
    fileExists(fileName: string) => Promise<boolean>;
    readFileToBuffer(identifier: string) => Promise<Buffer>;
    readFileToStream(identifier: string) => Promise<Stream>;
    deleteFile(identifier: string) => Promise<void>;
}
```
* Implements: <code><a href='/reference/typescript-api/assets/asset-storage-strategy#assetstoragestrategy'>AssetStorageStrategy</a></code>



<div className="members-wrapper">

### toAbsoluteUrl

<MemberInfo kind="property" type={`((reqest: Request, identifier: string) =&#62; string) | undefined`}   />


### constructor

<MemberInfo kind="method" type={`(uploadPath: string, toAbsoluteUrlFn?: (reqest: Request, identifier: string) =&#62; string) => LocalAssetStorageStrategy`}   />


### writeFileFromStream

<MemberInfo kind="method" type={`(fileName: string, data: ReadStream) => Promise&#60;string&#62;`}   />


### writeFileFromBuffer

<MemberInfo kind="method" type={`(fileName: string, data: Buffer) => Promise&#60;string&#62;`}   />


### fileExists

<MemberInfo kind="method" type={`(fileName: string) => Promise&#60;boolean&#62;`}   />


### readFileToBuffer

<MemberInfo kind="method" type={`(identifier: string) => Promise&#60;Buffer&#62;`}   />


### readFileToStream

<MemberInfo kind="method" type={`(identifier: string) => Promise&#60;Stream&#62;`}   />


### deleteFile

<MemberInfo kind="method" type={`(identifier: string) => Promise&#60;void&#62;`}   />




</div>


---

---
title: "PresetOnlyStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## PresetOnlyStrategy

<GenerationInfo sourceFile="packages/asset-server-plugin/src/config/preset-only-strategy.ts" sourceLine="85" packageName="@vendure/asset-server-plugin" since="3.1.0" />

An <a href='/reference/core-plugins/asset-server-plugin/image-transform-strategy#imagetransformstrategy'>ImageTransformStrategy</a> which only allows transformations to be made using
presets which are defined in the available presets.

With this strategy enabled, requests to the asset server must include a `preset` parameter (or use the default preset)

This is valid: `http://localhost:3000/assets/some-asset.jpg?preset=medium`

This is invalid: `http://localhost:3000/assets/some-asset.jpg?w=200&h=200`, and the dimensions will be ignored.

The strategy can be configured to allow only certain quality values and formats, and to
optionally allow the focal point to be specified in the URL.

If a preset is not found in the available presets, an error will be thrown.

*Example*

```ts
import { AssetServerPlugin, PresetOnlyStrategy } from '@vendure/core';

// ...

AssetServerPlugin.init({
  //...
  imageTransformStrategy: new PresetOnlyStrategy({
    defaultPreset: 'thumbnail',
    permittedQuality: [0, 50, 75, 85, 95],
    permittedFormats: ['jpg', 'webp', 'avif'],
    allowFocalPoint: true,
  }),
});
```

```ts title="Signature"
class PresetOnlyStrategy implements ImageTransformStrategy {
    constructor(options: PresetOnlyStrategyOptions)
    getImageTransformParameters({
        input,
        availablePresets,
    }: GetImageTransformParametersArgs) => Promise<ImageTransformParameters> | ImageTransformParameters;
}
```
* Implements: <code><a href='/reference/core-plugins/asset-server-plugin/image-transform-strategy#imagetransformstrategy'>ImageTransformStrategy</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(options: <a href='/reference/core-plugins/asset-server-plugin/preset-only-strategy#presetonlystrategyoptions'>PresetOnlyStrategyOptions</a>) => PresetOnlyStrategy`}   />


### getImageTransformParameters

<MemberInfo kind="method" type={`({
        input,
        availablePresets,
    }: <a href='/reference/core-plugins/asset-server-plugin/image-transform-strategy#getimagetransformparametersargs'>GetImageTransformParametersArgs</a>) => Promise&#60;<a href='/reference/core-plugins/asset-server-plugin/image-transform-strategy#imagetransformparameters'>ImageTransformParameters</a>&#62; | <a href='/reference/core-plugins/asset-server-plugin/image-transform-strategy#imagetransformparameters'>ImageTransformParameters</a>`}   />




</div>


## PresetOnlyStrategyOptions

<GenerationInfo sourceFile="packages/asset-server-plugin/src/config/preset-only-strategy.ts" sourceLine="16" packageName="@vendure/asset-server-plugin" />

Configuration options for the <a href='/reference/core-plugins/asset-server-plugin/preset-only-strategy#presetonlystrategy'>PresetOnlyStrategy</a>.

```ts title="Signature"
interface PresetOnlyStrategyOptions {
    defaultPreset: string;
    permittedQuality?: number[];
    permittedFormats?: ImageTransformFormat[];
    allowFocalPoint?: boolean;
}
```

<div className="members-wrapper">

### defaultPreset

<MemberInfo kind="property" type={`string`}   />

The name of the default preset to use if no preset is specified in the URL.
### permittedQuality

<MemberInfo kind="property" type={`number[]`} default={`[0, 50, 75, 85, 95]`}   />

The permitted quality of the transformed images. If set to 'any', then any quality is permitted.
If set to an array of numbers (0-100), then only those quality values are permitted.
### permittedFormats

<MemberInfo kind="property" type={`ImageTransformFormat[]`} default={`['jpg', 'webp', 'avif']`}   />

The permitted formats of the transformed images. If set to 'any', then any format is permitted.
If set to an array of strings e.g. `['jpg', 'webp']`, then only those formats are permitted.
### allowFocalPoint

<MemberInfo kind="property" type={`boolean`} default={`false`}   />

Whether to allow the focal point to be specified in the URL.


</div>


---

---
title: "S3AssetStorageStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## S3AssetStorageStrategy

<GenerationInfo sourceFile="packages/asset-server-plugin/src/config/s3-asset-storage-strategy.ts" sourceLine="155" packageName="@vendure/asset-server-plugin" />

An <a href='/reference/typescript-api/assets/asset-storage-strategy#assetstoragestrategy'>AssetStorageStrategy</a> which uses [Amazon S3](https://aws.amazon.com/s3/) object storage service.
To us this strategy you must first have access to an AWS account.
See their [getting started guide](https://aws.amazon.com/s3/getting-started/) for how to get set up.

Before using this strategy, make sure you have the `@aws-sdk/client-s3` and `@aws-sdk/lib-storage` package installed:

```sh
npm install @aws-sdk/client-s3 @aws-sdk/lib-storage
```

**Note:** Rather than instantiating this manually, use the <a href='/reference/core-plugins/asset-server-plugin/s3asset-storage-strategy#configures3assetstorage'>configureS3AssetStorage</a> function.

## Use with S3-compatible services (MinIO)
This strategy will also work with any S3-compatible object storage solutions, such as [MinIO](https://min.io/).
See the <a href='/reference/core-plugins/asset-server-plugin/s3asset-storage-strategy#configures3assetstorage'>configureS3AssetStorage</a> for an example with MinIO.

```ts title="Signature"
class S3AssetStorageStrategy implements AssetStorageStrategy {
    constructor(s3Config: S3Config, toAbsoluteUrl: (request: Request, identifier: string) => string)
    init() => ;
    destroy?: (() => void | Promise<void>) | undefined;
    writeFileFromBuffer(fileName: string, data: Buffer) => ;
    writeFileFromStream(fileName: string, data: Readable) => ;
    readFileToBuffer(identifier: string) => ;
    readFileToStream(identifier: string) => ;
    deleteFile(identifier: string) => ;
    fileExists(fileName: string) => ;
}
```
* Implements: <code><a href='/reference/typescript-api/assets/asset-storage-strategy#assetstoragestrategy'>AssetStorageStrategy</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(s3Config: <a href='/reference/core-plugins/asset-server-plugin/s3asset-storage-strategy#s3config'>S3Config</a>, toAbsoluteUrl: (request: Request, identifier: string) =&#62; string) => S3AssetStorageStrategy`}   />


### init

<MemberInfo kind="method" type={`() => `}   />


### destroy

<MemberInfo kind="property" type={`(() =&#62; void | Promise&#60;void&#62;) | undefined`}   />


### writeFileFromBuffer

<MemberInfo kind="method" type={`(fileName: string, data: Buffer) => `}   />


### writeFileFromStream

<MemberInfo kind="method" type={`(fileName: string, data: Readable) => `}   />


### readFileToBuffer

<MemberInfo kind="method" type={`(identifier: string) => `}   />


### readFileToStream

<MemberInfo kind="method" type={`(identifier: string) => `}   />


### deleteFile

<MemberInfo kind="method" type={`(identifier: string) => `}   />


### fileExists

<MemberInfo kind="method" type={`(fileName: string) => `}   />




</div>


## S3Config

<GenerationInfo sourceFile="packages/asset-server-plugin/src/config/s3-asset-storage-strategy.ts" sourceLine="19" packageName="@vendure/asset-server-plugin" />

Configuration for connecting to AWS S3.

```ts title="Signature"
interface S3Config {
    credentials: AwsCredentialIdentity | AwsCredentialIdentityProvider;
    bucket: string;
    nativeS3Configuration?: any;
    nativeS3UploadConfiguration?: any;
}
```

<div className="members-wrapper">

### credentials

<MemberInfo kind="property" type={`AwsCredentialIdentity | AwsCredentialIdentityProvider`}   />

The credentials used to access your s3 account. You can supply either the access key ID & secret, or you can make use of a
[shared credentials file](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/loading-node-credentials-shared.html)
To use a shared credentials file, import the `fromIni()` function from the "@aws-sdk/credential-provider-ini" or "@aws-sdk/credential-providers" package and supply
the profile name (e.g. `{ profile: 'default' }`) as its argument.
### bucket

<MemberInfo kind="property" type={`string`}   />

The S3 bucket in which to store the assets. If it does not exist, it will be created on startup.
### nativeS3Configuration

<MemberInfo kind="property" type={`any`}   />

Configuration object passed directly to the AWS SDK.
S3.Types.ClientConfiguration can be used after importing aws-sdk.
Using type `any` in order to avoid the need to include `aws-sdk` dependency in general.
### nativeS3UploadConfiguration

<MemberInfo kind="property" type={`any`}   />

Configuration object passed directly to the AWS SDK.
ManagedUpload.ManagedUploadOptions can be used after importing aws-sdk.
Using type `any` in order to avoid the need to include `aws-sdk` dependency in general.


</div>


## configureS3AssetStorage

<GenerationInfo sourceFile="packages/asset-server-plugin/src/config/s3-asset-storage-strategy.ts" sourceLine="119" packageName="@vendure/asset-server-plugin" />

Returns a configured instance of the <a href='/reference/core-plugins/asset-server-plugin/s3asset-storage-strategy#s3assetstoragestrategy'>S3AssetStorageStrategy</a> which can then be passed to the <a href='/reference/core-plugins/asset-server-plugin/asset-server-options#assetserveroptions'>AssetServerOptions</a>`storageStrategyFactory` property.

Before using this strategy, make sure you have the `@aws-sdk/client-s3` and `@aws-sdk/lib-storage` package installed:

```sh
npm install @aws-sdk/client-s3 @aws-sdk/lib-storage
```

*Example*

```ts
import { AssetServerPlugin, configureS3AssetStorage } from '@vendure/asset-server-plugin';
import { DefaultAssetNamingStrategy } from '@vendure/core';
import { fromEnv } from '@aws-sdk/credential-providers';

// ...

plugins: [
  AssetServerPlugin.init({
    route: 'assets',
    assetUploadDir: path.join(__dirname, 'assets'),
    namingStrategy: new DefaultAssetNamingStrategy(),
    storageStrategyFactory: configureS3AssetStorage({
      bucket: 'my-s3-bucket',
      credentials: fromEnv(), // or any other credential provider
      nativeS3Configuration: {
        region: process.env.AWS_REGION,
      },
    }),
}),
```

## Usage with MinIO

Reference: [How to use AWS SDK for Javascript with MinIO Server](https://docs.min.io/docs/how-to-use-aws-sdk-for-javascript-with-minio-server.html)

*Example*

```ts
import { AssetServerPlugin, configureS3AssetStorage } from '@vendure/asset-server-plugin';
import { DefaultAssetNamingStrategy } from '@vendure/core';

// ...

plugins: [
  AssetServerPlugin.init({
    route: 'assets',
    assetUploadDir: path.join(__dirname, 'assets'),
    namingStrategy: new DefaultAssetNamingStrategy(),
    storageStrategyFactory: configureS3AssetStorage({
      bucket: 'my-minio-bucket',
      credentials: {
        accessKeyId: process.env.MINIO_ACCESS_KEY_ID,
        secretAccessKey: process.env.MINIO_SECRET_ACCESS_KEY,
      },
      nativeS3Configuration: {
        endpoint: process.env.MINIO_ENDPOINT ?? 'http://localhost:9000',
        forcePathStyle: true,
        signatureVersion: 'v4',
        // The `region` is required by the AWS SDK even when using MinIO,
        // so we just use a dummy value here.
        region: 'eu-west-1',
      },
    }),
}),
```

```ts title="Signature"
function configureS3AssetStorage(s3Config: S3Config): void
```
Parameters

### s3Config

<MemberInfo kind="parameter" type={`<a href='/reference/core-plugins/asset-server-plugin/s3asset-storage-strategy#s3config'>S3Config</a>`} />



---

---
title: "SharpAssetPreviewStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## SharpAssetPreviewStrategy

<GenerationInfo sourceFile="packages/asset-server-plugin/src/config/sharp-asset-preview-strategy.ts" sourceLine="95" packageName="@vendure/asset-server-plugin" />

This <a href='/reference/typescript-api/assets/asset-preview-strategy#assetpreviewstrategy'>AssetPreviewStrategy</a> uses the [Sharp library](https://sharp.pixelplumbing.com/) to generate
preview images of uploaded binary files. For non-image binaries, a generic "file" icon with the mime type
overlay will be generated.

By default, this strategy will produce previews up to maximum dimensions of 1600 x 1600 pixels. The created
preview images will match the input format - so a source file in jpeg format will output a jpeg preview,
a webp source file will output a webp preview, and so on.

The settings for the outputs will default to Sharp's defaults (https://sharp.pixelplumbing.com/api-output).
However, it is possible to pass your own configurations to control the output of each format:

```ts
AssetServerPlugin.init({
  previewStrategy: new SharpAssetPreviewStrategy({
    jpegOptions: { quality: 95 },
    webpOptions: { quality: 95 },
  }),
}),
```

```ts title="Signature"
class SharpAssetPreviewStrategy implements AssetPreviewStrategy {
    constructor(config?: SharpAssetPreviewConfig)
    generatePreviewImage(ctx: RequestContext, mimeType: string, data: Buffer) => Promise<Buffer>;
}
```
* Implements: <code><a href='/reference/typescript-api/assets/asset-preview-strategy#assetpreviewstrategy'>AssetPreviewStrategy</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(config?: <a href='/reference/core-plugins/asset-server-plugin/sharp-asset-preview-strategy#sharpassetpreviewconfig'>SharpAssetPreviewConfig</a>) => SharpAssetPreviewStrategy`}   />


### generatePreviewImage

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, mimeType: string, data: Buffer) => Promise&#60;Buffer&#62;`}   />




</div>


## SharpAssetPreviewConfig

<GenerationInfo sourceFile="packages/asset-server-plugin/src/config/sharp-asset-preview-strategy.ts" sourceLine="17" packageName="@vendure/asset-server-plugin" />

This <a href='/reference/typescript-api/assets/asset-preview-strategy#assetpreviewstrategy'>AssetPreviewStrategy</a> uses the [Sharp library](https://sharp.pixelplumbing.com/) to generate
preview images of uploaded binary files. For non-image binaries, a generic "file" icon with the mime type
overlay will be generated.

```ts title="Signature"
interface SharpAssetPreviewConfig {
    maxHeight?: number;
    maxWidth?: number;
    jpegOptions?: sharp.JpegOptions;
    pngOptions?: sharp.PngOptions;
    webpOptions?: sharp.WebpOptions;
    gifOptions?: sharp.GifOptions;
    avifOptions?: sharp.AvifOptions;
}
```

<div className="members-wrapper">

### maxHeight

<MemberInfo kind="property" type={`number`} default={`1600`}   />

The max height in pixels of a generated preview image.
### maxWidth

<MemberInfo kind="property" type={`number`} default={`1600`}   />

The max width in pixels of a generated preview image.
### jpegOptions

<MemberInfo kind="property" type={`sharp.JpegOptions`}  since="1.7.0"  />

Set Sharp's options for encoding jpeg files: https://sharp.pixelplumbing.com/api-output#jpeg
### pngOptions

<MemberInfo kind="property" type={`sharp.PngOptions`}  since="1.7.0"  />

Set Sharp's options for encoding png files: https://sharp.pixelplumbing.com/api-output#png
### webpOptions

<MemberInfo kind="property" type={`sharp.WebpOptions`}  since="1.7.0"  />

Set Sharp's options for encoding webp files: https://sharp.pixelplumbing.com/api-output#webp
### gifOptions

<MemberInfo kind="property" type={`sharp.GifOptions`}  since="1.7.0"  />

Set Sharp's options for encoding gif files: https://sharp.pixelplumbing.com/api-output#gif
### avifOptions

<MemberInfo kind="property" type={`sharp.AvifOptions`}  since="1.7.0"  />

Set Sharp's options for encoding avif files: https://sharp.pixelplumbing.com/api-output#avif


</div>


---

---
title: "ElasticsearchOptions"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ElasticsearchOptions

<GenerationInfo sourceFile="packages/elasticsearch-plugin/src/options.ts" sourceLine="30" packageName="@vendure/elasticsearch-plugin" />

Configuration options for the <a href='/reference/core-plugins/elasticsearch-plugin/#elasticsearchplugin'>ElasticsearchPlugin</a>.

```ts title="Signature"
interface ElasticsearchOptions {
    host?: string;
    port?: number;
    connectionAttempts?: number;
    connectionAttemptInterval?: number;
    clientOptions?: ClientOptions;
    indexPrefix?: string;
    indexSettings?: object;
    indexMappingProperties?: {
        [indexName: string]: object;
    };
    reindexProductsChunkSize?: number;
    reindexBulkOperationSizeLimit?: number;
    searchConfig?: SearchConfig;
    customProductMappings?: {
        [fieldName: string]: CustomMapping<
            [Product, ProductVariant[], LanguageCode, Injector, RequestContext]
        >;
    };
    customProductVariantMappings?: {
        [fieldName: string]: CustomMapping<[ProductVariant, LanguageCode, Injector, RequestContext]>;
    };
    bufferUpdates?: boolean;
    hydrateProductRelations?: Array<EntityRelationPaths<Product>>;
    hydrateProductVariantRelations?: Array<EntityRelationPaths<ProductVariant>>;
    extendSearchInputType?: {
        [name: string]: PrimitiveTypeVariations<GraphQlPrimitive>;
    };
    extendSearchSortType?: string[];
}
```

<div className="members-wrapper">

### host

<MemberInfo kind="property" type={`string`} default={`'http://localhost'`}   />

The host of the Elasticsearch server. May also be specified in `clientOptions.node`.
### port

<MemberInfo kind="property" type={`number`} default={`9200`}   />

The port of the Elasticsearch server. May also be specified in `clientOptions.node`.
### connectionAttempts

<MemberInfo kind="property" type={`number`} default={`10`}   />

Maximum amount of attempts made to connect to the ElasticSearch server on startup.
### connectionAttemptInterval

<MemberInfo kind="property" type={`number`} default={`5000`}   />

Interval in milliseconds between attempts to connect to the ElasticSearch server on startup.
### clientOptions

<MemberInfo kind="property" type={`ClientOptions`}   />

Options to pass directly to the
[Elasticsearch Node.js client](https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/index.html). For example, to
set authentication or other more advanced options.
Note that if the `node` or `nodes` option is specified, it will override the values provided in the `host` and `port` options.
### indexPrefix

<MemberInfo kind="property" type={`string`} default={`'vendure-'`}   />

Prefix for the indices created by the plugin.
### indexSettings

<MemberInfo kind="property" type={`object`} default={`{}`}  since="1.2.0"  />

[These options](https://www.elastic.co/guide/en/elasticsearch/reference/7.x/index-modules.html#index-modules-settings)
are directly passed to index settings. To apply some settings indices will be recreated.

*Example*

```ts
// Configuring an English stemmer
indexSettings: {
  analysis: {
    analyzer: {
      custom_analyzer: {
        tokenizer: 'standard',
        filter: [
          'lowercase',
          'english_stemmer'
        ]
      }
    },
    filter : {
      english_stemmer : {
        type : 'stemmer',
        name : 'english'
      }
    }
  }
},
```
A more complete example can be found in the discussion thread
[How to make elastic plugin to search by substring with stemming](https://github.com/vendure-ecommerce/vendure/discussions/1066).
### indexMappingProperties

<MemberInfo kind="property" type={`{         [indexName: string]: object;     }`} default={`{}`}  since="1.2.0"  />

This option allow to redefine or define new properties in mapping. More about elastic
[mapping](https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping.html)
After changing this option indices will be recreated.

*Example*

```ts
// Configuring custom analyzer for the `productName` field.
indexMappingProperties: {
  productName: {
    type: 'text',
    analyzer:'custom_analyzer',
    fields: {
      keyword: {
        type: 'keyword',
        ignore_above: 256,
      }
    }
  }
}
```

To reference a field defined by `customProductMappings` or `customProductVariantMappings`, you will
need to prefix the name with `'product-<name>'` or `'variant-<name>'` respectively, e.g.:

*Example*

```ts
customProductMappings: {
   variantCount: {
       graphQlType: 'Int!',
       valueFn: (product, variants) => variants.length,
   },
},
indexMappingProperties: {
  'product-variantCount': {
    type: 'integer',
  }
}
```
### reindexProductsChunkSize

<MemberInfo kind="property" type={`number`} default={`2500`}  since="2.1.7"  />

Products limit chunk size for each loop iteration when indexing products.
### reindexBulkOperationSizeLimit

<MemberInfo kind="property" type={`number`} default={`3000`}  since="2.1.7"  />

Index operations are performed in bulk, with each bulk operation containing a number of individual
index operations. This option sets the maximum number of operations in the memory buffer before a
bulk operation is executed.
### searchConfig

<MemberInfo kind="property" type={`<a href='/reference/core-plugins/elasticsearch-plugin/elasticsearch-options#searchconfig'>SearchConfig</a>`}   />

Configuration of the internal Elasticsearch query.
### customProductMappings

<MemberInfo kind="property" type={`{         [fieldName: string]: CustomMapping&#60;             [<a href='/reference/typescript-api/entities/product#product'>Product</a>, <a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>[], <a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a>, <a href='/reference/typescript-api/common/injector#injector'>Injector</a>, <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>]         &#62;;     }`}   />

Custom mappings may be defined which will add the defined data to the
Elasticsearch index and expose that data via the SearchResult GraphQL type,
adding a new `customMappings`, `customProductMappings` & `customProductVariantMappings` fields.

The `graphQlType` property may be one of `String`, `Int`, `Float`, `Boolean`, `ID` or list
versions thereof (`[String!]` etc) and can be appended with a `!` to indicate non-nullable fields.

The `public` (default = `true`) property is used to reveal or hide the property in the GraphQL API schema.
If this property is set to `false` it's not accessible in the `customMappings` field but it's still getting
parsed to the elasticsearch index.

This config option defines custom mappings which are accessible when the "groupByProduct" or "groupBySKU"
input options is set to `true` (Do not set both to true at the same time). In addition, custom variant mappings can be accessed by using
the `customProductVariantMappings` field, which is always available.

*Example*

```ts
customProductMappings: {
   variantCount: {
       graphQlType: 'Int!',
       valueFn: (product, variants) => variants.length,
   },
   reviewRating: {
       graphQlType: 'Float',
       public: true,
       valueFn: product => (product.customFields as any).reviewRating,
   },
   priority: {
       graphQlType: 'Int!',
       public: false,
       valueFn: product => (product.customFields as any).priority,
   },
}
```

*Example*

```graphql
query SearchProducts($input: SearchInput!) {
    search(input: $input) {
        totalItems
        items {
            productId
            productName
            customProductMappings {
                variantCount
                reviewRating
            }
            customMappings {
                ...on CustomProductMappings {
                    variantCount
                    reviewRating
                }
            }
        }
    }
}
```
### customProductVariantMappings

<MemberInfo kind="property" type={`{         [fieldName: string]: CustomMapping&#60;[<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>, <a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a>, <a href='/reference/typescript-api/common/injector#injector'>Injector</a>, <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>]&#62;;     }`}   />

This config option defines custom mappings which are accessible when the "groupByProduct" and "groupBySKU"
input options are both set to `false`. In addition, custom product mappings can be accessed by using
the `customProductMappings` field, which is always available.

*Example*

```graphql
query SearchProducts($input: SearchInput!) {
    search(input: $input) {
        totalItems
        items {
            productId
            productName
            customProductVariantMappings {
                weight
            }
            customMappings {
                ...on CustomProductVariantMappings {
                    weight
                }
            }
        }
    }
}
```
### bufferUpdates

<MemberInfo kind="property" type={`boolean`} default={`false`}  since="1.3.0"  />

If set to `true`, updates to Products, ProductVariants and Collections will not immediately
trigger an update to the search index. Instead, all these changes will be buffered and will
only be run via a call to the `runPendingSearchIndexUpdates` mutation in the Admin API.

This is very useful for installations with a large number of ProductVariants and/or
Collections, as the buffering allows better control over when these expensive jobs are run,
and also performs optimizations to minimize the amount of work that needs to be performed by
the worker.
### hydrateProductRelations

<MemberInfo kind="property" type={`Array&#60;<a href='/reference/typescript-api/common/entity-relation-paths#entityrelationpaths'>EntityRelationPaths</a>&#60;<a href='/reference/typescript-api/entities/product#product'>Product</a>&#62;&#62;`} default={`[]`}  since="1.3.0"  />

Additional product relations that will be fetched from DB while reindexing. This can be used
in combination with `customProductMappings` to ensure that the required relations are joined
before the `product` object is passed to the `valueFn`.

*Example*

```ts
{
  hydrateProductRelations: ['assets.asset'],
  customProductMappings: {
    assetPreviews: {
      graphQlType: '[String!]',
      // Here we can be sure that the `product.assets` array is populated
      // with an Asset object
      valueFn: (product) => product.assets.map(a => a.asset.preview),
    }
  }
}
```
### hydrateProductVariantRelations

<MemberInfo kind="property" type={`Array&#60;<a href='/reference/typescript-api/common/entity-relation-paths#entityrelationpaths'>EntityRelationPaths</a>&#60;<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>&#62;&#62;`} default={`[]`}  since="1.3.0"  />

Additional variant relations that will be fetched from DB while reindexing. See
`hydrateProductRelations` for more explanation and a usage example.
### extendSearchInputType

<MemberInfo kind="property" type={`{         [name: string]: PrimitiveTypeVariations&#60;GraphQlPrimitive&#62;;     }`} default={`{}`}  since="1.3.0"  />

Allows the `SearchInput` type to be extended with new input fields. This allows arbitrary
data to be passed in, which can then be used e.g. in the `mapQuery()` function or
custom `scriptFields` functions.

*Example*

```ts
extendSearchInputType: {
  longitude: 'Float',
  latitude: 'Float',
  radius: 'Float',
}
```

This allows the search query to include these new fields:

*Example*

```graphql
query {
  search(input: {
    longitude: 101.7117,
    latitude: 3.1584,
    radius: 50.00
  }) {
    items {
      productName
    }
  }
}
```
### extendSearchSortType

<MemberInfo kind="property" type={`string[]`} default={`[]`}  since="1.4.0"  />

Adds a list of sort parameters. This is mostly important to make the
correct sort order values available inside `input` parameter of the `mapSort` option.

*Example*

```ts
extendSearchSortType: ["distance"]
```

will extend the `SearchResultSortParameter` input type like this:

*Example*

```GraphQl
extend input SearchResultSortParameter {
     distance: SortOrder
}
```


</div>


## SearchConfig

<GenerationInfo sourceFile="packages/elasticsearch-plugin/src/options.ts" sourceLine="397" packageName="@vendure/elasticsearch-plugin" />

Configuration options for the internal Elasticsearch query which is generated when performing a search.

```ts title="Signature"
interface SearchConfig {
    facetValueMaxSize?: number;
    collectionMaxSize?: number;
    totalItemsMaxSize?: number | boolean;
    multiMatchType?: 'best_fields' | 'most_fields' | 'cross_fields' | 'phrase' | 'phrase_prefix' | 'bool_prefix';
    boostFields?: BoostFieldsConfig;
    priceRangeBucketInterval?: number;
    mapQuery?: (
        query: any,
        input: ElasticSearchInput,
        searchConfig: DeepRequired<SearchConfig>,
        channelId: ID,
        enabledOnly: boolean,
        ctx: RequestContext,
    ) => any;
    scriptFields?: { [fieldName: string]: CustomScriptMapping<[ElasticSearchInput]> };
    mapSort?: (sort: ElasticSearchSortInput, input: ElasticSearchInput) => ElasticSearchSortInput;
}
```

<div className="members-wrapper">

### facetValueMaxSize

<MemberInfo kind="property" type={`number`} default={`50`}   />

The maximum number of FacetValues to return from the search query. Internally, this
value sets the "size" property of an Elasticsearch aggregation.
### collectionMaxSize

<MemberInfo kind="property" type={`number`} default={`50`}  since="1.1.0"  />

The maximum number of Collections to return from the search query. Internally, this
value sets the "size" property of an Elasticsearch aggregation.
### totalItemsMaxSize

<MemberInfo kind="property" type={`number | boolean`} default={`10000`}  since="1.2.0"  />

The maximum number of totalItems to return from the search query. Internally, this
value sets the "track_total_hits" property of an Elasticsearch query.
If this parameter is set to "True", accurate count of totalItems will be returned.
If this parameter is set to "False", totalItems will be returned as 0.
If this parameter is set to integer, accurate count of totalItems will be returned not bigger than integer.
### multiMatchType

<MemberInfo kind="property" type={`'best_fields' | 'most_fields' | 'cross_fields' | 'phrase' | 'phrase_prefix' | 'bool_prefix'`} default={`'best_fields'`}   />

Defines the
[multi match type](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-multi-match-query.html#multi-match-types)
used when matching against a search term.
### boostFields

<MemberInfo kind="property" type={`<a href='/reference/core-plugins/elasticsearch-plugin/elasticsearch-options#boostfieldsconfig'>BoostFieldsConfig</a>`}   />

Set custom boost values for particular fields when matching against a search term.
### priceRangeBucketInterval

<MemberInfo kind="property" type={`number`}   />

The interval used to group search results into buckets according to price range. For example, setting this to
`2000` will group into buckets every $20.00:

```json
{
  "data": {
    "search": {
      "totalItems": 32,
      "priceRange": {
        "buckets": [
          {
            "to": 2000,
            "count": 21
          },
          {
            "to": 4000,
            "count": 7
          },
          {
            "to": 6000,
            "count": 3
          },
          {
            "to": 12000,
            "count": 1
          }
        ]
      }
    }
  }
}
```
### mapQuery

<MemberInfo kind="property" type={`(         query: any,         input: ElasticSearchInput,         searchConfig: DeepRequired&#60;<a href='/reference/core-plugins/elasticsearch-plugin/elasticsearch-options#searchconfig'>SearchConfig</a>&#62;,         channelId: <a href='/reference/typescript-api/common/id#id'>ID</a>,         enabledOnly: boolean,         ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>,     ) =&#62; any`}   />

This config option allows the the modification of the whole (already built) search query. This allows
for e.g. wildcard / fuzzy searches on the index.

*Example*

```ts
mapQuery: (query, input, searchConfig, channelId, enabledOnly, ctx) => {
  if (query.bool.must) {
    delete query.bool.must;
  }
  query.bool.should = [
    {
      query_string: {
        query: "*" + term + "*",
        fields: [
          `productName^${searchConfig.boostFields.productName}`,
          `productVariantName^${searchConfig.boostFields.productVariantName}`,
        ]
      }
    },
    {
      multi_match: {
        query: term,
        type: searchConfig.multiMatchType,
        fields: [
          `description^${searchConfig.boostFields.description}`,
          `sku^${searchConfig.boostFields.sku}`,
        ],
      },
    },
  ];

  return query;
}
```
### scriptFields

<MemberInfo kind="property" type={`{ [fieldName: string]: CustomScriptMapping&#60;[ElasticSearchInput]&#62; }`}  since="1.3.0"  />

Sets `script_fields` inside the elasticsearch body which allows returning a script evaluation for each hit.

The script field definition consists of three properties:

* `graphQlType`: This is the type that will be returned when this script field is queried
via the GraphQL API. It may be one of `String`, `Int`, `Float`, `Boolean`, `ID` or list
versions thereof (`[String!]` etc) and can be appended with a `!` to indicate non-nullable fields.
* `context`: determines whether this script field is available when grouping by product. Can be
`product`, `variant` or `both`.
* `scriptFn`: This is the function to run on each hit. Should return an object with a `script` property,
as covered in the
[Elasticsearch script fields docs](https://www.elastic.co/guide/en/elasticsearch/reference/7.15/search-fields.html#script-fields)

*Example*

```ts
extendSearchInputType: {
  latitude: 'Float',
  longitude: 'Float',
},
indexMappingProperties: {
  // The `product-location` field corresponds to the `location` customProductMapping
  // defined below. Here we specify that it would be index as a `geo_point` type,
  // which will allow us to perform geo-spacial calculations on it in our script field.
  'product-location': {
    type: 'geo_point', // contains function arcDistance
  },
},
customProductMappings: {
  location: {
    graphQlType: 'String',
    valueFn: (product: Product) => {
      // Assume that the Product entity has this customField defined
      const custom = product.customFields.location;
      return `${custom.latitude},${custom.longitude}`;
    },
  }
},
searchConfig: {
  scriptFields: {
    distance: {
      graphQlType: 'Float!',
      // Run this script only when grouping results by product
      context: 'product',
      scriptFn: (input) => {
        // The SearchInput was extended with latitude and longitude
        // via the `extendSearchInputType` option above.
        const lat = input.latitude;
        const lon = input.longitude;
        return {
          script: `doc['product-location'].arcDistance(${lat}, ${lon})`,
        }
      }
    }
  }
}
```
### mapSort

<MemberInfo kind="property" type={`(sort: ElasticSearchSortInput, input: ElasticSearchInput) =&#62; ElasticSearchSortInput`} default={`{}`}  since="1.4.0"  />

Allows extending the `sort` input of the elasticsearch body as covered in
[Elasticsearch sort docs](https://www.elastic.co/guide/en/elasticsearch/reference/current/sort-search-results.html)

The `sort` input parameter contains the ElasticSearchSortInput generated for the default sort parameters "name" and "price".
If neither of those are applied it will be empty.

*Example*

```ts
mapSort: (sort, input) => {
    // Assuming `extendSearchSortType: ["priority"]`
    // Assuming priority is never undefined
    const { priority } = input.sort;
    return [
         ...sort,
         {
             // The `product-priority` field corresponds to the `priority` customProductMapping
             // Depending on the index type, this field might require a
             // more detailed input (example: 'productName.keyword')
             ["product-priority"]: {
                 order: priority === SortOrder.ASC ? 'asc' : 'desc'
             }
         }
     ];
}
```

A more generic example would be a sort function based on a product location like this:

*Example*

```ts
extendSearchInputType: {
  latitude: 'Float',
  longitude: 'Float',
},
extendSearchSortType: ["distance"],
indexMappingProperties: {
  // The `product-location` field corresponds to the `location` customProductMapping
  // defined below. Here we specify that it would be index as a `geo_point` type,
  // which will allow us to perform geo-spacial calculations on it in our script field.
  'product-location': {
    type: 'geo_point',
  },
},
customProductMappings: {
  location: {
    graphQlType: 'String',
    valueFn: (product: Product) => {
      // Assume that the Product entity has this customField defined
      const custom = product.customFields.location;
      return `${custom.latitude},${custom.longitude}`;
    },
  }
},
searchConfig: {
     mapSort: (sort, input) => {
         // Assuming distance is never undefined
         const { distance } = input.sort;
         return [
             ...sort,
             {
                 ["_geo_distance"]: {
                     "product-location": [
                         input.longitude,
                         input.latitude
                     ],
                     order: distance === SortOrder.ASC ? 'asc' : 'desc',
                     unit: "km"
                 }
             }
         ];
     }
}
```


</div>


## BoostFieldsConfig

<GenerationInfo sourceFile="packages/elasticsearch-plugin/src/options.ts" sourceLine="683" packageName="@vendure/elasticsearch-plugin" />

Configuration for [boosting](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-multi-match-query.html#field-boost)
the scores of given fields when performing a search against a term.

Boosting a field acts as a score multiplier for matches against that field.

```ts title="Signature"
interface BoostFieldsConfig {
    productName?: number;
    productVariantName?: number;
    description?: number;
    sku?: number;
}
```

<div className="members-wrapper">

### productName

<MemberInfo kind="property" type={`number`} default={`1`}   />

Defines the boost factor for the productName field.
### productVariantName

<MemberInfo kind="property" type={`number`} default={`1`}   />

Defines the boost factor for the productVariantName field.
### description

<MemberInfo kind="property" type={`number`} default={`1`}   />

Defines the boost factor for the description field.
### sku

<MemberInfo kind="property" type={`number`} default={`1`}   />

Defines the boost factor for the sku field.


</div>


---

---
title: "ElasticsearchPlugin"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ElasticsearchPlugin

<GenerationInfo sourceFile="packages/elasticsearch-plugin/src/plugin.ts" sourceLine="225" packageName="@vendure/elasticsearch-plugin" />

This plugin allows your product search to be powered by [Elasticsearch](https://github.com/elastic/elasticsearch) - a powerful Open Source search
engine. This is a drop-in replacement for the DefaultSearchPlugin which exposes many powerful configuration options enabling your storefront
to support a wide range of use-cases such as indexing of custom properties, fine control over search index configuration, and to leverage
advanced Elasticsearch features like spacial search.

## Installation

**Requires Elasticsearch v7.0 < required Elasticsearch version < 7.10 **
Elasticsearch version 7.10.2 will throw error due to incompatibility with elasticsearch-js client.
[Check here for more info](https://github.com/elastic/elasticsearch-js/issues/1519).

`yarn add @elastic/elasticsearch @vendure/elasticsearch-plugin`

or

`npm install @elastic/elasticsearch @vendure/elasticsearch-plugin`

Make sure to remove the `DefaultSearchPlugin` if it is still in the VendureConfig plugins array.

Then add the `ElasticsearchPlugin`, calling the `.init()` method with <a href='/reference/core-plugins/elasticsearch-plugin/elasticsearch-options#elasticsearchoptions'>ElasticsearchOptions</a>:

*Example*

```ts
import { ElasticsearchPlugin } from '@vendure/elasticsearch-plugin';

const config: VendureConfig = {
  // Add an instance of the plugin to the plugins array
  plugins: [
    ElasticsearchPlugin.init({
      host: 'http://localhost',
      port: 9200,
    }),
  ],
};
```

## Search API Extensions
This plugin extends the default search query of the Shop API, allowing richer querying of your product data.

The [SearchResponse](/reference/graphql-api/shop/object-types/#searchresponse) type is extended with information
about price ranges in the result set:
```graphql
extend type SearchResponse {
    prices: SearchResponsePriceData!
}

type SearchResponsePriceData {
    range: PriceRange!
    rangeWithTax: PriceRange!
    buckets: [PriceRangeBucket!]!
    bucketsWithTax: [PriceRangeBucket!]!
}

type PriceRangeBucket {
    to: Int!
    count: Int!
}

extend input SearchInput {
    priceRange: PriceRangeInput
    priceRangeWithTax: PriceRangeInput
    inStock: Boolean
}

input PriceRangeInput {
    min: Int!
    max: Int!
}
```

This `SearchResponsePriceData` type allows you to query data about the range of prices in the result set.

## Example Request & Response

```graphql
{
  search (input: {
    term: "table easel"
    groupByProduct: true
    priceRange: {
      min: 500
      max: 7000
    }
  }) {
    totalItems
    prices {
      range {
        min
        max
      }
      buckets {
        to
        count
      }
    }
    items {
      productName
      score
      price {
        ...on PriceRange {
          min
          max
        }
      }
    }
  }
}
```

```json
{
 "data": {
   "search": {
     "totalItems": 9,
     "prices": {
       "range": {
         "min": 999,
         "max": 6396,
       },
       "buckets": [
         {
           "to": 1000,
           "count": 1
         },
         {
           "to": 2000,
           "count": 2
         },
         {
           "to": 3000,
           "count": 3
         },
         {
           "to": 4000,
           "count": 1
         },
         {
           "to": 5000,
           "count": 1
         },
         {
           "to": 7000,
           "count": 1
         }
       ]
     },
     "items": [
       {
         "productName": "Loxley Yorkshire Table Easel",
         "score": 30.58831,
         "price": {
           "min": 4984,
           "max": 4984
         }
       },
       // ... truncated
     ]
   }
 }
}
```

```ts title="Signature"
class ElasticsearchPlugin implements OnApplicationBootstrap {
    init(options: ElasticsearchOptions) => Type<ElasticsearchPlugin>;
}
```
* Implements: <code>OnApplicationBootstrap</code>



<div className="members-wrapper">

### init

<MemberInfo kind="method" type={`(options: <a href='/reference/core-plugins/elasticsearch-plugin/elasticsearch-options#elasticsearchoptions'>ElasticsearchOptions</a>) => Type&#60;<a href='/reference/core-plugins/elasticsearch-plugin/#elasticsearchplugin'>ElasticsearchPlugin</a>&#62;`}   />




</div>


---

---
title: "EmailEventHandlerWithAsyncData"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## EmailEventHandlerWithAsyncData

<GenerationInfo sourceFile="packages/email-plugin/src/handler/event-handler.ts" sourceLine="506" packageName="@vendure/email-plugin" />

Identical to the <a href='/reference/core-plugins/email-plugin/email-event-handler#emaileventhandler'>EmailEventHandler</a> but with a `data` property added to the `event` based on the result
of the `.loadData()` function.

```ts title="Signature"
class EmailEventHandlerWithAsyncData<Data, T extends string = string, InputEvent extends EventWithContext = EventWithContext, Event extends EventWithAsyncData<InputEvent, Data> = EventWithAsyncData<InputEvent, Data>> extends EmailEventHandler<T, Event> {
    constructor(_loadDataFn: LoadDataFn<InputEvent, Data>, listener: EmailEventListener<T>, event: Type<InputEvent>)
}
```
* Extends: <code><a href='/reference/core-plugins/email-plugin/email-event-handler#emaileventhandler'>EmailEventHandler</a>&#60;T, Event&#62;</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(_loadDataFn: <a href='/reference/core-plugins/email-plugin/email-plugin-types#loaddatafn'>LoadDataFn</a>&#60;InputEvent, Data&#62;, listener: <a href='/reference/core-plugins/email-plugin/email-event-listener#emaileventlistener'>EmailEventListener</a>&#60;T&#62;, event: Type&#60;InputEvent&#62;) => EmailEventHandlerWithAsyncData`}   />




</div>


---

---
title: "EmailEventHandler"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## EmailEventHandler

<GenerationInfo sourceFile="packages/email-plugin/src/handler/event-handler.ts" sourceLine="150" packageName="@vendure/email-plugin" />

The EmailEventHandler defines how the EmailPlugin will respond to a given event.

A handler is created by creating a new <a href='/reference/core-plugins/email-plugin/email-event-listener#emaileventlistener'>EmailEventListener</a> and calling the `.on()` method
to specify which event to respond to.

*Example*

```ts
const confirmationHandler = new EmailEventListener('order-confirmation')
  .on(OrderStateTransitionEvent)
  .filter(event => event.toState === 'PaymentSettled')
  .setRecipient(event => event.order.customer.emailAddress)
  .setFrom('{{ fromAddress }}')
  .setSubject(`Order confirmation for #{{ order.code }}`)
  .setTemplateVars(event => ({ order: event.order }));
```

This example creates a handler which listens for the `OrderStateTransitionEvent` and if the Order has
transitioned to the `'PaymentSettled'` state, it will generate and send an email.

The string argument passed into the `EmailEventListener` constructor is used to identify the handler, and
also to locate the directory of the email template files. So in the example above, there should be a directory
`<app root>/static/email/templates/order-confirmation` which contains a Handlebars template named `body.hbs`.

## Handling other languages

By default, the handler will respond to all events on all channels and use the same subject ("Order confirmation for #12345" above)
and body template.

Since v2.0 the `.addTemplate()` method has been **deprecated**. To serve different templates — for example, based on the current
`languageCode` — implement a custom <a href='/reference/core-plugins/email-plugin/template-loader#templateloader'>TemplateLoader</a> and pass it to `EmailPlugin.init({ templateLoader: new MyTemplateLoader() })`.

The language is typically determined by the `languageCode` property of the event's `ctx` (<a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) object, so the
`loadTemplate()` method can use that to locate the correct template file.

*Example*

```ts
import { EmailPlugin, TemplateLoader } from '@vendure/email-plugin';
import { readFileSync } from 'fs';
import path from 'path';

class CustomLanguageAwareTemplateLoader implements TemplateLoader {
  constructor(private templateDir: string) {}

  async loadTemplate(_injector, ctx, { type, templateName }) {
    // e.g. returns the content of "body.de.hbs" or "body.en.hbs" depending on ctx.languageCode
    const filePath = path.join(this.templateDir, type, `${templateName}.${ctx.languageCode}.hbs`);
    return readFileSync(filePath, 'utf-8');
  }
}

EmailPlugin.init({
  templateLoader: new CustomLanguageAwareTemplateLoader(path.join(__dirname, '../static/email/templates')),
  handlers: defaultEmailHandlers,
});
```

## Defining a custom handler

Let's say you have a plugin which defines a new event type, `QuoteRequestedEvent`. In your plugin you have defined a mutation
which is executed when the customer requests a quote in your storefront, and in your resolver, you use the <a href='/reference/typescript-api/events/event-bus#eventbus'>EventBus</a> to publish a
new `QuoteRequestedEvent`.

You now want to email the customer with their quote. Here are the steps you would take to set this up:

### 1. Create a new handler

```ts
import { EmailEventListener } from `@vendure/email-plugin`;
import { QuoteRequestedEvent } from `./events`;

const quoteRequestedHandler = new EmailEventListener('quote-requested')
  .on(QuoteRequestedEvent)
  .setRecipient(event => event.customer.emailAddress)
  .setSubject(`Here's the quote you requested`)
  .setFrom('{{ fromAddress }}')
  .setTemplateVars(event => ({ details: event.details }));
```

### 2. Create the email template

Next you need to make sure there is a template defined at `<app root>/static/email/templates/quote-requested/body.hbs`. The path
segment `quote-requested` must match the string passed to the `EmailEventListener` constructor.

The template would look something like this:

```handlebars
{{> header title="Here's the quote you requested" }}

<mj-section background-color="#fafafa">
    <mj-column>
        <mj-text color="#525252">
            Thank you for your interest in our products! Here's the details
            of the quote you recently requested:
        </mj-text>

        <!-- your custom email layout goes here -->
    </mj-column>
</mj-section>


{{> footer }}
```

You can find pre-made templates on the [MJML website](https://mjml.io/templates/).

### 3. Register the handler

Finally, you need to register the handler with the EmailPlugin:

```ts {hl_lines=[8]}
import { defaultEmailHandlers, EmailPlugin } from '@vendure/email-plugin';
import { quoteRequestedHandler } from './plugins/quote-plugin';

const config: VendureConfig = {
  // Add an instance of the plugin to the plugins array
  plugins: [
    EmailPlugin.init({
      handler: [...defaultEmailHandlers, quoteRequestedHandler],
      // ... etc
    }),
  ],
};
```

```ts title="Signature"
class EmailEventHandler<T extends string = string, Event extends EventWithContext = EventWithContext> {
    constructor(listener: EmailEventListener<T>, event: Type<Event>)
    filter(filterFn: (event: Event) => boolean) => EmailEventHandler<T, Event>;
    setRecipient(setRecipientFn: (event: Event) => string) => EmailEventHandler<T, Event>;
    setLanguageCode(setLanguageCodeFn: (event: Event) => LanguageCode | undefined) => EmailEventHandler<T, Event>;
    setTemplateVars(templateVarsFn: SetTemplateVarsFn<Event>) => EmailEventHandler<T, Event>;
    setSubject(defaultSubject: string | SetSubjectFn<Event>) => EmailEventHandler<T, Event>;
    setFrom(from: string) => EmailEventHandler<T, Event>;
    setOptionalAddressFields(optionalAddressFieldsFn: SetOptionalAddressFieldsFn<Event>) => ;
    setMetadata(optionalSetMetadataFn: SetMetadataFn<Event>) => ;
    setAttachments(setAttachmentsFn: SetAttachmentsFn<Event>) => ;
    addTemplate(config: EmailTemplateConfig) => EmailEventHandler<T, Event>;
    loadData(loadDataFn: LoadDataFn<Event, R>) => EmailEventHandlerWithAsyncData<R, T, Event, EventWithAsyncData<Event, R>>;
    setMockEvent(event: Omit<Event, 'ctx' | 'data'>) => EmailEventHandler<T, Event>;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(listener: <a href='/reference/core-plugins/email-plugin/email-event-listener#emaileventlistener'>EmailEventListener</a>&#60;T&#62;, event: Type&#60;Event&#62;) => EmailEventHandler`}   />


### filter

<MemberInfo kind="method" type={`(filterFn: (event: Event) =&#62; boolean) => <a href='/reference/core-plugins/email-plugin/email-event-handler#emaileventhandler'>EmailEventHandler</a>&#60;T, Event&#62;`}   />

Defines a predicate function which is used to determine whether the event will trigger an email.
Multiple filter functions may be defined.
### setRecipient

<MemberInfo kind="method" type={`(setRecipientFn: (event: Event) =&#62; string) => <a href='/reference/core-plugins/email-plugin/email-event-handler#emaileventhandler'>EmailEventHandler</a>&#60;T, Event&#62;`}   />

A function which defines how the recipient email address should be extracted from the incoming event.

The recipient can be a plain email address: `'foobar@example.com'`
Or with a formatted name (includes unicode support): `'Ноде Майлер <foobar@example.com>'`
Or a comma-separated list of addresses: `'foobar@example.com, "Ноде Майлер" <bar@example.com>'`
### setLanguageCode

<MemberInfo kind="method" type={`(setLanguageCodeFn: (event: Event) =&#62; <a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a> | undefined) => <a href='/reference/core-plugins/email-plugin/email-event-handler#emaileventhandler'>EmailEventHandler</a>&#60;T, Event&#62;`}  since="1.8.0"  />

A function which allows to override the language of the email. If not defined, the language from the context will be used.
### setTemplateVars

<MemberInfo kind="method" type={`(templateVarsFn: <a href='/reference/core-plugins/email-plugin/email-plugin-types#settemplatevarsfn'>SetTemplateVarsFn</a>&#60;Event&#62;) => <a href='/reference/core-plugins/email-plugin/email-event-handler#emaileventhandler'>EmailEventHandler</a>&#60;T, Event&#62;`}   />

A function which returns an object hash of variables which will be made available to the Handlebars template
and subject line for interpolation.
### setSubject

<MemberInfo kind="method" type={`(defaultSubject: string | <a href='/reference/core-plugins/email-plugin/email-plugin-types#setsubjectfn'>SetSubjectFn</a>&#60;Event&#62;) => <a href='/reference/core-plugins/email-plugin/email-event-handler#emaileventhandler'>EmailEventHandler</a>&#60;T, Event&#62;`}   />

Sets the default subject of the email. The subject string may use Handlebars variables defined by the
setTemplateVars() method.
### setFrom

<MemberInfo kind="method" type={`(from: string) => <a href='/reference/core-plugins/email-plugin/email-event-handler#emaileventhandler'>EmailEventHandler</a>&#60;T, Event&#62;`}   />

Sets the default from field of the email. The from string may use Handlebars variables defined by the
setTemplateVars() method.
### setOptionalAddressFields

<MemberInfo kind="method" type={`(optionalAddressFieldsFn: <a href='/reference/core-plugins/email-plugin/email-plugin-types#setoptionaladdressfieldsfn'>SetOptionalAddressFieldsFn</a>&#60;Event&#62;) => `}  since="1.1.0"  />

A function which allows <a href='/reference/core-plugins/email-plugin/email-plugin-types#optionaladdressfields'>OptionalAddressFields</a> to be specified such as "cc" and "bcc".
### setMetadata

<MemberInfo kind="method" type={`(optionalSetMetadataFn: <a href='/reference/core-plugins/email-plugin/email-plugin-types#setmetadatafn'>SetMetadataFn</a>&#60;Event&#62;) => `}  since="3.1.0"  />

A function which allows <a href='/reference/core-plugins/email-plugin/email-plugin-types#emailmetadata'>EmailMetadata</a> to be specified for the email. This can be used
to store arbitrary data about the email which can be used for tracking or other purposes.

It will be exposed in the <a href='/reference/core-plugins/email-plugin/email-send-event#emailsendevent'>EmailSendEvent</a> as `event.metadata`. Here's an example of usage:

- An <a href='/reference/typescript-api/events/event-types#orderstatetransitionevent'>OrderStateTransitionEvent</a> occurs, and the EmailEventListener starts processing it.
- The EmailEventHandler attaches metadata to the email:
   ```ts
   new EmailEventListener(EventType.ORDER_CONFIRMATION)
     .on(OrderStateTransitionEvent)
     .setMetadata(event => ({
       type: EventType.ORDER_CONFIRMATION,
       orderId: event.order.id,
     }));
  ```
- Then, the EmailPlugin tries to send the email and publishes <a href='/reference/core-plugins/email-plugin/email-send-event#emailsendevent'>EmailSendEvent</a>,
  passing ctx, emailDetails, error or success, and this metadata.
- In another part of the server, we have an eventBus that subscribes to EmailSendEvent. We can use
  `metadata.type` and `metadata.orderId` to identify the related order. For example, we can indicate on the
   order that the email was successfully sent, or in case of an error, send a notification confirming
   the order in another available way.
### setAttachments

<MemberInfo kind="method" type={`(setAttachmentsFn: <a href='/reference/core-plugins/email-plugin/email-plugin-types#setattachmentsfn'>SetAttachmentsFn</a>&#60;Event&#62;) => `}   />

Defines one or more files to be attached to the email. An attachment can be specified
as either a `path` (to a file or URL) or as `content` which can be a string, Buffer or Stream.

**Note:** When using the `content` to pass a Buffer or Stream, the raw data will get serialized
into the job queue. For this reason the total size of all attachments passed as `content` should kept to
**less than ~50k**. If the attachments are greater than that limit, a warning will be logged and
errors may result if using the DefaultJobQueuePlugin with certain DBs such as MySQL/MariaDB.

*Example*

```ts
const testAttachmentHandler = new EmailEventListener('activate-voucher')
  .on(ActivateVoucherEvent)
  // ... omitted some steps for brevity
  .setAttachments(async (event) => {
    const { imageUrl, voucherCode } = await getVoucherDataForUser(event.user.id);
    return [
      {
        filename: `voucher-${voucherCode}.jpg`,
        path: imageUrl,
      },
    ];
  });
```
### addTemplate

<MemberInfo kind="method" type={`(config: EmailTemplateConfig) => <a href='/reference/core-plugins/email-plugin/email-event-handler#emaileventhandler'>EmailEventHandler</a>&#60;T, Event&#62;`}   />

Add configuration for another template other than the default `"body.hbs"`. Use this method to define specific
templates for channels or languageCodes other than the default.
### loadData

<MemberInfo kind="method" type={`(loadDataFn: <a href='/reference/core-plugins/email-plugin/email-plugin-types#loaddatafn'>LoadDataFn</a>&#60;Event, R&#62;) => <a href='/reference/core-plugins/email-plugin/email-event-handler-with-async-data#emaileventhandlerwithasyncdata'>EmailEventHandlerWithAsyncData</a>&#60;R, T, Event, <a href='/reference/core-plugins/email-plugin/email-plugin-types#eventwithasyncdata'>EventWithAsyncData</a>&#60;Event, R&#62;&#62;`}   />

Allows data to be loaded asynchronously which can then be used as template variables.
The `loadDataFn` has access to the event, the TypeORM `Connection` object, and an
`inject()` function which can be used to inject any of the providers exported
by the <a href='/reference/typescript-api/plugin/plugin-common-module#plugincommonmodule'>PluginCommonModule</a>. The return value of the `loadDataFn` will be
added to the `event` as the `data` property.

*Example*

```ts
new EmailEventListener('order-confirmation')
  .on(OrderStateTransitionEvent)
  .filter(event => event.toState === 'PaymentSettled' && !!event.order.customer)
  .loadData(({ event, injector }) => {
    const orderService = injector.get(OrderService);
    return orderService.getOrderPayments(event.order.id);
  })
  .setTemplateVars(event => ({
    order: event.order,
    payments: event.data,
  }))
  // ...
```
### setMockEvent

<MemberInfo kind="method" type={`(event: Omit&#60;Event, 'ctx' | 'data'&#62;) => <a href='/reference/core-plugins/email-plugin/email-event-handler#emaileventhandler'>EmailEventHandler</a>&#60;T, Event&#62;`}   />

Optionally define a mock Event which is used by the dev mode mailbox app for generating mock emails
from this handler, which is useful when developing the email templates.


</div>


---

---
title: "EmailEventListener"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## EmailEventListener

<GenerationInfo sourceFile="packages/email-plugin/src/event-listener.ts" sourceLine="13" packageName="@vendure/email-plugin" />

An EmailEventListener is used to listen for events and set up a <a href='/reference/core-plugins/email-plugin/email-event-handler#emaileventhandler'>EmailEventHandler</a> which
defines how an email will be generated from this event.

```ts title="Signature"
class EmailEventListener<T extends string> {
    public type: T;
    constructor(type: T)
    on(event: Type<Event>) => EmailEventHandler<T, Event>;
}
```

<div className="members-wrapper">

### type

<MemberInfo kind="property" type={`T`}   />


### constructor

<MemberInfo kind="method" type={`(type: T) => EmailEventListener`}   />


### on

<MemberInfo kind="method" type={`(event: Type&#60;Event&#62;) => <a href='/reference/core-plugins/email-plugin/email-event-handler#emaileventhandler'>EmailEventHandler</a>&#60;T, Event&#62;`}   />

Defines the event to listen for.


</div>


---

---
title: "EmailGenerator"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## EmailGenerator

<GenerationInfo sourceFile="packages/email-plugin/src/generator/email-generator.ts" sourceLine="13" packageName="@vendure/email-plugin" />

An EmailGenerator generates the subject and body details of an email.

```ts title="Signature"
interface EmailGenerator<T extends string = any, E extends VendureEvent = any> extends InjectableStrategy {
    onInit?(options: EmailPluginOptions): void | Promise<void>;
    generate(
        from: string,
        subject: string,
        body: string,
        templateVars: { [key: string]: any },
    ): Pick<EmailDetails, 'from' | 'subject' | 'body'>;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### onInit

<MemberInfo kind="method" type={`(options: <a href='/reference/core-plugins/email-plugin/email-plugin-options#emailpluginoptions'>EmailPluginOptions</a>) => void | Promise&#60;void&#62;`}   />

Any necessary setup can be performed here.
### generate

<MemberInfo kind="method" type={`(from: string, subject: string, body: string, templateVars: { [key: string]: any }) => Pick&#60;<a href='/reference/core-plugins/email-plugin/email-plugin-types#emaildetails'>EmailDetails</a>, 'from' | 'subject' | 'body'&#62;`}   />

Given a subject and body from an email template, this method generates the final
interpolated email text.


</div>


## HandlebarsMjmlGenerator

<GenerationInfo sourceFile="packages/email-plugin/src/generator/handlebars-mjml-generator.ts" sourceLine="17" packageName="@vendure/email-plugin" />

Uses Handlebars (https://handlebarsjs.com/) to output MJML (https://mjml.io) which is then
compiled down to responsive email HTML.

```ts title="Signature"
class HandlebarsMjmlGenerator implements EmailGenerator {
    onInit(options: InitializedEmailPluginOptions) => ;
    generate(from: string, subject: string, template: string, templateVars: any) => ;
}
```
* Implements: <code><a href='/reference/core-plugins/email-plugin/email-generator#emailgenerator'>EmailGenerator</a></code>



<div className="members-wrapper">

### onInit

<MemberInfo kind="method" type={`(options: InitializedEmailPluginOptions) => `}   />


### generate

<MemberInfo kind="method" type={`(from: string, subject: string, template: string, templateVars: any) => `}   />




</div>


---

---
title: "EmailPluginOptions"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## EmailPluginOptions

<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="77" packageName="@vendure/email-plugin" />

Configuration for the EmailPlugin.

```ts title="Signature"
interface EmailPluginOptions {
    templatePath?: string;
    templateLoader?: TemplateLoader;
    transport:
        | EmailTransportOptions
        | ((
              injector?: Injector,
              ctx?: RequestContext,
          ) => EmailTransportOptions | Promise<EmailTransportOptions>);
    handlers: Array<EmailEventHandler<string, any>>;
    globalTemplateVars?: { [key: string]: any } | GlobalTemplateVarsFn;
    emailSender?: EmailSender;
    emailGenerator?: EmailGenerator;
}
```

<div className="members-wrapper">

### templatePath

<MemberInfo kind="property" type={`string`}   />

The path to the location of the email templates. In a default Vendure installation,
the templates are installed to `<project root>/vendure/email/templates`.
### templateLoader

<MemberInfo kind="property" type={`<a href='/reference/core-plugins/email-plugin/template-loader#templateloader'>TemplateLoader</a>`}  since="2.0.0"  />

An optional TemplateLoader which can be used to load templates from a custom location or async service.
The default uses the FileBasedTemplateLoader which loads templates from `<project root>/vendure/email/templates`
### transport

<MemberInfo kind="property" type={`| <a href='/reference/core-plugins/email-plugin/transport-options#emailtransportoptions'>EmailTransportOptions</a>         | ((               injector?: <a href='/reference/typescript-api/common/injector#injector'>Injector</a>,               ctx?: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>,           ) =&#62; <a href='/reference/core-plugins/email-plugin/transport-options#emailtransportoptions'>EmailTransportOptions</a> | Promise&#60;<a href='/reference/core-plugins/email-plugin/transport-options#emailtransportoptions'>EmailTransportOptions</a>&#62;)`}   />

Configures how the emails are sent.
### handlers

<MemberInfo kind="property" type={`Array&#60;<a href='/reference/core-plugins/email-plugin/email-event-handler#emaileventhandler'>EmailEventHandler</a>&#60;string, any&#62;&#62;`}   />

An array of <a href='/reference/core-plugins/email-plugin/email-event-handler#emaileventhandler'>EmailEventHandler</a>s which define which Vendure events will trigger
emails, and how those emails are generated.
### globalTemplateVars

<MemberInfo kind="property" type={`{ [key: string]: any } | <a href='/reference/core-plugins/email-plugin/email-plugin-options#globaltemplatevarsfn'>GlobalTemplateVarsFn</a>`}   />

An object containing variables which are made available to all templates. For example,
the storefront URL could be defined here and then used in the "email address verification"
email. Use the GlobalTemplateVarsFn if you need to retrieve variables from Vendure or
plugin services.
### emailSender

<MemberInfo kind="property" type={`<a href='/reference/core-plugins/email-plugin/email-sender#emailsender'>EmailSender</a>`} default={`<a href='/reference/core-plugins/email-plugin/email-sender#nodemaileremailsender'>NodemailerEmailSender</a>`}   />

An optional allowed EmailSender, used to allow custom implementations of the send functionality
while still utilizing the existing emailPlugin functionality.
### emailGenerator

<MemberInfo kind="property" type={`<a href='/reference/core-plugins/email-plugin/email-generator#emailgenerator'>EmailGenerator</a>`} default={`<a href='/reference/core-plugins/email-plugin/email-generator#handlebarsmjmlgenerator'>HandlebarsMjmlGenerator</a>`}   />

An optional allowed EmailGenerator, used to allow custom email generation functionality to
better match with custom email sending functionality.


</div>


## GlobalTemplateVarsFn

<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="64" packageName="@vendure/email-plugin" since="2.3.0" />

Allows you to dynamically load the "globalTemplateVars" key async and access Vendure services
to create the object. This is not a requirement. You can also specify a simple static object if your
projects doesn't need to access async or dynamic values.

*Example*

```ts

EmailPlugin.init({
   globalTemplateVars: async (ctx, injector) => {
         const myAsyncService = injector.get(MyAsyncService);
         const asyncValue = await myAsyncService.get(ctx);
         const channel = ctx.channel;
         const { primaryColor } = channel.customFields.theme;
         const theme = {
             primaryColor,
             asyncValue,
         };
         return theme;
     }
  [...]
})

```

```ts title="Signature"
type GlobalTemplateVarsFn = (
    ctx: RequestContext,
    injector: Injector,
) => Promise<{ [key: string]: any }>
```


## EmailPluginDevModeOptions

<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="150" packageName="@vendure/email-plugin" />

Configuration for running the EmailPlugin in development mode.

```ts title="Signature"
interface EmailPluginDevModeOptions extends Omit<EmailPluginOptions, 'transport'> {
    devMode: true;
    outputPath: string;
    route: string;
}
```
* Extends: <code>Omit&#60;<a href='/reference/core-plugins/email-plugin/email-plugin-options#emailpluginoptions'>EmailPluginOptions</a>, 'transport'&#62;</code>



<div className="members-wrapper">

### devMode

<MemberInfo kind="property" type={`true`}   />


### outputPath

<MemberInfo kind="property" type={`string`}   />

The path to which html email files will be saved rather than being sent.
### route

<MemberInfo kind="property" type={`string`}   />

The route to the dev mailbox server.


</div>


---

---
title: "Email Plugin Types"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## EventWithContext

<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="22" packageName="@vendure/email-plugin" />

A VendureEvent which also includes a `ctx` property containing the current
<a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, which is used to determine the channel and language
to use when generating the email.

```ts title="Signature"
type EventWithContext = VendureEvent & { ctx: RequestContext }
```


## EventWithAsyncData

<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="32" packageName="@vendure/email-plugin" />

A VendureEvent with a <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a> and a `data` property which contains the
value resolved from the <a href='/reference/core-plugins/email-plugin/email-event-handler#emaileventhandler'>EmailEventHandler</a>`.loadData()` callback.

```ts title="Signature"
type EventWithAsyncData<Event extends EventWithContext, R> = Event & { data: R }
```


## EmailDetails

<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="288" packageName="@vendure/email-plugin" />

The final, generated email details to be sent.

```ts title="Signature"
interface EmailDetails<Type extends 'serialized' | 'unserialized' = 'unserialized'> {
    from: string;
    recipient: string;
    subject: string;
    body: string;
    attachments: Array<Type extends 'serialized' ? SerializedAttachment : Attachment>;
    cc?: string;
    bcc?: string;
    replyTo?: string;
}
```

<div className="members-wrapper">

### from

<MemberInfo kind="property" type={`string`}   />


### recipient

<MemberInfo kind="property" type={`string`}   />


### subject

<MemberInfo kind="property" type={`string`}   />


### body

<MemberInfo kind="property" type={`string`}   />


### attachments

<MemberInfo kind="property" type={`Array&#60;Type extends 'serialized' ? SerializedAttachment : Attachment&#62;`}   />


### cc

<MemberInfo kind="property" type={`string`}   />


### bcc

<MemberInfo kind="property" type={`string`}   />


### replyTo

<MemberInfo kind="property" type={`string`}   />




</div>


## LoadDataFn

<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="322" packageName="@vendure/email-plugin" />

A function used to load async data for use by an <a href='/reference/core-plugins/email-plugin/email-event-handler#emaileventhandler'>EmailEventHandler</a>.

```ts title="Signature"
type LoadDataFn<Event extends EventWithContext, R> = (context: {
    event: Event;
    injector: Injector;
}) => Promise<R>
```


## EmailAttachment

<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="341" packageName="@vendure/email-plugin" />

An object defining a file attachment for an email. Based on the object described
[here in the Nodemailer docs](https://nodemailer.com/message/attachments/), but
only uses the `path` property to define a filesystem path or a URL pointing to
the attachment file.

```ts title="Signature"
type EmailAttachment = Omit<Attachment, 'raw'> & { path?: string }
```


## LoadTemplateInput

<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="402" packageName="@vendure/email-plugin" />

The object passed to the <a href='/reference/core-plugins/email-plugin/template-loader#templateloader'>TemplateLoader</a> `loadTemplate()` method.

```ts title="Signature"
interface LoadTemplateInput {
    type: string;
    templateName: string;
    templateVars: any;
}
```

<div className="members-wrapper">

### type

<MemberInfo kind="property" type={`string`}   />

The type corresponds to the string passed to the EmailEventListener constructor.
### templateName

<MemberInfo kind="property" type={`string`}   />

The template name is specified by the EmailEventHander's call to
the `addTemplate()` method, and will default to `body.hbs`
### templateVars

<MemberInfo kind="property" type={`any`}   />

The variables defined by the globalTemplateVars as well as any variables defined in the
EmailEventHandler's `setTemplateVars()` method.


</div>


## SetTemplateVarsFn

<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="435" packageName="@vendure/email-plugin" />

A function used to define template variables available to email templates.
See <a href='/reference/core-plugins/email-plugin/email-event-handler#emaileventhandler'>EmailEventHandler</a>.setTemplateVars().

```ts title="Signature"
type SetTemplateVarsFn<Event> = (
    event: Event,
    globals: { [key: string]: any },
) => { [key: string]: any }
```


## SetAttachmentsFn

<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="449" packageName="@vendure/email-plugin" />

A function used to define attachments to be sent with the email.
See https://nodemailer.com/message/attachments/ for more information about
how attachments work in Nodemailer.

```ts title="Signature"
type SetAttachmentsFn<Event> = (event: Event) => EmailAttachment[] | Promise<EmailAttachment[]>
```


## SetSubjectFn

<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="457" packageName="@vendure/email-plugin" />

A function used to define the subject to be sent with the email.

```ts title="Signature"
type SetSubjectFn<Event> = (
    event: Event,
    ctx: RequestContext,
    injector: Injector,
) => string | Promise<string>
```


## OptionalAddressFields

<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="471" packageName="@vendure/email-plugin" since="1.1.0" />

Optional address-related fields for sending the email.

```ts title="Signature"
interface OptionalAddressFields {
    cc?: string;
    bcc?: string;
    replyTo?: string;
}
```

<div className="members-wrapper">

### cc

<MemberInfo kind="property" type={`string`}   />

Comma separated list of recipients email addresses that will appear on the _Cc:_ field
### bcc

<MemberInfo kind="property" type={`string`}   />

Comma separated list of recipients email addresses that will appear on the _Bcc:_ field
### replyTo

<MemberInfo kind="property" type={`string`}   />

An email address that will appear on the _Reply-To:_ field


</div>


## SetOptionalAddressFieldsFn

<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="497" packageName="@vendure/email-plugin" since="1.1.0" />

A function used to set the <a href='/reference/core-plugins/email-plugin/email-plugin-types#optionaladdressfields'>OptionalAddressFields</a>.

```ts title="Signature"
type SetOptionalAddressFieldsFn<Event> = (
    event: Event,
) => OptionalAddressFields | Promise<OptionalAddressFields>
```


## SetMetadataFn

<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="509" packageName="@vendure/email-plugin" since="3.1.0" />

A function used to set the <a href='/reference/core-plugins/email-plugin/email-plugin-types#emailmetadata'>EmailMetadata</a>.

```ts title="Signature"
type SetMetadataFn<Event> = (event: Event) => EmailMetadata | Promise<EmailMetadata>
```


## EmailMetadata

<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="519" packageName="@vendure/email-plugin" since="3.1.0" />

Metadata that can be attached to an email via the <a href='/reference/core-plugins/email-plugin/email-event-handler#emaileventhandler'>EmailEventHandler</a>`.setMetadata()` method.

```ts title="Signature"
type EmailMetadata = Record<string, any>
```


---

---
title: "EmailSendEvent"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## EmailSendEvent

<GenerationInfo sourceFile="packages/email-plugin/src/email-send-event.ts" sourceLine="14" packageName="@vendure/email-plugin" since="2.2.0" />

This event is fired when an email sending attempt has been made. If the sending was successful,
the `success` property will be `true`, and if not, the `error` property will contain the error
which occurred.

```ts title="Signature"
class EmailSendEvent extends VendureEvent {
    constructor(ctx: RequestContext, details: EmailDetails, success: boolean, error?: Error, metadata?: EmailMetadata)
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-event#vendureevent'>VendureEvent</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, details: <a href='/reference/core-plugins/email-plugin/email-plugin-types#emaildetails'>EmailDetails</a>, success: boolean, error?: Error, metadata?: <a href='/reference/core-plugins/email-plugin/email-plugin-types#emailmetadata'>EmailMetadata</a>) => EmailSendEvent`}   />




</div>


---

---
title: "EmailSender"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## EmailSender

<GenerationInfo sourceFile="packages/email-plugin/src/sender/email-sender.ts" sourceLine="45" packageName="@vendure/email-plugin" />

An EmailSender is responsible for sending the email, e.g. via an SMTP connection
or using some other mail-sending API. By default, the EmailPlugin uses the
<a href='/reference/core-plugins/email-plugin/email-sender#nodemaileremailsender'>NodemailerEmailSender</a>, but it is also possible to supply a custom implementation:

*Example*

```ts
const sgMail = require('@sendgrid/mail');

sgMail.setApiKey(process.env.SENDGRID_API_KEY);

class SendgridEmailSender implements EmailSender {
  async send(email: EmailDetails) {
    await sgMail.send({
      to: email.recipient,
      from: email.from,
      subject: email.subject,
      html: email.body,
    });
  }
}

const config: VendureConfig = {
  logger: new DefaultLogger({ level: LogLevel.Debug })
  // ...
  plugins: [
    EmailPlugin.init({
       // ... template, handler config omitted
      transport: { type: 'none' },
       emailSender: new SendgridEmailSender(),
    }),
  ],
};
```

```ts title="Signature"
interface EmailSender extends InjectableStrategy {
    send: (email: EmailDetails, options: EmailTransportOptions) => void | Promise<void>;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### send

<MemberInfo kind="property" type={`(email: <a href='/reference/core-plugins/email-plugin/email-plugin-types#emaildetails'>EmailDetails</a>, options: <a href='/reference/core-plugins/email-plugin/transport-options#emailtransportoptions'>EmailTransportOptions</a>) =&#62; void | Promise&#60;void&#62;`}   />




</div>


## NodemailerEmailSender

<GenerationInfo sourceFile="packages/email-plugin/src/sender/nodemailer-email-sender.ts" sourceLine="39" packageName="@vendure/email-plugin" />

Uses the configured transport to send the generated email.

```ts title="Signature"
class NodemailerEmailSender implements EmailSender {
    send(email: EmailDetails, options: EmailTransportOptions) => ;
}
```
* Implements: <code><a href='/reference/core-plugins/email-plugin/email-sender#emailsender'>EmailSender</a></code>



<div className="members-wrapper">

### send

<MemberInfo kind="method" type={`(email: <a href='/reference/core-plugins/email-plugin/email-plugin-types#emaildetails'>EmailDetails</a>, options: <a href='/reference/core-plugins/email-plugin/transport-options#emailtransportoptions'>EmailTransportOptions</a>) => `}   />




</div>


---

---
title: "Email Utils"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## transformOrderLineAssetUrls

<GenerationInfo sourceFile="packages/email-plugin/src/handler/default-email-handlers.ts" sourceLine="106" packageName="@vendure/email-plugin" />

Applies the configured `AssetStorageStrategy.toAbsoluteUrl()` function to each of the
OrderLine's `featuredAsset.preview` properties, so that they can be correctly displayed
in the email template.
This is required since that step usually happens at the API in middleware, which is not
applicable in this context. So we need to do it manually.

**Note: Mutates the Order object**

```ts title="Signature"
function transformOrderLineAssetUrls(ctx: RequestContext, order: Order, injector: Injector): Order
```
Parameters

### ctx

<MemberInfo kind="parameter" type={`<a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>`} />

### order

<MemberInfo kind="parameter" type={`<a href='/reference/typescript-api/entities/order#order'>Order</a>`} />

### injector

<MemberInfo kind="parameter" type={`<a href='/reference/typescript-api/common/injector#injector'>Injector</a>`} />



## shippingLinesWithMethod

<GenerationInfo sourceFile="packages/email-plugin/src/handler/default-email-handlers.ts" sourceLine="127" packageName="@vendure/email-plugin" />

Ensures that the ShippingLines have a shippingMethod so that we can use the
`shippingMethod.name` property in the email template.

```ts title="Signature"
function shippingLinesWithMethod(order: Order): ShippingLine[]
```
Parameters

### order

<MemberInfo kind="parameter" type={`<a href='/reference/typescript-api/entities/order#order'>Order</a>`} />



---

---
title: "EmailPlugin"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## EmailPlugin

<GenerationInfo sourceFile="packages/email-plugin/src/plugin.ts" sourceLine="304" packageName="@vendure/email-plugin" />

The EmailPlugin creates and sends transactional emails based on Vendure events. By default, it uses an [MJML](https://mjml.io/)-based
email generator to generate the email body and [Nodemailer](https://nodemailer.com/about/) to send the emails.

## High-level description
Vendure has an internal events system (see <a href='/reference/typescript-api/events/event-bus#eventbus'>EventBus</a>) that allows plugins to subscribe to events. The EmailPlugin is configured with <a href='/reference/core-plugins/email-plugin/email-event-handler#emaileventhandler'>EmailEventHandler</a>s
that listen for a specific event and when it is published, the handler defines which template to use to generate the resulting email.

The plugin comes with a set of default handler for the following events:
- Order confirmation
- New customer email address verification
- Password reset request
- Email address change request

You can also create your own handler and register them with the plugin - see the <a href='/reference/core-plugins/email-plugin/email-event-handler#emaileventhandler'>EmailEventHandler</a> docs for more details.

## Installation

`yarn add @vendure/email-plugin`

or

`npm install @vendure/email-plugin`

*Example*

```ts
import { defaultEmailHandlers, EmailPlugin, FileBasedTemplateLoader } from '@vendure/email-plugin';

const config: VendureConfig = {
  // Add an instance of the plugin to the plugins array
  plugins: [
    EmailPlugin.init({
      handler: defaultEmailHandlers,
      templateLoader: new FileBasedTemplateLoader(path.join(__dirname, '../static/email/templates')),
      transport: {
        type: 'smtp',
        host: 'smtp.example.com',
        port: 587,
        auth: {
          user: 'username',
          pass: 'password',
        }
      },
    }),
  ],
};
```

## Email templates

In the example above, the plugin has been configured to look in `<app-root>/static/email/templates`
for the email template files. If you used `@vendure/create` to create your application, the templates will have
been copied to that location during setup.

If you are installing the EmailPlugin separately, then you'll need to copy the templates manually from
`node_modules/@vendure/email-plugin/templates` to a location of your choice, and then point the `templatePath` config
property at that directory.

* ### Dynamic Email Templates
Instead of passing a static value to `templatePath`, use `templateLoader` to define a template path.
```ts
  EmailPlugin.init({
   ...,
   templateLoader: new FileBasedTemplateLoader(my/order-confirmation/templates)
  })
```
## Customizing templates

Emails are generated from templates which use [MJML](https://mjml.io/) syntax. MJML is an open-source HTML-like markup
language which makes the task of creating responsive email markup simple. By default, the templates are installed to
`<project root>/vendure/email/templates` and can be freely edited.

Dynamic data such as the recipient's name or order items are specified using [Handlebars syntax](https://handlebarsjs.com/):

```html
<p>Dear {{ order.customer.firstName }} {{ order.customer.lastName }},</p>

<p>Thank you for your order!</p>

<mj-table cellpadding="6px">
  {{#each order.lines }}
    <tr class="order-row">
      <td>{{ quantity }} x {{ productVariant.name }}</td>
      <td>{{ productVariant.quantity }}</td>
      <td>{{ formatMoney totalPrice }}</td>
    </tr>
  {{/each}}
</mj-table>
```

### Setting global variables using `globalTemplateVars`

`globalTemplateVars` is an object that can be passed to the configuration of the Email Plugin with static object variables.
You can also pass an async function that will be called with the `RequestContext` and the `Injector` so you can access services
and e.g. load channel specific theme configurations.

*Example*

```ts
EmailPlugin.init({
   globalTemplateVars: {
     primaryColor: '#FF0000',
     fromAddress: 'no-reply@ourstore.com'
   }
})
```
or
```ts
EmailPlugin.init({
   globalTemplateVars: async (ctx, injector) => {
     const myAsyncService = injector.get(MyAsyncService);
     const asyncValue = await myAsyncService.get(ctx);
     const channel = ctx.channel;
     const { primaryColor } = channel.customFields.theme;
     const theme = {
        primaryColor,
        asyncValue,
     };
     return theme;
   }
})
```

### Handlebars helpers

The following helper functions are available for use in email templates:

* `formatMoney`: Formats an amount of money (which are always stored as integers in Vendure) as a decimal, e.g. `123` => `1.23`
* `formatDate`: Formats a Date value with the [dateformat](https://www.npmjs.com/package/dateformat) package.

## Extending the default email handler

The `defaultEmailHandlers` array defines the default handler such as for handling new account registration, order confirmation, password reset
etc. These defaults can be extended by adding custom templates for languages other than the default, or even completely new types of emails
which respond to any of the available [VendureEvents](/reference/typescript-api/events/).

A good way to learn how to create your own email handler is to take a look at the
[source code of the default handler](https://github.com/vendure-ecommerce/vendure/blob/master/packages/email-plugin/src/handler/default-email-handlers.ts).
New handler are defined in exactly the same way.

It is also possible to modify the default handler:

```ts
// Rather than importing `defaultEmailHandlers`, you can
// import the handler individually
import {
  orderConfirmationHandler,
  emailVerificationHandler,
  passwordResetHandler,
  emailAddressChangeHandler,
} from '@vendure/email-plugin';
import { CustomerService } from '@vendure/core';

// This allows you to then customize each handler to your needs.
// For example, let's set a new subject line to the order confirmation:
const myOrderConfirmationHandler = orderConfirmationHandler
  .setSubject(`We received your order!`);

// Another example: loading additional data and setting new
// template variables.
const myPasswordResetHandler = passwordResetHandler
  .loadData(async ({ event, injector }) => {
    const customerService = injector.get(CustomerService);
    const customer = await customerService.findOneByUserId(event.ctx, event.user.id);
    return { customer };
  })
  .setTemplateVars(event => ({
    passwordResetToken: event.user.getNativeAuthenticationMethod().passwordResetToken,
    customer: event.data.customer,
  }));

// Then you pass the handler to the EmailPlugin init method
// individually
EmailPlugin.init({
  handler: [
    myOrderConfirmationHandler,
    myPasswordResetHandler,
    emailVerificationHandler,
    emailAddressChangeHandler,
  ],
  // ...
}),
```

For all available methods of extending a handler, see the <a href='/reference/core-plugins/email-plugin/email-event-handler#emaileventhandler'>EmailEventHandler</a> documentation.

## Dynamic SMTP settings

Instead of defining static transport settings, you can also provide a function that dynamically resolves
channel aware transport settings.

*Example*

```ts
import { defaultEmailHandlers, EmailPlugin, FileBasedTemplateLoader } from '@vendure/email-plugin';
import { MyTransportService } from './transport.services.ts';
const config: VendureConfig = {
  plugins: [
    EmailPlugin.init({
      handler: defaultEmailHandlers,
      templateLoader: new FileBasedTemplateLoader(path.join(__dirname, '../static/email/templates')),
      transport: (injector, ctx) => {
        if (ctx) {
          return injector.get(MyTransportService).getSettings(ctx);
        } else {
          return {
            type: 'smtp',
            host: 'smtp.example.com',
            // ... etc.
          }
        }
      }
    }),
  ],
};
```

## Dev mode

For development, the `transport` option can be replaced by `devMode: true`. Doing so configures Vendure to use the
file transport (See <a href='/reference/core-plugins/email-plugin/transport-options#filetransportoptions'>FileTransportOptions</a>) and outputs emails as rendered HTML files in the directory specified by the
`outputPath` property.

```ts
EmailPlugin.init({
  devMode: true,
  route: 'mailbox',
  handler: defaultEmailHandlers,
  templateLoader: new FileBasedTemplateLoader(path.join(__dirname, '../static/email/templates')),
  outputPath: path.join(__dirname, 'test-emails'),
})
```

### Dev mailbox

In dev mode, a webmail-like interface available at the `/mailbox` path, e.g.
http://localhost:3000/mailbox. This is a simple way to view the output of all emails generated by the EmailPlugin while in dev mode.

## Troubleshooting SMTP Connections

If you are having trouble sending email over and SMTP connection, set the `logging` and `debug` options to `true`. This will
send detailed information from the SMTP transporter to the configured logger (defaults to console). For maximum detail combine
this with a detail log level in the configured VendureLogger:

```ts
const config: VendureConfig = {
  logger: new DefaultLogger({ level: LogLevel.Debug })
  // ...
  plugins: [
    EmailPlugin.init({
      // ...
      transport: {
        type: 'smtp',
        host: 'smtp.example.com',
        port: 587,
        auth: {
          user: 'username',
          pass: 'password',
        },
        logging: true,
        debug: true,
      },
    }),
  ],
};
```

```ts title="Signature"
class EmailPlugin implements OnApplicationBootstrap, OnApplicationShutdown, NestModule {
    init(options: EmailPluginOptions | EmailPluginDevModeOptions) => Type<EmailPlugin>;
    onApplicationShutdown() => ;
    configure(consumer: MiddlewareConsumer) => ;
}
```
* Implements: <code>OnApplicationBootstrap</code>, <code>OnApplicationShutdown</code>, <code>NestModule</code>



<div className="members-wrapper">

### init

<MemberInfo kind="method" type={`(options: <a href='/reference/core-plugins/email-plugin/email-plugin-options#emailpluginoptions'>EmailPluginOptions</a> | <a href='/reference/core-plugins/email-plugin/email-plugin-options#emailplugindevmodeoptions'>EmailPluginDevModeOptions</a>) => Type&#60;<a href='/reference/core-plugins/email-plugin/#emailplugin'>EmailPlugin</a>&#62;`}   />


### onApplicationShutdown

<MemberInfo kind="method" type={`() => `}   />


### configure

<MemberInfo kind="method" type={`(consumer: MiddlewareConsumer) => `}   />




</div>


---

---
title: "TemplateLoader"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## TemplateLoader

<GenerationInfo sourceFile="packages/email-plugin/src/template-loader/template-loader.ts" sourceLine="32" packageName="@vendure/email-plugin" />

Loads email templates based on the given request context, type and template name
and return the template as a string.

*Example*

```ts
import { EmailPlugin, TemplateLoader } from '@vendure/email-plugin';

class MyTemplateLoader implements TemplateLoader {
     loadTemplate(injector, ctx, { type, templateName }){
         return myCustomTemplateFunction(ctx);
     }
}

// In vendure-config.ts:
...
EmailPlugin.init({
    templateLoader: new MyTemplateLoader()
    ...
})
```

```ts title="Signature"
interface TemplateLoader {
    loadTemplate(injector: Injector, ctx: RequestContext, input: LoadTemplateInput): Promise<string>;
    loadPartials?(): Promise<Partial[]>;
}
```

<div className="members-wrapper">

### loadTemplate

<MemberInfo kind="method" type={`(injector: <a href='/reference/typescript-api/common/injector#injector'>Injector</a>, ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: <a href='/reference/core-plugins/email-plugin/email-plugin-types#loadtemplateinput'>LoadTemplateInput</a>) => Promise&#60;string&#62;`}   />

Load template and return it's content as a string
### loadPartials

<MemberInfo kind="method" type={`() => Promise&#60;Partial[]&#62;`}   />

Load partials and return their contents.
This method is only called during initialization, i.e. during server startup.


</div>


## FileBasedTemplateLoader

<GenerationInfo sourceFile="packages/email-plugin/src/template-loader/file-based-template-loader.ts" sourceLine="17" packageName="@vendure/email-plugin" />

Loads email templates from the local file system. This is the default
loader used by the EmailPlugin.

```ts title="Signature"
class FileBasedTemplateLoader implements TemplateLoader {
    constructor(templatePath: string)
    loadTemplate(_injector: Injector, _ctx: RequestContext, { type, templateName }: LoadTemplateInput) => Promise<string>;
    loadPartials() => Promise<Partial[]>;
}
```
* Implements: <code><a href='/reference/core-plugins/email-plugin/template-loader#templateloader'>TemplateLoader</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(templatePath: string) => FileBasedTemplateLoader`}   />


### loadTemplate

<MemberInfo kind="method" type={`(_injector: <a href='/reference/typescript-api/common/injector#injector'>Injector</a>, _ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, { type, templateName }: <a href='/reference/core-plugins/email-plugin/email-plugin-types#loadtemplateinput'>LoadTemplateInput</a>) => Promise&#60;string&#62;`}   />


### loadPartials

<MemberInfo kind="method" type={`() => Promise&#60;Partial[]&#62;`}   />




</div>


---

---
title: "Transport Options"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## EmailTransportOptions

<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="171" packageName="@vendure/email-plugin" />

A union of all the possible transport options for sending emails.

```ts title="Signature"
type EmailTransportOptions = | SMTPTransportOptions
    | SendmailTransportOptions
    | FileTransportOptions
    | NoopTransportOptions
    | SESTransportOptions
    | TestingTransportOptions
```


## SMTPTransportOptions

<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="186" packageName="@vendure/email-plugin" />

The SMTP transport options of [Nodemailer](https://nodemailer.com/smtp/)

```ts title="Signature"
interface SMTPTransportOptions extends SMTPTransport.Options {
    type: 'smtp';
    logging?: boolean;
}
```
* Extends: <code>SMTPTransport.Options</code>



<div className="members-wrapper">

### type

<MemberInfo kind="property" type={`'smtp'`}   />


### logging

<MemberInfo kind="property" type={`boolean`} default={`false`}   />

If true, uses the configured <a href='/reference/typescript-api/logger/vendure-logger#vendurelogger'>VendureLogger</a> to log messages from Nodemailer as it interacts with
the SMTP server.


</div>


## SESTransportOptions

<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="235" packageName="@vendure/email-plugin" />

The SES transport options of [Nodemailer](https://nodemailer.com/transports/ses//)

See [Nodemailers's SES docs](https://nodemailer.com/transports/ses/) for more details

*Example*

```ts
 import { SES, SendRawEmailCommand } from '@aws-sdk/client-ses'

 const ses = new SES({
    apiVersion: '2010-12-01',
    region: 'eu-central-1',
    credentials: {
        accessKeyId: process.env.SES_ACCESS_KEY || '',
        secretAccessKey: process.env.SES_SECRET_KEY || '',
    },
 })

 const config: VendureConfig = {
  // Add an instance of the plugin to the plugins array
  plugins: [
    EmailPlugin.init({
      handler: defaultEmailHandlers,
      templateLoader: new FileBasedTemplateLoader(path.join(__dirname, '../static/email/templates')),
      transport: {
        type: 'ses',
        SES: { ses, aws: { SendRawEmailCommand } },
        sendingRate: 10, // optional messages per second sending rate
      },
    }),
  ],
};
 ```

```ts title="Signature"
interface SESTransportOptions extends SESTransport.Options {
    type: 'ses';
}
```
* Extends: <code>SESTransport.Options</code>



<div className="members-wrapper">

### type

<MemberInfo kind="property" type={`'ses'`}   />




</div>


## SendmailTransportOptions

<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="246" packageName="@vendure/email-plugin" />

Uses the local Sendmail program to send the email.

```ts title="Signature"
interface SendmailTransportOptions {
    type: 'sendmail';
    path?: string;
    newline?: string;
}
```

<div className="members-wrapper">

### type

<MemberInfo kind="property" type={`'sendmail'`}   />


### path

<MemberInfo kind="property" type={`string`}   />


### newline

<MemberInfo kind="property" type={`string`}   />




</div>


## FileTransportOptions

<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="261" packageName="@vendure/email-plugin" />

Outputs the email as an HTML file for development purposes.

```ts title="Signature"
interface FileTransportOptions {
    type: 'file';
    outputPath: string;
    raw?: boolean;
}
```

<div className="members-wrapper">

### type

<MemberInfo kind="property" type={`'file'`}   />


### outputPath

<MemberInfo kind="property" type={`string`}   />


### raw

<MemberInfo kind="property" type={`boolean`}   />




</div>


## NoopTransportOptions

<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="277" packageName="@vendure/email-plugin" />

Does nothing with the generated email. Intended for use in testing where we don't care about the email transport,
or when using a custom <a href='/reference/core-plugins/email-plugin/email-sender#emailsender'>EmailSender</a> which does not require transport options.

```ts title="Signature"
interface NoopTransportOptions {
    type: 'none';
}
```

<div className="members-wrapper">

### type

<MemberInfo kind="property" type={`'none'`}   />




</div>


## TestingTransportOptions

<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="306" packageName="@vendure/email-plugin" />

Forwards the raw GeneratedEmailContext object to a provided callback, for use in testing.

```ts title="Signature"
interface TestingTransportOptions {
    type: 'testing';
    onSend: (details: EmailDetails) => void;
}
```

<div className="members-wrapper">

### type

<MemberInfo kind="property" type={`'testing'`}   />


### onSend

<MemberInfo kind="property" type={`(details: <a href='/reference/core-plugins/email-plugin/email-plugin-types#emaildetails'>EmailDetails</a>) =&#62; void`}   />

Callback to be invoked when an email would be sent.


</div>


---

---
title: "GraphiqlPlugin"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## GraphiqlPlugin

<GenerationInfo sourceFile="packages/graphiql-plugin/src/plugin.ts" sourceLine="64" packageName="@vendure/graphiql-plugin" />

This plugin provides a GraphiQL UI for exploring and testing the Vendure GraphQL APIs.

It adds routes `/graphiql/admin` and `/graphiql/shop` which serve the GraphiQL interface
for the respective APIs.

## Installation

```ts
import { GraphiqlPlugin } from '@vendure/graphiql-plugin';

const config: VendureConfig = {
  // Add an instance of the plugin to the plugins array
  plugins: [
    GraphiqlPlugin.init({
      route: 'graphiql', // Optional, defaults to 'graphiql'
    }),
  ],
};
```

## Custom API paths

By default, the plugin automatically reads the Admin API and Shop API paths from your Vendure configuration.

If you need to override these paths, you can specify them explicitly:

```typescript
GraphiQLPlugin.init({
    route: 'my-custom-route', // defaults to `graphiql`
});
```

## Query parameters

You can add the following query parameters to the GraphiQL URL:

- `?query=...` - Pre-populate the query editor with a GraphQL query.
- `?embeddedMode=true` - This renders the editor in embedded mode, which hides the header and
   the API switcher. This is useful for embedding GraphiQL in other applications such as documentation.
   In this mode, the editor also does not persist changes across reloads.

```ts title="Signature"
class GraphiqlPlugin implements NestModule {
    static options: Required<GraphiqlPluginOptions>;
    constructor(processContext: ProcessContext, configService: ConfigService, graphiQLService: GraphiQLService)
    init(options: GraphiqlPluginOptions = {}) => Type<GraphiqlPlugin>;
    configure(consumer: MiddlewareConsumer) => ;
}
```
* Implements: <code>NestModule</code>



<div className="members-wrapper">

### options

<MemberInfo kind="property" type={`Required&#60;GraphiqlPluginOptions&#62;`}   />


### constructor

<MemberInfo kind="method" type={`(processContext: <a href='/reference/typescript-api/common/process-context#processcontext'>ProcessContext</a>, configService: ConfigService, graphiQLService: GraphiQLService) => GraphiqlPlugin`}   />


### init

<MemberInfo kind="method" type={`(options: GraphiqlPluginOptions = {}) => Type&#60;<a href='/reference/core-plugins/graphiql-plugin/#graphiqlplugin'>GraphiqlPlugin</a>&#62;`}   />


### configure

<MemberInfo kind="method" type={`(consumer: MiddlewareConsumer) => `}   />




</div>


---

---
title: "DefaultVendureComplexityEstimator"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## defaultVendureComplexityEstimator

<GenerationInfo sourceFile="packages/harden-plugin/src/middleware/query-complexity-plugin.ts" sourceLine="98" packageName="@vendure/harden-plugin" />

A complexity estimator which takes into account List and PaginatedList types and can
be further configured by providing a customComplexityFactors object.

When selecting PaginatedList types, the "take" argument is used to estimate a complexity
factor. If the "take" argument is omitted, a default factor of 1000 is applied.

```ts title="Signature"
function defaultVendureComplexityEstimator(customComplexityFactors: { [path: string]: number }, logFieldScores: boolean): void
```
Parameters

### customComplexityFactors

<MemberInfo kind="parameter" type={`{ [path: string]: number }`} />

### logFieldScores

<MemberInfo kind="parameter" type={`boolean`} />



---

---
title: "HardenPluginOptions"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## HardenPluginOptions

<GenerationInfo sourceFile="packages/harden-plugin/src/types.ts" sourceLine="10" packageName="@vendure/harden-plugin" />

Options that can be passed to the `.init()` static method of the HardenPlugin.

```ts title="Signature"
interface HardenPluginOptions {
    maxQueryComplexity?: number;
    queryComplexityEstimators?: ComplexityEstimator[];
    logComplexityScore?: boolean;
    customComplexityFactors?: {
        [path: string]: number;
    };
    hideFieldSuggestions?: boolean;
    apiMode?: 'dev' | 'prod';
    skip?: (context: GraphQLRequestContext<any>) => Promise<boolean> | boolean;
}
```

<div className="members-wrapper">

### maxQueryComplexity

<MemberInfo kind="property" type={`number`} default={`1000`}   />

Defines the maximum permitted complexity score of a query. The complexity score is based
on the number of fields being selected as well as other factors like whether there are nested
lists.

A query which exceeds the maximum score will result in an error.
### queryComplexityEstimators

<MemberInfo kind="property" type={`ComplexityEstimator[]`}   />

An array of custom estimator functions for calculating the complexity of a query. By default,
the plugin will use the <a href='/reference/core-plugins/harden-plugin/default-vendure-complexity-estimator#defaultvendurecomplexityestimator'>defaultVendureComplexityEstimator</a> which is specifically
tuned to accurately estimate Vendure queries.
### logComplexityScore

<MemberInfo kind="property" type={`boolean`} default={`false`}   />

When set to `true`, the complexity score of each query will be logged at the Verbose
log level, and a breakdown of the calculation for each field will be logged at the Debug level.

This is very useful for tuning your complexity scores.
### customComplexityFactors

<MemberInfo kind="property" type={`{         [path: string]: number;     }`}   />

This object allows you to tune the complexity weight of specific fields. For example,
if you have a custom `stockLocations` field defined on the `ProductVariant` type, and
you know that it is a particularly expensive operation to execute, you can increase
its complexity like this:

*Example*

```ts
HardenPlugin.init({
  maxQueryComplexity: 650,
  customComplexityFactors: {
    'ProductVariant.stockLocations': 10
  }
}),
```
### hideFieldSuggestions

<MemberInfo kind="property" type={`boolean`} default={`true`}   />

Graphql-js will make suggestions about the names of fields if an invalid field name is provided.
This would allow an attacker to find out the available fields by brute force even if introspection
is disabled.

Setting this option to `true` will prevent these suggestion error messages from being returned,
instead replacing the message with a generic "Invalid request" message.
### apiMode

<MemberInfo kind="property" type={`'dev' | 'prod'`} default={`'prod'`}   />

When set to `'prod'`, the plugin will disable dev-mode features of the GraphQL APIs:

- introspection
- GraphQL playground
### skip

<MemberInfo kind="property" type={`(context: GraphQLRequestContext&#60;any&#62;) =&#62; Promise&#60;boolean&#62; | boolean`}   />

Allows you to skip the complexity check for certain requests.

*Example*

```ts
HardenPlugin.init({
  skip: (context) => context.request.http.headers['x-storefront-ssr-auth'] === 'some-secret-token'
}),
```


</div>


---

---
title: "HardenPlugin"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## HardenPlugin

<GenerationInfo sourceFile="packages/harden-plugin/src/harden.plugin.ts" sourceLine="146" packageName="@vendure/harden-plugin" />

The HardenPlugin hardens the Shop and Admin GraphQL APIs against attacks and abuse.

- It analyzes the complexity on incoming graphql queries and rejects queries that are too complex and
  could be used to overload the resources of the server.
- It disables dev-mode API features such as introspection and the GraphQL playground app.
- It removes field name suggestions to prevent trial-and-error schema sniffing.

It is a recommended plugin for all production configurations.

## Installation

`yarn add @vendure/harden-plugin`

or

`npm install @vendure/harden-plugin`

Then add the `HardenPlugin`, calling the `.init()` method with <a href='/reference/core-plugins/harden-plugin/harden-plugin-options#hardenpluginoptions'>HardenPluginOptions</a>:

*Example*

```ts
import { HardenPlugin } from '@vendure/harden-plugin';

const config: VendureConfig = {
  // Add an instance of the plugin to the plugins array
  plugins: [
     HardenPlugin.init({
       maxQueryComplexity: 650,
       apiMode: process.env.APP_ENV === 'dev' ? 'dev' : 'prod',
     }),
  ],
};
```

## Setting the max query complexity

The `maxQueryComplexity` option determines how complex a query can be. The complexity of a query relates to how many, and how
deeply-nested are the fields being selected, and is intended to roughly correspond to the amount of server resources that would
be required to resolve that query.

The goal of this setting is to prevent attacks in which a malicious actor crafts a very complex query in order to overwhelm your
server resources. Here's an example of a request which would likely overwhelm a Vendure server:

```GraphQL
query EvilQuery {
  products {
    items {
      collections {
        productVariants {
          items {
            product {
              collections {
                productVariants {
                  items {
                    product {
                      variants {
                        name
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```

This evil query has a complexity score of 2,443,203 - much greater than the default of 1,000!

The complexity score is calculated by the [graphql-query-complexity library](https://www.npmjs.com/package/graphql-query-complexity),
and by default uses the <a href='/reference/core-plugins/harden-plugin/default-vendure-complexity-estimator#defaultvendurecomplexityestimator'>defaultVendureComplexityEstimator</a>, which is tuned specifically to the Vendure Shop API.

:::caution
Note: By default, if the "take" argument is omitted from a list query (e.g. the `products` or `collections` query), a default factor of 1000 is applied.
:::

The optimal max complexity score will vary depending on:

- The requirements of your storefront and other clients using the Shop API
- The resources available to your server

You should aim to set the maximum as low as possible while still being able to service all the requests required.
This will take some manual tuning.
While tuning the max, you can turn on the `logComplexityScore` to get a detailed breakdown of the complexity of each query, as well as how
that total score is derived from its child fields:

*Example*

```ts
import { HardenPlugin } from '@vendure/harden-plugin';

const config: VendureConfig = {
  // A detailed summary is logged at the "debug" level
  logger: new DefaultLogger({ level: LogLevel.Debug }),
  plugins: [
     HardenPlugin.init({
       maxQueryComplexity: 650,
       logComplexityScore: true,
     }),
  ],
};
```

With logging configured as above, the following query:

```GraphQL
query ProductList {
  products(options: { take: 5 }) {
    items {
      id
      name
      featuredAsset {
        preview
      }
    }
  }
}
```
will log the following breakdown:

```sh
debug 16/12/22, 14:12 - [HardenPlugin] Calculating complexity of [ProductList]
debug 16/12/22, 14:12 - [HardenPlugin] Product.id: ID!     childComplexity: 0, score: 1
debug 16/12/22, 14:12 - [HardenPlugin] Product.name: String!       childComplexity: 0, score: 1
debug 16/12/22, 14:12 - [HardenPlugin] Asset.preview: String!      childComplexity: 0, score: 1
debug 16/12/22, 14:12 - [HardenPlugin] Product.featuredAsset: Asset        childComplexity: 1, score: 2
debug 16/12/22, 14:12 - [HardenPlugin] ProductList.items: [Product!]!      childComplexity: 4, score: 20
debug 16/12/22, 14:12 - [HardenPlugin] Query.products: ProductList!        childComplexity: 20, score: 35
verbose 16/12/22, 14:12 - [HardenPlugin] Query complexity [ProductList]: 35
```

```ts title="Signature"
class HardenPlugin {
    static options: HardenPluginOptions;
    init(options: HardenPluginOptions) => ;
}
```

<div className="members-wrapper">

### options

<MemberInfo kind="property" type={`<a href='/reference/core-plugins/harden-plugin/harden-plugin-options#hardenpluginoptions'>HardenPluginOptions</a>`}   />


### init

<MemberInfo kind="method" type={`(options: <a href='/reference/core-plugins/harden-plugin/harden-plugin-options#hardenpluginoptions'>HardenPluginOptions</a>) => `}   />




</div>


---

---
title: "Core Plugins"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "BullMQJobQueuePlugin"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## BullMQJobQueuePlugin

<GenerationInfo sourceFile="packages/job-queue-plugin/src/bullmq/plugin.ts" sourceLine="192" packageName="@vendure/job-queue-plugin" />

This plugin is a drop-in replacement of the DefaultJobQueuePlugin, which implements a push-based
job queue strategy built on top of the popular [BullMQ](https://github.com/taskforcesh/bullmq) library.

## Advantages over the DefaultJobQueuePlugin

The advantage of this approach is that jobs are stored in Redis rather than in the database. For more complex
applications with many job queues and/or multiple worker instances, this can massively reduce the load on the
DB server. The reason for this is that the DefaultJobQueuePlugin uses polling to check for new jobs. By default
it will poll every 200ms. A typical Vendure instance uses at least 3 queues (handling emails, collections, search index),
so even with a single worker instance this results in 15 queries per second to the DB constantly. Adding more
custom queues and multiple worker instances can easily result in 50 or 100 queries per second. At this point
performance may be impacted.

Using this plugin, no polling is needed, as BullMQ will _push_ jobs to the worker(s) as and when they are added
to the queue. This results in significantly more scalable performance characteristics, as well as lower latency
in processing jobs.

## Installation

Note: To use this plugin, you need to manually install the `bullmq` package:

```shell
npm install bullmq@^5.4.2
```

**Note:** The v1.x version of this plugin is designed to work with bullmq v1.x, etc.

*Example*

```ts
import { BullMQJobQueuePlugin } from '@vendure/job-queue-plugin/package/bullmq';

const config: VendureConfig = {
  // Add an instance of the plugin to the plugins array
  plugins: [
    // DefaultJobQueuePlugin should be removed from the plugins array
    BullMQJobQueuePlugin.init({
      connection: {
        port: 6379
      }
    }),
  ],
};
```

### Running Redis locally

To develop with this plugin, you'll need an instance of Redis to connect to. Here's a docker-compose config
that will set up [Redis](https://redis.io/) as well as [Redis Commander](https://github.com/joeferner/redis-commander),
which is a web-based UI for interacting with Redis:

```YAML
version: "3"
services:
  redis:
    image: bitnami/redis:6.2
    hostname: redis
    container_name: redis
    environment:
      - ALLOW_EMPTY_PASSWORD=yes
    ports:
      - "6379:6379"
  redis-commander:
    container_name: redis-commander
    hostname: redis-commander
    image: rediscommander/redis-commander:latest
    environment:
      - REDIS_HOSTS=local:redis:6379
    ports:
      - "8085:8081"
```

## Concurrency

The default concurrency of a single worker is 3, i.e. up to 3 jobs will be processed at the same time.
You can change the concurrency in the `workerOptions` passed to the `init()` method:

*Example*

```ts
const config: VendureConfig = {
  plugins: [
    BullMQJobQueuePlugin.init({
      workerOptions: {
        concurrency: 10,
      },
    }),
  ],
};
```

## Removing old jobs

By default, BullMQ will keep completed jobs in the `completed` set and failed jobs in the `failed` set. Over time,
these sets can grow very large. Since Vendure v2.1, the default behaviour is to remove jobs from these sets after
30 days or after a maximum of 5,000 completed or failed jobs.

This can be configured using the `removeOnComplete` and `removeOnFail` options:

*Example*

```ts
const config: VendureConfig = {
  plugins: [
    BullMQJobQueuePlugin.init({
      workerOptions: {
        removeOnComplete: {
          count: 500,
        },
        removeOnFail: {
          age: 60 * 60 * 24 * 7, // 7 days
          count: 1000,
        },
      }
    }),
  ],
};
```

The `count` option specifies the maximum number of jobs to keep in the set, while the `age` option specifies the
maximum age of a job in seconds. If both options are specified, then the jobs kept will be the ones that satisfy
both properties.

## Job Priority
Some jobs are more important than others. For example, sending out a timely email after a customer places an order
is probably more important than a routine data import task. Sometimes you can get the situation where lower-priority
jobs are blocking higher-priority jobs.

Let's say you have a data import job that runs periodically and takes a long time to complete. If you have a high-priority
job that needs to be processed quickly, it could be stuck behind the data import job in the queue. A customer might
not get their confirmation email for 30 minutes while that data import job is processed!

To solve this problem, you can set the `priority` option on a job. Jobs with a higher priority will be processed before
jobs with a lower priority. By default, all jobs have a priority of 0 (which is the highest).

Learn more about how priority works in BullMQ in their [documentation](https://docs.bullmq.io/guide/jobs/prioritized).

You can set the priority by using the `setJobOptions` option (introduced in Vendure v3.2.0):

*Example*

```ts
const config: VendureConfig = {
  plugins: [
    BullMQJobQueuePlugin.init({
      setJobOptions: (queueName, job) => {
        let priority = 10;
        switch (queueName) {
          case 'super-critical-task':
            priority = 0;
            break;
          case 'send-email':
            priority = 5;
            break;
          default:
            priority = 10;
        }
        return { priority };
      }
    }),
  ],
};
```

## Setting Redis Prefix

By default, the underlying BullMQ library will use the default Redis key prefix of `bull`. This can be changed by setting the `prefix` option
in the `queueOptions` and `workerOptions` objects:

```ts
BullMQJobQueuePlugin.init({
  workerOptions: {
    prefix: 'my-prefix'
  },
  queueOptions: {
    prefix: 'my-prefix'
  }
}),
```

```ts title="Signature"
class BullMQJobQueuePlugin {
    static options: BullMQPluginOptions;
    init(options: BullMQPluginOptions) => ;
}
```

<div className="members-wrapper">

### options

<MemberInfo kind="property" type={`<a href='/reference/core-plugins/job-queue-plugin/bull-mqplugin-options#bullmqpluginoptions'>BullMQPluginOptions</a>`}   />


### init

<MemberInfo kind="method" type={`(options: <a href='/reference/core-plugins/job-queue-plugin/bull-mqplugin-options#bullmqpluginoptions'>BullMQPluginOptions</a>) => `}   />

Configures the plugin.


</div>


---

---
title: "BullMQJobQueueStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## BullMQJobQueueStrategy

<GenerationInfo sourceFile="packages/job-queue-plugin/src/bullmq/bullmq-job-queue-strategy.ts" sourceLine="53" packageName="@vendure/job-queue-plugin" />

This JobQueueStrategy uses [BullMQ](https://docs.bullmq.io/) to implement a push-based job queue
on top of Redis. It should not be used alone, but as part of the <a href='/reference/core-plugins/job-queue-plugin/bull-mqjob-queue-plugin#bullmqjobqueueplugin'>BullMQJobQueuePlugin</a>.

Note: To use this strategy, you need to manually install the `bullmq` package:

```shell
npm install bullmq@^5.4.2
```

```ts title="Signature"
class BullMQJobQueueStrategy implements InspectableJobQueueStrategy {
    init(injector: Injector) => Promise<void>;
    destroy() => ;
    add(job: Job<Data>) => Promise<Job<Data>>;
    cancelJob(jobId: string) => Promise<Job | undefined>;
    findMany(options?: JobListOptions) => Promise<PaginatedList<Job>>;
    findManyById(ids: ID[]) => Promise<Job[]>;
    findOne(id: ID) => Promise<Job | undefined>;
    removeSettledJobs(queueNames?: string[], olderThan?: Date) => Promise<number>;
    start(queueName: string, process: (job: Job<Data>) => Promise<any>) => Promise<void>;
    stop(queueName: string, process: (job: Job<Data>) => Promise<any>) => Promise<void>;
}
```
* Implements: <code>InspectableJobQueueStrategy</code>



<div className="members-wrapper">

### init

<MemberInfo kind="method" type={`(injector: Injector) => Promise&#60;void&#62;`}   />


### destroy

<MemberInfo kind="method" type={`() => `}   />


### add

<MemberInfo kind="method" type={`(job: Job&#60;Data&#62;) => Promise&#60;Job&#60;Data&#62;&#62;`}   />


### cancelJob

<MemberInfo kind="method" type={`(jobId: string) => Promise&#60;Job | undefined&#62;`}   />


### findMany

<MemberInfo kind="method" type={`(options?: JobListOptions) => Promise&#60;PaginatedList&#60;Job&#62;&#62;`}   />


### findManyById

<MemberInfo kind="method" type={`(ids: ID[]) => Promise&#60;Job[]&#62;`}   />


### findOne

<MemberInfo kind="method" type={`(id: ID) => Promise&#60;Job | undefined&#62;`}   />


### removeSettledJobs

<MemberInfo kind="method" type={`(queueNames?: string[], olderThan?: Date) => Promise&#60;number&#62;`}   />


### start

<MemberInfo kind="method" type={`(queueName: string, process: (job: Job&#60;Data&#62;) =&#62; Promise&#60;any&#62;) => Promise&#60;void&#62;`}   />


### stop

<MemberInfo kind="method" type={`(queueName: string, process: (job: Job&#60;Data&#62;) =&#62; Promise&#60;any&#62;) => Promise&#60;void&#62;`}   />




</div>


---

---
title: "BullMQPluginOptions"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## BullMQPluginOptions

<GenerationInfo sourceFile="packages/job-queue-plugin/src/bullmq/types.ts" sourceLine="21" packageName="@vendure/job-queue-plugin" since="1.2.0" />

Configuration options for the <a href='/reference/core-plugins/job-queue-plugin/bull-mqjob-queue-plugin#bullmqjobqueueplugin'>BullMQJobQueuePlugin</a>.

```ts title="Signature"
interface BullMQPluginOptions {
    connection?: ConnectionOptions;
    queueOptions?: Omit<QueueOptions, 'connection'>;
    workerOptions?: Omit<WorkerOptions, 'connection'>;
    setRetries?: (queueName: string, job: Job) => number;
    setBackoff?: (queueName: string, job: Job) => BackoffOptions | undefined;
    setJobOptions?: (queueName: string, job: Job) => BullJobsOptions;
}
```

<div className="members-wrapper">

### connection

<MemberInfo kind="property" type={`ConnectionOptions`}   />

Connection options which will be passed directly to BullMQ when
creating a new Queue, Worker and Scheduler instance.

If omitted, it will attempt to connect to Redis at `127.0.0.1:6379`.
### queueOptions

<MemberInfo kind="property" type={`Omit&#60;QueueOptions, 'connection'&#62;`}   />

Additional options used when instantiating the BullMQ
Queue instance.
See the [BullMQ QueueOptions docs](https://github.com/taskforcesh/bullmq/blob/master/docs/gitbook/api/bullmq.queueoptions.md)
### workerOptions

<MemberInfo kind="property" type={`Omit&#60;WorkerOptions, 'connection'&#62;`}   />

Additional options used when instantiating the BullMQ
Worker instance.
See the [BullMQ WorkerOptions docs](https://github.com/taskforcesh/bullmq/blob/master/docs/gitbook/api/bullmq.workeroptions.md)
### setRetries

<MemberInfo kind="property" type={`(queueName: string, job: Job) =&#62; number`}  since="1.3.0"  />

When a job is added to the JobQueue using `JobQueue.add()`, the calling
code may specify the number of retries in case of failure. This option allows
you to override that number and specify your own number of retries based on
the job being added.

*Example*

```ts
setRetries: (queueName, job) => {
  if (queueName === 'send-email') {
    // Override the default number of retries
    // for the 'send-email' job because we have
    // a very unreliable email service.
    return 10;
  }
  return job.retries;
}
 ```
### setBackoff

<MemberInfo kind="property" type={`(queueName: string, job: Job) =&#62; <a href='/reference/core-plugins/job-queue-plugin/bull-mqplugin-options#backoffoptions'>BackoffOptions</a> | undefined`} default={`'exponential', 1000`}  since="1.3.0"  />

This allows you to specify the backoff settings when a failed job gets retried.
In other words, this determines how much time should pass before attempting to
process the failed job again. If the function returns `undefined`, the default
value of exponential/1000ms will be used.

*Example*

```ts
setBackoff: (queueName, job) => {
  return {
    type: 'exponential', // or 'fixed'
    delay: 10000 // first retry after 10s, second retry after 20s, 40s,...
  };
}
```
### setJobOptions

<MemberInfo kind="property" type={`(queueName: string, job: Job) =&#62; BullJobsOptions`}  since="3.2.0"  />

This allows you to specify additional options for a job when it is added to the queue.
The object returned is the BullMQ [JobsOptions](https://api.docs.bullmq.io/types/v5.JobsOptions.html)
type, which includes control over settings such as `delay`, `attempts`, `priority` and much more.

This function is called every time a job is added to the queue, so you can return different options
based on the job being added.

*Example*

```ts
// Here we want to assign a higher priority to jobs in the 'critical' queue
setJobOptions: (queueName, job) => {
  const priority = queueName === 'critical' ? 1 : 5;
  return { priority };
}
```


</div>


## BackoffOptions

<GenerationInfo sourceFile="packages/job-queue-plugin/src/bullmq/types.ts" sourceLine="122" packageName="@vendure/job-queue-plugin" since="1.3.0" />

Configuration for the backoff function when retrying failed jobs.

```ts title="Signature"
interface BackoffOptions {
    type: 'exponential' | 'fixed';
    delay: number;
}
```

<div className="members-wrapper">

### type

<MemberInfo kind="property" type={`'exponential' | 'fixed'`}   />


### delay

<MemberInfo kind="property" type={`number`}   />




</div>


---

---
title: "Job Queue Plugin"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "PubSubJobQueueStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## PubSubJobQueueStrategy

<GenerationInfo sourceFile="packages/job-queue-plugin/src/pub-sub/pub-sub-job-queue-strategy.ts" sourceLine="29" packageName="@vendure/job-queue-plugin" />

This JobQueueStrategy uses Google Cloud Pub/Sub to implement a job queue for Vendure.
It should not be used alone, but as part of the <a href='/reference/core-plugins/job-queue-plugin/pub-sub-plugin#pubsubplugin'>PubSubPlugin</a>.

Note: To use this strategy, you need to manually install the `@google-cloud/pubsub` package:

```shell
npm install

```ts title="Signature"
class PubSubJobQueueStrategy extends InjectableJobQueueStrategy implements JobQueueStrategy {
    init(injector: Injector) => ;
    destroy() => ;
    add(job: Job<Data>) => Promise<Job<Data>>;
    start(queueName: string, process: (job: Job<Data>) => Promise<any>) => ;
    stop(queueName: string, process: (job: Job<Data>) => Promise<any>) => ;
}
```
* Extends: <code>InjectableJobQueueStrategy</code>


* Implements: <code>JobQueueStrategy</code>



<div className="members-wrapper">

### init

<MemberInfo kind="method" type={`(injector: Injector) => `}   />


### destroy

<MemberInfo kind="method" type={`() => `}   />


### add

<MemberInfo kind="method" type={`(job: Job&#60;Data&#62;) => Promise&#60;Job&#60;Data&#62;&#62;`}   />


### start

<MemberInfo kind="method" type={`(queueName: string, process: (job: Job&#60;Data&#62;) =&#62; Promise&#60;any&#62;) => `}   />


### stop

<MemberInfo kind="method" type={`(queueName: string, process: (job: Job&#60;Data&#62;) =&#62; Promise&#60;any&#62;) => `}   />




</div>


---

---
title: "PubSubPlugin"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## PubSubPlugin

<GenerationInfo sourceFile="packages/job-queue-plugin/src/pub-sub/plugin.ts" sourceLine="22" packageName="@vendure/job-queue-plugin" />

This plugin uses Google Cloud Pub/Sub to implement a job queue strategy for Vendure.

## Installation

Note: To use this plugin, you need to manually install the `@google-cloud/pubsub` package:

```shell
npm install

```ts title="Signature"
class PubSubPlugin {
    init(options: PubSubOptions) => Type<PubSubPlugin>;
}
```

<div className="members-wrapper">

### init

<MemberInfo kind="method" type={`(options: PubSubOptions) => Type&#60;<a href='/reference/core-plugins/job-queue-plugin/pub-sub-plugin#pubsubplugin'>PubSubPlugin</a>&#62;`}   />




</div>


---

---
title: "BraintreePlugin"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## BraintreePlugin

<GenerationInfo sourceFile="packages/payments-plugin/src/braintree/braintree.plugin.ts" sourceLine="241" packageName="@vendure/payments-plugin" />

This plugin enables payments to be processed by [Braintree](https://www.braintreepayments.com/), a popular payment provider.

## Requirements

1. You will need to create a Braintree sandbox account as outlined in https://developers.braintreepayments.com/start/overview.
2. Then install `braintree` and `@types/braintree` from npm. This plugin was written with `v3.x` of the Braintree lib.
    ```shell
    yarn add @vendure/payments-plugin braintree
    yarn add -D @types/braintree
    ```
    or
    ```shell
    npm install @vendure/payments-plugin braintree
    npm install -D @types/braintree
    ```

## Setup

1. Add the plugin to your VendureConfig `plugins` array:
    ```ts
    import { BraintreePlugin } from '@vendure/payments-plugin/package/braintree';
    import { Environment } from 'braintree';

    // ...

    plugins: [
      BraintreePlugin.init({
        environment: Environment.Sandbox,
        // This allows saving customer payment
        // methods with Braintree (see "vaulting"
        // section below for details)
        storeCustomersInBraintree: true,
      }),
    ]
    ```
2. Create a new PaymentMethod in the Admin UI, and select "Braintree payments" as the handler.
2. Fill in the `Merchant ID`, `Public Key` & `Private Key` from your Braintree sandbox account.

## Storefront usage

The plugin is designed to work with the [Braintree drop-in UI](https://developers.braintreepayments.com/guides/drop-in/overview/javascript/v3).
This is a library provided by Braintree which will handle the payment UI for you. You can install it in your storefront project
with:

```shell
yarn add braintree-web-drop-in
# or
npm install braintree-web-drop-in
```

The high-level workflow is:
1. Generate a "client token" on the server by executing the `generateBraintreeClientToken` mutation which is exposed by this plugin.
2. Use this client token to instantiate the Braintree Dropin UI.
3. Listen for the `"paymentMethodRequestable"` event which emitted by the Dropin.
4. Use the Dropin's `requestPaymentMethod()` method to get the required payment metadata.
5. Pass that metadata to the `addPaymentToOrder` mutation. The metadata should be an object of type `{ nonce: string; }`

Here is an example of how your storefront code will look. Note that this example is attempting to
be framework-agnostic, so you'll need to adapt it to fit to your framework of choice.

```ts
// The Braintree Dropin instance
let dropin: import('braintree-web-drop-in').Dropin;

// Used to show/hide a "submit" button, which would be bound to the
// `submitPayment()` method below.
let showSubmitButton = false;

// Used to display a "processing..." spinner
let processing = false;

//
// This method would be invoked when the payment screen is mounted/created.
//
async function renderDropin(order: Order, clientToken: string) {
  // Lazy load braintree dropin because it has a reference
  // to `window` which breaks SSR
  dropin = await import('braintree-web-drop-in').then((module) =>
    module.default.create({
      authorization: clientToken,
      // This assumes a div in your view with the corresponding ID
      container: '#dropin-container',
      card: {
        cardholderName: {
            required: true,
        },
        overrides: {},
      },
      // Additional config is passed here depending on
      // which payment methods you have enabled in your
      // Braintree account.
      paypal: {
        flow: 'checkout',
        amount: order.totalWithTax / 100,
        currency: 'GBP',
      },
    }),
  );

  // If you are using the `storeCustomersInBraintree` option, then the
  // customer might already have a stored payment method selected as
  // soon as the dropin script loads. In this case, show the submit
  // button immediately.
  if (dropin.isPaymentMethodRequestable()) {
    showSubmitButton = true;
  }

  dropin.on('paymentMethodRequestable', (payload) => {
    if (payload.type === 'CreditCard') {
      showSubmitButton = true;
    }
    if (payload.type === 'PayPalAccount') {
      this.submitPayment();
    }
  });

  dropin.on('noPaymentMethodRequestable', () => {
    // Display an error
  });
}

async function generateClientToken() {
  const { generateBraintreeClientToken } = await graphQlClient.query(gql`
    query GenerateBraintreeClientToken {
      generateBraintreeClientToken
    }
  `);
  return generateBraintreeClientToken;
}

async submitPayment() {
  if (!dropin.isPaymentMethodRequestable()) {
    return;
  }
  showSubmitButton = false;
  processing = true;

  const paymentResult = await dropin.requestPaymentMethod();

  const { addPaymentToOrder } = await graphQlClient.query(gql`
    mutation AddPayment($input: PaymentInput!) {
      addPaymentToOrder(input: $input) {
        ... on Order {
          id
          payments {
            id
            amount
            errorMessage
            method
            state
            transactionId
            createdAt
          }
        }
        ... on ErrorResult {
          errorCode
          message
        }
      }
    }`, {
      input: {
        method: 'braintree', // The code of you Braintree PaymentMethod
        metadata: paymentResult,
      },
    },
  );

  switch (addPaymentToOrder?.__typename) {
      case 'Order':
          // Adding payment succeeded!
          break;
      case 'OrderStateTransitionError':
      case 'OrderPaymentStateError':
      case 'PaymentDeclinedError':
      case 'PaymentFailedError':
        // Display an error to the customer
        dropin.clearSelectedPaymentMethod();
  }
}
```

## Storing payment details (vaulting)

Braintree has a [vault feature](https://developer.paypal.com/braintree/articles/control-panel/vault/overview) which allows the secure storage
of customer's payment information. Using the vault allows you to offer a faster checkout for repeat customers without needing to worry about
how to securely store payment details.

To enable this feature, set the `storeCustomersInBraintree` option to `true`.

```ts
BraintreePlugin.init({
  environment: Environment.Sandbox,
  storeCustomersInBraintree: true,
}),
```

Since v1.8, it is possible to override vaulting on a per-payment basis by passing `includeCustomerId: false` to the `generateBraintreeClientToken`
mutation:

```GraphQL
const { generateBraintreeClientToken } = await graphQlClient.query(gql`
  query GenerateBraintreeClientToken($includeCustomerId: Boolean) {
    generateBraintreeClientToken(includeCustomerId: $includeCustomerId)
  }
`, { includeCustomerId: false });
```

as well as in the metadata of the `addPaymentToOrder` mutation:

```ts
const { addPaymentToOrder } = await graphQlClient.query(gql`
  mutation AddPayment($input: PaymentInput!) {
    addPaymentToOrder(input: $input) {
      ...Order
      ...ErrorResult
    }
  }`, {
    input: {
      method: 'braintree',
      metadata: {
        ...paymentResult,
        includeCustomerId: false,
      },
    }
  );
```

```ts title="Signature"
class BraintreePlugin {
    static options: BraintreePluginOptions = {};
    init(options: BraintreePluginOptions) => Type<BraintreePlugin>;
}
```

<div className="members-wrapper">

### options

<MemberInfo kind="property" type={`<a href='/reference/core-plugins/payments-plugin/braintree-plugin#braintreepluginoptions'>BraintreePluginOptions</a>`}   />


### init

<MemberInfo kind="method" type={`(options: <a href='/reference/core-plugins/payments-plugin/braintree-plugin#braintreepluginoptions'>BraintreePluginOptions</a>) => Type&#60;<a href='/reference/core-plugins/payments-plugin/braintree-plugin#braintreeplugin'>BraintreePlugin</a>&#62;`}   />




</div>


## BraintreePluginOptions

<GenerationInfo sourceFile="packages/payments-plugin/src/braintree/types.ts" sourceLine="25" packageName="@vendure/payments-plugin" />

Options for the Braintree plugin.

```ts title="Signature"
interface BraintreePluginOptions {
    environment?: Environment;
    storeCustomersInBraintree?: boolean;
    extractMetadata?: (transaction: Transaction) => PaymentMetadata;
}
```

<div className="members-wrapper">

### environment

<MemberInfo kind="property" type={`Environment`} default={`Environment.Sandbox`}   />

The Braintree environment being targeted, e.g. sandbox or production.
### storeCustomersInBraintree

<MemberInfo kind="property" type={`boolean`} default={`false`}   />

If set to `true`, a [Customer](https://developer.paypal.com/braintree/docs/guides/customers) object
will be created in Braintree, which allows the secure storage ("vaulting") of previously-used payment methods.
This is done by adding a custom field to the Customer entity to store the Braintree customer ID,
so switching this on will require a database migration / synchronization.

Since v1.8, it is possible to override vaulting on a per-payment basis by passing `includeCustomerId: false` to the
`generateBraintreeClientToken` mutation.
### extractMetadata

<MemberInfo kind="property" type={`(transaction: <a href='/reference/typescript-api/request/transaction-decorator#transaction'>Transaction</a>) =&#62; PaymentMetadata`}  since="1.7.0"  />

Allows you to configure exactly what information from the Braintree
[Transaction object](https://developer.paypal.com/braintree/docs/reference/response/transaction#result-object) (which is returned by the
`transaction.sale()` method of the SDK) should be persisted to the resulting Payment entity metadata.

By default, the built-in extraction function will return a metadata object that looks like this:

*Example*

```ts
const metadata = {
  "status": "settling",
  "currencyIsoCode": "GBP",
  "merchantAccountId": "my_account_id",
  "cvvCheck": "Not Applicable",
  "avsPostCodeCheck": "Not Applicable",
  "avsStreetAddressCheck": "Not Applicable",
  "processorAuthorizationCode": null,
  "processorResponseText": "Approved",
  // for Paypal payments
  "paymentMethod": "paypal_account",
  "paypalData": {
    "payerEmail": "michael-buyer@paypalsandbox.com",
    "paymentId": "PAYID-MLCXYNI74301746XK8807043",
    "authorizationId": "3BU93594D85624939",
    "payerStatus": "VERIFIED",
    "sellerProtectionStatus": "ELIGIBLE",
    "transactionFeeAmount": "0.54"
  },
  // for credit card payments
  "paymentMethod": "credit_card",
  "cardData": {
    "cardType": "MasterCard",
    "last4": "5454",
    "expirationDate": "02/2023"
  }
  // publicly-available metadata that will be
  // readable from the Shop API
  "public": {
    "cardData": {
      "cardType": "MasterCard",
      "last4": "5454",
      "expirationDate": "02/2023"
    },
    "paypalData": {
      "authorizationId": "3BU93594D85624939",
    }
  }
}
```


</div>


---

---
title: "Payments Plugin"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "MolliePlugin"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## MolliePlugin

<GenerationInfo sourceFile="packages/payments-plugin/src/mollie/mollie.plugin.ts" sourceLine="195" packageName="@vendure/payments-plugin" />

Plugin to enable payments through the [Mollie platform](https://docs.mollie.com/).
This plugin uses the Order API from Mollie, not the Payments API.

## Requirements

1. You will need to create a Mollie account and get your apiKey in the dashboard.
2. Install the Payments plugin and the Mollie client:

    `yarn add @vendure/payments-plugin @mollie/api-client`

    or

    `npm install @vendure/payments-plugin @mollie/api-client`

## Setup

1. Add the plugin to your VendureConfig `plugins` array:
    ```ts
    import { MolliePlugin } from '@vendure/payments-plugin/package/mollie';

    // ...

    plugins: [
      MolliePlugin.init({ vendureHost: 'https://yourhost.io/' }),
    ]
    ```
2. Create a new PaymentMethod in the Admin UI, and select "Mollie payments" as the handler.
3. Set your Mollie apiKey in the `API Key` field.
4. Set the `Fallback redirectUrl` to the url that the customer should be redirected to after completing the payment.
You can override this url by passing the `redirectUrl` as an argument to the `createMolliePaymentIntent` mutation.

## Storefront usage

In your storefront you add a payment to an order using the `createMolliePaymentIntent` mutation. In this example, our Mollie
PaymentMethod was given the code "mollie-payment-method". The `redirectUrl``is the url that is used to redirect the end-user
back to your storefront after completing the payment.

```GraphQL
mutation CreateMolliePaymentIntent {
  createMolliePaymentIntent(input: {
    redirectUrl: "https://storefront/order/1234XYZ" // Optional, the fallback redirect url set in the admin UI will be used if not provided
    paymentMethodCode: "mollie-payment-method" // Optional, the first method with Mollie as handler will be used if not provided
    molliePaymentMethodCode: "ideal", // Optional argument to skip the method selection in the hosted checkout
    locale: "nl_NL", // Optional, the browser language will be used by Mollie if not provided
    immediateCapture: true, // Optional, default is true, set to false if you expect the order fulfillment to take longer than 24 hours
  }) {
         ... on MolliePaymentIntent {
              url
          }
         ... on MolliePaymentIntentError {
              errorCode
              message
         }
  }
}
```

The response will contain
a redirectUrl, which can be used to redirect your customer to the Mollie
platform.

'molliePaymentMethodCode' is an optional parameter that can be passed to skip Mollie's hosted payment method selection screen
You can get available Mollie payment methods with the following query:

```GraphQL
{
 molliePaymentMethods(input: { paymentMethodCode: "mollie-payment-method" }) {
   id
   code
   description
   minimumAmount {
     value
     currency
   }
   maximumAmount {
     value
     currency
   }
   image {
     size1x
     size2x
     svg
   }
 }
}
```

After completing payment on the Mollie platform,
the user is redirected to the redirect url that was provided in the `createMolliePaymentIntent` mutation, e.g. `https://storefront/order/CH234X5`

## Pay later methods

Mollie supports pay-later methods like 'Klarna Pay Later'. Pay-later methods are captured immediately after payment.

If your order fulfillment time is longer than 24 hours You should pass `immediateCapture=false` to the `createMolliePaymentIntent` mutation.
This will transition your order to 'PaymentAuthorized' after the Mollie hosted checkout.
You need to manually capture the payment after the order is fulfilled, by settling existing payments, either via the admin UI or in custom code.

Make sure to capture a payment within 28 days, after that the payment will be automaticallreleased.
See the [Mollie documentation](https://docs.mollie.com/docs/place-a-hold-for-a-payment#authorization-expiration-window)
for more information.

## ArrangingAdditionalPayment state

In some rare cases, a customer can add items to the active order, while a Mollie checkout is still open,
for example by opening your storefront in another browser tab.
This could result in an order being in `ArrangingAdditionalPayment` status after the customer finished payment.
You should check if there is still an active order with status `ArrangingAdditionalPayment` on your order confirmation page,
and if so, allow your customer to pay for the additional items by creating another Mollie payment.

```ts title="Signature"
class MolliePlugin {
    static options: MolliePluginOptions;
    init(options: MolliePluginOptions) => typeof MolliePlugin;
}
```

<div className="members-wrapper">

### options

<MemberInfo kind="property" type={`<a href='/reference/core-plugins/payments-plugin/mollie-plugin#molliepluginoptions'>MolliePluginOptions</a>`}   />


### init

<MemberInfo kind="method" type={`(options: <a href='/reference/core-plugins/payments-plugin/mollie-plugin#molliepluginoptions'>MolliePluginOptions</a>) => typeof <a href='/reference/core-plugins/payments-plugin/mollie-plugin#mollieplugin'>MolliePlugin</a>`}   />

Initialize the mollie payment plugin


</div>


## MolliePluginOptions

<GenerationInfo sourceFile="packages/payments-plugin/src/mollie/mollie.plugin.ts" sourceLine="28" packageName="@vendure/payments-plugin" />

Configuration options for the Mollie payments plugin.

```ts title="Signature"
interface MolliePluginOptions {
    vendureHost: string;
    enabledPaymentMethodsParams?: (
        injector: Injector,
        ctx: RequestContext,
        order: Order | null,
    ) => AdditionalEnabledPaymentMethodsParams | Promise<AdditionalEnabledPaymentMethodsParams>;
}
```

<div className="members-wrapper">

### vendureHost

<MemberInfo kind="property" type={`string`}   />

The host of your Vendure server, e.g. `'https://my-vendure.io'`.
This is used by Mollie to send webhook events to the Vendure server
### enabledPaymentMethodsParams

<MemberInfo kind="property" type={`(         injector: <a href='/reference/typescript-api/common/injector#injector'>Injector</a>,         ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>,         order: <a href='/reference/typescript-api/entities/order#order'>Order</a> | null,     ) =&#62; AdditionalEnabledPaymentMethodsParams | Promise&#60;AdditionalEnabledPaymentMethodsParams&#62;`}  since="2.2.0"  />

Provide additional parameters to the Mollie enabled payment methods API call. By default,
the plugin will already pass the `resource` parameter.

For example, if you want to provide a `locale` and `billingCountry` for the API call, you can do so like this:

**Note:** The `order` argument is possibly `null`, this could happen when you fetch the available payment methods
before the order is created.

*Example*

```ts
import { VendureConfig } from '@vendure/core';
import { MolliePlugin, getLocale } from '@vendure/payments-plugin/package/mollie';

export const config: VendureConfig = {
  // ...
  plugins: [
    MolliePlugin.init({
      enabledPaymentMethodsParams: (injector, ctx, order) => {
        const locale = order?.billingAddress?.countryCode
            ? getLocale(order.billingAddress.countryCode, ctx.languageCode)
            : undefined;

        return {
          locale,
          billingCountry: order?.billingAddress?.countryCode,
        },
      }
    }),
  ],
};
```


</div>


---

---
title: "StripePlugin"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## StripePlugin

<GenerationInfo sourceFile="packages/payments-plugin/src/stripe/stripe.plugin.ts" sourceLine="160" packageName="@vendure/payments-plugin" />

Plugin to enable payments through [Stripe](https://stripe.com/docs) via the Payment Intents API.

## Requirements

1. You will need to create a Stripe account and get your secret key in the dashboard.
2. Create a webhook endpoint in the Stripe dashboard (Developers -> Webhooks, "Add an endpoint") which listens to the `payment_intent.succeeded`
and `payment_intent.payment_failed` events. The URL should be `https://my-server.com/payments/stripe`, where
`my-server.com` is the host of your Vendure server. *Note:* for local development, you'll need to use
the Stripe CLI to test your webhook locally. See the _local development_ section below.
3. Get the signing secret for the newly created webhook.
4. Install the Payments plugin and the Stripe Node library:

    `yarn add @vendure/payments-plugin stripe`

    or

    `npm install @vendure/payments-plugin stripe`

## Setup

1. Add the plugin to your VendureConfig `plugins` array:
    ```ts
    import { StripePlugin } from '@vendure/payments-plugin/package/stripe';

    // ...

    plugins: [
      StripePlugin.init({
        // This prevents different customers from using the same PaymentIntent
        storeCustomersInStripe: true,
      }),
    ]
    ````
    For all the plugin options, see the <a href='/reference/core-plugins/payments-plugin/stripe-plugin#stripepluginoptions'>StripePluginOptions</a> type.
2. Create a new PaymentMethod in the Admin UI, and select "Stripe payments" as the handler.
3. Set the webhook secret and API key in the PaymentMethod form.

## Storefront usage

The plugin is designed to work with the [Custom payment flow](https://stripe.com/docs/payments/accept-a-payment?platform=web&ui=elements).
In this flow, Stripe provides libraries which handle the payment UI and confirmation for you. You can install it in your storefront project
with:

```shell
yarn add @stripe/stripe-js
# or
npm install @stripe/stripe-js
```

If you are using React, you should also consider installing `@stripe/react-stripe-js`, which is a wrapper around Stripe Elements.

The high-level workflow is:
1. Create a "payment intent" on the server by executing the `createStripePaymentIntent` mutation which is exposed by this plugin.
2. Use the returned client secret to instantiate the Stripe Payment Element:
   ```ts
   import { Elements } from '@stripe/react-stripe-js';
   import { loadStripe, Stripe } from '@stripe/stripe-js';
   import { CheckoutForm } from './CheckoutForm';

   const stripePromise = getStripe('pk_test_....wr83u');

   type StripePaymentsProps = {
     clientSecret: string;
     orderCode: string;
   }

   export function StripePayments({ clientSecret, orderCode }: StripePaymentsProps) {
     const options = {
       // passing the client secret obtained from the server
       clientSecret,
     }
     return (
       <Elements stripe={stripePromise} options={options}>
         <CheckoutForm orderCode={orderCode} />
       </Elements>
     );
   }
   ```
   ```ts
   // CheckoutForm.tsx
   import { useStripe, useElements, PaymentElement } from '@stripe/react-stripe-js';
   import { FormEvent } from 'react';

   export const CheckoutForm = ({ orderCode }: { orderCode: string }) => {
     const stripe = useStripe();
     const elements = useElements();

     const handleSubmit = async (event: FormEvent) => {
       // We don't want to let default form submission happen here,
       // which would refresh the page.
       event.preventDefault();

       if (!stripe || !elements) {
         // Stripe.js has not yet loaded.
         // Make sure to disable form submission until Stripe.js has loaded.
         return;
       }

       const result = await stripe.confirmPayment({
         //`Elements` instance that was used to create the Payment Element
         elements,
         confirmParams: {
           return_url: location.origin + `/checkout/confirmation/${orderCode}`,
         },
       });

       if (result.error) {
         // Show error to your customer (for example, payment details incomplete)
         console.log(result.error.message);
       } else {
         // Your customer will be redirected to your `return_url`. For some payment
         // methods like iDEAL, your customer will be redirected to an intermediate
         // site first to authorize the payment, then redirected to the `return_url`.
       }
     };

     return (
       <form onSubmit={handleSubmit}>
         <PaymentElement />
         <button disabled={!stripe}>Submit</button>
       </form>
     );
   };
   ```
3. Once the form is submitted and Stripe processes the payment, the webhook takes care of updating the order without additional action
in the storefront. As in the code above, the customer will be redirected to `/checkout/confirmation/${orderCode}`.

:::info
A full working storefront example of the Stripe integration can be found in the
[Remix Starter repo](https://github.com/vendure-ecommerce/storefront-remix-starter/tree/master/app/components/checkout/stripe)
:::

## Local development

1. Download & install the Stripe CLI: https://stripe.com/docs/stripe-cli
2. From your Stripe dashboard, go to Developers -> Webhooks and click "Add an endpoint" and follow the instructions
under "Test in a local environment".
3. The Stripe CLI command will look like
   ```shell
   stripe listen --forward-to localhost:3000/payments/stripe
   ```
4. The Stripe CLI will create a webhook signing secret you can then use in your config of the StripePlugin.

```ts title="Signature"
class StripePlugin {
    static options: StripePluginOptions;
    init(options: StripePluginOptions) => Type<StripePlugin>;
}
```

<div className="members-wrapper">

### options

<MemberInfo kind="property" type={`<a href='/reference/core-plugins/payments-plugin/stripe-plugin#stripepluginoptions'>StripePluginOptions</a>`}   />


### init

<MemberInfo kind="method" type={`(options: <a href='/reference/core-plugins/payments-plugin/stripe-plugin#stripepluginoptions'>StripePluginOptions</a>) => Type&#60;<a href='/reference/core-plugins/payments-plugin/stripe-plugin#stripeplugin'>StripePlugin</a>&#62;`}   />

Initialize the Stripe payment plugin


</div>


## StripePluginOptions

<GenerationInfo sourceFile="packages/payments-plugin/src/stripe/types.ts" sourceLine="29" packageName="@vendure/payments-plugin" />

Configuration options for the Stripe payments plugin.

```ts title="Signature"
interface StripePluginOptions {
    storeCustomersInStripe?: boolean;
    metadata?: (
        injector: Injector,
        ctx: RequestContext,
        order: Order,
    ) => Stripe.MetadataParam | Promise<Stripe.MetadataParam>;
    paymentIntentCreateParams?: (
        injector: Injector,
        ctx: RequestContext,
        order: Order,
    ) => AdditionalPaymentIntentCreateParams | Promise<AdditionalPaymentIntentCreateParams>;
    requestOptions?: (
        injector: Injector,
        ctx: RequestContext,
        order: Order,
    ) => AdditionalRequestOptions | Promise<AdditionalRequestOptions>;
    customerCreateParams?: (
        injector: Injector,
        ctx: RequestContext,
        order: Order,
    ) => AdditionalCustomerCreateParams | Promise<AdditionalCustomerCreateParams>;
    skipPaymentIntentsWithoutExpectedMetadata?: boolean;
}
```

<div className="members-wrapper">

### storeCustomersInStripe

<MemberInfo kind="property" type={`boolean`} default={`false`}   />

If set to `true`, a [Customer](https://stripe.com/docs/api/customers) object will be created in Stripe - if
it doesn't already exist - for authenticated users, which prevents payment methods attached to other Customers
to be used with the same PaymentIntent. This is done by adding a custom field to the Customer entity to store
the Stripe customer ID, so switching this on will require a database migration / synchronization.
### metadata

<MemberInfo kind="property" type={`(         injector: <a href='/reference/typescript-api/common/injector#injector'>Injector</a>,         ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>,         order: <a href='/reference/typescript-api/entities/order#order'>Order</a>,     ) =&#62; Stripe.MetadataParam | Promise&#60;Stripe.MetadataParam&#62;`}  since="1.9.7"  />

Attach extra metadata to Stripe payment intent creation call.

*Example*

```ts
import { EntityHydrator, VendureConfig } from '@vendure/core';
import { StripePlugin } from '@vendure/payments-plugin/package/stripe';

export const config: VendureConfig = {
  // ...
  plugins: [
    StripePlugin.init({
      metadata: async (injector, ctx, order) => {
        const hydrator = injector.get(EntityHydrator);
        await hydrator.hydrate(ctx, order, { relations: ['customer'] });
        return {
          description: `Order #${order.code} for ${order.customer!.emailAddress}`
        },
      }
    }),
  ],
};
```

Note: If the `paymentIntentCreateParams` is also used and returns a `metadata` key, then the values
returned by both functions will be merged.
### paymentIntentCreateParams

<MemberInfo kind="property" type={`(         injector: <a href='/reference/typescript-api/common/injector#injector'>Injector</a>,         ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>,         order: <a href='/reference/typescript-api/entities/order#order'>Order</a>,     ) =&#62; AdditionalPaymentIntentCreateParams | Promise&#60;AdditionalPaymentIntentCreateParams&#62;`}  since="2.1.0"  />

Provide additional parameters to the Stripe payment intent creation. By default,
the plugin will already pass the `amount`, `currency`, `customer` and `automatic_payment_methods: { enabled: true }` parameters.

For example, if you want to provide a `description` for the payment intent, you can do so like this:

*Example*

```ts
import { VendureConfig } from '@vendure/core';
import { StripePlugin } from '@vendure/payments-plugin/package/stripe';

export const config: VendureConfig = {
  // ...
  plugins: [
    StripePlugin.init({
      paymentIntentCreateParams: (injector, ctx, order) => {
        return {
          description: `Order #${order.code} for ${order.customer?.emailAddress}`
        },
      }
    }),
  ],
};
```
### requestOptions

<MemberInfo kind="property" type={`(         injector: <a href='/reference/typescript-api/common/injector#injector'>Injector</a>,         ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>,         order: <a href='/reference/typescript-api/entities/order#order'>Order</a>,     ) =&#62; AdditionalRequestOptions | Promise&#60;AdditionalRequestOptions&#62;`}  since="3.1.0"  />

Provide additional options to the Stripe payment intent creation. By default,
the plugin will already pass the `idempotencyKey` parameter.

For example, if you want to provide a `stripeAccount` for the payment intent, you can do so like this:

*Example*

```ts
import { VendureConfig } from '@vendure/core';
import { StripePlugin } from '@vendure/payments-plugin/package/stripe';

export const config: VendureConfig = {
  // ...
  plugins: [
    StripePlugin.init({
      requestOptions: (injector, ctx, order) => {
        return {
          stripeAccount: ctx.channel.seller?.customFields.connectedAccountId
        },
      }
    }),
  ],
};
```
### customerCreateParams

<MemberInfo kind="property" type={`(         injector: <a href='/reference/typescript-api/common/injector#injector'>Injector</a>,         ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>,         order: <a href='/reference/typescript-api/entities/order#order'>Order</a>,     ) =&#62; AdditionalCustomerCreateParams | Promise&#60;AdditionalCustomerCreateParams&#62;`}  since="2.1.0"  />

Provide additional parameters to the Stripe customer creation. By default,
the plugin will already pass the `email` and `name` parameters.

For example, if you want to provide an address for the customer:

*Example*

```ts
import { EntityHydrator, VendureConfig } from '@vendure/core';
import { StripePlugin } from '@vendure/payments-plugin/package/stripe';

export const config: VendureConfig = {
  // ...
  plugins: [
    StripePlugin.init({
      storeCustomersInStripe: true,
      customerCreateParams: async (injector, ctx, order) => {
        const entityHydrator = injector.get(EntityHydrator);
        const customer = order.customer;
        await entityHydrator.hydrate(ctx, customer, { relations: ['addresses'] });
        const defaultBillingAddress = customer.addresses.find(a => a.defaultBillingAddress) ?? customer.addresses[0];
        return {
          address: {
              line1: defaultBillingAddress.streetLine1 || order.shippingAddress?.streetLine1,
              postal_code: defaultBillingAddress.postalCode || order.shippingAddress?.postalCode,
              city: defaultBillingAddress.city || order.shippingAddress?.city,
              state: defaultBillingAddress.province || order.shippingAddress?.province,
              country: defaultBillingAddress.country.code || order.shippingAddress?.countryCode,
          },
        },
      }
    }),
  ],
};
```
### skipPaymentIntentsWithoutExpectedMetadata

<MemberInfo kind="property" type={`boolean`}   />

If your Stripe account also generates payment intents which are independent of Vendure orders, you can set this
to `true` to skip processing those payment intents.


</div>


---

---
title: "SentryPlugin"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## SentryPlugin

<GenerationInfo sourceFile="packages/sentry-plugin/src/sentry-plugin.ts" sourceLine="108" packageName="@vendure/sentry-plugin" />

This plugin integrates the [Sentry](https://sentry.io) error tracking & performance monitoring
service with your Vendure server. In addition to capturing errors, it also provides built-in
support for [tracing](https://docs.sentry.io/product/sentry-basics/concepts/tracing/) as well as
enriching your Sentry events with additional context about the request.

## Pre-requisites

This plugin depends on access to Sentry, which can be self-hosted or used as a cloud service.

If using the hosted SaaS option, you must have a Sentry account and a project set up ([sign up here](https://sentry.io/signup/)). When setting up your project,
select the "Node.js" platform and no framework.

Once set up, you will be given a [Data Source Name (DSN)](https://docs.sentry.io/product/sentry-basics/concepts/dsn-explainer/)
which you will need to provide to the plugin.

## Installation

Install this plugin as well as the `@sentry/node` package:

```sh
npm install --save @vendure/sentry-plugin @sentry/node
```

## Configuration

Before using the plugin, you must configure it with the DSN provided by Sentry:

```ts
import { VendureConfig } from '@vendure/core';
import { SentryPlugin } from '@vendure/sentry-plugin';

export const config: VendureConfig = {
    // ...
    plugins: [
        // ...
        // highlight-start
        SentryPlugin.init({
            dsn: process.env.SENTRY_DSN,
            // Optional configuration
            includeErrorTestMutation: true,
            enableTracing: true,
            // you can also pass in any of the options from @sentry/node
            // for instance:
            tracesSampleRate: 1.0,
        }),
        // highlight-end
    ],
};
```

## Tracing

This plugin includes built-in support for [tracing](https://docs.sentry.io/product/sentry-basics/concepts/tracing/), which allows you to see the performance of your
GraphQL resolvers in the Sentry dashboard. To enable tracing, set the `enableTracing` option to `true` as shown above.

## Instrumenting your own code

You may want to add your own custom spans to your code. To do so, you can use the `Sentry` object
just as you would in any Node application. For example:

```ts
import * as Sentry from "@sentry/node";

export class MyService {
    async myMethod() {
         Sentry.setContext('My Custom Context,{
             key: 'value',
         });
    }
}
```

## Error test mutation

To test whether your Sentry configuration is working correctly, you can set the `includeErrorTestMutation` option to `true`. This will add a mutation to the Admin API
which will throw an error of the type specified in the `errorType` argument. For example:

```graphql
mutation CreateTestError {
    createTestError(errorType: DATABASE_ERROR)
}
```

You should then be able to see the error in your Sentry dashboard (it may take a couple of minutes to appear).

```ts title="Signature"
class SentryPlugin implements NestModule {
    static options: SentryPluginOptions = {} as any;
    configure(consumer: MiddlewareConsumer) => any;
    init(options: SentryPluginOptions) => ;
}
```
* Implements: <code>NestModule</code>



<div className="members-wrapper">

### options

<MemberInfo kind="property" type={`<a href='/reference/core-plugins/sentry-plugin/sentry-plugin-options#sentrypluginoptions'>SentryPluginOptions</a>`}   />


### configure

<MemberInfo kind="method" type={`(consumer: MiddlewareConsumer) => any`}   />


### init

<MemberInfo kind="method" type={`(options: <a href='/reference/core-plugins/sentry-plugin/sentry-plugin-options#sentrypluginoptions'>SentryPluginOptions</a>) => `}   />




</div>


---

---
title: "SentryPluginOptions"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## SentryPluginOptions

<GenerationInfo sourceFile="packages/sentry-plugin/src/types.ts" sourceLine="12" packageName="@vendure/sentry-plugin" />

Configuration options for the <a href='/reference/core-plugins/sentry-plugin/#sentryplugin'>SentryPlugin</a>.

```ts title="Signature"
interface SentryPluginOptions extends NodeOptions {
    dsn: string;
    enableTracing?: boolean;
    includeErrorTestMutation?: boolean;
}
```
* Extends: <code>NodeOptions</code>



<div className="members-wrapper">

### dsn

<MemberInfo kind="property" type={`string`}   />

The [Data Source Name](https://docs.sentry.io/product/sentry-basics/concepts/dsn-explainer/) for your Sentry instance.
### enableTracing

<MemberInfo kind="property" type={`boolean`}   />


### includeErrorTestMutation

<MemberInfo kind="property" type={`boolean`}   />




</div>


---

---
title: "StellatePlugin"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## StellatePlugin

<GenerationInfo sourceFile="packages/stellate-plugin/src/stellate-plugin.ts" sourceLine="246" packageName="@vendure/stellate-plugin" since="2.1.5" />

A plugin to integrate the [Stellate](https://stellate.co/) GraphQL caching service with your Vendure server.
The main purpose of this plugin is to ensure that cached data gets correctly purged in
response to events inside Vendure. For example, changes to a Product's description should
purge any associated record for that Product in Stellate's cache.

## Pre-requisites

You will first need to [set up a free Stellate account](https://stellate.co/signup).

You will also need to generate an **API token** for the Stellate Purging API. For instructions on how to generate the token,
see the [Stellate Purging API docs](https://docs.stellate.co/docs/purging-api#authentication).

## Installation

```
npm install @vendure/stellate-plugin
```

## Configuration

The plugin is configured via the `StellatePlugin.init()` method. This method accepts an options object
which defines the Stellate service name and API token, as well as an array of <a href='/reference/core-plugins/stellate-plugin/purge-rule#purgerule'>PurgeRule</a>s which
define how the plugin will respond to Vendure events in order to trigger calls to the
Stellate [Purging API](https://stellate.co/docs/graphql-edge-cache/purging-api).

*Example*

```ts
import { StellatePlugin, defaultPurgeRules } from '@vendure/stellate-plugin';
import { VendureConfig } from '@vendure/core';

export const config: VendureConfig = {
   // ...
   plugins: [
       StellatePlugin.init({
           // The Stellate service name, i.e. `<serviceName>.stellate.sh`
           serviceName: 'my-service',
           // The API token for the Stellate Purging API. See the "pre-requisites" section above.
           apiToken: process.env.STELLATE_PURGE_API_TOKEN,
           devMode: !isProd || process.env.STELLATE_DEBUG_MODE ? true : false,
           debugLogging: process.env.STELLATE_DEBUG_MODE ? true : false,
           purgeRules: [
               ...defaultPurgeRules,
               // custom purge rules can be added here
           ],
       }),
   ],
};
```

In your Stellate dashboard, you can use the following configuration example as a sensible default for a
Vendure application:

*Example*

```ts
import { Config } from "stellate";

const config: Config = {
  config: {
    name: "my-vendure-server",
    originUrl: "https://my-vendure-server.com/shop-api",
    ignoreOriginCacheControl: true,
    passThroughOnly: false,
    scopes: {
      SESSION_BOUND: "header:authorization|cookie:session",
    },
    headers: {
      "access-control-expose-headers": "vendure-auth-token",
    },
    rootTypeNames: {
      query: "Query",
      mutation: "Mutation",
    },
    keyFields: {
      types: {
        SearchResult: ["productId"],
        SearchResponseCacheIdentifier: ["collectionSlug"],
      },
    },
    rules: [
      {
        types: [
          "Product",
          "Collection",
          "ProductVariant",
          "SearchResponse",
        ],
        maxAge: 900,
        swr: 900,
        description: "Cache Products & Collections",
      },
      {
        types: ["Channel"],
        maxAge: 9000,
        swr: 9000,
        description: "Cache active channel",
      },
      {
        types: ["Order", "Customer", "User"],
        maxAge: 0,
        swr: 0,
        description: "Do not cache user data",
      },
    ],
  },
};
export default config;
```

## Storefront setup

In your storefront, you should point your GraphQL client to the Stellate GraphQL API endpoint, which is
`https://<service-name>.stellate.sh`.

Wherever you are using the `search` query (typically in product listing & search pages), you should also add the
`cacheIdentifier` field to the query. This will ensure that the Stellate cache is correctly purged when
a Product or Collection is updated.

*Example*

```ts
import { graphql } from '../generated/gql';

export const searchProductsDocument = graphql(`
    query SearchProducts($input: SearchInput!) {
        search(input: $input) {
            // highlight-start
            cacheIdentifier {
                collectionSlug
            }
            // highlight-end
            items {
               # ...
            }
        }
    }
}`);
```

## Custom PurgeRules

The configuration above only accounts for caching of some of the built-in Vendure entity types. If you have
custom entity types, you may well want to add them to the Stellate cache. In this case, you'll also need a way to
purge those entities from the cache when they are updated. This is where the <a href='/reference/core-plugins/stellate-plugin/purge-rule#purgerule'>PurgeRule</a> comes in.

Let's imagine that you have built a simple CMS plugin for Vendure which exposes an `Article` entity in your Shop API, and
you have added this to your Stellate configuration:

*Example*

```ts
import { Config } from "stellate";

const config: Config = {
    config: {
        // ...
        rules: [
            // ...
            {
                types: ["Article"],
                maxAge: 900,
                swr: 900,
                description: "Cache Articles",
            },
        ],
    },
    // ...
};
export default config;
```

You can then add a custom <a href='/reference/core-plugins/stellate-plugin/purge-rule#purgerule'>PurgeRule</a> to the StellatePlugin configuration:

*Example*

```ts
import { StellatePlugin, defaultPurgeRules } from "@vendure/stellate-plugin";
import { VendureConfig } from "@vendure/core";
import { ArticleEvent } from "./plugins/cms/events/article-event";

export const config: VendureConfig = {
    // ...
    plugins: [
        StellatePlugin.init({
            // ...
            purgeRules: [
                ...defaultPurgeRules,
                new PurgeRule({
                    eventType: ArticleEvent,
                    handler: async ({ events, stellateService }) => {
                        const articleIds = events.map((e) => e.article.id);
                        stellateService.purge("Article", articleIds);
                    },
                }),
            ],
        }),
    ],
};
```

## DevMode & Debug Logging

In development, you can set `devMode: true`, which will prevent any calls being made to the Stellate Purging API.

If you want to log the calls that _would_ be made to the Stellate Purge API when in devMode, you can set `debugLogging: true`.
Note that debugLogging generates a lot of debug-level logging, so it is recommended to only enable this when needed.

*Example*

```ts
import { StellatePlugin, defaultPurgeRules } from '@vendure/stellate-plugin';
import { VendureConfig } from '@vendure/core';

export const config: VendureConfig = {
   // ...
   plugins: [
       StellatePlugin.init({
           // ...
           devMode: !process.env.PRODUCTION,
           debugLogging: process.env.STELLATE_DEBUG_MODE ? true : false,
           purgeRules: [
               ...defaultPurgeRules,
           ],
       }),
   ],
};
```

```ts title="Signature"
class StellatePlugin implements OnApplicationBootstrap {
    static options: StellatePluginOptions;
    init(options: StellatePluginOptions) => ;
    constructor(options: StellatePluginOptions, eventBus: EventBus, stellateService: StellateService, moduleRef: ModuleRef)
    onApplicationBootstrap() => ;
}
```
* Implements: <code>OnApplicationBootstrap</code>



<div className="members-wrapper">

### options

<MemberInfo kind="property" type={`<a href='/reference/core-plugins/stellate-plugin/stellate-plugin-options#stellatepluginoptions'>StellatePluginOptions</a>`}   />


### init

<MemberInfo kind="method" type={`(options: <a href='/reference/core-plugins/stellate-plugin/stellate-plugin-options#stellatepluginoptions'>StellatePluginOptions</a>) => `}   />


### constructor

<MemberInfo kind="method" type={`(options: <a href='/reference/core-plugins/stellate-plugin/stellate-plugin-options#stellatepluginoptions'>StellatePluginOptions</a>, eventBus: <a href='/reference/typescript-api/events/event-bus#eventbus'>EventBus</a>, stellateService: <a href='/reference/core-plugins/stellate-plugin/stellate-service#stellateservice'>StellateService</a>, moduleRef: ModuleRef) => StellatePlugin`}   />


### onApplicationBootstrap

<MemberInfo kind="method" type={`() => `}   />




</div>


---

---
title: "PurgeRule"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## PurgeRule

<GenerationInfo sourceFile="packages/stellate-plugin/src/purge-rule.ts" sourceLine="49" packageName="@vendure/stellate-plugin" />

Defines a rule that listens for a particular VendureEvent and uses that to
make calls to the [Stellate Purging API](https://docs.stellate.co/docs/purging-api) via
the provided <a href='/reference/core-plugins/stellate-plugin/stellate-service#stellateservice'>StellateService</a> instance.

```ts title="Signature"
class PurgeRule<Event extends VendureEvent = VendureEvent> {
    eventType: Type<Event>
    bufferTimeMs: number | undefined
    handle(handlerArgs: { events: Event[]; stellateService: StellateService; injector: Injector }) => ;
    constructor(config: PurgeRuleConfig<Event>)
}
```

<div className="members-wrapper">

### eventType

<MemberInfo kind="property" type={`Type&#60;Event&#62;`}   />


### bufferTimeMs

<MemberInfo kind="property" type={`number | undefined`}   />


### handle

<MemberInfo kind="method" type={`(handlerArgs: { events: Event[]; stellateService: <a href='/reference/core-plugins/stellate-plugin/stellate-service#stellateservice'>StellateService</a>; injector: <a href='/reference/typescript-api/common/injector#injector'>Injector</a> }) => `}   />


### constructor

<MemberInfo kind="method" type={`(config: <a href='/reference/core-plugins/stellate-plugin/purge-rule#purgeruleconfig'>PurgeRuleConfig</a>&#60;Event&#62;) => PurgeRule`}   />




</div>


## PurgeRuleConfig

<GenerationInfo sourceFile="packages/stellate-plugin/src/purge-rule.ts" sourceLine="13" packageName="@vendure/stellate-plugin" />

Configures a <a href='/reference/core-plugins/stellate-plugin/purge-rule#purgerule'>PurgeRule</a>.

```ts title="Signature"
interface PurgeRuleConfig<Event extends VendureEvent> {
    eventType: Type<Event>;
    bufferTime?: number;
    handler: (handlerArgs: {
        events: Event[];
        stellateService: StellateService;
        injector: Injector;
    }) => void | Promise<void>;
}
```

<div className="members-wrapper">

### eventType

<MemberInfo kind="property" type={`Type&#60;Event&#62;`}   />

Specifies which VendureEvent will trigger this purge rule.
### bufferTime

<MemberInfo kind="property" type={`number`} default={`5000`}   />

How long to buffer events for in milliseconds before executing the handler. This allows
us to efficiently batch calls to the Stellate Purge API.
### handler

<MemberInfo kind="property" type={`(handlerArgs: {         events: Event[];         stellateService: <a href='/reference/core-plugins/stellate-plugin/stellate-service#stellateservice'>StellateService</a>;         injector: <a href='/reference/typescript-api/common/injector#injector'>Injector</a>;     }) =&#62; void | Promise&#60;void&#62;`}   />

The function to invoke when the specified event is published. This function should use the
<a href='/reference/core-plugins/stellate-plugin/stellate-service#stellateservice'>StellateService</a> instance to call the Stellate Purge API.


</div>


---

---
title: "StellatePluginOptions"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## StellatePluginOptions

<GenerationInfo sourceFile="packages/stellate-plugin/src/types.ts" sourceLine="9" packageName="@vendure/stellate-plugin" />

Configuration options for the StellatePlugin.

```ts title="Signature"
interface StellatePluginOptions {
    serviceName: string;
    apiToken: string;
    purgeRules: PurgeRule[];
    defaultBufferTimeMs?: number;
    devMode?: boolean;
    debugLogging?: boolean;
}
```

<div className="members-wrapper">

### serviceName

<MemberInfo kind="property" type={`string`}   />

The Stellate service name, i.e. `<service-name>.stellate.sh`
### apiToken

<MemberInfo kind="property" type={`string`}   />

The Stellate Purging API token. For instructions on how to generate the token,
see the [Stellate docs](https://docs.stellate.co/docs/purging-api#authentication)
### purgeRules

<MemberInfo kind="property" type={`<a href='/reference/core-plugins/stellate-plugin/purge-rule#purgerule'>PurgeRule</a>[]`}   />

An array of <a href='/reference/core-plugins/stellate-plugin/purge-rule#purgerule'>PurgeRule</a> instances which are used to define how the plugin will
respond to Vendure events in order to trigger calls to the Stellate Purging API.
### defaultBufferTimeMs

<MemberInfo kind="property" type={`number`} default={`2000`}   />

When events are published, the PurgeRules will buffer those events in order to efficiently
batch requests to the Stellate Purging API. You may wish to change the default, e.g. if you are
running in a serverless environment and cannot introduce pauses after the main request has completed.
### devMode

<MemberInfo kind="property" type={`boolean`} default={`false`}   />

When set to `true`, calls will not be made to the Stellate Purge API.
### debugLogging

<MemberInfo kind="property" type={`boolean`} default={`false`}   />

If set to true, the plugin will log the calls that would be made
to the Stellate Purge API. Note, this generates a
lot of debug-level logging.


</div>


---

---
title: "StellateService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## StellateService

<GenerationInfo sourceFile="packages/stellate-plugin/src/service/stellate.service.ts" sourceLine="23" packageName="@vendure/stellate-plugin" />

The StellateService is used to purge the Stellate cache when certain events occur.

```ts title="Signature"
class StellateService {
    constructor(options: StellatePluginOptions)
    purgeProducts(products: Product[]) => ;
    purgeProductVariants(productVariants: ProductVariant[]) => ;
    purgeSearchResults(items: Array<ProductVariant | Product>) => ;
    purgeAllOfType(type: CachedType) => ;
    purgeCollections(collections: Collection[]) => ;
    purgeSearchResponseCacheIdentifiers(collections: Collection[]) => ;
    purge(type: CachedType, keys?: ID[], keyName:  = 'id') => ;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(options: <a href='/reference/core-plugins/stellate-plugin/stellate-plugin-options#stellatepluginoptions'>StellatePluginOptions</a>) => StellateService`}   />


### purgeProducts

<MemberInfo kind="method" type={`(products: <a href='/reference/typescript-api/entities/product#product'>Product</a>[]) => `}   />

Purges the cache for the given Products.
### purgeProductVariants

<MemberInfo kind="method" type={`(productVariants: <a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>[]) => `}   />

Purges the cache for the given ProductVariants.
### purgeSearchResults

<MemberInfo kind="method" type={`(items: Array&#60;<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a> | <a href='/reference/typescript-api/entities/product#product'>Product</a>&#62;) => `}   />

Purges the cache for SearchResults which contain the given Products or ProductVariants.
### purgeAllOfType

<MemberInfo kind="method" type={`(type: CachedType) => `}   />

Purges the entire cache for the given type.
### purgeCollections

<MemberInfo kind="method" type={`(collections: <a href='/reference/typescript-api/entities/collection#collection'>Collection</a>[]) => `}   />

Purges the cache for the given Collections.
### purgeSearchResponseCacheIdentifiers

<MemberInfo kind="method" type={`(collections: <a href='/reference/typescript-api/entities/collection#collection'>Collection</a>[]) => `}   />

Purges the cache of SearchResults for the given Collections based on slug.
### purge

<MemberInfo kind="method" type={`(type: CachedType, keys?: <a href='/reference/typescript-api/common/id#id'>ID</a>[], keyName:  = 'id') => `}   />

Purges the cache for the given type and keys.


</div>


---

---
title: "GetSdkConfiguration"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## getSdkConfiguration

<GenerationInfo sourceFile="packages/telemetry-plugin/src/instrumentation.ts" sourceLine="89" packageName="@vendure/telemetry-plugin" />

Creates a configuration object for the OpenTelemetry Node SDK. This is used to set up a custom
preload script which must be run before the main Vendure server is loaded by means of the
Node.js `--require` flag.

*Example*

```ts
// instrumentation.ts
import { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-proto';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { BatchLogRecordProcessor } from '@opentelemetry/sdk-logs';
import { NodeSDK } from '@opentelemetry/sdk-node';
import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
import { getSdkConfiguration } from '@vendure/telemetry-plugin/preload';

process.env.OTEL_EXPORTER_OTLP_ENDPOINT = 'http://localhost:3100/otlp';
process.env.OTEL_LOGS_EXPORTER = 'otlp';
process.env.OTEL_RESOURCE_ATTRIBUTES = 'service.name=vendure-dev-server';

const traceExporter = new OTLPTraceExporter({
    url: 'http://localhost:4318/v1/traces',
});
const logExporter = new OTLPLogExporter();

const config = getSdkConfiguration({
    config: {
        spanProcessors: [new BatchSpanProcessor(traceExporter)],
        logRecordProcessors: [new BatchLogRecordProcessor(logExporter)],
    },
});

const sdk = new NodeSDK(config);

sdk.start();
```

This would them be run as:
```bash
node --require ./dist/instrumentation.js ./dist/server.js
```

```ts title="Signature"
function getSdkConfiguration(options?: SdkConfigurationOptions): Partial<NodeSDKConfiguration>
```
Parameters

### options

<MemberInfo kind="parameter" type={`<a href='/reference/core-plugins/telemetry-plugin/get-sdk-configuration#sdkconfigurationoptions'>SdkConfigurationOptions</a>`} />



## SdkConfigurationOptions

<GenerationInfo sourceFile="packages/telemetry-plugin/src/instrumentation.ts" sourceLine="27" packageName="@vendure/telemetry-plugin" />

Options for configuring the OpenTelemetry Node SDK.

```ts title="Signature"
interface SdkConfigurationOptions {
    logToConsole?: boolean;
    config: Partial<NodeSDKConfiguration>;
}
```

<div className="members-wrapper">

### logToConsole

<MemberInfo kind="property" type={`boolean`} default={`false`}   />

When set to `true`, the SDK will log spans to the console instead of sending them to an
exporter. This should just be used for debugging purposes.
### config

<MemberInfo kind="property" type={`Partial&#60;NodeSDKConfiguration&#62;`}   />

The configuration object for the OpenTelemetry Node SDK.


</div>


---

---
title: "TelemetryPlugin"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## TelemetryPlugin

<GenerationInfo sourceFile="packages/telemetry-plugin/src/telemetry.plugin.ts" sourceLine="107" packageName="@vendure/telemetry-plugin" since="3.3.0" />

The TelemetryPlugin is used to instrument the Vendure application and collect telemetry data using
[OpenTelemetry](https://opentelemetry.io/).

## Installation

```
npm install @vendure/telemetry-plugin
```

:::info
For a complete guide to setting up and working with Open Telemetry, see
the [Implementing Open Telemetry guide](/guides/how-to/telemetry/).
:::

## Configuration

The plugin is configured via the `TelemetryPlugin.init()` method. This method accepts an options object
which defines the OtelLogger options and method hooks.

*Example*

```ts
import { VendureConfig } from '@vendure/core';
import { TelemetryPlugin, registerMethodHooks } from '@vendure/telemetry-plugin';

export const config: VendureConfig = {
  // ...
  plugins: [
    TelemetryPlugin.init({
      loggerOptions: {
        // Log to the console at the verbose level
        console: LogLevel.Verbose,
      },
    }),
  ],
};
```

## Preloading the SDK

In order to use the OpenTelemetry SDK, you must preload it before the Vendure server is started.
This is done by using the `--require` flag when starting the server with a custom preload script.

Create a file named `instrumentation.ts` in the root of your project and add the following code:

```ts
import { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-proto';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { BatchLogRecordProcessor } from '@opentelemetry/sdk-logs';
import { NodeSDK } from '@opentelemetry/sdk-node';
import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
import { getSdkConfiguration } from '@vendure/telemetry-plugin/preload';

// In this example we are using Loki as the OTLP endpoint for logging
process.env.OTEL_EXPORTER_OTLP_ENDPOINT = 'http://localhost:3100/otlp';
process.env.OTEL_LOGS_EXPORTER = 'otlp';
process.env.OTEL_RESOURCE_ATTRIBUTES = 'service.name=vendure-dev-server';

// We are using Jaeger as the OTLP endpoint for tracing
const traceExporter = new OTLPTraceExporter({
    url: 'http://localhost:4318/v1/traces',
});
const logExporter = new OTLPLogExporter();

// The getSdkConfiguration method returns a configuration object for the OpenTelemetry Node SDK.
// It also performs other configuration tasks such as setting a special environment variable
// to enable instrumentation in the Vendure core code.
const config = getSdkConfiguration({
    config: {
        // Pass in any custom configuration options for the Node SDK here
        spanProcessors: [new BatchSpanProcessor(traceExporter)],
        logRecordProcessors: [new BatchLogRecordProcessor(logExporter)],
    },
});

const sdk = new NodeSDK(config);

sdk.start();
```

The server would then be started with the following command:

```bash
node --require ./dist/instrumentation.js ./dist/server.js
```

or for development with ts-node:

```bash
npx ts-node --require ./src/instrumentation.ts ./src/server.ts
```

```ts title="Signature"
class TelemetryPlugin {
    static options: TelemetryPluginOptions = {};
    constructor(methodHooksService: MethodHooksService, options: TelemetryPluginOptions)
    init(options: TelemetryPluginOptions) => ;
}
```

<div className="members-wrapper">

### options

<MemberInfo kind="property" type={`<a href='/reference/core-plugins/telemetry-plugin/telemetry-plugin-options#telemetrypluginoptions'>TelemetryPluginOptions</a>`}   />


### constructor

<MemberInfo kind="method" type={`(methodHooksService: MethodHooksService, options: <a href='/reference/core-plugins/telemetry-plugin/telemetry-plugin-options#telemetrypluginoptions'>TelemetryPluginOptions</a>) => TelemetryPlugin`}   />


### init

<MemberInfo kind="method" type={`(options: <a href='/reference/core-plugins/telemetry-plugin/telemetry-plugin-options#telemetrypluginoptions'>TelemetryPluginOptions</a>) => `}   />




</div>


---

---
title: "OtelLogger"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## OtelLogger

<GenerationInfo sourceFile="packages/telemetry-plugin/src/config/otel-logger.ts" sourceLine="46" packageName="@vendure/telemetry-plugin" since="3.3.0" />

A logger that emits logs to OpenTelemetry and optionally to the console.

```ts title="Signature"
class OtelLogger implements VendureLogger {
    constructor(options: OtelLoggerOptions)
    debug(message: string, context?: string) => void;
    warn(message: string, context?: string) => void;
    info(message: string, context?: string) => void;
    error(message: string, context?: string) => void;
    verbose(message: string, context?: string) => void;
}
```
* Implements: <code><a href='/reference/typescript-api/logger/vendure-logger#vendurelogger'>VendureLogger</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(options: <a href='/reference/core-plugins/telemetry-plugin/otel-logger#otelloggeroptions'>OtelLoggerOptions</a>) => OtelLogger`}   />


### debug

<MemberInfo kind="method" type={`(message: string, context?: string) => void`}   />


### warn

<MemberInfo kind="method" type={`(message: string, context?: string) => void`}   />


### info

<MemberInfo kind="method" type={`(message: string, context?: string) => void`}   />


### error

<MemberInfo kind="method" type={`(message: string, context?: string) => void`}   />


### verbose

<MemberInfo kind="method" type={`(message: string, context?: string) => void`}   />




</div>


## OtelLoggerOptions

<GenerationInfo sourceFile="packages/telemetry-plugin/src/config/otel-logger.ts" sourceLine="14" packageName="@vendure/telemetry-plugin" since="3.3.0" />

Options for the OtelLogger.

```ts title="Signature"
interface OtelLoggerOptions {
    logToConsole?: LogLevel;
}
```

<div className="members-wrapper">

### logToConsole

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/logger/log-level#loglevel'>LogLevel</a>`}   />

If set to a LogLevel, the logger will also log to the console.
This can be useful for local development or debugging.

*Example*

```ts
import { LogLevel } from '@vendure/core';
import { TelemetryPlugin } from '@vendure/telemetry-plugin';

// ...

TelemetryPlugin.init({
  loggerOptions: {
    logToConsole: LogLevel.Verbose,
  },
});
```


</div>


---

---
title: "RegisterMethodHooks"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## registerMethodHooks

<GenerationInfo sourceFile="packages/telemetry-plugin/src/service/method-hooks.service.ts" sourceLine="60" packageName="@vendure/telemetry-plugin" since="3.3.0" />

Allows you to register hooks for a specific method of an instrumented class.
These hooks allow extra telemetry actions to be performed on the method.

They can then be passed to the <a href='/reference/core-plugins/telemetry-plugin/#telemetryplugin'>TelemetryPlugin</a> via the <a href='/reference/core-plugins/telemetry-plugin/telemetry-plugin-options#telemetrypluginoptions'>TelemetryPluginOptions</a>.

*Example*

```typescript
const productServiceHooks = registerMethodHooks(ProductService, {
    findOne: {
        // This will be called before the method is executed
        pre: ({ args: [ctx, productId], span }) => {
            span.setAttribute('productId', productId);
        },
        // This will be called after the method is executed
        post: ({ result, span }) => {
            span.setAttribute('found', !!result);
        },
    },
});
```

```ts title="Signature"
function registerMethodHooks<T>(target: Type<T>, hooks: MethodHooksForType<T>): MethodHookConfig<T>
```
Parameters

### target

<MemberInfo kind="parameter" type={`Type&#60;T&#62;`} />

### hooks

<MemberInfo kind="parameter" type={`MethodHooksForType&#60;T&#62;`} />



---

---
title: "TelemetryPluginOptions"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## TelemetryPluginOptions

<GenerationInfo sourceFile="packages/telemetry-plugin/src/types.ts" sourceLine="18" packageName="@vendure/telemetry-plugin" since="3.3.0" />

Configuration options for the TelemetryPlugin.

```ts title="Signature"
interface TelemetryPluginOptions {
    loggerOptions?: OtelLoggerOptions;
    methodHooks?: Array<MethodHookConfig<any>>;
}
```

<div className="members-wrapper">

### loggerOptions

<MemberInfo kind="property" type={`<a href='/reference/core-plugins/telemetry-plugin/otel-logger#otelloggeroptions'>OtelLoggerOptions</a>`}   />

The options for the OtelLogger.

For example, to also include logging to the console, you can use the following:
```ts
import { LogLevel } from '@vendure/core';
import { TelemetryPlugin } from '@vendure/telemetry-plugin';

TelemetryPlugin.init({
    loggerOptions: {
        console: LogLevel.Verbose,
    },
});
```
### methodHooks

<MemberInfo kind="property" type={`Array&#60;MethodHookConfig&#60;any&#62;&#62;`}  experimental="true" />

**Status: Developer Preview**

This API may change in a future release.

Method hooks allow you to add extra telemetry actions to specific methods.
To define hooks on a method, use the <a href='/reference/core-plugins/telemetry-plugin/register-method-hooks#registermethodhooks'>registerMethodHooks</a> function.

*Example*

```ts
import { TelemetryPlugin, registerMethodHooks } from '@vendure/telemetry-plugin';

TelemetryPlugin.init({
  methodHooks: [
    registerMethodHooks(ProductService, {

      // Define some hooks for the `findOne` method
      findOne: {
        // This will be called before the method is executed
        pre: ({ args: [ctx, productId], span }) => {
          span.setAttribute('productId', productId);
        },
        // This will be called after the method is executed
        post: ({ result, span }) => {
          span.setAttribute('found', !!result);
        },
      },
    }),
  ],
});
```


</div>


---

---
title: "DetailPage"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DetailPage

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/page/detail-page.tsx" sourceLine="152" packageName="@vendure/dashboard" since="3.3.0" />

**Status: Developer Preview**

Auto-generates a detail page with a form based on the provided query and mutation documents.

For more control over the layout, you would use the more low-level <a href='/reference/dashboard/components/page#page'>Page</a> component.

```ts title="Signature"
function DetailPage<T extends TypedDocumentNode<any, any>, C extends TypedDocumentNode<any, any>, U extends TypedDocumentNode<any, any>>(props: DetailPageProps<T, C, U>): void
```
Parameters

### props

<MemberInfo kind="parameter" type={`<a href='/reference/dashboard/components/detail-page#detailpageprops'>DetailPageProps</a>&#60;T, C, U&#62;`} />



## DetailPageProps

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/page/detail-page.tsx" sourceLine="42" packageName="@vendure/dashboard" since="3.3.0" />

**Status: Developer Preview**

```ts title="Signature"
interface DetailPageProps<T extends TypedDocumentNode<any, any>, C extends TypedDocumentNode<any, any>, U extends TypedDocumentNode<any, any>, EntityField extends keyof ResultOf<T> = DetailEntityPath<T>> {
    entityName?: string;
    pageId: string;
    route: AnyRoute;
    title: (entity: ResultOf<T>[EntityField]) => string;
    queryDocument: T;
    createDocument?: C;
    updateDocument: U;
    setValuesForUpdate: (entity: ResultOf<T>[EntityField]) => VariablesOf<U>['input'];
}
```

<div className="members-wrapper">

### entityName

<MemberInfo kind="property" type={`string`}   />

The name of the entity.
If not provided, it will be inferred from the query document.
### pageId

<MemberInfo kind="property" type={`string`}   />

A unique identifier for the page.
### route

<MemberInfo kind="property" type={`AnyRoute`}   />

The Tanstack Router route used to navigate to this page.
### title

<MemberInfo kind="property" type={`(entity: ResultOf&#60;T&#62;[EntityField]) =&#62; string`}   />

The title of the page.
### queryDocument

<MemberInfo kind="property" type={`T`}   />

The query document used to fetch the entity.
### createDocument

<MemberInfo kind="property" type={`C`}   />

The mutation document used to create the entity.
### updateDocument

<MemberInfo kind="property" type={`U`}   />

The mutation document used to update the entity.
### setValuesForUpdate

<MemberInfo kind="property" type={`(entity: ResultOf&#60;T&#62;[EntityField]) =&#62; VariablesOf&#60;U&#62;['input']`}   />

A function that sets the values for the update input type based on the entity.


</div>


---

---
title: "Components"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "ListPage"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ListPage

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/page/list-page.tsx" sourceLine="76" packageName="@vendure/dashboard" since="3.3.0" />

**Status: Developer Preview**

Auto-generates a list page with columns generated based on the provided query document fields.

```ts title="Signature"
function ListPage<T extends TypedDocumentNode<U, V>, U extends Record<string, any> = any, V extends ListQueryOptionsShape = ListQueryOptionsShape, AC extends AdditionalColumns<T> = AdditionalColumns<T>>(props: Readonly<ListPageProps<T, U, V, AC>>): void
```
Parameters

### props

<MemberInfo kind="parameter" type={`Readonly&#60;<a href='/reference/dashboard/components/list-page#listpageprops'>ListPageProps</a>&#60;T, U, V, AC&#62;&#62;`} />



## ListPageProps

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/page/list-page.tsx" sourceLine="31" packageName="@vendure/dashboard" since="3.3.0" />

**Status: Developer Preview**

```ts title="Signature"
interface ListPageProps<T extends TypedDocumentNode<U, V>, U extends ListQueryShape, V extends ListQueryOptionsShape, AC extends AdditionalColumns<T>> {
    pageId?: string;
    route: AnyRoute | (() => AnyRoute);
    title: string | React.ReactElement;
    listQuery: T;
    deleteMutation?: TypedDocumentNode<any, { id: string }>;
    transformVariables?: (variables: V) => V;
    onSearchTermChange?: (searchTerm: string) => NonNullable<V['options']>['filter'];
    customizeColumns?: CustomizeColumnConfig<T>;
    additionalColumns?: AC;
    defaultColumnOrder?: (keyof ListQueryFields<T> | keyof AC | CustomFieldKeysOfItem<ListQueryFields<T>>)[];
    defaultSort?: SortingState;
    defaultVisibility?: Partial<
        Record<keyof ListQueryFields<T> | keyof AC | CustomFieldKeysOfItem<ListQueryFields<T>>, boolean>
    >;
    children?: React.ReactNode;
    facetedFilters?: FacetedFilterConfig<T>;
    rowActions?: RowAction<ListQueryFields<T>>[];
    transformData?: (data: any[]) => any[];
    setTableOptions?: (table: TableOptions<any>) => TableOptions<any>;
    bulkActions?: BulkAction[];
    registerRefresher?: PaginatedListRefresherRegisterFn;
}
```

<div className="members-wrapper">

### pageId

<MemberInfo kind="property" type={`string`}   />


### route

<MemberInfo kind="property" type={`AnyRoute | (() =&#62; AnyRoute)`}   />


### title

<MemberInfo kind="property" type={`string | React.ReactElement`}   />


### listQuery

<MemberInfo kind="property" type={`T`}   />


### deleteMutation

<MemberInfo kind="property" type={`TypedDocumentNode&#60;any, { id: string }&#62;`}   />


### transformVariables

<MemberInfo kind="property" type={`(variables: V) =&#62; V`}   />


### onSearchTermChange

<MemberInfo kind="property" type={`(searchTerm: string) =&#62; NonNullable&#60;V['options']&#62;['filter']`}   />


### customizeColumns

<MemberInfo kind="property" type={`CustomizeColumnConfig&#60;T&#62;`}   />


### additionalColumns

<MemberInfo kind="property" type={`AC`}   />


### defaultColumnOrder

<MemberInfo kind="property" type={`(keyof ListQueryFields&#60;T&#62; | keyof AC | CustomFieldKeysOfItem&#60;ListQueryFields&#60;T&#62;&#62;)[]`}   />


### defaultSort

<MemberInfo kind="property" type={`SortingState`}   />


### defaultVisibility

<MemberInfo kind="property" type={`Partial&#60;         Record&#60;keyof ListQueryFields&#60;T&#62; | keyof AC | CustomFieldKeysOfItem&#60;ListQueryFields&#60;T&#62;&#62;, boolean&#62;     &#62;`}   />


### children

<MemberInfo kind="property" type={`React.ReactNode`}   />


### facetedFilters

<MemberInfo kind="property" type={`FacetedFilterConfig&#60;T&#62;`}   />


### rowActions

<MemberInfo kind="property" type={`RowAction&#60;ListQueryFields&#60;T&#62;&#62;[]`}   />


### transformData

<MemberInfo kind="property" type={`(data: any[]) =&#62; any[]`}   />


### setTableOptions

<MemberInfo kind="property" type={`(table: TableOptions&#60;any&#62;) =&#62; TableOptions&#60;any&#62;`}   />


### bulkActions

<MemberInfo kind="property" type={`<a href='/reference/dashboard/extensions/data-table#bulkaction'>BulkAction</a>[]`}   />


### registerRefresher

<MemberInfo kind="property" type={`PaginatedListRefresherRegisterFn`}   />




</div>


---

---
title: "PageActionBar"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## PageActionBar

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/layout-engine/page-layout.tsx" sourceLine="275" packageName="@vendure/dashboard" since="3.3.0" />

**Status: Developer Preview**

A component for displaying the main actions for a page. This should be used inside the <a href='/reference/dashboard/components/page#page'>Page</a> component.
It should be used in conjunction with the <a href='/reference/dashboard/components/page-action-bar#pageactionbarleft'>PageActionBarLeft</a> and <a href='/reference/dashboard/components/page-action-bar#pageactionbarright'>PageActionBarRight</a> components
as direct children.

```ts title="Signature"
function PageActionBar(props: Readonly<{ children: React.ReactNode }>): void
```
Parameters

### props

<MemberInfo kind="parameter" type={`Readonly&#60;{ children: React.ReactNode }&#62;`} />



## PageActionBarLeft

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/layout-engine/page-layout.tsx" sourceLine="297" packageName="@vendure/dashboard" since="3.3.0" />

**Status: Developer Preview**

```ts title="Signature"
function PageActionBarLeft(props: Readonly<{ children: React.ReactNode }>): void
```
Parameters

### props

<MemberInfo kind="parameter" type={`Readonly&#60;{ children: React.ReactNode }&#62;`} />



## PageActionBarRight

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/layout-engine/page-layout.tsx" sourceLine="311" packageName="@vendure/dashboard" since="3.3.0" />

**Status: Developer Preview**

```ts title="Signature"
function PageActionBarRight(props: Readonly<{
    children: React.ReactNode;
    dropdownMenuItems?: InlineDropdownItem[];
}>): void
```
Parameters

### props

<MemberInfo kind="parameter" type={`Readonly&#60;{     children: React.ReactNode;     dropdownMenuItems?: InlineDropdownItem[]; }&#62;`} />



---

---
title: "PageBlock"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## PageBlock

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/layout-engine/page-layout.tsx" sourceLine="407" packageName="@vendure/dashboard" since="3.3.0" />

**Status: Developer Preview**

A component for displaying a block of content on a page. This should be used inside the <a href='/reference/dashboard/components/page-layout#pagelayout'>PageLayout</a> component.
It should be provided with a `column` prop to determine which column it should appear in, and a `blockId` prop
to identify the block.

```ts title="Signature"
function PageBlock(props: Readonly<PageBlockProps>): void
```
Parameters

### props

<MemberInfo kind="parameter" type={`Readonly&#60;<a href='/reference/dashboard/components/page-block#pageblockprops'>PageBlockProps</a>&#62;`} />



## PageBlockProps

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/layout-engine/page-layout.tsx" sourceLine="384" packageName="@vendure/dashboard" since="3.3.0" />

**Status: Developer Preview**

```ts title="Signature"
type PageBlockProps = {
    children?: React.ReactNode;
    column: 'main' | 'side';
    blockId?: string;
    title?: React.ReactNode | string;
    description?: React.ReactNode | string;
    className?: string;
}
```

<div className="members-wrapper">

### children

<MemberInfo kind="property" type={`React.ReactNode`}   />


### column

<MemberInfo kind="property" type={`'main' | 'side'`}   />


### blockId

<MemberInfo kind="property" type={`string`}   />


### title

<MemberInfo kind="property" type={`React.ReactNode | string`}   />


### description

<MemberInfo kind="property" type={`React.ReactNode | string`}   />


### className

<MemberInfo kind="property" type={`string`}   />




</div>


## FullWidthPageBlock

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/layout-engine/page-layout.tsx" sourceLine="452" packageName="@vendure/dashboard" since="3.3.0" />

**Status: Developer Preview**

A component for displaying a block of content on a page that takes up the full width of the page.
This should be used inside the <a href='/reference/dashboard/components/page-layout#pagelayout'>PageLayout</a> component.

```ts title="Signature"
function FullWidthPageBlock(props: Readonly<Pick<PageBlockProps, 'children' | 'className' | 'blockId'>>): void
```
Parameters

### props

<MemberInfo kind="parameter" type={`Readonly&#60;Pick&#60;<a href='/reference/dashboard/components/page-block#pageblockprops'>PageBlockProps</a>, 'children' | 'className' | 'blockId'&#62;&#62;`} />



## CustomFieldsPageBlock

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/layout-engine/page-layout.tsx" sourceLine="477" packageName="@vendure/dashboard" since="3.3.0" />

**Status: Developer Preview**

A component for displaying an auto-generated form for custom fields on a page.

```ts title="Signature"
function CustomFieldsPageBlock(props: Readonly<{
    column: 'main' | 'side';
    entityType: string;
    control: Control<any, any>;
}>): void
```
Parameters

### props

<MemberInfo kind="parameter" type={`Readonly&#60;{     column: 'main' | 'side';     entityType: string;     control: Control&#60;any, any&#62;; }&#62;`} />



---

---
title: "PageLayout"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## PageLayout

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/layout-engine/page-layout.tsx" sourceLine="170" packageName="@vendure/dashboard" since="3.3.0" />

**Status: Developer Preview**

This component governs the layout of the contents of a <a href='/reference/dashboard/components/page#page'>Page</a> component.
It should contain all the <a href='/reference/dashboard/components/page-block#pageblock'>PageBlock</a> components that are to be displayed on the page.

```ts title="Signature"
function PageLayout(props: Readonly<PageLayoutProps>): void
```
Parameters

### props

<MemberInfo kind="parameter" type={`Readonly&#60;<a href='/reference/dashboard/components/page-layout#pagelayoutprops'>PageLayoutProps</a>&#62;`} />



## PageLayoutProps

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/layout-engine/page-layout.tsx" sourceLine="140" packageName="@vendure/dashboard" since="3.3.0" />

**Status: Developer Preview**

```ts title="Signature"
type PageLayoutProps = {
    children: React.ReactNode;
    className?: string;
}
```

<div className="members-wrapper">

### children

<MemberInfo kind="property" type={`React.ReactNode`}   />


### className

<MemberInfo kind="property" type={`string`}   />




</div>


---

---
title: "PageTitle"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## PageTitle

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/layout-engine/page-layout.tsx" sourceLine="258" packageName="@vendure/dashboard" since="3.3.0" />

**Status: Developer Preview**

A component for displaying the title of a page. This should be used inside the <a href='/reference/dashboard/components/page#page'>Page</a> component.

```ts title="Signature"
function PageTitle(props: Readonly<{ children: React.ReactNode }>): void
```
Parameters

### props

<MemberInfo kind="parameter" type={`Readonly&#60;{ children: React.ReactNode }&#62;`} />



---

---
title: "Page"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## Page

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/layout-engine/page-layout.tsx" sourceLine="48" packageName="@vendure/dashboard" since="3.3.0" />

**Status: Developer Preview**

This component should be used to wrap _all_ pages in the dashboard. It provides
a consistent layout as well as a context for the slot-based PageBlock system.

The typical hierarchy of a page is as follows:
- `Page`
 - <a href='/reference/dashboard/components/page-title#pagetitle'>PageTitle</a>
 - <a href='/reference/dashboard/components/page-action-bar#pageactionbar'>PageActionBar</a>
 - <a href='/reference/dashboard/components/page-layout#pagelayout'>PageLayout</a>

```ts title="Signature"
function Page(props: Readonly<PageProps>): void
```
Parameters

### props

<MemberInfo kind="parameter" type={`Readonly&#60;PageProps&#62;`} />



---

---
title: "DashboardAlertDefinition"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DashboardAlertDefinition

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/extension-api/types/alerts.ts" sourceLine="10" packageName="@vendure/dashboard" since="3.3.0" />

**Status: Developer Preview**

Allows you to define custom alerts that can be displayed in the dashboard.

```ts title="Signature"
interface DashboardAlertDefinition<TResponse = any> {
    id: string;
    title: string | ((data: TResponse) => string);
    description?: string | ((data: TResponse) => string);
    severity: 'info' | 'warning' | 'error';
    check: () => Promise<TResponse> | TResponse;
    recheckInterval?: number;
    shouldShow?: (data: TResponse) => boolean;
    actions?: Array<{
        label: string;
        onClick: (data: TResponse) => void;
    }>;
}
```

<div className="members-wrapper">

### id

<MemberInfo kind="property" type={`string`}   />

A unique identifier for the alert.
### title

<MemberInfo kind="property" type={`string | ((data: TResponse) =&#62; string)`}   />

The title of the alert. Can be a string or a function that returns a string based on the response data.
### description

<MemberInfo kind="property" type={`string | ((data: TResponse) =&#62; string)`}   />

The description of the alert. Can be a string or a function that returns a string based on the response data.
### severity

<MemberInfo kind="property" type={`'info' | 'warning' | 'error'`}   />

The severity level of the alert.
### check

<MemberInfo kind="property" type={`() =&#62; Promise&#60;TResponse&#62; | TResponse`}   />

A function that checks the condition and returns the response data.
### recheckInterval

<MemberInfo kind="property" type={`number`}   />

The interval in milliseconds to recheck the condition.
### shouldShow

<MemberInfo kind="property" type={`(data: TResponse) =&#62; boolean`}   />

A function that determines whether the alert should be shown based on the response data.
### actions

<MemberInfo kind="property" type={`Array&#60;{         label: string;         onClick: (data: TResponse) =&#62; void;     }&#62;`}   />

Optional actions that can be performed when the alert is shown.


</div>


---

---
title: "DashboardBaseWidgetProps"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DashboardBaseWidgetProps

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/extension-api/types/widgets.ts" sourceLine="10" packageName="@vendure/dashboard" since="3.3.0" />

Base props interface for dashboard widgets.

```ts title="Signature"
type DashboardBaseWidgetProps = PropsWithChildren<{
    id: string;
    title?: string;
    description?: string;
    config?: Record<string, unknown>;
    actions?: React.ReactNode;
}>
```


---

---
title: "DashboardExtension"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DashboardExtension

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/extension-api/extension-api-types.ts" sourceLine="24" packageName="@vendure/dashboard" since="3.3.0" />

**Status: Developer Preview**

This is used to define the routes, widgets, etc. that will be displayed in the dashboard.

```ts title="Signature"
interface DashboardExtension {
    routes?: DashboardRouteDefinition[];
    navSections?: DashboardNavSectionDefinition[];
    pageBlocks?: DashboardPageBlockDefinition[];
    actionBarItems?: DashboardActionBarItem[];
    alerts?: DashboardAlertDefinition[];
    widgets?: DashboardWidgetDefinition[];
    customFormComponents?: DashboardCustomFormComponents;
    dataTables?: DashboardDataTableExtensionDefinition[];
    detailForms?: DashboardDetailFormExtensionDefinition[];
    login?: DashboardLoginExtensions;
}
```

<div className="members-wrapper">

### routes

<MemberInfo kind="property" type={`<a href='/reference/dashboard/extensions/navigation#dashboardroutedefinition'>DashboardRouteDefinition</a>[]`}   />

Allows you to define custom routes such as list or detail views.
### navSections

<MemberInfo kind="property" type={`<a href='/reference/dashboard/extensions/navigation#dashboardnavsectiondefinition'>DashboardNavSectionDefinition</a>[]`}   />

Allows you to define custom nav sections for the dashboard.
### pageBlocks

<MemberInfo kind="property" type={`<a href='/reference/dashboard/extensions/layout#dashboardpageblockdefinition'>DashboardPageBlockDefinition</a>[]`}   />

Allows you to define custom page blocks for any page in the dashboard.
### actionBarItems

<MemberInfo kind="property" type={`<a href='/reference/dashboard/extensions/layout#dashboardactionbaritem'>DashboardActionBarItem</a>[]`}   />

Allows you to define custom action bar items for any page in the dashboard.
### alerts

<MemberInfo kind="property" type={`<a href='/reference/dashboard/extensions/dashboard-alert-definition#dashboardalertdefinition'>DashboardAlertDefinition</a>[]`}   />

Allows you to define custom alerts that can be displayed in the dashboard.
### widgets

<MemberInfo kind="property" type={`<a href='/reference/dashboard/extensions/dashboard-widget-definition#dashboardwidgetdefinition'>DashboardWidgetDefinition</a>[]`}   />

Allows you to define custom routes for the dashboard, which will render the
given components and optionally also add a nav menu item.
### customFormComponents

<MemberInfo kind="property" type={`<a href='/reference/dashboard/extensions/form-components#dashboardcustomformcomponents'>DashboardCustomFormComponents</a>`}   />

Unified registration for custom form custom field components.
### dataTables

<MemberInfo kind="property" type={`<a href='/reference/dashboard/extensions/data-table#dashboarddatatableextensiondefinition'>DashboardDataTableExtensionDefinition</a>[]`}   />

Allows you to customize aspects of existing data tables in the dashboard.
### detailForms

<MemberInfo kind="property" type={`<a href='/reference/dashboard/extensions/detail-forms#dashboarddetailformextensiondefinition'>DashboardDetailFormExtensionDefinition</a>[]`}   />

Allows you to customize the detail form for any page in the dashboard.
### login

<MemberInfo kind="property" type={`<a href='/reference/dashboard/extensions/login#dashboardloginextensions'>DashboardLoginExtensions</a>`}   />

Allows you to customize the login page with custom components.


</div>


---

---
title: "DashboardWidgetDefinition"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DashboardWidgetDefinition

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/extension-api/types/widgets.ts" sourceLine="62" packageName="@vendure/dashboard" since="3.3.0" />

**Status: Developer Preview**

Defines a dashboard widget that can be added to the dashboard.

```ts title="Signature"
type DashboardWidgetDefinition = {
    id: string;
    name: string;
    component: React.ComponentType<DashboardBaseWidgetProps>;
    defaultSize: { w: number; h: number; x?: number; y?: number };
    minSize?: { w: number; h: number };
    maxSize?: { w: number; h: number };
}
```

<div className="members-wrapper">

### id

<MemberInfo kind="property" type={`string`}   />

A unique identifier for the widget.
### name

<MemberInfo kind="property" type={`string`}   />

The display name of the widget.
### component

<MemberInfo kind="property" type={`React.ComponentType&#60;<a href='/reference/dashboard/extensions/dashboard-base-widget-props#dashboardbasewidgetprops'>DashboardBaseWidgetProps</a>&#62;`}   />

The React component that renders the widget.
### defaultSize

<MemberInfo kind="property" type={`{ w: number; h: number; x?: number; y?: number }`}   />

The default size and position of the widget.
### minSize

<MemberInfo kind="property" type={`{ w: number; h: number }`}   />

The minimum size constraints for the widget.
### maxSize

<MemberInfo kind="property" type={`{ w: number; h: number }`}   />

The maximum size constraints for the widget.


</div>


---

---
title: "DashboardWidgetInstance"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DashboardWidgetInstance

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/extension-api/types/widgets.ts" sourceLine="25" packageName="@vendure/dashboard" since="3.3.0" />

Represents an instance of a dashboard widget with its layout and configuration.

```ts title="Signature"
type DashboardWidgetInstance = {
    id: string;
    widgetId: string;
    layout: {
        x: number;
        y: number;
        w: number;
        h: number;
    };
    config?: Record<string, unknown>;
}
```

<div className="members-wrapper">

### id

<MemberInfo kind="property" type={`string`}   />

A unique identifier for the widget instance.
### widgetId

<MemberInfo kind="property" type={`string`}   />

The ID of the widget definition this instance is based on.
### layout

<MemberInfo kind="property" type={`{         x: number;         y: number;         w: number;         h: number;     }`}   />

The layout configuration for the widget.
### config

<MemberInfo kind="property" type={`Record&#60;string, unknown&#62;`}   />

Optional configuration data for the widget.


</div>


---

---
title: "DataTable"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DashboardDataTableDisplayComponent

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/extension-api/types/data-table.ts" sourceLine="13" packageName="@vendure/dashboard" since="3.4.0" />

Allows you to define custom display components for specific columns in data tables.
The pageId is already defined in the data table extension, so only the column name is needed.

```ts title="Signature"
interface DashboardDataTableDisplayComponent {
    column: string;
    component: React.ComponentType<{ value: any; [key: string]: any }>;
}
```

<div className="members-wrapper">

### column

<MemberInfo kind="property" type={`string`}   />

The name of the column where this display component should be used.
### component

<MemberInfo kind="property" type={`React.ComponentType&#60;{ value: any; [key: string]: any }&#62;`}   />

The React component that will be rendered as the display.
It should accept `value` and other standard display props.


</div>


## BulkAction

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/extension-api/types/data-table.ts" sourceLine="46" packageName="@vendure/dashboard" since="3.4.0" />

**Status: Developer Preview**

A bulk action is a component that will be rendered in the bulk actions dropdown.

```ts title="Signature"
type BulkAction = {
    order?: number;
    component: BulkActionComponent<any>;
}
```

<div className="members-wrapper">

### order

<MemberInfo kind="property" type={`number`}   />

Optional order number to control the position of this bulk action in the dropdown.
A larger number will appear lower in the list.
### component

<MemberInfo kind="property" type={`BulkActionComponent&#60;any&#62;`}   />

The React component that will be rendered as the bulk action item.


</div>


## DashboardDataTableExtensionDefinition

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/extension-api/types/data-table.ts" sourceLine="68" packageName="@vendure/dashboard" since="3.4.0" />

This allows you to customize aspects of existing data tables in the dashboard.

```ts title="Signature"
interface DashboardDataTableExtensionDefinition {
    pageId: string;
    blockId?: string;
    bulkActions?: BulkAction[];
    extendListDocument?: string | DocumentNode | (() => DocumentNode | string);
    displayComponents?: DashboardDataTableDisplayComponent[];
}
```

<div className="members-wrapper">

### pageId

<MemberInfo kind="property" type={`string`}   />

The ID of the page where the data table is located, e.g. `'product-list'`, `'order-list'`.
### blockId

<MemberInfo kind="property" type={`string`}   />

The ID of the data table block. Defaults to `'list-table'`, which is the default blockId
for the standard list pages. However, some other pages may use a different blockId,
such as `'product-variants-table'` on the `'product-detail'` page.
### bulkActions

<MemberInfo kind="property" type={`<a href='/reference/dashboard/extensions/data-table#bulkaction'>BulkAction</a>[]`}   />

An array of additional bulk actions that will be available on the data table.
### extendListDocument

<MemberInfo kind="property" type={`string | DocumentNode | (() =&#62; DocumentNode | string)`}   />

Allows you to extend the list document for the data table.
### displayComponents

<MemberInfo kind="property" type={`<a href='/reference/dashboard/extensions/data-table#dashboarddatatabledisplaycomponent'>DashboardDataTableDisplayComponent</a>[]`}   />

Custom display components for specific columns in the data table.


</div>


---

---
title: "DefineDashboardExtension"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## defineDashboardExtension

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/extension-api/define-dashboard-extension.ts" sourceLine="38" packageName="@vendure/dashboard" since="3.3.0" />

**Status: Developer Preview**

The main entry point for extensions to the React-based dashboard.

```ts title="Signature"
function defineDashboardExtension(extension: DashboardExtension): void
```
Parameters

### extension

<MemberInfo kind="parameter" type={`<a href='/reference/dashboard/extensions/dashboard-extension#dashboardextension'>DashboardExtension</a>`} />



---

---
title: "DetailForms"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DashboardDetailFormInputComponent

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/extension-api/types/detail-forms.ts" sourceLine="13" packageName="@vendure/dashboard" since="3.4.0" />

Allows you to define custom input components for specific fields in detail forms.
The pageId is already defined in the detail form extension, so only the blockId and field are needed.

```ts title="Signature"
interface DashboardDetailFormInputComponent {
    blockId: string;
    field: string;
    component: DashboardFormComponent;
}
```

<div className="members-wrapper">

### blockId

<MemberInfo kind="property" type={`string`}   />

The ID of the block where this input component should be used.
### field

<MemberInfo kind="property" type={`string`}   />

The name of the field where this input component should be used.
### component

<MemberInfo kind="property" type={`<a href='/reference/dashboard/forms/dashboard-form-component#dashboardformcomponent'>DashboardFormComponent</a>`}   />

The React component that will be rendered as the input.
It should accept `value`, `onChange`, and other standard input props.


</div>


## DashboardDetailFormExtensionDefinition

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/extension-api/types/detail-forms.ts" sourceLine="41" packageName="@vendure/dashboard" since="3.4.0" />

Allows you to extend existing detail forms (e.g. on the product detail or customer detail pages)
with custom GraphQL queries, input components, and display components.

```ts title="Signature"
interface DashboardDetailFormExtensionDefinition {
    pageId: string;
    extendDetailDocument?: string | DocumentNode | (() => DocumentNode | string);
    inputs?: DashboardDetailFormInputComponent[];
}
```

<div className="members-wrapper">

### pageId

<MemberInfo kind="property" type={`string`}   />

The ID of the page where the detail form is located, e.g. `'product-detail'`, `'order-detail'`.
### extendDetailDocument

<MemberInfo kind="property" type={`string | DocumentNode | (() =&#62; DocumentNode | string)`}   />

Extends the GraphQL query used to fetch data for the detail page, allowing you to add additional
fields that can be used by custom input or display components.
### inputs

<MemberInfo kind="property" type={`<a href='/reference/dashboard/extensions/detail-forms#dashboarddetailforminputcomponent'>DashboardDetailFormInputComponent</a>[]`}   />

Custom input components for specific fields in the detail form.


</div>


---

---
title: "FormComponents"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DashboardCustomFormComponent

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/extension-api/types/form-components.ts" sourceLine="11" packageName="@vendure/dashboard" since="3.4.0" />

Allows you to define custom form components for custom fields in the dashboard.

```ts title="Signature"
interface DashboardCustomFormComponent {
    id: string;
    component: DashboardFormComponent;
}
```

<div className="members-wrapper">

### id

<MemberInfo kind="property" type={`string`}   />

A unique identifier for the custom form component. It is a good practice to namespace
these IDs to avoid naming collisions, for example `"my-plugin.markdown-editor"`.
### component

<MemberInfo kind="property" type={`<a href='/reference/dashboard/forms/dashboard-form-component#dashboardformcomponent'>DashboardFormComponent</a>`}   />

The React component that will be rendered as the custom form input.


</div>


## DashboardCustomFormComponents

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/extension-api/types/form-components.ts" sourceLine="34" packageName="@vendure/dashboard" since="3.4.0" />

Interface for registering custom field components in the dashboard.
For input and display components, use the co-located approach with detailForms.

```ts title="Signature"
interface DashboardCustomFormComponents {
    customFields?: DashboardCustomFormComponent[];
}
```

<div className="members-wrapper">

### customFields

<MemberInfo kind="property" type={`<a href='/reference/dashboard/extensions/form-components#dashboardcustomformcomponent'>DashboardCustomFormComponent</a>[]`}   />

Custom form components for custom fields. These are used when rendering
custom fields in forms.


</div>


---

---
title: "Extensions"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "Layout"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DashboardActionBarItem

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/extension-api/types/layout.ts" sourceLine="18" packageName="@vendure/dashboard" since="3.3.0" />

Allows you to define custom action bar items for any page in the dashboard.

```ts title="Signature"
interface DashboardActionBarItem {
    pageId: string;
    component: React.FunctionComponent<{ context: PageContextValue }>;
    type?: 'button' | 'dropdown';
    requiresPermission?: string | string[];
}
```

<div className="members-wrapper">

### pageId

<MemberInfo kind="property" type={`string`}   />

The ID of the page where the action bar item should be displayed.
### component

<MemberInfo kind="property" type={`React.FunctionComponent&#60;{ context: PageContextValue }&#62;`}   />

A React component that will be rendered in the action bar.
### type

<MemberInfo kind="property" type={`'button' | 'dropdown'`} default={`'button'`}   />

The type of action bar item to display. Defaults to `button`.
The 'dropdown' type is used to display the action bar item as a dropdown menu item.

When using the dropdown type, use a suitable [dropdown item](https://ui.shadcn.com/docs/components/dropdown-menu)
component, such as:

```tsx
import { DropdownMenuItem } from '@vendure/dashboard';

// ...

{
  component: () => <DropdownMenuItem>My Item</DropdownMenuItem>
}
```
### requiresPermission

<MemberInfo kind="property" type={`string | string[]`}   />

Any permissions that are required to display this action bar item.


</div>


## PageBlockLocation

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/extension-api/types/layout.ts" sourceLine="69" packageName="@vendure/dashboard" since="3.3.0" />

The location of a page block in the dashboard. The location can be found by turning on
"developer mode" in the dashboard user menu (bottom left corner) and then
clicking the `< />` icon when hovering over a page block.

```ts title="Signature"
type PageBlockLocation = {
    pageId: string;
    position: PageBlockPosition;
    column: 'main' | 'side';
}
```

<div className="members-wrapper">

### pageId

<MemberInfo kind="property" type={`string`}   />


### position

<MemberInfo kind="property" type={`PageBlockPosition`}   />


### column

<MemberInfo kind="property" type={`'main' | 'side'`}   />




</div>


## DashboardPageBlockDefinition

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/extension-api/types/layout.ts" sourceLine="84" packageName="@vendure/dashboard" since="3.3.0" />

This allows you to insert a custom component into a specific location
on any page in the dashboard.

```ts title="Signature"
interface DashboardPageBlockDefinition {
    id: string;
    title?: React.ReactNode;
    location: PageBlockLocation;
    component: React.FunctionComponent<{ context: PageContextValue }>;
    requiresPermission?: string | string[];
}
```

<div className="members-wrapper">

### id

<MemberInfo kind="property" type={`string`}   />


### title

<MemberInfo kind="property" type={`React.ReactNode`}   />


### location

<MemberInfo kind="property" type={`<a href='/reference/dashboard/extensions/layout#pageblocklocation'>PageBlockLocation</a>`}   />


### component

<MemberInfo kind="property" type={`React.FunctionComponent&#60;{ context: PageContextValue }&#62;`}   />


### requiresPermission

<MemberInfo kind="property" type={`string | string[]`}   />




</div>


---

---
title: "Login"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## LoginLogoExtension

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/extension-api/types/login.ts" sourceLine="11" packageName="@vendure/dashboard" since="3.4.0" />

Defines a custom logo component for the login page.

```ts title="Signature"
interface LoginLogoExtension {
    component: React.ComponentType;
}
```

<div className="members-wrapper">

### component

<MemberInfo kind="property" type={`React.ComponentType`}   />

A React component that will replace the default Vendure logo.


</div>


## LoginBeforeFormExtension

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/extension-api/types/login.ts" sourceLine="27" packageName="@vendure/dashboard" since="3.4.0" />

Defines content to display before the login form.

```ts title="Signature"
interface LoginBeforeFormExtension {
    component: React.ComponentType;
}
```

<div className="members-wrapper">

### component

<MemberInfo kind="property" type={`React.ComponentType`}   />

A React component that will be rendered before the login form.


</div>


## LoginAfterFormExtension

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/extension-api/types/login.ts" sourceLine="43" packageName="@vendure/dashboard" since="3.4.0" />

Defines content to display after the login form.

```ts title="Signature"
interface LoginAfterFormExtension {
    component: React.ComponentType;
}
```

<div className="members-wrapper">

### component

<MemberInfo kind="property" type={`React.ComponentType`}   />

A React component that will be rendered after the login form.


</div>


## LoginImageExtension

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/extension-api/types/login.ts" sourceLine="59" packageName="@vendure/dashboard" since="3.4.0" />

Defines a custom login image component that replaces the default image panel.

```ts title="Signature"
interface LoginImageExtension {
    component: React.ComponentType;
}
```

<div className="members-wrapper">

### component

<MemberInfo kind="property" type={`React.ComponentType`}   />

A React component that will replace the default login image panel.


</div>


## DashboardLoginExtensions

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/extension-api/types/login.ts" sourceLine="75" packageName="@vendure/dashboard" since="3.4.0" />

Defines all available login page extensions.

```ts title="Signature"
interface DashboardLoginExtensions {
    logo?: LoginLogoExtension;
    beforeForm?: LoginBeforeFormExtension;
    afterForm?: LoginAfterFormExtension;
    loginImage?: LoginImageExtension;
}
```

<div className="members-wrapper">

### logo

<MemberInfo kind="property" type={`<a href='/reference/dashboard/extensions/login#loginlogoextension'>LoginLogoExtension</a>`}   />

Custom logo component to replace the default Vendure logo.
### beforeForm

<MemberInfo kind="property" type={`<a href='/reference/dashboard/extensions/login#loginbeforeformextension'>LoginBeforeFormExtension</a>`}   />

Component to render before the login form.
### afterForm

<MemberInfo kind="property" type={`<a href='/reference/dashboard/extensions/login#loginafterformextension'>LoginAfterFormExtension</a>`}   />

Component to render after the login form.
### loginImage

<MemberInfo kind="property" type={`<a href='/reference/dashboard/extensions/login#loginimageextension'>LoginImageExtension</a>`}   />

Custom login image component to replace the default image panel.


</div>


---

---
title: "Navigation"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DashboardRouteDefinition

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/extension-api/types/navigation.ts" sourceLine="15" packageName="@vendure/dashboard" since="3.4.0" />

Defines a custom route for the dashboard with optional navigation menu integration.

```ts title="Signature"
interface DashboardRouteDefinition {
    component: (route: AnyRoute) => React.ReactNode;
    path: string;
    navMenuItem?: Partial<NavMenuItem> & { sectionId: string };
    loader?: RouteOptions['loader'];
}
```

<div className="members-wrapper">

### component

<MemberInfo kind="property" type={`(route: AnyRoute) =&#62; React.ReactNode`}   />

The React component that will be rendered for this route.
### path

<MemberInfo kind="property" type={`string`}   />

The URL path for this route, e.g. '/my-custom-page'.
### navMenuItem

<MemberInfo kind="property" type={`Partial&#60;<a href='/reference/admin-ui-api/nav-menu/nav-menu-item#navmenuitem'>NavMenuItem</a>&#62; &#38; { sectionId: string }`}   />

Optional navigation menu item configuration to add this route to the nav menu
on the left side of the dashboard.
### loader

<MemberInfo kind="property" type={`RouteOptions['loader']`}   />

Optional loader function to fetch data before the route renders.
The value is a Tanstack Router
[loader function](https://tanstack.com/router/latest/docs/framework/react/guide/data-loading#route-loaders)


</div>


## DashboardNavSectionDefinition

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/extension-api/types/navigation.ts" sourceLine="49" packageName="@vendure/dashboard" since="3.4.0" />

Defines a custom navigation section in the dashboard sidebar.

```ts title="Signature"
interface DashboardNavSectionDefinition {
    id: string;
    title: string;
    icon?: LucideIcon;
    order?: number;
}
```

<div className="members-wrapper">

### id

<MemberInfo kind="property" type={`string`}   />

A unique identifier for the navigation section.
### title

<MemberInfo kind="property" type={`string`}   />

The display title for the navigation section.
### icon

<MemberInfo kind="property" type={`LucideIcon`}   />

Optional icon to display next to the section title. The icons should
be imported from `'lucide-react'`.

*Example*

```ts
import { PlusIcon } from 'lucide-react';
```
### order

<MemberInfo kind="property" type={`number`}   />

Optional order number to control the position of this section in the sidebar.


</div>


---

---
title: "DashboardFormComponent"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DashboardFormComponent

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/form-engine/form-engine-types.ts" sourceLine="161" packageName="@vendure/dashboard" />

This is the common type for all custom form components registered for:

- custom fields
- configurable operation args
- detail page fields

Here's a simple example:

```ts
import { DashboardFormComponent, Input } from '@vendure/dashboard';

const MyComponent: DashboardFormComponent = (props) => {
    return <Input value={props.value}
                  onChange={props.onChange}
                  onBlur={props.onBlur}
                  name={props.name}
                  disabled={props.disabled}
                  ref={props.ref}
                  />;
};
```

```ts title="Signature"
type DashboardFormComponent = React.ComponentType<DashboardFormComponentProps> & {
    metadata?: DashboardFormComponentMetadata;
}
```


## DashboardFormComponentProps

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/form-engine/form-engine-types.ts" sourceLine="91" packageName="@vendure/dashboard" />

Props that get passed to all form input components. They are based on the
controller props used by the underlying `react-hook-form`, i.e.:

```ts
export type ControllerRenderProps = {
    onChange: (event: any) => void;
    onBlur: () => void;
    value: any;
    disabled?: boolean;
    name: string;
    ref: RefCallBack;
};
```

in addition, they can optionally be passed a `fieldDef` prop if the
component is used in the context of a custom field or configurable operation arg.

The `fieldDef` arg, when present, has the following shape:

```ts
export type ConfigurableArgDef = {
    defaultValue: any
    description: string | null
    label: string | null
    list: boolean
    name: string
    required: boolean
    type: string
    ui: any
}
```

```ts title="Signature"
type DashboardFormComponentProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>> = ControllerRenderProps<TFieldValues, TName> & {
    fieldDef?: ConfigurableFieldDef;
}
```


## DashboardFormComponentMetadata

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/form-engine/form-engine-types.ts" sourceLine="122" packageName="@vendure/dashboard" />

Metadata which can be defined on a <a href='/reference/dashboard/forms/dashboard-form-component#dashboardformcomponent'>DashboardFormComponent</a> which
provides additional information about how the dashboard should render the
component.

The metadata is defined by adding the static property on the component:

*Example*

```ts
export const MyCustomInput: DashboardFormComponent = props => {
  // implementation omitted
}

// highlight-start
MyCustomInput.metadata = {
  isListInput: true
}
// highlight-end
```

```ts title="Signature"
type DashboardFormComponentMetadata = {
    isListInput?: boolean | 'dynamic';
    isFullWidth?: boolean;
}
```

<div className="members-wrapper">

### isListInput

<MemberInfo kind="property" type={`boolean | 'dynamic'`}   />

Defines whether this form component is designed to handle list inputs.
If set to `'dynamic'`, it means the component has internal logic that can
handle both lists and single values.
### isFullWidth

<MemberInfo kind="property" type={`boolean`}   />




</div>


---

---
title: "Forms"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "Hooks"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "UseAuth"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## useAuth

<GenerationInfo sourceFile="packages/dashboard/src/lib/hooks/use-auth.tsx" sourceLine="17" packageName="@vendure/dashboard" since="3.3.0" />

**Status: Developer Preview**

Provides access to the <a href='/reference/dashboard/hooks/use-channel#channelcontext'>ChannelContext</a> which contains information
about the active channel.

```ts title="Signature"
function useAuth(): void
```


## AuthContext

<GenerationInfo sourceFile="packages/dashboard/src/lib/providers/auth.tsx" sourceLine="16" packageName="@vendure/dashboard" since="3.3.0" />

**Status: Developer Preview**

```ts title="Signature"
interface AuthContext {
    status: 'initial' | 'authenticated' | 'verifying' | 'unauthenticated';
    authenticationError?: string;
    isAuthenticated: boolean;
    login: (username: string, password: string, onSuccess?: () => void) => void;
    logout: (onSuccess?: () => void) => Promise<void>;
    user: ResultOf<typeof CurrentUserQuery>['activeAdministrator'] | undefined;
    channels: NonNullable<ResultOf<typeof CurrentUserQuery>['me']>['channels'] | undefined;
}
```

<div className="members-wrapper">

### status

<MemberInfo kind="property" type={`'initial' | 'authenticated' | 'verifying' | 'unauthenticated'`}   />


### authenticationError

<MemberInfo kind="property" type={`string`}   />


### isAuthenticated

<MemberInfo kind="property" type={`boolean`}   />


### login

<MemberInfo kind="property" type={`(username: string, password: string, onSuccess?: () =&#62; void) =&#62; void`}   />


### logout

<MemberInfo kind="property" type={`(onSuccess?: () =&#62; void) =&#62; Promise&#60;void&#62;`}   />


### user

<MemberInfo kind="property" type={`ResultOf&#60;typeof CurrentUserQuery&#62;['activeAdministrator'] | undefined`}   />


### channels

<MemberInfo kind="property" type={`NonNullable&#60;ResultOf&#60;typeof CurrentUserQuery&#62;['me']&#62;['channels'] | undefined`}   />




</div>


---

---
title: "UseChannel"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## useChannel

<GenerationInfo sourceFile="packages/dashboard/src/lib/hooks/use-channel.ts" sourceLine="19" packageName="@vendure/dashboard" since="3.3.0" />

**Status: Developer Preview**

Provides access to the <a href='/reference/dashboard/hooks/use-channel#channelcontext'>ChannelContext</a> which contains information
about the active channel.

```ts title="Signature"
function useChannel(): void
```


## ChannelContext

<GenerationInfo sourceFile="packages/dashboard/src/lib/providers/channel-provider.tsx" sourceLine="53" packageName="@vendure/dashboard" since="3.3.0" />

**Status: Developer Preview**

```ts title="Signature"
interface ChannelContext {
    activeChannel: ActiveChannel | undefined;
    channels: Channel[];
    selectedChannelId: string | undefined;
    selectedChannel: Channel | undefined;
    isLoading: boolean;
    setSelectedChannel: (channelId: string) => void;
}
```

<div className="members-wrapper">

### activeChannel

<MemberInfo kind="property" type={`ActiveChannel | undefined`}   />


### channels

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/channel#channel'>Channel</a>[]`}   />


### selectedChannelId

<MemberInfo kind="property" type={`string | undefined`}   />


### selectedChannel

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/channel#channel'>Channel</a> | undefined`}   />


### isLoading

<MemberInfo kind="property" type={`boolean`}   />


### setSelectedChannel

<MemberInfo kind="property" type={`(channelId: string) =&#62; void`}   />




</div>


---

---
title: "UseDetailPage"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## useDetailPage

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/page/use-detail-page.ts" sourceLine="239" packageName="@vendure/dashboard" since="3.3.0" />

**Status: Developer Preview**

This hook is used to create an entity detail page which can read
and update an entity.

*Example*

```ts
const { form, submitHandler, entity, isPending, resetForm } = useDetailPage({
    queryDocument: paymentMethodDetailDocument,
    createDocument: createPaymentMethodDocument,
    updateDocument: updatePaymentMethodDocument,
    setValuesForUpdate: entity => {
        return {
            id: entity.id,
            enabled: entity.enabled,
            name: entity.name,
            code: entity.code,
            description: entity.description,
            checker: entity.checker?.code
                ? {
                      code: entity.checker?.code,
                      arguments: entity.checker?.args,
                  }
                : null,
            handler: entity.handler?.code
                ? {
                      code: entity.handler?.code,
                      arguments: entity.handler?.args,
                  }
                : null,
            translations: entity.translations.map(translation => ({
                id: translation.id,
                languageCode: translation.languageCode,
                name: translation.name,
                description: translation.description,
            })),
            customFields: entity.customFields,
        };
    },
    transformCreateInput: input => {
        return {
            ...input,
            checker: input.checker?.code ? input.checker : undefined,
            handler: input.handler,
        };
    },
    params: { id: params.id },
    onSuccess: async data => {
        toast.success(i18n.t('Successfully updated payment method'));
        resetForm();
        if (creatingNewEntity) {
            await navigate({ to: `../$id`, params: { id: data.id } });
        }
    },
    onError: err => {
        toast.error(i18n.t('Failed to update payment method'), {
            description: err instanceof Error ? err.message : 'Unknown error',
        });
    },
});
```

```ts title="Signature"
function useDetailPage<T extends TypedDocumentNode<any, any>, C extends TypedDocumentNode<any, any>, U extends TypedDocumentNode<any, any>, EntityField extends keyof ResultOf<T> = keyof ResultOf<T>, VarNameUpdate extends keyof VariablesOf<U> = 'input', VarNameCreate extends keyof VariablesOf<C> = 'input'>(options: DetailPageOptions<T, C, U, EntityField, VarNameCreate, VarNameUpdate>): UseDetailPageResult<T, U, EntityField>
```
Parameters

### options

<MemberInfo kind="parameter" type={`<a href='/reference/dashboard/hooks/use-detail-page#detailpageoptions'>DetailPageOptions</a>&#60;T, C, U, EntityField, VarNameCreate, VarNameUpdate&#62;`} />



## DetailPageOptions

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/page/use-detail-page.ts" sourceLine="46" packageName="@vendure/dashboard" since="3.3.0" />

**Status: Developer Preview**

```ts title="Signature"
interface DetailPageOptions<T extends TypedDocumentNode<any, any>, C extends TypedDocumentNode<any, any>, U extends TypedDocumentNode<any, any>, EntityField extends keyof ResultOf<T> = DetailEntityPath<T>, VarNameCreate extends keyof VariablesOf<C> = 'input', VarNameUpdate extends keyof VariablesOf<U> = 'input'> {
    pageId?: string;
    queryDocument: T;
    entityField?: EntityField;
    params: {
        id: string;
    };
    entityName?: string;
    createDocument?: C;
    updateDocument?: U;
    setValuesForUpdate: (entity: NonNullable<ResultOf<T>[EntityField]>) => VariablesOf<U>[VarNameUpdate];
    transformCreateInput?: (input: VariablesOf<C>[VarNameCreate]) => VariablesOf<C>[VarNameCreate];
    transformUpdateInput?: (input: VariablesOf<U>[VarNameUpdate]) => VariablesOf<U>[VarNameUpdate];
    onSuccess?: (entity: ResultOf<C>[keyof ResultOf<C>] | ResultOf<U>[keyof ResultOf<U>]) => void;
    onError?: (error: unknown) => void;
}
```

<div className="members-wrapper">

### pageId

<MemberInfo kind="property" type={`string`}   />

The page id. This is optional, but if provided, it will be used to
identify the page when extending the detail page query
### queryDocument

<MemberInfo kind="property" type={`T`}   />

The query document to fetch the entity.
### entityField

<MemberInfo kind="property" type={`EntityField`}   />

The field of the query document that contains the entity.
### params

<MemberInfo kind="property" type={`{         id: string;     }`}   />

The parameters used to identify the entity.
### entityName

<MemberInfo kind="property" type={`string`}   />

The entity type name for custom field configuration lookup.
Required to filter out readonly custom fields before mutations.
If not provided, the function will try to infer it from the query document.
### createDocument

<MemberInfo kind="property" type={`C`}   />

The document to create the entity.
### updateDocument

<MemberInfo kind="property" type={`U`}   />

The document to update the entity.
### setValuesForUpdate

<MemberInfo kind="property" type={`(entity: NonNullable&#60;ResultOf&#60;T&#62;[EntityField]&#62;) =&#62; VariablesOf&#60;U&#62;[VarNameUpdate]`}   />

The function to set the values for the update document.
### transformCreateInput

<MemberInfo kind="property" type={`(input: VariablesOf&#60;C&#62;[VarNameCreate]) =&#62; VariablesOf&#60;C&#62;[VarNameCreate]`}   />


### transformUpdateInput

<MemberInfo kind="property" type={`(input: VariablesOf&#60;U&#62;[VarNameUpdate]) =&#62; VariablesOf&#60;U&#62;[VarNameUpdate]`}   />


### onSuccess

<MemberInfo kind="property" type={`(entity: ResultOf&#60;C&#62;[keyof ResultOf&#60;C&#62;] | ResultOf&#60;U&#62;[keyof ResultOf&#60;U&#62;]) =&#62; void`}   />

The function to call when the update is successful.
### onError

<MemberInfo kind="property" type={`(error: unknown) =&#62; void`}   />

The function to call when the update is successful.


</div>


## UseDetailPageResult

<GenerationInfo sourceFile="packages/dashboard/src/lib/framework/page/use-detail-page.ts" sourceLine="157" packageName="@vendure/dashboard" since="3.3.0" />

**Status: Developer Preview**

```ts title="Signature"
interface UseDetailPageResult<T extends TypedDocumentNode<any, any>, U extends TypedDocumentNode<any, any>, EntityField extends keyof ResultOf<T>> {
    form: UseFormReturn<RemoveNullFields<VariablesOf<U>['input']>>;
    submitHandler: (event: FormEvent<HTMLFormElement>) => void;
    entity?: DetailPageEntity<T, EntityField>;
    isPending: boolean;
    refreshEntity: () => void;
    resetForm: () => void;
}
```

<div className="members-wrapper">

### form

<MemberInfo kind="property" type={`UseFormReturn&#60;RemoveNullFields&#60;VariablesOf&#60;U&#62;['input']&#62;&#62;`}   />


### submitHandler

<MemberInfo kind="property" type={`(event: FormEvent&#60;HTMLFormElement&#62;) =&#62; void`}   />


### entity

<MemberInfo kind="property" type={`DetailPageEntity&#60;T, EntityField&#62;`}   />


### isPending

<MemberInfo kind="property" type={`boolean`}   />


### refreshEntity

<MemberInfo kind="property" type={`() =&#62; void`}   />


### resetForm

<MemberInfo kind="property" type={`() =&#62; void`}   />




</div>


---

---
title: "UseLocalFormat"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## useLocalFormat

<GenerationInfo sourceFile="packages/dashboard/src/lib/hooks/use-local-format.ts" sourceLine="26" packageName="@vendure/dashboard" />

This hook is used to format numbers and currencies using the configured language and
locale of the dashboard app.

*Example*

```ts
const {
         formatCurrency,
         formatNumber,
         formatDate,
         formatLanguageName,
         formatCurrencyName,
         toMajorUnits,
} = useLocalFormat();
```

```ts title="Signature"
function useLocalFormat(): void
```


---

---
title: "UsePermissions"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## usePermissions

<GenerationInfo sourceFile="packages/dashboard/src/lib/hooks/use-permissions.ts" sourceLine="19" packageName="@vendure/dashboard" since="3.3.0" />

**Status: Developer Preview**

Returns a `hasPermissions` function that can be used to determine whether the active user
has the given permissions on the active channel.

```ts title="Signature"
function usePermissions(): void
```


---

---
title: "GraphQL API"
weight: 3
showtoc: false
---

# GraphQL API 

This section contains a description of all queries, mutations and related types available in the Vendure GraphQL API.

The API is split into two distinct endpoints: *Shop* and *Admin*. The Shop API is for storefront client applications, whereas the Admin API is used for administrative tasks.

:::note
All documentation in this section is auto-generated from the Vendure GraphQL schema.
:::



---

---
title: "Admin API"
weight: 4
showtoc: false
---

# GraphQL Admin API

The Admin API is primarily used by the included Admin UI web app to perform administrative tasks such as inventory management, order tracking etc.

:::note
Explore the interactive GraphQL Admin API at [demo.vendure.io/admin-api](https://demo.vendure.io/admin-api)
:::


---

---
title: "Enums"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';



## AdjustmentType

<div class="graphql-code-block">

<div class="graphql-code-line top-level">enum <span class="graphql-code-identifier">AdjustmentType</span> &#123;</div>
<div class="graphql-code-line ">PROMOTION</div>
<div class="graphql-code-line ">DISTRIBUTED_ORDER_PROMOTION</div>
<div class="graphql-code-line ">OTHER</div>
<div class="graphql-code-line top-level">&#125;</div>
</div>

## AssetType

<div class="graphql-code-block">

<div class="graphql-code-line top-level">enum <span class="graphql-code-identifier">AssetType</span> &#123;</div>
<div class="graphql-code-line ">IMAGE</div>
<div class="graphql-code-line ">VIDEO</div>
<div class="graphql-code-line ">BINARY</div>
<div class="graphql-code-line top-level">&#125;</div>
</div>

## CurrencyCode

<div class="graphql-code-block">
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">ISO 4217 currency code</div>

<div class="graphql-code-line comment"></div>

<div class="graphql-code-line comment"></div>
<div class="graphql-code-line comment">"""</div>

<div class="graphql-code-line top-level">enum <span class="graphql-code-identifier">CurrencyCode</span> &#123;</div>
<div class="graphql-code-line comment">"""United Arab Emirates dirham"""</div>
<div class="graphql-code-line ">AED</div>
<div class="graphql-code-line comment">"""Afghan afghani"""</div>
<div class="graphql-code-line ">AFN</div>
<div class="graphql-code-line comment">"""Albanian lek"""</div>
<div class="graphql-code-line ">ALL</div>
<div class="graphql-code-line comment">"""Armenian dram"""</div>
<div class="graphql-code-line ">AMD</div>
<div class="graphql-code-line comment">"""Netherlands Antillean guilder"""</div>
<div class="graphql-code-line ">ANG</div>
<div class="graphql-code-line comment">"""Angolan kwanza"""</div>
<div class="graphql-code-line ">AOA</div>
<div class="graphql-code-line comment">"""Argentine peso"""</div>
<div class="graphql-code-line ">ARS</div>
<div class="graphql-code-line comment">"""Australian dollar"""</div>
<div class="graphql-code-line ">AUD</div>
<div class="graphql-code-line comment">"""Aruban florin"""</div>
<div class="graphql-code-line ">AWG</div>
<div class="graphql-code-line comment">"""Azerbaijani manat"""</div>
<div class="graphql-code-line ">AZN</div>
<div class="graphql-code-line comment">"""Bosnia and Herzegovina convertible mark"""</div>
<div class="graphql-code-line ">BAM</div>
<div class="graphql-code-line comment">"""Barbados dollar"""</div>
<div class="graphql-code-line ">BBD</div>
<div class="graphql-code-line comment">"""Bangladeshi taka"""</div>
<div class="graphql-code-line ">BDT</div>
<div class="graphql-code-line comment">"""Bulgarian lev"""</div>
<div class="graphql-code-line ">BGN</div>
<div class="graphql-code-line comment">"""Bahraini dinar"""</div>
<div class="graphql-code-line ">BHD</div>
<div class="graphql-code-line comment">"""Burundian franc"""</div>
<div class="graphql-code-line ">BIF</div>
<div class="graphql-code-line comment">"""Bermudian dollar"""</div>
<div class="graphql-code-line ">BMD</div>
<div class="graphql-code-line comment">"""Brunei dollar"""</div>
<div class="graphql-code-line ">BND</div>
<div class="graphql-code-line comment">"""Boliviano"""</div>
<div class="graphql-code-line ">BOB</div>
<div class="graphql-code-line comment">"""Brazilian real"""</div>
<div class="graphql-code-line ">BRL</div>
<div class="graphql-code-line comment">"""Bahamian dollar"""</div>
<div class="graphql-code-line ">BSD</div>
<div class="graphql-code-line comment">"""Bhutanese ngultrum"""</div>
<div class="graphql-code-line ">BTN</div>
<div class="graphql-code-line comment">"""Botswana pula"""</div>
<div class="graphql-code-line ">BWP</div>
<div class="graphql-code-line comment">"""Belarusian ruble"""</div>
<div class="graphql-code-line ">BYN</div>
<div class="graphql-code-line comment">"""Belize dollar"""</div>
<div class="graphql-code-line ">BZD</div>
<div class="graphql-code-line comment">"""Canadian dollar"""</div>
<div class="graphql-code-line ">CAD</div>
<div class="graphql-code-line comment">"""Congolese franc"""</div>
<div class="graphql-code-line ">CDF</div>
<div class="graphql-code-line comment">"""Swiss franc"""</div>
<div class="graphql-code-line ">CHF</div>
<div class="graphql-code-line comment">"""Chilean peso"""</div>
<div class="graphql-code-line ">CLP</div>
<div class="graphql-code-line comment">"""Renminbi (Chinese) yuan"""</div>
<div class="graphql-code-line ">CNY</div>
<div class="graphql-code-line comment">"""Colombian peso"""</div>
<div class="graphql-code-line ">COP</div>
<div class="graphql-code-line comment">"""Costa Rican colon"""</div>
<div class="graphql-code-line ">CRC</div>
<div class="graphql-code-line comment">"""Cuban convertible peso"""</div>
<div class="graphql-code-line ">CUC</div>
<div class="graphql-code-line comment">"""Cuban peso"""</div>
<div class="graphql-code-line ">CUP</div>
<div class="graphql-code-line comment">"""Cape Verde escudo"""</div>
<div class="graphql-code-line ">CVE</div>
<div class="graphql-code-line comment">"""Czech koruna"""</div>
<div class="graphql-code-line ">CZK</div>
<div class="graphql-code-line comment">"""Djiboutian franc"""</div>
<div class="graphql-code-line ">DJF</div>
<div class="graphql-code-line comment">"""Danish krone"""</div>
<div class="graphql-code-line ">DKK</div>
<div class="graphql-code-line comment">"""Dominican peso"""</div>
<div class="graphql-code-line ">DOP</div>
<div class="graphql-code-line comment">"""Algerian dinar"""</div>
<div class="graphql-code-line ">DZD</div>
<div class="graphql-code-line comment">"""Egyptian pound"""</div>
<div class="graphql-code-line ">EGP</div>
<div class="graphql-code-line comment">"""Eritrean nakfa"""</div>
<div class="graphql-code-line ">ERN</div>
<div class="graphql-code-line comment">"""Ethiopian birr"""</div>
<div class="graphql-code-line ">ETB</div>
<div class="graphql-code-line comment">"""Euro"""</div>
<div class="graphql-code-line ">EUR</div>
<div class="graphql-code-line comment">"""Fiji dollar"""</div>
<div class="graphql-code-line ">FJD</div>
<div class="graphql-code-line comment">"""Falkland Islands pound"""</div>
<div class="graphql-code-line ">FKP</div>
<div class="graphql-code-line comment">"""Pound sterling"""</div>
<div class="graphql-code-line ">GBP</div>
<div class="graphql-code-line comment">"""Georgian lari"""</div>
<div class="graphql-code-line ">GEL</div>
<div class="graphql-code-line comment">"""Ghanaian cedi"""</div>
<div class="graphql-code-line ">GHS</div>
<div class="graphql-code-line comment">"""Gibraltar pound"""</div>
<div class="graphql-code-line ">GIP</div>
<div class="graphql-code-line comment">"""Gambian dalasi"""</div>
<div class="graphql-code-line ">GMD</div>
<div class="graphql-code-line comment">"""Guinean franc"""</div>
<div class="graphql-code-line ">GNF</div>
<div class="graphql-code-line comment">"""Guatemalan quetzal"""</div>
<div class="graphql-code-line ">GTQ</div>
<div class="graphql-code-line comment">"""Guyanese dollar"""</div>
<div class="graphql-code-line ">GYD</div>
<div class="graphql-code-line comment">"""Hong Kong dollar"""</div>
<div class="graphql-code-line ">HKD</div>
<div class="graphql-code-line comment">"""Honduran lempira"""</div>
<div class="graphql-code-line ">HNL</div>
<div class="graphql-code-line comment">"""Croatian kuna"""</div>
<div class="graphql-code-line ">HRK</div>
<div class="graphql-code-line comment">"""Haitian gourde"""</div>
<div class="graphql-code-line ">HTG</div>
<div class="graphql-code-line comment">"""Hungarian forint"""</div>
<div class="graphql-code-line ">HUF</div>
<div class="graphql-code-line comment">"""Indonesian rupiah"""</div>
<div class="graphql-code-line ">IDR</div>
<div class="graphql-code-line comment">"""Israeli new shekel"""</div>
<div class="graphql-code-line ">ILS</div>
<div class="graphql-code-line comment">"""Indian rupee"""</div>
<div class="graphql-code-line ">INR</div>
<div class="graphql-code-line comment">"""Iraqi dinar"""</div>
<div class="graphql-code-line ">IQD</div>
<div class="graphql-code-line comment">"""Iranian rial"""</div>
<div class="graphql-code-line ">IRR</div>
<div class="graphql-code-line comment">"""Icelandic króna"""</div>
<div class="graphql-code-line ">ISK</div>
<div class="graphql-code-line comment">"""Jamaican dollar"""</div>
<div class="graphql-code-line ">JMD</div>
<div class="graphql-code-line comment">"""Jordanian dinar"""</div>
<div class="graphql-code-line ">JOD</div>
<div class="graphql-code-line comment">"""Japanese yen"""</div>
<div class="graphql-code-line ">JPY</div>
<div class="graphql-code-line comment">"""Kenyan shilling"""</div>
<div class="graphql-code-line ">KES</div>
<div class="graphql-code-line comment">"""Kyrgyzstani som"""</div>
<div class="graphql-code-line ">KGS</div>
<div class="graphql-code-line comment">"""Cambodian riel"""</div>
<div class="graphql-code-line ">KHR</div>
<div class="graphql-code-line comment">"""Comoro franc"""</div>
<div class="graphql-code-line ">KMF</div>
<div class="graphql-code-line comment">"""North Korean won"""</div>
<div class="graphql-code-line ">KPW</div>
<div class="graphql-code-line comment">"""South Korean won"""</div>
<div class="graphql-code-line ">KRW</div>
<div class="graphql-code-line comment">"""Kuwaiti dinar"""</div>
<div class="graphql-code-line ">KWD</div>
<div class="graphql-code-line comment">"""Cayman Islands dollar"""</div>
<div class="graphql-code-line ">KYD</div>
<div class="graphql-code-line comment">"""Kazakhstani tenge"""</div>
<div class="graphql-code-line ">KZT</div>
<div class="graphql-code-line comment">"""Lao kip"""</div>
<div class="graphql-code-line ">LAK</div>
<div class="graphql-code-line comment">"""Lebanese pound"""</div>
<div class="graphql-code-line ">LBP</div>
<div class="graphql-code-line comment">"""Sri Lankan rupee"""</div>
<div class="graphql-code-line ">LKR</div>
<div class="graphql-code-line comment">"""Liberian dollar"""</div>
<div class="graphql-code-line ">LRD</div>
<div class="graphql-code-line comment">"""Lesotho loti"""</div>
<div class="graphql-code-line ">LSL</div>
<div class="graphql-code-line comment">"""Libyan dinar"""</div>
<div class="graphql-code-line ">LYD</div>
<div class="graphql-code-line comment">"""Moroccan dirham"""</div>
<div class="graphql-code-line ">MAD</div>
<div class="graphql-code-line comment">"""Moldovan leu"""</div>
<div class="graphql-code-line ">MDL</div>
<div class="graphql-code-line comment">"""Malagasy ariary"""</div>
<div class="graphql-code-line ">MGA</div>
<div class="graphql-code-line comment">"""Macedonian denar"""</div>
<div class="graphql-code-line ">MKD</div>
<div class="graphql-code-line comment">"""Myanmar kyat"""</div>
<div class="graphql-code-line ">MMK</div>
<div class="graphql-code-line comment">"""Mongolian tögrög"""</div>
<div class="graphql-code-line ">MNT</div>
<div class="graphql-code-line comment">"""Macanese pataca"""</div>
<div class="graphql-code-line ">MOP</div>
<div class="graphql-code-line comment">"""Mauritanian ouguiya"""</div>
<div class="graphql-code-line ">MRU</div>
<div class="graphql-code-line comment">"""Mauritian rupee"""</div>
<div class="graphql-code-line ">MUR</div>
<div class="graphql-code-line comment">"""Maldivian rufiyaa"""</div>
<div class="graphql-code-line ">MVR</div>
<div class="graphql-code-line comment">"""Malawian kwacha"""</div>
<div class="graphql-code-line ">MWK</div>
<div class="graphql-code-line comment">"""Mexican peso"""</div>
<div class="graphql-code-line ">MXN</div>
<div class="graphql-code-line comment">"""Malaysian ringgit"""</div>
<div class="graphql-code-line ">MYR</div>
<div class="graphql-code-line comment">"""Mozambican metical"""</div>
<div class="graphql-code-line ">MZN</div>
<div class="graphql-code-line comment">"""Namibian dollar"""</div>
<div class="graphql-code-line ">NAD</div>
<div class="graphql-code-line comment">"""Nigerian naira"""</div>
<div class="graphql-code-line ">NGN</div>
<div class="graphql-code-line comment">"""Nicaraguan córdoba"""</div>
<div class="graphql-code-line ">NIO</div>
<div class="graphql-code-line comment">"""Norwegian krone"""</div>
<div class="graphql-code-line ">NOK</div>
<div class="graphql-code-line comment">"""Nepalese rupee"""</div>
<div class="graphql-code-line ">NPR</div>
<div class="graphql-code-line comment">"""New Zealand dollar"""</div>
<div class="graphql-code-line ">NZD</div>
<div class="graphql-code-line comment">"""Omani rial"""</div>
<div class="graphql-code-line ">OMR</div>
<div class="graphql-code-line comment">"""Panamanian balboa"""</div>
<div class="graphql-code-line ">PAB</div>
<div class="graphql-code-line comment">"""Peruvian sol"""</div>
<div class="graphql-code-line ">PEN</div>
<div class="graphql-code-line comment">"""Papua New Guinean kina"""</div>
<div class="graphql-code-line ">PGK</div>
<div class="graphql-code-line comment">"""Philippine peso"""</div>
<div class="graphql-code-line ">PHP</div>
<div class="graphql-code-line comment">"""Pakistani rupee"""</div>
<div class="graphql-code-line ">PKR</div>
<div class="graphql-code-line comment">"""Polish złoty"""</div>
<div class="graphql-code-line ">PLN</div>
<div class="graphql-code-line comment">"""Paraguayan guaraní"""</div>
<div class="graphql-code-line ">PYG</div>
<div class="graphql-code-line comment">"""Qatari riyal"""</div>
<div class="graphql-code-line ">QAR</div>
<div class="graphql-code-line comment">"""Romanian leu"""</div>
<div class="graphql-code-line ">RON</div>
<div class="graphql-code-line comment">"""Serbian dinar"""</div>
<div class="graphql-code-line ">RSD</div>
<div class="graphql-code-line comment">"""Russian ruble"""</div>
<div class="graphql-code-line ">RUB</div>
<div class="graphql-code-line comment">"""Rwandan franc"""</div>
<div class="graphql-code-line ">RWF</div>
<div class="graphql-code-line comment">"""Saudi riyal"""</div>
<div class="graphql-code-line ">SAR</div>
<div class="graphql-code-line comment">"""Solomon Islands dollar"""</div>
<div class="graphql-code-line ">SBD</div>
<div class="graphql-code-line comment">"""Seychelles rupee"""</div>
<div class="graphql-code-line ">SCR</div>
<div class="graphql-code-line comment">"""Sudanese pound"""</div>
<div class="graphql-code-line ">SDG</div>
<div class="graphql-code-line comment">"""Swedish krona/kronor"""</div>
<div class="graphql-code-line ">SEK</div>
<div class="graphql-code-line comment">"""Singapore dollar"""</div>
<div class="graphql-code-line ">SGD</div>
<div class="graphql-code-line comment">"""Saint Helena pound"""</div>
<div class="graphql-code-line ">SHP</div>
<div class="graphql-code-line comment">"""Sierra Leonean leone"""</div>
<div class="graphql-code-line ">SLL</div>
<div class="graphql-code-line comment">"""Somali shilling"""</div>
<div class="graphql-code-line ">SOS</div>
<div class="graphql-code-line comment">"""Surinamese dollar"""</div>
<div class="graphql-code-line ">SRD</div>
<div class="graphql-code-line comment">"""South Sudanese pound"""</div>
<div class="graphql-code-line ">SSP</div>
<div class="graphql-code-line comment">"""São Tomé and Príncipe dobra"""</div>
<div class="graphql-code-line ">STN</div>
<div class="graphql-code-line comment">"""Salvadoran colón"""</div>
<div class="graphql-code-line ">SVC</div>
<div class="graphql-code-line comment">"""Syrian pound"""</div>
<div class="graphql-code-line ">SYP</div>
<div class="graphql-code-line comment">"""Swazi lilangeni"""</div>
<div class="graphql-code-line ">SZL</div>
<div class="graphql-code-line comment">"""Thai baht"""</div>
<div class="graphql-code-line ">THB</div>
<div class="graphql-code-line comment">"""Tajikistani somoni"""</div>
<div class="graphql-code-line ">TJS</div>
<div class="graphql-code-line comment">"""Turkmenistan manat"""</div>
<div class="graphql-code-line ">TMT</div>
<div class="graphql-code-line comment">"""Tunisian dinar"""</div>
<div class="graphql-code-line ">TND</div>
<div class="graphql-code-line comment">"""Tongan paʻanga"""</div>
<div class="graphql-code-line ">TOP</div>
<div class="graphql-code-line comment">"""Turkish lira"""</div>
<div class="graphql-code-line ">TRY</div>
<div class="graphql-code-line comment">"""Trinidad and Tobago dollar"""</div>
<div class="graphql-code-line ">TTD</div>
<div class="graphql-code-line comment">"""New Taiwan dollar"""</div>
<div class="graphql-code-line ">TWD</div>
<div class="graphql-code-line comment">"""Tanzanian shilling"""</div>
<div class="graphql-code-line ">TZS</div>
<div class="graphql-code-line comment">"""Ukrainian hryvnia"""</div>
<div class="graphql-code-line ">UAH</div>
<div class="graphql-code-line comment">"""Ugandan shilling"""</div>
<div class="graphql-code-line ">UGX</div>
<div class="graphql-code-line comment">"""United States dollar"""</div>
<div class="graphql-code-line ">USD</div>
<div class="graphql-code-line comment">"""Uruguayan peso"""</div>
<div class="graphql-code-line ">UYU</div>
<div class="graphql-code-line comment">"""Uzbekistan som"""</div>
<div class="graphql-code-line ">UZS</div>
<div class="graphql-code-line comment">"""Venezuelan bolívar soberano"""</div>
<div class="graphql-code-line ">VES</div>
<div class="graphql-code-line comment">"""Vietnamese đồng"""</div>
<div class="graphql-code-line ">VND</div>
<div class="graphql-code-line comment">"""Vanuatu vatu"""</div>
<div class="graphql-code-line ">VUV</div>
<div class="graphql-code-line comment">"""Samoan tala"""</div>
<div class="graphql-code-line ">WST</div>
<div class="graphql-code-line comment">"""CFA franc BEAC"""</div>
<div class="graphql-code-line ">XAF</div>
<div class="graphql-code-line comment">"""East Caribbean dollar"""</div>
<div class="graphql-code-line ">XCD</div>
<div class="graphql-code-line comment">"""CFA franc BCEAO"""</div>
<div class="graphql-code-line ">XOF</div>
<div class="graphql-code-line comment">"""CFP franc (franc Pacifique)"""</div>
<div class="graphql-code-line ">XPF</div>
<div class="graphql-code-line comment">"""Yemeni rial"""</div>
<div class="graphql-code-line ">YER</div>
<div class="graphql-code-line comment">"""South African rand"""</div>
<div class="graphql-code-line ">ZAR</div>
<div class="graphql-code-line comment">"""Zambian kwacha"""</div>
<div class="graphql-code-line ">ZMW</div>
<div class="graphql-code-line comment">"""Zimbabwean dollar"""</div>
<div class="graphql-code-line ">ZWL</div>
<div class="graphql-code-line top-level">&#125;</div>
</div>

## DeletionResult

<div class="graphql-code-block">

<div class="graphql-code-line top-level">enum <span class="graphql-code-identifier">DeletionResult</span> &#123;</div>
<div class="graphql-code-line comment">"""The entity was successfully deleted"""</div>
<div class="graphql-code-line ">DELETED</div>
<div class="graphql-code-line comment">"""Deletion did not take place, reason given in message"""</div>
<div class="graphql-code-line ">NOT_DELETED</div>
<div class="graphql-code-line top-level">&#125;</div>
</div>

## ErrorCode

<div class="graphql-code-block">

<div class="graphql-code-line top-level">enum <span class="graphql-code-identifier">ErrorCode</span> &#123;</div>
<div class="graphql-code-line ">UNKNOWN_ERROR</div>
<div class="graphql-code-line ">MIME_TYPE_ERROR</div>
<div class="graphql-code-line ">LANGUAGE_NOT_AVAILABLE_ERROR</div>
<div class="graphql-code-line ">DUPLICATE_ENTITY_ERROR</div>
<div class="graphql-code-line ">FACET_IN_USE_ERROR</div>
<div class="graphql-code-line ">CHANNEL_DEFAULT_LANGUAGE_ERROR</div>
<div class="graphql-code-line ">SETTLE_PAYMENT_ERROR</div>
<div class="graphql-code-line ">CANCEL_PAYMENT_ERROR</div>
<div class="graphql-code-line ">EMPTY_ORDER_LINE_SELECTION_ERROR</div>
<div class="graphql-code-line ">ITEMS_ALREADY_FULFILLED_ERROR</div>
<div class="graphql-code-line ">INVALID_FULFILLMENT_HANDLER_ERROR</div>
<div class="graphql-code-line ">CREATE_FULFILLMENT_ERROR</div>
<div class="graphql-code-line ">INSUFFICIENT_STOCK_ON_HAND_ERROR</div>
<div class="graphql-code-line ">MULTIPLE_ORDER_ERROR</div>
<div class="graphql-code-line ">CANCEL_ACTIVE_ORDER_ERROR</div>
<div class="graphql-code-line ">PAYMENT_ORDER_MISMATCH_ERROR</div>
<div class="graphql-code-line ">REFUND_ORDER_STATE_ERROR</div>
<div class="graphql-code-line ">NOTHING_TO_REFUND_ERROR</div>
<div class="graphql-code-line ">ALREADY_REFUNDED_ERROR</div>
<div class="graphql-code-line ">QUANTITY_TOO_GREAT_ERROR</div>
<div class="graphql-code-line ">REFUND_AMOUNT_ERROR</div>
<div class="graphql-code-line ">REFUND_STATE_TRANSITION_ERROR</div>
<div class="graphql-code-line ">PAYMENT_STATE_TRANSITION_ERROR</div>
<div class="graphql-code-line ">FULFILLMENT_STATE_TRANSITION_ERROR</div>
<div class="graphql-code-line ">ORDER_MODIFICATION_STATE_ERROR</div>
<div class="graphql-code-line ">NO_CHANGES_SPECIFIED_ERROR</div>
<div class="graphql-code-line ">PAYMENT_METHOD_MISSING_ERROR</div>
<div class="graphql-code-line ">REFUND_PAYMENT_ID_MISSING_ERROR</div>
<div class="graphql-code-line ">MANUAL_PAYMENT_STATE_ERROR</div>
<div class="graphql-code-line ">PRODUCT_OPTION_IN_USE_ERROR</div>
<div class="graphql-code-line ">MISSING_CONDITIONS_ERROR</div>
<div class="graphql-code-line ">NATIVE_AUTH_STRATEGY_ERROR</div>
<div class="graphql-code-line ">INVALID_CREDENTIALS_ERROR</div>
<div class="graphql-code-line ">ORDER_STATE_TRANSITION_ERROR</div>
<div class="graphql-code-line ">EMAIL_ADDRESS_CONFLICT_ERROR</div>
<div class="graphql-code-line ">GUEST_CHECKOUT_ERROR</div>
<div class="graphql-code-line ">ORDER_LIMIT_ERROR</div>
<div class="graphql-code-line ">NEGATIVE_QUANTITY_ERROR</div>
<div class="graphql-code-line ">INSUFFICIENT_STOCK_ERROR</div>
<div class="graphql-code-line ">COUPON_CODE_INVALID_ERROR</div>
<div class="graphql-code-line ">COUPON_CODE_EXPIRED_ERROR</div>
<div class="graphql-code-line ">COUPON_CODE_LIMIT_ERROR</div>
<div class="graphql-code-line ">ORDER_MODIFICATION_ERROR</div>
<div class="graphql-code-line ">INELIGIBLE_SHIPPING_METHOD_ERROR</div>
<div class="graphql-code-line ">NO_ACTIVE_ORDER_ERROR</div>
<div class="graphql-code-line ">ORDER_INTERCEPTOR_ERROR</div>
<div class="graphql-code-line top-level">&#125;</div>
</div>

## GlobalFlag

<div class="graphql-code-block">

<div class="graphql-code-line top-level">enum <span class="graphql-code-identifier">GlobalFlag</span> &#123;</div>
<div class="graphql-code-line ">TRUE</div>
<div class="graphql-code-line ">FALSE</div>
<div class="graphql-code-line ">INHERIT</div>
<div class="graphql-code-line top-level">&#125;</div>
</div>

## HistoryEntryType

<div class="graphql-code-block">

<div class="graphql-code-line top-level">enum <span class="graphql-code-identifier">HistoryEntryType</span> &#123;</div>
<div class="graphql-code-line ">CUSTOMER_REGISTERED</div>
<div class="graphql-code-line ">CUSTOMER_VERIFIED</div>
<div class="graphql-code-line ">CUSTOMER_DETAIL_UPDATED</div>
<div class="graphql-code-line ">CUSTOMER_ADDED_TO_GROUP</div>
<div class="graphql-code-line ">CUSTOMER_REMOVED_FROM_GROUP</div>
<div class="graphql-code-line ">CUSTOMER_ADDRESS_CREATED</div>
<div class="graphql-code-line ">CUSTOMER_ADDRESS_UPDATED</div>
<div class="graphql-code-line ">CUSTOMER_ADDRESS_DELETED</div>
<div class="graphql-code-line ">CUSTOMER_PASSWORD_UPDATED</div>
<div class="graphql-code-line ">CUSTOMER_PASSWORD_RESET_REQUESTED</div>
<div class="graphql-code-line ">CUSTOMER_PASSWORD_RESET_VERIFIED</div>
<div class="graphql-code-line ">CUSTOMER_EMAIL_UPDATE_REQUESTED</div>
<div class="graphql-code-line ">CUSTOMER_EMAIL_UPDATE_VERIFIED</div>
<div class="graphql-code-line ">CUSTOMER_NOTE</div>
<div class="graphql-code-line ">ORDER_STATE_TRANSITION</div>
<div class="graphql-code-line ">ORDER_PAYMENT_TRANSITION</div>
<div class="graphql-code-line ">ORDER_FULFILLMENT</div>
<div class="graphql-code-line ">ORDER_CANCELLATION</div>
<div class="graphql-code-line ">ORDER_REFUND_TRANSITION</div>
<div class="graphql-code-line ">ORDER_FULFILLMENT_TRANSITION</div>
<div class="graphql-code-line ">ORDER_NOTE</div>
<div class="graphql-code-line ">ORDER_COUPON_APPLIED</div>
<div class="graphql-code-line ">ORDER_COUPON_REMOVED</div>
<div class="graphql-code-line ">ORDER_MODIFIED</div>
<div class="graphql-code-line ">ORDER_CUSTOMER_UPDATED</div>
<div class="graphql-code-line top-level">&#125;</div>
</div>

## JobState

<div class="graphql-code-block">
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The state of a Job in the JobQueue</div>

<div class="graphql-code-line comment"></div>

<div class="graphql-code-line comment"></div>
<div class="graphql-code-line comment">"""</div>

<div class="graphql-code-line top-level">enum <span class="graphql-code-identifier">JobState</span> &#123;</div>
<div class="graphql-code-line ">PENDING</div>
<div class="graphql-code-line ">RUNNING</div>
<div class="graphql-code-line ">COMPLETED</div>
<div class="graphql-code-line ">RETRYING</div>
<div class="graphql-code-line ">FAILED</div>
<div class="graphql-code-line ">CANCELLED</div>
<div class="graphql-code-line top-level">&#125;</div>
</div>

## LanguageCode

<div class="graphql-code-block">
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Languages in the form of a ISO 639-1 language code with optional</div>

<div class="graphql-code-line comment">region or script modifier (e.g. de_AT). The selection available is based</div>

<div class="graphql-code-line comment">on the [Unicode CLDR summary list](https://unicode-org.github.io/cldr-staging/charts/37/summary/root.html)</div>

<div class="graphql-code-line comment">and includes the major spoken languages of the world and any widely-used variants.</div>

<div class="graphql-code-line comment"></div>

<div class="graphql-code-line comment"></div>
<div class="graphql-code-line comment">"""</div>

<div class="graphql-code-line top-level">enum <span class="graphql-code-identifier">LanguageCode</span> &#123;</div>
<div class="graphql-code-line comment">"""Afrikaans"""</div>
<div class="graphql-code-line ">af</div>
<div class="graphql-code-line comment">"""Akan"""</div>
<div class="graphql-code-line ">ak</div>
<div class="graphql-code-line comment">"""Albanian"""</div>
<div class="graphql-code-line ">sq</div>
<div class="graphql-code-line comment">"""Amharic"""</div>
<div class="graphql-code-line ">am</div>
<div class="graphql-code-line comment">"""Arabic"""</div>
<div class="graphql-code-line ">ar</div>
<div class="graphql-code-line comment">"""Armenian"""</div>
<div class="graphql-code-line ">hy</div>
<div class="graphql-code-line comment">"""Assamese"""</div>
<div class="graphql-code-line ">as</div>
<div class="graphql-code-line comment">"""Azerbaijani"""</div>
<div class="graphql-code-line ">az</div>
<div class="graphql-code-line comment">"""Bambara"""</div>
<div class="graphql-code-line ">bm</div>
<div class="graphql-code-line comment">"""Bangla"""</div>
<div class="graphql-code-line ">bn</div>
<div class="graphql-code-line comment">"""Basque"""</div>
<div class="graphql-code-line ">eu</div>
<div class="graphql-code-line comment">"""Belarusian"""</div>
<div class="graphql-code-line ">be</div>
<div class="graphql-code-line comment">"""Bosnian"""</div>
<div class="graphql-code-line ">bs</div>
<div class="graphql-code-line comment">"""Breton"""</div>
<div class="graphql-code-line ">br</div>
<div class="graphql-code-line comment">"""Bulgarian"""</div>
<div class="graphql-code-line ">bg</div>
<div class="graphql-code-line comment">"""Burmese"""</div>
<div class="graphql-code-line ">my</div>
<div class="graphql-code-line comment">"""Catalan"""</div>
<div class="graphql-code-line ">ca</div>
<div class="graphql-code-line comment">"""Chechen"""</div>
<div class="graphql-code-line ">ce</div>
<div class="graphql-code-line comment">"""Chinese"""</div>
<div class="graphql-code-line ">zh</div>
<div class="graphql-code-line comment">"""Simplified Chinese"""</div>
<div class="graphql-code-line ">zh_Hans</div>
<div class="graphql-code-line comment">"""Traditional Chinese"""</div>
<div class="graphql-code-line ">zh_Hant</div>
<div class="graphql-code-line comment">"""Church Slavic"""</div>
<div class="graphql-code-line ">cu</div>
<div class="graphql-code-line comment">"""Cornish"""</div>
<div class="graphql-code-line ">kw</div>
<div class="graphql-code-line comment">"""Corsican"""</div>
<div class="graphql-code-line ">co</div>
<div class="graphql-code-line comment">"""Croatian"""</div>
<div class="graphql-code-line ">hr</div>
<div class="graphql-code-line comment">"""Czech"""</div>
<div class="graphql-code-line ">cs</div>
<div class="graphql-code-line comment">"""Danish"""</div>
<div class="graphql-code-line ">da</div>
<div class="graphql-code-line comment">"""Dutch"""</div>
<div class="graphql-code-line ">nl</div>
<div class="graphql-code-line comment">"""Flemish"""</div>
<div class="graphql-code-line ">nl_BE</div>
<div class="graphql-code-line comment">"""Dzongkha"""</div>
<div class="graphql-code-line ">dz</div>
<div class="graphql-code-line comment">"""English"""</div>
<div class="graphql-code-line ">en</div>
<div class="graphql-code-line comment">"""Australian English"""</div>
<div class="graphql-code-line ">en_AU</div>
<div class="graphql-code-line comment">"""Canadian English"""</div>
<div class="graphql-code-line ">en_CA</div>
<div class="graphql-code-line comment">"""British English"""</div>
<div class="graphql-code-line ">en_GB</div>
<div class="graphql-code-line comment">"""American English"""</div>
<div class="graphql-code-line ">en_US</div>
<div class="graphql-code-line comment">"""Esperanto"""</div>
<div class="graphql-code-line ">eo</div>
<div class="graphql-code-line comment">"""Estonian"""</div>
<div class="graphql-code-line ">et</div>
<div class="graphql-code-line comment">"""Ewe"""</div>
<div class="graphql-code-line ">ee</div>
<div class="graphql-code-line comment">"""Faroese"""</div>
<div class="graphql-code-line ">fo</div>
<div class="graphql-code-line comment">"""Finnish"""</div>
<div class="graphql-code-line ">fi</div>
<div class="graphql-code-line comment">"""French"""</div>
<div class="graphql-code-line ">fr</div>
<div class="graphql-code-line comment">"""Canadian French"""</div>
<div class="graphql-code-line ">fr_CA</div>
<div class="graphql-code-line comment">"""Swiss French"""</div>
<div class="graphql-code-line ">fr_CH</div>
<div class="graphql-code-line comment">"""Fulah"""</div>
<div class="graphql-code-line ">ff</div>
<div class="graphql-code-line comment">"""Galician"""</div>
<div class="graphql-code-line ">gl</div>
<div class="graphql-code-line comment">"""Ganda"""</div>
<div class="graphql-code-line ">lg</div>
<div class="graphql-code-line comment">"""Georgian"""</div>
<div class="graphql-code-line ">ka</div>
<div class="graphql-code-line comment">"""German"""</div>
<div class="graphql-code-line ">de</div>
<div class="graphql-code-line comment">"""Austrian German"""</div>
<div class="graphql-code-line ">de_AT</div>
<div class="graphql-code-line comment">"""Swiss High German"""</div>
<div class="graphql-code-line ">de_CH</div>
<div class="graphql-code-line comment">"""Greek"""</div>
<div class="graphql-code-line ">el</div>
<div class="graphql-code-line comment">"""Gujarati"""</div>
<div class="graphql-code-line ">gu</div>
<div class="graphql-code-line comment">"""Haitian Creole"""</div>
<div class="graphql-code-line ">ht</div>
<div class="graphql-code-line comment">"""Hausa"""</div>
<div class="graphql-code-line ">ha</div>
<div class="graphql-code-line comment">"""Hebrew"""</div>
<div class="graphql-code-line ">he</div>
<div class="graphql-code-line comment">"""Hindi"""</div>
<div class="graphql-code-line ">hi</div>
<div class="graphql-code-line comment">"""Hungarian"""</div>
<div class="graphql-code-line ">hu</div>
<div class="graphql-code-line comment">"""Icelandic"""</div>
<div class="graphql-code-line ">is</div>
<div class="graphql-code-line comment">"""Igbo"""</div>
<div class="graphql-code-line ">ig</div>
<div class="graphql-code-line comment">"""Indonesian"""</div>
<div class="graphql-code-line ">id</div>
<div class="graphql-code-line comment">"""Interlingua"""</div>
<div class="graphql-code-line ">ia</div>
<div class="graphql-code-line comment">"""Irish"""</div>
<div class="graphql-code-line ">ga</div>
<div class="graphql-code-line comment">"""Italian"""</div>
<div class="graphql-code-line ">it</div>
<div class="graphql-code-line comment">"""Japanese"""</div>
<div class="graphql-code-line ">ja</div>
<div class="graphql-code-line comment">"""Javanese"""</div>
<div class="graphql-code-line ">jv</div>
<div class="graphql-code-line comment">"""Kalaallisut"""</div>
<div class="graphql-code-line ">kl</div>
<div class="graphql-code-line comment">"""Kannada"""</div>
<div class="graphql-code-line ">kn</div>
<div class="graphql-code-line comment">"""Kashmiri"""</div>
<div class="graphql-code-line ">ks</div>
<div class="graphql-code-line comment">"""Kazakh"""</div>
<div class="graphql-code-line ">kk</div>
<div class="graphql-code-line comment">"""Khmer"""</div>
<div class="graphql-code-line ">km</div>
<div class="graphql-code-line comment">"""Kikuyu"""</div>
<div class="graphql-code-line ">ki</div>
<div class="graphql-code-line comment">"""Kinyarwanda"""</div>
<div class="graphql-code-line ">rw</div>
<div class="graphql-code-line comment">"""Korean"""</div>
<div class="graphql-code-line ">ko</div>
<div class="graphql-code-line comment">"""Kurdish"""</div>
<div class="graphql-code-line ">ku</div>
<div class="graphql-code-line comment">"""Kyrgyz"""</div>
<div class="graphql-code-line ">ky</div>
<div class="graphql-code-line comment">"""Lao"""</div>
<div class="graphql-code-line ">lo</div>
<div class="graphql-code-line comment">"""Latin"""</div>
<div class="graphql-code-line ">la</div>
<div class="graphql-code-line comment">"""Latvian"""</div>
<div class="graphql-code-line ">lv</div>
<div class="graphql-code-line comment">"""Lingala"""</div>
<div class="graphql-code-line ">ln</div>
<div class="graphql-code-line comment">"""Lithuanian"""</div>
<div class="graphql-code-line ">lt</div>
<div class="graphql-code-line comment">"""Luba-Katanga"""</div>
<div class="graphql-code-line ">lu</div>
<div class="graphql-code-line comment">"""Luxembourgish"""</div>
<div class="graphql-code-line ">lb</div>
<div class="graphql-code-line comment">"""Macedonian"""</div>
<div class="graphql-code-line ">mk</div>
<div class="graphql-code-line comment">"""Malagasy"""</div>
<div class="graphql-code-line ">mg</div>
<div class="graphql-code-line comment">"""Malay"""</div>
<div class="graphql-code-line ">ms</div>
<div class="graphql-code-line comment">"""Malayalam"""</div>
<div class="graphql-code-line ">ml</div>
<div class="graphql-code-line comment">"""Maltese"""</div>
<div class="graphql-code-line ">mt</div>
<div class="graphql-code-line comment">"""Manx"""</div>
<div class="graphql-code-line ">gv</div>
<div class="graphql-code-line comment">"""Maori"""</div>
<div class="graphql-code-line ">mi</div>
<div class="graphql-code-line comment">"""Marathi"""</div>
<div class="graphql-code-line ">mr</div>
<div class="graphql-code-line comment">"""Mongolian"""</div>
<div class="graphql-code-line ">mn</div>
<div class="graphql-code-line comment">"""Nepali"""</div>
<div class="graphql-code-line ">ne</div>
<div class="graphql-code-line comment">"""North Ndebele"""</div>
<div class="graphql-code-line ">nd</div>
<div class="graphql-code-line comment">"""Northern Sami"""</div>
<div class="graphql-code-line ">se</div>
<div class="graphql-code-line comment">"""Norwegian Bokmål"""</div>
<div class="graphql-code-line ">nb</div>
<div class="graphql-code-line comment">"""Norwegian Nynorsk"""</div>
<div class="graphql-code-line ">nn</div>
<div class="graphql-code-line comment">"""Nyanja"""</div>
<div class="graphql-code-line ">ny</div>
<div class="graphql-code-line comment">"""Odia"""</div>
<div class="graphql-code-line ">or</div>
<div class="graphql-code-line comment">"""Oromo"""</div>
<div class="graphql-code-line ">om</div>
<div class="graphql-code-line comment">"""Ossetic"""</div>
<div class="graphql-code-line ">os</div>
<div class="graphql-code-line comment">"""Pashto"""</div>
<div class="graphql-code-line ">ps</div>
<div class="graphql-code-line comment">"""Persian"""</div>
<div class="graphql-code-line ">fa</div>
<div class="graphql-code-line comment">"""Dari"""</div>
<div class="graphql-code-line ">fa_AF</div>
<div class="graphql-code-line comment">"""Polish"""</div>
<div class="graphql-code-line ">pl</div>
<div class="graphql-code-line comment">"""Portuguese"""</div>
<div class="graphql-code-line ">pt</div>
<div class="graphql-code-line comment">"""Brazilian Portuguese"""</div>
<div class="graphql-code-line ">pt_BR</div>
<div class="graphql-code-line comment">"""European Portuguese"""</div>
<div class="graphql-code-line ">pt_PT</div>
<div class="graphql-code-line comment">"""Punjabi"""</div>
<div class="graphql-code-line ">pa</div>
<div class="graphql-code-line comment">"""Quechua"""</div>
<div class="graphql-code-line ">qu</div>
<div class="graphql-code-line comment">"""Romanian"""</div>
<div class="graphql-code-line ">ro</div>
<div class="graphql-code-line comment">"""Moldavian"""</div>
<div class="graphql-code-line ">ro_MD</div>
<div class="graphql-code-line comment">"""Romansh"""</div>
<div class="graphql-code-line ">rm</div>
<div class="graphql-code-line comment">"""Rundi"""</div>
<div class="graphql-code-line ">rn</div>
<div class="graphql-code-line comment">"""Russian"""</div>
<div class="graphql-code-line ">ru</div>
<div class="graphql-code-line comment">"""Samoan"""</div>
<div class="graphql-code-line ">sm</div>
<div class="graphql-code-line comment">"""Sango"""</div>
<div class="graphql-code-line ">sg</div>
<div class="graphql-code-line comment">"""Sanskrit"""</div>
<div class="graphql-code-line ">sa</div>
<div class="graphql-code-line comment">"""Scottish Gaelic"""</div>
<div class="graphql-code-line ">gd</div>
<div class="graphql-code-line comment">"""Serbian"""</div>
<div class="graphql-code-line ">sr</div>
<div class="graphql-code-line comment">"""Shona"""</div>
<div class="graphql-code-line ">sn</div>
<div class="graphql-code-line comment">"""Sichuan Yi"""</div>
<div class="graphql-code-line ">ii</div>
<div class="graphql-code-line comment">"""Sindhi"""</div>
<div class="graphql-code-line ">sd</div>
<div class="graphql-code-line comment">"""Sinhala"""</div>
<div class="graphql-code-line ">si</div>
<div class="graphql-code-line comment">"""Slovak"""</div>
<div class="graphql-code-line ">sk</div>
<div class="graphql-code-line comment">"""Slovenian"""</div>
<div class="graphql-code-line ">sl</div>
<div class="graphql-code-line comment">"""Somali"""</div>
<div class="graphql-code-line ">so</div>
<div class="graphql-code-line comment">"""Southern Sotho"""</div>
<div class="graphql-code-line ">st</div>
<div class="graphql-code-line comment">"""Spanish"""</div>
<div class="graphql-code-line ">es</div>
<div class="graphql-code-line comment">"""European Spanish"""</div>
<div class="graphql-code-line ">es_ES</div>
<div class="graphql-code-line comment">"""Mexican Spanish"""</div>
<div class="graphql-code-line ">es_MX</div>
<div class="graphql-code-line comment">"""Sundanese"""</div>
<div class="graphql-code-line ">su</div>
<div class="graphql-code-line comment">"""Swahili"""</div>
<div class="graphql-code-line ">sw</div>
<div class="graphql-code-line comment">"""Congo Swahili"""</div>
<div class="graphql-code-line ">sw_CD</div>
<div class="graphql-code-line comment">"""Swedish"""</div>
<div class="graphql-code-line ">sv</div>
<div class="graphql-code-line comment">"""Tajik"""</div>
<div class="graphql-code-line ">tg</div>
<div class="graphql-code-line comment">"""Tamil"""</div>
<div class="graphql-code-line ">ta</div>
<div class="graphql-code-line comment">"""Tatar"""</div>
<div class="graphql-code-line ">tt</div>
<div class="graphql-code-line comment">"""Telugu"""</div>
<div class="graphql-code-line ">te</div>
<div class="graphql-code-line comment">"""Thai"""</div>
<div class="graphql-code-line ">th</div>
<div class="graphql-code-line comment">"""Tibetan"""</div>
<div class="graphql-code-line ">bo</div>
<div class="graphql-code-line comment">"""Tigrinya"""</div>
<div class="graphql-code-line ">ti</div>
<div class="graphql-code-line comment">"""Tongan"""</div>
<div class="graphql-code-line ">to</div>
<div class="graphql-code-line comment">"""Turkish"""</div>
<div class="graphql-code-line ">tr</div>
<div class="graphql-code-line comment">"""Turkmen"""</div>
<div class="graphql-code-line ">tk</div>
<div class="graphql-code-line comment">"""Ukrainian"""</div>
<div class="graphql-code-line ">uk</div>
<div class="graphql-code-line comment">"""Urdu"""</div>
<div class="graphql-code-line ">ur</div>
<div class="graphql-code-line comment">"""Uyghur"""</div>
<div class="graphql-code-line ">ug</div>
<div class="graphql-code-line comment">"""Uzbek"""</div>
<div class="graphql-code-line ">uz</div>
<div class="graphql-code-line comment">"""Vietnamese"""</div>
<div class="graphql-code-line ">vi</div>
<div class="graphql-code-line comment">"""Volapük"""</div>
<div class="graphql-code-line ">vo</div>
<div class="graphql-code-line comment">"""Welsh"""</div>
<div class="graphql-code-line ">cy</div>
<div class="graphql-code-line comment">"""Western Frisian"""</div>
<div class="graphql-code-line ">fy</div>
<div class="graphql-code-line comment">"""Wolof"""</div>
<div class="graphql-code-line ">wo</div>
<div class="graphql-code-line comment">"""Xhosa"""</div>
<div class="graphql-code-line ">xh</div>
<div class="graphql-code-line comment">"""Yiddish"""</div>
<div class="graphql-code-line ">yi</div>
<div class="graphql-code-line comment">"""Yoruba"""</div>
<div class="graphql-code-line ">yo</div>
<div class="graphql-code-line comment">"""Zulu"""</div>
<div class="graphql-code-line ">zu</div>
<div class="graphql-code-line top-level">&#125;</div>
</div>

## LogicalOperator

<div class="graphql-code-block">

<div class="graphql-code-line top-level">enum <span class="graphql-code-identifier">LogicalOperator</span> &#123;</div>
<div class="graphql-code-line ">AND</div>
<div class="graphql-code-line ">OR</div>
<div class="graphql-code-line top-level">&#125;</div>
</div>

## MetricInterval

<div class="graphql-code-block">

<div class="graphql-code-line top-level">enum <span class="graphql-code-identifier">MetricInterval</span> &#123;</div>
<div class="graphql-code-line ">Daily</div>
<div class="graphql-code-line top-level">&#125;</div>
</div>

## MetricType

<div class="graphql-code-block">

<div class="graphql-code-line top-level">enum <span class="graphql-code-identifier">MetricType</span> &#123;</div>
<div class="graphql-code-line ">OrderCount</div>
<div class="graphql-code-line ">OrderTotal</div>
<div class="graphql-code-line ">AverageOrderValue</div>
<div class="graphql-code-line top-level">&#125;</div>
</div>

## OrderType

<div class="graphql-code-block">

<div class="graphql-code-line top-level">enum <span class="graphql-code-identifier">OrderType</span> &#123;</div>
<div class="graphql-code-line ">Regular</div>
<div class="graphql-code-line ">Seller</div>
<div class="graphql-code-line ">Aggregate</div>
<div class="graphql-code-line top-level">&#125;</div>
</div>

## Permission

<div class="graphql-code-block">
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Permissions for administrators and customers. Used to control access to</div>

<div class="graphql-code-line comment">GraphQL resolvers via the &#123;@link Allow&#125; decorator.</div>

<div class="graphql-code-line comment"></div>

<div class="graphql-code-line comment">## Understanding Permission.Owner</div>

<div class="graphql-code-line comment"></div>

<div class="graphql-code-line comment">`Permission.Owner` is a special permission which is used in some Vendure resolvers to indicate that that resolver should only</div>

<div class="graphql-code-line comment">be accessible to the "owner" of that resource.</div>

<div class="graphql-code-line comment"></div>

<div class="graphql-code-line comment">For example, the Shop API <code>activeCustomer</code> query resolver should only return the Customer object for the "owner" of that Customer, i.e.</div>

<div class="graphql-code-line comment">based on the activeUserId of the current session. As a result, the resolver code looks like this:</div>

<div class="graphql-code-line comment"></div>

<div class="graphql-code-line comment">@example</div>

<div class="graphql-code-line comment">```TypeScript</div>

<div class="graphql-code-line comment">\@Query()</div>

<div class="graphql-code-line comment">\@Allow(Permission.Owner)</div>

<div class="graphql-code-line comment">async activeCustomer(\@Ctx() ctx: RequestContext): Promise&lt;Customer | undefined&gt; &#123;</div>

<div class="graphql-code-line comment">  const userId = ctx.activeUserId;</div>

<div class="graphql-code-line comment">  if (userId) &#123;</div>

<div class="graphql-code-line comment">    return this.customerService.findOneByUserId(ctx, userId);</div>

<div class="graphql-code-line comment">  &#125;</div>

<div class="graphql-code-line comment">&#125;</div>

<div class="graphql-code-line comment">```</div>

<div class="graphql-code-line comment"></div>

<div class="graphql-code-line comment">Here we can see that the "ownership" must be enforced by custom logic inside the resolver. Since "ownership" cannot be defined generally</div>

<div class="graphql-code-line comment">nor statically encoded at build-time, any resolvers using <code>Permission.Owner</code> **must** include logic to enforce that only the owner</div>

<div class="graphql-code-line comment">of the resource has access. If not, then it is the equivalent of using `Permission.Public`.</div>

<div class="graphql-code-line comment"></div>

<div class="graphql-code-line comment"></div>

<div class="graphql-code-line comment"></div>
<div class="graphql-code-line comment">"""</div>

<div class="graphql-code-line top-level">enum <span class="graphql-code-identifier">Permission</span> &#123;</div>
<div class="graphql-code-line comment">"""Authenticated means simply that the user is logged in"""</div>
<div class="graphql-code-line ">Authenticated</div>
<div class="graphql-code-line comment">"""SuperAdmin has unrestricted access to all operations"""</div>
<div class="graphql-code-line ">SuperAdmin</div>
<div class="graphql-code-line comment">"""Owner means the user owns this entity, e.g. a Customer's own Order"""</div>
<div class="graphql-code-line ">Owner</div>
<div class="graphql-code-line comment">"""Public means any unauthenticated user may perform the operation"""</div>
<div class="graphql-code-line ">Public</div>
<div class="graphql-code-line comment">"""Grants permission to update GlobalSettings"""</div>
<div class="graphql-code-line ">UpdateGlobalSettings</div>
<div class="graphql-code-line comment">"""Grants permission to create Products, Facets, Assets, Collections"""</div>
<div class="graphql-code-line ">CreateCatalog</div>
<div class="graphql-code-line comment">"""Grants permission to read Products, Facets, Assets, Collections"""</div>
<div class="graphql-code-line ">ReadCatalog</div>
<div class="graphql-code-line comment">"""Grants permission to update Products, Facets, Assets, Collections"""</div>
<div class="graphql-code-line ">UpdateCatalog</div>
<div class="graphql-code-line comment">"""Grants permission to delete Products, Facets, Assets, Collections"""</div>
<div class="graphql-code-line ">DeleteCatalog</div>
<div class="graphql-code-line comment">"""Grants permission to create PaymentMethods, ShippingMethods, TaxCategories, TaxRates, Zones, Countries, System & GlobalSettings"""</div>
<div class="graphql-code-line ">CreateSettings</div>
<div class="graphql-code-line comment">"""Grants permission to read PaymentMethods, ShippingMethods, TaxCategories, TaxRates, Zones, Countries, System & GlobalSettings"""</div>
<div class="graphql-code-line ">ReadSettings</div>
<div class="graphql-code-line comment">"""Grants permission to update PaymentMethods, ShippingMethods, TaxCategories, TaxRates, Zones, Countries, System & GlobalSettings"""</div>
<div class="graphql-code-line ">UpdateSettings</div>
<div class="graphql-code-line comment">"""Grants permission to delete PaymentMethods, ShippingMethods, TaxCategories, TaxRates, Zones, Countries, System & GlobalSettings"""</div>
<div class="graphql-code-line ">DeleteSettings</div>
<div class="graphql-code-line comment">"""Grants permission to create Administrator"""</div>
<div class="graphql-code-line ">CreateAdministrator</div>
<div class="graphql-code-line comment">"""Grants permission to read Administrator"""</div>
<div class="graphql-code-line ">ReadAdministrator</div>
<div class="graphql-code-line comment">"""Grants permission to update Administrator"""</div>
<div class="graphql-code-line ">UpdateAdministrator</div>
<div class="graphql-code-line comment">"""Grants permission to delete Administrator"""</div>
<div class="graphql-code-line ">DeleteAdministrator</div>
<div class="graphql-code-line comment">"""Grants permission to create Asset"""</div>
<div class="graphql-code-line ">CreateAsset</div>
<div class="graphql-code-line comment">"""Grants permission to read Asset"""</div>
<div class="graphql-code-line ">ReadAsset</div>
<div class="graphql-code-line comment">"""Grants permission to update Asset"""</div>
<div class="graphql-code-line ">UpdateAsset</div>
<div class="graphql-code-line comment">"""Grants permission to delete Asset"""</div>
<div class="graphql-code-line ">DeleteAsset</div>
<div class="graphql-code-line comment">"""Grants permission to create Channel"""</div>
<div class="graphql-code-line ">CreateChannel</div>
<div class="graphql-code-line comment">"""Grants permission to read Channel"""</div>
<div class="graphql-code-line ">ReadChannel</div>
<div class="graphql-code-line comment">"""Grants permission to update Channel"""</div>
<div class="graphql-code-line ">UpdateChannel</div>
<div class="graphql-code-line comment">"""Grants permission to delete Channel"""</div>
<div class="graphql-code-line ">DeleteChannel</div>
<div class="graphql-code-line comment">"""Grants permission to create Collection"""</div>
<div class="graphql-code-line ">CreateCollection</div>
<div class="graphql-code-line comment">"""Grants permission to read Collection"""</div>
<div class="graphql-code-line ">ReadCollection</div>
<div class="graphql-code-line comment">"""Grants permission to update Collection"""</div>
<div class="graphql-code-line ">UpdateCollection</div>
<div class="graphql-code-line comment">"""Grants permission to delete Collection"""</div>
<div class="graphql-code-line ">DeleteCollection</div>
<div class="graphql-code-line comment">"""Grants permission to create Country"""</div>
<div class="graphql-code-line ">CreateCountry</div>
<div class="graphql-code-line comment">"""Grants permission to read Country"""</div>
<div class="graphql-code-line ">ReadCountry</div>
<div class="graphql-code-line comment">"""Grants permission to update Country"""</div>
<div class="graphql-code-line ">UpdateCountry</div>
<div class="graphql-code-line comment">"""Grants permission to delete Country"""</div>
<div class="graphql-code-line ">DeleteCountry</div>
<div class="graphql-code-line comment">"""Grants permission to create Customer"""</div>
<div class="graphql-code-line ">CreateCustomer</div>
<div class="graphql-code-line comment">"""Grants permission to read Customer"""</div>
<div class="graphql-code-line ">ReadCustomer</div>
<div class="graphql-code-line comment">"""Grants permission to update Customer"""</div>
<div class="graphql-code-line ">UpdateCustomer</div>
<div class="graphql-code-line comment">"""Grants permission to delete Customer"""</div>
<div class="graphql-code-line ">DeleteCustomer</div>
<div class="graphql-code-line comment">"""Grants permission to create CustomerGroup"""</div>
<div class="graphql-code-line ">CreateCustomerGroup</div>
<div class="graphql-code-line comment">"""Grants permission to read CustomerGroup"""</div>
<div class="graphql-code-line ">ReadCustomerGroup</div>
<div class="graphql-code-line comment">"""Grants permission to update CustomerGroup"""</div>
<div class="graphql-code-line ">UpdateCustomerGroup</div>
<div class="graphql-code-line comment">"""Grants permission to delete CustomerGroup"""</div>
<div class="graphql-code-line ">DeleteCustomerGroup</div>
<div class="graphql-code-line comment">"""Grants permission to create Facet"""</div>
<div class="graphql-code-line ">CreateFacet</div>
<div class="graphql-code-line comment">"""Grants permission to read Facet"""</div>
<div class="graphql-code-line ">ReadFacet</div>
<div class="graphql-code-line comment">"""Grants permission to update Facet"""</div>
<div class="graphql-code-line ">UpdateFacet</div>
<div class="graphql-code-line comment">"""Grants permission to delete Facet"""</div>
<div class="graphql-code-line ">DeleteFacet</div>
<div class="graphql-code-line comment">"""Grants permission to create Order"""</div>
<div class="graphql-code-line ">CreateOrder</div>
<div class="graphql-code-line comment">"""Grants permission to read Order"""</div>
<div class="graphql-code-line ">ReadOrder</div>
<div class="graphql-code-line comment">"""Grants permission to update Order"""</div>
<div class="graphql-code-line ">UpdateOrder</div>
<div class="graphql-code-line comment">"""Grants permission to delete Order"""</div>
<div class="graphql-code-line ">DeleteOrder</div>
<div class="graphql-code-line comment">"""Grants permission to create PaymentMethod"""</div>
<div class="graphql-code-line ">CreatePaymentMethod</div>
<div class="graphql-code-line comment">"""Grants permission to read PaymentMethod"""</div>
<div class="graphql-code-line ">ReadPaymentMethod</div>
<div class="graphql-code-line comment">"""Grants permission to update PaymentMethod"""</div>
<div class="graphql-code-line ">UpdatePaymentMethod</div>
<div class="graphql-code-line comment">"""Grants permission to delete PaymentMethod"""</div>
<div class="graphql-code-line ">DeletePaymentMethod</div>
<div class="graphql-code-line comment">"""Grants permission to create Product"""</div>
<div class="graphql-code-line ">CreateProduct</div>
<div class="graphql-code-line comment">"""Grants permission to read Product"""</div>
<div class="graphql-code-line ">ReadProduct</div>
<div class="graphql-code-line comment">"""Grants permission to update Product"""</div>
<div class="graphql-code-line ">UpdateProduct</div>
<div class="graphql-code-line comment">"""Grants permission to delete Product"""</div>
<div class="graphql-code-line ">DeleteProduct</div>
<div class="graphql-code-line comment">"""Grants permission to create Promotion"""</div>
<div class="graphql-code-line ">CreatePromotion</div>
<div class="graphql-code-line comment">"""Grants permission to read Promotion"""</div>
<div class="graphql-code-line ">ReadPromotion</div>
<div class="graphql-code-line comment">"""Grants permission to update Promotion"""</div>
<div class="graphql-code-line ">UpdatePromotion</div>
<div class="graphql-code-line comment">"""Grants permission to delete Promotion"""</div>
<div class="graphql-code-line ">DeletePromotion</div>
<div class="graphql-code-line comment">"""Grants permission to create ShippingMethod"""</div>
<div class="graphql-code-line ">CreateShippingMethod</div>
<div class="graphql-code-line comment">"""Grants permission to read ShippingMethod"""</div>
<div class="graphql-code-line ">ReadShippingMethod</div>
<div class="graphql-code-line comment">"""Grants permission to update ShippingMethod"""</div>
<div class="graphql-code-line ">UpdateShippingMethod</div>
<div class="graphql-code-line comment">"""Grants permission to delete ShippingMethod"""</div>
<div class="graphql-code-line ">DeleteShippingMethod</div>
<div class="graphql-code-line comment">"""Grants permission to create Tag"""</div>
<div class="graphql-code-line ">CreateTag</div>
<div class="graphql-code-line comment">"""Grants permission to read Tag"""</div>
<div class="graphql-code-line ">ReadTag</div>
<div class="graphql-code-line comment">"""Grants permission to update Tag"""</div>
<div class="graphql-code-line ">UpdateTag</div>
<div class="graphql-code-line comment">"""Grants permission to delete Tag"""</div>
<div class="graphql-code-line ">DeleteTag</div>
<div class="graphql-code-line comment">"""Grants permission to create TaxCategory"""</div>
<div class="graphql-code-line ">CreateTaxCategory</div>
<div class="graphql-code-line comment">"""Grants permission to read TaxCategory"""</div>
<div class="graphql-code-line ">ReadTaxCategory</div>
<div class="graphql-code-line comment">"""Grants permission to update TaxCategory"""</div>
<div class="graphql-code-line ">UpdateTaxCategory</div>
<div class="graphql-code-line comment">"""Grants permission to delete TaxCategory"""</div>
<div class="graphql-code-line ">DeleteTaxCategory</div>
<div class="graphql-code-line comment">"""Grants permission to create TaxRate"""</div>
<div class="graphql-code-line ">CreateTaxRate</div>
<div class="graphql-code-line comment">"""Grants permission to read TaxRate"""</div>
<div class="graphql-code-line ">ReadTaxRate</div>
<div class="graphql-code-line comment">"""Grants permission to update TaxRate"""</div>
<div class="graphql-code-line ">UpdateTaxRate</div>
<div class="graphql-code-line comment">"""Grants permission to delete TaxRate"""</div>
<div class="graphql-code-line ">DeleteTaxRate</div>
<div class="graphql-code-line comment">"""Grants permission to create Seller"""</div>
<div class="graphql-code-line ">CreateSeller</div>
<div class="graphql-code-line comment">"""Grants permission to read Seller"""</div>
<div class="graphql-code-line ">ReadSeller</div>
<div class="graphql-code-line comment">"""Grants permission to update Seller"""</div>
<div class="graphql-code-line ">UpdateSeller</div>
<div class="graphql-code-line comment">"""Grants permission to delete Seller"""</div>
<div class="graphql-code-line ">DeleteSeller</div>
<div class="graphql-code-line comment">"""Grants permission to create StockLocation"""</div>
<div class="graphql-code-line ">CreateStockLocation</div>
<div class="graphql-code-line comment">"""Grants permission to read StockLocation"""</div>
<div class="graphql-code-line ">ReadStockLocation</div>
<div class="graphql-code-line comment">"""Grants permission to update StockLocation"""</div>
<div class="graphql-code-line ">UpdateStockLocation</div>
<div class="graphql-code-line comment">"""Grants permission to delete StockLocation"""</div>
<div class="graphql-code-line ">DeleteStockLocation</div>
<div class="graphql-code-line comment">"""Grants permission to create System"""</div>
<div class="graphql-code-line ">CreateSystem</div>
<div class="graphql-code-line comment">"""Grants permission to read System"""</div>
<div class="graphql-code-line ">ReadSystem</div>
<div class="graphql-code-line comment">"""Grants permission to update System"""</div>
<div class="graphql-code-line ">UpdateSystem</div>
<div class="graphql-code-line comment">"""Grants permission to delete System"""</div>
<div class="graphql-code-line ">DeleteSystem</div>
<div class="graphql-code-line comment">"""Grants permission to create Zone"""</div>
<div class="graphql-code-line ">CreateZone</div>
<div class="graphql-code-line comment">"""Grants permission to read Zone"""</div>
<div class="graphql-code-line ">ReadZone</div>
<div class="graphql-code-line comment">"""Grants permission to update Zone"""</div>
<div class="graphql-code-line ">UpdateZone</div>
<div class="graphql-code-line comment">"""Grants permission to delete Zone"""</div>
<div class="graphql-code-line ">DeleteZone</div>
<div class="graphql-code-line top-level">&#125;</div>
</div>

## SortOrder

<div class="graphql-code-block">

<div class="graphql-code-line top-level">enum <span class="graphql-code-identifier">SortOrder</span> &#123;</div>
<div class="graphql-code-line ">ASC</div>
<div class="graphql-code-line ">DESC</div>
<div class="graphql-code-line top-level">&#125;</div>
</div>

## StockMovementType

<div class="graphql-code-block">

<div class="graphql-code-line top-level">enum <span class="graphql-code-identifier">StockMovementType</span> &#123;</div>
<div class="graphql-code-line ">ADJUSTMENT</div>
<div class="graphql-code-line ">ALLOCATION</div>
<div class="graphql-code-line ">RELEASE</div>
<div class="graphql-code-line ">SALE</div>
<div class="graphql-code-line ">CANCELLATION</div>
<div class="graphql-code-line ">RETURN</div>
<div class="graphql-code-line top-level">&#125;</div>
</div>


---

---
title: "Input Objects"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';



## AddItemInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">AddItemInput</span> &#123;</div>
<div class="graphql-code-line ">productVariantId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">quantity: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## AddItemToDraftOrderInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">AddItemToDraftOrderInput</span> &#123;</div>
<div class="graphql-code-line ">productVariantId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">quantity: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## AddNoteToCustomerInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">AddNoteToCustomerInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">note: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">isPublic: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## AddNoteToOrderInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">AddNoteToOrderInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">note: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">isPublic: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## AdjustDraftOrderLineInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">AdjustDraftOrderLineInput</span> &#123;</div>
<div class="graphql-code-line ">orderLineId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">quantity: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## AdministratorFilterParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">AdministratorFilterParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">firstName: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">lastName: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">emailAddress: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">_and: [<a href="/reference/graphql-api/admin/input-types#administratorfilterparameter">AdministratorFilterParameter</a>!]</div>

<div class="graphql-code-line ">_or: [<a href="/reference/graphql-api/admin/input-types#administratorfilterparameter">AdministratorFilterParameter</a>!]</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## AdministratorListOptions

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">AdministratorListOptions</span> &#123;</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Skips the first n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">skip: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Takes n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">take: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies which properties to sort the results by</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">sort: <a href="/reference/graphql-api/admin/input-types#administratorsortparameter">AdministratorSortParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Allows the results to be filtered</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filter: <a href="/reference/graphql-api/admin/input-types#administratorfilterparameter">AdministratorFilterParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies whether multiple top-level "filter" fields should be combined with a logical AND or OR operation. Defaults to AND.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filterOperator: <a href="/reference/graphql-api/admin/enums#logicaloperator">LogicalOperator</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## AdministratorPaymentInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">AdministratorPaymentInput</span> &#123;</div>
<div class="graphql-code-line ">paymentMethod: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">metadata: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## AdministratorRefundInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">AdministratorRefundInput</span> &#123;</div>
<div class="graphql-code-line ">paymentId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">reason: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The amount to be refunded to this particular Payment. This was introduced in</div>

<div class="graphql-code-line comment">v2.2.0 as the preferred way to specify the refund amount. The `lines`, <code>shipping</code> and `adjustment`</div>

<div class="graphql-code-line comment">fields will be removed in a future version.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">amount: <a href="/reference/graphql-api/admin/object-types#money">Money</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## AdministratorSortParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">AdministratorSortParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">firstName: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">lastName: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">emailAddress: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## AssetFilterParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">AssetFilterParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">fileSize: <a href="/reference/graphql-api/admin/input-types#numberoperators">NumberOperators</a></div>

<div class="graphql-code-line ">mimeType: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">width: <a href="/reference/graphql-api/admin/input-types#numberoperators">NumberOperators</a></div>

<div class="graphql-code-line ">height: <a href="/reference/graphql-api/admin/input-types#numberoperators">NumberOperators</a></div>

<div class="graphql-code-line ">source: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">preview: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">_and: [<a href="/reference/graphql-api/admin/input-types#assetfilterparameter">AssetFilterParameter</a>!]</div>

<div class="graphql-code-line ">_or: [<a href="/reference/graphql-api/admin/input-types#assetfilterparameter">AssetFilterParameter</a>!]</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## AssetListOptions

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">AssetListOptions</span> &#123;</div>
<div class="graphql-code-line ">tags: [<a href="/reference/graphql-api/admin/object-types#string">String</a>!]</div>

<div class="graphql-code-line ">tagsOperator: <a href="/reference/graphql-api/admin/enums#logicaloperator">LogicalOperator</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Skips the first n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">skip: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Takes n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">take: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies which properties to sort the results by</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">sort: <a href="/reference/graphql-api/admin/input-types#assetsortparameter">AssetSortParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Allows the results to be filtered</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filter: <a href="/reference/graphql-api/admin/input-types#assetfilterparameter">AssetFilterParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies whether multiple top-level "filter" fields should be combined with a logical AND or OR operation. Defaults to AND.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filterOperator: <a href="/reference/graphql-api/admin/enums#logicaloperator">LogicalOperator</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## AssetSortParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">AssetSortParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">fileSize: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">mimeType: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">width: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">height: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">source: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">preview: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## AssignAssetsToChannelInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">AssignAssetsToChannelInput</span> &#123;</div>
<div class="graphql-code-line ">assetIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!</div>

<div class="graphql-code-line ">channelId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## AssignCollectionsToChannelInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">AssignCollectionsToChannelInput</span> &#123;</div>
<div class="graphql-code-line ">collectionIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!</div>

<div class="graphql-code-line ">channelId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## AssignFacetsToChannelInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">AssignFacetsToChannelInput</span> &#123;</div>
<div class="graphql-code-line ">facetIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!</div>

<div class="graphql-code-line ">channelId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## AssignPaymentMethodsToChannelInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">AssignPaymentMethodsToChannelInput</span> &#123;</div>
<div class="graphql-code-line ">paymentMethodIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!</div>

<div class="graphql-code-line ">channelId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## AssignProductVariantsToChannelInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">AssignProductVariantsToChannelInput</span> &#123;</div>
<div class="graphql-code-line ">productVariantIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!</div>

<div class="graphql-code-line ">channelId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">priceFactor: <a href="/reference/graphql-api/admin/object-types#float">Float</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## AssignProductsToChannelInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">AssignProductsToChannelInput</span> &#123;</div>
<div class="graphql-code-line ">productIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!</div>

<div class="graphql-code-line ">channelId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">priceFactor: <a href="/reference/graphql-api/admin/object-types#float">Float</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## AssignPromotionsToChannelInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">AssignPromotionsToChannelInput</span> &#123;</div>
<div class="graphql-code-line ">promotionIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!</div>

<div class="graphql-code-line ">channelId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## AssignShippingMethodsToChannelInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">AssignShippingMethodsToChannelInput</span> &#123;</div>
<div class="graphql-code-line ">shippingMethodIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!</div>

<div class="graphql-code-line ">channelId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## AssignStockLocationsToChannelInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">AssignStockLocationsToChannelInput</span> &#123;</div>
<div class="graphql-code-line ">stockLocationIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!</div>

<div class="graphql-code-line ">channelId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## AuthenticationInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">AuthenticationInput</span> &#123;</div>
<div class="graphql-code-line ">native: <a href="/reference/graphql-api/admin/input-types#nativeauthinput">NativeAuthInput</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## BooleanListOperators

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Operators for filtering on a list of Boolean fields</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">BooleanListOperators</span> &#123;</div>
<div class="graphql-code-line ">inList: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## BooleanOperators

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Operators for filtering on a Boolean field</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">BooleanOperators</span> &#123;</div>
<div class="graphql-code-line ">eq: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">isNull: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CancelOrderInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CancelOrderInput</span> &#123;</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The id of the order to be cancelled</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">orderId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Optionally specify which OrderLines to cancel. If not provided, all OrderLines will be cancelled</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">lines: [<a href="/reference/graphql-api/admin/input-types#orderlineinput">OrderLineInput</a>!]</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specify whether the shipping charges should also be cancelled. Defaults to false</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">cancelShipping: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">reason: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ChannelFilterParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">ChannelFilterParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">token: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">defaultLanguageCode: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">currencyCode: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">defaultCurrencyCode: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">trackInventory: <a href="/reference/graphql-api/admin/input-types#booleanoperators">BooleanOperators</a></div>

<div class="graphql-code-line ">outOfStockThreshold: <a href="/reference/graphql-api/admin/input-types#numberoperators">NumberOperators</a></div>

<div class="graphql-code-line ">pricesIncludeTax: <a href="/reference/graphql-api/admin/input-types#booleanoperators">BooleanOperators</a></div>

<div class="graphql-code-line ">_and: [<a href="/reference/graphql-api/admin/input-types#channelfilterparameter">ChannelFilterParameter</a>!]</div>

<div class="graphql-code-line ">_or: [<a href="/reference/graphql-api/admin/input-types#channelfilterparameter">ChannelFilterParameter</a>!]</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ChannelListOptions

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">ChannelListOptions</span> &#123;</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Skips the first n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">skip: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Takes n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">take: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies which properties to sort the results by</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">sort: <a href="/reference/graphql-api/admin/input-types#channelsortparameter">ChannelSortParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Allows the results to be filtered</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filter: <a href="/reference/graphql-api/admin/input-types#channelfilterparameter">ChannelFilterParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies whether multiple top-level "filter" fields should be combined with a logical AND or OR operation. Defaults to AND.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filterOperator: <a href="/reference/graphql-api/admin/enums#logicaloperator">LogicalOperator</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ChannelSortParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">ChannelSortParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">token: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">outOfStockThreshold: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CollectionFilterParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CollectionFilterParameter</span> &#123;</div>
<div class="graphql-code-line ">isPrivate: <a href="/reference/graphql-api/admin/input-types#booleanoperators">BooleanOperators</a></div>

<div class="graphql-code-line ">inheritFilters: <a href="/reference/graphql-api/admin/input-types#booleanoperators">BooleanOperators</a></div>

<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">slug: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">position: <a href="/reference/graphql-api/admin/input-types#numberoperators">NumberOperators</a></div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">parentId: <a href="/reference/graphql-api/admin/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">_and: [<a href="/reference/graphql-api/admin/input-types#collectionfilterparameter">CollectionFilterParameter</a>!]</div>

<div class="graphql-code-line ">_or: [<a href="/reference/graphql-api/admin/input-types#collectionfilterparameter">CollectionFilterParameter</a>!]</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CollectionListOptions

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CollectionListOptions</span> &#123;</div>
<div class="graphql-code-line ">topLevelOnly: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Skips the first n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">skip: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Takes n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">take: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies which properties to sort the results by</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">sort: <a href="/reference/graphql-api/admin/input-types#collectionsortparameter">CollectionSortParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Allows the results to be filtered</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filter: <a href="/reference/graphql-api/admin/input-types#collectionfilterparameter">CollectionFilterParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies whether multiple top-level "filter" fields should be combined with a logical AND or OR operation. Defaults to AND.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filterOperator: <a href="/reference/graphql-api/admin/enums#logicaloperator">LogicalOperator</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CollectionSortParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CollectionSortParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">slug: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">position: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">parentId: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ConfigArgInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">ConfigArgInput</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">A JSON stringified representation of the actual value</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">value: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ConfigurableOperationInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">ConfigurableOperationInput</span> &#123;</div>
<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">arguments: [<a href="/reference/graphql-api/admin/input-types#configarginput">ConfigArgInput</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CoordinateInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CoordinateInput</span> &#123;</div>
<div class="graphql-code-line ">x: <a href="/reference/graphql-api/admin/object-types#float">Float</a>!</div>

<div class="graphql-code-line ">y: <a href="/reference/graphql-api/admin/object-types#float">Float</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CountryFilterParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CountryFilterParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">enabled: <a href="/reference/graphql-api/admin/input-types#booleanoperators">BooleanOperators</a></div>

<div class="graphql-code-line ">parentId: <a href="/reference/graphql-api/admin/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">_and: [<a href="/reference/graphql-api/admin/input-types#countryfilterparameter">CountryFilterParameter</a>!]</div>

<div class="graphql-code-line ">_or: [<a href="/reference/graphql-api/admin/input-types#countryfilterparameter">CountryFilterParameter</a>!]</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CountryListOptions

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CountryListOptions</span> &#123;</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Skips the first n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">skip: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Takes n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">take: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies which properties to sort the results by</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">sort: <a href="/reference/graphql-api/admin/input-types#countrysortparameter">CountrySortParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Allows the results to be filtered</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filter: <a href="/reference/graphql-api/admin/input-types#countryfilterparameter">CountryFilterParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies whether multiple top-level "filter" fields should be combined with a logical AND or OR operation. Defaults to AND.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filterOperator: <a href="/reference/graphql-api/admin/enums#logicaloperator">LogicalOperator</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CountrySortParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CountrySortParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">parentId: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CountryTranslationInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CountryTranslationInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a></div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CreateAddressInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Input used to create an Address.</div>

<div class="graphql-code-line top-level comment"></div>

<div class="graphql-code-line top-level comment">The countryCode must correspond to a <code>code</code> property of a Country that has been defined in the</div>

<div class="graphql-code-line top-level comment">Vendure server. The <code>code</code> property is typically a 2-character ISO code such as "GB", "US", "DE" etc.</div>

<div class="graphql-code-line top-level comment">If an invalid code is passed, the mutation will fail.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CreateAddressInput</span> &#123;</div>
<div class="graphql-code-line ">fullName: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">company: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">streetLine1: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">streetLine2: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">city: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">province: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">postalCode: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">countryCode: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">phoneNumber: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">defaultShippingAddress: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">defaultBillingAddress: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CreateAdministratorInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CreateAdministratorInput</span> &#123;</div>
<div class="graphql-code-line ">firstName: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">lastName: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">emailAddress: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">password: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">roleIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CreateAssetInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CreateAssetInput</span> &#123;</div>
<div class="graphql-code-line ">file: <a href="/reference/graphql-api/admin/object-types#upload">Upload</a>!</div>

<div class="graphql-code-line ">tags: [<a href="/reference/graphql-api/admin/object-types#string">String</a>!]</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CreateChannelInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CreateChannelInput</span> &#123;</div>
<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">token: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">defaultLanguageCode: <a href="/reference/graphql-api/admin/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">availableLanguageCodes: [<a href="/reference/graphql-api/admin/enums#languagecode">LanguageCode</a>!]</div>

<div class="graphql-code-line ">pricesIncludeTax: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">currencyCode: <a href="/reference/graphql-api/admin/enums#currencycode">CurrencyCode</a></div>

<div class="graphql-code-line ">defaultCurrencyCode: <a href="/reference/graphql-api/admin/enums#currencycode">CurrencyCode</a></div>

<div class="graphql-code-line ">availableCurrencyCodes: [<a href="/reference/graphql-api/admin/enums#currencycode">CurrencyCode</a>!]</div>

<div class="graphql-code-line ">trackInventory: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">outOfStockThreshold: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line ">defaultTaxZoneId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">defaultShippingZoneId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">sellerId: <a href="/reference/graphql-api/admin/object-types#id">ID</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CreateCollectionInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CreateCollectionInput</span> &#123;</div>
<div class="graphql-code-line ">isPrivate: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">featuredAssetId: <a href="/reference/graphql-api/admin/object-types#id">ID</a></div>

<div class="graphql-code-line ">assetIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]</div>

<div class="graphql-code-line ">parentId: <a href="/reference/graphql-api/admin/object-types#id">ID</a></div>

<div class="graphql-code-line ">inheritFilters: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">filters: [<a href="/reference/graphql-api/admin/input-types#configurableoperationinput">ConfigurableOperationInput</a>!]!</div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/admin/input-types#createcollectiontranslationinput">CreateCollectionTranslationInput</a>!]!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CreateCollectionTranslationInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CreateCollectionTranslationInput</span> &#123;</div>
<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">slug: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CreateCountryInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CreateCountryInput</span> &#123;</div>
<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/admin/input-types#countrytranslationinput">CountryTranslationInput</a>!]!</div>

<div class="graphql-code-line ">enabled: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CreateCustomerGroupInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CreateCustomerGroupInput</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">customerIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CreateCustomerInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CreateCustomerInput</span> &#123;</div>
<div class="graphql-code-line ">title: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">firstName: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">lastName: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">phoneNumber: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">emailAddress: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CreateFacetInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CreateFacetInput</span> &#123;</div>
<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">isPrivate: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/admin/input-types#facettranslationinput">FacetTranslationInput</a>!]!</div>

<div class="graphql-code-line ">values: [<a href="/reference/graphql-api/admin/input-types#createfacetvaluewithfacetinput">CreateFacetValueWithFacetInput</a>!]</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CreateFacetValueInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CreateFacetValueInput</span> &#123;</div>
<div class="graphql-code-line ">facetId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/admin/input-types#facetvaluetranslationinput">FacetValueTranslationInput</a>!]!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CreateFacetValueWithFacetInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CreateFacetValueWithFacetInput</span> &#123;</div>
<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/admin/input-types#facetvaluetranslationinput">FacetValueTranslationInput</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CreateGroupOptionInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CreateGroupOptionInput</span> &#123;</div>
<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/admin/input-types#productoptiongrouptranslationinput">ProductOptionGroupTranslationInput</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CreatePaymentMethodInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CreatePaymentMethodInput</span> &#123;</div>
<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">enabled: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">checker: <a href="/reference/graphql-api/admin/input-types#configurableoperationinput">ConfigurableOperationInput</a></div>

<div class="graphql-code-line ">handler: <a href="/reference/graphql-api/admin/input-types#configurableoperationinput">ConfigurableOperationInput</a>!</div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/admin/input-types#paymentmethodtranslationinput">PaymentMethodTranslationInput</a>!]!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CreateProductInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CreateProductInput</span> &#123;</div>
<div class="graphql-code-line ">featuredAssetId: <a href="/reference/graphql-api/admin/object-types#id">ID</a></div>

<div class="graphql-code-line ">enabled: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">assetIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]</div>

<div class="graphql-code-line ">facetValueIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]</div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/admin/input-types#producttranslationinput">ProductTranslationInput</a>!]!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CreateProductOptionGroupInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CreateProductOptionGroupInput</span> &#123;</div>
<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/admin/input-types#productoptiongrouptranslationinput">ProductOptionGroupTranslationInput</a>!]!</div>

<div class="graphql-code-line ">options: [<a href="/reference/graphql-api/admin/input-types#creategroupoptioninput">CreateGroupOptionInput</a>!]!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CreateProductOptionInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CreateProductOptionInput</span> &#123;</div>
<div class="graphql-code-line ">productOptionGroupId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/admin/input-types#productoptiongrouptranslationinput">ProductOptionGroupTranslationInput</a>!]!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CreateProductVariantInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CreateProductVariantInput</span> &#123;</div>
<div class="graphql-code-line ">productId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">enabled: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/admin/input-types#productvarianttranslationinput">ProductVariantTranslationInput</a>!]!</div>

<div class="graphql-code-line ">facetValueIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]</div>

<div class="graphql-code-line ">sku: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">price: <a href="/reference/graphql-api/admin/object-types#money">Money</a></div>

<div class="graphql-code-line ">prices: [<a href="/reference/graphql-api/admin/input-types#createproductvariantpriceinput">CreateProductVariantPriceInput</a>]</div>

<div class="graphql-code-line ">taxCategoryId: <a href="/reference/graphql-api/admin/object-types#id">ID</a></div>

<div class="graphql-code-line ">optionIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]</div>

<div class="graphql-code-line ">featuredAssetId: <a href="/reference/graphql-api/admin/object-types#id">ID</a></div>

<div class="graphql-code-line ">assetIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]</div>

<div class="graphql-code-line ">stockOnHand: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line ">stockLevels: [<a href="/reference/graphql-api/admin/input-types#stocklevelinput">StockLevelInput</a>!]</div>

<div class="graphql-code-line ">outOfStockThreshold: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line ">useGlobalOutOfStockThreshold: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">trackInventory: <a href="/reference/graphql-api/admin/enums#globalflag">GlobalFlag</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CreateProductVariantOptionInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CreateProductVariantOptionInput</span> &#123;</div>
<div class="graphql-code-line ">optionGroupId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/admin/input-types#productoptiontranslationinput">ProductOptionTranslationInput</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CreateProductVariantPriceInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CreateProductVariantPriceInput</span> &#123;</div>
<div class="graphql-code-line ">currencyCode: <a href="/reference/graphql-api/admin/enums#currencycode">CurrencyCode</a>!</div>

<div class="graphql-code-line ">price: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CreatePromotionInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CreatePromotionInput</span> &#123;</div>
<div class="graphql-code-line ">enabled: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">startsAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a></div>

<div class="graphql-code-line ">endsAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a></div>

<div class="graphql-code-line ">couponCode: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">perCustomerUsageLimit: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line ">usageLimit: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line ">conditions: [<a href="/reference/graphql-api/admin/input-types#configurableoperationinput">ConfigurableOperationInput</a>!]!</div>

<div class="graphql-code-line ">actions: [<a href="/reference/graphql-api/admin/input-types#configurableoperationinput">ConfigurableOperationInput</a>!]!</div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/admin/input-types#promotiontranslationinput">PromotionTranslationInput</a>!]!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CreateProvinceInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CreateProvinceInput</span> &#123;</div>
<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/admin/input-types#provincetranslationinput">ProvinceTranslationInput</a>!]!</div>

<div class="graphql-code-line ">enabled: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CreateRoleInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CreateRoleInput</span> &#123;</div>
<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">permissions: [<a href="/reference/graphql-api/admin/enums#permission">Permission</a>!]!</div>

<div class="graphql-code-line ">channelIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CreateSellerInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CreateSellerInput</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CreateShippingMethodInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CreateShippingMethodInput</span> &#123;</div>
<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">fulfillmentHandler: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">checker: <a href="/reference/graphql-api/admin/input-types#configurableoperationinput">ConfigurableOperationInput</a>!</div>

<div class="graphql-code-line ">calculator: <a href="/reference/graphql-api/admin/input-types#configurableoperationinput">ConfigurableOperationInput</a>!</div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/admin/input-types#shippingmethodtranslationinput">ShippingMethodTranslationInput</a>!]!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CreateStockLocationInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CreateStockLocationInput</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CreateTagInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CreateTagInput</span> &#123;</div>
<div class="graphql-code-line ">value: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CreateTaxCategoryInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CreateTaxCategoryInput</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">isDefault: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CreateTaxRateInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CreateTaxRateInput</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">enabled: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">value: <a href="/reference/graphql-api/admin/object-types#float">Float</a>!</div>

<div class="graphql-code-line ">categoryId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">zoneId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">customerGroupId: <a href="/reference/graphql-api/admin/object-types#id">ID</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CreateZoneInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CreateZoneInput</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">memberIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CustomerFilterParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CustomerFilterParameter</span> &#123;</div>
<div class="graphql-code-line ">postalCode: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">title: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">firstName: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">lastName: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">phoneNumber: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">emailAddress: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">_and: [<a href="/reference/graphql-api/admin/input-types#customerfilterparameter">CustomerFilterParameter</a>!]</div>

<div class="graphql-code-line ">_or: [<a href="/reference/graphql-api/admin/input-types#customerfilterparameter">CustomerFilterParameter</a>!]</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CustomerGroupFilterParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CustomerGroupFilterParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">_and: [<a href="/reference/graphql-api/admin/input-types#customergroupfilterparameter">CustomerGroupFilterParameter</a>!]</div>

<div class="graphql-code-line ">_or: [<a href="/reference/graphql-api/admin/input-types#customergroupfilterparameter">CustomerGroupFilterParameter</a>!]</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CustomerGroupListOptions

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CustomerGroupListOptions</span> &#123;</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Skips the first n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">skip: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Takes n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">take: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies which properties to sort the results by</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">sort: <a href="/reference/graphql-api/admin/input-types#customergroupsortparameter">CustomerGroupSortParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Allows the results to be filtered</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filter: <a href="/reference/graphql-api/admin/input-types#customergroupfilterparameter">CustomerGroupFilterParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies whether multiple top-level "filter" fields should be combined with a logical AND or OR operation. Defaults to AND.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filterOperator: <a href="/reference/graphql-api/admin/enums#logicaloperator">LogicalOperator</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CustomerGroupSortParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CustomerGroupSortParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CustomerListOptions

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CustomerListOptions</span> &#123;</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Skips the first n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">skip: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Takes n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">take: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies which properties to sort the results by</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">sort: <a href="/reference/graphql-api/admin/input-types#customersortparameter">CustomerSortParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Allows the results to be filtered</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filter: <a href="/reference/graphql-api/admin/input-types#customerfilterparameter">CustomerFilterParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies whether multiple top-level "filter" fields should be combined with a logical AND or OR operation. Defaults to AND.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filterOperator: <a href="/reference/graphql-api/admin/enums#logicaloperator">LogicalOperator</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CustomerSortParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CustomerSortParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">title: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">firstName: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">lastName: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">phoneNumber: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">emailAddress: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## DateListOperators

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Operators for filtering on a list of Date fields</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">DateListOperators</span> &#123;</div>
<div class="graphql-code-line ">inList: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## DateOperators

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Operators for filtering on a DateTime field</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">DateOperators</span> &#123;</div>
<div class="graphql-code-line ">eq: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a></div>

<div class="graphql-code-line ">before: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a></div>

<div class="graphql-code-line ">after: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a></div>

<div class="graphql-code-line ">between: <a href="/reference/graphql-api/admin/input-types#daterange">DateRange</a></div>

<div class="graphql-code-line ">isNull: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## DateRange

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">DateRange</span> &#123;</div>
<div class="graphql-code-line ">start: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">end: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## DeleteAssetInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">DeleteAssetInput</span> &#123;</div>
<div class="graphql-code-line ">assetId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">force: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">deleteFromAllChannels: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## DeleteAssetsInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">DeleteAssetsInput</span> &#123;</div>
<div class="graphql-code-line ">assetIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!</div>

<div class="graphql-code-line ">force: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">deleteFromAllChannels: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## DeleteStockLocationInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">DeleteStockLocationInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">transferToLocationId: <a href="/reference/graphql-api/admin/object-types#id">ID</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## DuplicateEntityInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">DuplicateEntityInput</span> &#123;</div>
<div class="graphql-code-line ">entityName: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">entityId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">duplicatorInput: <a href="/reference/graphql-api/admin/input-types#configurableoperationinput">ConfigurableOperationInput</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## FacetFilterParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">FacetFilterParameter</span> &#123;</div>
<div class="graphql-code-line ">isPrivate: <a href="/reference/graphql-api/admin/input-types#booleanoperators">BooleanOperators</a></div>

<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">_and: [<a href="/reference/graphql-api/admin/input-types#facetfilterparameter">FacetFilterParameter</a>!]</div>

<div class="graphql-code-line ">_or: [<a href="/reference/graphql-api/admin/input-types#facetfilterparameter">FacetFilterParameter</a>!]</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## FacetListOptions

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">FacetListOptions</span> &#123;</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Skips the first n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">skip: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Takes n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">take: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies which properties to sort the results by</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">sort: <a href="/reference/graphql-api/admin/input-types#facetsortparameter">FacetSortParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Allows the results to be filtered</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filter: <a href="/reference/graphql-api/admin/input-types#facetfilterparameter">FacetFilterParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies whether multiple top-level "filter" fields should be combined with a logical AND or OR operation. Defaults to AND.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filterOperator: <a href="/reference/graphql-api/admin/enums#logicaloperator">LogicalOperator</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## FacetSortParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">FacetSortParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## FacetTranslationInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">FacetTranslationInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a></div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## FacetValueFilterInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Used to construct boolean expressions for filtering search results</div>

<div class="graphql-code-line top-level comment">by FacetValue ID. Examples:</div>

<div class="graphql-code-line top-level comment"></div>

<div class="graphql-code-line top-level comment">* ID=1 OR ID=2: `&#123; facetValueFilters: [&#123; or: [1,2] &#125;] &#125;`</div>

<div class="graphql-code-line top-level comment">* ID=1 AND ID=2: `&#123; facetValueFilters: [&#123; and: 1 &#125;, &#123; and: 2 &#125;] &#125;`</div>

<div class="graphql-code-line top-level comment">* ID=1 AND (ID=2 OR ID=3): `&#123; facetValueFilters: [&#123; and: 1 &#125;, &#123; or: [2,3] &#125;] &#125;`</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">FacetValueFilterInput</span> &#123;</div>
<div class="graphql-code-line ">and: <a href="/reference/graphql-api/admin/object-types#id">ID</a></div>

<div class="graphql-code-line ">or: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## FacetValueFilterParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">FacetValueFilterParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">facetId: <a href="/reference/graphql-api/admin/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">_and: [<a href="/reference/graphql-api/admin/input-types#facetvaluefilterparameter">FacetValueFilterParameter</a>!]</div>

<div class="graphql-code-line ">_or: [<a href="/reference/graphql-api/admin/input-types#facetvaluefilterparameter">FacetValueFilterParameter</a>!]</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## FacetValueListOptions

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">FacetValueListOptions</span> &#123;</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Skips the first n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">skip: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Takes n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">take: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies which properties to sort the results by</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">sort: <a href="/reference/graphql-api/admin/input-types#facetvaluesortparameter">FacetValueSortParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Allows the results to be filtered</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filter: <a href="/reference/graphql-api/admin/input-types#facetvaluefilterparameter">FacetValueFilterParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies whether multiple top-level "filter" fields should be combined with a logical AND or OR operation. Defaults to AND.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filterOperator: <a href="/reference/graphql-api/admin/enums#logicaloperator">LogicalOperator</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## FacetValueSortParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">FacetValueSortParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">facetId: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## FacetValueTranslationInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">FacetValueTranslationInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a></div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## FulfillOrderInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">FulfillOrderInput</span> &#123;</div>
<div class="graphql-code-line ">lines: [<a href="/reference/graphql-api/admin/input-types#orderlineinput">OrderLineInput</a>!]!</div>

<div class="graphql-code-line ">handler: <a href="/reference/graphql-api/admin/input-types#configurableoperationinput">ConfigurableOperationInput</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## HistoryEntryFilterParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">HistoryEntryFilterParameter</span> &#123;</div>
<div class="graphql-code-line ">isPublic: <a href="/reference/graphql-api/admin/input-types#booleanoperators">BooleanOperators</a></div>

<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">_and: [<a href="/reference/graphql-api/admin/input-types#historyentryfilterparameter">HistoryEntryFilterParameter</a>!]</div>

<div class="graphql-code-line ">_or: [<a href="/reference/graphql-api/admin/input-types#historyentryfilterparameter">HistoryEntryFilterParameter</a>!]</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## HistoryEntryListOptions

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">HistoryEntryListOptions</span> &#123;</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Skips the first n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">skip: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Takes n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">take: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies which properties to sort the results by</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">sort: <a href="/reference/graphql-api/admin/input-types#historyentrysortparameter">HistoryEntrySortParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Allows the results to be filtered</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filter: <a href="/reference/graphql-api/admin/input-types#historyentryfilterparameter">HistoryEntryFilterParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies whether multiple top-level "filter" fields should be combined with a logical AND or OR operation. Defaults to AND.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filterOperator: <a href="/reference/graphql-api/admin/enums#logicaloperator">LogicalOperator</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## HistoryEntrySortParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">HistoryEntrySortParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## IDListOperators

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Operators for filtering on a list of ID fields</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">IDListOperators</span> &#123;</div>
<div class="graphql-code-line ">inList: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## IDOperators

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Operators for filtering on an ID field</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">IDOperators</span> &#123;</div>
<div class="graphql-code-line ">eq: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">notEq: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">in: [<a href="/reference/graphql-api/admin/object-types#string">String</a>!]</div>

<div class="graphql-code-line ">notIn: [<a href="/reference/graphql-api/admin/object-types#string">String</a>!]</div>

<div class="graphql-code-line ">isNull: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## JobFilterParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">JobFilterParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">startedAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">settledAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">queueName: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">state: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">progress: <a href="/reference/graphql-api/admin/input-types#numberoperators">NumberOperators</a></div>

<div class="graphql-code-line ">isSettled: <a href="/reference/graphql-api/admin/input-types#booleanoperators">BooleanOperators</a></div>

<div class="graphql-code-line ">duration: <a href="/reference/graphql-api/admin/input-types#numberoperators">NumberOperators</a></div>

<div class="graphql-code-line ">retries: <a href="/reference/graphql-api/admin/input-types#numberoperators">NumberOperators</a></div>

<div class="graphql-code-line ">attempts: <a href="/reference/graphql-api/admin/input-types#numberoperators">NumberOperators</a></div>

<div class="graphql-code-line ">_and: [<a href="/reference/graphql-api/admin/input-types#jobfilterparameter">JobFilterParameter</a>!]</div>

<div class="graphql-code-line ">_or: [<a href="/reference/graphql-api/admin/input-types#jobfilterparameter">JobFilterParameter</a>!]</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## JobListOptions

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">JobListOptions</span> &#123;</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Skips the first n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">skip: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Takes n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">take: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies which properties to sort the results by</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">sort: <a href="/reference/graphql-api/admin/input-types#jobsortparameter">JobSortParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Allows the results to be filtered</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filter: <a href="/reference/graphql-api/admin/input-types#jobfilterparameter">JobFilterParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies whether multiple top-level "filter" fields should be combined with a logical AND or OR operation. Defaults to AND.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filterOperator: <a href="/reference/graphql-api/admin/enums#logicaloperator">LogicalOperator</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## JobSortParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">JobSortParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">startedAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">settledAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">queueName: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">progress: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">duration: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">retries: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">attempts: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ManualPaymentInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">ManualPaymentInput</span> &#123;</div>
<div class="graphql-code-line ">orderId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">method: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">transactionId: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">metadata: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## MetricSummaryInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">MetricSummaryInput</span> &#123;</div>
<div class="graphql-code-line ">interval: <a href="/reference/graphql-api/admin/enums#metricinterval">MetricInterval</a>!</div>

<div class="graphql-code-line ">types: [<a href="/reference/graphql-api/admin/enums#metrictype">MetricType</a>!]!</div>

<div class="graphql-code-line ">refresh: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ModifyOrderInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">ModifyOrderInput</span> &#123;</div>
<div class="graphql-code-line ">dryRun: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">orderId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">addItems: [<a href="/reference/graphql-api/admin/input-types#additeminput">AddItemInput</a>!]</div>

<div class="graphql-code-line ">adjustOrderLines: [<a href="/reference/graphql-api/admin/input-types#orderlineinput">OrderLineInput</a>!]</div>

<div class="graphql-code-line ">surcharges: [<a href="/reference/graphql-api/admin/input-types#surchargeinput">SurchargeInput</a>!]</div>

<div class="graphql-code-line ">updateShippingAddress: <a href="/reference/graphql-api/admin/input-types#updateorderaddressinput">UpdateOrderAddressInput</a></div>

<div class="graphql-code-line ">updateBillingAddress: <a href="/reference/graphql-api/admin/input-types#updateorderaddressinput">UpdateOrderAddressInput</a></div>

<div class="graphql-code-line ">note: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Deprecated in v2.2.0. Use <code>refunds</code> instead to allow multiple refunds to be</div>

<div class="graphql-code-line comment">applied in the case that multiple payment methods have been used on the order.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">refund: <a href="/reference/graphql-api/admin/input-types#administratorrefundinput">AdministratorRefundInput</a></div>

<div class="graphql-code-line ">refunds: [<a href="/reference/graphql-api/admin/input-types#administratorrefundinput">AdministratorRefundInput</a>!]</div>

<div class="graphql-code-line ">options: <a href="/reference/graphql-api/admin/input-types#modifyorderoptions">ModifyOrderOptions</a></div>

<div class="graphql-code-line ">couponCodes: [<a href="/reference/graphql-api/admin/object-types#string">String</a>!]</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Added in v2.2</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">shippingMethodIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ModifyOrderOptions

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">ModifyOrderOptions</span> &#123;</div>
<div class="graphql-code-line ">freezePromotions: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">recalculateShipping: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## MoveCollectionInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">MoveCollectionInput</span> &#123;</div>
<div class="graphql-code-line ">collectionId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">parentId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">index: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## NativeAuthInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">NativeAuthInput</span> &#123;</div>
<div class="graphql-code-line ">username: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">password: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## NumberListOperators

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Operators for filtering on a list of Number fields</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">NumberListOperators</span> &#123;</div>
<div class="graphql-code-line ">inList: <a href="/reference/graphql-api/admin/object-types#float">Float</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## NumberOperators

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Operators for filtering on a Int or Float field</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">NumberOperators</span> &#123;</div>
<div class="graphql-code-line ">eq: <a href="/reference/graphql-api/admin/object-types#float">Float</a></div>

<div class="graphql-code-line ">lt: <a href="/reference/graphql-api/admin/object-types#float">Float</a></div>

<div class="graphql-code-line ">lte: <a href="/reference/graphql-api/admin/object-types#float">Float</a></div>

<div class="graphql-code-line ">gt: <a href="/reference/graphql-api/admin/object-types#float">Float</a></div>

<div class="graphql-code-line ">gte: <a href="/reference/graphql-api/admin/object-types#float">Float</a></div>

<div class="graphql-code-line ">between: <a href="/reference/graphql-api/admin/input-types#numberrange">NumberRange</a></div>

<div class="graphql-code-line ">isNull: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## NumberRange

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">NumberRange</span> &#123;</div>
<div class="graphql-code-line ">start: <a href="/reference/graphql-api/admin/object-types#float">Float</a>!</div>

<div class="graphql-code-line ">end: <a href="/reference/graphql-api/admin/object-types#float">Float</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## OrderFilterParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">OrderFilterParameter</span> &#123;</div>
<div class="graphql-code-line ">customerLastName: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">transactionId: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">aggregateOrderId: <a href="/reference/graphql-api/admin/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">orderPlacedAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">state: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">active: <a href="/reference/graphql-api/admin/input-types#booleanoperators">BooleanOperators</a></div>

<div class="graphql-code-line ">totalQuantity: <a href="/reference/graphql-api/admin/input-types#numberoperators">NumberOperators</a></div>

<div class="graphql-code-line ">subTotal: <a href="/reference/graphql-api/admin/input-types#numberoperators">NumberOperators</a></div>

<div class="graphql-code-line ">subTotalWithTax: <a href="/reference/graphql-api/admin/input-types#numberoperators">NumberOperators</a></div>

<div class="graphql-code-line ">currencyCode: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">shipping: <a href="/reference/graphql-api/admin/input-types#numberoperators">NumberOperators</a></div>

<div class="graphql-code-line ">shippingWithTax: <a href="/reference/graphql-api/admin/input-types#numberoperators">NumberOperators</a></div>

<div class="graphql-code-line ">total: <a href="/reference/graphql-api/admin/input-types#numberoperators">NumberOperators</a></div>

<div class="graphql-code-line ">totalWithTax: <a href="/reference/graphql-api/admin/input-types#numberoperators">NumberOperators</a></div>

<div class="graphql-code-line ">_and: [<a href="/reference/graphql-api/admin/input-types#orderfilterparameter">OrderFilterParameter</a>!]</div>

<div class="graphql-code-line ">_or: [<a href="/reference/graphql-api/admin/input-types#orderfilterparameter">OrderFilterParameter</a>!]</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## OrderLineInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">OrderLineInput</span> &#123;</div>
<div class="graphql-code-line ">orderLineId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">quantity: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## OrderListOptions

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">OrderListOptions</span> &#123;</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Skips the first n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">skip: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Takes n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">take: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies which properties to sort the results by</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">sort: <a href="/reference/graphql-api/admin/input-types#ordersortparameter">OrderSortParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Allows the results to be filtered</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filter: <a href="/reference/graphql-api/admin/input-types#orderfilterparameter">OrderFilterParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies whether multiple top-level "filter" fields should be combined with a logical AND or OR operation. Defaults to AND.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filterOperator: <a href="/reference/graphql-api/admin/enums#logicaloperator">LogicalOperator</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## OrderSortParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">OrderSortParameter</span> &#123;</div>
<div class="graphql-code-line ">customerLastName: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">transactionId: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">aggregateOrderId: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">orderPlacedAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">state: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">totalQuantity: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">subTotal: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">subTotalWithTax: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">shipping: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">shippingWithTax: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">total: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">totalWithTax: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## PaymentMethodFilterParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">PaymentMethodFilterParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">enabled: <a href="/reference/graphql-api/admin/input-types#booleanoperators">BooleanOperators</a></div>

<div class="graphql-code-line ">_and: [<a href="/reference/graphql-api/admin/input-types#paymentmethodfilterparameter">PaymentMethodFilterParameter</a>!]</div>

<div class="graphql-code-line ">_or: [<a href="/reference/graphql-api/admin/input-types#paymentmethodfilterparameter">PaymentMethodFilterParameter</a>!]</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## PaymentMethodListOptions

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">PaymentMethodListOptions</span> &#123;</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Skips the first n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">skip: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Takes n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">take: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies which properties to sort the results by</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">sort: <a href="/reference/graphql-api/admin/input-types#paymentmethodsortparameter">PaymentMethodSortParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Allows the results to be filtered</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filter: <a href="/reference/graphql-api/admin/input-types#paymentmethodfilterparameter">PaymentMethodFilterParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies whether multiple top-level "filter" fields should be combined with a logical AND or OR operation. Defaults to AND.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filterOperator: <a href="/reference/graphql-api/admin/enums#logicaloperator">LogicalOperator</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## PaymentMethodSortParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">PaymentMethodSortParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## PaymentMethodTranslationInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">PaymentMethodTranslationInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a></div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## PreviewCollectionVariantsInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">PreviewCollectionVariantsInput</span> &#123;</div>
<div class="graphql-code-line ">parentId: <a href="/reference/graphql-api/admin/object-types#id">ID</a></div>

<div class="graphql-code-line ">inheritFilters: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">filters: [<a href="/reference/graphql-api/admin/input-types#configurableoperationinput">ConfigurableOperationInput</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ProductFilterParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">ProductFilterParameter</span> &#123;</div>
<div class="graphql-code-line ">facetValueId: <a href="/reference/graphql-api/admin/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">sku: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">slug: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">enabled: <a href="/reference/graphql-api/admin/input-types#booleanoperators">BooleanOperators</a></div>

<div class="graphql-code-line ">_and: [<a href="/reference/graphql-api/admin/input-types#productfilterparameter">ProductFilterParameter</a>!]</div>

<div class="graphql-code-line ">_or: [<a href="/reference/graphql-api/admin/input-types#productfilterparameter">ProductFilterParameter</a>!]</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ProductListOptions

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">ProductListOptions</span> &#123;</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Skips the first n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">skip: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Takes n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">take: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies which properties to sort the results by</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">sort: <a href="/reference/graphql-api/admin/input-types#productsortparameter">ProductSortParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Allows the results to be filtered</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filter: <a href="/reference/graphql-api/admin/input-types#productfilterparameter">ProductFilterParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies whether multiple top-level "filter" fields should be combined with a logical AND or OR operation. Defaults to AND.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filterOperator: <a href="/reference/graphql-api/admin/enums#logicaloperator">LogicalOperator</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ProductOptionGroupTranslationInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">ProductOptionGroupTranslationInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a></div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ProductOptionTranslationInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">ProductOptionTranslationInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a></div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ProductSortParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">ProductSortParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">slug: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ProductTranslationInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">ProductTranslationInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a></div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">slug: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ProductVariantFilterParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">ProductVariantFilterParameter</span> &#123;</div>
<div class="graphql-code-line ">facetValueId: <a href="/reference/graphql-api/admin/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">enabled: <a href="/reference/graphql-api/admin/input-types#booleanoperators">BooleanOperators</a></div>

<div class="graphql-code-line ">trackInventory: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">stockOnHand: <a href="/reference/graphql-api/admin/input-types#numberoperators">NumberOperators</a></div>

<div class="graphql-code-line ">stockAllocated: <a href="/reference/graphql-api/admin/input-types#numberoperators">NumberOperators</a></div>

<div class="graphql-code-line ">outOfStockThreshold: <a href="/reference/graphql-api/admin/input-types#numberoperators">NumberOperators</a></div>

<div class="graphql-code-line ">useGlobalOutOfStockThreshold: <a href="/reference/graphql-api/admin/input-types#booleanoperators">BooleanOperators</a></div>

<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">productId: <a href="/reference/graphql-api/admin/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">sku: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">price: <a href="/reference/graphql-api/admin/input-types#numberoperators">NumberOperators</a></div>

<div class="graphql-code-line ">currencyCode: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">priceWithTax: <a href="/reference/graphql-api/admin/input-types#numberoperators">NumberOperators</a></div>

<div class="graphql-code-line ">stockLevel: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">_and: [<a href="/reference/graphql-api/admin/input-types#productvariantfilterparameter">ProductVariantFilterParameter</a>!]</div>

<div class="graphql-code-line ">_or: [<a href="/reference/graphql-api/admin/input-types#productvariantfilterparameter">ProductVariantFilterParameter</a>!]</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ProductVariantListOptions

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">ProductVariantListOptions</span> &#123;</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Skips the first n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">skip: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Takes n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">take: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies which properties to sort the results by</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">sort: <a href="/reference/graphql-api/admin/input-types#productvariantsortparameter">ProductVariantSortParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Allows the results to be filtered</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filter: <a href="/reference/graphql-api/admin/input-types#productvariantfilterparameter">ProductVariantFilterParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies whether multiple top-level "filter" fields should be combined with a logical AND or OR operation. Defaults to AND.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filterOperator: <a href="/reference/graphql-api/admin/enums#logicaloperator">LogicalOperator</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ProductVariantSortParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">ProductVariantSortParameter</span> &#123;</div>
<div class="graphql-code-line ">stockOnHand: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">stockAllocated: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">outOfStockThreshold: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">productId: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">sku: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">price: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">priceWithTax: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">stockLevel: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ProductVariantTranslationInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">ProductVariantTranslationInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a></div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## PromotionFilterParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">PromotionFilterParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">startsAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">endsAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">couponCode: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">perCustomerUsageLimit: <a href="/reference/graphql-api/admin/input-types#numberoperators">NumberOperators</a></div>

<div class="graphql-code-line ">usageLimit: <a href="/reference/graphql-api/admin/input-types#numberoperators">NumberOperators</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">enabled: <a href="/reference/graphql-api/admin/input-types#booleanoperators">BooleanOperators</a></div>

<div class="graphql-code-line ">_and: [<a href="/reference/graphql-api/admin/input-types#promotionfilterparameter">PromotionFilterParameter</a>!]</div>

<div class="graphql-code-line ">_or: [<a href="/reference/graphql-api/admin/input-types#promotionfilterparameter">PromotionFilterParameter</a>!]</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## PromotionListOptions

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">PromotionListOptions</span> &#123;</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Skips the first n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">skip: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Takes n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">take: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies which properties to sort the results by</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">sort: <a href="/reference/graphql-api/admin/input-types#promotionsortparameter">PromotionSortParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Allows the results to be filtered</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filter: <a href="/reference/graphql-api/admin/input-types#promotionfilterparameter">PromotionFilterParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies whether multiple top-level "filter" fields should be combined with a logical AND or OR operation. Defaults to AND.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filterOperator: <a href="/reference/graphql-api/admin/enums#logicaloperator">LogicalOperator</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## PromotionSortParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">PromotionSortParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">startsAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">endsAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">couponCode: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">perCustomerUsageLimit: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">usageLimit: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## PromotionTranslationInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">PromotionTranslationInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a></div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ProvinceFilterParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">ProvinceFilterParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">enabled: <a href="/reference/graphql-api/admin/input-types#booleanoperators">BooleanOperators</a></div>

<div class="graphql-code-line ">parentId: <a href="/reference/graphql-api/admin/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">_and: [<a href="/reference/graphql-api/admin/input-types#provincefilterparameter">ProvinceFilterParameter</a>!]</div>

<div class="graphql-code-line ">_or: [<a href="/reference/graphql-api/admin/input-types#provincefilterparameter">ProvinceFilterParameter</a>!]</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ProvinceListOptions

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">ProvinceListOptions</span> &#123;</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Skips the first n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">skip: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Takes n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">take: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies which properties to sort the results by</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">sort: <a href="/reference/graphql-api/admin/input-types#provincesortparameter">ProvinceSortParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Allows the results to be filtered</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filter: <a href="/reference/graphql-api/admin/input-types#provincefilterparameter">ProvinceFilterParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies whether multiple top-level "filter" fields should be combined with a logical AND or OR operation. Defaults to AND.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filterOperator: <a href="/reference/graphql-api/admin/enums#logicaloperator">LogicalOperator</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ProvinceSortParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">ProvinceSortParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">parentId: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ProvinceTranslationInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">ProvinceTranslationInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a></div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## RefundOrderInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">RefundOrderInput</span> &#123;</div>
<div class="graphql-code-line ">lines: [<a href="/reference/graphql-api/admin/input-types#orderlineinput">OrderLineInput</a>!]</div>

<div class="graphql-code-line ">shipping: <a href="/reference/graphql-api/admin/object-types#money">Money</a></div>

<div class="graphql-code-line ">adjustment: <a href="/reference/graphql-api/admin/object-types#money">Money</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The amount to be refunded to this particular payment. This was introduced in v2.2.0 as the preferred way to specify the refund amount.</div>

<div class="graphql-code-line comment">Can be as much as the total amount of the payment minus the sum of all previous refunds.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">amount: <a href="/reference/graphql-api/admin/object-types#money">Money</a></div>

<div class="graphql-code-line ">paymentId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">reason: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## RemoveCollectionsFromChannelInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">RemoveCollectionsFromChannelInput</span> &#123;</div>
<div class="graphql-code-line ">collectionIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!</div>

<div class="graphql-code-line ">channelId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## RemoveFacetsFromChannelInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">RemoveFacetsFromChannelInput</span> &#123;</div>
<div class="graphql-code-line ">facetIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!</div>

<div class="graphql-code-line ">channelId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">force: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## RemovePaymentMethodsFromChannelInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">RemovePaymentMethodsFromChannelInput</span> &#123;</div>
<div class="graphql-code-line ">paymentMethodIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!</div>

<div class="graphql-code-line ">channelId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## RemoveProductVariantsFromChannelInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">RemoveProductVariantsFromChannelInput</span> &#123;</div>
<div class="graphql-code-line ">productVariantIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!</div>

<div class="graphql-code-line ">channelId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## RemoveProductsFromChannelInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">RemoveProductsFromChannelInput</span> &#123;</div>
<div class="graphql-code-line ">productIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!</div>

<div class="graphql-code-line ">channelId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## RemovePromotionsFromChannelInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">RemovePromotionsFromChannelInput</span> &#123;</div>
<div class="graphql-code-line ">promotionIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!</div>

<div class="graphql-code-line ">channelId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## RemoveShippingMethodsFromChannelInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">RemoveShippingMethodsFromChannelInput</span> &#123;</div>
<div class="graphql-code-line ">shippingMethodIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!</div>

<div class="graphql-code-line ">channelId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## RemoveStockLocationsFromChannelInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">RemoveStockLocationsFromChannelInput</span> &#123;</div>
<div class="graphql-code-line ">stockLocationIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!</div>

<div class="graphql-code-line ">channelId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## RoleFilterParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">RoleFilterParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">_and: [<a href="/reference/graphql-api/admin/input-types#rolefilterparameter">RoleFilterParameter</a>!]</div>

<div class="graphql-code-line ">_or: [<a href="/reference/graphql-api/admin/input-types#rolefilterparameter">RoleFilterParameter</a>!]</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## RoleListOptions

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">RoleListOptions</span> &#123;</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Skips the first n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">skip: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Takes n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">take: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies which properties to sort the results by</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">sort: <a href="/reference/graphql-api/admin/input-types#rolesortparameter">RoleSortParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Allows the results to be filtered</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filter: <a href="/reference/graphql-api/admin/input-types#rolefilterparameter">RoleFilterParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies whether multiple top-level "filter" fields should be combined with a logical AND or OR operation. Defaults to AND.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filterOperator: <a href="/reference/graphql-api/admin/enums#logicaloperator">LogicalOperator</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## RoleSortParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">RoleSortParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## SearchInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">SearchInput</span> &#123;</div>
<div class="graphql-code-line ">term: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">facetValueIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]</div>

<div class="graphql-code-line ">facetValueOperator: <a href="/reference/graphql-api/admin/enums#logicaloperator">LogicalOperator</a></div>

<div class="graphql-code-line ">facetValueFilters: [<a href="/reference/graphql-api/admin/input-types#facetvaluefilterinput">FacetValueFilterInput</a>!]</div>

<div class="graphql-code-line ">collectionId: <a href="/reference/graphql-api/admin/object-types#id">ID</a></div>

<div class="graphql-code-line ">collectionSlug: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">groupByProduct: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">take: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line ">skip: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line ">sort: <a href="/reference/graphql-api/admin/input-types#searchresultsortparameter">SearchResultSortParameter</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## SearchResultSortParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">SearchResultSortParameter</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">price: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## SellerFilterParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">SellerFilterParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">_and: [<a href="/reference/graphql-api/admin/input-types#sellerfilterparameter">SellerFilterParameter</a>!]</div>

<div class="graphql-code-line ">_or: [<a href="/reference/graphql-api/admin/input-types#sellerfilterparameter">SellerFilterParameter</a>!]</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## SellerListOptions

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">SellerListOptions</span> &#123;</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Skips the first n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">skip: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Takes n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">take: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies which properties to sort the results by</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">sort: <a href="/reference/graphql-api/admin/input-types#sellersortparameter">SellerSortParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Allows the results to be filtered</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filter: <a href="/reference/graphql-api/admin/input-types#sellerfilterparameter">SellerFilterParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies whether multiple top-level "filter" fields should be combined with a logical AND or OR operation. Defaults to AND.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filterOperator: <a href="/reference/graphql-api/admin/enums#logicaloperator">LogicalOperator</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## SellerSortParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">SellerSortParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## SetOrderCustomerInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">SetOrderCustomerInput</span> &#123;</div>
<div class="graphql-code-line ">orderId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">customerId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">note: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## SettingsStoreInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">SettingsStoreInput</span> &#123;</div>
<div class="graphql-code-line ">key: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">value: <a href="/reference/graphql-api/admin/object-types#json">JSON</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## SettleRefundInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">SettleRefundInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">transactionId: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ShippingMethodFilterParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">ShippingMethodFilterParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">fulfillmentHandlerCode: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">_and: [<a href="/reference/graphql-api/admin/input-types#shippingmethodfilterparameter">ShippingMethodFilterParameter</a>!]</div>

<div class="graphql-code-line ">_or: [<a href="/reference/graphql-api/admin/input-types#shippingmethodfilterparameter">ShippingMethodFilterParameter</a>!]</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ShippingMethodListOptions

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">ShippingMethodListOptions</span> &#123;</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Skips the first n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">skip: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Takes n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">take: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies which properties to sort the results by</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">sort: <a href="/reference/graphql-api/admin/input-types#shippingmethodsortparameter">ShippingMethodSortParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Allows the results to be filtered</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filter: <a href="/reference/graphql-api/admin/input-types#shippingmethodfilterparameter">ShippingMethodFilterParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies whether multiple top-level "filter" fields should be combined with a logical AND or OR operation. Defaults to AND.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filterOperator: <a href="/reference/graphql-api/admin/enums#logicaloperator">LogicalOperator</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ShippingMethodSortParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">ShippingMethodSortParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">fulfillmentHandlerCode: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ShippingMethodTranslationInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">ShippingMethodTranslationInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a></div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## StockLevelInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">StockLevelInput</span> &#123;</div>
<div class="graphql-code-line ">stockLocationId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">stockOnHand: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## StockLocationFilterParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">StockLocationFilterParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">_and: [<a href="/reference/graphql-api/admin/input-types#stocklocationfilterparameter">StockLocationFilterParameter</a>!]</div>

<div class="graphql-code-line ">_or: [<a href="/reference/graphql-api/admin/input-types#stocklocationfilterparameter">StockLocationFilterParameter</a>!]</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## StockLocationListOptions

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">StockLocationListOptions</span> &#123;</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Skips the first n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">skip: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Takes n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">take: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies which properties to sort the results by</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">sort: <a href="/reference/graphql-api/admin/input-types#stocklocationsortparameter">StockLocationSortParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Allows the results to be filtered</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filter: <a href="/reference/graphql-api/admin/input-types#stocklocationfilterparameter">StockLocationFilterParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies whether multiple top-level "filter" fields should be combined with a logical AND or OR operation. Defaults to AND.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filterOperator: <a href="/reference/graphql-api/admin/enums#logicaloperator">LogicalOperator</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## StockLocationSortParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">StockLocationSortParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## StockMovementListOptions

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">StockMovementListOptions</span> &#123;</div>
<div class="graphql-code-line ">type: <a href="/reference/graphql-api/admin/enums#stockmovementtype">StockMovementType</a></div>

<div class="graphql-code-line ">skip: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line ">take: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## StringListOperators

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Operators for filtering on a list of String fields</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">StringListOperators</span> &#123;</div>
<div class="graphql-code-line ">inList: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## StringOperators

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Operators for filtering on a String field</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">StringOperators</span> &#123;</div>
<div class="graphql-code-line ">eq: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">notEq: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">contains: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">notContains: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">in: [<a href="/reference/graphql-api/admin/object-types#string">String</a>!]</div>

<div class="graphql-code-line ">notIn: [<a href="/reference/graphql-api/admin/object-types#string">String</a>!]</div>

<div class="graphql-code-line ">regex: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">isNull: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## SurchargeInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">SurchargeInput</span> &#123;</div>
<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">sku: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">price: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">priceIncludesTax: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">taxRate: <a href="/reference/graphql-api/admin/object-types#float">Float</a></div>

<div class="graphql-code-line ">taxDescription: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## TagFilterParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">TagFilterParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">value: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">_and: [<a href="/reference/graphql-api/admin/input-types#tagfilterparameter">TagFilterParameter</a>!]</div>

<div class="graphql-code-line ">_or: [<a href="/reference/graphql-api/admin/input-types#tagfilterparameter">TagFilterParameter</a>!]</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## TagListOptions

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">TagListOptions</span> &#123;</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Skips the first n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">skip: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Takes n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">take: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies which properties to sort the results by</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">sort: <a href="/reference/graphql-api/admin/input-types#tagsortparameter">TagSortParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Allows the results to be filtered</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filter: <a href="/reference/graphql-api/admin/input-types#tagfilterparameter">TagFilterParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies whether multiple top-level "filter" fields should be combined with a logical AND or OR operation. Defaults to AND.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filterOperator: <a href="/reference/graphql-api/admin/enums#logicaloperator">LogicalOperator</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## TagSortParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">TagSortParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">value: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## TaxCategoryFilterParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">TaxCategoryFilterParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">isDefault: <a href="/reference/graphql-api/admin/input-types#booleanoperators">BooleanOperators</a></div>

<div class="graphql-code-line ">_and: [<a href="/reference/graphql-api/admin/input-types#taxcategoryfilterparameter">TaxCategoryFilterParameter</a>!]</div>

<div class="graphql-code-line ">_or: [<a href="/reference/graphql-api/admin/input-types#taxcategoryfilterparameter">TaxCategoryFilterParameter</a>!]</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## TaxCategoryListOptions

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">TaxCategoryListOptions</span> &#123;</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Skips the first n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">skip: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Takes n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">take: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies which properties to sort the results by</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">sort: <a href="/reference/graphql-api/admin/input-types#taxcategorysortparameter">TaxCategorySortParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Allows the results to be filtered</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filter: <a href="/reference/graphql-api/admin/input-types#taxcategoryfilterparameter">TaxCategoryFilterParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies whether multiple top-level "filter" fields should be combined with a logical AND or OR operation. Defaults to AND.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filterOperator: <a href="/reference/graphql-api/admin/enums#logicaloperator">LogicalOperator</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## TaxCategorySortParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">TaxCategorySortParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## TaxRateFilterParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">TaxRateFilterParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">enabled: <a href="/reference/graphql-api/admin/input-types#booleanoperators">BooleanOperators</a></div>

<div class="graphql-code-line ">value: <a href="/reference/graphql-api/admin/input-types#numberoperators">NumberOperators</a></div>

<div class="graphql-code-line ">_and: [<a href="/reference/graphql-api/admin/input-types#taxratefilterparameter">TaxRateFilterParameter</a>!]</div>

<div class="graphql-code-line ">_or: [<a href="/reference/graphql-api/admin/input-types#taxratefilterparameter">TaxRateFilterParameter</a>!]</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## TaxRateListOptions

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">TaxRateListOptions</span> &#123;</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Skips the first n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">skip: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Takes n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">take: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies which properties to sort the results by</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">sort: <a href="/reference/graphql-api/admin/input-types#taxratesortparameter">TaxRateSortParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Allows the results to be filtered</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filter: <a href="/reference/graphql-api/admin/input-types#taxratefilterparameter">TaxRateFilterParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies whether multiple top-level "filter" fields should be combined with a logical AND or OR operation. Defaults to AND.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filterOperator: <a href="/reference/graphql-api/admin/enums#logicaloperator">LogicalOperator</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## TaxRateSortParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">TaxRateSortParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">value: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## TestEligibleShippingMethodsInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">TestEligibleShippingMethodsInput</span> &#123;</div>
<div class="graphql-code-line ">shippingAddress: <a href="/reference/graphql-api/admin/input-types#createaddressinput">CreateAddressInput</a>!</div>

<div class="graphql-code-line ">lines: [<a href="/reference/graphql-api/admin/input-types#testshippingmethodorderlineinput">TestShippingMethodOrderLineInput</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## TestShippingMethodInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">TestShippingMethodInput</span> &#123;</div>
<div class="graphql-code-line ">checker: <a href="/reference/graphql-api/admin/input-types#configurableoperationinput">ConfigurableOperationInput</a>!</div>

<div class="graphql-code-line ">calculator: <a href="/reference/graphql-api/admin/input-types#configurableoperationinput">ConfigurableOperationInput</a>!</div>

<div class="graphql-code-line ">shippingAddress: <a href="/reference/graphql-api/admin/input-types#createaddressinput">CreateAddressInput</a>!</div>

<div class="graphql-code-line ">lines: [<a href="/reference/graphql-api/admin/input-types#testshippingmethodorderlineinput">TestShippingMethodOrderLineInput</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## TestShippingMethodOrderLineInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">TestShippingMethodOrderLineInput</span> &#123;</div>
<div class="graphql-code-line ">productVariantId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">quantity: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## UpdateActiveAdministratorInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">UpdateActiveAdministratorInput</span> &#123;</div>
<div class="graphql-code-line ">firstName: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">lastName: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">emailAddress: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">password: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## UpdateAddressInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Input used to update an Address.</div>

<div class="graphql-code-line top-level comment"></div>

<div class="graphql-code-line top-level comment">The countryCode must correspond to a <code>code</code> property of a Country that has been defined in the</div>

<div class="graphql-code-line top-level comment">Vendure server. The <code>code</code> property is typically a 2-character ISO code such as "GB", "US", "DE" etc.</div>

<div class="graphql-code-line top-level comment">If an invalid code is passed, the mutation will fail.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">UpdateAddressInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">fullName: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">company: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">streetLine1: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">streetLine2: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">city: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">province: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">postalCode: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">countryCode: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">phoneNumber: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">defaultShippingAddress: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">defaultBillingAddress: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## UpdateAdministratorInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">UpdateAdministratorInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">firstName: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">lastName: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">emailAddress: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">password: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">roleIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## UpdateAssetInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">UpdateAssetInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">focalPoint: <a href="/reference/graphql-api/admin/input-types#coordinateinput">CoordinateInput</a></div>

<div class="graphql-code-line ">tags: [<a href="/reference/graphql-api/admin/object-types#string">String</a>!]</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## UpdateChannelInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">UpdateChannelInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">token: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">defaultLanguageCode: <a href="/reference/graphql-api/admin/enums#languagecode">LanguageCode</a></div>

<div class="graphql-code-line ">availableLanguageCodes: [<a href="/reference/graphql-api/admin/enums#languagecode">LanguageCode</a>!]</div>

<div class="graphql-code-line ">pricesIncludeTax: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">currencyCode: <a href="/reference/graphql-api/admin/enums#currencycode">CurrencyCode</a></div>

<div class="graphql-code-line ">defaultCurrencyCode: <a href="/reference/graphql-api/admin/enums#currencycode">CurrencyCode</a></div>

<div class="graphql-code-line ">availableCurrencyCodes: [<a href="/reference/graphql-api/admin/enums#currencycode">CurrencyCode</a>!]</div>

<div class="graphql-code-line ">trackInventory: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">outOfStockThreshold: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line ">defaultTaxZoneId: <a href="/reference/graphql-api/admin/object-types#id">ID</a></div>

<div class="graphql-code-line ">defaultShippingZoneId: <a href="/reference/graphql-api/admin/object-types#id">ID</a></div>

<div class="graphql-code-line ">sellerId: <a href="/reference/graphql-api/admin/object-types#id">ID</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## UpdateCollectionInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">UpdateCollectionInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">isPrivate: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">featuredAssetId: <a href="/reference/graphql-api/admin/object-types#id">ID</a></div>

<div class="graphql-code-line ">parentId: <a href="/reference/graphql-api/admin/object-types#id">ID</a></div>

<div class="graphql-code-line ">assetIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]</div>

<div class="graphql-code-line ">inheritFilters: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">filters: [<a href="/reference/graphql-api/admin/input-types#configurableoperationinput">ConfigurableOperationInput</a>!]</div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/admin/input-types#updatecollectiontranslationinput">UpdateCollectionTranslationInput</a>!]</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## UpdateCollectionTranslationInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">UpdateCollectionTranslationInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a></div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">slug: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## UpdateCountryInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">UpdateCountryInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/admin/input-types#countrytranslationinput">CountryTranslationInput</a>!]</div>

<div class="graphql-code-line ">enabled: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## UpdateCustomerGroupInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">UpdateCustomerGroupInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## UpdateCustomerInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">UpdateCustomerInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">title: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">firstName: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">lastName: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">phoneNumber: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">emailAddress: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## UpdateCustomerNoteInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">UpdateCustomerNoteInput</span> &#123;</div>
<div class="graphql-code-line ">noteId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">note: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## UpdateFacetInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">UpdateFacetInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">isPrivate: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/admin/input-types#facettranslationinput">FacetTranslationInput</a>!]</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## UpdateFacetValueInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">UpdateFacetValueInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/admin/input-types#facetvaluetranslationinput">FacetValueTranslationInput</a>!]</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## UpdateGlobalSettingsInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">UpdateGlobalSettingsInput</span> &#123;</div>
<div class="graphql-code-line ">availableLanguages: [<a href="/reference/graphql-api/admin/enums#languagecode">LanguageCode</a>!]</div>

<div class="graphql-code-line ">trackInventory: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">outOfStockThreshold: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## UpdateOrderAddressInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">UpdateOrderAddressInput</span> &#123;</div>
<div class="graphql-code-line ">fullName: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">company: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">streetLine1: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">streetLine2: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">city: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">province: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">postalCode: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">countryCode: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">phoneNumber: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## UpdateOrderInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">UpdateOrderInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## UpdateOrderNoteInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">UpdateOrderNoteInput</span> &#123;</div>
<div class="graphql-code-line ">noteId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">note: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">isPublic: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## UpdatePaymentMethodInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">UpdatePaymentMethodInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">enabled: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">checker: <a href="/reference/graphql-api/admin/input-types#configurableoperationinput">ConfigurableOperationInput</a></div>

<div class="graphql-code-line ">handler: <a href="/reference/graphql-api/admin/input-types#configurableoperationinput">ConfigurableOperationInput</a></div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/admin/input-types#paymentmethodtranslationinput">PaymentMethodTranslationInput</a>!]</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## UpdateProductInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">UpdateProductInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">enabled: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">featuredAssetId: <a href="/reference/graphql-api/admin/object-types#id">ID</a></div>

<div class="graphql-code-line ">assetIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]</div>

<div class="graphql-code-line ">facetValueIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]</div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/admin/input-types#producttranslationinput">ProductTranslationInput</a>!]</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## UpdateProductOptionGroupInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">UpdateProductOptionGroupInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/admin/input-types#productoptiongrouptranslationinput">ProductOptionGroupTranslationInput</a>!]</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## UpdateProductOptionInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">UpdateProductOptionInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/admin/input-types#productoptiongrouptranslationinput">ProductOptionGroupTranslationInput</a>!]</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## UpdateProductVariantInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">UpdateProductVariantInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">enabled: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/admin/input-types#productvarianttranslationinput">ProductVariantTranslationInput</a>!]</div>

<div class="graphql-code-line ">facetValueIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]</div>

<div class="graphql-code-line ">optionIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]</div>

<div class="graphql-code-line ">sku: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">taxCategoryId: <a href="/reference/graphql-api/admin/object-types#id">ID</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Sets the price for the ProductVariant in the Channel's default currency</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">price: <a href="/reference/graphql-api/admin/object-types#money">Money</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Allows multiple prices to be set for the ProductVariant in different currencies.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">prices: [<a href="/reference/graphql-api/admin/input-types#updateproductvariantpriceinput">UpdateProductVariantPriceInput</a>!]</div>

<div class="graphql-code-line ">featuredAssetId: <a href="/reference/graphql-api/admin/object-types#id">ID</a></div>

<div class="graphql-code-line ">assetIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]</div>

<div class="graphql-code-line ">stockOnHand: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line ">stockLevels: [<a href="/reference/graphql-api/admin/input-types#stocklevelinput">StockLevelInput</a>!]</div>

<div class="graphql-code-line ">outOfStockThreshold: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line ">useGlobalOutOfStockThreshold: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">trackInventory: <a href="/reference/graphql-api/admin/enums#globalflag">GlobalFlag</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## UpdateProductVariantPriceInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Used to set up update the price of a ProductVariant in a particular Channel.</div>

<div class="graphql-code-line top-level comment">If the <code>delete</code> flag is `true`, the price will be deleted for the given Channel.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">UpdateProductVariantPriceInput</span> &#123;</div>
<div class="graphql-code-line ">currencyCode: <a href="/reference/graphql-api/admin/enums#currencycode">CurrencyCode</a>!</div>

<div class="graphql-code-line ">price: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">delete: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## UpdatePromotionInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">UpdatePromotionInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">enabled: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">startsAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a></div>

<div class="graphql-code-line ">endsAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a></div>

<div class="graphql-code-line ">couponCode: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">perCustomerUsageLimit: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line ">usageLimit: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line ">conditions: [<a href="/reference/graphql-api/admin/input-types#configurableoperationinput">ConfigurableOperationInput</a>!]</div>

<div class="graphql-code-line ">actions: [<a href="/reference/graphql-api/admin/input-types#configurableoperationinput">ConfigurableOperationInput</a>!]</div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/admin/input-types#promotiontranslationinput">PromotionTranslationInput</a>!]</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## UpdateProvinceInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">UpdateProvinceInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/admin/input-types#provincetranslationinput">ProvinceTranslationInput</a>!]</div>

<div class="graphql-code-line ">enabled: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## UpdateRoleInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">UpdateRoleInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">permissions: [<a href="/reference/graphql-api/admin/enums#permission">Permission</a>!]</div>

<div class="graphql-code-line ">channelIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## UpdateScheduledTaskInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">UpdateScheduledTaskInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">enabled: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## UpdateSellerInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">UpdateSellerInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## UpdateShippingMethodInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">UpdateShippingMethodInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">fulfillmentHandler: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">checker: <a href="/reference/graphql-api/admin/input-types#configurableoperationinput">ConfigurableOperationInput</a></div>

<div class="graphql-code-line ">calculator: <a href="/reference/graphql-api/admin/input-types#configurableoperationinput">ConfigurableOperationInput</a></div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/admin/input-types#shippingmethodtranslationinput">ShippingMethodTranslationInput</a>!]!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## UpdateStockLocationInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">UpdateStockLocationInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## UpdateTagInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">UpdateTagInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">value: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## UpdateTaxCategoryInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">UpdateTaxCategoryInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">isDefault: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## UpdateTaxRateInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">UpdateTaxRateInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">value: <a href="/reference/graphql-api/admin/object-types#float">Float</a></div>

<div class="graphql-code-line ">enabled: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">categoryId: <a href="/reference/graphql-api/admin/object-types#id">ID</a></div>

<div class="graphql-code-line ">zoneId: <a href="/reference/graphql-api/admin/object-types#id">ID</a></div>

<div class="graphql-code-line ">customerGroupId: <a href="/reference/graphql-api/admin/object-types#id">ID</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## UpdateZoneInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">UpdateZoneInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ZoneFilterParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">ZoneFilterParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">_and: [<a href="/reference/graphql-api/admin/input-types#zonefilterparameter">ZoneFilterParameter</a>!]</div>

<div class="graphql-code-line ">_or: [<a href="/reference/graphql-api/admin/input-types#zonefilterparameter">ZoneFilterParameter</a>!]</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ZoneListOptions

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">ZoneListOptions</span> &#123;</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Skips the first n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">skip: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Takes n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">take: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies which properties to sort the results by</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">sort: <a href="/reference/graphql-api/admin/input-types#zonesortparameter">ZoneSortParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Allows the results to be filtered</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filter: <a href="/reference/graphql-api/admin/input-types#zonefilterparameter">ZoneFilterParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies whether multiple top-level "filter" fields should be combined with a logical AND or OR operation. Defaults to AND.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filterOperator: <a href="/reference/graphql-api/admin/enums#logicaloperator">LogicalOperator</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ZoneSortParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">ZoneSortParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/enums#sortorder">SortOrder</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>


---

---
title: "Mutations"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';



## addCustomersToGroup
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Add Customers to a CustomerGroup</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">addCustomersToGroup(customerGroupId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!, customerIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!): <a href="/reference/graphql-api/admin/object-types#customergroup">CustomerGroup</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## addFulfillmentToOrder
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">addFulfillmentToOrder(input: <a href="/reference/graphql-api/admin/input-types#fulfillorderinput">FulfillOrderInput</a>!): <a href="/reference/graphql-api/admin/object-types#addfulfillmenttoorderresult">AddFulfillmentToOrderResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## addItemToDraftOrder
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Adds an item to the draft Order.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">addItemToDraftOrder(orderId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!, input: <a href="/reference/graphql-api/admin/input-types#additemtodraftorderinput">AddItemToDraftOrderInput</a>!): <a href="/reference/graphql-api/admin/object-types#updateorderitemsresult">UpdateOrderItemsResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## addManualPaymentToOrder
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Used to manually create a new Payment against an Order.</div>

<div class="graphql-code-line top-level comment">This can be used by an Administrator when an Order is in the ArrangingPayment state.</div>

<div class="graphql-code-line top-level comment"></div>

<div class="graphql-code-line top-level comment">It is also used when a completed Order</div>

<div class="graphql-code-line top-level comment">has been modified (using `modifyOrder`) and the price has increased. The extra payment</div>

<div class="graphql-code-line top-level comment">can then be manually arranged by the administrator, and the details used to create a new</div>

<div class="graphql-code-line top-level comment">Payment.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">addManualPaymentToOrder(input: <a href="/reference/graphql-api/admin/input-types#manualpaymentinput">ManualPaymentInput</a>!): <a href="/reference/graphql-api/admin/object-types#addmanualpaymenttoorderresult">AddManualPaymentToOrderResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## addMembersToZone
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Add members to a Zone</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">addMembersToZone(zoneId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!, memberIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!): <a href="/reference/graphql-api/admin/object-types#zone">Zone</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## addNoteToCustomer
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">addNoteToCustomer(input: <a href="/reference/graphql-api/admin/input-types#addnotetocustomerinput">AddNoteToCustomerInput</a>!): <a href="/reference/graphql-api/admin/object-types#customer">Customer</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## addNoteToOrder
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">addNoteToOrder(input: <a href="/reference/graphql-api/admin/input-types#addnotetoorderinput">AddNoteToOrderInput</a>!): <a href="/reference/graphql-api/admin/object-types#order">Order</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## addOptionGroupToProduct
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Add an OptionGroup to a Product</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">addOptionGroupToProduct(productId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!, optionGroupId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#product">Product</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## adjustDraftOrderLine
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Adjusts a draft OrderLine. If custom fields are defined on the OrderLine entity, a third argument 'customFields' of type <code>OrderLineCustomFieldsInput</code> will be available.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">adjustDraftOrderLine(orderId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!, input: <a href="/reference/graphql-api/admin/input-types#adjustdraftorderlineinput">AdjustDraftOrderLineInput</a>!): <a href="/reference/graphql-api/admin/object-types#updateorderitemsresult">UpdateOrderItemsResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## applyCouponCodeToDraftOrder
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Applies the given coupon code to the draft Order</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">applyCouponCodeToDraftOrder(orderId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!, couponCode: <a href="/reference/graphql-api/admin/object-types#string">String</a>!): <a href="/reference/graphql-api/admin/object-types#applycouponcoderesult">ApplyCouponCodeResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## assignAssetsToChannel
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Assign assets to channel</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">assignAssetsToChannel(input: <a href="/reference/graphql-api/admin/input-types#assignassetstochannelinput">AssignAssetsToChannelInput</a>!): [<a href="/reference/graphql-api/admin/object-types#asset">Asset</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## assignCollectionsToChannel
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Assigns Collections to the specified Channel</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">assignCollectionsToChannel(input: <a href="/reference/graphql-api/admin/input-types#assigncollectionstochannelinput">AssignCollectionsToChannelInput</a>!): [<a href="/reference/graphql-api/admin/object-types#collection">Collection</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## assignFacetsToChannel
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Assigns Facets to the specified Channel</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">assignFacetsToChannel(input: <a href="/reference/graphql-api/admin/input-types#assignfacetstochannelinput">AssignFacetsToChannelInput</a>!): [<a href="/reference/graphql-api/admin/object-types#facet">Facet</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## assignPaymentMethodsToChannel
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Assigns PaymentMethods to the specified Channel</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">assignPaymentMethodsToChannel(input: <a href="/reference/graphql-api/admin/input-types#assignpaymentmethodstochannelinput">AssignPaymentMethodsToChannelInput</a>!): [<a href="/reference/graphql-api/admin/object-types#paymentmethod">PaymentMethod</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## assignProductVariantsToChannel
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Assigns ProductVariants to the specified Channel</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">assignProductVariantsToChannel(input: <a href="/reference/graphql-api/admin/input-types#assignproductvariantstochannelinput">AssignProductVariantsToChannelInput</a>!): [<a href="/reference/graphql-api/admin/object-types#productvariant">ProductVariant</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## assignProductsToChannel
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Assigns all ProductVariants of Product to the specified Channel</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">assignProductsToChannel(input: <a href="/reference/graphql-api/admin/input-types#assignproductstochannelinput">AssignProductsToChannelInput</a>!): [<a href="/reference/graphql-api/admin/object-types#product">Product</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## assignPromotionsToChannel
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Assigns Promotions to the specified Channel</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">assignPromotionsToChannel(input: <a href="/reference/graphql-api/admin/input-types#assignpromotionstochannelinput">AssignPromotionsToChannelInput</a>!): [<a href="/reference/graphql-api/admin/object-types#promotion">Promotion</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## assignRoleToAdministrator
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Assign a Role to an Administrator</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">assignRoleToAdministrator(administratorId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!, roleId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#administrator">Administrator</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## assignShippingMethodsToChannel
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Assigns ShippingMethods to the specified Channel</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">assignShippingMethodsToChannel(input: <a href="/reference/graphql-api/admin/input-types#assignshippingmethodstochannelinput">AssignShippingMethodsToChannelInput</a>!): [<a href="/reference/graphql-api/admin/object-types#shippingmethod">ShippingMethod</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## assignStockLocationsToChannel
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Assigns StockLocations to the specified Channel</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">assignStockLocationsToChannel(input: <a href="/reference/graphql-api/admin/input-types#assignstocklocationstochannelinput">AssignStockLocationsToChannelInput</a>!): [<a href="/reference/graphql-api/admin/object-types#stocklocation">StockLocation</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## authenticate
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Authenticates the user using a named authentication strategy</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">authenticate(input: <a href="/reference/graphql-api/admin/input-types#authenticationinput">AuthenticationInput</a>!, rememberMe: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>): <a href="/reference/graphql-api/admin/object-types#authenticationresult">AuthenticationResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## cancelJob
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">cancelJob(jobId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#job">Job</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## cancelOrder
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">cancelOrder(input: <a href="/reference/graphql-api/admin/input-types#cancelorderinput">CancelOrderInput</a>!): <a href="/reference/graphql-api/admin/object-types#cancelorderresult">CancelOrderResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## cancelPayment
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">cancelPayment(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#cancelpaymentresult">CancelPaymentResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## createAdministrator
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Create a new Administrator</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">createAdministrator(input: <a href="/reference/graphql-api/admin/input-types#createadministratorinput">CreateAdministratorInput</a>!): <a href="/reference/graphql-api/admin/object-types#administrator">Administrator</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## createAssets
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Create a new Asset</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">createAssets(input: [<a href="/reference/graphql-api/admin/input-types#createassetinput">CreateAssetInput</a>!]!): [<a href="/reference/graphql-api/admin/object-types#createassetresult">CreateAssetResult</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## createChannel
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Create a new Channel</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">createChannel(input: <a href="/reference/graphql-api/admin/input-types#createchannelinput">CreateChannelInput</a>!): <a href="/reference/graphql-api/admin/object-types#createchannelresult">CreateChannelResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## createCollection
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Create a new Collection</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">createCollection(input: <a href="/reference/graphql-api/admin/input-types#createcollectioninput">CreateCollectionInput</a>!): <a href="/reference/graphql-api/admin/object-types#collection">Collection</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## createCountry
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Create a new Country</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">createCountry(input: <a href="/reference/graphql-api/admin/input-types#createcountryinput">CreateCountryInput</a>!): <a href="/reference/graphql-api/admin/object-types#country">Country</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## createCustomer
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Create a new Customer. If a password is provided, a new User will also be created an linked to the Customer.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">createCustomer(input: <a href="/reference/graphql-api/admin/input-types#createcustomerinput">CreateCustomerInput</a>!, password: <a href="/reference/graphql-api/admin/object-types#string">String</a>): <a href="/reference/graphql-api/admin/object-types#createcustomerresult">CreateCustomerResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## createCustomerAddress
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Create a new Address and associate it with the Customer specified by customerId</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">createCustomerAddress(customerId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!, input: <a href="/reference/graphql-api/admin/input-types#createaddressinput">CreateAddressInput</a>!): <a href="/reference/graphql-api/admin/object-types#address">Address</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## createCustomerGroup
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Create a new CustomerGroup</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">createCustomerGroup(input: <a href="/reference/graphql-api/admin/input-types#createcustomergroupinput">CreateCustomerGroupInput</a>!): <a href="/reference/graphql-api/admin/object-types#customergroup">CustomerGroup</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## createDraftOrder
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Creates a draft Order</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">createDraftOrder: <a href="/reference/graphql-api/admin/object-types#order">Order</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## createFacet
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Create a new Facet</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">createFacet(input: <a href="/reference/graphql-api/admin/input-types#createfacetinput">CreateFacetInput</a>!): <a href="/reference/graphql-api/admin/object-types#facet">Facet</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## createFacetValue
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Create a single FacetValue</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">createFacetValue(input: <a href="/reference/graphql-api/admin/input-types#createfacetvalueinput">CreateFacetValueInput</a>!): <a href="/reference/graphql-api/admin/object-types#facetvalue">FacetValue</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## createFacetValues
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Create one or more FacetValues</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">createFacetValues(input: [<a href="/reference/graphql-api/admin/input-types#createfacetvalueinput">CreateFacetValueInput</a>!]!): [<a href="/reference/graphql-api/admin/object-types#facetvalue">FacetValue</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## createPaymentMethod
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Create existing PaymentMethod</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">createPaymentMethod(input: <a href="/reference/graphql-api/admin/input-types#createpaymentmethodinput">CreatePaymentMethodInput</a>!): <a href="/reference/graphql-api/admin/object-types#paymentmethod">PaymentMethod</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## createProduct
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Create a new Product</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">createProduct(input: <a href="/reference/graphql-api/admin/input-types#createproductinput">CreateProductInput</a>!): <a href="/reference/graphql-api/admin/object-types#product">Product</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## createProductOption
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Create a new ProductOption within a ProductOptionGroup</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">createProductOption(input: <a href="/reference/graphql-api/admin/input-types#createproductoptioninput">CreateProductOptionInput</a>!): <a href="/reference/graphql-api/admin/object-types#productoption">ProductOption</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## createProductOptionGroup
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Create a new ProductOptionGroup</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">createProductOptionGroup(input: <a href="/reference/graphql-api/admin/input-types#createproductoptiongroupinput">CreateProductOptionGroupInput</a>!): <a href="/reference/graphql-api/admin/object-types#productoptiongroup">ProductOptionGroup</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## createProductVariants
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Create a set of ProductVariants based on the OptionGroups assigned to the given Product</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">createProductVariants(input: [<a href="/reference/graphql-api/admin/input-types#createproductvariantinput">CreateProductVariantInput</a>!]!): [<a href="/reference/graphql-api/admin/object-types#productvariant">ProductVariant</a>]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## createPromotion
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">createPromotion(input: <a href="/reference/graphql-api/admin/input-types#createpromotioninput">CreatePromotionInput</a>!): <a href="/reference/graphql-api/admin/object-types#createpromotionresult">CreatePromotionResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## createProvince
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Create a new Province</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">createProvince(input: <a href="/reference/graphql-api/admin/input-types#createprovinceinput">CreateProvinceInput</a>!): <a href="/reference/graphql-api/admin/object-types#province">Province</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## createRole
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Create a new Role</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">createRole(input: <a href="/reference/graphql-api/admin/input-types#createroleinput">CreateRoleInput</a>!): <a href="/reference/graphql-api/admin/object-types#role">Role</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## createSeller
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Create a new Seller</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">createSeller(input: <a href="/reference/graphql-api/admin/input-types#createsellerinput">CreateSellerInput</a>!): <a href="/reference/graphql-api/admin/object-types#seller">Seller</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## createShippingMethod
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Create a new ShippingMethod</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">createShippingMethod(input: <a href="/reference/graphql-api/admin/input-types#createshippingmethodinput">CreateShippingMethodInput</a>!): <a href="/reference/graphql-api/admin/object-types#shippingmethod">ShippingMethod</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## createStockLocation
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">createStockLocation(input: <a href="/reference/graphql-api/admin/input-types#createstocklocationinput">CreateStockLocationInput</a>!): <a href="/reference/graphql-api/admin/object-types#stocklocation">StockLocation</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## createTag
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Create a new Tag</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">createTag(input: <a href="/reference/graphql-api/admin/input-types#createtaginput">CreateTagInput</a>!): <a href="/reference/graphql-api/admin/object-types#tag">Tag</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## createTaxCategory
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Create a new TaxCategory</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">createTaxCategory(input: <a href="/reference/graphql-api/admin/input-types#createtaxcategoryinput">CreateTaxCategoryInput</a>!): <a href="/reference/graphql-api/admin/object-types#taxcategory">TaxCategory</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## createTaxRate
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Create a new TaxRate</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">createTaxRate(input: <a href="/reference/graphql-api/admin/input-types#createtaxrateinput">CreateTaxRateInput</a>!): <a href="/reference/graphql-api/admin/object-types#taxrate">TaxRate</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## createZone
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Create a new Zone</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">createZone(input: <a href="/reference/graphql-api/admin/input-types#createzoneinput">CreateZoneInput</a>!): <a href="/reference/graphql-api/admin/object-types#zone">Zone</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deleteAdministrator
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Delete an Administrator</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deleteAdministrator(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deleteAdministrators
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Delete multiple Administrators</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deleteAdministrators(ids: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!): [<a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deleteAsset
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Delete an Asset</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deleteAsset(input: <a href="/reference/graphql-api/admin/input-types#deleteassetinput">DeleteAssetInput</a>!): <a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deleteAssets
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Delete multiple Assets</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deleteAssets(input: <a href="/reference/graphql-api/admin/input-types#deleteassetsinput">DeleteAssetsInput</a>!): <a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deleteChannel
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Delete a Channel</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deleteChannel(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deleteChannels
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Delete multiple Channels</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deleteChannels(ids: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!): [<a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deleteCollection
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Delete a Collection and all of its descendants</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deleteCollection(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deleteCollections
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Delete multiple Collections and all of their descendants</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deleteCollections(ids: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!): [<a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deleteCountries
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Delete multiple Countries</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deleteCountries(ids: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!): [<a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deleteCountry
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Delete a Country</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deleteCountry(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deleteCustomer
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Delete a Customer</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deleteCustomer(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deleteCustomerAddress
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Update an existing Address</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deleteCustomerAddress(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#success">Success</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deleteCustomerGroup
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Delete a CustomerGroup</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deleteCustomerGroup(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deleteCustomerGroups
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Delete multiple CustomerGroups</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deleteCustomerGroups(ids: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!): [<a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deleteCustomerNote
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deleteCustomerNote(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deleteCustomers
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Deletes Customers</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deleteCustomers(ids: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!): [<a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deleteDraftOrder
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Deletes a draft Order</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deleteDraftOrder(orderId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deleteFacet
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Delete an existing Facet</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deleteFacet(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!, force: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>): <a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deleteFacetValues
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Delete one or more FacetValues</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deleteFacetValues(ids: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!, force: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>): [<a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deleteFacets
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Delete multiple existing Facets</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deleteFacets(ids: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!, force: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>): [<a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deleteOrderNote
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deleteOrderNote(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deletePaymentMethod
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Delete a PaymentMethod</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deletePaymentMethod(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!, force: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>): <a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deletePaymentMethods
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Delete multiple PaymentMethods</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deletePaymentMethods(ids: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!, force: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>): [<a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deleteProduct
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Delete a Product</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deleteProduct(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deleteProductOption
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Delete a ProductOption</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deleteProductOption(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deleteProductVariant
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Delete a ProductVariant</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deleteProductVariant(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deleteProductVariants
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Delete multiple ProductVariants</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deleteProductVariants(ids: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!): [<a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deleteProducts
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Delete multiple Products</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deleteProducts(ids: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!): [<a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deletePromotion
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deletePromotion(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deletePromotions
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deletePromotions(ids: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!): [<a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deleteProvince
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Delete a Province</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deleteProvince(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deleteRole
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Delete an existing Role</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deleteRole(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deleteRoles
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Delete multiple Roles</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deleteRoles(ids: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!): [<a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deleteSeller
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Delete a Seller</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deleteSeller(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deleteSellers
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Delete multiple Sellers</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deleteSellers(ids: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!): [<a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deleteShippingMethod
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Delete a ShippingMethod</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deleteShippingMethod(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deleteShippingMethods
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Delete multiple ShippingMethods</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deleteShippingMethods(ids: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!): [<a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deleteStockLocation
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deleteStockLocation(input: <a href="/reference/graphql-api/admin/input-types#deletestocklocationinput">DeleteStockLocationInput</a>!): <a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deleteStockLocations
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deleteStockLocations(input: [<a href="/reference/graphql-api/admin/input-types#deletestocklocationinput">DeleteStockLocationInput</a>!]!): [<a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deleteTag
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Delete an existing Tag</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deleteTag(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deleteTaxCategories
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Deletes multiple TaxCategories</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deleteTaxCategories(ids: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!): [<a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deleteTaxCategory
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Deletes a TaxCategory</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deleteTaxCategory(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deleteTaxRate
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Delete a TaxRate</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deleteTaxRate(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deleteTaxRates
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Delete multiple TaxRates</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deleteTaxRates(ids: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!): [<a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deleteZone
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Delete a Zone</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deleteZone(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deleteZones
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Delete a Zone</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deleteZones(ids: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!): [<a href="/reference/graphql-api/admin/object-types#deletionresponse">DeletionResponse</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## duplicateEntity
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Duplicate an existing entity using a specific EntityDuplicator.</div>

<div class="graphql-code-line top-level comment">Since v2.2.0.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">duplicateEntity(input: <a href="/reference/graphql-api/admin/input-types#duplicateentityinput">DuplicateEntityInput</a>!): <a href="/reference/graphql-api/admin/object-types#duplicateentityresult">DuplicateEntityResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## flushBufferedJobs
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">flushBufferedJobs(bufferIds: [<a href="/reference/graphql-api/admin/object-types#string">String</a>!]): <a href="/reference/graphql-api/admin/object-types#success">Success</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## importProducts
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">importProducts(csvFile: <a href="/reference/graphql-api/admin/object-types#upload">Upload</a>!): <a href="/reference/graphql-api/admin/object-types#importinfo">ImportInfo</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## login
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Authenticates the user using the native authentication strategy. This mutation is an alias for authenticate(&#123; native: &#123; ... &#125;&#125;)</div>

<div class="graphql-code-line top-level comment"></div>

<div class="graphql-code-line top-level comment">The <code>rememberMe</code> option applies when using cookie-based sessions, and if <code>true</code> it will set the maxAge of the session cookie</div>

<div class="graphql-code-line top-level comment">to 1 year.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">login(username: <a href="/reference/graphql-api/admin/object-types#string">String</a>!, password: <a href="/reference/graphql-api/admin/object-types#string">String</a>!, rememberMe: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>): <a href="/reference/graphql-api/admin/object-types#nativeauthenticationresult">NativeAuthenticationResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## logout
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">logout: <a href="/reference/graphql-api/admin/object-types#success">Success</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## modifyOrder
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Allows an Order to be modified after it has been completed by the Customer. The Order must first</div>

<div class="graphql-code-line top-level comment">be in the <code>Modifying</code> state.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">modifyOrder(input: <a href="/reference/graphql-api/admin/input-types#modifyorderinput">ModifyOrderInput</a>!): <a href="/reference/graphql-api/admin/object-types#modifyorderresult">ModifyOrderResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## moveCollection
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Move a Collection to a different parent or index</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">moveCollection(input: <a href="/reference/graphql-api/admin/input-types#movecollectioninput">MoveCollectionInput</a>!): <a href="/reference/graphql-api/admin/object-types#collection">Collection</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## refundOrder
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">refundOrder(input: <a href="/reference/graphql-api/admin/input-types#refundorderinput">RefundOrderInput</a>!): <a href="/reference/graphql-api/admin/object-types#refundorderresult">RefundOrderResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## reindex
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">reindex: <a href="/reference/graphql-api/admin/object-types#job">Job</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## removeCollectionsFromChannel
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Removes Collections from the specified Channel</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">removeCollectionsFromChannel(input: <a href="/reference/graphql-api/admin/input-types#removecollectionsfromchannelinput">RemoveCollectionsFromChannelInput</a>!): [<a href="/reference/graphql-api/admin/object-types#collection">Collection</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## removeCouponCodeFromDraftOrder
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Removes the given coupon code from the draft Order</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">removeCouponCodeFromDraftOrder(orderId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!, couponCode: <a href="/reference/graphql-api/admin/object-types#string">String</a>!): <a href="/reference/graphql-api/admin/object-types#order">Order</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## removeCustomersFromGroup
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Remove Customers from a CustomerGroup</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">removeCustomersFromGroup(customerGroupId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!, customerIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!): <a href="/reference/graphql-api/admin/object-types#customergroup">CustomerGroup</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## removeDraftOrderLine
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Remove an OrderLine from the draft Order</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">removeDraftOrderLine(orderId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!, orderLineId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#removeorderitemsresult">RemoveOrderItemsResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## removeFacetsFromChannel
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Removes Facets from the specified Channel</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">removeFacetsFromChannel(input: <a href="/reference/graphql-api/admin/input-types#removefacetsfromchannelinput">RemoveFacetsFromChannelInput</a>!): [<a href="/reference/graphql-api/admin/object-types#removefacetfromchannelresult">RemoveFacetFromChannelResult</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## removeMembersFromZone
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Remove members from a Zone</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">removeMembersFromZone(zoneId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!, memberIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!): <a href="/reference/graphql-api/admin/object-types#zone">Zone</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## removeOptionGroupFromProduct
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Remove an OptionGroup from a Product. If the OptionGroup is in use by any ProductVariants</div>

<div class="graphql-code-line top-level comment">the mutation will return a ProductOptionInUseError, and the OptionGroup will not be removed.</div>

<div class="graphql-code-line top-level comment">Setting the <code>force</code> argument to <code>true</code> will override this and remove the OptionGroup anyway,</div>

<div class="graphql-code-line top-level comment">as well as removing any of the group's options from the Product's ProductVariants.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">removeOptionGroupFromProduct(productId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!, optionGroupId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!, force: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>): <a href="/reference/graphql-api/admin/object-types#removeoptiongroupfromproductresult">RemoveOptionGroupFromProductResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## removePaymentMethodsFromChannel
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Removes PaymentMethods from the specified Channel</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">removePaymentMethodsFromChannel(input: <a href="/reference/graphql-api/admin/input-types#removepaymentmethodsfromchannelinput">RemovePaymentMethodsFromChannelInput</a>!): [<a href="/reference/graphql-api/admin/object-types#paymentmethod">PaymentMethod</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## removeProductVariantsFromChannel
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Removes ProductVariants from the specified Channel</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">removeProductVariantsFromChannel(input: <a href="/reference/graphql-api/admin/input-types#removeproductvariantsfromchannelinput">RemoveProductVariantsFromChannelInput</a>!): [<a href="/reference/graphql-api/admin/object-types#productvariant">ProductVariant</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## removeProductsFromChannel
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Removes all ProductVariants of Product from the specified Channel</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">removeProductsFromChannel(input: <a href="/reference/graphql-api/admin/input-types#removeproductsfromchannelinput">RemoveProductsFromChannelInput</a>!): [<a href="/reference/graphql-api/admin/object-types#product">Product</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## removePromotionsFromChannel
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Removes Promotions from the specified Channel</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">removePromotionsFromChannel(input: <a href="/reference/graphql-api/admin/input-types#removepromotionsfromchannelinput">RemovePromotionsFromChannelInput</a>!): [<a href="/reference/graphql-api/admin/object-types#promotion">Promotion</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## removeSettledJobs
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Remove all settled jobs in the given queues older than the given date. Returns the number of jobs deleted.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">removeSettledJobs(queueNames: [<a href="/reference/graphql-api/admin/object-types#string">String</a>!], olderThan: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>): <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## removeShippingMethodsFromChannel
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Removes ShippingMethods from the specified Channel</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">removeShippingMethodsFromChannel(input: <a href="/reference/graphql-api/admin/input-types#removeshippingmethodsfromchannelinput">RemoveShippingMethodsFromChannelInput</a>!): [<a href="/reference/graphql-api/admin/object-types#shippingmethod">ShippingMethod</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## removeStockLocationsFromChannel
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Removes StockLocations from the specified Channel</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">removeStockLocationsFromChannel(input: <a href="/reference/graphql-api/admin/input-types#removestocklocationsfromchannelinput">RemoveStockLocationsFromChannelInput</a>!): [<a href="/reference/graphql-api/admin/object-types#stocklocation">StockLocation</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## runPendingSearchIndexUpdates
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">runPendingSearchIndexUpdates: <a href="/reference/graphql-api/admin/object-types#success">Success</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## runScheduledTask
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">runScheduledTask(id: <a href="/reference/graphql-api/admin/object-types#string">String</a>!): <a href="/reference/graphql-api/admin/object-types#success">Success</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## setCustomerForDraftOrder
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">setCustomerForDraftOrder(orderId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!, customerId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>, input: <a href="/reference/graphql-api/admin/input-types#createcustomerinput">CreateCustomerInput</a>): <a href="/reference/graphql-api/admin/object-types#setcustomerfordraftorderresult">SetCustomerForDraftOrderResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## setDraftOrderBillingAddress
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Sets the billing address for a draft Order</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">setDraftOrderBillingAddress(orderId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!, input: <a href="/reference/graphql-api/admin/input-types#createaddressinput">CreateAddressInput</a>!): <a href="/reference/graphql-api/admin/object-types#order">Order</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## setDraftOrderCustomFields
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Allows any custom fields to be set for the active order</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">setDraftOrderCustomFields(orderId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!, input: <a href="/reference/graphql-api/admin/input-types#updateorderinput">UpdateOrderInput</a>!): <a href="/reference/graphql-api/admin/object-types#order">Order</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## setDraftOrderShippingAddress
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Sets the shipping address for a draft Order</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">setDraftOrderShippingAddress(orderId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!, input: <a href="/reference/graphql-api/admin/input-types#createaddressinput">CreateAddressInput</a>!): <a href="/reference/graphql-api/admin/object-types#order">Order</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## setDraftOrderShippingMethod
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Sets the shipping method by id, which can be obtained with the <code>eligibleShippingMethodsForDraftOrder</code> query</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">setDraftOrderShippingMethod(orderId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!, shippingMethodId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#setordershippingmethodresult">SetOrderShippingMethodResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## setOrderCustomFields
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">setOrderCustomFields(input: <a href="/reference/graphql-api/admin/input-types#updateorderinput">UpdateOrderInput</a>!): <a href="/reference/graphql-api/admin/object-types#order">Order</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## setOrderCustomer
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Allows a different Customer to be assigned to an Order. Added in v2.2.0.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">setOrderCustomer(input: <a href="/reference/graphql-api/admin/input-types#setordercustomerinput">SetOrderCustomerInput</a>!): <a href="/reference/graphql-api/admin/object-types#order">Order</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## setSettingsStoreValue
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Set a single key-value pair (automatically scoped based on field configuration)</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">setSettingsStoreValue(input: <a href="/reference/graphql-api/admin/input-types#settingsstoreinput">SettingsStoreInput</a>!): <a href="/reference/graphql-api/admin/object-types#setsettingsstorevalueresult">SetSettingsStoreValueResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## setSettingsStoreValues
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Set multiple key-value pairs in a transaction (each automatically scoped)</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">setSettingsStoreValues(inputs: [<a href="/reference/graphql-api/admin/input-types#settingsstoreinput">SettingsStoreInput</a>!]!): [<a href="/reference/graphql-api/admin/object-types#setsettingsstorevalueresult">SetSettingsStoreValueResult</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## settlePayment
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">settlePayment(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#settlepaymentresult">SettlePaymentResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## settleRefund
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">settleRefund(input: <a href="/reference/graphql-api/admin/input-types#settlerefundinput">SettleRefundInput</a>!): <a href="/reference/graphql-api/admin/object-types#settlerefundresult">SettleRefundResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## transitionFulfillmentToState
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">transitionFulfillmentToState(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!, state: <a href="/reference/graphql-api/admin/object-types#string">String</a>!): <a href="/reference/graphql-api/admin/object-types#transitionfulfillmenttostateresult">TransitionFulfillmentToStateResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## transitionOrderToState
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">transitionOrderToState(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!, state: <a href="/reference/graphql-api/admin/object-types#string">String</a>!): <a href="/reference/graphql-api/admin/object-types#transitionordertostateresult">TransitionOrderToStateResult</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## transitionPaymentToState
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">transitionPaymentToState(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!, state: <a href="/reference/graphql-api/admin/object-types#string">String</a>!): <a href="/reference/graphql-api/admin/object-types#transitionpaymenttostateresult">TransitionPaymentToStateResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## unsetDraftOrderBillingAddress
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Unsets the billing address for a draft Order</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">unsetDraftOrderBillingAddress(orderId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#order">Order</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## unsetDraftOrderShippingAddress
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Unsets the shipping address for a draft Order</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">unsetDraftOrderShippingAddress(orderId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#order">Order</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## updateActiveAdministrator
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Update the active (currently logged-in) Administrator</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">updateActiveAdministrator(input: <a href="/reference/graphql-api/admin/input-types#updateactiveadministratorinput">UpdateActiveAdministratorInput</a>!): <a href="/reference/graphql-api/admin/object-types#administrator">Administrator</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## updateAdministrator
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Update an existing Administrator</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">updateAdministrator(input: <a href="/reference/graphql-api/admin/input-types#updateadministratorinput">UpdateAdministratorInput</a>!): <a href="/reference/graphql-api/admin/object-types#administrator">Administrator</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## updateAsset
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Update an existing Asset</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">updateAsset(input: <a href="/reference/graphql-api/admin/input-types#updateassetinput">UpdateAssetInput</a>!): <a href="/reference/graphql-api/admin/object-types#asset">Asset</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## updateChannel
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Update an existing Channel</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">updateChannel(input: <a href="/reference/graphql-api/admin/input-types#updatechannelinput">UpdateChannelInput</a>!): <a href="/reference/graphql-api/admin/object-types#updatechannelresult">UpdateChannelResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## updateCollection
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Update an existing Collection</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">updateCollection(input: <a href="/reference/graphql-api/admin/input-types#updatecollectioninput">UpdateCollectionInput</a>!): <a href="/reference/graphql-api/admin/object-types#collection">Collection</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## updateCountry
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Update an existing Country</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">updateCountry(input: <a href="/reference/graphql-api/admin/input-types#updatecountryinput">UpdateCountryInput</a>!): <a href="/reference/graphql-api/admin/object-types#country">Country</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## updateCustomer
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Update an existing Customer</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">updateCustomer(input: <a href="/reference/graphql-api/admin/input-types#updatecustomerinput">UpdateCustomerInput</a>!): <a href="/reference/graphql-api/admin/object-types#updatecustomerresult">UpdateCustomerResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## updateCustomerAddress
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Update an existing Address</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">updateCustomerAddress(input: <a href="/reference/graphql-api/admin/input-types#updateaddressinput">UpdateAddressInput</a>!): <a href="/reference/graphql-api/admin/object-types#address">Address</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## updateCustomerGroup
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Update an existing CustomerGroup</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">updateCustomerGroup(input: <a href="/reference/graphql-api/admin/input-types#updatecustomergroupinput">UpdateCustomerGroupInput</a>!): <a href="/reference/graphql-api/admin/object-types#customergroup">CustomerGroup</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## updateCustomerNote
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">updateCustomerNote(input: <a href="/reference/graphql-api/admin/input-types#updatecustomernoteinput">UpdateCustomerNoteInput</a>!): <a href="/reference/graphql-api/admin/object-types#historyentry">HistoryEntry</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## updateFacet
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Update an existing Facet</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">updateFacet(input: <a href="/reference/graphql-api/admin/input-types#updatefacetinput">UpdateFacetInput</a>!): <a href="/reference/graphql-api/admin/object-types#facet">Facet</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## updateFacetValue
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Update a single FacetValue</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">updateFacetValue(input: <a href="/reference/graphql-api/admin/input-types#updatefacetvalueinput">UpdateFacetValueInput</a>!): <a href="/reference/graphql-api/admin/object-types#facetvalue">FacetValue</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## updateFacetValues
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Update one or more FacetValues</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">updateFacetValues(input: [<a href="/reference/graphql-api/admin/input-types#updatefacetvalueinput">UpdateFacetValueInput</a>!]!): [<a href="/reference/graphql-api/admin/object-types#facetvalue">FacetValue</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## updateGlobalSettings
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">updateGlobalSettings(input: <a href="/reference/graphql-api/admin/input-types#updateglobalsettingsinput">UpdateGlobalSettingsInput</a>!): <a href="/reference/graphql-api/admin/object-types#updateglobalsettingsresult">UpdateGlobalSettingsResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## updateOrderNote
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">updateOrderNote(input: <a href="/reference/graphql-api/admin/input-types#updateordernoteinput">UpdateOrderNoteInput</a>!): <a href="/reference/graphql-api/admin/object-types#historyentry">HistoryEntry</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## updatePaymentMethod
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Update an existing PaymentMethod</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">updatePaymentMethod(input: <a href="/reference/graphql-api/admin/input-types#updatepaymentmethodinput">UpdatePaymentMethodInput</a>!): <a href="/reference/graphql-api/admin/object-types#paymentmethod">PaymentMethod</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## updateProduct
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Update an existing Product</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">updateProduct(input: <a href="/reference/graphql-api/admin/input-types#updateproductinput">UpdateProductInput</a>!): <a href="/reference/graphql-api/admin/object-types#product">Product</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## updateProductOption
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Create a new ProductOption within a ProductOptionGroup</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">updateProductOption(input: <a href="/reference/graphql-api/admin/input-types#updateproductoptioninput">UpdateProductOptionInput</a>!): <a href="/reference/graphql-api/admin/object-types#productoption">ProductOption</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## updateProductOptionGroup
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Update an existing ProductOptionGroup</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">updateProductOptionGroup(input: <a href="/reference/graphql-api/admin/input-types#updateproductoptiongroupinput">UpdateProductOptionGroupInput</a>!): <a href="/reference/graphql-api/admin/object-types#productoptiongroup">ProductOptionGroup</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## updateProductVariant
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Update an existing ProductVariant</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">updateProductVariant(input: <a href="/reference/graphql-api/admin/input-types#updateproductvariantinput">UpdateProductVariantInput</a>!): <a href="/reference/graphql-api/admin/object-types#productvariant">ProductVariant</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## updateProductVariants
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Update existing ProductVariants</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">updateProductVariants(input: [<a href="/reference/graphql-api/admin/input-types#updateproductvariantinput">UpdateProductVariantInput</a>!]!): [<a href="/reference/graphql-api/admin/object-types#productvariant">ProductVariant</a>]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## updateProducts
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Update multiple existing Products</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">updateProducts(input: [<a href="/reference/graphql-api/admin/input-types#updateproductinput">UpdateProductInput</a>!]!): [<a href="/reference/graphql-api/admin/object-types#product">Product</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## updatePromotion
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">updatePromotion(input: <a href="/reference/graphql-api/admin/input-types#updatepromotioninput">UpdatePromotionInput</a>!): <a href="/reference/graphql-api/admin/object-types#updatepromotionresult">UpdatePromotionResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## updateProvince
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Update an existing Province</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">updateProvince(input: <a href="/reference/graphql-api/admin/input-types#updateprovinceinput">UpdateProvinceInput</a>!): <a href="/reference/graphql-api/admin/object-types#province">Province</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## updateRole
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Update an existing Role</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">updateRole(input: <a href="/reference/graphql-api/admin/input-types#updateroleinput">UpdateRoleInput</a>!): <a href="/reference/graphql-api/admin/object-types#role">Role</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## updateScheduledTask
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">updateScheduledTask(input: <a href="/reference/graphql-api/admin/input-types#updatescheduledtaskinput">UpdateScheduledTaskInput</a>!): <a href="/reference/graphql-api/admin/object-types#scheduledtask">ScheduledTask</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## updateSeller
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Update an existing Seller</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">updateSeller(input: <a href="/reference/graphql-api/admin/input-types#updatesellerinput">UpdateSellerInput</a>!): <a href="/reference/graphql-api/admin/object-types#seller">Seller</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## updateShippingMethod
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Update an existing ShippingMethod</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">updateShippingMethod(input: <a href="/reference/graphql-api/admin/input-types#updateshippingmethodinput">UpdateShippingMethodInput</a>!): <a href="/reference/graphql-api/admin/object-types#shippingmethod">ShippingMethod</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## updateStockLocation
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">updateStockLocation(input: <a href="/reference/graphql-api/admin/input-types#updatestocklocationinput">UpdateStockLocationInput</a>!): <a href="/reference/graphql-api/admin/object-types#stocklocation">StockLocation</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## updateTag
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Update an existing Tag</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">updateTag(input: <a href="/reference/graphql-api/admin/input-types#updatetaginput">UpdateTagInput</a>!): <a href="/reference/graphql-api/admin/object-types#tag">Tag</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## updateTaxCategory
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Update an existing TaxCategory</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">updateTaxCategory(input: <a href="/reference/graphql-api/admin/input-types#updatetaxcategoryinput">UpdateTaxCategoryInput</a>!): <a href="/reference/graphql-api/admin/object-types#taxcategory">TaxCategory</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## updateTaxRate
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Update an existing TaxRate</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">updateTaxRate(input: <a href="/reference/graphql-api/admin/input-types#updatetaxrateinput">UpdateTaxRateInput</a>!): <a href="/reference/graphql-api/admin/object-types#taxrate">TaxRate</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## updateZone
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Update an existing Zone</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">updateZone(input: <a href="/reference/graphql-api/admin/input-types#updatezoneinput">UpdateZoneInput</a>!): <a href="/reference/graphql-api/admin/object-types#zone">Zone</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>


---

---
title: "Types"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';



## AddFulfillmentToOrderResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">AddFulfillmentToOrderResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/admin/object-types#fulfillment">Fulfillment</a> | <a href="/reference/graphql-api/admin/object-types#emptyorderlineselectionerror">EmptyOrderLineSelectionError</a> | <a href="/reference/graphql-api/admin/object-types#itemsalreadyfulfillederror">ItemsAlreadyFulfilledError</a> | <a href="/reference/graphql-api/admin/object-types#insufficientstockonhanderror">InsufficientStockOnHandError</a> | <a href="/reference/graphql-api/admin/object-types#invalidfulfillmenthandlererror">InvalidFulfillmentHandlerError</a> | <a href="/reference/graphql-api/admin/object-types#fulfillmentstatetransitionerror">FulfillmentStateTransitionError</a> | <a href="/reference/graphql-api/admin/object-types#createfulfillmenterror">CreateFulfillmentError</a></div>
</div>

## AddManualPaymentToOrderResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">AddManualPaymentToOrderResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/admin/object-types#order">Order</a> | <a href="/reference/graphql-api/admin/object-types#manualpaymentstateerror">ManualPaymentStateError</a></div>
</div>

## Address

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Address</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">fullName: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">company: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">streetLine1: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">streetLine2: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">city: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">province: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">postalCode: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">country: <a href="/reference/graphql-api/admin/object-types#country">Country</a>!</div>

<div class="graphql-code-line ">phoneNumber: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">defaultShippingAddress: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">defaultBillingAddress: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## Adjustment

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Adjustment</span> &#123;</div>
<div class="graphql-code-line ">adjustmentSource: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/admin/enums#adjustmenttype">AdjustmentType</a>!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">amount: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">data: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## Administrator

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Administrator</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">firstName: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">lastName: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">emailAddress: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">user: <a href="/reference/graphql-api/admin/object-types#user">User</a>!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## AdministratorList

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">AdministratorList</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/admin/object-types#administrator">Administrator</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## Allocation

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Allocation</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">productVariant: <a href="/reference/graphql-api/admin/object-types#productvariant">ProductVariant</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/admin/enums#stockmovementtype">StockMovementType</a>!</div>

<div class="graphql-code-line ">quantity: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>

<div class="graphql-code-line ">orderLine: <a href="/reference/graphql-api/admin/object-types#orderline">OrderLine</a>!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## AlreadyRefundedError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned if an attempting to refund an OrderItem which has already been refunded</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">AlreadyRefundedError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">refundId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ApplyCouponCodeResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">ApplyCouponCodeResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/admin/object-types#order">Order</a> | <a href="/reference/graphql-api/admin/object-types#couponcodeexpirederror">CouponCodeExpiredError</a> | <a href="/reference/graphql-api/admin/object-types#couponcodeinvaliderror">CouponCodeInvalidError</a> | <a href="/reference/graphql-api/admin/object-types#couponcodelimiterror">CouponCodeLimitError</a></div>
</div>

## Asset

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Asset</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/admin/enums#assettype">AssetType</a>!</div>

<div class="graphql-code-line ">fileSize: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>

<div class="graphql-code-line ">mimeType: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">width: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>

<div class="graphql-code-line ">height: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>

<div class="graphql-code-line ">source: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">preview: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">focalPoint: <a href="/reference/graphql-api/admin/object-types#coordinate">Coordinate</a></div>

<div class="graphql-code-line ">tags: [<a href="/reference/graphql-api/admin/object-types#tag">Tag</a>!]!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## AssetList

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">AssetList</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/admin/object-types#asset">Asset</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## AuthenticationMethod

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">AuthenticationMethod</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">strategy: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## AuthenticationResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">AuthenticationResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/admin/object-types#currentuser">CurrentUser</a> | <a href="/reference/graphql-api/admin/object-types#invalidcredentialserror">InvalidCredentialsError</a></div>
</div>

## Boolean

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">The <code>Boolean</code> scalar type represents <code>true</code> or `false`.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">scalar <span class="graphql-code-identifier">Boolean</span></div>
</div>

## BooleanCustomFieldConfig

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">BooleanCustomFieldConfig</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">list: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">label: [<a href="/reference/graphql-api/admin/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">description: [<a href="/reference/graphql-api/admin/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">readonly: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">internal: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">nullable: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">requiresPermission: [<a href="/reference/graphql-api/admin/enums#permission">Permission</a>!]</div>

<div class="graphql-code-line ">ui: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## BooleanStructFieldConfig

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">BooleanStructFieldConfig</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">list: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">label: [<a href="/reference/graphql-api/admin/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">description: [<a href="/reference/graphql-api/admin/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">ui: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CancelActiveOrderError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned if an attempting to cancel lines from an Order which is still active</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">CancelActiveOrderError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">orderState: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CancelOrderResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">CancelOrderResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/admin/object-types#order">Order</a> | <a href="/reference/graphql-api/admin/object-types#emptyorderlineselectionerror">EmptyOrderLineSelectionError</a> | <a href="/reference/graphql-api/admin/object-types#quantitytoogreaterror">QuantityTooGreatError</a> | <a href="/reference/graphql-api/admin/object-types#multipleordererror">MultipleOrderError</a> | <a href="/reference/graphql-api/admin/object-types#cancelactiveordererror">CancelActiveOrderError</a> | <a href="/reference/graphql-api/admin/object-types#orderstatetransitionerror">OrderStateTransitionError</a></div>
</div>

## CancelPaymentError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned if the Payment cancellation fails</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">CancelPaymentError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">paymentErrorMessage: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CancelPaymentResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">CancelPaymentResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/admin/object-types#payment">Payment</a> | <a href="/reference/graphql-api/admin/object-types#cancelpaymenterror">CancelPaymentError</a> | <a href="/reference/graphql-api/admin/object-types#paymentstatetransitionerror">PaymentStateTransitionError</a></div>
</div>

## Cancellation

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Cancellation</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">productVariant: <a href="/reference/graphql-api/admin/object-types#productvariant">ProductVariant</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/admin/enums#stockmovementtype">StockMovementType</a>!</div>

<div class="graphql-code-line ">quantity: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>

<div class="graphql-code-line ">orderLine: <a href="/reference/graphql-api/admin/object-types#orderline">OrderLine</a>!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## Channel

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Channel</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">token: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">defaultTaxZone: <a href="/reference/graphql-api/admin/object-types#zone">Zone</a></div>

<div class="graphql-code-line ">defaultShippingZone: <a href="/reference/graphql-api/admin/object-types#zone">Zone</a></div>

<div class="graphql-code-line ">defaultLanguageCode: <a href="/reference/graphql-api/admin/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">availableLanguageCodes: [<a href="/reference/graphql-api/admin/enums#languagecode">LanguageCode</a>!]</div>

<div class="graphql-code-line ">currencyCode: <a href="/reference/graphql-api/admin/enums#currencycode">CurrencyCode</a>!</div>

<div class="graphql-code-line ">defaultCurrencyCode: <a href="/reference/graphql-api/admin/enums#currencycode">CurrencyCode</a>!</div>

<div class="graphql-code-line ">availableCurrencyCodes: [<a href="/reference/graphql-api/admin/enums#currencycode">CurrencyCode</a>!]!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Not yet used - will be implemented in a future release.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">trackInventory: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Not yet used - will be implemented in a future release.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">outOfStockThreshold: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line ">pricesIncludeTax: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">seller: <a href="/reference/graphql-api/admin/object-types#seller">Seller</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ChannelDefaultLanguageError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned when the default LanguageCode of a Channel is no longer found in the `availableLanguages`</div>

<div class="graphql-code-line top-level comment">of the GlobalSettings</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ChannelDefaultLanguageError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">language: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">channelCode: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ChannelList

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ChannelList</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/admin/object-types#channel">Channel</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## Collection

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Collection</span> &#123;</div>
<div class="graphql-code-line ">isPrivate: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">inheritFilters: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/enums#languagecode">LanguageCode</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">slug: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">breadcrumbs: [<a href="/reference/graphql-api/admin/object-types#collectionbreadcrumb">CollectionBreadcrumb</a>!]!</div>

<div class="graphql-code-line ">position: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">featuredAsset: <a href="/reference/graphql-api/admin/object-types#asset">Asset</a></div>

<div class="graphql-code-line ">assets: [<a href="/reference/graphql-api/admin/object-types#asset">Asset</a>!]!</div>

<div class="graphql-code-line ">parent: <a href="/reference/graphql-api/admin/object-types#collection">Collection</a></div>

<div class="graphql-code-line ">parentId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">children: [<a href="/reference/graphql-api/admin/object-types#collection">Collection</a>!]</div>

<div class="graphql-code-line ">filters: [<a href="/reference/graphql-api/admin/object-types#configurableoperation">ConfigurableOperation</a>!]!</div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/admin/object-types#collectiontranslation">CollectionTranslation</a>!]!</div>

<div class="graphql-code-line ">productVariants(options: <a href="/reference/graphql-api/admin/input-types#productvariantlistoptions">ProductVariantListOptions</a>): <a href="/reference/graphql-api/admin/object-types#productvariantlist">ProductVariantList</a>!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CollectionBreadcrumb

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">CollectionBreadcrumb</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">slug: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CollectionList

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">CollectionList</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/admin/object-types#collection">Collection</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CollectionResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Which Collections are present in the products returned</div>

<div class="graphql-code-line top-level comment">by the search, and in what quantity.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">CollectionResult</span> &#123;</div>
<div class="graphql-code-line ">collection: <a href="/reference/graphql-api/admin/object-types#collection">Collection</a>!</div>

<div class="graphql-code-line ">count: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CollectionTranslation

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">CollectionTranslation</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">slug: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ConfigArg

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ConfigArg</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">value: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ConfigArgDefinition

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ConfigArgDefinition</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">list: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">required: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">defaultValue: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>

<div class="graphql-code-line ">label: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">ui: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ConfigurableOperation

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ConfigurableOperation</span> &#123;</div>
<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">args: [<a href="/reference/graphql-api/admin/object-types#configarg">ConfigArg</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ConfigurableOperationDefinition

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ConfigurableOperationDefinition</span> &#123;</div>
<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">args: [<a href="/reference/graphql-api/admin/object-types#configargdefinition">ConfigArgDefinition</a>!]!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## Coordinate

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Coordinate</span> &#123;</div>
<div class="graphql-code-line ">x: <a href="/reference/graphql-api/admin/object-types#float">Float</a>!</div>

<div class="graphql-code-line ">y: <a href="/reference/graphql-api/admin/object-types#float">Float</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## Country

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">A Country of the world which your shop operates in.</div>

<div class="graphql-code-line top-level comment"></div>

<div class="graphql-code-line top-level comment">The <code>code</code> field is typically a 2-character ISO code such as "GB", "US", "DE" etc. This code is used in certain inputs such as</div>

<div class="graphql-code-line top-level comment">`UpdateAddressInput` and <code>CreateAddressInput</code> to specify the country.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Country</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">enabled: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">parent: <a href="/reference/graphql-api/admin/object-types#region">Region</a></div>

<div class="graphql-code-line ">parentId: <a href="/reference/graphql-api/admin/object-types#id">ID</a></div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/admin/object-types#regiontranslation">RegionTranslation</a>!]!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CountryList

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">CountryList</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/admin/object-types#country">Country</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CouponCodeExpiredError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned if the provided coupon code is invalid</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">CouponCodeExpiredError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">couponCode: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CouponCodeInvalidError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned if the provided coupon code is invalid</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">CouponCodeInvalidError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">couponCode: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CouponCodeLimitError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned if the provided coupon code is invalid</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">CouponCodeLimitError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">couponCode: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">limit: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CreateAssetResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">CreateAssetResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/admin/object-types#asset">Asset</a> | <a href="/reference/graphql-api/admin/object-types#mimetypeerror">MimeTypeError</a></div>
</div>

## CreateChannelResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">CreateChannelResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/admin/object-types#channel">Channel</a> | <a href="/reference/graphql-api/admin/object-types#languagenotavailableerror">LanguageNotAvailableError</a></div>
</div>

## CreateCustomerResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">CreateCustomerResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/admin/object-types#customer">Customer</a> | <a href="/reference/graphql-api/admin/object-types#emailaddressconflicterror">EmailAddressConflictError</a></div>
</div>

## CreateFulfillmentError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned if an error is thrown in a FulfillmentHandler's createFulfillment method</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">CreateFulfillmentError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">fulfillmentHandlerError: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CreatePromotionResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">CreatePromotionResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/admin/object-types#promotion">Promotion</a> | <a href="/reference/graphql-api/admin/object-types#missingconditionserror">MissingConditionsError</a></div>
</div>

## CurrentUser

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">CurrentUser</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">identifier: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">channels: [<a href="/reference/graphql-api/admin/object-types#currentuserchannel">CurrentUserChannel</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CurrentUserChannel

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">CurrentUserChannel</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">token: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">permissions: [<a href="/reference/graphql-api/admin/enums#permission">Permission</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CustomFieldConfig

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">CustomFieldConfig</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/admin/object-types#stringcustomfieldconfig">StringCustomFieldConfig</a> | <a href="/reference/graphql-api/admin/object-types#localestringcustomfieldconfig">LocaleStringCustomFieldConfig</a> | <a href="/reference/graphql-api/admin/object-types#intcustomfieldconfig">IntCustomFieldConfig</a> | <a href="/reference/graphql-api/admin/object-types#floatcustomfieldconfig">FloatCustomFieldConfig</a> | <a href="/reference/graphql-api/admin/object-types#booleancustomfieldconfig">BooleanCustomFieldConfig</a> | <a href="/reference/graphql-api/admin/object-types#datetimecustomfieldconfig">DateTimeCustomFieldConfig</a> | <a href="/reference/graphql-api/admin/object-types#relationcustomfieldconfig">RelationCustomFieldConfig</a> | <a href="/reference/graphql-api/admin/object-types#textcustomfieldconfig">TextCustomFieldConfig</a> | <a href="/reference/graphql-api/admin/object-types#localetextcustomfieldconfig">LocaleTextCustomFieldConfig</a> | <a href="/reference/graphql-api/admin/object-types#structcustomfieldconfig">StructCustomFieldConfig</a></div>
</div>

## CustomFields

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">This type is deprecated in v2.2 in favor of the EntityCustomFields type,</div>

<div class="graphql-code-line top-level comment">which allows custom fields to be defined on user-supplied entities.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">CustomFields</span> &#123;</div>
<div class="graphql-code-line ">Address: [<a href="/reference/graphql-api/admin/object-types#customfieldconfig">CustomFieldConfig</a>!]!</div>

<div class="graphql-code-line ">Administrator: [<a href="/reference/graphql-api/admin/object-types#customfieldconfig">CustomFieldConfig</a>!]!</div>

<div class="graphql-code-line ">Asset: [<a href="/reference/graphql-api/admin/object-types#customfieldconfig">CustomFieldConfig</a>!]!</div>

<div class="graphql-code-line ">Channel: [<a href="/reference/graphql-api/admin/object-types#customfieldconfig">CustomFieldConfig</a>!]!</div>

<div class="graphql-code-line ">Collection: [<a href="/reference/graphql-api/admin/object-types#customfieldconfig">CustomFieldConfig</a>!]!</div>

<div class="graphql-code-line ">Customer: [<a href="/reference/graphql-api/admin/object-types#customfieldconfig">CustomFieldConfig</a>!]!</div>

<div class="graphql-code-line ">CustomerGroup: [<a href="/reference/graphql-api/admin/object-types#customfieldconfig">CustomFieldConfig</a>!]!</div>

<div class="graphql-code-line ">Facet: [<a href="/reference/graphql-api/admin/object-types#customfieldconfig">CustomFieldConfig</a>!]!</div>

<div class="graphql-code-line ">FacetValue: [<a href="/reference/graphql-api/admin/object-types#customfieldconfig">CustomFieldConfig</a>!]!</div>

<div class="graphql-code-line ">Fulfillment: [<a href="/reference/graphql-api/admin/object-types#customfieldconfig">CustomFieldConfig</a>!]!</div>

<div class="graphql-code-line ">GlobalSettings: [<a href="/reference/graphql-api/admin/object-types#customfieldconfig">CustomFieldConfig</a>!]!</div>

<div class="graphql-code-line ">HistoryEntry: [<a href="/reference/graphql-api/admin/object-types#customfieldconfig">CustomFieldConfig</a>!]!</div>

<div class="graphql-code-line ">Order: [<a href="/reference/graphql-api/admin/object-types#customfieldconfig">CustomFieldConfig</a>!]!</div>

<div class="graphql-code-line ">OrderLine: [<a href="/reference/graphql-api/admin/object-types#customfieldconfig">CustomFieldConfig</a>!]!</div>

<div class="graphql-code-line ">Payment: [<a href="/reference/graphql-api/admin/object-types#customfieldconfig">CustomFieldConfig</a>!]!</div>

<div class="graphql-code-line ">PaymentMethod: [<a href="/reference/graphql-api/admin/object-types#customfieldconfig">CustomFieldConfig</a>!]!</div>

<div class="graphql-code-line ">Product: [<a href="/reference/graphql-api/admin/object-types#customfieldconfig">CustomFieldConfig</a>!]!</div>

<div class="graphql-code-line ">ProductOption: [<a href="/reference/graphql-api/admin/object-types#customfieldconfig">CustomFieldConfig</a>!]!</div>

<div class="graphql-code-line ">ProductOptionGroup: [<a href="/reference/graphql-api/admin/object-types#customfieldconfig">CustomFieldConfig</a>!]!</div>

<div class="graphql-code-line ">ProductVariant: [<a href="/reference/graphql-api/admin/object-types#customfieldconfig">CustomFieldConfig</a>!]!</div>

<div class="graphql-code-line ">ProductVariantPrice: [<a href="/reference/graphql-api/admin/object-types#customfieldconfig">CustomFieldConfig</a>!]!</div>

<div class="graphql-code-line ">Promotion: [<a href="/reference/graphql-api/admin/object-types#customfieldconfig">CustomFieldConfig</a>!]!</div>

<div class="graphql-code-line ">Refund: [<a href="/reference/graphql-api/admin/object-types#customfieldconfig">CustomFieldConfig</a>!]!</div>

<div class="graphql-code-line ">Region: [<a href="/reference/graphql-api/admin/object-types#customfieldconfig">CustomFieldConfig</a>!]!</div>

<div class="graphql-code-line ">Seller: [<a href="/reference/graphql-api/admin/object-types#customfieldconfig">CustomFieldConfig</a>!]!</div>

<div class="graphql-code-line ">Session: [<a href="/reference/graphql-api/admin/object-types#customfieldconfig">CustomFieldConfig</a>!]!</div>

<div class="graphql-code-line ">ShippingLine: [<a href="/reference/graphql-api/admin/object-types#customfieldconfig">CustomFieldConfig</a>!]!</div>

<div class="graphql-code-line ">ShippingMethod: [<a href="/reference/graphql-api/admin/object-types#customfieldconfig">CustomFieldConfig</a>!]!</div>

<div class="graphql-code-line ">StockLevel: [<a href="/reference/graphql-api/admin/object-types#customfieldconfig">CustomFieldConfig</a>!]!</div>

<div class="graphql-code-line ">StockLocation: [<a href="/reference/graphql-api/admin/object-types#customfieldconfig">CustomFieldConfig</a>!]!</div>

<div class="graphql-code-line ">StockMovement: [<a href="/reference/graphql-api/admin/object-types#customfieldconfig">CustomFieldConfig</a>!]!</div>

<div class="graphql-code-line ">TaxCategory: [<a href="/reference/graphql-api/admin/object-types#customfieldconfig">CustomFieldConfig</a>!]!</div>

<div class="graphql-code-line ">TaxRate: [<a href="/reference/graphql-api/admin/object-types#customfieldconfig">CustomFieldConfig</a>!]!</div>

<div class="graphql-code-line ">User: [<a href="/reference/graphql-api/admin/object-types#customfieldconfig">CustomFieldConfig</a>!]!</div>

<div class="graphql-code-line ">Zone: [<a href="/reference/graphql-api/admin/object-types#customfieldconfig">CustomFieldConfig</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## Customer

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Customer</span> &#123;</div>
<div class="graphql-code-line ">groups: [<a href="/reference/graphql-api/admin/object-types#customergroup">CustomerGroup</a>!]!</div>

<div class="graphql-code-line ">history(options: <a href="/reference/graphql-api/admin/input-types#historyentrylistoptions">HistoryEntryListOptions</a>): <a href="/reference/graphql-api/admin/object-types#historyentrylist">HistoryEntryList</a>!</div>

<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">title: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">firstName: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">lastName: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">phoneNumber: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">emailAddress: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">addresses: [<a href="/reference/graphql-api/admin/object-types#address">Address</a>!]</div>

<div class="graphql-code-line ">orders(options: <a href="/reference/graphql-api/admin/input-types#orderlistoptions">OrderListOptions</a>): <a href="/reference/graphql-api/admin/object-types#orderlist">OrderList</a>!</div>

<div class="graphql-code-line ">user: <a href="/reference/graphql-api/admin/object-types#user">User</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CustomerGroup

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">CustomerGroup</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">customers(options: <a href="/reference/graphql-api/admin/input-types#customerlistoptions">CustomerListOptions</a>): <a href="/reference/graphql-api/admin/object-types#customerlist">CustomerList</a>!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CustomerGroupList

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">CustomerGroupList</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/admin/object-types#customergroup">CustomerGroup</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CustomerList

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">CustomerList</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/admin/object-types#customer">Customer</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## DateTime

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">A date-time string at UTC, such as 2007-12-03T10:15:30Z, compliant with the <code>date-time</code> format outlined in section 5.6 of the RFC 3339 profile of the ISO 8601 standard for representation of dates and times using the Gregorian calendar.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">scalar <span class="graphql-code-identifier">DateTime</span></div>
</div>

## DateTimeCustomFieldConfig

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Expects the same validation formats as the <code>&lt;input type="datetime-local"&gt;</code> HTML element.</div>

<div class="graphql-code-line top-level comment">See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/datetime-local#Additional_attributes</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">DateTimeCustomFieldConfig</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">list: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">label: [<a href="/reference/graphql-api/admin/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">description: [<a href="/reference/graphql-api/admin/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">readonly: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">internal: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">nullable: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">requiresPermission: [<a href="/reference/graphql-api/admin/enums#permission">Permission</a>!]</div>

<div class="graphql-code-line ">min: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">max: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">step: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line ">ui: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## DateTimeStructFieldConfig

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Expects the same validation formats as the <code>&lt;input type="datetime-local"&gt;</code> HTML element.</div>

<div class="graphql-code-line top-level comment">See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/datetime-local#Additional_attributes</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">DateTimeStructFieldConfig</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">list: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">label: [<a href="/reference/graphql-api/admin/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">description: [<a href="/reference/graphql-api/admin/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">min: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">max: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">step: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line ">ui: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## DeletionResponse

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">DeletionResponse</span> &#123;</div>
<div class="graphql-code-line ">result: <a href="/reference/graphql-api/admin/enums#deletionresult">DeletionResult</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## Discount

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Discount</span> &#123;</div>
<div class="graphql-code-line ">adjustmentSource: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/admin/enums#adjustmenttype">AdjustmentType</a>!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">amount: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">amountWithTax: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## DuplicateEntityError

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">DuplicateEntityError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">duplicationError: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## DuplicateEntityResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">DuplicateEntityResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/admin/object-types#duplicateentitysuccess">DuplicateEntitySuccess</a> | <a href="/reference/graphql-api/admin/object-types#duplicateentityerror">DuplicateEntityError</a></div>
</div>

## DuplicateEntitySuccess

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">DuplicateEntitySuccess</span> &#123;</div>
<div class="graphql-code-line ">newEntityId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## EmailAddressConflictError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned when attempting to create a Customer with an email address already registered to an existing User.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">EmailAddressConflictError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## EmptyOrderLineSelectionError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned if no OrderLines have been specified for the operation</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">EmptyOrderLineSelectionError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## EntityCustomFields

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">EntityCustomFields</span> &#123;</div>
<div class="graphql-code-line ">entityName: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">customFields: [<a href="/reference/graphql-api/admin/object-types#customfieldconfig">CustomFieldConfig</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## EntityDuplicatorDefinition

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">EntityDuplicatorDefinition</span> &#123;</div>
<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">args: [<a href="/reference/graphql-api/admin/object-types#configargdefinition">ConfigArgDefinition</a>!]!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">forEntities: [<a href="/reference/graphql-api/admin/object-types#string">String</a>!]!</div>

<div class="graphql-code-line ">requiresPermission: [<a href="/reference/graphql-api/admin/enums#permission">Permission</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## Facet

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Facet</span> &#123;</div>
<div class="graphql-code-line ">isPrivate: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">values: [<a href="/reference/graphql-api/admin/object-types#facetvalue">FacetValue</a>!]!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Returns a paginated, sortable, filterable list of the Facet's values. Added in v2.1.0.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">valueList(options: <a href="/reference/graphql-api/admin/input-types#facetvaluelistoptions">FacetValueListOptions</a>): <a href="/reference/graphql-api/admin/object-types#facetvaluelist">FacetValueList</a>!</div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/admin/object-types#facettranslation">FacetTranslation</a>!]!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## FacetInUseError

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">FacetInUseError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">facetCode: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">productCount: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>

<div class="graphql-code-line ">variantCount: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## FacetList

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">FacetList</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/admin/object-types#facet">Facet</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## FacetTranslation

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">FacetTranslation</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## FacetValue

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">FacetValue</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">facet: <a href="/reference/graphql-api/admin/object-types#facet">Facet</a>!</div>

<div class="graphql-code-line ">facetId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/admin/object-types#facetvaluetranslation">FacetValueTranslation</a>!]!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## FacetValueList

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">FacetValueList</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/admin/object-types#facetvalue">FacetValue</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## FacetValueResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Which FacetValues are present in the products returned</div>

<div class="graphql-code-line top-level comment">by the search, and in what quantity.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">FacetValueResult</span> &#123;</div>
<div class="graphql-code-line ">facetValue: <a href="/reference/graphql-api/admin/object-types#facetvalue">FacetValue</a>!</div>

<div class="graphql-code-line ">count: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## FacetValueTranslation

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">FacetValueTranslation</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## Float

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">The <code>Float</code> scalar type represents signed double-precision fractional values as specified by [IEEE 754](https://en.wikipedia.org/wiki/IEEE_floating_point).</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">scalar <span class="graphql-code-identifier">Float</span></div>
</div>

## FloatCustomFieldConfig

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">FloatCustomFieldConfig</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">list: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">label: [<a href="/reference/graphql-api/admin/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">description: [<a href="/reference/graphql-api/admin/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">readonly: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">internal: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">nullable: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">requiresPermission: [<a href="/reference/graphql-api/admin/enums#permission">Permission</a>!]</div>

<div class="graphql-code-line ">min: <a href="/reference/graphql-api/admin/object-types#float">Float</a></div>

<div class="graphql-code-line ">max: <a href="/reference/graphql-api/admin/object-types#float">Float</a></div>

<div class="graphql-code-line ">step: <a href="/reference/graphql-api/admin/object-types#float">Float</a></div>

<div class="graphql-code-line ">ui: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## FloatStructFieldConfig

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">FloatStructFieldConfig</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">list: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">label: [<a href="/reference/graphql-api/admin/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">description: [<a href="/reference/graphql-api/admin/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">min: <a href="/reference/graphql-api/admin/object-types#float">Float</a></div>

<div class="graphql-code-line ">max: <a href="/reference/graphql-api/admin/object-types#float">Float</a></div>

<div class="graphql-code-line ">step: <a href="/reference/graphql-api/admin/object-types#float">Float</a></div>

<div class="graphql-code-line ">ui: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## Fulfillment

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Fulfillment</span> &#123;</div>
<div class="graphql-code-line ">nextStates: [<a href="/reference/graphql-api/admin/object-types#string">String</a>!]!</div>

<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">lines: [<a href="/reference/graphql-api/admin/object-types#fulfillmentline">FulfillmentLine</a>!]!</div>

<div class="graphql-code-line ">summary: [<a href="/reference/graphql-api/admin/object-types#fulfillmentline">FulfillmentLine</a>!]!</div>

<div class="graphql-code-line ">state: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">method: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">trackingCode: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## FulfillmentLine

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">FulfillmentLine</span> &#123;</div>
<div class="graphql-code-line ">orderLine: <a href="/reference/graphql-api/admin/object-types#orderline">OrderLine</a>!</div>

<div class="graphql-code-line ">orderLineId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">quantity: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>

<div class="graphql-code-line ">fulfillment: <a href="/reference/graphql-api/admin/object-types#fulfillment">Fulfillment</a>!</div>

<div class="graphql-code-line ">fulfillmentId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## FulfillmentStateTransitionError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned when there is an error in transitioning the Fulfillment state</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">FulfillmentStateTransitionError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">transitionError: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">fromState: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">toState: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## GlobalSettings

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">GlobalSettings</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">availableLanguages: [<a href="/reference/graphql-api/admin/enums#languagecode">LanguageCode</a>!]!</div>

<div class="graphql-code-line ">trackInventory: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">outOfStockThreshold: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>

<div class="graphql-code-line ">serverConfig: <a href="/reference/graphql-api/admin/object-types#serverconfig">ServerConfig</a>!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## GuestCheckoutError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned when attempting to set the Customer on a guest checkout when the configured GuestCheckoutStrategy does not allow it.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">GuestCheckoutError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">errorDetail: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## HistoryEntry

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">HistoryEntry</span> &#123;</div>
<div class="graphql-code-line ">isPublic: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">administrator: <a href="/reference/graphql-api/admin/object-types#administrator">Administrator</a></div>

<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/admin/enums#historyentrytype">HistoryEntryType</a>!</div>

<div class="graphql-code-line ">data: <a href="/reference/graphql-api/admin/object-types#json">JSON</a>!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## HistoryEntryList

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">HistoryEntryList</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/admin/object-types#historyentry">HistoryEntry</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ID

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">The <code>ID</code> scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `"4"`) or integer (such as `4`) input value will be accepted as an ID.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">scalar <span class="graphql-code-identifier">ID</span></div>
</div>

## ImportInfo

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ImportInfo</span> &#123;</div>
<div class="graphql-code-line ">errors: [<a href="/reference/graphql-api/admin/object-types#string">String</a>!]</div>

<div class="graphql-code-line ">processed: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>

<div class="graphql-code-line ">imported: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## IneligibleShippingMethodError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned when attempting to set a ShippingMethod for which the Order is not eligible</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">IneligibleShippingMethodError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## InsufficientStockError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned when attempting to add more items to the Order than are available</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">InsufficientStockError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">quantityAvailable: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>

<div class="graphql-code-line ">order: <a href="/reference/graphql-api/admin/object-types#order">Order</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## InsufficientStockOnHandError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned if attempting to create a Fulfillment when there is insufficient</div>

<div class="graphql-code-line top-level comment">stockOnHand of a ProductVariant to satisfy the requested quantity.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">InsufficientStockOnHandError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">productVariantId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">productVariantName: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">stockOnHand: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## Int

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">The <code>Int</code> scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">scalar <span class="graphql-code-identifier">Int</span></div>
</div>

## IntCustomFieldConfig

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">IntCustomFieldConfig</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">list: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">label: [<a href="/reference/graphql-api/admin/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">description: [<a href="/reference/graphql-api/admin/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">readonly: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">internal: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">nullable: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">requiresPermission: [<a href="/reference/graphql-api/admin/enums#permission">Permission</a>!]</div>

<div class="graphql-code-line ">min: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line ">max: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line ">step: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line ">ui: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## IntStructFieldConfig

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">IntStructFieldConfig</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">list: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">label: [<a href="/reference/graphql-api/admin/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">description: [<a href="/reference/graphql-api/admin/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">min: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line ">max: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line ">step: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line ">ui: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## InvalidCredentialsError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned if the user authentication credentials are not valid</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">InvalidCredentialsError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">authenticationError: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## InvalidFulfillmentHandlerError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned if the specified FulfillmentHandler code is not valid</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">InvalidFulfillmentHandlerError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ItemsAlreadyFulfilledError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned if the specified items are already part of a Fulfillment</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ItemsAlreadyFulfilledError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## JSON

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">The <code>JSON</code> scalar type represents JSON values as specified by [ECMA-404](http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf).</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">scalar <span class="graphql-code-identifier">JSON</span></div>
</div>

## Job

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Job</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">startedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a></div>

<div class="graphql-code-line ">settledAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a></div>

<div class="graphql-code-line ">queueName: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">state: <a href="/reference/graphql-api/admin/enums#jobstate">JobState</a>!</div>

<div class="graphql-code-line ">progress: <a href="/reference/graphql-api/admin/object-types#float">Float</a>!</div>

<div class="graphql-code-line ">data: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>

<div class="graphql-code-line ">result: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>

<div class="graphql-code-line ">error: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>

<div class="graphql-code-line ">isSettled: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">duration: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>

<div class="graphql-code-line ">retries: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>

<div class="graphql-code-line ">attempts: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## JobBufferSize

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">JobBufferSize</span> &#123;</div>
<div class="graphql-code-line ">bufferId: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">size: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## JobList

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">JobList</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/admin/object-types#job">Job</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## JobQueue

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">JobQueue</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">running: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## LanguageNotAvailableError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned if attempting to set a Channel's defaultLanguageCode to a language which is not enabled in GlobalSettings</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">LanguageNotAvailableError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## LocaleStringCustomFieldConfig

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">LocaleStringCustomFieldConfig</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">list: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">length: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line ">label: [<a href="/reference/graphql-api/admin/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">description: [<a href="/reference/graphql-api/admin/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">readonly: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">internal: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">nullable: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">requiresPermission: [<a href="/reference/graphql-api/admin/enums#permission">Permission</a>!]</div>

<div class="graphql-code-line ">pattern: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">ui: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## LocaleTextCustomFieldConfig

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">LocaleTextCustomFieldConfig</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">list: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">label: [<a href="/reference/graphql-api/admin/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">description: [<a href="/reference/graphql-api/admin/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">readonly: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">internal: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">nullable: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">requiresPermission: [<a href="/reference/graphql-api/admin/enums#permission">Permission</a>!]</div>

<div class="graphql-code-line ">ui: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## LocalizedString

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">LocalizedString</span> &#123;</div>
<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">value: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ManualPaymentStateError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned when a call to addManualPaymentToOrder is made but the Order</div>

<div class="graphql-code-line top-level comment">is not in the required state.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ManualPaymentStateError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## MetricSummary

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">MetricSummary</span> &#123;</div>
<div class="graphql-code-line ">interval: <a href="/reference/graphql-api/admin/enums#metricinterval">MetricInterval</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/admin/enums#metrictype">MetricType</a>!</div>

<div class="graphql-code-line ">title: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">entries: [<a href="/reference/graphql-api/admin/object-types#metricsummaryentry">MetricSummaryEntry</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## MetricSummaryEntry

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">MetricSummaryEntry</span> &#123;</div>
<div class="graphql-code-line ">label: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">value: <a href="/reference/graphql-api/admin/object-types#float">Float</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## MimeTypeError

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">MimeTypeError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">fileName: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">mimeType: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## MissingConditionsError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned if a PromotionCondition has neither a couponCode nor any conditions set</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">MissingConditionsError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ModifyOrderResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">ModifyOrderResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/admin/object-types#order">Order</a> | <a href="/reference/graphql-api/admin/object-types#nochangesspecifiederror">NoChangesSpecifiedError</a> | <a href="/reference/graphql-api/admin/object-types#ordermodificationstateerror">OrderModificationStateError</a> | <a href="/reference/graphql-api/admin/object-types#paymentmethodmissingerror">PaymentMethodMissingError</a> | <a href="/reference/graphql-api/admin/object-types#refundpaymentidmissingerror">RefundPaymentIdMissingError</a> | <a href="/reference/graphql-api/admin/object-types#orderlimiterror">OrderLimitError</a> | <a href="/reference/graphql-api/admin/object-types#negativequantityerror">NegativeQuantityError</a> | <a href="/reference/graphql-api/admin/object-types#insufficientstockerror">InsufficientStockError</a> | <a href="/reference/graphql-api/admin/object-types#couponcodeexpirederror">CouponCodeExpiredError</a> | <a href="/reference/graphql-api/admin/object-types#couponcodeinvaliderror">CouponCodeInvalidError</a> | <a href="/reference/graphql-api/admin/object-types#couponcodelimiterror">CouponCodeLimitError</a> | <a href="/reference/graphql-api/admin/object-types#ineligibleshippingmethoderror">IneligibleShippingMethodError</a></div>
</div>

## Money

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">The <code>Money</code> scalar type represents monetary values and supports signed double-precision fractional values as specified by [IEEE 754](https://en.wikipedia.org/wiki/IEEE_floating_point).</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">scalar <span class="graphql-code-identifier">Money</span></div>
</div>

## MultipleOrderError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned if an operation has specified OrderLines from multiple Orders</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">MultipleOrderError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## NativeAuthStrategyError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned when attempting an operation that relies on the NativeAuthStrategy, if that strategy is not configured.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">NativeAuthStrategyError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## NativeAuthenticationResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">NativeAuthenticationResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/admin/object-types#currentuser">CurrentUser</a> | <a href="/reference/graphql-api/admin/object-types#invalidcredentialserror">InvalidCredentialsError</a> | <a href="/reference/graphql-api/admin/object-types#nativeauthstrategyerror">NativeAuthStrategyError</a></div>
</div>

## NegativeQuantityError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned when attempting to set a negative OrderLine quantity.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">NegativeQuantityError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## NoActiveOrderError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned when invoking a mutation which depends on there being an active Order on the</div>

<div class="graphql-code-line top-level comment">current session.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">NoActiveOrderError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## NoChangesSpecifiedError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned when a call to modifyOrder fails to specify any changes</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">NoChangesSpecifiedError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## NothingToRefundError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned if an attempting to refund an Order but neither items nor shipping refund was specified</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">NothingToRefundError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## Order

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Order</span> &#123;</div>
<div class="graphql-code-line ">nextStates: [<a href="/reference/graphql-api/admin/object-types#string">String</a>!]!</div>

<div class="graphql-code-line ">modifications: [<a href="/reference/graphql-api/admin/object-types#ordermodification">OrderModification</a>!]!</div>

<div class="graphql-code-line ">sellerOrders: [<a href="/reference/graphql-api/admin/object-types#order">Order</a>!]</div>

<div class="graphql-code-line ">aggregateOrder: <a href="/reference/graphql-api/admin/object-types#order">Order</a></div>

<div class="graphql-code-line ">aggregateOrderId: <a href="/reference/graphql-api/admin/object-types#id">ID</a></div>

<div class="graphql-code-line ">channels: [<a href="/reference/graphql-api/admin/object-types#channel">Channel</a>!]!</div>

<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/admin/enums#ordertype">OrderType</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The date & time that the Order was placed, i.e. the Customer</div>

<div class="graphql-code-line comment">completed the checkout and the Order is no longer "active"</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">orderPlacedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">A unique code for the Order</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">state: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">An order is active as long as the payment process has not been completed</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">active: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">customer: <a href="/reference/graphql-api/admin/object-types#customer">Customer</a></div>

<div class="graphql-code-line ">shippingAddress: <a href="/reference/graphql-api/admin/object-types#orderaddress">OrderAddress</a></div>

<div class="graphql-code-line ">billingAddress: <a href="/reference/graphql-api/admin/object-types#orderaddress">OrderAddress</a></div>

<div class="graphql-code-line ">lines: [<a href="/reference/graphql-api/admin/object-types#orderline">OrderLine</a>!]!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Surcharges are arbitrary modifications to the Order total which are neither</div>

<div class="graphql-code-line comment">ProductVariants nor discounts resulting from applied Promotions. For example,</div>

<div class="graphql-code-line comment">one-off discounts based on customer interaction, or surcharges based on payment</div>

<div class="graphql-code-line comment">methods.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">surcharges: [<a href="/reference/graphql-api/admin/object-types#surcharge">Surcharge</a>!]!</div>

<div class="graphql-code-line ">discounts: [<a href="/reference/graphql-api/admin/object-types#discount">Discount</a>!]!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">An array of all coupon codes applied to the Order</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">couponCodes: [<a href="/reference/graphql-api/admin/object-types#string">String</a>!]!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Promotions applied to the order. Only gets populated after the payment process has completed.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">promotions: [<a href="/reference/graphql-api/admin/object-types#promotion">Promotion</a>!]!</div>

<div class="graphql-code-line ">payments: [<a href="/reference/graphql-api/admin/object-types#payment">Payment</a>!]</div>

<div class="graphql-code-line ">fulfillments: [<a href="/reference/graphql-api/admin/object-types#fulfillment">Fulfillment</a>!]</div>

<div class="graphql-code-line ">totalQuantity: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The subTotal is the total of all OrderLines in the Order. This figure also includes any Order-level</div>

<div class="graphql-code-line comment">discounts which have been prorated (proportionally distributed) amongst the items of each OrderLine.</div>

<div class="graphql-code-line comment">To get a total of all OrderLines which does not account for prorated discounts, use the</div>

<div class="graphql-code-line comment">sum of <code>OrderLine.discountedLinePrice</code> values.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">subTotal: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Same as subTotal, but inclusive of tax</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">subTotalWithTax: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">currencyCode: <a href="/reference/graphql-api/admin/enums#currencycode">CurrencyCode</a>!</div>

<div class="graphql-code-line ">shippingLines: [<a href="/reference/graphql-api/admin/object-types#shippingline">ShippingLine</a>!]!</div>

<div class="graphql-code-line ">shipping: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">shippingWithTax: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Equal to subTotal plus shipping</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">total: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The final payable amount. Equal to subTotalWithTax plus shippingWithTax</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">totalWithTax: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">A summary of the taxes being applied to this Order</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">taxSummary: [<a href="/reference/graphql-api/admin/object-types#ordertaxsummary">OrderTaxSummary</a>!]!</div>

<div class="graphql-code-line ">history(options: <a href="/reference/graphql-api/admin/input-types#historyentrylistoptions">HistoryEntryListOptions</a>): <a href="/reference/graphql-api/admin/object-types#historyentrylist">HistoryEntryList</a>!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## OrderAddress

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">OrderAddress</span> &#123;</div>
<div class="graphql-code-line ">fullName: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">company: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">streetLine1: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">streetLine2: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">city: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">province: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">postalCode: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">country: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">countryCode: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">phoneNumber: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## OrderInterceptorError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned when an order operation is rejected by an OrderInterceptor method.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">OrderInterceptorError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">interceptorError: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## OrderLimitError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned when the maximum order size limit has been reached.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">OrderLimitError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">maxItems: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## OrderLine

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">OrderLine</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">productVariant: <a href="/reference/graphql-api/admin/object-types#productvariant">ProductVariant</a>!</div>

<div class="graphql-code-line ">featuredAsset: <a href="/reference/graphql-api/admin/object-types#asset">Asset</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The price of a single unit, excluding tax and discounts</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">unitPrice: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The price of a single unit, including tax but excluding discounts</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">unitPriceWithTax: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Non-zero if the unitPrice has changed since it was initially added to Order</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">unitPriceChangeSinceAdded: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Non-zero if the unitPriceWithTax has changed since it was initially added to Order</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">unitPriceWithTaxChangeSinceAdded: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The price of a single unit including discounts, excluding tax.</div>

<div class="graphql-code-line comment"></div>

<div class="graphql-code-line comment">If Order-level discounts have been applied, this will not be the</div>

<div class="graphql-code-line comment">actual taxable unit price (see `proratedUnitPrice`), but is generally the</div>

<div class="graphql-code-line comment">correct price to display to customers to avoid confusion</div>

<div class="graphql-code-line comment">about the internal handling of distributed Order-level discounts.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">discountedUnitPrice: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The price of a single unit including discounts and tax</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">discountedUnitPriceWithTax: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The actual unit price, taking into account both item discounts _and_ prorated (proportionally-distributed)</div>

<div class="graphql-code-line comment">Order-level discounts. This value is the true economic value of the OrderItem, and is used in tax</div>

<div class="graphql-code-line comment">and refund calculations.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">proratedUnitPrice: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The proratedUnitPrice including tax</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">proratedUnitPriceWithTax: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The quantity of items purchased</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">quantity: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The quantity at the time the Order was placed</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">orderPlacedQuantity: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>

<div class="graphql-code-line ">taxRate: <a href="/reference/graphql-api/admin/object-types#float">Float</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The total price of the line excluding tax and discounts.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">linePrice: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The total price of the line including tax but excluding discounts.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">linePriceWithTax: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The price of the line including discounts, excluding tax</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">discountedLinePrice: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The price of the line including discounts and tax</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">discountedLinePriceWithTax: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The actual line price, taking into account both item discounts _and_ prorated (proportionally-distributed)</div>

<div class="graphql-code-line comment">Order-level discounts. This value is the true economic value of the OrderLine, and is used in tax</div>

<div class="graphql-code-line comment">and refund calculations.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">proratedLinePrice: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The proratedLinePrice including tax</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">proratedLinePriceWithTax: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The total tax on this line</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">lineTax: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">discounts: [<a href="/reference/graphql-api/admin/object-types#discount">Discount</a>!]!</div>

<div class="graphql-code-line ">taxLines: [<a href="/reference/graphql-api/admin/object-types#taxline">TaxLine</a>!]!</div>

<div class="graphql-code-line ">order: <a href="/reference/graphql-api/admin/object-types#order">Order</a>!</div>

<div class="graphql-code-line ">fulfillmentLines: [<a href="/reference/graphql-api/admin/object-types#fulfillmentline">FulfillmentLine</a>!]</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## OrderList

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">OrderList</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/admin/object-types#order">Order</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## OrderModification

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">OrderModification</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">priceChange: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">note: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">lines: [<a href="/reference/graphql-api/admin/object-types#ordermodificationline">OrderModificationLine</a>!]!</div>

<div class="graphql-code-line ">surcharges: [<a href="/reference/graphql-api/admin/object-types#surcharge">Surcharge</a>!]</div>

<div class="graphql-code-line ">payment: <a href="/reference/graphql-api/admin/object-types#payment">Payment</a></div>

<div class="graphql-code-line ">refund: <a href="/reference/graphql-api/admin/object-types#refund">Refund</a></div>

<div class="graphql-code-line ">isSettled: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## OrderModificationError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned when attempting to modify the contents of an Order that is not in the <code>AddingItems</code> state.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">OrderModificationError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## OrderModificationLine

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">OrderModificationLine</span> &#123;</div>
<div class="graphql-code-line ">orderLine: <a href="/reference/graphql-api/admin/object-types#orderline">OrderLine</a>!</div>

<div class="graphql-code-line ">orderLineId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">quantity: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>

<div class="graphql-code-line ">modification: <a href="/reference/graphql-api/admin/object-types#ordermodification">OrderModification</a>!</div>

<div class="graphql-code-line ">modificationId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## OrderModificationStateError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned when attempting to modify the contents of an Order that is not in the <code>Modifying</code> state.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">OrderModificationStateError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## OrderProcessState

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">OrderProcessState</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">to: [<a href="/reference/graphql-api/admin/object-types#string">String</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## OrderStateTransitionError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned if there is an error in transitioning the Order state</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">OrderStateTransitionError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">transitionError: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">fromState: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">toState: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## OrderTaxSummary

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">A summary of the taxes being applied to this order, grouped</div>

<div class="graphql-code-line top-level comment">by taxRate.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">OrderTaxSummary</span> &#123;</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">A description of this tax</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The taxRate as a percentage</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">taxRate: <a href="/reference/graphql-api/admin/object-types#float">Float</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The total net price of OrderLines to which this taxRate applies</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">taxBase: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The total tax being applied to the Order at this taxRate</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">taxTotal: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## Payment

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Payment</span> &#123;</div>
<div class="graphql-code-line ">nextStates: [<a href="/reference/graphql-api/admin/object-types#string">String</a>!]!</div>

<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">method: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">amount: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">state: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">transactionId: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">errorMessage: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">refunds: [<a href="/reference/graphql-api/admin/object-types#refund">Refund</a>!]!</div>

<div class="graphql-code-line ">metadata: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## PaymentMethod

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">PaymentMethod</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">enabled: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">checker: <a href="/reference/graphql-api/admin/object-types#configurableoperation">ConfigurableOperation</a></div>

<div class="graphql-code-line ">handler: <a href="/reference/graphql-api/admin/object-types#configurableoperation">ConfigurableOperation</a>!</div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/admin/object-types#paymentmethodtranslation">PaymentMethodTranslation</a>!]!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## PaymentMethodList

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">PaymentMethodList</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/admin/object-types#paymentmethod">PaymentMethod</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## PaymentMethodMissingError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned when a call to modifyOrder fails to include a paymentMethod even</div>

<div class="graphql-code-line top-level comment">though the price has increased as a result of the changes.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">PaymentMethodMissingError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## PaymentMethodQuote

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">PaymentMethodQuote</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">isEligible: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">eligibilityMessage: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## PaymentMethodTranslation

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">PaymentMethodTranslation</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## PaymentOrderMismatchError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned if an attempting to refund a Payment against OrderLines from a different Order</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">PaymentOrderMismatchError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## PaymentStateTransitionError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned when there is an error in transitioning the Payment state</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">PaymentStateTransitionError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">transitionError: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">fromState: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">toState: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## PermissionDefinition

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">PermissionDefinition</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">assignable: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## PriceRange

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">The price range where the result has more than one price</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">PriceRange</span> &#123;</div>
<div class="graphql-code-line ">min: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">max: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## Product

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Product</span> &#123;</div>
<div class="graphql-code-line ">channels: [<a href="/reference/graphql-api/admin/object-types#channel">Channel</a>!]!</div>

<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">slug: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">enabled: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">featuredAsset: <a href="/reference/graphql-api/admin/object-types#asset">Asset</a></div>

<div class="graphql-code-line ">assets: [<a href="/reference/graphql-api/admin/object-types#asset">Asset</a>!]!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Returns all ProductVariants</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">variants: [<a href="/reference/graphql-api/admin/object-types#productvariant">ProductVariant</a>!]!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Returns a paginated, sortable, filterable list of ProductVariants</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">variantList(options: <a href="/reference/graphql-api/admin/input-types#productvariantlistoptions">ProductVariantListOptions</a>): <a href="/reference/graphql-api/admin/object-types#productvariantlist">ProductVariantList</a>!</div>

<div class="graphql-code-line ">optionGroups: [<a href="/reference/graphql-api/admin/object-types#productoptiongroup">ProductOptionGroup</a>!]!</div>

<div class="graphql-code-line ">facetValues: [<a href="/reference/graphql-api/admin/object-types#facetvalue">FacetValue</a>!]!</div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/admin/object-types#producttranslation">ProductTranslation</a>!]!</div>

<div class="graphql-code-line ">collections: [<a href="/reference/graphql-api/admin/object-types#collection">Collection</a>!]!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ProductList

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ProductList</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/admin/object-types#product">Product</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ProductOption

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ProductOption</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">groupId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">group: <a href="/reference/graphql-api/admin/object-types#productoptiongroup">ProductOptionGroup</a>!</div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/admin/object-types#productoptiontranslation">ProductOptionTranslation</a>!]!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ProductOptionGroup

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ProductOptionGroup</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">options: [<a href="/reference/graphql-api/admin/object-types#productoption">ProductOption</a>!]!</div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/admin/object-types#productoptiongrouptranslation">ProductOptionGroupTranslation</a>!]!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ProductOptionGroupTranslation

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ProductOptionGroupTranslation</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ProductOptionInUseError

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ProductOptionInUseError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">optionGroupCode: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">productVariantCount: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ProductOptionTranslation

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ProductOptionTranslation</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ProductTranslation

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ProductTranslation</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">slug: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ProductVariant

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ProductVariant</span> &#123;</div>
<div class="graphql-code-line ">enabled: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">trackInventory: <a href="/reference/graphql-api/admin/enums#globalflag">GlobalFlag</a>!</div>

<div class="graphql-code-line ">stockOnHand: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>

<div class="graphql-code-line ">stockAllocated: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>

<div class="graphql-code-line ">outOfStockThreshold: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>

<div class="graphql-code-line ">useGlobalOutOfStockThreshold: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">prices: [<a href="/reference/graphql-api/admin/object-types#productvariantprice">ProductVariantPrice</a>!]!</div>

<div class="graphql-code-line ">stockLevels: [<a href="/reference/graphql-api/admin/object-types#stocklevel">StockLevel</a>!]!</div>

<div class="graphql-code-line ">stockMovements(options: <a href="/reference/graphql-api/admin/input-types#stockmovementlistoptions">StockMovementListOptions</a>): <a href="/reference/graphql-api/admin/object-types#stockmovementlist">StockMovementList</a>!</div>

<div class="graphql-code-line ">channels: [<a href="/reference/graphql-api/admin/object-types#channel">Channel</a>!]!</div>

<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">product: <a href="/reference/graphql-api/admin/object-types#product">Product</a>!</div>

<div class="graphql-code-line ">productId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">sku: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">featuredAsset: <a href="/reference/graphql-api/admin/object-types#asset">Asset</a></div>

<div class="graphql-code-line ">assets: [<a href="/reference/graphql-api/admin/object-types#asset">Asset</a>!]!</div>

<div class="graphql-code-line ">price: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">currencyCode: <a href="/reference/graphql-api/admin/enums#currencycode">CurrencyCode</a>!</div>

<div class="graphql-code-line ">priceWithTax: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">stockLevel: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">taxRateApplied: <a href="/reference/graphql-api/admin/object-types#taxrate">TaxRate</a>!</div>

<div class="graphql-code-line ">taxCategory: <a href="/reference/graphql-api/admin/object-types#taxcategory">TaxCategory</a>!</div>

<div class="graphql-code-line ">options: [<a href="/reference/graphql-api/admin/object-types#productoption">ProductOption</a>!]!</div>

<div class="graphql-code-line ">facetValues: [<a href="/reference/graphql-api/admin/object-types#facetvalue">FacetValue</a>!]!</div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/admin/object-types#productvarianttranslation">ProductVariantTranslation</a>!]!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ProductVariantList

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ProductVariantList</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/admin/object-types#productvariant">ProductVariant</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ProductVariantPrice

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ProductVariantPrice</span> &#123;</div>
<div class="graphql-code-line ">currencyCode: <a href="/reference/graphql-api/admin/enums#currencycode">CurrencyCode</a>!</div>

<div class="graphql-code-line ">price: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ProductVariantTranslation

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ProductVariantTranslation</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## Promotion

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Promotion</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">startsAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a></div>

<div class="graphql-code-line ">endsAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a></div>

<div class="graphql-code-line ">couponCode: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">perCustomerUsageLimit: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line ">usageLimit: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">enabled: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">conditions: [<a href="/reference/graphql-api/admin/object-types#configurableoperation">ConfigurableOperation</a>!]!</div>

<div class="graphql-code-line ">actions: [<a href="/reference/graphql-api/admin/object-types#configurableoperation">ConfigurableOperation</a>!]!</div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/admin/object-types#promotiontranslation">PromotionTranslation</a>!]!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## PromotionList

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">PromotionList</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/admin/object-types#promotion">Promotion</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## PromotionTranslation

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">PromotionTranslation</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## Province

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Province</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">enabled: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">parent: <a href="/reference/graphql-api/admin/object-types#region">Region</a></div>

<div class="graphql-code-line ">parentId: <a href="/reference/graphql-api/admin/object-types#id">ID</a></div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/admin/object-types#regiontranslation">RegionTranslation</a>!]!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ProvinceList

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ProvinceList</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/admin/object-types#province">Province</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## QuantityTooGreatError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned if the specified quantity of an OrderLine is greater than the number of items in that line</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">QuantityTooGreatError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## Refund

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Refund</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">items: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">shipping: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">adjustment: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">total: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">method: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">state: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">transactionId: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">reason: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">lines: [<a href="/reference/graphql-api/admin/object-types#refundline">RefundLine</a>!]!</div>

<div class="graphql-code-line ">paymentId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">metadata: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## RefundAmountError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned if <code>amount</code> is greater than the maximum un-refunded amount of the Payment</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">RefundAmountError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">maximumRefundable: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## RefundLine

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">RefundLine</span> &#123;</div>
<div class="graphql-code-line ">orderLine: <a href="/reference/graphql-api/admin/object-types#orderline">OrderLine</a>!</div>

<div class="graphql-code-line ">orderLineId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">quantity: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>

<div class="graphql-code-line ">refund: <a href="/reference/graphql-api/admin/object-types#refund">Refund</a>!</div>

<div class="graphql-code-line ">refundId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## RefundOrderResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">RefundOrderResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/admin/object-types#refund">Refund</a> | <a href="/reference/graphql-api/admin/object-types#quantitytoogreaterror">QuantityTooGreatError</a> | <a href="/reference/graphql-api/admin/object-types#nothingtorefunderror">NothingToRefundError</a> | <a href="/reference/graphql-api/admin/object-types#orderstatetransitionerror">OrderStateTransitionError</a> | <a href="/reference/graphql-api/admin/object-types#multipleordererror">MultipleOrderError</a> | <a href="/reference/graphql-api/admin/object-types#paymentordermismatcherror">PaymentOrderMismatchError</a> | <a href="/reference/graphql-api/admin/object-types#refundorderstateerror">RefundOrderStateError</a> | <a href="/reference/graphql-api/admin/object-types#alreadyrefundederror">AlreadyRefundedError</a> | <a href="/reference/graphql-api/admin/object-types#refundstatetransitionerror">RefundStateTransitionError</a> | <a href="/reference/graphql-api/admin/object-types#refundamounterror">RefundAmountError</a></div>
</div>

## RefundOrderStateError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned if an attempting to refund an Order which is not in the expected state</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">RefundOrderStateError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">orderState: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## RefundPaymentIdMissingError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned when a call to modifyOrder fails to include a refundPaymentId even</div>

<div class="graphql-code-line top-level comment">though the price has decreased as a result of the changes.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">RefundPaymentIdMissingError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## RefundStateTransitionError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned when there is an error in transitioning the Refund state</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">RefundStateTransitionError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">transitionError: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">fromState: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">toState: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## RegionTranslation

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">RegionTranslation</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## RelationCustomFieldConfig

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">RelationCustomFieldConfig</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">list: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">label: [<a href="/reference/graphql-api/admin/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">description: [<a href="/reference/graphql-api/admin/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">readonly: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">internal: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">nullable: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">requiresPermission: [<a href="/reference/graphql-api/admin/enums#permission">Permission</a>!]</div>

<div class="graphql-code-line ">entity: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">scalarFields: [<a href="/reference/graphql-api/admin/object-types#string">String</a>!]!</div>

<div class="graphql-code-line ">ui: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## Release

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Release</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">productVariant: <a href="/reference/graphql-api/admin/object-types#productvariant">ProductVariant</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/admin/enums#stockmovementtype">StockMovementType</a>!</div>

<div class="graphql-code-line ">quantity: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## RemoveFacetFromChannelResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">RemoveFacetFromChannelResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/admin/object-types#facet">Facet</a> | <a href="/reference/graphql-api/admin/object-types#facetinuseerror">FacetInUseError</a></div>
</div>

## RemoveOptionGroupFromProductResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">RemoveOptionGroupFromProductResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/admin/object-types#product">Product</a> | <a href="/reference/graphql-api/admin/object-types#productoptioninuseerror">ProductOptionInUseError</a></div>
</div>

## RemoveOrderItemsResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">RemoveOrderItemsResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/admin/object-types#order">Order</a> | <a href="/reference/graphql-api/admin/object-types#ordermodificationerror">OrderModificationError</a> | <a href="/reference/graphql-api/admin/object-types#orderinterceptorerror">OrderInterceptorError</a></div>
</div>

## Return

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Return</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">productVariant: <a href="/reference/graphql-api/admin/object-types#productvariant">ProductVariant</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/admin/enums#stockmovementtype">StockMovementType</a>!</div>

<div class="graphql-code-line ">quantity: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## Role

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Role</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">permissions: [<a href="/reference/graphql-api/admin/enums#permission">Permission</a>!]!</div>

<div class="graphql-code-line ">channels: [<a href="/reference/graphql-api/admin/object-types#channel">Channel</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## RoleList

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">RoleList</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/admin/object-types#role">Role</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## Sale

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Sale</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">productVariant: <a href="/reference/graphql-api/admin/object-types#productvariant">ProductVariant</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/admin/enums#stockmovementtype">StockMovementType</a>!</div>

<div class="graphql-code-line ">quantity: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ScheduledTask

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ScheduledTask</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">schedule: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">scheduleDescription: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">lastExecutedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a></div>

<div class="graphql-code-line ">nextExecutionAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a></div>

<div class="graphql-code-line ">isRunning: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">lastResult: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>

<div class="graphql-code-line ">enabled: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## SearchReindexResponse

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">SearchReindexResponse</span> &#123;</div>
<div class="graphql-code-line ">success: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## SearchResponse

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">SearchResponse</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/admin/object-types#searchresult">SearchResult</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>

<div class="graphql-code-line ">facetValues: [<a href="/reference/graphql-api/admin/object-types#facetvalueresult">FacetValueResult</a>!]!</div>

<div class="graphql-code-line ">collections: [<a href="/reference/graphql-api/admin/object-types#collectionresult">CollectionResult</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## SearchResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">SearchResult</span> &#123;</div>
<div class="graphql-code-line ">enabled: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">An array of ids of the Channels in which this result appears</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">channelIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!</div>

<div class="graphql-code-line ">sku: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">slug: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">productId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">productName: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">productAsset: <a href="/reference/graphql-api/admin/object-types#searchresultasset">SearchResultAsset</a></div>

<div class="graphql-code-line ">productVariantId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">productVariantName: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">productVariantAsset: <a href="/reference/graphql-api/admin/object-types#searchresultasset">SearchResultAsset</a></div>

<div class="graphql-code-line ">price: <a href="/reference/graphql-api/admin/object-types#searchresultprice">SearchResultPrice</a>!</div>

<div class="graphql-code-line ">priceWithTax: <a href="/reference/graphql-api/admin/object-types#searchresultprice">SearchResultPrice</a>!</div>

<div class="graphql-code-line ">currencyCode: <a href="/reference/graphql-api/admin/enums#currencycode">CurrencyCode</a>!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">facetIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!</div>

<div class="graphql-code-line ">facetValueIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">An array of ids of the Collections in which this result appears</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">collectionIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">A relevance score for the result. Differs between database implementations</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">score: <a href="/reference/graphql-api/admin/object-types#float">Float</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## SearchResultAsset

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">SearchResultAsset</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">preview: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">focalPoint: <a href="/reference/graphql-api/admin/object-types#coordinate">Coordinate</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## SearchResultPrice

<div class="graphql-code-block">
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The price of a search result product, either as a range or as a single price</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">SearchResultPrice</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/admin/object-types#pricerange">PriceRange</a> | <a href="/reference/graphql-api/admin/object-types#singleprice">SinglePrice</a></div>
</div>

## Seller

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Seller</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## SellerList

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">SellerList</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/admin/object-types#seller">Seller</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ServerConfig

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ServerConfig</span> &#123;</div>
<div class="graphql-code-line ">orderProcess: [<a href="/reference/graphql-api/admin/object-types#orderprocessstate">OrderProcessState</a>!]!</div>

<div class="graphql-code-line ">permittedAssetTypes: [<a href="/reference/graphql-api/admin/object-types#string">String</a>!]!</div>

<div class="graphql-code-line ">permissions: [<a href="/reference/graphql-api/admin/object-types#permissiondefinition">PermissionDefinition</a>!]!</div>

<div class="graphql-code-line ">moneyStrategyPrecision: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">This field is deprecated in v2.2 in favor of the entityCustomFields field,</div>

<div class="graphql-code-line comment">which allows custom fields to be defined on user-supplies entities.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">customFieldConfig: <a href="/reference/graphql-api/admin/object-types#customfields">CustomFields</a>!</div>

<div class="graphql-code-line ">entityCustomFields: [<a href="/reference/graphql-api/admin/object-types#entitycustomfields">EntityCustomFields</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## SetCustomerForDraftOrderResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">SetCustomerForDraftOrderResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/admin/object-types#order">Order</a> | <a href="/reference/graphql-api/admin/object-types#emailaddressconflicterror">EmailAddressConflictError</a></div>
</div>

## SetOrderShippingMethodResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">SetOrderShippingMethodResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/admin/object-types#order">Order</a> | <a href="/reference/graphql-api/admin/object-types#ordermodificationerror">OrderModificationError</a> | <a href="/reference/graphql-api/admin/object-types#ineligibleshippingmethoderror">IneligibleShippingMethodError</a> | <a href="/reference/graphql-api/admin/object-types#noactiveordererror">NoActiveOrderError</a></div>
</div>

## SetSettingsStoreValueResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">SetSettingsStoreValueResult</span> &#123;</div>
<div class="graphql-code-line ">key: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">result: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">error: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## SettlePaymentError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned if the Payment settlement fails</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">SettlePaymentError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/admin/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">paymentErrorMessage: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## SettlePaymentResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">SettlePaymentResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/admin/object-types#payment">Payment</a> | <a href="/reference/graphql-api/admin/object-types#settlepaymenterror">SettlePaymentError</a> | <a href="/reference/graphql-api/admin/object-types#paymentstatetransitionerror">PaymentStateTransitionError</a> | <a href="/reference/graphql-api/admin/object-types#orderstatetransitionerror">OrderStateTransitionError</a></div>
</div>

## SettleRefundResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">SettleRefundResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/admin/object-types#refund">Refund</a> | <a href="/reference/graphql-api/admin/object-types#refundstatetransitionerror">RefundStateTransitionError</a></div>
</div>

## ShippingLine

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ShippingLine</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">shippingMethod: <a href="/reference/graphql-api/admin/object-types#shippingmethod">ShippingMethod</a>!</div>

<div class="graphql-code-line ">price: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">priceWithTax: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">discountedPrice: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">discountedPriceWithTax: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">discounts: [<a href="/reference/graphql-api/admin/object-types#discount">Discount</a>!]!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ShippingMethod

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ShippingMethod</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">fulfillmentHandlerCode: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">checker: <a href="/reference/graphql-api/admin/object-types#configurableoperation">ConfigurableOperation</a>!</div>

<div class="graphql-code-line ">calculator: <a href="/reference/graphql-api/admin/object-types#configurableoperation">ConfigurableOperation</a>!</div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/admin/object-types#shippingmethodtranslation">ShippingMethodTranslation</a>!]!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ShippingMethodList

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ShippingMethodList</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/admin/object-types#shippingmethod">ShippingMethod</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ShippingMethodQuote

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ShippingMethodQuote</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">price: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">priceWithTax: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Any optional metadata returned by the ShippingCalculator in the ShippingCalculationResult</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">metadata: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ShippingMethodTranslation

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ShippingMethodTranslation</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/admin/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## SinglePrice

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">The price value where the result has a single price</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">SinglePrice</span> &#123;</div>
<div class="graphql-code-line ">value: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## StockAdjustment

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">StockAdjustment</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">productVariant: <a href="/reference/graphql-api/admin/object-types#productvariant">ProductVariant</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/admin/enums#stockmovementtype">StockMovementType</a>!</div>

<div class="graphql-code-line ">quantity: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## StockLevel

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">StockLevel</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">stockLocationId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">stockOnHand: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>

<div class="graphql-code-line ">stockAllocated: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>

<div class="graphql-code-line ">stockLocation: <a href="/reference/graphql-api/admin/object-types#stocklocation">StockLocation</a>!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## StockLocation

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">StockLocation</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## StockLocationList

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">StockLocationList</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/admin/object-types#stocklocation">StockLocation</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## StockMovementItem

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">StockMovementItem</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/admin/object-types#stockadjustment">StockAdjustment</a> | <a href="/reference/graphql-api/admin/object-types#allocation">Allocation</a> | <a href="/reference/graphql-api/admin/object-types#sale">Sale</a> | <a href="/reference/graphql-api/admin/object-types#cancellation">Cancellation</a> | <a href="/reference/graphql-api/admin/object-types#return">Return</a> | <a href="/reference/graphql-api/admin/object-types#release">Release</a></div>
</div>

## StockMovementList

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">StockMovementList</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/admin/object-types#stockmovementitem">StockMovementItem</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## String

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">The <code>String</code> scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">scalar <span class="graphql-code-identifier">String</span></div>
</div>

## StringCustomFieldConfig

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">StringCustomFieldConfig</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">list: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">length: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line ">label: [<a href="/reference/graphql-api/admin/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">description: [<a href="/reference/graphql-api/admin/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">readonly: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">internal: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">nullable: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">requiresPermission: [<a href="/reference/graphql-api/admin/enums#permission">Permission</a>!]</div>

<div class="graphql-code-line ">pattern: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">options: [<a href="/reference/graphql-api/admin/object-types#stringfieldoption">StringFieldOption</a>!]</div>

<div class="graphql-code-line ">ui: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## StringFieldOption

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">StringFieldOption</span> &#123;</div>
<div class="graphql-code-line ">value: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">label: [<a href="/reference/graphql-api/admin/object-types#localizedstring">LocalizedString</a>!]</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## StringStructFieldConfig

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">StringStructFieldConfig</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">list: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">label: [<a href="/reference/graphql-api/admin/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">description: [<a href="/reference/graphql-api/admin/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">length: <a href="/reference/graphql-api/admin/object-types#int">Int</a></div>

<div class="graphql-code-line ">pattern: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">options: [<a href="/reference/graphql-api/admin/object-types#stringfieldoption">StringFieldOption</a>!]</div>

<div class="graphql-code-line ">ui: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## StructCustomFieldConfig

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">StructCustomFieldConfig</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">list: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">fields: [<a href="/reference/graphql-api/admin/object-types#structfieldconfig">StructFieldConfig</a>!]!</div>

<div class="graphql-code-line ">label: [<a href="/reference/graphql-api/admin/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">description: [<a href="/reference/graphql-api/admin/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">readonly: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">internal: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">nullable: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">requiresPermission: [<a href="/reference/graphql-api/admin/enums#permission">Permission</a>!]</div>

<div class="graphql-code-line ">ui: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## StructFieldConfig

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">StructFieldConfig</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/admin/object-types#stringstructfieldconfig">StringStructFieldConfig</a> | <a href="/reference/graphql-api/admin/object-types#intstructfieldconfig">IntStructFieldConfig</a> | <a href="/reference/graphql-api/admin/object-types#floatstructfieldconfig">FloatStructFieldConfig</a> | <a href="/reference/graphql-api/admin/object-types#booleanstructfieldconfig">BooleanStructFieldConfig</a> | <a href="/reference/graphql-api/admin/object-types#datetimestructfieldconfig">DateTimeStructFieldConfig</a> | <a href="/reference/graphql-api/admin/object-types#textstructfieldconfig">TextStructFieldConfig</a></div>
</div>

## Success

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Indicates that an operation succeeded, where we do not want to return any more specific information.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Success</span> &#123;</div>
<div class="graphql-code-line ">success: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## Surcharge

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Surcharge</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">sku: <a href="/reference/graphql-api/admin/object-types#string">String</a></div>

<div class="graphql-code-line ">taxLines: [<a href="/reference/graphql-api/admin/object-types#taxline">TaxLine</a>!]!</div>

<div class="graphql-code-line ">price: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">priceWithTax: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">taxRate: <a href="/reference/graphql-api/admin/object-types#float">Float</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## Tag

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Tag</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">value: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## TagList

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">TagList</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/admin/object-types#tag">Tag</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## TaxCategory

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">TaxCategory</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">isDefault: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## TaxCategoryList

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">TaxCategoryList</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/admin/object-types#taxcategory">TaxCategory</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## TaxLine

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">TaxLine</span> &#123;</div>
<div class="graphql-code-line ">description: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">taxRate: <a href="/reference/graphql-api/admin/object-types#float">Float</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## TaxRate

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">TaxRate</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">enabled: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">value: <a href="/reference/graphql-api/admin/object-types#float">Float</a>!</div>

<div class="graphql-code-line ">category: <a href="/reference/graphql-api/admin/object-types#taxcategory">TaxCategory</a>!</div>

<div class="graphql-code-line ">zone: <a href="/reference/graphql-api/admin/object-types#zone">Zone</a>!</div>

<div class="graphql-code-line ">customerGroup: <a href="/reference/graphql-api/admin/object-types#customergroup">CustomerGroup</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## TaxRateList

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">TaxRateList</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/admin/object-types#taxrate">TaxRate</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## TestShippingMethodQuote

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">TestShippingMethodQuote</span> &#123;</div>
<div class="graphql-code-line ">price: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">priceWithTax: <a href="/reference/graphql-api/admin/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">metadata: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## TestShippingMethodResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">TestShippingMethodResult</span> &#123;</div>
<div class="graphql-code-line ">eligible: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">quote: <a href="/reference/graphql-api/admin/object-types#testshippingmethodquote">TestShippingMethodQuote</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## TextCustomFieldConfig

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">TextCustomFieldConfig</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">list: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">label: [<a href="/reference/graphql-api/admin/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">description: [<a href="/reference/graphql-api/admin/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">readonly: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">internal: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">nullable: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">requiresPermission: [<a href="/reference/graphql-api/admin/enums#permission">Permission</a>!]</div>

<div class="graphql-code-line ">ui: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## TextStructFieldConfig

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">TextStructFieldConfig</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">list: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">label: [<a href="/reference/graphql-api/admin/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">description: [<a href="/reference/graphql-api/admin/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">ui: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## TransitionFulfillmentToStateResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">TransitionFulfillmentToStateResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/admin/object-types#fulfillment">Fulfillment</a> | <a href="/reference/graphql-api/admin/object-types#fulfillmentstatetransitionerror">FulfillmentStateTransitionError</a></div>
</div>

## TransitionOrderToStateResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">TransitionOrderToStateResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/admin/object-types#order">Order</a> | <a href="/reference/graphql-api/admin/object-types#orderstatetransitionerror">OrderStateTransitionError</a></div>
</div>

## TransitionPaymentToStateResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">TransitionPaymentToStateResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/admin/object-types#payment">Payment</a> | <a href="/reference/graphql-api/admin/object-types#paymentstatetransitionerror">PaymentStateTransitionError</a></div>
</div>

## UpdateChannelResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">UpdateChannelResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/admin/object-types#channel">Channel</a> | <a href="/reference/graphql-api/admin/object-types#languagenotavailableerror">LanguageNotAvailableError</a></div>
</div>

## UpdateCustomerResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">UpdateCustomerResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/admin/object-types#customer">Customer</a> | <a href="/reference/graphql-api/admin/object-types#emailaddressconflicterror">EmailAddressConflictError</a></div>
</div>

## UpdateGlobalSettingsResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">UpdateGlobalSettingsResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/admin/object-types#globalsettings">GlobalSettings</a> | <a href="/reference/graphql-api/admin/object-types#channeldefaultlanguageerror">ChannelDefaultLanguageError</a></div>
</div>

## UpdateOrderItemErrorResult

<div class="graphql-code-block">
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Union type of all possible errors that can occur when adding or removing items from an Order.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">UpdateOrderItemErrorResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/admin/object-types#ordermodificationerror">OrderModificationError</a> | <a href="/reference/graphql-api/admin/object-types#orderlimiterror">OrderLimitError</a> | <a href="/reference/graphql-api/admin/object-types#negativequantityerror">NegativeQuantityError</a> | <a href="/reference/graphql-api/admin/object-types#insufficientstockerror">InsufficientStockError</a> | <a href="/reference/graphql-api/admin/object-types#orderinterceptorerror">OrderInterceptorError</a></div>
</div>

## UpdateOrderItemsResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">UpdateOrderItemsResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/admin/object-types#order">Order</a> | <a href="/reference/graphql-api/admin/object-types#ordermodificationerror">OrderModificationError</a> | <a href="/reference/graphql-api/admin/object-types#orderlimiterror">OrderLimitError</a> | <a href="/reference/graphql-api/admin/object-types#negativequantityerror">NegativeQuantityError</a> | <a href="/reference/graphql-api/admin/object-types#insufficientstockerror">InsufficientStockError</a> | <a href="/reference/graphql-api/admin/object-types#orderinterceptorerror">OrderInterceptorError</a></div>
</div>

## UpdatePromotionResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">UpdatePromotionResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/admin/object-types#promotion">Promotion</a> | <a href="/reference/graphql-api/admin/object-types#missingconditionserror">MissingConditionsError</a></div>
</div>

## Upload

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">The <code>Upload</code> scalar type represents a file upload.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">scalar <span class="graphql-code-identifier">Upload</span></div>
</div>

## User

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">User</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">identifier: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">verified: <a href="/reference/graphql-api/admin/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">roles: [<a href="/reference/graphql-api/admin/object-types#role">Role</a>!]!</div>

<div class="graphql-code-line ">lastLogin: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a></div>

<div class="graphql-code-line ">authenticationMethods: [<a href="/reference/graphql-api/admin/object-types#authenticationmethod">AuthenticationMethod</a>!]!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## Zone

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Zone</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/admin/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/admin/object-types#string">String</a>!</div>

<div class="graphql-code-line ">members: [<a href="/reference/graphql-api/admin/object-types#region">Region</a>!]!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ZoneList

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ZoneList</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/admin/object-types#zone">Zone</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>


---

---
title: "Queries"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';



## activeAdministrator
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">activeAdministrator: <a href="/reference/graphql-api/admin/object-types#administrator">Administrator</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## activeChannel
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">activeChannel: <a href="/reference/graphql-api/admin/object-types#channel">Channel</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## administrator
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">administrator(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#administrator">Administrator</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## administrators
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">administrators(options: <a href="/reference/graphql-api/admin/input-types#administratorlistoptions">AdministratorListOptions</a>): <a href="/reference/graphql-api/admin/object-types#administratorlist">AdministratorList</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## asset
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Get a single Asset by id</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">asset(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#asset">Asset</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## assets
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Get a list of Assets</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">assets(options: <a href="/reference/graphql-api/admin/input-types#assetlistoptions">AssetListOptions</a>): <a href="/reference/graphql-api/admin/object-types#assetlist">AssetList</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## channel
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">channel(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#channel">Channel</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## channels
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">channels(options: <a href="/reference/graphql-api/admin/input-types#channellistoptions">ChannelListOptions</a>): <a href="/reference/graphql-api/admin/object-types#channellist">ChannelList</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## collection
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Get a Collection either by id or slug. If neither id nor slug is specified, an error will result.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">collection(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>, slug: <a href="/reference/graphql-api/admin/object-types#string">String</a>): <a href="/reference/graphql-api/admin/object-types#collection">Collection</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## collectionFilters
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">collectionFilters: [<a href="/reference/graphql-api/admin/object-types#configurableoperationdefinition">ConfigurableOperationDefinition</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## collections
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">collections(options: <a href="/reference/graphql-api/admin/input-types#collectionlistoptions">CollectionListOptions</a>): <a href="/reference/graphql-api/admin/object-types#collectionlist">CollectionList</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## countries
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">countries(options: <a href="/reference/graphql-api/admin/input-types#countrylistoptions">CountryListOptions</a>): <a href="/reference/graphql-api/admin/object-types#countrylist">CountryList</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## country
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">country(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#country">Country</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## customer
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">customer(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#customer">Customer</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## customerGroup
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">customerGroup(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#customergroup">CustomerGroup</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## customerGroups
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">customerGroups(options: <a href="/reference/graphql-api/admin/input-types#customergrouplistoptions">CustomerGroupListOptions</a>): <a href="/reference/graphql-api/admin/object-types#customergrouplist">CustomerGroupList</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## customers
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">customers(options: <a href="/reference/graphql-api/admin/input-types#customerlistoptions">CustomerListOptions</a>): <a href="/reference/graphql-api/admin/object-types#customerlist">CustomerList</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## eligibleShippingMethodsForDraftOrder
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returns a list of eligible shipping methods for the draft Order</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">eligibleShippingMethodsForDraftOrder(orderId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): [<a href="/reference/graphql-api/admin/object-types#shippingmethodquote">ShippingMethodQuote</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## entityDuplicators
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returns all configured EntityDuplicators.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">entityDuplicators: [<a href="/reference/graphql-api/admin/object-types#entityduplicatordefinition">EntityDuplicatorDefinition</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## facet
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">facet(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#facet">Facet</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## facetValue
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">facetValue(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#facetvalue">FacetValue</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## facetValues
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">facetValues(options: <a href="/reference/graphql-api/admin/input-types#facetvaluelistoptions">FacetValueListOptions</a>): <a href="/reference/graphql-api/admin/object-types#facetvaluelist">FacetValueList</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## facets
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">facets(options: <a href="/reference/graphql-api/admin/input-types#facetlistoptions">FacetListOptions</a>): <a href="/reference/graphql-api/admin/object-types#facetlist">FacetList</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## fulfillmentHandlers
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">fulfillmentHandlers: [<a href="/reference/graphql-api/admin/object-types#configurableoperationdefinition">ConfigurableOperationDefinition</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## getSettingsStoreValue
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Get value for a specific key (automatically scoped based on field configuration)</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">getSettingsStoreValue(key: <a href="/reference/graphql-api/admin/object-types#string">String</a>!): <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## getSettingsStoreValues
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Get multiple key-value pairs (each automatically scoped)</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">getSettingsStoreValues(keys: [<a href="/reference/graphql-api/admin/object-types#string">String</a>!]!): <a href="/reference/graphql-api/admin/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## globalSettings
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">globalSettings: <a href="/reference/graphql-api/admin/object-types#globalsettings">GlobalSettings</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## job
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">job(jobId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#job">Job</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## jobBufferSize
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">jobBufferSize(bufferIds: [<a href="/reference/graphql-api/admin/object-types#string">String</a>!]): [<a href="/reference/graphql-api/admin/object-types#jobbuffersize">JobBufferSize</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## jobQueues
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">jobQueues: [<a href="/reference/graphql-api/admin/object-types#jobqueue">JobQueue</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## jobs
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">jobs(options: <a href="/reference/graphql-api/admin/input-types#joblistoptions">JobListOptions</a>): <a href="/reference/graphql-api/admin/object-types#joblist">JobList</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## jobsById
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">jobsById(jobIds: [<a href="/reference/graphql-api/admin/object-types#id">ID</a>!]!): [<a href="/reference/graphql-api/admin/object-types#job">Job</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## me
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">me: <a href="/reference/graphql-api/admin/object-types#currentuser">CurrentUser</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## metricSummary
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Get metrics for the given interval and metric types.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">metricSummary(input: <a href="/reference/graphql-api/admin/input-types#metricsummaryinput">MetricSummaryInput</a>): [<a href="/reference/graphql-api/admin/object-types#metricsummary">MetricSummary</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## order
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">order(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#order">Order</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## orders
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">orders(options: <a href="/reference/graphql-api/admin/input-types#orderlistoptions">OrderListOptions</a>): <a href="/reference/graphql-api/admin/object-types#orderlist">OrderList</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## paymentMethod
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">paymentMethod(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#paymentmethod">PaymentMethod</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## paymentMethodEligibilityCheckers
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">paymentMethodEligibilityCheckers: [<a href="/reference/graphql-api/admin/object-types#configurableoperationdefinition">ConfigurableOperationDefinition</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## paymentMethodHandlers
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">paymentMethodHandlers: [<a href="/reference/graphql-api/admin/object-types#configurableoperationdefinition">ConfigurableOperationDefinition</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## paymentMethods
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">paymentMethods(options: <a href="/reference/graphql-api/admin/input-types#paymentmethodlistoptions">PaymentMethodListOptions</a>): <a href="/reference/graphql-api/admin/object-types#paymentmethodlist">PaymentMethodList</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## pendingSearchIndexUpdates
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">pendingSearchIndexUpdates: <a href="/reference/graphql-api/admin/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## previewCollectionVariants
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Used for real-time previews of the contents of a Collection</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">previewCollectionVariants(input: <a href="/reference/graphql-api/admin/input-types#previewcollectionvariantsinput">PreviewCollectionVariantsInput</a>!, options: <a href="/reference/graphql-api/admin/input-types#productvariantlistoptions">ProductVariantListOptions</a>): <a href="/reference/graphql-api/admin/object-types#productvariantlist">ProductVariantList</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## product
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Get a Product either by id or slug. If neither id nor slug is specified, an error will result.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">product(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>, slug: <a href="/reference/graphql-api/admin/object-types#string">String</a>): <a href="/reference/graphql-api/admin/object-types#product">Product</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## productOptionGroup
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">productOptionGroup(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#productoptiongroup">ProductOptionGroup</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## productOptionGroups
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">productOptionGroups(filterTerm: <a href="/reference/graphql-api/admin/object-types#string">String</a>): [<a href="/reference/graphql-api/admin/object-types#productoptiongroup">ProductOptionGroup</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## productVariant
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Get a ProductVariant by id</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">productVariant(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#productvariant">ProductVariant</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## productVariants
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">List ProductVariants either all or for the specific product.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">productVariants(options: <a href="/reference/graphql-api/admin/input-types#productvariantlistoptions">ProductVariantListOptions</a>, productId: <a href="/reference/graphql-api/admin/object-types#id">ID</a>): <a href="/reference/graphql-api/admin/object-types#productvariantlist">ProductVariantList</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## products
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">List Products</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">products(options: <a href="/reference/graphql-api/admin/input-types#productlistoptions">ProductListOptions</a>): <a href="/reference/graphql-api/admin/object-types#productlist">ProductList</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## promotion
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">promotion(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#promotion">Promotion</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## promotionActions
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">promotionActions: [<a href="/reference/graphql-api/admin/object-types#configurableoperationdefinition">ConfigurableOperationDefinition</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## promotionConditions
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">promotionConditions: [<a href="/reference/graphql-api/admin/object-types#configurableoperationdefinition">ConfigurableOperationDefinition</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## promotions
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">promotions(options: <a href="/reference/graphql-api/admin/input-types#promotionlistoptions">PromotionListOptions</a>): <a href="/reference/graphql-api/admin/object-types#promotionlist">PromotionList</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## province
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">province(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#province">Province</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## provinces
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">provinces(options: <a href="/reference/graphql-api/admin/input-types#provincelistoptions">ProvinceListOptions</a>): <a href="/reference/graphql-api/admin/object-types#provincelist">ProvinceList</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## role
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">role(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#role">Role</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## roles
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">roles(options: <a href="/reference/graphql-api/admin/input-types#rolelistoptions">RoleListOptions</a>): <a href="/reference/graphql-api/admin/object-types#rolelist">RoleList</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## scheduledTasks
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">scheduledTasks: [<a href="/reference/graphql-api/admin/object-types#scheduledtask">ScheduledTask</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## search
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">search(input: <a href="/reference/graphql-api/admin/input-types#searchinput">SearchInput</a>!): <a href="/reference/graphql-api/admin/object-types#searchresponse">SearchResponse</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## seller
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">seller(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#seller">Seller</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## sellers
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">sellers(options: <a href="/reference/graphql-api/admin/input-types#sellerlistoptions">SellerListOptions</a>): <a href="/reference/graphql-api/admin/object-types#sellerlist">SellerList</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## shippingCalculators
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">shippingCalculators: [<a href="/reference/graphql-api/admin/object-types#configurableoperationdefinition">ConfigurableOperationDefinition</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## shippingEligibilityCheckers
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">shippingEligibilityCheckers: [<a href="/reference/graphql-api/admin/object-types#configurableoperationdefinition">ConfigurableOperationDefinition</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## shippingMethod
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">shippingMethod(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#shippingmethod">ShippingMethod</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## shippingMethods
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">shippingMethods(options: <a href="/reference/graphql-api/admin/input-types#shippingmethodlistoptions">ShippingMethodListOptions</a>): <a href="/reference/graphql-api/admin/object-types#shippingmethodlist">ShippingMethodList</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## stockLocation
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">stockLocation(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#stocklocation">StockLocation</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## stockLocations
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">stockLocations(options: <a href="/reference/graphql-api/admin/input-types#stocklocationlistoptions">StockLocationListOptions</a>): <a href="/reference/graphql-api/admin/object-types#stocklocationlist">StockLocationList</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## tag
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">tag(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#tag">Tag</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## tags
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">tags(options: <a href="/reference/graphql-api/admin/input-types#taglistoptions">TagListOptions</a>): <a href="/reference/graphql-api/admin/object-types#taglist">TagList</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## taxCategories
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">taxCategories(options: <a href="/reference/graphql-api/admin/input-types#taxcategorylistoptions">TaxCategoryListOptions</a>): <a href="/reference/graphql-api/admin/object-types#taxcategorylist">TaxCategoryList</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## taxCategory
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">taxCategory(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#taxcategory">TaxCategory</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## taxRate
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">taxRate(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#taxrate">TaxRate</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## taxRates
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">taxRates(options: <a href="/reference/graphql-api/admin/input-types#taxratelistoptions">TaxRateListOptions</a>): <a href="/reference/graphql-api/admin/object-types#taxratelist">TaxRateList</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## testEligibleShippingMethods
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">testEligibleShippingMethods(input: <a href="/reference/graphql-api/admin/input-types#testeligibleshippingmethodsinput">TestEligibleShippingMethodsInput</a>!): [<a href="/reference/graphql-api/admin/object-types#shippingmethodquote">ShippingMethodQuote</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## testShippingMethod
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">testShippingMethod(input: <a href="/reference/graphql-api/admin/input-types#testshippingmethodinput">TestShippingMethodInput</a>!): <a href="/reference/graphql-api/admin/object-types#testshippingmethodresult">TestShippingMethodResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## zone
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">zone(id: <a href="/reference/graphql-api/admin/object-types#id">ID</a>!): <a href="/reference/graphql-api/admin/object-types#zone">Zone</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## zones
<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">zones(options: <a href="/reference/graphql-api/admin/input-types#zonelistoptions">ZoneListOptions</a>): <a href="/reference/graphql-api/admin/object-types#zonelist">ZoneList</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>


---

---
title: "Shop API"
weight: 3
showtoc: false
---

# GraphQL Shop API

The Shop API is used by storefront applications. It provides all the necessary queries and mutations for finding and viewing products, creating and updating orders, checking out, managing a customer account etc.

:::note
Explore the interactive GraphQL Shop API at [demo.vendure.io/shop-api](https://demo.vendure.io/shop-api)
:::


---

---
title: "Enums"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';



## AdjustmentType

<div class="graphql-code-block">

<div class="graphql-code-line top-level">enum <span class="graphql-code-identifier">AdjustmentType</span> &#123;</div>
<div class="graphql-code-line ">PROMOTION</div>
<div class="graphql-code-line ">DISTRIBUTED_ORDER_PROMOTION</div>
<div class="graphql-code-line ">OTHER</div>
<div class="graphql-code-line top-level">&#125;</div>
</div>

## AssetType

<div class="graphql-code-block">

<div class="graphql-code-line top-level">enum <span class="graphql-code-identifier">AssetType</span> &#123;</div>
<div class="graphql-code-line ">IMAGE</div>
<div class="graphql-code-line ">VIDEO</div>
<div class="graphql-code-line ">BINARY</div>
<div class="graphql-code-line top-level">&#125;</div>
</div>

## CurrencyCode

<div class="graphql-code-block">
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">ISO 4217 currency code</div>

<div class="graphql-code-line comment"></div>

<div class="graphql-code-line comment"></div>
<div class="graphql-code-line comment">"""</div>

<div class="graphql-code-line top-level">enum <span class="graphql-code-identifier">CurrencyCode</span> &#123;</div>
<div class="graphql-code-line comment">"""United Arab Emirates dirham"""</div>
<div class="graphql-code-line ">AED</div>
<div class="graphql-code-line comment">"""Afghan afghani"""</div>
<div class="graphql-code-line ">AFN</div>
<div class="graphql-code-line comment">"""Albanian lek"""</div>
<div class="graphql-code-line ">ALL</div>
<div class="graphql-code-line comment">"""Armenian dram"""</div>
<div class="graphql-code-line ">AMD</div>
<div class="graphql-code-line comment">"""Netherlands Antillean guilder"""</div>
<div class="graphql-code-line ">ANG</div>
<div class="graphql-code-line comment">"""Angolan kwanza"""</div>
<div class="graphql-code-line ">AOA</div>
<div class="graphql-code-line comment">"""Argentine peso"""</div>
<div class="graphql-code-line ">ARS</div>
<div class="graphql-code-line comment">"""Australian dollar"""</div>
<div class="graphql-code-line ">AUD</div>
<div class="graphql-code-line comment">"""Aruban florin"""</div>
<div class="graphql-code-line ">AWG</div>
<div class="graphql-code-line comment">"""Azerbaijani manat"""</div>
<div class="graphql-code-line ">AZN</div>
<div class="graphql-code-line comment">"""Bosnia and Herzegovina convertible mark"""</div>
<div class="graphql-code-line ">BAM</div>
<div class="graphql-code-line comment">"""Barbados dollar"""</div>
<div class="graphql-code-line ">BBD</div>
<div class="graphql-code-line comment">"""Bangladeshi taka"""</div>
<div class="graphql-code-line ">BDT</div>
<div class="graphql-code-line comment">"""Bulgarian lev"""</div>
<div class="graphql-code-line ">BGN</div>
<div class="graphql-code-line comment">"""Bahraini dinar"""</div>
<div class="graphql-code-line ">BHD</div>
<div class="graphql-code-line comment">"""Burundian franc"""</div>
<div class="graphql-code-line ">BIF</div>
<div class="graphql-code-line comment">"""Bermudian dollar"""</div>
<div class="graphql-code-line ">BMD</div>
<div class="graphql-code-line comment">"""Brunei dollar"""</div>
<div class="graphql-code-line ">BND</div>
<div class="graphql-code-line comment">"""Boliviano"""</div>
<div class="graphql-code-line ">BOB</div>
<div class="graphql-code-line comment">"""Brazilian real"""</div>
<div class="graphql-code-line ">BRL</div>
<div class="graphql-code-line comment">"""Bahamian dollar"""</div>
<div class="graphql-code-line ">BSD</div>
<div class="graphql-code-line comment">"""Bhutanese ngultrum"""</div>
<div class="graphql-code-line ">BTN</div>
<div class="graphql-code-line comment">"""Botswana pula"""</div>
<div class="graphql-code-line ">BWP</div>
<div class="graphql-code-line comment">"""Belarusian ruble"""</div>
<div class="graphql-code-line ">BYN</div>
<div class="graphql-code-line comment">"""Belize dollar"""</div>
<div class="graphql-code-line ">BZD</div>
<div class="graphql-code-line comment">"""Canadian dollar"""</div>
<div class="graphql-code-line ">CAD</div>
<div class="graphql-code-line comment">"""Congolese franc"""</div>
<div class="graphql-code-line ">CDF</div>
<div class="graphql-code-line comment">"""Swiss franc"""</div>
<div class="graphql-code-line ">CHF</div>
<div class="graphql-code-line comment">"""Chilean peso"""</div>
<div class="graphql-code-line ">CLP</div>
<div class="graphql-code-line comment">"""Renminbi (Chinese) yuan"""</div>
<div class="graphql-code-line ">CNY</div>
<div class="graphql-code-line comment">"""Colombian peso"""</div>
<div class="graphql-code-line ">COP</div>
<div class="graphql-code-line comment">"""Costa Rican colon"""</div>
<div class="graphql-code-line ">CRC</div>
<div class="graphql-code-line comment">"""Cuban convertible peso"""</div>
<div class="graphql-code-line ">CUC</div>
<div class="graphql-code-line comment">"""Cuban peso"""</div>
<div class="graphql-code-line ">CUP</div>
<div class="graphql-code-line comment">"""Cape Verde escudo"""</div>
<div class="graphql-code-line ">CVE</div>
<div class="graphql-code-line comment">"""Czech koruna"""</div>
<div class="graphql-code-line ">CZK</div>
<div class="graphql-code-line comment">"""Djiboutian franc"""</div>
<div class="graphql-code-line ">DJF</div>
<div class="graphql-code-line comment">"""Danish krone"""</div>
<div class="graphql-code-line ">DKK</div>
<div class="graphql-code-line comment">"""Dominican peso"""</div>
<div class="graphql-code-line ">DOP</div>
<div class="graphql-code-line comment">"""Algerian dinar"""</div>
<div class="graphql-code-line ">DZD</div>
<div class="graphql-code-line comment">"""Egyptian pound"""</div>
<div class="graphql-code-line ">EGP</div>
<div class="graphql-code-line comment">"""Eritrean nakfa"""</div>
<div class="graphql-code-line ">ERN</div>
<div class="graphql-code-line comment">"""Ethiopian birr"""</div>
<div class="graphql-code-line ">ETB</div>
<div class="graphql-code-line comment">"""Euro"""</div>
<div class="graphql-code-line ">EUR</div>
<div class="graphql-code-line comment">"""Fiji dollar"""</div>
<div class="graphql-code-line ">FJD</div>
<div class="graphql-code-line comment">"""Falkland Islands pound"""</div>
<div class="graphql-code-line ">FKP</div>
<div class="graphql-code-line comment">"""Pound sterling"""</div>
<div class="graphql-code-line ">GBP</div>
<div class="graphql-code-line comment">"""Georgian lari"""</div>
<div class="graphql-code-line ">GEL</div>
<div class="graphql-code-line comment">"""Ghanaian cedi"""</div>
<div class="graphql-code-line ">GHS</div>
<div class="graphql-code-line comment">"""Gibraltar pound"""</div>
<div class="graphql-code-line ">GIP</div>
<div class="graphql-code-line comment">"""Gambian dalasi"""</div>
<div class="graphql-code-line ">GMD</div>
<div class="graphql-code-line comment">"""Guinean franc"""</div>
<div class="graphql-code-line ">GNF</div>
<div class="graphql-code-line comment">"""Guatemalan quetzal"""</div>
<div class="graphql-code-line ">GTQ</div>
<div class="graphql-code-line comment">"""Guyanese dollar"""</div>
<div class="graphql-code-line ">GYD</div>
<div class="graphql-code-line comment">"""Hong Kong dollar"""</div>
<div class="graphql-code-line ">HKD</div>
<div class="graphql-code-line comment">"""Honduran lempira"""</div>
<div class="graphql-code-line ">HNL</div>
<div class="graphql-code-line comment">"""Croatian kuna"""</div>
<div class="graphql-code-line ">HRK</div>
<div class="graphql-code-line comment">"""Haitian gourde"""</div>
<div class="graphql-code-line ">HTG</div>
<div class="graphql-code-line comment">"""Hungarian forint"""</div>
<div class="graphql-code-line ">HUF</div>
<div class="graphql-code-line comment">"""Indonesian rupiah"""</div>
<div class="graphql-code-line ">IDR</div>
<div class="graphql-code-line comment">"""Israeli new shekel"""</div>
<div class="graphql-code-line ">ILS</div>
<div class="graphql-code-line comment">"""Indian rupee"""</div>
<div class="graphql-code-line ">INR</div>
<div class="graphql-code-line comment">"""Iraqi dinar"""</div>
<div class="graphql-code-line ">IQD</div>
<div class="graphql-code-line comment">"""Iranian rial"""</div>
<div class="graphql-code-line ">IRR</div>
<div class="graphql-code-line comment">"""Icelandic króna"""</div>
<div class="graphql-code-line ">ISK</div>
<div class="graphql-code-line comment">"""Jamaican dollar"""</div>
<div class="graphql-code-line ">JMD</div>
<div class="graphql-code-line comment">"""Jordanian dinar"""</div>
<div class="graphql-code-line ">JOD</div>
<div class="graphql-code-line comment">"""Japanese yen"""</div>
<div class="graphql-code-line ">JPY</div>
<div class="graphql-code-line comment">"""Kenyan shilling"""</div>
<div class="graphql-code-line ">KES</div>
<div class="graphql-code-line comment">"""Kyrgyzstani som"""</div>
<div class="graphql-code-line ">KGS</div>
<div class="graphql-code-line comment">"""Cambodian riel"""</div>
<div class="graphql-code-line ">KHR</div>
<div class="graphql-code-line comment">"""Comoro franc"""</div>
<div class="graphql-code-line ">KMF</div>
<div class="graphql-code-line comment">"""North Korean won"""</div>
<div class="graphql-code-line ">KPW</div>
<div class="graphql-code-line comment">"""South Korean won"""</div>
<div class="graphql-code-line ">KRW</div>
<div class="graphql-code-line comment">"""Kuwaiti dinar"""</div>
<div class="graphql-code-line ">KWD</div>
<div class="graphql-code-line comment">"""Cayman Islands dollar"""</div>
<div class="graphql-code-line ">KYD</div>
<div class="graphql-code-line comment">"""Kazakhstani tenge"""</div>
<div class="graphql-code-line ">KZT</div>
<div class="graphql-code-line comment">"""Lao kip"""</div>
<div class="graphql-code-line ">LAK</div>
<div class="graphql-code-line comment">"""Lebanese pound"""</div>
<div class="graphql-code-line ">LBP</div>
<div class="graphql-code-line comment">"""Sri Lankan rupee"""</div>
<div class="graphql-code-line ">LKR</div>
<div class="graphql-code-line comment">"""Liberian dollar"""</div>
<div class="graphql-code-line ">LRD</div>
<div class="graphql-code-line comment">"""Lesotho loti"""</div>
<div class="graphql-code-line ">LSL</div>
<div class="graphql-code-line comment">"""Libyan dinar"""</div>
<div class="graphql-code-line ">LYD</div>
<div class="graphql-code-line comment">"""Moroccan dirham"""</div>
<div class="graphql-code-line ">MAD</div>
<div class="graphql-code-line comment">"""Moldovan leu"""</div>
<div class="graphql-code-line ">MDL</div>
<div class="graphql-code-line comment">"""Malagasy ariary"""</div>
<div class="graphql-code-line ">MGA</div>
<div class="graphql-code-line comment">"""Macedonian denar"""</div>
<div class="graphql-code-line ">MKD</div>
<div class="graphql-code-line comment">"""Myanmar kyat"""</div>
<div class="graphql-code-line ">MMK</div>
<div class="graphql-code-line comment">"""Mongolian tögrög"""</div>
<div class="graphql-code-line ">MNT</div>
<div class="graphql-code-line comment">"""Macanese pataca"""</div>
<div class="graphql-code-line ">MOP</div>
<div class="graphql-code-line comment">"""Mauritanian ouguiya"""</div>
<div class="graphql-code-line ">MRU</div>
<div class="graphql-code-line comment">"""Mauritian rupee"""</div>
<div class="graphql-code-line ">MUR</div>
<div class="graphql-code-line comment">"""Maldivian rufiyaa"""</div>
<div class="graphql-code-line ">MVR</div>
<div class="graphql-code-line comment">"""Malawian kwacha"""</div>
<div class="graphql-code-line ">MWK</div>
<div class="graphql-code-line comment">"""Mexican peso"""</div>
<div class="graphql-code-line ">MXN</div>
<div class="graphql-code-line comment">"""Malaysian ringgit"""</div>
<div class="graphql-code-line ">MYR</div>
<div class="graphql-code-line comment">"""Mozambican metical"""</div>
<div class="graphql-code-line ">MZN</div>
<div class="graphql-code-line comment">"""Namibian dollar"""</div>
<div class="graphql-code-line ">NAD</div>
<div class="graphql-code-line comment">"""Nigerian naira"""</div>
<div class="graphql-code-line ">NGN</div>
<div class="graphql-code-line comment">"""Nicaraguan córdoba"""</div>
<div class="graphql-code-line ">NIO</div>
<div class="graphql-code-line comment">"""Norwegian krone"""</div>
<div class="graphql-code-line ">NOK</div>
<div class="graphql-code-line comment">"""Nepalese rupee"""</div>
<div class="graphql-code-line ">NPR</div>
<div class="graphql-code-line comment">"""New Zealand dollar"""</div>
<div class="graphql-code-line ">NZD</div>
<div class="graphql-code-line comment">"""Omani rial"""</div>
<div class="graphql-code-line ">OMR</div>
<div class="graphql-code-line comment">"""Panamanian balboa"""</div>
<div class="graphql-code-line ">PAB</div>
<div class="graphql-code-line comment">"""Peruvian sol"""</div>
<div class="graphql-code-line ">PEN</div>
<div class="graphql-code-line comment">"""Papua New Guinean kina"""</div>
<div class="graphql-code-line ">PGK</div>
<div class="graphql-code-line comment">"""Philippine peso"""</div>
<div class="graphql-code-line ">PHP</div>
<div class="graphql-code-line comment">"""Pakistani rupee"""</div>
<div class="graphql-code-line ">PKR</div>
<div class="graphql-code-line comment">"""Polish złoty"""</div>
<div class="graphql-code-line ">PLN</div>
<div class="graphql-code-line comment">"""Paraguayan guaraní"""</div>
<div class="graphql-code-line ">PYG</div>
<div class="graphql-code-line comment">"""Qatari riyal"""</div>
<div class="graphql-code-line ">QAR</div>
<div class="graphql-code-line comment">"""Romanian leu"""</div>
<div class="graphql-code-line ">RON</div>
<div class="graphql-code-line comment">"""Serbian dinar"""</div>
<div class="graphql-code-line ">RSD</div>
<div class="graphql-code-line comment">"""Russian ruble"""</div>
<div class="graphql-code-line ">RUB</div>
<div class="graphql-code-line comment">"""Rwandan franc"""</div>
<div class="graphql-code-line ">RWF</div>
<div class="graphql-code-line comment">"""Saudi riyal"""</div>
<div class="graphql-code-line ">SAR</div>
<div class="graphql-code-line comment">"""Solomon Islands dollar"""</div>
<div class="graphql-code-line ">SBD</div>
<div class="graphql-code-line comment">"""Seychelles rupee"""</div>
<div class="graphql-code-line ">SCR</div>
<div class="graphql-code-line comment">"""Sudanese pound"""</div>
<div class="graphql-code-line ">SDG</div>
<div class="graphql-code-line comment">"""Swedish krona/kronor"""</div>
<div class="graphql-code-line ">SEK</div>
<div class="graphql-code-line comment">"""Singapore dollar"""</div>
<div class="graphql-code-line ">SGD</div>
<div class="graphql-code-line comment">"""Saint Helena pound"""</div>
<div class="graphql-code-line ">SHP</div>
<div class="graphql-code-line comment">"""Sierra Leonean leone"""</div>
<div class="graphql-code-line ">SLL</div>
<div class="graphql-code-line comment">"""Somali shilling"""</div>
<div class="graphql-code-line ">SOS</div>
<div class="graphql-code-line comment">"""Surinamese dollar"""</div>
<div class="graphql-code-line ">SRD</div>
<div class="graphql-code-line comment">"""South Sudanese pound"""</div>
<div class="graphql-code-line ">SSP</div>
<div class="graphql-code-line comment">"""São Tomé and Príncipe dobra"""</div>
<div class="graphql-code-line ">STN</div>
<div class="graphql-code-line comment">"""Salvadoran colón"""</div>
<div class="graphql-code-line ">SVC</div>
<div class="graphql-code-line comment">"""Syrian pound"""</div>
<div class="graphql-code-line ">SYP</div>
<div class="graphql-code-line comment">"""Swazi lilangeni"""</div>
<div class="graphql-code-line ">SZL</div>
<div class="graphql-code-line comment">"""Thai baht"""</div>
<div class="graphql-code-line ">THB</div>
<div class="graphql-code-line comment">"""Tajikistani somoni"""</div>
<div class="graphql-code-line ">TJS</div>
<div class="graphql-code-line comment">"""Turkmenistan manat"""</div>
<div class="graphql-code-line ">TMT</div>
<div class="graphql-code-line comment">"""Tunisian dinar"""</div>
<div class="graphql-code-line ">TND</div>
<div class="graphql-code-line comment">"""Tongan paʻanga"""</div>
<div class="graphql-code-line ">TOP</div>
<div class="graphql-code-line comment">"""Turkish lira"""</div>
<div class="graphql-code-line ">TRY</div>
<div class="graphql-code-line comment">"""Trinidad and Tobago dollar"""</div>
<div class="graphql-code-line ">TTD</div>
<div class="graphql-code-line comment">"""New Taiwan dollar"""</div>
<div class="graphql-code-line ">TWD</div>
<div class="graphql-code-line comment">"""Tanzanian shilling"""</div>
<div class="graphql-code-line ">TZS</div>
<div class="graphql-code-line comment">"""Ukrainian hryvnia"""</div>
<div class="graphql-code-line ">UAH</div>
<div class="graphql-code-line comment">"""Ugandan shilling"""</div>
<div class="graphql-code-line ">UGX</div>
<div class="graphql-code-line comment">"""United States dollar"""</div>
<div class="graphql-code-line ">USD</div>
<div class="graphql-code-line comment">"""Uruguayan peso"""</div>
<div class="graphql-code-line ">UYU</div>
<div class="graphql-code-line comment">"""Uzbekistan som"""</div>
<div class="graphql-code-line ">UZS</div>
<div class="graphql-code-line comment">"""Venezuelan bolívar soberano"""</div>
<div class="graphql-code-line ">VES</div>
<div class="graphql-code-line comment">"""Vietnamese đồng"""</div>
<div class="graphql-code-line ">VND</div>
<div class="graphql-code-line comment">"""Vanuatu vatu"""</div>
<div class="graphql-code-line ">VUV</div>
<div class="graphql-code-line comment">"""Samoan tala"""</div>
<div class="graphql-code-line ">WST</div>
<div class="graphql-code-line comment">"""CFA franc BEAC"""</div>
<div class="graphql-code-line ">XAF</div>
<div class="graphql-code-line comment">"""East Caribbean dollar"""</div>
<div class="graphql-code-line ">XCD</div>
<div class="graphql-code-line comment">"""CFA franc BCEAO"""</div>
<div class="graphql-code-line ">XOF</div>
<div class="graphql-code-line comment">"""CFP franc (franc Pacifique)"""</div>
<div class="graphql-code-line ">XPF</div>
<div class="graphql-code-line comment">"""Yemeni rial"""</div>
<div class="graphql-code-line ">YER</div>
<div class="graphql-code-line comment">"""South African rand"""</div>
<div class="graphql-code-line ">ZAR</div>
<div class="graphql-code-line comment">"""Zambian kwacha"""</div>
<div class="graphql-code-line ">ZMW</div>
<div class="graphql-code-line comment">"""Zimbabwean dollar"""</div>
<div class="graphql-code-line ">ZWL</div>
<div class="graphql-code-line top-level">&#125;</div>
</div>

## DeletionResult

<div class="graphql-code-block">

<div class="graphql-code-line top-level">enum <span class="graphql-code-identifier">DeletionResult</span> &#123;</div>
<div class="graphql-code-line comment">"""The entity was successfully deleted"""</div>
<div class="graphql-code-line ">DELETED</div>
<div class="graphql-code-line comment">"""Deletion did not take place, reason given in message"""</div>
<div class="graphql-code-line ">NOT_DELETED</div>
<div class="graphql-code-line top-level">&#125;</div>
</div>

## ErrorCode

<div class="graphql-code-block">

<div class="graphql-code-line top-level">enum <span class="graphql-code-identifier">ErrorCode</span> &#123;</div>
<div class="graphql-code-line ">UNKNOWN_ERROR</div>
<div class="graphql-code-line ">NATIVE_AUTH_STRATEGY_ERROR</div>
<div class="graphql-code-line ">INVALID_CREDENTIALS_ERROR</div>
<div class="graphql-code-line ">ORDER_STATE_TRANSITION_ERROR</div>
<div class="graphql-code-line ">EMAIL_ADDRESS_CONFLICT_ERROR</div>
<div class="graphql-code-line ">GUEST_CHECKOUT_ERROR</div>
<div class="graphql-code-line ">ORDER_LIMIT_ERROR</div>
<div class="graphql-code-line ">NEGATIVE_QUANTITY_ERROR</div>
<div class="graphql-code-line ">INSUFFICIENT_STOCK_ERROR</div>
<div class="graphql-code-line ">COUPON_CODE_INVALID_ERROR</div>
<div class="graphql-code-line ">COUPON_CODE_EXPIRED_ERROR</div>
<div class="graphql-code-line ">COUPON_CODE_LIMIT_ERROR</div>
<div class="graphql-code-line ">ORDER_MODIFICATION_ERROR</div>
<div class="graphql-code-line ">INELIGIBLE_SHIPPING_METHOD_ERROR</div>
<div class="graphql-code-line ">NO_ACTIVE_ORDER_ERROR</div>
<div class="graphql-code-line ">ORDER_INTERCEPTOR_ERROR</div>
<div class="graphql-code-line ">ORDER_PAYMENT_STATE_ERROR</div>
<div class="graphql-code-line ">INELIGIBLE_PAYMENT_METHOD_ERROR</div>
<div class="graphql-code-line ">PAYMENT_FAILED_ERROR</div>
<div class="graphql-code-line ">PAYMENT_DECLINED_ERROR</div>
<div class="graphql-code-line ">ALREADY_LOGGED_IN_ERROR</div>
<div class="graphql-code-line ">MISSING_PASSWORD_ERROR</div>
<div class="graphql-code-line ">PASSWORD_VALIDATION_ERROR</div>
<div class="graphql-code-line ">PASSWORD_ALREADY_SET_ERROR</div>
<div class="graphql-code-line ">VERIFICATION_TOKEN_INVALID_ERROR</div>
<div class="graphql-code-line ">VERIFICATION_TOKEN_EXPIRED_ERROR</div>
<div class="graphql-code-line ">IDENTIFIER_CHANGE_TOKEN_INVALID_ERROR</div>
<div class="graphql-code-line ">IDENTIFIER_CHANGE_TOKEN_EXPIRED_ERROR</div>
<div class="graphql-code-line ">PASSWORD_RESET_TOKEN_INVALID_ERROR</div>
<div class="graphql-code-line ">PASSWORD_RESET_TOKEN_EXPIRED_ERROR</div>
<div class="graphql-code-line ">NOT_VERIFIED_ERROR</div>
<div class="graphql-code-line top-level">&#125;</div>
</div>

## GlobalFlag

<div class="graphql-code-block">

<div class="graphql-code-line top-level">enum <span class="graphql-code-identifier">GlobalFlag</span> &#123;</div>
<div class="graphql-code-line ">TRUE</div>
<div class="graphql-code-line ">FALSE</div>
<div class="graphql-code-line ">INHERIT</div>
<div class="graphql-code-line top-level">&#125;</div>
</div>

## HistoryEntryType

<div class="graphql-code-block">

<div class="graphql-code-line top-level">enum <span class="graphql-code-identifier">HistoryEntryType</span> &#123;</div>
<div class="graphql-code-line ">CUSTOMER_REGISTERED</div>
<div class="graphql-code-line ">CUSTOMER_VERIFIED</div>
<div class="graphql-code-line ">CUSTOMER_DETAIL_UPDATED</div>
<div class="graphql-code-line ">CUSTOMER_ADDED_TO_GROUP</div>
<div class="graphql-code-line ">CUSTOMER_REMOVED_FROM_GROUP</div>
<div class="graphql-code-line ">CUSTOMER_ADDRESS_CREATED</div>
<div class="graphql-code-line ">CUSTOMER_ADDRESS_UPDATED</div>
<div class="graphql-code-line ">CUSTOMER_ADDRESS_DELETED</div>
<div class="graphql-code-line ">CUSTOMER_PASSWORD_UPDATED</div>
<div class="graphql-code-line ">CUSTOMER_PASSWORD_RESET_REQUESTED</div>
<div class="graphql-code-line ">CUSTOMER_PASSWORD_RESET_VERIFIED</div>
<div class="graphql-code-line ">CUSTOMER_EMAIL_UPDATE_REQUESTED</div>
<div class="graphql-code-line ">CUSTOMER_EMAIL_UPDATE_VERIFIED</div>
<div class="graphql-code-line ">CUSTOMER_NOTE</div>
<div class="graphql-code-line ">ORDER_STATE_TRANSITION</div>
<div class="graphql-code-line ">ORDER_PAYMENT_TRANSITION</div>
<div class="graphql-code-line ">ORDER_FULFILLMENT</div>
<div class="graphql-code-line ">ORDER_CANCELLATION</div>
<div class="graphql-code-line ">ORDER_REFUND_TRANSITION</div>
<div class="graphql-code-line ">ORDER_FULFILLMENT_TRANSITION</div>
<div class="graphql-code-line ">ORDER_NOTE</div>
<div class="graphql-code-line ">ORDER_COUPON_APPLIED</div>
<div class="graphql-code-line ">ORDER_COUPON_REMOVED</div>
<div class="graphql-code-line ">ORDER_MODIFIED</div>
<div class="graphql-code-line ">ORDER_CUSTOMER_UPDATED</div>
<div class="graphql-code-line top-level">&#125;</div>
</div>

## LanguageCode

<div class="graphql-code-block">
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Languages in the form of a ISO 639-1 language code with optional</div>

<div class="graphql-code-line comment">region or script modifier (e.g. de_AT). The selection available is based</div>

<div class="graphql-code-line comment">on the [Unicode CLDR summary list](https://unicode-org.github.io/cldr-staging/charts/37/summary/root.html)</div>

<div class="graphql-code-line comment">and includes the major spoken languages of the world and any widely-used variants.</div>

<div class="graphql-code-line comment"></div>

<div class="graphql-code-line comment"></div>
<div class="graphql-code-line comment">"""</div>

<div class="graphql-code-line top-level">enum <span class="graphql-code-identifier">LanguageCode</span> &#123;</div>
<div class="graphql-code-line comment">"""Afrikaans"""</div>
<div class="graphql-code-line ">af</div>
<div class="graphql-code-line comment">"""Akan"""</div>
<div class="graphql-code-line ">ak</div>
<div class="graphql-code-line comment">"""Albanian"""</div>
<div class="graphql-code-line ">sq</div>
<div class="graphql-code-line comment">"""Amharic"""</div>
<div class="graphql-code-line ">am</div>
<div class="graphql-code-line comment">"""Arabic"""</div>
<div class="graphql-code-line ">ar</div>
<div class="graphql-code-line comment">"""Armenian"""</div>
<div class="graphql-code-line ">hy</div>
<div class="graphql-code-line comment">"""Assamese"""</div>
<div class="graphql-code-line ">as</div>
<div class="graphql-code-line comment">"""Azerbaijani"""</div>
<div class="graphql-code-line ">az</div>
<div class="graphql-code-line comment">"""Bambara"""</div>
<div class="graphql-code-line ">bm</div>
<div class="graphql-code-line comment">"""Bangla"""</div>
<div class="graphql-code-line ">bn</div>
<div class="graphql-code-line comment">"""Basque"""</div>
<div class="graphql-code-line ">eu</div>
<div class="graphql-code-line comment">"""Belarusian"""</div>
<div class="graphql-code-line ">be</div>
<div class="graphql-code-line comment">"""Bosnian"""</div>
<div class="graphql-code-line ">bs</div>
<div class="graphql-code-line comment">"""Breton"""</div>
<div class="graphql-code-line ">br</div>
<div class="graphql-code-line comment">"""Bulgarian"""</div>
<div class="graphql-code-line ">bg</div>
<div class="graphql-code-line comment">"""Burmese"""</div>
<div class="graphql-code-line ">my</div>
<div class="graphql-code-line comment">"""Catalan"""</div>
<div class="graphql-code-line ">ca</div>
<div class="graphql-code-line comment">"""Chechen"""</div>
<div class="graphql-code-line ">ce</div>
<div class="graphql-code-line comment">"""Chinese"""</div>
<div class="graphql-code-line ">zh</div>
<div class="graphql-code-line comment">"""Simplified Chinese"""</div>
<div class="graphql-code-line ">zh_Hans</div>
<div class="graphql-code-line comment">"""Traditional Chinese"""</div>
<div class="graphql-code-line ">zh_Hant</div>
<div class="graphql-code-line comment">"""Church Slavic"""</div>
<div class="graphql-code-line ">cu</div>
<div class="graphql-code-line comment">"""Cornish"""</div>
<div class="graphql-code-line ">kw</div>
<div class="graphql-code-line comment">"""Corsican"""</div>
<div class="graphql-code-line ">co</div>
<div class="graphql-code-line comment">"""Croatian"""</div>
<div class="graphql-code-line ">hr</div>
<div class="graphql-code-line comment">"""Czech"""</div>
<div class="graphql-code-line ">cs</div>
<div class="graphql-code-line comment">"""Danish"""</div>
<div class="graphql-code-line ">da</div>
<div class="graphql-code-line comment">"""Dutch"""</div>
<div class="graphql-code-line ">nl</div>
<div class="graphql-code-line comment">"""Flemish"""</div>
<div class="graphql-code-line ">nl_BE</div>
<div class="graphql-code-line comment">"""Dzongkha"""</div>
<div class="graphql-code-line ">dz</div>
<div class="graphql-code-line comment">"""English"""</div>
<div class="graphql-code-line ">en</div>
<div class="graphql-code-line comment">"""Australian English"""</div>
<div class="graphql-code-line ">en_AU</div>
<div class="graphql-code-line comment">"""Canadian English"""</div>
<div class="graphql-code-line ">en_CA</div>
<div class="graphql-code-line comment">"""British English"""</div>
<div class="graphql-code-line ">en_GB</div>
<div class="graphql-code-line comment">"""American English"""</div>
<div class="graphql-code-line ">en_US</div>
<div class="graphql-code-line comment">"""Esperanto"""</div>
<div class="graphql-code-line ">eo</div>
<div class="graphql-code-line comment">"""Estonian"""</div>
<div class="graphql-code-line ">et</div>
<div class="graphql-code-line comment">"""Ewe"""</div>
<div class="graphql-code-line ">ee</div>
<div class="graphql-code-line comment">"""Faroese"""</div>
<div class="graphql-code-line ">fo</div>
<div class="graphql-code-line comment">"""Finnish"""</div>
<div class="graphql-code-line ">fi</div>
<div class="graphql-code-line comment">"""French"""</div>
<div class="graphql-code-line ">fr</div>
<div class="graphql-code-line comment">"""Canadian French"""</div>
<div class="graphql-code-line ">fr_CA</div>
<div class="graphql-code-line comment">"""Swiss French"""</div>
<div class="graphql-code-line ">fr_CH</div>
<div class="graphql-code-line comment">"""Fulah"""</div>
<div class="graphql-code-line ">ff</div>
<div class="graphql-code-line comment">"""Galician"""</div>
<div class="graphql-code-line ">gl</div>
<div class="graphql-code-line comment">"""Ganda"""</div>
<div class="graphql-code-line ">lg</div>
<div class="graphql-code-line comment">"""Georgian"""</div>
<div class="graphql-code-line ">ka</div>
<div class="graphql-code-line comment">"""German"""</div>
<div class="graphql-code-line ">de</div>
<div class="graphql-code-line comment">"""Austrian German"""</div>
<div class="graphql-code-line ">de_AT</div>
<div class="graphql-code-line comment">"""Swiss High German"""</div>
<div class="graphql-code-line ">de_CH</div>
<div class="graphql-code-line comment">"""Greek"""</div>
<div class="graphql-code-line ">el</div>
<div class="graphql-code-line comment">"""Gujarati"""</div>
<div class="graphql-code-line ">gu</div>
<div class="graphql-code-line comment">"""Haitian Creole"""</div>
<div class="graphql-code-line ">ht</div>
<div class="graphql-code-line comment">"""Hausa"""</div>
<div class="graphql-code-line ">ha</div>
<div class="graphql-code-line comment">"""Hebrew"""</div>
<div class="graphql-code-line ">he</div>
<div class="graphql-code-line comment">"""Hindi"""</div>
<div class="graphql-code-line ">hi</div>
<div class="graphql-code-line comment">"""Hungarian"""</div>
<div class="graphql-code-line ">hu</div>
<div class="graphql-code-line comment">"""Icelandic"""</div>
<div class="graphql-code-line ">is</div>
<div class="graphql-code-line comment">"""Igbo"""</div>
<div class="graphql-code-line ">ig</div>
<div class="graphql-code-line comment">"""Indonesian"""</div>
<div class="graphql-code-line ">id</div>
<div class="graphql-code-line comment">"""Interlingua"""</div>
<div class="graphql-code-line ">ia</div>
<div class="graphql-code-line comment">"""Irish"""</div>
<div class="graphql-code-line ">ga</div>
<div class="graphql-code-line comment">"""Italian"""</div>
<div class="graphql-code-line ">it</div>
<div class="graphql-code-line comment">"""Japanese"""</div>
<div class="graphql-code-line ">ja</div>
<div class="graphql-code-line comment">"""Javanese"""</div>
<div class="graphql-code-line ">jv</div>
<div class="graphql-code-line comment">"""Kalaallisut"""</div>
<div class="graphql-code-line ">kl</div>
<div class="graphql-code-line comment">"""Kannada"""</div>
<div class="graphql-code-line ">kn</div>
<div class="graphql-code-line comment">"""Kashmiri"""</div>
<div class="graphql-code-line ">ks</div>
<div class="graphql-code-line comment">"""Kazakh"""</div>
<div class="graphql-code-line ">kk</div>
<div class="graphql-code-line comment">"""Khmer"""</div>
<div class="graphql-code-line ">km</div>
<div class="graphql-code-line comment">"""Kikuyu"""</div>
<div class="graphql-code-line ">ki</div>
<div class="graphql-code-line comment">"""Kinyarwanda"""</div>
<div class="graphql-code-line ">rw</div>
<div class="graphql-code-line comment">"""Korean"""</div>
<div class="graphql-code-line ">ko</div>
<div class="graphql-code-line comment">"""Kurdish"""</div>
<div class="graphql-code-line ">ku</div>
<div class="graphql-code-line comment">"""Kyrgyz"""</div>
<div class="graphql-code-line ">ky</div>
<div class="graphql-code-line comment">"""Lao"""</div>
<div class="graphql-code-line ">lo</div>
<div class="graphql-code-line comment">"""Latin"""</div>
<div class="graphql-code-line ">la</div>
<div class="graphql-code-line comment">"""Latvian"""</div>
<div class="graphql-code-line ">lv</div>
<div class="graphql-code-line comment">"""Lingala"""</div>
<div class="graphql-code-line ">ln</div>
<div class="graphql-code-line comment">"""Lithuanian"""</div>
<div class="graphql-code-line ">lt</div>
<div class="graphql-code-line comment">"""Luba-Katanga"""</div>
<div class="graphql-code-line ">lu</div>
<div class="graphql-code-line comment">"""Luxembourgish"""</div>
<div class="graphql-code-line ">lb</div>
<div class="graphql-code-line comment">"""Macedonian"""</div>
<div class="graphql-code-line ">mk</div>
<div class="graphql-code-line comment">"""Malagasy"""</div>
<div class="graphql-code-line ">mg</div>
<div class="graphql-code-line comment">"""Malay"""</div>
<div class="graphql-code-line ">ms</div>
<div class="graphql-code-line comment">"""Malayalam"""</div>
<div class="graphql-code-line ">ml</div>
<div class="graphql-code-line comment">"""Maltese"""</div>
<div class="graphql-code-line ">mt</div>
<div class="graphql-code-line comment">"""Manx"""</div>
<div class="graphql-code-line ">gv</div>
<div class="graphql-code-line comment">"""Maori"""</div>
<div class="graphql-code-line ">mi</div>
<div class="graphql-code-line comment">"""Marathi"""</div>
<div class="graphql-code-line ">mr</div>
<div class="graphql-code-line comment">"""Mongolian"""</div>
<div class="graphql-code-line ">mn</div>
<div class="graphql-code-line comment">"""Nepali"""</div>
<div class="graphql-code-line ">ne</div>
<div class="graphql-code-line comment">"""North Ndebele"""</div>
<div class="graphql-code-line ">nd</div>
<div class="graphql-code-line comment">"""Northern Sami"""</div>
<div class="graphql-code-line ">se</div>
<div class="graphql-code-line comment">"""Norwegian Bokmål"""</div>
<div class="graphql-code-line ">nb</div>
<div class="graphql-code-line comment">"""Norwegian Nynorsk"""</div>
<div class="graphql-code-line ">nn</div>
<div class="graphql-code-line comment">"""Nyanja"""</div>
<div class="graphql-code-line ">ny</div>
<div class="graphql-code-line comment">"""Odia"""</div>
<div class="graphql-code-line ">or</div>
<div class="graphql-code-line comment">"""Oromo"""</div>
<div class="graphql-code-line ">om</div>
<div class="graphql-code-line comment">"""Ossetic"""</div>
<div class="graphql-code-line ">os</div>
<div class="graphql-code-line comment">"""Pashto"""</div>
<div class="graphql-code-line ">ps</div>
<div class="graphql-code-line comment">"""Persian"""</div>
<div class="graphql-code-line ">fa</div>
<div class="graphql-code-line comment">"""Dari"""</div>
<div class="graphql-code-line ">fa_AF</div>
<div class="graphql-code-line comment">"""Polish"""</div>
<div class="graphql-code-line ">pl</div>
<div class="graphql-code-line comment">"""Portuguese"""</div>
<div class="graphql-code-line ">pt</div>
<div class="graphql-code-line comment">"""Brazilian Portuguese"""</div>
<div class="graphql-code-line ">pt_BR</div>
<div class="graphql-code-line comment">"""European Portuguese"""</div>
<div class="graphql-code-line ">pt_PT</div>
<div class="graphql-code-line comment">"""Punjabi"""</div>
<div class="graphql-code-line ">pa</div>
<div class="graphql-code-line comment">"""Quechua"""</div>
<div class="graphql-code-line ">qu</div>
<div class="graphql-code-line comment">"""Romanian"""</div>
<div class="graphql-code-line ">ro</div>
<div class="graphql-code-line comment">"""Moldavian"""</div>
<div class="graphql-code-line ">ro_MD</div>
<div class="graphql-code-line comment">"""Romansh"""</div>
<div class="graphql-code-line ">rm</div>
<div class="graphql-code-line comment">"""Rundi"""</div>
<div class="graphql-code-line ">rn</div>
<div class="graphql-code-line comment">"""Russian"""</div>
<div class="graphql-code-line ">ru</div>
<div class="graphql-code-line comment">"""Samoan"""</div>
<div class="graphql-code-line ">sm</div>
<div class="graphql-code-line comment">"""Sango"""</div>
<div class="graphql-code-line ">sg</div>
<div class="graphql-code-line comment">"""Sanskrit"""</div>
<div class="graphql-code-line ">sa</div>
<div class="graphql-code-line comment">"""Scottish Gaelic"""</div>
<div class="graphql-code-line ">gd</div>
<div class="graphql-code-line comment">"""Serbian"""</div>
<div class="graphql-code-line ">sr</div>
<div class="graphql-code-line comment">"""Shona"""</div>
<div class="graphql-code-line ">sn</div>
<div class="graphql-code-line comment">"""Sichuan Yi"""</div>
<div class="graphql-code-line ">ii</div>
<div class="graphql-code-line comment">"""Sindhi"""</div>
<div class="graphql-code-line ">sd</div>
<div class="graphql-code-line comment">"""Sinhala"""</div>
<div class="graphql-code-line ">si</div>
<div class="graphql-code-line comment">"""Slovak"""</div>
<div class="graphql-code-line ">sk</div>
<div class="graphql-code-line comment">"""Slovenian"""</div>
<div class="graphql-code-line ">sl</div>
<div class="graphql-code-line comment">"""Somali"""</div>
<div class="graphql-code-line ">so</div>
<div class="graphql-code-line comment">"""Southern Sotho"""</div>
<div class="graphql-code-line ">st</div>
<div class="graphql-code-line comment">"""Spanish"""</div>
<div class="graphql-code-line ">es</div>
<div class="graphql-code-line comment">"""European Spanish"""</div>
<div class="graphql-code-line ">es_ES</div>
<div class="graphql-code-line comment">"""Mexican Spanish"""</div>
<div class="graphql-code-line ">es_MX</div>
<div class="graphql-code-line comment">"""Sundanese"""</div>
<div class="graphql-code-line ">su</div>
<div class="graphql-code-line comment">"""Swahili"""</div>
<div class="graphql-code-line ">sw</div>
<div class="graphql-code-line comment">"""Congo Swahili"""</div>
<div class="graphql-code-line ">sw_CD</div>
<div class="graphql-code-line comment">"""Swedish"""</div>
<div class="graphql-code-line ">sv</div>
<div class="graphql-code-line comment">"""Tajik"""</div>
<div class="graphql-code-line ">tg</div>
<div class="graphql-code-line comment">"""Tamil"""</div>
<div class="graphql-code-line ">ta</div>
<div class="graphql-code-line comment">"""Tatar"""</div>
<div class="graphql-code-line ">tt</div>
<div class="graphql-code-line comment">"""Telugu"""</div>
<div class="graphql-code-line ">te</div>
<div class="graphql-code-line comment">"""Thai"""</div>
<div class="graphql-code-line ">th</div>
<div class="graphql-code-line comment">"""Tibetan"""</div>
<div class="graphql-code-line ">bo</div>
<div class="graphql-code-line comment">"""Tigrinya"""</div>
<div class="graphql-code-line ">ti</div>
<div class="graphql-code-line comment">"""Tongan"""</div>
<div class="graphql-code-line ">to</div>
<div class="graphql-code-line comment">"""Turkish"""</div>
<div class="graphql-code-line ">tr</div>
<div class="graphql-code-line comment">"""Turkmen"""</div>
<div class="graphql-code-line ">tk</div>
<div class="graphql-code-line comment">"""Ukrainian"""</div>
<div class="graphql-code-line ">uk</div>
<div class="graphql-code-line comment">"""Urdu"""</div>
<div class="graphql-code-line ">ur</div>
<div class="graphql-code-line comment">"""Uyghur"""</div>
<div class="graphql-code-line ">ug</div>
<div class="graphql-code-line comment">"""Uzbek"""</div>
<div class="graphql-code-line ">uz</div>
<div class="graphql-code-line comment">"""Vietnamese"""</div>
<div class="graphql-code-line ">vi</div>
<div class="graphql-code-line comment">"""Volapük"""</div>
<div class="graphql-code-line ">vo</div>
<div class="graphql-code-line comment">"""Welsh"""</div>
<div class="graphql-code-line ">cy</div>
<div class="graphql-code-line comment">"""Western Frisian"""</div>
<div class="graphql-code-line ">fy</div>
<div class="graphql-code-line comment">"""Wolof"""</div>
<div class="graphql-code-line ">wo</div>
<div class="graphql-code-line comment">"""Xhosa"""</div>
<div class="graphql-code-line ">xh</div>
<div class="graphql-code-line comment">"""Yiddish"""</div>
<div class="graphql-code-line ">yi</div>
<div class="graphql-code-line comment">"""Yoruba"""</div>
<div class="graphql-code-line ">yo</div>
<div class="graphql-code-line comment">"""Zulu"""</div>
<div class="graphql-code-line ">zu</div>
<div class="graphql-code-line top-level">&#125;</div>
</div>

## LogicalOperator

<div class="graphql-code-block">

<div class="graphql-code-line top-level">enum <span class="graphql-code-identifier">LogicalOperator</span> &#123;</div>
<div class="graphql-code-line ">AND</div>
<div class="graphql-code-line ">OR</div>
<div class="graphql-code-line top-level">&#125;</div>
</div>

## OrderType

<div class="graphql-code-block">

<div class="graphql-code-line top-level">enum <span class="graphql-code-identifier">OrderType</span> &#123;</div>
<div class="graphql-code-line ">Regular</div>
<div class="graphql-code-line ">Seller</div>
<div class="graphql-code-line ">Aggregate</div>
<div class="graphql-code-line top-level">&#125;</div>
</div>

## Permission

<div class="graphql-code-block">
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Permissions for administrators and customers. Used to control access to</div>

<div class="graphql-code-line comment">GraphQL resolvers via the &#123;@link Allow&#125; decorator.</div>

<div class="graphql-code-line comment"></div>

<div class="graphql-code-line comment">## Understanding Permission.Owner</div>

<div class="graphql-code-line comment"></div>

<div class="graphql-code-line comment">`Permission.Owner` is a special permission which is used in some Vendure resolvers to indicate that that resolver should only</div>

<div class="graphql-code-line comment">be accessible to the "owner" of that resource.</div>

<div class="graphql-code-line comment"></div>

<div class="graphql-code-line comment">For example, the Shop API <code>activeCustomer</code> query resolver should only return the Customer object for the "owner" of that Customer, i.e.</div>

<div class="graphql-code-line comment">based on the activeUserId of the current session. As a result, the resolver code looks like this:</div>

<div class="graphql-code-line comment"></div>

<div class="graphql-code-line comment">@example</div>

<div class="graphql-code-line comment">```TypeScript</div>

<div class="graphql-code-line comment">\@Query()</div>

<div class="graphql-code-line comment">\@Allow(Permission.Owner)</div>

<div class="graphql-code-line comment">async activeCustomer(\@Ctx() ctx: RequestContext): Promise&lt;Customer | undefined&gt; &#123;</div>

<div class="graphql-code-line comment">  const userId = ctx.activeUserId;</div>

<div class="graphql-code-line comment">  if (userId) &#123;</div>

<div class="graphql-code-line comment">    return this.customerService.findOneByUserId(ctx, userId);</div>

<div class="graphql-code-line comment">  &#125;</div>

<div class="graphql-code-line comment">&#125;</div>

<div class="graphql-code-line comment">```</div>

<div class="graphql-code-line comment"></div>

<div class="graphql-code-line comment">Here we can see that the "ownership" must be enforced by custom logic inside the resolver. Since "ownership" cannot be defined generally</div>

<div class="graphql-code-line comment">nor statically encoded at build-time, any resolvers using <code>Permission.Owner</code> **must** include logic to enforce that only the owner</div>

<div class="graphql-code-line comment">of the resource has access. If not, then it is the equivalent of using `Permission.Public`.</div>

<div class="graphql-code-line comment"></div>

<div class="graphql-code-line comment"></div>

<div class="graphql-code-line comment"></div>
<div class="graphql-code-line comment">"""</div>

<div class="graphql-code-line top-level">enum <span class="graphql-code-identifier">Permission</span> &#123;</div>
<div class="graphql-code-line comment">"""Authenticated means simply that the user is logged in"""</div>
<div class="graphql-code-line ">Authenticated</div>
<div class="graphql-code-line comment">"""SuperAdmin has unrestricted access to all operations"""</div>
<div class="graphql-code-line ">SuperAdmin</div>
<div class="graphql-code-line comment">"""Owner means the user owns this entity, e.g. a Customer's own Order"""</div>
<div class="graphql-code-line ">Owner</div>
<div class="graphql-code-line comment">"""Public means any unauthenticated user may perform the operation"""</div>
<div class="graphql-code-line ">Public</div>
<div class="graphql-code-line comment">"""Grants permission to update GlobalSettings"""</div>
<div class="graphql-code-line ">UpdateGlobalSettings</div>
<div class="graphql-code-line comment">"""Grants permission to create Products, Facets, Assets, Collections"""</div>
<div class="graphql-code-line ">CreateCatalog</div>
<div class="graphql-code-line comment">"""Grants permission to read Products, Facets, Assets, Collections"""</div>
<div class="graphql-code-line ">ReadCatalog</div>
<div class="graphql-code-line comment">"""Grants permission to update Products, Facets, Assets, Collections"""</div>
<div class="graphql-code-line ">UpdateCatalog</div>
<div class="graphql-code-line comment">"""Grants permission to delete Products, Facets, Assets, Collections"""</div>
<div class="graphql-code-line ">DeleteCatalog</div>
<div class="graphql-code-line comment">"""Grants permission to create PaymentMethods, ShippingMethods, TaxCategories, TaxRates, Zones, Countries, System & GlobalSettings"""</div>
<div class="graphql-code-line ">CreateSettings</div>
<div class="graphql-code-line comment">"""Grants permission to read PaymentMethods, ShippingMethods, TaxCategories, TaxRates, Zones, Countries, System & GlobalSettings"""</div>
<div class="graphql-code-line ">ReadSettings</div>
<div class="graphql-code-line comment">"""Grants permission to update PaymentMethods, ShippingMethods, TaxCategories, TaxRates, Zones, Countries, System & GlobalSettings"""</div>
<div class="graphql-code-line ">UpdateSettings</div>
<div class="graphql-code-line comment">"""Grants permission to delete PaymentMethods, ShippingMethods, TaxCategories, TaxRates, Zones, Countries, System & GlobalSettings"""</div>
<div class="graphql-code-line ">DeleteSettings</div>
<div class="graphql-code-line comment">"""Grants permission to create Administrator"""</div>
<div class="graphql-code-line ">CreateAdministrator</div>
<div class="graphql-code-line comment">"""Grants permission to read Administrator"""</div>
<div class="graphql-code-line ">ReadAdministrator</div>
<div class="graphql-code-line comment">"""Grants permission to update Administrator"""</div>
<div class="graphql-code-line ">UpdateAdministrator</div>
<div class="graphql-code-line comment">"""Grants permission to delete Administrator"""</div>
<div class="graphql-code-line ">DeleteAdministrator</div>
<div class="graphql-code-line comment">"""Grants permission to create Asset"""</div>
<div class="graphql-code-line ">CreateAsset</div>
<div class="graphql-code-line comment">"""Grants permission to read Asset"""</div>
<div class="graphql-code-line ">ReadAsset</div>
<div class="graphql-code-line comment">"""Grants permission to update Asset"""</div>
<div class="graphql-code-line ">UpdateAsset</div>
<div class="graphql-code-line comment">"""Grants permission to delete Asset"""</div>
<div class="graphql-code-line ">DeleteAsset</div>
<div class="graphql-code-line comment">"""Grants permission to create Channel"""</div>
<div class="graphql-code-line ">CreateChannel</div>
<div class="graphql-code-line comment">"""Grants permission to read Channel"""</div>
<div class="graphql-code-line ">ReadChannel</div>
<div class="graphql-code-line comment">"""Grants permission to update Channel"""</div>
<div class="graphql-code-line ">UpdateChannel</div>
<div class="graphql-code-line comment">"""Grants permission to delete Channel"""</div>
<div class="graphql-code-line ">DeleteChannel</div>
<div class="graphql-code-line comment">"""Grants permission to create Collection"""</div>
<div class="graphql-code-line ">CreateCollection</div>
<div class="graphql-code-line comment">"""Grants permission to read Collection"""</div>
<div class="graphql-code-line ">ReadCollection</div>
<div class="graphql-code-line comment">"""Grants permission to update Collection"""</div>
<div class="graphql-code-line ">UpdateCollection</div>
<div class="graphql-code-line comment">"""Grants permission to delete Collection"""</div>
<div class="graphql-code-line ">DeleteCollection</div>
<div class="graphql-code-line comment">"""Grants permission to create Country"""</div>
<div class="graphql-code-line ">CreateCountry</div>
<div class="graphql-code-line comment">"""Grants permission to read Country"""</div>
<div class="graphql-code-line ">ReadCountry</div>
<div class="graphql-code-line comment">"""Grants permission to update Country"""</div>
<div class="graphql-code-line ">UpdateCountry</div>
<div class="graphql-code-line comment">"""Grants permission to delete Country"""</div>
<div class="graphql-code-line ">DeleteCountry</div>
<div class="graphql-code-line comment">"""Grants permission to create Customer"""</div>
<div class="graphql-code-line ">CreateCustomer</div>
<div class="graphql-code-line comment">"""Grants permission to read Customer"""</div>
<div class="graphql-code-line ">ReadCustomer</div>
<div class="graphql-code-line comment">"""Grants permission to update Customer"""</div>
<div class="graphql-code-line ">UpdateCustomer</div>
<div class="graphql-code-line comment">"""Grants permission to delete Customer"""</div>
<div class="graphql-code-line ">DeleteCustomer</div>
<div class="graphql-code-line comment">"""Grants permission to create CustomerGroup"""</div>
<div class="graphql-code-line ">CreateCustomerGroup</div>
<div class="graphql-code-line comment">"""Grants permission to read CustomerGroup"""</div>
<div class="graphql-code-line ">ReadCustomerGroup</div>
<div class="graphql-code-line comment">"""Grants permission to update CustomerGroup"""</div>
<div class="graphql-code-line ">UpdateCustomerGroup</div>
<div class="graphql-code-line comment">"""Grants permission to delete CustomerGroup"""</div>
<div class="graphql-code-line ">DeleteCustomerGroup</div>
<div class="graphql-code-line comment">"""Grants permission to create Facet"""</div>
<div class="graphql-code-line ">CreateFacet</div>
<div class="graphql-code-line comment">"""Grants permission to read Facet"""</div>
<div class="graphql-code-line ">ReadFacet</div>
<div class="graphql-code-line comment">"""Grants permission to update Facet"""</div>
<div class="graphql-code-line ">UpdateFacet</div>
<div class="graphql-code-line comment">"""Grants permission to delete Facet"""</div>
<div class="graphql-code-line ">DeleteFacet</div>
<div class="graphql-code-line comment">"""Grants permission to create Order"""</div>
<div class="graphql-code-line ">CreateOrder</div>
<div class="graphql-code-line comment">"""Grants permission to read Order"""</div>
<div class="graphql-code-line ">ReadOrder</div>
<div class="graphql-code-line comment">"""Grants permission to update Order"""</div>
<div class="graphql-code-line ">UpdateOrder</div>
<div class="graphql-code-line comment">"""Grants permission to delete Order"""</div>
<div class="graphql-code-line ">DeleteOrder</div>
<div class="graphql-code-line comment">"""Grants permission to create PaymentMethod"""</div>
<div class="graphql-code-line ">CreatePaymentMethod</div>
<div class="graphql-code-line comment">"""Grants permission to read PaymentMethod"""</div>
<div class="graphql-code-line ">ReadPaymentMethod</div>
<div class="graphql-code-line comment">"""Grants permission to update PaymentMethod"""</div>
<div class="graphql-code-line ">UpdatePaymentMethod</div>
<div class="graphql-code-line comment">"""Grants permission to delete PaymentMethod"""</div>
<div class="graphql-code-line ">DeletePaymentMethod</div>
<div class="graphql-code-line comment">"""Grants permission to create Product"""</div>
<div class="graphql-code-line ">CreateProduct</div>
<div class="graphql-code-line comment">"""Grants permission to read Product"""</div>
<div class="graphql-code-line ">ReadProduct</div>
<div class="graphql-code-line comment">"""Grants permission to update Product"""</div>
<div class="graphql-code-line ">UpdateProduct</div>
<div class="graphql-code-line comment">"""Grants permission to delete Product"""</div>
<div class="graphql-code-line ">DeleteProduct</div>
<div class="graphql-code-line comment">"""Grants permission to create Promotion"""</div>
<div class="graphql-code-line ">CreatePromotion</div>
<div class="graphql-code-line comment">"""Grants permission to read Promotion"""</div>
<div class="graphql-code-line ">ReadPromotion</div>
<div class="graphql-code-line comment">"""Grants permission to update Promotion"""</div>
<div class="graphql-code-line ">UpdatePromotion</div>
<div class="graphql-code-line comment">"""Grants permission to delete Promotion"""</div>
<div class="graphql-code-line ">DeletePromotion</div>
<div class="graphql-code-line comment">"""Grants permission to create ShippingMethod"""</div>
<div class="graphql-code-line ">CreateShippingMethod</div>
<div class="graphql-code-line comment">"""Grants permission to read ShippingMethod"""</div>
<div class="graphql-code-line ">ReadShippingMethod</div>
<div class="graphql-code-line comment">"""Grants permission to update ShippingMethod"""</div>
<div class="graphql-code-line ">UpdateShippingMethod</div>
<div class="graphql-code-line comment">"""Grants permission to delete ShippingMethod"""</div>
<div class="graphql-code-line ">DeleteShippingMethod</div>
<div class="graphql-code-line comment">"""Grants permission to create Tag"""</div>
<div class="graphql-code-line ">CreateTag</div>
<div class="graphql-code-line comment">"""Grants permission to read Tag"""</div>
<div class="graphql-code-line ">ReadTag</div>
<div class="graphql-code-line comment">"""Grants permission to update Tag"""</div>
<div class="graphql-code-line ">UpdateTag</div>
<div class="graphql-code-line comment">"""Grants permission to delete Tag"""</div>
<div class="graphql-code-line ">DeleteTag</div>
<div class="graphql-code-line comment">"""Grants permission to create TaxCategory"""</div>
<div class="graphql-code-line ">CreateTaxCategory</div>
<div class="graphql-code-line comment">"""Grants permission to read TaxCategory"""</div>
<div class="graphql-code-line ">ReadTaxCategory</div>
<div class="graphql-code-line comment">"""Grants permission to update TaxCategory"""</div>
<div class="graphql-code-line ">UpdateTaxCategory</div>
<div class="graphql-code-line comment">"""Grants permission to delete TaxCategory"""</div>
<div class="graphql-code-line ">DeleteTaxCategory</div>
<div class="graphql-code-line comment">"""Grants permission to create TaxRate"""</div>
<div class="graphql-code-line ">CreateTaxRate</div>
<div class="graphql-code-line comment">"""Grants permission to read TaxRate"""</div>
<div class="graphql-code-line ">ReadTaxRate</div>
<div class="graphql-code-line comment">"""Grants permission to update TaxRate"""</div>
<div class="graphql-code-line ">UpdateTaxRate</div>
<div class="graphql-code-line comment">"""Grants permission to delete TaxRate"""</div>
<div class="graphql-code-line ">DeleteTaxRate</div>
<div class="graphql-code-line comment">"""Grants permission to create Seller"""</div>
<div class="graphql-code-line ">CreateSeller</div>
<div class="graphql-code-line comment">"""Grants permission to read Seller"""</div>
<div class="graphql-code-line ">ReadSeller</div>
<div class="graphql-code-line comment">"""Grants permission to update Seller"""</div>
<div class="graphql-code-line ">UpdateSeller</div>
<div class="graphql-code-line comment">"""Grants permission to delete Seller"""</div>
<div class="graphql-code-line ">DeleteSeller</div>
<div class="graphql-code-line comment">"""Grants permission to create StockLocation"""</div>
<div class="graphql-code-line ">CreateStockLocation</div>
<div class="graphql-code-line comment">"""Grants permission to read StockLocation"""</div>
<div class="graphql-code-line ">ReadStockLocation</div>
<div class="graphql-code-line comment">"""Grants permission to update StockLocation"""</div>
<div class="graphql-code-line ">UpdateStockLocation</div>
<div class="graphql-code-line comment">"""Grants permission to delete StockLocation"""</div>
<div class="graphql-code-line ">DeleteStockLocation</div>
<div class="graphql-code-line comment">"""Grants permission to create System"""</div>
<div class="graphql-code-line ">CreateSystem</div>
<div class="graphql-code-line comment">"""Grants permission to read System"""</div>
<div class="graphql-code-line ">ReadSystem</div>
<div class="graphql-code-line comment">"""Grants permission to update System"""</div>
<div class="graphql-code-line ">UpdateSystem</div>
<div class="graphql-code-line comment">"""Grants permission to delete System"""</div>
<div class="graphql-code-line ">DeleteSystem</div>
<div class="graphql-code-line comment">"""Grants permission to create Zone"""</div>
<div class="graphql-code-line ">CreateZone</div>
<div class="graphql-code-line comment">"""Grants permission to read Zone"""</div>
<div class="graphql-code-line ">ReadZone</div>
<div class="graphql-code-line comment">"""Grants permission to update Zone"""</div>
<div class="graphql-code-line ">UpdateZone</div>
<div class="graphql-code-line comment">"""Grants permission to delete Zone"""</div>
<div class="graphql-code-line ">DeleteZone</div>
<div class="graphql-code-line top-level">&#125;</div>
</div>

## SortOrder

<div class="graphql-code-block">

<div class="graphql-code-line top-level">enum <span class="graphql-code-identifier">SortOrder</span> &#123;</div>
<div class="graphql-code-line ">ASC</div>
<div class="graphql-code-line ">DESC</div>
<div class="graphql-code-line top-level">&#125;</div>
</div>


---

---
title: "Input Objects"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';



## AddItemInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">AddItemInput</span> &#123;</div>
<div class="graphql-code-line ">productVariantId: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">quantity: <a href="/reference/graphql-api/shop/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## AuthenticationInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">AuthenticationInput</span> &#123;</div>
<div class="graphql-code-line ">native: <a href="/reference/graphql-api/shop/input-types#nativeauthinput">NativeAuthInput</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## BooleanListOperators

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Operators for filtering on a list of Boolean fields</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">BooleanListOperators</span> &#123;</div>
<div class="graphql-code-line ">inList: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## BooleanOperators

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Operators for filtering on a Boolean field</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">BooleanOperators</span> &#123;</div>
<div class="graphql-code-line ">eq: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">isNull: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CollectionFilterParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CollectionFilterParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/shop/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">slug: <a href="/reference/graphql-api/shop/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">position: <a href="/reference/graphql-api/shop/input-types#numberoperators">NumberOperators</a></div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/shop/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">parentId: <a href="/reference/graphql-api/shop/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">_and: [<a href="/reference/graphql-api/shop/input-types#collectionfilterparameter">CollectionFilterParameter</a>!]</div>

<div class="graphql-code-line ">_or: [<a href="/reference/graphql-api/shop/input-types#collectionfilterparameter">CollectionFilterParameter</a>!]</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CollectionListOptions

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CollectionListOptions</span> &#123;</div>
<div class="graphql-code-line ">topLevelOnly: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Skips the first n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">skip: <a href="/reference/graphql-api/shop/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Takes n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">take: <a href="/reference/graphql-api/shop/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies which properties to sort the results by</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">sort: <a href="/reference/graphql-api/shop/input-types#collectionsortparameter">CollectionSortParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Allows the results to be filtered</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filter: <a href="/reference/graphql-api/shop/input-types#collectionfilterparameter">CollectionFilterParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies whether multiple top-level "filter" fields should be combined with a logical AND or OR operation. Defaults to AND.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filterOperator: <a href="/reference/graphql-api/shop/enums#logicaloperator">LogicalOperator</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CollectionSortParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CollectionSortParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">slug: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">position: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">parentId: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ConfigArgInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">ConfigArgInput</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">A JSON stringified representation of the actual value</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">value: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ConfigurableOperationInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">ConfigurableOperationInput</span> &#123;</div>
<div class="graphql-code-line ">code: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">arguments: [<a href="/reference/graphql-api/shop/input-types#configarginput">ConfigArgInput</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CreateAddressInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Input used to create an Address.</div>

<div class="graphql-code-line top-level comment"></div>

<div class="graphql-code-line top-level comment">The countryCode must correspond to a <code>code</code> property of a Country that has been defined in the</div>

<div class="graphql-code-line top-level comment">Vendure server. The <code>code</code> property is typically a 2-character ISO code such as "GB", "US", "DE" etc.</div>

<div class="graphql-code-line top-level comment">If an invalid code is passed, the mutation will fail.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CreateAddressInput</span> &#123;</div>
<div class="graphql-code-line ">fullName: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">company: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">streetLine1: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">streetLine2: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">city: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">province: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">postalCode: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">countryCode: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">phoneNumber: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">defaultShippingAddress: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">defaultBillingAddress: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CreateCustomerInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CreateCustomerInput</span> &#123;</div>
<div class="graphql-code-line ">title: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">firstName: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">lastName: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">phoneNumber: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">emailAddress: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CustomerFilterParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CustomerFilterParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">title: <a href="/reference/graphql-api/shop/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">firstName: <a href="/reference/graphql-api/shop/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">lastName: <a href="/reference/graphql-api/shop/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">phoneNumber: <a href="/reference/graphql-api/shop/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">emailAddress: <a href="/reference/graphql-api/shop/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">_and: [<a href="/reference/graphql-api/shop/input-types#customerfilterparameter">CustomerFilterParameter</a>!]</div>

<div class="graphql-code-line ">_or: [<a href="/reference/graphql-api/shop/input-types#customerfilterparameter">CustomerFilterParameter</a>!]</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CustomerListOptions

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CustomerListOptions</span> &#123;</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Skips the first n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">skip: <a href="/reference/graphql-api/shop/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Takes n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">take: <a href="/reference/graphql-api/shop/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies which properties to sort the results by</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">sort: <a href="/reference/graphql-api/shop/input-types#customersortparameter">CustomerSortParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Allows the results to be filtered</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filter: <a href="/reference/graphql-api/shop/input-types#customerfilterparameter">CustomerFilterParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies whether multiple top-level "filter" fields should be combined with a logical AND or OR operation. Defaults to AND.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filterOperator: <a href="/reference/graphql-api/shop/enums#logicaloperator">LogicalOperator</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CustomerSortParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">CustomerSortParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">title: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">firstName: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">lastName: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">phoneNumber: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">emailAddress: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## DateListOperators

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Operators for filtering on a list of Date fields</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">DateListOperators</span> &#123;</div>
<div class="graphql-code-line ">inList: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## DateOperators

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Operators for filtering on a DateTime field</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">DateOperators</span> &#123;</div>
<div class="graphql-code-line ">eq: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a></div>

<div class="graphql-code-line ">before: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a></div>

<div class="graphql-code-line ">after: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a></div>

<div class="graphql-code-line ">between: <a href="/reference/graphql-api/shop/input-types#daterange">DateRange</a></div>

<div class="graphql-code-line ">isNull: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## DateRange

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">DateRange</span> &#123;</div>
<div class="graphql-code-line ">start: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">end: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## FacetFilterParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">FacetFilterParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/shop/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/shop/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">_and: [<a href="/reference/graphql-api/shop/input-types#facetfilterparameter">FacetFilterParameter</a>!]</div>

<div class="graphql-code-line ">_or: [<a href="/reference/graphql-api/shop/input-types#facetfilterparameter">FacetFilterParameter</a>!]</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## FacetListOptions

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">FacetListOptions</span> &#123;</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Skips the first n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">skip: <a href="/reference/graphql-api/shop/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Takes n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">take: <a href="/reference/graphql-api/shop/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies which properties to sort the results by</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">sort: <a href="/reference/graphql-api/shop/input-types#facetsortparameter">FacetSortParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Allows the results to be filtered</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filter: <a href="/reference/graphql-api/shop/input-types#facetfilterparameter">FacetFilterParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies whether multiple top-level "filter" fields should be combined with a logical AND or OR operation. Defaults to AND.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filterOperator: <a href="/reference/graphql-api/shop/enums#logicaloperator">LogicalOperator</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## FacetSortParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">FacetSortParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## FacetValueFilterInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Used to construct boolean expressions for filtering search results</div>

<div class="graphql-code-line top-level comment">by FacetValue ID. Examples:</div>

<div class="graphql-code-line top-level comment"></div>

<div class="graphql-code-line top-level comment">* ID=1 OR ID=2: `&#123; facetValueFilters: [&#123; or: [1,2] &#125;] &#125;`</div>

<div class="graphql-code-line top-level comment">* ID=1 AND ID=2: `&#123; facetValueFilters: [&#123; and: 1 &#125;, &#123; and: 2 &#125;] &#125;`</div>

<div class="graphql-code-line top-level comment">* ID=1 AND (ID=2 OR ID=3): `&#123; facetValueFilters: [&#123; and: 1 &#125;, &#123; or: [2,3] &#125;] &#125;`</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">FacetValueFilterInput</span> &#123;</div>
<div class="graphql-code-line ">and: <a href="/reference/graphql-api/shop/object-types#id">ID</a></div>

<div class="graphql-code-line ">or: [<a href="/reference/graphql-api/shop/object-types#id">ID</a>!]</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## FacetValueFilterParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">FacetValueFilterParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/shop/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">facetId: <a href="/reference/graphql-api/shop/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/shop/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">_and: [<a href="/reference/graphql-api/shop/input-types#facetvaluefilterparameter">FacetValueFilterParameter</a>!]</div>

<div class="graphql-code-line ">_or: [<a href="/reference/graphql-api/shop/input-types#facetvaluefilterparameter">FacetValueFilterParameter</a>!]</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## FacetValueListOptions

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">FacetValueListOptions</span> &#123;</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Skips the first n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">skip: <a href="/reference/graphql-api/shop/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Takes n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">take: <a href="/reference/graphql-api/shop/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies which properties to sort the results by</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">sort: <a href="/reference/graphql-api/shop/input-types#facetvaluesortparameter">FacetValueSortParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Allows the results to be filtered</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filter: <a href="/reference/graphql-api/shop/input-types#facetvaluefilterparameter">FacetValueFilterParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies whether multiple top-level "filter" fields should be combined with a logical AND or OR operation. Defaults to AND.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filterOperator: <a href="/reference/graphql-api/shop/enums#logicaloperator">LogicalOperator</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## FacetValueSortParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">FacetValueSortParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">facetId: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## HistoryEntryFilterParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">HistoryEntryFilterParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/shop/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">_and: [<a href="/reference/graphql-api/shop/input-types#historyentryfilterparameter">HistoryEntryFilterParameter</a>!]</div>

<div class="graphql-code-line ">_or: [<a href="/reference/graphql-api/shop/input-types#historyentryfilterparameter">HistoryEntryFilterParameter</a>!]</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## HistoryEntryListOptions

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">HistoryEntryListOptions</span> &#123;</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Skips the first n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">skip: <a href="/reference/graphql-api/shop/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Takes n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">take: <a href="/reference/graphql-api/shop/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies which properties to sort the results by</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">sort: <a href="/reference/graphql-api/shop/input-types#historyentrysortparameter">HistoryEntrySortParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Allows the results to be filtered</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filter: <a href="/reference/graphql-api/shop/input-types#historyentryfilterparameter">HistoryEntryFilterParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies whether multiple top-level "filter" fields should be combined with a logical AND or OR operation. Defaults to AND.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filterOperator: <a href="/reference/graphql-api/shop/enums#logicaloperator">LogicalOperator</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## HistoryEntrySortParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">HistoryEntrySortParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## IDListOperators

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Operators for filtering on a list of ID fields</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">IDListOperators</span> &#123;</div>
<div class="graphql-code-line ">inList: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## IDOperators

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Operators for filtering on an ID field</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">IDOperators</span> &#123;</div>
<div class="graphql-code-line ">eq: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">notEq: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">in: [<a href="/reference/graphql-api/shop/object-types#string">String</a>!]</div>

<div class="graphql-code-line ">notIn: [<a href="/reference/graphql-api/shop/object-types#string">String</a>!]</div>

<div class="graphql-code-line ">isNull: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## NativeAuthInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">NativeAuthInput</span> &#123;</div>
<div class="graphql-code-line ">username: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">password: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## NumberListOperators

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Operators for filtering on a list of Number fields</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">NumberListOperators</span> &#123;</div>
<div class="graphql-code-line ">inList: <a href="/reference/graphql-api/shop/object-types#float">Float</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## NumberOperators

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Operators for filtering on a Int or Float field</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">NumberOperators</span> &#123;</div>
<div class="graphql-code-line ">eq: <a href="/reference/graphql-api/shop/object-types#float">Float</a></div>

<div class="graphql-code-line ">lt: <a href="/reference/graphql-api/shop/object-types#float">Float</a></div>

<div class="graphql-code-line ">lte: <a href="/reference/graphql-api/shop/object-types#float">Float</a></div>

<div class="graphql-code-line ">gt: <a href="/reference/graphql-api/shop/object-types#float">Float</a></div>

<div class="graphql-code-line ">gte: <a href="/reference/graphql-api/shop/object-types#float">Float</a></div>

<div class="graphql-code-line ">between: <a href="/reference/graphql-api/shop/input-types#numberrange">NumberRange</a></div>

<div class="graphql-code-line ">isNull: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## NumberRange

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">NumberRange</span> &#123;</div>
<div class="graphql-code-line ">start: <a href="/reference/graphql-api/shop/object-types#float">Float</a>!</div>

<div class="graphql-code-line ">end: <a href="/reference/graphql-api/shop/object-types#float">Float</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## OrderFilterParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">OrderFilterParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/shop/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">orderPlacedAt: <a href="/reference/graphql-api/shop/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/shop/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">state: <a href="/reference/graphql-api/shop/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">active: <a href="/reference/graphql-api/shop/input-types#booleanoperators">BooleanOperators</a></div>

<div class="graphql-code-line ">totalQuantity: <a href="/reference/graphql-api/shop/input-types#numberoperators">NumberOperators</a></div>

<div class="graphql-code-line ">subTotal: <a href="/reference/graphql-api/shop/input-types#numberoperators">NumberOperators</a></div>

<div class="graphql-code-line ">subTotalWithTax: <a href="/reference/graphql-api/shop/input-types#numberoperators">NumberOperators</a></div>

<div class="graphql-code-line ">currencyCode: <a href="/reference/graphql-api/shop/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">shipping: <a href="/reference/graphql-api/shop/input-types#numberoperators">NumberOperators</a></div>

<div class="graphql-code-line ">shippingWithTax: <a href="/reference/graphql-api/shop/input-types#numberoperators">NumberOperators</a></div>

<div class="graphql-code-line ">total: <a href="/reference/graphql-api/shop/input-types#numberoperators">NumberOperators</a></div>

<div class="graphql-code-line ">totalWithTax: <a href="/reference/graphql-api/shop/input-types#numberoperators">NumberOperators</a></div>

<div class="graphql-code-line ">_and: [<a href="/reference/graphql-api/shop/input-types#orderfilterparameter">OrderFilterParameter</a>!]</div>

<div class="graphql-code-line ">_or: [<a href="/reference/graphql-api/shop/input-types#orderfilterparameter">OrderFilterParameter</a>!]</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## OrderListOptions

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">OrderListOptions</span> &#123;</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Skips the first n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">skip: <a href="/reference/graphql-api/shop/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Takes n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">take: <a href="/reference/graphql-api/shop/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies which properties to sort the results by</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">sort: <a href="/reference/graphql-api/shop/input-types#ordersortparameter">OrderSortParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Allows the results to be filtered</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filter: <a href="/reference/graphql-api/shop/input-types#orderfilterparameter">OrderFilterParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies whether multiple top-level "filter" fields should be combined with a logical AND or OR operation. Defaults to AND.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filterOperator: <a href="/reference/graphql-api/shop/enums#logicaloperator">LogicalOperator</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## OrderSortParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">OrderSortParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">orderPlacedAt: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">state: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">totalQuantity: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">subTotal: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">subTotalWithTax: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">shipping: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">shippingWithTax: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">total: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">totalWithTax: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## PaymentInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Passed as input to the <code>addPaymentToOrder</code> mutation.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">PaymentInput</span> &#123;</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">This field should correspond to the <code>code</code> property of a PaymentMethod.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">method: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">This field should contain arbitrary data passed to the specified PaymentMethodHandler's <code>createPayment()</code> method</div>

<div class="graphql-code-line comment">as the "metadata" argument. For example, it could contain an ID for the payment and other</div>

<div class="graphql-code-line comment">data generated by the payment provider.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">metadata: <a href="/reference/graphql-api/shop/object-types#json">JSON</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ProductFilterParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">ProductFilterParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/shop/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">slug: <a href="/reference/graphql-api/shop/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/shop/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">enabled: <a href="/reference/graphql-api/shop/input-types#booleanoperators">BooleanOperators</a></div>

<div class="graphql-code-line ">_and: [<a href="/reference/graphql-api/shop/input-types#productfilterparameter">ProductFilterParameter</a>!]</div>

<div class="graphql-code-line ">_or: [<a href="/reference/graphql-api/shop/input-types#productfilterparameter">ProductFilterParameter</a>!]</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ProductListOptions

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">ProductListOptions</span> &#123;</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Skips the first n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">skip: <a href="/reference/graphql-api/shop/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Takes n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">take: <a href="/reference/graphql-api/shop/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies which properties to sort the results by</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">sort: <a href="/reference/graphql-api/shop/input-types#productsortparameter">ProductSortParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Allows the results to be filtered</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filter: <a href="/reference/graphql-api/shop/input-types#productfilterparameter">ProductFilterParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies whether multiple top-level "filter" fields should be combined with a logical AND or OR operation. Defaults to AND.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filterOperator: <a href="/reference/graphql-api/shop/enums#logicaloperator">LogicalOperator</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ProductSortParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">ProductSortParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">slug: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ProductVariantFilterParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">ProductVariantFilterParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">productId: <a href="/reference/graphql-api/shop/input-types#idoperators">IDOperators</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/input-types#dateoperators">DateOperators</a></div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/shop/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">sku: <a href="/reference/graphql-api/shop/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">price: <a href="/reference/graphql-api/shop/input-types#numberoperators">NumberOperators</a></div>

<div class="graphql-code-line ">currencyCode: <a href="/reference/graphql-api/shop/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">priceWithTax: <a href="/reference/graphql-api/shop/input-types#numberoperators">NumberOperators</a></div>

<div class="graphql-code-line ">stockLevel: <a href="/reference/graphql-api/shop/input-types#stringoperators">StringOperators</a></div>

<div class="graphql-code-line ">_and: [<a href="/reference/graphql-api/shop/input-types#productvariantfilterparameter">ProductVariantFilterParameter</a>!]</div>

<div class="graphql-code-line ">_or: [<a href="/reference/graphql-api/shop/input-types#productvariantfilterparameter">ProductVariantFilterParameter</a>!]</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ProductVariantListOptions

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">ProductVariantListOptions</span> &#123;</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Skips the first n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">skip: <a href="/reference/graphql-api/shop/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Takes n results, for use in pagination</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">take: <a href="/reference/graphql-api/shop/object-types#int">Int</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies which properties to sort the results by</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">sort: <a href="/reference/graphql-api/shop/input-types#productvariantsortparameter">ProductVariantSortParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Allows the results to be filtered</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filter: <a href="/reference/graphql-api/shop/input-types#productvariantfilterparameter">ProductVariantFilterParameter</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Specifies whether multiple top-level "filter" fields should be combined with a logical AND or OR operation. Defaults to AND.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">filterOperator: <a href="/reference/graphql-api/shop/enums#logicaloperator">LogicalOperator</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ProductVariantSortParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">ProductVariantSortParameter</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">productId: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">sku: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">price: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">priceWithTax: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">stockLevel: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## RegisterCustomerInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">RegisterCustomerInput</span> &#123;</div>
<div class="graphql-code-line ">emailAddress: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">title: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">firstName: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">lastName: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">phoneNumber: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">password: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## SearchInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">SearchInput</span> &#123;</div>
<div class="graphql-code-line ">term: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">facetValueIds: [<a href="/reference/graphql-api/shop/object-types#id">ID</a>!]</div>

<div class="graphql-code-line ">facetValueOperator: <a href="/reference/graphql-api/shop/enums#logicaloperator">LogicalOperator</a></div>

<div class="graphql-code-line ">facetValueFilters: [<a href="/reference/graphql-api/shop/input-types#facetvaluefilterinput">FacetValueFilterInput</a>!]</div>

<div class="graphql-code-line ">collectionId: <a href="/reference/graphql-api/shop/object-types#id">ID</a></div>

<div class="graphql-code-line ">collectionSlug: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">groupByProduct: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">take: <a href="/reference/graphql-api/shop/object-types#int">Int</a></div>

<div class="graphql-code-line ">skip: <a href="/reference/graphql-api/shop/object-types#int">Int</a></div>

<div class="graphql-code-line ">sort: <a href="/reference/graphql-api/shop/input-types#searchresultsortparameter">SearchResultSortParameter</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## SearchResultSortParameter

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">SearchResultSortParameter</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>

<div class="graphql-code-line ">price: <a href="/reference/graphql-api/shop/enums#sortorder">SortOrder</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## StringListOperators

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Operators for filtering on a list of String fields</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">StringListOperators</span> &#123;</div>
<div class="graphql-code-line ">inList: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## StringOperators

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Operators for filtering on a String field</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">StringOperators</span> &#123;</div>
<div class="graphql-code-line ">eq: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">notEq: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">contains: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">notContains: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">in: [<a href="/reference/graphql-api/shop/object-types#string">String</a>!]</div>

<div class="graphql-code-line ">notIn: [<a href="/reference/graphql-api/shop/object-types#string">String</a>!]</div>

<div class="graphql-code-line ">regex: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">isNull: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## UpdateAddressInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Input used to update an Address.</div>

<div class="graphql-code-line top-level comment"></div>

<div class="graphql-code-line top-level comment">The countryCode must correspond to a <code>code</code> property of a Country that has been defined in the</div>

<div class="graphql-code-line top-level comment">Vendure server. The <code>code</code> property is typically a 2-character ISO code such as "GB", "US", "DE" etc.</div>

<div class="graphql-code-line top-level comment">If an invalid code is passed, the mutation will fail.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">UpdateAddressInput</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">fullName: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">company: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">streetLine1: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">streetLine2: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">city: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">province: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">postalCode: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">countryCode: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">phoneNumber: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">defaultShippingAddress: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">defaultBillingAddress: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## UpdateCustomerInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">UpdateCustomerInput</span> &#123;</div>
<div class="graphql-code-line ">title: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">firstName: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">lastName: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">phoneNumber: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## UpdateOrderInput

<div class="graphql-code-block">
<div class="graphql-code-line top-level">input <span class="graphql-code-identifier">UpdateOrderInput</span> &#123;</div>
<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>


---

---
title: "Mutations"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';



## addItemToOrder
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Adds an item to the Order. If custom fields are defined on the OrderLine entity, a third argument 'customFields' will be available.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">addItemToOrder(productVariantId: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!, quantity: <a href="/reference/graphql-api/shop/object-types#int">Int</a>!): <a href="/reference/graphql-api/shop/object-types#updateorderitemsresult">UpdateOrderItemsResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## addItemsToOrder
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Adds mutliple items to the Order. Returns a list of errors for each item that failed to add. It will still add successful items.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">addItemsToOrder(inputs: [<a href="/reference/graphql-api/shop/input-types#additeminput">AddItemInput</a>!]!): <a href="/reference/graphql-api/shop/object-types#updatemultipleorderitemsresult">UpdateMultipleOrderItemsResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## addPaymentToOrder
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Add a Payment to the Order</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">addPaymentToOrder(input: <a href="/reference/graphql-api/shop/input-types#paymentinput">PaymentInput</a>!): <a href="/reference/graphql-api/shop/object-types#addpaymenttoorderresult">AddPaymentToOrderResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## adjustOrderLine
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Adjusts an OrderLine. If custom fields are defined on the OrderLine entity, a third argument 'customFields' of type <code>OrderLineCustomFieldsInput</code> will be available.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">adjustOrderLine(orderLineId: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!, quantity: <a href="/reference/graphql-api/shop/object-types#int">Int</a>!): <a href="/reference/graphql-api/shop/object-types#updateorderitemsresult">UpdateOrderItemsResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## applyCouponCode
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Applies the given coupon code to the active Order</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">applyCouponCode(couponCode: <a href="/reference/graphql-api/shop/object-types#string">String</a>!): <a href="/reference/graphql-api/shop/object-types#applycouponcoderesult">ApplyCouponCodeResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## authenticate
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Authenticates the user using a named authentication strategy</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">authenticate(input: <a href="/reference/graphql-api/shop/input-types#authenticationinput">AuthenticationInput</a>!, rememberMe: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a>): <a href="/reference/graphql-api/shop/object-types#authenticationresult">AuthenticationResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## createCustomerAddress
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Create a new Customer Address</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">createCustomerAddress(input: <a href="/reference/graphql-api/shop/input-types#createaddressinput">CreateAddressInput</a>!): <a href="/reference/graphql-api/shop/object-types#address">Address</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## deleteCustomerAddress
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Delete an existing Address</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">deleteCustomerAddress(id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!): <a href="/reference/graphql-api/shop/object-types#success">Success</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## login
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Authenticates the user using the native authentication strategy. This mutation is an alias for authenticate(&#123; native: &#123; ... &#125;&#125;)</div>

<div class="graphql-code-line top-level comment"></div>

<div class="graphql-code-line top-level comment">The <code>rememberMe</code> option applies when using cookie-based sessions, and if <code>true</code> it will set the maxAge of the session cookie</div>

<div class="graphql-code-line top-level comment">to 1 year.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">login(username: <a href="/reference/graphql-api/shop/object-types#string">String</a>!, password: <a href="/reference/graphql-api/shop/object-types#string">String</a>!, rememberMe: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a>): <a href="/reference/graphql-api/shop/object-types#nativeauthenticationresult">NativeAuthenticationResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## logout
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">End the current authenticated session</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">logout: <a href="/reference/graphql-api/shop/object-types#success">Success</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## refreshCustomerVerification
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Regenerate and send a verification token for a new Customer registration. Only applicable if <code>authOptions.requireVerification</code> is set to true.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">refreshCustomerVerification(emailAddress: <a href="/reference/graphql-api/shop/object-types#string">String</a>!): <a href="/reference/graphql-api/shop/object-types#refreshcustomerverificationresult">RefreshCustomerVerificationResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## registerCustomerAccount
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Register a Customer account with the given credentials. There are three possible registration flows:</div>

<div class="graphql-code-line top-level comment"></div>

<div class="graphql-code-line top-level comment">_If <code>authOptions.requireVerification</code> is set to `true`:_</div>

<div class="graphql-code-line top-level comment"></div>

<div class="graphql-code-line top-level comment">1. **The Customer is registered _with_ a password**. A verificationToken will be created (and typically emailed to the Customer). That</div>

<div class="graphql-code-line top-level comment">   verificationToken would then be passed to the <code>verifyCustomerAccount</code> mutation _without_ a password. The Customer is then</div>

<div class="graphql-code-line top-level comment">   verified and authenticated in one step.</div>

<div class="graphql-code-line top-level comment">2. **The Customer is registered _without_ a password**. A verificationToken will be created (and typically emailed to the Customer). That</div>

<div class="graphql-code-line top-level comment">   verificationToken would then be passed to the <code>verifyCustomerAccount</code> mutation _with_ the chosen password of the Customer. The Customer is then</div>

<div class="graphql-code-line top-level comment">   verified and authenticated in one step.</div>

<div class="graphql-code-line top-level comment"></div>

<div class="graphql-code-line top-level comment">_If <code>authOptions.requireVerification</code> is set to `false`:_</div>

<div class="graphql-code-line top-level comment"></div>

<div class="graphql-code-line top-level comment">3. The Customer _must_ be registered _with_ a password. No further action is needed - the Customer is able to authenticate immediately.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">registerCustomerAccount(input: <a href="/reference/graphql-api/shop/input-types#registercustomerinput">RegisterCustomerInput</a>!): <a href="/reference/graphql-api/shop/object-types#registercustomeraccountresult">RegisterCustomerAccountResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## removeAllOrderLines
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Remove all OrderLine from the Order</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">removeAllOrderLines: <a href="/reference/graphql-api/shop/object-types#removeorderitemsresult">RemoveOrderItemsResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## removeCouponCode
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Removes the given coupon code from the active Order</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">removeCouponCode(couponCode: <a href="/reference/graphql-api/shop/object-types#string">String</a>!): <a href="/reference/graphql-api/shop/object-types#order">Order</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## removeOrderLine
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Remove an OrderLine from the Order</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">removeOrderLine(orderLineId: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!): <a href="/reference/graphql-api/shop/object-types#removeorderitemsresult">RemoveOrderItemsResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## requestPasswordReset
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Requests a password reset email to be sent</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">requestPasswordReset(emailAddress: <a href="/reference/graphql-api/shop/object-types#string">String</a>!): <a href="/reference/graphql-api/shop/object-types#requestpasswordresetresult">RequestPasswordResetResult</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## requestUpdateCustomerEmailAddress
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Request to update the emailAddress of the active Customer. If <code>authOptions.requireVerification</code> is enabled</div>

<div class="graphql-code-line top-level comment">(as is the default), then the <code>identifierChangeToken</code> will be assigned to the current User and</div>

<div class="graphql-code-line top-level comment">a IdentifierChangeRequestEvent will be raised. This can then be used e.g. by the EmailPlugin to email</div>

<div class="graphql-code-line top-level comment">that verification token to the Customer, which is then used to verify the change of email address.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">requestUpdateCustomerEmailAddress(password: <a href="/reference/graphql-api/shop/object-types#string">String</a>!, newEmailAddress: <a href="/reference/graphql-api/shop/object-types#string">String</a>!): <a href="/reference/graphql-api/shop/object-types#requestupdatecustomeremailaddressresult">RequestUpdateCustomerEmailAddressResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## resetPassword
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Resets a Customer's password based on the provided token</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">resetPassword(token: <a href="/reference/graphql-api/shop/object-types#string">String</a>!, password: <a href="/reference/graphql-api/shop/object-types#string">String</a>!): <a href="/reference/graphql-api/shop/object-types#resetpasswordresult">ResetPasswordResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## setCustomerForOrder
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Set the Customer for the Order. Required only if the Customer is not currently logged in</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">setCustomerForOrder(input: <a href="/reference/graphql-api/shop/input-types#createcustomerinput">CreateCustomerInput</a>!): <a href="/reference/graphql-api/shop/object-types#setcustomerfororderresult">SetCustomerForOrderResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## setOrderBillingAddress
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Sets the billing address for the active Order</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">setOrderBillingAddress(input: <a href="/reference/graphql-api/shop/input-types#createaddressinput">CreateAddressInput</a>!): <a href="/reference/graphql-api/shop/object-types#activeorderresult">ActiveOrderResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## setOrderCustomFields
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Allows any custom fields to be set for the active Order</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">setOrderCustomFields(input: <a href="/reference/graphql-api/shop/input-types#updateorderinput">UpdateOrderInput</a>!): <a href="/reference/graphql-api/shop/object-types#activeorderresult">ActiveOrderResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## setOrderShippingAddress
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Sets the shipping address for the active Order</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">setOrderShippingAddress(input: <a href="/reference/graphql-api/shop/input-types#createaddressinput">CreateAddressInput</a>!): <a href="/reference/graphql-api/shop/object-types#activeorderresult">ActiveOrderResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## setOrderShippingMethod
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Sets the shipping method by id, which can be obtained with the <code>eligibleShippingMethods</code> query.</div>

<div class="graphql-code-line top-level comment">An Order can have multiple shipping methods, in which case you can pass an array of ids. In this case,</div>

<div class="graphql-code-line top-level comment">you should configure a custom ShippingLineAssignmentStrategy in order to know which OrderLines each</div>

<div class="graphql-code-line top-level comment">shipping method will apply to.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">setOrderShippingMethod(shippingMethodId: [<a href="/reference/graphql-api/shop/object-types#id">ID</a>!]!): <a href="/reference/graphql-api/shop/object-types#setordershippingmethodresult">SetOrderShippingMethodResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## transitionOrderToState
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Transitions an Order to a new state. Valid next states can be found by querying `nextOrderStates`</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">transitionOrderToState(state: <a href="/reference/graphql-api/shop/object-types#string">String</a>!): <a href="/reference/graphql-api/shop/object-types#transitionordertostateresult">TransitionOrderToStateResult</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## unsetOrderBillingAddress
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Unsets the billing address for the active Order. Available since version 3.1.0</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">unsetOrderBillingAddress: <a href="/reference/graphql-api/shop/object-types#activeorderresult">ActiveOrderResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## unsetOrderShippingAddress
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Unsets the shipping address for the active Order. Available since version 3.1.0</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">unsetOrderShippingAddress: <a href="/reference/graphql-api/shop/object-types#activeorderresult">ActiveOrderResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## updateCustomer
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Update an existing Customer</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">updateCustomer(input: <a href="/reference/graphql-api/shop/input-types#updatecustomerinput">UpdateCustomerInput</a>!): <a href="/reference/graphql-api/shop/object-types#customer">Customer</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## updateCustomerAddress
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Update an existing Address</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">updateCustomerAddress(input: <a href="/reference/graphql-api/shop/input-types#updateaddressinput">UpdateAddressInput</a>!): <a href="/reference/graphql-api/shop/object-types#address">Address</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## updateCustomerEmailAddress
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Confirm the update of the emailAddress with the provided token, which has been generated by the</div>

<div class="graphql-code-line top-level comment">`requestUpdateCustomerEmailAddress` mutation.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">updateCustomerEmailAddress(token: <a href="/reference/graphql-api/shop/object-types#string">String</a>!): <a href="/reference/graphql-api/shop/object-types#updatecustomeremailaddressresult">UpdateCustomerEmailAddressResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## updateCustomerPassword
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Update the password of the active Customer</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">updateCustomerPassword(currentPassword: <a href="/reference/graphql-api/shop/object-types#string">String</a>!, newPassword: <a href="/reference/graphql-api/shop/object-types#string">String</a>!): <a href="/reference/graphql-api/shop/object-types#updatecustomerpasswordresult">UpdateCustomerPasswordResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## verifyCustomerAccount
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Verify a Customer email address with the token sent to that address. Only applicable if <code>authOptions.requireVerification</code> is set to true.</div>

<div class="graphql-code-line top-level comment"></div>

<div class="graphql-code-line top-level comment">If the Customer was not registered with a password in the <code>registerCustomerAccount</code> mutation, the password _must_ be</div>

<div class="graphql-code-line top-level comment">provided here.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Mutation</span> &#123;</div>
<div class="graphql-code-line ">verifyCustomerAccount(token: <a href="/reference/graphql-api/shop/object-types#string">String</a>!, password: <a href="/reference/graphql-api/shop/object-types#string">String</a>): <a href="/reference/graphql-api/shop/object-types#verifycustomeraccountresult">VerifyCustomerAccountResult</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>


---

---
title: "Types"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';



## ActiveOrderResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">ActiveOrderResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/shop/object-types#order">Order</a> | <a href="/reference/graphql-api/shop/object-types#noactiveordererror">NoActiveOrderError</a></div>
</div>

## AddPaymentToOrderResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">AddPaymentToOrderResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/shop/object-types#order">Order</a> | <a href="/reference/graphql-api/shop/object-types#orderpaymentstateerror">OrderPaymentStateError</a> | <a href="/reference/graphql-api/shop/object-types#ineligiblepaymentmethoderror">IneligiblePaymentMethodError</a> | <a href="/reference/graphql-api/shop/object-types#paymentfailederror">PaymentFailedError</a> | <a href="/reference/graphql-api/shop/object-types#paymentdeclinederror">PaymentDeclinedError</a> | <a href="/reference/graphql-api/shop/object-types#orderstatetransitionerror">OrderStateTransitionError</a> | <a href="/reference/graphql-api/shop/object-types#noactiveordererror">NoActiveOrderError</a></div>
</div>

## Address

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Address</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">fullName: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">company: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">streetLine1: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">streetLine2: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">city: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">province: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">postalCode: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">country: <a href="/reference/graphql-api/shop/object-types#country">Country</a>!</div>

<div class="graphql-code-line ">phoneNumber: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">defaultShippingAddress: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">defaultBillingAddress: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## Adjustment

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Adjustment</span> &#123;</div>
<div class="graphql-code-line ">adjustmentSource: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/shop/enums#adjustmenttype">AdjustmentType</a>!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">amount: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">data: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## AlreadyLoggedInError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned when attempting to set the Customer for an Order when already logged in.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">AlreadyLoggedInError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/shop/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ApplyCouponCodeResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">ApplyCouponCodeResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/shop/object-types#order">Order</a> | <a href="/reference/graphql-api/shop/object-types#couponcodeexpirederror">CouponCodeExpiredError</a> | <a href="/reference/graphql-api/shop/object-types#couponcodeinvaliderror">CouponCodeInvalidError</a> | <a href="/reference/graphql-api/shop/object-types#couponcodelimiterror">CouponCodeLimitError</a></div>
</div>

## Asset

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Asset</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/shop/enums#assettype">AssetType</a>!</div>

<div class="graphql-code-line ">fileSize: <a href="/reference/graphql-api/shop/object-types#int">Int</a>!</div>

<div class="graphql-code-line ">mimeType: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">width: <a href="/reference/graphql-api/shop/object-types#int">Int</a>!</div>

<div class="graphql-code-line ">height: <a href="/reference/graphql-api/shop/object-types#int">Int</a>!</div>

<div class="graphql-code-line ">source: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">preview: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">focalPoint: <a href="/reference/graphql-api/shop/object-types#coordinate">Coordinate</a></div>

<div class="graphql-code-line ">tags: [<a href="/reference/graphql-api/shop/object-types#tag">Tag</a>!]!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## AssetList

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">AssetList</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/shop/object-types#asset">Asset</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/shop/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## AuthenticationMethod

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">AuthenticationMethod</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">strategy: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## AuthenticationResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">AuthenticationResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/shop/object-types#currentuser">CurrentUser</a> | <a href="/reference/graphql-api/shop/object-types#invalidcredentialserror">InvalidCredentialsError</a> | <a href="/reference/graphql-api/shop/object-types#notverifiederror">NotVerifiedError</a></div>
</div>

## Boolean

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">The <code>Boolean</code> scalar type represents <code>true</code> or `false`.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">scalar <span class="graphql-code-identifier">Boolean</span></div>
</div>

## BooleanCustomFieldConfig

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">BooleanCustomFieldConfig</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">list: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">label: [<a href="/reference/graphql-api/shop/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">description: [<a href="/reference/graphql-api/shop/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">readonly: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">internal: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">nullable: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">requiresPermission: [<a href="/reference/graphql-api/shop/enums#permission">Permission</a>!]</div>

<div class="graphql-code-line ">ui: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## BooleanStructFieldConfig

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">BooleanStructFieldConfig</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">list: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">label: [<a href="/reference/graphql-api/shop/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">description: [<a href="/reference/graphql-api/shop/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">ui: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## Channel

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Channel</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">token: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">defaultTaxZone: <a href="/reference/graphql-api/shop/object-types#zone">Zone</a></div>

<div class="graphql-code-line ">defaultShippingZone: <a href="/reference/graphql-api/shop/object-types#zone">Zone</a></div>

<div class="graphql-code-line ">defaultLanguageCode: <a href="/reference/graphql-api/shop/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">availableLanguageCodes: [<a href="/reference/graphql-api/shop/enums#languagecode">LanguageCode</a>!]</div>

<div class="graphql-code-line ">currencyCode: <a href="/reference/graphql-api/shop/enums#currencycode">CurrencyCode</a>!</div>

<div class="graphql-code-line ">defaultCurrencyCode: <a href="/reference/graphql-api/shop/enums#currencycode">CurrencyCode</a>!</div>

<div class="graphql-code-line ">availableCurrencyCodes: [<a href="/reference/graphql-api/shop/enums#currencycode">CurrencyCode</a>!]!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Not yet used - will be implemented in a future release.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">trackInventory: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Not yet used - will be implemented in a future release.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">outOfStockThreshold: <a href="/reference/graphql-api/shop/object-types#int">Int</a></div>

<div class="graphql-code-line ">pricesIncludeTax: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">seller: <a href="/reference/graphql-api/shop/object-types#seller">Seller</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## Collection

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Collection</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/shop/enums#languagecode">LanguageCode</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">slug: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">breadcrumbs: [<a href="/reference/graphql-api/shop/object-types#collectionbreadcrumb">CollectionBreadcrumb</a>!]!</div>

<div class="graphql-code-line ">position: <a href="/reference/graphql-api/shop/object-types#int">Int</a>!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">featuredAsset: <a href="/reference/graphql-api/shop/object-types#asset">Asset</a></div>

<div class="graphql-code-line ">assets: [<a href="/reference/graphql-api/shop/object-types#asset">Asset</a>!]!</div>

<div class="graphql-code-line ">parent: <a href="/reference/graphql-api/shop/object-types#collection">Collection</a></div>

<div class="graphql-code-line ">parentId: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">children: [<a href="/reference/graphql-api/shop/object-types#collection">Collection</a>!]</div>

<div class="graphql-code-line ">filters: [<a href="/reference/graphql-api/shop/object-types#configurableoperation">ConfigurableOperation</a>!]!</div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/shop/object-types#collectiontranslation">CollectionTranslation</a>!]!</div>

<div class="graphql-code-line ">productVariants(options: <a href="/reference/graphql-api/shop/input-types#productvariantlistoptions">ProductVariantListOptions</a>): <a href="/reference/graphql-api/shop/object-types#productvariantlist">ProductVariantList</a>!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CollectionBreadcrumb

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">CollectionBreadcrumb</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">slug: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CollectionList

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">CollectionList</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/shop/object-types#collection">Collection</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/shop/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CollectionResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Which Collections are present in the products returned</div>

<div class="graphql-code-line top-level comment">by the search, and in what quantity.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">CollectionResult</span> &#123;</div>
<div class="graphql-code-line ">collection: <a href="/reference/graphql-api/shop/object-types#collection">Collection</a>!</div>

<div class="graphql-code-line ">count: <a href="/reference/graphql-api/shop/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CollectionTranslation

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">CollectionTranslation</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/shop/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">slug: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ConfigArg

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ConfigArg</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">value: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ConfigArgDefinition

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ConfigArgDefinition</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">list: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">required: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">defaultValue: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>

<div class="graphql-code-line ">label: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">ui: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ConfigurableOperation

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ConfigurableOperation</span> &#123;</div>
<div class="graphql-code-line ">code: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">args: [<a href="/reference/graphql-api/shop/object-types#configarg">ConfigArg</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ConfigurableOperationDefinition

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ConfigurableOperationDefinition</span> &#123;</div>
<div class="graphql-code-line ">code: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">args: [<a href="/reference/graphql-api/shop/object-types#configargdefinition">ConfigArgDefinition</a>!]!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## Coordinate

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Coordinate</span> &#123;</div>
<div class="graphql-code-line ">x: <a href="/reference/graphql-api/shop/object-types#float">Float</a>!</div>

<div class="graphql-code-line ">y: <a href="/reference/graphql-api/shop/object-types#float">Float</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## Country

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">A Country of the world which your shop operates in.</div>

<div class="graphql-code-line top-level comment"></div>

<div class="graphql-code-line top-level comment">The <code>code</code> field is typically a 2-character ISO code such as "GB", "US", "DE" etc. This code is used in certain inputs such as</div>

<div class="graphql-code-line top-level comment">`UpdateAddressInput` and <code>CreateAddressInput</code> to specify the country.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Country</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/shop/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">enabled: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">parent: <a href="/reference/graphql-api/shop/object-types#region">Region</a></div>

<div class="graphql-code-line ">parentId: <a href="/reference/graphql-api/shop/object-types#id">ID</a></div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/shop/object-types#regiontranslation">RegionTranslation</a>!]!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CountryList

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">CountryList</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/shop/object-types#country">Country</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/shop/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CouponCodeExpiredError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned if the provided coupon code is invalid</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">CouponCodeExpiredError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/shop/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">couponCode: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CouponCodeInvalidError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned if the provided coupon code is invalid</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">CouponCodeInvalidError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/shop/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">couponCode: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CouponCodeLimitError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned if the provided coupon code is invalid</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">CouponCodeLimitError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/shop/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">couponCode: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">limit: <a href="/reference/graphql-api/shop/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CurrentUser

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">CurrentUser</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">identifier: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">channels: [<a href="/reference/graphql-api/shop/object-types#currentuserchannel">CurrentUserChannel</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CurrentUserChannel

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">CurrentUserChannel</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">token: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">permissions: [<a href="/reference/graphql-api/shop/enums#permission">Permission</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CustomFieldConfig

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">CustomFieldConfig</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/shop/object-types#stringcustomfieldconfig">StringCustomFieldConfig</a> | <a href="/reference/graphql-api/shop/object-types#localestringcustomfieldconfig">LocaleStringCustomFieldConfig</a> | <a href="/reference/graphql-api/shop/object-types#intcustomfieldconfig">IntCustomFieldConfig</a> | <a href="/reference/graphql-api/shop/object-types#floatcustomfieldconfig">FloatCustomFieldConfig</a> | <a href="/reference/graphql-api/shop/object-types#booleancustomfieldconfig">BooleanCustomFieldConfig</a> | <a href="/reference/graphql-api/shop/object-types#datetimecustomfieldconfig">DateTimeCustomFieldConfig</a> | <a href="/reference/graphql-api/shop/object-types#relationcustomfieldconfig">RelationCustomFieldConfig</a> | <a href="/reference/graphql-api/shop/object-types#textcustomfieldconfig">TextCustomFieldConfig</a> | <a href="/reference/graphql-api/shop/object-types#localetextcustomfieldconfig">LocaleTextCustomFieldConfig</a> | <a href="/reference/graphql-api/shop/object-types#structcustomfieldconfig">StructCustomFieldConfig</a></div>
</div>

## Customer

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Customer</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">title: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">firstName: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">lastName: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">phoneNumber: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">emailAddress: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">addresses: [<a href="/reference/graphql-api/shop/object-types#address">Address</a>!]</div>

<div class="graphql-code-line ">orders(options: <a href="/reference/graphql-api/shop/input-types#orderlistoptions">OrderListOptions</a>): <a href="/reference/graphql-api/shop/object-types#orderlist">OrderList</a>!</div>

<div class="graphql-code-line ">user: <a href="/reference/graphql-api/shop/object-types#user">User</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CustomerGroup

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">CustomerGroup</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">customers(options: <a href="/reference/graphql-api/shop/input-types#customerlistoptions">CustomerListOptions</a>): <a href="/reference/graphql-api/shop/object-types#customerlist">CustomerList</a>!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## CustomerList

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">CustomerList</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/shop/object-types#customer">Customer</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/shop/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## DateTime

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">A date-time string at UTC, such as 2007-12-03T10:15:30Z, compliant with the <code>date-time</code> format outlined in section 5.6 of the RFC 3339 profile of the ISO 8601 standard for representation of dates and times using the Gregorian calendar.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">scalar <span class="graphql-code-identifier">DateTime</span></div>
</div>

## DateTimeCustomFieldConfig

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Expects the same validation formats as the <code>&lt;input type="datetime-local"&gt;</code> HTML element.</div>

<div class="graphql-code-line top-level comment">See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/datetime-local#Additional_attributes</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">DateTimeCustomFieldConfig</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">list: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">label: [<a href="/reference/graphql-api/shop/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">description: [<a href="/reference/graphql-api/shop/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">readonly: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">internal: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">nullable: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">requiresPermission: [<a href="/reference/graphql-api/shop/enums#permission">Permission</a>!]</div>

<div class="graphql-code-line ">min: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">max: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">step: <a href="/reference/graphql-api/shop/object-types#int">Int</a></div>

<div class="graphql-code-line ">ui: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## DateTimeStructFieldConfig

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Expects the same validation formats as the <code>&lt;input type="datetime-local"&gt;</code> HTML element.</div>

<div class="graphql-code-line top-level comment">See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/datetime-local#Additional_attributes</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">DateTimeStructFieldConfig</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">list: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">label: [<a href="/reference/graphql-api/shop/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">description: [<a href="/reference/graphql-api/shop/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">min: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">max: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">step: <a href="/reference/graphql-api/shop/object-types#int">Int</a></div>

<div class="graphql-code-line ">ui: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## DeletionResponse

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">DeletionResponse</span> &#123;</div>
<div class="graphql-code-line ">result: <a href="/reference/graphql-api/shop/enums#deletionresult">DeletionResult</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## Discount

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Discount</span> &#123;</div>
<div class="graphql-code-line ">adjustmentSource: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/shop/enums#adjustmenttype">AdjustmentType</a>!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">amount: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">amountWithTax: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## EmailAddressConflictError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned when attempting to create a Customer with an email address already registered to an existing User.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">EmailAddressConflictError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/shop/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## Facet

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Facet</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/shop/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">values: [<a href="/reference/graphql-api/shop/object-types#facetvalue">FacetValue</a>!]!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Returns a paginated, sortable, filterable list of the Facet's values. Added in v2.1.0.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">valueList(options: <a href="/reference/graphql-api/shop/input-types#facetvaluelistoptions">FacetValueListOptions</a>): <a href="/reference/graphql-api/shop/object-types#facetvaluelist">FacetValueList</a>!</div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/shop/object-types#facettranslation">FacetTranslation</a>!]!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## FacetList

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">FacetList</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/shop/object-types#facet">Facet</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/shop/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## FacetTranslation

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">FacetTranslation</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/shop/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## FacetValue

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">FacetValue</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/shop/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">facet: <a href="/reference/graphql-api/shop/object-types#facet">Facet</a>!</div>

<div class="graphql-code-line ">facetId: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/shop/object-types#facetvaluetranslation">FacetValueTranslation</a>!]!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## FacetValueList

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">FacetValueList</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/shop/object-types#facetvalue">FacetValue</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/shop/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## FacetValueResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Which FacetValues are present in the products returned</div>

<div class="graphql-code-line top-level comment">by the search, and in what quantity.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">FacetValueResult</span> &#123;</div>
<div class="graphql-code-line ">facetValue: <a href="/reference/graphql-api/shop/object-types#facetvalue">FacetValue</a>!</div>

<div class="graphql-code-line ">count: <a href="/reference/graphql-api/shop/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## FacetValueTranslation

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">FacetValueTranslation</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/shop/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## Float

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">The <code>Float</code> scalar type represents signed double-precision fractional values as specified by [IEEE 754](https://en.wikipedia.org/wiki/IEEE_floating_point).</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">scalar <span class="graphql-code-identifier">Float</span></div>
</div>

## FloatCustomFieldConfig

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">FloatCustomFieldConfig</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">list: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">label: [<a href="/reference/graphql-api/shop/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">description: [<a href="/reference/graphql-api/shop/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">readonly: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">internal: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">nullable: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">requiresPermission: [<a href="/reference/graphql-api/shop/enums#permission">Permission</a>!]</div>

<div class="graphql-code-line ">min: <a href="/reference/graphql-api/shop/object-types#float">Float</a></div>

<div class="graphql-code-line ">max: <a href="/reference/graphql-api/shop/object-types#float">Float</a></div>

<div class="graphql-code-line ">step: <a href="/reference/graphql-api/shop/object-types#float">Float</a></div>

<div class="graphql-code-line ">ui: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## FloatStructFieldConfig

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">FloatStructFieldConfig</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">list: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">label: [<a href="/reference/graphql-api/shop/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">description: [<a href="/reference/graphql-api/shop/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">min: <a href="/reference/graphql-api/shop/object-types#float">Float</a></div>

<div class="graphql-code-line ">max: <a href="/reference/graphql-api/shop/object-types#float">Float</a></div>

<div class="graphql-code-line ">step: <a href="/reference/graphql-api/shop/object-types#float">Float</a></div>

<div class="graphql-code-line ">ui: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## Fulfillment

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Fulfillment</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">lines: [<a href="/reference/graphql-api/shop/object-types#fulfillmentline">FulfillmentLine</a>!]!</div>

<div class="graphql-code-line ">summary: [<a href="/reference/graphql-api/shop/object-types#fulfillmentline">FulfillmentLine</a>!]!</div>

<div class="graphql-code-line ">state: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">method: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">trackingCode: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## FulfillmentLine

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">FulfillmentLine</span> &#123;</div>
<div class="graphql-code-line ">orderLine: <a href="/reference/graphql-api/shop/object-types#orderline">OrderLine</a>!</div>

<div class="graphql-code-line ">orderLineId: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">quantity: <a href="/reference/graphql-api/shop/object-types#int">Int</a>!</div>

<div class="graphql-code-line ">fulfillment: <a href="/reference/graphql-api/shop/object-types#fulfillment">Fulfillment</a>!</div>

<div class="graphql-code-line ">fulfillmentId: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## GuestCheckoutError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned when attempting to set the Customer on a guest checkout when the configured GuestCheckoutStrategy does not allow it.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">GuestCheckoutError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/shop/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">errorDetail: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## HistoryEntry

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">HistoryEntry</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/shop/enums#historyentrytype">HistoryEntryType</a>!</div>

<div class="graphql-code-line ">data: <a href="/reference/graphql-api/shop/object-types#json">JSON</a>!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## HistoryEntryList

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">HistoryEntryList</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/shop/object-types#historyentry">HistoryEntry</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/shop/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ID

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">The <code>ID</code> scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `"4"`) or integer (such as `4`) input value will be accepted as an ID.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">scalar <span class="graphql-code-identifier">ID</span></div>
</div>

## IdentifierChangeTokenExpiredError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned if the token used to change a Customer's email address is valid, but has</div>

<div class="graphql-code-line top-level comment">expired according to the <code>verificationTokenDuration</code> setting in the AuthOptions.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">IdentifierChangeTokenExpiredError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/shop/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## IdentifierChangeTokenInvalidError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned if the token used to change a Customer's email address is either</div>

<div class="graphql-code-line top-level comment">invalid or does not match any expected tokens.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">IdentifierChangeTokenInvalidError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/shop/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## IneligiblePaymentMethodError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned when attempting to add a Payment using a PaymentMethod for which the Order is not eligible.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">IneligiblePaymentMethodError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/shop/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">eligibilityCheckerMessage: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## IneligibleShippingMethodError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned when attempting to set a ShippingMethod for which the Order is not eligible</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">IneligibleShippingMethodError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/shop/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## InsufficientStockError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned when attempting to add more items to the Order than are available</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">InsufficientStockError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/shop/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">quantityAvailable: <a href="/reference/graphql-api/shop/object-types#int">Int</a>!</div>

<div class="graphql-code-line ">order: <a href="/reference/graphql-api/shop/object-types#order">Order</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## Int

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">The <code>Int</code> scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">scalar <span class="graphql-code-identifier">Int</span></div>
</div>

## IntCustomFieldConfig

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">IntCustomFieldConfig</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">list: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">label: [<a href="/reference/graphql-api/shop/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">description: [<a href="/reference/graphql-api/shop/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">readonly: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">internal: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">nullable: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">requiresPermission: [<a href="/reference/graphql-api/shop/enums#permission">Permission</a>!]</div>

<div class="graphql-code-line ">min: <a href="/reference/graphql-api/shop/object-types#int">Int</a></div>

<div class="graphql-code-line ">max: <a href="/reference/graphql-api/shop/object-types#int">Int</a></div>

<div class="graphql-code-line ">step: <a href="/reference/graphql-api/shop/object-types#int">Int</a></div>

<div class="graphql-code-line ">ui: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## IntStructFieldConfig

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">IntStructFieldConfig</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">list: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">label: [<a href="/reference/graphql-api/shop/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">description: [<a href="/reference/graphql-api/shop/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">min: <a href="/reference/graphql-api/shop/object-types#int">Int</a></div>

<div class="graphql-code-line ">max: <a href="/reference/graphql-api/shop/object-types#int">Int</a></div>

<div class="graphql-code-line ">step: <a href="/reference/graphql-api/shop/object-types#int">Int</a></div>

<div class="graphql-code-line ">ui: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## InvalidCredentialsError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned if the user authentication credentials are not valid</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">InvalidCredentialsError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/shop/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">authenticationError: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## JSON

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">The <code>JSON</code> scalar type represents JSON values as specified by [ECMA-404](http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf).</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">scalar <span class="graphql-code-identifier">JSON</span></div>
</div>

## LocaleStringCustomFieldConfig

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">LocaleStringCustomFieldConfig</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">list: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">length: <a href="/reference/graphql-api/shop/object-types#int">Int</a></div>

<div class="graphql-code-line ">label: [<a href="/reference/graphql-api/shop/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">description: [<a href="/reference/graphql-api/shop/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">readonly: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">internal: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">nullable: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">requiresPermission: [<a href="/reference/graphql-api/shop/enums#permission">Permission</a>!]</div>

<div class="graphql-code-line ">pattern: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">ui: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## LocaleTextCustomFieldConfig

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">LocaleTextCustomFieldConfig</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">list: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">label: [<a href="/reference/graphql-api/shop/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">description: [<a href="/reference/graphql-api/shop/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">readonly: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">internal: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">nullable: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">requiresPermission: [<a href="/reference/graphql-api/shop/enums#permission">Permission</a>!]</div>

<div class="graphql-code-line ">ui: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## LocalizedString

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">LocalizedString</span> &#123;</div>
<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/shop/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">value: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## MissingPasswordError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned when attempting to register or verify a customer account without a password, when one is required.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">MissingPasswordError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/shop/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## Money

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">The <code>Money</code> scalar type represents monetary values and supports signed double-precision fractional values as specified by [IEEE 754](https://en.wikipedia.org/wiki/IEEE_floating_point).</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">scalar <span class="graphql-code-identifier">Money</span></div>
</div>

## NativeAuthStrategyError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned when attempting an operation that relies on the NativeAuthStrategy, if that strategy is not configured.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">NativeAuthStrategyError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/shop/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## NativeAuthenticationResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">NativeAuthenticationResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/shop/object-types#currentuser">CurrentUser</a> | <a href="/reference/graphql-api/shop/object-types#invalidcredentialserror">InvalidCredentialsError</a> | <a href="/reference/graphql-api/shop/object-types#notverifiederror">NotVerifiedError</a> | <a href="/reference/graphql-api/shop/object-types#nativeauthstrategyerror">NativeAuthStrategyError</a></div>
</div>

## NegativeQuantityError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned when attempting to set a negative OrderLine quantity.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">NegativeQuantityError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/shop/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## NoActiveOrderError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned when invoking a mutation which depends on there being an active Order on the</div>

<div class="graphql-code-line top-level comment">current session.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">NoActiveOrderError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/shop/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## NotVerifiedError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned if <code>authOptions.requireVerification</code> is set to <code>true</code> (which is the default)</div>

<div class="graphql-code-line top-level comment">and an unverified user attempts to authenticate.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">NotVerifiedError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/shop/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## Order

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Order</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/shop/enums#ordertype">OrderType</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The date & time that the Order was placed, i.e. the Customer</div>

<div class="graphql-code-line comment">completed the checkout and the Order is no longer "active"</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">orderPlacedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">A unique code for the Order</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">code: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">state: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">An order is active as long as the payment process has not been completed</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">active: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">customer: <a href="/reference/graphql-api/shop/object-types#customer">Customer</a></div>

<div class="graphql-code-line ">shippingAddress: <a href="/reference/graphql-api/shop/object-types#orderaddress">OrderAddress</a></div>

<div class="graphql-code-line ">billingAddress: <a href="/reference/graphql-api/shop/object-types#orderaddress">OrderAddress</a></div>

<div class="graphql-code-line ">lines: [<a href="/reference/graphql-api/shop/object-types#orderline">OrderLine</a>!]!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Surcharges are arbitrary modifications to the Order total which are neither</div>

<div class="graphql-code-line comment">ProductVariants nor discounts resulting from applied Promotions. For example,</div>

<div class="graphql-code-line comment">one-off discounts based on customer interaction, or surcharges based on payment</div>

<div class="graphql-code-line comment">methods.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">surcharges: [<a href="/reference/graphql-api/shop/object-types#surcharge">Surcharge</a>!]!</div>

<div class="graphql-code-line ">discounts: [<a href="/reference/graphql-api/shop/object-types#discount">Discount</a>!]!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">An array of all coupon codes applied to the Order</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">couponCodes: [<a href="/reference/graphql-api/shop/object-types#string">String</a>!]!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Promotions applied to the order. Only gets populated after the payment process has completed.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">promotions: [<a href="/reference/graphql-api/shop/object-types#promotion">Promotion</a>!]!</div>

<div class="graphql-code-line ">payments: [<a href="/reference/graphql-api/shop/object-types#payment">Payment</a>!]</div>

<div class="graphql-code-line ">fulfillments: [<a href="/reference/graphql-api/shop/object-types#fulfillment">Fulfillment</a>!]</div>

<div class="graphql-code-line ">totalQuantity: <a href="/reference/graphql-api/shop/object-types#int">Int</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The subTotal is the total of all OrderLines in the Order. This figure also includes any Order-level</div>

<div class="graphql-code-line comment">discounts which have been prorated (proportionally distributed) amongst the items of each OrderLine.</div>

<div class="graphql-code-line comment">To get a total of all OrderLines which does not account for prorated discounts, use the</div>

<div class="graphql-code-line comment">sum of <code>OrderLine.discountedLinePrice</code> values.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">subTotal: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Same as subTotal, but inclusive of tax</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">subTotalWithTax: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">currencyCode: <a href="/reference/graphql-api/shop/enums#currencycode">CurrencyCode</a>!</div>

<div class="graphql-code-line ">shippingLines: [<a href="/reference/graphql-api/shop/object-types#shippingline">ShippingLine</a>!]!</div>

<div class="graphql-code-line ">shipping: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">shippingWithTax: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Equal to subTotal plus shipping</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">total: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The final payable amount. Equal to subTotalWithTax plus shippingWithTax</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">totalWithTax: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">A summary of the taxes being applied to this Order</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">taxSummary: [<a href="/reference/graphql-api/shop/object-types#ordertaxsummary">OrderTaxSummary</a>!]!</div>

<div class="graphql-code-line ">history(options: <a href="/reference/graphql-api/shop/input-types#historyentrylistoptions">HistoryEntryListOptions</a>): <a href="/reference/graphql-api/shop/object-types#historyentrylist">HistoryEntryList</a>!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## OrderAddress

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">OrderAddress</span> &#123;</div>
<div class="graphql-code-line ">fullName: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">company: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">streetLine1: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">streetLine2: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">city: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">province: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">postalCode: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">country: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">countryCode: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">phoneNumber: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## OrderInterceptorError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned when an order operation is rejected by an OrderInterceptor method.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">OrderInterceptorError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/shop/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">interceptorError: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## OrderLimitError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned when the maximum order size limit has been reached.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">OrderLimitError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/shop/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">maxItems: <a href="/reference/graphql-api/shop/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## OrderLine

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">OrderLine</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">productVariant: <a href="/reference/graphql-api/shop/object-types#productvariant">ProductVariant</a>!</div>

<div class="graphql-code-line ">featuredAsset: <a href="/reference/graphql-api/shop/object-types#asset">Asset</a></div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The price of a single unit, excluding tax and discounts</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">unitPrice: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The price of a single unit, including tax but excluding discounts</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">unitPriceWithTax: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Non-zero if the unitPrice has changed since it was initially added to Order</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">unitPriceChangeSinceAdded: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Non-zero if the unitPriceWithTax has changed since it was initially added to Order</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">unitPriceWithTaxChangeSinceAdded: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The price of a single unit including discounts, excluding tax.</div>

<div class="graphql-code-line comment"></div>

<div class="graphql-code-line comment">If Order-level discounts have been applied, this will not be the</div>

<div class="graphql-code-line comment">actual taxable unit price (see `proratedUnitPrice`), but is generally the</div>

<div class="graphql-code-line comment">correct price to display to customers to avoid confusion</div>

<div class="graphql-code-line comment">about the internal handling of distributed Order-level discounts.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">discountedUnitPrice: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The price of a single unit including discounts and tax</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">discountedUnitPriceWithTax: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The actual unit price, taking into account both item discounts _and_ prorated (proportionally-distributed)</div>

<div class="graphql-code-line comment">Order-level discounts. This value is the true economic value of the OrderItem, and is used in tax</div>

<div class="graphql-code-line comment">and refund calculations.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">proratedUnitPrice: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The proratedUnitPrice including tax</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">proratedUnitPriceWithTax: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The quantity of items purchased</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">quantity: <a href="/reference/graphql-api/shop/object-types#int">Int</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The quantity at the time the Order was placed</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">orderPlacedQuantity: <a href="/reference/graphql-api/shop/object-types#int">Int</a>!</div>

<div class="graphql-code-line ">taxRate: <a href="/reference/graphql-api/shop/object-types#float">Float</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The total price of the line excluding tax and discounts.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">linePrice: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The total price of the line including tax but excluding discounts.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">linePriceWithTax: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The price of the line including discounts, excluding tax</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">discountedLinePrice: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The price of the line including discounts and tax</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">discountedLinePriceWithTax: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The actual line price, taking into account both item discounts _and_ prorated (proportionally-distributed)</div>

<div class="graphql-code-line comment">Order-level discounts. This value is the true economic value of the OrderLine, and is used in tax</div>

<div class="graphql-code-line comment">and refund calculations.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">proratedLinePrice: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The proratedLinePrice including tax</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">proratedLinePriceWithTax: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The total tax on this line</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">lineTax: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">discounts: [<a href="/reference/graphql-api/shop/object-types#discount">Discount</a>!]!</div>

<div class="graphql-code-line ">taxLines: [<a href="/reference/graphql-api/shop/object-types#taxline">TaxLine</a>!]!</div>

<div class="graphql-code-line ">order: <a href="/reference/graphql-api/shop/object-types#order">Order</a>!</div>

<div class="graphql-code-line ">fulfillmentLines: [<a href="/reference/graphql-api/shop/object-types#fulfillmentline">FulfillmentLine</a>!]</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## OrderList

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">OrderList</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/shop/object-types#order">Order</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/shop/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## OrderModificationError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned when attempting to modify the contents of an Order that is not in the <code>AddingItems</code> state.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">OrderModificationError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/shop/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## OrderPaymentStateError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned when attempting to add a Payment to an Order that is not in the <code>ArrangingPayment</code> state.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">OrderPaymentStateError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/shop/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## OrderStateTransitionError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned if there is an error in transitioning the Order state</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">OrderStateTransitionError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/shop/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">transitionError: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">fromState: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">toState: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## OrderTaxSummary

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">A summary of the taxes being applied to this order, grouped</div>

<div class="graphql-code-line top-level comment">by taxRate.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">OrderTaxSummary</span> &#123;</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">A description of this tax</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">description: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The taxRate as a percentage</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">taxRate: <a href="/reference/graphql-api/shop/object-types#float">Float</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The total net price of OrderLines to which this taxRate applies</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">taxBase: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The total tax being applied to the Order at this taxRate</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">taxTotal: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## PasswordAlreadySetError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned when attempting to verify a customer account with a password, when a password has already been set.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">PasswordAlreadySetError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/shop/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## PasswordResetTokenExpiredError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned if the token used to reset a Customer's password is valid, but has</div>

<div class="graphql-code-line top-level comment">expired according to the <code>verificationTokenDuration</code> setting in the AuthOptions.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">PasswordResetTokenExpiredError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/shop/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## PasswordResetTokenInvalidError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned if the token used to reset a Customer's password is either</div>

<div class="graphql-code-line top-level comment">invalid or does not match any expected tokens.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">PasswordResetTokenInvalidError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/shop/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## PasswordValidationError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned when attempting to register or verify a customer account where the given password fails password validation.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">PasswordValidationError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/shop/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">validationErrorMessage: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## Payment

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Payment</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">method: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">amount: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">state: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">transactionId: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">errorMessage: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">refunds: [<a href="/reference/graphql-api/shop/object-types#refund">Refund</a>!]!</div>

<div class="graphql-code-line ">metadata: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## PaymentDeclinedError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned when a Payment is declined by the payment provider.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">PaymentDeclinedError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/shop/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">paymentErrorMessage: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## PaymentFailedError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned when a Payment fails due to an error.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">PaymentFailedError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/shop/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">paymentErrorMessage: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## PaymentMethod

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">PaymentMethod</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">enabled: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">checker: <a href="/reference/graphql-api/shop/object-types#configurableoperation">ConfigurableOperation</a></div>

<div class="graphql-code-line ">handler: <a href="/reference/graphql-api/shop/object-types#configurableoperation">ConfigurableOperation</a>!</div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/shop/object-types#paymentmethodtranslation">PaymentMethodTranslation</a>!]!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## PaymentMethodQuote

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">PaymentMethodQuote</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">isEligible: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">eligibilityMessage: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## PaymentMethodTranslation

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">PaymentMethodTranslation</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/shop/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## PriceRange

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">The price range where the result has more than one price</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">PriceRange</span> &#123;</div>
<div class="graphql-code-line ">min: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">max: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## Product

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Product</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/shop/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">slug: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">enabled: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">featuredAsset: <a href="/reference/graphql-api/shop/object-types#asset">Asset</a></div>

<div class="graphql-code-line ">assets: [<a href="/reference/graphql-api/shop/object-types#asset">Asset</a>!]!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Returns all ProductVariants</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">variants: [<a href="/reference/graphql-api/shop/object-types#productvariant">ProductVariant</a>!]!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Returns a paginated, sortable, filterable list of ProductVariants</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">variantList(options: <a href="/reference/graphql-api/shop/input-types#productvariantlistoptions">ProductVariantListOptions</a>): <a href="/reference/graphql-api/shop/object-types#productvariantlist">ProductVariantList</a>!</div>

<div class="graphql-code-line ">optionGroups: [<a href="/reference/graphql-api/shop/object-types#productoptiongroup">ProductOptionGroup</a>!]!</div>

<div class="graphql-code-line ">facetValues: [<a href="/reference/graphql-api/shop/object-types#facetvalue">FacetValue</a>!]!</div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/shop/object-types#producttranslation">ProductTranslation</a>!]!</div>

<div class="graphql-code-line ">collections: [<a href="/reference/graphql-api/shop/object-types#collection">Collection</a>!]!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ProductList

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ProductList</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/shop/object-types#product">Product</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/shop/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ProductOption

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ProductOption</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/shop/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">groupId: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">group: <a href="/reference/graphql-api/shop/object-types#productoptiongroup">ProductOptionGroup</a>!</div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/shop/object-types#productoptiontranslation">ProductOptionTranslation</a>!]!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ProductOptionGroup

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ProductOptionGroup</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/shop/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">options: [<a href="/reference/graphql-api/shop/object-types#productoption">ProductOption</a>!]!</div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/shop/object-types#productoptiongrouptranslation">ProductOptionGroupTranslation</a>!]!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ProductOptionGroupTranslation

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ProductOptionGroupTranslation</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/shop/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ProductOptionTranslation

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ProductOptionTranslation</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/shop/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ProductTranslation

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ProductTranslation</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/shop/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">slug: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ProductVariant

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ProductVariant</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">product: <a href="/reference/graphql-api/shop/object-types#product">Product</a>!</div>

<div class="graphql-code-line ">productId: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/shop/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">sku: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">featuredAsset: <a href="/reference/graphql-api/shop/object-types#asset">Asset</a></div>

<div class="graphql-code-line ">assets: [<a href="/reference/graphql-api/shop/object-types#asset">Asset</a>!]!</div>

<div class="graphql-code-line ">price: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">currencyCode: <a href="/reference/graphql-api/shop/enums#currencycode">CurrencyCode</a>!</div>

<div class="graphql-code-line ">priceWithTax: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">stockLevel: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">taxRateApplied: <a href="/reference/graphql-api/shop/object-types#taxrate">TaxRate</a>!</div>

<div class="graphql-code-line ">taxCategory: <a href="/reference/graphql-api/shop/object-types#taxcategory">TaxCategory</a>!</div>

<div class="graphql-code-line ">options: [<a href="/reference/graphql-api/shop/object-types#productoption">ProductOption</a>!]!</div>

<div class="graphql-code-line ">facetValues: [<a href="/reference/graphql-api/shop/object-types#facetvalue">FacetValue</a>!]!</div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/shop/object-types#productvarianttranslation">ProductVariantTranslation</a>!]!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ProductVariantList

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ProductVariantList</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/shop/object-types#productvariant">ProductVariant</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/shop/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ProductVariantTranslation

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ProductVariantTranslation</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/shop/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## Promotion

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Promotion</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">startsAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a></div>

<div class="graphql-code-line ">endsAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a></div>

<div class="graphql-code-line ">couponCode: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">perCustomerUsageLimit: <a href="/reference/graphql-api/shop/object-types#int">Int</a></div>

<div class="graphql-code-line ">usageLimit: <a href="/reference/graphql-api/shop/object-types#int">Int</a></div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">enabled: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">conditions: [<a href="/reference/graphql-api/shop/object-types#configurableoperation">ConfigurableOperation</a>!]!</div>

<div class="graphql-code-line ">actions: [<a href="/reference/graphql-api/shop/object-types#configurableoperation">ConfigurableOperation</a>!]!</div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/shop/object-types#promotiontranslation">PromotionTranslation</a>!]!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## PromotionList

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">PromotionList</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/shop/object-types#promotion">Promotion</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/shop/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## PromotionTranslation

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">PromotionTranslation</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/shop/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## Province

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Province</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/shop/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">enabled: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">parent: <a href="/reference/graphql-api/shop/object-types#region">Region</a></div>

<div class="graphql-code-line ">parentId: <a href="/reference/graphql-api/shop/object-types#id">ID</a></div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/shop/object-types#regiontranslation">RegionTranslation</a>!]!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ProvinceList

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ProvinceList</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/shop/object-types#province">Province</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/shop/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## PublicPaymentMethod

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">PublicPaymentMethod</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/shop/object-types#paymentmethodtranslation">PaymentMethodTranslation</a>!]!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## PublicShippingMethod

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">PublicShippingMethod</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/shop/object-types#shippingmethodtranslation">ShippingMethodTranslation</a>!]!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## RefreshCustomerVerificationResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">RefreshCustomerVerificationResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/shop/object-types#success">Success</a> | <a href="/reference/graphql-api/shop/object-types#nativeauthstrategyerror">NativeAuthStrategyError</a></div>
</div>

## Refund

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Refund</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">items: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">shipping: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">adjustment: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">total: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">method: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">state: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">transactionId: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">reason: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">lines: [<a href="/reference/graphql-api/shop/object-types#refundline">RefundLine</a>!]!</div>

<div class="graphql-code-line ">paymentId: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">metadata: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## RefundLine

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">RefundLine</span> &#123;</div>
<div class="graphql-code-line ">orderLine: <a href="/reference/graphql-api/shop/object-types#orderline">OrderLine</a>!</div>

<div class="graphql-code-line ">orderLineId: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">quantity: <a href="/reference/graphql-api/shop/object-types#int">Int</a>!</div>

<div class="graphql-code-line ">refund: <a href="/reference/graphql-api/shop/object-types#refund">Refund</a>!</div>

<div class="graphql-code-line ">refundId: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## RegionTranslation

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">RegionTranslation</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/shop/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## RegisterCustomerAccountResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">RegisterCustomerAccountResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/shop/object-types#success">Success</a> | <a href="/reference/graphql-api/shop/object-types#missingpassworderror">MissingPasswordError</a> | <a href="/reference/graphql-api/shop/object-types#passwordvalidationerror">PasswordValidationError</a> | <a href="/reference/graphql-api/shop/object-types#nativeauthstrategyerror">NativeAuthStrategyError</a></div>
</div>

## RelationCustomFieldConfig

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">RelationCustomFieldConfig</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">list: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">label: [<a href="/reference/graphql-api/shop/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">description: [<a href="/reference/graphql-api/shop/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">readonly: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">internal: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">nullable: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">requiresPermission: [<a href="/reference/graphql-api/shop/enums#permission">Permission</a>!]</div>

<div class="graphql-code-line ">entity: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">scalarFields: [<a href="/reference/graphql-api/shop/object-types#string">String</a>!]!</div>

<div class="graphql-code-line ">ui: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## RemoveOrderItemsResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">RemoveOrderItemsResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/shop/object-types#order">Order</a> | <a href="/reference/graphql-api/shop/object-types#ordermodificationerror">OrderModificationError</a> | <a href="/reference/graphql-api/shop/object-types#orderinterceptorerror">OrderInterceptorError</a></div>
</div>

## RequestPasswordResetResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">RequestPasswordResetResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/shop/object-types#success">Success</a> | <a href="/reference/graphql-api/shop/object-types#nativeauthstrategyerror">NativeAuthStrategyError</a></div>
</div>

## RequestUpdateCustomerEmailAddressResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">RequestUpdateCustomerEmailAddressResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/shop/object-types#success">Success</a> | <a href="/reference/graphql-api/shop/object-types#invalidcredentialserror">InvalidCredentialsError</a> | <a href="/reference/graphql-api/shop/object-types#emailaddressconflicterror">EmailAddressConflictError</a> | <a href="/reference/graphql-api/shop/object-types#nativeauthstrategyerror">NativeAuthStrategyError</a></div>
</div>

## ResetPasswordResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">ResetPasswordResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/shop/object-types#currentuser">CurrentUser</a> | <a href="/reference/graphql-api/shop/object-types#passwordresettokeninvaliderror">PasswordResetTokenInvalidError</a> | <a href="/reference/graphql-api/shop/object-types#passwordresettokenexpirederror">PasswordResetTokenExpiredError</a> | <a href="/reference/graphql-api/shop/object-types#passwordvalidationerror">PasswordValidationError</a> | <a href="/reference/graphql-api/shop/object-types#nativeauthstrategyerror">NativeAuthStrategyError</a> | <a href="/reference/graphql-api/shop/object-types#notverifiederror">NotVerifiedError</a></div>
</div>

## Role

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Role</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">permissions: [<a href="/reference/graphql-api/shop/enums#permission">Permission</a>!]!</div>

<div class="graphql-code-line ">channels: [<a href="/reference/graphql-api/shop/object-types#channel">Channel</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## RoleList

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">RoleList</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/shop/object-types#role">Role</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/shop/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## SearchReindexResponse

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">SearchReindexResponse</span> &#123;</div>
<div class="graphql-code-line ">success: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## SearchResponse

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">SearchResponse</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/shop/object-types#searchresult">SearchResult</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/shop/object-types#int">Int</a>!</div>

<div class="graphql-code-line ">facetValues: [<a href="/reference/graphql-api/shop/object-types#facetvalueresult">FacetValueResult</a>!]!</div>

<div class="graphql-code-line ">collections: [<a href="/reference/graphql-api/shop/object-types#collectionresult">CollectionResult</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## SearchResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">SearchResult</span> &#123;</div>
<div class="graphql-code-line ">sku: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">slug: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">productId: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">productName: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">productAsset: <a href="/reference/graphql-api/shop/object-types#searchresultasset">SearchResultAsset</a></div>

<div class="graphql-code-line ">productVariantId: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">productVariantName: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">productVariantAsset: <a href="/reference/graphql-api/shop/object-types#searchresultasset">SearchResultAsset</a></div>

<div class="graphql-code-line ">price: <a href="/reference/graphql-api/shop/object-types#searchresultprice">SearchResultPrice</a>!</div>

<div class="graphql-code-line ">priceWithTax: <a href="/reference/graphql-api/shop/object-types#searchresultprice">SearchResultPrice</a>!</div>

<div class="graphql-code-line ">currencyCode: <a href="/reference/graphql-api/shop/enums#currencycode">CurrencyCode</a>!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">facetIds: [<a href="/reference/graphql-api/shop/object-types#id">ID</a>!]!</div>

<div class="graphql-code-line ">facetValueIds: [<a href="/reference/graphql-api/shop/object-types#id">ID</a>!]!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">An array of ids of the Collections in which this result appears</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">collectionIds: [<a href="/reference/graphql-api/shop/object-types#id">ID</a>!]!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">A relevance score for the result. Differs between database implementations</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">score: <a href="/reference/graphql-api/shop/object-types#float">Float</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## SearchResultAsset

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">SearchResultAsset</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">preview: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">focalPoint: <a href="/reference/graphql-api/shop/object-types#coordinate">Coordinate</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## SearchResultPrice

<div class="graphql-code-block">
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">The price of a search result product, either as a range or as a single price</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">SearchResultPrice</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/shop/object-types#pricerange">PriceRange</a> | <a href="/reference/graphql-api/shop/object-types#singleprice">SinglePrice</a></div>
</div>

## Seller

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Seller</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## SetCustomerForOrderResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">SetCustomerForOrderResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/shop/object-types#order">Order</a> | <a href="/reference/graphql-api/shop/object-types#alreadyloggedinerror">AlreadyLoggedInError</a> | <a href="/reference/graphql-api/shop/object-types#emailaddressconflicterror">EmailAddressConflictError</a> | <a href="/reference/graphql-api/shop/object-types#noactiveordererror">NoActiveOrderError</a> | <a href="/reference/graphql-api/shop/object-types#guestcheckouterror">GuestCheckoutError</a></div>
</div>

## SetOrderShippingMethodResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">SetOrderShippingMethodResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/shop/object-types#order">Order</a> | <a href="/reference/graphql-api/shop/object-types#ordermodificationerror">OrderModificationError</a> | <a href="/reference/graphql-api/shop/object-types#ineligibleshippingmethoderror">IneligibleShippingMethodError</a> | <a href="/reference/graphql-api/shop/object-types#noactiveordererror">NoActiveOrderError</a></div>
</div>

## ShippingLine

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ShippingLine</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">shippingMethod: <a href="/reference/graphql-api/shop/object-types#shippingmethod">ShippingMethod</a>!</div>

<div class="graphql-code-line ">price: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">priceWithTax: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">discountedPrice: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">discountedPriceWithTax: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">discounts: [<a href="/reference/graphql-api/shop/object-types#discount">Discount</a>!]!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ShippingMethod

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ShippingMethod</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/shop/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">fulfillmentHandlerCode: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">checker: <a href="/reference/graphql-api/shop/object-types#configurableoperation">ConfigurableOperation</a>!</div>

<div class="graphql-code-line ">calculator: <a href="/reference/graphql-api/shop/object-types#configurableoperation">ConfigurableOperation</a>!</div>

<div class="graphql-code-line ">translations: [<a href="/reference/graphql-api/shop/object-types#shippingmethodtranslation">ShippingMethodTranslation</a>!]!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ShippingMethodList

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ShippingMethodList</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/shop/object-types#shippingmethod">ShippingMethod</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/shop/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ShippingMethodQuote

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ShippingMethodQuote</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">price: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">priceWithTax: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">code: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Any optional metadata returned by the ShippingCalculator in the ShippingCalculationResult</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line ">metadata: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## ShippingMethodTranslation

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">ShippingMethodTranslation</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">languageCode: <a href="/reference/graphql-api/shop/enums#languagecode">LanguageCode</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## SinglePrice

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">The price value where the result has a single price</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">SinglePrice</span> &#123;</div>
<div class="graphql-code-line ">value: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## String

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">The <code>String</code> scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">scalar <span class="graphql-code-identifier">String</span></div>
</div>

## StringCustomFieldConfig

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">StringCustomFieldConfig</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">list: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">length: <a href="/reference/graphql-api/shop/object-types#int">Int</a></div>

<div class="graphql-code-line ">label: [<a href="/reference/graphql-api/shop/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">description: [<a href="/reference/graphql-api/shop/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">readonly: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">internal: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">nullable: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">requiresPermission: [<a href="/reference/graphql-api/shop/enums#permission">Permission</a>!]</div>

<div class="graphql-code-line ">pattern: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">options: [<a href="/reference/graphql-api/shop/object-types#stringfieldoption">StringFieldOption</a>!]</div>

<div class="graphql-code-line ">ui: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## StringFieldOption

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">StringFieldOption</span> &#123;</div>
<div class="graphql-code-line ">value: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">label: [<a href="/reference/graphql-api/shop/object-types#localizedstring">LocalizedString</a>!]</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## StringStructFieldConfig

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">StringStructFieldConfig</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">list: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">label: [<a href="/reference/graphql-api/shop/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">description: [<a href="/reference/graphql-api/shop/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">length: <a href="/reference/graphql-api/shop/object-types#int">Int</a></div>

<div class="graphql-code-line ">pattern: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">options: [<a href="/reference/graphql-api/shop/object-types#stringfieldoption">StringFieldOption</a>!]</div>

<div class="graphql-code-line ">ui: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## StructCustomFieldConfig

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">StructCustomFieldConfig</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">list: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">fields: [<a href="/reference/graphql-api/shop/object-types#structfieldconfig">StructFieldConfig</a>!]!</div>

<div class="graphql-code-line ">label: [<a href="/reference/graphql-api/shop/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">description: [<a href="/reference/graphql-api/shop/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">readonly: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">internal: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">nullable: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">requiresPermission: [<a href="/reference/graphql-api/shop/enums#permission">Permission</a>!]</div>

<div class="graphql-code-line ">ui: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## StructFieldConfig

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">StructFieldConfig</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/shop/object-types#stringstructfieldconfig">StringStructFieldConfig</a> | <a href="/reference/graphql-api/shop/object-types#intstructfieldconfig">IntStructFieldConfig</a> | <a href="/reference/graphql-api/shop/object-types#floatstructfieldconfig">FloatStructFieldConfig</a> | <a href="/reference/graphql-api/shop/object-types#booleanstructfieldconfig">BooleanStructFieldConfig</a> | <a href="/reference/graphql-api/shop/object-types#datetimestructfieldconfig">DateTimeStructFieldConfig</a> | <a href="/reference/graphql-api/shop/object-types#textstructfieldconfig">TextStructFieldConfig</a></div>
</div>

## Success

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Indicates that an operation succeeded, where we do not want to return any more specific information.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Success</span> &#123;</div>
<div class="graphql-code-line ">success: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## Surcharge

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Surcharge</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">description: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">sku: <a href="/reference/graphql-api/shop/object-types#string">String</a></div>

<div class="graphql-code-line ">taxLines: [<a href="/reference/graphql-api/shop/object-types#taxline">TaxLine</a>!]!</div>

<div class="graphql-code-line ">price: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">priceWithTax: <a href="/reference/graphql-api/shop/object-types#money">Money</a>!</div>

<div class="graphql-code-line ">taxRate: <a href="/reference/graphql-api/shop/object-types#float">Float</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## Tag

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Tag</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">value: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## TagList

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">TagList</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/shop/object-types#tag">Tag</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/shop/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## TaxCategory

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">TaxCategory</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">isDefault: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## TaxLine

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">TaxLine</span> &#123;</div>
<div class="graphql-code-line ">description: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">taxRate: <a href="/reference/graphql-api/shop/object-types#float">Float</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## TaxRate

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">TaxRate</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">enabled: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">value: <a href="/reference/graphql-api/shop/object-types#float">Float</a>!</div>

<div class="graphql-code-line ">category: <a href="/reference/graphql-api/shop/object-types#taxcategory">TaxCategory</a>!</div>

<div class="graphql-code-line ">zone: <a href="/reference/graphql-api/shop/object-types#zone">Zone</a>!</div>

<div class="graphql-code-line ">customerGroup: <a href="/reference/graphql-api/shop/object-types#customergroup">CustomerGroup</a></div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## TaxRateList

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">TaxRateList</span> &#123;</div>
<div class="graphql-code-line ">items: [<a href="/reference/graphql-api/shop/object-types#taxrate">TaxRate</a>!]!</div>

<div class="graphql-code-line ">totalItems: <a href="/reference/graphql-api/shop/object-types#int">Int</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## TextCustomFieldConfig

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">TextCustomFieldConfig</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">list: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">label: [<a href="/reference/graphql-api/shop/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">description: [<a href="/reference/graphql-api/shop/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">readonly: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">internal: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">nullable: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a></div>

<div class="graphql-code-line ">requiresPermission: [<a href="/reference/graphql-api/shop/enums#permission">Permission</a>!]</div>

<div class="graphql-code-line ">ui: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## TextStructFieldConfig

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">TextStructFieldConfig</span> &#123;</div>
<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">type: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">list: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">label: [<a href="/reference/graphql-api/shop/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">description: [<a href="/reference/graphql-api/shop/object-types#localizedstring">LocalizedString</a>!]</div>

<div class="graphql-code-line ">ui: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## TransitionOrderToStateResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">TransitionOrderToStateResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/shop/object-types#order">Order</a> | <a href="/reference/graphql-api/shop/object-types#orderstatetransitionerror">OrderStateTransitionError</a></div>
</div>

## UpdateCustomerEmailAddressResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">UpdateCustomerEmailAddressResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/shop/object-types#success">Success</a> | <a href="/reference/graphql-api/shop/object-types#identifierchangetokeninvaliderror">IdentifierChangeTokenInvalidError</a> | <a href="/reference/graphql-api/shop/object-types#identifierchangetokenexpirederror">IdentifierChangeTokenExpiredError</a> | <a href="/reference/graphql-api/shop/object-types#nativeauthstrategyerror">NativeAuthStrategyError</a></div>
</div>

## UpdateCustomerPasswordResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">UpdateCustomerPasswordResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/shop/object-types#success">Success</a> | <a href="/reference/graphql-api/shop/object-types#invalidcredentialserror">InvalidCredentialsError</a> | <a href="/reference/graphql-api/shop/object-types#passwordvalidationerror">PasswordValidationError</a> | <a href="/reference/graphql-api/shop/object-types#nativeauthstrategyerror">NativeAuthStrategyError</a></div>
</div>

## UpdateMultipleOrderItemsResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned when multiple items are added to an Order.</div>

<div class="graphql-code-line top-level comment">The errorResults array contains the errors that occurred for each item, if any.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">UpdateMultipleOrderItemsResult</span> &#123;</div>
<div class="graphql-code-line ">order: <a href="/reference/graphql-api/shop/object-types#order">Order</a>!</div>

<div class="graphql-code-line ">errorResults: [<a href="/reference/graphql-api/shop/object-types#updateorderitemerrorresult">UpdateOrderItemErrorResult</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## UpdateOrderItemErrorResult

<div class="graphql-code-block">
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line comment">Union type of all possible errors that can occur when adding or removing items from an Order.</div>
<div class="graphql-code-line comment">"""</div>
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">UpdateOrderItemErrorResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/shop/object-types#ordermodificationerror">OrderModificationError</a> | <a href="/reference/graphql-api/shop/object-types#orderlimiterror">OrderLimitError</a> | <a href="/reference/graphql-api/shop/object-types#negativequantityerror">NegativeQuantityError</a> | <a href="/reference/graphql-api/shop/object-types#insufficientstockerror">InsufficientStockError</a> | <a href="/reference/graphql-api/shop/object-types#orderinterceptorerror">OrderInterceptorError</a></div>
</div>

## UpdateOrderItemsResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">UpdateOrderItemsResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/shop/object-types#order">Order</a> | <a href="/reference/graphql-api/shop/object-types#ordermodificationerror">OrderModificationError</a> | <a href="/reference/graphql-api/shop/object-types#orderlimiterror">OrderLimitError</a> | <a href="/reference/graphql-api/shop/object-types#negativequantityerror">NegativeQuantityError</a> | <a href="/reference/graphql-api/shop/object-types#insufficientstockerror">InsufficientStockError</a> | <a href="/reference/graphql-api/shop/object-types#orderinterceptorerror">OrderInterceptorError</a></div>
</div>

## Upload

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">The <code>Upload</code> scalar type represents a file upload.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">scalar <span class="graphql-code-identifier">Upload</span></div>
</div>

## User

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">User</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">identifier: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">verified: <a href="/reference/graphql-api/shop/object-types#boolean">Boolean</a>!</div>

<div class="graphql-code-line ">roles: [<a href="/reference/graphql-api/shop/object-types#role">Role</a>!]!</div>

<div class="graphql-code-line ">lastLogin: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a></div>

<div class="graphql-code-line ">authenticationMethods: [<a href="/reference/graphql-api/shop/object-types#authenticationmethod">AuthenticationMethod</a>!]!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## VerificationTokenExpiredError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned if the verification token (used to verify a Customer's email address) is valid, but has</div>

<div class="graphql-code-line top-level comment">expired according to the <code>verificationTokenDuration</code> setting in the AuthOptions.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">VerificationTokenExpiredError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/shop/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## VerificationTokenInvalidError

<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returned if the verification token (used to verify a Customer's email address) is either</div>

<div class="graphql-code-line top-level comment">invalid or does not match any expected tokens.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">VerificationTokenInvalidError</span> &#123;</div>
<div class="graphql-code-line ">errorCode: <a href="/reference/graphql-api/shop/enums#errorcode">ErrorCode</a>!</div>

<div class="graphql-code-line ">message: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## VerifyCustomerAccountResult

<div class="graphql-code-block">
<div class="graphql-code-line top-level">union <span class="graphql-code-identifier">VerifyCustomerAccountResult</span> =</div>
<div class="graphql-code-line "><a href="/reference/graphql-api/shop/object-types#currentuser">CurrentUser</a> | <a href="/reference/graphql-api/shop/object-types#verificationtokeninvaliderror">VerificationTokenInvalidError</a> | <a href="/reference/graphql-api/shop/object-types#verificationtokenexpirederror">VerificationTokenExpiredError</a> | <a href="/reference/graphql-api/shop/object-types#missingpassworderror">MissingPasswordError</a> | <a href="/reference/graphql-api/shop/object-types#passwordvalidationerror">PasswordValidationError</a> | <a href="/reference/graphql-api/shop/object-types#passwordalreadyseterror">PasswordAlreadySetError</a> | <a href="/reference/graphql-api/shop/object-types#nativeauthstrategyerror">NativeAuthStrategyError</a></div>
</div>

## Zone

<div class="graphql-code-block">
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Zone</span> &#123;</div>
<div class="graphql-code-line ">id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!</div>

<div class="graphql-code-line ">createdAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">updatedAt: <a href="/reference/graphql-api/shop/object-types#datetime">DateTime</a>!</div>

<div class="graphql-code-line ">name: <a href="/reference/graphql-api/shop/object-types#string">String</a>!</div>

<div class="graphql-code-line ">members: [<a href="/reference/graphql-api/shop/object-types#region">Region</a>!]!</div>

<div class="graphql-code-line ">customFields: <a href="/reference/graphql-api/shop/object-types#json">JSON</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>


---

---
title: "Queries"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';



## activeChannel
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">The active Channel</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">activeChannel: <a href="/reference/graphql-api/shop/object-types#channel">Channel</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## activeCustomer
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">The active Customer</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">activeCustomer: <a href="/reference/graphql-api/shop/object-types#customer">Customer</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## activeOrder
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">The active Order. Will be <code>null</code> until an Order is created via `addItemToOrder`. Once an Order reaches the</div>

<div class="graphql-code-line top-level comment">state of <code>PaymentAuthorized</code> or `PaymentSettled`, then that Order is no longer considered "active" and this</div>

<div class="graphql-code-line top-level comment">query will once again return `null`.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">activeOrder: <a href="/reference/graphql-api/shop/object-types#order">Order</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## activePaymentMethods
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Get active payment methods</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">activePaymentMethods: [<a href="/reference/graphql-api/shop/object-types#publicpaymentmethod">PublicPaymentMethod</a>]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## activeShippingMethods
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Get active shipping methods</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">activeShippingMethods: [<a href="/reference/graphql-api/shop/object-types#publicshippingmethod">PublicShippingMethod</a>]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## availableCountries
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">An array of supported Countries</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">availableCountries: [<a href="/reference/graphql-api/shop/object-types#country">Country</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## collection
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returns a Collection either by its id or slug. If neither 'id' nor 'slug' is specified, an error will result.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">collection(id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>, slug: <a href="/reference/graphql-api/shop/object-types#string">String</a>): <a href="/reference/graphql-api/shop/object-types#collection">Collection</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## collections
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">A list of Collections available to the shop</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">collections(options: <a href="/reference/graphql-api/shop/input-types#collectionlistoptions">CollectionListOptions</a>): <a href="/reference/graphql-api/shop/object-types#collectionlist">CollectionList</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## eligiblePaymentMethods
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returns a list of payment methods and their eligibility based on the current active Order</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">eligiblePaymentMethods: [<a href="/reference/graphql-api/shop/object-types#paymentmethodquote">PaymentMethodQuote</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## eligibleShippingMethods
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returns a list of eligible shipping methods based on the current active Order</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">eligibleShippingMethods: [<a href="/reference/graphql-api/shop/object-types#shippingmethodquote">ShippingMethodQuote</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## facet
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returns a Facet by its id</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">facet(id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!): <a href="/reference/graphql-api/shop/object-types#facet">Facet</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## facets
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">A list of Facets available to the shop</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">facets(options: <a href="/reference/graphql-api/shop/input-types#facetlistoptions">FacetListOptions</a>): <a href="/reference/graphql-api/shop/object-types#facetlist">FacetList</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## me
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returns information about the current authenticated User</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">me: <a href="/reference/graphql-api/shop/object-types#currentuser">CurrentUser</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## nextOrderStates
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returns the possible next states that the activeOrder can transition to</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">nextOrderStates: [<a href="/reference/graphql-api/shop/object-types#string">String</a>!]!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## order
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returns an Order based on the id. Note that in the Shop API, only orders belonging to the</div>

<div class="graphql-code-line top-level comment">currently-authenticated User may be queried.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">order(id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>!): <a href="/reference/graphql-api/shop/object-types#order">Order</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## orderByCode
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Returns an Order based on the order `code`. For guest Orders (i.e. Orders placed by non-authenticated Customers)</div>

<div class="graphql-code-line top-level comment">this query will only return the Order within 2 hours of the Order being placed. This allows an Order confirmation</div>

<div class="graphql-code-line top-level comment">screen to be shown immediately after completion of a guest checkout, yet prevents security risks of allowing</div>

<div class="graphql-code-line top-level comment">general anonymous access to Order data.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">orderByCode(code: <a href="/reference/graphql-api/shop/object-types#string">String</a>!): <a href="/reference/graphql-api/shop/object-types#order">Order</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## product
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Get a Product either by id or slug. If neither 'id' nor 'slug' is specified, an error will result.</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">product(id: <a href="/reference/graphql-api/shop/object-types#id">ID</a>, slug: <a href="/reference/graphql-api/shop/object-types#string">String</a>): <a href="/reference/graphql-api/shop/object-types#product">Product</a></div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## products
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Get a list of Products</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">products(options: <a href="/reference/graphql-api/shop/input-types#productlistoptions">ProductListOptions</a>): <a href="/reference/graphql-api/shop/object-types#productlist">ProductList</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>

## search
<div class="graphql-code-block">
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level comment">Search Products based on the criteria set by the `SearchInput`</div>
<div class="graphql-code-line top-level comment">"""</div>
<div class="graphql-code-line top-level">type <span class="graphql-code-identifier">Query</span> &#123;</div>
<div class="graphql-code-line ">search(input: <a href="/reference/graphql-api/shop/input-types#searchinput">SearchInput</a>!): <a href="/reference/graphql-api/shop/object-types#searchresponse">SearchResponse</a>!</div>


<div class="graphql-code-line top-level">&#125;</div>
</div>


---

---
title: "Vendure API Reference"
---

This section contains reference documentation for the various APIs exposed by Vendure.

:::note

All of the information in this section is generated directly from the Vendure source code. You can jump directly
to the source file using the links below each heading.

:::

![Source links](./links.webp)



### TypeScript API

These are the classes, interfaces and other TypeScript object which are used when **writing plugins** or custom business logic.

### Core Plugins

These are the TypeScript APIs for the core Vendure plugins.

### GraphQL API

These are the GraphQL APIs you will use to build your storefront (Shop API) or admin integrations (Admin API).

### Admin UI API

These are the Angular components and services you can use when building Admin UI extensions.


---

---
title: "TypeScript API"
weight: 9
showtoc: false
---

# Vendure TypeScript API Docs

The Vendure TypeScript API is used when configuring the server (via the [`VendureConfig`](/reference/typescript-api/configuration/vendure-config/#vendureconfig) object) and when writing plugins that extend the functionality of Vendure core.

:::note
All documentation in this section is auto-generated from the TypeScript source of the Vendure server.
:::


---

---
title: "AssetNamingStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## AssetNamingStrategy

<GenerationInfo sourceFile="packages/core/src/config/asset-naming-strategy/asset-naming-strategy.ts" sourceLine="18" packageName="@vendure/core" />

The AssetNamingStrategy determines how file names are generated based on the uploaded source file name,
as well as how to handle naming conflicts.

:::info

This is configured via the `assetOptions.assetNamingStrategy` property of
your VendureConfig.

:::

```ts title="Signature"
interface AssetNamingStrategy extends InjectableStrategy {
    generateSourceFileName(ctx: RequestContext, originalFileName: string, conflictFileName?: string): string;
    generatePreviewFileName(ctx: RequestContext, sourceFileName: string, conflictFileName?: string): string;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### generateSourceFileName

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, originalFileName: string, conflictFileName?: string) => string`}   />

Given the original file name of the uploaded file, generate a file name to
be stored on the server. Operations like normalization and time-stamping can
be performed in this method.

The output will be checked for a naming conflict with an existing file. If a conflict
exists, this method will be invoked again with the second argument passed in and a new, unique
file name should then be generated. This process will repeat until a unique file name has
been returned.
### generatePreviewFileName

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, sourceFileName: string, conflictFileName?: string) => string`}   />

Given the source file name generated in the `generateSourceFileName` method, this method
should generate the file name of the preview image.

The same mechanism of checking for conflicts is used as described above.


</div>


---

---
title: "AssetOptions"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## AssetOptions

<GenerationInfo sourceFile="packages/core/src/config/vendure-config.ts" sourceLine="674" packageName="@vendure/core" />

The AssetOptions define how assets (images and other files) are named and stored, and how preview images are generated.

**Note**: If you are using the `AssetServerPlugin`, it is not necessary to configure these options.

```ts title="Signature"
interface AssetOptions {
    assetNamingStrategy?: AssetNamingStrategy;
    assetStorageStrategy?: AssetStorageStrategy;
    assetPreviewStrategy?: AssetPreviewStrategy;
    permittedFileTypes?: string[];
    uploadMaxFileSize?: number;
}
```

<div className="members-wrapper">

### assetNamingStrategy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/assets/asset-naming-strategy#assetnamingstrategy'>AssetNamingStrategy</a>`} default={`<a href='/reference/typescript-api/assets/default-asset-naming-strategy#defaultassetnamingstrategy'>DefaultAssetNamingStrategy</a>`}   />

Defines how asset files and preview images are named before being saved.
### assetStorageStrategy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/assets/asset-storage-strategy#assetstoragestrategy'>AssetStorageStrategy</a>`} default={`NoAssetStorageStrategy`}   />

Defines the strategy used for storing uploaded binary files.
### assetPreviewStrategy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/assets/asset-preview-strategy#assetpreviewstrategy'>AssetPreviewStrategy</a>`} default={`NoAssetPreviewStrategy`}   />

Defines the strategy used for creating preview images of uploaded assets.
### permittedFileTypes

<MemberInfo kind="property" type={`string[]`} default={`image, audio, video MIME types plus PDFs`}   />

An array of the permitted file types that may be uploaded as Assets. Each entry
should be in the form of a valid
[unique file type specifier](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#Unique_file_type_specifiers)
i.e. either a file extension (".pdf") or a mime type ("image/*", "audio/mpeg" etc.).
### uploadMaxFileSize

<MemberInfo kind="property" type={`number`} default={`20971520`}   />

The max file size in bytes for uploaded assets.


</div>


---

---
title: "AssetPreviewStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## AssetPreviewStrategy

<GenerationInfo sourceFile="packages/core/src/config/asset-preview-strategy/asset-preview-strategy.ts" sourceLine="25" packageName="@vendure/core" />

The AssetPreviewStrategy determines how preview images for assets are created. For image
assets, this would usually typically involve resizing to sensible dimensions. Other file types
could be previewed in a variety of ways, e.g.:

- waveform images generated for audio files
- preview images generated for pdf documents
- watermarks added to preview images

:::info

This is configured via the `assetOptions.assetPreviewStrategy` property of
your VendureConfig.

:::

```ts title="Signature"
interface AssetPreviewStrategy extends InjectableStrategy {
    generatePreviewImage(ctx: RequestContext, mimeType: string, data: Buffer): Promise<Buffer>;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### generatePreviewImage

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, mimeType: string, data: Buffer) => Promise&#60;Buffer&#62;`}   />




</div>


---

---
title: "AssetStorageStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## AssetStorageStrategy

<GenerationInfo sourceFile="packages/core/src/config/asset-storage-strategy/asset-storage-strategy.ts" sourceLine="32" packageName="@vendure/core" />

The AssetPersistenceStrategy determines how Asset files are physically stored
and retrieved.

:::info

This is configured via the `assetOptions.assetStorageStrategy` property of
your VendureConfig.

:::

```ts title="Signature"
interface AssetStorageStrategy extends InjectableStrategy {
    writeFileFromBuffer(fileName: string, data: Buffer): Promise<string>;
    writeFileFromStream(fileName: string, data: Stream): Promise<string>;
    readFileToBuffer(identifier: string): Promise<Buffer>;
    readFileToStream(identifier: string): Promise<Stream>;
    deleteFile(identifier: string): Promise<void>;
    fileExists(fileName: string): Promise<boolean>;
    toAbsoluteUrl?(request: Request, identifier: string): string;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### writeFileFromBuffer

<MemberInfo kind="method" type={`(fileName: string, data: Buffer) => Promise&#60;string&#62;`}   />

Writes a buffer to the store and returns a unique identifier for that
file such as a file path or a URL.
### writeFileFromStream

<MemberInfo kind="method" type={`(fileName: string, data: Stream) => Promise&#60;string&#62;`}   />

Writes a readable stream to the store and returns a unique identifier for that
file such as a file path or a URL.
### readFileToBuffer

<MemberInfo kind="method" type={`(identifier: string) => Promise&#60;Buffer&#62;`}   />

Reads a file based on an identifier which was generated by the writeFile
method, and returns the as a Buffer.
### readFileToStream

<MemberInfo kind="method" type={`(identifier: string) => Promise&#60;Stream&#62;`}   />

Reads a file based on an identifier which was generated by the writeFile
method, and returns the file as a Stream.
### deleteFile

<MemberInfo kind="method" type={`(identifier: string) => Promise&#60;void&#62;`}   />

Deletes a file from the storage.
### fileExists

<MemberInfo kind="method" type={`(fileName: string) => Promise&#60;boolean&#62;`}   />

Check whether a file with the given name already exists. Used to avoid
naming conflicts before saving the file.
### toAbsoluteUrl

<MemberInfo kind="method" type={`(request: Request, identifier: string) => string`}   />

Convert an identifier as generated by the writeFile... methods into an absolute
url (if it is not already in that form). If no conversion step is needed
(i.e. the identifier is already an absolute url) then this method
should not be implemented.


</div>


---

---
title: "DefaultAssetNamingStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DefaultAssetNamingStrategy

<GenerationInfo sourceFile="packages/core/src/config/asset-naming-strategy/default-asset-naming-strategy.ts" sourceLine="15" packageName="@vendure/core" />

The default strategy normalizes the file names to remove unwanted characters and
in the case of conflicts, increments a counter suffix.

```ts title="Signature"
class DefaultAssetNamingStrategy implements AssetNamingStrategy {
    generateSourceFileName(ctx: RequestContext, originalFileName: string, conflictFileName?: string) => string;
    generatePreviewFileName(ctx: RequestContext, sourceFileName: string, conflictFileName?: string) => string;
}
```
* Implements: <code><a href='/reference/typescript-api/assets/asset-naming-strategy#assetnamingstrategy'>AssetNamingStrategy</a></code>



<div className="members-wrapper">

### generateSourceFileName

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, originalFileName: string, conflictFileName?: string) => string`}   />


### generatePreviewFileName

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, sourceFileName: string, conflictFileName?: string) => string`}   />




</div>


---

---
title: "Assets"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "AuthOptions"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## AuthOptions

<GenerationInfo sourceFile="packages/core/src/config/vendure-config.ts" sourceLine="359" packageName="@vendure/core" />

The AuthOptions define how authentication and authorization is managed.

```ts title="Signature"
interface AuthOptions {
    disableAuth?: boolean;
    tokenMethod?: 'cookie' | 'bearer' | ReadonlyArray<'cookie' | 'bearer'>;
    cookieOptions?: CookieOptions;
    authTokenHeaderKey?: string;
    sessionDuration?: string | number;
    sessionCacheStrategy?: SessionCacheStrategy;
    sessionCacheTTL?: string | number;
    requireVerification?: boolean;
    verificationTokenDuration?: string | number;
    superadminCredentials?: SuperadminCredentials;
    shopAuthenticationStrategy?: AuthenticationStrategy[];
    adminAuthenticationStrategy?: AuthenticationStrategy[];
    customPermissions?: PermissionDefinition[];
    passwordHashingStrategy?: PasswordHashingStrategy;
    passwordValidationStrategy?: PasswordValidationStrategy;
    verificationTokenStrategy?: VerificationTokenStrategy;
}
```

<div className="members-wrapper">

### disableAuth

<MemberInfo kind="property" type={`boolean`} default={`false`}   />

Disable authentication & permissions checks.
NEVER set the to true in production. It exists
only to aid certain development tasks.
### tokenMethod

<MemberInfo kind="property" type={`'cookie' | 'bearer' | ReadonlyArray&#60;'cookie' | 'bearer'&#62;`} default={`'cookie'`}   />

Sets the method by which the session token is delivered and read.

* 'cookie': Upon login, a 'Set-Cookie' header will be returned to the client, setting a
  cookie containing the session token. A browser-based client (making requests with credentials)
  should automatically send the session cookie with each request.
* 'bearer': Upon login, the token is returned in the response and should be then stored by the
  client app. Each request should include the header `Authorization: Bearer <token>`.

Note that if the bearer method is used, Vendure will automatically expose the configured
`authTokenHeaderKey` in the server's CORS configuration (adding `Access-Control-Expose-Headers: vendure-auth-token`
by default).

From v1.2.0 it is possible to specify both methods as a tuple: `['cookie', 'bearer']`.
### cookieOptions

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/auth/cookie-options#cookieoptions'>CookieOptions</a>`}   />

Options related to the handling of cookies when using the 'cookie' tokenMethod.
### authTokenHeaderKey

<MemberInfo kind="property" type={`string`} default={`'vendure-auth-token'`}   />

Sets the header property which will be used to send the auth token when using the 'bearer' method.
### sessionDuration

<MemberInfo kind="property" type={`string | number`} default={`'1y'`}   />

Session duration, i.e. the time which must elapse from the last authenticated request
after which the user must re-authenticate.

If passed as a number should represent milliseconds and if passed as a string describes a time span per
[zeit/ms](https://github.com/zeit/ms.js).  Eg: `60`, `'2 days'`, `'10h'`, `'7d'`
### sessionCacheStrategy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/auth/session-cache-strategy#sessioncachestrategy'>SessionCacheStrategy</a>`} default={`<a href='/reference/typescript-api/auth/default-session-cache-strategy#defaultsessioncachestrategy'>DefaultSessionCacheStrategy</a>`}   />

This strategy defines how sessions will be cached. By default, since v3.1.0, sessions are cached using
the underlying cache strategy defined in the <a href='/reference/typescript-api/configuration/system-options#systemoptions'>SystemOptions</a>`.cacheStrategy`.
### sessionCacheTTL

<MemberInfo kind="property" type={`string | number`} default={`300`}   />

The "time to live" of a given item in the session cache. This determines the length of time that a cache entry
is kept before being considered "stale" and being replaced with fresh data taken from the database.

If passed as a number should represent seconds and if passed as a string describes a time span per
[zeit/ms](https://github.com/zeit/ms.js). Eg: `60`, `'2 days'`, `'10h'`, `'7d'`
### requireVerification

<MemberInfo kind="property" type={`boolean`} default={`true`}   />

Determines whether new User accounts require verification of their email address.

If set to "true", the customer will be required to verify their email address using a verification token
they receive in their email. See the `registerCustomerAccount` mutation for more details on the verification behavior.
### verificationTokenDuration

<MemberInfo kind="property" type={`string | number`} default={`'7d'`}   />

Sets the length of time that a verification token is valid for, after which the verification token must be refreshed.

If passed as a number should represent milliseconds and if passed as a string describes a time span per
[zeit/ms](https://github.com/zeit/ms.js).  Eg: `60`, `'2 days'`, `'10h'`, `'7d'`
### superadminCredentials

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/auth/superadmin-credentials#superadmincredentials'>SuperadminCredentials</a>`}   />

Configures the credentials to be used to create a superadmin
### shopAuthenticationStrategy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/auth/authentication-strategy#authenticationstrategy'>AuthenticationStrategy</a>[]`} default={`<a href='/reference/typescript-api/auth/native-authentication-strategy#nativeauthenticationstrategy'>NativeAuthenticationStrategy</a>`}   />

Configures one or more AuthenticationStrategies which defines how authentication
is handled in the Shop API.
### adminAuthenticationStrategy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/auth/authentication-strategy#authenticationstrategy'>AuthenticationStrategy</a>[]`} default={`<a href='/reference/typescript-api/auth/native-authentication-strategy#nativeauthenticationstrategy'>NativeAuthenticationStrategy</a>`}   />

Configures one or more AuthenticationStrategy which defines how authentication
is handled in the Admin API.
### customPermissions

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/auth/permission-definition#permissiondefinition'>PermissionDefinition</a>[]`} default={`[]`}   />

Allows custom Permissions to be defined, which can be used to restrict access to custom
GraphQL resolvers defined in plugins.
### passwordHashingStrategy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/auth/password-hashing-strategy#passwordhashingstrategy'>PasswordHashingStrategy</a>`} default={`<a href='/reference/typescript-api/auth/bcrypt-password-hashing-strategy#bcryptpasswordhashingstrategy'>BcryptPasswordHashingStrategy</a>`}  since="1.3.0"  />

Allows you to customize the way passwords are hashed when using the <a href='/reference/typescript-api/auth/native-authentication-strategy#nativeauthenticationstrategy'>NativeAuthenticationStrategy</a>.
### passwordValidationStrategy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/auth/password-validation-strategy#passwordvalidationstrategy'>PasswordValidationStrategy</a>`} default={`<a href='/reference/typescript-api/auth/default-password-validation-strategy#defaultpasswordvalidationstrategy'>DefaultPasswordValidationStrategy</a>`}  since="1.5.0"  />

Allows you to set a custom policy for passwords when using the <a href='/reference/typescript-api/auth/native-authentication-strategy#nativeauthenticationstrategy'>NativeAuthenticationStrategy</a>.
By default, it uses the <a href='/reference/typescript-api/auth/default-password-validation-strategy#defaultpasswordvalidationstrategy'>DefaultPasswordValidationStrategy</a>, which will impose a minimum length
of four characters. To improve security for production, you are encouraged to specify a more strict
policy, which you can do like this:

*Example*

```ts
{
  passwordValidationStrategy: new DefaultPasswordValidationStrategy({
    // Minimum eight characters, at least one letter and one number
    regexp: /^(?=.*[A-Za-z])(?=.*\d)[A-Za-z\d]{8,}$/,
  }),
}
```
### verificationTokenStrategy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/auth/verification-token-strategy#verificationtokenstrategy'>VerificationTokenStrategy</a>`} default={`<a href='/reference/typescript-api/auth/default-verification-token-strategy#defaultverificationtokenstrategy'>DefaultVerificationTokenStrategy</a>`}  since="3.2.0"  />

Allows you to customize the way verification tokens are generated.


</div>


---

---
title: "AuthenticationStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## AuthenticationStrategy

<GenerationInfo sourceFile="packages/core/src/config/auth/authentication-strategy.ts" sourceLine="23" packageName="@vendure/core" />

An AuthenticationStrategy defines how a User (which can be a Customer in the Shop API or
and Administrator in the Admin API) may be authenticated.

Real-world examples can be found in the [Authentication guide](/guides/core-concepts/auth/).

:::info

This is configured via the `authOptions.shopAuthenticationStrategy` and `authOptions.adminAuthenticationStrategy`
properties of your VendureConfig.

:::

```ts title="Signature"
interface AuthenticationStrategy<Data = unknown> extends InjectableStrategy {
    readonly name: string;
    defineInputType(): DocumentNode;
    authenticate(ctx: RequestContext, data: Data): Promise<User | false | string>;
    onLogOut?(ctx: RequestContext, user: User): Promise<void>;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### name

<MemberInfo kind="property" type={`string`}   />

The name of the strategy, for example `'facebook'`, `'google'`, `'keycloak'`.
### defineInputType

<MemberInfo kind="method" type={`() => DocumentNode`}   />

Defines the type of the GraphQL Input object expected by the `authenticate`
mutation. The final input object will be a map, with the key being the name
of the strategy. The shape of the input object should match the generic `Data`
type argument.

*Example*

For example, given the following:

```ts
defineInputType() {
  return gql`
     input MyAuthInput {
       token: String!
     }
  `;
}
```

assuming the strategy name is "my_auth", then the resulting call to `authenticate`
would look like:

```GraphQL
authenticate(input: {
  my_auth: {
    token: "foo"
  }
}) {
  # ...
}
```

**Note:** if more than one graphql `input` type is being defined (as in a nested input type), then
the _first_ input will be assumed to be the top-level input.
### authenticate

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, data: Data) => Promise&#60;<a href='/reference/typescript-api/entities/user#user'>User</a> | false | string&#62;`}   />

Used to authenticate a user with the authentication provider. This method
will implement the provider-specific authentication logic, and should resolve to either a
<a href='/reference/typescript-api/entities/user#user'>User</a> object on success, or `false | string` on failure.
A `string` return could be used to describe what error happened, otherwise `false` to an unknown error.
### onLogOut

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, user: <a href='/reference/typescript-api/entities/user#user'>User</a>) => Promise&#60;void&#62;`}   />

Called when a user logs out, and may perform any required tasks
related to the user logging out with the external provider.


</div>


---

---
title: "BcryptPasswordHashingStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## BcryptPasswordHashingStrategy

<GenerationInfo sourceFile="packages/core/src/config/auth/bcrypt-password-hashing-strategy.ts" sourceLine="12" packageName="@vendure/core" since="1.3.0" />

A hashing strategy which uses bcrypt (https://en.wikipedia.org/wiki/Bcrypt) to hash plaintext password strings.

```ts title="Signature"
class BcryptPasswordHashingStrategy implements PasswordHashingStrategy {
    hash(plaintext: string) => Promise<string>;
    check(plaintext: string, hash: string) => Promise<boolean>;
}
```
* Implements: <code><a href='/reference/typescript-api/auth/password-hashing-strategy#passwordhashingstrategy'>PasswordHashingStrategy</a></code>



<div className="members-wrapper">

### hash

<MemberInfo kind="method" type={`(plaintext: string) => Promise&#60;string&#62;`}   />


### check

<MemberInfo kind="method" type={`(plaintext: string, hash: string) => Promise&#60;boolean&#62;`}   />




</div>


---

---
title: "CookieOptions"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## CookieOptions

<GenerationInfo sourceFile="packages/core/src/config/vendure-config.ts" sourceLine="254" packageName="@vendure/core" />

Options for the handling of the cookies used to track sessions (only applicable if
`authOptions.tokenMethod` is set to `'cookie'`). These options are passed directly
to the Express [cookie-session middleware](https://github.com/expressjs/cookie-session).

```ts title="Signature"
interface CookieOptions {
    name?: string | { shop: string; admin: string };
    secret?: string;
    path?: string;
    domain?: string;
    sameSite?: 'strict' | 'lax' | 'none' | boolean;
    secure?: boolean;
    secureProxy?: boolean;
    httpOnly?: boolean;
    signed?: boolean;
    overwrite?: boolean;
    maxAge?: number;
    expires?: Date;
}
```

<div className="members-wrapper">

### name

<MemberInfo kind="property" type={`string | { shop: string; admin: string }`} default={`'session'`}   />

The name of the cookies to set.
If set to a string, both cookies for the Admin API and Shop API will have the same name.
If set as an object, it makes it possible to give different names to the Admin API and the Shop API cookies
### secret

<MemberInfo kind="property" type={`string`} default={`(random character string)`}   />

The secret used for signing the session cookies for authenticated users. Only applies
tokenMethod is set to 'cookie'.

In production applications, this should not be stored as a string in
source control for security reasons, but may be loaded from an external
file not under source control, or from an environment variable, for example.
### path

<MemberInfo kind="property" type={`string`} default={`'/'`}   />

a string indicating the path of the cookie.
### domain

<MemberInfo kind="property" type={`string`}   />

a string indicating the domain of the cookie (no default).
### sameSite

<MemberInfo kind="property" type={`'strict' | 'lax' | 'none' | boolean`} default={`false`}   />

a boolean or string indicating whether the cookie is a "same site" cookie (false by default). This can be set to 'strict',
'lax', 'none', or true (which maps to 'strict').
### secure

<MemberInfo kind="property" type={`boolean`}   />

a boolean indicating whether the cookie is only to be sent over HTTPS (false by default for HTTP, true by default for HTTPS).
### secureProxy

<MemberInfo kind="property" type={`boolean`}   />

a boolean indicating whether the cookie is only to be sent over HTTPS (use this if you handle SSL not in your node process).
### httpOnly

<MemberInfo kind="property" type={`boolean`} default={`true`}   />

a boolean indicating whether the cookie is only to be sent over HTTP(S), and not made available to client JavaScript (true by default).
### signed

<MemberInfo kind="property" type={`boolean`}   />

a boolean indicating whether the cookie is to be signed (true by default). If this is true, another cookie of the same name with the .sig
suffix appended will also be sent, with a 27-byte url-safe base64 SHA1 value representing the hash of cookie-name=cookie-value against the
first Keygrip key. This signature key is used to detect tampering the next time a cookie is received.
### overwrite

<MemberInfo kind="property" type={`boolean`}   />

a boolean indicating whether to overwrite previously set cookies of the same name (true by default). If this is true, all cookies set during
the same request with the same name (regardless of path or domain) are filtered out of the Set-Cookie header when setting this cookie.
### maxAge

<MemberInfo kind="property" type={`number`}  since="2.2.0"  />

A number representing the milliseconds from Date.now() for expiry
### expires

<MemberInfo kind="property" type={`Date`}  since="2.2.0"  />

a Date object indicating the cookie's expiration date (expires at the end of session by default).


</div>


---

---
title: "DefaultPasswordValidationStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DefaultPasswordValidationStrategy

<GenerationInfo sourceFile="packages/core/src/config/auth/default-password-validation-strategy.ts" sourceLine="18" packageName="@vendure/core" since="1.5.0" />

The DefaultPasswordValidationStrategy allows you to specify a minimum length and/or
a regular expression to match passwords against. The default `maxLength` is `72`.

TODO:
By default, the `minLength` will be set to `4`. This is rather permissive and is only
this way in order to reduce the risk of backward-compatibility breaks. In the next major version
this default will be made more strict.

```ts title="Signature"
class DefaultPasswordValidationStrategy implements PasswordValidationStrategy {
    constructor(options: { minLength?: number; maxLength?: number; regexp?: RegExp })
    validate(ctx: RequestContext, password: string) => boolean | string;
}
```
* Implements: <code><a href='/reference/typescript-api/auth/password-validation-strategy#passwordvalidationstrategy'>PasswordValidationStrategy</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(options: { minLength?: number; maxLength?: number; regexp?: RegExp }) => DefaultPasswordValidationStrategy`}   />


### validate

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, password: string) => boolean | string`}   />




</div>


---

---
title: "DefaultSessionCacheStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DefaultSessionCacheStrategy

<GenerationInfo sourceFile="packages/core/src/config/session-cache/default-session-cache-strategy.ts" sourceLine="17" packageName="@vendure/core" since="3.1.0" />

The default <a href='/reference/typescript-api/auth/session-cache-strategy#sessioncachestrategy'>SessionCacheStrategy</a> delegates to the configured
<a href='/reference/typescript-api/cache/cache-strategy#cachestrategy'>CacheStrategy</a> to store the session data. This should be suitable
for most use-cases, assuming you select a suitable <a href='/reference/typescript-api/cache/cache-strategy#cachestrategy'>CacheStrategy</a>

```ts title="Signature"
class DefaultSessionCacheStrategy implements SessionCacheStrategy {
    protected cacheService: CacheService;
    constructor(options?: {
            ttl?: number;
            cachePrefix?: string;
        })
    init(injector: Injector) => ;
    set(session: CachedSession) => Promise<void>;
    get(sessionToken: string) => Promise<CachedSession | undefined>;
    delete(sessionToken: string) => void | Promise<void>;
    clear() => Promise<void>;
}
```
* Implements: <code><a href='/reference/typescript-api/auth/session-cache-strategy#sessioncachestrategy'>SessionCacheStrategy</a></code>



<div className="members-wrapper">

### cacheService

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/cache/cache-service#cacheservice'>CacheService</a>`}   />


### constructor

<MemberInfo kind="method" type={`(options?: {             ttl?: number;             cachePrefix?: string;         }) => DefaultSessionCacheStrategy`}   />


### init

<MemberInfo kind="method" type={`(injector: <a href='/reference/typescript-api/common/injector#injector'>Injector</a>) => `}   />


### set

<MemberInfo kind="method" type={`(session: <a href='/reference/typescript-api/auth/session-cache-strategy#cachedsession'>CachedSession</a>) => Promise&#60;void&#62;`}   />


### get

<MemberInfo kind="method" type={`(sessionToken: string) => Promise&#60;<a href='/reference/typescript-api/auth/session-cache-strategy#cachedsession'>CachedSession</a> | undefined&#62;`}   />


### delete

<MemberInfo kind="method" type={`(sessionToken: string) => void | Promise&#60;void&#62;`}   />


### clear

<MemberInfo kind="method" type={`() => Promise&#60;void&#62;`}   />




</div>


---

---
title: "DefaultVerificationTokenStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DefaultVerificationTokenStrategy

<GenerationInfo sourceFile="packages/core/src/config/auth/default-verification-token-strategy.ts" sourceLine="20" packageName="@vendure/core" since="3.2.0" />

The default VerificationTokenStrategy which generates a token consisting of the
base64-encoded current time concatenated with a random id. The token is considered
valid if the current time is within the configured `verificationTokenDuration` of the
time encoded in the token.

```ts title="Signature"
class DefaultVerificationTokenStrategy implements VerificationTokenStrategy {
    init(injector: Injector) => ;
    generateVerificationToken(_ctx: RequestContext) => string;
    verifyVerificationToken(_ctx: RequestContext, token: string) => boolean;
}
```
* Implements: <code><a href='/reference/typescript-api/auth/verification-token-strategy#verificationtokenstrategy'>VerificationTokenStrategy</a></code>



<div className="members-wrapper">

### init

<MemberInfo kind="method" type={`(injector: <a href='/reference/typescript-api/common/injector#injector'>Injector</a>) => `}   />


### generateVerificationToken

<MemberInfo kind="method" type={`(_ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => string`}   />


### verifyVerificationToken

<MemberInfo kind="method" type={`(_ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, token: string) => boolean`}   />




</div>


---

---
title: "ExternalAuthenticationService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ExternalAuthenticationService

<GenerationInfo sourceFile="packages/core/src/service/helpers/external-authentication/external-authentication.service.ts" sourceLine="24" packageName="@vendure/core" />

This is a helper service which exposes methods related to looking up and creating Users based on an
external <a href='/reference/typescript-api/auth/authentication-strategy#authenticationstrategy'>AuthenticationStrategy</a>.

```ts title="Signature"
class ExternalAuthenticationService {
    constructor(connection: TransactionalConnection, roleService: RoleService, historyService: HistoryService, customerService: CustomerService, administratorService: AdministratorService, channelService: ChannelService)
    findCustomerUser(ctx: RequestContext, strategy: string, externalIdentifier: string, checkCurrentChannelOnly:  = true) => Promise<User | undefined>;
    findAdministratorUser(ctx: RequestContext, strategy: string, externalIdentifier: string) => Promise<User | undefined>;
    createCustomerAndUser(ctx: RequestContext, config: {
            strategy: string;
            externalIdentifier: string;
            emailAddress: string;
            firstName: string;
            lastName: string;
            verified?: boolean;
        }) => Promise<User>;
    createAdministratorAndUser(ctx: RequestContext, config: {
            strategy: string;
            externalIdentifier: string;
            identifier: string;
            emailAddress?: string;
            firstName?: string;
            lastName?: string;
            roles: Role[];
        }) => ;
    findUser(ctx: RequestContext, strategy: string, externalIdentifier: string) => Promise<User | undefined>;
    createUser(ctx: RequestContext, config: {
            strategy: string;
            externalIdentifier: string;
        }) => Promise<User>;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, roleService: <a href='/reference/typescript-api/services/role-service#roleservice'>RoleService</a>, historyService: <a href='/reference/typescript-api/services/history-service#historyservice'>HistoryService</a>, customerService: <a href='/reference/typescript-api/services/customer-service#customerservice'>CustomerService</a>, administratorService: <a href='/reference/typescript-api/services/administrator-service#administratorservice'>AdministratorService</a>, channelService: <a href='/reference/typescript-api/services/channel-service#channelservice'>ChannelService</a>) => ExternalAuthenticationService`}   />


### findCustomerUser

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, strategy: string, externalIdentifier: string, checkCurrentChannelOnly:  = true) => Promise&#60;<a href='/reference/typescript-api/entities/user#user'>User</a> | undefined&#62;`}   />

Looks up a User based on their identifier from an external authentication
provider, ensuring this User is associated with a Customer account.

By default, only customers in the currently-active Channel will be checked.
By passing `false` as the `checkCurrentChannelOnly` argument, _all_ channels
will be checked.
### findAdministratorUser

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, strategy: string, externalIdentifier: string) => Promise&#60;<a href='/reference/typescript-api/entities/user#user'>User</a> | undefined&#62;`}   />

Looks up a User based on their identifier from an external authentication
provider, ensuring this User is associated with an Administrator account.
### createCustomerAndUser

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, config: {             strategy: string;             externalIdentifier: string;             emailAddress: string;             firstName: string;             lastName: string;             verified?: boolean;         }) => Promise&#60;<a href='/reference/typescript-api/entities/user#user'>User</a>&#62;`}   />

If a customer has been successfully authenticated by an external authentication provider, yet cannot
be found using `findCustomerUser`, then we need to create a new User and
Customer record in Vendure for that user. This method encapsulates that logic as well as additional
housekeeping such as adding a record to the Customer's history.
### createAdministratorAndUser

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, config: {             strategy: string;             externalIdentifier: string;             identifier: string;             emailAddress?: string;             firstName?: string;             lastName?: string;             roles: <a href='/reference/typescript-api/entities/role#role'>Role</a>[];         }) => `}   />

If an administrator has been successfully authenticated by an external authentication provider, yet cannot
be found using `findAdministratorUser`, then we need to create a new User and
Administrator record in Vendure for that user.
### findUser

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, strategy: string, externalIdentifier: string) => Promise&#60;<a href='/reference/typescript-api/entities/user#user'>User</a> | undefined&#62;`}   />


### createUser

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, config: {             strategy: string;             externalIdentifier: string;         }) => Promise&#60;<a href='/reference/typescript-api/entities/user#user'>User</a>&#62;`}   />

Looks up a User based on their identifier from an external authentication
provider. Creates the user if does not exist. Unlike `findCustomerUser` and `findAdministratorUser`,
this method does not enforce that the User is associated with a Customer or
Administrator account.


</div>


---

---
title: "InMemorySessionCacheStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## InMemorySessionCacheStrategy

<GenerationInfo sourceFile="packages/core/src/config/session-cache/in-memory-session-cache-strategy.ts" sourceLine="16" packageName="@vendure/core" />

Caches session in memory, using a LRU cache implementation. Not suitable for
multi-server setups since the cache will be local to each instance, reducing
its effectiveness. By default the cache has a size of 1000, meaning that after
1000 sessions have been cached, any new sessions will cause the least-recently-used
session to be evicted (removed) from the cache.

The cache size can be configured by passing a different number to the constructor
function.

```ts title="Signature"
class InMemorySessionCacheStrategy implements SessionCacheStrategy {
    constructor(cacheSize?: number)
    delete(sessionToken: string) => ;
    get(sessionToken: string) => ;
    set(session: CachedSession) => ;
    clear() => ;
}
```
* Implements: <code><a href='/reference/typescript-api/auth/session-cache-strategy#sessioncachestrategy'>SessionCacheStrategy</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(cacheSize?: number) => InMemorySessionCacheStrategy`}   />


### delete

<MemberInfo kind="method" type={`(sessionToken: string) => `}   />


### get

<MemberInfo kind="method" type={`(sessionToken: string) => `}   />


### set

<MemberInfo kind="method" type={`(session: <a href='/reference/typescript-api/auth/session-cache-strategy#cachedsession'>CachedSession</a>) => `}   />


### clear

<MemberInfo kind="method" type={`() => `}   />




</div>


---

---
title: "Auth"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "NativeAuthenticationStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## NativeAuthenticationStrategy

<GenerationInfo sourceFile="packages/core/src/config/auth/native-authentication-strategy.ts" sourceLine="28" packageName="@vendure/core" />

This strategy implements a username/password credential-based authentication, with the credentials
being stored in the Vendure database. This is the default method of authentication, and it is advised
to keep it configured unless there is a specific reason not to.

```ts title="Signature"
class NativeAuthenticationStrategy implements AuthenticationStrategy<NativeAuthenticationData> {
    readonly name = NATIVE_AUTH_STRATEGY_NAME;
    init(injector: Injector) => ;
    defineInputType() => DocumentNode;
    authenticate(ctx: RequestContext, data: NativeAuthenticationData) => Promise<User | false>;
    verifyUserPassword(ctx: RequestContext, userId: ID, password: string) => Promise<boolean>;
}
```
* Implements: <code><a href='/reference/typescript-api/auth/authentication-strategy#authenticationstrategy'>AuthenticationStrategy</a>&#60;NativeAuthenticationData&#62;</code>



<div className="members-wrapper">

### name

<MemberInfo kind="property" type={``}   />


### init

<MemberInfo kind="method" type={`(injector: <a href='/reference/typescript-api/common/injector#injector'>Injector</a>) => `}   />


### defineInputType

<MemberInfo kind="method" type={`() => DocumentNode`}   />


### authenticate

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, data: NativeAuthenticationData) => Promise&#60;<a href='/reference/typescript-api/entities/user#user'>User</a> | false&#62;`}   />


### verifyUserPassword

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, userId: <a href='/reference/typescript-api/common/id#id'>ID</a>, password: string) => Promise&#60;boolean&#62;`}   />




</div>


---

---
title: "NoopSessionCacheStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## NoopSessionCacheStrategy

<GenerationInfo sourceFile="packages/core/src/config/session-cache/noop-session-cache-strategy.ts" sourceLine="10" packageName="@vendure/core" />

A cache that doesn't cache. The cache lookup will miss every time
so the session will always be taken from the database.

```ts title="Signature"
class NoopSessionCacheStrategy implements SessionCacheStrategy {
    clear() => ;
    delete(sessionToken: string) => ;
    get(sessionToken: string) => ;
    set(session: CachedSession) => ;
}
```
* Implements: <code><a href='/reference/typescript-api/auth/session-cache-strategy#sessioncachestrategy'>SessionCacheStrategy</a></code>



<div className="members-wrapper">

### clear

<MemberInfo kind="method" type={`() => `}   />


### delete

<MemberInfo kind="method" type={`(sessionToken: string) => `}   />


### get

<MemberInfo kind="method" type={`(sessionToken: string) => `}   />


### set

<MemberInfo kind="method" type={`(session: <a href='/reference/typescript-api/auth/session-cache-strategy#cachedsession'>CachedSession</a>) => `}   />




</div>


---

---
title: "PasswordHashingStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## PasswordHashingStrategy

<GenerationInfo sourceFile="packages/core/src/config/auth/password-hashing-strategy.ts" sourceLine="17" packageName="@vendure/core" since="1.3.0" />

Defines how user passwords get hashed when using the <a href='/reference/typescript-api/auth/native-authentication-strategy#nativeauthenticationstrategy'>NativeAuthenticationStrategy</a>.

:::info

This is configured via the `authOptions.passwordHashingStrategy` property of
your VendureConfig.

:::

```ts title="Signature"
interface PasswordHashingStrategy extends InjectableStrategy {
    hash(plaintext: string): Promise<string>;
    check(plaintext: string, hash: string): Promise<boolean>;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### hash

<MemberInfo kind="method" type={`(plaintext: string) => Promise&#60;string&#62;`}   />


### check

<MemberInfo kind="method" type={`(plaintext: string, hash: string) => Promise&#60;boolean&#62;`}   />




</div>


---

---
title: "PasswordValidationStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## PasswordValidationStrategy

<GenerationInfo sourceFile="packages/core/src/config/auth/password-validation-strategy.ts" sourceLine="19" packageName="@vendure/core" since="1.5.0" />

Defines validation to apply to new password (when creating an account or updating an existing account's
password when using the <a href='/reference/typescript-api/auth/native-authentication-strategy#nativeauthenticationstrategy'>NativeAuthenticationStrategy</a>.

:::info

This is configured via the `authOptions.passwordValidationStrategy` property of
your VendureConfig.

:::

```ts title="Signature"
interface PasswordValidationStrategy extends InjectableStrategy {
    validate(ctx: RequestContext, password: string): Promise<boolean | string> | boolean | string;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### validate

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, password: string) => Promise&#60;boolean | string&#62; | boolean | string`}  since="1.5.0"  />

Validates a password submitted during account registration or when a customer updates their password.
The method should resolve to `true` if the password is acceptable. If not, it should return `false` or
optionally a string which will be passed to the returned ErrorResult, which can e.g. advise on why
exactly the proposed password is not valid.


</div>


---

---
title: "PermissionDefinition"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## PermissionDefinition

<GenerationInfo sourceFile="packages/core/src/common/permission-definition.ts" sourceLine="86" packageName="@vendure/core" />

Defines a new Permission with which to control access to GraphQL resolvers & REST controllers.
Used in conjunction with the <a href='/reference/typescript-api/request/allow-decorator#allow'>Allow</a> decorator (see example below).

**Note:** To define CRUD permissions, use the <a href='/reference/typescript-api/auth/permission-definition#crudpermissiondefinition'>CrudPermissionDefinition</a>.

*Example*

```ts
export const sync = new PermissionDefinition({
  name: 'SyncInventory',
  description: 'Allows syncing stock levels via Admin API'
});
```

```ts
const config: VendureConfig = {
  authOptions: {
    customPermissions: [sync],
  },
}
```

```ts
@Resolver()
export class ExternalSyncResolver {

  @Allow(sync.Permission)
  @Mutation()
  syncStockLevels() {
    // ...
  }
}
```

```ts title="Signature"
class PermissionDefinition {
    constructor(config: PermissionDefinitionConfig)
    Permission: Permission
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(config: <a href='/reference/typescript-api/auth/permission-definition#permissiondefinitionconfig'>PermissionDefinitionConfig</a>) => PermissionDefinition`}   />


### Permission

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/permission#permission'>Permission</a>`}   />

Returns the permission defined by this definition, for use in the
<a href='/reference/typescript-api/request/allow-decorator#allow'>Allow</a> decorator.


</div>


## CrudPermissionDefinition

<GenerationInfo sourceFile="packages/core/src/common/permission-definition.ts" sourceLine="146" packageName="@vendure/core" />

Defines a set of CRUD Permissions for the given name, i.e. a `name` of 'Wishlist' will create
4 Permissions: 'CreateWishlist', 'ReadWishlist', 'UpdateWishlist' & 'DeleteWishlist'.

*Example*

```ts
export const wishlist = new CrudPermissionDefinition('Wishlist');
```

```ts
const config: VendureConfig = {
  authOptions: {
    customPermissions: [wishlist],
  },
}
```

```ts
@Resolver()
export class WishlistResolver {

  @Allow(wishlist.Create)
  @Mutation()
  createWishlist() {
    // ...
  }
}
```

```ts title="Signature"
class CrudPermissionDefinition extends PermissionDefinition {
    constructor(name: string, descriptionFn?: (operation: 'create' | 'read' | 'update' | 'delete') => string)
    Create: Permission
    Read: Permission
    Update: Permission
    Delete: Permission
}
```
* Extends: <code><a href='/reference/typescript-api/auth/permission-definition#permissiondefinition'>PermissionDefinition</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(name: string, descriptionFn?: (operation: 'create' | 'read' | 'update' | 'delete') =&#62; string) => CrudPermissionDefinition`}   />


### Create

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/permission#permission'>Permission</a>`}   />

Returns the 'Create' CRUD permission defined by this definition, for use in the
<a href='/reference/typescript-api/request/allow-decorator#allow'>Allow</a> decorator.
### Read

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/permission#permission'>Permission</a>`}   />

Returns the 'Read' CRUD permission defined by this definition, for use in the
<a href='/reference/typescript-api/request/allow-decorator#allow'>Allow</a> decorator.
### Update

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/permission#permission'>Permission</a>`}   />

Returns the 'Update' CRUD permission defined by this definition, for use in the
<a href='/reference/typescript-api/request/allow-decorator#allow'>Allow</a> decorator.
### Delete

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/permission#permission'>Permission</a>`}   />

Returns the 'Delete' CRUD permission defined by this definition, for use in the
<a href='/reference/typescript-api/request/allow-decorator#allow'>Allow</a> decorator.


</div>


## PermissionDefinitionConfig

<GenerationInfo sourceFile="packages/core/src/common/permission-definition.ts" sourceLine="10" packageName="@vendure/core" />

Configures a <a href='/reference/typescript-api/auth/permission-definition#permissiondefinition'>PermissionDefinition</a>

```ts title="Signature"
interface PermissionDefinitionConfig {
    name: string;
    description?: string;
    assignable?: boolean;
    internal?: boolean;
}
```

<div className="members-wrapper">

### name

<MemberInfo kind="property" type={`string`}   />

The name of the permission. By convention this should be
UpperCamelCased.
### description

<MemberInfo kind="property" type={`string`}   />

A description of the permission.
### assignable

<MemberInfo kind="property" type={`boolean`} default={`true`}   />

Whether this permission can be assigned to a Role. In general this
should be left as the default `true` except in special cases.
### internal

<MemberInfo kind="property" type={`boolean`} default={`false`}   />

Internal permissions are not exposed via the API and are reserved for
special use-cases such at the `Owner` or `Public` permissions.


</div>


---

---
title: "SessionCacheStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## SessionCacheStrategy

<GenerationInfo sourceFile="packages/core/src/config/session-cache/session-cache-strategy.ts" sourceLine="164" packageName="@vendure/core" />

This strategy defines how sessions get cached. Since most requests will need the Session
object for permissions data, it can become a bottleneck to go to the database and do a multi-join
SQL query each time. Therefore, we cache the session data only perform the SQL query once and upon
invalidation of the cache.

The Vendure default from v3.1+ is to use a the <a href='/reference/typescript-api/auth/default-session-cache-strategy#defaultsessioncachestrategy'>DefaultSessionCacheStrategy</a>, which delegates
to the configured <a href='/reference/typescript-api/cache/cache-strategy#cachestrategy'>CacheStrategy</a> to store the session data. This should be suitable
for most use-cases.

:::note

If you are using v3.1 or later, you should not normally need to implement a custom `SessionCacheStrategy`,
since this is now handled by the <a href='/reference/typescript-api/auth/default-session-cache-strategy#defaultsessioncachestrategy'>DefaultSessionCacheStrategy</a>.

:::

Prior to v3.1, the default was to use the <a href='/reference/typescript-api/auth/in-memory-session-cache-strategy#inmemorysessioncachestrategy'>InMemorySessionCacheStrategy</a>, which is fast but suitable for
single-instance deployments.

:::info

This is configured via the `authOptions.sessionCacheStrategy` property of
your VendureConfig.

:::

Here's an example implementation using Redis. To use this, you need to add the
[ioredis package](https://www.npmjs.com/package/ioredis) as a dependency.

*Example*

```ts
import { CachedSession, Logger, SessionCacheStrategy, VendurePlugin } from '@vendure/core';
import { Redis, RedisOptions } from 'ioredis';

export interface RedisSessionCachePluginOptions {
  namespace?: string;
  redisOptions?: RedisOptions;
}
const loggerCtx = 'RedisSessionCacheStrategy';
const DEFAULT_NAMESPACE = 'vendure-session-cache';
const DEFAULT_TTL = 86400;

export class RedisSessionCacheStrategy implements SessionCacheStrategy {
  private client: Redis;
  constructor(private options: RedisSessionCachePluginOptions) {}

  init() {
    this.client = new Redis(this.options.redisOptions as RedisOptions);
    this.client.on('error', err => Logger.error(err.message, loggerCtx, err.stack));
  }

  async destroy() {
    await this.client.quit();
  }

  async get(sessionToken: string): Promise<CachedSession | undefined> {
    try {
      const retrieved = await this.client.get(this.namespace(sessionToken));
      if (retrieved) {
        try {
          return JSON.parse(retrieved);
        } catch (e: any) {
          Logger.error(`Could not parse cached session data: ${e.message}`, loggerCtx);
        }
      }
    } catch (e: any) {
      Logger.error(`Could not get cached session: ${e.message}`, loggerCtx);
    }
  }

  async set(session: CachedSession) {
    try {
      await this.client.set(this.namespace(session.token), JSON.stringify(session), 'EX', DEFAULT_TTL);
    } catch (e: any) {
      Logger.error(`Could not set cached session: ${e.message}`, loggerCtx);
    }
  }

  async delete(sessionToken: string) {
    try {
      await this.client.del(this.namespace(sessionToken));
    } catch (e: any) {
      Logger.error(`Could not delete cached session: ${e.message}`, loggerCtx);
    }
  }

  clear() {
    // not implemented
  }

  private namespace(key: string) {
    return `${this.options.namespace ?? DEFAULT_NAMESPACE}:${key}`;
  }
}

@VendurePlugin({
  configuration: config => {
    config.authOptions.sessionCacheStrategy = new RedisSessionCacheStrategy(
      RedisSessionCachePlugin.options,
    );
    return config;
  },
})
export class RedisSessionCachePlugin {
  static options: RedisSessionCachePluginOptions;
  static init(options: RedisSessionCachePluginOptions) {
    this.options = options;
    return this;
  }
}
```

```ts title="Signature"
interface SessionCacheStrategy extends InjectableStrategy {
    set(session: CachedSession): void | Promise<void>;
    get(sessionToken: string): CachedSession | undefined | Promise<CachedSession | undefined>;
    delete(sessionToken: string): void | Promise<void>;
    clear(): void | Promise<void>;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### set

<MemberInfo kind="method" type={`(session: <a href='/reference/typescript-api/auth/session-cache-strategy#cachedsession'>CachedSession</a>) => void | Promise&#60;void&#62;`}   />

Store the session in the cache. When caching a session, the data
should not be modified apart from performing any transforms needed to
get it into a state to be stored, e.g. JSON.stringify().
### get

<MemberInfo kind="method" type={`(sessionToken: string) => <a href='/reference/typescript-api/auth/session-cache-strategy#cachedsession'>CachedSession</a> | undefined | Promise&#60;<a href='/reference/typescript-api/auth/session-cache-strategy#cachedsession'>CachedSession</a> | undefined&#62;`}   />

Retrieve the session from the cache
### delete

<MemberInfo kind="method" type={`(sessionToken: string) => void | Promise&#60;void&#62;`}   />

Delete a session from the cache
### clear

<MemberInfo kind="method" type={`() => void | Promise&#60;void&#62;`}   />

Clear the entire cache


</div>


## CachedSessionUser

<GenerationInfo sourceFile="packages/core/src/config/session-cache/session-cache-strategy.ts" sourceLine="14" packageName="@vendure/core" />

A simplified representation of the User associated with the
current Session.

```ts title="Signature"
type CachedSessionUser = {
    id: ID;
    identifier: string;
    verified: boolean;
    channelPermissions: UserChannelPermissions[];
}
```

<div className="members-wrapper">

### id

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a>`}   />


### identifier

<MemberInfo kind="property" type={`string`}   />


### verified

<MemberInfo kind="property" type={`boolean`}   />


### channelPermissions

<MemberInfo kind="property" type={`UserChannelPermissions[]`}   />




</div>


## CachedSession

<GenerationInfo sourceFile="packages/core/src/config/session-cache/session-cache-strategy.ts" sourceLine="29" packageName="@vendure/core" />

A simplified representation of a Session which is easy to
store.

```ts title="Signature"
type CachedSession = {
    cacheExpiry: number;
    id: ID;
    token: string;
    expires: Date;
    activeOrderId?: ID;
    authenticationStrategy?: string;
    user?: CachedSessionUser;
    activeChannelId?: ID;
}
```

<div className="members-wrapper">

### cacheExpiry

<MemberInfo kind="property" type={`number`}   />

The timestamp after which this cache entry is considered stale and
a fresh copy of the data will be set. Based on the `sessionCacheTTL`
option.
### id

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a>`}   />


### token

<MemberInfo kind="property" type={`string`}   />


### expires

<MemberInfo kind="property" type={`Date`}   />


### activeOrderId

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a>`}   />


### authenticationStrategy

<MemberInfo kind="property" type={`string`}   />


### user

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/auth/session-cache-strategy#cachedsessionuser'>CachedSessionUser</a>`}   />


### activeChannelId

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a>`}   />




</div>


---

---
title: "SuperadminCredentials"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## SuperadminCredentials

<GenerationInfo sourceFile="packages/core/src/config/vendure-config.ts" sourceLine="850" packageName="@vendure/core" />

These credentials will be used to create the Superadmin user & administrator
when Vendure first bootstraps.

```ts title="Signature"
interface SuperadminCredentials {
    identifier: string;
    password: string;
}
```

<div className="members-wrapper">

### identifier

<MemberInfo kind="property" type={`string`} default={`'superadmin'`}   />

The identifier to be used to create a superadmin account
### password

<MemberInfo kind="property" type={`string`} default={`'superadmin'`}   />

The password to be used to create a superadmin account


</div>


---

---
title: "VerificationTokenStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## VerificationTokenStrategy

<GenerationInfo sourceFile="packages/core/src/config/auth/verification-token-strategy.ts" sourceLine="18" packageName="@vendure/core" since="3.2.0" />

Defines a custom strategy for creating and validating verification tokens.

:::info

This is configured via the `authOptions.verificationTokenStrategy` property of
your VendureConfig.

:::

```ts title="Signature"
interface VerificationTokenStrategy extends InjectableStrategy {
    generateVerificationToken(ctx: RequestContext): Promise<string> | string;
    verifyVerificationToken(ctx: RequestContext, token: string): Promise<boolean> | boolean;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### generateVerificationToken

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => Promise&#60;string&#62; | string`}  since="3.2.0"  />

Generates a verification token.
### verifyVerificationToken

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, token: string) => Promise&#60;boolean&#62; | boolean`}  since="3.2.0"  />

Checks the validity of a verification token.


</div>


---

---
title: "CacheConfig"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## CacheConfig

<GenerationInfo sourceFile="packages/core/src/cache/cache.ts" sourceLine="14" packageName="@vendure/core" since="3.1.0" />

Configuration for a new <a href='/reference/typescript-api/cache/#cache'>Cache</a> instance.

```ts title="Signature"
interface CacheConfig {
    getKey: (id: string | number) => string;
    options?: SetCacheKeyOptions;
}
```

<div className="members-wrapper">

### getKey

<MemberInfo kind="property" type={`(id: string | number) =&#62; string`}   />

A function which generates a cache key from the given id.
This key will be used to store the value in the cache.

By convention, the key should be namespaced to avoid conflicts.

*Example*

```ts
getKey: id => `MyStrategy:getProductVariantIds:${id}`,
```
### options

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/cache/cache-strategy#setcachekeyoptions'>SetCacheKeyOptions</a>`}   />

Options available when setting the value in the cache.


</div>


---

---
title: "CacheService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## CacheService

<GenerationInfo sourceFile="packages/core/src/cache/cache.service.ts" sourceLine="21" packageName="@vendure/core" since="3.1.0" />

The CacheService is used to cache data in order to optimize performance.

Internally it makes use of the configured <a href='/reference/typescript-api/cache/cache-strategy#cachestrategy'>CacheStrategy</a> to persist
the cache into a key-value store.

```ts title="Signature"
class CacheService {
    protected cacheStrategy: CacheStrategy;
    constructor(configService: ConfigService)
    createCache(config: CacheConfig) => Cache;
    get(key: string) => Promise<T | undefined>;
    set(key: string, value: T, options?: SetCacheKeyOptions) => Promise<void>;
    delete(key: string) => Promise<void>;
    invalidateTags(tags: string[]) => Promise<void>;
}
```

<div className="members-wrapper">

### cacheStrategy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/cache/cache-strategy#cachestrategy'>CacheStrategy</a>`}   />


### constructor

<MemberInfo kind="method" type={`(configService: ConfigService) => CacheService`}   />


### createCache

<MemberInfo kind="method" type={`(config: <a href='/reference/typescript-api/cache/cache-config#cacheconfig'>CacheConfig</a>) => <a href='/reference/typescript-api/cache/#cache'>Cache</a>`}   />

Creates a new <a href='/reference/typescript-api/cache/#cache'>Cache</a> instance with the given configuration.

The `Cache` instance provides a convenience wrapper around the `CacheService`
methods.
### get

<MemberInfo kind="method" type={`(key: string) => Promise&#60;T | undefined&#62;`}   />

Gets an item from the cache, or returns undefined if the key is not found, or the
item has expired.
### set

<MemberInfo kind="method" type={`(key: string, value: T, options?: <a href='/reference/typescript-api/cache/cache-strategy#setcachekeyoptions'>SetCacheKeyOptions</a>) => Promise&#60;void&#62;`}   />

Sets a key-value pair in the cache. The value must be serializable, so cannot contain
things like functions, circular data structures, class instances etc.

Optionally a "time to live" (ttl) can be specified, which means that the key will
be considered stale after that many milliseconds.
### delete

<MemberInfo kind="method" type={`(key: string) => Promise&#60;void&#62;`}   />

Deletes an item from the cache.
### invalidateTags

<MemberInfo kind="method" type={`(tags: string[]) => Promise&#60;void&#62;`}   />

Deletes all items from the cache which contain at least one matching tag.


</div>


---

---
title: "CacheStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## CacheStrategy

<GenerationInfo sourceFile="packages/core/src/config/system/cache-strategy.ts" sourceLine="53" packageName="@vendure/core" since="3.1.0" />

The CacheStrategy defines how the underlying shared cache mechanism is implemented.

It is used by the <a href='/reference/typescript-api/cache/cache-service#cacheservice'>CacheService</a> to take care of storage and retrieval of items
from the cache.

If you are using the `DefaultCachePlugin` or the `RedisCachePlugin`, you will not need to
manually specify a CacheStrategy, as these plugins will automatically configure the
appropriate strategy.

:::info

This is configured via the `systemOptions.cacheStrategy` property of
your VendureConfig.

:::

```ts title="Signature"
interface CacheStrategy extends InjectableStrategy {
    get<T extends JsonCompatible<T>>(key: string): Promise<T | undefined>;
    set<T extends JsonCompatible<T>>(key: string, value: T, options?: SetCacheKeyOptions): Promise<void>;
    delete(key: string): Promise<void>;
    invalidateTags(tags: string[]): Promise<void>;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### get

<MemberInfo kind="method" type={`(key: string) => Promise&#60;T | undefined&#62;`}   />

Gets an item from the cache, or returns undefined if the key is not found, or the
item has expired.
### set

<MemberInfo kind="method" type={`(key: string, value: T, options?: <a href='/reference/typescript-api/cache/cache-strategy#setcachekeyoptions'>SetCacheKeyOptions</a>) => Promise&#60;void&#62;`}   />

Sets a key-value pair in the cache. The value must be serializable, so cannot contain
things like functions, circular data structures, class instances etc.

Optionally a "time to live" (ttl) can be specified, which means that the key will
be considered stale after that many milliseconds.
### delete

<MemberInfo kind="method" type={`(key: string) => Promise&#60;void&#62;`}   />

Deletes an item from the cache.
### invalidateTags

<MemberInfo kind="method" type={`(tags: string[]) => Promise&#60;void&#62;`}   />

Deletes all items from the cache which contain at least one matching tag.


</div>


## SetCacheKeyOptions

<GenerationInfo sourceFile="packages/core/src/config/system/cache-strategy.ts" sourceLine="13" packageName="@vendure/core" since="3.1.0" />

Options available when setting the value in the cache.

```ts title="Signature"
interface SetCacheKeyOptions {
    ttl?: number;
    tags?: string[];
}
```

<div className="members-wrapper">

### ttl

<MemberInfo kind="property" type={`number`}   />

The time-to-live for the cache key in milliseconds. This means
that after this time period, the key will be considered stale
and will no longer be returned from the cache. Omitting
this is equivalent to having an infinite ttl.
### tags

<MemberInfo kind="property" type={`string[]`}   />

An array of tags which can be used to group cache keys together.
This can be useful for bulk deletion of related keys.


</div>


---

---
title: "DefaultCachePlugin"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DefaultCachePlugin

<GenerationInfo sourceFile="packages/core/src/plugin/default-cache-plugin/default-cache-plugin.ts" sourceLine="48" packageName="@vendure/core" since="3.1.0" />

This plugin provides a simple SQL-based cache strategy <a href='/reference/typescript-api/cache/sql-cache-strategy#sqlcachestrategy'>SqlCacheStrategy</a> which stores cached
items in the database.

It is suitable for production use (including multi-instance setups). For increased performance
you can also consider using the <a href='/reference/typescript-api/cache/redis-cache-plugin#rediscacheplugin'>RedisCachePlugin</a>.

```ts title="Signature"
class DefaultCachePlugin {
    static options: DefaultCachePluginInitOptions = {
        cacheSize: 10_000,
    };
    init(options: DefaultCachePluginInitOptions) => ;
}
```

<div className="members-wrapper">

### options

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/cache/default-cache-plugin#defaultcacheplugininitoptions'>DefaultCachePluginInitOptions</a>`}   />


### init

<MemberInfo kind="method" type={`(options: <a href='/reference/typescript-api/cache/default-cache-plugin#defaultcacheplugininitoptions'>DefaultCachePluginInitOptions</a>) => `}   />




</div>


## DefaultCachePluginInitOptions

<GenerationInfo sourceFile="packages/core/src/plugin/default-cache-plugin/default-cache-plugin.ts" sourceLine="18" packageName="@vendure/core" since="3.1.0" />

Configuration options for the <a href='/reference/typescript-api/cache/default-cache-plugin#defaultcacheplugin'>DefaultCachePlugin</a>.

```ts title="Signature"
interface DefaultCachePluginInitOptions {
    cacheSize?: number;
    cacheTtlProvider?: CacheTtlProvider;
}
```

<div className="members-wrapper">

### cacheSize

<MemberInfo kind="property" type={`number`} default={`10_000`}   />

The maximum number of items to store in the cache. Once the cache reaches this size,
the least-recently-used items will be evicted to make room for new items.
### cacheTtlProvider

<MemberInfo kind="property" type={`CacheTtlProvider`}   />

Optionally provide a custom CacheTtlProvider to control the TTL of cache items.
This is useful for testing.


</div>


---

---
title: "Cache"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## Cache

<GenerationInfo sourceFile="packages/core/src/cache/cache.ts" sourceLine="72" packageName="@vendure/core" since="3.1.0" />

A convenience wrapper around the <a href='/reference/typescript-api/cache/cache-service#cacheservice'>CacheService</a> methods which provides a simple
API for caching and retrieving data.

The advantage of using the `Cache` class rather than directly calling the `CacheService`
methods is that it allows you to define a consistent way of generating cache keys and
to set default cache options, and takes care of setting the value in cache if it does not
already exist.

In most cases, using the `Cache` class will result in simpler and more readable code.

This class is normally created via the <a href='/reference/typescript-api/cache/cache-service#cacheservice'>CacheService</a>.`createCache()` method.

*Example*

```ts
const cache = cacheService.createCache({
  getKey: id => `ProductVariantIds:${id}`,
  options: {
    ttl: 1000 * 60 * 60,
    tags: ['products'],
  },
});

// This will fetch the value from the cache if it exists, or
// fetch it from the ProductService if not, and then cache
// using the key 'ProductVariantIds.${id}'.
const variantIds = await cache.get(id, async () => {
  const variants await ProductService.getVariantsByProductId(ctx, id) ;
  // The cached value must be serializable, so we just return the ids
  return variants.map(v => v.id);
});
```

```ts title="Signature"
class Cache {
    constructor(config: CacheConfig, cacheService: CacheService)
    get(id: string | number, getValueFn: () => T | Promise<T>) => Promise<T>;
    delete(id: string | number | Array<string | number>) => Promise<void>;
    invalidateTags(tags: string[]) => Promise<void>;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(config: <a href='/reference/typescript-api/cache/cache-config#cacheconfig'>CacheConfig</a>, cacheService: <a href='/reference/typescript-api/cache/cache-service#cacheservice'>CacheService</a>) => Cache`}   />


### get

<MemberInfo kind="method" type={`(id: string | number, getValueFn: () =&#62; T | Promise&#60;T&#62;) => Promise&#60;T&#62;`}   />

Retrieves the value from the cache if it exists, otherwise calls the `getValueFn` function
to get the value, sets it in the cache and returns it.
### delete

<MemberInfo kind="method" type={`(id: string | number | Array&#60;string | number&#62;) => Promise&#60;void&#62;`}   />

Deletes one or more items from the cache.
### invalidateTags

<MemberInfo kind="method" type={`(tags: string[]) => Promise&#60;void&#62;`}   />

Invalidates one or more tags in the cache.


</div>


---

---
title: "RedisCachePlugin"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## RedisCachePlugin

<GenerationInfo sourceFile="packages/core/src/plugin/redis-cache-plugin/redis-cache-plugin.ts" sourceLine="25" packageName="@vendure/core" since="3.1.0" />

This plugin provides a Redis-based <a href='/reference/typescript-api/cache/redis-cache-strategy#rediscachestrategy'>RedisCacheStrategy</a> which stores cached items in a Redis instance.
This is a high-performance cache strategy which is suitable for production use, and is a drop-in
replacement for the <a href='/reference/typescript-api/cache/default-cache-plugin#defaultcacheplugin'>DefaultCachePlugin</a>.

Note: To use this plugin, you need to manually install the `ioredis` package:

```shell
npm install ioredis@^5.3.2
```

```ts title="Signature"
class RedisCachePlugin {
    static options: RedisCachePluginInitOptions = {
        maxItemSizeInBytes: 128_000,
        redisOptions: {},
        namespace: 'vendure-cache',
    };
    init(options: RedisCachePluginInitOptions) => ;
}
```

<div className="members-wrapper">

### options

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/cache/redis-cache-plugin#rediscacheplugininitoptions'>RedisCachePluginInitOptions</a>`}   />


### init

<MemberInfo kind="method" type={`(options: <a href='/reference/typescript-api/cache/redis-cache-plugin#rediscacheplugininitoptions'>RedisCachePluginInitOptions</a>) => `}   />




</div>


## RedisCachePluginInitOptions

<GenerationInfo sourceFile="packages/core/src/plugin/redis-cache-plugin/types.ts" sourceLine="9" packageName="@vendure/core" since="3.1.0" />

Configuration options for the <a href='/reference/typescript-api/cache/redis-cache-plugin#rediscacheplugin'>RedisCachePlugin</a>.

```ts title="Signature"
interface RedisCachePluginInitOptions {
    maxItemSizeInBytes?: number;
    namespace?: string;
    redisOptions?: import('ioredis').RedisOptions;
}
```

<div className="members-wrapper">

### maxItemSizeInBytes

<MemberInfo kind="property" type={`number`} default={`128kb`}   />

The maximum size of a single cache item in bytes. If a cache item exceeds this size, it will not be stored
and an error will be logged.
### namespace

<MemberInfo kind="property" type={`string`} default={`'vendure-cache'`}   />

The namespace to use for all keys stored in Redis. This can be useful if you are sharing a Redis instance
between multiple applications.
### redisOptions

<MemberInfo kind="property" type={`import('ioredis').RedisOptions`}   />

Options to pass to the `ioredis` Redis client.


</div>


---

---
title: "RedisCacheStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## RedisCacheStrategy

<GenerationInfo sourceFile="packages/core/src/plugin/redis-cache-plugin/redis-cache-strategy.ts" sourceLine="23" packageName="@vendure/core" since="3.1.0" />

A <a href='/reference/typescript-api/cache/cache-strategy#cachestrategy'>CacheStrategy</a> which stores cached items in a Redis instance.
This is a high-performance cache strategy which is suitable for production use.

Note: To use this strategy, you need to manually install the `ioredis` package:

```shell
npm install ioredis@^5.3.2
```

```ts title="Signature"
class RedisCacheStrategy implements CacheStrategy {
    constructor(options: RedisCachePluginInitOptions)
    init() => ;
    destroy() => ;
    get(key: string) => Promise<T | undefined>;
    set(key: string, value: T, options?: SetCacheKeyOptions) => Promise<void>;
    delete(key: string) => Promise<void>;
    invalidateTags(tags: string[]) => Promise<void>;
}
```
* Implements: <code><a href='/reference/typescript-api/cache/cache-strategy#cachestrategy'>CacheStrategy</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(options: <a href='/reference/typescript-api/cache/redis-cache-plugin#rediscacheplugininitoptions'>RedisCachePluginInitOptions</a>) => RedisCacheStrategy`}   />


### init

<MemberInfo kind="method" type={`() => `}   />


### destroy

<MemberInfo kind="method" type={`() => `}   />


### get

<MemberInfo kind="method" type={`(key: string) => Promise&#60;T | undefined&#62;`}   />


### set

<MemberInfo kind="method" type={`(key: string, value: T, options?: <a href='/reference/typescript-api/cache/cache-strategy#setcachekeyoptions'>SetCacheKeyOptions</a>) => Promise&#60;void&#62;`}   />


### delete

<MemberInfo kind="method" type={`(key: string) => Promise&#60;void&#62;`}   />


### invalidateTags

<MemberInfo kind="method" type={`(tags: string[]) => Promise&#60;void&#62;`}   />




</div>


---

---
title: "RequestContextCacheService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## RequestContextCacheService

<GenerationInfo sourceFile="packages/core/src/cache/request-context-cache.service.ts" sourceLine="15" packageName="@vendure/core" />

This service is used to cache arbitrary data relative to an ongoing request.
It does this by using a WeakMap bound to the current RequestContext, so the cached
data is available for the duration of the request. Once the request completes, the
cached data will be automatically garbage-collected.

This is useful for caching data which is expensive to compute and which is needed
multiple times during the handling of a single request.

```ts title="Signature"
class RequestContextCacheService {
    set(ctx: RequestContext, key: any, val: T) => void;
    get(ctx: RequestContext, key: any) => T | undefined;
    get(ctx: RequestContext, key: any, getDefault?: () => T) => T;
    get(ctx: RequestContext, key: any, getDefault?: () => T) => T | Promise<T> | undefined;
}
```

<div className="members-wrapper">

### set

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, key: any, val: T) => void`}   />

Set a value in the RequestContext cache.
### get

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, key: any) => T | undefined`}   />

Get a value from the RequestContext cache. If the value is not found, the `getDefault`
function will be called to get the value, which will then be cached and returned.
### get

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, key: any, getDefault?: () =&#62; T) => T`}   />


### get

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, key: any, getDefault?: () =&#62; T) => T | Promise&#60;T&#62; | undefined`}   />




</div>


---

---
title: "SelfRefreshingCache"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## SelfRefreshingCache

<GenerationInfo sourceFile="packages/core/src/common/self-refreshing-cache.ts" sourceLine="10" packageName="@vendure/core" />

A cache which automatically refreshes itself if the value is found to be stale.

```ts title="Signature"
interface SelfRefreshingCache<V, RefreshArgs extends any[] = []> {
    value(...refreshArgs: RefreshArgs | [undefined] | []): Promise<V>;
    memoize<Args extends any[], R>(
        args: Args,
        refreshArgs: RefreshArgs,
        fn: (value: V, ...args: Args) => R,
    ): Promise<R>;
    refresh(...args: RefreshArgs): Promise<V>;
}
```

<div className="members-wrapper">

### value

<MemberInfo kind="method" type={`(refreshArgs: RefreshArgs | [undefined] | []) => Promise&#60;V&#62;`}   />

The current value of the cache. If the value is stale, the data will be refreshed and then
the fresh value will be returned.
### memoize

<MemberInfo kind="method" type={`(args: Args, refreshArgs: RefreshArgs, fn: (value: V, ...args: Args) =&#62; R) => Promise&#60;R&#62;`}   />

Allows a memoized function to be defined. For the given arguments, the `fn` function will
be invoked only once and its output cached and returned.
The results cache is cleared along with the rest of the cache according to the configured
`ttl` value.
### refresh

<MemberInfo kind="method" type={`(args: RefreshArgs) => Promise&#60;V&#62;`}   />

Force a refresh of the value, e.g. when it is known that the value has changed such as after
an update operation to the source data in the database.


</div>


## SelfRefreshingCacheConfig

<GenerationInfo sourceFile="packages/core/src/common/self-refreshing-cache.ts" sourceLine="46" packageName="@vendure/core" />

Configuration options for creating a <a href='/reference/typescript-api/cache/self-refreshing-cache#selfrefreshingcache'>SelfRefreshingCache</a>.

```ts title="Signature"
interface SelfRefreshingCacheConfig<V, RefreshArgs extends any[]> {
    name: string;
    ttl: number;
    refresh: {
        fn: (...args: RefreshArgs) => Promise<V>;
        /**
         * Default arguments, passed to refresh function
         */
        defaultArgs: RefreshArgs;
    };
    getTimeFn?: () => number;
}
```

<div className="members-wrapper">

### name

<MemberInfo kind="property" type={`string`}   />

The name of the cache, used for logging purposes.
e.g. `'MyService.cachedValue'`.
### ttl

<MemberInfo kind="property" type={`number`}   />

The time-to-live (ttl) in milliseconds for the cache. After this time, the value will be considered stale
and will be refreshed the next time it is accessed.
### refresh

<MemberInfo kind="property" type={`{         fn: (...args: RefreshArgs) =&#62; Promise&#60;V&#62;;         /**          * Default arguments, passed to refresh function          */         defaultArgs: RefreshArgs;     }`}   />

The function which is used to refresh the value of the cache.
This function should return a Promise which resolves to the new value.
### getTimeFn

<MemberInfo kind="property" type={`() =&#62; number`}   />

Intended for unit testing the SelfRefreshingCache only.
By default uses `() => new Date().getTime()`


</div>


## createSelfRefreshingCache

<GenerationInfo sourceFile="packages/core/src/common/self-refreshing-cache.ts" sourceLine="114" packageName="@vendure/core" />

Creates a <a href='/reference/typescript-api/cache/self-refreshing-cache#selfrefreshingcache'>SelfRefreshingCache</a> object, which is used to cache a single frequently-accessed value. In this type
of cache, the function used to populate the value (`refreshFn`) is defined during the creation of the cache, and
it is immediately used to populate the initial value.

From there, when the `.value` property is accessed, it will return a value from the cache, and if the
value has expired, it will automatically run the `refreshFn` to update the value and then return the
fresh value.

*Example*

```ts title="Example of creating a SelfRefreshingCache"
import { createSelfRefreshingCache } from '@vendure/core';

@Injectable()
export class PublicChannelService {
  private publicChannel: SelfRefreshingCache<Channel, [RequestContext]>;

  async init() {
    this.publicChannel = await createSelfRefreshingCache<Channel, [RequestContext]>({
     name: 'PublicChannelService.publicChannel',
     ttl: 1000 * 60 * 60, // 1 hour
     refresh: {
       fn: async (ctx: RequestContext) => {
        return this.channelService.getPublicChannel(ctx);
      },
     defaultArgs: [RequestContext.empty()],
    },
  });
}
```

```ts title="Signature"
function createSelfRefreshingCache<V, RefreshArgs extends any[]>(config: SelfRefreshingCacheConfig<V, RefreshArgs>, refreshArgs?: RefreshArgs): Promise<SelfRefreshingCache<V, RefreshArgs>>
```
Parameters

### config

<MemberInfo kind="parameter" type={`<a href='/reference/typescript-api/cache/self-refreshing-cache#selfrefreshingcacheconfig'>SelfRefreshingCacheConfig</a>&#60;V, RefreshArgs&#62;`} />

### refreshArgs

<MemberInfo kind="parameter" type={`RefreshArgs`} />



---

---
title: "SqlCacheStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## SqlCacheStrategy

<GenerationInfo sourceFile="packages/core/src/plugin/default-cache-plugin/sql-cache-strategy.ts" sourceLine="21" packageName="@vendure/core" since="3.1.0" />

A <a href='/reference/typescript-api/cache/cache-strategy#cachestrategy'>CacheStrategy</a> that stores cached items in the database. This
is the strategy used by the <a href='/reference/typescript-api/cache/default-cache-plugin#defaultcacheplugin'>DefaultCachePlugin</a>.

```ts title="Signature"
class SqlCacheStrategy implements CacheStrategy {
    protected cacheSize = 10_000;
    protected ttlProvider: CacheTtlProvider;
    constructor(config?: { cacheSize?: number; cacheTtlProvider?: CacheTtlProvider })
    protected connection: TransactionalConnection;
    protected configService: ConfigService;
    init(injector: Injector) => ;
    get(key: string) => Promise<T | undefined>;
    set(key: string, value: T, options?: SetCacheKeyOptions) => ;
    delete(key: string) => ;
    invalidateTags(tags: string[]) => ;
}
```
* Implements: <code><a href='/reference/typescript-api/cache/cache-strategy#cachestrategy'>CacheStrategy</a></code>



<div className="members-wrapper">

### cacheSize

<MemberInfo kind="property" type={``}   />


### ttlProvider

<MemberInfo kind="property" type={`CacheTtlProvider`}   />


### constructor

<MemberInfo kind="method" type={`(config?: { cacheSize?: number; cacheTtlProvider?: CacheTtlProvider }) => SqlCacheStrategy`}   />


### connection

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>`}   />


### configService

<MemberInfo kind="property" type={`ConfigService`}   />


### init

<MemberInfo kind="method" type={`(injector: <a href='/reference/typescript-api/common/injector#injector'>Injector</a>) => `}   />


### get

<MemberInfo kind="method" type={`(key: string) => Promise&#60;T | undefined&#62;`}   />


### set

<MemberInfo kind="method" type={`(key: string, value: T, options?: <a href='/reference/typescript-api/cache/cache-strategy#setcachekeyoptions'>SetCacheKeyOptions</a>) => `}   />


### delete

<MemberInfo kind="method" type={`(key: string) => `}   />


### invalidateTags

<MemberInfo kind="method" type={`(tags: string[]) => `}   />




</div>


---

---
title: "AdminUiAppConfig"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## AdminUiAppConfig

<GenerationInfo sourceFile="packages/common/src/shared-types.ts" sourceLine="355" packageName="@vendure/common" />

Configures the path to a custom-build of the Admin UI app.

```ts title="Signature"
interface AdminUiAppConfig {
    path: string;
    route?: string;
    compile?: () => Promise<void>;
}
```

<div className="members-wrapper">

### path

<MemberInfo kind="property" type={`string`}   />

The path to the compiled admin UI app files. If not specified, an internal
default build is used. This path should contain the `vendure-ui-config.json` file,
index.html, the compiled js bundles etc.
### route

<MemberInfo kind="property" type={`string`} default={`'admin'`}   />

Specifies the url route to the Admin UI app.
### compile

<MemberInfo kind="property" type={`() =&#62; Promise&#60;void&#62;`}   />

The function which will be invoked to start the app compilation process.


</div>


---

---
title: "AdminUiAppDevModeConfig"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## AdminUiAppDevModeConfig

<GenerationInfo sourceFile="packages/common/src/shared-types.ts" sourceLine="383" packageName="@vendure/common" />

Information about the Admin UI app dev server.

```ts title="Signature"
interface AdminUiAppDevModeConfig {
    sourcePath: string;
    port: number;
    route?: string;
    compile: () => Promise<void>;
}
```

<div className="members-wrapper">

### sourcePath

<MemberInfo kind="property" type={`string`}   />

The path to the uncompiled UI app source files. This path should contain the `vendure-ui-config.json` file.
### port

<MemberInfo kind="property" type={`number`}   />

The port on which the dev server is listening. Overrides the value set by `AdminUiOptions.port`.
### route

<MemberInfo kind="property" type={`string`} default={`'admin'`}   />

Specifies the url route to the Admin UI app.
### compile

<MemberInfo kind="property" type={`() =&#62; Promise&#60;void&#62;`}   />

The function which will be invoked to start the app compilation process.


</div>


---

---
title: "AdminUiConfig"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## AdminUiConfig

<GenerationInfo sourceFile="packages/common/src/shared-types.ts" sourceLine="221" packageName="@vendure/common" />

This interface describes JSON config file (vendure-ui-config.json) used by the Admin UI.
The values are loaded at run-time by the Admin UI app, and allow core configuration to be
managed without the need to re-build the application.

```ts title="Signature"
interface AdminUiConfig {
    apiHost: string | 'auto';
    apiPort: number | 'auto';
    adminApiPath: string;
    tokenMethod: 'cookie' | 'bearer';
    authTokenHeaderKey: string;
    channelTokenKey: string;
    defaultLanguage: LanguageCode;
    defaultLocale?: string;
    availableLanguages: LanguageCode[];
    availableLocales: string[];
    loginUrl?: string;
    brand?: string;
    hideVendureBranding?: boolean;
    hideVersion?: boolean;
    loginImageUrl?: string;
    cancellationReasons?: string[];
}
```

<div className="members-wrapper">

### apiHost

<MemberInfo kind="property" type={`string | 'auto'`} default={`'auto'`}   />

The hostname of the Vendure server which the admin UI will be making API calls
to. If set to "auto", the Admin UI app will determine the hostname from the
current location (i.e. `window.location.hostname`).
### apiPort

<MemberInfo kind="property" type={`number | 'auto'`} default={`'auto'`}   />

The port of the Vendure server which the admin UI will be making API calls
to. If set to "auto", the Admin UI app will determine the port from the
current location (i.e. `window.location.port`).
### adminApiPath

<MemberInfo kind="property" type={`string`} default={`'admin-api'`}   />

The path to the GraphQL Admin API.
### tokenMethod

<MemberInfo kind="property" type={`'cookie' | 'bearer'`} default={`'cookie'`}   />

Whether to use cookies or bearer tokens to track sessions.
Should match the setting of in the server's `tokenMethod` config
option.
### authTokenHeaderKey

<MemberInfo kind="property" type={`string`} default={`'vendure-auth-token'`}   />

The header used when using the 'bearer' auth method. Should match the
setting of the server's `authOptions.authTokenHeaderKey` config option.
### channelTokenKey

<MemberInfo kind="property" type={`string`} default={`'vendure-token'`}   />

The name of the header which contains the channel token. Should match the
setting of the server's `apiOptions.channelTokenKey` config option.
### defaultLanguage

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a>`} default={`<a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a>.en`}   />

The default language for the Admin UI. Must be one of the
items specified in the `availableLanguages` property.
### defaultLocale

<MemberInfo kind="property" type={`string`}  since="2.2.0"  />

The default locale for the Admin UI. The locale affects the formatting of
currencies & dates. Must be one of the items specified
in the `availableLocales` property.

If not set, the browser default locale will be used.
### availableLanguages

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a>[]`}   />

An array of languages for which translations exist for the Admin UI.
### availableLocales

<MemberInfo kind="property" type={`string[]`}  since="2.2.0"  />

An array of locales to be used on Admin UI.
### loginUrl

<MemberInfo kind="property" type={`string`}   />

If you are using an external <a href='/reference/typescript-api/auth/authentication-strategy#authenticationstrategy'>AuthenticationStrategy</a> for the Admin API, you can configure
a custom URL for the login page with this option. On logging out or redirecting an unauthenticated
user, the Admin UI app will redirect the user to this URL rather than the default username/password
screen.
### brand

<MemberInfo kind="property" type={`string`}   />

The custom brand name.
### hideVendureBranding

<MemberInfo kind="property" type={`boolean`} default={`false`}   />

Option to hide vendure branding.
### hideVersion

<MemberInfo kind="property" type={`boolean`} default={`false`}   />

Option to hide version.
### loginImageUrl

<MemberInfo kind="property" type={`string`}  since="1.9.0"  />

A url of a custom image to be used on the login screen, to override the images provided by Vendure's login image server.
### cancellationReasons

<MemberInfo kind="property" type={`string[]`} default={`['order.cancel-reason-customer-request', 'order.cancel-reason-not-available']`}  since="1.5.0"  />

Allows you to provide default reasons for a refund or cancellation. This will be used in the
refund/cancel dialog. The values can be literal strings (e.g. "Not in stock") or translation
tokens (see [Adding Admin UI Translations](/guides/extending-the-admin-ui/adding-ui-translations/)).


</div>


---

---
title: "Admin Ui"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "AsyncQueue"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## AsyncQueue

<GenerationInfo sourceFile="packages/core/src/common/async-queue.ts" sourceLine="13" packageName="@vendure/core" />

A queue class for limiting concurrent async tasks. This can be used e.g. to prevent
race conditions when working on a shared resource such as writing to a database.

```ts title="Signature"
class AsyncQueue {
    constructor(label: string = 'default', concurrency: number = 1)
    push(task: Task<T>) => Promise<T>;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(label: string = 'default', concurrency: number = 1) => AsyncQueue`}   />


### push

<MemberInfo kind="method" type={`(task: Task&#60;T&#62;) => Promise&#60;T&#62;`}   />

Pushes a new task onto the queue, upon which the task will either execute immediately or
(if the number of running tasks is equal to the concurrency limit) enqueue the task to
be executed at the soonest opportunity.


</div>


---

---
title: "Bootstrap"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## bootstrap

<GenerationInfo sourceFile="packages/core/src/bootstrap.ts" sourceLine="160" packageName="@vendure/core" />

Bootstraps the Vendure server. This is the entry point to the application.

*Example*

```ts
import { bootstrap } from '@vendure/core';
import { config } from './vendure-config';

bootstrap(config).catch(err => {
  console.log(err);
  process.exit(1);
});
```

### Passing additional options

Since v2.2.0, you can pass additional options to the NestJs application via the `options` parameter.
For example, to integrate with the [Nest Devtools](https://docs.nestjs.com/devtools/overview), you need to
pass the `snapshot` option:

```ts
import { bootstrap } from '@vendure/core';
import { config } from './vendure-config';

bootstrap(config, {
  // highlight-start
  nestApplicationOptions: {
    snapshot: true,
  }
  // highlight-end
}).catch(err => {
  console.log(err);
  process.exit(1);
});
```

### Ignoring compatibility errors for plugins

Since v3.1.0, you can ignore compatibility errors for specific plugins by passing the `ignoreCompatibilityErrorsForPlugins` option.

This should be used with caution, only if you are sure that the plugin will still work as expected with the current version of Vendure.

*Example*

```ts
import { bootstrap } from '@vendure/core';
import { config } from './vendure-config';
import { MyPlugin } from './plugins/my-plugin';

bootstrap(config, {
  // Let's say that `MyPlugin` is not yet compatible with the current version of Vendure
  // but we know that it will still work as expected, and we are not able to publish
  // a new version of the plugin right now.
  ignoreCompatibilityErrorsForPlugins: [MyPlugin],
});
```

```ts title="Signature"
function bootstrap(userConfig: Partial<VendureConfig>, options?: BootstrapOptions): Promise<INestApplication>
```
Parameters

### userConfig

<MemberInfo kind="parameter" type={`Partial&#60;<a href='/reference/typescript-api/configuration/vendure-config#vendureconfig'>VendureConfig</a>&#62;`} />

### options

<MemberInfo kind="parameter" type={`<a href='/reference/typescript-api/common/bootstrap#bootstrapoptions'>BootstrapOptions</a>`} />



## BootstrapOptions

<GenerationInfo sourceFile="packages/core/src/bootstrap.ts" sourceLine="42" packageName="@vendure/core" since="2.2.0" />

Additional options that can be used to configure the bootstrap process of the
Vendure server.

```ts title="Signature"
interface BootstrapOptions {
    nestApplicationOptions?: NestApplicationOptions;
    ignoreCompatibilityErrorsForPlugins?: Array<DynamicModule | Type<any>>;
}
```

<div className="members-wrapper">

### nestApplicationOptions

<MemberInfo kind="property" type={`NestApplicationOptions`}   />

These options get passed directly to the `NestFactory.create()` method.
### ignoreCompatibilityErrorsForPlugins

<MemberInfo kind="property" type={`Array&#60;DynamicModule | Type&#60;any&#62;&#62;`} default={`[]`}  since="3.1.0"  />

By default, if a plugin specifies a compatibility range which does not include the current
Vendure version, the bootstrap process will fail. This option allows you to ignore compatibility
errors for specific plugins.

This setting should be used with caution, only if you are sure that the plugin will still
work as expected with the current version of Vendure.

*Example*

```ts
import { bootstrap } from '@vendure/core';
import { config } from './vendure-config';
import { MyPlugin } from './plugins/my-plugin';

bootstrap(config, {
 ignoreCompatibilityErrorsForPlugins: [MyPlugin],
});
```


</div>


---

---
title: "CurrencyCode"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## CurrencyCode

<GenerationInfo sourceFile="packages/common/src/generated-types.ts" sourceLine="1002" packageName="@vendure/common" />

ISO 4217 currency code

```ts title="Signature"
enum CurrencyCode {
    AED = 'AED'
    AFN = 'AFN'
    ALL = 'ALL'
    AMD = 'AMD'
    ANG = 'ANG'
    AOA = 'AOA'
    ARS = 'ARS'
    AUD = 'AUD'
    AWG = 'AWG'
    AZN = 'AZN'
    BAM = 'BAM'
    BBD = 'BBD'
    BDT = 'BDT'
    BGN = 'BGN'
    BHD = 'BHD'
    BIF = 'BIF'
    BMD = 'BMD'
    BND = 'BND'
    BOB = 'BOB'
    BRL = 'BRL'
    BSD = 'BSD'
    BTN = 'BTN'
    BWP = 'BWP'
    BYN = 'BYN'
    BZD = 'BZD'
    CAD = 'CAD'
    CDF = 'CDF'
    CHF = 'CHF'
    CLP = 'CLP'
    CNY = 'CNY'
    COP = 'COP'
    CRC = 'CRC'
    CUC = 'CUC'
    CUP = 'CUP'
    CVE = 'CVE'
    CZK = 'CZK'
    DJF = 'DJF'
    DKK = 'DKK'
    DOP = 'DOP'
    DZD = 'DZD'
    EGP = 'EGP'
    ERN = 'ERN'
    ETB = 'ETB'
    EUR = 'EUR'
    FJD = 'FJD'
    FKP = 'FKP'
    GBP = 'GBP'
    GEL = 'GEL'
    GHS = 'GHS'
    GIP = 'GIP'
    GMD = 'GMD'
    GNF = 'GNF'
    GTQ = 'GTQ'
    GYD = 'GYD'
    HKD = 'HKD'
    HNL = 'HNL'
    HRK = 'HRK'
    HTG = 'HTG'
    HUF = 'HUF'
    IDR = 'IDR'
    ILS = 'ILS'
    INR = 'INR'
    IQD = 'IQD'
    IRR = 'IRR'
    ISK = 'ISK'
    JMD = 'JMD'
    JOD = 'JOD'
    JPY = 'JPY'
    KES = 'KES'
    KGS = 'KGS'
    KHR = 'KHR'
    KMF = 'KMF'
    KPW = 'KPW'
    KRW = 'KRW'
    KWD = 'KWD'
    KYD = 'KYD'
    KZT = 'KZT'
    LAK = 'LAK'
    LBP = 'LBP'
    LKR = 'LKR'
    LRD = 'LRD'
    LSL = 'LSL'
    LYD = 'LYD'
    MAD = 'MAD'
    MDL = 'MDL'
    MGA = 'MGA'
    MKD = 'MKD'
    MMK = 'MMK'
    MNT = 'MNT'
    MOP = 'MOP'
    MRU = 'MRU'
    MUR = 'MUR'
    MVR = 'MVR'
    MWK = 'MWK'
    MXN = 'MXN'
    MYR = 'MYR'
    MZN = 'MZN'
    NAD = 'NAD'
    NGN = 'NGN'
    NIO = 'NIO'
    NOK = 'NOK'
    NPR = 'NPR'
    NZD = 'NZD'
    OMR = 'OMR'
    PAB = 'PAB'
    PEN = 'PEN'
    PGK = 'PGK'
    PHP = 'PHP'
    PKR = 'PKR'
    PLN = 'PLN'
    PYG = 'PYG'
    QAR = 'QAR'
    RON = 'RON'
    RSD = 'RSD'
    RUB = 'RUB'
    RWF = 'RWF'
    SAR = 'SAR'
    SBD = 'SBD'
    SCR = 'SCR'
    SDG = 'SDG'
    SEK = 'SEK'
    SGD = 'SGD'
    SHP = 'SHP'
    SLL = 'SLL'
    SOS = 'SOS'
    SRD = 'SRD'
    SSP = 'SSP'
    STN = 'STN'
    SVC = 'SVC'
    SYP = 'SYP'
    SZL = 'SZL'
    THB = 'THB'
    TJS = 'TJS'
    TMT = 'TMT'
    TND = 'TND'
    TOP = 'TOP'
    TRY = 'TRY'
    TTD = 'TTD'
    TWD = 'TWD'
    TZS = 'TZS'
    UAH = 'UAH'
    UGX = 'UGX'
    USD = 'USD'
    UYU = 'UYU'
    UZS = 'UZS'
    VES = 'VES'
    VND = 'VND'
    VUV = 'VUV'
    WST = 'WST'
    XAF = 'XAF'
    XCD = 'XCD'
    XOF = 'XOF'
    XPF = 'XPF'
    YER = 'YER'
    ZAR = 'ZAR'
    ZMW = 'ZMW'
    ZWL = 'ZWL'
}
```


---

---
title: "EntityRelationPaths"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## EntityRelationPaths

<GenerationInfo sourceFile="packages/core/src/common/types/entity-relation-paths.ts" sourceLine="25" packageName="@vendure/core" />

This type allows type-safe access to entity relations using strings with dot notation.
It works to 2 levels deep.

*Example*

```ts
type T1 = EntityRelationPaths<Product>;
```
In the above example, the type `T1` will be a string union of all relations of the
`Product` entity:

 * `'featuredAsset'`
 * `'variants'`
 * `'variants.options'`
 * `'variants.featuredAsset'`
 * etc.

```ts title="Signature"
type EntityRelationPaths<T extends VendureEntity> = | `customFields.${string}`
    | PathsToStringProps1<T>
    | Join<PathsToStringProps2<T>, '.'>
    | TripleDotPath
```


---

---
title: "I18nService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## I18nService

<GenerationInfo sourceFile="packages/core/src/i18n/i18n.service.ts" sourceLine="44" packageName="@vendure/core" />



```ts title="Signature"
class I18nService implements OnModuleInit {
    addTranslationFile(langKey: string, filePath: string) => void;
    addTranslation(langKey: string, resources: VendureTranslationResources | any) => void;
}
```
* Implements: <code>OnModuleInit</code>



<div className="members-wrapper">

### addTranslationFile

<MemberInfo kind="method" type={`(langKey: string, filePath: string) => void`}   />

Add a I18n translation by json file
### addTranslation

<MemberInfo kind="method" type={`(langKey: string, resources: <a href='/reference/typescript-api/common/i18n-service#venduretranslationresources'>VendureTranslationResources</a> | any) => void`}   />

Add a I18n translation (key-value) resource


</div>


## VendureTranslationResources

<GenerationInfo sourceFile="packages/core/src/i18n/i18n.service.ts" sourceLine="24" packageName="@vendure/core" />

I18n resources used for translations

```ts title="Signature"
interface VendureTranslationResources {
    error: any;
    errorResult: any;
    message: any;
}
```

<div className="members-wrapper">

### error

<MemberInfo kind="property" type={`any`}   />


### errorResult

<MemberInfo kind="property" type={`any`}   />


### message

<MemberInfo kind="property" type={`any`}   />




</div>


---

---
title: "ID"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ID

<GenerationInfo sourceFile="packages/common/src/shared-types.ts" sourceLine="79" packageName="@vendure/common" />

An entity ID. Depending on the configured <a href='/reference/typescript-api/configuration/entity-id-strategy#entityidstrategy'>EntityIdStrategy</a>, it will be either
a `string` or a `number`;

```ts title="Signature"
type ID = string | number
```


---

---
title: "Common"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "InjectableStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## InjectableStrategy

<GenerationInfo sourceFile="packages/core/src/common/types/injectable-strategy.ts" sourceLine="10" packageName="@vendure/core" />

This interface defines the setup and teardown hooks available to the
various strategies used to configure Vendure.

```ts title="Signature"
interface InjectableStrategy {
    init?: (injector: Injector) => void | Promise<void>;
    destroy?: () => void | Promise<void>;
}
```

<div className="members-wrapper">

### init

<MemberInfo kind="property" type={`(injector: <a href='/reference/typescript-api/common/injector#injector'>Injector</a>) =&#62; void | Promise&#60;void&#62;`}   />

Defines setup logic to be run during application bootstrap. Receives
the <a href='/reference/typescript-api/common/injector#injector'>Injector</a> as an argument, which allows application providers
to be used as part of the setup. This hook will be called on both the
main server and the worker processes.

*Example*

```ts
async init(injector: Injector) {
  const myService = injector.get(MyService);
  await myService.doSomething();
}
```
### destroy

<MemberInfo kind="property" type={`() =&#62; void | Promise&#60;void&#62;`}   />

Defines teardown logic to be run before application shutdown.


</div>


---

---
title: "Injector"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## Injector

<GenerationInfo sourceFile="packages/core/src/common/injector.ts" sourceLine="15" packageName="@vendure/core" />

The Injector wraps the underlying Nestjs `ModuleRef`, allowing injection of providers
known to the application's dependency injection container. This is intended to enable the injection
of services into objects which exist outside of the Nestjs module system, e.g. the various
Strategies which can be supplied in the VendureConfig.

```ts title="Signature"
class Injector {
    constructor(moduleRef: ModuleRef)
    get(typeOrToken: Type<T> | string | symbol) => R;
    resolve(typeOrToken: Type<T> | string | symbol, contextId?: ContextId) => Promise<R>;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(moduleRef: ModuleRef) => Injector`}   />


### get

<MemberInfo kind="method" type={`(typeOrToken: Type&#60;T&#62; | string | symbol) => R`}   />

Retrieve an instance of the given type from the app's dependency injection container.
Wraps the Nestjs `ModuleRef.get()` method.
### resolve

<MemberInfo kind="method" type={`(typeOrToken: Type&#60;T&#62; | string | symbol, contextId?: ContextId) => Promise&#60;R&#62;`}   />

Retrieve an instance of the given scoped provider (transient or request-scoped) from the
app's dependency injection container.
Wraps the Nestjs `ModuleRef.resolve()` method.


</div>


---

---
title: "JobState"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## JobState

<GenerationInfo sourceFile="packages/common/src/generated-types.ts" sourceLine="2246" packageName="@vendure/common" />

The state of a Job in the JobQueue

```ts title="Signature"
enum JobState {
    CANCELLED = 'CANCELLED'
    COMPLETED = 'COMPLETED'
    FAILED = 'FAILED'
    PENDING = 'PENDING'
    RETRYING = 'RETRYING'
    RUNNING = 'RUNNING'
}
```


---

---
title: "JsonCompatible"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## JsonCompatible

<GenerationInfo sourceFile="packages/common/src/shared-types.ts" sourceLine="52" packageName="@vendure/common" />

A type representing JSON-compatible values.
From https://github.com/microsoft/TypeScript/issues/1897#issuecomment-580962081

```ts title="Signature"
type JsonCompatible<T> = {
    [P in keyof T]: T[P] extends Json
        ? T[P]
        : Pick<T, P> extends Required<Pick<T, P>>
          ? never
          : JsonCompatible<T[P]>;
}
```


---

---
title: "LanguageCode"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## LanguageCode

<GenerationInfo sourceFile="packages/common/src/generated-types.ts" sourceLine="2264" packageName="@vendure/common" />

Languages in the form of a ISO 639-1 language code with optional
region or script modifier (e.g. de_AT). The selection available is based
on the [Unicode CLDR summary list](https://unicode-org.github.io/cldr-staging/charts/37/summary/root.html)
and includes the major spoken languages of the world and any widely-used variants.

```ts title="Signature"
enum LanguageCode {
    af = 'af'
    ak = 'ak'
    am = 'am'
    ar = 'ar'
    as = 'as'
    az = 'az'
    be = 'be'
    bg = 'bg'
    bm = 'bm'
    bn = 'bn'
    bo = 'bo'
    br = 'br'
    bs = 'bs'
    ca = 'ca'
    ce = 'ce'
    co = 'co'
    cs = 'cs'
    cu = 'cu'
    cy = 'cy'
    da = 'da'
    de = 'de'
    de_AT = 'de_AT'
    de_CH = 'de_CH'
    dz = 'dz'
    ee = 'ee'
    el = 'el'
    en = 'en'
    en_AU = 'en_AU'
    en_CA = 'en_CA'
    en_GB = 'en_GB'
    en_US = 'en_US'
    eo = 'eo'
    es = 'es'
    es_ES = 'es_ES'
    es_MX = 'es_MX'
    et = 'et'
    eu = 'eu'
    fa = 'fa'
    fa_AF = 'fa_AF'
    ff = 'ff'
    fi = 'fi'
    fo = 'fo'
    fr = 'fr'
    fr_CA = 'fr_CA'
    fr_CH = 'fr_CH'
    fy = 'fy'
    ga = 'ga'
    gd = 'gd'
    gl = 'gl'
    gu = 'gu'
    gv = 'gv'
    ha = 'ha'
    he = 'he'
    hi = 'hi'
    hr = 'hr'
    ht = 'ht'
    hu = 'hu'
    hy = 'hy'
    ia = 'ia'
    id = 'id'
    ig = 'ig'
    ii = 'ii'
    is = 'is'
    it = 'it'
    ja = 'ja'
    jv = 'jv'
    ka = 'ka'
    ki = 'ki'
    kk = 'kk'
    kl = 'kl'
    km = 'km'
    kn = 'kn'
    ko = 'ko'
    ks = 'ks'
    ku = 'ku'
    kw = 'kw'
    ky = 'ky'
    la = 'la'
    lb = 'lb'
    lg = 'lg'
    ln = 'ln'
    lo = 'lo'
    lt = 'lt'
    lu = 'lu'
    lv = 'lv'
    mg = 'mg'
    mi = 'mi'
    mk = 'mk'
    ml = 'ml'
    mn = 'mn'
    mr = 'mr'
    ms = 'ms'
    mt = 'mt'
    my = 'my'
    nb = 'nb'
    nd = 'nd'
    ne = 'ne'
    nl = 'nl'
    nl_BE = 'nl_BE'
    nn = 'nn'
    ny = 'ny'
    om = 'om'
    or = 'or'
    os = 'os'
    pa = 'pa'
    pl = 'pl'
    ps = 'ps'
    pt = 'pt'
    pt_BR = 'pt_BR'
    pt_PT = 'pt_PT'
    qu = 'qu'
    rm = 'rm'
    rn = 'rn'
    ro = 'ro'
    ro_MD = 'ro_MD'
    ru = 'ru'
    rw = 'rw'
    sa = 'sa'
    sd = 'sd'
    se = 'se'
    sg = 'sg'
    si = 'si'
    sk = 'sk'
    sl = 'sl'
    sm = 'sm'
    sn = 'sn'
    so = 'so'
    sq = 'sq'
    sr = 'sr'
    st = 'st'
    su = 'su'
    sv = 'sv'
    sw = 'sw'
    sw_CD = 'sw_CD'
    ta = 'ta'
    te = 'te'
    tg = 'tg'
    th = 'th'
    ti = 'ti'
    tk = 'tk'
    to = 'to'
    tr = 'tr'
    tt = 'tt'
    ug = 'ug'
    uk = 'uk'
    ur = 'ur'
    uz = 'uz'
    vi = 'vi'
    vo = 'vo'
    wo = 'wo'
    xh = 'xh'
    yi = 'yi'
    yo = 'yo'
    zh = 'zh'
    zh_Hans = 'zh_Hans'
    zh_Hant = 'zh_Hant'
    zu = 'zu'
}
```


---

---
title: "Middleware"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## Middleware

<GenerationInfo sourceFile="packages/core/src/common/types/common-types.ts" sourceLine="212" packageName="@vendure/core" />

Defines API middleware, set in the <a href='/reference/typescript-api/configuration/api-options#apioptions'>ApiOptions</a>. Middleware can be either
[Express middleware](https://expressjs.com/en/guide/using-middleware.html) or [NestJS middleware](https://docs.nestjs.com/middleware).

## Increasing the maximum request body size limit

Internally, Vendure relies on the body-parser middleware to parse incoming JSON data. By default, the maximum
body size is set to 100kb. Attempting to send a request with more than 100kb of JSON data will result in a
`PayloadTooLargeError`. To increase this limit, we can manually configure the body-parser middleware:

*Example*

```ts
import { VendureConfig } from '@vendure/core';
import { json } from 'body-parser';

export const config: VendureConfig = {
  // ...
  apiOptions: {
    middleware: [{
      handler: json({ limit: '10mb' }),
      route: '*splat',
      beforeListen: true,
    }],
  },
};
```

```ts title="Signature"
interface Middleware {
    handler: MiddlewareHandler;
    route: string;
    beforeListen?: boolean;
}
```

<div className="members-wrapper">

### handler

<MemberInfo kind="property" type={`MiddlewareHandler`}   />

The Express middleware function or NestJS `NestMiddleware` class.
### route

<MemberInfo kind="property" type={`string`}   />

The route to which this middleware will apply. Pattern based routes are supported as well.

The `'ab*cd'` route path will match `abcd`, `ab_cd`, `abecd`, and so on. The characters `?`, `+`, `*`, and `()` may be used in a route path,
and are subsets of their regular expression counterparts. The hyphen (`-`) and the dot (`.`) are interpreted literally.
### beforeListen

<MemberInfo kind="property" type={`boolean`} default={`false`}  since="1.1.0"  />

When set to `true`, this will cause the middleware to be applied before the Vendure server (and underlying Express server) starts listening
for connections. In practical terms this means that the middleware will be at the very start of the middleware stack, before even the
`body-parser` middleware which is automatically applied by NestJS. This can be useful in certain cases such as when you need to access the
raw unparsed request for a specific route.


</div>


---

---
title: "PaginatedList"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## PaginatedList

<GenerationInfo sourceFile="packages/common/src/shared-types.ts" sourceLine="67" packageName="@vendure/common" />

A type describing the shape of a paginated list response. In Vendure, almost all list queries
(`products`, `collections`, `orders`, `customers` etc) return an object of this type.

```ts title="Signature"
type PaginatedList<T> = {
    items: T[];
    totalItems: number;
}
```

<div className="members-wrapper">

### items

<MemberInfo kind="property" type={`T[]`}   />


### totalItems

<MemberInfo kind="property" type={`number`}   />




</div>


---

---
title: "Permission"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## Permission

<GenerationInfo sourceFile="packages/common/src/generated-types.ts" sourceLine="4477" packageName="@vendure/common" />

Permissions for administrators and customers. Used to control access to
GraphQL resolvers via the <a href='/reference/typescript-api/request/allow-decorator#allow'>Allow</a> decorator.

## Understanding Permission.Owner

`Permission.Owner` is a special permission which is used in some Vendure resolvers to indicate that that resolver should only
be accessible to the "owner" of that resource.

For example, the Shop API `activeCustomer` query resolver should only return the Customer object for the "owner" of that Customer, i.e.
based on the activeUserId of the current session. As a result, the resolver code looks like this:

*Example*

```TypeScript
@Query()
@Allow(Permission.Owner)
async activeCustomer(@Ctx() ctx: RequestContext): Promise<Customer | undefined> {
  const userId = ctx.activeUserId;
  if (userId) {
    return this.customerService.findOneByUserId(ctx, userId);
  }
}
```

Here we can see that the "ownership" must be enforced by custom logic inside the resolver. Since "ownership" cannot be defined generally
nor statically encoded at build-time, any resolvers using `Permission.Owner` **must** include logic to enforce that only the owner
of the resource has access. If not, then it is the equivalent of using `Permission.Public`.

```ts title="Signature"
enum Permission {
    Authenticated = 'Authenticated'
    CreateAdministrator = 'CreateAdministrator'
    CreateAsset = 'CreateAsset'
    CreateCatalog = 'CreateCatalog'
    CreateChannel = 'CreateChannel'
    CreateCollection = 'CreateCollection'
    CreateCountry = 'CreateCountry'
    CreateCustomer = 'CreateCustomer'
    CreateCustomerGroup = 'CreateCustomerGroup'
    CreateFacet = 'CreateFacet'
    CreateOrder = 'CreateOrder'
    CreatePaymentMethod = 'CreatePaymentMethod'
    CreateProduct = 'CreateProduct'
    CreatePromotion = 'CreatePromotion'
    CreateSeller = 'CreateSeller'
    CreateSettings = 'CreateSettings'
    CreateShippingMethod = 'CreateShippingMethod'
    CreateStockLocation = 'CreateStockLocation'
    CreateSystem = 'CreateSystem'
    CreateTag = 'CreateTag'
    CreateTaxCategory = 'CreateTaxCategory'
    CreateTaxRate = 'CreateTaxRate'
    CreateZone = 'CreateZone'
    DeleteAdministrator = 'DeleteAdministrator'
    DeleteAsset = 'DeleteAsset'
    DeleteCatalog = 'DeleteCatalog'
    DeleteChannel = 'DeleteChannel'
    DeleteCollection = 'DeleteCollection'
    DeleteCountry = 'DeleteCountry'
    DeleteCustomer = 'DeleteCustomer'
    DeleteCustomerGroup = 'DeleteCustomerGroup'
    DeleteFacet = 'DeleteFacet'
    DeleteOrder = 'DeleteOrder'
    DeletePaymentMethod = 'DeletePaymentMethod'
    DeleteProduct = 'DeleteProduct'
    DeletePromotion = 'DeletePromotion'
    DeleteSeller = 'DeleteSeller'
    DeleteSettings = 'DeleteSettings'
    DeleteShippingMethod = 'DeleteShippingMethod'
    DeleteStockLocation = 'DeleteStockLocation'
    DeleteSystem = 'DeleteSystem'
    DeleteTag = 'DeleteTag'
    DeleteTaxCategory = 'DeleteTaxCategory'
    DeleteTaxRate = 'DeleteTaxRate'
    DeleteZone = 'DeleteZone'
    Owner = 'Owner'
    Public = 'Public'
    ReadAdministrator = 'ReadAdministrator'
    ReadAsset = 'ReadAsset'
    ReadCatalog = 'ReadCatalog'
    ReadChannel = 'ReadChannel'
    ReadCollection = 'ReadCollection'
    ReadCountry = 'ReadCountry'
    ReadCustomer = 'ReadCustomer'
    ReadCustomerGroup = 'ReadCustomerGroup'
    ReadFacet = 'ReadFacet'
    ReadOrder = 'ReadOrder'
    ReadPaymentMethod = 'ReadPaymentMethod'
    ReadProduct = 'ReadProduct'
    ReadPromotion = 'ReadPromotion'
    ReadSeller = 'ReadSeller'
    ReadSettings = 'ReadSettings'
    ReadShippingMethod = 'ReadShippingMethod'
    ReadStockLocation = 'ReadStockLocation'
    ReadSystem = 'ReadSystem'
    ReadTag = 'ReadTag'
    ReadTaxCategory = 'ReadTaxCategory'
    ReadTaxRate = 'ReadTaxRate'
    ReadZone = 'ReadZone'
    SuperAdmin = 'SuperAdmin'
    UpdateAdministrator = 'UpdateAdministrator'
    UpdateAsset = 'UpdateAsset'
    UpdateCatalog = 'UpdateCatalog'
    UpdateChannel = 'UpdateChannel'
    UpdateCollection = 'UpdateCollection'
    UpdateCountry = 'UpdateCountry'
    UpdateCustomer = 'UpdateCustomer'
    UpdateCustomerGroup = 'UpdateCustomerGroup'
    UpdateFacet = 'UpdateFacet'
    UpdateGlobalSettings = 'UpdateGlobalSettings'
    UpdateOrder = 'UpdateOrder'
    UpdatePaymentMethod = 'UpdatePaymentMethod'
    UpdateProduct = 'UpdateProduct'
    UpdatePromotion = 'UpdatePromotion'
    UpdateSeller = 'UpdateSeller'
    UpdateSettings = 'UpdateSettings'
    UpdateShippingMethod = 'UpdateShippingMethod'
    UpdateStockLocation = 'UpdateStockLocation'
    UpdateSystem = 'UpdateSystem'
    UpdateTag = 'UpdateTag'
    UpdateTaxCategory = 'UpdateTaxCategory'
    UpdateTaxRate = 'UpdateTaxRate'
    UpdateZone = 'UpdateZone'
}
```


---

---
title: "PriceCalculationResult"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## PriceCalculationResult

<GenerationInfo sourceFile="packages/core/src/common/types/common-types.ts" sourceLine="174" packageName="@vendure/core" />

The result of the price calculation from the <a href='/reference/typescript-api/products-stock/product-variant-price-calculation-strategy#productvariantpricecalculationstrategy'>ProductVariantPriceCalculationStrategy</a> or the
<a href='/reference/typescript-api/orders/order-item-price-calculation-strategy#orderitempricecalculationstrategy'>OrderItemPriceCalculationStrategy</a>.

```ts title="Signature"
type PriceCalculationResult = {
    price: number;
    priceIncludesTax: boolean;
}
```

<div className="members-wrapper">

### price

<MemberInfo kind="property" type={`number`}   />


### priceIncludesTax

<MemberInfo kind="property" type={`boolean`}   />




</div>


---

---
title: "ProcessContext"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ProcessContext

<GenerationInfo sourceFile="packages/core/src/process-context/process-context.ts" sourceLine="31" packageName="@vendure/core" />

The ProcessContext can be injected into your providers & modules in order to know whether it
is being executed in the context of the main Vendure server or the worker.

*Example*

```ts
import { Injectable, OnApplicationBootstrap } from '@nestjs/common';
import { ProcessContext } from '@vendure/core';

@Injectable()
export class MyService implements OnApplicationBootstrap {
  constructor(private processContext: ProcessContext) {}

  onApplicationBootstrap() {
    if (this.processContext.isServer) {
      // code which will only execute when running in
      // the server process
    }
  }
}
```

```ts title="Signature"
class ProcessContext {
    isServer: boolean
    isWorker: boolean
}
```

<div className="members-wrapper">

### isServer

<MemberInfo kind="property" type={`boolean`}   />


### isWorker

<MemberInfo kind="property" type={`boolean`}   />




</div>


---

---
title: "VENDURE_VERSION"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## VENDURE_VERSION

<GenerationInfo sourceFile="packages/core/src/version.ts" sourceLine="17" packageName="@vendure/core" since="2.0.0" />

A constant which holds the current version of the Vendure core. You can use
this when your code needs to know the version of Vendure which is running.

*Example*

```ts
import { VENDURE_VERSION } from '@vendure/core';

console.log('Vendure version:', VENDURE_VERSION);
```



---

---
title: "ConfigArgType"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ConfigArgType

<GenerationInfo sourceFile="packages/common/src/shared-types.ts" sourceLine="130" packageName="@vendure/common" />

Certain entities (those which implement <a href='/reference/typescript-api/configurable-operation-def/#configurableoperationdef'>ConfigurableOperationDef</a>) allow arbitrary
configuration arguments to be specified which can then be set in the admin-ui and used in
the business logic of the app. These are the valid data types of such arguments.
The data type influences:

1. How the argument form field is rendered in the admin-ui
2. The JavaScript type into which the value is coerced before being passed to the business logic.

```ts title="Signature"
type ConfigArgType = 'string' | 'int' | 'float' | 'boolean' | 'datetime' | 'ID'
```


---

---
title: "ConfigArgs"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ConfigArgs

<GenerationInfo sourceFile="packages/core/src/common/configurable-operation.ts" sourceLine="140" packageName="@vendure/core" />

A object which defines the configurable arguments which may be passed to
functions in those classes which implement the <a href='/reference/typescript-api/configurable-operation-def/#configurableoperationdef'>ConfigurableOperationDef</a> interface.

## Data types
Each argument has a data type, which must be one of <a href='/reference/typescript-api/configurable-operation-def/config-arg-type#configargtype'>ConfigArgType</a>.

*Example*

```ts
{
  apiKey: { type: 'string' },
  maxRetries: { type: 'int' },
  logErrors: { type: 'boolean' },
}
```

## Lists
Setting the `list` property to `true` will make the argument into an array of the specified
data type. For example, if you want to store an array of strings:

*Example*

```ts
{
  aliases: {
    type: 'string',
    list: true,
  },
}
```
In the Admin UI, this will be rendered as an orderable list of string inputs.

## UI Component
The `ui` field allows you to specify a specific input component to be used in the Admin UI.
When not set, a default input component is used appropriate to the data type.

*Example*

```ts
{
  operator: {
    type: 'string',
    ui: {
      component: 'select-form-input',
      options: [
        { value: 'startsWith' },
        { value: 'endsWith' },
        { value: 'contains' },
        { value: 'doesNotContain' },
      ],
    },
  },
  secretKey: {
    type: 'string',
    ui: { component: 'password-form-input' },
  },
}
```
The available components as well as their configuration options can be found in the <a href='/reference/typescript-api/configurable-operation-def/default-form-config-hash#defaultformconfighash'>DefaultFormConfigHash</a> docs.
Custom UI components may also be defined via an Admin UI extension using the `registerFormInputComponent()` function
which is exported from `@vendure/admin-ui/core`.

```ts title="Signature"
type ConfigArgs = {
    [name: string]: ConfigArgDef<ConfigArgType>;
}
```

<div className="members-wrapper">

### [index]

<MemberInfo kind="property" type={`ConfigArgDef&#60;<a href='/reference/typescript-api/configurable-operation-def/config-arg-type#configargtype'>ConfigArgType</a>&#62;`}   />




</div>


---

---
title: "ConfigurableOperationDefOptions"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ConfigurableOperationDefOptions

<GenerationInfo sourceFile="packages/core/src/common/configurable-operation.ts" sourceLine="230" packageName="@vendure/core" />

Common configuration options used when creating a new instance of a
<a href='/reference/typescript-api/configurable-operation-def/#configurableoperationdef'>ConfigurableOperationDef</a> (

```ts title="Signature"
interface ConfigurableOperationDefOptions<T extends ConfigArgs> extends InjectableStrategy {
    code: string;
    args: T;
    description: LocalizedStringArray;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### code

<MemberInfo kind="property" type={`string`}   />

A unique code used to identify this operation.
### args

<MemberInfo kind="property" type={`T`}   />

Optional provider-specific arguments which, when specified, are
editable in the admin-ui. For example, args could be used to store an API key
for a payment provider service.

*Example*

```ts
args: {
  apiKey: { type: 'string' },
}
```

See <a href='/reference/typescript-api/configurable-operation-def/config-args#configargs'>ConfigArgs</a> for available configuration options.
### description

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/configurable-operation-def/localized-string-array#localizedstringarray'>LocalizedStringArray</a>`}   />

A human-readable description for the operation method.


</div>


---

---
title: "DefaultFormComponentId"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DefaultFormComponentId

<GenerationInfo sourceFile="packages/common/src/shared-types.ts" sourceLine="139" packageName="@vendure/common" />

The ids of the default form input components that ship with the
Admin UI.

```ts title="Signature"
type DefaultFormComponentId = | 'boolean-form-input'
    | 'currency-form-input'
    | 'customer-group-form-input'
    | 'date-form-input'
    | 'facet-value-form-input'
    | 'json-editor-form-input'
    | 'html-editor-form-input'
    | 'number-form-input'
    | 'password-form-input'
    | 'product-selector-form-input'
    | 'relation-form-input'
    | 'rich-text-form-input'
    | 'select-form-input'
    | 'text-form-input'
    | 'textarea-form-input'
    | 'product-multi-form-input'
    | 'combination-mode-form-input'
    | 'struct-form-input'
```


---

---
title: "DefaultFormConfigHash"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DefaultFormConfigHash

<GenerationInfo sourceFile="packages/common/src/shared-types.ts" sourceLine="165" packageName="@vendure/common" />

Used to define the expected arguments for a given default form input component.

```ts title="Signature"
type DefaultFormConfigHash = {
    'boolean-form-input': Record<string, never>;
    'currency-form-input': Record<string, never>;
    'customer-group-form-input': Record<string, never>;
    'date-form-input': { min?: string; max?: string; yearRange?: number };
    'facet-value-form-input': Record<string, never>;
    'json-editor-form-input': { height?: string };
    'html-editor-form-input': { height?: string };
    'number-form-input': { min?: number; max?: number; step?: number; prefix?: string; suffix?: string };
    'password-form-input': Record<string, never>;
    'product-selector-form-input': Record<string, never>;
    'relation-form-input': Record<string, never>;
    'rich-text-form-input': Record<string, never>;
    'select-form-input': {
        options?: Array<{ value: string; label?: Array<Omit<LocalizedString, '__typename'>> }>;
    };
    'text-form-input': { prefix?: string; suffix?: string };
    'textarea-form-input': {
        spellcheck?: boolean;
    };
    'product-multi-form-input': {
        selectionMode?: 'product' | 'variant';
    };
    'combination-mode-form-input': Record<string, never>;
    'struct-form-input': Record<string, never>;
}
```

<div className="members-wrapper">

### 'boolean-form-input'

<MemberInfo kind="property" type={`Record&#60;string, never&#62;`}   />


### 'currency-form-input'

<MemberInfo kind="property" type={`Record&#60;string, never&#62;`}   />


### 'customer-group-form-input'

<MemberInfo kind="property" type={`Record&#60;string, never&#62;`}   />


### 'date-form-input'

<MemberInfo kind="property" type={`{ min?: string; max?: string; yearRange?: number }`}   />


### 'facet-value-form-input'

<MemberInfo kind="property" type={`Record&#60;string, never&#62;`}   />


### 'json-editor-form-input'

<MemberInfo kind="property" type={`{ height?: string }`}   />


### 'html-editor-form-input'

<MemberInfo kind="property" type={`{ height?: string }`}   />


### 'number-form-input'

<MemberInfo kind="property" type={`{ min?: number; max?: number; step?: number; prefix?: string; suffix?: string }`}   />


### 'password-form-input'

<MemberInfo kind="property" type={`Record&#60;string, never&#62;`}   />


### 'product-selector-form-input'

<MemberInfo kind="property" type={`Record&#60;string, never&#62;`}   />


### 'relation-form-input'

<MemberInfo kind="property" type={`Record&#60;string, never&#62;`}   />


### 'rich-text-form-input'

<MemberInfo kind="property" type={`Record&#60;string, never&#62;`}   />


### 'select-form-input'

<MemberInfo kind="property" type={`{         options?: Array&#60;{ value: string; label?: Array&#60;Omit&#60;LocalizedString, '__typename'&#62;&#62; }&#62;;     }`}   />


### 'text-form-input'

<MemberInfo kind="property" type={`{ prefix?: string; suffix?: string }`}   />


### 'textarea-form-input'

<MemberInfo kind="property" type={`{         spellcheck?: boolean;     }`}   />


### 'product-multi-form-input'

<MemberInfo kind="property" type={`{         selectionMode?: 'product' | 'variant';     }`}   />


### 'combination-mode-form-input'

<MemberInfo kind="property" type={`Record&#60;string, never&#62;`}   />


### 'struct-form-input'

<MemberInfo kind="property" type={`Record&#60;string, never&#62;`}   />




</div>


---

---
title: "ConfigurableOperationDef"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ConfigurableOperationDef

<GenerationInfo sourceFile="packages/core/src/common/configurable-operation.ts" sourceLine="335" packageName="@vendure/core" />

A ConfigurableOperationDef is a special type of object used extensively by Vendure to define
code blocks which have arguments which are configurable at run-time by the administrator.

This is the mechanism used by:

* <a href='/reference/typescript-api/configuration/collection-filter#collectionfilter'>CollectionFilter</a>
* <a href='/reference/typescript-api/payment/payment-method-handler#paymentmethodhandler'>PaymentMethodHandler</a>
* <a href='/reference/typescript-api/promotions/promotion-action#promotionaction'>PromotionAction</a>
* <a href='/reference/typescript-api/promotions/promotion-condition#promotioncondition'>PromotionCondition</a>
* <a href='/reference/typescript-api/shipping/shipping-calculator#shippingcalculator'>ShippingCalculator</a>
* <a href='/reference/typescript-api/shipping/shipping-eligibility-checker#shippingeligibilitychecker'>ShippingEligibilityChecker</a>

Any class which extends ConfigurableOperationDef works in the same way: it takes a
config object as the constructor argument. That config object extends the <a href='/reference/typescript-api/configurable-operation-def/configurable-operation-def-options#configurableoperationdefoptions'>ConfigurableOperationDefOptions</a>
interface and typically adds some kind of business logic function to it.

For example, in the case of `ShippingEligibilityChecker`,
it adds the `check()` function to the config object which defines the logic for checking whether an Order is eligible
for a particular ShippingMethod.

## The `args` property

The key feature of the ConfigurableOperationDef is the `args` property. This is where we define those
arguments that are exposed via the Admin UI as data input components. This allows their values to
be set at run-time by the Administrator. Those values can then be accessed in the business logic
of the operation.

The data type of the args can be one of <a href='/reference/typescript-api/configurable-operation-def/config-arg-type#configargtype'>ConfigArgType</a>, and the configuration is further explained in
the docs of <a href='/reference/typescript-api/configurable-operation-def/config-args#configargs'>ConfigArgs</a>.

## Dependency Injection
If your business logic relies on injectable providers, such as the `TransactionalConnection` object, or any of the
internal Vendure services or those defined in a plugin, you can inject them by using the config object's
`init()` method, which exposes the <a href='/reference/typescript-api/common/injector#injector'>Injector</a>.

Here's an example of a ShippingCalculator that injects a service which has been defined in a plugin:

*Example*

```ts
import { Injector, ShippingCalculator } from '@vendure/core';
import { ShippingRatesService } from './shipping-rates.service';

// We keep reference to our injected service by keeping it
// in the top-level scope of the file.
let shippingRatesService: ShippingRatesService;

export const customShippingCalculator = new ShippingCalculator({
  code: 'custom-shipping-calculator',
  description: [],
  args: {},

  init(injector: Injector) {
    // The init function is called during bootstrap, and allows
    // us to inject any providers we need.
    shippingRatesService = injector.get(ShippingRatesService);
  },

  calculate: async (order, args) => {
    // We can now use the injected provider in the business logic.
    const { price, priceWithTax } = await shippingRatesService.getRate({
      destination: order.shippingAddress,
      contents: order.lines,
    });

    return {
      price,
      priceWithTax,
    };
  },
});
```

```ts title="Signature"
class ConfigurableOperationDef<T extends ConfigArgs = ConfigArgs> {
    code: string
    args: T
    description: LocalizedStringArray
    constructor(options: ConfigurableOperationDefOptions<T>)
    init(injector: Injector) => ;
    destroy() => ;
    toGraphQlType(ctx: RequestContext) => ConfigurableOperationDefinition;
    argsArrayToHash(args: ConfigArg[]) => ConfigArgValues<T>;
}
```

<div className="members-wrapper">

### code

<MemberInfo kind="property" type={`string`}   />


### args

<MemberInfo kind="property" type={`T`}   />


### description

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/configurable-operation-def/localized-string-array#localizedstringarray'>LocalizedStringArray</a>`}   />


### constructor

<MemberInfo kind="method" type={`(options: <a href='/reference/typescript-api/configurable-operation-def/configurable-operation-def-options#configurableoperationdefoptions'>ConfigurableOperationDefOptions</a>&#60;T&#62;) => ConfigurableOperationDef`}   />


### init

<MemberInfo kind="method" type={`(injector: <a href='/reference/typescript-api/common/injector#injector'>Injector</a>) => `}   />


### destroy

<MemberInfo kind="method" type={`() => `}   />


### toGraphQlType

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => ConfigurableOperationDefinition`}   />

Convert a ConfigurableOperationDef into a ConfigurableOperationDefinition object, typically
so that it can be sent via the API.
### argsArrayToHash

<MemberInfo kind="method" type={`(args: ConfigArg[]) => ConfigArgValues&#60;T&#62;`}   />

Coverts an array of ConfigArgs into a hash object:

from:
`[{ name: 'foo', type: 'string', value: 'bar'}]`

to:
`{ foo: 'bar' }`


</div>


---

---
title: "LocalizedStringArray"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## LocalizedStringArray

<GenerationInfo sourceFile="packages/core/src/common/configurable-operation.ts" sourceLine="43" packageName="@vendure/core" />

An array of string values in a given <a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a>, used to define human-readable string values.
The `ui` property can be used in conjunction with the Vendure Admin UI to specify a custom form input
component.

*Example*

```ts
const title: LocalizedStringArray = [
  { languageCode: LanguageCode.en, value: 'English Title' },
  { languageCode: LanguageCode.de, value: 'German Title' },
  { languageCode: LanguageCode.zh, value: 'Chinese Title' },
]
```

```ts title="Signature"
type LocalizedStringArray = Array<Omit<LocalizedString, '__typename'>>
```


---

---
title: "ApiOptions"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ApiOptions

<GenerationInfo sourceFile="packages/core/src/config/vendure-config.ts" sourceLine="75" packageName="@vendure/core" />

The ApiOptions define how the Vendure GraphQL APIs are exposed, as well as allowing the API layer
to be extended with middleware.

```ts title="Signature"
interface ApiOptions {
    hostname?: string;
    port: number;
    adminApiPath?: string;
    shopApiPath?: string;
    adminApiPlayground?: boolean | RenderPageOptions;
    shopApiPlayground?: boolean | RenderPageOptions;
    adminApiDebug?: boolean;
    shopApiDebug?: boolean;
    shopListQueryLimit?: number;
    adminListQueryLimit?: number;
    adminApiValidationRules?: Array<(context: ValidationContext) => any>;
    shopApiValidationRules?: Array<(context: ValidationContext) => any>;
    channelTokenKey?: string;
    cors?: boolean | CorsOptions;
    middleware?: Middleware[];
    trustProxy?: TrustProxyOptions;
    apolloServerPlugins?: ApolloServerPlugin[];
    introspection?: boolean;
}
```

<div className="members-wrapper">

### hostname

<MemberInfo kind="property" type={`string`} default={`''`}   />

Set the hostname of the server. If not set, the server will be available on localhost.
### port

<MemberInfo kind="property" type={`number`} default={`3000`}   />

Which port the Vendure server should listen on.
### adminApiPath

<MemberInfo kind="property" type={`string`} default={`'admin-api'`}   />

The path to the admin GraphQL API.
### shopApiPath

<MemberInfo kind="property" type={`string`} default={`'shop-api'`}   />

The path to the shop GraphQL API.
### adminApiPlayground

<MemberInfo kind="property" type={`boolean | RenderPageOptions`} default={`false`}   />

The playground config to the admin GraphQL API
[ApolloServer playground](https://www.apollographql.com/docs/apollo-server/api/apollo-server/#constructoroptions-apolloserver).
### shopApiPlayground

<MemberInfo kind="property" type={`boolean | RenderPageOptions`} default={`false`}   />

The playground config to the shop GraphQL API
[ApolloServer playground](https://www.apollographql.com/docs/apollo-server/api/apollo-server/#constructoroptions-apolloserver).
### adminApiDebug

<MemberInfo kind="property" type={`boolean`} default={`false`}   />

The debug config to the admin GraphQL API
[ApolloServer playground](https://www.apollographql.com/docs/apollo-server/api/apollo-server/#constructoroptions-apolloserver).
### shopApiDebug

<MemberInfo kind="property" type={`boolean`} default={`false`}   />

The debug config to the shop GraphQL API
[ApolloServer playground](https://www.apollographql.com/docs/apollo-server/api/apollo-server/#constructoroptions-apolloserver).
### shopListQueryLimit

<MemberInfo kind="property" type={`number`} default={`100`}   />

The maximum number of items that may be returned by a query which returns a `PaginatedList` response. In other words,
this is the upper limit of the `take` input option.
### adminListQueryLimit

<MemberInfo kind="property" type={`number`} default={`1000`}   />

The maximum number of items that may be returned by a query which returns a `PaginatedList` response. In other words,
this is the upper limit of the `take` input option.
### adminApiValidationRules

<MemberInfo kind="property" type={`Array&#60;(context: ValidationContext) =&#62; any&#62;`} default={`[]`}   />

Custom functions to use as additional validation rules when validating the schema for the admin GraphQL API
[ApolloServer validation rules](https://www.apollographql.com/docs/apollo-server/api/apollo-server/#validationrules).
### shopApiValidationRules

<MemberInfo kind="property" type={`Array&#60;(context: ValidationContext) =&#62; any&#62;`} default={`[]`}   />

Custom functions to use as additional validation rules when validating the schema for the shop GraphQL API
[ApolloServer validation rules](https://www.apollographql.com/docs/apollo-server/api/apollo-server/#validationrules).
### channelTokenKey

<MemberInfo kind="property" type={`string`} default={`'vendure-token'`}   />

The name of the property which contains the token of the
active channel. This property can be included either in
the request header or as a query string.
### cors

<MemberInfo kind="property" type={`boolean | CorsOptions`} default={`{ origin: true, credentials: true }`}   />

Set the CORS handling for the server. See the [express CORS docs](https://github.com/expressjs/cors#configuration-options).
### middleware

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/middleware#middleware'>Middleware</a>[]`} default={`[]`}   />

Custom Express or NestJS middleware for the server. More information can be found in the <a href='/reference/typescript-api/common/middleware#middleware'>Middleware</a> docs.
### trustProxy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/configuration/trust-proxy-options#trustproxyoptions'>TrustProxyOptions</a>`} default={`false`}  since="3.4.0"  />

Set the trust proxy configuration for the server. See the [express proxy docs](https://expressjs.com/en/guide/behind-proxies.html).
### apolloServerPlugins

<MemberInfo kind="property" type={`ApolloServerPlugin[]`} default={`[]`}   />

Custom [ApolloServerPlugins](https://www.apollographql.com/docs/apollo-server/integrations/plugins/) which
allow the extension of the Apollo Server, which is the underlying GraphQL server used by Vendure.

Apollo plugins can be used e.g. to perform custom data transformations on incoming operations or outgoing
data.
### introspection

<MemberInfo kind="property" type={`boolean`} default={`true`}  since="1.5.0"  />

Controls whether introspection of the GraphQL APIs is enabled. For production, it is recommended to disable
introspection, since exposing your entire schema can allow an attacker to trivially learn all operations
and much more easily find any potentially exploitable queries.

**Note:** when introspection is disabled, tooling which relies on it for things like autocompletion
will not work.

*Example*

```ts
{
  introspection: process.env.NODE_ENV !== 'production'
}
```


</div>


---

---
title: "CollectionFilter"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## CollectionFilter

<GenerationInfo sourceFile="packages/core/src/config/catalog/collection-filter.ts" sourceLine="64" packageName="@vendure/core" />

A CollectionFilter defines a rule which can be used to associate ProductVariants with a Collection.
The filtering is done by defining the `apply()` function, which receives a TypeORM
[`QueryBuilder`](https://typeorm.io/#/select-query-builder) object to which clauses may be added.

Creating a CollectionFilter is considered an advanced Vendure topic. For more insight into how
they work, study the [default collection filters](https://github.com/vendure-ecommerce/vendure/blob/master/packages/core/src/config/catalog/default-collection-filters.ts)

Here's a simple example of a custom CollectionFilter:

*Example*

```ts
import { CollectionFilter, LanguageCode } from '@vendure/core';

export const skuCollectionFilter = new CollectionFilter({
  args: {
    // The `args` object defines the user-configurable arguments
    // which will get passed to the filter's `apply()` function.
    sku: {
      type: 'string',
      label: [{ languageCode: LanguageCode.en, value: 'SKU' }],
      description: [
        {
          languageCode: LanguageCode.en,
          value: 'Matches any product variants with SKUs containing this value',
        },
      ],
    },
  },
  code: 'variant-sku-filter',
  description: [{ languageCode: LanguageCode.en, value: 'Filter by matching SKU' }],

  // This is the function that defines the logic of the filter.
  apply: (qb, args) => {
    const LIKE = qb.connection.options.type === 'postgres' ? 'ILIKE' : 'LIKE';
    return qb.andWhere(`productVariant.sku ${LIKE} :sku`, { sku: `%${args.sku}%` });
  },
});
```

```ts title="Signature"
class CollectionFilter<T extends ConfigArgs = ConfigArgs> extends ConfigurableOperationDef<T> {
    constructor(config: CollectionFilterConfig<T>)
    apply(qb: SelectQueryBuilder<ProductVariant>, args: ConfigArg[]) => SelectQueryBuilder<ProductVariant>;
}
```
* Extends: <code><a href='/reference/typescript-api/configurable-operation-def/#configurableoperationdef'>ConfigurableOperationDef</a>&#60;T&#62;</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(config: CollectionFilterConfig&#60;T&#62;) => CollectionFilter`}   />


### apply

<MemberInfo kind="method" type={`(qb: SelectQueryBuilder&#60;<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>&#62;, args: ConfigArg[]) => SelectQueryBuilder&#60;<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>&#62;`}   />




</div>


---

---
title: "DefaultConfig"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## defaultConfig

<GenerationInfo sourceFile="packages/core/src/config/default-config.ts" sourceLine="68" packageName="@vendure/core" />

The default configuration settings which are used if not explicitly overridden in the bootstrap() call.



---

---
title: "EntityDuplicator"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## EntityDuplicator

<GenerationInfo sourceFile="packages/core/src/config/entity/entity-duplicator.ts" sourceLine="158" packageName="@vendure/core" since="2.2.0" />

An EntityDuplicator is used to define the logic for duplicating entities when the `duplicateEntity` mutation is called.
This allows you to add support for duplication of both core and custom entities.

*Example*

```ts title=src/config/custom-collection-duplicator.ts
import { Collection, LanguageCode, Permission
  EntityDuplicator, TransactionalConnection, CollectionService } from '@vendure/core';

let collectionService: CollectionService;
let connection: TransactionalConnection;

// This is just an example - we already ship with a built-in duplicator for Collections.
const customCollectionDuplicator = new EntityDuplicator({
    code: 'custom-collection-duplicator',
    description: [{ languageCode: LanguageCode.en, value: 'Custom collection duplicator' }],
    args: {
        throwError: {
            type: 'boolean',
            defaultValue: false,
        },
    },
    forEntities: ['Collection'],
    requiresPermission: [Permission.UpdateCollection],
    init(injector) {
        collectionService = injector.get(CollectionService);
        connection = injector.get(TransactionalConnection);
    },
    duplicate: async input => {
        const { ctx, id, args } = input;

        const original = await connection.getEntityOrThrow(ctx, Collection, id, {
            relations: {
                assets: true,
                featuredAsset: true,
            },
        });
        const newCollection = await collectionService.create(ctx, {
            isPrivate: original.isPrivate,
            customFields: original.customFields,
            assetIds: original.assets.map(a => a.id),
            featuredAssetId: original.featuredAsset?.id,
            parentId: original.parentId,
            filters: original.filters.map(f => ({
                code: f.code,
                arguments: f.args,
            })),
            inheritFilters: original.inheritFilters,
            translations: original.translations.map(t => ({
                languageCode: t.languageCode,
                name: `${t.name} (copy)`,
                slug: `${t.slug}-copy`,
                description: t.description,
                customFields: t.customFields,
            })),
        });

        if (args.throwError) {
            // If an error is thrown at any point during the duplication process, the entire
            // transaction will get automatically rolled back, and the mutation will return
            // an ErrorResponse containing the error message.
            throw new Error('Dummy error');
        }

        return newCollection;
    },
});
```

The duplicator then gets passed to your VendureConfig object:

```ts title=src/vendure-config.ts
import { VendureConfig, defaultEntityDuplicators } from '@vendure/core';
import { customCollectionDuplicator } from './config/custom-collection-duplicator';

export const config: VendureConfig = {
   // ...
   entityOptions: {
     entityDuplicators: [
         ...defaultEntityDuplicators,
         customCollectionDuplicator,
     ],
   },
};
```

```ts title="Signature"
class EntityDuplicator<T extends ConfigArgs = ConfigArgs> extends ConfigurableOperationDef<T> {
    constructor(config: EntityDuplicatorConfig<T>)
    duplicate(input: {
        ctx: RequestContext;
        entityName: string;
        id: ID;
        args: ConfigArg[];
    }) => Promise<VendureEntity>;
}
```
* Extends: <code><a href='/reference/typescript-api/configurable-operation-def/#configurableoperationdef'>ConfigurableOperationDef</a>&#60;T&#62;</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(config: <a href='/reference/typescript-api/configuration/entity-duplicator#entityduplicatorconfig'>EntityDuplicatorConfig</a>&#60;T&#62;) => EntityDuplicator`}   />


### duplicate

<MemberInfo kind="method" type={`(input: {         ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>;         entityName: string;         id: <a href='/reference/typescript-api/common/id#id'>ID</a>;         args: ConfigArg[];     }) => Promise&#60;<a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a>&#62;`}   />




</div>


## DuplicateEntityFn

<GenerationInfo sourceFile="packages/core/src/config/entity/entity-duplicator.ts" sourceLine="21" packageName="@vendure/core" since="2.2.0" />

A function which performs the duplication of an entity.

```ts title="Signature"
type DuplicateEntityFn<T extends ConfigArgs> = (input: {
    ctx: RequestContext;
    entityName: string;
    id: ID;
    args: ConfigArgValues<T>;
}) => Promise<VendureEntity>
```


## EntityDuplicatorConfig

<GenerationInfo sourceFile="packages/core/src/config/entity/entity-duplicator.ts" sourceLine="36" packageName="@vendure/core" since="2.2.0" />

Configuration for creating a new EntityDuplicator.

```ts title="Signature"
interface EntityDuplicatorConfig<T extends ConfigArgs> extends ConfigurableOperationDefOptions<T> {
    requiresPermission: Array<Permission | string> | Permission | string;
    forEntities: string[];
    duplicate: DuplicateEntityFn<T>;
}
```
* Extends: <code><a href='/reference/typescript-api/configurable-operation-def/configurable-operation-def-options#configurableoperationdefoptions'>ConfigurableOperationDefOptions</a>&#60;T&#62;</code>



<div className="members-wrapper">

### requiresPermission

<MemberInfo kind="property" type={`Array&#60;<a href='/reference/typescript-api/common/permission#permission'>Permission</a> | string&#62; | <a href='/reference/typescript-api/common/permission#permission'>Permission</a> | string`}   />

The permissions required in order to execute this duplicator. If an array is passed,
then the administrator must have at least one of the permissions in the array.
### forEntities

<MemberInfo kind="property" type={`string[]`}   />

The entities for which this duplicator is able to duplicate.
### duplicate

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/configuration/entity-duplicator#duplicateentityfn'>DuplicateEntityFn</a>&#60;T&#62;`}   />

The function which performs the duplication.

*Example*

```ts
duplicate: async input => {
  const { ctx, id, args } = input;

  // perform the duplication logic here

  return newEntity;
}
```


</div>


---

---
title: "EntityId Decorator"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## EntityId

<GenerationInfo sourceFile="packages/core/src/entity/entity-id.decorator.ts" sourceLine="41" packageName="@vendure/core" />

Decorates a property which points to another entity by ID. This custom decorator is needed
because we do not know the data type of the ID column until runtime, when we have access
to the configured EntityIdStrategy.

```ts title="Signature"
function EntityId(options?: IdColumnOptions): void
```
Parameters

### options

<MemberInfo kind="parameter" type={`IdColumnOptions`} />



---

---
title: "EntityIdStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## AutoIncrementIdStrategy

<GenerationInfo sourceFile="packages/core/src/config/entity/auto-increment-id-strategy.ts" sourceLine="11" packageName="@vendure/core" />

An id strategy which uses auto-increment integers as primary keys
for all entities. This is the default strategy used by Vendure.

```ts title="Signature"
class AutoIncrementIdStrategy implements EntityIdStrategy<'increment'> {
    readonly primaryKeyType = 'increment';
    decodeId(id: string) => number;
    encodeId(primaryKey: number) => string;
}
```
* Implements: <code><a href='/reference/typescript-api/configuration/entity-id-strategy#entityidstrategy'>EntityIdStrategy</a>&#60;'increment'&#62;</code>



<div className="members-wrapper">

### primaryKeyType

<MemberInfo kind="property" type={``}   />


### decodeId

<MemberInfo kind="method" type={`(id: string) => number`}   />


### encodeId

<MemberInfo kind="method" type={`(primaryKey: number) => string`}   />




</div>


## EntityIdStrategy

<GenerationInfo sourceFile="packages/core/src/config/entity/entity-id-strategy.ts" sourceLine="32" packageName="@vendure/core" />

The EntityIdStrategy determines how entity IDs are generated and stored in the
database, as well as how they are transformed when being passed from the API to the
service layer and vice versa.

Vendure ships with two strategies: <a href='/reference/typescript-api/configuration/entity-id-strategy#autoincrementidstrategy'>AutoIncrementIdStrategy</a> and <a href='/reference/typescript-api/configuration/entity-id-strategy#uuididstrategy'>UuidIdStrategy</a>,
but custom strategies can be used, e.g. to apply some custom encoding to the ID before exposing
it in the GraphQL API.

:::info

This is configured via the `entityOptions.entityIdStrategy` property of
your VendureConfig.

:::

:::caution
Note: changing from an integer-based strategy to a uuid-based strategy
on an existing Vendure database will lead to problems with broken foreign-key
references. To change primary key types like this, you'll need to start with
a fresh database.
:::

```ts title="Signature"
interface EntityIdStrategy<T extends 'increment' | 'uuid'> extends InjectableStrategy {
    readonly primaryKeyType: T;
    encodeId: (primaryKey: PrimaryKeyType<T>) => string;
    decodeId: (id: string) => PrimaryKeyType<T>;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### primaryKeyType

<MemberInfo kind="property" type={`T`}   />

Defines how the primary key will be stored in the database - either
`'increment'` for auto-increment integer IDs, or `'uuid'` for a unique
string ID.
### encodeId

<MemberInfo kind="property" type={`(primaryKey: PrimaryKeyType&#60;T&#62;) =&#62; string`}   />

Allows the raw ID from the database to be transformed in some way before exposing
it in the GraphQL API.

For example, you may need to use auto-increment integer IDs due to some business
constraint, but you may not want to expose this data publicly in your API. In this
case, you can use the encode/decode methods to obfuscate the ID with some kind of
encoding scheme, such as base64 (or something more sophisticated).
### decodeId

<MemberInfo kind="property" type={`(id: string) =&#62; PrimaryKeyType&#60;T&#62;`}   />

Reverses the transformation performed by the `encodeId` method in order to get
back to the raw ID value.


</div>


## UuidIdStrategy

<GenerationInfo sourceFile="packages/core/src/config/entity/uuid-id-strategy.ts" sourceLine="25" packageName="@vendure/core" />

An id strategy which uses string uuids as primary keys
for all entities. This strategy can be configured with the
`entityIdStrategy` property of the `entityOptions` property
of <a href='/reference/typescript-api/configuration/vendure-config#vendureconfig'>VendureConfig</a>.

*Example*

```ts
import { UuidIdStrategy, VendureConfig } from '@vendure/core';

export const config: VendureConfig = {
  entityOptions: {
    entityIdStrategy: new UuidIdStrategy(),
    // ...
  }
}
```

```ts title="Signature"
class UuidIdStrategy implements EntityIdStrategy<'uuid'> {
    readonly primaryKeyType = 'uuid';
    decodeId(id: string) => string;
    encodeId(primaryKey: string) => string;
}
```
* Implements: <code><a href='/reference/typescript-api/configuration/entity-id-strategy#entityidstrategy'>EntityIdStrategy</a>&#60;'uuid'&#62;</code>



<div className="members-wrapper">

### primaryKeyType

<MemberInfo kind="property" type={``}   />


### decodeId

<MemberInfo kind="method" type={`(id: string) => string`}   />


### encodeId

<MemberInfo kind="method" type={`(primaryKey: string) => string`}   />




</div>


---

---
title: "EntityOptions"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## EntityOptions

<GenerationInfo sourceFile="packages/core/src/config/vendure-config.ts" sourceLine="1035" packageName="@vendure/core" since="1.3.0" />

Options relating to the internal handling of entities.

```ts title="Signature"
interface EntityOptions {
    entityIdStrategy?: EntityIdStrategy<any>;
    entityDuplicators?: Array<EntityDuplicator<any>>;
    moneyStrategy?: MoneyStrategy;
    channelCacheTtl?: number;
    zoneCacheTtl?: number;
    taxRateCacheTtl?: number;
    metadataModifiers?: EntityMetadataModifier[];
}
```

<div className="members-wrapper">

### entityIdStrategy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/configuration/entity-id-strategy#entityidstrategy'>EntityIdStrategy</a>&#60;any&#62;`} default={`<a href='/reference/typescript-api/configuration/entity-id-strategy#autoincrementidstrategy'>AutoIncrementIdStrategy</a>`}  since="1.3.0"  />

Defines the strategy used for both storing the primary keys of entities
in the database, and the encoding & decoding of those ids when exposing
entities via the API. The default uses a simple auto-increment integer
strategy.

:::caution
Note: changing from an integer-based strategy to a uuid-based strategy
on an existing Vendure database will lead to problems with broken foreign-key
references. To change primary key types like this, you'll need to start with
a fresh database.
:::
### entityDuplicators

<MemberInfo kind="property" type={`Array&#60;<a href='/reference/typescript-api/configuration/entity-duplicator#entityduplicator'>EntityDuplicator</a>&#60;any&#62;&#62;`} default={`defaultEntityDuplicators`}  since="2.2.0"  />

An array of <a href='/reference/typescript-api/configuration/entity-duplicator#entityduplicator'>EntityDuplicator</a> instances which are used to duplicate entities
when using the `duplicateEntity` mutation.
### moneyStrategy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/money/money-strategy#moneystrategy'>MoneyStrategy</a>`} default={`<a href='/reference/typescript-api/money/default-money-strategy#defaultmoneystrategy'>DefaultMoneyStrategy</a>`}  since="2.0.0"  />

Defines the strategy used to store and round monetary values.
### channelCacheTtl

<MemberInfo kind="property" type={`number`} default={`30000`}  since="1.3.0"  />

Channels get cached in-memory as they are accessed very frequently. This
setting determines how long the cache lives (in ms) until it is considered stale and
refreshed. For multi-instance deployments (e.g. serverless, load-balanced), a
smaller value here will prevent data inconsistencies between instances.
### zoneCacheTtl

<MemberInfo kind="property" type={`number`} default={`30000`}  since="1.3.0"  />

Zones get cached in-memory as they are accessed very frequently. This
setting determines how long the cache lives (in ms) until it is considered stale and
refreshed. For multi-instance deployments (e.g. serverless, load-balanced), a
smaller value here will prevent data inconsistencies between instances.
### taxRateCacheTtl

<MemberInfo kind="property" type={`number`} default={`30000`}  since="1.9.0"  />

TaxRates get cached in-memory as they are accessed very frequently. This
setting determines how long the cache lives (in ms) until it is considered stale and
refreshed. For multi-instance deployments (e.g. serverless, load-balanced), a
smaller value here will prevent data inconsistencies between instances.
### metadataModifiers

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/configuration/entity-options#entitymetadatamodifier'>EntityMetadataModifier</a>[]`} default={`[]`}  since="1.6.0"  />

Allows the metadata of the built-in TypeORM entities to be manipulated. This allows you
to do things like altering data types, adding indices etc. This is an advanced feature
which should be used with some caution as it will result in DB schema changes. For examples
see <a href='/reference/typescript-api/configuration/entity-options#entitymetadatamodifier'>EntityMetadataModifier</a>.


</div>


## EntityMetadataModifier

<GenerationInfo sourceFile="packages/core/src/config/entity-metadata/entity-metadata-modifier.ts" sourceLine="56" packageName="@vendure/core" since="1.6.0" />

A function which allows TypeORM entity metadata to be manipulated prior to the DB schema being generated
during bootstrap.

:::caution
Certain DB schema modifications will result in auto-generated migrations which will lead to data loss. For instance,
changing the data type of a column will drop the column & data and then re-create it. To avoid loss of important data,
always check and modify your migration scripts as needed.
:::

*Example*

```ts
import { Index } from 'typeorm';
import { EntityMetadataModifier, ProductVariant } from '@vendure/core';

// Adds a unique index to the ProductVariant.sku column
export const addSkuUniqueIndex: EntityMetadataModifier = metadata => {
  const instance = new ProductVariant();
  Index({ unique: true })(instance, 'sku');
};
```

*Example*

```ts
import { Column } from 'typeorm';
import { EntityMetadataModifier, ProductTranslation } from '@vendure/core';

// Use the "mediumtext" datatype for the Product's description rather than
// the default "text" type.
export const makeProductDescriptionMediumText: EntityMetadataModifier = metadata => {
    const descriptionColumnIndex = metadata.columns.findIndex(
        col => col.propertyName === 'description' && col.target === ProductTranslation,
    );
    if (-1 < descriptionColumnIndex) {
        // First we need to remove the existing column definition
        // from the metadata.
        metadata.columns.splice(descriptionColumnIndex, 1);
        // Then we add a new column definition with our custom
        // data type "mediumtext"
        // DANGER: this particular modification will generate a DB migration
        // which will result in data loss of existing descriptions. Make sure
        // to manually check & modify your migration scripts.
        const instance = new ProductTranslation();
        Column({ type: 'mediumtext' })(instance, 'description');
    }
};
```

```ts title="Signature"
type EntityMetadataModifier = (metadata: MetadataArgsStorage) => void | Promise<void>
```


---

---
title: "Configuration"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "MergeConfig"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## mergeConfig

<GenerationInfo sourceFile="packages/core/src/config/merge-config.ts" sourceLine="32" packageName="@vendure/core" />

Performs a deep merge of two VendureConfig objects. Unlike `Object.assign()` the `target` object is
not mutated, instead the function returns a new object which is the result of deeply merging the
values of `source` into `target`.

Arrays do not get merged, they are treated as a single value that will be replaced. So if merging the
`plugins` array, you must explicitly concatenate the array.

*Example*

```ts
const result = mergeConfig(defaultConfig, {
  assetOptions: {
    uploadMaxFileSize: 5000,
  },
  plugins: [
    ...defaultConfig.plugins,
    MyPlugin,
  ]
};
```

```ts title="Signature"
function mergeConfig<T extends VendureConfig>(target: T, source: PartialVendureConfig, depth:  = 0): T
```
Parameters

### target

<MemberInfo kind="parameter" type={`T`} />

### source

<MemberInfo kind="parameter" type={`PartialVendureConfig`} />

### depth

<MemberInfo kind="parameter" type={``} />



---

---
title: "ProductVariantPriceSelectionStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ProductVariantPriceSelectionStrategy

<GenerationInfo sourceFile="packages/core/src/config/catalog/product-variant-price-selection-strategy.ts" sourceLine="21" packageName="@vendure/core" since="2.0.0" />

The strategy for selecting the price for a ProductVariant in a given Channel.

:::info

This is configured via the `catalogOptions.productVariantPriceSelectionStrategy` property of
your VendureConfig.

:::

```ts title="Signature"
interface ProductVariantPriceSelectionStrategy extends InjectableStrategy {
    selectPrice(
        ctx: RequestContext,
        prices: ProductVariantPrice[],
    ): ProductVariantPrice | undefined | Promise<ProductVariantPrice | undefined>;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### selectPrice

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, prices: <a href='/reference/typescript-api/entities/product-variant-price#productvariantprice'>ProductVariantPrice</a>[]) => <a href='/reference/typescript-api/entities/product-variant-price#productvariantprice'>ProductVariantPrice</a> | undefined | Promise&#60;<a href='/reference/typescript-api/entities/product-variant-price#productvariantprice'>ProductVariantPrice</a> | undefined&#62;`}   />




</div>


## DefaultProductVariantPriceSelectionStrategy

<GenerationInfo sourceFile="packages/core/src/config/catalog/default-product-variant-price-selection-strategy.ts" sourceLine="17" packageName="@vendure/core" since="2.0.0" />

The default strategy for selecting the price for a ProductVariant in a given Channel. It
first filters all available prices to those which are in the current Channel, and then
selects the first price which matches the current currency.

```ts title="Signature"
class DefaultProductVariantPriceSelectionStrategy implements ProductVariantPriceSelectionStrategy {
    selectPrice(ctx: RequestContext, prices: ProductVariantPrice[]) => ;
}
```
* Implements: <code><a href='/reference/typescript-api/configuration/product-variant-price-selection-strategy#productvariantpriceselectionstrategy'>ProductVariantPriceSelectionStrategy</a></code>



<div className="members-wrapper">

### selectPrice

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, prices: <a href='/reference/typescript-api/entities/product-variant-price#productvariantprice'>ProductVariantPrice</a>[]) => `}   />




</div>


---

---
title: "ProductVariantPriceUpdateStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ProductVariantPriceUpdateStrategy

<GenerationInfo sourceFile="packages/core/src/config/catalog/product-variant-price-update-strategy.ts" sourceLine="58" packageName="@vendure/core" since="2.2.0" />

This strategy determines how updates to a ProductVariantPrice is handled in regard to
any other prices which may be associated with the same ProductVariant.

For instance, in a multichannel setup, if a price is updated for a ProductVariant in one
Channel, this strategy can be used to update the prices in other Channels.

Using custom logic, this can be made more sophisticated - for example, you could have a
one-way sync that only updates prices in child channels when the price in the default
channel is updated. You could also have a conditional sync which is dependent on the
permissions of the current administrator, or based on custom field flags on the ProductVariant
or Channel.

Another use-case might be to update the prices of a ProductVariant in other currencies
when a price is updated in one currency, based on the current exchange rate.


:::info

This is configured via the `catalogOptions.productVariantPriceUpdateStrategy` property of
your VendureConfig.

:::

```ts title="Signature"
interface ProductVariantPriceUpdateStrategy extends InjectableStrategy {
    onPriceCreated(
        ctx: RequestContext,
        createdPrice: ProductVariantPrice,
        prices: ProductVariantPrice[],
    ): UpdatedProductVariantPrice[] | Promise<UpdatedProductVariantPrice[]>;
    onPriceUpdated(
        ctx: RequestContext,
        updatedPrice: ProductVariantPrice,
        prices: ProductVariantPrice[],
    ): UpdatedProductVariantPrice[] | Promise<UpdatedProductVariantPrice[]>;
    onPriceDeleted(
        ctx: RequestContext,
        deletedPrice: ProductVariantPrice,
        prices: ProductVariantPrice[],
    ): UpdatedProductVariantPrice[] | Promise<UpdatedProductVariantPrice[]>;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### onPriceCreated

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, createdPrice: <a href='/reference/typescript-api/entities/product-variant-price#productvariantprice'>ProductVariantPrice</a>, prices: <a href='/reference/typescript-api/entities/product-variant-price#productvariantprice'>ProductVariantPrice</a>[]) => UpdatedProductVariantPrice[] | Promise&#60;UpdatedProductVariantPrice[]&#62;`}   />

This method is called when a ProductVariantPrice is created. It receives the created
ProductVariantPrice and the array of all prices associated with the ProductVariant.

It should return an array of UpdatedProductVariantPrice objects which will be used to update
the prices of the specific ProductVariantPrices.
### onPriceUpdated

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, updatedPrice: <a href='/reference/typescript-api/entities/product-variant-price#productvariantprice'>ProductVariantPrice</a>, prices: <a href='/reference/typescript-api/entities/product-variant-price#productvariantprice'>ProductVariantPrice</a>[]) => UpdatedProductVariantPrice[] | Promise&#60;UpdatedProductVariantPrice[]&#62;`}   />

This method is called when a ProductVariantPrice is updated. It receives the updated
ProductVariantPrice and the array of all prices associated with the ProductVariant.

It should return an array of UpdatedProductVariantPrice objects which will be used to update
the prices of the specific ProductVariantPrices.
### onPriceDeleted

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, deletedPrice: <a href='/reference/typescript-api/entities/product-variant-price#productvariantprice'>ProductVariantPrice</a>, prices: <a href='/reference/typescript-api/entities/product-variant-price#productvariantprice'>ProductVariantPrice</a>[]) => UpdatedProductVariantPrice[] | Promise&#60;UpdatedProductVariantPrice[]&#62;`}   />

This method is called when a ProductVariantPrice is deleted. It receives the deleted
ProductVariantPrice and the array of all prices associated with the ProductVariant.

It should return an array of UpdatedProductVariantPrice objects which will be used to update
the prices of the specific ProductVariantPrices.


</div>


## DefaultProductVariantPriceUpdateStrategyOptions

<GenerationInfo sourceFile="packages/core/src/config/catalog/default-product-variant-price-update-strategy.ts" sourceLine="14" packageName="@vendure/core" since="2.2.0" />

The options available to the <a href='/reference/typescript-api/configuration/product-variant-price-update-strategy#defaultproductvariantpriceupdatestrategy'>DefaultProductVariantPriceUpdateStrategy</a>.

```ts title="Signature"
interface DefaultProductVariantPriceUpdateStrategyOptions {
    syncPricesAcrossChannels: boolean;
}
```

<div className="members-wrapper">

### syncPricesAcrossChannels

<MemberInfo kind="property" type={`boolean`}   />

When `true`, any price changes to a ProductVariant in one Channel will update any other
prices of the same currencyCode in other Channels. Note that if there are different
tax settings across the channels, these will not be taken into account. To handle this
case, a custom strategy should be implemented.


</div>


## DefaultProductVariantPriceUpdateStrategy

<GenerationInfo sourceFile="packages/core/src/config/catalog/default-product-variant-price-update-strategy.ts" sourceLine="56" packageName="@vendure/core" since="2.2.0" />

The default <a href='/reference/typescript-api/configuration/product-variant-price-update-strategy#productvariantpriceupdatestrategy'>ProductVariantPriceUpdateStrategy</a> which by default will not update any other
prices when a price is created, updated or deleted.

If the `syncPricesAcrossChannels` option is set to `true`, then when a price is updated in one Channel,
the price of the same currencyCode in other Channels will be updated to match.  Note that if there are different
tax settings across the channels, these will not be taken into account. To handle this
case, a custom strategy should be implemented.

*Example*

```ts
import { DefaultProductVariantPriceUpdateStrategy, VendureConfig } from '@vendure/core';

export const config: VendureConfig = {
  // ...
  catalogOptions: {
    // highlight-start
    productVariantPriceUpdateStrategy: new DefaultProductVariantPriceUpdateStrategy({
      syncPricesAcrossChannels: true,
    }),
    // highlight-end
  },
  // ...
};
```

```ts title="Signature"
class DefaultProductVariantPriceUpdateStrategy implements ProductVariantPriceUpdateStrategy {
    constructor(options: DefaultProductVariantPriceUpdateStrategyOptions)
    onPriceCreated(ctx: RequestContext, price: ProductVariantPrice) => ;
    onPriceUpdated(ctx: RequestContext, updatedPrice: ProductVariantPrice, prices: ProductVariantPrice[]) => ;
    onPriceDeleted(ctx: RequestContext, deletedPrice: ProductVariantPrice, prices: ProductVariantPrice[]) => ;
}
```
* Implements: <code><a href='/reference/typescript-api/configuration/product-variant-price-update-strategy#productvariantpriceupdatestrategy'>ProductVariantPriceUpdateStrategy</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(options: <a href='/reference/typescript-api/configuration/product-variant-price-update-strategy#defaultproductvariantpriceupdatestrategyoptions'>DefaultProductVariantPriceUpdateStrategyOptions</a>) => DefaultProductVariantPriceUpdateStrategy`}   />


### onPriceCreated

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, price: <a href='/reference/typescript-api/entities/product-variant-price#productvariantprice'>ProductVariantPrice</a>) => `}   />


### onPriceUpdated

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, updatedPrice: <a href='/reference/typescript-api/entities/product-variant-price#productvariantprice'>ProductVariantPrice</a>, prices: <a href='/reference/typescript-api/entities/product-variant-price#productvariantprice'>ProductVariantPrice</a>[]) => `}   />


### onPriceDeleted

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, deletedPrice: <a href='/reference/typescript-api/entities/product-variant-price#productvariantprice'>ProductVariantPrice</a>, prices: <a href='/reference/typescript-api/entities/product-variant-price#productvariantprice'>ProductVariantPrice</a>[]) => `}   />




</div>


---

---
title: "RuntimeVendureConfig"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## RuntimeVendureConfig

<GenerationInfo sourceFile="packages/core/src/config/vendure-config.ts" sourceLine="1309" packageName="@vendure/core" />

This interface represents the VendureConfig object available at run-time, i.e. the user-supplied
config values have been merged with the <a href='/reference/typescript-api/configuration/default-config#defaultconfig'>defaultConfig</a> values.

```ts title="Signature"
interface RuntimeVendureConfig extends Required<VendureConfig> {
    apiOptions: Required<ApiOptions>;
    assetOptions: Required<AssetOptions>;
    authOptions: Required<AuthOptions>;
    catalogOptions: Required<CatalogOptions>;
    customFields: Required<CustomFields>;
    entityOptions: Required<Omit<EntityOptions, 'entityIdStrategy'>> & EntityOptions;
    importExportOptions: Required<ImportExportOptions>;
    jobQueueOptions: Required<JobQueueOptions>;
    schedulerOptions: Required<SchedulerOptions>;
    orderOptions: Required<OrderOptions>;
    promotionOptions: Required<PromotionOptions>;
    shippingOptions: Required<ShippingOptions>;
    taxOptions: Required<TaxOptions>;
    systemOptions: Required<SystemOptions>;
}
```
* Extends: <code>Required&#60;<a href='/reference/typescript-api/configuration/vendure-config#vendureconfig'>VendureConfig</a>&#62;</code>



<div className="members-wrapper">

### apiOptions

<MemberInfo kind="property" type={`Required&#60;<a href='/reference/typescript-api/configuration/api-options#apioptions'>ApiOptions</a>&#62;`}   />


### assetOptions

<MemberInfo kind="property" type={`Required&#60;<a href='/reference/typescript-api/assets/asset-options#assetoptions'>AssetOptions</a>&#62;`}   />


### authOptions

<MemberInfo kind="property" type={`Required&#60;<a href='/reference/typescript-api/auth/auth-options#authoptions'>AuthOptions</a>&#62;`}   />


### catalogOptions

<MemberInfo kind="property" type={`Required&#60;<a href='/reference/typescript-api/products-stock/catalog-options#catalogoptions'>CatalogOptions</a>&#62;`}   />


### customFields

<MemberInfo kind="property" type={`Required&#60;<a href='/reference/typescript-api/custom-fields/#customfields'>CustomFields</a>&#62;`}   />


### entityOptions

<MemberInfo kind="property" type={`Required&#60;Omit&#60;<a href='/reference/typescript-api/configuration/entity-options#entityoptions'>EntityOptions</a>, 'entityIdStrategy'&#62;&#62; &#38; <a href='/reference/typescript-api/configuration/entity-options#entityoptions'>EntityOptions</a>`}   />


### importExportOptions

<MemberInfo kind="property" type={`Required&#60;<a href='/reference/typescript-api/import-export/import-export-options#importexportoptions'>ImportExportOptions</a>&#62;`}   />


### jobQueueOptions

<MemberInfo kind="property" type={`Required&#60;<a href='/reference/typescript-api/job-queue/job-queue-options#jobqueueoptions'>JobQueueOptions</a>&#62;`}   />


### schedulerOptions

<MemberInfo kind="property" type={`Required&#60;<a href='/reference/typescript-api/scheduled-tasks/scheduler-options#scheduleroptions'>SchedulerOptions</a>&#62;`}   />


### orderOptions

<MemberInfo kind="property" type={`Required&#60;<a href='/reference/typescript-api/orders/order-options#orderoptions'>OrderOptions</a>&#62;`}   />


### promotionOptions

<MemberInfo kind="property" type={`Required&#60;<a href='/reference/typescript-api/promotions/promotion-options#promotionoptions'>PromotionOptions</a>&#62;`}   />


### shippingOptions

<MemberInfo kind="property" type={`Required&#60;<a href='/reference/typescript-api/shipping/shipping-options#shippingoptions'>ShippingOptions</a>&#62;`}   />


### taxOptions

<MemberInfo kind="property" type={`Required&#60;<a href='/reference/typescript-api/tax/tax-options#taxoptions'>TaxOptions</a>&#62;`}   />


### systemOptions

<MemberInfo kind="property" type={`Required&#60;<a href='/reference/typescript-api/configuration/system-options#systemoptions'>SystemOptions</a>&#62;`}   />




</div>


---

---
title: "SettingsStoreFields"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## SettingsStoreFields

<GenerationInfo sourceFile="packages/core/src/config/settings-store/settings-store-types.ts" sourceLine="111" packageName="@vendure/core" since="3.4.0" />

This is how SettingsStoreFields are defined in the <a href='/reference/typescript-api/configuration/vendure-config#vendureconfig'>VendureConfig</a> object.

```ts title="Signature"
type SettingsStoreFields = {
    [namespace: string]: SettingsStoreFieldConfig[];
}
```

<div className="members-wrapper">

### [index]

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/settings-store/settings-store-field-config#settingsstorefieldconfig'>SettingsStoreFieldConfig</a>[]`}   />




</div>


---

---
title: "SystemOptions"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## SystemOptions

<GenerationInfo sourceFile="packages/core/src/config/vendure-config.ts" sourceLine="1124" packageName="@vendure/core" since="1.6.0" />

Options relating to system functions.

```ts title="Signature"
interface SystemOptions {
    healthChecks?: HealthCheckStrategy[];
    errorHandlers?: ErrorHandlerStrategy[];
    cacheStrategy?: CacheStrategy;
    instrumentationStrategy?: InstrumentationStrategy;
}
```

<div className="members-wrapper">

### healthChecks

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/health-check/health-check-strategy#healthcheckstrategy'>HealthCheckStrategy</a>[]`} default={`[<a href='/reference/typescript-api/health-check/type-ormhealth-check-strategy#typeormhealthcheckstrategy'>TypeORMHealthCheckStrategy</a>]`}  since="1.6.0"  />

Defines an array of <a href='/reference/typescript-api/health-check/health-check-strategy#healthcheckstrategy'>HealthCheckStrategy</a> instances which are used by the `/health` endpoint to verify
that any critical systems which the Vendure server depends on are also healthy.
### errorHandlers

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/errors/error-handler-strategy#errorhandlerstrategy'>ErrorHandlerStrategy</a>[]`} default={`[]`}  since="2.2.0"  />

Defines an array of <a href='/reference/typescript-api/errors/error-handler-strategy#errorhandlerstrategy'>ErrorHandlerStrategy</a> instances which are used to define logic to be executed
when an error occurs, either on the server or the worker.
### cacheStrategy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/cache/cache-strategy#cachestrategy'>CacheStrategy</a>`} default={`InMemoryCacheStrategy`}  since="3.1.0"  />

Defines the underlying method used to store cache key-value pairs which powers the
<a href='/reference/typescript-api/cache/cache-service#cacheservice'>CacheService</a>.
### instrumentationStrategy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/telemetry/instrumentation-strategy#instrumentationstrategy'>InstrumentationStrategy</a>`}   />




</div>


---

---
title: "TrustProxyOptions"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## TrustProxyOptions

<GenerationInfo sourceFile="packages/core/src/config/vendure-config.ts" sourceLine="244" packageName="@vendure/core" since="3.4.0" />

Configures Express trust proxy settings when running behind a reverse proxy (usually the case with most hosting services).
Setting `trustProxy` allows you to retrieve the original IP address from the `X-Forwarded-For` header.

See the [express documentation](https://expressjs.com/en/guide/behind-proxies.html) for more details.

```ts title="Signature"
type TrustProxyOptions = boolean | number | string | string[] | ((ip: string) => boolean)
```


---

---
title: "VendureConfig"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## VendureConfig

<GenerationInfo sourceFile="packages/core/src/config/vendure-config.ts" sourceLine="1162" packageName="@vendure/core" />

All possible configuration options are defined by the
[`VendureConfig`](https://github.com/vendure-ecommerce/vendure/blob/master/packages/core/src/config/vendure-config.ts) interface.

```ts title="Signature"
interface VendureConfig {
    apiOptions: ApiOptions;
    assetOptions?: AssetOptions;
    authOptions: AuthOptions;
    catalogOptions?: CatalogOptions;
    customFields?: CustomFields;
    settingsStoreFields?: SettingsStoreFields;
    dbConnectionOptions: DataSourceOptions;
    defaultChannelToken?: string | null;
    defaultLanguageCode?: LanguageCode;
    entityIdStrategy?: EntityIdStrategy<any>;
    entityOptions?: EntityOptions;
    importExportOptions?: ImportExportOptions;
    orderOptions?: OrderOptions;
    paymentOptions: PaymentOptions;
    plugins?: Array<DynamicModule | Type<any>>;
    promotionOptions?: PromotionOptions;
    shippingOptions?: ShippingOptions;
    logger?: VendureLogger;
    taxOptions?: TaxOptions;
    jobQueueOptions?: JobQueueOptions;
    schedulerOptions?: SchedulerOptions;
    systemOptions?: SystemOptions;
}
```

<div className="members-wrapper">

### apiOptions

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/configuration/api-options#apioptions'>ApiOptions</a>`}   />

Configuration for the GraphQL APIs, including hostname, port, CORS settings,
middleware etc.
### assetOptions

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/assets/asset-options#assetoptions'>AssetOptions</a>`}   />

Configuration for the handling of Assets.
### authOptions

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/auth/auth-options#authoptions'>AuthOptions</a>`}   />

Configuration for authorization.
### catalogOptions

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/products-stock/catalog-options#catalogoptions'>CatalogOptions</a>`}   />

Configuration for Products and Collections.
### customFields

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/custom-fields/#customfields'>CustomFields</a>`} default={`{}`}   />

Defines custom fields which can be used to extend the built-in entities.
### settingsStoreFields

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/configuration/settings-store-fields#settingsstorefields'>SettingsStoreFields</a>`}  since="3.4.0"  />

Defines key-value fields that can be set and read via the `getKeyValue`/`setKeyValue` GraphQL APIs
and via the <a href='/reference/typescript-api/services/settings-store-service#settingsstoreservice'>SettingsStoreService</a>. These differ from custom fields in that they are not associated
with a specific entity, but can be scoped globally or to a specific user etc, and defining them does not
require any changes to the database schema.
### dbConnectionOptions

<MemberInfo kind="property" type={`DataSourceOptions`}   />

The connection options used by TypeORM to connect to the database.
See the [TypeORM documentation](https://typeorm.io/#/connection-options) for a
full description of all available options.
### defaultChannelToken

<MemberInfo kind="property" type={`string | null`} default={`null`}   />

The token for the default channel. If not specified, a token
will be randomly generated.
### defaultLanguageCode

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a>`} default={`<a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a>.en`}   />

The default languageCode of the app.
### entityIdStrategy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/configuration/entity-id-strategy#entityidstrategy'>EntityIdStrategy</a>&#60;any&#62;`} default={`<a href='/reference/typescript-api/configuration/entity-id-strategy#autoincrementidstrategy'>AutoIncrementIdStrategy</a>`}   />

Defines the strategy used for both storing the primary keys of entities
in the database, and the encoding & decoding of those ids when exposing
entities via the API. The default uses a simple auto-increment integer
strategy.
### entityOptions

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/configuration/entity-options#entityoptions'>EntityOptions</a>`}   />


### importExportOptions

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/import-export/import-export-options#importexportoptions'>ImportExportOptions</a>`}   />

Configuration settings for data import and export.
### orderOptions

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/orders/order-options#orderoptions'>OrderOptions</a>`}   />

Configuration settings governing how orders are handled.
### paymentOptions

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/payment/payment-options#paymentoptions'>PaymentOptions</a>`}   />

Configures available payment processing methods.
### plugins

<MemberInfo kind="property" type={`Array&#60;DynamicModule | Type&#60;any&#62;&#62;`} default={`[]`}   />

An array of plugins.
### promotionOptions

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/promotions/promotion-options#promotionoptions'>PromotionOptions</a>`}   />

Configures the Conditions and Actions available when creating Promotions.
### shippingOptions

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/shipping/shipping-options#shippingoptions'>ShippingOptions</a>`}   />

Configures the available checkers and calculators for ShippingMethods.
### logger

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/logger/vendure-logger#vendurelogger'>VendureLogger</a>`} default={`<a href='/reference/typescript-api/logger/default-logger#defaultlogger'>DefaultLogger</a>`}   />

Provide a logging service which implements the <a href='/reference/typescript-api/logger/vendure-logger#vendurelogger'>VendureLogger</a> interface.
Note that the logging of SQL queries is controlled separately by the
`dbConnectionOptions.logging` property.
### taxOptions

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/tax/tax-options#taxoptions'>TaxOptions</a>`}   />

Configures how taxes are calculated on products.
### jobQueueOptions

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/job-queue/job-queue-options#jobqueueoptions'>JobQueueOptions</a>`}   />

Configures how the job queue is persisted and processed.
### schedulerOptions

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/scheduled-tasks/scheduler-options#scheduleroptions'>SchedulerOptions</a>`}  since="3.3.0"  />

Configures the scheduler mechanism and tasks.
### systemOptions

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/configuration/system-options#systemoptions'>SystemOptions</a>`}  since="1.6.0"  />

Configures system options


</div>


---

---
title: "CustomFieldConfig"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## CustomFieldConfig

<GenerationInfo sourceFile="packages/core/src/config/custom-field/custom-field-types.ts" sourceLine="237" packageName="@vendure/core" />

An object used to configure a custom field.

```ts title="Signature"
type CustomFieldConfig = | StringCustomFieldConfig
    | LocaleStringCustomFieldConfig
    | TextCustomFieldConfig
    | LocaleTextCustomFieldConfig
    | IntCustomFieldConfig
    | FloatCustomFieldConfig
    | BooleanCustomFieldConfig
    | DateTimeCustomFieldConfig
    | RelationCustomFieldConfig
    | StructCustomFieldConfig
```


---

---
title: "CustomFieldType"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## CustomFieldType

<GenerationInfo sourceFile="packages/common/src/shared-types.ts" sourceLine="104" packageName="@vendure/common" />

A data type for a custom field. The CustomFieldType determines the data types used in the generated
database columns and GraphQL fields as follows (key: m = MySQL, p = Postgres, s = SQLite):

Type         | DB type                               | GraphQL type
-----        |---------                              |---------------
string       | varchar                               | String
localeString | varchar                               | String
text         | longtext(m), text(p,s)                | String
localeText   | longtext(m), text(p,s)                | String
int          | int                                   | Int
float        | double precision                      | Float
boolean      | tinyint (m), bool (p), boolean (s)    | Boolean
datetime     | datetime (m,s), timestamp (p)         | DateTime
struct       | json (m), jsonb (p), text (s)         | JSON
relation     | many-to-one / many-to-many relation   | As specified in config

Additionally, the CustomFieldType also dictates which [configuration options](/guides/developer-guide/custom-fields/#custom-field-config-properties)
are available for that custom field.

```ts title="Signature"
type CustomFieldType = | 'string'
    | 'localeString'
    | 'int'
    | 'float'
    | 'boolean'
    | 'datetime'
    | 'relation'
    | 'text'
    | 'localeText'
    | 'struct'
```


---

---
title: "CustomFields"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## CustomFields

<GenerationInfo sourceFile="packages/core/src/config/custom-field/custom-field-types.ts" sourceLine="273" packageName="@vendure/core" />

Most entities can have additional fields added to them by defining an array of <a href='/reference/typescript-api/custom-fields/custom-field-config#customfieldconfig'>CustomFieldConfig</a>objects on against the corresponding key.

*Example*

```ts
bootstrap({
    // ...
    customFields: {
        Product: [
            { name: 'infoUrl', type: 'string' },
            { name: 'downloadable', type: 'boolean', defaultValue: false },
            { name: 'shortName', type: 'localeString' },
        ],
        User: [
            { name: 'socialLoginToken', type: 'string', public: false },
        ],
    },
})
```

```ts title="Signature"
type CustomFields = {
    Address?: CustomFieldConfig[];
    Administrator?: CustomFieldConfig[];
    Asset?: CustomFieldConfig[];
    Channel?: CustomFieldConfig[];
    Collection?: CustomFieldConfig[];
    Customer?: CustomFieldConfig[];
    CustomerGroup?: CustomFieldConfig[];
    Facet?: CustomFieldConfig[];
    FacetValue?: CustomFieldConfig[];
    Fulfillment?: CustomFieldConfig[];
    GlobalSettings?: CustomFieldConfig[];
    HistoryEntry?: CustomFieldConfig[];
    Order?: CustomFieldConfig[];
    OrderLine?: CustomFieldConfig[];
    Payment?: CustomFieldConfig[];
    PaymentMethod?: CustomFieldConfig[];
    Product?: CustomFieldConfig[];
    ProductOption?: CustomFieldConfig[];
    ProductOptionGroup?: CustomFieldConfig[];
    ProductVariant?: CustomFieldConfig[];
    ProductVariantPrice?: CustomFieldConfig[];
    Promotion?: CustomFieldConfig[];
    Refund?: CustomFieldConfig[];
    Region?: CustomFieldConfig[];
    Seller?: CustomFieldConfig[];
    Session?: CustomFieldConfig[];
    ShippingLine?: CustomFieldConfig[];
    ShippingMethod?: CustomFieldConfig[];
    StockLevel?: CustomFieldConfig[];
    StockLocation?: CustomFieldConfig[];
    StockMovement?: CustomFieldConfig[];
    TaxCategory?: CustomFieldConfig[];
    TaxRate?: CustomFieldConfig[];
    User?: CustomFieldConfig[];
    Zone?: CustomFieldConfig[];
} & { [entity: string]: CustomFieldConfig[] }
```


---

---
title: "StructCustomFieldConfig"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## StructCustomFieldConfig

<GenerationInfo sourceFile="packages/core/src/config/custom-field/custom-field-types.ts" sourceLine="224" packageName="@vendure/core" since="3.1.0" />

Configures a "struct" custom field.

```ts title="Signature"
type StructCustomFieldConfig = TypedCustomFieldConfig<
    'struct',
    Omit<GraphQLStructCustomFieldConfig, 'fields'>
> & {
    fields: StructFieldConfig[];
}
```


---

---
title: "StructFieldConfig"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## StructFieldConfig

<GenerationInfo sourceFile="packages/core/src/config/custom-field/custom-field-types.ts" sourceLine="209" packageName="@vendure/core" since="3.1.0" />

Configures an individual field of a "struct" custom field. The individual fields share
the same API as the top-level custom fields, with the exception that they do not support the
`readonly`, `internal`, `nullable`, `unique` and `requiresPermission` options.

*Example*

```ts
const customFields: CustomFields = {
  Product: [
    {
      name: 'specifications',
      type: 'struct',
      fields: [
        { name: 'processor', type: 'string' },
        { name: 'ram', type: 'string' },
        { name: 'screenSize', type: 'float' },
      ],
    },
  ],
};
```

```ts title="Signature"
type StructFieldConfig = | StringStructFieldConfig
    | TextStructFieldConfig
    | IntStructFieldConfig
    | FloatStructFieldConfig
    | BooleanStructFieldConfig
    | DateTimeStructFieldConfig
```


---

---
title: "TypedCustomSingleFieldConfig"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## TypedCustomSingleFieldConfig

<GenerationInfo sourceFile="packages/core/src/config/custom-field/custom-field-types.ts" sourceLine="84" packageName="@vendure/core" />

Configures a custom field on an entity in the <a href='/reference/typescript-api/custom-fields/#customfields'>CustomFields</a> config object.

```ts title="Signature"
type TypedCustomSingleFieldConfig<T extends CustomFieldType, C extends CustomField> = BaseTypedCustomFieldConfig<T, C> & {
    list?: false;
    defaultValue?: DefaultValueType<T>;
    validate?: (
        value: DefaultValueType<T>,
        injector: Injector,
        ctx: RequestContext,
    ) => string | LocalizedString[] | void | Promise<string | LocalizedString[] | void>;
}
```


---

---
title: "CalculatedPropertySubscriber"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## CalculatedPropertySubscriber

<GenerationInfo sourceFile="packages/core/src/entity/subscribers.ts" sourceLine="14" packageName="@vendure/core" />



```ts title="Signature"
class CalculatedPropertySubscriber implements EntitySubscriberInterface {
    afterLoad(event: any) => ;
    afterInsert(event: InsertEvent<any>) => Promise<any> | void;
}
```
* Implements: <code>EntitySubscriberInterface</code>



<div className="members-wrapper">

### afterLoad

<MemberInfo kind="method" type={`(event: any) => `}   />


### afterInsert

<MemberInfo kind="method" type={`(event: InsertEvent&#60;any&#62;) => Promise&#60;any&#62; | void`}   />




</div>


---

---
title: "Calculated"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## Calculated

<GenerationInfo sourceFile="packages/core/src/common/calculated-decorator.ts" sourceLine="43" packageName="@vendure/core" />

Used to define calculated entity getters. The decorator simply attaches an array of "calculated"
property names to the entity's prototype. This array is then used by the <a href='/reference/typescript-api/data-access/calculated-property-subscriber#calculatedpropertysubscriber'>CalculatedPropertySubscriber</a>to transfer the getter function from the prototype to the entity instance.

```ts title="Signature"
function Calculated(queryInstruction?: CalculatedColumnQueryInstruction): MethodDecorator
```
Parameters

### queryInstruction

<MemberInfo kind="parameter" type={`<a href='/reference/typescript-api/data-access/calculated#calculatedcolumnqueryinstruction'>CalculatedColumnQueryInstruction</a>`} />



## CalculatedColumnQueryInstruction

<GenerationInfo sourceFile="packages/core/src/common/calculated-decorator.ts" sourceLine="17" packageName="@vendure/core" />

Optional metadata used to tell the <a href='/reference/typescript-api/data-access/list-query-builder#listquerybuilder'>ListQueryBuilder</a> & <a href='/reference/typescript-api/request/relations-decorator#relations'>Relations</a> decorator how to deal with
calculated columns when sorting, filtering and deriving required relations from GraphQL operations.

```ts title="Signature"
interface CalculatedColumnQueryInstruction {
    relations?: string[];
    query?: (qb: SelectQueryBuilder<any>) => void;
    expression?: string;
}
```

<div className="members-wrapper">

### relations

<MemberInfo kind="property" type={`string[]`}   />

If the calculated property depends on one or more relations being present
on the entity (e.g. an `Order` entity calculating the `totalQuantity` by adding
up the quantities of each `OrderLine`), then those relations should be defined here.
### query

<MemberInfo kind="property" type={`(qb: SelectQueryBuilder&#60;any&#62;) =&#62; void`}   />


### expression

<MemberInfo kind="property" type={`string`}   />




</div>


---

---
title: "EntityHydrator"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## EntityHydrator

<GenerationInfo sourceFile="packages/core/src/service/helpers/entity-hydrator/entity-hydrator.service.ts" sourceLine="77" packageName="@vendure/core" since="1.3.0" />

This is a helper class which is used to "hydrate" entity instances, which means to populate them
with the specified relations. This is useful when writing plugin code which receives an entity,
and you need to ensure that one or more relations are present.

*Example*

```ts
import { Injectable } from '@nestjs/common';
import { ID, RequestContext, EntityHydrator, ProductVariantService } from '@vendure/core';

@Injectable()
export class MyService {

  constructor(
     // highlight-next-line
     private entityHydrator: EntityHydrator,
     private productVariantService: ProductVariantService,
  ) {}

  myMethod(ctx: RequestContext, variantId: ID) {
    const product = await this.productVariantService
      .getProductForVariant(ctx, variantId);

    // at this stage, we don't know which of the Product relations
    // will be joined at runtime.

    // highlight-start
    await this.entityHydrator
      .hydrate(ctx, product, { relations: ['facetValues.facet' ]});

    // You can be sure now that the `facetValues` & `facetValues.facet` relations are populated
    // highlight-end
  }
}
```

In this above example, the `product` instance will now have the `facetValues` relation
available, and those FacetValues will have their `facet` relations joined too.

This `hydrate` method will _also_ automatically take care or translating any
translatable entities (e.g. Product, Collection, Facet), and if the `applyProductVariantPrices`
options is used (see <a href='/reference/typescript-api/data-access/hydrate-options#hydrateoptions'>HydrateOptions</a>), any related ProductVariant will have the correct
Channel-specific prices applied to them.

Custom field relations may also be hydrated:

*Example*

```ts
const customer = await this.customerService
  .findOne(ctx, id);

await this.entityHydrator
  .hydrate(ctx, customer, { relations: ['customFields.avatar' ]});
```

```ts title="Signature"
class EntityHydrator {
    constructor(connection: TransactionalConnection, productPriceApplicator: ProductPriceApplicator, translator: TranslatorService)
    hydrate(ctx: RequestContext, target: Entity, options: HydrateOptions<Entity>) => Promise<Entity>;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, productPriceApplicator: <a href='/reference/typescript-api/service-helpers/product-price-applicator#productpriceapplicator'>ProductPriceApplicator</a>, translator: <a href='/reference/typescript-api/service-helpers/translator-service#translatorservice'>TranslatorService</a>) => EntityHydrator`}   />


### hydrate

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, target: Entity, options: <a href='/reference/typescript-api/data-access/hydrate-options#hydrateoptions'>HydrateOptions</a>&#60;Entity&#62;) => Promise&#60;Entity&#62;`}  since="1.3.0"  />

Hydrates (joins) the specified relations to the target entity instance. This method
mutates the `target` entity.

*Example*

```ts
await this.entityHydrator.hydrate(ctx, product, {
  relations: [
    'variants.stockMovements'
    'optionGroups.options',
    'featuredAsset',
  ],
  applyProductVariantPrices: true,
});
```


</div>


---

---
title: "GetEntityOrThrowOptions"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## GetEntityOrThrowOptions

<GenerationInfo sourceFile="packages/core/src/connection/types.ts" sourceLine="10" packageName="@vendure/core" />

Options used by the <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a> `getEntityOrThrow` method.

```ts title="Signature"
interface GetEntityOrThrowOptions<T = any> extends FindOneOptions<T> {
    channelId?: ID;
    retries?: number;
    retryDelay?: number;
    includeSoftDeleted?: boolean;
}
```
* Extends: <code>FindOneOptions&#60;T&#62;</code>



<div className="members-wrapper">

### channelId

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a>`}   />

An optional channelId to limit results to entities assigned to the given Channel. Should
only be used when getting entities that implement the <a href='/reference/typescript-api/entities/interfaces#channelaware'>ChannelAware</a> interface.
### retries

<MemberInfo kind="property" type={`number`} default={`0`}  since="1.1.0"  />

If set to a positive integer, it will retry getting the entity in case it is initially not
found.
### retryDelay

<MemberInfo kind="property" type={`number`} default={`25`}  since="1.1.0"  />

Specifies the delay in ms to wait between retries.
### includeSoftDeleted

<MemberInfo kind="property" type={`boolean`} default={`false`}  since="1.3.0"  />

If set to `true`, soft-deleted entities will be returned. Otherwise they will
throw as if they did not exist.


</div>


---

---
title: "HydrateOptions"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## HydrateOptions

<GenerationInfo sourceFile="packages/core/src/service/helpers/entity-hydrator/entity-hydrator-types.ts" sourceLine="12" packageName="@vendure/core" since="1.3.0" />

Options used to control which relations of the entity get hydrated
when using the <a href='/reference/typescript-api/data-access/entity-hydrator#entityhydrator'>EntityHydrator</a> helper.

```ts title="Signature"
interface HydrateOptions<Entity extends VendureEntity> {
    relations: Array<EntityRelationPaths<Entity>>;
    applyProductVariantPrices?: boolean;
}
```

<div className="members-wrapper">

### relations

<MemberInfo kind="property" type={`Array&#60;<a href='/reference/typescript-api/common/entity-relation-paths#entityrelationpaths'>EntityRelationPaths</a>&#60;Entity&#62;&#62;`}   />

Defines the relations to hydrate, using strings with dot notation to indicate
nested joins. If the entity already has a particular relation available, that relation
will be skipped (no extra DB join will be added).
### applyProductVariantPrices

<MemberInfo kind="property" type={`boolean`} default={`false`}   />

If set to `true`, any ProductVariants will also have their `price` and `priceWithTax` fields
applied based on the current context. If prices are not required, this can be left `false` which
will be slightly more efficient.


</div>


---

---
title: "Data Access"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "ListQueryBuilder"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ListQueryBuilder

<GenerationInfo sourceFile="packages/core/src/service/helpers/list-query-builder/list-query-builder.ts" sourceLine="201" packageName="@vendure/core" />

This helper class is used when fetching entities the database from queries which return a <a href='/reference/typescript-api/common/paginated-list#paginatedlist'>PaginatedList</a> type.
These queries all follow the same format:

In the GraphQL definition, they return a type which implements the `Node` interface, and the query returns a
type which implements the `PaginatedList` interface:

```GraphQL
type BlogPost implements Node {
  id: ID!
  published: DateTime!
  title: String!
  body: String!
}

type BlogPostList implements PaginatedList {
  items: [BlogPost!]!
  totalItems: Int!
}

# Generated at run-time by Vendure
input BlogPostListOptions

extend type Query {
   blogPosts(options: BlogPostListOptions): BlogPostList!
}
```
When Vendure bootstraps, it will find the `BlogPostListOptions` input and, because it is used in a query
returning a `PaginatedList` type, it knows that it should dynamically generate this input. This means
all primitive field of the `BlogPost` type (namely, "published", "title" and "body") will have `filter` and
`sort` inputs created for them, as well a `skip` and `take` fields for pagination.

Your resolver function will then look like this:

```ts
@Resolver()
export class BlogPostResolver
  constructor(private blogPostService: BlogPostService) {}

  @Query()
  async blogPosts(
    @Ctx() ctx: RequestContext,
    @Args() args: any,
  ): Promise<PaginatedList<BlogPost>> {
    return this.blogPostService.findAll(ctx, args.options || undefined);
  }
}
```

and the corresponding service will use the ListQueryBuilder:

```ts
@Injectable()
export class BlogPostService {
  constructor(private listQueryBuilder: ListQueryBuilder) {}

  findAll(ctx: RequestContext, options?: ListQueryOptions<BlogPost>) {
    return this.listQueryBuilder
      .build(BlogPost, options)
      .getManyAndCount()
      .then(async ([items, totalItems]) => {
        return { items, totalItems };
      });
  }
}
```

```ts title="Signature"
class ListQueryBuilder implements OnApplicationBootstrap {
    constructor(connection: TransactionalConnection, configService: ConfigService)
    filterObjectHasProperty(filterObject: FP | NullOptionals<FP> | null | undefined, property: keyof FP) => boolean;
    build(entity: Type<T>, options: ListQueryOptions<T> = {}, extendedOptions: ExtendedListQueryOptions<T> = {}) => SelectQueryBuilder<T>;
}
```
* Implements: <code>OnApplicationBootstrap</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, configService: ConfigService) => ListQueryBuilder`}   />


### filterObjectHasProperty

<MemberInfo kind="method" type={`(filterObject: FP | NullOptionals&#60;FP&#62; | null | undefined, property: keyof FP) => boolean`}   />

Used to determine whether a list query `filter` object contains the
given property, either at the top level or nested inside a boolean
`_and` or `_or` expression.

This is useful when a custom property map is used to map a filter
field to a related entity, and we need to determine whether the
filter object contains that property, which then means we would need
to join that relation.
### build

<MemberInfo kind="method" type={`(entity: Type&#60;T&#62;, options: ListQueryOptions&#60;T&#62; = {}, extendedOptions: <a href='/reference/typescript-api/data-access/list-query-builder#extendedlistqueryoptions'>ExtendedListQueryOptions</a>&#60;T&#62; = {}) => SelectQueryBuilder&#60;T&#62;`}   />




</div>


## ExtendedListQueryOptions

<GenerationInfo sourceFile="packages/core/src/service/helpers/list-query-builder/list-query-builder.ts" sourceLine="42" packageName="@vendure/core" />

Options which can be passed to the ListQueryBuilder's `build()` method.

```ts title="Signature"
type ExtendedListQueryOptions<T extends VendureEntity> = {
    relations?: string[];
    channelId?: ID;
    where?: FindOptionsWhere<T>;
    orderBy?: FindOneOptions<T>['order'];
    entityAlias?: string;
    ctx?: RequestContext;
    customPropertyMap?: { [name: string]: string };
    ignoreQueryLimits?: boolean;
}
```

<div className="members-wrapper">

### relations

<MemberInfo kind="property" type={`string[]`}   />


### channelId

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a>`}   />


### where

<MemberInfo kind="property" type={`FindOptionsWhere&#60;T&#62;`}   />


### orderBy

<MemberInfo kind="property" type={`FindOneOptions&#60;T&#62;['order']`}   />


### entityAlias

<MemberInfo kind="property" type={`string`}  since="1.6.0"  />

Allows you to specify the alias used for the entity `T` in the generated SQL query.
Defaults to the entity class name lower-cased, i.e. `ProductVariant` -> `'productvariant'`.
### ctx

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>`}   />

When a RequestContext is passed, then the query will be
executed as part of any outer transaction.
### customPropertyMap

<MemberInfo kind="property" type={`{ [name: string]: string }`}   />

One of the main tasks of the ListQueryBuilder is to auto-generate filter and sort queries based on the
available columns of a given entity. However, it may also be sometimes desirable to allow filter/sort
on a property of a relation. In this case, the `customPropertyMap` can be used to define a property
of the `options.sort` or `options.filter` which does not correspond to a direct column of the current
entity, and then provide a mapping to the related property to be sorted/filtered.

Example: we want to allow sort/filter by and Order's `customerLastName`. The actual lastName property is
not a column in the Order table, it exists on the Customer entity, and Order has a relation to Customer via
`Order.customer`. Therefore, we can define a customPropertyMap like this:

*Example*

```GraphQL
"""
Manually extend the filter & sort inputs to include the new
field that we want to be able to use in building list queries.
"""
input OrderFilterParameter {
    customerLastName: StringOperators
}

input OrderSortParameter {
    customerLastName: SortOrder
}
```

*Example*

```ts
const qb = this.listQueryBuilder.build(Order, options, {
  relations: ['customer'],
  customPropertyMap: {
    // Tell TypeORM how to map that custom
    // sort/filter field to the property on a
    // related entity.
    customerLastName: 'customer.lastName',
  },
};
```
We can now use the `customerLastName` property to filter or sort
on the list query:

*Example*

```GraphQL
query {
  myOrderQuery(options: {
    filter: {
      customerLastName: { contains: "sm" }
    }
  }) {
    # ...
  }
}
```
### ignoreQueryLimits

<MemberInfo kind="property" type={`boolean`} default={`false`}  since="2.0.2"  />

When set to `true`, the configured `shopListQueryLimit` and `adminListQueryLimit` values will be ignored,
allowing unlimited results to be returned. Use caution when exposing an unlimited list query to the public,
as it could become a vector for a denial of service attack if an attacker requests a very large list.


</div>


---

---
title: "TransactionalConnection"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## TransactionalConnection

<GenerationInfo sourceFile="packages/core/src/connection/transactional-connection.ts" sourceLine="41" packageName="@vendure/core" />

The TransactionalConnection is a wrapper around the TypeORM `Connection` object which works in conjunction
with the <a href='/reference/typescript-api/request/transaction-decorator#transaction'>Transaction</a> decorator to implement per-request transactions. All services which access the
database should use this class rather than the raw TypeORM connection, to ensure that db changes can be
easily wrapped in transactions when required.

The service layer does not need to know about the scope of a transaction, as this is covered at the
API by the use of the `Transaction` decorator.

```ts title="Signature"
class TransactionalConnection {
    constructor(dataSource: DataSource, transactionWrapper: TransactionWrapper)
    rawConnection: DataSource
    getRepository(target: ObjectType<Entity> | EntitySchema<Entity> | string) => Repository<Entity>;
    getRepository(ctx: RequestContext | undefined, target: ObjectType<Entity> | EntitySchema<Entity> | string, options?: {
            replicationMode?: ReplicationMode;
        }) => Repository<Entity>;
    getRepository(ctxOrTarget: RequestContext | ObjectType<Entity> | EntitySchema<Entity> | string | undefined, maybeTarget?: ObjectType<Entity> | EntitySchema<Entity> | string, options?: {
            replicationMode?: ReplicationMode;
        }) => Repository<Entity>;
    withTransaction(work: (ctx: RequestContext) => Promise<T>) => Promise<T>;
    withTransaction(ctx: RequestContext, work: (ctx: RequestContext) => Promise<T>) => Promise<T>;
    withTransaction(ctxOrWork: RequestContext | ((ctx: RequestContext) => Promise<T>), maybeWork?: (ctx: RequestContext) => Promise<T>) => Promise<T>;
    startTransaction(ctx: RequestContext, isolationLevel?: TransactionIsolationLevel) => ;
    commitOpenTransaction(ctx: RequestContext) => ;
    rollBackTransaction(ctx: RequestContext) => ;
    getEntityOrThrow(ctx: RequestContext, entityType: Type<T>, id: ID, options: GetEntityOrThrowOptions<T> = {}) => Promise<T>;
    findOneInChannel(ctx: RequestContext, entity: Type<T>, id: ID, channelId: ID, options: FindOneOptions<T> = {}) => ;
    findByIdsInChannel(ctx: RequestContext, entity: Type<T>, ids: ID[], channelId: ID, options: FindManyOptions<T>) => ;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(dataSource: DataSource, transactionWrapper: TransactionWrapper) => TransactionalConnection`}   />


### rawConnection

<MemberInfo kind="property" type={`DataSource`}   />

The plain TypeORM Connection object. Should be used carefully as any operations
performed with this connection will not be performed within any outer
transactions.
### getRepository

<MemberInfo kind="method" type={`(target: ObjectType&#60;Entity&#62; | EntitySchema&#60;Entity&#62; | string) => Repository&#60;Entity&#62;`}   />

Returns a TypeORM repository. Note that when no RequestContext is supplied, the repository will not
be aware of any existing transaction. Therefore, calling this method without supplying a RequestContext
is discouraged without a deliberate reason.
### getRepository

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a> | undefined, target: ObjectType&#60;Entity&#62; | EntitySchema&#60;Entity&#62; | string, options?: {             replicationMode?: ReplicationMode;         }) => Repository&#60;Entity&#62;`}   />

Returns a TypeORM repository which is bound to any existing transactions. It is recommended to _always_ pass
the RequestContext argument when possible, otherwise the queries will be executed outside of any
ongoing transactions which have been started by the <a href='/reference/typescript-api/request/transaction-decorator#transaction'>Transaction</a> decorator.

The `options` parameter allows specifying additional configurations, such as the `replicationMode`,
which determines whether the repository should interact with the master or replica database.
### getRepository

<MemberInfo kind="method" type={`(ctxOrTarget: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a> | ObjectType&#60;Entity&#62; | EntitySchema&#60;Entity&#62; | string | undefined, maybeTarget?: ObjectType&#60;Entity&#62; | EntitySchema&#60;Entity&#62; | string, options?: {             replicationMode?: ReplicationMode;         }) => Repository&#60;Entity&#62;`}   />

Returns a TypeORM repository. Depending on the parameters passed, it will either be transaction-aware
or not. If `RequestContext` is provided, the repository is bound to any ongoing transactions. The
`options` parameter allows further customization, such as selecting the replication mode (e.g., 'master').
### withTransaction

<MemberInfo kind="method" type={`(work: (ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) =&#62; Promise&#60;T&#62;) => Promise&#60;T&#62;`}  since="1.3.0"  />

Allows database operations to be wrapped in a transaction, ensuring that in the event of an error being
thrown at any point, the entire transaction will be rolled back and no changes will be saved.

In the context of API requests, you should instead use the <a href='/reference/typescript-api/request/transaction-decorator#transaction'>Transaction</a> decorator on your resolver or
controller method.

On the other hand, for code that does not run in the context of a GraphQL/REST request, this method
should be used to protect against non-atomic changes to the data which could leave your data in an
inconsistent state.

Such situations include function processed by the JobQueue or stand-alone scripts which make use
of Vendure internal services.

If there is already a <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a> object available, you should pass it in as the first
argument in order to create transactional context as the copy. If not, omit the first argument and an empty
RequestContext object will be created, which is then used to propagate the transaction to
all inner method calls.

*Example*

```ts
private async transferCredit(outerCtx: RequestContext, fromId: ID, toId: ID, amount: number) {
  await this.connection.withTransaction(outerCtx, async ctx => {
    // Note you must not use `outerCtx` here, instead use `ctx`. Otherwise, this query
    // will be executed outside of transaction
    await this.giftCardService.updateCustomerCredit(ctx, fromId, -amount);

    await this.connection.getRepository(ctx, GiftCard).update(fromId, { transferred: true })

    // If some intermediate logic here throws an Error,
    // then all DB transactions will be rolled back and neither Customer's
    // credit balance will have changed.

    await this.giftCardService.updateCustomerCredit(ctx, toId, amount);
  })
}
```
### withTransaction

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, work: (ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) =&#62; Promise&#60;T&#62;) => Promise&#60;T&#62;`}   />


### withTransaction

<MemberInfo kind="method" type={`(ctxOrWork: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a> | ((ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) =&#62; Promise&#60;T&#62;), maybeWork?: (ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) =&#62; Promise&#60;T&#62;) => Promise&#60;T&#62;`}   />


### startTransaction

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, isolationLevel?: <a href='/reference/typescript-api/request/transaction-decorator#transactionisolationlevel'>TransactionIsolationLevel</a>) => `}   />

Manually start a transaction if one is not already in progress. This method should be used in
conjunction with the `'manual'` mode of the <a href='/reference/typescript-api/request/transaction-decorator#transaction'>Transaction</a> decorator.
### commitOpenTransaction

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => `}   />

Manually commits any open transaction. Should be very rarely needed, since the <a href='/reference/typescript-api/request/transaction-decorator#transaction'>Transaction</a> decorator
and the internal TransactionInterceptor take care of this automatically. Use-cases include situations
in which the worker thread needs to access changes made in the current transaction, or when using the
Transaction decorator in manual mode.
### rollBackTransaction

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => `}   />

Manually rolls back any open transaction. Should be very rarely needed, since the <a href='/reference/typescript-api/request/transaction-decorator#transaction'>Transaction</a> decorator
and the internal TransactionInterceptor take care of this automatically. Use-cases include when using the
Transaction decorator in manual mode.
### getEntityOrThrow

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, entityType: Type&#60;T&#62;, id: <a href='/reference/typescript-api/common/id#id'>ID</a>, options: <a href='/reference/typescript-api/data-access/get-entity-or-throw-options#getentityorthrowoptions'>GetEntityOrThrowOptions</a>&#60;T&#62; = {}) => Promise&#60;T&#62;`}   />

Finds an entity of the given type by ID, or throws an `EntityNotFoundError` if none
is found.
### findOneInChannel

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, entity: Type&#60;T&#62;, id: <a href='/reference/typescript-api/common/id#id'>ID</a>, channelId: <a href='/reference/typescript-api/common/id#id'>ID</a>, options: FindOneOptions&#60;T&#62; = {}) => `}   />

Like the TypeOrm `Repository.findOne()` method, but limits the results to
the given Channel.
### findByIdsInChannel

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, entity: Type&#60;T&#62;, ids: <a href='/reference/typescript-api/common/id#id'>ID</a>[], channelId: <a href='/reference/typescript-api/common/id#id'>ID</a>, options: FindManyOptions&#60;T&#62;) => `}   />

Like the TypeOrm `Repository.findByIds()` method, but limits the results to
the given Channel.


</div>


---

---
title: "DefaultSearchPluginInitOptions"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DefaultSearchPluginInitOptions

<GenerationInfo sourceFile="packages/core/src/plugin/default-search-plugin/types.ts" sourceLine="15" packageName="@vendure/core" />

Options which configure the behaviour of the DefaultSearchPlugin

```ts title="Signature"
interface DefaultSearchPluginInitOptions {
    indexStockStatus?: boolean;
    bufferUpdates?: boolean;
    searchStrategy?: SearchStrategy;
}
```

<div className="members-wrapper">

### indexStockStatus

<MemberInfo kind="property" type={`boolean`} default={`false.`}   />

If set to `true`, the stock status of a ProductVariant (inStock: Boolean) will
be exposed in the `search` query results. Enabling this option on an existing
Vendure installation will require a DB migration/synchronization.
### bufferUpdates

<MemberInfo kind="property" type={`boolean`} default={`false`}  since="1.3.0"  />

If set to `true`, updates to Products, ProductVariants and Collections will not immediately
trigger an update to the search index. Instead, all these changes will be buffered and will
only be run via a call to the `runPendingSearchIndexUpdates` mutation in the Admin API.

This is very useful for installations with a large number of ProductVariants and/or
Collections, as the buffering allows better control over when these expensive jobs are run,
and also performs optimizations to minimize the amount of work that needs to be performed by
the worker.
### searchStrategy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/default-search-plugin/search-strategy#searchstrategy'>SearchStrategy</a>`} default={`undefined`}  since="1.6.0"  />

Set a custom search strategy that implements <a href='/reference/typescript-api/default-search-plugin/search-strategy#searchstrategy'>SearchStrategy</a> or extends an existing search strategy
such as <a href='/reference/typescript-api/default-search-plugin/mysql-search-strategy#mysqlsearchstrategy'>MysqlSearchStrategy</a>, <a href='/reference/typescript-api/default-search-plugin/postgres-search-strategy#postgressearchstrategy'>PostgresSearchStrategy</a> or <a href='/reference/typescript-api/default-search-plugin/sqlite-search-strategy#sqlitesearchstrategy'>SqliteSearchStrategy</a>.

*Example*

```ts
export class MySearchStrategy implements SearchStrategy {
    private readonly minTermLength = 2;
    private connection: TransactionalConnection;
    private options: DefaultSearchPluginInitOptions;

    async init(injector: Injector) {
        this.connection = injector.get(TransactionalConnection);
        this.options = injector.get(PLUGIN_INIT_OPTIONS);
    }

    async getFacetValueIds(
        ctx: RequestContext,
        input: SearchInput,
        enabledOnly: boolean,
    ): Promise<Map<ID, number>> {
        // ...
        return createFacetIdCountMap(facetValuesResult);
    }

    async getCollectionIds(
        ctx: RequestContext,
        input: SearchInput,
        enabledOnly: boolean,
    ): Promise<Map<ID, number>> {
        // ...
        return createCollectionIdCountMap(collectionsResult);
    }

    async getSearchResults(
        ctx: RequestContext,
        input: SearchInput,
        enabledOnly: boolean,
    ): Promise<SearchResult[]> {
        const take = input.take || 25;
        const skip = input.skip || 0;
        const sort = input.sort;
        const qb = this.connection
            .getRepository(SearchIndexItem)
            .createQueryBuilder('si')
            .select(this.createMysqlSelect(!!input.groupByProduct));
        // ...

        return qb
            .take(take)
            .skip(skip)
            .getRawMany()
            .then(res => res.map(r => mapToSearchResult(r, ctx.channel.currencyCode)));
    }

    async getTotalCount(ctx: RequestContext, input: SearchInput, enabledOnly: boolean): Promise<number> {
        const innerQb = this.applyTermAndFilters(
            ctx,
            this.connection
                .getRepository(SearchIndexItem)
                .createQueryBuilder('si')
                .select(this.createMysqlSelect(!!input.groupByProduct)),
            input,
        );
        if (enabledOnly) {
            innerQb.andWhere('si.enabled = :enabled', { enabled: true });
        }

        const totalItemsQb = this.connection.rawConnection
            .createQueryBuilder()
            .select('COUNT(*) as total')
            .from(`(${innerQb.getQuery()})`, 'inner')
            .setParameters(innerQb.getParameters());
        return totalItemsQb.getRawOne().then(res => res.total);
    }
}
```


</div>


---

---
title: "DefaultSearchPlugin"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DefaultSearchPlugin

<GenerationInfo sourceFile="packages/core/src/plugin/default-search-plugin/default-search-plugin.ts" sourceLine="70" packageName="@vendure/core" />

The DefaultSearchPlugin provides a full-text Product search based on the full-text searching capabilities of the
underlying database.

The DefaultSearchPlugin is bundled with the `@vendure/core` package. If you are not using an alternative search
plugin, then make sure this one is used, otherwise you will not be able to search products via the
[`search` query](/reference/graphql-api/shop/queries#search).

:::caution
Note that the quality of the fulltext search capabilities varies depending on the underlying database being used. For example,
the MySQL & Postgres implementations will typically yield better results than the SQLite implementation.
:::

*Example*

```ts
import { DefaultSearchPlugin, VendureConfig } from '@vendure/core';

export const config: VendureConfig = {
  // Add an instance of the plugin to the plugins array
  plugins: [
    DefaultSearchPlugin.init({
      indexStockStatus: true,
      bufferUpdates: true,
    }),
  ],
};
```

```ts title="Signature"
class DefaultSearchPlugin implements OnApplicationBootstrap, OnApplicationShutdown {
    static options: DefaultSearchPluginInitOptions = {};
    init(options: DefaultSearchPluginInitOptions) => Type<DefaultSearchPlugin>;
}
```
* Implements: <code>OnApplicationBootstrap</code>, <code>OnApplicationShutdown</code>



<div className="members-wrapper">

### options

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/default-search-plugin/default-search-plugin-init-options#defaultsearchplugininitoptions'>DefaultSearchPluginInitOptions</a>`}   />


### init

<MemberInfo kind="method" type={`(options: <a href='/reference/typescript-api/default-search-plugin/default-search-plugin-init-options#defaultsearchplugininitoptions'>DefaultSearchPluginInitOptions</a>) => Type&#60;<a href='/reference/typescript-api/default-search-plugin/#defaultsearchplugin'>DefaultSearchPlugin</a>&#62;`}   />




</div>


---

---
title: "MysqlSearchStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## MysqlSearchStrategy

<GenerationInfo sourceFile="packages/core/src/plugin/default-search-plugin/search-strategy/mysql-search-strategy.ts" sourceLine="28" packageName="@vendure/core" />

A weighted fulltext search for MySQL / MariaDB.

```ts title="Signature"
class MysqlSearchStrategy implements SearchStrategy {
    init(injector: Injector) => ;
    getFacetValueIds(ctx: RequestContext, input: SearchInput, enabledOnly: boolean) => Promise<Map<ID, number>>;
    getCollectionIds(ctx: RequestContext, input: SearchInput, enabledOnly: boolean) => Promise<Map<ID, number>>;
    getSearchResults(ctx: RequestContext, input: SearchInput, enabledOnly: boolean) => Promise<SearchResult[]>;
    getTotalCount(ctx: RequestContext, input: SearchInput, enabledOnly: boolean) => Promise<number>;
}
```
* Implements: <code><a href='/reference/typescript-api/default-search-plugin/search-strategy#searchstrategy'>SearchStrategy</a></code>



<div className="members-wrapper">

### init

<MemberInfo kind="method" type={`(injector: <a href='/reference/typescript-api/common/injector#injector'>Injector</a>) => `}   />


### getFacetValueIds

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: SearchInput, enabledOnly: boolean) => Promise&#60;Map&#60;<a href='/reference/typescript-api/common/id#id'>ID</a>, number&#62;&#62;`}   />


### getCollectionIds

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: SearchInput, enabledOnly: boolean) => Promise&#60;Map&#60;<a href='/reference/typescript-api/common/id#id'>ID</a>, number&#62;&#62;`}   />


### getSearchResults

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: SearchInput, enabledOnly: boolean) => Promise&#60;SearchResult[]&#62;`}   />


### getTotalCount

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: SearchInput, enabledOnly: boolean) => Promise&#60;number&#62;`}   />




</div>


---

---
title: "PostgresSearchStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## PostgresSearchStrategy

<GenerationInfo sourceFile="packages/core/src/plugin/default-search-plugin/search-strategy/postgres-search-strategy.ts" sourceLine="28" packageName="@vendure/core" />

A weighted fulltext search for PostgeSQL.

```ts title="Signature"
class PostgresSearchStrategy implements SearchStrategy {
    init(injector: Injector) => ;
    getFacetValueIds(ctx: RequestContext, input: SearchInput, enabledOnly: boolean) => Promise<Map<ID, number>>;
    getCollectionIds(ctx: RequestContext, input: SearchInput, enabledOnly: boolean) => Promise<Map<ID, number>>;
    getSearchResults(ctx: RequestContext, input: SearchInput, enabledOnly: boolean) => Promise<SearchResult[]>;
    getTotalCount(ctx: RequestContext, input: SearchInput, enabledOnly: boolean) => Promise<number>;
}
```
* Implements: <code><a href='/reference/typescript-api/default-search-plugin/search-strategy#searchstrategy'>SearchStrategy</a></code>



<div className="members-wrapper">

### init

<MemberInfo kind="method" type={`(injector: <a href='/reference/typescript-api/common/injector#injector'>Injector</a>) => `}   />


### getFacetValueIds

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: SearchInput, enabledOnly: boolean) => Promise&#60;Map&#60;<a href='/reference/typescript-api/common/id#id'>ID</a>, number&#62;&#62;`}   />


### getCollectionIds

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: SearchInput, enabledOnly: boolean) => Promise&#60;Map&#60;<a href='/reference/typescript-api/common/id#id'>ID</a>, number&#62;&#62;`}   />


### getSearchResults

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: SearchInput, enabledOnly: boolean) => Promise&#60;SearchResult[]&#62;`}   />


### getTotalCount

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: SearchInput, enabledOnly: boolean) => Promise&#60;number&#62;`}   />




</div>


---

---
title: "SearchStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## SearchStrategy

<GenerationInfo sourceFile="packages/core/src/plugin/default-search-plugin/search-strategy/search-strategy.ts" sourceLine="21" packageName="@vendure/core" />

This interface defines the contract that any database-specific search implementations
should follow.

:::info

This is configured via the `searchStrategy` property of
the <a href='/reference/typescript-api/default-search-plugin/default-search-plugin-init-options#defaultsearchplugininitoptions'>DefaultSearchPluginInitOptions</a>.

:::

```ts title="Signature"
interface SearchStrategy extends InjectableStrategy {
    getSearchResults(ctx: RequestContext, input: SearchInput, enabledOnly: boolean): Promise<SearchResult[]>;
    getTotalCount(ctx: RequestContext, input: SearchInput, enabledOnly: boolean): Promise<number>;
    getFacetValueIds(ctx: RequestContext, input: SearchInput, enabledOnly: boolean): Promise<Map<ID, number>>;
    getCollectionIds(ctx: RequestContext, input: SearchInput, enabledOnly: boolean): Promise<Map<ID, number>>;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### getSearchResults

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: SearchInput, enabledOnly: boolean) => Promise&#60;SearchResult[]&#62;`}   />


### getTotalCount

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: SearchInput, enabledOnly: boolean) => Promise&#60;number&#62;`}   />


### getFacetValueIds

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: SearchInput, enabledOnly: boolean) => Promise&#60;Map&#60;<a href='/reference/typescript-api/common/id#id'>ID</a>, number&#62;&#62;`}   />


### getCollectionIds

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: SearchInput, enabledOnly: boolean) => Promise&#60;Map&#60;<a href='/reference/typescript-api/common/id#id'>ID</a>, number&#62;&#62;`}   />




</div>


---

---
title: "SqliteSearchStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## SqliteSearchStrategy

<GenerationInfo sourceFile="packages/core/src/plugin/default-search-plugin/search-strategy/sqlite-search-strategy.ts" sourceLine="30" packageName="@vendure/core" />

A rather naive search for SQLite / SQL.js. Rather than proper
full-text searching, it uses a weighted `LIKE "%term%"` operator instead.

```ts title="Signature"
class SqliteSearchStrategy implements SearchStrategy {
    init(injector: Injector) => ;
    getFacetValueIds(ctx: RequestContext, input: SearchInput, enabledOnly: boolean) => Promise<Map<ID, number>>;
    getCollectionIds(ctx: RequestContext, input: SearchInput, enabledOnly: boolean) => Promise<Map<ID, number>>;
    getSearchResults(ctx: RequestContext, input: SearchInput, enabledOnly: boolean) => Promise<SearchResult[]>;
    getTotalCount(ctx: RequestContext, input: SearchInput, enabledOnly: boolean) => Promise<number>;
}
```
* Implements: <code><a href='/reference/typescript-api/default-search-plugin/search-strategy#searchstrategy'>SearchStrategy</a></code>



<div className="members-wrapper">

### init

<MemberInfo kind="method" type={`(injector: <a href='/reference/typescript-api/common/injector#injector'>Injector</a>) => `}   />


### getFacetValueIds

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: SearchInput, enabledOnly: boolean) => Promise&#60;Map&#60;<a href='/reference/typescript-api/common/id#id'>ID</a>, number&#62;&#62;`}   />


### getCollectionIds

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: SearchInput, enabledOnly: boolean) => Promise&#60;Map&#60;<a href='/reference/typescript-api/common/id#id'>ID</a>, number&#62;&#62;`}   />


### getSearchResults

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: SearchInput, enabledOnly: boolean) => Promise&#60;SearchResult[]&#62;`}   />


### getTotalCount

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: SearchInput, enabledOnly: boolean) => Promise&#60;number&#62;`}   />




</div>


---

---
title: "Address"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## Address

<GenerationInfo sourceFile="packages/core/src/entity/address/address.entity.ts" sourceLine="16" packageName="@vendure/core" />

Represents a <a href='/reference/typescript-api/entities/customer#customer'>Customer</a>'s address.

```ts title="Signature"
class Address extends VendureEntity implements HasCustomFields {
    constructor(input?: DeepPartial<Address>)
    @Index()
    @ManyToOne(type => Customer, customer => customer.addresses)
    customer: Customer;
    @Column({ default: '' }) fullName: string;
    @Column({ default: '' })
    company: string;
    @Column() streetLine1: string;
    @Column({ default: '' })
    streetLine2: string;
    @Column({ default: '' }) city: string;
    @Column({ default: '' })
    province: string;
    @Column({ default: '' }) postalCode: string;
    @Index()
    @ManyToOne(type => Country)
    country: Country;
    @Column({ default: '' })
    phoneNumber: string;
    @Column({ default: false })
    defaultShippingAddress: boolean;
    @Column({ default: false })
    defaultBillingAddress: boolean;
    @Column(type => CustomAddressFields)
    customFields: CustomAddressFields;
}
```
* Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>


* Implements: <code>HasCustomFields</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input?: DeepPartial&#60;<a href='/reference/typescript-api/entities/address#address'>Address</a>&#62;) => Address`}   />


### customer

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/customer#customer'>Customer</a>`}   />


### fullName

<MemberInfo kind="property" type={`string`}   />


### company

<MemberInfo kind="property" type={`string`}   />


### streetLine1

<MemberInfo kind="property" type={`string`}   />


### streetLine2

<MemberInfo kind="property" type={`string`}   />


### city

<MemberInfo kind="property" type={`string`}   />


### province

<MemberInfo kind="property" type={`string`}   />


### postalCode

<MemberInfo kind="property" type={`string`}   />


### country

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/country#country'>Country</a>`}   />


### phoneNumber

<MemberInfo kind="property" type={`string`}   />


### defaultShippingAddress

<MemberInfo kind="property" type={`boolean`}   />


### defaultBillingAddress

<MemberInfo kind="property" type={`boolean`}   />


### customFields

<MemberInfo kind="property" type={`CustomAddressFields`}   />




</div>


---

---
title: "Administrator"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## Administrator

<GenerationInfo sourceFile="packages/core/src/entity/administrator/administrator.entity.ts" sourceLine="18" packageName="@vendure/core" />

An administrative user who has access to the Admin UI and Admin API. The
specific permissions of the Administrator are determined by the assigned
<a href='/reference/typescript-api/entities/role#role'>Role</a>s.

```ts title="Signature"
class Administrator extends VendureEntity implements SoftDeletable, HasCustomFields {
    constructor(input?: DeepPartial<Administrator>)
    @Column({ type: Date, nullable: true })
    deletedAt: Date | null;
    @Column() firstName: string;
    @Column() lastName: string;
    @Column({ unique: true })
    emailAddress: string;
    @OneToOne(type => User)
    @JoinColumn()
    user: User;
    @Column(type => CustomAdministratorFields)
    customFields: CustomAdministratorFields;
}
```
* Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>


* Implements: <code><a href='/reference/typescript-api/entities/interfaces#softdeletable'>SoftDeletable</a></code>, <code>HasCustomFields</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input?: DeepPartial&#60;<a href='/reference/typescript-api/entities/administrator#administrator'>Administrator</a>&#62;) => Administrator`}   />


### deletedAt

<MemberInfo kind="property" type={`Date | null`}   />


### firstName

<MemberInfo kind="property" type={`string`}   />


### lastName

<MemberInfo kind="property" type={`string`}   />


### emailAddress

<MemberInfo kind="property" type={`string`}   />


### user

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/user#user'>User</a>`}   />


### customFields

<MemberInfo kind="property" type={`CustomAdministratorFields`}   />




</div>


---

---
title: "AnonymousSession"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## AnonymousSession

<GenerationInfo sourceFile="packages/core/src/entity/session/anonymous-session.entity.ts" sourceLine="16" packageName="@vendure/core" />

An anonymous session is created when a unauthenticated user interacts with restricted operations,
such as calling the `activeOrder` query in the Shop API. Anonymous sessions allow a guest Customer
to maintain an order without requiring authentication and a registered account beforehand.

```ts title="Signature"
class AnonymousSession extends Session {
    constructor(input: DeepPartial<AnonymousSession>)
}
```
* Extends: <code><a href='/reference/typescript-api/entities/session#session'>Session</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input: DeepPartial&#60;<a href='/reference/typescript-api/entities/anonymous-session#anonymoussession'>AnonymousSession</a>&#62;) => AnonymousSession`}   />




</div>


---

---
title: "Asset"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## Asset

<GenerationInfo sourceFile="packages/core/src/entity/asset/asset.entity.ts" sourceLine="22" packageName="@vendure/core" />

An Asset represents a file such as an image which can be associated with certain other entities
such as Products.

```ts title="Signature"
class Asset extends VendureEntity implements Taggable, ChannelAware, HasCustomFields {
    constructor(input?: DeepPartial<Asset>)
    @Column() name: string;
    @Column('varchar') type: AssetType;
    @Column() mimeType: string;
    @Column({ default: 0 }) width: number;
    @Column({ default: 0 }) height: number;
    @Column() fileSize: number;
    @Column() source: string;
    @Column() preview: string;
    @Column('simple-json', { nullable: true })
    focalPoint?: { x: number; y: number };
    @ManyToMany(type => Tag)
    @JoinTable()
    tags: Tag[];
    @ManyToMany(type => Channel)
    @JoinTable()
    channels: Channel[];
    @OneToMany(type => Collection, collection => collection.featuredAsset)
    featuredInCollections?: Collection[];
    @OneToMany(type => ProductVariant, productVariant => productVariant.featuredAsset)
    featuredInVariants?: ProductVariant[];
    @OneToMany(type => Product, product => product.featuredAsset)
    featuredInProducts?: Product[];
    @Column(type => CustomAssetFields)
    customFields: CustomAssetFields;
}
```
* Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>


* Implements: <code><a href='/reference/typescript-api/entities/interfaces#taggable'>Taggable</a></code>, <code><a href='/reference/typescript-api/entities/interfaces#channelaware'>ChannelAware</a></code>, <code>HasCustomFields</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input?: DeepPartial&#60;<a href='/reference/typescript-api/entities/asset#asset'>Asset</a>&#62;) => Asset`}   />


### name

<MemberInfo kind="property" type={`string`}   />


### type

<MemberInfo kind="property" type={`AssetType`}   />


### mimeType

<MemberInfo kind="property" type={`string`}   />


### width

<MemberInfo kind="property" type={`number`}   />


### height

<MemberInfo kind="property" type={`number`}   />


### fileSize

<MemberInfo kind="property" type={`number`}   />


### source

<MemberInfo kind="property" type={`string`}   />


### preview

<MemberInfo kind="property" type={`string`}   />


### focalPoint

<MemberInfo kind="property" type={`{ x: number; y: number }`}   />


### tags

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/tag#tag'>Tag</a>[]`}   />


### channels

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/channel#channel'>Channel</a>[]`}   />


### featuredInCollections

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/collection#collection'>Collection</a>[]`}   />


### featuredInVariants

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>[]`}   />


### featuredInProducts

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/product#product'>Product</a>[]`}   />


### customFields

<MemberInfo kind="property" type={`CustomAssetFields`}   />




</div>


---

---
title: "AuthenticatedSession"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## AuthenticatedSession

<GenerationInfo sourceFile="packages/core/src/entity/session/authenticated-session.entity.ts" sourceLine="14" packageName="@vendure/core" />

An AuthenticatedSession is created upon successful authentication.

```ts title="Signature"
class AuthenticatedSession extends Session {
    constructor(input: DeepPartial<AuthenticatedSession>)
    @Index()
    @ManyToOne(type => User, user => user.sessions)
    user: User;
    @Column()
    authenticationStrategy: string;
}
```
* Extends: <code><a href='/reference/typescript-api/entities/session#session'>Session</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input: DeepPartial&#60;<a href='/reference/typescript-api/entities/authenticated-session#authenticatedsession'>AuthenticatedSession</a>&#62;) => AuthenticatedSession`}   />


### user

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/user#user'>User</a>`}   />

The <a href='/reference/typescript-api/entities/user#user'>User</a> who has authenticated to create this session.
### authenticationStrategy

<MemberInfo kind="property" type={`string`}   />

The name of the <a href='/reference/typescript-api/auth/authentication-strategy#authenticationstrategy'>AuthenticationStrategy</a> used when authenticating
to create this session.


</div>


---

---
title: "AuthenticationMethod"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## AuthenticationMethod

<GenerationInfo sourceFile="packages/core/src/entity/authentication-method/authentication-method.entity.ts" sourceLine="14" packageName="@vendure/core" />

An AuthenticationMethod represents the means by which a <a href='/reference/typescript-api/entities/user#user'>User</a> is authenticated. There are two kinds:
<a href='/reference/typescript-api/entities/authentication-method#nativeauthenticationmethod'>NativeAuthenticationMethod</a> and <a href='/reference/typescript-api/entities/authentication-method#externalauthenticationmethod'>ExternalAuthenticationMethod</a>.

```ts title="Signature"
class AuthenticationMethod extends VendureEntity {
    @Index()
    @ManyToOne(type => User, user => user.authenticationMethods)
    user: User;
}
```
* Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>



<div className="members-wrapper">

### user

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/user#user'>User</a>`}   />




</div>


## ExternalAuthenticationMethod

<GenerationInfo sourceFile="packages/core/src/entity/authentication-method/external-authentication-method.entity.ts" sourceLine="14" packageName="@vendure/core" />

This method is used when an external authentication service is used to authenticate Vendure Users.
Examples of external auth include social logins or corporate identity servers.

```ts title="Signature"
class ExternalAuthenticationMethod extends AuthenticationMethod {
    constructor(input: DeepPartial<ExternalAuthenticationMethod>)
    @Column()
    strategy: string;
    @Column()
    externalIdentifier: string;
    @Column('simple-json')
    metadata: any;
}
```
* Extends: <code><a href='/reference/typescript-api/entities/authentication-method#authenticationmethod'>AuthenticationMethod</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input: DeepPartial&#60;<a href='/reference/typescript-api/entities/authentication-method#externalauthenticationmethod'>ExternalAuthenticationMethod</a>&#62;) => ExternalAuthenticationMethod`}   />


### strategy

<MemberInfo kind="property" type={`string`}   />


### externalIdentifier

<MemberInfo kind="property" type={`string`}   />


### metadata

<MemberInfo kind="property" type={`any`}   />




</div>


## NativeAuthenticationMethod

<GenerationInfo sourceFile="packages/core/src/entity/authentication-method/native-authentication-method.entity.ts" sourceLine="14" packageName="@vendure/core" />

This is the default, built-in authentication method which uses a identifier (typically username or email address)
and password combination to authenticate a User.

```ts title="Signature"
class NativeAuthenticationMethod extends AuthenticationMethod {
    constructor(input?: DeepPartial<NativeAuthenticationMethod>)
    @Column()
    identifier: string;
    @Column({ select: false }) passwordHash: string;
    @Column({ type: 'varchar', nullable: true })
    verificationToken: string | null;
    @Column({ type: 'varchar', nullable: true })
    passwordResetToken: string | null;
    @Column({ type: 'varchar', nullable: true })
    identifierChangeToken: string | null;
    @Column({ type: 'varchar', nullable: true })
    pendingIdentifier: string | null;
}
```
* Extends: <code><a href='/reference/typescript-api/entities/authentication-method#authenticationmethod'>AuthenticationMethod</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input?: DeepPartial&#60;<a href='/reference/typescript-api/entities/authentication-method#nativeauthenticationmethod'>NativeAuthenticationMethod</a>&#62;) => NativeAuthenticationMethod`}   />


### identifier

<MemberInfo kind="property" type={`string`}   />


### passwordHash

<MemberInfo kind="property" type={`string`}   />


### verificationToken

<MemberInfo kind="property" type={`string | null`}   />


### passwordResetToken

<MemberInfo kind="property" type={`string | null`}   />


### identifierChangeToken

<MemberInfo kind="property" type={`string | null`}   />

A token issued when a User requests to change their identifier (typically
an email address)
### pendingIdentifier

<MemberInfo kind="property" type={`string | null`}   />

When a request has been made to change the User's identifier, the new identifier
will be stored here until it has been verified, after which it will
replace the current value of the `identifier` field.


</div>


---

---
title: "Channel"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## Channel

<GenerationInfo sourceFile="packages/core/src/entity/channel/channel.entity.ts" sourceLine="37" packageName="@vendure/core" />

A Channel represents a distinct sales channel and configures defaults for that
channel.

* Set a channel-specific currency, language, tax and shipping defaults
* Assign only specific Products to the Channel (with Channel-specific prices)
* Create Administrator roles limited to the Channel
* Assign only specific StockLocations, Assets, Facets, Collections, Promotions, ShippingMethods & PaymentMethods to the Channel
* Have Orders and Customers associated with specific Channels.

In Vendure, Channels have a number of different uses, such as:

* Multi-region stores, where there is a distinct website for each territory with its own available inventory, pricing, tax and shipping rules.
* Creating distinct rules and inventory for different sales channels such as Amazon.
* Specialized stores offering a subset of the main inventory.
* Implementing multi-vendor marketplace applications.

```ts title="Signature"
class Channel extends VendureEntity {
    constructor(input?: DeepPartial<Channel>)
    @Column({ unique: true })
    code: string;
    @Column({ unique: true })
    token: string;
    @Column({ default: '', nullable: true })
    description: string;
    @Index()
    @ManyToOne(type => Seller, seller => seller.channels)
    seller?: Seller;
    @EntityId({ nullable: true })
    sellerId?: ID;
    @Column('varchar') defaultLanguageCode: LanguageCode;
    @Column({ type: 'simple-array', nullable: true })
    availableLanguageCodes: LanguageCode[];
    @Index()
    @ManyToOne(type => Zone, zone => zone.defaultTaxZoneChannels)
    defaultTaxZone: Zone;
    @Index()
    @ManyToOne(type => Zone, zone => zone.defaultShippingZoneChannels)
    defaultShippingZone: Zone;
    @Column('varchar')
    defaultCurrencyCode: CurrencyCode;
    @Column({ type: 'simple-array', nullable: true })
    availableCurrencyCodes: CurrencyCode[];
    @Column({ default: true })
    trackInventory: boolean;
    @Column({ default: 0 })
    outOfStockThreshold: number;
    @Column(type => CustomChannelFields)
    customFields: CustomChannelFields;
    @Column() pricesIncludeTax: boolean;
    @ManyToMany(type => Product, product => product.channels, { onDelete: 'CASCADE' })
    products: Product[];
    @ManyToMany(type => ProductVariant, productVariant => productVariant.channels, { onDelete: 'CASCADE' })
    productVariants: ProductVariant[];
    @ManyToMany(type => FacetValue, facetValue => facetValue.channels, { onDelete: 'CASCADE' })
    facetValues: FacetValue[];
    @ManyToMany(type => Facet, facet => facet.channels, { onDelete: 'CASCADE' })
    facets: Facet[];
    @ManyToMany(type => Collection, collection => collection.channels, { onDelete: 'CASCADE' })
    collections: Collection[];
    @ManyToMany(type => Promotion, promotion => promotion.channels, { onDelete: 'CASCADE' })
    promotions: Promotion[];
    @ManyToMany(type => PaymentMethod, paymentMethod => paymentMethod.channels, { onDelete: 'CASCADE' })
    paymentMethods: PaymentMethod[];
    @ManyToMany(type => ShippingMethod, shippingMethod => shippingMethod.channels, { onDelete: 'CASCADE' })
    shippingMethods: ShippingMethod[];
    @ManyToMany(type => Customer, customer => customer.channels, { onDelete: 'CASCADE' })
    customers: Customer[];
    @ManyToMany(type => Role, role => role.channels, { onDelete: 'CASCADE' })
    roles: Role[];
    @ManyToMany(type => StockLocation, stockLocation => stockLocation.channels, { onDelete: 'CASCADE' })
    stockLocations: StockLocation[];
}
```
* Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input?: DeepPartial&#60;<a href='/reference/typescript-api/entities/channel#channel'>Channel</a>&#62;) => Channel`}   />


### code

<MemberInfo kind="property" type={`string`}   />

The name of the Channel. For example "US Webstore" or "German Webstore".
### token

<MemberInfo kind="property" type={`string`}   />

A unique token (string) used to identify the Channel in the `vendure-token` header of the
GraphQL API requests.
### description

<MemberInfo kind="property" type={`string`}   />


### seller

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/seller#seller'>Seller</a>`}   />


### sellerId

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a>`}   />


### defaultLanguageCode

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a>`}   />


### availableLanguageCodes

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a>[]`}   />


### defaultTaxZone

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/zone#zone'>Zone</a>`}   />


### defaultShippingZone

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/zone#zone'>Zone</a>`}   />


### defaultCurrencyCode

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/currency-code#currencycode'>CurrencyCode</a>`}   />


### availableCurrencyCodes

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/currency-code#currencycode'>CurrencyCode</a>[]`}   />


### trackInventory

<MemberInfo kind="property" type={`boolean`}   />

Specifies the default value for inventory tracking for ProductVariants.
Can be overridden per ProductVariant, but this value determines the default
if not otherwise specified.
### outOfStockThreshold

<MemberInfo kind="property" type={`number`}   />

Specifies the value of stockOnHand at which a given ProductVariant is considered
out of stock.
### customFields

<MemberInfo kind="property" type={`CustomChannelFields`}   />


### pricesIncludeTax

<MemberInfo kind="property" type={`boolean`}   />


### products

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/product#product'>Product</a>[]`}   />


### productVariants

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>[]`}   />


### facetValues

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/facet-value#facetvalue'>FacetValue</a>[]`}   />


### facets

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/facet#facet'>Facet</a>[]`}   />


### collections

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/collection#collection'>Collection</a>[]`}   />


### promotions

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/promotion#promotion'>Promotion</a>[]`}   />


### paymentMethods

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/payment-method#paymentmethod'>PaymentMethod</a>[]`}   />


### shippingMethods

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/shipping-method#shippingmethod'>ShippingMethod</a>[]`}   />


### customers

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/customer#customer'>Customer</a>[]`}   />


### roles

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/role#role'>Role</a>[]`}   />


### stockLocations

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/stock-location#stocklocation'>StockLocation</a>[]`}   />




</div>


---

---
title: "Collection"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## Collection

<GenerationInfo sourceFile="packages/core/src/entity/collection/collection.entity.ts" sourceLine="35" packageName="@vendure/core" />

A Collection is a grouping of <a href='/reference/typescript-api/entities/product#product'>Product</a>s based on various configurable criteria.

```ts title="Signature"
class Collection extends VendureEntity implements Translatable, HasCustomFields, ChannelAware, Orderable {
    constructor(input?: DeepPartial<Collection>)
    @Column({ default: false })
    isRoot: boolean;
    @Column()
    position: number;
    @Column({ default: false })
    isPrivate: boolean;
    name: LocaleString;
    description: LocaleString;
    slug: LocaleString;
    @OneToMany(type => CollectionTranslation, translation => translation.base, { eager: true })
    translations: Array<Translation<Collection>>;
    @Index()
    @ManyToOne(type => Asset, asset => asset.featuredInCollections, { onDelete: 'SET NULL' })
    featuredAsset: Asset;
    @OneToMany(type => CollectionAsset, collectionAsset => collectionAsset.collection)
    assets: CollectionAsset[];
    @Column('simple-json') filters: ConfigurableOperation[];
    @Column({ default: true }) inheritFilters: boolean;
    @ManyToMany(type => ProductVariant, productVariant => productVariant.collections)
    @JoinTable()
    productVariants: ProductVariant[];
    @Column(type => CustomCollectionFields)
    customFields: CustomCollectionFields;
    @TreeChildren()
    children: Collection[];
    @TreeParent()
    parent: Collection;
    @EntityId({ nullable: true })
    parentId: ID;
    @ManyToMany(type => Channel, channel => channel.collections)
    @JoinTable()
    channels: Channel[];
}
```
* Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>


* Implements: <code><a href='/reference/typescript-api/entities/interfaces#translatable'>Translatable</a></code>, <code>HasCustomFields</code>, <code><a href='/reference/typescript-api/entities/interfaces#channelaware'>ChannelAware</a></code>, <code><a href='/reference/typescript-api/entities/interfaces#orderable'>Orderable</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input?: DeepPartial&#60;<a href='/reference/typescript-api/entities/collection#collection'>Collection</a>&#62;) => Collection`}   />


### isRoot

<MemberInfo kind="property" type={`boolean`}   />


### position

<MemberInfo kind="property" type={`number`}   />


### isPrivate

<MemberInfo kind="property" type={`boolean`}   />


### name

<MemberInfo kind="property" type={`LocaleString`}   />


### description

<MemberInfo kind="property" type={`LocaleString`}   />


### slug

<MemberInfo kind="property" type={`LocaleString`}   />


### translations

<MemberInfo kind="property" type={`Array&#60;Translation&#60;<a href='/reference/typescript-api/entities/collection#collection'>Collection</a>&#62;&#62;`}   />


### featuredAsset

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/asset#asset'>Asset</a>`}   />


### assets

<MemberInfo kind="property" type={`CollectionAsset[]`}   />


### filters

<MemberInfo kind="property" type={`ConfigurableOperation[]`}   />


### inheritFilters

<MemberInfo kind="property" type={`boolean`}  since="2.0.0"  />


### productVariants

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>[]`}   />


### customFields

<MemberInfo kind="property" type={`CustomCollectionFields`}   />


### children

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/collection#collection'>Collection</a>[]`}   />


### parent

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/collection#collection'>Collection</a>`}   />


### parentId

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a>`}   />


### channels

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/channel#channel'>Channel</a>[]`}   />




</div>


---

---
title: "Country"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## Country

<GenerationInfo sourceFile="packages/core/src/entity/region/country.entity.ts" sourceLine="14" packageName="@vendure/core" />

A country to which is available when creating / updating an <a href='/reference/typescript-api/entities/address#address'>Address</a>. Countries are
grouped together into <a href='/reference/typescript-api/entities/zone#zone'>Zone</a>s which are in turn used to determine applicable shipping
and taxes for an <a href='/reference/typescript-api/entities/order#order'>Order</a>.

```ts title="Signature"
class Country extends Region {
    constructor(input?: DeepPartial<Country>)
    readonly type: RegionType = 'country';
}
```
* Extends: <code><a href='/reference/typescript-api/entities/region#region'>Region</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input?: DeepPartial&#60;<a href='/reference/typescript-api/entities/country#country'>Country</a>&#62;) => Country`}   />


### type

<MemberInfo kind="property" type={`RegionType`}   />




</div>


---

---
title: "CustomerGroup"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## CustomerGroup

<GenerationInfo sourceFile="packages/core/src/entity/customer-group/customer-group.entity.ts" sourceLine="17" packageName="@vendure/core" />

A grouping of <a href='/reference/typescript-api/entities/customer#customer'>Customer</a>s which enables features such as group-based promotions
or tax rules.

```ts title="Signature"
class CustomerGroup extends VendureEntity implements HasCustomFields {
    constructor(input?: DeepPartial<CustomerGroup>)
    @Column() name: string;
    @ManyToMany(type => Customer, customer => customer.groups)
    customers: Customer[];
    @Column(type => CustomCustomerGroupFields)
    customFields: CustomCustomerGroupFields;
    @OneToMany(type => TaxRate, taxRate => taxRate.zone)
    taxRates: TaxRate[];
}
```
* Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>


* Implements: <code>HasCustomFields</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input?: DeepPartial&#60;<a href='/reference/typescript-api/entities/customer-group#customergroup'>CustomerGroup</a>&#62;) => CustomerGroup`}   />


### name

<MemberInfo kind="property" type={`string`}   />


### customers

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/customer#customer'>Customer</a>[]`}   />


### customFields

<MemberInfo kind="property" type={`CustomCustomerGroupFields`}   />


### taxRates

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/tax-rate#taxrate'>TaxRate</a>[]`}   />




</div>


---

---
title: "CustomerHistoryEntry"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## CustomerHistoryEntry

<GenerationInfo sourceFile="packages/core/src/entity/history-entry/customer-history-entry.entity.ts" sourceLine="14" packageName="@vendure/core" />

Represents an event in the history of a particular <a href='/reference/typescript-api/entities/customer#customer'>Customer</a>.

```ts title="Signature"
class CustomerHistoryEntry extends HistoryEntry {
    constructor(input: DeepPartial<CustomerHistoryEntry>)
    @Index()
    @ManyToOne(type => Customer, { onDelete: 'CASCADE' })
    customer: Customer;
}
```
* Extends: <code><a href='/reference/typescript-api/entities/history-entry#historyentry'>HistoryEntry</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input: DeepPartial&#60;<a href='/reference/typescript-api/entities/customer-history-entry#customerhistoryentry'>CustomerHistoryEntry</a>&#62;) => CustomerHistoryEntry`}   />


### customer

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/customer#customer'>Customer</a>`}   />




</div>


---

---
title: "Customer"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## Customer

<GenerationInfo sourceFile="packages/core/src/entity/customer/customer.entity.ts" sourceLine="22" packageName="@vendure/core" />

This entity represents a customer of the store, typically an individual person. A Customer can be
a guest, in which case it has no associated <a href='/reference/typescript-api/entities/user#user'>User</a>. Customers with registered account will
have an associated User entity.

```ts title="Signature"
class Customer extends VendureEntity implements ChannelAware, HasCustomFields, SoftDeletable {
    constructor(input?: DeepPartial<Customer>)
    @Column({ type: Date, nullable: true })
    deletedAt: Date | null;
    @Column({ nullable: true })
    title: string;
    @Column() firstName: string;
    @Column() lastName: string;
    @Column({ nullable: true })
    phoneNumber: string;
    @Column()
    emailAddress: string;
    @ManyToMany(type => CustomerGroup, group => group.customers)
    @JoinTable()
    groups: CustomerGroup[];
    @OneToMany(type => Address, address => address.customer)
    addresses: Address[];
    @OneToMany(type => Order, order => order.customer)
    orders: Order[];
    @OneToOne(type => User, { eager: true })
    @JoinColumn()
    user?: User;
    @Column(type => CustomCustomerFields)
    customFields: CustomCustomerFields;
    @ManyToMany(type => Channel, channel => channel.customers)
    @JoinTable()
    channels: Channel[];
}
```
* Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>


* Implements: <code><a href='/reference/typescript-api/entities/interfaces#channelaware'>ChannelAware</a></code>, <code>HasCustomFields</code>, <code><a href='/reference/typescript-api/entities/interfaces#softdeletable'>SoftDeletable</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input?: DeepPartial&#60;<a href='/reference/typescript-api/entities/customer#customer'>Customer</a>&#62;) => Customer`}   />


### deletedAt

<MemberInfo kind="property" type={`Date | null`}   />


### title

<MemberInfo kind="property" type={`string`}   />


### firstName

<MemberInfo kind="property" type={`string`}   />


### lastName

<MemberInfo kind="property" type={`string`}   />


### phoneNumber

<MemberInfo kind="property" type={`string`}   />


### emailAddress

<MemberInfo kind="property" type={`string`}   />


### groups

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/customer-group#customergroup'>CustomerGroup</a>[]`}   />


### addresses

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/address#address'>Address</a>[]`}   />


### orders

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/order#order'>Order</a>[]`}   />


### user

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/user#user'>User</a>`}   />


### customFields

<MemberInfo kind="property" type={`CustomCustomerFields`}   />


### channels

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/channel#channel'>Channel</a>[]`}   />




</div>


---

---
title: "FacetValue"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## FacetValue

<GenerationInfo sourceFile="packages/core/src/entity/facet-value/facet-value.entity.ts" sourceLine="23" packageName="@vendure/core" />

A particular value of a <a href='/reference/typescript-api/entities/facet#facet'>Facet</a>.

```ts title="Signature"
class FacetValue extends VendureEntity implements Translatable, HasCustomFields, ChannelAware {
    constructor(input?: DeepPartial<FacetValue>)
    name: LocaleString;
    @Column() code: string;
    @OneToMany(type => FacetValueTranslation, translation => translation.base, { eager: true })
    translations: Array<Translation<FacetValue>>;
    @Index()
    @ManyToOne(type => Facet, group => group.values, { onDelete: 'CASCADE' })
    facet: Facet;
    @EntityId()
    facetId: ID;
    @Column(type => CustomFacetValueFields)
    customFields: CustomFacetValueFields;
    @ManyToMany(type => Channel, channel => channel.facetValues)
    @JoinTable()
    channels: Channel[];
    @ManyToMany(() => Product, product => product.facetValues, { onDelete: 'CASCADE' })
    products: Product[];
    @ManyToMany(type => ProductVariant, productVariant => productVariant.facetValues)
    productVariants: ProductVariant[];
}
```
* Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>


* Implements: <code><a href='/reference/typescript-api/entities/interfaces#translatable'>Translatable</a></code>, <code>HasCustomFields</code>, <code><a href='/reference/typescript-api/entities/interfaces#channelaware'>ChannelAware</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input?: DeepPartial&#60;<a href='/reference/typescript-api/entities/facet-value#facetvalue'>FacetValue</a>&#62;) => FacetValue`}   />


### name

<MemberInfo kind="property" type={`LocaleString`}   />


### code

<MemberInfo kind="property" type={`string`}   />


### translations

<MemberInfo kind="property" type={`Array&#60;Translation&#60;<a href='/reference/typescript-api/entities/facet-value#facetvalue'>FacetValue</a>&#62;&#62;`}   />


### facet

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/facet#facet'>Facet</a>`}   />


### facetId

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a>`}   />


### customFields

<MemberInfo kind="property" type={`CustomFacetValueFields`}   />


### channels

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/channel#channel'>Channel</a>[]`}   />


### products

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/product#product'>Product</a>[]`}   />


### productVariants

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>[]`}   />




</div>


---

---
title: "Facet"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## Facet

<GenerationInfo sourceFile="packages/core/src/entity/facet/facet.entity.ts" sourceLine="25" packageName="@vendure/core" />

A Facet is a class of properties which can be applied to a <a href='/reference/typescript-api/entities/product#product'>Product</a> or <a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>.
They are used to enable [faceted search](https://en.wikipedia.org/wiki/Faceted_search) whereby products
can be filtered along a number of dimensions (facets).

For example, there could be a Facet named "Brand" which has a number of <a href='/reference/typescript-api/entities/facet-value#facetvalue'>FacetValue</a>s representing
the various brands of product, e.g. "Apple", "Samsung", "Dell", "HP" etc.

```ts title="Signature"
class Facet extends VendureEntity implements Translatable, HasCustomFields, ChannelAware {
    constructor(input?: DeepPartial<Facet>)
    name: LocaleString;
    @Column({ default: false })
    isPrivate: boolean;
    @Column({ unique: true })
    code: string;
    @OneToMany(type => FacetTranslation, translation => translation.base, { eager: true })
    translations: Array<Translation<Facet>>;
    @OneToMany(type => FacetValue, value => value.facet)
    values: FacetValue[];
    @Column(type => CustomFacetFields)
    customFields: CustomFacetFields;
    @ManyToMany(type => Channel, channel => channel.facets)
    @JoinTable()
    channels: Channel[];
}
```
* Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>


* Implements: <code><a href='/reference/typescript-api/entities/interfaces#translatable'>Translatable</a></code>, <code>HasCustomFields</code>, <code><a href='/reference/typescript-api/entities/interfaces#channelaware'>ChannelAware</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input?: DeepPartial&#60;<a href='/reference/typescript-api/entities/facet#facet'>Facet</a>&#62;) => Facet`}   />


### name

<MemberInfo kind="property" type={`LocaleString`}   />


### isPrivate

<MemberInfo kind="property" type={`boolean`}   />


### code

<MemberInfo kind="property" type={`string`}   />


### translations

<MemberInfo kind="property" type={`Array&#60;Translation&#60;<a href='/reference/typescript-api/entities/facet#facet'>Facet</a>&#62;&#62;`}   />


### values

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/facet-value#facetvalue'>FacetValue</a>[]`}   />


### customFields

<MemberInfo kind="property" type={`CustomFacetFields`}   />


### channels

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/channel#channel'>Channel</a>[]`}   />




</div>


---

---
title: "Fulfillment"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## Fulfillment

<GenerationInfo sourceFile="packages/core/src/entity/fulfillment/fulfillment.entity.ts" sourceLine="18" packageName="@vendure/core" />

This entity represents a fulfillment of an Order or part of it, i.e. which <a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a>s have been
delivered to the Customer after successful payment.

```ts title="Signature"
class Fulfillment extends VendureEntity implements HasCustomFields {
    constructor(input?: DeepPartial<Fulfillment>)
    @Column('varchar') state: FulfillmentState;
    @Column({ default: '' })
    trackingCode: string;
    @Column()
    method: string;
    @Column()
    handlerCode: string;
    @OneToMany(type => FulfillmentLine, fulfillmentLine => fulfillmentLine.fulfillment)
    lines: FulfillmentLine[];
    @ManyToMany(type => Order, order => order.fulfillments)
    orders: Order[];
    @Column(type => CustomFulfillmentFields)
    customFields: CustomFulfillmentFields;
}
```
* Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>


* Implements: <code>HasCustomFields</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input?: DeepPartial&#60;<a href='/reference/typescript-api/entities/fulfillment#fulfillment'>Fulfillment</a>&#62;) => Fulfillment`}   />


### state

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/fulfillment/fulfillment-state#fulfillmentstate'>FulfillmentState</a>`}   />


### trackingCode

<MemberInfo kind="property" type={`string`}   />


### method

<MemberInfo kind="property" type={`string`}   />


### handlerCode

<MemberInfo kind="property" type={`string`}   />


### lines

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/order-line-reference#fulfillmentline'>FulfillmentLine</a>[]`}   />


### orders

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/order#order'>Order</a>[]`}   />


### customFields

<MemberInfo kind="property" type={`CustomFulfillmentFields`}   />




</div>


---

---
title: "GlobalSettings"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## GlobalSettings

<GenerationInfo sourceFile="packages/core/src/entity/global-settings/global-settings.entity.ts" sourceLine="14" packageName="@vendure/core" />

Stores global settings for the whole application

```ts title="Signature"
class GlobalSettings extends VendureEntity implements HasCustomFields {
    constructor(input?: DeepPartial<GlobalSettings>)
    @Column('simple-array')
    availableLanguages: LanguageCode[];
    @Column({ default: true })
    trackInventory: boolean;
    @Column({ default: 0 })
    outOfStockThreshold: number;
    @Column(type => CustomGlobalSettingsFields)
    customFields: CustomGlobalSettingsFields;
}
```
* Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>


* Implements: <code>HasCustomFields</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input?: DeepPartial&#60;<a href='/reference/typescript-api/entities/global-settings#globalsettings'>GlobalSettings</a>&#62;) => GlobalSettings`}   />


### availableLanguages

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a>[]`}   />


### trackInventory

<MemberInfo kind="property" type={`boolean`}   />

Specifies the default value for inventory tracking for ProductVariants.
Can be overridden per ProductVariant, but this value determines the default
if not otherwise specified.
### outOfStockThreshold

<MemberInfo kind="property" type={`number`}   />

Specifies the value of stockOnHand at which a given ProductVariant is considered
out of stock.
### customFields

<MemberInfo kind="property" type={`CustomGlobalSettingsFields`}   />




</div>


---

---
title: "HistoryEntry"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## HistoryEntry

<GenerationInfo sourceFile="packages/core/src/entity/history-entry/history-entry.entity.ts" sourceLine="16" packageName="@vendure/core" />

An abstract entity representing an entry in the history of an Order (<a href='/reference/typescript-api/entities/order-history-entry#orderhistoryentry'>OrderHistoryEntry</a>)
or a Customer (<a href='/reference/typescript-api/entities/customer-history-entry#customerhistoryentry'>CustomerHistoryEntry</a>).

```ts title="Signature"
class HistoryEntry extends VendureEntity implements HasCustomFields {
    @Index()
    @ManyToOne(type => Administrator)
    administrator?: Administrator;
    @Column({ nullable: false, type: 'varchar' })
    readonly type: HistoryEntryType;
    @Column()
    isPublic: boolean;
    @Column('simple-json')
    data: any;
    @Column(type => CustomHistoryEntryFields)
    customFields: CustomHistoryEntryFields;
}
```
* Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>


* Implements: <code>HasCustomFields</code>



<div className="members-wrapper">

### administrator

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/administrator#administrator'>Administrator</a>`}   />


### type

<MemberInfo kind="property" type={`HistoryEntryType`}   />


### isPublic

<MemberInfo kind="property" type={`boolean`}   />


### data

<MemberInfo kind="property" type={`any`}   />


### customFields

<MemberInfo kind="property" type={`CustomHistoryEntryFields`}   />




</div>


---

---
title: "Entities"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "Interfaces"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ChannelAware

<GenerationInfo sourceFile="packages/core/src/common/types/common-types.ts" sourceLine="17" packageName="@vendure/core" />

Entities which can be assigned to Channels should implement this interface.

```ts title="Signature"
interface ChannelAware {
    channels: Channel[];
}
```

<div className="members-wrapper">

### channels

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/channel#channel'>Channel</a>[]`}   />




</div>


## SoftDeletable

<GenerationInfo sourceFile="packages/core/src/common/types/common-types.ts" sourceLine="28" packageName="@vendure/core" />

Entities which can be soft deleted should implement this interface.

```ts title="Signature"
interface SoftDeletable {
    deletedAt: Date | null;
}
```

<div className="members-wrapper">

### deletedAt

<MemberInfo kind="property" type={`Date | null`}   />




</div>


## Orderable

<GenerationInfo sourceFile="packages/core/src/common/types/common-types.ts" sourceLine="39" packageName="@vendure/core" />

Entities which can be ordered relative to their siblings in a list.

```ts title="Signature"
interface Orderable {
    position: number;
}
```

<div className="members-wrapper">

### position

<MemberInfo kind="property" type={`number`}   />




</div>


## Taggable

<GenerationInfo sourceFile="packages/core/src/common/types/common-types.ts" sourceLine="50" packageName="@vendure/core" />

Entities which can have Tags applied to them.

```ts title="Signature"
interface Taggable {
    tags: Tag[];
}
```

<div className="members-wrapper">

### tags

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/tag#tag'>Tag</a>[]`}   />




</div>


## Translatable

<GenerationInfo sourceFile="packages/core/src/common/types/locale-types.ts" sourceLine="29" packageName="@vendure/core" />

Entities which have localizable string properties should implement this type.

```ts title="Signature"
interface Translatable {
    translations: Array<Translation<VendureEntity>>;
}
```

<div className="members-wrapper">

### translations

<MemberInfo kind="property" type={`Array&#60;Translation&#60;<a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a>&#62;&#62;`}   />




</div>


---

---
title: "OrderHistoryEntry"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## OrderHistoryEntry

<GenerationInfo sourceFile="packages/core/src/entity/history-entry/order-history-entry.entity.ts" sourceLine="14" packageName="@vendure/core" />

Represents an event in the history of a particular <a href='/reference/typescript-api/entities/order#order'>Order</a>.

```ts title="Signature"
class OrderHistoryEntry extends HistoryEntry {
    constructor(input: DeepPartial<OrderHistoryEntry>)
    @Index()
    @ManyToOne(type => Order, { onDelete: 'CASCADE' })
    order: Order;
}
```
* Extends: <code><a href='/reference/typescript-api/entities/history-entry#historyentry'>HistoryEntry</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input: DeepPartial&#60;<a href='/reference/typescript-api/entities/order-history-entry#orderhistoryentry'>OrderHistoryEntry</a>&#62;) => OrderHistoryEntry`}   />


### order

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/order#order'>Order</a>`}   />




</div>


---

---
title: "OrderLineReference"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## FulfillmentLine

<GenerationInfo sourceFile="packages/core/src/entity/order-line-reference/fulfillment-line.entity.ts" sourceLine="16" packageName="@vendure/core" />

This entity represents a line from an <a href='/reference/typescript-api/entities/order#order'>Order</a> which has been fulfilled by a <a href='/reference/typescript-api/entities/fulfillment#fulfillment'>Fulfillment</a>.

```ts title="Signature"
class FulfillmentLine extends OrderLineReference {
    constructor(input?: DeepPartial<FulfillmentLine>)
    @Index()
    @ManyToOne(type => Fulfillment, fulfillment => fulfillment.lines)
    fulfillment: Fulfillment;
    @EntityId()
    fulfillmentId: ID;
}
```
* Extends: <code><a href='/reference/typescript-api/entities/order-line-reference#orderlinereference'>OrderLineReference</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input?: DeepPartial&#60;<a href='/reference/typescript-api/entities/order-line-reference#fulfillmentline'>FulfillmentLine</a>&#62;) => FulfillmentLine`}   />


### fulfillment

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/fulfillment#fulfillment'>Fulfillment</a>`}   />


### fulfillmentId

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a>`}   />




</div>


## OrderLineReference

<GenerationInfo sourceFile="packages/core/src/entity/order-line-reference/order-line-reference.entity.ts" sourceLine="15" packageName="@vendure/core" />

This is an abstract base class for entities which reference an <a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a>.

```ts title="Signature"
class OrderLineReference extends VendureEntity {
    @Column()
    quantity: number;
    @Index()
    @ManyToOne(type => OrderLine, line => line.linesReferences, { onDelete: 'CASCADE' })
    orderLine: OrderLine;
    @EntityId()
    orderLineId: ID;
}
```
* Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>



<div className="members-wrapper">

### quantity

<MemberInfo kind="property" type={`number`}   />


### orderLine

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a>`}   />


### orderLineId

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a>`}   />




</div>


## OrderModificationLine

<GenerationInfo sourceFile="packages/core/src/entity/order-line-reference/order-modification-line.entity.ts" sourceLine="16" packageName="@vendure/core" />

This entity represents a line from an <a href='/reference/typescript-api/entities/order#order'>Order</a> which has been modified by an <a href='/reference/typescript-api/entities/order-modification#ordermodification'>OrderModification</a>.

```ts title="Signature"
class OrderModificationLine extends OrderLineReference {
    constructor(input?: DeepPartial<OrderModificationLine>)
    @Index()
    @ManyToOne(type => OrderModification, modification => modification.lines)
    modification: OrderModification;
    @EntityId()
    modificationId: ID;
}
```
* Extends: <code><a href='/reference/typescript-api/entities/order-line-reference#orderlinereference'>OrderLineReference</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input?: DeepPartial&#60;<a href='/reference/typescript-api/entities/order-line-reference#ordermodificationline'>OrderModificationLine</a>&#62;) => OrderModificationLine`}   />


### modification

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/order-modification#ordermodification'>OrderModification</a>`}   />


### modificationId

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a>`}   />




</div>


## RefundLine

<GenerationInfo sourceFile="packages/core/src/entity/order-line-reference/refund-line.entity.ts" sourceLine="16" packageName="@vendure/core" />

This entity represents a line from an <a href='/reference/typescript-api/entities/order#order'>Order</a> which has been refunded by a <a href='/reference/typescript-api/entities/refund#refund'>Refund</a>.

```ts title="Signature"
class RefundLine extends OrderLineReference {
    constructor(input?: DeepPartial<RefundLine>)
    @Index()
    @ManyToOne(type => Refund, refund => refund.lines)
    refund: Refund;
    @EntityId()
    refundId: ID;
}
```
* Extends: <code><a href='/reference/typescript-api/entities/order-line-reference#orderlinereference'>OrderLineReference</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input?: DeepPartial&#60;<a href='/reference/typescript-api/entities/order-line-reference#refundline'>RefundLine</a>&#62;) => RefundLine`}   />


### refund

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/refund#refund'>Refund</a>`}   />


### refundId

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a>`}   />




</div>


---

---
title: "OrderLine"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## OrderLine

<GenerationInfo sourceFile="packages/core/src/entity/order-line/order-line.entity.ts" sourceLine="32" packageName="@vendure/core" />

A single line on an <a href='/reference/typescript-api/entities/order#order'>Order</a> which contains information about the <a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a> and
quantity ordered, as well as the price and tax information.

```ts title="Signature"
class OrderLine extends VendureEntity implements HasCustomFields {
    constructor(input?: DeepPartial<OrderLine>)
    @Index()
    @ManyToOne(type => Channel, { nullable: true, onDelete: 'SET NULL' })
    sellerChannel?: Channel;
    @EntityId({ nullable: true })
    sellerChannelId?: ID;
    @Index()
    @ManyToOne(type => ShippingLine, shippingLine => shippingLine.orderLines, {
        nullable: true,
        onDelete: 'SET NULL',
    })
    shippingLine?: ShippingLine;
    @EntityId({ nullable: true })
    shippingLineId?: ID;
    @Index()
    @ManyToOne(type => ProductVariant, productVariant => productVariant.lines, { onDelete: 'CASCADE' })
    productVariant: ProductVariant;
    @EntityId()
    productVariantId: ID;
    @Index()
    @ManyToOne(type => TaxCategory)
    taxCategory: TaxCategory;
    @EntityId({ nullable: true })
    taxCategoryId: ID;
    @Index()
    @ManyToOne(type => Asset, asset => asset.featuredInVariants, { onDelete: 'SET NULL' })
    featuredAsset: Asset;
    @Index()
    @ManyToOne(type => Order, order => order.lines, { onDelete: 'CASCADE' })
    order: Order;
    @OneToMany(type => OrderLineReference, lineRef => lineRef.orderLine)
    linesReferences: OrderLineReference[];
    @OneToMany(type => Sale, sale => sale.orderLine)
    sales: Sale[];
    @Column()
    quantity: number;
    @Column({ default: 0 })
    orderPlacedQuantity: number;
    @Money({ nullable: true })
    initialListPrice: number;
    @Money()
    listPrice: number;
    @Column()
    listPriceIncludesTax: boolean;
    @Column('simple-json')
    adjustments: Adjustment[];
    @Column('simple-json')
    taxLines: TaxLine[];
    @OneToMany(type => Cancellation, cancellation => cancellation.orderLine)
    cancellations: Cancellation[];
    @OneToMany(type => Allocation, allocation => allocation.orderLine)
    allocations: Allocation[];
    @Column(type => CustomOrderLineFields)
    customFields: CustomOrderLineFields;
    unitPrice: number
    unitPriceWithTax: number
    unitPriceChangeSinceAdded: number
    unitPriceWithTaxChangeSinceAdded: number
    discountedUnitPrice: number
    discountedUnitPriceWithTax: number
    proratedUnitPrice: number
    proratedUnitPriceWithTax: number
    unitTax: number
    proratedUnitTax: number
    taxRate: number
    linePrice: number
    linePriceWithTax: number
    discountedLinePrice: number
    discountedLinePriceWithTax: number
    discounts: Discount[]
    lineTax: number
    proratedLinePrice: number
    proratedLinePriceWithTax: number
    proratedLineTax: number
    addAdjustment(adjustment: Adjustment) => ;
    clearAdjustments(type?: AdjustmentType) => ;
}
```
* Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>


* Implements: <code>HasCustomFields</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input?: DeepPartial&#60;<a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a>&#62;) => OrderLine`}   />


### sellerChannel

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/channel#channel'>Channel</a>`}   />

The <a href='/reference/typescript-api/entities/channel#channel'>Channel</a> of the <a href='/reference/typescript-api/entities/seller#seller'>Seller</a> for a multivendor setup.
### sellerChannelId

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a>`}   />


### shippingLine

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/shipping-line#shippingline'>ShippingLine</a>`}   />

The <a href='/reference/typescript-api/entities/shipping-line#shippingline'>ShippingLine</a> to which this line has been assigned.
This is determined by the configured <a href='/reference/typescript-api/shipping/shipping-line-assignment-strategy#shippinglineassignmentstrategy'>ShippingLineAssignmentStrategy</a>.
### shippingLineId

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a>`}   />


### productVariant

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>`}   />

The <a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a> which is being ordered.
### productVariantId

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a>`}   />


### taxCategory

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/tax-category#taxcategory'>TaxCategory</a>`}   />


### taxCategoryId

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a>`}   />


### featuredAsset

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/asset#asset'>Asset</a>`}   />


### order

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/order#order'>Order</a>`}   />


### linesReferences

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/order-line-reference#orderlinereference'>OrderLineReference</a>[]`}   />


### sales

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/stock-movement#sale'>Sale</a>[]`}   />


### quantity

<MemberInfo kind="property" type={`number`}   />


### orderPlacedQuantity

<MemberInfo kind="property" type={`number`}   />

The quantity of this OrderLine at the time the order was placed (as per the <a href='/reference/typescript-api/orders/order-placed-strategy#orderplacedstrategy'>OrderPlacedStrategy</a>).
### initialListPrice

<MemberInfo kind="property" type={`number`}   />

The price as calculated when the OrderLine was first added to the Order. Usually will be identical to the
`listPrice`, except when the ProductVariant price has changed in the meantime and a re-calculation of
the Order has been performed.
### listPrice

<MemberInfo kind="property" type={`number`}   />

This is the price as listed by the ProductVariant (and possibly modified by the <a href='/reference/typescript-api/orders/order-item-price-calculation-strategy#orderitempricecalculationstrategy'>OrderItemPriceCalculationStrategy</a>),
which, depending on the current Channel, may or may not include tax.
### listPriceIncludesTax

<MemberInfo kind="property" type={`boolean`}   />

Whether the listPrice includes tax, which depends on the settings of the current Channel.
### adjustments

<MemberInfo kind="property" type={`Adjustment[]`}   />


### taxLines

<MemberInfo kind="property" type={`TaxLine[]`}   />


### cancellations

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/stock-movement#cancellation'>Cancellation</a>[]`}   />


### allocations

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/stock-movement#allocation'>Allocation</a>[]`}   />


### customFields

<MemberInfo kind="property" type={`CustomOrderLineFields`}   />


### unitPrice

<MemberInfo kind="property" type={`number`}   />

The price of a single unit, excluding tax and discounts.
### unitPriceWithTax

<MemberInfo kind="property" type={`number`}   />

The price of a single unit, including tax but excluding discounts.
### unitPriceChangeSinceAdded

<MemberInfo kind="property" type={`number`}   />

Non-zero if the `unitPrice` has changed since it was initially added to Order.
### unitPriceWithTaxChangeSinceAdded

<MemberInfo kind="property" type={`number`}   />

Non-zero if the `unitPriceWithTax` has changed since it was initially added to Order.
### discountedUnitPrice

<MemberInfo kind="property" type={`number`}   />

The price of a single unit including discounts, excluding tax.

If Order-level discounts have been applied, this will not be the
actual taxable unit price (see `proratedUnitPrice`), but is generally the
correct price to display to customers to avoid confusion
about the internal handling of distributed Order-level discounts.
### discountedUnitPriceWithTax

<MemberInfo kind="property" type={`number`}   />

The price of a single unit including discounts and tax
### proratedUnitPrice

<MemberInfo kind="property" type={`number`}   />

The actual unit price, taking into account both item discounts _and_ prorated (proportionally-distributed)
Order-level discounts. This value is the true economic value of a single unit in this OrderLine, and is used in tax
and refund calculations.
### proratedUnitPriceWithTax

<MemberInfo kind="property" type={`number`}   />

The `proratedUnitPrice` including tax.
### unitTax

<MemberInfo kind="property" type={`number`}   />


### proratedUnitTax

<MemberInfo kind="property" type={`number`}   />


### taxRate

<MemberInfo kind="property" type={`number`}   />


### linePrice

<MemberInfo kind="property" type={`number`}   />

The total price of the line excluding tax and discounts.
### linePriceWithTax

<MemberInfo kind="property" type={`number`}   />

The total price of the line including tax but excluding discounts.
### discountedLinePrice

<MemberInfo kind="property" type={`number`}   />

The price of the line including discounts, excluding tax.
### discountedLinePriceWithTax

<MemberInfo kind="property" type={`number`}   />

The price of the line including discounts and tax.
### discounts

<MemberInfo kind="property" type={`Discount[]`}   />


### lineTax

<MemberInfo kind="property" type={`number`}   />

The total tax on this line.
### proratedLinePrice

<MemberInfo kind="property" type={`number`}   />

The actual line price, taking into account both item discounts _and_ prorated (proportionally-distributed)
Order-level discounts. This value is the true economic value of the OrderLine, and is used in tax
and refund calculations.
### proratedLinePriceWithTax

<MemberInfo kind="property" type={`number`}   />

The `proratedLinePrice` including tax.
### proratedLineTax

<MemberInfo kind="property" type={`number`}   />


### addAdjustment

<MemberInfo kind="method" type={`(adjustment: Adjustment) => `}   />


### clearAdjustments

<MemberInfo kind="method" type={`(type?: AdjustmentType) => `}   />




</div>


---

---
title: "OrderModification"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## OrderModification

<GenerationInfo sourceFile="packages/core/src/entity/order-modification/order-modification.entity.ts" sourceLine="21" packageName="@vendure/core" />

An entity which represents a modification to an order which has been placed, and
then modified afterwards by an administrator.

```ts title="Signature"
class OrderModification extends VendureEntity {
    constructor(input?: DeepPartial<OrderModification>)
    @Column()
    note: string;
    @Index()
    @ManyToOne(type => Order, order => order.modifications, { onDelete: 'CASCADE' })
    order: Order;
    @OneToMany(type => OrderModificationLine, line => line.modification)
    lines: OrderModificationLine[];
    @OneToMany(type => Surcharge, surcharge => surcharge.orderModification)
    surcharges: Surcharge[];
    @Money()
    priceChange: number;
    @ManyToOne(type => Payment)
    @JoinColumn()
    payment?: Payment;
    @ManyToOne(type => Refund)
    @JoinColumn()
    refund?: Refund;
    @Column('simple-json', { nullable: true }) shippingAddressChange: OrderAddress;
    @Column('simple-json', { nullable: true }) billingAddressChange: OrderAddress;
    isSettled: boolean
}
```
* Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input?: DeepPartial&#60;<a href='/reference/typescript-api/entities/order-modification#ordermodification'>OrderModification</a>&#62;) => OrderModification`}   />


### note

<MemberInfo kind="property" type={`string`}   />


### order

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/order#order'>Order</a>`}   />


### lines

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/order-line-reference#ordermodificationline'>OrderModificationLine</a>[]`}   />


### surcharges

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/surcharge#surcharge'>Surcharge</a>[]`}   />


### priceChange

<MemberInfo kind="property" type={`number`}   />


### payment

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/payment#payment'>Payment</a>`}   />


### refund

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/refund#refund'>Refund</a>`}   />


### shippingAddressChange

<MemberInfo kind="property" type={`OrderAddress`}   />


### billingAddressChange

<MemberInfo kind="property" type={`OrderAddress`}   />


### isSettled

<MemberInfo kind="property" type={`boolean`}   />




</div>


---

---
title: "Order"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## Order

<GenerationInfo sourceFile="packages/core/src/entity/order/order.entity.ts" sourceLine="43" packageName="@vendure/core" />

An Order is created whenever a <a href='/reference/typescript-api/entities/customer#customer'>Customer</a> adds an item to the cart. It contains all the
information required to fulfill an order: which <a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>s in what quantities;
the shipping address and price; any applicable promotions; payments etc.

An Order exists in a well-defined state according to the <a href='/reference/typescript-api/orders/order-process#orderstate'>OrderState</a> type. A state machine
is used to govern the transition from one state to another.

```ts title="Signature"
class Order extends VendureEntity implements ChannelAware, HasCustomFields {
    constructor(input?: DeepPartial<Order>)
    @Column('varchar', { default: OrderType.Regular })
    type: OrderType;
    @OneToMany(type => Order, sellerOrder => sellerOrder.aggregateOrder)
    sellerOrders: Order[];
    @Index()
    @ManyToOne(type => Order, aggregateOrder => aggregateOrder.sellerOrders)
    aggregateOrder?: Order;
    @EntityId({ nullable: true })
    aggregateOrderId?: ID;
    @Column()
    @Index({ unique: true })
    code: string;
    @Column('varchar') state: OrderState;
    @Column({ default: true })
    active: boolean;
    @Column({ nullable: true })
    @Index()
    orderPlacedAt?: Date;
    @Index()
    @ManyToOne(type => Customer, customer => customer.orders)
    customer?: Customer;
    @EntityId({ nullable: true })
    customerId?: ID;
    @OneToMany(type => OrderLine, line => line.order)
    lines: OrderLine[];
    @OneToMany(type => Surcharge, surcharge => surcharge.order)
    surcharges: Surcharge[];
    @Column('simple-array')
    couponCodes: string[];
    @ManyToMany(type => Promotion, promotion => promotion.orders)
    @JoinTable()
    promotions: Promotion[];
    @Column('simple-json') shippingAddress: OrderAddress;
    @Column('simple-json') billingAddress: OrderAddress;
    @OneToMany(type => Payment, payment => payment.order)
    payments: Payment[];
    @ManyToMany(type => Fulfillment, fulfillment => fulfillment.orders)
    @JoinTable()
    fulfillments: Fulfillment[];
    @Column('varchar')
    currencyCode: CurrencyCode;
    @Column(type => CustomOrderFields)
    customFields: CustomOrderFields;
    @EntityId({ nullable: true })
    taxZoneId?: ID;
    @ManyToMany(type => Channel)
    @JoinTable()
    channels: Channel[];
    @OneToMany(type => OrderModification, modification => modification.order)
    modifications: OrderModification[];
    @Money()
    subTotal: number;
    @Money()
    subTotalWithTax: number;
    @OneToMany(type => ShippingLine, shippingLine => shippingLine.order)
    shippingLines: ShippingLine[];
    @Money({ default: 0 })
    shipping: number;
    @Money({ default: 0 })
    shippingWithTax: number;
    discounts: Discount[]
    total: number
    totalWithTax: number
    totalQuantity: number
    taxSummary: OrderTaxSummary[]
}
```
* Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>


* Implements: <code><a href='/reference/typescript-api/entities/interfaces#channelaware'>ChannelAware</a></code>, <code>HasCustomFields</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input?: DeepPartial&#60;<a href='/reference/typescript-api/entities/order#order'>Order</a>&#62;) => Order`}   />


### type

<MemberInfo kind="property" type={`OrderType`}   />


### sellerOrders

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/order#order'>Order</a>[]`}   />


### aggregateOrder

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/order#order'>Order</a>`}   />


### aggregateOrderId

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a>`}   />


### code

<MemberInfo kind="property" type={`string`}   />

A unique code for the Order, generated according to the
<a href='/reference/typescript-api/orders/order-code-strategy#ordercodestrategy'>OrderCodeStrategy</a>. This should be used as an order reference
for Customers, rather than the Order's id.
### state

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/orders/order-process#orderstate'>OrderState</a>`}   />


### active

<MemberInfo kind="property" type={`boolean`}   />

Whether the Order is considered "active", meaning that the
Customer can still make changes to it and has not yet completed
the checkout process.
This is governed by the <a href='/reference/typescript-api/orders/order-placed-strategy#orderplacedstrategy'>OrderPlacedStrategy</a>.
### orderPlacedAt

<MemberInfo kind="property" type={`Date`}   />

The date & time that the Order was placed, i.e. the Customer
completed the checkout and the Order is no longer "active".
This is governed by the <a href='/reference/typescript-api/orders/order-placed-strategy#orderplacedstrategy'>OrderPlacedStrategy</a>.
### customer

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/customer#customer'>Customer</a>`}   />


### customerId

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a>`}   />


### lines

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a>[]`}   />


### surcharges

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/surcharge#surcharge'>Surcharge</a>[]`}   />

Surcharges are arbitrary modifications to the Order total which are neither
ProductVariants nor discounts resulting from applied Promotions. For example,
one-off discounts based on customer interaction, or surcharges based on payment
methods.
### couponCodes

<MemberInfo kind="property" type={`string[]`}   />

An array of all coupon codes applied to the Order.
### promotions

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/promotion#promotion'>Promotion</a>[]`}   />

Promotions applied to the order. Only gets populated after the payment process has completed,
i.e. the Order is no longer active.
### shippingAddress

<MemberInfo kind="property" type={`OrderAddress`}   />


### billingAddress

<MemberInfo kind="property" type={`OrderAddress`}   />


### payments

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/payment#payment'>Payment</a>[]`}   />


### fulfillments

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/fulfillment#fulfillment'>Fulfillment</a>[]`}   />


### currencyCode

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/currency-code#currencycode'>CurrencyCode</a>`}   />


### customFields

<MemberInfo kind="property" type={`CustomOrderFields`}   />


### taxZoneId

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a>`}   />


### channels

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/channel#channel'>Channel</a>[]`}   />


### modifications

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/order-modification#ordermodification'>OrderModification</a>[]`}   />


### subTotal

<MemberInfo kind="property" type={`number`}   />

The subTotal is the total of all OrderLines in the Order. This figure also includes any Order-level
discounts which have been prorated (proportionally distributed) amongst the OrderItems.
To get a total of all OrderLines which does not account for prorated discounts, use the
sum of <a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a>'s `discountedLinePrice` values.
### subTotalWithTax

<MemberInfo kind="property" type={`number`}   />

Same as subTotal, but inclusive of tax.
### shippingLines

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/shipping-line#shippingline'>ShippingLine</a>[]`}   />

The shipping charges applied to this order.
### shipping

<MemberInfo kind="property" type={`number`}   />

The total of all the `shippingLines`.
### shippingWithTax

<MemberInfo kind="property" type={`number`}   />


### discounts

<MemberInfo kind="property" type={`Discount[]`}   />


### total

<MemberInfo kind="property" type={`number`}   />

Equal to `subTotal` plus `shipping`
### totalWithTax

<MemberInfo kind="property" type={`number`}   />

The final payable amount. Equal to `subTotalWithTax` plus `shippingWithTax`.
### totalQuantity

<MemberInfo kind="property" type={`number`}   />


### taxSummary

<MemberInfo kind="property" type={`OrderTaxSummary[]`}   />

A summary of the taxes being applied to this Order.


</div>


---

---
title: "OrderableAsset"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## OrderableAsset

<GenerationInfo sourceFile="packages/core/src/entity/asset/orderable-asset.entity.ts" sourceLine="18" packageName="@vendure/core" />

This base class is extended in order to enable specific ordering of the one-to-many
Entity -> Assets relation. Using a many-to-many relation does not provide a way
to guarantee order of the Assets, so this entity is used in place of the
usual join table that would be created by TypeORM.
See https://typeorm.io/#/many-to-many-relations/many-to-many-relations-with-custom-properties

```ts title="Signature"
class OrderableAsset extends VendureEntity implements Orderable {
    constructor(input?: DeepPartial<OrderableAsset>)
    @Column()
    assetId: ID;
    @Index()
    @ManyToOne(type => Asset, { eager: true, onDelete: 'CASCADE' })
    asset: Asset;
    @Column()
    position: number;
}
```
* Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>


* Implements: <code><a href='/reference/typescript-api/entities/interfaces#orderable'>Orderable</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input?: DeepPartial&#60;<a href='/reference/typescript-api/entities/orderable-asset#orderableasset'>OrderableAsset</a>&#62;) => OrderableAsset`}   />


### assetId

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a>`}   />


### asset

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/asset#asset'>Asset</a>`}   />


### position

<MemberInfo kind="property" type={`number`}   />




</div>


---

---
title: "PaymentMethod"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## PaymentMethod

<GenerationInfo sourceFile="packages/core/src/entity/payment-method/payment-method.entity.ts" sourceLine="21" packageName="@vendure/core" />

A PaymentMethod is created automatically according to the configured <a href='/reference/typescript-api/payment/payment-method-handler#paymentmethodhandler'>PaymentMethodHandler</a>s defined
in the <a href='/reference/typescript-api/payment/payment-options#paymentoptions'>PaymentOptions</a> config.

```ts title="Signature"
class PaymentMethod extends VendureEntity implements Translatable, ChannelAware, HasCustomFields {
    constructor(input?: DeepPartial<PaymentMethod>)
    name: LocaleString;
    @Column({ default: '' }) code: string;
    description: LocaleString;
    @OneToMany(type => PaymentMethodTranslation, translation => translation.base, { eager: true })
    translations: Array<Translation<PaymentMethod>>;
    @Column() enabled: boolean;
    @Column('simple-json', { nullable: true }) checker: ConfigurableOperation | null;
    @Column('simple-json') handler: ConfigurableOperation;
    @ManyToMany(type => Channel, channel => channel.paymentMethods)
    @JoinTable()
    channels: Channel[];
    @Column(type => CustomPaymentMethodFields)
    customFields: CustomPaymentMethodFields;
}
```
* Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>


* Implements: <code><a href='/reference/typescript-api/entities/interfaces#translatable'>Translatable</a></code>, <code><a href='/reference/typescript-api/entities/interfaces#channelaware'>ChannelAware</a></code>, <code>HasCustomFields</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input?: DeepPartial&#60;<a href='/reference/typescript-api/entities/payment-method#paymentmethod'>PaymentMethod</a>&#62;) => PaymentMethod`}   />


### name

<MemberInfo kind="property" type={`LocaleString`}   />


### code

<MemberInfo kind="property" type={`string`}   />


### description

<MemberInfo kind="property" type={`LocaleString`}   />


### translations

<MemberInfo kind="property" type={`Array&#60;Translation&#60;<a href='/reference/typescript-api/entities/payment-method#paymentmethod'>PaymentMethod</a>&#62;&#62;`}   />


### enabled

<MemberInfo kind="property" type={`boolean`}   />


### checker

<MemberInfo kind="property" type={`ConfigurableOperation | null`}   />


### handler

<MemberInfo kind="property" type={`ConfigurableOperation`}   />


### channels

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/channel#channel'>Channel</a>[]`}   />


### customFields

<MemberInfo kind="property" type={`CustomPaymentMethodFields`}   />




</div>


---

---
title: "Payment"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## Payment

<GenerationInfo sourceFile="packages/core/src/entity/payment/payment.entity.ts" sourceLine="20" packageName="@vendure/core" />

A Payment represents a single payment transaction and exists in a well-defined state
defined by the <a href='/reference/typescript-api/payment/payment-state#paymentstate'>PaymentState</a> type.

```ts title="Signature"
class Payment extends VendureEntity implements HasCustomFields {
    constructor(input?: DeepPartial<Payment>)
    @Column() method: string;
    @Money() amount: number;
    @Column('varchar') state: PaymentState;
    @Column({ type: 'varchar', nullable: true })
    errorMessage: string | undefined;
    @Column({ nullable: true })
    transactionId: string;
    @Column('simple-json') metadata: PaymentMetadata;
    @Index()
    @ManyToOne(type => Order, order => order.payments)
    order: Order;
    @OneToMany(type => Refund, refund => refund.payment)
    refunds: Refund[];
    @Column(type => CustomPaymentFields)
    customFields: CustomPaymentFields;
}
```
* Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>


* Implements: <code>HasCustomFields</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input?: DeepPartial&#60;<a href='/reference/typescript-api/entities/payment#payment'>Payment</a>&#62;) => Payment`}   />


### method

<MemberInfo kind="property" type={`string`}   />


### amount

<MemberInfo kind="property" type={`number`}   />


### state

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/payment/payment-state#paymentstate'>PaymentState</a>`}   />


### errorMessage

<MemberInfo kind="property" type={`string | undefined`}   />


### transactionId

<MemberInfo kind="property" type={`string`}   />


### metadata

<MemberInfo kind="property" type={`PaymentMetadata`}   />


### order

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/order#order'>Order</a>`}   />


### refunds

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/refund#refund'>Refund</a>[]`}   />


### customFields

<MemberInfo kind="property" type={`CustomPaymentFields`}   />




</div>


---

---
title: "ProductOptionGroup"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ProductOptionGroup

<GenerationInfo sourceFile="packages/core/src/entity/product-option-group/product-option-group.entity.ts" sourceLine="20" packageName="@vendure/core" />

A grouping of one or more <a href='/reference/typescript-api/entities/product-option#productoption'>ProductOption</a>s.

```ts title="Signature"
class ProductOptionGroup extends VendureEntity implements Translatable, HasCustomFields, SoftDeletable {
    constructor(input?: DeepPartial<ProductOptionGroup>)
    @Column({ type: Date, nullable: true })
    deletedAt: Date | null;
    name: LocaleString;
    @Column()
    code: string;
    @OneToMany(type => ProductOptionGroupTranslation, translation => translation.base, { eager: true })
    translations: Array<Translation<ProductOptionGroup>>;
    @OneToMany(type => ProductOption, option => option.group)
    options: ProductOption[];
    @Index()
    @ManyToOne(type => Product, product => product.optionGroups)
    product: Product;
    @Column(type => CustomProductOptionGroupFields)
    customFields: CustomProductOptionGroupFields;
}
```
* Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>


* Implements: <code><a href='/reference/typescript-api/entities/interfaces#translatable'>Translatable</a></code>, <code>HasCustomFields</code>, <code><a href='/reference/typescript-api/entities/interfaces#softdeletable'>SoftDeletable</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input?: DeepPartial&#60;<a href='/reference/typescript-api/entities/product-option-group#productoptiongroup'>ProductOptionGroup</a>&#62;) => ProductOptionGroup`}   />


### deletedAt

<MemberInfo kind="property" type={`Date | null`}   />


### name

<MemberInfo kind="property" type={`LocaleString`}   />


### code

<MemberInfo kind="property" type={`string`}   />


### translations

<MemberInfo kind="property" type={`Array&#60;Translation&#60;<a href='/reference/typescript-api/entities/product-option-group#productoptiongroup'>ProductOptionGroup</a>&#62;&#62;`}   />


### options

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/product-option#productoption'>ProductOption</a>[]`}   />


### product

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/product#product'>Product</a>`}   />


### customFields

<MemberInfo kind="property" type={`CustomProductOptionGroupFields`}   />




</div>


---

---
title: "ProductOption"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ProductOption

<GenerationInfo sourceFile="packages/core/src/entity/product-option/product-option.entity.ts" sourceLine="21" packageName="@vendure/core" />

A ProductOption is used to differentiate <a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>s from one another.

```ts title="Signature"
class ProductOption extends VendureEntity implements Translatable, HasCustomFields, SoftDeletable {
    constructor(input?: DeepPartial<ProductOption>)
    @Column({ type: Date, nullable: true })
    deletedAt: Date | null;
    name: LocaleString;
    @Column() code: string;
    @OneToMany(type => ProductOptionTranslation, translation => translation.base, { eager: true })
    translations: Array<Translation<ProductOption>>;
    @Index()
    @ManyToOne(type => ProductOptionGroup, group => group.options)
    group: ProductOptionGroup;
    @EntityId()
    groupId: ID;
    @ManyToMany(type => ProductVariant, variant => variant.options)
    productVariants: ProductVariant[];
    @Column(type => CustomProductOptionFields)
    customFields: CustomProductOptionFields;
}
```
* Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>


* Implements: <code><a href='/reference/typescript-api/entities/interfaces#translatable'>Translatable</a></code>, <code>HasCustomFields</code>, <code><a href='/reference/typescript-api/entities/interfaces#softdeletable'>SoftDeletable</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input?: DeepPartial&#60;<a href='/reference/typescript-api/entities/product-option#productoption'>ProductOption</a>&#62;) => ProductOption`}   />


### deletedAt

<MemberInfo kind="property" type={`Date | null`}   />


### name

<MemberInfo kind="property" type={`LocaleString`}   />


### code

<MemberInfo kind="property" type={`string`}   />


### translations

<MemberInfo kind="property" type={`Array&#60;Translation&#60;<a href='/reference/typescript-api/entities/product-option#productoption'>ProductOption</a>&#62;&#62;`}   />


### group

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/product-option-group#productoptiongroup'>ProductOptionGroup</a>`}   />


### groupId

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a>`}   />


### productVariants

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>[]`}   />


### customFields

<MemberInfo kind="property" type={`CustomProductOptionFields`}   />




</div>


---

---
title: "ProductVariantPrice"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ProductVariantPrice

<GenerationInfo sourceFile="packages/core/src/entity/product-variant/product-variant-price.entity.ts" sourceLine="20" packageName="@vendure/core" />

A ProductVariantPrice is a Channel-specific price for a ProductVariant. For every Channel to
which a ProductVariant is assigned, there will be a corresponding ProductVariantPrice entity.

```ts title="Signature"
class ProductVariantPrice extends VendureEntity implements HasCustomFields {
    constructor(input?: DeepPartial<ProductVariantPrice>)
    @Money() price: number;
    @EntityId({ nullable: true }) channelId: ID;
    @Column('varchar')
    currencyCode: CurrencyCode;
    @Index()
    @ManyToOne(type => ProductVariant, variant => variant.productVariantPrices, { onDelete: 'CASCADE' })
    variant: ProductVariant;
    @Column(type => CustomProductVariantPriceFields)
    customFields: CustomProductVariantPriceFields;
}
```
* Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>


* Implements: <code>HasCustomFields</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input?: DeepPartial&#60;<a href='/reference/typescript-api/entities/product-variant-price#productvariantprice'>ProductVariantPrice</a>&#62;) => ProductVariantPrice`}   />


### price

<MemberInfo kind="property" type={`number`}   />


### channelId

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a>`}   />


### currencyCode

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/currency-code#currencycode'>CurrencyCode</a>`}   />


### variant

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>`}   />


### customFields

<MemberInfo kind="property" type={`CustomProductVariantPriceFields`}   />




</div>


---

---
title: "ProductVariant"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ProductVariant

<GenerationInfo sourceFile="packages/core/src/entity/product-variant/product-variant.entity.ts" sourceLine="38" packageName="@vendure/core" />

A ProductVariant represents a single stock keeping unit (SKU) in the store's inventory.
Whereas a <a href='/reference/typescript-api/entities/product#product'>Product</a> is a "container" of variants, the variant itself holds the
data on price, tax category etc. When one adds items to their cart, they are adding
ProductVariants, not Products.

```ts title="Signature"
class ProductVariant extends VendureEntity implements Translatable, HasCustomFields, SoftDeletable, ChannelAware {
    constructor(input?: DeepPartial<ProductVariant>)
    @Column({ type: Date, nullable: true })
    deletedAt: Date | null;
    name: LocaleString;
    @Column({ default: true })
    enabled: boolean;
    @Column()
    sku: string;
    listPrice: number;
    listPriceIncludesTax: boolean;
    currencyCode: CurrencyCode;
    price: number
    priceWithTax: number
    taxRateApplied: TaxRate;
    @Index()
    @ManyToOne(type => Asset, asset => asset.featuredInVariants, { onDelete: 'SET NULL' })
    featuredAsset: Asset;
    @EntityId({ nullable: true })
    featuredAssetId: ID;
    @OneToMany(type => ProductVariantAsset, productVariantAsset => productVariantAsset.productVariant, {
        onDelete: 'SET NULL',
    })
    assets: ProductVariantAsset[];
    @Index()
    @ManyToOne(type => TaxCategory, taxCategory => taxCategory.productVariants)
    taxCategory: TaxCategory;
    @EntityId({ nullable: true })
    taxCategoryId: ID;
    @OneToMany(type => ProductVariantPrice, price => price.variant, { eager: true })
    productVariantPrices: ProductVariantPrice[];
    @OneToMany(type => ProductVariantTranslation, translation => translation.base, { eager: true })
    translations: Array<Translation<ProductVariant>>;
    @Index()
    @ManyToOne(type => Product, product => product.variants)
    product: Product;
    @EntityId({ nullable: true })
    productId: ID;
    @Column({ default: 0 })
    outOfStockThreshold: number;
    @Column({ default: true })
    useGlobalOutOfStockThreshold: boolean;
    @Column({ type: 'varchar', default: GlobalFlag.INHERIT })
    trackInventory: GlobalFlag;
    @OneToMany(type => StockLevel, stockLevel => stockLevel.productVariant)
    stockLevels: StockLevel[];
    @OneToMany(type => StockMovement, stockMovement => stockMovement.productVariant)
    stockMovements: StockMovement[];
    @ManyToMany(type => ProductOption, productOption => productOption.productVariants)
    @JoinTable()
    options: ProductOption[];
    @ManyToMany(type => FacetValue, facetValue => facetValue.productVariants)
    @JoinTable()
    facetValues: FacetValue[];
    @Column(type => CustomProductVariantFields)
    customFields: CustomProductVariantFields;
    @ManyToMany(type => Collection, collection => collection.productVariants)
    collections: Collection[];
    @ManyToMany(type => Channel, channel => channel.productVariants)
    @JoinTable()
    channels: Channel[];
    @OneToMany(type => OrderLine, orderLine => orderLine.productVariant)
    lines: OrderLine[];
}
```
* Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>


* Implements: <code><a href='/reference/typescript-api/entities/interfaces#translatable'>Translatable</a></code>, <code>HasCustomFields</code>, <code><a href='/reference/typescript-api/entities/interfaces#softdeletable'>SoftDeletable</a></code>, <code><a href='/reference/typescript-api/entities/interfaces#channelaware'>ChannelAware</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input?: DeepPartial&#60;<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>&#62;) => ProductVariant`}   />


### deletedAt

<MemberInfo kind="property" type={`Date | null`}   />


### name

<MemberInfo kind="property" type={`LocaleString`}   />


### enabled

<MemberInfo kind="property" type={`boolean`}   />


### sku

<MemberInfo kind="property" type={`string`}   />


### listPrice

<MemberInfo kind="property" type={`number`}   />


### listPriceIncludesTax

<MemberInfo kind="property" type={`boolean`}   />


### currencyCode

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/currency-code#currencycode'>CurrencyCode</a>`}   />


### price

<MemberInfo kind="property" type={`number`}   />


### priceWithTax

<MemberInfo kind="property" type={`number`}   />


### taxRateApplied

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/tax-rate#taxrate'>TaxRate</a>`}   />


### featuredAsset

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/asset#asset'>Asset</a>`}   />


### featuredAssetId

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a>`}   />


### assets

<MemberInfo kind="property" type={`ProductVariantAsset[]`}   />


### taxCategory

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/tax-category#taxcategory'>TaxCategory</a>`}   />


### taxCategoryId

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a>`}   />


### productVariantPrices

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/product-variant-price#productvariantprice'>ProductVariantPrice</a>[]`}   />


### translations

<MemberInfo kind="property" type={`Array&#60;Translation&#60;<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>&#62;&#62;`}   />


### product

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/product#product'>Product</a>`}   />


### productId

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a>`}   />


### outOfStockThreshold

<MemberInfo kind="property" type={`number`}   />

Specifies the value of stockOnHand at which the ProductVariant is considered
out of stock.
### useGlobalOutOfStockThreshold

<MemberInfo kind="property" type={`boolean`}   />

When true, the `outOfStockThreshold` value will be taken from the GlobalSettings and the
value set on this ProductVariant will be ignored.
### trackInventory

<MemberInfo kind="property" type={`GlobalFlag`}   />


### stockLevels

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/stock-level#stocklevel'>StockLevel</a>[]`}   />


### stockMovements

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/stock-movement#stockmovement'>StockMovement</a>[]`}   />


### options

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/product-option#productoption'>ProductOption</a>[]`}   />


### facetValues

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/facet-value#facetvalue'>FacetValue</a>[]`}   />


### customFields

<MemberInfo kind="property" type={`CustomProductVariantFields`}   />


### collections

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/collection#collection'>Collection</a>[]`}   />


### channels

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/channel#channel'>Channel</a>[]`}   />


### lines

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a>[]`}   />




</div>


---

---
title: "Product"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## Product

<GenerationInfo sourceFile="packages/core/src/entity/product/product.entity.ts" sourceLine="26" packageName="@vendure/core" />

A Product contains one or more <a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>s and serves as a container for those variants,
providing an overall name, description etc.

```ts title="Signature"
class Product extends VendureEntity implements Translatable, HasCustomFields, ChannelAware, SoftDeletable {
    constructor(input?: DeepPartial<Product>)
    @Column({ type: Date, nullable: true })
    deletedAt: Date | null;
    name: LocaleString;
    slug: LocaleString;
    description: LocaleString;
    @Column({ default: true })
    enabled: boolean;
    @Index()
    @ManyToOne(type => Asset, asset => asset.featuredInProducts, { onDelete: 'SET NULL' })
    featuredAsset: Asset;
    @EntityId({ nullable: true })
    featuredAssetId: ID;
    @OneToMany(type => ProductAsset, productAsset => productAsset.product)
    assets: ProductAsset[];
    @OneToMany(type => ProductTranslation, translation => translation.base, { eager: true })
    translations: Array<Translation<Product>>;
    @OneToMany(type => ProductVariant, variant => variant.product)
    variants: ProductVariant[];
    @OneToMany(type => ProductOptionGroup, optionGroup => optionGroup.product)
    optionGroups: ProductOptionGroup[];
    @ManyToMany(type => FacetValue, facetValue => facetValue.products)
    @JoinTable()
    facetValues: FacetValue[];
    @ManyToMany(type => Channel, channel => channel.products)
    @JoinTable()
    channels: Channel[];
    @Column(type => CustomProductFields)
    customFields: CustomProductFields;
}
```
* Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>


* Implements: <code><a href='/reference/typescript-api/entities/interfaces#translatable'>Translatable</a></code>, <code>HasCustomFields</code>, <code><a href='/reference/typescript-api/entities/interfaces#channelaware'>ChannelAware</a></code>, <code><a href='/reference/typescript-api/entities/interfaces#softdeletable'>SoftDeletable</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input?: DeepPartial&#60;<a href='/reference/typescript-api/entities/product#product'>Product</a>&#62;) => Product`}   />


### deletedAt

<MemberInfo kind="property" type={`Date | null`}   />


### name

<MemberInfo kind="property" type={`LocaleString`}   />


### slug

<MemberInfo kind="property" type={`LocaleString`}   />


### description

<MemberInfo kind="property" type={`LocaleString`}   />


### enabled

<MemberInfo kind="property" type={`boolean`}   />


### featuredAsset

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/asset#asset'>Asset</a>`}   />


### featuredAssetId

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a>`}   />


### assets

<MemberInfo kind="property" type={`ProductAsset[]`}   />


### translations

<MemberInfo kind="property" type={`Array&#60;Translation&#60;<a href='/reference/typescript-api/entities/product#product'>Product</a>&#62;&#62;`}   />


### variants

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>[]`}   />


### optionGroups

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/product-option-group#productoptiongroup'>ProductOptionGroup</a>[]`}   />


### facetValues

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/facet-value#facetvalue'>FacetValue</a>[]`}   />


### channels

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/channel#channel'>Channel</a>[]`}   />


### customFields

<MemberInfo kind="property" type={`CustomProductFields`}   />




</div>


---

---
title: "Promotion"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## Promotion

<GenerationInfo sourceFile="packages/core/src/entity/promotion/promotion.entity.ts" sourceLine="61" packageName="@vendure/core" />

A Promotion is used to define a set of conditions under which promotions actions (typically discounts)
will be applied to an Order.

Each assigned <a href='/reference/typescript-api/promotions/promotion-condition#promotioncondition'>PromotionCondition</a> is checked against the Order, and if they all return `true`,
then each assign <a href='/reference/typescript-api/promotions/promotion-action#promotionitemaction'>PromotionItemAction</a> / <a href='/reference/typescript-api/promotions/promotion-action#promotionlineaction'>PromotionLineAction</a> / <a href='/reference/typescript-api/promotions/promotion-action#promotionorderaction'>PromotionOrderAction</a> / <a href='/reference/typescript-api/promotions/promotion-action#promotionshippingaction'>PromotionShippingAction</a> is applied to the Order.

```ts title="Signature"
class Promotion extends AdjustmentSource implements ChannelAware, SoftDeletable, HasCustomFields, Translatable {
    type = AdjustmentType.PROMOTION;
    constructor(input?: DeepPartial<Promotion> & {
            promotionConditions?: Array<PromotionCondition<any>>;
            promotionActions?: Array<PromotionAction<any>>;
        })
    @Column({ type: Date, nullable: true })
    deletedAt: Date | null;
    @Column({ type: Date, nullable: true })
    startsAt: Date | null;
    @Column({ type: Date, nullable: true })
    endsAt: Date | null;
    @Column({ nullable: true })
    couponCode: string;
    @Column({ nullable: true })
    perCustomerUsageLimit: number;
    @Column({ nullable: true })
    usageLimit: number;
    name: LocaleString;
    description: LocaleString;
    @OneToMany(type => PromotionTranslation, translation => translation.base, { eager: true })
    translations: Array<Translation<Promotion>>;
    @Column() enabled: boolean;
    @ManyToMany(type => Channel, channel => channel.promotions)
    @JoinTable()
    channels: Channel[];
    @ManyToMany(type => Order, order => order.promotions)
    orders: Order[];
    @Column(type => CustomPromotionFields)
    customFields: CustomPromotionFields;
    @Column('simple-json') conditions: ConfigurableOperation[];
    @Column('simple-json') actions: ConfigurableOperation[];
    @Column() priorityScore: number;
    apply(ctx: RequestContext, args: ApplyOrderActionArgs | ApplyOrderItemActionArgs | ApplyShippingActionArgs, state?: PromotionState) => Promise<Adjustment | undefined>;
    test(ctx: RequestContext, order: Order) => Promise<PromotionTestResult>;
    activate(ctx: RequestContext, order: Order) => ;
    deactivate(ctx: RequestContext, order: Order) => ;
}
```
* Extends: <code>AdjustmentSource</code>


* Implements: <code><a href='/reference/typescript-api/entities/interfaces#channelaware'>ChannelAware</a></code>, <code><a href='/reference/typescript-api/entities/interfaces#softdeletable'>SoftDeletable</a></code>, <code>HasCustomFields</code>, <code><a href='/reference/typescript-api/entities/interfaces#translatable'>Translatable</a></code>



<div className="members-wrapper">

### type

<MemberInfo kind="property" type={``}   />


### constructor

<MemberInfo kind="method" type={`(input?: DeepPartial&#60;<a href='/reference/typescript-api/entities/promotion#promotion'>Promotion</a>&#62; &#38; {             promotionConditions?: Array&#60;<a href='/reference/typescript-api/promotions/promotion-condition#promotioncondition'>PromotionCondition</a>&#60;any&#62;&#62;;             promotionActions?: Array&#60;<a href='/reference/typescript-api/promotions/promotion-action#promotionaction'>PromotionAction</a>&#60;any&#62;&#62;;         }) => Promotion`}   />


### deletedAt

<MemberInfo kind="property" type={`Date | null`}   />


### startsAt

<MemberInfo kind="property" type={`Date | null`}   />


### endsAt

<MemberInfo kind="property" type={`Date | null`}   />


### couponCode

<MemberInfo kind="property" type={`string`}   />


### perCustomerUsageLimit

<MemberInfo kind="property" type={`number`}   />


### usageLimit

<MemberInfo kind="property" type={`number`}   />


### name

<MemberInfo kind="property" type={`LocaleString`}   />


### description

<MemberInfo kind="property" type={`LocaleString`}   />


### translations

<MemberInfo kind="property" type={`Array&#60;Translation&#60;<a href='/reference/typescript-api/entities/promotion#promotion'>Promotion</a>&#62;&#62;`}   />


### enabled

<MemberInfo kind="property" type={`boolean`}   />


### channels

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/channel#channel'>Channel</a>[]`}   />


### orders

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/order#order'>Order</a>[]`}   />


### customFields

<MemberInfo kind="property" type={`CustomPromotionFields`}   />


### conditions

<MemberInfo kind="property" type={`ConfigurableOperation[]`}   />


### actions

<MemberInfo kind="property" type={`ConfigurableOperation[]`}   />


### priorityScore

<MemberInfo kind="property" type={`number`}   />

The PriorityScore is used to determine the sequence in which multiple promotions are tested
on a given order. A higher number moves the Promotion towards the end of the sequence.

The score is derived from the sum of the priorityValues of the PromotionConditions and
PromotionActions comprising this Promotion.

An example illustrating the need for a priority is this:


Consider 2 Promotions, 1) buy 1 get one free and 2) 10% off when order total is over $50.
If Promotion 2 is evaluated prior to Promotion 1, then it can trigger the 10% discount even
if the subsequent application of Promotion 1 brings the order total down to way below $50.
### apply

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, args: ApplyOrderActionArgs | ApplyOrderItemActionArgs | ApplyShippingActionArgs, state?: PromotionState) => Promise&#60;Adjustment | undefined&#62;`}   />


### test

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>) => Promise&#60;PromotionTestResult&#62;`}   />


### activate

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>) => `}   />


### deactivate

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>) => `}   />




</div>


---

---
title: "Province"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## Province

<GenerationInfo sourceFile="packages/core/src/entity/region/province.entity.ts" sourceLine="13" packageName="@vendure/core" />

A Province represents an administrative subdivision of a <a href='/reference/typescript-api/entities/country#country'>Country</a>. For example, in the
United States, the country would be "United States" and the province would be "California".

```ts title="Signature"
class Province extends Region {
    constructor(input?: DeepPartial<Province>)
    readonly type: RegionType = 'province';
}
```
* Extends: <code><a href='/reference/typescript-api/entities/region#region'>Region</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input?: DeepPartial&#60;<a href='/reference/typescript-api/entities/province#province'>Province</a>&#62;) => Province`}   />


### type

<MemberInfo kind="property" type={`RegionType`}   />




</div>


---

---
title: "Refund"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## Refund

<GenerationInfo sourceFile="packages/core/src/entity/refund/refund.entity.ts" sourceLine="19" packageName="@vendure/core" />

A refund the belongs to an order

```ts title="Signature"
class Refund extends VendureEntity implements HasCustomFields {
    constructor(input?: DeepPartial<Refund>)
    @Money() items: number;
    @Money() shipping: number;
    @Money() adjustment: number;
    @Money() total: number;
    @Column() method: string;
    @Column({ nullable: true }) reason: string;
    @Column('varchar') state: RefundState;
    @Column({ nullable: true }) transactionId: string;
    @OneToMany(type => RefundLine, line => line.refund)
    @JoinTable()
    lines: RefundLine[];
    @Index()
    @ManyToOne(type => Payment, payment => payment.refunds)
    @JoinColumn()
    payment: Payment;
    @EntityId()
    paymentId: ID;
    @Column('simple-json') metadata: PaymentMetadata;
    @Column(type => CustomRefundFields)
    customFields: CustomRefundFields;
}
```
* Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>


* Implements: <code>HasCustomFields</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input?: DeepPartial&#60;<a href='/reference/typescript-api/entities/refund#refund'>Refund</a>&#62;) => Refund`}   />


### items

<MemberInfo kind="property" type={`number`}   />


### shipping

<MemberInfo kind="property" type={`number`}   />


### adjustment

<MemberInfo kind="property" type={`number`}   />


### total

<MemberInfo kind="property" type={`number`}   />


### method

<MemberInfo kind="property" type={`string`}   />


### reason

<MemberInfo kind="property" type={`string`}   />


### state

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/payment/refund-state#refundstate'>RefundState</a>`}   />


### transactionId

<MemberInfo kind="property" type={`string`}   />


### lines

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/order-line-reference#refundline'>RefundLine</a>[]`}   />


### payment

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/payment#payment'>Payment</a>`}   />


### paymentId

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a>`}   />


### metadata

<MemberInfo kind="property" type={`PaymentMetadata`}   />


### customFields

<MemberInfo kind="property" type={`CustomRefundFields`}   />




</div>


---

---
title: "Region"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## Region

<GenerationInfo sourceFile="packages/core/src/entity/region/region.entity.ts" sourceLine="22" packageName="@vendure/core" />

A Region represents a geographical administrative unit, such as a Country, Province, State, Prefecture etc.
This is an abstract class which is extended by the <a href='/reference/typescript-api/entities/country#country'>Country</a> and <a href='/reference/typescript-api/entities/province#province'>Province</a> entities.
Regions can be grouped into <a href='/reference/typescript-api/entities/zone#zone'>Zone</a>s which are in turn used to determine applicable shipping and taxes for an <a href='/reference/typescript-api/entities/order#order'>Order</a>.

```ts title="Signature"
class Region extends VendureEntity implements Translatable, HasCustomFields {
    @Column() code: string;
    @Column({ nullable: false, type: 'varchar' })
    readonly type: RegionType;
    name: LocaleString;
    @Index()
    @ManyToOne(type => Region, { nullable: true, onDelete: 'SET NULL' })
    parent?: Region;
    @EntityId({ nullable: true })
    parentId?: ID;
    @Column() enabled: boolean;
    @OneToMany(type => RegionTranslation, translation => translation.base, { eager: true })
    translations: Array<Translation<Region>>;
    @Column(type => CustomRegionFields)
    customFields: CustomRegionFields;
}
```
* Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>


* Implements: <code><a href='/reference/typescript-api/entities/interfaces#translatable'>Translatable</a></code>, <code>HasCustomFields</code>



<div className="members-wrapper">

### code

<MemberInfo kind="property" type={`string`}   />

A code representing the region. The code format will depend on the type of region. For
example, a Country code will be a 2-letter ISO code, whereas a Province code could use
a format relevant to the type of province, e.g. a US state code like "CA".
### type

<MemberInfo kind="property" type={`RegionType`}   />


### name

<MemberInfo kind="property" type={`LocaleString`}   />


### parent

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/region#region'>Region</a>`}   />


### parentId

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a>`}   />


### enabled

<MemberInfo kind="property" type={`boolean`}   />


### translations

<MemberInfo kind="property" type={`Array&#60;Translation&#60;<a href='/reference/typescript-api/entities/region#region'>Region</a>&#62;&#62;`}   />


### customFields

<MemberInfo kind="property" type={`CustomRegionFields`}   />




</div>


---

---
title: "Role"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## Role

<GenerationInfo sourceFile="packages/core/src/entity/role/role.entity.ts" sourceLine="16" packageName="@vendure/core" />

A Role represents a collection of permissions which determine the authorization
level of a <a href='/reference/typescript-api/entities/user#user'>User</a> on a given set of <a href='/reference/typescript-api/entities/channel#channel'>Channel</a>s.

```ts title="Signature"
class Role extends VendureEntity implements ChannelAware {
    constructor(input?: DeepPartial<Role>)
    @Column() code: string;
    @Column() description: string;
    @Column('simple-array') permissions: Permission[];
    @ManyToMany(type => Channel, channel => channel.roles)
    @JoinTable()
    channels: Channel[];
}
```
* Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>


* Implements: <code><a href='/reference/typescript-api/entities/interfaces#channelaware'>ChannelAware</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input?: DeepPartial&#60;<a href='/reference/typescript-api/entities/role#role'>Role</a>&#62;) => Role`}   />


### code

<MemberInfo kind="property" type={`string`}   />


### description

<MemberInfo kind="property" type={`string`}   />


### permissions

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/permission#permission'>Permission</a>[]`}   />


### channels

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/channel#channel'>Channel</a>[]`}   />




</div>


---

---
title: "Seller"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## Seller

<GenerationInfo sourceFile="packages/core/src/entity/seller/seller.entity.ts" sourceLine="17" packageName="@vendure/core" />

A Seller represents the person or organization who is selling the goods on a given <a href='/reference/typescript-api/entities/channel#channel'>Channel</a>.
By default, a single-channel Vendure installation will have a single default Seller.

```ts title="Signature"
class Seller extends VendureEntity implements SoftDeletable, HasCustomFields {
    constructor(input?: DeepPartial<Seller>)
    @Column({ type: Date, nullable: true })
    deletedAt: Date | null;
    @Column() name: string;
    @Column(type => CustomSellerFields)
    customFields: CustomSellerFields;
    @OneToMany(type => Channel, channel => channel.seller)
    channels: Channel[];
}
```
* Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>


* Implements: <code><a href='/reference/typescript-api/entities/interfaces#softdeletable'>SoftDeletable</a></code>, <code>HasCustomFields</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input?: DeepPartial&#60;<a href='/reference/typescript-api/entities/seller#seller'>Seller</a>&#62;) => Seller`}   />


### deletedAt

<MemberInfo kind="property" type={`Date | null`}   />


### name

<MemberInfo kind="property" type={`string`}   />


### customFields

<MemberInfo kind="property" type={`CustomSellerFields`}   />


### channels

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/channel#channel'>Channel</a>[]`}   />




</div>


---

---
title: "Session"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## Session

<GenerationInfo sourceFile="packages/core/src/entity/session/session.entity.ts" sourceLine="18" packageName="@vendure/core" />

A Session is created when a user makes a request to restricted API operations. A Session can be an <a href='/reference/typescript-api/entities/anonymous-session#anonymoussession'>AnonymousSession</a>
in the case of un-authenticated users, otherwise it is an <a href='/reference/typescript-api/entities/authenticated-session#authenticatedsession'>AuthenticatedSession</a>.

```ts title="Signature"
class Session extends VendureEntity implements HasCustomFields {
    @Index({ unique: true })
    @Column()
    token: string;
    @Column() expires: Date;
    @Column() invalidated: boolean;
    @EntityId({ nullable: true })
    activeOrderId?: ID;
    @Index()
    @ManyToOne(type => Order)
    activeOrder: Order | null;
    @EntityId({ nullable: true })
    activeChannelId?: ID;
    @Index()
    @ManyToOne(type => Channel)
    activeChannel: Channel | null;
    @Column(type => CustomSessionFields)
    customFields: CustomSessionFields;
}
```
* Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>


* Implements: <code>HasCustomFields</code>



<div className="members-wrapper">

### token

<MemberInfo kind="property" type={`string`}   />


### expires

<MemberInfo kind="property" type={`Date`}   />


### invalidated

<MemberInfo kind="property" type={`boolean`}   />


### activeOrderId

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a>`}   />


### activeOrder

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/order#order'>Order</a> | null`}   />


### activeChannelId

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a>`}   />


### activeChannel

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/channel#channel'>Channel</a> | null`}   />


### customFields

<MemberInfo kind="property" type={`CustomSessionFields`}   />




</div>


---

---
title: "SettingsStoreEntry"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## SettingsStoreEntry

<GenerationInfo sourceFile="packages/core/src/entity/settings-store-entry/settings-store-entry.entity.ts" sourceLine="15" packageName="@vendure/core" since="3.4.0" />

An entity for storing arbitrary settings data with scoped isolation.
This is used by the SettingsStore system to provide flexible key-value storage
with support for user, channel, and custom scoping.

```ts title="Signature"
class SettingsStoreEntry extends VendureEntity {
    constructor(input?: Partial<SettingsStoreEntry>)
    @Index()
    @Column()
    key: string;
    @Column('json', { nullable: true })
    value: any | null;
    @Index()
    @Column({ type: 'varchar', nullable: true })
    scope: string | null;
}
```
* Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input?: Partial&#60;<a href='/reference/typescript-api/entities/settings-store-entry#settingsstoreentry'>SettingsStoreEntry</a>&#62;) => SettingsStoreEntry`}   />


### key

<MemberInfo kind="property" type={`string`}   />

The settings key, typically in the format 'namespace.fieldName'
### value

<MemberInfo kind="property" type={`any | null`}   />

The JSON value stored for this setting
### scope

<MemberInfo kind="property" type={`string | null`}   />

The scope string that isolates this setting (e.g., 'user:123', 'channel:456', '')


</div>


---

---
title: "ShippingLine"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ShippingLine

<GenerationInfo sourceFile="packages/core/src/entity/shipping-line/shipping-line.entity.ts" sourceLine="26" packageName="@vendure/core" />

A ShippingLine is created when a <a href='/reference/typescript-api/entities/shipping-method#shippingmethod'>ShippingMethod</a> is applied to an <a href='/reference/typescript-api/entities/order#order'>Order</a>.
It contains information about the price of the shipping method, any discounts that were
applied, and the resulting tax on the shipping method.

```ts title="Signature"
class ShippingLine extends VendureEntity implements HasCustomFields {
    constructor(input?: DeepPartial<ShippingLine>)
    @EntityId()
    shippingMethodId: ID | null;
    @Index()
    @ManyToOne(type => ShippingMethod)
    shippingMethod: ShippingMethod;
    @Index()
    @ManyToOne(type => Order, order => order.shippingLines, { onDelete: 'CASCADE' })
    order: Order;
    @Money()
    listPrice: number;
    @Column()
    listPriceIncludesTax: boolean;
    @Column('simple-json')
    adjustments: Adjustment[];
    @Column('simple-json')
    taxLines: TaxLine[];
    @OneToMany(type => OrderLine, orderLine => orderLine.shippingLine)
    orderLines: OrderLine[];
    @Column(type => CustomShippingLineFields)
    customFields: CustomShippingLineFields;
    price: number
    priceWithTax: number
    discountedPrice: number
    discountedPriceWithTax: number
    taxRate: number
    discounts: Discount[]
    addAdjustment(adjustment: Adjustment) => ;
    clearAdjustments() => ;
}
```
* Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>


* Implements: <code>HasCustomFields</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input?: DeepPartial&#60;<a href='/reference/typescript-api/entities/shipping-line#shippingline'>ShippingLine</a>&#62;) => ShippingLine`}   />


### shippingMethodId

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a> | null`}   />


### shippingMethod

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/shipping-method#shippingmethod'>ShippingMethod</a>`}   />


### order

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/order#order'>Order</a>`}   />


### listPrice

<MemberInfo kind="property" type={`number`}   />


### listPriceIncludesTax

<MemberInfo kind="property" type={`boolean`}   />


### adjustments

<MemberInfo kind="property" type={`Adjustment[]`}   />


### taxLines

<MemberInfo kind="property" type={`TaxLine[]`}   />


### orderLines

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a>[]`}   />


### customFields

<MemberInfo kind="property" type={`CustomShippingLineFields`}   />


### price

<MemberInfo kind="property" type={`number`}   />


### priceWithTax

<MemberInfo kind="property" type={`number`}   />


### discountedPrice

<MemberInfo kind="property" type={`number`}   />


### discountedPriceWithTax

<MemberInfo kind="property" type={`number`}   />


### taxRate

<MemberInfo kind="property" type={`number`}   />


### discounts

<MemberInfo kind="property" type={`Discount[]`}   />


### addAdjustment

<MemberInfo kind="method" type={`(adjustment: Adjustment) => `}   />


### clearAdjustments

<MemberInfo kind="method" type={`() => `}   />




</div>


---

---
title: "ShippingMethod"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ShippingMethod

<GenerationInfo sourceFile="packages/core/src/entity/shipping-method/shipping-method.entity.ts" sourceLine="34" packageName="@vendure/core" />

A ShippingMethod is used to apply a shipping price to an <a href='/reference/typescript-api/entities/order#order'>Order</a>. It is composed of a
<a href='/reference/typescript-api/shipping/shipping-eligibility-checker#shippingeligibilitychecker'>ShippingEligibilityChecker</a> and a <a href='/reference/typescript-api/shipping/shipping-calculator#shippingcalculator'>ShippingCalculator</a>. For a given Order,
the `checker` is used to determine whether this ShippingMethod can be used. If yes, then
the ShippingMethod can be applied and the `calculator` is used to determine the price of
shipping.

```ts title="Signature"
class ShippingMethod extends VendureEntity implements ChannelAware, SoftDeletable, HasCustomFields, Translatable {
    constructor(input?: DeepPartial<ShippingMethod>)
    @Column({ type: Date, nullable: true })
    deletedAt: Date | null;
    @Column() code: string;
    name: LocaleString;
    description: LocaleString;
    @Column('simple-json') checker: ConfigurableOperation;
    @Column('simple-json') calculator: ConfigurableOperation;
    @Column()
    fulfillmentHandlerCode: string;
    @ManyToMany(type => Channel, channel => channel.shippingMethods)
    @JoinTable()
    channels: Channel[];
    @OneToMany(type => ShippingMethodTranslation, translation => translation.base, { eager: true })
    translations: Array<Translation<ShippingMethod>>;
    @Column(type => CustomShippingMethodFields)
    customFields: CustomShippingMethodFields;
    apply(ctx: RequestContext, order: Order) => Promise<ShippingCalculationResult | undefined>;
    test(ctx: RequestContext, order: Order) => Promise<boolean>;
    toJSON() => any;
}
```
* Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>


* Implements: <code><a href='/reference/typescript-api/entities/interfaces#channelaware'>ChannelAware</a></code>, <code><a href='/reference/typescript-api/entities/interfaces#softdeletable'>SoftDeletable</a></code>, <code>HasCustomFields</code>, <code><a href='/reference/typescript-api/entities/interfaces#translatable'>Translatable</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input?: DeepPartial&#60;<a href='/reference/typescript-api/entities/shipping-method#shippingmethod'>ShippingMethod</a>&#62;) => ShippingMethod`}   />


### deletedAt

<MemberInfo kind="property" type={`Date | null`}   />


### code

<MemberInfo kind="property" type={`string`}   />


### name

<MemberInfo kind="property" type={`LocaleString`}   />


### description

<MemberInfo kind="property" type={`LocaleString`}   />


### checker

<MemberInfo kind="property" type={`ConfigurableOperation`}   />


### calculator

<MemberInfo kind="property" type={`ConfigurableOperation`}   />


### fulfillmentHandlerCode

<MemberInfo kind="property" type={`string`}   />


### channels

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/channel#channel'>Channel</a>[]`}   />


### translations

<MemberInfo kind="property" type={`Array&#60;Translation&#60;<a href='/reference/typescript-api/entities/shipping-method#shippingmethod'>ShippingMethod</a>&#62;&#62;`}   />


### customFields

<MemberInfo kind="property" type={`CustomShippingMethodFields`}   />


### apply

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>) => Promise&#60;<a href='/reference/typescript-api/shipping/shipping-calculator#shippingcalculationresult'>ShippingCalculationResult</a> | undefined&#62;`}   />


### test

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>) => Promise&#60;boolean&#62;`}   />


### toJSON

<MemberInfo kind="method" type={`() => any`}   />




</div>


---

---
title: "StockLevel"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## StockLevel

<GenerationInfo sourceFile="packages/core/src/entity/stock-level/stock-level.entity.ts" sourceLine="18" packageName="@vendure/core" />

A StockLevel represents the number of a particular <a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a> which are available
at a particular <a href='/reference/typescript-api/entities/stock-location#stocklocation'>StockLocation</a>.

```ts title="Signature"
class StockLevel extends VendureEntity implements HasCustomFields {
    constructor(input: DeepPartial<StockLevel>)
    @Index()
    @ManyToOne(type => ProductVariant, productVariant => productVariant.stockLevels, { onDelete: 'CASCADE' })
    productVariant: ProductVariant;
    @EntityId()
    productVariantId: ID;
    @Index()
    @ManyToOne(type => StockLocation, { onDelete: 'CASCADE' })
    stockLocation: StockLocation;
    @EntityId()
    stockLocationId: ID;
    @Column()
    stockOnHand: number;
    @Column()
    stockAllocated: number;
    @Column(type => CustomStockLevelFields)
    customFields: CustomStockLevelFields;
}
```
* Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>


* Implements: <code>HasCustomFields</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input: DeepPartial&#60;<a href='/reference/typescript-api/entities/stock-level#stocklevel'>StockLevel</a>&#62;) => StockLevel`}   />


### productVariant

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>`}   />


### productVariantId

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a>`}   />


### stockLocation

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/stock-location#stocklocation'>StockLocation</a>`}   />


### stockLocationId

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a>`}   />


### stockOnHand

<MemberInfo kind="property" type={`number`}   />


### stockAllocated

<MemberInfo kind="property" type={`number`}   />


### customFields

<MemberInfo kind="property" type={`CustomStockLevelFields`}   />




</div>


---

---
title: "StockLocation"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## StockLocation

<GenerationInfo sourceFile="packages/core/src/entity/stock-location/stock-location.entity.ts" sourceLine="22" packageName="@vendure/core" />

A StockLocation represents a physical location where stock is held. For example, a warehouse or a shop.

When the stock of a <a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a> is adjusted, the adjustment is applied to a specific StockLocation,
and the stockOnHand of that ProductVariant is updated accordingly. When there are multiple StockLocations
configured, the <a href='/reference/typescript-api/products-stock/stock-location-strategy#stocklocationstrategy'>StockLocationStrategy</a> is used to determine which StockLocation should be used for
a given operation.

```ts title="Signature"
class StockLocation extends VendureEntity implements HasCustomFields, ChannelAware {
    constructor(input: DeepPartial<StockLocation>)
    @Column()
    name: string;
    @Column()
    description: string;
    @Column(type => CustomStockLocationFields)
    customFields: CustomStockLocationFields;
    @ManyToMany(type => Channel, channel => channel.stockLocations)
    @JoinTable()
    channels: Channel[];
    @OneToMany(type => StockMovement, movement => movement.stockLocation)
    stockMovements: StockMovement[];
}
```
* Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>


* Implements: <code>HasCustomFields</code>, <code><a href='/reference/typescript-api/entities/interfaces#channelaware'>ChannelAware</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input: DeepPartial&#60;<a href='/reference/typescript-api/entities/stock-location#stocklocation'>StockLocation</a>&#62;) => StockLocation`}   />


### name

<MemberInfo kind="property" type={`string`}   />


### description

<MemberInfo kind="property" type={`string`}   />


### customFields

<MemberInfo kind="property" type={`CustomStockLocationFields`}   />


### channels

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/channel#channel'>Channel</a>[]`}   />


### stockMovements

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/stock-movement#stockmovement'>StockMovement</a>[]`}   />




</div>


---

---
title: "StockMovement"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## StockMovement

<GenerationInfo sourceFile="packages/core/src/entity/stock-movement/stock-movement.entity.ts" sourceLine="21" packageName="@vendure/core" />

A StockMovement is created whenever stock of a particular ProductVariant goes in
or out.

```ts title="Signature"
class StockMovement extends VendureEntity implements HasCustomFields {
    @Column({ nullable: false, type: 'varchar' })
    readonly type: StockMovementType;
    @Index()
    @ManyToOne(type => ProductVariant, variant => variant.stockMovements)
    productVariant: ProductVariant;
    @Index()
    @ManyToOne(type => StockLocation, stockLocation => stockLocation.stockMovements, { onDelete: 'CASCADE' })
    stockLocation: StockLocation;
    @EntityId()
    stockLocationId: ID;
    @Column()
    quantity: number;
    @Column(type => CustomStockMovementFields)
    customFields: CustomStockMovementFields;
}
```
* Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>


* Implements: <code>HasCustomFields</code>



<div className="members-wrapper">

### type

<MemberInfo kind="property" type={`StockMovementType`}   />


### productVariant

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>`}   />


### stockLocation

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/stock-location#stocklocation'>StockLocation</a>`}   />


### stockLocationId

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a>`}   />


### quantity

<MemberInfo kind="property" type={`number`}   />


### customFields

<MemberInfo kind="property" type={`CustomStockMovementFields`}   />




</div>


## Allocation

<GenerationInfo sourceFile="packages/core/src/entity/stock-movement/allocation.entity.ts" sourceLine="17" packageName="@vendure/core" />

An Allocation is created for each ProductVariant in an Order when the checkout is completed
(as configured by the <a href='/reference/typescript-api/orders/stock-allocation-strategy#stockallocationstrategy'>StockAllocationStrategy</a>. This prevents stock being sold twice.

```ts title="Signature"
class Allocation extends StockMovement {
    readonly type = StockMovementType.ALLOCATION;
    constructor(input: DeepPartial<Allocation>)
    @Index()
    @ManyToOne(type => OrderLine, orderLine => orderLine.allocations)
    orderLine: OrderLine;
}
```
* Extends: <code><a href='/reference/typescript-api/entities/stock-movement#stockmovement'>StockMovement</a></code>



<div className="members-wrapper">

### type

<MemberInfo kind="property" type={``}   />


### constructor

<MemberInfo kind="method" type={`(input: DeepPartial&#60;<a href='/reference/typescript-api/entities/stock-movement#allocation'>Allocation</a>&#62;) => Allocation`}   />


### orderLine

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a>`}   />




</div>


## Cancellation

<GenerationInfo sourceFile="packages/core/src/entity/stock-movement/cancellation.entity.ts" sourceLine="16" packageName="@vendure/core" />

A Cancellation is created when OrderItems from a fulfilled Order are cancelled.

```ts title="Signature"
class Cancellation extends StockMovement {
    readonly type = StockMovementType.CANCELLATION;
    constructor(input: DeepPartial<Cancellation>)
    @ManyToOne(type => OrderLine, orderLine => orderLine.cancellations)
    orderLine: OrderLine;
}
```
* Extends: <code><a href='/reference/typescript-api/entities/stock-movement#stockmovement'>StockMovement</a></code>



<div className="members-wrapper">

### type

<MemberInfo kind="property" type={``}   />


### constructor

<MemberInfo kind="method" type={`(input: DeepPartial&#60;<a href='/reference/typescript-api/entities/stock-movement#cancellation'>Cancellation</a>&#62;) => Cancellation`}   />


### orderLine

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a>`}   />




</div>


## Release

<GenerationInfo sourceFile="packages/core/src/entity/stock-movement/release.entity.ts" sourceLine="17" packageName="@vendure/core" />

A Release is created when OrderItems which have been allocated (but not yet fulfilled)
are cancelled.

```ts title="Signature"
class Release extends StockMovement {
    readonly type = StockMovementType.RELEASE;
    constructor(input: DeepPartial<Release>)
    @ManyToOne(type => OrderLine)
    orderLine: OrderLine;
}
```
* Extends: <code><a href='/reference/typescript-api/entities/stock-movement#stockmovement'>StockMovement</a></code>



<div className="members-wrapper">

### type

<MemberInfo kind="property" type={``}   />


### constructor

<MemberInfo kind="method" type={`(input: DeepPartial&#60;<a href='/reference/typescript-api/entities/stock-movement#release'>Release</a>&#62;) => Release`}   />


### orderLine

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a>`}   />




</div>


## Sale

<GenerationInfo sourceFile="packages/core/src/entity/stock-movement/sale.entity.ts" sourceLine="16" packageName="@vendure/core" />

A Sale is created when OrderItems are fulfilled.

```ts title="Signature"
class Sale extends StockMovement {
    readonly type = StockMovementType.SALE;
    constructor(input: DeepPartial<Sale>)
    @ManyToOne(type => OrderLine, line => line.sales)
    orderLine: OrderLine;
}
```
* Extends: <code><a href='/reference/typescript-api/entities/stock-movement#stockmovement'>StockMovement</a></code>



<div className="members-wrapper">

### type

<MemberInfo kind="property" type={``}   />


### constructor

<MemberInfo kind="method" type={`(input: DeepPartial&#60;<a href='/reference/typescript-api/entities/stock-movement#sale'>Sale</a>&#62;) => Sale`}   />


### orderLine

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a>`}   />




</div>


## StockAdjustment

<GenerationInfo sourceFile="packages/core/src/entity/stock-movement/stock-adjustment.entity.ts" sourceLine="14" packageName="@vendure/core" />

A StockAdjustment is created when the `stockOnHand` level of a ProductVariant is manually adjusted.

```ts title="Signature"
class StockAdjustment extends StockMovement {
    readonly type = StockMovementType.ADJUSTMENT;
    constructor(input: DeepPartial<StockAdjustment>)
}
```
* Extends: <code><a href='/reference/typescript-api/entities/stock-movement#stockmovement'>StockMovement</a></code>



<div className="members-wrapper">

### type

<MemberInfo kind="property" type={``}   />


### constructor

<MemberInfo kind="method" type={`(input: DeepPartial&#60;<a href='/reference/typescript-api/entities/stock-movement#stockadjustment'>StockAdjustment</a>&#62;) => StockAdjustment`}   />




</div>


---

---
title: "Surcharge"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## Surcharge

<GenerationInfo sourceFile="packages/core/src/entity/surcharge/surcharge.entity.ts" sourceLine="21" packageName="@vendure/core" />

A Surcharge represents an arbitrary extra item on an <a href='/reference/typescript-api/entities/order#order'>Order</a> which is not
a ProductVariant. It can be used to e.g. represent payment-related surcharges.

```ts title="Signature"
class Surcharge extends VendureEntity {
    constructor(input?: DeepPartial<Surcharge>)
    @Column()
    description: string;
    @Money()
    listPrice: number;
    @Column()
    listPriceIncludesTax: boolean;
    @Column()
    sku: string;
    @Column('simple-json')
    taxLines: TaxLine[];
    @Index()
    @ManyToOne(type => Order, order => order.surcharges, { onDelete: 'CASCADE' })
    order: Order;
    @Index()
    @ManyToOne(type => OrderModification, orderModification => orderModification.surcharges)
    orderModification: OrderModification;
    price: number
    priceWithTax: number
    taxRate: number
}
```
* Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input?: DeepPartial&#60;<a href='/reference/typescript-api/entities/surcharge#surcharge'>Surcharge</a>&#62;) => Surcharge`}   />


### description

<MemberInfo kind="property" type={`string`}   />


### listPrice

<MemberInfo kind="property" type={`number`}   />


### listPriceIncludesTax

<MemberInfo kind="property" type={`boolean`}   />


### sku

<MemberInfo kind="property" type={`string`}   />


### taxLines

<MemberInfo kind="property" type={`TaxLine[]`}   />


### order

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/order#order'>Order</a>`}   />


### orderModification

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/order-modification#ordermodification'>OrderModification</a>`}   />


### price

<MemberInfo kind="property" type={`number`}   />


### priceWithTax

<MemberInfo kind="property" type={`number`}   />


### taxRate

<MemberInfo kind="property" type={`number`}   />




</div>


---

---
title: "Tag"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## Tag

<GenerationInfo sourceFile="packages/core/src/entity/tag/tag.entity.ts" sourceLine="13" packageName="@vendure/core" />

A tag is an arbitrary label which can be applied to certain entities.
It is used to help organize and filter those entities.

```ts title="Signature"
class Tag extends VendureEntity {
    constructor(input?: DeepPartial<Tag>)
    @Column()
    value: string;
}
```
* Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input?: DeepPartial&#60;<a href='/reference/typescript-api/entities/tag#tag'>Tag</a>&#62;) => Tag`}   />


### value

<MemberInfo kind="property" type={`string`}   />




</div>


---

---
title: "TaxCategory"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## TaxCategory

<GenerationInfo sourceFile="packages/core/src/entity/tax-category/tax-category.entity.ts" sourceLine="16" packageName="@vendure/core" />

A TaxCategory defines what type of taxes to apply to a <a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>.

```ts title="Signature"
class TaxCategory extends VendureEntity implements HasCustomFields {
    constructor(input?: DeepPartial<TaxCategory>)
    @Column() name: string;
    @Column({ default: false }) isDefault: boolean;
    @Column(type => CustomTaxCategoryFields)
    customFields: CustomTaxCategoryFields;
    @OneToMany(type => ProductVariant, productVariant => productVariant.taxCategory)
    productVariants: ProductVariant[];
    @OneToMany(type => TaxRate, taxRate => taxRate.category)
    taxRates: TaxRate[];
}
```
* Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>


* Implements: <code>HasCustomFields</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input?: DeepPartial&#60;<a href='/reference/typescript-api/entities/tax-category#taxcategory'>TaxCategory</a>&#62;) => TaxCategory`}   />


### name

<MemberInfo kind="property" type={`string`}   />


### isDefault

<MemberInfo kind="property" type={`boolean`}   />


### customFields

<MemberInfo kind="property" type={`CustomTaxCategoryFields`}   />


### productVariants

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>[]`}   />


### taxRates

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/tax-rate#taxrate'>TaxRate</a>[]`}   />




</div>


---

---
title: "TaxRate"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## TaxRate

<GenerationInfo sourceFile="packages/core/src/entity/tax-rate/tax-rate.entity.ts" sourceLine="26" packageName="@vendure/core" />

A TaxRate defines the rate of tax to apply to a <a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a> based on three factors:

1. the ProductVariant's <a href='/reference/typescript-api/entities/tax-category#taxcategory'>TaxCategory</a>
2. the applicable <a href='/reference/typescript-api/entities/zone#zone'>Zone</a> ("applicable" being defined by the configured <a href='/reference/typescript-api/tax/tax-zone-strategy#taxzonestrategy'>TaxZoneStrategy</a>)
3. the <a href='/reference/typescript-api/entities/customer-group#customergroup'>CustomerGroup</a> of the current Customer

```ts title="Signature"
class TaxRate extends VendureEntity implements HasCustomFields {
    constructor(input?: DeepPartial<TaxRate>)
    @Column() name: string;
    @Column() enabled: boolean;
    @Column({ type: 'decimal', precision: 5, scale: 2, transformer: new DecimalTransformer() }) value: number;
    @Index()
    @ManyToOne(type => TaxCategory, taxCategory => taxCategory.taxRates)
    category: TaxCategory;
    @EntityId({ nullable: true })
    categoryId: ID;
    @Index()
    @ManyToOne(type => Zone, zone => zone.taxRates)
    zone: Zone;
    @EntityId({ nullable: true })
    zoneId: ID;
    @Index()
    @ManyToOne(type => CustomerGroup, customerGroup => customerGroup.taxRates, { nullable: true })
    customerGroup?: CustomerGroup;
    @Column(type => CustomTaxRateFields)
    customFields: CustomTaxRateFields;
    taxComponentOf(grossPrice: number) => number;
    netPriceOf(grossPrice: number) => number;
    taxPayableOn(netPrice: number) => number;
    grossPriceOf(netPrice: number) => number;
    apply(price: number) => TaxLine;
    test(zone: Zone | ID, taxCategory: TaxCategory | ID) => boolean;
}
```
* Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>


* Implements: <code>HasCustomFields</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input?: DeepPartial&#60;<a href='/reference/typescript-api/entities/tax-rate#taxrate'>TaxRate</a>&#62;) => TaxRate`}   />


### name

<MemberInfo kind="property" type={`string`}   />


### enabled

<MemberInfo kind="property" type={`boolean`}   />


### value

<MemberInfo kind="property" type={`number`}   />


### category

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/tax-category#taxcategory'>TaxCategory</a>`}   />


### categoryId

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a>`}   />


### zone

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/zone#zone'>Zone</a>`}   />


### zoneId

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a>`}   />


### customerGroup

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/customer-group#customergroup'>CustomerGroup</a>`}   />


### customFields

<MemberInfo kind="property" type={`CustomTaxRateFields`}   />


### taxComponentOf

<MemberInfo kind="method" type={`(grossPrice: number) => number`}   />


### netPriceOf

<MemberInfo kind="method" type={`(grossPrice: number) => number`}   />


### taxPayableOn

<MemberInfo kind="method" type={`(netPrice: number) => number`}   />


### grossPriceOf

<MemberInfo kind="method" type={`(netPrice: number) => number`}   />


### apply

<MemberInfo kind="method" type={`(price: number) => TaxLine`}   />


### test

<MemberInfo kind="method" type={`(zone: <a href='/reference/typescript-api/entities/zone#zone'>Zone</a> | <a href='/reference/typescript-api/common/id#id'>ID</a>, taxCategory: <a href='/reference/typescript-api/entities/tax-category#taxcategory'>TaxCategory</a> | <a href='/reference/typescript-api/common/id#id'>ID</a>) => boolean`}   />




</div>


---

---
title: "User"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## User

<GenerationInfo sourceFile="packages/core/src/entity/user/user.entity.ts" sourceLine="21" packageName="@vendure/core" />

A User represents any authenticated user of the Vendure API. This includes both
<a href='/reference/typescript-api/entities/administrator#administrator'>Administrator</a>s as well as registered <a href='/reference/typescript-api/entities/customer#customer'>Customer</a>s.

```ts title="Signature"
class User extends VendureEntity implements HasCustomFields, SoftDeletable {
    constructor(input?: DeepPartial<User>)
    @Column({ type: Date, nullable: true })
    deletedAt: Date | null;
    @Column()
    identifier: string;
    @OneToMany(type => AuthenticationMethod, method => method.user)
    authenticationMethods: AuthenticationMethod[];
    @Column({ default: false })
    verified: boolean;
    @ManyToMany(type => Role)
    @JoinTable()
    roles: Role[];
    @Column({ type: Date, nullable: true })
    lastLogin: Date | null;
    @Column(type => CustomUserFields)
    customFields: CustomUserFields;
    @OneToMany(type => AuthenticatedSession, session => session.user)
    sessions: AuthenticatedSession[];
    getNativeAuthenticationMethod() => NativeAuthenticationMethod;
    getNativeAuthenticationMethod(strict?: boolean) => NativeAuthenticationMethod | undefined;
    getNativeAuthenticationMethod(strict?: boolean) => NativeAuthenticationMethod | undefined;
}
```
* Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>


* Implements: <code>HasCustomFields</code>, <code><a href='/reference/typescript-api/entities/interfaces#softdeletable'>SoftDeletable</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input?: DeepPartial&#60;<a href='/reference/typescript-api/entities/user#user'>User</a>&#62;) => User`}   />


### deletedAt

<MemberInfo kind="property" type={`Date | null`}   />


### identifier

<MemberInfo kind="property" type={`string`}   />


### authenticationMethods

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/authentication-method#authenticationmethod'>AuthenticationMethod</a>[]`}   />


### verified

<MemberInfo kind="property" type={`boolean`}   />


### roles

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/role#role'>Role</a>[]`}   />


### lastLogin

<MemberInfo kind="property" type={`Date | null`}   />


### customFields

<MemberInfo kind="property" type={`CustomUserFields`}   />


### sessions

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/authenticated-session#authenticatedsession'>AuthenticatedSession</a>[]`}   />


### getNativeAuthenticationMethod

<MemberInfo kind="method" type={`() => <a href='/reference/typescript-api/entities/authentication-method#nativeauthenticationmethod'>NativeAuthenticationMethod</a>`}   />


### getNativeAuthenticationMethod

<MemberInfo kind="method" type={`(strict?: boolean) => <a href='/reference/typescript-api/entities/authentication-method#nativeauthenticationmethod'>NativeAuthenticationMethod</a> | undefined`}   />


### getNativeAuthenticationMethod

<MemberInfo kind="method" type={`(strict?: boolean) => <a href='/reference/typescript-api/entities/authentication-method#nativeauthenticationmethod'>NativeAuthenticationMethod</a> | undefined`}   />




</div>


---

---
title: "VendureEntity"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## VendureEntity

<GenerationInfo sourceFile="packages/core/src/entity/base/base.entity.ts" sourceLine="13" packageName="@vendure/core" />

This is the base class from which all entities inherit. The type of
the `id` property is defined by the <a href='/reference/typescript-api/configuration/entity-id-strategy#entityidstrategy'>EntityIdStrategy</a>.

```ts title="Signature"
class VendureEntity {
    constructor(input?: DeepPartial<VendureEntity>)
    @PrimaryGeneratedId()
    id: ID;
    @CreateDateColumn() createdAt: Date;
    @UpdateDateColumn() updatedAt: Date;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input?: DeepPartial&#60;<a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a>&#62;) => VendureEntity`}   />


### id

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a>`}   />


### createdAt

<MemberInfo kind="property" type={`Date`}   />


### updatedAt

<MemberInfo kind="property" type={`Date`}   />




</div>


---

---
title: "Zone"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## Zone

<GenerationInfo sourceFile="packages/core/src/entity/zone/zone.entity.ts" sourceLine="19" packageName="@vendure/core" />

A Zone is a grouping of one or more <a href='/reference/typescript-api/entities/country#country'>Country</a> entities. It is used for
calculating applicable shipping and taxes.

```ts title="Signature"
class Zone extends VendureEntity implements HasCustomFields {
    constructor(input?: DeepPartial<Zone>)
    @Column() name: string;
    @ManyToMany(type => Region)
    @JoinTable()
    members: Region[];
    @Column(type => CustomZoneFields)
    customFields: CustomZoneFields;
    @OneToMany(type => Channel, country => country.defaultShippingZone)
    defaultShippingZoneChannels: Channel[];
    @OneToMany(type => Channel, country => country.defaultTaxZone)
    defaultTaxZoneChannels: Channel[];
    @OneToMany(type => TaxRate, taxRate => taxRate.zone)
    taxRates: TaxRate[];
}
```
* Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>


* Implements: <code>HasCustomFields</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(input?: DeepPartial&#60;<a href='/reference/typescript-api/entities/zone#zone'>Zone</a>&#62;) => Zone`}   />


### name

<MemberInfo kind="property" type={`string`}   />


### members

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/region#region'>Region</a>[]`}   />


### customFields

<MemberInfo kind="property" type={`CustomZoneFields`}   />


### defaultShippingZoneChannels

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/channel#channel'>Channel</a>[]`}   />


### defaultTaxZoneChannels

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/channel#channel'>Channel</a>[]`}   />


### taxRates

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/tax-rate#taxrate'>TaxRate</a>[]`}   />




</div>


---

---
title: "ErrorHandlerStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ErrorHandlerStrategy

<GenerationInfo sourceFile="packages/core/src/config/system/error-handler-strategy.ts" sourceLine="60" packageName="@vendure/core" since="2.2.0" />

This strategy defines logic for handling errors thrown during on both the server
and the worker. It can be used for additional logging & monitoring, or for sending error
reports to external services.

:::info

This is configured via the `systemOptions.errorHandlers` property of
your VendureConfig.

:::

*Example*

```ts
import { ArgumentsHost, ExecutionContext } from '@nestjs/common';
import { GqlContextType, GqlExecutionContext } from '@nestjs/graphql';
import { ErrorHandlerStrategy, I18nError, Injector, Job, LogLevel } from '@vendure/core';

import { MonitoringService } from './monitoring.service';

export class CustomErrorHandlerStrategy implements ErrorHandlerStrategy {
    private monitoringService: MonitoringService;

    init(injector: Injector) {
        this.monitoringService = injector.get(MonitoringService);
    }

    handleServerError(error: Error, { host }: { host: ArgumentsHost }) {
         const errorContext: any = {};
         if (host?.getType<GqlContextType>() === 'graphql') {
             const gqlContext = GqlExecutionContext.create(host as ExecutionContext);
             const info = gqlContext.getInfo();
             errorContext.graphQlInfo = {
                 fieldName: info.fieldName,
                 path: info.path,
             };
         }
         this.monitoringService.captureException(error, errorContext);
    }

    handleWorkerError(error: Error, { job }: { job: Job }) {
        const errorContext = {
            queueName: job.queueName,
            jobId: job.id,
        };
        this.monitoringService.captureException(error, errorContext);
    }
}
```

```ts title="Signature"
interface ErrorHandlerStrategy extends InjectableStrategy {
    handleServerError(exception: Error, context: { host: ArgumentsHost }): void | Promise<void>;
    handleWorkerError(exception: Error, context: { job: Job }): void | Promise<void>;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### handleServerError

<MemberInfo kind="method" type={`(exception: Error, context: { host: ArgumentsHost }) => void | Promise&#60;void&#62;`}   />

This method will be invoked for any error thrown during the execution of the
server.
### handleWorkerError

<MemberInfo kind="method" type={`(exception: Error, context: { job: <a href='/reference/typescript-api/job-queue/job#job'>Job</a> }) => void | Promise&#60;void&#62;`}   />

This method will be invoked for any error thrown during the execution of a
job on the worker.


</div>


---

---
title: "ErrorResultUnion"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ErrorResultUnion

<GenerationInfo sourceFile="packages/core/src/common/error/error-result.ts" sourceLine="44" packageName="@vendure/core" />

Used to construct a TypeScript return type for a query or mutation which, in the GraphQL schema,
returns a union type composed of a success result (e.g. Order) plus one or more ErrorResult
types.

Since the TypeScript entities do not correspond 1-to-1 with their GraphQL type counterparts,
we use this type to substitute them.

*Example*

```ts
type UpdateOrderItemsResult = Order | OrderModificationError | OrderLimitError | NegativeQuantityError;
type T1 = ErrorResultUnion<UpdateOrderItemsResult, VendureEntityOrder>;
// T1 = VendureEntityOrder | OrderModificationError | OrderLimitError | NegativeQuantityError;
```

```ts title="Signature"
type ErrorResultUnion<T extends GraphQLErrorResult | U, E extends VendureEntity, U = any> = | JustErrorResults<T>
    | E
```


---

---
title: "Error Types"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## InternalServerError

<GenerationInfo sourceFile="packages/core/src/common/error/errors.ts" sourceLine="14" packageName="@vendure/core" />

This error should be thrown when some unexpected and exceptional case is encountered.

```ts title="Signature"
class InternalServerError extends I18nError {
    constructor(message: string, variables: { [key: string]: string | number } = {})
}
```
* Extends: <code><a href='/reference/typescript-api/errors/i18n-error#i18nerror'>I18nError</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(message: string, variables: { [key: string]: string | number } = {}) => InternalServerError`}   />




</div>


## UserInputError

<GenerationInfo sourceFile="packages/core/src/common/error/errors.ts" sourceLine="27" packageName="@vendure/core" />

This error should be thrown when user input is not as expected.

```ts title="Signature"
class UserInputError extends I18nError {
    constructor(message: string, variables: { [key: string]: string | number } = {})
}
```
* Extends: <code><a href='/reference/typescript-api/errors/i18n-error#i18nerror'>I18nError</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(message: string, variables: { [key: string]: string | number } = {}) => UserInputError`}   />




</div>


## IllegalOperationError

<GenerationInfo sourceFile="packages/core/src/common/error/errors.ts" sourceLine="40" packageName="@vendure/core" />

This error should be thrown when an operation is attempted which is not allowed.

```ts title="Signature"
class IllegalOperationError extends I18nError {
    constructor(message: string, variables: { [key: string]: string | number } = {})
}
```
* Extends: <code><a href='/reference/typescript-api/errors/i18n-error#i18nerror'>I18nError</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(message: string, variables: { [key: string]: string | number } = {}) => IllegalOperationError`}   />




</div>


## UnauthorizedError

<GenerationInfo sourceFile="packages/core/src/common/error/errors.ts" sourceLine="53" packageName="@vendure/core" />

This error should be thrown when the user's authentication credentials do not match.

```ts title="Signature"
class UnauthorizedError extends I18nError {
    constructor()
}
```
* Extends: <code><a href='/reference/typescript-api/errors/i18n-error#i18nerror'>I18nError</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`() => UnauthorizedError`}   />




</div>


## ForbiddenError

<GenerationInfo sourceFile="packages/core/src/common/error/errors.ts" sourceLine="67" packageName="@vendure/core" />

This error should be thrown when a user attempts to access a resource which is outside of
his or her privileges.

```ts title="Signature"
class ForbiddenError extends I18nError {
    constructor(logLevel: LogLevel = LogLevel.Warn)
}
```
* Extends: <code><a href='/reference/typescript-api/errors/i18n-error#i18nerror'>I18nError</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(logLevel: <a href='/reference/typescript-api/logger/log-level#loglevel'>LogLevel</a> = LogLevel.Warn) => ForbiddenError`}   />




</div>


## ChannelNotFoundError

<GenerationInfo sourceFile="packages/core/src/common/error/errors.ts" sourceLine="81" packageName="@vendure/core" />

This error should be thrown when a <a href='/reference/typescript-api/entities/channel#channel'>Channel</a> cannot be found based on the provided
channel token.

```ts title="Signature"
class ChannelNotFoundError extends I18nError {
    constructor(token: string)
}
```
* Extends: <code><a href='/reference/typescript-api/errors/i18n-error#i18nerror'>I18nError</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(token: string) => ChannelNotFoundError`}   />




</div>


## EntityNotFoundError

<GenerationInfo sourceFile="packages/core/src/common/error/errors.ts" sourceLine="95" packageName="@vendure/core" />

This error should be thrown when an entity cannot be found in the database, i.e. no entity of
the given entityName (Product, User etc.) exists with the provided id.

```ts title="Signature"
class EntityNotFoundError extends I18nError {
    constructor(entityName: keyof typeof coreEntitiesMap | string, id: ID)
}
```
* Extends: <code><a href='/reference/typescript-api/errors/i18n-error#i18nerror'>I18nError</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(entityName: keyof typeof coreEntitiesMap | string, id: <a href='/reference/typescript-api/common/id#id'>ID</a>) => EntityNotFoundError`}   />




</div>


---

---
title: "I18nError"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## I18nError

<GenerationInfo sourceFile="packages/core/src/i18n/i18n-error.ts" sourceLine="18" packageName="@vendure/core" />

All errors thrown in the Vendure server must use or extend this error class. This allows the
error message to be translated before being served to the client.

The error messages should be provided in the form of a string key which corresponds to
a key defined in the `i18n/messages/<languageCode>.json` files.

Note that this class should not be directly used in code, but should be extended by
a more specific Error class.

```ts title="Signature"
class I18nError extends GraphQLError {
    constructor(message: string, variables: { [key: string]: string | number } = {}, code?: string, logLevel: LogLevel = LogLevel.Warn)
}
```
* Extends: <code>GraphQLError</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(message: string, variables: { [key: string]: string | number } = {}, code?: string, logLevel: <a href='/reference/typescript-api/logger/log-level#loglevel'>LogLevel</a> = LogLevel.Warn) => I18nError`}   />




</div>


---

---
title: "Errors"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "IsGraphQlErrorResult"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## isGraphQlErrorResult

<GenerationInfo sourceFile="packages/core/src/common/error/error-result.ts" sourceLine="71" packageName="@vendure/core" />

Returns true if the <a href='/reference/typescript-api/errors/error-result-union#errorresultunion'>ErrorResultUnion</a> is actually an ErrorResult type. This is useful when dealing with
certain internal service method that return an ErrorResultUnion.

*Example*

```ts
import { isGraphQlErrorResult } from '@vendure/core';

// ...

const transitionResult = await this.orderService.transitionToState(ctx, order.id, newState);
if (isGraphQlErrorResult(transitionResult)) {
    // The transition failed with an ErrorResult
    throw transitionResult;
} else {
    // TypeScript will correctly infer the type of `transitionResult` to be `Order`
    return transitionResult;
}
```

```ts title="Signature"
function isGraphQlErrorResult<T extends GraphQLErrorResult | U, U = any>(input: T): input is JustErrorResults<T>
```
Parameters

### input

<MemberInfo kind="parameter" type={`T`} />



---

---
title: "BlockingEventHandlerOptions"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## BlockingEventHandlerOptions

<GenerationInfo sourceFile="packages/core/src/event-bus/event-bus.ts" sourceLine="23" packageName="@vendure/core" since="2.2.0" />

Options for registering a blocking event handler.

```ts title="Signature"
type BlockingEventHandlerOptions<T extends VendureEvent> = {
    event: Type<T> | Array<Type<T>>;
    handler: (event: T) => void | Promise<void>;
    id: string;
    before?: string;
    after?: string;
}
```

<div className="members-wrapper">

### event

<MemberInfo kind="property" type={`Type&#60;T&#62; | Array&#60;Type&#60;T&#62;&#62;`}   />

The event type to which the handler should listen.
Can be a single event type or an array of event types.
### handler

<MemberInfo kind="property" type={`(event: T) =&#62; void | Promise&#60;void&#62;`}   />

The handler function which will be executed when the event is published.
If the handler returns a Promise, the event publishing code will wait for the Promise to resolve
before continuing. Any errors thrown by the handler will cause the event publishing code to fail.
### id

<MemberInfo kind="property" type={`string`}   />

A unique identifier for the handler. This can then be used to specify the order in which
handlers should be executed using the `before` and `after` options in other handlers.
### before

<MemberInfo kind="property" type={`string`}   />

The ID of another handler which this handler should execute before.
### after

<MemberInfo kind="property" type={`string`}   />

The ID of another handler which this handler should execute after.


</div>


---

---
title: "EventBus"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## EventBus

<GenerationInfo sourceFile="packages/core/src/event-bus/event-bus.ts" sourceLine="98" packageName="@vendure/core" />

The EventBus is used to globally publish events which can then be subscribed to.

Events are published whenever certain actions take place within the Vendure server, for example:

* when a Product is updated (<a href='/reference/typescript-api/events/event-types#productevent'>ProductEvent</a>)
* when an Order transitions state (<a href='/reference/typescript-api/events/event-types#orderstatetransitionevent'>OrderStateTransitionEvent</a>)
* when a Customer registers a new account (<a href='/reference/typescript-api/events/event-types#accountregistrationevent'>AccountRegistrationEvent</a>)

Using the EventBus it is possible to subscribe to an take action when these events occur.
This is done with the `.ofType()` method, which takes an event type and returns an rxjs observable
stream of events:

*Example*

```ts
import { OnApplicationBootstrap } from '@nestjs/common';
import { EventBus, PluginCommonModule, VendurePlugin } from '@vendure/core';
import { filter } from 'rxjs/operators';

@VendurePlugin({
    imports: [PluginCommonModule]
})
export class MyPlugin implements OnApplicationBootstrap {

  constructor(private eventBus: EventBus) {}

  async onApplicationBootstrap() {

    this.eventBus
      .ofType(OrderStateTransitionEvent)
      .pipe(
        filter(event => event.toState === 'PaymentSettled'),
      )
      .subscribe((event) => {
        // do some action when this event fires
      });
  }
}
```

```ts title="Signature"
class EventBus implements OnModuleDestroy {
    constructor(transactionSubscriber: TransactionSubscriber)
    publish(event: T) => Promise<void>;
    ofType(type: Type<T>) => Observable<T>;
    filter(predicate: (event: VendureEvent) => boolean) => Observable<T>;
    registerBlockingEventHandler(handlerOptions: BlockingEventHandlerOptions<T>) => ;
}
```
* Implements: <code>OnModuleDestroy</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(transactionSubscriber: TransactionSubscriber) => EventBus`}   />


### publish

<MemberInfo kind="method" type={`(event: T) => Promise&#60;void&#62;`}   />

Publish an event which any subscribers can react to.

*Example*

```ts
await eventBus.publish(new SomeEvent());
```
### ofType

<MemberInfo kind="method" type={`(type: Type&#60;T&#62;) => Observable&#60;T&#62;`}   />

Returns an RxJS Observable stream of events of the given type.
If the event contains a <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a> object, the subscriber
will only get called after any active database transactions are complete.

This means that the subscriber function can safely access all updated
data related to the event.
### filter

<MemberInfo kind="method" type={`(predicate: (event: <a href='/reference/typescript-api/events/vendure-event#vendureevent'>VendureEvent</a>) =&#62; boolean) => Observable&#60;T&#62;`}   />

Returns an RxJS Observable stream of events filtered by a custom predicate.
If the event contains a <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a> object, the subscriber
will only get called after any active database transactions are complete.

This means that the subscriber function can safely access all updated
data related to the event.
### registerBlockingEventHandler

<MemberInfo kind="method" type={`(handlerOptions: <a href='/reference/typescript-api/events/blocking-event-handler-options#blockingeventhandleroptions'>BlockingEventHandlerOptions</a>&#60;T&#62;) => `}  since="2.2.0"  />

Register an event handler function which will be executed when an event of the given type is published,
and will block execution of the code which published the event until the handler has completed.

This is useful when you need assurance that the event handler has successfully completed, and you want
the triggering code to fail if the handler fails.

::: warning
This API should be used with caution, as errors or performance issues in the handler can cause the
associated operation to be slow or fail entirely. For this reason, any handler which takes longer than
100ms to execute will log a warning. Any non-trivial task to be performed in a blocking event handler
should be offloaded to a background job using the <a href='/reference/typescript-api/job-queue/job-queue-service#jobqueueservice'>JobQueueService</a>.

Also, be aware that the handler will be executed in the _same database transaction_ as the code which published
the event (as long as you pass the `ctx` object from the event to any TransactionalConnection calls).
:::

*Example*

```ts
eventBus.registerBlockingEventHandler({
  event: OrderStateTransitionEvent,
  id: 'my-order-state-transition-handler',
  handler: async (event) => {
    // perform some synchronous task
  }
});
```


</div>


---

---
title: "Event Types"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## AccountRegistrationEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/account-registration-event.ts" sourceLine="13" packageName="@vendure/core" />

This event is fired when a new user registers an account, either as a stand-alone signup or after
placing an order.

```ts title="Signature"
class AccountRegistrationEvent extends VendureEvent {
    constructor(ctx: RequestContext, user: User)
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-event#vendureevent'>VendureEvent</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, user: <a href='/reference/typescript-api/entities/user#user'>User</a>) => AccountRegistrationEvent`}   />




</div>


## AccountVerifiedEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/account-verified-event.ts" sourceLine="13" packageName="@vendure/core" />

This event is fired when a users email address successfully gets verified after
the `verifyCustomerAccount` mutation was executed.

```ts title="Signature"
class AccountVerifiedEvent extends VendureEvent {
    constructor(ctx: RequestContext, customer: Customer)
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-event#vendureevent'>VendureEvent</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, customer: <a href='/reference/typescript-api/entities/customer#customer'>Customer</a>) => AccountVerifiedEvent`}   />




</div>


## AdministratorEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/administrator-event.ts" sourceLine="18" packageName="@vendure/core" since="1.4" />

This event is fired whenever a <a href='/reference/typescript-api/entities/administrator#administrator'>Administrator</a> is added, updated or deleted.

```ts title="Signature"
class AdministratorEvent extends VendureEntityEvent<Administrator, AdministratorInputTypes> {
    constructor(ctx: RequestContext, entity: Administrator, type: 'created' | 'updated' | 'deleted', input?: AdministratorInputTypes)
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-entity-event#vendureentityevent'>VendureEntityEvent</a>&#60;<a href='/reference/typescript-api/entities/administrator#administrator'>Administrator</a>, AdministratorInputTypes&#62;</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, entity: <a href='/reference/typescript-api/entities/administrator#administrator'>Administrator</a>, type: 'created' | 'updated' | 'deleted', input?: AdministratorInputTypes) => AdministratorEvent`}   />




</div>


## AssetChannelEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/asset-channel-event.ts" sourceLine="15" packageName="@vendure/core" />

This event is fired whenever an <a href='/reference/typescript-api/entities/asset#asset'>Asset</a> is assigned or removed
From a channel.

```ts title="Signature"
class AssetChannelEvent extends VendureEvent {
    constructor(ctx: RequestContext, asset: Asset, channelId: ID, type: 'assigned' | 'removed')
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-event#vendureevent'>VendureEvent</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, asset: <a href='/reference/typescript-api/entities/asset#asset'>Asset</a>, channelId: <a href='/reference/typescript-api/common/id#id'>ID</a>, type: 'assigned' | 'removed') => AssetChannelEvent`}   />




</div>


## AssetEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/asset-event.ts" sourceLine="18" packageName="@vendure/core" since="1.4" />

This event is fired whenever a <a href='/reference/typescript-api/entities/asset#asset'>Asset</a> is added, updated or deleted.

```ts title="Signature"
class AssetEvent extends VendureEntityEvent<Asset, AssetInputTypes> {
    constructor(ctx: RequestContext, entity: Asset, type: 'created' | 'updated' | 'deleted', input?: AssetInputTypes)
    asset: Asset
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-entity-event#vendureentityevent'>VendureEntityEvent</a>&#60;<a href='/reference/typescript-api/entities/asset#asset'>Asset</a>, AssetInputTypes&#62;</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, entity: <a href='/reference/typescript-api/entities/asset#asset'>Asset</a>, type: 'created' | 'updated' | 'deleted', input?: AssetInputTypes) => AssetEvent`}   />


### asset

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/asset#asset'>Asset</a>`}  since="1.4"  />




</div>


## AttemptedLoginEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/attempted-login-event.ts" sourceLine="14" packageName="@vendure/core" />

This event is fired when an attempt is made to log in via the shop or admin API `login` mutation.
The `strategy` represents the name of the AuthenticationStrategy used in the login attempt.
If the "native" strategy is used, the additional `identifier` property will be available.

```ts title="Signature"
class AttemptedLoginEvent extends VendureEvent {
    constructor(ctx: RequestContext, strategy: string, identifier?: string)
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-event#vendureevent'>VendureEvent</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, strategy: string, identifier?: string) => AttemptedLoginEvent`}   />




</div>


## ChangeChannelEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/change-channel-event.ts" sourceLine="17" packageName="@vendure/core" since="1.4" />

This event is fired whenever an <a href='/reference/typescript-api/entities/interfaces#channelaware'>ChannelAware</a> entity is assigned or removed
from a channel. The entity property contains the value before updating the channels.

```ts title="Signature"
class ChangeChannelEvent<T extends ChannelAware & VendureEntity> extends VendureEvent {
    constructor(ctx: RequestContext, entity: T, channelIds: ID[], type: 'assigned' | 'removed', entityType?: Type<T>)
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-event#vendureevent'>VendureEvent</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, entity: T, channelIds: <a href='/reference/typescript-api/common/id#id'>ID</a>[], type: 'assigned' | 'removed', entityType?: Type&#60;T&#62;) => ChangeChannelEvent`}   />




</div>


## ChannelEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/channel-event.ts" sourceLine="18" packageName="@vendure/core" since="1.4" />

This event is fired whenever a <a href='/reference/typescript-api/entities/channel#channel'>Channel</a> is added, updated or deleted.

```ts title="Signature"
class ChannelEvent extends VendureEntityEvent<Channel, ChannelInputTypes> {
    constructor(ctx: RequestContext, entity: Channel, type: 'created' | 'updated' | 'deleted', input?: ChannelInputTypes)
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-entity-event#vendureentityevent'>VendureEntityEvent</a>&#60;<a href='/reference/typescript-api/entities/channel#channel'>Channel</a>, ChannelInputTypes&#62;</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, entity: <a href='/reference/typescript-api/entities/channel#channel'>Channel</a>, type: 'created' | 'updated' | 'deleted', input?: ChannelInputTypes) => ChannelEvent`}   />




</div>


## CollectionEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/collection-event.ts" sourceLine="18" packageName="@vendure/core" since="1.4" />

This event is fired whenever a <a href='/reference/typescript-api/entities/collection#collection'>Collection</a> is added, updated or deleted.

```ts title="Signature"
class CollectionEvent extends VendureEntityEvent<Collection, CollectionInputTypes> {
    constructor(ctx: RequestContext, entity: Collection, type: 'created' | 'updated' | 'deleted', input?: CollectionInputTypes)
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-entity-event#vendureentityevent'>VendureEntityEvent</a>&#60;<a href='/reference/typescript-api/entities/collection#collection'>Collection</a>, CollectionInputTypes&#62;</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, entity: <a href='/reference/typescript-api/entities/collection#collection'>Collection</a>, type: 'created' | 'updated' | 'deleted', input?: CollectionInputTypes) => CollectionEvent`}   />




</div>


## CollectionModificationEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/collection-modification-event.ts" sourceLine="18" packageName="@vendure/core" />

This event is fired whenever a Collection is modified in some way. The `productVariantIds`
argument is an array of ids of all ProductVariants which:

1. were part of this collection prior to modification and are no longer
2. are now part of this collection after modification but were not before

```ts title="Signature"
class CollectionModificationEvent extends VendureEvent {
    constructor(ctx: RequestContext, collection: Collection, productVariantIds: ID[])
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-event#vendureevent'>VendureEvent</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, collection: <a href='/reference/typescript-api/entities/collection#collection'>Collection</a>, productVariantIds: <a href='/reference/typescript-api/common/id#id'>ID</a>[]) => CollectionModificationEvent`}   />




</div>


## CountryEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/country-event.ts" sourceLine="18" packageName="@vendure/core" since="1.4" />

This event is fired whenever a <a href='/reference/typescript-api/entities/country#country'>Country</a> is added, updated or deleted.

```ts title="Signature"
class CountryEvent extends VendureEntityEvent<Country, CountryInputTypes> {
    constructor(ctx: RequestContext, entity: Country, type: 'created' | 'updated' | 'deleted', input?: CountryInputTypes)
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-entity-event#vendureentityevent'>VendureEntityEvent</a>&#60;<a href='/reference/typescript-api/entities/country#country'>Country</a>, CountryInputTypes&#62;</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, entity: <a href='/reference/typescript-api/entities/country#country'>Country</a>, type: 'created' | 'updated' | 'deleted', input?: CountryInputTypes) => CountryEvent`}   />




</div>


## CouponCodeEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/coupon-code-event.ts" sourceLine="15" packageName="@vendure/core" since="1.4" />

This event is fired whenever an coupon code of an active <a href='/reference/typescript-api/entities/promotion#promotion'>Promotion</a>
is assigned or removed to an <a href='/reference/typescript-api/entities/order#order'>Order</a>.

```ts title="Signature"
class CouponCodeEvent extends VendureEvent {
    constructor(ctx: RequestContext, couponCode: string, orderId: ID, type: 'assigned' | 'removed')
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-event#vendureevent'>VendureEvent</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, couponCode: string, orderId: <a href='/reference/typescript-api/common/id#id'>ID</a>, type: 'assigned' | 'removed') => CouponCodeEvent`}   />




</div>


## CustomerAddressEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/customer-address-event.ts" sourceLine="22" packageName="@vendure/core" since="1.4" />

This event is fired whenever a <a href='/reference/typescript-api/entities/address#address'>Address</a> is added, updated
or deleted.

```ts title="Signature"
class CustomerAddressEvent extends VendureEntityEvent<Address, CustomerAddressInputTypes> {
    constructor(ctx: RequestContext, entity: Address, type: 'created' | 'updated' | 'deleted', input?: CustomerAddressInputTypes)
    address: Address
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-entity-event#vendureentityevent'>VendureEntityEvent</a>&#60;<a href='/reference/typescript-api/entities/address#address'>Address</a>, CustomerAddressInputTypes&#62;</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, entity: <a href='/reference/typescript-api/entities/address#address'>Address</a>, type: 'created' | 'updated' | 'deleted', input?: CustomerAddressInputTypes) => CustomerAddressEvent`}   />


### address

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/address#address'>Address</a>`}   />




</div>


## CustomerEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/customer-event.ts" sourceLine="22" packageName="@vendure/core" />

This event is fired whenever a <a href='/reference/typescript-api/entities/customer#customer'>Customer</a> is added, updated
or deleted.

```ts title="Signature"
class CustomerEvent extends VendureEntityEvent<Customer, CustomerInputTypes> {
    constructor(ctx: RequestContext, entity: Customer, type: 'created' | 'updated' | 'deleted', input?: CustomerInputTypes)
    customer: Customer
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-entity-event#vendureentityevent'>VendureEntityEvent</a>&#60;<a href='/reference/typescript-api/entities/customer#customer'>Customer</a>, CustomerInputTypes&#62;</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, entity: <a href='/reference/typescript-api/entities/customer#customer'>Customer</a>, type: 'created' | 'updated' | 'deleted', input?: CustomerInputTypes) => CustomerEvent`}   />


### customer

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/customer#customer'>Customer</a>`}  since="1.4"  />




</div>


## CustomerGroupChangeEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/customer-group-change-event.ts" sourceLine="15" packageName="@vendure/core" since="1.4" />

This event is fired whenever one or more <a href='/reference/typescript-api/entities/customer#customer'>Customer</a> is assigned to or removed from a
<a href='/reference/typescript-api/entities/customer-group#customergroup'>CustomerGroup</a>.

```ts title="Signature"
class CustomerGroupChangeEvent extends VendureEvent {
    constructor(ctx: RequestContext, customers: Customer[], customGroup: CustomerGroup, type: 'assigned' | 'removed')
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-event#vendureevent'>VendureEvent</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, customers: <a href='/reference/typescript-api/entities/customer#customer'>Customer</a>[], customGroup: <a href='/reference/typescript-api/entities/customer-group#customergroup'>CustomerGroup</a>, type: 'assigned' | 'removed') => CustomerGroupChangeEvent`}   />




</div>


## CustomerGroupEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/customer-group-event.ts" sourceLine="18" packageName="@vendure/core" since="1.4" />

This event is fired whenever a <a href='/reference/typescript-api/entities/customer-group#customergroup'>CustomerGroup</a> is added, updated or deleted.

```ts title="Signature"
class CustomerGroupEvent extends VendureEntityEvent<CustomerGroup, CustomerGroupInputTypes> {
    constructor(ctx: RequestContext, entity: CustomerGroup, type: 'created' | 'updated' | 'deleted', input?: CustomerGroupInputTypes)
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-entity-event#vendureentityevent'>VendureEntityEvent</a>&#60;<a href='/reference/typescript-api/entities/customer-group#customergroup'>CustomerGroup</a>, CustomerGroupInputTypes&#62;</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, entity: <a href='/reference/typescript-api/entities/customer-group#customergroup'>CustomerGroup</a>, type: 'created' | 'updated' | 'deleted', input?: CustomerGroupInputTypes) => CustomerGroupEvent`}   />




</div>


## FacetEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/facet-event.ts" sourceLine="18" packageName="@vendure/core" since="1.4" />

This event is fired whenever a <a href='/reference/typescript-api/entities/facet#facet'>Facet</a> is added, updated or deleted.

```ts title="Signature"
class FacetEvent extends VendureEntityEvent<Facet, FacetInputTypes> {
    constructor(ctx: RequestContext, entity: Facet, type: 'created' | 'updated' | 'deleted', input?: FacetInputTypes)
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-entity-event#vendureentityevent'>VendureEntityEvent</a>&#60;<a href='/reference/typescript-api/entities/facet#facet'>Facet</a>, FacetInputTypes&#62;</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, entity: <a href='/reference/typescript-api/entities/facet#facet'>Facet</a>, type: 'created' | 'updated' | 'deleted', input?: FacetInputTypes) => FacetEvent`}   />




</div>


## FacetValueEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/facet-value-event.ts" sourceLine="26" packageName="@vendure/core" since="1.4" />

This event is fired whenever a <a href='/reference/typescript-api/entities/facet-value#facetvalue'>FacetValue</a> is added, updated or deleted.

```ts title="Signature"
class FacetValueEvent extends VendureEntityEvent<FacetValue, FacetValueInputTypes> {
    constructor(ctx: RequestContext, entity: FacetValue, type: 'created' | 'updated' | 'deleted', input?: FacetValueInputTypes)
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-entity-event#vendureentityevent'>VendureEntityEvent</a>&#60;<a href='/reference/typescript-api/entities/facet-value#facetvalue'>FacetValue</a>, FacetValueInputTypes&#62;</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, entity: <a href='/reference/typescript-api/entities/facet-value#facetvalue'>FacetValue</a>, type: 'created' | 'updated' | 'deleted', input?: FacetValueInputTypes) => FacetValueEvent`}   />




</div>


## FulfillmentEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/fulfillment-event.ts" sourceLine="27" packageName="@vendure/core" since="1.4" />

This event is fired whenever a <a href='/reference/typescript-api/entities/fulfillment#fulfillment'>Fulfillment</a> is added. The type is always `created`.

```ts title="Signature"
class FulfillmentEvent extends VendureEntityEvent<Fulfillment, CreateFulfillmentInput> {
    constructor(ctx: RequestContext, entity: Fulfillment, input?: CreateFulfillmentInput)
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-entity-event#vendureentityevent'>VendureEntityEvent</a>&#60;<a href='/reference/typescript-api/entities/fulfillment#fulfillment'>Fulfillment</a>, CreateFulfillmentInput&#62;</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, entity: <a href='/reference/typescript-api/entities/fulfillment#fulfillment'>Fulfillment</a>, input?: CreateFulfillmentInput) => FulfillmentEvent`}   />




</div>


## FulfillmentStateTransitionEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/fulfillment-state-transition-event.ts" sourceLine="13" packageName="@vendure/core" />

This event is fired whenever an <a href='/reference/typescript-api/entities/fulfillment#fulfillment'>Fulfillment</a> transitions from one <a href='/reference/typescript-api/fulfillment/fulfillment-state#fulfillmentstate'>FulfillmentState</a> to another.

```ts title="Signature"
class FulfillmentStateTransitionEvent extends VendureEvent {
    constructor(fromState: FulfillmentState, toState: FulfillmentState, ctx: RequestContext, fulfillment: Fulfillment)
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-event#vendureevent'>VendureEvent</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(fromState: <a href='/reference/typescript-api/fulfillment/fulfillment-state#fulfillmentstate'>FulfillmentState</a>, toState: <a href='/reference/typescript-api/fulfillment/fulfillment-state#fulfillmentstate'>FulfillmentState</a>, ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, fulfillment: <a href='/reference/typescript-api/entities/fulfillment#fulfillment'>Fulfillment</a>) => FulfillmentStateTransitionEvent`}   />




</div>


## GlobalSettingsEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/global-settings-event.ts" sourceLine="16" packageName="@vendure/core" since="1.4" />

This event is fired whenever a <a href='/reference/typescript-api/entities/global-settings#globalsettings'>GlobalSettings</a> is added. The type is always `updated`, because it's
only created once and never deleted.

```ts title="Signature"
class GlobalSettingsEvent extends VendureEntityEvent<GlobalSettings, UpdateGlobalSettingsInput> {
    constructor(ctx: RequestContext, entity: GlobalSettings, input?: UpdateGlobalSettingsInput)
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-entity-event#vendureentityevent'>VendureEntityEvent</a>&#60;<a href='/reference/typescript-api/entities/global-settings#globalsettings'>GlobalSettings</a>, UpdateGlobalSettingsInput&#62;</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, entity: <a href='/reference/typescript-api/entities/global-settings#globalsettings'>GlobalSettings</a>, input?: UpdateGlobalSettingsInput) => GlobalSettingsEvent`}   />




</div>


## HistoryEntryEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/history-entry-event.ts" sourceLine="23" packageName="@vendure/core" since="1.4" />

This event is fired whenever one <a href='/reference/typescript-api/entities/history-entry#historyentry'>HistoryEntry</a> is added, updated or deleted.

```ts title="Signature"
class HistoryEntryEvent extends VendureEntityEvent<HistoryEntry, HistoryInput> {
    public readonly historyType: 'order' | 'customer' | string;
    constructor(ctx: RequestContext, entity: HistoryEntry, type: 'created' | 'updated' | 'deleted', historyType: 'order' | 'customer' | string, input?: HistoryInput)
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-entity-event#vendureentityevent'>VendureEntityEvent</a>&#60;<a href='/reference/typescript-api/entities/history-entry#historyentry'>HistoryEntry</a>, HistoryInput&#62;</code>



<div className="members-wrapper">

### historyType

<MemberInfo kind="property" type={`'order' | 'customer' | string`}   />


### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, entity: <a href='/reference/typescript-api/entities/history-entry#historyentry'>HistoryEntry</a>, type: 'created' | 'updated' | 'deleted', historyType: 'order' | 'customer' | string, input?: HistoryInput) => HistoryEntryEvent`}   />




</div>


## IdentifierChangeEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/identifier-change-event.ts" sourceLine="13" packageName="@vendure/core" />

This event is fired when a registered user successfully changes the identifier (ie email address)
associated with their account.

```ts title="Signature"
class IdentifierChangeEvent extends VendureEvent {
    constructor(ctx: RequestContext, user: User, oldIdentifier: string)
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-event#vendureevent'>VendureEvent</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, user: <a href='/reference/typescript-api/entities/user#user'>User</a>, oldIdentifier: string) => IdentifierChangeEvent`}   />




</div>


## IdentifierChangeRequestEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/identifier-change-request-event.ts" sourceLine="13" packageName="@vendure/core" />

This event is fired when a registered user requests to update the identifier (ie email address)
associated with the account.

```ts title="Signature"
class IdentifierChangeRequestEvent extends VendureEvent {
    constructor(ctx: RequestContext, user: User)
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-event#vendureevent'>VendureEvent</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, user: <a href='/reference/typescript-api/entities/user#user'>User</a>) => IdentifierChangeRequestEvent`}   />




</div>


## InitializerEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/initializer-event.ts" sourceLine="11" packageName="@vendure/core" since="1.7.0" />

This event is fired when vendure finished initializing its services inside the <a href='/reference/typescript-api/services/initializer-service#initializerservice'>InitializerService</a>

```ts title="Signature"
class InitializerEvent extends VendureEvent {
    constructor()
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-event#vendureevent'>VendureEvent</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`() => InitializerEvent`}   />




</div>


## LoginEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/login-event.ts" sourceLine="12" packageName="@vendure/core" />

This event is fired when a user successfully logs in via the shop or admin API `login` mutation.

```ts title="Signature"
class LoginEvent extends VendureEvent {
    constructor(ctx: RequestContext, user: User)
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-event#vendureevent'>VendureEvent</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, user: <a href='/reference/typescript-api/entities/user#user'>User</a>) => LoginEvent`}   />




</div>


## LogoutEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/logout-event.ts" sourceLine="12" packageName="@vendure/core" />

This event is fired when a user logs out via the shop or admin API `logout` mutation.

```ts title="Signature"
class LogoutEvent extends VendureEvent {
    constructor(ctx: RequestContext)
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-event#vendureevent'>VendureEvent</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => LogoutEvent`}   />




</div>


## OrderEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/order-event.ts" sourceLine="17" packageName="@vendure/core" />

This event is fired whenever an <a href='/reference/typescript-api/entities/order#order'>Order</a> is added, updated
or deleted.

```ts title="Signature"
class OrderEvent extends VendureEntityEvent<Order, OrderInputTypes> {
    constructor(ctx: RequestContext, order: Order, type: 'created' | 'updated' | 'deleted', input?: OrderInputTypes)
    order: Order
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-entity-event#vendureentityevent'>VendureEntityEvent</a>&#60;<a href='/reference/typescript-api/entities/order#order'>Order</a>, OrderInputTypes&#62;</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>, type: 'created' | 'updated' | 'deleted', input?: OrderInputTypes) => OrderEvent`}   />


### order

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/order#order'>Order</a>`}  since="3.4.0"  />




</div>


## OrderLineEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/order-line-event.ts" sourceLine="13" packageName="@vendure/core" />

This event is fired whenever an <a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a> is added, updated
or deleted.

```ts title="Signature"
class OrderLineEvent extends VendureEvent {
    constructor(ctx: RequestContext, order: Order, orderLine: OrderLine, type: 'created' | 'updated' | 'deleted' | 'cancelled')
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-event#vendureevent'>VendureEvent</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>, orderLine: <a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a>, type: 'created' | 'updated' | 'deleted' | 'cancelled') => OrderLineEvent`}   />




</div>


## OrderPlacedEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/order-placed-event.ts" sourceLine="17" packageName="@vendure/core" />

This event is fired whenever an <a href='/reference/typescript-api/entities/order#order'>Order</a> is set as "placed", which by default is
when it transitions from 'ArrangingPayment' to either 'PaymentAuthorized' or 'PaymentSettled'.

Note that the exact point that it is set as "placed" can be configured according to the
<a href='/reference/typescript-api/orders/order-placed-strategy#orderplacedstrategy'>OrderPlacedStrategy</a>.

```ts title="Signature"
class OrderPlacedEvent extends VendureEvent {
    constructor(fromState: OrderState, toState: OrderState, ctx: RequestContext, order: Order)
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-event#vendureevent'>VendureEvent</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(fromState: <a href='/reference/typescript-api/orders/order-process#orderstate'>OrderState</a>, toState: <a href='/reference/typescript-api/orders/order-process#orderstate'>OrderState</a>, ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>) => OrderPlacedEvent`}   />




</div>


## OrderStateTransitionEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/order-state-transition-event.ts" sourceLine="13" packageName="@vendure/core" />

This event is fired whenever an <a href='/reference/typescript-api/entities/order#order'>Order</a> transitions from one <a href='/reference/typescript-api/orders/order-process#orderstate'>OrderState</a> to another.

```ts title="Signature"
class OrderStateTransitionEvent extends VendureEvent {
    constructor(fromState: OrderState, toState: OrderState, ctx: RequestContext, order: Order)
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-event#vendureevent'>VendureEvent</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(fromState: <a href='/reference/typescript-api/orders/order-process#orderstate'>OrderState</a>, toState: <a href='/reference/typescript-api/orders/order-process#orderstate'>OrderState</a>, ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>) => OrderStateTransitionEvent`}   />




</div>


## PasswordResetEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/password-reset-event.ts" sourceLine="12" packageName="@vendure/core" />

This event is fired when a Customer requests a password reset email.

```ts title="Signature"
class PasswordResetEvent extends VendureEvent {
    constructor(ctx: RequestContext, user: User)
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-event#vendureevent'>VendureEvent</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, user: <a href='/reference/typescript-api/entities/user#user'>User</a>) => PasswordResetEvent`}   />




</div>


## PasswordResetVerifiedEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/password-reset-verified-event.ts" sourceLine="13" packageName="@vendure/core" since="1.4" />

This event is fired when a password reset is executed with a verified token.

```ts title="Signature"
class PasswordResetVerifiedEvent extends VendureEvent {
    constructor(ctx: RequestContext, user: User)
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-event#vendureevent'>VendureEvent</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, user: <a href='/reference/typescript-api/entities/user#user'>User</a>) => PasswordResetVerifiedEvent`}   />




</div>


## PaymentMethodEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/payment-method-event.ts" sourceLine="18" packageName="@vendure/core" />

This event is fired whenever a <a href='/reference/typescript-api/entities/payment-method#paymentmethod'>PaymentMethod</a> is added, updated
or deleted.

```ts title="Signature"
class PaymentMethodEvent extends VendureEntityEvent<PaymentMethod, PaymentMethodInputTypes> {
    constructor(ctx: RequestContext, entity: PaymentMethod, type: 'created' | 'updated' | 'deleted', input?: PaymentMethodInputTypes)
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-entity-event#vendureentityevent'>VendureEntityEvent</a>&#60;<a href='/reference/typescript-api/entities/payment-method#paymentmethod'>PaymentMethod</a>, PaymentMethodInputTypes&#62;</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, entity: <a href='/reference/typescript-api/entities/payment-method#paymentmethod'>PaymentMethod</a>, type: 'created' | 'updated' | 'deleted', input?: PaymentMethodInputTypes) => PaymentMethodEvent`}   />




</div>


## PaymentStateTransitionEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/payment-state-transition-event.ts" sourceLine="15" packageName="@vendure/core" />

This event is fired whenever a <a href='/reference/typescript-api/entities/payment#payment'>Payment</a> transitions from one <a href='/reference/typescript-api/payment/payment-state#paymentstate'>PaymentState</a> to another, e.g.
a Payment is authorized by the payment provider.

```ts title="Signature"
class PaymentStateTransitionEvent extends VendureEvent {
    constructor(fromState: PaymentState, toState: PaymentState, ctx: RequestContext, payment: Payment, order: Order)
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-event#vendureevent'>VendureEvent</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(fromState: <a href='/reference/typescript-api/payment/payment-state#paymentstate'>PaymentState</a>, toState: <a href='/reference/typescript-api/payment/payment-state#paymentstate'>PaymentState</a>, ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, payment: <a href='/reference/typescript-api/entities/payment#payment'>Payment</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>) => PaymentStateTransitionEvent`}   />




</div>


## ProductChannelEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/product-channel-event.ts" sourceLine="15" packageName="@vendure/core" />

This event is fired whenever a <a href='/reference/typescript-api/entities/product#product'>Product</a> is added, updated
or deleted.

```ts title="Signature"
class ProductChannelEvent extends VendureEvent {
    constructor(ctx: RequestContext, product: Product, channelId: ID, type: 'assigned' | 'removed')
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-event#vendureevent'>VendureEvent</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, product: <a href='/reference/typescript-api/entities/product#product'>Product</a>, channelId: <a href='/reference/typescript-api/common/id#id'>ID</a>, type: 'assigned' | 'removed') => ProductChannelEvent`}   />




</div>


## ProductEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/product-event.ts" sourceLine="18" packageName="@vendure/core" />

This event is fired whenever a <a href='/reference/typescript-api/entities/product#product'>Product</a> is added, updated
or deleted.

```ts title="Signature"
class ProductEvent extends VendureEntityEvent<Product, ProductInputTypes> {
    constructor(ctx: RequestContext, entity: Product, type: 'created' | 'updated' | 'deleted', input?: ProductInputTypes)
    product: Product
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-entity-event#vendureentityevent'>VendureEntityEvent</a>&#60;<a href='/reference/typescript-api/entities/product#product'>Product</a>, ProductInputTypes&#62;</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, entity: <a href='/reference/typescript-api/entities/product#product'>Product</a>, type: 'created' | 'updated' | 'deleted', input?: ProductInputTypes) => ProductEvent`}   />


### product

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/product#product'>Product</a>`}  since="1.4"  />




</div>


## ProductOptionEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/product-option-event.ts" sourceLine="26" packageName="@vendure/core" since="1.4" />

This event is fired whenever a <a href='/reference/typescript-api/entities/product-option#productoption'>ProductOption</a> is added or updated.

```ts title="Signature"
class ProductOptionEvent extends VendureEntityEvent<ProductOption, ProductOptionInputTypes> {
    constructor(ctx: RequestContext, entity: ProductOption, type: 'created' | 'updated' | 'deleted', input?: ProductOptionInputTypes)
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-entity-event#vendureentityevent'>VendureEntityEvent</a>&#60;<a href='/reference/typescript-api/entities/product-option#productoption'>ProductOption</a>, ProductOptionInputTypes&#62;</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, entity: <a href='/reference/typescript-api/entities/product-option#productoption'>ProductOption</a>, type: 'created' | 'updated' | 'deleted', input?: ProductOptionInputTypes) => ProductOptionEvent`}   />




</div>


## ProductOptionGroupChangeEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/product-option-group-change-event.ts" sourceLine="15" packageName="@vendure/core" since="1.4" />

This event is fired whenever a <a href='/reference/typescript-api/entities/product-option-group#productoptiongroup'>ProductOptionGroup</a> is assigned or removed from a <a href='/reference/typescript-api/entities/product#product'>Product</a>.

```ts title="Signature"
class ProductOptionGroupChangeEvent extends VendureEvent {
    constructor(ctx: RequestContext, product: Product, optionGroupId: ID, type: 'assigned' | 'removed')
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-event#vendureevent'>VendureEvent</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, product: <a href='/reference/typescript-api/entities/product#product'>Product</a>, optionGroupId: <a href='/reference/typescript-api/common/id#id'>ID</a>, type: 'assigned' | 'removed') => ProductOptionGroupChangeEvent`}   />




</div>


## ProductOptionGroupEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/product-option-group-event.ts" sourceLine="24" packageName="@vendure/core" since="1.4" />

This event is fired whenever a <a href='/reference/typescript-api/entities/product-option-group#productoptiongroup'>ProductOptionGroup</a> is added or updated.

```ts title="Signature"
class ProductOptionGroupEvent extends VendureEntityEvent<
    ProductOptionGroup,
    ProductOptionGroupInputTypes
> {
    constructor(ctx: RequestContext, entity: ProductOptionGroup, type: 'created' | 'updated' | 'deleted', input?: ProductOptionGroupInputTypes)
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-entity-event#vendureentityevent'>VendureEntityEvent</a>&#60;     <a href='/reference/typescript-api/entities/product-option-group#productoptiongroup'>ProductOptionGroup</a>,     ProductOptionGroupInputTypes &#62;</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, entity: <a href='/reference/typescript-api/entities/product-option-group#productoptiongroup'>ProductOptionGroup</a>, type: 'created' | 'updated' | 'deleted', input?: ProductOptionGroupInputTypes) => ProductOptionGroupEvent`}   />




</div>


## ProductVariantChannelEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/product-variant-channel-event.ts" sourceLine="14" packageName="@vendure/core" />

This event is fired whenever a <a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a> is assigned or removed from a <a href='/reference/typescript-api/entities/channel#channel'>Channel</a>.

```ts title="Signature"
class ProductVariantChannelEvent extends VendureEvent {
    constructor(ctx: RequestContext, productVariant: ProductVariant, channelId: ID, type: 'assigned' | 'removed')
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-event#vendureevent'>VendureEvent</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, productVariant: <a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>, channelId: <a href='/reference/typescript-api/common/id#id'>ID</a>, type: 'assigned' | 'removed') => ProductVariantChannelEvent`}   />




</div>


## ProductVariantEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/product-variant-event.ts" sourceLine="18" packageName="@vendure/core" />

This event is fired whenever a <a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a> is added, updated
or deleted.

```ts title="Signature"
class ProductVariantEvent extends VendureEntityEvent<ProductVariant[], ProductVariantInputTypes> {
    constructor(ctx: RequestContext, entity: ProductVariant[], type: 'created' | 'updated' | 'deleted', input?: ProductVariantInputTypes)
    variants: ProductVariant[]
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-entity-event#vendureentityevent'>VendureEntityEvent</a>&#60;<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>[], ProductVariantInputTypes&#62;</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, entity: <a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>[], type: 'created' | 'updated' | 'deleted', input?: ProductVariantInputTypes) => ProductVariantEvent`}   />


### variants

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>[]`}  since="1.4"  />




</div>


## ProductVariantPriceEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/product-variant-price-event.ts" sourceLine="17" packageName="@vendure/core" since="2.2.0" />

This event is fired whenever a <a href='/reference/typescript-api/entities/product-variant-price#productvariantprice'>ProductVariantPrice</a> is added, updated or deleted.

```ts title="Signature"
class ProductVariantPriceEvent extends VendureEntityEvent<
    ProductVariantPrice[],
    ProductVariantInputTypes
> {
    constructor(ctx: RequestContext, entity: ProductVariantPrice[], type: 'created' | 'updated' | 'deleted', input?: ProductVariantInputTypes)
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-entity-event#vendureentityevent'>VendureEntityEvent</a>&#60;     <a href='/reference/typescript-api/entities/product-variant-price#productvariantprice'>ProductVariantPrice</a>[],     ProductVariantInputTypes &#62;</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, entity: <a href='/reference/typescript-api/entities/product-variant-price#productvariantprice'>ProductVariantPrice</a>[], type: 'created' | 'updated' | 'deleted', input?: ProductVariantInputTypes) => ProductVariantPriceEvent`}   />




</div>


## PromotionEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/promotion-event.ts" sourceLine="18" packageName="@vendure/core" />

This event is fired whenever a <a href='/reference/typescript-api/entities/promotion#promotion'>Promotion</a> is added, updated
or deleted.

```ts title="Signature"
class PromotionEvent extends VendureEntityEvent<Promotion, PromotionInputTypes> {
    constructor(ctx: RequestContext, entity: Promotion, type: 'created' | 'updated' | 'deleted', input?: PromotionInputTypes)
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-entity-event#vendureentityevent'>VendureEntityEvent</a>&#60;<a href='/reference/typescript-api/entities/promotion#promotion'>Promotion</a>, PromotionInputTypes&#62;</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, entity: <a href='/reference/typescript-api/entities/promotion#promotion'>Promotion</a>, type: 'created' | 'updated' | 'deleted', input?: PromotionInputTypes) => PromotionEvent`}   />




</div>


## ProvinceEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/province-event.ts" sourceLine="18" packageName="@vendure/core" since="2.0" />

This event is fired whenever a <a href='/reference/typescript-api/entities/province#province'>Province</a> is added, updated or deleted.

```ts title="Signature"
class ProvinceEvent extends VendureEntityEvent<Province, ProvinceInputTypes> {
    constructor(ctx: RequestContext, entity: Province, type: 'created' | 'updated' | 'deleted', input?: ProvinceInputTypes)
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-entity-event#vendureentityevent'>VendureEntityEvent</a>&#60;<a href='/reference/typescript-api/entities/province#province'>Province</a>, ProvinceInputTypes&#62;</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, entity: <a href='/reference/typescript-api/entities/province#province'>Province</a>, type: 'created' | 'updated' | 'deleted', input?: ProvinceInputTypes) => ProvinceEvent`}   />




</div>


## RefundEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/refund-event.ts" sourceLine="12" packageName="@vendure/core" />

This event is fired whenever a <a href='/reference/typescript-api/entities/refund#refund'>Refund</a> is created

```ts title="Signature"
class RefundEvent extends VendureEvent {
    constructor(ctx: RequestContext, order: Order, refund: Refund, type: 'created')
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-event#vendureevent'>VendureEvent</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>, refund: <a href='/reference/typescript-api/entities/refund#refund'>Refund</a>, type: 'created') => RefundEvent`}   />




</div>


## RefundStateTransitionEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/refund-state-transition-event.ts" sourceLine="14" packageName="@vendure/core" />

This event is fired whenever a <a href='/reference/typescript-api/entities/refund#refund'>Refund</a> transitions from one <a href='/reference/typescript-api/payment/refund-state#refundstate'>RefundState</a> to another.

```ts title="Signature"
class RefundStateTransitionEvent extends VendureEvent {
    constructor(fromState: RefundState, toState: RefundState, ctx: RequestContext, refund: Refund, order: Order)
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-event#vendureevent'>VendureEvent</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(fromState: <a href='/reference/typescript-api/payment/refund-state#refundstate'>RefundState</a>, toState: <a href='/reference/typescript-api/payment/refund-state#refundstate'>RefundState</a>, ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, refund: <a href='/reference/typescript-api/entities/refund#refund'>Refund</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>) => RefundStateTransitionEvent`}   />




</div>


## RoleChangeEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/role-change-event.ts" sourceLine="16" packageName="@vendure/core" since="1.4" />

This event is fired whenever one <a href='/reference/typescript-api/entities/role#role'>Role</a> is assigned or removed from a user.
The property `roleIds` only contains the removed or assigned role ids.

```ts title="Signature"
class RoleChangeEvent extends VendureEvent {
    constructor(ctx: RequestContext, admin: Administrator, roleIds: ID[], type: 'assigned' | 'removed')
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-event#vendureevent'>VendureEvent</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, admin: <a href='/reference/typescript-api/entities/administrator#administrator'>Administrator</a>, roleIds: <a href='/reference/typescript-api/common/id#id'>ID</a>[], type: 'assigned' | 'removed') => RoleChangeEvent`}   />




</div>


## RoleEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/role-event.ts" sourceLine="18" packageName="@vendure/core" since="1.4" />

This event is fired whenever one <a href='/reference/typescript-api/entities/role#role'>Role</a> is added, updated or deleted.

```ts title="Signature"
class RoleEvent extends VendureEntityEvent<Role, RoleInputTypes> {
    constructor(ctx: RequestContext, entity: Role, type: 'created' | 'updated' | 'deleted', input?: RoleInputTypes)
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-entity-event#vendureentityevent'>VendureEntityEvent</a>&#60;<a href='/reference/typescript-api/entities/role#role'>Role</a>, RoleInputTypes&#62;</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, entity: <a href='/reference/typescript-api/entities/role#role'>Role</a>, type: 'created' | 'updated' | 'deleted', input?: RoleInputTypes) => RoleEvent`}   />




</div>


## SearchEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/search-event.ts" sourceLine="18" packageName="@vendure/core" since="1.6.0" />

This event is fired whenever a search query is executed.

```ts title="Signature"
class SearchEvent extends VendureEvent {
    constructor(ctx: RequestContext, input: ExtendedSearchInput)
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-event#vendureevent'>VendureEvent</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: ExtendedSearchInput) => SearchEvent`}   />




</div>


## SellerEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/seller-event.ts" sourceLine="19" packageName="@vendure/core" since="2.0.1" />

This event is fired whenever one <a href='/reference/typescript-api/entities/seller#seller'>Seller</a> is added, updated or deleted.

```ts title="Signature"
class SellerEvent extends VendureEntityEvent<Seller, SellerInputTypes> {
    constructor(ctx: RequestContext, entity: Seller, type: 'created' | 'updated' | 'deleted', input?: SellerInputTypes)
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-entity-event#vendureentityevent'>VendureEntityEvent</a>&#60;<a href='/reference/typescript-api/entities/seller#seller'>Seller</a>, SellerInputTypes&#62;</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, entity: <a href='/reference/typescript-api/entities/seller#seller'>Seller</a>, type: 'created' | 'updated' | 'deleted', input?: SellerInputTypes) => SellerEvent`}   />




</div>


## ShippingMethodEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/shipping-method-event.ts" sourceLine="18" packageName="@vendure/core" />

This event is fired whenever a <a href='/reference/typescript-api/entities/shipping-method#shippingmethod'>ShippingMethod</a> is added, updated
or deleted.

```ts title="Signature"
class ShippingMethodEvent extends VendureEntityEvent<ShippingMethod, ShippingMethodInputTypes> {
    constructor(ctx: RequestContext, entity: ShippingMethod, type: 'created' | 'updated' | 'deleted', input?: ShippingMethodInputTypes)
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-entity-event#vendureentityevent'>VendureEntityEvent</a>&#60;<a href='/reference/typescript-api/entities/shipping-method#shippingmethod'>ShippingMethod</a>, ShippingMethodInputTypes&#62;</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, entity: <a href='/reference/typescript-api/entities/shipping-method#shippingmethod'>ShippingMethod</a>, type: 'created' | 'updated' | 'deleted', input?: ShippingMethodInputTypes) => ShippingMethodEvent`}   />




</div>


## StockLocationEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/stock-location-event.ts" sourceLine="18" packageName="@vendure/core" />

This event is fired whenever a <a href='/reference/typescript-api/entities/stock-location#stocklocation'>StockLocation</a> is added, updated
or deleted.

```ts title="Signature"
class StockLocationEvent extends VendureEntityEvent<StockLocation, StockLocationInputTypes> {
    constructor(ctx: RequestContext, entity: StockLocation, type: 'created' | 'updated' | 'deleted', input?: StockLocationInputTypes)
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-entity-event#vendureentityevent'>VendureEntityEvent</a>&#60;<a href='/reference/typescript-api/entities/stock-location#stocklocation'>StockLocation</a>, StockLocationInputTypes&#62;</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, entity: <a href='/reference/typescript-api/entities/stock-location#stocklocation'>StockLocation</a>, type: 'created' | 'updated' | 'deleted', input?: StockLocationInputTypes) => StockLocationEvent`}   />




</div>


## StockMovementEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/stock-movement-event.ts" sourceLine="16" packageName="@vendure/core" since="1.1.0" />

This event is fired whenever a <a href='/reference/typescript-api/entities/stock-movement#stockmovement'>StockMovement</a> entity is created, which occurs when the saleable
stock level of a ProductVariant is altered due to things like sales, manual adjustments, and cancellations.

```ts title="Signature"
class StockMovementEvent extends VendureEvent {
    public readonly type: StockMovementType;
    constructor(ctx: RequestContext, stockMovements: StockMovement[])
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-event#vendureevent'>VendureEvent</a></code>



<div className="members-wrapper">

### type

<MemberInfo kind="property" type={`StockMovementType`}   />


### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, stockMovements: <a href='/reference/typescript-api/entities/stock-movement#stockmovement'>StockMovement</a>[]) => StockMovementEvent`}   />




</div>


## TaxCategoryEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/tax-category-event.ts" sourceLine="18" packageName="@vendure/core" />

This event is fired whenever a <a href='/reference/typescript-api/entities/tax-category#taxcategory'>TaxCategory</a> is added, updated
or deleted.

```ts title="Signature"
class TaxCategoryEvent extends VendureEntityEvent<TaxCategory, TaxCategoryInputTypes> {
    constructor(ctx: RequestContext, entity: TaxCategory, type: 'created' | 'updated' | 'deleted', input?: TaxCategoryInputTypes)
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-entity-event#vendureentityevent'>VendureEntityEvent</a>&#60;<a href='/reference/typescript-api/entities/tax-category#taxcategory'>TaxCategory</a>, TaxCategoryInputTypes&#62;</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, entity: <a href='/reference/typescript-api/entities/tax-category#taxcategory'>TaxCategory</a>, type: 'created' | 'updated' | 'deleted', input?: TaxCategoryInputTypes) => TaxCategoryEvent`}   />




</div>


## TaxRateEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/tax-rate-event.ts" sourceLine="18" packageName="@vendure/core" />

This event is fired whenever a <a href='/reference/typescript-api/entities/tax-rate#taxrate'>TaxRate</a> is added, updated
or deleted.

```ts title="Signature"
class TaxRateEvent extends VendureEntityEvent<TaxRate, TaxRateInputTypes> {
    constructor(ctx: RequestContext, entity: TaxRate, type: 'created' | 'updated' | 'deleted', input?: TaxRateInputTypes)
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-entity-event#vendureentityevent'>VendureEntityEvent</a>&#60;<a href='/reference/typescript-api/entities/tax-rate#taxrate'>TaxRate</a>, TaxRateInputTypes&#62;</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, entity: <a href='/reference/typescript-api/entities/tax-rate#taxrate'>TaxRate</a>, type: 'created' | 'updated' | 'deleted', input?: TaxRateInputTypes) => TaxRateEvent`}   />




</div>


## TaxRateModificationEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/tax-rate-modification-event.ts" sourceLine="13" packageName="@vendure/core" />

This event is fired whenever a TaxRate is changed

```ts title="Signature"
class TaxRateModificationEvent extends VendureEvent {
    constructor(ctx: RequestContext, taxRate: TaxRate)
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-event#vendureevent'>VendureEvent</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, taxRate: <a href='/reference/typescript-api/entities/tax-rate#taxrate'>TaxRate</a>) => TaxRateModificationEvent`}   />




</div>


## ZoneEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/zone-event.ts" sourceLine="18" packageName="@vendure/core" />

This event is fired whenever a <a href='/reference/typescript-api/entities/zone#zone'>Zone</a> is added, updated
or deleted.

```ts title="Signature"
class ZoneEvent extends VendureEntityEvent<Zone, ZoneInputTypes> {
    constructor(ctx: RequestContext, entity: Zone, type: 'created' | 'updated' | 'deleted', input?: ZoneInputTypes)
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-entity-event#vendureentityevent'>VendureEntityEvent</a>&#60;<a href='/reference/typescript-api/entities/zone#zone'>Zone</a>, ZoneInputTypes&#62;</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, entity: <a href='/reference/typescript-api/entities/zone#zone'>Zone</a>, type: 'created' | 'updated' | 'deleted', input?: ZoneInputTypes) => ZoneEvent`}   />




</div>


## ZoneMembersEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/events/zone-members-event.ts" sourceLine="15" packageName="@vendure/core" />

This event is fired whenever a <a href='/reference/typescript-api/entities/zone#zone'>Zone</a> gets <a href='/reference/typescript-api/entities/country#country'>Country</a> members assigned or removed
The `entity` property contains the zone with the already updated member field.

```ts title="Signature"
class ZoneMembersEvent extends VendureEvent {
    constructor(ctx: RequestContext, entity: Zone, type: 'assigned' | 'removed', memberIds: ID[])
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-event#vendureevent'>VendureEvent</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, entity: <a href='/reference/typescript-api/entities/zone#zone'>Zone</a>, type: 'assigned' | 'removed', memberIds: <a href='/reference/typescript-api/common/id#id'>ID</a>[]) => ZoneMembersEvent`}   />




</div>


---

---
title: "Events"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "VendureEntityEvent"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## VendureEntityEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/vendure-entity-event.ts" sourceLine="12" packageName="@vendure/core" />

The base class for all entity events used by the EventBus system.
* For event type `'deleted'` the input will most likely be an `id: ID`

```ts title="Signature"
class VendureEntityEvent<Entity, Input = any> extends VendureEvent {
    public readonly entity: Entity;
    public readonly type: 'created' | 'updated' | 'deleted';
    public readonly ctx: RequestContext;
    public readonly input?: Input;
    constructor(entity: Entity, type: 'created' | 'updated' | 'deleted', ctx: RequestContext, input?: Input)
}
```
* Extends: <code><a href='/reference/typescript-api/events/vendure-event#vendureevent'>VendureEvent</a></code>



<div className="members-wrapper">

### entity

<MemberInfo kind="property" type={`Entity`}   />


### type

<MemberInfo kind="property" type={`'created' | 'updated' | 'deleted'`}   />


### ctx

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>`}   />


### input

<MemberInfo kind="property" type={`Input`}   />


### constructor

<MemberInfo kind="method" type={`(entity: Entity, type: 'created' | 'updated' | 'deleted', ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input?: Input) => VendureEntityEvent`}   />




</div>


---

---
title: "VendureEvent"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## VendureEvent

<GenerationInfo sourceFile="packages/core/src/event-bus/vendure-event.ts" sourceLine="7" packageName="@vendure/core" />

The base class for all events used by the EventBus system.

```ts title="Signature"
class VendureEvent {
    public readonly createdAt: Date;
    constructor()
}
```

<div className="members-wrapper">

### createdAt

<MemberInfo kind="property" type={`Date`}   />


### constructor

<MemberInfo kind="method" type={`() => VendureEvent`}   />




</div>


---

---
title: "FulfillmentHandler"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## FulfillmentHandler

<GenerationInfo sourceFile="packages/core/src/config/fulfillment/fulfillment-handler.ts" sourceLine="149" packageName="@vendure/core" />

A FulfillmentHandler is used when creating a new <a href='/reference/typescript-api/entities/fulfillment#fulfillment'>Fulfillment</a>. When the `addFulfillmentToOrder` mutation
is executed, the specified handler will be used and it's `createFulfillment` method is called. This method
may perform async tasks such as calling a 3rd-party shipping API to register a new shipment and receive
a tracking code. This data can then be returned and will be incorporated into the created Fulfillment.

If the `args` property is defined, this means that arguments passed to the `addFulfillmentToOrder` mutation
will be passed through to the `createFulfillment` method as the last argument.

*Example*

```ts
let shipomatic;

export const shipomaticFulfillmentHandler = new FulfillmentHandler({
  code: 'ship-o-matic',
  description: [{
    languageCode: LanguageCode.en,
    value: 'Generate tracking codes via the Ship-o-matic API'
  }],

  args: {
    preferredService: {
      type: 'string',
      ui: {
        component: 'select-form-input',
        options: [
          { value: 'first_class' },
          { value: 'priority'},
          { value: 'standard' },
        ],
      },
    }
  },

  init: () => {
    // some imaginary shipping service
    shipomatic = new ShipomaticClient(API_KEY);
  },

  createFulfillment: async (ctx, orders, lines, args) => {

     const shipment = getShipmentFromOrders(orders, lines);

     try {
       const transaction = await shipomatic.transaction.create({
         shipment,
         service_level: args.preferredService,
         label_file_type: 'png',
       })

       return {
         method: `Ship-o-matic ${args.preferredService}`,
         trackingCode: transaction.tracking_code,
         customFields: {
           shippingTransactionId: transaction.id,
         }
       };
     } catch (e: any) {
       // Errors thrown from within this function will
       // result in a CreateFulfillmentError being returned
       throw e;
     }
  },

  onFulfillmentTransition: async (fromState, toState, { fulfillment }) => {
    if (toState === 'Cancelled') {
      await shipomatic.transaction.cancel({
        transaction_id: fulfillment.customFields.shippingTransactionId,
      });
    }
  }
});
```

```ts title="Signature"
class FulfillmentHandler<T extends ConfigArgs = ConfigArgs> extends ConfigurableOperationDef<T> {
    constructor(config: FulfillmentHandlerConfig<T>)
}
```
* Extends: <code><a href='/reference/typescript-api/configurable-operation-def/#configurableoperationdef'>ConfigurableOperationDef</a>&#60;T&#62;</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(config: <a href='/reference/typescript-api/fulfillment/fulfillment-handler#fulfillmenthandlerconfig'>FulfillmentHandlerConfig</a>&#60;T&#62;) => FulfillmentHandler`}   />




</div>


## FulfillmentHandlerConfig

<GenerationInfo sourceFile="packages/core/src/config/fulfillment/fulfillment-handler.ts" sourceLine="48" packageName="@vendure/core" />

The configuration object used to instantiate a <a href='/reference/typescript-api/fulfillment/fulfillment-handler#fulfillmenthandler'>FulfillmentHandler</a>.

```ts title="Signature"
interface FulfillmentHandlerConfig<T extends ConfigArgs> extends ConfigurableOperationDefOptions<T> {
    createFulfillment: CreateFulfillmentFn<T>;
    onFulfillmentTransition?: OnTransitionStartFn<FulfillmentState, FulfillmentTransitionData>;
}
```
* Extends: <code><a href='/reference/typescript-api/configurable-operation-def/configurable-operation-def-options#configurableoperationdefoptions'>ConfigurableOperationDefOptions</a>&#60;T&#62;</code>



<div className="members-wrapper">

### createFulfillment

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/fulfillment/fulfillment-handler#createfulfillmentfn'>CreateFulfillmentFn</a>&#60;T&#62;`}   />

Invoked when the `addFulfillmentToOrder` mutation is executed with this handler selected.

If an Error is thrown from within this function, no Fulfillment is created and the `CreateFulfillmentError`
result will be returned.
### onFulfillmentTransition

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/state-machine/state-machine-config#ontransitionstartfn'>OnTransitionStartFn</a>&#60;<a href='/reference/typescript-api/fulfillment/fulfillment-state#fulfillmentstate'>FulfillmentState</a>, <a href='/reference/typescript-api/fulfillment/fulfillment-transition-data#fulfillmenttransitiondata'>FulfillmentTransitionData</a>&#62;`}   />

This allows the handler to intercept state transitions of the created Fulfillment. This works much in the
same way as the <a href='/reference/typescript-api/fulfillment/fulfillment-process#fulfillmentprocess'>FulfillmentProcess</a> `onTransitionStart` method (i.e. returning `false` or
`string` will be interpreted as an error and prevent the state transition), except that it is only invoked
on Fulfillments which were created with this particular FulfillmentHandler.

It can be useful e.g. to intercept Fulfillment cancellations and relay that information to a 3rd-party
shipping API.


</div>


## CreateFulfillmentFn

<GenerationInfo sourceFile="packages/core/src/config/fulfillment/fulfillment-handler.ts" sourceLine="33" packageName="@vendure/core" />

The function called when creating a new Fulfillment

```ts title="Signature"
type CreateFulfillmentFn<T extends ConfigArgs> = (
    ctx: RequestContext,
    orders: Order[],
    lines: OrderLineInput[],
    args: ConfigArgValues<T>,
) => CreateFulfillmentResult | Promise<CreateFulfillmentResult>
```


## CreateFulfillmentResult

<GenerationInfo sourceFile="packages/core/src/config/fulfillment/fulfillment-handler.ts" sourceLine="23" packageName="@vendure/core" />



```ts title="Signature"
type CreateFulfillmentResult = Partial<Pick<Fulfillment, 'trackingCode' | 'method' | 'customFields'>>
```


---

---
title: "FulfillmentProcess"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## defaultFulfillmentProcess

<GenerationInfo sourceFile="packages/core/src/config/fulfillment/default-fulfillment-process.ts" sourceLine="45" packageName="@vendure/core" since="2.0.0" />

The default <a href='/reference/typescript-api/fulfillment/fulfillment-process#fulfillmentprocess'>FulfillmentProcess</a>. This process includes the following actions:

- Executes the configured `FulfillmentHandler.onFulfillmentTransition()` before any state
  transition.
- On cancellation of a Fulfillment, creates the necessary <a href='/reference/typescript-api/entities/stock-movement#cancellation'>Cancellation</a> & <a href='/reference/typescript-api/entities/stock-movement#allocation'>Allocation</a>
  stock movement records.
- When a Fulfillment transitions from the `Created` to `Pending` state, the necessary
  <a href='/reference/typescript-api/entities/stock-movement#sale'>Sale</a> stock movements are created.



## FulfillmentProcess

<GenerationInfo sourceFile="packages/core/src/config/fulfillment/fulfillment-process.ts" sourceLine="26" packageName="@vendure/core" since="2.0.0" />

A FulfillmentProcess is used to define the way the fulfillment process works as in: what states a Fulfillment can be
in, and how it may transition from one state to another. Using the `onTransitionStart()` hook, a
FulfillmentProcess can perform checks before allowing a state transition to occur, and the `onTransitionEnd()`
hook allows logic to be executed after a state change.

For detailed description of the interface members, see the <a href='/reference/typescript-api/state-machine/state-machine-config#statemachineconfig'>StateMachineConfig</a> docs.

```ts title="Signature"
interface FulfillmentProcess<State extends keyof CustomFulfillmentStates | string> extends InjectableStrategy {
    transitions?: Transitions<State, State | FulfillmentState> &
        Partial<Transitions<FulfillmentState | State>>;
    onTransitionStart?: OnTransitionStartFn<State | FulfillmentState, FulfillmentTransitionData>;
    onTransitionEnd?: OnTransitionEndFn<State | FulfillmentState, FulfillmentTransitionData>;
    onTransitionError?: OnTransitionErrorFn<State | FulfillmentState>;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### transitions

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/state-machine/transitions#transitions'>Transitions</a>&#60;State, State | <a href='/reference/typescript-api/fulfillment/fulfillment-state#fulfillmentstate'>FulfillmentState</a>&#62; &#38;         Partial&#60;<a href='/reference/typescript-api/state-machine/transitions#transitions'>Transitions</a>&#60;<a href='/reference/typescript-api/fulfillment/fulfillment-state#fulfillmentstate'>FulfillmentState</a> | State&#62;&#62;`}   />


### onTransitionStart

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/state-machine/state-machine-config#ontransitionstartfn'>OnTransitionStartFn</a>&#60;State | <a href='/reference/typescript-api/fulfillment/fulfillment-state#fulfillmentstate'>FulfillmentState</a>, <a href='/reference/typescript-api/fulfillment/fulfillment-transition-data#fulfillmenttransitiondata'>FulfillmentTransitionData</a>&#62;`}   />


### onTransitionEnd

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/state-machine/state-machine-config#ontransitionendfn'>OnTransitionEndFn</a>&#60;State | <a href='/reference/typescript-api/fulfillment/fulfillment-state#fulfillmentstate'>FulfillmentState</a>, <a href='/reference/typescript-api/fulfillment/fulfillment-transition-data#fulfillmenttransitiondata'>FulfillmentTransitionData</a>&#62;`}   />


### onTransitionError

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/state-machine/state-machine-config#ontransitionerrorfn'>OnTransitionErrorFn</a>&#60;State | <a href='/reference/typescript-api/fulfillment/fulfillment-state#fulfillmentstate'>FulfillmentState</a>&#62;`}   />




</div>


---

---
title: "FulfillmentState"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## FulfillmentState

<GenerationInfo sourceFile="packages/core/src/service/helpers/fulfillment-state-machine/fulfillment-state.ts" sourceLine="29" packageName="@vendure/core" />

These are the default states of the fulfillment process. By default, they will be extended
by the <a href='/reference/typescript-api/fulfillment/fulfillment-process#defaultfulfillmentprocess'>defaultFulfillmentProcess</a> to also include `Shipped` and `Delivered`.

```ts title="Signature"
type FulfillmentState = | 'Created'
    | 'Pending'
    | 'Cancelled'
    | keyof CustomFulfillmentStates
    | keyof FulfillmentStates
```


---

---
title: "FulfillmentStates"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## FulfillmentStates

<GenerationInfo sourceFile="packages/core/src/service/helpers/fulfillment-state-machine/fulfillment-state.ts" sourceLine="19" packageName="@vendure/core" />

An interface to extend standard <a href='/reference/typescript-api/fulfillment/fulfillment-state#fulfillmentstate'>FulfillmentState</a>.

```ts title="Signature"
interface FulfillmentStates {

}
```


---

---
title: "FulfillmentTransitionData"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## FulfillmentTransitionData

<GenerationInfo sourceFile="packages/core/src/service/helpers/fulfillment-state-machine/fulfillment-state.ts" sourceLine="42" packageName="@vendure/core" />

The data which is passed to the state transition handler of the FulfillmentStateMachine.

```ts title="Signature"
interface FulfillmentTransitionData {
    ctx: RequestContext;
    orders: Order[];
    fulfillment: Fulfillment;
}
```

<div className="members-wrapper">

### ctx

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>`}   />


### orders

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/order#order'>Order</a>[]`}   />


### fulfillment

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/fulfillment#fulfillment'>Fulfillment</a>`}   />




</div>


---

---
title: "Fulfillment"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "HealthCheckRegistryService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## HealthCheckRegistryService

<GenerationInfo sourceFile="packages/core/src/health-check/health-check-registry.service.ts" sourceLine="47" packageName="@vendure/core" />

This service is used to register health indicator functions to be included in the
health check. Health checks can be used by automated services such as Kubernetes
to determine the state of applications it is running. They are also useful for
administrators to get an overview of the health of all the parts of the
Vendure stack.

It wraps the [Nestjs Terminus module](https://docs.nestjs.com/recipes/terminus),
so see those docs for information on creating custom health checks.

Plugins which rely on external services (web services, databases etc.) can make use of this
service to add a check for that dependency to the Vendure health check.


Since v1.6.0, the preferred way to implement a custom health check is by creating a new <a href='/reference/typescript-api/health-check/health-check-strategy#healthcheckstrategy'>HealthCheckStrategy</a>
and then passing it to the `systemOptions.healthChecks` array.
See the <a href='/reference/typescript-api/health-check/health-check-strategy#healthcheckstrategy'>HealthCheckStrategy</a> docs for an example configuration.

The alternative way to register a health check is by injecting this service directly into your
plugin module. To use it in your plugin, you'll need to import the <a href='/reference/typescript-api/plugin/plugin-common-module#plugincommonmodule'>PluginCommonModule</a>:

*Example*

```ts
import { HealthCheckRegistryService, PluginCommonModule, VendurePlugin } from '@vendure/core';
import { TerminusModule } from '@nestjs/terminus';

@VendurePlugin({
  imports: [PluginCommonModule, TerminusModule],
})
export class MyPlugin {
  constructor(
    private registry: HealthCheckRegistryService
    private httpIndicator: HttpHealthIndicator
  ) {
    registry.registerIndicatorFunction(
      () => this.httpIndicator.pingCheck('vendure-docs', 'https://www.vendure.io/docs/'),
    )
  }
}
```

```ts title="Signature"
class HealthCheckRegistryService {
    registerIndicatorFunction(fn: HealthIndicatorFunction | HealthIndicatorFunction[]) => ;
}
```

<div className="members-wrapper">

### registerIndicatorFunction

<MemberInfo kind="method" type={`(fn: HealthIndicatorFunction | HealthIndicatorFunction[]) => `}   />

Registers one or more `HealthIndicatorFunctions` (see [Nestjs docs](https://docs.nestjs.com/recipes/terminus#setting-up-a-healthcheck))
to be added to the health check endpoint.
The indicator will also appear in the Admin UI's "system status" view.


</div>


---

---
title: "HealthCheckStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## HealthCheckStrategy

<GenerationInfo sourceFile="packages/core/src/config/system/health-check-strategy.ts" sourceLine="48" packageName="@vendure/core" />

This strategy defines health checks which are included as part of the
`/health` endpoint. They should only be used to monitor _critical_ systems
on which proper functioning of the Vendure server depends.

For more information on the underlying mechanism, see the
[NestJS Terminus module docs](https://docs.nestjs.com/recipes/terminus).

Custom strategies should be added to the `systemOptions.healthChecks` array.
By default, Vendure includes the `TypeORMHealthCheckStrategy`, so if you set the value of the `healthChecks`
array, be sure to include it manually.

Vendure also ships with the <a href='/reference/typescript-api/health-check/http-health-check-strategy#httphealthcheckstrategy'>HttpHealthCheckStrategy</a>, which is convenient
for adding a health check dependent on an HTTP ping.

:::info

This is configured via the `systemOptions.healthChecks` property of
your VendureConfig.

:::

*Example*

```ts
import { HttpHealthCheckStrategy, TypeORMHealthCheckStrategy } from '@vendure/core';
import { MyCustomHealthCheckStrategy } from './config/custom-health-check-strategy';

export const config = {
  // ...
  systemOptions: {
    healthChecks: [
      new TypeORMHealthCheckStrategy(),
      new HttpHealthCheckStrategy({ key: 'my-service', url: 'https://my-service.com' }),
      new MyCustomHealthCheckStrategy(),
    ],
  },
};
```

```ts title="Signature"
interface HealthCheckStrategy extends InjectableStrategy {
    getHealthIndicator(): HealthIndicatorFunction;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### getHealthIndicator

<MemberInfo kind="method" type={`() => HealthIndicatorFunction`}   />

Should return a `HealthIndicatorFunction`, as defined by the
[NestJS Terminus module](https://docs.nestjs.com/recipes/terminus).


</div>


---

---
title: "HttpHealthCheckStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## HttpHealthCheckStrategy

<GenerationInfo sourceFile="packages/core/src/health-check/http-health-check-strategy.ts" sourceLine="37" packageName="@vendure/core" />

A <a href='/reference/typescript-api/health-check/health-check-strategy#healthcheckstrategy'>HealthCheckStrategy</a> used to check health by pinging a url. Internally it uses
the [NestJS HttpHealthIndicator](https://docs.nestjs.com/recipes/terminus#http-healthcheck).

*Example*

```ts
import { HttpHealthCheckStrategy, TypeORMHealthCheckStrategy } from '@vendure/core';

export const config = {
  // ...
  systemOptions: {
    healthChecks: [
      new TypeORMHealthCheckStrategy(),
      new HttpHealthCheckStrategy({ key: 'my-service', url: 'https://my-service.com' }),
    ]
  },
};
```

```ts title="Signature"
class HttpHealthCheckStrategy implements HealthCheckStrategy {
    constructor(options: HttpHealthCheckOptions)
    init(injector: Injector) => ;
    getHealthIndicator() => HealthIndicatorFunction;
}
```
* Implements: <code><a href='/reference/typescript-api/health-check/health-check-strategy#healthcheckstrategy'>HealthCheckStrategy</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(options: HttpHealthCheckOptions) => HttpHealthCheckStrategy`}   />


### init

<MemberInfo kind="method" type={`(injector: <a href='/reference/typescript-api/common/injector#injector'>Injector</a>) => `}   />


### getHealthIndicator

<MemberInfo kind="method" type={`() => HealthIndicatorFunction`}   />




</div>


---

---
title: "Health Check"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "TypeORMHealthCheckStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## TypeORMHealthCheckStrategy

<GenerationInfo sourceFile="packages/core/src/health-check/typeorm-health-check-strategy.ts" sourceLine="38" packageName="@vendure/core" />

A <a href='/reference/typescript-api/health-check/health-check-strategy#healthcheckstrategy'>HealthCheckStrategy</a> used to check the health of the database. This health
check is included by default, but can be customized by explicitly adding it to the
`systemOptions.healthChecks` array:

*Example*

```ts
import { TypeORMHealthCheckStrategy } from '@vendure/core';

export const config = {
  // ...
  systemOptions: {
    healthChecks:[
        // The default key is "database" and the default timeout is 1000ms
        // Sometimes this is too short and leads to false negatives in the
        // /health endpoint.
        new TypeORMHealthCheckStrategy({ key: 'postgres-db', timeout: 5000 }),
    ]
  }
}
```

```ts title="Signature"
class TypeORMHealthCheckStrategy implements HealthCheckStrategy {
    constructor(options?: TypeORMHealthCheckOptions)
    init(injector: Injector) => ;
    getHealthIndicator() => HealthIndicatorFunction;
}
```
* Implements: <code><a href='/reference/typescript-api/health-check/health-check-strategy#healthcheckstrategy'>HealthCheckStrategy</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(options?: TypeORMHealthCheckOptions) => TypeORMHealthCheckStrategy`}   />


### init

<MemberInfo kind="method" type={`(injector: <a href='/reference/typescript-api/common/injector#injector'>Injector</a>) => `}   />


### getHealthIndicator

<MemberInfo kind="method" type={`() => HealthIndicatorFunction`}   />




</div>


---

---
title: "AssetImportStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## AssetImportStrategy

<GenerationInfo sourceFile="packages/core/src/config/asset-import-strategy/asset-import-strategy.ts" sourceLine="25" packageName="@vendure/core" since="1.7.0" />

The AssetImportStrategy determines how asset files get imported based on the path given in the
import CSV or via the <a href='/reference/typescript-api/import-export/asset-importer#assetimporter'>AssetImporter</a> `getAssets()` method.

The <a href='/reference/typescript-api/import-export/default-asset-import-strategy#defaultassetimportstrategy'>DefaultAssetImportStrategy</a> is able to load files from either the local filesystem
or from a remote URL.

A custom strategy could be created which could e.g. get the asset file from an S3 bucket.

:::info

This is configured via the `importExportOptions.assetImportStrategy` property of
your VendureConfig.

:::

```ts title="Signature"
interface AssetImportStrategy extends InjectableStrategy {
    getStreamFromPath(assetPath: string): Readable | Promise<Readable>;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### getStreamFromPath

<MemberInfo kind="method" type={`(assetPath: string) => Readable | Promise&#60;Readable&#62;`}   />

Given an asset path, this method should return a Stream of file data. This could
e.g. be read from a file system or fetch from a remote location.


</div>


---

---
title: "AssetImporter"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## AssetImporter

<GenerationInfo sourceFile="packages/core/src/data-import/providers/asset-importer/asset-importer.ts" sourceLine="17" packageName="@vendure/core" />

This service creates new <a href='/reference/typescript-api/entities/asset#asset'>Asset</a> entities based on string paths provided in the CSV
import format. The source files are resolved by joining the value of `importExportOptions.importAssetsDir`
with the asset path. This service is used internally by the <a href='/reference/typescript-api/import-export/importer#importer'>Importer</a> service.

```ts title="Signature"
class AssetImporter {
    getAssets(assetPaths: string[], ctx?: RequestContext) => Promise<{ assets: Asset[]; errors: string[] }>;
}
```

<div className="members-wrapper">

### getAssets

<MemberInfo kind="method" type={`(assetPaths: string[], ctx?: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => Promise&#60;{ assets: <a href='/reference/typescript-api/entities/asset#asset'>Asset</a>[]; errors: string[] }&#62;`}   />

Creates Asset entities for the given paths, using the assetMap cache to prevent the
creation of duplicates.


</div>


---

---
title: "DefaultAssetImportStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DefaultAssetImportStrategy

<GenerationInfo sourceFile="packages/core/src/config/asset-import-strategy/default-asset-import-strategy.ts" sourceLine="50" packageName="@vendure/core" since="1.7.0" />

The DefaultAssetImportStrategy is able to import paths from the local filesystem (taking into account the
`importExportOptions.importAssetsDir` setting) as well as remote http/https urls.

```ts title="Signature"
class DefaultAssetImportStrategy implements AssetImportStrategy {
    constructor(options?: {
            retryDelayMs: number;
            retryCount: number;
        })
    init(injector: Injector) => ;
    getStreamFromPath(assetPath: string) => ;
}
```
* Implements: <code><a href='/reference/typescript-api/import-export/asset-import-strategy#assetimportstrategy'>AssetImportStrategy</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(options?: {             retryDelayMs: number;             retryCount: number;         }) => DefaultAssetImportStrategy`}   />


### init

<MemberInfo kind="method" type={`(injector: <a href='/reference/typescript-api/common/injector#injector'>Injector</a>) => `}   />


### getStreamFromPath

<MemberInfo kind="method" type={`(assetPath: string) => `}   />




</div>


---

---
title: "FastImporterService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## FastImporterService

<GenerationInfo sourceFile="packages/core/src/data-import/providers/importer/fast-importer.service.ts" sourceLine="41" packageName="@vendure/core" />

A service to import entities into the database. This replaces the regular `create` methods of the service layer with faster
versions which skip much of the defensive checks and other DB calls which are not needed when running an import. It also
does not publish any events, so e.g. will not trigger search index jobs.

In testing, the use of the FastImporterService approximately doubled the speed of bulk imports.

```ts title="Signature"
class FastImporterService {
    initialize(channel?: Channel) => ;
    createProduct(input: CreateProductInput) => Promise<ID>;
    createProductOptionGroup(input: CreateProductOptionGroupInput) => Promise<ID>;
    createProductOption(input: CreateProductOptionInput) => Promise<ID>;
    addOptionGroupToProduct(productId: ID, optionGroupId: ID) => ;
    createProductVariant(input: CreateProductVariantInput) => Promise<ID>;
}
```

<div className="members-wrapper">

### initialize

<MemberInfo kind="method" type={`(channel?: <a href='/reference/typescript-api/entities/channel#channel'>Channel</a>) => `}   />

This should be called prior to any of the import methods, as it establishes the
default Channel as well as the context in which the new entities will be created.

Passing a `channel` argument means that Products and ProductVariants will be assigned
to that Channel.
### createProduct

<MemberInfo kind="method" type={`(input: CreateProductInput) => Promise&#60;<a href='/reference/typescript-api/common/id#id'>ID</a>&#62;`}   />


### createProductOptionGroup

<MemberInfo kind="method" type={`(input: CreateProductOptionGroupInput) => Promise&#60;<a href='/reference/typescript-api/common/id#id'>ID</a>&#62;`}   />


### createProductOption

<MemberInfo kind="method" type={`(input: CreateProductOptionInput) => Promise&#60;<a href='/reference/typescript-api/common/id#id'>ID</a>&#62;`}   />


### addOptionGroupToProduct

<MemberInfo kind="method" type={`(productId: <a href='/reference/typescript-api/common/id#id'>ID</a>, optionGroupId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => `}   />


### createProductVariant

<MemberInfo kind="method" type={`(input: CreateProductVariantInput) => Promise&#60;<a href='/reference/typescript-api/common/id#id'>ID</a>&#62;`}   />




</div>


---

---
title: "ImportExportOptions"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ImportExportOptions

<GenerationInfo sourceFile="packages/core/src/config/vendure-config.ts" sourceLine="935" packageName="@vendure/core" />

Options related to importing & exporting data.

```ts title="Signature"
interface ImportExportOptions {
    importAssetsDir?: string;
    assetImportStrategy?: AssetImportStrategy;
}
```

<div className="members-wrapper">

### importAssetsDir

<MemberInfo kind="property" type={`string`} default={`__dirname`}   />

The directory in which assets to be imported are located.
### assetImportStrategy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/import-export/asset-import-strategy#assetimportstrategy'>AssetImportStrategy</a>`}  since="1.7.0"  />

This strategy determines how asset files get imported based on the path given in the
import CSV or via the <a href='/reference/typescript-api/import-export/asset-importer#assetimporter'>AssetImporter</a> `getAssets()` method.


</div>


---

---
title: "ImportParser"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ImportParser

<GenerationInfo sourceFile="packages/core/src/data-import/providers/import-parser/import-parser.ts" sourceLine="152" packageName="@vendure/core" />

Validates and parses CSV files into a data structure which can then be used to created new entities.
This is used internally by the <a href='/reference/typescript-api/import-export/importer#importer'>Importer</a>.

```ts title="Signature"
class ImportParser {
    parseProducts(input: string | Stream, mainLanguage: LanguageCode = this.configService.defaultLanguageCode) => Promise<ParseResult<ParsedProductWithVariants>>;
}
```

<div className="members-wrapper">

### parseProducts

<MemberInfo kind="method" type={`(input: string | Stream, mainLanguage: <a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a> = this.configService.defaultLanguageCode) => Promise&#60;<a href='/reference/typescript-api/import-export/import-parser#parseresult'>ParseResult</a>&#60;<a href='/reference/typescript-api/import-export/import-parser#parsedproductwithvariants'>ParsedProductWithVariants</a>&#62;&#62;`}   />

Parses the contents of the [product import CSV file](/guides/developer-guide/importing-data/#product-import-format) and
returns a data structure which can then be used to populate Vendure using the <a href='/reference/typescript-api/import-export/fast-importer-service#fastimporterservice'>FastImporterService</a>.


</div>


## ParsedOptionGroup

<GenerationInfo sourceFile="packages/core/src/data-import/providers/import-parser/import-parser.ts" sourceLine="45" packageName="@vendure/core" />

The intermediate representation of an OptionGroup after it has been parsed
by the <a href='/reference/typescript-api/import-export/import-parser#importparser'>ImportParser</a>.

```ts title="Signature"
interface ParsedOptionGroup {
    translations: Array<{
        languageCode: LanguageCode;
        name: string;
        values: string[];
    }>;
}
```

<div className="members-wrapper">

### translations

<MemberInfo kind="property" type={`Array&#60;{         languageCode: <a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a>;         name: string;         values: string[];     }&#62;`}   />




</div>


## ParsedFacet

<GenerationInfo sourceFile="packages/core/src/data-import/providers/import-parser/import-parser.ts" sourceLine="61" packageName="@vendure/core" />

The intermediate representation of a Facet after it has been parsed
by the <a href='/reference/typescript-api/import-export/import-parser#importparser'>ImportParser</a>.

```ts title="Signature"
interface ParsedFacet {
    translations: Array<{
        languageCode: LanguageCode;
        facet: string;
        value: string;
    }>;
}
```

<div className="members-wrapper">

### translations

<MemberInfo kind="property" type={`Array&#60;{         languageCode: <a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a>;         facet: string;         value: string;     }&#62;`}   />




</div>


## ParsedProductVariant

<GenerationInfo sourceFile="packages/core/src/data-import/providers/import-parser/import-parser.ts" sourceLine="77" packageName="@vendure/core" />

The intermediate representation of a ProductVariant after it has been parsed
by the <a href='/reference/typescript-api/import-export/import-parser#importparser'>ImportParser</a>.

```ts title="Signature"
interface ParsedProductVariant {
    sku: string;
    price: number;
    taxCategory: string;
    stockOnHand: number;
    trackInventory: GlobalFlag;
    assetPaths: string[];
    facets: ParsedFacet[];
    translations: Array<{
        languageCode: LanguageCode;
        optionValues: string[];
        customFields: {
            [name: string]: string;
        };
    }>;
}
```

<div className="members-wrapper">

### sku

<MemberInfo kind="property" type={`string`}   />


### price

<MemberInfo kind="property" type={`number`}   />


### taxCategory

<MemberInfo kind="property" type={`string`}   />


### stockOnHand

<MemberInfo kind="property" type={`number`}   />


### trackInventory

<MemberInfo kind="property" type={`GlobalFlag`}   />


### assetPaths

<MemberInfo kind="property" type={`string[]`}   />


### facets

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/import-export/import-parser#parsedfacet'>ParsedFacet</a>[]`}   />


### translations

<MemberInfo kind="property" type={`Array&#60;{         languageCode: <a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a>;         optionValues: string[];         customFields: {             [name: string]: string;         };     }&#62;`}   />




</div>


## ParsedProduct

<GenerationInfo sourceFile="packages/core/src/data-import/providers/import-parser/import-parser.ts" sourceLine="102" packageName="@vendure/core" />

The intermediate representation of a Product after it has been parsed
by the <a href='/reference/typescript-api/import-export/import-parser#importparser'>ImportParser</a>.

```ts title="Signature"
interface ParsedProduct {
    assetPaths: string[];
    optionGroups: ParsedOptionGroup[];
    facets: ParsedFacet[];
    translations: Array<{
        languageCode: LanguageCode;
        name: string;
        slug: string;
        description: string;
        customFields: {
            [name: string]: string;
        };
    }>;
}
```

<div className="members-wrapper">

### assetPaths

<MemberInfo kind="property" type={`string[]`}   />


### optionGroups

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/import-export/import-parser#parsedoptiongroup'>ParsedOptionGroup</a>[]`}   />


### facets

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/import-export/import-parser#parsedfacet'>ParsedFacet</a>[]`}   />


### translations

<MemberInfo kind="property" type={`Array&#60;{         languageCode: <a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a>;         name: string;         slug: string;         description: string;         customFields: {             [name: string]: string;         };     }&#62;`}   />




</div>


## ParsedProductWithVariants

<GenerationInfo sourceFile="packages/core/src/data-import/providers/import-parser/import-parser.ts" sourceLine="125" packageName="@vendure/core" />

The data structure into which an import CSV file is parsed by the
<a href='/reference/typescript-api/import-export/import-parser#importparser'>ImportParser</a> `parseProducts()` method.

```ts title="Signature"
interface ParsedProductWithVariants {
    product: ParsedProduct;
    variants: ParsedProductVariant[];
}
```

<div className="members-wrapper">

### product

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/import-export/import-parser#parsedproduct'>ParsedProduct</a>`}   />


### variants

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/import-export/import-parser#parsedproductvariant'>ParsedProductVariant</a>[]`}   />




</div>


## ParseResult

<GenerationInfo sourceFile="packages/core/src/data-import/providers/import-parser/import-parser.ts" sourceLine="137" packageName="@vendure/core" />

The result returned by the <a href='/reference/typescript-api/import-export/import-parser#importparser'>ImportParser</a> `parseProducts()` method.

```ts title="Signature"
interface ParseResult<T> {
    results: T[];
    errors: string[];
    processed: number;
}
```

<div className="members-wrapper">

### results

<MemberInfo kind="property" type={`T[]`}   />


### errors

<MemberInfo kind="property" type={`string[]`}   />


### processed

<MemberInfo kind="property" type={`number`}   />




</div>


---

---
title: "Importer"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## Importer

<GenerationInfo sourceFile="packages/core/src/data-import/providers/importer/importer.ts" sourceLine="42" packageName="@vendure/core" />

Parses and imports Products using the CSV import format.

Internally it is using the <a href='/reference/typescript-api/import-export/import-parser#importparser'>ImportParser</a> to parse the CSV file, and then the
<a href='/reference/typescript-api/import-export/fast-importer-service#fastimporterservice'>FastImporterService</a> and the <a href='/reference/typescript-api/import-export/asset-importer#assetimporter'>AssetImporter</a> to actually create the resulting
entities in the Vendure database.

```ts title="Signature"
class Importer {
    parseAndImport(input: string | Stream, ctxOrLanguageCode: RequestContext | LanguageCode, reportProgress: boolean = false) => Observable<ImportProgress>;
    importProducts(ctx: RequestContext, rows: ParsedProductWithVariants[], onProgress: OnProgressFn) => Promise<string[]>;
    getFacetValueIds(ctx: RequestContext, facets: ParsedFacet[], languageCode: LanguageCode) => Promise<ID[]>;
    processCustomFieldValues(customFields: { [field: string]: string }, config: CustomFieldConfig[]) => ;
}
```

<div className="members-wrapper">

### parseAndImport

<MemberInfo kind="method" type={`(input: string | Stream, ctxOrLanguageCode: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a> | <a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a>, reportProgress: boolean = false) => Observable&#60;ImportProgress&#62;`}   />

Parses the contents of the [product import CSV file](/guides/developer-guide/importing-data/#product-import-format) and imports
the resulting Product & ProductVariants, as well as any associated Assets, Facets & FacetValues.

The `ctxOrLanguageCode` argument is used to specify the languageCode to be used when creating the Products.
### importProducts

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, rows: <a href='/reference/typescript-api/import-export/import-parser#parsedproductwithvariants'>ParsedProductWithVariants</a>[], onProgress: OnProgressFn) => Promise&#60;string[]&#62;`}   />

Imports the products specified in the rows object. Return an array of error messages.
### getFacetValueIds

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, facets: <a href='/reference/typescript-api/import-export/import-parser#parsedfacet'>ParsedFacet</a>[], languageCode: <a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a>) => Promise&#60;<a href='/reference/typescript-api/common/id#id'>ID</a>[]&#62;`}   />


### processCustomFieldValues

<MemberInfo kind="method" type={`(customFields: { [field: string]: string }, config: <a href='/reference/typescript-api/custom-fields/custom-field-config#customfieldconfig'>CustomFieldConfig</a>[]) => `}   />




</div>


---

---
title: "Import Export"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "InitialData"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## InitialData

<GenerationInfo sourceFile="packages/core/src/data-import/types.ts" sourceLine="47" packageName="@vendure/core" />

An object defining initial settings for a new Vendure installation.

```ts title="Signature"
interface InitialData {
    defaultLanguage: LanguageCode;
    defaultZone: string;
    roles?: RoleDefinition[];
    countries: CountryDefinition[];
    taxRates: Array<{ name: string; percentage: number }>;
    shippingMethods: Array<{ name: string; price: number; taxRate?: number }>;
    paymentMethods: Array<{ name: string; handler: ConfigurableOperationInput }>;
    collections: CollectionDefinition[];
}
```

<div className="members-wrapper">

### defaultLanguage

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a>`}   />


### defaultZone

<MemberInfo kind="property" type={`string`}   />


### roles

<MemberInfo kind="property" type={`RoleDefinition[]`}   />


### countries

<MemberInfo kind="property" type={`CountryDefinition[]`}   />


### taxRates

<MemberInfo kind="property" type={`Array&#60;{ name: string; percentage: number }&#62;`}   />


### shippingMethods

<MemberInfo kind="property" type={`Array&#60;{ name: string; price: number; taxRate?: number }&#62;`}   />


### paymentMethods

<MemberInfo kind="property" type={`Array&#60;{ name: string; handler: ConfigurableOperationInput }&#62;`}   />


### collections

<MemberInfo kind="property" type={`CollectionDefinition[]`}   />




</div>


---

---
title: "Populate"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## populate

<GenerationInfo sourceFile="packages/core/src/cli/populate.ts" sourceLine="51" packageName="@vendure/core" />

Populates the Vendure server with some initial data and (optionally) product data from
a supplied CSV file. The format of the CSV file is described in the section
[Importing Product Data](/guides/developer-guide/importing-data/).

If the `channelOrToken` argument is provided, all ChannelAware entities (Products, ProductVariants,
Assets, ShippingMethods, PaymentMethods etc.) will be assigned to the specified Channel.
The argument can be either a Channel object or a valid channel `token`.

Internally the `populate()` function does the following:

1. Uses the <a href='/reference/typescript-api/import-export/populator#populator'>Populator</a> to populate the <a href='/reference/typescript-api/import-export/initial-data#initialdata'>InitialData</a>.
2. If `productsCsvPath` is provided, uses <a href='/reference/typescript-api/import-export/importer#importer'>Importer</a> to populate Product data.
3. Uses <a href='/reference/typescript-api/import-export/populator#populator'>Populator</a> to populate collections specified in the <a href='/reference/typescript-api/import-export/initial-data#initialdata'>InitialData</a>.

*Example*

```ts
import { bootstrap } from '@vendure/core';
import { populate } from '@vendure/core/cli';
import { config } from './vendure-config.ts'
import { initialData } from './my-initial-data.ts';

const productsCsvFile = path.join(__dirname, 'path/to/products.csv')

populate(
  () => bootstrap(config),
  initialData,
  productsCsvFile,
)
.then(app => app.close())
.then(
  () => process.exit(0),
  err => {
    console.log(err);
    process.exit(1);
  },
);
```

```ts title="Signature"
function populate<T extends INestApplicationContext>(bootstrapFn: () => Promise<T | undefined>, initialDataPathOrObject: string | object, productsCsvPath?: string, channelOrToken?: string | import('@vendure/core').Channel): Promise<T>
```
Parameters

### bootstrapFn

<MemberInfo kind="parameter" type={`() =&#62; Promise&#60;T | undefined&#62;`} />

### initialDataPathOrObject

<MemberInfo kind="parameter" type={`string | object`} />

### productsCsvPath

<MemberInfo kind="parameter" type={`string`} />

### channelOrToken

<MemberInfo kind="parameter" type={`string | import('@vendure/core').<a href='/reference/typescript-api/entities/channel#channel'>Channel</a>`} />



---

---
title: "Populator"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## Populator

<GenerationInfo sourceFile="packages/core/src/data-import/providers/populator/populator.ts" sourceLine="46" packageName="@vendure/core" />

Responsible for populating the database with <a href='/reference/typescript-api/import-export/initial-data#initialdata'>InitialData</a>, i.e. non-product data such as countries, tax rates,
shipping methods, payment methods & roles.

```ts title="Signature"
class Populator {
    populateInitialData(data: InitialData, channel?: Channel) => ;
    populateCollections(data: InitialData, channel?: Channel) => ;
}
```

<div className="members-wrapper">

### populateInitialData

<MemberInfo kind="method" type={`(data: <a href='/reference/typescript-api/import-export/initial-data#initialdata'>InitialData</a>, channel?: <a href='/reference/typescript-api/entities/channel#channel'>Channel</a>) => `}   />

Should be run *before* populating the products, so that there are TaxRates by which
product prices can be set. If the `channel` argument is set, then any <a href='/reference/typescript-api/entities/interfaces#channelaware'>ChannelAware</a>entities will be assigned to that Channel.
### populateCollections

<MemberInfo kind="method" type={`(data: <a href='/reference/typescript-api/import-export/initial-data#initialdata'>InitialData</a>, channel?: <a href='/reference/typescript-api/entities/channel#channel'>Channel</a>) => `}   />

Should be run *after* the products have been populated, otherwise the expected FacetValues will not
yet exist.


</div>


---

---
title: "DefaultJobQueuePlugin"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DefaultJobQueuePlugin

<GenerationInfo sourceFile="packages/core/src/plugin/default-job-queue-plugin/default-job-queue-plugin.ts" sourceLine="127" packageName="@vendure/core" />

A plugin which configures Vendure to use the SQL database to persist the JobQueue jobs using the <a href='/reference/typescript-api/job-queue/sql-job-queue-strategy#sqljobqueuestrategy'>SqlJobQueueStrategy</a>. If you add this
plugin to an existing Vendure installation, you'll need to run a [database migration](/guides/developer-guide/migrations), since this
plugin will add a new "job_record" table to the database.

*Example*

```ts
import { DefaultJobQueuePlugin, VendureConfig } from '@vendure/core';

export const config: VendureConfig = {
  // Add an instance of the plugin to the plugins array
  plugins: [
    DefaultJobQueuePlugin,
  ],
};
```

## Configuration

It is possible to configure the behaviour of the <a href='/reference/typescript-api/job-queue/sql-job-queue-strategy#sqljobqueuestrategy'>SqlJobQueueStrategy</a> by passing options to the static `init()` function:

### pollInterval
The interval in ms between polling for new jobs. The default is 200ms.
Using a longer interval reduces load on the database but results in a slight
delay in processing jobs. For more control, it is possible to supply a function which can specify
a pollInterval based on the queue name:

*Example*

```ts
export const config: VendureConfig = {
  plugins: [
    DefaultJobQueuePlugin.init({
      pollInterval: queueName => {
        if (queueName === 'cart-recovery-email') {
          // This queue does not need to be polled so frequently,
          // so we set a longer interval in order to reduce load
          // on the database.
          return 10000;
        }
        return 200;
      },
    }),
  ],
};
```
### concurrency
The number of jobs to process concurrently per worker. Defaults to 1.

### backoffStrategy
Defines the backoff strategy used when retrying failed jobs. In other words, if a job fails
and is configured to be re-tried, how long should we wait before the next attempt?

By default, a job will be retried as soon as possible, but in some cases this is not desirable. For example,
a job may interact with an unreliable 3rd-party API which is sensitive to too many requests. In this case, an
exponential backoff may be used which progressively increases the delay between each subsequent retry.

*Example*

```ts
export const config: VendureConfig = {
  plugins: [
    DefaultJobQueuePlugin.init({
      pollInterval: 5000,
      concurrency: 2
      backoffStrategy: (queueName, attemptsMade, job) => {
        if (queueName === 'transcode-video') {
          // exponential backoff example
          return (attemptsMade ** 2) * 1000;
        }

        // A default delay for all other queues
        return 1000;
      },
      setRetries: (queueName, job) => {
        if (queueName === 'send-email') {
          // Override the default number of retries
          // for the 'send-email' job because we have
          // a very unreliable email service.
          return 10;
        }
        return job.retries;
      }
    }),
  ],
};
```

### Removing old jobs
Since v3.3, the job queue will automatically remove old jobs from the database. This is done by a scheduled task
which runs every 2 hours by default. The number of jobs to keep in the database can be configured using the
`keepJobsCount` option. The default is 1000.

*Example*

```ts
export const config: VendureConfig = {
  plugins: [
    DefaultJobQueuePlugin.init({
      // The number of completed/failed/cancelled
      // jobs to keep in the database. The default is 1000.
      keepJobsCount: 100,
      // The interval at which to run the clean-up task.
      // This can be a standard cron expression or a function
      // that returns a cron expression. The default is every 2 hours.
      cleanJobsSchedule: cron => cron.every(5).hours(),
    }),
  ],
};
```

```ts title="Signature"
class DefaultJobQueuePlugin {
    init(options: DefaultJobQueueOptions) => Type<DefaultJobQueuePlugin>;
}
```

<div className="members-wrapper">

### init

<MemberInfo kind="method" type={`(options: <a href='/reference/typescript-api/job-queue/default-job-queue-plugin#defaultjobqueueoptions'>DefaultJobQueueOptions</a>) => Type&#60;<a href='/reference/typescript-api/job-queue/default-job-queue-plugin#defaultjobqueueplugin'>DefaultJobQueuePlugin</a>&#62;`}   />




</div>


## cleanJobsTask

<GenerationInfo sourceFile="packages/core/src/plugin/default-job-queue-plugin/clean-jobs-task.ts" sourceLine="18" packageName="@vendure/core" since="3.3.0" />

A <a href='/reference/typescript-api/scheduled-tasks/scheduled-task#scheduledtask'>ScheduledTask</a> that cleans up old jobs from the database when using the DefaultJobQueuePlugin.
You can configure the settings & schedule of the task via the <a href='/reference/typescript-api/job-queue/default-job-queue-plugin#defaultjobqueueplugin'>DefaultJobQueuePlugin</a> options.



## DefaultJobQueueOptions

<GenerationInfo sourceFile="packages/core/src/plugin/default-job-queue-plugin/types.ts" sourceLine="12" packageName="@vendure/core" />

Configuration options for the DefaultJobQueuePlugin. These values get passed into the
<a href='/reference/typescript-api/job-queue/sql-job-queue-strategy#sqljobqueuestrategy'>SqlJobQueueStrategy</a>.

```ts title="Signature"
interface DefaultJobQueueOptions {
    pollInterval?: number | ((queueName: string) => number);
    concurrency?: number;
    backoffStrategy?: BackoffStrategy;
    setRetries?: (queueName: string, job: Job) => number;
    useDatabaseForBuffer?: boolean;
    gracefulShutdownTimeout?: number;
    keepJobsCount?: number;
    cleanJobsSchedule?: ScheduledTaskConfig['schedule'];
}
```

<div className="members-wrapper">

### pollInterval

<MemberInfo kind="property" type={`number | ((queueName: string) =&#62; number)`} default={`200`}   />

The interval in ms between polling the database for new jobs. If many job queues
are active, the polling may cause undue load on the database, in which case this value
should be increased to e.g. 1000.
### concurrency

<MemberInfo kind="property" type={`number`} default={`1`}   />

How many jobs from a given queue to process concurrently.
### backoffStrategy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/job-queue/types#backoffstrategy'>BackoffStrategy</a>`} default={`() =&#62; 1000`}   />

The strategy used to decide how long to wait before retrying a failed job.
### setRetries

<MemberInfo kind="property" type={`(queueName: string, job: <a href='/reference/typescript-api/job-queue/job#job'>Job</a>) =&#62; number`}   />

When a job is added to the JobQueue using `JobQueue.add()`, the calling
code may specify the number of retries in case of failure. This option allows
you to override that number and specify your own number of retries based on
the job being added.

*Example*

```ts
setRetries: (queueName, job) => {
  if (queueName === 'send-email') {
    // Override the default number of retries
    // for the 'send-email' job because we have
    // a very unreliable email service.
    return 10;
  }
  return job.retries;
}
 ```
### useDatabaseForBuffer

<MemberInfo kind="property" type={`boolean`}  since="1.3.0"  />

If set to `true`, the database will be used to store buffered jobs. This is
recommended for production.

When enabled, a new `JobRecordBuffer` database entity will be defined which will
require a migration when first enabling this option.
### gracefulShutdownTimeout

<MemberInfo kind="property" type={`number`} default={`20_000`}  since="2.2.0"  />

The timeout in ms which the queue will use when attempting a graceful shutdown.
That means when the server is shut down but a job is running, the job queue will
wait for the job to complete before allowing the server to shut down. If the job
does not complete within this timeout window, the job will be forced to stop
and the server will shut down anyway.
### keepJobsCount

<MemberInfo kind="property" type={`number`} default={`1000`}  since="3.3.0"  />

The number of completed/failed jobs to keep in the database. This is useful for
debugging and auditing purposes, but if you have a lot of jobs, it may be
desirable to limit the number of records in the database.
### cleanJobsSchedule

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/scheduled-tasks/scheduled-task#scheduledtaskconfig'>ScheduledTaskConfig</a>['schedule']`} default={`cron =&#62; cron.every(2).hours()`}  since="3.3.0"  />

The schedule for the "clean-jobs" task. This task will run periodically to clean up
old jobs from the database. The schedule can be a cron expression or a function
that returns a cron expression.


</div>


---

---
title: "InMemoryJobBufferStorageStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## InMemoryJobBufferStorageStrategy

<GenerationInfo sourceFile="packages/core/src/job-queue/job-buffer/in-memory-job-buffer-storage-strategy.ts" sourceLine="17" packageName="@vendure/core" since="1.3.0" />

A <a href='/reference/typescript-api/job-queue/job-buffer-storage-strategy#jobbufferstoragestrategy'>JobBufferStorageStrategy</a> which keeps the buffered jobs in memory. Should
_not_ be used in production, since it will lose data in the event of the server
stopping.

Instead, use the <a href='/reference/typescript-api/job-queue/default-job-queue-plugin#defaultjobqueueplugin'>DefaultJobQueuePlugin</a> with the `useDatabaseForBuffer: true` option set,
or the <a href='/reference/core-plugins/job-queue-plugin/bull-mqjob-queue-plugin#bullmqjobqueueplugin'>BullMQJobQueuePlugin</a> or another custom strategy with persistent storage.

```ts title="Signature"
class InMemoryJobBufferStorageStrategy implements JobBufferStorageStrategy {
    protected bufferStorage = new Map<string, Set<Job>>();
    add(bufferId: string, job: Job) => Promise<Job>;
    bufferSize(bufferIds?: string[]) => Promise<{ [bufferId: string]: number }>;
    flush(bufferIds?: string[]) => Promise<{ [bufferId: string]: Job[] }>;
}
```
* Implements: <code><a href='/reference/typescript-api/job-queue/job-buffer-storage-strategy#jobbufferstoragestrategy'>JobBufferStorageStrategy</a></code>



<div className="members-wrapper">

### bufferStorage

<MemberInfo kind="property" type={``}   />


### add

<MemberInfo kind="method" type={`(bufferId: string, job: <a href='/reference/typescript-api/job-queue/job#job'>Job</a>) => Promise&#60;<a href='/reference/typescript-api/job-queue/job#job'>Job</a>&#62;`}   />


### bufferSize

<MemberInfo kind="method" type={`(bufferIds?: string[]) => Promise&#60;{ [bufferId: string]: number }&#62;`}   />


### flush

<MemberInfo kind="method" type={`(bufferIds?: string[]) => Promise&#60;{ [bufferId: string]: <a href='/reference/typescript-api/job-queue/job#job'>Job</a>[] }&#62;`}   />




</div>


---

---
title: "InMemoryJobQueueStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## InMemoryJobQueueStrategy

<GenerationInfo sourceFile="packages/core/src/job-queue/in-memory-job-queue-strategy.ts" sourceLine="42" packageName="@vendure/core" />

An in-memory <a href='/reference/typescript-api/job-queue/job-queue-strategy#jobqueuestrategy'>JobQueueStrategy</a>. This is the default strategy if not using a dedicated
JobQueue plugin (e.g. <a href='/reference/typescript-api/job-queue/default-job-queue-plugin#defaultjobqueueplugin'>DefaultJobQueuePlugin</a>). Not recommended for production, since
the queue will be cleared when the server stops, and can only be used when the JobQueueService is
started from the main server process:

*Example*

```ts
bootstrap(config)
  .then(app => app.get(JobQueueService).start());
```

Attempting to use this strategy when running the worker in a separate process (using `bootstrapWorker()`)
will result in an error on startup.

Completed jobs will be evicted from the store every 2 hours to prevent a memory leak.

```ts title="Signature"
class InMemoryJobQueueStrategy extends PollingJobQueueStrategy implements InspectableJobQueueStrategy {
    protected jobs = new Map<ID, Job>();
    protected unsettledJobs: { [queueName: string]: Array<{ job: Job; updatedAt: Date }> } = {};
    init(injector: Injector) => ;
    destroy() => ;
    add(job: Job<Data>) => Promise<Job<Data>>;
    findOne(id: ID) => Promise<Job | undefined>;
    findMany(options?: JobListOptions) => Promise<PaginatedList<Job>>;
    findManyById(ids: ID[]) => Promise<Job[]>;
    next(queueName: string, waitingJobs: Job[] = []) => Promise<Job | undefined>;
    update(job: Job) => Promise<void>;
    removeSettledJobs(queueNames: string[] = [], olderThan?: Date) => Promise<number>;
}
```
* Extends: <code><a href='/reference/typescript-api/job-queue/polling-job-queue-strategy#pollingjobqueuestrategy'>PollingJobQueueStrategy</a></code>


* Implements: <code><a href='/reference/typescript-api/job-queue/inspectable-job-queue-strategy#inspectablejobqueuestrategy'>InspectableJobQueueStrategy</a></code>



<div className="members-wrapper">

### jobs

<MemberInfo kind="property" type={``}   />


### unsettledJobs

<MemberInfo kind="property" type={`{ [queueName: string]: Array&#60;{ job: <a href='/reference/typescript-api/job-queue/job#job'>Job</a>; updatedAt: Date }&#62; }`}   />


### init

<MemberInfo kind="method" type={`(injector: <a href='/reference/typescript-api/common/injector#injector'>Injector</a>) => `}   />


### destroy

<MemberInfo kind="method" type={`() => `}   />


### add

<MemberInfo kind="method" type={`(job: <a href='/reference/typescript-api/job-queue/job#job'>Job</a>&#60;Data&#62;) => Promise&#60;<a href='/reference/typescript-api/job-queue/job#job'>Job</a>&#60;Data&#62;&#62;`}   />


### findOne

<MemberInfo kind="method" type={`(id: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/job-queue/job#job'>Job</a> | undefined&#62;`}   />


### findMany

<MemberInfo kind="method" type={`(options?: JobListOptions) => Promise&#60;<a href='/reference/typescript-api/common/paginated-list#paginatedlist'>PaginatedList</a>&#60;<a href='/reference/typescript-api/job-queue/job#job'>Job</a>&#62;&#62;`}   />


### findManyById

<MemberInfo kind="method" type={`(ids: <a href='/reference/typescript-api/common/id#id'>ID</a>[]) => Promise&#60;<a href='/reference/typescript-api/job-queue/job#job'>Job</a>[]&#62;`}   />


### next

<MemberInfo kind="method" type={`(queueName: string, waitingJobs: <a href='/reference/typescript-api/job-queue/job#job'>Job</a>[] = []) => Promise&#60;<a href='/reference/typescript-api/job-queue/job#job'>Job</a> | undefined&#62;`}   />


### update

<MemberInfo kind="method" type={`(job: <a href='/reference/typescript-api/job-queue/job#job'>Job</a>) => Promise&#60;void&#62;`}   />


### removeSettledJobs

<MemberInfo kind="method" type={`(queueNames: string[] = [], olderThan?: Date) => Promise&#60;number&#62;`}   />




</div>


---

---
title: "JobQueue"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## JobQueue

<GenerationInfo sourceFile="packages/core/src/job-queue/job-queue.ts" sourceLine="21" packageName="@vendure/core" />

A JobQueue is used to process <a href='/reference/typescript-api/job-queue/job#job'>Job</a>s. A job is added to the queue via the
`.add()` method, and the configured <a href='/reference/typescript-api/job-queue/job-queue-strategy#jobqueuestrategy'>JobQueueStrategy</a> will check for new jobs and process each
according to the defined `process` function.

*Note*: JobQueue instances should not be directly instantiated. Rather, the
<a href='/reference/typescript-api/job-queue/job-queue-service#jobqueueservice'>JobQueueService</a> `createQueue()` method should be used (see that service
for example usage).

```ts title="Signature"
class JobQueue<Data extends JobData<Data> = object> {
    name: string
    started: boolean
    constructor(options: CreateQueueOptions<Data>, jobQueueStrategy: JobQueueStrategy, jobBufferService: JobBufferService)
    add(data: Data, options?: JobOptions<Data>) => Promise<SubscribableJob<Data>>;
}
```

<div className="members-wrapper">

### name

<MemberInfo kind="property" type={`string`}   />


### started

<MemberInfo kind="property" type={`boolean`}   />


### constructor

<MemberInfo kind="method" type={`(options: <a href='/reference/typescript-api/job-queue/types#createqueueoptions'>CreateQueueOptions</a>&#60;Data&#62;, jobQueueStrategy: <a href='/reference/typescript-api/job-queue/job-queue-strategy#jobqueuestrategy'>JobQueueStrategy</a>, jobBufferService: JobBufferService) => JobQueue`}   />


### add

<MemberInfo kind="method" type={`(data: Data, options?: JobOptions&#60;Data&#62;) => Promise&#60;<a href='/reference/typescript-api/job-queue/subscribable-job#subscribablejob'>SubscribableJob</a>&#60;Data&#62;&#62;`}   />

Adds a new <a href='/reference/typescript-api/job-queue/job#job'>Job</a> to the queue. The resolved <a href='/reference/typescript-api/job-queue/subscribable-job#subscribablejob'>SubscribableJob</a> allows the
calling code to subscribe to updates to the Job:

*Example*

```ts
const job = await this.myQueue.add({ intervalMs, shouldFail }, { retries: 2 });
return job.updates().pipe(
  map(update => {
    // The returned Observable will emit a value for every update to the job
    // such as when the `progress` or `status` value changes.
    Logger.info(`Job ${update.id}: progress: ${update.progress}`);
    if (update.state === JobState.COMPLETED) {
      Logger.info(`COMPLETED ${update.id}: ${update.result}`);
    }
    return update.result;
  }),
  catchError(err => of(err.message)),
);
```

Alternatively, if you aren't interested in the intermediate
`progress` changes, you can convert to a Promise like this:

*Example*

```ts
const job = await this.myQueue.add({ intervalMs, shouldFail }, { retries: 2 });
return job.updates().toPromise()
  .then(update => update.result),
  .catch(err => err.message);
```


</div>


---

---
title: "InspectableJobQueueStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## InspectableJobQueueStrategy

<GenerationInfo sourceFile="packages/core/src/config/job-queue/inspectable-job-queue-strategy.ts" sourceLine="14" packageName="@vendure/core" />

Defines a job queue strategy that can be inspected using the default admin ui

```ts title="Signature"
interface InspectableJobQueueStrategy extends JobQueueStrategy {
    findOne(id: ID): Promise<Job | undefined>;
    findMany(options?: JobListOptions): Promise<PaginatedList<Job>>;
    findManyById(ids: ID[]): Promise<Job[]>;
    removeSettledJobs(queueNames?: string[], olderThan?: Date): Promise<number>;
    cancelJob(jobId: ID): Promise<Job | undefined>;
}
```
* Extends: <code><a href='/reference/typescript-api/job-queue/job-queue-strategy#jobqueuestrategy'>JobQueueStrategy</a></code>



<div className="members-wrapper">

### findOne

<MemberInfo kind="method" type={`(id: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/job-queue/job#job'>Job</a> | undefined&#62;`}   />

Returns a job by its id.
### findMany

<MemberInfo kind="method" type={`(options?: JobListOptions) => Promise&#60;<a href='/reference/typescript-api/common/paginated-list#paginatedlist'>PaginatedList</a>&#60;<a href='/reference/typescript-api/job-queue/job#job'>Job</a>&#62;&#62;`}   />

Returns a list of jobs according to the specified options.
### findManyById

<MemberInfo kind="method" type={`(ids: <a href='/reference/typescript-api/common/id#id'>ID</a>[]) => Promise&#60;<a href='/reference/typescript-api/job-queue/job#job'>Job</a>[]&#62;`}   />

Returns an array of jobs for the given ids.
### removeSettledJobs

<MemberInfo kind="method" type={`(queueNames?: string[], olderThan?: Date) => Promise&#60;number&#62;`}   />

Remove all settled jobs in the specified queues older than the given date.
If no queueName is passed, all queues will be considered. If no olderThan
date is passed, all jobs older than the current time will be removed.

Returns a promise of the number of jobs removed.
### cancelJob

<MemberInfo kind="method" type={`(jobId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/job-queue/job#job'>Job</a> | undefined&#62;`}   />




</div>


---

---
title: "JobBufferStorageStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## JobBufferStorageStrategy

<GenerationInfo sourceFile="packages/core/src/job-queue/job-buffer/job-buffer-storage-strategy.ts" sourceLine="19" packageName="@vendure/core" since="1.3.0" />

This strategy defines where to store jobs that have been collected by a
<a href='/reference/typescript-api/job-queue/job-buffer#jobbuffer'>JobBuffer</a>.

:::info

This is configured via the `jobQueueOptions.jobBufferStorageStrategy` property of
your VendureConfig.

:::

```ts title="Signature"
interface JobBufferStorageStrategy extends InjectableStrategy {
    add(bufferId: string, job: Job): Promise<Job>;
    bufferSize(bufferIds?: string[]): Promise<{ [bufferId: string]: number }>;
    flush(bufferIds?: string[]): Promise<{ [bufferId: string]: Job[] }>;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### add

<MemberInfo kind="method" type={`(bufferId: string, job: <a href='/reference/typescript-api/job-queue/job#job'>Job</a>) => Promise&#60;<a href='/reference/typescript-api/job-queue/job#job'>Job</a>&#62;`}   />

Persist a job to the storage medium. The storage format should
take into account the `bufferId` argument, as it is necessary to be
able to later retrieve jobs by that id.
### bufferSize

<MemberInfo kind="method" type={`(bufferIds?: string[]) => Promise&#60;{ [bufferId: string]: number }&#62;`}   />

Returns an object containing the number of buffered jobs arranged by bufferId.

Passing bufferIds limits the results to the specified bufferIds.
If the array is empty, sizes will be returned for _all_ bufferIds.

*Example*

```ts
const sizes = await myJobBufferStrategy.bufferSize(['buffer-1', 'buffer-2']);

// sizes = { 'buffer-1': 12, 'buffer-2': 3 }
```
### flush

<MemberInfo kind="method" type={`(bufferIds?: string[]) => Promise&#60;{ [bufferId: string]: <a href='/reference/typescript-api/job-queue/job#job'>Job</a>[] }&#62;`}   />

Clears all jobs from the storage medium which match the specified bufferIds (if the
array is empty, clear for _all_ bufferIds), and returns those jobs in an object
arranged by bufferId

*Example*

```ts
const result = await myJobBufferStrategy.flush(['buffer-1', 'buffer-2']);

// result = {
//   'buffer-1': [Job, Job, Job, ...],
//   'buffer-2': [Job, Job, Job, ...],
// };
```


</div>


---

---
title: "JobBuffer"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## JobBuffer

<GenerationInfo sourceFile="packages/core/src/job-queue/job-buffer/job-buffer.ts" sourceLine="83" packageName="@vendure/core" since="1.3.0" />

A JobBuffer is used to temporarily prevent jobs from being sent to the job queue for processing.
Instead, it collects certain jobs (as specified by the `collect()` method), and stores them.

How these buffered jobs are stored is determined by the configured <a href='/reference/typescript-api/job-queue/job-buffer-storage-strategy#jobbufferstoragestrategy'>JobBufferStorageStrategy</a>.

The JobBuffer can be thought of as a kind of "interceptor" of jobs. That is, when a JobBuffer is active,
it sits in between calls to `JobQueue.add()` and the actual adding of the job to the queue.

At some later point, the buffer can be flushed (by calling `JobQueue.flush()`), at which point all the jobs
that were collected into the buffer will be removed from the buffer and passed to the `JobBuffer.reduce()` method.
This method is able to perform additional logic to e.g. aggregate many jobs into a single job in order to de-duplicate
work.

*Example*

```ts
// This is a buffer which will collect all the
// 'apply-collection-filters' jobs and buffer them.
export class CollectionJobBuffer implements JobBuffer<ApplyCollectionFiltersJobData> {
  readonly id = 'apply-collection-filters-buffer';

  collect(job: Job): boolean {
    return job.queueName === 'apply-collection-filters';
  }


  // When the buffer gets flushed, this function will be passed all the collected jobs
  // and will reduce them down to a single job that has aggregated all of the collectionIds.
  reduce(collectedJobs: Array<Job<ApplyCollectionFiltersJobData>>): Array<Job<any>> {
    // Concatenate all the collectionIds from all the events that were buffered
    const collectionIdsToUpdate = collectedJobs.reduce((result, job) => {
      return [...result, ...job.data.collectionIds];
    }, [] as ID[]);

    const referenceJob = collectedJobs[0];

    // Create a new Job containing all the concatenated collectionIds,
    // de-duplicated to include each collectionId only once.
    const batchedCollectionJob = new Job<ApplyCollectionFiltersJobData>({
      ...referenceJob,
      id: undefined,
      data: {
        collectionIds: unique(collectionIdsToUpdate),
        ctx: referenceJob.data.ctx,
        applyToChangedVariantsOnly: referenceJob.data.applyToChangedVariantsOnly,
      },
    });

    // Only this single job will get added to the job queue
    return [batchedCollectionJob];
  }
}
```

A JobBuffer is used by adding it to the <a href='/reference/typescript-api/job-queue/job-queue-service#jobqueueservice'>JobQueueService</a>, at which point it will become active
and start collecting jobs.

At some later point, the buffer can be flushed, causing the buffered jobs to be passed through the
`reduce()` method and sent to the job queue.

*Example*

```ts
const collectionBuffer = new CollectionJobBuffer();

await this.jobQueueService.addBuffer(collectionBuffer);

// Here you can perform some work which would ordinarily
// trigger the 'apply-collection-filters' job, such as updating
// collection filters or changing ProductVariant prices.

await this.jobQueueService.flush(collectionBuffer);

await this.jobQueueService.removeBuffer(collectionBuffer);
```

```ts title="Signature"
interface JobBuffer<Data extends JobData<Data> = object> {
    readonly id: string;
    collect(job: Job<Data>): boolean | Promise<boolean>;
    reduce(collectedJobs: Array<Job<Data>>): Array<Job<Data>> | Promise<Array<Job<Data>>>;
}
```

<div className="members-wrapper">

### id

<MemberInfo kind="property" type={`string`}   />


### collect

<MemberInfo kind="method" type={`(job: <a href='/reference/typescript-api/job-queue/job#job'>Job</a>&#60;Data&#62;) => boolean | Promise&#60;boolean&#62;`}   />

This method is called whenever a job is added to the job queue. If it returns `true`, then
the job will be _buffered_ and _not_ added to the job queue. If it returns `false`, the job
will be added to the job queue as normal.
### reduce

<MemberInfo kind="method" type={`(collectedJobs: Array&#60;<a href='/reference/typescript-api/job-queue/job#job'>Job</a>&#60;Data&#62;&#62;) => Array&#60;<a href='/reference/typescript-api/job-queue/job#job'>Job</a>&#60;Data&#62;&#62; | Promise&#60;Array&#60;<a href='/reference/typescript-api/job-queue/job#job'>Job</a>&#60;Data&#62;&#62;&#62;`}   />

This method is called whenever the buffer gets flushed via a call to `JobQueueService.flush()`.
It allows logic to be run on the buffered jobs which enables optimizations such as
aggregating and de-duplicating the work of many jobs into one job.


</div>


---

---
title: "JobQueueOptions"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## JobQueueOptions

<GenerationInfo sourceFile="packages/core/src/config/vendure-config.ts" sourceLine="959" packageName="@vendure/core" />

Options related to the built-in job queue.

```ts title="Signature"
interface JobQueueOptions {
    jobQueueStrategy?: JobQueueStrategy;
    jobBufferStorageStrategy?: JobBufferStorageStrategy;
    activeQueues?: string[];
    prefix?: string;
}
```

<div className="members-wrapper">

### jobQueueStrategy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/job-queue/job-queue-strategy#jobqueuestrategy'>JobQueueStrategy</a>`} default={`<a href='/reference/typescript-api/job-queue/in-memory-job-queue-strategy#inmemoryjobqueuestrategy'>InMemoryJobQueueStrategy</a>`}   />

Defines how the jobs in the queue are persisted and accessed.
### jobBufferStorageStrategy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/job-queue/job-buffer-storage-strategy#jobbufferstoragestrategy'>JobBufferStorageStrategy</a>`}   />


### activeQueues

<MemberInfo kind="property" type={`string[]`}   />

Defines the queues that will run in this process.
This can be used to configure only certain queues to run in this process.
If its empty all queues will be run. Note: this option is primarily intended
to apply to the Worker process. Jobs will _always_ get published to the queue
regardless of this setting, but this setting determines whether they get
_processed_ or not.
### prefix

<MemberInfo kind="property" type={`string`}  since="1.5.0"  />

Prefixes all job queue names with the passed string. This is useful with multiple deployments
in cloud environments using services such as Amazon SQS or Google Cloud Tasks.

For example, we might have a staging and a production deployment in the same account/project and
each one will need its own task queue. We can achieve this with a prefix.


</div>


---

---
title: "JobQueueService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## JobQueueService

<GenerationInfo sourceFile="packages/core/src/job-queue/job-queue.service.ts" sourceLine="49" packageName="@vendure/core" />

The JobQueueService is used to create new <a href='/reference/typescript-api/job-queue/#jobqueue'>JobQueue</a> instances and access
existing jobs.

*Example*

```ts
// A service which transcodes video files
class VideoTranscoderService {

  private jobQueue: JobQueue<{ videoId: string; }>;

  async onModuleInit() {
    // The JobQueue is created on initialization
    this.jobQueue = await this.jobQueueService.createQueue({
      name: 'transcode-video',
      process: async job => {
        return await this.transcodeVideo(job.data.videoId);
      },
    });
  }

  addToTranscodeQueue(videoId: string) {
    this.jobQueue.add({ videoId, })
  }

  private async transcodeVideo(videoId: string) {
    // e.g. call some external transcoding service
  }

}
```

```ts title="Signature"
class JobQueueService implements OnModuleDestroy {
    constructor(configService: ConfigService, jobBufferService: JobBufferService)
    createQueue(options: CreateQueueOptions<Data>) => Promise<JobQueue<Data>>;
    start() => Promise<void>;
    addBuffer(buffer: JobBuffer<any>) => ;
    removeBuffer(buffer: JobBuffer<any>) => ;
    bufferSize(forBuffers: Array<JobBuffer<any> | string>) => Promise<{ [bufferId: string]: number }>;
    flush(forBuffers: Array<JobBuffer<any> | string>) => Promise<Job[]>;
    getJobQueues() => GraphQlJobQueue[];
}
```
* Implements: <code>OnModuleDestroy</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(configService: ConfigService, jobBufferService: JobBufferService) => JobQueueService`}   />


### createQueue

<MemberInfo kind="method" type={`(options: <a href='/reference/typescript-api/job-queue/types#createqueueoptions'>CreateQueueOptions</a>&#60;Data&#62;) => Promise&#60;<a href='/reference/typescript-api/job-queue/#jobqueue'>JobQueue</a>&#60;Data&#62;&#62;`}   />

Configures and creates a new <a href='/reference/typescript-api/job-queue/#jobqueue'>JobQueue</a> instance.
### start

<MemberInfo kind="method" type={`() => Promise&#60;void&#62;`}   />


### addBuffer

<MemberInfo kind="method" type={`(buffer: <a href='/reference/typescript-api/job-queue/job-buffer#jobbuffer'>JobBuffer</a>&#60;any&#62;) => `}  since="1.3.0"  />

Adds a <a href='/reference/typescript-api/job-queue/job-buffer#jobbuffer'>JobBuffer</a>, which will make it active and begin collecting
jobs to buffer.
### removeBuffer

<MemberInfo kind="method" type={`(buffer: <a href='/reference/typescript-api/job-queue/job-buffer#jobbuffer'>JobBuffer</a>&#60;any&#62;) => `}  since="1.3.0"  />

Removes a <a href='/reference/typescript-api/job-queue/job-buffer#jobbuffer'>JobBuffer</a>, prevent it from collecting and buffering any
subsequent jobs.
### bufferSize

<MemberInfo kind="method" type={`(forBuffers: Array&#60;<a href='/reference/typescript-api/job-queue/job-buffer#jobbuffer'>JobBuffer</a>&#60;any&#62; | string&#62;) => Promise&#60;{ [bufferId: string]: number }&#62;`}  since="1.3.0"  />

Returns an object containing the number of buffered jobs arranged by bufferId. This
can be used to decide whether a particular buffer has any jobs to flush.

Passing in JobBuffer instances _or_ ids limits the results to the specified JobBuffers.
If no argument is passed, sizes will be returned for _all_ JobBuffers.

*Example*

```ts
const sizes = await this.jobQueueService.bufferSize('buffer-1', 'buffer-2');

// sizes = { 'buffer-1': 12, 'buffer-2': 3 }
```
### flush

<MemberInfo kind="method" type={`(forBuffers: Array&#60;<a href='/reference/typescript-api/job-queue/job-buffer#jobbuffer'>JobBuffer</a>&#60;any&#62; | string&#62;) => Promise&#60;<a href='/reference/typescript-api/job-queue/job#job'>Job</a>[]&#62;`}  since="1.3.0"  />

Flushes the specified buffers, which means that the buffer is cleared and the jobs get
sent to the job queue for processing. Before sending the jobs to the job queue,
they will be passed through each JobBuffer's `reduce()` method, which is can be used
to optimize the amount of work to be done by e.g. de-duplicating identical jobs or
aggregating data over the collected jobs.

Passing in JobBuffer instances _or_ ids limits the action to the specified JobBuffers.
If no argument is passed, _all_ JobBuffers will be flushed.

Returns an array of all Jobs which were added to the job queue.
### getJobQueues

<MemberInfo kind="method" type={`() => GraphQlJobQueue[]`}   />

Returns an array of `{ name: string; running: boolean; }` for each
registered JobQueue.


</div>


---

---
title: "JobQueueStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## JobQueueStrategy

<GenerationInfo sourceFile="packages/core/src/config/job-queue/job-queue-strategy.ts" sourceLine="24" packageName="@vendure/core" />

Defines how the jobs in the <a href='/reference/typescript-api/job-queue/job-queue-service#jobqueueservice'>JobQueueService</a> are persisted and
accessed. Custom strategies can be defined to make use of external
services such as Redis.

:::info

This is configured via the `jobQueueOptions.jobQueueStrategy` property of
your VendureConfig.

:::

```ts title="Signature"
interface JobQueueStrategy extends InjectableStrategy {
    add<Data extends JobData<Data> = object>(job: Job<Data>, jobOptions?: JobQueueStrategyJobOptions<Data>): Promise<Job<Data>>;
    start<Data extends JobData<Data> = object>(
        queueName: string,
        process: (job: Job<Data>) => Promise<any>,
    ): Promise<void>;
    stop<Data extends JobData<Data> = object>(
        queueName: string,
        process: (job: Job<Data>) => Promise<any>,
    ): Promise<void>;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### add

<MemberInfo kind="method" type={`(job: <a href='/reference/typescript-api/job-queue/job#job'>Job</a>&#60;Data&#62;, jobOptions?: JobQueueStrategyJobOptions&#60;Data&#62;) => Promise&#60;<a href='/reference/typescript-api/job-queue/job#job'>Job</a>&#60;Data&#62;&#62;`}   />

Add a new job to the queue.
### start

<MemberInfo kind="method" type={`(queueName: string, process: (job: <a href='/reference/typescript-api/job-queue/job#job'>Job</a>&#60;Data&#62;) =&#62; Promise&#60;any&#62;) => Promise&#60;void&#62;`}   />

Start the job queue
### stop

<MemberInfo kind="method" type={`(queueName: string, process: (job: <a href='/reference/typescript-api/job-queue/job#job'>Job</a>&#60;Data&#62;) =&#62; Promise&#60;any&#62;) => Promise&#60;void&#62;`}   />

Stops a queue from running. Its not guaranteed to stop immediately.


</div>


---

---
title: "Job"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## Job

<GenerationInfo sourceFile="packages/core/src/job-queue/job.ts" sourceLine="37" packageName="@vendure/core" />

A Job represents a piece of work to be run in the background, i.e. outside the request-response cycle.
It is intended to be used for long-running work triggered by API requests. Jobs should now generally
be directly instantiated. Rather, the <a href='/reference/typescript-api/job-queue/#jobqueue'>JobQueue</a> `add()` method should be used to create and
add a new Job to a queue.

```ts title="Signature"
class Job<T extends JobData<T> = any> {
    readonly id: number | string | null;
    readonly queueName: string;
    readonly retries: number;
    readonly createdAt: Date;
    name: string
    data: T
    state: JobState
    progress: number
    result: any
    error: any
    isSettled: boolean
    startedAt: Date | undefined
    settledAt: Date | undefined
    duration: number
    attempts: number
    constructor(config: JobConfig<T>)
    start() => ;
    setProgress(percent: number) => ;
    complete(result?: any) => ;
    fail(err?: any) => ;
    cancel() => ;
    defer() => ;
    on(eventType: JobEventType, listener: JobEventListener<T>) => ;
    off(eventType: JobEventType, listener: JobEventListener<T>) => ;
}
```

<div className="members-wrapper">

### id

<MemberInfo kind="property" type={`number | string | null`}   />


### queueName

<MemberInfo kind="property" type={`string`}   />


### retries

<MemberInfo kind="property" type={`number`}   />


### createdAt

<MemberInfo kind="property" type={`Date`}   />


### name

<MemberInfo kind="property" type={`string`}   />


### data

<MemberInfo kind="property" type={`T`}   />


### state

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/job-state#jobstate'>JobState</a>`}   />


### progress

<MemberInfo kind="property" type={`number`}   />


### result

<MemberInfo kind="property" type={`any`}   />


### error

<MemberInfo kind="property" type={`any`}   />


### isSettled

<MemberInfo kind="property" type={`boolean`}   />


### startedAt

<MemberInfo kind="property" type={`Date | undefined`}   />


### settledAt

<MemberInfo kind="property" type={`Date | undefined`}   />


### duration

<MemberInfo kind="property" type={`number`}   />


### attempts

<MemberInfo kind="property" type={`number`}   />


### constructor

<MemberInfo kind="method" type={`(config: <a href='/reference/typescript-api/job-queue/types#jobconfig'>JobConfig</a>&#60;T&#62;) => Job`}   />


### start

<MemberInfo kind="method" type={`() => `}   />

Calling this signifies that the job work has started. This method should be
called in the <a href='/reference/typescript-api/job-queue/job-queue-strategy#jobqueuestrategy'>JobQueueStrategy</a> `next()` method.
### setProgress

<MemberInfo kind="method" type={`(percent: number) => `}   />

Sets the progress (0 - 100) of the job.
### complete

<MemberInfo kind="method" type={`(result?: any) => `}   />

Calling this method signifies that the job succeeded. The result
will be stored in the `Job.result` property.
### fail

<MemberInfo kind="method" type={`(err?: any) => `}   />

Calling this method signifies that the job failed.
### cancel

<MemberInfo kind="method" type={`() => `}   />


### defer

<MemberInfo kind="method" type={`() => `}   />

Sets a RUNNING job back to PENDING. Should be used when the JobQueue is being
destroyed before the job has been completed.
### on

<MemberInfo kind="method" type={`(eventType: <a href='/reference/typescript-api/job-queue/job#jobeventtype'>JobEventType</a>, listener: <a href='/reference/typescript-api/job-queue/job#jobeventlistener'>JobEventListener</a>&#60;T&#62;) => `}   />

Used to register event handler for job events
### off

<MemberInfo kind="method" type={`(eventType: <a href='/reference/typescript-api/job-queue/job#jobeventtype'>JobEventType</a>, listener: <a href='/reference/typescript-api/job-queue/job#jobeventlistener'>JobEventListener</a>&#60;T&#62;) => `}   />




</div>


## JobEventType

<GenerationInfo sourceFile="packages/core/src/job-queue/job.ts" sourceLine="15" packageName="@vendure/core" />

An event raised by a Job.

```ts title="Signature"
type JobEventType = 'progress'
```


## JobEventListener

<GenerationInfo sourceFile="packages/core/src/job-queue/job.ts" sourceLine="24" packageName="@vendure/core" />

The signature of the event handler expected by the `Job.on()` method.

```ts title="Signature"
type JobEventListener<T extends JobData<T>> = (job: Job<T>) => void
```


---

---
title: "PollingJobQueueStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## PollingJobQueueStrategy

<GenerationInfo sourceFile="packages/core/src/job-queue/polling-job-queue-strategy.ts" sourceLine="242" packageName="@vendure/core" />

This class allows easier implementation of <a href='/reference/typescript-api/job-queue/job-queue-strategy#jobqueuestrategy'>JobQueueStrategy</a> in a polling style.
Instead of providing <a href='/reference/typescript-api/job-queue/job-queue-strategy#jobqueuestrategy'>JobQueueStrategy</a> `start()` you should provide a `next` method.

This class should be extended by any strategy which does not support a push-based system
to notify on new jobs. It is used by the <a href='/reference/typescript-api/job-queue/sql-job-queue-strategy#sqljobqueuestrategy'>SqlJobQueueStrategy</a> and <a href='/reference/typescript-api/job-queue/in-memory-job-queue-strategy#inmemoryjobqueuestrategy'>InMemoryJobQueueStrategy</a>.

```ts title="Signature"
class PollingJobQueueStrategy extends InjectableJobQueueStrategy {
    public concurrency: number;
    public pollInterval: number | ((queueName: string) => number);
    public setRetries: (queueName: string, job: Job) => number;
    public backOffStrategy?: BackoffStrategy;
    public gracefulShutdownTimeout: number;
    protected activeQueues = new QueueNameProcessStorage<ActiveQueue<any>>();
    constructor(config?: PollingJobQueueStrategyConfig)
    constructor(concurrency?: number, pollInterval?: number)
    constructor(concurrencyOrConfig?: number | PollingJobQueueStrategyConfig, maybePollInterval?: number)
    start(queueName: string, process: (job: Job<Data>) => Promise<any>) => ;
    stop(queueName: string, process: (job: Job<Data>) => Promise<any>) => ;
    cancelJob(jobId: ID) => Promise<Job | undefined>;
    next(queueName: string) => Promise<Job | undefined>;
    update(job: Job) => Promise<void>;
    findOne(id: ID) => Promise<Job | undefined>;
}
```
* Extends: <code>InjectableJobQueueStrategy</code>



<div className="members-wrapper">

### concurrency

<MemberInfo kind="property" type={`number`}   />


### pollInterval

<MemberInfo kind="property" type={`number | ((queueName: string) =&#62; number)`}   />


### setRetries

<MemberInfo kind="property" type={`(queueName: string, job: <a href='/reference/typescript-api/job-queue/job#job'>Job</a>) =&#62; number`}   />


### backOffStrategy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/job-queue/types#backoffstrategy'>BackoffStrategy</a>`}   />


### gracefulShutdownTimeout

<MemberInfo kind="property" type={`number`}   />


### activeQueues

<MemberInfo kind="property" type={``}   />


### constructor

<MemberInfo kind="method" type={`(config?: PollingJobQueueStrategyConfig) => PollingJobQueueStrategy`}   />


### constructor

<MemberInfo kind="method" type={`(concurrency?: number, pollInterval?: number) => PollingJobQueueStrategy`}   />


### constructor

<MemberInfo kind="method" type={`(concurrencyOrConfig?: number | PollingJobQueueStrategyConfig, maybePollInterval?: number) => PollingJobQueueStrategy`}   />


### start

<MemberInfo kind="method" type={`(queueName: string, process: (job: <a href='/reference/typescript-api/job-queue/job#job'>Job</a>&#60;Data&#62;) =&#62; Promise&#60;any&#62;) => `}   />


### stop

<MemberInfo kind="method" type={`(queueName: string, process: (job: <a href='/reference/typescript-api/job-queue/job#job'>Job</a>&#60;Data&#62;) =&#62; Promise&#60;any&#62;) => `}   />


### cancelJob

<MemberInfo kind="method" type={`(jobId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/job-queue/job#job'>Job</a> | undefined&#62;`}   />


### next

<MemberInfo kind="method" type={`(queueName: string) => Promise&#60;<a href='/reference/typescript-api/job-queue/job#job'>Job</a> | undefined&#62;`}   />

Should return the next job in the given queue. The implementation is
responsible for returning the correct job according to the time of
creation.
### update

<MemberInfo kind="method" type={`(job: <a href='/reference/typescript-api/job-queue/job#job'>Job</a>) => Promise&#60;void&#62;`}   />

Update the job details in the store.
### findOne

<MemberInfo kind="method" type={`(id: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/job-queue/job#job'>Job</a> | undefined&#62;`}   />

Returns a job by its id.


</div>


---

---
title: "SqlJobQueueStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## SqlJobQueueStrategy

<GenerationInfo sourceFile="packages/core/src/plugin/default-job-queue-plugin/sql-job-queue-strategy.ts" sourceLine="22" packageName="@vendure/core" />

A <a href='/reference/typescript-api/job-queue/job-queue-strategy#jobqueuestrategy'>JobQueueStrategy</a> which uses the configured SQL database to persist jobs in the queue.
This strategy is used by the <a href='/reference/typescript-api/job-queue/default-job-queue-plugin#defaultjobqueueplugin'>DefaultJobQueuePlugin</a>.

```ts title="Signature"
class SqlJobQueueStrategy extends PollingJobQueueStrategy implements InspectableJobQueueStrategy {
    init(injector: Injector) => ;
    destroy() => ;
    add(job: Job<Data>, jobOptions?: JobQueueStrategyJobOptions<Data>) => Promise<Job<Data>>;
    next(queueName: string) => Promise<Job | undefined>;
    update(job: Job<any>) => Promise<void>;
    findMany(options?: JobListOptions) => Promise<PaginatedList<Job>>;
    findOne(id: ID) => Promise<Job | undefined>;
    findManyById(ids: ID[]) => Promise<Job[]>;
    removeSettledJobs(queueNames: string[] = [], olderThan?: Date) => ;
}
```
* Extends: <code><a href='/reference/typescript-api/job-queue/polling-job-queue-strategy#pollingjobqueuestrategy'>PollingJobQueueStrategy</a></code>


* Implements: <code><a href='/reference/typescript-api/job-queue/inspectable-job-queue-strategy#inspectablejobqueuestrategy'>InspectableJobQueueStrategy</a></code>



<div className="members-wrapper">

### init

<MemberInfo kind="method" type={`(injector: <a href='/reference/typescript-api/common/injector#injector'>Injector</a>) => `}   />


### destroy

<MemberInfo kind="method" type={`() => `}   />


### add

<MemberInfo kind="method" type={`(job: <a href='/reference/typescript-api/job-queue/job#job'>Job</a>&#60;Data&#62;, jobOptions?: JobQueueStrategyJobOptions&#60;Data&#62;) => Promise&#60;<a href='/reference/typescript-api/job-queue/job#job'>Job</a>&#60;Data&#62;&#62;`}   />


### next

<MemberInfo kind="method" type={`(queueName: string) => Promise&#60;<a href='/reference/typescript-api/job-queue/job#job'>Job</a> | undefined&#62;`}   />


### update

<MemberInfo kind="method" type={`(job: <a href='/reference/typescript-api/job-queue/job#job'>Job</a>&#60;any&#62;) => Promise&#60;void&#62;`}   />


### findMany

<MemberInfo kind="method" type={`(options?: JobListOptions) => Promise&#60;<a href='/reference/typescript-api/common/paginated-list#paginatedlist'>PaginatedList</a>&#60;<a href='/reference/typescript-api/job-queue/job#job'>Job</a>&#62;&#62;`}   />


### findOne

<MemberInfo kind="method" type={`(id: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/job-queue/job#job'>Job</a> | undefined&#62;`}   />


### findManyById

<MemberInfo kind="method" type={`(ids: <a href='/reference/typescript-api/common/id#id'>ID</a>[]) => Promise&#60;<a href='/reference/typescript-api/job-queue/job#job'>Job</a>[]&#62;`}   />


### removeSettledJobs

<MemberInfo kind="method" type={`(queueNames: string[] = [], olderThan?: Date) => `}   />




</div>


---

---
title: "SubscribableJob"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## SubscribableJob

<GenerationInfo sourceFile="packages/core/src/job-queue/subscribable-job.ts" sourceLine="59" packageName="@vendure/core" />

This is a type of Job object that allows you to subscribe to updates to the Job. It is returned
by the <a href='/reference/typescript-api/job-queue/#jobqueue'>JobQueue</a>'s `add()` method. Note that the subscription capability is only supported
if the <a href='/reference/typescript-api/job-queue/job-queue-strategy#jobqueuestrategy'>JobQueueStrategy</a> implements the <a href='/reference/typescript-api/job-queue/inspectable-job-queue-strategy#inspectablejobqueuestrategy'>InspectableJobQueueStrategy</a> interface (e.g.
the <a href='/reference/typescript-api/job-queue/sql-job-queue-strategy#sqljobqueuestrategy'>SqlJobQueueStrategy</a> does support this).

```ts title="Signature"
class SubscribableJob<T extends JobData<T> = any> extends Job<T> {
    constructor(job: Job<T>, jobQueueStrategy: JobQueueStrategy)
    updates(options?: JobUpdateOptions) => Observable<JobUpdate<T>>;
}
```
* Extends: <code><a href='/reference/typescript-api/job-queue/job#job'>Job</a>&#60;T&#62;</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(job: <a href='/reference/typescript-api/job-queue/job#job'>Job</a>&#60;T&#62;, jobQueueStrategy: <a href='/reference/typescript-api/job-queue/job-queue-strategy#jobqueuestrategy'>JobQueueStrategy</a>) => SubscribableJob`}   />


### updates

<MemberInfo kind="method" type={`(options?: <a href='/reference/typescript-api/job-queue/types#jobupdateoptions'>JobUpdateOptions</a>) => Observable&#60;<a href='/reference/typescript-api/job-queue/types#jobupdate'>JobUpdate</a>&#60;T&#62;&#62;`}   />

Returns an Observable stream of updates to the Job. Works by polling the current JobQueueStrategy's `findOne()` method
to obtain updates. If the updates are not subscribed to, then no polling occurs.

Polling interval, timeout and other options may be configured with an options arguments <a href='/reference/typescript-api/job-queue/types#jobupdateoptions'>JobUpdateOptions</a>.


</div>


---

---
title: "Types"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## BackoffStrategy

<GenerationInfo sourceFile="packages/core/src/job-queue/polling-job-queue-strategy.ts" sourceLine="22" packageName="@vendure/core" />

Defines the backoff strategy used when retrying failed jobs. Returns the delay in
ms that should pass before the failed job is retried.

```ts title="Signature"
type BackoffStrategy = (queueName: string, attemptsMade: number, job: Job) => number
```


## JobUpdate

<GenerationInfo sourceFile="packages/core/src/job-queue/subscribable-job.ts" sourceLine="23" packageName="@vendure/core" />

Job update status as returned from the <a href='/reference/typescript-api/job-queue/subscribable-job#subscribablejob'>SubscribableJob</a>'s `update()` method.

```ts title="Signature"
type JobUpdate<T extends JobData<T>> = Pick<
    Job<T>,
    'id' | 'state' | 'progress' | 'result' | 'error' | 'data'
>
```


## JobUpdateOptions

<GenerationInfo sourceFile="packages/core/src/job-queue/subscribable-job.ts" sourceLine="35" packageName="@vendure/core" />

Job update options, that you can specify by calling <a href='/reference/typescript-api/job-queue/subscribable-job#subscribablejob'>SubscribableJob</a> `updates` method.

```ts title="Signature"
type JobUpdateOptions = {
    pollInterval?: number;
    timeoutMs?: number;
    errorOnFail?: boolean;
}
```

<div className="members-wrapper">

### pollInterval

<MemberInfo kind="property" type={`number`}   />


### timeoutMs

<MemberInfo kind="property" type={`number`}   />


### errorOnFail

<MemberInfo kind="property" type={`boolean`}   />




</div>


## CreateQueueOptions

<GenerationInfo sourceFile="packages/core/src/job-queue/types.ts" sourceLine="15" packageName="@vendure/core" />

Used to configure a new <a href='/reference/typescript-api/job-queue/#jobqueue'>JobQueue</a> instance.

```ts title="Signature"
interface CreateQueueOptions<T extends JobData<T>> {
    name: string;
    process: (job: Job<T>) => Promise<any>;
}
```

<div className="members-wrapper">

### name

<MemberInfo kind="property" type={`string`}   />

The name of the queue, e.g. "image processing", "re-indexing" etc.
### process

<MemberInfo kind="property" type={`(job: <a href='/reference/typescript-api/job-queue/job#job'>Job</a>&#60;T&#62;) =&#62; Promise&#60;any&#62;`}   />

Defines the work to be done for each job in the queue. The returned promise
should resolve when the job is complete, or be rejected in case of an error.


</div>


## JobData

<GenerationInfo sourceFile="packages/core/src/job-queue/types.ts" sourceLine="37" packageName="@vendure/core" />

A JSON-serializable data type which provides a <a href='/reference/typescript-api/job-queue/job#job'>Job</a>with the data it needs to be processed.

```ts title="Signature"
type JobData<T> = JsonCompatible<T>
```


## JobConfig

<GenerationInfo sourceFile="packages/core/src/job-queue/types.ts" sourceLine="46" packageName="@vendure/core" />

Used to instantiate a new <a href='/reference/typescript-api/job-queue/job#job'>Job</a>

```ts title="Signature"
interface JobConfig<T extends JobData<T>> {
    queueName: string;
    data: T;
    retries?: number;
    attempts?: number;
    id?: ID;
    state?: JobState;
    progress?: number;
    result?: any;
    error?: any;
    createdAt?: Date;
    startedAt?: Date;
    settledAt?: Date;
}
```

<div className="members-wrapper">

### queueName

<MemberInfo kind="property" type={`string`}   />


### data

<MemberInfo kind="property" type={`T`}   />


### retries

<MemberInfo kind="property" type={`number`}   />


### attempts

<MemberInfo kind="property" type={`number`}   />


### id

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a>`}   />


### state

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/job-state#jobstate'>JobState</a>`}   />


### progress

<MemberInfo kind="property" type={`number`}   />


### result

<MemberInfo kind="property" type={`any`}   />


### error

<MemberInfo kind="property" type={`any`}   />


### createdAt

<MemberInfo kind="property" type={`Date`}   />


### startedAt

<MemberInfo kind="property" type={`Date`}   />


### settledAt

<MemberInfo kind="property" type={`Date`}   />




</div>


---

---
title: "DefaultLogger"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DefaultLogger

<GenerationInfo sourceFile="packages/core/src/config/logger/default-logger.ts" sourceLine="25" packageName="@vendure/core" />

The default logger, which logs to the console (stdout) with optional timestamps. Since this logger is part of the
default Vendure configuration, you do not need to specify it explicitly in your server config. You would only need
to specify it if you wish to change the log level (which defaults to `LogLevel.Info`) or remove the timestamp.

*Example*

```ts
import { DefaultLogger, LogLevel, VendureConfig } from '@vendure/core';

export config: VendureConfig = {
    // ...
    logger: new DefaultLogger({ level: LogLevel.Debug, timestamp: false }),
}
```

```ts title="Signature"
class DefaultLogger implements VendureLogger {
    constructor(options?: { level?: LogLevel; timestamp?: boolean })
    setDefaultContext(defaultContext: string) => ;
    error(message: string, context?: string, trace?: string | undefined) => void;
    warn(message: string, context?: string) => void;
    info(message: string, context?: string) => void;
    verbose(message: string, context?: string) => void;
    debug(message: string, context?: string) => void;
}
```
* Implements: <code><a href='/reference/typescript-api/logger/vendure-logger#vendurelogger'>VendureLogger</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(options?: { level?: <a href='/reference/typescript-api/logger/log-level#loglevel'>LogLevel</a>; timestamp?: boolean }) => DefaultLogger`}   />


### setDefaultContext

<MemberInfo kind="method" type={`(defaultContext: string) => `}   />


### error

<MemberInfo kind="method" type={`(message: string, context?: string, trace?: string | undefined) => void`}   />


### warn

<MemberInfo kind="method" type={`(message: string, context?: string) => void`}   />


### info

<MemberInfo kind="method" type={`(message: string, context?: string) => void`}   />


### verbose

<MemberInfo kind="method" type={`(message: string, context?: string) => void`}   />


### debug

<MemberInfo kind="method" type={`(message: string, context?: string) => void`}   />




</div>


---

---
title: "Logger"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## Logger

<GenerationInfo sourceFile="packages/core/src/config/logger/vendure-logger.ts" sourceLine="136" packageName="@vendure/core" />

The Logger is responsible for all logging in a Vendure application.

It is intended to be used as a static class:

*Example*

```ts
import { Logger } from '@vendure/core';

Logger.info(`Some log message`, 'My Vendure Plugin');
```

The actual implementation - where the logs are written to - is defined by the <a href='/reference/typescript-api/logger/vendure-logger#vendurelogger'>VendureLogger</a>
instance configured in the <a href='/reference/typescript-api/configuration/vendure-config#vendureconfig'>VendureConfig</a>. By default, the <a href='/reference/typescript-api/logger/default-logger#defaultlogger'>DefaultLogger</a> is used, which
logs to the console.

## Implementing a custom logger

A custom logger can be passed to the `logger` config option by creating a class which implements the
<a href='/reference/typescript-api/logger/vendure-logger#vendurelogger'>VendureLogger</a> interface. For example, here is how you might go about implementing a logger which
logs to a file:

*Example*

```ts
import { VendureLogger } from '@vendure/core';
import fs from 'fs';

// A simple custom logger which writes all logs to a file.
export class SimpleFileLogger implements VendureLogger {
    private logfile: fs.WriteStream;

    constructor(logfileLocation: string) {
        this.logfile = fs.createWriteStream(logfileLocation, { flags: 'w' });
    }

    error(message: string, context?: string) {
        this.logfile.write(`ERROR: [${context}] ${message}\n`);
    }
    warn(message: string, context?: string) {
        this.logfile.write(`WARN: [${context}] ${message}\n`);
    }
    info(message: string, context?: string) {
        this.logfile.write(`INFO: [${context}] ${message}\n`);
    }
    verbose(message: string, context?: string) {
        this.logfile.write(`VERBOSE: [${context}] ${message}\n`);
    }
    debug(message: string, context?: string) {
        this.logfile.write(`DEBUG: [${context}] ${message}\n`);
    }
}

// in the VendureConfig
export const config = {
    // ...
    logger: new SimpleFileLogger('server.log'),
}
```

```ts title="Signature"
class Logger implements LoggerService {
    logger: VendureLogger
    error(message: string, context?: string, trace?: string) => void;
    warn(message: string, context?: string) => void;
    info(message: string, context?: string) => void;
    verbose(message: string, context?: string) => void;
    debug(message: string, context?: string) => void;
}
```
* Implements: <code>LoggerService</code>



<div className="members-wrapper">

### logger

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/logger/vendure-logger#vendurelogger'>VendureLogger</a>`}   />


### error

<MemberInfo kind="method" type={`(message: string, context?: string, trace?: string) => void`}   />


### warn

<MemberInfo kind="method" type={`(message: string, context?: string) => void`}   />


### info

<MemberInfo kind="method" type={`(message: string, context?: string) => void`}   />


### verbose

<MemberInfo kind="method" type={`(message: string, context?: string) => void`}   />


### debug

<MemberInfo kind="method" type={`(message: string, context?: string) => void`}   />




</div>


---

---
title: "LogLevel"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## LogLevel

<GenerationInfo sourceFile="packages/core/src/config/logger/vendure-logger.ts" sourceLine="9" packageName="@vendure/core" />

An enum of valid logging levels.

```ts title="Signature"
enum LogLevel {
    // Log Errors only. These are usually indicative of some potentially
serious issue, so should be acted upon.
    Error = 0
    // Warnings indicate that some situation may require investigation
and handling. But not as serious as an Error.
    Warn = 1
    // Logs general information such as startup messages.
    Info = 2
    // Logs additional information
    Verbose = 3
    // Logs detailed info useful in debug scenarios, including stack traces for
all errors. In production this would probably generate too much noise.
    Debug = 4
}
```


---

---
title: "VendureLogger"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## VendureLogger

<GenerationInfo sourceFile="packages/core/src/config/logger/vendure-logger.ts" sourceLine="47" packageName="@vendure/core" />

The VendureLogger interface defines the shape of a logger service which may be provided in
the config.

```ts title="Signature"
interface VendureLogger {
    error(message: string, context?: string, trace?: string): void;
    warn(message: string, context?: string): void;
    info(message: string, context?: string): void;
    verbose(message: string, context?: string): void;
    debug(message: string, context?: string): void;
    setDefaultContext?(defaultContext: string): void;
}
```

<div className="members-wrapper">

### error

<MemberInfo kind="method" type={`(message: string, context?: string, trace?: string) => void`}   />


### warn

<MemberInfo kind="method" type={`(message: string, context?: string) => void`}   />


### info

<MemberInfo kind="method" type={`(message: string, context?: string) => void`}   />


### verbose

<MemberInfo kind="method" type={`(message: string, context?: string) => void`}   />


### debug

<MemberInfo kind="method" type={`(message: string, context?: string) => void`}   />


### setDefaultContext

<MemberInfo kind="method" type={`(defaultContext: string) => void`}   />




</div>


---

---
title: "GenerateMigration"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## generateMigration

<GenerationInfo sourceFile="packages/core/src/migrate.ts" sourceLine="118" packageName="@vendure/core" />

Generates a new migration file based on any schema changes (e.g. adding or removing CustomFields).
See [TypeORM migration docs](https://typeorm.io/#/migrations) for more information about the
underlying migration mechanism.

```ts title="Signature"
function generateMigration(userConfig: Partial<VendureConfig>, options: MigrationOptions): Promise<string | undefined>
```
Parameters

### userConfig

<MemberInfo kind="parameter" type={`Partial&#60;<a href='/reference/typescript-api/configuration/vendure-config#vendureconfig'>VendureConfig</a>&#62;`} />

### options

<MemberInfo kind="parameter" type={`<a href='/reference/typescript-api/migration/migration-options#migrationoptions'>MigrationOptions</a>`} />



---

---
title: "Migration"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "MigrationOptions"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## MigrationOptions

<GenerationInfo sourceFile="packages/core/src/migrate.ts" sourceLine="19" packageName="@vendure/core" />

Configuration for generating a new migration script via <a href='/reference/typescript-api/migration/generate-migration#generatemigration'>generateMigration</a>.

```ts title="Signature"
interface MigrationOptions {
    name: string;
    outputDir?: string;
}
```

<div className="members-wrapper">

### name

<MemberInfo kind="property" type={`string`}   />

The name of the migration. The resulting migration script will be named
`{TIMESTAMP}-{name}.ts`.
### outputDir

<MemberInfo kind="property" type={`string`}   />

The output directory of the generated migration scripts.


</div>


---

---
title: "RevertLastMigration"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## revertLastMigration

<GenerationInfo sourceFile="packages/core/src/migrate.ts" sourceLine="89" packageName="@vendure/core" />

Reverts the last applied database migration. See [TypeORM migration docs](https://typeorm.io/#/migrations)
for more information about the underlying migration mechanism.

```ts title="Signature"
function revertLastMigration(userConfig: Partial<VendureConfig>): void
```
Parameters

### userConfig

<MemberInfo kind="parameter" type={`Partial&#60;<a href='/reference/typescript-api/configuration/vendure-config#vendureconfig'>VendureConfig</a>&#62;`} />



---

---
title: "RunMigrations"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## runMigrations

<GenerationInfo sourceFile="packages/core/src/migrate.ts" sourceLine="40" packageName="@vendure/core" />

Runs any pending database migrations. See [TypeORM migration docs](https://typeorm.io/#/migrations)
for more information about the underlying migration mechanism.

```ts title="Signature"
function runMigrations(userConfig: Partial<VendureConfig>): Promise<string[]>
```
Parameters

### userConfig

<MemberInfo kind="parameter" type={`Partial&#60;<a href='/reference/typescript-api/configuration/vendure-config#vendureconfig'>VendureConfig</a>&#62;`} />



---

---
title: "BigIntMoneyStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## BigIntMoneyStrategy

<GenerationInfo sourceFile="packages/core/src/config/entity/bigint-money-strategy.ts" sourceLine="18" packageName="@vendure/core" since="2.0.0" />

A <a href='/reference/typescript-api/money/money-strategy#moneystrategy'>MoneyStrategy</a> that stores monetary values as a `bigint` type in the database, which
allows values up to ~9 quadrillion to be stored (limited by JavaScript's `MAX_SAFE_INTEGER` limit).

This strategy also slightly differs in the way rounding is performed, with rounding being done _after_
multiplying the unit price, rather than before (as is the case with the <a href='/reference/typescript-api/money/default-money-strategy#defaultmoneystrategy'>DefaultMoneyStrategy</a>.

```ts title="Signature"
class BigIntMoneyStrategy implements MoneyStrategy {
    readonly moneyColumnOptions: ColumnOptions = {
        type: 'bigint',
        transformer: {
            to: (entityValue: number) => {
                return entityValue;
            },
            from: (databaseValue: string): number => {
                if (databaseValue == null) {
                    return databaseValue;
                }
                const intVal = Number.parseInt(databaseValue, 10);
                if (!Number.isSafeInteger(intVal)) {
                    Logger.warn(`Monetary value ${databaseValue} is not a safe integer!`);
                }
                if (Number.isNaN(intVal)) {
                    Logger.warn(`Monetary value ${databaseValue} is not a number!`);
                }
                return intVal;
            },
        },
    };
    precision = 2;
    round(value: number, quantity:  = 1) => number;
}
```
* Implements: <code><a href='/reference/typescript-api/money/money-strategy#moneystrategy'>MoneyStrategy</a></code>



<div className="members-wrapper">

### moneyColumnOptions

<MemberInfo kind="property" type={`ColumnOptions`}   />


### precision

<MemberInfo kind="property" type={``}   />


### round

<MemberInfo kind="method" type={`(value: number, quantity:  = 1) => number`}   />




</div>


---

---
title: "DefaultMoneyStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DefaultMoneyStrategy

<GenerationInfo sourceFile="packages/core/src/config/entity/default-money-strategy.ts" sourceLine="14" packageName="@vendure/core" since="2.0.0" />

A <a href='/reference/typescript-api/money/money-strategy#moneystrategy'>MoneyStrategy</a> that stores monetary values as a `int` type in the database.
The storage configuration and rounding logic replicates the behaviour of Vendure pre-2.0.

```ts title="Signature"
class DefaultMoneyStrategy implements MoneyStrategy {
    readonly moneyColumnOptions: ColumnOptions = {
        type: 'int',
    };
    readonly precision: number = 2;
    round(value: number, quantity:  = 1) => number;
}
```
* Implements: <code><a href='/reference/typescript-api/money/money-strategy#moneystrategy'>MoneyStrategy</a></code>



<div className="members-wrapper">

### moneyColumnOptions

<MemberInfo kind="property" type={`ColumnOptions`}   />


### precision

<MemberInfo kind="property" type={`number`}   />


### round

<MemberInfo kind="method" type={`(value: number, quantity:  = 1) => number`}   />




</div>


---

---
title: "Money"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "Money Decorator"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## Money

<GenerationInfo sourceFile="packages/core/src/entity/money.decorator.ts" sourceLine="26" packageName="@vendure/core" since="2.0.0" />

Use this decorator for any entity field that is storing a monetary value.
This allows the column type to be defined by the configured <a href='/reference/typescript-api/money/money-strategy#moneystrategy'>MoneyStrategy</a>.

```ts title="Signature"
function Money(options?: MoneyColumnOptions): void
```
Parameters

### options

<MemberInfo kind="parameter" type={`MoneyColumnOptions`} />



---

---
title: "MoneyStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## MoneyStrategy

<GenerationInfo sourceFile="packages/core/src/config/entity/money-strategy.ts" sourceLine="63" packageName="@vendure/core" since="2.0.0" />

The MoneyStrategy defines how monetary values are stored and manipulated. The MoneyStrategy
is defined in <a href='/reference/typescript-api/configuration/entity-options#entityoptions'>EntityOptions</a>:

*Example*

```ts
const config: VendureConfig = {
  entityOptions: {
    moneyStrategy: new MyCustomMoneyStrategy(),
  }
};
```

## Range

The <a href='/reference/typescript-api/money/default-money-strategy#defaultmoneystrategy'>DefaultMoneyStrategy</a> uses an `int` field in the database, which puts an
effective limit of ~21.4 million on any stored value. For certain use cases
(e.g. business sales with very high amounts, or currencies with very large
denominations), this may cause issues. In this case, you can use the
<a href='/reference/typescript-api/money/big-int-money-strategy#bigintmoneystrategy'>BigIntMoneyStrategy</a> which will use the `bigint` type to store monetary values,
giving an effective upper limit of over 9 quadrillion.

## Precision

Both the `DefaultMoneyStrategy` and `BigIntMoneyStrategy` store monetary values as integers, representing
the price in the minor units of the currency (i.e. _cents_ in USD or _pennies_ in GBP).

Since v2.2.0, you can configure the precision of the stored values via the `precision` property of the
strategy. Changing the precision has **no effect** on the stored value. It is merely a hint to the
UI as to how many decimal places to display.

*Example*

```ts
import { DefaultMoneyStrategy, VendureConfig } from '@vendure/core';

export class ThreeDecimalPlacesMoneyStrategy extends DefaultMoneyStrategy {
  readonly precision = 3;
}

export const config: VendureConfig = {
  // ...
  entityOptions: {
    moneyStrategy: new ThreeDecimalPlacesMoneyStrategy(),
  }
};
```

:::info

This is configured via the `entityOptions.moneyStrategy` property of
your VendureConfig.

:::

```ts title="Signature"
interface MoneyStrategy extends InjectableStrategy {
    readonly moneyColumnOptions: ColumnOptions;
    readonly precision?: number;
    round(value: number, quantity?: number): number;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### moneyColumnOptions

<MemberInfo kind="property" type={`ColumnOptions`}   />

Defines the TypeORM column used to store monetary values.
### precision

<MemberInfo kind="property" type={`number`} default={`2`}  since="2.2.0"  />

Defines the precision (i.e. number of decimal places) represented by the monetary values.
For example, consider a product variant with a price value of `12345`.

- If the precision is `2`, then the price is `123.45`.
- If the precision is `3`, then the price is `12.345`.

Changing the precision has **no effect** on the stored value. It is merely a hint to the
UI as to how many decimal places to display.
### round

<MemberInfo kind="method" type={`(value: number, quantity?: number) => number`}   />

Defines the logic used to round monetary values. For instance, the default behavior
in the <a href='/reference/typescript-api/money/default-money-strategy#defaultmoneystrategy'>DefaultMoneyStrategy</a> is to round the value, then multiply.

```ts
return Math.round(value * quantity);
```

However, it may be desirable to instead round only _after_ the unit amount has been
multiplied. In this case you can define a custom strategy with logic like this:

```ts
return Math.round(value * quantity);
```


</div>


---

---
title: "RoundMoney"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## roundMoney

<GenerationInfo sourceFile="packages/core/src/common/round-money.ts" sourceLine="13" packageName="@vendure/core" since="2.0.0" />

Rounds a monetary value according to the configured <a href='/reference/typescript-api/money/money-strategy#moneystrategy'>MoneyStrategy</a>.

```ts title="Signature"
function roundMoney(value: number, quantity:  = 1): number
```
Parameters

### value

<MemberInfo kind="parameter" type={`number`} />

### quantity

<MemberInfo kind="parameter" type={``} />



---

---
title: "ActiveOrderService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ActiveOrderService

<GenerationInfo sourceFile="packages/core/src/service/helpers/active-order/active-order.service.ts" sourceLine="18" packageName="@vendure/core" />

This helper class is used to get a reference to the active Order from the current RequestContext.

```ts title="Signature"
class ActiveOrderService {
    constructor(sessionService: SessionService, orderService: OrderService, connection: TransactionalConnection, configService: ConfigService)
    getOrderFromContext(ctx: RequestContext) => Promise<Order | undefined>;
    getOrderFromContext(ctx: RequestContext, createIfNotExists: true) => Promise<Order>;
    getOrderFromContext(ctx: RequestContext, createIfNotExists:  = false) => Promise<Order | undefined>;
    getActiveOrder(ctx: RequestContext, input: { [strategyName: string]: any } | undefined) => Promise<Order | undefined>;
    getActiveOrder(ctx: RequestContext, input: { [strategyName: string]: any } | undefined, createIfNotExists: true) => Promise<Order>;
    getActiveOrder(ctx: RequestContext, input: { [strategyName: string]: Record<string, any> | undefined } | undefined, createIfNotExists:  = false) => Promise<Order | undefined>;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(sessionService: <a href='/reference/typescript-api/services/session-service#sessionservice'>SessionService</a>, orderService: <a href='/reference/typescript-api/services/order-service#orderservice'>OrderService</a>, connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, configService: ConfigService) => ActiveOrderService`}   />


### getOrderFromContext

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => Promise&#60;<a href='/reference/typescript-api/entities/order#order'>Order</a> | undefined&#62;`}   />

Gets the active Order object from the current Session. Optionally can create a new Order if
no active Order exists.

Intended to be used at the Resolver layer for those resolvers that depend upon an active Order
being present.
### getOrderFromContext

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, createIfNotExists: true) => Promise&#60;<a href='/reference/typescript-api/entities/order#order'>Order</a>&#62;`}   />


### getOrderFromContext

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, createIfNotExists:  = false) => Promise&#60;<a href='/reference/typescript-api/entities/order#order'>Order</a> | undefined&#62;`}   />


### getActiveOrder

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: { [strategyName: string]: any } | undefined) => Promise&#60;<a href='/reference/typescript-api/entities/order#order'>Order</a> | undefined&#62;`}  since="1.9.0"  />

Retrieves the active Order based on the configured <a href='/reference/typescript-api/orders/active-order-strategy#activeorderstrategy'>ActiveOrderStrategy</a>.
### getActiveOrder

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: { [strategyName: string]: any } | undefined, createIfNotExists: true) => Promise&#60;<a href='/reference/typescript-api/entities/order#order'>Order</a>&#62;`}   />


### getActiveOrder

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: { [strategyName: string]: Record&#60;string, any&#62; | undefined } | undefined, createIfNotExists:  = false) => Promise&#60;<a href='/reference/typescript-api/entities/order#order'>Order</a> | undefined&#62;`}   />




</div>


---

---
title: "ActiveOrderStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ActiveOrderStrategy

<GenerationInfo sourceFile="packages/core/src/config/order/active-order-strategy.ts" sourceLine="127" packageName="@vendure/core" since="1.9.0" />

This strategy is used to determine the active Order for all order-related operations in
the Shop API. By default, all the Shop API operations that relate to the active Order (e.g.
`activeOrder`, `addItemToOrder`, `applyCouponCode` etc.) will implicitly create a new Order
and set it on the current Session, and then read the session to obtain the active Order.
This behaviour is defined by the <a href='/reference/typescript-api/orders/default-active-order-strategy#defaultactiveorderstrategy'>DefaultActiveOrderStrategy</a>.

The `InputType` generic argument should correspond to the input type defined by the
`defineInputType()` method.

When `defineInputType()` is used, then the following Shop API operations will receive an additional
`activeOrderInput` argument allowing the active order input to be specified:

- `activeOrder`
- `eligibleShippingMethods`
- `eligiblePaymentMethods`
- `nextOrderStates`
- `addItemToOrder`
- `adjustOrderLine`
- `removeOrderLine`
- `removeAllOrderLines`
- `applyCouponCode`
- `removeCouponCode`
- `addPaymentToOrder`
- `setCustomerForOrder`
- `setOrderShippingAddress`
- `setOrderBillingAddress`
- `setOrderShippingMethod`
- `setOrderCustomFields`
- `transitionOrderToState`

*Example*

```GraphQL {hl_lines=[5]}
mutation AddItemToOrder {
  addItemToOrder(
    productVariantId: 42,
    quantity: 1,
    activeOrderInput: { token: "123456" }
  ) {
    ...on Order {
      id
      # ...etc
    }
  }
}
```

*Example*

```ts
import { ID } from '@vendure/common/lib/shared-types';
import {
  ActiveOrderStrategy,
  CustomerService,
  idsAreEqual,
  Injector,
  Order,
  OrderService,
  RequestContext,
  TransactionalConnection,
} from '@vendure/core';
import gql from 'graphql-tag';

// This strategy assumes a "orderToken" custom field is defined on the Order
// entity, and uses that token to perform a lookup to determine the active Order.
//
// Additionally, it does _not_ define a `createActiveOrder()` method, which
// means that a custom mutation would be required to create the initial Order in
// the first place and set the "orderToken" custom field.
class TokenActiveOrderStrategy implements ActiveOrderStrategy<{ token: string }> {
  readonly name = 'orderToken';

  private connection: TransactionalConnection;
  private orderService: OrderService;

  init(injector: Injector) {
    this.connection = injector.get(TransactionalConnection);
    this.orderService = injector.get(OrderService);
  }

  defineInputType = () => gql`
    input OrderTokenActiveOrderInput {
      token: String
    }
  `;

  async determineActiveOrder(ctx: RequestContext, input: { token: string }) {
    const qb = this.connection
      .getRepository(ctx, Order)
      .createQueryBuilder('order')
      .leftJoinAndSelect('order.customer', 'customer')
      .leftJoinAndSelect('customer.user', 'user')
      .where('order.customFields.orderToken = :orderToken', { orderToken: input.token });

    const order = await qb.getOne();
    if (!order) {
      return;
    }
    // Ensure the active user is the owner of this Order
    const orderUserId = order.customer && order.customer.user && order.customer.user.id;
    if (order.customer && idsAreEqual(orderUserId, ctx.activeUserId)) {
      return order;
    }
  }
}

// in vendure-config.ts
export const config = {
  // ...
  orderOptions: {
    activeOrderStrategy: new TokenActiveOrderStrategy(),
  },
}
```

```ts title="Signature"
interface ActiveOrderStrategy<InputType extends Record<string, any> | void = void> extends InjectableStrategy {
    readonly name: string;
    defineInputType?: () => DocumentNode;
    createActiveOrder?: (ctx: RequestContext, input: InputType) => Promise<Order>;
    determineActiveOrder(ctx: RequestContext, input: InputType): Promise<Order | undefined>;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### name

<MemberInfo kind="property" type={`string`}   />

The name of the strategy, e.g. "orderByToken", which will also be used as the
field name in the ActiveOrderInput type.
### defineInputType

<MemberInfo kind="property" type={`() =&#62; DocumentNode`}   />

Defines the type of the GraphQL Input object expected by the `activeOrderInput`
input argument.

*Example*

For example, given the following:

```ts
defineInputType() {
  return gql`
     input OrderTokenInput {
       token: String!
     }
  `;
}
```

assuming the strategy name is "orderByToken", then the resulting call to `activeOrder` (or any of the other
affected Shop API operations) would look like:

```GraphQL
activeOrder(activeOrderInput: {
  orderByToken: {
    token: "foo"
  }
}) {
  # ...
}
```

**Note:** if more than one graphql `input` type is being defined (as in a nested input type), then
the _first_ input will be assumed to be the top-level input.
### createActiveOrder

<MemberInfo kind="property" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: InputType) =&#62; Promise&#60;<a href='/reference/typescript-api/entities/order#order'>Order</a>&#62;`}   />

Certain mutations such as `addItemToOrder` can automatically create a new Order if one does not exist.
In these cases, this method will be called to create the new Order.

If automatic creation of an Order does not make sense in your strategy, then leave this method
undefined. You'll then need to take care of creating an order manually by defining a custom mutation.
### determineActiveOrder

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: InputType) => Promise&#60;<a href='/reference/typescript-api/entities/order#order'>Order</a> | undefined&#62;`}   />

This method is used to determine the active Order based on the current RequestContext in addition to any
input values provided, as defined by the `defineInputType` method of this strategy.

Note that this method is invoked frequently, so you should aim to keep it efficient. The returned Order,
for example, does not need to have its various relations joined.


</div>


---

---
title: "ChangedPriceHandlingStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ChangedPriceHandlingStrategy

<GenerationInfo sourceFile="packages/core/src/config/order/changed-price-handling-strategy.ts" sourceLine="24" packageName="@vendure/core" />

This strategy defines how we handle the situation where an item exists in an Order, and
then later on another is added but in the meantime the price of the ProductVariant has changed.

By default, the latest price will be used. Any price changes resulting from using a newer price
will be reflected in the GraphQL `OrderLine.unitPrice[WithTax]ChangeSinceAdded` field.

:::info

This is configured via the `orderOptions.changedPriceHandlingStrategy` property of
your VendureConfig.

:::

```ts title="Signature"
interface ChangedPriceHandlingStrategy extends InjectableStrategy {
    handlePriceChange(
        ctx: RequestContext,
        current: PriceCalculationResult,
        orderLine: OrderLine,
        order: Order,
    ): PriceCalculationResult | Promise<PriceCalculationResult>;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### handlePriceChange

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, current: <a href='/reference/typescript-api/common/price-calculation-result#pricecalculationresult'>PriceCalculationResult</a>, orderLine: <a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>) => <a href='/reference/typescript-api/common/price-calculation-result#pricecalculationresult'>PriceCalculationResult</a> | Promise&#60;<a href='/reference/typescript-api/common/price-calculation-result#pricecalculationresult'>PriceCalculationResult</a>&#62;`}   />

This method is called when adding to or adjusting OrderLines, if the latest price
(as determined by the ProductVariant price, potentially modified by the configured
<a href='/reference/typescript-api/orders/order-item-price-calculation-strategy#orderitempricecalculationstrategy'>OrderItemPriceCalculationStrategy</a>) differs from the initial price at the time
that the OrderLine was created.


</div>


---

---
title: "CustomOrderStates"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## CustomOrderStates

<GenerationInfo sourceFile="packages/core/src/service/helpers/order-state-machine/order-state.ts" sourceLine="11" packageName="@vendure/core" />

An interface to extend standard <a href='/reference/typescript-api/orders/order-process#orderstate'>OrderState</a>.

```ts title="Signature"
interface CustomOrderStates {

}
```


---

---
title: "DefaultActiveOrderStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DefaultActiveOrderStrategy

<GenerationInfo sourceFile="packages/core/src/config/order/default-active-order-strategy.ts" sourceLine="18" packageName="@vendure/core" since="1.9.0" />

The default <a href='/reference/typescript-api/orders/active-order-strategy#activeorderstrategy'>ActiveOrderStrategy</a>, which uses the current <a href='/reference/typescript-api/entities/session#session'>Session</a> to determine
the active Order, and requires no additional input in the Shop API since it is based on the
session which is part of the RequestContext.

```ts title="Signature"
class DefaultActiveOrderStrategy implements ActiveOrderStrategy {
    name: 'default-active-order-strategy';
    init(injector: Injector) => ;
    createActiveOrder(ctx: RequestContext) => ;
    determineActiveOrder(ctx: RequestContext) => ;
}
```
* Implements: <code><a href='/reference/typescript-api/orders/active-order-strategy#activeorderstrategy'>ActiveOrderStrategy</a></code>



<div className="members-wrapper">

### name

<MemberInfo kind="property" type={`'default-active-order-strategy'`}   />


### init

<MemberInfo kind="method" type={`(injector: <a href='/reference/typescript-api/common/injector#injector'>Injector</a>) => `}   />


### createActiveOrder

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => `}   />


### determineActiveOrder

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => `}   />




</div>


---

---
title: "DefaultGuestCheckoutStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DefaultGuestCheckoutStrategy

<GenerationInfo sourceFile="packages/core/src/config/order/default-guest-checkout-strategy.ts" sourceLine="64" packageName="@vendure/core" since="2.0.0" />

The default implementation of the <a href='/reference/typescript-api/orders/guest-checkout-strategy#guestcheckoutstrategy'>GuestCheckoutStrategy</a>. This strategy allows
guest checkouts by default, but can be configured to disallow them.

*Example*

```ts
import { DefaultGuestCheckoutStrategy, VendureConfig } from '@vendure/core';

export const config: VendureConfig = {
  orderOptions: {
    guestCheckoutStrategy: new DefaultGuestCheckoutStrategy({
      allowGuestCheckouts: false,
      allowGuestCheckoutForRegisteredCustomers: false,
    }),
  },
  // ...
};
```

```ts title="Signature"
class DefaultGuestCheckoutStrategy implements GuestCheckoutStrategy {
    init(injector: Injector) => ;
    constructor(options?: DefaultGuestCheckoutStrategyOptions)
    setCustomerForOrder(ctx: RequestContext, order: Order, input: CreateCustomerInput) => Promise<ErrorResultUnion<SetCustomerForOrderResult, Customer>>;
}
```
* Implements: <code><a href='/reference/typescript-api/orders/guest-checkout-strategy#guestcheckoutstrategy'>GuestCheckoutStrategy</a></code>



<div className="members-wrapper">

### init

<MemberInfo kind="method" type={`(injector: <a href='/reference/typescript-api/common/injector#injector'>Injector</a>) => `}   />


### constructor

<MemberInfo kind="method" type={`(options?: <a href='/reference/typescript-api/orders/default-guest-checkout-strategy#defaultguestcheckoutstrategyoptions'>DefaultGuestCheckoutStrategyOptions</a>) => DefaultGuestCheckoutStrategy`}   />


### setCustomerForOrder

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>, input: CreateCustomerInput) => Promise&#60;<a href='/reference/typescript-api/errors/error-result-union#errorresultunion'>ErrorResultUnion</a>&#60;SetCustomerForOrderResult, <a href='/reference/typescript-api/entities/customer#customer'>Customer</a>&#62;&#62;`}   />




</div>


## DefaultGuestCheckoutStrategyOptions

<GenerationInfo sourceFile="packages/core/src/config/order/default-guest-checkout-strategy.ts" sourceLine="20" packageName="@vendure/core" since="2.0.0" />

Options available for the <a href='/reference/typescript-api/orders/default-guest-checkout-strategy#defaultguestcheckoutstrategy'>DefaultGuestCheckoutStrategy</a>.

```ts title="Signature"
interface DefaultGuestCheckoutStrategyOptions {
    allowGuestCheckouts?: boolean;
    allowGuestCheckoutForRegisteredCustomers?: boolean;
}
```

<div className="members-wrapper">

### allowGuestCheckouts

<MemberInfo kind="property" type={`boolean`} default={`true`}   />

Whether to allow guest checkouts.
### allowGuestCheckoutForRegisteredCustomers

<MemberInfo kind="property" type={`boolean`} default={`false`}   />

Whether to allow guest checkouts for customers who already have an account.
Note that when this is enabled, the details provided in the `CreateCustomerInput`
will overwrite the existing customer details of the registered customer.


</div>


---

---
title: "DefaultOrderItemPriceCalculationStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DefaultOrderItemPriceCalculationStrategy

<GenerationInfo sourceFile="packages/core/src/config/order/default-order-item-price-calculation-strategy.ts" sourceLine="14" packageName="@vendure/core" />

The default <a href='/reference/typescript-api/orders/order-item-price-calculation-strategy#orderitempricecalculationstrategy'>OrderItemPriceCalculationStrategy</a>, which simply passes through the price of
the ProductVariant without performing any calculations

```ts title="Signature"
class DefaultOrderItemPriceCalculationStrategy implements OrderItemPriceCalculationStrategy {
    calculateUnitPrice(ctx: RequestContext, productVariant: ProductVariant) => PriceCalculationResult | Promise<PriceCalculationResult>;
}
```
* Implements: <code><a href='/reference/typescript-api/orders/order-item-price-calculation-strategy#orderitempricecalculationstrategy'>OrderItemPriceCalculationStrategy</a></code>



<div className="members-wrapper">

### calculateUnitPrice

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, productVariant: <a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>) => <a href='/reference/typescript-api/common/price-calculation-result#pricecalculationresult'>PriceCalculationResult</a> | Promise&#60;<a href='/reference/typescript-api/common/price-calculation-result#pricecalculationresult'>PriceCalculationResult</a>&#62;`}   />




</div>


---

---
title: "DefaultOrderPlacedStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DefaultOrderPlacedStrategy

<GenerationInfo sourceFile="packages/core/src/config/order/default-order-placed-strategy.ts" sourceLine="14" packageName="@vendure/core" />

The default <a href='/reference/typescript-api/orders/order-placed-strategy#orderplacedstrategy'>OrderPlacedStrategy</a>. The order is set as "placed" when it transitions from
'ArrangingPayment' to either 'PaymentAuthorized' or 'PaymentSettled'.

```ts title="Signature"
class DefaultOrderPlacedStrategy implements OrderPlacedStrategy {
    shouldSetAsPlaced(ctx: RequestContext, fromState: OrderState, toState: OrderState, order: Order) => boolean;
}
```
* Implements: <code><a href='/reference/typescript-api/orders/order-placed-strategy#orderplacedstrategy'>OrderPlacedStrategy</a></code>



<div className="members-wrapper">

### shouldSetAsPlaced

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, fromState: <a href='/reference/typescript-api/orders/order-process#orderstate'>OrderState</a>, toState: <a href='/reference/typescript-api/orders/order-process#orderstate'>OrderState</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>) => boolean`}   />




</div>


---

---
title: "DefaultStockAllocationStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DefaultStockAllocationStrategy

<GenerationInfo sourceFile="packages/core/src/config/order/default-stock-allocation-strategy.ts" sourceLine="14" packageName="@vendure/core" />

Allocates stock when the Order transitions from `ArrangingPayment` to either
`PaymentAuthorized` or `PaymentSettled`.

```ts title="Signature"
class DefaultStockAllocationStrategy implements StockAllocationStrategy {
    shouldAllocateStock(ctx: RequestContext, fromState: OrderState, toState: OrderState, order: Order) => boolean | Promise<boolean>;
}
```
* Implements: <code><a href='/reference/typescript-api/orders/stock-allocation-strategy#stockallocationstrategy'>StockAllocationStrategy</a></code>



<div className="members-wrapper">

### shouldAllocateStock

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, fromState: <a href='/reference/typescript-api/orders/order-process#orderstate'>OrderState</a>, toState: <a href='/reference/typescript-api/orders/order-process#orderstate'>OrderState</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>) => boolean | Promise&#60;boolean&#62;`}   />




</div>


---

---
title: "GuestCheckoutStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## GuestCheckoutStrategy

<GenerationInfo sourceFile="packages/core/src/config/order/guest-checkout-strategy.ts" sourceLine="33" packageName="@vendure/core" since="2.0.0" />

A strategy that determines how to deal with guest checkouts - i.e. when a customer
checks out without being logged in. For example, a strategy could be used to implement
business rules such as:

- No guest checkouts allowed
- No guest checkouts allowed for customers who already have an account
- No guest checkouts allowed for customers who have previously placed an order
- Allow guest checkouts, but create a new Customer entity if the email address
  is already in use
- Allow guest checkouts, but update the existing Customer entity if the email address
  is already in use

:::info

This is configured via the `orderOptions.guestCheckoutStrategy` property of
your VendureConfig.

:::

```ts title="Signature"
interface GuestCheckoutStrategy extends InjectableStrategy {
    setCustomerForOrder(
        ctx: RequestContext,
        order: Order,
        input: CreateCustomerInput,
    ):
        | ErrorResultUnion<SetCustomerForOrderResult, Customer>
        | Promise<ErrorResultUnion<SetCustomerForOrderResult, Customer>>;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### setCustomerForOrder

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>, input: CreateCustomerInput) => | <a href='/reference/typescript-api/errors/error-result-union#errorresultunion'>ErrorResultUnion</a>&#60;SetCustomerForOrderResult, <a href='/reference/typescript-api/entities/customer#customer'>Customer</a>&#62;         | Promise&#60;<a href='/reference/typescript-api/errors/error-result-union#errorresultunion'>ErrorResultUnion</a>&#60;SetCustomerForOrderResult, <a href='/reference/typescript-api/entities/customer#customer'>Customer</a>&#62;&#62;`}   />

This method is called when the `setCustomerForOrder` mutation is executed.
It should return either a Customer object or an ErrorResult.


</div>


---

---
title: "Orders"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "Merge Strategies"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## MergeOrdersStrategy

<GenerationInfo sourceFile="packages/core/src/config/order/merge-orders-strategy.ts" sourceLine="15" packageName="@vendure/core" />

Merges both Orders. If the guest order contains items which are already in the
existing Order, the guest Order quantity will replace that of the existing Order.

```ts title="Signature"
class MergeOrdersStrategy implements OrderMergeStrategy {
    merge(ctx: RequestContext, guestOrder: Order, existingOrder: Order) => MergedOrderLine[];
}
```
* Implements: <code><a href='/reference/typescript-api/orders/order-merge-strategy#ordermergestrategy'>OrderMergeStrategy</a></code>



<div className="members-wrapper">

### merge

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, guestOrder: <a href='/reference/typescript-api/entities/order#order'>Order</a>, existingOrder: <a href='/reference/typescript-api/entities/order#order'>Order</a>) => <a href='/reference/typescript-api/orders/order-merge-strategy#mergedorderline'>MergedOrderLine</a>[]`}   />




</div>


## UseExistingStrategy

<GenerationInfo sourceFile="packages/core/src/config/order/use-existing-strategy.ts" sourceLine="13" packageName="@vendure/core" />

The guest order is discarded and the existing order is used as the active order.

```ts title="Signature"
class UseExistingStrategy implements OrderMergeStrategy {
    merge(ctx: RequestContext, guestOrder: Order, existingOrder: Order) => MergedOrderLine[];
}
```
* Implements: <code><a href='/reference/typescript-api/orders/order-merge-strategy#ordermergestrategy'>OrderMergeStrategy</a></code>



<div className="members-wrapper">

### merge

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, guestOrder: <a href='/reference/typescript-api/entities/order#order'>Order</a>, existingOrder: <a href='/reference/typescript-api/entities/order#order'>Order</a>) => <a href='/reference/typescript-api/orders/order-merge-strategy#mergedorderline'>MergedOrderLine</a>[]`}   />




</div>


## UseGuestIfExistingEmptyStrategy

<GenerationInfo sourceFile="packages/core/src/config/order/use-guest-if-existing-empty-strategy.ts" sourceLine="13" packageName="@vendure/core" />

If the existing order is empty, then the guest order is used. Otherwise the existing order is used.

```ts title="Signature"
class UseGuestIfExistingEmptyStrategy implements OrderMergeStrategy {
    merge(ctx: RequestContext, guestOrder: Order, existingOrder: Order) => MergedOrderLine[];
}
```
* Implements: <code><a href='/reference/typescript-api/orders/order-merge-strategy#ordermergestrategy'>OrderMergeStrategy</a></code>



<div className="members-wrapper">

### merge

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, guestOrder: <a href='/reference/typescript-api/entities/order#order'>Order</a>, existingOrder: <a href='/reference/typescript-api/entities/order#order'>Order</a>) => <a href='/reference/typescript-api/orders/order-merge-strategy#mergedorderline'>MergedOrderLine</a>[]`}   />




</div>


## UseGuestStrategy

<GenerationInfo sourceFile="packages/core/src/config/order/use-guest-strategy.ts" sourceLine="13" packageName="@vendure/core" />

Any existing order is discarded and the guest order is set as the active order.

```ts title="Signature"
class UseGuestStrategy implements OrderMergeStrategy {
    merge(ctx: RequestContext, guestOrder: Order, existingOrder: Order) => MergedOrderLine[];
}
```
* Implements: <code><a href='/reference/typescript-api/orders/order-merge-strategy#ordermergestrategy'>OrderMergeStrategy</a></code>



<div className="members-wrapper">

### merge

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, guestOrder: <a href='/reference/typescript-api/entities/order#order'>Order</a>, existingOrder: <a href='/reference/typescript-api/entities/order#order'>Order</a>) => <a href='/reference/typescript-api/orders/order-merge-strategy#mergedorderline'>MergedOrderLine</a>[]`}   />




</div>


---

---
title: "OrderByCodeAccessStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## OrderByCodeAccessStrategy

<GenerationInfo sourceFile="packages/core/src/config/order/order-by-code-access-strategy.ts" sourceLine="38" packageName="@vendure/core" since="1.1.0" />

The OrderByCodeAccessStrategy determines how access to a placed Order via the
orderByCode query is granted.
With a custom strategy anonymous access could be made permanent or tied to specific
conditions like IP range or an Order status.

*Example*

This example grants access to the requested Order to anyone – unless it's Monday.
```ts
export class NotMondayOrderByCodeAccessStrategy implements OrderByCodeAccessStrategy {
    canAccessOrder(ctx: RequestContext, order: Order): boolean {
        const MONDAY = 1;
        const today = (new Date()).getDay();

        return today !== MONDAY;
    }
}
```

:::info

This is configured via the `orderOptions.orderByCodeAccessStrategy` property of
your VendureConfig.

:::

```ts title="Signature"
interface OrderByCodeAccessStrategy extends InjectableStrategy {
    canAccessOrder(ctx: RequestContext, order: Order): boolean | Promise<boolean>;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### canAccessOrder

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>) => boolean | Promise&#60;boolean&#62;`}   />

Gives or denies permission to access the requested Order


</div>


## DefaultOrderByCodeAccessStrategy

<GenerationInfo sourceFile="packages/core/src/config/order/order-by-code-access-strategy.ts" sourceLine="57" packageName="@vendure/core" />

The default OrderByCodeAccessStrategy used by Vendure. It permitts permanent access to
the Customer owning the Order and anyone within a given time period after placing the Order
(defaults to 2h).

```ts title="Signature"
class DefaultOrderByCodeAccessStrategy implements OrderByCodeAccessStrategy {
    constructor(anonymousAccessDuration: string)
    canAccessOrder(ctx: RequestContext, order: Order) => boolean;
}
```
* Implements: <code><a href='/reference/typescript-api/orders/order-by-code-access-strategy#orderbycodeaccessstrategy'>OrderByCodeAccessStrategy</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(anonymousAccessDuration: string) => DefaultOrderByCodeAccessStrategy`}   />


### canAccessOrder

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>) => boolean`}   />




</div>


---

---
title: "OrderCodeStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## OrderCodeStrategy

<GenerationInfo sourceFile="packages/core/src/config/order/order-code-strategy.ts" sourceLine="39" packageName="@vendure/core" />

The OrderCodeStrategy determines how Order codes are generated.
A custom strategy can be defined which e.g. integrates with an
existing system to generate a code:

:::info

This is configured via the `orderOptions.orderCodeStrategy` property of
your VendureConfig.

:::

*Example*

```ts
class MyOrderCodeStrategy implements OrderCodeStrategy {
  // Some imaginary service which calls out to an existing external
  // order management system.
  private mgmtService: ExternalOrderManagementService;

  init(injector: Injector) {
    this.mgmtService = injector.get(ExternalOrderManagementService);
  }

  async generate(ctx: RequestContext) {
    const result = await this.mgmtService.getAvailableOrderParams();
    return result.code;
  }
}
```

```ts title="Signature"
interface OrderCodeStrategy extends InjectableStrategy {
    generate(ctx: RequestContext): string | Promise<string>;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### generate

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => string | Promise&#60;string&#62;`}   />

Generates the order code.


</div>


## DefaultOrderCodeStrategy

<GenerationInfo sourceFile="packages/core/src/config/order/order-code-strategy.ts" sourceLine="55" packageName="@vendure/core" />

The default OrderCodeStrategy generates a random string consisting
of 16 uppercase letters and numbers.

```ts title="Signature"
class DefaultOrderCodeStrategy implements OrderCodeStrategy {
    generate(ctx: RequestContext) => string;
}
```
* Implements: <code><a href='/reference/typescript-api/orders/order-code-strategy#ordercodestrategy'>OrderCodeStrategy</a></code>



<div className="members-wrapper">

### generate

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => string`}   />




</div>


---

---
title: "OrderInterceptor"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## OrderInterceptor

<GenerationInfo sourceFile="packages/core/src/config/order/order-interceptor.ts" sourceLine="214" packageName="@vendure/core" since="3.1.0" />

An OrderInterceptor is a class which can be used to intercept and modify the behavior of order-related
operations.

It does this by providing methods which are called whenever the contents of an order are about
to get changed. These methods are able to prevent the operation from proceeding by returning a string
error message.

Examples of use-cases for an OrderInterceptor include:

* Preventing certain products from being added to the order based on some criteria, e.g. if the
  product is already in another active order.
* Enforcing a minimum or maximum quantity of a given product in the order
* Using a CAPTCHA to prevent automated order creation

:::info

This is configured via the `orderOptions.orderInterceptors` property of
your VendureConfig.

:::

OrderInterceptors are executed when the following mutations are called:

- `addItemToOrder`
- `adjustOrderLine`
- `removeItemFromOrder`

Additionally, if you are working directly with the <a href='/reference/typescript-api/services/order-service#orderservice'>OrderService</a>, the following methods will trigger
any registered OrderInterceptors:

- `addItemToOrder`
- `addItemsToOrder`
- `adjustOrderLine`
- `adjustOrderLines`
- `removeItemFromOrder`
- `removeItemsFromOrder`

When an OrderInterceptor is registered, it will be called in the order in which it was registered.
If an interceptor method resolves to a string, the operation will be prevented and the string will be used as the error message.

When multiple interceptors are registered, the first interceptor to resolve to a string will prevent the operation from proceeding.

Errors returned by OrderInterceptors are surfaced to the GraphQL API as an `OrderInterceptorError` and can be
queried like this:

```graphql
mutation AddItemToOrder($productVariantId: ID!, $quantity: Int!) {
  addItemToOrder(productVariantId: $productVariantId, quantity: $quantity) {
    ... on Order {
      id
      code
      # ... other Order fields
    }
    ... on ErrorResult {
      errorCode
      message
    }
    // highlight-start
    ... on OrderInterceptorError {
      interceptorError
    }
    // highlight-end
  }
}
```

In the above example, the error message returned by the OrderInterceptor would be available in the `interceptorError` field.

## Example: Min/max order quantity

Let's say we want to allow ProductVariants to specify the minimum or maximum amount which may be added
to an order. We can define custom fields to store this information and
then use this custom field value to prevent an order line from being added to the order if the quantity
is below the minimum.

*Example*

```ts
import {
  EntityHydrator,
  Injector,
  LanguageCode,
  Order,
  OrderInterceptor,
  ProductVariant,
  RequestContext,
  TranslatorService,
  VendurePlugin,
  WillAddItemToOrderInput,
  WillAdjustOrderLineInput,
} from '@vendure/core';

declare module '@vendure/core/dist/entity/custom-entity-fields' {
  interface CustomProductVariantFields {
    minOrderQuantity?: number;
    maxOrderQuantity?: number;
  }
}

// This OrderInterceptor enforces minimum and maximum order quantities on ProductVariants.
export class MinMaxOrderInterceptor implements OrderInterceptor {
 private entityHydrator: EntityHydrator;
 private translatorService: TranslatorService;

 init(injector: Injector) {
   this.entityHydrator = injector.get(EntityHydrator);
   this.translatorService = injector.get(TranslatorService);
 }

 willAddItemToOrder(
   ctx: RequestContext,
   order: Order,
   input: WillAddItemToOrderInput,
 ): Promise<void | string> | void | string {
   const { productVariant, quantity } = input;
   const min = productVariant.customFields?.minOrderQuantity;
   const max = productVariant.customFields?.maxOrderQuantity;
   if (min && quantity < min) {
     return this.minErrorMessage(ctx, productVariant, min);
   }
   if (max && quantity > max) {
     return this.maxErrorMessage(ctx, productVariant, max);
   }
 }

 willAdjustOrderLine(
   ctx: RequestContext,
   order: Order,
   input: WillAdjustOrderLineInput,
 ): Promise<void | string> | void | string {
   const { orderLine, quantity } = input;
   const min = orderLine.productVariant.customFields?.minOrderQuantity;
   const max = orderLine.productVariant.customFields?.maxOrderQuantity;
   if (min && quantity < min) {
     return this.minErrorMessage(ctx, orderLine.productVariant, min);
   }
   if (max && quantity > max) {
     return this.maxErrorMessage(ctx, orderLine.productVariant, max);
   }
 }

 private async minErrorMessage(ctx: RequestContext, variant: ProductVariant, min: number) {
   const variantName = await this.getTranslatedVariantName(ctx, variant);
   return `Minimum order quantity for "${variantName}" is ${min}`;
 }

 private async maxErrorMessage(ctx: RequestContext, variant: ProductVariant, max: number) {
   const variantName = await this.getTranslatedVariantName(ctx, variant);
   return `Maximum order quantity for "${variantName}" is ${max}`;
 }

 private async getTranslatedVariantName(ctx: RequestContext, variant: ProductVariant) {
   await this.entityHydrator.hydrate(ctx, variant, { relations: ['translations'] });
   const translated = this.translatorService.translate(variant, ctx);
   return translated.name;
 }
}

// This plugin enforces minimum and maximum order quantities on ProductVariants.
// It adds two new custom fields to ProductVariant:
// - minOrderQuantity
// - maxOrderQuantity
//
// It also adds an OrderInterceptor which enforces these limits.
@VendurePlugin({
 configuration: config => {
 // Here we add the custom fields to the ProductVariant entity
   config.customFields.ProductVariant.push({
     type: 'int',
     min: 0,
     name: 'minOrderQuantity',
     label: [{ languageCode: LanguageCode.en, value: 'Minimum order quantity' }],
     nullable: true,
   });
   config.customFields.ProductVariant.push({
     type: 'int',
     min: 0,
     name: 'maxOrderQuantity',
     label: [{ languageCode: LanguageCode.en, value: 'Maximum order quantity' }],
     nullable: true,
   });

   // Here we add the MinMaxOrderInterceptor to the orderInterceptors array
   config.orderOptions.orderInterceptors.push(new MinMaxOrderInterceptor());
   return config;
 },
})
export class OrderQuantityLimitsPlugin {}
```

```ts title="Signature"
interface OrderInterceptor extends InjectableStrategy {
    willAddItemToOrder?(
        ctx: RequestContext,
        order: Order,
        input: WillAddItemToOrderInput,
    ): Promise<void | string> | void | string;
    willAdjustOrderLine?(
        ctx: RequestContext,
        order: Order,
        input: WillAdjustOrderLineInput,
    ): Promise<void | string> | void | string;
    willRemoveItemFromOrder?(
        ctx: RequestContext,
        order: Order,
        orderLine: OrderLine,
    ): Promise<void | string> | void | string;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### willAddItemToOrder

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>, input: WillAddItemToOrderInput) => Promise&#60;void | string&#62; | void | string`}   />

Called when a new item is about to be added to the order,
as in the `addItemToOrder` mutation or the `addItemToOrder()` / `addItemsToOrder()` method
of the <a href='/reference/typescript-api/services/order-service#orderservice'>OrderService</a>.
### willAdjustOrderLine

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>, input: WillAdjustOrderLineInput) => Promise&#60;void | string&#62; | void | string`}   />

Called when an existing order line is about to be adjusted,
as in the `adjustOrderLine` mutation or the `adjustOrderLine()` / `adjustOrderLines()` method
of the <a href='/reference/typescript-api/services/order-service#orderservice'>OrderService</a>.
### willRemoveItemFromOrder

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>, orderLine: <a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a>) => Promise&#60;void | string&#62; | void | string`}   />

Called when an item is about to be removed from the order,
as in the `removeItemFromOrder` mutation or the `removeItemFromOrder()` / `removeItemsFromOrder()` method
of the <a href='/reference/typescript-api/services/order-service#orderservice'>OrderService</a>.


</div>


---

---
title: "OrderItemPriceCalculationStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## OrderItemPriceCalculationStrategy

<GenerationInfo sourceFile="packages/core/src/config/order/order-item-price-calculation-strategy.ts" sourceLine="60" packageName="@vendure/core" />

The OrderItemPriceCalculationStrategy defines the listPrice of an OrderLine when adding an item to an Order. By default the
<a href='/reference/typescript-api/orders/default-order-item-price-calculation-strategy#defaultorderitempricecalculationstrategy'>DefaultOrderItemPriceCalculationStrategy</a> is used.

:::info

This is configured via the `orderOptions.orderItemPriceCalculationStrategy` property of
your VendureConfig.

:::

### When is the strategy invoked ?
* addItemToOrder (only on the new order line)
* adjustOrderLine  (only on the adjusted order line)
* setOrderShippingAddress (on all order lines)
* setOrderBillingAddress (on all order lines)

### OrderItemPriceCalculationStrategy vs Promotions
Both the OrderItemPriceCalculationStrategy and Promotions can be used to alter the price paid for a product.

The main difference is when a Promotion is applied, it adds a `discount` line to the Order, and the regular
price is used for the value of `OrderLine.listPrice` property, whereas
the OrderItemPriceCalculationStrategy actually alters the value of `OrderLine.listPrice` itself, and does not
add any discounts to the Order.

Use OrderItemPriceCalculationStrategy if:

* The price calculation is based on the properties of the ProductVariant and any CustomFields
  specified on the OrderLine, for example via a product configurator.
* The logic is a permanent part of your business requirements.

Use Promotions if:

* You want to implement "discounts" and "special offers"
* The calculation is not a permanent part of your business requirements.
* The price depends on dynamic aspects such as quantities and which other
  ProductVariants are in the Order.
* The configuration of the logic needs to be manipulated via the Admin UI.

### Example use-cases

A custom OrderItemPriceCalculationStrategy can be used to implement things like:

* A gift-wrapping service, where a boolean custom field is defined on the OrderLine. If `true`,
  a gift-wrapping surcharge would be added to the price.
* A product-configurator where e.g. various finishes, colors, and materials can be selected and stored
  as OrderLine custom fields (see [the Custom Fields guide](/guides/developer-guide/custom-fields/).
* Price lists or bulk pricing, where different price bands are stored e.g. in a customField on the ProductVariant, and this
  is used to calculate the price based on the current quantity.

```ts title="Signature"
interface OrderItemPriceCalculationStrategy extends InjectableStrategy {
    calculateUnitPrice(
        ctx: RequestContext,
        productVariant: ProductVariant,
        orderLineCustomFields: { [key: string]: any },
        order: Order,
        quantity: number,
    ): PriceCalculationResult | Promise<PriceCalculationResult>;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### calculateUnitPrice

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, productVariant: <a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>, orderLineCustomFields: { [key: string]: any }, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>, quantity: number) => <a href='/reference/typescript-api/common/price-calculation-result#pricecalculationresult'>PriceCalculationResult</a> | Promise&#60;<a href='/reference/typescript-api/common/price-calculation-result#pricecalculationresult'>PriceCalculationResult</a>&#62;`}   />

Receives the ProductVariant to be added to the Order as well as any OrderLine custom fields and returns
the price for a single unit.

Note: if you have any `relation` type custom fields defined on the OrderLine entity, they will only be
passed in to this method if they are set to `eager: true`. Otherwise, you can use the <a href='/reference/typescript-api/data-access/entity-hydrator#entityhydrator'>EntityHydrator</a>to join the missing relations.

Note: the `quantity` argument was added in v2.0.0


</div>


---

---
title: "OrderMergeStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## OrderMergeStrategy

<GenerationInfo sourceFile="packages/core/src/config/order/order-merge-strategy.ts" sourceLine="48" packageName="@vendure/core" />

An OrderMergeStrategy defines what happens when a Customer with an existing Order
signs in with a guest Order, where both Orders may contain differing OrderLines.

Somehow these differing OrderLines need to be reconciled into a single collection
of OrderLines. The OrderMergeStrategy defines the rules governing this reconciliation.

:::info

This is configured via the `orderOptions.mergeStrategy` property of
your VendureConfig.

:::

```ts title="Signature"
interface OrderMergeStrategy extends InjectableStrategy {
    merge(ctx: RequestContext, guestOrder: Order, existingOrder: Order): MergedOrderLine[];
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### merge

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, guestOrder: <a href='/reference/typescript-api/entities/order#order'>Order</a>, existingOrder: <a href='/reference/typescript-api/entities/order#order'>Order</a>) => <a href='/reference/typescript-api/orders/order-merge-strategy#mergedorderline'>MergedOrderLine</a>[]`}   />

Merges the lines of the guest Order with those of the existing Order which is associated
with the active customer.


</div>


## MergedOrderLine

<GenerationInfo sourceFile="packages/core/src/config/order/order-merge-strategy.ts" sourceLine="15" packageName="@vendure/core" />

The result of the <a href='/reference/typescript-api/orders/order-merge-strategy#ordermergestrategy'>OrderMergeStrategy</a> `merge` method.

```ts title="Signature"
interface MergedOrderLine {
    orderLineId: ID;
    quantity: number;
    customFields?: any;
}
```

<div className="members-wrapper">

### orderLineId

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a>`}   />


### quantity

<MemberInfo kind="property" type={`number`}   />


### customFields

<MemberInfo kind="property" type={`any`}   />




</div>


---

---
title: "OrderOptions"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## OrderOptions

<GenerationInfo sourceFile="packages/core/src/config/vendure-config.ts" sourceLine="520" packageName="@vendure/core" />



```ts title="Signature"
interface OrderOptions {
    orderItemsLimit?: number;
    orderLineItemsLimit?: number;
    orderItemPriceCalculationStrategy?: OrderItemPriceCalculationStrategy;
    process?: Array<OrderProcess<any>>;
    stockAllocationStrategy?: StockAllocationStrategy;
    mergeStrategy?: OrderMergeStrategy;
    checkoutMergeStrategy?: OrderMergeStrategy;
    orderCodeStrategy?: OrderCodeStrategy;
    orderByCodeAccessStrategy?: OrderByCodeAccessStrategy;
    changedPriceHandlingStrategy?: ChangedPriceHandlingStrategy;
    orderPlacedStrategy?: OrderPlacedStrategy;
    activeOrderStrategy?: ActiveOrderStrategy<any> | Array<ActiveOrderStrategy<any>>;
    orderSellerStrategy?: OrderSellerStrategy;
    guestCheckoutStrategy?: GuestCheckoutStrategy;
    orderInterceptors?: OrderInterceptor[];
}
```

<div className="members-wrapper">

### orderItemsLimit

<MemberInfo kind="property" type={`number`} default={`999`}   />

The maximum number of individual items allowed in a single order. This option exists
to prevent excessive resource usage when dealing with very large orders. For example,
if an order contains a million items, then any operations on that order (modifying a quantity,
adding or removing an item) will require Vendure to loop through all million items
to perform price calculations against active promotions and taxes. This can have a significant
performance impact for very large values.

Attempting to exceed this limit will cause Vendure to throw a `OrderLimitError`.
### orderLineItemsLimit

<MemberInfo kind="property" type={`number`} default={`999`}   />

The maximum number of items allowed per order line. This option is an addition
on the `orderItemsLimit` for more granular control. Note `orderItemsLimit` is still
important in order to prevent excessive resource usage.

Attempting to exceed this limit will cause Vendure to throw a OrderLimitError`.
### orderItemPriceCalculationStrategy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/orders/order-item-price-calculation-strategy#orderitempricecalculationstrategy'>OrderItemPriceCalculationStrategy</a>`} default={`DefaultPriceCalculationStrategy`}   />

Defines the logic used to calculate the unit price of an OrderLine when adding an
item to an Order.
### process

<MemberInfo kind="property" type={`Array&#60;<a href='/reference/typescript-api/orders/order-process#orderprocess'>OrderProcess</a>&#60;any&#62;&#62;`} default={`[]`}   />

Allows the definition of custom states and transition logic for the order process state machine.
Takes an array of objects implementing the <a href='/reference/typescript-api/orders/order-process#orderprocess'>OrderProcess</a> interface.
### stockAllocationStrategy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/orders/stock-allocation-strategy#stockallocationstrategy'>StockAllocationStrategy</a>`} default={`<a href='/reference/typescript-api/orders/default-stock-allocation-strategy#defaultstockallocationstrategy'>DefaultStockAllocationStrategy</a>`}   />

Determines the point of the order process at which stock gets allocated.
### mergeStrategy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/orders/order-merge-strategy#ordermergestrategy'>OrderMergeStrategy</a>`} default={`<a href='/reference/typescript-api/orders/merge-strategies#mergeordersstrategy'>MergeOrdersStrategy</a>`}   />

Defines the strategy used to merge a guest Order and an existing Order when
signing in.
### checkoutMergeStrategy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/orders/order-merge-strategy#ordermergestrategy'>OrderMergeStrategy</a>`} default={`<a href='/reference/typescript-api/orders/merge-strategies#usegueststrategy'>UseGuestStrategy</a>`}   />

Defines the strategy used to merge a guest Order and an existing Order when
signing in as part of the checkout flow.
### orderCodeStrategy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/orders/order-code-strategy#ordercodestrategy'>OrderCodeStrategy</a>`} default={`<a href='/reference/typescript-api/orders/order-code-strategy#defaultordercodestrategy'>DefaultOrderCodeStrategy</a>`}   />

Allows a user-defined function to create Order codes. This can be useful when
integrating with existing systems. By default, Vendure will generate a 16-character
alphanumeric string.

Note: when using a custom function for Order codes, bear in mind the database limit
for string types (e.g. 255 chars for a varchar field in MySQL), and also the need
for codes to be unique.
### orderByCodeAccessStrategy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/orders/order-by-code-access-strategy#orderbycodeaccessstrategy'>OrderByCodeAccessStrategy</a>`} default={`<a href='/reference/typescript-api/orders/order-by-code-access-strategy#defaultorderbycodeaccessstrategy'>DefaultOrderByCodeAccessStrategy</a>`}  since="1.1.0"  />

Defines the strategy used to check if and how an Order may be retrieved via the orderByCode query.

The default strategy permits permanent access to the Customer owning the Order and anyone
within 2 hours after placing the Order.
### changedPriceHandlingStrategy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/orders/changed-price-handling-strategy#changedpricehandlingstrategy'>ChangedPriceHandlingStrategy</a>`} default={`DefaultChangedPriceHandlingStrategy`}   />

Defines how we handle the situation where an item exists in an Order, and
then later on another is added but in the meantime the price of the ProductVariant has changed.

By default, the latest price will be used. Any price changes resulting from using a newer price
will be reflected in the GraphQL `OrderLine.unitPrice[WithTax]ChangeSinceAdded` field.
### orderPlacedStrategy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/orders/order-placed-strategy#orderplacedstrategy'>OrderPlacedStrategy</a>`} default={`<a href='/reference/typescript-api/orders/default-order-placed-strategy#defaultorderplacedstrategy'>DefaultOrderPlacedStrategy</a>`}   />

Defines the point of the order process at which the Order is set as "placed".
### activeOrderStrategy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/orders/active-order-strategy#activeorderstrategy'>ActiveOrderStrategy</a>&#60;any&#62; | Array&#60;<a href='/reference/typescript-api/orders/active-order-strategy#activeorderstrategy'>ActiveOrderStrategy</a>&#60;any&#62;&#62;`} default={`<a href='/reference/typescript-api/orders/default-active-order-strategy#defaultactiveorderstrategy'>DefaultActiveOrderStrategy</a>`}  since="1.9.0"  />

Defines the strategy used to determine the active Order when interacting with Shop API operations
such as `activeOrder` and `addItemToOrder`. By default, the strategy uses the active Session.

Note that if multiple strategies are defined, they will be checked in order and the first one that
returns an Order will be used.
### orderSellerStrategy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/orders/order-seller-strategy#ordersellerstrategy'>OrderSellerStrategy</a>`} default={`<a href='/reference/typescript-api/orders/order-seller-strategy#defaultordersellerstrategy'>DefaultOrderSellerStrategy</a>`}  since="2.0.0"  />

Defines how Orders will be split amongst multiple Channels in a multivendor scenario.
### guestCheckoutStrategy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/orders/guest-checkout-strategy#guestcheckoutstrategy'>GuestCheckoutStrategy</a>`} default={`<a href='/reference/typescript-api/orders/default-guest-checkout-strategy#defaultguestcheckoutstrategy'>DefaultGuestCheckoutStrategy</a>`}   />

Defines how we deal with guest checkouts.
### orderInterceptors

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/orders/order-interceptor#orderinterceptor'>OrderInterceptor</a>[]`} default={`[]`}  since="3.1.0"  />

An array of <a href='/reference/typescript-api/orders/order-interceptor#orderinterceptor'>OrderInterceptor</a>s which can be used to modify the behavior of the Order process.


</div>


---

---
title: "OrderPlacedStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## OrderPlacedStrategy

<GenerationInfo sourceFile="packages/core/src/config/order/order-placed-strategy.ts" sourceLine="24" packageName="@vendure/core" />

This strategy is responsible for deciding at which stage in the order process
the Order will be set as "placed" (i.e. the Customer has checked out, and
next it must be processed by an Administrator).

By default, the order is set as "placed" when it transitions from
'ArrangingPayment' to either 'PaymentAuthorized' or 'PaymentSettled'.

:::info

This is configured via the `orderOptions.orderPlacedStrategy` property of
your VendureConfig.

:::

```ts title="Signature"
interface OrderPlacedStrategy extends InjectableStrategy {
    shouldSetAsPlaced(
        ctx: RequestContext,
        fromState: OrderState,
        toState: OrderState,
        order: Order,
    ): boolean | Promise<boolean>;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### shouldSetAsPlaced

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, fromState: <a href='/reference/typescript-api/orders/order-process#orderstate'>OrderState</a>, toState: <a href='/reference/typescript-api/orders/order-process#orderstate'>OrderState</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>) => boolean | Promise&#60;boolean&#62;`}   />

This method is called whenever an _active_ Order transitions from one state to another.
If it resolves to `true`, then the Order will be set as "placed", which means:

* Order.active = false
* Order.placedAt = new Date()
* Any active Promotions are linked to the Order


</div>


---

---
title: "OrderProcess"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## OrderProcess

<GenerationInfo sourceFile="packages/core/src/config/order/order-process.ts" sourceLine="35" packageName="@vendure/core" />

An OrderProcess is used to define the way the order process works as in: what states an Order can be
in, and how it may transition from one state to another. Using the `onTransitionStart()` hook, an
OrderProcess can perform checks before allowing a state transition to occur, and the `onTransitionEnd()`
hook allows logic to be executed after a state change.

For detailed description of the interface members, see the <a href='/reference/typescript-api/state-machine/state-machine-config#statemachineconfig'>StateMachineConfig</a> docs.

:::info

This is configured via the `orderOptions.process` property of
your VendureConfig.

:::

```ts title="Signature"
interface OrderProcess<State extends keyof CustomOrderStates | string> extends InjectableStrategy {
    transitions?: Transitions<State, State | OrderState> & Partial<Transitions<OrderState | State>>;
    onTransitionStart?: OnTransitionStartFn<State | OrderState, OrderTransitionData>;
    onTransitionEnd?: OnTransitionEndFn<State | OrderState, OrderTransitionData>;
    onTransitionError?: OnTransitionErrorFn<State | OrderState>;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### transitions

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/state-machine/transitions#transitions'>Transitions</a>&#60;State, State | <a href='/reference/typescript-api/orders/order-process#orderstate'>OrderState</a>&#62; &#38; Partial&#60;<a href='/reference/typescript-api/state-machine/transitions#transitions'>Transitions</a>&#60;<a href='/reference/typescript-api/orders/order-process#orderstate'>OrderState</a> | State&#62;&#62;`}   />


### onTransitionStart

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/state-machine/state-machine-config#ontransitionstartfn'>OnTransitionStartFn</a>&#60;State | <a href='/reference/typescript-api/orders/order-process#orderstate'>OrderState</a>, <a href='/reference/typescript-api/orders/order-process#ordertransitiondata'>OrderTransitionData</a>&#62;`}   />


### onTransitionEnd

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/state-machine/state-machine-config#ontransitionendfn'>OnTransitionEndFn</a>&#60;State | <a href='/reference/typescript-api/orders/order-process#orderstate'>OrderState</a>, <a href='/reference/typescript-api/orders/order-process#ordertransitiondata'>OrderTransitionData</a>&#62;`}   />


### onTransitionError

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/state-machine/state-machine-config#ontransitionerrorfn'>OnTransitionErrorFn</a>&#60;State | <a href='/reference/typescript-api/orders/order-process#orderstate'>OrderState</a>&#62;`}   />




</div>


## DefaultOrderProcessOptions

<GenerationInfo sourceFile="packages/core/src/config/order/default-order-process.ts" sourceLine="50" packageName="@vendure/core" since="2.0.0" />

Options which can be passed to the <a href='/reference/typescript-api/orders/order-process#configuredefaultorderprocess'>configureDefaultOrderProcess</a> function
to configure an instance of the default <a href='/reference/typescript-api/orders/order-process#orderprocess'>OrderProcess</a>. By default, all
options are set to `true`.

```ts title="Signature"
interface DefaultOrderProcessOptions {
    checkModificationPayments?: boolean;
    checkAdditionalPaymentsAmount?: boolean;
    checkAllVariantsExist?: boolean;
    arrangingPaymentRequiresContents?: boolean;
    arrangingPaymentRequiresCustomer?: boolean;
    arrangingPaymentRequiresShipping?: boolean;
    arrangingPaymentRequiresStock?: boolean;
    checkPaymentsCoverTotal?: boolean;
    checkAllItemsBeforeCancel?: boolean;
    checkFulfillmentStates?: boolean;
}
```

<div className="members-wrapper">

### checkModificationPayments

<MemberInfo kind="property" type={`boolean`} default={`true`}   />

Prevents an Order from transitioning out of the `Modifying` state if
the Order price has changed and there is no Payment or Refund associated
with the Modification.
### checkAdditionalPaymentsAmount

<MemberInfo kind="property" type={`boolean`} default={`true`}   />

Prevents an Order from transitioning out of the `ArrangingAdditionalPayment` state if
the Order's Payments do not cover the full amount of `totalWithTax`.
### checkAllVariantsExist

<MemberInfo kind="property" type={`boolean`} default={`true`}   />

Prevents the transition from `AddingItems` to any other state (apart from `Cancelled`) if
and of the ProductVariants no longer exists due to deletion.
### arrangingPaymentRequiresContents

<MemberInfo kind="property" type={`boolean`} default={`true`}   />

Prevents transition to the `ArrangingPayment` state if the active Order has no lines.
### arrangingPaymentRequiresCustomer

<MemberInfo kind="property" type={`boolean`} default={`true`}   />

Prevents transition to the `ArrangingPayment` state if the active Order has no customer
associated with it.
### arrangingPaymentRequiresShipping

<MemberInfo kind="property" type={`boolean`} default={`true`}   />

Prevents transition to the `ArrangingPayment` state if the active Order has no shipping
method set.
### arrangingPaymentRequiresStock

<MemberInfo kind="property" type={`boolean`} default={`true`}   />

Prevents transition to the `ArrangingPayment` state if there is insufficient saleable
stock to cover the contents of the Order.
### checkPaymentsCoverTotal

<MemberInfo kind="property" type={`boolean`} default={`true`}   />

Prevents transition to the `PaymentAuthorized` or `PaymentSettled` states if the order
`totalWithTax` amount is not covered by Payment(s) in the corresponding states.
### checkAllItemsBeforeCancel

<MemberInfo kind="property" type={`boolean`} default={`true`}   />

Prevents transition to the `Cancelled` state unless all OrderItems are already
cancelled.
### checkFulfillmentStates

<MemberInfo kind="property" type={`boolean`} default={`true`}   />

Prevents transition to the `Shipped`, `PartiallyShipped`, `Delivered` & `PartiallyDelivered` states unless
there are corresponding Fulfillments in the correct states to allow this. E.g. `Shipped` only if all items in
the Order are part of a Fulfillment which itself is in the `Shipped` state.


</div>


## configureDefaultOrderProcess

<GenerationInfo sourceFile="packages/core/src/config/order/default-order-process.ts" sourceLine="163" packageName="@vendure/core" since="2.0.0" />

Used to configure a customized instance of the default <a href='/reference/typescript-api/orders/order-process#orderprocess'>OrderProcess</a> that ships with Vendure.
Using this function allows you to turn off certain checks and constraints that are enabled by default.

```ts
import { configureDefaultOrderProcess, VendureConfig } from '@vendure/core';

const myCustomOrderProcess = configureDefaultOrderProcess({
  // Disable the constraint that requires
  // Orders to have a shipping method assigned
  // before payment.
  arrangingPaymentRequiresShipping: false,
});

export const config: VendureConfig = {
  orderOptions: {
    process: [myCustomOrderProcess],
  },
};
```
The <a href='/reference/typescript-api/orders/order-process#defaultorderprocessoptions'>DefaultOrderProcessOptions</a> type defines all available options. If you require even
more customization, you can create your own implementation of the <a href='/reference/typescript-api/orders/order-process#orderprocess'>OrderProcess</a> interface.

```ts title="Signature"
function configureDefaultOrderProcess(options: DefaultOrderProcessOptions): void
```
Parameters

### options

<MemberInfo kind="parameter" type={`<a href='/reference/typescript-api/orders/order-process#defaultorderprocessoptions'>DefaultOrderProcessOptions</a>`} />



## defaultOrderProcess

<GenerationInfo sourceFile="packages/core/src/config/order/default-order-process.ts" sourceLine="475" packageName="@vendure/core" since="2.0.0" />

This is the built-in <a href='/reference/typescript-api/orders/order-process#orderprocess'>OrderProcess</a> that ships with Vendure. A customized version of this process
can be created using the <a href='/reference/typescript-api/orders/order-process#configuredefaultorderprocess'>configureDefaultOrderProcess</a> function, which allows you to pass in an object
to enable/disable certain checks.



## OrderStates

<GenerationInfo sourceFile="packages/core/src/service/helpers/order-state-machine/order-state.ts" sourceLine="21" packageName="@vendure/core" since="2.0.0" />

An interface to extend the <a href='/reference/typescript-api/orders/order-process#orderstate'>OrderState</a> type.

```ts title="Signature"
interface OrderStates {

}
```


## OrderState

<GenerationInfo sourceFile="packages/core/src/service/helpers/order-state-machine/order-state.ts" sourceLine="42" packageName="@vendure/core" />

These are the default states of the Order process. They can be augmented and
modified by using the <a href='/reference/typescript-api/orders/order-options#orderoptions'>OrderOptions</a> `process` property, and by default
the <a href='/reference/typescript-api/orders/order-process#defaultorderprocess'>defaultOrderProcess</a> will add the states

- `ArrangingPayment`
- `PaymentAuthorized`
- `PaymentSettled`
- `PartiallyShipped`
- `Shipped`
- `PartiallyDelivered`
- `Delivered`
- `Modifying`
- `ArrangingAdditionalPayment`

```ts title="Signature"
type OrderState = | 'Created'
    | 'Draft'
    | 'AddingItems'
    | 'Cancelled'
    | keyof CustomOrderStates
    | keyof OrderStates
```


## OrderTransitionData

<GenerationInfo sourceFile="packages/core/src/service/helpers/order-state-machine/order-state.ts" sourceLine="57" packageName="@vendure/core" />

This is the object passed to the <a href='/reference/typescript-api/orders/order-process#orderprocess'>OrderProcess</a> state transition hooks.

```ts title="Signature"
interface OrderTransitionData {
    ctx: RequestContext;
    order: Order;
}
```

<div className="members-wrapper">

### ctx

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>`}   />


### order

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/order#order'>Order</a>`}   />




</div>


---

---
title: "OrderSellerStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## OrderSellerStrategy

<GenerationInfo sourceFile="packages/core/src/config/order/order-seller-strategy.ts" sourceLine="43" packageName="@vendure/core" since="2.0.0" />

This strategy defines how an Order can be split into multiple sub-orders for the use-case of
a multivendor application.

:::info

This is configured via the `orderOptions.orderSellerStrategy` property of
your VendureConfig.

:::

```ts title="Signature"
interface OrderSellerStrategy extends InjectableStrategy {
    setOrderLineSellerChannel?(
        ctx: RequestContext,
        orderLine: OrderLine,
    ): Channel | undefined | Promise<Channel | undefined>;
    splitOrder?(ctx: RequestContext, order: Order): SplitOrderContents[] | Promise<SplitOrderContents[]>;
    afterSellerOrdersCreated?(
        ctx: RequestContext,
        aggregateOrder: Order,
        sellerOrders: Order[],
    ): void | Promise<void>;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### setOrderLineSellerChannel

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, orderLine: <a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a>) => <a href='/reference/typescript-api/entities/channel#channel'>Channel</a> | undefined | Promise&#60;<a href='/reference/typescript-api/entities/channel#channel'>Channel</a> | undefined&#62;`}   />

This method is called whenever a new OrderLine is added to the Order via the `addItemToOrder` mutation or the
underlying `addItemToOrder()` method of the <a href='/reference/typescript-api/services/order-service#orderservice'>OrderService</a>.

It should return the Channel to which this OrderLine will be assigned, which will be used to set the
<a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a> `sellerChannel` property.
### splitOrder

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>) => <a href='/reference/typescript-api/orders/order-seller-strategy#splitordercontents'>SplitOrderContents</a>[] | Promise&#60;<a href='/reference/typescript-api/orders/order-seller-strategy#splitordercontents'>SplitOrderContents</a>[]&#62;`}   />

Upon checkout (by default, when the Order moves from "active" to "inactive" according to the <a href='/reference/typescript-api/orders/order-placed-strategy#orderplacedstrategy'>OrderPlacedStrategy</a>),
this method will be called in order to split the Order into multiple Orders, one for each Seller.
### afterSellerOrdersCreated

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, aggregateOrder: <a href='/reference/typescript-api/entities/order#order'>Order</a>, sellerOrders: <a href='/reference/typescript-api/entities/order#order'>Order</a>[]) => void | Promise&#60;void&#62;`}   />

This method is called after splitting the orders, including calculating the totals for each of the seller Orders.
This method can be used to set platform fee surcharges on the seller Orders as well as perform any payment processing
needed.


</div>


## DefaultOrderSellerStrategy

<GenerationInfo sourceFile="packages/core/src/config/order/default-order-seller-strategy.ts" sourceLine="11" packageName="@vendure/core" since="2.0.0" />

The DefaultOrderSellerStrategy treats the Order as single-vendor.

```ts title="Signature"
class DefaultOrderSellerStrategy implements OrderSellerStrategy {

}
```
* Implements: <code><a href='/reference/typescript-api/orders/order-seller-strategy#ordersellerstrategy'>OrderSellerStrategy</a></code>




## SplitOrderContents

<GenerationInfo sourceFile="packages/core/src/config/order/order-seller-strategy.ts" sourceLine="19" packageName="@vendure/core" since="2.0.0" />

The contents of the aggregate Order which make up a single seller Order.

```ts title="Signature"
interface SplitOrderContents {
    channelId: ID;
    state: OrderState;
    lines: OrderLine[];
    shippingLines: ShippingLine[];
}
```

<div className="members-wrapper">

### channelId

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a>`}   />


### state

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/orders/order-process#orderstate'>OrderState</a>`}   />


### lines

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a>[]`}   />


### shippingLines

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/shipping-line#shippingline'>ShippingLine</a>[]`}   />




</div>


---

---
title: "StockAllocationStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## StockAllocationStrategy

<GenerationInfo sourceFile="packages/core/src/config/order/stock-allocation-strategy.ts" sourceLine="20" packageName="@vendure/core" />

This strategy is responsible for deciding at which stage in the order process
stock will be allocated.

:::info

This is configured via the `orderOptions.stockAllocationStrategy` property of
your VendureConfig.

:::

```ts title="Signature"
interface StockAllocationStrategy extends InjectableStrategy {
    shouldAllocateStock(
        ctx: RequestContext,
        fromState: OrderState,
        toState: OrderState,
        order: Order,
    ): boolean | Promise<boolean>;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### shouldAllocateStock

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, fromState: <a href='/reference/typescript-api/orders/order-process#orderstate'>OrderState</a>, toState: <a href='/reference/typescript-api/orders/order-process#orderstate'>OrderState</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>) => boolean | Promise&#60;boolean&#62;`}   />

This method is called whenever an Order transitions from one state to another.
If it resolves to `true`, then stock will be allocated for this order.


</div>


---

---
title: "DefaultPaymentProcess"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## defaultPaymentProcess

<GenerationInfo sourceFile="packages/core/src/config/payment/default-payment-process.ts" sourceLine="26" packageName="@vendure/core" />

The default <a href='/reference/typescript-api/payment/payment-process#paymentprocess'>PaymentProcess</a>



---

---
title: "DefaultRefundProcess"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## defaultRefundProcess

<GenerationInfo sourceFile="packages/core/src/config/refund/default-refund-process.ts" sourceLine="16" packageName="@vendure/core" />

The default <a href='/reference/typescript-api/payment/refund-process#refundprocess'>RefundProcess</a>.



---

---
title: "DummyPaymentHandler"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## dummyPaymentHandler

<GenerationInfo sourceFile="packages/core/src/config/payment/dummy-payment-method-handler.ts" sourceLine="27" packageName="@vendure/core" />

A dummy PaymentMethodHandler which simply creates a Payment without any integration
with an external payment provider. Intended only for use in development.

By specifying certain metadata keys, failures can be simulated:

*Example*

```GraphQL
addPaymentToOrder(input: {
  method: 'dummy-payment-method',
  metadata: {
    shouldDecline: false,
    shouldError: false,
    shouldErrorOnSettle: true,
  }
}) {
  # ...
}
```



---

---
title: "Payment"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "PaymentMethodConfigOptions"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## PaymentMethodConfigOptions

<GenerationInfo sourceFile="packages/core/src/config/payment/payment-method-handler.ts" sourceLine="255" packageName="@vendure/core" />

Defines the object which is used to construct the <a href='/reference/typescript-api/payment/payment-method-handler#paymentmethodhandler'>PaymentMethodHandler</a>.

```ts title="Signature"
interface PaymentMethodConfigOptions<T extends ConfigArgs> extends ConfigurableOperationDefOptions<T> {
    createPayment: CreatePaymentFn<T>;
    settlePayment: SettlePaymentFn<T>;
    cancelPayment?: CancelPaymentFn<T>;
    createRefund?: CreateRefundFn<T>;
    onStateTransitionStart?: OnTransitionStartFn<PaymentState, PaymentTransitionData>;
}
```
* Extends: <code><a href='/reference/typescript-api/configurable-operation-def/configurable-operation-def-options#configurableoperationdefoptions'>ConfigurableOperationDefOptions</a>&#60;T&#62;</code>



<div className="members-wrapper">

### createPayment

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/payment/payment-method-types#createpaymentfn'>CreatePaymentFn</a>&#60;T&#62;`}   />

This function provides the logic for creating a payment. For example,
it may call out to a third-party service with the data and should return a
<a href='/reference/typescript-api/payment/payment-method-types#createpaymentresult'>CreatePaymentResult</a> object contains the details of the payment.
### settlePayment

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/payment/payment-method-types#settlepaymentfn'>SettlePaymentFn</a>&#60;T&#62;`}   />

This function provides the logic for settling a payment, also known as "capturing".
For payment integrations that settle/capture the payment on creation (i.e. the
`createPayment()` method returns with a state of `'Settled'`) this method
need only return `{ success: true }`.
### cancelPayment

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/payment/payment-method-types#cancelpaymentfn'>CancelPaymentFn</a>&#60;T&#62;`}  since="1.7.0"  />

This function provides the logic for cancelling a payment, which would be invoked when a call is
made to the `cancelPayment` mutation in the Admin API. Cancelling a payment can apply
if, for example, you have created a "payment intent" with the payment provider but not yet
completed the payment. It allows the incomplete payment to be cleaned up on the provider's end
if it gets cancelled via Vendure.
### createRefund

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/payment/payment-method-types#createrefundfn'>CreateRefundFn</a>&#60;T&#62;`}   />

This function provides the logic for refunding a payment created with this
payment method. Some payment providers may not provide the facility to
programmatically create a refund. In such a case, this method should be
omitted and any Refunds will have to be settled manually by an administrator.
### onStateTransitionStart

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/state-machine/state-machine-config#ontransitionstartfn'>OnTransitionStartFn</a>&#60;<a href='/reference/typescript-api/payment/payment-state#paymentstate'>PaymentState</a>, <a href='/reference/typescript-api/payment/payment-transition-data#paymenttransitiondata'>PaymentTransitionData</a>&#62;`}   />

This function, when specified, will be invoked before any transition from one <a href='/reference/typescript-api/payment/payment-state#paymentstate'>PaymentState</a> to another.
The return value (a sync / async `boolean`) is used to determine whether the transition is permitted.


</div>


---

---
title: "PaymentMethodEligibilityChecker"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## PaymentMethodEligibilityChecker

<GenerationInfo sourceFile="packages/core/src/config/payment/payment-method-eligibility-checker.ts" sourceLine="47" packageName="@vendure/core" />

The PaymentMethodEligibilityChecker class is used to check whether an order qualifies for a
given <a href='/reference/typescript-api/entities/payment-method#paymentmethod'>PaymentMethod</a>.

*Example*

```ts
const ccPaymentEligibilityChecker = new PaymentMethodEligibilityChecker({
    code: 'order-total-payment-eligibility-checker',
    description: [{ languageCode: LanguageCode.en, value: 'Checks that the order total is above some minimum value' }],
    args: {
        orderMinimum: { type: 'int', ui: { component: 'currency-form-input' } },
    },
    check: (ctx, order, args) => {
        return order.totalWithTax >= args.orderMinimum;
    },
});
```

```ts title="Signature"
class PaymentMethodEligibilityChecker<T extends ConfigArgs = ConfigArgs> extends ConfigurableOperationDef<T> {
    constructor(config: PaymentMethodEligibilityCheckerConfig<T>)
}
```
* Extends: <code><a href='/reference/typescript-api/configurable-operation-def/#configurableoperationdef'>ConfigurableOperationDef</a>&#60;T&#62;</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(config: <a href='/reference/typescript-api/payment/payment-method-eligibility-checker#paymentmethodeligibilitycheckerconfig'>PaymentMethodEligibilityCheckerConfig</a>&#60;T&#62;) => PaymentMethodEligibilityChecker`}   />




</div>


## PaymentMethodEligibilityCheckerConfig

<GenerationInfo sourceFile="packages/core/src/config/payment/payment-method-eligibility-checker.ts" sourceLine="20" packageName="@vendure/core" />

Configuration passed into the constructor of a <a href='/reference/typescript-api/payment/payment-method-eligibility-checker#paymentmethodeligibilitychecker'>PaymentMethodEligibilityChecker</a> to
configure its behavior.

```ts title="Signature"
interface PaymentMethodEligibilityCheckerConfig<T extends ConfigArgs> extends ConfigurableOperationDefOptions<T> {
    check: CheckPaymentMethodEligibilityCheckerFn<T>;
}
```
* Extends: <code><a href='/reference/typescript-api/configurable-operation-def/configurable-operation-def-options#configurableoperationdefoptions'>ConfigurableOperationDefOptions</a>&#60;T&#62;</code>



<div className="members-wrapper">

### check

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/payment/payment-method-eligibility-checker#checkpaymentmethodeligibilitycheckerfn'>CheckPaymentMethodEligibilityCheckerFn</a>&#60;T&#62;`}   />




</div>


## CheckPaymentMethodEligibilityCheckerFn

<GenerationInfo sourceFile="packages/core/src/config/payment/payment-method-eligibility-checker.ts" sourceLine="83" packageName="@vendure/core" />

A function which implements logic to determine whether a given <a href='/reference/typescript-api/entities/order#order'>Order</a> is eligible for
a particular payment method. If the function resolves to `false` or a string, the check is
considered to have failed. A string result can be used to provide information about the
reason for ineligibility, if desired.

```ts title="Signature"
type CheckPaymentMethodEligibilityCheckerFn<T extends ConfigArgs> = (
    ctx: RequestContext,
    order: Order,
    args: ConfigArgValues<T>,
    method: PaymentMethod,
) => boolean | string | Promise<boolean | string>
```


---

---
title: "PaymentMethodHandler"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## PaymentMethodHandler

<GenerationInfo sourceFile="packages/core/src/config/payment/payment-method-handler.ts" sourceLine="354" packageName="@vendure/core" />

A PaymentMethodHandler contains the code which is used to generate a Payment when a call to the
`addPaymentToOrder` mutation is made. It contains any necessary steps of interfacing with a
third-party payment gateway before the Payment is created and can also define actions to fire
when the state of the payment is changed.

PaymentMethodHandlers are instantiated using a <a href='/reference/typescript-api/payment/payment-method-config-options#paymentmethodconfigoptions'>PaymentMethodConfigOptions</a> object, which
configures the business logic used to create, settle and refund payments.

*Example*

```ts
import { PaymentMethodHandler, CreatePaymentResult, SettlePaymentResult, LanguageCode } from '@vendure/core';
// A mock 3rd-party payment SDK
import gripeSDK from 'gripe';

export const examplePaymentHandler = new PaymentMethodHandler({
  code: 'example-payment-provider',
  description: [{
    languageCode: LanguageCode.en,
    value: 'Example Payment Provider',
  }],
  args: {
    apiKey: { type: 'string' },
  },
  createPayment: async (ctx, order, amount, args, metadata): Promise<CreatePaymentResult> => {
    try {
      const result = await gripeSDK.charges.create({
        amount,
        apiKey: args.apiKey,
        source: metadata.authToken,
      });
      return {
        amount: order.total,
        state: 'Settled' as const,
        transactionId: result.id.toString(),
        metadata: result.outcome,
      };
    } catch (err: any) {
      return {
        amount: order.total,
        state: 'Declined' as const,
        metadata: {
          errorMessage: err.message,
        },
      };
    }
  },
  settlePayment: async (ctx, order, payment, args): Promise<SettlePaymentResult> => {
    return { success: true };
  }
});
```

```ts title="Signature"
class PaymentMethodHandler<T extends ConfigArgs = ConfigArgs> extends ConfigurableOperationDef<T> {
    constructor(config: PaymentMethodConfigOptions<T>)
}
```
* Extends: <code><a href='/reference/typescript-api/configurable-operation-def/#configurableoperationdef'>ConfigurableOperationDef</a>&#60;T&#62;</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(config: <a href='/reference/typescript-api/payment/payment-method-config-options#paymentmethodconfigoptions'>PaymentMethodConfigOptions</a>&#60;T&#62;) => PaymentMethodHandler`}   />




</div>


---

---
title: "Payment Method Types"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## CreatePaymentResult

<GenerationInfo sourceFile="packages/core/src/config/payment/payment-method-handler.ts" sourceLine="30" packageName="@vendure/core" />

This object is the return value of the <a href='/reference/typescript-api/payment/payment-method-types#createpaymentfn'>CreatePaymentFn</a>.

```ts title="Signature"
interface CreatePaymentResult {
    amount: number;
    state: Exclude<PaymentState, 'Error'>;
    transactionId?: string;
    errorMessage?: string;
    metadata?: PaymentMetadata;
}
```

<div className="members-wrapper">

### amount

<MemberInfo kind="property" type={`number`}   />

The amount (as an integer - i.e. $10 = `1000`) that this payment is for.
Typically this should equal the Order total, unless multiple payment methods
are being used for the order.
### state

<MemberInfo kind="property" type={`Exclude&#60;<a href='/reference/typescript-api/payment/payment-state#paymentstate'>PaymentState</a>, 'Error'&#62;`}   />

The <a href='/reference/typescript-api/payment/payment-state#paymentstate'>PaymentState</a> of the resulting Payment.

In a single-step payment flow, this should be set to `'Settled'`.
In a two-step flow, this should be set to `'Authorized'`.

If using a <a href='/reference/typescript-api/payment/payment-process#paymentprocess'>PaymentProcess</a>, may be something else
entirely according to your business logic.
### transactionId

<MemberInfo kind="property" type={`string`}   />

The unique payment reference code typically assigned by
the payment provider.
### errorMessage

<MemberInfo kind="property" type={`string`}   />

If the payment is declined or fails for ome other reason, pass the
relevant error message here, and it gets returned with the
ErrorResponse of the `addPaymentToOrder` mutation.
### metadata

<MemberInfo kind="property" type={`PaymentMetadata`}   />

This field can be used to store other relevant data which is often
provided by the payment provider, such as security data related to
the payment method or data used in troubleshooting or debugging.

Any data stored in the optional `public` property will be available
via the Shop API. This is useful for certain checkout flows such as
external gateways, where the payment provider returns a unique
url which must then be passed to the storefront app.


</div>


## CreatePaymentErrorResult

<GenerationInfo sourceFile="packages/core/src/config/payment/payment-method-handler.ts" sourceLine="83" packageName="@vendure/core" />

This object is the return value of the <a href='/reference/typescript-api/payment/payment-method-types#createpaymentfn'>CreatePaymentFn</a> when there has been an error.

```ts title="Signature"
interface CreatePaymentErrorResult {
    amount: number;
    state: 'Error';
    transactionId?: string;
    errorMessage: string;
    metadata?: PaymentMetadata;
}
```

<div className="members-wrapper">

### amount

<MemberInfo kind="property" type={`number`}   />


### state

<MemberInfo kind="property" type={`'Error'`}   />


### transactionId

<MemberInfo kind="property" type={`string`}   />


### errorMessage

<MemberInfo kind="property" type={`string`}   />


### metadata

<MemberInfo kind="property" type={`PaymentMetadata`}   />




</div>


## CreateRefundResult

<GenerationInfo sourceFile="packages/core/src/config/payment/payment-method-handler.ts" sourceLine="98" packageName="@vendure/core" />

This object is the return value of the <a href='/reference/typescript-api/payment/payment-method-types#createrefundfn'>CreateRefundFn</a>.

```ts title="Signature"
interface CreateRefundResult {
    state: RefundState;
    transactionId?: string;
    metadata?: PaymentMetadata;
}
```

<div className="members-wrapper">

### state

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/payment/refund-state#refundstate'>RefundState</a>`}   />


### transactionId

<MemberInfo kind="property" type={`string`}   />


### metadata

<MemberInfo kind="property" type={`PaymentMetadata`}   />




</div>


## SettlePaymentResult

<GenerationInfo sourceFile="packages/core/src/config/payment/payment-method-handler.ts" sourceLine="112" packageName="@vendure/core" />

This object is the return value of the <a href='/reference/typescript-api/payment/payment-method-types#settlepaymentfn'>SettlePaymentFn</a> when the Payment
has been successfully settled.

```ts title="Signature"
interface SettlePaymentResult {
    success: true;
    metadata?: PaymentMetadata;
}
```

<div className="members-wrapper">

### success

<MemberInfo kind="property" type={`true`}   />


### metadata

<MemberInfo kind="property" type={`PaymentMetadata`}   />




</div>


## SettlePaymentErrorResult

<GenerationInfo sourceFile="packages/core/src/config/payment/payment-method-handler.ts" sourceLine="125" packageName="@vendure/core" />

This object is the return value of the <a href='/reference/typescript-api/payment/payment-method-types#settlepaymentfn'>SettlePaymentFn</a> when the Payment
could not be settled.

```ts title="Signature"
interface SettlePaymentErrorResult {
    success: false;
    state?: Exclude<PaymentState, 'Settled'>;
    errorMessage?: string;
    metadata?: PaymentMetadata;
}
```

<div className="members-wrapper">

### success

<MemberInfo kind="property" type={`false`}   />


### state

<MemberInfo kind="property" type={`Exclude&#60;<a href='/reference/typescript-api/payment/payment-state#paymentstate'>PaymentState</a>, 'Settled'&#62;`}   />

The state to transition this Payment to upon unsuccessful settlement.
Defaults to `Error`. Note that if using a different state, it must be
legal to transition to that state from the `Authorized` state according
to the PaymentState config (which can be customized using the
<a href='/reference/typescript-api/payment/payment-process#paymentprocess'>PaymentProcess</a>).
### errorMessage

<MemberInfo kind="property" type={`string`}   />

The message that will be returned when attempting to settle the payment, and will
also be persisted as `Payment.errorMessage`.
### metadata

<MemberInfo kind="property" type={`PaymentMetadata`}   />




</div>


## CancelPaymentResult

<GenerationInfo sourceFile="packages/core/src/config/payment/payment-method-handler.ts" sourceLine="153" packageName="@vendure/core" />

This object is the return value of the <a href='/reference/typescript-api/payment/payment-method-types#cancelpaymentfn'>CancelPaymentFn</a> when the Payment
has been successfully cancelled.

```ts title="Signature"
interface CancelPaymentResult {
    success: true;
    metadata?: PaymentMetadata;
}
```

<div className="members-wrapper">

### success

<MemberInfo kind="property" type={`true`}   />


### metadata

<MemberInfo kind="property" type={`PaymentMetadata`}   />




</div>


## CancelPaymentErrorResult

<GenerationInfo sourceFile="packages/core/src/config/payment/payment-method-handler.ts" sourceLine="165" packageName="@vendure/core" />

This object is the return value of the <a href='/reference/typescript-api/payment/payment-method-types#cancelpaymentfn'>CancelPaymentFn</a> when the Payment
could not be cancelled.

```ts title="Signature"
interface CancelPaymentErrorResult {
    success: false;
    state?: Exclude<PaymentState, 'Cancelled'>;
    errorMessage?: string;
    metadata?: PaymentMetadata;
}
```

<div className="members-wrapper">

### success

<MemberInfo kind="property" type={`false`}   />


### state

<MemberInfo kind="property" type={`Exclude&#60;<a href='/reference/typescript-api/payment/payment-state#paymentstate'>PaymentState</a>, 'Cancelled'&#62;`}   />

The state to transition this Payment to upon unsuccessful cancellation.
Defaults to `Error`. Note that if using a different state, it must be
legal to transition to that state from the `Authorized` state according
to the PaymentState config (which can be customized using the
<a href='/reference/typescript-api/payment/payment-process#paymentprocess'>PaymentProcess</a>).
### errorMessage

<MemberInfo kind="property" type={`string`}   />

The message that will be returned when attempting to cancel the payment, and will
also be persisted as `Payment.errorMessage`.
### metadata

<MemberInfo kind="property" type={`PaymentMetadata`}   />




</div>


## CreatePaymentFn

<GenerationInfo sourceFile="packages/core/src/config/payment/payment-method-handler.ts" sourceLine="193" packageName="@vendure/core" />

This function contains the logic for creating a payment. See <a href='/reference/typescript-api/payment/payment-method-handler#paymentmethodhandler'>PaymentMethodHandler</a> for an example.

Returns a <a href='/reference/typescript-api/payment/payment-method-types#createpaymentresult'>CreatePaymentResult</a>.

```ts title="Signature"
type CreatePaymentFn<T extends ConfigArgs> = (
    ctx: RequestContext,
    order: Order,
    amount: number,
    args: ConfigArgValues<T>,
    metadata: PaymentMetadata,
    method: PaymentMethod,
) => CreatePaymentResult | CreatePaymentErrorResult | Promise<CreatePaymentResult | CreatePaymentErrorResult>
```


## SettlePaymentFn

<GenerationInfo sourceFile="packages/core/src/config/payment/payment-method-handler.ts" sourceLine="209" packageName="@vendure/core" />

This function contains the logic for settling a payment. See <a href='/reference/typescript-api/payment/payment-method-handler#paymentmethodhandler'>PaymentMethodHandler</a> for an example.

```ts title="Signature"
type SettlePaymentFn<T extends ConfigArgs> = (
    ctx: RequestContext,
    order: Order,
    payment: Payment,
    args: ConfigArgValues<T>,
    method: PaymentMethod,
) => SettlePaymentResult | SettlePaymentErrorResult | Promise<SettlePaymentResult | SettlePaymentErrorResult>
```


## CancelPaymentFn

<GenerationInfo sourceFile="packages/core/src/config/payment/payment-method-handler.ts" sourceLine="224" packageName="@vendure/core" />

This function contains the logic for cancelling a payment. See <a href='/reference/typescript-api/payment/payment-method-handler#paymentmethodhandler'>PaymentMethodHandler</a> for an example.

```ts title="Signature"
type CancelPaymentFn<T extends ConfigArgs> = (
    ctx: RequestContext,
    order: Order,
    payment: Payment,
    args: ConfigArgValues<T>,
    method: PaymentMethod,
) => CancelPaymentResult | CancelPaymentErrorResult | Promise<CancelPaymentResult | CancelPaymentErrorResult>
```


## CreateRefundFn

<GenerationInfo sourceFile="packages/core/src/config/payment/payment-method-handler.ts" sourceLine="239" packageName="@vendure/core" />

This function contains the logic for creating a refund. See <a href='/reference/typescript-api/payment/payment-method-handler#paymentmethodhandler'>PaymentMethodHandler</a> for an example.

```ts title="Signature"
type CreateRefundFn<T extends ConfigArgs> = (
    ctx: RequestContext,
    input: RefundOrderInput,
    amount: number,
    order: Order,
    payment: Payment,
    args: ConfigArgValues<T>,
    method: PaymentMethod,
) => CreateRefundResult | Promise<CreateRefundResult>
```


---

---
title: "PaymentOptions"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## PaymentOptions

<GenerationInfo sourceFile="packages/core/src/config/vendure-config.ts" sourceLine="872" packageName="@vendure/core" />

Defines payment-related options in the <a href='/reference/typescript-api/configuration/vendure-config#vendureconfig'>VendureConfig</a>.

```ts title="Signature"
interface PaymentOptions {
    paymentMethodHandlers: PaymentMethodHandler[];
    paymentMethodEligibilityCheckers?: PaymentMethodEligibilityChecker[];
    customPaymentProcess?: Array<PaymentProcess<any>>;
    process?: Array<PaymentProcess<any>>;
    refundProcess?: Array<RefundProcess<any>>;
}
```

<div className="members-wrapper">

### paymentMethodHandlers

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/payment/payment-method-handler#paymentmethodhandler'>PaymentMethodHandler</a>[]`}   />

Defines which <a href='/reference/typescript-api/payment/payment-method-handler#paymentmethodhandler'>PaymentMethodHandler</a>s are available when configuring
<a href='/reference/typescript-api/entities/payment-method#paymentmethod'>PaymentMethod</a>s
### paymentMethodEligibilityCheckers

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/payment/payment-method-eligibility-checker#paymentmethodeligibilitychecker'>PaymentMethodEligibilityChecker</a>[]`}   />

Defines which <a href='/reference/typescript-api/payment/payment-method-eligibility-checker#paymentmethodeligibilitychecker'>PaymentMethodEligibilityChecker</a>s are available when configuring
<a href='/reference/typescript-api/entities/payment-method#paymentmethod'>PaymentMethod</a>s
### customPaymentProcess

<MemberInfo kind="property" type={`Array&#60;<a href='/reference/typescript-api/payment/payment-process#paymentprocess'>PaymentProcess</a>&#60;any&#62;&#62;`}   />


### process

<MemberInfo kind="property" type={`Array&#60;<a href='/reference/typescript-api/payment/payment-process#paymentprocess'>PaymentProcess</a>&#60;any&#62;&#62;`} default={`<a href='/reference/typescript-api/payment/default-payment-process#defaultpaymentprocess'>defaultPaymentProcess</a>`}  since="2.0.0"  />

Allows the definition of custom states and transition logic for the payment process state machine.
Takes an array of objects implementing the <a href='/reference/typescript-api/payment/payment-process#paymentprocess'>PaymentProcess</a> interface.
### refundProcess

<MemberInfo kind="property" type={`Array&#60;<a href='/reference/typescript-api/payment/refund-process#refundprocess'>RefundProcess</a>&#60;any&#62;&#62;`} default={`<a href='/reference/typescript-api/payment/default-refund-process#defaultrefundprocess'>defaultRefundProcess</a>`}   />

Allows the definition of custom states and transition logic for the refund process state machine.
Takes an array of objects implementing the <a href='/reference/typescript-api/payment/refund-process#refundprocess'>RefundProcess</a> interface.


</div>


---

---
title: "PaymentProcess"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## PaymentProcess

<GenerationInfo sourceFile="packages/core/src/config/payment/payment-process.ts" sourceLine="33" packageName="@vendure/core" since="2.0.0" />

A PaymentProcess is used to define the way the payment process works as in: what states a Payment can be
in, and how it may transition from one state to another. Using the `onTransitionStart()` hook, a
PaymentProcess can perform checks before allowing a state transition to occur, and the `onTransitionEnd()`
hook allows logic to be executed after a state change.

For detailed description of the interface members, see the <a href='/reference/typescript-api/state-machine/state-machine-config#statemachineconfig'>StateMachineConfig</a> docs.

:::info

This is configured via the `paymentOptions.process` property of
your VendureConfig.

:::

```ts title="Signature"
interface PaymentProcess<State extends keyof CustomPaymentStates | string> extends InjectableStrategy {
    transitions?: Transitions<State, State | PaymentState> & Partial<Transitions<PaymentState | State>>;
    onTransitionStart?: OnTransitionStartFn<State | PaymentState, PaymentTransitionData>;
    onTransitionEnd?: OnTransitionEndFn<State | PaymentState, PaymentTransitionData>;
    onTransitionError?: OnTransitionErrorFn<State | PaymentState>;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### transitions

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/state-machine/transitions#transitions'>Transitions</a>&#60;State, State | <a href='/reference/typescript-api/payment/payment-state#paymentstate'>PaymentState</a>&#62; &#38; Partial&#60;<a href='/reference/typescript-api/state-machine/transitions#transitions'>Transitions</a>&#60;<a href='/reference/typescript-api/payment/payment-state#paymentstate'>PaymentState</a> | State&#62;&#62;`}   />


### onTransitionStart

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/state-machine/state-machine-config#ontransitionstartfn'>OnTransitionStartFn</a>&#60;State | <a href='/reference/typescript-api/payment/payment-state#paymentstate'>PaymentState</a>, <a href='/reference/typescript-api/payment/payment-transition-data#paymenttransitiondata'>PaymentTransitionData</a>&#62;`}   />


### onTransitionEnd

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/state-machine/state-machine-config#ontransitionendfn'>OnTransitionEndFn</a>&#60;State | <a href='/reference/typescript-api/payment/payment-state#paymentstate'>PaymentState</a>, <a href='/reference/typescript-api/payment/payment-transition-data#paymenttransitiondata'>PaymentTransitionData</a>&#62;`}   />


### onTransitionError

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/state-machine/state-machine-config#ontransitionerrorfn'>OnTransitionErrorFn</a>&#60;State | <a href='/reference/typescript-api/payment/payment-state#paymentstate'>PaymentState</a>&#62;`}   />




</div>


---

---
title: "PaymentState"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## PaymentState

<GenerationInfo sourceFile="packages/core/src/service/helpers/payment-state-machine/payment-state.ts" sourceLine="27" packageName="@vendure/core" />

These are the default states of the payment process.

```ts title="Signature"
type PaymentState = | 'Created'
    | 'Error'
    | 'Cancelled'
    | keyof CustomPaymentStates
    | keyof PaymentStates
```


---

---
title: "PaymentStates"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## PaymentStates

<GenerationInfo sourceFile="packages/core/src/service/helpers/payment-state-machine/payment-state.ts" sourceLine="19" packageName="@vendure/core" />

An interface to extend standard <a href='/reference/typescript-api/payment/payment-state#paymentstate'>PaymentState</a>.

```ts title="Signature"
interface PaymentStates {

}
```


---

---
title: "PaymentTransitionData"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## PaymentTransitionData

<GenerationInfo sourceFile="packages/core/src/service/helpers/payment-state-machine/payment-state.ts" sourceLine="41" packageName="@vendure/core" />

The data which is passed to the `onStateTransitionStart` function configured when constructing
a new `PaymentMethodHandler`

```ts title="Signature"
interface PaymentTransitionData {
    ctx: RequestContext;
    payment: Payment;
    order: Order;
}
```

<div className="members-wrapper">

### ctx

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>`}   />


### payment

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/payment#payment'>Payment</a>`}   />


### order

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/order#order'>Order</a>`}   />




</div>


---

---
title: "RefundProcess"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## RefundProcess

<GenerationInfo sourceFile="packages/core/src/config/refund/refund-process.ts" sourceLine="25" packageName="@vendure/core" />

A RefundProcess is used to define the way the refund process works as in: what states a Refund can be
in, and how it may transition from one state to another. Using the `onTransitionStart()` hook, a
RefundProcess can perform checks before allowing a state transition to occur, and the `onTransitionEnd()`
hook allows logic to be executed after a state change.

For detailed description of the interface members, see the <a href='/reference/typescript-api/state-machine/state-machine-config#statemachineconfig'>StateMachineConfig</a> docs.

```ts title="Signature"
interface RefundProcess<State extends keyof CustomRefundStates | string> extends InjectableStrategy {
    transitions?: Transitions<State, State | RefundState> & Partial<Transitions<RefundState | State>>;
    onTransitionStart?: OnTransitionStartFn<State | RefundState, RefundTransitionData>;
    onTransitionEnd?: OnTransitionEndFn<State | RefundState, RefundTransitionData>;
    onTransitionError?: OnTransitionErrorFn<State | RefundState>;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### transitions

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/state-machine/transitions#transitions'>Transitions</a>&#60;State, State | <a href='/reference/typescript-api/payment/refund-state#refundstate'>RefundState</a>&#62; &#38; Partial&#60;<a href='/reference/typescript-api/state-machine/transitions#transitions'>Transitions</a>&#60;<a href='/reference/typescript-api/payment/refund-state#refundstate'>RefundState</a> | State&#62;&#62;`}   />


### onTransitionStart

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/state-machine/state-machine-config#ontransitionstartfn'>OnTransitionStartFn</a>&#60;State | <a href='/reference/typescript-api/payment/refund-state#refundstate'>RefundState</a>, <a href='/reference/typescript-api/payment/refund-transition-data#refundtransitiondata'>RefundTransitionData</a>&#62;`}   />


### onTransitionEnd

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/state-machine/state-machine-config#ontransitionendfn'>OnTransitionEndFn</a>&#60;State | <a href='/reference/typescript-api/payment/refund-state#refundstate'>RefundState</a>, <a href='/reference/typescript-api/payment/refund-transition-data#refundtransitiondata'>RefundTransitionData</a>&#62;`}   />


### onTransitionError

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/state-machine/state-machine-config#ontransitionerrorfn'>OnTransitionErrorFn</a>&#60;State | <a href='/reference/typescript-api/payment/refund-state#refundstate'>RefundState</a>&#62;`}   />




</div>


---

---
title: "RefundState"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## RefundState

<GenerationInfo sourceFile="packages/core/src/service/helpers/refund-state-machine/refund-state.ts" sourceLine="27" packageName="@vendure/core" />

These are the default states of the refund process.

```ts title="Signature"
type RefundState = 'Pending' | 'Settled' | 'Failed' | keyof CustomRefundStates | keyof RefundStates
```


---

---
title: "RefundStates"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## RefundStates

<GenerationInfo sourceFile="packages/core/src/service/helpers/refund-state-machine/refund-state.ts" sourceLine="19" packageName="@vendure/core" />

An interface to extend standard <a href='/reference/typescript-api/payment/refund-state#refundstate'>RefundState</a>.

```ts title="Signature"
interface RefundStates {

}
```


---

---
title: "RefundTransitionData"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## RefundTransitionData

<GenerationInfo sourceFile="packages/core/src/service/helpers/refund-state-machine/refund-state.ts" sourceLine="35" packageName="@vendure/core" />

The data which is passed to the state transition handler of the RefundStateMachine.

```ts title="Signature"
interface RefundTransitionData {
    ctx: RequestContext;
    order: Order;
    refund: Refund;
}
```

<div className="members-wrapper">

### ctx

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>`}   />


### order

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/order#order'>Order</a>`}   />


### refund

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/refund#refund'>Refund</a>`}   />




</div>


---

---
title: "Plugin"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "PluginCommonModule"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## PluginCommonModule

<GenerationInfo sourceFile="packages/core/src/plugin/plugin-common.module.ts" sourceLine="30" packageName="@vendure/core" />

This module provides the common services, configuration, and event bus capabilities
required by a typical plugin. It should be imported into plugins to avoid having to
repeat the same boilerplate for each individual plugin.

The PluginCommonModule exports:

* `EventBusModule`, allowing the injection of the <a href='/reference/typescript-api/events/event-bus#eventbus'>EventBus</a> service.
* `ServiceModule` allowing the injection of any of the various entity services such as ProductService, OrderService etc.
* `ConfigModule`, allowing the injection of the ConfigService.
* `JobQueueModule`, allowing the injection of the <a href='/reference/typescript-api/job-queue/job-queue-service#jobqueueservice'>JobQueueService</a>.
* `HealthCheckModule`, allowing the injection of the <a href='/reference/typescript-api/health-check/health-check-registry-service#healthcheckregistryservice'>HealthCheckRegistryService</a>.

```ts title="Signature"
class PluginCommonModule {

}
```


---

---
title: "Plugin Utilities"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## createProxyHandler

<GenerationInfo sourceFile="packages/core/src/plugin/plugin-utils.ts" sourceLine="37" packageName="@vendure/core" />

Creates a proxy middleware which proxies the given route to the given port.
Useful for plugins which start their own servers but should be accessible
via the main Vendure url.

*Example*

```ts
// Example usage in the `configuration` method of a VendurePlugin.
// Imagine that we have started a Node server on port 5678
// running some service which we want to access via the `/my-plugin/`
// route of the main Vendure server.
@VendurePlugin({
  configuration: (config: Required<VendureConfig>) => {
      config.apiOptions.middleware.push({
          handler: createProxyHandler({
              label: 'Admin UI',
              route: 'my-plugin',
              port: 5678,
          }),
          route: 'my-plugin',
      });
      return config;
  }
})
export class MyPlugin {}
```

```ts title="Signature"
function createProxyHandler(options: ProxyOptions): RequestHandler
```
Parameters

### options

<MemberInfo kind="parameter" type={`<a href='/reference/typescript-api/plugin/plugin-utilities#proxyoptions'>ProxyOptions</a>`} />



## ProxyOptions

<GenerationInfo sourceFile="packages/core/src/plugin/plugin-utils.ts" sourceLine="74" packageName="@vendure/core" />

Options to configure proxy middleware via <a href='/reference/typescript-api/plugin/plugin-utilities#createproxyhandler'>createProxyHandler</a>.

```ts title="Signature"
interface ProxyOptions {
    label: string;
    route: string;
    port: number;
    hostname?: string;
    basePath?: string;
}
```

<div className="members-wrapper">

### label

<MemberInfo kind="property" type={`string`}   />

A human-readable label for the service which is being proxied. Used to
generate more informative logs.
### route

<MemberInfo kind="property" type={`string`}   />

The route of the Vendure server which will act as the proxy url.
### port

<MemberInfo kind="property" type={`number`}   />

The port on which the service being proxied is running.
### hostname

<MemberInfo kind="property" type={`string`} default={`'localhost'`}   />

The hostname of the server on which the service being proxied is running.
### basePath

<MemberInfo kind="property" type={`string`}   />

An optional base path on the proxied server.


</div>


---

---
title: "VendurePluginMetadata"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## VendurePluginMetadata

<GenerationInfo sourceFile="packages/core/src/plugin/vendure-plugin.ts" sourceLine="23" packageName="@vendure/core" />

Defines the metadata of a Vendure plugin. This interface is an superset of the [Nestjs ModuleMetadata](https://docs.nestjs.com/modules)
(which allows the definition of `imports`, `exports`, `providers` and `controllers`), which means
that any Nestjs Module is a valid Vendure plugin. In addition, the VendurePluginMetadata allows the definition of
extra properties specific to Vendure.

```ts title="Signature"
interface VendurePluginMetadata extends ModuleMetadata {
    configuration?: PluginConfigurationFn;
    shopApiExtensions?: APIExtensionDefinition;
    adminApiExtensions?: APIExtensionDefinition;
    entities?: Array<Type<any>> | (() => Array<Type<any>>);
    dashboard?: DashboardExtension;
    compatibility?: string;
}
```
* Extends: <code>ModuleMetadata</code>



<div className="members-wrapper">

### configuration

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/plugin/vendure-plugin-metadata#pluginconfigurationfn'>PluginConfigurationFn</a>`}   />

A function which can modify the <a href='/reference/typescript-api/configuration/vendure-config#vendureconfig'>VendureConfig</a> object before the server bootstraps.
### shopApiExtensions

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/plugin/vendure-plugin-metadata#apiextensiondefinition'>APIExtensionDefinition</a>`}   />

The plugin may extend the default Vendure GraphQL shop api by providing extended
schema definitions and any required resolvers.
### adminApiExtensions

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/plugin/vendure-plugin-metadata#apiextensiondefinition'>APIExtensionDefinition</a>`}   />

The plugin may extend the default Vendure GraphQL admin api by providing extended
schema definitions and any required resolvers.
### entities

<MemberInfo kind="property" type={`Array&#60;Type&#60;any&#62;&#62; | (() =&#62; Array&#60;Type&#60;any&#62;&#62;)`}   />

The plugin may define custom [TypeORM database entities](https://typeorm.io/#/entities).
### dashboard

<MemberInfo kind="property" type={`DashboardExtension`}   />


### compatibility

<MemberInfo kind="property" type={`string`}  since="2.0.0"  />

The plugin should define a valid [semver version string](https://www.npmjs.com/package/semver) to indicate which versions of
Vendure core it is compatible with. Attempting to use a plugin with an incompatible
version of Vendure will result in an error and the server will be unable to bootstrap.

If a plugin does not define this property, a message will be logged on bootstrap that the plugin is not
guaranteed to be compatible with the current version of Vendure.

To effectively disable this check for a plugin, you can use an overly-permissive string such as `>0.0.0`.

:::note
Since Vendure v3.1.0, it is possible to ignore compatibility errors for specific plugins by
passing the `ignoreCompatibilityErrorsForPlugins` option to the <a href='/reference/typescript-api/common/bootstrap#bootstrap'>bootstrap</a> function.
:::

*Example*

```ts
compatibility: '^3.0.0'
```


</div>


## APIExtensionDefinition

<GenerationInfo sourceFile="packages/core/src/plugin/vendure-plugin.ts" sourceLine="80" packageName="@vendure/core" />

An object which allows a plugin to extend the Vendure GraphQL API.

```ts title="Signature"
interface APIExtensionDefinition {
    schema?: DocumentNode | ((schema?: GraphQLSchema) => DocumentNode | undefined);
    resolvers?: Array<Type<any>> | (() => Array<Type<any>>);
    scalars?: Record<string, GraphQLScalarType> | (() => Record<string, GraphQLScalarType>);
}
```

<div className="members-wrapper">

### schema

<MemberInfo kind="property" type={`DocumentNode | ((schema?: GraphQLSchema) =&#62; DocumentNode | undefined)`}   />

Extensions to the schema.
Passes the current schema as an optional argument, allowing the extension to be based on the existing schema.

*Example*

```ts
const schema = gql`extend type SearchReindexResponse {
    timeTaken: Int!
    indexedItemCount: Int!
}`;
```
### resolvers

<MemberInfo kind="property" type={`Array&#60;Type&#60;any&#62;&#62; | (() =&#62; Array&#60;Type&#60;any&#62;&#62;)`}   />

An array of resolvers for the schema extensions. Should be defined as [Nestjs GraphQL resolver](https://docs.nestjs.com/graphql/resolvers-map)
classes, i.e. using the Nest `@Resolver()` decorator etc.
### scalars

<MemberInfo kind="property" type={`Record&#60;string, GraphQLScalarType&#62; | (() =&#62; Record&#60;string, GraphQLScalarType&#62;)`}  since="1.7.0"  />

A map of GraphQL scalar types which should correspond to any custom scalars defined in your schema.
Read more about defining custom scalars in the
[Apollo Server Custom Scalars docs](https://www.apollographql.com/docs/apollo-server/schema/custom-scalars)


</div>


## PluginConfigurationFn

<GenerationInfo sourceFile="packages/core/src/plugin/vendure-plugin.ts" sourceLine="119" packageName="@vendure/core" />

This method is called before the app bootstraps and should be used to perform any needed modifications to the <a href='/reference/typescript-api/configuration/vendure-config#vendureconfig'>VendureConfig</a>.

```ts title="Signature"
type PluginConfigurationFn = (
    config: RuntimeVendureConfig,
) => RuntimeVendureConfig | Promise<RuntimeVendureConfig>
```


---

---
title: "VendurePlugin"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## VendurePlugin

<GenerationInfo sourceFile="packages/core/src/plugin/vendure-plugin.ts" sourceLine="164" packageName="@vendure/core" />

The VendurePlugin decorator is a means of configuring and/or extending the functionality of the Vendure server. A Vendure plugin is
a [Nestjs Module](https://docs.nestjs.com/modules), with optional additional metadata defining things like extensions to the GraphQL API, custom
configuration or new database entities.

As well as configuring the app, a plugin may also extend the GraphQL schema by extending existing types or adding
entirely new types. Database entities and resolvers can also be defined to handle the extended GraphQL types.

*Example*

```ts
import { Controller, Get } from '@nestjs/common';
import { Ctx, PluginCommonModule, ProductService, RequestContext, VendurePlugin } from '@vendure/core';

@Controller('products')
export class ProductsController {
    constructor(private productService: ProductService) {}

    @Get()
    findAll(@Ctx() ctx: RequestContext) {
        return this.productService.findAll(ctx);
    }
}


//A simple plugin which adds a REST endpoint for querying products.
@VendurePlugin({
    imports: [PluginCommonModule],
    controllers: [ProductsController],
})
export class RestPlugin {}
```

```ts title="Signature"
function VendurePlugin(pluginMetadata: VendurePluginMetadata): ClassDecorator
```
Parameters

### pluginMetadata

<MemberInfo kind="parameter" type={`<a href='/reference/typescript-api/plugin/vendure-plugin-metadata#vendurepluginmetadata'>VendurePluginMetadata</a>`} />



---

---
title: "CatalogOptions"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## CatalogOptions

<GenerationInfo sourceFile="packages/core/src/config/vendure-config.ts" sourceLine="721" packageName="@vendure/core" />

Options related to products and collections.

```ts title="Signature"
interface CatalogOptions {
    collectionFilters?: Array<CollectionFilter<any>>;
    productVariantPriceSelectionStrategy?: ProductVariantPriceSelectionStrategy;
    productVariantPriceCalculationStrategy?: ProductVariantPriceCalculationStrategy;
    productVariantPriceUpdateStrategy?: ProductVariantPriceUpdateStrategy;
    stockDisplayStrategy?: StockDisplayStrategy;
    stockLocationStrategy?: StockLocationStrategy;
}
```

<div className="members-wrapper">

### collectionFilters

<MemberInfo kind="property" type={`Array&#60;<a href='/reference/typescript-api/configuration/collection-filter#collectionfilter'>CollectionFilter</a>&#60;any&#62;&#62;`} default={`defaultCollectionFilters`}   />

Allows custom <a href='/reference/typescript-api/configuration/collection-filter#collectionfilter'>CollectionFilter</a>s to be defined.
### productVariantPriceSelectionStrategy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/configuration/product-variant-price-selection-strategy#productvariantpriceselectionstrategy'>ProductVariantPriceSelectionStrategy</a>`} default={`<a href='/reference/typescript-api/configuration/product-variant-price-selection-strategy#defaultproductvariantpriceselectionstrategy'>DefaultProductVariantPriceSelectionStrategy</a>`}  since="2.0.0"  />

Defines the strategy used to select the price of a ProductVariant, based on factors
such as the active Channel and active CurrencyCode.
### productVariantPriceCalculationStrategy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/products-stock/product-variant-price-calculation-strategy#productvariantpricecalculationstrategy'>ProductVariantPriceCalculationStrategy</a>`} default={`DefaultTaxCalculationStrategy`}   />

Defines the strategy used for calculating the price of ProductVariants based
on the Channel settings and active tax Zone.
### productVariantPriceUpdateStrategy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/configuration/product-variant-price-update-strategy#productvariantpriceupdatestrategy'>ProductVariantPriceUpdateStrategy</a>`} default={`<a href='/reference/typescript-api/configuration/product-variant-price-update-strategy#defaultproductvariantpriceupdatestrategy'>DefaultProductVariantPriceUpdateStrategy</a>`}  since="2.2.0"  />

Defines the strategy which determines what happens to a ProductVariant's prices
when one of the prices gets updated. For instance, this can be used to synchronize
prices across multiple Channels.
### stockDisplayStrategy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/products-stock/stock-display-strategy#stockdisplaystrategy'>StockDisplayStrategy</a>`} default={`<a href='/reference/typescript-api/products-stock/default-stock-display-strategy#defaultstockdisplaystrategy'>DefaultStockDisplayStrategy</a>`}   />

Defines how the `ProductVariant.stockLevel` value is obtained. It is usually not desirable
to directly expose stock levels over a public API, as this could be considered a leak of
sensitive information. However, the storefront will usually want to display _some_ indication
of whether a given ProductVariant is in stock. The default StockDisplayStrategy will
display "IN_STOCK", "OUT_OF_STOCK" or "LOW_STOCK" rather than exposing the actual saleable
stock level.
### stockLocationStrategy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/products-stock/stock-location-strategy#stocklocationstrategy'>StockLocationStrategy</a>`} default={`<a href='/reference/typescript-api/products-stock/default-stock-location-strategy#defaultstocklocationstrategy'>DefaultStockLocationStrategy</a>`}  since="2.0.0"  />

Defines the strategy used to determine which StockLocation should be used when performing
stock operations such as allocating and releasing stock as well as determining the
amount of stock available for sale.


</div>


---

---
title: "DefaultProductVariantPriceCalculationStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DefaultProductVariantPriceCalculationStrategy

<GenerationInfo sourceFile="packages/core/src/config/catalog/default-product-variant-price-calculation-strategy.ts" sourceLine="18" packageName="@vendure/core" />

A default ProductVariant price calculation function.

```ts title="Signature"
class DefaultProductVariantPriceCalculationStrategy implements ProductVariantPriceCalculationStrategy {
    init(injector: Injector) => ;
    calculate(args: ProductVariantPriceCalculationArgs) => Promise<PriceCalculationResult>;
}
```
* Implements: <code><a href='/reference/typescript-api/products-stock/product-variant-price-calculation-strategy#productvariantpricecalculationstrategy'>ProductVariantPriceCalculationStrategy</a></code>



<div className="members-wrapper">

### init

<MemberInfo kind="method" type={`(injector: <a href='/reference/typescript-api/common/injector#injector'>Injector</a>) => `}   />


### calculate

<MemberInfo kind="method" type={`(args: <a href='/reference/typescript-api/products-stock/product-variant-price-calculation-strategy#productvariantpricecalculationargs'>ProductVariantPriceCalculationArgs</a>) => Promise&#60;<a href='/reference/typescript-api/common/price-calculation-result#pricecalculationresult'>PriceCalculationResult</a>&#62;`}   />




</div>


---

---
title: "DefaultStockDisplayStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DefaultStockDisplayStrategy

<GenerationInfo sourceFile="packages/core/src/config/catalog/default-stock-display-strategy.ts" sourceLine="14" packageName="@vendure/core" />

Displays the `ProductVariant.stockLevel` as either `'IN_STOCK'`, `'OUT_OF_STOCK'` or `'LOW_STOCK'`.
Low stock is defined as a saleable stock level less than or equal to the `lowStockLevel` as passed in
to the constructor (defaults to `2`).

```ts title="Signature"
class DefaultStockDisplayStrategy implements StockDisplayStrategy {
    constructor(lowStockLevel: number = 2)
    getStockLevel(ctx: RequestContext, productVariant: ProductVariant, saleableStockLevel: number) => string;
}
```
* Implements: <code><a href='/reference/typescript-api/products-stock/stock-display-strategy#stockdisplaystrategy'>StockDisplayStrategy</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(lowStockLevel: number = 2) => DefaultStockDisplayStrategy`}   />


### getStockLevel

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, productVariant: <a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>, saleableStockLevel: number) => string`}   />




</div>


---

---
title: "DefaultStockLocationStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DefaultStockLocationStrategy

<GenerationInfo sourceFile="packages/core/src/config/catalog/default-stock-location-strategy.ts" sourceLine="105" packageName="@vendure/core" since="2.0.0" />

The DefaultStockLocationStrategy was the default implementation of the <a href='/reference/typescript-api/products-stock/stock-location-strategy#stocklocationstrategy'>StockLocationStrategy</a>
prior to the introduction of the <a href='/reference/typescript-api/products-stock/multi-channel-stock-location-strategy#multichannelstocklocationstrategy'>MultiChannelStockLocationStrategy</a>.
It assumes only a single StockLocation and that all stock is allocated from that location. When
more than one StockLocation or Channel is used, it will not behave as expected.

```ts title="Signature"
class DefaultStockLocationStrategy extends BaseStockLocationStrategy {
    init(injector: Injector) => ;
    getAvailableStock(ctx: RequestContext, productVariantId: ID, stockLevels: StockLevel[]) => AvailableStock;
    forAllocation(ctx: RequestContext, stockLocations: StockLocation[], orderLine: OrderLine, quantity: number) => LocationWithQuantity[] | Promise<LocationWithQuantity[]>;
}
```
* Extends: <code>BaseStockLocationStrategy</code>



<div className="members-wrapper">

### init

<MemberInfo kind="method" type={`(injector: <a href='/reference/typescript-api/common/injector#injector'>Injector</a>) => `}   />


### getAvailableStock

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, productVariantId: <a href='/reference/typescript-api/common/id#id'>ID</a>, stockLevels: <a href='/reference/typescript-api/entities/stock-level#stocklevel'>StockLevel</a>[]) => <a href='/reference/typescript-api/products-stock/stock-location-strategy#availablestock'>AvailableStock</a>`}   />


### forAllocation

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, stockLocations: <a href='/reference/typescript-api/entities/stock-location#stocklocation'>StockLocation</a>[], orderLine: <a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a>, quantity: number) => <a href='/reference/typescript-api/products-stock/stock-location-strategy#locationwithquantity'>LocationWithQuantity</a>[] | Promise&#60;<a href='/reference/typescript-api/products-stock/stock-location-strategy#locationwithquantity'>LocationWithQuantity</a>[]&#62;`}   />




</div>


---

---
title: "Products Stock"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "MultiChannelStockLocationStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## MultiChannelStockLocationStrategy

<GenerationInfo sourceFile="packages/core/src/config/catalog/multi-channel-stock-location-strategy.ts" sourceLine="32" packageName="@vendure/core" since="3.1.0" />

The MultiChannelStockLocationStrategy is an implementation of the <a href='/reference/typescript-api/products-stock/stock-location-strategy#stocklocationstrategy'>StockLocationStrategy</a>.
which is suitable for both single- and multichannel setups. It takes into account the active
channel when determining stock levels, and also ensures that allocations are made only against
stock locations which are associated with the active channel.

This strategy became the default in Vendure 3.1.0. If you want to use the previous strategy which
does not take channels into account, update your VendureConfig to use to <a href='/reference/typescript-api/products-stock/default-stock-location-strategy#defaultstocklocationstrategy'>DefaultStockLocationStrategy</a>.

```ts title="Signature"
class MultiChannelStockLocationStrategy extends BaseStockLocationStrategy {
    getAvailableStock(ctx: RequestContext, productVariantId: ID, stockLevels: StockLevel[]) => Promise<AvailableStock>;
    forAllocation(ctx: RequestContext, stockLocations: StockLocation[], orderLine: OrderLine, quantity: number) => Promise<LocationWithQuantity[]>;
}
```
* Extends: <code>BaseStockLocationStrategy</code>



<div className="members-wrapper">

### getAvailableStock

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, productVariantId: <a href='/reference/typescript-api/common/id#id'>ID</a>, stockLevels: <a href='/reference/typescript-api/entities/stock-level#stocklevel'>StockLevel</a>[]) => Promise&#60;<a href='/reference/typescript-api/products-stock/stock-location-strategy#availablestock'>AvailableStock</a>&#62;`}   />

Returns the available stock for the given ProductVariant, taking into account the active Channel.
### forAllocation

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, stockLocations: <a href='/reference/typescript-api/entities/stock-location#stocklocation'>StockLocation</a>[], orderLine: <a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a>, quantity: number) => Promise&#60;<a href='/reference/typescript-api/products-stock/stock-location-strategy#locationwithquantity'>LocationWithQuantity</a>[]&#62;`}   />

This method takes into account whether the stock location is applicable to the active channel.
It furthermore respects the `trackInventory` and `outOfStockThreshold` settings of the ProductVariant,
in order to allocate stock only from locations which are relevant to the active channel and which
have sufficient stock available.


</div>


---

---
title: "ProductVariantPriceCalculationStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ProductVariantPriceCalculationStrategy

<GenerationInfo sourceFile="packages/core/src/config/catalog/product-variant-price-calculation-strategy.ts" sourceLine="22" packageName="@vendure/core" />

Defines how ProductVariant are calculated based on the input price, tax zone and current request context.

:::info

This is configured via the `catalogOptions.productVariantPriceCalculationStrategy` property of
your VendureConfig.

:::

```ts title="Signature"
interface ProductVariantPriceCalculationStrategy extends InjectableStrategy {
    calculate(args: ProductVariantPriceCalculationArgs): Promise<PriceCalculationResult>;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### calculate

<MemberInfo kind="method" type={`(args: <a href='/reference/typescript-api/products-stock/product-variant-price-calculation-strategy#productvariantpricecalculationargs'>ProductVariantPriceCalculationArgs</a>) => Promise&#60;<a href='/reference/typescript-api/common/price-calculation-result#pricecalculationresult'>PriceCalculationResult</a>&#62;`}   />




</div>


## ProductVariantPriceCalculationArgs

<GenerationInfo sourceFile="packages/core/src/config/catalog/product-variant-price-calculation-strategy.ts" sourceLine="35" packageName="@vendure/core" />

The arguments passed the `calculate` method of the configured <a href='/reference/typescript-api/products-stock/product-variant-price-calculation-strategy#productvariantpricecalculationstrategy'>ProductVariantPriceCalculationStrategy</a>.

The `productVariant` argument was added in v2.1.0.

```ts title="Signature"
interface ProductVariantPriceCalculationArgs {
    inputPrice: number;
    productVariant: ProductVariant;
    taxCategory: TaxCategory;
    activeTaxZone: Zone;
    ctx: RequestContext;
}
```

<div className="members-wrapper">

### inputPrice

<MemberInfo kind="property" type={`number`}   />


### productVariant

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>`}   />


### taxCategory

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/tax-category#taxcategory'>TaxCategory</a>`}   />


### activeTaxZone

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/zone#zone'>Zone</a>`}   />


### ctx

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>`}   />




</div>


---

---
title: "StockDisplayStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## StockDisplayStrategy

<GenerationInfo sourceFile="packages/core/src/config/catalog/stock-display-strategy.ts" sourceLine="21" packageName="@vendure/core" />

Defines how the `ProductVariant.stockLevel` value is obtained. It is usually not desirable
to directly expose stock levels over a public API, as this could be considered a leak of
sensitive information. However, the storefront will usually want to display _some_ indication
of whether a given ProductVariant is in stock.

:::info

This is configured via the `catalogOptions.stockDisplayStrategy` property of
your VendureConfig.

:::

```ts title="Signature"
interface StockDisplayStrategy extends InjectableStrategy {
    getStockLevel(
        ctx: RequestContext,
        productVariant: ProductVariant,
        saleableStockLevel: number,
    ): string | Promise<string>;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### getStockLevel

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, productVariant: <a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>, saleableStockLevel: number) => string | Promise&#60;string&#62;`}   />

Returns a string representing the stock level, which will be used directly
in the GraphQL `ProductVariant.stockLevel` field.


</div>


---

---
title: "StockLocationStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## StockLocationStrategy

<GenerationInfo sourceFile="packages/core/src/config/catalog/stock-location-strategy.ts" sourceLine="55" packageName="@vendure/core" since="2.0.0" />

The StockLocationStrategy is responsible for determining which <a href='/reference/typescript-api/entities/stock-location#stocklocation'>StockLocation</a>s
should be used to fulfill an <a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a> and how much stock should be allocated
from each location. It is also used to determine the available stock for a given
<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>.

:::info

This is configured via the `catalogOptions.stockLocationStrategy` property of
your VendureConfig.

:::

```ts title="Signature"
interface StockLocationStrategy extends InjectableStrategy {
    getAvailableStock(
        ctx: RequestContext,
        productVariantId: ID,
        stockLevels: StockLevel[],
    ): AvailableStock | Promise<AvailableStock>;
    forAllocation(
        ctx: RequestContext,
        stockLocations: StockLocation[],
        orderLine: OrderLine,
        quantity: number,
    ): LocationWithQuantity[] | Promise<LocationWithQuantity[]>;
    forRelease(
        ctx: RequestContext,
        stockLocations: StockLocation[],
        orderLine: OrderLine,
        quantity: number,
    ): LocationWithQuantity[] | Promise<LocationWithQuantity[]>;
    forSale(
        ctx: RequestContext,
        stockLocations: StockLocation[],
        orderLine: OrderLine,
        quantity: number,
    ): LocationWithQuantity[] | Promise<LocationWithQuantity[]>;
    forCancellation(
        ctx: RequestContext,
        stockLocations: StockLocation[],
        orderLine: OrderLine,
        quantity: number,
    ): LocationWithQuantity[] | Promise<LocationWithQuantity[]>;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### getAvailableStock

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, productVariantId: <a href='/reference/typescript-api/common/id#id'>ID</a>, stockLevels: <a href='/reference/typescript-api/entities/stock-level#stocklevel'>StockLevel</a>[]) => <a href='/reference/typescript-api/products-stock/stock-location-strategy#availablestock'>AvailableStock</a> | Promise&#60;<a href='/reference/typescript-api/products-stock/stock-location-strategy#availablestock'>AvailableStock</a>&#62;`}   />

Returns the available stock for the given ProductVariant, taking into account
the stock levels at each StockLocation.
### forAllocation

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, stockLocations: <a href='/reference/typescript-api/entities/stock-location#stocklocation'>StockLocation</a>[], orderLine: <a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a>, quantity: number) => <a href='/reference/typescript-api/products-stock/stock-location-strategy#locationwithquantity'>LocationWithQuantity</a>[] | Promise&#60;<a href='/reference/typescript-api/products-stock/stock-location-strategy#locationwithquantity'>LocationWithQuantity</a>[]&#62;`}   />

Determines which StockLocations should be used to when allocating stock when
and Order is placed.
### forRelease

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, stockLocations: <a href='/reference/typescript-api/entities/stock-location#stocklocation'>StockLocation</a>[], orderLine: <a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a>, quantity: number) => <a href='/reference/typescript-api/products-stock/stock-location-strategy#locationwithquantity'>LocationWithQuantity</a>[] | Promise&#60;<a href='/reference/typescript-api/products-stock/stock-location-strategy#locationwithquantity'>LocationWithQuantity</a>[]&#62;`}   />

Determines which StockLocations should be used to when releasing allocated
stock when an OrderLine is cancelled before being fulfilled.
### forSale

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, stockLocations: <a href='/reference/typescript-api/entities/stock-location#stocklocation'>StockLocation</a>[], orderLine: <a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a>, quantity: number) => <a href='/reference/typescript-api/products-stock/stock-location-strategy#locationwithquantity'>LocationWithQuantity</a>[] | Promise&#60;<a href='/reference/typescript-api/products-stock/stock-location-strategy#locationwithquantity'>LocationWithQuantity</a>[]&#62;`}   />

Determines which StockLocations should be used to when creating a Sale
and reducing the stockOnHand upon fulfillment.
### forCancellation

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, stockLocations: <a href='/reference/typescript-api/entities/stock-location#stocklocation'>StockLocation</a>[], orderLine: <a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a>, quantity: number) => <a href='/reference/typescript-api/products-stock/stock-location-strategy#locationwithquantity'>LocationWithQuantity</a>[] | Promise&#60;<a href='/reference/typescript-api/products-stock/stock-location-strategy#locationwithquantity'>LocationWithQuantity</a>[]&#62;`}   />

Determines which StockLocations should be used to when creating a Cancellation
of an OrderLine which has already been fulfilled.


</div>


## AvailableStock

<GenerationInfo sourceFile="packages/core/src/config/catalog/stock-location-strategy.ts" sourceLine="18" packageName="@vendure/core" since="2.0.0" />

The overall available stock for a ProductVariant as determined by the logic of the
<a href='/reference/typescript-api/products-stock/stock-location-strategy#stocklocationstrategy'>StockLocationStrategy</a>'s `getAvailableStock` method.

```ts title="Signature"
interface AvailableStock {
    stockOnHand: number;
    stockAllocated: number;
}
```

<div className="members-wrapper">

### stockOnHand

<MemberInfo kind="property" type={`number`}   />


### stockAllocated

<MemberInfo kind="property" type={`number`}   />




</div>


## LocationWithQuantity

<GenerationInfo sourceFile="packages/core/src/config/catalog/stock-location-strategy.ts" sourceLine="32" packageName="@vendure/core" since="2.0.0" />

Returned by the `StockLocationStrategy` methods to indicate how much stock from each
location should be used in the allocation/sale/release/cancellation of an OrderLine.

```ts title="Signature"
interface LocationWithQuantity {
    location: StockLocation;
    quantity: number;
}
```

<div className="members-wrapper">

### location

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/stock-location#stocklocation'>StockLocation</a>`}   />


### quantity

<MemberInfo kind="property" type={`number`}   />




</div>


---

---
title: "FacetValueChecker"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## FacetValueChecker

<GenerationInfo sourceFile="packages/core/src/service/helpers/facet-value-checker/facet-value-checker.ts" sourceLine="53" packageName="@vendure/core" />

The FacetValueChecker is a helper class used to determine whether a given OrderLine consists
of ProductVariants containing the given FacetValues.

*Example*

```ts
import { FacetValueChecker, LanguageCode, PromotionCondition, TransactionalConnection } from '@vendure/core';

let facetValueChecker: FacetValueChecker;

export const hasFacetValues = new PromotionCondition({
  code: 'at_least_n_with_facets',
  description: [
    { languageCode: LanguageCode.en, value: 'Buy at least { minimum } products with the given facets' },
  ],
  args: {
    minimum: { type: 'int' },
    facets: { type: 'ID', list: true, ui: { component: 'facet-value-form-input' } },
  },
  init(injector) {
    facetValueChecker = injector.get(FacetValueChecker);
  },
  async check(ctx, order, args) {
    let matches = 0;
    for (const line of order.lines) {
      if (await facetValueChecker.hasFacetValues(line, args.facets)) {
          matches += line.quantity;
      }
    }
    return args.minimum <= matches;
  },
});
```

```ts title="Signature"
class FacetValueChecker implements OnModuleInit {
    constructor(connection: TransactionalConnection, cacheService: CacheService, eventBus?: EventBus)
    onModuleInit() => any;
    hasFacetValues(orderLine: OrderLine, facetValueIds: ID[], ctx?: RequestContext) => Promise<boolean>;
}
```
* Implements: <code>OnModuleInit</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, cacheService: <a href='/reference/typescript-api/cache/cache-service#cacheservice'>CacheService</a>, eventBus?: <a href='/reference/typescript-api/events/event-bus#eventbus'>EventBus</a>) => FacetValueChecker`}   />


### onModuleInit

<MemberInfo kind="method" type={`() => any`}   />


### hasFacetValues

<MemberInfo kind="method" type={`(orderLine: <a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a>, facetValueIds: <a href='/reference/typescript-api/common/id#id'>ID</a>[], ctx?: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => Promise&#60;boolean&#62;`}   />

Checks a given <a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a> against the facetValueIds and returns
`true` if the associated <a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a> & <a href='/reference/typescript-api/entities/product#product'>Product</a> together
have *all* the specified <a href='/reference/typescript-api/entities/facet-value#facetvalue'>FacetValue</a>s.


</div>


---

---
title: "Promotions"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "Promotion Action"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## PromotionAction

<GenerationInfo sourceFile="packages/core/src/config/promotion/promotion-action.ts" sourceLine="281" packageName="@vendure/core" />

An abstract class which is extended by <a href='/reference/typescript-api/promotions/promotion-action#promotionitemaction'>PromotionItemAction</a>, <a href='/reference/typescript-api/promotions/promotion-action#promotionorderaction'>PromotionOrderAction</a>,
and <a href='/reference/typescript-api/promotions/promotion-action#promotionshippingaction'>PromotionShippingAction</a>.

```ts title="Signature"
class PromotionAction<T extends ConfigArgs = ConfigArgs, U extends PromotionCondition[] | undefined = any> extends ConfigurableOperationDef<T> {
    readonly priorityValue: number;
    constructor(config: PromotionActionConfig<T, U>)
}
```
* Extends: <code><a href='/reference/typescript-api/configurable-operation-def/#configurableoperationdef'>ConfigurableOperationDef</a>&#60;T&#62;</code>



<div className="members-wrapper">

### priorityValue

<MemberInfo kind="property" type={`number`} default={`0`}   />

Used to determine the order of application of multiple Promotions
on the same Order. See the <a href='/reference/typescript-api/entities/promotion#promotion'>Promotion</a> `priorityScore` field for
more information.
### constructor

<MemberInfo kind="method" type={`(config: <a href='/reference/typescript-api/promotions/promotion-action#promotionactionconfig'>PromotionActionConfig</a>&#60;T, U&#62;) => PromotionAction`}   />




</div>


## PromotionItemAction

<GenerationInfo sourceFile="packages/core/src/config/promotion/promotion-action.ts" sourceLine="354" packageName="@vendure/core" />

Represents a PromotionAction which applies to individual <a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a>s.

*Example*

```ts
// Applies a percentage discount to each OrderLine
const itemPercentageDiscount = new PromotionItemAction({
    code: 'item_percentage_discount',
    args: { discount: 'percentage' },
    execute(ctx, orderLine, args) {
        return -orderLine.unitPrice * (args.discount / 100);
    },
    description: 'Discount every item by { discount }%',
});
```

```ts title="Signature"
class PromotionItemAction<T extends ConfigArgs = ConfigArgs, U extends Array<PromotionCondition<any>> = []> extends PromotionAction<T, U> {
    constructor(config: PromotionItemActionConfig<T, U>)
}
```
* Extends: <code><a href='/reference/typescript-api/promotions/promotion-action#promotionaction'>PromotionAction</a>&#60;T, U&#62;</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(config: <a href='/reference/typescript-api/promotions/promotion-action#promotionitemactionconfig'>PromotionItemActionConfig</a>&#60;T, U&#62;) => PromotionItemAction`}   />




</div>


## PromotionOrderAction

<GenerationInfo sourceFile="packages/core/src/config/promotion/promotion-action.ts" sourceLine="464" packageName="@vendure/core" />

Represents a PromotionAction which applies to the <a href='/reference/typescript-api/entities/order#order'>Order</a> as a whole.

*Example*

```ts
// Applies a percentage discount to the entire Order
const orderPercentageDiscount = new PromotionOrderAction({
    code: 'order_percentage_discount',
    args: { discount: 'percentage' },
    execute(ctx, order, args) {
        return -order.subTotal * (args.discount / 100);
    },
    description: 'Discount order by { discount }%',
});
```

```ts title="Signature"
class PromotionOrderAction<T extends ConfigArgs = ConfigArgs, U extends PromotionCondition[] = []> extends PromotionAction<T, U> {
    constructor(config: PromotionOrderActionConfig<T, U>)
}
```
* Extends: <code><a href='/reference/typescript-api/promotions/promotion-action#promotionaction'>PromotionAction</a>&#60;T, U&#62;</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(config: <a href='/reference/typescript-api/promotions/promotion-action#promotionorderactionconfig'>PromotionOrderActionConfig</a>&#60;T, U&#62;) => PromotionOrderAction`}   />




</div>


## PromotionShippingAction

<GenerationInfo sourceFile="packages/core/src/config/promotion/promotion-action.ts" sourceLine="506" packageName="@vendure/core" />

Represents a PromotionAction which applies to the shipping cost of an Order.

```ts title="Signature"
class PromotionShippingAction<T extends ConfigArgs = ConfigArgs, U extends PromotionCondition[] = []> extends PromotionAction<T, U> {
    constructor(config: PromotionShippingActionConfig<T, U>)
}
```
* Extends: <code><a href='/reference/typescript-api/promotions/promotion-action#promotionaction'>PromotionAction</a>&#60;T, U&#62;</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(config: <a href='/reference/typescript-api/promotions/promotion-action#promotionshippingactionconfig'>PromotionShippingActionConfig</a>&#60;T, U&#62;) => PromotionShippingAction`}   />




</div>


## ExecutePromotionItemActionFn

<GenerationInfo sourceFile="packages/core/src/config/promotion/promotion-action.ts" sourceLine="72" packageName="@vendure/core" />

The function which is used by a PromotionItemAction to calculate the
discount on the OrderLine for each item.

```ts title="Signature"
type ExecutePromotionItemActionFn<T extends ConfigArgs, U extends Array<PromotionCondition<any>>> = (
    ctx: RequestContext,
    orderLine: OrderLine,
    args: ConfigArgValues<T>,
    state: ConditionState<U>,
    promotion: Promotion,
) => number | Promise<number>
```


## ExecutePromotionLineActionFn

<GenerationInfo sourceFile="packages/core/src/config/promotion/promotion-action.ts" sourceLine="88" packageName="@vendure/core" />

The function which is used by a PromotionLineAction to calculate the
discount on the OrderLine.

```ts title="Signature"
type ExecutePromotionLineActionFn<T extends ConfigArgs, U extends Array<PromotionCondition<any>>> = (
    ctx: RequestContext,
    orderLine: OrderLine,
    args: ConfigArgValues<T>,
    state: ConditionState<U>,
    promotion: Promotion,
) => number | Promise<number>
```


## ExecutePromotionOrderActionFn

<GenerationInfo sourceFile="packages/core/src/config/promotion/promotion-action.ts" sourceLine="104" packageName="@vendure/core" />

The function which is used by a PromotionOrderAction to calculate the
discount on the Order.

```ts title="Signature"
type ExecutePromotionOrderActionFn<T extends ConfigArgs, U extends Array<PromotionCondition<any>>> = (
    ctx: RequestContext,
    order: Order,
    args: ConfigArgValues<T>,
    state: ConditionState<U>,
    promotion: Promotion,
) => number | Promise<number>
```


## ExecutePromotionShippingActionFn

<GenerationInfo sourceFile="packages/core/src/config/promotion/promotion-action.ts" sourceLine="120" packageName="@vendure/core" />

The function which is used by a PromotionOrderAction to calculate the
discount on the Order.

```ts title="Signature"
type ExecutePromotionShippingActionFn<T extends ConfigArgs, U extends Array<PromotionCondition<any>>> = (
    ctx: RequestContext,
    shippingLine: ShippingLine,
    order: Order,
    args: ConfigArgValues<T>,
    state: ConditionState<U>,
    promotion: Promotion,
) => number | Promise<number>
```


## PromotionActionSideEffectFn

<GenerationInfo sourceFile="packages/core/src/config/promotion/promotion-action.ts" sourceLine="141" packageName="@vendure/core" since="1.8.0" experimental="true" />

The signature of a PromotionAction's side-effect functions `onActivate` and `onDeactivate`.

```ts title="Signature"
type PromotionActionSideEffectFn<T extends ConfigArgs> = (
    ctx: RequestContext,
    order: Order,
    args: ConfigArgValues<T>,
    promotion: Promotion,
) => void | Promise<void>
```


## PromotionActionConfig

<GenerationInfo sourceFile="packages/core/src/config/promotion/promotion-action.ts" sourceLine="155" packageName="@vendure/core" />

Configuration for all types of <a href='/reference/typescript-api/promotions/promotion-action#promotionaction'>PromotionAction</a>.

```ts title="Signature"
interface PromotionActionConfig<T extends ConfigArgs, U extends Array<PromotionCondition<any>> | undefined> extends ConfigurableOperationDefOptions<T> {
    priorityValue?: number;
    conditions?: U extends undefined ? undefined : ConditionTuple<Exclude<U, undefined>>;
    onActivate?: PromotionActionSideEffectFn<T>;
    onDeactivate?: PromotionActionSideEffectFn<T>;
}
```
* Extends: <code><a href='/reference/typescript-api/configurable-operation-def/configurable-operation-def-options#configurableoperationdefoptions'>ConfigurableOperationDefOptions</a>&#60;T&#62;</code>



<div className="members-wrapper">

### priorityValue

<MemberInfo kind="property" type={`number`} default={`0`}   />

Used to determine the order of application of multiple Promotions
on the same Order. See the <a href='/reference/typescript-api/entities/promotion#promotion'>Promotion</a> `priorityScore` field for
more information.
### conditions

<MemberInfo kind="property" type={`U extends undefined ? undefined : ConditionTuple&#60;Exclude&#60;U, undefined&#62;&#62;`}   />

Allows PromotionActions to define one or more PromotionConditions as dependencies. Having a PromotionCondition
as a dependency has the following consequences:
1. A Promotion using this PromotionAction is only valid if it also contains all PromotionConditions
on which it depends.
2. The `execute()` function will receive a statically-typed `state` argument which will contain
the return values of the PromotionConditions' `check()` function.
### onActivate

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/promotions/promotion-action#promotionactionsideeffectfn'>PromotionActionSideEffectFn</a>&#60;T&#62;`}  since="1.8.0" experimental="true" />

An optional side effect function which is invoked when the promotion
becomes active. It can be used for things like adding a free gift to the order
or other side effects that are unrelated to price calculations.

If used, make sure to use the corresponding `onDeactivate` function to clean up
or reverse any side effects as needed.
### onDeactivate

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/promotions/promotion-action#promotionactionsideeffectfn'>PromotionActionSideEffectFn</a>&#60;T&#62;`}  since="1.8.0" experimental="true" />

Used to reverse or clean up any side effects executed as part of the `onActivate` function.


</div>


## PromotionItemActionConfig

<GenerationInfo sourceFile="packages/core/src/config/promotion/promotion-action.ts" sourceLine="209" packageName="@vendure/core" />

Configuration for a <a href='/reference/typescript-api/promotions/promotion-action#promotionitemaction'>PromotionItemAction</a>

```ts title="Signature"
interface PromotionItemActionConfig<T extends ConfigArgs, U extends PromotionCondition[]> extends PromotionActionConfig<T, U> {
    execute: ExecutePromotionItemActionFn<T, U>;
}
```
* Extends: <code><a href='/reference/typescript-api/promotions/promotion-action#promotionactionconfig'>PromotionActionConfig</a>&#60;T, U&#62;</code>



<div className="members-wrapper">

### execute

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/promotions/promotion-action#executepromotionitemactionfn'>ExecutePromotionItemActionFn</a>&#60;T, U&#62;`}   />

The function which contains the promotion calculation logic.
Should resolve to a number which represents the amount by which to discount
the OrderLine, i.e. the number should be negative.


</div>


## PromotionLineActionConfig

<GenerationInfo sourceFile="packages/core/src/config/promotion/promotion-action.ts" sourceLine="227" packageName="@vendure/core" />

Configuration for a <a href='/reference/typescript-api/promotions/promotion-action#promotionlineaction'>PromotionLineAction</a>

```ts title="Signature"
interface PromotionLineActionConfig<T extends ConfigArgs, U extends PromotionCondition[]> extends PromotionActionConfig<T, U> {
    execute: ExecutePromotionLineActionFn<T, U>;
}
```
* Extends: <code><a href='/reference/typescript-api/promotions/promotion-action#promotionactionconfig'>PromotionActionConfig</a>&#60;T, U&#62;</code>



<div className="members-wrapper">

### execute

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/promotions/promotion-action#executepromotionlineactionfn'>ExecutePromotionLineActionFn</a>&#60;T, U&#62;`}   />

The function which contains the promotion calculation logic.
Should resolve to a number which represents the amount by which to discount
the OrderLine, i.e. the number should be negative.


</div>


## PromotionOrderActionConfig

<GenerationInfo sourceFile="packages/core/src/config/promotion/promotion-action.ts" sourceLine="244" packageName="@vendure/core" />



```ts title="Signature"
interface PromotionOrderActionConfig<T extends ConfigArgs, U extends PromotionCondition[]> extends PromotionActionConfig<T, U> {
    execute: ExecutePromotionOrderActionFn<T, U>;
}
```
* Extends: <code><a href='/reference/typescript-api/promotions/promotion-action#promotionactionconfig'>PromotionActionConfig</a>&#60;T, U&#62;</code>



<div className="members-wrapper">

### execute

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/promotions/promotion-action#executepromotionorderactionfn'>ExecutePromotionOrderActionFn</a>&#60;T, U&#62;`}   />

The function which contains the promotion calculation logic.
Should resolve to a number which represents the amount by which to discount
the Order, i.e. the number should be negative.


</div>


## PromotionShippingActionConfig

<GenerationInfo sourceFile="packages/core/src/config/promotion/promotion-action.ts" sourceLine="261" packageName="@vendure/core" />



```ts title="Signature"
interface PromotionShippingActionConfig<T extends ConfigArgs, U extends PromotionCondition[]> extends PromotionActionConfig<T, U> {
    execute: ExecutePromotionShippingActionFn<T, U>;
}
```
* Extends: <code><a href='/reference/typescript-api/promotions/promotion-action#promotionactionconfig'>PromotionActionConfig</a>&#60;T, U&#62;</code>



<div className="members-wrapper">

### execute

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/promotions/promotion-action#executepromotionshippingactionfn'>ExecutePromotionShippingActionFn</a>&#60;T, U&#62;`}   />

The function which contains the promotion calculation logic.
Should resolve to a number which represents the amount by which to discount
the Shipping, i.e. the number should be negative.


</div>


## PromotionLineAction

<GenerationInfo sourceFile="packages/core/src/config/promotion/promotion-action.ts" sourceLine="409" packageName="@vendure/core" />

Represents a PromotionAction which applies to individual <a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a>s.
The difference from PromotionItemAction is that it applies regardless of the Quantity of the OrderLine.

*Example*

```ts
// Applies a percentage discount to each OrderLine
const linePercentageDiscount = new PromotionLineAction({
    code: 'line_percentage_discount',
    args: { discount: 'percentage' },
    execute(ctx, orderLine, args) {
        return -orderLine.linePrice * (args.discount / 100);
    },
    description: 'Discount every line by { discount }%',
});
```

```ts title="Signature"
class PromotionLineAction<T extends ConfigArgs = ConfigArgs, U extends Array<PromotionCondition<any>> = []> extends PromotionAction<T, U> {
    constructor(config: PromotionLineActionConfig<T, U>)
}
```
* Extends: <code><a href='/reference/typescript-api/promotions/promotion-action#promotionaction'>PromotionAction</a>&#60;T, U&#62;</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(config: <a href='/reference/typescript-api/promotions/promotion-action#promotionlineactionconfig'>PromotionLineActionConfig</a>&#60;T, U&#62;) => PromotionLineAction`}   />




</div>


---

---
title: "Promotion Condition"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## PromotionCondition

<GenerationInfo sourceFile="packages/core/src/config/promotion/promotion-condition.ts" sourceLine="66" packageName="@vendure/core" />

PromotionConditions are used to create <a href='/reference/typescript-api/entities/promotion#promotion'>Promotion</a>s. The purpose of a PromotionCondition
is to check the order against a particular predicate function (the `check` function) and to return
`true` if the Order satisfies the condition, or `false` if it does not.

```ts title="Signature"
class PromotionCondition<T extends ConfigArgs = ConfigArgs, C extends string = string, R extends CheckPromotionConditionResult = any> extends ConfigurableOperationDef<T> {
    readonly priorityValue: number;
    code: C
    constructor(config: PromotionConditionConfig<T, C, R>)
    check(ctx: RequestContext, order: Order, args: ConfigArg[], promotion: Promotion) => Promise<R>;
}
```
* Extends: <code><a href='/reference/typescript-api/configurable-operation-def/#configurableoperationdef'>ConfigurableOperationDef</a>&#60;T&#62;</code>



<div className="members-wrapper">

### priorityValue

<MemberInfo kind="property" type={`number`} default={`0`}   />

Used to determine the order of application of multiple Promotions
on the same Order. See the <a href='/reference/typescript-api/entities/promotion#promotion'>Promotion</a> `priorityScore` field for
more information.
### code

<MemberInfo kind="property" type={`C`}   />


### constructor

<MemberInfo kind="method" type={`(config: <a href='/reference/typescript-api/promotions/promotion-condition#promotionconditionconfig'>PromotionConditionConfig</a>&#60;T, C, R&#62;) => PromotionCondition`}   />


### check

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>, args: ConfigArg[], promotion: <a href='/reference/typescript-api/entities/promotion#promotion'>Promotion</a>) => Promise&#60;R&#62;`}   />

This is the function which contains the conditional logic to decide whether
a Promotion should apply to an Order. See <a href='/reference/typescript-api/promotions/promotion-condition#checkpromotionconditionfn'>CheckPromotionConditionFn</a>.


</div>


## PromotionConditionConfig

<GenerationInfo sourceFile="packages/core/src/config/promotion/promotion-condition.ts" sourceLine="46" packageName="@vendure/core" />

This object is used to configure a PromotionCondition.

```ts title="Signature"
interface PromotionConditionConfig<T extends ConfigArgs, C extends string, R extends CheckPromotionConditionResult> extends ConfigurableOperationDefOptions<T> {
    code: C;
    check: CheckPromotionConditionFn<T, R>;
    priorityValue?: number;
}
```
* Extends: <code><a href='/reference/typescript-api/configurable-operation-def/configurable-operation-def-options#configurableoperationdefoptions'>ConfigurableOperationDefOptions</a>&#60;T&#62;</code>



<div className="members-wrapper">

### code

<MemberInfo kind="property" type={`C`}   />


### check

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/promotions/promotion-condition#checkpromotionconditionfn'>CheckPromotionConditionFn</a>&#60;T, R&#62;`}   />


### priorityValue

<MemberInfo kind="property" type={`number`}   />




</div>


## CheckPromotionConditionFn

<GenerationInfo sourceFile="packages/core/src/config/promotion/promotion-condition.ts" sourceLine="31" packageName="@vendure/core" />

A function which checks whether or not a given <a href='/reference/typescript-api/entities/order#order'>Order</a> satisfies the <a href='/reference/typescript-api/promotions/promotion-condition#promotioncondition'>PromotionCondition</a>.

The function should return either a `boolean` or and plain object type:

* `false`: The condition is not satisfied - do not apply PromotionActions
* `true`: The condition is satisfied, apply PromotionActions
* `{ [key: string]: any; }`: The condition is satisfied, apply PromotionActions
_and_ pass this object into the PromotionAction's `state` argument.

```ts title="Signature"
type CheckPromotionConditionFn<T extends ConfigArgs, R extends CheckPromotionConditionResult> = (
    ctx: RequestContext,
    order: Order,
    args: ConfigArgValues<T>,
    promotion: Promotion,
) => R | Promise<R>
```


---

---
title: "PromotionOptions"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## PromotionOptions

<GenerationInfo sourceFile="packages/core/src/config/vendure-config.ts" sourceLine="783" packageName="@vendure/core" />



```ts title="Signature"
interface PromotionOptions {
    promotionConditions?: Array<PromotionCondition<any>>;
    promotionActions?: Array<PromotionAction<any>>;
}
```

<div className="members-wrapper">

### promotionConditions

<MemberInfo kind="property" type={`Array&#60;<a href='/reference/typescript-api/promotions/promotion-condition#promotioncondition'>PromotionCondition</a>&#60;any&#62;&#62;`}   />

An array of conditions which can be used to construct Promotions
### promotionActions

<MemberInfo kind="property" type={`Array&#60;<a href='/reference/typescript-api/promotions/promotion-action#promotionaction'>PromotionAction</a>&#60;any&#62;&#62;`}   />

An array of actions which can be used to construct Promotions


</div>


---

---
title: "Allow Decorator"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## Allow

<GenerationInfo sourceFile="packages/core/src/api/decorators/allow.decorator.ts" sourceLine="38" packageName="@vendure/core" />

Attaches metadata to the resolver defining which permissions are required to execute the
operation, using one or more <a href='/reference/typescript-api/common/permission#permission'>Permission</a> values.

In a GraphQL context, it can be applied to top-level queries and mutations as well as field resolvers.

For REST controllers, it can be applied to route handler.

## Allow and Sessions
The `@Allow()` decorator is closely linked to the way Vendure manages sessions. For any operation or route that is decorated
with `@Allow()`, there must be an authenticated session in progress, which would have been created during a prior authentication
step.

The exception to this is when the operation is decorated with `@Allow(Permission.Owner)`. This is a special permission which is designed
to give access to certain resources to potentially un-authenticated users. For this reason, any operation decorated with this permission
will always have an anonymous session created if no session is currently in progress.

For more information see [Understanding Permission.Owner](/reference/typescript-api/common/permission/#understanding-permissionowner).

*Example*

```ts
 @Allow(Permission.SuperAdmin)
 @Query()
 getAdministrators() {
     // ...
 }
```



---

---
title: "Api Decorator"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## Api

<GenerationInfo sourceFile="packages/core/src/api/decorators/api.decorator.ts" sourceLine="26" packageName="@vendure/core" />

Resolver param decorator which returns which Api the request came though.
This is useful because sometimes the same resolver will have different behaviour
depending whether it is being called from the shop API or the admin API.

Returns a string of type <a href='/reference/typescript-api/request/api-type#apitype'>ApiType</a>.

*Example*

```ts
 @Query()
 getAdministrators(@Api() apiType: ApiType) {
   if (apiType === 'admin') {
     // ...
   }
 }
```



---

---
title: "ApiType"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ApiType

<GenerationInfo sourceFile="packages/core/src/api/common/get-api-type.ts" sourceLine="9" packageName="@vendure/core" />

Which of the GraphQL APIs the current request came via.

```ts title="Signature"
type ApiType = 'admin' | 'shop' | 'custom'
```


---

---
title: "Ctx Decorator"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## Ctx

<GenerationInfo sourceFile="packages/core/src/api/decorators/request-context.decorator.ts" sourceLine="23" packageName="@vendure/core" />

Resolver param decorator which extracts the <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a> from the incoming
request object.

*Example*

```ts
 @Query()
 getAdministrators(@Ctx() ctx: RequestContext) {
     // ...
 }
```



---

---
title: "Request"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "Relations Decorator"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## Relations

<GenerationInfo sourceFile="packages/core/src/api/decorators/relations.decorator.ts" sourceLine="136" packageName="@vendure/core" since="1.6.0" />

Resolver param decorator which returns an array of relation paths which can be passed through
to the TypeORM data layer in order to join only the required relations. This works by inspecting
the GraphQL `info` object, examining the field selection, and then comparing this with information
about the return type's relations.

In addition to analyzing the field selection, this decorator also checks for any `@Calculated()`
properties on the entity, and additionally includes relations from the `relations` array of the calculated
metadata, if defined.

So if, for example, the query only selects the `id` field of an Order, then no other relations need
be joined in the resulting SQL query. This can massively speed up execution time for queries which do
not include many deep nested relations.

*Example*

```ts
@Query()
@Allow(Permission.ReadOrder)
orders(
    @Ctx() ctx: RequestContext,
    @Args() args: QueryOrdersArgs,
    @Relations(Order) relations: RelationPaths<Order>,
): Promise<PaginatedList<Order>> {
    return this.orderService.findAll(ctx, args.options || undefined, relations);
}
```

In the above example, given the following query:

*Example*

```GraphQL
{
  orders(options: { take: 10 }) {
    items {
      id
      customer {
        id
        firstName
        lastName
      }
      totalQuantity
      totalWithTax
    }
  }
}
```
then the value of `relations` will be

```
['customer', 'lines'']
```
The `'customer'` comes from the fact that the query is nesting the "customer" object, and the `'lines'` is taken
from the `Order` entity's `totalQuantity` property, which uses <a href='/reference/typescript-api/data-access/calculated#calculated'>Calculated</a> decorator and defines those relations as dependencies
for deriving the calculated value.

## Depth

By default, when inspecting the GraphQL query, the Relations decorator will look 3 levels deep in any nested fields. So, e.g. if
the above `orders` query were changed to:

*Example*

```GraphQL
{
  orders(options: { take: 10 }) {
    items {
      id
      lines {
        productVariant {
          product {
            featuredAsset {
              preview
            }
          }
        }
      }
    }
  }
}
```
then the `relations` array would include `'lines'`, `'lines.productVariant'`, & `'lines.productVariant.product'` - 3 levels deep - but it would
_not_ include `'lines.productVariant.product.featuredAsset'` since that exceeds the default depth. To specify a custom depth, you would
use the decorator like this:

*Example*

```ts
@Relations({ entity: Order, depth: 2 }) relations: RelationPaths<Order>,
```

## Omit

The `omit` option is used to explicitly omit certain relations from the calculated relations array. This is useful in certain
cases where we know for sure that we need to run the field resolver _anyway_. A good example is the `Collection.productVariants` relation.
When a GraphQL query comes in for a Collection and also requests its `productVariants` field, there is no point using a lookahead to eagerly
join that relation, because we will throw that data away anyway when the `productVariants` field resolver executes, since it returns a
PaginatedList query rather than a simple array.

*Example*

```ts
@Relations({ entity: Collection, omit: ['productVariant'] }) relations: RelationPaths<Collection>,
```



---

---
title: "RequestContextService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## RequestContextService

<GenerationInfo sourceFile="packages/core/src/service/helpers/request-context/request-context.service.ts" sourceLine="25" packageName="@vendure/core" />

Creates new <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a> instances.

```ts title="Signature"
class RequestContextService {
    create(config: {
        req?: Request;
        apiType: ApiType;
        channelOrToken?: Channel | string;
        languageCode?: LanguageCode;
        currencyCode?: CurrencyCode;
        user?: User;
        activeOrderId?: ID;
    }) => Promise<RequestContext>;
    fromRequest(req: Request, info?: GraphQLResolveInfo, requiredPermissions?: Permission[], session?: CachedSession) => Promise<RequestContext>;
}
```

<div className="members-wrapper">

### create

<MemberInfo kind="method" type={`(config: {         req?: Request;         apiType: <a href='/reference/typescript-api/request/api-type#apitype'>ApiType</a>;         channelOrToken?: <a href='/reference/typescript-api/entities/channel#channel'>Channel</a> | string;         languageCode?: <a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a>;         currencyCode?: <a href='/reference/typescript-api/common/currency-code#currencycode'>CurrencyCode</a>;         user?: <a href='/reference/typescript-api/entities/user#user'>User</a>;         activeOrderId?: <a href='/reference/typescript-api/common/id#id'>ID</a>;     }) => Promise&#60;<a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>&#62;`}  since="1.5.0"  />

Creates a RequestContext based on the config provided. This can be useful when interacting
with services outside the request-response cycle, for example in stand-alone scripts or in
worker jobs.
### fromRequest

<MemberInfo kind="method" type={`(req: Request, info?: GraphQLResolveInfo, requiredPermissions?: <a href='/reference/typescript-api/common/permission#permission'>Permission</a>[], session?: <a href='/reference/typescript-api/auth/session-cache-strategy#cachedsession'>CachedSession</a>) => Promise&#60;<a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>&#62;`}   />

Creates a new RequestContext based on an Express request object. This is used internally
in the API layer by the AuthGuard, and creates the RequestContext which is then passed
to all resolvers & controllers.


</div>


---

---
title: "RequestContext"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## RequestContext

<GenerationInfo sourceFile="packages/core/src/api/common/request-context.ts" sourceLine="179" packageName="@vendure/core" />

The RequestContext holds information relevant to the current request, which may be
required at various points of the stack.

It is a good practice to inject the RequestContext (using the <a href='/reference/typescript-api/request/ctx-decorator#ctx'>Ctx</a> decorator) into
_all_ resolvers & REST handler, and then pass it through to the service layer.

This allows the service layer to access information about the current user, the active language,
the active Channel, and so on. In addition, the <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a> relies on the
presence of the RequestContext object in order to correctly handle per-request database transactions.

The RequestContext also provides mechanisms for managing the database replication mode via the
`setReplicationMode` method and the `replicationMode` getter. This allows for finer control
over whether database queries within the context should be executed against the master or a replica
database, which can be particularly useful in distributed database environments.

*Example*

```ts
@Query()
myQuery(@Ctx() ctx: RequestContext) {
  return this.myService.getData(ctx);
}
```

*Example*

```ts
@Query()
myMutation(@Ctx() ctx: RequestContext) {
  ctx.setReplicationMode('master');
  return this.myService.getData(ctx);
}
```

```ts title="Signature"
class RequestContext {
    empty() => RequestContext;
    deserialize(ctxObject: SerializedRequestContext) => RequestContext;
    userHasPermissions(permissions: Permission[]) => boolean;
    serialize() => SerializedRequestContext;
    copy() => RequestContext;
    req: Request | undefined
    apiType: ApiType
    channel: Channel
    channelId: ID
    languageCode: LanguageCode
    currencyCode: CurrencyCode
    session: CachedSession | undefined
    activeUserId: ID | undefined
    isAuthorized: boolean
    authorizedAsOwnerOnly: boolean
    translate(key: string, variables?: { [k: string]: any }) => string;
    setReplicationMode(mode: ReplicationMode) => void;
    replicationMode: ReplicationMode | undefined
}
```

<div className="members-wrapper">

### empty

<MemberInfo kind="method" type={`() => <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>`}   />

Creates an "empty" RequestContext object. This is only intended to be used
when a service method must be called outside the normal request-response
cycle, e.g. when programmatically populating data. Usually a better alternative
is to use the <a href='/reference/typescript-api/request/request-context-service#requestcontextservice'>RequestContextService</a> `create()` method, which allows more control
over the resulting RequestContext object.
### deserialize

<MemberInfo kind="method" type={`(ctxObject: SerializedRequestContext) => <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>`}   />

Creates a new RequestContext object from a serialized object created by the
`serialize()` method.
### userHasPermissions

<MemberInfo kind="method" type={`(permissions: <a href='/reference/typescript-api/common/permission#permission'>Permission</a>[]) => boolean`}   />

Returns `true` if there is an active Session & User associated with this request,
and that User has the specified permissions on the active Channel.
### serialize

<MemberInfo kind="method" type={`() => SerializedRequestContext`}   />

Serializes the RequestContext object into a JSON-compatible simple object.
This is useful when you need to send a RequestContext object to another
process, e.g. to pass it to the Job Queue via the <a href='/reference/typescript-api/job-queue/job-queue-service#jobqueueservice'>JobQueueService</a>.
### copy

<MemberInfo kind="method" type={`() => <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>`}   />

Creates a shallow copy of the RequestContext instance. This means that
mutations to the copy itself will not affect the original, but deep mutations
(e.g. copy.channel.code = 'new') *will* also affect the original.
### req

<MemberInfo kind="property" type={`Request | undefined`}   />

The raw Express request object.
### apiType

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/request/api-type#apitype'>ApiType</a>`}   />

Signals which API this request was received by, e.g. `admin` or `shop`.
### channel

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/channel#channel'>Channel</a>`}   />

The active <a href='/reference/typescript-api/entities/channel#channel'>Channel</a> of this request.
### channelId

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a>`}   />


### languageCode

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a>`}   />


### currencyCode

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/currency-code#currencycode'>CurrencyCode</a>`}   />


### session

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/auth/session-cache-strategy#cachedsession'>CachedSession</a> | undefined`}   />


### activeUserId

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a> | undefined`}   />


### isAuthorized

<MemberInfo kind="property" type={`boolean`}   />

True if the current session is authorized to access the current resolver method.
### authorizedAsOwnerOnly

<MemberInfo kind="property" type={`boolean`}   />

True if the current anonymous session is only authorized to operate on entities that
are owned by the current session.
### translate

<MemberInfo kind="method" type={`(key: string, variables?: { [k: string]: any }) => string`}   />

Translate the given i18n key
### setReplicationMode

<MemberInfo kind="method" type={`(mode: ReplicationMode) => void`}   />

Sets the replication mode for the current RequestContext. This mode determines whether the operations
within this context should interact with the master database or a replica. Use this method to explicitly
define the replication mode for the context.
### replicationMode

<MemberInfo kind="property" type={`ReplicationMode | undefined`}   />

Gets the current replication mode of the RequestContext. If no replication mode has been set,
it returns `undefined`. This property indicates whether the context is configured to interact with
the master database or a replica.


</div>


---

---
title: "Transaction Decorator"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## Transaction

<GenerationInfo sourceFile="packages/core/src/api/decorators/transaction.decorator.ts" sourceLine="81" packageName="@vendure/core" />

Runs the decorated method in a TypeORM transaction. It works by creating a transactional
QueryRunner which gets attached to the RequestContext object. When the RequestContext
is the passed to the <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a> `getRepository()` method, this
QueryRunner is used to execute the queries within this transaction.

Essentially, the entire resolver function is wrapped in a try-catch block which commits the
transaction on successful completion of the method, or rolls back the transaction in an unhandled
error is thrown.

*Example*

```ts
// in a GraphQL resolver file

@Transaction()
async myMutation(@Ctx() ctx: RequestContext) {
  // as long as the `ctx` object is passed in to
  // all database operations, the entire mutation
  // will be run as an atomic transaction, and rolled
  // back if an error is thrown.
  const result = this.myService.createThing(ctx);
  return this.myService.updateOtherThing(ctx, result.id);
}
```



## TransactionMode

<GenerationInfo sourceFile="packages/core/src/api/decorators/transaction.decorator.ts" sourceLine="32" packageName="@vendure/core" />

The Transaction decorator can handle transactions automatically (which is the default) or be set to
"manual" mode, where the <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a> `.startTransaction()` and `.commitOpenTransaction()`
methods must them be used.

*Example*

```ts
// in a GraphQL resolver file

@Transaction('manual')
async myMutation(@Ctx() ctx: RequestContext) {
  await this.connection.startTransaction(ctx);
  const result = this.myService.createThing(ctx);
  const thing = this.myService.updateOtherThing(ctx, result.id);
  await this.connection.commitOpenTransaction(ctx);
  return thing;
}
```
Note that even in manual mode, a rollback will be automatically performed in
the case that an uncaught error is thrown within the resolver.

```ts title="Signature"
type TransactionMode = 'auto' | 'manual'
```


## TransactionIsolationLevel

<GenerationInfo sourceFile="packages/core/src/api/decorators/transaction.decorator.ts" sourceLine="45" packageName="@vendure/core" />

Transactions can be run at different isolation levels. The default is undefined, which
falls back to the default of your database. See the documentation of your database for more
information on available isolation levels.

```ts title="Signature"
type TransactionIsolationLevel = | 'READ UNCOMMITTED'
    | 'READ COMMITTED'
    | 'REPEATABLE READ'
    | 'SERIALIZABLE'
```


---

---
title: "CleanSessionsTask"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## cleanSessionsTask

<GenerationInfo sourceFile="packages/core/src/scheduler/tasks/clean-sessions-task.ts" sourceLine="37" packageName="@vendure/core" since="3.3.0" />

A <a href='/reference/typescript-api/scheduled-tasks/scheduled-task#scheduledtask'>ScheduledTask</a> that cleans expired & inactive sessions from the database.

*Example*

```ts
import { cleanSessionsTask, VendureConfig } from '@vendure/core';

export const config: VendureConfig = {
  // ...
  schedulerOptions: {
    tasks: [
      // Use the task as is
      cleanSessionsTask,
      // or configure the task
      cleanSessionsTask.configure({
        // Run the task every day at 3:00am
        // The default schedule is every day at 00:00am
        schedule: cron => cron.everyDayAt(3, 0),
        params: {
          // How many sessions to process in each batch
          // Default: 1000
          batchSize: 5_000,
        },
      }),
    ],
  },
};
```



---

---
title: "DefaultSchedulerPlugin"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DefaultSchedulerPlugin

<GenerationInfo sourceFile="packages/core/src/plugin/default-scheduler-plugin/default-scheduler.plugin.ts" sourceLine="39" packageName="@vendure/core" since="3.3.0" />

This plugin configures a default scheduling strategy that executes scheduled
tasks using the database to ensure that each task is executed exactly once
at the scheduled time, even if there are multiple instances of the worker
running.

*Example*

```ts
import { DefaultSchedulerPlugin, VendureConfig } from '@vendure/core';

export const config: VendureConfig = {
  plugins: [
    DefaultSchedulerPlugin.init({
      // The default is 60s, but you can override it here
      defaultTimeout: '10s',
    }),
  ],
};
```

```ts title="Signature"
class DefaultSchedulerPlugin {
    static options: DefaultSchedulerPluginOptions = {
        defaultTimeout: DEFAULT_TIMEOUT,
        manualTriggerCheckInterval: DEFAULT_MANUAL_TRIGGER_CHECK_INTERVAL,
    };
    init(config?: DefaultSchedulerPluginOptions) => ;
}
```

<div className="members-wrapper">

### options

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/scheduled-tasks/default-scheduler-plugin#defaultschedulerpluginoptions'>DefaultSchedulerPluginOptions</a>`}   />


### init

<MemberInfo kind="method" type={`(config?: <a href='/reference/typescript-api/scheduled-tasks/default-scheduler-plugin#defaultschedulerpluginoptions'>DefaultSchedulerPluginOptions</a>) => `}   />




</div>


## DefaultSchedulerPluginOptions

<GenerationInfo sourceFile="packages/core/src/plugin/default-scheduler-plugin/types.ts" sourceLine="9" packageName="@vendure/core" since="3.3.0" />

The options for the <a href='/reference/typescript-api/scheduled-tasks/default-scheduler-plugin#defaultschedulerplugin'>DefaultSchedulerPlugin</a>.

```ts title="Signature"
interface DefaultSchedulerPluginOptions {
    defaultTimeout?: string | number;
    manualTriggerCheckInterval?: string | number;
}
```

<div className="members-wrapper">

### defaultTimeout

<MemberInfo kind="property" type={`string | number`} default={`60_000ms`}   />

The default timeout for scheduled tasks.
### manualTriggerCheckInterval

<MemberInfo kind="property" type={`string | number`} default={`10_000ms`}   />

The interval at which the plugin will check for manually triggered tasks.


</div>


---

---
title: "DefaultSchedulerStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DefaultSchedulerStrategy

<GenerationInfo sourceFile="packages/core/src/plugin/default-scheduler-plugin/default-scheduler-strategy.ts" sourceLine="27" packageName="@vendure/core" since="3.3.0" />

The default <a href='/reference/typescript-api/scheduled-tasks/scheduler-strategy#schedulerstrategy'>SchedulerStrategy</a> implementation that uses the database to
execute scheduled tasks. This strategy is configured when you use the
<a href='/reference/typescript-api/scheduled-tasks/default-scheduler-plugin#defaultschedulerplugin'>DefaultSchedulerPlugin</a>.

```ts title="Signature"
class DefaultSchedulerStrategy implements SchedulerStrategy {
    init(injector: Injector) => ;
    destroy() => ;
    registerTask(task: ScheduledTask) => void;
    executeTask(task: ScheduledTask) => ;
    getTasks() => Promise<TaskReport[]>;
    getTask(id: string) => Promise<TaskReport | undefined>;
    updateTask(input: UpdateScheduledTaskInput) => Promise<TaskReport>;
    triggerTask(task: ScheduledTask) => Promise<void>;
}
```
* Implements: <code><a href='/reference/typescript-api/scheduled-tasks/scheduler-strategy#schedulerstrategy'>SchedulerStrategy</a></code>



<div className="members-wrapper">

### init

<MemberInfo kind="method" type={`(injector: <a href='/reference/typescript-api/common/injector#injector'>Injector</a>) => `}   />


### destroy

<MemberInfo kind="method" type={`() => `}   />


### registerTask

<MemberInfo kind="method" type={`(task: <a href='/reference/typescript-api/scheduled-tasks/scheduled-task#scheduledtask'>ScheduledTask</a>) => void`}   />


### executeTask

<MemberInfo kind="method" type={`(task: <a href='/reference/typescript-api/scheduled-tasks/scheduled-task#scheduledtask'>ScheduledTask</a>) => `}   />


### getTasks

<MemberInfo kind="method" type={`() => Promise&#60;<a href='/reference/typescript-api/scheduled-tasks/scheduler-strategy#taskreport'>TaskReport</a>[]&#62;`}   />


### getTask

<MemberInfo kind="method" type={`(id: string) => Promise&#60;<a href='/reference/typescript-api/scheduled-tasks/scheduler-strategy#taskreport'>TaskReport</a> | undefined&#62;`}   />


### updateTask

<MemberInfo kind="method" type={`(input: UpdateScheduledTaskInput) => Promise&#60;<a href='/reference/typescript-api/scheduled-tasks/scheduler-strategy#taskreport'>TaskReport</a>&#62;`}   />


### triggerTask

<MemberInfo kind="method" type={`(task: <a href='/reference/typescript-api/scheduled-tasks/scheduled-task#scheduledtask'>ScheduledTask</a>) => Promise&#60;void&#62;`}   />




</div>


---

---
title: "Scheduled Tasks"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "ScheduledTask"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ScheduledTask

<GenerationInfo sourceFile="packages/core/src/scheduler/scheduled-task.ts" sourceLine="120" packageName="@vendure/core" since="3.3.0" />

Use this class to define a scheduled task that will be executed at a given cron schedule.

*Example*

```ts
import { ScheduledTask } from '@vendure/core';

const task = new ScheduledTask({
    id: 'test-job',
    schedule: cron => cron.every(2).minutes(),
    execute: async ({ injector, scheduledContext, params }) => {
        // some logic here
    },
});
```

```ts title="Signature"
class ScheduledTask<C extends Record<string, any> = Record<string, any>> {
    constructor(config: ScheduledTaskConfig<C>)
    id: void
    options: void
    execute(injector: Injector) => ;
    configure(additionalConfig: Partial<Pick<ScheduledTaskConfig<C>, 'schedule' | 'timeout' | 'params'>>) => ;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(config: <a href='/reference/typescript-api/scheduled-tasks/scheduled-task#scheduledtaskconfig'>ScheduledTaskConfig</a>&#60;C&#62;) => ScheduledTask`}   />


### id

<MemberInfo kind="property" type={``}   />


### options

<MemberInfo kind="property" type={``}   />


### execute

<MemberInfo kind="method" type={`(injector: <a href='/reference/typescript-api/common/injector#injector'>Injector</a>) => `}   />


### configure

<MemberInfo kind="method" type={`(additionalConfig: Partial&#60;Pick&#60;<a href='/reference/typescript-api/scheduled-tasks/scheduled-task#scheduledtaskconfig'>ScheduledTaskConfig</a>&#60;C&#62;, 'schedule' | 'timeout' | 'params'&#62;&#62;) => `}   />

This method allows you to further configure existing scheduled tasks. For example, you may
wish to change the schedule or timeout of a task, without having to define a new task.

*Example*

```ts
import { ScheduledTask } from '@vendure/core';

const task = new ScheduledTask({
    id: 'test-job',
    schedule: cron => cron.every(2).minutes(),
    execute: async ({ injector, scheduledContext, params }) => {
        // some logic here
    },
});

// later, you can configure the task
task.configure({ schedule: cron => cron.every(5).minutes() });
```


</div>


## ScheduledTaskExecutionArgs

<GenerationInfo sourceFile="packages/core/src/scheduler/scheduled-task.ts" sourceLine="16" packageName="@vendure/core" since="3.3.0" />

The arguments passed to the execute method of a scheduled task.

```ts title="Signature"
interface ScheduledTaskExecutionArgs<C extends Record<string, any> = Record<string, any>> {
    injector: Injector;
    scheduledContext: RequestContext;
    params: C;
}
```

<div className="members-wrapper">

### injector

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/injector#injector'>Injector</a>`}   />

The injector instance.
### scheduledContext

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>`}   />

A RequestContext instance that is configured for the scheduled task.
### params

<MemberInfo kind="property" type={`C`}   />

The parameters for the scheduled task.


</div>


## ScheduledTaskConfig

<GenerationInfo sourceFile="packages/core/src/scheduler/scheduled-task.ts" sourceLine="42" packageName="@vendure/core" since="3.3.0" />

The configuration for a scheduled task.

```ts title="Signature"
interface ScheduledTaskConfig<C extends Record<string, any> = Record<string, any>> {
    id: string;
    description?: string;
    params?: C;
    schedule: string | ((cronTime: typeof CronTime) => string);
    timeout?: number | string;
    preventOverlap?: boolean;
    execute(args: ScheduledTaskExecutionArgs<C>): Promise<any>;
}
```

<div className="members-wrapper">

### id

<MemberInfo kind="property" type={`string`}   />

The unique identifier for the scheduled task.
### description

<MemberInfo kind="property" type={`string`}   />

The description for the scheduled task.
### params

<MemberInfo kind="property" type={`C`}   />

Optional parameters that will be passed to the `execute` function.
### schedule

<MemberInfo kind="property" type={`string | ((cronTime: typeof CronTime) =&#62; string)`}   />

The cron schedule for the scheduled task. This can be a standard cron expression or
a function that returns a [cron-time-generator](https://www.npmjs.com/package/cron-time-generator)
expression.

*Example*

```ts
// Standard cron expression
{ schedule: '0 0-23/5 * * *', } // every 5 hours
{ schedule: '0 22 * * *', } // every day at 10:00 PM

// Cron-time-generator expression
{ schedule: cronTime => cronTime.every(2).minutes(), }
{ schedule: cronTime => cronTime.every(5).hours(), }
```
### timeout

<MemberInfo kind="property" type={`number | string`} default={`60_000ms`}   />

The timeout for the scheduled task. If the task takes longer than the timeout, the task
will be considered to have failed with a timeout error.
### preventOverlap

<MemberInfo kind="property" type={`boolean`} default={`true`}   />

Whether the scheduled task should be prevented from running if it is already running.
### execute

<MemberInfo kind="method" type={`(args: <a href='/reference/typescript-api/scheduled-tasks/scheduled-task#scheduledtaskexecutionargs'>ScheduledTaskExecutionArgs</a>&#60;C&#62;) => Promise&#60;any&#62;`}   />

The function that will be executed when the scheduled task is run.


</div>


---

---
title: "SchedulerOptions"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## SchedulerOptions

<GenerationInfo sourceFile="packages/core/src/config/vendure-config.ts" sourceLine="998" packageName="@vendure/core" since="3.3.0" />

Options related to scheduled tasks..

```ts title="Signature"
interface SchedulerOptions {
    schedulerStrategy?: SchedulerStrategy;
    tasks?: ScheduledTask[];
    runTasksInWorkerOnly?: boolean;
}
```

<div className="members-wrapper">

### schedulerStrategy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/scheduled-tasks/scheduler-strategy#schedulerstrategy'>SchedulerStrategy</a>`}   />

The strategy used to execute scheduled tasks. If you are using the
<a href='/reference/typescript-api/scheduled-tasks/default-scheduler-plugin#defaultschedulerplugin'>DefaultSchedulerPlugin</a> (which is recommended) then this will be set to the
<a href='/reference/typescript-api/scheduled-tasks/default-scheduler-strategy#defaultschedulerstrategy'>DefaultSchedulerStrategy</a>.
### tasks

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/scheduled-tasks/scheduled-task#scheduledtask'>ScheduledTask</a>[]`}   />

The tasks to be executed.
### runTasksInWorkerOnly

<MemberInfo kind="property" type={`boolean`} default={`true`}   />

Whether to run tasks only in the worker process. Generally this should
be left as true, since tasks may involve expensive operations that should
not be allowed to interfere with the server responsiveness.

This option mainly exists for testing purposes.


</div>


---

---
title: "SchedulerService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## SchedulerService

<GenerationInfo sourceFile="packages/core/src/scheduler/scheduler.service.ts" sourceLine="34" packageName="@vendure/core" since="3.3.0" />

The service that is responsible for setting up and querying the scheduled tasks.

```ts title="Signature"
class SchedulerService implements OnApplicationBootstrap, OnApplicationShutdown {
    constructor(configService: ConfigService, processContext: ProcessContext)
    onApplicationBootstrap() => ;
    onApplicationShutdown(signal?: string) => ;
    getTaskList() => Promise<TaskInfo[]>;
    updateTask(input: UpdateScheduledTaskInput) => Promise<TaskInfo>;
    runTask(taskId: string) => Promise<Success>;
}
```
* Implements: <code>OnApplicationBootstrap</code>, <code>OnApplicationShutdown</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(configService: ConfigService, processContext: <a href='/reference/typescript-api/common/process-context#processcontext'>ProcessContext</a>) => SchedulerService`}   />


### onApplicationBootstrap

<MemberInfo kind="method" type={`() => `}   />


### onApplicationShutdown

<MemberInfo kind="method" type={`(signal?: string) => `}   />


### getTaskList

<MemberInfo kind="method" type={`() => Promise&#60;TaskInfo[]&#62;`}   />

Returns a list of all the scheduled tasks and their current status.
### updateTask

<MemberInfo kind="method" type={`(input: UpdateScheduledTaskInput) => Promise&#60;TaskInfo&#62;`}   />


### runTask

<MemberInfo kind="method" type={`(taskId: string) => Promise&#60;Success&#62;`}   />




</div>


---

---
title: "SchedulerStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## SchedulerStrategy

<GenerationInfo sourceFile="packages/core/src/scheduler/scheduler-strategy.ts" sourceLine="42" packageName="@vendure/core" since="3.3.0" />

This strategy is used to define the mechanism by which scheduled tasks are executed
and how they are reported on. The main purpose of this strategy is to ensure
that a given task is executed exactly once at the scheduled time, even if there
are multiple instances of the worker running.

To do this, the strategy must use some form of shared storage and a method of
locking so that only a single worker is allowed to execute the task.

By default, the <a href='/reference/typescript-api/scheduled-tasks/default-scheduler-strategy#defaultschedulerstrategy'>DefaultSchedulerStrategy</a> will use the database to enable
this functionality.

```ts title="Signature"
interface SchedulerStrategy extends InjectableStrategy {
    registerTask?(task: ScheduledTask): void;
    executeTask(task: ScheduledTask): (job?: Cron) => Promise<any> | any;
    getTasks(): Promise<TaskReport[]>;
    getTask(id: string): Promise<TaskReport | undefined>;
    triggerTask(task: ScheduledTask): Promise<void>;
    updateTask(input: UpdateScheduledTaskInput): Promise<TaskReport>;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### registerTask

<MemberInfo kind="method" type={`(task: <a href='/reference/typescript-api/scheduled-tasks/scheduled-task#scheduledtask'>ScheduledTask</a>) => void`}   />

An optional method that may be used by the strategy to register all the configured
tasks ahead of time. This can be useful for keeping an internal reference of
all the tasks to aid in the specific strategy implemetation.
### executeTask

<MemberInfo kind="method" type={`(task: <a href='/reference/typescript-api/scheduled-tasks/scheduled-task#scheduledtask'>ScheduledTask</a>) => (job?: Cron) =&#62; Promise&#60;any&#62; | any`}   />

Execute a scheduled task. This method must also take care of
ensuring that the task is executed exactly once at the scheduled time,
even if there are multiple instances of the worker running.

For instance, in the <a href='/reference/typescript-api/scheduled-tasks/default-scheduler-strategy#defaultschedulerstrategy'>DefaultSchedulerStrategy</a> we make use of a
dedicated database table and a locking mechansim. If you implement a custom
SchedulerStrategy, you must use some other form of shared locking mechanism
that could make use of something like Redis etc. to ensure that the task
is executed exactly once at the scheduled time.

The function returned is then called in order to execture the task. The
`job` argument is an instance of the croner `Cron` class, except when
the task has been manually triggered, in which case it will be undefined.
### getTasks

<MemberInfo kind="method" type={`() => Promise&#60;<a href='/reference/typescript-api/scheduled-tasks/scheduler-strategy#taskreport'>TaskReport</a>[]&#62;`}   />

Get all scheduled tasks.
### getTask

<MemberInfo kind="method" type={`(id: string) => Promise&#60;<a href='/reference/typescript-api/scheduled-tasks/scheduler-strategy#taskreport'>TaskReport</a> | undefined&#62;`}   />

Get a single scheduled task by its id.
### triggerTask

<MemberInfo kind="method" type={`(task: <a href='/reference/typescript-api/scheduled-tasks/scheduled-task#scheduledtask'>ScheduledTask</a>) => Promise&#60;void&#62;`}   />

Manually trigger a given task. This method is not used to actually invoke the
task function itself, since that would cause the task to run on the server
instance which we typically do not want. Instead, it should be used
to signal to the strategy that this specific task needs to be invoked
at the soonest opportunity.

For instance, in the <a href='/reference/typescript-api/scheduled-tasks/default-scheduler-strategy#defaultschedulerstrategy'>DefaultSchedulerStrategy</a> this is done by setting
a flag in the database table which is checked periodically and causes those tasks
to get immediately invoked.
### updateTask

<MemberInfo kind="method" type={`(input: UpdateScheduledTaskInput) => Promise&#60;<a href='/reference/typescript-api/scheduled-tasks/scheduler-strategy#taskreport'>TaskReport</a>&#62;`}   />

Update a scheduled task.


</div>


## TaskReport

<GenerationInfo sourceFile="packages/core/src/scheduler/scheduler-strategy.ts" sourceLine="16" packageName="@vendure/core" since="3.3.0" />

A report on the status of a scheduled task.

```ts title="Signature"
interface TaskReport {
    id: string;
    lastExecutedAt: Date | null;
    isRunning: boolean;
    lastResult: any;
    enabled: boolean;
}
```

<div className="members-wrapper">

### id

<MemberInfo kind="property" type={`string`}   />


### lastExecutedAt

<MemberInfo kind="property" type={`Date | null`}   />


### isRunning

<MemberInfo kind="property" type={`boolean`}   />


### lastResult

<MemberInfo kind="property" type={`any`}   />


### enabled

<MemberInfo kind="property" type={`boolean`}   />




</div>


---

---
title: "EntityDuplicatorService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## EntityDuplicatorService

<GenerationInfo sourceFile="packages/core/src/service/helpers/entity-duplicator/entity-duplicator.service.ts" sourceLine="23" packageName="@vendure/core" since="2.2.0" />

This service is used to duplicate entities using one of the configured
<a href='/reference/typescript-api/configuration/entity-duplicator#entityduplicator'>EntityDuplicator</a> functions.

```ts title="Signature"
class EntityDuplicatorService {
    constructor(configService: ConfigService, configArgService: ConfigArgService, connection: TransactionalConnection)
    getEntityDuplicators(ctx: RequestContext) => EntityDuplicatorDefinition[];
    duplicateEntity(ctx: RequestContext, input: DuplicateEntityInput) => Promise<DuplicateEntityResult>;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(configService: ConfigService, configArgService: ConfigArgService, connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>) => EntityDuplicatorService`}   />


### getEntityDuplicators

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => EntityDuplicatorDefinition[]`}   />

Returns all configured <a href='/reference/typescript-api/configuration/entity-duplicator#entityduplicator'>EntityDuplicator</a> definitions.
### duplicateEntity

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: DuplicateEntityInput) => Promise&#60;DuplicateEntityResult&#62;`}   />

Duplicates an entity using the specified <a href='/reference/typescript-api/configuration/entity-duplicator#entityduplicator'>EntityDuplicator</a>. The duplication is performed
within a transaction, so if an error occurs, the transaction will be rolled back.


</div>


---

---
title: "Service Helpers"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "OrderCalculator"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## OrderCalculator

<GenerationInfo sourceFile="packages/core/src/service/helpers/order-calculator/order-calculator.ts" sourceLine="35" packageName="@vendure/core" />

This helper is used when making changes to an Order, to apply all applicable price adjustments to that Order,
including:

- Promotions
- Taxes
- Shipping

```ts title="Signature"
class OrderCalculator {
    constructor(configService: ConfigService, zoneService: ZoneService, taxRateService: TaxRateService, shippingMethodService: ShippingMethodService, shippingCalculator: ShippingCalculator, requestContextCache: RequestContextCacheService)
    applyPriceAdjustments(ctx: RequestContext, order: Order, promotions: Promotion[], updatedOrderLines: OrderLine[] = [], options?: { recalculateShipping?: boolean }) => Promise<Order>;
    calculateOrderTotals(order: Order) => ;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(configService: ConfigService, zoneService: <a href='/reference/typescript-api/services/zone-service#zoneservice'>ZoneService</a>, taxRateService: <a href='/reference/typescript-api/services/tax-rate-service#taxrateservice'>TaxRateService</a>, shippingMethodService: <a href='/reference/typescript-api/services/shipping-method-service#shippingmethodservice'>ShippingMethodService</a>, shippingCalculator: <a href='/reference/typescript-api/shipping/shipping-calculator#shippingcalculator'>ShippingCalculator</a>, requestContextCache: <a href='/reference/typescript-api/cache/request-context-cache-service#requestcontextcacheservice'>RequestContextCacheService</a>) => OrderCalculator`}   />


### applyPriceAdjustments

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>, promotions: <a href='/reference/typescript-api/entities/promotion#promotion'>Promotion</a>[], updatedOrderLines: <a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a>[] = [], options?: { recalculateShipping?: boolean }) => Promise&#60;<a href='/reference/typescript-api/entities/order#order'>Order</a>&#62;`}   />

Applies taxes and promotions to an Order. Mutates the order object.
Returns an array of any OrderItems which had new adjustments
applied, either tax or promotions.
### calculateOrderTotals

<MemberInfo kind="method" type={`(order: <a href='/reference/typescript-api/entities/order#order'>Order</a>) => `}   />

Sets the totals properties on an Order by summing each OrderLine, and taking
into account any Surcharges and ShippingLines. Does not save the Order, so
the entity must be persisted to the DB after calling this method.

Note that this method does *not* evaluate any taxes or promotions. It assumes
that has already been done and is solely responsible for summing the
totals.


</div>


---

---
title: "OrderModifier"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## OrderModifier

<GenerationInfo sourceFile="packages/core/src/service/helpers/order-modifier/order-modifier.ts" sourceLine="84" packageName="@vendure/core" />

This helper is responsible for modifying the contents of an Order.

Note:
There is not a clear separation of concerns between the OrderService and this, since
the OrderService also contains some method which modify the Order (e.g. removeItemFromOrder).
So this helper was mainly extracted to isolate the huge `modifyOrder` method since the
OrderService was just growing too large. Future refactoring could improve the organization
of these Order-related methods into a more clearly-delineated set of classes.

```ts title="Signature"
class OrderModifier {
    constructor(connection: TransactionalConnection, configService: ConfigService, orderCalculator: OrderCalculator, paymentService: PaymentService, countryService: CountryService, stockMovementService: StockMovementService, productVariantService: ProductVariantService, customFieldRelationService: CustomFieldRelationService, promotionService: PromotionService, eventBus: EventBus, shippingCalculator: ShippingCalculator, historyService: HistoryService, translator: TranslatorService)
    constrainQuantityToSaleable(ctx: RequestContext, variant: ProductVariant, quantity: number, existingOrderLineQuantity:  = 0, quantityInOtherOrderLines:  = 0) => ;
    getExistingOrderLine(ctx: RequestContext, order: Order, productVariantId: ID, customFields?: { [key: string]: any }) => Promise<OrderLine | undefined>;
    getOrCreateOrderLine(ctx: RequestContext, order: Order, productVariantId: ID, customFields?: { [key: string]: any }) => ;
    updateOrderLineQuantity(ctx: RequestContext, orderLine: OrderLine, quantity: number, order: Order) => Promise<OrderLine>;
    cancelOrderByOrderLines(ctx: RequestContext, input: CancelOrderInput, lineInputs: OrderLineInput[]) => ;
    modifyOrder(ctx: RequestContext, input: ModifyOrderInput, order: Order) => Promise<JustErrorResults<ModifyOrderResult> | { order: Order; modification: OrderModification }>;
    setShippingMethods(ctx: RequestContext, order: Order, shippingMethodIds: ID[]) => ;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, configService: ConfigService, orderCalculator: <a href='/reference/typescript-api/service-helpers/order-calculator#ordercalculator'>OrderCalculator</a>, paymentService: <a href='/reference/typescript-api/services/payment-service#paymentservice'>PaymentService</a>, countryService: <a href='/reference/typescript-api/services/country-service#countryservice'>CountryService</a>, stockMovementService: <a href='/reference/typescript-api/services/stock-movement-service#stockmovementservice'>StockMovementService</a>, productVariantService: <a href='/reference/typescript-api/services/product-variant-service#productvariantservice'>ProductVariantService</a>, customFieldRelationService: CustomFieldRelationService, promotionService: <a href='/reference/typescript-api/services/promotion-service#promotionservice'>PromotionService</a>, eventBus: <a href='/reference/typescript-api/events/event-bus#eventbus'>EventBus</a>, shippingCalculator: <a href='/reference/typescript-api/shipping/shipping-calculator#shippingcalculator'>ShippingCalculator</a>, historyService: <a href='/reference/typescript-api/services/history-service#historyservice'>HistoryService</a>, translator: <a href='/reference/typescript-api/service-helpers/translator-service#translatorservice'>TranslatorService</a>) => OrderModifier`}   />


### constrainQuantityToSaleable

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, variant: <a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>, quantity: number, existingOrderLineQuantity:  = 0, quantityInOtherOrderLines:  = 0) => `}   />

Ensure that the ProductVariant has sufficient saleable stock to add the given
quantity to an Order.

- `existingOrderLineQuantity` is used when adding an item to the order, since if an OrderLine
already exists then we will be adding the new quantity to the existing quantity.
- `quantityInOtherOrderLines` is used when we have more than 1 OrderLine containing the same
ProductVariant. This occurs when there are custom fields defined on the OrderLine and the lines
have differing values for one or more custom fields. In this case, we need to take _all_ of these
OrderLines into account when constraining the quantity. See https://github.com/vendure-ecommerce/vendure/issues/2702
for more on this.
### getExistingOrderLine

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>, productVariantId: <a href='/reference/typescript-api/common/id#id'>ID</a>, customFields?: { [key: string]: any }) => Promise&#60;<a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a> | undefined&#62;`}   />

Given a ProductVariant ID and optional custom fields, this method will return an existing OrderLine that
matches, or `undefined` if no match is found.
### getOrCreateOrderLine

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>, productVariantId: <a href='/reference/typescript-api/common/id#id'>ID</a>, customFields?: { [key: string]: any }) => `}   />

Returns the OrderLine containing the given <a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>, taking into account any custom field values. If no existing
OrderLine is found, a new OrderLine will be created.
### updateOrderLineQuantity

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, orderLine: <a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a>, quantity: number, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>) => Promise&#60;<a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a>&#62;`}   />

Updates the quantity of an OrderLine, taking into account the available saleable stock level.
Returns the actual quantity that the OrderLine was updated to (which may be less than the
`quantity` argument if insufficient stock was available.
### cancelOrderByOrderLines

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: CancelOrderInput, lineInputs: OrderLineInput[]) => `}   />


### modifyOrder

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: ModifyOrderInput, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>) => Promise&#60;JustErrorResults&#60;ModifyOrderResult&#62; | { order: <a href='/reference/typescript-api/entities/order#order'>Order</a>; modification: <a href='/reference/typescript-api/entities/order-modification#ordermodification'>OrderModification</a> }&#62;`}   />


### setShippingMethods

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>, shippingMethodIds: <a href='/reference/typescript-api/common/id#id'>ID</a>[]) => `}   />




</div>


---

---
title: "ProductPriceApplicator"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ProductPriceApplicator

<GenerationInfo sourceFile="packages/core/src/service/helpers/product-price-applicator/product-price-applicator.ts" sourceLine="41" packageName="@vendure/core" />

This helper is used to apply the correct price to a ProductVariant based on the current context
including active Channel, any current Order, etc. If you use the <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a> to
directly query ProductVariants, you will find that the `price` and `priceWithTax` properties will
always be `0` until you use the `applyChannelPriceAndTax()` method:

*Example*

```ts
export class MyCustomService {
  constructor(private connection: TransactionalConnection,
              private productPriceApplicator: ProductPriceApplicator) {}

  getVariant(ctx: RequestContext, id: ID) {
    const productVariant = await this.connection
      .getRepository(ctx, ProductVariant)
      .findOne(id, { relations: ['taxCategory'] });

    await this.productPriceApplicator
      .applyChannelPriceAndTax(productVariant, ctx);

    return productVariant;
  }
}
```

```ts title="Signature"
class ProductPriceApplicator {
    constructor(configService: ConfigService, taxRateService: TaxRateService, zoneService: ZoneService, requestCache: RequestContextCacheService)
    applyChannelPriceAndTax(variant: ProductVariant, ctx: RequestContext, order?: Order, throwIfNoPriceFound:  = false) => Promise<ProductVariant>;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(configService: ConfigService, taxRateService: <a href='/reference/typescript-api/services/tax-rate-service#taxrateservice'>TaxRateService</a>, zoneService: <a href='/reference/typescript-api/services/zone-service#zoneservice'>ZoneService</a>, requestCache: <a href='/reference/typescript-api/cache/request-context-cache-service#requestcontextcacheservice'>RequestContextCacheService</a>) => ProductPriceApplicator`}   />


### applyChannelPriceAndTax

<MemberInfo kind="method" type={`(variant: <a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>, ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, order?: <a href='/reference/typescript-api/entities/order#order'>Order</a>, throwIfNoPriceFound:  = false) => Promise&#60;<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>&#62;`}   />

Populates the `price` field with the price for the specified channel. Make sure that
the ProductVariant being passed in has its `taxCategory` relation joined.

If the `throwIfNoPriceFound` option is set to `true`, then an error will be thrown if no
price is found for the given Channel.


</div>


---

---
title: "SlugValidator"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## SlugValidator

<GenerationInfo sourceFile="packages/core/src/service/helpers/slug-validator/slug-validator.ts" sourceLine="44" packageName="@vendure/core" />

Used to validate slugs to ensure they are URL-safe and unique. Designed to be used with translatable
entities such as <a href='/reference/typescript-api/entities/product#product'>Product</a> and <a href='/reference/typescript-api/entities/collection#collection'>Collection</a>.

```ts title="Signature"
class SlugValidator {
    constructor(connection: TransactionalConnection)
    validateSlugs(ctx: RequestContext, input: T, translationEntity: Type<E>) => Promise<T>;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>) => SlugValidator`}   />


### validateSlugs

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: T, translationEntity: Type&#60;E&#62;) => Promise&#60;T&#62;`}   />




</div>


## InputWithSlug

<GenerationInfo sourceFile="packages/core/src/service/helpers/slug-validator/slug-validator.ts" sourceLine="16" packageName="@vendure/core" />



```ts title="Signature"
type InputWithSlug = {
    id?: ID | null;
    translations?: Array<{
        id?: ID | null;
        languageCode: LanguageCode;
        slug?: string | null;
    }> | null;
}
```

<div className="members-wrapper">

### id

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a> | null`}   />


### translations

<MemberInfo kind="property" type={`Array&#60;{         id?: <a href='/reference/typescript-api/common/id#id'>ID</a> | null;         languageCode: <a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a>;         slug?: string | null;     }&#62; | null`}   />




</div>


## TranslationEntity

<GenerationInfo sourceFile="packages/core/src/service/helpers/slug-validator/slug-validator.ts" sourceLine="29" packageName="@vendure/core" />



```ts title="Signature"
type TranslationEntity = VendureEntity & {
    id: ID;
    languageCode: LanguageCode;
    slug: string;
    base: any;
}
```


---

---
title: "TranslatableSaver"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## TranslatableSaver

<GenerationInfo sourceFile="packages/core/src/service/helpers/translatable-saver/translatable-saver.ts" sourceLine="55" packageName="@vendure/core" />

A helper which contains methods for creating and updating entities which implement the <a href='/reference/typescript-api/entities/interfaces#translatable'>Translatable</a> interface.

*Example*

```ts
export class MyService {
  constructor(private translatableSaver: TranslatableSaver) {}

  async create(ctx: RequestContext, input: CreateFacetInput): Promise<Translated<Facet>> {
    const facet = await this.translatableSaver.create({
      ctx,
      input,
      entityType: Facet,
      translationType: FacetTranslation,
      beforeSave: async f => {
          f.code = await this.ensureUniqueCode(ctx, f.code);
      },
    });
    return facet;
  }

  // ...
}
```

```ts title="Signature"
class TranslatableSaver {
    constructor(connection: TransactionalConnection)
    create(options: CreateTranslatableOptions<T>) => Promise<T>;
    update(options: UpdateTranslatableOptions<T>) => Promise<T>;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>) => TranslatableSaver`}   />


### create

<MemberInfo kind="method" type={`(options: CreateTranslatableOptions&#60;T&#62;) => Promise&#60;T&#62;`}   />

Create a translatable entity, including creating any translation entities according
to the `translations` array.
### update

<MemberInfo kind="method" type={`(options: UpdateTranslatableOptions&#60;T&#62;) => Promise&#60;T&#62;`}   />

Update a translatable entity. Performs a diff of the `translations` array in order to
perform the correct operation on the translations.


</div>


---

---
title: "TranslatorService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## TranslatorService

<GenerationInfo sourceFile="packages/core/src/service/helpers/translator/translator.service.ts" sourceLine="42" packageName="@vendure/core" />

The TranslatorService is used to translate entities into the current language.

*Example*

```ts
import { Injectable } from '@nestjs/common';
import { ID, Product, RequestContext, TransactionalConnection, TranslatorService } from '@vendure/core';

@Injectable()
export class ProductService {

    constructor(private connection: TransactionalConnection,
                private translator: TranslatorService){}

    async findOne(ctx: RequestContext, productId: ID): Promise<Product | undefined> {
        const product = await this.connection.findOneInChannel(ctx, Product, productId, ctx.channelId, {
            relations: {
                 facetValues: {
                     facet: true,
                 }
            }
        });
        if (!product) {
            return;
        }
        return this.translator.translate(product, ctx, ['facetValues', ['facetValues', 'facet']]);
    }
}
```

```ts title="Signature"
class TranslatorService {
    constructor(configService: ConfigService)
    translate(translatable: T, ctx: RequestContext, translatableRelations: DeepTranslatableRelations<T> = []) => ;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(configService: ConfigService) => TranslatorService`}   />


### translate

<MemberInfo kind="method" type={`(translatable: T, ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, translatableRelations: DeepTranslatableRelations&#60;T&#62; = []) => `}   />




</div>


---

---
title: "AdministratorService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## AdministratorService

<GenerationInfo sourceFile="packages/core/src/service/services/administrator.service.ts" sourceLine="41" packageName="@vendure/core" />

Contains methods relating to <a href='/reference/typescript-api/entities/administrator#administrator'>Administrator</a> entities.

```ts title="Signature"
class AdministratorService {
    constructor(connection: TransactionalConnection, configService: ConfigService, listQueryBuilder: ListQueryBuilder, passwordCipher: PasswordCipher, userService: UserService, roleService: RoleService, customFieldRelationService: CustomFieldRelationService, eventBus: EventBus, requestContextService: RequestContextService)
    findAll(ctx: RequestContext, options?: ListQueryOptions<Administrator>, relations?: RelationPaths<Administrator>) => Promise<PaginatedList<Administrator>>;
    findOne(ctx: RequestContext, administratorId: ID, relations?: RelationPaths<Administrator>) => Promise<Administrator | undefined>;
    findOneByUserId(ctx: RequestContext, userId: ID, relations?: RelationPaths<Administrator>) => Promise<Administrator | undefined>;
    create(ctx: RequestContext, input: CreateAdministratorInput) => Promise<Administrator>;
    update(ctx: RequestContext, input: UpdateAdministratorInput) => Promise<Administrator>;
    assignRole(ctx: RequestContext, administratorId: ID, roleId: ID) => Promise<Administrator>;
    softDelete(ctx: RequestContext, id: ID) => ;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, configService: ConfigService, listQueryBuilder: <a href='/reference/typescript-api/data-access/list-query-builder#listquerybuilder'>ListQueryBuilder</a>, passwordCipher: PasswordCipher, userService: <a href='/reference/typescript-api/services/user-service#userservice'>UserService</a>, roleService: <a href='/reference/typescript-api/services/role-service#roleservice'>RoleService</a>, customFieldRelationService: CustomFieldRelationService, eventBus: <a href='/reference/typescript-api/events/event-bus#eventbus'>EventBus</a>, requestContextService: <a href='/reference/typescript-api/request/request-context-service#requestcontextservice'>RequestContextService</a>) => AdministratorService`}   />


### findAll

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, options?: ListQueryOptions&#60;<a href='/reference/typescript-api/entities/administrator#administrator'>Administrator</a>&#62;, relations?: RelationPaths&#60;<a href='/reference/typescript-api/entities/administrator#administrator'>Administrator</a>&#62;) => Promise&#60;<a href='/reference/typescript-api/common/paginated-list#paginatedlist'>PaginatedList</a>&#60;<a href='/reference/typescript-api/entities/administrator#administrator'>Administrator</a>&#62;&#62;`}   />

Get a paginated list of Administrators.
### findOne

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, administratorId: <a href='/reference/typescript-api/common/id#id'>ID</a>, relations?: RelationPaths&#60;<a href='/reference/typescript-api/entities/administrator#administrator'>Administrator</a>&#62;) => Promise&#60;<a href='/reference/typescript-api/entities/administrator#administrator'>Administrator</a> | undefined&#62;`}   />

Get an Administrator by id.
### findOneByUserId

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, userId: <a href='/reference/typescript-api/common/id#id'>ID</a>, relations?: RelationPaths&#60;<a href='/reference/typescript-api/entities/administrator#administrator'>Administrator</a>&#62;) => Promise&#60;<a href='/reference/typescript-api/entities/administrator#administrator'>Administrator</a> | undefined&#62;`}   />

Get an Administrator based on the User id.
### create

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: CreateAdministratorInput) => Promise&#60;<a href='/reference/typescript-api/entities/administrator#administrator'>Administrator</a>&#62;`}   />

Create a new Administrator.
### update

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: UpdateAdministratorInput) => Promise&#60;<a href='/reference/typescript-api/entities/administrator#administrator'>Administrator</a>&#62;`}   />

Update an existing Administrator.
### assignRole

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, administratorId: <a href='/reference/typescript-api/common/id#id'>ID</a>, roleId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/entities/administrator#administrator'>Administrator</a>&#62;`}   />

Assigns a Role to the Administrator's User entity.
### softDelete

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, id: <a href='/reference/typescript-api/common/id#id'>ID</a>) => `}   />

Soft deletes an Administrator (sets the `deletedAt` field).


</div>


---

---
title: "AssetService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## AssetService

<GenerationInfo sourceFile="packages/core/src/service/services/asset.service.ts" sourceLine="91" packageName="@vendure/core" />

Contains methods relating to <a href='/reference/typescript-api/entities/asset#asset'>Asset</a> entities.

```ts title="Signature"
class AssetService {
    constructor(connection: TransactionalConnection, configService: ConfigService, listQueryBuilder: ListQueryBuilder, eventBus: EventBus, tagService: TagService, channelService: ChannelService, roleService: RoleService, customFieldRelationService: CustomFieldRelationService)
    findOne(ctx: RequestContext, id: ID, relations?: RelationPaths<Asset>) => Promise<Asset | undefined>;
    findAll(ctx: RequestContext, options?: AssetListOptions, relations?: RelationPaths<Asset>) => Promise<PaginatedList<Asset>>;
    getFeaturedAsset(ctx: RequestContext, entity: T) => Promise<Asset | undefined>;
    getEntityAssets(ctx: RequestContext, entity: T) => Promise<Asset[] | undefined>;
    updateFeaturedAsset(ctx: RequestContext, entity: T, input: EntityAssetInput) => Promise<T>;
    updateEntityAssets(ctx: RequestContext, entity: T, input: EntityAssetInput) => Promise<T>;
    create(ctx: RequestContext, input: CreateAssetInput) => Promise<CreateAssetResult>;
    update(ctx: RequestContext, input: UpdateAssetInput) => Promise<Asset>;
    delete(ctx: RequestContext, ids: ID[], force: boolean = false, deleteFromAllChannels: boolean = false) => Promise<DeletionResponse>;
    assignToChannel(ctx: RequestContext, input: AssignAssetsToChannelInput) => Promise<Asset[]>;
    createFromFileStream(stream: ReadStream, ctx?: RequestContext) => Promise<CreateAssetResult>;
    createFromFileStream(stream: Readable, filePath: string, ctx?: RequestContext) => Promise<CreateAssetResult>;
    createFromFileStream(stream: ReadStream | Readable, maybeFilePathOrCtx?: string | RequestContext, maybeCtx?: RequestContext) => Promise<CreateAssetResult>;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, configService: ConfigService, listQueryBuilder: <a href='/reference/typescript-api/data-access/list-query-builder#listquerybuilder'>ListQueryBuilder</a>, eventBus: <a href='/reference/typescript-api/events/event-bus#eventbus'>EventBus</a>, tagService: <a href='/reference/typescript-api/services/tag-service#tagservice'>TagService</a>, channelService: <a href='/reference/typescript-api/services/channel-service#channelservice'>ChannelService</a>, roleService: <a href='/reference/typescript-api/services/role-service#roleservice'>RoleService</a>, customFieldRelationService: CustomFieldRelationService) => AssetService`}   />


### findOne

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, id: <a href='/reference/typescript-api/common/id#id'>ID</a>, relations?: RelationPaths&#60;<a href='/reference/typescript-api/entities/asset#asset'>Asset</a>&#62;) => Promise&#60;<a href='/reference/typescript-api/entities/asset#asset'>Asset</a> | undefined&#62;`}   />


### findAll

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, options?: AssetListOptions, relations?: RelationPaths&#60;<a href='/reference/typescript-api/entities/asset#asset'>Asset</a>&#62;) => Promise&#60;<a href='/reference/typescript-api/common/paginated-list#paginatedlist'>PaginatedList</a>&#60;<a href='/reference/typescript-api/entities/asset#asset'>Asset</a>&#62;&#62;`}   />


### getFeaturedAsset

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, entity: T) => Promise&#60;<a href='/reference/typescript-api/entities/asset#asset'>Asset</a> | undefined&#62;`}   />


### getEntityAssets

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, entity: T) => Promise&#60;<a href='/reference/typescript-api/entities/asset#asset'>Asset</a>[] | undefined&#62;`}   />

Returns the Assets of an entity which has a well-ordered list of Assets, such as Product,
ProductVariant or Collection.
### updateFeaturedAsset

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, entity: T, input: <a href='/reference/typescript-api/services/asset-service#entityassetinput'>EntityAssetInput</a>) => Promise&#60;T&#62;`}   />


### updateEntityAssets

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, entity: T, input: <a href='/reference/typescript-api/services/asset-service#entityassetinput'>EntityAssetInput</a>) => Promise&#60;T&#62;`}   />

Updates the assets / featuredAsset of an entity, ensuring that only valid assetIds are used.
### create

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: CreateAssetInput) => Promise&#60;CreateAssetResult&#62;`}   />

Create an Asset based on a file uploaded via the GraphQL API. The file should be uploaded
using the [GraphQL multipart request specification](https://github.com/jaydenseric/graphql-multipart-request-spec),
e.g. using the [apollo-upload-client](https://github.com/jaydenseric/apollo-upload-client) npm package.

See the [Uploading Files docs](/guides/developer-guide/uploading-files) for an example of usage.
### update

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: UpdateAssetInput) => Promise&#60;<a href='/reference/typescript-api/entities/asset#asset'>Asset</a>&#62;`}   />

Updates the name, focalPoint, tags & custom fields of an Asset.
### delete

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, ids: <a href='/reference/typescript-api/common/id#id'>ID</a>[], force: boolean = false, deleteFromAllChannels: boolean = false) => Promise&#60;DeletionResponse&#62;`}   />

Deletes an Asset after performing checks to ensure that the Asset is not currently in use
by a Product, ProductVariant or Collection.
### assignToChannel

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: AssignAssetsToChannelInput) => Promise&#60;<a href='/reference/typescript-api/entities/asset#asset'>Asset</a>[]&#62;`}   />


### createFromFileStream

<MemberInfo kind="method" type={`(stream: ReadStream, ctx?: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => Promise&#60;CreateAssetResult&#62;`}   />

Create an Asset from a file stream, for example to create an Asset during data import.
### createFromFileStream

<MemberInfo kind="method" type={`(stream: Readable, filePath: string, ctx?: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => Promise&#60;CreateAssetResult&#62;`}   />


### createFromFileStream

<MemberInfo kind="method" type={`(stream: ReadStream | Readable, maybeFilePathOrCtx?: string | <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, maybeCtx?: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => Promise&#60;CreateAssetResult&#62;`}   />




</div>


## EntityWithAssets

<GenerationInfo sourceFile="packages/core/src/service/services/asset.service.ts" sourceLine="67" packageName="@vendure/core" />

Certain entities (Product, ProductVariant, Collection) use this interface
to model a featured asset and then a list of assets with a defined order.

```ts title="Signature"
interface EntityWithAssets extends VendureEntity {
    featuredAsset: Asset | null;
    assets: OrderableAsset[];
}
```
* Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>



<div className="members-wrapper">

### featuredAsset

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/asset#asset'>Asset</a> | null`}   />


### assets

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/orderable-asset#orderableasset'>OrderableAsset</a>[]`}   />




</div>


## EntityAssetInput

<GenerationInfo sourceFile="packages/core/src/service/services/asset.service.ts" sourceLine="79" packageName="@vendure/core" />

Used when updating entities which implement <a href='/reference/typescript-api/services/asset-service#entitywithassets'>EntityWithAssets</a>.

```ts title="Signature"
interface EntityAssetInput {
    assetIds?: ID[] | null;
    featuredAssetId?: ID | null;
}
```

<div className="members-wrapper">

### assetIds

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a>[] | null`}   />


### featuredAssetId

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a> | null`}   />




</div>


---

---
title: "AuthService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## AuthService

<GenerationInfo sourceFile="packages/core/src/service/services/auth.service.ts" sourceLine="37" packageName="@vendure/core" />

Contains methods relating to <a href='/reference/typescript-api/entities/session#session'>Session</a>, <a href='/reference/typescript-api/entities/authenticated-session#authenticatedsession'>AuthenticatedSession</a> & <a href='/reference/typescript-api/entities/anonymous-session#anonymoussession'>AnonymousSession</a> entities.

```ts title="Signature"
class AuthService {
    constructor(connection: TransactionalConnection, configService: ConfigService, sessionService: SessionService, eventBus: EventBus)
    authenticate(ctx: RequestContext, apiType: ApiType, authenticationMethod: string, authenticationData: any) => Promise<AuthenticatedSession | InvalidCredentialsError | NotVerifiedError>;
    createAuthenticatedSessionForUser(ctx: RequestContext, user: User, authenticationStrategyName: string) => Promise<AuthenticatedSession | NotVerifiedError>;
    verifyUserPassword(ctx: RequestContext, userId: ID, password: string) => Promise<boolean | InvalidCredentialsError | ShopInvalidCredentialsError>;
    destroyAuthenticatedSession(ctx: RequestContext, sessionToken: string) => Promise<void>;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, configService: ConfigService, sessionService: <a href='/reference/typescript-api/services/session-service#sessionservice'>SessionService</a>, eventBus: <a href='/reference/typescript-api/events/event-bus#eventbus'>EventBus</a>) => AuthService`}   />


### authenticate

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, apiType: <a href='/reference/typescript-api/request/api-type#apitype'>ApiType</a>, authenticationMethod: string, authenticationData: any) => Promise&#60;<a href='/reference/typescript-api/entities/authenticated-session#authenticatedsession'>AuthenticatedSession</a> | InvalidCredentialsError | NotVerifiedError&#62;`}   />

Authenticates a user's credentials and if okay, creates a new <a href='/reference/typescript-api/entities/authenticated-session#authenticatedsession'>AuthenticatedSession</a>.
### createAuthenticatedSessionForUser

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, user: <a href='/reference/typescript-api/entities/user#user'>User</a>, authenticationStrategyName: string) => Promise&#60;<a href='/reference/typescript-api/entities/authenticated-session#authenticatedsession'>AuthenticatedSession</a> | NotVerifiedError&#62;`}   />


### verifyUserPassword

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, userId: <a href='/reference/typescript-api/common/id#id'>ID</a>, password: string) => Promise&#60;boolean | InvalidCredentialsError | ShopInvalidCredentialsError&#62;`}   />

Verify the provided password against the one we have for the given user. Requires
the <a href='/reference/typescript-api/auth/native-authentication-strategy#nativeauthenticationstrategy'>NativeAuthenticationStrategy</a> to be configured.
### destroyAuthenticatedSession

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, sessionToken: string) => Promise&#60;void&#62;`}   />

Deletes all sessions for the user associated with the given session token.


</div>


---

---
title: "ChannelService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ChannelService

<GenerationInfo sourceFile="packages/core/src/service/services/channel.service.ts" sourceLine="54" packageName="@vendure/core" />

Contains methods relating to <a href='/reference/typescript-api/entities/channel#channel'>Channel</a> entities.

```ts title="Signature"
class ChannelService {
    constructor(connection: TransactionalConnection, configService: ConfigService, globalSettingsService: GlobalSettingsService, customFieldRelationService: CustomFieldRelationService, eventBus: EventBus, listQueryBuilder: ListQueryBuilder)
    assignToCurrentChannel(entity: T, ctx: RequestContext) => Promise<T>;
    assignToChannels(ctx: RequestContext, entityType: Type<T>, entityId: ID, channelIds: ID[]) => Promise<T>;
    removeFromChannels(ctx: RequestContext, entityType: Type<T>, entityId: ID, channelIds: ID[]) => Promise<T | undefined>;
    getChannelFromToken(token: string) => Promise<Channel>;
    getChannelFromToken(ctx: RequestContext, token: string) => Promise<Channel>;
    getChannelFromToken(ctxOrToken: RequestContext | string, token?: string) => Promise<Channel>;
    getDefaultChannel(ctx?: RequestContext) => Promise<Channel>;
    findAll(ctx: RequestContext, options?: ListQueryOptions<Channel>, relations?: RelationPaths<Channel>) => Promise<PaginatedList<Channel>>;
    findOne(ctx: RequestContext, id: ID) => Promise<Channel | undefined>;
    create(ctx: RequestContext, input: CreateChannelInput) => Promise<ErrorResultUnion<CreateChannelResult, Channel>>;
    update(ctx: RequestContext, input: UpdateChannelInput) => Promise<ErrorResultUnion<UpdateChannelResult, Channel>>;
    delete(ctx: RequestContext, id: ID) => Promise<DeletionResponse>;
    isChannelAware(entity: VendureEntity) => entity is VendureEntity & ChannelAware;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, configService: ConfigService, globalSettingsService: <a href='/reference/typescript-api/services/global-settings-service#globalsettingsservice'>GlobalSettingsService</a>, customFieldRelationService: CustomFieldRelationService, eventBus: <a href='/reference/typescript-api/events/event-bus#eventbus'>EventBus</a>, listQueryBuilder: <a href='/reference/typescript-api/data-access/list-query-builder#listquerybuilder'>ListQueryBuilder</a>) => ChannelService`}   />


### assignToCurrentChannel

<MemberInfo kind="method" type={`(entity: T, ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => Promise&#60;T&#62;`}   />

Assigns a ChannelAware entity to the default Channel as well as any channel
specified in the RequestContext. This method will not save the entity to the database, but
assigns the `channels` property of the entity.
### assignToChannels

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, entityType: Type&#60;T&#62;, entityId: <a href='/reference/typescript-api/common/id#id'>ID</a>, channelIds: <a href='/reference/typescript-api/common/id#id'>ID</a>[]) => Promise&#60;T&#62;`}   />

Assigns the entity to the given Channels and saves all changes to the database.
### removeFromChannels

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, entityType: Type&#60;T&#62;, entityId: <a href='/reference/typescript-api/common/id#id'>ID</a>, channelIds: <a href='/reference/typescript-api/common/id#id'>ID</a>[]) => Promise&#60;T | undefined&#62;`}   />

Removes the entity from the given Channels and saves.
### getChannelFromToken

<MemberInfo kind="method" type={`(token: string) => Promise&#60;<a href='/reference/typescript-api/entities/channel#channel'>Channel</a>&#62;`}   />

Given a channel token, returns the corresponding Channel if it exists, else will throw
a <a href='/reference/typescript-api/errors/error-types#channelnotfounderror'>ChannelNotFoundError</a>.
### getChannelFromToken

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, token: string) => Promise&#60;<a href='/reference/typescript-api/entities/channel#channel'>Channel</a>&#62;`}   />


### getChannelFromToken

<MemberInfo kind="method" type={`(ctxOrToken: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a> | string, token?: string) => Promise&#60;<a href='/reference/typescript-api/entities/channel#channel'>Channel</a>&#62;`}   />


### getDefaultChannel

<MemberInfo kind="method" type={`(ctx?: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => Promise&#60;<a href='/reference/typescript-api/entities/channel#channel'>Channel</a>&#62;`}   />

Returns the default Channel.
### findAll

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, options?: ListQueryOptions&#60;<a href='/reference/typescript-api/entities/channel#channel'>Channel</a>&#62;, relations?: RelationPaths&#60;<a href='/reference/typescript-api/entities/channel#channel'>Channel</a>&#62;) => Promise&#60;<a href='/reference/typescript-api/common/paginated-list#paginatedlist'>PaginatedList</a>&#60;<a href='/reference/typescript-api/entities/channel#channel'>Channel</a>&#62;&#62;`}   />


### findOne

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, id: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/entities/channel#channel'>Channel</a> | undefined&#62;`}   />


### create

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: CreateChannelInput) => Promise&#60;<a href='/reference/typescript-api/errors/error-result-union#errorresultunion'>ErrorResultUnion</a>&#60;CreateChannelResult, <a href='/reference/typescript-api/entities/channel#channel'>Channel</a>&#62;&#62;`}   />


### update

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: UpdateChannelInput) => Promise&#60;<a href='/reference/typescript-api/errors/error-result-union#errorresultunion'>ErrorResultUnion</a>&#60;UpdateChannelResult, <a href='/reference/typescript-api/entities/channel#channel'>Channel</a>&#62;&#62;`}   />


### delete

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, id: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;DeletionResponse&#62;`}   />


### isChannelAware

<MemberInfo kind="method" type={`(entity: <a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a>) => entity is <a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a> &#38; <a href='/reference/typescript-api/entities/interfaces#channelaware'>ChannelAware</a>`}   />

Type guard method which returns true if the given entity is an
instance of a class which implements the <a href='/reference/typescript-api/entities/interfaces#channelaware'>ChannelAware</a> interface.


</div>


---

---
title: "CollectionService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## CollectionService

<GenerationInfo sourceFile="packages/core/src/service/services/collection.service.ts" sourceLine="77" packageName="@vendure/core" />

Contains methods relating to <a href='/reference/typescript-api/entities/collection#collection'>Collection</a> entities.

```ts title="Signature"
class CollectionService implements OnModuleInit {
    constructor(connection: TransactionalConnection, channelService: ChannelService, assetService: AssetService, listQueryBuilder: ListQueryBuilder, translatableSaver: TranslatableSaver, eventBus: EventBus, jobQueueService: JobQueueService, configService: ConfigService, slugValidator: SlugValidator, configArgService: ConfigArgService, customFieldRelationService: CustomFieldRelationService, translator: TranslatorService, roleService: RoleService, requestContextService: RequestContextService)
    findAll(ctx: RequestContext, options?: ListQueryOptions<Collection> & { topLevelOnly?: boolean }, relations?: RelationPaths<Collection>) => Promise<PaginatedList<Translated<Collection>>>;
    findOne(ctx: RequestContext, collectionId: ID, relations?: RelationPaths<Collection>) => Promise<Translated<Collection> | undefined>;
    findByIds(ctx: RequestContext, ids: ID[], relations?: RelationPaths<Collection>) => Promise<Array<Translated<Collection>>>;
    findOneBySlug(ctx: RequestContext, slug: string, relations?: RelationPaths<Collection>) => Promise<Translated<Collection> | undefined>;
    getAvailableFilters(ctx: RequestContext) => ConfigurableOperationDefinition[];
    getParent(ctx: RequestContext, collectionId: ID) => Promise<Collection | undefined>;
    getChildren(ctx: RequestContext, collectionId: ID) => Promise<Collection[]>;
    getBreadcrumbs(ctx: RequestContext, collection: Collection) => Promise<Array<{ name: string; id: ID; slug: string }>>;
    getCollectionsByProductId(ctx: RequestContext, productId: ID, publicOnly: boolean) => Promise<Array<Translated<Collection>>>;
    getDescendants(ctx: RequestContext, rootId: ID, maxDepth: number = Number.MAX_SAFE_INTEGER) => Promise<Array<Translated<Collection>>>;
    getAncestors(collectionId: ID) => Promise<Collection[]>;
    getAncestors(collectionId: ID, ctx: RequestContext) => Promise<Array<Translated<Collection>>>;
    getAncestors(collectionId: ID, ctx?: RequestContext) => Promise<Array<Translated<Collection> | Collection>>;
    previewCollectionVariants(ctx: RequestContext, input: PreviewCollectionVariantsInput, options?: ListQueryOptions<ProductVariant>, relations?: RelationPaths<Collection>) => Promise<PaginatedList<ProductVariant>>;
    create(ctx: RequestContext, input: CreateCollectionInput) => Promise<Translated<Collection>>;
    update(ctx: RequestContext, input: UpdateCollectionInput) => Promise<Translated<Collection>>;
    delete(ctx: RequestContext, id: ID) => Promise<DeletionResponse>;
    move(ctx: RequestContext, input: MoveCollectionInput) => Promise<Translated<Collection>>;
    setApplyAllFiltersOnProductUpdates(applyAllFiltersOnProductUpdates: boolean) => ;
    triggerApplyFiltersJob(ctx: RequestContext, options?: { collectionIds?: ID[]; applyToChangedVariantsOnly?: boolean }) => ;
    getCollectionProductVariantIds(collection: Collection, ctx?: RequestContext) => Promise<ID[]>;
    assignCollectionsToChannel(ctx: RequestContext, input: AssignCollectionsToChannelInput) => Promise<Array<Translated<Collection>>>;
    removeCollectionsFromChannel(ctx: RequestContext, input: RemoveCollectionsFromChannelInput) => Promise<Array<Translated<Collection>>>;
}
```
* Implements: <code>OnModuleInit</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, channelService: <a href='/reference/typescript-api/services/channel-service#channelservice'>ChannelService</a>, assetService: <a href='/reference/typescript-api/services/asset-service#assetservice'>AssetService</a>, listQueryBuilder: <a href='/reference/typescript-api/data-access/list-query-builder#listquerybuilder'>ListQueryBuilder</a>, translatableSaver: <a href='/reference/typescript-api/service-helpers/translatable-saver#translatablesaver'>TranslatableSaver</a>, eventBus: <a href='/reference/typescript-api/events/event-bus#eventbus'>EventBus</a>, jobQueueService: <a href='/reference/typescript-api/job-queue/job-queue-service#jobqueueservice'>JobQueueService</a>, configService: ConfigService, slugValidator: <a href='/reference/typescript-api/service-helpers/slug-validator#slugvalidator'>SlugValidator</a>, configArgService: ConfigArgService, customFieldRelationService: CustomFieldRelationService, translator: <a href='/reference/typescript-api/service-helpers/translator-service#translatorservice'>TranslatorService</a>, roleService: <a href='/reference/typescript-api/services/role-service#roleservice'>RoleService</a>, requestContextService: <a href='/reference/typescript-api/request/request-context-service#requestcontextservice'>RequestContextService</a>) => CollectionService`}   />


### findAll

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, options?: ListQueryOptions&#60;<a href='/reference/typescript-api/entities/collection#collection'>Collection</a>&#62; &#38; { topLevelOnly?: boolean }, relations?: RelationPaths&#60;<a href='/reference/typescript-api/entities/collection#collection'>Collection</a>&#62;) => Promise&#60;<a href='/reference/typescript-api/common/paginated-list#paginatedlist'>PaginatedList</a>&#60;Translated&#60;<a href='/reference/typescript-api/entities/collection#collection'>Collection</a>&#62;&#62;&#62;`}   />


### findOne

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, collectionId: <a href='/reference/typescript-api/common/id#id'>ID</a>, relations?: RelationPaths&#60;<a href='/reference/typescript-api/entities/collection#collection'>Collection</a>&#62;) => Promise&#60;Translated&#60;<a href='/reference/typescript-api/entities/collection#collection'>Collection</a>&#62; | undefined&#62;`}   />


### findByIds

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, ids: <a href='/reference/typescript-api/common/id#id'>ID</a>[], relations?: RelationPaths&#60;<a href='/reference/typescript-api/entities/collection#collection'>Collection</a>&#62;) => Promise&#60;Array&#60;Translated&#60;<a href='/reference/typescript-api/entities/collection#collection'>Collection</a>&#62;&#62;&#62;`}   />


### findOneBySlug

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, slug: string, relations?: RelationPaths&#60;<a href='/reference/typescript-api/entities/collection#collection'>Collection</a>&#62;) => Promise&#60;Translated&#60;<a href='/reference/typescript-api/entities/collection#collection'>Collection</a>&#62; | undefined&#62;`}   />


### getAvailableFilters

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => ConfigurableOperationDefinition[]`}   />

Returns all configured CollectionFilters, as specified by the <a href='/reference/typescript-api/products-stock/catalog-options#catalogoptions'>CatalogOptions</a>.
### getParent

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, collectionId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/entities/collection#collection'>Collection</a> | undefined&#62;`}   />


### getChildren

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, collectionId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/entities/collection#collection'>Collection</a>[]&#62;`}   />

Returns all child Collections of the Collection with the given id.
### getBreadcrumbs

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, collection: <a href='/reference/typescript-api/entities/collection#collection'>Collection</a>) => Promise&#60;Array&#60;{ name: string; id: <a href='/reference/typescript-api/common/id#id'>ID</a>; slug: string }&#62;&#62;`}   />

Returns an array of name/id pairs representing all ancestor Collections up
to the Root Collection.
### getCollectionsByProductId

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, productId: <a href='/reference/typescript-api/common/id#id'>ID</a>, publicOnly: boolean) => Promise&#60;Array&#60;Translated&#60;<a href='/reference/typescript-api/entities/collection#collection'>Collection</a>&#62;&#62;&#62;`}   />

Returns all Collections which are associated with the given Product ID.
### getDescendants

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, rootId: <a href='/reference/typescript-api/common/id#id'>ID</a>, maxDepth: number = Number.MAX_SAFE_INTEGER) => Promise&#60;Array&#60;Translated&#60;<a href='/reference/typescript-api/entities/collection#collection'>Collection</a>&#62;&#62;&#62;`}   />

Returns the descendants of a Collection as a flat array. The depth of the traversal can be limited
with the maxDepth argument. So to get only the immediate children, set maxDepth = 1.
### getAncestors

<MemberInfo kind="method" type={`(collectionId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/entities/collection#collection'>Collection</a>[]&#62;`}   />

Gets the ancestors of a given collection. Note that since ProductCategories are implemented as an adjacency list, this method
will produce more queries the deeper the collection is in the tree.
### getAncestors

<MemberInfo kind="method" type={`(collectionId: <a href='/reference/typescript-api/common/id#id'>ID</a>, ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => Promise&#60;Array&#60;Translated&#60;<a href='/reference/typescript-api/entities/collection#collection'>Collection</a>&#62;&#62;&#62;`}   />


### getAncestors

<MemberInfo kind="method" type={`(collectionId: <a href='/reference/typescript-api/common/id#id'>ID</a>, ctx?: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => Promise&#60;Array&#60;Translated&#60;<a href='/reference/typescript-api/entities/collection#collection'>Collection</a>&#62; | <a href='/reference/typescript-api/entities/collection#collection'>Collection</a>&#62;&#62;`}   />


### previewCollectionVariants

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: PreviewCollectionVariantsInput, options?: ListQueryOptions&#60;<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>&#62;, relations?: RelationPaths&#60;<a href='/reference/typescript-api/entities/collection#collection'>Collection</a>&#62;) => Promise&#60;<a href='/reference/typescript-api/common/paginated-list#paginatedlist'>PaginatedList</a>&#60;<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>&#62;&#62;`}   />


### create

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: CreateCollectionInput) => Promise&#60;Translated&#60;<a href='/reference/typescript-api/entities/collection#collection'>Collection</a>&#62;&#62;`}   />


### update

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: UpdateCollectionInput) => Promise&#60;Translated&#60;<a href='/reference/typescript-api/entities/collection#collection'>Collection</a>&#62;&#62;`}   />


### delete

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, id: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;DeletionResponse&#62;`}   />


### move

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: MoveCollectionInput) => Promise&#60;Translated&#60;<a href='/reference/typescript-api/entities/collection#collection'>Collection</a>&#62;&#62;`}   />

Moves a Collection by specifying the parent Collection ID, and an index representing the order amongst
its siblings.
### setApplyAllFiltersOnProductUpdates

<MemberInfo kind="method" type={`(applyAllFiltersOnProductUpdates: boolean) => `}  since="3.1.3"  />

By default, whenever product data is updated (as determined by subscribing to the
<a href='/reference/typescript-api/events/event-types#productevent'>ProductEvent</a> and <a href='/reference/typescript-api/events/event-types#productvariantevent'>ProductVariantEvent</a> events), the CollectionFilters are re-applied
to all Collections.

In certain scenarios, such as when a large number of products are updated at once due to
bulk data import, this can be inefficient. In such cases, you can disable this behaviour
for the duration of the import process by calling this method with `false`, and then
re-enable it by calling with `true`.

Afterward, you can call the `triggerApplyFiltersJob` method to manually re-apply the filters.
### triggerApplyFiltersJob

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, options?: { collectionIds?: <a href='/reference/typescript-api/common/id#id'>ID</a>[]; applyToChangedVariantsOnly?: boolean }) => `}  since="3.1.3"  />

Triggers the creation of an `apply-collection-filters` job which will cause the contents
of the specified collections to be re-evaluated against their filters.

If no `collectionIds` option is passed, then all collections will be re-evaluated.
### getCollectionProductVariantIds

<MemberInfo kind="method" type={`(collection: <a href='/reference/typescript-api/entities/collection#collection'>Collection</a>, ctx?: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => Promise&#60;<a href='/reference/typescript-api/common/id#id'>ID</a>[]&#62;`}   />


### assignCollectionsToChannel

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: AssignCollectionsToChannelInput) => Promise&#60;Array&#60;Translated&#60;<a href='/reference/typescript-api/entities/collection#collection'>Collection</a>&#62;&#62;&#62;`}   />

Assigns Collections to the specified Channel
### removeCollectionsFromChannel

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: RemoveCollectionsFromChannelInput) => Promise&#60;Array&#60;Translated&#60;<a href='/reference/typescript-api/entities/collection#collection'>Collection</a>&#62;&#62;&#62;`}   />

Remove Collections from the specified Channel


</div>


---

---
title: "CountryService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## CountryService

<GenerationInfo sourceFile="packages/core/src/service/services/country.service.ts" sourceLine="33" packageName="@vendure/core" />

Contains methods relating to <a href='/reference/typescript-api/entities/country#country'>Country</a> entities.

```ts title="Signature"
class CountryService {
    constructor(connection: TransactionalConnection, listQueryBuilder: ListQueryBuilder, translatableSaver: TranslatableSaver, eventBus: EventBus, translator: TranslatorService)
    findAll(ctx: RequestContext, options?: ListQueryOptions<Country>, relations: RelationPaths<Country> = []) => Promise<PaginatedList<Translated<Country>>>;
    findOne(ctx: RequestContext, countryId: ID, relations: RelationPaths<Country> = []) => Promise<Translated<Country> | undefined>;
    findAllAvailable(ctx: RequestContext) => Promise<Array<Translated<Country>>>;
    findOneByCode(ctx: RequestContext, countryCode: string) => Promise<Translated<Country>>;
    create(ctx: RequestContext, input: CreateCountryInput) => Promise<Translated<Country>>;
    update(ctx: RequestContext, input: UpdateCountryInput) => Promise<Translated<Country>>;
    delete(ctx: RequestContext, id: ID) => Promise<DeletionResponse>;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, listQueryBuilder: <a href='/reference/typescript-api/data-access/list-query-builder#listquerybuilder'>ListQueryBuilder</a>, translatableSaver: <a href='/reference/typescript-api/service-helpers/translatable-saver#translatablesaver'>TranslatableSaver</a>, eventBus: <a href='/reference/typescript-api/events/event-bus#eventbus'>EventBus</a>, translator: <a href='/reference/typescript-api/service-helpers/translator-service#translatorservice'>TranslatorService</a>) => CountryService`}   />


### findAll

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, options?: ListQueryOptions&#60;<a href='/reference/typescript-api/entities/country#country'>Country</a>&#62;, relations: RelationPaths&#60;<a href='/reference/typescript-api/entities/country#country'>Country</a>&#62; = []) => Promise&#60;<a href='/reference/typescript-api/common/paginated-list#paginatedlist'>PaginatedList</a>&#60;Translated&#60;<a href='/reference/typescript-api/entities/country#country'>Country</a>&#62;&#62;&#62;`}   />


### findOne

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, countryId: <a href='/reference/typescript-api/common/id#id'>ID</a>, relations: RelationPaths&#60;<a href='/reference/typescript-api/entities/country#country'>Country</a>&#62; = []) => Promise&#60;Translated&#60;<a href='/reference/typescript-api/entities/country#country'>Country</a>&#62; | undefined&#62;`}   />


### findAllAvailable

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => Promise&#60;Array&#60;Translated&#60;<a href='/reference/typescript-api/entities/country#country'>Country</a>&#62;&#62;&#62;`}   />

Returns an array of enabled Countries, intended for use in a public-facing (ie. Shop) API.
### findOneByCode

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, countryCode: string) => Promise&#60;Translated&#60;<a href='/reference/typescript-api/entities/country#country'>Country</a>&#62;&#62;`}   />

Returns a Country based on its ISO country code.
### create

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: CreateCountryInput) => Promise&#60;Translated&#60;<a href='/reference/typescript-api/entities/country#country'>Country</a>&#62;&#62;`}   />


### update

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: UpdateCountryInput) => Promise&#60;Translated&#60;<a href='/reference/typescript-api/entities/country#country'>Country</a>&#62;&#62;`}   />


### delete

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, id: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;DeletionResponse&#62;`}   />




</div>


---

---
title: "CustomerGroupService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## CustomerGroupService

<GenerationInfo sourceFile="packages/core/src/service/services/customer-group.service.ts" sourceLine="38" packageName="@vendure/core" />

Contains methods relating to <a href='/reference/typescript-api/entities/customer-group#customergroup'>CustomerGroup</a> entities.

```ts title="Signature"
class CustomerGroupService {
    constructor(connection: TransactionalConnection, listQueryBuilder: ListQueryBuilder, historyService: HistoryService, eventBus: EventBus, customFieldRelationService: CustomFieldRelationService)
    findAll(ctx: RequestContext, options?: CustomerGroupListOptions, relations: RelationPaths<CustomerGroup> = []) => Promise<PaginatedList<CustomerGroup>>;
    findOne(ctx: RequestContext, customerGroupId: ID, relations: RelationPaths<CustomerGroup> = []) => Promise<CustomerGroup | undefined>;
    getGroupCustomers(ctx: RequestContext, customerGroupId: ID, options?: CustomerListOptions) => Promise<PaginatedList<Customer>>;
    create(ctx: RequestContext, input: CreateCustomerGroupInput) => Promise<CustomerGroup>;
    update(ctx: RequestContext, input: UpdateCustomerGroupInput) => Promise<CustomerGroup>;
    delete(ctx: RequestContext, id: ID) => Promise<DeletionResponse>;
    addCustomersToGroup(ctx: RequestContext, input: MutationAddCustomersToGroupArgs) => Promise<CustomerGroup>;
    removeCustomersFromGroup(ctx: RequestContext, input: MutationRemoveCustomersFromGroupArgs) => Promise<CustomerGroup>;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, listQueryBuilder: <a href='/reference/typescript-api/data-access/list-query-builder#listquerybuilder'>ListQueryBuilder</a>, historyService: <a href='/reference/typescript-api/services/history-service#historyservice'>HistoryService</a>, eventBus: <a href='/reference/typescript-api/events/event-bus#eventbus'>EventBus</a>, customFieldRelationService: CustomFieldRelationService) => CustomerGroupService`}   />


### findAll

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, options?: CustomerGroupListOptions, relations: RelationPaths&#60;<a href='/reference/typescript-api/entities/customer-group#customergroup'>CustomerGroup</a>&#62; = []) => Promise&#60;<a href='/reference/typescript-api/common/paginated-list#paginatedlist'>PaginatedList</a>&#60;<a href='/reference/typescript-api/entities/customer-group#customergroup'>CustomerGroup</a>&#62;&#62;`}   />


### findOne

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, customerGroupId: <a href='/reference/typescript-api/common/id#id'>ID</a>, relations: RelationPaths&#60;<a href='/reference/typescript-api/entities/customer-group#customergroup'>CustomerGroup</a>&#62; = []) => Promise&#60;<a href='/reference/typescript-api/entities/customer-group#customergroup'>CustomerGroup</a> | undefined&#62;`}   />


### getGroupCustomers

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, customerGroupId: <a href='/reference/typescript-api/common/id#id'>ID</a>, options?: CustomerListOptions) => Promise&#60;<a href='/reference/typescript-api/common/paginated-list#paginatedlist'>PaginatedList</a>&#60;<a href='/reference/typescript-api/entities/customer#customer'>Customer</a>&#62;&#62;`}   />

Returns a <a href='/reference/typescript-api/common/paginated-list#paginatedlist'>PaginatedList</a> of all the Customers in the group.
### create

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: CreateCustomerGroupInput) => Promise&#60;<a href='/reference/typescript-api/entities/customer-group#customergroup'>CustomerGroup</a>&#62;`}   />


### update

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: UpdateCustomerGroupInput) => Promise&#60;<a href='/reference/typescript-api/entities/customer-group#customergroup'>CustomerGroup</a>&#62;`}   />


### delete

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, id: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;DeletionResponse&#62;`}   />


### addCustomersToGroup

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: MutationAddCustomersToGroupArgs) => Promise&#60;<a href='/reference/typescript-api/entities/customer-group#customergroup'>CustomerGroup</a>&#62;`}   />


### removeCustomersFromGroup

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: MutationRemoveCustomersFromGroupArgs) => Promise&#60;<a href='/reference/typescript-api/entities/customer-group#customergroup'>CustomerGroup</a>&#62;`}   />




</div>


---

---
title: "CustomerService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## CustomerService

<GenerationInfo sourceFile="packages/core/src/service/services/customer.service.ts" sourceLine="80" packageName="@vendure/core" />

Contains methods relating to <a href='/reference/typescript-api/entities/customer#customer'>Customer</a> entities.

```ts title="Signature"
class CustomerService {
    constructor(connection: TransactionalConnection, configService: ConfigService, userService: UserService, countryService: CountryService, listQueryBuilder: ListQueryBuilder, eventBus: EventBus, historyService: HistoryService, channelService: ChannelService, customFieldRelationService: CustomFieldRelationService, translator: TranslatorService)
    findAll(ctx: RequestContext, options: ListQueryOptions<Customer> | undefined, relations: RelationPaths<Customer> = []) => Promise<PaginatedList<Customer>>;
    findOne(ctx: RequestContext, id: ID, relations: RelationPaths<Customer> = []) => Promise<Customer | undefined>;
    findOneByUserId(ctx: RequestContext, userId: ID, filterOnChannel:  = true) => Promise<Customer | undefined>;
    findAddressesByCustomerId(ctx: RequestContext, customerId: ID) => Promise<Address[]>;
    getCustomerGroups(ctx: RequestContext, customerId: ID) => Promise<CustomerGroup[]>;
    create(ctx: RequestContext, input: CreateCustomerInput, password?: string) => Promise<ErrorResultUnion<CreateCustomerResult, Customer>>;
    update(ctx: RequestContext, input: UpdateCustomerShopInput & { id: ID }) => Promise<Customer>;
    update(ctx: RequestContext, input: UpdateCustomerInput) => Promise<ErrorResultUnion<UpdateCustomerResult, Customer>>;
    update(ctx: RequestContext, input: UpdateCustomerInput | (UpdateCustomerShopInput & { id: ID })) => Promise<ErrorResultUnion<UpdateCustomerResult, Customer>>;
    registerCustomerAccount(ctx: RequestContext, input: RegisterCustomerInput) => Promise<RegisterCustomerAccountResult | EmailAddressConflictError | PasswordValidationError>;
    refreshVerificationToken(ctx: RequestContext, emailAddress: string) => Promise<void>;
    verifyCustomerEmailAddress(ctx: RequestContext, verificationToken: string, password?: string) => Promise<ErrorResultUnion<VerifyCustomerAccountResult, Customer>>;
    requestPasswordReset(ctx: RequestContext, emailAddress: string) => Promise<void>;
    resetPassword(ctx: RequestContext, passwordResetToken: string, password: string) => Promise<
        User | PasswordResetTokenExpiredError | PasswordResetTokenInvalidError | PasswordValidationError
    >;
    requestUpdateEmailAddress(ctx: RequestContext, userId: ID, newEmailAddress: string) => Promise<boolean | EmailAddressConflictError>;
    updateEmailAddress(ctx: RequestContext, token: string) => Promise<boolean | IdentifierChangeTokenInvalidError | IdentifierChangeTokenExpiredError>;
    createOrUpdate(ctx: RequestContext, input: Partial<CreateCustomerInput> & { emailAddress: string }, errorOnExistingUser: boolean = false) => Promise<Customer | EmailAddressConflictError>;
    createAddress(ctx: RequestContext, customerId: ID, input: CreateAddressInput) => Promise<Address>;
    updateAddress(ctx: RequestContext, input: UpdateAddressInput) => Promise<Address>;
    deleteAddress(ctx: RequestContext, id: ID) => Promise<boolean>;
    softDelete(ctx: RequestContext, customerId: ID) => Promise<DeletionResponse>;
    createAddressesForNewCustomer(ctx: RequestContext, order: Order) => ;
    addNoteToCustomer(ctx: RequestContext, input: AddNoteToCustomerInput) => Promise<Customer>;
    updateCustomerNote(ctx: RequestContext, input: UpdateCustomerNoteInput) => Promise<HistoryEntry>;
    deleteCustomerNote(ctx: RequestContext, id: ID) => Promise<DeletionResponse>;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, configService: ConfigService, userService: <a href='/reference/typescript-api/services/user-service#userservice'>UserService</a>, countryService: <a href='/reference/typescript-api/services/country-service#countryservice'>CountryService</a>, listQueryBuilder: <a href='/reference/typescript-api/data-access/list-query-builder#listquerybuilder'>ListQueryBuilder</a>, eventBus: <a href='/reference/typescript-api/events/event-bus#eventbus'>EventBus</a>, historyService: <a href='/reference/typescript-api/services/history-service#historyservice'>HistoryService</a>, channelService: <a href='/reference/typescript-api/services/channel-service#channelservice'>ChannelService</a>, customFieldRelationService: CustomFieldRelationService, translator: <a href='/reference/typescript-api/service-helpers/translator-service#translatorservice'>TranslatorService</a>) => CustomerService`}   />


### findAll

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, options: ListQueryOptions&#60;<a href='/reference/typescript-api/entities/customer#customer'>Customer</a>&#62; | undefined, relations: RelationPaths&#60;<a href='/reference/typescript-api/entities/customer#customer'>Customer</a>&#62; = []) => Promise&#60;<a href='/reference/typescript-api/common/paginated-list#paginatedlist'>PaginatedList</a>&#60;<a href='/reference/typescript-api/entities/customer#customer'>Customer</a>&#62;&#62;`}   />


### findOne

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, id: <a href='/reference/typescript-api/common/id#id'>ID</a>, relations: RelationPaths&#60;<a href='/reference/typescript-api/entities/customer#customer'>Customer</a>&#62; = []) => Promise&#60;<a href='/reference/typescript-api/entities/customer#customer'>Customer</a> | undefined&#62;`}   />


### findOneByUserId

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, userId: <a href='/reference/typescript-api/common/id#id'>ID</a>, filterOnChannel:  = true) => Promise&#60;<a href='/reference/typescript-api/entities/customer#customer'>Customer</a> | undefined&#62;`}   />

Returns the Customer entity associated with the given userId, if one exists.
Setting `filterOnChannel` to `true` will limit the results to Customers which are assigned
to the current active Channel only.
### findAddressesByCustomerId

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, customerId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/entities/address#address'>Address</a>[]&#62;`}   />

Returns all <a href='/reference/typescript-api/entities/address#address'>Address</a> entities associated with the specified Customer.
### getCustomerGroups

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, customerId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/entities/customer-group#customergroup'>CustomerGroup</a>[]&#62;`}   />

Returns a list of all <a href='/reference/typescript-api/entities/customer-group#customergroup'>CustomerGroup</a> entities.
### create

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: CreateCustomerInput, password?: string) => Promise&#60;<a href='/reference/typescript-api/errors/error-result-union#errorresultunion'>ErrorResultUnion</a>&#60;CreateCustomerResult, <a href='/reference/typescript-api/entities/customer#customer'>Customer</a>&#62;&#62;`}   />

Creates a new Customer, including creation of a new User with the special `customer` Role.

If the `password` argument is specified, the Customer will be immediately verified. If not,
then an <a href='/reference/typescript-api/events/event-types#accountregistrationevent'>AccountRegistrationEvent</a> is published, so that the customer can have their
email address verified and set their password in a later step using the `verifyCustomerEmailAddress()`
method.

This method is intended to be used in admin-created Customer flows.
### update

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: UpdateCustomerShopInput &#38; { id: <a href='/reference/typescript-api/common/id#id'>ID</a> }) => Promise&#60;<a href='/reference/typescript-api/entities/customer#customer'>Customer</a>&#62;`}   />


### update

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: UpdateCustomerInput) => Promise&#60;<a href='/reference/typescript-api/errors/error-result-union#errorresultunion'>ErrorResultUnion</a>&#60;UpdateCustomerResult, <a href='/reference/typescript-api/entities/customer#customer'>Customer</a>&#62;&#62;`}   />


### update

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: UpdateCustomerInput | (UpdateCustomerShopInput &#38; { id: <a href='/reference/typescript-api/common/id#id'>ID</a> })) => Promise&#60;<a href='/reference/typescript-api/errors/error-result-union#errorresultunion'>ErrorResultUnion</a>&#60;UpdateCustomerResult, <a href='/reference/typescript-api/entities/customer#customer'>Customer</a>&#62;&#62;`}   />


### registerCustomerAccount

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: RegisterCustomerInput) => Promise&#60;RegisterCustomerAccountResult | EmailAddressConflictError | PasswordValidationError&#62;`}   />

Registers a new Customer account with the <a href='/reference/typescript-api/auth/native-authentication-strategy#nativeauthenticationstrategy'>NativeAuthenticationStrategy</a> and starts
the email verification flow (unless <a href='/reference/typescript-api/auth/auth-options#authoptions'>AuthOptions</a> `requireVerification` is set to `false`)
by publishing an <a href='/reference/typescript-api/events/event-types#accountregistrationevent'>AccountRegistrationEvent</a>.

This method is intended to be used in storefront Customer-creation flows.
### refreshVerificationToken

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, emailAddress: string) => Promise&#60;void&#62;`}   />

Refreshes a stale email address verification token by generating a new one and
publishing a <a href='/reference/typescript-api/events/event-types#accountregistrationevent'>AccountRegistrationEvent</a>.
### verifyCustomerEmailAddress

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, verificationToken: string, password?: string) => Promise&#60;<a href='/reference/typescript-api/errors/error-result-union#errorresultunion'>ErrorResultUnion</a>&#60;VerifyCustomerAccountResult, <a href='/reference/typescript-api/entities/customer#customer'>Customer</a>&#62;&#62;`}   />

Given a valid verification token which has been published in an <a href='/reference/typescript-api/events/event-types#accountregistrationevent'>AccountRegistrationEvent</a>, this
method is used to set the Customer as `verified` as part of the account registration flow.
### requestPasswordReset

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, emailAddress: string) => Promise&#60;void&#62;`}   />

Publishes a new <a href='/reference/typescript-api/events/event-types#passwordresetevent'>PasswordResetEvent</a> for the given email address. This event creates
a token which can be used in the `resetPassword()` method.
### resetPassword

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, passwordResetToken: string, password: string) => Promise&#60;         <a href='/reference/typescript-api/entities/user#user'>User</a> | PasswordResetTokenExpiredError | PasswordResetTokenInvalidError | PasswordValidationError     &#62;`}   />

Given a valid password reset token created by a call to the `requestPasswordReset()` method,
this method will change the Customer's password to that given as the `password` argument.
### requestUpdateEmailAddress

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, userId: <a href='/reference/typescript-api/common/id#id'>ID</a>, newEmailAddress: string) => Promise&#60;boolean | EmailAddressConflictError&#62;`}   />

Publishes a <a href='/reference/typescript-api/events/event-types#identifierchangerequestevent'>IdentifierChangeRequestEvent</a> for the given User. This event contains a token
which is then used in the `updateEmailAddress()` method to change the email address of the User &
Customer.
### updateEmailAddress

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, token: string) => Promise&#60;boolean | IdentifierChangeTokenInvalidError | IdentifierChangeTokenExpiredError&#62;`}   />

Given a valid email update token published in a <a href='/reference/typescript-api/events/event-types#identifierchangerequestevent'>IdentifierChangeRequestEvent</a>, this method
will update the Customer & User email address.
### createOrUpdate

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: Partial&#60;CreateCustomerInput&#62; &#38; { emailAddress: string }, errorOnExistingUser: boolean = false) => Promise&#60;<a href='/reference/typescript-api/entities/customer#customer'>Customer</a> | EmailAddressConflictError&#62;`}   />

For guest checkouts, we assume that a matching email address is the same customer.
### createAddress

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, customerId: <a href='/reference/typescript-api/common/id#id'>ID</a>, input: CreateAddressInput) => Promise&#60;<a href='/reference/typescript-api/entities/address#address'>Address</a>&#62;`}   />

Creates a new <a href='/reference/typescript-api/entities/address#address'>Address</a> for the given Customer.
### updateAddress

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: UpdateAddressInput) => Promise&#60;<a href='/reference/typescript-api/entities/address#address'>Address</a>&#62;`}   />


### deleteAddress

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, id: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;boolean&#62;`}   />


### softDelete

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, customerId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;DeletionResponse&#62;`}   />


### createAddressesForNewCustomer

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>) => `}   />

If the Customer associated with the given Order does not yet have any Addresses,
this method will create new Address(es) based on the Order's shipping & billing
addresses.
### addNoteToCustomer

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: AddNoteToCustomerInput) => Promise&#60;<a href='/reference/typescript-api/entities/customer#customer'>Customer</a>&#62;`}   />


### updateCustomerNote

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: UpdateCustomerNoteInput) => Promise&#60;<a href='/reference/typescript-api/entities/history-entry#historyentry'>HistoryEntry</a>&#62;`}   />


### deleteCustomerNote

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, id: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;DeletionResponse&#62;`}   />




</div>


---

---
title: "FacetService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## FacetService

<GenerationInfo sourceFile="packages/core/src/service/services/facet.service.ts" sourceLine="45" packageName="@vendure/core" />

Contains methods relating to <a href='/reference/typescript-api/entities/facet#facet'>Facet</a> entities.

```ts title="Signature"
class FacetService {
    constructor(connection: TransactionalConnection, facetValueService: FacetValueService, translatableSaver: TranslatableSaver, listQueryBuilder: ListQueryBuilder, configService: ConfigService, channelService: ChannelService, customFieldRelationService: CustomFieldRelationService, eventBus: EventBus, translator: TranslatorService, roleService: RoleService)
    findAll(ctx: RequestContext, options?: ListQueryOptions<Facet>, relations?: RelationPaths<Facet>) => Promise<PaginatedList<Translated<Facet>>>;
    findOne(ctx: RequestContext, facetId: ID, relations?: RelationPaths<Facet>) => Promise<Translated<Facet> | undefined>;
    findByCode(facetCode: string, lang: LanguageCode) => Promise<Translated<Facet> | undefined>;
    findByCode(ctx: RequestContext, facetCode: string, lang: LanguageCode) => Promise<Translated<Facet> | undefined>;
    findByCode(ctxOrFacetCode: RequestContext | string, facetCodeOrLang: string | LanguageCode, lang?: LanguageCode) => Promise<Translated<Facet> | undefined>;
    findByFacetValueId(ctx: RequestContext, id: ID) => Promise<Translated<Facet> | undefined>;
    create(ctx: RequestContext, input: CreateFacetInput) => Promise<Translated<Facet>>;
    update(ctx: RequestContext, input: UpdateFacetInput) => Promise<Translated<Facet>>;
    delete(ctx: RequestContext, id: ID, force: boolean = false) => Promise<DeletionResponse>;
    assignFacetsToChannel(ctx: RequestContext, input: AssignFacetsToChannelInput) => Promise<Array<Translated<Facet>>>;
    removeFacetsFromChannel(ctx: RequestContext, input: RemoveFacetsFromChannelInput) => Promise<Array<ErrorResultUnion<RemoveFacetFromChannelResult, Facet>>>;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, facetValueService: <a href='/reference/typescript-api/services/facet-value-service#facetvalueservice'>FacetValueService</a>, translatableSaver: <a href='/reference/typescript-api/service-helpers/translatable-saver#translatablesaver'>TranslatableSaver</a>, listQueryBuilder: <a href='/reference/typescript-api/data-access/list-query-builder#listquerybuilder'>ListQueryBuilder</a>, configService: ConfigService, channelService: <a href='/reference/typescript-api/services/channel-service#channelservice'>ChannelService</a>, customFieldRelationService: CustomFieldRelationService, eventBus: <a href='/reference/typescript-api/events/event-bus#eventbus'>EventBus</a>, translator: <a href='/reference/typescript-api/service-helpers/translator-service#translatorservice'>TranslatorService</a>, roleService: <a href='/reference/typescript-api/services/role-service#roleservice'>RoleService</a>) => FacetService`}   />


### findAll

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, options?: ListQueryOptions&#60;<a href='/reference/typescript-api/entities/facet#facet'>Facet</a>&#62;, relations?: RelationPaths&#60;<a href='/reference/typescript-api/entities/facet#facet'>Facet</a>&#62;) => Promise&#60;<a href='/reference/typescript-api/common/paginated-list#paginatedlist'>PaginatedList</a>&#60;Translated&#60;<a href='/reference/typescript-api/entities/facet#facet'>Facet</a>&#62;&#62;&#62;`}   />


### findOne

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, facetId: <a href='/reference/typescript-api/common/id#id'>ID</a>, relations?: RelationPaths&#60;<a href='/reference/typescript-api/entities/facet#facet'>Facet</a>&#62;) => Promise&#60;Translated&#60;<a href='/reference/typescript-api/entities/facet#facet'>Facet</a>&#62; | undefined&#62;`}   />


### findByCode

<MemberInfo kind="method" type={`(facetCode: string, lang: <a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a>) => Promise&#60;Translated&#60;<a href='/reference/typescript-api/entities/facet#facet'>Facet</a>&#62; | undefined&#62;`}   />


### findByCode

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, facetCode: string, lang: <a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a>) => Promise&#60;Translated&#60;<a href='/reference/typescript-api/entities/facet#facet'>Facet</a>&#62; | undefined&#62;`}   />


### findByCode

<MemberInfo kind="method" type={`(ctxOrFacetCode: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a> | string, facetCodeOrLang: string | <a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a>, lang?: <a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a>) => Promise&#60;Translated&#60;<a href='/reference/typescript-api/entities/facet#facet'>Facet</a>&#62; | undefined&#62;`}   />


### findByFacetValueId

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, id: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;Translated&#60;<a href='/reference/typescript-api/entities/facet#facet'>Facet</a>&#62; | undefined&#62;`}   />

Returns the Facet which contains the given FacetValue id.
### create

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: CreateFacetInput) => Promise&#60;Translated&#60;<a href='/reference/typescript-api/entities/facet#facet'>Facet</a>&#62;&#62;`}   />


### update

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: UpdateFacetInput) => Promise&#60;Translated&#60;<a href='/reference/typescript-api/entities/facet#facet'>Facet</a>&#62;&#62;`}   />


### delete

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, id: <a href='/reference/typescript-api/common/id#id'>ID</a>, force: boolean = false) => Promise&#60;DeletionResponse&#62;`}   />


### assignFacetsToChannel

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: AssignFacetsToChannelInput) => Promise&#60;Array&#60;Translated&#60;<a href='/reference/typescript-api/entities/facet#facet'>Facet</a>&#62;&#62;&#62;`}   />

Assigns Facets to the specified Channel
### removeFacetsFromChannel

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: RemoveFacetsFromChannelInput) => Promise&#60;Array&#60;<a href='/reference/typescript-api/errors/error-result-union#errorresultunion'>ErrorResultUnion</a>&#60;RemoveFacetFromChannelResult, <a href='/reference/typescript-api/entities/facet#facet'>Facet</a>&#62;&#62;&#62;`}   />

Remove Facets from the specified Channel


</div>


---

---
title: "FacetValueService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## FacetValueService

<GenerationInfo sourceFile="packages/core/src/service/services/facet-value.service.ts" sourceLine="40" packageName="@vendure/core" />

Contains methods relating to <a href='/reference/typescript-api/entities/facet-value#facetvalue'>FacetValue</a> entities.

```ts title="Signature"
class FacetValueService {
    constructor(connection: TransactionalConnection, translatableSaver: TranslatableSaver, configService: ConfigService, customFieldRelationService: CustomFieldRelationService, channelService: ChannelService, eventBus: EventBus, translator: TranslatorService, listQueryBuilder: ListQueryBuilder)
    findAll(lang: LanguageCode) => Promise<Array<Translated<FacetValue>>>;
    findAll(ctx: RequestContext, lang: LanguageCode) => Promise<Array<Translated<FacetValue>>>;
    findAll(ctxOrLang: RequestContext | LanguageCode, lang?: LanguageCode) => Promise<Array<Translated<FacetValue>>>;
    findAllList(ctx: RequestContext, options?: ListQueryOptions<FacetValue>, relations?: RelationPaths<FacetValue>) => Promise<PaginatedList<Translated<FacetValue>>>;
    findOne(ctx: RequestContext, id: ID) => Promise<Translated<FacetValue> | undefined>;
    findByIds(ctx: RequestContext, ids: ID[]) => Promise<Array<Translated<FacetValue>>>;
    findByFacetId(ctx: RequestContext, id: ID) => Promise<Array<Translated<FacetValue>>>;
    findByFacetIdList(ctx: RequestContext, id: ID, options?: ListQueryOptions<FacetValue>, relations?: RelationPaths<FacetValue>) => Promise<PaginatedList<Translated<FacetValue>>>;
    create(ctx: RequestContext, facet: Facet, input: CreateFacetValueInput | CreateFacetValueWithFacetInput) => Promise<Translated<FacetValue>>;
    update(ctx: RequestContext, input: UpdateFacetValueInput) => Promise<Translated<FacetValue>>;
    delete(ctx: RequestContext, id: ID, force: boolean = false) => Promise<DeletionResponse>;
    checkFacetValueUsage(ctx: RequestContext, facetValueIds: ID[], channelId?: ID) => Promise<{ productCount: number; variantCount: number }>;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, translatableSaver: <a href='/reference/typescript-api/service-helpers/translatable-saver#translatablesaver'>TranslatableSaver</a>, configService: ConfigService, customFieldRelationService: CustomFieldRelationService, channelService: <a href='/reference/typescript-api/services/channel-service#channelservice'>ChannelService</a>, eventBus: <a href='/reference/typescript-api/events/event-bus#eventbus'>EventBus</a>, translator: <a href='/reference/typescript-api/service-helpers/translator-service#translatorservice'>TranslatorService</a>, listQueryBuilder: <a href='/reference/typescript-api/data-access/list-query-builder#listquerybuilder'>ListQueryBuilder</a>) => FacetValueService`}   />


### findAll

<MemberInfo kind="method" type={`(lang: <a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a>) => Promise&#60;Array&#60;Translated&#60;<a href='/reference/typescript-api/entities/facet-value#facetvalue'>FacetValue</a>&#62;&#62;&#62;`}   />


### findAll

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, lang: <a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a>) => Promise&#60;Array&#60;Translated&#60;<a href='/reference/typescript-api/entities/facet-value#facetvalue'>FacetValue</a>&#62;&#62;&#62;`}   />


### findAll

<MemberInfo kind="method" type={`(ctxOrLang: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a> | <a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a>, lang?: <a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a>) => Promise&#60;Array&#60;Translated&#60;<a href='/reference/typescript-api/entities/facet-value#facetvalue'>FacetValue</a>&#62;&#62;&#62;`}   />


### findAllList

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, options?: ListQueryOptions&#60;<a href='/reference/typescript-api/entities/facet-value#facetvalue'>FacetValue</a>&#62;, relations?: RelationPaths&#60;<a href='/reference/typescript-api/entities/facet-value#facetvalue'>FacetValue</a>&#62;) => Promise&#60;<a href='/reference/typescript-api/common/paginated-list#paginatedlist'>PaginatedList</a>&#60;Translated&#60;<a href='/reference/typescript-api/entities/facet-value#facetvalue'>FacetValue</a>&#62;&#62;&#62;`}   />

Returns a PaginatedList of FacetValues.

TODO: in v2 this should replace the `findAll()` method.
A separate method was created just to avoid a breaking change in v1.9.
### findOne

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, id: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;Translated&#60;<a href='/reference/typescript-api/entities/facet-value#facetvalue'>FacetValue</a>&#62; | undefined&#62;`}   />


### findByIds

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, ids: <a href='/reference/typescript-api/common/id#id'>ID</a>[]) => Promise&#60;Array&#60;Translated&#60;<a href='/reference/typescript-api/entities/facet-value#facetvalue'>FacetValue</a>&#62;&#62;&#62;`}   />


### findByFacetId

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, id: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;Array&#60;Translated&#60;<a href='/reference/typescript-api/entities/facet-value#facetvalue'>FacetValue</a>&#62;&#62;&#62;`}   />

Returns all FacetValues belonging to the Facet with the given id.
### findByFacetIdList

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, id: <a href='/reference/typescript-api/common/id#id'>ID</a>, options?: ListQueryOptions&#60;<a href='/reference/typescript-api/entities/facet-value#facetvalue'>FacetValue</a>&#62;, relations?: RelationPaths&#60;<a href='/reference/typescript-api/entities/facet-value#facetvalue'>FacetValue</a>&#62;) => Promise&#60;<a href='/reference/typescript-api/common/paginated-list#paginatedlist'>PaginatedList</a>&#60;Translated&#60;<a href='/reference/typescript-api/entities/facet-value#facetvalue'>FacetValue</a>&#62;&#62;&#62;`}   />

Returns all FacetValues belonging to the Facet with the given id.
### create

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, facet: <a href='/reference/typescript-api/entities/facet#facet'>Facet</a>, input: CreateFacetValueInput | CreateFacetValueWithFacetInput) => Promise&#60;Translated&#60;<a href='/reference/typescript-api/entities/facet-value#facetvalue'>FacetValue</a>&#62;&#62;`}   />


### update

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: UpdateFacetValueInput) => Promise&#60;Translated&#60;<a href='/reference/typescript-api/entities/facet-value#facetvalue'>FacetValue</a>&#62;&#62;`}   />


### delete

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, id: <a href='/reference/typescript-api/common/id#id'>ID</a>, force: boolean = false) => Promise&#60;DeletionResponse&#62;`}   />


### checkFacetValueUsage

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, facetValueIds: <a href='/reference/typescript-api/common/id#id'>ID</a>[], channelId?: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;{ productCount: number; variantCount: number }&#62;`}   />

Checks for usage of the given FacetValues in any Products or Variants, and returns the counts.


</div>


---

---
title: "FulfillmentService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## FulfillmentService

<GenerationInfo sourceFile="packages/core/src/service/services/fulfillment.service.ts" sourceLine="34" packageName="@vendure/core" />

Contains methods relating to <a href='/reference/typescript-api/entities/fulfillment#fulfillment'>Fulfillment</a> entities.

```ts title="Signature"
class FulfillmentService {
    constructor(connection: TransactionalConnection, fulfillmentStateMachine: FulfillmentStateMachine, eventBus: EventBus, configService: ConfigService, customFieldRelationService: CustomFieldRelationService)
    create(ctx: RequestContext, orders: Order[], lines: OrderLineInput[], handler: ConfigurableOperationInput) => Promise<Fulfillment | InvalidFulfillmentHandlerError | CreateFulfillmentError>;
    getFulfillmentLines(ctx: RequestContext, id: ID) => Promise<FulfillmentLine[]>;
    getFulfillmentsLinesForOrderLine(ctx: RequestContext, orderLineId: ID, relations: RelationPaths<FulfillmentLine> = []) => Promise<FulfillmentLine[]>;
    transitionToState(ctx: RequestContext, fulfillmentId: ID, state: FulfillmentState) => Promise<
        | {
              fulfillment: Fulfillment;
              orders: Order[];
              fromState: FulfillmentState;
              toState: FulfillmentState;
          }
        | FulfillmentStateTransitionError
    >;
    getNextStates(fulfillment: Fulfillment) => readonly FulfillmentState[];
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, fulfillmentStateMachine: FulfillmentStateMachine, eventBus: <a href='/reference/typescript-api/events/event-bus#eventbus'>EventBus</a>, configService: ConfigService, customFieldRelationService: CustomFieldRelationService) => FulfillmentService`}   />


### create

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, orders: <a href='/reference/typescript-api/entities/order#order'>Order</a>[], lines: OrderLineInput[], handler: ConfigurableOperationInput) => Promise&#60;<a href='/reference/typescript-api/entities/fulfillment#fulfillment'>Fulfillment</a> | InvalidFulfillmentHandlerError | CreateFulfillmentError&#62;`}   />

Creates a new Fulfillment for the given Orders and OrderItems, using the specified
<a href='/reference/typescript-api/fulfillment/fulfillment-handler#fulfillmenthandler'>FulfillmentHandler</a>.
### getFulfillmentLines

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, id: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/entities/order-line-reference#fulfillmentline'>FulfillmentLine</a>[]&#62;`}   />


### getFulfillmentsLinesForOrderLine

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, orderLineId: <a href='/reference/typescript-api/common/id#id'>ID</a>, relations: RelationPaths&#60;<a href='/reference/typescript-api/entities/order-line-reference#fulfillmentline'>FulfillmentLine</a>&#62; = []) => Promise&#60;<a href='/reference/typescript-api/entities/order-line-reference#fulfillmentline'>FulfillmentLine</a>[]&#62;`}   />


### transitionToState

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, fulfillmentId: <a href='/reference/typescript-api/common/id#id'>ID</a>, state: <a href='/reference/typescript-api/fulfillment/fulfillment-state#fulfillmentstate'>FulfillmentState</a>) => Promise&#60;         | {               fulfillment: <a href='/reference/typescript-api/entities/fulfillment#fulfillment'>Fulfillment</a>;               orders: <a href='/reference/typescript-api/entities/order#order'>Order</a>[];               fromState: <a href='/reference/typescript-api/fulfillment/fulfillment-state#fulfillmentstate'>FulfillmentState</a>;               toState: <a href='/reference/typescript-api/fulfillment/fulfillment-state#fulfillmentstate'>FulfillmentState</a>;           }         | FulfillmentStateTransitionError     &#62;`}   />

Transitions the specified Fulfillment to a new state and upon successful transition
publishes a <a href='/reference/typescript-api/events/event-types#fulfillmentstatetransitionevent'>FulfillmentStateTransitionEvent</a>.
### getNextStates

<MemberInfo kind="method" type={`(fulfillment: <a href='/reference/typescript-api/entities/fulfillment#fulfillment'>Fulfillment</a>) => readonly <a href='/reference/typescript-api/fulfillment/fulfillment-state#fulfillmentstate'>FulfillmentState</a>[]`}   />

Returns an array of the next valid states for the Fulfillment.


</div>


---

---
title: "GlobalSettingsService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## GlobalSettingsService

<GenerationInfo sourceFile="packages/core/src/service/services/global-settings.service.ts" sourceLine="23" packageName="@vendure/core" />

Contains methods relating to the <a href='/reference/typescript-api/entities/global-settings#globalsettings'>GlobalSettings</a> entity.

```ts title="Signature"
class GlobalSettingsService {
    constructor(connection: TransactionalConnection, configService: ConfigService, customFieldRelationService: CustomFieldRelationService, eventBus: EventBus, requestCache: RequestContextCacheService)
    getSettings(ctx: RequestContext) => Promise<GlobalSettings>;
    updateSettings(ctx: RequestContext, input: UpdateGlobalSettingsInput) => Promise<GlobalSettings>;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, configService: ConfigService, customFieldRelationService: CustomFieldRelationService, eventBus: <a href='/reference/typescript-api/events/event-bus#eventbus'>EventBus</a>, requestCache: <a href='/reference/typescript-api/cache/request-context-cache-service#requestcontextcacheservice'>RequestContextCacheService</a>) => GlobalSettingsService`}   />


### getSettings

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => Promise&#60;<a href='/reference/typescript-api/entities/global-settings#globalsettings'>GlobalSettings</a>&#62;`}   />

Returns the GlobalSettings entity.
### updateSettings

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: UpdateGlobalSettingsInput) => Promise&#60;<a href='/reference/typescript-api/entities/global-settings#globalsettings'>GlobalSettings</a>&#62;`}   />




</div>


---

---
title: "HistoryService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## HistoryService

<GenerationInfo sourceFile="packages/core/src/service/services/history.service.ts" sourceLine="248" packageName="@vendure/core" />

Contains methods relating to <a href='/reference/typescript-api/entities/history-entry#historyentry'>HistoryEntry</a> entities. Histories are timelines of actions
related to a particular Customer or Order, recording significant events such as creation, state changes,
notes, etc.

## Custom History Entry Types

Since Vendure v1.9.0, it is possible to define custom HistoryEntry types.

Let's take an example where we have some Customers who are businesses. We want to verify their
tax ID in order to allow them wholesale rates. As part of this verification, we'd like to add
an entry into the Customer's history with data about the tax ID verification.

First of all we'd extend the GraphQL `HistoryEntryType` enum for our new type as part of a plugin

*Example*

```ts
import { PluginCommonModule, VendurePlugin } from '@vendure/core';
import { VerificationService } from './verification.service';

@VendurePlugin({
  imports: [PluginCommonModule],
  adminApiExtensions: {
    schema: gql`
      extend enum HistoryEntryType {
        CUSTOMER_TAX_ID_VERIFICATION
      }
    `,
  },
  providers: [VerificationService],
})
export class TaxIDVerificationPlugin {}
```

Next we need to create a TypeScript type definition file where we extend the `CustomerHistoryEntryData` interface. This is done
via TypeScript's [declaration merging](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#merging-interfaces)
and [ambient modules](https://www.typescriptlang.org/docs/handbook/modules.html#ambient-modules) features.

*Example*

```ts
// types.ts
import { CustomerHistoryEntryData } from '@vendure/core';

export const CUSTOMER_TAX_ID_VERIFICATION = 'CUSTOMER_TAX_ID_VERIFICATION';

declare module '@vendure/core' {
  interface CustomerHistoryEntryData {
    [CUSTOMER_TAX_ID_VERIFICATION]: {
      taxId: string;
      valid: boolean;
      name?: string;
      address?: string;
    };
  }
}
```

Note: it works exactly the same way if we wanted to add a custom type for Order history, except in that case we'd extend the
`OrderHistoryEntryData` interface instead.

Now that we have our types set up, we can use the HistoryService to add a new HistoryEntry in a type-safe manner:

*Example*

```ts
// verification.service.ts
import { Injectable } from '@nestjs/common';
import { RequestContext } from '@vendure/core';
import { CUSTOMER_TAX_ID_VERIFICATION } from './types';

@Injectable()
export class VerificationService {
  constructor(private historyService: HistoryService) {}

  async verifyTaxId(ctx: RequestContext, customerId: ID, taxId: string) {
    const result = await someTaxIdCheckingService(taxId);

    await this.historyService.createHistoryEntryForCustomer({
      customerId,
      ctx,
      type: CUSTOMER_TAX_ID_VERIFICATION,
      data: {
        taxId,
        valid: result.isValid,
        name: result.companyName,
        address: result.registeredAddress,
      },
    });
  }
}
```
:::info
It is also possible to define a UI component to display custom history entry types. See the
[Custom History Timeline Components guide](/guides/extending-the-admin-ui/custom-timeline-components/).
:::

```ts title="Signature"
class HistoryService {
    constructor(connection: TransactionalConnection, administratorService: AdministratorService, listQueryBuilder: ListQueryBuilder, eventBus: EventBus)
    getHistoryForOrder(ctx: RequestContext, orderId: ID, publicOnly: boolean, options?: HistoryEntryListOptions) => Promise<PaginatedList<OrderHistoryEntry>>;
    createHistoryEntryForOrder(args: CreateOrderHistoryEntryArgs<T>, isPublic:  = true) => Promise<OrderHistoryEntry>;
    getHistoryForCustomer(ctx: RequestContext, customerId: ID, publicOnly: boolean, options?: HistoryEntryListOptions) => Promise<PaginatedList<CustomerHistoryEntry>>;
    createHistoryEntryForCustomer(args: CreateCustomerHistoryEntryArgs<T>, isPublic:  = false) => Promise<CustomerHistoryEntry>;
    updateOrderHistoryEntry(ctx: RequestContext, args: UpdateOrderHistoryEntryArgs<T>) => ;
    deleteOrderHistoryEntry(ctx: RequestContext, id: ID) => Promise<void>;
    updateCustomerHistoryEntry(ctx: RequestContext, args: UpdateCustomerHistoryEntryArgs<T>) => ;
    deleteCustomerHistoryEntry(ctx: RequestContext, id: ID) => Promise<void>;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, administratorService: <a href='/reference/typescript-api/services/administrator-service#administratorservice'>AdministratorService</a>, listQueryBuilder: <a href='/reference/typescript-api/data-access/list-query-builder#listquerybuilder'>ListQueryBuilder</a>, eventBus: <a href='/reference/typescript-api/events/event-bus#eventbus'>EventBus</a>) => HistoryService`}   />


### getHistoryForOrder

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, orderId: <a href='/reference/typescript-api/common/id#id'>ID</a>, publicOnly: boolean, options?: HistoryEntryListOptions) => Promise&#60;<a href='/reference/typescript-api/common/paginated-list#paginatedlist'>PaginatedList</a>&#60;<a href='/reference/typescript-api/entities/order-history-entry#orderhistoryentry'>OrderHistoryEntry</a>&#62;&#62;`}   />


### createHistoryEntryForOrder

<MemberInfo kind="method" type={`(args: CreateOrderHistoryEntryArgs&#60;T&#62;, isPublic:  = true) => Promise&#60;<a href='/reference/typescript-api/entities/order-history-entry#orderhistoryentry'>OrderHistoryEntry</a>&#62;`}   />


### getHistoryForCustomer

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, customerId: <a href='/reference/typescript-api/common/id#id'>ID</a>, publicOnly: boolean, options?: HistoryEntryListOptions) => Promise&#60;<a href='/reference/typescript-api/common/paginated-list#paginatedlist'>PaginatedList</a>&#60;<a href='/reference/typescript-api/entities/customer-history-entry#customerhistoryentry'>CustomerHistoryEntry</a>&#62;&#62;`}   />


### createHistoryEntryForCustomer

<MemberInfo kind="method" type={`(args: CreateCustomerHistoryEntryArgs&#60;T&#62;, isPublic:  = false) => Promise&#60;<a href='/reference/typescript-api/entities/customer-history-entry#customerhistoryentry'>CustomerHistoryEntry</a>&#62;`}   />


### updateOrderHistoryEntry

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, args: UpdateOrderHistoryEntryArgs&#60;T&#62;) => `}   />


### deleteOrderHistoryEntry

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, id: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;void&#62;`}   />


### updateCustomerHistoryEntry

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, args: UpdateCustomerHistoryEntryArgs&#60;T&#62;) => `}   />


### deleteCustomerHistoryEntry

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, id: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;void&#62;`}   />




</div>


---

---
title: "Services"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "InitializerService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## InitializerService

<GenerationInfo sourceFile="packages/core/src/service/initializer.service.ts" sourceLine="26" packageName="@vendure/core" />

Only used internally to run the various service init methods in the correct
sequence on bootstrap.

```ts title="Signature"
class InitializerService {
    constructor(connection: TransactionalConnection, zoneService: ZoneService, channelService: ChannelService, roleService: RoleService, administratorService: AdministratorService, shippingMethodService: ShippingMethodService, globalSettingsService: GlobalSettingsService, taxRateService: TaxRateService, sellerService: SellerService, eventBus: EventBus, stockLocationService: StockLocationService)
    onModuleInit() => ;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, zoneService: <a href='/reference/typescript-api/services/zone-service#zoneservice'>ZoneService</a>, channelService: <a href='/reference/typescript-api/services/channel-service#channelservice'>ChannelService</a>, roleService: <a href='/reference/typescript-api/services/role-service#roleservice'>RoleService</a>, administratorService: <a href='/reference/typescript-api/services/administrator-service#administratorservice'>AdministratorService</a>, shippingMethodService: <a href='/reference/typescript-api/services/shipping-method-service#shippingmethodservice'>ShippingMethodService</a>, globalSettingsService: <a href='/reference/typescript-api/services/global-settings-service#globalsettingsservice'>GlobalSettingsService</a>, taxRateService: <a href='/reference/typescript-api/services/tax-rate-service#taxrateservice'>TaxRateService</a>, sellerService: <a href='/reference/typescript-api/services/seller-service#sellerservice'>SellerService</a>, eventBus: <a href='/reference/typescript-api/events/event-bus#eventbus'>EventBus</a>, stockLocationService: StockLocationService) => InitializerService`}   />


### onModuleInit

<MemberInfo kind="method" type={`() => `}   />




</div>


---

---
title: "OrderService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## OrderService

<GenerationInfo sourceFile="packages/core/src/service/services/order.service.ts" sourceLine="140" packageName="@vendure/core" />

Contains methods relating to <a href='/reference/typescript-api/entities/order#order'>Order</a> entities.

```ts title="Signature"
class OrderService {
    constructor(connection: TransactionalConnection, configService: ConfigService, productVariantService: ProductVariantService, customerService: CustomerService, countryService: CountryService, orderCalculator: OrderCalculator, shippingCalculator: ShippingCalculator, orderStateMachine: OrderStateMachine, orderMerger: OrderMerger, paymentService: PaymentService, paymentMethodService: PaymentMethodService, fulfillmentService: FulfillmentService, listQueryBuilder: ListQueryBuilder, refundStateMachine: RefundStateMachine, historyService: HistoryService, promotionService: PromotionService, eventBus: EventBus, channelService: ChannelService, orderModifier: OrderModifier, customFieldRelationService: CustomFieldRelationService, requestCache: RequestContextCacheService, translator: TranslatorService, stockLevelService: StockLevelService)
    getOrderProcessStates() => OrderProcessState[];
    findAll(ctx: RequestContext, options?: OrderListOptions, relations?: RelationPaths<Order>) => Promise<PaginatedList<Order>>;
    findOne(ctx: RequestContext, orderId: ID, relations?: RelationPaths<Order>) => Promise<Order | undefined>;
    findOneByCode(ctx: RequestContext, orderCode: string, relations?: RelationPaths<Order>) => Promise<Order | undefined>;
    findOneByOrderLineId(ctx: RequestContext, orderLineId: ID, relations?: RelationPaths<Order>) => Promise<Order | undefined>;
    findByCustomerId(ctx: RequestContext, customerId: ID, options?: ListQueryOptions<Order>, relations?: RelationPaths<Order>) => Promise<PaginatedList<Order>>;
    getOrderPayments(ctx: RequestContext, orderId: ID) => Promise<Payment[]>;
    getOrderModifications(ctx: RequestContext, orderId: ID) => Promise<OrderModification[]>;
    getPaymentRefunds(ctx: RequestContext, paymentId: ID) => Promise<Refund[]>;
    getSellerOrders(ctx: RequestContext, order: Order) => Promise<Order[]>;
    getAggregateOrder(ctx: RequestContext, order: Order) => Promise<Order | undefined>;
    getOrderChannels(ctx: RequestContext, order: Order) => Promise<Channel[]>;
    getActiveOrderForUser(ctx: RequestContext, userId: ID) => Promise<Order | undefined>;
    create(ctx: RequestContext, userId?: ID) => Promise<Order>;
    createDraft(ctx: RequestContext) => ;
    updateCustomFields(ctx: RequestContext, orderId: ID, customFields: any) => ;
    updateOrderCustomer(ctx: RequestContext, { customerId, orderId, note }: SetOrderCustomerInput) => ;
    addItemToOrder(ctx: RequestContext, orderId: ID, productVariantId: ID, quantity: number, customFields?: { [key: string]: any }, relations?: RelationPaths<Order>) => Promise<ErrorResultUnion<UpdateOrderItemsResult, Order>>;
    addItemsToOrder(ctx: RequestContext, orderId: ID, items: Array<{
            productVariantId: ID;
            quantity: number;
            customFields?: { [key: string]: any };
        }>, relations?: RelationPaths<Order>) => Promise<{ order: Order; errorResults: Array<JustErrorResults<UpdateOrderItemsResult>> }>;
    adjustOrderLine(ctx: RequestContext, orderId: ID, orderLineId: ID, quantity: number, customFields?: { [key: string]: any }, relations?: RelationPaths<Order>) => Promise<ErrorResultUnion<UpdateOrderItemsResult, Order>>;
    adjustOrderLines(ctx: RequestContext, orderId: ID, lines: Array<{ orderLineId: ID; quantity: number; customFields?: { [key: string]: any } }>, relations?: RelationPaths<Order>) => Promise<{ order: Order; errorResults: Array<JustErrorResults<UpdateOrderItemsResult>> }>;
    removeItemFromOrder(ctx: RequestContext, orderId: ID, orderLineId: ID) => Promise<ErrorResultUnion<RemoveOrderItemsResult, Order>>;
    removeItemsFromOrder(ctx: RequestContext, orderId: ID, orderLineIds: ID[]) => Promise<ErrorResultUnion<RemoveOrderItemsResult, Order>>;
    removeAllItemsFromOrder(ctx: RequestContext, orderId: ID) => Promise<ErrorResultUnion<RemoveOrderItemsResult, Order>>;
    addSurchargeToOrder(ctx: RequestContext, orderId: ID, surchargeInput: Partial<Omit<Surcharge, 'id' | 'createdAt' | 'updatedAt' | 'order'>>) => Promise<Order>;
    removeSurchargeFromOrder(ctx: RequestContext, orderId: ID, surchargeId: ID) => Promise<Order>;
    applyCouponCode(ctx: RequestContext, orderId: ID, couponCode: string) => Promise<ErrorResultUnion<ApplyCouponCodeResult, Order>>;
    removeCouponCode(ctx: RequestContext, orderId: ID, couponCode: string) => ;
    getOrderPromotions(ctx: RequestContext, orderId: ID) => Promise<Promotion[]>;
    getNextOrderStates(order: Order) => readonly OrderState[];
    setShippingAddress(ctx: RequestContext, orderId: ID, input: CreateAddressInput) => Promise<Order>;
    setBillingAddress(ctx: RequestContext, orderId: ID, input: CreateAddressInput) => Promise<Order>;
    unsetShippingAddress(ctx: RequestContext, orderId: ID) => Promise<Order>;
    unsetBillingAddress(ctx: RequestContext, orderId: ID) => Promise<Order>;
    getEligibleShippingMethods(ctx: RequestContext, orderId: ID) => Promise<ShippingMethodQuote[]>;
    getEligiblePaymentMethods(ctx: RequestContext, orderId: ID) => Promise<PaymentMethodQuote[]>;
    setShippingMethod(ctx: RequestContext, orderId: ID, shippingMethodIds: ID[]) => Promise<ErrorResultUnion<SetOrderShippingMethodResult, Order>>;
    transitionToState(ctx: RequestContext, orderId: ID, state: OrderState) => Promise<Order | OrderStateTransitionError>;
    transitionFulfillmentToState(ctx: RequestContext, fulfillmentId: ID, state: FulfillmentState) => Promise<Fulfillment | FulfillmentStateTransitionError>;
    transitionRefundToState(ctx: RequestContext, refundId: ID, state: RefundState, transactionId?: string) => Promise<Refund | RefundStateTransitionError>;
    modifyOrder(ctx: RequestContext, input: ModifyOrderInput) => Promise<ErrorResultUnion<ModifyOrderResult, Order>>;
    transitionPaymentToState(ctx: RequestContext, paymentId: ID, state: PaymentState) => Promise<ErrorResultUnion<TransitionPaymentToStateResult, Payment>>;
    addPaymentToOrder(ctx: RequestContext, orderId: ID, input: PaymentInput) => Promise<ErrorResultUnion<AddPaymentToOrderResult, Order>>;
    addManualPaymentToOrder(ctx: RequestContext, input: ManualPaymentInput) => Promise<ErrorResultUnion<AddManualPaymentToOrderResult, Order>>;
    settlePayment(ctx: RequestContext, paymentId: ID) => Promise<ErrorResultUnion<SettlePaymentResult, Payment>>;
    cancelPayment(ctx: RequestContext, paymentId: ID) => Promise<ErrorResultUnion<CancelPaymentResult, Payment>>;
    createFulfillment(ctx: RequestContext, input: FulfillOrderInput) => Promise<ErrorResultUnion<AddFulfillmentToOrderResult, Fulfillment>>;
    getOrderFulfillments(ctx: RequestContext, order: Order) => Promise<Fulfillment[]>;
    getOrderSurcharges(ctx: RequestContext, orderId: ID) => Promise<Surcharge[]>;
    cancelOrder(ctx: RequestContext, input: CancelOrderInput) => Promise<ErrorResultUnion<CancelOrderResult, Order>>;
    refundOrder(ctx: RequestContext, input: RefundOrderInput) => Promise<ErrorResultUnion<RefundOrderResult, Refund>>;
    settleRefund(ctx: RequestContext, input: SettleRefundInput) => Promise<Refund>;
    addCustomerToOrder(ctx: RequestContext, orderIdOrOrder: ID | Order, customer: Customer) => Promise<Order>;
    addNoteToOrder(ctx: RequestContext, input: AddNoteToOrderInput) => Promise<Order>;
    updateOrderNote(ctx: RequestContext, input: UpdateOrderNoteInput) => Promise<HistoryEntry>;
    deleteOrderNote(ctx: RequestContext, id: ID) => Promise<DeletionResponse>;
    deleteOrder(ctx: RequestContext, orderOrId: ID | Order) => ;
    mergeOrders(ctx: RequestContext, user: User, guestOrder?: Order, existingOrder?: Order) => Promise<Order | undefined>;
    applyPriceAdjustments(ctx: RequestContext, order: Order, updatedOrderLines?: OrderLine[], relations?: RelationPaths<Order>) => Promise<Order>;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, configService: ConfigService, productVariantService: <a href='/reference/typescript-api/services/product-variant-service#productvariantservice'>ProductVariantService</a>, customerService: <a href='/reference/typescript-api/services/customer-service#customerservice'>CustomerService</a>, countryService: <a href='/reference/typescript-api/services/country-service#countryservice'>CountryService</a>, orderCalculator: <a href='/reference/typescript-api/service-helpers/order-calculator#ordercalculator'>OrderCalculator</a>, shippingCalculator: <a href='/reference/typescript-api/shipping/shipping-calculator#shippingcalculator'>ShippingCalculator</a>, orderStateMachine: OrderStateMachine, orderMerger: OrderMerger, paymentService: <a href='/reference/typescript-api/services/payment-service#paymentservice'>PaymentService</a>, paymentMethodService: <a href='/reference/typescript-api/services/payment-method-service#paymentmethodservice'>PaymentMethodService</a>, fulfillmentService: <a href='/reference/typescript-api/services/fulfillment-service#fulfillmentservice'>FulfillmentService</a>, listQueryBuilder: <a href='/reference/typescript-api/data-access/list-query-builder#listquerybuilder'>ListQueryBuilder</a>, refundStateMachine: RefundStateMachine, historyService: <a href='/reference/typescript-api/services/history-service#historyservice'>HistoryService</a>, promotionService: <a href='/reference/typescript-api/services/promotion-service#promotionservice'>PromotionService</a>, eventBus: <a href='/reference/typescript-api/events/event-bus#eventbus'>EventBus</a>, channelService: <a href='/reference/typescript-api/services/channel-service#channelservice'>ChannelService</a>, orderModifier: <a href='/reference/typescript-api/service-helpers/order-modifier#ordermodifier'>OrderModifier</a>, customFieldRelationService: CustomFieldRelationService, requestCache: <a href='/reference/typescript-api/cache/request-context-cache-service#requestcontextcacheservice'>RequestContextCacheService</a>, translator: <a href='/reference/typescript-api/service-helpers/translator-service#translatorservice'>TranslatorService</a>, stockLevelService: <a href='/reference/typescript-api/services/stock-level-service#stocklevelservice'>StockLevelService</a>) => OrderService`}   />


### getOrderProcessStates

<MemberInfo kind="method" type={`() => OrderProcessState[]`}   />

Returns an array of all the configured states and transitions of the order process. This is
based on the default order process plus all configured <a href='/reference/typescript-api/orders/order-process#orderprocess'>OrderProcess</a> objects
defined in the <a href='/reference/typescript-api/orders/order-options#orderoptions'>OrderOptions</a> `process` array.
### findAll

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, options?: OrderListOptions, relations?: RelationPaths&#60;<a href='/reference/typescript-api/entities/order#order'>Order</a>&#62;) => Promise&#60;<a href='/reference/typescript-api/common/paginated-list#paginatedlist'>PaginatedList</a>&#60;<a href='/reference/typescript-api/entities/order#order'>Order</a>&#62;&#62;`}   />


### findOne

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, orderId: <a href='/reference/typescript-api/common/id#id'>ID</a>, relations?: RelationPaths&#60;<a href='/reference/typescript-api/entities/order#order'>Order</a>&#62;) => Promise&#60;<a href='/reference/typescript-api/entities/order#order'>Order</a> | undefined&#62;`}   />


### findOneByCode

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, orderCode: string, relations?: RelationPaths&#60;<a href='/reference/typescript-api/entities/order#order'>Order</a>&#62;) => Promise&#60;<a href='/reference/typescript-api/entities/order#order'>Order</a> | undefined&#62;`}   />


### findOneByOrderLineId

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, orderLineId: <a href='/reference/typescript-api/common/id#id'>ID</a>, relations?: RelationPaths&#60;<a href='/reference/typescript-api/entities/order#order'>Order</a>&#62;) => Promise&#60;<a href='/reference/typescript-api/entities/order#order'>Order</a> | undefined&#62;`}   />


### findByCustomerId

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, customerId: <a href='/reference/typescript-api/common/id#id'>ID</a>, options?: ListQueryOptions&#60;<a href='/reference/typescript-api/entities/order#order'>Order</a>&#62;, relations?: RelationPaths&#60;<a href='/reference/typescript-api/entities/order#order'>Order</a>&#62;) => Promise&#60;<a href='/reference/typescript-api/common/paginated-list#paginatedlist'>PaginatedList</a>&#60;<a href='/reference/typescript-api/entities/order#order'>Order</a>&#62;&#62;`}   />


### getOrderPayments

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, orderId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/entities/payment#payment'>Payment</a>[]&#62;`}   />

Returns all <a href='/reference/typescript-api/entities/payment#payment'>Payment</a> entities associated with the Order.
### getOrderModifications

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, orderId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/entities/order-modification#ordermodification'>OrderModification</a>[]&#62;`}   />

Returns an array of any <a href='/reference/typescript-api/entities/order-modification#ordermodification'>OrderModification</a> entities associated with the Order.
### getPaymentRefunds

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, paymentId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/entities/refund#refund'>Refund</a>[]&#62;`}   />

Returns any <a href='/reference/typescript-api/entities/refund#refund'>Refund</a>s associated with a <a href='/reference/typescript-api/entities/payment#payment'>Payment</a>.
### getSellerOrders

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>) => Promise&#60;<a href='/reference/typescript-api/entities/order#order'>Order</a>[]&#62;`}   />


### getAggregateOrder

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>) => Promise&#60;<a href='/reference/typescript-api/entities/order#order'>Order</a> | undefined&#62;`}   />


### getOrderChannels

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>) => Promise&#60;<a href='/reference/typescript-api/entities/channel#channel'>Channel</a>[]&#62;`}   />


### getActiveOrderForUser

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, userId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/entities/order#order'>Order</a> | undefined&#62;`}   />

Returns any Order associated with the specified User's Customer account
that is still in the `active` state.
### create

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, userId?: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/entities/order#order'>Order</a>&#62;`}   />

Creates a new, empty Order. If a `userId` is passed, the Order will get associated with that
User's Customer account.
### createDraft

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => `}   />


### updateCustomFields

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, orderId: <a href='/reference/typescript-api/common/id#id'>ID</a>, customFields: any) => `}   />

Updates the custom fields of an Order.
### updateOrderCustomer

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, { customerId, orderId, note }: SetOrderCustomerInput) => `}  since="2.2.0"  />

Updates the Customer which is assigned to a given Order. The target Customer must be assigned to the same
Channels as the Order, otherwise an error will be thrown.
### addItemToOrder

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, orderId: <a href='/reference/typescript-api/common/id#id'>ID</a>, productVariantId: <a href='/reference/typescript-api/common/id#id'>ID</a>, quantity: number, customFields?: { [key: string]: any }, relations?: RelationPaths&#60;<a href='/reference/typescript-api/entities/order#order'>Order</a>&#62;) => Promise&#60;<a href='/reference/typescript-api/errors/error-result-union#errorresultunion'>ErrorResultUnion</a>&#60;UpdateOrderItemsResult, <a href='/reference/typescript-api/entities/order#order'>Order</a>&#62;&#62;`}   />

Adds an item to the Order, either creating a new OrderLine or
incrementing an existing one.

If you need to add multiple items to an Order, use `addItemsToOrder()` instead.
### addItemsToOrder

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, orderId: <a href='/reference/typescript-api/common/id#id'>ID</a>, items: Array&#60;{             productVariantId: <a href='/reference/typescript-api/common/id#id'>ID</a>;             quantity: number;             customFields?: { [key: string]: any };         }&#62;, relations?: RelationPaths&#60;<a href='/reference/typescript-api/entities/order#order'>Order</a>&#62;) => Promise&#60;{ order: <a href='/reference/typescript-api/entities/order#order'>Order</a>; errorResults: Array&#60;JustErrorResults&#60;UpdateOrderItemsResult&#62;&#62; }&#62;`}  since="3.1.0"  />

Adds multiple items to an Order. This method is more efficient than calling `addItemToOrder`
multiple times, as it only needs to fetch the entire Order once, and only performs
price adjustments once at the end.

Since this method can return multiple error results, it is recommended to check the `errorResults`
array to determine if any errors occurred.
### adjustOrderLine

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, orderId: <a href='/reference/typescript-api/common/id#id'>ID</a>, orderLineId: <a href='/reference/typescript-api/common/id#id'>ID</a>, quantity: number, customFields?: { [key: string]: any }, relations?: RelationPaths&#60;<a href='/reference/typescript-api/entities/order#order'>Order</a>&#62;) => Promise&#60;<a href='/reference/typescript-api/errors/error-result-union#errorresultunion'>ErrorResultUnion</a>&#60;UpdateOrderItemsResult, <a href='/reference/typescript-api/entities/order#order'>Order</a>&#62;&#62;`}   />

Adjusts the quantity and/or custom field values of an existing OrderLine.

If you need to adjust multiple OrderLines, use `adjustOrderLines()` instead.
### adjustOrderLines

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, orderId: <a href='/reference/typescript-api/common/id#id'>ID</a>, lines: Array&#60;{ orderLineId: <a href='/reference/typescript-api/common/id#id'>ID</a>; quantity: number; customFields?: { [key: string]: any } }&#62;, relations?: RelationPaths&#60;<a href='/reference/typescript-api/entities/order#order'>Order</a>&#62;) => Promise&#60;{ order: <a href='/reference/typescript-api/entities/order#order'>Order</a>; errorResults: Array&#60;JustErrorResults&#60;UpdateOrderItemsResult&#62;&#62; }&#62;`}  since="3.1.0"  />

Adjusts the quantity and/or custom field values of existing OrderLines.
This method is more efficient than calling `adjustOrderLine` multiple times, as it only needs to fetch
the entire Order once, and only performs price adjustments once at the end.
Since this method can return multiple error results, it is recommended to check the `errorResults`
array to determine if any errors occurred.
### removeItemFromOrder

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, orderId: <a href='/reference/typescript-api/common/id#id'>ID</a>, orderLineId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/errors/error-result-union#errorresultunion'>ErrorResultUnion</a>&#60;RemoveOrderItemsResult, <a href='/reference/typescript-api/entities/order#order'>Order</a>&#62;&#62;`}   />

Removes the specified OrderLine from the Order.

If you need to remove multiple OrderLines, use `removeItemsFromOrder()` instead.
### removeItemsFromOrder

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, orderId: <a href='/reference/typescript-api/common/id#id'>ID</a>, orderLineIds: <a href='/reference/typescript-api/common/id#id'>ID</a>[]) => Promise&#60;<a href='/reference/typescript-api/errors/error-result-union#errorresultunion'>ErrorResultUnion</a>&#60;RemoveOrderItemsResult, <a href='/reference/typescript-api/entities/order#order'>Order</a>&#62;&#62;`}  since="3.1.0"  />

Removes the specified OrderLines from the Order.
This method is more efficient than calling `removeItemFromOrder` multiple times, as it only needs to fetch
the entire Order once, and only performs price adjustments once at the end.
### removeAllItemsFromOrder

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, orderId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/errors/error-result-union#errorresultunion'>ErrorResultUnion</a>&#60;RemoveOrderItemsResult, <a href='/reference/typescript-api/entities/order#order'>Order</a>&#62;&#62;`}   />

Removes all OrderLines from the Order.
### addSurchargeToOrder

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, orderId: <a href='/reference/typescript-api/common/id#id'>ID</a>, surchargeInput: Partial&#60;Omit&#60;<a href='/reference/typescript-api/entities/surcharge#surcharge'>Surcharge</a>, 'id' | 'createdAt' | 'updatedAt' | 'order'&#62;&#62;) => Promise&#60;<a href='/reference/typescript-api/entities/order#order'>Order</a>&#62;`}   />

Adds a <a href='/reference/typescript-api/entities/surcharge#surcharge'>Surcharge</a> to the Order.
### removeSurchargeFromOrder

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, orderId: <a href='/reference/typescript-api/common/id#id'>ID</a>, surchargeId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/entities/order#order'>Order</a>&#62;`}   />

Removes a <a href='/reference/typescript-api/entities/surcharge#surcharge'>Surcharge</a> from the Order.
### applyCouponCode

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, orderId: <a href='/reference/typescript-api/common/id#id'>ID</a>, couponCode: string) => Promise&#60;<a href='/reference/typescript-api/errors/error-result-union#errorresultunion'>ErrorResultUnion</a>&#60;ApplyCouponCodeResult, <a href='/reference/typescript-api/entities/order#order'>Order</a>&#62;&#62;`}   />

Applies a coupon code to the Order, which should be a valid coupon code as specified in the configuration
of an active <a href='/reference/typescript-api/entities/promotion#promotion'>Promotion</a>.
### removeCouponCode

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, orderId: <a href='/reference/typescript-api/common/id#id'>ID</a>, couponCode: string) => `}   />

Removes a coupon code from the Order.
### getOrderPromotions

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, orderId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/entities/promotion#promotion'>Promotion</a>[]&#62;`}   />

Returns all <a href='/reference/typescript-api/entities/promotion#promotion'>Promotion</a>s associated with an Order.
### getNextOrderStates

<MemberInfo kind="method" type={`(order: <a href='/reference/typescript-api/entities/order#order'>Order</a>) => readonly <a href='/reference/typescript-api/orders/order-process#orderstate'>OrderState</a>[]`}   />

Returns the next possible states that the Order may transition to.
### setShippingAddress

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, orderId: <a href='/reference/typescript-api/common/id#id'>ID</a>, input: CreateAddressInput) => Promise&#60;<a href='/reference/typescript-api/entities/order#order'>Order</a>&#62;`}   />

Sets the shipping address for the Order.
### setBillingAddress

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, orderId: <a href='/reference/typescript-api/common/id#id'>ID</a>, input: CreateAddressInput) => Promise&#60;<a href='/reference/typescript-api/entities/order#order'>Order</a>&#62;`}   />

Sets the billing address for the Order.
### unsetShippingAddress

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, orderId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/entities/order#order'>Order</a>&#62;`}  since="3.1.0"  />

Unsets the shipping address for the Order.
### unsetBillingAddress

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, orderId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/entities/order#order'>Order</a>&#62;`}  since="3.1.0"  />

Unsets the billing address for the Order.
### getEligibleShippingMethods

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, orderId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;ShippingMethodQuote[]&#62;`}   />

Returns an array of quotes stating which <a href='/reference/typescript-api/entities/shipping-method#shippingmethod'>ShippingMethod</a>s may be applied to this Order.
This is determined by the configured <a href='/reference/typescript-api/shipping/shipping-eligibility-checker#shippingeligibilitychecker'>ShippingEligibilityChecker</a> of each ShippingMethod.

The quote also includes a price for each method, as determined by the configured
<a href='/reference/typescript-api/shipping/shipping-calculator#shippingcalculator'>ShippingCalculator</a> of each eligible ShippingMethod.
### getEligiblePaymentMethods

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, orderId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;PaymentMethodQuote[]&#62;`}   />

Returns an array of quotes stating which <a href='/reference/typescript-api/entities/payment-method#paymentmethod'>PaymentMethod</a>s may be used on this Order.
### setShippingMethod

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, orderId: <a href='/reference/typescript-api/common/id#id'>ID</a>, shippingMethodIds: <a href='/reference/typescript-api/common/id#id'>ID</a>[]) => Promise&#60;<a href='/reference/typescript-api/errors/error-result-union#errorresultunion'>ErrorResultUnion</a>&#60;SetOrderShippingMethodResult, <a href='/reference/typescript-api/entities/order#order'>Order</a>&#62;&#62;`}   />

Sets the ShippingMethod to be used on this Order.
### transitionToState

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, orderId: <a href='/reference/typescript-api/common/id#id'>ID</a>, state: <a href='/reference/typescript-api/orders/order-process#orderstate'>OrderState</a>) => Promise&#60;<a href='/reference/typescript-api/entities/order#order'>Order</a> | OrderStateTransitionError&#62;`}   />

Transitions the Order to the given state.
### transitionFulfillmentToState

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, fulfillmentId: <a href='/reference/typescript-api/common/id#id'>ID</a>, state: <a href='/reference/typescript-api/fulfillment/fulfillment-state#fulfillmentstate'>FulfillmentState</a>) => Promise&#60;<a href='/reference/typescript-api/entities/fulfillment#fulfillment'>Fulfillment</a> | FulfillmentStateTransitionError&#62;`}   />

Transitions a Fulfillment to the given state and then transitions the Order state based on
whether all Fulfillments of the Order are shipped or delivered.
### transitionRefundToState

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, refundId: <a href='/reference/typescript-api/common/id#id'>ID</a>, state: <a href='/reference/typescript-api/payment/refund-state#refundstate'>RefundState</a>, transactionId?: string) => Promise&#60;<a href='/reference/typescript-api/entities/refund#refund'>Refund</a> | RefundStateTransitionError&#62;`}   />

Transitions a Refund to the given state
### modifyOrder

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: ModifyOrderInput) => Promise&#60;<a href='/reference/typescript-api/errors/error-result-union#errorresultunion'>ErrorResultUnion</a>&#60;ModifyOrderResult, <a href='/reference/typescript-api/entities/order#order'>Order</a>&#62;&#62;`}   />

Allows the Order to be modified, which allows several aspects of the Order to be changed:

* Changes to OrderLine quantities
* New OrderLines being added
* Arbitrary <a href='/reference/typescript-api/entities/surcharge#surcharge'>Surcharge</a>s being added
* Shipping or billing address changes

Setting the `dryRun` input property to `true` will apply all changes, including updating the price of the
Order, except history entry and additional payment actions.

__Using dryRun option, you must wrap function call in transaction manually.__
### transitionPaymentToState

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, paymentId: <a href='/reference/typescript-api/common/id#id'>ID</a>, state: <a href='/reference/typescript-api/payment/payment-state#paymentstate'>PaymentState</a>) => Promise&#60;<a href='/reference/typescript-api/errors/error-result-union#errorresultunion'>ErrorResultUnion</a>&#60;TransitionPaymentToStateResult, <a href='/reference/typescript-api/entities/payment#payment'>Payment</a>&#62;&#62;`}   />

Transitions the given <a href='/reference/typescript-api/entities/payment#payment'>Payment</a> to a new state.
### addPaymentToOrder

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, orderId: <a href='/reference/typescript-api/common/id#id'>ID</a>, input: PaymentInput) => Promise&#60;<a href='/reference/typescript-api/errors/error-result-union#errorresultunion'>ErrorResultUnion</a>&#60;AddPaymentToOrderResult, <a href='/reference/typescript-api/entities/order#order'>Order</a>&#62;&#62;`}   />

Adds a new Payment to the Order. If the Order totalWithTax is covered by Payments, then the Order
state will get automatically transitioned to the `PaymentSettled` or `PaymentAuthorized` state.
### addManualPaymentToOrder

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: ManualPaymentInput) => Promise&#60;<a href='/reference/typescript-api/errors/error-result-union#errorresultunion'>ErrorResultUnion</a>&#60;AddManualPaymentToOrderResult, <a href='/reference/typescript-api/entities/order#order'>Order</a>&#62;&#62;`}   />

This method is used after modifying an existing completed order using the `modifyOrder()` method. If the modifications
cause the order total to increase (such as when adding a new OrderLine), then there will be an outstanding charge to
pay.

This method allows you to add a new Payment and assumes the actual processing has been done manually, e.g. in the
dashboard of your payment provider.
### settlePayment

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, paymentId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/errors/error-result-union#errorresultunion'>ErrorResultUnion</a>&#60;<a href='/reference/typescript-api/payment/payment-method-types#settlepaymentresult'>SettlePaymentResult</a>, <a href='/reference/typescript-api/entities/payment#payment'>Payment</a>&#62;&#62;`}   />

Settles a payment by invoking the <a href='/reference/typescript-api/payment/payment-method-handler#paymentmethodhandler'>PaymentMethodHandler</a>'s `settlePayment()` method. Automatically
transitions the Order state if all Payments are settled.
### cancelPayment

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, paymentId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/errors/error-result-union#errorresultunion'>ErrorResultUnion</a>&#60;<a href='/reference/typescript-api/payment/payment-method-types#cancelpaymentresult'>CancelPaymentResult</a>, <a href='/reference/typescript-api/entities/payment#payment'>Payment</a>&#62;&#62;`}   />

Cancels a payment by invoking the <a href='/reference/typescript-api/payment/payment-method-handler#paymentmethodhandler'>PaymentMethodHandler</a>'s `cancelPayment()` method (if defined), and transitions the Payment to
the `Cancelled` state.
### createFulfillment

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: FulfillOrderInput) => Promise&#60;<a href='/reference/typescript-api/errors/error-result-union#errorresultunion'>ErrorResultUnion</a>&#60;AddFulfillmentToOrderResult, <a href='/reference/typescript-api/entities/fulfillment#fulfillment'>Fulfillment</a>&#62;&#62;`}   />

Creates a new Fulfillment associated with the given Order and OrderItems.
### getOrderFulfillments

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>) => Promise&#60;<a href='/reference/typescript-api/entities/fulfillment#fulfillment'>Fulfillment</a>[]&#62;`}   />

Returns an array of all Fulfillments associated with the Order.
### getOrderSurcharges

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, orderId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/entities/surcharge#surcharge'>Surcharge</a>[]&#62;`}   />

Returns an array of all Surcharges associated with the Order.
### cancelOrder

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: CancelOrderInput) => Promise&#60;<a href='/reference/typescript-api/errors/error-result-union#errorresultunion'>ErrorResultUnion</a>&#60;CancelOrderResult, <a href='/reference/typescript-api/entities/order#order'>Order</a>&#62;&#62;`}   />

Cancels an Order by transitioning it to the `Cancelled` state. If stock is being tracked for the ProductVariants
in the Order, then new <a href='/reference/typescript-api/entities/stock-movement#stockmovement'>StockMovement</a>s will be created to correct the stock levels.
### refundOrder

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: RefundOrderInput) => Promise&#60;<a href='/reference/typescript-api/errors/error-result-union#errorresultunion'>ErrorResultUnion</a>&#60;RefundOrderResult, <a href='/reference/typescript-api/entities/refund#refund'>Refund</a>&#62;&#62;`}   />

Creates a <a href='/reference/typescript-api/entities/refund#refund'>Refund</a> against the order and in doing so invokes the `createRefund()` method of the
<a href='/reference/typescript-api/payment/payment-method-handler#paymentmethodhandler'>PaymentMethodHandler</a>.
### settleRefund

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: SettleRefundInput) => Promise&#60;<a href='/reference/typescript-api/entities/refund#refund'>Refund</a>&#62;`}   />

Settles a Refund by transitioning it to the `Settled` state.
### addCustomerToOrder

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, orderIdOrOrder: <a href='/reference/typescript-api/common/id#id'>ID</a> | <a href='/reference/typescript-api/entities/order#order'>Order</a>, customer: <a href='/reference/typescript-api/entities/customer#customer'>Customer</a>) => Promise&#60;<a href='/reference/typescript-api/entities/order#order'>Order</a>&#62;`}   />

Associates a Customer with the Order.
### addNoteToOrder

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: AddNoteToOrderInput) => Promise&#60;<a href='/reference/typescript-api/entities/order#order'>Order</a>&#62;`}   />

Creates a new "ORDER_NOTE" type <a href='/reference/typescript-api/entities/order-history-entry#orderhistoryentry'>OrderHistoryEntry</a> in the Order's history timeline.
### updateOrderNote

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: UpdateOrderNoteInput) => Promise&#60;<a href='/reference/typescript-api/entities/history-entry#historyentry'>HistoryEntry</a>&#62;`}   />


### deleteOrderNote

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, id: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;DeletionResponse&#62;`}   />


### deleteOrder

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, orderOrId: <a href='/reference/typescript-api/common/id#id'>ID</a> | <a href='/reference/typescript-api/entities/order#order'>Order</a>) => `}  since="1.5.0"  />

Deletes an Order, ensuring that any Sessions that reference this Order are dereferenced before deletion.
### mergeOrders

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, user: <a href='/reference/typescript-api/entities/user#user'>User</a>, guestOrder?: <a href='/reference/typescript-api/entities/order#order'>Order</a>, existingOrder?: <a href='/reference/typescript-api/entities/order#order'>Order</a>) => Promise&#60;<a href='/reference/typescript-api/entities/order#order'>Order</a> | undefined&#62;`}   />

When a guest user with an anonymous Order signs in and has an existing Order associated with that Customer,
we need to reconcile the contents of the two orders.

The logic used to do the merging is specified in the <a href='/reference/typescript-api/orders/order-options#orderoptions'>OrderOptions</a> `mergeStrategy` config setting.
### applyPriceAdjustments

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>, updatedOrderLines?: <a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a>[], relations?: RelationPaths&#60;<a href='/reference/typescript-api/entities/order#order'>Order</a>&#62;) => Promise&#60;<a href='/reference/typescript-api/entities/order#order'>Order</a>&#62;`}   />

Applies promotions, taxes and shipping to the Order. If the `updatedOrderLines` argument is passed in,
then all of those OrderLines will have their prices re-calculated using the configured <a href='/reference/typescript-api/orders/order-item-price-calculation-strategy#orderitempricecalculationstrategy'>OrderItemPriceCalculationStrategy</a>.


</div>


---

---
title: "OrderTestingService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## OrderTestingService

<GenerationInfo sourceFile="packages/core/src/service/services/order-testing.service.ts" sourceLine="35" packageName="@vendure/core" />

This service is responsible for creating temporary mock Orders against which tests can be run, such as
testing a ShippingMethod or Promotion.

```ts title="Signature"
class OrderTestingService {
    constructor(connection: TransactionalConnection, orderCalculator: OrderCalculator, shippingCalculator: ShippingCalculator, configArgService: ConfigArgService, configService: ConfigService, productPriceApplicator: ProductPriceApplicator, translator: TranslatorService)
    testShippingMethod(ctx: RequestContext, input: TestShippingMethodInput) => Promise<TestShippingMethodResult>;
    testEligibleShippingMethods(ctx: RequestContext, input: TestEligibleShippingMethodsInput) => Promise<ShippingMethodQuote[]>;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, orderCalculator: <a href='/reference/typescript-api/service-helpers/order-calculator#ordercalculator'>OrderCalculator</a>, shippingCalculator: <a href='/reference/typescript-api/shipping/shipping-calculator#shippingcalculator'>ShippingCalculator</a>, configArgService: ConfigArgService, configService: ConfigService, productPriceApplicator: <a href='/reference/typescript-api/service-helpers/product-price-applicator#productpriceapplicator'>ProductPriceApplicator</a>, translator: <a href='/reference/typescript-api/service-helpers/translator-service#translatorservice'>TranslatorService</a>) => OrderTestingService`}   />


### testShippingMethod

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: TestShippingMethodInput) => Promise&#60;TestShippingMethodResult&#62;`}   />

Runs a given ShippingMethod configuration against a mock Order to test for eligibility and resulting
price.
### testEligibleShippingMethods

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: TestEligibleShippingMethodsInput) => Promise&#60;ShippingMethodQuote[]&#62;`}   />

Tests all available ShippingMethods against a mock Order and return those which are eligible. This
is intended to simulate a call to the `eligibleShippingMethods` query of the Shop API.


</div>


---

---
title: "PaymentMethodService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## PaymentMethodService

<GenerationInfo sourceFile="packages/core/src/service/services/payment-method.service.ts" sourceLine="47" packageName="@vendure/core" />

Contains methods relating to <a href='/reference/typescript-api/entities/payment-method#paymentmethod'>PaymentMethod</a> entities.

```ts title="Signature"
class PaymentMethodService {
    constructor(connection: TransactionalConnection, configService: ConfigService, roleService: RoleService, listQueryBuilder: ListQueryBuilder, eventBus: EventBus, configArgService: ConfigArgService, channelService: ChannelService, customFieldRelationService: CustomFieldRelationService, translatableSaver: TranslatableSaver, translator: TranslatorService)
    findAll(ctx: RequestContext, options?: ListQueryOptions<PaymentMethod>, relations: RelationPaths<PaymentMethod> = []) => Promise<PaginatedList<PaymentMethod>>;
    findOne(ctx: RequestContext, paymentMethodId: ID, relations: RelationPaths<PaymentMethod> = []) => Promise<PaymentMethod | undefined>;
    create(ctx: RequestContext, input: CreatePaymentMethodInput) => Promise<PaymentMethod>;
    update(ctx: RequestContext, input: UpdatePaymentMethodInput) => Promise<PaymentMethod>;
    delete(ctx: RequestContext, paymentMethodId: ID, force: boolean = false) => Promise<DeletionResponse>;
    assignPaymentMethodsToChannel(ctx: RequestContext, input: AssignPaymentMethodsToChannelInput) => Promise<Array<Translated<PaymentMethod>>>;
    removePaymentMethodsFromChannel(ctx: RequestContext, input: RemovePaymentMethodsFromChannelInput) => Promise<Array<Translated<PaymentMethod>>>;
    getPaymentMethodEligibilityCheckers(ctx: RequestContext) => ConfigurableOperationDefinition[];
    getPaymentMethodHandlers(ctx: RequestContext) => ConfigurableOperationDefinition[];
    getEligiblePaymentMethods(ctx: RequestContext, order: Order) => Promise<PaymentMethodQuote[]>;
    getMethodAndOperations(ctx: RequestContext, method: string) => Promise<{
        paymentMethod: PaymentMethod;
        handler: PaymentMethodHandler;
        checker: PaymentMethodEligibilityChecker | null;
    }>;
    getActivePaymentMethods(ctx: RequestContext) => Promise<PaymentMethod[]>;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, configService: ConfigService, roleService: <a href='/reference/typescript-api/services/role-service#roleservice'>RoleService</a>, listQueryBuilder: <a href='/reference/typescript-api/data-access/list-query-builder#listquerybuilder'>ListQueryBuilder</a>, eventBus: <a href='/reference/typescript-api/events/event-bus#eventbus'>EventBus</a>, configArgService: ConfigArgService, channelService: <a href='/reference/typescript-api/services/channel-service#channelservice'>ChannelService</a>, customFieldRelationService: CustomFieldRelationService, translatableSaver: <a href='/reference/typescript-api/service-helpers/translatable-saver#translatablesaver'>TranslatableSaver</a>, translator: <a href='/reference/typescript-api/service-helpers/translator-service#translatorservice'>TranslatorService</a>) => PaymentMethodService`}   />


### findAll

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, options?: ListQueryOptions&#60;<a href='/reference/typescript-api/entities/payment-method#paymentmethod'>PaymentMethod</a>&#62;, relations: RelationPaths&#60;<a href='/reference/typescript-api/entities/payment-method#paymentmethod'>PaymentMethod</a>&#62; = []) => Promise&#60;<a href='/reference/typescript-api/common/paginated-list#paginatedlist'>PaginatedList</a>&#60;<a href='/reference/typescript-api/entities/payment-method#paymentmethod'>PaymentMethod</a>&#62;&#62;`}   />


### findOne

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, paymentMethodId: <a href='/reference/typescript-api/common/id#id'>ID</a>, relations: RelationPaths&#60;<a href='/reference/typescript-api/entities/payment-method#paymentmethod'>PaymentMethod</a>&#62; = []) => Promise&#60;<a href='/reference/typescript-api/entities/payment-method#paymentmethod'>PaymentMethod</a> | undefined&#62;`}   />


### create

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: CreatePaymentMethodInput) => Promise&#60;<a href='/reference/typescript-api/entities/payment-method#paymentmethod'>PaymentMethod</a>&#62;`}   />


### update

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: UpdatePaymentMethodInput) => Promise&#60;<a href='/reference/typescript-api/entities/payment-method#paymentmethod'>PaymentMethod</a>&#62;`}   />


### delete

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, paymentMethodId: <a href='/reference/typescript-api/common/id#id'>ID</a>, force: boolean = false) => Promise&#60;DeletionResponse&#62;`}   />


### assignPaymentMethodsToChannel

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: AssignPaymentMethodsToChannelInput) => Promise&#60;Array&#60;Translated&#60;<a href='/reference/typescript-api/entities/payment-method#paymentmethod'>PaymentMethod</a>&#62;&#62;&#62;`}   />


### removePaymentMethodsFromChannel

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: RemovePaymentMethodsFromChannelInput) => Promise&#60;Array&#60;Translated&#60;<a href='/reference/typescript-api/entities/payment-method#paymentmethod'>PaymentMethod</a>&#62;&#62;&#62;`}   />


### getPaymentMethodEligibilityCheckers

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => ConfigurableOperationDefinition[]`}   />


### getPaymentMethodHandlers

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => ConfigurableOperationDefinition[]`}   />


### getEligiblePaymentMethods

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>) => Promise&#60;PaymentMethodQuote[]&#62;`}   />


### getMethodAndOperations

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, method: string) => Promise&#60;{         paymentMethod: <a href='/reference/typescript-api/entities/payment-method#paymentmethod'>PaymentMethod</a>;         handler: <a href='/reference/typescript-api/payment/payment-method-handler#paymentmethodhandler'>PaymentMethodHandler</a>;         checker: <a href='/reference/typescript-api/payment/payment-method-eligibility-checker#paymentmethodeligibilitychecker'>PaymentMethodEligibilityChecker</a> | null;     }&#62;`}   />


### getActivePaymentMethods

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => Promise&#60;<a href='/reference/typescript-api/entities/payment-method#paymentmethod'>PaymentMethod</a>[]&#62;`}   />




</div>


---

---
title: "PaymentService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## PaymentService

<GenerationInfo sourceFile="packages/core/src/service/services/payment.service.ts" sourceLine="43" packageName="@vendure/core" />

Contains methods relating to <a href='/reference/typescript-api/entities/payment#payment'>Payment</a> entities.

```ts title="Signature"
class PaymentService {
    constructor(connection: TransactionalConnection, paymentStateMachine: PaymentStateMachine, refundStateMachine: RefundStateMachine, paymentMethodService: PaymentMethodService, eventBus: EventBus)
    create(ctx: RequestContext, input: DeepPartial<Payment>) => Promise<Payment>;
    findOneOrThrow(ctx: RequestContext, id: ID, relations: string[] = ['order']) => Promise<Payment>;
    transitionToState(ctx: RequestContext, paymentId: ID, state: PaymentState) => Promise<Payment | PaymentStateTransitionError>;
    getNextStates(payment: Payment) => readonly PaymentState[];
    createPayment(ctx: RequestContext, order: Order, amount: number, method: string, metadata: any) => Promise<Payment | IneligiblePaymentMethodError>;
    settlePayment(ctx: RequestContext, paymentId: ID) => Promise<PaymentStateTransitionError | Payment>;
    cancelPayment(ctx: RequestContext, paymentId: ID) => Promise<PaymentStateTransitionError | Payment>;
    createManualPayment(ctx: RequestContext, order: Order, amount: number, input: ManualPaymentInput) => ;
    createRefund(ctx: RequestContext, input: RefundOrderInput, order: Order, selectedPayment: Payment) => Promise<Refund | RefundStateTransitionError | RefundAmountError>;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, paymentStateMachine: PaymentStateMachine, refundStateMachine: RefundStateMachine, paymentMethodService: <a href='/reference/typescript-api/services/payment-method-service#paymentmethodservice'>PaymentMethodService</a>, eventBus: <a href='/reference/typescript-api/events/event-bus#eventbus'>EventBus</a>) => PaymentService`}   />


### create

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: DeepPartial&#60;<a href='/reference/typescript-api/entities/payment#payment'>Payment</a>&#62;) => Promise&#60;<a href='/reference/typescript-api/entities/payment#payment'>Payment</a>&#62;`}   />


### findOneOrThrow

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, id: <a href='/reference/typescript-api/common/id#id'>ID</a>, relations: string[] = ['order']) => Promise&#60;<a href='/reference/typescript-api/entities/payment#payment'>Payment</a>&#62;`}   />


### transitionToState

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, paymentId: <a href='/reference/typescript-api/common/id#id'>ID</a>, state: <a href='/reference/typescript-api/payment/payment-state#paymentstate'>PaymentState</a>) => Promise&#60;<a href='/reference/typescript-api/entities/payment#payment'>Payment</a> | PaymentStateTransitionError&#62;`}   />

Transitions a Payment to the given state.

When updating a Payment in the context of an Order, it is
preferable to use the <a href='/reference/typescript-api/services/order-service#orderservice'>OrderService</a> `transitionPaymentToState()` method, which will also handle
updating the Order state too.
### getNextStates

<MemberInfo kind="method" type={`(payment: <a href='/reference/typescript-api/entities/payment#payment'>Payment</a>) => readonly <a href='/reference/typescript-api/payment/payment-state#paymentstate'>PaymentState</a>[]`}   />


### createPayment

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>, amount: number, method: string, metadata: any) => Promise&#60;<a href='/reference/typescript-api/entities/payment#payment'>Payment</a> | IneligiblePaymentMethodError&#62;`}   />

Creates a new Payment.

When creating a Payment in the context of an Order, it is
preferable to use the <a href='/reference/typescript-api/services/order-service#orderservice'>OrderService</a> `addPaymentToOrder()` method, which will also handle
updating the Order state too.
### settlePayment

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, paymentId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;PaymentStateTransitionError | <a href='/reference/typescript-api/entities/payment#payment'>Payment</a>&#62;`}   />

Settles a Payment.

When settling a Payment in the context of an Order, it is
preferable to use the <a href='/reference/typescript-api/services/order-service#orderservice'>OrderService</a> `settlePayment()` method, which will also handle
updating the Order state too.
### cancelPayment

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, paymentId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;PaymentStateTransitionError | <a href='/reference/typescript-api/entities/payment#payment'>Payment</a>&#62;`}   />


### createManualPayment

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>, amount: number, input: ManualPaymentInput) => `}   />

Creates a Payment from the manual payment mutation in the Admin API

When creating a manual Payment in the context of an Order, it is
preferable to use the <a href='/reference/typescript-api/services/order-service#orderservice'>OrderService</a> `addManualPaymentToOrder()` method, which will also handle
updating the Order state too.
### createRefund

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: RefundOrderInput, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>, selectedPayment: <a href='/reference/typescript-api/entities/payment#payment'>Payment</a>) => Promise&#60;<a href='/reference/typescript-api/entities/refund#refund'>Refund</a> | RefundStateTransitionError | RefundAmountError&#62;`}   />

Creates a Refund against the specified Payment. If the amount to be refunded exceeds the value of the
specified Payment (in the case of multiple payments on a single Order), then the remaining outstanding
refund amount will be refunded against the next available Payment from the Order.

When creating a Refund in the context of an Order, it is
preferable to use the <a href='/reference/typescript-api/services/order-service#orderservice'>OrderService</a> `refundOrder()` method, which performs additional
validation.


</div>


---

---
title: "ProductOptionGroupService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ProductOptionGroupService

<GenerationInfo sourceFile="packages/core/src/service/services/product-option-group.service.ts" sourceLine="35" packageName="@vendure/core" />

Contains methods relating to <a href='/reference/typescript-api/entities/product-option-group#productoptiongroup'>ProductOptionGroup</a> entities.

```ts title="Signature"
class ProductOptionGroupService {
    constructor(connection: TransactionalConnection, translatableSaver: TranslatableSaver, customFieldRelationService: CustomFieldRelationService, productOptionService: ProductOptionService, eventBus: EventBus, translator: TranslatorService)
    findAll(ctx: RequestContext, filterTerm?: string, relations?: RelationPaths<ProductOptionGroup>) => Promise<Array<Translated<ProductOptionGroup>>>;
    findOne(ctx: RequestContext, id: ID, relations?: RelationPaths<ProductOptionGroup>, findOneOptions?: { includeSoftDeleted: boolean }) => Promise<Translated<ProductOptionGroup> | undefined>;
    getOptionGroupsByProductId(ctx: RequestContext, id: ID) => Promise<Array<Translated<ProductOptionGroup>>>;
    create(ctx: RequestContext, input: Omit<CreateProductOptionGroupInput, 'options'>) => Promise<Translated<ProductOptionGroup>>;
    update(ctx: RequestContext, input: UpdateProductOptionGroupInput) => Promise<Translated<ProductOptionGroup>>;
    deleteGroupAndOptionsFromProduct(ctx: RequestContext, id: ID, productId: ID) => ;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, translatableSaver: <a href='/reference/typescript-api/service-helpers/translatable-saver#translatablesaver'>TranslatableSaver</a>, customFieldRelationService: CustomFieldRelationService, productOptionService: <a href='/reference/typescript-api/services/product-option-service#productoptionservice'>ProductOptionService</a>, eventBus: <a href='/reference/typescript-api/events/event-bus#eventbus'>EventBus</a>, translator: <a href='/reference/typescript-api/service-helpers/translator-service#translatorservice'>TranslatorService</a>) => ProductOptionGroupService`}   />


### findAll

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, filterTerm?: string, relations?: RelationPaths&#60;<a href='/reference/typescript-api/entities/product-option-group#productoptiongroup'>ProductOptionGroup</a>&#62;) => Promise&#60;Array&#60;Translated&#60;<a href='/reference/typescript-api/entities/product-option-group#productoptiongroup'>ProductOptionGroup</a>&#62;&#62;&#62;`}   />


### findOne

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, id: <a href='/reference/typescript-api/common/id#id'>ID</a>, relations?: RelationPaths&#60;<a href='/reference/typescript-api/entities/product-option-group#productoptiongroup'>ProductOptionGroup</a>&#62;, findOneOptions?: { includeSoftDeleted: boolean }) => Promise&#60;Translated&#60;<a href='/reference/typescript-api/entities/product-option-group#productoptiongroup'>ProductOptionGroup</a>&#62; | undefined&#62;`}   />


### getOptionGroupsByProductId

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, id: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;Array&#60;Translated&#60;<a href='/reference/typescript-api/entities/product-option-group#productoptiongroup'>ProductOptionGroup</a>&#62;&#62;&#62;`}   />


### create

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: Omit&#60;CreateProductOptionGroupInput, 'options'&#62;) => Promise&#60;Translated&#60;<a href='/reference/typescript-api/entities/product-option-group#productoptiongroup'>ProductOptionGroup</a>&#62;&#62;`}   />


### update

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: UpdateProductOptionGroupInput) => Promise&#60;Translated&#60;<a href='/reference/typescript-api/entities/product-option-group#productoptiongroup'>ProductOptionGroup</a>&#62;&#62;`}   />


### deleteGroupAndOptionsFromProduct

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, id: <a href='/reference/typescript-api/common/id#id'>ID</a>, productId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => `}   />

Deletes the ProductOptionGroup and any associated ProductOptions. If the ProductOptionGroup
is still referenced by a soft-deleted Product, then a soft-delete will be used to preserve
referential integrity. Otherwise a hard-delete will be performed.


</div>


---

---
title: "ProductOptionService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ProductOptionService

<GenerationInfo sourceFile="packages/core/src/service/services/product-option.service.ts" sourceLine="34" packageName="@vendure/core" />

Contains methods relating to <a href='/reference/typescript-api/entities/product-option#productoption'>ProductOption</a> entities.

```ts title="Signature"
class ProductOptionService {
    constructor(connection: TransactionalConnection, translatableSaver: TranslatableSaver, customFieldRelationService: CustomFieldRelationService, eventBus: EventBus, translator: TranslatorService)
    findAll(ctx: RequestContext) => Promise<Array<Translated<ProductOption>>>;
    findOne(ctx: RequestContext, id: ID) => Promise<Translated<ProductOption> | undefined>;
    create(ctx: RequestContext, group: ProductOptionGroup | ID, input: CreateGroupOptionInput | CreateProductOptionInput) => Promise<Translated<ProductOption>>;
    update(ctx: RequestContext, input: UpdateProductOptionInput) => Promise<Translated<ProductOption>>;
    delete(ctx: RequestContext, id: ID) => Promise<DeletionResponse>;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, translatableSaver: <a href='/reference/typescript-api/service-helpers/translatable-saver#translatablesaver'>TranslatableSaver</a>, customFieldRelationService: CustomFieldRelationService, eventBus: <a href='/reference/typescript-api/events/event-bus#eventbus'>EventBus</a>, translator: <a href='/reference/typescript-api/service-helpers/translator-service#translatorservice'>TranslatorService</a>) => ProductOptionService`}   />


### findAll

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => Promise&#60;Array&#60;Translated&#60;<a href='/reference/typescript-api/entities/product-option#productoption'>ProductOption</a>&#62;&#62;&#62;`}   />


### findOne

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, id: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;Translated&#60;<a href='/reference/typescript-api/entities/product-option#productoption'>ProductOption</a>&#62; | undefined&#62;`}   />


### create

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, group: <a href='/reference/typescript-api/entities/product-option-group#productoptiongroup'>ProductOptionGroup</a> | <a href='/reference/typescript-api/common/id#id'>ID</a>, input: CreateGroupOptionInput | CreateProductOptionInput) => Promise&#60;Translated&#60;<a href='/reference/typescript-api/entities/product-option#productoption'>ProductOption</a>&#62;&#62;`}   />


### update

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: UpdateProductOptionInput) => Promise&#60;Translated&#60;<a href='/reference/typescript-api/entities/product-option#productoption'>ProductOption</a>&#62;&#62;`}   />


### delete

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, id: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;DeletionResponse&#62;`}   />

Deletes a ProductOption.

- If the ProductOption is used by any ProductVariants, the deletion will fail.
- If the ProductOption is used only by soft-deleted ProductVariants, the option will itself
  be soft-deleted.
- If the ProductOption is not used by any ProductVariant at all, it will be hard-deleted.


</div>


---

---
title: "ProductService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ProductService

<GenerationInfo sourceFile="packages/core/src/service/services/product.service.ts" sourceLine="54" packageName="@vendure/core" />

Contains methods relating to <a href='/reference/typescript-api/entities/product#product'>Product</a> entities.

```ts title="Signature"
class ProductService {
    constructor(connection: TransactionalConnection, channelService: ChannelService, assetService: AssetService, productVariantService: ProductVariantService, facetValueService: FacetValueService, listQueryBuilder: ListQueryBuilder, translatableSaver: TranslatableSaver, eventBus: EventBus, slugValidator: SlugValidator, customFieldRelationService: CustomFieldRelationService, translator: TranslatorService, productOptionGroupService: ProductOptionGroupService)
    findAll(ctx: RequestContext, options?: ListQueryOptions<Product>, relations?: RelationPaths<Product>) => Promise<PaginatedList<Translated<Product>>>;
    findOne(ctx: RequestContext, productId: ID, relations?: RelationPaths<Product>) => Promise<Translated<Product> | undefined>;
    findByIds(ctx: RequestContext, productIds: ID[], relations?: RelationPaths<Product>) => Promise<Array<Translated<Product>>>;
    getProductChannels(ctx: RequestContext, productId: ID) => Promise<Channel[]>;
    getFacetValuesForProduct(ctx: RequestContext, productId: ID) => Promise<Array<Translated<FacetValue>>>;
    findOneBySlug(ctx: RequestContext, slug: string, relations?: RelationPaths<Product>) => Promise<Translated<Product> | undefined>;
    create(ctx: RequestContext, input: CreateProductInput) => Promise<Translated<Product>>;
    update(ctx: RequestContext, input: UpdateProductInput) => Promise<Translated<Product>>;
    softDelete(ctx: RequestContext, productId: ID) => Promise<DeletionResponse>;
    assignProductsToChannel(ctx: RequestContext, input: AssignProductsToChannelInput) => Promise<Array<Translated<Product>>>;
    removeProductsFromChannel(ctx: RequestContext, input: RemoveProductsFromChannelInput) => Promise<Array<Translated<Product>>>;
    addOptionGroupToProduct(ctx: RequestContext, productId: ID, optionGroupId: ID) => Promise<Translated<Product>>;
    removeOptionGroupFromProduct(ctx: RequestContext, productId: ID, optionGroupId: ID, force?: boolean) => Promise<ErrorResultUnion<RemoveOptionGroupFromProductResult, Translated<Product>>>;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, channelService: <a href='/reference/typescript-api/services/channel-service#channelservice'>ChannelService</a>, assetService: <a href='/reference/typescript-api/services/asset-service#assetservice'>AssetService</a>, productVariantService: <a href='/reference/typescript-api/services/product-variant-service#productvariantservice'>ProductVariantService</a>, facetValueService: <a href='/reference/typescript-api/services/facet-value-service#facetvalueservice'>FacetValueService</a>, listQueryBuilder: <a href='/reference/typescript-api/data-access/list-query-builder#listquerybuilder'>ListQueryBuilder</a>, translatableSaver: <a href='/reference/typescript-api/service-helpers/translatable-saver#translatablesaver'>TranslatableSaver</a>, eventBus: <a href='/reference/typescript-api/events/event-bus#eventbus'>EventBus</a>, slugValidator: <a href='/reference/typescript-api/service-helpers/slug-validator#slugvalidator'>SlugValidator</a>, customFieldRelationService: CustomFieldRelationService, translator: <a href='/reference/typescript-api/service-helpers/translator-service#translatorservice'>TranslatorService</a>, productOptionGroupService: <a href='/reference/typescript-api/services/product-option-group-service#productoptiongroupservice'>ProductOptionGroupService</a>) => ProductService`}   />


### findAll

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, options?: ListQueryOptions&#60;<a href='/reference/typescript-api/entities/product#product'>Product</a>&#62;, relations?: RelationPaths&#60;<a href='/reference/typescript-api/entities/product#product'>Product</a>&#62;) => Promise&#60;<a href='/reference/typescript-api/common/paginated-list#paginatedlist'>PaginatedList</a>&#60;Translated&#60;<a href='/reference/typescript-api/entities/product#product'>Product</a>&#62;&#62;&#62;`}   />


### findOne

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, productId: <a href='/reference/typescript-api/common/id#id'>ID</a>, relations?: RelationPaths&#60;<a href='/reference/typescript-api/entities/product#product'>Product</a>&#62;) => Promise&#60;Translated&#60;<a href='/reference/typescript-api/entities/product#product'>Product</a>&#62; | undefined&#62;`}   />


### findByIds

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, productIds: <a href='/reference/typescript-api/common/id#id'>ID</a>[], relations?: RelationPaths&#60;<a href='/reference/typescript-api/entities/product#product'>Product</a>&#62;) => Promise&#60;Array&#60;Translated&#60;<a href='/reference/typescript-api/entities/product#product'>Product</a>&#62;&#62;&#62;`}   />


### getProductChannels

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, productId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/entities/channel#channel'>Channel</a>[]&#62;`}   />

Returns all Channels to which the Product is assigned.
### getFacetValuesForProduct

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, productId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;Array&#60;Translated&#60;<a href='/reference/typescript-api/entities/facet-value#facetvalue'>FacetValue</a>&#62;&#62;&#62;`}   />


### findOneBySlug

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, slug: string, relations?: RelationPaths&#60;<a href='/reference/typescript-api/entities/product#product'>Product</a>&#62;) => Promise&#60;Translated&#60;<a href='/reference/typescript-api/entities/product#product'>Product</a>&#62; | undefined&#62;`}   />


### create

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: CreateProductInput) => Promise&#60;Translated&#60;<a href='/reference/typescript-api/entities/product#product'>Product</a>&#62;&#62;`}   />


### update

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: UpdateProductInput) => Promise&#60;Translated&#60;<a href='/reference/typescript-api/entities/product#product'>Product</a>&#62;&#62;`}   />


### softDelete

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, productId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;DeletionResponse&#62;`}   />


### assignProductsToChannel

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: AssignProductsToChannelInput) => Promise&#60;Array&#60;Translated&#60;<a href='/reference/typescript-api/entities/product#product'>Product</a>&#62;&#62;&#62;`}   />

Assigns a Product to the specified Channel, and optionally uses a `priceFactor` to set the ProductVariantPrices
on the new Channel.

Internally, this method will also call <a href='/reference/typescript-api/services/product-variant-service#productvariantservice'>ProductVariantService</a> `assignProductVariantsToChannel()` for
each of the Product's variants, and will assign the Product's Assets to the Channel too.
### removeProductsFromChannel

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: RemoveProductsFromChannelInput) => Promise&#60;Array&#60;Translated&#60;<a href='/reference/typescript-api/entities/product#product'>Product</a>&#62;&#62;&#62;`}   />


### addOptionGroupToProduct

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, productId: <a href='/reference/typescript-api/common/id#id'>ID</a>, optionGroupId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;Translated&#60;<a href='/reference/typescript-api/entities/product#product'>Product</a>&#62;&#62;`}   />


### removeOptionGroupFromProduct

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, productId: <a href='/reference/typescript-api/common/id#id'>ID</a>, optionGroupId: <a href='/reference/typescript-api/common/id#id'>ID</a>, force?: boolean) => Promise&#60;<a href='/reference/typescript-api/errors/error-result-union#errorresultunion'>ErrorResultUnion</a>&#60;RemoveOptionGroupFromProductResult, Translated&#60;<a href='/reference/typescript-api/entities/product#product'>Product</a>&#62;&#62;&#62;`}   />




</div>


---

---
title: "ProductVariantService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ProductVariantService

<GenerationInfo sourceFile="packages/core/src/service/services/product-variant.service.ts" sourceLine="70" packageName="@vendure/core" />

Contains methods relating to <a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a> entities.

```ts title="Signature"
class ProductVariantService {
    constructor(connection: TransactionalConnection, configService: ConfigService, taxCategoryService: TaxCategoryService, facetValueService: FacetValueService, assetService: AssetService, translatableSaver: TranslatableSaver, eventBus: EventBus, listQueryBuilder: ListQueryBuilder, globalSettingsService: GlobalSettingsService, stockMovementService: StockMovementService, stockLevelService: StockLevelService, channelService: ChannelService, roleService: RoleService, customFieldRelationService: CustomFieldRelationService, requestCache: RequestContextCacheService, productPriceApplicator: ProductPriceApplicator, translator: TranslatorService)
    findAll(ctx: RequestContext, options?: ListQueryOptions<ProductVariant>) => Promise<PaginatedList<Translated<ProductVariant>>>;
    findOne(ctx: RequestContext, productVariantId: ID, relations?: RelationPaths<ProductVariant>) => Promise<Translated<ProductVariant> | undefined>;
    findByIds(ctx: RequestContext, ids: ID[]) => Promise<Array<Translated<ProductVariant>>>;
    getVariantsByProductId(ctx: RequestContext, productId: ID, options: ListQueryOptions<ProductVariant> = {}, relations?: RelationPaths<ProductVariant>) => Promise<PaginatedList<Translated<ProductVariant>>>;
    getVariantsByCollectionId(ctx: RequestContext, collectionId: ID, options: ListQueryOptions<ProductVariant>, relations: RelationPaths<ProductVariant> = []) => Promise<PaginatedList<Translated<ProductVariant>>>;
    getProductVariantChannels(ctx: RequestContext, productVariantId: ID) => Promise<Channel[]>;
    getProductVariantPrices(ctx: RequestContext, productVariantId: ID) => Promise<ProductVariantPrice[]>;
    getVariantByOrderLineId(ctx: RequestContext, orderLineId: ID) => Promise<Translated<ProductVariant>>;
    getOptionsForVariant(ctx: RequestContext, variantId: ID) => Promise<Array<Translated<ProductOption>>>;
    getFacetValuesForVariant(ctx: RequestContext, variantId: ID) => Promise<Array<Translated<FacetValue>>>;
    getProductForVariant(ctx: RequestContext, variant: ProductVariant) => Promise<Translated<Product>>;
    getSaleableStockLevel(ctx: RequestContext, variant: ProductVariant) => Promise<number>;
    getDisplayStockLevel(ctx: RequestContext, variant: ProductVariant) => Promise<string>;
    getFulfillableStockLevel(ctx: RequestContext, variant: ProductVariant) => Promise<number>;
    create(ctx: RequestContext, input: CreateProductVariantInput[]) => Promise<Array<Translated<ProductVariant>>>;
    update(ctx: RequestContext, input: UpdateProductVariantInput[]) => Promise<Array<Translated<ProductVariant>>>;
    createOrUpdateProductVariantPrice(ctx: RequestContext, productVariantId: ID, price: number, channelId: ID, currencyCode?: CurrencyCode, customFields?: CustomFieldsObject) => Promise<ProductVariantPrice>;
    deleteProductVariantPrice(ctx: RequestContext, variantId: ID, channelId: ID, currencyCode: CurrencyCode) => ;
    softDelete(ctx: RequestContext, id: ID | ID[]) => Promise<DeletionResponse>;
    hydratePriceFields(ctx: RequestContext, variant: ProductVariant, priceField: F) => Promise<ProductVariant[F]>;
    applyChannelPriceAndTax(variant: ProductVariant, ctx: RequestContext, order?: Order, throwIfNoPriceFound:  = false) => Promise<ProductVariant>;
    assignProductVariantsToChannel(ctx: RequestContext, input: AssignProductVariantsToChannelInput) => Promise<Array<Translated<ProductVariant>>>;
    removeProductVariantsFromChannel(ctx: RequestContext, input: RemoveProductVariantsFromChannelInput) => Promise<Array<Translated<ProductVariant>>>;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, configService: ConfigService, taxCategoryService: <a href='/reference/typescript-api/services/tax-category-service#taxcategoryservice'>TaxCategoryService</a>, facetValueService: <a href='/reference/typescript-api/services/facet-value-service#facetvalueservice'>FacetValueService</a>, assetService: <a href='/reference/typescript-api/services/asset-service#assetservice'>AssetService</a>, translatableSaver: <a href='/reference/typescript-api/service-helpers/translatable-saver#translatablesaver'>TranslatableSaver</a>, eventBus: <a href='/reference/typescript-api/events/event-bus#eventbus'>EventBus</a>, listQueryBuilder: <a href='/reference/typescript-api/data-access/list-query-builder#listquerybuilder'>ListQueryBuilder</a>, globalSettingsService: <a href='/reference/typescript-api/services/global-settings-service#globalsettingsservice'>GlobalSettingsService</a>, stockMovementService: <a href='/reference/typescript-api/services/stock-movement-service#stockmovementservice'>StockMovementService</a>, stockLevelService: <a href='/reference/typescript-api/services/stock-level-service#stocklevelservice'>StockLevelService</a>, channelService: <a href='/reference/typescript-api/services/channel-service#channelservice'>ChannelService</a>, roleService: <a href='/reference/typescript-api/services/role-service#roleservice'>RoleService</a>, customFieldRelationService: CustomFieldRelationService, requestCache: <a href='/reference/typescript-api/cache/request-context-cache-service#requestcontextcacheservice'>RequestContextCacheService</a>, productPriceApplicator: <a href='/reference/typescript-api/service-helpers/product-price-applicator#productpriceapplicator'>ProductPriceApplicator</a>, translator: <a href='/reference/typescript-api/service-helpers/translator-service#translatorservice'>TranslatorService</a>) => ProductVariantService`}   />


### findAll

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, options?: ListQueryOptions&#60;<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>&#62;) => Promise&#60;<a href='/reference/typescript-api/common/paginated-list#paginatedlist'>PaginatedList</a>&#60;Translated&#60;<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>&#62;&#62;&#62;`}   />


### findOne

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, productVariantId: <a href='/reference/typescript-api/common/id#id'>ID</a>, relations?: RelationPaths&#60;<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>&#62;) => Promise&#60;Translated&#60;<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>&#62; | undefined&#62;`}   />


### findByIds

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, ids: <a href='/reference/typescript-api/common/id#id'>ID</a>[]) => Promise&#60;Array&#60;Translated&#60;<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>&#62;&#62;&#62;`}   />


### getVariantsByProductId

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, productId: <a href='/reference/typescript-api/common/id#id'>ID</a>, options: ListQueryOptions&#60;<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>&#62; = {}, relations?: RelationPaths&#60;<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>&#62;) => Promise&#60;<a href='/reference/typescript-api/common/paginated-list#paginatedlist'>PaginatedList</a>&#60;Translated&#60;<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>&#62;&#62;&#62;`}   />


### getVariantsByCollectionId

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, collectionId: <a href='/reference/typescript-api/common/id#id'>ID</a>, options: ListQueryOptions&#60;<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>&#62;, relations: RelationPaths&#60;<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>&#62; = []) => Promise&#60;<a href='/reference/typescript-api/common/paginated-list#paginatedlist'>PaginatedList</a>&#60;Translated&#60;<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>&#62;&#62;&#62;`}   />

Returns a <a href='/reference/typescript-api/common/paginated-list#paginatedlist'>PaginatedList</a> of all ProductVariants associated with the given Collection.
### getProductVariantChannels

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, productVariantId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/entities/channel#channel'>Channel</a>[]&#62;`}   />

Returns all Channels to which the ProductVariant is assigned.
### getProductVariantPrices

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, productVariantId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/entities/product-variant-price#productvariantprice'>ProductVariantPrice</a>[]&#62;`}   />


### getVariantByOrderLineId

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, orderLineId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;Translated&#60;<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>&#62;&#62;`}   />

Returns the ProductVariant associated with the given <a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a>.
### getOptionsForVariant

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, variantId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;Array&#60;Translated&#60;<a href='/reference/typescript-api/entities/product-option#productoption'>ProductOption</a>&#62;&#62;&#62;`}   />

Returns the <a href='/reference/typescript-api/entities/product-option#productoption'>ProductOption</a>s for the given ProductVariant.
### getFacetValuesForVariant

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, variantId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;Array&#60;Translated&#60;<a href='/reference/typescript-api/entities/facet-value#facetvalue'>FacetValue</a>&#62;&#62;&#62;`}   />


### getProductForVariant

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, variant: <a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>) => Promise&#60;Translated&#60;<a href='/reference/typescript-api/entities/product#product'>Product</a>&#62;&#62;`}   />

Returns the Product associated with the ProductVariant. Whereas the `ProductService.findOne()`
method performs a large multi-table join with all the typical data needed for a "product detail"
page, this method returns only the Product itself.
### getSaleableStockLevel

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, variant: <a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>) => Promise&#60;number&#62;`}   />

Returns the number of saleable units of the ProductVariant, i.e. how many are available
for purchase by Customers. This is determined by the ProductVariant's `stockOnHand` value,
as well as the local and global `outOfStockThreshold` settings.
### getDisplayStockLevel

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, variant: <a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>) => Promise&#60;string&#62;`}   />

Returns the stockLevel to display to the customer, as specified by the configured
<a href='/reference/typescript-api/products-stock/stock-display-strategy#stockdisplaystrategy'>StockDisplayStrategy</a>.
### getFulfillableStockLevel

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, variant: <a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>) => Promise&#60;number&#62;`}   />

Returns the number of fulfillable units of the ProductVariant, equivalent to stockOnHand
for those variants which are tracking inventory.
### create

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: CreateProductVariantInput[]) => Promise&#60;Array&#60;Translated&#60;<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>&#62;&#62;&#62;`}   />


### update

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: UpdateProductVariantInput[]) => Promise&#60;Array&#60;Translated&#60;<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>&#62;&#62;&#62;`}   />


### createOrUpdateProductVariantPrice

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, productVariantId: <a href='/reference/typescript-api/common/id#id'>ID</a>, price: number, channelId: <a href='/reference/typescript-api/common/id#id'>ID</a>, currencyCode?: <a href='/reference/typescript-api/common/currency-code#currencycode'>CurrencyCode</a>, customFields?: CustomFieldsObject) => Promise&#60;<a href='/reference/typescript-api/entities/product-variant-price#productvariantprice'>ProductVariantPrice</a>&#62;`}   />

Creates a <a href='/reference/typescript-api/entities/product-variant-price#productvariantprice'>ProductVariantPrice</a> for the given ProductVariant/Channel combination.
If the `currencyCode` is not specified, the default currency of the Channel will be used.
### deleteProductVariantPrice

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, variantId: <a href='/reference/typescript-api/common/id#id'>ID</a>, channelId: <a href='/reference/typescript-api/common/id#id'>ID</a>, currencyCode: <a href='/reference/typescript-api/common/currency-code#currencycode'>CurrencyCode</a>) => `}   />


### softDelete

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, id: <a href='/reference/typescript-api/common/id#id'>ID</a> | <a href='/reference/typescript-api/common/id#id'>ID</a>[]) => Promise&#60;DeletionResponse&#62;`}   />


### hydratePriceFields

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, variant: <a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>, priceField: F) => Promise&#60;<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>[F]&#62;`}   />

This method is intended to be used by the ProductVariant GraphQL entity resolver to resolve the
price-related fields which need to be populated at run-time using the `applyChannelPriceAndTax`
method.

Is optimized to make as few DB calls as possible using caching based on the open request.
### applyChannelPriceAndTax

<MemberInfo kind="method" type={`(variant: <a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>, ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, order?: <a href='/reference/typescript-api/entities/order#order'>Order</a>, throwIfNoPriceFound:  = false) => Promise&#60;<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>&#62;`}   />

Populates the `price` field with the price for the specified channel.
### assignProductVariantsToChannel

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: AssignProductVariantsToChannelInput) => Promise&#60;Array&#60;Translated&#60;<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>&#62;&#62;&#62;`}   />

Assigns the specified ProductVariants to the specified Channel. In doing so, it will create a new
<a href='/reference/typescript-api/entities/product-variant-price#productvariantprice'>ProductVariantPrice</a> and also assign the associated Product and any Assets to the Channel too.
### removeProductVariantsFromChannel

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: RemoveProductVariantsFromChannelInput) => Promise&#60;Array&#60;Translated&#60;<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>&#62;&#62;&#62;`}   />




</div>


---

---
title: "PromotionService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## PromotionService

<GenerationInfo sourceFile="packages/core/src/service/services/promotion.service.ts" sourceLine="57" packageName="@vendure/core" />

Contains methods relating to <a href='/reference/typescript-api/entities/promotion#promotion'>Promotion</a> entities.

```ts title="Signature"
class PromotionService {
    availableConditions: PromotionCondition[] = [];
    availableActions: PromotionAction[] = [];
    constructor(connection: TransactionalConnection, configService: ConfigService, channelService: ChannelService, listQueryBuilder: ListQueryBuilder, configArgService: ConfigArgService, customFieldRelationService: CustomFieldRelationService, eventBus: EventBus, translatableSaver: TranslatableSaver, translator: TranslatorService)
    findAll(ctx: RequestContext, options?: ListQueryOptions<Promotion>, relations: RelationPaths<Promotion> = []) => Promise<PaginatedList<Promotion>>;
    findOne(ctx: RequestContext, adjustmentSourceId: ID, relations: RelationPaths<Promotion> = []) => Promise<Promotion | undefined>;
    getPromotionConditions(ctx: RequestContext) => ConfigurableOperationDefinition[];
    getPromotionActions(ctx: RequestContext) => ConfigurableOperationDefinition[];
    createPromotion(ctx: RequestContext, input: CreatePromotionInput) => Promise<ErrorResultUnion<CreatePromotionResult, Promotion>>;
    updatePromotion(ctx: RequestContext, input: UpdatePromotionInput) => Promise<ErrorResultUnion<UpdatePromotionResult, Promotion>>;
    softDeletePromotion(ctx: RequestContext, promotionId: ID) => Promise<DeletionResponse>;
    assignPromotionsToChannel(ctx: RequestContext, input: AssignPromotionsToChannelInput) => Promise<Promotion[]>;
    removePromotionsFromChannel(ctx: RequestContext, input: RemovePromotionsFromChannelInput) => ;
    validateCouponCode(ctx: RequestContext, couponCode: string, customerId?: ID) => Promise<JustErrorResults<ApplyCouponCodeResult> | Promotion>;
    getActivePromotionsInChannel(ctx: RequestContext) => ;
    getActivePromotionsOnOrder(ctx: RequestContext, orderId: ID) => Promise<Promotion[]>;
    runPromotionSideEffects(ctx: RequestContext, order: Order, promotionsPre: Promotion[]) => ;
    addPromotionsToOrder(ctx: RequestContext, order: Order) => Promise<Order>;
}
```

<div className="members-wrapper">

### availableConditions

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/promotions/promotion-condition#promotioncondition'>PromotionCondition</a>[]`}   />


### availableActions

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/promotions/promotion-action#promotionaction'>PromotionAction</a>[]`}   />


### constructor

<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, configService: ConfigService, channelService: <a href='/reference/typescript-api/services/channel-service#channelservice'>ChannelService</a>, listQueryBuilder: <a href='/reference/typescript-api/data-access/list-query-builder#listquerybuilder'>ListQueryBuilder</a>, configArgService: ConfigArgService, customFieldRelationService: CustomFieldRelationService, eventBus: <a href='/reference/typescript-api/events/event-bus#eventbus'>EventBus</a>, translatableSaver: <a href='/reference/typescript-api/service-helpers/translatable-saver#translatablesaver'>TranslatableSaver</a>, translator: <a href='/reference/typescript-api/service-helpers/translator-service#translatorservice'>TranslatorService</a>) => PromotionService`}   />


### findAll

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, options?: ListQueryOptions&#60;<a href='/reference/typescript-api/entities/promotion#promotion'>Promotion</a>&#62;, relations: RelationPaths&#60;<a href='/reference/typescript-api/entities/promotion#promotion'>Promotion</a>&#62; = []) => Promise&#60;<a href='/reference/typescript-api/common/paginated-list#paginatedlist'>PaginatedList</a>&#60;<a href='/reference/typescript-api/entities/promotion#promotion'>Promotion</a>&#62;&#62;`}   />


### findOne

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, adjustmentSourceId: <a href='/reference/typescript-api/common/id#id'>ID</a>, relations: RelationPaths&#60;<a href='/reference/typescript-api/entities/promotion#promotion'>Promotion</a>&#62; = []) => Promise&#60;<a href='/reference/typescript-api/entities/promotion#promotion'>Promotion</a> | undefined&#62;`}   />


### getPromotionConditions

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => ConfigurableOperationDefinition[]`}   />


### getPromotionActions

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => ConfigurableOperationDefinition[]`}   />


### createPromotion

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: CreatePromotionInput) => Promise&#60;<a href='/reference/typescript-api/errors/error-result-union#errorresultunion'>ErrorResultUnion</a>&#60;CreatePromotionResult, <a href='/reference/typescript-api/entities/promotion#promotion'>Promotion</a>&#62;&#62;`}   />


### updatePromotion

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: UpdatePromotionInput) => Promise&#60;<a href='/reference/typescript-api/errors/error-result-union#errorresultunion'>ErrorResultUnion</a>&#60;UpdatePromotionResult, <a href='/reference/typescript-api/entities/promotion#promotion'>Promotion</a>&#62;&#62;`}   />


### softDeletePromotion

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, promotionId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;DeletionResponse&#62;`}   />


### assignPromotionsToChannel

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: AssignPromotionsToChannelInput) => Promise&#60;<a href='/reference/typescript-api/entities/promotion#promotion'>Promotion</a>[]&#62;`}   />


### removePromotionsFromChannel

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: RemovePromotionsFromChannelInput) => `}   />


### validateCouponCode

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, couponCode: string, customerId?: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;JustErrorResults&#60;ApplyCouponCodeResult&#62; | <a href='/reference/typescript-api/entities/promotion#promotion'>Promotion</a>&#62;`}   />

Checks the validity of a coupon code, by checking that it is associated with an existing,
enabled and non-expired Promotion. Additionally, if there is a usage limit on the coupon code,
this method will enforce that limit against the specified Customer.
### getActivePromotionsInChannel

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => `}   />


### getActivePromotionsOnOrder

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, orderId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/entities/promotion#promotion'>Promotion</a>[]&#62;`}   />


### runPromotionSideEffects

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>, promotionsPre: <a href='/reference/typescript-api/entities/promotion#promotion'>Promotion</a>[]) => `}   />


### addPromotionsToOrder

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>) => Promise&#60;<a href='/reference/typescript-api/entities/order#order'>Order</a>&#62;`}   />

Used internally to associate a Promotion with an Order, once an Order has been placed.


</div>


---

---
title: "ProvinceService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ProvinceService

<GenerationInfo sourceFile="packages/core/src/service/services/province.service.ts" sourceLine="32" packageName="@vendure/core" />

Contains methods relating to <a href='/reference/typescript-api/entities/province#province'>Province</a> entities.

```ts title="Signature"
class ProvinceService {
    constructor(connection: TransactionalConnection, listQueryBuilder: ListQueryBuilder, translatableSaver: TranslatableSaver, eventBus: EventBus, translator: TranslatorService)
    findAll(ctx: RequestContext, options?: ListQueryOptions<Province>, relations: RelationPaths<Province> = []) => Promise<PaginatedList<Translated<Province>>>;
    findOne(ctx: RequestContext, provinceId: ID, relations: RelationPaths<Province> = []) => Promise<Translated<Province> | undefined>;
    create(ctx: RequestContext, input: CreateProvinceInput) => Promise<Translated<Province>>;
    update(ctx: RequestContext, input: UpdateProvinceInput) => Promise<Translated<Province>>;
    delete(ctx: RequestContext, id: ID) => Promise<DeletionResponse>;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, listQueryBuilder: <a href='/reference/typescript-api/data-access/list-query-builder#listquerybuilder'>ListQueryBuilder</a>, translatableSaver: <a href='/reference/typescript-api/service-helpers/translatable-saver#translatablesaver'>TranslatableSaver</a>, eventBus: <a href='/reference/typescript-api/events/event-bus#eventbus'>EventBus</a>, translator: <a href='/reference/typescript-api/service-helpers/translator-service#translatorservice'>TranslatorService</a>) => ProvinceService`}   />


### findAll

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, options?: ListQueryOptions&#60;<a href='/reference/typescript-api/entities/province#province'>Province</a>&#62;, relations: RelationPaths&#60;<a href='/reference/typescript-api/entities/province#province'>Province</a>&#62; = []) => Promise&#60;<a href='/reference/typescript-api/common/paginated-list#paginatedlist'>PaginatedList</a>&#60;Translated&#60;<a href='/reference/typescript-api/entities/province#province'>Province</a>&#62;&#62;&#62;`}   />


### findOne

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, provinceId: <a href='/reference/typescript-api/common/id#id'>ID</a>, relations: RelationPaths&#60;<a href='/reference/typescript-api/entities/province#province'>Province</a>&#62; = []) => Promise&#60;Translated&#60;<a href='/reference/typescript-api/entities/province#province'>Province</a>&#62; | undefined&#62;`}   />


### create

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: CreateProvinceInput) => Promise&#60;Translated&#60;<a href='/reference/typescript-api/entities/province#province'>Province</a>&#62;&#62;`}   />


### update

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: UpdateProvinceInput) => Promise&#60;Translated&#60;<a href='/reference/typescript-api/entities/province#province'>Province</a>&#62;&#62;`}   />


### delete

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, id: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;DeletionResponse&#62;`}   />




</div>


---

---
title: "RoleService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## RoleService

<GenerationInfo sourceFile="packages/core/src/service/services/role.service.ts" sourceLine="53" packageName="@vendure/core" />

Contains methods relating to <a href='/reference/typescript-api/entities/role#role'>Role</a> entities.

```ts title="Signature"
class RoleService {
    constructor(connection: TransactionalConnection, channelService: ChannelService, listQueryBuilder: ListQueryBuilder, configService: ConfigService, eventBus: EventBus, requestContextCache: RequestContextCacheService)
    initRoles() => ;
    findAll(ctx: RequestContext, options?: ListQueryOptions<Role>, relations?: RelationPaths<Role>) => Promise<PaginatedList<Role>>;
    findOne(ctx: RequestContext, roleId: ID, relations?: RelationPaths<Role>) => Promise<Role | undefined>;
    getChannelsForRole(ctx: RequestContext, roleId: ID) => Promise<Channel[]>;
    getSuperAdminRole(ctx?: RequestContext) => Promise<Role>;
    getCustomerRole(ctx?: RequestContext) => Promise<Role>;
    getAllPermissions() => string[];
    userHasPermissionOnChannel(ctx: RequestContext, channelId: ID, permission: Permission) => Promise<boolean>;
    userHasAnyPermissionsOnChannel(ctx: RequestContext, channelId: ID, permissions: Permission[]) => Promise<boolean>;
    userHasAllPermissionsOnChannel(ctx: RequestContext, channelId: ID, permissions: Permission[]) => Promise<boolean>;
    create(ctx: RequestContext, input: CreateRoleInput) => Promise<Role>;
    update(ctx: RequestContext, input: UpdateRoleInput) => Promise<Role>;
    delete(ctx: RequestContext, id: ID) => Promise<DeletionResponse>;
    assignRoleToChannel(ctx: RequestContext, roleId: ID, channelId: ID) => ;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, channelService: <a href='/reference/typescript-api/services/channel-service#channelservice'>ChannelService</a>, listQueryBuilder: <a href='/reference/typescript-api/data-access/list-query-builder#listquerybuilder'>ListQueryBuilder</a>, configService: ConfigService, eventBus: <a href='/reference/typescript-api/events/event-bus#eventbus'>EventBus</a>, requestContextCache: <a href='/reference/typescript-api/cache/request-context-cache-service#requestcontextcacheservice'>RequestContextCacheService</a>) => RoleService`}   />


### initRoles

<MemberInfo kind="method" type={`() => `}   />


### findAll

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, options?: ListQueryOptions&#60;<a href='/reference/typescript-api/entities/role#role'>Role</a>&#62;, relations?: RelationPaths&#60;<a href='/reference/typescript-api/entities/role#role'>Role</a>&#62;) => Promise&#60;<a href='/reference/typescript-api/common/paginated-list#paginatedlist'>PaginatedList</a>&#60;<a href='/reference/typescript-api/entities/role#role'>Role</a>&#62;&#62;`}   />


### findOne

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, roleId: <a href='/reference/typescript-api/common/id#id'>ID</a>, relations?: RelationPaths&#60;<a href='/reference/typescript-api/entities/role#role'>Role</a>&#62;) => Promise&#60;<a href='/reference/typescript-api/entities/role#role'>Role</a> | undefined&#62;`}   />


### getChannelsForRole

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, roleId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/entities/channel#channel'>Channel</a>[]&#62;`}   />


### getSuperAdminRole

<MemberInfo kind="method" type={`(ctx?: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => Promise&#60;<a href='/reference/typescript-api/entities/role#role'>Role</a>&#62;`}   />

Returns the special SuperAdmin Role, which always exists in Vendure.
### getCustomerRole

<MemberInfo kind="method" type={`(ctx?: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => Promise&#60;<a href='/reference/typescript-api/entities/role#role'>Role</a>&#62;`}   />

Returns the special Customer Role, which always exists in Vendure.
### getAllPermissions

<MemberInfo kind="method" type={`() => string[]`}   />

Returns all the valid Permission values
### userHasPermissionOnChannel

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, channelId: <a href='/reference/typescript-api/common/id#id'>ID</a>, permission: <a href='/reference/typescript-api/common/permission#permission'>Permission</a>) => Promise&#60;boolean&#62;`}   />

Returns true if the User has the specified permission on that Channel
### userHasAnyPermissionsOnChannel

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, channelId: <a href='/reference/typescript-api/common/id#id'>ID</a>, permissions: <a href='/reference/typescript-api/common/permission#permission'>Permission</a>[]) => Promise&#60;boolean&#62;`}   />

Returns true if the User has any of the specified permissions on that Channel
### userHasAllPermissionsOnChannel

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, channelId: <a href='/reference/typescript-api/common/id#id'>ID</a>, permissions: <a href='/reference/typescript-api/common/permission#permission'>Permission</a>[]) => Promise&#60;boolean&#62;`}   />

Returns true if the User has all the specified permissions on that Channel
### create

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: CreateRoleInput) => Promise&#60;<a href='/reference/typescript-api/entities/role#role'>Role</a>&#62;`}   />


### update

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: UpdateRoleInput) => Promise&#60;<a href='/reference/typescript-api/entities/role#role'>Role</a>&#62;`}   />


### delete

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, id: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;DeletionResponse&#62;`}   />


### assignRoleToChannel

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, roleId: <a href='/reference/typescript-api/common/id#id'>ID</a>, channelId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => `}   />




</div>


---

---
title: "SearchService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## SearchService

<GenerationInfo sourceFile="packages/core/src/service/services/search.service.ts" sourceLine="15" packageName="@vendure/core" />

This service allows a concrete search service to override its behaviour
by passing itself to the `adopt()` method.

```ts title="Signature"
class SearchService {
    adopt(override: Pick<SearchService, 'reindex'>) => ;
    reindex(ctx: RequestContext) => Promise<Job>;
}
```

<div className="members-wrapper">

### adopt

<MemberInfo kind="method" type={`(override: Pick&#60;<a href='/reference/typescript-api/services/search-service#searchservice'>SearchService</a>, 'reindex'&#62;) => `}   />

Adopt a concrete search service implementation to pass through the
calls to.
### reindex

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => Promise&#60;<a href='/reference/typescript-api/job-queue/job#job'>Job</a>&#62;`}   />




</div>


---

---
title: "SellerService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## SellerService

<GenerationInfo sourceFile="packages/core/src/service/services/seller.service.ts" sourceLine="26" packageName="@vendure/core" />

Contains methods relating to <a href='/reference/typescript-api/entities/seller#seller'>Seller</a> entities.

```ts title="Signature"
class SellerService {
    constructor(connection: TransactionalConnection, listQueryBuilder: ListQueryBuilder, eventBus: EventBus, customFieldRelationService: CustomFieldRelationService)
    initSellers() => ;
    findAll(ctx: RequestContext, options?: ListQueryOptions<Seller>) => Promise<PaginatedList<Seller>>;
    findOne(ctx: RequestContext, sellerId: ID) => Promise<Seller | undefined>;
    create(ctx: RequestContext, input: CreateSellerInput) => ;
    update(ctx: RequestContext, input: UpdateSellerInput) => ;
    delete(ctx: RequestContext, id: ID) => Promise<DeletionResponse>;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, listQueryBuilder: <a href='/reference/typescript-api/data-access/list-query-builder#listquerybuilder'>ListQueryBuilder</a>, eventBus: <a href='/reference/typescript-api/events/event-bus#eventbus'>EventBus</a>, customFieldRelationService: CustomFieldRelationService) => SellerService`}   />


### initSellers

<MemberInfo kind="method" type={`() => `}   />


### findAll

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, options?: ListQueryOptions&#60;<a href='/reference/typescript-api/entities/seller#seller'>Seller</a>&#62;) => Promise&#60;<a href='/reference/typescript-api/common/paginated-list#paginatedlist'>PaginatedList</a>&#60;<a href='/reference/typescript-api/entities/seller#seller'>Seller</a>&#62;&#62;`}   />


### findOne

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, sellerId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/entities/seller#seller'>Seller</a> | undefined&#62;`}   />


### create

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: CreateSellerInput) => `}   />


### update

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: UpdateSellerInput) => `}   />


### delete

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, id: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;DeletionResponse&#62;`}   />




</div>


---

---
title: "SessionService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## SessionService

<GenerationInfo sourceFile="packages/core/src/service/services/session.service.ts" sourceLine="33" packageName="@vendure/core" />

Contains methods relating to <a href='/reference/typescript-api/entities/session#session'>Session</a> entities.

```ts title="Signature"
class SessionService implements EntitySubscriberInterface, OnApplicationBootstrap {
    constructor(connection: TransactionalConnection, configService: ConfigService, orderService: OrderService, jobQueueService: JobQueueService, requestContextService: RequestContextService)
    onApplicationBootstrap() => ;
    createNewAuthenticatedSession(ctx: RequestContext, user: User, authenticationStrategyName: string) => Promise<AuthenticatedSession>;
    createAnonymousSession() => Promise<CachedSession>;
    getSessionFromToken(sessionToken: string) => Promise<CachedSession | undefined>;
    serializeSession(session: AuthenticatedSession | AnonymousSession) => CachedSession;
    setActiveOrder(ctx: RequestContext, serializedSession: CachedSession, order: Order) => Promise<CachedSession>;
    unsetActiveOrder(ctx: RequestContext, serializedSession: CachedSession) => Promise<CachedSession>;
    setActiveChannel(serializedSession: CachedSession, channel: Channel) => Promise<CachedSession>;
    deleteSessionsByUser(ctx: RequestContext, user: User) => Promise<void>;
    deleteSessionsByActiveOrderId(ctx: RequestContext, activeOrderId: ID) => Promise<void>;
    triggerCleanSessionsJob(batchSize: number) => ;
    cleanExpiredSessions(ctx: RequestContext, batchSize: number) => ;
}
```
* Implements: <code>EntitySubscriberInterface</code>, <code>OnApplicationBootstrap</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, configService: ConfigService, orderService: <a href='/reference/typescript-api/services/order-service#orderservice'>OrderService</a>, jobQueueService: <a href='/reference/typescript-api/job-queue/job-queue-service#jobqueueservice'>JobQueueService</a>, requestContextService: <a href='/reference/typescript-api/request/request-context-service#requestcontextservice'>RequestContextService</a>) => SessionService`}   />


### onApplicationBootstrap

<MemberInfo kind="method" type={`() => `}   />


### createNewAuthenticatedSession

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, user: <a href='/reference/typescript-api/entities/user#user'>User</a>, authenticationStrategyName: string) => Promise&#60;<a href='/reference/typescript-api/entities/authenticated-session#authenticatedsession'>AuthenticatedSession</a>&#62;`}   />

Creates a new <a href='/reference/typescript-api/entities/authenticated-session#authenticatedsession'>AuthenticatedSession</a>. To be used after successful authentication.
### createAnonymousSession

<MemberInfo kind="method" type={`() => Promise&#60;<a href='/reference/typescript-api/auth/session-cache-strategy#cachedsession'>CachedSession</a>&#62;`}   />

Create an <a href='/reference/typescript-api/entities/anonymous-session#anonymoussession'>AnonymousSession</a> and caches it using the configured <a href='/reference/typescript-api/auth/session-cache-strategy#sessioncachestrategy'>SessionCacheStrategy</a>,
and returns the cached session object.
### getSessionFromToken

<MemberInfo kind="method" type={`(sessionToken: string) => Promise&#60;<a href='/reference/typescript-api/auth/session-cache-strategy#cachedsession'>CachedSession</a> | undefined&#62;`}   />

Returns the cached session object matching the given session token.
### serializeSession

<MemberInfo kind="method" type={`(session: <a href='/reference/typescript-api/entities/authenticated-session#authenticatedsession'>AuthenticatedSession</a> | <a href='/reference/typescript-api/entities/anonymous-session#anonymoussession'>AnonymousSession</a>) => <a href='/reference/typescript-api/auth/session-cache-strategy#cachedsession'>CachedSession</a>`}   />

Serializes a <a href='/reference/typescript-api/entities/session#session'>Session</a> instance into a simplified plain object suitable for caching.
### setActiveOrder

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, serializedSession: <a href='/reference/typescript-api/auth/session-cache-strategy#cachedsession'>CachedSession</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>) => Promise&#60;<a href='/reference/typescript-api/auth/session-cache-strategy#cachedsession'>CachedSession</a>&#62;`}   />

Sets the `activeOrder` on the given cached session object and updates the cache.
### unsetActiveOrder

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, serializedSession: <a href='/reference/typescript-api/auth/session-cache-strategy#cachedsession'>CachedSession</a>) => Promise&#60;<a href='/reference/typescript-api/auth/session-cache-strategy#cachedsession'>CachedSession</a>&#62;`}   />

Clears the `activeOrder` on the given cached session object and updates the cache.
### setActiveChannel

<MemberInfo kind="method" type={`(serializedSession: <a href='/reference/typescript-api/auth/session-cache-strategy#cachedsession'>CachedSession</a>, channel: <a href='/reference/typescript-api/entities/channel#channel'>Channel</a>) => Promise&#60;<a href='/reference/typescript-api/auth/session-cache-strategy#cachedsession'>CachedSession</a>&#62;`}   />

Sets the `activeChannel` on the given cached session object and updates the cache.
### deleteSessionsByUser

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, user: <a href='/reference/typescript-api/entities/user#user'>User</a>) => Promise&#60;void&#62;`}   />

Deletes all existing sessions for the given user.
### deleteSessionsByActiveOrderId

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, activeOrderId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;void&#62;`}   />

Deletes all existing sessions with the given activeOrder.
### triggerCleanSessionsJob

<MemberInfo kind="method" type={`(batchSize: number) => `}   />

Triggers the clean sessions job.
### cleanExpiredSessions

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, batchSize: number) => `}   />

Cleans expired sessions from the database & the session cache.


</div>


---

---
title: "SettingsStoreService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## SettingsStoreService

<GenerationInfo sourceFile="packages/core/src/service/helpers/settings-store/settings-store.service.ts" sourceLine="50" packageName="@vendure/core" since="3.4.0" />

The SettingsStoreService provides a flexible settings storage system with support for
scoping, permissions, and validation. It allows plugins and the core system to
store and retrieve configuration data with fine-grained control over access and isolation.

## Usage

Values are automatically scoped according to their field configuration:

*Example*

```ts
// In a service
const userTheme = await this.settingsStoreService.get('dashboard.theme', ctx);
await this.settingsStoreService.set('dashboard.theme', 'dark', ctx);

// Get multiple values
const settings = await this.settingsStoreService.getMany([
  'dashboard.theme',
  'dashboard.tableFilters'
], ctx);
```

```ts title="Signature"
class SettingsStoreService implements OnModuleInit {
    constructor(connection: TransactionalConnection, moduleRef: ModuleRef, configService: ConfigService)
    onModuleInit() => ;
    register(registration: SettingsStoreRegistration) => void;
    get(key: string, ctx: RequestContext) => Promise<T | undefined>;
    getMany(keys: string[], ctx: RequestContext) => Promise<Record<string, JsonCompatible<any>>>;
    set(key: string, value: T, ctx: RequestContext) => Promise<SetSettingsStoreValueResult>;
    setMany(values: Record<string, JsonCompatible<any>>, ctx: RequestContext) => Promise<SetSettingsStoreValueResult[]>;
    getFieldDefinition(key: string) => SettingsStoreFieldConfig | undefined;
    validateValue(key: string, value: any, ctx: RequestContext) => Promise<string | void>;
    findOrphanedEntries(options: CleanupOrphanedSettingsStoreEntriesOptions = {}) => Promise<OrphanedSettingsStoreEntry[]>;
    cleanupOrphanedEntries(options: CleanupOrphanedSettingsStoreEntriesOptions = {}) => Promise<CleanupOrphanedSettingsStoreEntriesResult>;
}
```
* Implements: <code>OnModuleInit</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, moduleRef: ModuleRef, configService: ConfigService) => SettingsStoreService`}   />


### onModuleInit

<MemberInfo kind="method" type={`() => `}   />


### register

<MemberInfo kind="method" type={`(registration: <a href='/reference/typescript-api/settings-store/settings-store-registration#settingsstoreregistration'>SettingsStoreRegistration</a>) => void`}   />

Register settings store fields. This is typically called during application
bootstrap when processing the VendureConfig.
### get

<MemberInfo kind="method" type={`(key: string, ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => Promise&#60;T | undefined&#62;`}   />

Get a value for the specified key. The value is automatically scoped
according to the field's scope configuration.
### getMany

<MemberInfo kind="method" type={`(keys: string[], ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => Promise&#60;Record&#60;string, <a href='/reference/typescript-api/common/json-compatible#jsoncompatible'>JsonCompatible</a>&#60;any&#62;&#62;&#62;`}   />

Get multiple values efficiently. Each key is scoped according to
its individual field configuration.
### set

<MemberInfo kind="method" type={`(key: string, value: T, ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => Promise&#60;<a href='/reference/typescript-api/settings-store/set-settings-store-value-result#setsettingsstorevalueresult'>SetSettingsStoreValueResult</a>&#62;`}   />

Set a value for the specified key with structured result feedback.
This version returns detailed information about the success or failure
of the operation instead of throwing errors.
### setMany

<MemberInfo kind="method" type={`(values: Record&#60;string, <a href='/reference/typescript-api/common/json-compatible#jsoncompatible'>JsonCompatible</a>&#60;any&#62;&#62;, ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => Promise&#60;<a href='/reference/typescript-api/settings-store/set-settings-store-value-result#setsettingsstorevalueresult'>SetSettingsStoreValueResult</a>[]&#62;`}   />

Set multiple values with structured result feedback for each operation.
This method will not throw errors but will return
detailed results for each key-value pair.
### getFieldDefinition

<MemberInfo kind="method" type={`(key: string) => <a href='/reference/typescript-api/settings-store/settings-store-field-config#settingsstorefieldconfig'>SettingsStoreFieldConfig</a> | undefined`}   />

Get the field configuration for a key.
### validateValue

<MemberInfo kind="method" type={`(key: string, value: any, ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => Promise&#60;string | void&#62;`}   />

Validate a value against its field definition.
### findOrphanedEntries

<MemberInfo kind="method" type={`(options: <a href='/reference/typescript-api/settings-store/cleanup-orphaned-settings-store-entries-options#cleanuporphanedsettingsstoreentriesoptions'>CleanupOrphanedSettingsStoreEntriesOptions</a> = {}) => Promise&#60;<a href='/reference/typescript-api/settings-store/orphaned-settings-store-entry#orphanedsettingsstoreentry'>OrphanedSettingsStoreEntry</a>[]&#62;`}   />

Find orphaned settings store entries that no longer have corresponding field definitions.
### cleanupOrphanedEntries

<MemberInfo kind="method" type={`(options: <a href='/reference/typescript-api/settings-store/cleanup-orphaned-settings-store-entries-options#cleanuporphanedsettingsstoreentriesoptions'>CleanupOrphanedSettingsStoreEntriesOptions</a> = {}) => Promise&#60;<a href='/reference/typescript-api/settings-store/cleanup-orphaned-settings-store-entries-result#cleanuporphanedsettingsstoreentriesresult'>CleanupOrphanedSettingsStoreEntriesResult</a>&#62;`}   />

Clean up orphaned settings store entries from the database.


</div>


---

---
title: "ShippingMethodService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ShippingMethodService

<GenerationInfo sourceFile="packages/core/src/service/services/shipping-method.service.ts" sourceLine="45" packageName="@vendure/core" />

Contains methods relating to <a href='/reference/typescript-api/entities/shipping-method#shippingmethod'>ShippingMethod</a> entities.

```ts title="Signature"
class ShippingMethodService {
    constructor(connection: TransactionalConnection, configService: ConfigService, roleService: RoleService, listQueryBuilder: ListQueryBuilder, channelService: ChannelService, configArgService: ConfigArgService, translatableSaver: TranslatableSaver, customFieldRelationService: CustomFieldRelationService, eventBus: EventBus, translator: TranslatorService)
    findAll(ctx: RequestContext, options?: ListQueryOptions<ShippingMethod>, relations: RelationPaths<ShippingMethod> = []) => Promise<PaginatedList<Translated<ShippingMethod>>>;
    findOne(ctx: RequestContext, shippingMethodId: ID, includeDeleted:  = false, relations: RelationPaths<ShippingMethod> = []) => Promise<Translated<ShippingMethod> | undefined>;
    create(ctx: RequestContext, input: CreateShippingMethodInput) => Promise<Translated<ShippingMethod>>;
    update(ctx: RequestContext, input: UpdateShippingMethodInput) => Promise<Translated<ShippingMethod>>;
    softDelete(ctx: RequestContext, id: ID) => Promise<DeletionResponse>;
    assignShippingMethodsToChannel(ctx: RequestContext, input: AssignShippingMethodsToChannelInput) => Promise<Array<Translated<ShippingMethod>>>;
    removeShippingMethodsFromChannel(ctx: RequestContext, input: RemoveShippingMethodsFromChannelInput) => Promise<Array<Translated<ShippingMethod>>>;
    getShippingEligibilityCheckers(ctx: RequestContext) => ConfigurableOperationDefinition[];
    getShippingCalculators(ctx: RequestContext) => ConfigurableOperationDefinition[];
    getFulfillmentHandlers(ctx: RequestContext) => ConfigurableOperationDefinition[];
    getActiveShippingMethods(ctx: RequestContext) => Promise<ShippingMethod[]>;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, configService: ConfigService, roleService: <a href='/reference/typescript-api/services/role-service#roleservice'>RoleService</a>, listQueryBuilder: <a href='/reference/typescript-api/data-access/list-query-builder#listquerybuilder'>ListQueryBuilder</a>, channelService: <a href='/reference/typescript-api/services/channel-service#channelservice'>ChannelService</a>, configArgService: ConfigArgService, translatableSaver: <a href='/reference/typescript-api/service-helpers/translatable-saver#translatablesaver'>TranslatableSaver</a>, customFieldRelationService: CustomFieldRelationService, eventBus: <a href='/reference/typescript-api/events/event-bus#eventbus'>EventBus</a>, translator: <a href='/reference/typescript-api/service-helpers/translator-service#translatorservice'>TranslatorService</a>) => ShippingMethodService`}   />


### findAll

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, options?: ListQueryOptions&#60;<a href='/reference/typescript-api/entities/shipping-method#shippingmethod'>ShippingMethod</a>&#62;, relations: RelationPaths&#60;<a href='/reference/typescript-api/entities/shipping-method#shippingmethod'>ShippingMethod</a>&#62; = []) => Promise&#60;<a href='/reference/typescript-api/common/paginated-list#paginatedlist'>PaginatedList</a>&#60;Translated&#60;<a href='/reference/typescript-api/entities/shipping-method#shippingmethod'>ShippingMethod</a>&#62;&#62;&#62;`}   />


### findOne

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, shippingMethodId: <a href='/reference/typescript-api/common/id#id'>ID</a>, includeDeleted:  = false, relations: RelationPaths&#60;<a href='/reference/typescript-api/entities/shipping-method#shippingmethod'>ShippingMethod</a>&#62; = []) => Promise&#60;Translated&#60;<a href='/reference/typescript-api/entities/shipping-method#shippingmethod'>ShippingMethod</a>&#62; | undefined&#62;`}   />


### create

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: CreateShippingMethodInput) => Promise&#60;Translated&#60;<a href='/reference/typescript-api/entities/shipping-method#shippingmethod'>ShippingMethod</a>&#62;&#62;`}   />


### update

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: UpdateShippingMethodInput) => Promise&#60;Translated&#60;<a href='/reference/typescript-api/entities/shipping-method#shippingmethod'>ShippingMethod</a>&#62;&#62;`}   />


### softDelete

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, id: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;DeletionResponse&#62;`}   />


### assignShippingMethodsToChannel

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: AssignShippingMethodsToChannelInput) => Promise&#60;Array&#60;Translated&#60;<a href='/reference/typescript-api/entities/shipping-method#shippingmethod'>ShippingMethod</a>&#62;&#62;&#62;`}   />


### removeShippingMethodsFromChannel

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: RemoveShippingMethodsFromChannelInput) => Promise&#60;Array&#60;Translated&#60;<a href='/reference/typescript-api/entities/shipping-method#shippingmethod'>ShippingMethod</a>&#62;&#62;&#62;`}   />


### getShippingEligibilityCheckers

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => ConfigurableOperationDefinition[]`}   />


### getShippingCalculators

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => ConfigurableOperationDefinition[]`}   />


### getFulfillmentHandlers

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => ConfigurableOperationDefinition[]`}   />


### getActiveShippingMethods

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => Promise&#60;<a href='/reference/typescript-api/entities/shipping-method#shippingmethod'>ShippingMethod</a>[]&#62;`}   />




</div>


---

---
title: "StockLevelService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## StockLevelService

<GenerationInfo sourceFile="packages/core/src/service/services/stock-level.service.ts" sourceLine="23" packageName="@vendure/core" since="2.0.0" />

The StockLevelService is responsible for managing the stock levels of ProductVariants.
Whenever you need to adjust the `stockOnHand` or `stockAllocated` for a ProductVariant,
you should use this service.

```ts title="Signature"
class StockLevelService {
    constructor(connection: TransactionalConnection, stockLocationService: StockLocationService, configService: ConfigService)
    getStockLevel(ctx: RequestContext, productVariantId: ID, stockLocationId: ID) => Promise<StockLevel>;
    getStockLevelsForVariant(ctx: RequestContext, productVariantId: ID) => Promise<StockLevel[]>;
    getAvailableStock(ctx: RequestContext, productVariantId: ID) => Promise<AvailableStock>;
    updateStockOnHandForLocation(ctx: RequestContext, productVariantId: ID, stockLocationId: ID, change: number) => ;
    updateStockAllocatedForLocation(ctx: RequestContext, productVariantId: ID, stockLocationId: ID, change: number) => ;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, stockLocationService: StockLocationService, configService: ConfigService) => StockLevelService`}   />


### getStockLevel

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, productVariantId: <a href='/reference/typescript-api/common/id#id'>ID</a>, stockLocationId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/entities/stock-level#stocklevel'>StockLevel</a>&#62;`}   />

Returns the StockLevel for the given <a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a> and <a href='/reference/typescript-api/entities/stock-location#stocklocation'>StockLocation</a>.
### getStockLevelsForVariant

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, productVariantId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/entities/stock-level#stocklevel'>StockLevel</a>[]&#62;`}   />


### getAvailableStock

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, productVariantId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/products-stock/stock-location-strategy#availablestock'>AvailableStock</a>&#62;`}   />

Returns the available stock (on hand and allocated) for the given <a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>. This is determined
by the configured <a href='/reference/typescript-api/products-stock/stock-location-strategy#stocklocationstrategy'>StockLocationStrategy</a>.
### updateStockOnHandForLocation

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, productVariantId: <a href='/reference/typescript-api/common/id#id'>ID</a>, stockLocationId: <a href='/reference/typescript-api/common/id#id'>ID</a>, change: number) => `}   />

Updates the `stockOnHand` for the given <a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a> and <a href='/reference/typescript-api/entities/stock-location#stocklocation'>StockLocation</a>.
### updateStockAllocatedForLocation

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, productVariantId: <a href='/reference/typescript-api/common/id#id'>ID</a>, stockLocationId: <a href='/reference/typescript-api/common/id#id'>ID</a>, change: number) => `}   />

Updates the `stockAllocated` for the given <a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a> and <a href='/reference/typescript-api/entities/stock-location#stocklocation'>StockLocation</a>.


</div>


---

---
title: "StockMovementService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## StockMovementService

<GenerationInfo sourceFile="packages/core/src/service/services/stock-movement.service.ts" sourceLine="41" packageName="@vendure/core" />

Contains methods relating to <a href='/reference/typescript-api/entities/stock-movement#stockmovement'>StockMovement</a> entities.

```ts title="Signature"
class StockMovementService {
    shippingEligibilityCheckers: ShippingEligibilityChecker[];
    shippingCalculators: ShippingCalculator[];
    constructor(connection: TransactionalConnection, listQueryBuilder: ListQueryBuilder, globalSettingsService: GlobalSettingsService, stockLevelService: StockLevelService, eventBus: EventBus, stockLocationService: StockLocationService)
    getStockMovementsByProductVariantId(ctx: RequestContext, productVariantId: ID, options: StockMovementListOptions) => Promise<PaginatedList<StockMovement>>;
    adjustProductVariantStock(ctx: RequestContext, productVariantId: ID, stockOnHandNumberOrInput: number | StockLevelInput[]) => Promise<StockAdjustment[]>;
    createAllocationsForOrder(ctx: RequestContext, order: Order) => Promise<Allocation[]>;
    createAllocationsForOrderLines(ctx: RequestContext, lines: OrderLineInput[]) => Promise<Allocation[]>;
    createSalesForOrder(ctx: RequestContext, lines: OrderLineInput[]) => Promise<Sale[]>;
    createCancellationsForOrderLines(ctx: RequestContext, lineInputs: OrderLineInput[]) => Promise<Cancellation[]>;
    createReleasesForOrderLines(ctx: RequestContext, lineInputs: OrderLineInput[]) => Promise<Release[]>;
}
```

<div className="members-wrapper">

### shippingEligibilityCheckers

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/shipping/shipping-eligibility-checker#shippingeligibilitychecker'>ShippingEligibilityChecker</a>[]`}   />


### shippingCalculators

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/shipping/shipping-calculator#shippingcalculator'>ShippingCalculator</a>[]`}   />


### constructor

<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, listQueryBuilder: <a href='/reference/typescript-api/data-access/list-query-builder#listquerybuilder'>ListQueryBuilder</a>, globalSettingsService: <a href='/reference/typescript-api/services/global-settings-service#globalsettingsservice'>GlobalSettingsService</a>, stockLevelService: <a href='/reference/typescript-api/services/stock-level-service#stocklevelservice'>StockLevelService</a>, eventBus: <a href='/reference/typescript-api/events/event-bus#eventbus'>EventBus</a>, stockLocationService: StockLocationService) => StockMovementService`}   />


### getStockMovementsByProductVariantId

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, productVariantId: <a href='/reference/typescript-api/common/id#id'>ID</a>, options: StockMovementListOptions) => Promise&#60;<a href='/reference/typescript-api/common/paginated-list#paginatedlist'>PaginatedList</a>&#60;<a href='/reference/typescript-api/entities/stock-movement#stockmovement'>StockMovement</a>&#62;&#62;`}   />

Returns a <a href='/reference/typescript-api/common/paginated-list#paginatedlist'>PaginatedList</a> of all StockMovements associated with the specified ProductVariant.
### adjustProductVariantStock

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, productVariantId: <a href='/reference/typescript-api/common/id#id'>ID</a>, stockOnHandNumberOrInput: number | StockLevelInput[]) => Promise&#60;<a href='/reference/typescript-api/entities/stock-movement#stockadjustment'>StockAdjustment</a>[]&#62;`}   />

Adjusts the stock level of the ProductVariant, creating a new <a href='/reference/typescript-api/entities/stock-movement#stockadjustment'>StockAdjustment</a> entity
in the process.
### createAllocationsForOrder

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>) => Promise&#60;<a href='/reference/typescript-api/entities/stock-movement#allocation'>Allocation</a>[]&#62;`}   />

Creates a new <a href='/reference/typescript-api/entities/stock-movement#allocation'>Allocation</a> for each OrderLine in the Order. For ProductVariants
which are configured to track stock levels, the `ProductVariant.stockAllocated` value is
increased, indicating that this quantity of stock is allocated and cannot be sold.
### createAllocationsForOrderLines

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, lines: OrderLineInput[]) => Promise&#60;<a href='/reference/typescript-api/entities/stock-movement#allocation'>Allocation</a>[]&#62;`}   />

Creates a new <a href='/reference/typescript-api/entities/stock-movement#allocation'>Allocation</a> for each of the given OrderLines. For ProductVariants
which are configured to track stock levels, the `ProductVariant.stockAllocated` value is
increased, indicating that this quantity of stock is allocated and cannot be sold.
### createSalesForOrder

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, lines: OrderLineInput[]) => Promise&#60;<a href='/reference/typescript-api/entities/stock-movement#sale'>Sale</a>[]&#62;`}   />

Creates <a href='/reference/typescript-api/entities/stock-movement#sale'>Sale</a>s for each OrderLine in the Order. For ProductVariants
which are configured to track stock levels, the `ProductVariant.stockAllocated` value is
reduced and the `stockOnHand` value is also reduced by the OrderLine quantity, indicating
that the stock is no longer allocated, but is actually sold and no longer available.
### createCancellationsForOrderLines

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, lineInputs: OrderLineInput[]) => Promise&#60;<a href='/reference/typescript-api/entities/stock-movement#cancellation'>Cancellation</a>[]&#62;`}   />

Creates a <a href='/reference/typescript-api/entities/stock-movement#cancellation'>Cancellation</a> for each of the specified OrderItems. For ProductVariants
which are configured to track stock levels, the `ProductVariant.stockOnHand` value is
increased for each Cancellation, allowing that stock to be sold again.
### createReleasesForOrderLines

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, lineInputs: OrderLineInput[]) => Promise&#60;<a href='/reference/typescript-api/entities/stock-movement#release'>Release</a>[]&#62;`}   />

Creates a <a href='/reference/typescript-api/entities/stock-movement#release'>Release</a> for each of the specified OrderItems. For ProductVariants
which are configured to track stock levels, the `ProductVariant.stockAllocated` value is
reduced, indicating that this stock is once again available to buy.


</div>


---

---
title: "TagService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## TagService

<GenerationInfo sourceFile="packages/core/src/service/services/tag.service.ts" sourceLine="25" packageName="@vendure/core" />

Contains methods relating to <a href='/reference/typescript-api/entities/tag#tag'>Tag</a> entities.

```ts title="Signature"
class TagService {
    constructor(connection: TransactionalConnection, listQueryBuilder: ListQueryBuilder)
    findAll(ctx: RequestContext, options?: ListQueryOptions<Tag>) => Promise<PaginatedList<Tag>>;
    findOne(ctx: RequestContext, tagId: ID) => Promise<Tag | undefined>;
    create(ctx: RequestContext, input: CreateTagInput) => ;
    update(ctx: RequestContext, input: UpdateTagInput) => ;
    delete(ctx: RequestContext, id: ID) => Promise<DeletionResponse>;
    valuesToTags(ctx: RequestContext, values: string[]) => Promise<Tag[]>;
    getTagsForEntity(ctx: RequestContext, entity: Type<VendureEntity & Taggable>, id: ID) => Promise<Tag[]>;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, listQueryBuilder: <a href='/reference/typescript-api/data-access/list-query-builder#listquerybuilder'>ListQueryBuilder</a>) => TagService`}   />


### findAll

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, options?: ListQueryOptions&#60;<a href='/reference/typescript-api/entities/tag#tag'>Tag</a>&#62;) => Promise&#60;<a href='/reference/typescript-api/common/paginated-list#paginatedlist'>PaginatedList</a>&#60;<a href='/reference/typescript-api/entities/tag#tag'>Tag</a>&#62;&#62;`}   />


### findOne

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, tagId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/entities/tag#tag'>Tag</a> | undefined&#62;`}   />


### create

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: CreateTagInput) => `}   />


### update

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: UpdateTagInput) => `}   />


### delete

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, id: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;DeletionResponse&#62;`}   />


### valuesToTags

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, values: string[]) => Promise&#60;<a href='/reference/typescript-api/entities/tag#tag'>Tag</a>[]&#62;`}   />


### getTagsForEntity

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, entity: Type&#60;<a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a> &#38; <a href='/reference/typescript-api/entities/interfaces#taggable'>Taggable</a>&#62;, id: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/entities/tag#tag'>Tag</a>[]&#62;`}   />




</div>


---

---
title: "TaxCategoryService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## TaxCategoryService

<GenerationInfo sourceFile="packages/core/src/service/services/tax-category.service.ts" sourceLine="29" packageName="@vendure/core" />

Contains methods relating to <a href='/reference/typescript-api/entities/tax-category#taxcategory'>TaxCategory</a> entities.

```ts title="Signature"
class TaxCategoryService {
    constructor(connection: TransactionalConnection, eventBus: EventBus, listQueryBuilder: ListQueryBuilder)
    findAll(ctx: RequestContext, options?: ListQueryOptions<TaxCategory>) => Promise<PaginatedList<TaxCategory>>;
    findOne(ctx: RequestContext, taxCategoryId: ID) => Promise<TaxCategory | undefined>;
    create(ctx: RequestContext, input: CreateTaxCategoryInput) => Promise<TaxCategory>;
    update(ctx: RequestContext, input: UpdateTaxCategoryInput) => Promise<TaxCategory>;
    delete(ctx: RequestContext, id: ID) => Promise<DeletionResponse>;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, eventBus: <a href='/reference/typescript-api/events/event-bus#eventbus'>EventBus</a>, listQueryBuilder: <a href='/reference/typescript-api/data-access/list-query-builder#listquerybuilder'>ListQueryBuilder</a>) => TaxCategoryService`}   />


### findAll

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, options?: ListQueryOptions&#60;<a href='/reference/typescript-api/entities/tax-category#taxcategory'>TaxCategory</a>&#62;) => Promise&#60;<a href='/reference/typescript-api/common/paginated-list#paginatedlist'>PaginatedList</a>&#60;<a href='/reference/typescript-api/entities/tax-category#taxcategory'>TaxCategory</a>&#62;&#62;`}   />


### findOne

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, taxCategoryId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/entities/tax-category#taxcategory'>TaxCategory</a> | undefined&#62;`}   />


### create

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: CreateTaxCategoryInput) => Promise&#60;<a href='/reference/typescript-api/entities/tax-category#taxcategory'>TaxCategory</a>&#62;`}   />


### update

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: UpdateTaxCategoryInput) => Promise&#60;<a href='/reference/typescript-api/entities/tax-category#taxcategory'>TaxCategory</a>&#62;`}   />


### delete

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, id: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;DeletionResponse&#62;`}   />




</div>


---

---
title: "TaxRateService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## TaxRateService

<GenerationInfo sourceFile="packages/core/src/service/services/tax-rate.service.ts" sourceLine="36" packageName="@vendure/core" />

Contains methods relating to <a href='/reference/typescript-api/entities/tax-rate#taxrate'>TaxRate</a> entities.

```ts title="Signature"
class TaxRateService {
    constructor(connection: TransactionalConnection, eventBus: EventBus, listQueryBuilder: ListQueryBuilder, configService: ConfigService, customFieldRelationService: CustomFieldRelationService)
    findAll(ctx: RequestContext, options?: ListQueryOptions<TaxRate>, relations?: RelationPaths<TaxRate>) => Promise<PaginatedList<TaxRate>>;
    findOne(ctx: RequestContext, taxRateId: ID, relations?: RelationPaths<TaxRate>) => Promise<TaxRate | undefined>;
    create(ctx: RequestContext, input: CreateTaxRateInput) => Promise<TaxRate>;
    update(ctx: RequestContext, input: UpdateTaxRateInput) => Promise<TaxRate>;
    delete(ctx: RequestContext, id: ID) => Promise<DeletionResponse>;
    getApplicableTaxRate(ctx: RequestContext, zone: Zone | ID, taxCategory: TaxCategory | ID) => Promise<TaxRate>;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, eventBus: <a href='/reference/typescript-api/events/event-bus#eventbus'>EventBus</a>, listQueryBuilder: <a href='/reference/typescript-api/data-access/list-query-builder#listquerybuilder'>ListQueryBuilder</a>, configService: ConfigService, customFieldRelationService: CustomFieldRelationService) => TaxRateService`}   />


### findAll

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, options?: ListQueryOptions&#60;<a href='/reference/typescript-api/entities/tax-rate#taxrate'>TaxRate</a>&#62;, relations?: RelationPaths&#60;<a href='/reference/typescript-api/entities/tax-rate#taxrate'>TaxRate</a>&#62;) => Promise&#60;<a href='/reference/typescript-api/common/paginated-list#paginatedlist'>PaginatedList</a>&#60;<a href='/reference/typescript-api/entities/tax-rate#taxrate'>TaxRate</a>&#62;&#62;`}   />


### findOne

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, taxRateId: <a href='/reference/typescript-api/common/id#id'>ID</a>, relations?: RelationPaths&#60;<a href='/reference/typescript-api/entities/tax-rate#taxrate'>TaxRate</a>&#62;) => Promise&#60;<a href='/reference/typescript-api/entities/tax-rate#taxrate'>TaxRate</a> | undefined&#62;`}   />


### create

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: CreateTaxRateInput) => Promise&#60;<a href='/reference/typescript-api/entities/tax-rate#taxrate'>TaxRate</a>&#62;`}   />


### update

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: UpdateTaxRateInput) => Promise&#60;<a href='/reference/typescript-api/entities/tax-rate#taxrate'>TaxRate</a>&#62;`}   />


### delete

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, id: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;DeletionResponse&#62;`}   />


### getApplicableTaxRate

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, zone: <a href='/reference/typescript-api/entities/zone#zone'>Zone</a> | <a href='/reference/typescript-api/common/id#id'>ID</a>, taxCategory: <a href='/reference/typescript-api/entities/tax-category#taxcategory'>TaxCategory</a> | <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/entities/tax-rate#taxrate'>TaxRate</a>&#62;`}   />

Returns the applicable TaxRate based on the specified Zone and TaxCategory. Used when calculating Order
prices.


</div>


---

---
title: "UserService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## UserService

<GenerationInfo sourceFile="packages/core/src/service/services/user.service.ts" sourceLine="38" packageName="@vendure/core" />

Contains methods relating to <a href='/reference/typescript-api/entities/user#user'>User</a> entities.

```ts title="Signature"
class UserService {
    constructor(connection: TransactionalConnection, configService: ConfigService, roleService: RoleService, passwordCipher: PasswordCipher, verificationTokenGenerator: VerificationTokenGenerator, moduleRef: ModuleRef)
    getUserById(ctx: RequestContext, userId: ID) => Promise<User | undefined>;
    getUserByEmailAddress(ctx: RequestContext, emailAddress: string, userType?: 'administrator' | 'customer') => Promise<User | undefined>;
    createCustomerUser(ctx: RequestContext, identifier: string, password?: string) => Promise<User | PasswordValidationError>;
    addNativeAuthenticationMethod(ctx: RequestContext, user: User, identifier: string, password?: string) => Promise<User | PasswordValidationError>;
    createAdminUser(ctx: RequestContext, identifier: string, password: string) => Promise<User>;
    softDelete(ctx: RequestContext, userId: ID) => ;
    setVerificationToken(ctx: RequestContext, user: User) => Promise<User>;
    verifyUserByToken(ctx: RequestContext, verificationToken: string, password?: string) => Promise<ErrorResultUnion<VerifyCustomerAccountResult, User>>;
    setPasswordResetToken(ctx: RequestContext, emailAddress: string) => Promise<User | undefined>;
    resetPasswordByToken(ctx: RequestContext, passwordResetToken: string, password: string) => Promise<
        User | PasswordResetTokenExpiredError | PasswordResetTokenInvalidError | PasswordValidationError
    >;
    changeUserAndNativeIdentifier(ctx: RequestContext, userId: ID, newIdentifier: string) => ;
    setIdentifierChangeToken(ctx: RequestContext, user: User) => Promise<User>;
    changeIdentifierByToken(ctx: RequestContext, token: string) => Promise<
        | { user: User; oldIdentifier: string }
        | IdentifierChangeTokenInvalidError
        | IdentifierChangeTokenExpiredError
    >;
    updatePassword(ctx: RequestContext, userId: ID, currentPassword: string, newPassword: string) => Promise<boolean | InvalidCredentialsError | PasswordValidationError>;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, configService: ConfigService, roleService: <a href='/reference/typescript-api/services/role-service#roleservice'>RoleService</a>, passwordCipher: PasswordCipher, verificationTokenGenerator: VerificationTokenGenerator, moduleRef: ModuleRef) => UserService`}   />


### getUserById

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, userId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/entities/user#user'>User</a> | undefined&#62;`}   />


### getUserByEmailAddress

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, emailAddress: string, userType?: 'administrator' | 'customer') => Promise&#60;<a href='/reference/typescript-api/entities/user#user'>User</a> | undefined&#62;`}   />


### createCustomerUser

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, identifier: string, password?: string) => Promise&#60;<a href='/reference/typescript-api/entities/user#user'>User</a> | PasswordValidationError&#62;`}   />

Creates a new User with the special `customer` Role and using the <a href='/reference/typescript-api/auth/native-authentication-strategy#nativeauthenticationstrategy'>NativeAuthenticationStrategy</a>.
### addNativeAuthenticationMethod

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, user: <a href='/reference/typescript-api/entities/user#user'>User</a>, identifier: string, password?: string) => Promise&#60;<a href='/reference/typescript-api/entities/user#user'>User</a> | PasswordValidationError&#62;`}   />

Adds a new <a href='/reference/typescript-api/entities/authentication-method#nativeauthenticationmethod'>NativeAuthenticationMethod</a> to the User. If the <a href='/reference/typescript-api/auth/auth-options#authoptions'>AuthOptions</a> `requireVerification`
is set to `true` (as is the default), the User will be marked as unverified until the email verification
flow is completed.
### createAdminUser

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, identifier: string, password: string) => Promise&#60;<a href='/reference/typescript-api/entities/user#user'>User</a>&#62;`}   />

Creates a new verified User using the <a href='/reference/typescript-api/auth/native-authentication-strategy#nativeauthenticationstrategy'>NativeAuthenticationStrategy</a>.
### softDelete

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, userId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => `}   />


### setVerificationToken

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, user: <a href='/reference/typescript-api/entities/user#user'>User</a>) => Promise&#60;<a href='/reference/typescript-api/entities/user#user'>User</a>&#62;`}   />

Sets the <a href='/reference/typescript-api/entities/authentication-method#nativeauthenticationmethod'>NativeAuthenticationMethod</a> `verificationToken` as part of the User email verification
flow.
### verifyUserByToken

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, verificationToken: string, password?: string) => Promise&#60;<a href='/reference/typescript-api/errors/error-result-union#errorresultunion'>ErrorResultUnion</a>&#60;VerifyCustomerAccountResult, <a href='/reference/typescript-api/entities/user#user'>User</a>&#62;&#62;`}   />

Verifies a verificationToken by looking for a User which has previously had it set using the
`setVerificationToken()` method, and checks that the token is valid and has not expired.

If valid, the User will be set to `verified: true`.
### setPasswordResetToken

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, emailAddress: string) => Promise&#60;<a href='/reference/typescript-api/entities/user#user'>User</a> | undefined&#62;`}   />

Sets the <a href='/reference/typescript-api/entities/authentication-method#nativeauthenticationmethod'>NativeAuthenticationMethod</a> `passwordResetToken` as part of the User password reset
flow.
### resetPasswordByToken

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, passwordResetToken: string, password: string) => Promise&#60;         <a href='/reference/typescript-api/entities/user#user'>User</a> | PasswordResetTokenExpiredError | PasswordResetTokenInvalidError | PasswordValidationError     &#62;`}   />

Verifies a passwordResetToken by looking for a User which has previously had it set using the
`setPasswordResetToken()` method, and checks that the token is valid and has not expired.

If valid, the User's credentials will be updated with the new password.
### changeUserAndNativeIdentifier

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, userId: <a href='/reference/typescript-api/common/id#id'>ID</a>, newIdentifier: string) => `}   />

Changes the User identifier without an email verification step, so this should be only used when
an Administrator is setting a new email address.
### setIdentifierChangeToken

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, user: <a href='/reference/typescript-api/entities/user#user'>User</a>) => Promise&#60;<a href='/reference/typescript-api/entities/user#user'>User</a>&#62;`}   />

Sets the <a href='/reference/typescript-api/entities/authentication-method#nativeauthenticationmethod'>NativeAuthenticationMethod</a> `identifierChangeToken` as part of the User email address change
flow.
### changeIdentifierByToken

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, token: string) => Promise&#60;         | { user: <a href='/reference/typescript-api/entities/user#user'>User</a>; oldIdentifier: string }         | IdentifierChangeTokenInvalidError         | IdentifierChangeTokenExpiredError     &#62;`}   />

Changes the User identifier as part of the storefront flow used by Customers to set a
new email address, with the token previously set using the `setIdentifierChangeToken()` method.
### updatePassword

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, userId: <a href='/reference/typescript-api/common/id#id'>ID</a>, currentPassword: string, newPassword: string) => Promise&#60;boolean | InvalidCredentialsError | PasswordValidationError&#62;`}   />

Updates the password for a User with the <a href='/reference/typescript-api/entities/authentication-method#nativeauthenticationmethod'>NativeAuthenticationMethod</a>.


</div>


---

---
title: "ZoneService"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ZoneService

<GenerationInfo sourceFile="packages/core/src/service/services/zone.service.ts" sourceLine="37" packageName="@vendure/core" />

Contains methods relating to <a href='/reference/typescript-api/entities/zone#zone'>Zone</a> entities.

```ts title="Signature"
class ZoneService {
    constructor(connection: TransactionalConnection, configService: ConfigService, eventBus: EventBus, translator: TranslatorService, listQueryBuilder: ListQueryBuilder)
    findAll(ctx: RequestContext, options?: ListQueryOptions<Zone>) => Promise<PaginatedList<Zone>>;
    findOne(ctx: RequestContext, zoneId: ID) => Promise<Zone | undefined>;
    getAllWithMembers(ctx: RequestContext) => Promise<Zone[]>;
    create(ctx: RequestContext, input: CreateZoneInput) => Promise<Zone>;
    update(ctx: RequestContext, input: UpdateZoneInput) => Promise<Zone>;
    delete(ctx: RequestContext, id: ID) => Promise<DeletionResponse>;
    addMembersToZone(ctx: RequestContext, { memberIds, zoneId }: MutationAddMembersToZoneArgs) => Promise<Zone>;
    removeMembersFromZone(ctx: RequestContext, { memberIds, zoneId }: MutationRemoveMembersFromZoneArgs) => Promise<Zone>;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, configService: ConfigService, eventBus: <a href='/reference/typescript-api/events/event-bus#eventbus'>EventBus</a>, translator: <a href='/reference/typescript-api/service-helpers/translator-service#translatorservice'>TranslatorService</a>, listQueryBuilder: <a href='/reference/typescript-api/data-access/list-query-builder#listquerybuilder'>ListQueryBuilder</a>) => ZoneService`}   />


### findAll

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, options?: ListQueryOptions&#60;<a href='/reference/typescript-api/entities/zone#zone'>Zone</a>&#62;) => Promise&#60;<a href='/reference/typescript-api/common/paginated-list#paginatedlist'>PaginatedList</a>&#60;<a href='/reference/typescript-api/entities/zone#zone'>Zone</a>&#62;&#62;`}   />


### findOne

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, zoneId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/entities/zone#zone'>Zone</a> | undefined&#62;`}   />


### getAllWithMembers

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => Promise&#60;<a href='/reference/typescript-api/entities/zone#zone'>Zone</a>[]&#62;`}   />


### create

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: CreateZoneInput) => Promise&#60;<a href='/reference/typescript-api/entities/zone#zone'>Zone</a>&#62;`}   />


### update

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: UpdateZoneInput) => Promise&#60;<a href='/reference/typescript-api/entities/zone#zone'>Zone</a>&#62;`}   />


### delete

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, id: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;DeletionResponse&#62;`}   />


### addMembersToZone

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, { memberIds, zoneId }: MutationAddMembersToZoneArgs) => Promise&#60;<a href='/reference/typescript-api/entities/zone#zone'>Zone</a>&#62;`}   />


### removeMembersFromZone

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, { memberIds, zoneId }: MutationRemoveMembersFromZoneArgs) => Promise&#60;<a href='/reference/typescript-api/entities/zone#zone'>Zone</a>&#62;`}   />




</div>


---

---
title: "CleanupOrphanedSettingsStoreEntriesOptions"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## CleanupOrphanedSettingsStoreEntriesOptions

<GenerationInfo sourceFile="packages/core/src/config/settings-store/settings-store-types.ts" sourceLine="240" packageName="@vendure/core" since="3.4.0" />

Options for cleaning up orphaned settings store entries.

```ts title="Signature"
interface CleanupOrphanedSettingsStoreEntriesOptions {
    dryRun?: boolean;
    olderThan?: string;
    maxDeleteCount?: number;
    batchSize?: number;
}
```

<div className="members-wrapper">

### dryRun

<MemberInfo kind="property" type={`boolean`} default={`false`}   />

If true, perform a dry run without actually deleting entries.
### olderThan

<MemberInfo kind="property" type={`string`} default={`'7d'`}   />

Only delete entries older than this duration.
Examples: '30d', '7d', '1h', '30m'
### maxDeleteCount

<MemberInfo kind="property" type={`number`} default={`1000`}   />

Maximum number of entries to delete in a single operation.
### batchSize

<MemberInfo kind="property" type={`number`} default={`100`}   />

Batch size for deletion operations.


</div>


---

---
title: "CleanupOrphanedSettingsStoreEntriesResult"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## CleanupOrphanedSettingsStoreEntriesResult

<GenerationInfo sourceFile="packages/core/src/config/settings-store/settings-store-types.ts" sourceLine="278" packageName="@vendure/core" since="3.4.0" />

Result of a cleanup operation for orphaned settings store entries.

```ts title="Signature"
interface CleanupOrphanedSettingsStoreEntriesResult {
    deletedCount: number;
    dryRun: boolean;
    deletedEntries: OrphanedSettingsStoreEntry[];
}
```

<div className="members-wrapper">

### deletedCount

<MemberInfo kind="property" type={`number`}   />

Number of entries that were (or would be) deleted.
### dryRun

<MemberInfo kind="property" type={`boolean`}   />

Whether this was a dry run.
### deletedEntries

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/settings-store/orphaned-settings-store-entry#orphanedsettingsstoreentry'>OrphanedSettingsStoreEntry</a>[]`}   />

Sample of deleted entries (for logging/audit purposes).


</div>


---

---
title: "SettingsStore"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## cleanOrphanedSettingsStoreTask

<GenerationInfo sourceFile="packages/core/src/config/settings-store/clean-orphaned-settings-store-task.ts" sourceLine="39" packageName="@vendure/core" since="3.4.0" />

A <a href='/reference/typescript-api/scheduled-tasks/scheduled-task#scheduledtask'>ScheduledTask</a> that cleans up orphaned settings store entries from the database.
Orphaned entries are entries that no longer have corresponding field definitions
in the settings store configuration.

This task can be configured with options for dry-run mode, age thresholds,
and batch processing settings. Users can override or disable this task entirely
using the existing ScheduledTask APIs.

*Example*

```ts
// Override the default task with custom options
const customCleanupTask = new ScheduledTask({
  id: 'clean-orphaned-settings-store',
  description: 'Custom orphaned settings store cleanup',
  schedule: cron => cron.every(7).days(),
  async execute({ injector }) {
    const settingsStoreService = injector.get(SettingsStoreService);
    return settingsStoreService.cleanupOrphanedEntries({
      olderThan: '30d',
      maxDeleteCount: 500,
      batchSize: 50,
    });
  },
});
```



---

---
title: "OrphanedSettingsStoreEntry"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## OrphanedSettingsStoreEntry

<GenerationInfo sourceFile="packages/core/src/config/settings-store/settings-store-types.ts" sourceLine="207" packageName="@vendure/core" since="3.4.0" />

Represents an orphaned settings store entry that no longer has a corresponding
field definition in the configuration.

```ts title="Signature"
interface OrphanedSettingsStoreEntry {
    key: string;
    scope: string;
    updatedAt: Date;
    valuePreview: string;
}
```

<div className="members-wrapper">

### key

<MemberInfo kind="property" type={`string`}   />

The orphaned key.
### scope

<MemberInfo kind="property" type={`string`}   />

The scope of the orphaned entry.
### updatedAt

<MemberInfo kind="property" type={`Date`}   />

When the entry was last updated.
### valuePreview

<MemberInfo kind="property" type={`string`}   />

Preview of the stored value (truncated for large values).


</div>


---

---
title: "SetSettingsStoreValueResult"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## SetSettingsStoreValueResult

<GenerationInfo sourceFile="packages/core/src/config/settings-store/settings-store-types.ts" sourceLine="179" packageName="@vendure/core" since="3.4.0" />

Result type for settings store set operations, providing detailed feedback
about the success or failure of each operation.

```ts title="Signature"
interface SetSettingsStoreValueResult {
    key: string;
    result: boolean;
    error?: string;
}
```

<div className="members-wrapper">

### key

<MemberInfo kind="property" type={`string`}   />

The key that was attempted to be set.
### result

<MemberInfo kind="property" type={`boolean`}   />

Whether the set operation was successful.
### error

<MemberInfo kind="property" type={`string`}   />

Error message if the operation failed, null if successful.


</div>


---

---
title: "SettingsStoreFieldConfig"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## SettingsStoreFieldConfig

<GenerationInfo sourceFile="packages/core/src/config/settings-store/settings-store-types.ts" sourceLine="41" packageName="@vendure/core" since="3.4.0" />

Configuration for a settings store field, defining how it should be stored,
scoped, validated, and accessed.

```ts title="Signature"
interface SettingsStoreFieldConfig {
    name: string;
    scope?: SettingsStoreScopeFunction;
    readonly?: boolean;
    requiresPermission?: Array<Permission | string> | Permission | string;
    validate?: (
        value: any,
        injector: Injector,
        ctx: RequestContext,
    ) => string | LocalizedString[] | void | Promise<string | LocalizedString[] | void>;
}
```

<div className="members-wrapper">

### name

<MemberInfo kind="property" type={`string`}   />

The name of the field. This will be combined with the namespace
to create the full key (e.g., 'dashboard.theme').
### scope

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/settings-store/settings-store-scope-function#settingsstorescopefunction'>SettingsStoreScopeFunction</a>`}   />

Function that determines how this field should be scoped.
Defaults to global scoping (no isolation).
### readonly

<MemberInfo kind="property" type={`boolean`} default={`false`}   />

Whether this field is readonly via the GraphQL API.
Readonly fields can still be modified programmatically via a service.
### requiresPermission

<MemberInfo kind="property" type={`Array&#60;<a href='/reference/typescript-api/common/permission#permission'>Permission</a> | string&#62; | <a href='/reference/typescript-api/common/permission#permission'>Permission</a> | string`}   />

Permissions required to access this field. If not specified,
basic authentication is required for admin API access.
### validate

<MemberInfo kind="property" type={`(         value: any,         injector: <a href='/reference/typescript-api/common/injector#injector'>Injector</a>,         ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>,     ) =&#62; string | LocalizedString[] | void | Promise&#60;string | LocalizedString[] | void&#62;`}   />

Custom validation function for field values.


</div>


---

---
title: "SettingsStoreRegistration"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## SettingsStoreRegistration

<GenerationInfo sourceFile="packages/core/src/config/settings-store/settings-store-types.ts" sourceLine="89" packageName="@vendure/core" since="3.4.0" />

Configuration for registering a namespace of settings store fields.

```ts title="Signature"
interface SettingsStoreRegistration {
    namespace: string;
    fields: SettingsStoreFieldConfig[];
}
```

<div className="members-wrapper">

### namespace

<MemberInfo kind="property" type={`string`}   />

The namespace for these fields (e.g., 'dashboard', 'payment').
Field names will be prefixed with this namespace.
### fields

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/settings-store/settings-store-field-config#settingsstorefieldconfig'>SettingsStoreFieldConfig</a>[]`}   />

Array of field configurations for this namespace.


</div>


---

---
title: "SettingsStoreScopeFunction"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## SettingsStoreScopeFunction

<GenerationInfo sourceFile="packages/core/src/config/settings-store/settings-store-types.ts" sourceLine="27" packageName="@vendure/core" since="3.4.0" />

A function that determines how a settings store entry should be scoped.
Returns a string that will be used as the scope key for storage isolation.

*Example*

```ts
// User-specific scoping
const userScope: SettingsStoreScopeFunction = ({ ctx }) => ctx.activeUserId || '';

// Channel-specific scoping
const channelScope: SettingsStoreScopeFunction = ({ ctx }) => ctx.channelId || '';

// User and channel scoping
const userAndChannelScope: SettingsStoreScopeFunction = ({ ctx }) =>
  `${ctx.activeUserId || ''}:${ctx.channelId || ''}`;
```

```ts title="Signature"
type SettingsStoreScopeFunction = (params: {
    key: string;
    value?: any;
    ctx: RequestContext;
}) => string
```


---

---
title: "SettingsStoreScopes"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## SettingsStoreScopes

<GenerationInfo sourceFile="packages/core/src/config/settings-store/settings-store-types.ts" sourceLine="144" packageName="@vendure/core" since="3.4.0" />

Pre-built scope functions for common scoping patterns.

*Example*

```ts
const config: VendureConfig = {
  settingsStoreFields: {
    dashboard: [
      {
        name: 'theme',
        scope: SettingsStoreScopes.user, // User-specific
      },
      {
        name: 'currency',
        scope: SettingsStoreScopes.channel, // Channel-specific
      },
      {
        name: 'tableFilters',
        scope: SettingsStoreScopes.userAndChannel, // User-specific per channel
      }
    ]
  }
};
```



---

---
title: "CheckShippingEligibilityCheckerFn"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## CheckShippingEligibilityCheckerFn

<GenerationInfo sourceFile="packages/core/src/config/shipping-method/shipping-eligibility-checker.ts" sourceLine="138" packageName="@vendure/core" />

A function which implements logic to determine whether a given <a href='/reference/typescript-api/entities/order#order'>Order</a> is eligible for
a particular shipping method. Once a ShippingMethod has been assigned to an Order, this
function will be called on every change to the Order (e.g. updating quantities, adding/removing
items etc).

If the code running in this function is expensive, then consider also defining
a <a href='/reference/typescript-api/shipping/should-run-check-fn#shouldruncheckfn'>ShouldRunCheckFn</a> to avoid unnecessary calls.

```ts title="Signature"
type CheckShippingEligibilityCheckerFn<T extends ConfigArgs> = (
    ctx: RequestContext,
    order: Order,
    args: ConfigArgValues<T>,
    method: ShippingMethod,
) => boolean | Promise<boolean>
```


---

---
title: "DefaultShippingLineAssignmentStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DefaultShippingLineAssignmentStrategy

<GenerationInfo sourceFile="packages/core/src/config/shipping-method/default-shipping-line-assignment-strategy.ts" sourceLine="16" packageName="@vendure/core" since="2.0.0" />

This is the default <a href='/reference/typescript-api/shipping/shipping-line-assignment-strategy#shippinglineassignmentstrategy'>ShippingLineAssignmentStrategy</a> which simply assigns all OrderLines to the
ShippingLine, and is suitable for the most common scenario of a single shipping method per Order.

```ts title="Signature"
class DefaultShippingLineAssignmentStrategy implements ShippingLineAssignmentStrategy {
    assignShippingLineToOrderLines(ctx: RequestContext, shippingLine: ShippingLine, order: Order) => OrderLine[] | Promise<OrderLine[]>;
}
```
* Implements: <code><a href='/reference/typescript-api/shipping/shipping-line-assignment-strategy#shippinglineassignmentstrategy'>ShippingLineAssignmentStrategy</a></code>



<div className="members-wrapper">

### assignShippingLineToOrderLines

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, shippingLine: <a href='/reference/typescript-api/entities/shipping-line#shippingline'>ShippingLine</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>) => <a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a>[] | Promise&#60;<a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a>[]&#62;`}   />




</div>


---

---
title: "Shipping"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "ShippingCalculator"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ShippingCalculator

<GenerationInfo sourceFile="packages/core/src/config/shipping-method/shipping-calculator.ts" sourceLine="48" packageName="@vendure/core" />

The ShippingCalculator is used by a <a href='/reference/typescript-api/entities/shipping-method#shippingmethod'>ShippingMethod</a> to calculate the price of shipping on a given <a href='/reference/typescript-api/entities/order#order'>Order</a>.

*Example*

```ts
const flatRateCalculator = new ShippingCalculator({
  code: 'flat-rate-calculator',
  description: [{ languageCode: LanguageCode.en, value: 'Default Flat-Rate Shipping Calculator' }],
  args: {
    rate: {
      type: 'int',
      ui: { component: 'currency-form-input' },
    },
    taxRate: {
      type: 'int',
      ui: { component: 'number-form-input', suffix: '%' },
    },
  },
  calculate: (ctx, order, args) => {
    return {
      price: args.rate,
      taxRate: args.taxRate,
      priceIncludesTax: ctx.channel.pricesIncludeTax,
    };
  },
});
```

```ts title="Signature"
class ShippingCalculator<T extends ConfigArgs = ConfigArgs> extends ConfigurableOperationDef<T> {
    constructor(config: ShippingCalculatorConfig<T>)
}
```
* Extends: <code><a href='/reference/typescript-api/configurable-operation-def/#configurableoperationdef'>ConfigurableOperationDef</a>&#60;T&#62;</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(config: ShippingCalculatorConfig&#60;T&#62;) => ShippingCalculator`}   />




</div>


## ShippingCalculationResult

<GenerationInfo sourceFile="packages/core/src/config/shipping-method/shipping-calculator.ts" sourceLine="79" packageName="@vendure/core" />

The return value of the <a href='/reference/typescript-api/shipping/shipping-calculator#calculateshippingfn'>CalculateShippingFn</a>.

```ts title="Signature"
interface ShippingCalculationResult {
    price: number;
    priceIncludesTax: boolean;
    taxRate: number;
    metadata?: Record<string, any>;
}
```

<div className="members-wrapper">

### price

<MemberInfo kind="property" type={`number`}   />

The shipping price without any taxes.
### priceIncludesTax

<MemberInfo kind="property" type={`boolean`}   />

Whether or not the given price already includes taxes.
### taxRate

<MemberInfo kind="property" type={`number`}   />

The tax rate applied to the shipping price.
### metadata

<MemberInfo kind="property" type={`Record&#60;string, any&#62;`}   />

Arbitrary metadata may be returned from the calculation function. This can be used
e.g. to return data on estimated delivery times or any other data which may be
needed in the storefront application when listing eligible shipping methods.


</div>


## CalculateShippingFn

<GenerationInfo sourceFile="packages/core/src/config/shipping-method/shipping-calculator.ts" sourceLine="119" packageName="@vendure/core" />

A function which implements the specific shipping calculation logic. It takes an <a href='/reference/typescript-api/entities/order#order'>Order</a> and
an arguments object and should return the shipping price as an integer in cents.

Should return a <a href='/reference/typescript-api/shipping/shipping-calculator#shippingcalculationresult'>ShippingCalculationResult</a> object.

```ts title="Signature"
type CalculateShippingFn<T extends ConfigArgs> = (
    ctx: RequestContext,
    order: Order,
    args: ConfigArgValues<T>,
    method: ShippingMethod,
) => CalculateShippingFnResult
```


---

---
title: "ShippingEligibilityCheckerConfig"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ShippingEligibilityCheckerConfig

<GenerationInfo sourceFile="packages/core/src/config/shipping-method/shipping-eligibility-checker.ts" sourceLine="23" packageName="@vendure/core" />

Configuration passed into the constructor of a <a href='/reference/typescript-api/shipping/shipping-eligibility-checker#shippingeligibilitychecker'>ShippingEligibilityChecker</a> to
configure its behavior.

```ts title="Signature"
interface ShippingEligibilityCheckerConfig<T extends ConfigArgs> extends ConfigurableOperationDefOptions<T> {
    check: CheckShippingEligibilityCheckerFn<T>;
    shouldRunCheck?: ShouldRunCheckFn<T>;
}
```
* Extends: <code><a href='/reference/typescript-api/configurable-operation-def/configurable-operation-def-options#configurableoperationdefoptions'>ConfigurableOperationDefOptions</a>&#60;T&#62;</code>



<div className="members-wrapper">

### check

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/shipping/check-shipping-eligibility-checker-fn#checkshippingeligibilitycheckerfn'>CheckShippingEligibilityCheckerFn</a>&#60;T&#62;`}   />


### shouldRunCheck

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/shipping/should-run-check-fn#shouldruncheckfn'>ShouldRunCheckFn</a>&#60;T&#62;`}   />




</div>


---

---
title: "ShippingEligibilityChecker"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ShippingEligibilityChecker

<GenerationInfo sourceFile="packages/core/src/config/shipping-method/shipping-eligibility-checker.ts" sourceLine="50" packageName="@vendure/core" />

The ShippingEligibilityChecker class is used to check whether an order qualifies for a
given <a href='/reference/typescript-api/entities/shipping-method#shippingmethod'>ShippingMethod</a>.

*Example*

```ts
const minOrderTotalEligibilityChecker = new ShippingEligibilityChecker({
    code: 'min-order-total-eligibility-checker',
    description: [{ languageCode: LanguageCode.en, value: 'Checks that the order total is above some minimum value' }],
    args: {
        orderMinimum: { type: 'int', ui: { component: 'currency-form-input' } },
    },
    check: (ctx, order, args) => {
        return order.totalWithTax >= args.orderMinimum;
    },
});
```

```ts title="Signature"
class ShippingEligibilityChecker<T extends ConfigArgs = ConfigArgs> extends ConfigurableOperationDef<T> {
    constructor(config: ShippingEligibilityCheckerConfig<T>)
    init(injector: Injector) => ;
    toJSON() => ;
}
```
* Extends: <code><a href='/reference/typescript-api/configurable-operation-def/#configurableoperationdef'>ConfigurableOperationDef</a>&#60;T&#62;</code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(config: <a href='/reference/typescript-api/shipping/shipping-eligibility-checker-config#shippingeligibilitycheckerconfig'>ShippingEligibilityCheckerConfig</a>&#60;T&#62;) => ShippingEligibilityChecker`}   />


### init

<MemberInfo kind="method" type={`(injector: <a href='/reference/typescript-api/common/injector#injector'>Injector</a>) => `}   />


### toJSON

<MemberInfo kind="method" type={`() => `}   />




</div>


---

---
title: "ShippingLineAssignmentStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ShippingLineAssignmentStrategy

<GenerationInfo sourceFile="packages/core/src/config/shipping-method/shipping-line-assignment-strategy.ts" sourceLine="52" packageName="@vendure/core" since="2.0.0" />

This strategy is used to assign a given <a href='/reference/typescript-api/entities/shipping-line#shippingline'>ShippingLine</a> to one or more <a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a>s of the Order.
This allows you to set multiple shipping methods for a single order, each assigned a different subset of
OrderLines.

The <a href='/reference/typescript-api/shipping/default-shipping-line-assignment-strategy#defaultshippinglineassignmentstrategy'>DefaultShippingLineAssignmentStrategy</a> simply assigns _all_ OrderLines, so is suitable for the
most common scenario of a single shipping method per Order.

:::info

This is configured via the `shippingOptions.shippingLineAssignmentStrategy` property of
your VendureConfig.

:::

Here's an example of a custom ShippingLineAssignmentStrategy which assigns digital products to a
different ShippingLine to physical products:

```ts
import {
    Order,
    OrderLine,
    RequestContext,
    ShippingLine,
    ShippingLineAssignmentStrategy,
} from '@vendure/core';

export class DigitalShippingLineAssignmentStrategy implements ShippingLineAssignmentStrategy {
    assignShippingLineToOrderLines(
        ctx: RequestContext,
        shippingLine: ShippingLine,
        order: Order,
    ): OrderLine[] | Promise<OrderLine[]> {
        if (shippingLine.shippingMethod.customFields.isDigital) {
            return order.lines.filter(l => l.productVariant.customFields.isDigital);
        } else {
            return order.lines.filter(l => !l.productVariant.customFields.isDigital);
        }
    }
}
```

```ts title="Signature"
interface ShippingLineAssignmentStrategy extends InjectableStrategy {
    assignShippingLineToOrderLines(
        ctx: RequestContext,
        shippingLine: ShippingLine,
        order: Order,
    ): OrderLine[] | Promise<OrderLine[]>;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### assignShippingLineToOrderLines

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, shippingLine: <a href='/reference/typescript-api/entities/shipping-line#shippingline'>ShippingLine</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>) => <a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a>[] | Promise&#60;<a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a>[]&#62;`}   />




</div>


---

---
title: "ShippingOptions"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ShippingOptions

<GenerationInfo sourceFile="packages/core/src/config/vendure-config.ts" sourceLine="799" packageName="@vendure/core" />



```ts title="Signature"
interface ShippingOptions {
    shippingEligibilityCheckers?: Array<ShippingEligibilityChecker<any>>;
    shippingCalculators?: Array<ShippingCalculator<any>>;
    shippingLineAssignmentStrategy?: ShippingLineAssignmentStrategy;
    customFulfillmentProcess?: Array<FulfillmentProcess<any>>;
    process?: Array<FulfillmentProcess<any>>;
    fulfillmentHandlers?: Array<FulfillmentHandler<any>>;
}
```

<div className="members-wrapper">

### shippingEligibilityCheckers

<MemberInfo kind="property" type={`Array&#60;<a href='/reference/typescript-api/shipping/shipping-eligibility-checker#shippingeligibilitychecker'>ShippingEligibilityChecker</a>&#60;any&#62;&#62;`}   />

An array of available ShippingEligibilityCheckers for use in configuring ShippingMethods
### shippingCalculators

<MemberInfo kind="property" type={`Array&#60;<a href='/reference/typescript-api/shipping/shipping-calculator#shippingcalculator'>ShippingCalculator</a>&#60;any&#62;&#62;`}   />

An array of available ShippingCalculators for use in configuring ShippingMethods
### shippingLineAssignmentStrategy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/shipping/shipping-line-assignment-strategy#shippinglineassignmentstrategy'>ShippingLineAssignmentStrategy</a>`}  since="2.0.0"  />

This strategy is used to assign a given <a href='/reference/typescript-api/entities/shipping-line#shippingline'>ShippingLine</a> to one or more <a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a>s of the Order.
This allows you to set multiple shipping methods for a single order, each assigned a different subset of
OrderLines.
### customFulfillmentProcess

<MemberInfo kind="property" type={`Array&#60;<a href='/reference/typescript-api/fulfillment/fulfillment-process#fulfillmentprocess'>FulfillmentProcess</a>&#60;any&#62;&#62;`}   />

Allows the definition of custom states and transition logic for the fulfillment process state machine.
Takes an array of objects implementing the <a href='/reference/typescript-api/fulfillment/fulfillment-process#fulfillmentprocess'>FulfillmentProcess</a> interface.
### process

<MemberInfo kind="property" type={`Array&#60;<a href='/reference/typescript-api/fulfillment/fulfillment-process#fulfillmentprocess'>FulfillmentProcess</a>&#60;any&#62;&#62;`} default={`<a href='/reference/typescript-api/fulfillment/fulfillment-process#defaultfulfillmentprocess'>defaultFulfillmentProcess</a>`}  since="2.0.0"  />

Allows the definition of custom states and transition logic for the fulfillment process state machine.
Takes an array of objects implementing the <a href='/reference/typescript-api/fulfillment/fulfillment-process#fulfillmentprocess'>FulfillmentProcess</a> interface.
### fulfillmentHandlers

<MemberInfo kind="property" type={`Array&#60;<a href='/reference/typescript-api/fulfillment/fulfillment-handler#fulfillmenthandler'>FulfillmentHandler</a>&#60;any&#62;&#62;`}   />

An array of available FulfillmentHandlers.


</div>


---

---
title: "ShouldRunCheckFn"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ShouldRunCheckFn

<GenerationInfo sourceFile="packages/core/src/config/shipping-method/shipping-eligibility-checker.ts" sourceLine="173" packageName="@vendure/core" />

An optional method which is used to decide whether to run the `check()` function.
Returns a JSON-compatible object which is cached and compared between calls.
If the value is the same, then the `check()` function is not called.

Use of this function is an optimization technique which can be useful when
the `check()` function is expensive and should be kept to an absolute minimum.

*Example*

```ts
const optimizedChecker = new ShippingEligibilityChecker({
  code: 'example',
  description: [],
  args: {},
  check: async (ctx, order) => {
    // some slow, expensive function here
  },
  shouldRunCheck: (ctx, order) => {
    // Will only run the `check()` function any time
    // the shippingAddress object has changed.
    return order.shippingAddress;
  },
});
```

```ts title="Signature"
type ShouldRunCheckFn<T extends ConfigArgs> = (
    ctx: RequestContext,
    order: Order,
    args: ConfigArgValues<T>,
    method: ShippingMethod,
) => Json | Promise<Json>
```


---

---
title: "FSM"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## FSM

<GenerationInfo sourceFile="packages/core/src/common/finite-state-machine/finite-state-machine.ts" sourceLine="12" packageName="@vendure/core" />

A simple type-safe finite state machine. This is used internally to control the Order process, ensuring that
the state of Orders, Payments, Fulfillments and Refunds follows a well-defined behaviour.

```ts title="Signature"
class FSM<T extends string, Data = any> {
    constructor(config: StateMachineConfig<T, Data>, initialState: T)
    initialState: T
    currentState: T
    transitionTo(state: T, data: Data) => Promise<{ finalize: () => Promise<any> }>;
    jumpTo(state: T) => ;
    getNextStates() => readonly T[];
    canTransitionTo(state: T) => boolean;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(config: <a href='/reference/typescript-api/state-machine/state-machine-config#statemachineconfig'>StateMachineConfig</a>&#60;T, Data&#62;, initialState: T) => FSM`}   />


### initialState

<MemberInfo kind="property" type={`T`}   />


### currentState

<MemberInfo kind="property" type={`T`}   />


### transitionTo

<MemberInfo kind="method" type={`(state: T, data: Data) => Promise&#60;{ finalize: () =&#62; Promise&#60;any&#62; }&#62;`}   />


### jumpTo

<MemberInfo kind="method" type={`(state: T) => `}   />


### getNextStates

<MemberInfo kind="method" type={`() => readonly T[]`}   />


### canTransitionTo

<MemberInfo kind="method" type={`(state: T) => boolean`}   />




</div>


---

---
title: "State Machine"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "StateMachineConfig"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## StateMachineConfig

<GenerationInfo sourceFile="packages/core/src/common/finite-state-machine/types.ts" sourceLine="89" packageName="@vendure/core" />

The config object used to instantiate a new <a href='/reference/typescript-api/state-machine/fsm#fsm'>FSM</a> instance.

```ts title="Signature"
interface StateMachineConfig<T extends string, Data = undefined> {
    readonly transitions: Transitions<T>;
    onTransitionStart?: OnTransitionStartFn<T, Data>;
    onTransitionEnd?: OnTransitionEndFn<T, Data>;
    onError?: OnTransitionErrorFn<T>;
}
```

<div className="members-wrapper">

### transitions

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/state-machine/transitions#transitions'>Transitions</a>&#60;T&#62;`}   />

Defines the available states of the state machine as well as the permitted
transitions from one state to another.
### onTransitionStart

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/state-machine/state-machine-config#ontransitionstartfn'>OnTransitionStartFn</a>&#60;T, Data&#62;`}   />

Called before a transition takes place. If the function resolves to `false` or a string, then the transition
will be cancelled. In the case of a string, the string (error message) will be forwarded to the onError handler.

If this function returns a value resolving to `true` or `void` (no return value), then the transition
will be permitted.
### onTransitionEnd

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/state-machine/state-machine-config#ontransitionendfn'>OnTransitionEndFn</a>&#60;T, Data&#62;`}   />

Called after a transition has taken place.
### onError

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/state-machine/state-machine-config#ontransitionerrorfn'>OnTransitionErrorFn</a>&#60;T&#62;`}   />

Called when a transition is prevented and the `onTransitionStart` handler has returned an
error message.


</div>


## OnTransitionStartFn

<GenerationInfo sourceFile="packages/core/src/common/finite-state-machine/types.ts" sourceLine="48" packageName="@vendure/core" />

Called before a transition takes place. If the function resolves to `false` or a string, then the transition
will be cancelled. In the case of a string, the string (error message) will be forwarded to the onError handler.

If this function returns a value resolving to `true` or `void` (no return value), then the transition
will be permitted.

```ts title="Signature"
type OnTransitionStartFn<T extends string, Data> = (
    fromState: T,
    toState: T,
    data: Data,
) => boolean | string | void | Promise<boolean | string | void> | Observable<boolean | string | void>
```


## OnTransitionErrorFn

<GenerationInfo sourceFile="packages/core/src/common/finite-state-machine/types.ts" sourceLine="62" packageName="@vendure/core" />

Called when a transition is prevented and the `onTransitionStart` handler has returned an
error message.

```ts title="Signature"
type OnTransitionErrorFn<T extends string> = (
    fromState: T,
    toState: T,
    message?: string,
) => void | Promise<void> | Observable<void>
```


## OnTransitionEndFn

<GenerationInfo sourceFile="packages/core/src/common/finite-state-machine/types.ts" sourceLine="75" packageName="@vendure/core" />

Called after a transition has taken place.

```ts title="Signature"
type OnTransitionEndFn<T extends string, Data> = (
    fromState: T,
    toState: T,
    data: Data,
) => void | Promise<void> | Observable<void>
```


---

---
title: "Transitions"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## Transitions

<GenerationInfo sourceFile="packages/core/src/common/finite-state-machine/types.ts" sourceLine="30" packageName="@vendure/core" />

A type which is used to define valid states and transitions for a state machine based
on <a href='/reference/typescript-api/state-machine/fsm#fsm'>FSM</a>.

*Example*

```ts
type LightColor = 'Green' | 'Amber' | 'Red';

const trafficLightTransitions: Transitions<LightColor> = {
  Green: {
    to: ['Amber'],
  },
  Amber: {
    to: ['Red'],
  },
  Red: {
    to: ['Green'],
  },
};
```

The `mergeStrategy` property defines how to handle the merging of states when one set of
transitions is being merged with another (as in the case of defining a <a href='/reference/typescript-api/orders/order-process#orderprocess'>OrderProcess</a>)

```ts title="Signature"
type Transitions<State extends string, Target extends string = State> = {
    [S in State]: {
        to: Readonly<Target[]>;
        mergeStrategy?: 'merge' | 'replace';
    };
}
```


---

---
title: "AddressBasedTaxZoneStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## AddressBasedTaxZoneStrategy

<GenerationInfo sourceFile="packages/core/src/config/tax/address-based-tax-zone-strategy.ts" sourceLine="40" packageName="@vendure/core" since="3.1.0" />

Address based <a href='/reference/typescript-api/tax/tax-zone-strategy#taxzonestrategy'>TaxZoneStrategy</a> which tries to find the applicable <a href='/reference/typescript-api/entities/zone#zone'>Zone</a> based on the
country of the shipping address of the Order.
This is useful for shops that do cross-border B2C orders and use the One-Stop-Shop (OSS) VAT scheme.

Returns the default <a href='/reference/typescript-api/entities/channel#channel'>Channel</a>'s default tax zone if no applicable zone is found.

:::info

This is configured via `taxOptions.taxZoneStrategy = new AddressBasedTaxZoneStrategy()` in
your VendureConfig.

:::

*Example*

```ts
import { VendureConfig, AddressBasedTaxZoneStrategy } from '@vendure/core';

export const config: VendureConfig = {
  // other options...
  taxOptions: {
    // highlight-next-line
    taxZoneStrategy: new AddressBasedTaxZoneStrategy(),
  },
};
```

```ts title="Signature"
class AddressBasedTaxZoneStrategy implements TaxZoneStrategy {
    determineTaxZone(ctx: RequestContext, zones: Zone[], channel: Channel, order?: Order) => Zone;
}
```
* Implements: <code><a href='/reference/typescript-api/tax/tax-zone-strategy#taxzonestrategy'>TaxZoneStrategy</a></code>



<div className="members-wrapper">

### determineTaxZone

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, zones: <a href='/reference/typescript-api/entities/zone#zone'>Zone</a>[], channel: <a href='/reference/typescript-api/entities/channel#channel'>Channel</a>, order?: <a href='/reference/typescript-api/entities/order#order'>Order</a>) => <a href='/reference/typescript-api/entities/zone#zone'>Zone</a>`}   />




</div>


---

---
title: "DefaultTaxLineCalculationStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DefaultTaxLineCalculationStrategy

<GenerationInfo sourceFile="packages/core/src/config/tax/default-tax-line-calculation-strategy.ts" sourceLine="12" packageName="@vendure/core" />

The default <a href='/reference/typescript-api/tax/tax-line-calculation-strategy#taxlinecalculationstrategy'>TaxLineCalculationStrategy</a> which applies a single TaxLine to the OrderLine
based on the applicable <a href='/reference/typescript-api/entities/tax-rate#taxrate'>TaxRate</a>.

```ts title="Signature"
class DefaultTaxLineCalculationStrategy implements TaxLineCalculationStrategy {
    calculate(args: CalculateTaxLinesArgs) => TaxLine[];
}
```
* Implements: <code><a href='/reference/typescript-api/tax/tax-line-calculation-strategy#taxlinecalculationstrategy'>TaxLineCalculationStrategy</a></code>



<div className="members-wrapper">

### calculate

<MemberInfo kind="method" type={`(args: <a href='/reference/typescript-api/tax/tax-line-calculation-strategy#calculatetaxlinesargs'>CalculateTaxLinesArgs</a>) => TaxLine[]`}   />




</div>


---

---
title: "DefaultTaxZoneStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## DefaultTaxZoneStrategy

<GenerationInfo sourceFile="packages/core/src/config/tax/default-tax-zone-strategy.ts" sourceLine="15" packageName="@vendure/core" />

A default method of determining Zone for tax calculations. The strategy simply returns the default
tax zone of the Channel. In many cases you actually want to base the tax zone
on the shipping or billing address of the Order, in which case you would use the
<a href='/reference/typescript-api/tax/address-based-tax-zone-strategy#addressbasedtaxzonestrategy'>AddressBasedTaxZoneStrategy</a>.

```ts title="Signature"
class DefaultTaxZoneStrategy implements TaxZoneStrategy {
    determineTaxZone(ctx: RequestContext, zones: Zone[], channel: Channel, order?: Order) => Zone;
}
```
* Implements: <code><a href='/reference/typescript-api/tax/tax-zone-strategy#taxzonestrategy'>TaxZoneStrategy</a></code>



<div className="members-wrapper">

### determineTaxZone

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, zones: <a href='/reference/typescript-api/entities/zone#zone'>Zone</a>[], channel: <a href='/reference/typescript-api/entities/channel#channel'>Channel</a>, order?: <a href='/reference/typescript-api/entities/order#order'>Order</a>) => <a href='/reference/typescript-api/entities/zone#zone'>Zone</a>`}   />




</div>


---

---
title: "Tax"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "TaxLineCalculationStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## TaxLineCalculationStrategy

<GenerationInfo sourceFile="packages/core/src/config/tax/tax-line-calculation-strategy.ts" sourceLine="29" packageName="@vendure/core" />

This strategy defines how the TaxLines on OrderItems are calculated. By default,
the <a href='/reference/typescript-api/tax/default-tax-line-calculation-strategy#defaulttaxlinecalculationstrategy'>DefaultTaxLineCalculationStrategy</a> is used, which directly applies
a single TaxLine based on the applicable <a href='/reference/typescript-api/entities/tax-rate#taxrate'>TaxRate</a>.

However, custom strategies may use any suitable method for calculating TaxLines.
For example, a third-party tax API or a lookup of a custom tax table may be used.

:::info

This is configured via the `taxOptions.taxLineCalculationStrategy` property of
your VendureConfig.

:::

```ts title="Signature"
interface TaxLineCalculationStrategy extends InjectableStrategy {
    calculate(args: CalculateTaxLinesArgs): TaxLine[] | Promise<TaxLine[]>;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### calculate

<MemberInfo kind="method" type={`(args: <a href='/reference/typescript-api/tax/tax-line-calculation-strategy#calculatetaxlinesargs'>CalculateTaxLinesArgs</a>) => TaxLine[] | Promise&#60;TaxLine[]&#62;`}   />

This method is called when calculating the Order prices. Since it will be called
whenever an Order is modified in some way (adding/removing items, applying promotions,
setting ShippingMethod etc), care should be taken so that calling the function does
not adversely impact overall performance. For example, by using caching and only
calling external APIs when absolutely necessary.


</div>


## CalculateTaxLinesArgs

<GenerationInfo sourceFile="packages/core/src/config/tax/tax-line-calculation-strategy.ts" sourceLine="47" packageName="@vendure/core" />



```ts title="Signature"
interface CalculateTaxLinesArgs {
    ctx: RequestContext;
    order: Order;
    orderLine: OrderLine;
    applicableTaxRate: TaxRate;
}
```

<div className="members-wrapper">

### ctx

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>`}   />


### order

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/order#order'>Order</a>`}   />


### orderLine

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a>`}   />


### applicableTaxRate

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/tax-rate#taxrate'>TaxRate</a>`}   />




</div>


---

---
title: "TaxOptions"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## TaxOptions

<GenerationInfo sourceFile="packages/core/src/config/vendure-config.ts" sourceLine="912" packageName="@vendure/core" />



```ts title="Signature"
interface TaxOptions {
    taxZoneStrategy?: TaxZoneStrategy;
    taxLineCalculationStrategy?: TaxLineCalculationStrategy;
}
```

<div className="members-wrapper">

### taxZoneStrategy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/tax/tax-zone-strategy#taxzonestrategy'>TaxZoneStrategy</a>`} default={`<a href='/reference/typescript-api/tax/default-tax-zone-strategy#defaulttaxzonestrategy'>DefaultTaxZoneStrategy</a>`}   />

Defines the strategy used to determine the applicable Zone used in tax calculations.
### taxLineCalculationStrategy

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/tax/tax-line-calculation-strategy#taxlinecalculationstrategy'>TaxLineCalculationStrategy</a>`} default={`<a href='/reference/typescript-api/tax/default-tax-line-calculation-strategy#defaulttaxlinecalculationstrategy'>DefaultTaxLineCalculationStrategy</a>`}   />

Defines the strategy used to calculate the TaxLines added to OrderItems.


</div>


---

---
title: "TaxZoneStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## TaxZoneStrategy

<GenerationInfo sourceFile="packages/core/src/config/tax/tax-zone-strategy.ts" sourceLine="28" packageName="@vendure/core" />

Defines how the active <a href='/reference/typescript-api/entities/zone#zone'>Zone</a> is determined for the purposes of calculating taxes.

This strategy is used in 2 scenarios:

1. To determine the applicable Zone when calculating the taxRate to apply when displaying ProductVariants. In this case the
`order` argument will be undefined, as the request is not related to a specific Order.
2. To determine the applicable Zone when calculating the taxRate on the contents of a specific Order. In this case the
`order` argument _will_ be defined, and can be used in the logic. For example, the shipping address can be taken into account.

Note that this method is called very often in a typical user session, so any work it performs should be designed with as little
performance impact as possible.

:::info

This is configured via the `taxOptions.taxZoneStrategy` property of
your VendureConfig.

:::

```ts title="Signature"
interface TaxZoneStrategy extends InjectableStrategy {
    determineTaxZone(
        ctx: RequestContext,
        zones: Zone[],
        channel: Channel,
        order?: Order,
    ): Zone | Promise<Zone> | undefined;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### determineTaxZone

<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, zones: <a href='/reference/typescript-api/entities/zone#zone'>Zone</a>[], channel: <a href='/reference/typescript-api/entities/channel#channel'>Channel</a>, order?: <a href='/reference/typescript-api/entities/order#order'>Order</a>) => <a href='/reference/typescript-api/entities/zone#zone'>Zone</a> | Promise&#60;<a href='/reference/typescript-api/entities/zone#zone'>Zone</a>&#62; | undefined`}   />




</div>


---

---
title: "Telemetry"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "Instrument"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## Instrument

<GenerationInfo sourceFile="packages/core/src/common/instrument-decorator.ts" sourceLine="41" packageName="@vendure/core" since="3.3.0" />

This decorator is used to apply instrumentation to a class. It is intended to be used in conjunction
with an <a href='/reference/typescript-api/telemetry/instrumentation-strategy#instrumentationstrategy'>InstrumentationStrategy</a> which defines how the instrumentation should be applied.

In order for the instrumentation to be applied, the `VENDURE_ENABLE_INSTRUMENTATION` environment
variable (exported from the `@vendure/core` package as `ENABLE_INSTRUMENTATION_ENV_VAR`) must be set to `true`.
This is done to avoid the overhead of instrumentation in environments where it is not needed.

For more information on how instrumentation is used, see docs on the TelemetryPlugin.

*Example*

```ts
import { Instrument } from '@vendure/core';
import { Injectable } from '@nestjs/common';

@Injectable()
// highlight-next-line
@Instrument()
export class MyService {

  // Calls to this method will be instrumented
  myMethod() {
    // ...
  }
}
```

```ts title="Signature"
function Instrument(): ClassDecorator
```


---

---
title: "InstrumentationStrategy"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## InstrumentationStrategy

<GenerationInfo sourceFile="packages/core/src/config/system/instrumentation-strategy.ts" sourceLine="51" packageName="@vendure/core" since="3.3.0" />

This interface is used to define a strategy for instrumenting methods of
classes which are decorated with the <a href='/reference/typescript-api/telemetry/instrument#instrument'>Instrument</a> decorator.

```ts title="Signature"
interface InstrumentationStrategy extends InjectableStrategy {
    wrapMethod(args: WrappedMethodArgs): any;
}
```
* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>



<div className="members-wrapper">

### wrapMethod

<MemberInfo kind="method" type={`(args: <a href='/reference/typescript-api/telemetry/wrapped-method-args#wrappedmethodargs'>WrappedMethodArgs</a>) => any`}   />

When a method of an instrumented class is called, it will be wrapped (by means of
a Proxy) and this method will be called. The `applyOriginalFunction` function
will apply the original method and return the result.


</div>


---

---
title: "WrappedMethodArgs"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## WrappedMethodArgs

<GenerationInfo sourceFile="packages/core/src/config/system/instrumentation-strategy.ts" sourceLine="13" packageName="@vendure/core" since="3.3.0" />

The arguments that are passed to the `wrapMethod` method of the
<a href='/reference/typescript-api/telemetry/instrumentation-strategy#instrumentationstrategy'>InstrumentationStrategy</a> interface.

```ts title="Signature"
interface WrappedMethodArgs {
    instance: any;
    target: Type<any>;
    methodName: string;
    args: any[];
    applyOriginalFunction: () => any | Promise<any>;
}
```

<div className="members-wrapper">

### instance

<MemberInfo kind="property" type={`any`}   />

The instance of the class which is being instrumented.
### target

<MemberInfo kind="property" type={`Type&#60;any&#62;`}   />

The class which is being instrumented.
### methodName

<MemberInfo kind="property" type={`string`}   />

The name of the method which is being instrumented.
### args

<MemberInfo kind="property" type={`any[]`}   />

The arguments which are passed to the method.
### applyOriginalFunction

<MemberInfo kind="property" type={`() =&#62; any | Promise&#60;any&#62;`}   />

A function which applies the original method and returns the result.
This is used to call the original method after the instrumentation has
been applied.


</div>


---

---
title: "CreateErrorResultGuard"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## createErrorResultGuard

<GenerationInfo sourceFile="packages/testing/src/error-result-guard.ts" sourceLine="18" packageName="@vendure/testing" />

Convenience method for creating an <a href='/reference/typescript-api/testing/error-result-guard#errorresultguard'>ErrorResultGuard</a>. Takes a predicate function which
tests whether the input is considered successful (true) or an error result (false).

Note that the resulting variable must _still_ be type annotated in order for the TypeScript
type inference to work as expected:

*Example*

```ts
const orderResultGuard: ErrorResultGuard<AddItemToOrderResult>
  = createErrorResultGuard(order => !!order.lines);
```

```ts title="Signature"
function createErrorResultGuard<T>(testFn: (input: T) => boolean): ErrorResultGuard<T>
```
Parameters

### testFn

<MemberInfo kind="parameter" type={`(input: T) =&#62; boolean`} />



---

---
title: "CreateTestEnvironment"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## createTestEnvironment

<GenerationInfo sourceFile="packages/testing/src/create-test-environment.ts" sourceLine="60" packageName="@vendure/testing" />

Configures a <a href='/reference/typescript-api/testing/test-server#testserver'>TestServer</a> and a <a href='/reference/typescript-api/testing/simple-graph-qlclient#simplegraphqlclient'>SimpleGraphQLClient</a> for each of the GraphQL APIs
for use in end-to-end tests. Returns a <a href='/reference/typescript-api/testing/test-environment#testenvironment'>TestEnvironment</a> object.

*Example*

```ts
import { createTestEnvironment, testConfig } from '@vendure/testing';

describe('some feature to test', () => {

  const { server, adminClient, shopClient } = createTestEnvironment(testConfig);

  beforeAll(async () => {
    await server.init({
        // ... server options
    });
    await adminClient.asSuperAdmin();
  });

  afterAll(async () => {
      await server.destroy();
  });

  // ... end-to-end tests here
});
```

```ts title="Signature"
function createTestEnvironment(config: Required<VendureConfig>): TestEnvironment
```
Parameters

### config

<MemberInfo kind="parameter" type={`Required&#60;<a href='/reference/typescript-api/configuration/vendure-config#vendureconfig'>VendureConfig</a>&#62;`} />



---

---
title: "ErrorResultGuard"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## ErrorResultGuard

<GenerationInfo sourceFile="packages/testing/src/error-result-guard.ts" sourceLine="50" packageName="@vendure/testing" />

A utility class which is used to assert the success of an operation
which returns a union type of `SuccessType | ErrorResponse [ | ErrorResponse ]`.
The methods of this class are used to:
1. assert that the result is a success or error case
2. narrow the type so that TypeScript can correctly infer the properties of the result.

*Example*

```ts
const orderResultGuard: ErrorResultGuard<AddItemToOrderResult>
  = createErrorResultGuard(order => !!order.lines);

it('errors when quantity is negative', async () => {
   const { addItemToOrder } = await shopClient.query<AddItemToOrder.Query, AddItemToOrder.Mutation>(ADD_ITEM_TO_ORDER, {
     productVariantId: 42, quantity: -1,
   });

   // The test will fail
   orderResultGuard.assertErrorResult(addItemToOrder);

   // the type of `addItemToOrder` has now been
   // narrowed to only include the ErrorResult types.
   expect(addItemToOrder.errorCode).toBe(ErrorCode.NegativeQuantityError);
}
```

```ts title="Signature"
class ErrorResultGuard<T> {
    constructor(testFn: (input: T) => boolean)
    isSuccess(input: T | any) => input is T;
    assertSuccess(input: T | R) => asserts input is T;
    assertErrorResult(input: T | R) => asserts input is R;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(testFn: (input: T) =&#62; boolean) => ErrorResultGuard`}   />


### isSuccess

<MemberInfo kind="method" type={`(input: T | any) => input is T`}   />

A type guard which returns `true` if the input passes the `testFn` predicate.
### assertSuccess

<MemberInfo kind="method" type={`(input: T | R) => asserts input is T`}   />

Asserts (using the testing library's `fail()` function) that the input is
successful, i.e. it passes the `testFn`.
### assertErrorResult

<MemberInfo kind="method" type={`(input: T | R) => asserts input is R`}   />

Asserts (using the testing library's `fail()` function) that the input is
not successful, i.e. it does not pass the `testFn`.


</div>


---

---
title: "GetSuperadminContext"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## getSuperadminContext

<GenerationInfo sourceFile="packages/testing/src/utils/get-superadmin-context.ts" sourceLine="11" packageName="@vendure/testing" />

Creates a <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a> configured for the default Channel with the activeUser set
as the superadmin user. Useful for populating data.

```ts title="Signature"
function getSuperadminContext(app: INestApplicationContext): Promise<RequestContext>
```
Parameters

### app

<MemberInfo kind="parameter" type={`INestApplicationContext`} />



---

---
title: "Testing"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "RegisterInitializer"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## registerInitializer

<GenerationInfo sourceFile="packages/testing/src/initializers/initializers.ts" sourceLine="16" packageName="@vendure/testing" />

Registers a <a href='/reference/typescript-api/testing/test-db-initializer#testdbinitializer'>TestDbInitializer</a> for the given database type. Should be called before invoking
<a href='/reference/typescript-api/testing/create-test-environment#createtestenvironment'>createTestEnvironment</a>.

```ts title="Signature"
function registerInitializer(type: DataSourceOptions['type'], initializer: TestDbInitializer<any>): void
```
Parameters

### type

<MemberInfo kind="parameter" type={`DataSourceOptions['type']`} />

### initializer

<MemberInfo kind="parameter" type={`<a href='/reference/typescript-api/testing/test-db-initializer#testdbinitializer'>TestDbInitializer</a>&#60;any&#62;`} />



---

---
title: "SimpleGraphQLClient"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## SimpleGraphQLClient

<GenerationInfo sourceFile="packages/testing/src/simple-graphql-client.ts" sourceLine="40" packageName="@vendure/testing" />

A minimalistic GraphQL client for populating and querying test data.

```ts title="Signature"
class SimpleGraphQLClient {
    constructor(vendureConfig: Required<VendureConfig>, apiUrl: string = '')
    setAuthToken(token: string) => ;
    setChannelToken(token: string | null) => ;
    getAuthToken() => string;
    query(query: DocumentNode | TypedDocumentNode<T, V>, variables?: V, queryParams?: QueryParams) => Promise<T>;
    fetch(url: string, options: RequestInit = {}) => Promise<Response>;
    queryStatus(query: DocumentNode, variables?: V) => Promise<number>;
    asUserWithCredentials(username: string, password: string) => ;
    asSuperAdmin() => ;
    asAnonymousUser() => ;
    fileUploadMutation(options: {
        mutation: DocumentNode;
        filePaths: string[];
        mapVariables: (filePaths: string[]) => any;
    }) => Promise<any>;
}
```

<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(vendureConfig: Required&#60;<a href='/reference/typescript-api/configuration/vendure-config#vendureconfig'>VendureConfig</a>&#62;, apiUrl: string = '') => SimpleGraphQLClient`}   />


### setAuthToken

<MemberInfo kind="method" type={`(token: string) => `}   />

Sets the authToken to be used in each GraphQL request.
### setChannelToken

<MemberInfo kind="method" type={`(token: string | null) => `}   />

Sets the authToken to be used in each GraphQL request.
### getAuthToken

<MemberInfo kind="method" type={`() => string`}   />

Returns the authToken currently being used.
### query

<MemberInfo kind="method" type={`(query: DocumentNode | TypedDocumentNode&#60;T, V&#62;, variables?: V, queryParams?: QueryParams) => Promise&#60;T&#62;`}   />

Performs both query and mutation operations.
### fetch

<MemberInfo kind="method" type={`(url: string, options: RequestInit = {}) => Promise&#60;Response&#62;`}   />

Performs a raw HTTP request to the given URL, but also includes the authToken & channelToken
headers if they have been set. Useful for testing non-GraphQL endpoints, e.g. for plugins
which make use of REST controllers.
### queryStatus

<MemberInfo kind="method" type={`(query: DocumentNode, variables?: V) => Promise&#60;number&#62;`}   />

Performs a query or mutation and returns the resulting status code.
### asUserWithCredentials

<MemberInfo kind="method" type={`(username: string, password: string) => `}   />

Attempts to log in with the specified credentials.
### asSuperAdmin

<MemberInfo kind="method" type={`() => `}   />

Logs in as the SuperAdmin user.
### asAnonymousUser

<MemberInfo kind="method" type={`() => `}   />

Logs out so that the client is then treated as an anonymous user.
### fileUploadMutation

<MemberInfo kind="method" type={`(options: {         mutation: DocumentNode;         filePaths: string[];         mapVariables: (filePaths: string[]) =&#62; any;     }) => Promise&#60;any&#62;`}   />

Perform a file upload mutation.

Upload spec: https://github.com/jaydenseric/graphql-multipart-request-spec

Discussion of issue: https://github.com/jaydenseric/apollo-upload-client/issues/32

*Example*

```ts
// Testing a custom mutation:
const result = await client.fileUploadMutation({
  mutation: gql`
    mutation AddSellerImages($input: AddSellerImagesInput!) {
      addSellerImages(input: $input) {
        id
        name
      }
    }
  `,
  filePaths: ['./images/profile-picture.jpg', './images/logo.png'],
  mapVariables: () => ({
    name: "George's Pans",
    profilePicture: null,  // corresponds to filePaths[0]
    branding: {
      logo: null  // corresponds to filePaths[1]
    }
  })
});
```


</div>


---

---
title: "TestConfig"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## testConfig

<GenerationInfo sourceFile="packages/testing/src/config/test-config.ts" sourceLine="42" packageName="@vendure/testing" />

A <a href='/reference/typescript-api/configuration/vendure-config#vendureconfig'>VendureConfig</a> object used for e2e tests. This configuration uses sqljs as the database
and configures some special settings which are optimized for e2e tests:

* `entityIdStrategy: new TestingEntityIdStrategy()` This ID strategy uses auto-increment IDs but encodes all IDs
to be prepended with the string `'T_'`, so ID `1` becomes `'T_1'`.
* `logger: new NoopLogger()` Do no output logs by default
* `assetStorageStrategy: new TestingAssetStorageStrategy()` This strategy does not actually persist any binary data to disk.
* `assetPreviewStrategy: new TestingAssetPreviewStrategy()` This strategy is a no-op.

## Logging
By default, the testConfig does not output any log messages. This is most desirable to keep a clean CI output.
However, for debugging purposes, it can make it hard to figure out why tests fail.

You can enable default logging behaviour with the environment variable `LOG`:

```
LOG=true yarn e2e
```



---

---
title: "TestDbInitializer"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## TestDbInitializer

<GenerationInfo sourceFile="packages/testing/src/initializers/test-db-initializer.ts" sourceLine="23" packageName="@vendure/testing" />

Defines how the e2e TestService sets up a particular DB to run a single test suite.
The `@vendure/testing` package ships with initializers for sql.js, MySQL & Postgres.

Custom initializers can be created by implementing this interface and registering
it with the <a href='/reference/typescript-api/testing/register-initializer#registerinitializer'>registerInitializer</a> function:

*Example*

```ts
export class CockroachDbInitializer implements TestDbInitializer<CockroachConnectionOptions> {
    // database-specific implementation goes here
}

registerInitializer('cockroachdb', new CockroachDbInitializer());
```

```ts title="Signature"
interface TestDbInitializer<T extends BaseConnectionOptions> {
    init(testFileName: string, connectionOptions: T): Promise<T>;
    populate(populateFn: () => Promise<void>): Promise<void>;
    destroy(): void | Promise<void>;
}
```

<div className="members-wrapper">

### init

<MemberInfo kind="method" type={`(testFileName: string, connectionOptions: T) => Promise&#60;T&#62;`}   />

Responsible for creating a database for the current test suite.
Typically, this method will:

* use the testFileName parameter to derive a database name
* create the database
* mutate the `connetionOptions` object to point to that new database
### populate

<MemberInfo kind="method" type={`(populateFn: () =&#62; Promise&#60;void&#62;) => Promise&#60;void&#62;`}   />

Execute the populateFn to populate your database.
### destroy

<MemberInfo kind="method" type={`() => void | Promise&#60;void&#62;`}   />

Clean up any resources used during the init() phase (i.e. close open DB connections)


</div>


---

---
title: "TestEnvironment"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## TestEnvironment

<GenerationInfo sourceFile="packages/testing/src/create-test-environment.ts" sourceLine="13" packageName="@vendure/testing" />

The return value of <a href='/reference/typescript-api/testing/create-test-environment#createtestenvironment'>createTestEnvironment</a>, containing the test server
and clients for the Shop API and Admin API.

```ts title="Signature"
interface TestEnvironment {
    server: TestServer;
    adminClient: SimpleGraphQLClient;
    shopClient: SimpleGraphQLClient;
}
```

<div className="members-wrapper">

### server

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/testing/test-server#testserver'>TestServer</a>`}   />

A Vendure server instance against which GraphQL requests can be made.
### adminClient

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/testing/simple-graph-qlclient#simplegraphqlclient'>SimpleGraphQLClient</a>`}   />

A GraphQL client configured for the Admin API.
### shopClient

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/testing/simple-graph-qlclient#simplegraphqlclient'>SimpleGraphQLClient</a>`}   />

A GraphQL client configured for the Shop API.


</div>


---

---
title: "TestServerOptions"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## TestServerOptions

<GenerationInfo sourceFile="packages/testing/src/types.ts" sourceLine="14" packageName="@vendure/testing" />

Configuration options used to initialize an instance of the <a href='/reference/typescript-api/testing/test-server#testserver'>TestServer</a>.

```ts title="Signature"
interface TestServerOptions {
    productsCsvPath?: string;
    initialData: InitialData;
    customerCount?: number;
    logging?: boolean;
}
```

<div className="members-wrapper">

### productsCsvPath

<MemberInfo kind="property" type={`string`}   />

The path to an optional CSV file containing product data to import.
### initialData

<MemberInfo kind="property" type={`<a href='/reference/typescript-api/import-export/initial-data#initialdata'>InitialData</a>`}   />

An object containing non-product data which is used to populate the database.
### customerCount

<MemberInfo kind="property" type={`number`} default={`10`}   />

The number of fake Customers to populate into the database.
### logging

<MemberInfo kind="property" type={`boolean`} default={`false`}   />

Set this to `true` to log some information about the database population process.


</div>


---

---
title: "TestServer"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## TestServer

<GenerationInfo sourceFile="packages/testing/src/test-server.ts" sourceLine="17" packageName="@vendure/testing" />

A real Vendure server against which the e2e tests should be run.

```ts title="Signature"
class TestServer {
    public app: INestApplication;
    constructor(vendureConfig: Required<VendureConfig>)
    init(options: TestServerOptions) => Promise<void>;
    bootstrap() => ;
    destroy() => ;
}
```

<div className="members-wrapper">

### app

<MemberInfo kind="property" type={`INestApplication`}   />


### constructor

<MemberInfo kind="method" type={`(vendureConfig: Required&#60;<a href='/reference/typescript-api/configuration/vendure-config#vendureconfig'>VendureConfig</a>&#62;) => TestServer`}   />


### init

<MemberInfo kind="method" type={`(options: <a href='/reference/typescript-api/testing/test-server-options#testserveroptions'>TestServerOptions</a>) => Promise&#60;void&#62;`}   />

Bootstraps an instance of Vendure server and populates the database according to the options
passed in. Should be called in the `beforeAll` function.

The populated data is saved into an .sqlite file for each test file. On subsequent runs, this file
is loaded so that the populate step can be skipped, which speeds up the tests significantly.
### bootstrap

<MemberInfo kind="method" type={`() => `}   />

Bootstraps a Vendure server instance. Generally the `.init()` method should be used, as that will also
populate the test data. However, the `bootstrap()` method is sometimes useful in tests which need to
start and stop a Vendure instance multiple times without re-populating data.
### destroy

<MemberInfo kind="method" type={`() => `}   />

Destroy the Vendure server instance and clean up all resources.
Should be called after all tests have run, e.g. in an `afterAll` function.


</div>


---

---
title: "TestingLogger"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## TestingLogger

<GenerationInfo sourceFile="packages/testing/src/testing-logger.ts" sourceLine="55" packageName="@vendure/testing" />

The TestingLogger can be used in unit tests or e2e tests to make assertions on whether the various
Logger methods have been called, and which arguments.

Here's some examples of how to use it in e2e tests and unit tests. In both cases we are using
the Jest testing framework, but the TestingLogger should work with other similar frameworks
(e.g. replacing `jest.fn()` with `jasmine.createSpy()`).

*Example*

```ts
// e2e test example
import { createTestEnvironment, TestingLogger } from '@vendure/testing';

const testingLogger = new TestingLogger(() => jest.fn());

const { server, adminClient, shopClient } = createTestEnvironment({
  ...testConfig,
  logger: testingLogger,
});

// e2e testing setup omitted

it('should log an error', async () => {
  // The `errorSpy` property exposes the Jest mock function
  testingLogger.errorSpy.mockClear();

  await doSomethingThatErrors();

  expect(testingLogger.errorSpy).toHaveBeenCalled();
});
```

*Example*

```ts
// unit test example
import { Test } from '@nestjs/testing';
import { Logger } from '@vendure/core';
import { TestingLogger } from '@vendure/testing';

beforeEach(async () => {
  const moduleRef = await Test.createTestingModule({
    // Nest testing setup omitted
  }).compile();

  Logger.useLogger(testingLogger);
  moduleRef.useLogger(new Logger());
}
```

```ts title="Signature"
class TestingLogger<Spy extends (...args: any[]) => any> implements VendureLogger {
    constructor(createSpyFn: () => Spy)
    debugSpy: Spy;
    errorSpy: Spy;
    infoSpy: Spy;
    verboseSpy: Spy;
    warnSpy: Spy;
    debug(message: string, context?: string) => void;
    error(message: string, context?: string, trace?: string) => void;
    info(message: string, context?: string) => void;
    verbose(message: string, context?: string) => void;
    warn(message: string, context?: string) => void;
}
```
* Implements: <code><a href='/reference/typescript-api/logger/vendure-logger#vendurelogger'>VendureLogger</a></code>



<div className="members-wrapper">

### constructor

<MemberInfo kind="method" type={`(createSpyFn: () =&#62; Spy) => TestingLogger`}   />


### debugSpy

<MemberInfo kind="property" type={`Spy`}   />


### errorSpy

<MemberInfo kind="property" type={`Spy`}   />


### infoSpy

<MemberInfo kind="property" type={`Spy`}   />


### verboseSpy

<MemberInfo kind="property" type={`Spy`}   />


### warnSpy

<MemberInfo kind="property" type={`Spy`}   />


### debug

<MemberInfo kind="method" type={`(message: string, context?: string) => void`}   />


### error

<MemberInfo kind="method" type={`(message: string, context?: string, trace?: string) => void`}   />


### info

<MemberInfo kind="method" type={`(message: string, context?: string) => void`}   />


### verbose

<MemberInfo kind="method" type={`(message: string, context?: string) => void`}   />


### warn

<MemberInfo kind="method" type={`(message: string, context?: string) => void`}   />




</div>


---

---
title: "BootstrapWorker"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## bootstrapWorker

<GenerationInfo sourceFile="packages/core/src/bootstrap.ts" sourceLine="225" packageName="@vendure/core" />

Bootstraps a Vendure worker. Resolves to a <a href='/reference/typescript-api/worker/vendure-worker#vendureworker'>VendureWorker</a> object containing a reference to the underlying
NestJs [standalone application](https://docs.nestjs.com/standalone-applications) as well as convenience
methods for starting the job queue and health check server.

Read more about the [Vendure Worker](/guides/developer-guide/worker-job-queue/).

*Example*

```ts
import { bootstrapWorker } from '@vendure/core';
import { config } from './vendure-config';

bootstrapWorker(config)
  .then(worker => worker.startJobQueue())
  .then(worker => worker.startHealthCheckServer({ port: 3020 }))
  .catch(err => {
    console.log(err);
    process.exit(1);
  });
```

```ts title="Signature"
function bootstrapWorker(userConfig: Partial<VendureConfig>, options?: BootstrapWorkerOptions): Promise<VendureWorker>
```
Parameters

### userConfig

<MemberInfo kind="parameter" type={`Partial&#60;<a href='/reference/typescript-api/configuration/vendure-config#vendureconfig'>VendureConfig</a>&#62;`} />

### options

<MemberInfo kind="parameter" type={`<a href='/reference/typescript-api/worker/bootstrap-worker#bootstrapworkeroptions'>BootstrapWorkerOptions</a>`} />



## BootstrapWorkerOptions

<GenerationInfo sourceFile="packages/core/src/bootstrap.ts" sourceLine="83" packageName="@vendure/core" since="2.2.0" />

Additional options that can be used to configure the bootstrap process of the
Vendure worker.

```ts title="Signature"
interface BootstrapWorkerOptions {
    nestApplicationContextOptions?: NestApplicationContextOptions;
    ignoreCompatibilityErrorsForPlugins?: Array<DynamicModule | Type<any>>;
}
```

<div className="members-wrapper">

### nestApplicationContextOptions

<MemberInfo kind="property" type={`NestApplicationContextOptions`}   />

These options get passed directly to the `NestFactory.createApplicationContext` method.
### ignoreCompatibilityErrorsForPlugins

<MemberInfo kind="property" type={`Array&#60;DynamicModule | Type&#60;any&#62;&#62;`} default={`[]`}  since="3.1.0"  />

See the `ignoreCompatibilityErrorsForPlugins` option in <a href='/reference/typescript-api/common/bootstrap#bootstrapoptions'>BootstrapOptions</a>.


</div>


---

---
title: "Worker"
isDefaultIndex: true
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


import DocCardList from '@theme/DocCardList';

<DocCardList />

---

---
title: "VendureWorker"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## VendureWorker

<GenerationInfo sourceFile="packages/core/src/worker/vendure-worker.ts" sourceLine="13" packageName="@vendure/core" />

This object is created by calling the <a href='/reference/typescript-api/worker/bootstrap-worker#bootstrapworker'>bootstrapWorker</a> function.

```ts title="Signature"
class VendureWorker {
    public app: INestApplicationContext;
    constructor(app: INestApplicationContext)
    startJobQueue() => Promise<VendureWorker>;
    startHealthCheckServer(healthCheckConfig: WorkerHealthCheckConfig) => Promise<VendureWorker>;
}
```

<div className="members-wrapper">

### app

<MemberInfo kind="property" type={`INestApplicationContext`}   />

A reference to the `INestApplicationContext` object, which represents
the NestJS [standalone application](https://docs.nestjs.com/standalone-applications) instance.
### constructor

<MemberInfo kind="method" type={`(app: INestApplicationContext) => VendureWorker`}   />


### startJobQueue

<MemberInfo kind="method" type={`() => Promise&#60;<a href='/reference/typescript-api/worker/vendure-worker#vendureworker'>VendureWorker</a>&#62;`}   />

Starts the job queues running so that the worker can handle background jobs.
### startHealthCheckServer

<MemberInfo kind="method" type={`(healthCheckConfig: <a href='/reference/typescript-api/worker/worker-health-check-config#workerhealthcheckconfig'>WorkerHealthCheckConfig</a>) => Promise&#60;<a href='/reference/typescript-api/worker/vendure-worker#vendureworker'>VendureWorker</a>&#62;`}  since="1.2.0"  />

Starts a simple http server which can be used as a health check on the worker instance.
This endpoint can be used by container orchestration services such as Kubernetes to
verify whether the worker is running.


</div>


---

---
title: "WorkerHealthCheckConfig"
isDefaultIndex: false
generated: true
---
<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
import MemberInfo from '@site/src/components/MemberInfo';
import GenerationInfo from '@site/src/components/GenerationInfo';
import MemberDescription from '@site/src/components/MemberDescription';


## WorkerHealthCheckConfig

<GenerationInfo sourceFile="packages/core/src/worker/worker-health.service.ts" sourceLine="14" packageName="@vendure/core" since="1.2.0" />

Specifies the configuration for the Worker's HTTP health check endpoint.

```ts title="Signature"
interface WorkerHealthCheckConfig {
    port: number;
    hostname?: string;
    route?: string;
}
```

<div className="members-wrapper">

### port

<MemberInfo kind="property" type={`number`}   />

The port on which the worker will listen
### hostname

<MemberInfo kind="property" type={`string`} default={`'localhost'`}   />

The hostname
### route

<MemberInfo kind="property" type={`string`} default={`'/health'`}   />

The route at which the health check is available.


</div>


---

---
title: "Collections"
weight: 2
---

# Collections

Collections allow you to group ProductVariants together by various criteria. A typical use of Collections is to create a hierarchical category tree which can be used in a navigation menu in your storefront.

## Populating Collections

Collections are _dynamic_, which means that you define a set of rules, and Vendure will automatically populate the Collection with ProductVariants according to those rules.

The rules are defined by **filters**. A Collection can define multiple filters, for example:

* Include all ProductVariants with a certain FacetValue
* Include all ProductVariants whose name includes the word "sale"

## Nesting Collections

Collections can be nested inside one another, as many levels deep as needed.

When populating a nested Collection, its own filters _plus the filters of all Collections above it_ are used to calculate the contents.

## Public vs Private Collections

A Collection can be made private, meaning that it will not be available in the storefront. This can be useful when you need to organize your inventory for internal purposes.


---

---
title: "Facets"
weight: 1
---

# Facets

Facets are the primary means to attach structured data to your Products & ProductVariants. Typical uses of Facets include:

* Enabling faceted search & filtering in the storefront
* Organizing Products into Collections
* Labelling Products for inclusion in Promotions 

![./screen-facet-list.webp](./screen-facet-list.webp)

A Facet has one or more FacetValues, for example:

* Facet: "Brand"
* Values: "Apple", "Logitech", "Sony", "LG" ...

## Assigning to Products & Variants

In the Product detail page, you can assign FacetValues by clicking the _ADD FACETS_ button toward the bottom of the Product or ProductVariant views.

![./screen-facet-add.webp](./screen-facet-add.webp)

## Public vs Private Facets

The visibility of a Facet can be set to either _public_ or _private_.

* **Public** facets are visible via the Shop API, meaning they can be listed in the storefront and used for faceted searches.
* **Private** facets are only visible to Administrators, and cannot be used in storefront faceted searches. 

Private facets can be useful for labelling Products for internal use. For example, you could create a "profit margin" Facet with "high" and "low" values. You wouldn't want to display these in the storefront, but you may want to use them e.g. in Promotion logic.


---

---
title: "Products"
---

# Products

Products represent the items you want to sell to your customers.

## Products vs ProductVariants

In Vendure, every Product has one or more _ProductVariants_. You can think of a Product as a "container" which houses the variants: 

![./product-variants.png](./product-variants.png)

In the diagram above you'll notice that it is the ProductVariants which have an SKU (_stock-keeping unit_: a unique product code) and a price.

**Products** provide the overall name, description, slug, images. A product _does not_ have a price, sku, or stock level. 

**ProductVariants** have a price, sku, stock level, tax settings. They are the actual things that get added to orders and purchased.

## Tracking Inventory

Vendure can track the stock levels of each of your ProductVariants. This is done by setting the "track inventory" option to "track" (or "inherit from global settings" if the [global setting](/user-guide/settings/global-settings) is set to track).

![./screen-inventory.webp](./screen-inventory.webp)

When tracking inventory:

* When a customer checks out, the contents of the order will be "allocated". This means that the stock has not yet been sold, but it is no longer available to purchase (no longer _saleable_).
* Once a Fulfillment has been created (see the Orders section), those allocated items will be converted into sales, meaning the stock level will be lowered by the corresponding quantity.
* If a customer attempts to add more of a ProductVariant than are currently _saleable_, they will encounter an error.

### Back orders

Back orders can be enabled by setting a **negative value** as the "Out-of-stock threshold". This can be done via [global settings](/user-guide/settings/global-settings) or on a per-variant basis.


---

---
title: "Customers"
weight: 2
---

# Customers

A Customer is anybody who has:

* Placed an order
* Registered an account

The Customers section allows you to view and search for your customers. Clicking "edit" in the list view brings up the detail view, allowing you to edit the customer details and view orders and history.

## Guest, Registered, Verified

* **Guest:** Vendure allows "guest checkouts", which means people may place orders without needing to register an account with the storefront. 
* **Registered:** When a customer registers for an account (using their email address by default), they are assigned this status.
* **Verified:** A registered customer becomes verified once they have been able to confirm ownership of their email account. Note that if alternative authentication methods are set up on your store (e.g. Facebook login), then this workflow might be slightly different.

## Customer Groups

Customer Groups can be used for things like:

* Grouping wholesale customers so that alternative tax calculations may be applied
* Grouping members of a loyalty scheme for access to exclusive Promotions
* Segmenting customers for other marketing purposes

![./screen-customer-group.webp](./screen-customer-group.webp)



---

# Vendure User Guide

This section is for store owners and staff who are charged with running a Vendure-based store.

This guide assumes that your Vendure instance is running the AdminUiPlugin.

We will roughly structure this guide to conform to the default layout of the Admin UI main navigation menu. 


---

---
title: "Localization"
weight: 10
---

# Localization

Vendure supports **customer-facing** (Shop API) localization by allowing you to define translations for the following objects:

* Collections
* Countries
* Facets
* FacetValue
* Products
* ProductOptions
* ProductOptionGroups
* ProductVariants
* ShippingMethods  

Vendure supports **admin-facing** (Admin API and Admin UI) localization by allowing you to define translations for labels and descriptions of the following objects:
  
* CustomFields
* CollectionFilters
* PaymentMethodHandlers
* PromotionActions
* PromotionConditions
* ShippingCalculators
* ShippingEligibilityCheckers

## How to enable languages

To select the set of languages you wish to create translations for, set them in the [global settings](/user-guide/settings/global-settings).

Once more than one language is enabled, you will see a language switcher appear when editing the object types listed above.

![../settings/screen-translations.webp](../settings/screen-translations.webp)

## Setting the Admin UI language

Separately, you can change the language used in the Admin UI from the menu in the top right. Note that changing the UI language has no effect on the localization of your products etc.

![./screen-ui-language.webp](./screen-ui-language.webp)


---

---
title: "Draft Orders"
---

# Draft Orders

Draft Orders are used when an Administrator would like to manually create an order via the Admin UI. For example, this can be useful when:

- A customer phones up to place an order
- A customer wants to place an order in person
- You want to create an order on behalf of a customer, e.g. for a quote.
- When testing Promotions

To create a Draft Order, click the **"Create draft order"** button from the Order List view.

From there you can:

- Add ProductVariants to the Order using the search input marked "Add item to order"
- Optionally activate coupon codes to trigger Promotions
- Set the customer, shipping and billing addresses
- Select the shipping method

Once ready, click the **"Complete draft"** button to convert this Order from a Draft into a regular Order. At this stage the order can be paid for, and you can manually record the payment details.

:::note
Note: Draft Orders do not appear in a Customer's order history in the storefront (Shop API) while still
in the "Draft" state.
:::


---

---
title: "Orders"
weight: 3
---

# Orders

An Order is created whenever someone adds an item to their cart in the storefront. In Vendure, there is no distinction between a "cart" and an "order". Thus a "cart" is just an Order which has not yet passed through the checkout process.

## The Order Workflow

The exact set of stages that an Order goes through can be customized in Vendure to suit your particular business needs, but we can look at the default steps to get a good idea of the typical workflow:

![./order-state-diagram-for-admin.png](./order-state-diagram-for-admin.png)

When a new Order arrives, you would:

1. **Settle the payment** if not already done (this may or may not be needed depending on the way your payment provider is configured).
    ![./screen-settle-payment.webp](./screen-settle-payment.webp)
1. **Create a Fulfillment** by clicking the "Fulfill Order" button in the top-right of the order detail page. A Fulfillment represents the physical package which will be sent to the customer. You may split up your order into multiple Fulfillments, if that makes sense from a logistical point of view.
    ![./screen-fulfillment.webp](./screen-fulfillment.webp)
1. **Mark the Fulfillment as "shipped"** once the physical package leaves your warehouse. 
1. **Mark the Fulfillment as "delivered"** once you have notice of the package arriving with the customer. 
   ![./screen-fulfillment-shipped.webp](./screen-fulfillment-shipped.webp)

## Refunds

You can refund one or more items from an Order by clicking this menu item, which is available once the payments are settled:

![./screen-refund-button.webp](./screen-refund-button.webp)

This will bring up a dialog which allows you to select which items to refund, as well as whether to refund shipping. You can also make an arbitrary adjustment to the refund amount if needed.

A Refund is then made against the payment method used in that order. Some payment methods will handle refunds automatically, and others will expect you to perform the refund manually in your payment provider's admin interface, and then record the fact manually.

## Cancellation

One or more items may also be cancelled in a similar way to how refunds are handled. Performing a cancellation will return the selected items back into stock.

Cancellations and refunds are often done together, but do not have to be. For example, you may refund a faulty item without requiring the customer to return it. This would be a pure refund.

## Modifying an Order

An Order can be modified after checkout is completed. 

![./screen-modify-button.webp](./screen-modify-button.webp)

Modification allows you to:

* Alter the quantities of any items in the order
* Remove items from the order  
* Add new items to the order
* Add arbitrary surcharges or discounts
* Alter the shipping & billing address

![./screen-modification.webp](./screen-modification.webp)

Once you have made the desired modifications, you preview the changes including the price difference.

If the modifications have resulted in an increased price (as in the above example), the Order will then be set into the "Arranging additional payment" state. This allows you to process another payment from the customer to make up the price difference.

On the other hand, if the new price is less than what was originally paid (e.g. if the quantity is decreased), then a Refund will be generated against the payment method used.





---

---
title: "Promotions"
weight: 4
---

# Promotions

Promotions are a means of offering discounts on an order based on various criteria. A Promotion consists of _conditions_ and _actions_.

* **conditions** are the rules which determine whether the Promotion should be applied to the order.
* **actions** specify exactly how this Promotion should modify the order.

## Promotion Conditions

A condition defines the criteria that must be met for the Promotion to be activated. Vendure comes with some simple conditions provided which enable things like:

* If the order total is at least $X
* Buy at least X of a certain product
* But at least X of any product with the specified [FacetValues](/user-guide/catalog/facets)
* If the customer is a member of the specified [Customer Group](/user-guide/customers#customer-groups)

Vendure allows completely custom conditions to be defined by your developers, implementing the specific logic needed by your business.

## Coupon codes

A coupon code can be any text which will activate a Promotion. A coupon code can be used in conjunction with conditions if desired.


:::note
Note: Promotions **must** have either a **coupon code** _or_ **at least 1 condition** defined.
:::

## Promotion Actions

If all the defined conditions pass (or if the specified coupon code is used), then the actions are performed on the order. Vendure comes with some commonly-used actions which allow promotions like:

* Discount the whole order by a fixed amount
* Discount the whole order by a percentage
* Discount selected products by a percentage
* Free shipping

## Coupon code per-customer limit

If a per-customer limit is specified, then the specified coupon code may only be used that many times by a single Customer. For guest checkouts, the "same customer" status is determined by the email address used when checking out.


---

---
title: "Administrators & Roles"
---

# Administrators & Roles

An **administrator** is a staff member who has access to the Admin UI, and is able to view and modify some or all of the items and settings.

The exact permissions of _what_ a given administrator may view and modify is defined by which **roles** are assigned to that administrator.

## Defining a Role

The role detail page allows you to create a new role or edit an existing one. A role can be thought of as a list of permissions. Permissions are usually divided into four types:

* **Create** allows you to create new items, e.g. "CreateProduct" will allow one to create a new product.
* **Read** allows you to view items, but not modify or delete them.
* **Update** allows you to make changes to existing items, but not to create new ones.
* **Delete** allows you to delete items.

Vendure comes with a few pre-defined roles for commonly-needed tasks, but you are free to modify these or create your own.

In general, it is advisable to create roles with the fewest amount of privileges needed for the staff member to do their jobs. For example, a marketing manager would need to be able to create, read, update and delete promotions, but probably doesn't need to be able to update or delete payment methods.

### The SuperAdmin role

This is a special role which cannot be deleted or modified. This role grants _all permissions_ and is used to set up the store initially, and make certain special changes (such as creating new Channels).

## Creating Administrators

For each individual that needs to log in to the Admin UI, you should create a new administrator account. 

Apart from filling in their details and selecting a strong password, you then need to assign at least one role. Roles "add together", meaning that when more than one role is assigned, the combined set of permissions of all assigned roles is granted to that administrator. 

Thus, it is possible to create a set of specific roles "Inventory Manager", "Order Manager", "Customer Services", "Marketing Manager", and _compose_ them together as needed.


---

---
title: "Channels"
---

# Channels

Channels allow you to split your store into multiple sub-stores, each of which can have its own selection of inventory, customers, orders, shipping methods etc.

There are various reasons why you might want to do this:

* Creating distinct stores for different countries, each with country-specific pricing, shipping and payment rules.
* Implementing a multi-tenant application where many merchants have their own store, each confined to its own channel.
* Implementing a marketplace where each seller has their own channel.

Each channel defines some basic default settings - currency, language, tax options.

There is _always_ a **default channel** - this is the "root" channel which contains _everything_, and any sub-channels can then contain a subset of the contents of the default channel.
  


---

---
title: "Countries & Zones"
---

# Countries & Zones

**Countries** are where you define the list of countries which are relevant to your operations. This does not only include those countries you ship to, but also those countries which may appear on a billing address.

By default, Vendure includes all countries in the list, but you are free to remove or disable any that you don't need.

**Zones** provide a way to group countries. Zones are used mainly for defining [tax rates](/user-guide/settings/taxes) and can also be used in shipping calculations.



---

---
title: "Global Settings"
---

# Global Settings

The global settings allow you to define certain configurations that affect _all_ channels.

* **Available languages** defines which languages you wish to make available for translations. When more than one language has been enabled, you will see the language switcher appear when viewing translatable objects such as products, collections, facets and shipping methods.
  ![./screen-translations.webp](./screen-translations.webp)
* **Global out-of-stock threshold** sets the stock level at which a product variant is considered to be out of stock. Using a negative value enables backorder support. This setting can be overridden by individual product variants (see the [tracking inventory](/user-guide/catalog/products#tracking-inventory) guide).
* **Track inventory by default** sets whether stock levels should be tracked. This setting can be overridden by individual product variants (see the [tracking inventory](/user-guide/catalog/products#tracking-inventory) guide).


---

---
title: "Payment Methods"
---

# Payment Methods

Payment methods define how your storefront handles payments. Your storefront may offer multiple payment methods or just one.

A Payment method consists of two parts: an **eligibility checker** and a **handler**

## Payment eligibility checker

This is an optional part which can be useful in certain situations where you want to limit a payment method based on things like:

* Billing address
* Order contents or total price
* Customer group

Since these requirements are particular to your business needs, Vendure does not provide any built-in checkers, but your developers can create one to suit your requirements.

## Payment handler

The payment handler contains the actual logic for processing a payment. Again, since there are many ways to handle payments, Vendure only provides a "dummy handler" by default and it is up to your developers to create integrations. 

Payment handlers can be created which enable payment via:

* Popular payment services such as Stripe, Paypal, Braintree, Klarna etc
* Pay-on-delivery
* Store credit
* etc




---

---
title: "Shipping Methods"
---

# Shipping Methods

Shipping methods define:

* Whether an order is eligible for a particular shipping method
* How much the shipping should cost for a given order
* How the order will be fulfilled

Let's take a closer look at each of these parts:

## Shipping eligibility checker

This is how we decide whether a particular shipping method may be applied to an order. This allows you to limit a particular shipping method based on things like:

* Minimum order amount
* Order weight
* Shipping destination
* Particular contents of the order
* etc.

By default, Vendure comes with a checker which can impose a minimum order amount. To implement more complex checks, your developers are able to create custom checkers to suit your requirements.

## Shipping calculator

The calculator is used to determine how much to charge for shipping an order. Calculators can be written to implement things like:

* Determining shipping based on a 3rd-party service such as Shippo
* Looking up prices from data supplied by couriers
* Flat-rate shipping

By default, Vendure comes with a simple flat-rate shipping calculator. Your developers can create more sophisticated integrations according to your business requirements.

## Fulfillment handler

By "fulfillment" we mean how we physically get the goods into the hands of the customer. Common fulfillment methods include:

* Courier services such as FedEx, DPD, DHL, etc.
* Collection by customer
* Delivery via email for digital goods or licenses

By default, Vendure comes with a "manual fulfillment handler", which allows you to manually enter the details of whatever actual method is used. For example, if you send the order by courier, you can enter the courier name and parcel number manually when creating an order.

Your developers can however create much more sophisticated fulfillment handlers, which can enable things like automated calls to courier APIs, automated label generation, and so on.

## Testing a Shipping Method

At the bottom of the shipping method **detail page** you can test the current method by creating a fake order and shipping address and testing a) whether this method would be eligible, and b) how much it would cost.

![./screen-shipping-test.webp](./screen-shipping-test.webp)

Additionally, on the shipping method **list page** you can test _all_ shipping methods at once.


---

---
title: "Taxes"
---

# Taxes

Taxes represent extra charges on top of the base price of a product. There are various forms of taxes that might be applicable, depending on local laws and the laws of the regions that your business serves. Common forms of applicable taxes are:

* Value added tax (VAT)
* Goods and services tax (GST)  
* Sales taxes (as in the USA)


## Tax Category

In Vendure every product variant is assigned a **tax category**. In many countries, different rates of tax apply depending on the type of product being sold.

For example, in the UK there are three rates of VAT:

* Standard rate (20%)
* Reduced rate (5%)
* Zero rate (0%)

Most types of products would fall into the "standard rate" category, but for instance books are classified as "zero rate".

## Tax Rate

Tax rates set the rate of tax for a given **tax category** destined for a particular **zone**. They are used by default in Vendure when calculating all taxes.

## Tax Compliance

Please note that tax compliance is a complex topic that varies significantly between countries. Vendure does not (and cannot) offer a complete out-of-the-box tax solution which is guaranteed to be compliant with your use-case. What we strive to do is to provide a very flexible set of tools that your developers can use to tailor tax calculations exactly to your needs. These are covered in the [Developer's guide to taxes](/guides/core-concepts/taxes/). 


---

# @algolia/autocomplete-core

The [`autocomplete-core`](https://www.algolia.com/doc/ui-libraries/autocomplete/api-reference/autocomplete-core/createAutocomplete) package is the foundation of Autocomplete. It exposes primitives to build an autocomplete experience.

You likely don’t need to use this package directly unless you’re building a [renderer](https://www.algolia.com/doc/ui-libraries/autocomplete/guides/creating-a-renderer).

## Installation

```sh
yarn add @algolia/autocomplete-core
# or
npm install @algolia/autocomplete-core
```

## Documentation

See [**Documentation**](https://www.algolia.com/doc/ui-libraries/autocomplete/api-reference/autocomplete-core).


---

# @algolia/autocomplete-plugin-algolia-insights

The Algolia Insights plugin automatically sends click and conversion events to the [Algolia Insights API](https://www.algolia.com/doc/rest-api/insights]) whenever a user interacts with the autocomplete.

## Installation

```sh
yarn add @algolia/autocomplete-plugin-algolia-insights
# or
npm install @algolia/autocomplete-plugin-algolia-insights
```

## Documentation

See [**Documentation**](https://www.algolia.com/doc/ui-libraries/autocomplete/api-reference/autocomplete-plugin-algolia-insights).


---

# @algolia/autocomplete-preset-algolia

The Algolia preset provides fetching and highlighting utilities for usage with Algolia.

## Installation

```sh
yarn add @algolia/autocomplete-preset-algolia
# or
npm install @algolia/autocomplete-preset-algolia
```

## Documentation

See [**Documentation**](https://www.algolia.com/doc/ui-libraries/autocomplete/api-reference/autocomplete-preset-algolia).


---

<p align="center">
  <a href="https://www.algolia.com">
    <img alt="Algolia for JavaScript" src="https://raw.githubusercontent.com/algolia/algoliasearch-client-common/master/banners/javascript.png" >
  </a>

  <h4 align="center">The perfect starting point to integrate <a href="https://algolia.com" target="_blank">Algolia</a> within your JavaScript project</h4>

  <p align="center">
    <a href="https://npmjs.org/package/@algolia/client-abtesting"><img src="https://img.shields.io/npm/v/@algolia/client-abtesting.svg?style=flat-square" alt="NPM version"></img></a>
    <a href="http://npm-stat.com/charts.html?package=@algolia/client-abtesting"><img src="https://img.shields.io/npm/dm/@algolia/client-abtesting.svg?style=flat-square" alt="NPM downloads"></a>
    <a href="https://www.jsdelivr.com/package/npm/@algolia/client-abtesting"><img src="https://data.jsdelivr.com/v1/package/npm/@algolia/client-abtesting/badge" alt="jsDelivr Downloads"></img></a>
    <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg?style=flat-square" alt="License"></a>
  </p>
</p>

<p align="center">
  <a href="https://www.algolia.com/doc/libraries/javascript/" target="_blank">Documentation</a>  •
  <a href="https://www.algolia.com/doc/guides/building-search-ui/what-is-instantsearch/js/" target="_blank">InstantSearch</a>  •
  <a href="https://discourse.algolia.com" target="_blank">Community Forum</a>  •
  <a href="http://stackoverflow.com/questions/tagged/algolia" target="_blank">Stack Overflow</a>  •
  <a href="https://github.com/algolia/algoliasearch-client-javascript/issues" target="_blank">Report a bug</a>  •
  <a href="https://www.algolia.com/doc/libraries/javascript/v5/" target="_blank">FAQ</a>  •
  <a href="https://alg.li/support" target="_blank">Support</a>
</p>

## ✨ Features

- Thin & **minimal low-level HTTP client** to interact with Algolia's API
- Works both on the **browser** and **node.js**
- **UMD and ESM compatible**, you can use it with any module loader
- Built with TypeScript

## 💡 Getting Started

> [!TIP]
> This API client is already a dependency of [the algoliasearch client](https://www.npmjs.com/package/algoliasearch), you don't need to manually install `@algolia/client-abtesting` if you already have `algoliasearch` installed.

To get started, you first need to install @algolia/client-abtesting (or any other available API client package).
All of our clients comes with type definition, and are available for both browser and node environments.

### With a package manager

```bash
yarn add @algolia/client-abtesting@5.23.0
# or
npm install @algolia/client-abtesting@5.23.0
# or
pnpm add @algolia/client-abtesting@5.23.0
```

### Without a package manager

Add the following JavaScript snippet to the <head> of your website:

```html
<script src="https://cdn.jsdelivr.net/npm/@algolia/client-abtesting@5.23.0/dist/builds/browser.umd.js"></script>
```

### Usage

You can now import the Algolia API client in your project and play with it.

```js
import { abtestingClient } from '@algolia/client-abtesting';

const client = abtestingClient('YOUR_APP_ID', 'YOUR_API_KEY');
```

For full documentation, visit the **[Algolia JavaScript API Client](https://www.algolia.com/doc/libraries/javascript/v5/methods/abtesting/)**.

## ❓ Troubleshooting

Encountering an issue? Before reaching out to support, we recommend heading to our [FAQ](https://www.algolia.com/doc/libraries/javascript/v5/) where you will find answers for the most common issues and gotchas with the client. You can also open [a GitHub issue](https://github.com/algolia/api-clients-automation/issues/new?assignees=&labels=&projects=&template=Bug_report.md)

## 📄 License

The Algolia JavaScript API Client is an open-sourced software licensed under the [MIT license](LICENSE).


---

<p align="center">
  <a href="https://www.algolia.com">
    <img alt="Algolia for JavaScript" src="https://raw.githubusercontent.com/algolia/algoliasearch-client-common/master/banners/javascript.png" >
  </a>

  <h4 align="center">The perfect starting point to integrate <a href="https://algolia.com" target="_blank">Algolia</a> within your JavaScript project</h4>

  <p align="center">
    <a href="https://npmjs.org/package/@algolia/client-analytics"><img src="https://img.shields.io/npm/v/@algolia/client-analytics.svg?style=flat-square" alt="NPM version"></img></a>
    <a href="http://npm-stat.com/charts.html?package=@algolia/client-analytics"><img src="https://img.shields.io/npm/dm/@algolia/client-analytics.svg?style=flat-square" alt="NPM downloads"></a>
    <a href="https://www.jsdelivr.com/package/npm/@algolia/client-analytics"><img src="https://data.jsdelivr.com/v1/package/npm/@algolia/client-analytics/badge" alt="jsDelivr Downloads"></img></a>
    <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg?style=flat-square" alt="License"></a>
  </p>
</p>

<p align="center">
  <a href="https://www.algolia.com/doc/libraries/javascript/" target="_blank">Documentation</a>  •
  <a href="https://www.algolia.com/doc/guides/building-search-ui/what-is-instantsearch/js/" target="_blank">InstantSearch</a>  •
  <a href="https://discourse.algolia.com" target="_blank">Community Forum</a>  •
  <a href="http://stackoverflow.com/questions/tagged/algolia" target="_blank">Stack Overflow</a>  •
  <a href="https://github.com/algolia/algoliasearch-client-javascript/issues" target="_blank">Report a bug</a>  •
  <a href="https://www.algolia.com/doc/libraries/javascript/v5/" target="_blank">FAQ</a>  •
  <a href="https://alg.li/support" target="_blank">Support</a>
</p>

## ✨ Features

- Thin & **minimal low-level HTTP client** to interact with Algolia's API
- Works both on the **browser** and **node.js**
- **UMD and ESM compatible**, you can use it with any module loader
- Built with TypeScript

## 💡 Getting Started

> [!TIP]
> This API client is already a dependency of [the algoliasearch client](https://www.npmjs.com/package/algoliasearch), you don't need to manually install `@algolia/client-analytics` if you already have `algoliasearch` installed.

To get started, you first need to install @algolia/client-analytics (or any other available API client package).
All of our clients comes with type definition, and are available for both browser and node environments.

### With a package manager

```bash
yarn add @algolia/client-analytics@5.23.0
# or
npm install @algolia/client-analytics@5.23.0
# or
pnpm add @algolia/client-analytics@5.23.0
```

### Without a package manager

Add the following JavaScript snippet to the <head> of your website:

```html
<script src="https://cdn.jsdelivr.net/npm/@algolia/client-analytics@5.23.0/dist/builds/browser.umd.js"></script>
```

### Usage

You can now import the Algolia API client in your project and play with it.

```js
import { analyticsClient } from '@algolia/client-analytics';

const client = analyticsClient('YOUR_APP_ID', 'YOUR_API_KEY');
```

For full documentation, visit the **[Algolia JavaScript API Client](https://www.algolia.com/doc/libraries/javascript/v5/methods/analytics/)**.

## ❓ Troubleshooting

Encountering an issue? Before reaching out to support, we recommend heading to our [FAQ](https://www.algolia.com/doc/libraries/javascript/v5/) where you will find answers for the most common issues and gotchas with the client. You can also open [a GitHub issue](https://github.com/algolia/api-clients-automation/issues/new?assignees=&labels=&projects=&template=Bug_report.md)

## 📄 License

The Algolia JavaScript API Client is an open-sourced software licensed under the [MIT license](LICENSE).


---

<p align="center">
  <a href="https://www.algolia.com">
    <img alt="Algolia for JavaScript" src="https://raw.githubusercontent.com/algolia/algoliasearch-client-common/master/banners/javascript.png" >
  </a>

  <h4 align="center">The perfect starting point to integrate <a href="https://algolia.com" target="_blank">Algolia</a> within your JavaScript project</h4>

  <p align="center">
    <a href="https://npmjs.org/package/@algolia/client-insights"><img src="https://img.shields.io/npm/v/@algolia/client-insights.svg?style=flat-square" alt="NPM version"></img></a>
    <a href="http://npm-stat.com/charts.html?package=@algolia/client-insights"><img src="https://img.shields.io/npm/dm/@algolia/client-insights.svg?style=flat-square" alt="NPM downloads"></a>
    <a href="https://www.jsdelivr.com/package/npm/@algolia/client-insights"><img src="https://data.jsdelivr.com/v1/package/npm/@algolia/client-insights/badge" alt="jsDelivr Downloads"></img></a>
    <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg?style=flat-square" alt="License"></a>
  </p>
</p>

<p align="center">
  <a href="https://www.algolia.com/doc/libraries/javascript/" target="_blank">Documentation</a>  •
  <a href="https://www.algolia.com/doc/guides/building-search-ui/what-is-instantsearch/js/" target="_blank">InstantSearch</a>  •
  <a href="https://discourse.algolia.com" target="_blank">Community Forum</a>  •
  <a href="http://stackoverflow.com/questions/tagged/algolia" target="_blank">Stack Overflow</a>  •
  <a href="https://github.com/algolia/algoliasearch-client-javascript/issues" target="_blank">Report a bug</a>  •
  <a href="https://www.algolia.com/doc/libraries/javascript/v5/" target="_blank">FAQ</a>  •
  <a href="https://alg.li/support" target="_blank">Support</a>
</p>

## ✨ Features

- Thin & **minimal low-level HTTP client** to interact with Algolia's API
- Works both on the **browser** and **node.js**
- **UMD and ESM compatible**, you can use it with any module loader
- Built with TypeScript

## 💡 Getting Started

> [!TIP]
> This API client is already a dependency of [the algoliasearch client](https://www.npmjs.com/package/algoliasearch), you don't need to manually install `@algolia/client-insights` if you already have `algoliasearch` installed.

To get started, you first need to install @algolia/client-insights (or any other available API client package).
All of our clients comes with type definition, and are available for both browser and node environments.

### With a package manager

```bash
yarn add @algolia/client-insights@5.23.0
# or
npm install @algolia/client-insights@5.23.0
# or
pnpm add @algolia/client-insights@5.23.0
```

### Without a package manager

Add the following JavaScript snippet to the <head> of your website:

```html
<script src="https://cdn.jsdelivr.net/npm/@algolia/client-insights@5.23.0/dist/builds/browser.umd.js"></script>
```

### Usage

You can now import the Algolia API client in your project and play with it.

```js
import { insightsClient } from '@algolia/client-insights';

const client = insightsClient('YOUR_APP_ID', 'YOUR_API_KEY');
```

For full documentation, visit the **[Algolia JavaScript API Client](https://www.algolia.com/doc/libraries/javascript/v5/methods/insights/)**.

## ❓ Troubleshooting

Encountering an issue? Before reaching out to support, we recommend heading to our [FAQ](https://www.algolia.com/doc/libraries/javascript/v5/) where you will find answers for the most common issues and gotchas with the client. You can also open [a GitHub issue](https://github.com/algolia/api-clients-automation/issues/new?assignees=&labels=&projects=&template=Bug_report.md)

## 📄 License

The Algolia JavaScript API Client is an open-sourced software licensed under the [MIT license](LICENSE).


---

<p align="center">
  <a href="https://www.algolia.com">
    <img alt="Algolia for JavaScript" src="https://raw.githubusercontent.com/algolia/algoliasearch-client-common/master/banners/javascript.png" >
  </a>

  <h4 align="center">The perfect starting point to integrate <a href="https://algolia.com" target="_blank">Algolia</a> within your JavaScript project</h4>

  <p align="center">
    <a href="https://npmjs.org/package/@algolia/client-personalization"><img src="https://img.shields.io/npm/v/@algolia/client-personalization.svg?style=flat-square" alt="NPM version"></img></a>
    <a href="http://npm-stat.com/charts.html?package=@algolia/client-personalization"><img src="https://img.shields.io/npm/dm/@algolia/client-personalization.svg?style=flat-square" alt="NPM downloads"></a>
    <a href="https://www.jsdelivr.com/package/npm/@algolia/client-personalization"><img src="https://data.jsdelivr.com/v1/package/npm/@algolia/client-personalization/badge" alt="jsDelivr Downloads"></img></a>
    <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg?style=flat-square" alt="License"></a>
  </p>
</p>

<p align="center">
  <a href="https://www.algolia.com/doc/libraries/javascript/" target="_blank">Documentation</a>  •
  <a href="https://www.algolia.com/doc/guides/building-search-ui/what-is-instantsearch/js/" target="_blank">InstantSearch</a>  •
  <a href="https://discourse.algolia.com" target="_blank">Community Forum</a>  •
  <a href="http://stackoverflow.com/questions/tagged/algolia" target="_blank">Stack Overflow</a>  •
  <a href="https://github.com/algolia/algoliasearch-client-javascript/issues" target="_blank">Report a bug</a>  •
  <a href="https://www.algolia.com/doc/libraries/javascript/v5/" target="_blank">FAQ</a>  •
  <a href="https://alg.li/support" target="_blank">Support</a>
</p>

## ✨ Features

- Thin & **minimal low-level HTTP client** to interact with Algolia's API
- Works both on the **browser** and **node.js**
- **UMD and ESM compatible**, you can use it with any module loader
- Built with TypeScript

## 💡 Getting Started

> [!TIP]
> This API client is already a dependency of [the algoliasearch client](https://www.npmjs.com/package/algoliasearch), you don't need to manually install `@algolia/client-personalization` if you already have `algoliasearch` installed.

To get started, you first need to install @algolia/client-personalization (or any other available API client package).
All of our clients comes with type definition, and are available for both browser and node environments.

### With a package manager

```bash
yarn add @algolia/client-personalization@5.23.0
# or
npm install @algolia/client-personalization@5.23.0
# or
pnpm add @algolia/client-personalization@5.23.0
```

### Without a package manager

Add the following JavaScript snippet to the <head> of your website:

```html
<script src="https://cdn.jsdelivr.net/npm/@algolia/client-personalization@5.23.0/dist/builds/browser.umd.js"></script>
```

### Usage

You can now import the Algolia API client in your project and play with it.

```js
import { personalizationClient } from '@algolia/client-personalization';

const client = personalizationClient('YOUR_APP_ID', 'YOUR_API_KEY');
```

For full documentation, visit the **[Algolia JavaScript API Client](https://www.algolia.com/doc/libraries/javascript/v5/methods/personalization/)**.

## ❓ Troubleshooting

Encountering an issue? Before reaching out to support, we recommend heading to our [FAQ](https://www.algolia.com/doc/libraries/javascript/v5/) where you will find answers for the most common issues and gotchas with the client. You can also open [a GitHub issue](https://github.com/algolia/api-clients-automation/issues/new?assignees=&labels=&projects=&template=Bug_report.md)

## 📄 License

The Algolia JavaScript API Client is an open-sourced software licensed under the [MIT license](LICENSE).


---

<p align="center">
  <a href="https://www.algolia.com">
    <img alt="Algolia for JavaScript" src="https://raw.githubusercontent.com/algolia/algoliasearch-client-common/master/banners/javascript.png" >
  </a>

  <h4 align="center">The perfect starting point to integrate <a href="https://algolia.com" target="_blank">Algolia</a> within your JavaScript project</h4>

  <p align="center">
    <a href="https://npmjs.org/package/@algolia/client-query-suggestions"><img src="https://img.shields.io/npm/v/@algolia/client-query-suggestions.svg?style=flat-square" alt="NPM version"></img></a>
    <a href="http://npm-stat.com/charts.html?package=@algolia/client-query-suggestions"><img src="https://img.shields.io/npm/dm/@algolia/client-query-suggestions.svg?style=flat-square" alt="NPM downloads"></a>
    <a href="https://www.jsdelivr.com/package/npm/@algolia/client-query-suggestions"><img src="https://data.jsdelivr.com/v1/package/npm/@algolia/client-query-suggestions/badge" alt="jsDelivr Downloads"></img></a>
    <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg?style=flat-square" alt="License"></a>
  </p>
</p>

<p align="center">
  <a href="https://www.algolia.com/doc/libraries/javascript/" target="_blank">Documentation</a>  •
  <a href="https://www.algolia.com/doc/guides/building-search-ui/what-is-instantsearch/js/" target="_blank">InstantSearch</a>  •
  <a href="https://discourse.algolia.com" target="_blank">Community Forum</a>  •
  <a href="http://stackoverflow.com/questions/tagged/algolia" target="_blank">Stack Overflow</a>  •
  <a href="https://github.com/algolia/algoliasearch-client-javascript/issues" target="_blank">Report a bug</a>  •
  <a href="https://www.algolia.com/doc/libraries/javascript/v5/" target="_blank">FAQ</a>  •
  <a href="https://alg.li/support" target="_blank">Support</a>
</p>

## ✨ Features

- Thin & **minimal low-level HTTP client** to interact with Algolia's API
- Works both on the **browser** and **node.js**
- **UMD and ESM compatible**, you can use it with any module loader
- Built with TypeScript

## 💡 Getting Started

> [!TIP]
> This API client is already a dependency of [the algoliasearch client](https://www.npmjs.com/package/algoliasearch), you don't need to manually install `@algolia/client-query-suggestions` if you already have `algoliasearch` installed.

To get started, you first need to install @algolia/client-query-suggestions (or any other available API client package).
All of our clients comes with type definition, and are available for both browser and node environments.

### With a package manager

```bash
yarn add @algolia/client-query-suggestions@5.23.0
# or
npm install @algolia/client-query-suggestions@5.23.0
# or
pnpm add @algolia/client-query-suggestions@5.23.0
```

### Without a package manager

Add the following JavaScript snippet to the <head> of your website:

```html
<script src="https://cdn.jsdelivr.net/npm/@algolia/client-query-suggestions@5.23.0/dist/builds/browser.umd.js"></script>
```

### Usage

You can now import the Algolia API client in your project and play with it.

```js
import { querySuggestionsClient } from '@algolia/client-query-suggestions';

const client = querySuggestionsClient('YOUR_APP_ID', 'YOUR_API_KEY');
```

For full documentation, visit the **[Algolia JavaScript API Client](https://www.algolia.com/doc/libraries/javascript/v5/methods/query-suggestions/)**.

## ❓ Troubleshooting

Encountering an issue? Before reaching out to support, we recommend heading to our [FAQ](https://www.algolia.com/doc/libraries/javascript/v5/) where you will find answers for the most common issues and gotchas with the client. You can also open [a GitHub issue](https://github.com/algolia/api-clients-automation/issues/new?assignees=&labels=&projects=&template=Bug_report.md)

## 📄 License

The Algolia JavaScript API Client is an open-sourced software licensed under the [MIT license](LICENSE).


---

<p align="center">
  <a href="https://www.algolia.com">
    <img alt="Algolia for JavaScript" src="https://raw.githubusercontent.com/algolia/algoliasearch-client-common/master/banners/javascript.png" >
  </a>

  <h4 align="center">The perfect starting point to integrate <a href="https://algolia.com" target="_blank">Algolia</a> within your JavaScript project</h4>

  <p align="center">
    <a href="https://npmjs.org/package/@algolia/client-search"><img src="https://img.shields.io/npm/v/@algolia/client-search.svg?style=flat-square" alt="NPM version"></img></a>
    <a href="http://npm-stat.com/charts.html?package=@algolia/client-search"><img src="https://img.shields.io/npm/dm/@algolia/client-search.svg?style=flat-square" alt="NPM downloads"></a>
    <a href="https://www.jsdelivr.com/package/npm/@algolia/client-search"><img src="https://data.jsdelivr.com/v1/package/npm/@algolia/client-search/badge" alt="jsDelivr Downloads"></img></a>
    <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg?style=flat-square" alt="License"></a>
  </p>
</p>

<p align="center">
  <a href="https://www.algolia.com/doc/libraries/javascript/" target="_blank">Documentation</a>  •
  <a href="https://www.algolia.com/doc/guides/building-search-ui/what-is-instantsearch/js/" target="_blank">InstantSearch</a>  •
  <a href="https://discourse.algolia.com" target="_blank">Community Forum</a>  •
  <a href="http://stackoverflow.com/questions/tagged/algolia" target="_blank">Stack Overflow</a>  •
  <a href="https://github.com/algolia/algoliasearch-client-javascript/issues" target="_blank">Report a bug</a>  •
  <a href="https://www.algolia.com/doc/libraries/javascript/v5/" target="_blank">FAQ</a>  •
  <a href="https://alg.li/support" target="_blank">Support</a>
</p>

## ✨ Features

- Thin & **minimal low-level HTTP client** to interact with Algolia's API
- Works both on the **browser** and **node.js**
- **UMD and ESM compatible**, you can use it with any module loader
- Built with TypeScript

## 💡 Getting Started

> [!TIP]
> This API client is already a dependency of [the algoliasearch client](https://www.npmjs.com/package/algoliasearch), you don't need to manually install `@algolia/client-search` if you already have `algoliasearch` installed.

To get started, you first need to install @algolia/client-search (or any other available API client package).
All of our clients comes with type definition, and are available for both browser and node environments.

### With a package manager

```bash
yarn add @algolia/client-search@5.23.0
# or
npm install @algolia/client-search@5.23.0
# or
pnpm add @algolia/client-search@5.23.0
```

### Without a package manager

Add the following JavaScript snippet to the <head> of your website:

```html
<script src="https://cdn.jsdelivr.net/npm/@algolia/client-search@5.23.0/dist/builds/browser.umd.js"></script>
```

### Usage

You can now import the Algolia API client in your project and play with it.

```js
import { searchClient } from '@algolia/client-search';

const client = searchClient('YOUR_APP_ID', 'YOUR_API_KEY');
```

For full documentation, visit the **[Algolia JavaScript API Client](https://www.algolia.com/doc/libraries/javascript/v5/methods/search/)**.

## ❓ Troubleshooting

Encountering an issue? Before reaching out to support, we recommend heading to our [FAQ](https://www.algolia.com/doc/libraries/javascript/v5/) where you will find answers for the most common issues and gotchas with the client. You can also open [a GitHub issue](https://github.com/algolia/api-clients-automation/issues/new?assignees=&labels=&projects=&template=Bug_report.md)

## 📄 License

The Algolia JavaScript API Client is an open-sourced software licensed under the [MIT license](LICENSE).


---

# 4.0.1 (2021-11-24)

  - undo fake default export

# 4.0.0 (2021-11-24)

  - add type definitions
  - remove fake "named import" of EventEmitter

# 1.1.1 (2016-06-22)

  - add more context to errors if they are not instanceof Error

# 1.1.0 (2015-09-29)

  - add Emitter#listerCount (to match node v4 api)

# 1.0.2 (2014-08-28)

  - remove un-reachable code
  - update devDeps

## 1.0.1 / 2014-05-11

  - check for console.trace before using it

## 1.0.0 / 2013-12-10

  - Update to latest events code from node.js 0.10
  - copy tests from node.js

## 0.4.0 / 2011-07-03 ##

  - Switching to graphquire@0.8.0

## 0.3.0 / 2011-07-03 ##

  - Switching to URL based module require.

## 0.2.0 / 2011-06-10 ##

  - Simplified package structure.
  - Graphquire for dependency management.

## 0.1.1 / 2011-05-16 ##

  - Unhandled errors are logged via console.error

## 0.1.0 / 2011-04-22 ##

  - Initial release


---

# events [![Build Status](https://travis-ci.org/Gozala/events.png?branch=master)](https://travis-ci.org/Gozala/events)

Algolia's fork of Node's event emitter for all engines.

Specifics:
- v1.1.1-based, as it's much smaller and we don't use the newer features
- builtin type-definitions
- better interop with ESM, while still being cjs

## Install

```
npm install events
```

## Require

```javascript
var EventEmitter = require('events');
```

## Usage

See the [node.js event emitter docs](http://nodejs.org/api/events.html)


---

<p align="center">
  <a href="https://www.algolia.com">
    <img alt="Algolia for JavaScript" src="https://raw.githubusercontent.com/algolia/algoliasearch-client-common/master/banners/javascript.png" >
  </a>

  <h4 align="center">The perfect starting point to integrate <a href="https://algolia.com" target="_blank">Algolia</a> within your JavaScript project</h4>

  <p align="center">
    <a href="https://npmjs.org/package/@algolia/ingestion"><img src="https://img.shields.io/npm/v/@algolia/ingestion.svg?style=flat-square" alt="NPM version"></img></a>
    <a href="http://npm-stat.com/charts.html?package=@algolia/ingestion"><img src="https://img.shields.io/npm/dm/@algolia/ingestion.svg?style=flat-square" alt="NPM downloads"></a>
    <a href="https://www.jsdelivr.com/package/npm/@algolia/ingestion"><img src="https://data.jsdelivr.com/v1/package/npm/@algolia/ingestion/badge" alt="jsDelivr Downloads"></img></a>
    <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg?style=flat-square" alt="License"></a>
  </p>
</p>

<p align="center">
  <a href="https://www.algolia.com/doc/libraries/javascript/" target="_blank">Documentation</a>  •
  <a href="https://www.algolia.com/doc/guides/building-search-ui/what-is-instantsearch/js/" target="_blank">InstantSearch</a>  •
  <a href="https://discourse.algolia.com" target="_blank">Community Forum</a>  •
  <a href="http://stackoverflow.com/questions/tagged/algolia" target="_blank">Stack Overflow</a>  •
  <a href="https://github.com/algolia/algoliasearch-client-javascript/issues" target="_blank">Report a bug</a>  •
  <a href="https://www.algolia.com/doc/libraries/javascript/v5/" target="_blank">FAQ</a>  •
  <a href="https://alg.li/support" target="_blank">Support</a>
</p>

## ✨ Features

- Thin & **minimal low-level HTTP client** to interact with Algolia's API
- Works both on the **browser** and **node.js**
- **UMD and ESM compatible**, you can use it with any module loader
- Built with TypeScript

## 💡 Getting Started

> [!TIP]
> This API client is already a dependency of [the algoliasearch client](https://www.npmjs.com/package/algoliasearch), you don't need to manually install `@algolia/ingestion` if you already have `algoliasearch` installed.

To get started, you first need to install @algolia/ingestion (or any other available API client package).
All of our clients comes with type definition, and are available for both browser and node environments.

### With a package manager

```bash
yarn add @algolia/ingestion@1.23.0
# or
npm install @algolia/ingestion@1.23.0
# or
pnpm add @algolia/ingestion@1.23.0
```

### Without a package manager

Add the following JavaScript snippet to the <head> of your website:

```html
<script src="https://cdn.jsdelivr.net/npm/@algolia/ingestion@1.23.0/dist/builds/browser.umd.js"></script>
```

### Usage

You can now import the Algolia API client in your project and play with it.

```js
import { ingestionClient } from '@algolia/ingestion';

const client = ingestionClient('YOUR_APP_ID', 'YOUR_API_KEY');
```

For full documentation, visit the **[Algolia JavaScript API Client](https://www.algolia.com/doc/libraries/javascript/v5/methods/ingestion/)**.

## ❓ Troubleshooting

Encountering an issue? Before reaching out to support, we recommend heading to our [FAQ](https://www.algolia.com/doc/libraries/javascript/v5/) where you will find answers for the most common issues and gotchas with the client. You can also open [a GitHub issue](https://github.com/algolia/api-clients-automation/issues/new?assignees=&labels=&projects=&template=Bug_report.md)

## 📄 License

The Algolia JavaScript API Client is an open-sourced software licensed under the [MIT license](LICENSE).


---

<p align="center">
  <a href="https://www.algolia.com">
    <img alt="Algolia for JavaScript" src="https://raw.githubusercontent.com/algolia/algoliasearch-client-common/master/banners/javascript.png" >
  </a>

  <h4 align="center">The perfect starting point to integrate <a href="https://algolia.com" target="_blank">Algolia</a> within your JavaScript project</h4>

  <p align="center">
    <a href="https://npmjs.org/package/@algolia/monitoring"><img src="https://img.shields.io/npm/v/@algolia/monitoring.svg?style=flat-square" alt="NPM version"></img></a>
    <a href="http://npm-stat.com/charts.html?package=@algolia/monitoring"><img src="https://img.shields.io/npm/dm/@algolia/monitoring.svg?style=flat-square" alt="NPM downloads"></a>
    <a href="https://www.jsdelivr.com/package/npm/@algolia/monitoring"><img src="https://data.jsdelivr.com/v1/package/npm/@algolia/monitoring/badge" alt="jsDelivr Downloads"></img></a>
    <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg?style=flat-square" alt="License"></a>
  </p>
</p>

<p align="center">
  <a href="https://www.algolia.com/doc/libraries/javascript/" target="_blank">Documentation</a>  •
  <a href="https://www.algolia.com/doc/guides/building-search-ui/what-is-instantsearch/js/" target="_blank">InstantSearch</a>  •
  <a href="https://discourse.algolia.com" target="_blank">Community Forum</a>  •
  <a href="http://stackoverflow.com/questions/tagged/algolia" target="_blank">Stack Overflow</a>  •
  <a href="https://github.com/algolia/algoliasearch-client-javascript/issues" target="_blank">Report a bug</a>  •
  <a href="https://www.algolia.com/doc/libraries/javascript/v5/" target="_blank">FAQ</a>  •
  <a href="https://alg.li/support" target="_blank">Support</a>
</p>

## ✨ Features

- Thin & **minimal low-level HTTP client** to interact with Algolia's API
- Works both on the **browser** and **node.js**
- **UMD and ESM compatible**, you can use it with any module loader
- Built with TypeScript

## 💡 Getting Started

> [!TIP]
> This API client is already a dependency of [the algoliasearch client](https://www.npmjs.com/package/algoliasearch), you don't need to manually install `@algolia/monitoring` if you already have `algoliasearch` installed.

To get started, you first need to install @algolia/monitoring (or any other available API client package).
All of our clients comes with type definition, and are available for both browser and node environments.

### With a package manager

```bash
yarn add @algolia/monitoring@1.23.0
# or
npm install @algolia/monitoring@1.23.0
# or
pnpm add @algolia/monitoring@1.23.0
```

### Without a package manager

Add the following JavaScript snippet to the <head> of your website:

```html
<script src="https://cdn.jsdelivr.net/npm/@algolia/monitoring@1.23.0/dist/builds/browser.umd.js"></script>
```

### Usage

You can now import the Algolia API client in your project and play with it.

```js
import { monitoringClient } from '@algolia/monitoring';

const client = monitoringClient('YOUR_APP_ID', 'YOUR_API_KEY');
```

For full documentation, visit the **[Algolia JavaScript API Client](https://www.algolia.com/doc/libraries/javascript/v5/methods/monitoring/)**.

## ❓ Troubleshooting

Encountering an issue? Before reaching out to support, we recommend heading to our [FAQ](https://www.algolia.com/doc/libraries/javascript/v5/) where you will find answers for the most common issues and gotchas with the client. You can also open [a GitHub issue](https://github.com/algolia/api-clients-automation/issues/new?assignees=&labels=&projects=&template=Bug_report.md)

## 📄 License

The Algolia JavaScript API Client is an open-sourced software licensed under the [MIT license](LICENSE).


---

<p align="center">
  <a href="https://www.algolia.com">
    <img alt="Algolia for JavaScript" src="https://raw.githubusercontent.com/algolia/algoliasearch-client-common/master/banners/javascript.png" >
  </a>

  <h4 align="center">The perfect starting point to integrate <a href="https://algolia.com" target="_blank">Algolia</a> within your JavaScript project</h4>

  <p align="center">
    <a href="https://npmjs.org/package/@algolia/recommend"><img src="https://img.shields.io/npm/v/@algolia/recommend.svg?style=flat-square" alt="NPM version"></img></a>
    <a href="http://npm-stat.com/charts.html?package=@algolia/recommend"><img src="https://img.shields.io/npm/dm/@algolia/recommend.svg?style=flat-square" alt="NPM downloads"></a>
    <a href="https://www.jsdelivr.com/package/npm/@algolia/recommend"><img src="https://data.jsdelivr.com/v1/package/npm/@algolia/recommend/badge" alt="jsDelivr Downloads"></img></a>
    <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg?style=flat-square" alt="License"></a>
  </p>
</p>

<p align="center">
  <a href="https://www.algolia.com/doc/libraries/javascript/" target="_blank">Documentation</a>  •
  <a href="https://www.algolia.com/doc/guides/building-search-ui/what-is-instantsearch/js/" target="_blank">InstantSearch</a>  •
  <a href="https://discourse.algolia.com" target="_blank">Community Forum</a>  •
  <a href="http://stackoverflow.com/questions/tagged/algolia" target="_blank">Stack Overflow</a>  •
  <a href="https://github.com/algolia/algoliasearch-client-javascript/issues" target="_blank">Report a bug</a>  •
  <a href="https://www.algolia.com/doc/libraries/javascript/v5/" target="_blank">FAQ</a>  •
  <a href="https://alg.li/support" target="_blank">Support</a>
</p>

## ✨ Features

- Thin & **minimal low-level HTTP client** to interact with Algolia's API
- Works both on the **browser** and **node.js**
- **UMD and ESM compatible**, you can use it with any module loader
- Built with TypeScript

## 💡 Getting Started

> [!TIP]
> This API client is already a dependency of [the algoliasearch client](https://www.npmjs.com/package/algoliasearch), you don't need to manually install `@algolia/recommend` if you already have `algoliasearch` installed.

To get started, you first need to install @algolia/recommend (or any other available API client package).
All of our clients comes with type definition, and are available for both browser and node environments.

### With a package manager

```bash
yarn add @algolia/recommend@5.23.0
# or
npm install @algolia/recommend@5.23.0
# or
pnpm add @algolia/recommend@5.23.0
```

### Without a package manager

Add the following JavaScript snippet to the <head> of your website:

```html
<script src="https://cdn.jsdelivr.net/npm/@algolia/recommend@5.23.0/dist/builds/browser.umd.js"></script>
```

### Usage

You can now import the Algolia API client in your project and play with it.

```js
import { recommendClient } from '@algolia/recommend';

const client = recommendClient('YOUR_APP_ID', 'YOUR_API_KEY');
```

For full documentation, visit the **[Algolia JavaScript API Client](https://www.algolia.com/doc/libraries/javascript/v5/methods/recommend/)**.

## ❓ Troubleshooting

Encountering an issue? Before reaching out to support, we recommend heading to our [FAQ](https://www.algolia.com/doc/libraries/javascript/v5/) where you will find answers for the most common issues and gotchas with the client. You can also open [a GitHub issue](https://github.com/algolia/api-clients-automation/issues/new?assignees=&labels=&projects=&template=Bug_report.md)

## 📄 License

The Algolia JavaScript API Client is an open-sourced software licensed under the [MIT license](LICENSE).


---

# @ampproject/remapping

> Remap sequential sourcemaps through transformations to point at the original source code

Remapping allows you to take the sourcemaps generated through transforming your code and "remap"
them to the original source locations. Think "my minified code, transformed with babel and bundled
with webpack", all pointing to the correct location in your original source code.

With remapping, none of your source code transformations need to be aware of the input's sourcemap,
they only need to generate an output sourcemap. This greatly simplifies building custom
transformations (think a find-and-replace).

## Installation

```sh
npm install @ampproject/remapping
```

## Usage

```typescript
function remapping(
  map: SourceMap | SourceMap[],
  loader: (file: string, ctx: LoaderContext) => (SourceMap | null | undefined),
  options?: { excludeContent: boolean, decodedMappings: boolean }
): SourceMap;

// LoaderContext gives the loader the importing sourcemap, tree depth, the ability to override the
// "source" location (where child sources are resolved relative to, or the location of original
// source), and the ability to override the "content" of an original source for inclusion in the
// output sourcemap.
type LoaderContext = {
 readonly importer: string;
 readonly depth: number;
 source: string;
 content: string | null | undefined;
}
```

`remapping` takes the final output sourcemap, and a `loader` function. For every source file pointer
in the sourcemap, the `loader` will be called with the resolved path. If the path itself represents
a transformed file (it has a sourcmap associated with it), then the `loader` should return that
sourcemap. If not, the path will be treated as an original, untransformed source code.

```js
// Babel transformed "helloworld.js" into "transformed.js"
const transformedMap = JSON.stringify({
  file: 'transformed.js',
  // 1st column of 2nd line of output file translates into the 1st source
  // file, line 3, column 2
  mappings: ';CAEE',
  sources: ['helloworld.js'],
  version: 3,
});

// Uglify minified "transformed.js" into "transformed.min.js"
const minifiedTransformedMap = JSON.stringify({
  file: 'transformed.min.js',
  // 0th column of 1st line of output file translates into the 1st source
  // file, line 2, column 1.
  mappings: 'AACC',
  names: [],
  sources: ['transformed.js'],
  version: 3,
});

const remapped = remapping(
  minifiedTransformedMap,
  (file, ctx) => {

    // The "transformed.js" file is an transformed file.
    if (file === 'transformed.js') {
      // The root importer is empty.
      console.assert(ctx.importer === '');
      // The depth in the sourcemap tree we're currently loading.
      // The root `minifiedTransformedMap` is depth 0, and its source children are depth 1, etc.
      console.assert(ctx.depth === 1);

      return transformedMap;
    }

    // Loader will be called to load transformedMap's source file pointers as well.
    console.assert(file === 'helloworld.js');
    // `transformed.js`'s sourcemap points into `helloworld.js`.
    console.assert(ctx.importer === 'transformed.js');
    // This is a source child of `transformed`, which is a source child of `minifiedTransformedMap`.
    console.assert(ctx.depth === 2);
    return null;
  }
);

console.log(remapped);
// {
//   file: 'transpiled.min.js',
//   mappings: 'AAEE',
//   sources: ['helloworld.js'],
//   version: 3,
// };
```

In this example, `loader` will be called twice:

1. `"transformed.js"`, the first source file pointer in the `minifiedTransformedMap`. We return the
   associated sourcemap for it (its a transformed file, after all) so that sourcemap locations can
   be traced through it into the source files it represents.
2. `"helloworld.js"`, our original, unmodified source code. This file does not have a sourcemap, so
   we return `null`.

The `remapped` sourcemap now points from `transformed.min.js` into locations in `helloworld.js`. If
you were to read the `mappings`, it says "0th column of the first line output line points to the 1st
column of the 2nd line of the file `helloworld.js`".

### Multiple transformations of a file

As a convenience, if you have multiple single-source transformations of a file, you may pass an
array of sourcemap files in the order of most-recent transformation sourcemap first. Note that this
changes the `importer` and `depth` of each call to our loader. So our above example could have been
written as:

```js
const remapped = remapping(
  [minifiedTransformedMap, transformedMap],
  () => null
);

console.log(remapped);
// {
//   file: 'transpiled.min.js',
//   mappings: 'AAEE',
//   sources: ['helloworld.js'],
//   version: 3,
// };
```

### Advanced control of the loading graph

#### `source`

The `source` property can overridden to any value to change the location of the current load. Eg,
for an original source file, it allows us to change the location to the original source regardless
of what the sourcemap source entry says. And for transformed files, it allows us to change the
relative resolving location for child sources of the loaded sourcemap.

```js
const remapped = remapping(
  minifiedTransformedMap,
  (file, ctx) => {

    if (file === 'transformed.js') {
      // We pretend the transformed.js file actually exists in the 'src/' directory. When the nested
      // source files are loaded, they will now be relative to `src/`.
      ctx.source = 'src/transformed.js';
      return transformedMap;
    }

    console.assert(file === 'src/helloworld.js');
    // We could futher change the source of this original file, eg, to be inside a nested directory
    // itself. This will be reflected in the remapped sourcemap.
    ctx.source = 'src/nested/transformed.js';
    return null;
  }
);

console.log(remapped);
// {
//   …,
//   sources: ['src/nested/helloworld.js'],
// };
```


#### `content`

The `content` property can be overridden when we encounter an original source file. Eg, this allows
you to manually provide the source content of the original file regardless of whether the
`sourcesContent` field is present in the parent sourcemap. It can also be set to `null` to remove
the source content.

```js
const remapped = remapping(
  minifiedTransformedMap,
  (file, ctx) => {

    if (file === 'transformed.js') {
      // transformedMap does not include a `sourcesContent` field, so usually the remapped sourcemap
      // would not include any `sourcesContent` values.
      return transformedMap;
    }

    console.assert(file === 'helloworld.js');
    // We can read the file to provide the source content.
    ctx.content = fs.readFileSync(file, 'utf8');
    return null;
  }
);

console.log(remapped);
// {
//   …,
//   sourcesContent: [
//     'console.log("Hello world!")',
//   ],
// };
```

### Options

#### excludeContent

By default, `excludeContent` is `false`. Passing `{ excludeContent: true }` will exclude the
`sourcesContent` field from the returned sourcemap. This is mainly useful when you want to reduce
the size out the sourcemap.

#### decodedMappings

By default, `decodedMappings` is `false`. Passing `{ decodedMappings: true }` will leave the
`mappings` field in a [decoded state](https://github.com/rich-harris/sourcemap-codec) instead of
encoding into a VLQ string.


---

# @babel/code-frame

> Generate errors that contain a code frame that point to source locations.

See our website [@babel/code-frame](https://babeljs.io/docs/babel-code-frame) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/code-frame
```

or using yarn:

```sh
yarn add @babel/code-frame --dev
```


---

# @babel/compat-data

> The compat-data to determine required Babel plugins

See our website [@babel/compat-data](https://babeljs.io/docs/babel-compat-data) for more information.

## Install

Using npm:

```sh
npm install --save @babel/compat-data
```

or using yarn:

```sh
yarn add @babel/compat-data
```


---

# @babel/core

> Babel compiler core.

See our website [@babel/core](https://babeljs.io/docs/babel-core) for more information or the [issues](https://github.com/babel/babel/issues?utf8=%E2%9C%93&q=is%3Aissue+label%3A%22pkg%3A%20core%22+is%3Aopen) associated with this package.

## Install

Using npm:

```sh
npm install --save-dev @babel/core
```

or using yarn:

```sh
yarn add @babel/core --dev
```


---

semver(1) -- The semantic versioner for npm
===========================================

## Install

```bash
npm install semver
````

## Usage

As a node module:

```js
const semver = require('semver')

semver.valid('1.2.3') // '1.2.3'
semver.valid('a.b.c') // null
semver.clean('  =v1.2.3   ') // '1.2.3'
semver.satisfies('1.2.3', '1.x || >=2.5.0 || 5.0.0 - 7.2.3') // true
semver.gt('1.2.3', '9.8.7') // false
semver.lt('1.2.3', '9.8.7') // true
semver.minVersion('>=1.0.0') // '1.0.0'
semver.valid(semver.coerce('v2')) // '2.0.0'
semver.valid(semver.coerce('42.6.7.9.3-alpha')) // '42.6.7'
```

As a command-line utility:

```
$ semver -h

A JavaScript implementation of the https://semver.org/ specification
Copyright Isaac Z. Schlueter

Usage: semver [options] <version> [<version> [...]]
Prints valid versions sorted by SemVer precedence

Options:
-r --range <range>
        Print versions that match the specified range.

-i --increment [<level>]
        Increment a version by the specified level.  Level can
        be one of: major, minor, patch, premajor, preminor,
        prepatch, or prerelease.  Default level is 'patch'.
        Only one version may be specified.

--preid <identifier>
        Identifier to be used to prefix premajor, preminor,
        prepatch or prerelease version increments.

-l --loose
        Interpret versions and ranges loosely

-p --include-prerelease
        Always include prerelease versions in range matching

-c --coerce
        Coerce a string into SemVer if possible
        (does not imply --loose)

--rtl
        Coerce version strings right to left

--ltr
        Coerce version strings left to right (default)

Program exits successfully if any valid version satisfies
all supplied ranges, and prints all satisfying versions.

If no satisfying versions are found, then exits failure.

Versions are printed in ascending order, so supplying
multiple versions to the utility will just sort them.
```

## Versions

A "version" is described by the `v2.0.0` specification found at
<https://semver.org/>.

A leading `"="` or `"v"` character is stripped off and ignored.

## Ranges

A `version range` is a set of `comparators` which specify versions
that satisfy the range.

A `comparator` is composed of an `operator` and a `version`.  The set
of primitive `operators` is:

* `<` Less than
* `<=` Less than or equal to
* `>` Greater than
* `>=` Greater than or equal to
* `=` Equal.  If no operator is specified, then equality is assumed,
  so this operator is optional, but MAY be included.

For example, the comparator `>=1.2.7` would match the versions
`1.2.7`, `1.2.8`, `2.5.3`, and `1.3.9`, but not the versions `1.2.6`
or `1.1.0`.

Comparators can be joined by whitespace to form a `comparator set`,
which is satisfied by the **intersection** of all of the comparators
it includes.

A range is composed of one or more comparator sets, joined by `||`.  A
version matches a range if and only if every comparator in at least
one of the `||`-separated comparator sets is satisfied by the version.

For example, the range `>=1.2.7 <1.3.0` would match the versions
`1.2.7`, `1.2.8`, and `1.2.99`, but not the versions `1.2.6`, `1.3.0`,
or `1.1.0`.

The range `1.2.7 || >=1.2.9 <2.0.0` would match the versions `1.2.7`,
`1.2.9`, and `1.4.6`, but not the versions `1.2.8` or `2.0.0`.

### Prerelease Tags

If a version has a prerelease tag (for example, `1.2.3-alpha.3`) then
it will only be allowed to satisfy comparator sets if at least one
comparator with the same `[major, minor, patch]` tuple also has a
prerelease tag.

For example, the range `>1.2.3-alpha.3` would be allowed to match the
version `1.2.3-alpha.7`, but it would *not* be satisfied by
`3.4.5-alpha.9`, even though `3.4.5-alpha.9` is technically "greater
than" `1.2.3-alpha.3` according to the SemVer sort rules.  The version
range only accepts prerelease tags on the `1.2.3` version.  The
version `3.4.5` *would* satisfy the range, because it does not have a
prerelease flag, and `3.4.5` is greater than `1.2.3-alpha.7`.

The purpose for this behavior is twofold.  First, prerelease versions
frequently are updated very quickly, and contain many breaking changes
that are (by the author's design) not yet fit for public consumption.
Therefore, by default, they are excluded from range matching
semantics.

Second, a user who has opted into using a prerelease version has
clearly indicated the intent to use *that specific* set of
alpha/beta/rc versions.  By including a prerelease tag in the range,
the user is indicating that they are aware of the risk.  However, it
is still not appropriate to assume that they have opted into taking a
similar risk on the *next* set of prerelease versions.

Note that this behavior can be suppressed (treating all prerelease
versions as if they were normal versions, for the purpose of range
matching) by setting the `includePrerelease` flag on the options
object to any
[functions](https://github.com/npm/node-semver#functions) that do
range matching.

#### Prerelease Identifiers

The method `.inc` takes an additional `identifier` string argument that
will append the value of the string as a prerelease identifier:

```javascript
semver.inc('1.2.3', 'prerelease', 'beta')
// '1.2.4-beta.0'
```

command-line example:

```bash
$ semver 1.2.3 -i prerelease --preid beta
1.2.4-beta.0
```

Which then can be used to increment further:

```bash
$ semver 1.2.4-beta.0 -i prerelease
1.2.4-beta.1
```

### Advanced Range Syntax

Advanced range syntax desugars to primitive comparators in
deterministic ways.

Advanced ranges may be combined in the same way as primitive
comparators using white space or `||`.

#### Hyphen Ranges `X.Y.Z - A.B.C`

Specifies an inclusive set.

* `1.2.3 - 2.3.4` := `>=1.2.3 <=2.3.4`

If a partial version is provided as the first version in the inclusive
range, then the missing pieces are replaced with zeroes.

* `1.2 - 2.3.4` := `>=1.2.0 <=2.3.4`

If a partial version is provided as the second version in the
inclusive range, then all versions that start with the supplied parts
of the tuple are accepted, but nothing that would be greater than the
provided tuple parts.

* `1.2.3 - 2.3` := `>=1.2.3 <2.4.0`
* `1.2.3 - 2` := `>=1.2.3 <3.0.0`

#### X-Ranges `1.2.x` `1.X` `1.2.*` `*`

Any of `X`, `x`, or `*` may be used to "stand in" for one of the
numeric values in the `[major, minor, patch]` tuple.

* `*` := `>=0.0.0` (Any version satisfies)
* `1.x` := `>=1.0.0 <2.0.0` (Matching major version)
* `1.2.x` := `>=1.2.0 <1.3.0` (Matching major and minor versions)

A partial version range is treated as an X-Range, so the special
character is in fact optional.

* `""` (empty string) := `*` := `>=0.0.0`
* `1` := `1.x.x` := `>=1.0.0 <2.0.0`
* `1.2` := `1.2.x` := `>=1.2.0 <1.3.0`

#### Tilde Ranges `~1.2.3` `~1.2` `~1`

Allows patch-level changes if a minor version is specified on the
comparator.  Allows minor-level changes if not.

* `~1.2.3` := `>=1.2.3 <1.(2+1).0` := `>=1.2.3 <1.3.0`
* `~1.2` := `>=1.2.0 <1.(2+1).0` := `>=1.2.0 <1.3.0` (Same as `1.2.x`)
* `~1` := `>=1.0.0 <(1+1).0.0` := `>=1.0.0 <2.0.0` (Same as `1.x`)
* `~0.2.3` := `>=0.2.3 <0.(2+1).0` := `>=0.2.3 <0.3.0`
* `~0.2` := `>=0.2.0 <0.(2+1).0` := `>=0.2.0 <0.3.0` (Same as `0.2.x`)
* `~0` := `>=0.0.0 <(0+1).0.0` := `>=0.0.0 <1.0.0` (Same as `0.x`)
* `~1.2.3-beta.2` := `>=1.2.3-beta.2 <1.3.0` Note that prereleases in
  the `1.2.3` version will be allowed, if they are greater than or
  equal to `beta.2`.  So, `1.2.3-beta.4` would be allowed, but
  `1.2.4-beta.2` would not, because it is a prerelease of a
  different `[major, minor, patch]` tuple.

#### Caret Ranges `^1.2.3` `^0.2.5` `^0.0.4`

Allows changes that do not modify the left-most non-zero element in the
`[major, minor, patch]` tuple.  In other words, this allows patch and
minor updates for versions `1.0.0` and above, patch updates for
versions `0.X >=0.1.0`, and *no* updates for versions `0.0.X`.

Many authors treat a `0.x` version as if the `x` were the major
"breaking-change" indicator.

Caret ranges are ideal when an author may make breaking changes
between `0.2.4` and `0.3.0` releases, which is a common practice.
However, it presumes that there will *not* be breaking changes between
`0.2.4` and `0.2.5`.  It allows for changes that are presumed to be
additive (but non-breaking), according to commonly observed practices.

* `^1.2.3` := `>=1.2.3 <2.0.0`
* `^0.2.3` := `>=0.2.3 <0.3.0`
* `^0.0.3` := `>=0.0.3 <0.0.4`
* `^1.2.3-beta.2` := `>=1.2.3-beta.2 <2.0.0` Note that prereleases in
  the `1.2.3` version will be allowed, if they are greater than or
  equal to `beta.2`.  So, `1.2.3-beta.4` would be allowed, but
  `1.2.4-beta.2` would not, because it is a prerelease of a
  different `[major, minor, patch]` tuple.
* `^0.0.3-beta` := `>=0.0.3-beta <0.0.4`  Note that prereleases in the
  `0.0.3` version *only* will be allowed, if they are greater than or
  equal to `beta`.  So, `0.0.3-pr.2` would be allowed.

When parsing caret ranges, a missing `patch` value desugars to the
number `0`, but will allow flexibility within that value, even if the
major and minor versions are both `0`.

* `^1.2.x` := `>=1.2.0 <2.0.0`
* `^0.0.x` := `>=0.0.0 <0.1.0`
* `^0.0` := `>=0.0.0 <0.1.0`

A missing `minor` and `patch` values will desugar to zero, but also
allow flexibility within those values, even if the major version is
zero.

* `^1.x` := `>=1.0.0 <2.0.0`
* `^0.x` := `>=0.0.0 <1.0.0`

### Range Grammar

Putting all this together, here is a Backus-Naur grammar for ranges,
for the benefit of parser authors:

```bnf
range-set  ::= range ( logical-or range ) *
logical-or ::= ( ' ' ) * '||' ( ' ' ) *
range      ::= hyphen | simple ( ' ' simple ) * | ''
hyphen     ::= partial ' - ' partial
simple     ::= primitive | partial | tilde | caret
primitive  ::= ( '<' | '>' | '>=' | '<=' | '=' ) partial
partial    ::= xr ( '.' xr ( '.' xr qualifier ? )? )?
xr         ::= 'x' | 'X' | '*' | nr
nr         ::= '0' | ['1'-'9'] ( ['0'-'9'] ) *
tilde      ::= '~' partial
caret      ::= '^' partial
qualifier  ::= ( '-' pre )? ( '+' build )?
pre        ::= parts
build      ::= parts
parts      ::= part ( '.' part ) *
part       ::= nr | [-0-9A-Za-z]+
```

## Functions

All methods and classes take a final `options` object argument.  All
options in this object are `false` by default.  The options supported
are:

- `loose`  Be more forgiving about not-quite-valid semver strings.
  (Any resulting output will always be 100% strict compliant, of
  course.)  For backwards compatibility reasons, if the `options`
  argument is a boolean value instead of an object, it is interpreted
  to be the `loose` param.
- `includePrerelease`  Set to suppress the [default
  behavior](https://github.com/npm/node-semver#prerelease-tags) of
  excluding prerelease tagged versions from ranges unless they are
  explicitly opted into.

Strict-mode Comparators and Ranges will be strict about the SemVer
strings that they parse.

* `valid(v)`: Return the parsed version, or null if it's not valid.
* `inc(v, release)`: Return the version incremented by the release
  type (`major`,   `premajor`, `minor`, `preminor`, `patch`,
  `prepatch`, or `prerelease`), or null if it's not valid
  * `premajor` in one call will bump the version up to the next major
    version and down to a prerelease of that major version.
    `preminor`, and `prepatch` work the same way.
  * If called from a non-prerelease version, the `prerelease` will work the
    same as `prepatch`. It increments the patch version, then makes a
    prerelease. If the input version is already a prerelease it simply
    increments it.
* `prerelease(v)`: Returns an array of prerelease components, or null
  if none exist. Example: `prerelease('1.2.3-alpha.1') -> ['alpha', 1]`
* `major(v)`: Return the major version number.
* `minor(v)`: Return the minor version number.
* `patch(v)`: Return the patch version number.
* `intersects(r1, r2, loose)`: Return true if the two supplied ranges
  or comparators intersect.
* `parse(v)`: Attempt to parse a string as a semantic version, returning either
  a `SemVer` object or `null`.

### Comparison

* `gt(v1, v2)`: `v1 > v2`
* `gte(v1, v2)`: `v1 >= v2`
* `lt(v1, v2)`: `v1 < v2`
* `lte(v1, v2)`: `v1 <= v2`
* `eq(v1, v2)`: `v1 == v2` This is true if they're logically equivalent,
  even if they're not the exact same string.  You already know how to
  compare strings.
* `neq(v1, v2)`: `v1 != v2` The opposite of `eq`.
* `cmp(v1, comparator, v2)`: Pass in a comparison string, and it'll call
  the corresponding function above.  `"==="` and `"!=="` do simple
  string comparison, but are included for completeness.  Throws if an
  invalid comparison string is provided.
* `compare(v1, v2)`: Return `0` if `v1 == v2`, or `1` if `v1` is greater, or `-1` if
  `v2` is greater.  Sorts in ascending order if passed to `Array.sort()`.
* `rcompare(v1, v2)`: The reverse of compare.  Sorts an array of versions
  in descending order when passed to `Array.sort()`.
* `compareBuild(v1, v2)`: The same as `compare` but considers `build` when two versions
  are equal.  Sorts in ascending order if passed to `Array.sort()`.
  `v2` is greater.  Sorts in ascending order if passed to `Array.sort()`.
* `diff(v1, v2)`: Returns difference between two versions by the release type
  (`major`, `premajor`, `minor`, `preminor`, `patch`, `prepatch`, or `prerelease`),
  or null if the versions are the same.

### Comparators

* `intersects(comparator)`: Return true if the comparators intersect

### Ranges

* `validRange(range)`: Return the valid range or null if it's not valid
* `satisfies(version, range)`: Return true if the version satisfies the
  range.
* `maxSatisfying(versions, range)`: Return the highest version in the list
  that satisfies the range, or `null` if none of them do.
* `minSatisfying(versions, range)`: Return the lowest version in the list
  that satisfies the range, or `null` if none of them do.
* `minVersion(range)`: Return the lowest version that can possibly match
  the given range.
* `gtr(version, range)`: Return `true` if version is greater than all the
  versions possible in the range.
* `ltr(version, range)`: Return `true` if version is less than all the
  versions possible in the range.
* `outside(version, range, hilo)`: Return true if the version is outside
  the bounds of the range in either the high or low direction.  The
  `hilo` argument must be either the string `'>'` or `'<'`.  (This is
  the function called by `gtr` and `ltr`.)
* `intersects(range)`: Return true if any of the ranges comparators intersect

Note that, since ranges may be non-contiguous, a version might not be
greater than a range, less than a range, *or* satisfy a range!  For
example, the range `1.2 <1.2.9 || >2.0.0` would have a hole from `1.2.9`
until `2.0.0`, so the version `1.2.10` would not be greater than the
range (because `2.0.1` satisfies, which is higher), nor less than the
range (since `1.2.8` satisfies, which is lower), and it also does not
satisfy the range.

If you want to know if a version satisfies or does not satisfy a
range, use the `satisfies(version, range)` function.

### Coercion

* `coerce(version, options)`: Coerces a string to semver if possible

This aims to provide a very forgiving translation of a non-semver string to
semver. It looks for the first digit in a string, and consumes all
remaining characters which satisfy at least a partial semver (e.g., `1`,
`1.2`, `1.2.3`) up to the max permitted length (256 characters).  Longer
versions are simply truncated (`4.6.3.9.2-alpha2` becomes `4.6.3`).  All
surrounding text is simply ignored (`v3.4 replaces v3.3.1` becomes
`3.4.0`).  Only text which lacks digits will fail coercion (`version one`
is not valid).  The maximum  length for any semver component considered for
coercion is 16 characters; longer components will be ignored
(`10000000000000000.4.7.4` becomes `4.7.4`).  The maximum value for any
semver component is `Integer.MAX_SAFE_INTEGER || (2**53 - 1)`; higher value
components are invalid (`9999999999999999.4.7.4` is likely invalid).

If the `options.rtl` flag is set, then `coerce` will return the right-most
coercible tuple that does not share an ending index with a longer coercible
tuple.  For example, `1.2.3.4` will return `2.3.4` in rtl mode, not
`4.0.0`.  `1.2.3/4` will return `4.0.0`, because the `4` is not a part of
any other overlapping SemVer tuple.

### Clean

* `clean(version)`: Clean a string to be a valid semver if possible

This will return a cleaned and trimmed semver version. If the provided version is not valid a null will be returned. This does not work for ranges. 

ex.
* `s.clean(' = v 2.1.5foo')`: `null`
* `s.clean(' = v 2.1.5foo', { loose: true })`: `'2.1.5-foo'`
* `s.clean(' = v 2.1.5-foo')`: `null`
* `s.clean(' = v 2.1.5-foo', { loose: true })`: `'2.1.5-foo'`
* `s.clean('=v2.1.5')`: `'2.1.5'`
* `s.clean('  =v2.1.5')`: `2.1.5`
* `s.clean('      2.1.5   ')`: `'2.1.5'`
* `s.clean('~1.0.0')`: `null`


---

# @babel/generator

> Turns an AST into code.

See our website [@babel/generator](https://babeljs.io/docs/babel-generator) for more information or the [issues](https://github.com/babel/babel/issues?utf8=%E2%9C%93&q=is%3Aissue+label%3A%22pkg%3A%20generator%22+is%3Aopen) associated with this package.

## Install

Using npm:

```sh
npm install --save-dev @babel/generator
```

or using yarn:

```sh
yarn add @babel/generator --dev
```


---

# @babel/helper-annotate-as-pure

> Helper function to annotate paths and nodes with #__PURE__ comment

See our website [@babel/helper-annotate-as-pure](https://babeljs.io/docs/babel-helper-annotate-as-pure) for more information.

## Install

Using npm:

```sh
npm install --save @babel/helper-annotate-as-pure
```

or using yarn:

```sh
yarn add @babel/helper-annotate-as-pure
```


---

# @babel/helper-compilation-targets

> Helper functions on Babel compilation targets

See our website [@babel/helper-compilation-targets](https://babeljs.io/docs/babel-helper-compilation-targets) for more information.

## Install

Using npm:

```sh
npm install --save @babel/helper-compilation-targets
```

or using yarn:

```sh
yarn add @babel/helper-compilation-targets
```


---

semver(1) -- The semantic versioner for npm
===========================================

## Install

```bash
npm install semver
````

## Usage

As a node module:

```js
const semver = require('semver')

semver.valid('1.2.3') // '1.2.3'
semver.valid('a.b.c') // null
semver.clean('  =v1.2.3   ') // '1.2.3'
semver.satisfies('1.2.3', '1.x || >=2.5.0 || 5.0.0 - 7.2.3') // true
semver.gt('1.2.3', '9.8.7') // false
semver.lt('1.2.3', '9.8.7') // true
semver.minVersion('>=1.0.0') // '1.0.0'
semver.valid(semver.coerce('v2')) // '2.0.0'
semver.valid(semver.coerce('42.6.7.9.3-alpha')) // '42.6.7'
```

As a command-line utility:

```
$ semver -h

A JavaScript implementation of the https://semver.org/ specification
Copyright Isaac Z. Schlueter

Usage: semver [options] <version> [<version> [...]]
Prints valid versions sorted by SemVer precedence

Options:
-r --range <range>
        Print versions that match the specified range.

-i --increment [<level>]
        Increment a version by the specified level.  Level can
        be one of: major, minor, patch, premajor, preminor,
        prepatch, or prerelease.  Default level is 'patch'.
        Only one version may be specified.

--preid <identifier>
        Identifier to be used to prefix premajor, preminor,
        prepatch or prerelease version increments.

-l --loose
        Interpret versions and ranges loosely

-p --include-prerelease
        Always include prerelease versions in range matching

-c --coerce
        Coerce a string into SemVer if possible
        (does not imply --loose)

--rtl
        Coerce version strings right to left

--ltr
        Coerce version strings left to right (default)

Program exits successfully if any valid version satisfies
all supplied ranges, and prints all satisfying versions.

If no satisfying versions are found, then exits failure.

Versions are printed in ascending order, so supplying
multiple versions to the utility will just sort them.
```

## Versions

A "version" is described by the `v2.0.0` specification found at
<https://semver.org/>.

A leading `"="` or `"v"` character is stripped off and ignored.

## Ranges

A `version range` is a set of `comparators` which specify versions
that satisfy the range.

A `comparator` is composed of an `operator` and a `version`.  The set
of primitive `operators` is:

* `<` Less than
* `<=` Less than or equal to
* `>` Greater than
* `>=` Greater than or equal to
* `=` Equal.  If no operator is specified, then equality is assumed,
  so this operator is optional, but MAY be included.

For example, the comparator `>=1.2.7` would match the versions
`1.2.7`, `1.2.8`, `2.5.3`, and `1.3.9`, but not the versions `1.2.6`
or `1.1.0`.

Comparators can be joined by whitespace to form a `comparator set`,
which is satisfied by the **intersection** of all of the comparators
it includes.

A range is composed of one or more comparator sets, joined by `||`.  A
version matches a range if and only if every comparator in at least
one of the `||`-separated comparator sets is satisfied by the version.

For example, the range `>=1.2.7 <1.3.0` would match the versions
`1.2.7`, `1.2.8`, and `1.2.99`, but not the versions `1.2.6`, `1.3.0`,
or `1.1.0`.

The range `1.2.7 || >=1.2.9 <2.0.0` would match the versions `1.2.7`,
`1.2.9`, and `1.4.6`, but not the versions `1.2.8` or `2.0.0`.

### Prerelease Tags

If a version has a prerelease tag (for example, `1.2.3-alpha.3`) then
it will only be allowed to satisfy comparator sets if at least one
comparator with the same `[major, minor, patch]` tuple also has a
prerelease tag.

For example, the range `>1.2.3-alpha.3` would be allowed to match the
version `1.2.3-alpha.7`, but it would *not* be satisfied by
`3.4.5-alpha.9`, even though `3.4.5-alpha.9` is technically "greater
than" `1.2.3-alpha.3` according to the SemVer sort rules.  The version
range only accepts prerelease tags on the `1.2.3` version.  The
version `3.4.5` *would* satisfy the range, because it does not have a
prerelease flag, and `3.4.5` is greater than `1.2.3-alpha.7`.

The purpose for this behavior is twofold.  First, prerelease versions
frequently are updated very quickly, and contain many breaking changes
that are (by the author's design) not yet fit for public consumption.
Therefore, by default, they are excluded from range matching
semantics.

Second, a user who has opted into using a prerelease version has
clearly indicated the intent to use *that specific* set of
alpha/beta/rc versions.  By including a prerelease tag in the range,
the user is indicating that they are aware of the risk.  However, it
is still not appropriate to assume that they have opted into taking a
similar risk on the *next* set of prerelease versions.

Note that this behavior can be suppressed (treating all prerelease
versions as if they were normal versions, for the purpose of range
matching) by setting the `includePrerelease` flag on the options
object to any
[functions](https://github.com/npm/node-semver#functions) that do
range matching.

#### Prerelease Identifiers

The method `.inc` takes an additional `identifier` string argument that
will append the value of the string as a prerelease identifier:

```javascript
semver.inc('1.2.3', 'prerelease', 'beta')
// '1.2.4-beta.0'
```

command-line example:

```bash
$ semver 1.2.3 -i prerelease --preid beta
1.2.4-beta.0
```

Which then can be used to increment further:

```bash
$ semver 1.2.4-beta.0 -i prerelease
1.2.4-beta.1
```

### Advanced Range Syntax

Advanced range syntax desugars to primitive comparators in
deterministic ways.

Advanced ranges may be combined in the same way as primitive
comparators using white space or `||`.

#### Hyphen Ranges `X.Y.Z - A.B.C`

Specifies an inclusive set.

* `1.2.3 - 2.3.4` := `>=1.2.3 <=2.3.4`

If a partial version is provided as the first version in the inclusive
range, then the missing pieces are replaced with zeroes.

* `1.2 - 2.3.4` := `>=1.2.0 <=2.3.4`

If a partial version is provided as the second version in the
inclusive range, then all versions that start with the supplied parts
of the tuple are accepted, but nothing that would be greater than the
provided tuple parts.

* `1.2.3 - 2.3` := `>=1.2.3 <2.4.0`
* `1.2.3 - 2` := `>=1.2.3 <3.0.0`

#### X-Ranges `1.2.x` `1.X` `1.2.*` `*`

Any of `X`, `x`, or `*` may be used to "stand in" for one of the
numeric values in the `[major, minor, patch]` tuple.

* `*` := `>=0.0.0` (Any version satisfies)
* `1.x` := `>=1.0.0 <2.0.0` (Matching major version)
* `1.2.x` := `>=1.2.0 <1.3.0` (Matching major and minor versions)

A partial version range is treated as an X-Range, so the special
character is in fact optional.

* `""` (empty string) := `*` := `>=0.0.0`
* `1` := `1.x.x` := `>=1.0.0 <2.0.0`
* `1.2` := `1.2.x` := `>=1.2.0 <1.3.0`

#### Tilde Ranges `~1.2.3` `~1.2` `~1`

Allows patch-level changes if a minor version is specified on the
comparator.  Allows minor-level changes if not.

* `~1.2.3` := `>=1.2.3 <1.(2+1).0` := `>=1.2.3 <1.3.0`
* `~1.2` := `>=1.2.0 <1.(2+1).0` := `>=1.2.0 <1.3.0` (Same as `1.2.x`)
* `~1` := `>=1.0.0 <(1+1).0.0` := `>=1.0.0 <2.0.0` (Same as `1.x`)
* `~0.2.3` := `>=0.2.3 <0.(2+1).0` := `>=0.2.3 <0.3.0`
* `~0.2` := `>=0.2.0 <0.(2+1).0` := `>=0.2.0 <0.3.0` (Same as `0.2.x`)
* `~0` := `>=0.0.0 <(0+1).0.0` := `>=0.0.0 <1.0.0` (Same as `0.x`)
* `~1.2.3-beta.2` := `>=1.2.3-beta.2 <1.3.0` Note that prereleases in
  the `1.2.3` version will be allowed, if they are greater than or
  equal to `beta.2`.  So, `1.2.3-beta.4` would be allowed, but
  `1.2.4-beta.2` would not, because it is a prerelease of a
  different `[major, minor, patch]` tuple.

#### Caret Ranges `^1.2.3` `^0.2.5` `^0.0.4`

Allows changes that do not modify the left-most non-zero element in the
`[major, minor, patch]` tuple.  In other words, this allows patch and
minor updates for versions `1.0.0` and above, patch updates for
versions `0.X >=0.1.0`, and *no* updates for versions `0.0.X`.

Many authors treat a `0.x` version as if the `x` were the major
"breaking-change" indicator.

Caret ranges are ideal when an author may make breaking changes
between `0.2.4` and `0.3.0` releases, which is a common practice.
However, it presumes that there will *not* be breaking changes between
`0.2.4` and `0.2.5`.  It allows for changes that are presumed to be
additive (but non-breaking), according to commonly observed practices.

* `^1.2.3` := `>=1.2.3 <2.0.0`
* `^0.2.3` := `>=0.2.3 <0.3.0`
* `^0.0.3` := `>=0.0.3 <0.0.4`
* `^1.2.3-beta.2` := `>=1.2.3-beta.2 <2.0.0` Note that prereleases in
  the `1.2.3` version will be allowed, if they are greater than or
  equal to `beta.2`.  So, `1.2.3-beta.4` would be allowed, but
  `1.2.4-beta.2` would not, because it is a prerelease of a
  different `[major, minor, patch]` tuple.
* `^0.0.3-beta` := `>=0.0.3-beta <0.0.4`  Note that prereleases in the
  `0.0.3` version *only* will be allowed, if they are greater than or
  equal to `beta`.  So, `0.0.3-pr.2` would be allowed.

When parsing caret ranges, a missing `patch` value desugars to the
number `0`, but will allow flexibility within that value, even if the
major and minor versions are both `0`.

* `^1.2.x` := `>=1.2.0 <2.0.0`
* `^0.0.x` := `>=0.0.0 <0.1.0`
* `^0.0` := `>=0.0.0 <0.1.0`

A missing `minor` and `patch` values will desugar to zero, but also
allow flexibility within those values, even if the major version is
zero.

* `^1.x` := `>=1.0.0 <2.0.0`
* `^0.x` := `>=0.0.0 <1.0.0`

### Range Grammar

Putting all this together, here is a Backus-Naur grammar for ranges,
for the benefit of parser authors:

```bnf
range-set  ::= range ( logical-or range ) *
logical-or ::= ( ' ' ) * '||' ( ' ' ) *
range      ::= hyphen | simple ( ' ' simple ) * | ''
hyphen     ::= partial ' - ' partial
simple     ::= primitive | partial | tilde | caret
primitive  ::= ( '<' | '>' | '>=' | '<=' | '=' ) partial
partial    ::= xr ( '.' xr ( '.' xr qualifier ? )? )?
xr         ::= 'x' | 'X' | '*' | nr
nr         ::= '0' | ['1'-'9'] ( ['0'-'9'] ) *
tilde      ::= '~' partial
caret      ::= '^' partial
qualifier  ::= ( '-' pre )? ( '+' build )?
pre        ::= parts
build      ::= parts
parts      ::= part ( '.' part ) *
part       ::= nr | [-0-9A-Za-z]+
```

## Functions

All methods and classes take a final `options` object argument.  All
options in this object are `false` by default.  The options supported
are:

- `loose`  Be more forgiving about not-quite-valid semver strings.
  (Any resulting output will always be 100% strict compliant, of
  course.)  For backwards compatibility reasons, if the `options`
  argument is a boolean value instead of an object, it is interpreted
  to be the `loose` param.
- `includePrerelease`  Set to suppress the [default
  behavior](https://github.com/npm/node-semver#prerelease-tags) of
  excluding prerelease tagged versions from ranges unless they are
  explicitly opted into.

Strict-mode Comparators and Ranges will be strict about the SemVer
strings that they parse.

* `valid(v)`: Return the parsed version, or null if it's not valid.
* `inc(v, release)`: Return the version incremented by the release
  type (`major`,   `premajor`, `minor`, `preminor`, `patch`,
  `prepatch`, or `prerelease`), or null if it's not valid
  * `premajor` in one call will bump the version up to the next major
    version and down to a prerelease of that major version.
    `preminor`, and `prepatch` work the same way.
  * If called from a non-prerelease version, the `prerelease` will work the
    same as `prepatch`. It increments the patch version, then makes a
    prerelease. If the input version is already a prerelease it simply
    increments it.
* `prerelease(v)`: Returns an array of prerelease components, or null
  if none exist. Example: `prerelease('1.2.3-alpha.1') -> ['alpha', 1]`
* `major(v)`: Return the major version number.
* `minor(v)`: Return the minor version number.
* `patch(v)`: Return the patch version number.
* `intersects(r1, r2, loose)`: Return true if the two supplied ranges
  or comparators intersect.
* `parse(v)`: Attempt to parse a string as a semantic version, returning either
  a `SemVer` object or `null`.

### Comparison

* `gt(v1, v2)`: `v1 > v2`
* `gte(v1, v2)`: `v1 >= v2`
* `lt(v1, v2)`: `v1 < v2`
* `lte(v1, v2)`: `v1 <= v2`
* `eq(v1, v2)`: `v1 == v2` This is true if they're logically equivalent,
  even if they're not the exact same string.  You already know how to
  compare strings.
* `neq(v1, v2)`: `v1 != v2` The opposite of `eq`.
* `cmp(v1, comparator, v2)`: Pass in a comparison string, and it'll call
  the corresponding function above.  `"==="` and `"!=="` do simple
  string comparison, but are included for completeness.  Throws if an
  invalid comparison string is provided.
* `compare(v1, v2)`: Return `0` if `v1 == v2`, or `1` if `v1` is greater, or `-1` if
  `v2` is greater.  Sorts in ascending order if passed to `Array.sort()`.
* `rcompare(v1, v2)`: The reverse of compare.  Sorts an array of versions
  in descending order when passed to `Array.sort()`.
* `compareBuild(v1, v2)`: The same as `compare` but considers `build` when two versions
  are equal.  Sorts in ascending order if passed to `Array.sort()`.
  `v2` is greater.  Sorts in ascending order if passed to `Array.sort()`.
* `diff(v1, v2)`: Returns difference between two versions by the release type
  (`major`, `premajor`, `minor`, `preminor`, `patch`, `prepatch`, or `prerelease`),
  or null if the versions are the same.

### Comparators

* `intersects(comparator)`: Return true if the comparators intersect

### Ranges

* `validRange(range)`: Return the valid range or null if it's not valid
* `satisfies(version, range)`: Return true if the version satisfies the
  range.
* `maxSatisfying(versions, range)`: Return the highest version in the list
  that satisfies the range, or `null` if none of them do.
* `minSatisfying(versions, range)`: Return the lowest version in the list
  that satisfies the range, or `null` if none of them do.
* `minVersion(range)`: Return the lowest version that can possibly match
  the given range.
* `gtr(version, range)`: Return `true` if version is greater than all the
  versions possible in the range.
* `ltr(version, range)`: Return `true` if version is less than all the
  versions possible in the range.
* `outside(version, range, hilo)`: Return true if the version is outside
  the bounds of the range in either the high or low direction.  The
  `hilo` argument must be either the string `'>'` or `'<'`.  (This is
  the function called by `gtr` and `ltr`.)
* `intersects(range)`: Return true if any of the ranges comparators intersect

Note that, since ranges may be non-contiguous, a version might not be
greater than a range, less than a range, *or* satisfy a range!  For
example, the range `1.2 <1.2.9 || >2.0.0` would have a hole from `1.2.9`
until `2.0.0`, so the version `1.2.10` would not be greater than the
range (because `2.0.1` satisfies, which is higher), nor less than the
range (since `1.2.8` satisfies, which is lower), and it also does not
satisfy the range.

If you want to know if a version satisfies or does not satisfy a
range, use the `satisfies(version, range)` function.

### Coercion

* `coerce(version, options)`: Coerces a string to semver if possible

This aims to provide a very forgiving translation of a non-semver string to
semver. It looks for the first digit in a string, and consumes all
remaining characters which satisfy at least a partial semver (e.g., `1`,
`1.2`, `1.2.3`) up to the max permitted length (256 characters).  Longer
versions are simply truncated (`4.6.3.9.2-alpha2` becomes `4.6.3`).  All
surrounding text is simply ignored (`v3.4 replaces v3.3.1` becomes
`3.4.0`).  Only text which lacks digits will fail coercion (`version one`
is not valid).  The maximum  length for any semver component considered for
coercion is 16 characters; longer components will be ignored
(`10000000000000000.4.7.4` becomes `4.7.4`).  The maximum value for any
semver component is `Integer.MAX_SAFE_INTEGER || (2**53 - 1)`; higher value
components are invalid (`9999999999999999.4.7.4` is likely invalid).

If the `options.rtl` flag is set, then `coerce` will return the right-most
coercible tuple that does not share an ending index with a longer coercible
tuple.  For example, `1.2.3.4` will return `2.3.4` in rtl mode, not
`4.0.0`.  `1.2.3/4` will return `4.0.0`, because the `4` is not a part of
any other overlapping SemVer tuple.

### Clean

* `clean(version)`: Clean a string to be a valid semver if possible

This will return a cleaned and trimmed semver version. If the provided version is not valid a null will be returned. This does not work for ranges. 

ex.
* `s.clean(' = v 2.1.5foo')`: `null`
* `s.clean(' = v 2.1.5foo', { loose: true })`: `'2.1.5-foo'`
* `s.clean(' = v 2.1.5-foo')`: `null`
* `s.clean(' = v 2.1.5-foo', { loose: true })`: `'2.1.5-foo'`
* `s.clean('=v2.1.5')`: `'2.1.5'`
* `s.clean('  =v2.1.5')`: `2.1.5`
* `s.clean('      2.1.5   ')`: `'2.1.5'`
* `s.clean('~1.0.0')`: `null`


---

# @babel/helper-create-class-features-plugin

> Compile class public and private fields, private methods and decorators to ES6

See our website [@babel/helper-create-class-features-plugin](https://babeljs.io/docs/babel-helper-create-class-features-plugin) for more information.

## Install

Using npm:

```sh
npm install --save @babel/helper-create-class-features-plugin
```

or using yarn:

```sh
yarn add @babel/helper-create-class-features-plugin
```


---

semver(1) -- The semantic versioner for npm
===========================================

## Install

```bash
npm install semver
````

## Usage

As a node module:

```js
const semver = require('semver')

semver.valid('1.2.3') // '1.2.3'
semver.valid('a.b.c') // null
semver.clean('  =v1.2.3   ') // '1.2.3'
semver.satisfies('1.2.3', '1.x || >=2.5.0 || 5.0.0 - 7.2.3') // true
semver.gt('1.2.3', '9.8.7') // false
semver.lt('1.2.3', '9.8.7') // true
semver.minVersion('>=1.0.0') // '1.0.0'
semver.valid(semver.coerce('v2')) // '2.0.0'
semver.valid(semver.coerce('42.6.7.9.3-alpha')) // '42.6.7'
```

As a command-line utility:

```
$ semver -h

A JavaScript implementation of the https://semver.org/ specification
Copyright Isaac Z. Schlueter

Usage: semver [options] <version> [<version> [...]]
Prints valid versions sorted by SemVer precedence

Options:
-r --range <range>
        Print versions that match the specified range.

-i --increment [<level>]
        Increment a version by the specified level.  Level can
        be one of: major, minor, patch, premajor, preminor,
        prepatch, or prerelease.  Default level is 'patch'.
        Only one version may be specified.

--preid <identifier>
        Identifier to be used to prefix premajor, preminor,
        prepatch or prerelease version increments.

-l --loose
        Interpret versions and ranges loosely

-p --include-prerelease
        Always include prerelease versions in range matching

-c --coerce
        Coerce a string into SemVer if possible
        (does not imply --loose)

--rtl
        Coerce version strings right to left

--ltr
        Coerce version strings left to right (default)

Program exits successfully if any valid version satisfies
all supplied ranges, and prints all satisfying versions.

If no satisfying versions are found, then exits failure.

Versions are printed in ascending order, so supplying
multiple versions to the utility will just sort them.
```

## Versions

A "version" is described by the `v2.0.0` specification found at
<https://semver.org/>.

A leading `"="` or `"v"` character is stripped off and ignored.

## Ranges

A `version range` is a set of `comparators` which specify versions
that satisfy the range.

A `comparator` is composed of an `operator` and a `version`.  The set
of primitive `operators` is:

* `<` Less than
* `<=` Less than or equal to
* `>` Greater than
* `>=` Greater than or equal to
* `=` Equal.  If no operator is specified, then equality is assumed,
  so this operator is optional, but MAY be included.

For example, the comparator `>=1.2.7` would match the versions
`1.2.7`, `1.2.8`, `2.5.3`, and `1.3.9`, but not the versions `1.2.6`
or `1.1.0`.

Comparators can be joined by whitespace to form a `comparator set`,
which is satisfied by the **intersection** of all of the comparators
it includes.

A range is composed of one or more comparator sets, joined by `||`.  A
version matches a range if and only if every comparator in at least
one of the `||`-separated comparator sets is satisfied by the version.

For example, the range `>=1.2.7 <1.3.0` would match the versions
`1.2.7`, `1.2.8`, and `1.2.99`, but not the versions `1.2.6`, `1.3.0`,
or `1.1.0`.

The range `1.2.7 || >=1.2.9 <2.0.0` would match the versions `1.2.7`,
`1.2.9`, and `1.4.6`, but not the versions `1.2.8` or `2.0.0`.

### Prerelease Tags

If a version has a prerelease tag (for example, `1.2.3-alpha.3`) then
it will only be allowed to satisfy comparator sets if at least one
comparator with the same `[major, minor, patch]` tuple also has a
prerelease tag.

For example, the range `>1.2.3-alpha.3` would be allowed to match the
version `1.2.3-alpha.7`, but it would *not* be satisfied by
`3.4.5-alpha.9`, even though `3.4.5-alpha.9` is technically "greater
than" `1.2.3-alpha.3` according to the SemVer sort rules.  The version
range only accepts prerelease tags on the `1.2.3` version.  The
version `3.4.5` *would* satisfy the range, because it does not have a
prerelease flag, and `3.4.5` is greater than `1.2.3-alpha.7`.

The purpose for this behavior is twofold.  First, prerelease versions
frequently are updated very quickly, and contain many breaking changes
that are (by the author's design) not yet fit for public consumption.
Therefore, by default, they are excluded from range matching
semantics.

Second, a user who has opted into using a prerelease version has
clearly indicated the intent to use *that specific* set of
alpha/beta/rc versions.  By including a prerelease tag in the range,
the user is indicating that they are aware of the risk.  However, it
is still not appropriate to assume that they have opted into taking a
similar risk on the *next* set of prerelease versions.

Note that this behavior can be suppressed (treating all prerelease
versions as if they were normal versions, for the purpose of range
matching) by setting the `includePrerelease` flag on the options
object to any
[functions](https://github.com/npm/node-semver#functions) that do
range matching.

#### Prerelease Identifiers

The method `.inc` takes an additional `identifier` string argument that
will append the value of the string as a prerelease identifier:

```javascript
semver.inc('1.2.3', 'prerelease', 'beta')
// '1.2.4-beta.0'
```

command-line example:

```bash
$ semver 1.2.3 -i prerelease --preid beta
1.2.4-beta.0
```

Which then can be used to increment further:

```bash
$ semver 1.2.4-beta.0 -i prerelease
1.2.4-beta.1
```

### Advanced Range Syntax

Advanced range syntax desugars to primitive comparators in
deterministic ways.

Advanced ranges may be combined in the same way as primitive
comparators using white space or `||`.

#### Hyphen Ranges `X.Y.Z - A.B.C`

Specifies an inclusive set.

* `1.2.3 - 2.3.4` := `>=1.2.3 <=2.3.4`

If a partial version is provided as the first version in the inclusive
range, then the missing pieces are replaced with zeroes.

* `1.2 - 2.3.4` := `>=1.2.0 <=2.3.4`

If a partial version is provided as the second version in the
inclusive range, then all versions that start with the supplied parts
of the tuple are accepted, but nothing that would be greater than the
provided tuple parts.

* `1.2.3 - 2.3` := `>=1.2.3 <2.4.0`
* `1.2.3 - 2` := `>=1.2.3 <3.0.0`

#### X-Ranges `1.2.x` `1.X` `1.2.*` `*`

Any of `X`, `x`, or `*` may be used to "stand in" for one of the
numeric values in the `[major, minor, patch]` tuple.

* `*` := `>=0.0.0` (Any version satisfies)
* `1.x` := `>=1.0.0 <2.0.0` (Matching major version)
* `1.2.x` := `>=1.2.0 <1.3.0` (Matching major and minor versions)

A partial version range is treated as an X-Range, so the special
character is in fact optional.

* `""` (empty string) := `*` := `>=0.0.0`
* `1` := `1.x.x` := `>=1.0.0 <2.0.0`
* `1.2` := `1.2.x` := `>=1.2.0 <1.3.0`

#### Tilde Ranges `~1.2.3` `~1.2` `~1`

Allows patch-level changes if a minor version is specified on the
comparator.  Allows minor-level changes if not.

* `~1.2.3` := `>=1.2.3 <1.(2+1).0` := `>=1.2.3 <1.3.0`
* `~1.2` := `>=1.2.0 <1.(2+1).0` := `>=1.2.0 <1.3.0` (Same as `1.2.x`)
* `~1` := `>=1.0.0 <(1+1).0.0` := `>=1.0.0 <2.0.0` (Same as `1.x`)
* `~0.2.3` := `>=0.2.3 <0.(2+1).0` := `>=0.2.3 <0.3.0`
* `~0.2` := `>=0.2.0 <0.(2+1).0` := `>=0.2.0 <0.3.0` (Same as `0.2.x`)
* `~0` := `>=0.0.0 <(0+1).0.0` := `>=0.0.0 <1.0.0` (Same as `0.x`)
* `~1.2.3-beta.2` := `>=1.2.3-beta.2 <1.3.0` Note that prereleases in
  the `1.2.3` version will be allowed, if they are greater than or
  equal to `beta.2`.  So, `1.2.3-beta.4` would be allowed, but
  `1.2.4-beta.2` would not, because it is a prerelease of a
  different `[major, minor, patch]` tuple.

#### Caret Ranges `^1.2.3` `^0.2.5` `^0.0.4`

Allows changes that do not modify the left-most non-zero element in the
`[major, minor, patch]` tuple.  In other words, this allows patch and
minor updates for versions `1.0.0` and above, patch updates for
versions `0.X >=0.1.0`, and *no* updates for versions `0.0.X`.

Many authors treat a `0.x` version as if the `x` were the major
"breaking-change" indicator.

Caret ranges are ideal when an author may make breaking changes
between `0.2.4` and `0.3.0` releases, which is a common practice.
However, it presumes that there will *not* be breaking changes between
`0.2.4` and `0.2.5`.  It allows for changes that are presumed to be
additive (but non-breaking), according to commonly observed practices.

* `^1.2.3` := `>=1.2.3 <2.0.0`
* `^0.2.3` := `>=0.2.3 <0.3.0`
* `^0.0.3` := `>=0.0.3 <0.0.4`
* `^1.2.3-beta.2` := `>=1.2.3-beta.2 <2.0.0` Note that prereleases in
  the `1.2.3` version will be allowed, if they are greater than or
  equal to `beta.2`.  So, `1.2.3-beta.4` would be allowed, but
  `1.2.4-beta.2` would not, because it is a prerelease of a
  different `[major, minor, patch]` tuple.
* `^0.0.3-beta` := `>=0.0.3-beta <0.0.4`  Note that prereleases in the
  `0.0.3` version *only* will be allowed, if they are greater than or
  equal to `beta`.  So, `0.0.3-pr.2` would be allowed.

When parsing caret ranges, a missing `patch` value desugars to the
number `0`, but will allow flexibility within that value, even if the
major and minor versions are both `0`.

* `^1.2.x` := `>=1.2.0 <2.0.0`
* `^0.0.x` := `>=0.0.0 <0.1.0`
* `^0.0` := `>=0.0.0 <0.1.0`

A missing `minor` and `patch` values will desugar to zero, but also
allow flexibility within those values, even if the major version is
zero.

* `^1.x` := `>=1.0.0 <2.0.0`
* `^0.x` := `>=0.0.0 <1.0.0`

### Range Grammar

Putting all this together, here is a Backus-Naur grammar for ranges,
for the benefit of parser authors:

```bnf
range-set  ::= range ( logical-or range ) *
logical-or ::= ( ' ' ) * '||' ( ' ' ) *
range      ::= hyphen | simple ( ' ' simple ) * | ''
hyphen     ::= partial ' - ' partial
simple     ::= primitive | partial | tilde | caret
primitive  ::= ( '<' | '>' | '>=' | '<=' | '=' ) partial
partial    ::= xr ( '.' xr ( '.' xr qualifier ? )? )?
xr         ::= 'x' | 'X' | '*' | nr
nr         ::= '0' | ['1'-'9'] ( ['0'-'9'] ) *
tilde      ::= '~' partial
caret      ::= '^' partial
qualifier  ::= ( '-' pre )? ( '+' build )?
pre        ::= parts
build      ::= parts
parts      ::= part ( '.' part ) *
part       ::= nr | [-0-9A-Za-z]+
```

## Functions

All methods and classes take a final `options` object argument.  All
options in this object are `false` by default.  The options supported
are:

- `loose`  Be more forgiving about not-quite-valid semver strings.
  (Any resulting output will always be 100% strict compliant, of
  course.)  For backwards compatibility reasons, if the `options`
  argument is a boolean value instead of an object, it is interpreted
  to be the `loose` param.
- `includePrerelease`  Set to suppress the [default
  behavior](https://github.com/npm/node-semver#prerelease-tags) of
  excluding prerelease tagged versions from ranges unless they are
  explicitly opted into.

Strict-mode Comparators and Ranges will be strict about the SemVer
strings that they parse.

* `valid(v)`: Return the parsed version, or null if it's not valid.
* `inc(v, release)`: Return the version incremented by the release
  type (`major`,   `premajor`, `minor`, `preminor`, `patch`,
  `prepatch`, or `prerelease`), or null if it's not valid
  * `premajor` in one call will bump the version up to the next major
    version and down to a prerelease of that major version.
    `preminor`, and `prepatch` work the same way.
  * If called from a non-prerelease version, the `prerelease` will work the
    same as `prepatch`. It increments the patch version, then makes a
    prerelease. If the input version is already a prerelease it simply
    increments it.
* `prerelease(v)`: Returns an array of prerelease components, or null
  if none exist. Example: `prerelease('1.2.3-alpha.1') -> ['alpha', 1]`
* `major(v)`: Return the major version number.
* `minor(v)`: Return the minor version number.
* `patch(v)`: Return the patch version number.
* `intersects(r1, r2, loose)`: Return true if the two supplied ranges
  or comparators intersect.
* `parse(v)`: Attempt to parse a string as a semantic version, returning either
  a `SemVer` object or `null`.

### Comparison

* `gt(v1, v2)`: `v1 > v2`
* `gte(v1, v2)`: `v1 >= v2`
* `lt(v1, v2)`: `v1 < v2`
* `lte(v1, v2)`: `v1 <= v2`
* `eq(v1, v2)`: `v1 == v2` This is true if they're logically equivalent,
  even if they're not the exact same string.  You already know how to
  compare strings.
* `neq(v1, v2)`: `v1 != v2` The opposite of `eq`.
* `cmp(v1, comparator, v2)`: Pass in a comparison string, and it'll call
  the corresponding function above.  `"==="` and `"!=="` do simple
  string comparison, but are included for completeness.  Throws if an
  invalid comparison string is provided.
* `compare(v1, v2)`: Return `0` if `v1 == v2`, or `1` if `v1` is greater, or `-1` if
  `v2` is greater.  Sorts in ascending order if passed to `Array.sort()`.
* `rcompare(v1, v2)`: The reverse of compare.  Sorts an array of versions
  in descending order when passed to `Array.sort()`.
* `compareBuild(v1, v2)`: The same as `compare` but considers `build` when two versions
  are equal.  Sorts in ascending order if passed to `Array.sort()`.
  `v2` is greater.  Sorts in ascending order if passed to `Array.sort()`.
* `diff(v1, v2)`: Returns difference between two versions by the release type
  (`major`, `premajor`, `minor`, `preminor`, `patch`, `prepatch`, or `prerelease`),
  or null if the versions are the same.

### Comparators

* `intersects(comparator)`: Return true if the comparators intersect

### Ranges

* `validRange(range)`: Return the valid range or null if it's not valid
* `satisfies(version, range)`: Return true if the version satisfies the
  range.
* `maxSatisfying(versions, range)`: Return the highest version in the list
  that satisfies the range, or `null` if none of them do.
* `minSatisfying(versions, range)`: Return the lowest version in the list
  that satisfies the range, or `null` if none of them do.
* `minVersion(range)`: Return the lowest version that can possibly match
  the given range.
* `gtr(version, range)`: Return `true` if version is greater than all the
  versions possible in the range.
* `ltr(version, range)`: Return `true` if version is less than all the
  versions possible in the range.
* `outside(version, range, hilo)`: Return true if the version is outside
  the bounds of the range in either the high or low direction.  The
  `hilo` argument must be either the string `'>'` or `'<'`.  (This is
  the function called by `gtr` and `ltr`.)
* `intersects(range)`: Return true if any of the ranges comparators intersect

Note that, since ranges may be non-contiguous, a version might not be
greater than a range, less than a range, *or* satisfy a range!  For
example, the range `1.2 <1.2.9 || >2.0.0` would have a hole from `1.2.9`
until `2.0.0`, so the version `1.2.10` would not be greater than the
range (because `2.0.1` satisfies, which is higher), nor less than the
range (since `1.2.8` satisfies, which is lower), and it also does not
satisfy the range.

If you want to know if a version satisfies or does not satisfy a
range, use the `satisfies(version, range)` function.

### Coercion

* `coerce(version, options)`: Coerces a string to semver if possible

This aims to provide a very forgiving translation of a non-semver string to
semver. It looks for the first digit in a string, and consumes all
remaining characters which satisfy at least a partial semver (e.g., `1`,
`1.2`, `1.2.3`) up to the max permitted length (256 characters).  Longer
versions are simply truncated (`4.6.3.9.2-alpha2` becomes `4.6.3`).  All
surrounding text is simply ignored (`v3.4 replaces v3.3.1` becomes
`3.4.0`).  Only text which lacks digits will fail coercion (`version one`
is not valid).  The maximum  length for any semver component considered for
coercion is 16 characters; longer components will be ignored
(`10000000000000000.4.7.4` becomes `4.7.4`).  The maximum value for any
semver component is `Integer.MAX_SAFE_INTEGER || (2**53 - 1)`; higher value
components are invalid (`9999999999999999.4.7.4` is likely invalid).

If the `options.rtl` flag is set, then `coerce` will return the right-most
coercible tuple that does not share an ending index with a longer coercible
tuple.  For example, `1.2.3.4` will return `2.3.4` in rtl mode, not
`4.0.0`.  `1.2.3/4` will return `4.0.0`, because the `4` is not a part of
any other overlapping SemVer tuple.

### Clean

* `clean(version)`: Clean a string to be a valid semver if possible

This will return a cleaned and trimmed semver version. If the provided version is not valid a null will be returned. This does not work for ranges. 

ex.
* `s.clean(' = v 2.1.5foo')`: `null`
* `s.clean(' = v 2.1.5foo', { loose: true })`: `'2.1.5-foo'`
* `s.clean(' = v 2.1.5-foo')`: `null`
* `s.clean(' = v 2.1.5-foo', { loose: true })`: `'2.1.5-foo'`
* `s.clean('=v2.1.5')`: `'2.1.5'`
* `s.clean('  =v2.1.5')`: `2.1.5`
* `s.clean('      2.1.5   ')`: `'2.1.5'`
* `s.clean('~1.0.0')`: `null`


---

# @babel/helper-create-regexp-features-plugin

> Compile ESNext Regular Expressions to ES5

See our website [@babel/helper-create-regexp-features-plugin](https://babeljs.io/docs/babel-helper-create-regexp-features-plugin) for more information.

## Install

Using npm:

```sh
npm install --save @babel/helper-create-regexp-features-plugin
```

or using yarn:

```sh
yarn add @babel/helper-create-regexp-features-plugin
```


---

semver(1) -- The semantic versioner for npm
===========================================

## Install

```bash
npm install semver
````

## Usage

As a node module:

```js
const semver = require('semver')

semver.valid('1.2.3') // '1.2.3'
semver.valid('a.b.c') // null
semver.clean('  =v1.2.3   ') // '1.2.3'
semver.satisfies('1.2.3', '1.x || >=2.5.0 || 5.0.0 - 7.2.3') // true
semver.gt('1.2.3', '9.8.7') // false
semver.lt('1.2.3', '9.8.7') // true
semver.minVersion('>=1.0.0') // '1.0.0'
semver.valid(semver.coerce('v2')) // '2.0.0'
semver.valid(semver.coerce('42.6.7.9.3-alpha')) // '42.6.7'
```

As a command-line utility:

```
$ semver -h

A JavaScript implementation of the https://semver.org/ specification
Copyright Isaac Z. Schlueter

Usage: semver [options] <version> [<version> [...]]
Prints valid versions sorted by SemVer precedence

Options:
-r --range <range>
        Print versions that match the specified range.

-i --increment [<level>]
        Increment a version by the specified level.  Level can
        be one of: major, minor, patch, premajor, preminor,
        prepatch, or prerelease.  Default level is 'patch'.
        Only one version may be specified.

--preid <identifier>
        Identifier to be used to prefix premajor, preminor,
        prepatch or prerelease version increments.

-l --loose
        Interpret versions and ranges loosely

-p --include-prerelease
        Always include prerelease versions in range matching

-c --coerce
        Coerce a string into SemVer if possible
        (does not imply --loose)

--rtl
        Coerce version strings right to left

--ltr
        Coerce version strings left to right (default)

Program exits successfully if any valid version satisfies
all supplied ranges, and prints all satisfying versions.

If no satisfying versions are found, then exits failure.

Versions are printed in ascending order, so supplying
multiple versions to the utility will just sort them.
```

## Versions

A "version" is described by the `v2.0.0` specification found at
<https://semver.org/>.

A leading `"="` or `"v"` character is stripped off and ignored.

## Ranges

A `version range` is a set of `comparators` which specify versions
that satisfy the range.

A `comparator` is composed of an `operator` and a `version`.  The set
of primitive `operators` is:

* `<` Less than
* `<=` Less than or equal to
* `>` Greater than
* `>=` Greater than or equal to
* `=` Equal.  If no operator is specified, then equality is assumed,
  so this operator is optional, but MAY be included.

For example, the comparator `>=1.2.7` would match the versions
`1.2.7`, `1.2.8`, `2.5.3`, and `1.3.9`, but not the versions `1.2.6`
or `1.1.0`.

Comparators can be joined by whitespace to form a `comparator set`,
which is satisfied by the **intersection** of all of the comparators
it includes.

A range is composed of one or more comparator sets, joined by `||`.  A
version matches a range if and only if every comparator in at least
one of the `||`-separated comparator sets is satisfied by the version.

For example, the range `>=1.2.7 <1.3.0` would match the versions
`1.2.7`, `1.2.8`, and `1.2.99`, but not the versions `1.2.6`, `1.3.0`,
or `1.1.0`.

The range `1.2.7 || >=1.2.9 <2.0.0` would match the versions `1.2.7`,
`1.2.9`, and `1.4.6`, but not the versions `1.2.8` or `2.0.0`.

### Prerelease Tags

If a version has a prerelease tag (for example, `1.2.3-alpha.3`) then
it will only be allowed to satisfy comparator sets if at least one
comparator with the same `[major, minor, patch]` tuple also has a
prerelease tag.

For example, the range `>1.2.3-alpha.3` would be allowed to match the
version `1.2.3-alpha.7`, but it would *not* be satisfied by
`3.4.5-alpha.9`, even though `3.4.5-alpha.9` is technically "greater
than" `1.2.3-alpha.3` according to the SemVer sort rules.  The version
range only accepts prerelease tags on the `1.2.3` version.  The
version `3.4.5` *would* satisfy the range, because it does not have a
prerelease flag, and `3.4.5` is greater than `1.2.3-alpha.7`.

The purpose for this behavior is twofold.  First, prerelease versions
frequently are updated very quickly, and contain many breaking changes
that are (by the author's design) not yet fit for public consumption.
Therefore, by default, they are excluded from range matching
semantics.

Second, a user who has opted into using a prerelease version has
clearly indicated the intent to use *that specific* set of
alpha/beta/rc versions.  By including a prerelease tag in the range,
the user is indicating that they are aware of the risk.  However, it
is still not appropriate to assume that they have opted into taking a
similar risk on the *next* set of prerelease versions.

Note that this behavior can be suppressed (treating all prerelease
versions as if they were normal versions, for the purpose of range
matching) by setting the `includePrerelease` flag on the options
object to any
[functions](https://github.com/npm/node-semver#functions) that do
range matching.

#### Prerelease Identifiers

The method `.inc` takes an additional `identifier` string argument that
will append the value of the string as a prerelease identifier:

```javascript
semver.inc('1.2.3', 'prerelease', 'beta')
// '1.2.4-beta.0'
```

command-line example:

```bash
$ semver 1.2.3 -i prerelease --preid beta
1.2.4-beta.0
```

Which then can be used to increment further:

```bash
$ semver 1.2.4-beta.0 -i prerelease
1.2.4-beta.1
```

### Advanced Range Syntax

Advanced range syntax desugars to primitive comparators in
deterministic ways.

Advanced ranges may be combined in the same way as primitive
comparators using white space or `||`.

#### Hyphen Ranges `X.Y.Z - A.B.C`

Specifies an inclusive set.

* `1.2.3 - 2.3.4` := `>=1.2.3 <=2.3.4`

If a partial version is provided as the first version in the inclusive
range, then the missing pieces are replaced with zeroes.

* `1.2 - 2.3.4` := `>=1.2.0 <=2.3.4`

If a partial version is provided as the second version in the
inclusive range, then all versions that start with the supplied parts
of the tuple are accepted, but nothing that would be greater than the
provided tuple parts.

* `1.2.3 - 2.3` := `>=1.2.3 <2.4.0`
* `1.2.3 - 2` := `>=1.2.3 <3.0.0`

#### X-Ranges `1.2.x` `1.X` `1.2.*` `*`

Any of `X`, `x`, or `*` may be used to "stand in" for one of the
numeric values in the `[major, minor, patch]` tuple.

* `*` := `>=0.0.0` (Any version satisfies)
* `1.x` := `>=1.0.0 <2.0.0` (Matching major version)
* `1.2.x` := `>=1.2.0 <1.3.0` (Matching major and minor versions)

A partial version range is treated as an X-Range, so the special
character is in fact optional.

* `""` (empty string) := `*` := `>=0.0.0`
* `1` := `1.x.x` := `>=1.0.0 <2.0.0`
* `1.2` := `1.2.x` := `>=1.2.0 <1.3.0`

#### Tilde Ranges `~1.2.3` `~1.2` `~1`

Allows patch-level changes if a minor version is specified on the
comparator.  Allows minor-level changes if not.

* `~1.2.3` := `>=1.2.3 <1.(2+1).0` := `>=1.2.3 <1.3.0`
* `~1.2` := `>=1.2.0 <1.(2+1).0` := `>=1.2.0 <1.3.0` (Same as `1.2.x`)
* `~1` := `>=1.0.0 <(1+1).0.0` := `>=1.0.0 <2.0.0` (Same as `1.x`)
* `~0.2.3` := `>=0.2.3 <0.(2+1).0` := `>=0.2.3 <0.3.0`
* `~0.2` := `>=0.2.0 <0.(2+1).0` := `>=0.2.0 <0.3.0` (Same as `0.2.x`)
* `~0` := `>=0.0.0 <(0+1).0.0` := `>=0.0.0 <1.0.0` (Same as `0.x`)
* `~1.2.3-beta.2` := `>=1.2.3-beta.2 <1.3.0` Note that prereleases in
  the `1.2.3` version will be allowed, if they are greater than or
  equal to `beta.2`.  So, `1.2.3-beta.4` would be allowed, but
  `1.2.4-beta.2` would not, because it is a prerelease of a
  different `[major, minor, patch]` tuple.

#### Caret Ranges `^1.2.3` `^0.2.5` `^0.0.4`

Allows changes that do not modify the left-most non-zero element in the
`[major, minor, patch]` tuple.  In other words, this allows patch and
minor updates for versions `1.0.0` and above, patch updates for
versions `0.X >=0.1.0`, and *no* updates for versions `0.0.X`.

Many authors treat a `0.x` version as if the `x` were the major
"breaking-change" indicator.

Caret ranges are ideal when an author may make breaking changes
between `0.2.4` and `0.3.0` releases, which is a common practice.
However, it presumes that there will *not* be breaking changes between
`0.2.4` and `0.2.5`.  It allows for changes that are presumed to be
additive (but non-breaking), according to commonly observed practices.

* `^1.2.3` := `>=1.2.3 <2.0.0`
* `^0.2.3` := `>=0.2.3 <0.3.0`
* `^0.0.3` := `>=0.0.3 <0.0.4`
* `^1.2.3-beta.2` := `>=1.2.3-beta.2 <2.0.0` Note that prereleases in
  the `1.2.3` version will be allowed, if they are greater than or
  equal to `beta.2`.  So, `1.2.3-beta.4` would be allowed, but
  `1.2.4-beta.2` would not, because it is a prerelease of a
  different `[major, minor, patch]` tuple.
* `^0.0.3-beta` := `>=0.0.3-beta <0.0.4`  Note that prereleases in the
  `0.0.3` version *only* will be allowed, if they are greater than or
  equal to `beta`.  So, `0.0.3-pr.2` would be allowed.

When parsing caret ranges, a missing `patch` value desugars to the
number `0`, but will allow flexibility within that value, even if the
major and minor versions are both `0`.

* `^1.2.x` := `>=1.2.0 <2.0.0`
* `^0.0.x` := `>=0.0.0 <0.1.0`
* `^0.0` := `>=0.0.0 <0.1.0`

A missing `minor` and `patch` values will desugar to zero, but also
allow flexibility within those values, even if the major version is
zero.

* `^1.x` := `>=1.0.0 <2.0.0`
* `^0.x` := `>=0.0.0 <1.0.0`

### Range Grammar

Putting all this together, here is a Backus-Naur grammar for ranges,
for the benefit of parser authors:

```bnf
range-set  ::= range ( logical-or range ) *
logical-or ::= ( ' ' ) * '||' ( ' ' ) *
range      ::= hyphen | simple ( ' ' simple ) * | ''
hyphen     ::= partial ' - ' partial
simple     ::= primitive | partial | tilde | caret
primitive  ::= ( '<' | '>' | '>=' | '<=' | '=' ) partial
partial    ::= xr ( '.' xr ( '.' xr qualifier ? )? )?
xr         ::= 'x' | 'X' | '*' | nr
nr         ::= '0' | ['1'-'9'] ( ['0'-'9'] ) *
tilde      ::= '~' partial
caret      ::= '^' partial
qualifier  ::= ( '-' pre )? ( '+' build )?
pre        ::= parts
build      ::= parts
parts      ::= part ( '.' part ) *
part       ::= nr | [-0-9A-Za-z]+
```

## Functions

All methods and classes take a final `options` object argument.  All
options in this object are `false` by default.  The options supported
are:

- `loose`  Be more forgiving about not-quite-valid semver strings.
  (Any resulting output will always be 100% strict compliant, of
  course.)  For backwards compatibility reasons, if the `options`
  argument is a boolean value instead of an object, it is interpreted
  to be the `loose` param.
- `includePrerelease`  Set to suppress the [default
  behavior](https://github.com/npm/node-semver#prerelease-tags) of
  excluding prerelease tagged versions from ranges unless they are
  explicitly opted into.

Strict-mode Comparators and Ranges will be strict about the SemVer
strings that they parse.

* `valid(v)`: Return the parsed version, or null if it's not valid.
* `inc(v, release)`: Return the version incremented by the release
  type (`major`,   `premajor`, `minor`, `preminor`, `patch`,
  `prepatch`, or `prerelease`), or null if it's not valid
  * `premajor` in one call will bump the version up to the next major
    version and down to a prerelease of that major version.
    `preminor`, and `prepatch` work the same way.
  * If called from a non-prerelease version, the `prerelease` will work the
    same as `prepatch`. It increments the patch version, then makes a
    prerelease. If the input version is already a prerelease it simply
    increments it.
* `prerelease(v)`: Returns an array of prerelease components, or null
  if none exist. Example: `prerelease('1.2.3-alpha.1') -> ['alpha', 1]`
* `major(v)`: Return the major version number.
* `minor(v)`: Return the minor version number.
* `patch(v)`: Return the patch version number.
* `intersects(r1, r2, loose)`: Return true if the two supplied ranges
  or comparators intersect.
* `parse(v)`: Attempt to parse a string as a semantic version, returning either
  a `SemVer` object or `null`.

### Comparison

* `gt(v1, v2)`: `v1 > v2`
* `gte(v1, v2)`: `v1 >= v2`
* `lt(v1, v2)`: `v1 < v2`
* `lte(v1, v2)`: `v1 <= v2`
* `eq(v1, v2)`: `v1 == v2` This is true if they're logically equivalent,
  even if they're not the exact same string.  You already know how to
  compare strings.
* `neq(v1, v2)`: `v1 != v2` The opposite of `eq`.
* `cmp(v1, comparator, v2)`: Pass in a comparison string, and it'll call
  the corresponding function above.  `"==="` and `"!=="` do simple
  string comparison, but are included for completeness.  Throws if an
  invalid comparison string is provided.
* `compare(v1, v2)`: Return `0` if `v1 == v2`, or `1` if `v1` is greater, or `-1` if
  `v2` is greater.  Sorts in ascending order if passed to `Array.sort()`.
* `rcompare(v1, v2)`: The reverse of compare.  Sorts an array of versions
  in descending order when passed to `Array.sort()`.
* `compareBuild(v1, v2)`: The same as `compare` but considers `build` when two versions
  are equal.  Sorts in ascending order if passed to `Array.sort()`.
  `v2` is greater.  Sorts in ascending order if passed to `Array.sort()`.
* `diff(v1, v2)`: Returns difference between two versions by the release type
  (`major`, `premajor`, `minor`, `preminor`, `patch`, `prepatch`, or `prerelease`),
  or null if the versions are the same.

### Comparators

* `intersects(comparator)`: Return true if the comparators intersect

### Ranges

* `validRange(range)`: Return the valid range or null if it's not valid
* `satisfies(version, range)`: Return true if the version satisfies the
  range.
* `maxSatisfying(versions, range)`: Return the highest version in the list
  that satisfies the range, or `null` if none of them do.
* `minSatisfying(versions, range)`: Return the lowest version in the list
  that satisfies the range, or `null` if none of them do.
* `minVersion(range)`: Return the lowest version that can possibly match
  the given range.
* `gtr(version, range)`: Return `true` if version is greater than all the
  versions possible in the range.
* `ltr(version, range)`: Return `true` if version is less than all the
  versions possible in the range.
* `outside(version, range, hilo)`: Return true if the version is outside
  the bounds of the range in either the high or low direction.  The
  `hilo` argument must be either the string `'>'` or `'<'`.  (This is
  the function called by `gtr` and `ltr`.)
* `intersects(range)`: Return true if any of the ranges comparators intersect

Note that, since ranges may be non-contiguous, a version might not be
greater than a range, less than a range, *or* satisfy a range!  For
example, the range `1.2 <1.2.9 || >2.0.0` would have a hole from `1.2.9`
until `2.0.0`, so the version `1.2.10` would not be greater than the
range (because `2.0.1` satisfies, which is higher), nor less than the
range (since `1.2.8` satisfies, which is lower), and it also does not
satisfy the range.

If you want to know if a version satisfies or does not satisfy a
range, use the `satisfies(version, range)` function.

### Coercion

* `coerce(version, options)`: Coerces a string to semver if possible

This aims to provide a very forgiving translation of a non-semver string to
semver. It looks for the first digit in a string, and consumes all
remaining characters which satisfy at least a partial semver (e.g., `1`,
`1.2`, `1.2.3`) up to the max permitted length (256 characters).  Longer
versions are simply truncated (`4.6.3.9.2-alpha2` becomes `4.6.3`).  All
surrounding text is simply ignored (`v3.4 replaces v3.3.1` becomes
`3.4.0`).  Only text which lacks digits will fail coercion (`version one`
is not valid).  The maximum  length for any semver component considered for
coercion is 16 characters; longer components will be ignored
(`10000000000000000.4.7.4` becomes `4.7.4`).  The maximum value for any
semver component is `Integer.MAX_SAFE_INTEGER || (2**53 - 1)`; higher value
components are invalid (`9999999999999999.4.7.4` is likely invalid).

If the `options.rtl` flag is set, then `coerce` will return the right-most
coercible tuple that does not share an ending index with a longer coercible
tuple.  For example, `1.2.3.4` will return `2.3.4` in rtl mode, not
`4.0.0`.  `1.2.3/4` will return `4.0.0`, because the `4` is not a part of
any other overlapping SemVer tuple.

### Clean

* `clean(version)`: Clean a string to be a valid semver if possible

This will return a cleaned and trimmed semver version. If the provided version is not valid a null will be returned. This does not work for ranges. 

ex.
* `s.clean(' = v 2.1.5foo')`: `null`
* `s.clean(' = v 2.1.5foo', { loose: true })`: `'2.1.5-foo'`
* `s.clean(' = v 2.1.5-foo')`: `null`
* `s.clean(' = v 2.1.5-foo', { loose: true })`: `'2.1.5-foo'`
* `s.clean('=v2.1.5')`: `'2.1.5'`
* `s.clean('  =v2.1.5')`: `2.1.5`
* `s.clean('      2.1.5   ')`: `'2.1.5'`
* `s.clean('~1.0.0')`: `null`


---

# @babel/helper-define-polyfill-provider

## Install

Using npm:

```sh
npm install --save-dev @babel/helper-define-polyfill-provider
```

or using yarn:

```sh
yarn add @babel/helper-define-polyfill-provider --dev
```


---

# @babel/helper-member-expression-to-functions

> Helper function to replace certain member expressions with function calls

See our website [@babel/helper-member-expression-to-functions](https://babeljs.io/docs/babel-helper-member-expression-to-functions) for more information.

## Install

Using npm:

```sh
npm install --save @babel/helper-member-expression-to-functions
```

or using yarn:

```sh
yarn add @babel/helper-member-expression-to-functions
```


---

# @babel/helper-module-imports

> Babel helper functions for inserting module loads

See our website [@babel/helper-module-imports](https://babeljs.io/docs/babel-helper-module-imports) for more information.

## Install

Using npm:

```sh
npm install --save @babel/helper-module-imports
```

or using yarn:

```sh
yarn add @babel/helper-module-imports
```


---

# @babel/helper-module-transforms

> Babel helper functions for implementing ES6 module transformations

See our website [@babel/helper-module-transforms](https://babeljs.io/docs/babel-helper-module-transforms) for more information.

## Install

Using npm:

```sh
npm install --save @babel/helper-module-transforms
```

or using yarn:

```sh
yarn add @babel/helper-module-transforms
```


---

# @babel/helper-optimise-call-expression

> Helper function to optimise call expression

See our website [@babel/helper-optimise-call-expression](https://babeljs.io/docs/babel-helper-optimise-call-expression) for more information.

## Install

Using npm:

```sh
npm install --save @babel/helper-optimise-call-expression
```

or using yarn:

```sh
yarn add @babel/helper-optimise-call-expression
```


---

# @babel/helper-plugin-utils

> General utilities for plugins to use

See our website [@babel/helper-plugin-utils](https://babeljs.io/docs/babel-helper-plugin-utils) for more information.

## Install

Using npm:

```sh
npm install --save @babel/helper-plugin-utils
```

or using yarn:

```sh
yarn add @babel/helper-plugin-utils
```


---

# @babel/helper-remap-async-to-generator

> Helper function to remap async functions to generators

See our website [@babel/helper-remap-async-to-generator](https://babeljs.io/docs/babel-helper-remap-async-to-generator) for more information.

## Install

Using npm:

```sh
npm install --save @babel/helper-remap-async-to-generator
```

or using yarn:

```sh
yarn add @babel/helper-remap-async-to-generator
```


---

# @babel/helper-replace-supers

> Helper function to replace supers

See our website [@babel/helper-replace-supers](https://babeljs.io/docs/babel-helper-replace-supers) for more information.

## Install

Using npm:

```sh
npm install --save @babel/helper-replace-supers
```

or using yarn:

```sh
yarn add @babel/helper-replace-supers
```


---

# @babel/helper-skip-transparent-expression-wrappers

> Helper which skips types and parentheses

See our website [@babel/helper-skip-transparent-expression-wrappers](https://babeljs.io/docs/babel-helper-skip-transparent-expression-wrappers) for more information.

## Install

Using npm:

```sh
npm install --save @babel/helper-skip-transparent-expression-wrappers
```

or using yarn:

```sh
yarn add @babel/helper-skip-transparent-expression-wrappers
```


---

# @babel/helper-string-parser

> A utility package to parse strings

See our website [@babel/helper-string-parser](https://babeljs.io/docs/babel-helper-string-parser) for more information.

## Install

Using npm:

```sh
npm install --save @babel/helper-string-parser
```

or using yarn:

```sh
yarn add @babel/helper-string-parser
```


---

# @babel/helper-validator-identifier

> Validate identifier/keywords name

See our website [@babel/helper-validator-identifier](https://babeljs.io/docs/babel-helper-validator-identifier) for more information.

## Install

Using npm:

```sh
npm install --save @babel/helper-validator-identifier
```

or using yarn:

```sh
yarn add @babel/helper-validator-identifier
```


---

# @babel/helper-validator-option

> Validate plugin/preset options

See our website [@babel/helper-validator-option](https://babeljs.io/docs/babel-helper-validator-option) for more information.

## Install

Using npm:

```sh
npm install --save @babel/helper-validator-option
```

or using yarn:

```sh
yarn add @babel/helper-validator-option
```


---

# @babel/helper-wrap-function

> Helper to wrap functions inside a function call.

See our website [@babel/helper-wrap-function](https://babeljs.io/docs/babel-helper-wrap-function) for more information.

## Install

Using npm:

```sh
npm install --save @babel/helper-wrap-function
```

or using yarn:

```sh
yarn add @babel/helper-wrap-function
```


---

# @babel/helpers

> Collection of helper functions used by Babel transforms.

See our website [@babel/helpers](https://babeljs.io/docs/babel-helpers) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/helpers
```

or using yarn:

```sh
yarn add @babel/helpers --dev
```


---

# Changelog

> **Tags:**
> - :boom:       [Breaking Change]
> - :eyeglasses: [Spec Compliance]
> - :rocket:     [New Feature]
> - :bug:        [Bug Fix]
> - :memo:       [Documentation]
> - :house:      [Internal]
> - :nail_care:  [Polish]

> Semver Policy: https://github.com/babel/babel/tree/main/packages/babel-parser#semver

_Note: Gaps between patch versions are faulty, broken or test releases._

See the [Babel Changelog](https://github.com/babel/babel/blob/main/CHANGELOG.md) for the pre-6.8.0 version Changelog.

## 6.17.1 (2017-05-10)

### :bug: Bug Fix
 * Fix typo in flow spread operator error (Brian Ng)
 * Fixed invalid number literal parsing ([#473](https://github.com/babel/babylon/pull/473)) (Alex Kuzmenko)
 * Fix number parser ([#433](https://github.com/babel/babylon/pull/433)) (Alex Kuzmenko)
 * Ensure non pattern shorthand props are checked for reserved words ([#479](https://github.com/babel/babylon/pull/479)) (Brian Ng)
 * Remove jsx context when parsing arrow functions ([#475](https://github.com/babel/babylon/pull/475)) (Brian Ng)
 * Allow super in class properties ([#499](https://github.com/babel/babylon/pull/499)) (Brian Ng)
 * Allow flow class field to be named constructor ([#510](https://github.com/babel/babylon/pull/510)) (Brian Ng)

## 6.17.0 (2017-04-20)

### :bug: Bug Fix
 * Cherry-pick #418 to 6.x ([#476](https://github.com/babel/babylon/pull/476)) (Sebastian McKenzie)
 * Add support for invalid escapes in tagged templates ([#274](https://github.com/babel/babylon/pull/274)) (Kevin Gibbons)
 * Throw error if new.target is used outside of a function ([#402](https://github.com/babel/babylon/pull/402)) (Brian Ng)
 * Fix parsing of class properties ([#351](https://github.com/babel/babylon/pull/351)) (Kevin Gibbons)
 * Fix parsing yield with dynamicImport ([#383](https://github.com/babel/babylon/pull/383)) (Brian Ng)
 * Ensure consistent start args for parseParenItem ([#386](https://github.com/babel/babylon/pull/386)) (Brian Ng)

## 7.0.0-beta.8 (2017-04-04)

### New Feature
* Add support for flow type spread (#418) (Conrad Buck)
* Allow statics in flow interfaces (#427) (Brian Ng)

### Bug Fix
* Fix predicate attachment to match flow parser (#428) (Brian Ng)
* Add extra.raw back to JSXText and JSXAttribute (#344) (Alex Rattray)
* Fix rest parameters with array and objects (#424) (Brian Ng)
* Fix number parser (#433) (Alex Kuzmenko)

### Docs
* Fix CONTRIBUTING.md [skip ci] (#432) (Alex Kuzmenko)

### Internal
* Use babel-register script when running babel smoke tests (#442) (Brian Ng)

## 7.0.0-beta.7 (2017-03-22)

### Spec Compliance
* Remove babylon plugin for template revision since it's stage-4 (#426) (Henry Zhu)

### Bug Fix

* Fix push-pop logic in flow (#405) (Daniel Tschinder)

## 7.0.0-beta.6 (2017-03-21)

### New Feature
* Add support for invalid escapes in tagged templates (#274) (Kevin Gibbons)

### Polish
* Improves error message when super is called outside of constructor (#408) (Arshabh Kumar Agarwal)

### Docs

* [7.0] Moved value field in spec from ObjectMember to ObjectProperty as ObjectMethod's don't have it (#415) [skip ci] (James Browning)

## 7.0.0-beta.5 (2017-03-21)

### Bug Fix
* Throw error if new.target is used outside of a function (#402) (Brian Ng)
* Fix parsing of class properties (#351) (Kevin Gibbons)

### Other
 * Test runner: Detect extra property in 'actual' but not in 'expected'. (#407) (Andy)
 * Optimize travis builds (#419) (Daniel Tschinder)
 * Update codecov to 2.0 (#412) (Daniel Tschinder)
 * Fix spec for ClassMethod: It doesn't have a function, it *is* a function. (#406) [skip ci] (Andy)
 * Changed Non-existent RestPattern to RestElement which is what is actually parsed (#409) [skip ci] (James Browning)
 * Upgrade flow to 0.41 (Daniel Tschinder)
 * Fix watch command (#403) (Brian Ng)
 * Update yarn lock (Daniel Tschinder)
 * Fix watch command (#403) (Brian Ng)
 * chore(package): update flow-bin to version 0.41.0 (#395) (greenkeeper[bot])
 * Add estree test for correct order of directives (Daniel Tschinder)
 * Add DoExpression to spec (#364) (Alex Kuzmenko)
 * Mention cloning of repository in CONTRIBUTING.md (#391) [skip ci] (Sumedh Nimkarde)
 * Explain how to run only one test (#389) [skip ci] (Aaron Ang)

 ## 7.0.0-beta.4 (2017-03-01)

* Don't consume async when checking for async func decl (#377) (Brian Ng)
* add `ranges` option [skip ci] (Henry Zhu)
* Don't parse class properties without initializers when classProperties is disabled and Flow is enabled (#300) (Andrew Levine)

## 7.0.0-beta.3 (2017-02-28)

- [7.0] Change RestProperty/SpreadProperty to RestElement/SpreadElement (#384)
- Merge changes from 6.x

## 7.0.0-beta.2 (2017-02-20)

- estree: correctly change literals in all cases (#368) (Daniel Tschinder)

## 7.0.0-beta.1 (2017-02-20)

- Fix negative number literal typeannotations (#366) (Daniel Tschinder)
- Update contributing with more test info [skip ci] (#355) (Brian Ng)

## 7.0.0-beta.0 (2017-02-15)

- Reintroduce Variance node (#333) (Daniel Tschinder)
- Rename NumericLiteralTypeAnnotation to NumberLiteralTypeAnnotation (#332) (Charles Pick)
- [7.0] Remove ForAwaitStatement, add await flag to ForOfStatement (#349) (Brandon Dail)
- chore(package): update ava to version 0.18.0 (#345) (greenkeeper[bot])
- chore(package): update babel-plugin-istanbul to version 4.0.0 (#350) (greenkeeper[bot])
- Change location of ObjectTypeIndexer to match flow (#228) (Daniel Tschinder)
- Rename flow AST Type ExistentialTypeParam to ExistsTypeAnnotation (#322) (Toru Kobayashi)
- Revert "Temporary rollback for erroring on trailing comma with spread (#154)" (#290) (Daniel Tschinder)
- Remove classConstructorCall plugin (#291) (Brian Ng)
- Update yarn.lock (Daniel Tschinder)
- Update cross-env to 3.x (Daniel Tschinder)
- [7.0] Remove node 0.10, 0.12 and 5 from Travis (#284) (Sergey Rubanov)
- Remove `String.fromCodePoint` shim (#279) (Mathias Bynens)

## 6.16.1 (2017-02-23)

### :bug: Regression

- Revert "Fix export default async function to be FunctionDeclaration" ([#375](https://github.com/babel/babylon/pull/375))

Need to modify Babel for this AST node change, so moving to 7.0.

- Revert "Don't parse class properties without initializers when classProperties plugin is disabled, and Flow is enabled" ([#376](https://github.com/babel/babylon/pull/376))

[react-native](https://github.com/facebook/react-native/issues/12542) broke with this so we reverted.

## 6.16.0 (2017-02-23)

### :rocket: New Feature

***ESTree*** compatibility as plugin ([#277](https://github.com/babel/babylon/pull/277)) (Daniel Tschinder)

We finally introduce a new compatibility layer for ESTree. To put babylon into ESTree-compatible mode the new plugin `estree` can be enabled. In this mode the parser will output an AST that is compliant to the specs of [ESTree](https://github.com/estree/estree/)

We highly recommend everyone who uses babylon outside of babel to use this plugin. This will make it much easier for users to switch between different ESTree-compatible parsers. We so far tested several projects with different parsers and exchanged their parser to babylon and in nearly all cases it worked out of the box. Some other estree-compatible parsers include `acorn`, `esprima`, `espree`, `flow-parser`, etc.

To enable `estree` mode simply add the plugin in the config:
```json
{
  "plugins": [ "estree" ]
}
```

If you want to migrate your project from non-ESTree mode to ESTree, have a look at our [Readme](https://github.com/babel/babylon/#output), where all deviations are mentioned.

Add a parseExpression public method ([#213](https://github.com/babel/babylon/pull/213)) (jeromew)

Babylon exports a new function to parse a single expression

```js
import { parseExpression } from 'babylon';

const ast = parseExpression('x || y && z', options);
```

The returned AST will only consist of the expression. The options are the same as for `parse()`

Add startLine option ([#346](https://github.com/babel/babylon/pull/346)) (Raphael Mu)

A new option was added to babylon allowing to change the initial linenumber for the first line which is usually `1`.
Changing this for example to `100` will make line `1` of the input source to be marked as line `100`, line `2` as `101`, line `3` as `102`, ...

Function predicate declaration ([#103](https://github.com/babel/babylon/pull/103)) (Panagiotis Vekris)

Added support for function predicates which flow introduced in version 0.33.0

```js
declare function is_number(x: mixed): boolean %checks(typeof x === "number");
```

Allow imports in declare module ([#315](https://github.com/babel/babylon/pull/315)) (Daniel Tschinder)

Added support for imports within module declarations which flow introduced in version 0.37.0

```js
declare module "C" {
  import type { DT } from "D";
  declare export type CT = { D: DT };
}
```

### :eyeglasses: Spec Compliance

Forbid semicolons after decorators in classes ([#352](https://github.com/babel/babylon/pull/352)) (Kevin Gibbons)

This example now correctly throws an error when there is a semicolon after the decorator:

```js
class A {
@a;
foo(){}
}
```

Keywords are not allowed as local specifier ([#307](https://github.com/babel/babylon/pull/307)) (Daniel Tschinder)

Using keywords in imports is not allowed anymore:

```js
import { default } from "foo";
import { a as debugger } from "foo";
```

Do not allow overwritting of primitive types ([#314](https://github.com/babel/babylon/pull/314)) (Daniel Tschinder)

In flow it is now forbidden to overwrite the primitive types `"any"`, `"mixed"`, `"empty"`, `"bool"`, `"boolean"`, `"number"`, `"string"`, `"void"` and `"null"` with your own type declaration.

Disallow import type { type a } from … ([#305](https://github.com/babel/babylon/pull/305)) (Daniel Tschinder)

The following code now correctly throws an error

```js
import type { type a } from "foo";
```

Don't parse class properties without initializers when classProperties is disabled and Flow is enabled ([#300](https://github.com/babel/babylon/pull/300)) (Andrew Levine)

Ensure that you enable the `classProperties` plugin in order to enable correct parsing of class properties. Prior to this version it was possible to parse them by enabling the `flow` plugin but this was not intended the behaviour.

If you enable the flow plugin you can only define the type of the class properties, but not initialize them.

Fix export default async function to be FunctionDeclaration ([#324](https://github.com/babel/babylon/pull/324)) (Daniel Tschinder)

Parsing the following code now returns a `FunctionDeclaration` AST node instead of `FunctionExpression`.

```js
export default async function bar() {};
```

### :nail_care: Polish

Improve error message on attempt to destructure named import ([#288](https://github.com/babel/babylon/pull/288)) (Brian Ng)

### :bug: Bug Fix

Fix negative number literal typeannotations ([#366](https://github.com/babel/babylon/pull/366)) (Daniel Tschinder)

Ensure takeDecorators is called on exported class ([#358](https://github.com/babel/babylon/pull/358)) (Brian Ng)

ESTree: correctly change literals in all cases ([#368](https://github.com/babel/babylon/pull/368)) (Daniel Tschinder)

Correctly convert RestProperty to Assignable ([#339](https://github.com/babel/babylon/pull/339)) (Daniel Tschinder)

Fix #321 by allowing question marks in type params ([#338](https://github.com/babel/babylon/pull/338)) (Daniel Tschinder)

Fix #336 by correctly setting arrow-param ([#337](https://github.com/babel/babylon/pull/337)) (Daniel Tschinder)

Fix parse error when destructuring `set` with default value ([#317](https://github.com/babel/babylon/pull/317)) (Brian Ng)

Fix ObjectTypeCallProperty static ([#298](https://github.com/babel/babylon/pull/298)) (Dan Harper)


### :house: Internal

Fix generator-method-with-computed-name spec ([#360](https://github.com/babel/babylon/pull/360)) (Alex Rattray)

Fix flow type-parameter-declaration test with unintended semantic ([#361](https://github.com/babel/babylon/pull/361)) (Alex Rattray)

Cleanup and splitup parser functions ([#295](https://github.com/babel/babylon/pull/295)) (Daniel Tschinder)

chore(package): update flow-bin to version 0.38.0 ([#313](https://github.com/babel/babylon/pull/313)) (greenkeeper[bot])

Call inner function instead of 1:1 copy to plugin ([#294](https://github.com/babel/babylon/pull/294)) (Daniel Tschinder)

Update eslint-config-babel to the latest version 🚀 ([#299](https://github.com/babel/babylon/pull/299)) (greenkeeper[bot])

Update eslint-config-babel to the latest version 🚀 ([#293](https://github.com/babel/babylon/pull/293)) (greenkeeper[bot])

devDeps: remove eslint-plugin-babel ([#292](https://github.com/babel/babylon/pull/292)) (Kai Cataldo)

Correct indent eslint rule config ([#276](https://github.com/babel/babylon/pull/276)) (Daniel Tschinder)

Fail tests that have expected.json and throws-option ([#285](https://github.com/babel/babylon/pull/285)) (Daniel Tschinder)

### :memo: Documentation

Update contributing with more test info [skip ci] ([#355](https://github.com/babel/babylon/pull/355)) (Brian Ng)

Update API documentation ([#330](https://github.com/babel/babylon/pull/330)) (Timothy Gu)

Added keywords to package.json ([#323](https://github.com/babel/babylon/pull/323)) (Dmytro)

AST spec: fix casing of `RegExpLiteral` ([#318](https://github.com/babel/babylon/pull/318)) (Mathias Bynens)

## 6.15.0 (2017-01-10)

### :eyeglasses: Spec Compliance

Add support for Flow shorthand import type ([#267](https://github.com/babel/babylon/pull/267)) (Jeff Morrison)

This change implements flows new shorthand import syntax
and where previously you had to write this code:

```js
import {someValue} from "blah";
import type {someType} from "blah";
import typeof {someOtherValue} from "blah";
```

you can now write it like this:

```js
import {
  someValue,
  type someType,
  typeof someOtherValue,
} from "blah";
```

For more information look at [this](https://github.com/facebook/flow/pull/2890) pull request.

flow: allow leading pipes in all positions ([#256](https://github.com/babel/babylon/pull/256)) (Vladimir Kurchatkin)

This change now allows a leading pipe everywhere types can be used:
```js
var f = (x): | 1 | 2 => 1;
```

Throw error when exporting non-declaration ([#241](https://github.com/babel/babylon/pull/241)) (Kai Cataldo)

Previously babylon parsed the following exports, although they are not valid:
```js
export typeof foo;
export new Foo();
export function() {};
export for (;;);
export while(foo);
```

### :bug: Bug Fix

Don't set inType flag when parsing property names ([#266](https://github.com/babel/babylon/pull/266)) (Vladimir Kurchatkin)

This fixes parsing of this case:

```js
const map = {
  [age <= 17] : 'Too young'
};
```

Fix source location for JSXEmptyExpression nodes (fixes #248) ([#249](https://github.com/babel/babylon/pull/249)) (James Long)

The following case produced an invalid AST
```js
<div>{/* foo */}</div>
```

Use fromCodePoint to convert high value unicode entities ([#243](https://github.com/babel/babylon/pull/243)) (Ryan Duffy)

When high value unicode entities (e.g. 💩) were used in the input source code they are now correctly encoded in the resulting AST.

Rename folder to avoid Windows-illegal characters ([#281](https://github.com/babel/babylon/pull/281)) (Ryan Plant)

Allow this.state.clone() when parsing decorators ([#262](https://github.com/babel/babylon/pull/262)) (Alex Rattray)

### :house: Internal

User external-helpers ([#254](https://github.com/babel/babylon/pull/254)) (Daniel Tschinder)

Add watch script for dev ([#234](https://github.com/babel/babylon/pull/234)) (Kai Cataldo)

Freeze current plugins list for "*" option, and remove from README.md ([#245](https://github.com/babel/babylon/pull/245)) (Andrew Levine)

Prepare tests for multiple fixture runners. ([#240](https://github.com/babel/babylon/pull/240)) (Daniel Tschinder)

Add some test coverage for decorators stage-0 plugin ([#250](https://github.com/babel/babylon/pull/250)) (Andrew Levine)

Refactor tokenizer types file ([#263](https://github.com/babel/babylon/pull/263)) (Sven SAULEAU)

Update eslint-config-babel to the latest version 🚀 ([#273](https://github.com/babel/babylon/pull/273)) (greenkeeper[bot])

chore(package): update rollup to version 0.41.0 ([#272](https://github.com/babel/babylon/pull/272)) (greenkeeper[bot])

chore(package): update flow-bin to version 0.37.0 ([#255](https://github.com/babel/babylon/pull/255)) (greenkeeper[bot])

## 6.14.1 (2016-11-17)

### :bug: Bug Fix

Allow `"plugins": ["*"]` ([#229](https://github.com/babel/babylon/pull/229)) (Daniel Tschinder)

```js
{
  "plugins": ["*"]
}
```

Will include all parser plugins instead of specifying each one individually. Useful for tools like babel-eslint, jscodeshift, and ast-explorer.

## 6.14.0 (2016-11-16)

### :eyeglasses: Spec Compliance

Throw error for reserved words `enum` and `await` ([#195](https://github.com/babel/babylon/pull/195)) (Kai Cataldo)

[11.6.2.2 Future Reserved Words](http://www.ecma-international.org/ecma-262/6.0/#sec-future-reserved-words)

Babylon will throw for more reserved words such as `enum` or `await` (in strict mode).

```
class enum {} // throws
class await {} // throws in strict mode (module)
```

Optional names for function types and object type indexers ([#197](https://github.com/babel/babylon/pull/197)) (Gabe Levi)

So where you used to have to write

```js
type A = (x: string, y: boolean) => number;
type B = (z: string) => number;
type C = { [key: string]: number };
```

you can now write (with flow 0.34.0)

```js
type A = (string, boolean) => number;
type B = string => number;
type C = { [string]: number };
```

Parse flow nested array type annotations like `number[][]` ([#219](https://github.com/babel/babylon/pull/219)) (Bernhard Häussner)

Supports these form now of specifying array types:

```js
var a: number[][][][];
var b: string[][];
```

### :bug: Bug Fix

Correctly eat semicolon at the end of `DelcareModuleExports` ([#223](https://github.com/babel/babylon/pull/223))  (Daniel Tschinder)

```
declare module "foo" { declare module.exports: number }
declare module "foo" { declare module.exports: number; }  // also allowed now
```

### :house: Internal

 * Count Babel tests towards Babylon code coverage ([#182](https://github.com/babel/babylon/pull/182)) (Moti Zilberman)
 * Fix strange line endings ([#214](https://github.com/babel/babylon/pull/214)) (Thomas Grainger)
 * Add node 7 (Daniel Tschinder)
 * chore(package): update flow-bin to version 0.34.0 ([#204](https://github.com/babel/babylon/pull/204)) (Greenkeeper)

## v6.13.1 (2016-10-26)

### :nail_care: Polish

- Use rollup for bundling to speed up startup time ([#190](https://github.com/babel/babylon/pull/190)) ([@drewml](https://github.com/DrewML))

```js
const babylon = require('babylon');
const ast = babylon.parse('var foo = "lol";');
```

With that test case, there was a ~95ms savings by removing the need for node to build/traverse the dependency graph.

**Without bundling**
![image](https://cloud.githubusercontent.com/assets/5233399/19420264/3133497e-93ad-11e6-9a6a-2da59c4f5c13.png)

**With bundling**
![image](https://cloud.githubusercontent.com/assets/5233399/19420267/388f556e-93ad-11e6-813e-7c5c396be322.png)

- add clean command [skip ci] ([#201](https://github.com/babel/babylon/pull/201)) (Henry Zhu)
- add ForAwaitStatement (async generator already added) [skip ci] ([#196](https://github.com/babel/babylon/pull/196)) (Henry Zhu)

## v6.13.0 (2016-10-21)

### :eyeglasses: Spec Compliance

Property variance type annotations for Flow plugin ([#161](https://github.com/babel/babylon/pull/161)) (Sam Goldman)

> See https://flowtype.org/docs/variance.html for more information

```js
type T = { +p: T };
interface T { -p: T };
declare class T { +[k:K]: V };
class T { -[k:K]: V };
class C2 { +p: T = e };
```

Raise error on duplicate definition of __proto__ ([#183](https://github.com/babel/babylon/pull/183)) (Moti Zilberman)

```js
({ __proto__: 1, __proto__: 2 }) // Throws an error now
```

### :bug: Bug Fix

Flow: Allow class properties to be named `static` ([#184](https://github.com/babel/babylon/pull/184)) (Moti Zilberman)

```js
declare class A {
  static: T;
}
```

Allow "async" as identifier for object literal property shorthand ([#187](https://github.com/babel/babylon/pull/187)) (Andrew Levine)

```js
var foo = { async, bar };
```

### :nail_care: Polish

Fix flowtype and add inType to state ([#189](https://github.com/babel/babylon/pull/189)) (Daniel Tschinder)

> This improves the performance slightly (because of hidden classes)

### :house: Internal

Fix .gitattributes line ending setting ([#191](https://github.com/babel/babylon/pull/191)) (Moti Zilberman)

Increase test coverage ([#175](https://github.com/babel/babylon/pull/175) (Moti Zilberman)

Readd missin .eslinignore for IDEs (Daniel Tschinder)

Error on missing expected.json fixture in CI ([#188](https://github.com/babel/babylon/pull/188)) (Moti Zilberman)

Add .gitattributes and .editorconfig for LF line endings ([#179](https://github.com/babel/babylon/pull/179)) (Moti Zilberman)

Fixes two tests that are failing after the merge of #172 ([#177](https://github.com/babel/babylon/pull/177)) (Moti Zilberman)

## v6.12.0 (2016-10-14)

### :eyeglasses: Spec Compliance

Implement import() syntax ([#163](https://github.com/babel/babylon/pull/163)) (Jordan Gensler)

#### Dynamic Import

- Proposal Repo: https://github.com/domenic/proposal-dynamic-import
- Championed by [@domenic](https://github.com/domenic)
- stage-2
- [sept-28 tc39 notes](https://github.com/rwaldron/tc39-notes/blob/master/es7/2016-09/sept-28.md#113a-import)

> This repository contains a proposal for adding a "function-like" import() module loading syntactic form to JavaScript

```js
import(`./section-modules/${link.dataset.entryModule}.js`)
.then(module => {
  module.loadPageInto(main);
})
```

Add EmptyTypeAnnotation ([#171](https://github.com/babel/babylon/pull/171)) (Sam Goldman)

#### EmptyTypeAnnotation

Just wasn't covered before.

```js
type T = empty;
```

### :bug: Bug Fix

Fix crash when exporting with destructuring and sparse array ([#170](https://github.com/babel/babylon/pull/170)) (Jeroen Engels)

```js
// was failing due to sparse array
export const { foo: [ ,, qux7 ] } = bar;
```

Allow keyword in Flow object declaration property names with type parameters ([#146](https://github.com/babel/babylon/pull/146)) (Dan Harper)

```js
declare class X {
  foobar<T>(): void;
  static foobar<T>(): void;
}
```

Allow keyword in object/class property names with Flow type parameters ([#145](https://github.com/babel/babylon/pull/145)) (Dan Harper)

```js
class Foo {
  delete<T>(item: T): T {
    return item;
  }
}
```

Allow typeAnnotations for yield expressions ([#174](https://github.com/babel/babylon/pull/174))) (Daniel Tschinder)

```js
function *foo() {
  const x = (yield 5: any);
}
```

### :nail_care: Polish

Annotate more errors with expected token ([#172](https://github.com/babel/babylon/pull/172))) (Moti Zilberman)

```js
// Unexpected token, expected ; (1:6)
{ set 1 }
```

### :house: Internal

Remove kcheck ([#173](https://github.com/babel/babylon/pull/173)))  (Daniel Tschinder)

Also run flow, linting, babel tests on separate instances (add back node 0.10)

## v6.11.6 (2016-10-12)

### :bug: Bug Fix/Regression

Fix crash when exporting with destructuring and sparse array ([#170](https://github.com/babel/babylon/pull/170)) (Jeroen Engels)

```js
// was failing with `Cannot read property 'type' of null` because of null identifiers
export const { foo: [ ,, qux7 ] } = bar;
```

## v6.11.5 (2016-10-12)

### :eyeglasses: Spec Compliance

Fix: Check for duplicate named exports in exported destructuring assignments ([#144](https://github.com/babel/babylon/pull/144)) (Kai Cataldo)

```js
// `foo` has already been exported. Exported identifiers must be unique. (2:20)
export function foo() {};
export const { a: [{foo}] } = bar;
```

Fix: Check for duplicate named exports in exported rest elements/properties ([#164](https://github.com/babel/babylon/pull/164)) (Kai Cataldo)

```js
// `foo` has already been exported. Exported identifiers must be unique. (2:22)
export const foo = 1;
export const [bar, ...foo] = baz;
```

### :bug: Bug Fix

Fix: Allow identifier `async` for default param in arrow expression ([#165](https://github.com/babel/babylon/pull/165)) (Kai Cataldo)

```js
// this is ok now
const test = ({async = true}) => {};
```

### :nail_care: Polish

Babylon will now print out the token it's expecting if there's a `SyntaxError` ([#150](https://github.com/babel/babylon/pull/150)) (Daniel Tschinder)

```bash
# So in the case of a missing ending curly (`}`)
Module build failed: SyntaxError: Unexpected token, expected } (30:0)
  28 |   }
  29 |
> 30 |
     | ^
```

## v6.11.4 (2016-10-03)

Temporary rollback for erroring on trailing comma with spread (#154) (Henry Zhu)

## v6.11.3 (2016-10-01)

### :eyeglasses: Spec Compliance

Add static errors for object rest (#149) ([@danez](https://github.com/danez))

> https://github.com/sebmarkbage/ecmascript-rest-spread

Object rest copies the *rest* of properties from the right hand side `obj` starting from the left to right.

```js
let { x, y, ...z } =  { x: 1, y: 2, z: 3 };
// x = 1
// y = 2
// z = { z: 3 }
```

#### New Syntax Errors:

**SyntaxError**: The rest element has to be the last element when destructuring (1:10)
```bash
> 1 | let { ...x, y, z } = { x: 1, y: 2, z: 3};
    |           ^
# Previous behavior:
# x = { x: 1, y: 2, z: 3 }
# y = 2
# z = 3
```

Before, this was just a more verbose way of shallow copying `obj` since it doesn't actually do what you think.

**SyntaxError**: Cannot have multiple rest elements when destructuring (1:13)

```bash
> 1 | let { x, ...y, ...z } = { x: 1, y: 2, z: 3};
    |              ^
# Previous behavior:
# x = 1
# y = { y: 2, z: 3 }
# z = { y: 2, z: 3 }
```

Before y and z would just be the same value anyway so there is no reason to need to have both.

**SyntaxError**: A trailing comma is not permitted after the rest element (1:16)

```js
let { x, y, ...z, } = obj;
```

The rationale for this is that the use case for trailing comma is that you can add something at the end without affecting the line above. Since a RestProperty always has to be the last property it doesn't make sense.

---

get / set are valid property names in default assignment (#142) ([@jezell](https://github.com/jezell))

```js
// valid
function something({ set = null, get = null }) {}
```

## v6.11.2 (2016-09-23)

### Bug Fix

- [#139](https://github.com/babel/babylon/issues/139) Don't do the duplicate check if not an identifier (#140) @hzoo

```js
// regression with duplicate export check
SyntaxError: ./typography.js: `undefined` has already been exported. Exported identifiers must be unique. (22:13)
  20 |
  21 | export const { rhythm } = typography;
> 22 | export const { TypographyStyle } = typography
```

Bail out for now, and make a change to account for destructuring in the next release.

## 6.11.1 (2016-09-22)

### Bug Fix
- [#137](https://github.com/babel/babylon/pull/137) - Fix a regression with duplicate exports - it was erroring on all keys in `Object.prototype`. @danez

```javascript
export toString from './toString';
```

```bash
`toString` has already been exported. Exported identifiers must be unique. (1:7)
> 1 | export toString from './toString';
    |        ^
  2 |
```

## 6.11.0 (2016-09-22)

### Spec Compliance (will break CI)

- Disallow duplicate named exports ([#107](https://github.com/babel/babylon/pull/107)) @kaicataldo

```js
// Only one default export allowed per module. (2:9)
export default function() {};
export { foo as default };

// Only one default export allowed per module. (2:0)
export default {};
export default function() {};

// `Foo` has already been exported. Exported identifiers must be unique. (2:0)
export { Foo };
export class Foo {};
```

### New Feature (Syntax)

- Add support for computed class property names ([#121](https://github.com/babel/babylon/pull/121)) @motiz88

```js
// AST
interface ClassProperty <: Node {
  type: "ClassProperty";
  key: Identifier;
  value: Expression;
  computed: boolean; // added
}
```

```js
// with "plugins": ["classProperties"]
class Foo {
  [x]
  ['y']
}

class Bar {
  [p]
  [m] () {}
}
 ```

### Bug Fix

- Fix `static` property falling through in the declare class Flow AST ([#135](https://github.com/babel/babylon/pull/135)) @danharper

```js
declare class X {
    a: number;
    static b: number; // static
    c: number; // this was being marked as static in the AST as well
}
```

### Polish

- Rephrase "assigning/binding to rvalue" errors to include context ([#119](https://github.com/babel/babylon/pull/119)) @motiz88

```js
// Used to error with:
// SyntaxError: Assigning to rvalue (1:0)

// Now:
// Invalid left-hand side in assignment expression (1:0)
3 = 4

// Invalid left-hand side in for-in statement (1:5)
for (+i in {});
```

### Internal

- Fix call to `this.parseMaybeAssign` with correct arguments ([#133](https://github.com/babel/babylon/pull/133)) @danez
- Add semver note to changelog ([#131](https://github.com/babel/babylon/pull/131)) @hzoo

## 6.10.0 (2016-09-19)

> We plan to include some spec compliance bugs in patch versions. An example was the multiple default exports issue.

### Spec Compliance

* Implement ES2016 check for simple parameter list in strict mode ([#106](https://github.com/babel/babylon/pull/106)) (Timothy Gu)

> It is a Syntax Error if ContainsUseStrict of FunctionBody is true and IsSimpleParameterList of FormalParameters is false. https://tc39.github.io/ecma262/2016/#sec-function-definitions-static-semantics-early-errors

More Context: [tc39-notes](https://github.com/rwaldron/tc39-notes/blob/master/es7/2015-07/july-29.md#611-the-scope-of-use-strict-with-respect-to-destructuring-in-parameter-lists)

For example:

```js
// this errors because it uses destructuring and default parameters
// in a function with a "use strict" directive
function a([ option1, option2 ] = []) {
  "use strict";
}
 ```

The solution would be to use a top level "use strict" or to remove the destructuring or default parameters when using a function + "use strict" or to.

### New Feature

* Exact object type annotations for Flow plugin ([#104](https://github.com/babel/babylon/pull/104)) (Basil Hosmer)

Added to flow in https://github.com/facebook/flow/commit/c710c40aa2a115435098d6c0dfeaadb023cd39b8

Looks like:

```js
var a : {| x: number, y: string |} = { x: 0, y: 'foo' };
```

### Bug Fixes

* Include `typeParameter` location in `ArrowFunctionExpression` ([#126](https://github.com/babel/babylon/pull/126)) (Daniel Tschinder)
* Error on invalid flow type annotation with default assignment ([#122](https://github.com/babel/babylon/pull/122)) (Dan Harper)
* Fix Flow return types on arrow functions ([#124](https://github.com/babel/babylon/pull/124)) (Dan Harper)

### Misc

* Add tests for export extensions ([#127](https://github.com/babel/babylon/pull/127)) (Daniel Tschinder)
* Fix Contributing guidelines [skip ci] (Daniel Tschinder)

## 6.9.2 (2016-09-09)

The only change is to remove the `babel-runtime` dependency by compiling with Babel's ES2015 loose mode. So using babylon standalone should be smaller.

## 6.9.1 (2016-08-23)

This release contains mainly small bugfixes but also updates babylons default mode to es2017. The features for `exponentiationOperator`, `asyncFunctions` and `trailingFunctionCommas` which previously needed to be activated via plugin are now enabled by default and the plugins are now no-ops.

### Bug Fixes

- Fix issues with default object params in async functions ([#96](https://github.com/babel/babylon/pull/96)) @danez
- Fix issues with flow-types and async function ([#95](https://github.com/babel/babylon/pull/95)) @danez
- Fix arrow functions with destructuring, types & default value ([#94](https://github.com/babel/babylon/pull/94)) @danharper
- Fix declare class with qualified type identifier ([#97](https://github.com/babel/babylon/pull/97)) @danez
- Remove exponentiationOperator, asyncFunctions, trailingFunctionCommas plugins and enable them by default ([#98](https://github.com/babel/babylon/pull/98)) @danez

## 6.9.0 (2016-08-16)

### New syntax support

- Add JSX spread children ([#42](https://github.com/babel/babylon/pull/42)) @calebmer

(Be aware that React is not going to support this syntax)

```js
<div>
  {...todos.map(todo => <Todo key={todo.id} todo={todo}/>)}
</div>
```

- Add support for declare module.exports ([#72](https://github.com/babel/babylon/pull/72)) @danez

```js
declare module "foo" {
  declare module.exports: {}
}
```

### New Features

- If supplied, attach filename property to comment node loc. ([#80](https://github.com/babel/babylon/pull/80)) @divmain
- Add identifier name to node loc field ([#90](https://github.com/babel/babylon/pull/90)) @kittens

### Bug Fixes

- Fix exponential operator to behave according to spec ([#75](https://github.com/babel/babylon/pull/75)) @danez
- Fix lookahead to not add comments to arrays which are not cloned ([#76](https://github.com/babel/babylon/pull/76)) @danez
- Fix accidental fall-through in Flow type parsing. ([#82](https://github.com/babel/babylon/pull/82)) @xiemaisi
- Only allow declares inside declare module ([#73](https://github.com/babel/babylon/pull/73)) @danez
- Small fix for parsing type parameter declarations ([#83](https://github.com/babel/babylon/pull/83)) @gabelevi
- Fix arrow param locations with flow types ([#57](https://github.com/babel/babylon/pull/57)) @danez
- Fixes SyntaxError position with flow optional type ([#65](https://github.com/babel/babylon/pull/65)) @danez

### Internal

- Add codecoverage to tests @danez
- Fix tests to not save expected output if we expect the test to fail @danez
- Make a shallow clone of babel for testing @danez
- chore(package): update cross-env to version 2.0.0 ([#77](https://github.com/babel/babylon/pull/77)) @greenkeeperio-bot
- chore(package): update ava to version 0.16.0 ([#86](https://github.com/babel/babylon/pull/86)) @greenkeeperio-bot
- chore(package): update babel-plugin-istanbul to version 2.0.0 ([#89](https://github.com/babel/babylon/pull/89)) @greenkeeperio-bot
- chore(package): update nyc to version 8.0.0 ([#88](https://github.com/babel/babylon/pull/88)) @greenkeeperio-bot

## 6.8.4 (2016-07-06)

### Bug Fixes

- Fix the location of params, when flow and default value used ([#68](https://github.com/babel/babylon/pull/68)) @danez

## 6.8.3 (2016-07-02)

### Bug Fixes

- Fix performance regression introduced in 6.8.2 with conditionals ([#63](https://github.com/babel/babylon/pull/63)) @danez

## 6.8.2 (2016-06-24)

### Bug Fixes

- Fix parse error with yielding jsx elements in generators `function* it() { yield <a></a>; }` ([#31](https://github.com/babel/babylon/pull/31)) @eldereal
- When cloning nodes do not clone its comments ([#24](https://github.com/babel/babylon/pull/24)) @danez
- Fix parse errors when using arrow functions with an spread element and return type `(...props): void => {}` ([#10](https://github.com/babel/babylon/pull/10)) @danez
- Fix leading comments added from previous node ([#23](https://github.com/babel/babylon/pull/23)) @danez
- Fix parse errors with flow's optional arguments `(arg?) => {}` ([#19](https://github.com/babel/babylon/pull/19)) @danez
- Support negative numeric type literals @kittens
- Remove line terminator restriction after await keyword @kittens
- Remove grouped type arrow restriction as it seems flow no longer has it @kittens
- Fix parse error with generic methods that have the name `get` or `set` `class foo { get() {} }` ([#55](https://github.com/babel/babylon/pull/55)) @vkurchatkin
- Fix parse error with arrow functions that have flow type parameter declarations `<T>(x: T): T => x;` ([#54](https://github.com/babel/babylon/pull/54)) @gabelevi

### Documentation

- Document AST differences from ESTree ([#41](https://github.com/babel/babylon/pull/41)) @nene
- Move ast spec from babel/babel ([#46](https://github.com/babel/babylon/pull/46)) @hzoo

### Internal

- Enable skipped tests ([#16](https://github.com/babel/babylon/pull/16)) @danez
- Add script to test latest version of babylon with babel ([#21](https://github.com/babel/babylon/pull/21)) @danez
- Upgrade test runner ava @kittens
- Add missing generate-identifier-regex script @kittens
- Rename parser context types @kittens
- Add node v6 to travis testing @hzoo
- Update to Unicode v9 ([#45](https://github.com/babel/babylon/pull/45)) @mathiasbynens

## 6.8.1 (2016-06-06)

### New Feature

- Parse type parameter declarations with defaults like `type Foo<T = string> = T`

### Bug Fixes
- Type parameter declarations need 1 or more type parameters.
- The existential type `*` is not a valid type parameter.
- The existential type `*` is a primary type

### Spec Compliance
- The param list for type parameter declarations now consists of `TypeParameter` nodes
- New `TypeParameter` AST Node (replaces using the `Identifier` node before)

```
interface TypeParameter <: Node {
  bound: TypeAnnotation;
  default: TypeAnnotation;
  name: string;
  variance: "plus" | "minus";
}
```

## 6.8.0 (2016-05-02)

#### New Feature

##### Parse Method Parameter Decorators ([#12](https://github.com/babel/babylon/pull/12))

> [Method Parameter Decorators](https://goo.gl/8MmCMG) is now a TC39 [stage 0 proposal](https://github.com/tc39/ecma262/blob/master/stage0.md).

Examples:

```js
class Foo {
  constructor(@foo() x, @bar({ a: 123 }) @baz() y) {}
}

export default function func(@foo() x, @bar({ a: 123 }) @baz() y) {}

var obj = {
  method(@foo() x, @bar({ a: 123 }) @baz() y) {}
};
```

##### Parse for-await statements (w/ `asyncGenerators` plugin) ([#17](https://github.com/babel/babylon/pull/17))

There is also a new node type, `ForAwaitStatement`.

> [Async generators and for-await](https://github.com/tc39/proposal-async-iteration) are now a [stage 2 proposal](https://github.com/tc39/ecma262#current-proposals).

Example:

```js
async function f() {
  for await (let x of y);
}
```


---

# @babel/parser

> A JavaScript parser

See our website [@babel/parser](https://babeljs.io/docs/babel-parser) for more information or the [issues](https://github.com/babel/babel/issues?utf8=%E2%9C%93&q=is%3Aissue+label%3A%22pkg%3A%20parser%22+is%3Aopen) associated with this package.

## Install

Using npm:

```sh
npm install --save-dev @babel/parser
```

or using yarn:

```sh
yarn add @babel/parser --dev
```


---

# @babel/plugin-bugfix-firefox-class-in-computed-class-key

> Wraps classes defined in computed keys of other classes affected by https://bugzilla.mozilla.org/show_bug.cgi?id=1887677

See our website [@babel/plugin-bugfix-firefox-class-in-computed-class-key](https://babeljs.io/docs/babel-plugin-bugfix-firefox-class-in-computed-class-key) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-bugfix-firefox-class-in-computed-class-key
```

or using yarn:

```sh
yarn add @babel/plugin-bugfix-firefox-class-in-computed-class-key --dev
```


---

# @babel/plugin-bugfix-safari-class-field-initializer-scope

> Wrap class field initializers with IIFE to workaround https://webkit.org/b/236843

See our website [@babel/plugin-bugfix-safari-class-field-initializer-scope](https://babeljs.io/docs/babel-plugin-bugfix-safari-class-field-initializer-scope) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-bugfix-safari-class-field-initializer-scope
```

or using yarn:

```sh
yarn add @babel/plugin-bugfix-safari-class-field-initializer-scope --dev
```


---

# @babel/plugin-bugfix-safari-id-destructuring-collision-in-function-expression

> Rename destructuring parameter to workaround https://bugs.webkit.org/show_bug.cgi?id=220517

See our website [@babel/plugin-bugfix-safari-id-destructuring-collision-in-function-expression](https://babeljs.io/docs/babel-plugin-bugfix-safari-id-destructuring-collision-in-function-expression) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-bugfix-safari-id-destructuring-collision-in-function-expression
```

or using yarn:

```sh
yarn add @babel/plugin-bugfix-safari-id-destructuring-collision-in-function-expression --dev
```


---

# @babel/plugin-bugfix-v8-spread-parameters-in-optional-chaining

> Transform optional chaining operators to workaround https://crbug.com/v8/11558

See our website [@babel/plugin-bugfix-v8-spread-parameters-in-optional-chaining](https://babeljs.io/docs/babel-plugin-bugfix-v8-spread-parameters-in-optional-chaining) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-bugfix-v8-spread-parameters-in-optional-chaining
```

or using yarn:

```sh
yarn add @babel/plugin-bugfix-v8-spread-parameters-in-optional-chaining --dev
```


---

# @babel/plugin-bugfix-v8-static-class-fields-redefine-readonly

> Transform static class fields assignments that are affected by https://crbug.com/v8/12421

See our website [@babel/plugin-bugfix-v8-static-class-fields-redefine-readonly](https://babeljs.io/docs/babel-plugin-bugfix-v8-static-class-fields-redefine-readonly) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-bugfix-v8-static-class-fields-redefine-readonly
```

or using yarn:

```sh
yarn add @babel/plugin-bugfix-v8-static-class-fields-redefine-readonly --dev
```


---

# @babel/plugin-proposal-private-property-in-object

> ⚠️ This version of the package (`v7.21.0-placeholder-for-preset-env.1`) is not meant to
> be imported. Use any other version of this plugin or, even better, the
> [@babel/plugin-transform-private-property-in-object](https://babeljs.io/docs/en/babel-plugin-transform-private-property-in-object) package.

> This plugin transforms checks for a private property in an object

See our website [@babel/plugin-proposal-private-property-in-object](https://babeljs.io/docs/en/babel-plugin-proposal-private-property-in-object) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-proposal-private-property-in-object
```

or using yarn:

```sh
yarn add @babel/plugin-proposal-private-property-in-object --dev
```


---

# @babel/plugin-syntax-dynamic-import

> Allow parsing of import()

See our website [@babel/plugin-syntax-dynamic-import](https://babeljs.io/docs/en/next/babel-plugin-syntax-dynamic-import.html) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-syntax-dynamic-import
```

or using yarn:

```sh
yarn add @babel/plugin-syntax-dynamic-import --dev
```


---

# @babel/plugin-syntax-import-assertions

> Allow parsing of the module assertion attributes in the import statement

See our website [@babel/plugin-syntax-import-assertions](https://babeljs.io/docs/babel-plugin-syntax-import-assertions) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-syntax-import-assertions
```

or using yarn:

```sh
yarn add @babel/plugin-syntax-import-assertions --dev
```


---

# @babel/plugin-syntax-import-attributes

> Allow parsing of the module attributes in the import statement

See our website [@babel/plugin-syntax-import-attributes](https://babeljs.io/docs/babel-plugin-syntax-import-attributes) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-syntax-import-attributes
```

or using yarn:

```sh
yarn add @babel/plugin-syntax-import-attributes --dev
```


---

# @babel/plugin-syntax-jsx

> Allow parsing of jsx

See our website [@babel/plugin-syntax-jsx](https://babeljs.io/docs/babel-plugin-syntax-jsx) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-syntax-jsx
```

or using yarn:

```sh
yarn add @babel/plugin-syntax-jsx --dev
```


---

# @babel/plugin-syntax-typescript

> Allow parsing of TypeScript syntax

See our website [@babel/plugin-syntax-typescript](https://babeljs.io/docs/babel-plugin-syntax-typescript) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-syntax-typescript
```

or using yarn:

```sh
yarn add @babel/plugin-syntax-typescript --dev
```


---

# @babel/plugin-syntax-unicode-sets-regex

> Parse regular expressions' unicodeSets (v) flag.

See our website [@babel/plugin-syntax-unicode-sets-regex](https://babeljs.io/docs/en/babel-plugin-syntax-unicode-sets-regex) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-syntax-unicode-sets-regex
```

or using yarn:

```sh
yarn add @babel/plugin-syntax-unicode-sets-regex --dev
```


---

# @babel/plugin-transform-arrow-functions

> Compile ES2015 arrow functions to ES5

See our website [@babel/plugin-transform-arrow-functions](https://babeljs.io/docs/babel-plugin-transform-arrow-functions) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-arrow-functions
```

or using yarn:

```sh
yarn add @babel/plugin-transform-arrow-functions --dev
```


---

# @babel/plugin-transform-async-generator-functions

> Turn async generator functions into ES2015 generators

See our website [@babel/plugin-transform-async-generator-functions](https://babeljs.io/docs/babel-plugin-transform-async-generator-functions) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-async-generator-functions
```

or using yarn:

```sh
yarn add @babel/plugin-transform-async-generator-functions --dev
```


---

# @babel/plugin-transform-async-to-generator

> Turn async functions into ES2015 generators

See our website [@babel/plugin-transform-async-to-generator](https://babeljs.io/docs/babel-plugin-transform-async-to-generator) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-async-to-generator
```

or using yarn:

```sh
yarn add @babel/plugin-transform-async-to-generator --dev
```


---

# @babel/plugin-transform-block-scoped-functions

> Babel plugin to ensure function declarations at the block level are block scoped

See our website [@babel/plugin-transform-block-scoped-functions](https://babeljs.io/docs/babel-plugin-transform-block-scoped-functions) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-block-scoped-functions
```

or using yarn:

```sh
yarn add @babel/plugin-transform-block-scoped-functions --dev
```


---

# @babel/plugin-transform-block-scoping

> Compile ES2015 block scoping (const and let) to ES5

See our website [@babel/plugin-transform-block-scoping](https://babeljs.io/docs/babel-plugin-transform-block-scoping) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-block-scoping
```

or using yarn:

```sh
yarn add @babel/plugin-transform-block-scoping --dev
```


---

# @babel/plugin-transform-class-properties

> This plugin transforms static class properties as well as properties declared with the property initializer syntax

See our website [@babel/plugin-transform-class-properties](https://babeljs.io/docs/babel-plugin-transform-class-properties) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-class-properties
```

or using yarn:

```sh
yarn add @babel/plugin-transform-class-properties --dev
```


---

# @babel/plugin-transform-class-static-block

> Transform class static blocks

See our website [@babel/plugin-transform-class-static-block](https://babeljs.io/docs/babel-plugin-transform-class-static-block) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-class-static-block
```

or using yarn:

```sh
yarn add @babel/plugin-transform-class-static-block --dev
```


---

# @babel/plugin-transform-classes

> Compile ES2015 classes to ES5

See our website [@babel/plugin-transform-classes](https://babeljs.io/docs/babel-plugin-transform-classes) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-classes
```

or using yarn:

```sh
yarn add @babel/plugin-transform-classes --dev
```


---

# @babel/plugin-transform-computed-properties

> Compile ES2015 computed properties to ES5

See our website [@babel/plugin-transform-computed-properties](https://babeljs.io/docs/babel-plugin-transform-computed-properties) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-computed-properties
```

or using yarn:

```sh
yarn add @babel/plugin-transform-computed-properties --dev
```


---

# @babel/plugin-transform-destructuring

> Compile ES2015 destructuring to ES5

See our website [@babel/plugin-transform-destructuring](https://babeljs.io/docs/babel-plugin-transform-destructuring) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-destructuring
```

or using yarn:

```sh
yarn add @babel/plugin-transform-destructuring --dev
```


---

# @babel/plugin-transform-dotall-regex

> Compile regular expressions using the `s` (`dotAll`) flag to ES5.

See our website [@babel/plugin-transform-dotall-regex](https://babeljs.io/docs/babel-plugin-transform-dotall-regex) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-dotall-regex
```

or using yarn:

```sh
yarn add @babel/plugin-transform-dotall-regex --dev
```


---

# @babel/plugin-transform-duplicate-keys

> Compile objects with duplicate keys to valid strict ES5

See our website [@babel/plugin-transform-duplicate-keys](https://babeljs.io/docs/babel-plugin-transform-duplicate-keys) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-duplicate-keys
```

or using yarn:

```sh
yarn add @babel/plugin-transform-duplicate-keys --dev
```


---

# @babel/plugin-transform-duplicate-named-capturing-groups-regex

> Compile regular expressions using duplicate named groups to index-based groups.

See our website [@babel/plugin-transform-duplicate-named-capturing-groups-regex](https://babeljs.io/docs/babel-plugin-transform-duplicate-named-capturing-groups-regex) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-duplicate-named-capturing-groups-regex
```

or using yarn:

```sh
yarn add @babel/plugin-transform-duplicate-named-capturing-groups-regex --dev
```


---

# @babel/plugin-transform-dynamic-import

> Transform import() expressions

See our website [@babel/plugin-transform-dynamic-import](https://babeljs.io/docs/babel-plugin-transform-dynamic-import) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-dynamic-import
```

or using yarn:

```sh
yarn add @babel/plugin-transform-dynamic-import --dev
```


---

# @babel/plugin-transform-exponentiation-operator

> Compile exponentiation operator to ES5

See our website [@babel/plugin-transform-exponentiation-operator](https://babeljs.io/docs/babel-plugin-transform-exponentiation-operator) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-exponentiation-operator
```

or using yarn:

```sh
yarn add @babel/plugin-transform-exponentiation-operator --dev
```


---

# @babel/plugin-transform-export-namespace-from

> Compile export namespace to ES2015

See our website [@babel/plugin-transform-export-namespace-from](https://babeljs.io/docs/babel-plugin-transform-export-namespace-from) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-export-namespace-from
```

or using yarn:

```sh
yarn add @babel/plugin-transform-export-namespace-from --dev
```


---

# @babel/plugin-transform-for-of

> Compile ES2015 for...of to ES5

See our website [@babel/plugin-transform-for-of](https://babeljs.io/docs/babel-plugin-transform-for-of) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-for-of
```

or using yarn:

```sh
yarn add @babel/plugin-transform-for-of --dev
```


---

# @babel/plugin-transform-function-name

> Apply ES2015 function.name semantics to all functions

See our website [@babel/plugin-transform-function-name](https://babeljs.io/docs/babel-plugin-transform-function-name) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-function-name
```

or using yarn:

```sh
yarn add @babel/plugin-transform-function-name --dev
```


---

# @babel/plugin-transform-json-strings

> Escape U+2028 LINE SEPARATOR and U+2029 PARAGRAPH SEPARATOR in JS strings

See our website [@babel/plugin-transform-json-strings](https://babeljs.io/docs/babel-plugin-transform-json-strings) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-json-strings
```

or using yarn:

```sh
yarn add @babel/plugin-transform-json-strings --dev
```


---

# @babel/plugin-transform-literals

> Compile ES2015 unicode string and number literals to ES5

See our website [@babel/plugin-transform-literals](https://babeljs.io/docs/babel-plugin-transform-literals) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-literals
```

or using yarn:

```sh
yarn add @babel/plugin-transform-literals --dev
```


---

# @babel/plugin-transform-logical-assignment-operators

> Transforms logical assignment operators into short-circuited assignments

See our website [@babel/plugin-transform-logical-assignment-operators](https://babeljs.io/docs/babel-plugin-transform-logical-assignment-operators) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-logical-assignment-operators
```

or using yarn:

```sh
yarn add @babel/plugin-transform-logical-assignment-operators --dev
```


---

# @babel/plugin-transform-member-expression-literals

> Ensure that reserved words are quoted in property accesses

See our website [@babel/plugin-transform-member-expression-literals](https://babeljs.io/docs/babel-plugin-transform-member-expression-literals) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-member-expression-literals
```

or using yarn:

```sh
yarn add @babel/plugin-transform-member-expression-literals --dev
```


---

# @babel/plugin-transform-modules-amd

> This plugin transforms ES2015 modules to AMD

See our website [@babel/plugin-transform-modules-amd](https://babeljs.io/docs/babel-plugin-transform-modules-amd) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-modules-amd
```

or using yarn:

```sh
yarn add @babel/plugin-transform-modules-amd --dev
```


---

# @babel/plugin-transform-modules-commonjs

> This plugin transforms ES2015 modules to CommonJS

See our website [@babel/plugin-transform-modules-commonjs](https://babeljs.io/docs/babel-plugin-transform-modules-commonjs) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-modules-commonjs
```

or using yarn:

```sh
yarn add @babel/plugin-transform-modules-commonjs --dev
```


---

# @babel/plugin-transform-modules-systemjs

> This plugin transforms ES2015 modules to SystemJS

See our website [@babel/plugin-transform-modules-systemjs](https://babeljs.io/docs/babel-plugin-transform-modules-systemjs) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-modules-systemjs
```

or using yarn:

```sh
yarn add @babel/plugin-transform-modules-systemjs --dev
```


---

# @babel/plugin-transform-modules-umd

> This plugin transforms ES2015 modules to UMD

See our website [@babel/plugin-transform-modules-umd](https://babeljs.io/docs/babel-plugin-transform-modules-umd) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-modules-umd
```

or using yarn:

```sh
yarn add @babel/plugin-transform-modules-umd --dev
```


---

# @babel/plugin-transform-named-capturing-groups-regex

> Compile regular expressions using named groups to ES5.

See our website [@babel/plugin-transform-named-capturing-groups-regex](https://babeljs.io/docs/babel-plugin-transform-named-capturing-groups-regex) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-named-capturing-groups-regex
```

or using yarn:

```sh
yarn add @babel/plugin-transform-named-capturing-groups-regex --dev
```


---

# @babel/plugin-transform-new-target

> Transforms new.target meta property

See our website [@babel/plugin-transform-new-target](https://babeljs.io/docs/babel-plugin-transform-new-target) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-new-target
```

or using yarn:

```sh
yarn add @babel/plugin-transform-new-target --dev
```


---

# @babel/plugin-transform-nullish-coalescing-operator

> Remove nullish coalescing operator

See our website [@babel/plugin-transform-nullish-coalescing-operator](https://babeljs.io/docs/babel-plugin-transform-nullish-coalescing-operator) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-nullish-coalescing-operator
```

or using yarn:

```sh
yarn add @babel/plugin-transform-nullish-coalescing-operator --dev
```


---

# @babel/plugin-transform-numeric-separator

> Remove numeric separators from Decimal, Binary, Hex and Octal literals

See our website [@babel/plugin-transform-numeric-separator](https://babeljs.io/docs/babel-plugin-transform-numeric-separator) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-numeric-separator
```

or using yarn:

```sh
yarn add @babel/plugin-transform-numeric-separator --dev
```


---

# @babel/plugin-transform-object-rest-spread

> Compile object rest and spread to ES5

See our website [@babel/plugin-transform-object-rest-spread](https://babeljs.io/docs/babel-plugin-transform-object-rest-spread) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-object-rest-spread
```

or using yarn:

```sh
yarn add @babel/plugin-transform-object-rest-spread --dev
```


---

# @babel/plugin-transform-object-super

> Compile ES2015 object super to ES5

See our website [@babel/plugin-transform-object-super](https://babeljs.io/docs/babel-plugin-transform-object-super) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-object-super
```

or using yarn:

```sh
yarn add @babel/plugin-transform-object-super --dev
```


---

# @babel/plugin-transform-optional-catch-binding

> Compile optional catch bindings

See our website [@babel/plugin-transform-optional-catch-binding](https://babeljs.io/docs/babel-plugin-transform-optional-catch-binding) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-optional-catch-binding
```

or using yarn:

```sh
yarn add @babel/plugin-transform-optional-catch-binding --dev
```


---

# @babel/plugin-transform-optional-chaining

> Transform optional chaining operators into a series of nil checks

See our website [@babel/plugin-transform-optional-chaining](https://babeljs.io/docs/babel-plugin-transform-optional-chaining) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-optional-chaining
```

or using yarn:

```sh
yarn add @babel/plugin-transform-optional-chaining --dev
```


---

# @babel/plugin-transform-parameters

> Compile ES2015 default and rest parameters to ES5

See our website [@babel/plugin-transform-parameters](https://babeljs.io/docs/babel-plugin-transform-parameters) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-parameters
```

or using yarn:

```sh
yarn add @babel/plugin-transform-parameters --dev
```


---

# @babel/plugin-transform-private-methods

> This plugin transforms private class methods

See our website [@babel/plugin-transform-private-methods](https://babeljs.io/docs/babel-plugin-transform-private-methods) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-private-methods
```

or using yarn:

```sh
yarn add @babel/plugin-transform-private-methods --dev
```


---

# @babel/plugin-transform-private-property-in-object

> This plugin transforms checks for a private property in an object

See our website [@babel/plugin-transform-private-property-in-object](https://babeljs.io/docs/babel-plugin-transform-private-property-in-object) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-private-property-in-object
```

or using yarn:

```sh
yarn add @babel/plugin-transform-private-property-in-object --dev
```


---

# @babel/plugin-transform-property-literals

> Ensure that reserved words are quoted in object property keys

See our website [@babel/plugin-transform-property-literals](https://babeljs.io/docs/babel-plugin-transform-property-literals) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-property-literals
```

or using yarn:

```sh
yarn add @babel/plugin-transform-property-literals --dev
```


---

# @babel/plugin-transform-react-constant-elements

> Treat React JSX elements as value types and hoist them to the highest scope

See our website [@babel/plugin-transform-react-constant-elements](https://babeljs.io/docs/babel-plugin-transform-react-constant-elements) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-react-constant-elements
```

or using yarn:

```sh
yarn add @babel/plugin-transform-react-constant-elements --dev
```


---

# @babel/plugin-transform-react-display-name

> Add displayName to React.createClass calls

See our website [@babel/plugin-transform-react-display-name](https://babeljs.io/docs/babel-plugin-transform-react-display-name) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-react-display-name
```

or using yarn:

```sh
yarn add @babel/plugin-transform-react-display-name --dev
```


---

# @babel/plugin-transform-react-jsx

> Turn JSX into React function calls

See our website [@babel/plugin-transform-react-jsx](https://babeljs.io/docs/babel-plugin-transform-react-jsx) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-react-jsx
```

or using yarn:

```sh
yarn add @babel/plugin-transform-react-jsx --dev
```


---

# @babel/plugin-transform-react-jsx-development

> Turn JSX into React function calls in development

See our website [@babel/plugin-transform-react-jsx-development](https://babeljs.io/docs/babel-plugin-transform-react-jsx-development) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-react-jsx-development
```

or using yarn:

```sh
yarn add @babel/plugin-transform-react-jsx-development --dev
```


---

# @babel/plugin-transform-react-pure-annotations

> Mark top-level React method calls as pure for tree shaking

See our website [@babel/plugin-transform-react-pure-annotations](https://babeljs.io/docs/babel-plugin-transform-react-pure-annotations) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-react-pure-annotations
```

or using yarn:

```sh
yarn add @babel/plugin-transform-react-pure-annotations --dev
```


---

# @babel/plugin-transform-regenerator

> Explode async and generator functions into a state machine.

See our website [@babel/plugin-transform-regenerator](https://babeljs.io/docs/babel-plugin-transform-regenerator) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-regenerator
```

or using yarn:

```sh
yarn add @babel/plugin-transform-regenerator --dev
```


---

# @babel/plugin-transform-regexp-modifiers

> Compile inline regular expression modifiers

See our website [@babel/plugin-transform-regexp-modifiers](https://babeljs.io/docs/babel-plugin-transform-regexp-modifiers) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-regexp-modifiers
```

or using yarn:

```sh
yarn add @babel/plugin-transform-regexp-modifiers --dev
```


---

# @babel/plugin-transform-reserved-words

> Ensure that no reserved words are used.

See our website [@babel/plugin-transform-reserved-words](https://babeljs.io/docs/babel-plugin-transform-reserved-words) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-reserved-words
```

or using yarn:

```sh
yarn add @babel/plugin-transform-reserved-words --dev
```


---

# @babel/plugin-transform-runtime

> Externalise references to helpers and builtins, automatically polyfilling your code without polluting globals

See our website [@babel/plugin-transform-runtime](https://babeljs.io/docs/babel-plugin-transform-runtime) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-runtime
```

or using yarn:

```sh
yarn add @babel/plugin-transform-runtime --dev
```


---

semver(1) -- The semantic versioner for npm
===========================================

## Install

```bash
npm install semver
````

## Usage

As a node module:

```js
const semver = require('semver')

semver.valid('1.2.3') // '1.2.3'
semver.valid('a.b.c') // null
semver.clean('  =v1.2.3   ') // '1.2.3'
semver.satisfies('1.2.3', '1.x || >=2.5.0 || 5.0.0 - 7.2.3') // true
semver.gt('1.2.3', '9.8.7') // false
semver.lt('1.2.3', '9.8.7') // true
semver.minVersion('>=1.0.0') // '1.0.0'
semver.valid(semver.coerce('v2')) // '2.0.0'
semver.valid(semver.coerce('42.6.7.9.3-alpha')) // '42.6.7'
```

As a command-line utility:

```
$ semver -h

A JavaScript implementation of the https://semver.org/ specification
Copyright Isaac Z. Schlueter

Usage: semver [options] <version> [<version> [...]]
Prints valid versions sorted by SemVer precedence

Options:
-r --range <range>
        Print versions that match the specified range.

-i --increment [<level>]
        Increment a version by the specified level.  Level can
        be one of: major, minor, patch, premajor, preminor,
        prepatch, or prerelease.  Default level is 'patch'.
        Only one version may be specified.

--preid <identifier>
        Identifier to be used to prefix premajor, preminor,
        prepatch or prerelease version increments.

-l --loose
        Interpret versions and ranges loosely

-p --include-prerelease
        Always include prerelease versions in range matching

-c --coerce
        Coerce a string into SemVer if possible
        (does not imply --loose)

--rtl
        Coerce version strings right to left

--ltr
        Coerce version strings left to right (default)

Program exits successfully if any valid version satisfies
all supplied ranges, and prints all satisfying versions.

If no satisfying versions are found, then exits failure.

Versions are printed in ascending order, so supplying
multiple versions to the utility will just sort them.
```

## Versions

A "version" is described by the `v2.0.0` specification found at
<https://semver.org/>.

A leading `"="` or `"v"` character is stripped off and ignored.

## Ranges

A `version range` is a set of `comparators` which specify versions
that satisfy the range.

A `comparator` is composed of an `operator` and a `version`.  The set
of primitive `operators` is:

* `<` Less than
* `<=` Less than or equal to
* `>` Greater than
* `>=` Greater than or equal to
* `=` Equal.  If no operator is specified, then equality is assumed,
  so this operator is optional, but MAY be included.

For example, the comparator `>=1.2.7` would match the versions
`1.2.7`, `1.2.8`, `2.5.3`, and `1.3.9`, but not the versions `1.2.6`
or `1.1.0`.

Comparators can be joined by whitespace to form a `comparator set`,
which is satisfied by the **intersection** of all of the comparators
it includes.

A range is composed of one or more comparator sets, joined by `||`.  A
version matches a range if and only if every comparator in at least
one of the `||`-separated comparator sets is satisfied by the version.

For example, the range `>=1.2.7 <1.3.0` would match the versions
`1.2.7`, `1.2.8`, and `1.2.99`, but not the versions `1.2.6`, `1.3.0`,
or `1.1.0`.

The range `1.2.7 || >=1.2.9 <2.0.0` would match the versions `1.2.7`,
`1.2.9`, and `1.4.6`, but not the versions `1.2.8` or `2.0.0`.

### Prerelease Tags

If a version has a prerelease tag (for example, `1.2.3-alpha.3`) then
it will only be allowed to satisfy comparator sets if at least one
comparator with the same `[major, minor, patch]` tuple also has a
prerelease tag.

For example, the range `>1.2.3-alpha.3` would be allowed to match the
version `1.2.3-alpha.7`, but it would *not* be satisfied by
`3.4.5-alpha.9`, even though `3.4.5-alpha.9` is technically "greater
than" `1.2.3-alpha.3` according to the SemVer sort rules.  The version
range only accepts prerelease tags on the `1.2.3` version.  The
version `3.4.5` *would* satisfy the range, because it does not have a
prerelease flag, and `3.4.5` is greater than `1.2.3-alpha.7`.

The purpose for this behavior is twofold.  First, prerelease versions
frequently are updated very quickly, and contain many breaking changes
that are (by the author's design) not yet fit for public consumption.
Therefore, by default, they are excluded from range matching
semantics.

Second, a user who has opted into using a prerelease version has
clearly indicated the intent to use *that specific* set of
alpha/beta/rc versions.  By including a prerelease tag in the range,
the user is indicating that they are aware of the risk.  However, it
is still not appropriate to assume that they have opted into taking a
similar risk on the *next* set of prerelease versions.

Note that this behavior can be suppressed (treating all prerelease
versions as if they were normal versions, for the purpose of range
matching) by setting the `includePrerelease` flag on the options
object to any
[functions](https://github.com/npm/node-semver#functions) that do
range matching.

#### Prerelease Identifiers

The method `.inc` takes an additional `identifier` string argument that
will append the value of the string as a prerelease identifier:

```javascript
semver.inc('1.2.3', 'prerelease', 'beta')
// '1.2.4-beta.0'
```

command-line example:

```bash
$ semver 1.2.3 -i prerelease --preid beta
1.2.4-beta.0
```

Which then can be used to increment further:

```bash
$ semver 1.2.4-beta.0 -i prerelease
1.2.4-beta.1
```

### Advanced Range Syntax

Advanced range syntax desugars to primitive comparators in
deterministic ways.

Advanced ranges may be combined in the same way as primitive
comparators using white space or `||`.

#### Hyphen Ranges `X.Y.Z - A.B.C`

Specifies an inclusive set.

* `1.2.3 - 2.3.4` := `>=1.2.3 <=2.3.4`

If a partial version is provided as the first version in the inclusive
range, then the missing pieces are replaced with zeroes.

* `1.2 - 2.3.4` := `>=1.2.0 <=2.3.4`

If a partial version is provided as the second version in the
inclusive range, then all versions that start with the supplied parts
of the tuple are accepted, but nothing that would be greater than the
provided tuple parts.

* `1.2.3 - 2.3` := `>=1.2.3 <2.4.0`
* `1.2.3 - 2` := `>=1.2.3 <3.0.0`

#### X-Ranges `1.2.x` `1.X` `1.2.*` `*`

Any of `X`, `x`, or `*` may be used to "stand in" for one of the
numeric values in the `[major, minor, patch]` tuple.

* `*` := `>=0.0.0` (Any version satisfies)
* `1.x` := `>=1.0.0 <2.0.0` (Matching major version)
* `1.2.x` := `>=1.2.0 <1.3.0` (Matching major and minor versions)

A partial version range is treated as an X-Range, so the special
character is in fact optional.

* `""` (empty string) := `*` := `>=0.0.0`
* `1` := `1.x.x` := `>=1.0.0 <2.0.0`
* `1.2` := `1.2.x` := `>=1.2.0 <1.3.0`

#### Tilde Ranges `~1.2.3` `~1.2` `~1`

Allows patch-level changes if a minor version is specified on the
comparator.  Allows minor-level changes if not.

* `~1.2.3` := `>=1.2.3 <1.(2+1).0` := `>=1.2.3 <1.3.0`
* `~1.2` := `>=1.2.0 <1.(2+1).0` := `>=1.2.0 <1.3.0` (Same as `1.2.x`)
* `~1` := `>=1.0.0 <(1+1).0.0` := `>=1.0.0 <2.0.0` (Same as `1.x`)
* `~0.2.3` := `>=0.2.3 <0.(2+1).0` := `>=0.2.3 <0.3.0`
* `~0.2` := `>=0.2.0 <0.(2+1).0` := `>=0.2.0 <0.3.0` (Same as `0.2.x`)
* `~0` := `>=0.0.0 <(0+1).0.0` := `>=0.0.0 <1.0.0` (Same as `0.x`)
* `~1.2.3-beta.2` := `>=1.2.3-beta.2 <1.3.0` Note that prereleases in
  the `1.2.3` version will be allowed, if they are greater than or
  equal to `beta.2`.  So, `1.2.3-beta.4` would be allowed, but
  `1.2.4-beta.2` would not, because it is a prerelease of a
  different `[major, minor, patch]` tuple.

#### Caret Ranges `^1.2.3` `^0.2.5` `^0.0.4`

Allows changes that do not modify the left-most non-zero element in the
`[major, minor, patch]` tuple.  In other words, this allows patch and
minor updates for versions `1.0.0` and above, patch updates for
versions `0.X >=0.1.0`, and *no* updates for versions `0.0.X`.

Many authors treat a `0.x` version as if the `x` were the major
"breaking-change" indicator.

Caret ranges are ideal when an author may make breaking changes
between `0.2.4` and `0.3.0` releases, which is a common practice.
However, it presumes that there will *not* be breaking changes between
`0.2.4` and `0.2.5`.  It allows for changes that are presumed to be
additive (but non-breaking), according to commonly observed practices.

* `^1.2.3` := `>=1.2.3 <2.0.0`
* `^0.2.3` := `>=0.2.3 <0.3.0`
* `^0.0.3` := `>=0.0.3 <0.0.4`
* `^1.2.3-beta.2` := `>=1.2.3-beta.2 <2.0.0` Note that prereleases in
  the `1.2.3` version will be allowed, if they are greater than or
  equal to `beta.2`.  So, `1.2.3-beta.4` would be allowed, but
  `1.2.4-beta.2` would not, because it is a prerelease of a
  different `[major, minor, patch]` tuple.
* `^0.0.3-beta` := `>=0.0.3-beta <0.0.4`  Note that prereleases in the
  `0.0.3` version *only* will be allowed, if they are greater than or
  equal to `beta`.  So, `0.0.3-pr.2` would be allowed.

When parsing caret ranges, a missing `patch` value desugars to the
number `0`, but will allow flexibility within that value, even if the
major and minor versions are both `0`.

* `^1.2.x` := `>=1.2.0 <2.0.0`
* `^0.0.x` := `>=0.0.0 <0.1.0`
* `^0.0` := `>=0.0.0 <0.1.0`

A missing `minor` and `patch` values will desugar to zero, but also
allow flexibility within those values, even if the major version is
zero.

* `^1.x` := `>=1.0.0 <2.0.0`
* `^0.x` := `>=0.0.0 <1.0.0`

### Range Grammar

Putting all this together, here is a Backus-Naur grammar for ranges,
for the benefit of parser authors:

```bnf
range-set  ::= range ( logical-or range ) *
logical-or ::= ( ' ' ) * '||' ( ' ' ) *
range      ::= hyphen | simple ( ' ' simple ) * | ''
hyphen     ::= partial ' - ' partial
simple     ::= primitive | partial | tilde | caret
primitive  ::= ( '<' | '>' | '>=' | '<=' | '=' ) partial
partial    ::= xr ( '.' xr ( '.' xr qualifier ? )? )?
xr         ::= 'x' | 'X' | '*' | nr
nr         ::= '0' | ['1'-'9'] ( ['0'-'9'] ) *
tilde      ::= '~' partial
caret      ::= '^' partial
qualifier  ::= ( '-' pre )? ( '+' build )?
pre        ::= parts
build      ::= parts
parts      ::= part ( '.' part ) *
part       ::= nr | [-0-9A-Za-z]+
```

## Functions

All methods and classes take a final `options` object argument.  All
options in this object are `false` by default.  The options supported
are:

- `loose`  Be more forgiving about not-quite-valid semver strings.
  (Any resulting output will always be 100% strict compliant, of
  course.)  For backwards compatibility reasons, if the `options`
  argument is a boolean value instead of an object, it is interpreted
  to be the `loose` param.
- `includePrerelease`  Set to suppress the [default
  behavior](https://github.com/npm/node-semver#prerelease-tags) of
  excluding prerelease tagged versions from ranges unless they are
  explicitly opted into.

Strict-mode Comparators and Ranges will be strict about the SemVer
strings that they parse.

* `valid(v)`: Return the parsed version, or null if it's not valid.
* `inc(v, release)`: Return the version incremented by the release
  type (`major`,   `premajor`, `minor`, `preminor`, `patch`,
  `prepatch`, or `prerelease`), or null if it's not valid
  * `premajor` in one call will bump the version up to the next major
    version and down to a prerelease of that major version.
    `preminor`, and `prepatch` work the same way.
  * If called from a non-prerelease version, the `prerelease` will work the
    same as `prepatch`. It increments the patch version, then makes a
    prerelease. If the input version is already a prerelease it simply
    increments it.
* `prerelease(v)`: Returns an array of prerelease components, or null
  if none exist. Example: `prerelease('1.2.3-alpha.1') -> ['alpha', 1]`
* `major(v)`: Return the major version number.
* `minor(v)`: Return the minor version number.
* `patch(v)`: Return the patch version number.
* `intersects(r1, r2, loose)`: Return true if the two supplied ranges
  or comparators intersect.
* `parse(v)`: Attempt to parse a string as a semantic version, returning either
  a `SemVer` object or `null`.

### Comparison

* `gt(v1, v2)`: `v1 > v2`
* `gte(v1, v2)`: `v1 >= v2`
* `lt(v1, v2)`: `v1 < v2`
* `lte(v1, v2)`: `v1 <= v2`
* `eq(v1, v2)`: `v1 == v2` This is true if they're logically equivalent,
  even if they're not the exact same string.  You already know how to
  compare strings.
* `neq(v1, v2)`: `v1 != v2` The opposite of `eq`.
* `cmp(v1, comparator, v2)`: Pass in a comparison string, and it'll call
  the corresponding function above.  `"==="` and `"!=="` do simple
  string comparison, but are included for completeness.  Throws if an
  invalid comparison string is provided.
* `compare(v1, v2)`: Return `0` if `v1 == v2`, or `1` if `v1` is greater, or `-1` if
  `v2` is greater.  Sorts in ascending order if passed to `Array.sort()`.
* `rcompare(v1, v2)`: The reverse of compare.  Sorts an array of versions
  in descending order when passed to `Array.sort()`.
* `compareBuild(v1, v2)`: The same as `compare` but considers `build` when two versions
  are equal.  Sorts in ascending order if passed to `Array.sort()`.
  `v2` is greater.  Sorts in ascending order if passed to `Array.sort()`.
* `diff(v1, v2)`: Returns difference between two versions by the release type
  (`major`, `premajor`, `minor`, `preminor`, `patch`, `prepatch`, or `prerelease`),
  or null if the versions are the same.

### Comparators

* `intersects(comparator)`: Return true if the comparators intersect

### Ranges

* `validRange(range)`: Return the valid range or null if it's not valid
* `satisfies(version, range)`: Return true if the version satisfies the
  range.
* `maxSatisfying(versions, range)`: Return the highest version in the list
  that satisfies the range, or `null` if none of them do.
* `minSatisfying(versions, range)`: Return the lowest version in the list
  that satisfies the range, or `null` if none of them do.
* `minVersion(range)`: Return the lowest version that can possibly match
  the given range.
* `gtr(version, range)`: Return `true` if version is greater than all the
  versions possible in the range.
* `ltr(version, range)`: Return `true` if version is less than all the
  versions possible in the range.
* `outside(version, range, hilo)`: Return true if the version is outside
  the bounds of the range in either the high or low direction.  The
  `hilo` argument must be either the string `'>'` or `'<'`.  (This is
  the function called by `gtr` and `ltr`.)
* `intersects(range)`: Return true if any of the ranges comparators intersect

Note that, since ranges may be non-contiguous, a version might not be
greater than a range, less than a range, *or* satisfy a range!  For
example, the range `1.2 <1.2.9 || >2.0.0` would have a hole from `1.2.9`
until `2.0.0`, so the version `1.2.10` would not be greater than the
range (because `2.0.1` satisfies, which is higher), nor less than the
range (since `1.2.8` satisfies, which is lower), and it also does not
satisfy the range.

If you want to know if a version satisfies or does not satisfy a
range, use the `satisfies(version, range)` function.

### Coercion

* `coerce(version, options)`: Coerces a string to semver if possible

This aims to provide a very forgiving translation of a non-semver string to
semver. It looks for the first digit in a string, and consumes all
remaining characters which satisfy at least a partial semver (e.g., `1`,
`1.2`, `1.2.3`) up to the max permitted length (256 characters).  Longer
versions are simply truncated (`4.6.3.9.2-alpha2` becomes `4.6.3`).  All
surrounding text is simply ignored (`v3.4 replaces v3.3.1` becomes
`3.4.0`).  Only text which lacks digits will fail coercion (`version one`
is not valid).  The maximum  length for any semver component considered for
coercion is 16 characters; longer components will be ignored
(`10000000000000000.4.7.4` becomes `4.7.4`).  The maximum value for any
semver component is `Integer.MAX_SAFE_INTEGER || (2**53 - 1)`; higher value
components are invalid (`9999999999999999.4.7.4` is likely invalid).

If the `options.rtl` flag is set, then `coerce` will return the right-most
coercible tuple that does not share an ending index with a longer coercible
tuple.  For example, `1.2.3.4` will return `2.3.4` in rtl mode, not
`4.0.0`.  `1.2.3/4` will return `4.0.0`, because the `4` is not a part of
any other overlapping SemVer tuple.

### Clean

* `clean(version)`: Clean a string to be a valid semver if possible

This will return a cleaned and trimmed semver version. If the provided version is not valid a null will be returned. This does not work for ranges. 

ex.
* `s.clean(' = v 2.1.5foo')`: `null`
* `s.clean(' = v 2.1.5foo', { loose: true })`: `'2.1.5-foo'`
* `s.clean(' = v 2.1.5-foo')`: `null`
* `s.clean(' = v 2.1.5-foo', { loose: true })`: `'2.1.5-foo'`
* `s.clean('=v2.1.5')`: `'2.1.5'`
* `s.clean('  =v2.1.5')`: `2.1.5`
* `s.clean('      2.1.5   ')`: `'2.1.5'`
* `s.clean('~1.0.0')`: `null`


---

# @babel/plugin-transform-shorthand-properties

> Compile ES2015 shorthand properties to ES5

See our website [@babel/plugin-transform-shorthand-properties](https://babeljs.io/docs/babel-plugin-transform-shorthand-properties) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-shorthand-properties
```

or using yarn:

```sh
yarn add @babel/plugin-transform-shorthand-properties --dev
```


---

# @babel/plugin-transform-spread

> Compile ES2015 spread to ES5

See our website [@babel/plugin-transform-spread](https://babeljs.io/docs/babel-plugin-transform-spread) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-spread
```

or using yarn:

```sh
yarn add @babel/plugin-transform-spread --dev
```


---

# @babel/plugin-transform-sticky-regex

> Compile ES2015 sticky regex to an ES5 RegExp constructor

See our website [@babel/plugin-transform-sticky-regex](https://babeljs.io/docs/babel-plugin-transform-sticky-regex) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-sticky-regex
```

or using yarn:

```sh
yarn add @babel/plugin-transform-sticky-regex --dev
```


---

# @babel/plugin-transform-template-literals

> Compile ES2015 template literals to ES5

See our website [@babel/plugin-transform-template-literals](https://babeljs.io/docs/babel-plugin-transform-template-literals) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-template-literals
```

or using yarn:

```sh
yarn add @babel/plugin-transform-template-literals --dev
```


---

# @babel/plugin-transform-typeof-symbol

> This transformer wraps all typeof expressions with a method that replicates native behaviour. (ie. returning “symbol” for symbols)

See our website [@babel/plugin-transform-typeof-symbol](https://babeljs.io/docs/babel-plugin-transform-typeof-symbol) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-typeof-symbol
```

or using yarn:

```sh
yarn add @babel/plugin-transform-typeof-symbol --dev
```


---

# @babel/plugin-transform-typescript

> Transform TypeScript into ES.next

See our website [@babel/plugin-transform-typescript](https://babeljs.io/docs/babel-plugin-transform-typescript) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-typescript
```

or using yarn:

```sh
yarn add @babel/plugin-transform-typescript --dev
```


---

# @babel/plugin-transform-unicode-escapes

> Compile ES2015 Unicode escapes to ES5

See our website [@babel/plugin-transform-unicode-escapes](https://babeljs.io/docs/babel-plugin-transform-unicode-escapes) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-unicode-escapes
```

or using yarn:

```sh
yarn add @babel/plugin-transform-unicode-escapes --dev
```


---

# @babel/plugin-transform-unicode-property-regex

> Compile Unicode property escapes in Unicode regular expressions to ES5.

See our website [@babel/plugin-transform-unicode-property-regex](https://babeljs.io/docs/babel-plugin-transform-unicode-property-regex) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-unicode-property-regex
```

or using yarn:

```sh
yarn add @babel/plugin-transform-unicode-property-regex --dev
```


---

# @babel/plugin-transform-unicode-regex

> Compile ES2015 Unicode regex to ES5

See our website [@babel/plugin-transform-unicode-regex](https://babeljs.io/docs/babel-plugin-transform-unicode-regex) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-unicode-regex
```

or using yarn:

```sh
yarn add @babel/plugin-transform-unicode-regex --dev
```


---

# @babel/plugin-transform-unicode-sets-regex

> Compile regular expressions' unicodeSets (v) flag.

See our website [@babel/plugin-transform-unicode-sets-regex](https://babeljs.io/docs/babel-plugin-transform-unicode-sets-regex) for more information.

## Install

Using npm:

```sh
npm install --save-dev @babel/plugin-transform-unicode-sets-regex
```

or using yarn:

```sh
yarn add @babel/plugin-transform-unicode-sets-regex --dev
```


---

# Contributing

## Adding a new plugin or polyfill to support (when approved in the next ECMAScript version)

### Update [`plugin-features.js`](https://github.com/babel/babel/blob/main/packages/babel-compat-data/scripts/data/plugin-features.js)

*Example:*

If you were going to add `**` which is in ES2016:

Find the relevant entries on [compat-table](https://kangax.github.io/compat-table/es2016plus/#test-exponentiation_(**)_operator):

`exponentiation (**) operator`

Find the corresponding babel plugin:

`@babel/plugin-transform-exponentiation-operator`

And add them in this structure:

```js
// es2016
"@babel/plugin-transform-exponentiation-operator": {
  features: [
    "exponentiation (**) operator",
  ],
},
```

### Update data for `core-js@2` polyfilling

*Example:*

In case you want to add `Object.values` which is in ES2017:

Find the relevant feature and subfeature on [compat-table](https://kangax.github.io/compat-table/es2016plus/#test-Object_static_methods_Object.values)
and split it with `/`:

`Object static methods / Object.values`

Find the corresponding module on [`core-js@2`](https://github.com/zloirock/core-js/tree/v2/modules):

`es7.object.values.js`

Find required ES version in [`corejs2-built-in-features.js`](https://github.com/babel/babel/blob/main/packages/babel-preset-env/data/corejs2-built-in-features.js) and add the new feature:

```js
const es = {
  //...
  "es7.object.values": "Object static methods / Object.values"
}
```

If you want to transform a new built-in by `useBuiltIns: 'usage'`, add mapping to related `core-js` modules to [this file](https://github.com/babel/babel/blob/main/packages/babel-preset-env/polyfills/corejs2/built-in-definitions.js).

### Update data for `core-js@3` polyfilling

Just update the version of [`core-js-compat`](https://github.com/zloirock/core-js/tree/main/packages/core-js-compat) in dependencies.

If you want to transform a new built-in by `useBuiltIns: 'usage'`, add mapping to related [`core-js`](https://github.com/zloirock/core-js/tree/main/packages/core-js/modules) modules to [this file](https://github.com/babel/babel/blob/main/packages/babel-preset-env/polyfills/corejs3/built-in-definitions.js).

If you want to mark a new proposal as shipped, add it to [this list](https://github.com/babel/babel/blob/main/packages/babel-preset-env/polyfills/corejs3/shipped-proposals.js).

### Update [`plugins.json`](https://github.com/babel/babel/blob/main/packages/babel-preset-env/data/plugins.json)

Until `compat-table` is a standalone npm module for data we are using the git commit in `packages/babel-compat-data/scripts/download-compat-table.sh`

`COMPAT_TABLE_COMMIT=[latest-commit-hash]`,

So we update and then run `npm run build-data`. If there are no changes, then `plugins.json` will be the same.

## Tests

### Running tests
See general [CONTRIBUTING.md](https://github.com/babel/babel/blob/main/CONTRIBUTING.md#running-lintingtests).

### Writing tests

#### General

All the tests for `@babel/preset-env` exist in the `test/fixtures` folder. The
test setup and conventions are exactly the same as testing a Babel plugin, so
please read our [documentation on writing tests](https://github.com/babel/babel/blob/main/CONTRIBUTING.md#babel-plugin-x).

#### Testing the `debug` option

Testing debug output to `stdout` is similar. Under the `test/debug-fixtures`,
create a folder with a descriptive name of your test, and add the following:

* Add a `options.json` file (just as the other tests, this is essentially a
`.babelrc`) with the desired test configuration (required)
* Add a `stdout.txt` file with the expected debug output. For added
convenience, if there is no `stdout.txt` present, the test runner will
generate one for you.


---

# @babel/preset-env

> A Babel preset for each environment.

See our website [@babel/preset-env](https://babeljs.io/docs/babel-preset-env) for more information or the [issues](https://github.com/babel/babel/issues?utf8=%E2%9C%93&q=is%3Aissue+label%3A%22pkg%3A%20preset-env%22+is%3Aopen) associated with this package.

## Install

Using npm:

```sh
npm install --save-dev @babel/preset-env
```

or using yarn:

```sh
yarn add @babel/preset-env --dev
```


---

semver(1) -- The semantic versioner for npm
===========================================

## Install

```bash
npm install semver
````

## Usage

As a node module:

```js
const semver = require('semver')

semver.valid('1.2.3') // '1.2.3'
semver.valid('a.b.c') // null
semver.clean('  =v1.2.3   ') // '1.2.3'
semver.satisfies('1.2.3', '1.x || >=2.5.0 || 5.0.0 - 7.2.3') // true
semver.gt('1.2.3', '9.8.7') // false
semver.lt('1.2.3', '9.8.7') // true
semver.minVersion('>=1.0.0') // '1.0.0'
semver.valid(semver.coerce('v2')) // '2.0.0'
semver.valid(semver.coerce('42.6.7.9.3-alpha')) // '42.6.7'
```

As a command-line utility:

```
$ semver -h

A JavaScript implementation of the https://semver.org/ specification
Copyright Isaac Z. Schlueter

Usage: semver [options] <version> [<version> [...]]
Prints valid versions sorted by SemVer precedence

Options:
-r --range <range>
        Print versions that match the specified range.

-i --increment [<level>]
        Increment a version by the specified level.  Level can
        be one of: major, minor, patch, premajor, preminor,
        prepatch, or prerelease.  Default level is 'patch'.
        Only one version may be specified.

--preid <identifier>
        Identifier to be used to prefix premajor, preminor,
        prepatch or prerelease version increments.

-l --loose
        Interpret versions and ranges loosely

-p --include-prerelease
        Always include prerelease versions in range matching

-c --coerce
        Coerce a string into SemVer if possible
        (does not imply --loose)

--rtl
        Coerce version strings right to left

--ltr
        Coerce version strings left to right (default)

Program exits successfully if any valid version satisfies
all supplied ranges, and prints all satisfying versions.

If no satisfying versions are found, then exits failure.

Versions are printed in ascending order, so supplying
multiple versions to the utility will just sort them.
```

## Versions

A "version" is described by the `v2.0.0` specification found at
<https://semver.org/>.

A leading `"="` or `"v"` character is stripped off and ignored.

## Ranges

A `version range` is a set of `comparators` which specify versions
that satisfy the range.

A `comparator` is composed of an `operator` and a `version`.  The set
of primitive `operators` is:

* `<` Less than
* `<=` Less than or equal to
* `>` Greater than
* `>=` Greater than or equal to
* `=` Equal.  If no operator is specified, then equality is assumed,
  so this operator is optional, but MAY be included.

For example, the comparator `>=1.2.7` would match the versions
`1.2.7`, `1.2.8`, `2.5.3`, and `1.3.9`, but not the versions `1.2.6`
or `1.1.0`.

Comparators can be joined by whitespace to form a `comparator set`,
which is satisfied by the **intersection** of all of the comparators
it includes.

A range is composed of one or more comparator sets, joined by `||`.  A
version matches a range if and only if every comparator in at least
one of the `||`-separated comparator sets is satisfied by the version.

For example, the range `>=1.2.7 <1.3.0` would match the versions
`1.2.7`, `1.2.8`, and `1.2.99`, but not the versions `1.2.6`, `1.3.0`,
or `1.1.0`.

The range `1.2.7 || >=1.2.9 <2.0.0` would match the versions `1.2.7`,
`1.2.9`, and `1.4.6`, but not the versions `1.2.8` or `2.0.0`.

### Prerelease Tags

If a version has a prerelease tag (for example, `1.2.3-alpha.3`) then
it will only be allowed to satisfy comparator sets if at least one
comparator with the same `[major, minor, patch]` tuple also has a
prerelease tag.

For example, the range `>1.2.3-alpha.3` would be allowed to match the
version `1.2.3-alpha.7`, but it would *not* be satisfied by
`3.4.5-alpha.9`, even though `3.4.5-alpha.9` is technically "greater
than" `1.2.3-alpha.3` according to the SemVer sort rules.  The version
range only accepts prerelease tags on the `1.2.3` version.  The
version `3.4.5` *would* satisfy the range, because it does not have a
prerelease flag, and `3.4.5` is greater than `1.2.3-alpha.7`.

The purpose for this behavior is twofold.  First, prerelease versions
frequently are updated very quickly, and contain many breaking changes
that are (by the author's design) not yet fit for public consumption.
Therefore, by default, they are excluded from range matching
semantics.

Second, a user who has opted into using a prerelease version has
clearly indicated the intent to use *that specific* set of
alpha/beta/rc versions.  By including a prerelease tag in the range,
the user is indicating that they are aware of the risk.  However, it
is still not appropriate to assume that they have opted into taking a
similar risk on the *next* set of prerelease versions.

Note that this behavior can be suppressed (treating all prerelease
versions as if they were normal versions, for the purpose of range
matching) by setting the `includePrerelease` flag on the options
object to any
[functions](https://github.com/npm/node-semver#functions) that do
range matching.

#### Prerelease Identifiers

The method `.inc` takes an additional `identifier` string argument that
will append the value of the string as a prerelease identifier:

```javascript
semver.inc('1.2.3', 'prerelease', 'beta')
// '1.2.4-beta.0'
```

command-line example:

```bash
$ semver 1.2.3 -i prerelease --preid beta
1.2.4-beta.0
```

Which then can be used to increment further:

```bash
$ semver 1.2.4-beta.0 -i prerelease
1.2.4-beta.1
```

### Advanced Range Syntax

Advanced range syntax desugars to primitive comparators in
deterministic ways.

Advanced ranges may be combined in the same way as primitive
comparators using white space or `||`.

#### Hyphen Ranges `X.Y.Z - A.B.C`

Specifies an inclusive set.

* `1.2.3 - 2.3.4` := `>=1.2.3 <=2.3.4`

If a partial version is provided as the first version in the inclusive
range, then the missing pieces are replaced with zeroes.

* `1.2 - 2.3.4` := `>=1.2.0 <=2.3.4`

If a partial version is provided as the second version in the
inclusive range, then all versions that start with the supplied parts
of the tuple are accepted, but nothing that would be greater than the
provided tuple parts.

* `1.2.3 - 2.3` := `>=1.2.3 <2.4.0`
* `1.2.3 - 2` := `>=1.2.3 <3.0.0`

#### X-Ranges `1.2.x` `1.X` `1.2.*` `*`

Any of `X`, `x`, or `*` may be used to "stand in" for one of the
numeric values in the `[major, minor, patch]` tuple.

* `*` := `>=0.0.0` (Any version satisfies)
* `1.x` := `>=1.0.0 <2.0.0` (Matching major version)
* `1.2.x` := `>=1.2.0 <1.3.0` (Matching major and minor versions)

A partial version range is treated as an X-Range, so the special
character is in fact optional.

* `""` (empty string) := `*` := `>=0.0.0`
* `1` := `1.x.x` := `>=1.0.0 <2.0.0`
* `1.2` := `1.2.x` := `>=1.2.0 <1.3.0`

#### Tilde Ranges `~1.2.3` `~1.2` `~1`

Allows patch-level changes if a minor version is specified on the
comparator.  Allows minor-level changes if not.

* `~1.2.3` := `>=1.2.3 <1.(2+1).0` := `>=1.2.3 <1.3.0`
* `~1.2` := `>=1.2.0 <1.(2+1).0` := `>=1.2.0 <1.3.0` (Same as `1.2.x`)
* `~1` := `>=1.0.0 <(1+1).0.0` := `>=1.0.0 <2.0.0` (Same as `1.x`)
* `~0.2.3` := `>=0.2.3 <0.(2+1).0` := `>=0.2.3 <0.3.0`
* `~0.2` := `>=0.2.0 <0.(2+1).0` := `>=0.2.0 <0.3.0` (Same as `0.2.x`)
* `~0` := `>=0.0.0 <(0+1).0.0` := `>=0.0.0 <1.0.0` (Same as `0.x`)
* `~1.2.3-beta.2` := `>=1.2.3-beta.2 <1.3.0` Note that prereleases in
  the `1.2.3` version will be allowed, if they are greater than or
  equal to `beta.2`.  So, `1.2.3-beta.4` would be allowed, but
  `1.2.4-beta.2` would not, because it is a prerelease of a
  different `[major, minor, patch]` tuple.

#### Caret Ranges `^1.2.3` `^0.2.5` `^0.0.4`

Allows changes that do not modify the left-most non-zero element in the
`[major, minor, patch]` tuple.  In other words, this allows patch and
minor updates for versions `1.0.0` and above, patch updates for
versions `0.X >=0.1.0`, and *no* updates for versions `0.0.X`.

Many authors treat a `0.x` version as if the `x` were the major
"breaking-change" indicator.

Caret ranges are ideal when an author may make breaking changes
between `0.2.4` and `0.3.0` releases, which is a common practice.
However, it presumes that there will *not* be breaking changes between
`0.2.4` and `0.2.5`.  It allows for changes that are presumed to be
additive (but non-breaking), according to commonly observed practices.

* `^1.2.3` := `>=1.2.3 <2.0.0`
* `^0.2.3` := `>=0.2.3 <0.3.0`
* `^0.0.3` := `>=0.0.3 <0.0.4`
* `^1.2.3-beta.2` := `>=1.2.3-beta.2 <2.0.0` Note that prereleases in
  the `1.2.3` version will be allowed, if they are greater than or
  equal to `beta.2`.  So, `1.2.3-beta.4` would be allowed, but
  `1.2.4-beta.2` would not, because it is a prerelease of a
  different `[major, minor, patch]` tuple.
* `^0.0.3-beta` := `>=0.0.3-beta <0.0.4`  Note that prereleases in the
  `0.0.3` version *only* will be allowed, if they are greater than or
  equal to `beta`.  So, `0.0.3-pr.2` would be allowed.

When parsing caret ranges, a missing `patch` value desugars to the
number `0`, but will allow flexibility within that value, even if the
major and minor versions are both `0`.

* `^1.2.x` := `>=1.2.0 <2.0.0`
* `^0.0.x` := `>=0.0.0 <0.1.0`
* `^0.0` := `>=0.0.0 <0.1.0`

A missing `minor` and `patch` values will desugar to zero, but also
allow flexibility within those values, even if the major version is
zero.

* `^1.x` := `>=1.0.0 <2.0.0`
* `^0.x` := `>=0.0.0 <1.0.0`

### Range Grammar

Putting all this together, here is a Backus-Naur grammar for ranges,
for the benefit of parser authors:

```bnf
range-set  ::= range ( logical-or range ) *
logical-or ::= ( ' ' ) * '||' ( ' ' ) *
range      ::= hyphen | simple ( ' ' simple ) * | ''
hyphen     ::= partial ' - ' partial
simple     ::= primitive | partial | tilde | caret
primitive  ::= ( '<' | '>' | '>=' | '<=' | '=' ) partial
partial    ::= xr ( '.' xr ( '.' xr qualifier ? )? )?
xr         ::= 'x' | 'X' | '*' | nr
nr         ::= '0' | ['1'-'9'] ( ['0'-'9'] ) *
tilde      ::= '~' partial
caret      ::= '^' partial
qualifier  ::= ( '-' pre )? ( '+' build )?
pre        ::= parts
build      ::= parts
parts      ::= part ( '.' part ) *
part       ::= nr | [-0-9A-Za-z]+
```

## Functions

All methods and classes take a final `options` object argument.  All
options in this object are `false` by default.  The options supported
are:

- `loose`  Be more forgiving about not-quite-valid semver strings.
  (Any resulting output will always be 100% strict compliant, of
  course.)  For backwards compatibility reasons, if the `options`
  argument is a boolean value instead of an object, it is interpreted
  to be the `loose` param.
- `includePrerelease`  Set to suppress the [default
  behavior](https://github.com/npm/node-semver#prerelease-tags) of
  excluding prerelease tagged versions from ranges unless they are
  explicitly opted into.

Strict-mode Comparators and Ranges will be strict about the SemVer
strings that they parse.

* `valid(v)`: Return the parsed version, or null if it's not valid.
* `inc(v, release)`: Return the version incremented by the release
  type (`major`,   `premajor`, `minor`, `preminor`, `patch`,
  `prepatch`, or `prerelease`), or null if it's not valid
  * `premajor` in one call will bump the version up to the next major
    version and down to a prerelease of that major version.
    `preminor`, and `prepatch` work the same way.
  * If called from a non-prerelease version, the `prerelease` will work the
    same as `prepatch`. It increments the patch version, then makes a
    prerelease. If the input version is already a prerelease it simply
    increments it.
* `prerelease(v)`: Returns an array of prerelease components, or null
  if none exist. Example: `prerelease('1.2.3-alpha.1') -> ['alpha', 1]`
* `major(v)`: Return the major version number.
* `minor(v)`: Return the minor version number.
* `patch(v)`: Return the patch version number.
* `intersects(r1, r2, loose)`: Return true if the two supplied ranges
  or comparators intersect.
* `parse(v)`: Attempt to parse a string as a semantic version, returning either
  a `SemVer` object or `null`.

### Comparison

* `gt(v1, v2)`: `v1 > v2`
* `gte(v1, v2)`: `v1 >= v2`
* `lt(v1, v2)`: `v1 < v2`
* `lte(v1, v2)`: `v1 <= v2`
* `eq(v1, v2)`: `v1 == v2` This is true if they're logically equivalent,
  even if they're not the exact same string.  You already know how to
  compare strings.
* `neq(v1, v2)`: `v1 != v2` The opposite of `eq`.
* `cmp(v1, comparator, v2)`: Pass in a comparison string, and it'll call
  the corresponding function above.  `"==="` and `"!=="` do simple
  string comparison, but are included for completeness.  Throws if an
  invalid comparison string is provided.
* `compare(v1, v2)`: Return `0` if `v1 == v2`, or `1` if `v1` is greater, or `-1` if
  `v2` is greater.  Sorts in ascending order if passed to `Array.sort()`.
* `rcompare(v1, v2)`: The reverse of compare.  Sorts an array of versions
  in descending order when passed to `Array.sort()`.
* `compareBuild(v1, v2)`: The same as `compare` but considers `build` when two versions
  are equal.  Sorts in ascending order if passed to `Array.sort()`.
  `v2` is greater.  Sorts in ascending order if passed to `Array.sort()`.
* `diff(v1, v2)`: Returns difference between two versions by the release type
  (`major`, `premajor`, `minor`, `preminor`, `patch`, `prepatch`, or `prerelease`),
  or null if the versions are the same.

### Comparators

* `intersects(comparator)`: Return true if the comparators intersect

### Ranges

* `validRange(range)`: Return the valid range or null if it's not valid
* `satisfies(version, range)`: Return true if the version satisfies the
  range.
* `maxSatisfying(versions, range)`: Return the highest version in the list
  that satisfies the range, or `null` if none of them do.
* `minSatisfying(versions, range)`: Return the lowest version in the list
  that satisfies the range, or `null` if none of them do.
* `minVersion(range)`: Return the lowest version that can possibly match
  the given range.
* `gtr(version, range)`: Return `true` if version is greater than all the
  versions possible in the range.
* `ltr(version, range)`: Return `true` if version is less than all the
  versions possible in the range.
* `outside(version, range, hilo)`: Return true if the version is outside
  the bounds of the range in either the high or low direction.  The
  `hilo` argument must be either the string `'>'` or `'<'`.  (This is
  the function called by `gtr` and `ltr`.)
* `intersects(range)`: Return true if any of the ranges comparators intersect

Note that, since ranges may be non-contiguous, a version might not be
greater than a range, less than a range, *or* satisfy a range!  For
example, the range `1.2 <1.2.9 || >2.0.0` would have a hole from `1.2.9`
until `2.0.0`, so the version `1.2.10` would not be greater than the
range (because `2.0.1` satisfies, which is higher), nor less than the
range (since `1.2.8` satisfies, which is lower), and it also does not
satisfy the range.

If you want to know if a version satisfies or does not satisfy a
range, use the `satisfies(version, range)` function.

### Coercion

* `coerce(version, options)`: Coerces a string to semver if possible

This aims to provide a very forgiving translation of a non-semver string to
semver. It looks for the first digit in a string, and consumes all
remaining characters which satisfy at least a partial semver (e.g., `1`,
`1.2`, `1.2.3`) up to the max permitted length (256 characters).  Longer
versions are simply truncated (`4.6.3.9.2-alpha2` becomes `4.6.3`).  All
surrounding text is simply ignored (`v3.4 replaces v3.3.1` becomes
`3.4.0`).  Only text which lacks digits will fail coercion (`version one`
is not valid).  The maximum  length for any semver component considered for
coercion is 16 characters; longer components will be ignored
(`10000000000000000.4.7.4` becomes `4.7.4`).  The maximum value for any
semver component is `Integer.MAX_SAFE_INTEGER || (2**53 - 1)`; higher value
components are invalid (`9999999999999999.4.7.4` is likely invalid).

If the `options.rtl` flag is set, then `coerce` will return the right-most
coercible tuple that does not share an ending index with a longer coercible
tuple.  For example, `1.2.3.4` will return `2.3.4` in rtl mode, not
`4.0.0`.  `1.2.3/4` will return `4.0.0`, because the `4` is not a part of
any other overlapping SemVer tuple.

### Clean

* `clean(version)`: Clean a string to be a valid semver if possible

This will return a cleaned and trimmed semver version. If the provided version is not valid a null will be returned. This does not work for ranges. 

ex.
* `s.clean(' = v 2.1.5foo')`: `null`
* `s.clean(' = v 2.1.5foo', { loose: true })`: `'2.1.5-foo'`
* `s.clean(' = v 2.1.5-foo')`: `null`
* `s.clean(' = v 2.1.5-foo', { loose: true })`: `'2.1.5-foo'`
* `s.clean('=v2.1.5')`: `'2.1.5'`
* `s.clean('  =v2.1.5')`: `2.1.5`
* `s.clean('      2.1.5   ')`: `'2.1.5'`
* `s.clean('~1.0.0')`: `null`


---

# `@babel/preset-modules`

> ℹ️ Starting from `@babel/preset-env` 7.9.0, you can enable the [`bugfixes: true` option](https://babeljs.io/docs/en/babel-preset-env#bugfixes) to get the same behavior as using `@babel/preset-modules`, but with support for custom `targets`.
> If you need to target browsers with native modules support (like this preset does), you can use `targets: { esmodules: true }`.

A Babel preset that enables async/await, Tagged Templates, arrow functions, destructured and rest parameters, and more **in all modern browsers** ([88% of traffic](https://caniuse.com/#feat=es6-module)).

It works around bugs and inconsistencies in modern JavaScript engines by converting broken syntax to the _closest non-broken modern syntax_.  Use this in place of `@babel/preset-env`'s [target.esmodules](https://babeljs.io/docs/en/babel-preset-env#targetsesmodules) option for smaller bundle size and improved performance.

This preset is only useful for browsers. You can serve the output to modern browsers while still supporting older browsers using the [module/nomodule pattern](https://philipwalton.com/articles/deploying-es2015-code-in-production-today/):

```html
<!-- transpiled with preset-modules: -->
<script type="module" src="modern.js"></script>
<!-- transpiled with preset-env: -->
<script nomodule src="legacy.js"></script>
```

### Features Supported

- JSX spread attributes are compiled to Object.assign() instead of a helper.
- Default, destructured and optional parameters are all natively supported.
- Tagged Templates are fully supported, patched for Safari 10+ and Edge 16+.
- async/await is supported without being transpiled to generators.
- Function name inference works as expected, including Arrow Functions.

### Installation & Usage

Install the preset from [npm](https://www.npmjs.com/package/@babel/preset-modules):

```sh
npm install @babel/preset-modules --save-dev
```

To use the preset, add it to your [Babel Configuration](https://babeljs.io/docs/en/configuration):

```js
{
  "presets": [
    "@babel/preset-modules"
  ]
}
```

If you're implementing the module/nomodule pattern, your configuration might look something like this:

```js
{
  "env": {
    "modern": {
      "presets": [
        "@babel/preset-modules"
      ]
    },
    "legacy": {
      "presets": [
        "@babel/preset-env"
      ]
    }
  }
}
```

### Options

There's a single Boolean `loose` option, which defaults to `false`. Passing `true` further reduces output size.

The `loose` setting turns off a rarely-needed function name workaround for older versions of Edge. If you're not relying on `Function.prototype.name`, it's worth enabling loose mode.

### How does it work?

Babel’s `preset-env` is great, since it lets you define which Babel features are needed based on a browser support target. In order to make that plumbing work automatically, the preset has configuration that groups all of the new JavaScript syntax features into collections of related syntax transforms. These groups are fairly large, for example "function arguments" includes destructured, default and rest parameters. The groupings come from the fact that Babel’s transforms often rely on other transforms, so they can’t always be applied in isolation.

From this grouping information, Babel enables or disables each group based on the browser support target you specify to preset-env’s [targets](https://babeljs.io/docs/en/babel-preset-env#targets) option. For modern output, the [targets.esmodules](https://babeljs.io/docs/en/babel-preset-env#targetsesmodules) option is effectively an alias for the set of browsers that support ES Modules: Edge 16+, Safari 10.1+, Firefox 60+ and Chrome 61+.

Here's the problem: if any version of any browser in that list contains a bug triggered by modern syntax, the only solution we have is to enable the corresponding transform group that fixes that bug. This means that fundamentally, preset-env converts code to ES5 in order to get around syntax bugs in ES2017. Since that's the only solution at our disposal, eventually it becomes overused.

For example, all of the new syntax features relating to function parameters are grouped into the same Babel plugin (`@babel/plugin-transform-function-parameters`). That means because Edge 16 & 17 support ES Modules but have a bug related to parsing shorthand destructured parameters with default values within arrow functions, all functions get compiled from the new compact argument syntaxes down to ES5:

```js
// this breaks in Edge 16:
const foo = ({ a = 1 }) => {};

// .. but this doesn't:
function foo({ a = 1, b }, ...args) {}

// ... and neither does this:
const foo = ({ a: a = 1 }) => {};
```

In fact, there are 23 syntax improvements for function parameters in ES2017, and only one of them is broken in ES Modules-supporting browsers. It seems unfortunate to transpile all those great features down to ES5 just for one browser!

This plugin takes a different approach than we've historically taken with JavaScript: it transpiles the broken syntax to the closest _non-broken modern syntax_. In the above case, here's what is generated to fix all ES Modules-supporting browsers:

**input:**

```js
const foo = ({ a = 1 }, b = 2, ...args) => [a,b,args];
```

**output:**

```js
const foo = ({ a: a = 1 }, b = 2, ...args) => [a,b,args];
```

That output works in all ES Modules-supporting browsers, and is only **59 bytes** minified & gzipped.

> Compare this to `@babel/preset-env`'s `targets.esmodules` output (**147 bytes** minified & gzipped):
>
> ```js
>const foo = function foo(_ref, b) {
>  let { a = 1 } = _ref;
>
>  if (b === void 0) { b = 2; }
>
>  for (
>    var _len = arguments.length,
>      args = new Array(_len > 2 ? _len - 2 : 0),
>      _key = 2;  _key < _len; _key++
>  ) {
>    args[_key - 2] = arguments[_key];
>  }
>
>  return [a, b, args];
>};
>````

The result is improved bundle size and performance, while supporting the same browsers.


### Important: Minification

The output generated by this preset includes workarounds for Safari 10, however minifiers like Terser sometimes remove these workarounds. In order to avoid shipping broken code, it's important to tell Terser to preserve the workarounds, which can be done via the `safari10` option.

It's also generally the case that minifiers are configured to output ES5 by default, so you'll want to change the output syntax to ES2017.

With [Terser's Node API](https://github.com/terser/terser#minify-options):

```js
terser.minify({
  ecma: 2017,
  safari10: true
})
```

With [Terser CLI](https://npm.im/terser):

```sh
terser --ecma 2017 --safari10 ...
```

With [terser-webpack-plugin](https://webpack.js.org/plugins/terser-webpack-plugin/):

```js
module.exports = {
  optimization: {
    minimizer: [
      new TerserPlugin({
        terserOptions: {
          ecma: 2017,
          safari10: true
        }
      })
    ]
  }
};
```

All of the above configurations also apply to [uglify-es](https://github.com/mishoo/UglifyJS2/tree/harmony).
UglifyJS (2.x and prior) does not support modern JavaScript, so it cannot be used in conjunction with this preset.


---

# @babel/preset-react

> Babel preset for all React plugins.

See our website [@babel/preset-react](https://babeljs.io/docs/babel-preset-react) for more information or the [issues](https://github.com/babel/babel/issues?utf8=%E2%9C%93&q=is%3Aissue+label%3A%22area%3A%20react%22+is%3Aopen) associated with this package.

## Install

Using npm:

```sh
npm install --save-dev @babel/preset-react
```

or using yarn:

```sh
yarn add @babel/preset-react --dev
```


---

# @babel/preset-typescript

> Babel preset for TypeScript.

See our website [@babel/preset-typescript](https://babeljs.io/docs/babel-preset-typescript) for more information or the [issues](https://github.com/babel/babel/issues?utf8=%E2%9C%93&q=is%3Aissue+label%3A%22area%3A%20typescript%22+is%3Aopen) associated with this package.

## Install

Using npm:

```sh
npm install --save-dev @babel/preset-typescript
```

or using yarn:

```sh
yarn add @babel/preset-typescript --dev
```


---

# @babel/runtime

> babel's modular runtime helpers

See our website [@babel/runtime](https://babeljs.io/docs/babel-runtime) for more information.

## Install

Using npm:

```sh
npm install --save @babel/runtime
```

or using yarn:

```sh
yarn add @babel/runtime
```


---

# @babel/runtime-corejs3

> babel's modular runtime helpers with core-js@3 polyfilling

See our website [@babel/runtime-corejs3](https://babeljs.io/docs/babel-runtime-corejs3) for more information.

## Install

Using npm:

```sh
npm install --save @babel/runtime-corejs3
```

or using yarn:

```sh
yarn add @babel/runtime-corejs3
```


---

# @babel/template

> Generate an AST from a string template.

See our website [@babel/template](https://babeljs.io/docs/babel-template) for more information or the [issues](https://github.com/babel/babel/issues?utf8=%E2%9C%93&q=is%3Aissue+label%3A%22pkg%3A%20template%22+is%3Aopen) associated with this package.

## Install

Using npm:

```sh
npm install --save-dev @babel/template
```

or using yarn:

```sh
yarn add @babel/template --dev
```


---

# @babel/traverse

> The Babel Traverse module maintains the overall tree state, and is responsible for replacing, removing, and adding nodes

See our website [@babel/traverse](https://babeljs.io/docs/babel-traverse) for more information or the [issues](https://github.com/babel/babel/issues?utf8=%E2%9C%93&q=is%3Aissue+label%3A%22pkg%3A%20traverse%22+is%3Aopen) associated with this package.

## Install

Using npm:

```sh
npm install --save-dev @babel/traverse
```

or using yarn:

```sh
yarn add @babel/traverse --dev
```


---

# @babel/types

> Babel Types is a Lodash-esque utility library for AST nodes

See our website [@babel/types](https://babeljs.io/docs/babel-types) for more information or the [issues](https://github.com/babel/babel/issues?utf8=%E2%9C%93&q=is%3Aissue+label%3A%22pkg%3A%20types%22+is%3Aopen) associated with this package.

## Install

Using npm:

```sh
npm install --save-dev @babel/types
```

or using yarn:

```sh
yarn add @babel/types --dev
```


---

# @colors/colors ("colors.js")
[![Build Status](https://github.com/DABH/colors.js/actions/workflows/ci.yml/badge.svg)](https://github.com/DABH/colors.js/actions/workflows/ci.yml)
[![version](https://img.shields.io/npm/v/@colors/colors.svg)](https://www.npmjs.org/package/@colors/colors)

Please check out the [roadmap](ROADMAP.md) for upcoming features and releases.  Please open Issues to provide feedback.

## get color and style in your node.js console

![Demo](https://raw.githubusercontent.com/DABH/colors.js/master/screenshots/colors.png)

## Installation

    npm install @colors/colors

## colors and styles!

### text colors

  - black
  - red
  - green
  - yellow
  - blue
  - magenta
  - cyan
  - white
  - gray
  - grey

### bright text colors

  - brightRed
  - brightGreen
  - brightYellow
  - brightBlue
  - brightMagenta
  - brightCyan
  - brightWhite

### background colors

  - bgBlack
  - bgRed
  - bgGreen
  - bgYellow
  - bgBlue
  - bgMagenta
  - bgCyan
  - bgWhite
  - bgGray
  - bgGrey

### bright background colors

  - bgBrightRed
  - bgBrightGreen
  - bgBrightYellow
  - bgBrightBlue
  - bgBrightMagenta
  - bgBrightCyan
  - bgBrightWhite

### styles

  - reset
  - bold
  - dim
  - italic
  - underline
  - inverse
  - hidden
  - strikethrough

### extras

  - rainbow
  - zebra
  - america
  - trap
  - random


## Usage

By popular demand, `@colors/colors` now ships with two types of usages!

The super nifty way

```js
var colors = require('@colors/colors');

console.log('hello'.green); // outputs green text
console.log('i like cake and pies'.underline.red); // outputs red underlined text
console.log('inverse the color'.inverse); // inverses the color
console.log('OMG Rainbows!'.rainbow); // rainbow
console.log('Run the trap'.trap); // Drops the bass

```

or a slightly less nifty way which doesn't extend `String.prototype`

```js
var colors = require('@colors/colors/safe');

console.log(colors.green('hello')); // outputs green text
console.log(colors.red.underline('i like cake and pies')); // outputs red underlined text
console.log(colors.inverse('inverse the color')); // inverses the color
console.log(colors.rainbow('OMG Rainbows!')); // rainbow
console.log(colors.trap('Run the trap')); // Drops the bass

```

I prefer the first way. Some people seem to be afraid of extending `String.prototype` and prefer the second way. 

If you are writing good code you will never have an issue with the first approach. If you really don't want to touch `String.prototype`, the second usage will not touch `String` native object.

## Enabling/Disabling Colors

The package will auto-detect whether your terminal can use colors and enable/disable accordingly. When colors are disabled, the color functions do nothing. You can override this with a command-line flag:

```bash
node myapp.js --no-color
node myapp.js --color=false

node myapp.js --color
node myapp.js --color=true
node myapp.js --color=always

FORCE_COLOR=1 node myapp.js
```

Or in code:

```javascript
var colors = require('@colors/colors');
colors.enable();
colors.disable();
```

## Console.log [string substitution](http://nodejs.org/docs/latest/api/console.html#console_console_log_data)

```js
var name = 'Beowulf';
console.log(colors.green('Hello %s'), name);
// outputs -> 'Hello Beowulf'
```

## Custom themes

### Using standard API

```js

var colors = require('@colors/colors');

colors.setTheme({
  silly: 'rainbow',
  input: 'grey',
  verbose: 'cyan',
  prompt: 'grey',
  info: 'green',
  data: 'grey',
  help: 'cyan',
  warn: 'yellow',
  debug: 'blue',
  error: 'red'
});

// outputs red text
console.log("this is an error".error);

// outputs yellow text
console.log("this is a warning".warn);
```

### Using string safe API

```js
var colors = require('@colors/colors/safe');

// set single property
var error = colors.red;
error('this is red');

// set theme
colors.setTheme({
  silly: 'rainbow',
  input: 'grey',
  verbose: 'cyan',
  prompt: 'grey',
  info: 'green',
  data: 'grey',
  help: 'cyan',
  warn: 'yellow',
  debug: 'blue',
  error: 'red'
});

// outputs red text
console.log(colors.error("this is an error"));

// outputs yellow text
console.log(colors.warn("this is a warning"));

```

### Combining Colors

```javascript
var colors = require('@colors/colors');

colors.setTheme({
  custom: ['red', 'underline']
});

console.log('test'.custom);
```

*Protip: There is a secret undocumented style in `colors`. If you find the style you can summon him.*


---

# Changes to Cascade Layer Name Parser

### 2.0.4

_November 1, 2024_

- Updated [`@csstools/css-tokenizer`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-tokenizer) to [`3.0.3`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-tokenizer/CHANGELOG.md#303) (patch)
- Updated [`@csstools/css-parser-algorithms`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-parser-algorithms) to [`3.0.4`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-parser-algorithms/CHANGELOG.md#304) (patch)

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/packages/cascade-layer-name-parser/CHANGELOG.md)


---

The MIT License (MIT)

Copyright 2022 Romain Menke, Antonio Laguna <antonio@laguna.es>

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


---

# Cascade Layer Name Parser

[<img alt="npm version" src="https://img.shields.io/npm/v/@csstools/cascade-layer-name-parser.svg" height="20">][npm-url]
[<img alt="Build Status" src="https://github.com/csstools/postcss-plugins/workflows/test/badge.svg" height="20">][cli-url]
[<img alt="Discord" src="https://shields.io/badge/Discord-5865F2?logo=discord&logoColor=white">][discord]

## Usage

Add [Cascade Layer Name Parser] to your project:

```bash
npm install @csstools/cascade-layer-name-parser @csstools/css-parser-algorithms @csstools/css-tokenizer --save-dev
```

[Cascade Layer Name Parser] depends on our CSS tokenizer and parser algorithms.
It must be used together with `@csstools/css-tokenizer` and `@csstools/css-parser-algorithms`.

```ts
import { parse } from '@csstools/cascade-layer-name-parser';

const layerNames = parse('layer-name, foo.bar');
layerNames.forEach((layerName) => {
	console.log(layerName.name()) // "foo.bar"
	console.log(layerName.segments()) // ["foo", "bar"]
});
```

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/cascade-layer-name-parser

[Cascade Layer Name Parser]: https://github.com/csstools/postcss-plugins/tree/main/packages/cascade-layer-name-parser


---

# Changes to Color Helpers

### 5.0.2

_February 23, 2025_

- Use `Number.isNaN` instead of `NaN` for consistency.

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/packages/color-helpers/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# Color Helpers <img src="https://cssdb.org/images/css.svg" alt="for CSS" width="90" height="90" align="right">

[<img alt="npm version" src="https://img.shields.io/npm/v/@csstools/color-helpers.svg" height="20">][npm-url]
[<img alt="Build Status" src="https://github.com/csstools/postcss-plugins/workflows/test/badge.svg" height="20">][cli-url]
[<img alt="Discord" src="https://shields.io/badge/Discord-5865F2?logo=discord&logoColor=white">][discord]

## Usage

Add [Color Helpers] to your project:

```bash
npm install @csstools/color-helpers --save-dev
```

This package exists to join all the different color functions scattered among the Colors 4 and Colors 5 plugins we maintain such as:

* [PostCSS Color Function]
* [PostCSS Lab Function]
* [PostCSS OKLab Function]

## Copyright

This software or document includes material copied from or derived from https://github.com/w3c/csswg-drafts/tree/main/css-color-4. Copyright © 2022 W3C® (MIT, ERCIM, Keio, Beihang).

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/color-helpers

[Color Helpers]: https://github.com/csstools/postcss-plugins/tree/main/packages/color-helpers
[PostCSS Color Function]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-color-function
[PostCSS Lab Function]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-lab-functionw
[PostCSS OKLab Function]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-oklab-function


---

# Changes to CSS Calc

### 2.1.2

_February 23, 2025_

- Update `random()` to correctly handle extremely large ranges or extremely tiny steps.

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/packages/css-calc/CHANGELOG.md)


---

The MIT License (MIT)

Copyright 2022 Romain Menke, Antonio Laguna <antonio@laguna.es>

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


---

# CSS Calc <img src="https://cssdb.org/images/css.svg" alt="for CSS" width="90" height="90" align="right">

[<img alt="npm version" src="https://img.shields.io/npm/v/@csstools/css-calc.svg" height="20">][npm-url]
[<img alt="Build Status" src="https://github.com/csstools/postcss-plugins/workflows/test/badge.svg" height="20">][cli-url]
[<img alt="Discord" src="https://shields.io/badge/Discord-5865F2?logo=discord&logoColor=white">][discord]

Implemented from : https://drafts.csswg.org/css-values-4/ on 2023-02-17

## Usage

Add [CSS calc] to your project:

```bash
npm install @csstools/css-calc @csstools/css-parser-algorithms @csstools/css-tokenizer --save-dev
```

### With string values :

```mjs
import { calc } from '@csstools/css-calc';

// '20'
console.log(calc('calc(10 * 2)'));
```

### With component values :

```mjs
import { stringify, tokenizer } from '@csstools/css-tokenizer';
import { parseCommaSeparatedListOfComponentValues } from '@csstools/css-parser-algorithms';
import { calcFromComponentValues } from '@csstools/css-calc';

const t = tokenizer({
	css: 'calc(10 * 2)',
});

const tokens = [];

{
	while (!t.endOfFile()) {
		tokens.push(t.nextToken());
	}

	tokens.push(t.nextToken()); // EOF-token
}

const result = parseCommaSeparatedListOfComponentValues(tokens, {});

// filter or mutate the component values

const calcResult = calcFromComponentValues(result, { precision: 5, toCanonicalUnits: true });

// filter or mutate the component values even further

const calcResultStr = calcResult.map((componentValues) => {
	return componentValues.map((x) => stringify(...x.tokens())).join('');
}).join(',');

// '20'
console.log(calcResultStr);
```

### Options

#### `precision` :

The default precision is fairly high.
It aims to be high enough to make rounding unnoticeable in the browser.

You can set it to a lower number to suit your needs.

```mjs
import { calc } from '@csstools/css-calc';

// '0.3'
console.log(calc('calc(1 / 3)', { precision: 1 }));
// '0.33'
console.log(calc('calc(1 / 3)', { precision: 2 }));
```

#### `globals` :

Pass global values as a map of key value pairs.

> Example : Relative color syntax (`lch(from pink calc(l / 2) c h)`) exposes color channel information as ident tokens.
> By passing globals for `l`, `c` and `h` it is possible to solve nested `calc()`'s.

```mjs
import { calc } from '@csstools/css-calc';

const globals = new Map([
	['a', '10px'],
	['b', '2rem'],
]);

// '20px'
console.log(calc('calc(a * 2)', { globals: globals }));
// '6rem'
console.log(calc('calc(b * 3)', { globals: globals }));
```

#### `toCanonicalUnits` :

By default this package will try to preserve units.
The heuristic to do this is very simplistic.
We take the first unit we encounter and try to convert other dimensions to that unit.

This better matches what users expect from a CSS dev tool.

If you want to have outputs that are closes to CSS serialized values you can pass `toCanonicalUnits: true`.

```mjs
import { calc } from '@csstools/css-calc';

// '20hz'
console.log(calc('calc(0.01khz + 10hz)', { toCanonicalUnits: true }));

// '20hz'
console.log(calc('calc(10hz + 0.01khz)', { toCanonicalUnits: true }));

// '0.02khz' !!!
console.log(calc('calc(0.01khz + 10hz)', { toCanonicalUnits: false }));

// '20hz'
console.log(calc('calc(10hz + 0.01khz)', { toCanonicalUnits: false }));
```

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/css-calc

[CSS calc]: https://github.com/csstools/postcss-plugins/tree/main/packages/css-calc


---

# Changes to CSS Color Parser

### 3.0.8

_February 23, 2025_

- Use `Number.isNaN` instead of `NaN` for consistency.
- Updated [`@csstools/color-helpers`](https://github.com/csstools/postcss-plugins/tree/main/packages/color-helpers) to [`5.0.2`](https://github.com/csstools/postcss-plugins/tree/main/packages/color-helpers/CHANGELOG.md#502) (patch)
- Updated [`@csstools/css-calc`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-calc) to [`2.1.2`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-calc/CHANGELOG.md#212) (patch)

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/packages/css-color-parser/CHANGELOG.md)


---

The MIT License (MIT)

Copyright 2022 Romain Menke, Antonio Laguna <antonio@laguna.es>

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


---

# CSS Color Parser <img src="https://cssdb.org/images/css.svg" alt="for CSS" width="90" height="90" align="right">

[<img alt="npm version" src="https://img.shields.io/npm/v/@csstools/css-color-parser.svg" height="20">][npm-url]
[<img alt="Build Status" src="https://github.com/csstools/postcss-plugins/workflows/test/badge.svg" height="20">][cli-url]
[<img alt="Discord" src="https://shields.io/badge/Discord-5865F2?logo=discord&logoColor=white">][discord]

## Usage

Add [CSS Color Parser] to your project:

```bash
npm install @csstools/css-color-parser @csstools/css-parser-algorithms @csstools/css-tokenizer --save-dev
```

```ts
import { color } from '@csstools/css-color-parser';
import { isFunctionNode, parseComponentValue } from '@csstools/css-parser-algorithms';
import { serializeRGB } from '@csstools/css-color-parser';
import { tokenize } from '@csstools/css-tokenizer';

// color() expects a parsed component value.
const hwbComponentValue = parseComponentValue(tokenize({ css: 'hwb(10deg 10% 20%)' }));
const colorData = color(hwbComponentValue);
if (colorData) {
	console.log(colorData);

	// serializeRGB() returns a component value.
	const rgbComponentValue = serializeRGB(colorData);
	console.log(rgbComponentValue.toString());
}
```

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/css-color-parser

[CSS Color Parser]: https://github.com/csstools/postcss-plugins/tree/main/packages/css-color-parser


---

# Changes to CSS Parser Algorithms

### 3.0.4

_November 1, 2024_

- Updated [`@csstools/css-tokenizer`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-tokenizer) to [`3.0.3`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-tokenizer/CHANGELOG.md#303) (patch)

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/packages/css-parser-algorithms/CHANGELOG.md)


---

The MIT License (MIT)

Copyright 2022 Romain Menke, Antonio Laguna <antonio@laguna.es>

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


---

# CSS Parser Algorithms

[<img alt="npm version" src="https://img.shields.io/npm/v/@csstools/css-parser-algorithms.svg" height="20">][npm-url]
[<img alt="Build Status" src="https://github.com/csstools/postcss-plugins/workflows/test/badge.svg" height="20">][cli-url]
[<img alt="Discord" src="https://shields.io/badge/Discord-5865F2?logo=discord&logoColor=white">][discord]

Implemented from : https://www.w3.org/TR/2021/CRD-css-syntax-3-20211224/

## API

[Read the API docs](./docs/css-parser-algorithms.md)

## Usage

Add [CSS Parser Algorithms] to your project:

```bash
npm install @csstools/css-parser-algorithms @csstools/css-tokenizer --save-dev
```

[CSS Parser Algorithms] only accepts tokenized CSS.
It must be used together with `@csstools/css-tokenizer`.


```js
import { tokenizer, TokenType } from '@csstools/css-tokenizer';
import { parseComponentValue } from '@csstools/css-parser-algorithms';

const myCSS =  `@media only screen and (min-width: 768rem) {
	.foo {
		content: 'Some content!' !important;
	}
}
`;

const t = tokenizer({
	css: myCSS,
});

const tokens = [];

{
	while (!t.endOfFile()) {
		tokens.push(t.nextToken());
	}

	tokens.push(t.nextToken()); // EOF-token
}

const options = {
	onParseError: ((err) => {
		throw err;
	}),
};

const result = parseComponentValue(tokens, options);

console.log(result);
```

### Available functions

- [`parseComponentValue`](https://www.w3.org/TR/css-syntax-3/#parse-component-value)
- [`parseListOfComponentValues`](https://www.w3.org/TR/css-syntax-3/#parse-list-of-component-values)
- [`parseCommaSeparatedListOfComponentValues`](https://www.w3.org/TR/css-syntax-3/#parse-comma-separated-list-of-component-values)

### Utilities

#### `gatherNodeAncestry`

The AST does not expose the entire ancestry of each node.
The walker methods do provide access to the current parent, but also not the entire ancestry.

To gather the entire ancestry for a a given sub tree of the AST you can use `gatherNodeAncestry`.
The result is a `Map` with the child nodes as keys and the parents as values.
This allows you to lookup any ancestor of any node.

```js
import { parseComponentValue } from '@csstools/css-parser-algorithms';

const result = parseComponentValue(tokens, options);
const ancestry = gatherNodeAncestry(result);
```

### Options

```ts
{
	onParseError?: (error: ParseError) => void
}
```

#### `onParseError`

The parser algorithms are forgiving and won't stop when a parse error is encountered.
Parse errors also aren't tokens.

To receive parsing error information you can set a callback.

Parser errors will try to inform you about the point in the parsing logic the error happened.
This tells you the kind of error.

## Goals and non-goals

Things this package aims to be:
- specification compliant CSS parser
- a reliable low level package to be used in CSS sub-grammars

What it is not:
- opinionated
- fast
- small
- a replacement for PostCSS (PostCSS is fast and also an ecosystem)

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/css-parser-algorithms

[CSS Parser Algorithms]: https://github.com/csstools/postcss-plugins/tree/main/packages/css-parser-algorithms


---

# Changes to CSS Tokenizer

### 3.0.3

_October 25, 2024_

- Fix input preprocessing

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/packages/css-tokenizer/CHANGELOG.md)


---

The MIT License (MIT)

Copyright 2022 Romain Menke, Antonio Laguna <antonio@laguna.es>

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


---

# CSS Tokenizer

[<img alt="npm version" src="https://img.shields.io/npm/v/@csstools/css-tokenizer.svg" height="20">][npm-url]
[<img alt="Build Status" src="https://github.com/csstools/postcss-plugins/workflows/test/badge.svg" height="20">][cli-url]
[<img alt="Discord" src="https://shields.io/badge/Discord-5865F2?logo=discord&logoColor=white">][discord]

Implemented from : https://www.w3.org/TR/2021/CRD-css-syntax-3-20211224/

## API

[Read the API docs](./docs/css-tokenizer.md)

## Usage

Add [CSS Tokenizer] to your project:

```bash
npm install @csstools/css-tokenizer --save-dev
```

```js
import { tokenizer, TokenType } from '@csstools/css-tokenizer';

const myCSS = `@media only screen and (min-width: 768rem) {
	.foo {
		content: 'Some content!' !important;
	}
}
`;

const t = tokenizer({
	css: myCSS,
});

while (true) {
	const token = t.nextToken();
	if (token[0] === TokenType.EOF) {
		break;
	}

	console.log(token);
}
```

Or use the `tokenize` helper function:

```js
import { tokenize } from '@csstools/css-tokenizer';

const myCSS =  `@media only screen and (min-width: 768rem) {
	.foo {
		content: 'Some content!' !important;
	}
}
`;

const tokens = tokenize({
	css: myCSS,
});

console.log(tokens);
```

### Options

```ts
{
	onParseError?: (error: ParseError) => void
}
```

#### `onParseError`

The tokenizer is forgiving and won't stop when a parse error is encountered.

To receive parsing error information you can set a callback.

```js
import { tokenizer, TokenType } from '@csstools/css-tokenizer';

const t = tokenizer({
	css: '\\',
}, { onParseError: (err) => console.warn(err) });

while (true) {
	const token = t.nextToken();
	if (token[0] === TokenType.EOF) {
		break;
	}
}
```

Parser errors will try to inform you where in the tokenizer logic the error happened.
This tells you what kind of error occurred.

## Goals and non-goals

Things this package aims to be:
- specification compliant CSS tokenizer
- a reliable low level package to be used in CSS parsers

What it is not:
- opinionated
- fast
- small

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/css-tokenizer

[CSS Tokenizer]: https://github.com/csstools/postcss-plugins/tree/main/packages/css-tokenizer


---

# Changes to Media Query List Parser

### 4.0.2

_November 1, 2024_

- Updated [`@csstools/css-tokenizer`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-tokenizer) to [`3.0.3`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-tokenizer/CHANGELOG.md#303) (patch)
- Updated [`@csstools/css-parser-algorithms`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-parser-algorithms) to [`3.0.4`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-parser-algorithms/CHANGELOG.md#304) (patch)

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/packages/media-query-list-parser/CHANGELOG.md)


---

The MIT License (MIT)

Copyright 2022 Romain Menke, Antonio Laguna <antonio@laguna.es>

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


---

# Media Query List Parser

[<img alt="npm version" src="https://img.shields.io/npm/v/@csstools/media-query-list-parser.svg" height="20">][npm-url]
[<img alt="Build Status" src="https://github.com/csstools/postcss-plugins/workflows/test/badge.svg" height="20">][cli-url]
[<img alt="Discord" src="https://shields.io/badge/Discord-5865F2?logo=discord&logoColor=white">][discord]

Implemented from : https://www.w3.org/TR/mediaqueries-5/

## Usage

Add [Media Query List Parser] to your project:

```bash
npm install @csstools/media-query-list-parser @csstools/css-parser-algorithms @csstools/css-tokenizer --save-dev
```

[Media Query List Parser] depends on our CSS tokenizer and parser algorithms.
It must be used together with `@csstools/css-tokenizer` and `@csstools/css-parser-algorithms`.

```ts
import { parse } from '@csstools/media-query-list-parser';

export function parseCustomMedia() {
	const mediaQueryList = parse('screen and (min-width: 300px), (50px < height < 30vw)');

	mediaQueryList.forEach((mediaQuery) => {
		mediaQuery.walk((entry, index) => {
			// Index of the current Node in `parent`.
			console.log(index);
			// Type of `parent`.
			console.log(entry.parent.type);

			// Type of `node`
			{
				// Sometimes nodes can be arrays.
				if (Array.isArray(entry.node)) {
					entry.node.forEach((item) => {
						console.log(item.type);
					});
				}

				if ('type' in entry.node) {
					console.log(entry.node.type);
				}
			}

			// stringified version of the current node.
			console.log(entry.node.toString());

			// Return `false` to stop the walker.
			return false;
		});
	});
}
```

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/media-query-list-parser

[Media Query List Parser]: https://github.com/csstools/postcss-plugins/tree/main/packages/media-query-list-parser


---

# Changes to PostCSS Cascade Layers

### 5.0.1

_October 23, 2024_

- Updated: `postcss-selector-parser`
- Updated [`@csstools/selector-specificity`](https://github.com/csstools/postcss-plugins/tree/main/packages/selector-specificity) to [`5.0.0`](https://github.com/csstools/postcss-plugins/tree/main/packages/selector-specificity/CHANGELOG.md#500) (major)

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-cascade-layers/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Cascade Layers [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install @csstools/postcss-cascade-layers --save-dev`

[PostCSS Cascade Layers] lets you use `@layer` following the [Cascade Layers Specification]. For more information on layers, checkout [A Complete Guide to CSS Cascade Layers] by Miriam Suzanne.

```pcss

target {
	color: purple;
}

@layer {
	target {
		color: green;
	}
}


/* becomes */


target:not(#\#) {
	color: purple;
}

target {
		color: green;
	}

```

## How it works

[PostCSS Cascade Layers] creates "layers" of specificity.

It applies extra specificity on all your styles based on :
- the most specific selector found
- the order in which layers are defined

```css
@layer A, B;

@layer B {
	.a-less-specific-selector {
		/* styles */
	}
}

@layer A {
	#something #very-specific {
		/* styles */
	}
}

@layer C {
	.a-less-specific-selector {
		/* styles */
	}
}
```

most specific selector :
- `#something #very-specific`
- `[2, 0, 0]`
- `2 + 1` -> `3` to ensure there is no overlap

the order in which layers are defined :
- `A`
- `B`
- `C`

| layer | previous adjustment | specificity adjustment | selector |
| ------ | ------ | ----------- | --- |
| `A` | `0` | `0 + 0 = 0` | N/A |
| `B` | `0` | `0 + 3 = 3` | `:not(#\#):not(#\#):not(#\#)` |
| `C` | `3` | `3 + 3 = 6` | `:not(#\#):not(#\#):not(#\#):not(#\#):not(#\#):not(#\#)` |

This approach lets more important (later) layers always override less important (earlier) layers.<br>
And layers have enough room internally so that each selector works and overrides as expected.

More layers with more specificity will cause longer `:not(...)` selectors to be generated.

> [!IMPORTANT]
> [PostCSS Cascade Layers] assumes to process your complete CSS bundle.<br>If your build tool processes files individually or processes files in parallel the output will be incorrect.<br>Using [`@csstools/postcss-bundler`](https://github.com/csstools/postcss-plugins/tree/main/plugin-packs/postcss-bundler) and `@import` statements is one way to make sure your CSS is bundled before it is processed by this plugin.


## Usage

Add [PostCSS Cascade Layers] to your project:

```bash
npm install postcss @csstools/postcss-cascade-layers --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssCascadeLayers = require('@csstools/postcss-cascade-layers');

postcss([
	postcssCascadeLayers(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## Options

### onRevertLayerKeyword

The `onRevertLayerKeyword` option enables warnings if `revert-layer` is used.
Transforming `revert-layer` for older browsers is not possible in this plugin.

Defaults to `warn`

```js
postcssCascadeLayers({ onRevertLayerKeyword: 'warn' }) // 'warn' | false
```

```pcss
/* [postcss-cascade-layers]: handling "revert-layer" is unsupported by this plugin and will cause style differences between browser versions. */
@layer {
	.foo {
		color: revert-layer;
	}
}
```

### onConditionalRulesChangingLayerOrder

The `onConditionalRulesChangingLayerOrder` option enables warnings if layers are declared in multiple different orders in conditional rules.
Transforming these layers correctly for older browsers is not possible in this plugin.

Defaults to `warn`

```js
postcssCascadeLayers({ onConditionalRulesChangingLayerOrder: 'warn' }) // 'warn' | false
```

```pcss
/* [postcss-cascade-layers]: handling different layer orders in conditional rules is unsupported by this plugin and will cause style differences between browser versions. */
@media (min-width: 10px) {
	@layer B {
		.foo {
			color: red;
		}
	}
}

@layer A {
	.foo {
		color: pink;
	}
}

@layer B {
	.foo {
		color: red;
	}
}
```

### onImportLayerRule

The `@import` at-rule can also be used with cascade layers, specifically to create a new layer like so: 
```css
@import 'theme.css' layer(utilities);
```
If your CSS uses `@import` with layers, you will also need the [postcss-import] plugin. This plugin alone will not handle the `@import` at-rule.  

This plugin will warn you when it detects that [postcss-import] did not transform`@import` at-rules.

```js
postcssCascadeLayers({ onImportLayerRule: 'warn' }) // 'warn' | false
```

### Contributors
The contributors to this plugin were [Olu Niyi-Awosusi] and [Sana Javed] from [Oddbird] and Romain Menke.

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#cascade-layers
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/postcss-cascade-layers

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Cascade Layers]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-cascade-layers
[Cascade Layers Specification]: https://www.w3.org/TR/css-cascade-5/#layering
[A Complete Guide to CSS Cascade Layers]: https://css-tricks.com/css-cascade-layers/
[Olu Niyi-Awosusi]: https://github.com/oluoluoxenfree
[Sana Javed]: https://github.com/sanajaved7
[Oddbird]: https://github.com/oddbird
[postcss-import]: https://github.com/postcss/postcss-import


---

# Changes to Selector Specificity

### 5.0.0

_October 23, 2024_

- Updated: `postcss-selector-parser`

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/packages/selector-specificity/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# Selector Specificity

[<img alt="npm version" src="https://img.shields.io/npm/v/@csstools/selector-specificity.svg" height="20">][npm-url]
[<img alt="Build Status" src="https://github.com/csstools/postcss-plugins/workflows/test/badge.svg" height="20">][cli-url]
[<img alt="Discord" src="https://shields.io/badge/Discord-5865F2?logo=discord&logoColor=white">][discord]

## Usage

Add [Selector Specificity] to your project:

```bash
npm install @csstools/selector-specificity --save-dev
```

```js
import parser from 'postcss-selector-parser';
import { selectorSpecificity } from '@csstools/selector-specificity';

const selectorAST = parser().astSync('#foo:has(> .foo)');
const specificity = selectorSpecificity(selectorAST);

console.log(specificity.a); // 1
console.log(specificity.b); // 1
console.log(specificity.c); // 0
```

_`selectorSpecificity` takes a single selector, not a list of selectors (not : `a, b, c`).
To compare or otherwise manipulate lists of selectors you need to call `selectorSpecificity` on each part._

### Comparing

The package exports a utility function to compare two specificities.

```js
import { selectorSpecificity, compare } from '@csstools/selector-specificity';

const s1 = selectorSpecificity(ast1);
const s2 = selectorSpecificity(ast2);
compare(s1, s2); // -1 | 0 | 1
```

- if `s1 < s2` then `compare(s1, s2)` returns a negative number (`< 0`)
- if `s1 > s2` then `compare(s1, s2)` returns a positive number (`> 0`)
- if `s1 === s2` then `compare(s1, s2)` returns zero (`=== 0`)

## Prior Art

- [keeganstreet/specificity](https://github.com/keeganstreet/specificity)
- [bramus/specificity](https://github.com/bramus/specificity)

For CSSTools we always use `postcss-selector-parser` and want to calculate specificity from this AST.

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/selector-specificity

[Selector Specificity]: https://github.com/csstools/postcss-plugins/tree/main/packages/selector-specificity


---

# API Documentation

*Please use only this documented API when working with the parser. Methods
not documented here are subject to change at any point.*

## `parser` function

This is the module's main entry point.

```js
const parser = require('postcss-selector-parser');
```

### `parser([transform], [options])`

Creates a new `processor` instance

```js
const processor = parser();
```

Or, with optional transform function

```js
const transform = selectors => {
    selectors.walkUniversals(selector => {
        selector.remove();
    });
};

const processor = parser(transform)

// Example
const result = processor.processSync('*.class');
// => .class
```

[See processor documentation](#processor)

Arguments:

* `transform (function)`: Provide a function to work with the parsed AST.
* `options (object)`: Provide default options for all calls on the returned `Processor`.

### `parser.attribute([props])`

Creates a new attribute selector.

```js
parser.attribute({attribute: 'href'});
// => [href]
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.className([props])`

Creates a new class selector.

```js
parser.className({value: 'button'});
// => .button
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.combinator([props])`

Creates a new selector combinator.

```js
parser.combinator({value: '+'});
// => +
```

Arguments:

* `props (object)`: The new node's properties.

Notes:
* **Descendant Combinators** The value of descendant combinators created by the
  parser always just a single space (`" "`). For descendant selectors with no
  comments, additional space is now stored in `node.spaces.before`. Depending
  on the location of comments, additional spaces may be stored in
  `node.raws.spaces.before`, `node.raws.spaces.after`, or `node.raws.value`.
* **Named Combinators** Although, nonstandard and unlikely to ever become a standard,
  named combinators like `/deep/` and `/for/` are parsed as combinators. The
  `node.value` is name after being unescaped and normalized as lowercase. The
  original value for the combinator name is stored in `node.raws.value`.


### `parser.comment([props])`

Creates a new comment.

```js
parser.comment({value: '/* Affirmative, Dave. I read you. */'});
// => /* Affirmative, Dave. I read you. */
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.id([props])`

Creates a new id selector.

```js
parser.id({value: 'search'});
// => #search
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.nesting([props])`

Creates a new nesting selector.

```js
parser.nesting();
// => &
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.pseudo([props])`

Creates a new pseudo selector.

```js
parser.pseudo({value: '::before'});
// => ::before
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.root([props])`

Creates a new root node.

```js
parser.root();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.selector([props])`

Creates a new selector node.

```js
parser.selector();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.string([props])`

Creates a new string node.

```js
parser.string();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.tag([props])`

Creates a new tag selector.

```js
parser.tag({value: 'button'});
// => button
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.universal([props])`

Creates a new universal selector.

```js
parser.universal();
// => *
```

Arguments:

* `props (object)`: The new node's properties.

## Node types

### `node.type`

A string representation of the selector type. It can be one of the following;
`attribute`, `class`, `combinator`, `comment`, `id`, `nesting`, `pseudo`,
`root`, `selector`, `string`, `tag`, or `universal`. Note that for convenience,
these constants are exposed on the main `parser` as uppercased keys. So for
example you can get `id` by querying `parser.ID`.

```js
parser.attribute({attribute: 'href'}).type;
// => 'attribute'
```

### `node.parent`

Returns the parent node.

```js
root.nodes[0].parent === root;
```

### `node.toString()`, `String(node)`, or `'' + node`

Returns a string representation of the node.

```js
const id = parser.id({value: 'search'});
console.log(String(id));
// => #search
```

### `node.next()` & `node.prev()`

Returns the next/previous child of the parent node.

```js
const next = id.next();
if (next && next.type !== 'combinator') {
    throw new Error('Qualified IDs are not allowed!');
}
```

### `node.replaceWith(node[,...nodeN])`

Replace a node with another.

```js
const attr = selectors.first.first;
const className = parser.className({value: 'test'});
attr.replaceWith(className);
```

Arguments:

* `node`: The node to substitute the original with.
...
* `nodeN`: The node to substitute the original with.

### `node.remove()`

Removes the node from its parent node.

```js
if (node.type === 'id') {
    node.remove();
}
```

### `node.clone([opts])`

Returns a copy of a node, detached from any parent containers that the
original might have had.

```js
const cloned = node.clone();
```

### `node.isAtPosition(line, column)`

Return a `boolean` indicating whether this node includes the character at the
position of the given line and column. Returns `undefined` if the nodes lack
sufficient source metadata to determine the position.

Arguments:

* `line`: 1-index based line number relative to the start of the selector.
* `column`: 1-index based column number relative to the start of the selector.

### `node.spaces`

Extra whitespaces around the node will be moved into `node.spaces.before` and
`node.spaces.after`. So for example, these spaces will be moved as they have
no semantic meaning:

```css
      h1     ,     h2   {}
```

For descendent selectors, the value is always a single space.

```css
h1        h2 {}
```

Additional whitespace is found in either the `node.spaces.before` and `node.spaces.after` depending on the presence of comments or other whitespace characters. If the actual whitespace does not start or end with a single space, the node's raw value is set to the actual space(s) found in the source.

### `node.source`

An object describing the node's start/end, line/column source position.

Within the following CSS, the `.bar` class node ...

```css
.foo,
  .bar {}
```

... will contain the following `source` object.

```js
source: {
    start: {
        line: 2,
        column: 3
    },
    end: {
        line: 2,
        column: 6
    }
}
```

### `node.sourceIndex`

The zero-based index of the node within the original source string.

Within the following CSS, the `.baz` class node will have a `sourceIndex` of `12`.

```css
.foo, .bar, .baz {}
```

## Container types

The `root`, `selector`, and `pseudo` nodes have some helper methods for working
with their children.

### `container.nodes`

An array of the container's children.

```js
// Input: h1 h2
selectors.at(0).nodes.length   // => 3
selectors.at(0).nodes[0].value // => 'h1'
selectors.at(0).nodes[1].value // => ' '
```

### `container.first` & `container.last`

The first/last child of the container.

```js
selector.first === selector.nodes[0];
selector.last === selector.nodes[selector.nodes.length - 1];
```

### `container.at(index)`

Returns the node at position `index`.

```js
selector.at(0) === selector.first;
selector.at(0) === selector.nodes[0];
```

Arguments:

* `index`: The index of the node to return.

### `container.atPosition(line, column)`

Returns the node at the source position `line` and `column`.

```js
// Input: :not(.foo),\n#foo > :matches(ol, ul)
selector.atPosition(1, 1); // => :not(.foo)
selector.atPosition(2, 1); // => \n#foo
```

Arguments:

* `line`: The line number of the node to return.
* `column`: The column number of the node to return.

### `container.index(node)`

Return the index of the node within its container.

```js
selector.index(selector.nodes[2]) // => 2
```

Arguments:

* `node`: A node within the current container.

### `container.length`

Proxy to the length of the container's nodes.

```js
container.length === container.nodes.length
```

### `container` Array iterators

The container class provides proxies to certain Array methods; these are:

* `container.map === container.nodes.map`
* `container.reduce === container.nodes.reduce`
* `container.every === container.nodes.every`
* `container.some === container.nodes.some`
* `container.filter === container.nodes.filter`
* `container.sort === container.nodes.sort`

Note that these methods only work on a container's immediate children; recursive
iteration is provided by `container.walk`.

### `container.each(callback)`

Iterate the container's immediate children, calling `callback` for each child.
You may return `false` within the callback to break the iteration.

```js
let className;
selectors.each((selector, index) => {
    if (selector.type === 'class') {
        className = selector.value;
        return false;
    }
});
```

Note that unlike `Array#forEach()`, this iterator is safe to use whilst adding
or removing nodes from the container.

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  and `index` arguments.

### `container.walk(callback)`

Like `container#each`, but will also iterate child nodes as long as they are
`container` types.

```js
selectors.walk((selector, index) => {
    // all nodes
});
```

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  and `index` arguments.

This iterator is safe to use whilst mutating `container.nodes`,
like `container#each`.

### `container.walk` proxies

The container class provides proxy methods for iterating over types of nodes,
so that it is easier to write modules that target specific selectors. Those
methods are:

* `container.walkAttributes`
* `container.walkClasses`
* `container.walkCombinators`
* `container.walkComments`
* `container.walkIds`
* `container.walkNesting`
* `container.walkPseudos`
* `container.walkTags`
* `container.walkUniversals`

### `container.split(callback)`

This method allows you to split a group of nodes by returning `true` from
a callback. It returns an array of arrays, where each inner array corresponds
to the groups that you created via the callback.

```js
// (input) => h1 h2>>h3
const list = selectors.first.split(selector => {
    return selector.type === 'combinator';
});

// (node values) => [['h1', ' '], ['h2', '>>'], ['h3']]
```

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  as an argument.

### `container.prepend(node)` & `container.append(node)`

Add a node to the start/end of the container. Note that doing so will set
the parent property of the node to this container.

```js
const id = parser.id({value: 'search'});
selector.append(id);
```

Arguments:

* `node`: The node to add.

### `container.insertBefore(old, new[, ...newNodes])` & `container.insertAfter(old, new[, ...newNodes])`

Add a node before or after an existing node in a container:

```js
selectors.walk(selector => {
    if (selector.type !== 'class') {
        const className = parser.className({value: 'theme-name'});
        selector.parent.insertAfter(selector, className);
    }
});
```

Arguments:

* `old`: The existing node in the container.
* `new`: The new node to add before/after the existing node.

### `container.removeChild(node)`

Remove the node from the container. Note that you can also use
`node.remove()` if you would like to remove just a single node.

```js
selector.length // => 2
selector.remove(id)
selector.length // => 1;
id.parent       // undefined
```

Arguments:

* `node`: The node to remove.

### `container.removeAll()` or `container.empty()`

Remove all children from the container.

```js
selector.removeAll();
selector.length // => 0
```

## Root nodes

A root node represents a comma separated list of selectors. Indeed, all
a root's `toString()` method does is join its selector children with a ','.
Other than this, it has no special functionality and acts like a container.

### `root.trailingComma`

This will be set to `true` if the input has a trailing comma, in order to
support parsing of legacy CSS hacks.

## Selector nodes

A selector node represents a single complex selector. For example, this
selector string `h1 h2 h3, [href] > p`, is represented as two selector nodes.
It has no special functionality of its own.

## Pseudo nodes

A pseudo selector extends a container node; if it has any parameters of its
own (such as `h1:not(h2, h3)`), they will be its children. Note that the pseudo
`value` will always contain the colons preceding the pseudo identifier. This
is so that both `:before` and `::before` are properly represented in the AST.

## Attribute nodes

### `attribute.quoted`

Returns `true` if the attribute's value is wrapped in quotation marks, false if it is not.
Remains `undefined` if there is no attribute value.

```css
[href=foo] /* false */
[href='foo'] /* true */
[href="foo"] /* true */
[href] /* undefined */
```

### `attribute.qualifiedAttribute`

Returns the attribute name qualified with the namespace if one is given.

### `attribute.offsetOf(part)`

 Returns the offset of the attribute part specified relative to the
 start of the node of the output string. This is useful in raising
 error messages about a specific part of the attribute, especially
 in combination with `attribute.sourceIndex`.

 Returns `-1` if the name is invalid or the value doesn't exist in this
 attribute.

 The legal values for `part` are:

 * `"ns"` - alias for "namespace"
 * `"namespace"` - the namespace if it exists.
 * `"attribute"` - the attribute name
 * `"attributeNS"` - the start of the attribute or its namespace
 * `"operator"` - the match operator of the attribute
 * `"value"` - The value (string or identifier)
 * `"insensitive"` - the case insensitivity flag

### `attribute.raws.unquoted`

Returns the unquoted content of the attribute's value.
Remains `undefined` if there is no attribute value.

```css
[href=foo] /* foo */
[href='foo'] /* foo */
[href="foo"] /* foo */
[href] /* undefined */
```

### `attribute.spaces`

Like `node.spaces` with the `before` and `after` values containing the spaces
around the element, the parts of the attribute can also have spaces before
and after them. The for each of `attribute`, `operator`, `value` and
`insensitive` there is corresponding property of the same nam in
`node.spaces` that has an optional `before` or `after` string containing only
whitespace.

Note that corresponding values in `attributes.raws.spaces` contain values
including any comments. If set, these values will override the
`attribute.spaces` value. Take care to remove them if changing
`attribute.spaces`.

### `attribute.raws`

The raws object stores comments and other information necessary to re-render
the node exactly as it was in the source.

If a comment is embedded within the identifiers for the `namespace`, `attribute`
or `value` then a property is placed in the raws for that value containing the full source of the propery including comments.

If a comment is embedded within the space between parts of the attribute
then the raw for that space is set accordingly.

Setting an attribute's property `raws` value to be deleted.

For now, changing the spaces required also updating or removing any of the
raws values that override them.

Example: `[ /*before*/ href /* after-attr */ = /* after-operator */ te/*inside-value*/st/* wow */ /*omg*/i/*bbq*/ /*whodoesthis*/]` would parse as:

```js
{
  attribute: "href",
  operator: "=",
  value: "test",
  spaces: {
    before: '',
    after: '',
    attribute: { before: '  ', after: '  ' },
    operator: { after: '  ' },
    value: { after: ' ' },
    insensitive: { after: ' ' }
  },
  raws: {
    spaces: {
      attribute: { before: ' /*before*/ ', after: ' /* after-attr */ ' },
      operator: { after: ' /* after-operator */ ' },
      value: { after: '/* wow */ /*omg*/' },
      insensitive: { after: '/*bbq*/ /*whodoesthis*/' }
    },
    unquoted: 'test',
    value: 'te/*inside-value*/st'
  }
}
```

## `Processor`

### `ProcessorOptions`

* `lossless` - When `true`, whitespace is preserved. Defaults to `true`.
* `updateSelector` - When `true`, if any processor methods are passed a postcss
  `Rule` node instead of a string, then that Rule's selector is updated
  with the results of the processing. Defaults to `true`.

### `process|processSync(selectors, [options])`

Processes the `selectors`, returning a string from the result of processing.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

**Example:**

```js
const parser = require("postcss-selector-parser");
const processor = parser();

let result = processor.processSync(' .class');
console.log(result);
// =>  .class

// Asynchronous operation
let promise = processor.process(' .class').then(result => {
    console.log(result)
    // => .class
});

// To have the parser normalize whitespace values, utilize the options
result = processor.processSync('  .class  ', {lossless: false});
console.log(result);
// => .class

// For better syntax errors, pass a PostCSS Rule node.
const postcss = require('postcss');
rule = postcss.rule({selector: ' #foo    > a,  .class  '});
processor.process(rule, {lossless: false, updateSelector: true}).then(result => {
    console.log(result);
    // => #foo>a,.class
    console.log("rule:", rule.selector);
    // => rule: #foo>a,.class
})
```

Arguments:

* `selectors (string|postcss.Rule)`: Either a selector string or a PostCSS Rule
  node.
* `[options] (object)`: Process options


### `ast|astSync(selectors, [options])`

Like `process()` and `processSync()` but after
processing the `selectors` these methods return the `Root` node of the result
instead of a string.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

### `transform|transformSync(selectors, [options])`

Like `process()` and `processSync()` but after
processing the `selectors` these methods return the value returned by the
processor callback.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

### Error Handling Within Selector Processors

The root node passed to the selector processor callback
has a method `error(message, options)` that returns an
error object. This method should always be used to raise
errors relating to the syntax of selectors. The options
to this method are passed to postcss's error constructor
([documentation](http://postcss.org/api/#container-error)).

#### Async Error Example

```js
let processor = (root) => {
    return new Promise((resolve, reject) => {
        root.walkClasses((classNode) => {
            if (/^(.*)[-_]/.test(classNode.value)) {
                let msg = "classes may not have underscores or dashes in them";
                reject(root.error(msg, {
                    index: classNode.sourceIndex + RegExp.$1.length + 1,
                    word: classNode.value
                }));
            }
        });
        resolve();
    });
};

const postcss = require("postcss");
const parser = require("postcss-selector-parser");
const selectorProcessor = parser(processor);
const plugin = postcss.plugin('classValidator', (options) => {
    return (root) => {
        let promises = [];
        root.walkRules(rule => {
            promises.push(selectorProcessor.process(rule));
        });
        return Promise.all(promises);
    };
});
postcss(plugin()).process(`
.foo-bar {
  color: red;
}
`.trim(), {from: 'test.css'}).catch((e) => console.error(e.toString()));

// CssSyntaxError: classValidator: ./test.css:1:5: classes may not have underscores or dashes in them
//
// > 1 | .foo-bar {
//     |     ^
//   2 |   color: red;
//   3 | }
```

#### Synchronous Error Example

```js
let processor = (root) => {
    root.walkClasses((classNode) => {
        if (/.*[-_]/.test(classNode.value)) {
            let msg = "classes may not have underscores or dashes in them";
            throw root.error(msg, {
                index: classNode.sourceIndex,
                word: classNode.value
            });
        }
    });
};

const postcss = require("postcss");
const parser = require("postcss-selector-parser");
const selectorProcessor = parser(processor);
const plugin = postcss.plugin('classValidator', (options) => {
    return (root) => {
        root.walkRules(rule => {
            selectorProcessor.processSync(rule);
        });
    };
});
postcss(plugin()).process(`
.foo-bar {
  color: red;
}
`.trim(), {from: 'test.css'}).catch((e) => console.error(e.toString()));

// CssSyntaxError: classValidator: ./test.css:1:5: classes may not have underscores or dashes in them
//
// > 1 | .foo-bar {
//     |     ^
//   2 |   color: red;
//   3 | }
```


---

# 7.1.0

- feat: insert(Before|After) support multiple new node

# 7.0.0

- Feat: make insertions during iteration safe (major)

# 6.1.2

- Fixed: erroneous trailing combinators in pseudos

# 6.1.1

- Fixed: improve typings of constructor helpers (#292)

# 6.1.0

- Feature: add `sourceIndex` to `Selector` nodes (#290)

# 6.0.16

- Fixed: add missing `index` argument to `each`/`walk` callback types (#289)

# 6.0.15

- Fixed: Node#prev and Node#next type for the first/last node

# 6.0.14

- Fixed: type definitions

# 6.0.13

- Fixed: throw on unexpected pipe symbols

# 6.0.12

- Fixed: `clone` arguments should be optional

# 6.0.11

- Fixed: parse attribute case insensitivity flag

# 6.0.10

- Fixed: `isPseudoElement()` supports `:first-letter` and `:first-line`

# 6.0.9

- Fixed: `Combinator.raws` property type

# 6.0.8

- Fixed: reduced size

# 6.0.7

- Fixed: parse animation percents

# 6.0.6

- Fixed: parse quoted attributes containing a newline correctly

# 6.0.5

- Perf: rework unesc for a 63+% performance boost

# 6.0.4

- Fixed: ts errors

# 6.0.3

- Fixed: replace node built-in "util" module with "util-deprecate"
- Fixed: handle uppercase pseudo elements
- Fixed: do not create invalid combinator before comment

# 6.0.2

- Fixed an issue with parsing and stringifying an empty attribute value

# 6.0.1

- Fixed an issue with unicode surrogate pair parsing

# 6.0.0

- Updated: `cssesc` to 3.0.0 (major)
- Fixed: Issues with escaped `id` and `class` selectors

# 5.0.0

- Allow escaped dot within class name.
- Update PostCSS to 7.0.7 (patch)

# 5.0.0-rc.4

- Fixed an issue where comments immediately after an insensitive (in attribute)
  were not parsed correctly.
- Updated `cssesc` to 2.0.0 (major).
- Removed outdated integration tests.
- Added tests for custom selectors, tags with attributes, the universal
  selector with pseudos, and tokens after combinators.

# 5.0.0-rc.1

To ease adoption of the v5.0 release, we have relaxed the node version
check performed by npm at installation time to allow for node 4, which
remains officially unsupported, but likely to continue working for the
time being.

# 5.0.0-rc.0

This release has **BREAKING CHANGES** that were required to fix regressions
in 4.0.0 and to make the Combinator Node API consistent for all combinator
types. Please read carefully.

## Summary of Changes

* The way a descendent combinator that isn't a single space character (E.g. `.a  .b`) is stored in the AST has changed.
* Named Combinators (E.g. `.a /for/ .b`) are now properly parsed as a combinator.
* It is now possible to look up a node based on the source location of a character in that node and to query nodes if they contain some character.
* Several bug fixes that caused the parser to hang and run out of memory when a `/` was encountered have been fixed.
* The minimum supported version of Node is now `v6.0.0`.

### Changes to the Descendent Combinator

In prior releases, the value of a descendant combinator with multiple spaces included all the spaces.

* `.a   .b`: Extra spaces are now stored as space before.
  - Old & Busted:
    - `combinator.value === "   "`
  - New hotness:
    - `combinator.value === " " && combinator.spaces.before === "  "`
* `.a   /*comment*/.b`: A comment at the end of the combinator causes extra space to become after space.
  - Old & Busted:
    - `combinator.value === "   "`
    - `combinator.raws.value === "   /*comment/"`
  - New hotness:
    - `combinator.value === " "`
    - `combinator.spaces.after === "  "`
    - `combinator.raws.spaces.after === "  /*comment*/"`
* `.a<newline>.b`: whitespace that doesn't start or end with a single space character is stored as a raw value.
  - Old & Busted:
    - `combinator.value === "\n"`
    - `combinator.raws.value === undefined`
  - New hotness:
    - `combinator.value === " "`
    - `combinator.raws.value === "\n"`

### Support for "Named Combinators"

Although, nonstandard and unlikely to ever become a standard, combinators like `/deep/` and `/for/` are now properly supported.

Because they've been taken off the standardization track, there is no spec-official name for combinators of the form `/<ident>/`. However, I talked to [Tab Atkins](https://twitter.com/tabatkins) and we agreed to call them "named combinators" so now they are called that.

Before this release such named combinators were parsed without intention and generated three nodes of type `"tag"` where the first and last nodes had a value of `"/"`.

* `.a /for/ .b` is parsed as a combinator.
  - Old & Busted:
    - `root.nodes[0].nodes[1].type === "tag"`
    - `root.nodes[0].nodes[1].value === "/"`
  - New hotness:
    - `root.nodes[0].nodes[1].type === "combinator"`
    - `root.nodes[0].nodes[1].value === "/for/"`
* `.a /F\6fR/ .b` escapes are handled and uppercase is normalized.
  - Old & Busted:
    - `root.nodes[0].nodes[2].type === "tag"`
    - `root.nodes[0].nodes[2].value === "F\\6fR"`
  - New hotness:
    - `root.nodes[0].nodes[1].type === "combinator"`
    - `root.nodes[0].nodes[1].value === "/for/"`
    - `root.nodes[0].nodes[1].raws.value === "/F\\6fR/"`

### Source position checks and lookups

A new API was added to look up a node based on the source location.

```js
const selectorParser = require("postcss-selector-parser");
// You can find the most specific node for any given character
let combinator = selectorParser.astSync(".a > .b").atPosition(1,4);
combinator.toString() === " > ";
// You can check if a node includes a specific character
// Whitespace surrounding the node that is owned by that node
// is included in the check.
[2,3,4,5,6].map(column => combinator.isAtPosition(1, column));
// => [false, true, true, true, false]
```

# 4.0.0

This release has **BREAKING CHANGES** that were required to fix bugs regarding values with escape sequences. Please read carefully.

* **Identifiers with escapes** - CSS escape sequences are now hidden from the public API by default.
  The normal value of a node like a class name or ID, or an aspect of a node such as attribute
  selector's value, is unescaped. Escapes representing Non-ascii characters are unescaped into
  unicode characters. For example: `bu\tton, .\31 00, #i\2764\FE0Fu, [attr="value is \"quoted\""]`
  will parse respectively to the values `button`, `100`, `i❤️u`, `value is "quoted"`.
  The original escape sequences for these values can be found in the corresponding property name
  in `node.raws`. Where possible, deprecation warnings were added, but the nature
  of escape handling makes it impossible to detect what is escaped or not. Our expectation is
  that most users are neither expecting nor handling escape sequences in their use of this library,
  and so for them, this is a bug fix. Users who are taking care to handle escapes correctly can
  now update their code to remove the escape handling and let us do it for them.

* **Mutating values with escapes** - When you make an update to a node property that has escape handling
  The value is assumed to be unescaped, and any special characters are escaped automatically and
  the corresponding `raws` value is immediately updated. This can result in changes to the original
  escape format. Where the exact value of the escape sequence is important there are methods that
  allow both values to be set in conjunction. There are a number of new convenience methods for
  manipulating values that involve escapes, especially for attributes values where the quote mark
  is involved. See https://github.com/postcss/postcss-selector-parser/pull/133 for an extensive
  write-up on these changes.


**Upgrade/API Example**

In `3.x` there was no unescape handling and internal consistency of several properties was the caller's job to maintain. It was very easy for the developer
to create a CSS file that did not parse correctly when some types of values
were in use.

```js
const selectorParser = require("postcss-selector-parser");
let attr = selectorParser.attribute({attribute: "id", operator: "=", value: "a-value"});
attr.value; // => "a-value"
attr.toString(); // => [id=a-value]
// Add quotes to an attribute's value.
// All these values have to be set by the caller to be consistent:
// no internal consistency is maintained.
attr.raws.unquoted = attr.value
attr.value = "'" + attr.value + "'";
attr.value; // => "'a-value'"
attr.quoted = true;
attr.toString();  // => "[id='a-value']"
```

In `4.0` there is a convenient API for setting and mutating values
that may need escaping. Especially for attributes.

```js
const selectorParser = require("postcss-selector-parser");

// The constructor requires you specify the exact escape sequence
let className = selectorParser.className({value: "illegal class name", raws: {value: "illegal\\ class\\ name"}});
className.toString(); // => '.illegal\\ class\\ name'

// So it's better to set the value as a property
className = selectorParser.className();
// Most properties that deal with identifiers work like this
className.value = "escape for me";
className.value; // => 'escape for me'
className.toString(); // => '.escape\\ for\\ me'

// emoji and all non-ascii are escaped to ensure it works in every css file.
className.value = "😱🦄😍";
className.value; // => '😱🦄😍'
className.toString(); // => '.\\1F631\\1F984\\1F60D'

// you can control the escape sequence if you want, or do bad bad things
className.setPropertyAndEscape('value', 'xxxx', 'yyyy');
className.value; // => "xxxx"
className.toString(); // => ".yyyy"

// Pass a value directly through to the css output without escaping it. 
className.setPropertyWithoutEscape('value', '$REPLACE_ME$');
className.value; // => "$REPLACE_ME$"
className.toString(); // => ".$REPLACE_ME$"

// The biggest changes are to the Attribute class
// passing quoteMark explicitly is required to avoid a deprecation warning.
let attr = selectorParser.attribute({attribute: "id", operator: "=", value: "a-value", quoteMark: null});
attr.toString(); // => "[id=a-value]"
// Get the value with quotes on it and any necessary escapes.
// This is the same as reading attr.value in 3.x.
attr.getQuotedValue(); // => "a-value";
attr.quoteMark; // => null

// Add quotes to an attribute's value.
attr.quoteMark = "'"; // This is all that's required.
attr.toString(); // => "[id='a-value']"
attr.quoted; // => true
// The value is still the same, only the quotes have changed.
attr.value; // => a-value
attr.getQuotedValue(); // => "'a-value'";

// deprecated assignment, no warning because there's no escapes
attr.value = "new-value";
// no quote mark is needed so it is removed
attr.getQuotedValue(); // => "new-value";

// deprecated assignment, 
attr.value = "\"a 'single quoted' value\"";
// > (node:27859) DeprecationWarning: Assigning an attribute a value containing characters that might need to be escaped is deprecated. Call attribute.setValue() instead.
attr.getQuotedValue(); // => '"a \'single quoted\' value"';
// quote mark inferred from first and last characters.
attr.quoteMark; // => '"'

// setValue takes options to make manipulating the value simple.
attr.setValue('foo', {smart: true});
// foo doesn't require any escapes or quotes.
attr.toString(); // => '[id=foo]'
attr.quoteMark; // => null 

// An explicit quote mark can be specified
attr.setValue('foo', {quoteMark: '"'});
attr.toString(); // => '[id="foo"]'

// preserves quote mark by default
attr.setValue('bar');
attr.toString(); // => '[id="bar"]'
attr.quoteMark = null;
attr.toString(); // => '[id=bar]'

// with no arguments, it preserves quote mark even when it's not a great idea
attr.setValue('a value \n that should be quoted');
attr.toString(); // => '[id=a\\ value\\ \\A\\ that\\ should\\ be\\ quoted]'

// smart preservation with a specified default
attr.setValue('a value \n that should be quoted', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => "[id='a value \\A  that should be quoted']"
attr.quoteMark = '"';
// => '[id="a value \\A  that should be quoted"]'

// this keeps double quotes because it wants to quote the value and the existing value has double quotes.
attr.setValue('this should be quoted', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => '[id="this should be quoted"]'

// picks single quotes because the value has double quotes
attr.setValue('a "double quoted" value', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => "[id='a "double quoted" value']"

// setPropertyAndEscape lets you do anything you want. Even things that are a bad idea and illegal.
attr.setPropertyAndEscape('value', 'xxxx', 'the password is 42');
attr.value; // => "xxxx"
attr.toString(); // => "[id=the password is 42]"

// Pass a value directly through to the css output without escaping it. 
attr.setPropertyWithoutEscape('value', '$REPLACEMENT$');
attr.value; // => "$REPLACEMENT$"
attr.toString(); // => "[id=$REPLACEMENT$]"
```

# 3.1.2

* Fix: Removed dot-prop dependency since it's no longer written in es5.

# 3.1.1

* Fix: typescript definitions weren't in the published package.

# 3.1.0

* Fixed numerous bugs in attribute nodes relating to the handling of comments
  and whitespace. There's significant changes to `attrNode.spaces` and `attrNode.raws` since the `3.0.0` release.
* Added `Attribute#offsetOf(part)` to get the offset location of
  attribute parts like `"operator"` and `"value"`. This is most
  often added to `Attribute#sourceIndex` for error reporting.

# 3.0.0

## Breaking changes

* Some tweaks to the tokenizer/attribute selector parsing mean that whitespace
  locations might be slightly different to the 2.x code.
* Better attribute selector parsing with more validation; postcss-selector-parser
  no longer uses regular expressions to parse attribute selectors.
* Added an async API (thanks to @jacobp100); the default `process` API is now
  async, and the sync API is now accessed through `processSync` instead.
* `process()` and `processSync()` now return a string instead of the Processor
  instance.
* Tweaks handling of Less interpolation (thanks to @jwilsson).
* Removes support for Node 0.12.

## Other changes

* `ast()` and `astSync()` methods have been added to the `Processor`. These
  return the `Root` node of the selectors after processing them.
* `transform()` and `transformSync()` methods have been added to the
  `Processor`. These return the value returned by the processor callback
  after processing the selectors.
* Set the parent when inserting a node (thanks to @chriseppstein).
* Correctly adjust indices when using insertBefore/insertAfter (thanks to @tivac).
* Fixes handling of namespaces with qualified tag selectors.
* `process`, `ast` and `transform` (and their sync variants) now accept a
  `postcss` rule node. When provided, better errors are generated and selector
  processing is automatically set back to the rule selector (unless the `updateSelector` option is set to `false`.)
* Now more memory efficient when tokenizing selectors.

### Upgrade hints

The pattern of:

`rule.selector = processor.process(rule.selector).result.toString();`

is now:

`processor.processSync(rule)`

# 2.2.3

* Resolves an issue where the parser would not reduce multiple spaces between an
  ampersand and another simple selector in lossy mode (thanks to @adam-26).

# 2.2.2

* No longer hangs on an unescaped semicolon; instead the parser will throw
  an exception for these cases.

# 2.2.1

* Allows a consumer to specify whitespace tokens when creating a new Node
  (thanks to @Semigradsky).

# 2.2.0

* Added a new option to normalize whitespace when parsing the selector string
  (thanks to @adam-26).

# 2.1.1

* Better unquoted value handling within attribute selectors
  (thanks to @evilebottnawi).

# 2.1.0

* Added: Use string constants for all node types & expose them on the main
  parser instance (thanks to @Aweary).

# 2.0.0

This release contains the following breaking changes:

* Renamed all `eachInside` iterators to `walk`. For example, `eachTag` is now
  `walkTags`, and `eachInside` is now `walk`.
* Renamed `Node#removeSelf()` to `Node#remove()`.
* Renamed `Container#remove()` to `Container#removeChild()`.
* Renamed `Node#raw` to `Node#raws` (thanks to @davidtheclark).
* Now parses `&` as the *nesting* selector, rather than a *tag* selector.
* Fixes misinterpretation of Sass interpolation (e.g. `#{foo}`) as an
  id selector (thanks to @davidtheclark).

and;

* Fixes parsing of attribute selectors with equals signs in them
  (e.g. `[data-attr="foo=bar"]`) (thanks to @montmanu).
* Adds `quoted` and `raw.unquoted` properties to attribute nodes
  (thanks to @davidtheclark).

# 1.3.3

* Fixes an infinite loop on `)` and `]` tokens when they had no opening pairs.
  Now postcss-selector-parser will throw when it encounters these lone tokens.

# 1.3.2

* Now uses plain integers rather than `str.charCodeAt(0)` for compiled builds.

# 1.3.1

* Update flatten to v1.x (thanks to @shinnn).

# 1.3.0

* Adds a new node type, `String`, to fix a crash on selectors such as
  `foo:bar("test")`.

# 1.2.1

* Fixes a crash when the parser encountered a trailing combinator.

# 1.2.0

* A more descriptive error is thrown when the parser expects to find a
  pseudo-class/pseudo-element (thanks to @ashelley).
* Adds support for line/column locations for selector nodes, as well as a
  `Node#sourceIndex` method (thanks to @davidtheclark).

# 1.1.4

* Fixes a crash when a selector started with a `>` combinator. The module will
  now no longer throw if a selector has a leading/trailing combinator node.

# 1.1.3

* Fixes a crash on `@` tokens.

# 1.1.2

* Fixes an infinite loop caused by using parentheses in a non-pseudo element
  context.

# 1.1.1

* Fixes a crash when a backslash ended a selector string.

# 1.1.0

* Adds support for replacing multiple nodes at once with `replaceWith`
  (thanks to @jonathantneal).
* Parser no longer throws on sequential IDs and trailing commas, to support
  parsing of selector hacks.

# 1.0.1

* Fixes using `insertAfter` and `insertBefore` during iteration.

# 1.0.0

* Adds `clone` and `replaceWith` methods to nodes.
* Adds `insertBefore` and `insertAfter` to containers.
* Stabilises API.

# 0.0.5

* Fixes crash on extra whitespace inside a pseudo selector's parentheses.
* Adds sort function to the container class.
* Enables the parser to pass its input through without transforming.
* Iteration-safe `each` and `eachInside`.

# 0.0.4

* Tidy up redundant duplication.
* Fixes a bug where the parser would loop infinitely on universal selectors
  inside pseudo selectors.
* Adds `length` getter and `eachInside`, `map`, `reduce` to the container class.
* When a selector has been removed from the tree, the root node will no longer
  cast it to a string.
* Adds node type iterators to the container class (e.g. `eachComment`).
* Adds filter function to the container class.
* Adds split function to the container class.
* Create new node types by doing `parser.id(opts)` etc.
* Adds support for pseudo classes anywhere in the selector.

# 0.0.3

* Adds `next` and `prev` to the node class.
* Adds `first` and `last` getters to the container class.
* Adds `every` and `some` iterators to the container class.
* Add `empty` alias for `removeAll`.
* Combinators are now types of node.
* Fixes the at method so that it is not an alias for `index`.
* Tidy up creation of new nodes in the parser.
* Refactors how namespaces are handled for consistency & less redundant code.
* Refactors AST to use `nodes` exclusively, and eliminates excessive nesting.
* Fixes nested pseudo parsing.
* Fixes whitespace parsing.

# 0.0.2

* Adds support for namespace selectors.
* Adds support for selectors joined by escaped spaces - such as `.\31\ 0`.

# 0.0.1

* Initial release.


---

# postcss-selector-parser [![test](https://github.com/postcss/postcss-selector-parser/actions/workflows/test.yml/badge.svg)](https://github.com/postcss/postcss-selector-parser/actions/workflows/test.yml)

> Selector parser with built in methods for working with selector strings.

## Install

With [npm](https://npmjs.com/package/postcss-selector-parser) do:

```
npm install postcss-selector-parser
```

## Quick Start

```js
const parser = require('postcss-selector-parser');
const transform = selectors => {
    selectors.walk(selector => {
        // do something with the selector
        console.log(String(selector))
    });
};

const transformed = parser(transform).processSync('h1, h2, h3');
```

To normalize selector whitespace:

```js
const parser = require('postcss-selector-parser');
const normalized = parser().processSync('h1, h2, h3', {lossless: false});
// -> h1,h2,h3
```

Async support is provided through `parser.process` and will resolve a Promise
with the resulting selector string.

## API

Please see [API.md](API.md).

## Credits

* Huge thanks to Andrey Sitnik (@ai) for work on PostCSS which helped
  accelerate this module's development.

## License

MIT


---

# Changes to PostCSS Color Function

### 4.0.8

_February 23, 2025_

- Updated [`@csstools/css-color-parser`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-color-parser) to [`3.0.8`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-color-parser/CHANGELOG.md#308) (patch)

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-color-function/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Color Function [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install @csstools/postcss-color-function --save-dev`

[PostCSS Color Function] lets you use the `color` function in
CSS, following the [CSS Color] specification.

```css
.color {
	color: color(display-p3 0.64331 0.19245 0.16771);
}

:root {
	--a-color: color(srgb 0.64331 0.19245 0.16771);
}

/* becomes */

.color {
	color: rgb(179, 35, 35);
}

:root {
	--a-color: rgb(164, 49, 43);
}
```

## Usage

Add [PostCSS Color Function] to your project:

```bash
npm install postcss @csstools/postcss-color-function --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssColorFunction = require('@csstools/postcss-color-function');

postcss([
	postcssColorFunction(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## Options

### preserve

The `preserve` option determines whether the original notation
is preserved. By default, it is not preserved.

```js
postcssColorFunction({ preserve: true })
```

```css
.color {
	color: color(display-p3 0.64331 0.19245 0.16771);
}

:root {
	--a-color: color(srgb 0.64331 0.19245 0.16771);
}

/* becomes */

.color {
	color: rgb(179, 35, 35);
	color: color(display-p3 0.64331 0.19245 0.16771);
}

:root {
	--a-color: rgb(164, 49, 43);
}

@supports (color: color(display-p3 0 0 0%)) {
:root {
	--a-color: color(srgb 0.64331 0.19245 0.16771);
}
}
```

### enableProgressiveCustomProperties

The `enableProgressiveCustomProperties` option determines whether the original notation
is wrapped with `@supports` when used in Custom Properties. By default, it is enabled.

> [!NOTE]
> We only recommend disabling this when you set `preserve` to `false` or if you bring your own fix for Custom Properties.  
> See what the plugin does in its [README](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-progressive-custom-properties#readme).

```js
postcssColorFunction({ enableProgressiveCustomProperties: false })
```

```css
.color {
	color: color(display-p3 0.64331 0.19245 0.16771);
}

:root {
	--a-color: color(srgb 0.64331 0.19245 0.16771);
}

/* becomes */

.color {
	color: rgb(179, 35, 35);
	color: color(display-p3 0.64331 0.19245 0.16771);
}

:root {
	--a-color: rgb(164, 49, 43);
	--a-color: color(srgb 0.64331 0.19245 0.16771);
}
```

_Custom properties do not fallback to the previous declaration_

## Supported Color Spaces

```css
.color-spaces {
	color: color(a98-rgb 0.803 0.484 0.944);
	color: color(display-p3 0.8434 0.509 0.934);
	color: color(prophoto-rgb 0.759 0.493 0.898);
	color: color(rec2020 0.772 0.491 0.920);
	color: color(srgb 0.897 0.488 0.959);
	color: color(srgb-linear 0.783 0.203 0.910);
	color: color(xyz 0.560 0.377 0.904);
	color: color(xyz-d50 0.550 0.375 0.680);
	color: color(xyz-d65 0.560 0.377 0.904);
}
```

## Copyright : color conversions

This software or document includes material copied from or derived from https://github.com/w3c/csswg-drafts/tree/main/css-color-4. Copyright © 2022 W3C® (MIT, ERCIM, Keio, Beihang).

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#color-function
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/postcss-color-function

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Color Function]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-color-function
[CSS Color]: https://www.w3.org/TR/css-color-4/#funcdef-color


---

# Changes to PostCSS Color Mix Function

### 3.0.8

_February 23, 2025_

- Updated [`@csstools/css-color-parser`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-color-parser) to [`3.0.8`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-color-parser/CHANGELOG.md#308) (patch)

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-color-mix-function/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Color Mix Function [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install @csstools/postcss-color-mix-function --save-dev`

[PostCSS Color Mix Function] lets you use the `color-mix()` function following the [CSS Color 5 Specification].

```css
.purple_plum {
	color: color-mix(in lch, purple 50%, plum 50%);
}

/* becomes */

.purple_plum {
	color: rgb(175, 92, 174);
}
```

> [!NOTE]
> We can not dynamically resolve `var()` arguments in `color-mix()`, only static values will work.

## Usage

Add [PostCSS Color Mix Function] to your project:

```bash
npm install postcss @csstools/postcss-color-mix-function --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssColorMixFunction = require('@csstools/postcss-color-mix-function');

postcss([
	postcssColorMixFunction(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## Options

### preserve

The `preserve` option determines whether the original notation
is preserved. By default, it is not preserved.

```js
postcssColorMixFunction({ preserve: true })
```

```css
.purple_plum {
	color: color-mix(in lch, purple 50%, plum 50%);
}

/* becomes */

.purple_plum {
	color: rgb(175, 92, 174);
	color: color-mix(in lch, purple 50%, plum 50%);
}
```

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#color-mix
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/postcss-color-mix-function

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Color Mix Function]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-color-mix-function
[CSS Color 5 Specification]: https://www.w3.org/TR/css-color-5/#color-mix


---

# Changes to PostCSS Content Alt Text

### 2.0.4

_November 1, 2024_

- Updated [`@csstools/css-tokenizer`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-tokenizer) to [`3.0.3`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-tokenizer/CHANGELOG.md#303) (patch)
- Updated [`@csstools/css-parser-algorithms`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-parser-algorithms) to [`3.0.4`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-parser-algorithms/CHANGELOG.md#304) (patch)

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-content-alt-text/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Content Alt Text [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install @csstools/postcss-content-alt-text --save-dev`

[PostCSS Content Alt Text] generates fallback values for `content` with alt text following the [CSS Generated Content Module].

```pcss
.foo {
	content: url(tree.jpg) / "A beautiful tree in a dark forest";
}

.bar {
	content: ">" / "";
}

/* becomes */

.foo {
	content: url(tree.jpg)  "A beautiful tree in a dark forest";
	content: url(tree.jpg) / "A beautiful tree in a dark forest";
}

.bar {
	content: ">" ;
	content: ">" / "";
}
```

## Usage

Add [PostCSS Content Alt Text] to your project:

```bash
npm install postcss @csstools/postcss-content-alt-text --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssContentAltText = require('@csstools/postcss-content-alt-text');

postcss([
	postcssContentAltText(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## Options

### preserve

The `preserve` option determines whether the original notation
is preserved. By default, it is preserved.

```js
postcssContentAltText({ preserve: false })
```

```pcss
.foo {
	content: url(tree.jpg) / "A beautiful tree in a dark forest";
}

.bar {
	content: ">" / "";
}

/* becomes */

.foo {
	content: url(tree.jpg)  "A beautiful tree in a dark forest";
}

.bar {
	content: ">" ;
}
```

### stripAltText

The `stripAltText` option determines whether the alt text is removed from the value.  
By default, it is not removed.  
Instead it is added to the `content` value itself to ensure content is accessible.

Only set this to `true` if you are sure the alt text is not needed.

```js
postcssContentAltText({ stripAltText: true })
```

```pcss
.foo {
	content: url(tree.jpg) / "A beautiful tree in a dark forest";
}

.bar {
	content: ">" / "";
}

/* becomes */

.foo {
	content: url(tree.jpg) ;
	content: url(tree.jpg) / "A beautiful tree in a dark forest";
}

.bar {
	content: ">" ;
	content: ">" / "";
}
```

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#content-alt-text
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/postcss-content-alt-text

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Content Alt Text]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-content-alt-text
[CSS Generated Content Module]: https://drafts.csswg.org/css-content/#content-property


---

# Changes to PostCSS Exponential Functions

### 2.0.7

_February 23, 2025_

- Updated [`@csstools/css-calc`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-calc) to [`2.1.2`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-calc/CHANGELOG.md#212) (patch)

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-exponential-functions/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Exponential Functions [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install @csstools/postcss-exponential-functions --save-dev`

[PostCSS Exponential Functions] lets you use the `pow()`, `sqrt()`, `hypot()`, `log()`, `exp()` functions following the [CSS Values 4 Specification].

```css
.foo {
	top: calc(1px * pow(2, 3));
	line-height: sqrt(1.2);
	padding: hypot(3px, 4px);
	order: log(10, 10);
	min-height: calc(e - exp(1));
}

/* becomes */

.foo {
	top: 8px;
	line-height: 1.0954451150103;
	padding: 5px;
	order: 1;
	min-height: 0;
}
```

## Usage

Add [PostCSS Exponential Functions] to your project:

```bash
npm install postcss @csstools/postcss-exponential-functions --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssExponentialFunctions = require('@csstools/postcss-exponential-functions');

postcss([
	postcssExponentialFunctions(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## Options

### preserve

The `preserve` option determines whether the original notation
is preserved. By default, it is not preserved.

```js
postcssExponentialFunctions({ preserve: true })
```

```css
.foo {
	top: calc(1px * pow(2, 3));
	line-height: sqrt(1.2);
	padding: hypot(3px, 4px);
	order: log(10, 10);
	min-height: calc(e - exp(1));
}

/* becomes */

.foo {
	top: 8px;
	top: calc(1px * pow(2, 3));
	line-height: 1.0954451150103;
	line-height: sqrt(1.2);
	padding: 5px;
	padding: hypot(3px, 4px);
	order: 1;
	order: log(10, 10);
	min-height: 0;
	min-height: calc(e - exp(1));
}
```

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#exponential-functions
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/postcss-exponential-functions

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Exponential Functions]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-exponential-functions
[CSS Values 4 Specification]: https://www.w3.org/TR/css-values-4/#exponent-funcs


---

# Changes to PostCSS Font Format

### 4.0.0

_August 3, 2024_

- Updated: Support for Node v18+ (major).
- Updated [`@csstools/utilities`](https://github.com/csstools/postcss-plugins/tree/main/packages/utilities) to [`2.0.0`](https://github.com/csstools/postcss-plugins/tree/main/packages/utilities/CHANGELOG.md#200) (major)

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-font-format-keywords/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Font Format [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][postcss]

[<img alt="npm version" src="https://img.shields.io/npm/v/@csstools/postcss-font-format-keywords.svg" height="20">][npm-url]
[<img alt="Build Status" src="https://github.com/csstools/postcss-plugins/workflows/test/badge.svg" height="20">][cli-url]
[<img alt="Discord" src="https://shields.io/badge/Discord-5865F2?logo=discord&logoColor=white">][discord]
<br><br>
[<img alt="Baseline Status" src="https://cssdb.org/images/badges-baseline/font-format-keywords.svg" height="20">][css-url]
[<img alt="CSS Standard Status" src="https://cssdb.org/images/badges/font-format-keywords.svg" height="20">][css-url]

[PostCSS Font Format Keywords] lets you specify font formats as keywords, following the [CSS Fonts] specification.

```pcss
@font-face {
  src: url(file.woff2) format(woff2);
}

/* becomes */

@font-face {
  src: url(file.woff2) format("woff2");
}
```

_See prior work by [valtlai](https://github.com/valtlai) here [postcss-font-format-keywords](https://github.com/valtlai/postcss-font-format-keywords)
To ensure long term maintenance and to provide the needed features this plugin was recreated based on valtlai's work._

## Usage

Add [PostCSS Font Format Keywords] to your project:

```bash
npm install postcss @csstools/postcss-font-format-keywords --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssFontFormatKeywords = require('@csstools/postcss-font-format-keywords');

postcss([
  postcssFontFormatKeywords(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```

[PostCSS Font Format Keywords] runs in all Node environments, with special
instructions for:

| [Node](INSTALL.md#node) | [PostCSS CLI](INSTALL.md#postcss-cli) | [Webpack](INSTALL.md#webpack) | [Gulp](INSTALL.md#gulp) | [Grunt](INSTALL.md#grunt) |
| --- | --- | --- | --- | --- |

## Options

### preserve

The `preserve` option determines whether the original source
is preserved. By default, it is not preserved.

```js
postcssFontFormatKeywords({ preserve: true })
```

```pcss
@font-face {
  src: url(file.woff2) format(woff2);
}

/* becomes */

@font-face {
  src: url(file.woff2) format("woff2");
  src: url(file.woff2) format(woff2);
}
```

[postcss]: https://github.com/postcss/postcss

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#font-format-keywords
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/postcss-font-format-keywords

[CSS Fonts]: https://www.w3.org/TR/css-fonts-4/#font-format-values
[Gulp PostCSS]: https://github.com/postcss/gulp-postcss
[Grunt PostCSS]: https://github.com/nDmitry/grunt-postcss
[PostCSS]: https://github.com/postcss/postcss
[PostCSS Loader]: https://github.com/postcss/postcss-loader
[PostCSS Font Format Keywords]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-font-format-keywords


---

# Changes to PostCSS gamut-mapping

### 2.0.8

_February 23, 2025_

- Updated [`@csstools/css-color-parser`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-color-parser) to [`3.0.8`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-color-parser/CHANGELOG.md#308) (patch)

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-gamut-mapping/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Gamut Mapping [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install @csstools/postcss-gamut-mapping --save-dev`

[PostCSS Gamut Mapping] lets you use wide gamut colors with gamut mapping for specific displays following the [CSS Color 4 Specification].

When out of gamut colors are naively clipped the result can be radically different.  
A saturated and bright color will be much darker after clipping.

To correctly adjust colors for a narrow gamut display, the colors must be mapped.  
This is done by lowering the `chroma` in `oklch` until the color is in gamut.  

Using the `@media (color-gamut)` media feature makes it possible to only use the wide gamut colors on displays that support them.

```css
p {
	background-color: oklch(80% 0.05 0.39 / 0.5);
	color: oklch(20% 0.234 0.39 / 0.5);
	border-color: color(display-p3 0 1 0);
}

/* becomes */

p {
	background-color: oklch(80% 0.05 0.39 / 0.5);
	color: rgba(48, 0, 20, 0.5);
	border-color: rgb(0, 247, 79);
}

@media (color-gamut: rec2020) {
p {
	color: oklch(20% 0.234 0.39 / 0.5);
}
}

@media (color-gamut: p3) {
p {
	border-color: color(display-p3 0 1 0);
}
}
```

## Usage

Add [PostCSS Gamut Mapping] to your project:

```bash
npm install postcss @csstools/postcss-gamut-mapping --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssGamutMapping = require('@csstools/postcss-gamut-mapping');

postcss([
	postcssGamutMapping(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#gamut-mapping
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/postcss-gamut-mapping

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Gamut Mapping]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-gamut-mapping
[CSS Color 4 Specification]: https://www.w3.org/TR/css-color-4/#gamut-mapping


---

# Changes to PostCSS Gradients Interpolation Method

### 5.0.8

_February 23, 2025_

- Updated [`@csstools/css-color-parser`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-color-parser) to [`3.0.8`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-color-parser/CHANGELOG.md#308) (patch)

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-gradients-interpolation-method/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Gradients Interpolation Method [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install @csstools/postcss-gradients-interpolation-method --save-dev`

[PostCSS Gradients Interpolation Method] lets you use different interpolation methods in CSS gradient functions following [CSS Images Module 4].

```css
.example {
	background-image: linear-gradient(in oklch, hsl(0deg 85% 75%) 0%, hsl(180deg 80% 65%) 100%);
}

:root {
	--background-image: linear-gradient(in oklab, hsl(96, 42%, 24%) 0%, hsl(302, 67%, 25%) 100%);
}

/* becomes */

.example {
	background-image: linear-gradient(rgb(245, 137, 137) 0%, rgb(248, 146, 114), rgb(244, 158, 94), rgb(235, 171, 82), rgb(220, 185, 81), rgb(201, 199, 95), rgb(177, 211, 118), rgb(151, 221, 146), rgb(125, 229, 177), rgb(103, 235, 208), rgb(94, 237, 237) 100%);
	background-image: linear-gradient(in oklch, hsl(0deg 85% 75%) 0%, hsl(180deg 80% 65%) 100%);
}

:root {
	--background-image: linear-gradient(rgb(56, 87, 35) 0%, rgb(64, 83, 46), rgb(70, 79, 54), rgb(76, 74, 62), rgb(82, 69, 68), rgb(86, 64, 75), rgb(91, 58, 81), rgb(95, 51, 87), rgb(99, 44, 93), rgb(103, 34, 98), rgb(106, 21, 104) 100%);
}

@supports (background: linear-gradient(in oklch, red 0%, red 0% 1%, red 2%)) {
:root {
	--background-image: linear-gradient(in oklab, hsl(96, 42%, 24%) 0%, hsl(302, 67%, 25%) 100%);
}
}
```

## Shortcomings

> [!CAUTION]
> Color stops with only a color or only an interpolation hint are not supported.

For best results you should always provide at least the color and position for each color stop.
Double position color stops are supported.

```css
.foo {
	/* Only a color: can't transform */
	background-image: linear-gradient(in oklch, black 0%, green, blue 100%);

	/* Only an interpolation hint: can't transform */
	background-image: linear-gradient(in oklch, black 0%, 25%, blue 100%);
}
```

> [!CAUTION]
> Variable colors are not supported.
> We can not mix colors when the color is a variable.

```css
.foo {
	--red: red;
	/* Color stop variable : can't transform */
	background-image: linear-gradient(in oklch, black 0%, var(--red), blue 100%);
}
```

## Usage

Add [PostCSS Gradients Interpolation Method] to your project:

```bash
npm install postcss @csstools/postcss-gradients-interpolation-method --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssGradientsInterpolationMethod = require('@csstools/postcss-gradients-interpolation-method');

postcss([
	postcssGradientsInterpolationMethod(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## Options

### preserve

The `preserve` option determines whether the original notation
is preserved. By default, it is preserved.

```js
postcssGradientsInterpolationMethod({ preserve: false })
```

```css
.example {
	background-image: linear-gradient(in oklch, hsl(0deg 85% 75%) 0%, hsl(180deg 80% 65%) 100%);
}

:root {
	--background-image: linear-gradient(in oklab, hsl(96, 42%, 24%) 0%, hsl(302, 67%, 25%) 100%);
}

/* becomes */

.example {
	background-image: linear-gradient(rgb(245, 137, 137) 0%, rgb(248, 146, 114), rgb(244, 158, 94), rgb(235, 171, 82), rgb(220, 185, 81), rgb(201, 199, 95), rgb(177, 211, 118), rgb(151, 221, 146), rgb(125, 229, 177), rgb(103, 235, 208), rgb(94, 237, 237) 100%);
}

:root {
	--background-image: linear-gradient(rgb(56, 87, 35) 0%, rgb(64, 83, 46), rgb(70, 79, 54), rgb(76, 74, 62), rgb(82, 69, 68), rgb(86, 64, 75), rgb(91, 58, 81), rgb(95, 51, 87), rgb(99, 44, 93), rgb(103, 34, 98), rgb(106, 21, 104) 100%);
}
```

### enableProgressiveCustomProperties

The `enableProgressiveCustomProperties` option determines whether the original notation
is wrapped with `@supports` when used in Custom Properties. By default, it is enabled.

> [!NOTE]
> We only recommend disabling this when you set `preserve` to `false` or if you bring your own fix for Custom Properties.  
> See what the plugin does in its [README](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-progressive-custom-properties#readme).

```js
postcssGradientsInterpolationMethod({ enableProgressiveCustomProperties: false })
```

```css
.example {
	background-image: linear-gradient(in oklch, hsl(0deg 85% 75%) 0%, hsl(180deg 80% 65%) 100%);
}

:root {
	--background-image: linear-gradient(in oklab, hsl(96, 42%, 24%) 0%, hsl(302, 67%, 25%) 100%);
}

/* becomes */

.example {
	background-image: linear-gradient(rgb(245, 137, 137) 0%, rgb(248, 146, 114), rgb(244, 158, 94), rgb(235, 171, 82), rgb(220, 185, 81), rgb(201, 199, 95), rgb(177, 211, 118), rgb(151, 221, 146), rgb(125, 229, 177), rgb(103, 235, 208), rgb(94, 237, 237) 100%);
	background-image: linear-gradient(in oklch, hsl(0deg 85% 75%) 0%, hsl(180deg 80% 65%) 100%);
}

:root {
	--background-image: linear-gradient(rgb(56, 87, 35) 0%, rgb(64, 83, 46), rgb(70, 79, 54), rgb(76, 74, 62), rgb(82, 69, 68), rgb(86, 64, 75), rgb(91, 58, 81), rgb(95, 51, 87), rgb(99, 44, 93), rgb(103, 34, 98), rgb(106, 21, 104) 100%);
	--background-image: linear-gradient(in oklab, hsl(96, 42%, 24%) 0%, hsl(302, 67%, 25%) 100%);
}
```

_Custom properties do not fallback to the previous declaration_

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#gradients-interpolation-method
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/postcss-gradients-interpolation-method

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Gradients Interpolation Method]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-gradients-interpolation-method
[CSS Images Module 4]: https://drafts.csswg.org/css-images-4/#linear-gradients


---

# Changes to PostCSS HWB Function

### 4.0.8

_February 23, 2025_

- Updated [`@csstools/css-color-parser`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-color-parser) to [`3.0.8`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-color-parser/CHANGELOG.md#308) (patch)

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-hwb-function/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS HWB Function [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install @csstools/postcss-hwb-function --save-dev`

[PostCSS HWB Function] lets you use the `hwb()` color function in CSS, following [CSS Color Module 4].

```css
a {
	color: hwb(194 0% 0%);
}

b {
	color: hwb(194 0% 0% / .5);
}

/* becomes */

a {
	color: rgb(0, 196, 255);
}

b {
	color: rgba(0, 196, 255, 0.5);
}
```

## Usage

Add [PostCSS HWB Function] to your project:

```bash
npm install postcss @csstools/postcss-hwb-function --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssHWBFunction = require('@csstools/postcss-hwb-function');

postcss([
	postcssHWBFunction(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## Options

### preserve

The `preserve` option determines whether the original notation
is preserved. By default, it is not preserved.

```js
postcssHWBFunction({ preserve: true })
```

```css
a {
	color: hwb(194 0% 0%);
}

b {
	color: hwb(194 0% 0% / .5);
}

/* becomes */

a {
	color: rgb(0, 196, 255);
	color: hwb(194 0% 0%);
}

b {
	color: rgba(0, 196, 255, 0.5);
	color: hwb(194 0% 0% / .5);
}
```

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#hwb-function
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/postcss-hwb-function

[PostCSS]: https://github.com/postcss/postcss
[PostCSS HWB Function]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-hwb-function
[CSS Color Module 4]: https://www.w3.org/TR/css-color-4/#the-hwb-notation


---

# Changes to PostCSS IC Unit

### 4.0.0

_August 3, 2024_

- Updated: Support for Node v18+ (major).
- Updated [`@csstools/utilities`](https://github.com/csstools/postcss-plugins/tree/main/packages/utilities) to [`2.0.0`](https://github.com/csstools/postcss-plugins/tree/main/packages/utilities/CHANGELOG.md#200) (major)
- Updated [`@csstools/postcss-progressive-custom-properties`](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-progressive-custom-properties) to [`4.0.0`](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-progressive-custom-properties/CHANGELOG.md#400) (major)

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-ic-unit/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS IC Unit [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][postcss]


[<img alt="npm version" src="https://img.shields.io/npm/v/@csstools/postcss-ic-unit.svg" height="20">][npm-url]
[<img alt="Build Status" src="https://github.com/csstools/postcss-plugins/workflows/test/badge.svg" height="20">][cli-url]
[<img alt="Discord" src="https://shields.io/badge/Discord-5865F2?logo=discord&logoColor=white">][discord]
<br><br>
[<img alt="Baseline Status" src="https://cssdb.org/images/badges-baseline/ic-unit.svg" height="20">][css-url]
[<img alt="CSS Standard Status" src="https://cssdb.org/images/badges/ic-unit.svg" height="20">][css-url]

[PostCSS IC Unit] lets you use the ic length unit, following the [CSS Values and Units Module] specification.

```pcss
p {
  text-indent: 2ic;
}

.bubble {
  width: calc(8ic + 20px);
}

/* becomes */
p {
  text-indent: 2em;
}

.bubble {
  width: calc(8em + 20px);
}
```

_See prior work by [JLHwung](https://github.com/JLHwung) here [postcss-ic-unit](https://github.com/JLHwung/postcss-ic-unit)
To ensure long term maintenance and to provide the needed features this plugin was recreated based on JLHwung's work._

## Usage

Add [PostCSS IC Unit] to your project:

```bash
npm install postcss @csstools/postcss-ic-unit --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssIcUnit = require('@csstools/postcss-ic-unit');

postcss([
  postcssIcUnit(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```

[PostCSS IC Unit] runs in all Node environments, with special
instructions for:

| [Node](INSTALL.md#node) | [PostCSS CLI](INSTALL.md#postcss-cli) | [Webpack](INSTALL.md#webpack) | [Gulp](INSTALL.md#gulp) | [Grunt](INSTALL.md#grunt) |
| --- | --- | --- | --- | --- |

## Options

### preserve

The `preserve` option determines whether the original source
is preserved. By default, it is not preserved.

```js
postcssIcUnit({ preserve: true })
```

```pcss
p {
  text-indent: 2ic;
}

/* becomes */

p {
  text-indent: 2em;
  text-indent: 2ic;
}
```

[postcss]: https://github.com/postcss/postcss

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#ic-unit
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/postcss-ic-unit

[Gulp PostCSS]: https://github.com/postcss/gulp-postcss
[Grunt PostCSS]: https://github.com/nDmitry/grunt-postcss
[PostCSS]: https://github.com/postcss/postcss
[PostCSS Loader]: https://github.com/postcss/postcss-loader
[CSS Values and Units Module]: https://www.w3.org/TR/css-values-4/#ic
[PostCSS IC Unit]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-ic-unit


---

# Changes to PostCSS Initial

### 2.0.1

_February 12, 2025_

- Fix unexpected removal of declarations that do not require a fallback.

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-initial/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Initial [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install @csstools/postcss-initial --save-dev`

[PostCSS Initial] fallback the `initial` keyword following the [CSS Cascade 4 Specification].

```css
.foo {
	border: initial;
}

/* becomes */

.foo {
	border: medium none currentcolor;
	border: initial;
}
```

_See prior work by [maximkoretskiy](https://github.com/maximkoretskiy) here [postcss-initial](https://github.com/maximkoretskiy/postcss-initial)
To ensure long term maintenance and to provide the needed features this plugin was recreated based on maximkoretskiy's work._

## Usage

Add [PostCSS Initial] to your project:

```bash
npm install postcss @csstools/postcss-initial --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssInitial = require('@csstools/postcss-initial');

postcss([
	postcssInitial(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## Options

### preserve

The `preserve` option determines whether the original notation
is preserved. By default, it is preserved.

```js
postcssInitial({ preserve: false })
```

```css
.foo {
	border: initial;
}

/* becomes */

.foo {
	border: medium none currentcolor;
}
```

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#all-property
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/postcss-initial

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Initial]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-initial
[CSS Cascade 4 Specification]: https://www.w3.org/TR/css-cascade-4/#initial


---

# Changes to PostCSS Is Pseudo Class

### 5.0.1

_October 23, 2024_

- Make sorting compound selectors forwards compatible with potential future changes in `postcss-selector-parser`
- Updated: `postcss-selector-parser`
- Updated [`@csstools/selector-specificity`](https://github.com/csstools/postcss-plugins/tree/main/packages/selector-specificity) to [`5.0.0`](https://github.com/csstools/postcss-plugins/tree/main/packages/selector-specificity/CHANGELOG.md#500) (major)

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-is-pseudo-class/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Is Pseudo [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS" width="90" height="90" align="right">][postcss]

[![NPM Version][npm-img]][npm-url]
[<img alt="Build Status" src="https://github.com/csstools/postcss-plugins/workflows/test/badge.svg" height="20">][cli-url]
[<img alt="Discord" src="https://shields.io/badge/Discord-5865F2?logo=discord&logoColor=white">][discord]
<br><br>
[<img alt="Baseline Status" src="https://cssdb.org/images/badges-baseline/is-pseudo-class.svg" height="20">][css-url]
[![CSS Standard Status][css-img]][css-url]

[PostCSS Is Pseudo Class] lets you use the `:is` pseudo class function, following the
[CSS Selector] specification.

```pcss
:is(input, button):is(:hover, :focus) {
	order: 1;
}
```

Becomes :

```pcss
input:hover {
	order: 1;
}
input:focus {
	order: 1;
}
button:hover {
	order: 1;
}
button:focus {
	order: 1;
}
```

## Usage

Add [PostCSS Is Pseudo Class] to your project:

```bash
npm install @csstools/postcss-is-pseudo-class --save-dev
```

Use [PostCSS Is Pseudo Class] as a [PostCSS] plugin:

```js
import postcss from 'postcss';
import postcssIsPseudoClass from '@csstools/postcss-is-pseudo-class';

postcss([
  postcssIsPseudoClass(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```

[PostCSS Is Pseudo Class] runs in all Node environments, with special instructions for:

| [Node](INSTALL.md#node) | [Webpack](INSTALL.md#webpack) | [Gulp](INSTALL.md#gulp) | [Grunt](INSTALL.md#grunt) |
| --- | --- | --- | --- |

## Options

### preserve

The `preserve` option determines whether the original notation
is preserved. By default, it is not preserved.

```js
postcss([
  postcssIsPseudoClass({ preserve: true })
]).process(YOUR_CSS /*, processOptions */);
```

```pcss
:is(input, button):is(:hover, :focus) {
	order: 1;
}
```

Becomes :

```pcss
input:hover {
	order: 1;
}
input:focus {
	order: 1;
}
button:hover {
	order: 1;
}
button:focus {
	order: 1;
}
:is(input, button):is(:hover, :focus) {
	order: 1;
}
```

### specificityMatchingName

The `specificityMatchingName` option allows you to change the selector used to adjust specificity.
The default value is `does-not-exist`.
If this is an actual class, id or tag name in your code, you will need to set a different option here.

See how `:not` is used to modify [specificity](#specificity).

```js
postcss([
  postcssIsPseudoClass({ specificityMatchingName: 'something-random' })
]).process(YOUR_CSS /*, processOptions */);
```

```pcss
:is(.button, button):hover {
	order: 7;
}
```

Becomes :

```pcss
.button:hover {
	order: 7;
}

button:not(.something-random):hover {
	order: 7;
}
```

### onComplexSelector

Warn on complex selectors in `:is` pseudo class functions.

```js
postcss([
  postcssIsPseudoClass({ onComplexSelector: 'warning' })
]).process(YOUR_CSS /*, processOptions */);
```

### onPseudoElement

Warn when pseudo elements are used in `:is` pseudo class functions.

⚠️ Pseudo elements are always invalid and will be transformed to `::-csstools-invalid-<pseudo-name>`.

```js
postcss([
  postcssIsPseudoClass({ onPseudoElement: 'warning' })
]).process(YOUR_CSS /*, processOptions */);
```

```css
:is(::after):hover {
	order: 1.0;
}

/* becomes */

::-csstools-invalid-after:hover {
	order: 1.0;
}
```

## ⚠️ Known shortcomings

### Specificity

`:is` takes the specificity of the most specific list item.
We can increase specificity with `:not` selectors, but we can't decrease it.

Converted selectors are ensured to have the same specificity as `:is` for the most important bit.
Less important bits can have higher specificity that `:is`.

Before :

[specificity: 0, 2, 0](https://polypane.app/css-specificity-calculator/#selector=%3Ais(%3Ahover%2C%20%3Afocus)%3Ais(.button%2C%20button))

```pcss
:is(:hover, :focus):is(.button, button) {
	order: 7;
}
```

After :

```pcss
/* specificity: [0, 2, 0] */
.button:hover {
	order: 7;
}

/* specificity: [0, 2, 1] */
/* last bit is higher than it should be, but middle bit matches */
button:not(.does-not-exist):hover {
	order: 7;
}

/* specificity: [0, 2, 0] */
.button:focus {
	order: 7;
}

/* specificity: [0, 2, 1] */
/* last bit is higher than it should be, but middle bit matches */
button:not(.does-not-exist):focus {
	order: 7;
}
```

### Complex selectors

Before :


```pcss
:is(.alpha > .beta) ~ :is(:focus > .beta) {
	order: 2;
}
```

After :

```pcss
.alpha > .beta ~ :focus > .beta {
	order: 2;
}
```

_this is a different selector than expected as `.beta ~ :focus` matches `.beta` followed by `:focus`._<br>
_avoid these cases._<br>
_writing the selector without `:is()` is advised here_

```pcss
/* without is */
.alpha:focus > .beta ~ .beta {
	order: 2;
}
```

If you have a specific pattern you can open an issue to discuss it.
We can detect and transform some cases but can't generalize them into a single solution that tackles all of them. 

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-img]: https://cssdb.org/images/badges/is-pseudo-class.svg
[css-url]: https://cssdb.org/#is-pseudo-class
[discord]: https://discord.gg/bUadyRwkJS
[npm-img]: https://img.shields.io/npm/v/@csstools/postcss-is-pseudo-class.svg
[npm-url]: https://www.npmjs.com/package/@csstools/postcss-is-pseudo-class

[CSS Selector]: https://www.w3.org/TR/selectors-4/#matches
[PostCSS]: https://github.com/postcss/postcss
[PostCSS Is Pseudo Class]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-is-pseudo-class


---

# Changes to Selector Specificity

### 5.0.0

_October 23, 2024_

- Updated: `postcss-selector-parser`

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/packages/selector-specificity/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# Selector Specificity

[<img alt="npm version" src="https://img.shields.io/npm/v/@csstools/selector-specificity.svg" height="20">][npm-url]
[<img alt="Build Status" src="https://github.com/csstools/postcss-plugins/workflows/test/badge.svg" height="20">][cli-url]
[<img alt="Discord" src="https://shields.io/badge/Discord-5865F2?logo=discord&logoColor=white">][discord]

## Usage

Add [Selector Specificity] to your project:

```bash
npm install @csstools/selector-specificity --save-dev
```

```js
import parser from 'postcss-selector-parser';
import { selectorSpecificity } from '@csstools/selector-specificity';

const selectorAST = parser().astSync('#foo:has(> .foo)');
const specificity = selectorSpecificity(selectorAST);

console.log(specificity.a); // 1
console.log(specificity.b); // 1
console.log(specificity.c); // 0
```

_`selectorSpecificity` takes a single selector, not a list of selectors (not : `a, b, c`).
To compare or otherwise manipulate lists of selectors you need to call `selectorSpecificity` on each part._

### Comparing

The package exports a utility function to compare two specificities.

```js
import { selectorSpecificity, compare } from '@csstools/selector-specificity';

const s1 = selectorSpecificity(ast1);
const s2 = selectorSpecificity(ast2);
compare(s1, s2); // -1 | 0 | 1
```

- if `s1 < s2` then `compare(s1, s2)` returns a negative number (`< 0`)
- if `s1 > s2` then `compare(s1, s2)` returns a positive number (`> 0`)
- if `s1 === s2` then `compare(s1, s2)` returns zero (`=== 0`)

## Prior Art

- [keeganstreet/specificity](https://github.com/keeganstreet/specificity)
- [bramus/specificity](https://github.com/bramus/specificity)

For CSSTools we always use `postcss-selector-parser` and want to calculate specificity from this AST.

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/selector-specificity

[Selector Specificity]: https://github.com/csstools/postcss-plugins/tree/main/packages/selector-specificity


---

# API Documentation

*Please use only this documented API when working with the parser. Methods
not documented here are subject to change at any point.*

## `parser` function

This is the module's main entry point.

```js
const parser = require('postcss-selector-parser');
```

### `parser([transform], [options])`

Creates a new `processor` instance

```js
const processor = parser();
```

Or, with optional transform function

```js
const transform = selectors => {
    selectors.walkUniversals(selector => {
        selector.remove();
    });
};

const processor = parser(transform)

// Example
const result = processor.processSync('*.class');
// => .class
```

[See processor documentation](#processor)

Arguments:

* `transform (function)`: Provide a function to work with the parsed AST.
* `options (object)`: Provide default options for all calls on the returned `Processor`.

### `parser.attribute([props])`

Creates a new attribute selector.

```js
parser.attribute({attribute: 'href'});
// => [href]
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.className([props])`

Creates a new class selector.

```js
parser.className({value: 'button'});
// => .button
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.combinator([props])`

Creates a new selector combinator.

```js
parser.combinator({value: '+'});
// => +
```

Arguments:

* `props (object)`: The new node's properties.

Notes:
* **Descendant Combinators** The value of descendant combinators created by the
  parser always just a single space (`" "`). For descendant selectors with no
  comments, additional space is now stored in `node.spaces.before`. Depending
  on the location of comments, additional spaces may be stored in
  `node.raws.spaces.before`, `node.raws.spaces.after`, or `node.raws.value`.
* **Named Combinators** Although, nonstandard and unlikely to ever become a standard,
  named combinators like `/deep/` and `/for/` are parsed as combinators. The
  `node.value` is name after being unescaped and normalized as lowercase. The
  original value for the combinator name is stored in `node.raws.value`.


### `parser.comment([props])`

Creates a new comment.

```js
parser.comment({value: '/* Affirmative, Dave. I read you. */'});
// => /* Affirmative, Dave. I read you. */
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.id([props])`

Creates a new id selector.

```js
parser.id({value: 'search'});
// => #search
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.nesting([props])`

Creates a new nesting selector.

```js
parser.nesting();
// => &
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.pseudo([props])`

Creates a new pseudo selector.

```js
parser.pseudo({value: '::before'});
// => ::before
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.root([props])`

Creates a new root node.

```js
parser.root();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.selector([props])`

Creates a new selector node.

```js
parser.selector();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.string([props])`

Creates a new string node.

```js
parser.string();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.tag([props])`

Creates a new tag selector.

```js
parser.tag({value: 'button'});
// => button
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.universal([props])`

Creates a new universal selector.

```js
parser.universal();
// => *
```

Arguments:

* `props (object)`: The new node's properties.

## Node types

### `node.type`

A string representation of the selector type. It can be one of the following;
`attribute`, `class`, `combinator`, `comment`, `id`, `nesting`, `pseudo`,
`root`, `selector`, `string`, `tag`, or `universal`. Note that for convenience,
these constants are exposed on the main `parser` as uppercased keys. So for
example you can get `id` by querying `parser.ID`.

```js
parser.attribute({attribute: 'href'}).type;
// => 'attribute'
```

### `node.parent`

Returns the parent node.

```js
root.nodes[0].parent === root;
```

### `node.toString()`, `String(node)`, or `'' + node`

Returns a string representation of the node.

```js
const id = parser.id({value: 'search'});
console.log(String(id));
// => #search
```

### `node.next()` & `node.prev()`

Returns the next/previous child of the parent node.

```js
const next = id.next();
if (next && next.type !== 'combinator') {
    throw new Error('Qualified IDs are not allowed!');
}
```

### `node.replaceWith(node[,...nodeN])`

Replace a node with another.

```js
const attr = selectors.first.first;
const className = parser.className({value: 'test'});
attr.replaceWith(className);
```

Arguments:

* `node`: The node to substitute the original with.
...
* `nodeN`: The node to substitute the original with.

### `node.remove()`

Removes the node from its parent node.

```js
if (node.type === 'id') {
    node.remove();
}
```

### `node.clone([opts])`

Returns a copy of a node, detached from any parent containers that the
original might have had.

```js
const cloned = node.clone();
```

### `node.isAtPosition(line, column)`

Return a `boolean` indicating whether this node includes the character at the
position of the given line and column. Returns `undefined` if the nodes lack
sufficient source metadata to determine the position.

Arguments:

* `line`: 1-index based line number relative to the start of the selector.
* `column`: 1-index based column number relative to the start of the selector.

### `node.spaces`

Extra whitespaces around the node will be moved into `node.spaces.before` and
`node.spaces.after`. So for example, these spaces will be moved as they have
no semantic meaning:

```css
      h1     ,     h2   {}
```

For descendent selectors, the value is always a single space.

```css
h1        h2 {}
```

Additional whitespace is found in either the `node.spaces.before` and `node.spaces.after` depending on the presence of comments or other whitespace characters. If the actual whitespace does not start or end with a single space, the node's raw value is set to the actual space(s) found in the source.

### `node.source`

An object describing the node's start/end, line/column source position.

Within the following CSS, the `.bar` class node ...

```css
.foo,
  .bar {}
```

... will contain the following `source` object.

```js
source: {
    start: {
        line: 2,
        column: 3
    },
    end: {
        line: 2,
        column: 6
    }
}
```

### `node.sourceIndex`

The zero-based index of the node within the original source string.

Within the following CSS, the `.baz` class node will have a `sourceIndex` of `12`.

```css
.foo, .bar, .baz {}
```

## Container types

The `root`, `selector`, and `pseudo` nodes have some helper methods for working
with their children.

### `container.nodes`

An array of the container's children.

```js
// Input: h1 h2
selectors.at(0).nodes.length   // => 3
selectors.at(0).nodes[0].value // => 'h1'
selectors.at(0).nodes[1].value // => ' '
```

### `container.first` & `container.last`

The first/last child of the container.

```js
selector.first === selector.nodes[0];
selector.last === selector.nodes[selector.nodes.length - 1];
```

### `container.at(index)`

Returns the node at position `index`.

```js
selector.at(0) === selector.first;
selector.at(0) === selector.nodes[0];
```

Arguments:

* `index`: The index of the node to return.

### `container.atPosition(line, column)`

Returns the node at the source position `line` and `column`.

```js
// Input: :not(.foo),\n#foo > :matches(ol, ul)
selector.atPosition(1, 1); // => :not(.foo)
selector.atPosition(2, 1); // => \n#foo
```

Arguments:

* `line`: The line number of the node to return.
* `column`: The column number of the node to return.

### `container.index(node)`

Return the index of the node within its container.

```js
selector.index(selector.nodes[2]) // => 2
```

Arguments:

* `node`: A node within the current container.

### `container.length`

Proxy to the length of the container's nodes.

```js
container.length === container.nodes.length
```

### `container` Array iterators

The container class provides proxies to certain Array methods; these are:

* `container.map === container.nodes.map`
* `container.reduce === container.nodes.reduce`
* `container.every === container.nodes.every`
* `container.some === container.nodes.some`
* `container.filter === container.nodes.filter`
* `container.sort === container.nodes.sort`

Note that these methods only work on a container's immediate children; recursive
iteration is provided by `container.walk`.

### `container.each(callback)`

Iterate the container's immediate children, calling `callback` for each child.
You may return `false` within the callback to break the iteration.

```js
let className;
selectors.each((selector, index) => {
    if (selector.type === 'class') {
        className = selector.value;
        return false;
    }
});
```

Note that unlike `Array#forEach()`, this iterator is safe to use whilst adding
or removing nodes from the container.

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  and `index` arguments.

### `container.walk(callback)`

Like `container#each`, but will also iterate child nodes as long as they are
`container` types.

```js
selectors.walk((selector, index) => {
    // all nodes
});
```

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  and `index` arguments.

This iterator is safe to use whilst mutating `container.nodes`,
like `container#each`.

### `container.walk` proxies

The container class provides proxy methods for iterating over types of nodes,
so that it is easier to write modules that target specific selectors. Those
methods are:

* `container.walkAttributes`
* `container.walkClasses`
* `container.walkCombinators`
* `container.walkComments`
* `container.walkIds`
* `container.walkNesting`
* `container.walkPseudos`
* `container.walkTags`
* `container.walkUniversals`

### `container.split(callback)`

This method allows you to split a group of nodes by returning `true` from
a callback. It returns an array of arrays, where each inner array corresponds
to the groups that you created via the callback.

```js
// (input) => h1 h2>>h3
const list = selectors.first.split(selector => {
    return selector.type === 'combinator';
});

// (node values) => [['h1', ' '], ['h2', '>>'], ['h3']]
```

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  as an argument.

### `container.prepend(node)` & `container.append(node)`

Add a node to the start/end of the container. Note that doing so will set
the parent property of the node to this container.

```js
const id = parser.id({value: 'search'});
selector.append(id);
```

Arguments:

* `node`: The node to add.

### `container.insertBefore(old, new[, ...newNodes])` & `container.insertAfter(old, new[, ...newNodes])`

Add a node before or after an existing node in a container:

```js
selectors.walk(selector => {
    if (selector.type !== 'class') {
        const className = parser.className({value: 'theme-name'});
        selector.parent.insertAfter(selector, className);
    }
});
```

Arguments:

* `old`: The existing node in the container.
* `new`: The new node to add before/after the existing node.

### `container.removeChild(node)`

Remove the node from the container. Note that you can also use
`node.remove()` if you would like to remove just a single node.

```js
selector.length // => 2
selector.remove(id)
selector.length // => 1;
id.parent       // undefined
```

Arguments:

* `node`: The node to remove.

### `container.removeAll()` or `container.empty()`

Remove all children from the container.

```js
selector.removeAll();
selector.length // => 0
```

## Root nodes

A root node represents a comma separated list of selectors. Indeed, all
a root's `toString()` method does is join its selector children with a ','.
Other than this, it has no special functionality and acts like a container.

### `root.trailingComma`

This will be set to `true` if the input has a trailing comma, in order to
support parsing of legacy CSS hacks.

## Selector nodes

A selector node represents a single complex selector. For example, this
selector string `h1 h2 h3, [href] > p`, is represented as two selector nodes.
It has no special functionality of its own.

## Pseudo nodes

A pseudo selector extends a container node; if it has any parameters of its
own (such as `h1:not(h2, h3)`), they will be its children. Note that the pseudo
`value` will always contain the colons preceding the pseudo identifier. This
is so that both `:before` and `::before` are properly represented in the AST.

## Attribute nodes

### `attribute.quoted`

Returns `true` if the attribute's value is wrapped in quotation marks, false if it is not.
Remains `undefined` if there is no attribute value.

```css
[href=foo] /* false */
[href='foo'] /* true */
[href="foo"] /* true */
[href] /* undefined */
```

### `attribute.qualifiedAttribute`

Returns the attribute name qualified with the namespace if one is given.

### `attribute.offsetOf(part)`

 Returns the offset of the attribute part specified relative to the
 start of the node of the output string. This is useful in raising
 error messages about a specific part of the attribute, especially
 in combination with `attribute.sourceIndex`.

 Returns `-1` if the name is invalid or the value doesn't exist in this
 attribute.

 The legal values for `part` are:

 * `"ns"` - alias for "namespace"
 * `"namespace"` - the namespace if it exists.
 * `"attribute"` - the attribute name
 * `"attributeNS"` - the start of the attribute or its namespace
 * `"operator"` - the match operator of the attribute
 * `"value"` - The value (string or identifier)
 * `"insensitive"` - the case insensitivity flag

### `attribute.raws.unquoted`

Returns the unquoted content of the attribute's value.
Remains `undefined` if there is no attribute value.

```css
[href=foo] /* foo */
[href='foo'] /* foo */
[href="foo"] /* foo */
[href] /* undefined */
```

### `attribute.spaces`

Like `node.spaces` with the `before` and `after` values containing the spaces
around the element, the parts of the attribute can also have spaces before
and after them. The for each of `attribute`, `operator`, `value` and
`insensitive` there is corresponding property of the same nam in
`node.spaces` that has an optional `before` or `after` string containing only
whitespace.

Note that corresponding values in `attributes.raws.spaces` contain values
including any comments. If set, these values will override the
`attribute.spaces` value. Take care to remove them if changing
`attribute.spaces`.

### `attribute.raws`

The raws object stores comments and other information necessary to re-render
the node exactly as it was in the source.

If a comment is embedded within the identifiers for the `namespace`, `attribute`
or `value` then a property is placed in the raws for that value containing the full source of the propery including comments.

If a comment is embedded within the space between parts of the attribute
then the raw for that space is set accordingly.

Setting an attribute's property `raws` value to be deleted.

For now, changing the spaces required also updating or removing any of the
raws values that override them.

Example: `[ /*before*/ href /* after-attr */ = /* after-operator */ te/*inside-value*/st/* wow */ /*omg*/i/*bbq*/ /*whodoesthis*/]` would parse as:

```js
{
  attribute: "href",
  operator: "=",
  value: "test",
  spaces: {
    before: '',
    after: '',
    attribute: { before: '  ', after: '  ' },
    operator: { after: '  ' },
    value: { after: ' ' },
    insensitive: { after: ' ' }
  },
  raws: {
    spaces: {
      attribute: { before: ' /*before*/ ', after: ' /* after-attr */ ' },
      operator: { after: ' /* after-operator */ ' },
      value: { after: '/* wow */ /*omg*/' },
      insensitive: { after: '/*bbq*/ /*whodoesthis*/' }
    },
    unquoted: 'test',
    value: 'te/*inside-value*/st'
  }
}
```

## `Processor`

### `ProcessorOptions`

* `lossless` - When `true`, whitespace is preserved. Defaults to `true`.
* `updateSelector` - When `true`, if any processor methods are passed a postcss
  `Rule` node instead of a string, then that Rule's selector is updated
  with the results of the processing. Defaults to `true`.

### `process|processSync(selectors, [options])`

Processes the `selectors`, returning a string from the result of processing.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

**Example:**

```js
const parser = require("postcss-selector-parser");
const processor = parser();

let result = processor.processSync(' .class');
console.log(result);
// =>  .class

// Asynchronous operation
let promise = processor.process(' .class').then(result => {
    console.log(result)
    // => .class
});

// To have the parser normalize whitespace values, utilize the options
result = processor.processSync('  .class  ', {lossless: false});
console.log(result);
// => .class

// For better syntax errors, pass a PostCSS Rule node.
const postcss = require('postcss');
rule = postcss.rule({selector: ' #foo    > a,  .class  '});
processor.process(rule, {lossless: false, updateSelector: true}).then(result => {
    console.log(result);
    // => #foo>a,.class
    console.log("rule:", rule.selector);
    // => rule: #foo>a,.class
})
```

Arguments:

* `selectors (string|postcss.Rule)`: Either a selector string or a PostCSS Rule
  node.
* `[options] (object)`: Process options


### `ast|astSync(selectors, [options])`

Like `process()` and `processSync()` but after
processing the `selectors` these methods return the `Root` node of the result
instead of a string.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

### `transform|transformSync(selectors, [options])`

Like `process()` and `processSync()` but after
processing the `selectors` these methods return the value returned by the
processor callback.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

### Error Handling Within Selector Processors

The root node passed to the selector processor callback
has a method `error(message, options)` that returns an
error object. This method should always be used to raise
errors relating to the syntax of selectors. The options
to this method are passed to postcss's error constructor
([documentation](http://postcss.org/api/#container-error)).

#### Async Error Example

```js
let processor = (root) => {
    return new Promise((resolve, reject) => {
        root.walkClasses((classNode) => {
            if (/^(.*)[-_]/.test(classNode.value)) {
                let msg = "classes may not have underscores or dashes in them";
                reject(root.error(msg, {
                    index: classNode.sourceIndex + RegExp.$1.length + 1,
                    word: classNode.value
                }));
            }
        });
        resolve();
    });
};

const postcss = require("postcss");
const parser = require("postcss-selector-parser");
const selectorProcessor = parser(processor);
const plugin = postcss.plugin('classValidator', (options) => {
    return (root) => {
        let promises = [];
        root.walkRules(rule => {
            promises.push(selectorProcessor.process(rule));
        });
        return Promise.all(promises);
    };
});
postcss(plugin()).process(`
.foo-bar {
  color: red;
}
`.trim(), {from: 'test.css'}).catch((e) => console.error(e.toString()));

// CssSyntaxError: classValidator: ./test.css:1:5: classes may not have underscores or dashes in them
//
// > 1 | .foo-bar {
//     |     ^
//   2 |   color: red;
//   3 | }
```

#### Synchronous Error Example

```js
let processor = (root) => {
    root.walkClasses((classNode) => {
        if (/.*[-_]/.test(classNode.value)) {
            let msg = "classes may not have underscores or dashes in them";
            throw root.error(msg, {
                index: classNode.sourceIndex,
                word: classNode.value
            });
        }
    });
};

const postcss = require("postcss");
const parser = require("postcss-selector-parser");
const selectorProcessor = parser(processor);
const plugin = postcss.plugin('classValidator', (options) => {
    return (root) => {
        root.walkRules(rule => {
            selectorProcessor.processSync(rule);
        });
    };
});
postcss(plugin()).process(`
.foo-bar {
  color: red;
}
`.trim(), {from: 'test.css'}).catch((e) => console.error(e.toString()));

// CssSyntaxError: classValidator: ./test.css:1:5: classes may not have underscores or dashes in them
//
// > 1 | .foo-bar {
//     |     ^
//   2 |   color: red;
//   3 | }
```


---

# 7.1.0

- feat: insert(Before|After) support multiple new node

# 7.0.0

- Feat: make insertions during iteration safe (major)

# 6.1.2

- Fixed: erroneous trailing combinators in pseudos

# 6.1.1

- Fixed: improve typings of constructor helpers (#292)

# 6.1.0

- Feature: add `sourceIndex` to `Selector` nodes (#290)

# 6.0.16

- Fixed: add missing `index` argument to `each`/`walk` callback types (#289)

# 6.0.15

- Fixed: Node#prev and Node#next type for the first/last node

# 6.0.14

- Fixed: type definitions

# 6.0.13

- Fixed: throw on unexpected pipe symbols

# 6.0.12

- Fixed: `clone` arguments should be optional

# 6.0.11

- Fixed: parse attribute case insensitivity flag

# 6.0.10

- Fixed: `isPseudoElement()` supports `:first-letter` and `:first-line`

# 6.0.9

- Fixed: `Combinator.raws` property type

# 6.0.8

- Fixed: reduced size

# 6.0.7

- Fixed: parse animation percents

# 6.0.6

- Fixed: parse quoted attributes containing a newline correctly

# 6.0.5

- Perf: rework unesc for a 63+% performance boost

# 6.0.4

- Fixed: ts errors

# 6.0.3

- Fixed: replace node built-in "util" module with "util-deprecate"
- Fixed: handle uppercase pseudo elements
- Fixed: do not create invalid combinator before comment

# 6.0.2

- Fixed an issue with parsing and stringifying an empty attribute value

# 6.0.1

- Fixed an issue with unicode surrogate pair parsing

# 6.0.0

- Updated: `cssesc` to 3.0.0 (major)
- Fixed: Issues with escaped `id` and `class` selectors

# 5.0.0

- Allow escaped dot within class name.
- Update PostCSS to 7.0.7 (patch)

# 5.0.0-rc.4

- Fixed an issue where comments immediately after an insensitive (in attribute)
  were not parsed correctly.
- Updated `cssesc` to 2.0.0 (major).
- Removed outdated integration tests.
- Added tests for custom selectors, tags with attributes, the universal
  selector with pseudos, and tokens after combinators.

# 5.0.0-rc.1

To ease adoption of the v5.0 release, we have relaxed the node version
check performed by npm at installation time to allow for node 4, which
remains officially unsupported, but likely to continue working for the
time being.

# 5.0.0-rc.0

This release has **BREAKING CHANGES** that were required to fix regressions
in 4.0.0 and to make the Combinator Node API consistent for all combinator
types. Please read carefully.

## Summary of Changes

* The way a descendent combinator that isn't a single space character (E.g. `.a  .b`) is stored in the AST has changed.
* Named Combinators (E.g. `.a /for/ .b`) are now properly parsed as a combinator.
* It is now possible to look up a node based on the source location of a character in that node and to query nodes if they contain some character.
* Several bug fixes that caused the parser to hang and run out of memory when a `/` was encountered have been fixed.
* The minimum supported version of Node is now `v6.0.0`.

### Changes to the Descendent Combinator

In prior releases, the value of a descendant combinator with multiple spaces included all the spaces.

* `.a   .b`: Extra spaces are now stored as space before.
  - Old & Busted:
    - `combinator.value === "   "`
  - New hotness:
    - `combinator.value === " " && combinator.spaces.before === "  "`
* `.a   /*comment*/.b`: A comment at the end of the combinator causes extra space to become after space.
  - Old & Busted:
    - `combinator.value === "   "`
    - `combinator.raws.value === "   /*comment/"`
  - New hotness:
    - `combinator.value === " "`
    - `combinator.spaces.after === "  "`
    - `combinator.raws.spaces.after === "  /*comment*/"`
* `.a<newline>.b`: whitespace that doesn't start or end with a single space character is stored as a raw value.
  - Old & Busted:
    - `combinator.value === "\n"`
    - `combinator.raws.value === undefined`
  - New hotness:
    - `combinator.value === " "`
    - `combinator.raws.value === "\n"`

### Support for "Named Combinators"

Although, nonstandard and unlikely to ever become a standard, combinators like `/deep/` and `/for/` are now properly supported.

Because they've been taken off the standardization track, there is no spec-official name for combinators of the form `/<ident>/`. However, I talked to [Tab Atkins](https://twitter.com/tabatkins) and we agreed to call them "named combinators" so now they are called that.

Before this release such named combinators were parsed without intention and generated three nodes of type `"tag"` where the first and last nodes had a value of `"/"`.

* `.a /for/ .b` is parsed as a combinator.
  - Old & Busted:
    - `root.nodes[0].nodes[1].type === "tag"`
    - `root.nodes[0].nodes[1].value === "/"`
  - New hotness:
    - `root.nodes[0].nodes[1].type === "combinator"`
    - `root.nodes[0].nodes[1].value === "/for/"`
* `.a /F\6fR/ .b` escapes are handled and uppercase is normalized.
  - Old & Busted:
    - `root.nodes[0].nodes[2].type === "tag"`
    - `root.nodes[0].nodes[2].value === "F\\6fR"`
  - New hotness:
    - `root.nodes[0].nodes[1].type === "combinator"`
    - `root.nodes[0].nodes[1].value === "/for/"`
    - `root.nodes[0].nodes[1].raws.value === "/F\\6fR/"`

### Source position checks and lookups

A new API was added to look up a node based on the source location.

```js
const selectorParser = require("postcss-selector-parser");
// You can find the most specific node for any given character
let combinator = selectorParser.astSync(".a > .b").atPosition(1,4);
combinator.toString() === " > ";
// You can check if a node includes a specific character
// Whitespace surrounding the node that is owned by that node
// is included in the check.
[2,3,4,5,6].map(column => combinator.isAtPosition(1, column));
// => [false, true, true, true, false]
```

# 4.0.0

This release has **BREAKING CHANGES** that were required to fix bugs regarding values with escape sequences. Please read carefully.

* **Identifiers with escapes** - CSS escape sequences are now hidden from the public API by default.
  The normal value of a node like a class name or ID, or an aspect of a node such as attribute
  selector's value, is unescaped. Escapes representing Non-ascii characters are unescaped into
  unicode characters. For example: `bu\tton, .\31 00, #i\2764\FE0Fu, [attr="value is \"quoted\""]`
  will parse respectively to the values `button`, `100`, `i❤️u`, `value is "quoted"`.
  The original escape sequences for these values can be found in the corresponding property name
  in `node.raws`. Where possible, deprecation warnings were added, but the nature
  of escape handling makes it impossible to detect what is escaped or not. Our expectation is
  that most users are neither expecting nor handling escape sequences in their use of this library,
  and so for them, this is a bug fix. Users who are taking care to handle escapes correctly can
  now update their code to remove the escape handling and let us do it for them.

* **Mutating values with escapes** - When you make an update to a node property that has escape handling
  The value is assumed to be unescaped, and any special characters are escaped automatically and
  the corresponding `raws` value is immediately updated. This can result in changes to the original
  escape format. Where the exact value of the escape sequence is important there are methods that
  allow both values to be set in conjunction. There are a number of new convenience methods for
  manipulating values that involve escapes, especially for attributes values where the quote mark
  is involved. See https://github.com/postcss/postcss-selector-parser/pull/133 for an extensive
  write-up on these changes.


**Upgrade/API Example**

In `3.x` there was no unescape handling and internal consistency of several properties was the caller's job to maintain. It was very easy for the developer
to create a CSS file that did not parse correctly when some types of values
were in use.

```js
const selectorParser = require("postcss-selector-parser");
let attr = selectorParser.attribute({attribute: "id", operator: "=", value: "a-value"});
attr.value; // => "a-value"
attr.toString(); // => [id=a-value]
// Add quotes to an attribute's value.
// All these values have to be set by the caller to be consistent:
// no internal consistency is maintained.
attr.raws.unquoted = attr.value
attr.value = "'" + attr.value + "'";
attr.value; // => "'a-value'"
attr.quoted = true;
attr.toString();  // => "[id='a-value']"
```

In `4.0` there is a convenient API for setting and mutating values
that may need escaping. Especially for attributes.

```js
const selectorParser = require("postcss-selector-parser");

// The constructor requires you specify the exact escape sequence
let className = selectorParser.className({value: "illegal class name", raws: {value: "illegal\\ class\\ name"}});
className.toString(); // => '.illegal\\ class\\ name'

// So it's better to set the value as a property
className = selectorParser.className();
// Most properties that deal with identifiers work like this
className.value = "escape for me";
className.value; // => 'escape for me'
className.toString(); // => '.escape\\ for\\ me'

// emoji and all non-ascii are escaped to ensure it works in every css file.
className.value = "😱🦄😍";
className.value; // => '😱🦄😍'
className.toString(); // => '.\\1F631\\1F984\\1F60D'

// you can control the escape sequence if you want, or do bad bad things
className.setPropertyAndEscape('value', 'xxxx', 'yyyy');
className.value; // => "xxxx"
className.toString(); // => ".yyyy"

// Pass a value directly through to the css output without escaping it. 
className.setPropertyWithoutEscape('value', '$REPLACE_ME$');
className.value; // => "$REPLACE_ME$"
className.toString(); // => ".$REPLACE_ME$"

// The biggest changes are to the Attribute class
// passing quoteMark explicitly is required to avoid a deprecation warning.
let attr = selectorParser.attribute({attribute: "id", operator: "=", value: "a-value", quoteMark: null});
attr.toString(); // => "[id=a-value]"
// Get the value with quotes on it and any necessary escapes.
// This is the same as reading attr.value in 3.x.
attr.getQuotedValue(); // => "a-value";
attr.quoteMark; // => null

// Add quotes to an attribute's value.
attr.quoteMark = "'"; // This is all that's required.
attr.toString(); // => "[id='a-value']"
attr.quoted; // => true
// The value is still the same, only the quotes have changed.
attr.value; // => a-value
attr.getQuotedValue(); // => "'a-value'";

// deprecated assignment, no warning because there's no escapes
attr.value = "new-value";
// no quote mark is needed so it is removed
attr.getQuotedValue(); // => "new-value";

// deprecated assignment, 
attr.value = "\"a 'single quoted' value\"";
// > (node:27859) DeprecationWarning: Assigning an attribute a value containing characters that might need to be escaped is deprecated. Call attribute.setValue() instead.
attr.getQuotedValue(); // => '"a \'single quoted\' value"';
// quote mark inferred from first and last characters.
attr.quoteMark; // => '"'

// setValue takes options to make manipulating the value simple.
attr.setValue('foo', {smart: true});
// foo doesn't require any escapes or quotes.
attr.toString(); // => '[id=foo]'
attr.quoteMark; // => null 

// An explicit quote mark can be specified
attr.setValue('foo', {quoteMark: '"'});
attr.toString(); // => '[id="foo"]'

// preserves quote mark by default
attr.setValue('bar');
attr.toString(); // => '[id="bar"]'
attr.quoteMark = null;
attr.toString(); // => '[id=bar]'

// with no arguments, it preserves quote mark even when it's not a great idea
attr.setValue('a value \n that should be quoted');
attr.toString(); // => '[id=a\\ value\\ \\A\\ that\\ should\\ be\\ quoted]'

// smart preservation with a specified default
attr.setValue('a value \n that should be quoted', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => "[id='a value \\A  that should be quoted']"
attr.quoteMark = '"';
// => '[id="a value \\A  that should be quoted"]'

// this keeps double quotes because it wants to quote the value and the existing value has double quotes.
attr.setValue('this should be quoted', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => '[id="this should be quoted"]'

// picks single quotes because the value has double quotes
attr.setValue('a "double quoted" value', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => "[id='a "double quoted" value']"

// setPropertyAndEscape lets you do anything you want. Even things that are a bad idea and illegal.
attr.setPropertyAndEscape('value', 'xxxx', 'the password is 42');
attr.value; // => "xxxx"
attr.toString(); // => "[id=the password is 42]"

// Pass a value directly through to the css output without escaping it. 
attr.setPropertyWithoutEscape('value', '$REPLACEMENT$');
attr.value; // => "$REPLACEMENT$"
attr.toString(); // => "[id=$REPLACEMENT$]"
```

# 3.1.2

* Fix: Removed dot-prop dependency since it's no longer written in es5.

# 3.1.1

* Fix: typescript definitions weren't in the published package.

# 3.1.0

* Fixed numerous bugs in attribute nodes relating to the handling of comments
  and whitespace. There's significant changes to `attrNode.spaces` and `attrNode.raws` since the `3.0.0` release.
* Added `Attribute#offsetOf(part)` to get the offset location of
  attribute parts like `"operator"` and `"value"`. This is most
  often added to `Attribute#sourceIndex` for error reporting.

# 3.0.0

## Breaking changes

* Some tweaks to the tokenizer/attribute selector parsing mean that whitespace
  locations might be slightly different to the 2.x code.
* Better attribute selector parsing with more validation; postcss-selector-parser
  no longer uses regular expressions to parse attribute selectors.
* Added an async API (thanks to @jacobp100); the default `process` API is now
  async, and the sync API is now accessed through `processSync` instead.
* `process()` and `processSync()` now return a string instead of the Processor
  instance.
* Tweaks handling of Less interpolation (thanks to @jwilsson).
* Removes support for Node 0.12.

## Other changes

* `ast()` and `astSync()` methods have been added to the `Processor`. These
  return the `Root` node of the selectors after processing them.
* `transform()` and `transformSync()` methods have been added to the
  `Processor`. These return the value returned by the processor callback
  after processing the selectors.
* Set the parent when inserting a node (thanks to @chriseppstein).
* Correctly adjust indices when using insertBefore/insertAfter (thanks to @tivac).
* Fixes handling of namespaces with qualified tag selectors.
* `process`, `ast` and `transform` (and their sync variants) now accept a
  `postcss` rule node. When provided, better errors are generated and selector
  processing is automatically set back to the rule selector (unless the `updateSelector` option is set to `false`.)
* Now more memory efficient when tokenizing selectors.

### Upgrade hints

The pattern of:

`rule.selector = processor.process(rule.selector).result.toString();`

is now:

`processor.processSync(rule)`

# 2.2.3

* Resolves an issue where the parser would not reduce multiple spaces between an
  ampersand and another simple selector in lossy mode (thanks to @adam-26).

# 2.2.2

* No longer hangs on an unescaped semicolon; instead the parser will throw
  an exception for these cases.

# 2.2.1

* Allows a consumer to specify whitespace tokens when creating a new Node
  (thanks to @Semigradsky).

# 2.2.0

* Added a new option to normalize whitespace when parsing the selector string
  (thanks to @adam-26).

# 2.1.1

* Better unquoted value handling within attribute selectors
  (thanks to @evilebottnawi).

# 2.1.0

* Added: Use string constants for all node types & expose them on the main
  parser instance (thanks to @Aweary).

# 2.0.0

This release contains the following breaking changes:

* Renamed all `eachInside` iterators to `walk`. For example, `eachTag` is now
  `walkTags`, and `eachInside` is now `walk`.
* Renamed `Node#removeSelf()` to `Node#remove()`.
* Renamed `Container#remove()` to `Container#removeChild()`.
* Renamed `Node#raw` to `Node#raws` (thanks to @davidtheclark).
* Now parses `&` as the *nesting* selector, rather than a *tag* selector.
* Fixes misinterpretation of Sass interpolation (e.g. `#{foo}`) as an
  id selector (thanks to @davidtheclark).

and;

* Fixes parsing of attribute selectors with equals signs in them
  (e.g. `[data-attr="foo=bar"]`) (thanks to @montmanu).
* Adds `quoted` and `raw.unquoted` properties to attribute nodes
  (thanks to @davidtheclark).

# 1.3.3

* Fixes an infinite loop on `)` and `]` tokens when they had no opening pairs.
  Now postcss-selector-parser will throw when it encounters these lone tokens.

# 1.3.2

* Now uses plain integers rather than `str.charCodeAt(0)` for compiled builds.

# 1.3.1

* Update flatten to v1.x (thanks to @shinnn).

# 1.3.0

* Adds a new node type, `String`, to fix a crash on selectors such as
  `foo:bar("test")`.

# 1.2.1

* Fixes a crash when the parser encountered a trailing combinator.

# 1.2.0

* A more descriptive error is thrown when the parser expects to find a
  pseudo-class/pseudo-element (thanks to @ashelley).
* Adds support for line/column locations for selector nodes, as well as a
  `Node#sourceIndex` method (thanks to @davidtheclark).

# 1.1.4

* Fixes a crash when a selector started with a `>` combinator. The module will
  now no longer throw if a selector has a leading/trailing combinator node.

# 1.1.3

* Fixes a crash on `@` tokens.

# 1.1.2

* Fixes an infinite loop caused by using parentheses in a non-pseudo element
  context.

# 1.1.1

* Fixes a crash when a backslash ended a selector string.

# 1.1.0

* Adds support for replacing multiple nodes at once with `replaceWith`
  (thanks to @jonathantneal).
* Parser no longer throws on sequential IDs and trailing commas, to support
  parsing of selector hacks.

# 1.0.1

* Fixes using `insertAfter` and `insertBefore` during iteration.

# 1.0.0

* Adds `clone` and `replaceWith` methods to nodes.
* Adds `insertBefore` and `insertAfter` to containers.
* Stabilises API.

# 0.0.5

* Fixes crash on extra whitespace inside a pseudo selector's parentheses.
* Adds sort function to the container class.
* Enables the parser to pass its input through without transforming.
* Iteration-safe `each` and `eachInside`.

# 0.0.4

* Tidy up redundant duplication.
* Fixes a bug where the parser would loop infinitely on universal selectors
  inside pseudo selectors.
* Adds `length` getter and `eachInside`, `map`, `reduce` to the container class.
* When a selector has been removed from the tree, the root node will no longer
  cast it to a string.
* Adds node type iterators to the container class (e.g. `eachComment`).
* Adds filter function to the container class.
* Adds split function to the container class.
* Create new node types by doing `parser.id(opts)` etc.
* Adds support for pseudo classes anywhere in the selector.

# 0.0.3

* Adds `next` and `prev` to the node class.
* Adds `first` and `last` getters to the container class.
* Adds `every` and `some` iterators to the container class.
* Add `empty` alias for `removeAll`.
* Combinators are now types of node.
* Fixes the at method so that it is not an alias for `index`.
* Tidy up creation of new nodes in the parser.
* Refactors how namespaces are handled for consistency & less redundant code.
* Refactors AST to use `nodes` exclusively, and eliminates excessive nesting.
* Fixes nested pseudo parsing.
* Fixes whitespace parsing.

# 0.0.2

* Adds support for namespace selectors.
* Adds support for selectors joined by escaped spaces - such as `.\31\ 0`.

# 0.0.1

* Initial release.


---

# postcss-selector-parser [![test](https://github.com/postcss/postcss-selector-parser/actions/workflows/test.yml/badge.svg)](https://github.com/postcss/postcss-selector-parser/actions/workflows/test.yml)

> Selector parser with built in methods for working with selector strings.

## Install

With [npm](https://npmjs.com/package/postcss-selector-parser) do:

```
npm install postcss-selector-parser
```

## Quick Start

```js
const parser = require('postcss-selector-parser');
const transform = selectors => {
    selectors.walk(selector => {
        // do something with the selector
        console.log(String(selector))
    });
};

const transformed = parser(transform).processSync('h1, h2, h3');
```

To normalize selector whitespace:

```js
const parser = require('postcss-selector-parser');
const normalized = parser().processSync('h1, h2, h3', {lossless: false});
// -> h1,h2,h3
```

Async support is provided through `parser.process` and will resolve a Promise
with the resulting selector string.

## API

Please see [API.md](API.md).

## Credits

* Huge thanks to Andrey Sitnik (@ai) for work on PostCSS which helped
  accelerate this module's development.

## License

MIT


---

# Changes to PostCSS Light Dark Function

### 2.0.7

_November 1, 2024_

- Updated [`@csstools/css-tokenizer`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-tokenizer) to [`3.0.3`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-tokenizer/CHANGELOG.md#303) (patch)
- Updated [`@csstools/css-parser-algorithms`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-parser-algorithms) to [`3.0.4`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-parser-algorithms/CHANGELOG.md#304) (patch)

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-light-dark-function/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Light Dark Function [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install @csstools/postcss-light-dark-function --save-dev`

[PostCSS Light Dark Function] lets you use the `light-dark` color function in
CSS, following the [CSS Color 5 Specification].

Read more about this feature on mdn:
- define the colors for light and dark with [`light-dark()`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/light-dark)
- define which elements support light and/or dark with [`color-scheme`](https://developer.mozilla.org/en-US/docs/Web/CSS/color-scheme)

With both features combined you can mix and match color schemes in a single document, while also respecting the user's preferences.

```pcss
.foo {
	color: light-dark(pink, magenta);
}

.bar {
	--bar: light-dark(cyan, deepskyblue);
}

/* becomes */

.foo {
	--csstools-light-dark-toggle--0: var(--csstools-color-scheme--light) magenta;
	color: var(--csstools-light-dark-toggle--0, pink);
	color: light-dark(pink, magenta);
}

.bar {
	--csstools-light-dark-toggle--1: var(--csstools-color-scheme--light) deepskyblue;
	--bar: var(--csstools-light-dark-toggle--1, cyan);
	@supports not (color: light-dark(tan, tan)) {

		& * {
	--csstools-light-dark-toggle--1: var(--csstools-color-scheme--light) deepskyblue;
	--bar: var(--csstools-light-dark-toggle--1, cyan);
		}
	}
}

@supports (color: light-dark(red, red)) {
.bar {
	--bar: light-dark(cyan, deepskyblue);
}
}
```

Declare that your document supports both light and dark mode:

```pcss
:root {
	color-scheme: light dark;
}

/* becomes */

:root {
	--csstools-color-scheme--light: initial;
	color-scheme: light dark;
}@media (prefers-color-scheme: dark) {:root {
	--csstools-color-scheme--light:  ;
}
}
```

Dynamically alter the supported color scheme for some elements:

```pcss
:root {
	/* Root only supports light mode */
	color-scheme: light;
}

.foo {
	/* This element and its children only support dark mode */
	color-scheme: dark;
}

/* becomes */

:root {
	/* Root only supports light mode */
	--csstools-color-scheme--light: initial;
	color-scheme: light;
}

.foo {
	/* This element and its children only support dark mode */
	--csstools-color-scheme--light:  ;
	color-scheme: dark;
}
```

## Usage

Add [PostCSS Light Dark Function] to your project:

```bash
npm install postcss @csstools/postcss-light-dark-function --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssLightDarkFunction = require('@csstools/postcss-light-dark-function');

postcss([
	postcssLightDarkFunction(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## Options

### preserve

The `preserve` option determines whether the original notation
is preserved. By default, it is preserved.

```js
postcssLightDarkFunction({ preserve: false })
```

```pcss
.foo {
	color: light-dark(pink, magenta);
}

.bar {
	--bar: light-dark(cyan, deepskyblue);
}

/* becomes */

.foo {
	--csstools-light-dark-toggle--0: var(--csstools-color-scheme--light) magenta;
	color: var(--csstools-light-dark-toggle--0, pink);
}

.bar {
	--csstools-light-dark-toggle--1: var(--csstools-color-scheme--light) deepskyblue;
	--bar: var(--csstools-light-dark-toggle--1, cyan);
	& * {
	--csstools-light-dark-toggle--1: var(--csstools-color-scheme--light) deepskyblue;
	--bar: var(--csstools-light-dark-toggle--1, cyan);
	}
}
```

### enableProgressiveCustomProperties

The `enableProgressiveCustomProperties` option determines whether the original notation
is wrapped with `@supports` when used in Custom Properties. By default, it is enabled.

> [!NOTE]
> We only recommend disabling this when you set `preserve` to `false` or if you bring your own fix for Custom Properties.  
> See what the plugin does in its [README](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-progressive-custom-properties#readme).

```js
postcssLightDarkFunction({ enableProgressiveCustomProperties: false })
```

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#light-dark-function
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/postcss-light-dark-function

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Light Dark Function]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-light-dark-function
[CSS Color 5 Specification]: https://drafts.csswg.org/css-color-5/#light-dark


---

# Changes to PostCSS Logical Float And Clear

### 3.0.0

_August 3, 2024_

- Updated: Support for Node v18+ (major).

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-logical-float-and-clear/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Logical Float And Clear [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install @csstools/postcss-logical-float-and-clear --save-dev`

[PostCSS Logical Float And Clear] lets you use logical, rather than physical, direction and dimension mappings in CSS, following the [CSS Logical Properties and Values] specification.

```pcss
.element {
	clear: inline-start;
	float: inline-end;
}

/* becomes */

.element {
	clear: left;
	float: right;
}
```

## Usage

Add [PostCSS Logical Float And Clear] to your project:

```bash
npm install postcss @csstools/postcss-logical-float-and-clear --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssLogicalFloatAndClear = require('@csstools/postcss-logical-float-and-clear');

postcss([
	postcssLogicalFloatAndClear(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## Options

### inlineDirection

The `inlineDirection` option allows you to specify the direction of the inline axe. The default value is `left-to-right`, which would match any latin language.

**You should tweak this value so that it is specific to your language and writing mode.**

```js
postcssLogicalFloatAndClear({
	inlineDirection: 'right-to-left'
})
```

```pcss
.element {
	clear: inline-start;
	float: inline-end;
}

/* becomes */

.element {
	clear: right;
	float: left;
}
```

Each direction must be one of the following:

- `top-to-bottom`
- `bottom-to-top`
- `left-to-right`
- `right-to-left`

Please do note that transformations won't run if `inlineDirection` becomes vertical.

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#float-clear-logical-values
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/postcss-logical-float-and-clear

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Logical Float And Clear]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-logical-float-and-clear
[CSS Logical Properties and Values]: https://www.w3.org/TR/css-logical-1/#float-clear


---

# Changes to PostCSS Logical Overflow

### 2.0.0

_August 3, 2024_

- Updated: Support for Node v18+ (major).

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-logical-overflow/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Logical Overflow [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install @csstools/postcss-logical-overflow --save-dev`

[PostCSS Logical Overflow] lets you use `overflow-inline` and `overflow-block` properties following the [CSS Overflow Specification].

```pcss
.inline {
	overflow-inline: clip;
}

.block {
	overflow-block: scroll;
}

/* becomes */

.inline {
	overflow-x: clip;
}

.block {
	overflow-y: scroll;
}
```

## Usage

Add [PostCSS Logical Overflow] to your project:

```bash
npm install postcss @csstools/postcss-logical-overflow --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssLogicalOverflow = require('@csstools/postcss-logical-overflow');

postcss([
	postcssLogicalOverflow(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## Options

### inlineDirection

The `inlineDirection` option allows you to specify the direction of the inline axe. The default value is `left-to-right`, which would match any latin language.

**You should tweak this value so that it is specific to your language and writing mode.**

```js
postcssLogicalOverflow({
	inlineDirection: 'top-to-bottom'
})
```

```pcss
.inline {
	overflow-inline: clip;
}

.block {
	overflow-block: scroll;
}

/* becomes */

.inline {
	overflow-y: clip;
}

.block {
	overflow-x: scroll;
}
```

Each direction must be one of the following:

- `top-to-bottom`
- `bottom-to-top`
- `left-to-right`
- `right-to-left`

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#logical-overflow
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/postcss-logical-overflow

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Logical Overflow]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-logical-overflow
[CSS Overflow Specification]: https://www.w3.org/TR/css-overflow-3/#overflow-control


---

# Changes to PostCSS Logical Overscroll Behavior

### 2.0.0

_August 3, 2024_

- Updated: Support for Node v18+ (major).

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-logical-overscroll-behavior/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Logical Overscroll Behavior [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install @csstools/postcss-logical-overscroll-behavior --save-dev`

[PostCSS Logical Overscroll Behavior] lets you use `overscroll-behavior-inline` and `overscroll-behavior-block` properties following the [CSS Overscroll Specification].

```pcss
.inline {
	overscroll-behavior-inline: auto;
}

.block {
	overscroll-behavior-block: contain;
}

/* becomes */

.inline {
	overscroll-behavior-x: auto;
}

.block {
	overscroll-behavior-y: contain;
}
```

## Usage

Add [PostCSS Logical Overscroll Behavior] to your project:

```bash
npm install postcss @csstools/postcss-logical-overscroll-behavior --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssLogicalOverscrollBehavior = require('@csstools/postcss-logical-overscroll-behavior');

postcss([
	postcssLogicalOverscrollBehavior(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## Options

### inlineDirection

The `inlineDirection` option allows you to specify the direction of the inline axe. The default value is `left-to-right`, which would match any latin language.

**You should tweak this value so that it is specific to your language and writing mode.**

```js
postcssLogicalOverscrollBehavior({
	inlineDirection: 'top-to-bottom'
})
```

```pcss
.inline {
	overscroll-behavior-inline: auto;
}

.block {
	overscroll-behavior-block: contain;
}

/* becomes */

.inline {
	overscroll-behavior-y: auto;
}

.block {
	overscroll-behavior-x: contain;
}
```

Each direction must be one of the following:

- `top-to-bottom`
- `bottom-to-top`
- `left-to-right`
- `right-to-left`

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#logical-overscroll-behavior
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/postcss-logical-overscroll-behavior

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Logical Overscroll Behavior]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-logical-overscroll-behavior
[CSS Overscroll Specification]: https://www.w3.org/TR/css-overscroll-1/#overscroll-behavior-longhands-logical


---

# Changes to PostCSS Logical Resize

### 3.0.0

_August 3, 2024_

- Updated: Support for Node v18+ (major).

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-logical-resize/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Logical Resize [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install @csstools/postcss-logical-resize --save-dev`

[PostCSS Logical Resize] lets you use logical, rather than physical, values for `resize`, following the [CSS Logical Properties and Values] specification.

```pcss
.resize-block {
	resize: block;
}

.resize-inline {
	resize: inline;
}

/* becomes */

.resize-block {
	resize: vertical;
}

.resize-inline {
	resize: horizontal;
}
```

## Usage

Add [PostCSS Logical Resize] to your project:

```bash
npm install postcss @csstools/postcss-logical-resize --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssLogicalResize = require('@csstools/postcss-logical-resize');

postcss([
	postcssLogicalResize(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## Options

### blockDirection & inlineDirection

The `blockDirection` and `inlineDirection` options allow you to specify the direction of the block and inline axes. The default values are `top-to-bottom` and `left-to-right` respectively, which would match any latin language.

**You should tweak these values so that they are specific to your language and writing mode.**

```js
postcssLogicalResize({
	blockDirection: 'right-to-left',
	inlineDirection: 'top-to-bottom'
})
```

```pcss
.resize-block {
	resize: block;
}

.resize-inline {
	resize: inline;
}

/* becomes */

.resize-block {
	resize: horizontal;
}

.resize-inline {
	resize: vertical;
}
```

Each direction must be one of the following:

- `top-to-bottom`
- `bottom-to-top`
- `left-to-right`
- `right-to-left`

You can't mix two vertical directions or two horizontal directions so for example `top-to-bottom` and `right-to-left` are valid, but `top-to-bottom` and `bottom-to-top` are not.

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#logical-resize
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/postcss-logical-resize

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Logical Resize]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-logical-resize
[CSS Logical Properties and Values]: https://www.w3.org/TR/css-logical-1/


---

# Changes to PostCSS Logical Viewport Units

### 3.0.3

_November 1, 2024_

- Updated [`@csstools/css-tokenizer`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-tokenizer) to [`3.0.3`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-tokenizer/CHANGELOG.md#303) (patch)

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-logical-viewport-units/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Logical Viewport Units [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install @csstools/postcss-logical-viewport-units --save-dev`

[PostCSS Logical Viewport Units] lets you easily use `vb` and `vi` length units following the [CSS-Values-4 Specification].

```pcss
.foo {
	margin: 10vi 20vb;
}

/* becomes */

.foo {
	margin: 10vw 20vh;
	margin: 10vi 20vb;
}
```

## Usage

Add [PostCSS Logical Viewport Units] to your project:

```bash
npm install postcss @csstools/postcss-logical-viewport-units --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssLogicalViewportUnits = require('@csstools/postcss-logical-viewport-units');

postcss([
	postcssLogicalViewportUnits(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## Options

### inlineDirection

The `inlineDirection` option allows you to specify the direction of the inline axe. The default value is `left-to-right`, which would match any latin language.

**You should tweak this value so that it is specific to your language and writing mode.**

```js
postcssLogicalViewportUnits({
	inlineDirection: 'top-to-bottom'
})
```

```pcss
.foo {
	margin: 10vi 20vb;
}

/* becomes */

.foo {
	margin: 10vh 20vw;
	margin: 10vi 20vb;
}
```

Each direction must be one of the following:

- `top-to-bottom`
- `bottom-to-top`
- `left-to-right`
- `right-to-left`

Please do note that transformations won't do anything particular for `right-to-left` or `bottom-to-top`.

### preserve

The `preserve` option determines whether the original notation
is preserved. By default, it is preserved.

```js
postcssLogicalViewportUnits({ preserve: false })
```

```pcss
.foo {
	margin: 10vi 20vb;
}

/* becomes */

.foo {
	margin: 10vw 20vh;
}
```

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#logical-viewport-units
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/postcss-logical-viewport-units

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Logical Viewport Units]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-logical-viewport-units
[CSS-Values-4 Specification]: https://www.w3.org/TR/css-values-4/#viewport-relative-units


---

# Changes to PostCSS Media MinMax

### 2.0.7

_February 23, 2025_

- Updated [`@csstools/css-calc`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-calc) to [`2.1.2`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-calc/CHANGELOG.md#212) (patch)

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-media-minmax/CHANGELOG.md)


---

The MIT License (MIT)

Copyright (c) 2022 Romain Menke, Antonio Laguna <antonio@laguna.es>, PostCSS

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Media MinMax [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install @csstools/postcss-media-minmax --save-dev`

[PostCSS Media MinMax] lets you use the range notation in media queries following the [Media Queries 4 Specification].

```css
@media screen and (width >=500px) and (width <=1200px) {
	.bar {
		display: block;
	}
}

/* becomes */

@media screen and (min-width:500px) and (max-width:1200px) {
	.bar {
		display: block;
	}
}
```

## Usage

Add [PostCSS Media MinMax] to your project:

```bash
npm install postcss @csstools/postcss-media-minmax --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssMediaMinMax = require('@csstools/postcss-media-minmax');

postcss([
	postcssMediaMinMax(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



_See prior work by [yisibl](https://github.com/yisibl) here [postcss-media-minmax](https://github.com/postcss/postcss-media-minmax)
To ensure long term maintenance and to provide the needed features this plugin was recreated based on yisibl's work._

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#media-query-ranges
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/postcss-media-minmax

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Media MinMax]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-media-minmax
[Media Queries 4 Specification]: https://www.w3.org/TR/mediaqueries-4/#mq-features


---

# Changes to PostCSS Media Queries Aspect-Ratio Number Values

### 3.0.4

_November 1, 2024_

- Updated [`@csstools/css-tokenizer`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-tokenizer) to [`3.0.3`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-tokenizer/CHANGELOG.md#303) (patch)
- Updated [`@csstools/css-parser-algorithms`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-parser-algorithms) to [`3.0.4`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-parser-algorithms/CHANGELOG.md#304) (patch)
- Updated [`@csstools/media-query-list-parser`](https://github.com/csstools/postcss-plugins/tree/main/packages/media-query-list-parser) to [`4.0.2`](https://github.com/csstools/postcss-plugins/tree/main/packages/media-query-list-parser/CHANGELOG.md#402) (patch)

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-media-queries-aspect-ratio-number-values/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Media Queries Aspect-Ratio Number Values [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install @csstools/postcss-media-queries-aspect-ratio-number-values --save-dev`

[PostCSS Media Queries Aspect-Ratio Number Values] lets you use non-integer numbers and `calc()` in `aspect-ratio` feature queries following the [Media Queries 4 Specification].

```pcss
@media (min-aspect-ratio: 1.77) {}

/* becomes */

@media (min-aspect-ratio: 177/100) {}
```

## Usage

Add [PostCSS Media Queries Aspect-Ratio Number Values] to your project:

```bash
npm install postcss @csstools/postcss-media-queries-aspect-ratio-number-values --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssMediaQueriesAspectRatioNumberValues = require('@csstools/postcss-media-queries-aspect-ratio-number-values');

postcss([
	postcssMediaQueriesAspectRatioNumberValues(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## Options

### preserve

The `preserve` option determines whether the original notation
is preserved. By default, it is not preserved.

```js
postcssMediaQueriesAspectRatioNumberValues({ preserve: true })
```

```pcss
@media (min-aspect-ratio: 1.77) {}

/* becomes */

@media (min-aspect-ratio: 1.77),(min-aspect-ratio: 177/100) {}
```

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#media-queries-aspect-ratio-number-values
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/postcss-media-queries-aspect-ratio-number-values

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Media Queries Aspect-Ratio Number Values]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-media-queries-aspect-ratio-number-values
[Media Queries 4 Specification]: https://www.w3.org/TR/mediaqueries-4/#aspect-ratio


---

# Changes to PostCSS Nested Calc

### 4.0.0

_August 3, 2024_

- Updated: Support for Node v18+ (major).
- Updated [`@csstools/utilities`](https://github.com/csstools/postcss-plugins/tree/main/packages/utilities) to [`2.0.0`](https://github.com/csstools/postcss-plugins/tree/main/packages/utilities/CHANGELOG.md#200) (major)

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-nested-calc/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Nested Calc [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install @csstools/postcss-nested-calc --save-dev`

[PostCSS Nested Calc] lets you use nested `calc()` expressions following the [CSS Values and Units 4 specification].

```pcss
.example {
	order: calc(1 + calc(2 * 2));
}

/* becomes */

.example {
	order: calc(1 + (2 * 2));
	order: calc(1 + calc(2 * 2));
}
```

## Usage

Add [PostCSS Nested Calc] to your project:

```bash
npm install postcss @csstools/postcss-nested-calc --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssNestedCalc = require('@csstools/postcss-nested-calc');

postcss([
	postcssNestedCalc(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## Options

### preserve

The `preserve` option determines whether the original notation
is preserved. By default the original values are preserved.

```js
postcssNestedCalc({ preserve: false })
```

```pcss
.example {
	order: calc(1 + calc(2 * 2));
}

/* becomes */

.example {
	order: calc(1 + (2 * 2));
}
```

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#nested-calc
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/postcss-nested-calc

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Nested Calc]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-nested-calc
[CSS Values and Units 4 specification]: https://www.w3.org/TR/css-values/#calc-func


---

# Changes to PostCSS Normalize Display Values

### 4.0.0

_August 3, 2024_

- Updated: Support for Node v18+ (major).

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-normalize-display-values/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Normalize Display Values [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][postcss]

[<img alt="npm version" src="https://img.shields.io/npm/v/@csstools/postcss-normalize-display-values.svg" height="20">][npm-url]
[<img alt="Build Status" src="https://github.com/csstools/postcss-plugins/workflows/test/badge.svg" height="20">][cli-url]
[<img alt="Discord" src="https://shields.io/badge/Discord-5865F2?logo=discord&logoColor=white">][discord]
<br><br>
[<img alt="Baseline Status" src="https://cssdb.org/images/badges-baseline/display-two-values.svg" height="20">][css-url]
[<img alt="CSS Standard Status" src="https://cssdb.org/images/badges/display-two-values.svg" height="20">][css-url]

[PostCSS Normalize Display Values] lets you specify definition of outer and inner displays types for an element.

```pcss
.element {
  display: inline flow-root;
}

/* becomes */

.element {
  display: inline-block;
  display: inline flow-root;
}
```

_See prior work by [cssnano](https://github.com/cssnano) here [postcss-normalize-display-values](https://github.com/cssnano/cssnano/tree/master/packages/postcss-normalize-display-values)
To ensure long term maintenance and to provide the needed features this plugin was recreated based on cssnano's work._

## Usage

Add [PostCSS Normalize Display Values] to your project:

```bash
npm install postcss @csstools/postcss-normalize-display-values --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssNormalizeDisplayValues = require('@csstools/postcss-normalize-display-values');

postcss([
  postcssNormalizeDisplayValues(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```

[PostCSS Normalize Display Values] runs in all Node environments, with special
instructions for:

| [Node](INSTALL.md#node) | [PostCSS CLI](INSTALL.md#postcss-cli) | [Webpack](INSTALL.md#webpack) | [Gulp](INSTALL.md#gulp) | [Grunt](INSTALL.md#grunt) |
| --- | --- | --- | --- | --- |

## Options

### preserve

The `preserve` option determines whether the original source
is preserved. By default, it is preserved.

```js
postcssNormalizeDisplayValues({ preserve: false })
```

```pcss
.element {
  display: inline flow-root;
}

/* becomes */

.element {
  display: inline-block; 
}
```

[postcss]: https://github.com/postcss/postcss

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#display-two-values
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/postcss-normalize-display-values

[CSS Fonts]: https://www.w3.org/TR/css-display-3/#the-display-properties
[Gulp PostCSS]: https://github.com/postcss/gulp-postcss
[Grunt PostCSS]: https://github.com/nDmitry/grunt-postcss
[PostCSS]: https://github.com/postcss/postcss
[PostCSS Loader]: https://github.com/postcss/postcss-loader
[PostCSS Normalize Display Values]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-normalize-display-values


---

# Changes to PostCSS OKLab Function

### 4.0.8

_February 23, 2025_

- Updated [`@csstools/css-color-parser`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-color-parser) to [`3.0.8`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-color-parser/CHANGELOG.md#308) (patch)

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-oklab-function/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS OKLab Function [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][postcss]

[<img alt="npm version" src="https://img.shields.io/npm/v/@csstools/postcss-oklab-function.svg" height="20">][npm-url]
[<img alt="Build Status" src="https://github.com/csstools/postcss-plugins/workflows/test/badge.svg" height="20">][cli-url]
[<img alt="Discord" src="https://shields.io/badge/Discord-5865F2?logo=discord&logoColor=white">][discord]
<br><br>
[<img alt="Baseline Status" src="https://cssdb.org/images/badges-baseline/oklab-function.svg" height="20">][css-url]
[<img alt="CSS Standard Status" src="https://cssdb.org/images/badges/oklab-function.svg" height="20">][css-url]

[PostCSS OKLab Function] lets you use `oklab` and `oklch` color functions in
CSS, following the [CSS Color] specification.

```css
.test-oklab {
	color: oklab(40% 0.001236 0.0039);
}

.test-oklch {
	color: oklch(40% 0.268735435 34.568626);
}

/* becomes */

.test-oklab {
	color: rgb(73, 71, 69);
	color: color(display-p3 0.28515 0.27983 0.27246);
}

.test-oklch {
	color: rgb(131, 28, 0);
	color: color(display-p3 0.49163 0.11178 0.00000);
}
```

## Usage

Add [PostCSS OKLab Function] to your project:

```bash
npm install postcss @csstools/postcss-oklab-function --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssOKLabFunction = require('@csstools/postcss-oklab-function');

postcss([
  postcssOKLabFunction(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```

[PostCSS OKLab Function] runs in all Node environments, with special
instructions for:

| [Node](INSTALL.md#node) | [PostCSS CLI](INSTALL.md#postcss-cli) | [Webpack](INSTALL.md#webpack) | [Gulp](INSTALL.md#gulp) | [Grunt](INSTALL.md#grunt) |
| --- | --- | --- | --- | --- |

## Options

### preserve

The `preserve` option determines whether the original notation
is preserved. By default, it is not preserved.

```js
postcssOKLabFunction({ preserve: true })
```

```css
.test-oklab {
	color: oklab(40% 0.001236 0.0039);
}

.test-oklch {
	color: oklch(40% 0.268735435 34.568626);
}

/* becomes */

.test-oklab {
	color: rgb(73, 71, 69);
	color: color(display-p3 0.28515 0.27983 0.27246);
	color: oklab(40% 0.001236 0.0039);
}

.test-oklch {
	color: rgb(131, 28, 0);
	color: color(display-p3 0.49163 0.11178 0.00000);
	color: oklch(40% 0.268735435 34.568626);
}
```

### enableProgressiveCustomProperties

The `enableProgressiveCustomProperties` option determines whether the original notation
is wrapped with `@supports` when used in Custom Properties. By default, it is enabled.

> [!NOTE]
> We only recommend disabling this when you set `preserve` to `false` or if you bring your own fix for Custom Properties.  
> See what the plugin does in its [README](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-progressive-custom-properties#readme).

```js
postcssOKLabFunction({ enableProgressiveCustomProperties: false })
```

```css
:root {
	--firebrick: oklab(40% 0.234 0.39);
}

/* becomes */

:root {
	--firebrick: rgb(133, 0, 67); /* will never be used, not even in older browser */
	--firebrick: color(display-p3 0.49890 0.00000 0.25954); /* will never be used, not even in older browser */
	--firebrick: oklab(40% 0.234 0.39);
}
```

### subFeatures

#### displayP3

The `subFeatures.displayP3` option determines if `color(display-p3 ...)` is used as a fallback.<br>
By default, it is enabled.

`display-p3` can display wider gamut colors than `rgb` on some devices.

```js
postcssOKLabFunction({
	subFeatures: {
		displayP3: false
	}
})
```

```css
.test-oklab {
	color: oklab(40% 0.001236 0.0039);
}

.test-oklch {
	color: oklch(40% 0.268735435 34.568626);
}

/* becomes */

.test-oklab {
	color: rgb(73, 71, 69);
}

.test-oklch {
	color: rgb(131, 28, 0);
}
```

## Copyright : color conversions

This software or document includes material copied from or derived from https://github.com/w3c/csswg-drafts/tree/main/css-color-4. Copyright © 2022 W3C® (MIT, ERCIM, Keio, Beihang).

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#oklab-function
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/postcss-oklab-function

[CSS Color]: https://www.w3.org/TR/css-color-4/#specifying-oklab-oklch
[Gulp PostCSS]: https://github.com/postcss/gulp-postcss
[Grunt PostCSS]: https://github.com/nDmitry/grunt-postcss
[PostCSS]: https://github.com/postcss/postcss
[PostCSS Loader]: https://github.com/postcss/postcss-loader
[PostCSS OKLab Function]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-oklab-function


---

# Changes to PostCSS Progressive Custom Properties

### 4.0.0

_August 3, 2024_

- Updated: Support for Node v18+ (major).

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-progressive-custom-properties/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Progressive Custom Properties [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS" width="90" height="90" align="right">][postcss]

[![NPM Version][npm-img]][npm-url]
[![Build Status][cli-img]][cli-url]
[<img alt="Discord" src="https://shields.io/badge/Discord-5865F2?logo=discord&logoColor=white">][discord]

[PostCSS Progressive Custom Properties] is a utility plugin to correctly declare Custom Property fallbacks and enhancements.

> [!WARNING]
> It is not intended to be used directly by stylesheet authors.
> Meant to be included in other PostCSS plugins that provide CSS value transforms as fallbacks.

[Custom Properties are not discarded like regular declarations when invalid.](https://www.w3.org/TR/css-variables-1/#invalid-variables)
This makes it tricky to provide fallback values for older browsers.

The solution is to wrap Custom Property declarations in an `@supports` rule.

```pcss
:root {
	/* fallback */
	--a-color: red;
	/* progressive enhancement */
	--a-color: oklch(40% 0.234 0.39 / var(--opacity-50));
}

/* becomes */

:root {
	--a-color: red;
}

@supports (color: oklch(0% 0 0)) {
	:root {
		--a-color: oklch(40% 0.234 0.39 / var(--opacity-50));
	}
}
```

## Ignored values

`initial` and `<white space>` are ignored.

```pcss
.initial {
	--prop-1: red;
	--prop-1: initial;
}

.white-space {
	--prop-1: red;
	--prop-1:;

	--prop-2: red;
	--prop-2: ;

	--prop-3: red;
	--prop-3:    ;
}

/* remains */

.initial {
	--prop-1: red;
	--prop-1: initial;
}

.white-space {
	--prop-1: red;
	--prop-1:;

	--prop-2: red;
	--prop-2: ;

	--prop-3: red;
	--prop-3:    ;
}
```

## Usage

Add [PostCSS Progressive Custom Properties] to your project:

```bash
npm install @csstools/postcss-progressive-custom-properties --save-dev
```

Use [PostCSS Progressive Custom Properties] as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssCustomProperties = require('@csstools/postcss-progressive-custom-properties');

postcss([
  postcssProgressiveCustomProperties()
]).process(YOUR_CSS /*, processOptions */);
```

## @supports

This plugin wraps Custom Property override declarations in an `@supports` rule.
With PostCSS 8 this trigger declaration visitors to run again.

Make sure your plugin detects and ignores values inside relevant `@supports` rules.

## Reading list 

- https://moderncss.dev/how-custom-property-values-are-computed/

[PostCSS Progressive Custom Properties] runs in all Node environments, with special instructions for:

| [Node](INSTALL.md#node) | [PostCSS CLI](INSTALL.md#postcss-cli) | [Webpack](INSTALL.md#webpack) | [Gulp](INSTALL.md#gulp) | [Grunt](INSTALL.md#grunt) |
| --- | --- | --- | --- | --- |


[cli-img]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml/badge.svg
[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[discord]: https://discord.gg/bUadyRwkJS
[npm-img]: https://img.shields.io/npm/v/@csstools/postcss-progressive-custom-properties.svg
[npm-url]: https://www.npmjs.com/package/@csstools/postcss-progressive-custom-properties

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Progressive Custom Properties]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-progressive-custom-properties


---

# Changes to PostCSS Random Function

### 1.0.3

_February 23, 2025_

- Updated [`@csstools/css-calc`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-calc) to [`2.1.2`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-calc/CHANGELOG.md#212) (patch)

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-random-function/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Random Function [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install @csstools/postcss-random-function --save-dev`

[PostCSS Random Function] lets you use the `random` function, following the [CSS Values 5] specification.

```css
div {
	color: oklch(0.7, 0.2, random(120deg, 240deg));
}

div {
	color: oklch(0.7, 0.2, random(120deg, 240deg, by 7deg));
}

div {
	color: oklch(0.7, 0.2, random(--text, 120deg, 240deg));
	border-color: oklch(0.7, 0.2, random(--border, 120deg, 240deg));
}

/* becomes */

div {
	color: oklch(0.7, 0.2, 238.66036deg);
}

div {
	color: oklch(0.7, 0.2, 134deg);
}

div {
	color: oklch(0.7, 0.2, 226.47057deg);
	border-color: oklch(0.7, 0.2, 157.76966deg);
}
```

> [!NOTE]
> Generated values are deterministic pseudo random numbers.
> Generating values twice with the same input will give the same result.
> The input length of the CSS source file is used as a random seed.

## Usage

Add [PostCSS Random Function] to your project:

```bash
npm install postcss @csstools/postcss-random-function --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssRandomFunction = require('@csstools/postcss-random-function');

postcss([
	postcssRandomFunction(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## ⚠️ About custom properties

Given the dynamic nature of custom properties it's impossible to know what the variable value is, which means the plugin can't compute a final value for the stylesheet. 

Because of that, any usage that contains a `var` is skipped.

## Options

### preserve

The `preserve` option determines whether the original notation
is preserved. By default, it is not preserved.

```js
postcssRandomFunction({ preserve: true })
```

```css
div {
	color: oklch(0.7, 0.2, random(120deg, 240deg));
}

div {
	color: oklch(0.7, 0.2, random(120deg, 240deg, by 7deg));
}

div {
	color: oklch(0.7, 0.2, random(--text, 120deg, 240deg));
	border-color: oklch(0.7, 0.2, random(--border, 120deg, 240deg));
}

/* becomes */

div {
	color: oklch(0.7, 0.2, 238.66036deg);
	color: oklch(0.7, 0.2, random(120deg, 240deg));
}

div {
	color: oklch(0.7, 0.2, 134deg);
	color: oklch(0.7, 0.2, random(120deg, 240deg, by 7deg));
}

div {
	color: oklch(0.7, 0.2, 226.47057deg);
	color: oklch(0.7, 0.2, random(--text, 120deg, 240deg));
	border-color: oklch(0.7, 0.2, 157.76966deg);
	border-color: oklch(0.7, 0.2, random(--border, 120deg, 240deg));
}
```

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#random-function
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/postcss-random-function

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Random Function]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-random-function
[CSS Values 5]: https://drafts.csswg.org/css-values-5/#random


---

# Changes to PostCSS Relative Color Syntax

### 3.0.8

_February 23, 2025_

- Updated [`@csstools/css-color-parser`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-color-parser) to [`3.0.8`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-color-parser/CHANGELOG.md#308) (patch)

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-relative-color-syntax/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Relative Color Syntax [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install @csstools/postcss-relative-color-syntax --save-dev`

[PostCSS Relative Color Syntax] lets you use the relative color syntax in CSS color functions following [CSS Color Module 5].

```css
.example {
	background: oklab(from oklab(54.3% -22.5% -5%) calc(1.0 - l) calc(a * 0.8) b);
}

/* becomes */

.example {
	background: rgb(12, 100, 100);
}
```

> [!NOTE]
> We can not dynamically resolve `var()` arguments in relative color syntax, only static values will work.

## Usage

Add [PostCSS Relative Color Syntax] to your project:

```bash
npm install postcss @csstools/postcss-relative-color-syntax --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssRelativeColorSyntax = require('@csstools/postcss-relative-color-syntax');

postcss([
	postcssRelativeColorSyntax(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## Options

### preserve

The `preserve` option determines whether the original notation
is preserved. By default, it is not preserved.

```js
postcssRelativeColorSyntax({ preserve: true })
```

```css
.example {
	background: oklab(from oklab(54.3% -22.5% -5%) calc(1.0 - l) calc(a * 0.8) b);
}

/* becomes */

.example {
	background: rgb(12, 100, 100);
	background: oklab(from oklab(54.3% -22.5% -5%) calc(1.0 - l) calc(a * 0.8) b);
}
```

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#relative-color-syntax
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/postcss-relative-color-syntax

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Relative Color Syntax]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-relative-color-syntax
[CSS Color Module 5]: https://www.w3.org/TR/css-color-5/#relative-colors


---

# Changes to PostCSS Scope Pseudo Class

### 4.0.1

_October 23, 2024_

- Updated: `postcss-selector-parser`

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-scope-pseudo-class/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Scope Pseudo Class [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install @csstools/postcss-scope-pseudo-class --save-dev`

[PostCSS Scope Pseudo Class] lets you use the `:scope` Pseudo-class following the [Selectors 4 specification].

```pcss
:scope {
	color: green;
}

/* becomes */

:root {
	color: green;
}
```

## Usage

Add [PostCSS Scope Pseudo Class] to your project:

```bash
npm install postcss @csstools/postcss-scope-pseudo-class --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssScopePseudoClass = require('@csstools/postcss-scope-pseudo-class');

postcss([
	postcssScopePseudoClass(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## Options

### preserve

The `preserve` option determines whether the original notation
is preserved. By default, it is not preserved.

```js
postcssScopePseudoClass({ preserve: true })
```

```pcss
:scope {
	color: green;
}

/* becomes */

:root {
	color: green;
}
:scope {
	color: green;
}
```

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#scope-pseudo-class
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/postcss-scope-pseudo-class

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Scope Pseudo Class]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-scope-pseudo-class
[Selectors 4 specification]: https://www.w3.org/TR/selectors-4/#the-scope-pseudo


---

# API Documentation

*Please use only this documented API when working with the parser. Methods
not documented here are subject to change at any point.*

## `parser` function

This is the module's main entry point.

```js
const parser = require('postcss-selector-parser');
```

### `parser([transform], [options])`

Creates a new `processor` instance

```js
const processor = parser();
```

Or, with optional transform function

```js
const transform = selectors => {
    selectors.walkUniversals(selector => {
        selector.remove();
    });
};

const processor = parser(transform)

// Example
const result = processor.processSync('*.class');
// => .class
```

[See processor documentation](#processor)

Arguments:

* `transform (function)`: Provide a function to work with the parsed AST.
* `options (object)`: Provide default options for all calls on the returned `Processor`.

### `parser.attribute([props])`

Creates a new attribute selector.

```js
parser.attribute({attribute: 'href'});
// => [href]
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.className([props])`

Creates a new class selector.

```js
parser.className({value: 'button'});
// => .button
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.combinator([props])`

Creates a new selector combinator.

```js
parser.combinator({value: '+'});
// => +
```

Arguments:

* `props (object)`: The new node's properties.

Notes:
* **Descendant Combinators** The value of descendant combinators created by the
  parser always just a single space (`" "`). For descendant selectors with no
  comments, additional space is now stored in `node.spaces.before`. Depending
  on the location of comments, additional spaces may be stored in
  `node.raws.spaces.before`, `node.raws.spaces.after`, or `node.raws.value`.
* **Named Combinators** Although, nonstandard and unlikely to ever become a standard,
  named combinators like `/deep/` and `/for/` are parsed as combinators. The
  `node.value` is name after being unescaped and normalized as lowercase. The
  original value for the combinator name is stored in `node.raws.value`.


### `parser.comment([props])`

Creates a new comment.

```js
parser.comment({value: '/* Affirmative, Dave. I read you. */'});
// => /* Affirmative, Dave. I read you. */
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.id([props])`

Creates a new id selector.

```js
parser.id({value: 'search'});
// => #search
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.nesting([props])`

Creates a new nesting selector.

```js
parser.nesting();
// => &
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.pseudo([props])`

Creates a new pseudo selector.

```js
parser.pseudo({value: '::before'});
// => ::before
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.root([props])`

Creates a new root node.

```js
parser.root();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.selector([props])`

Creates a new selector node.

```js
parser.selector();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.string([props])`

Creates a new string node.

```js
parser.string();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.tag([props])`

Creates a new tag selector.

```js
parser.tag({value: 'button'});
// => button
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.universal([props])`

Creates a new universal selector.

```js
parser.universal();
// => *
```

Arguments:

* `props (object)`: The new node's properties.

## Node types

### `node.type`

A string representation of the selector type. It can be one of the following;
`attribute`, `class`, `combinator`, `comment`, `id`, `nesting`, `pseudo`,
`root`, `selector`, `string`, `tag`, or `universal`. Note that for convenience,
these constants are exposed on the main `parser` as uppercased keys. So for
example you can get `id` by querying `parser.ID`.

```js
parser.attribute({attribute: 'href'}).type;
// => 'attribute'
```

### `node.parent`

Returns the parent node.

```js
root.nodes[0].parent === root;
```

### `node.toString()`, `String(node)`, or `'' + node`

Returns a string representation of the node.

```js
const id = parser.id({value: 'search'});
console.log(String(id));
// => #search
```

### `node.next()` & `node.prev()`

Returns the next/previous child of the parent node.

```js
const next = id.next();
if (next && next.type !== 'combinator') {
    throw new Error('Qualified IDs are not allowed!');
}
```

### `node.replaceWith(node[,...nodeN])`

Replace a node with another.

```js
const attr = selectors.first.first;
const className = parser.className({value: 'test'});
attr.replaceWith(className);
```

Arguments:

* `node`: The node to substitute the original with.
...
* `nodeN`: The node to substitute the original with.

### `node.remove()`

Removes the node from its parent node.

```js
if (node.type === 'id') {
    node.remove();
}
```

### `node.clone([opts])`

Returns a copy of a node, detached from any parent containers that the
original might have had.

```js
const cloned = node.clone();
```

### `node.isAtPosition(line, column)`

Return a `boolean` indicating whether this node includes the character at the
position of the given line and column. Returns `undefined` if the nodes lack
sufficient source metadata to determine the position.

Arguments:

* `line`: 1-index based line number relative to the start of the selector.
* `column`: 1-index based column number relative to the start of the selector.

### `node.spaces`

Extra whitespaces around the node will be moved into `node.spaces.before` and
`node.spaces.after`. So for example, these spaces will be moved as they have
no semantic meaning:

```css
      h1     ,     h2   {}
```

For descendent selectors, the value is always a single space.

```css
h1        h2 {}
```

Additional whitespace is found in either the `node.spaces.before` and `node.spaces.after` depending on the presence of comments or other whitespace characters. If the actual whitespace does not start or end with a single space, the node's raw value is set to the actual space(s) found in the source.

### `node.source`

An object describing the node's start/end, line/column source position.

Within the following CSS, the `.bar` class node ...

```css
.foo,
  .bar {}
```

... will contain the following `source` object.

```js
source: {
    start: {
        line: 2,
        column: 3
    },
    end: {
        line: 2,
        column: 6
    }
}
```

### `node.sourceIndex`

The zero-based index of the node within the original source string.

Within the following CSS, the `.baz` class node will have a `sourceIndex` of `12`.

```css
.foo, .bar, .baz {}
```

## Container types

The `root`, `selector`, and `pseudo` nodes have some helper methods for working
with their children.

### `container.nodes`

An array of the container's children.

```js
// Input: h1 h2
selectors.at(0).nodes.length   // => 3
selectors.at(0).nodes[0].value // => 'h1'
selectors.at(0).nodes[1].value // => ' '
```

### `container.first` & `container.last`

The first/last child of the container.

```js
selector.first === selector.nodes[0];
selector.last === selector.nodes[selector.nodes.length - 1];
```

### `container.at(index)`

Returns the node at position `index`.

```js
selector.at(0) === selector.first;
selector.at(0) === selector.nodes[0];
```

Arguments:

* `index`: The index of the node to return.

### `container.atPosition(line, column)`

Returns the node at the source position `line` and `column`.

```js
// Input: :not(.foo),\n#foo > :matches(ol, ul)
selector.atPosition(1, 1); // => :not(.foo)
selector.atPosition(2, 1); // => \n#foo
```

Arguments:

* `line`: The line number of the node to return.
* `column`: The column number of the node to return.

### `container.index(node)`

Return the index of the node within its container.

```js
selector.index(selector.nodes[2]) // => 2
```

Arguments:

* `node`: A node within the current container.

### `container.length`

Proxy to the length of the container's nodes.

```js
container.length === container.nodes.length
```

### `container` Array iterators

The container class provides proxies to certain Array methods; these are:

* `container.map === container.nodes.map`
* `container.reduce === container.nodes.reduce`
* `container.every === container.nodes.every`
* `container.some === container.nodes.some`
* `container.filter === container.nodes.filter`
* `container.sort === container.nodes.sort`

Note that these methods only work on a container's immediate children; recursive
iteration is provided by `container.walk`.

### `container.each(callback)`

Iterate the container's immediate children, calling `callback` for each child.
You may return `false` within the callback to break the iteration.

```js
let className;
selectors.each((selector, index) => {
    if (selector.type === 'class') {
        className = selector.value;
        return false;
    }
});
```

Note that unlike `Array#forEach()`, this iterator is safe to use whilst adding
or removing nodes from the container.

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  and `index` arguments.

### `container.walk(callback)`

Like `container#each`, but will also iterate child nodes as long as they are
`container` types.

```js
selectors.walk((selector, index) => {
    // all nodes
});
```

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  and `index` arguments.

This iterator is safe to use whilst mutating `container.nodes`,
like `container#each`.

### `container.walk` proxies

The container class provides proxy methods for iterating over types of nodes,
so that it is easier to write modules that target specific selectors. Those
methods are:

* `container.walkAttributes`
* `container.walkClasses`
* `container.walkCombinators`
* `container.walkComments`
* `container.walkIds`
* `container.walkNesting`
* `container.walkPseudos`
* `container.walkTags`
* `container.walkUniversals`

### `container.split(callback)`

This method allows you to split a group of nodes by returning `true` from
a callback. It returns an array of arrays, where each inner array corresponds
to the groups that you created via the callback.

```js
// (input) => h1 h2>>h3
const list = selectors.first.split(selector => {
    return selector.type === 'combinator';
});

// (node values) => [['h1', ' '], ['h2', '>>'], ['h3']]
```

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  as an argument.

### `container.prepend(node)` & `container.append(node)`

Add a node to the start/end of the container. Note that doing so will set
the parent property of the node to this container.

```js
const id = parser.id({value: 'search'});
selector.append(id);
```

Arguments:

* `node`: The node to add.

### `container.insertBefore(old, new[, ...newNodes])` & `container.insertAfter(old, new[, ...newNodes])`

Add a node before or after an existing node in a container:

```js
selectors.walk(selector => {
    if (selector.type !== 'class') {
        const className = parser.className({value: 'theme-name'});
        selector.parent.insertAfter(selector, className);
    }
});
```

Arguments:

* `old`: The existing node in the container.
* `new`: The new node to add before/after the existing node.

### `container.removeChild(node)`

Remove the node from the container. Note that you can also use
`node.remove()` if you would like to remove just a single node.

```js
selector.length // => 2
selector.remove(id)
selector.length // => 1;
id.parent       // undefined
```

Arguments:

* `node`: The node to remove.

### `container.removeAll()` or `container.empty()`

Remove all children from the container.

```js
selector.removeAll();
selector.length // => 0
```

## Root nodes

A root node represents a comma separated list of selectors. Indeed, all
a root's `toString()` method does is join its selector children with a ','.
Other than this, it has no special functionality and acts like a container.

### `root.trailingComma`

This will be set to `true` if the input has a trailing comma, in order to
support parsing of legacy CSS hacks.

## Selector nodes

A selector node represents a single complex selector. For example, this
selector string `h1 h2 h3, [href] > p`, is represented as two selector nodes.
It has no special functionality of its own.

## Pseudo nodes

A pseudo selector extends a container node; if it has any parameters of its
own (such as `h1:not(h2, h3)`), they will be its children. Note that the pseudo
`value` will always contain the colons preceding the pseudo identifier. This
is so that both `:before` and `::before` are properly represented in the AST.

## Attribute nodes

### `attribute.quoted`

Returns `true` if the attribute's value is wrapped in quotation marks, false if it is not.
Remains `undefined` if there is no attribute value.

```css
[href=foo] /* false */
[href='foo'] /* true */
[href="foo"] /* true */
[href] /* undefined */
```

### `attribute.qualifiedAttribute`

Returns the attribute name qualified with the namespace if one is given.

### `attribute.offsetOf(part)`

 Returns the offset of the attribute part specified relative to the
 start of the node of the output string. This is useful in raising
 error messages about a specific part of the attribute, especially
 in combination with `attribute.sourceIndex`.

 Returns `-1` if the name is invalid or the value doesn't exist in this
 attribute.

 The legal values for `part` are:

 * `"ns"` - alias for "namespace"
 * `"namespace"` - the namespace if it exists.
 * `"attribute"` - the attribute name
 * `"attributeNS"` - the start of the attribute or its namespace
 * `"operator"` - the match operator of the attribute
 * `"value"` - The value (string or identifier)
 * `"insensitive"` - the case insensitivity flag

### `attribute.raws.unquoted`

Returns the unquoted content of the attribute's value.
Remains `undefined` if there is no attribute value.

```css
[href=foo] /* foo */
[href='foo'] /* foo */
[href="foo"] /* foo */
[href] /* undefined */
```

### `attribute.spaces`

Like `node.spaces` with the `before` and `after` values containing the spaces
around the element, the parts of the attribute can also have spaces before
and after them. The for each of `attribute`, `operator`, `value` and
`insensitive` there is corresponding property of the same nam in
`node.spaces` that has an optional `before` or `after` string containing only
whitespace.

Note that corresponding values in `attributes.raws.spaces` contain values
including any comments. If set, these values will override the
`attribute.spaces` value. Take care to remove them if changing
`attribute.spaces`.

### `attribute.raws`

The raws object stores comments and other information necessary to re-render
the node exactly as it was in the source.

If a comment is embedded within the identifiers for the `namespace`, `attribute`
or `value` then a property is placed in the raws for that value containing the full source of the propery including comments.

If a comment is embedded within the space between parts of the attribute
then the raw for that space is set accordingly.

Setting an attribute's property `raws` value to be deleted.

For now, changing the spaces required also updating or removing any of the
raws values that override them.

Example: `[ /*before*/ href /* after-attr */ = /* after-operator */ te/*inside-value*/st/* wow */ /*omg*/i/*bbq*/ /*whodoesthis*/]` would parse as:

```js
{
  attribute: "href",
  operator: "=",
  value: "test",
  spaces: {
    before: '',
    after: '',
    attribute: { before: '  ', after: '  ' },
    operator: { after: '  ' },
    value: { after: ' ' },
    insensitive: { after: ' ' }
  },
  raws: {
    spaces: {
      attribute: { before: ' /*before*/ ', after: ' /* after-attr */ ' },
      operator: { after: ' /* after-operator */ ' },
      value: { after: '/* wow */ /*omg*/' },
      insensitive: { after: '/*bbq*/ /*whodoesthis*/' }
    },
    unquoted: 'test',
    value: 'te/*inside-value*/st'
  }
}
```

## `Processor`

### `ProcessorOptions`

* `lossless` - When `true`, whitespace is preserved. Defaults to `true`.
* `updateSelector` - When `true`, if any processor methods are passed a postcss
  `Rule` node instead of a string, then that Rule's selector is updated
  with the results of the processing. Defaults to `true`.

### `process|processSync(selectors, [options])`

Processes the `selectors`, returning a string from the result of processing.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

**Example:**

```js
const parser = require("postcss-selector-parser");
const processor = parser();

let result = processor.processSync(' .class');
console.log(result);
// =>  .class

// Asynchronous operation
let promise = processor.process(' .class').then(result => {
    console.log(result)
    // => .class
});

// To have the parser normalize whitespace values, utilize the options
result = processor.processSync('  .class  ', {lossless: false});
console.log(result);
// => .class

// For better syntax errors, pass a PostCSS Rule node.
const postcss = require('postcss');
rule = postcss.rule({selector: ' #foo    > a,  .class  '});
processor.process(rule, {lossless: false, updateSelector: true}).then(result => {
    console.log(result);
    // => #foo>a,.class
    console.log("rule:", rule.selector);
    // => rule: #foo>a,.class
})
```

Arguments:

* `selectors (string|postcss.Rule)`: Either a selector string or a PostCSS Rule
  node.
* `[options] (object)`: Process options


### `ast|astSync(selectors, [options])`

Like `process()` and `processSync()` but after
processing the `selectors` these methods return the `Root` node of the result
instead of a string.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

### `transform|transformSync(selectors, [options])`

Like `process()` and `processSync()` but after
processing the `selectors` these methods return the value returned by the
processor callback.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

### Error Handling Within Selector Processors

The root node passed to the selector processor callback
has a method `error(message, options)` that returns an
error object. This method should always be used to raise
errors relating to the syntax of selectors. The options
to this method are passed to postcss's error constructor
([documentation](http://postcss.org/api/#container-error)).

#### Async Error Example

```js
let processor = (root) => {
    return new Promise((resolve, reject) => {
        root.walkClasses((classNode) => {
            if (/^(.*)[-_]/.test(classNode.value)) {
                let msg = "classes may not have underscores or dashes in them";
                reject(root.error(msg, {
                    index: classNode.sourceIndex + RegExp.$1.length + 1,
                    word: classNode.value
                }));
            }
        });
        resolve();
    });
};

const postcss = require("postcss");
const parser = require("postcss-selector-parser");
const selectorProcessor = parser(processor);
const plugin = postcss.plugin('classValidator', (options) => {
    return (root) => {
        let promises = [];
        root.walkRules(rule => {
            promises.push(selectorProcessor.process(rule));
        });
        return Promise.all(promises);
    };
});
postcss(plugin()).process(`
.foo-bar {
  color: red;
}
`.trim(), {from: 'test.css'}).catch((e) => console.error(e.toString()));

// CssSyntaxError: classValidator: ./test.css:1:5: classes may not have underscores or dashes in them
//
// > 1 | .foo-bar {
//     |     ^
//   2 |   color: red;
//   3 | }
```

#### Synchronous Error Example

```js
let processor = (root) => {
    root.walkClasses((classNode) => {
        if (/.*[-_]/.test(classNode.value)) {
            let msg = "classes may not have underscores or dashes in them";
            throw root.error(msg, {
                index: classNode.sourceIndex,
                word: classNode.value
            });
        }
    });
};

const postcss = require("postcss");
const parser = require("postcss-selector-parser");
const selectorProcessor = parser(processor);
const plugin = postcss.plugin('classValidator', (options) => {
    return (root) => {
        root.walkRules(rule => {
            selectorProcessor.processSync(rule);
        });
    };
});
postcss(plugin()).process(`
.foo-bar {
  color: red;
}
`.trim(), {from: 'test.css'}).catch((e) => console.error(e.toString()));

// CssSyntaxError: classValidator: ./test.css:1:5: classes may not have underscores or dashes in them
//
// > 1 | .foo-bar {
//     |     ^
//   2 |   color: red;
//   3 | }
```


---

# 7.1.0

- feat: insert(Before|After) support multiple new node

# 7.0.0

- Feat: make insertions during iteration safe (major)

# 6.1.2

- Fixed: erroneous trailing combinators in pseudos

# 6.1.1

- Fixed: improve typings of constructor helpers (#292)

# 6.1.0

- Feature: add `sourceIndex` to `Selector` nodes (#290)

# 6.0.16

- Fixed: add missing `index` argument to `each`/`walk` callback types (#289)

# 6.0.15

- Fixed: Node#prev and Node#next type for the first/last node

# 6.0.14

- Fixed: type definitions

# 6.0.13

- Fixed: throw on unexpected pipe symbols

# 6.0.12

- Fixed: `clone` arguments should be optional

# 6.0.11

- Fixed: parse attribute case insensitivity flag

# 6.0.10

- Fixed: `isPseudoElement()` supports `:first-letter` and `:first-line`

# 6.0.9

- Fixed: `Combinator.raws` property type

# 6.0.8

- Fixed: reduced size

# 6.0.7

- Fixed: parse animation percents

# 6.0.6

- Fixed: parse quoted attributes containing a newline correctly

# 6.0.5

- Perf: rework unesc for a 63+% performance boost

# 6.0.4

- Fixed: ts errors

# 6.0.3

- Fixed: replace node built-in "util" module with "util-deprecate"
- Fixed: handle uppercase pseudo elements
- Fixed: do not create invalid combinator before comment

# 6.0.2

- Fixed an issue with parsing and stringifying an empty attribute value

# 6.0.1

- Fixed an issue with unicode surrogate pair parsing

# 6.0.0

- Updated: `cssesc` to 3.0.0 (major)
- Fixed: Issues with escaped `id` and `class` selectors

# 5.0.0

- Allow escaped dot within class name.
- Update PostCSS to 7.0.7 (patch)

# 5.0.0-rc.4

- Fixed an issue where comments immediately after an insensitive (in attribute)
  were not parsed correctly.
- Updated `cssesc` to 2.0.0 (major).
- Removed outdated integration tests.
- Added tests for custom selectors, tags with attributes, the universal
  selector with pseudos, and tokens after combinators.

# 5.0.0-rc.1

To ease adoption of the v5.0 release, we have relaxed the node version
check performed by npm at installation time to allow for node 4, which
remains officially unsupported, but likely to continue working for the
time being.

# 5.0.0-rc.0

This release has **BREAKING CHANGES** that were required to fix regressions
in 4.0.0 and to make the Combinator Node API consistent for all combinator
types. Please read carefully.

## Summary of Changes

* The way a descendent combinator that isn't a single space character (E.g. `.a  .b`) is stored in the AST has changed.
* Named Combinators (E.g. `.a /for/ .b`) are now properly parsed as a combinator.
* It is now possible to look up a node based on the source location of a character in that node and to query nodes if they contain some character.
* Several bug fixes that caused the parser to hang and run out of memory when a `/` was encountered have been fixed.
* The minimum supported version of Node is now `v6.0.0`.

### Changes to the Descendent Combinator

In prior releases, the value of a descendant combinator with multiple spaces included all the spaces.

* `.a   .b`: Extra spaces are now stored as space before.
  - Old & Busted:
    - `combinator.value === "   "`
  - New hotness:
    - `combinator.value === " " && combinator.spaces.before === "  "`
* `.a   /*comment*/.b`: A comment at the end of the combinator causes extra space to become after space.
  - Old & Busted:
    - `combinator.value === "   "`
    - `combinator.raws.value === "   /*comment/"`
  - New hotness:
    - `combinator.value === " "`
    - `combinator.spaces.after === "  "`
    - `combinator.raws.spaces.after === "  /*comment*/"`
* `.a<newline>.b`: whitespace that doesn't start or end with a single space character is stored as a raw value.
  - Old & Busted:
    - `combinator.value === "\n"`
    - `combinator.raws.value === undefined`
  - New hotness:
    - `combinator.value === " "`
    - `combinator.raws.value === "\n"`

### Support for "Named Combinators"

Although, nonstandard and unlikely to ever become a standard, combinators like `/deep/` and `/for/` are now properly supported.

Because they've been taken off the standardization track, there is no spec-official name for combinators of the form `/<ident>/`. However, I talked to [Tab Atkins](https://twitter.com/tabatkins) and we agreed to call them "named combinators" so now they are called that.

Before this release such named combinators were parsed without intention and generated three nodes of type `"tag"` where the first and last nodes had a value of `"/"`.

* `.a /for/ .b` is parsed as a combinator.
  - Old & Busted:
    - `root.nodes[0].nodes[1].type === "tag"`
    - `root.nodes[0].nodes[1].value === "/"`
  - New hotness:
    - `root.nodes[0].nodes[1].type === "combinator"`
    - `root.nodes[0].nodes[1].value === "/for/"`
* `.a /F\6fR/ .b` escapes are handled and uppercase is normalized.
  - Old & Busted:
    - `root.nodes[0].nodes[2].type === "tag"`
    - `root.nodes[0].nodes[2].value === "F\\6fR"`
  - New hotness:
    - `root.nodes[0].nodes[1].type === "combinator"`
    - `root.nodes[0].nodes[1].value === "/for/"`
    - `root.nodes[0].nodes[1].raws.value === "/F\\6fR/"`

### Source position checks and lookups

A new API was added to look up a node based on the source location.

```js
const selectorParser = require("postcss-selector-parser");
// You can find the most specific node for any given character
let combinator = selectorParser.astSync(".a > .b").atPosition(1,4);
combinator.toString() === " > ";
// You can check if a node includes a specific character
// Whitespace surrounding the node that is owned by that node
// is included in the check.
[2,3,4,5,6].map(column => combinator.isAtPosition(1, column));
// => [false, true, true, true, false]
```

# 4.0.0

This release has **BREAKING CHANGES** that were required to fix bugs regarding values with escape sequences. Please read carefully.

* **Identifiers with escapes** - CSS escape sequences are now hidden from the public API by default.
  The normal value of a node like a class name or ID, or an aspect of a node such as attribute
  selector's value, is unescaped. Escapes representing Non-ascii characters are unescaped into
  unicode characters. For example: `bu\tton, .\31 00, #i\2764\FE0Fu, [attr="value is \"quoted\""]`
  will parse respectively to the values `button`, `100`, `i❤️u`, `value is "quoted"`.
  The original escape sequences for these values can be found in the corresponding property name
  in `node.raws`. Where possible, deprecation warnings were added, but the nature
  of escape handling makes it impossible to detect what is escaped or not. Our expectation is
  that most users are neither expecting nor handling escape sequences in their use of this library,
  and so for them, this is a bug fix. Users who are taking care to handle escapes correctly can
  now update their code to remove the escape handling and let us do it for them.

* **Mutating values with escapes** - When you make an update to a node property that has escape handling
  The value is assumed to be unescaped, and any special characters are escaped automatically and
  the corresponding `raws` value is immediately updated. This can result in changes to the original
  escape format. Where the exact value of the escape sequence is important there are methods that
  allow both values to be set in conjunction. There are a number of new convenience methods for
  manipulating values that involve escapes, especially for attributes values where the quote mark
  is involved. See https://github.com/postcss/postcss-selector-parser/pull/133 for an extensive
  write-up on these changes.


**Upgrade/API Example**

In `3.x` there was no unescape handling and internal consistency of several properties was the caller's job to maintain. It was very easy for the developer
to create a CSS file that did not parse correctly when some types of values
were in use.

```js
const selectorParser = require("postcss-selector-parser");
let attr = selectorParser.attribute({attribute: "id", operator: "=", value: "a-value"});
attr.value; // => "a-value"
attr.toString(); // => [id=a-value]
// Add quotes to an attribute's value.
// All these values have to be set by the caller to be consistent:
// no internal consistency is maintained.
attr.raws.unquoted = attr.value
attr.value = "'" + attr.value + "'";
attr.value; // => "'a-value'"
attr.quoted = true;
attr.toString();  // => "[id='a-value']"
```

In `4.0` there is a convenient API for setting and mutating values
that may need escaping. Especially for attributes.

```js
const selectorParser = require("postcss-selector-parser");

// The constructor requires you specify the exact escape sequence
let className = selectorParser.className({value: "illegal class name", raws: {value: "illegal\\ class\\ name"}});
className.toString(); // => '.illegal\\ class\\ name'

// So it's better to set the value as a property
className = selectorParser.className();
// Most properties that deal with identifiers work like this
className.value = "escape for me";
className.value; // => 'escape for me'
className.toString(); // => '.escape\\ for\\ me'

// emoji and all non-ascii are escaped to ensure it works in every css file.
className.value = "😱🦄😍";
className.value; // => '😱🦄😍'
className.toString(); // => '.\\1F631\\1F984\\1F60D'

// you can control the escape sequence if you want, or do bad bad things
className.setPropertyAndEscape('value', 'xxxx', 'yyyy');
className.value; // => "xxxx"
className.toString(); // => ".yyyy"

// Pass a value directly through to the css output without escaping it. 
className.setPropertyWithoutEscape('value', '$REPLACE_ME$');
className.value; // => "$REPLACE_ME$"
className.toString(); // => ".$REPLACE_ME$"

// The biggest changes are to the Attribute class
// passing quoteMark explicitly is required to avoid a deprecation warning.
let attr = selectorParser.attribute({attribute: "id", operator: "=", value: "a-value", quoteMark: null});
attr.toString(); // => "[id=a-value]"
// Get the value with quotes on it and any necessary escapes.
// This is the same as reading attr.value in 3.x.
attr.getQuotedValue(); // => "a-value";
attr.quoteMark; // => null

// Add quotes to an attribute's value.
attr.quoteMark = "'"; // This is all that's required.
attr.toString(); // => "[id='a-value']"
attr.quoted; // => true
// The value is still the same, only the quotes have changed.
attr.value; // => a-value
attr.getQuotedValue(); // => "'a-value'";

// deprecated assignment, no warning because there's no escapes
attr.value = "new-value";
// no quote mark is needed so it is removed
attr.getQuotedValue(); // => "new-value";

// deprecated assignment, 
attr.value = "\"a 'single quoted' value\"";
// > (node:27859) DeprecationWarning: Assigning an attribute a value containing characters that might need to be escaped is deprecated. Call attribute.setValue() instead.
attr.getQuotedValue(); // => '"a \'single quoted\' value"';
// quote mark inferred from first and last characters.
attr.quoteMark; // => '"'

// setValue takes options to make manipulating the value simple.
attr.setValue('foo', {smart: true});
// foo doesn't require any escapes or quotes.
attr.toString(); // => '[id=foo]'
attr.quoteMark; // => null 

// An explicit quote mark can be specified
attr.setValue('foo', {quoteMark: '"'});
attr.toString(); // => '[id="foo"]'

// preserves quote mark by default
attr.setValue('bar');
attr.toString(); // => '[id="bar"]'
attr.quoteMark = null;
attr.toString(); // => '[id=bar]'

// with no arguments, it preserves quote mark even when it's not a great idea
attr.setValue('a value \n that should be quoted');
attr.toString(); // => '[id=a\\ value\\ \\A\\ that\\ should\\ be\\ quoted]'

// smart preservation with a specified default
attr.setValue('a value \n that should be quoted', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => "[id='a value \\A  that should be quoted']"
attr.quoteMark = '"';
// => '[id="a value \\A  that should be quoted"]'

// this keeps double quotes because it wants to quote the value and the existing value has double quotes.
attr.setValue('this should be quoted', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => '[id="this should be quoted"]'

// picks single quotes because the value has double quotes
attr.setValue('a "double quoted" value', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => "[id='a "double quoted" value']"

// setPropertyAndEscape lets you do anything you want. Even things that are a bad idea and illegal.
attr.setPropertyAndEscape('value', 'xxxx', 'the password is 42');
attr.value; // => "xxxx"
attr.toString(); // => "[id=the password is 42]"

// Pass a value directly through to the css output without escaping it. 
attr.setPropertyWithoutEscape('value', '$REPLACEMENT$');
attr.value; // => "$REPLACEMENT$"
attr.toString(); // => "[id=$REPLACEMENT$]"
```

# 3.1.2

* Fix: Removed dot-prop dependency since it's no longer written in es5.

# 3.1.1

* Fix: typescript definitions weren't in the published package.

# 3.1.0

* Fixed numerous bugs in attribute nodes relating to the handling of comments
  and whitespace. There's significant changes to `attrNode.spaces` and `attrNode.raws` since the `3.0.0` release.
* Added `Attribute#offsetOf(part)` to get the offset location of
  attribute parts like `"operator"` and `"value"`. This is most
  often added to `Attribute#sourceIndex` for error reporting.

# 3.0.0

## Breaking changes

* Some tweaks to the tokenizer/attribute selector parsing mean that whitespace
  locations might be slightly different to the 2.x code.
* Better attribute selector parsing with more validation; postcss-selector-parser
  no longer uses regular expressions to parse attribute selectors.
* Added an async API (thanks to @jacobp100); the default `process` API is now
  async, and the sync API is now accessed through `processSync` instead.
* `process()` and `processSync()` now return a string instead of the Processor
  instance.
* Tweaks handling of Less interpolation (thanks to @jwilsson).
* Removes support for Node 0.12.

## Other changes

* `ast()` and `astSync()` methods have been added to the `Processor`. These
  return the `Root` node of the selectors after processing them.
* `transform()` and `transformSync()` methods have been added to the
  `Processor`. These return the value returned by the processor callback
  after processing the selectors.
* Set the parent when inserting a node (thanks to @chriseppstein).
* Correctly adjust indices when using insertBefore/insertAfter (thanks to @tivac).
* Fixes handling of namespaces with qualified tag selectors.
* `process`, `ast` and `transform` (and their sync variants) now accept a
  `postcss` rule node. When provided, better errors are generated and selector
  processing is automatically set back to the rule selector (unless the `updateSelector` option is set to `false`.)
* Now more memory efficient when tokenizing selectors.

### Upgrade hints

The pattern of:

`rule.selector = processor.process(rule.selector).result.toString();`

is now:

`processor.processSync(rule)`

# 2.2.3

* Resolves an issue where the parser would not reduce multiple spaces between an
  ampersand and another simple selector in lossy mode (thanks to @adam-26).

# 2.2.2

* No longer hangs on an unescaped semicolon; instead the parser will throw
  an exception for these cases.

# 2.2.1

* Allows a consumer to specify whitespace tokens when creating a new Node
  (thanks to @Semigradsky).

# 2.2.0

* Added a new option to normalize whitespace when parsing the selector string
  (thanks to @adam-26).

# 2.1.1

* Better unquoted value handling within attribute selectors
  (thanks to @evilebottnawi).

# 2.1.0

* Added: Use string constants for all node types & expose them on the main
  parser instance (thanks to @Aweary).

# 2.0.0

This release contains the following breaking changes:

* Renamed all `eachInside` iterators to `walk`. For example, `eachTag` is now
  `walkTags`, and `eachInside` is now `walk`.
* Renamed `Node#removeSelf()` to `Node#remove()`.
* Renamed `Container#remove()` to `Container#removeChild()`.
* Renamed `Node#raw` to `Node#raws` (thanks to @davidtheclark).
* Now parses `&` as the *nesting* selector, rather than a *tag* selector.
* Fixes misinterpretation of Sass interpolation (e.g. `#{foo}`) as an
  id selector (thanks to @davidtheclark).

and;

* Fixes parsing of attribute selectors with equals signs in them
  (e.g. `[data-attr="foo=bar"]`) (thanks to @montmanu).
* Adds `quoted` and `raw.unquoted` properties to attribute nodes
  (thanks to @davidtheclark).

# 1.3.3

* Fixes an infinite loop on `)` and `]` tokens when they had no opening pairs.
  Now postcss-selector-parser will throw when it encounters these lone tokens.

# 1.3.2

* Now uses plain integers rather than `str.charCodeAt(0)` for compiled builds.

# 1.3.1

* Update flatten to v1.x (thanks to @shinnn).

# 1.3.0

* Adds a new node type, `String`, to fix a crash on selectors such as
  `foo:bar("test")`.

# 1.2.1

* Fixes a crash when the parser encountered a trailing combinator.

# 1.2.0

* A more descriptive error is thrown when the parser expects to find a
  pseudo-class/pseudo-element (thanks to @ashelley).
* Adds support for line/column locations for selector nodes, as well as a
  `Node#sourceIndex` method (thanks to @davidtheclark).

# 1.1.4

* Fixes a crash when a selector started with a `>` combinator. The module will
  now no longer throw if a selector has a leading/trailing combinator node.

# 1.1.3

* Fixes a crash on `@` tokens.

# 1.1.2

* Fixes an infinite loop caused by using parentheses in a non-pseudo element
  context.

# 1.1.1

* Fixes a crash when a backslash ended a selector string.

# 1.1.0

* Adds support for replacing multiple nodes at once with `replaceWith`
  (thanks to @jonathantneal).
* Parser no longer throws on sequential IDs and trailing commas, to support
  parsing of selector hacks.

# 1.0.1

* Fixes using `insertAfter` and `insertBefore` during iteration.

# 1.0.0

* Adds `clone` and `replaceWith` methods to nodes.
* Adds `insertBefore` and `insertAfter` to containers.
* Stabilises API.

# 0.0.5

* Fixes crash on extra whitespace inside a pseudo selector's parentheses.
* Adds sort function to the container class.
* Enables the parser to pass its input through without transforming.
* Iteration-safe `each` and `eachInside`.

# 0.0.4

* Tidy up redundant duplication.
* Fixes a bug where the parser would loop infinitely on universal selectors
  inside pseudo selectors.
* Adds `length` getter and `eachInside`, `map`, `reduce` to the container class.
* When a selector has been removed from the tree, the root node will no longer
  cast it to a string.
* Adds node type iterators to the container class (e.g. `eachComment`).
* Adds filter function to the container class.
* Adds split function to the container class.
* Create new node types by doing `parser.id(opts)` etc.
* Adds support for pseudo classes anywhere in the selector.

# 0.0.3

* Adds `next` and `prev` to the node class.
* Adds `first` and `last` getters to the container class.
* Adds `every` and `some` iterators to the container class.
* Add `empty` alias for `removeAll`.
* Combinators are now types of node.
* Fixes the at method so that it is not an alias for `index`.
* Tidy up creation of new nodes in the parser.
* Refactors how namespaces are handled for consistency & less redundant code.
* Refactors AST to use `nodes` exclusively, and eliminates excessive nesting.
* Fixes nested pseudo parsing.
* Fixes whitespace parsing.

# 0.0.2

* Adds support for namespace selectors.
* Adds support for selectors joined by escaped spaces - such as `.\31\ 0`.

# 0.0.1

* Initial release.


---

# postcss-selector-parser [![test](https://github.com/postcss/postcss-selector-parser/actions/workflows/test.yml/badge.svg)](https://github.com/postcss/postcss-selector-parser/actions/workflows/test.yml)

> Selector parser with built in methods for working with selector strings.

## Install

With [npm](https://npmjs.com/package/postcss-selector-parser) do:

```
npm install postcss-selector-parser
```

## Quick Start

```js
const parser = require('postcss-selector-parser');
const transform = selectors => {
    selectors.walk(selector => {
        // do something with the selector
        console.log(String(selector))
    });
};

const transformed = parser(transform).processSync('h1, h2, h3');
```

To normalize selector whitespace:

```js
const parser = require('postcss-selector-parser');
const normalized = parser().processSync('h1, h2, h3', {lossless: false});
// -> h1,h2,h3
```

Async support is provided through `parser.process` and will resolve a Promise
with the resulting selector string.

## API

Please see [API.md](API.md).

## Credits

* Huge thanks to Andrey Sitnik (@ai) for work on PostCSS which helped
  accelerate this module's development.

## License

MIT


---

# Changes to PostCSS Sign Functions

### 1.1.2

_February 23, 2025_

- Updated [`@csstools/css-calc`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-calc) to [`2.1.2`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-calc/CHANGELOG.md#212) (patch)

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-sign-functions/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Sign Functions [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install @csstools/postcss-sign-functions --save-dev`

[PostCSS Sign Functions] lets you use the `sign` and `abs` functions, following the [CSS Values 4] specification.

```css
.sign {
	z-index: sign(-10px);
}

.sign {
	z-index: sign(0);
}

.sign {
	z-index: sign(10px);
}

.abs {
	z-index: abs(-10px);
}

.abs {
	z-index: abs(0);
}

.abs {
	z-index: abs(10px);
}

.abs {
	z-index: abs(10%);
}

/* becomes */

.sign {
	z-index: -1;
}

.sign {
	z-index: 0;
}

.sign {
	z-index: 1;
}

.abs {
	z-index: 10px;
}

.abs {
	z-index: 0;
}

.abs {
	z-index: 10px;
}

.abs {
	z-index: max((10%), -1 * (10%));
}
```

> [!NOTE]
> The utility of static fallbacks for `sign` and `abs` is limited.
> The most interesting values are variables and dynamic values (e.g. those containing `%`).
> It is impossible to generate static fallbacks in a build process for values that are dynamic on the client.

## Usage

Add [PostCSS Sign Functions] to your project:

```bash
npm install postcss @csstools/postcss-sign-functions --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssSignFunctions = require('@csstools/postcss-sign-functions');

postcss([
	postcssSignFunctions(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## ⚠️ About custom properties

Given the dynamic nature of custom properties it's impossible to know what the variable value is, which means the plugin can't compute a final value for the stylesheet. 

Because of that, any usage that contains a `var` is skipped.

## Options

### preserve

The `preserve` option determines whether the original notation
is preserved. By default, it is not preserved.

```js
postcssSignFunctions({ preserve: true })
```

```css
.sign {
	z-index: sign(-10px);
}

.sign {
	z-index: sign(0);
}

.sign {
	z-index: sign(10px);
}

.abs {
	z-index: abs(-10px);
}

.abs {
	z-index: abs(0);
}

.abs {
	z-index: abs(10px);
}

.abs {
	z-index: abs(10%);
}

/* becomes */

.sign {
	z-index: -1;
	z-index: sign(-10px);
}

.sign {
	z-index: 0;
	z-index: sign(0);
}

.sign {
	z-index: 1;
	z-index: sign(10px);
}

.abs {
	z-index: 10px;
	z-index: abs(-10px);
}

.abs {
	z-index: 0;
	z-index: abs(0);
}

.abs {
	z-index: 10px;
	z-index: abs(10px);
}

.abs {
	z-index: max((10%), -1 * (10%));
	z-index: abs(10%);
}
```

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#sign-functions
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/postcss-sign-functions

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Sign Functions]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-sign-functions
[CSS Values 4]: https://drafts.csswg.org/css-values-4/#sign-funcs


---

# Changes to PostCSS Stepped Value Functions

### 4.0.7

_February 23, 2025_

- Updated [`@csstools/css-calc`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-calc) to [`2.1.2`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-calc/CHANGELOG.md#212) (patch)

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-stepped-value-functions/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Stepped Value Functions [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install @csstools/postcss-stepped-value-functions --save-dev`

[PostCSS Stepped Value Functions] lets you use `round`, `rem` and `mod` stepped value functions, following the [CSS Values 4] specification.

```css
.test-functions {
	padding: 8px mod(18px, 5px) 1px calc(rem(15px, 6px) + 50%);
	transform: rotate(mod(-140deg, -90deg));
	top: round(15px, 4px);
	right: round(nearest, 15px, 4px);
	bottom: round(up, 15px, 7px);
	left: round(down, 15px, 4px);
	width: round(to-zero, 15px, 4px);
}

/* becomes */

.test-functions {
	padding: 8px 3px 1px calc(3px + 50%);
	transform: rotate(-50deg);
	top: 16px;
	right: 16px;
	bottom: 21px;
	left: 12px;
	width: 12px;
}
```

## Usage

Add [PostCSS Stepped Value Functions] to your project:

```bash
npm install postcss @csstools/postcss-stepped-value-functions --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssSteppedValueFunctions = require('@csstools/postcss-stepped-value-functions');

postcss([
	postcssSteppedValueFunctions(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## ⚠️ About custom properties

Given the dynamic nature of custom properties it's impossible to know what the variable value is, which means the plugin can't compute a final value for the stylesheet. 

Because of that, any usage that contains a `var` is skipped.

## Options

### preserve

The `preserve` option determines whether the original notation
is preserved. By default, it is not preserved.

```js
postcssSteppedValueFunctions({ preserve: true })
```

```css
.test-functions {
	padding: 8px mod(18px, 5px) 1px calc(rem(15px, 6px) + 50%);
	transform: rotate(mod(-140deg, -90deg));
	top: round(15px, 4px);
	right: round(nearest, 15px, 4px);
	bottom: round(up, 15px, 7px);
	left: round(down, 15px, 4px);
	width: round(to-zero, 15px, 4px);
}

/* becomes */

.test-functions {
	padding: 8px 3px 1px calc(3px + 50%);
	padding: 8px mod(18px, 5px) 1px calc(rem(15px, 6px) + 50%);
	transform: rotate(-50deg);
	transform: rotate(mod(-140deg, -90deg));
	top: 16px;
	top: round(15px, 4px);
	right: 16px;
	right: round(nearest, 15px, 4px);
	bottom: 21px;
	bottom: round(up, 15px, 7px);
	left: 12px;
	left: round(down, 15px, 4px);
	width: 12px;
	width: round(to-zero, 15px, 4px);
}
```

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#stepped-value-functions
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/postcss-stepped-value-functions

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Stepped Value Functions]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-stepped-value-functions
[CSS Values 4]: https://www.w3.org/TR/css-values-4/#round-func


---

# Changes to PostCSS Text Decoration Shorthand

### 4.0.2

_February 23, 2025_

- Updated [`@csstools/color-helpers`](https://github.com/csstools/postcss-plugins/tree/main/packages/color-helpers) to [`5.0.2`](https://github.com/csstools/postcss-plugins/tree/main/packages/color-helpers/CHANGELOG.md#502) (patch)

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-text-decoration-shorthand/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Text Decoration Shorthand [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install @csstools/postcss-text-decoration-shorthand --save-dev`

[PostCSS Text Decoration Shorthand] lets you use `text-decoration` as a shorthand following the [Text Decoration Specification].

```css
.example {
	text-decoration: wavy underline purple 25%;
}

/* becomes */

.example {
	text-decoration: underline;
	text-decoration: underline wavy purple;
	text-decoration-thickness: calc(0.01em * 25);
	text-decoration: wavy underline purple 25%;
}
```

## Usage

Add [PostCSS Text Decoration Shorthand] to your project:

```bash
npm install postcss @csstools/postcss-text-decoration-shorthand --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssTextDecorationShorthand = require('@csstools/postcss-text-decoration-shorthand');

postcss([
	postcssTextDecorationShorthand(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## Options

### preserve

The `preserve` option determines whether the original notation
is preserved. By default, it is preserved.

```js
postcssTextDecorationShorthand({ preserve: false })
```

```css
.example {
	text-decoration: wavy underline purple 25%;
}

/* becomes */

.example {
	text-decoration: underline;
	text-decoration: underline wavy purple;
	text-decoration-thickness: calc(0.01em * 25);
}
```

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#text-decoration-shorthand
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/postcss-text-decoration-shorthand

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Text Decoration Shorthand]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-text-decoration-shorthand
[Text Decoration Specification]: https://drafts.csswg.org/css-text-decor-4/#text-decoration-property


---

# Changes to PostCSS Trigonometric Functions

### 4.0.7

_February 23, 2025_

- Updated [`@csstools/css-calc`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-calc) to [`2.1.2`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-calc/CHANGELOG.md#212) (patch)

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-trigonometric-functions/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Trigonometric Functions [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install @csstools/postcss-trigonometric-functions --save-dev`

[PostCSS Trigonometric Functions] lets you use `sin`, `cos`, `tan`, `asin`, `acos`, `atan` and `atan2` to be able to compute trigonometric relationships following the [CSS Values 4] specification.

```css
.trigonometry {
	line-height: sin(pi / 4);
	line-height: cos(.125turn);
	line-height: tan(50grad);
	transform: rotate(asin(-1));
	transform: rotate(asin(sin(30deg + 1.0471967rad)));
	transform: rotate(acos(-1));
	transform: rotate(acos(cos(0 / 2 + 1 - 1)));
	transform: rotate(atan(infinity));
	transform: rotate(atan(e - 2.7182818284590452354));
	transform: rotate(atan2(-infinity,-infinity));
	transform: rotate(atan2(-infinity,infinity));
	transform: rotate(atan2(-infinity,infinity));
	transform: rotate(atan2(90, 15));
}

/* becomes */

.trigonometry {
	line-height: 0.70711;
	line-height: 0.70711;
	line-height: 1;
	transform: rotate(-90deg);
	transform: rotate(89.99995deg);
	transform: rotate(180deg);
	transform: rotate(0deg);
	transform: rotate(90deg);
	transform: rotate(0deg);
	transform: rotate(-135deg);
	transform: rotate(-45deg);
	transform: rotate(-45deg);
	transform: rotate(80.53768deg);
}
```

## Usage

Add [PostCSS Trigonometric Functions] to your project:

```bash
npm install postcss @csstools/postcss-trigonometric-functions --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssTrigonometricFunctions = require('@csstools/postcss-trigonometric-functions');

postcss([
	postcssTrigonometricFunctions(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## ⚠️ About custom properties

Given the dynamic nature of custom properties it's impossible to know what the variable value is, which means the plugin can't compute a final value for the stylesheet.

Because of that, any usage that contains a `var` is skipped.

## Units

[PostCSS Trigonometric Functions] lets you use different special units that are within the spec and computed at run time to be able to calculate the result of the trigonometric function.

The following units are supported:

* `pi`: Computes to `Math.PI` which is `3.141592653589793`
* `e`: Computes to `Math.E` which is `2.718281828459045`
* `infinity`, `-infinity`: Compute to `Infinity` and `-Infinity` respectively. Note that the usage is case insensitive so `InFiNiTy` is a valid value.

Some calculations (such as `sin(-infinity)`) might return `NaN` as per the spec. Given that `NaN` can't be replaced with a value that's useful to CSS it is left as is, as the result will be effectively ignored by the browser.

## Options

### preserve

The `preserve` option determines whether the original notation
is preserved. By default, it is not preserved.

```js
postcssTrigonometricFunctions({ preserve: true })
```

```css
.trigonometry {
	line-height: sin(pi / 4);
	line-height: cos(.125turn);
	line-height: tan(50grad);
	transform: rotate(asin(-1));
	transform: rotate(asin(sin(30deg + 1.0471967rad)));
	transform: rotate(acos(-1));
	transform: rotate(acos(cos(0 / 2 + 1 - 1)));
	transform: rotate(atan(infinity));
	transform: rotate(atan(e - 2.7182818284590452354));
	transform: rotate(atan2(-infinity,-infinity));
	transform: rotate(atan2(-infinity,infinity));
	transform: rotate(atan2(-infinity,infinity));
	transform: rotate(atan2(90, 15));
}

/* becomes */

.trigonometry {
	line-height: 0.70711;
	line-height: sin(pi / 4);
	line-height: 0.70711;
	line-height: cos(.125turn);
	line-height: 1;
	line-height: tan(50grad);
	transform: rotate(-90deg);
	transform: rotate(asin(-1));
	transform: rotate(89.99995deg);
	transform: rotate(asin(sin(30deg + 1.0471967rad)));
	transform: rotate(180deg);
	transform: rotate(acos(-1));
	transform: rotate(0deg);
	transform: rotate(acos(cos(0 / 2 + 1 - 1)));
	transform: rotate(90deg);
	transform: rotate(atan(infinity));
	transform: rotate(0deg);
	transform: rotate(atan(e - 2.7182818284590452354));
	transform: rotate(-135deg);
	transform: rotate(atan2(-infinity,-infinity));
	transform: rotate(-45deg);
	transform: rotate(atan2(-infinity,infinity));
	transform: rotate(-45deg);
	transform: rotate(atan2(-infinity,infinity));
	transform: rotate(80.53768deg);
	transform: rotate(atan2(90, 15));
}
```

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#trigonometric-functions
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/postcss-trigonometric-functions

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Trigonometric Functions]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-trigonometric-functions
[CSS Values 4]: https://www.w3.org/TR/css-values-4/#trig-funcs


---

# Changes to PostCSS Unset Value

### 4.0.0

_August 3, 2024_

- Updated: Support for Node v18+ (major).

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-unset-value/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Unset Value [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][postcss]


[<img alt="npm version" src="https://img.shields.io/npm/v/@csstools/postcss-unset-value.svg" height="20">][npm-url]
[<img alt="Build Status" src="https://github.com/csstools/postcss-plugins/workflows/test/badge.svg" height="20">][cli-url]
[<img alt="Discord" src="https://shields.io/badge/Discord-5865F2?logo=discord&logoColor=white">][discord]
<br><br>
[<img alt="Baseline Status" src="https://cssdb.org/images/badges-baseline/unset-value.svg" height="20">][css-url]
[<img alt="CSS Standard Status" src="https://cssdb.org/images/badges/unset-value.svg" height="20">][css-url]

[PostCSS Unset Value] lets you use the unset keyword, following the [CSS Cascading and Inheritance] specification.

```pcss
.color {
	color: unset;
}

.border-color {
	border-color: unset;
}

.margin {
	margin: unset;
}


/* becomes */
.color {
	color: inherit;
}

.border-color {
	border-color: initial;
}

.margin {
	margin: initial;
}
```

## Usage

Add [PostCSS Unset Value] to your project:

```bash
npm install postcss @csstools/postcss-unset-value --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssUnsetValue = require('@csstools/postcss-unset-value');

postcss([
  postcssUnsetValue(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```

[PostCSS Unset Value] runs in all Node environments, with special
instructions for:

| [Node](INSTALL.md#node) | [PostCSS CLI](INSTALL.md#postcss-cli) | [Webpack](INSTALL.md#webpack) | [Gulp](INSTALL.md#gulp) | [Grunt](INSTALL.md#grunt) |
| --- | --- | --- | --- | --- |

## Options

### preserve

The `preserve` option determines whether the original source
is preserved. By default, it is not preserved.

```js
postcssUnsetValue({ preserve: true })
```

```pcss
.color {
	color: unset;
}

.border-color {
	border-color: unset;
}

.margin {
	margin: unset;
}

/* becomes */

.color {
	color: inherit;
	color: unset;
}

.border-color {
	border-color: initial;
	border-color: unset;
}

.margin {
	margin: initial;
	margin: unset;
}
```

[postcss]: https://github.com/postcss/postcss

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#unset-value
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/postcss-unset-value

[Gulp PostCSS]: https://github.com/postcss/gulp-postcss
[Grunt PostCSS]: https://github.com/nDmitry/grunt-postcss
[PostCSS]: https://github.com/postcss/postcss
[PostCSS Loader]: https://github.com/postcss/postcss-loader
[CSS Cascading and Inheritance]: https://www.w3.org/TR/css-cascade-4/#inherit-initial
[PostCSS Unset Value]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-unset-value


---

# Changes to Utilities

### 2.0.0

_August 3, 2024_

- Updated: Support for Node v18+ (major).

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/packages/utilities/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# Utilities

[<img alt="npm version" src="https://img.shields.io/npm/v/@csstools/utilities.svg" height="20">][npm-url]
[<img alt="Build Status" src="https://github.com/csstools/postcss-plugins/workflows/test/badge.svg" height="20">][cli-url]
[<img alt="Discord" src="https://shields.io/badge/Discord-5865F2?logo=discord&logoColor=white">][discord]

Helpers that we use in many PostCSS plugins.

## API

[Read the API docs](./docs/utilities.md)

## Usage

Add [Utilities] to your project:

```bash
npm install @csstools/utilities --save-dev
```

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/utilities

[Utilities]: https://github.com/csstools/postcss-plugins/tree/main/packages/utilities


---

# json-ext

[![NPM version](https://img.shields.io/npm/v/@discoveryjs/json-ext.svg)](https://www.npmjs.com/package/@discoveryjs/json-ext)
[![Build Status](https://github.com/discoveryjs/json-ext/actions/workflows/ci.yml/badge.svg)](https://github.com/discoveryjs/json-ext/actions/workflows/ci.yml)
[![Coverage Status](https://coveralls.io/repos/github/discoveryjs/json-ext/badge.svg?branch=master)](https://coveralls.io/github/discoveryjs/json-ext?)
[![NPM Downloads](https://img.shields.io/npm/dm/@discoveryjs/json-ext.svg)](https://www.npmjs.com/package/@discoveryjs/json-ext)

A set of utilities that extend the use of JSON. Designed to be fast and memory efficient

Features:

- [x] `parseChunked()` – Parse JSON that comes by chunks (e.g. FS readable stream or fetch response stream)
- [x] `stringifyStream()` – Stringify stream (Node.js)
- [x] `stringifyInfo()` – Get estimated size and other facts of JSON.stringify() without converting a value to string
- [ ] **TBD** Support for circular references
- [ ] **TBD** Binary representation [branch](https://github.com/discoveryjs/json-ext/tree/binary)
- [ ] **TBD** WHATWG [Streams](https://streams.spec.whatwg.org/) support

## Install

```bash
npm install @discoveryjs/json-ext
```

## API

- [parseChunked(chunkEmitter)](#parsechunkedchunkemitter)
- [stringifyStream(value[, replacer[, space]])](#stringifystreamvalue-replacer-space)
- [stringifyInfo(value[, replacer[, space[, options]]])](#stringifyinfovalue-replacer-space-options)
    - [Options](#options)
        - [async](#async)
        - [continueOnCircular](#continueoncircular)
- [version](#version)

### parseChunked(chunkEmitter)

Works the same as [`JSON.parse()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse) but takes `chunkEmitter` instead of string and returns [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise).

> NOTE: `reviver` parameter is not supported yet, but will be added in next releases.
> NOTE: WHATWG streams aren't supported yet

When to use:
- It's required to avoid freezing the main thread during big JSON parsing, since this process can be distributed in time
- Huge JSON needs to be parsed (e.g. >500MB on Node.js)
- Needed to reduce memory pressure. `JSON.parse()` needs to receive the entire JSON before parsing it. With `parseChunked()` you may parse JSON as first bytes of it comes. This approach helps to avoid storing a huge string in the memory at a single time point and following GC.

[Benchmark](https://github.com/discoveryjs/json-ext/tree/master/benchmarks#parse-chunked)

Usage:

```js
const { parseChunked } = require('@discoveryjs/json-ext');

// as a regular Promise
parseChunked(chunkEmitter)
    .then(data => {
        /* data is parsed JSON */
    });

// using await (keep in mind that not every runtime has a support for top level await)
const data = await parseChunked(chunkEmitter);
```

Parameter `chunkEmitter` can be:
- [`ReadableStream`](https://nodejs.org/dist/latest-v14.x/docs/api/stream.html#stream_readable_streams) (Node.js only)
```js
const fs = require('fs');
const { parseChunked } = require('@discoveryjs/json-ext');

parseChunked(fs.createReadStream('path/to/file.json'))
```
- Generator, async generator or function that returns iterable (chunks). Chunk might be a `string`, `Uint8Array` or `Buffer` (Node.js only):
```js
const { parseChunked } = require('@discoveryjs/json-ext');
const encoder = new TextEncoder();

// generator
parseChunked(function*() {
    yield '{ "hello":';
    yield Buffer.from(' "wor');    // Node.js only
    yield encoder.encode('ld" }'); // returns Uint8Array(5) [ 108, 100, 34, 32, 125 ]
});

// async generator
parseChunked(async function*() {
    for await (const chunk of someAsyncSource) {
        yield chunk;
    }
});

// function that returns iterable
parseChunked(() => ['{ "hello":', ' "world"}'])
```

Using with [fetch()](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API):

```js
async function loadData(url) {
    const response = await fetch(url);
    const reader = response.body.getReader();

    return parseChunked(async function*() {
        while (true) {
            const { done, value } = await reader.read();

            if (done) {
                break;
            }

            yield value;
        }
    });
}

loadData('https://example.com/data.json')
    .then(data => {
        /* data is parsed JSON */
    })
```

### stringifyStream(value[, replacer[, space]])

Works the same as [`JSON.stringify()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify), but returns an instance of [`ReadableStream`](https://nodejs.org/dist/latest-v14.x/docs/api/stream.html#stream_readable_streams) instead of string.

> NOTE: WHATWG Streams aren't supported yet, so function available for Node.js only for now

Departs from JSON.stringify():
- Outputs `null` when `JSON.stringify()` returns `undefined` (since streams may not emit `undefined`)
- A promise is resolving and the resulting value is stringifying as a regular one
- A stream in non-object mode is piping to output as is
- A stream in object mode is piping to output as an array of objects

When to use:
- Huge JSON needs to be generated (e.g. >500MB on Node.js)
- Needed to reduce memory pressure. `JSON.stringify()` needs to generate the entire JSON before send or write it to somewhere. With `stringifyStream()` you may send a result to somewhere as first bytes of the result appears. This approach helps to avoid storing a huge string in the memory at a single time point.
- The object being serialized contains Promises or Streams (see Usage for examples)

[Benchmark](https://github.com/discoveryjs/json-ext/tree/master/benchmarks#stream-stringifying)

Usage:

```js
const { stringifyStream } = require('@discoveryjs/json-ext');

// handle events
stringifyStream(data)
    .on('data', chunk => console.log(chunk))
    .on('error', error => consold.error(error))
    .on('finish', () => console.log('DONE!'));

// pipe into a stream
stringifyStream(data)
    .pipe(writableStream);
```

Using Promise or ReadableStream in serializing object:

```js
const fs = require('fs');
const { stringifyStream } = require('@discoveryjs/json-ext');

// output will be
// {"name":"example","willSerializeResolvedValue":42,"fromFile":[1, 2, 3],"at":{"any":{"level":"promise!"}}}
stringifyStream({
    name: 'example',
    willSerializeResolvedValue: Promise.resolve(42),
    fromFile: fs.createReadStream('path/to/file.json'), // support file content is "[1, 2, 3]", it'll be inserted as it
    at: {
        any: {
            level: new Promise(resolve => setTimeout(() => resolve('promise!'), 100))
        }
    }
})

// in case several async requests are used in object, it's prefered
// to put fastest requests first, because in this case
stringifyStream({
    foo: fetch('http://example.com/request_takes_2s').then(req => req.json()),
    bar: fetch('http://example.com/request_takes_5s').then(req => req.json())
});
```

Using with [`WritableStream`](https://nodejs.org/dist/latest-v14.x/docs/api/stream.html#stream_writable_streams) (Node.js only):

```js
const fs = require('fs');
const { stringifyStream } = require('@discoveryjs/json-ext');

// pipe into a console
stringifyStream(data)
    .pipe(process.stdout);

// pipe into a file
stringifyStream(data)
    .pipe(fs.createWriteStream('path/to/file.json'));

// wrapping into a Promise
new Promise((resolve, reject) => {
    stringifyStream(data)
        .on('error', reject)
        .pipe(stream)
        .on('error', reject)
        .on('finish', resolve);
});
```

### stringifyInfo(value[, replacer[, space[, options]]])

`value`, `replacer` and `space` arguments are the same as for `JSON.stringify()`.

Result is an object:

```js
{
    minLength: Number,  // minimal bytes when values is stringified
    circular: [...],    // list of circular references
    duplicate: [...],   // list of objects that occur more than once
    async: [...]        // list of async values, i.e. promises and streams
}
```

Example:

```js
const { stringifyInfo } = require('@discoveryjs/json-ext');

console.log(
    stringifyInfo({ test: true }).minLength
);
// > 13
// that equals '{"test":true}'.length
```

#### Options

##### async

Type: `Boolean`  
Default: `false`

Collect async values (promises and streams) or not.

##### continueOnCircular

Type: `Boolean`  
Default: `false`

Stop collecting info for a value or not whenever circular reference is found. Setting option to `true` allows to find all circular references.

### version

The version of library, e.g. `"0.3.1"`.

## License

MIT


---

# @docsearch/css

Style package for [DocSearch](http://docsearch.algolia.com/), the best search experience for docs.

## Installation

```bash
yarn add @docsearch/css@3
# or
npm install @docsearch/css@3
```

If you don’t want to use a package manager, you can use a standalone endpoint:

```html
<script src="https://cdn.jsdelivr.net/npm/@docsearch/css@3"></script>
```

## Get started

```js
import '@docsearch/css';
```

## Documentation

[Read documentation →](https://docsearch.algolia.com/docs/styling)


---

# @docsearch/react

React package for [DocSearch](http://docsearch.algolia.com/), the best search experience for docs.

## Installation

```bash
yarn add @docsearch/react@3
# or
npm install @docsearch/react@3
```

If you don’t want to use a package manager, you can use a standalone endpoint:

```html
<script src="https://cdn.jsdelivr.net/npm/@docsearch/react@3"></script>
```

## Get started

DocSearch generates a fully accessible search box for you.

```jsx App.js
import { DocSearch } from '@docsearch/react';

import '@docsearch/css';

function App() {
  return (
    <DocSearch
      appId="YOUR_APP_ID"
      indexName="YOUR_INDEX_NAME"
      apiKey="YOUR_SEARCH_API_KEY"
    />
  );
}

export default App;
```

## Documentation

[Read documentation →](https://docsearch.algolia.com/docs/docsearch-v3)


---

# `@docusaurus/babel`

Docusaurus package for Babel-related utils.


---

# `@docusaurus/bundler`

Docusaurus util package to abstract the current bundler.


---

# Docusaurus core


---

# `@docusaurus/cssnano-preset`

An advanced cssnano preset for maximum optimization.


---

# `@docusaurus/logger`

An encapsulated logger for semantically formatting console messages.

## APIs

It exports a single object as default export: `logger`. `logger` has the following properties:

- Some useful colors.
  - `red`
  - `yellow`
  - `green`
  - `bold`
  - `dim`
- Formatters. These functions all have the signature `(msg: unknown) => string`. Note that their implementations are not guaranteed. You should only care about their semantics.
  - `path`: formats a file path.
  - `url`: formats a URL.
  - `name`: formats an identifier.
  - `code`: formats a code snippet.
  - `subdue`: subdues the text.
  - `num`: formats a number.
- The `interpolate` function. It is a template literal tag. The syntax can be found below.
- Logging functions. All logging functions can both be used as normal functions (similar to the `console.log` family, but only accepts one parameter) or template literal tags.
  - `info`: prints information.
  - `warn`: prints a warning that should be paid attention to.
  - `error`: prints an error (not necessarily halting the program) that signals significant problems.
  - `success`: prints a success message.
- The `report` function. It takes a `ReportingSeverity` value (`ignore`, `log`, `warn`, `throw`) and reports a message according to the severity.

### A word on the `error` formatter

Beware that an `error` message, even when it doesn't hang the program, is likely going to cause confusion. When users inspect logs and find an `[ERROR]`, even when the build succeeds, they will assume something is going wrong. Use it sparingly.

Docusaurus only uses `logger.error` when printing messages immediately before throwing an error, or when user has set the reporting severity of `onBrokenLink`, etc. to `"error"`.

In addition, `warn` and `error` will color the **entire** message for better attention. If you are printing large blocks of help text about an error, better use `logger.info`.

### Using the template literal tag

The template literal tag evaluates the template and expressions embedded. `interpolate` returns a new string, while other logging functions prints it. Below is a typical usage:

```js
import logger from '@docusaurus/logger';

logger.info`Hello name=${name}! You have number=${money} dollars. Here are the ${
  items.length > 1 ? 'items' : 'item'
} on the shelf: ${items}
To buy anything, enter code=${'buy x'} where code=${'x'} is the item's name; to quit, press code=${'Ctrl + C'}.`;
```

An embedded expression is optionally preceded by a flag in the form `[a-z]+=` (a few lowercase letters, followed by an equals sign, directly preceding the embedded expression). If the expression is not preceded by any flag, it's printed out as-is. Otherwise, it's formatted with one of the formatters:

- `path=`: `path`
- `url=`: `url`
- `name=`: `name`
- `code=`: `code`
- `subdue=`: `subdue`
- `number=`: `num`

If the expression is an array, it's formatted by `` `\n- ${array.join('\n- ')}\n` `` (note it automatically gets a leading line end). Each member is formatted by itself and the bullet is not formatted. So you would see the above message printed as:

![Some text output in the terminal, containing array, code, name, and number formatting](./demo.png)


---

# `@docusaurus/mdx-loader`

Docusaurus webpack loader for [MDX](https://github.com/mdx-js/mdx).

## Installation

```sh
yarn add @docusaurus/mdx-loader
```

## Usage

```js
// ...
module: {
  rules: [
    // ...
    {
      test: /\.mdx?$/,
      use: [
        {
          loader: '@docusaurus/mdx-loader',
          options: {
            // .. See options
          },
        },
      ],
    },
  ];
}
```

## Options

### `rehypePlugins`

Array of rehype plugins to manipulate the MDXHAST

### `remarkPlugins`

Array of remark plugins to manipulate the MDXAST

### `metadataPath`

A function to provide the metadataPath depending on current loaded MDX path that will be exported as the MDX metadata.

### `markdownConfig`

The global Docusaurus Markdown config (`config.markdown`), that plugin authors should forward:

```js
const loader = {
  loader: require.resolve('@docusaurus/mdx-loader'),
  options: {
    markdownConfig: siteConfig.markdown,
  },
};
```


---

# Docusaurus admonitions

Code from [remark-admonitions](https://github.com/elviswolcott/remark-admonitions) (MIT license) has been copied to this folder, and highly customized for Docusaurus needs.


---

# `@docusaurus/module-type-aliases`

Docusaurus module type aliases.


---

# `@docusaurus/plugin-content-blog`

Blog plugin for Docusaurus.

## Usage

See [plugin-content-blog documentation](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-blog).


---

# `@docusaurus/plugin-content-docs`

Docs plugin for Docusaurus.

## Usage

See [plugin-content-docs documentation](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs).


---

# Sidebars

This part is very complicated and hard to navigate. Sidebars are loaded through the following steps:

1. **Loading**. The sidebars file is read. Returns `SidebarsConfig`.
2. **Normalization**. The shorthands are expanded. This step is very lenient about the sidebars' shapes. Returns `NormalizedSidebars`.
3. **Validation**. The normalized sidebars are validated. This step happens after normalization, because the normalized sidebars are easier to validate, and allows us to repeatedly validate & generate in the future.
4. **Generation**. This step is done through the "processor" (naming is hard). The `autogenerated` items are unwrapped. In the future, steps 3 and 4 may be repeatedly done until all autogenerated items are unwrapped. Returns `ProcessedSidebars`.
   - **Important**: this step should only care about unwrapping autogenerated items, not filtering them, writing additional metadata, applying defaults, etc.—everything will be handled in the post-processor. Important because the generator is exposed to the end-user and we want it to be easy to be reasoned about.
5. **Post-processing**. Defaults are applied (collapsed states), category links are resolved, empty categories are flattened. Returns `Sidebars`.


---

# `@docusaurus/plugin-content-pages`

Pages plugin for Docusaurus.

## Usage

See [plugin-content-pages documentation](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-pages).


---

# `@docusaurus/plugin-debug`

Debug plugin for Docusaurus.

## Usage

See [plugin-debug documentation](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-debug).


---

<div align="center">
  <a href="https://npmjs.org/package/react-json-view-lite">
    <img alt="npm" src="https://img.shields.io/npm/v/react-json-view-lite.svg" />
  </a>
  <a href="https://npmjs.org/package/react-json-view-lite">
    <img alt="no dependencies" src="https://badgen.net/bundlephobia/dependency-count/react-json-view-lite" />
  </a>
  <a href="https://npmjs.org/package/react-json-view-lite">
    <img alt="size" src="https://badgen.net/bundlephobia/minzip/react-json-view-lite" />
  </a>
  <a href="https://travis-ci.com/github/AnyRoad/react-json-view-lite">
    <img alt="build" src="https://travis-ci.com/AnyRoad/react-json-view-lite.svg?branch=release" />
  </a>
  <a href="https://codecov.io/gh/anyroad/react-json-view-lite">
    <img alt="coverage" src="https://codecov.io/gh/AnyRoad/react-json-view-lite/branch/release/graph/badge.svg" />
  </a>
  <a href="https://bundlephobia.com/result?p=react-json-view-lite">
    <img alt="tree-shakeable" src="https://badgen.net/bundlephobia/tree-shaking/react-json-view-lite" />
  </a>
  <a href="https://npmjs.org/package/react-json-view-lite">
    <img alt="types included" src="https://badgen.net/npm/types/react-json-view-lite" />
  </a>

  <a href="https://npmjs.org/package/react-json-view-lite">
    <img alt="downloads per month" src="https://img.shields.io/npm/dm/react-json-view-lite" />
  </a>
  
</div>

<div>
  <strong>react-json-view-lite</strong> is a tiny component for React allowing to render JSON as a tree. It focused on the balance between performance for large JSON inputs and functionality. It might not have all the rich features (suce as customization, copy, json editinng) but still provides more than just rendering json with highlighting - e.g. ability to collapse/expand nested objects and override css. It is written in TypeScript and has no dependencies.
</div>

## Install

```bash
npm install --save react-json-view-lite
```

## Migration from the 0.9.x versions

1. Property `shouldInitiallyExpand` has different name `shouldExpandNode` in order to emphasize that it will be called every time properties change.
2. If you use custom styles:
   - `pointer` and `expander` are no longer used
   - component uses `collapseIcon`, `expandIcon`, `collapsedContent` styles in order to customize expand/collapse icon and collpased content placeholder which were previously hardcode to the `▸`, `▾` and `...`.
     Default style values use `::after` pseudo-classes to set the content.

## Usage

```tsx
import * as React from 'react';

import { JsonView, allExpanded, darkStyles, defaultStyles } from 'react-json-view-lite';
import 'react-json-view-lite/dist/index.css';

const json = {
  a: 1,
  b: 'example'
};

const App = () => {
  return (
    <React.Fragment>
      <JsonView data={json} shouldExpandNode={allExpanded} style={defaultStyles} />
      <JsonView data={json} shouldExpandNode={allExpanded} style={darkStyles} />
    </React.Fragment>
  );
};

export default App;
```

Please note that in JavaScript, an anonymous function like `function() {}` or `() => {}` always creates a different function every time component is rendered, so you might need to use
[useCallback](https://react.dev/reference/react/useCallback) React Hook for the `shouldExpandNode` parameter or extract the function outside the functional component.

### StoryBook

https://anyroad.github.io/react-json-view-lite/

### Props

| Name              | Type                                                     | Default Value | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ----------------- | -------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| data              | `Object` \| `Array<any>`                                 |               | Data which should be rendered                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| style             | StyleProps                                               | defaultStyles | Optional. CSS classes for rendering. Library provides two build-in implementations: `darkStyles`, `defaultStyles` (see below)                                                                                                                                                                                                                                                                                                                                 |
| shouldExpandNode  | `(level: number, value: any, field?: string) => boolean` | allExpanded   | Optional. Function which will be called during initial rendering for each Object and Array of the data in order to calculate should if this node be expanded. **Note** that this function will be called again to update the each node state once the property value changed. `level` startes from `0`, `field` does not have a value for the array element. Library provides two build-in implementations: `allExpanded` and `collapseAllNested` (see below) |
| clickToExpandNode | boolean                                                  | false         | Optional. Set to true if you want to expand/collapse nodes by clicking on the node itself.                                                                                                                                                                                                                                                                                                                                                                    |

### Extra exported

| Name              | Type                         | Description                                         |
| ----------------- | ---------------------------- | --------------------------------------------------- |
| defaultStyles     | StyleProps                   | Default styles for light background                 |
| darkStyles        | StyleProps                   | Default styles for dark background                  |
| allExpanded       | `() => boolean`              | Always returns `true`                               |
| collapseAllNested | `(level: number) => boolean` | Returns `true` only for the first level (`level=0`) |

### StyleProps

| Name                    | Type    | Description                                                                                                       |
| ----------------------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
| container               | string  | CSS class name for rendering parent block                                                                         |
| basicChildStyle         | string  | CSS class name for property block containing property name and value                                              |
| collapseIcon            | string  | CSS class name for rendering button collapsing Object and Array nodes. Default content is `▾`.                    |
| expandIcon              | string  | CSS class name for rendering button expanding Object and Array nodes. Default content is `▸`.                     |
| collapsedContent        | string  | CSS class name for rendering placeholder when Object and Array nodes are collapsed. Default contents is `...`.    |
| label                   | string  | CSS class name for rendering property names                                                                       |
| clickableLabel          | string  | CSS class name for rendering clickable property names (requires the `clickToExpandNode` prop to be true)          |
| nullValue               | string  | CSS class name for rendering null values                                                                          |
| undefinedValue          | string  | CSS class name for rendering undefined values                                                                     |
| numberValue             | string  | CSS class name for rendering numeric values                                                                       |
| stringValue             | string  | CSS class name for rendering string values                                                                        |
| booleanValue            | string  | CSS class name for rendering boolean values                                                                       |
| otherValue              | string  | CSS class name for rendering all other values except Object, Arrray, null, undefined, numeric, boolean and string |
| punctuation             | string  | CSS class name for rendering `,`, `[`, `]`, `{`, `}`                                                              |
| noQuotesForStringValues | boolean | whether or not to add double quotes when rendering string values, default value is `false`                        |

## Comparison with other libraries

### Size and dependencies

Here is the size benchmark (using [bundlephobia.com](https://bundlephobia.com)) against similar React libraries (found by https://www.npmjs.com/search?q=react%20json&ranking=popularity):

| Library                  | Bundle size                                                                                                                                  | Bundle size (gzip)                                                                                                                              | Dependencies                                                                                                                                              |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **react-json-view-lite** | [![](https://badgen.net/bundlephobia/min/react-json-view-lite?color=6ead0a&label=)](https://bundlephobia.com/result?p=react-json-view-lite)  | [![](https://badgen.net/bundlephobia/minzip/react-json-view-lite?color=6ead0a&label=)](https://bundlephobia.com/result?p=react-json-view-lite)  | [![](https://badgen.net/bundlephobia/dependency-count/react-json-view-lite?color=6ead0a&label=)](https://bundlephobia.com/result?p=react-json-view-lite)  |
| react-json-pretty        | [![](https://badgen.net/bundlephobia/min/react-json-pretty?color=red&label=)](https://bundlephobia.com/result?p=react-json-pretty)           | [![](https://badgen.net/bundlephobia/minzip/react-json-pretty?color=red&label=)](https://bundlephobia.com/result?p=react-json-pretty)           | [![](https://badgen.net/bundlephobia/dependency-count/react-json-pretty?color=red&label=)](https://bundlephobia.com/result?p=react-json-pretty)           |
| react-json-inspector     | [![](https://badgen.net/bundlephobia/min/react-json-inspector?color=red&label=)](https://bundlephobia.com/result?p=react-json-inspector)     | [![](https://badgen.net/bundlephobia/minzip/react-json-inspector?color=red&label=)](https://bundlephobia.com/result?p=react-json-inspector)     | [![](https://badgen.net/bundlephobia/dependency-count/react-json-inspector?color=red&label=)](https://bundlephobia.com/result?p=react-json-inspector)     |
| react-json-tree          | [![](https://badgen.net/bundlephobia/min/react-json-tree?color=red&label=)](https://bundlephobia.com/result?p=react-json-tree)               | [![](https://badgen.net/bundlephobia/minzip/react-json-tree?color=red&label=)](https://bundlephobia.com/result?p=react-json-tree)               | [![](https://badgen.net/bundlephobia/dependency-count/react-json-tree?color=red&label=)](https://bundlephobia.com/result?p=react-json-tree)               |
| react-json-view          | [![](https://badgen.net/bundlephobia/min/react-json-view?color=red&label=)](https://bundlephobia.com/result?p=react-json-view)               | [![](https://badgen.net/bundlephobia/minzip/react-json-view?color=red&label=)](https://bundlephobia.com/result?p=react-json-view)               | [![](https://badgen.net/bundlephobia/dependency-count/react-json-view?color=red&label=)](https://bundlephobia.com/result?p=react-json-view)               |
| react-json-tree-viewer   | [![](https://badgen.net/bundlephobia/min/react-json-tree-viewer?color=red&label=)](https://bundlephobia.com/result?p=react-json-tree-viewer) | [![](https://badgen.net/bundlephobia/minzip/react-json-tree-viewer?color=red&label=)](https://bundlephobia.com/result?p=react-json-tree-viewer) | [![](https://badgen.net/bundlephobia/dependency-count/react-json-tree-viewer?color=red&label=)](https://bundlephobia.com/result?p=react-json-tree-viewer) |

### Performance

Performance was mesaured using the [react-component-benchmark](https://github.com/paularmstrong/react-component-benchmark) library. Every component was rendered 50 times using the [300Kb json file](https://github.com/AnyRoad/react-json-view-lite-benchmark/blob/main/src/hugeJson.json) as data source, please refer to source code of the [benchmark project](https://github.com/AnyRoad/react-json-view-lite-benchmark).
All numbers are in milliseconds. Tests were performed on Macbook Air M1 16Gb RAM usging Chrome v96.0.4664.110(official build, arm64). Every component was tested 2 times but there was no significant differences in the results.

| Library                  | Min   | Max   | Average | Median | P90   |
| ------------------------ | ----- | ----- | ------- | ------ | ----- |
| **react-json-view-lite** | 81    | 604   | 195     | 82     | 582   |
| react-json-pretty        | 22    | 59    | 32      | 24     | 56    |
| react-json-inspector     | 682   | 1 109 | 758     | 711    | 905   |
| react-json-tree          | 565   | 1 217 | 658     | 620    | 741   |
| react-json-view          | 1 403 | 1 722 | 1529    | 1 540  | 1 631 |
| react-json-tree-viewer   | 266   | 663   | 320     | 278    | 455   |

As you can see `react-json-pretty` renders faster than other libraries but it does not have ability to collapse/expand nested objects so it might be good choice if you need just json syntax highlighting.

## License

MIT © [AnyRoad](https://github.com/AnyRoad)


---

# `@docusaurus/plugin-google-analytics`

Google analytics plugin for Docusaurus.

## Usage

See [plugin-google-analytics documentation](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-google-analytics).


---

# `@docusaurus/plugin-google-gtag`

Global Site Tag (gtag.js) plugin for Docusaurus.

## Usage

See [plugin-google-gtag documentation](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-google-gtag).


---

# `@docusaurus/plugin-google-tag-manager`

Google Tag Manager plugin for Docusaurus.

## Usage

See [plugin-google-tag-manager documentation](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-google-tag-manager).


---

# `@docusaurus/plugin-sitemap`

Simple sitemap generation plugin for Docusaurus.

## Usage

See [plugin-sitemap documentation](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-sitemap).


---

# `@docusaurus/plugin-svgr`

[SVGR](https://react-svgr.com/) plugin for Docusaurus.

## Usage

See [plugin-svgr documentation](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-svgr).


---

# `@docusaurus/preset-classic`

Classic preset for Docusaurus.

## Usage

See [presets documentation](https://docusaurus.io/docs/using-plugins#using-presets).


---

# Docusaurus Theme Classic

The classic theme for Docusaurus.

## Installation

Add `docusaurus/theme-classic` to your package:

```bash
npm i @docusaurus/theme-classic
# or
yarn add @docusaurus/theme-classic
```

Modify your `docusaurus.config.js`:

```diff
module.exports = {
  ...
+ themes: ['@docusaurus/theme-classic'],
  ...
}
```

## Swizzling components

```bash
$ npm swizzle @docusaurus/theme-classic [component name]
```

All components used by this theme can be found [here](https://github.com/facebook/docusaurus/tree/main/packages/docusaurus-theme-classic/src/theme)


---

# clsx [![CI](https://github.com/lukeed/clsx/workflows/CI/badge.svg)](https://github.com/lukeed/clsx/actions?query=workflow%3ACI) [![codecov](https://badgen.net/codecov/c/github/lukeed/clsx)](https://codecov.io/gh/lukeed/clsx) [![licenses](https://licenses.dev/b/npm/clsx)](https://licenses.dev/npm/clsx)

> A tiny (239B) utility for constructing `className` strings conditionally.<Br>Also serves as a [faster](bench) & smaller drop-in replacement for the `classnames` module.

This module is available in three formats:

* **ES Module**: `dist/clsx.mjs`
* **CommonJS**: `dist/clsx.js`
* **UMD**: `dist/clsx.min.js`


## Install

```
$ npm install --save clsx
```


## Usage

```js
import clsx from 'clsx';
// or
import { clsx } from 'clsx';

// Strings (variadic)
clsx('foo', true && 'bar', 'baz');
//=> 'foo bar baz'

// Objects
clsx({ foo:true, bar:false, baz:isTrue() });
//=> 'foo baz'

// Objects (variadic)
clsx({ foo:true }, { bar:false }, null, { '--foobar':'hello' });
//=> 'foo --foobar'

// Arrays
clsx(['foo', 0, false, 'bar']);
//=> 'foo bar'

// Arrays (variadic)
clsx(['foo'], ['', 0, false, 'bar'], [['baz', [['hello'], 'there']]]);
//=> 'foo bar baz hello there'

// Kitchen sink (with nesting)
clsx('foo', [1 && 'bar', { baz:false, bat:null }, ['hello', ['world']]], 'cya');
//=> 'foo bar hello world cya'
```


## API

### clsx(...input)
Returns: `String`

#### input
Type: `Mixed`

The `clsx` function can take ***any*** number of arguments, each of which can be an Object, Array, Boolean, or String.

> **Important:** _Any_ falsey values are discarded!<br>Standalone Boolean values are discarded as well.

```js
clsx(true, false, '', null, undefined, 0, NaN);
//=> ''
```

## Modes

There are multiple "versions" of `clsx` available, which allows you to bring only the functionality you need!

#### `clsx`
> **Size (gzip):** 239 bytes<br>
> **Availability:** CommonJS, ES Module, UMD

The default `clsx` module; see [API](#API) for info.

```js
import { clsx } from 'clsx';
// or
import clsx from 'clsx';
```

#### `clsx/lite`
> **Size (gzip):** 140 bytes<br>
> **Availability:** CommonJS, ES Module<br>
> **CAUTION:** Accepts **ONLY** string arguments!

Ideal for applications that ***only*** use the string-builder pattern.

Any non-string arguments are ignored!

```js
import { clsx } from 'clsx/lite';
// or
import clsx from 'clsx/lite';

// string
clsx('hello', true && 'foo', false && 'bar');
// => "hello foo"

// NOTE: Any non-string input(s) ignored
clsx({ foo: true });
//=> ""
```

## Benchmarks

For snapshots of cross-browser results, check out the [`bench`](bench) directory~!

## Support

All versions of Node.js are supported.

All browsers that support [`Array.isArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/isArray#Browser_compatibility) are supported (IE9+).

>**Note:** For IE8 support and older, please install `clsx@1.0.x` and beware of [#17](https://github.com/lukeed/clsx/issues/17).

## Tailwind Support

Here some additional (optional) steps to enable classes autocompletion using `clsx` with Tailwind CSS.

<details>
<summary>
  Visual Studio Code
</summary>

1. [Install the "Tailwind CSS IntelliSense" Visual Studio Code extension](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss)

2. Add the following to your [`settings.json`](https://code.visualstudio.com/docs/getstarted/settings):

  ```json
   {
    "tailwindCSS.experimental.classRegex": [
      ["clsx\\(([^)]*)\\)", "(?:'|\"|`)([^']*)(?:'|\"|`)"]
    ]
   }
  ```
</details>

You may find the [`clsx/lite`](#clsxlite) module useful within Tailwind contexts. This is especially true if/when your application **only** composes classes in this pattern:

```js
clsx('text-base', props.active && 'text-primary', props.className);
```

## Related

- [obj-str](https://github.com/lukeed/obj-str) - A smaller (96B) and similiar utility that only works with Objects.

## License

MIT © [Luke Edwards](https://lukeed.com)


---

<a href="https://commerce.nearform.com/open-source/" target="_blank">
  <img alt="Prism React Renderer" src="https://oss.nearform.com/api/banner.svg?text=prism+react+renderer" />
</a>

<p align="center" style="font-size: 1.2rem;">
  A lean <a href="https://github.com/PrismJS/prism">Prism</a> highlighter component for React
</p>

<p align="center">
  <a href="https://npmjs.com/package/prism-react-renderer"><img src="https://img.shields.io/npm/dm/prism-react-renderer.svg"></a>
  <a href="https://npmjs.com/package/prism-react-renderer"><img src="https://img.shields.io/npm/v/prism-react-renderer.svg"></a>
  <a href="https://github.com/FormidableLabs/prism-react-renderer#maintenance-status">
    <img alt="Maintenance Status" src="https://img.shields.io/badge/maintenance-active-green.svg" />
  </a>
</p>

<p align="center">
  Comes with everything to render Prismjs syntax highlighted code directly in React & React Native!
</p>

## Introduction

Prism React Renderer powers syntax highlighting in the amazing [Docusaurus](https://docusaurus.io/) framework and many others.

This library tokenises code using Prism and provides a small render-props-driven
component to quickly render it out into React. This is why it even works with
React Native! It's bundled with a modified version of Prism that won't pollute
the global namespace and comes with
[a couple of common language syntaxes](./packages/generate-prism-languages/index.ts#L9-L23).

_(There's also an [escape-hatch](https://github.com/FormidableLabs/prism-react-renderer#prism) to use your own Prism setup, just in case)_

It also comes with its own [VSCode-like theming format](#theming), which means by default
you can easily drop in different themes, use the ones this library ships with, or
create new ones programmatically on the fly.

_(If you just want to use your Prism CSS-file themes, that's also no problem)_

## Table of Contents

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->


- [Installation](#installation)
  - [Usage](#usage)
  - [Custom Language Support](#custom-language-support)
- [Basic Props](#basic-props)
  - [children](#children)
  - [language](#language)
  - [code](#code)
- [Advanced Props](#advanced-props)
  - [theme](#theme)
  - [prism](#prism)
- [Children Function](#children-function)
  - [state](#state)
  - [prop getters](#prop-getters)
    - [`getLineProps`](#getlineprops)
    - [`getTokenProps`](#gettokenprops)
- [Utility Functions](#utility-functions)
  - [`normalizeTokens`](#normalizetokens)
  - [`useTokenize`](#usetokenize)
- [Theming](#theming)
- [Upgrading from v1 to v2](#upgrade)
- [LICENSE](#license)
- [Maintenance Status](#maintenance-status)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## Installation

This module is distributed via npm which is bundled with node and
should be installed as one of your project's `dependencies`:

```sh
# npm
npm install --save prism-react-renderer
# yarn
yarn add prism-react-renderer
# pnpm
pnpm add prism-react-renderer
```

> Prism React Renderer has a peer dependency on `react`

### Usage
Prism React Renderer has a named export for the `<Highlight />` component along with `themes`. To see Prism React Render in action with base styling check out `packages/demo` or run `pnpm run start:demo` from the root of this repository.

```tsx
import React from "react"
import ReactDOM from "react-dom/client"
import { Highlight, themes } from "prism-react-renderer"
import styles from 'styles.module.css'

const codeBlock = `
const GroceryItem: React.FC<GroceryItemProps> = ({ item }) => {
  return (
    <div>
      <h2>{item.name}</h2>
      <p>Price: {item.price}</p>
      <p>Quantity: {item.quantity}</p>
    </div>
  );
}
`

export const App = () => (
  <Highlight
    theme={themes.shadesOfPurple}
    code={codeBlock}
    language="tsx"
  >
    {({ className, style, tokens, getLineProps, getTokenProps }) => (
      <pre style={style}>
        {tokens.map((line, i) => (
          <div key={i} {...getLineProps({ line })}>
            <span>{i + 1}</span>
            {line.map((token, key) => (
              <span key={key} {...getTokenProps({ token })} />
            ))}
          </div>
        ))}
      </pre>
    )}
  </Highlight>
)

ReactDOM
  .createRoot(document.getElementById("root") as HTMLElement)
  .render(<App />)
```

### Custom Language Support

By default `prism-react-renderer` only includes a [base set of languages](https://github.com/FormidableLabs/prism-react-renderer/blob/c914fdea48625ba59c8022174bb3df1ed802ce4d/packages/generate-prism-languages/index.ts#L9-L23) that Prism supports. 

> _Note_: Some languages (such as Javascript) are part of the bundle of other languages

**Depending on your app's build system you may need to `await` the `import` or use `require` to ensure `window.Prism` exists before importing the custom languages.** You can add support for more by including their definitions from the main `prismjs` package:

```js
import { Highlight, Prism } from "prism-react-renderer";

(typeof global !== "undefined" ? global : window).Prism = Prism
await import("prismjs/components/prism-applescript")
/** or **/
require("prismjs/components/prism-applescript")
```


## Basic Props

This is the list of props that you should probably know about. There are some
[advanced props](#advanced-props) below as well.

Most of these [advanced props](#advanced-props) are included in the `defaultProps`.

### children

> `function({})` | _required_

This is called with an object. Read more about the properties of this object in
the section "[Children Function](#children-function)".

### language

> `string` | _required_

This is the language that your code will be highlighted as. You can see a list
of all languages that are supported out of the box [here](./packages/generate-prism-languages/index.ts#L9-L23). Not all languages are included and the list of languages that are currently is a little arbitrary. You can use the [escape-hatch](https://github.com/FormidableLabs/prism-react-renderer#prism) to use your own Prism setup, just in case, or [add more languages to the bundled Prism.](https://github.com/FormidableLabs/prism-react-renderer#faq)

### code

> `string` | _required_

This is the code that will be highlighted.

## Advanced Props

### theme

> `PrismTheme` | _optional; default is vsDark_

If a theme is passed, it is used to generate style props which can be retrieved
via the prop-getters which are described in "[Children Function](#children-function)".

Read more about how to theme `prism-react-renderer` in
the section "[Theming](#theming)".

### prism

> `prism` | _optional; default is the vendored version_

This is the [Prismjs](https://github.com/PrismJS/prism) library itself.
A vendored version of Prism is provided (and also exported) as part of this library.
This vendored version doesn't pollute the global namespace, is slimmed down,
and doesn't conflict with any installation of `prismjs` you might have.

If you're only using `Prism.highlight` you can choose to use `prism-react-renderer`'s
exported, vendored version of Prism instead.

But if you choose to use your own Prism setup, simply pass Prism as a prop:

```jsx
// Whichever way you're retrieving Prism here:
import Prism from 'prismjs/components/prism-core';

<Highlight prism={Prism} {/* ... */} />
```

## Children Function

This is where you render whatever you want to based on the output of `<Highlight />`.
You use it like so:

```js
const ui = (
  <Highlight>
    {highlight => (
      // use utilities and prop getters here, like highlight.className, highlight.getTokenProps, etc.
      <pre>{/* more jsx here */}</pre>
    )}
  </Highlight>
);
```

The properties of this `highlight` object can be split into two categories as indicated below:

### state

These properties are the flat output of `<Highlight />`. They're generally "state" and are what
you'd usually expect from a render-props-based API.

| property    | type        | description                                                                                                                  |
| ----------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `tokens`    | `Token[][]` | This is a doubly nested array of tokens. The outer array is for separate lines, the inner for tokens, so the actual content. |
| `className` | `string`    | This is the class you should apply to your wrapping element, typically a `<pre>`                                             |

A "Token" is an object that represents a piece of content for Prism. It has a `types` property, which is an array
of types that indicate the purpose and styling of a piece of text, and a `content` property, which is the actual
text.

You'd typically iterate over `tokens`, rendering each line, and iterate over its items, rendering out each token, which is a piece of
this line.

### prop getters

> See
> [Kent C. Dodds' blog post about prop getters](https://blog.kentcdodds.com/how-to-give-rendering-control-to-users-with-prop-getters-549eaef76acf)

These functions are used to apply props to the elements that you render. This
gives you maximum flexibility to render what, when, and wherever you like.

You'd typically call these functions with some dictated input and add on all other
props that it should pass through. It'll correctly override and modify the props
that it returns to you, so passing props to it instead of adding them directly is
advisable.

| property        | type           | description                                                                                           |
| --------------- | -------------- | ----------------------------------------------------------------------------------------------------- |
| `getLineProps`  | `function({})` | returns the props you should apply to any list of tokens, i.e. the element that contains your tokens. |
| `getTokenProps` | `function({})` | returns the props you should apply to the elements displaying tokens that you render.                 |

#### `getLineProps`

You need to add a `line` property (type: `Token[]`) to the object you're passing to
`getLineProps`.

This getter will return you props to spread onto your line elements (typically `<div>s`).

It will typically return a `className` (if you pass one it'll be appended), `children`,
`style` (if you pass one it'll be merged). It also passes on all other props you pass
to the input.

The `className` will always contain `.token-line`.

#### `getTokenProps`

You need to add a `token` property (type: `Token`) to the object you're passing to
`getTokenProps`.

This getter will return you props to spread onto your token elements (typically `<span>s`).

It will typically return a `className` (if you pass one it'll be appended), `children`,
`style` (if you pass one it'll be merged). It also passes on all other props you pass
to the input.

The `className` will always contain `.token`. This also provides full compatibility with
your old Prism CSS-file themes.

## Utility Functions

### `useTokenize`

> `(options: TokenizeOptions) => Token[][]`

```ts
type TokenizeOptions = {
  prism: PrismLib
  code: string
  grammar?: PrismGrammar
  language: Language
}

```

This is a React hook that tokenizes code using Prism. It returns an array of tokens that can be rendered using the built-in `<Highlight />` component or your own custom component. It uses `normalizeTokens` internally to convert the tokens into a shape that can be rendered.

- `prism: PrismLib`: the Prism library to use for tokenization. This can be the vendored version of Prism that is included with `prism-react-renderer` or a custom version of Prism that you have configured.

- `code: string`: a string containing the code to tokenize.
- `grammar?: PrismGrammar`: a Prism grammar object to use for tokenization. If this is omitted, the tokens will just be normalized. A grammar can be obtained from `Prism.languages` or by importing a language from `prismjs/components/`.
- `language: Language`: the language to use for tokenization. This should be a language that Prism supports.

### `normalizeTokens`

> `(tokens: (PrismToken | string)[]) => Token[][]`

Takes an array of Prism’s tokens and groups them by line, converting strings into tokens. Tokens can become recursive in some cases which means that their types are concatenated. Plain-string tokens however are always of type `plain`.

- `PrismToken` is an internal alias for `Token` exported by `prismjs` and is defined [here](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/prismjs/index.d.ts#L347).

- `Token` is an internal object that represents a slice of tokenized content for Prism with three properties:
  - `types: string[]`: an array of types that indicate the purpose and styling of a piece of text
  - `content: string`: the content of the token
  - `empty: boolean`: a flag indicating whether the token is empty or not.

## Theming

The `defaultProps` you'd typically apply in a basic use-case, contain a default theme.
This theme is [vsDark](./packages/prism-react-renderer/src/themes/vsDark.ts).

While all `className`s are provided with `<Highlight />`, so that you could use your good
old Prism CSS-file themes, you can also choose to use `prism-react-renderer`'s themes like so:

```jsx
import { Highlight, themes } from 'prism-react-renderer';

<Highlight theme={themes.dracula} {/* ... */} />
```

These themes are JSON-based and are heavily inspired by VSCode's theme format.

Their syntax, expressed in Flow looks like the following:

```js
{
  plain: StyleObj,
  styles: Array<{
    types: string[],
    languages?: string[],
    style: StyleObj
  }>
}
```

The `plain` property provides a base style-object. This style object is directly used
in the `style` props that you'll receive from the prop getters, if a `theme` prop has
been passed to `<Highlight />`.

The `styles` property contains an array of definitions. Each definition contains a `style`
property, that is also just a style object. These styles are limited by the `types`
and `languages` properties.

The `types` properties is an array of token types that Prism outputs. The `languages`
property limits styles to highlighted languages.

When converting a Prism CSS theme it's mostly just necessary to use classes as
`types` and convert the declarations to object-style-syntax and put them on `style`.

## Upgrade

If you are migrating from v1.x to v2.x, follow these steps

### Change module imports

```diff
- import Highlight, { defaultProps } from "prism-react-renderer";
+ import { Highlight } from "prism-react-renderer"

const Content = (
-  <Highlight {...defaultProps} code={exampleCode} language="jsx">
+  <Highlight code={exampleCode} language="jsx">
```

### Change theme imports

```diff
- const theme = require('prism-react-renderer/themes/github')
+ const theme = require('prism-react-renderer').themes.github
```

### Check language support

> By default prism-react-renderer only includes a base set of languages that Prism supports. Depending on your app's build system you may need to await the import or use require to ensure window.Prism exists before importing the custom languages.

See: https://github.com/FormidableLabs/prism-react-renderer#custom-language-support

Install prismjs (if not available yet):

```
# npm
npm install --save prismjs
# yarn
yarn add prismjs
# pnpm
pnpm add prismjs
```

### Add language component

If the language is not already bundled in the above, you can add additional languages with the following code:

```
import { Highlight, Prism } from "prism-react-renderer";

(typeof global !== "undefined" ? global : window).Prism = Prism
await import("prismjs/components/prism-applescript")
/** or **/
require("prismjs/components/prism-applescript")
```

## LICENSE

MIT

## Maintenance Status

**Active:** Nearform is actively working on this project, and we expect to continue work for the foreseeable future. Bug reports, feature requests and pull requests are welcome.

[maintenance-image]: https://img.shields.io/badge/maintenance-active-green.svg


---

# `@docusaurus/theme-common`

Common code for Docusaurus themes.


---

# clsx [![CI](https://github.com/lukeed/clsx/workflows/CI/badge.svg)](https://github.com/lukeed/clsx/actions?query=workflow%3ACI) [![codecov](https://badgen.net/codecov/c/github/lukeed/clsx)](https://codecov.io/gh/lukeed/clsx) [![licenses](https://licenses.dev/b/npm/clsx)](https://licenses.dev/npm/clsx)

> A tiny (239B) utility for constructing `className` strings conditionally.<Br>Also serves as a [faster](bench) & smaller drop-in replacement for the `classnames` module.

This module is available in three formats:

* **ES Module**: `dist/clsx.mjs`
* **CommonJS**: `dist/clsx.js`
* **UMD**: `dist/clsx.min.js`


## Install

```
$ npm install --save clsx
```


## Usage

```js
import clsx from 'clsx';
// or
import { clsx } from 'clsx';

// Strings (variadic)
clsx('foo', true && 'bar', 'baz');
//=> 'foo bar baz'

// Objects
clsx({ foo:true, bar:false, baz:isTrue() });
//=> 'foo baz'

// Objects (variadic)
clsx({ foo:true }, { bar:false }, null, { '--foobar':'hello' });
//=> 'foo --foobar'

// Arrays
clsx(['foo', 0, false, 'bar']);
//=> 'foo bar'

// Arrays (variadic)
clsx(['foo'], ['', 0, false, 'bar'], [['baz', [['hello'], 'there']]]);
//=> 'foo bar baz hello there'

// Kitchen sink (with nesting)
clsx('foo', [1 && 'bar', { baz:false, bat:null }, ['hello', ['world']]], 'cya');
//=> 'foo bar hello world cya'
```


## API

### clsx(...input)
Returns: `String`

#### input
Type: `Mixed`

The `clsx` function can take ***any*** number of arguments, each of which can be an Object, Array, Boolean, or String.

> **Important:** _Any_ falsey values are discarded!<br>Standalone Boolean values are discarded as well.

```js
clsx(true, false, '', null, undefined, 0, NaN);
//=> ''
```

## Modes

There are multiple "versions" of `clsx` available, which allows you to bring only the functionality you need!

#### `clsx`
> **Size (gzip):** 239 bytes<br>
> **Availability:** CommonJS, ES Module, UMD

The default `clsx` module; see [API](#API) for info.

```js
import { clsx } from 'clsx';
// or
import clsx from 'clsx';
```

#### `clsx/lite`
> **Size (gzip):** 140 bytes<br>
> **Availability:** CommonJS, ES Module<br>
> **CAUTION:** Accepts **ONLY** string arguments!

Ideal for applications that ***only*** use the string-builder pattern.

Any non-string arguments are ignored!

```js
import { clsx } from 'clsx/lite';
// or
import clsx from 'clsx/lite';

// string
clsx('hello', true && 'foo', false && 'bar');
// => "hello foo"

// NOTE: Any non-string input(s) ignored
clsx({ foo: true });
//=> ""
```

## Benchmarks

For snapshots of cross-browser results, check out the [`bench`](bench) directory~!

## Support

All versions of Node.js are supported.

All browsers that support [`Array.isArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/isArray#Browser_compatibility) are supported (IE9+).

>**Note:** For IE8 support and older, please install `clsx@1.0.x` and beware of [#17](https://github.com/lukeed/clsx/issues/17).

## Tailwind Support

Here some additional (optional) steps to enable classes autocompletion using `clsx` with Tailwind CSS.

<details>
<summary>
  Visual Studio Code
</summary>

1. [Install the "Tailwind CSS IntelliSense" Visual Studio Code extension](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss)

2. Add the following to your [`settings.json`](https://code.visualstudio.com/docs/getstarted/settings):

  ```json
   {
    "tailwindCSS.experimental.classRegex": [
      ["clsx\\(([^)]*)\\)", "(?:'|\"|`)([^']*)(?:'|\"|`)"]
    ]
   }
  ```
</details>

You may find the [`clsx/lite`](#clsxlite) module useful within Tailwind contexts. This is especially true if/when your application **only** composes classes in this pattern:

```js
clsx('text-base', props.active && 'text-primary', props.className);
```

## Related

- [obj-str](https://github.com/lukeed/obj-str) - A smaller (96B) and similiar utility that only works with Objects.

## License

MIT © [Luke Edwards](https://lukeed.com)


---

<a href="https://commerce.nearform.com/open-source/" target="_blank">
  <img alt="Prism React Renderer" src="https://oss.nearform.com/api/banner.svg?text=prism+react+renderer" />
</a>

<p align="center" style="font-size: 1.2rem;">
  A lean <a href="https://github.com/PrismJS/prism">Prism</a> highlighter component for React
</p>

<p align="center">
  <a href="https://npmjs.com/package/prism-react-renderer"><img src="https://img.shields.io/npm/dm/prism-react-renderer.svg"></a>
  <a href="https://npmjs.com/package/prism-react-renderer"><img src="https://img.shields.io/npm/v/prism-react-renderer.svg"></a>
  <a href="https://github.com/FormidableLabs/prism-react-renderer#maintenance-status">
    <img alt="Maintenance Status" src="https://img.shields.io/badge/maintenance-active-green.svg" />
  </a>
</p>

<p align="center">
  Comes with everything to render Prismjs syntax highlighted code directly in React & React Native!
</p>

## Introduction

Prism React Renderer powers syntax highlighting in the amazing [Docusaurus](https://docusaurus.io/) framework and many others.

This library tokenises code using Prism and provides a small render-props-driven
component to quickly render it out into React. This is why it even works with
React Native! It's bundled with a modified version of Prism that won't pollute
the global namespace and comes with
[a couple of common language syntaxes](./packages/generate-prism-languages/index.ts#L9-L23).

_(There's also an [escape-hatch](https://github.com/FormidableLabs/prism-react-renderer#prism) to use your own Prism setup, just in case)_

It also comes with its own [VSCode-like theming format](#theming), which means by default
you can easily drop in different themes, use the ones this library ships with, or
create new ones programmatically on the fly.

_(If you just want to use your Prism CSS-file themes, that's also no problem)_

## Table of Contents

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->


- [Installation](#installation)
  - [Usage](#usage)
  - [Custom Language Support](#custom-language-support)
- [Basic Props](#basic-props)
  - [children](#children)
  - [language](#language)
  - [code](#code)
- [Advanced Props](#advanced-props)
  - [theme](#theme)
  - [prism](#prism)
- [Children Function](#children-function)
  - [state](#state)
  - [prop getters](#prop-getters)
    - [`getLineProps`](#getlineprops)
    - [`getTokenProps`](#gettokenprops)
- [Utility Functions](#utility-functions)
  - [`normalizeTokens`](#normalizetokens)
  - [`useTokenize`](#usetokenize)
- [Theming](#theming)
- [Upgrading from v1 to v2](#upgrade)
- [LICENSE](#license)
- [Maintenance Status](#maintenance-status)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## Installation

This module is distributed via npm which is bundled with node and
should be installed as one of your project's `dependencies`:

```sh
# npm
npm install --save prism-react-renderer
# yarn
yarn add prism-react-renderer
# pnpm
pnpm add prism-react-renderer
```

> Prism React Renderer has a peer dependency on `react`

### Usage
Prism React Renderer has a named export for the `<Highlight />` component along with `themes`. To see Prism React Render in action with base styling check out `packages/demo` or run `pnpm run start:demo` from the root of this repository.

```tsx
import React from "react"
import ReactDOM from "react-dom/client"
import { Highlight, themes } from "prism-react-renderer"
import styles from 'styles.module.css'

const codeBlock = `
const GroceryItem: React.FC<GroceryItemProps> = ({ item }) => {
  return (
    <div>
      <h2>{item.name}</h2>
      <p>Price: {item.price}</p>
      <p>Quantity: {item.quantity}</p>
    </div>
  );
}
`

export const App = () => (
  <Highlight
    theme={themes.shadesOfPurple}
    code={codeBlock}
    language="tsx"
  >
    {({ className, style, tokens, getLineProps, getTokenProps }) => (
      <pre style={style}>
        {tokens.map((line, i) => (
          <div key={i} {...getLineProps({ line })}>
            <span>{i + 1}</span>
            {line.map((token, key) => (
              <span key={key} {...getTokenProps({ token })} />
            ))}
          </div>
        ))}
      </pre>
    )}
  </Highlight>
)

ReactDOM
  .createRoot(document.getElementById("root") as HTMLElement)
  .render(<App />)
```

### Custom Language Support

By default `prism-react-renderer` only includes a [base set of languages](https://github.com/FormidableLabs/prism-react-renderer/blob/c914fdea48625ba59c8022174bb3df1ed802ce4d/packages/generate-prism-languages/index.ts#L9-L23) that Prism supports. 

> _Note_: Some languages (such as Javascript) are part of the bundle of other languages

**Depending on your app's build system you may need to `await` the `import` or use `require` to ensure `window.Prism` exists before importing the custom languages.** You can add support for more by including their definitions from the main `prismjs` package:

```js
import { Highlight, Prism } from "prism-react-renderer";

(typeof global !== "undefined" ? global : window).Prism = Prism
await import("prismjs/components/prism-applescript")
/** or **/
require("prismjs/components/prism-applescript")
```


## Basic Props

This is the list of props that you should probably know about. There are some
[advanced props](#advanced-props) below as well.

Most of these [advanced props](#advanced-props) are included in the `defaultProps`.

### children

> `function({})` | _required_

This is called with an object. Read more about the properties of this object in
the section "[Children Function](#children-function)".

### language

> `string` | _required_

This is the language that your code will be highlighted as. You can see a list
of all languages that are supported out of the box [here](./packages/generate-prism-languages/index.ts#L9-L23). Not all languages are included and the list of languages that are currently is a little arbitrary. You can use the [escape-hatch](https://github.com/FormidableLabs/prism-react-renderer#prism) to use your own Prism setup, just in case, or [add more languages to the bundled Prism.](https://github.com/FormidableLabs/prism-react-renderer#faq)

### code

> `string` | _required_

This is the code that will be highlighted.

## Advanced Props

### theme

> `PrismTheme` | _optional; default is vsDark_

If a theme is passed, it is used to generate style props which can be retrieved
via the prop-getters which are described in "[Children Function](#children-function)".

Read more about how to theme `prism-react-renderer` in
the section "[Theming](#theming)".

### prism

> `prism` | _optional; default is the vendored version_

This is the [Prismjs](https://github.com/PrismJS/prism) library itself.
A vendored version of Prism is provided (and also exported) as part of this library.
This vendored version doesn't pollute the global namespace, is slimmed down,
and doesn't conflict with any installation of `prismjs` you might have.

If you're only using `Prism.highlight` you can choose to use `prism-react-renderer`'s
exported, vendored version of Prism instead.

But if you choose to use your own Prism setup, simply pass Prism as a prop:

```jsx
// Whichever way you're retrieving Prism here:
import Prism from 'prismjs/components/prism-core';

<Highlight prism={Prism} {/* ... */} />
```

## Children Function

This is where you render whatever you want to based on the output of `<Highlight />`.
You use it like so:

```js
const ui = (
  <Highlight>
    {highlight => (
      // use utilities and prop getters here, like highlight.className, highlight.getTokenProps, etc.
      <pre>{/* more jsx here */}</pre>
    )}
  </Highlight>
);
```

The properties of this `highlight` object can be split into two categories as indicated below:

### state

These properties are the flat output of `<Highlight />`. They're generally "state" and are what
you'd usually expect from a render-props-based API.

| property    | type        | description                                                                                                                  |
| ----------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `tokens`    | `Token[][]` | This is a doubly nested array of tokens. The outer array is for separate lines, the inner for tokens, so the actual content. |
| `className` | `string`    | This is the class you should apply to your wrapping element, typically a `<pre>`                                             |

A "Token" is an object that represents a piece of content for Prism. It has a `types` property, which is an array
of types that indicate the purpose and styling of a piece of text, and a `content` property, which is the actual
text.

You'd typically iterate over `tokens`, rendering each line, and iterate over its items, rendering out each token, which is a piece of
this line.

### prop getters

> See
> [Kent C. Dodds' blog post about prop getters](https://blog.kentcdodds.com/how-to-give-rendering-control-to-users-with-prop-getters-549eaef76acf)

These functions are used to apply props to the elements that you render. This
gives you maximum flexibility to render what, when, and wherever you like.

You'd typically call these functions with some dictated input and add on all other
props that it should pass through. It'll correctly override and modify the props
that it returns to you, so passing props to it instead of adding them directly is
advisable.

| property        | type           | description                                                                                           |
| --------------- | -------------- | ----------------------------------------------------------------------------------------------------- |
| `getLineProps`  | `function({})` | returns the props you should apply to any list of tokens, i.e. the element that contains your tokens. |
| `getTokenProps` | `function({})` | returns the props you should apply to the elements displaying tokens that you render.                 |

#### `getLineProps`

You need to add a `line` property (type: `Token[]`) to the object you're passing to
`getLineProps`.

This getter will return you props to spread onto your line elements (typically `<div>s`).

It will typically return a `className` (if you pass one it'll be appended), `children`,
`style` (if you pass one it'll be merged). It also passes on all other props you pass
to the input.

The `className` will always contain `.token-line`.

#### `getTokenProps`

You need to add a `token` property (type: `Token`) to the object you're passing to
`getTokenProps`.

This getter will return you props to spread onto your token elements (typically `<span>s`).

It will typically return a `className` (if you pass one it'll be appended), `children`,
`style` (if you pass one it'll be merged). It also passes on all other props you pass
to the input.

The `className` will always contain `.token`. This also provides full compatibility with
your old Prism CSS-file themes.

## Utility Functions

### `useTokenize`

> `(options: TokenizeOptions) => Token[][]`

```ts
type TokenizeOptions = {
  prism: PrismLib
  code: string
  grammar?: PrismGrammar
  language: Language
}

```

This is a React hook that tokenizes code using Prism. It returns an array of tokens that can be rendered using the built-in `<Highlight />` component or your own custom component. It uses `normalizeTokens` internally to convert the tokens into a shape that can be rendered.

- `prism: PrismLib`: the Prism library to use for tokenization. This can be the vendored version of Prism that is included with `prism-react-renderer` or a custom version of Prism that you have configured.

- `code: string`: a string containing the code to tokenize.
- `grammar?: PrismGrammar`: a Prism grammar object to use for tokenization. If this is omitted, the tokens will just be normalized. A grammar can be obtained from `Prism.languages` or by importing a language from `prismjs/components/`.
- `language: Language`: the language to use for tokenization. This should be a language that Prism supports.

### `normalizeTokens`

> `(tokens: (PrismToken | string)[]) => Token[][]`

Takes an array of Prism’s tokens and groups them by line, converting strings into tokens. Tokens can become recursive in some cases which means that their types are concatenated. Plain-string tokens however are always of type `plain`.

- `PrismToken` is an internal alias for `Token` exported by `prismjs` and is defined [here](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/prismjs/index.d.ts#L347).

- `Token` is an internal object that represents a slice of tokenized content for Prism with three properties:
  - `types: string[]`: an array of types that indicate the purpose and styling of a piece of text
  - `content: string`: the content of the token
  - `empty: boolean`: a flag indicating whether the token is empty or not.

## Theming

The `defaultProps` you'd typically apply in a basic use-case, contain a default theme.
This theme is [vsDark](./packages/prism-react-renderer/src/themes/vsDark.ts).

While all `className`s are provided with `<Highlight />`, so that you could use your good
old Prism CSS-file themes, you can also choose to use `prism-react-renderer`'s themes like so:

```jsx
import { Highlight, themes } from 'prism-react-renderer';

<Highlight theme={themes.dracula} {/* ... */} />
```

These themes are JSON-based and are heavily inspired by VSCode's theme format.

Their syntax, expressed in Flow looks like the following:

```js
{
  plain: StyleObj,
  styles: Array<{
    types: string[],
    languages?: string[],
    style: StyleObj
  }>
}
```

The `plain` property provides a base style-object. This style object is directly used
in the `style` props that you'll receive from the prop getters, if a `theme` prop has
been passed to `<Highlight />`.

The `styles` property contains an array of definitions. Each definition contains a `style`
property, that is also just a style object. These styles are limited by the `types`
and `languages` properties.

The `types` properties is an array of token types that Prism outputs. The `languages`
property limits styles to highlighted languages.

When converting a Prism CSS theme it's mostly just necessary to use classes as
`types` and convert the declarations to object-style-syntax and put them on `style`.

## Upgrade

If you are migrating from v1.x to v2.x, follow these steps

### Change module imports

```diff
- import Highlight, { defaultProps } from "prism-react-renderer";
+ import { Highlight } from "prism-react-renderer"

const Content = (
-  <Highlight {...defaultProps} code={exampleCode} language="jsx">
+  <Highlight code={exampleCode} language="jsx">
```

### Change theme imports

```diff
- const theme = require('prism-react-renderer/themes/github')
+ const theme = require('prism-react-renderer').themes.github
```

### Check language support

> By default prism-react-renderer only includes a base set of languages that Prism supports. Depending on your app's build system you may need to await the import or use require to ensure window.Prism exists before importing the custom languages.

See: https://github.com/FormidableLabs/prism-react-renderer#custom-language-support

Install prismjs (if not available yet):

```
# npm
npm install --save prismjs
# yarn
yarn add prismjs
# pnpm
pnpm add prismjs
```

### Add language component

If the language is not already bundled in the above, you can add additional languages with the following code:

```
import { Highlight, Prism } from "prism-react-renderer";

(typeof global !== "undefined" ? global : window).Prism = Prism
await import("prismjs/components/prism-applescript")
/** or **/
require("prismjs/components/prism-applescript")
```

## LICENSE

MIT

## Maintenance Status

**Active:** Nearform is actively working on this project, and we expect to continue work for the foreseeable future. Bug reports, feature requests and pull requests are welcome.

[maintenance-image]: https://img.shields.io/badge/maintenance-active-green.svg


---

# `@docusaurus/theme-search-algolia`

Algolia search component for Docusaurus.

## Usage

See [`@docusaurus/theme-search-algolia` documentation](https://docusaurus.io/docs/api/themes/@docusaurus/theme-search-algolia).


---

# clsx [![CI](https://github.com/lukeed/clsx/workflows/CI/badge.svg)](https://github.com/lukeed/clsx/actions?query=workflow%3ACI) [![codecov](https://badgen.net/codecov/c/github/lukeed/clsx)](https://codecov.io/gh/lukeed/clsx) [![licenses](https://licenses.dev/b/npm/clsx)](https://licenses.dev/npm/clsx)

> A tiny (239B) utility for constructing `className` strings conditionally.<Br>Also serves as a [faster](bench) & smaller drop-in replacement for the `classnames` module.

This module is available in three formats:

* **ES Module**: `dist/clsx.mjs`
* **CommonJS**: `dist/clsx.js`
* **UMD**: `dist/clsx.min.js`


## Install

```
$ npm install --save clsx
```


## Usage

```js
import clsx from 'clsx';
// or
import { clsx } from 'clsx';

// Strings (variadic)
clsx('foo', true && 'bar', 'baz');
//=> 'foo bar baz'

// Objects
clsx({ foo:true, bar:false, baz:isTrue() });
//=> 'foo baz'

// Objects (variadic)
clsx({ foo:true }, { bar:false }, null, { '--foobar':'hello' });
//=> 'foo --foobar'

// Arrays
clsx(['foo', 0, false, 'bar']);
//=> 'foo bar'

// Arrays (variadic)
clsx(['foo'], ['', 0, false, 'bar'], [['baz', [['hello'], 'there']]]);
//=> 'foo bar baz hello there'

// Kitchen sink (with nesting)
clsx('foo', [1 && 'bar', { baz:false, bat:null }, ['hello', ['world']]], 'cya');
//=> 'foo bar hello world cya'
```


## API

### clsx(...input)
Returns: `String`

#### input
Type: `Mixed`

The `clsx` function can take ***any*** number of arguments, each of which can be an Object, Array, Boolean, or String.

> **Important:** _Any_ falsey values are discarded!<br>Standalone Boolean values are discarded as well.

```js
clsx(true, false, '', null, undefined, 0, NaN);
//=> ''
```

## Modes

There are multiple "versions" of `clsx` available, which allows you to bring only the functionality you need!

#### `clsx`
> **Size (gzip):** 239 bytes<br>
> **Availability:** CommonJS, ES Module, UMD

The default `clsx` module; see [API](#API) for info.

```js
import { clsx } from 'clsx';
// or
import clsx from 'clsx';
```

#### `clsx/lite`
> **Size (gzip):** 140 bytes<br>
> **Availability:** CommonJS, ES Module<br>
> **CAUTION:** Accepts **ONLY** string arguments!

Ideal for applications that ***only*** use the string-builder pattern.

Any non-string arguments are ignored!

```js
import { clsx } from 'clsx/lite';
// or
import clsx from 'clsx/lite';

// string
clsx('hello', true && 'foo', false && 'bar');
// => "hello foo"

// NOTE: Any non-string input(s) ignored
clsx({ foo: true });
//=> ""
```

## Benchmarks

For snapshots of cross-browser results, check out the [`bench`](bench) directory~!

## Support

All versions of Node.js are supported.

All browsers that support [`Array.isArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/isArray#Browser_compatibility) are supported (IE9+).

>**Note:** For IE8 support and older, please install `clsx@1.0.x` and beware of [#17](https://github.com/lukeed/clsx/issues/17).

## Tailwind Support

Here some additional (optional) steps to enable classes autocompletion using `clsx` with Tailwind CSS.

<details>
<summary>
  Visual Studio Code
</summary>

1. [Install the "Tailwind CSS IntelliSense" Visual Studio Code extension](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss)

2. Add the following to your [`settings.json`](https://code.visualstudio.com/docs/getstarted/settings):

  ```json
   {
    "tailwindCSS.experimental.classRegex": [
      ["clsx\\(([^)]*)\\)", "(?:'|\"|`)([^']*)(?:'|\"|`)"]
    ]
   }
  ```
</details>

You may find the [`clsx/lite`](#clsxlite) module useful within Tailwind contexts. This is especially true if/when your application **only** composes classes in this pattern:

```js
clsx('text-base', props.active && 'text-primary', props.className);
```

## Related

- [obj-str](https://github.com/lukeed/obj-str) - A smaller (96B) and similiar utility that only works with Objects.

## License

MIT © [Luke Edwards](https://lukeed.com)


---

# Docusaurus theme translations

This package includes default translations for labels (like the pagination "Next" / "Previous") used by official Docusaurus themes.

## For Docusaurus users:

Please help us provide exhaustive translations:

- add new translation by running `yarn workspace @docusaurus/theme-translations update %new_lang_code%`, then edit generated JSON files
- double-check existent `language.json` file for bad or missing translations

## For maintainers:

After updating the theme code, you can "synchronize" the translations by running:

```
yarn workspace @docusaurus/theme-translations update
```

Then, ask contributors to translate the newly added labels on this [issue](https://github.com/facebook/docusaurus/issues/3526)


---

# `@docusaurus/types`

Common types for Docusaurus packages.


---

[![Financial Contributors on Open Collective](https://opencollective.com/webpack-merge/all/badge.svg?label=financial+contributors)](https://opencollective.com/webpack-merge) [![Test](https://github.com/survivejs/webpack-merge/actions/workflows/test.yml/badge.svg?branch=develop&event=push)](https://github.com/survivejs/webpack-merge/actions/workflows/test.yml) [![codecov](https://codecov.io/gh/survivejs/webpack-merge/branch/master/graph/badge.svg)](https://codecov.io/gh/survivejs/webpack-merge)

# webpack-merge - Merge designed for Webpack

**webpack-merge** provides a `merge` function that concatenates arrays and merges objects creating a new object. If functions are encountered, it will execute them, run the results through the algorithm, and then wrap the returned values within a function again.

This behavior is particularly useful in configuring webpack although it has uses beyond it. Whenever you need to merge configuration objects, **webpack-merge** can come in handy.

## **`merge(...configuration | [...configuration])`**

`merge` is the core, and the most important idea, of the API. Often this is all you need unless you want further customization.

```javascript
const { merge } = require('webpack-merge');

// Default API
const output = merge(object1, object2, object3, ...);

// You can pass an array of objects directly.
// This works with all available functions.
const output = merge([object1, object2, object3]);

// Keys matching to the right take precedence:
const output = merge(
  { fruit: "apple", color: "red" },
  { fruit: "strawberries" }
);
console.log(output);
// { color: "red", fruit: "strawberries"}
```

### Limitations

Note that `Promise`s are not supported! If you want to return a configuration wrapped within a `Promise`, `merge` inside one. Example: `Promise.resolve(merge({ ... }, { ... }))`.

The same goes for configuration level functions as in the example below:

**webpack.config.js**

```javascript
const commonConfig = { ... };

const productionConfig = { ... };

const developmentConfig = { ... };

module.exports = (env, args) => {
  switch(args.mode) {
    case 'development':
      return merge(commonConfig, developmentConfig);
    case 'production':
      return merge(commonConfig, productionConfig);
    default:
      throw new Error('No matching configuration was found!');
  }
}
```

You can choose the configuration you want by using `webpack --mode development` assuming you are using _webpack-cli_.

## **`mergeWithCustomize({ customizeArray, customizeObject })(...configuration | [...configuration])`**

In case you need more flexibility, `merge` behavior can be customized per field as below:

```javascript
const { mergeWithCustomize } = require('webpack-merge');

const output = mergeWithCustomize(
  {
    customizeArray(a, b, key) {
      if (key === 'extensions') {
        return _.uniq([...a, ...b]);
      }

      // Fall back to default merging
      return undefined;
    },
    customizeObject(a, b, key) {
      if (key === 'module') {
        // Custom merging
        return _.merge({}, a, b);
      }

      // Fall back to default merging
      return undefined;
    }
  }
)(object1, object2, object3, ...);
```

For example, if the previous code was invoked with only `object1` and `object2`
with `object1` as:

```javascript
{
    foo1: ['object1'],
    foo2: ['object1'],
    bar1: { object1: {} },
    bar2: { object1: {} },
}
```

and `object2` as:

```javascript
{
    foo1: ['object2'],
    foo2: ['object2'],
    bar1: { object2: {} },
    bar2: { object2: {} },
}
```

then `customizeArray` will be invoked for each property of `Array` type, i.e:

```javascript
customizeArray(["object1"], ["object2"], "foo1");
customizeArray(["object1"], ["object2"], "foo2");
```

and `customizeObject` will be invoked for each property of `Object` type, i.e:

```javascript
customizeObject({ object1: {} }, { object2: {} }, bar1);
customizeObject({ object1: {} }, { object2: {} }, bar2);
```

## **`customizeArray`** and **`customizeObject`**

`customizeArray` and `customizeObject` provide small strategies to for `mergeWithCustomize`. They support `append`, `prepend`, `replace`, and wildcards for field names.

```javascript
const { mergeWithCustomize, customizeArray, customizeObject } = require('webpack-merge');

const output = mergeWithCustomize({
  customizeArray: customizeArray({
    'entry.*': 'prepend'
  }),
  customizeObject: customizeObject({
    entry: 'prepend'
  })
})(object1, object2, object3, ...);
```

## **`unique(<field>, <fields>, field => field)`**

`unique` is a strategy used for forcing uniqueness within configuration. It's most useful with plugins when you want to make sure there's only one in place.

The first `<field>` is the config property to look through for duplicates.

`<fields>` represents the values that should be unique when you run the field => field function on each duplicate.

When the order of elements of the `<field>` in the first configuration differs from the order in the second configuration, the latter is preserved.

```javascript
const { mergeWithCustomize, unique } = require("webpack-merge");

const output = mergeWithCustomize({
  customizeArray: unique(
    "plugins",
    ["HotModuleReplacementPlugin"],
    (plugin) => plugin.constructor && plugin.constructor.name
  ),
})(
  {
    plugins: [new webpack.HotModuleReplacementPlugin()],
  },
  {
    plugins: [new webpack.HotModuleReplacementPlugin()],
  }
);

// Output contains only single HotModuleReplacementPlugin now and it's
// going to be the last plugin instance.
```

## **`mergeWithRules`**

To support advanced merging needs (i.e. merging within loaders), `mergeWithRules` includes additional syntax that allows you to match fields and apply strategies to match. Consider the full example below:

```javascript
const a = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [{ loader: "style-loader" }, { loader: "sass-loader" }],
      },
    ],
  },
};
const b = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          {
            loader: "style-loader",
            options: {
              modules: true,
            },
          },
        ],
      },
    ],
  },
};
const result = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          {
            loader: "style-loader",
            options: {
              modules: true,
            },
          },
          { loader: "sass-loader" },
        ],
      },
    ],
  },
};

assert.deepStrictEqual(
  mergeWithRules({
    module: {
      rules: {
        test: "match",
        use: {
          loader: "match",
          options: "replace",
        },
      },
    },
  })(a, b),
  result
);
```

The way it works is that you should annotate fields to match using `match` (or `CustomizeRule.Match` if you are using TypeScript) matching your configuration structure and then use specific strategies to define how particular fields should be transformed. If a match doesn't exist above a rule, then it will apply the rule automatically.

**Supported annotations:**

- `match` (`CustomizeRule.Match`) - Optional matcher that scopes merging behavior to a specific part based on similarity (think DOM or jQuery selectors)
- `append` (`CustomizeRule.Append`) - Appends items
- `prepend` (`CustomizeRule.Prepend`) - Prepends items
- `replace` (`CustomizeRule.Replace`) - Replaces items
- `merge` (`CustomizeRule.Merge`) - Merges objects (shallow merge)

## Using with TypeScript

**webpack-merge** supports TypeScript out of the box. You should pass `Configuration` type from webpack to it as follows:

```typescript
import { Configuration } from "webpack";
import { merge } from "webpack-merge";

const config = merge<Configuration>({...}, {...});

...
```

## Development

1. `nvm use`
1. `npm i`
1. `npm run build -- --watch` in one terminal
1. `npm t -- --watch` in another one

Before contributing, please [open an issue](https://github.com/survivejs/webpack-merge/issues/new) where to discuss.

## Further Information and Support

Check out [SurviveJS - Webpack 5](http://survivejs.com/) to dig deeper into webpack. The free book uses **webpack-merge** extensively and shows you how to compose your configuration to keep it maintainable.

I am also available as a consultant in case you require specific assistance. I can contribute particularly in terms of improving maintainability of the setup while speeding it up and pointing out better practices. In addition to improving developer productivity, the work has impact on the end users of the product in terms of reduced application size and loading times.

## Contributors

### Code Contributors

This project exists thanks to all the people who contribute. [[Contribute](CONTRIBUTING.md)].
<a href="https://github.com/survivejs/webpack-merge/graphs/contributors"><img src="https://opencollective.com/webpack-merge/contributors.svg?width=890&button=false" /></a>

### Financial Contributors

Become a financial contributor and help us sustain our community. [[Contribute](https://opencollective.com/webpack-merge/contribute)]

#### Individuals

<a href="https://opencollective.com/webpack-merge"><img src="https://opencollective.com/webpack-merge/individuals.svg?width=890"></a>

#### Organizations

Support this project with your organization. Your logo will show up here with a link to your website. [[Contribute](https://opencollective.com/webpack-merge/contribute)]

<a href="https://opencollective.com/webpack-merge/organization/0/website"><img src="https://opencollective.com/webpack-merge/organization/0/avatar.svg"></a>
<a href="https://opencollective.com/webpack-merge/organization/1/website"><img src="https://opencollective.com/webpack-merge/organization/1/avatar.svg"></a>
<a href="https://opencollective.com/webpack-merge/organization/2/website"><img src="https://opencollective.com/webpack-merge/organization/2/avatar.svg"></a>
<a href="https://opencollective.com/webpack-merge/organization/3/website"><img src="https://opencollective.com/webpack-merge/organization/3/avatar.svg"></a>
<a href="https://opencollective.com/webpack-merge/organization/4/website"><img src="https://opencollective.com/webpack-merge/organization/4/avatar.svg"></a>
<a href="https://opencollective.com/webpack-merge/organization/5/website"><img src="https://opencollective.com/webpack-merge/organization/5/avatar.svg"></a>
<a href="https://opencollective.com/webpack-merge/organization/6/website"><img src="https://opencollective.com/webpack-merge/organization/6/avatar.svg"></a>
<a href="https://opencollective.com/webpack-merge/organization/7/website"><img src="https://opencollective.com/webpack-merge/organization/7/avatar.svg"></a>
<a href="https://opencollective.com/webpack-merge/organization/8/website"><img src="https://opencollective.com/webpack-merge/organization/8/avatar.svg"></a>
<a href="https://opencollective.com/webpack-merge/organization/9/website"><img src="https://opencollective.com/webpack-merge/organization/9/avatar.svg"></a>

## License

**webpack-merge** is available under MIT. See LICENSE for more details.


---

# `@docusaurus/utils`

Node utility functions for Docusaurus packages.


---

# `@docusaurus/utils`

Common (Node/Browser) utility functions for Docusaurus packages.


---

# `@docusaurus/utils-validation`

Node validation utility functions for Docusaurus packages.


---

Copyright (c) 2011-2020, Sideway Inc, and project contributors  
Copyright (c) 2011-2014, Walmart  
Copyright (c) 2011, Yahoo Inc.

All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
* The names of any contributors may not be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS AND CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS OFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


---

<a href="https://hapi.dev"><img src="https://raw.githubusercontent.com/hapijs/assets/master/images/family.png" width="180px" align="right" /></a>

# @hapi/hoek

#### Utility methods for the hapi ecosystem.

**hoek** is part of the **hapi** ecosystem and was designed to work seamlessly with the [hapi web framework](https://hapi.dev) and its other components (but works great on its own or with other frameworks). If you are using a different web framework and find this module useful, check out [hapi](https://hapi.dev) – they work even better together.

This module is not intended to solve every problem for everyone, but rather as a central place to store hapi-specific methods. If you're looking for a general purpose utility module, check out [lodash](https://github.com/lodash/lodash).

### Visit the [hapi.dev](https://hapi.dev) Developer Portal for tutorials, documentation, and support

## Useful resources

- [Documentation and API](https://hapi.dev/family/hoek/)
- [Version status](https://hapi.dev/resources/status/#hoek) (builds, dependencies, node versions, licenses, eol)
- [Changelog](https://hapi.dev/family/hoek/changelog/)
- [Project policies](https://hapi.dev/policies/)
- [Free and commercial support options](https://hapi.dev/support/)


---

Copyright (c) 2012-2020, Sideway Inc, and project contributors  
Copyright (c) 2012-2014, Walmart.  
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
* The names of any contributors may not be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS AND CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS OFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


---

<a href="https://hapi.dev"><img src="https://raw.githubusercontent.com/hapijs/assets/master/images/family.png" width="180px" align="right" /></a>

# @hapi/topo

#### Topological sorting with grouping support.

**topo** is part of the **hapi** ecosystem and was designed to work seamlessly with the [hapi web framework](https://hapi.dev) and its other components (but works great on its own or with other frameworks). If you are using a different web framework and find this module useful, check out [hapi](https://hapi.dev) – they work even better together.

### Visit the [hapi.dev](https://hapi.dev) Developer Portal for tutorials, documentation, and support

## Useful resources

- [Documentation and API](https://hapi.dev/family/topo/)
- [Version status](https://hapi.dev/resources/status/#topo) (builds, dependencies, node versions, licenses, eol)
- [Changelog](https://hapi.dev/family/topo/changelog/)
- [Project policies](https://hapi.dev/policies/)
- [Free and commercial support options](https://hapi.dev/support/)


---

# `@jest/schemas`

Experimental and currently incomplete module for JSON schemas for [Jest's](https://jestjs.io/) configuration.


---

# @jest/types

This package contains shared types of Jest's packages.

If you are looking for types of [Jest globals](https://jestjs.io/docs/api), you can import them from `@jest/globals` package:

```ts
import {describe, expect, it} from '@jest/globals';

describe('my tests', () => {
  it('works', () => {
    expect(1).toBe(1);
  });
});
```

If you prefer to omit imports, a similar result can be achieved installing the [@types/jest](https://npmjs.com/package/@types/jest) package. Note that this is a third party library maintained at [DefinitelyTyped](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/jest) and may not cover the latest Jest features.

Another use-case for `@types/jest` is a typed Jest config as those types are not provided by Jest out of the box:

```ts
// jest.config.ts
import {Config} from '@jest/types';

const config: Config.InitialOptions = {
  // some typed config
};

export default config;
```


---

# @jridgewell/gen-mapping

> Generate source maps

`gen-mapping` allows you to generate a source map during transpilation or minification.
With a source map, you're able to trace the original location in the source file, either in Chrome's
DevTools or using a library like [`@jridgewell/trace-mapping`][trace-mapping].

You may already be familiar with the [`source-map`][source-map] package's `SourceMapGenerator`. This
provides the same `addMapping` and `setSourceContent` API.

## Installation

```sh
npm install @jridgewell/gen-mapping
```

## Usage

```typescript
import { GenMapping, addMapping, setSourceContent, toEncodedMap, toDecodedMap } from '@jridgewell/gen-mapping';

const map = new GenMapping({
  file: 'output.js',
  sourceRoot: 'https://example.com/',
});

setSourceContent(map, 'input.js', `function foo() {}`);

addMapping(map, {
  // Lines start at line 1, columns at column 0.
  generated: { line: 1, column: 0 },
  source: 'input.js',
  original: { line: 1, column: 0 },
});

addMapping(map, {
  generated: { line: 1, column: 9 },
  source: 'input.js',
  original: { line: 1, column: 9 },
  name: 'foo',
});

assert.deepEqual(toDecodedMap(map), {
  version: 3,
  file: 'output.js',
  names: ['foo'],
  sourceRoot: 'https://example.com/',
  sources: ['input.js'],
  sourcesContent: ['function foo() {}'],
  mappings: [
    [ [0, 0, 0, 0], [9, 0, 0, 9, 0] ]
  ],
});

assert.deepEqual(toEncodedMap(map), {
  version: 3,
  file: 'output.js',
  names: ['foo'],
  sourceRoot: 'https://example.com/',
  sources: ['input.js'],
  sourcesContent: ['function foo() {}'],
  mappings: 'AAAA,SAASA',
});
```

### Smaller Sourcemaps

Not everything needs to be added to a sourcemap, and needless markings can cause signficantly
larger file sizes. `gen-mapping` exposes `maybeAddSegment`/`maybeAddMapping` APIs that will
intelligently determine if this marking adds useful information. If not, the marking will be
skipped.

```typescript
import { maybeAddMapping } from '@jridgewell/gen-mapping';

const map = new GenMapping();

// Adding a sourceless marking at the beginning of a line isn't useful.
maybeAddMapping(map, {
  generated: { line: 1, column: 0 },
});

// Adding a new source marking is useful.
maybeAddMapping(map, {
  generated: { line: 1, column: 0 },
  source: 'input.js',
  original: { line: 1, column: 0 },
});

// But adding another marking pointing to the exact same original location isn't, even if the
// generated column changed.
maybeAddMapping(map, {
  generated: { line: 1, column: 9 },
  source: 'input.js',
  original: { line: 1, column: 0 },
});

assert.deepEqual(toEncodedMap(map), {
  version: 3,
  names: [],
  sources: ['input.js'],
  sourcesContent: [null],
  mappings: 'AAAA',
});
```

## Benchmarks

```
node v18.0.0

amp.js.map
Memory Usage:
gen-mapping: addSegment      5852872 bytes
gen-mapping: addMapping      7716042 bytes
source-map-js                6143250 bytes
source-map-0.6.1             6124102 bytes
source-map-0.8.0             6121173 bytes
Smallest memory usage is gen-mapping: addSegment

Adding speed:
gen-mapping:      addSegment x 441 ops/sec ±2.07% (90 runs sampled)
gen-mapping:      addMapping x 350 ops/sec ±2.40% (86 runs sampled)
source-map-js:    addMapping x 169 ops/sec ±2.42% (80 runs sampled)
source-map-0.6.1: addMapping x 167 ops/sec ±2.56% (80 runs sampled)
source-map-0.8.0: addMapping x 168 ops/sec ±2.52% (80 runs sampled)
Fastest is gen-mapping:      addSegment

Generate speed:
gen-mapping:      decoded output x 150,824,370 ops/sec ±0.07% (102 runs sampled)
gen-mapping:      encoded output x 663 ops/sec ±0.22% (98 runs sampled)
source-map-js:    encoded output x 197 ops/sec ±0.45% (84 runs sampled)
source-map-0.6.1: encoded output x 198 ops/sec ±0.33% (85 runs sampled)
source-map-0.8.0: encoded output x 197 ops/sec ±0.06% (93 runs sampled)
Fastest is gen-mapping:      decoded output


***


babel.min.js.map
Memory Usage:
gen-mapping: addSegment     37578063 bytes
gen-mapping: addMapping     37212897 bytes
source-map-js               47638527 bytes
source-map-0.6.1            47690503 bytes
source-map-0.8.0            47470188 bytes
Smallest memory usage is gen-mapping: addMapping

Adding speed:
gen-mapping:      addSegment x 31.05 ops/sec ±8.31% (43 runs sampled)
gen-mapping:      addMapping x 29.83 ops/sec ±7.36% (51 runs sampled)
source-map-js:    addMapping x 20.73 ops/sec ±6.22% (38 runs sampled)
source-map-0.6.1: addMapping x 20.03 ops/sec ±10.51% (38 runs sampled)
source-map-0.8.0: addMapping x 19.30 ops/sec ±8.27% (37 runs sampled)
Fastest is gen-mapping:      addSegment

Generate speed:
gen-mapping:      decoded output x 381,379,234 ops/sec ±0.29% (96 runs sampled)
gen-mapping:      encoded output x 95.15 ops/sec ±2.98% (72 runs sampled)
source-map-js:    encoded output x 15.20 ops/sec ±7.41% (33 runs sampled)
source-map-0.6.1: encoded output x 16.36 ops/sec ±10.46% (31 runs sampled)
source-map-0.8.0: encoded output x 16.06 ops/sec ±6.45% (31 runs sampled)
Fastest is gen-mapping:      decoded output


***


preact.js.map
Memory Usage:
gen-mapping: addSegment       416247 bytes
gen-mapping: addMapping       419824 bytes
source-map-js                1024619 bytes
source-map-0.6.1             1146004 bytes
source-map-0.8.0             1113250 bytes
Smallest memory usage is gen-mapping: addSegment

Adding speed:
gen-mapping:      addSegment x 13,755 ops/sec ±0.15% (98 runs sampled)
gen-mapping:      addMapping x 13,013 ops/sec ±0.11% (101 runs sampled)
source-map-js:    addMapping x 4,564 ops/sec ±0.21% (98 runs sampled)
source-map-0.6.1: addMapping x 4,562 ops/sec ±0.11% (99 runs sampled)
source-map-0.8.0: addMapping x 4,593 ops/sec ±0.11% (100 runs sampled)
Fastest is gen-mapping:      addSegment

Generate speed:
gen-mapping:      decoded output x 379,864,020 ops/sec ±0.23% (93 runs sampled)
gen-mapping:      encoded output x 14,368 ops/sec ±4.07% (82 runs sampled)
source-map-js:    encoded output x 5,261 ops/sec ±0.21% (99 runs sampled)
source-map-0.6.1: encoded output x 5,124 ops/sec ±0.58% (99 runs sampled)
source-map-0.8.0: encoded output x 5,434 ops/sec ±0.33% (96 runs sampled)
Fastest is gen-mapping:      decoded output


***


react.js.map
Memory Usage:
gen-mapping: addSegment       975096 bytes
gen-mapping: addMapping      1102981 bytes
source-map-js                2918836 bytes
source-map-0.6.1             2885435 bytes
source-map-0.8.0             2874336 bytes
Smallest memory usage is gen-mapping: addSegment

Adding speed:
gen-mapping:      addSegment x 4,772 ops/sec ±0.15% (100 runs sampled)
gen-mapping:      addMapping x 4,456 ops/sec ±0.13% (97 runs sampled)
source-map-js:    addMapping x 1,618 ops/sec ±0.24% (97 runs sampled)
source-map-0.6.1: addMapping x 1,622 ops/sec ±0.12% (99 runs sampled)
source-map-0.8.0: addMapping x 1,631 ops/sec ±0.12% (100 runs sampled)
Fastest is gen-mapping:      addSegment

Generate speed:
gen-mapping:      decoded output x 379,107,695 ops/sec ±0.07% (99 runs sampled)
gen-mapping:      encoded output x 5,421 ops/sec ±1.60% (89 runs sampled)
source-map-js:    encoded output x 2,113 ops/sec ±1.81% (98 runs sampled)
source-map-0.6.1: encoded output x 2,126 ops/sec ±0.10% (100 runs sampled)
source-map-0.8.0: encoded output x 2,176 ops/sec ±0.39% (98 runs sampled)
Fastest is gen-mapping:      decoded output
```

[source-map]: https://www.npmjs.com/package/source-map
[trace-mapping]: https://github.com/jridgewell/trace-mapping


---

# @jridgewell/resolve-uri

> Resolve a URI relative to an optional base URI

Resolve any combination of absolute URIs, protocol-realtive URIs, absolute paths, or relative paths.

## Installation

```sh
npm install @jridgewell/resolve-uri
```

## Usage

```typescript
function resolve(input: string, base?: string): string;
```

```js
import resolve from '@jridgewell/resolve-uri';

resolve('foo', 'https://example.com'); // => 'https://example.com/foo'
```

| Input                 | Base                    | Resolution                     | Explanation                                                  |
|-----------------------|-------------------------|--------------------------------|--------------------------------------------------------------|
| `https://example.com` | _any_                   | `https://example.com/`         | Input is normalized only                                     |
| `//example.com`       | `https://base.com/`     | `https://example.com/`         | Input inherits the base's protocol                           |
| `//example.com`       | _rest_                  | `//example.com/`               | Input is normalized only                                     |
| `/example`            | `https://base.com/`     | `https://base.com/example`     | Input inherits the base's origin                             |
| `/example`            | `//base.com/`           | `//base.com/example`           | Input inherits the base's host and remains protocol relative |
| `/example`            | _rest_                  | `/example`                     | Input is normalized only                                     |
| `example`             | `https://base.com/dir/` | `https://base.com/dir/example` | Input is joined with the base                                |
| `example`             | `https://base.com/file` | `https://base.com/example`     | Input is joined with the base without its file               |
| `example`             | `//base.com/dir/`       | `//base.com/dir/example`       | Input is joined with the base's last directory               |
| `example`             | `//base.com/file`       | `//base.com/example`           | Input is joined with the base without its file               |
| `example`             | `/base/dir/`            | `/base/dir/example`            | Input is joined with the base's last directory               |
| `example`             | `/base/file`            | `/base/example`                | Input is joined with the base without its file               |
| `example`             | `base/dir/`             | `base/dir/example`             | Input is joined with the base's last directory               |
| `example`             | `base/file`             | `base/example`                 | Input is joined with the base without its file               |


---

# @jridgewell/set-array

> Like a Set, but provides the index of the `key` in the backing array

This is designed to allow synchronizing a second array with the contents of the backing array, like
how in a sourcemap `sourcesContent[i]` is the source content associated with `source[i]`, and there
are never duplicates.

## Installation

```sh
npm install @jridgewell/set-array
```

## Usage

```js
import { SetArray, get, put, pop } from '@jridgewell/set-array';

const sa = new SetArray();

let index = put(sa, 'first');
assert.strictEqual(index, 0);

index = put(sa, 'second');
assert.strictEqual(index, 1);

assert.deepEqual(sa.array, [ 'first', 'second' ]);

index = get(sa, 'first');
assert.strictEqual(index, 0);

pop(sa);
index = get(sa, 'second');
assert.strictEqual(index, undefined);
assert.deepEqual(sa.array, [ 'first' ]);
```


---

# @jridgewell/source-map

> Packages `@jridgewell/trace-mapping` and `@jridgewell/gen-mapping` into the familiar source-map API

This isn't the full API, but it's the core functionality. This wraps
[@jridgewell/trace-mapping][trace-mapping] and [@jridgewell/gen-mapping][gen-mapping]
implementations.

## Installation

```sh
npm install @jridgewell/source-map
```

## Usage

TODO

### SourceMapConsumer

```typescript
import { SourceMapConsumer } from '@jridgewell/source-map';
const smc = new SourceMapConsumer({
  version: 3,
  names: ['foo'],
  sources: ['input.js'],
  mappings: 'AAAAA',
});
```

#### SourceMapConsumer.prototype.originalPositionFor(generatedPosition)

```typescript
const smc = new SourceMapConsumer(map);
smc.originalPositionFor({ line: 1, column: 0 });
```

### SourceMapGenerator

```typescript
import { SourceMapGenerator } from '@jridgewell/source-map';
const smg = new SourceMapGenerator({
  file: 'output.js',
  sourceRoot: 'https://example.com/',
});
```

#### SourceMapGenerator.prototype.addMapping(mapping)

```typescript
const smg = new SourceMapGenerator();
smg.addMapping({
  generated: { line: 1, column: 0 },
  source: 'input.js',
  original: { line: 1, column: 0 },
  name: 'foo',
});
```

#### SourceMapGenerator.prototype.setSourceContent(sourceFile, sourceContent)

```typescript
const smg = new SourceMapGenerator();
smg.setSourceContent('input.js', 'foobar');
```

#### SourceMapGenerator.prototype.toJSON()

```typescript
const smg = new SourceMapGenerator();
smg.toJSON(); // { version: 3, names: [], sources: [], mappings: '' }
```

#### SourceMapGenerator.prototype.toDecodedMap()

```typescript
const smg = new SourceMapGenerator();
smg.toDecodedMap(); // { version: 3, names: [], sources: [], mappings: [] }
```

[trace-mapping]: https://github.com/jridgewell/trace-mapping/
[gen-mapping]: https://github.com/jridgewell/gen-mapping/


---

# @jridgewell/sourcemap-codec

Encode/decode the `mappings` property of a [sourcemap](https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k/edit).


## Why?

Sourcemaps are difficult to generate and manipulate, because the `mappings` property – the part that actually links the generated code back to the original source – is encoded using an obscure method called [Variable-length quantity](https://en.wikipedia.org/wiki/Variable-length_quantity). On top of that, each segment in the mapping contains offsets rather than absolute indices, which means that you can't look at a segment in isolation – you have to understand the whole sourcemap.

This package makes the process slightly easier.


## Installation

```bash
npm install @jridgewell/sourcemap-codec
```


## Usage

```js
import { encode, decode } from '@jridgewell/sourcemap-codec';

var decoded = decode( ';EAEEA,EAAE,EAAC,CAAE;ECQY,UACC' );

assert.deepEqual( decoded, [
	// the first line (of the generated code) has no mappings,
	// as shown by the starting semi-colon (which separates lines)
	[],

	// the second line contains four (comma-separated) segments
	[
		// segments are encoded as you'd expect:
		// [ generatedCodeColumn, sourceIndex, sourceCodeLine, sourceCodeColumn, nameIndex ]

		// i.e. the first segment begins at column 2, and maps back to the second column
		// of the second line (both zero-based) of the 0th source, and uses the 0th
		// name in the `map.names` array
		[ 2, 0, 2, 2, 0 ],

		// the remaining segments are 4-length rather than 5-length,
		// because they don't map a name
		[ 4, 0, 2, 4 ],
		[ 6, 0, 2, 5 ],
		[ 7, 0, 2, 7 ]
	],

	// the final line contains two segments
	[
		[ 2, 1, 10, 19 ],
		[ 12, 1, 11, 20 ]
	]
]);

var encoded = encode( decoded );
assert.equal( encoded, ';EAEEA,EAAE,EAAC,CAAE;ECQY,UACC' );
```

## Benchmarks

```
node v18.0.0

amp.js.map - 45120 segments

Decode Memory Usage:
@jridgewell/sourcemap-codec       5479160 bytes
sourcemap-codec                   5659336 bytes
source-map-0.6.1                 17144440 bytes
source-map-0.8.0                  6867424 bytes
Smallest memory usage is @jridgewell/sourcemap-codec

Decode speed:
decode: @jridgewell/sourcemap-codec x 502 ops/sec ±1.03% (90 runs sampled)
decode: sourcemap-codec x 445 ops/sec ±0.97% (92 runs sampled)
decode: source-map-0.6.1 x 36.01 ops/sec ±1.64% (49 runs sampled)
decode: source-map-0.8.0 x 367 ops/sec ±0.04% (95 runs sampled)
Fastest is decode: @jridgewell/sourcemap-codec

Encode Memory Usage:
@jridgewell/sourcemap-codec       1261620 bytes
sourcemap-codec                   9119248 bytes
source-map-0.6.1                  8968560 bytes
source-map-0.8.0                  8952952 bytes
Smallest memory usage is @jridgewell/sourcemap-codec

Encode speed:
encode: @jridgewell/sourcemap-codec x 738 ops/sec ±0.42% (98 runs sampled)
encode: sourcemap-codec x 238 ops/sec ±0.73% (88 runs sampled)
encode: source-map-0.6.1 x 162 ops/sec ±0.43% (84 runs sampled)
encode: source-map-0.8.0 x 191 ops/sec ±0.34% (90 runs sampled)
Fastest is encode: @jridgewell/sourcemap-codec


***


babel.min.js.map - 347793 segments

Decode Memory Usage:
@jridgewell/sourcemap-codec      35338184 bytes
sourcemap-codec                  35922736 bytes
source-map-0.6.1                 62366360 bytes
source-map-0.8.0                 44337416 bytes
Smallest memory usage is @jridgewell/sourcemap-codec

Decode speed:
decode: @jridgewell/sourcemap-codec x 40.35 ops/sec ±4.47% (54 runs sampled)
decode: sourcemap-codec x 36.76 ops/sec ±3.67% (51 runs sampled)
decode: source-map-0.6.1 x 4.44 ops/sec ±2.15% (16 runs sampled)
decode: source-map-0.8.0 x 59.35 ops/sec ±0.05% (78 runs sampled)
Fastest is decode: source-map-0.8.0

Encode Memory Usage:
@jridgewell/sourcemap-codec       7212604 bytes
sourcemap-codec                  21421456 bytes
source-map-0.6.1                 25286888 bytes
source-map-0.8.0                 25498744 bytes
Smallest memory usage is @jridgewell/sourcemap-codec

Encode speed:
encode: @jridgewell/sourcemap-codec x 112 ops/sec ±0.13% (84 runs sampled)
encode: sourcemap-codec x 30.23 ops/sec ±2.76% (53 runs sampled)
encode: source-map-0.6.1 x 19.43 ops/sec ±3.70% (37 runs sampled)
encode: source-map-0.8.0 x 19.40 ops/sec ±3.26% (37 runs sampled)
Fastest is encode: @jridgewell/sourcemap-codec


***


preact.js.map - 1992 segments

Decode Memory Usage:
@jridgewell/sourcemap-codec        500272 bytes
sourcemap-codec                    516864 bytes
source-map-0.6.1                  1596672 bytes
source-map-0.8.0                   517272 bytes
Smallest memory usage is @jridgewell/sourcemap-codec

Decode speed:
decode: @jridgewell/sourcemap-codec x 16,137 ops/sec ±0.17% (99 runs sampled)
decode: sourcemap-codec x 12,139 ops/sec ±0.13% (99 runs sampled)
decode: source-map-0.6.1 x 1,264 ops/sec ±0.12% (100 runs sampled)
decode: source-map-0.8.0 x 9,894 ops/sec ±0.08% (101 runs sampled)
Fastest is decode: @jridgewell/sourcemap-codec

Encode Memory Usage:
@jridgewell/sourcemap-codec        321026 bytes
sourcemap-codec                    830832 bytes
source-map-0.6.1                   586608 bytes
source-map-0.8.0                   586680 bytes
Smallest memory usage is @jridgewell/sourcemap-codec

Encode speed:
encode: @jridgewell/sourcemap-codec x 19,876 ops/sec ±0.78% (95 runs sampled)
encode: sourcemap-codec x 6,983 ops/sec ±0.15% (100 runs sampled)
encode: source-map-0.6.1 x 5,070 ops/sec ±0.12% (102 runs sampled)
encode: source-map-0.8.0 x 5,641 ops/sec ±0.17% (100 runs sampled)
Fastest is encode: @jridgewell/sourcemap-codec


***


react.js.map - 5726 segments

Decode Memory Usage:
@jridgewell/sourcemap-codec        734848 bytes
sourcemap-codec                    954200 bytes
source-map-0.6.1                  2276432 bytes
source-map-0.8.0                   955488 bytes
Smallest memory usage is @jridgewell/sourcemap-codec

Decode speed:
decode: @jridgewell/sourcemap-codec x 5,723 ops/sec ±0.12% (98 runs sampled)
decode: sourcemap-codec x 4,555 ops/sec ±0.09% (101 runs sampled)
decode: source-map-0.6.1 x 437 ops/sec ±0.11% (93 runs sampled)
decode: source-map-0.8.0 x 3,441 ops/sec ±0.15% (100 runs sampled)
Fastest is decode: @jridgewell/sourcemap-codec

Encode Memory Usage:
@jridgewell/sourcemap-codec        638672 bytes
sourcemap-codec                   1109840 bytes
source-map-0.6.1                  1321224 bytes
source-map-0.8.0                  1324448 bytes
Smallest memory usage is @jridgewell/sourcemap-codec

Encode speed:
encode: @jridgewell/sourcemap-codec x 6,801 ops/sec ±0.48% (98 runs sampled)
encode: sourcemap-codec x 2,533 ops/sec ±0.13% (101 runs sampled)
encode: source-map-0.6.1 x 2,248 ops/sec ±0.08% (100 runs sampled)
encode: source-map-0.8.0 x 2,303 ops/sec ±0.15% (100 runs sampled)
Fastest is encode: @jridgewell/sourcemap-codec
```

# License

MIT


---

# @jridgewell/trace-mapping

> Trace the original position through a source map

`trace-mapping` allows you to take the line and column of an output file and trace it to the
original location in the source file through a source map.

You may already be familiar with the [`source-map`][source-map] package's `SourceMapConsumer`. This
provides the same `originalPositionFor` and `generatedPositionFor` API, without requiring WASM.

## Installation

```sh
npm install @jridgewell/trace-mapping
```

## Usage

```typescript
import {
  TraceMap,
  originalPositionFor,
  generatedPositionFor,
  sourceContentFor,
  isIgnored,
} from '@jridgewell/trace-mapping';

const tracer = new TraceMap({
  version: 3,
  sources: ['input.js'],
  sourcesContent: ['content of input.js'],
  names: ['foo'],
  mappings: 'KAyCIA',
  ignoreList: [],
});

// Lines start at line 1, columns at column 0.
const traced = originalPositionFor(tracer, { line: 1, column: 5 });
assert.deepEqual(traced, {
  source: 'input.js',
  line: 42,
  column: 4,
  name: 'foo',
});

const content = sourceContentFor(tracer, traced.source);
assert.strictEqual(content, 'content for input.js');

const generated = generatedPositionFor(tracer, {
  source: 'input.js',
  line: 42,
  column: 4,
});
assert.deepEqual(generated, {
  line: 1,
  column: 5,
});

const ignored = isIgnored(tracer, 'input.js');
assert.equal(ignored, false);
```

We also provide a lower level API to get the actual segment that matches our line and column. Unlike
`originalPositionFor`, `traceSegment` uses a 0-base for `line`:

```typescript
import { traceSegment } from '@jridgewell/trace-mapping';

// line is 0-base.
const traced = traceSegment(tracer, /* line */ 0, /* column */ 5);

// Segments are [outputColumn, sourcesIndex, sourceLine, sourceColumn, namesIndex]
// Again, line is 0-base and so is sourceLine
assert.deepEqual(traced, [5, 0, 41, 4, 0]);
```

### SectionedSourceMaps

The sourcemap spec defines a special `sections` field that's designed to handle concatenation of
output code with associated sourcemaps. This type of sourcemap is rarely used (no major build tool
produces it), but if you are hand coding a concatenation you may need it. We provide an `AnyMap`
helper that can receive either a regular sourcemap or a `SectionedSourceMap` and returns a
`TraceMap` instance:

```typescript
import { AnyMap } from '@jridgewell/trace-mapping';
const fooOutput = 'foo';
const barOutput = 'bar';
const output = [fooOutput, barOutput].join('\n');

const sectioned = new AnyMap({
  version: 3,
  sections: [
    {
      // 0-base line and column
      offset: { line: 0, column: 0 },
      // fooOutput's sourcemap
      map: {
        version: 3,
        sources: ['foo.js'],
        names: ['foo'],
        mappings: 'AAAAA',
      },
    },
    {
      // barOutput's sourcemap will not affect the first line, only the second
      offset: { line: 1, column: 0 },
      map: {
        version: 3,
        sources: ['bar.js'],
        names: ['bar'],
        mappings: 'AAAAA',
      },
    },
  ],
});

const traced = originalPositionFor(sectioned, {
  line: 2,
  column: 0,
});

assert.deepEqual(traced, {
  source: 'bar.js',
  line: 1,
  column: 0,
  name: 'bar',
});
```

## Benchmarks

```
node v18.0.0

amp.js.map - 45120 segments

Memory Usage:
trace-mapping decoded         562400 bytes
trace-mapping encoded        5706544 bytes
source-map-js               10717664 bytes
source-map-0.6.1            17446384 bytes
source-map-0.8.0             9701757 bytes
Smallest memory usage is trace-mapping decoded

Init speed:
trace-mapping:    decoded JSON input x 180 ops/sec ±0.34% (85 runs sampled)
trace-mapping:    encoded JSON input x 364 ops/sec ±1.77% (89 runs sampled)
trace-mapping:    decoded Object input x 3,116 ops/sec ±0.50% (96 runs sampled)
trace-mapping:    encoded Object input x 410 ops/sec ±2.62% (85 runs sampled)
source-map-js:    encoded Object input x 84.23 ops/sec ±0.91% (73 runs sampled)
source-map-0.6.1: encoded Object input x 37.21 ops/sec ±2.08% (51 runs sampled)
Fastest is trace-mapping:    decoded Object input

Trace speed:
trace-mapping:    decoded originalPositionFor x 3,952,212 ops/sec ±0.17% (98 runs sampled)
trace-mapping:    encoded originalPositionFor x 3,487,468 ops/sec ±1.58% (90 runs sampled)
source-map-js:    encoded originalPositionFor x 827,730 ops/sec ±0.78% (97 runs sampled)
source-map-0.6.1: encoded originalPositionFor x 748,991 ops/sec ±0.53% (94 runs sampled)
source-map-0.8.0: encoded originalPositionFor x 2,532,894 ops/sec ±0.57% (95 runs sampled)
Fastest is trace-mapping:    decoded originalPositionFor


***


babel.min.js.map - 347793 segments

Memory Usage:
trace-mapping decoded          89832 bytes
trace-mapping encoded       35474640 bytes
source-map-js               51257176 bytes
source-map-0.6.1            63515664 bytes
source-map-0.8.0            42933752 bytes
Smallest memory usage is trace-mapping decoded

Init speed:
trace-mapping:    decoded JSON input x 15.41 ops/sec ±8.65% (34 runs sampled)
trace-mapping:    encoded JSON input x 28.20 ops/sec ±12.87% (42 runs sampled)
trace-mapping:    decoded Object input x 964 ops/sec ±0.36% (99 runs sampled)
trace-mapping:    encoded Object input x 31.77 ops/sec ±13.79% (45 runs sampled)
source-map-js:    encoded Object input x 6.45 ops/sec ±5.16% (21 runs sampled)
source-map-0.6.1: encoded Object input x 4.07 ops/sec ±5.24% (15 runs sampled)
Fastest is trace-mapping:    decoded Object input

Trace speed:
trace-mapping:    decoded originalPositionFor x 7,183,038 ops/sec ±0.58% (95 runs sampled)
trace-mapping:    encoded originalPositionFor x 5,192,185 ops/sec ±0.41% (100 runs sampled)
source-map-js:    encoded originalPositionFor x 4,259,489 ops/sec ±0.79% (94 runs sampled)
source-map-0.6.1: encoded originalPositionFor x 3,742,629 ops/sec ±0.71% (95 runs sampled)
source-map-0.8.0: encoded originalPositionFor x 6,270,211 ops/sec ±0.64% (94 runs sampled)
Fastest is trace-mapping:    decoded originalPositionFor


***


preact.js.map - 1992 segments

Memory Usage:
trace-mapping decoded          37128 bytes
trace-mapping encoded         247280 bytes
source-map-js                1143536 bytes
source-map-0.6.1             1290992 bytes
source-map-0.8.0               96544 bytes
Smallest memory usage is trace-mapping decoded

Init speed:
trace-mapping:    decoded JSON input x 3,483 ops/sec ±0.30% (98 runs sampled)
trace-mapping:    encoded JSON input x 6,092 ops/sec ±0.18% (97 runs sampled)
trace-mapping:    decoded Object input x 249,076 ops/sec ±0.24% (98 runs sampled)
trace-mapping:    encoded Object input x 14,555 ops/sec ±0.48% (100 runs sampled)
source-map-js:    encoded Object input x 2,447 ops/sec ±0.36% (99 runs sampled)
source-map-0.6.1: encoded Object input x 1,201 ops/sec ±0.57% (96 runs sampled)
Fastest is trace-mapping:    decoded Object input

Trace speed:
trace-mapping:    decoded originalPositionFor x 7,620,192 ops/sec ±0.09% (99 runs sampled)
trace-mapping:    encoded originalPositionFor x 6,872,554 ops/sec ±0.30% (97 runs sampled)
source-map-js:    encoded originalPositionFor x 2,489,570 ops/sec ±0.35% (94 runs sampled)
source-map-0.6.1: encoded originalPositionFor x 1,698,633 ops/sec ±0.28% (98 runs sampled)
source-map-0.8.0: encoded originalPositionFor x 4,015,644 ops/sec ±0.22% (98 runs sampled)
Fastest is trace-mapping:    decoded originalPositionFor


***


react.js.map - 5726 segments

Memory Usage:
trace-mapping decoded          16176 bytes
trace-mapping encoded         681552 bytes
source-map-js                2418352 bytes
source-map-0.6.1             2443672 bytes
source-map-0.8.0              111768 bytes
Smallest memory usage is trace-mapping decoded

Init speed:
trace-mapping:    decoded JSON input x 1,720 ops/sec ±0.34% (98 runs sampled)
trace-mapping:    encoded JSON input x 4,406 ops/sec ±0.35% (100 runs sampled)
trace-mapping:    decoded Object input x 92,122 ops/sec ±0.10% (99 runs sampled)
trace-mapping:    encoded Object input x 5,385 ops/sec ±0.37% (99 runs sampled)
source-map-js:    encoded Object input x 794 ops/sec ±0.40% (98 runs sampled)
source-map-0.6.1: encoded Object input x 416 ops/sec ±0.54% (91 runs sampled)
Fastest is trace-mapping:    decoded Object input

Trace speed:
trace-mapping:    decoded originalPositionFor x 32,759,519 ops/sec ±0.33% (100 runs sampled)
trace-mapping:    encoded originalPositionFor x 31,116,306 ops/sec ±0.33% (97 runs sampled)
source-map-js:    encoded originalPositionFor x 17,458,435 ops/sec ±0.44% (97 runs sampled)
source-map-0.6.1: encoded originalPositionFor x 12,687,097 ops/sec ±0.43% (95 runs sampled)
source-map-0.8.0: encoded originalPositionFor x 23,538,275 ops/sec ±0.38% (95 runs sampled)
Fastest is trace-mapping:    decoded originalPositionFor
```

[source-map]: https://www.npmjs.com/package/source-map


---

# @leichtgewicht/ip-codec

Small package to encode or decode IP addresses from buffers to strings.
Supports IPV4 and IPV6.

## Usage

The basics are straigthforward

```js
import { encode, decode, sizeOf, familyOf } from '@leichtgewicht/ip-codec'

const uint8Array = encode("127.0.0.1")
const str = decode(uint8Array)

try {
  switch sizeOf(str) {
    case 4: // IPv4
    case 16: // IPv6
  }
  switch familyOf(str) {
    case: 1: // IPv4
    case: 2: // IPv6
  }
} catch (err) {
  // Invalid IP
}
```

By default the library will work with Uint8Array's but you can bring your own buffer:

```js
const buf = Buffer.alloc(4)
encode('127.0.0.1', buf)
```

It is also possible to de-encode at a location inside a given buffer

```js
const buf = Buffer.alloc(10)
encode('127.0.0.1', buf, 4)
```

Allocation of a buffer may be difficult if you don't know what type the buffer:
you can pass in a generator to allocate it for you:

```js
encode('127.0.0.1', Buffer.alloc)
```

You can also de/encode ipv4 or ipv6 specifically:

```js
import { v4, v6 } from '@leichtgewicht/ip-codec'

v4.decode(v4.encode('127.0.0.1'))
v6.decode(v6.encode('::'))
```

## History

The code in this package was originally extracted from [node-ip](https://github.com/indutny/node-ip) and since improved.

Notable changes are the removal of the `Buffer` dependency and better support for detection of
formats and allocation of buffers.

## License

[MIT](./LICENSE)


---

# Source Map

[![Build Status](https://travis-ci.org/mozilla/source-map.png?branch=master)](https://travis-ci.org/mozilla/source-map)

[![Coverage Status](https://coveralls.io/repos/github/mozilla/source-map/badge.svg)](https://coveralls.io/github/mozilla/source-map)

[![NPM](https://nodei.co/npm/source-map.png?downloads=true&downloadRank=true)](https://www.npmjs.com/package/source-map)

This is a library to generate and consume the source map format
[described here][format].

[format]: https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k/edit

## Use with Node

    $ npm install source-map

## Use on the Web

    <script src="https://unpkg.com/source-map@0.7.3/dist/source-map.js"></script>
    <script>
        sourceMap.SourceMapConsumer.initialize({
            "lib/mappings.wasm": "https://unpkg.com/source-map@0.7.3/lib/mappings.wasm"
        });
    </script>

--------------------------------------------------------------------------------

<!-- `npm run toc` to regenerate the Table of Contents -->

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
## Table of Contents

- [Examples](#examples)
  - [Consuming a source map](#consuming-a-source-map)
  - [Generating a source map](#generating-a-source-map)
    - [With SourceNode (high level API)](#with-sourcenode-high-level-api)
    - [With SourceMapGenerator (low level API)](#with-sourcemapgenerator-low-level-api)
- [API](#api)
  - [SourceMapConsumer](#sourcemapconsumer)
    - [SourceMapConsumer.initialize(options)](#sourcemapconsumerinitializeoptions)
    - [new SourceMapConsumer(rawSourceMap)](#new-sourcemapconsumerrawsourcemap)
    - [SourceMapConsumer.with](#sourcemapconsumerwith)
    - [SourceMapConsumer.prototype.destroy()](#sourcemapconsumerprototypedestroy)
    - [SourceMapConsumer.prototype.computeColumnSpans()](#sourcemapconsumerprototypecomputecolumnspans)
    - [SourceMapConsumer.prototype.originalPositionFor(generatedPosition)](#sourcemapconsumerprototypeoriginalpositionforgeneratedposition)
    - [SourceMapConsumer.prototype.generatedPositionFor(originalPosition)](#sourcemapconsumerprototypegeneratedpositionfororiginalposition)
    - [SourceMapConsumer.prototype.allGeneratedPositionsFor(originalPosition)](#sourcemapconsumerprototypeallgeneratedpositionsfororiginalposition)
    - [SourceMapConsumer.prototype.hasContentsOfAllSources()](#sourcemapconsumerprototypehascontentsofallsources)
    - [SourceMapConsumer.prototype.sourceContentFor(source[, returnNullOnMissing])](#sourcemapconsumerprototypesourcecontentforsource-returnnullonmissing)
    - [SourceMapConsumer.prototype.eachMapping(callback, context, order)](#sourcemapconsumerprototypeeachmappingcallback-context-order)
  - [SourceMapGenerator](#sourcemapgenerator)
    - [new SourceMapGenerator([startOfSourceMap])](#new-sourcemapgeneratorstartofsourcemap)
    - [SourceMapGenerator.fromSourceMap(sourceMapConsumer)](#sourcemapgeneratorfromsourcemapsourcemapconsumer)
    - [SourceMapGenerator.prototype.addMapping(mapping)](#sourcemapgeneratorprototypeaddmappingmapping)
    - [SourceMapGenerator.prototype.setSourceContent(sourceFile, sourceContent)](#sourcemapgeneratorprototypesetsourcecontentsourcefile-sourcecontent)
    - [SourceMapGenerator.prototype.applySourceMap(sourceMapConsumer[, sourceFile[, sourceMapPath]])](#sourcemapgeneratorprototypeapplysourcemapsourcemapconsumer-sourcefile-sourcemappath)
    - [SourceMapGenerator.prototype.toString()](#sourcemapgeneratorprototypetostring)
  - [SourceNode](#sourcenode)
    - [new SourceNode([line, column, source[, chunk[, name]]])](#new-sourcenodeline-column-source-chunk-name)
    - [SourceNode.fromStringWithSourceMap(code, sourceMapConsumer[, relativePath])](#sourcenodefromstringwithsourcemapcode-sourcemapconsumer-relativepath)
    - [SourceNode.prototype.add(chunk)](#sourcenodeprototypeaddchunk)
    - [SourceNode.prototype.prepend(chunk)](#sourcenodeprototypeprependchunk)
    - [SourceNode.prototype.setSourceContent(sourceFile, sourceContent)](#sourcenodeprototypesetsourcecontentsourcefile-sourcecontent)
    - [SourceNode.prototype.walk(fn)](#sourcenodeprototypewalkfn)
    - [SourceNode.prototype.walkSourceContents(fn)](#sourcenodeprototypewalksourcecontentsfn)
    - [SourceNode.prototype.join(sep)](#sourcenodeprototypejoinsep)
    - [SourceNode.prototype.replaceRight(pattern, replacement)](#sourcenodeprototypereplacerightpattern-replacement)
    - [SourceNode.prototype.toString()](#sourcenodeprototypetostring)
    - [SourceNode.prototype.toStringWithSourceMap([startOfSourceMap])](#sourcenodeprototypetostringwithsourcemapstartofsourcemap)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## Examples

### Consuming a source map

```js
const rawSourceMap = {
  version: 3,
  file: 'min.js',
  names: ['bar', 'baz', 'n'],
  sources: ['one.js', 'two.js'],
  sourceRoot: 'http://example.com/www/js/',
  mappings: 'CAAC,IAAI,IAAM,SAAUA,GAClB,OAAOC,IAAID;CCDb,IAAI,IAAM,SAAUE,GAClB,OAAOA'
};

const whatever = await SourceMapConsumer.with(rawSourceMap, null, consumer => {

  console.log(consumer.sources);
  // [ 'http://example.com/www/js/one.js',
  //   'http://example.com/www/js/two.js' ]

  console.log(consumer.originalPositionFor({
    line: 2,
    column: 28
  }));
  // { source: 'http://example.com/www/js/two.js',
  //   line: 2,
  //   column: 10,
  //   name: 'n' }

  console.log(consumer.generatedPositionFor({
    source: 'http://example.com/www/js/two.js',
    line: 2,
    column: 10
  }));
  // { line: 2, column: 28 }

  consumer.eachMapping(function (m) {
    // ...
  });

  return computeWhatever();
});
```

### Generating a source map

In depth guide:
[**Compiling to JavaScript, and Debugging with Source Maps**](https://hacks.mozilla.org/2013/05/compiling-to-javascript-and-debugging-with-source-maps/)

#### With SourceNode (high level API)

```js
function compile(ast) {
  switch (ast.type) {
  case 'BinaryExpression':
    return new SourceNode(
      ast.location.line,
      ast.location.column,
      ast.location.source,
      [compile(ast.left), " + ", compile(ast.right)]
    );
  case 'Literal':
    return new SourceNode(
      ast.location.line,
      ast.location.column,
      ast.location.source,
      String(ast.value)
    );
  // ...
  default:
    throw new Error("Bad AST");
  }
}

var ast = parse("40 + 2", "add.js");
console.log(compile(ast).toStringWithSourceMap({
  file: 'add.js'
}));
// { code: '40 + 2',
//   map: [object SourceMapGenerator] }
```

#### With SourceMapGenerator (low level API)

```js
var map = new SourceMapGenerator({
  file: "source-mapped.js"
});

map.addMapping({
  generated: {
    line: 10,
    column: 35
  },
  source: "foo.js",
  original: {
    line: 33,
    column: 2
  },
  name: "christopher"
});

console.log(map.toString());
// '{"version":3,"file":"source-mapped.js","sources":["foo.js"],"names":["christopher"],"mappings":";;;;;;;;;mCAgCEA"}'
```

## API

Get a reference to the module:

```js
// Node.js
var sourceMap = require('source-map');

// Browser builds
var sourceMap = window.sourceMap;

// Inside Firefox
const sourceMap = require("devtools/toolkit/sourcemap/source-map.js");
```

### SourceMapConsumer

A `SourceMapConsumer` instance represents a parsed source map which we can query
for information about the original file positions by giving it a file position
in the generated source.

#### SourceMapConsumer.initialize(options)

When using `SourceMapConsumer` outside of node.js, for example on the Web, it
needs to know from what URL to load `lib/mappings.wasm`. You must inform it by
calling `initialize` before constructing any `SourceMapConsumer`s.

The options object has the following properties:

* `"lib/mappings.wasm"`: A `String` containing the URL of the
  `lib/mappings.wasm` file, or an `ArrayBuffer` with the contents of `lib/mappings.wasm`.

```js
sourceMap.SourceMapConsumer.initialize({
  "lib/mappings.wasm": "https://example.com/source-map/lib/mappings.wasm"
});
```

#### new SourceMapConsumer(rawSourceMap)

The only parameter is the raw source map (either as a string which can be
`JSON.parse`'d, or an object). According to the spec, source maps have the
following attributes:

* `version`: Which version of the source map spec this map is following.

* `sources`: An array of URLs to the original source files.

* `names`: An array of identifiers which can be referenced by individual
  mappings.

* `sourceRoot`: Optional. The URL root from which all sources are relative.

* `sourcesContent`: Optional. An array of contents of the original source files.

* `mappings`: A string of base64 VLQs which contain the actual mappings.

* `file`: Optional. The generated filename this source map is associated with.

The promise of the constructed souce map consumer is returned.

When the `SourceMapConsumer` will no longer be used anymore, you must call its
`destroy` method.

```js
const consumer = await new sourceMap.SourceMapConsumer(rawSourceMapJsonData);
doStuffWith(consumer);
consumer.destroy();
```

Alternatively, you can use `SourceMapConsumer.with` to avoid needing to remember
to call `destroy`.

#### SourceMapConsumer.with

Construct a new `SourceMapConsumer` from `rawSourceMap` and `sourceMapUrl`
(see the `SourceMapConsumer` constructor for details. Then, invoke the `async
function f(SourceMapConsumer) -> T` with the newly constructed consumer, wait
for `f` to complete, call `destroy` on the consumer, and return `f`'s return
value.

You must not use the consumer after `f` completes!

By using `with`, you do not have to remember to manually call `destroy` on
the consumer, since it will be called automatically once `f` completes.

```js
const xSquared = await SourceMapConsumer.with(
  myRawSourceMap,
  null,
  async function (consumer) {
    // Use `consumer` inside here and don't worry about remembering
    // to call `destroy`.

    const x = await whatever(consumer);
    return x * x;
  }
);

// You may not use that `consumer` anymore out here; it has
// been destroyed. But you can use `xSquared`.
console.log(xSquared);
```

#### SourceMapConsumer.prototype.destroy()

Free this source map consumer's associated wasm data that is manually-managed.

```js
consumer.destroy();
```

Alternatively, you can use `SourceMapConsumer.with` to avoid needing to remember
to call `destroy`.

#### SourceMapConsumer.prototype.computeColumnSpans()

Compute the last column for each generated mapping. The last column is
inclusive.

```js
// Before:
consumer.allGeneratedPositionsFor({ line: 2, source: "foo.coffee" })
// [ { line: 2,
//     column: 1 },
//   { line: 2,
//     column: 10 },
//   { line: 2,
//     column: 20 } ]

consumer.computeColumnSpans();

// After:
consumer.allGeneratedPositionsFor({ line: 2, source: "foo.coffee" })
// [ { line: 2,
//     column: 1,
//     lastColumn: 9 },
//   { line: 2,
//     column: 10,
//     lastColumn: 19 },
//   { line: 2,
//     column: 20,
//     lastColumn: Infinity } ]
```

#### SourceMapConsumer.prototype.originalPositionFor(generatedPosition)

Returns the original source, line, and column information for the generated
source's line and column positions provided. The only argument is an object with
the following properties:

* `line`: The line number in the generated source.  Line numbers in
  this library are 1-based (note that the underlying source map
  specification uses 0-based line numbers -- this library handles the
  translation).

* `column`: The column number in the generated source.  Column numbers
  in this library are 0-based.

* `bias`: Either `SourceMapConsumer.GREATEST_LOWER_BOUND` or
  `SourceMapConsumer.LEAST_UPPER_BOUND`. Specifies whether to return the closest
  element that is smaller than or greater than the one we are searching for,
  respectively, if the exact element cannot be found.  Defaults to
  `SourceMapConsumer.GREATEST_LOWER_BOUND`.

and an object is returned with the following properties:

* `source`: The original source file, or null if this information is not
  available.

* `line`: The line number in the original source, or null if this information is
  not available.  The line number is 1-based.

* `column`: The column number in the original source, or null if this
  information is not available.  The column number is 0-based.

* `name`: The original identifier, or null if this information is not available.

```js
consumer.originalPositionFor({ line: 2, column: 10 })
// { source: 'foo.coffee',
//   line: 2,
//   column: 2,
//   name: null }

consumer.originalPositionFor({ line: 99999999999999999, column: 999999999999999 })
// { source: null,
//   line: null,
//   column: null,
//   name: null }
```

#### SourceMapConsumer.prototype.generatedPositionFor(originalPosition)

Returns the generated line and column information for the original source,
line, and column positions provided. The only argument is an object with
the following properties:

* `source`: The filename of the original source.

* `line`: The line number in the original source.  The line number is
  1-based.

* `column`: The column number in the original source.  The column
  number is 0-based.

and an object is returned with the following properties:

* `line`: The line number in the generated source, or null.  The line
  number is 1-based.

* `column`: The column number in the generated source, or null.  The
  column number is 0-based.

```js
consumer.generatedPositionFor({ source: "example.js", line: 2, column: 10 })
// { line: 1,
//   column: 56 }
```

#### SourceMapConsumer.prototype.allGeneratedPositionsFor(originalPosition)

Returns all generated line and column information for the original source, line,
and column provided. If no column is provided, returns all mappings
corresponding to a either the line we are searching for or the next closest line
that has any mappings. Otherwise, returns all mappings corresponding to the
given line and either the column we are searching for or the next closest column
that has any offsets.

The only argument is an object with the following properties:

* `source`: The filename of the original source.

* `line`: The line number in the original source.  The line number is
  1-based.

* `column`: Optional. The column number in the original source.  The
  column number is 0-based.

and an array of objects is returned, each with the following properties:

* `line`: The line number in the generated source, or null.  The line
  number is 1-based.

* `column`: The column number in the generated source, or null.  The
  column number is 0-based.

```js
consumer.allGeneratedpositionsfor({ line: 2, source: "foo.coffee" })
// [ { line: 2,
//     column: 1 },
//   { line: 2,
//     column: 10 },
//   { line: 2,
//     column: 20 } ]
```

#### SourceMapConsumer.prototype.hasContentsOfAllSources()

Return true if we have the embedded source content for every source listed in
the source map, false otherwise.

In other words, if this method returns `true`, then
`consumer.sourceContentFor(s)` will succeed for every source `s` in
`consumer.sources`.

```js
// ...
if (consumer.hasContentsOfAllSources()) {
  consumerReadyCallback(consumer);
} else {
  fetchSources(consumer, consumerReadyCallback);
}
// ...
```

#### SourceMapConsumer.prototype.sourceContentFor(source[, returnNullOnMissing])

Returns the original source content for the source provided. The only
argument is the URL of the original source file.

If the source content for the given source is not found, then an error is
thrown. Optionally, pass `true` as the second param to have `null` returned
instead.

```js
consumer.sources
// [ "my-cool-lib.clj" ]

consumer.sourceContentFor("my-cool-lib.clj")
// "..."

consumer.sourceContentFor("this is not in the source map");
// Error: "this is not in the source map" is not in the source map

consumer.sourceContentFor("this is not in the source map", true);
// null
```

#### SourceMapConsumer.prototype.eachMapping(callback, context, order)

Iterate over each mapping between an original source/line/column and a
generated line/column in this source map.

* `callback`: The function that is called with each mapping. Mappings have the
  form `{ source, generatedLine, generatedColumn, originalLine, originalColumn,
  name }`

* `context`: Optional. If specified, this object will be the value of `this`
  every time that `callback` is called.

* `order`: Either `SourceMapConsumer.GENERATED_ORDER` or
  `SourceMapConsumer.ORIGINAL_ORDER`. Specifies whether you want to iterate over
  the mappings sorted by the generated file's line/column order or the
  original's source/line/column order, respectively. Defaults to
  `SourceMapConsumer.GENERATED_ORDER`.

```js
consumer.eachMapping(function (m) { console.log(m); })
// ...
// { source: 'illmatic.js',
//   generatedLine: 1,
//   generatedColumn: 0,
//   originalLine: 1,
//   originalColumn: 0,
//   name: null }
// { source: 'illmatic.js',
//   generatedLine: 2,
//   generatedColumn: 0,
//   originalLine: 2,
//   originalColumn: 0,
//   name: null }
// ...
```
### SourceMapGenerator

An instance of the SourceMapGenerator represents a source map which is being
built incrementally.

#### new SourceMapGenerator([startOfSourceMap])

You may pass an object with the following properties:

* `file`: The filename of the generated source that this source map is
  associated with.

* `sourceRoot`: A root for all relative URLs in this source map.

* `skipValidation`: Optional. When `true`, disables validation of mappings as
  they are added. This can improve performance but should be used with
  discretion, as a last resort. Even then, one should avoid using this flag when
  running tests, if possible.

```js
var generator = new sourceMap.SourceMapGenerator({
  file: "my-generated-javascript-file.js",
  sourceRoot: "http://example.com/app/js/"
});
```

#### SourceMapGenerator.fromSourceMap(sourceMapConsumer)

Creates a new `SourceMapGenerator` from an existing `SourceMapConsumer` instance.

* `sourceMapConsumer` The SourceMap.

```js
var generator = sourceMap.SourceMapGenerator.fromSourceMap(consumer);
```

#### SourceMapGenerator.prototype.addMapping(mapping)

Add a single mapping from original source line and column to the generated
source's line and column for this source map being created. The mapping object
should have the following properties:

* `generated`: An object with the generated line and column positions.

* `original`: An object with the original line and column positions.

* `source`: The original source file (relative to the sourceRoot).

* `name`: An optional original token name for this mapping.

```js
generator.addMapping({
  source: "module-one.scm",
  original: { line: 128, column: 0 },
  generated: { line: 3, column: 456 }
})
```

#### SourceMapGenerator.prototype.setSourceContent(sourceFile, sourceContent)

Set the source content for an original source file.

* `sourceFile` the URL of the original source file.

* `sourceContent` the content of the source file.

```js
generator.setSourceContent("module-one.scm",
                           fs.readFileSync("path/to/module-one.scm"))
```

#### SourceMapGenerator.prototype.applySourceMap(sourceMapConsumer[, sourceFile[, sourceMapPath]])

Applies a SourceMap for a source file to the SourceMap.
Each mapping to the supplied source file is rewritten using the
supplied SourceMap. Note: The resolution for the resulting mappings
is the minimum of this map and the supplied map.

* `sourceMapConsumer`: The SourceMap to be applied.

* `sourceFile`: Optional. The filename of the source file.
  If omitted, sourceMapConsumer.file will be used, if it exists.
  Otherwise an error will be thrown.

* `sourceMapPath`: Optional. The dirname of the path to the SourceMap
  to be applied. If relative, it is relative to the SourceMap.

  This parameter is needed when the two SourceMaps aren't in the same
  directory, and the SourceMap to be applied contains relative source
  paths. If so, those relative source paths need to be rewritten
  relative to the SourceMap.

  If omitted, it is assumed that both SourceMaps are in the same directory,
  thus not needing any rewriting. (Supplying `'.'` has the same effect.)

#### SourceMapGenerator.prototype.toString()

Renders the source map being generated to a string.

```js
generator.toString()
// '{"version":3,"sources":["module-one.scm"],"names":[],"mappings":"...snip...","file":"my-generated-javascript-file.js","sourceRoot":"http://example.com/app/js/"}'
```

### SourceNode

SourceNodes provide a way to abstract over interpolating and/or concatenating
snippets of generated JavaScript source code, while maintaining the line and
column information associated between those snippets and the original source
code. This is useful as the final intermediate representation a compiler might
use before outputting the generated JS and source map.

#### new SourceNode([line, column, source[, chunk[, name]]])

* `line`: The original line number associated with this source node, or null if
  it isn't associated with an original line.  The line number is 1-based.

* `column`: The original column number associated with this source node, or null
  if it isn't associated with an original column.  The column number
  is 0-based.

* `source`: The original source's filename; null if no filename is provided.

* `chunk`: Optional. Is immediately passed to `SourceNode.prototype.add`, see
  below.

* `name`: Optional. The original identifier.

```js
var node = new SourceNode(1, 2, "a.cpp", [
  new SourceNode(3, 4, "b.cpp", "extern int status;\n"),
  new SourceNode(5, 6, "c.cpp", "std::string* make_string(size_t n);\n"),
  new SourceNode(7, 8, "d.cpp", "int main(int argc, char** argv) {}\n"),
]);
```

#### SourceNode.fromStringWithSourceMap(code, sourceMapConsumer[, relativePath])

Creates a SourceNode from generated code and a SourceMapConsumer.

* `code`: The generated code

* `sourceMapConsumer` The SourceMap for the generated code

* `relativePath` The optional path that relative sources in `sourceMapConsumer`
  should be relative to.

```js
const consumer = await new SourceMapConsumer(fs.readFileSync("path/to/my-file.js.map", "utf8"));
const node = SourceNode.fromStringWithSourceMap(fs.readFileSync("path/to/my-file.js"), consumer);
```

#### SourceNode.prototype.add(chunk)

Add a chunk of generated JS to this source node.

* `chunk`: A string snippet of generated JS code, another instance of
   `SourceNode`, or an array where each member is one of those things.

```js
node.add(" + ");
node.add(otherNode);
node.add([leftHandOperandNode, " + ", rightHandOperandNode]);
```

#### SourceNode.prototype.prepend(chunk)

Prepend a chunk of generated JS to this source node.

* `chunk`: A string snippet of generated JS code, another instance of
   `SourceNode`, or an array where each member is one of those things.

```js
node.prepend("/** Build Id: f783haef86324gf **/\n\n");
```

#### SourceNode.prototype.setSourceContent(sourceFile, sourceContent)

Set the source content for a source file. This will be added to the
`SourceMap` in the `sourcesContent` field.

* `sourceFile`: The filename of the source file

* `sourceContent`: The content of the source file

```js
node.setSourceContent("module-one.scm",
                      fs.readFileSync("path/to/module-one.scm"))
```

#### SourceNode.prototype.walk(fn)

Walk over the tree of JS snippets in this node and its children. The walking
function is called once for each snippet of JS and is passed that snippet and
the its original associated source's line/column location.

* `fn`: The traversal function.

```js
var node = new SourceNode(1, 2, "a.js", [
  new SourceNode(3, 4, "b.js", "uno"),
  "dos",
  [
    "tres",
    new SourceNode(5, 6, "c.js", "quatro")
  ]
]);

node.walk(function (code, loc) { console.log("WALK:", code, loc); })
// WALK: uno { source: 'b.js', line: 3, column: 4, name: null }
// WALK: dos { source: 'a.js', line: 1, column: 2, name: null }
// WALK: tres { source: 'a.js', line: 1, column: 2, name: null }
// WALK: quatro { source: 'c.js', line: 5, column: 6, name: null }
```

#### SourceNode.prototype.walkSourceContents(fn)

Walk over the tree of SourceNodes. The walking function is called for each
source file content and is passed the filename and source content.

* `fn`: The traversal function.

```js
var a = new SourceNode(1, 2, "a.js", "generated from a");
a.setSourceContent("a.js", "original a");
var b = new SourceNode(1, 2, "b.js", "generated from b");
b.setSourceContent("b.js", "original b");
var c = new SourceNode(1, 2, "c.js", "generated from c");
c.setSourceContent("c.js", "original c");

var node = new SourceNode(null, null, null, [a, b, c]);
node.walkSourceContents(function (source, contents) { console.log("WALK:", source, ":", contents); })
// WALK: a.js : original a
// WALK: b.js : original b
// WALK: c.js : original c
```

#### SourceNode.prototype.join(sep)

Like `Array.prototype.join` except for SourceNodes. Inserts the separator
between each of this source node's children.

* `sep`: The separator.

```js
var lhs = new SourceNode(1, 2, "a.rs", "my_copy");
var operand = new SourceNode(3, 4, "a.rs", "=");
var rhs = new SourceNode(5, 6, "a.rs", "orig.clone()");

var node = new SourceNode(null, null, null, [ lhs, operand, rhs ]);
var joinedNode = node.join(" ");
```

#### SourceNode.prototype.replaceRight(pattern, replacement)

Call `String.prototype.replace` on the very right-most source snippet. Useful
for trimming white space from the end of a source node, etc.

* `pattern`: The pattern to replace.

* `replacement`: The thing to replace the pattern with.

```js
// Trim trailing white space.
node.replaceRight(/\s*$/, "");
```

#### SourceNode.prototype.toString()

Return the string representation of this source node. Walks over the tree and
concatenates all the various snippets together to one string.

```js
var node = new SourceNode(1, 2, "a.js", [
  new SourceNode(3, 4, "b.js", "uno"),
  "dos",
  [
    "tres",
    new SourceNode(5, 6, "c.js", "quatro")
  ]
]);

node.toString()
// 'unodostresquatro'
```

#### SourceNode.prototype.toStringWithSourceMap([startOfSourceMap])

Returns the string representation of this tree of source nodes, plus a
SourceMapGenerator which contains all the mappings between the generated and
original sources.

The arguments are the same as those to `new SourceMapGenerator`.

```js
var node = new SourceNode(1, 2, "a.js", [
  new SourceNode(3, 4, "b.js", "uno"),
  "dos",
  [
    "tres",
    new SourceNode(5, 6, "c.js", "quatro")
  ]
]);

node.toStringWithSourceMap({ file: "my-output-file.js" })
// { code: 'unodostresquatro',
//   map: [object SourceMapGenerator] }
```


---

# `@mdx-js/mdx`

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

MDX compiler.

<!-- more -->

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`compile(file, options?)`](#compilefile-options)
  * [`compileSync(file, options?)`](#compilesyncfile-options)
  * [`createProcessor(options?)`](#createprocessoroptions)
  * [`evaluate(file, options)`](#evaluatefile-options)
  * [`evaluateSync(file, options)`](#evaluatesyncfile-options)
  * [`nodeTypes`](#nodetypes)
  * [`run(code, options)`](#runcode-options)
  * [`runSync(code, options)`](#runsynccode-options)
  * [`CompileOptions`](#compileoptions)
  * [`EvaluateOptions`](#evaluateoptions)
  * [`Fragment`](#fragment)
  * [`Jsx`](#jsx)
  * [`JsxDev`](#jsxdev)
  * [`ProcessorOptions`](#processoroptions)
  * [`RunOptions`](#runoptions)
  * [`UseMdxComponents`](#usemdxcomponents)
* [Types](#types)
* [Architecture](#architecture)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package is a compiler that turns MDX into JavaScript.
It can also evaluate MDX code.

## When should I use this?

This is the core compiler for turning MDX into JavaScript which gives you the
most control.
If you’re using a bundler (Rollup, esbuild, webpack), a site builder (Next.js),
or build system (Vite) which comes with a bundler, you’re better off using an
integration: see [§ Integrations][integrations].

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install @mdx-js/mdx
```

In Deno with [`esm.sh`][esmsh]:

```tsx
import {compile} from 'https://esm.sh/@mdx-js/mdx@3'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {compile} from 'https://esm.sh/@mdx-js/mdx@3?bundle'
</script>
```

## Use

Say we have an MDX document, `example.mdx`:

```mdx
export function Thing() {
  return <>World!</>
}

# Hello, <Thing />
```

…and some code in `example.js` to compile `example.mdx` to JavaScript:

```tsx
import fs from 'node:fs/promises'
import {compile} from '@mdx-js/mdx'

const compiled = await compile(await fs.readFile('example.mdx'))

console.log(String(compiled))
```

Yields roughly:

```tsx
import {Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs} from 'react/jsx-runtime'

export function Thing() {
  return _jsx(_Fragment, {children: 'World!'})
}

function _createMdxContent(props) {
  const _components = {h1: 'h1', ...props.components}
  return _jsxs(_components.h1, {children: ['Hello, ', _jsx(Thing, {})]})
}

export default function MDXContent(props = {}) {
  const {wrapper: MDXLayout} = props.components || {}
  return MDXLayout
    ? _jsx(MDXLayout, {...props, children: _jsx(_createMdxContent, {...props})})
    : _createMdxContent(props)
}
```

See [§ Using MDX][using-mdx] for more on how MDX work and how to use the result.

## API

This package exports the following identifiers:
[`compile`][api-compile],
[`compileSync`][api-compile-sync],
[`createProcessor`][api-create-processor],
[`evaluate`][api-evaluate],
[`evaluateSync`][api-evaluate-sync],
[`nodeTypes`][api-node-types],
[`run`][api-run], and
[`runSync`][api-run-sync].
There is no default export.

### `compile(file, options?)`

Compile MDX to JS.

###### Parameters

* `file` ([`Compatible` from `vfile`][vfile-compatible])
  — MDX document to parse
* `options` ([`CompileOptions`][api-compile-options], optional)
  — compile configuration

###### Returns

Promise to compiled file ([`Promise<VFile>`][vfile]).

###### Examples

The input value for `file` can be many different things.
You can pass a `string`, `Uint8Array` in UTF-8, [`VFile`][vfile], or anything
that can be given to `new VFile`.

```tsx
import {compile} from '@mdx-js/mdx'
import {VFile} from 'vfile'

await compile(':)')
await compile(Buffer.from(':-)'))
await compile({path: 'path/to/file.mdx', value: '🥳'})
await compile(new VFile({path: 'path/to/file.mdx', value: '🤭'}))
```

The output `VFile` can be used to access more than the generated code:

```tsx
import {compile} from '@mdx-js/mdx'
import remarkPresetLintConsistent from 'remark-preset-lint-consistent' // Lint rules to check for consistent markdown.
import {reporter} from 'vfile-reporter'

const file = await compile('*like this* or _like this_?', {remarkPlugins: [remarkPresetLintConsistent]})

console.error(reporter(file))
```

Yields:

```txt
  1:16-1:27  warning  Emphasis should use `*` as a marker  emphasis-marker  remark-lint

⚠ 1 warning
```

### `compileSync(file, options?)`

Synchronously compile MDX to JS.

When possible please use the async [`compile`][api-compile].

###### Parameters

* `file` ([`Compatible` from `vfile`][vfile-compatible])
  — MDX document to parse
* `options` ([`CompileOptions`][api-compile-options], optional)
  — compile configuration

###### Returns

Compiled file ([`VFile`][vfile]).

### `createProcessor(options?)`

Create a processor to compile markdown or MDX to JavaScript.

> **Note**: `format: 'detect'` is not allowed in `ProcessorOptions`.

###### Parameters

* `options` ([`ProcessorOptions`][api-processor-options], optional)
  — process configuration

###### Returns

Processor ([`Processor` from `unified`][unified-processor]).

### `evaluate(file, options)`

[Compile][api-compile] and [run][api-run] MDX.

When you trust your content, `evaluate` can work.
When possible, use [`compile`][api-compile], write to a file, and then run with
Node or use one of the [§ Integrations][integrations].

> ☢️ **Danger**: it’s called **evaluate** because it `eval`s JavaScript.

###### Parameters

* `file` ([`Compatible` from `vfile`][vfile-compatible])
  — MDX document to parse
* `options` ([`EvaluateOptions`][api-evaluate-options], **required**)
  — configuration

###### Returns

Promise to a module ([`Promise<MDXModule>` from
`mdx/types.js`][mdx-types-module]).

The result is an object with a `default` field set to the component;
anything else that was exported is available too.
For example, assuming the contents of `example.mdx` from [§ Use][use] was in
`file`, then:

```tsx
import {evaluate} from '@mdx-js/mdx'
import * as runtime from 'react/jsx-runtime'

console.log(await evaluate(file, runtime))
```

…yields:

```tsx
{Thing: [Function: Thing], default: [Function: MDXContent]}
```

###### Notes

Compiling (and running) MDX takes time.

If you are live-rendering a string of MDX that often changes using a virtual DOM
based framework (such as React), one performance improvement is to call the
`MDXContent` component yourself.
The reason is that the `evaluate` creates a new function each time, which cannot
be diffed:

```diff
 const {default: MDXContent} = await evaluate('…')

-<MDXContent {...props} />
+MDXContent(props)
```

### `evaluateSync(file, options)`

Compile and run MDX, synchronously.

When possible please use the async [`evaluate`][api-evaluate].

> ☢️ **Danger**: it’s called **evaluate** because it `eval`s JavaScript.

###### Parameters

* `file` ([`Compatible` from `vfile`][vfile-compatible])
  — MDX document to parse
* `options` ([`EvaluateOptions`][api-evaluate-options], **required**)
  — configuration

###### Returns

Module ([`MDXModule` from `mdx/types.js`][mdx-types-module]).

### `nodeTypes`

List of node types made by `mdast-util-mdx`, which have to be passed
through untouched from the mdast tree to the hast tree (`Array<string>`).

### `run(code, options)`

Run code compiled with `outputFormat: 'function-body'`.

> ☢️ **Danger**: this `eval`s JavaScript.

###### Parameters

* `code` ([`VFile`][vfile] or `string`)
  — JavaScript function body to run
* `options` ([`RunOptions`][api-run-options], **required**)
  — configuration

###### Returns

Promise to a module ([`Promise<MDXModule>` from
`mdx/types.js`][mdx-types-module]);
the result is an object with a `default` field set to the component;
anything else that was exported is available too.

###### Example

On the server:

```tsx
import {compile} from '@mdx-js/mdx'

const code = String(await compile('# hi', {outputFormat: 'function-body'}))
// To do: send `code` to the client somehow.
```

On the client:

```tsx
import {run} from '@mdx-js/mdx'
import * as runtime from 'react/jsx-runtime'

const code = '' // To do: get `code` from server somehow.

const {default: Content} = await run(code, {...runtime, baseUrl: import.meta.url})

console.log(Content)
```

…yields:

```tsx
[Function: MDXContent]
```

### `runSync(code, options)`

Run code, synchronously.

When possible please use the async [`run`][api-run].

> ☢️ **Danger**: this `eval`s JavaScript.

###### Parameters

* `code` ([`VFile`][vfile] or `string`)
  — JavaScript function body to run
* `options` ([`RunOptions`][api-run-options], **required**)
  — configuration

###### Returns

Module ([`MDXModule` from `mdx/types.js`][mdx-types-module]).

### `CompileOptions`

Configuration for `compile` (TypeScript type).

`CompileOptions` is the same as [`ProcessorOptions`][api-processor-options]
with the exception that the `format` option supports a `'detect'` value,
which is the default.
The `'detect'` format means to use `'md'` for files with an extension in
`mdExtensions` and `'mdx'` otherwise.

###### Type

```tsx
/**
 * Configuration for `compile`
 */
type CompileOptions = Omit<ProcessorOptions, 'format'> & {
  /**
   * Format of `file` (default: `'detect'`).
   */
  format?: 'detect' | 'md' | 'mdx' | null | undefined
}
```

### `EvaluateOptions`

Configuration for `evaluate` (TypeScript type).

`EvaluateOptions` is the same as [`CompileOptions`][api-compile-options],
except that the options `baseUrl`, `jsx`, `jsxImportSource`, `jsxRuntime`,
`outputFormat`, `pragma`, `pragmaFrag`, `pragmaImportSource`, and
`providerImportSource` are not allowed, and that
[`RunOptions`][api-run-options] are also used.

###### Type

```tsx
/**
 * Configuration for `evaluate`.
 */
type EvaluateOptions = Omit<
  CompileOptions,
  | 'baseUrl' // Note that this is also in `RunOptions`.
  | 'jsx'
  | 'jsxImportSource'
  | 'jsxRuntime'
  | 'outputFormat'
  | 'pragma'
  | 'pragmaFrag'
  | 'pragmaImportSource'
  | 'providerImportSource'
> &
  RunOptions
```

### `Fragment`

Represent the children, typically a symbol (TypeScript type).

###### Type

```ts
type Fragment = unknown
```

### `Jsx`

Create a production element (TypeScript type).

###### Parameters

* `type` (`unknown`)
  — element type: `Fragment` symbol, tag name (`string`), component
* `properties` (`Properties`)
  — element properties and `children`
* `key` (`string` or `undefined`)
  — key to use

###### Returns

Element from your framework (`JSX.Element`).

### `JsxDev`

Create a development element (TypeScript type).

###### Parameters

* `type` (`unknown`)
  — element type: `Fragment` symbol, tag name (`string`), component
* `properties` (`Properties`)
  — element properties and `children`
* `key` (`string` or `undefined`)
  — key to use
* `isStaticChildren` (`boolean`)
  — whether two or more children are passed (in an array), which is whether
  `jsxs` or `jsx` would be used
* `source` (`Source`)
  — info about source
* `self` (`unknown`)
  — context object (`this`)

### `ProcessorOptions`

Configuration for `createProcessor` (TypeScript type).

###### Fields

* `SourceMapGenerator` (`SourceMapGenerator` from [`source-map`][source-map],
  optional)
  — add a source map (object form) as the `map` field on the resulting file

  <details><summary>Expand example</summary>

  Assuming `example.mdx` from [§ Use][use] exists, then:

  ```tsx
  import fs from 'node:fs/promises'
  import {compile} from '@mdx-js/mdx'
  import {SourceMapGenerator} from 'source-map'

  const file = await compile(
    {path: 'example.mdx', value: await fs.readFile('example.mdx')},
    {SourceMapGenerator}
  )

  console.log(file.map)
  ```

  …yields:

  ```tsx
  {
    file: 'example.mdx',
    mappings: ';;aAAaA,QAAQ;YAAQ;;;;;;;;iBAE3B',
    names: ['Thing'],
    sources: ['example.mdx'],
    version: 3
  }
  ```

  </details>

* `baseUrl` (`URL` or `string`, optional, example: `import.meta.url`)
  — use this URL as `import.meta.url` and resolve `import` and
  `export … from` relative to it

  <details><summary>Expand example</summary>

  Say we have a module `example.js`:

  ```tsx
  import {compile} from '@mdx-js/mdx'

  const code = 'export {number} from "./data.js"\n\n# hi'
  const baseUrl = 'https://a.full/url' // Typically `import.meta.url`

  console.log(String(await compile(code, {baseUrl})))
  ```

  …now running `node example.js` yields:

  ```tsx
  import {jsx as _jsx} from 'react/jsx-runtime'
  export {number} from 'https://a.full/data.js'
  function _createMdxContent(props) { /* … */ }
  export default function MDXContent(props = {}) { /* … */ }
  ```

  </details>

* `development` (`boolean`, default: `false`)
  — whether to add extra info to error messages in generated code and use the
  development automatic JSX runtime (`Fragment` and `jsxDEV` from
  `/jsx-dev-runtime`);
  when using the webpack loader (`@mdx-js/loader`) or the Rollup integration
  (`@mdx-js/rollup`) through Vite, this is automatically inferred from how
  you configure those tools

  <details><summary>Expand example</summary>

  Say we had some MDX that references a component that can be passed or
  provided at runtime:

  ```mdx
  **Note**<NoteIcon />: some stuff.
  ```

  And a module to evaluate that:

  ```tsx
  import fs from 'node:fs/promises'
  import {evaluate} from '@mdx-js/mdx'
  import * as runtime from 'react/jsx-runtime'

  const path = 'example.mdx'
  const value = await fs.readFile(path)
  const MDXContent = (await evaluate({path, value}, {...runtime, baseUrl: import.meta.url})).default

  console.log(MDXContent({}))
  ```

  …running that would normally (production) yield:

  ```txt
  Error: Expected component `NoteIcon` to be defined: you likely forgot to import, pass, or provide it.
      at _missingMdxReference (eval at run (…/@mdx-js/mdx/lib/run.js:18:10), <anonymous>:27:9)
      at _createMdxContent (eval at run (…/@mdx-js/mdx/lib/run.js:18:10), <anonymous>:15:20)
      at MDXContent (eval at run (…/@mdx-js/mdx/lib/run.js:18:10), <anonymous>:9:9)
      at main (…/example.js:11:15)
  ```

  …but if we add `development: true` to our example:

  ```diff
  @@ -7,6 +7,6 @@
  import fs from 'node:fs/promises'
  -import * as runtime from 'react/jsx-runtime'
  +import * as runtime from 'react/jsx-dev-runtime'
  import {evaluate} from '@mdx-js/mdx'

  const path = 'example.mdx'
  const value = await fs.readFile(path)
  -const MDXContent = (await evaluate({path, value}, {...runtime, baseUrl: import.meta.url})).default
  +const MDXContent = (await evaluate({path, value}, {development: true, ...runtime, baseUrl: import.meta.url})).default

  console.log(MDXContent({}))
  ```

  …and we’d run it again, we’d get:

  ```txt
  Error: Expected component `NoteIcon` to be defined: you likely forgot to import, pass, or provide it.
  It’s referenced in your code at `1:9-1:21` in `example.mdx`
  provide it.
      at _missingMdxReference (eval at run (…/@mdx-js/mdx/lib/run.js:18:10), <anonymous>:27:9)
      at _createMdxContent (eval at run (…/@mdx-js/mdx/lib/run.js:18:10), <anonymous>:15:20)
      at MDXContent (eval at run (…/@mdx-js/mdx/lib/run.js:18:10), <anonymous>:9:9)
      at main (…/example.js:11:15)
  ```

  </details>

* `elementAttributeNameCase` (`'html'` or `'react`, default: `'react'`)
  — casing to use for attribute names;
  HTML casing is for example `class`, `stroke-linecap`, `xml:lang`;
  React casing is for example `className`, `strokeLinecap`, `xmlLang`;
  for JSX components written in MDX, the author has to be aware of which
  framework they use and write code accordingly;
  for AST nodes generated by this project, this option configures it

* `format` (`'md'` or `'mdx'`, default: `'mdx'`)
  — format of the file;
  `'md'` means treat as markdown and `'mdx'` means treat as [MDX][mdx-syntax]

  <details><summary>Expand example</summary>

  ```tsx
  compile('…') // Seen as MDX.
  compile('…', {format: 'mdx'}) // Seen as MDX.
  compile('…', {format: 'md'}) // Seen as markdown.
  ```

  </details>

* `jsx` (`boolean`, default: `false`)
  — whether to keep JSX;
  the default is to compile JSX away so that the resulting file is
  immediately runnable.

  <details><summary>Expand example</summary>

  If `file` is the contents of `example.mdx` from [§ Use][use], then:

  ```tsx
  compile(file, {jsx: true})
  ```

  …yields this difference:

  ```diff
  -import {Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs} from 'react/jsx-runtime'
  +/*@jsxRuntime automatic*/
  +/*@jsxImportSource react*/

  export function Thing() {
  -  return _jsx(_Fragment, {children: 'World'})
  +  return <>World!</>
  }

  function _createMdxContent(props) {
    const _components = {
      h1: 'h1',
      ...props.components
    }
  -  return _jsxs(_components.h1, {children: ['Hello ', _jsx(Thing, {})]})
  +  return <_components.h1>{"Hello "}<Thing /></_components.h1>
  }

  export default function MDXContent(props = {}) {
    const {wrapper: MDXLayout} = props.components || {}
    return MDXLayout
  -    ? _jsx(MDXLayout, {
  -        ...props,
  -        children: _jsx(_createMdxContent, props)
  -      })
  +    ? <MDXLayout {...props}><_createMdxContent {...props} /></MDXLayout>
      : _createMdxContent(props)
  }
  }
  ```

  </details>

* `jsxImportSource` (`string`, default: `'react'`)
  — place to import automatic JSX runtimes from;
  when in the `automatic` runtime, this is used to define an import for
  `Fragment`, `jsx`, `jsxDEV`, and `jsxs`

  <details><summary>Expand example</summary>

  If `file` is the contents of `example.mdx` from [§ Use][use], then:

  ```tsx
  compile(file, {jsxImportSource: 'preact'})
  ```

  …yields this difference:

  ```diff
  -import {Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs} from 'react/jsx-runtime'
  +import {Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from 'preact/jsx-runtime'
  ```

  </details>

* `jsxRuntime` (`'automatic'` or `'classic'`, default: `'automatic'`)
  — JSX runtime to use;
  the automatic runtime compiles to `import _jsx from
  '$importSource/jsx-runtime'\n_jsx('p')`;
  the classic runtime compiles to calls such as `h('p')`

  > 👉 **Note**: support for the classic runtime is deprecated and will
  > likely be removed in the next major version.

  <details><summary>Expand example</summary>

  If `file` is the contents of `example.mdx` from [§ Use][use], then:

  ```tsx
  compile(file, {jsxRuntime: 'classic'})
  ```

  …yields this difference:

  ```diff
  -import {Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs} from 'react/jsx-runtime'
  +import React from 'react'

  export function Thing() {
  -  return _jsx(_Fragment, {children: 'World'})
  +  return React.createElement(React.Fragment, null, 'World!')
  }
  …
  ```

  </details>

* `outputFormat` (`'function-body'` or `'program'`, default: `'program'`)
  — output format to generate;
  in most cases `'program'` should be used, it results in a whole program;
  internally [`evaluate`][api-evaluate] uses `'function-body'` to compile to
  code that can be passed to [`run`][api-run];
  in some cases, you might want what `evaluate` does in separate steps, such
  as when compiling on the server and running on the client.

  <details><summary>Expand example</summary>

  With a module `example.js`:

  ```tsx
  import {compile} from '@mdx-js/mdx'

  const code = 'export const no = 3.14\n\n# hi {no}'

  console.log(String(await compile(code, {outputFormat: 'program'}))) // Default.
  console.log(String(await compile(code, {outputFormat: 'function-body'})))
  ```

  …yields:

  ```tsx
  import {jsx as _jsx, jsxs as _jsxs} from 'react/jsx-runtime'
  export const no = 3.14
  function _createMdxContent(props) { /* … */ }
  export default function MDXContent(props = {}) { /* … */ }
  ```

  ```tsx
  'use strict'
  const {Fragment: _Fragment, jsx: _jsx} = arguments[0]
  const no = 3.14
  function _createMdxContent(props) { /* … */ }
  function MDXContent(props = {}) { /* … */ }
  return {no, default: MDXContent}
  ```

  The `'program'` format will use import statements to import the runtime (and
  optionally provider) and use an export statement to yield the `MDXContent`
  component.

  The `'function-body'` format will get the runtime (and optionally provider)
  from `arguments[0]`, rewrite export statements, and use a return statement to
  yield what was exported.

  </details>

* `mdExtensions` (`Array<string>`, default: `['.md', '.markdown', '.mdown',
  '.mkdn', '.mkd', '.mdwn', '.mkdown', '.ron']`)
  — list of markdown extensions, with dot
  affects [§ Integrations][integrations]

* `mdxExtensions` (`Array<string>`, default: `['.mdx']`)
  — list of MDX extensions, with dot;
  affects [§ Integrations][integrations]

* `pragma` (`string`, default: `'React.createElement'`)
  — pragma for JSX, used in the classic runtime as an identifier for function
  calls: `<x />` to `React.createElement('x')`;
  when changing this, you should also define `pragmaFrag` and
  `pragmaImportSource` too

  > 👉 **Note**: support for the classic runtime is deprecated and will
  > likely be removed in the next major version.

  <details><summary>Expand example</summary>

  If `file` is the contents of `example.mdx` from [§ Use][use], then:

  ```tsx
  compile(file, {
    jsxRuntime: 'classic',
    pragma: 'preact.createElement',
    pragmaFrag: 'preact.Fragment',
    pragmaImportSource: 'preact/compat'
  })
  ```

  …yields this difference:

  ```diff
  -import React from 'react'
  +import preact from 'preact/compat'

  export function Thing() {
  -  return React.createElement(React.Fragment, null, 'World!')
  +  return preact.createElement(preact.Fragment, null, 'World!')
  }
  …
  ```

  </details>

* `pragmaFrag` (`string`, default: `'React.Fragment'`)
  — pragma for fragment symbol, used in the classic runtime as an identifier
  for unnamed calls: `<>` to `React.createElement(React.Fragment)`;
  when changing this, you should also define `pragma` and `pragmaImportSource`
  too

  > 👉 **Note**: support for the classic runtime is deprecated and will
  > likely be removed in the next major version.

* `pragmaImportSource` (`string`, default: `'react'`)
  — where to import the identifier of `pragma` from, used in the classic
  runtime;
  to illustrate, when `pragma` is `'a.b'` and `pragmaImportSource` is `'c'`
  the following will be generated: `import a from 'c'` and things such as
  `a.b('h1', {})`;
  when changing this, you should also define `pragma` and `pragmaFrag` too

  > 👉 **Note**: support for the classic runtime is deprecated and will
  > likely be removed in the next major version.

* `providerImportSource` (`string`, optional, example: `'@mdx-js/react'`)
  — place to import a provider from;
  normally it’s used for runtimes that support context (React, Preact), but
  it can be used to inject components into the compiled code;
  the module must export and identifier `useMDXComponents` which is called
  without arguments to get an object of components (see
  [`UseMdxComponents`][api-use-mdx-components])

  <details><summary>Expand example</summary>

  If `file` is the contents of `example.mdx` from [§ Use][use], then:

  ```tsx
  compile(file, {providerImportSource: '@mdx-js/react'})
  ```

  …yields this difference:

  ```diff
  import {Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs} from 'react/jsx-runtime'
  +import {useMDXComponents as _provideComponents} from '@mdx-js/react'

  export function Thing() {
    return _jsx(_Fragment, {children: 'World'})
  }

  function _createMdxContent(props) {
    const _components = {
      h1: 'h1',
  +    ..._provideComponents(),
      ...props.components
    }
    return _jsxs(_components.h1, {children: ['Hello ', _jsx(Thing, {})]})
  }

  export default function MDXContent(props = {}) {
  -  const {wrapper: MDXLayout} = props.components || {}
  +  const {wrapper: MDXLayout} = {
  +    ..._provideComponents(),
  +    ...props.components
  +  }

    return MDXLayout
      ? _jsx(MDXLayout, {...props, children: _jsx(_createMdxContent, {})})
      : _createMdxContent()
  ```

  </details>

* `recmaPlugins` ([`PluggableList` from `unified`][unified-pluggable-list],
  optional)
  — list of recma plugins;
  this is a new ecosystem, currently in beta, to transform [esast][] trees
  (JavaScript)

  <details><summary>Expand example</summary>

  ```tsx
  import recmaMdxIsMdxComponent from 'recma-mdx-is-mdx-component'

  await compile(file, {recmaPlugins: [recmaMdxIsMdxComponent]})
  ```

  </details>

* `rehypePlugins` ([`PluggableList` from `unified`][unified-pluggable-list],
  optional)
  — list of [rehype plugins][rehype-plugins]

  <details><summary>Expand example</summary>

  ```tsx
  import rehypeKatex from 'rehype-katex' // Render math with KaTeX.
  import remarkMath from 'remark-math' // Support math like `$so$`.

  await compile(file, {rehypePlugins: [rehypeKatex], remarkPlugins: [remarkMath]})

  await compile(file, {
    // A plugin with options:
    rehypePlugins: [[rehypeKatex, {strict: true, throwOnError: true}]],
    remarkPlugins: [remarkMath]
  })
  ```

  </details>

* `remarkPlugins` ([`PluggableList` from `unified`][unified-pluggable-list],
  optional)
  — list of [remark plugins][remark-plugins]

  <details><summary>Expand example</summary>

  ```tsx
  import remarkFrontmatter from 'remark-frontmatter' // YAML and such.
  import remarkGfm from 'remark-gfm' // Tables, footnotes, strikethrough, task lists, literal URLs.

  await compile(file, {remarkPlugins: [remarkGfm]}) // One plugin.
  await compile(file, {remarkPlugins: [[remarkFrontmatter, 'toml']]}) // A plugin with options.
  await compile(file, {remarkPlugins: [remarkGfm, remarkFrontmatter]}) // Two plugins.
  await compile(file, {remarkPlugins: [[remarkGfm, {singleTilde: false}], remarkFrontmatter]}) // Two plugins, first w/ options.
  ```

  </details>

* `remarkRehypeOptions` ([`Options` from
  `remark-rehype`][remark-rehype-options], optional)
  — options to pass through to `remark-rehype`;
  the option `allowDangerousHtml` will always be set to `true` and the MDX
  nodes (see [`nodeTypes`][api-node-types]) are passed through;
  In particular, you might want to pass configuration for footnotes if your
  content is not in English

  <details><summary>Expand example</summary>

  ```tsx
  compile({value: '…'}, {remarkRehypeOptions: {clobberPrefix: 'comment-1'}})
  ```

  </details>

* `stylePropertyNameCase` (`'css'` or `'dom`, default: `'dom'`)
  — casing to use for property names in `style` objects;
  CSS casing is for example `background-color` and `-webkit-line-clamp`;
  DOM casing is for example `backgroundColor` and `WebkitLineClamp`;
  for JSX components written in MDX, the author has to be aware of which
  framework they use and write code accordingly;
  for AST nodes generated by this project, this option configures it

* `tableCellAlignToStyle` (`boolean`, default: `true`)
  — turn obsolete `align` properties on `td` and `th` into CSS `style`
  properties

### `RunOptions`

Configuration to run compiled code (TypeScript type).

`Fragment`, `jsx`, and `jsxs` are used when the code is compiled in production
mode (`development: false`).
`Fragment` and `jsxDEV` are used when compiled in development mode
(`development: true`).
`useMDXComponents` is used when the code is compiled with
`providerImportSource: '#'` (the exact value of this compile option doesn’t
matter).

###### Fields

* `Fragment` ([`Fragment`][api-fragment], **required**)
  — symbol to use for fragments
* `baseUrl` (`URL` or `string`, optional, example: `import.meta.url`)
  — use this URL as `import.meta.url` and resolve `import` and
  `export … from` relative to it;
  this option can also be given at compile time in `CompileOptions`;
  you should pass this (likely at runtime), as you might get runtime errors
  when using `import.meta.url` / `import` / `export … from ` otherwise
* `jsx` ([`Jsx`][api-jsx], optional)
  — function to generate an element with static children in production mode
* `jsxDEV` ([`JsxDev`][api-jsx-dev], optional)
  — function to generate an element in development mode
* `jsxs` ([`Jsx`][api-jsx], optional)
  — function to generate an element with dynamic children in production mode
* `useMDXComponents` ([`UseMdxComponents`][api-use-mdx-components], optional)
  — function to get components to use

###### Examples

A `/jsx-runtime` module will expose `Fragment`, `jsx`, and `jsxs`:

```tsx
import * as runtime from 'react/jsx-runtime'

const {default: Content} = await evaluate('# hi', {...runtime, baseUrl: import.meta.url, ...otherOptions})

```

A `/jsx-dev-runtime` module will expose `Fragment` and `jsxDEV`:

```tsx
import * as runtime from 'react/jsx-dev-runtime'

const {default: Content} = await evaluate('# hi', {development: true, baseUrl: import.meta.url, ...runtime, ...otherOptions})
```

Our providers will expose `useMDXComponents`:

```tsx
import * as provider from '@mdx-js/react'
import * as runtime from 'react/jsx-runtime'

const {default: Content} = await evaluate('# hi', {...provider, ...runtime, baseUrl: import.meta.url, ...otherOptions})
```

### `UseMdxComponents`

Get components (TypeScript type).

###### Parameters

There are no parameters.

###### Returns

Components ([`MDXComponents` from `mdx/types.js`][mdx-types-components]).

## Types

This package is fully typed with [TypeScript][].
It exports the additional types
[`CompileOptions`][api-compile-options],
[`EvaluateOptions`][api-evaluate-options],
[`Fragment`][api-fragment],
[`Jsx`][api-jsx],
[`JsxDev`][api-jsx-dev],
[`ProcessorOptions`][api-processor-options],
[`RunOptions`][api-run-options], and
[`UseMdxComponents`][api-use-mdx-components].

For types of evaluated MDX to work, make sure the TypeScript `JSX` namespace is
typed.
This is done by installing and using the types of your framework, such as
[`@types/react`](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/HEAD/types/react).
See [§ Types][types] on our website for information.

## Architecture

To understand what this project does, it’s very important to first understand
what unified does: please read through the [`unifiedjs/unified`][unified] readme
(the part until you hit the API section is required reading).

`@mdx-js/mdx` is a unified pipeline — wrapped so that most folks don’t need to
know about unified.
The processor goes through these steps:

1. parse MDX (serialized markdown with embedded JSX, ESM, and expressions)
   to mdast (markdown syntax tree)
2. transform through remark (markdown ecosystem)
3. transform mdast to hast (HTML syntax tree)
4. transform through rehype (HTML ecosystem)
5. transform hast to esast (JS syntax tree)
6. do the work needed to get a component
7. transform through recma (JS ecosystem)
8. serialize esast as JavaScript

The *input* is MDX (serialized markdown with embedded JSX, ESM, and
expressions).
The markdown is parsed with [`micromark/micromark`][micromark] and the embedded
JS with one of its extensions
[`micromark/micromark-extension-mdxjs`][micromark-extension-mdxjs] (which in
turn uses [acorn][]).
Then [`syntax-tree/mdast-util-from-markdown`][mdast-util-from-markdown] and its
extension [`syntax-tree/mdast-util-mdx`][mdast-util-mdx] are used to turn the
results from the parser into a syntax tree: [mdast][].

Markdown is closest to the source format.
This is where [remark plugins][remark-plugins] come in.
Typically, there shouldn’t be much going on here.
But perhaps you want to support GFM (tables and such) or frontmatter?
Then you can add a plugin here: `remark-gfm` or `remark-frontmatter`,
respectively.

After markdown, we go to [hast][] (HTML).
This transformation is done by
[`syntax-tree/mdast-util-to-hast`][mdast-util-to-hast].
Wait, why, what is HTML needed?
Part of the reason is that we care about HTML semantics: we want to know that
something is an `<a>`, not whether it’s a link with a resource (`[text](url)`)
or a reference to a defined link definition (`[text][id]\n\n[id]: url`).
So an HTML AST is *closer* to where we want to go.
Another reason is that there are many things folks need when they go MDX -> JS,
markdown -> HTML, or even folks who only process their HTML -> HTML: use cases
other than MDX.
By having a single AST in these cases and writing a plugin that works on that
AST, that plugin can supports *all* these use cases (for example,
[`rehypejs/rehype-highlight`][rehype-highlight] for syntax highlighting or
[`rehypejs/rehype-katex`][rehype-katex] for math).
So, this is where [rehype plugins][rehype-plugins] come in: most of the plugins,
probably.

Then we go to JavaScript: [esast][] (JS; an
AST which is compatible with estree but looks a bit more like other unist ASTs).
This transformation is done by
[`rehype-recma`][rehype-recma].
This is a new ecosystem that does not have utilities or plugins yet.
But it’s where `@mdx-js/mdx` does its thing: where it adds imports/exports,
where it compiles JSX away into `_jsx()` calls, and where it does the other cool
things that it provides.

Finally, The output is serialized JavaScript.
That final step is done by [astring][], a
small and fast JS generator.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, `@mdx-js/mdx@^3`,
compatible with Node.js 16.

## Security

See [§ Security][security] on our website for information.

## Contribute

See [§ Contribute][contribute] on our website for ways to get started.
See [§ Support][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][] © Compositor and [Vercel][]

[build-badge]: https://github.com/mdx-js/mdx/workflows/main/badge.svg

[build]: https://github.com/mdx-js/mdx/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/mdx-js/mdx/main.svg

[coverage]: https://codecov.io/github/mdx-js/mdx

[downloads-badge]: https://img.shields.io/npm/dm/@mdx-js/mdx.svg

[downloads]: https://www.npmjs.com/package/@mdx-js/mdx

[size-badge]: https://img.shields.io/bundlejs/size/@mdx-js/mdx

[size]: https://bundlejs.com/?q=@mdx-js/mdx

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/mdx-js/mdx/discussions

[npm]: https://docs.npmjs.com/cli/install

[contribute]: https://mdxjs.com/community/contribute/

[support]: https://mdxjs.com/community/support/

[coc]: https://github.com/mdx-js/.github/blob/main/code-of-conduct.md

[mit]: https://github.com/mdx-js/mdx/blob/main/packages/mdx/license

[vercel]: https://vercel.com

[source-map]: https://github.com/mozilla/source-map

[vfile]: https://github.com/vfile/vfile

[remark-plugins]: https://github.com/remarkjs/remark/blob/main/doc/plugins.md#list-of-plugins

[rehype-plugins]: https://github.com/rehypejs/rehype/blob/main/doc/plugins.md#list-of-plugins

[mdx-syntax]: https://mdxjs.com/docs/what-is-mdx/#mdx-syntax

[use]: #use

[unified]: https://github.com/unifiedjs/unified

[micromark]: https://github.com/micromark/micromark

[acorn]: https://github.com/acornjs/acorn

[micromark-extension-mdxjs]: https://github.com/micromark/micromark-extension-mdxjs

[mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown

[mdast-util-mdx]: https://github.com/syntax-tree/mdast-util-mdx

[mdast]: https://github.com/syntax-tree/mdast

[mdast-util-to-hast]: https://github.com/syntax-tree/mdast-util-to-hast

[hast]: https://github.com/syntax-tree/hast

[rehype-recma]: https://github.com/mdx-js/recma/tree/main/packages/rehype-recma

[rehype-highlight]: https://github.com/rehypejs/rehype-highlight

[rehype-katex]: https://github.com/remarkjs/remark-math/tree/main/packages/rehype-katex

[esast]: https://github.com/syntax-tree/esast

[astring]: https://github.com/davidbonnet/astring

[integrations]: https://mdxjs.com/getting-started/#integrations

[using-mdx]: https://mdxjs.com/docs/using-mdx/

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[types]: https://mdxjs.com/getting-started/#types

[security]: https://mdxjs.com/getting-started/#security

[typescript]: https://www.typescriptlang.org

[mdx-types-components]: https://github.com/DefinitelyTyped/DefinitelyTyped/blob/HEAD/types/mdx/types.d.ts#L65

[mdx-types-module]: https://github.com/DefinitelyTyped/DefinitelyTyped/blob/HEAD/types/mdx/types.d.ts#L101

[remark-rehype-options]: https://github.com/remarkjs/remark-rehype#options

[unified-pluggable-list]: https://github.com/unifiedjs/unified#pluggablelist

[unified-processor]: https://github.com/unifiedjs/unified#processor

[vfile-compatible]: https://github.com/vfile/vfile#compatible

[api-compile]: #compilefile-options

[api-compile-options]: #compileoptions

[api-compile-sync]: #compilesyncfile-options

[api-create-processor]: #createprocessoroptions

[api-evaluate]: #evaluatefile-options

[api-evaluate-options]: #evaluateoptions

[api-evaluate-sync]: #evaluatesyncfile-options

[api-fragment]: #fragment

[api-jsx]: #jsx

[api-jsx-dev]: #jsxdev

[api-node-types]: #nodetypes

[api-processor-options]: #processoroptions

[api-run]: #runcode-options

[api-run-options]: #runoptions

[api-run-sync]: #runsynccode-options

[api-use-mdx-components]: #usemdxcomponents


---

# `@mdx-js/react`

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

React context for MDX.

<!-- more -->

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`MDXProvider(properties?)`](#mdxproviderproperties)
  * [`useMDXComponents(components?)`](#usemdxcomponentscomponents)
  * [`MergeComponents`](#mergecomponents)
  * [`Props`](#props)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package is a *context* based components provider for combining React with
MDX.

## When should I use this?

This package is **not needed** for MDX to work with React.
See [¶ MDX provider in § Using MDX][use-provider] for when and how to use an MDX
provider.

If you use Next.js, **do not use this**.
Add an `mdx-components.tsx` (in `src/` or `/`) file instead.
See [Configuring MDX on `nextjs.org`][next-configuring-mdx] for more info.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install @mdx-js/react
```

In Deno with [`esm.sh`][esmsh]:

```tsx
import {MDXProvider} from 'https://esm.sh/@mdx-js/react@3'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {MDXProvider} from 'https://esm.sh/@mdx-js/react@3?bundle'
</script>
```

## Use

```tsx
import {MDXProvider} from '@mdx-js/react'
import Post from './post.mdx'
// ^-- Assumes an integration is used to compile MDX to JS, such as
// `@mdx-js/esbuild`, `@mdx-js/loader`, `@mdx-js/node-loader`, or
// `@mdx-js/rollup`, and that it is configured with
// `options.providerImportSource: '@mdx-js/react'`.

/** @type {import('mdx/types.js').MDXComponents} */
const components = {
  em(properties) {
    return <i {...properties} />
  }
}

console.log(
  <MDXProvider components={components}>
    <Post />
  </MDXProvider>
)
```

> 👉 **Note**: you don’t have to use `MDXProvider` and can pass components
> directly:
>
> ```diff
> -<MDXProvider components={components}>
> -  <Post />
> -</MDXProvider>
> +<Post components={components} />
> ```

See [¶ React in § Getting started][start-react] for how to get started with MDX
and React.
See [¶ MDX provider in § Using MDX][use-provider] for how to use an MDX
provider.

## API

This package exports the identifiers [`MDXProvider`][api-mdx-provider] and
[`useMDXComponents`][api-use-mdx-components].
There is no default export.

### `MDXProvider(properties?)`

Provider for MDX context.

###### Parameters

* `properties` ([`Props`][api-props])
  — configuration

##### Returns

Element (`JSX.Element`).

### `useMDXComponents(components?)`

Get current components from the MDX Context.

###### Parameters

* `components` ([`MDXComponents` from `mdx/types.js`][mdx-types-components]
  or [`MergeComponents`][api-merge-components], optional)
  — additional components to use or a function that creates them

###### Returns

Current components ([`MDXComponents` from
`mdx/types.js`][mdx-types-components]).

### `MergeComponents`

Custom merge function (TypeScript type).

###### Parameters

* `components` ([`MDXComponents` from `mdx/types.js`][mdx-types-components])
  — current components from the context

###### Returns

Additional components ([`MDXComponents` from
`mdx/types.js`][mdx-types-components]).

### `Props`

Configuration for `MDXProvider` (TypeScript type).

###### Fields

* `children` ([`ReactNode` from `react`][react-node],
  optional)
  — children
* `components` ([`MDXComponents` from `mdx/types.js`][mdx-types-components]
  or [`MergeComponents`][api-merge-components], optional)
  — additional components to use or a function that creates them
* `disableParentContext` (`boolean`, default: `false`)
  — turn off outer component context

## Types

This package is fully typed with [TypeScript][].
It exports the additional types [`MergeComponents`][api-merge-components] and
[`Props`][api-props].

For types to work, make sure the TypeScript `JSX` namespace is typed.
This is done by installing and using the types of your framework, as in
[`@types/react`](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/HEAD/types/react).

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, `@mdx-js/react@^3`,
compatible with Node.js 16.

## Security

See [§ Security][security] on our website for information.

## Contribute

See [§ Contribute][contribute] on our website for ways to get started.
See [§ Support][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][] © Compositor and [Vercel][]

[build-badge]: https://github.com/mdx-js/mdx/workflows/main/badge.svg

[build]: https://github.com/mdx-js/mdx/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/mdx-js/mdx/main.svg

[coverage]: https://codecov.io/github/mdx-js/mdx

[downloads-badge]: https://img.shields.io/npm/dm/@mdx-js/react.svg

[downloads]: https://www.npmjs.com/package/@mdx-js/react

[size-badge]: https://img.shields.io/bundlejs/size/@mdx-js/react

[size]: https://bundlejs.com/?q=@mdx-js/react

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/mdx-js/mdx/discussions

[npm]: https://docs.npmjs.com/cli/install

[contribute]: https://mdxjs.com/community/contribute/

[support]: https://mdxjs.com/community/support/

[coc]: https://github.com/mdx-js/.github/blob/main/code-of-conduct.md

[mit]: https://github.com/mdx-js/mdx/blob/main/packages/react/license

[vercel]: https://vercel.com

[start-react]: https://mdxjs.com/getting-started/#react

[use-provider]: https://mdxjs.com/docs/using-mdx/#mdx-provider

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[security]: https://mdxjs.com/getting-started/#security

[typescript]: https://www.typescriptlang.org

[mdx-types-components]: https://github.com/DefinitelyTyped/DefinitelyTyped/blob/HEAD/types/mdx/types.d.ts#L65

[react-node]: https://github.com/DefinitelyTyped/DefinitelyTyped/blob/HEAD/types/react/index.d.ts#L244

[next-configuring-mdx]: https://nextjs.org/docs/pages/building-your-application/configuring/mdx

[api-mdx-provider]: #mdxproviderproperties

[api-merge-components]: #mergecomponents

[api-props]: #props

[api-use-mdx-components]: #usemdxcomponentscomponents


---

# @nodelib/fs.scandir

> List files and directories inside the specified directory.

## :bulb: Highlights

The package is aimed at obtaining information about entries in the directory.

* :moneybag: Returns useful information: `name`, `path`, `dirent` and `stats` (optional).
* :gear: On Node.js 10.10+ uses the mechanism without additional calls to determine the entry type. See [`old` and `modern` mode](#old-and-modern-mode).
* :link: Can safely work with broken symbolic links.

## Install

```console
npm install @nodelib/fs.scandir
```

## Usage

```ts
import * as fsScandir from '@nodelib/fs.scandir';

fsScandir.scandir('path', (error, stats) => { /* … */ });
```

## API

### .scandir(path, [optionsOrSettings], callback)

Returns an array of plain objects ([`Entry`](#entry)) with information about entry for provided path with standard callback-style.

```ts
fsScandir.scandir('path', (error, entries) => { /* … */ });
fsScandir.scandir('path', {}, (error, entries) => { /* … */ });
fsScandir.scandir('path', new fsScandir.Settings(), (error, entries) => { /* … */ });
```

### .scandirSync(path, [optionsOrSettings])

Returns an array of plain objects ([`Entry`](#entry)) with information about entry for provided path.

```ts
const entries = fsScandir.scandirSync('path');
const entries = fsScandir.scandirSync('path', {});
const entries = fsScandir.scandirSync(('path', new fsScandir.Settings());
```

#### path

* Required: `true`
* Type: `string | Buffer | URL`

A path to a file. If a URL is provided, it must use the `file:` protocol.

#### optionsOrSettings

* Required: `false`
* Type: `Options | Settings`
* Default: An instance of `Settings` class

An [`Options`](#options) object or an instance of [`Settings`](#settingsoptions) class.

> :book: When you pass a plain object, an instance of the `Settings` class will be created automatically. If you plan to call the method frequently, use a pre-created instance of the `Settings` class.

### Settings([options])

A class of full settings of the package.

```ts
const settings = new fsScandir.Settings({ followSymbolicLinks: false });

const entries = fsScandir.scandirSync('path', settings);
```

## Entry

* `name` — The name of the entry (`unknown.txt`).
* `path` — The path of the entry relative to call directory (`root/unknown.txt`).
* `dirent` — An instance of [`fs.Dirent`](./src/types/index.ts) class. On Node.js below 10.10 will be emulated by [`DirentFromStats`](./src/utils/fs.ts) class.
* `stats` (optional) — An instance of `fs.Stats` class.

For example, the `scandir` call for `tools` directory with one directory inside:

```ts
{
	dirent: Dirent { name: 'typedoc', /* … */ },
	name: 'typedoc',
	path: 'tools/typedoc'
}
```

## Options

### stats

* Type: `boolean`
* Default: `false`

Adds an instance of `fs.Stats` class to the [`Entry`](#entry).

> :book: Always use `fs.readdir` without the `withFileTypes` option. ??TODO??

### followSymbolicLinks

* Type: `boolean`
* Default: `false`

Follow symbolic links or not. Call `fs.stat` on symbolic link if `true`.

### `throwErrorOnBrokenSymbolicLink`

* Type: `boolean`
* Default: `true`

Throw an error when symbolic link is broken if `true` or safely use `lstat` call if `false`.

### `pathSegmentSeparator`

* Type: `string`
* Default: `path.sep`

By default, this package uses the correct path separator for your OS (`\` on Windows, `/` on Unix-like systems). But you can set this option to any separator character(s) that you want to use instead.

### `fs`

* Type: [`FileSystemAdapter`](./src/adapters/fs.ts)
* Default: A default FS methods

By default, the built-in Node.js module (`fs`) is used to work with the file system. You can replace any method with your own.

```ts
interface FileSystemAdapter {
	lstat?: typeof fs.lstat;
	stat?: typeof fs.stat;
	lstatSync?: typeof fs.lstatSync;
	statSync?: typeof fs.statSync;
	readdir?: typeof fs.readdir;
	readdirSync?: typeof fs.readdirSync;
}

const settings = new fsScandir.Settings({
	fs: { lstat: fakeLstat }
});
```

## `old` and `modern` mode

This package has two modes that are used depending on the environment and parameters of use.

### old

* Node.js below `10.10` or when the `stats` option is enabled

When working in the old mode, the directory is read first (`fs.readdir`), then the type of entries is determined (`fs.lstat` and/or `fs.stat` for symbolic links).

### modern

* Node.js 10.10+ and the `stats` option is disabled

In the modern mode, reading the directory (`fs.readdir` with the `withFileTypes` option) is combined with obtaining information about its entries. An additional call for symbolic links (`fs.stat`) is still present.

This mode makes fewer calls to the file system. It's faster.

## Changelog

See the [Releases section of our GitHub project](https://github.com/nodelib/nodelib/releases) for changelog for each release version.

## License

This software is released under the terms of the MIT license.


---

# @nodelib/fs.stat

> Get the status of a file with some features.

## :bulb: Highlights

Wrapper around standard method `fs.lstat` and `fs.stat` with some features.

* :beginner: Normally follows symbolic link.
* :gear: Can safely work with broken symbolic link.

## Install

```console
npm install @nodelib/fs.stat
```

## Usage

```ts
import * as fsStat from '@nodelib/fs.stat';

fsStat.stat('path', (error, stats) => { /* … */ });
```

## API

### .stat(path, [optionsOrSettings], callback)

Returns an instance of `fs.Stats` class for provided path with standard callback-style.

```ts
fsStat.stat('path', (error, stats) => { /* … */ });
fsStat.stat('path', {}, (error, stats) => { /* … */ });
fsStat.stat('path', new fsStat.Settings(), (error, stats) => { /* … */ });
```

### .statSync(path, [optionsOrSettings])

Returns an instance of `fs.Stats` class for provided path.

```ts
const stats = fsStat.stat('path');
const stats = fsStat.stat('path', {});
const stats = fsStat.stat('path', new fsStat.Settings());
```

#### path

* Required: `true`
* Type: `string | Buffer | URL`

A path to a file. If a URL is provided, it must use the `file:` protocol.

#### optionsOrSettings

* Required: `false`
* Type: `Options | Settings`
* Default: An instance of `Settings` class

An [`Options`](#options) object or an instance of [`Settings`](#settings) class.

> :book: When you pass a plain object, an instance of the `Settings` class will be created automatically. If you plan to call the method frequently, use a pre-created instance of the `Settings` class.

### Settings([options])

A class of full settings of the package.

```ts
const settings = new fsStat.Settings({ followSymbolicLink: false });

const stats = fsStat.stat('path', settings);
```

## Options

### `followSymbolicLink`

* Type: `boolean`
* Default: `true`

Follow symbolic link or not. Call `fs.stat` on symbolic link if `true`.

### `markSymbolicLink`

* Type: `boolean`
* Default: `false`

Mark symbolic link by setting the return value of `isSymbolicLink` function to always `true` (even after `fs.stat`).

> :book: Can be used if you want to know what is hidden behind a symbolic link, but still continue to know that it is a symbolic link.

### `throwErrorOnBrokenSymbolicLink`

* Type: `boolean`
* Default: `true`

Throw an error when symbolic link is broken if `true` or safely return `lstat` call if `false`.

### `fs`

* Type: [`FileSystemAdapter`](./src/adapters/fs.ts)
* Default: A default FS methods

By default, the built-in Node.js module (`fs`) is used to work with the file system. You can replace any method with your own.

```ts
interface FileSystemAdapter {
	lstat?: typeof fs.lstat;
	stat?: typeof fs.stat;
	lstatSync?: typeof fs.lstatSync;
	statSync?: typeof fs.statSync;
}

const settings = new fsStat.Settings({
	fs: { lstat: fakeLstat }
});
```

## Changelog

See the [Releases section of our GitHub project](https://github.com/nodelib/nodelib/releases) for changelog for each release version.

## License

This software is released under the terms of the MIT license.


---

# @nodelib/fs.walk

> A library for efficiently walking a directory recursively.

## :bulb: Highlights

* :moneybag: Returns useful information: `name`, `path`, `dirent` and `stats` (optional).
* :rocket: On Node.js 10.10+ uses the mechanism without additional calls to determine the entry type for performance reasons. See [`old` and `modern` mode](https://github.com/nodelib/nodelib/blob/master/packages/fs/fs.scandir/README.md#old-and-modern-mode).
* :gear: Built-in directories/files and error filtering system.
* :link: Can safely work with broken symbolic links.

## Install

```console
npm install @nodelib/fs.walk
```

## Usage

```ts
import * as fsWalk from '@nodelib/fs.walk';

fsWalk.walk('path', (error, entries) => { /* … */ });
```

## API

### .walk(path, [optionsOrSettings], callback)

Reads the directory recursively and asynchronously. Requires a callback function.

> :book: If you want to use the Promise API, use `util.promisify`.

```ts
fsWalk.walk('path', (error, entries) => { /* … */ });
fsWalk.walk('path', {}, (error, entries) => { /* … */ });
fsWalk.walk('path', new fsWalk.Settings(), (error, entries) => { /* … */ });
```

### .walkStream(path, [optionsOrSettings])

Reads the directory recursively and asynchronously. [Readable Stream](https://nodejs.org/dist/latest-v12.x/docs/api/stream.html#stream_readable_streams) is used as a provider.

```ts
const stream = fsWalk.walkStream('path');
const stream = fsWalk.walkStream('path', {});
const stream = fsWalk.walkStream('path', new fsWalk.Settings());
```

### .walkSync(path, [optionsOrSettings])

Reads the directory recursively and synchronously. Returns an array of entries.

```ts
const entries = fsWalk.walkSync('path');
const entries = fsWalk.walkSync('path', {});
const entries = fsWalk.walkSync('path', new fsWalk.Settings());
```

#### path

* Required: `true`
* Type: `string | Buffer | URL`

A path to a file. If a URL is provided, it must use the `file:` protocol.

#### optionsOrSettings

* Required: `false`
* Type: `Options | Settings`
* Default: An instance of `Settings` class

An [`Options`](#options) object or an instance of [`Settings`](#settings) class.

> :book: When you pass a plain object, an instance of the `Settings` class will be created automatically. If you plan to call the method frequently, use a pre-created instance of the `Settings` class.

### Settings([options])

A class of full settings of the package.

```ts
const settings = new fsWalk.Settings({ followSymbolicLinks: true });

const entries = fsWalk.walkSync('path', settings);
```

## Entry

* `name` — The name of the entry (`unknown.txt`).
* `path` — The path of the entry relative to call directory (`root/unknown.txt`).
* `dirent` — An instance of [`fs.Dirent`](./src/types/index.ts) class.
* [`stats`] — An instance of `fs.Stats` class.

## Options

### basePath

* Type: `string`
* Default: `undefined`

By default, all paths are built relative to the root path. You can use this option to set custom root path.

In the example below we read the files from the `root` directory, but in the results the root path will be `custom`.

```ts
fsWalk.walkSync('root'); // → ['root/file.txt']
fsWalk.walkSync('root', { basePath: 'custom' }); // → ['custom/file.txt']
```

### concurrency

* Type: `number`
* Default: `Infinity`

The maximum number of concurrent calls to `fs.readdir`.

> :book: The higher the number, the higher performance and the load on the File System. If you want to read in quiet mode, set the value to `4 * os.cpus().length` (4 is default size of [thread pool work scheduling](http://docs.libuv.org/en/v1.x/threadpool.html#thread-pool-work-scheduling)).

### deepFilter

* Type: [`DeepFilterFunction`](./src/settings.ts)
* Default: `undefined`

A function that indicates whether the directory will be read deep or not.

```ts
// Skip all directories that starts with `node_modules`
const filter: DeepFilterFunction = (entry) => !entry.path.startsWith('node_modules');
```

### entryFilter

* Type: [`EntryFilterFunction`](./src/settings.ts)
* Default: `undefined`

A function that indicates whether the entry will be included to results or not.

```ts
// Exclude all `.js` files from results
const filter: EntryFilterFunction = (entry) => !entry.name.endsWith('.js');
```

### errorFilter

* Type: [`ErrorFilterFunction`](./src/settings.ts)
* Default: `undefined`

A function that allows you to skip errors that occur when reading directories.

For example, you can skip `ENOENT` errors if required:

```ts
// Skip all ENOENT errors
const filter: ErrorFilterFunction = (error) => error.code == 'ENOENT';
```

### stats

* Type: `boolean`
* Default: `false`

Adds an instance of `fs.Stats` class to the [`Entry`](#entry).

> :book: Always use `fs.readdir` with additional `fs.lstat/fs.stat` calls to determine the entry type.

### followSymbolicLinks

* Type: `boolean`
* Default: `false`

Follow symbolic links or not. Call `fs.stat` on symbolic link if `true`.

### `throwErrorOnBrokenSymbolicLink`

* Type: `boolean`
* Default: `true`

Throw an error when symbolic link is broken if `true` or safely return `lstat` call if `false`.

### `pathSegmentSeparator`

* Type: `string`
* Default: `path.sep`

By default, this package uses the correct path separator for your OS (`\` on Windows, `/` on Unix-like systems). But you can set this option to any separator character(s) that you want to use instead.

### `fs`

* Type: `FileSystemAdapter`
* Default: A default FS methods

By default, the built-in Node.js module (`fs`) is used to work with the file system. You can replace any method with your own.

```ts
interface FileSystemAdapter {
	lstat: typeof fs.lstat;
	stat: typeof fs.stat;
	lstatSync: typeof fs.lstatSync;
	statSync: typeof fs.statSync;
	readdir: typeof fs.readdir;
	readdirSync: typeof fs.readdirSync;
}

const settings = new fsWalk.Settings({
	fs: { lstat: fakeLstat }
});
```

## Changelog

See the [Releases section of our GitHub project](https://github.com/nodelib/nodelib/releases) for changelog for each release version.

## License

This software is released under the terms of the MIT license.


---

---
labels: ['configuration']
description: 'A function for repacing env variables in configuration settings'
---

API:

```ts
function envReplace(settingValue: string, env: NodeJS.ProcessEnv): string;
```

Usage:

```ts
import { envReplace } from '@pnpm/config.env-replace'

envReplace('${foo}', process.env)
```


---

---
labels: ['configuration']
description: 'A function for repacing env variables in configuration settings'
---

API:

```ts
function envReplace(settingValue: string, env: NodeJS.ProcessEnv): string;
```

Usage:

```ts
import { envReplace } from '@pnpm/config.env-replace'

envReplace('${foo}', process.env)
```


---

---
labels: ['ca', 'certificate authority']
description: 'A component for reading the certificate authority data from a text file'
---

API:

```ts
import { readCAFileSync } from '@pnpm/network.ca-file'

readCAFileSync('cafile.txt')
```


---

---
labels: ['ca', 'certificate authority']
description: 'A component for reading the certificate authority data from a text file'
---

API:

```ts
import { readCAFileSync } from '@pnpm/network.ca-file'

readCAFileSync('cafile.txt')
```


---

# graceful-fs

graceful-fs functions as a drop-in replacement for the fs module,
making various improvements.

The improvements are meant to normalize behavior across different
platforms and environments, and to make filesystem access more
resilient to errors.

## Improvements over [fs module](https://nodejs.org/api/fs.html)

* Queues up `open` and `readdir` calls, and retries them once
  something closes if there is an EMFILE error from too many file
  descriptors.
* fixes `lchmod` for Node versions prior to 0.6.2.
* implements `fs.lutimes` if possible. Otherwise it becomes a noop.
* ignores `EINVAL` and `EPERM` errors in `chown`, `fchown` or
  `lchown` if the user isn't root.
* makes `lchmod` and `lchown` become noops, if not available.
* retries reading a file if `read` results in EAGAIN error.

On Windows, it retries renaming a file for up to one second if `EACCESS`
or `EPERM` error occurs, likely because antivirus software has locked
the directory.

## USAGE

```javascript
// use just like fs
var fs = require('graceful-fs')

// now go and do stuff with it...
fs.readFile('some-file-or-whatever', (err, data) => {
  // Do stuff here.
})
```

## Sync methods

This module cannot intercept or handle `EMFILE` or `ENFILE` errors from sync
methods.  If you use sync methods which open file descriptors then you are
responsible for dealing with any errors.

This is a known limitation, not a bug.

## Global Patching

If you want to patch the global fs module (or any other fs-like
module) you can do this:

```javascript
// Make sure to read the caveat below.
var realFs = require('fs')
var gracefulFs = require('graceful-fs')
gracefulFs.gracefulify(realFs)
```

This should only ever be done at the top-level application layer, in
order to delay on EMFILE errors from any fs-using dependencies.  You
should **not** do this in a library, because it can cause unexpected
delays in other parts of the program.

## Changes

This module is fairly stable at this point, and used by a lot of
things.  That being said, because it implements a subtle behavior
change in a core part of the node API, even modest changes can be
extremely breaking, and the versioning is thus biased towards
bumping the major when in doubt.

The main change between major versions has been switching between
providing a fully-patched `fs` module vs monkey-patching the node core
builtin, and the approach by which a non-monkey-patched `fs` was
created.

The goal is to trade `EMFILE` errors for slower fs operations.  So, if
you try to open a zillion files, rather than crashing, `open`
operations will be queued up and wait for something else to `close`.

There are advantages to each approach.  Monkey-patching the fs means
that no `EMFILE` errors can possibly occur anywhere in your
application, because everything is using the same core `fs` module,
which is patched.  However, it can also obviously cause undesirable
side-effects, especially if the module is loaded multiple times.

Implementing a separate-but-identical patched `fs` module is more
surgical (and doesn't run the risk of patching multiple times), but
also imposes the challenge of keeping in sync with the core module.

The current approach loads the `fs` module, and then creates a
lookalike object that has all the same methods, except a few that are
patched.  It is safe to use in all versions of Node from 0.8 through
7.0.

### v4

* Do not monkey-patch the fs module.  This module may now be used as a
  drop-in dep, and users can opt into monkey-patching the fs builtin
  if their app requires it.

### v3

* Monkey-patch fs, because the eval approach no longer works on recent
  node.
* fixed possible type-error throw if rename fails on windows
* verify that we *never* get EMFILE errors
* Ignore ENOSYS from chmod/chown
* clarify that graceful-fs must be used as a drop-in

### v2.1.0

* Use eval rather than monkey-patching fs.
* readdir: Always sort the results
* win32: requeue a file if error has an OK status

### v2.0

* A return to monkey patching
* wrap process.cwd

### v1.1

* wrap readFile
* Wrap fs.writeFile.
* readdir protection
* Don't clobber the fs builtin
* Handle fs.read EAGAIN errors by trying again
* Expose the curOpen counter
* No-op lchown/lchmod if not implemented
* fs.rename patch only for win32
* Patch fs.rename to handle AV software on Windows
* Close #4 Chown should not fail on einval or eperm if non-root
* Fix isaacs/fstream#1 Only wrap fs one time
* Fix #3 Start at 1024 max files, then back off on EMFILE
* lutimes that doens't blow up on Linux
* A full on-rewrite using a queue instead of just swallowing the EMFILE error
* Wrap Read/Write streams as well

### 1.0

* Update engines for node 0.6
* Be lstat-graceful on Windows
* first


---

# @pnpm/npm-conf [![Build Status](https://travis-ci.com/pnpm/npm-conf.svg?branch=master)](https://travis-ci.com/pnpm/npm-conf)

> Get the npm config


## Install

```
$ pnpm add @pnpm/npm-conf
```


## Usage

```js
const npmConf = require('@pnpm/npm-conf');

const conf = npmConf();

conf.get('prefix')
//=> //=> /Users/unicorn/.npm-packages

conf.get('registry')
//=> https://registry.npmjs.org/
```

To get a list of all available `npm` config options:

```bash
$ npm config list --long
```


## API

### npmConf()

Returns the `npm` config.

### npmConf.defaults

Returns the default `npm` config.


## License

MIT © [Kevin Mårtensson](https://github.com/kevva)


---

# @polka/url [![npm](https://badgen.now.sh/npm/v/@polka/url)](https://npmjs.org/package/@polka/url) [![licenses](https://licenses.dev/b/npm/%40polka%2Furl)](https://licenses.dev/npm/%40polka%2Furl)

> Super fast, memoized `req.url` parser; _not_ limited to [Polka][polka]!

Parses the `url` from a [`IncomingMessage`](https://nodejs.org/api/http.html#http_class_http_incomingmessage) request. The returned object will always only contain the following keys: `search`, `query`, `pathname`, and `raw`.

> **Note:** This library does not process `protocol`, `hostname`, `port`, etc.<br>This is because the incoming `req.url` value only begins with the path information.

Parsed requests will be mutated with a `_parsedUrl` key, containing the returned output. This is used for future memoization, avoiding the need to fully parse the same `url` value multiple times.

## Install

```
$ npm install --save @polka/url
```

## Usage

```js
const parse = require('@polka/url');

let req = {
  url: '/foo/bar?fizz=buzz'
};
let output = parse(req);
//=> {
//=>   pathname: '/foo/bar',
//=>   raw: '/foo/bar?fizz=buzz',
//=>   search: '?fizz=buzz',
//=>   query: {
//=>     fizz: 'buzz'
//=>   },
//=> }

// Attaches result for future memoization
assert.deepEqual(output, req._parsedUrl); //=> true
```

## API

### url(req)
Returns: `Object` or `undefined`

> **Important:** The `req` must have a `url` key, otherwise `undefined` will be returned.<br>If no input is provided at all, a `TypeError` will be thrown.

#### req
Type: `IncomingMessage` or `{ url: string }`

The incoming HTTP request (`req`) or a plain `Object` with a `url` key.

> **Note:** In Node.js servers, the [`req.url`](https://nodejs.org/api/http.html#http_message_url) begins with a pathname & does not include a `hash`.


## Benchmarks

Check out the [`bench`](/bench) directory for in-depth benchmark results and comparisons.


## Support

Any issues or questions can be sent to the [Polka][polka] repository.<br>However, please specify that your inquiry is about `@polka/url` specifically.


## License

MIT © [Luke Edwards](https://lukeed.com)

[polka]: https://github.com/lukeed/polka


---

Copyright (c) 2019-2020, Sideway, Inc. and Project contributors
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
 * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
 * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
 * The names of any contributors may not be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS AND CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


---

# @sideway/address

#### Validate email address and domain.

**address** is part of the **joi** ecosystem.

### Visit the [joi.dev](https://joi.dev) Developer Portal for tutorials, documentation, and support

## Useful resources

- [Documentation and API](https://joi.dev/module/address/)
- [Versions status](https://joi.dev/resources/status/#address)
- [Changelog](https://joi.dev/module/address/changelog/)
- [Project policies](https://joi.dev/policies/)


---

Copyright (c) 2019-2020, Sideway. Inc, and project contributors
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
 * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
 * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
 * The names of any contributors may not be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS AND CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


---

# @sideway/formula

#### Math and string formula parser.

**formula** is part of the **joi** ecosystem.

### Visit the [joi.dev](https://joi.dev) Developer Portal for tutorials, documentation, and support

## Useful resources

- [Documentation and API](https://joi.dev/module/formula/)
- [Version status](https://joi.dev/resources/status/#formula) (builds, dependencies, node versions, licenses, eol)
- [Changelog](https://joi.dev/module/formula/changelog/)
- [Project policies](https://joi.dev/policies/)

## Acknowledgements

Inspired by [**fparse**](https://github.com/bylexus/fparse), copyright 2012-2018 Alexander Schenkel <alex@alexi.ch>


---

Copyright (c) 2019-2020, Sideway. Inc, and project contributors  

All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
* The names of any contributors may not be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS AND CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS OFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


---

# @sideway/pinpoint

#### Return the filename and line number of the calling function.

**pinpoint** is part of the **joi** ecosystem.

### Visit the [joi.dev](https://joi.dev) Developer Portal for tutorials, documentation, and support

## Useful resources

- [Documentation and API](https://joi.dev/module/pinpoint/)
- [Version status](https://joi.dev/resources/status/#pinpoint) (builds, dependencies, node versions, licenses, eol)
- [Changelog](https://joi.dev/module/pinpoint/changelog/)
- [Project policies](https://joi.dev/policies/)


---

<div align='center'>

<h1>TypeBox</h1>

<p>JSON Schema Type Builder with Static Type Resolution for TypeScript</p>
	
<img src="https://github.com/sinclairzx81/typebox/blob/master/typebox.png?raw=true" />

<br />
<br />

[![npm version](https://badge.fury.io/js/%40sinclair%2Ftypebox.svg)](https://badge.fury.io/js/%40sinclair%2Ftypebox)
[![Downloads](https://img.shields.io/npm/dm/%40sinclair%2Ftypebox.svg)](https://www.npmjs.com/package/%40sinclair%2Ftypebox)
[![GitHub CI](https://github.com/sinclairzx81/typebox/workflows/GitHub%20CI/badge.svg)](https://github.com/sinclairzx81/typebox/actions)

</div>

<a name="Install"></a>

## Install

#### Npm
```bash
$ npm install @sinclair/typebox --save
```

#### Deno
```typescript
import { Static, Type } from 'npm:@sinclair/typebox'
```

#### Esm

```typescript
import { Static, Type } from 'https://esm.sh/@sinclair/typebox'
```

## Example

```typescript
import { Static, Type } from '@sinclair/typebox'

const T = Type.Object({                              // const T = {
  x: Type.Number(),                                  //   type: 'object',
  y: Type.Number(),                                  //   required: ['x', 'y', 'z'],
  z: Type.Number()                                   //   properties: {
})                                                   //     x: { type: 'number' },
                                                     //     y: { type: 'number' },
                                                     //     z: { type: 'number' }
                                                     //   }
                                                     // }

type T = Static<typeof T>                            // type T = {
                                                     //   x: number,
                                                     //   y: number,
                                                     //   z: number
                                                     // }
```


<a name="Overview"></a>

## Overview

TypeBox is a runtime type builder that creates in-memory JSON Schema objects that can be statically inferred as TypeScript types. The schemas produced by this library are designed to match the static type assertion rules of the TypeScript compiler. TypeBox enables one to create a unified type that can be statically checked by TypeScript and runtime asserted using standard JSON Schema validation.

This library is designed to enable JSON schema to compose with the same flexibility as TypeScript's type system. It can be used as a simple tool to build up complex schemas or integrated into REST or RPC services to help validate data received over the wire. 

License MIT

## Contents
- [Install](#install)
- [Overview](#overview)
- [Usage](#usage)
- [Types](#types)
  - [Standard](#types-standard)
  - [Extended](#types-extended)
  - [Modifiers](#types-modifiers)
  - [Options](#types-options)
  - [Generics](#types-generics)
  - [References](#types-references)
  - [Recursive](#types-recursive)
  - [Conditional](#types-conditional)
  - [Template Literal](#types-template-literal)
  - [Guards](#types-guards)
  - [Unsafe](#types-unsafe)
  - [Strict](#types-strict)
- [Values](#values)
  - [Create](#values-create)
  - [Clone](#values-clone)
  - [Check](#values-check)
  - [Convert](#values-convert)
  - [Cast](#values-cast)
  - [Equal](#values-equal)
  - [Hash](#values-hash)
  - [Diff](#values-diff)
  - [Patch](#values-patch)
  - [Errors](#values-errors)
  - [Mutate](#values-mutate)
  - [Pointer](#values-pointer)
- [TypeCheck](#typecheck)
  - [Ajv](#typecheck-ajv)
  - [TypeCompiler](#typecheck-typecompiler)
- [TypeSystem](#typesystem)
  - [Types](#typesystem-types)
  - [Formats](#typesystem-formats)
  - [Policies](#typesystem-policies)
- [Benchmark](#benchmark)
  - [Compile](#benchmark-compile)
  - [Validate](#benchmark-validate)
  - [Compression](#benchmark-compression)
- [Contribute](#contribute)

<a name="usage"></a>

## Usage

The following shows general usage.

```typescript
import { Static, Type } from '@sinclair/typebox'

//--------------------------------------------------------------------------------------------
//
// Let's say you have the following type ...
//
//--------------------------------------------------------------------------------------------

type T = {
  id: string,
  name: string,
  timestamp: number
}

//--------------------------------------------------------------------------------------------
//
// ... you can express this type in the following way.
//
//--------------------------------------------------------------------------------------------

const T = Type.Object({                              // const T = {
  id: Type.String(),                                 //   type: 'object',
  name: Type.String(),                               //   properties: { 
  timestamp: Type.Integer()                          //     id: { 
})                                                   //       type: 'string' 
                                                     //     },
                                                     //     name: { 
                                                     //       type: 'string' 
                                                     //     },
                                                     //     timestamp: { 
                                                     //       type: 'integer' 
                                                     //     }
                                                     //   }, 
                                                     //   required: [
                                                     //     'id',
                                                     //     'name',
                                                     //     'timestamp'
                                                     //   ]
                                                     // } 

//--------------------------------------------------------------------------------------------
//
// ... then infer back to the original static type this way.
//
//--------------------------------------------------------------------------------------------

type T = Static<typeof T>                            // type T = {
                                                     //   id: string,
                                                     //   name: string,
                                                     //   timestamp: number
                                                     // }

//--------------------------------------------------------------------------------------------
//
// ... then use the type both as JSON schema and as a TypeScript type.
//
//--------------------------------------------------------------------------------------------

import { Value } from '@sinclair/typebox/value'

function receive(value: T) {                         // ... as a Static Type

  if(Value.Check(T, value)) {                        // ... as a JSON Schema
  
    // ok...
  }
}
```

<a name='types'></a>

## Types

TypeBox types are JSON schema fragments that can be composed into more complex types. Each fragment is structured such that a JSON schema compliant validator can runtime assert a value the same way TypeScript will statically assert a type. TypeBox provides a set of Standard types which are used create JSON schema compliant schematics as well as an Extended type set used to create schematics for constructs native to JavaScript. 

<a name='types-standard'></a>

### Standard Types

The following table lists the Standard TypeBox types. These types are fully compatible with the JSON Schema Draft 6 specification.

```typescript
┌────────────────────────────────┬─────────────────────────────┬────────────────────────────────┐
│ TypeBox                        │ TypeScript                  │ JSON Schema                    │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Any()           │ type T = any                │ const T = { }                  │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Unknown()       │ type T = unknown            │ const T = { }                  │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.String()        │ type T = string             │ const T = {                    │
│                                │                             │   type: 'string'               │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Number()        │ type T = number             │ const T = {                    │
│                                │                             │   type: 'number'               │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Integer()       │ type T = number             │ const T = {                    │
│                                │                             │   type: 'integer'              │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Boolean()       │ type T = boolean            │ const T = {                    │
│                                │                             │   type: 'boolean'              │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Null()          │ type T = null               │ const T = {                    │
│                                │                             │   type: 'null'                 │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Literal(42)     │ type T = 42                 │ const T = {                    │
│                                │                             │   const: 42,                   │
│                                │                             │   type: 'number'               │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Array(          │ type T = number[]           │ const T = {                    │
│   Type.Number()                │                             │   type: 'array',               │
│ )                              │                             │   items: {                     │
│                                │                             │     type: 'number'             │
│                                │                             │   }                            │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Object({        │ type T = {                  │ const T = {                    │
│   x: Type.Number(),            │   x: number,                │   type: 'object',              │
│   y: Type.Number()             │   y: number                 │   required: ['x', 'y'],        │
│ })                             │ }                           │   properties: {                │
│                                │                             │     x: {                       │
│                                │                             │       type: 'number'           │
│                                │                             │     }, {                       │
│                                │                             │       type: 'number'           │
│                                │                             │     }                          │
│                                │                             │   }                            │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Tuple([         │ type T = [number, number]   │ const T = {                    │
│   Type.Number(),               │                             │   type: 'array',               │
│   Type.Number()                │                             │   items: [{                    │
│ ])                             │                             │      type: 'number'            │
│                                │                             │   }, {                         │
│                                │                             │     type: 'number'             │
│                                │                             │   }],                          │
│                                │                             │   additionalItems: false,      │
│                                │                             │   minItems: 2,                 │
│                                │                             │   maxItems: 2                  │
│                                │                             │ }                              │
│                                │                             │                                │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ enum Foo {                     │ enum Foo {                  │ const T = {                    │
│   A,                           │   A,                        │   anyOf: [{                    │
│   B                            │   B                         │     type: 'number',            │
│ }                              │ }                           │     const: 0                   │
│                                │                             │   }, {                         │
│ const T = Type.Enum(Foo)       │ type T = Foo                │     type: 'number',            │
│                                │                             │     const: 1                   │
│                                │                             │   }]                           │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.KeyOf(          │ type T = keyof {            │ const T = {                    │
│   Type.Object({                │   x: number,                │   anyOf: [{                    │
│     x: Type.Number(),          │   y: number                 │     type: 'string',            │
│     y: Type.Number()           │ }                           │     const: 'x'                 │
│   })                           │                             │   }, {                         │
│ )                              │                             │     type: 'string',            │
│                                │                             │     const: 'y'                 │
│                                │                             │   }]                           │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Union([         │ type T = string | number    │ const T = {                    │
│   Type.String(),               │                             │   anyOf: [{                    │
│   Type.Number()                │                             │      type: 'string'            │
│ ])                             │                             │   }, {                         │
│                                │                             │      type: 'number'            │
│                                │                             │   }]                           │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Intersect([     │ type T = {                  │ const T = {                    │
│   Type.Object({                │   x: number                 │   allOf: [{                    │
│     x: Type.Number()           │ } & {                       │     type: 'object',            │
│   }),                          │   y: number                 │     required: ['x'],           │
│   Type.Object({                │ }                           │     properties: {              │
│     y: Type.Number()           │                             │       x: {                     │
│   ])                           │                             │         type: 'number'         │
│ ])                             │                             │       }                        │
│                                │                             │     }                          │
│                                │                             │   }, {                         │
│                                │                             │     type: 'object',            |
│                                │                             │     required: ['y'],           │
│                                │                             │     properties: {              │
│                                │                             │       y: {                     │
│                                │                             │         type: 'number'         │
│                                │                             │       }                        │
│                                │                             │     }                          │
│                                │                             │   }]                           │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Composite([     │ type I = {                  │ const T = {                    │
│   Type.Object({                │   x: number                 │   type: 'object',              │
│     x: Type.Number()           │ } & {                       │   required: ['x', 'y'],        │
│   }),                          │   y: number                 │   properties: {                │
│   Type.Object({                │ }                           │     x: {                       │
│     y: Type.Number()           │                             │       type: 'number'           │
│   })                           │ type T = {                  │     },                         │
│ ])                             │   [K in keyof I]: I[K]      │     y: {                       │
│                                │ }                           │       type: 'number'           │
│                                │                             │     }                          │
│                                │                             │   }                            │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Never()         │ type T = never              │ const T = {                    │
│                                │                             │   not: {}                      │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Not(            | type T = string             │ const T = {                    │
|   Type.Union([                 │                             │   allOf: [{                    │
│     Type.Literal('x'),         │                             │     not: {                     │
│     Type.Literal('y'),         │                             │       anyOf: [                 │
│     Type.Literal('z')          │                             │         { const: 'x' },        │
│   ]),                          │                             │         { const: 'y' },        │
│   Type.String()                │                             │         { const: 'z' }         │
│ )                              │                             │       ]                        │
│                                │                             │     }                          │
│                                │                             │   }, {                         │
│                                │                             │     type: 'string'             │
│                                │                             │   }]                           │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Extends(        │ type T =                    │ const T = {                    │
│   Type.String(),               │  string extends number      │   const: false,                │
│   Type.Number(),               │  true : false               │   type: 'boolean'              │
│   Type.Literal(true),          │                             │ }                              │
│   Type.Literal(false)          │                             │                                │
│ )                              │                             │                                │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Extract(        │ type T = Extract<           │ const T = {                    │
│   Type.Union([                 │   string | number,          │   type: 'string'               │
│     Type.String(),             │   string                    │ }                              │
│     Type.Number(),             │ >                           │                                │
│   ]),                          │                             │                                │
│   Type.String()                │                             │                                │
│ )                              │                             │                                │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Exclude(        │ type T = Exclude<           │ const T = {                    │
│   Type.Union([                 │   string | number,          │   type: 'number'               │
│     Type.String(),             │   string                    │ }                              │
│     Type.Number(),             │ >                           │                                │
│   ]),                          │                             │                                │
│   Type.String()                │                             │                                │
│ )                              │                             │                                │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const U = Type.Union([         │ type U = 'open' | 'close'   │ const T = {                    │
│   Type.Literal('open'),        │                             │   type: 'string',              │
│   Type.Literal('close')        │ type T = `on${U}`           │   pattern: '^on(open|close)$'  │
│ ])                             │                             │ }                              │
│                                │                             │                                │
│ const T = Type                 │                             │                                │
│   .TemplateLiteral([           │                             │                                │
│      Type.Literal('on'),       │                             │                                │
│      U                         │                             │                                │
│   ])                           │                             │                                │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Record(         │ type T = Record<            │ const T = {                    │
│   Type.String(),               │   string,                   │   type: 'object',              │
│   Type.Number()                │   number                    │   patternProperties: {         │
│ )                              │ >                           │     '^.*$': {                  │
│                                │                             │       type: 'number'           │
│                                │                             │     }                          │
│                                │                             │   }                            │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Partial(        │ type T = Partial<{          │ const T = {                    │
│   Type.Object({                │   x: number,                │   type: 'object',              │
│     x: Type.Number(),          │   y: number                 │   properties: {                │
│     y: Type.Number()           | }>                          │     x: {                       │
│   })                           │                             │       type: 'number'           │
│ )                              │                             │     },                         │
│                                │                             │     y: {                       │
│                                │                             │       type: 'number'           │
│                                │                             │     }                          │
│                                │                             │   }                            │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Required(       │ type T = Required<{         │ const T = {                    │
│   Type.Object({                │   x?: number,               │   type: 'object',              │
│     x: Type.Optional(          │   y?: number                │   required: ['x', 'y'],        │
│       Type.Number()            | }>                          │   properties: {                │
│     ),                         │                             │     x: {                       │
│     y: Type.Optional(          │                             │       type: 'number'           │
│       Type.Number()            │                             │     },                         │
│     )                          │                             │     y: {                       │
│   })                           │                             │       type: 'number'           │
│ )                              │                             │     }                          │
│                                │                             │   }                            │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Pick(           │ type T = Pick<{             │ const T = {                    │
│   Type.Object({                │   x: number,                │   type: 'object',              │
│     x: Type.Number(),          │   y: number                 │   required: ['x'],             │
│     y: Type.Number()           │ }, 'x'>                     │   properties: {                │
│   }), ['x']                    |                             │     x: {                       │
│ )                              │                             │       type: 'number'           │
│                                │                             │     }                          │
│                                │                             │   }                            │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Omit(           │ type T = Omit<{             │ const T = {                    │
│   Type.Object({                │   x: number,                │   type: 'object',              │
│     x: Type.Number(),          │   y: number                 │   required: ['y'],             │
│     y: Type.Number()           │ }, 'x'>                     │   properties: {                │
│   }), ['x']                    |                             │     y: {                       │
│ )                              │                             │       type: 'number'           │
│                                │                             │     }                          │
│                                │                             │   }                            │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Object({        │ type T = {                  │ const R = {                    │
│    x: Type.Number(),           │   x: number,                │   $ref: 'T'                    │
│    y: Type.Number()            │   y: number                 │ }                              │
│ }, { $id: 'T' })               | }                           │                                │
│                                │                             │                                │
│ const R = Type.Ref(T)          │ type R = T                  │                                │
│                                │                             │                                │
│                                │                             │                                │
│                                │                             │                                │
│                                │                             │                                │
└────────────────────────────────┴─────────────────────────────┴────────────────────────────────┘
```

<a name='types-extended'></a>

### Extended Types

TypeBox provides several extended types that can be used to produce schematics for common JavaScript constructs. These types can not be used with standard JSON schema validators; but are useful to help frame schematics for RPC interfaces that may receive JSON validated data. Extended types are prefixed with the `[Extended]` doc comment for convenience. The following table lists the supported types.

```typescript
┌────────────────────────────────┬─────────────────────────────┬────────────────────────────────┐
│ TypeBox                        │ TypeScript                  │ Extended Schema                │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Constructor([   │ type T = new (              │ const T = {                    │
│   Type.String(),               │  arg0: string,              │   type: 'object',              │
│   Type.Number()                │  arg1: number               │   instanceOf: 'Constructor',   │
│ ], Type.Boolean())             │ ) => boolean                │   parameters: [{               │
│                                │                             │     type: 'string'             │
│                                │                             │   }, {                         │
│                                │                             │     type: 'number'             │
│                                │                             │   }],                          │
│                                │                             │   return: {                    │
│                                │                             │     type: 'boolean'            │
│                                │                             │   }                            │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Function([      │ type T = (                  │ const T = {                    │
|   Type.String(),               │  arg0: string,              │   type : 'object',             │
│   Type.Number()                │  arg1: number               │   instanceOf: 'Function',      │
│ ], Type.Boolean())             │ ) => boolean                │   parameters: [{               │
│                                │                             │     type: 'string'             │
│                                │                             │   }, {                         │
│                                │                             │     type: 'number'             │
│                                │                             │   }],                          │
│                                │                             │   return: {                    │
│                                │                             │     type: 'boolean'            │
│                                │                             │   }                            │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Promise(        │ type T = Promise<string>    │ const T = {                    │
│   Type.String()                │                             │   type: 'object',              │
│ )                              │                             │   instanceOf: 'Promise',       │
│                                │                             │   item: {                      │
│                                │                             │     type: 'string'             │
│                                │                             │   }                            │
│                                │                             │ }                              │
│                                │                             │                                │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Uint8Array()    │ type T = Uint8Array         │ const T = {                    │
│                                │                             │   type: 'object',              │
│                                │                             │   instanceOf: 'Uint8Array'     │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Date()          │ type T = Date               │ const T = {                    │
│                                │                             │   type: 'object',              │
│                                │                             │   instanceOf: 'Date'           │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Undefined()     │ type T = undefined          │ const T = {                    │
│                                │                             │   type: 'null',                │
│                                │                             │   typeOf: 'Undefined'          │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.RegEx(/foo/)    │ type T = string             │ const T = {                    │
│                                │                             │    type: 'string',             │
│                                │                             │    pattern: 'foo'              │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Symbol()        │ type T = symbol             │ const T = {                    │
│                                │                             │   type: 'null',                │
│                                │                             │   typeOf: 'Symbol'             │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.BigInt()        │ type T = bigint             │ const T = {                    │
│                                │                             │   type: 'null',                │
│                                │                             │   typeOf: 'BigInt'             │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Void()          │ type T = void               │ const T = {                    │
│                                │                             │   type: 'null'                 │
│                                │                             │   typeOf: 'Void'               │
│                                │                             │ }                              │
│                                │                             │                                │
└────────────────────────────────┴─────────────────────────────┴────────────────────────────────┘
```

<a name='types-modifiers'></a>

### Modifiers

TypeBox provides modifiers that allow schema properties to be statically inferred as `readonly` or `optional`. The following table shows the supported modifiers and how they map between TypeScript and JSON Schema.

```typescript
┌────────────────────────────────┬─────────────────────────────┬────────────────────────────────┐
│ TypeBox                        │ TypeScript                  │ JSON Schema                    │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Object({        │ type T = {                  │ const T = {                    │
│   name: Type.Optional(         │   name?: string             │   type: 'object',              │
│     Type.String()              │ }                           │   properties: {                │
│   )                            │                             │     name: {                    │
│ })  	                         │                             │       type: 'string'           │
│                                │                             │     }                          │
│                                │                             │   }                            │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Object({        │ type T = {                  │ const T = {                    │
│   name: Type.Readonly(         │   readonly name: string     │   type: 'object',              │
│     Type.String()              │ }                           │   properties: {                │
│   )                            │                             │     name: {                    │
│ })  	                         │                             │       type: 'string'           │
│                                │                             │     }                          │
│                                │                             │   },                           │
│                                │                             │   required: ['name']           │
│                                │                             │ }                              │
│                                │                             │                                │
├────────────────────────────────┼─────────────────────────────┼────────────────────────────────┤
│ const T = Type.Object({        │ type T = {                  │ const T = {                    │
│   name: Type.ReadonlyOptional( │   readonly name?: string    │   type: 'object',              │
│     Type.String()              │ }                           │   properties: {                │
│   )                            │                             │     name: {                    │
│ })  	                         │                             │       type: 'string'           │
│                                │                             │     }                          │
│                                │                             │   }                            │
│                                │                             │ }                              │
│                                │                             │                                │
└────────────────────────────────┴─────────────────────────────┴────────────────────────────────┘
```

<a name='types-options'></a>

### Options

You can pass JSON Schema options on the last argument of any type. Option hints specific to each type are provided for convenience.

```typescript
// String must be an email
const T = Type.String({                              // const T = { 
  format: 'email'                                    //   type: 'string',
})                                                   //   format: 'email' 
                                                     // }

// Mumber must be a multiple of 2
const T = Type.Number({                              // const T = { 
  multipleOf: 2                                      //  type: 'number', 
})                                                   //  multipleOf: 2 
                                                     // }

// Array must have at least 5 integer values
const T = Type.Array(Type.Integer(), {               // const T = { 
  minItems: 5                                        //   type: 'array',
})                                                   //   minItems: 5,        
                                                     //   items: { 
                                                     //     type: 'integer'
                                                     //   }
                                                     // }

```

<a name='types-generics'></a>

### Generic Types

Generic types can be created with generic functions constrained to type `TSchema`. The following creates a generic `Vector<T>` type.

```typescript
import { Type, Static, TSchema } from '@sinclair/typebox'

const Vector = <T extends TSchema>(t: T) => Type.Object({ x: t, y: t, z: t })

const NumberVector = Vector(Type.Number())           // const NumberVector = {
                                                     //   type: 'object',
                                                     //   required: ['x', 'y', 'z'],
                                                     //   properties: {
                                                     //     x: { type: 'number' },
                                                     //     y: { type: 'number' },
                                                     //     z: { type: 'number' }
                                                     //   }
                                                     // }

type NumberVector = Static<typeof NumberVector>      // type NumberVector = {
                                                     //   x: number,
                                                     //   y: number,
                                                     //   z: number
                                                     // }

const BooleanVector = Vector(Type.Boolean())         // const BooleanVector = {
                                                     //   type: 'object',
                                                     //   required: ['x', 'y', 'z'],
                                                     //   properties: {
                                                     //     x: { type: 'boolean' },
                                                     //     y: { type: 'boolean' },
                                                     //     z: { type: 'boolean' }
                                                     //   }
                                                     // }

type BooleanVector = Static<typeof BooleanVector>    // type BooleanVector = {
                                                     //   x: boolean,
                                                     //   y: boolean,
                                                     //   z: boolean
                                                     // }
```

The following creates a generic `Nullable<T>` type.

```typescript
const Nullable = <T extends TSchema>(schema: T) => Type.Union([schema, Type.Null()])

const T = Nullable(Type.String())                   // const T = {
                                                    //   anyOf: [
                                                    //     { type: 'string' },
                                                    //     { type: 'null' }
                                                    //   ]
                                                    // }

type T = Static<typeof T>                           // type T = string | null
```

<a name='types-references'></a>

### Reference Types

Reference types are supported with `Type.Ref`. The target type must specify a valid `$id`.

```typescript
const T = Type.String({ $id: 'T' })                  // const T = {
                                                     //    $id: 'T',
                                                     //    type: 'string'
                                                     // }
                                             
const R = Type.Ref(T)                                // const R = {
                                                     //    $ref: 'T'
                                                     // }
```

<a name='types-recursive'></a>

### Recursive Types

Recursive types are supported with `Type.Recursive`

```typescript
const Node = Type.Recursive(Node => Type.Object({    // const Node = {
  id: Type.String(),                                 //   $id: 'Node',
  nodes: Type.Array(Node)                            //   type: 'object',
}), { $id: 'Node' })                                 //   properties: {
                                                     //     id: {
                                                     //       type: 'string'
                                                     //     },
                                                     //     nodes: {
                                                     //       type: 'array',
                                                     //       items: {
                                                     //         $ref: 'Node'
                                                     //       }
                                                     //     }
                                                     //   },
                                                     //   required: [
                                                     //     'id',
                                                     //     'nodes'
                                                     //   ]
                                                     // }

type Node = Static<typeof Node>                      // type Node = {
                                                     //   id: string
                                                     //   nodes: Node[]
                                                     // }

function test(node: Node) {
  const id = node.nodes[0].nodes[0].id               // id is string
}
```

<a name='types-conditional'></a>

### Conditional Types

Conditional types are supported with `Type.Extends`, `Type.Exclude` and `Type.Extract`

```typescript
// TypeScript

type T0 = string extends number ? true : false       // type T0 = false

type T1 = Extract<string | number, number>           // type T1 = number

type T2 = Exclude<string | number, number>           // type T2 = string

// TypeBox

const T0 = Type.Extends(Type.String(), Type.Number(), Type.Literal(true), Type.Literal(false))

const T1 = Type.Extract(Type.Union([Type.String(), Type.Number()]), Type.Number())

const T2 = Type.Exclude(Type.Union([Type.String(), Type.Number()]), Type.Number())


type T0 = Static<typeof T0>                        // type T0 = false

type T1 = Static<typeof T1>                        // type T1 = number

type T2 = Static<typeof T2>                        // type T2 = string 
```

<a name='types-template-literal'></a>

### Template Literal Types

Template Literal types are supported with `Type.TemplateLiteral`

```typescript
// TypeScript

type T = `option${'A'|'B'}`                          // type T = 'optionA' | 'optionB'

type R = Record<T, string>                           // type R = {
                                                     //   optionA: string
                                                     //   optionB: string
                                                     // }

// TypeBox

const T = Type.TemplateLiteral([                     // const T = {
  Type.Literal('option'),                            //   pattern: '^option(A|B)$',
  Type.Union([                                       //   type: 'string'
    Type.Literal('A'),                               // }
    Type.Literal('B')
  ])
])

const R = Type.Record(T, Type.String())              // const R = {
                                                     //   type: 'object',
                                                     //   required: ['optionA', 'optionB'],
                                                     //   properties: {
                                                     //     optionA: {
                                                     //       type: 'string'
                                                     //     },
                                                     //     optionB: {
                                                     //       type: 'string'
                                                     //     }
                                                     //   }
                                                     // }

type T = Static<typeof T>                            // type T = 'optionA' | 'optionB'

type R = Static<typeof R>                            // type R = {
                                                     //   optionA: string
                                                     //   optionB: string
                                                     // }
```

<a name='types-unsafe'></a>

### Unsafe

Use `Type.Unsafe` to create custom schematics with user defined inference rules.

```typescript
const T = Type.Unsafe<string>({ type: 'number' })    // const T = {
                                                     //   type: 'number'
                                                     // }

type T = Static<typeof T>                            // type T = string
```

The `Type.Unsafe` type can be useful to express specific OpenAPI schema representations.

```typescript
import { Type, Static, TSchema } from '@sinclair/typebox'

// Nullable<T>

function Nullable<T extends TSchema>(schema: T) {
  return Type.Unsafe<Static<T> | null>({ ...schema, nullable: true })
}

const T = Nullable(Type.String())                    // const T = {
                                                     //   type: 'string',
                                                     //   nullable: true
                                                     // }

type T = Static<typeof T>                            // type T = string | null

// StringEnum<string[]>

function StringEnum<T extends string[]>(values: [...T]) {
  return Type.Unsafe<T[number]>({ type: 'string', enum: values })
}

const T = StringEnum(['A', 'B', 'C'])                // const T = {
                                                     //   enum: ['A', 'B', 'C']
                                                     // }

type T = Static<typeof T>                            // type T = 'A' | 'B' | 'C'
```

<a name='types-guards'></a>

### Guards

TypeBox provides a `TypeGuard` module that can be used for reflection and asserting values as types.

```typescript
import { Type, TypeGuard } from '@sinclair/typebox'

const T = Type.String()

if(TypeGuard.TString(T)) {
    
  // T is TString
}
```

<a name='types-strict'></a>

### Strict

TypeBox schemas contain the `Kind` and `Modifier` symbol properties. These properties are used for type composition and reflection. These properties are not strictly valid JSON schema; so in some cases it may be desirable to omit them. TypeBox provides a `Type.Strict` function that will omit these properties if necessary.

```typescript
const T = Type.Object({                              // const T = {
  name: Type.Optional(Type.String())                 //   [Kind]: 'Object',
})                                                   //   type: 'object',
                                                     //   properties: {
                                                     //     name: {
                                                     //       [Kind]: 'String',
                                                     //       type: 'string',
                                                     //       [Modifier]: 'Optional'
                                                     //     }
                                                     //   }
                                                     // }

const U = Type.Strict(T)                             // const U = {
                                                     //   type: 'object', 
                                                     //   properties: { 
                                                     //     name: { 
                                                     //       type: 'string' 
                                                     //     } 
                                                     //   } 
                                                     // }
```

<a name='values'></a>

## Values

TypeBox provides an optional utility module that can be used to perform common operations on JavaScript values. This module includes functionality to create, check and cast values from types as well as check equality, clone, diff and patch JavaScript values. This module is provided via optional import.

```typescript
import { Value } from '@sinclair/typebox/value'
```

<a name='values-create'></a>

### Create

Use the Create function to create a value from a type. TypeBox will use default values if specified.

```typescript
const T = Type.Object({ x: Type.Number(), y: Type.Number({ default: 42 }) })

const A = Value.Create(T)                            // const A = { x: 0, y: 42 }
```

<a name='values-clone'></a>

### Clone

Use the Clone function to deeply clone a value

```typescript
const A = Value.Clone({ x: 1, y: 2, z: 3 })          // const A = { x: 1, y: 2, z: 3 }
```

<a name='values-check'></a>

### Check

Use the Check function to type check a value

```typescript
const T = Type.Object({ x: Type.Number() })

const R = Value.Check(T, { x: 1 })                   // const R = true
```

<a name='values-convert'></a>

### Convert

Use the Convert function to convert a value into its target type if a reasonable conversion is possible.

```typescript
const T = Type.Object({ x: Type.Number() })

const R1 = Value.Convert(T, { x: '3.14' })          // const R1 = { x: 3.14 }

const R2 = Value.Convert(T, { x: 'not a number' })  // const R2 = { x: 'not a number' }
```

<a name='values-cast'></a>

### Cast

Use the Cast function to cast a value into a type. The cast function will retain as much information as possible from the original value.

```typescript
const T = Type.Object({ x: Type.Number(), y: Type.Number() }, { additionalProperties: false })

const X = Value.Cast(T, null)                        // const X = { x: 0, y: 0 }

const Y = Value.Cast(T, { x: 1 })                    // const Y = { x: 1, y: 0 }

const Z = Value.Cast(T, { x: 1, y: 2, z: 3 })        // const Z = { x: 1, y: 2 }
```

<a name='values-equal'></a>

### Equal

Use the Equal function to deeply check for value equality.

```typescript
const R = Value.Equal(                               // const R = true
  { x: 1, y: 2, z: 3 },
  { x: 1, y: 2, z: 3 }
)
```

<a name='values-hash'></a>

### Hash

Use the Hash function to create a [FNV1A-64](https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function) non cryptographic hash of a value.

```typescript
const A = Value.Hash({ x: 1, y: 2, z: 3 })          // const A = 2910466848807138541n

const B = Value.Hash({ x: 1, y: 4, z: 3 })          // const B = 1418369778807423581n
```

<a name='values-diff'></a>

### Diff

Use the Diff function to produce a sequence of edits to transform one value into another.

```typescript
const E = Value.Diff(                               // const E = [
  { x: 1, y: 2, z: 3 },                             //   { type: 'update', path: '/y', value: 4 },
  { y: 4, z: 5, w: 6 }                              //   { type: 'update', path: '/z', value: 5 },
)                                                   //   { type: 'insert', path: '/w', value: 6 },
                                                    //   { type: 'delete', path: '/x' }
                                                    // ]
```

<a name='values-patch'></a>

### Patch

Use the Patch function to apply edits

```typescript
const A = { x: 1, y: 2 }

const B = { x: 3 }

const E = Value.Diff(A, B)                           // const E = [
                                                     //   { type: 'update', path: '/x', value: 3 },
                                                     //   { type: 'delete', path: '/y' }
                                                     // ]

const C = Value.Patch<typeof B>(A, E)                // const C = { x: 3 }
```

<a name='values-errors'></a>

### Errors

Use the Errors function enumerate validation errors.

```typescript
const T = Type.Object({ x: Type.Number(), y: Type.Number() })

const R = [...Value.Errors(T, { x: '42' })]          // const R = [{
                                                     //   schema: { type: 'number' },
                                                     //   path: '/x',
                                                     //   value: '42',
                                                     //   message: 'Expected number'
                                                     // }, {
                                                     //   schema: { type: 'number' },
                                                     //   path: '/y',
                                                     //   value: undefined,
                                                     //   message: 'Expected number'
                                                     // }]
```

<a name='values-mutate'></a>

### Mutate

Use the Mutate function to perform a deep mutable value assignment while retaining internal references.

```typescript
const Y = { z: 1 }                                   // const Y = { z: 1 } 

const X = { y: Y }                                   // const X = { y: { z: 1 } }

const A = { x: X }                                   // const A = { x: { y: { z: 1 } } }             


Value.Mutate(A, { x: { y: { z: 2 } } })              // const A' = { x: { y: { z: 2 } } }   

const R0 = A.x.y.z === 2                             // const R0 = 2

const R1 = A.x.y === Y                               // const R1 = true

const R2 = A.x === X                                 // const R2 = true
```     

<a name='values-pointer'></a>

### Pointer

Use ValuePointer to perform mutable updates on existing values using [RFC6901](https://www.rfc-editor.org/rfc/rfc6901) JSON Pointers.

```typescript
import { ValuePointer } from '@sinclair/typebox/value'

const A = { x: 0, y: 0, z: 0 }

ValuePointer.Set(A, '/x', 1)                         // const A' = { x: 1, y: 0, z: 0 }

ValuePointer.Set(A, '/y', 1)                         // const A' = { x: 1, y: 1, z: 0 }

ValuePointer.Set(A, '/z', 1)                         // const A' = { x: 1, y: 1, z: 1 }
```

<a name='typecheck'></a>

## TypeCheck

TypeBox types target JSON Schema draft 6 so are compatible with any validator that supports this specification. TypeBox also provides a built in type checking compiler designed specifically for high performance compilation and value assertion.

The following sections detail using Ajv and TypeBox's compiler infrastructure.

<a name='typecheck-ajv'></a>

## Ajv

The following shows the recommended setup for Ajv.

```bash
$ npm install ajv ajv-formats --save
```

```typescript
import { Type }   from '@sinclair/typebox'
import addFormats from 'ajv-formats'
import Ajv        from 'ajv'

const ajv = addFormats(new Ajv({}), [
  'date-time', 
  'time', 
  'date', 
  'email',  
  'hostname', 
  'ipv4', 
  'ipv6', 
  'uri', 
  'uri-reference', 
  'uuid',
  'uri-template', 
  'json-pointer', 
  'relative-json-pointer', 
  'regex'
])

const C = ajv.compile(Type.Object({                
  x: Type.Number(),
  y: Type.Number(),
  z: Type.Number()
}))

const R = C({ x: 1, y: 2, z: 3 })                    // const R = true 
```

<a name='typecheck-typecompiler'></a>

### TypeCompiler

The TypeBox TypeCompiler is a high performance JIT compiler that transforms TypeBox types into optimized JavaScript validation routines. The compiler is tuned for fast compilation as well as fast value assertion. It is designed to serve as a validation backend that can be integrated into larger applications; but can also be used as a general purpose validator.

The TypeCompiler is provided as an optional import.

```typescript
import { TypeCompiler } from '@sinclair/typebox/compiler'
```

Use the `Compile(...)` function to compile a type.

```typescript
const C = TypeCompiler.Compile(Type.Object({         // const C: TypeCheck<TObject<{
  x: Type.Number(),                                  //     x: TNumber;
  y: Type.Number(),                                  //     y: TNumber;
  z: Type.Number()                                   //     z: TNumber;
}))                                                  // }>>

const R = C.Check({ x: 1, y: 2, z: 3 })              // const R = true
```

Use the `Errors(...)` function to produce diagnostic errors for a value. The `Errors(...)` function will return an iterator that if enumerated; will perform an exhaustive check across the entire value and yield any error found. For performance, this function should only be called after failed `Check(...)`. Applications may also choose to yield only the first value to avoid exhaustive error generation.

```typescript
const C = TypeCompiler.Compile(Type.Object({         // const C: TypeCheck<TObject<{
  x: Type.Number(),                                  //     x: TNumber;
  y: Type.Number(),                                  //     y: TNumber;
  z: Type.Number()                                   //     z: TNumber;
}))                                                  // }>>

const value = { }

const errors = [...C.Errors(value)]                  // const errors = [{
                                                     //   schema: { type: 'number' },
                                                     //   path: '/x',
                                                     //   value: undefined,
                                                     //   message: 'Expected number'
                                                     // }, {
                                                     //   schema: { type: 'number' },
                                                     //   path: '/y',
                                                     //   value: undefined,
                                                     //   message: 'Expected number'
                                                     // }, {
                                                     //   schema: { type: 'number' },
                                                     //   path: '/z',
                                                     //   value: undefined,
                                                     //   message: 'Expected number'
                                                     // }]
```

Compiled routines can be inspected with the `.Code()` function.

```typescript
const C = TypeCompiler.Compile(Type.String())        // const C: TypeCheck<TString>

console.log(C.Code())                                // return function check(value) {
                                                     //   return (
                                                     //     (typeof value === 'string')
                                                     //   )
                                                     // }
```

<a name='typesystem'></a>

## TypeSystem

The TypeBox TypeSystem module provides functionality to define types above and beyond the Standard and Extended type sets as well as control various assertion polices. Configurations made to the TypeSystem module are observed by both `TypeCompiler` and `Value` modules.

The TypeSystem module is provided as an optional import.

```typescript
import { TypeSystem } from '@sinclair/typebox/system'
```

<a name='typesystem-types'></a>

### Types

Use the `Type(...)` function to create a custom type. This function will return a type factory function that can be used to construct the type. The following creates a Point type.

```typescript
type PointOptions = { }                              // The Type Options

type PointType = { x: number, y: number }            // The Static<T> Type

const Point = TypeSystem.Type<PointType, PointOptions>('Point', (options, value) => {
  return (
    typeof value === 'object' && value !== null &&
    typeof value.x === 'number' && 
    typeof value.y === 'number'
  )
})

const T = Point()

type T = Static<typeof T>                             // type T = { x: number, y: number }

const R = Value.Check(T, { x: 1, y: 2 })              // const R = true
```

<a name='typesystem-formats'></a>

### Formats

Use the `Format(...)` function to create a custom string format. The following creates a format that checks for lowercase strings.

```typescript
TypeSystem.Format('lowercase', value => value === value.toLowerCase()) // format should be lowercase

const T = Type.String({ format: 'lowercase' })       

const A = Value.Check(T, 'Hello')                    // const A = false

const B = Value.Check(T, 'hello')                    // const B = true
```

<a name='typesystem-policies'></a>

### Policies

TypeBox validates using JSON Schema assertion policies by default. It is possible to override these policies and have TypeBox assert using TypeScript policies. The following overrides are available.

```typescript
// Allow arrays to validate as object types (default is false)
//
// const A: {} = [] - allowed in TS

TypeSystem.AllowArrayObjects = true                  

// Allow numeric values to be NaN or + or - Infinity (default is false)
//
// const A: number = NaN - allowed in TS

TypeSystem.AllowNaN = true                      
```

<a name='benchmark'></a>

## Benchmark

This project maintains a set of benchmarks that measure Ajv, Value and TypeCompiler compilation and validation performance. These benchmarks can be run locally by cloning this repository and running `npm run benchmark`. The results below show for Ajv version 8.12.0. 

For additional comparative benchmarks, please refer to [typescript-runtime-type-benchmarks](https://moltar.github.io/typescript-runtime-type-benchmarks/).

<a name='benchmark-compile'></a>

### Compile

This benchmark measures compilation performance for varying types. You can review this benchmark [here](https://github.com/sinclairzx81/typebox/blob/master/benchmark/measurement/module/compile.ts).

```typescript
┌────────────────────────────┬────────────┬──────────────┬──────────────┬──────────────┐
│          (index)           │ Iterations │     Ajv      │ TypeCompiler │ Performance  │
├────────────────────────────┼────────────┼──────────────┼──────────────┼──────────────┤
│ Literal_String             │    1000    │ '    257 ms' │ '      8 ms' │ '   32.13 x' │
│ Literal_Number             │    1000    │ '    203 ms' │ '      4 ms' │ '   50.75 x' │
│ Literal_Boolean            │    1000    │ '    183 ms' │ '      4 ms' │ '   45.75 x' │
│ Primitive_Number           │    1000    │ '    174 ms' │ '      8 ms' │ '   21.75 x' │
│ Primitive_String           │    1000    │ '    158 ms' │ '      9 ms' │ '   17.56 x' │
│ Primitive_String_Pattern   │    1000    │ '    213 ms' │ '     13 ms' │ '   16.38 x' │
│ Primitive_Boolean          │    1000    │ '    136 ms' │ '      6 ms' │ '   22.67 x' │
│ Primitive_Null             │    1000    │ '    144 ms' │ '      6 ms' │ '   24.00 x' │
│ Object_Unconstrained       │    1000    │ '   1176 ms' │ '     38 ms' │ '   30.95 x' │
│ Object_Constrained         │    1000    │ '   1181 ms' │ '     31 ms' │ '   38.10 x' │
│ Object_Vector3             │    1000    │ '    387 ms' │ '      8 ms' │ '   48.38 x' │
│ Object_Box3D               │    1000    │ '   1693 ms' │ '     25 ms' │ '   67.72 x' │
│ Tuple_Primitive            │    1000    │ '    470 ms' │ '     15 ms' │ '   31.33 x' │
│ Tuple_Object               │    1000    │ '   1206 ms' │ '     17 ms' │ '   70.94 x' │
│ Composite_Intersect        │    1000    │ '    567 ms' │ '     20 ms' │ '   28.35 x' │
│ Composite_Union            │    1000    │ '    515 ms' │ '     21 ms' │ '   24.52 x' │
│ Math_Vector4               │    1000    │ '    787 ms' │ '     10 ms' │ '   78.70 x' │
│ Math_Matrix4               │    1000    │ '    386 ms' │ '      8 ms' │ '   48.25 x' │
│ Array_Primitive_Number     │    1000    │ '    349 ms' │ '      7 ms' │ '   49.86 x' │
│ Array_Primitive_String     │    1000    │ '    336 ms' │ '      4 ms' │ '   84.00 x' │
│ Array_Primitive_Boolean    │    1000    │ '    284 ms' │ '      3 ms' │ '   94.67 x' │
│ Array_Object_Unconstrained │    1000    │ '   1704 ms' │ '     19 ms' │ '   89.68 x' │
│ Array_Object_Constrained   │    1000    │ '   1456 ms' │ '     18 ms' │ '   80.89 x' │
│ Array_Tuple_Primitive      │    1000    │ '    792 ms' │ '     15 ms' │ '   52.80 x' │
│ Array_Tuple_Object         │    1000    │ '   1552 ms' │ '     17 ms' │ '   91.29 x' │
│ Array_Composite_Intersect  │    1000    │ '    744 ms' │ '     18 ms' │ '   41.33 x' │
│ Array_Composite_Union      │    1000    │ '    783 ms' │ '     15 ms' │ '   52.20 x' │
│ Array_Math_Vector4         │    1000    │ '   1093 ms' │ '     14 ms' │ '   78.07 x' │
│ Array_Math_Matrix4         │    1000    │ '    684 ms' │ '      6 ms' │ '  114.00 x' │
└────────────────────────────┴────────────┴──────────────┴──────────────┴──────────────┘
```

<a name='benchmark-validate'></a>

### Validate

This benchmark measures validation performance for varying types. You can review this benchmark [here](https://github.com/sinclairzx81/typebox/blob/master/benchmark/measurement/module/check.ts).

```typescript
┌────────────────────────────┬────────────┬──────────────┬──────────────┬──────────────┬──────────────┐
│          (index)           │ Iterations │  ValueCheck  │     Ajv      │ TypeCompiler │ Performance  │
├────────────────────────────┼────────────┼──────────────┼──────────────┼──────────────┼──────────────┤
│ Literal_String             │  1000000   │ '     27 ms' │ '      6 ms' │ '      5 ms' │ '    1.20 x' │
│ Literal_Number             │  1000000   │ '     23 ms' │ '     21 ms' │ '     11 ms' │ '    1.91 x' │
│ Literal_Boolean            │  1000000   │ '     21 ms' │ '     20 ms' │ '     10 ms' │ '    2.00 x' │
│ Primitive_Number           │  1000000   │ '     26 ms' │ '     19 ms' │ '     11 ms' │ '    1.73 x' │
│ Primitive_String           │  1000000   │ '     25 ms' │ '     19 ms' │ '     10 ms' │ '    1.90 x' │
│ Primitive_String_Pattern   │  1000000   │ '    155 ms' │ '     49 ms' │ '     43 ms' │ '    1.14 x' │
│ Primitive_Boolean          │  1000000   │ '     23 ms' │ '     19 ms' │ '     10 ms' │ '    1.90 x' │
│ Primitive_Null             │  1000000   │ '     24 ms' │ '     19 ms' │ '     10 ms' │ '    1.90 x' │
│ Object_Unconstrained       │  1000000   │ '    804 ms' │ '     35 ms' │ '     28 ms' │ '    1.25 x' │
│ Object_Constrained         │  1000000   │ '   1041 ms' │ '     55 ms' │ '     41 ms' │ '    1.34 x' │
│ Object_Vector3             │  1000000   │ '    380 ms' │ '     26 ms' │ '     20 ms' │ '    1.30 x' │
│ Object_Box3D               │  1000000   │ '   1785 ms' │ '     65 ms' │ '     52 ms' │ '    1.25 x' │
│ Object_Recursive           │  1000000   │ '   4984 ms' │ '    396 ms' │ '    114 ms' │ '    3.47 x' │
│ Tuple_Primitive            │  1000000   │ '    168 ms' │ '     24 ms' │ '     16 ms' │ '    1.50 x' │
│ Tuple_Object               │  1000000   │ '    673 ms' │ '     30 ms' │ '     26 ms' │ '    1.15 x' │
│ Composite_Intersect        │  1000000   │ '    751 ms' │ '     28 ms' │ '     20 ms' │ '    1.40 x' │
│ Composite_Union            │  1000000   │ '    489 ms' │ '     24 ms' │ '     16 ms' │ '    1.50 x' │
│ Math_Vector4               │  1000000   │ '    259 ms' │ '     23 ms' │ '     13 ms' │ '    1.77 x' │
│ Math_Matrix4               │  1000000   │ '   1002 ms' │ '     40 ms' │ '     30 ms' │ '    1.33 x' │
│ Array_Primitive_Number     │  1000000   │ '    252 ms' │ '     22 ms' │ '     15 ms' │ '    1.47 x' │
│ Array_Primitive_String     │  1000000   │ '    227 ms' │ '     22 ms' │ '     18 ms' │ '    1.22 x' │
│ Array_Primitive_Boolean    │  1000000   │ '    150 ms' │ '     23 ms' │ '     22 ms' │ '    1.05 x' │
│ Array_Object_Unconstrained │  1000000   │ '   4754 ms' │ '     71 ms' │ '     64 ms' │ '    1.11 x' │
│ Array_Object_Constrained   │  1000000   │ '   4787 ms' │ '    142 ms' │ '    123 ms' │ '    1.15 x' │
│ Array_Object_Recursive     │  1000000   │ '  19088 ms' │ '   1735 ms' │ '    314 ms' │ '    5.53 x' │
│ Array_Tuple_Primitive      │  1000000   │ '    650 ms' │ '     41 ms' │ '     31 ms' │ '    1.32 x' │
│ Array_Tuple_Object         │  1000000   │ '   2770 ms' │ '     67 ms' │ '     55 ms' │ '    1.22 x' │
│ Array_Composite_Intersect  │  1000000   │ '   2693 ms' │ '     50 ms' │ '     39 ms' │ '    1.28 x' │
│ Array_Composite_Union      │  1000000   │ '   1982 ms' │ '     72 ms' │ '     33 ms' │ '    2.18 x' │
│ Array_Math_Vector4         │  1000000   │ '   1068 ms' │ '     40 ms' │ '     26 ms' │ '    1.54 x' │
│ Array_Math_Matrix4         │  1000000   │ '   4609 ms' │ '    115 ms' │ '     88 ms' │ '    1.31 x' │
└────────────────────────────┴────────────┴──────────────┴──────────────┴──────────────┴──────────────┘
```

<a name='benchmark-compression'></a>

### Compression

The following table lists esbuild compiled and minified sizes for each TypeBox module.

```typescript
┌──────────────────────┬────────────┬────────────┬─────────────┐
│       (index)        │  Compiled  │  Minified  │ Compression │
├──────────────────────┼────────────┼────────────┼─────────────┤
│ typebox/compiler     │ '124.3 kb' │ ' 55.7 kb' │  '2.23 x'   │
│ typebox/errors       │ '107.8 kb' │ ' 47.9 kb' │  '2.25 x'   │
│ typebox/system       │ ' 73.3 kb' │ ' 30.2 kb' │  '2.43 x'   │
│ typebox/value        │ '170.7 kb' │ ' 74.2 kb' │  '2.30 x'   │
│ typebox              │ ' 72.0 kb' │ ' 29.7 kb' │  '2.43 x'   │
└──────────────────────┴────────────┴────────────┴─────────────┘
```

<a name='contribute'></a>

## Contribute

TypeBox is open to community contribution. Please ensure you submit an open issue before submitting your pull request. The TypeBox project preferences open community discussion prior to accepting new features.


---

# is

> Type check values

For example, `is.string('🦄') //=> true`

<img src="header.gif" width="182" align="right">

## Highlights

- Written in TypeScript
- [Extensive use of type guards](#type-guards)
- [Supports type assertions](#type-assertions)
- [Aware of generic type parameters](#generic-type-parameters) (use with caution)
- Actively maintained
- ![Millions of downloads per week](https://img.shields.io/npm/dw/@sindresorhus/is)

## Install

```sh
npm install @sindresorhus/is
```

## Usage

```js
const is = require('@sindresorhus/is');

is('🦄');
//=> 'string'

is(new Map());
//=> 'Map'

is.number(6);
//=> true
```

[Assertions](#type-assertions) perform the same type checks, but throw an error if the type does not match.

```js
const {assert} = require('@sindresorhus/is');

assert.string(2);
//=> Error: Expected value which is `string`, received value of type `number`.
```

And with TypeScript:

```ts
import {assert} from '@sindresorhus/is';

assert.string(foo);
// `foo` is now typed as a `string`.
```

## API

### is(value)

Returns the type of `value`.

Primitives are lowercase and object types are camelcase.

Example:

- `'undefined'`
- `'null'`
- `'string'`
- `'symbol'`
- `'Array'`
- `'Function'`
- `'Object'`

Note: It will throw an error if you try to feed it object-wrapped primitives, as that's a bad practice. For example `new String('foo')`.

### is.{method}

All the below methods accept a value and returns a boolean for whether the value is of the desired type.

#### Primitives

##### .undefined(value)
##### .null(value)

**Note:** TypeScript users must use `.null_()` because of a TypeScript naming limitation.

##### .string(value)
##### .number(value)

Note: `is.number(NaN)` returns `false`. This intentionally deviates from `typeof` behavior to increase user-friendliness of `is` type checks.

##### .boolean(value)
##### .symbol(value)
##### .bigint(value)

#### Built-in types

##### .array(value, assertion?)

Returns true if `value` is an array and all of its items match the assertion (if provided).

```js
is.array(value); // Validate `value` is an array.
is.array(value, is.number); // Validate `value` is an array and all of its items are numbers.
```

##### .function(value)

**Note:** TypeScript users must use `.function_()` because of a TypeScript naming limitation.

##### .buffer(value)
##### .blob(value)
##### .object(value)

Keep in mind that [functions are objects too](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions).

##### .numericString(value)

Returns `true` for a string that represents a number satisfying `is.number`, for example, `'42'` and `'-8.3'`.

Note: `'NaN'` returns `false`, but `'Infinity'` and `'-Infinity'` return `true`.

##### .regExp(value)
##### .date(value)
##### .error(value)
##### .nativePromise(value)
##### .promise(value)

Returns `true` for any object with a `.then()` and `.catch()` method. Prefer this one over `.nativePromise()` as you usually want to allow userland promise implementations too.

##### .generator(value)

Returns `true` for any object that implements its own `.next()` and `.throw()` methods and has a function definition for `Symbol.iterator`.

##### .generatorFunction(value)

##### .asyncFunction(value)

Returns `true` for any `async` function that can be called with the `await` operator.

```js
is.asyncFunction(async () => {});
//=> true

is.asyncFunction(() => {});
//=> false
```

##### .asyncGenerator(value)

```js
is.asyncGenerator(
	(async function * () {
		yield 4;
	})()
);
//=> true

is.asyncGenerator(
	(function * () {
		yield 4;
	})()
);
//=> false
```

##### .asyncGeneratorFunction(value)

```js
is.asyncGeneratorFunction(async function * () {
	yield 4;
});
//=> true

is.asyncGeneratorFunction(function * () {
	yield 4;
});
//=> false
```

##### .boundFunction(value)

Returns `true` for any `bound` function.

```js
is.boundFunction(() => {});
//=> true

is.boundFunction(function () {}.bind(null));
//=> true

is.boundFunction(function () {});
//=> false
```

##### .map(value)
##### .set(value)
##### .weakMap(value)
##### .weakSet(value)

#### Typed arrays

##### .int8Array(value)
##### .uint8Array(value)
##### .uint8ClampedArray(value)
##### .int16Array(value)
##### .uint16Array(value)
##### .int32Array(value)
##### .uint32Array(value)
##### .float32Array(value)
##### .float64Array(value)
##### .bigInt64Array(value)
##### .bigUint64Array(value)

#### Structured data

##### .arrayBuffer(value)
##### .sharedArrayBuffer(value)
##### .dataView(value)

##### .enumCase(value, enum)

TypeScript-only. Returns `true` if `value` is a member of `enum`.

```ts
enum Direction {
	Ascending = 'ascending',
	Descending = 'descending'
}

is.enumCase('ascending', Direction);
//=> true

is.enumCase('other', Direction);
//=> false
```

#### Emptiness

##### .emptyString(value)

Returns `true` if the value is a `string` and the `.length` is 0.

##### .emptyStringOrWhitespace(value)

Returns `true` if `is.emptyString(value)` or if it's a `string` that is all whitespace.

##### .nonEmptyString(value)

Returns `true` if the value is a `string` and the `.length` is more than 0.

##### .nonEmptyStringAndNotWhitespace(value)

Returns `true` if the value is a `string` that is not empty and not whitespace.

```js
const values = ['property1', '', null, 'property2', '    ', undefined];

values.filter(is.nonEmptyStringAndNotWhitespace);
//=> ['property1', 'property2']
```

##### .emptyArray(value)

Returns `true` if the value is an `Array` and the `.length` is 0.

##### .nonEmptyArray(value)

Returns `true` if the value is an `Array` and the `.length` is more than 0.

##### .emptyObject(value)

Returns `true` if the value is an `Object` and `Object.keys(value).length` is 0.

Please note that `Object.keys` returns only own enumerable properties. Hence something like this can happen:

```js
const object1 = {};

Object.defineProperty(object1, 'property1', {
	value: 42,
	writable: true,
	enumerable: false,
	configurable: true
});

is.emptyObject(object1);
//=> true
```

##### .nonEmptyObject(value)

Returns `true` if the value is an `Object` and `Object.keys(value).length` is more than 0.

##### .emptySet(value)

Returns `true` if the value is a `Set` and the `.size` is 0.

##### .nonEmptySet(Value)

Returns `true` if the value is a `Set` and the `.size` is more than 0.

##### .emptyMap(value)

Returns `true` if the value is a `Map` and the `.size` is 0.

##### .nonEmptyMap(value)

Returns `true` if the value is a `Map` and the `.size` is more than 0.

#### Miscellaneous

##### .directInstanceOf(value, class)

Returns `true` if `value` is a direct instance of `class`.

```js
is.directInstanceOf(new Error(), Error);
//=> true

class UnicornError extends Error {}

is.directInstanceOf(new UnicornError(), Error);
//=> false
```

##### .urlInstance(value)

Returns `true` if `value` is an instance of the [`URL` class](https://developer.mozilla.org/en-US/docs/Web/API/URL).

```js
const url = new URL('https://example.com');

is.urlInstance(url);
//=> true
```

##### .urlString(value)

Returns `true` if `value` is a URL string.

Note: this only does basic checking using the [`URL` class](https://developer.mozilla.org/en-US/docs/Web/API/URL) constructor.

```js
const url = 'https://example.com';

is.urlString(url);
//=> true

is.urlString(new URL(url));
//=> false
```

##### .truthy(value)

Returns `true` for all values that evaluate to true in a boolean context:

```js
is.truthy('🦄');
//=> true

is.truthy(undefined);
//=> false
```

##### .falsy(value)

Returns `true` if `value` is one of: `false`, `0`, `''`, `null`, `undefined`, `NaN`.

##### .nan(value)
##### .nullOrUndefined(value)
##### .primitive(value)

JavaScript primitives are as follows: `null`, `undefined`, `string`, `number`, `boolean`, `symbol`.

##### .integer(value)

##### .safeInteger(value)

Returns `true` if `value` is a [safe integer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isSafeInteger).

##### .plainObject(value)

An object is plain if it's created by either `{}`, `new Object()`, or `Object.create(null)`.

##### .iterable(value)
##### .asyncIterable(value)
##### .class(value)

Returns `true` for instances created by a class.

**Note:** TypeScript users must use `.class_()` because of a TypeScript naming limitation.

##### .typedArray(value)

##### .arrayLike(value)

A `value` is array-like if it is not a function and has a `value.length` that is a safe integer greater than or equal to 0.

```js
is.arrayLike(document.forms);
//=> true

function foo() {
	is.arrayLike(arguments);
	//=> true
}
foo();
```

##### .inRange(value, range)

Check if `value` (number) is in the given `range`. The range is an array of two values, lower bound and upper bound, in no specific order.

```js
is.inRange(3, [0, 5]);
is.inRange(3, [5, 0]);
is.inRange(0, [-2, 2]);
```

##### .inRange(value, upperBound)

Check if `value` (number) is in the range of `0` to `upperBound`.

```js
is.inRange(3, 10);
```

##### .domElement(value)

Returns `true` if `value` is a DOM Element.

##### .nodeStream(value)

Returns `true` if `value` is a Node.js [stream](https://nodejs.org/api/stream.html).

```js
const fs = require('fs');

is.nodeStream(fs.createReadStream('unicorn.png'));
//=> true
```

##### .observable(value)

Returns `true` if `value` is an `Observable`.

```js
const {Observable} = require('rxjs');

is.observable(new Observable());
//=> true
```

##### .infinite(value)

Check if `value` is `Infinity` or `-Infinity`.

##### .evenInteger(value)

Returns `true` if `value` is an even integer.

##### .oddInteger(value)

Returns `true` if `value` is an odd integer.

##### .propertyKey(value)

Returns `true` if `value` can be used as an object property key (either `string`, `number`, or `symbol`).

##### .formData(value)

Returns `true` if `value` is an instance of the [`FormData` class](https://developer.mozilla.org/en-US/docs/Web/API/FormData).

```js
const data = new FormData();

is.formData(data);
//=> true
```

##### .urlSearchParams(value)

Returns `true` if `value` is an instance of the [`URLSearchParams` class](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams).

```js
const searchParams = new URLSearchParams();

is.urlSearchParams(searchParams);
//=> true
```

##### .any(predicate | predicate[], ...values)

Using a single `predicate` argument, returns `true` if **any** of the input `values` returns true in the `predicate`:

```js
is.any(is.string, {}, true, '🦄');
//=> true

is.any(is.boolean, 'unicorns', [], new Map());
//=> false
```

Using an array of `predicate[]`, returns `true` if **any** of the input `values` returns true for **any** of the `predicates` provided in an array:

```js
is.any([is.string, is.number], {}, true, '🦄');
//=> true

is.any([is.boolean, is.number], 'unicorns', [], new Map());
//=> false
```

##### .all(predicate, ...values)

Returns `true` if **all** of the input `values` returns true in the `predicate`:

```js
is.all(is.object, {}, new Map(), new Set());
//=> true

is.all(is.string, '🦄', [], 'unicorns');
//=> false
```

## Type guards

When using `is` together with TypeScript, [type guards](http://www.typescriptlang.org/docs/handbook/advanced-types.html#type-guards-and-differentiating-types) are being used extensively to infer the correct type inside if-else statements.

```ts
import is from '@sindresorhus/is';

const padLeft = (value: string, padding: string | number) => {
	if (is.number(padding)) {
		// `padding` is typed as `number`
		return Array(padding + 1).join(' ') + value;
	}

	if (is.string(padding)) {
		// `padding` is typed as `string`
		return padding + value;
	}

	throw new TypeError(`Expected 'padding' to be of type 'string' or 'number', got '${is(padding)}'.`);
}

padLeft('🦄', 3);
//=> '   🦄'

padLeft('🦄', '🌈');
//=> '🌈🦄'
```

## Type assertions

The type guards are also available as [type assertions](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions), which throw an error for unexpected types. It is a convenient one-line version of the often repetitive "if-not-expected-type-throw" pattern.

```ts
import {assert} from '@sindresorhus/is';

const handleMovieRatingApiResponse = (response: unknown) => {
	assert.plainObject(response);
	// `response` is now typed as a plain `object` with `unknown` properties.

	assert.number(response.rating);
	// `response.rating` is now typed as a `number`.

	assert.string(response.title);
	// `response.title` is now typed as a `string`.

	return `${response.title} (${response.rating * 10})`;
};

handleMovieRatingApiResponse({rating: 0.87, title: 'The Matrix'});
//=> 'The Matrix (8.7)'

// This throws an error.
handleMovieRatingApiResponse({rating: '🦄'});
```

## Generic type parameters

The type guards and type assertions are aware of [generic type parameters](https://www.typescriptlang.org/docs/handbook/generics.html), such as `Promise<T>` and `Map<Key, Value>`. The default is `unknown` for most cases, since `is` cannot check them at runtime. If the generic type is known at compile-time, either implicitly (inferred) or explicitly (provided), `is` propagates the type so it can be used later.

Use generic type parameters with caution. They are only checked by the TypeScript compiler, and not checked by `is` at runtime. This can lead to unexpected behavior, where the generic type is _assumed_ at compile-time, but actually is something completely different at runtime. It is best to use `unknown` (default) and type-check the value of the generic type parameter at runtime with `is` or `assert`.

```ts
import {assert} from '@sindresorhus/is';

async function badNumberAssumption(input: unknown) {
	// Bad assumption about the generic type parameter fools the compile-time type system.
	assert.promise<number>(input);
	// `input` is a `Promise` but only assumed to be `Promise<number>`.

	const resolved = await input;
	// `resolved` is typed as `number` but was not actually checked at runtime.

	// Multiplication will return NaN if the input promise did not actually contain a number.
	return 2 * resolved;
}

async function goodNumberAssertion(input: unknown) {
	assert.promise(input);
	// `input` is typed as `Promise<unknown>`

	const resolved = await input;
	// `resolved` is typed as `unknown`

	assert.number(resolved);
	// `resolved` is typed as `number`

	// Uses runtime checks so only numbers will reach the multiplication.
	return 2 * resolved;
}

badNumberAssumption(Promise.resolve('An unexpected string'));
//=> NaN

// This correctly throws an error because of the unexpected string value.
goodNumberAssertion(Promise.resolve('An unexpected string'));
```

## FAQ

### Why yet another type checking module?

There are hundreds of type checking modules on npm, unfortunately, I couldn't find any that fit my needs:

- Includes both type methods and ability to get the type
- Types of primitives returned as lowercase and object types as camelcase
- Covers all built-ins
- Unsurprising behavior
- Well-maintained
- Comprehensive test suite

For the ones I found, pick 3 of these.

The most common mistakes I noticed in these modules was using `instanceof` for type checking, forgetting that functions are objects, and omitting `symbol` as a primitive.

### Why not just use `instanceof` instead of this package?

`instanceof` does not work correctly for all types and it does not work across [realms](https://stackoverflow.com/a/49832343/64949). Examples of realms are iframes, windows, web workers, and the `vm` module in Node.js.

## For enterprise

Available as part of the Tidelift Subscription.

The maintainers of @sindresorhus/is and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-sindresorhus-is?utm_source=npm-sindresorhus-is&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)

## Related

- [ow](https://github.com/sindresorhus/ow) - Function argument validation for humans
- [is-stream](https://github.com/sindresorhus/is-stream) - Check if something is a Node.js stream
- [is-observable](https://github.com/sindresorhus/is-observable) - Check if a value is an Observable
- [file-type](https://github.com/sindresorhus/file-type) - Detect the file type of a Buffer/Uint8Array
- [is-ip](https://github.com/sindresorhus/is-ip) - Check if a string is an IP address
- [is-array-sorted](https://github.com/sindresorhus/is-array-sorted) - Check if an Array is sorted
- [is-error-constructor](https://github.com/sindresorhus/is-error-constructor) - Check if a value is an error constructor
- [is-empty-iterable](https://github.com/sindresorhus/is-empty-iterable) - Check if an Iterable is empty
- [is-blob](https://github.com/sindresorhus/is-blob) - Check if a value is a Blob - File-like object of immutable, raw data
- [has-emoji](https://github.com/sindresorhus/has-emoji) - Check whether a string has any emoji

## Maintainers

- [Sindre Sorhus](https://github.com/sindresorhus)
- [Giora Guttsait](https://github.com/gioragutt)
- [Brandon Smith](https://github.com/brandon93s)


---

# remark-comment

Parse HTML style comments as a different node type so it can be ignored during
serialization.

## Install and usage

```sh
npm install remark-comment
```

```js
import { unified } from 'unified'
import remarkParse from 'remark-parse'
import remarkComment from 'remark-comment'

unified().use(remarkParse).use(remarkComment)
```

For more help with unified, please see the docs for [unified] and [remark].

This package also exports its [micromark] and [mdast] plugins:

```js
import {
  comment,
  commentHtml,
  commentFromMarkdown,
  commentToMarkdown,
} from 'remark-comment'
```

**Options:**

The `remarkComment` and `commentFromMarkdown` functions take the options:

- `ast`: If true, a `{ type: "comment" }` node will be included in the
  resulting AST. This is useful if you want to do post-processing and stringify
  back to markdown. Default: `false`.

[unified]: https://unifiedjs.com/learn/guide/using-unified/
[remark]: https://unifiedjs.com/explore/package/remark-parse/
[micromark]: https://github.com/micromark/micromark
[mdast]: https://github.com/syntax-tree/mdast#extensions

## Example

```markdown
# This file

<!-- contains a comment -->

And a paragraph
```

Renders to:

```html
<h1>This file</h1>
<p>And a paragraph</p>
```

## Motivation

This package was created after realizing that MDX lacked support for HTML style
comments. When trying to migrate an existing collection of markdown files to
MDX, hitting syntax errors for HTML comments was a non-starter. Rather than go
modify all those files to use a (more awkward) JSX expression comment, I created
this plugin to add back this support.

However, I found this useful when used outside of MDX. Common markdown
interprets an HTML comment as an HTML block, and during serialization will pass
it directly through to the final HTML document. I typically do not want my
markdown comments appearing in my final HTML documents, and this plugin achieves
this effect.

## Caveats

This plugin must be added after MDX, otherwise you will see this error:

```
Unexpected character `!` (U+0021) before name, expected a character that can start a name, such as a letter, `$`, or `_` (note: to create a comment in MDX, use `{/* text */}`)
```

In a unified pipeline:

```js
unified().use(remarkMDX).use(remarkComment)
```

Unlike HTML, comments cannot be used within a JSX body. JSX is still JSX.
HTML comments must appear outside of JSX, use JSX style comments (`{/* comment */}`) inside of JSX.


---

# Change Log

All notable changes to this project will be documented in this file.
See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.

# [8.0.0](https://github.com/gregberge/svgr/compare/v7.0.0...v8.0.0) (2023-05-09)

**Note:** Version bump only for package @svgr/babel-plugin-add-jsx-attribute





# [7.0.0](https://github.com/gregberge/svgr/compare/v6.5.1...v7.0.0) (2023-03-24)

**Note:** Version bump only for package @svgr/babel-plugin-add-jsx-attribute





## [6.5.1](https://github.com/gregberge/svgr/compare/v6.5.0...v6.5.1) (2022-10-27)

**Note:** Version bump only for package @svgr/babel-plugin-add-jsx-attribute

# [6.5.0](https://github.com/gregberge/svgr/compare/v6.4.0...v6.5.0) (2022-10-14)

**Note:** Version bump only for package @svgr/babel-plugin-add-jsx-attribute

## [6.3.1](https://github.com/gregberge/svgr/compare/v6.3.0...v6.3.1) (2022-07-22)

### Bug Fixes

- fix exports compat with ESM ([#749](https://github.com/gregberge/svgr/issues/749)) ([f3e304c](https://github.com/gregberge/svgr/commit/f3e304c166282f042ecd4d6c396a0798a7f0b490))

# [6.3.0](https://github.com/gregberge/svgr/compare/v6.2.1...v6.3.0) (2022-07-18)

### Bug Fixes

- **package.json:** fix exports ([#745](https://github.com/gregberge/svgr/issues/745)) ([2a368d1](https://github.com/gregberge/svgr/commit/2a368d1305949ec6426c7c7312c04224071ec2bd))

# [5.4.0](https://github.com/gregberge/svgr/tree/master/packages/babel-plugin-add-jsx-attribute/compare/v5.3.1...v5.4.0) (2020-04-27)

**Note:** Version bump only for package @svgr/babel-plugin-add-jsx-attribute

## [5.0.1](https://github.com/gregberge/svgr/tree/master/packages/babel-plugin-add-jsx-attribute/compare/v5.0.0...v5.0.1) (2019-12-29)

### Bug Fixes

- fix engines in package.json ([a45d6fc](https://github.com/gregberge/svgr/tree/master/packages/babel-plugin-add-jsx-attribute/commit/a45d6fc8b43402bec60ed4e9273f90fdc65a23a7))

# [4.2.0](https://github.com/gregberge/svgr/tree/master/packages/babel-plugin-add-jsx-attribute/compare/v4.1.0...v4.2.0) (2019-04-11)

**Note:** Version bump only for package @svgr/babel-plugin-add-jsx-attribute

# [4.0.0](https://github.com/gregberge/svgr/compare/v3.1.0...v4.0.0) (2018-11-04)

### Features

- **v4:** new architecture ([ac8b8ca](https://github.com/gregberge/svgr/commit/ac8b8ca))

### BREAKING CHANGES

- **v4:** - `template` option must now returns a Babel AST

* `@svgr/core` does not include svgo & prettier by default


---

# @svgr/babel-plugin-add-jsx-attribute

## Install

```
npm install --save-dev @svgr/babel-plugin-add-jsx-attribute
```

## Usage

**.babelrc**

```json
{
  "plugins": [
    [
      "@svgr/babel-plugin-add-jsx-attribute",
      {
        "elements": ["svg"],
        "attributes": [
          {
            "name": "width",
            "value": "200",
            "spread": false,
            "literal": false,
            "position": "end"
          }
        ]
      }
    ]
  ]
}
```

## License

MIT


---

# @svgr/babel-plugin-remove-jsx-attribute

## Install

```
npm install --save-dev @svgr/babel-plugin-remove-jsx-attribute
```

## Usage

**.babelrc**

```json
{
  "plugins": [
    [
      "@svgr/babel-plugin-remove-jsx-attribute",
      {
        "elements": ["svg"],
        "attributes": ["width", "height"]
      }
    ]
  ]
}
```

## License

MIT


---

# @svgr/babel-plugin-remove-jsx-empty-expression

## Install

```
npm install --save-dev @svgr/babel-plugin-remove-jsx-empty-expression
```

## Usage

**.babelrc**

```json
{
  "plugins": ["@svgr/babel-plugin-remove-jsx-empty-expression"]
}
```

## License

MIT


---

# @svgr/babel-plugin-replace-jsx-attribute-value

## Install

```
npm install --save-dev @svgr/babel-plugin-replace-jsx-attribute-value
```

## Usage

**.babelrc**

```json
{
  "plugins": [
    [
      "@svgr/babel-plugin-replace-jsx-attribute-value",
      {
        "values": [
          { "value": "#000", "newValue": "#fff" },
          { "value": "blue", "newValue": "props.color", "literal": true }
        ]
      }
    ]
  ]
}
```

## License

MIT


---

# @svgr/babel-plugin-svg-dynamic-title

## Install

```
npm install --save-dev @svgr/babel-plugin-svg-dynamic-title
```

## Usage

**.babelrc**

```json
{
  "plugins": ["@svgr/babel-plugin-svg-dynamic-title"]
}
```

## Note

This plugin handles both the titleProp and descProp options. By default, it will handle titleProp only.

## License

MIT


---

# @svgr/babel-plugin-svg-em-dimensions

## Install

```
npm install --save-dev @svgr/babel-plugin-svg-em-dimensions
```

## Usage

**.babelrc**

```json
{
  "plugins": [
    ["@svgr/babel-plugin-svg-em-dimensions", { "width": 24, "height": 24 }]
  ]
}
```

## License

MIT


---

# @svgr/babel-plugin-transform-react-native-svg

## Install

```
npm install --save-dev @svgr/babel-plugin-transform-react-native-svg
```

## Usage

**.babelrc**

```json
{
  "plugins": ["@svgr/babel-plugin-transform-react-native-svg"]
}
```

## License

MIT


---

# @svgr/babel-plugin-transform-svg-component

## Install

```
npm install --save-dev @svgr/babel-plugin-transform-svg-component
```

## Usage

**.babelrc**

```json
{
  "plugins": [
    ["@svgr/babel-plugin-transform-svg-component", { "titleProp": true }]
  ]
}
```

## License

MIT


---

# @svgr/babel-preset

## Install

```
npm install --save-dev @svgr/babel-preset
```

## Usage

**.babelrc**

```json
{
  "presets": [["@svgr/babel-preset", { "svgProps": { "width": 200 } }]]
}
```

## License

MIT


---

# @svgr/core

[![Build Status][build-badge]][build]
[![version][version-badge]][package]
[![MIT License][license-badge]][license]

Node API of SVGR.

```
npm install @svgr/core
```

## Usage

```js
import { transform } from '@svgr/core'

const svgCode = `
<svg xmlns="http://www.w3.org/2000/svg"
  xmlns:xlink="http://www.w3.org/1999/xlink">
  <rect x="10" y="10" height="100" width="100"
    style="stroke:#ff0000; fill: #0000ff"/>
</svg>
`

transform(svgCode, { icon: true }, { componentName: 'MyComponent' }).then(
  (jsCode) => {
    console.log(jsCode)
  },
)
```

Use `svgr.sync(code, config, state)` if you would like to use sync version.

### Plugins

By default `@svgr/core` doesn't include any plugin, if you want them, you have to install them and include them in config.

```js
svgr(svgCode, {
  plugins: ['@svgr/plugin-svgo', '@svgr/plugin-jsx', '@svgr/plugin-prettier'],
}).then((jsCode) => {
  console.log(jsCode)
})
```

## License

MIT

[build-badge]: https://img.shields.io/travis/smooth-code/svgr.svg?style=flat-square
[build]: https://travis-ci.org/smooth-code/svgr
[version-badge]: https://img.shields.io/npm/v/@svgr/core.svg?style=flat-square
[package]: https://www.npmjs.com/package/@svgr/core
[license-badge]: https://img.shields.io/npm/l/@svgr/core.svg?style=flat-square
[license]: https://github.com/smooth-code/svgr/blob/master/LICENSE


---

# @svgr/hast-util-to-babel-ast

[![Build Status](https://img.shields.io/travis/smooth-code/svgr.svg)](https://travis-ci.org/smooth-code/svgr)
[![Version](https://img.shields.io/npm/v/@svgr/hast-util-to-babel-ast.svg)](https://www.npmjs.com/package/@svgr/hast-util-to-babel-ast)
[![MIT License](https://img.shields.io/npm/l/@svgr/hast-util-to-babel-ast.svg)](https://github.com/smooth-code/svgr/blob/master/LICENSE)

Transforms HAST into Babel AST.

## Install

```
npm install --save-dev @svgr/hast-util-to-babel-ast
```

## Usage

```js
import { parse } from 'svg-parser'
import hastToBabelAst from '@svgr/hast-util-to-babel-ast'

const hastTree = parse(`<svg></svg>`)

const babelTree = hastToBabelAst(hastTree)
```

## License

MIT


---

# @svgr/plugin-jsx

[![Build Status](https://img.shields.io/travis/smooth-code/svgr.svg)](https://travis-ci.org/smooth-code/svgr)
[![Version](https://img.shields.io/npm/v/@svgr/plugin-jsx.svg)](https://www.npmjs.com/package/@svgr/plugin-jsx)
[![MIT License](https://img.shields.io/npm/l/@svgr/plugin-jsx.svg)](https://github.com/smooth-code/svgr/blob/master/LICENSE)

Transforms SVG into JSX.

## Install

```
npm install --save-dev @svgr/plugin-jsx
```

## Usage

**.svgrrc**

```json
{
  "plugins": ["@svgr/plugin-jsx"]
}
```

## How does it work?

`@svgr/plugin-jsx` consists in three phases:

- Parsing the SVG code using [svg-parser](https://github.com/Rich-Harris/svg-parser)
- Converting the [HAST](https://github.com/syntax-tree/hast) into a [Babel AST](https://github.com/babel/babel/blob/master/packages/babel-parser/ast/spec.md)
- Applying [`@svgr/babel-preset`](../babel-preset/README.md) transformations

## Applying custom transformations

You can extend the Babel config applied in this plugin using `jsx.babelConfig` config path:

```js
// .svgrrc.js

module.exports = {
  jsx: {
    babelConfig: {
      plugins: [
        // For an example, this plugin will remove "id" attribute from "svg" tag
        [
          '@svgr/babel-plugin-remove-jsx-attribute',
          {
            elements: ['svg'],
            attributes: ['id'],
          },
        ],
      ],
    },
  },
}
```

Several Babel plugins are available:

- [`@svgr/babel-plugin-add-jsx-attribute`](../babel-plugin-add-jsx-attribute/README.md)
- [`@svgr/babel-plugin-remove-jsx-attribute`](../babel-plugin-remove-jsx-attribute/README.md)
- [`@svgr/babel-plugin-remove-jsx-empty-expression`](../babel-plugin-remove-jsx-empty-expression/README.md)
- [`@svgr/babel-plugin-replace-jsx-attribute-value`](../babel-plugin-replace-jsx-attribute-value/README.md)
- [`@svgr/babel-plugin-svg-dynamic-title`](../babel-plugin-svg-dynamic-title/README.md)
- [`@svgr/babel-plugin-svg-em-dimensions`](../babel-plugin-svg-em-dimensions/README.md)
- [`@svgr/babel-plugin-transform-react-native-svg`](../babel-plugin-transform-react-native-svg/README.md)
- [`@svgr/babel-plugin-transform-svg-component`](../babel-plugin-transform-svg-component/README.md)

If you want to create your own, reading [Babel Handbook](https://github.com/jamiebuilds/babel-handbook/blob/master/translations/en/plugin-handbook.md) is a good start!

## License

MIT


---

# @svgr/plugin-svgo

[![Build Status](https://img.shields.io/travis/smooth-code/svgr.svg)](https://travis-ci.org/smooth-code/svgr)
[![Version](https://img.shields.io/npm/v/@svgr/plugin-svgo.svg)](https://www.npmjs.com/package/@svgr/plugin-svgo)
[![MIT License](https://img.shields.io/npm/l/@svgr/plugin-svgo.svg)](https://github.com/smooth-code/svgr/blob/master/LICENSE)

Optimize SVG using SVGO.

## Install

```
npm install --save-dev @svgr/plugin-svgo
```

## Usage

**.svgrrc**

```json
{
  "plugins": ["@svgr/plugin-svgo"]
}
```

## License

MIT


---

# @svgr/webpack

[![Build Status](https://img.shields.io/travis/gregberge/svgr.svg)](https://travis-ci.org/gregberge/svgr)
[![Version](https://img.shields.io/npm/v/@svgr/webpack.svg)](https://www.npmjs.com/package/@svgr/webpack)
[![MIT License](https://img.shields.io/npm/l/@svgr/webpack.svg)](https://github.com/gregberge/svgr/blob/master/LICENSE)

Webpack loader for SVGR.

```
npm install @svgr/webpack --save-dev
```

## Usage

In your `webpack.config.js`:

```js
{
  test: /\.svg$/,
  use: ['@svgr/webpack'],
}
```

In your code:

```js
import Star from './star.svg'

const App = () => (
  <div>
    <Star />
  </div>
)
```

### Passing options

```js
{
  test: /\.svg$/,
  use: [
    {
      loader: '@svgr/webpack',
      options: {
        native: true,
      },
    },
  ],
}
```

### Using with `url-loader` or `file-loader`

It is possible to use it with [`url-loader`](https://github.com/webpack-contrib/url-loader) or [`file-loader`](https://github.com/webpack-contrib/file-loader).

In your `webpack.config.js`:

```js
{
  test: /\.svg$/,
  use: ['@svgr/webpack', 'url-loader'],
}
```

In your code:

```js
import starUrl, { ReactComponent as Star } from './star.svg'

const App = () => (
  <div>
    <img src={starUrl} alt="star" />
    <Star />
  </div>
)
```

The named export defaults to `ReactComponent`, but can be customized with the `namedExport` option.

Please note that by default, `@svgr/webpack` will try to export the React Component via default export if there is no other loader handling svg files with default export. When there is already any other loader using default export for svg files, `@svgr/webpack` will always export the React component via named export.

If you prefer named export in any case, you may set the `exportType` option to `named`.

### Use your own Babel configuration

By default, `@svgr/webpack` includes a `babel-loader` with [an optimized configuration](https://github.com/gregberge/svgr/blob/main/packages/webpack/src/index.ts). In some case you may want to apply a custom one (if you are using Preact for an example). You can turn off Babel transformation by specifying `babel: false` in options.

```js
// Example using preact
{
  test: /\.svg$/,
  use: [
    {
      loader: 'babel-loader',
      options: {
        presets: ['preact', 'env'],
      },
    },
    {
      loader: '@svgr/webpack',
      options: { babel: false },
    }
  ],
}
```

### Handle SVG in CSS, Sass or Less

It is possible to detect the module that requires your SVG using [`Rule.issuer`](https://webpack.js.org/configuration/module/#ruleissuer) in Webpack 5. Using it you can specify two different configurations for JavaScript and the rest of your files.

```js
;[
  {
    test: /\.svg(\?v=\d+\.\d+\.\d+)?$/,
    issuer: /\.[jt]sx?$/,
    use: ['babel-loader', '@svgr/webpack', 'url-loader'],
  },
  {
    test: /\.svg(\?v=\d+\.\d+\.\d+)?$/,
    loader: 'url-loader',
  },
]
```

_[Rule.issuer](https://v4.webpack.js.org/configuration/module/#ruleissuer) in Webpack 4 has additional conditions which are not available in Webpack 5._

## License

MIT


---

# http-timer
> Timings for HTTP requests

[![Build Status](https://travis-ci.org/szmarczak/http-timer.svg?branch=master)](https://travis-ci.org/szmarczak/http-timer)
[![Coverage Status](https://coveralls.io/repos/github/szmarczak/http-timer/badge.svg?branch=master)](https://coveralls.io/github/szmarczak/http-timer?branch=master)
[![install size](https://packagephobia.now.sh/badge?p=@szmarczak/http-timer)](https://packagephobia.now.sh/result?p=@szmarczak/http-timer)

Inspired by the [`request` package](https://github.com/request/request).

## Installation

NPM:

> `npm install @szmarczak/http-timer`

Yarn:

> `yarn add @szmarczak/http-timer`

## Usage
**Note:**
> - The measured events resemble Node.js events, not the kernel ones.
> - Sending a chunk greater than [`highWaterMark`](https://nodejs.org/api/stream.html#stream_new_stream_writable_options) will result in invalid `upload` and `response` timings. You can avoid this by splitting the payload into smaller chunks.

```js
import https from 'https';
import timer from '@szmarczak/http-timer';

const request = https.get('https://httpbin.org/anything');
timer(request);

request.once('response', response => {
	response.resume();
	response.once('end', () => {
		console.log(response.timings); // You can use `request.timings` as well
	});
});

// {
//   start: 1572712180361,
//   socket: 1572712180362,
//   lookup: 1572712180415,
//   connect: 1572712180571,
//   upload: 1572712180884,
//   response: 1572712181037,
//   end: 1572712181039,
//   error: undefined,
//   abort: undefined,
//   phases: {
//     wait: 1,
//     dns: 53,
//     tcp: 156,
//     request: 313,
//     firstByte: 153,
//     download: 2,
//     total: 678
//   }
// }
```

## API

### timer(request)

Returns: `Object`

**Note**: The time is a `number` representing the milliseconds elapsed since the UNIX epoch.

- `start` - Time when the request started.
- `socket` - Time when a socket was assigned to the request.
- `lookup` - Time when the DNS lookup finished.
- `connect` - Time when the socket successfully connected.
- `secureConnect` - Time when the socket securely connected.
- `upload` - Time when the request finished uploading.
- `response` - Time when the request fired `response` event.
- `end` - Time when the response fired `end` event.
- `error` - Time when the request fired `error` event.
- `abort` - Time when the request fired `abort` event.
- `phases`
	- `wait` - `timings.socket - timings.start`
	- `dns` - `timings.lookup - timings.socket`
	- `tcp` - `timings.connect - timings.lookup`
	- `tls` - `timings.secureConnect - timings.connect`
	- `request` - `timings.upload - (timings.secureConnect || timings.connect)`
	- `firstByte` - `timings.response - timings.upload`
	- `download` - `timings.end - timings.response`
	- `total` - `(timings.end || timings.error || timings.abort) - timings.start`

If something has not been measured yet, it will be `undefined`.

## License

MIT


---

# svg/sax

A maintained fork of [sax-js](https://github.com/isaacs/sax-js) sax-style parser for XML and HTML.

Designed with [node](http://nodejs.org/) in mind, but should work fine in
the browser or other CommonJS implementations.

## What This Is

* A very simple tool to parse through an XML string.
* A stepping stone to a streaming HTML parser.
* A handy way to deal with RSS and other mostly-ok-but-kinda-broken XML
  docs.

## What This Is (probably) Not

* An HTML Parser - That's a fine goal, but this isn't it.  It's just
  XML.
* A DOM Builder - You can use it to build an object model out of XML,
  but it doesn't do that out of the box.
* XSLT - No DOM = no querying.
* 100% Compliant with (some other SAX implementation) - Most SAX
  implementations are in Java and do a lot more than this does.
* An XML Validator - It does a little validation when in strict mode, but
  not much.
* A Schema-Aware XSD Thing - Schemas are an exercise in fetishistic
  masochism.
* A DTD-aware Thing - Fetching DTDs is a much bigger job.

## Regarding `<!DOCTYPE`s and `<!ENTITY`s

The parser will handle the basic XML entities in text nodes and attribute
values: `&amp; &lt; &gt; &apos; &quot;`. It's possible to define additional
entities in XML by putting them in the DTD. This parser doesn't do anything
with that. If you want to listen to the `ondoctype` event, and then fetch
the doctypes, and read the entities and add them to `parser.ENTITIES`, then
be my guest.

Unknown entities will fail in strict mode, and in loose mode, will pass
through unmolested.

## Usage

```javascript
var sax = require("./lib/sax"),
  strict = true, // set to false for html-mode
  parser = sax.parser(strict);

parser.onerror = function (e) {
  // an error happened.
};
parser.ontext = function (t) {
  // got some text.  t is the string of text.
};
parser.onopentag = function (node) {
  // opened a tag.  node has "name" and "attributes"
};
parser.onattribute = function (attr) {
  // an attribute.  attr has "name" and "value"
};
parser.onend = function () {
  // parser stream is done, and ready to have more stuff written to it.
};

parser.write('<xml>Hello, <who name="world">world</who>!</xml>').close();
```


## Arguments

Pass the following arguments to the parser function.  All are optional.

`strict` - Boolean. Whether or not to be a jerk. Default: `false`.

`opt` - Object bag of settings regarding string formatting.  All default to `false`.

Settings supported:

* `trim` - Boolean. Whether or not to trim text and comment nodes.
* `normalize` - Boolean. If true, then turn any whitespace into a single
  space.
* `lowercase` - Boolean. If true, then lowercase tag names and attribute names
  in loose mode, rather than uppercasing them.
* `xmlns` - Boolean. If true, then namespaces are supported.
* `position` - Boolean. If false, then don't track line/col/position.
* `strictEntities` - Boolean. If true, only parse [predefined XML
  entities](http://www.w3.org/TR/REC-xml/#sec-predefined-ent)
  (`&amp;`, `&apos;`, `&gt;`, `&lt;`, and `&quot;`)

## Methods

`write` - Write bytes onto the stream. You don't have to do this all at
once. You can keep writing as much as you want.

`close` - Close the stream. Once closed, no more data may be written until
it is done processing the buffer, which is signaled by the `end` event.

`resume` - To gracefully handle errors, assign a listener to the `error`
event. Then, when the error is taken care of, you can call `resume` to
continue parsing. Otherwise, the parser will not continue while in an error
state.

## Members

At all times, the parser object will have the following members:

`line`, `column`, `position` - Indications of the position in the XML
document where the parser currently is looking.

`startTagPosition` - Indicates the position where the current tag starts.

`closed` - Boolean indicating whether or not the parser can be written to.
If it's `true`, then wait for the `ready` event to write again.

`strict` - Boolean indicating whether or not the parser is a jerk.

`opt` - Any options passed into the constructor.

`tag` - The current tag being dealt with.

And a bunch of other stuff that you probably shouldn't touch.

## Events

All events emit with a single argument. To listen to an event, assign a
function to `on<eventname>`. Functions get executed in the this-context of
the parser object. The list of supported events are also in the exported
`EVENTS` array.

`error` - Indication that something bad happened. The error will be hanging
out on `parser.error`, and must be deleted before parsing can continue. By
listening to this event, you can keep an eye on that kind of stuff. Note:
this happens *much* more in strict mode. Argument: instance of `Error`.

`text` - Text node. Argument: string of text.

`doctype` - The `<!DOCTYPE` declaration. Argument: doctype string.

`processinginstruction` - Stuff like `<?xml foo="blerg" ?>`. Argument:
object with `name` and `body` members. Attributes are not parsed, as
processing instructions have implementation dependent semantics.

`sgmldeclaration` - Random SGML declarations. Stuff like `<!ENTITY p>`
would trigger this kind of event. This is a weird thing to support, so it
might go away at some point. SAX isn't intended to be used to parse SGML,
after all.

`opentagstart` - Emitted immediately when the tag name is available,
but before any attributes are encountered.  Argument: object with a
`name` field and an empty `attributes` set.  Note that this is the
same object that will later be emitted in the `opentag` event.

`opentag` - An opening tag. Argument: object with `name` and `attributes`.
In non-strict mode, tag names are uppercased, unless the `lowercase`
option is set.  If the `xmlns` option is set, then it will contain
namespace binding information on the `ns` member, and will have a
`local`, `prefix`, and `uri` member.

`closetag` - A closing tag. In loose mode, tags are auto-closed if their
parent closes. In strict mode, well-formedness is enforced. Note that
self-closing tags will have `closeTag` emitted immediately after `openTag`.
Argument: tag name.

`attribute` - An attribute node.  Argument: object with `name` and `value`.
In non-strict mode, attribute names are uppercased, unless the `lowercase`
option is set.  If the `xmlns` option is set, it will also contains namespace
information.

`comment` - A comment node.  Argument: the string of the comment.

`opencdata` - The opening tag of a `<![CDATA[` block.

`cdata` - The text of a `<![CDATA[` block. Since `<![CDATA[` blocks can get
quite large, this event may fire multiple times for a single block, if it
is broken up into multiple `write()`s. Argument: the string of random
character data.

`closecdata` - The closing tag (`]]>`) of a `<![CDATA[` block.

`opennamespace` - If the `xmlns` option is set, then this event will
signal the start of a new namespace binding.

`closenamespace` - If the `xmlns` option is set, then this event will
signal the end of a namespace binding.

`end` - Indication that the closed stream has ended.

`ready` - Indication that the stream has reset, and is ready to be written
to.

`noscript` - In non-strict mode, `<script>` tags trigger a `"script"`
event, and their contents are not checked for special xml characters.
If you pass `noscript: true`, then this behavior is suppressed.

## Reporting Problems

It's best to write a failing test if you find an issue.  I will always
accept pull requests with failing tests if they demonstrate intended
behavior, but it is very hard to figure out what issue you're describing
without a test.  Writing a test is also the best way for you yourself
to figure out if you really understand the issue you think you have with
sax-js.


---

### A base TSConfig for working with Docusaurus v2.

Add the package to your `"devDependencies"`:

```sh
npm install --save-dev @tsconfig/docusaurus
yarn add --dev @tsconfig/docusaurus
```

Add to your `tsconfig.json`:

```json
"extends": "@tsconfig/docusaurus/tsconfig.json"
```

---

The `tsconfig.json`: 

```jsonc
{
  "$schema": "https://json.schemastore.org/tsconfig",
  "display": "Docusaurus v2",
  "docs": "https://v2.docusaurus.io/docs/typescript-support",
  
  "compilerOptions": {
    "allowJs": true,
    "esModuleInterop": true,
    "jsx": "react",
    "lib": ["DOM"],
    "moduleResolution": "Node16",
    "noEmit": true,
    "types": ["node", "@docusaurus/module-type-aliases", "@docusaurus/theme-classic"],
    "baseUrl": ".",
    "paths": {
      "@site/*": ["./*"]
    },
    "skipLibCheck": true
  }
}

```

You can find the [code here](https://github.com/tsconfig/bases/blob/master/bases/docusaurus.json).


---

# Installation
> `npm install --save @types/body-parser`

# Summary
This package contains type definitions for body-parser (https://github.com/expressjs/body-parser).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/body-parser.

### Additional Details
 * Last updated: Mon, 06 Nov 2023 22:41:05 GMT
 * Dependencies: [@types/connect](https://npmjs.com/package/@types/connect), [@types/node](https://npmjs.com/package/@types/node)

# Credits
These definitions were written by [Santi Albo](https://github.com/santialbo), [Vilic Vane](https://github.com/vilic), [Jonathan Häberle](https://github.com/dreampulse), [Gevik Babakhani](https://github.com/blendsdk), [Tomasz Łaziuk](https://github.com/tlaziuk), [Jason Walton](https://github.com/jwalton), and [Piotr Błażejewicz](https://github.com/peterblazejewicz).


---

# Installation
> `npm install --save @types/bonjour`

# Summary
This package contains type definitions for bonjour (https://github.com/watson/bonjour).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/bonjour.

### Additional Details
 * Last updated: Mon, 06 Nov 2023 22:41:05 GMT
 * Dependencies: [@types/node](https://npmjs.com/package/@types/node)

# Credits
These definitions were written by [Quentin Lampin](https://github.com/quentin-ol).


---

# Installation
> `npm install --save @types/connect`

# Summary
This package contains type definitions for connect (https://github.com/senchalabs/connect).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/connect.

### Additional Details
 * Last updated: Mon, 06 Nov 2023 22:41:05 GMT
 * Dependencies: [@types/node](https://npmjs.com/package/@types/node)

# Credits
These definitions were written by [Maxime LUCE](https://github.com/SomaticIT), and [Evan Hahn](https://github.com/EvanHahn).


---

# Installation
> `npm install --save @types/connect-history-api-fallback`

# Summary
This package contains type definitions for connect-history-api-fallback (https://github.com/bripkens/connect-history-api-fallback#readme).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/connect-history-api-fallback.
## [index.d.ts](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/connect-history-api-fallback/index.d.ts)
````ts
/// <reference types="node" />

import { Url } from "url";

import * as core from "express-serve-static-core";

export = historyApiFallback;

declare function historyApiFallback(options?: historyApiFallback.Options): core.RequestHandler;

declare namespace historyApiFallback {
    interface Options {
        readonly disableDotRule?: true | undefined;
        readonly htmlAcceptHeaders?: readonly string[] | undefined;
        readonly index?: string | undefined;
        readonly logger?: typeof console.log | undefined;
        readonly rewrites?: readonly Rewrite[] | undefined;
        readonly verbose?: boolean | undefined;
    }

    interface Context {
        readonly match: RegExpMatchArray;
        readonly parsedUrl: Url;
        readonly request: core.Request;
    }
    type RewriteTo = (context: Context) => string;

    interface Rewrite {
        readonly from: RegExp;
        readonly to: string | RegExp | RewriteTo;
    }
}

````

### Additional Details
 * Last updated: Mon, 20 Nov 2023 23:36:24 GMT
 * Dependencies: [@types/express-serve-static-core](https://npmjs.com/package/@types/express-serve-static-core), [@types/node](https://npmjs.com/package/@types/node)

# Credits
These definitions were written by [Douglas Duteil](https://github.com/douglasduteil).


---

# Installation
> `npm install --save @types/debug`

# Summary
This package contains type definitions for debug (https://github.com/debug-js/debug).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/debug.
## [index.d.ts](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/debug/index.d.ts)
````ts
declare var debug: debug.Debug & { debug: debug.Debug; default: debug.Debug };

export = debug;
export as namespace debug;

declare namespace debug {
    interface Debug {
        (namespace: string): Debugger;
        coerce: (val: any) => any;
        disable: () => string;
        enable: (namespaces: string) => void;
        enabled: (namespaces: string) => boolean;
        formatArgs: (this: Debugger, args: any[]) => void;
        log: (...args: any[]) => any;
        selectColor: (namespace: string) => string | number;
        humanize: typeof import("ms");

        names: RegExp[];
        skips: RegExp[];

        formatters: Formatters;

        inspectOpts?: {
            hideDate?: boolean | number | null;
            colors?: boolean | number | null;
            depth?: boolean | number | null;
            showHidden?: boolean | number | null;
        };
    }

    type IDebug = Debug;

    interface Formatters {
        [formatter: string]: (v: any) => string;
    }

    type IDebugger = Debugger;

    interface Debugger {
        (formatter: any, ...args: any[]): void;

        color: string;
        diff: number;
        enabled: boolean;
        log: (...args: any[]) => any;
        namespace: string;
        destroy: () => boolean;
        extend: (namespace: string, delimiter?: string) => Debugger;
    }
}

````

### Additional Details
 * Last updated: Thu, 09 Nov 2023 03:06:57 GMT
 * Dependencies: [@types/ms](https://npmjs.com/package/@types/ms)

# Credits
These definitions were written by [Seon-Wook Park](https://github.com/swook), [Gal Talmor](https://github.com/galtalmor), [John McLaughlin](https://github.com/zamb3zi), [Brasten Sager](https://github.com/brasten), [Nicolas Penin](https://github.com/npenin), [Kristian Brünn](https://github.com/kristianmitk), and [Caleb Gregory](https://github.com/calebgregory).


---

# Installation
> `npm install --save @types/eslint`

# Summary
This package contains type definitions for eslint (https://eslint.org).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/eslint.

### Additional Details
 * Last updated: Mon, 26 Aug 2024 07:08:02 GMT
 * Dependencies: [@types/estree](https://npmjs.com/package/@types/estree), [@types/json-schema](https://npmjs.com/package/@types/json-schema)

# Credits
These definitions were written by [Pierre-Marie Dartus](https://github.com/pmdartus), [Jed Fox](https://github.com/j-f1), [Saad Quadri](https://github.com/saadq), [Jason Kwok](https://github.com/JasonHK), [Brad Zacher](https://github.com/bradzacher), [JounQin](https://github.com/JounQin), and [Bryan Mishkin](https://github.com/bmish).


---

# Installation
> `npm install --save @types/eslint-scope`

# Summary
This package contains type definitions for eslint-scope (https://github.com/eslint/eslint-scope).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/eslint-scope.
## [index.d.ts](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/eslint-scope/index.d.ts)
````ts
import * as eslint from "eslint";
import * as estree from "estree";

export const version: string;

export class ScopeManager implements eslint.Scope.ScopeManager {
    scopes: Scope[];
    globalScope: Scope;
    acquire(node: {}, inner?: boolean): Scope | null;
    getDeclaredVariables(node: {}): Variable[];
}

export class Scope implements eslint.Scope.Scope {
    type:
        | "block"
        | "catch"
        | "class"
        | "for"
        | "function"
        | "function-expression-name"
        | "global"
        | "module"
        | "switch"
        | "with"
        | "TDZ";
    isStrict: boolean;
    upper: Scope | null;
    childScopes: Scope[];
    variableScope: Scope;
    block: estree.Node;
    variables: Variable[];
    set: Map<string, Variable>;
    references: Reference[];
    through: Reference[];
    functionExpressionScope: boolean;
}

export class Variable implements eslint.Scope.Variable {
    name: string;
    scope: Scope;
    identifiers: estree.Identifier[];
    references: Reference[];
    defs: eslint.Scope.Definition[];
}

export class Reference implements eslint.Scope.Reference {
    identifier: estree.Identifier;
    from: Scope;
    resolved: Variable | null;
    writeExpr: estree.Node | null;
    init: boolean;

    isWrite(): boolean;
    isRead(): boolean;
    isWriteOnly(): boolean;
    isReadOnly(): boolean;
    isReadWrite(): boolean;
}

export interface AnalysisOptions {
    optimistic?: boolean;
    directive?: boolean;
    ignoreEval?: boolean;
    nodejsScope?: boolean;
    impliedStrict?: boolean;
    fallback?: string | ((node: {}) => string[]);
    sourceType?: "script" | "module";
    ecmaVersion?: number;
}

export function analyze(ast: {}, options?: AnalysisOptions): ScopeManager;

````

### Additional Details
 * Last updated: Mon, 06 Nov 2023 22:41:05 GMT
 * Dependencies: [@types/eslint](https://npmjs.com/package/@types/eslint), [@types/estree](https://npmjs.com/package/@types/estree)

# Credits
These definitions were written by [Toru Nagashima](https://github.com/mysticatea).


---

# Installation
> `npm install --save @types/estree`

# Summary
This package contains type definitions for estree (https://github.com/estree/estree).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/estree.

### Additional Details
 * Last updated: Mon, 24 Mar 2025 07:34:10 GMT
 * Dependencies: none

# Credits
These definitions were written by [RReverser](https://github.com/RReverser).


---

# Installation
> `npm install --save @types/estree-jsx`

# Summary
This package contains type definitions for estree-jsx (https://github.com/facebook/jsx).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/estree-jsx.

### Additional Details
 * Last updated: Fri, 23 Feb 2024 02:11:41 GMT
 * Dependencies: [@types/estree](https://npmjs.com/package/@types/estree)

# Credits
These definitions were written by [Tony Ross](https://github.com/antross).


---

# Installation
> `npm install --save @types/express`

# Summary
This package contains type definitions for express (http://expressjs.com).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/express.

### Additional Details
 * Last updated: Tue, 07 Nov 2023 03:09:36 GMT
 * Dependencies: [@types/body-parser](https://npmjs.com/package/@types/body-parser), [@types/express-serve-static-core](https://npmjs.com/package/@types/express-serve-static-core), [@types/qs](https://npmjs.com/package/@types/qs), [@types/serve-static](https://npmjs.com/package/@types/serve-static)

# Credits
These definitions were written by [Boris Yankov](https://github.com/borisyankov), [China Medical University Hospital](https://github.com/CMUH), [Puneet Arora](https://github.com/puneetar), and [Dylan Frankland](https://github.com/dfrankland).


---

# Installation
> `npm install --save @types/express-serve-static-core`

# Summary
This package contains type definitions for express-serve-static-core (http://expressjs.com).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/express-serve-static-core/v4.

### Additional Details
 * Last updated: Wed, 25 Sep 2024 19:19:36 GMT
 * Dependencies: [@types/node](https://npmjs.com/package/@types/node), [@types/qs](https://npmjs.com/package/@types/qs), [@types/range-parser](https://npmjs.com/package/@types/range-parser), [@types/send](https://npmjs.com/package/@types/send)

# Credits
These definitions were written by [Boris Yankov](https://github.com/borisyankov), [Satana Charuwichitratana](https://github.com/micksatana), [Jose Luis Leon](https://github.com/JoseLion), [David Stephens](https://github.com/dwrss), and [Shin Ando](https://github.com/andoshin11).


---

# Installation
> `npm install --save @types/express-serve-static-core`

# Summary
This package contains type definitions for express-serve-static-core (http://expressjs.com).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/express-serve-static-core.

### Additional Details
 * Last updated: Tue, 28 Jan 2025 05:02:28 GMT
 * Dependencies: [@types/node](https://npmjs.com/package/@types/node), [@types/qs](https://npmjs.com/package/@types/qs), [@types/range-parser](https://npmjs.com/package/@types/range-parser), [@types/send](https://npmjs.com/package/@types/send)

# Credits
These definitions were written by [Boris Yankov](https://github.com/borisyankov), [Satana Charuwichitratana](https://github.com/micksatana), [Jose Luis Leon](https://github.com/JoseLion), [David Stephens](https://github.com/dwrss), and [Shin Ando](https://github.com/andoshin11).


---

# Installation
> `npm install --save @types/gtag.js`

# Summary
This package contains type definitions for Google gtag.js API (https://developers.google.com/gtagjs).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/gtag.js.

### Additional Details
 * Last updated: Tue, 04 Oct 2022 21:02:53 GMT
 * Dependencies: none
 * Global values: `gtag`

# Credits
These definitions were written by [ Junyoung Choi](https://github.com/rokt33r), and [Lucas Akira Uehara](https://github.com/KsAkira10).


---

# Installation
> `npm install --save @types/hast`

# Summary
This package contains type definitions for hast (https://github.com/syntax-tree/hast).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/hast.

### Additional Details
 * Last updated: Tue, 30 Jan 2024 21:35:45 GMT
 * Dependencies: [@types/unist](https://npmjs.com/package/@types/unist)

# Credits
These definitions were written by [lukeggchapman](https://github.com/lukeggchapman), [Junyoung Choi](https://github.com/rokt33r), [Christian Murphy](https://github.com/ChristianMurphy), and [Remco Haszing](https://github.com/remcohaszing).


---

# Installation
> `npm install --save @types/history`

# Summary
This package contains type definitions for history (https://github.com/mjackson/history).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/history.

### Additional Details
 * Last updated: Sun, 16 Jan 2022 17:31:24 GMT
 * Dependencies: none
 * Global values: `History`

# Credits
These definitions were written by [Sergey Buturlakin](https://github.com/sergey-buturlakin), [Nathan Brown](https://github.com/ngbrown), [Young Rok Kim](https://github.com/rokoroku), and [Daniel Nixon](https://github.com/danielnixon).


---

# Installation
> `npm install --save @types/html-minifier-terser`

# Summary
This package contains type definitions for html-minifier-terser (https://github.com/terser/html-minifier-terser#readme).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/html-minifier-terser.

### Additional Details
 * Last updated: Tue, 23 Nov 2021 21:01:04 GMT
 * Dependencies: none
 * Global values: none

# Credits
These definitions were written by [Piotr Błażejewicz](https://github.com/peterblazejewicz).


---

# Installation
> `npm install --save @types/http-cache-semantics`

# Summary
This package contains type definitions for http-cache-semantics (https://github.com/kornelski/http-cache-semantics#readme).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/http-cache-semantics.

### Additional Details
 * Last updated: Tue, 07 Nov 2023 03:09:37 GMT
 * Dependencies: none

# Credits
These definitions were written by [BendingBender](https://github.com/BendingBender).


---

# Installation
> `npm install --save @types/http-errors`

# Summary
This package contains type definitions for http-errors (https://github.com/jshttp/http-errors).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/http-errors.

### Additional Details
 * Last updated: Tue, 07 Nov 2023 03:09:37 GMT
 * Dependencies: none

# Credits
These definitions were written by [Tanguy Krotoff](https://github.com/tkrotoff), and [BendingBender](https://github.com/BendingBender).


---

# Installation
> `npm install --save @types/http-proxy`

# Summary
This package contains type definitions for http-proxy (https://github.com/nodejitsu/node-http-proxy).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/http-proxy.

### Additional Details
 * Last updated: Fri, 07 Feb 2025 07:02:35 GMT
 * Dependencies: [@types/node](https://npmjs.com/package/@types/node)

# Credits
These definitions were written by [Maxime LUCE](https://github.com/SomaticIT), [Florian Oellerich](https://github.com/Raigen), [Daniel Schmidt](https://github.com/DanielMSchmidt), [Jordan Abreu](https://github.com/jabreu610), and [Samuel Bodin](https://github.com/bodinsamuel).


---

# Installation
> `npm install --save @types/istanbul-lib-coverage`

# Summary
This package contains type definitions for istanbul-lib-coverage (https://istanbul.js.org).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/istanbul-lib-coverage.

### Additional Details
 * Last updated: Tue, 07 Nov 2023 03:09:37 GMT
 * Dependencies: none

# Credits
These definitions were written by [Jason Cheatham](https://github.com/jason0x43).


---

# Installation
> `npm install --save @types/istanbul-lib-report`

# Summary
This package contains type definitions for istanbul-lib-report (https://istanbul.js.org).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/istanbul-lib-report.

### Additional Details
 * Last updated: Tue, 07 Nov 2023 03:09:37 GMT
 * Dependencies: [@types/istanbul-lib-coverage](https://npmjs.com/package/@types/istanbul-lib-coverage)

# Credits
These definitions were written by [Jason Cheatham](https://github.com/jason0x43), and [Zacharias Björngren](https://github.com/zache).


---

# Installation
> `npm install --save @types/istanbul-reports`

# Summary
This package contains type definitions for istanbul-reports (https://github.com/istanbuljs/istanbuljs).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/istanbul-reports.
## [index.d.ts](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/istanbul-reports/index.d.ts)
````ts
import { Node, ReportBase } from "istanbul-lib-report";

export function create<T extends keyof ReportOptions>(name: T, options?: Partial<ReportOptions[T]>): ReportBase;

export interface FileOptions {
    file: string;
}

export interface ProjectOptions {
    projectRoot: string;
}

export interface ReportOptions {
    clover: CloverOptions;
    cobertura: CoberturaOptions;
    "html-spa": HtmlSpaOptions;
    html: HtmlOptions;
    json: JsonOptions;
    "json-summary": JsonSummaryOptions;
    lcov: LcovOptions;
    lcovonly: LcovOnlyOptions;
    none: never;
    teamcity: TeamcityOptions;
    text: TextOptions;
    "text-lcov": TextLcovOptions;
    "text-summary": TextSummaryOptions;
}

export type ReportType = keyof ReportOptions;

export interface CloverOptions extends FileOptions, ProjectOptions {}

export interface CoberturaOptions extends FileOptions, ProjectOptions {}

export interface HtmlSpaOptions extends HtmlOptions {
    metricsToShow: Array<"lines" | "branches" | "functions" | "statements">;
}
export interface HtmlOptions {
    verbose: boolean;
    skipEmpty: boolean;
    subdir: string;
    linkMapper: LinkMapper;
}

export type JsonOptions = FileOptions;
export type JsonSummaryOptions = FileOptions;

export interface LcovOptions extends FileOptions, ProjectOptions {}
export interface LcovOnlyOptions extends FileOptions, ProjectOptions {}

export interface TeamcityOptions extends FileOptions {
    blockName: string;
}

export interface TextOptions extends FileOptions {
    maxCols: number;
    skipEmpty: boolean;
    skipFull: boolean;
}
export type TextLcovOptions = ProjectOptions;
export type TextSummaryOptions = FileOptions;

export interface LinkMapper {
    getPath(node: string | Node): string;
    relativePath(source: string | Node, target: string | Node): string;
    assetPath(node: Node, name: string): string;
}

````

### Additional Details
 * Last updated: Tue, 07 Nov 2023 03:09:37 GMT
 * Dependencies: [@types/istanbul-lib-report](https://npmjs.com/package/@types/istanbul-lib-report)

# Credits
These definitions were written by [Jason Cheatham](https://github.com/jason0x43), and [Elena Shcherbakova](https://github.com/not-a-doctor).


---

# Installation
> `npm install --save @types/json-schema`

# Summary
This package contains type definitions for json-schema 4.0, 6.0 and (https://github.com/kriszyp/json-schema).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/json-schema.

### Additional Details
 * Last updated: Thu, 25 May 2023 20:34:16 GMT
 * Dependencies: none
 * Global values: none

# Credits
These definitions were written by [Boris Cherny](https://github.com/bcherny), [Lucian Buzzo](https://github.com/lucianbuzzo), [Roland Groza](https://github.com/rolandjitsu), and [Jason Kwok](https://github.com/JasonHK).


---

# Installation
> `npm install --save @types/mdast`

# Summary
This package contains type definitions for mdast (https://github.com/syntax-tree/mdast).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/mdast.

### Additional Details
 * Last updated: Tue, 14 May 2024 07:35:36 GMT
 * Dependencies: [@types/unist](https://npmjs.com/package/@types/unist)

# Credits
These definitions were written by [Christian Murphy](https://github.com/ChristianMurphy), [Jun Lu](https://github.com/lujun2), [Remco Haszing](https://github.com/remcohaszing), [Titus Wormer](https://github.com/wooorm), and [Remco Haszing](https://github.com/remcohaszing).


---

# Installation
> `npm install --save @types/mdx`

# Summary
This package contains type definitions for mdx (https://github.com/mdx-js/mdx).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/mdx.

### Additional Details
 * Last updated: Thu, 11 Apr 2024 15:07:22 GMT
 * Dependencies: none

# Credits
These definitions were written by [Christian Murphy](https://github.com/ChristianMurphy), [Remco Haszing](https://github.com/remcohaszing), and [Titus Wormer](https://github.com/wooorm).


---

# Installation
> `npm install --save @types/mime`

# Summary
This package contains type definitions for mime (https://github.com/broofa/node-mime).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/mime/v1.

### Additional Details
 * Last updated: Tue, 07 Nov 2023 20:08:00 GMT
 * Dependencies: none

# Credits
These definitions were written by [Jeff Goddard](https://github.com/jedigo), and [Daniel Hritzkiv](https://github.com/dhritzkiv).


---

# Installation
> `npm install --save @types/ms`

# Summary
This package contains type definitions for ms (https://github.com/vercel/ms).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/ms.
## [index.d.ts](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/ms/index.d.ts)
````ts
/**
 * Short/Long format for `value`.
 *
 * @param {Number} value
 * @param {{long: boolean}} options
 * @return {String}
 */
declare function ms(value: number, options?: { long: boolean }): string;

/**
 * Parse the given `value` and return milliseconds.
 *
 * @param {ms.StringValue} value
 * @return {Number}
 */
declare function ms(value: ms.StringValue): number;

declare namespace ms {
    // Unit, UnitAnyCase, and StringValue are backported from ms@3
    // https://github.com/vercel/ms/blob/8b5923d1d86c84a9f6aba8022d416dcf2361aa8d/src/index.ts

    type Unit =
        | "Years"
        | "Year"
        | "Yrs"
        | "Yr"
        | "Y"
        | "Weeks"
        | "Week"
        | "W"
        | "Days"
        | "Day"
        | "D"
        | "Hours"
        | "Hour"
        | "Hrs"
        | "Hr"
        | "H"
        | "Minutes"
        | "Minute"
        | "Mins"
        | "Min"
        | "M"
        | "Seconds"
        | "Second"
        | "Secs"
        | "Sec"
        | "s"
        | "Milliseconds"
        | "Millisecond"
        | "Msecs"
        | "Msec"
        | "Ms";

    type UnitAnyCase = Unit | Uppercase<Unit> | Lowercase<Unit>;

    type StringValue =
        | `${number}`
        | `${number}${UnitAnyCase}`
        | `${number} ${UnitAnyCase}`;
}

export = ms;

````

### Additional Details
 * Last updated: Thu, 16 Jan 2025 21:02:45 GMT
 * Dependencies: none

# Credits
These definitions were written by [Zhiyuan Wang](https://github.com/danny8002).


---

# Installation
> `npm install --save @types/node`

# Summary
This package contains type definitions for Node.js (https://nodejs.org/).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/node.

### Additional Details
 * Last updated: Wed, 12 Jul 2023 23:02:41 GMT
 * Dependencies: none
 * Global values: `AbortController`, `AbortSignal`, `__dirname`, `__filename`, `console`, `exports`, `gc`, `global`, `module`, `process`, `require`, `structuredClone`

# Credits
These definitions were written by [Microsoft TypeScript](https://github.com/Microsoft), [DefinitelyTyped](https://github.com/DefinitelyTyped), [Alberto Schiabel](https://github.com/jkomyno), [Alvis HT Tang](https://github.com/alvis), [Andrew Makarov](https://github.com/r3nya), [Benjamin Toueg](https://github.com/btoueg), [Chigozirim C.](https://github.com/smac89), [David Junger](https://github.com/touffy), [Deividas Bakanas](https://github.com/DeividasBakanas), [Eugene Y. Q. Shen](https://github.com/eyqs), [Hannes Magnusson](https://github.com/Hannes-Magnusson-CK), [Huw](https://github.com/hoo29), [Kelvin Jin](https://github.com/kjin), [Klaus Meinhardt](https://github.com/ajafff), [Lishude](https://github.com/islishude), [Mariusz Wiktorczyk](https://github.com/mwiktorczyk), [Mohsen Azimi](https://github.com/mohsen1), [Nicolas Even](https://github.com/n-e), [Nikita Galkin](https://github.com/galkin), [Parambir Singh](https://github.com/parambirs), [Sebastian Silbermann](https://github.com/eps1lon), [Simon Schick](https://github.com/SimonSchick), [Thomas den Hollander](https://github.com/ThomasdenH), [Wilco Bakker](https://github.com/WilcoBakker), [wwwy3y3](https://github.com/wwwy3y3), [Samuel Ainsworth](https://github.com/samuela), [Kyle Uehlein](https://github.com/kuehlein), [Thanik Bhongbhibhat](https://github.com/bhongy), [Marcin Kopacz](https://github.com/chyzwar), [Trivikram Kamat](https://github.com/trivikr), [Junxiao Shi](https://github.com/yoursunny), [Ilia Baryshnikov](https://github.com/qwelias), [ExE Boss](https://github.com/ExE-Boss), [Piotr Błażejewicz](https://github.com/peterblazejewicz), [Anna Henningsen](https://github.com/addaleax), [Victor Perin](https://github.com/victorperin), [Yongsheng Zhang](https://github.com/ZYSzys), [NodeJS Contributors](https://github.com/NodeJS), [Linus Unnebäck](https://github.com/LinusU), [wafuwafu13](https://github.com/wafuwafu13), [Matteo Collina](https://github.com/mcollina), and [Dmitry Semigradsky](https://github.com/Semigradsky).


---

# Installation
> `npm install --save @types/node-forge`

# Summary
This package contains type definitions for node-forge (https://github.com/digitalbazaar/forge).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/node-forge.

### Additional Details
 * Last updated: Tue, 02 Jan 2024 22:35:21 GMT
 * Dependencies: [@types/node](https://npmjs.com/package/@types/node)

# Credits
These definitions were written by [Seth Westphal      ](https://github.com/westy92), [Kay Schecker       ](https://github.com/flynetworks), [Aakash Goenka      ](https://github.com/a-k-g), [Rafal2228          ](https://github.com/rafal2228), [Beeno Tung         ](https://github.com/beenotung), [Joe Flateau        ](https://github.com/joeflateau), [timhwang21         ](https://github.com/timhwang21), [Anders Kaseorg     ](https://github.com/andersk), [Sascha Zarhuber    ](https://github.com/saschazar21), [Rogier Schouten    ](https://github.com/rogierschouten), [Ivan Aseev         ](https://github.com/aseevia), [Wiktor Kwapisiewicz](https://github.com/wiktor-k), [Ligia Frangello    ](https://github.com/frangello), [Dmitry Avezov      ](https://github.com/avezov), [Jose Fuentes       ](https://github.com/j-fuentes), [Anya Reyes         ](https://github.com/darkade), and [BendingBender      ](https://github.com/BendingBender).


---

# Installation
> `npm install --save @types/parse-json`

# Summary
This package contains type definitions for parse-json (https://github.com/sindresorhus/parse-json).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/parse-json.
## [index.d.ts](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/parse-json/index.d.ts)
````ts
declare function parseJson(input: string | null, filepath?: string): any;
declare function parseJson(input: string | null, reviver: (key: any, value: any) => any, filepath?: string): any;

export = parseJson;

````

### Additional Details
 * Last updated: Tue, 07 Nov 2023 09:09:39 GMT
 * Dependencies: none

# Credits
These definitions were written by [mrmlnc](https://github.com/mrmlnc).


---

# Installation
> `npm install --save @types/prismjs`

# Summary
This package contains type definitions for prismjs (http://prismjs.com/).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/prismjs.

### Additional Details
 * Last updated: Wed, 23 Oct 2024 03:36:41 GMT
 * Dependencies: none

# Credits
These definitions were written by [Michael Schmidt](https://github.com/RunDevelopment), [ExE Boss](https://github.com/ExE-Boss), [Erik Lieben](https://github.com/eriklieben), [Andre Wiggins](https://github.com/andrewiggins), and [Michał Miszczyszyn](https://github.com/typeofweb).


---

# Installation
> `npm install --save @types/prop-types`

# Summary
This package contains type definitions for prop-types (https://github.com/reactjs/prop-types).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/prop-types.

### Additional Details
 * Last updated: Thu, 07 Apr 2022 17:31:22 GMT
 * Dependencies: none
 * Global values: none

# Credits
These definitions were written by [DovydasNavickas](https://github.com/DovydasNavickas), [Ferdy Budhidharma](https://github.com/ferdaber), and [Sebastian Silbermann](https://github.com/eps1lon).


---

# Installation
> `npm install --save @types/qs`

# Summary
This package contains type definitions for qs (https://github.com/ljharb/qs).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/qs.

### Additional Details
 * Last updated: Tue, 14 Jan 2025 01:30:27 GMT
 * Dependencies: none

# Credits
These definitions were written by [Roman Korneev](https://github.com/RWander), [Leon Yu](https://github.com/leonyu), [Belinda Teh](https://github.com/tehbelinda), [Melvin Lee](https://github.com/zyml), [Arturs Vonda](https://github.com/artursvonda), [Carlos Bonetti](https://github.com/CarlosBonetti), [Dan Smith](https://github.com/dpsmith3), [Hunter Perrin](https://github.com/hperrin), and [Jordan Harband](https://github.com/ljharb).


---

# Installation
> `npm install --save @types/range-parser`

# Summary
This package contains type definitions for range-parser (https://github.com/jshttp/range-parser).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/range-parser.
## [index.d.ts](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/range-parser/index.d.ts)
````ts
/**
 * When ranges are returned, the array has a "type" property which is the type of
 * range that is required (most commonly, "bytes"). Each array element is an object
 * with a "start" and "end" property for the portion of the range.
 *
 * @returns `-1` when unsatisfiable and `-2` when syntactically invalid, ranges otherwise.
 */
declare function RangeParser(
    size: number,
    str: string,
    options?: RangeParser.Options,
): RangeParser.Result | RangeParser.Ranges;

declare namespace RangeParser {
    interface Ranges extends Array<Range> {
        type: string;
    }
    interface Range {
        start: number;
        end: number;
    }
    interface Options {
        /**
         * The "combine" option can be set to `true` and overlapping & adjacent ranges
         * will be combined into a single range.
         */
        combine?: boolean | undefined;
    }
    type ResultUnsatisfiable = -1;
    type ResultInvalid = -2;
    type Result = ResultUnsatisfiable | ResultInvalid;
}

export = RangeParser;

````

### Additional Details
 * Last updated: Tue, 07 Nov 2023 09:09:39 GMT
 * Dependencies: none

# Credits
These definitions were written by [Tomek Łaziuk](https://github.com/tlaziuk).


---

# Installation
> `npm install --save @types/react`

# Summary
This package contains type definitions for React (https://react.dev/).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/react.

### Additional Details
 * Last updated: Thu, 13 Jul 2023 17:02:48 GMT
 * Dependencies: [@types/csstype](https://npmjs.com/package/@types/csstype), [@types/prop-types](https://npmjs.com/package/@types/prop-types), [@types/scheduler](https://npmjs.com/package/@types/scheduler)
 * Global values: `React`

# Credits
These definitions were written by [Asana](https://asana.com), [AssureSign](http://www.assuresign.com), [Microsoft](https://microsoft.com), [John Reilly](https://github.com/johnnyreilly), [Benoit Benezech](https://github.com/bbenezech), [Patricio Zavolinsky](https://github.com/pzavolinsky), [Eric Anderson](https://github.com/ericanderson), [Dovydas Navickas](https://github.com/DovydasNavickas), [Josh Rutherford](https://github.com/theruther4d), [Guilherme Hübner](https://github.com/guilhermehubner), [Ferdy Budhidharma](https://github.com/ferdaber), [Johann Rakotoharisoa](https://github.com/jrakotoharisoa), [Olivier Pascal](https://github.com/pascaloliv), [Martin Hochel](https://github.com/hotell), [Frank Li](https://github.com/franklixuefei), [Jessica Franco](https://github.com/Jessidhia), [Saransh Kataria](https://github.com/saranshkataria), [Kanitkorn Sujautra](https://github.com/lukyth), [Sebastian Silbermann](https://github.com/eps1lon), [Kyle Scully](https://github.com/zieka), [Cong Zhang](https://github.com/dancerphil), [Dimitri Mitropoulos](https://github.com/dimitropoulos), [JongChan Choi](https://github.com/disjukr), [Victor Magalhães](https://github.com/vhfmag), [Dale Tan](https://github.com/hellatan), [Priyanshu Rav](https://github.com/priyanshurav), and [Dmitry Semigradsky](https://github.com/Semigradsky).


---

# Installation
> `npm install --save @types/react-router`

# Summary
This package contains type definitions for React Router (https://github.com/ReactTraining/react-router).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/react-router.

### Additional Details
 * Last updated: Fri, 23 Dec 2022 11:02:45 GMT
 * Dependencies: [@types/history](https://npmjs.com/package/@types/history), [@types/react](https://npmjs.com/package/@types/react)
 * Global values: none

# Credits
These definitions were written by [Sergey Buturlakin](https://github.com/sergey-buturlakin), [Yuichi Murata](https://github.com/mrk21), [Václav Ostrožlík](https://github.com/vasek17), [Nathan Brown](https://github.com/ngbrown), [Alex Wendland](https://github.com/awendland), [Kostya Esmukov](https://github.com/KostyaEsmukov), [John Reilly](https://github.com/johnnyreilly), [Karol Janyst](https://github.com/LKay), [Dovydas Navickas](https://github.com/DovydasNavickas), [Huy Nguyen](https://github.com/huy-nguyen), [Jérémy Fauvel](https://github.com/grmiade), [Daniel Roth](https://github.com/DaIgeb), [Egor Shulga](https://github.com/egorshulga), [Rahul Raina](https://github.com/rraina), [Duong Tran](https://github.com/t49tran), [Ben Smith](https://github.com/8enSmith), [Wesley Tsai](https://github.com/wezleytsai), [Sebastian Silbermann](https://github.com/eps1lon), [Nicholas Hehr](https://github.com/HipsterBrown), and [Pawel Fajfer](https://github.com/pawfa).


---

# Installation
> `npm install --save @types/react-router-config`

# Summary
This package contains type definitions for react-router-config (https://github.com/ReactTraining/react-router/tree/master/packages/react-router-config).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/react-router-config.
## [index.d.ts](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/react-router-config/index.d.ts)
````ts
// Type definitions for react-router-config 5.0
// Project: https://github.com/ReactTraining/react-router/tree/master/packages/react-router-config, https://github.com/reacttraining/react-router
// Definitions by: John Reilly <https://github.com/johnnyreilly>
//                 Mathieu TUDISCO <https://github.com/mathieutu>
// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
// TypeScript Version: 2.8

import * as React from 'react';
import { RouteComponentProps, SwitchProps, match } from 'react-router';
import { Location } from 'history';

export interface RouteConfigComponentProps<Params extends { [K in keyof Params]?: string } = {}>
    extends RouteComponentProps<Params> {
    route?: RouteConfig | undefined;
}

export interface RouteConfig {
    key?: React.Key | undefined;
    location?: Location | undefined;
    component?: React.ComponentType<RouteConfigComponentProps<any>> | React.ComponentType | undefined;
    path?: string | string[] | undefined;
    exact?: boolean | undefined;
    strict?: boolean | undefined;
    routes?: RouteConfig[] | undefined;
    render?: ((props: RouteConfigComponentProps<any>) => React.ReactNode) | undefined;
    [propName: string]: any;
}

export interface MatchedRoute<
    Params extends { [K in keyof Params]?: string },
    TRouteConfig extends RouteConfig = RouteConfig
> {
    route: TRouteConfig;
    match: match<Params>;
}

export function matchRoutes<
    Params extends { [K in keyof Params]?: string },
    TRouteConfig extends RouteConfig = RouteConfig
>(routes: TRouteConfig[], pathname: string): Array<MatchedRoute<Params, TRouteConfig>>;

export function renderRoutes(
    routes: RouteConfig[] | undefined,
    extraProps?: any,
    switchProps?: SwitchProps,
): JSX.Element;

````

### Additional Details
 * Last updated: Wed, 05 Apr 2023 19:33:19 GMT
 * Dependencies: [@types/history](https://npmjs.com/package/@types/history), [@types/react](https://npmjs.com/package/@types/react), [@types/react-router](https://npmjs.com/package/@types/react-router)
 * Global values: none

# Credits
These definitions were written by [John Reilly](https://github.com/johnnyreilly), and [Mathieu TUDISCO](https://github.com/mathieutu).


---

# Installation
> `npm install --save @types/react-router-dom`

# Summary
This package contains type definitions for react-router-dom (https://github.com/ReactTraining/react-router).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/react-router-dom.

### Additional Details
 * Last updated: Tue, 18 Jan 2022 22:01:52 GMT
 * Dependencies: [@types/react-router](https://npmjs.com/package/@types/react-router), [@types/react](https://npmjs.com/package/@types/react), [@types/history](https://npmjs.com/package/@types/history)
 * Global values: none

# Credits
These definitions were written by [Huy Nguyen](https://github.com/huy-nguyen), [Philip Jackson](https://github.com/p-jackson), [John Reilly](https://github.com/johnnyreilly), [Sebastian Silbermann](https://github.com/eps1lon), [Daniel Nixon](https://github.com/danielnixon), [Tony Ward](https://github.com/ynotdraw), and [Pirasis Leelatanon](https://github.com/1pete).


---

# Installation
> `npm install --save @types/retry`

# Summary
This package contains type definitions for retry (https://github.com/tim-kos/node-retry).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/retry

Additional Details
 * Last updated: Thu, 03 Jan 2019 17:45:51 GMT
 * Dependencies: none
 * Global values: none

# Credits
These definitions were written by Stan Goldmann <https://github.com/krenor>, BendingBender <https://github.com/BendingBender>.


---

# Installation
> `npm install --save @types/sax`

# Summary
This package contains type definitions for sax (https://github.com/isaacs/sax-js).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/sax.

### Additional Details
 * Last updated: Tue, 07 Nov 2023 15:11:36 GMT
 * Dependencies: [@types/node](https://npmjs.com/package/@types/node)

# Credits
These definitions were written by [Vincent Siao (Asana, Inc.)](https://github.com/vsiao), [Evert Pot](https://github.com/evert), [Daniel Cassidy](https://github.com/djcsdy), and [Fabian van der Veen](https://github.com/fvanderveen).


---

# Installation
> `npm install --save @types/scheduler`

# Summary
This package contains type definitions for scheduler (https://reactjs.org/).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/scheduler.

### Additional Details
 * Last updated: Wed, 22 Mar 2023 23:02:44 GMT
 * Dependencies: none
 * Global values: none

# Credits
These definitions were written by [Nathan Bierema](https://github.com/Methuselah96), and [Sebastian Silbermann](https://github.com/eps1lon).


---

# Installation
> `npm install --save @types/send`

# Summary
This package contains type definitions for send (https://github.com/pillarjs/send).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/send.

### Additional Details
 * Last updated: Tue, 07 Nov 2023 15:11:36 GMT
 * Dependencies: [@types/mime](https://npmjs.com/package/@types/mime), [@types/node](https://npmjs.com/package/@types/node)

# Credits
These definitions were written by [Mike Jerred](https://github.com/MikeJerred), and [Piotr Błażejewicz](https://github.com/peterblazejewicz).


---

# Installation
> `npm install --save @types/serve-index`

# Summary
This package contains type definitions for serve-index (https://github.com/expressjs/serve-index).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/serve-index.
## [index.d.ts](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/serve-index/index.d.ts)
````ts
import { Handler } from "express";
import { Stats } from "fs";

/** Serves pages that contain directory listings for a given path. */
declare function serveIndex(path: string, options?: serveIndex.Options): Handler;

declare namespace serveIndex {
    interface File {
        name: string;
        stat: Stats;
    }

    interface Locals {
        directory: string;
        displayIcons: boolean;
        fileList: File[];
        name: string;
        stat: Stats;
        path: string;
        style: string;
        viewName: string;
    }

    type TemplateCallback = (error: Error | null, htmlString?: string) => void;

    interface Options {
        filter?: ((filename: string, index: number, files: File[], dir: string) => boolean) | undefined;
        hidden?: boolean | undefined;
        icons?: boolean | undefined;
        stylesheet?: string | undefined;
        template?: string | ((locals: Locals, callback: TemplateCallback) => void) | undefined;
        view?: string | undefined;
    }
}

export = serveIndex;

````

### Additional Details
 * Last updated: Tue, 07 Nov 2023 15:11:36 GMT
 * Dependencies: [@types/express](https://npmjs.com/package/@types/express)

# Credits
These definitions were written by [Tanguy Krotoff](https://github.com/tkrotoff).


---

# Installation
> `npm install --save @types/serve-static`

# Summary
This package contains type definitions for serve-static (https://github.com/expressjs/serve-static).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/serve-static.

### Additional Details
 * Last updated: Wed, 03 Apr 2024 06:07:52 GMT
 * Dependencies: [@types/http-errors](https://npmjs.com/package/@types/http-errors), [@types/node](https://npmjs.com/package/@types/node), [@types/send](https://npmjs.com/package/@types/send)

# Credits
These definitions were written by [Uros Smolnik](https://github.com/urossmolnik), [Linus Unnebäck](https://github.com/LinusU), and [Devansh Jethmalani](https://github.com/devanshj).


---

# Installation
> `npm install --save @types/sockjs`

# Summary
This package contains type definitions for sockjs (https://github.com/sockjs/sockjs-node).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/sockjs.
## [index.d.ts](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/sockjs/index.d.ts)
````ts
/// <reference types="node" />

import http = require("http");

export interface ServerOptions {
    sockjs_url?: string | undefined;
    prefix?: string | undefined;
    response_limit?: number | undefined;
    websocket?: boolean | undefined;
    jsessionid?: any;
    log?(severity: string, message: string): void;
    heartbeat_delay?: number | undefined;
    disconnect_delay?: number | undefined;
}

export function createServer(options?: ServerOptions): Server;

export interface Server extends NodeJS.EventEmitter {
    installHandlers(server: http.Server, options?: ServerOptions): any;

    on(event: "connection", listener: (conn: Connection) => any): this;
    on(event: string, listener: Function): this;
}

export interface Connection extends NodeJS.ReadWriteStream {
    remoteAddress: string;
    remotePort: number;
    address: {
        [key: string]: {
            address: string;
            port: number;
        };
    };
    headers: {
        [key: string]: string;
    };
    url: string;
    pathname: string;
    prefix: string;
    protocol: string;
    readyState: number;
    id: string;

    close(code?: string, reason?: string): boolean;
    destroy(): void;

    on(event: "data", listener: (message: string) => any): this;
    on(event: "close", listener: () => void): this;
    on(event: string, listener: Function): this;
}

````

### Additional Details
 * Last updated: Tue, 07 Nov 2023 15:11:36 GMT
 * Dependencies: [@types/node](https://npmjs.com/package/@types/node)

# Credits
These definitions were written by [Phil McCloghry-Laing](https://github.com/pmccloghrylaing).


---

# Installation
> `npm install --save @types/unist`

# Summary
This package contains type definitions for unist (https://github.com/syntax-tree/unist).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/unist.

### Additional Details
 * Last updated: Thu, 15 Aug 2024 02:18:53 GMT
 * Dependencies: none

# Credits
These definitions were written by [bizen241](https://github.com/bizen241), [Jun Lu](https://github.com/lujun2), [Hernan Rajchert](https://github.com/hrajchert), [Titus Wormer](https://github.com/wooorm), [Junyoung Choi](https://github.com/rokt33r), [Ben Moon](https://github.com/GuiltyDolphin), [JounQin](https://github.com/JounQin), and [Remco Haszing](https://github.com/remcohaszing).


---

# Installation
> `npm install --save @types/ws`

# Summary
This package contains type definitions for ws (https://github.com/websockets/ws).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/ws.

### Additional Details
 * Last updated: Tue, 01 Apr 2025 02:59:53 GMT
 * Dependencies: [@types/node](https://npmjs.com/package/@types/node)

# Credits
These definitions were written by [Paul Loyd](https://github.com/loyd), [Margus Lamp](https://github.com/mlamp), [Philippe D'Alva](https://github.com/TitaneBoy), [reduckted](https://github.com/reduckted), [teidesu](https://github.com/teidesu), [Bartosz Wojtkowiak](https://github.com/wojtkowiak), [Kyle Hensel](https://github.com/k-yle), and [Samuel Skeen](https://github.com/cwadrupldijjit).


---

# Installation
> `npm install --save @types/yargs`

# Summary
This package contains type definitions for yargs (https://github.com/chevex/yargs).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/yargs.

### Additional Details
 * Last updated: Tue, 06 Aug 2024 20:07:10 GMT
 * Dependencies: [@types/yargs-parser](https://npmjs.com/package/@types/yargs-parser)

# Credits
These definitions were written by [Martin Poelstra](https://github.com/poelstra), [Mizunashi Mana](https://github.com/mizunashi-mana), [Jeffery Grajkowski](https://github.com/pushplay), [Jimi (Dimitris) Charalampidis](https://github.com/JimiC), [Steffen Viken Valvåg](https://github.com/steffenvv), [Emily Marigold Klassen](https://github.com/forivall), [ExE Boss](https://github.com/ExE-Boss), [Aankhen](https://github.com/Aankhen), and [Ben Coe](https://github.com/bcoe).


---

# Installation
> `npm install --save @types/yargs-parser`

# Summary
This package contains type definitions for yargs-parser (https://github.com/yargs/yargs-parser#readme).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/yargs-parser.

### Additional Details
 * Last updated: Tue, 07 Nov 2023 21:36:25 GMT
 * Dependencies: none

# Credits
These definitions were written by [Miles Johnson](https://github.com/milesj).


---

# structuredClone polyfill

[![Downloads](https://img.shields.io/npm/dm/@ungap/structured-clone.svg)](https://www.npmjs.com/package/@ungap/structured-clone) [![build status](https://github.com/ungap/structured-clone/actions/workflows/node.js.yml/badge.svg)](https://github.com/ungap/structured-clone/actions) [![Coverage Status](https://coveralls.io/repos/github/ungap/structured-clone/badge.svg?branch=main)](https://coveralls.io/github/ungap/structured-clone?branch=main)

An env agnostic serializer and deserializer with recursion ability and types beyond *JSON* from the *HTML* standard itself.

  * [Supported Types](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm#supported_types)
    * *not supported yet*: Blob, File, FileList, ImageBitmap, ImageData or others non *JS* types but typed arrays are supported without major issues, but u/int8, u/int16, and u/int32 are the only safely suppored (right now).
    * *not possible to implement*: the `{transfer: []}` option can be passed but it's completely ignored.
  * [MDN Documentation](https://developer.mozilla.org/en-US/docs/Web/API/structuredClone)
  * [Serializer](https://html.spec.whatwg.org/multipage/structured-data.html#structuredserializeinternal)
  * [Deserializer](https://html.spec.whatwg.org/multipage/structured-data.html#structureddeserialize)

Serialized values can be safely stringified as *JSON* too, and deserialization resurrect all values, even recursive, or more complex than what *JSON* allows.


### Examples

Check the [100% test coverage](./test/index.js) to know even more.

```js
// as default export
import structuredClone from '@ungap/structured-clone';
const cloned = structuredClone({any: 'serializable'});

// as independent serializer/deserializer
import {serialize, deserialize} from '@ungap/structured-clone';

// the result can be stringified as JSON without issues
// even if there is recursive data, bigint values,
// typed arrays, and so on
const serialized = serialize({any: 'serializable'});

// the result will be a replica of the original object
const deserialized = deserialize(serialized);
```

#### Global Polyfill
Note: Only monkey patch the global if needed. This polyfill works just fine as an explicit import: `import structuredClone from "@ungap/structured-clone"`
```js
// Attach the polyfill as a Global function
import structuredClone from "@ungap/structured-clone";
if (!("structuredClone" in globalThis)) {
  globalThis.structuredClone = structuredClone;
}

// Or don't monkey patch
import structuredClone from "@ungap/structured-clone"
// Just use it in the file
structuredClone()
```

**Note**: Do not attach this module's default export directly to the global scope, whithout a conditional guard to detect a native implementation. In environments where there is a native global implementation of `structuredClone()` already, assignment to the global object will result in an infinite loop when `globalThis.structuredClone()` is called. See the example above for a safe way to provide the polyfill globally in your project.

### Extra Features

There is no middle-ground between the structured clone algorithm and JSON:

  * JSON is more relaxed about incompatible values: it just ignores these
  * Structured clone is inflexible regarding incompatible values, yet it makes specialized instances impossible to reconstruct, plus it doesn't offer any helper, such as `toJSON()`, to make serialization possible, or better, with specific cases

This module specialized `serialize` export offers, within the optional extra argument, a **lossy** property to avoid throwing when incompatible types are found down the road (function, symbol, ...), so that it is possible to send with less worrying about thrown errors.

```js
// as default export
import structuredClone from '@ungap/structured-clone';
const cloned = structuredClone(
  {
    method() {
      // ignored, won't be cloned
    },
    special: Symbol('also ignored')
  },
  {
    // avoid throwing
    lossy: true,
    // avoid throwing *and* looks for toJSON
    json: true
  }
);
```

The behavior is the same found in *JSON* when it comes to *Array*, so that unsupported values will result as `null` placeholders instead.

#### toJSON

If `lossy` option is not enough, `json` will actually enforce `lossy` and also check for `toJSON` method when objects are parsed.

Alternative, the `json` exports combines all features:

```js
import {stringify, parse} from '@ungap/structured-clone/json';

parse(stringify({any: 'serializable'}));
```


---

# @webassemblyjs/ast

> AST utils for webassemblyjs

## Installation

```sh
yarn add @webassemblyjs/ast
```

## Usage

### Traverse

```js
import { traverse } from "@webassemblyjs/ast";

traverse(ast, {
  Module(path) {
    console.log(path.node);
  }
});
```

### Instruction signatures

```js
import { signatures } from "@webassemblyjs/ast";

console.log(signatures);
```

### Path methods

- `findParent: NodeLocator`
- `replaceWith: Node => void`
- `remove: () => void`
- `insertBefore: Node => void`
- `insertAfter: Node => void`
- `stop: () => void`

### AST utils

- function `module(id, fields, metadata)`
- function `moduleMetadata(sections, functionNames, localNames)`
- function `moduleNameMetadata(value)`
- function `functionNameMetadata(value, index)`
- function `localNameMetadata(value, localIndex, functionIndex)`
- function `binaryModule(id, blob)`
- function `quoteModule(id, string)`
- function `sectionMetadata(section, startOffset, size, vectorOfSize)`
- function `loopInstruction(label, resulttype, instr)`
- function `instruction(id, args, namedArgs)`
- function `objectInstruction(id, object, args, namedArgs)`
- function `ifInstruction(testLabel, test, result, consequent, alternate)`
- function `stringLiteral(value)`
- function `numberLiteralFromRaw(value, raw)`
- function `longNumberLiteral(value, raw)`
- function `floatLiteral(value, nan, inf, raw)`
- function `elem(table, offset, funcs)`
- function `indexInFuncSection(index)`
- function `valtypeLiteral(name)`
- function `typeInstruction(id, functype)`
- function `start(index)`
- function `globalType(valtype, mutability)`
- function `leadingComment(value)`
- function `blockComment(value)`
- function `data(memoryIndex, offset, init)`
- function `global(globalType, init, name)`
- function `table(elementType, limits, name, elements)`
- function `memory(limits, id)`
- function `funcImportDescr(id, signature)`
- function `moduleImport(module, name, descr)`
- function `moduleExportDescr(exportType, id)`
- function `moduleExport(name, descr)`
- function `limit(min, max)`
- function `signature(params, results)`
- function `program(body)`
- function `identifier(value, raw)`
- function `blockInstruction(label, instr, result)`
- function `callInstruction(index, instrArgs)`
- function `callIndirectInstruction(signature, intrs)`
- function `byteArray(values)`
- function `func(name, signature, body, isExternal, metadata)`
- Constant`isModule`
- Constant`isModuleMetadata`
- Constant`isModuleNameMetadata`
- Constant`isFunctionNameMetadata`
- Constant`isLocalNameMetadata`
- Constant`isBinaryModule`
- Constant`isQuoteModule`
- Constant`isSectionMetadata`
- Constant`isLoopInstruction`
- Constant`isInstruction`
- Constant`isObjectInstruction`
- Constant`isIfInstruction`
- Constant`isStringLiteral`
- Constant`isNumberLiteral`
- Constant`isLongNumberLiteral`
- Constant`isFloatLiteral`
- Constant`isElem`
- Constant`isIndexInFuncSection`
- Constant`isValtypeLiteral`
- Constant`isTypeInstruction`
- Constant`isStart`
- Constant`isGlobalType`
- Constant`isLeadingComment`
- Constant`isBlockComment`
- Constant`isData`
- Constant`isGlobal`
- Constant`isTable`
- Constant`isMemory`
- Constant`isFuncImportDescr`
- Constant`isModuleImport`
- Constant`isModuleExportDescr`
- Constant`isModuleExport`
- Constant`isLimit`
- Constant`isSignature`
- Constant`isProgram`
- Constant`isIdentifier`
- Constant`isBlockInstruction`
- Constant`isCallInstruction`
- Constant`isCallIndirectInstruction`
- Constant`isByteArray`
- Constant`isFunc`
- Constant`assertModule`
- Constant`assertModuleMetadata`
- Constant`assertModuleNameMetadata`
- Constant`assertFunctionNameMetadata`
- Constant`assertLocalNameMetadata`
- Constant`assertBinaryModule`
- Constant`assertQuoteModule`
- Constant`assertSectionMetadata`
- Constant`assertLoopInstruction`
- Constant`assertInstruction`
- Constant`assertObjectInstruction`
- Constant`assertIfInstruction`
- Constant`assertStringLiteral`
- Constant`assertNumberLiteral`
- Constant`assertLongNumberLiteral`
- Constant`assertFloatLiteral`
- Constant`assertElem`
- Constant`assertIndexInFuncSection`
- Constant`assertValtypeLiteral`
- Constant`assertTypeInstruction`
- Constant`assertStart`
- Constant`assertGlobalType`
- Constant`assertLeadingComment`
- Constant`assertBlockComment`
- Constant`assertData`
- Constant`assertGlobal`
- Constant`assertTable`
- Constant`assertMemory`
- Constant`assertFuncImportDescr`
- Constant`assertModuleImport`
- Constant`assertModuleExportDescr`
- Constant`assertModuleExport`
- Constant`assertLimit`
- Constant`assertSignature`
- Constant`assertProgram`
- Constant`assertIdentifier`
- Constant`assertBlockInstruction`
- Constant`assertCallInstruction`
- Constant`assertCallIndirectInstruction`
- Constant`assertByteArray`
- Constant`assertFunc`



---

# Parser function for floating point hexadecimals

[![license](https://img.shields.io/github/license/maurobringolf/@webassemblyjs/floating-point-hex-parser.svg)]()
[![GitHub last commit](https://img.shields.io/github/last-commit/maurobringolf/@webassemblyjs/floating-point-hex-parser.svg)]()
[![npm](https://img.shields.io/npm/v/@webassemblyjs/floating-point-hex-parser.svg)]()

> A JavaScript function to parse floating point hexadecimals as defined by the [WebAssembly specification](https://webassembly.github.io/spec/core/text/values.html#text-hexfloat).

## Usage

```javascript
import parseHexFloat from '@webassemblyjs/floating-point-hex-parser'

parseHexFloat('0x1p-1')               // 0.5
parseHexFloat('0x1.921fb54442d18p+2') // 6.283185307179586
```

## Tests

This module is tested in two ways. The first one is through a small set of test cases that can be found in [test/regular.test.js](https://github.com/maurobringolf/@webassemblyjs/floating-point-hex-parser/blob/master/test/regular.test.js). The second one is non-deterministic (sometimes called *fuzzing*):

1. Generate a random IEEE754 double precision value `x`.
1. Compute its representation `y` in floating point hexadecimal format using the C standard library function `printf` since C supports this format.
1. Give both values to JS testcase and see if `parseHexFloat(y) === x`.

By default one `npm test` run tests 100 random samples. If you want to do more, you can set the environment variable `FUZZ_AMOUNT` to whatever number of runs you'd like. Because it uses one child process for each sample, it is really slow though. For more details about the randomized tests see [the source](https://github.com/maurobringolf/@webassemblyjs/floating-point-hex-parser/tree/master/test/fuzzing).

## Links

* [maurobringolf.ch/2017/12/hexadecimal-floating-point-notation/](https://maurobringolf.ch/2017/12/hexadecimal-floating-point-notation/)

* [github.com/xtuc/js-webassembly-interpreter/issues/32](https://github.com/xtuc/js-webassembly-interpreter/issues/32)

* [github.com/WebAssembly/design/issues/292](https://github.com/WebAssembly/design/issues/292)


---

# @webassemblyjs/wasm-edit

> Rewrite a WASM binary

Replace in-place an AST node in the binary.

## Installation

```sh
yarn add @webassemblyjs/wasm-edit
```

## Usage

Update:

```js
import { edit } from "@webassemblyjs/wasm-edit";

const binary = [/*...*/];

const visitors = {
  ModuleImport({ node }) {
    node.module = "foo";
    node.name = "bar";
  }
};

const newBinary = edit(binary, visitors);
```

Replace:

```js
import { edit } from "@webassemblyjs/wasm-edit";

const binary = [/*...*/];

const visitors = {
  Instr(path) {
    const newNode = t.callInstruction(t.indexLiteral(0));
    path.replaceWith(newNode);
  }
};

const newBinary = edit(binary, visitors);
```

Remove:

```js
import { edit } from "@webassemblyjs/wasm-edit";

const binary = [/*...*/];

const visitors = {
  ModuleExport({ node }) {
    path.remove()
  }
};

const newBinary = edit(binary, visitors);
```

Insert:

```js
import { add } from "@webassemblyjs/wasm-edit";

const binary = [/*...*/];

const newBinary = add(actualBinary, [
  t.moduleImport("env", "mem", t.memory(t.limit(1)))
]);
```

## Providing the AST

Providing an AST allows you to handle the decoding yourself, here is the API:

```js
addWithAST(Program, ArrayBuffer, Array<Node>): ArrayBuffer;
editWithAST(Program, ArrayBuffer, visitors): ArrayBuffer;
```

Note that the AST will be updated in-place.


---

# @webassemblyjs/wasm-parser

> WebAssembly binary format parser

## Installation

```sh
yarn add @webassemblyjs/wasm-parser
```

## Usage

```js
import { decode } from "@webassemblyjs/wasm-parser";
import { readFileSync } from "fs";

const binary = readFileSync("/path/to/module.wasm");

const decoderOpts = {};
const ast = decode(binary, decoderOpts);
```

### Decoder options

- `dump`: print dump information while decoding (default `false`)
- `ignoreCodeSection`: ignore the code section (default `false`)
- `ignoreDataSection`: ignore the data section (default `false`)



---

# @webassemblyjs/wast-parser

> WebAssembly text format printer

## Installation

```sh
yarn add @webassemblyjs/wast-printer
```

## Usage

```js
import { print } from "@webassemblyjs/wast-printer"

console.log(print(ast));
```


---

# ieee754 [![travis][travis-image]][travis-url] [![npm][npm-image]][npm-url] [![downloads][downloads-image]][downloads-url] [![javascript style guide][standard-image]][standard-url]

[travis-image]: https://img.shields.io/travis/feross/ieee754/master.svg
[travis-url]: https://travis-ci.org/feross/ieee754
[npm-image]: https://img.shields.io/npm/v/ieee754.svg
[npm-url]: https://npmjs.org/package/ieee754
[downloads-image]: https://img.shields.io/npm/dm/ieee754.svg
[downloads-url]: https://npmjs.org/package/ieee754
[standard-image]: https://img.shields.io/badge/code_style-standard-brightgreen.svg
[standard-url]: https://standardjs.com

[![saucelabs][saucelabs-image]][saucelabs-url]

[saucelabs-image]: https://saucelabs.com/browser-matrix/ieee754.svg
[saucelabs-url]: https://saucelabs.com/u/ieee754

### Read/write IEEE754 floating point numbers from/to a Buffer or array-like object.

## install

```
npm install ieee754
```

## methods

`var ieee754 = require('ieee754')`

The `ieee754` object has the following functions:

```
ieee754.read = function (buffer, offset, isLE, mLen, nBytes)
ieee754.write = function (buffer, value, offset, isLE, mLen, nBytes)
```

The arguments mean the following:

- buffer = the buffer
- offset = offset into the buffer
- value = value to set (only for `write`)
- isLe = is little endian?
- mLen = mantissa length
- nBytes = number of bytes

## what is ieee754?

The IEEE Standard for Floating-Point Arithmetic (IEEE 754) is a technical standard for floating-point computation. [Read more](http://en.wikipedia.org/wiki/IEEE_floating_point).

## license

BSD 3 Clause. Copyright (c) 2008, Fair Oaks Labs, Inc.


---

long.js
=======

A Long class for representing a 64 bit two's-complement integer value derived from the [Closure Library](https://github.com/google/closure-library)
for stand-alone use and extended with unsigned support.

[![npm](https://img.shields.io/npm/v/long.svg)](https://www.npmjs.com/package/long) [![Build Status](https://travis-ci.org/dcodeIO/long.js.svg)](https://travis-ci.org/dcodeIO/long.js)

Background
----------

As of [ECMA-262 5th Edition](http://ecma262-5.com/ELS5_HTML.htm#Section_8.5), "all the positive and negative integers
whose magnitude is no greater than 2<sup>53</sup> are representable in the Number type", which is "representing the
doubleprecision 64-bit format IEEE 754 values as specified in the IEEE Standard for Binary Floating-Point Arithmetic".
The [maximum safe integer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER)
in JavaScript is 2<sup>53</sup>-1.

Example: 2<sup>64</sup>-1 is 1844674407370955**1615** but in JavaScript it evaluates to 1844674407370955**2000**.

Furthermore, bitwise operators in JavaScript "deal only with integers in the range −2<sup>31</sup> through
2<sup>31</sup>−1, inclusive, or in the range 0 through 2<sup>32</sup>−1, inclusive. These operators accept any value of
the Number type but first convert each such value to one of 2<sup>32</sup> integer values."

In some use cases, however, it is required to be able to reliably work with and perform bitwise operations on the full
64 bits. This is where long.js comes into play.

Usage
-----

The class is compatible with CommonJS and AMD loaders and is exposed globally as `Long` if neither is available.

```javascript
var Long = require("long");

var longVal = new Long(0xFFFFFFFF, 0x7FFFFFFF);

console.log(longVal.toString());
...
```

API
---

### Constructor

* new **Long**(low: `number`, high: `number`, unsigned?: `boolean`)<br />
  Constructs a 64 bit two's-complement integer, given its low and high 32 bit values as *signed* integers. See the from* functions below for more convenient ways of constructing Longs.

### Fields

* Long#**low**: `number`<br />
  The low 32 bits as a signed value.

* Long#**high**: `number`<br />
  The high 32 bits as a signed value.

* Long#**unsigned**: `boolean`<br />
  Whether unsigned or not.

### Constants

* Long.**ZERO**: `Long`<br />
  Signed zero.

* Long.**ONE**: `Long`<br />
  Signed one.

* Long.**NEG_ONE**: `Long`<br />
  Signed negative one.

* Long.**UZERO**: `Long`<br />
  Unsigned zero.

* Long.**UONE**: `Long`<br />
  Unsigned one.

* Long.**MAX_VALUE**: `Long`<br />
  Maximum signed value.

* Long.**MIN_VALUE**: `Long`<br />
  Minimum signed value.

* Long.**MAX_UNSIGNED_VALUE**: `Long`<br />
  Maximum unsigned value.

### Utility

* Long.**isLong**(obj: `*`): `boolean`<br />
  Tests if the specified object is a Long.

* Long.**fromBits**(lowBits: `number`, highBits: `number`, unsigned?: `boolean`): `Long`<br />
  Returns a Long representing the 64 bit integer that comes by concatenating the given low and high bits. Each is assumed to use 32 bits.

* Long.**fromBytes**(bytes: `number[]`, unsigned?: `boolean`, le?: `boolean`): `Long`<br />
  Creates a Long from its byte representation.

* Long.**fromBytesLE**(bytes: `number[]`, unsigned?: `boolean`): `Long`<br />
  Creates a Long from its little endian byte representation.

* Long.**fromBytesBE**(bytes: `number[]`, unsigned?: `boolean`): `Long`<br />
  Creates a Long from its big endian byte representation.

* Long.**fromInt**(value: `number`, unsigned?: `boolean`): `Long`<br />
  Returns a Long representing the given 32 bit integer value.

* Long.**fromNumber**(value: `number`, unsigned?: `boolean`): `Long`<br />
  Returns a Long representing the given value, provided that it is a finite number. Otherwise, zero is returned.

* Long.**fromString**(str: `string`, unsigned?: `boolean`, radix?: `number`)<br />
  Long.**fromString**(str: `string`, radix: `number`)<br />
  Returns a Long representation of the given string, written using the specified radix.

* Long.**fromValue**(val: `*`, unsigned?: `boolean`): `Long`<br />
  Converts the specified value to a Long using the appropriate from* function for its type.

### Methods

* Long#**add**(addend: `Long | number | string`): `Long`<br />
  Returns the sum of this and the specified Long.

* Long#**and**(other: `Long | number | string`): `Long`<br />
  Returns the bitwise AND of this Long and the specified.

* Long#**compare**/**comp**(other: `Long | number | string`): `number`<br />
  Compares this Long's value with the specified's. Returns `0` if they are the same, `1` if the this is greater and `-1` if the given one is greater.

* Long#**divide**/**div**(divisor: `Long | number | string`): `Long`<br />
  Returns this Long divided by the specified.

* Long#**equals**/**eq**(other: `Long | number | string`): `boolean`<br />
  Tests if this Long's value equals the specified's.

* Long#**getHighBits**(): `number`<br />
  Gets the high 32 bits as a signed integer.

* Long#**getHighBitsUnsigned**(): `number`<br />
  Gets the high 32 bits as an unsigned integer.

* Long#**getLowBits**(): `number`<br />
  Gets the low 32 bits as a signed integer.

* Long#**getLowBitsUnsigned**(): `number`<br />
  Gets the low 32 bits as an unsigned integer.

* Long#**getNumBitsAbs**(): `number`<br />
  Gets the number of bits needed to represent the absolute value of this Long.

* Long#**greaterThan**/**gt**(other: `Long | number | string`): `boolean`<br />
  Tests if this Long's value is greater than the specified's.

* Long#**greaterThanOrEqual**/**gte**/**ge**(other: `Long | number | string`): `boolean`<br />
  Tests if this Long's value is greater than or equal the specified's.

* Long#**isEven**(): `boolean`<br />
  Tests if this Long's value is even.

* Long#**isNegative**(): `boolean`<br />
  Tests if this Long's value is negative.

* Long#**isOdd**(): `boolean`<br />
  Tests if this Long's value is odd.

* Long#**isPositive**(): `boolean`<br />
  Tests if this Long's value is positive.

* Long#**isZero**/**eqz**(): `boolean`<br />
  Tests if this Long's value equals zero.

* Long#**lessThan**/**lt**(other: `Long | number | string`): `boolean`<br />
  Tests if this Long's value is less than the specified's.

* Long#**lessThanOrEqual**/**lte**/**le**(other: `Long | number | string`): `boolean`<br />
  Tests if this Long's value is less than or equal the specified's.

* Long#**modulo**/**mod**/**rem**(divisor: `Long | number | string`): `Long`<br />
  Returns this Long modulo the specified.

* Long#**multiply**/**mul**(multiplier: `Long | number | string`): `Long`<br />
  Returns the product of this and the specified Long.

* Long#**negate**/**neg**(): `Long`<br />
  Negates this Long's value.

* Long#**not**(): `Long`<br />
  Returns the bitwise NOT of this Long.

* Long#**notEquals**/**neq**/**ne**(other: `Long | number | string`): `boolean`<br />
  Tests if this Long's value differs from the specified's.

* Long#**or**(other: `Long | number | string`): `Long`<br />
  Returns the bitwise OR of this Long and the specified.

* Long#**shiftLeft**/**shl**(numBits: `Long | number | string`): `Long`<br />
  Returns this Long with bits shifted to the left by the given amount.

* Long#**shiftRight**/**shr**(numBits: `Long | number | string`): `Long`<br />
  Returns this Long with bits arithmetically shifted to the right by the given amount.

* Long#**shiftRightUnsigned**/**shru**/**shr_u**(numBits: `Long | number | string`): `Long`<br />
  Returns this Long with bits logically shifted to the right by the given amount.

* Long#**rotateLeft**/**rotl**(numBits: `Long | number | string`): `Long`<br />
  Returns this Long with bits rotated to the left by the given amount.

* Long#**rotateRight**/**rotr**(numBits: `Long | number | string`): `Long`<br />
  Returns this Long with bits rotated to the right by the given amount.

* Long#**subtract**/**sub**(subtrahend: `Long | number | string`): `Long`<br />
  Returns the difference of this and the specified Long.

* Long#**toBytes**(le?: `boolean`): `number[]`<br />
  Converts this Long to its byte representation.

* Long#**toBytesLE**(): `number[]`<br />
  Converts this Long to its little endian byte representation.

* Long#**toBytesBE**(): `number[]`<br />
  Converts this Long to its big endian byte representation.

* Long#**toInt**(): `number`<br />
  Converts the Long to a 32 bit integer, assuming it is a 32 bit integer.

* Long#**toNumber**(): `number`<br />
  Converts the Long to a the nearest floating-point representation of this value (double, 53 bit mantissa).

* Long#**toSigned**(): `Long`<br />
  Converts this Long to signed.

* Long#**toString**(radix?: `number`): `string`<br />
  Converts the Long to a string written in the specified radix.

* Long#**toUnsigned**(): `Long`<br />
  Converts this Long to unsigned.

* Long#**xor**(other: `Long | number | string`): `Long`<br />
  Returns the bitwise XOR of this Long and the given one.

WebAssembly support
-------------------

[WebAssembly](http://webassembly.org) supports 64-bit integer arithmetic out of the box, hence a [tiny WebAssembly module](./src/wasm.wat) is used to compute operations like multiplication, division and remainder more efficiently (slow operations like division are around twice as fast), falling back to floating point based computations in JavaScript where WebAssembly is not yet supported, e.g., in older versions of node.

Building
--------

To build an UMD bundle to `dist/long.js`, run:

```
$> npm install
$> npm run build
```

Running the [tests](./tests):

```
$> npm test
```


---

1.3.8 / 2022-02-02
==================

  * deps: mime-types@~2.1.34
    - deps: mime-db@~1.51.0
  * deps: negotiator@0.6.3

1.3.7 / 2019-04-29
==================

  * deps: negotiator@0.6.2
    - Fix sorting charset, encoding, and language with extra parameters

1.3.6 / 2019-04-28
==================

  * deps: mime-types@~2.1.24
    - deps: mime-db@~1.40.0

1.3.5 / 2018-02-28
==================

  * deps: mime-types@~2.1.18
    - deps: mime-db@~1.33.0

1.3.4 / 2017-08-22
==================

  * deps: mime-types@~2.1.16
    - deps: mime-db@~1.29.0

1.3.3 / 2016-05-02
==================

  * deps: mime-types@~2.1.11
    - deps: mime-db@~1.23.0
  * deps: negotiator@0.6.1
    - perf: improve `Accept` parsing speed
    - perf: improve `Accept-Charset` parsing speed
    - perf: improve `Accept-Encoding` parsing speed
    - perf: improve `Accept-Language` parsing speed

1.3.2 / 2016-03-08
==================

  * deps: mime-types@~2.1.10
    - Fix extension of `application/dash+xml`
    - Update primary extension for `audio/mp4`
    - deps: mime-db@~1.22.0

1.3.1 / 2016-01-19
==================

  * deps: mime-types@~2.1.9
    - deps: mime-db@~1.21.0

1.3.0 / 2015-09-29
==================

  * deps: mime-types@~2.1.7
    - deps: mime-db@~1.19.0
  * deps: negotiator@0.6.0
    - Fix including type extensions in parameters in `Accept` parsing
    - Fix parsing `Accept` parameters with quoted equals
    - Fix parsing `Accept` parameters with quoted semicolons
    - Lazy-load modules from main entry point
    - perf: delay type concatenation until needed
    - perf: enable strict mode
    - perf: hoist regular expressions
    - perf: remove closures getting spec properties
    - perf: remove a closure from media type parsing
    - perf: remove property delete from media type parsing

1.2.13 / 2015-09-06
===================

  * deps: mime-types@~2.1.6
    - deps: mime-db@~1.18.0

1.2.12 / 2015-07-30
===================

  * deps: mime-types@~2.1.4
    - deps: mime-db@~1.16.0

1.2.11 / 2015-07-16
===================

  * deps: mime-types@~2.1.3
    - deps: mime-db@~1.15.0

1.2.10 / 2015-07-01
===================

  * deps: mime-types@~2.1.2
    - deps: mime-db@~1.14.0

1.2.9 / 2015-06-08
==================

  * deps: mime-types@~2.1.1
    - perf: fix deopt during mapping

1.2.8 / 2015-06-07
==================

  * deps: mime-types@~2.1.0
    - deps: mime-db@~1.13.0
  * perf: avoid argument reassignment & argument slice
  * perf: avoid negotiator recursive construction
  * perf: enable strict mode
  * perf: remove unnecessary bitwise operator

1.2.7 / 2015-05-10
==================

  * deps: negotiator@0.5.3
    - Fix media type parameter matching to be case-insensitive

1.2.6 / 2015-05-07
==================

  * deps: mime-types@~2.0.11
    - deps: mime-db@~1.9.1
  * deps: negotiator@0.5.2
    - Fix comparing media types with quoted values
    - Fix splitting media types with quoted commas

1.2.5 / 2015-03-13
==================

  * deps: mime-types@~2.0.10
    - deps: mime-db@~1.8.0

1.2.4 / 2015-02-14
==================

  * Support Node.js 0.6
  * deps: mime-types@~2.0.9
    - deps: mime-db@~1.7.0
  * deps: negotiator@0.5.1
    - Fix preference sorting to be stable for long acceptable lists

1.2.3 / 2015-01-31
==================

  * deps: mime-types@~2.0.8
    - deps: mime-db@~1.6.0

1.2.2 / 2014-12-30
==================

  * deps: mime-types@~2.0.7
    - deps: mime-db@~1.5.0

1.2.1 / 2014-12-30
==================

  * deps: mime-types@~2.0.5
    - deps: mime-db@~1.3.1

1.2.0 / 2014-12-19
==================

  * deps: negotiator@0.5.0
    - Fix list return order when large accepted list
    - Fix missing identity encoding when q=0 exists
    - Remove dynamic building of Negotiator class

1.1.4 / 2014-12-10
==================

  * deps: mime-types@~2.0.4
    - deps: mime-db@~1.3.0

1.1.3 / 2014-11-09
==================

  * deps: mime-types@~2.0.3
    - deps: mime-db@~1.2.0

1.1.2 / 2014-10-14
==================

  * deps: negotiator@0.4.9
    - Fix error when media type has invalid parameter

1.1.1 / 2014-09-28
==================

  * deps: mime-types@~2.0.2
    - deps: mime-db@~1.1.0
  * deps: negotiator@0.4.8
    - Fix all negotiations to be case-insensitive
    - Stable sort preferences of same quality according to client order

1.1.0 / 2014-09-02
==================

  * update `mime-types`

1.0.7 / 2014-07-04
==================

  * Fix wrong type returned from `type` when match after unknown extension

1.0.6 / 2014-06-24
==================

  * deps: negotiator@0.4.7

1.0.5 / 2014-06-20
==================

 * fix crash when unknown extension given

1.0.4 / 2014-06-19
==================

  * use `mime-types`

1.0.3 / 2014-06-11
==================

  * deps: negotiator@0.4.6
    - Order by specificity when quality is the same

1.0.2 / 2014-05-29
==================

  * Fix interpretation when header not in request
  * deps: pin negotiator@0.4.5

1.0.1 / 2014-01-18
==================

  * Identity encoding isn't always acceptable
  * deps: negotiator@~0.4.0

1.0.0 / 2013-12-27
==================

  * Genesis


---

# accepts

[![NPM Version][npm-version-image]][npm-url]
[![NPM Downloads][npm-downloads-image]][npm-url]
[![Node.js Version][node-version-image]][node-version-url]
[![Build Status][github-actions-ci-image]][github-actions-ci-url]
[![Test Coverage][coveralls-image]][coveralls-url]

Higher level content negotiation based on [negotiator](https://www.npmjs.com/package/negotiator).
Extracted from [koa](https://www.npmjs.com/package/koa) for general use.

In addition to negotiator, it allows:

- Allows types as an array or arguments list, ie `(['text/html', 'application/json'])`
  as well as `('text/html', 'application/json')`.
- Allows type shorthands such as `json`.
- Returns `false` when no types match
- Treats non-existent headers as `*`

## Installation

This is a [Node.js](https://nodejs.org/en/) module available through the
[npm registry](https://www.npmjs.com/). Installation is done using the
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):

```sh
$ npm install accepts
```

## API

```js
var accepts = require('accepts')
```

### accepts(req)

Create a new `Accepts` object for the given `req`.

#### .charset(charsets)

Return the first accepted charset. If nothing in `charsets` is accepted,
then `false` is returned.

#### .charsets()

Return the charsets that the request accepts, in the order of the client's
preference (most preferred first).

#### .encoding(encodings)

Return the first accepted encoding. If nothing in `encodings` is accepted,
then `false` is returned.

#### .encodings()

Return the encodings that the request accepts, in the order of the client's
preference (most preferred first).

#### .language(languages)

Return the first accepted language. If nothing in `languages` is accepted,
then `false` is returned.

#### .languages()

Return the languages that the request accepts, in the order of the client's
preference (most preferred first).

#### .type(types)

Return the first accepted type (and it is returned as the same text as what
appears in the `types` array). If nothing in `types` is accepted, then `false`
is returned.

The `types` array can contain full MIME types or file extensions. Any value
that is not a full MIME types is passed to `require('mime-types').lookup`.

#### .types()

Return the types that the request accepts, in the order of the client's
preference (most preferred first).

## Examples

### Simple type negotiation

This simple example shows how to use `accepts` to return a different typed
respond body based on what the client wants to accept. The server lists it's
preferences in order and will get back the best match between the client and
server.

```js
var accepts = require('accepts')
var http = require('http')

function app (req, res) {
  var accept = accepts(req)

  // the order of this list is significant; should be server preferred order
  switch (accept.type(['json', 'html'])) {
    case 'json':
      res.setHeader('Content-Type', 'application/json')
      res.write('{"hello":"world!"}')
      break
    case 'html':
      res.setHeader('Content-Type', 'text/html')
      res.write('<b>hello, world!</b>')
      break
    default:
      // the fallback is text/plain, so no need to specify it above
      res.setHeader('Content-Type', 'text/plain')
      res.write('hello, world!')
      break
  }

  res.end()
}

http.createServer(app).listen(3000)
```

You can test this out with the cURL program:
```sh
curl -I -H'Accept: text/html' http://localhost:3000/
```

## License

[MIT](LICENSE)

[coveralls-image]: https://badgen.net/coveralls/c/github/jshttp/accepts/master
[coveralls-url]: https://coveralls.io/r/jshttp/accepts?branch=master
[github-actions-ci-image]: https://badgen.net/github/checks/jshttp/accepts/master?label=ci
[github-actions-ci-url]: https://github.com/jshttp/accepts/actions/workflows/ci.yml
[node-version-image]: https://badgen.net/npm/node/accepts
[node-version-url]: https://nodejs.org/en/download
[npm-downloads-image]: https://badgen.net/npm/dm/accepts
[npm-url]: https://npmjs.org/package/accepts
[npm-version-image]: https://badgen.net/npm/v/accepts


---

1.52.0 / 2022-02-21
===================

  * Add extensions from IANA for more `image/*` types
  * Add extension `.asc` to `application/pgp-keys`
  * Add extensions to various XML types
  * Add new upstream MIME types

1.51.0 / 2021-11-08
===================

  * Add new upstream MIME types
  * Mark `image/vnd.microsoft.icon` as compressible
  * Mark `image/vnd.ms-dds` as compressible

1.50.0 / 2021-09-15
===================

  * Add deprecated iWorks mime types and extensions
  * Add new upstream MIME types

1.49.0 / 2021-07-26
===================

  * Add extension `.trig` to `application/trig`
  * Add new upstream MIME types

1.48.0 / 2021-05-30
===================

  * Add extension `.mvt` to `application/vnd.mapbox-vector-tile`
  * Add new upstream MIME types
  * Mark `text/yaml` as compressible

1.47.0 / 2021-04-01
===================

  * Add new upstream MIME types
  * Remove ambigious extensions from IANA for `application/*+xml` types
  * Update primary extension to `.es` for `application/ecmascript`

1.46.0 / 2021-02-13
===================

  * Add extension `.amr` to `audio/amr`
  * Add extension `.m4s` to `video/iso.segment`
  * Add extension `.opus` to `audio/ogg`
  * Add new upstream MIME types

1.45.0 / 2020-09-22
===================

  * Add `application/ubjson` with extension `.ubj`
  * Add `image/avif` with extension `.avif`
  * Add `image/ktx2` with extension `.ktx2`
  * Add extension `.dbf` to `application/vnd.dbf`
  * Add extension `.rar` to `application/vnd.rar`
  * Add extension `.td` to `application/urc-targetdesc+xml`
  * Add new upstream MIME types
  * Fix extension of `application/vnd.apple.keynote` to be `.key`

1.44.0 / 2020-04-22
===================

  * Add charsets from IANA
  * Add extension `.cjs` to `application/node`
  * Add new upstream MIME types

1.43.0 / 2020-01-05
===================

  * Add `application/x-keepass2` with extension `.kdbx`
  * Add extension `.mxmf` to `audio/mobile-xmf`
  * Add extensions from IANA for `application/*+xml` types
  * Add new upstream MIME types

1.42.0 / 2019-09-25
===================

  * Add `image/vnd.ms-dds` with extension `.dds`
  * Add new upstream MIME types
  * Remove compressible from `multipart/mixed`

1.41.0 / 2019-08-30
===================

  * Add new upstream MIME types
  * Add `application/toml` with extension `.toml`
  * Mark `font/ttf` as compressible

1.40.0 / 2019-04-20
===================

  * Add extensions from IANA for `model/*` types
  * Add `text/mdx` with extension `.mdx`

1.39.0 / 2019-04-04
===================

  * Add extensions `.siv` and `.sieve` to `application/sieve`
  * Add new upstream MIME types

1.38.0 / 2019-02-04
===================

  * Add extension `.nq` to `application/n-quads`
  * Add extension `.nt` to `application/n-triples`
  * Add new upstream MIME types
  * Mark `text/less` as compressible

1.37.0 / 2018-10-19
===================

  * Add extensions to HEIC image types
  * Add new upstream MIME types

1.36.0 / 2018-08-20
===================

  * Add Apple file extensions from IANA
  * Add extensions from IANA for `image/*` types
  * Add new upstream MIME types

1.35.0 / 2018-07-15
===================

  * Add extension `.owl` to `application/rdf+xml`
  * Add new upstream MIME types
    - Removes extension `.woff` from `application/font-woff`

1.34.0 / 2018-06-03
===================

  * Add extension `.csl` to `application/vnd.citationstyles.style+xml`
  * Add extension `.es` to `application/ecmascript`
  * Add new upstream MIME types
  * Add `UTF-8` as default charset for `text/turtle`
  * Mark all XML-derived types as compressible

1.33.0 / 2018-02-15
===================

  * Add extensions from IANA for `message/*` types
  * Add new upstream MIME types
  * Fix some incorrect OOXML types
  * Remove `application/font-woff2`

1.32.0 / 2017-11-29
===================

  * Add new upstream MIME types
  * Update `text/hjson` to registered `application/hjson`
  * Add `text/shex` with extension `.shex`

1.31.0 / 2017-10-25
===================

  * Add `application/raml+yaml` with extension `.raml`
  * Add `application/wasm` with extension `.wasm`
  * Add new `font` type from IANA
  * Add new upstream font extensions
  * Add new upstream MIME types
  * Add extensions for JPEG-2000 images

1.30.0 / 2017-08-27
===================

  * Add `application/vnd.ms-outlook`
  * Add `application/x-arj`
  * Add extension `.mjs` to `application/javascript`
  * Add glTF types and extensions
  * Add new upstream MIME types
  * Add `text/x-org`
  * Add VirtualBox MIME types
  * Fix `source` records for `video/*` types that are IANA
  * Update `font/opentype` to registered `font/otf`

1.29.0 / 2017-07-10
===================

  * Add `application/fido.trusted-apps+json`
  * Add extension `.wadl` to `application/vnd.sun.wadl+xml`
  * Add new upstream MIME types
  * Add `UTF-8` as default charset for `text/css`

1.28.0 / 2017-05-14
===================

  * Add new upstream MIME types
  * Add extension `.gz` to `application/gzip`
  * Update extensions `.md` and `.markdown` to be `text/markdown`

1.27.0 / 2017-03-16
===================

  * Add new upstream MIME types
  * Add `image/apng` with extension `.apng`

1.26.0 / 2017-01-14
===================

  * Add new upstream MIME types
  * Add extension `.geojson` to `application/geo+json`

1.25.0 / 2016-11-11
===================

  * Add new upstream MIME types

1.24.0 / 2016-09-18
===================

  * Add `audio/mp3`
  * Add new upstream MIME types

1.23.0 / 2016-05-01
===================

  * Add new upstream MIME types
  * Add extension `.3gpp` to `audio/3gpp`

1.22.0 / 2016-02-15
===================

  * Add `text/slim`
  * Add extension `.rng` to `application/xml`
  * Add new upstream MIME types
  * Fix extension of `application/dash+xml` to be `.mpd`
  * Update primary extension to `.m4a` for `audio/mp4`

1.21.0 / 2016-01-06
===================

  * Add Google document types
  * Add new upstream MIME types

1.20.0 / 2015-11-10
===================

  * Add `text/x-suse-ymp`
  * Add new upstream MIME types

1.19.0 / 2015-09-17
===================

  * Add `application/vnd.apple.pkpass`
  * Add new upstream MIME types

1.18.0 / 2015-09-03
===================

  * Add new upstream MIME types

1.17.0 / 2015-08-13
===================

  * Add `application/x-msdos-program`
  * Add `audio/g711-0`
  * Add `image/vnd.mozilla.apng`
  * Add extension `.exe` to `application/x-msdos-program`

1.16.0 / 2015-07-29
===================

  * Add `application/vnd.uri-map`

1.15.0 / 2015-07-13
===================

  * Add `application/x-httpd-php`

1.14.0 / 2015-06-25
===================

  * Add `application/scim+json`
  * Add `application/vnd.3gpp.ussd+xml`
  * Add `application/vnd.biopax.rdf+xml`
  * Add `text/x-processing`

1.13.0 / 2015-06-07
===================

  * Add nginx as a source
  * Add `application/x-cocoa`
  * Add `application/x-java-archive-diff`
  * Add `application/x-makeself`
  * Add `application/x-perl`
  * Add `application/x-pilot`
  * Add `application/x-redhat-package-manager`
  * Add `application/x-sea`
  * Add `audio/x-m4a`
  * Add `audio/x-realaudio`
  * Add `image/x-jng`
  * Add `text/mathml`

1.12.0 / 2015-06-05
===================

  * Add `application/bdoc`
  * Add `application/vnd.hyperdrive+json`
  * Add `application/x-bdoc`
  * Add extension `.rtf` to `text/rtf`

1.11.0 / 2015-05-31
===================

  * Add `audio/wav`
  * Add `audio/wave`
  * Add extension `.litcoffee` to `text/coffeescript`
  * Add extension `.sfd-hdstx` to `application/vnd.hydrostatix.sof-data`
  * Add extension `.n-gage` to `application/vnd.nokia.n-gage.symbian.install`

1.10.0 / 2015-05-19
===================

  * Add `application/vnd.balsamiq.bmpr`
  * Add `application/vnd.microsoft.portable-executable`
  * Add `application/x-ns-proxy-autoconfig`

1.9.1 / 2015-04-19
==================

  * Remove `.json` extension from `application/manifest+json`
    - This is causing bugs downstream

1.9.0 / 2015-04-19
==================

  * Add `application/manifest+json`
  * Add `application/vnd.micro+json`
  * Add `image/vnd.zbrush.pcx`
  * Add `image/x-ms-bmp`

1.8.0 / 2015-03-13
==================

  * Add `application/vnd.citationstyles.style+xml`
  * Add `application/vnd.fastcopy-disk-image`
  * Add `application/vnd.gov.sk.xmldatacontainer+xml`
  * Add extension `.jsonld` to `application/ld+json`

1.7.0 / 2015-02-08
==================

  * Add `application/vnd.gerber`
  * Add `application/vnd.msa-disk-image`

1.6.1 / 2015-02-05
==================

  * Community extensions ownership transferred from `node-mime`

1.6.0 / 2015-01-29
==================

  * Add `application/jose`
  * Add `application/jose+json`
  * Add `application/json-seq`
  * Add `application/jwk+json`
  * Add `application/jwk-set+json`
  * Add `application/jwt`
  * Add `application/rdap+json`
  * Add `application/vnd.gov.sk.e-form+xml`
  * Add `application/vnd.ims.imsccv1p3`

1.5.0 / 2014-12-30
==================

  * Add `application/vnd.oracle.resource+json`
  * Fix various invalid MIME type entries
    - `application/mbox+xml`
    - `application/oscp-response`
    - `application/vwg-multiplexed`
    - `audio/g721`

1.4.0 / 2014-12-21
==================

  * Add `application/vnd.ims.imsccv1p2`
  * Fix various invalid MIME type entries
    - `application/vnd-acucobol`
    - `application/vnd-curl`
    - `application/vnd-dart`
    - `application/vnd-dxr`
    - `application/vnd-fdf`
    - `application/vnd-mif`
    - `application/vnd-sema`
    - `application/vnd-wap-wmlc`
    - `application/vnd.adobe.flash-movie`
    - `application/vnd.dece-zip`
    - `application/vnd.dvb_service`
    - `application/vnd.micrografx-igx`
    - `application/vnd.sealed-doc`
    - `application/vnd.sealed-eml`
    - `application/vnd.sealed-mht`
    - `application/vnd.sealed-ppt`
    - `application/vnd.sealed-tiff`
    - `application/vnd.sealed-xls`
    - `application/vnd.sealedmedia.softseal-html`
    - `application/vnd.sealedmedia.softseal-pdf`
    - `application/vnd.wap-slc`
    - `application/vnd.wap-wbxml`
    - `audio/vnd.sealedmedia.softseal-mpeg`
    - `image/vnd-djvu`
    - `image/vnd-svf`
    - `image/vnd-wap-wbmp`
    - `image/vnd.sealed-png`
    - `image/vnd.sealedmedia.softseal-gif`
    - `image/vnd.sealedmedia.softseal-jpg`
    - `model/vnd-dwf`
    - `model/vnd.parasolid.transmit-binary`
    - `model/vnd.parasolid.transmit-text`
    - `text/vnd-a`
    - `text/vnd-curl`
    - `text/vnd.wap-wml`
  * Remove example template MIME types
    - `application/example`
    - `audio/example`
    - `image/example`
    - `message/example`
    - `model/example`
    - `multipart/example`
    - `text/example`
    - `video/example`

1.3.1 / 2014-12-16
==================

  * Fix missing extensions
    - `application/json5`
    - `text/hjson`

1.3.0 / 2014-12-07
==================

  * Add `application/a2l`
  * Add `application/aml`
  * Add `application/atfx`
  * Add `application/atxml`
  * Add `application/cdfx+xml`
  * Add `application/dii`
  * Add `application/json5`
  * Add `application/lxf`
  * Add `application/mf4`
  * Add `application/vnd.apache.thrift.compact`
  * Add `application/vnd.apache.thrift.json`
  * Add `application/vnd.coffeescript`
  * Add `application/vnd.enphase.envoy`
  * Add `application/vnd.ims.imsccv1p1`
  * Add `text/csv-schema`
  * Add `text/hjson`
  * Add `text/markdown`
  * Add `text/yaml`

1.2.0 / 2014-11-09
==================

  * Add `application/cea`
  * Add `application/dit`
  * Add `application/vnd.gov.sk.e-form+zip`
  * Add `application/vnd.tmd.mediaflex.api+xml`
  * Type `application/epub+zip` is now IANA-registered

1.1.2 / 2014-10-23
==================

  * Rebuild database for `application/x-www-form-urlencoded` change

1.1.1 / 2014-10-20
==================

  * Mark `application/x-www-form-urlencoded` as compressible.

1.1.0 / 2014-09-28
==================

  * Add `application/font-woff2`

1.0.3 / 2014-09-25
==================

  * Fix engine requirement in package

1.0.2 / 2014-09-25
==================

  * Add `application/coap-group+json`
  * Add `application/dcd`
  * Add `application/vnd.apache.thrift.binary`
  * Add `image/vnd.tencent.tap`
  * Mark all JSON-derived types as compressible
  * Update `text/vtt` data

1.0.1 / 2014-08-30
==================

  * Fix extension ordering

1.0.0 / 2014-08-30
==================

  * Add `application/atf`
  * Add `application/merge-patch+json`
  * Add `multipart/x-mixed-replace`
  * Add `source: 'apache'` metadata
  * Add `source: 'iana'` metadata
  * Remove badly-assumed charset data


---

# mime-db

[![NPM Version][npm-version-image]][npm-url]
[![NPM Downloads][npm-downloads-image]][npm-url]
[![Node.js Version][node-image]][node-url]
[![Build Status][ci-image]][ci-url]
[![Coverage Status][coveralls-image]][coveralls-url]

This is a large database of mime types and information about them.
It consists of a single, public JSON file and does not include any logic,
allowing it to remain as un-opinionated as possible with an API.
It aggregates data from the following sources:

- http://www.iana.org/assignments/media-types/media-types.xhtml
- http://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/conf/mime.types
- http://hg.nginx.org/nginx/raw-file/default/conf/mime.types

## Installation

```bash
npm install mime-db
```

### Database Download

If you're crazy enough to use this in the browser, you can just grab the
JSON file using [jsDelivr](https://www.jsdelivr.com/). It is recommended to
replace `master` with [a release tag](https://github.com/jshttp/mime-db/tags)
as the JSON format may change in the future.

```
https://cdn.jsdelivr.net/gh/jshttp/mime-db@master/db.json
```

## Usage

```js
var db = require('mime-db')

// grab data on .js files
var data = db['application/javascript']
```

## Data Structure

The JSON file is a map lookup for lowercased mime types.
Each mime type has the following properties:

- `.source` - where the mime type is defined.
    If not set, it's probably a custom media type.
    - `apache` - [Apache common media types](http://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/conf/mime.types)
    - `iana` - [IANA-defined media types](http://www.iana.org/assignments/media-types/media-types.xhtml)
    - `nginx` - [nginx media types](http://hg.nginx.org/nginx/raw-file/default/conf/mime.types)
- `.extensions[]` - known extensions associated with this mime type.
- `.compressible` - whether a file of this type can be gzipped.
- `.charset` - the default charset associated with this type, if any.

If unknown, every property could be `undefined`.

## Contributing

To edit the database, only make PRs against `src/custom-types.json` or
`src/custom-suffix.json`.

The `src/custom-types.json` file is a JSON object with the MIME type as the
keys and the values being an object with the following keys:

- `compressible` - leave out if you don't know, otherwise `true`/`false` to
  indicate whether the data represented by the type is typically compressible.
- `extensions` - include an array of file extensions that are associated with
  the type.
- `notes` - human-readable notes about the type, typically what the type is.
- `sources` - include an array of URLs of where the MIME type and the associated
  extensions are sourced from. This needs to be a [primary source](https://en.wikipedia.org/wiki/Primary_source);
  links to type aggregating sites and Wikipedia are _not acceptable_.

To update the build, run `npm run build`.

### Adding Custom Media Types

The best way to get new media types included in this library is to register
them with the IANA. The community registration procedure is outlined in
[RFC 6838 section 5](http://tools.ietf.org/html/rfc6838#section-5). Types
registered with the IANA are automatically pulled into this library.

If that is not possible / feasible, they can be added directly here as a
"custom" type. To do this, it is required to have a primary source that
definitively lists the media type. If an extension is going to be listed as
associateed with this media type, the source must definitively link the
media type and extension as well.

[ci-image]: https://badgen.net/github/checks/jshttp/mime-db/master?label=ci
[ci-url]: https://github.com/jshttp/mime-db/actions?query=workflow%3Aci
[coveralls-image]: https://badgen.net/coveralls/c/github/jshttp/mime-db/master
[coveralls-url]: https://coveralls.io/r/jshttp/mime-db?branch=master
[node-image]: https://badgen.net/npm/node/mime-db
[node-url]: https://nodejs.org/en/download
[npm-downloads-image]: https://badgen.net/npm/dm/mime-db
[npm-url]: https://npmjs.org/package/mime-db
[npm-version-image]: https://badgen.net/npm/v/mime-db


---

2.1.35 / 2022-03-12
===================

  * deps: mime-db@1.52.0
    - Add extensions from IANA for more `image/*` types
    - Add extension `.asc` to `application/pgp-keys`
    - Add extensions to various XML types
    - Add new upstream MIME types

2.1.34 / 2021-11-08
===================

  * deps: mime-db@1.51.0
    - Add new upstream MIME types

2.1.33 / 2021-10-01
===================

  * deps: mime-db@1.50.0
    - Add deprecated iWorks mime types and extensions
    - Add new upstream MIME types

2.1.32 / 2021-07-27
===================

  * deps: mime-db@1.49.0
    - Add extension `.trig` to `application/trig`
    - Add new upstream MIME types

2.1.31 / 2021-06-01
===================

  * deps: mime-db@1.48.0
    - Add extension `.mvt` to `application/vnd.mapbox-vector-tile`
    - Add new upstream MIME types

2.1.30 / 2021-04-02
===================

  * deps: mime-db@1.47.0
    - Add extension `.amr` to `audio/amr`
    - Remove ambigious extensions from IANA for `application/*+xml` types
    - Update primary extension to `.es` for `application/ecmascript`

2.1.29 / 2021-02-17
===================

  * deps: mime-db@1.46.0
    - Add extension `.amr` to `audio/amr`
    - Add extension `.m4s` to `video/iso.segment`
    - Add extension `.opus` to `audio/ogg`
    - Add new upstream MIME types

2.1.28 / 2021-01-01
===================

  * deps: mime-db@1.45.0
    - Add `application/ubjson` with extension `.ubj`
    - Add `image/avif` with extension `.avif`
    - Add `image/ktx2` with extension `.ktx2`
    - Add extension `.dbf` to `application/vnd.dbf`
    - Add extension `.rar` to `application/vnd.rar`
    - Add extension `.td` to `application/urc-targetdesc+xml`
    - Add new upstream MIME types
    - Fix extension of `application/vnd.apple.keynote` to be `.key`

2.1.27 / 2020-04-23
===================

  * deps: mime-db@1.44.0
    - Add charsets from IANA
    - Add extension `.cjs` to `application/node`
    - Add new upstream MIME types

2.1.26 / 2020-01-05
===================

  * deps: mime-db@1.43.0
    - Add `application/x-keepass2` with extension `.kdbx`
    - Add extension `.mxmf` to `audio/mobile-xmf`
    - Add extensions from IANA for `application/*+xml` types
    - Add new upstream MIME types

2.1.25 / 2019-11-12
===================

  * deps: mime-db@1.42.0
    - Add new upstream MIME types
    - Add `application/toml` with extension `.toml`
    - Add `image/vnd.ms-dds` with extension `.dds`

2.1.24 / 2019-04-20
===================

  * deps: mime-db@1.40.0
    - Add extensions from IANA for `model/*` types
    - Add `text/mdx` with extension `.mdx`

2.1.23 / 2019-04-17
===================

  * deps: mime-db@~1.39.0
    - Add extensions `.siv` and `.sieve` to `application/sieve`
    - Add new upstream MIME types

2.1.22 / 2019-02-14
===================

  * deps: mime-db@~1.38.0
    - Add extension `.nq` to `application/n-quads`
    - Add extension `.nt` to `application/n-triples`
    - Add new upstream MIME types

2.1.21 / 2018-10-19
===================

  * deps: mime-db@~1.37.0
    - Add extensions to HEIC image types
    - Add new upstream MIME types

2.1.20 / 2018-08-26
===================

  * deps: mime-db@~1.36.0
    - Add Apple file extensions from IANA
    - Add extensions from IANA for `image/*` types
    - Add new upstream MIME types

2.1.19 / 2018-07-17
===================

  * deps: mime-db@~1.35.0
    - Add extension `.csl` to `application/vnd.citationstyles.style+xml`
    - Add extension `.es` to `application/ecmascript`
    - Add extension `.owl` to `application/rdf+xml`
    - Add new upstream MIME types
    - Add UTF-8 as default charset for `text/turtle`

2.1.18 / 2018-02-16
===================

  * deps: mime-db@~1.33.0
    - Add `application/raml+yaml` with extension `.raml`
    - Add `application/wasm` with extension `.wasm`
    - Add `text/shex` with extension `.shex`
    - Add extensions for JPEG-2000 images
    - Add extensions from IANA for `message/*` types
    - Add new upstream MIME types
    - Update font MIME types
    - Update `text/hjson` to registered `application/hjson`

2.1.17 / 2017-09-01
===================

  * deps: mime-db@~1.30.0
    - Add `application/vnd.ms-outlook`
    - Add `application/x-arj`
    - Add extension `.mjs` to `application/javascript`
    - Add glTF types and extensions
    - Add new upstream MIME types
    - Add `text/x-org`
    - Add VirtualBox MIME types
    - Fix `source` records for `video/*` types that are IANA
    - Update `font/opentype` to registered `font/otf`

2.1.16 / 2017-07-24
===================

  * deps: mime-db@~1.29.0
    - Add `application/fido.trusted-apps+json`
    - Add extension `.wadl` to `application/vnd.sun.wadl+xml`
    - Add extension `.gz` to `application/gzip`
    - Add new upstream MIME types
    - Update extensions `.md` and `.markdown` to be `text/markdown`

2.1.15 / 2017-03-23
===================

  * deps: mime-db@~1.27.0
    - Add new mime types
    - Add `image/apng`

2.1.14 / 2017-01-14
===================

  * deps: mime-db@~1.26.0
    - Add new mime types

2.1.13 / 2016-11-18
===================

  * deps: mime-db@~1.25.0
    - Add new mime types

2.1.12 / 2016-09-18
===================

  * deps: mime-db@~1.24.0
    - Add new mime types
    - Add `audio/mp3`

2.1.11 / 2016-05-01
===================

  * deps: mime-db@~1.23.0
    - Add new mime types

2.1.10 / 2016-02-15
===================

  * deps: mime-db@~1.22.0
    - Add new mime types
    - Fix extension of `application/dash+xml`
    - Update primary extension for `audio/mp4`

2.1.9 / 2016-01-06
==================

  * deps: mime-db@~1.21.0
    - Add new mime types

2.1.8 / 2015-11-30
==================

  * deps: mime-db@~1.20.0
    - Add new mime types

2.1.7 / 2015-09-20
==================

  * deps: mime-db@~1.19.0
    - Add new mime types

2.1.6 / 2015-09-03
==================

  * deps: mime-db@~1.18.0
    - Add new mime types

2.1.5 / 2015-08-20
==================

  * deps: mime-db@~1.17.0
    - Add new mime types

2.1.4 / 2015-07-30
==================

  * deps: mime-db@~1.16.0
    - Add new mime types

2.1.3 / 2015-07-13
==================

  * deps: mime-db@~1.15.0
    - Add new mime types

2.1.2 / 2015-06-25
==================

  * deps: mime-db@~1.14.0
    - Add new mime types

2.1.1 / 2015-06-08
==================

  * perf: fix deopt during mapping

2.1.0 / 2015-06-07
==================

  * Fix incorrectly treating extension-less file name as extension
    - i.e. `'path/to/json'` will no longer return `application/json`
  * Fix `.charset(type)` to accept parameters
  * Fix `.charset(type)` to match case-insensitive
  * Improve generation of extension to MIME mapping
  * Refactor internals for readability and no argument reassignment
  * Prefer `application/*` MIME types from the same source
  * Prefer any type over `application/octet-stream`
  * deps: mime-db@~1.13.0
    - Add nginx as a source
    - Add new mime types

2.0.14 / 2015-06-06
===================

  * deps: mime-db@~1.12.0
    - Add new mime types

2.0.13 / 2015-05-31
===================

  * deps: mime-db@~1.11.0
    - Add new mime types

2.0.12 / 2015-05-19
===================

  * deps: mime-db@~1.10.0
    - Add new mime types

2.0.11 / 2015-05-05
===================

  * deps: mime-db@~1.9.1
    - Add new mime types

2.0.10 / 2015-03-13
===================

  * deps: mime-db@~1.8.0
    - Add new mime types

2.0.9 / 2015-02-09
==================

  * deps: mime-db@~1.7.0
    - Add new mime types
    - Community extensions ownership transferred from `node-mime`

2.0.8 / 2015-01-29
==================

  * deps: mime-db@~1.6.0
    - Add new mime types

2.0.7 / 2014-12-30
==================

  * deps: mime-db@~1.5.0
    - Add new mime types
    - Fix various invalid MIME type entries

2.0.6 / 2014-12-30
==================

  * deps: mime-db@~1.4.0
    - Add new mime types
    - Fix various invalid MIME type entries
    - Remove example template MIME types

2.0.5 / 2014-12-29
==================

  * deps: mime-db@~1.3.1
    - Fix missing extensions

2.0.4 / 2014-12-10
==================

  * deps: mime-db@~1.3.0
    - Add new mime types

2.0.3 / 2014-11-09
==================

  * deps: mime-db@~1.2.0
    - Add new mime types

2.0.2 / 2014-09-28
==================

  * deps: mime-db@~1.1.0
    - Add new mime types
    - Update charsets

2.0.1 / 2014-09-07
==================

  * Support Node.js 0.6

2.0.0 / 2014-09-02
==================

  * Use `mime-db`
  * Remove `.define()`

1.0.2 / 2014-08-04
==================

  * Set charset=utf-8 for `text/javascript`

1.0.1 / 2014-06-24
==================

  * Add `text/jsx` type

1.0.0 / 2014-05-12
==================

  * Return `false` for unknown types
  * Set charset=utf-8 for `application/json`

0.1.0 / 2014-05-02
==================

  * Initial release


---

# mime-types

[![NPM Version][npm-version-image]][npm-url]
[![NPM Downloads][npm-downloads-image]][npm-url]
[![Node.js Version][node-version-image]][node-version-url]
[![Build Status][ci-image]][ci-url]
[![Test Coverage][coveralls-image]][coveralls-url]

The ultimate javascript content-type utility.

Similar to [the `mime@1.x` module](https://www.npmjs.com/package/mime), except:

- __No fallbacks.__ Instead of naively returning the first available type,
  `mime-types` simply returns `false`, so do
  `var type = mime.lookup('unrecognized') || 'application/octet-stream'`.
- No `new Mime()` business, so you could do `var lookup = require('mime-types').lookup`.
- No `.define()` functionality
- Bug fixes for `.lookup(path)`

Otherwise, the API is compatible with `mime` 1.x.

## Install

This is a [Node.js](https://nodejs.org/en/) module available through the
[npm registry](https://www.npmjs.com/). Installation is done using the
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):

```sh
$ npm install mime-types
```

## Adding Types

All mime types are based on [mime-db](https://www.npmjs.com/package/mime-db),
so open a PR there if you'd like to add mime types.

## API

```js
var mime = require('mime-types')
```

All functions return `false` if input is invalid or not found.

### mime.lookup(path)

Lookup the content-type associated with a file.

```js
mime.lookup('json') // 'application/json'
mime.lookup('.md') // 'text/markdown'
mime.lookup('file.html') // 'text/html'
mime.lookup('folder/file.js') // 'application/javascript'
mime.lookup('folder/.htaccess') // false

mime.lookup('cats') // false
```

### mime.contentType(type)

Create a full content-type header given a content-type or extension.
When given an extension, `mime.lookup` is used to get the matching
content-type, otherwise the given content-type is used. Then if the
content-type does not already have a `charset` parameter, `mime.charset`
is used to get the default charset and add to the returned content-type.

```js
mime.contentType('markdown') // 'text/x-markdown; charset=utf-8'
mime.contentType('file.json') // 'application/json; charset=utf-8'
mime.contentType('text/html') // 'text/html; charset=utf-8'
mime.contentType('text/html; charset=iso-8859-1') // 'text/html; charset=iso-8859-1'

// from a full path
mime.contentType(path.extname('/path/to/file.json')) // 'application/json; charset=utf-8'
```

### mime.extension(type)

Get the default extension for a content-type.

```js
mime.extension('application/octet-stream') // 'bin'
```

### mime.charset(type)

Lookup the implied default charset of a content-type.

```js
mime.charset('text/markdown') // 'UTF-8'
```

### var type = mime.types[extension]

A map of content-types by extension.

### [extensions...] = mime.extensions[type]

A map of extensions by content-type.

## License

[MIT](LICENSE)

[ci-image]: https://badgen.net/github/checks/jshttp/mime-types/master?label=ci
[ci-url]: https://github.com/jshttp/mime-types/actions/workflows/ci.yml
[coveralls-image]: https://badgen.net/coveralls/c/github/jshttp/mime-types/master
[coveralls-url]: https://coveralls.io/r/jshttp/mime-types?branch=master
[node-version-image]: https://badgen.net/npm/node/mime-types
[node-version-url]: https://nodejs.org/en/download
[npm-downloads-image]: https://badgen.net/npm/dm/mime-types
[npm-url]: https://npmjs.org/package/mime-types
[npm-version-image]: https://badgen.net/npm/v/mime-types


---

0.6.3 / 2022-01-22
==================

  * Revert "Lazy-load modules from main entry point"

0.6.2 / 2019-04-29
==================

  * Fix sorting charset, encoding, and language with extra parameters

0.6.1 / 2016-05-02
==================

  * perf: improve `Accept` parsing speed
  * perf: improve `Accept-Charset` parsing speed
  * perf: improve `Accept-Encoding` parsing speed
  * perf: improve `Accept-Language` parsing speed

0.6.0 / 2015-09-29
==================

  * Fix including type extensions in parameters in `Accept` parsing
  * Fix parsing `Accept` parameters with quoted equals
  * Fix parsing `Accept` parameters with quoted semicolons
  * Lazy-load modules from main entry point
  * perf: delay type concatenation until needed
  * perf: enable strict mode
  * perf: hoist regular expressions
  * perf: remove closures getting spec properties
  * perf: remove a closure from media type parsing
  * perf: remove property delete from media type parsing

0.5.3 / 2015-05-10
==================

  * Fix media type parameter matching to be case-insensitive

0.5.2 / 2015-05-06
==================

  * Fix comparing media types with quoted values
  * Fix splitting media types with quoted commas

0.5.1 / 2015-02-14
==================

  * Fix preference sorting to be stable for long acceptable lists

0.5.0 / 2014-12-18
==================

  * Fix list return order when large accepted list
  * Fix missing identity encoding when q=0 exists
  * Remove dynamic building of Negotiator class

0.4.9 / 2014-10-14
==================

  * Fix error when media type has invalid parameter

0.4.8 / 2014-09-28
==================

  * Fix all negotiations to be case-insensitive
  * Stable sort preferences of same quality according to client order
  * Support Node.js 0.6

0.4.7 / 2014-06-24
==================

  * Handle invalid provided languages
  * Handle invalid provided media types

0.4.6 / 2014-06-11
==================

  *  Order by specificity when quality is the same

0.4.5 / 2014-05-29
==================

  * Fix regression in empty header handling

0.4.4 / 2014-05-29
==================

  * Fix behaviors when headers are not present

0.4.3 / 2014-04-16
==================

  * Handle slashes on media params correctly

0.4.2 / 2014-02-28
==================

  * Fix media type sorting
  * Handle media types params strictly

0.4.1 / 2014-01-16
==================

  * Use most specific matches

0.4.0 / 2014-01-09
==================

  * Remove preferred prefix from methods


---

# negotiator

[![NPM Version][npm-image]][npm-url]
[![NPM Downloads][downloads-image]][downloads-url]
[![Node.js Version][node-version-image]][node-version-url]
[![Build Status][github-actions-ci-image]][github-actions-ci-url]
[![Test Coverage][coveralls-image]][coveralls-url]

An HTTP content negotiator for Node.js

## Installation

```sh
$ npm install negotiator
```

## API

```js
var Negotiator = require('negotiator')
```

### Accept Negotiation

```js
availableMediaTypes = ['text/html', 'text/plain', 'application/json']

// The negotiator constructor receives a request object
negotiator = new Negotiator(request)

// Let's say Accept header is 'text/html, application/*;q=0.2, image/jpeg;q=0.8'

negotiator.mediaTypes()
// -> ['text/html', 'image/jpeg', 'application/*']

negotiator.mediaTypes(availableMediaTypes)
// -> ['text/html', 'application/json']

negotiator.mediaType(availableMediaTypes)
// -> 'text/html'
```

You can check a working example at `examples/accept.js`.

#### Methods

##### mediaType()

Returns the most preferred media type from the client.

##### mediaType(availableMediaType)

Returns the most preferred media type from a list of available media types.

##### mediaTypes()

Returns an array of preferred media types ordered by the client preference.

##### mediaTypes(availableMediaTypes)

Returns an array of preferred media types ordered by priority from a list of
available media types.

### Accept-Language Negotiation

```js
negotiator = new Negotiator(request)

availableLanguages = ['en', 'es', 'fr']

// Let's say Accept-Language header is 'en;q=0.8, es, pt'

negotiator.languages()
// -> ['es', 'pt', 'en']

negotiator.languages(availableLanguages)
// -> ['es', 'en']

language = negotiator.language(availableLanguages)
// -> 'es'
```

You can check a working example at `examples/language.js`.

#### Methods

##### language()

Returns the most preferred language from the client.

##### language(availableLanguages)

Returns the most preferred language from a list of available languages.

##### languages()

Returns an array of preferred languages ordered by the client preference.

##### languages(availableLanguages)

Returns an array of preferred languages ordered by priority from a list of
available languages.

### Accept-Charset Negotiation

```js
availableCharsets = ['utf-8', 'iso-8859-1', 'iso-8859-5']

negotiator = new Negotiator(request)

// Let's say Accept-Charset header is 'utf-8, iso-8859-1;q=0.8, utf-7;q=0.2'

negotiator.charsets()
// -> ['utf-8', 'iso-8859-1', 'utf-7']

negotiator.charsets(availableCharsets)
// -> ['utf-8', 'iso-8859-1']

negotiator.charset(availableCharsets)
// -> 'utf-8'
```

You can check a working example at `examples/charset.js`.

#### Methods

##### charset()

Returns the most preferred charset from the client.

##### charset(availableCharsets)

Returns the most preferred charset from a list of available charsets.

##### charsets()

Returns an array of preferred charsets ordered by the client preference.

##### charsets(availableCharsets)

Returns an array of preferred charsets ordered by priority from a list of
available charsets.

### Accept-Encoding Negotiation

```js
availableEncodings = ['identity', 'gzip']

negotiator = new Negotiator(request)

// Let's say Accept-Encoding header is 'gzip, compress;q=0.2, identity;q=0.5'

negotiator.encodings()
// -> ['gzip', 'identity', 'compress']

negotiator.encodings(availableEncodings)
// -> ['gzip', 'identity']

negotiator.encoding(availableEncodings)
// -> 'gzip'
```

You can check a working example at `examples/encoding.js`.

#### Methods

##### encoding()

Returns the most preferred encoding from the client.

##### encoding(availableEncodings)

Returns the most preferred encoding from a list of available encodings.

##### encodings()

Returns an array of preferred encodings ordered by the client preference.

##### encodings(availableEncodings)

Returns an array of preferred encodings ordered by priority from a list of
available encodings.

## See Also

The [accepts](https://npmjs.org/package/accepts#readme) module builds on
this module and provides an alternative interface, mime type validation,
and more.

## License

[MIT](LICENSE)

[npm-image]: https://img.shields.io/npm/v/negotiator.svg
[npm-url]: https://npmjs.org/package/negotiator
[node-version-image]: https://img.shields.io/node/v/negotiator.svg
[node-version-url]: https://nodejs.org/en/download/
[coveralls-image]: https://img.shields.io/coveralls/jshttp/negotiator/master.svg
[coveralls-url]: https://coveralls.io/r/jshttp/negotiator?branch=master
[downloads-image]: https://img.shields.io/npm/dm/negotiator.svg
[downloads-url]: https://npmjs.org/package/negotiator
[github-actions-ci-image]: https://img.shields.io/github/workflow/status/jshttp/negotiator/ci/master?label=ci
[github-actions-ci-url]: https://github.com/jshttp/negotiator/actions/workflows/ci.yml


---

## 8.14.1 (2025-03-05)

### Bug fixes

Fix an issue where `await` expressions in class field initializers were inappropriately allowed.

Properly allow await inside an async arrow function inside a class field initializer.

Mention the source file name in syntax error messages when given.

Properly add an empty `attributes` property to every form of `ExportNamedDeclaration`.

## 8.14.0 (2024-10-27)

### New features

Support ES2025 import attributes.

Support ES2025 RegExp modifiers.

### Bug fixes

Support some missing Unicode properties.

## 8.13.0 (2024-10-16)

### New features

Upgrade to Unicode 16.0.

## 8.12.1 (2024-07-03)

### Bug fixes

Fix a regression that caused Acorn to no longer run on Node versions <8.10.

## 8.12.0 (2024-06-14)

### New features

Support ES2025 duplicate capture group names in regular expressions.

### Bug fixes

Include `VariableDeclarator` in the `AnyNode` type so that walker objects can refer to it without getting a type error.

Properly raise a parse error for invalid `for`/`of` statements using `async` as binding name.

Properly recognize \"use strict\" when preceded by a string with an escaped newline.

Mark the `Parser` constructor as protected, not private, so plugins can extend it without type errors.

Fix a bug where some invalid `delete` expressions were let through when the operand was parenthesized and `preserveParens` was enabled.

Properly normalize line endings in raw strings of invalid template tokens.

Properly track line numbers for escaped newlines in strings.

Fix a bug that broke line number accounting after a template literal with invalid escape sequences.

## 8.11.3 (2023-12-29)

### Bug fixes

Add `Function` and `Class` to the `AggregateType` type, so that they can be used in walkers without raising a type error.

Make sure `onToken` get an `import` keyword token when parsing `import.meta`.

Fix a bug where `.loc.start` could be undefined for `new.target` `meta` nodes.

## 8.11.2 (2023-10-27)

### Bug fixes

Fix a bug that caused regular expressions after colon tokens to not be properly tokenized in some circumstances.

## 8.11.1 (2023-10-26)

### Bug fixes

Fix a regression where `onToken` would receive 'name' tokens for 'new' keyword tokens.

## 8.11.0 (2023-10-26)

### Bug fixes

Fix an issue where tokenizing (without parsing) an object literal with a property named `class` or `function` could, in some circumstance, put the tokenizer into an invalid state.

Fix an issue where a slash after a call to a propery named the same as some keywords would be tokenized as a regular expression.

### New features

Upgrade to Unicode 15.1.

Use a set of new, much more precise, TypeScript types.

## 8.10.0 (2023-07-05)

### New features

Add a `checkPrivateFields` option that disables strict checking of private property use.

## 8.9.0 (2023-06-16)

### Bug fixes

Forbid dynamic import after `new`, even when part of a member expression.

### New features

Add Unicode properties for ES2023.

Add support for the `v` flag to regular expressions.

## 8.8.2 (2023-01-23)

### Bug fixes

Fix a bug that caused `allowHashBang` to be set to false when not provided, even with `ecmaVersion >= 14`.

Fix an exception when passing no option object to `parse` or `new Parser`.

Fix incorrect parse error on `if (0) let\n[astral identifier char]`.

## 8.8.1 (2022-10-24)

### Bug fixes

Make type for `Comment` compatible with estree types.

## 8.8.0 (2022-07-21)

### Bug fixes

Allow parentheses around spread args in destructuring object assignment.

Fix an issue where the tree contained `directive` properties in when parsing with a language version that doesn't support them.

### New features

Support hashbang comments by default in ECMAScript 2023 and later.

## 8.7.1 (2021-04-26)

### Bug fixes

Stop handling `"use strict"` directives in ECMAScript versions before 5.

Fix an issue where duplicate quoted export names in `export *` syntax were incorrectly checked.

Add missing type for `tokTypes`.

## 8.7.0 (2021-12-27)

### New features

Support quoted export names.

Upgrade to Unicode 14.

Add support for Unicode 13 properties in regular expressions.

### Bug fixes

Use a loop to find line breaks, because the existing regexp search would overrun the end of the searched range and waste a lot of time in minified code.

## 8.6.0 (2021-11-18)

### Bug fixes

Fix a bug where an object literal with multiple `__proto__` properties would incorrectly be accepted if a later property value held an assigment.

### New features

Support class private fields with the `in` operator.

## 8.5.0 (2021-09-06)

### Bug fixes

Improve context-dependent tokenization in a number of corner cases.

Fix location tracking after a 0x2028 or 0x2029 character in a string literal (which before did not increase the line number).

Fix an issue where arrow function bodies in for loop context would inappropriately consume `in` operators.

Fix wrong end locations stored on SequenceExpression nodes.

Implement restriction that `for`/`of` loop LHS can't start with `let`.

### New features

Add support for ES2022 class static blocks.

Allow multiple input files to be passed to the CLI tool.

## 8.4.1 (2021-06-24)

### Bug fixes

Fix a bug where `allowAwaitOutsideFunction` would allow `await` in class field initializers, and setting `ecmaVersion` to 13 or higher would allow top-level await in non-module sources.

## 8.4.0 (2021-06-11)

### New features

A new option, `allowSuperOutsideMethod`, can be used to suppress the error when `super` is used in the wrong context.

## 8.3.0 (2021-05-31)

### New features

Default `allowAwaitOutsideFunction` to true for ECMAScript 2022 an higher.

Add support for the `d` ([indices](https://github.com/tc39/proposal-regexp-match-indices)) regexp flag.

## 8.2.4 (2021-05-04)

### Bug fixes

Fix spec conformity in corner case 'for await (async of ...)'.

## 8.2.3 (2021-05-04)

### Bug fixes

Fix an issue where the library couldn't parse 'for (async of ...)'.

Fix a bug in UTF-16 decoding that would read characters incorrectly in some circumstances.

## 8.2.2 (2021-04-29)

### Bug fixes

Fix a bug where a class field initialized to an async arrow function wouldn't allow await inside it. Same issue existed for generator arrow functions with yield.

## 8.2.1 (2021-04-24)

### Bug fixes

Fix a regression introduced in 8.2.0 where static or async class methods with keyword names fail to parse.

## 8.2.0 (2021-04-24)

### New features

Add support for ES2022 class fields and private methods.

## 8.1.1 (2021-04-12)

### Various

Stop shipping source maps in the NPM package.

## 8.1.0 (2021-03-09)

### Bug fixes

Fix a spurious error in nested destructuring arrays.

### New features

Expose `allowAwaitOutsideFunction` in CLI interface.

Make `allowImportExportAnywhere` also apply to `import.meta`.

## 8.0.5 (2021-01-25)

### Bug fixes

Adjust package.json to work with Node 12.16.0 and 13.0-13.6.

## 8.0.4 (2020-10-05)

### Bug fixes

Make `await x ** y` an error, following the spec.

Fix potentially exponential regular expression.

## 8.0.3 (2020-10-02)

### Bug fixes

Fix a wasteful loop during `Parser` creation when setting `ecmaVersion` to `"latest"`.

## 8.0.2 (2020-09-30)

### Bug fixes

Make the TypeScript types reflect the current allowed values for `ecmaVersion`.

Fix another regexp/division tokenizer issue.

## 8.0.1 (2020-08-12)

### Bug fixes

Provide the correct value in the `version` export.

## 8.0.0 (2020-08-12)

### Bug fixes

Disallow expressions like `(a = b) = c`.

Make non-octal escape sequences a syntax error in strict mode.

### New features

The package can now be loaded directly as an ECMAScript module in node 13+.

Update to the set of Unicode properties from ES2021.

### Breaking changes

The `ecmaVersion` option is now required. For the moment, omitting it will still work with a warning, but that will change in a future release.

Some changes to method signatures that may be used by plugins.

## 7.4.0 (2020-08-03)

### New features

Add support for logical assignment operators.

Add support for numeric separators.

## 7.3.1 (2020-06-11)

### Bug fixes

Make the string in the `version` export match the actual library version.

## 7.3.0 (2020-06-11)

### Bug fixes

Fix a bug that caused parsing of object patterns with a property named `set` that had a default value to fail.

### New features

Add support for optional chaining (`?.`).

## 7.2.0 (2020-05-09)

### Bug fixes

Fix precedence issue in parsing of async arrow functions.

### New features

Add support for nullish coalescing.

Add support for `import.meta`.

Support `export * as ...` syntax.

Upgrade to Unicode 13.

## 6.4.1 (2020-03-09)

### Bug fixes

More carefully check for valid UTF16 surrogate pairs in regexp validator.

## 7.1.1 (2020-03-01)

### Bug fixes

Treat `\8` and `\9` as invalid escapes in template strings.

Allow unicode escapes in property names that are keywords.

Don't error on an exponential operator expression as argument to `await`.

More carefully check for valid UTF16 surrogate pairs in regexp validator.

## 7.1.0 (2019-09-24)

### Bug fixes

Disallow trailing object literal commas when ecmaVersion is less than 5.

### New features

Add a static `acorn` property to the `Parser` class that contains the entire module interface, to allow plugins to access the instance of the library that they are acting on.

## 7.0.0 (2019-08-13)

### Breaking changes

Changes the node format for dynamic imports to use the `ImportExpression` node type, as defined in [ESTree](https://github.com/estree/estree/blob/master/es2020.md#importexpression).

Makes 10 (ES2019) the default value for the `ecmaVersion` option.

## 6.3.0 (2019-08-12)

### New features

`sourceType: "module"` can now be used even when `ecmaVersion` is less than 6, to parse module-style code that otherwise conforms to an older standard.

## 6.2.1 (2019-07-21)

### Bug fixes

Fix bug causing Acorn to treat some characters as identifier characters that shouldn't be treated as such.

Fix issue where setting the `allowReserved` option to `"never"` allowed reserved words in some circumstances.

## 6.2.0 (2019-07-04)

### Bug fixes

Improve valid assignment checking in `for`/`in` and `for`/`of` loops.

Disallow binding `let` in patterns.

### New features

Support bigint syntax with `ecmaVersion` >= 11.

Support dynamic `import` syntax with `ecmaVersion` >= 11.

Upgrade to Unicode version 12.

## 6.1.1 (2019-02-27)

### Bug fixes

Fix bug that caused parsing default exports of with names to fail.

## 6.1.0 (2019-02-08)

### Bug fixes

Fix scope checking when redefining a `var` as a lexical binding.

### New features

Split up `parseSubscripts` to use an internal `parseSubscript` method to make it easier to extend with plugins.

## 6.0.7 (2019-02-04)

### Bug fixes

Check that exported bindings are defined.

Don't treat `\u180e` as a whitespace character.

Check for duplicate parameter names in methods.

Don't allow shorthand properties when they are generators or async methods.

Forbid binding `await` in async arrow function's parameter list.

## 6.0.6 (2019-01-30)

### Bug fixes

The content of class declarations and expressions is now always parsed in strict mode.

Don't allow `let` or `const` to bind the variable name `let`.

Treat class declarations as lexical.

Don't allow a generator function declaration as the sole body of an `if` or `else`.

Ignore `"use strict"` when after an empty statement.

Allow string line continuations with special line terminator characters.

Treat `for` bodies as part of the `for` scope when checking for conflicting bindings.

Fix bug with parsing `yield` in a `for` loop initializer.

Implement special cases around scope checking for functions.

## 6.0.5 (2019-01-02)

### Bug fixes

Fix TypeScript type for `Parser.extend` and add `allowAwaitOutsideFunction` to options type.

Don't treat `let` as a keyword when the next token is `{` on the next line.

Fix bug that broke checking for parentheses around an object pattern in a destructuring assignment when `preserveParens` was on.

## 6.0.4 (2018-11-05)

### Bug fixes

Further improvements to tokenizing regular expressions in corner cases.

## 6.0.3 (2018-11-04)

### Bug fixes

Fix bug in tokenizing an expression-less return followed by a function followed by a regular expression.

Remove stray symlink in the package tarball.

## 6.0.2 (2018-09-26)

### Bug fixes

Fix bug where default expressions could fail to parse inside an object destructuring assignment expression.

## 6.0.1 (2018-09-14)

### Bug fixes

Fix wrong value in `version` export.

## 6.0.0 (2018-09-14)

### Bug fixes

Better handle variable-redefinition checks for catch bindings and functions directly under if statements.

Forbid `new.target` in top-level arrow functions.

Fix issue with parsing a regexp after `yield` in some contexts.

### New features

The package now comes with TypeScript definitions.

### Breaking changes

The default value of the `ecmaVersion` option is now 9 (2018).

Plugins work differently, and will have to be rewritten to work with this version.

The loose parser and walker have been moved into separate packages (`acorn-loose` and `acorn-walk`).

## 5.7.3 (2018-09-10)

### Bug fixes

Fix failure to tokenize regexps after expressions like `x.of`.

Better error message for unterminated template literals.

## 5.7.2 (2018-08-24)

### Bug fixes

Properly handle `allowAwaitOutsideFunction` in for statements.

Treat function declarations at the top level of modules like let bindings.

Don't allow async function declarations as the only statement under a label.

## 5.7.0 (2018-06-15)

### New features

Upgraded to Unicode 11.

## 5.6.0 (2018-05-31)

### New features

Allow U+2028 and U+2029 in string when ECMAVersion >= 10.

Allow binding-less catch statements when ECMAVersion >= 10.

Add `allowAwaitOutsideFunction` option for parsing top-level `await`.

## 5.5.3 (2018-03-08)

### Bug fixes

A _second_ republish of the code in 5.5.1, this time with yarn, to hopefully get valid timestamps.

## 5.5.2 (2018-03-08)

### Bug fixes

A republish of the code in 5.5.1 in an attempt to solve an issue with the file timestamps in the npm package being 0.

## 5.5.1 (2018-03-06)

### Bug fixes

Fix misleading error message for octal escapes in template strings.

## 5.5.0 (2018-02-27)

### New features

The identifier character categorization is now based on Unicode version 10.

Acorn will now validate the content of regular expressions, including new ES9 features.

## 5.4.0 (2018-02-01)

### Bug fixes

Disallow duplicate or escaped flags on regular expressions.

Disallow octal escapes in strings in strict mode.

### New features

Add support for async iteration.

Add support for object spread and rest.

## 5.3.0 (2017-12-28)

### Bug fixes

Fix parsing of floating point literals with leading zeroes in loose mode.

Allow duplicate property names in object patterns.

Don't allow static class methods named `prototype`.

Disallow async functions directly under `if` or `else`.

Parse right-hand-side of `for`/`of` as an assignment expression.

Stricter parsing of `for`/`in`.

Don't allow unicode escapes in contextual keywords.

### New features

Parsing class members was factored into smaller methods to allow plugins to hook into it.

## 5.2.1 (2017-10-30)

### Bug fixes

Fix a token context corruption bug.

## 5.2.0 (2017-10-30)

### Bug fixes

Fix token context tracking for `class` and `function` in property-name position.

Make sure `%*` isn't parsed as a valid operator.

Allow shorthand properties `get` and `set` to be followed by default values.

Disallow `super` when not in callee or object position.

### New features

Support [`directive` property](https://github.com/estree/estree/compare/b3de58c9997504d6fba04b72f76e6dd1619ee4eb...1da8e603237144f44710360f8feb7a9977e905e0) on directive expression statements.

## 5.1.2 (2017-09-04)

### Bug fixes

Disable parsing of legacy HTML-style comments in modules.

Fix parsing of async methods whose names are keywords.

## 5.1.1 (2017-07-06)

### Bug fixes

Fix problem with disambiguating regexp and division after a class.

## 5.1.0 (2017-07-05)

### Bug fixes

Fix tokenizing of regexps in an object-desctructuring `for`/`of` loop and after `yield`.

Parse zero-prefixed numbers with non-octal digits as decimal.

Allow object/array patterns in rest parameters.

Don't error when `yield` is used as a property name.

Allow `async` as a shorthand object property.

### New features

Implement the [template literal revision proposal](https://github.com/tc39/proposal-template-literal-revision) for ES9.

## 5.0.3 (2017-04-01)

### Bug fixes

Fix spurious duplicate variable definition errors for named functions.

## 5.0.2 (2017-03-30)

### Bug fixes

A binary operator after a parenthesized arrow expression is no longer incorrectly treated as an error.

## 5.0.0 (2017-03-28)

### Bug fixes

Raise an error for duplicated lexical bindings.

Fix spurious error when an assignement expression occurred after a spread expression.

Accept regular expressions after `of` (in `for`/`of`), `yield` (in a generator), and braced arrow functions.

Allow labels in front or `var` declarations, even in strict mode.

### Breaking changes

Parse declarations following `export default` as declaration nodes, not expressions. This means that class and function declarations nodes can now have `null` as their `id`.

## 4.0.11 (2017-02-07)

### Bug fixes

Allow all forms of member expressions to be parenthesized as lvalue.

## 4.0.10 (2017-02-07)

### Bug fixes

Don't expect semicolons after default-exported functions or classes, even when they are expressions.

Check for use of `'use strict'` directives in non-simple parameter functions, even when already in strict mode.

## 4.0.9 (2017-02-06)

### Bug fixes

Fix incorrect error raised for parenthesized simple assignment targets, so that `(x) = 1` parses again.

## 4.0.8 (2017-02-03)

### Bug fixes

Solve spurious parenthesized pattern errors by temporarily erring on the side of accepting programs that our delayed errors don't handle correctly yet.

## 4.0.7 (2017-02-02)

### Bug fixes

Accept invalidly rejected code like `(x).y = 2` again.

Don't raise an error when a function _inside_ strict code has a non-simple parameter list.

## 4.0.6 (2017-02-02)

### Bug fixes

Fix exponential behavior (manifesting itself as a complete hang for even relatively small source files) introduced by the new 'use strict' check.

## 4.0.5 (2017-02-02)

### Bug fixes

Disallow parenthesized pattern expressions.

Allow keywords as export names.

Don't allow the `async` keyword to be parenthesized.

Properly raise an error when a keyword contains a character escape.

Allow `"use strict"` to appear after other string literal expressions.

Disallow labeled declarations.

## 4.0.4 (2016-12-19)

### Bug fixes

Fix crash when `export` was followed by a keyword that can't be
exported.

## 4.0.3 (2016-08-16)

### Bug fixes

Allow regular function declarations inside single-statement `if` branches in loose mode. Forbid them entirely in strict mode.

Properly parse properties named `async` in ES2017 mode.

Fix bug where reserved words were broken in ES2017 mode.

## 4.0.2 (2016-08-11)

### Bug fixes

Don't ignore period or 'e' characters after octal numbers.

Fix broken parsing for call expressions in default parameter values of arrow functions.

## 4.0.1 (2016-08-08)

### Bug fixes

Fix false positives in duplicated export name errors.

## 4.0.0 (2016-08-07)

### Breaking changes

The default `ecmaVersion` option value is now 7.

A number of internal method signatures changed, so plugins might need to be updated.

### Bug fixes

The parser now raises errors on duplicated export names.

`arguments` and `eval` can now be used in shorthand properties.

Duplicate parameter names in non-simple argument lists now always produce an error.

### New features

The `ecmaVersion` option now also accepts year-style version numbers
(2015, etc).

Support for `async`/`await` syntax when `ecmaVersion` is >= 8.

Support for trailing commas in call expressions when `ecmaVersion` is >= 8.

## 3.3.0 (2016-07-25)

### Bug fixes

Fix bug in tokenizing of regexp operator after a function declaration.

Fix parser crash when parsing an array pattern with a hole.

### New features

Implement check against complex argument lists in functions that enable strict mode in ES7.

## 3.2.0 (2016-06-07)

### Bug fixes

Improve handling of lack of unicode regexp support in host
environment.

Properly reject shorthand properties whose name is a keyword.

### New features

Visitors created with `visit.make` now have their base as _prototype_, rather than copying properties into a fresh object.

## 3.1.0 (2016-04-18)

### Bug fixes

Properly tokenize the division operator directly after a function expression.

Allow trailing comma in destructuring arrays.

## 3.0.4 (2016-02-25)

### Fixes

Allow update expressions as left-hand-side of the ES7 exponential operator.

## 3.0.2 (2016-02-10)

### Fixes

Fix bug that accidentally made `undefined` a reserved word when parsing ES7.

## 3.0.0 (2016-02-10)

### Breaking changes

The default value of the `ecmaVersion` option is now 6 (used to be 5).

Support for comprehension syntax (which was dropped from the draft spec) has been removed.

### Fixes

`let` and `yield` are now “contextual keywords”, meaning you can mostly use them as identifiers in ES5 non-strict code.

A parenthesized class or function expression after `export default` is now parsed correctly.

### New features

When `ecmaVersion` is set to 7, Acorn will parse the exponentiation operator (`**`).

The identifier character ranges are now based on Unicode 8.0.0.

Plugins can now override the `raiseRecoverable` method to override the way non-critical errors are handled.

## 2.7.0 (2016-01-04)

### Fixes

Stop allowing rest parameters in setters.

Disallow `y` rexexp flag in ES5.

Disallow `\00` and `\000` escapes in strict mode.

Raise an error when an import name is a reserved word.

## 2.6.2 (2015-11-10)

### Fixes

Don't crash when no options object is passed.

## 2.6.0 (2015-11-09)

### Fixes

Add `await` as a reserved word in module sources.

Disallow `yield` in a parameter default value for a generator.

Forbid using a comma after a rest pattern in an array destructuring.

### New features

Support parsing stdin in command-line tool.

## 2.5.0 (2015-10-27)

### Fixes

Fix tokenizer support in the command-line tool.

Stop allowing `new.target` outside of functions.

Remove legacy `guard` and `guardedHandler` properties from try nodes.

Stop allowing multiple `__proto__` properties on an object literal in strict mode.

Don't allow rest parameters to be non-identifier patterns.

Check for duplicate paramter names in arrow functions.


---

# Acorn

A tiny, fast JavaScript parser written in JavaScript.

## Community

Acorn is open source software released under an
[MIT license](https://github.com/acornjs/acorn/blob/master/acorn/LICENSE).

You are welcome to
[report bugs](https://github.com/acornjs/acorn/issues) or create pull
requests on [github](https://github.com/acornjs/acorn).

## Installation

The easiest way to install acorn is from [`npm`](https://www.npmjs.com/):

```sh
npm install acorn
```

Alternately, you can download the source and build acorn yourself:

```sh
git clone https://github.com/acornjs/acorn.git
cd acorn
npm install
```

## Interface

**parse**`(input, options)` is the main interface to the library. The
`input` parameter is a string, `options` must be an object setting
some of the options listed below. The return value will be an abstract
syntax tree object as specified by the [ESTree
spec](https://github.com/estree/estree).

```javascript
let acorn = require("acorn");
console.log(acorn.parse("1 + 1", {ecmaVersion: 2020}));
```

When encountering a syntax error, the parser will raise a
`SyntaxError` object with a meaningful message. The error object will
have a `pos` property that indicates the string offset at which the
error occurred, and a `loc` object that contains a `{line, column}`
object referring to that same position.

Options are provided by in a second argument, which should be an
object containing any of these fields (only `ecmaVersion` is
required):

- **ecmaVersion**: Indicates the ECMAScript version to parse. Can be a
  number, either in year (`2022`) or plain version number (`6`) form,
  or `"latest"` (the latest the library supports). This influences
  support for strict mode, the set of reserved words, and support for
  new syntax features.

  **NOTE**: Only 'stage 4' (finalized) ECMAScript features are being
  implemented by Acorn. Other proposed new features must be
  implemented through plugins.

- **sourceType**: Indicate the mode the code should be parsed in. Can be
  either `"script"` or `"module"`. This influences global strict mode
  and parsing of `import` and `export` declarations.

  **NOTE**: If set to `"module"`, then static `import` / `export` syntax
  will be valid, even if `ecmaVersion` is less than 6.

- **onInsertedSemicolon**: If given a callback, that callback will be
  called whenever a missing semicolon is inserted by the parser. The
  callback will be given the character offset of the point where the
  semicolon is inserted as argument, and if `locations` is on, also a
  `{line, column}` object representing this position.

- **onTrailingComma**: Like `onInsertedSemicolon`, but for trailing
  commas.

- **allowReserved**: If `false`, using a reserved word will generate
  an error. Defaults to `true` for `ecmaVersion` 3, `false` for higher
  versions. When given the value `"never"`, reserved words and
  keywords can also not be used as property names (as in Internet
  Explorer's old parser).

- **allowReturnOutsideFunction**: By default, a return statement at
  the top level raises an error. Set this to `true` to accept such
  code.

- **allowImportExportEverywhere**: By default, `import` and `export`
  declarations can only appear at a program's top level. Setting this
  option to `true` allows them anywhere where a statement is allowed,
  and also allows `import.meta` expressions to appear in scripts
  (when `sourceType` is not `"module"`).

- **allowAwaitOutsideFunction**: If `false`, `await` expressions can
  only appear inside `async` functions. Defaults to `true` in modules
  for `ecmaVersion` 2022 and later, `false` for lower versions.
  Setting this option to `true` allows to have top-level `await`
  expressions. They are still not allowed in non-`async` functions,
  though.

- **allowSuperOutsideMethod**: By default, `super` outside a method
  raises an error. Set this to `true` to accept such code.

- **allowHashBang**: When this is enabled, if the code starts with the
  characters `#!` (as in a shellscript), the first line will be
  treated as a comment. Defaults to true when `ecmaVersion` >= 2023.

- **checkPrivateFields**: By default, the parser will verify that
  private properties are only used in places where they are valid and
  have been declared. Set this to false to turn such checks off.

- **locations**: When `true`, each node has a `loc` object attached
  with `start` and `end` subobjects, each of which contains the
  one-based line and zero-based column numbers in `{line, column}`
  form. Default is `false`.

- **onToken**: If a function is passed for this option, each found
  token will be passed in same format as tokens returned from
  `tokenizer().getToken()`.

  If array is passed, each found token is pushed to it.

  Note that you are not allowed to call the parser from the
  callback—that will corrupt its internal state.

- **onComment**: If a function is passed for this option, whenever a
  comment is encountered the function will be called with the
  following parameters:

  - `block`: `true` if the comment is a block comment, false if it
    is a line comment.
  - `text`: The content of the comment.
  - `start`: Character offset of the start of the comment.
  - `end`: Character offset of the end of the comment.

  When the `locations` options is on, the `{line, column}` locations
  of the comment’s start and end are passed as two additional
  parameters.

  If array is passed for this option, each found comment is pushed
  to it as object in Esprima format:

  ```javascript
  {
    "type": "Line" | "Block",
    "value": "comment text",
    "start": Number,
    "end": Number,
    // If `locations` option is on:
    "loc": {
      "start": {line: Number, column: Number}
      "end": {line: Number, column: Number}
    },
    // If `ranges` option is on:
    "range": [Number, Number]
  }
  ```

  Note that you are not allowed to call the parser from the
  callback—that will corrupt its internal state.

- **ranges**: Nodes have their start and end characters offsets
  recorded in `start` and `end` properties (directly on the node,
  rather than the `loc` object, which holds line/column data. To also
  add a
  [semi-standardized](https://bugzilla.mozilla.org/show_bug.cgi?id=745678)
  `range` property holding a `[start, end]` array with the same
  numbers, set the `ranges` option to `true`.

- **program**: It is possible to parse multiple files into a single
  AST by passing the tree produced by parsing the first file as the
  `program` option in subsequent parses. This will add the toplevel
  forms of the parsed file to the "Program" (top) node of an existing
  parse tree.

- **sourceFile**: When the `locations` option is `true`, you can pass
  this option to add a `source` attribute in every node’s `loc`
  object. Note that the contents of this option are not examined or
  processed in any way; you are free to use whatever format you
  choose.

- **directSourceFile**: Like `sourceFile`, but a `sourceFile` property
  will be added (regardless of the `location` option) directly to the
  nodes, rather than the `loc` object.

- **preserveParens**: If this option is `true`, parenthesized expressions
  are represented by (non-standard) `ParenthesizedExpression` nodes
  that have a single `expression` property containing the expression
  inside parentheses.

**parseExpressionAt**`(input, offset, options)` will parse a single
expression in a string, and return its AST. It will not complain if
there is more of the string left after the expression.

**tokenizer**`(input, options)` returns an object with a `getToken`
method that can be called repeatedly to get the next token, a `{start,
end, type, value}` object (with added `loc` property when the
`locations` option is enabled and `range` property when the `ranges`
option is enabled). When the token's type is `tokTypes.eof`, you
should stop calling the method, since it will keep returning that same
token forever.

Note that tokenizing JavaScript without parsing it is, in modern
versions of the language, not really possible due to the way syntax is
overloaded in ways that can only be disambiguated by the parse
context. This package applies a bunch of heuristics to try and do a
reasonable job, but you are advised to use `parse` with the `onToken`
option instead of this.

In ES6 environment, returned result can be used as any other
protocol-compliant iterable:

```javascript
for (let token of acorn.tokenizer(str)) {
  // iterate over the tokens
}

// transform code to array of tokens:
var tokens = [...acorn.tokenizer(str)];
```

**tokTypes** holds an object mapping names to the token type objects
that end up in the `type` properties of tokens.

**getLineInfo**`(input, offset)` can be used to get a `{line,
column}` object for a given program string and offset.

### The `Parser` class

Instances of the **`Parser`** class contain all the state and logic
that drives a parse. It has static methods `parse`,
`parseExpressionAt`, and `tokenizer` that match the top-level
functions by the same name.

When extending the parser with plugins, you need to call these methods
on the extended version of the class. To extend a parser with plugins,
you can use its static `extend` method.

```javascript
var acorn = require("acorn");
var jsx = require("acorn-jsx");
var JSXParser = acorn.Parser.extend(jsx());
JSXParser.parse("foo(<bar/>)", {ecmaVersion: 2020});
```

The `extend` method takes any number of plugin values, and returns a
new `Parser` class that includes the extra parser logic provided by
the plugins.

## Command line interface

The `bin/acorn` utility can be used to parse a file from the command
line. It accepts as arguments its input file and the following
options:

- `--ecma3|--ecma5|--ecma6|--ecma7|--ecma8|--ecma9|--ecma10`: Sets the ECMAScript version
  to parse. Default is version 9.

- `--module`: Sets the parsing mode to `"module"`. Is set to `"script"` otherwise.

- `--locations`: Attaches a "loc" object to each node with "start" and
  "end" subobjects, each of which contains the one-based line and
  zero-based column numbers in `{line, column}` form.

- `--allow-hash-bang`: If the code starts with the characters #! (as
  in a shellscript), the first line will be treated as a comment.

- `--allow-await-outside-function`: Allows top-level `await` expressions.
  See the `allowAwaitOutsideFunction` option for more information.

- `--compact`: No whitespace is used in the AST output.

- `--silent`: Do not output the AST, just return the exit status.

- `--help`: Print the usage information and quit.

The utility spits out the syntax tree as JSON data.

## Existing plugins

 - [`acorn-jsx`](https://github.com/RReverser/acorn-jsx): Parse [Facebook JSX syntax extensions](https://github.com/facebook/jsx)


---

# Acorn-JSX

[![Build Status](https://travis-ci.org/acornjs/acorn-jsx.svg?branch=master)](https://travis-ci.org/acornjs/acorn-jsx)
[![NPM version](https://img.shields.io/npm/v/acorn-jsx.svg)](https://www.npmjs.org/package/acorn-jsx)

This is plugin for [Acorn](http://marijnhaverbeke.nl/acorn/) - a tiny, fast JavaScript parser, written completely in JavaScript.

It was created as an experimental alternative, faster [React.js JSX](http://facebook.github.io/react/docs/jsx-in-depth.html) parser. Later, it replaced the [official parser](https://github.com/facebookarchive/esprima) and these days is used by many prominent development tools.

## Transpiler

Please note that this tool only parses source code to JSX AST, which is useful for various language tools and services. If you want to transpile your code to regular ES5-compliant JavaScript with source map, check out [Babel](https://babeljs.io/) and [Buble](https://buble.surge.sh/) transpilers which use `acorn-jsx` under the hood.

## Usage

Requiring this module provides you with an Acorn plugin that you can use like this:

```javascript
var acorn = require("acorn");
var jsx = require("acorn-jsx");
acorn.Parser.extend(jsx()).parse("my(<jsx/>, 'code');");
```

Note that official spec doesn't support mix of XML namespaces and object-style access in tag names (#27) like in `<namespace:Object.Property />`, so it was deprecated in `acorn-jsx@3.0`. If you still want to opt-in to support of such constructions, you can pass the following option:

```javascript
acorn.Parser.extend(jsx({ allowNamespacedObjects: true }))
```

Also, since most apps use pure React transformer, a new option was introduced that allows to prohibit namespaces completely:

```javascript
acorn.Parser.extend(jsx({ allowNamespaces: false }))
```

Note that by default `allowNamespaces` is enabled for spec compliancy.

## License

This plugin is issued under the [MIT license](./LICENSE).


---

## 8.3.4 (2024-09-09)

### Bug fixes

Walk SwitchCase nodes as separate nodes.

## 8.3.3 (2024-01-11)

### Bug fixes

Make acorn a dependency because acorn-walk uses the types from that package.

## 8.3.2 (2024-01-11)

### Bug fixes

Add missing type for `findNodeBefore`.

## 8.3.1 (2023-12-06)

### Bug fixes

Add `Function` and `Class` to the `AggregateType` type, so that they can be used in walkers without raising a type error.

Visitor functions are now called in such a way that their `this` refers to the object they are part of.

## 8.3.0 (2023-10-26)

### New features

Use a set of new, much more precise, TypeScript types.

## 8.2.0 (2021-09-06)

### New features

Add support for walking ES2022 class static blocks.

## 8.1.1 (2021-06-29)

### Bug fixes

Include `base` in the type declarations.

## 8.1.0 (2021-04-24)

### New features

Support node types for class fields and private methods.

## 8.0.2 (2021-01-25)

### Bug fixes

Adjust package.json to work with Node 12.16.0 and 13.0-13.6.

## 8.0.0 (2021-01-05)

### Bug fixes

Fix a bug where `full` and `fullAncestor` would skip nodes with overridden types.

## 8.0.0 (2020-08-12)

### New features

The package can now be loaded directly as an ECMAScript module in node 13+.

## 7.2.0 (2020-06-17)

### New features

Support optional chaining and nullish coalescing.

Support `import.meta`.

Add support for `export * as ns from "source"`.

## 7.1.1 (2020-02-13)

### Bug fixes

Clean up the type definitions to actually work well with the main parser.

## 7.1.0 (2020-02-11)

### New features

Add a TypeScript definition file for the library.

## 7.0.0 (2017-08-12)

### New features

Support walking `ImportExpression` nodes.

## 6.2.0 (2017-07-04)

### New features

Add support for `Import` nodes.

## 6.1.0 (2018-09-28)

### New features

The walker now walks `TemplateElement` nodes.

## 6.0.1 (2018-09-14)

### Bug fixes

Fix bad "main" field in package.json.

## 6.0.0 (2018-09-14)

### Breaking changes

This is now a separate package, `acorn-walk`, rather than part of the main `acorn` package.

The `ScopeBody` and `ScopeExpression` meta-node-types are no longer supported.

## 5.7.1 (2018-06-15)

### Bug fixes

Make sure the walker and bin files are rebuilt on release (the previous release didn't get the up-to-date versions).

## 5.7.0 (2018-06-15)

### Bug fixes

Fix crash in walker when walking a binding-less catch node.

## 5.6.2 (2018-06-05)

### Bug fixes

In the walker, go back to allowing the `baseVisitor` argument to be null to default to the default base everywhere.

## 5.6.1 (2018-06-01)

### Bug fixes

Fix regression when passing `null` as fourth argument to `walk.recursive`.

## 5.6.0 (2018-05-31)

### Bug fixes

Fix a bug in the walker that caused a crash when walking an object pattern spread.

## 5.5.1 (2018-03-06)

### Bug fixes

Fix regression in walker causing property values in object patterns to be walked as expressions.

## 5.5.0 (2018-02-27)

### Bug fixes

Support object spread in the AST walker.

## 5.4.1 (2018-02-02)

### Bug fixes

5.4.0 somehow accidentally included an old version of walk.js.

## 5.2.0 (2017-10-30)

### Bug fixes

The `full` and `fullAncestor` walkers no longer visit nodes multiple times.

## 5.1.0 (2017-07-05)

### New features

New walker functions `full` and `fullAncestor`.

## 3.2.0 (2016-06-07)

### New features

Make it possible to use `visit.ancestor` with a walk state.

## 3.1.0 (2016-04-18)

### New features

The walker now allows defining handlers for `CatchClause` nodes.

## 2.5.2 (2015-10-27)

### Fixes

Fix bug where the walker walked an exported `let` statement as an expression.


---

# Acorn AST walker

An abstract syntax tree walker for the
[ESTree](https://github.com/estree/estree) format.

## Community

Acorn is open source software released under an
[MIT license](https://github.com/acornjs/acorn/blob/master/acorn-walk/LICENSE).

You are welcome to
[report bugs](https://github.com/acornjs/acorn/issues) or create pull
requests on [github](https://github.com/acornjs/acorn).

## Installation

The easiest way to install acorn is from [`npm`](https://www.npmjs.com/):

```sh
npm install acorn-walk
```

Alternately, you can download the source and build acorn yourself:

```sh
git clone https://github.com/acornjs/acorn.git
cd acorn
npm install
```

## Interface

An algorithm for recursing through a syntax tree is stored as an
object, with a property for each tree node type holding a function
that will recurse through such a node. There are several ways to run
such a walker.

**simple**`(node, visitors, base, state)` does a 'simple' walk over a
tree. `node` should be the AST node to walk, and `visitors` an object
with properties whose names correspond to node types in the [ESTree
spec](https://github.com/estree/estree). The properties should contain
functions that will be called with the node object and, if applicable
the state at that point. The last two arguments are optional. `base`
is a walker algorithm, and `state` is a start state. The default
walker will simply visit all statements and expressions and not
produce a meaningful state. (An example of a use of state is to track
scope at each point in the tree.)

```js
const acorn = require("acorn")
const walk = require("acorn-walk")

walk.simple(acorn.parse("let x = 10"), {
  Literal(node) {
    console.log(`Found a literal: ${node.value}`)
  }
})
```

**ancestor**`(node, visitors, base, state)` does a 'simple' walk over
a tree, building up an array of ancestor nodes (including the current node)
and passing the array to the callbacks as a third parameter.

```js
const acorn = require("acorn")
const walk = require("acorn-walk")

walk.ancestor(acorn.parse("foo('hi')"), {
  Literal(_node, _state, ancestors) {
    console.log("This literal's ancestors are:", ancestors.map(n => n.type))
  }
})
```

**recursive**`(node, state, functions, base)` does a 'recursive'
walk, where the walker functions are responsible for continuing the
walk on the child nodes of their target node. `state` is the start
state, and `functions` should contain an object that maps node types
to walker functions. Such functions are called with `(node, state, c)`
arguments, and can cause the walk to continue on a sub-node by calling
the `c` argument on it with `(node, state)` arguments. The optional
`base` argument provides the fallback walker functions for node types
that aren't handled in the `functions` object. If not given, the
default walkers will be used.

**make**`(functions, base)` builds a new walker object by using the
walker functions in `functions` and filling in the missing ones by
taking defaults from `base`.

**full**`(node, callback, base, state)` does a 'full' walk over a
tree, calling the callback with the arguments (node, state, type) for
each node

**fullAncestor**`(node, callback, base, state)` does a 'full' walk
over a tree, building up an array of ancestor nodes (including the
current node) and passing the array to the callbacks as a third
parameter.

```js
const acorn = require("acorn")
const walk = require("acorn-walk")

walk.full(acorn.parse("1 + 1"), node => {
  console.log(`There's a ${node.type} node at ${node.ch}`)
})
```

**findNodeAt**`(node, start, end, test, base, state)` tries to locate
a node in a tree at the given start and/or end offsets, which
satisfies the predicate `test`. `start` and `end` can be either `null`
(as wildcard) or a number. `test` may be a string (indicating a node
type) or a function that takes `(nodeType, node)` arguments and
returns a boolean indicating whether this node is interesting. `base`
and `state` are optional, and can be used to specify a custom walker.
Nodes are tested from inner to outer, so if two nodes match the
boundaries, the inner one will be preferred.

**findNodeAround**`(node, pos, test, base, state)` is a lot like
`findNodeAt`, but will match any node that exists 'around' (spanning)
the given position.

**findNodeAfter**`(node, pos, test, base, state)` is similar to
`findNodeAround`, but will match all nodes *after* the given position
(testing outer nodes before inner nodes).


---

address
=======

[![NPM version][npm-image]][npm-url]
[![Node.js CI](https://github.com/node-modules/address/actions/workflows/nodejs.yml/badge.svg)](https://github.com/node-modules/address/actions/workflows/nodejs.yml)
[![Test coverage][coveralls-image]][coveralls-url]
[![npm download][download-image]][download-url]

[npm-image]: https://img.shields.io/npm/v/address.svg?style=flat-square
[npm-url]: https://npmjs.org/package/address
[coveralls-image]: https://img.shields.io/coveralls/node-modules/address.svg?style=flat-square
[coveralls-url]: https://coveralls.io/r/node-modules/address?branch=master
[download-image]: https://img.shields.io/npm/dm/address.svg?style=flat-square
[download-url]: https://npmjs.org/package/address

Get current machine IP, MAC and DNS servers.

DNS servers receive from `/etc/resolv.conf`.

## Install

```bash
$ npm install address
```

## Usage

Get IP is sync and get MAC is async for now.

```js
const address = require('address');

// default interface 'eth' on linux, 'en' on osx.
address.ip();   // '192.168.0.2'
address.ipv6(); // 'fe80::7aca:39ff:feb0:e67d'
address.mac(function (err, addr) {
  console.log(addr); // '78:ca:39:b0:e6:7d'
});

// local loopback
address.ip('lo'); // '127.0.0.1'

// vboxnet MAC
address.mac('vboxnet', function (err, addr) {
  console.log(addr); // '0a:00:27:00:00:00'
});
```

### Get all addresses: IPv4, IPv6 and MAC

```js
address((err, addrs) => {
  console.log(addrs.ip, addrs.ipv6, addrs.mac);
  // '192.168.0.2', 'fe80::7aca:39ff:feb0:e67d', '78:ca:39:b0:e6:7d'
});

address('vboxnet', (err, addrs) => {
  console.log(addrs.ip, addrs.ipv6, addrs.mac);
  // '192.168.56.1', null, '0a:00:27:00:00:00'
});
```

### Get an interface info with family

```js
address.interface('IPv4', 'eth1');
// { address: '192.168.1.1', family: 'IPv4', mac: '78:ca:39:b0:e6:7d' }
```

### Get DNS servers

```js
address.dns((err, addrs) => {
  console.log(addrs);
  // ['10.13.2.1', '10.13.2.6']
});
```

## License

[MIT](LICENSE.txt)

<!-- GITCONTRIBUTOR_START -->

## Contributors

|[<img src="https://avatars.githubusercontent.com/u/156269?v=4" width="100px;"/><br/><sub><b>fengmk2</b></sub>](https://github.com/fengmk2)<br/>|[<img src="https://avatars.githubusercontent.com/u/1147375?v=4" width="100px;"/><br/><sub><b>alsotang</b></sub>](https://github.com/alsotang)<br/>|[<img src="https://avatars.githubusercontent.com/u/10237910?v=4" width="100px;"/><br/><sub><b>jkelleyrtp</b></sub>](https://github.com/jkelleyrtp)<br/>|[<img src="https://avatars.githubusercontent.com/u/1409643?v=4" width="100px;"/><br/><sub><b>mariodu</b></sub>](https://github.com/mariodu)<br/>|[<img src="https://avatars.githubusercontent.com/u/11351322?v=4" width="100px;"/><br/><sub><b>mathieutu</b></sub>](https://github.com/mathieutu)<br/>|[<img src="https://avatars.githubusercontent.com/u/2139038?v=4" width="100px;"/><br/><sub><b>zhangyuheng</b></sub>](https://github.com/zhangyuheng)<br/>|
| :---: | :---: | :---: | :---: | :---: | :---: |
[<img src="https://avatars.githubusercontent.com/u/1400114?v=4" width="100px;"/><br/><sub><b>coolme200</b></sub>](https://github.com/coolme200)<br/>|[<img src="https://avatars.githubusercontent.com/u/5856440?v=4" width="100px;"/><br/><sub><b>whxaxes</b></sub>](https://github.com/whxaxes)<br/>

This project follows the git-contributor [spec](https://github.com/xudafeng/git-contributor), auto updated at `Tue Sep 13 2022 09:09:11 GMT+0800`.

<!-- GITCONTRIBUTOR_END -->


---

# aggregate-error [![Build Status](https://travis-ci.org/sindresorhus/aggregate-error.svg?branch=master)](https://travis-ci.org/sindresorhus/aggregate-error)

> Create an error from multiple errors


## Install

```
$ npm install aggregate-error
```


## Usage

```js
const AggregateError = require('aggregate-error');

const error = new AggregateError([new Error('foo'), 'bar', {message: 'baz'}]);

throw error;
/*
AggregateError:
    Error: foo
        at Object.<anonymous> (/Users/sindresorhus/dev/aggregate-error/example.js:3:33)
    Error: bar
        at Object.<anonymous> (/Users/sindresorhus/dev/aggregate-error/example.js:3:13)
    Error: baz
        at Object.<anonymous> (/Users/sindresorhus/dev/aggregate-error/example.js:3:13)
    at AggregateError (/Users/sindresorhus/dev/aggregate-error/index.js:19:3)
    at Object.<anonymous> (/Users/sindresorhus/dev/aggregate-error/example.js:3:13)
    at Module._compile (module.js:556:32)
    at Object.Module._extensions..js (module.js:565:10)
    at Module.load (module.js:473:32)
    at tryModuleLoad (module.js:432:12)
    at Function.Module._load (module.js:424:3)
    at Module.runMain (module.js:590:10)
    at run (bootstrap_node.js:394:7)
    at startup (bootstrap_node.js:149:9)
*/

for (const individualError of error) {
	console.log(individualError);
}
//=> [Error: foo]
//=> [Error: bar]
//=> [Error: baz]
```


## API

### AggregateError(errors)

Returns an `Error` that is also an [`Iterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Iterators_and_Generators#Iterables) for the individual errors.

#### errors

Type: `Array<Error|Object|string>`

If a string, a new `Error` is created with the string as the error message.<br>
If a non-Error object, a new `Error` is created with all properties from the object copied over.


---

<img align="right" alt="Ajv logo" width="160" src="https://ajv.js.org/images/ajv_logo.png">

# Ajv: Another JSON Schema Validator

The fastest JSON Schema validator for Node.js and browser. Supports draft-04/06/07.

[![Build Status](https://travis-ci.org/ajv-validator/ajv.svg?branch=master)](https://travis-ci.org/ajv-validator/ajv)
[![npm](https://img.shields.io/npm/v/ajv.svg)](https://www.npmjs.com/package/ajv)
[![npm (beta)](https://img.shields.io/npm/v/ajv/beta)](https://www.npmjs.com/package/ajv/v/7.0.0-beta.0)
[![npm downloads](https://img.shields.io/npm/dm/ajv.svg)](https://www.npmjs.com/package/ajv)
[![Coverage Status](https://coveralls.io/repos/github/ajv-validator/ajv/badge.svg?branch=master)](https://coveralls.io/github/ajv-validator/ajv?branch=master)
[![Gitter](https://img.shields.io/gitter/room/ajv-validator/ajv.svg)](https://gitter.im/ajv-validator/ajv)
[![GitHub Sponsors](https://img.shields.io/badge/$-sponsors-brightgreen)](https://github.com/sponsors/epoberezkin)


## Ajv v7 beta is released

[Ajv version 7.0.0-beta.0](https://github.com/ajv-validator/ajv/tree/v7-beta) is released with these changes:

- to reduce the mistakes in JSON schemas and unexpected validation results, [strict mode](./docs/strict-mode.md) is added - it prohibits ignored or ambiguous JSON Schema elements.
- to make code injection from untrusted schemas impossible, [code generation](./docs/codegen.md) is fully re-written to be safe.
- to simplify Ajv extensions, the new keyword API that is used by pre-defined keywords is available to user-defined keywords - it is much easier to define any keywords now, especially with subschemas.
- schemas are compiled to ES6 code (ES5 code generation is supported with an option).
- to improve reliability and maintainability the code is migrated to TypeScript.

**Please note**:

- the support for JSON-Schema draft-04 is removed - if you have schemas using "id" attributes you have to replace them with "\$id" (or continue using version 6 that will be supported until 02/28/2021).
- all formats are separated to ajv-formats package - they have to be explicitely added if you use them.

See [release notes](https://github.com/ajv-validator/ajv/releases/tag/v7.0.0-beta.0) for the details.

To install the new version:

```bash
npm install ajv@beta
```

See [Getting started with v7](https://github.com/ajv-validator/ajv/tree/v7-beta#usage) for code example.


## Mozilla MOSS grant and OpenJS Foundation

[<img src="https://www.poberezkin.com/images/mozilla.png" width="240" height="68">](https://www.mozilla.org/en-US/moss/) &nbsp;&nbsp;&nbsp; [<img src="https://www.poberezkin.com/images/openjs.png" width="220" height="68">](https://openjsf.org/blog/2020/08/14/ajv-joins-openjs-foundation-as-an-incubation-project/)

Ajv has been awarded a grant from Mozilla’s [Open Source Support (MOSS) program](https://www.mozilla.org/en-US/moss/) in the “Foundational Technology” track! It will sponsor the development of Ajv support of [JSON Schema version 2019-09](https://tools.ietf.org/html/draft-handrews-json-schema-02) and of [JSON Type Definition](https://tools.ietf.org/html/draft-ucarion-json-type-definition-04).

Ajv also joined [OpenJS Foundation](https://openjsf.org/) – having this support will help ensure the longevity and stability of Ajv for all its users.

This [blog post](https://www.poberezkin.com/posts/2020-08-14-ajv-json-validator-mozilla-open-source-grant-openjs-foundation.html) has more details.

I am looking for the long term maintainers of Ajv – working with [ReadySet](https://www.thereadyset.co/), also sponsored by Mozilla, to establish clear guidelines for the role of a "maintainer" and the contribution standards, and to encourage a wider, more inclusive, contribution from the community.


## Please [sponsor Ajv development](https://github.com/sponsors/epoberezkin)

Since I asked to support Ajv development 40 people and 6 organizations contributed via GitHub and OpenCollective - this support helped receiving the MOSS grant!

Your continuing support is very important - the funds will be used to develop and maintain Ajv once the next major version is released.

Please sponsor Ajv via:
- [GitHub sponsors page](https://github.com/sponsors/epoberezkin) (GitHub will match it)
- [Ajv Open Collective️](https://opencollective.com/ajv)

Thank you.


#### Open Collective sponsors

<a href="https://opencollective.com/ajv"><img src="https://opencollective.com/ajv/individuals.svg?width=890"></a>

<a href="https://opencollective.com/ajv/organization/0/website"><img src="https://opencollective.com/ajv/organization/0/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/1/website"><img src="https://opencollective.com/ajv/organization/1/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/2/website"><img src="https://opencollective.com/ajv/organization/2/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/3/website"><img src="https://opencollective.com/ajv/organization/3/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/4/website"><img src="https://opencollective.com/ajv/organization/4/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/5/website"><img src="https://opencollective.com/ajv/organization/5/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/6/website"><img src="https://opencollective.com/ajv/organization/6/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/7/website"><img src="https://opencollective.com/ajv/organization/7/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/8/website"><img src="https://opencollective.com/ajv/organization/8/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/9/website"><img src="https://opencollective.com/ajv/organization/9/avatar.svg"></a>


## Using version 6

[JSON Schema draft-07](http://json-schema.org/latest/json-schema-validation.html) is published.

[Ajv version 6.0.0](https://github.com/ajv-validator/ajv/releases/tag/v6.0.0) that supports draft-07 is released. It may require either migrating your schemas or updating your code (to continue using draft-04 and v5 schemas, draft-06 schemas will be supported without changes).

__Please note__: To use Ajv with draft-06 schemas you need to explicitly add the meta-schema to the validator instance:

```javascript
ajv.addMetaSchema(require('ajv/lib/refs/json-schema-draft-06.json'));
```

To use Ajv with draft-04 schemas in addition to explicitly adding meta-schema you also need to use option schemaId:

```javascript
var ajv = new Ajv({schemaId: 'id'});
// If you want to use both draft-04 and draft-06/07 schemas:
// var ajv = new Ajv({schemaId: 'auto'});
ajv.addMetaSchema(require('ajv/lib/refs/json-schema-draft-04.json'));
```


## Contents

- [Performance](#performance)
- [Features](#features)
- [Getting started](#getting-started)
- [Frequently Asked Questions](https://github.com/ajv-validator/ajv/blob/master/FAQ.md)
- [Using in browser](#using-in-browser)
  - [Ajv and Content Security Policies (CSP)](#ajv-and-content-security-policies-csp)
- [Command line interface](#command-line-interface)
- Validation
  - [Keywords](#validation-keywords)
  - [Annotation keywords](#annotation-keywords)
  - [Formats](#formats)
  - [Combining schemas with $ref](#ref)
  - [$data reference](#data-reference)
  - NEW: [$merge and $patch keywords](#merge-and-patch-keywords)
  - [Defining custom keywords](#defining-custom-keywords)
  - [Asynchronous schema compilation](#asynchronous-schema-compilation)
  - [Asynchronous validation](#asynchronous-validation)
- [Security considerations](#security-considerations)
  - [Security contact](#security-contact)
  - [Untrusted schemas](#untrusted-schemas)
  - [Circular references in objects](#circular-references-in-javascript-objects)
  - [Trusted schemas](#security-risks-of-trusted-schemas)
  - [ReDoS attack](#redos-attack)
- Modifying data during validation
  - [Filtering data](#filtering-data)
  - [Assigning defaults](#assigning-defaults)
  - [Coercing data types](#coercing-data-types)
- API
  - [Methods](#api)
  - [Options](#options)
  - [Validation errors](#validation-errors)
- [Plugins](#plugins)
- [Related packages](#related-packages)
- [Some packages using Ajv](#some-packages-using-ajv)
- [Tests, Contributing, Changes history](#tests)
- [Support, Code of conduct, License](#open-source-software-support)


## Performance

Ajv generates code using [doT templates](https://github.com/olado/doT) to turn JSON Schemas into super-fast validation functions that are efficient for v8 optimization.

Currently Ajv is the fastest and the most standard compliant validator according to these benchmarks:

- [json-schema-benchmark](https://github.com/ebdrup/json-schema-benchmark) - 50% faster than the second place
- [jsck benchmark](https://github.com/pandastrike/jsck#benchmarks) - 20-190% faster
- [z-schema benchmark](https://rawgit.com/zaggino/z-schema/master/benchmark/results.html)
- [themis benchmark](https://cdn.rawgit.com/playlyfe/themis/master/benchmark/results.html)


Performance of different validators by [json-schema-benchmark](https://github.com/ebdrup/json-schema-benchmark):

[![performance](https://chart.googleapis.com/chart?chxt=x,y&cht=bhs&chco=76A4FB&chls=2.0&chbh=32,4,1&chs=600x416&chxl=-1:|djv|ajv|json-schema-validator-generator|jsen|is-my-json-valid|themis|z-schema|jsck|skeemas|json-schema-library|tv4&chd=t:100,98,72.1,66.8,50.1,15.1,6.1,3.8,1.2,0.7,0.2)](https://github.com/ebdrup/json-schema-benchmark/blob/master/README.md#performance)


## Features

- Ajv implements full JSON Schema [draft-06/07](http://json-schema.org/) and draft-04 standards:
  - all validation keywords (see [JSON Schema validation keywords](https://github.com/ajv-validator/ajv/blob/master/KEYWORDS.md))
  - full support of remote refs (remote schemas have to be added with `addSchema` or compiled to be available)
  - support of circular references between schemas
  - correct string lengths for strings with unicode pairs (can be turned off)
  - [formats](#formats) defined by JSON Schema draft-07 standard and custom formats (can be turned off)
  - [validates schemas against meta-schema](#api-validateschema)
- supports [browsers](#using-in-browser) and Node.js 0.10-14.x
- [asynchronous loading](#asynchronous-schema-compilation) of referenced schemas during compilation
- "All errors" validation mode with [option allErrors](#options)
- [error messages with parameters](#validation-errors) describing error reasons to allow creating custom error messages
- i18n error messages support with [ajv-i18n](https://github.com/ajv-validator/ajv-i18n) package
- [filtering data](#filtering-data) from additional properties
- [assigning defaults](#assigning-defaults) to missing properties and items
- [coercing data](#coercing-data-types) to the types specified in `type` keywords
- [custom keywords](#defining-custom-keywords)
- draft-06/07 keywords `const`, `contains`, `propertyNames` and `if/then/else`
- draft-06 boolean schemas (`true`/`false` as a schema to always pass/fail).
- keywords `switch`, `patternRequired`, `formatMaximum` / `formatMinimum` and `formatExclusiveMaximum` / `formatExclusiveMinimum` from [JSON Schema extension proposals](https://github.com/json-schema/json-schema/wiki/v5-Proposals) with [ajv-keywords](https://github.com/ajv-validator/ajv-keywords) package
- [$data reference](#data-reference) to use values from the validated data as values for the schema keywords
- [asynchronous validation](#asynchronous-validation) of custom formats and keywords


## Install

```
npm install ajv
```


## <a name="usage"></a>Getting started

Try it in the Node.js REPL: https://tonicdev.com/npm/ajv


The fastest validation call:

```javascript
// Node.js require:
var Ajv = require('ajv');
// or ESM/TypeScript import
import Ajv from 'ajv';

var ajv = new Ajv(); // options can be passed, e.g. {allErrors: true}
var validate = ajv.compile(schema);
var valid = validate(data);
if (!valid) console.log(validate.errors);
```

or with less code

```javascript
// ...
var valid = ajv.validate(schema, data);
if (!valid) console.log(ajv.errors);
// ...
```

or

```javascript
// ...
var valid = ajv.addSchema(schema, 'mySchema')
               .validate('mySchema', data);
if (!valid) console.log(ajv.errorsText());
// ...
```

See [API](#api) and [Options](#options) for more details.

Ajv compiles schemas to functions and caches them in all cases (using schema serialized with [fast-json-stable-stringify](https://github.com/epoberezkin/fast-json-stable-stringify) or a custom function as a key), so that the next time the same schema is used (not necessarily the same object instance) it won't be compiled again.

The best performance is achieved when using compiled functions returned by `compile` or `getSchema` methods (there is no additional function call).

__Please note__: every time a validation function or `ajv.validate` are called `errors` property is overwritten. You need to copy `errors` array reference to another variable if you want to use it later (e.g., in the callback). See [Validation errors](#validation-errors)

__Note for TypeScript users__: `ajv` provides its own TypeScript declarations
out of the box, so you don't need to install the deprecated `@types/ajv`
module.


## Using in browser

You can require Ajv directly from the code you browserify - in this case Ajv will be a part of your bundle.

If you need to use Ajv in several bundles you can create a separate UMD bundle using `npm run bundle` script (thanks to [siddo420](https://github.com/siddo420)).

Then you need to load Ajv in the browser:
```html
<script src="ajv.min.js"></script>
```

This bundle can be used with different module systems; it creates global `Ajv` if no module system is found.

The browser bundle is available on [cdnjs](https://cdnjs.com/libraries/ajv).

Ajv is tested with these browsers:

[![Sauce Test Status](https://saucelabs.com/browser-matrix/epoberezkin.svg)](https://saucelabs.com/u/epoberezkin)

__Please note__: some frameworks, e.g. Dojo, may redefine global require in such way that is not compatible with CommonJS module format. In such case Ajv bundle has to be loaded before the framework and then you can use global Ajv (see issue [#234](https://github.com/ajv-validator/ajv/issues/234)).


### Ajv and Content Security Policies (CSP)

If you're using Ajv to compile a schema (the typical use) in a browser document that is loaded with a Content Security Policy (CSP), that policy will require a `script-src` directive that includes the value `'unsafe-eval'`.
:warning: NOTE, however, that `unsafe-eval` is NOT recommended in a secure CSP[[1]](https://developer.chrome.com/extensions/contentSecurityPolicy#relaxing-eval), as it has the potential to open the document to cross-site scripting (XSS) attacks.

In order to make use of Ajv without easing your CSP, you can [pre-compile a schema using the CLI](https://github.com/ajv-validator/ajv-cli#compile-schemas). This will transpile the schema JSON into a JavaScript file that exports a `validate` function that works simlarly to a schema compiled at runtime.

Note that pre-compilation of schemas is performed using [ajv-pack](https://github.com/ajv-validator/ajv-pack) and there are [some limitations to the schema features it can compile](https://github.com/ajv-validator/ajv-pack#limitations). A successfully pre-compiled schema is equivalent to the same schema compiled at runtime.


## Command line interface

CLI is available as a separate npm package [ajv-cli](https://github.com/ajv-validator/ajv-cli). It supports:

- compiling JSON Schemas to test their validity
- BETA: generating standalone module exporting a validation function to be used without Ajv (using [ajv-pack](https://github.com/ajv-validator/ajv-pack))
- migrate schemas to draft-07 (using [json-schema-migrate](https://github.com/epoberezkin/json-schema-migrate))
- validating data file(s) against JSON Schema
- testing expected validity of data against JSON Schema
- referenced schemas
- custom meta-schemas
- files in JSON, JSON5, YAML, and JavaScript format
- all Ajv options
- reporting changes in data after validation in [JSON-patch](https://tools.ietf.org/html/rfc6902) format


## Validation keywords

Ajv supports all validation keywords from draft-07 of JSON Schema standard:

- [type](https://github.com/ajv-validator/ajv/blob/master/KEYWORDS.md#type)
- [for numbers](https://github.com/ajv-validator/ajv/blob/master/KEYWORDS.md#keywords-for-numbers) - maximum, minimum, exclusiveMaximum, exclusiveMinimum, multipleOf
- [for strings](https://github.com/ajv-validator/ajv/blob/master/KEYWORDS.md#keywords-for-strings) - maxLength, minLength, pattern, format
- [for arrays](https://github.com/ajv-validator/ajv/blob/master/KEYWORDS.md#keywords-for-arrays) - maxItems, minItems, uniqueItems, items, additionalItems, [contains](https://github.com/ajv-validator/ajv/blob/master/KEYWORDS.md#contains)
- [for objects](https://github.com/ajv-validator/ajv/blob/master/KEYWORDS.md#keywords-for-objects) - maxProperties, minProperties, required, properties, patternProperties, additionalProperties, dependencies, [propertyNames](https://github.com/ajv-validator/ajv/blob/master/KEYWORDS.md#propertynames)
- [for all types](https://github.com/ajv-validator/ajv/blob/master/KEYWORDS.md#keywords-for-all-types) - enum, [const](https://github.com/ajv-validator/ajv/blob/master/KEYWORDS.md#const)
- [compound keywords](https://github.com/ajv-validator/ajv/blob/master/KEYWORDS.md#compound-keywords) - not, oneOf, anyOf, allOf, [if/then/else](https://github.com/ajv-validator/ajv/blob/master/KEYWORDS.md#ifthenelse)

With [ajv-keywords](https://github.com/ajv-validator/ajv-keywords) package Ajv also supports validation keywords from [JSON Schema extension proposals](https://github.com/json-schema/json-schema/wiki/v5-Proposals) for JSON Schema standard:

- [patternRequired](https://github.com/ajv-validator/ajv/blob/master/KEYWORDS.md#patternrequired-proposed) - like `required` but with patterns that some property should match.
- [formatMaximum, formatMinimum, formatExclusiveMaximum, formatExclusiveMinimum](https://github.com/ajv-validator/ajv/blob/master/KEYWORDS.md#formatmaximum--formatminimum-and-exclusiveformatmaximum--exclusiveformatminimum-proposed) - setting limits for date, time, etc.

See [JSON Schema validation keywords](https://github.com/ajv-validator/ajv/blob/master/KEYWORDS.md) for more details.


## Annotation keywords

JSON Schema specification defines several annotation keywords that describe schema itself but do not perform any validation.

- `title` and `description`: information about the data represented by that schema
- `$comment` (NEW in draft-07): information for developers. With option `$comment` Ajv logs or passes the comment string to the user-supplied function. See [Options](#options).
- `default`: a default value of the data instance, see [Assigning defaults](#assigning-defaults).
- `examples` (NEW in draft-06): an array of data instances. Ajv does not check the validity of these instances against the schema.
- `readOnly` and `writeOnly` (NEW in draft-07): marks data-instance as read-only or write-only in relation to the source of the data (database, api, etc.).
- `contentEncoding`: [RFC 2045](https://tools.ietf.org/html/rfc2045#section-6.1 ), e.g., "base64".
- `contentMediaType`: [RFC 2046](https://tools.ietf.org/html/rfc2046), e.g., "image/png".

__Please note__:  Ajv does not implement validation of the keywords `examples`, `contentEncoding` and `contentMediaType` but it reserves them. If you want to create a plugin that implements some of them, it should remove these keywords from the instance.


## Formats

Ajv implements formats defined by JSON Schema specification and several other formats. It is recommended NOT to use "format" keyword implementations with untrusted data, as they use potentially unsafe regular expressions - see [ReDoS attack](#redos-attack).

__Please note__: if you need to use "format" keyword to validate untrusted data, you MUST assess their suitability and safety for your validation scenarios.

The following formats are implemented for string validation with "format" keyword:

- _date_: full-date according to [RFC3339](http://tools.ietf.org/html/rfc3339#section-5.6).
- _time_: time with optional time-zone.
- _date-time_: date-time from the same source (time-zone is mandatory). `date`, `time` and `date-time` validate ranges in `full` mode and only regexp in `fast` mode (see [options](#options)).
- _uri_: full URI.
- _uri-reference_: URI reference, including full and relative URIs.
- _uri-template_: URI template according to [RFC6570](https://tools.ietf.org/html/rfc6570)
- _url_ (deprecated): [URL record](https://url.spec.whatwg.org/#concept-url).
- _email_: email address.
- _hostname_: host name according to [RFC1034](http://tools.ietf.org/html/rfc1034#section-3.5).
- _ipv4_: IP address v4.
- _ipv6_: IP address v6.
- _regex_: tests whether a string is a valid regular expression by passing it to RegExp constructor.
- _uuid_: Universally Unique IDentifier according to [RFC4122](http://tools.ietf.org/html/rfc4122).
- _json-pointer_: JSON-pointer according to [RFC6901](https://tools.ietf.org/html/rfc6901).
- _relative-json-pointer_: relative JSON-pointer according to [this draft](http://tools.ietf.org/html/draft-luff-relative-json-pointer-00).

__Please note__: JSON Schema draft-07 also defines formats `iri`, `iri-reference`, `idn-hostname` and `idn-email` for URLs, hostnames and emails with international characters. Ajv does not implement these formats. If you create Ajv plugin that implements them please make a PR to mention this plugin here.

There are two modes of format validation: `fast` and `full`. This mode affects formats `date`, `time`, `date-time`, `uri`, `uri-reference`, and `email`. See [Options](#options) for details.

You can add additional formats and replace any of the formats above using [addFormat](#api-addformat) method.

The option `unknownFormats` allows changing the default behaviour when an unknown format is encountered. In this case Ajv can either fail schema compilation (default) or ignore it (default in versions before 5.0.0). You also can allow specific format(s) that will be ignored. See [Options](#options) for details.

You can find regular expressions used for format validation and the sources that were used in [formats.js](https://github.com/ajv-validator/ajv/blob/master/lib/compile/formats.js).


## <a name="ref"></a>Combining schemas with $ref

You can structure your validation logic across multiple schema files and have schemas reference each other using `$ref` keyword.

Example:

```javascript
var schema = {
  "$id": "http://example.com/schemas/schema.json",
  "type": "object",
  "properties": {
    "foo": { "$ref": "defs.json#/definitions/int" },
    "bar": { "$ref": "defs.json#/definitions/str" }
  }
};

var defsSchema = {
  "$id": "http://example.com/schemas/defs.json",
  "definitions": {
    "int": { "type": "integer" },
    "str": { "type": "string" }
  }
};
```

Now to compile your schema you can either pass all schemas to Ajv instance:

```javascript
var ajv = new Ajv({schemas: [schema, defsSchema]});
var validate = ajv.getSchema('http://example.com/schemas/schema.json');
```

or use `addSchema` method:

```javascript
var ajv = new Ajv;
var validate = ajv.addSchema(defsSchema)
                  .compile(schema);
```

See [Options](#options) and [addSchema](#api) method.

__Please note__:
- `$ref` is resolved as the uri-reference using schema $id as the base URI (see the example).
- References can be recursive (and mutually recursive) to implement the schemas for different data structures (such as linked lists, trees, graphs, etc.).
- You don't have to host your schema files at the URIs that you use as schema $id. These URIs are only used to identify the schemas, and according to JSON Schema specification validators should not expect to be able to download the schemas from these URIs.
- The actual location of the schema file in the file system is not used.
- You can pass the identifier of the schema as the second parameter of `addSchema` method or as a property name in `schemas` option. This identifier can be used instead of (or in addition to) schema $id.
- You cannot have the same $id (or the schema identifier) used for more than one schema - the exception will be thrown.
- You can implement dynamic resolution of the referenced schemas using `compileAsync` method. In this way you can store schemas in any system (files, web, database, etc.) and reference them without explicitly adding to Ajv instance. See [Asynchronous schema compilation](#asynchronous-schema-compilation).


## $data reference

With `$data` option you can use values from the validated data as the values for the schema keywords. See [proposal](https://github.com/json-schema-org/json-schema-spec/issues/51) for more information about how it works.

`$data` reference is supported in the keywords: const, enum, format, maximum/minimum, exclusiveMaximum / exclusiveMinimum, maxLength / minLength, maxItems / minItems, maxProperties / minProperties, formatMaximum / formatMinimum, formatExclusiveMaximum / formatExclusiveMinimum, multipleOf, pattern, required, uniqueItems.

The value of "$data" should be a [JSON-pointer](https://tools.ietf.org/html/rfc6901) to the data (the root is always the top level data object, even if the $data reference is inside a referenced subschema) or a [relative JSON-pointer](http://tools.ietf.org/html/draft-luff-relative-json-pointer-00) (it is relative to the current point in data; if the $data reference is inside a referenced subschema it cannot point to the data outside of the root level for this subschema).

Examples.

This schema requires that the value in property `smaller` is less or equal than the value in the property larger:

```javascript
var ajv = new Ajv({$data: true});

var schema = {
  "properties": {
    "smaller": {
      "type": "number",
      "maximum": { "$data": "1/larger" }
    },
    "larger": { "type": "number" }
  }
};

var validData = {
  smaller: 5,
  larger: 7
};

ajv.validate(schema, validData); // true
```

This schema requires that the properties have the same format as their field names:

```javascript
var schema = {
  "additionalProperties": {
    "type": "string",
    "format": { "$data": "0#" }
  }
};

var validData = {
  'date-time': '1963-06-19T08:30:06.283185Z',
  email: 'joe.bloggs@example.com'
}
```

`$data` reference is resolved safely - it won't throw even if some property is undefined. If `$data` resolves to `undefined` the validation succeeds (with the exclusion of `const` keyword). If `$data` resolves to incorrect type (e.g. not "number" for maximum keyword) the validation fails.


## $merge and $patch keywords

With the package [ajv-merge-patch](https://github.com/ajv-validator/ajv-merge-patch) you can use the keywords `$merge` and `$patch` that allow extending JSON Schemas with patches using formats [JSON Merge Patch (RFC 7396)](https://tools.ietf.org/html/rfc7396) and [JSON Patch (RFC 6902)](https://tools.ietf.org/html/rfc6902).

To add keywords `$merge` and `$patch` to Ajv instance use this code:

```javascript
require('ajv-merge-patch')(ajv);
```

Examples.

Using `$merge`:

```json
{
  "$merge": {
    "source": {
      "type": "object",
      "properties": { "p": { "type": "string" } },
      "additionalProperties": false
    },
    "with": {
      "properties": { "q": { "type": "number" } }
    }
  }
}
```

Using `$patch`:

```json
{
  "$patch": {
    "source": {
      "type": "object",
      "properties": { "p": { "type": "string" } },
      "additionalProperties": false
    },
    "with": [
      { "op": "add", "path": "/properties/q", "value": { "type": "number" } }
    ]
  }
}
```

The schemas above are equivalent to this schema:

```json
{
  "type": "object",
  "properties": {
    "p": { "type": "string" },
    "q": { "type": "number" }
  },
  "additionalProperties": false
}
```

The properties `source` and `with` in the keywords `$merge` and `$patch` can use absolute or relative `$ref` to point to other schemas previously added to the Ajv instance or to the fragments of the current schema.

See the package [ajv-merge-patch](https://github.com/ajv-validator/ajv-merge-patch) for more information.


## Defining custom keywords

The advantages of using custom keywords are:

- allow creating validation scenarios that cannot be expressed using JSON Schema
- simplify your schemas
- help bringing a bigger part of the validation logic to your schemas
- make your schemas more expressive, less verbose and closer to your application domain
- implement custom data processors that modify your data (`modifying` option MUST be used in keyword definition) and/or create side effects while the data is being validated

If a keyword is used only for side-effects and its validation result is pre-defined, use option `valid: true/false` in keyword definition to simplify both generated code (no error handling in case of `valid: true`) and your keyword functions (no need to return any validation result).

The concerns you have to be aware of when extending JSON Schema standard with custom keywords are the portability and understanding of your schemas. You will have to support these custom keywords on other platforms and to properly document these keywords so that everybody can understand them in your schemas.

You can define custom keywords with [addKeyword](#api-addkeyword) method. Keywords are defined on the `ajv` instance level - new instances will not have previously defined keywords.

Ajv allows defining keywords with:
- validation function
- compilation function
- macro function
- inline compilation function that should return code (as string) that will be inlined in the currently compiled schema.

Example. `range` and `exclusiveRange` keywords using compiled schema:

```javascript
ajv.addKeyword('range', {
  type: 'number',
  compile: function (sch, parentSchema) {
    var min = sch[0];
    var max = sch[1];

    return parentSchema.exclusiveRange === true
            ? function (data) { return data > min && data < max; }
            : function (data) { return data >= min && data <= max; }
  }
});

var schema = { "range": [2, 4], "exclusiveRange": true };
var validate = ajv.compile(schema);
console.log(validate(2.01)); // true
console.log(validate(3.99)); // true
console.log(validate(2)); // false
console.log(validate(4)); // false
```

Several custom keywords (typeof, instanceof, range and propertyNames) are defined in [ajv-keywords](https://github.com/ajv-validator/ajv-keywords) package - they can be used for your schemas and as a starting point for your own custom keywords.

See [Defining custom keywords](https://github.com/ajv-validator/ajv/blob/master/CUSTOM.md) for more details.


## Asynchronous schema compilation

During asynchronous compilation remote references are loaded using supplied function. See `compileAsync` [method](#api-compileAsync) and `loadSchema` [option](#options).

Example:

```javascript
var ajv = new Ajv({ loadSchema: loadSchema });

ajv.compileAsync(schema).then(function (validate) {
  var valid = validate(data);
  // ...
});

function loadSchema(uri) {
  return request.json(uri).then(function (res) {
    if (res.statusCode >= 400)
      throw new Error('Loading error: ' + res.statusCode);
    return res.body;
  });
}
```

__Please note__: [Option](#options) `missingRefs` should NOT be set to `"ignore"` or `"fail"` for asynchronous compilation to work.


## Asynchronous validation

Example in Node.js REPL: https://tonicdev.com/esp/ajv-asynchronous-validation

You can define custom formats and keywords that perform validation asynchronously by accessing database or some other service. You should add `async: true` in the keyword or format definition (see [addFormat](#api-addformat), [addKeyword](#api-addkeyword) and [Defining custom keywords](#defining-custom-keywords)).

If your schema uses asynchronous formats/keywords or refers to some schema that contains them it should have `"$async": true` keyword so that Ajv can compile it correctly. If asynchronous format/keyword or reference to asynchronous schema is used in the schema without `$async` keyword Ajv will throw an exception during schema compilation.

__Please note__: all asynchronous subschemas that are referenced from the current or other schemas should have `"$async": true` keyword as well, otherwise the schema compilation will fail.

Validation function for an asynchronous custom format/keyword should return a promise that resolves with `true` or `false` (or rejects with `new Ajv.ValidationError(errors)` if you want to return custom errors from the keyword function).

Ajv compiles asynchronous schemas to [es7 async functions](http://tc39.github.io/ecmascript-asyncawait/) that can optionally be transpiled with [nodent](https://github.com/MatAtBread/nodent). Async functions are supported in Node.js 7+ and all modern browsers. You can also supply any other transpiler as a function via `processCode` option. See [Options](#options).

The compiled validation function has `$async: true` property (if the schema is asynchronous), so you can differentiate these functions if you are using both synchronous and asynchronous schemas.

Validation result will be a promise that resolves with validated data or rejects with an exception `Ajv.ValidationError` that contains the array of validation errors in `errors` property.


Example:

```javascript
var ajv = new Ajv;
// require('ajv-async')(ajv);

ajv.addKeyword('idExists', {
  async: true,
  type: 'number',
  validate: checkIdExists
});


function checkIdExists(schema, data) {
  return knex(schema.table)
  .select('id')
  .where('id', data)
  .then(function (rows) {
    return !!rows.length; // true if record is found
  });
}

var schema = {
  "$async": true,
  "properties": {
    "userId": {
      "type": "integer",
      "idExists": { "table": "users" }
    },
    "postId": {
      "type": "integer",
      "idExists": { "table": "posts" }
    }
  }
};

var validate = ajv.compile(schema);

validate({ userId: 1, postId: 19 })
.then(function (data) {
  console.log('Data is valid', data); // { userId: 1, postId: 19 }
})
.catch(function (err) {
  if (!(err instanceof Ajv.ValidationError)) throw err;
  // data is invalid
  console.log('Validation errors:', err.errors);
});
```

### Using transpilers with asynchronous validation functions.

[ajv-async](https://github.com/ajv-validator/ajv-async) uses [nodent](https://github.com/MatAtBread/nodent) to transpile async functions. To use another transpiler you should separately install it (or load its bundle in the browser).


#### Using nodent

```javascript
var ajv = new Ajv;
require('ajv-async')(ajv);
// in the browser if you want to load ajv-async bundle separately you can:
// window.ajvAsync(ajv);
var validate = ajv.compile(schema); // transpiled es7 async function
validate(data).then(successFunc).catch(errorFunc);
```


#### Using other transpilers

```javascript
var ajv = new Ajv({ processCode: transpileFunc });
var validate = ajv.compile(schema); // transpiled es7 async function
validate(data).then(successFunc).catch(errorFunc);
```

See [Options](#options).


## Security considerations

JSON Schema, if properly used, can replace data sanitisation. It doesn't replace other API security considerations. It also introduces additional security aspects to consider.


##### Security contact

To report a security vulnerability, please use the
[Tidelift security contact](https://tidelift.com/security).
Tidelift will coordinate the fix and disclosure. Please do NOT report security vulnerabilities via GitHub issues.


##### Untrusted schemas

Ajv treats JSON schemas as trusted as your application code. This security model is based on the most common use case, when the schemas are static and bundled together with the application.

If your schemas are received from untrusted sources (or generated from untrusted data) there are several scenarios you need to prevent:
- compiling schemas can cause stack overflow (if they are too deep)
- compiling schemas can be slow (e.g. [#557](https://github.com/ajv-validator/ajv/issues/557))
- validating certain data can be slow

It is difficult to predict all the scenarios, but at the very least it may help to limit the size of untrusted schemas (e.g. limit JSON string length) and also the maximum schema object depth (that can be high for relatively small JSON strings). You also may want to mitigate slow regular expressions in `pattern` and `patternProperties` keywords.

Regardless the measures you take, using untrusted schemas increases security risks.


##### Circular references in JavaScript objects

Ajv does not support schemas and validated data that have circular references in objects. See [issue #802](https://github.com/ajv-validator/ajv/issues/802).

An attempt to compile such schemas or validate such data would cause stack overflow (or will not complete in case of asynchronous validation). Depending on the parser you use, untrusted data can lead to circular references.


##### Security risks of trusted schemas

Some keywords in JSON Schemas can lead to very slow validation for certain data. These keywords include (but may be not limited to):

- `pattern` and `format` for large strings - in some cases using `maxLength` can help mitigate it, but certain regular expressions can lead to exponential validation time even with relatively short strings (see [ReDoS attack](#redos-attack)).
- `patternProperties` for large property names - use `propertyNames` to mitigate, but some regular expressions can have exponential evaluation time as well.
- `uniqueItems` for large non-scalar arrays - use `maxItems` to mitigate

__Please note__: The suggestions above to prevent slow validation would only work if you do NOT use `allErrors: true` in production code (using it would continue validation after validation errors).

You can validate your JSON schemas against [this meta-schema](https://github.com/ajv-validator/ajv/blob/master/lib/refs/json-schema-secure.json) to check that these recommendations are followed:

```javascript
const isSchemaSecure = ajv.compile(require('ajv/lib/refs/json-schema-secure.json'));

const schema1 = {format: 'email'};
isSchemaSecure(schema1); // false

const schema2 = {format: 'email', maxLength: MAX_LENGTH};
isSchemaSecure(schema2); // true
```

__Please note__: following all these recommendation is not a guarantee that validation of untrusted data is safe - it can still lead to some undesirable results.


##### Content Security Policies (CSP)
See [Ajv and Content Security Policies (CSP)](#ajv-and-content-security-policies-csp)


## ReDoS attack

Certain regular expressions can lead to the exponential evaluation time even with relatively short strings.

Please assess the regular expressions you use in the schemas on their vulnerability to this attack - see [safe-regex](https://github.com/substack/safe-regex), for example.

__Please note__: some formats that Ajv implements use [regular expressions](https://github.com/ajv-validator/ajv/blob/master/lib/compile/formats.js) that can be vulnerable to ReDoS attack, so if you use Ajv to validate data from untrusted sources __it is strongly recommended__ to consider the following:

- making assessment of "format" implementations in Ajv.
- using `format: 'fast'` option that simplifies some of the regular expressions (although it does not guarantee that they are safe).
- replacing format implementations provided by Ajv with your own implementations of "format" keyword that either uses different regular expressions or another approach to format validation. Please see [addFormat](#api-addformat) method.
- disabling format validation by ignoring "format" keyword with option `format: false`

Whatever mitigation you choose, please assume all formats provided by Ajv as potentially unsafe and make your own assessment of their suitability for your validation scenarios.


## Filtering data

With [option `removeAdditional`](#options) (added by [andyscott](https://github.com/andyscott)) you can filter data during the validation.

This option modifies original data.

Example:

```javascript
var ajv = new Ajv({ removeAdditional: true });
var schema = {
  "additionalProperties": false,
  "properties": {
    "foo": { "type": "number" },
    "bar": {
      "additionalProperties": { "type": "number" },
      "properties": {
        "baz": { "type": "string" }
      }
    }
  }
}

var data = {
  "foo": 0,
  "additional1": 1, // will be removed; `additionalProperties` == false
  "bar": {
    "baz": "abc",
    "additional2": 2 // will NOT be removed; `additionalProperties` != false
  },
}

var validate = ajv.compile(schema);

console.log(validate(data)); // true
console.log(data); // { "foo": 0, "bar": { "baz": "abc", "additional2": 2 }
```

If `removeAdditional` option in the example above were `"all"` then both `additional1` and `additional2` properties would have been removed.

If the option were `"failing"` then property `additional1` would have been removed regardless of its value and property `additional2` would have been removed only if its value were failing the schema in the inner `additionalProperties` (so in the example above it would have stayed because it passes the schema, but any non-number would have been removed).

__Please note__: If you use `removeAdditional` option with `additionalProperties` keyword inside `anyOf`/`oneOf` keywords your validation can fail with this schema, for example:

```json
{
  "type": "object",
  "oneOf": [
    {
      "properties": {
        "foo": { "type": "string" }
      },
      "required": [ "foo" ],
      "additionalProperties": false
    },
    {
      "properties": {
        "bar": { "type": "integer" }
      },
      "required": [ "bar" ],
      "additionalProperties": false
    }
  ]
}
```

The intention of the schema above is to allow objects with either the string property "foo" or the integer property "bar", but not with both and not with any other properties.

With the option `removeAdditional: true` the validation will pass for the object `{ "foo": "abc"}` but will fail for the object `{"bar": 1}`. It happens because while the first subschema in `oneOf` is validated, the property `bar` is removed because it is an additional property according to the standard (because it is not included in `properties` keyword in the same schema).

While this behaviour is unexpected (issues [#129](https://github.com/ajv-validator/ajv/issues/129), [#134](https://github.com/ajv-validator/ajv/issues/134)), it is correct. To have the expected behaviour (both objects are allowed and additional properties are removed) the schema has to be refactored in this way:

```json
{
  "type": "object",
  "properties": {
    "foo": { "type": "string" },
    "bar": { "type": "integer" }
  },
  "additionalProperties": false,
  "oneOf": [
    { "required": [ "foo" ] },
    { "required": [ "bar" ] }
  ]
}
```

The schema above is also more efficient - it will compile into a faster function.


## Assigning defaults

With [option `useDefaults`](#options) Ajv will assign values from `default` keyword in the schemas of `properties` and `items` (when it is the array of schemas) to the missing properties and items.

With the option value `"empty"` properties and items equal to `null` or `""` (empty string) will be considered missing and assigned defaults.

This option modifies original data.

__Please note__: the default value is inserted in the generated validation code as a literal, so the value inserted in the data will be the deep clone of the default in the schema.


Example 1 (`default` in `properties`):

```javascript
var ajv = new Ajv({ useDefaults: true });
var schema = {
  "type": "object",
  "properties": {
    "foo": { "type": "number" },
    "bar": { "type": "string", "default": "baz" }
  },
  "required": [ "foo", "bar" ]
};

var data = { "foo": 1 };

var validate = ajv.compile(schema);

console.log(validate(data)); // true
console.log(data); // { "foo": 1, "bar": "baz" }
```

Example 2 (`default` in `items`):

```javascript
var schema = {
  "type": "array",
  "items": [
    { "type": "number" },
    { "type": "string", "default": "foo" }
  ]
}

var data = [ 1 ];

var validate = ajv.compile(schema);

console.log(validate(data)); // true
console.log(data); // [ 1, "foo" ]
```

`default` keywords in other cases are ignored:

- not in `properties` or `items` subschemas
- in schemas inside `anyOf`, `oneOf` and `not` (see [#42](https://github.com/ajv-validator/ajv/issues/42))
- in `if` subschema of `switch` keyword
- in schemas generated by custom macro keywords

The [`strictDefaults` option](#options) customizes Ajv's behavior for the defaults that Ajv ignores (`true` raises an error, and `"log"` outputs a warning).


## Coercing data types

When you are validating user inputs all your data properties are usually strings. The option `coerceTypes` allows you to have your data types coerced to the types specified in your schema `type` keywords, both to pass the validation and to use the correctly typed data afterwards.

This option modifies original data.

__Please note__: if you pass a scalar value to the validating function its type will be coerced and it will pass the validation, but the value of the variable you pass won't be updated because scalars are passed by value.


Example 1:

```javascript
var ajv = new Ajv({ coerceTypes: true });
var schema = {
  "type": "object",
  "properties": {
    "foo": { "type": "number" },
    "bar": { "type": "boolean" }
  },
  "required": [ "foo", "bar" ]
};

var data = { "foo": "1", "bar": "false" };

var validate = ajv.compile(schema);

console.log(validate(data)); // true
console.log(data); // { "foo": 1, "bar": false }
```

Example 2 (array coercions):

```javascript
var ajv = new Ajv({ coerceTypes: 'array' });
var schema = {
  "properties": {
    "foo": { "type": "array", "items": { "type": "number" } },
    "bar": { "type": "boolean" }
  }
};

var data = { "foo": "1", "bar": ["false"] };

var validate = ajv.compile(schema);

console.log(validate(data)); // true
console.log(data); // { "foo": [1], "bar": false }
```

The coercion rules, as you can see from the example, are different from JavaScript both to validate user input as expected and to have the coercion reversible (to correctly validate cases where different types are defined in subschemas of "anyOf" and other compound keywords).

See [Coercion rules](https://github.com/ajv-validator/ajv/blob/master/COERCION.md) for details.


## API

##### new Ajv(Object options) -&gt; Object

Create Ajv instance.


##### .compile(Object schema) -&gt; Function&lt;Object data&gt;

Generate validating function and cache the compiled schema for future use.

Validating function returns a boolean value. This function has properties `errors` and `schema`. Errors encountered during the last validation are assigned to `errors` property (it is assigned `null` if there was no errors). `schema` property contains the reference to the original schema.

The schema passed to this method will be validated against meta-schema unless `validateSchema` option is false. If schema is invalid, an error will be thrown. See [options](#options).


##### <a name="api-compileAsync"></a>.compileAsync(Object schema [, Boolean meta] [, Function callback]) -&gt; Promise

Asynchronous version of `compile` method that loads missing remote schemas using asynchronous function in `options.loadSchema`. This function returns a Promise that resolves to a validation function. An optional callback passed to `compileAsync` will be called with 2 parameters: error (or null) and validating function. The returned promise will reject (and the callback will be called with an error) when:

- missing schema can't be loaded (`loadSchema` returns a Promise that rejects).
- a schema containing a missing reference is loaded, but the reference cannot be resolved.
- schema (or some loaded/referenced schema) is invalid.

The function compiles schema and loads the first missing schema (or meta-schema) until all missing schemas are loaded.

You can asynchronously compile meta-schema by passing `true` as the second parameter.

See example in [Asynchronous compilation](#asynchronous-schema-compilation).


##### .validate(Object schema|String key|String ref, data) -&gt; Boolean

Validate data using passed schema (it will be compiled and cached).

Instead of the schema you can use the key that was previously passed to `addSchema`, the schema id if it was present in the schema or any previously resolved reference.

Validation errors will be available in the `errors` property of Ajv instance (`null` if there were no errors).

__Please note__: every time this method is called the errors are overwritten so you need to copy them to another variable if you want to use them later.

If the schema is asynchronous (has `$async` keyword on the top level) this method returns a Promise. See [Asynchronous validation](#asynchronous-validation).


##### .addSchema(Array&lt;Object&gt;|Object schema [, String key]) -&gt; Ajv

Add schema(s) to validator instance. This method does not compile schemas (but it still validates them). Because of that dependencies can be added in any order and circular dependencies are supported. It also prevents unnecessary compilation of schemas that are containers for other schemas but not used as a whole.

Array of schemas can be passed (schemas should have ids), the second parameter will be ignored.

Key can be passed that can be used to reference the schema and will be used as the schema id if there is no id inside the schema. If the key is not passed, the schema id will be used as the key.


Once the schema is added, it (and all the references inside it) can be referenced in other schemas and used to validate data.

Although `addSchema` does not compile schemas, explicit compilation is not required - the schema will be compiled when it is used first time.

By default the schema is validated against meta-schema before it is added, and if the schema does not pass validation the exception is thrown. This behaviour is controlled by `validateSchema` option.

__Please note__: Ajv uses the [method chaining syntax](https://en.wikipedia.org/wiki/Method_chaining) for all methods with the prefix `add*` and `remove*`.
This allows you to do nice things like the following.

```javascript
var validate = new Ajv().addSchema(schema).addFormat(name, regex).getSchema(uri);
```

##### .addMetaSchema(Array&lt;Object&gt;|Object schema [, String key]) -&gt; Ajv

Adds meta schema(s) that can be used to validate other schemas. That function should be used instead of `addSchema` because there may be instance options that would compile a meta schema incorrectly (at the moment it is `removeAdditional` option).

There is no need to explicitly add draft-07 meta schema (http://json-schema.org/draft-07/schema) - it is added by default, unless option `meta` is set to `false`. You only need to use it if you have a changed meta-schema that you want to use to validate your schemas. See `validateSchema`.


##### <a name="api-validateschema"></a>.validateSchema(Object schema) -&gt; Boolean

Validates schema. This method should be used to validate schemas rather than `validate` due to the inconsistency of `uri` format in JSON Schema standard.

By default this method is called automatically when the schema is added, so you rarely need to use it directly.

If schema doesn't have `$schema` property, it is validated against draft 6 meta-schema (option `meta` should not be false).

If schema has `$schema` property, then the schema with this id (that should be previously added) is used to validate passed schema.

Errors will be available at `ajv.errors`.


##### .getSchema(String key) -&gt; Function&lt;Object data&gt;

Retrieve compiled schema previously added with `addSchema` by the key passed to `addSchema` or by its full reference (id). The returned validating function has `schema` property with the reference to the original schema.


##### .removeSchema([Object schema|String key|String ref|RegExp pattern]) -&gt; Ajv

Remove added/cached schema. Even if schema is referenced by other schemas it can be safely removed as dependent schemas have local references.

Schema can be removed using:
- key passed to `addSchema`
- it's full reference (id)
- RegExp that should match schema id or key (meta-schemas won't be removed)
- actual schema object that will be stable-stringified to remove schema from cache

If no parameter is passed all schemas but meta-schemas will be removed and the cache will be cleared.


##### <a name="api-addformat"></a>.addFormat(String name, String|RegExp|Function|Object format) -&gt; Ajv

Add custom format to validate strings or numbers. It can also be used to replace pre-defined formats for Ajv instance.

Strings are converted to RegExp.

Function should return validation result as `true` or `false`.

If object is passed it should have properties `validate`, `compare` and `async`:

- _validate_: a string, RegExp or a function as described above.
- _compare_: an optional comparison function that accepts two strings and compares them according to the format meaning. This function is used with keywords `formatMaximum`/`formatMinimum` (defined in [ajv-keywords](https://github.com/ajv-validator/ajv-keywords) package). It should return `1` if the first value is bigger than the second value, `-1` if it is smaller and `0` if it is equal.
- _async_: an optional `true` value if `validate` is an asynchronous function; in this case it should return a promise that resolves with a value `true` or `false`.
- _type_: an optional type of data that the format applies to. It can be `"string"` (default) or `"number"` (see https://github.com/ajv-validator/ajv/issues/291#issuecomment-259923858). If the type of data is different, the validation will pass.

Custom formats can be also added via `formats` option.


##### <a name="api-addkeyword"></a>.addKeyword(String keyword, Object definition) -&gt; Ajv

Add custom validation keyword to Ajv instance.

Keyword should be different from all standard JSON Schema keywords and different from previously defined keywords. There is no way to redefine keywords or to remove keyword definition from the instance.

Keyword must start with a letter, `_` or `$`, and may continue with letters, numbers, `_`, `$`, or `-`.
It is recommended to use an application-specific prefix for keywords to avoid current and future name collisions.

Example Keywords:
- `"xyz-example"`: valid, and uses prefix for the xyz project to avoid name collisions.
- `"example"`: valid, but not recommended as it could collide with future versions of JSON Schema etc.
- `"3-example"`: invalid as numbers are not allowed to be the first character in a keyword

Keyword definition is an object with the following properties:

- _type_: optional string or array of strings with data type(s) that the keyword applies to. If not present, the keyword will apply to all types.
- _validate_: validating function
- _compile_: compiling function
- _macro_: macro function
- _inline_: compiling function that returns code (as string)
- _schema_: an optional `false` value used with "validate" keyword to not pass schema
- _metaSchema_: an optional meta-schema for keyword schema
- _dependencies_: an optional list of properties that must be present in the parent schema - it will be checked during schema compilation
- _modifying_: `true` MUST be passed if keyword modifies data
- _statements_: `true` can be passed in case inline keyword generates statements (as opposed to expression)
- _valid_: pass `true`/`false` to pre-define validation result, the result returned from validation function will be ignored. This option cannot be used with macro keywords.
- _$data_: an optional `true` value to support [$data reference](#data-reference) as the value of custom keyword. The reference will be resolved at validation time. If the keyword has meta-schema it would be extended to allow $data and it will be used to validate the resolved value. Supporting $data reference requires that keyword has validating function (as the only option or in addition to compile, macro or inline function).
- _async_: an optional `true` value if the validation function is asynchronous (whether it is compiled or passed in _validate_ property); in this case it should return a promise that resolves with a value `true` or `false`. This option is ignored in case of "macro" and "inline" keywords.
- _errors_: an optional boolean or string `"full"` indicating whether keyword returns errors. If this property is not set Ajv will determine if the errors were set in case of failed validation.

_compile_, _macro_ and _inline_ are mutually exclusive, only one should be used at a time. _validate_ can be used separately or in addition to them to support $data reference.

__Please note__: If the keyword is validating data type that is different from the type(s) in its definition, the validation function will not be called (and expanded macro will not be used), so there is no need to check for data type inside validation function or inside schema returned by macro function (unless you want to enforce a specific type and for some reason do not want to use a separate `type` keyword for that). In the same way as standard keywords work, if the keyword does not apply to the data type being validated, the validation of this keyword will succeed.

See [Defining custom keywords](#defining-custom-keywords) for more details.


##### .getKeyword(String keyword) -&gt; Object|Boolean

Returns custom keyword definition, `true` for pre-defined keywords and `false` if the keyword is unknown.


##### .removeKeyword(String keyword) -&gt; Ajv

Removes custom or pre-defined keyword so you can redefine them.

While this method can be used to extend pre-defined keywords, it can also be used to completely change their meaning - it may lead to unexpected results.

__Please note__: schemas compiled before the keyword is removed will continue to work without changes. To recompile schemas use `removeSchema` method and compile them again.


##### .errorsText([Array&lt;Object&gt; errors [, Object options]]) -&gt; String

Returns the text with all errors in a String.

Options can have properties `separator` (string used to separate errors, ", " by default) and `dataVar` (the variable name that dataPaths are prefixed with, "data" by default).


## Options

Defaults:

```javascript
{
  // validation and reporting options:
  $data:            false,
  allErrors:        false,
  verbose:          false,
  $comment:         false, // NEW in Ajv version 6.0
  jsonPointers:     false,
  uniqueItems:      true,
  unicode:          true,
  nullable:         false,
  format:           'fast',
  formats:          {},
  unknownFormats:   true,
  schemas:          {},
  logger:           undefined,
  // referenced schema options:
  schemaId:         '$id',
  missingRefs:      true,
  extendRefs:       'ignore', // recommended 'fail'
  loadSchema:       undefined, // function(uri: string): Promise {}
  // options to modify validated data:
  removeAdditional: false,
  useDefaults:      false,
  coerceTypes:      false,
  // strict mode options
  strictDefaults:   false,
  strictKeywords:   false,
  strictNumbers:    false,
  // asynchronous validation options:
  transpile:        undefined, // requires ajv-async package
  // advanced options:
  meta:             true,
  validateSchema:   true,
  addUsedSchema:    true,
  inlineRefs:       true,
  passContext:      false,
  loopRequired:     Infinity,
  ownProperties:    false,
  multipleOfPrecision: false,
  errorDataPath:    'object', // deprecated
  messages:         true,
  sourceCode:       false,
  processCode:      undefined, // function (str: string, schema: object): string {}
  cache:            new Cache,
  serialize:        undefined
}
```

##### Validation and reporting options

- _$data_: support [$data references](#data-reference). Draft 6 meta-schema that is added by default will be extended to allow them. If you want to use another meta-schema you need to use $dataMetaSchema method to add support for $data reference. See [API](#api).
- _allErrors_: check all rules collecting all errors. Default is to return after the first error.
- _verbose_: include the reference to the part of the schema (`schema` and `parentSchema`) and validated data in errors (false by default).
- _$comment_ (NEW in Ajv version 6.0): log or pass the value of `$comment` keyword to a function. Option values:
  - `false` (default): ignore $comment keyword.
  - `true`: log the keyword value to console.
  - function: pass the keyword value, its schema path and root schema to the specified function
- _jsonPointers_: set `dataPath` property of errors using [JSON Pointers](https://tools.ietf.org/html/rfc6901) instead of JavaScript property access notation.
- _uniqueItems_: validate `uniqueItems` keyword (true by default).
- _unicode_: calculate correct length of strings with unicode pairs (true by default). Pass `false` to use `.length` of strings that is faster, but gives "incorrect" lengths of strings with unicode pairs - each unicode pair is counted as two characters.
- _nullable_: support keyword "nullable" from [Open API 3 specification](https://swagger.io/docs/specification/data-models/data-types/).
- _format_: formats validation mode. Option values:
  - `"fast"` (default) - simplified and fast validation (see [Formats](#formats) for details of which formats are available and affected by this option).
  - `"full"` - more restrictive and slow validation. E.g., 25:00:00 and 2015/14/33 will be invalid time and date in 'full' mode but it will be valid in 'fast' mode.
  - `false` - ignore all format keywords.
- _formats_: an object with custom formats. Keys and values will be passed to `addFormat` method.
- _keywords_: an object with custom keywords. Keys and values will be passed to `addKeyword` method.
- _unknownFormats_: handling of unknown formats. Option values:
  - `true` (default) - if an unknown format is encountered the exception is thrown during schema compilation. If `format` keyword value is [$data reference](#data-reference) and it is unknown the validation will fail.
  - `[String]` - an array of unknown format names that will be ignored. This option can be used to allow usage of third party schemas with format(s) for which you don't have definitions, but still fail if another unknown format is used. If `format` keyword value is [$data reference](#data-reference) and it is not in this array the validation will fail.
  - `"ignore"` - to log warning during schema compilation and always pass validation (the default behaviour in versions before 5.0.0). This option is not recommended, as it allows to mistype format name and it won't be validated without any error message. This behaviour is required by JSON Schema specification.
- _schemas_: an array or object of schemas that will be added to the instance. In case you pass the array the schemas must have IDs in them. When the object is passed the method `addSchema(value, key)` will be called for each schema in this object.
- _logger_: sets the logging method. Default is the global `console` object that should have methods `log`, `warn` and `error`. See [Error logging](#error-logging). Option values:
  - custom logger - it should have methods `log`, `warn` and `error`. If any of these methods is missing an exception will be thrown.
  - `false` - logging is disabled.


##### Referenced schema options

- _schemaId_: this option defines which keywords are used as schema URI. Option value:
  - `"$id"` (default) - only use `$id` keyword as schema URI (as specified in JSON Schema draft-06/07), ignore `id` keyword (if it is present a warning will be logged).
  - `"id"` - only use `id` keyword as schema URI (as specified in JSON Schema draft-04), ignore `$id` keyword (if it is present a warning will be logged).
  - `"auto"` - use both `$id` and `id` keywords as schema URI. If both are present (in the same schema object) and different the exception will be thrown during schema compilation.
- _missingRefs_: handling of missing referenced schemas. Option values:
  - `true` (default) - if the reference cannot be resolved during compilation the exception is thrown. The thrown error has properties `missingRef` (with hash fragment) and `missingSchema` (without it). Both properties are resolved relative to the current base id (usually schema id, unless it was substituted).
  - `"ignore"` - to log error during compilation and always pass validation.
  - `"fail"` - to log error and successfully compile schema but fail validation if this rule is checked.
- _extendRefs_: validation of other keywords when `$ref` is present in the schema. Option values:
  - `"ignore"` (default) - when `$ref` is used other keywords are ignored (as per [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03#section-3) standard). A warning will be logged during the schema compilation.
  - `"fail"` (recommended) - if other validation keywords are used together with `$ref` the exception will be thrown when the schema is compiled. This option is recommended to make sure schema has no keywords that are ignored, which can be confusing.
  - `true` - validate all keywords in the schemas with `$ref` (the default behaviour in versions before 5.0.0).
- _loadSchema_: asynchronous function that will be used to load remote schemas when `compileAsync` [method](#api-compileAsync) is used and some reference is missing (option `missingRefs` should NOT be 'fail' or 'ignore'). This function should accept remote schema uri as a parameter and return a Promise that resolves to a schema. See example in [Asynchronous compilation](#asynchronous-schema-compilation).


##### Options to modify validated data

- _removeAdditional_: remove additional properties - see example in [Filtering data](#filtering-data). This option is not used if schema is added with `addMetaSchema` method. Option values:
  - `false` (default) - not to remove additional properties
  - `"all"` - all additional properties are removed, regardless of `additionalProperties` keyword in schema (and no validation is made for them).
  - `true` - only additional properties with `additionalProperties` keyword equal to `false` are removed.
  - `"failing"` - additional properties that fail schema validation will be removed (where `additionalProperties` keyword is `false` or schema).
- _useDefaults_: replace missing or undefined properties and items with the values from corresponding `default` keywords. Default behaviour is to ignore `default` keywords. This option is not used if schema is added with `addMetaSchema` method. See examples in [Assigning defaults](#assigning-defaults). Option values:
  - `false` (default) - do not use defaults
  - `true` - insert defaults by value (object literal is used).
  - `"empty"` - in addition to missing or undefined, use defaults for properties and items that are equal to `null` or `""` (an empty string).
  - `"shared"` (deprecated) - insert defaults by reference. If the default is an object, it will be shared by all instances of validated data. If you modify the inserted default in the validated data, it will be modified in the schema as well.
- _coerceTypes_: change data type of data to match `type` keyword. See the example in [Coercing data types](#coercing-data-types) and [coercion rules](https://github.com/ajv-validator/ajv/blob/master/COERCION.md). Option values:
  - `false` (default) - no type coercion.
  - `true` - coerce scalar data types.
  - `"array"` - in addition to coercions between scalar types, coerce scalar data to an array with one element and vice versa (as required by the schema).


##### Strict mode options

- _strictDefaults_: report ignored `default` keywords in schemas. Option values:
  - `false` (default) - ignored defaults are not reported
  - `true` - if an ignored default is present, throw an error
  - `"log"` - if an ignored default is present, log warning
- _strictKeywords_: report unknown keywords in schemas. Option values:
  - `false` (default) - unknown keywords are not reported
  - `true` - if an unknown keyword is present, throw an error
  - `"log"` - if an unknown keyword is present, log warning
- _strictNumbers_: validate numbers strictly, failing validation for NaN and Infinity. Option values:
  - `false` (default) - NaN or Infinity will pass validation for numeric types
  - `true` - NaN or Infinity will not pass validation for numeric types

##### Asynchronous validation options

- _transpile_: Requires [ajv-async](https://github.com/ajv-validator/ajv-async) package. It determines whether Ajv transpiles compiled asynchronous validation function. Option values:
  - `undefined` (default) - transpile with [nodent](https://github.com/MatAtBread/nodent) if async functions are not supported.
  - `true` - always transpile with nodent.
  - `false` - do not transpile; if async functions are not supported an exception will be thrown.


##### Advanced options

- _meta_: add [meta-schema](http://json-schema.org/documentation.html) so it can be used by other schemas (true by default). If an object is passed, it will be used as the default meta-schema for schemas that have no `$schema` keyword. This default meta-schema MUST have `$schema` keyword.
- _validateSchema_: validate added/compiled schemas against meta-schema (true by default). `$schema` property in the schema can be http://json-schema.org/draft-07/schema or absent (draft-07 meta-schema will be used) or can be a reference to the schema previously added with `addMetaSchema` method. Option values:
  - `true` (default) -  if the validation fails, throw the exception.
  - `"log"` - if the validation fails, log error.
  - `false` - skip schema validation.
- _addUsedSchema_: by default methods `compile` and `validate` add schemas to the instance if they have `$id` (or `id`) property that doesn't start with "#". If `$id` is present and it is not unique the exception will be thrown. Set this option to `false` to skip adding schemas to the instance and the `$id` uniqueness check when these methods are used. This option does not affect `addSchema` method.
- _inlineRefs_: Affects compilation of referenced schemas. Option values:
  - `true` (default) - the referenced schemas that don't have refs in them are inlined, regardless of their size - that substantially improves performance at the cost of the bigger size of compiled schema functions.
  - `false` - to not inline referenced schemas (they will be compiled as separate functions).
  - integer number - to limit the maximum number of keywords of the schema that will be inlined.
- _passContext_: pass validation context to custom keyword functions. If this option is `true` and you pass some context to the compiled validation function with `validate.call(context, data)`, the `context` will be available as `this` in your custom keywords. By default `this` is Ajv instance.
- _loopRequired_: by default `required` keyword is compiled into a single expression (or a sequence of statements in `allErrors` mode). In case of a very large number of properties in this keyword it may result in a very big validation function. Pass integer to set the number of properties above which `required` keyword will be validated in a loop - smaller validation function size but also worse performance.
- _ownProperties_: by default Ajv iterates over all enumerable object properties; when this option is `true` only own enumerable object properties (i.e. found directly on the object rather than on its prototype) are iterated. Contributed by @mbroadst.
- _multipleOfPrecision_: by default `multipleOf` keyword is validated by comparing the result of division with parseInt() of that result. It works for dividers that are bigger than 1. For small dividers such as 0.01 the result of the division is usually not integer (even when it should be integer, see issue [#84](https://github.com/ajv-validator/ajv/issues/84)). If you need to use fractional dividers set this option to some positive integer N to have `multipleOf` validated using this formula: `Math.abs(Math.round(division) - division) < 1e-N` (it is slower but allows for float arithmetics deviations).
- _errorDataPath_ (deprecated): set `dataPath` to point to 'object' (default) or to 'property' when validating keywords `required`, `additionalProperties` and `dependencies`.
- _messages_: Include human-readable messages in errors. `true` by default. `false` can be passed when custom messages are used (e.g. with [ajv-i18n](https://github.com/ajv-validator/ajv-i18n)).
- _sourceCode_: add `sourceCode` property to validating function (for debugging; this code can be different from the result of toString call).
- _processCode_: an optional function to process generated code before it is passed to Function constructor. It can be used to either beautify (the validating function is generated without line-breaks) or to transpile code. Starting from version 5.0.0 this option replaced options:
  - `beautify` that formatted the generated function using [js-beautify](https://github.com/beautify-web/js-beautify). If you want to beautify the generated code pass a function calling `require('js-beautify').js_beautify` as `processCode: code => js_beautify(code)`.
  - `transpile` that transpiled asynchronous validation function. You can still use `transpile` option with [ajv-async](https://github.com/ajv-validator/ajv-async) package. See [Asynchronous validation](#asynchronous-validation) for more information.
- _cache_: an optional instance of cache to store compiled schemas using stable-stringified schema as a key. For example, set-associative cache [sacjs](https://github.com/epoberezkin/sacjs) can be used. If not passed then a simple hash is used which is good enough for the common use case (a limited number of statically defined schemas). Cache should have methods `put(key, value)`, `get(key)`, `del(key)` and `clear()`.
- _serialize_: an optional function to serialize schema to cache key. Pass `false` to use schema itself as a key (e.g., if WeakMap used as a cache). By default [fast-json-stable-stringify](https://github.com/epoberezkin/fast-json-stable-stringify) is used.


## Validation errors

In case of validation failure, Ajv assigns the array of errors to `errors` property of validation function (or to `errors` property of Ajv instance when `validate` or `validateSchema` methods were called). In case of [asynchronous validation](#asynchronous-validation), the returned promise is rejected with exception `Ajv.ValidationError` that has `errors` property.


### Error objects

Each error is an object with the following properties:

- _keyword_: validation keyword.
- _dataPath_: the path to the part of the data that was validated. By default `dataPath` uses JavaScript property access notation (e.g., `".prop[1].subProp"`). When the option `jsonPointers` is true (see [Options](#options)) `dataPath` will be set using JSON pointer standard (e.g., `"/prop/1/subProp"`).
- _schemaPath_: the path (JSON-pointer as a URI fragment) to the schema of the keyword that failed validation.
- _params_: the object with the additional information about error that can be used to create custom error messages (e.g., using [ajv-i18n](https://github.com/ajv-validator/ajv-i18n) package). See below for parameters set by all keywords.
- _message_: the standard error message (can be excluded with option `messages` set to false).
- _schema_: the schema of the keyword (added with `verbose` option).
- _parentSchema_: the schema containing the keyword (added with `verbose` option)
- _data_: the data validated by the keyword (added with `verbose` option).

__Please note__: `propertyNames` keyword schema validation errors have an additional property `propertyName`, `dataPath` points to the object. After schema validation for each property name, if it is invalid an additional error is added with the property `keyword` equal to `"propertyNames"`.


### Error parameters

Properties of `params` object in errors depend on the keyword that failed validation.

- `maxItems`, `minItems`, `maxLength`, `minLength`, `maxProperties`, `minProperties` - property `limit` (number, the schema of the keyword).
- `additionalItems` - property `limit` (the maximum number of allowed items in case when `items` keyword is an array of schemas and `additionalItems` is false).
- `additionalProperties` - property `additionalProperty` (the property not used in `properties` and `patternProperties` keywords).
- `dependencies` - properties:
  - `property` (dependent property),
  - `missingProperty` (required missing dependency - only the first one is reported currently)
  - `deps` (required dependencies, comma separated list as a string),
  - `depsCount` (the number of required dependencies).
- `format` - property `format` (the schema of the keyword).
- `maximum`, `minimum` - properties:
  - `limit` (number, the schema of the keyword),
  - `exclusive` (boolean, the schema of `exclusiveMaximum` or `exclusiveMinimum`),
  - `comparison` (string, comparison operation to compare the data to the limit, with the data on the left and the limit on the right; can be "<", "<=", ">", ">=")
- `multipleOf` - property `multipleOf` (the schema of the keyword)
- `pattern` - property `pattern` (the schema of the keyword)
- `required` - property `missingProperty` (required property that is missing).
- `propertyNames` - property `propertyName` (an invalid property name).
- `patternRequired` (in ajv-keywords) - property `missingPattern` (required pattern that did not match any property).
- `type` - property `type` (required type(s), a string, can be a comma-separated list)
- `uniqueItems` - properties `i` and `j` (indices of duplicate items).
- `const` - property `allowedValue` pointing to the value (the schema of the keyword).
- `enum` - property `allowedValues` pointing to the array of values (the schema of the keyword).
- `$ref` - property `ref` with the referenced schema URI.
- `oneOf` - property `passingSchemas` (array of indices of passing schemas, null if no schema passes).
- custom keywords (in case keyword definition doesn't create errors) - property `keyword` (the keyword name).


### Error logging

Using the `logger` option when initiallizing Ajv will allow you to define custom logging. Here you can build upon the exisiting logging. The use of other logging packages is supported as long as the package or its associated wrapper exposes the required methods. If any of the required methods are missing an exception will be thrown.
- **Required Methods**: `log`, `warn`, `error`

```javascript
var otherLogger = new OtherLogger();
var ajv = new Ajv({
  logger: {
    log: console.log.bind(console),
    warn: function warn() {
      otherLogger.logWarn.apply(otherLogger, arguments);
    },
    error: function error() {
      otherLogger.logError.apply(otherLogger, arguments);
      console.error.apply(console, arguments);
    }
  }
});
```


## Plugins

Ajv can be extended with plugins that add custom keywords, formats or functions to process generated code. When such plugin is published as npm package it is recommended that it follows these conventions:

- it exports a function
- this function accepts ajv instance as the first parameter and returns the same instance to allow chaining
- this function can accept an optional configuration as the second parameter

If you have published a useful plugin please submit a PR to add it to the next section.


## Related packages

- [ajv-async](https://github.com/ajv-validator/ajv-async) - plugin to configure async validation mode
- [ajv-bsontype](https://github.com/BoLaMN/ajv-bsontype) - plugin to validate mongodb's bsonType formats
- [ajv-cli](https://github.com/jessedc/ajv-cli) - command line interface
- [ajv-errors](https://github.com/ajv-validator/ajv-errors) - plugin for custom error messages
- [ajv-i18n](https://github.com/ajv-validator/ajv-i18n) - internationalised error messages
- [ajv-istanbul](https://github.com/ajv-validator/ajv-istanbul) - plugin to instrument generated validation code to measure test coverage of your schemas
- [ajv-keywords](https://github.com/ajv-validator/ajv-keywords) - plugin with custom validation keywords (select, typeof, etc.)
- [ajv-merge-patch](https://github.com/ajv-validator/ajv-merge-patch) - plugin with keywords $merge and $patch
- [ajv-pack](https://github.com/ajv-validator/ajv-pack) - produces a compact module exporting validation functions
- [ajv-formats-draft2019](https://github.com/luzlab/ajv-formats-draft2019) - format validators for draft2019 that aren't already included in ajv (ie. `idn-hostname`, `idn-email`, `iri`, `iri-reference` and `duration`).

## Some packages using Ajv

- [webpack](https://github.com/webpack/webpack) - a module bundler. Its main purpose is to bundle JavaScript files for usage in a browser
- [jsonscript-js](https://github.com/JSONScript/jsonscript-js) - the interpreter for [JSONScript](http://www.jsonscript.org) - scripted processing of existing endpoints and services
- [osprey-method-handler](https://github.com/mulesoft-labs/osprey-method-handler) - Express middleware for validating requests and responses based on a RAML method object, used in [osprey](https://github.com/mulesoft/osprey) - validating API proxy generated from a RAML definition
- [har-validator](https://github.com/ahmadnassri/har-validator) - HTTP Archive (HAR) validator
- [jsoneditor](https://github.com/josdejong/jsoneditor) - a web-based tool to view, edit, format, and validate JSON http://jsoneditoronline.org
- [JSON Schema Lint](https://github.com/nickcmaynard/jsonschemalint) - a web tool to validate JSON/YAML document against a single JSON Schema http://jsonschemalint.com
- [objection](https://github.com/vincit/objection.js) - SQL-friendly ORM for Node.js
- [table](https://github.com/gajus/table) - formats data into a string table
- [ripple-lib](https://github.com/ripple/ripple-lib) - a JavaScript API for interacting with [Ripple](https://ripple.com) in Node.js and the browser
- [restbase](https://github.com/wikimedia/restbase) - distributed storage with REST API & dispatcher for backend services built to provide a low-latency & high-throughput API for Wikipedia / Wikimedia content
- [hippie-swagger](https://github.com/CacheControl/hippie-swagger) - [Hippie](https://github.com/vesln/hippie) wrapper that provides end to end API testing with swagger validation
- [react-form-controlled](https://github.com/seeden/react-form-controlled) - React controlled form components with validation
- [rabbitmq-schema](https://github.com/tjmehta/rabbitmq-schema) - a schema definition module for RabbitMQ graphs and messages
- [@query/schema](https://www.npmjs.com/package/@query/schema) - stream filtering with a URI-safe query syntax parsing to JSON Schema
- [chai-ajv-json-schema](https://github.com/peon374/chai-ajv-json-schema) - chai plugin to us JSON Schema with expect in mocha tests
- [grunt-jsonschema-ajv](https://github.com/SignpostMarv/grunt-jsonschema-ajv) - Grunt plugin for validating files against JSON Schema
- [extract-text-webpack-plugin](https://github.com/webpack-contrib/extract-text-webpack-plugin) - extract text from bundle into a file
- [electron-builder](https://github.com/electron-userland/electron-builder) - a solution to package and build a ready for distribution Electron app
- [addons-linter](https://github.com/mozilla/addons-linter) - Mozilla Add-ons Linter
- [gh-pages-generator](https://github.com/epoberezkin/gh-pages-generator) - multi-page site generator converting markdown files to GitHub pages
- [ESLint](https://github.com/eslint/eslint) - the pluggable linting utility for JavaScript and JSX


## Tests

```
npm install
git submodule update --init
npm test
```

## Contributing

All validation functions are generated using doT templates in [dot](https://github.com/ajv-validator/ajv/tree/master/lib/dot) folder. Templates are precompiled so doT is not a run-time dependency.

`npm run build` - compiles templates to [dotjs](https://github.com/ajv-validator/ajv/tree/master/lib/dotjs) folder.

`npm run watch` - automatically compiles templates when files in dot folder change

Please see [Contributing guidelines](https://github.com/ajv-validator/ajv/blob/master/CONTRIBUTING.md)


## Changes history

See https://github.com/ajv-validator/ajv/releases

__Please note__: [Changes in version 7.0.0-beta](https://github.com/ajv-validator/ajv/releases/tag/v7.0.0-beta.0)

[Version 6.0.0](https://github.com/ajv-validator/ajv/releases/tag/v6.0.0).

## Code of conduct

Please review and follow the [Code of conduct](https://github.com/ajv-validator/ajv/blob/master/CODE_OF_CONDUCT.md).

Please report any unacceptable behaviour to ajv.validator@gmail.com - it will be reviewed by the project team.


## Open-source software support

Ajv is a part of [Tidelift subscription](https://tidelift.com/subscription/pkg/npm-ajv?utm_source=npm-ajv&utm_medium=referral&utm_campaign=readme) - it provides a centralised support to open-source software users, in addition to the support provided by software maintainers.


## License

[MIT](https://github.com/ajv-validator/ajv/blob/master/LICENSE)


---

These files are compiled dot templates from dot folder.

Do NOT edit them directly, edit the templates and run `npm run build` from main ajv folder.


---

# ajv-formats

JSON Schema formats for Ajv

[![Build Status](https://travis-ci.org/ajv-validator/ajv-formats.svg?branch=master)](https://travis-ci.org/ajv-validator/ajv-formats)
[![npm](https://img.shields.io/npm/v/ajv-formats.svg)](https://www.npmjs.com/package/ajv-formats)
[![Gitter](https://img.shields.io/gitter/room/ajv-validator/ajv.svg)](https://gitter.im/ajv-validator/ajv)
[![GitHub Sponsors](https://img.shields.io/badge/$-sponsors-brightgreen)](https://github.com/sponsors/epoberezkin)

## Usage

```javascript
// ESM/TypeScript import
import Ajv from "ajv"
import addFormats from "ajv-formats"
// Node.js require:
const Ajv = require("ajv")
const addFormats = require("ajv-formats")

const ajv = new Ajv()
addFormats(ajv)
```

## Formats

The package defines these formats:

- _date_: full-date according to [RFC3339](http://tools.ietf.org/html/rfc3339#section-5.6).
- _time_: time with optional time-zone.
- _date-time_: date-time from the same source (time-zone is mandatory).
- _duration_: duration from [RFC3339](https://tools.ietf.org/html/rfc3339#appendix-A)
- _uri_: full URI.
- _uri-reference_: URI reference, including full and relative URIs.
- _uri-template_: URI template according to [RFC6570](https://tools.ietf.org/html/rfc6570)
- _url_ (deprecated): [URL record](https://url.spec.whatwg.org/#concept-url).
- _email_: email address.
- _hostname_: host name according to [RFC1034](http://tools.ietf.org/html/rfc1034#section-3.5).
- _ipv4_: IP address v4.
- _ipv6_: IP address v6.
- _regex_: tests whether a string is a valid regular expression by passing it to RegExp constructor.
- _uuid_: Universally Unique IDentifier according to [RFC4122](http://tools.ietf.org/html/rfc4122).
- _json-pointer_: JSON-pointer according to [RFC6901](https://tools.ietf.org/html/rfc6901).
- _relative-json-pointer_: relative JSON-pointer according to [this draft](http://tools.ietf.org/html/draft-luff-relative-json-pointer-00).
- _byte_: base64 encoded data according to the [openApi 3.0.0 specification](https://spec.openapis.org/oas/v3.0.0#data-types)
- _int32_: signed 32 bits integer according to the [openApi 3.0.0 specification](https://spec.openapis.org/oas/v3.0.0#data-types)
- _int64_: signed 64 bits according to the [openApi 3.0.0 specification](https://spec.openapis.org/oas/v3.0.0#data-types)
- _float_: float according to the [openApi 3.0.0 specification](https://spec.openapis.org/oas/v3.0.0#data-types)
- _double_: double according to the [openApi 3.0.0 specification](https://spec.openapis.org/oas/v3.0.0#data-types)
- _password_: password string according to the [openApi 3.0.0 specification](https://spec.openapis.org/oas/v3.0.0#data-types)
- _binary_: binary string according to the [openApi 3.0.0 specification](https://spec.openapis.org/oas/v3.0.0#data-types)

See regular expressions used for format validation and the sources that were used in [formats.ts](https://github.com/ajv-validator/ajv-formats/blob/master/src/formats.ts).

**Please note**: JSON Schema draft-07 also defines formats `iri`, `iri-reference`, `idn-hostname` and `idn-email` for URLs, hostnames and emails with international characters. These formats are available in [ajv-formats-draft2019](https://github.com/luzlab/ajv-formats-draft2019) plugin.

## Keywords to compare values: `formatMaximum` / `formatMinimum` and `formatExclusiveMaximum` / `formatExclusiveMinimum`

These keywords allow to define minimum/maximum constraints when the format keyword defines ordering (`compare` function in format definition).

These keywords are added to ajv instance when ajv-formats is used without options or with option `keywords: true`.

These keywords apply only to strings. If the data is not a string, the validation succeeds.

The value of keywords `formatMaximum`/`formatMinimum` and `formatExclusiveMaximum`/`formatExclusiveMinimum` should be a string or [\$data reference](https://github.com/ajv-validator/ajv/blob/master/docs/validation.md#data-reference). This value is the maximum (minimum) allowed value for the data to be valid as determined by `format` keyword. If `format` keyword is not present schema compilation will throw exception.

When these keyword are added, they also add comparison functions to formats `"date"`, `"time"` and `"date-time"`. User-defined formats also can have comparison functions. See [addFormat](https://github.com/ajv-validator/ajv/blob/master/docs/api.md#api-addformat) method.

```javascript
require("ajv-formats")(ajv)

const schema = {
  type: "string",
  format: "date",
  formatMinimum: "2016-02-06",
  formatExclusiveMaximum: "2016-12-27",
}

const validDataList = ["2016-02-06", "2016-12-26"]

const invalidDataList = ["2016-02-05", "2016-12-27", "abc"]
```

## Options

Options can be passed via the second parameter. Options value can be

1. The list of format names that will be added to ajv instance:

```javascript
addFormats(ajv, ["date", "time"])
```

**Please note**: when ajv encounters an undefined format it throws exception (unless ajv instance was configured with `strict: false` option). To allow specific undefined formats they have to be passed to ajv instance via `formats` option with `true` value:

```javascript
const ajv = new Ajv((formats: {date: true, time: true})) // to ignore "date" and "time" formats in schemas.
```

2. Format validation mode (default is `"full"`) with optional list of format names and `keywords` option to add additional format comparison keywords:

```javascript
addFormats(ajv, {mode: "fast"})
```

or

```javascript
addFormats(ajv, {mode: "fast", formats: ["date", "time"], keywords: true})
```

In `"fast"` mode the following formats are simplified: `"date"`, `"time"`, `"date-time"`, `"uri"`, `"uri-reference"`, `"email"`. For example `"date"`, `"time"` and `"date-time"` do not validate ranges in `"fast"` mode, only string structure, and other formats have simplified regular expressions.

## Tests

```bash
npm install
git submodule update --init
npm test
```

## License

[MIT](https://github.com/ajv-validator/ajv-formats/blob/master/LICENSE)


---

<img align="right" alt="Ajv logo" width="160" src="https://ajv.js.org/img/ajv.svg">

&nbsp;

# Ajv JSON schema validator

The fastest JSON validator for Node.js and browser.

Supports JSON Schema draft-04/06/07/2019-09/2020-12 ([draft-04 support](https://ajv.js.org/json-schema.html#draft-04) requires ajv-draft-04 package) and JSON Type Definition [RFC8927](https://datatracker.ietf.org/doc/rfc8927/).

[![build](https://github.com/ajv-validator/ajv/actions/workflows/build.yml/badge.svg)](https://github.com/ajv-validator/ajv/actions?query=workflow%3Abuild)
[![npm](https://img.shields.io/npm/v/ajv.svg)](https://www.npmjs.com/package/ajv)
[![npm downloads](https://img.shields.io/npm/dm/ajv.svg)](https://www.npmjs.com/package/ajv)
[![Coverage Status](https://coveralls.io/repos/github/ajv-validator/ajv/badge.svg?branch=master)](https://coveralls.io/github/ajv-validator/ajv?branch=master)
[![SimpleX](https://img.shields.io/badge/chat-on%20SimpleX-70F0F9)](https://simplex.chat/contact#/?v=1-2&smp=smp%3A%2F%2Fu2dS9sG8nMNURyZwqASV4yROM28Er0luVTx5X1CsMrU%3D%40smp4.simplex.im%2F8KvvURM6J38Gdq9dCuPswMOkMny0xCOJ%23%2F%3Fv%3D1-2%26dh%3DMCowBQYDK2VuAyEAr8rPVRuMOXv6kwF2yUAap-eoVg-9ssOFCi1fIrxTUw0%253D%26srv%3Do5vmywmrnaxalvz6wi3zicyftgio6psuvyniis6gco6bp6ekl4cqj4id.onion&data=%7B%22type%22%3A%22group%22%2C%22groupLinkId%22%3A%224pwLRgWHU9tlroMWHz0uOg%3D%3D%22%7D)
[![Gitter](https://img.shields.io/gitter/room/ajv-validator/ajv.svg)](https://gitter.im/ajv-validator/ajv)
[![GitHub Sponsors](https://img.shields.io/badge/$-sponsors-brightgreen)](https://github.com/sponsors/epoberezkin)

## Ajv sponsors

[<img src="https://ajv.js.org/img/mozilla.svg" width="45%" alt="Mozilla">](https://www.mozilla.org)<img src="https://ajv.js.org/img/gap.svg" width="9%">[<img src="https://ajv.js.org/img/reserved.svg" width="45%">](https://opencollective.com/ajv)

[<img src="https://ajv.js.org/img/microsoft.png" width="31%" alt="Microsoft">](https://opensource.microsoft.com)<img src="https://ajv.js.org/img/gap.svg" width="3%">[<img src="https://ajv.js.org/img/reserved.svg" width="31%">](https://opencollective.com/ajv)<img src="https://ajv.js.org/img/gap.svg" width="3%">[<img src="https://ajv.js.org/img/reserved.svg" width="31%">](https://opencollective.com/ajv)

[<img src="https://ajv.js.org/img/retool.svg" width="22.5%" alt="Retool">](https://retool.com/?utm_source=sponsor&utm_campaign=ajv)<img src="https://ajv.js.org/img/gap.svg" width="3%">[<img src="https://ajv.js.org/img/tidelift.svg" width="22.5%" alt="Tidelift">](https://tidelift.com/subscription/pkg/npm-ajv?utm_source=npm-ajv&utm_medium=referral&utm_campaign=enterprise)<img src="https://ajv.js.org/img/gap.svg" width="3%">[<img src="https://ajv.js.org/img/simplex.svg" width="22.5%" alt="SimpleX">](https://github.com/simplex-chat/simplex-chat)<img src="https://ajv.js.org/img/gap.svg" width="3%">[<img src="https://ajv.js.org/img/reserved.svg" width="22.5%">](https://opencollective.com/ajv)

## Contributing

More than 100 people contributed to Ajv, and we would love to have you join the development. We welcome implementing new features that will benefit many users and ideas to improve our documentation.

Please review [Contributing guidelines](./CONTRIBUTING.md) and [Code components](https://ajv.js.org/components.html).

## Documentation

All documentation is available on the [Ajv website](https://ajv.js.org).

Some useful site links:

- [Getting started](https://ajv.js.org/guide/getting-started.html)
- [JSON Schema vs JSON Type Definition](https://ajv.js.org/guide/schema-language.html)
- [API reference](https://ajv.js.org/api.html)
- [Strict mode](https://ajv.js.org/strict-mode.html)
- [Standalone validation code](https://ajv.js.org/standalone.html)
- [Security considerations](https://ajv.js.org/security.html)
- [Command line interface](https://ajv.js.org/packages/ajv-cli.html)
- [Frequently Asked Questions](https://ajv.js.org/faq.html)

## <a name="sponsors"></a>Please [sponsor Ajv development](https://github.com/sponsors/epoberezkin)

Since I asked to support Ajv development 40 people and 6 organizations contributed via GitHub and OpenCollective - this support helped receiving the MOSS grant!

Your continuing support is very important - the funds will be used to develop and maintain Ajv once the next major version is released.

Please sponsor Ajv via:

- [GitHub sponsors page](https://github.com/sponsors/epoberezkin) (GitHub will match it)
- [Ajv Open Collective](https://opencollective.com/ajv)

Thank you.

#### Open Collective sponsors

<a href="https://opencollective.com/ajv"><img src="https://opencollective.com/ajv/individuals.svg?width=890"></a>

<a href="https://opencollective.com/ajv/organization/0/website"><img src="https://opencollective.com/ajv/organization/0/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/1/website"><img src="https://opencollective.com/ajv/organization/1/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/2/website"><img src="https://opencollective.com/ajv/organization/2/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/3/website"><img src="https://opencollective.com/ajv/organization/3/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/4/website"><img src="https://opencollective.com/ajv/organization/4/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/5/website"><img src="https://opencollective.com/ajv/organization/5/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/6/website"><img src="https://opencollective.com/ajv/organization/6/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/7/website"><img src="https://opencollective.com/ajv/organization/7/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/8/website"><img src="https://opencollective.com/ajv/organization/8/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/9/website"><img src="https://opencollective.com/ajv/organization/9/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/10/website"><img src="https://opencollective.com/ajv/organization/10/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/11/website"><img src="https://opencollective.com/ajv/organization/11/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/12/website"><img src="https://opencollective.com/ajv/organization/12/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/13/website"><img src="https://opencollective.com/ajv/organization/13/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/14/website"><img src="https://opencollective.com/ajv/organization/14/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/15/website"><img src="https://opencollective.com/ajv/organization/15/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/16/website"><img src="https://opencollective.com/ajv/organization/16/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/17/website"><img src="https://opencollective.com/ajv/organization/17/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/18/website"><img src="https://opencollective.com/ajv/organization/18/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/19/website"><img src="https://opencollective.com/ajv/organization/19/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/20/website"><img src="https://opencollective.com/ajv/organization/20/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/21/website"><img src="https://opencollective.com/ajv/organization/21/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/22/website"><img src="https://opencollective.com/ajv/organization/22/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/23/website"><img src="https://opencollective.com/ajv/organization/23/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/24/website"><img src="https://opencollective.com/ajv/organization/24/avatar.svg"></a>

## Performance

Ajv generates code to turn JSON Schemas into super-fast validation functions that are efficient for v8 optimization.

Currently Ajv is the fastest and the most standard compliant validator according to these benchmarks:

- [json-schema-benchmark](https://github.com/ebdrup/json-schema-benchmark) - 50% faster than the second place
- [jsck benchmark](https://github.com/pandastrike/jsck#benchmarks) - 20-190% faster
- [z-schema benchmark](https://rawgit.com/zaggino/z-schema/master/benchmark/results.html)
- [themis benchmark](https://cdn.rawgit.com/playlyfe/themis/master/benchmark/results.html)

Performance of different validators by [json-schema-benchmark](https://github.com/ebdrup/json-schema-benchmark):

[![performance](https://chart.googleapis.com/chart?chxt=x,y&cht=bhs&chco=76A4FB&chls=2.0&chbh=62,4,1&chs=600x416&chxl=-1:|ajv|@exodus/schemasafe|is-my-json-valid|djv|@cfworker/json-schema|jsonschema/=t:100,69.2,51.5,13.1,5.1,1.2)](https://github.com/ebdrup/json-schema-benchmark/blob/master/README.md#performance)

## Features

- Ajv implements JSON Schema [draft-06/07/2019-09/2020-12](http://json-schema.org/) standards (draft-04 is supported in v6):
  - all validation keywords (see [JSON Schema validation keywords](https://ajv.js.org/json-schema.html))
  - [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md) extensions:
    - NEW: keyword [discriminator](https://ajv.js.org/json-schema.html#discriminator).
    - keyword [nullable](https://ajv.js.org/json-schema.html#nullable).
  - full support of remote references (remote schemas have to be added with `addSchema` or compiled to be available)
  - support of recursive references between schemas
  - correct string lengths for strings with unicode pairs
  - JSON Schema [formats](https://ajv.js.org/guide/formats.html) (with [ajv-formats](https://github.com/ajv-validator/ajv-formats) plugin).
  - [validates schemas against meta-schema](https://ajv.js.org/api.html#api-validateschema)
- NEW: supports [JSON Type Definition](https://datatracker.ietf.org/doc/rfc8927/):
  - all keywords (see [JSON Type Definition schema forms](https://ajv.js.org/json-type-definition.html))
  - meta-schema for JTD schemas
  - "union" keyword and user-defined keywords (can be used inside "metadata" member of the schema)
- supports [browsers](https://ajv.js.org/guide/environments.html#browsers) and Node.js 10.x - current
- [asynchronous loading](https://ajv.js.org/guide/managing-schemas.html#asynchronous-schema-loading) of referenced schemas during compilation
- "All errors" validation mode with [option allErrors](https://ajv.js.org/options.html#allerrors)
- [error messages with parameters](https://ajv.js.org/api.html#validation-errors) describing error reasons to allow error message generation
- i18n error messages support with [ajv-i18n](https://github.com/ajv-validator/ajv-i18n) package
- [removing-additional-properties](https://ajv.js.org/guide/modifying-data.html#removing-additional-properties)
- [assigning defaults](https://ajv.js.org/guide/modifying-data.html#assigning-defaults) to missing properties and items
- [coercing data](https://ajv.js.org/guide/modifying-data.html#coercing-data-types) to the types specified in `type` keywords
- [user-defined keywords](https://ajv.js.org/guide/user-keywords.html)
- additional extension keywords with [ajv-keywords](https://github.com/ajv-validator/ajv-keywords) package
- [\$data reference](https://ajv.js.org/guide/combining-schemas.html#data-reference) to use values from the validated data as values for the schema keywords
- [asynchronous validation](https://ajv.js.org/guide/async-validation.html) of user-defined formats and keywords

## Install

To install version 8:

```
npm install ajv
```

## <a name="usage"></a>Getting started

Try it in the Node.js REPL: https://runkit.com/npm/ajv

In JavaScript:

```javascript
// or ESM/TypeScript import
import Ajv from "ajv"
// Node.js require:
const Ajv = require("ajv")

const ajv = new Ajv() // options can be passed, e.g. {allErrors: true}

const schema = {
  type: "object",
  properties: {
    foo: {type: "integer"},
    bar: {type: "string"},
  },
  required: ["foo"],
  additionalProperties: false,
}

const data = {
  foo: 1,
  bar: "abc",
}

const validate = ajv.compile(schema)
const valid = validate(data)
if (!valid) console.log(validate.errors)
```

Learn how to use Ajv and see more examples in the [Guide: getting started](https://ajv.js.org/guide/getting-started.html)

## Changes history

See [https://github.com/ajv-validator/ajv/releases](https://github.com/ajv-validator/ajv/releases)

**Please note**: [Changes in version 8.0.0](https://github.com/ajv-validator/ajv/releases/tag/v8.0.0)

[Version 7.0.0](https://github.com/ajv-validator/ajv/releases/tag/v7.0.0)

[Version 6.0.0](https://github.com/ajv-validator/ajv/releases/tag/v6.0.0).

## Code of conduct

Please review and follow the [Code of conduct](./CODE_OF_CONDUCT.md).

Please report any unacceptable behaviour to ajv.validator@gmail.com - it will be reviewed by the project team.

## Security contact

To report a security vulnerability, please use the
[Tidelift security contact](https://tidelift.com/security).
Tidelift will coordinate the fix and disclosure. Please do NOT report security vulnerabilities via GitHub issues.

## Open-source software support

Ajv is a part of [Tidelift subscription](https://tidelift.com/subscription/pkg/npm-ajv?utm_source=npm-ajv&utm_medium=referral&utm_campaign=readme) - it provides a centralised support to open-source software users, in addition to the support provided by software maintainers.

## License

[MIT](./LICENSE)


---

# json-schema-traverse
Traverse JSON Schema passing each schema object to callback

[![build](https://github.com/epoberezkin/json-schema-traverse/workflows/build/badge.svg)](https://github.com/epoberezkin/json-schema-traverse/actions?query=workflow%3Abuild)
[![npm](https://img.shields.io/npm/v/json-schema-traverse)](https://www.npmjs.com/package/json-schema-traverse)
[![coverage](https://coveralls.io/repos/github/epoberezkin/json-schema-traverse/badge.svg?branch=master)](https://coveralls.io/github/epoberezkin/json-schema-traverse?branch=master)


## Install

```
npm install json-schema-traverse
```


## Usage

```javascript
const traverse = require('json-schema-traverse');
const schema = {
  properties: {
    foo: {type: 'string'},
    bar: {type: 'integer'}
  }
};

traverse(schema, {cb});
// cb is called 3 times with:
// 1. root schema
// 2. {type: 'string'}
// 3. {type: 'integer'}

// Or:

traverse(schema, {cb: {pre, post}});
// pre is called 3 times with:
// 1. root schema
// 2. {type: 'string'}
// 3. {type: 'integer'}
//
// post is called 3 times with:
// 1. {type: 'string'}
// 2. {type: 'integer'}
// 3. root schema

```

Callback function `cb` is called for each schema object (not including draft-06 boolean schemas), including the root schema, in pre-order traversal. Schema references ($ref) are not resolved, they are passed as is.  Alternatively, you can pass a `{pre, post}` object as `cb`, and then `pre` will be called before traversing child elements, and `post` will be called after all child elements have been traversed.

Callback is passed these parameters:

- _schema_: the current schema object
- _JSON pointer_: from the root schema to the current schema object
- _root schema_: the schema passed to `traverse` object
- _parent JSON pointer_: from the root schema to the parent schema object (see below)
- _parent keyword_: the keyword inside which this schema appears (e.g. `properties`, `anyOf`, etc.)
- _parent schema_: not necessarily parent object/array; in the example above the parent schema for `{type: 'string'}` is the root schema
- _index/property_: index or property name in the array/object containing multiple schemas; in the example above for `{type: 'string'}` the property name is `'foo'`


## Traverse objects in all unknown keywords

```javascript
const traverse = require('json-schema-traverse');
const schema = {
  mySchema: {
    minimum: 1,
    maximum: 2
  }
};

traverse(schema, {allKeys: true, cb});
// cb is called 2 times with:
// 1. root schema
// 2. mySchema
```

Without option `allKeys: true` callback will be called only with root schema.


## Enterprise support

json-schema-traverse package is a part of [Tidelift enterprise subscription](https://tidelift.com/subscription/pkg/npm-json-schema-traverse?utm_source=npm-json-schema-traverse&utm_medium=referral&utm_campaign=enterprise&utm_term=repo) - it provides a centralised commercial support to open-source software users, in addition to the support provided by software maintainers.


## Security contact

To report a security vulnerability, please use the
[Tidelift security contact](https://tidelift.com/security).
Tidelift will coordinate the fix and disclosure. Please do NOT report security vulnerability via GitHub issues.


## License

[MIT](https://github.com/epoberezkin/json-schema-traverse/blob/master/LICENSE)


---

# ajv-keywords

Custom JSON-Schema keywords for [Ajv](https://github.com/epoberezkin/ajv) validator

[![Build Status](https://travis-ci.org/ajv-validator/ajv-keywords.svg?branch=master)](https://travis-ci.org/ajv-validator/ajv-keywords)
[![npm](https://img.shields.io/npm/v/ajv-keywords.svg)](https://www.npmjs.com/package/ajv-keywords)
[![npm downloads](https://img.shields.io/npm/dm/ajv-keywords.svg)](https://www.npmjs.com/package/ajv-keywords)
[![Coverage Status](https://coveralls.io/repos/github/ajv-validator/ajv-keywords/badge.svg?branch=master)](https://coveralls.io/github/ajv-validator/ajv-keywords?branch=master)
[![Dependabot](https://api.dependabot.com/badges/status?host=github&repo=ajv-validator/ajv-keywords)](https://app.dependabot.com/accounts/ajv-validator/repos/60477053)
[![Gitter](https://img.shields.io/gitter/room/ajv-validator/ajv.svg)](https://gitter.im/ajv-validator/ajv)


## Contents

- [Install](#install)
- [Usage](#usage)
- [Keywords](#keywords)
  - [Types](#types)
    - [typeof](#typeof)
    - [instanceof](#instanceof)
  - [Keywords for numbers](#keywords-for-numbers)
    - [range and exclusiveRange](#range-and-exclusiverange)
  - [Keywords for strings](#keywords-for-strings)
    - [regexp](#regexp)
    - [formatMaximum / formatMinimum and formatExclusiveMaximum / formatExclusiveMinimum](#formatmaximum--formatminimum-and-formatexclusivemaximum--formatexclusiveminimum)
    - [transform](#transform)<sup>\*</sup>
  - [Keywords for arrays](#keywords-for-arrays)
    - [uniqueItemProperties](#uniqueitemproperties)
  - [Keywords for objects](#keywords-for-objects)
    - [allRequired](#allrequired)
    - [anyRequired](#anyrequired)
    - [oneRequired](#onerequired)
    - [patternRequired](#patternrequired)
    - [prohibited](#prohibited)
    - [deepProperties](#deepproperties)
    - [deepRequired](#deeprequired)
  - [Compound keywords](#compound-keywords)
    - [switch](#switch) (deprecated)
    - [select/selectCases/selectDefault](#selectselectcasesselectdefault) (BETA)
  - [Keywords for all types](#keywords-for-all-types)
    - [dynamicDefaults](#dynamicdefaults)<sup>\*</sup>
- [Security contact](#security-contact)
- [Open-source software support](#open-source-software-support)
- [License](#license)

<sup>\*</sup> - keywords that modify data


## Install

```
npm install ajv-keywords
```


## Usage

To add all available keywords:

```javascript
var Ajv = require('ajv');
var ajv = new Ajv;
require('ajv-keywords')(ajv);

ajv.validate({ instanceof: 'RegExp' }, /.*/); // true
ajv.validate({ instanceof: 'RegExp' }, '.*'); // false
```

To add a single keyword:

```javascript
require('ajv-keywords')(ajv, 'instanceof');
```

To add multiple keywords:

```javascript
require('ajv-keywords')(ajv, ['typeof', 'instanceof']);
```

To add a single keyword in browser (to avoid adding unused code):

```javascript
require('ajv-keywords/keywords/instanceof')(ajv);
```


## Keywords

### Types

#### `typeof`

Based on JavaScript `typeof` operation.

The value of the keyword should be a string (`"undefined"`, `"string"`, `"number"`, `"object"`, `"function"`, `"boolean"` or `"symbol"`) or array of strings.

To pass validation the result of `typeof` operation on the value should be equal to the string (or one of the strings in the array).

```
ajv.validate({ typeof: 'undefined' }, undefined); // true
ajv.validate({ typeof: 'undefined' }, null); // false
ajv.validate({ typeof: ['undefined', 'object'] }, null); // true
```


#### `instanceof`

Based on JavaScript `instanceof` operation.

The value of the keyword should be a string (`"Object"`, `"Array"`, `"Function"`, `"Number"`, `"String"`, `"Date"`, `"RegExp"`, `"Promise"` or `"Buffer"`) or array of strings.

To pass validation the result of `data instanceof ...` operation on the value should be true:

```
ajv.validate({ instanceof: 'Array' }, []); // true
ajv.validate({ instanceof: 'Array' }, {}); // false
ajv.validate({ instanceof: ['Array', 'Function'] }, function(){}); // true
```

You can add your own constructor function to be recognised by this keyword:

```javascript
function MyClass() {}
var instanceofDefinition = require('ajv-keywords').get('instanceof').definition;
// or require('ajv-keywords/keywords/instanceof').definition;
instanceofDefinition.CONSTRUCTORS.MyClass = MyClass;

ajv.validate({ instanceof: 'MyClass' }, new MyClass); // true
```


### Keywords for numbers

#### `range` and `exclusiveRange`

Syntax sugar for the combination of minimum and maximum keywords, also fails schema compilation if there are no numbers in the range.

The value of this keyword must be the array consisting of two numbers, the second must be greater or equal than the first one.

If the validated value is not a number the validation passes, otherwise to pass validation the value should be greater (or equal) than the first number and smaller (or equal) than the second number in the array. If `exclusiveRange` keyword is present in the same schema and its value is true, the validated value must not be equal to the range boundaries.

```javascript
var schema = { range: [1, 3] };
ajv.validate(schema, 1); // true
ajv.validate(schema, 2); // true
ajv.validate(schema, 3); // true
ajv.validate(schema, 0.99); // false
ajv.validate(schema, 3.01); // false

var schema = { range: [1, 3], exclusiveRange: true };
ajv.validate(schema, 1.01); // true
ajv.validate(schema, 2); // true
ajv.validate(schema, 2.99); // true
ajv.validate(schema, 1); // false
ajv.validate(schema, 3); // false
```


### Keywords for strings

#### `regexp`

This keyword allows to use regular expressions with flags in schemas (the standard `pattern` keyword does not support flags).

This keyword applies only to strings. If the data is not a string, the validation succeeds.

The value of this keyword can be either a string (the result of `regexp.toString()`) or an object with the properties `pattern` and `flags` (the same strings that should be passed to RegExp constructor).

```javascript
var schema = {
  type: 'object',
  properties: {
    foo: { regexp: '/foo/i' },
    bar: { regexp: { pattern: 'bar', flags: 'i' } }
  }
};

var validData = {
  foo: 'Food',
  bar: 'Barmen'
};

var invalidData = {
  foo: 'fog',
  bar: 'bad'
};
```


#### `formatMaximum` / `formatMinimum` and `formatExclusiveMaximum` / `formatExclusiveMinimum`

These keywords allow to define minimum/maximum constraints when the format keyword defines ordering.

These keywords apply only to strings. If the data is not a string, the validation succeeds.

The value of keyword `formatMaximum` (`formatMinimum`) should be a string. This value is the maximum (minimum) allowed value for the data to be valid as determined by `format` keyword. If `format` is not present schema compilation will throw exception.

When this keyword is added, it defines comparison rules for formats `"date"`, `"time"` and `"date-time"`. Custom formats also can have comparison rules. See [addFormat](https://github.com/epoberezkin/ajv#api-addformat) method.

The value of keyword `formatExclusiveMaximum` (`formatExclusiveMinimum`) should be a boolean value. These keyword cannot be used without `formatMaximum` (`formatMinimum`). If this keyword value is equal to `true`, the data to be valid should not be equal to the value in `formatMaximum` (`formatMinimum`) keyword.

```javascript
require('ajv-keywords')(ajv, ['formatMinimum', 'formatMaximum']);

var schema = {
  format: 'date',
  formatMinimum: '2016-02-06',
  formatMaximum: '2016-12-27',
  formatExclusiveMaximum: true
}

var validDataList = ['2016-02-06', '2016-12-26', 1];

var invalidDataList = ['2016-02-05', '2016-12-27', 'abc'];
```


#### `transform`

This keyword allows a string to be modified before validation. 

These keywords apply only to strings. If the data is not a string, the transform is skipped.

There are limitation due to how ajv is written:
- a stand alone string cannot be transformed. ie `data = 'a'; ajv.validate(schema, data);`
- currently cannot work with `ajv-pack`

**Supported options:**
- `trim`: remove whitespace from start and end
- `trimLeft`: remove whitespace from start
- `trimRight`: remove whitespace from end
- `toLowerCase`: case string to all lower case
- `toUpperCase`: case string to all upper case
- `toEnumCase`: case string to match case in schema

Options are applied in the order they are listed.

Note: `toEnumCase` requires that all allowed values are unique when case insensitive.

**Example: multiple options**
```javascript
require('ajv-keywords')(ajv, ['transform']);

var schema = {
  type: 'array',
  items: {
    type:'string',
    transform:['trim','toLowerCase']
  }
};

var data = ['  MixCase  '];
ajv.validate(schema, data);
console.log(data); // ['mixcase']

```

**Example: `enumcase`**
```javascript
require('ajv-keywords')(ajv, ['transform']);

var schema = {
  type: 'array',
  items: {
    type:'string',
    transform:['trim','toEnumCase'],
    enum:['pH']
  }
};

var data = ['ph',' Ph','PH','pH '];
ajv.validate(schema, data);
console.log(data); // ['pH','pH','pH','pH']
```


### Keywords for arrays

#### `uniqueItemProperties`

The keyword allows to check that some properties in array items are unique.

This keyword applies only to arrays. If the data is not an array, the validation succeeds.

The value of this keyword must be an array of strings - property names that should have unique values across all items.

```javascript
var schema = { uniqueItemProperties: [ "id", "name" ] };

var validData = [
  { id: 1 },
  { id: 2 },
  { id: 3 }
];

var invalidData1 = [
  { id: 1 },
  { id: 1 }, // duplicate "id"
  { id: 3 }
];

var invalidData2 = [
  { id: 1, name: "taco" },
  { id: 2, name: "taco" }, // duplicate "name"
  { id: 3, name: "salsa" }
];
```

This keyword is contributed by [@blainesch](https://github.com/blainesch).


### Keywords for objects

#### `allRequired`

This keyword allows to require the presence of all properties used in `properties` keyword in the same schema object.

This keyword applies only to objects. If the data is not an object, the validation succeeds.

The value of this keyword must be boolean.

If the value of the keyword is `false`, the validation succeeds.

If the value of the keyword is `true`, the validation succeeds if the data contains all properties defined in `properties` keyword (in the same schema object).

If the `properties` keyword is not present in the same schema object, schema compilation will throw exception.

```javascript
var schema = {
  properties: {
    foo: {type: 'number'},
    bar: {type: 'number'}
  }
  allRequired: true
};

var validData = { foo: 1, bar: 2 };
var alsoValidData = { foo: 1, bar: 2, baz: 3 };

var invalidDataList = [ {}, { foo: 1 }, { bar: 2 } ];
```


#### `anyRequired`

This keyword allows to require the presence of any (at least one) property from the list.

This keyword applies only to objects. If the data is not an object, the validation succeeds.

The value of this keyword must be an array of strings, each string being a property name. For data object to be valid at least one of the properties in this array should be present in the object.

```javascript
var schema = {
  anyRequired: ['foo', 'bar']
};

var validData = { foo: 1 };
var alsoValidData = { foo: 1, bar: 2 };

var invalidDataList = [ {}, { baz: 3 } ];
```


#### `oneRequired`

This keyword allows to require the presence of only one property from the list.

This keyword applies only to objects. If the data is not an object, the validation succeeds.

The value of this keyword must be an array of strings, each string being a property name. For data object to be valid exactly one of the properties in this array should be present in the object.

```javascript
var schema = {
  oneRequired: ['foo', 'bar']
};

var validData = { foo: 1 };
var alsoValidData = { bar: 2, baz: 3 };

var invalidDataList = [ {}, { baz: 3 }, { foo: 1, bar: 2 } ];
```


#### `patternRequired`

This keyword allows to require the presence of properties that match some pattern(s).

This keyword applies only to objects. If the data is not an object, the validation succeeds.

The value of this keyword should be an array of strings, each string being a regular expression. For data object to be valid each regular expression in this array should match at least one property name in the data object.

If the array contains multiple regular expressions, more than one expression can match the same property name.

```javascript
var schema = { patternRequired: [ 'f.*o', 'b.*r' ] };

var validData = { foo: 1, bar: 2 };
var alsoValidData = { foobar: 3 };

var invalidDataList = [ {}, { foo: 1 }, { bar: 2 } ];
```


#### `prohibited`

This keyword allows to prohibit that any of the properties in the list is present in the object.

This keyword applies only to objects. If the data is not an object, the validation succeeds.

The value of this keyword should be an array of strings, each string being a property name. For data object to be valid none of the properties in this array should be present in the object.

```
var schema = { prohibited: ['foo', 'bar']};

var validData = { baz: 1 };
var alsoValidData = {};

var invalidDataList = [
  { foo: 1 },
  { bar: 2 },
  { foo: 1, bar: 2}
];
```

__Please note__: `{prohibited: ['foo', 'bar']}` is equivalent to `{not: {anyRequired: ['foo', 'bar']}}` (i.e. it has the same validation result for any data).


#### `deepProperties`

This keyword allows to validate deep properties (identified by JSON pointers).

This keyword applies only to objects. If the data is not an object, the validation succeeds.

The value should be an object, where keys are JSON pointers to the data, starting from the current position in data, and the values are JSON schemas. For data object to be valid the value of each JSON pointer should be valid according to the corresponding schema.

```javascript
var schema = {
  type: 'object',
  deepProperties: {
    "/users/1/role": { "enum": ["admin"] }
  }
};

var validData = {
  users: [
    {},
    {
      id: 123,
      role: 'admin'
    }
  ]
};

var alsoValidData = {
  users: {
    "1": {
      id: 123,
      role: 'admin'
    }
  }
};

var invalidData = {
  users: [
    {},
    {
      id: 123,
      role: 'user'
    }
  ]
};

var alsoInvalidData = {
  users: {
    "1": {
      id: 123,
      role: 'user'
    }
  }
};
```


#### `deepRequired`

This keyword allows to check that some deep properties (identified by JSON pointers) are available.

This keyword applies only to objects. If the data is not an object, the validation succeeds.

The value should be an array of JSON pointers to the data, starting from the current position in data. For data object to be valid each JSON pointer should be some existing part of the data.

```javascript
var schema = {
  type: 'object',
  deepRequired: ["/users/1/role"]
};

var validData = {
  users: [
    {},
    {
      id: 123,
      role: 'admin'
    }
  ]
};

var invalidData = {
  users: [
    {},
    {
      id: 123
    }
  ]
};
```

See [json-schema-org/json-schema-spec#203](https://github.com/json-schema-org/json-schema-spec/issues/203#issue-197211916) for an example of the equivalent schema without `deepRequired` keyword.


### Compound keywords

#### `switch` (deprecated)

__Please note__: this keyword is provided to preserve backward compatibility with previous versions of Ajv. It is strongly recommended to use `if`/`then`/`else` keywords instead, as they have been added to the draft-07 of JSON Schema specification.

This keyword allows to perform advanced conditional validation.

The value of the keyword is the array of if/then clauses. Each clause is the object with the following properties:

- `if` (optional) - the value is JSON-schema
- `then` (required) - the value is JSON-schema or boolean
- `continue` (optional) - the value is boolean

The validation process is dynamic; all clauses are executed sequentially in the following way:

1. `if`:
    1.  `if` property is JSON-schema according to which the data is:
        1.  valid => go to step 2.
        2.  invalid => go to the NEXT clause, if this was the last clause the validation of `switch` SUCCEEDS.
    2.  `if` property is absent => go to step 2.
2. `then`:
    1.  `then` property is `true` or it is JSON-schema according to which the data is valid => go to step 3.
    2.  `then` property is `false` or it is JSON-schema according to which the data is invalid => the validation of `switch` FAILS.
3. `continue`:
    1.  `continue` property is `true` => go to the NEXT clause, if this was the last clause the validation of `switch` SUCCEEDS.
    2.  `continue` property is `false` or absent => validation of `switch` SUCCEEDS.

```javascript
require('ajv-keywords')(ajv, 'switch');

var schema = {
  type: 'array',
  items: {
    type: 'integer',
    'switch': [
      { if: { not: { minimum: 1 } }, then: false },
      { if: { maximum: 10 }, then: true },
      { if: { maximum: 100 }, then: { multipleOf: 10 } },
      { if: { maximum: 1000 }, then: { multipleOf: 100 } },
      { then: false }
    ]
  }
};

var validItems = [1, 5, 10, 20, 50, 100, 200, 500, 1000];

var invalidItems = [1, 0, 2000, 11, 57, 123, 'foo'];
```

The above schema is equivalent to (for example):

```javascript
{
  type: 'array',
  items: {
    type: 'integer',
    if: { minimum: 1, maximum: 10 },
    then: true,
    else: {
      if: { maximum: 100 },
      then: { multipleOf: 10 },
      else: {
        if: { maximum: 1000 },
        then: { multipleOf: 100 },
        else: false
      }
    }
  }
}
```


#### `select`/`selectCases`/`selectDefault`

These keywords allow to choose the schema to validate the data based on the value of some property in the validated data.

These keywords must be present in the same schema object (`selectDefault` is optional).

The value of `select` keyword should be a [$data reference](https://github.com/epoberezkin/ajv/tree/5.0.2-beta.0#data-reference) that points to any primitive JSON type (string, number, boolean or null) in the data that is validated. You can also use a constant of primitive type as the value of this keyword (e.g., for debugging purposes).

The value of `selectCases` keyword must be an object where each property name is a possible string representation of the value of `select` keyword and each property value is a corresponding schema (from draft-06 it can be boolean) that must be used to validate the data.

The value of `selectDefault` keyword is a schema (from draft-06 it can be boolean) that must be used to validate the data in case `selectCases` has no key equal to the stringified value of `select` keyword.

The validation succeeds in one of the following cases:
- the validation of data using selected schema succeeds,
- none of the schemas is selected for validation,
- the value of select is undefined (no property in the data that the data reference points to).

If `select` value (in data) is not a primitive type the validation fails.

__Please note__: these keywords require Ajv `$data` option to support [$data reference](https://github.com/epoberezkin/ajv/tree/5.0.2-beta.0#data-reference).


```javascript
require('ajv-keywords')(ajv, 'select');

var schema = {
  type: object,
  required: ['kind'],
  properties: {
    kind: { type: 'string' }
  },
  select: { $data: '0/kind' },
  selectCases: {
    foo: {
      required: ['foo'],
      properties: {
        kind: {},
        foo: { type: 'string' }
      },
      additionalProperties: false
    },
    bar: {
      required: ['bar'],
      properties: {
        kind: {},
        bar: { type: 'number' }
      },
      additionalProperties: false
    }
  },
  selectDefault: {
    propertyNames: {
      not: { enum: ['foo', 'bar'] }
    }
  }
};

var validDataList = [
  { kind: 'foo', foo: 'any' },
  { kind: 'bar', bar: 1 },
  { kind: 'anything_else', not_bar_or_foo: 'any value' }
];

var invalidDataList = [
  { kind: 'foo' }, // no propery foo
  { kind: 'bar' }, // no propery bar
  { kind: 'foo', foo: 'any', another: 'any value' }, // additional property
  { kind: 'bar', bar: 1, another: 'any value' }, // additional property
  { kind: 'anything_else', foo: 'any' } // property foo not allowed
  { kind: 'anything_else', bar: 1 } // property bar not allowed
];
```

__Please note__: the current implementation is BETA. It does not allow using relative URIs in $ref keywords in schemas in `selectCases` and `selectDefault` that point outside of these schemas. The workaround is to use absolute URIs (that can point to any (sub-)schema added to Ajv, including those inside the current root schema where `select` is used). See [tests](https://github.com/epoberezkin/ajv-keywords/blob/v2.0.0/spec/tests/select.json#L314).


### Keywords for all types

#### `dynamicDefaults`

This keyword allows to assign dynamic defaults to properties, such as timestamps, unique IDs etc.

This keyword only works if `useDefaults` options is used and not inside `anyOf` keywords etc., in the same way as [default keyword treated by Ajv](https://github.com/epoberezkin/ajv#assigning-defaults).

The keyword should be added on the object level. Its value should be an object with each property corresponding to a property name, in the same way as in standard `properties` keyword. The value of each property can be:

- an identifier of default function (a string)
- an object with properties `func` (an identifier) and `args` (an object with parameters that will be passed to this function during schema compilation - see examples).

The properties used in `dynamicDefaults` should not be added to `required` keyword (or validation will fail), because unlike `default` this keyword is processed after validation.

There are several predefined dynamic default functions:

- `"timestamp"` - current timestamp in milliseconds
- `"datetime"` - current date and time as string (ISO, valid according to `date-time` format)
- `"date"` - current date as string (ISO, valid according to `date` format)
- `"time"` - current time as string (ISO, valid according to `time` format)
- `"random"` - pseudo-random number in [0, 1) interval
- `"randomint"` - pseudo-random integer number. If string is used as a property value, the function will randomly return 0 or 1. If object `{ func: 'randomint', args: { max: N } }` is used then the default will be an integer number in [0, N) interval.
- `"seq"` - sequential integer number starting from 0. If string is used as a property value, the default sequence will be used. If object `{ func: 'seq', args: { name: 'foo'} }` is used then the sequence with name `"foo"` will be used. Sequences are global, even if different ajv instances are used.

```javascript
var schema = {
  type: 'object',
  dynamicDefaults: {
    ts: 'datetime',
    r: { func: 'randomint', args: { max: 100 } },
    id: { func: 'seq', args: { name: 'id' } }
  },
  properties: {
    ts: {
      type: 'string',
      format: 'date-time'
    },
    r: {
      type: 'integer',
      minimum: 0,
      exclusiveMaximum: 100
    },
    id: {
      type: 'integer',
      minimum: 0
    }
  }
};

var data = {};
ajv.validate(data); // true
data; // { ts: '2016-12-01T22:07:28.829Z', r: 25, id: 0 }

var data1 = {};
ajv.validate(data1); // true
data1; // { ts: '2016-12-01T22:07:29.832Z', r: 68, id: 1 }

ajv.validate(data1); // true
data1; // didn't change, as all properties were defined
```

When using the `useDefaults` option value `"empty"`, properties and items equal to `null` or `""` (empty string) will be considered missing and assigned defaults.  Use the `allOf` [compound keyword](https://github.com/epoberezkin/ajv/blob/master/KEYWORDS.md#compound-keywords) to execute `dynamicDefaults` before validation.

```javascript
var schema = {
  allOf: [
    {
      dynamicDefaults: {
        ts: 'datetime',
        r: { func: 'randomint', args: { min: 5, max: 100 } },
        id: { func: 'seq', args: { name: 'id' } }
      }
    },
    {
      type: 'object',
      properties: {
        ts: {
          type: 'string'
        },
        r: {
          type: 'number',
          minimum: 5,
          exclusiveMaximum: 100
        },
        id: {
          type: 'integer',
          minimum: 0
        }
      }
    }
  ]
};

var data = { ts: '', r: null };
ajv.validate(data); // true
data; // { ts: '2016-12-01T22:07:28.829Z', r: 25, id: 0 }
```

You can add your own dynamic default function to be recognised by this keyword:

```javascript
var uuid = require('uuid');

function uuidV4() { return uuid.v4(); }

var definition = require('ajv-keywords').get('dynamicDefaults').definition;
// or require('ajv-keywords/keywords/dynamicDefaults').definition;
definition.DEFAULTS.uuid = uuidV4;

var schema = {
  dynamicDefaults: { id: 'uuid' },
  properties: { id: { type: 'string', format: 'uuid' } }
};

var data = {};
ajv.validate(schema, data); // true
data; // { id: 'a1183fbe-697b-4030-9bcc-cfeb282a9150' };

var data1 = {};
ajv.validate(schema, data1); // true
data1; // { id: '5b008de7-1669-467a-a5c6-70fa244d7209' }
```

You also can define dynamic default that accepts parameters, e.g. version of uuid:

```javascript
var uuid = require('uuid');

function getUuid(args) {
  var version = 'v' + (arvs && args.v || 4);
  return function() {
    return uuid[version]();
  };
}

var definition = require('ajv-keywords').get('dynamicDefaults').definition;
definition.DEFAULTS.uuid = getUuid;

var schema = {
  dynamicDefaults: {
    id1: 'uuid', // v4
    id2: { func: 'uuid', v: 4 }, // v4
    id3: { func: 'uuid', v: 1 } // v1
  }
};
```


## Security contact

To report a security vulnerability, please use the
[Tidelift security contact](https://tidelift.com/security).
Tidelift will coordinate the fix and disclosure.

Please do NOT report security vulnerabilities via GitHub issues.


## Open-source software support

Ajv-keywords is a part of [Tidelift subscription](https://tidelift.com/subscription/pkg/npm-ajv-keywords?utm_source=npm-ajv-keywords&utm_medium=referral&utm_campaign=readme) - it provides a centralised support to open-source software users, in addition to the support provided by software maintainers.


## License

[MIT](https://github.com/epoberezkin/ajv-keywords/blob/master/LICENSE)


---

These files are compiled dot templates from dot folder.

Do NOT edit them directly, edit the templates and run `npm run build` from main ajv-keywords folder.


---

<p align="center">
  <a href="https://www.algolia.com">
    <img alt="Algolia for JavaScript" src="https://raw.githubusercontent.com/algolia/algoliasearch-client-common/master/banners/javascript.png" >
  </a>

  <h4 align="center">The perfect starting point to integrate <a href="https://algolia.com" target="_blank">Algolia</a> within your JavaScript project</h4>

  <p align="center">
    <a href="https://npmjs.org/package/algoliasearch"><img src="https://img.shields.io/npm/v/algoliasearch.svg?style=flat-square" alt="NPM version"></img></a>
    <a href="http://npm-stat.com/charts.html?package=algoliasearch"><img src="https://img.shields.io/npm/dm/algoliasearch.svg?style=flat-square" alt="NPM downloads"></a>
    <a href="https://www.jsdelivr.com/package/npm/algoliasearch"><img src="https://data.jsdelivr.com/v1/package/npm/algoliasearch/badge" alt="jsDelivr Downloads"></img></a>
    <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg?style=flat-square" alt="License"></a>
  </p>
</p>

<p align="center">
  <a href="https://www.algolia.com/doc/libraries/javascript/" target="_blank">Documentation</a>  •
  <a href="https://www.algolia.com/doc/guides/building-search-ui/what-is-instantsearch/js/" target="_blank">InstantSearch</a>  •
  <a href="https://discourse.algolia.com" target="_blank">Community Forum</a>  •
  <a href="http://stackoverflow.com/questions/tagged/algolia" target="_blank">Stack Overflow</a>  •
  <a href="https://github.com/algolia/algoliasearch-client-javascript/issues" target="_blank">Report a bug</a>  •
  <a href="https://www.algolia.com/doc/libraries/javascript/v5/" target="_blank">FAQ</a>  •
  <a href="https://alg.li/support" target="_blank">Support</a>
</p>

## ✨ Features

- Thin & **minimal low-level HTTP client** to interact with Algolia's API
- Works both on the **browser** and **node.js**
- **UMD and ESM compatible**, you can use it with any module loader
- Built with TypeScript

## 💡 Getting Started

To get started, you first need to install algoliasearch (or any other available API client package).
All of our clients comes with type definition, and are available for both browser and node environments.

### With a package manager

```bash
yarn add algoliasearch@5.23.0
# or
npm install algoliasearch@5.23.0
# or
pnpm add algoliasearch@5.23.0
```

### Without a package manager

Add the following JavaScript snippet to the <head> of your website:

```html
// for the full client
<script src="https://cdn.jsdelivr.net/npm/algoliasearch@5.23.0/dist/algoliasearch.umd.js"></script>

// for the lite client
<script src="https://cdn.jsdelivr.net/npm/algoliasearch@5.23.0/dist/lite/builds/browser.umd.js"></script>
```

### Usage

You can now import the Algolia API client in your project and play with it.

```js
import { algoliasearch } from 'algoliasearch';

const client = algoliasearch('YOUR_APP_ID', 'YOUR_API_KEY');

// or with the lite client
import { liteClient } from 'algoliasearch/lite';

const client = liteClient('YOUR_APP_ID', 'YOUR_API_KEY');
```

For full documentation, visit the **[Algolia JavaScript API Client](https://www.algolia.com/doc/libraries/javascript/v5/methods/search/)**.

## ❓ Troubleshooting

Encountering an issue? Before reaching out to support, we recommend heading to our [FAQ](https://www.algolia.com/doc/libraries/javascript/v5/) where you will find answers for the most common issues and gotchas with the client. You can also open [a GitHub issue](https://github.com/algolia/api-clients-automation/issues/new?assignees=&labels=&projects=&template=Bug_report.md)

## 📄 License

The Algolia JavaScript API Client is an open-sourced software licensed under the [MIT license](LICENSE).


---

_Coming from V1 (or js client v2)?_ Read the [migration guide](https://github.com/algolia/algoliasearch-helper-js/wiki/Migration-guide-:-V1-to-V2) to the new version of the Helper.

_Coming from V2?_ Read the [migration guide](https://github.com/algolia/algoliasearch-helper-js/wiki/Migration-guide-:-V2-to-V3) to the new version of the Helper.

**The JavaScript helper is an advanced library we provide to our users. If you are looking to build a complete search interface, we recommend you to use [InstantSearch](https://www.algolia.com/doc/guides/building-search-ui/what-is-instantsearch/js/). If you want to build an autocomplete menu, see [Autocomplete](https://github.com/algolia/autocomplete).**

# algoliasearch-helper

This module is the companion of the [algolia/algoliasearch-client-javascript](https://github.com/algolia/algoliasearch-client-javascript). It helps you keep track of the search parameters and provides a higher level API.

[See the helper in action](https://community.algolia.com/algoliasearch-helper-js/)

[![Version][version-svg]][package-url] [![License][license-image]][license-url] [![Downloads][downloads-image]][downloads-url] [![jsDelivr Hits][jsdelivr-badge]][jsdelivr-hits]

[license-image]: http://img.shields.io/badge/license-MIT-green.svg?style=flat-square
[license-url]: LICENSE
[downloads-image]: https://img.shields.io/npm/dm/algoliasearch-helper.svg?style=flat-square
[downloads-url]: http://npm-stat.com/charts.html?package=algoliasearch-helper
[version-svg]: https://img.shields.io/npm/v/algoliasearch-helper.svg?style=flat-square
[package-url]: https://npmjs.org/package/algoliasearch-helper
[jsdelivr-badge]: https://data.jsdelivr.com/v1/package/npm/algoliasearch-helper/badge
[jsdelivr-hits]: https://www.jsdelivr.com/package/npm/algoliasearch-helper

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

- [Features](#features)
- [Examples](#examples)
  - [Vanilla JavaScript](#vanilla-javascript)
  - [AngularJS module](#angularjs-module)
- [Helper cheatsheet](#helper-cheatsheet)
  - [Add the helper in your project](#add-the-helper-in-your-project)
  - [Regular `<script>` tag](#regular-script-tag)
  - [With npm](#with-npm)
  - [Init the helper](#init-the-helper)
  - [Helper lifecycle](#helper-lifecycle)
  - [Objects](#objects)
  - [Search](#search)
  - [Events](#events)
  - [Query](#query)
  - [Filtering results](#filtering-results)
  - [Facet utilities](#facet-utilities)
  - [Tags](#tags)
  - [Pagination](#pagination)
  - [Index](#index)
  - [One time query](#one-time-query)
  - [Query parameters](#query-parameters)
  - [Results format](#results-format)
- [Browser support](#browser-support)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## Features

- Search parameters management
- Facets exclusions
- Pagination
- Disjunctive faceting (search on two or more values of the same facet)

## Examples

### Vanilla JavaScript

A small example that uses Browserify to manage modules.

```js
var algoliasearch = require('algoliasearch');
var algoliasearchHelper = require('algoliasearch-helper');

var client = algoliasearch('appId', 'apiKey');

var helper = algoliasearchHelper(client, 'indexName', {
  facets: ['mainCharacterFirstName', 'year'],
  disjunctiveFacets: ['director'],
});

helper.on('result', function (event) {
  console.log(event.results);
});

helper.addDisjunctiveFacetRefinement('director', 'Clint Eastwood');
helper.addDisjunctiveFacetRefinement('director', 'Sofia Coppola');

helper.addNumericRefinement('year', '=', 2003);

// Search for any movie filmed in 2003 and directed by either C. Eastwood or S. Coppola
helper.search();
```

See more examples in the [examples folder](examples/)

### AngularJS module

```js
<script src="https://cdn.jsdelivr.net/algoliasearch/3/algoliasearch.angular.js"></script>
<script src="dist/algoliasearch.helper.min.js"></script>

<script type="text/javascript">
angular.module('searchApp', ['ngSanitize', 'algoliasearch'])
.controller('searchController', ['$scope', '$sce', 'algolia', function($scope, $sce, algolia) {
  var algolia = algolia.Client('applicationId', 'apiKey');
  $scope.q = '';
  $scope.content = null;
  $scope.helper = algoliasearchHelper(algolia, 'indexName', {
    facets: ['type', 'shipping'],
    disjunctiveFacets: ['category', 'manufacturer'],
    hitsPerPage: 5,
  });
  $scope.helper.on('result', function(event) {
    $scope.$apply(function() {
      $scope.content = event.results;
    });
  });
  $scope.toggleRefine = function($event, facet, value) {
    $event.preventDefault();
    $scope.helper.toggleRefine(facet, value).search();
  };
  $scope.$watch('q', function(q) {
    $scope.helper.setQuery(q).search();
  });
  $scope.helper.search();
}]);
</script>
```

You can see the full [Angular example here](https://codepen.io/Algolia/pen/PzZobK)

## Helper cheatsheet

[There is also a complete JSDoc](https://community.algolia.com/algoliasearch-helper-js/reference.html)

### Add the helper in your project

### Regular `<script>` tag

Use our [jsDelivr](http://www.jsdelivr.com/) build:

`<script src="https://cdn.jsdelivr.net/algoliasearch.helper/2/algoliasearch.helper.min.js"></script>`

### With npm

`npm install algoliasearch-helper`

### Init the helper

```js
var helper = algoliasearchHelper(client, 'indexName' /*, parameters*/);
```

### Helper lifecycle

1. modify the parameters of the search (usually through user interactions)<br/> `helper.setQuery('iphone').addFacetRefinement('category', 'phone')`

2. trigger the search (after all the modification have been applied)<br/> `helper.search()`

3. read the results (with the event "result" handler) and update the UI with the results<br/> `helper.on('result', function(event) { updateUI(event.results); });`

4. go back to 1

### Objects

**AlgoliasearchHelper**: the helper. Keeps the state of the search, makes the queries and calls the handlers when an event happen.

**SearchParameters**: the object representing the state of the search. The current state is stored in `helperInstance.state`.

**SearchResults**: the object in which the Algolia answers are transformed into. This object is passed to the result event handler. An example of SearchResults in JSON is available at [the end of this readme](#results-format)

### Search

The search is triggered by the `search()` method.

It takes all the previous modifications to the search and uses them to create the queries to Algolia. The search parameters are immutable.

Example:

```js
var helper = algoliasearchHelper(client, indexName);

// Let's monitor the results with the console
helper.on('result', function (event) {
  console.log(event.results);
});

// Let's make an empty search
// The results are all sorted using the dashboard configuration
helper.search();

// Let's search for "landscape"
helper.setQuery('landscape').search();

// Let's add a category "photo"
// Will make a search with "photo" tag and "landscape" as the query
helper.addTag('photo').search();
```

### Events

The helper is a Node.js [EventEmitter](https://nodejs.org/api/events.html#events_class_events_eventemitter) instance.

`result`: get notified when new results are received. The handler function will receive two objects (`SearchResults` and `SearchParameters`).

`error`: get notified when errors are received from the API.

`change`: get notified when a property has changed in the helper

`search` : get notified when a request is sent to Algolia

#### Listen to the `result` event

```js
helper.on('result', updateTheResults);
```

#### Listen to a `result` event once

```js
helper.once('result', updateTheResults);
```

#### Remove a `result` listener

```js
helper.removeListener('result', updateTheResults);
```

#### Remove all `result` listeners

```js
helper.removeAllListeners('result');
```

All the methods from Node.js [EventEmitter](https://nodejs.org/api/events.html#events_class_events_eventemitter) class are available.

### Query

#### Do a search with the query "fruit"

```javscript
helper.setQuery('fruit').search();
```

### Filtering results

Facets are filters to retrieve a subset of an index having a specific value for a given attribute. First you need to define which attribute will be used as a facet in the dashboard: [https://www.algolia.com/explorer#?tab=display](https://www.algolia.com/explorer#?tab=display)

#### Regular (conjunctive) facets

Refinements are ANDed by default (Conjunctive selection).

##### Facet definition

```js
var helper = algoliasearchHelper(client, indexName, {
  facets: ['ANDFacet'],
});
```

##### Add a facet filter

```js
helper.addFacetRefinement('ANDFacet', 'valueOfANDFacet').search();
```

##### Remove a facet filter

```js
helper.removeFacetRefinement('ANDFacet', 'valueOfANDFacet').search();
```

#### Disjunctive facets

Refinements are ORed by default (Disjunctive selection).

##### Facet definition

```js
var helper = algoliasearchHelper(client, indexName, {
  disjunctiveFacets: ['ORFacet'],
});
```

##### Add a facet filter

```js
helper.addDisjunctiveFacetRefinement('ORFacet', 'valueOfORFacet').search();
```

##### Remove a facet filter

```js
helper.removeDisjunctiveFacetRefinement('ORFacet', 'valueOfORFacet').search();
```

#### Negative facets

Filter so that we do NOT get a given facet

##### Facet definition (same as "AND" facet)

```js
var helper = algoliasearchHelper(client, indexName, {
  facets: ['ANDFacet'],
}).search();
```

##### Exclude a value for a facet

```js
helper.addFacetExclusion('ANDFacet', 'valueOfANDFacetToExclude');
```

##### Remove an exclude from the list of excluded values

```js
helper.removeFacetExclusion('ANDFacet', 'valueOfANDFacetToExclude');
```

#### Numeric facets

Filter over numeric attributes with math operations like `=`, `>`, `<`, `>=`, `<=`. Can be used for numbers and dates (if converted to timestamp)

##### Facet definition

```js
var helper = algoliasearchHelper(client, indexName, {
  disjunctiveFacets: ['numericAttribute'],
});
```

##### Add numeric refinements

```js
helper.addNumericRefinement('numericAttribute', '=', '3').search();
// filter to only the results that match numericAttribute=3
helper.addNumericRefinement('numericAttribute', '=', '4').search();
// filter to only the results that match numericAttribute=3 AND numericAttribute=4

// On another numeric with no previous filter
helper
  .addNumericRefinement('numericAttribute2', '=', ['42', '56', '37'])
  .search();
// filter to only the results that match numericAttribute2=42 OR numericAttribute2=56 OR numericAttribute2=37
```

##### Remove a numeric refinement

```js
helper.removeNumericRefinement('numericAttribute', '=', '3').search();
```

##### Batch numeric filter removal

```js
// for the single operator = on numericAttribute
helper.removeNumericRefinement('numericAttribute', '=').search();
// for all the refinements on numericAttribute
helper.removeNumericRefinement('numericAttribute').search();
```

#### Hierarchical facets

Hierarchical facets are useful to build such navigation menus:

```txt
| products
  > fruits
    > citrus
    | strawberries
    | peaches
    | apples
```

Here, we refined the search this way:

- click on fruits
- click on citrus

##### Usage

To build such menu, you need to use hierarchical faceting:

```javascript
var helper = algoliasearchHelper(client, indexName, {
  hierarchicalFacets: [
    {
      name: 'products',
      attributes: ['categories.lvl0', 'categories.lvl1'],
    },
  ],
});
```

**Requirements:** All the specified `attributes` must be defined in your Algolia settings as attributes for faceting.

Given your objects looks like this:

```json
{
  "objectID": "123",
  "name": "orange",
  "categories": {
    "lvl0": "fruits",
    "lvl1": "fruits > citrus"
  }
}
```

And you refine `products`:

```js
helper.toggleFacetRefinement('products', 'fruits > citrus');
```

You will get a hierarchical presentation of your facet values: a navigation menu of your facet values.

```js
helper.on('result', function (event) {
  console.log(event.results.hierarchicalFacets[0]);
  // {
  //   'name': 'products',
  //   'count': null,
  //   'isRefined': true,
  //   'path': null,
  //   'data': [{
  //     'name': 'fruits',
  //     'path': 'fruits',
  //     'count': 1,
  //     'isRefined': true,
  //     'data': [{
  //       'name': 'citrus',
  //       'path': 'fruits > citrus',
  //       'count': 1,
  //       'isRefined': true,
  //       'data': null
  //     }]
  //   }]
  // }
});
```

To ease navigation, we always:

- provide the root level categories
- provide the current refinement sub categories (`fruits > citrus > *`: n + 1)
- provide the parent refinement (`fruits > citrus` => `fruits`: n -1) categories
- refine the search using the current hierarchical refinement

##### Multiple values per level

Your records can also share multiple categories between one another by using arrays inside your object:

```json
{
  "objectID": "123",
  "name": "orange",
  "categories": {
    "lvl0": ["fruits", "color"],
    "lvl1": ["fruits > citrus", "color > orange"]
  }
},
{
  "objectID": "456",
  "name": "grapefruit",
  "categories": {
    "lvl0": ["fruits", "color", "new"],
    "lvl1": ["fruits > citrus", "color > yellow", "new > citrus"]
  }
}
```

##### Specifying another separator

```js
var helper = algoliasearchHelper(client, indexName, {
  hierarchicalFacets: [
    {
      name: 'products',
      attributes: ['categories.lvl0', 'categories.lvl1'],
      separator: '|',
    },
  ],
});

helper.toggleFacetRefinement('products', 'fruits|citrus');
```

Would mean that your objects look like so:

```json
{
  "objectID": "123",
  "name": "orange",
  "categories": {
    "lvl0": "fruits",
    "lvl1": "fruits|citrus"
  }
}
```

##### Specifying a different sort order for values

The default sort for the hierarchical facet view is: `isRefined:desc (first show refined), name:asc (then sort by name)`.

You can specify a different sort order by using:

```js
var helper = algoliasearchHelper(client, indexName, {
  hierarchicalFacets: [
    {
      name: 'products',
      attributes: ['categories.lvl0', 'categories.lvl1'],
      sortBy: ['count:desc', 'name:asc'], // first show the most common values, then sort by name
    },
  ],
});
```

The available sort tokens are:

- count
- isRefined
- name
- path

##### Restrict results and hierarchical values to non-root level

Let's say you have a lot of levels:

```
- fruits
  - yellow
    - citrus
      - spicy
```

But you only want to get the values starting at "citrus", you can use `rootPath`

You can specify an root path to filter the hierarchical values

```
var helper = algoliasearchHelper(client, indexName, {
  hierarchicalFacets: [{
    name: 'products',
    attributes: ['categories.lvl0', 'categories.lvl1', 'categories.lvl2', 'categories.lvl3'],
    rootPath: 'fruits > yellow > citrus'
  }]
});
```

Having a rootPath will refine the results on it **automatically**.

##### Hide parent level of current parent level

By default the hierarchical facet is going to return the child and parent facet values of the current refinement.

If you do not want to get the parent facet values you can set showParentLevel to false

```js
var helper = algoliasearchHelper(client, indexName, {
  hierarchicalFacets: [
    {
      name: 'products',
      attributes: ['categories.lvl0', 'categories.lvl1'],
      showParentLevel: false,
    },
  ],
});
```

##### Asking for the current breadcrumb

```js
var helper = algoliasearchHelper(client, indexName, {
  hierarchicalFacets: [
    {
      name: 'products',
      attributes: ['categories.lvl0', 'categories.lvl1'],
      separator: '|',
    },
  ],
});

helper.toggleFacetRefinement('products', 'fruits|citrus');
var breadcrumb = helper.getHierarchicalFacetBreadcrumb('products');

console.log(breadcrumb);
// ['fruits', 'citrus']

console.log(breadcrumb.join(' | '));
// 'fruits | citrus'
```

#### Clearing filters

##### Clear all the refinements for all the refined attributes

```js
helper.clearRefinements().search();
```

##### Clear all the refinements for a specific attribute

```js
helper.clearRefinements('ANDFacet').search();
```

##### [ADVANCED] Clear only the exclusions on the "ANDFacet" attribute

```js
helper
  .clearRefinements(function (value, attribute, type) {
    return type === 'exclude' && attribute === 'ANDFacet';
  })
  .search();
```

### Facet utilities

#### Get the values of a facet with the default sort

```js
helper.on('result', function (event) {
  // Get the facet values for the attribute age
  event.results.getFacetValues('age');
  // It will be ordered :
  //  - refined facets first
  //  - then ordered by number of occurence (bigger count -> higher in the list)
  //  - then ordered by name (alphabetically)
});
```

#### Get the values of a facet with a custom sort

```js
helper.on('result', function (event) {
  // Get the facet values for the attribute age
  event.results.getFacetValues('age', { sortBy: ['count:asc'] });
  // It will be ordered by number of occurence (lower number => higher position)
  // Elements that can be sorted : count, name, isRefined
  // Type of sort : 'asc' for ascending order, 'desc' for descending order
});
```

#### Get the facet stats

_This only apply on numeric based facets/attributes._

```js
helper.on('result', function (event) {
  // Get the facet values for the attribute age
  event.results.getFacetStats('age');
});
```

### Tags

Tags are an easy way to do filtering. They are based on a special attribute in the records named `_tags`, which can be a single string value or an array of strings.

#### Add a tag filter for the value "landscape"

```js
helper.addTag('landscape').search();
```

#### Remove a tag filter for the value "landscape"

```js
helper.removeTag('landscape').search();
```

#### Clear all the tags filters

```js
helper.clearTags().search();
```

### Pagination

#### Get the current page

```js
helper.getPage();
```

#### Change page

```js
helper.setPage(3).search();
```

#### Automatic reset to page 0

During a search, changing the parameters will update the result set, which can then change the number of pages in the result set. Therefore, the behavior has been standardized so that any operation that may change the number of page will reset the pagination to page 0.

This may lead to some unexpected behavior. For example:

```js
helper.setPage(4);
helper.getPage(); // 4
helper.setQuery('foo');
helper.getPage(); // 0
```

Non exhaustive list of operations that trigger a reset:

- refinements (conjunctive, exclude, disjunctive, hierarchical, numeric)
- tags
- index (setIndex)
- setQuery
- setHitsPerPage
- setTypoTolerance

### Index

Index can be changed. The common use case is when you have several slaves with different sort order (sort by relevance, price or any other attribute).

#### Change the current index

```js
helper.setIndex('index_orderByPrice').search();
```

#### Get the current index

```js
var currentIndex = helper.getIndex();
```

### One time query

Sometime it's convenient to reuse the current search parameters with small changes without changing the state stored in the helper. That's why there is a function called `searchOnce`. This method does not trigger `change` or `error` events.

In the following, we are using `searchOnce` to fetch only a single element using all the other parameters already set in the search parameters.

#### Using searchOnce with a callback

```js
var state = helper.searchOnce(
  { hitsPerPage: 1 },
  function (error, content, state) {
    // if an error occured it will be passed in error, otherwise its value is null
    // content contains the results formatted as a SearchResults
    // state is the instance of SearchParameters used for this search
  }
);
```

#### Using searchOnce with a promise

```js
var state1 = helper.searchOnce({ hitsPerPage: 1 }).then(function (res) {
  // res contains
  // {
  //   content : SearchResults
  //   state : SearchParameters (the one used for this specific search)
  // }
});
```

### Query parameters

There are lots of other parameters you can set.

#### Set a parameter at the initialization of the helper

```js
var helper = algoliasearchHelper(client, indexName, {
  hitsPerPage: 50,
});
```

#### Set a parameter later

```js
helper.setQueryParameter('hitsPerPage', 20).search();
```

#### List of parameters that can be set

<table cellspacing="0" cellpadding="0" class="params">
  <tbody>
    <tr>
      <td valign="top" class="td1">
        <p class="p1"><span class="s1"><b>Name</b></span></p>
      </td>
      <td valign="top" class="td2">
        <p class="p1"><span class="s1"><b>Type</b></span></p>
      </td>
      <td valign="top" class="td3">
        <p class="p1"><span class="s1"><b>Description</b></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">advancedSyntax</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">boolean</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Enable the advanced syntax.</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/advancedSyntax/">advancedSyntax on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">allowTyposOnNumericTokens</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">boolean</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Should the engine allow typos on numerics.</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/allowTyposOnNumericTokens/">allowTyposOnNumericTokens on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">analytics</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">boolean</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Enable the analytics</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/analytics/">analytics on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">analyticsTags</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">string</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Tag of the query in the analytics.</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/analyticsTags/">analyticsTags on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">aroundLatLng</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">string</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Center of the geo search.</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/aroundLatLng/">aroundLatLng on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">aroundLatLngViaIP</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">boolean</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Center of the search, retrieve from the user IP.</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/aroundLatLngViaIP/">aroundLatLngViaIP on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">aroundPrecision</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">number</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Precision of the geo search.</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/aroundPrecision/">aroundPrecision on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">aroundRadius</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">number</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Radius of the geo search.</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/aroundRadius/">aroundRadius on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">minimumAroundRadius</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">number</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Minimum radius of the geo search.</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/minimumAroundRadius/">minimumAroundRadius on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">attributesToHighlight</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">string</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">List of attributes to highlight</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/attributesToHighlight/">attributesToHighlight on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">attributesToRetrieve</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">string</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">List of attributes to retrieve</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/attributesToRetrieve/">attributesToRetrieve on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">attributesToSnippet</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">string</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">List of attributes to snippet</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/attributesToSnippet/">attributesToSnippet on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">disjunctiveFacets</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">Array.&lt;string&gt;</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p1"><span class="s1">All the declared disjunctive facets</span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">distinct</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">boolean|number</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Remove duplicates based on the index setting attributeForDistinct</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/distinct/">distinct on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">facets</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">Array.&lt;string&gt;</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p1"><span class="s1">All the facets that will be requested to the server</span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">filters</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">string</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p1"><span class="s1">Add filters to the query (similar to WHERE clauses)</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/filters/">filters on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">getRankingInfo</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">integer</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Enable the ranking informations in the response</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/getRankingInfo/">getRankingInfo on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">hitsPerPage</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">number</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Number of hits to be returned by the search API</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/hitsPerPage/">hitsPerPage on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">ignorePlurals</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">boolean</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Should the plurals be ignored</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/ignorePlurals/">ignorePlurals on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">insideBoundingBox</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">string</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Geo search inside a box.</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/insideBoundingBox/">insideBoundingBox on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">insidePolygon</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">string</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Geo search inside a polygon.</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/insidePolygon/">insidePolygon on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">maxValuesPerFacet</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">number</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Number of values for each facetted attribute</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/maxValuesPerFacet/">maxValuesPerFacet on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">minWordSizefor1Typo</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">number</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Number of characters to wait before doing one character replacement.</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/minWordSizefor1Typo/">minWordSizefor1Typo on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">minWordSizefor2Typos</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">number</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Number of characters to wait before doing a second character replacement.</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/minWordSizefor2Typos/">minWordSizefor2Typos on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">optionalWords</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">string</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Add some optional words to those defined in the dashboard</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/optionalWords/">optionalWords on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">page</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">number</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">The current page number</span></p>
        <p class="p5"><span class="s1"><a href="algolia.com/doc/api-reference/api-parameters/page/">page on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">query</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">string</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Query string of the instant search. The empty string is a valid query.</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/query/">query on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">queryType</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">string</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">How the query should be treated by the search engine. Possible values: prefixAll, prefixLast, prefixNone</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/queryType/">queryType on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">removeWordsIfNoResults</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">string</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Possible values are "lastWords" "firstWords" "allOptional" "none" (default)</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/removeWordsIfNoResults/">removeWordsIfNoResults on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">replaceSynonymsInHighlight</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">boolean</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Should the engine replace the synonyms in the highlighted results.</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/replaceSynonymsInHighlight/">replaceSynonymsInHighlight on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">restrictSearchableAttributes</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">string</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Restrict which attribute is searched.</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/restrictSearchableAttributes/">restrictSearchableAttributes on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">synonyms</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">boolean</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Enable the synonyms</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/synonyms/">synonyms on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">tagFilters</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">string</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Contains the tag filters in the raw format of the Algolia API. Setting this parameter is not compatible with the of the add/remove/toggle methods of the tag api.</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/tagFilters/">tagFilters on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">typoTolerance</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">string</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">How the typo tolerance behave in the search engine. Possible values: true, false, min, strict</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/typoTolerance/">typoTolerance on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
  </tbody>
</table>

### Results format

Here is an example of a result object you get with the `result` event.

```js
{
   "hitsPerPage": 10,
   "processingTimeMS": 2,
   "facets": [
      {
         "name": "type",
         "data": {
            "HardGood": 6627,
            "BlackTie": 550,
            "Music": 665,
            "Software": 131,
            "Game": 456,
            "Movie": 1571
         },
         "exhaustive": false
      },
      {
         "exhaustive": false,
         "data": {
            "Free shipping": 5507
         },
         "name": "shipping"
      }
   ],
   "hits": [
      {
         "thumbnailImage": "http://img.bbystatic.com/BestBuy_US/images/products/1688/1688832_54x108_s.gif",
         "_highlightResult": {
            "shortDescription": {
               "matchLevel": "none",
               "value": "Safeguard your PC, Mac, Android and iOS devices with comprehensive Internet protection",
               "matchedWords": []
            },
            "category": {
               "matchLevel": "none",
               "value": "Computer Security Software",
               "matchedWords": []
            },
            "manufacturer": {
               "matchedWords": [],
               "value": "Webroot",
               "matchLevel": "none"
            },
            "name": {
               "value": "Webroot SecureAnywhere Internet Security (3-Device) (1-Year Subscription) - Mac/Windows",
               "matchedWords": [],
               "matchLevel": "none"
            }
         },
         "image": "http://img.bbystatic.com/BestBuy_US/images/products/1688/1688832_105x210_sc.jpg",
         "shipping": "Free shipping",
         "bestSellingRank": 4,
         "shortDescription": "Safeguard your PC, Mac, Android and iOS devices with comprehensive Internet protection",
         "url": "http://www.bestbuy.com/site/webroot-secureanywhere-internet-security-3-devi…d=1219060687969&skuId=1688832&cmp=RMX&ky=2d3GfEmNIzjA0vkzveHdZEBgpPCyMnLTJ",
         "name": "Webroot SecureAnywhere Internet Security (3-Device) (1-Year Subscription) - Mac/Windows",
         "category": "Computer Security Software",
         "salePrice_range": "1 - 50",
         "objectID": "1688832",
         "type": "Software",
         "customerReviewCount": 5980,
         "salePrice": 49.99,
         "manufacturer": "Webroot"
      },
      ....
   ],
   "nbHits": 10000,
   "disjunctiveFacets": [
      {
         "exhaustive": false,
         "data": {
            "5": 183,
            "12": 112,
            "7": 149,
            ...
         },
         "name": "customerReviewCount",
         "stats": {
            "max": 7461,
            "avg": 157.939,
            "min": 1
         }
      },
      {
         "data": {
            "Printer Ink": 142,
            "Wireless Speakers": 60,
            "Point & Shoot Cameras": 48,
            ...
         },
         "name": "category",
         "exhaustive": false
      },
      {
         "exhaustive": false,
         "data": {
            "> 5000": 2,
            "1 - 50": 6524,
            "501 - 2000": 566,
            "201 - 500": 1501,
            "101 - 200": 1360,
            "2001 - 5000": 47
         },
         "name": "salePrice_range"
      },
      {
         "data": {
            "Dynex™": 202,
            "Insignia™": 230,
            "PNY": 72,
            ...
         },
         "name": "manufacturer",
         "exhaustive": false
      }
   ],
   "query": "",
   "nbPages": 100,
   "page": 0,
   "index": "bestbuy"
}
```

## Browser support

This project works on any [ES5](https://en.wikipedia.org/wiki/ECMAScript#5th_Edition) browser, basically >= IE9+.


---

# Changelog

All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.

### [3.0.1](https://github.com/nexdrew/ansi-align/compare/v3.0.0...v3.0.1) (2021-09-27)


### Bug Fixes

* **package:** update string-width to version 4.1.0 ([#52](https://github.com/nexdrew/ansi-align/issues/52)) ([ab5b733](https://github.com/nexdrew/ansi-align/commit/ab5b733b1c30eef87b75e15459f2216db28d7ed3))

<a name="3.0.0"></a>
# [3.0.0](https://github.com/nexdrew/ansi-align/compare/v2.0.0...v3.0.0) (2018-12-17)


### Bug Fixes

* **package:** update string-width to version 3.0.0 ([#50](https://github.com/nexdrew/ansi-align/issues/50)) ([67f0d8f](https://github.com/nexdrew/ansi-align/commit/67f0d8f))


### BREAKING CHANGES

* **package:** Node 4 no longer supported, please update to Node 6+ or use ansi-align@2.0.0



<a name="2.0.0"></a>
# [2.0.0](https://github.com/nexdrew/ansi-align/compare/v1.1.0...v2.0.0) (2017-05-01)


### Features

* ES2015ify, dropping support for Node <4 ([#30](https://github.com/nexdrew/ansi-align/issues/30)) ([7b43f48](https://github.com/nexdrew/ansi-align/commit/7b43f48))


### BREAKING CHANGES

* Node 0.10 or 0.12 no longer supported, please update to Node 4+ or use ansi-align@1.1.0



<a name="1.1.0"></a>
# [1.1.0](https://github.com/nexdrew/ansi-align/compare/v1.0.0...v1.1.0) (2016-06-06)


### Features

* support left-alignment as no-op ([#3](https://github.com/nexdrew/ansi-align/issues/3)) ([e581db6](https://github.com/nexdrew/ansi-align/commit/e581db6))



<a name="1.0.0"></a>
# 1.0.0 (2016-04-30)


### Features

* initial commit ([1914d90](https://github.com/nexdrew/ansi-align/commit/1914d90))


---

# ansi-align

> align-text with ANSI support for CLIs

[![Build Status](https://travis-ci.org/nexdrew/ansi-align.svg?branch=master)](https://travis-ci.org/nexdrew/ansi-align)
[![Coverage Status](https://coveralls.io/repos/github/nexdrew/ansi-align/badge.svg?branch=master)](https://coveralls.io/github/nexdrew/ansi-align?branch=master)
[![Standard Version](https://img.shields.io/badge/release-standard%20version-brightgreen.svg)](https://github.com/conventional-changelog/standard-version)
[![Greenkeeper badge](https://badges.greenkeeper.io/nexdrew/ansi-align.svg)](https://greenkeeper.io/)

Easily center- or right- align a block of text, carefully ignoring ANSI escape codes.

E.g. turn this:

<img width="281" alt="ansi text block no alignment :(" src="https://cloud.githubusercontent.com/assets/1929625/14937509/7c3076dc-0ed7-11e6-8c16-4f6a4ccc8346.png">

Into this:

<img width="278" alt="ansi text block center aligned!" src="https://cloud.githubusercontent.com/assets/1929625/14937510/7c3ca0b0-0ed7-11e6-8f0a-541ca39b6e0a.png">

## Install

```sh
npm install --save ansi-align
```

```js
var ansiAlign = require('ansi-align')
```

## API

### `ansiAlign(text, [opts])`

Align the given text per the line with the greatest [`string-width`](https://github.com/sindresorhus/string-width), returning a new string (or array).

#### Arguments

- `text`: required, string or array

    The text to align. If a string is given, it will be split using either the `opts.split` value or `'\n'` by default. If an array is given, a different array of modified strings will be returned.

- `opts`: optional, object

    Options to change behavior, see below.

#### Options

- `opts.align`: string, default `'center'`

   The alignment mode. Use `'center'` for center-alignment, `'right'` for right-alignment, or `'left'` for left-alignment. Note that the given `text` is assumed to be left-aligned already, so specifying `align: 'left'` just returns the `text` as is (no-op).

- `opts.split`: string or RegExp, default `'\n'`

    The separator to use when splitting the text. Only used if text is given as a string.

- `opts.pad`: string, default `' '`

    The value used to left-pad (prepend to) lines of lesser width. Will be repeated as necessary to adjust alignment to the line with the greatest width.

### `ansiAlign.center(text)`

Alias for `ansiAlign(text, { align: 'center' })`.

### `ansiAlign.right(text)`

Alias for `ansiAlign(text, { align: 'right' })`.

### `ansiAlign.left(text)`

Alias for `ansiAlign(text, { align: 'left' })`, which is a no-op.

## Similar Packages

- [`center-align`](https://github.com/jonschlinkert/center-align): Very close to this package, except it doesn't support ANSI codes.
- [`left-pad`](https://github.com/camwest/left-pad): Great for left-padding but does not support center alignment or ANSI codes.
- Pretty much anything by the [chalk](https://github.com/chalk) team

## License

ISC © Contributors


---

# emoji-regex [![Build status](https://travis-ci.org/mathiasbynens/emoji-regex.svg?branch=master)](https://travis-ci.org/mathiasbynens/emoji-regex)

_emoji-regex_ offers a regular expression to match all emoji symbols (including textual representations of emoji) as per the Unicode Standard.

This repository contains a script that generates this regular expression based on [the data from Unicode v12](https://github.com/mathiasbynens/unicode-12.0.0). Because of this, the regular expression can easily be updated whenever new emoji are added to the Unicode standard.

## Installation

Via [npm](https://www.npmjs.com/):

```bash
npm install emoji-regex
```

In [Node.js](https://nodejs.org/):

```js
const emojiRegex = require('emoji-regex');
// Note: because the regular expression has the global flag set, this module
// exports a function that returns the regex rather than exporting the regular
// expression itself, to make it impossible to (accidentally) mutate the
// original regular expression.

const text = `
\u{231A}: ⌚ default emoji presentation character (Emoji_Presentation)
\u{2194}\u{FE0F}: ↔️ default text presentation character rendered as emoji
\u{1F469}: 👩 emoji modifier base (Emoji_Modifier_Base)
\u{1F469}\u{1F3FF}: 👩🏿 emoji modifier base followed by a modifier
`;

const regex = emojiRegex();
let match;
while (match = regex.exec(text)) {
  const emoji = match[0];
  console.log(`Matched sequence ${ emoji } — code points: ${ [...emoji].length }`);
}
```

Console output:

```
Matched sequence ⌚ — code points: 1
Matched sequence ⌚ — code points: 1
Matched sequence ↔️ — code points: 2
Matched sequence ↔️ — code points: 2
Matched sequence 👩 — code points: 1
Matched sequence 👩 — code points: 1
Matched sequence 👩🏿 — code points: 2
Matched sequence 👩🏿 — code points: 2
```

To match emoji in their textual representation as well (i.e. emoji that are not `Emoji_Presentation` symbols and that aren’t forced to render as emoji by a variation selector), `require` the other regex:

```js
const emojiRegex = require('emoji-regex/text.js');
```

Additionally, in environments which support ES2015 Unicode escapes, you may `require` ES2015-style versions of the regexes:

```js
const emojiRegex = require('emoji-regex/es2015/index.js');
const emojiRegexText = require('emoji-regex/es2015/text.js');
```

## Author

| [![twitter/mathias](https://gravatar.com/avatar/24e08a9ea84deb17ae121074d0f17125?s=70)](https://twitter.com/mathias "Follow @mathias on Twitter") |
|---|
| [Mathias Bynens](https://mathiasbynens.be/) |

## License

_emoji-regex_ is available under the [MIT](https://mths.be/mit) license.


---

# string-width

> Get the visual width of a string - the number of columns required to display it

Some Unicode characters are [fullwidth](https://en.wikipedia.org/wiki/Halfwidth_and_fullwidth_forms) and use double the normal width. [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code) are stripped and doesn't affect the width.

Useful to be able to measure the actual width of command-line output.


## Install

```
$ npm install string-width
```


## Usage

```js
const stringWidth = require('string-width');

stringWidth('a');
//=> 1

stringWidth('古');
//=> 2

stringWidth('\u001B[1m古\u001B[22m');
//=> 2
```


## Related

- [string-width-cli](https://github.com/sindresorhus/string-width-cli) - CLI for this module
- [string-length](https://github.com/sindresorhus/string-length) - Get the real length of a string
- [widest-line](https://github.com/sindresorhus/widest-line) - Get the visual width of the widest line in a string


---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-string-width?utm_source=npm-string-width&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

<div align="center">
	<br>
	<br>
	<img src="media/logo.svg" alt="type-fest" height="300">
	<br>
	<br>
	<b>A collection of essential TypeScript types</b>
	<br>
	<br>
	<br>
	<br>
	<div align="center">
		<p>
			<p>
				<sup>
					<a href="https://github.com/sponsors/sindresorhus">Sindre Sorhus' open source work is supported by the community</a>
				</sup>
			</p>
			<sup>Special thanks to:</sup>
			<br>
			<br>
			<a href="https://standardresume.co/tech">
				<img src="https://sindresorhus.com/assets/thanks/standard-resume-logo.svg" width="180"/>
			</a>
		</p>
	</div>
	<br>
	<hr>
</div>
<br>
<br>

[![](https://img.shields.io/badge/unicorn-approved-ff69b4.svg)](https://giphy.com/gifs/illustration-rainbow-unicorn-26AHG5KGFxSkUWw1i)
[![npm dependents](https://badgen.net/npm/dependents/type-fest)](https://www.npmjs.com/package/type-fest?activeTab=dependents) [![npm downloads](https://badgen.net/npm/dt/type-fest)](https://www.npmjs.com/package/type-fest)

Many of the types here should have been built-in. You can help by suggesting some of them to the [TypeScript project](https://github.com/Microsoft/TypeScript/blob/master/CONTRIBUTING.md).

Either add this package as a dependency or copy-paste the needed types. No credit required. 👌

PR welcome for additional commonly needed types and docs improvements. Read the [contributing guidelines](.github/contributing.md) first.

## Install

```
$ npm install type-fest
```

*Requires TypeScript >=3.4*

## Usage

```ts
import {Except} from 'type-fest';

type Foo = {
	unicorn: string;
	rainbow: boolean;
};

type FooWithoutRainbow = Except<Foo, 'rainbow'>;
//=> {unicorn: string}
```

## API

Click the type names for complete docs.

### Basic

- [`Primitive`](source/basic.d.ts) - Matches any [primitive value](https://developer.mozilla.org/en-US/docs/Glossary/Primitive).
- [`Class`](source/basic.d.ts) - Matches a [`class` constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes).
- [`TypedArray`](source/typed-array.d.ts) - Matches any [typed array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray), like `Uint8Array` or `Float64Array`.
- [`JsonObject`](source/basic.d.ts) - Matches a JSON object.
- [`JsonArray`](source/basic.d.ts) - Matches a JSON array.
- [`JsonValue`](source/basic.d.ts) - Matches any valid JSON value.
- [`ObservableLike`](source/basic.d.ts) - Matches a value that is like an [Observable](https://github.com/tc39/proposal-observable).

### Utilities

- [`Except`](source/except.d.ts) - Create a type from an object type without certain keys. This is a stricter version of [`Omit`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-5.html#the-omit-helper-type).
- [`Mutable`](source/mutable.d.ts) - Create a type that strips `readonly` from all or some of an object's keys. The inverse of `Readonly<T>`.
- [`Merge`](source/merge.d.ts) - Merge two types into a new type. Keys of the second type overrides keys of the first type.
- [`MergeExclusive`](source/merge-exclusive.d.ts) - Create a type that has mutually exclusive keys.
- [`RequireAtLeastOne`](source/require-at-least-one.d.ts) - Create a type that requires at least one of the given keys.
- [`RequireExactlyOne`](source/require-exactly-one.d.ts) - Create a type that requires exactly a single key of the given keys and disallows more.
- [`PartialDeep`](source/partial-deep.d.ts) - Create a deeply optional version of another type. Use [`Partial<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1401-L1406) if you only need one level deep.
- [`ReadonlyDeep`](source/readonly-deep.d.ts) - Create a deeply immutable version of an `object`/`Map`/`Set`/`Array` type. Use [`Readonly<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1415-L1420) if you only need one level deep.
- [`LiteralUnion`](source/literal-union.d.ts) - Create a union type by combining primitive types and literal types without sacrificing auto-completion in IDEs for the literal type part of the union. Workaround for [Microsoft/TypeScript#29729](https://github.com/Microsoft/TypeScript/issues/29729).
- [`Promisable`](source/promisable.d.ts) - Create a type that represents either the value or the value wrapped in `PromiseLike`.
- [`Opaque`](source/opaque.d.ts) - Create an [opaque type](https://codemix.com/opaque-types-in-javascript/).
- [`SetOptional`](source/set-optional.d.ts) - Create a type that makes the given keys optional.
- [`SetRequired`](source/set-required.d.ts) - Create a type that makes the given keys required.
- [`ValueOf`](source/value-of.d.ts) - Create a union of the given object's values, and optionally specify which keys to get the values from.
- [`PromiseValue`](source/promise-value.d.ts) - Returns the type that is wrapped inside a `Promise`.
- [`AsyncReturnType`](source/async-return-type.d.ts) - Unwrap the return type of a function that returns a `Promise`.
- [`ConditionalKeys`](source/conditional-keys.d.ts) - Extract keys from a shape where values extend the given `Condition` type.
- [`ConditionalPick`](source/conditional-pick.d.ts) - Like `Pick` except it selects properties from a shape where the values extend the given `Condition` type.
- [`ConditionalExcept`](source/conditional-except.d.ts) - Like `Omit` except it removes properties from a shape where the values extend the given `Condition` type.
- [`UnionToIntersection`](source/union-to-intersection.d.ts) - Convert a union type to an intersection type.
- [`Stringified`](source/stringified.d.ts) - Create a type with the keys of the given type changed to `string` type.
- [`FixedLengthArray`](source/fixed-length-array.d.ts) - Create a type that represents an array of the given type and length.
- [`IterableElement`](source/iterable-element.d.ts) - Get the element type of an `Iterable`/`AsyncIterable`. For example, an array or a generator.
- [`Entry`](source/entry.d.ts) - Create a type that represents the type of an entry of a collection.
- [`Entries`](source/entries.d.ts) - Create a type that represents the type of the entries of a collection.
- [`SetReturnType`](source/set-return-type.d.ts) - Create a function type with a return type of your choice and the same parameters as the given function type.
- [`Asyncify`](source/asyncify.d.ts) - Create an async version of the given function type.

### Template literal types

*Note:* These require [TypeScript 4.1 or newer](https://devblogs.microsoft.com/typescript/announcing-typescript-4-1/#template-literal-types).

- [`CamelCase`](ts41/camel-case.d.ts) – Convert a string literal to camel-case (`fooBar`).
- [`KebabCase`](ts41/kebab-case.d.ts) – Convert a string literal to kebab-case (`foo-bar`).
- [`PascalCase`](ts41/pascal-case.d.ts) – Converts a string literal to pascal-case (`FooBar`)
- [`SnakeCase`](ts41/snake-case.d.ts) – Convert a string literal to snake-case (`foo_bar`).
- [`DelimiterCase`](ts41/delimiter-case.d.ts) – Convert a string literal to a custom string delimiter casing.
- [`Get`](ts41/get.d.ts) - Get a deeply-nested property from an object using a key path, like [Lodash's `.get()`](https://lodash.com/docs/latest#get) function.

### Miscellaneous

- [`PackageJson`](source/package-json.d.ts) - Type for [npm's `package.json` file](https://docs.npmjs.com/creating-a-package-json-file).
- [`TsConfigJson`](source/tsconfig-json.d.ts) - Type for [TypeScript's `tsconfig.json` file](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) (TypeScript 3.7).

## Declined types

*If we decline a type addition, we will make sure to document the better solution here.*

- [`Diff` and `Spread`](https://github.com/sindresorhus/type-fest/pull/7) - The PR author didn't provide any real-world use-cases and the PR went stale. If you think this type is useful, provide some real-world use-cases and we might reconsider.
- [`Dictionary`](https://github.com/sindresorhus/type-fest/issues/33) - You only save a few characters (`Dictionary<number>` vs `Record<string, number>`) from [`Record`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1429-L1434), which is more flexible and well-known. Also, you shouldn't use an object as a dictionary. We have `Map` in JavaScript now.
- [`SubType`](https://github.com/sindresorhus/type-fest/issues/22) - The type is powerful, but lacks good use-cases and is prone to misuse.
- [`ExtractProperties` and `ExtractMethods`](https://github.com/sindresorhus/type-fest/pull/4) - The types violate the single responsibility principle. Instead, refine your types into more granular type hierarchies.

## Tips

### Built-in types

There are many advanced types most users don't know about.

- [`Partial<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1401-L1406) - Make all properties in `T` optional.
	<details>
	<summary>
			Example
	</summary>

	[Playground](https://www.typescriptlang.org/play/#code/JYOwLgpgTgZghgYwgAgHIHsAmEDC6QzADmyA3gLABQyycADnanALYQBcyAzmFKEQNxUaddFDAcQAV2YAjaIMoBfKlQQAbOJ05osEAIIMAQpOBrsUMkOR1eANziRkCfISKSoD4Pg4ZseAsTIALyW1DS0DEysHADkvvoMMQA0VsKi4sgAzAAMuVaKClY2wPaOknSYDrguADwA0sgQAB6QIJjaANYQAJ7oMDp+LsQAfAAUXd0cdUnI9mo+uv6uANp1ALoAlKHhyGAAFsCcAHTOAW4eYF4gyxNrwbNwago0ypRWp66jH8QcAApwYmAjxq8SWIy2FDCNDA3ToKFBQyIdR69wmfQG1TOhShyBgomQX3w3GQE2Q6IA8jIAFYQBBgI4TTiEs5bTQYsFInrLTbbHZOIlgZDlSqQABqj0kKBC3yINx6a2xfOQwH6o2FVXFaklwSCIUkbQghBAEEwENSfNOlykEGefNe5uhB2O6sgS3GPRmLogmslG1tLxUOKgEDA7hAuydtteryAA)

	```ts
	interface NodeConfig {
			appName: string;
			port: number;
	}

	class NodeAppBuilder {
			private configuration: NodeConfig = {
					appName: 'NodeApp',
					port: 3000
			};

			private updateConfig<Key extends keyof NodeConfig>(key: Key, value: NodeConfig[Key]) {
					this.configuration[key] = value;
			}

			config(config: Partial<NodeConfig>) {
					type NodeConfigKey = keyof NodeConfig;

					for (const key of Object.keys(config) as NodeConfigKey[]) {
							const updateValue = config[key];

							if (updateValue === undefined) {
									continue;
							}

							this.updateConfig(key, updateValue);
					}

					return this;
			}
	}

	// `Partial<NodeConfig>`` allows us to provide only a part of the
	// NodeConfig interface.
	new NodeAppBuilder().config({appName: 'ToDoApp'});
	```
	</details>

- [`Required<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1408-L1413) - Make all properties in `T` required.
	<details>
	<summary>
			Example
	</summary>

	[Playground](https://typescript-play.js.org/?target=6#code/AQ4SwOwFwUwJwGYEMDGNgGED21VQGJZwC2wA3gFCjXAzFJgA2A-AFzADOUckA5gNxUaIYjA4ckvGG07c+g6gF8KQkAgCuEFFDA5O6gEbEwUbLm2ESwABQIixACJIoSdgCUYAR3Vg4MACYAPGYuFvYAfACU5Ko0APRxwADKMBD+wFAAFuh2Vv7OSBlYGdmc8ABu8LHKsRyGxqY4oQT21pTCIHQMjOwA5DAAHgACxAAOjDAAdChYxL0ANLHUouKSMH0AEmAAhJhY6ozpAJ77GTCMjMCiV0ToSAb7UJPPC9WRgrEJwAAqR6MwSRQPFGUFocDgRHYxnEfGAowh-zgUCOwF6KwkUl6tXqJhCeEsxDaS1AXSYfUGI3GUxmc0WSneQA)

	```ts
	interface ContactForm {
			email?: string;
			message?: string;
	}

	function submitContactForm(formData: Required<ContactForm>) {
			// Send the form data to the server.
	}

	submitContactForm({
			email: 'ex@mple.com',
			message: 'Hi! Could you tell me more about…',
	});

	// TypeScript error: missing property 'message'
	submitContactForm({
			email: 'ex@mple.com',
	});
	```
	</details>

- [`Readonly<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1415-L1420) - Make all properties in `T` readonly.
	<details>
	<summary>
			Example
	</summary>

	[Playground](https://typescript-play.js.org/?target=6#code/AQ4UwOwVwW2AZA9gc3mAbmANsA3gKFCOAHkAzMgGkOJABEwAjKZa2kAUQCcvEu32AMQCGAF2FYBIAL4BufDRABLCKLBcywgMZgEKZOoDCiCGSXI8i4hGEwwALmABnUVxXJ57YFgzZHSVF8sT1BpBSItLGEnJz1kAy5LLy0TM2RHACUwYQATEywATwAeAITjU3MAPnkrCJMXLigtUT4AClxgGztKbyDgaX99I1TzAEokr1BRAAslJwA6FIqLAF48TtswHp9MHDla9hJGACswZvmyLjAwAC8wVpm5xZHkUZDaMKIwqyWXYCW0oN4sNlsA1h0ug5gAByACyBQAggAHJHQ7ZBIFoXbzBjMCz7OoQP5YIaJNYQMAAdziCVaALGNSIAHomcAACoFJFgADKWjcSNEwG4vC4ji0wggEEQguiTnMEGALWAV1yAFp8gVgEjeFyuKICvMrCTgVxnst5jtsGC4ljsPNhXxGaAWcAAOq6YRXYDCRg+RWIcA5JSC+kWdCepQ+v3RYCU3RInzRMCGwlpC19NYBW1Ye08R1AA)

	```ts
	enum LogLevel {
			Off,
			Debug,
			Error,
			Fatal
	};

	interface LoggerConfig {
			name: string;
			level: LogLevel;
	}

	class Logger {
			config: Readonly<LoggerConfig>;

			constructor({name, level}: LoggerConfig) {
					this.config = {name, level};
					Object.freeze(this.config);
			}
	}

	const config: LoggerConfig = {
		name: 'MyApp',
		level: LogLevel.Debug
	};

	const logger = new Logger(config);

	// TypeScript Error: cannot assign to read-only property.
	logger.config.level = LogLevel.Error;

	// We are able to edit config variable as we please.
	config.level = LogLevel.Error;
	```
	</details>

- [`Pick<T, K>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1422-L1427) - From `T`, pick a set of properties whose keys are in the union `K`.
	<details>
	<summary>
			Example
	</summary>

	[Playground](https://typescript-play.js.org/?target=6#code/AQ4SwOwFwUwJwGYEMDGNgEE5TCgNugN4BQoZwOUBAXMAM5RyQDmA3KeSFABYCuAtgCMISMHloMmENh04oA9tBjQJjFuzIBfYrOAB6PcADCcGElh1gEGAHcKATwAO6ebyjB5CTNlwFwSxFR0BX5HeToYABNgBDh5fm8cfBg6AHIKG3ldA2BHOOcfFNpUygJ0pAhokr4hETFUgDpswywkggAFUwA3MFtgAF5gQgowKhhVKTYKGuFRcXo1aVZgbTIoJ3RW3xhOmB6+wfbcAGsAHi3kgBpgEtGy4AAfG54BWfqAPnZm4AAlZUj4MAkMA8GAGB4vEgfMlLLw6CwPBA8PYRmMgZVgAC6CgmI4cIommQELwICh8RBgKZKvALh1ur0bHQABR5PYMui0Wk7em2ADaAF0AJS0AASABUALIAGQAogR+Mp3CROCAFBBwVC2ikBpj5CgBIqGjizLA5TAFdAmalImAuqlBRoVQh5HBgEy1eDWfs7J5cjzGYKhroVfpDEhHM4MV6GRR5NN0JrtnRg6BVirTFBeHAKYmYY6QNpdB73LmCJZBlSAXAubtvczeSmQMNSuMbmKNgBlHFgPEUNwusBIPAAQlS1xetTmxT0SDoESgdD0C4aACtHMwxytLrohawgA)

	```ts
	interface Article {
			title: string;
			thumbnail: string;
			content: string;
	}

	// Creates new type out of the `Article` interface composed
	// from the Articles' two properties: `title` and `thumbnail`.
	// `ArticlePreview = {title: string; thumbnail: string}`
	type ArticlePreview = Pick<Article, 'title' | 'thumbnail'>;

	// Render a list of articles using only title and description.
	function renderArticlePreviews(previews: ArticlePreview[]): HTMLElement {
			const articles = document.createElement('div');

			for (const preview of previews) {
					// Append preview to the articles.
			}

			return articles;
	}

	const articles = renderArticlePreviews([
			{
				title: 'TypeScript tutorial!',
				thumbnail: '/assets/ts.jpg'
			}
	]);
	```
	</details>

- [`Record<K, T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1429-L1434) - Construct a type with a set of properties `K` of type `T`.
	<details>
	<summary>
			Example
	</summary>

	[Playground](https://typescript-play.js.org/?target=6#code/AQ4ejYAUHsGcCWAXBMB2dgwGbAKYC2ADgDYwCeeemCaWArgE7ADGMxAhmuQHQBQoYEnJE8wALKEARnkaxEKdMAC8wAOS0kstGuAAfdQBM8ANzxlRjXQbVaWACwC0JPB0NqA3HwGgIwAJJoWozYHCxixnAsjAhStADmwESMMJYo1Fi4HMCIaPEu+MRklHj8gpqyoeHAAKJFFFTAAN4+giDYCIxwSAByHAR4AFw5SDF5Xm2gJBzdfQPD3WPxE5PAlBxdAPLYNQAelgh4aOHDaPQEMowrIAC+3oJ+AMKMrlrAXFhSAFZ4LEhC9g4-0BmA4JBISXgiCkBQABpILrJ5MhUGhYcATGD6Bk4Hh-jNgABrPDkOBlXyQAAq9ngYmJpOAAHcEOCRjAXqwYODfoo6DhakUSph+Uh7GI4P0xER4Cj0OSQGwMP8tP1hgAlX7swwAHgRl2RvIANALSA08ABtAC6AD4VM1Wm0Kow0MMrYaHYJjGYLLJXZb3at1HYnC43Go-QHQDcvA6-JsmEJXARgCDgMYWAhjIYhDAU+YiMAAFIwex0ZmilMITCGF79TLAGRsAgJYAAZRwSEZGzEABFTOZUrJ5Yn+jwnWgeER6HB7AAKJrADpdXqS4ZqYultTG6azVfqHswPBbtauLY7fayQ7HIbAAAMwBuAEoYw9IBq2Ixs9h2eFMOQYPQObALQKJgggABeYhghCIpikkKRpOQRIknAsZUiIeCttECBEP8NSMCkjDDAARMGziuIYxHwYOjDCMBmDNnAuTxA6irdCOBB1Lh5Dqpqn66tISIykawBnOCtqqC0gbjqc9DgpGkxegOliyfJDrRkAA)

	```ts
	// Positions of employees in our company.
	type MemberPosition = 'intern' | 'developer' | 'tech-lead';

	// Interface describing properties of a single employee.
	interface Employee {
			firstName: string;
			lastName: string;
			yearsOfExperience: number;
	}

	// Create an object that has all possible `MemberPosition` values set as keys.
	// Those keys will store a collection of Employees of the same position.
	const team: Record<MemberPosition, Employee[]> = {
			intern: [],
			developer: [],
			'tech-lead': [],
	};

	// Our team has decided to help John with his dream of becoming Software Developer.
	team.intern.push({
		firstName: 'John',
		lastName: 'Doe',
		yearsOfExperience: 0
	});

	// `Record` forces you to initialize all of the property keys.
	// TypeScript Error: "tech-lead" property is missing
	const teamEmpty: Record<MemberPosition, null> = {
			intern: null,
			developer: null,
	};
	```
	</details>

- [`Exclude<T, U>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1436-L1439) - Exclude from `T` those types that are assignable to `U`.
	<details>
	<summary>
			Example
	</summary>

	[Playground](https://typescript-play.js.org/?target=6#code/JYOwLgpgTgZghgYwgAgMrQG7QMIHsQzADmyA3gFDLIAOuUYAXMiAK4A2byAPsgM5hRQJHqwC2AI2gBucgF9y5MAE9qKAEoQAjiwj8AEnBAATNtGQBeZAAooWphu26wAGmS3e93bRC8IASgsAPmRDJRlyAHoI5ABRAA8ENhYjFFYOZGVVZBgoXFFkAAM0zh5+QRBhZhYJaAKAOkjogEkQZAQ4X2QAdwALCFbaemRgXmQtFjhOMFwq9K6ULuB0lk6U+HYwZAxJnQaYFhAEMGB8ZCIIMAAFOjAANR2IK0HGWISklIAedCgsKDwCYgAbQA5M9gQBdVzFQJ+JhiSRQMiUYYwayZCC4VHPCzmSzAspCYEBWxgFhQAZwKC+FpgJ43VwARgADH4ZFQSWSBjcZPJyPtDsdTvxKWBvr8rD1DCZoJ5HPopaYoK4EPhCEQmGKcKriLCtrhgEYkVQVT5Nr4fmZLLZtMBbFZgT0wGBqES6ghbHBIJqoBKFdBWQpjfh+DQbhY2tqiHVsbjLMVkAB+ZAAZiZaeQTHOVxu9ySjxNaujNwDVHNvzqbBGkBAdPoAfkQA)

	```ts
	interface ServerConfig {
		port: null | string | number;
	}

	type RequestHandler = (request: Request, response: Response) => void;

	// Exclude `null` type from `null | string | number`.
	// In case the port is equal to `null`, we will use default value.
	function getPortValue(port: Exclude<ServerConfig['port'], null>): number {
		if (typeof port === 'string') {
			return parseInt(port, 10);
		}

		return port;
	}

	function startServer(handler: RequestHandler, config: ServerConfig): void {
		const server = require('http').createServer(handler);

		const port = config.port === null ? 3000 : getPortValue(config.port);
		server.listen(port);
	}
	```
	</details>

- [`Extract<T, U>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1441-L1444) - Extract from `T` those types that are assignable to `U`.
	<details>
	<summary>
			Example
	</summary>

	[Playground](https://typescript-play.js.org/?target=6#code/CYUwxgNghgTiAEAzArgOzAFwJYHtXzSwEdkQBJYACgEoAueVZAWwCMQYBuAKDDwGcM8MgBF4AXngBlAJ6scESgHIRi6ty5ZUGdoihgEABXZ888AN5d48ANoiAuvUat23K6ihMQ9ATE0BzV3goPy8GZjZOLgBfLi4Aejj4AEEICBwAdz54MAALKFQQ+BxEeAAHY1NgKAwoIKy0grr4DByEUpgccpgMaXgAaxBerCzi+B9-ZulygDouFHRsU1z8kKMYE1RhaqgAHkt4AHkWACt4EAAPbVRgLLWNgBp9gGlBs8uQa6yAUUuYPQwdgNpKM7nh7mMML4CgA+R5WABqUAgpDeVxuhxO1he0jsXGh8EoOBO9COx3BQPo2PBADckaR6IjkSA6PBqTgsMBzPsicdrEC7OJWXSQNwYvFEgAVTS9JLXODpeDpKBZFg4GCoWa8VACIJykAKiQWKy2YQOAioYikCg0OEMDyhRSy4DyxS24KhAAMjyi6gS8AAwjh5OD0iBFHAkJoEOksC1mnkMJq8gUQKDNttKPlnfrwYp3J5XfBHXqoKpfYkAOI4ansTxaeDADmoRSCCBYAbxhC6TDx6rwYHIRX5bScjA4bLJwoDmDwDkfbA9JMrVMVdM1TN69LgkTgwgkchUahqIA)

	```ts
	declare function uniqueId(): number;

	const ID = Symbol('ID');

	interface Person {
		[ID]: number;
		name: string;
		age: number;
	}

	// Allows changing the person data as long as the property key is of string type.
	function changePersonData<
		Obj extends Person,
		Key extends Extract<keyof Person, string>,
		Value extends Obj[Key]
	> (obj: Obj, key: Key, value: Value): void {
		obj[key] = value;
	}

	// Tiny Andrew was born.
	const andrew = {
		[ID]: uniqueId(),
		name: 'Andrew',
		age: 0,
	};

	// Cool, we're fine with that.
	changePersonData(andrew, 'name', 'Pony');

	// Goverment didn't like the fact that you wanted to change your identity.
	changePersonData(andrew, ID, uniqueId());
	```
	</details>

- [`NonNullable<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1446-L1449) - Exclude `null` and `undefined` from `T`.
	<details>
	<summary>
			Example
	</summary>
	Works with <code>strictNullChecks</code> set to <code>true</code>. (Read more <a href="https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-0.html">here</a>)

	[Playground](https://typescript-play.js.org/?target=6#code/C4TwDgpgBACg9gJ2AOQK4FsBGEFQLxQDOwCAlgHYDmUAPlORtrnQwDasDcAUFwPQBU-WAEMkUOADMowqAGNWwwoSgATCBIqlgpOOSjAAFsOBRSy1IQgr9cKJlSlW1mZYQA3HFH68u8xcoBlHA8EACEHJ08Aby4oKDBUTFZSWXjEFEYcAEIALihkXTR2YSSIAB54JDQsHAA+blj4xOTUsHSACkMzPKD3HHDHNQQAGjSkPMqMmoQASh7g-oihqBi4uNIpdraxPAI2VhmVxrX9AzMAOm2ppnwoAA4ABifuE4BfKAhWSyOTuK7CS7pao3AhXF5rV48E4ICDAVAIPT-cGQyG+XTEIgLMJLTx7CAAdygvRCA0iCHaMwarhJOIQjUBSHaACJHk8mYdeLwxtdcVAAOSsh58+lXdr7Dlcq7A3n3J4PEUdADMcspUE53OluAIUGVTx46oAKuAIAFZGQwCYAKIIBCILjUxaDHAMnla+iodjcIA)

	```ts
	type PortNumber = string | number | null;

	/** Part of a class definition that is used to build a server */
	class ServerBuilder {
			portNumber!: NonNullable<PortNumber>;

			port(this: ServerBuilder, port: PortNumber): ServerBuilder {
					if (port == null) {
							this.portNumber = 8000;
					} else {
							this.portNumber = port;
					}

					return this;
			}
	}

	const serverBuilder = new ServerBuilder();

	serverBuilder
			.port('8000')   // portNumber = '8000'
			.port(null)     // portNumber =  8000
			.port(3000);    // portNumber =  3000

	// TypeScript error
	serverBuilder.portNumber = null;
	```
	</details>

- [`Parameters<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1451-L1454) - Obtain the parameters of a function type in a tuple.
	<details>
	<summary>
			Example
	</summary>

	[Playground](https://typescript-play.js.org/?target=6#code/GYVwdgxgLglg9mABAZwBYmMANgUwBQxgAOIUAXIgIZgCeA2gLoCUFAbnDACaIDeAUIkQB6IYgCypSlBxUATrMo1ECsJzgBbLEoipqAc0J7EMKMgDkiHLnU4wp46pwAPHMgB0fAL58+oSLARECEosLAA5ABUYG2QAHgAxJGdpVWREPDdMylk9ZApqemZEAF4APipacrw-CApEgBogkKwAYThwckQwEHUAIxxZJl4BYVEImiIZKF0oZRwiWVdbeygJmThgOYgcGFYcbhqApCJsyhtpWXcR1cnEePBoeDAABVPzgbTixFeFd8uEsClADcIxGiygIFkSEOT3SmTc2VydQeRx+ZxwF2QQ34gkEwDgsnSuFmMBKiAADEDjIhYk1Qm0OlSYABqZnYka4xA1DJZHJYkGc7yCbyeRA+CAIZCzNAYbA4CIAdxg2zJwVCkWirjwMswuEaACYmCCgA)

	```ts
	function shuffle(input: any[]): void {
		// Mutate array randomly changing its' elements indexes.
	}

	function callNTimes<Fn extends (...args: any[]) => any> (func: Fn, callCount: number) {
		// Type that represents the type of the received function parameters.
		type FunctionParameters = Parameters<Fn>;

		return function (...args: FunctionParameters) {
			for (let i = 0; i < callCount; i++) {
				func(...args);
			}
		}
	}

	const shuffleTwice = callNTimes(shuffle, 2);
	```
	</details>

- [`ConstructorParameters<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1456-L1459) - Obtain the parameters of a constructor function type in a tuple.
	<details>
	<summary>
			Example
	</summary>

	[Playground](https://typescript-play.js.org/?target=6#code/MYGwhgzhAECCBOAXAlqApgWQPYBM0mgG8AoaaFRENALmgkXmQDsBzAblOmCycTV4D8teo1YdO3JiICuwRFngAKClWENmLAJRFOZRAAtkEAHQq00ALzlklNBzIBfYk+KhIMAJJTEYJsDQAwmDA+mgAPAAq0GgAHnxMODCKTGgA7tCKxllg8CwQtL4AngDaALraFgB80EWa1SRkAA6MAG5gfNAB4FABPDJyCrQR9tDNyG0dwMGhtBhgjWEiGgA00F70vv4RhY3hEZXVVinpc42KmuJkkv3y8Bly8EPaDWTkhiZd7r3e8LK3llwGCMXGQWGhEOsfH5zJlsrl8p0+gw-goAAo5MAAW3BaHgEEilU0tEhmzQ212BJ0ry4SOg+kg+gBBiMximIGA0nAfAQLGk2N4EAAEgzYcYcnkLsRdDTvNEYkYUKwSdCme9WdM0MYwYhFPSIPpJdTkAAzDKxBUaZX+aAAQgsVmkCTQxuYaBw2ng4Ok8CYcotSu8pMur09iG9vuObxZnx6SN+AyUWTF8MN0CcZE4Ywm5jZHK5aB5fP4iCFIqT4oRRTKRLo6lYVNeAHpG50wOzOe1zHr9NLQ+HoABybsD4HOKXXRA1JCoKhBELmI5pNaB6Fz0KKBAodDYPAgSUTmqYsAALx4m5nC6nW9nGq14KtaEUA9gR9PvuNCjQ9BgACNvcwNBtAcLiAA)

	```ts
	class ArticleModel {
		title: string;
		content?: string;

		constructor(title: string) {
			this.title = title;
		}
	}

	class InstanceCache<T extends (new (...args: any[]) => any)> {
		private ClassConstructor: T;
		private cache: Map<string, InstanceType<T>> = new Map();

		constructor (ctr: T) {
			this.ClassConstructor = ctr;
		}

		getInstance (...args: ConstructorParameters<T>): InstanceType<T> {
			const hash = this.calculateArgumentsHash(...args);

			const existingInstance = this.cache.get(hash);
			if (existingInstance !== undefined) {
				return existingInstance;
			}

			return new this.ClassConstructor(...args);
		}

		private calculateArgumentsHash(...args: any[]): string {
			// Calculate hash.
			return 'hash';
		}
	}

	const articleCache = new InstanceCache(ArticleModel);
	const amazonArticle = articleCache.getInstance('Amazon forests burining!');
	```
	</details>

- [`ReturnType<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1461-L1464) – Obtain the return type of a function type.
	<details>
	<summary>
			Example
	</summary>

	[Playground](https://typescript-play.js.org/?target=6#code/MYGwhgzhAECSAmICmBlJAnAbgS2E6A3gFDTTwD2AcuQC4AW2AdgOYAUAlAFzSbnbyEAvkWFFQkGJSQB3GMVI1sNZNwg10TZgG4S0YOUY0kh1es07d+xmvQBXYDXLpWi5UlMaWAGj0GjJ6BtNdkJdBQYIADpXZGgAXmgYpB1ScOwoq38aeN9DYxoU6GFRKzVoJjUwRjwAYXJbPPRuAFkwAAcAHgAxBodsAx9GWwBbACMMAD4cxhloVraOCyYjdAAzMDxoOut1e0d0UNIZ6WhWSPOwdGYIbiqATwBtAF0uaHudUQB6ACpv6ABpJBINqJdAbADW0Do5BOw3u5R2VTwMHIq2gAANtjZ0bkbHsnFCwJh8ONjHp0EgwEZ4JFoN9PkRVr1FAZoMwkDRYIjqkgOrosepoEgAB7+eAwAV2BxOLy6ACCVxgIrFEoMeOl6AACpcwMMORgIB1JRMiBNWKVdhruJKfOdIpdrtwFddXlzKjyACp3Nq842HaDIbL6BrZBIVGhIpB1EMYSLsmjmtWW-YhAA+qegAAYLKQLQj3ZsEsdccmnGcLor2Dn8xGedHGpEIBzEzspfsfMHDNAANTQACMVaIljV5GQkRA5DYmIpVKQAgAJARO9le33BDXIyi0YuLW2nJFGLqkOvxFB0YPdBSaLZ0IwNzyPkO8-xkGgsLh8Al427a3hWAhXwwHA8EHT5PmgAB1bAQBAANJ24adKWpft72RaBUTgRBUCAj89HAM8xCTaBjggABRQx0DuHJv25P9dCkWRZVIAAiBjoFImpmjlFBgA0NpsjadByDacgIDAEAIAAQmYpjoGYgAZSBsmGPw6DtZiiFA8CoJguDmAQmoZ2QvtUKQLdoAYmBTwgdEiCAA)

	```ts
	/** Provides every element of the iterable `iter` into the `callback` function and stores the results in an array. */
	function mapIter<
			Elem,
			Func extends (elem: Elem) => any,
			Ret extends ReturnType<Func>
	>(iter: Iterable<Elem>, callback: Func): Ret[] {
			const mapped: Ret[] = [];

			for (const elem of iter) {
					mapped.push(callback(elem));
			}

			return mapped;
	}

	const setObject: Set<string> = new Set();
	const mapObject: Map<number, string> = new Map();

	mapIter(setObject, (value: string) => value.indexOf('Foo')); // number[]

	mapIter(mapObject, ([key, value]: [number, string]) => {
			return key % 2 === 0 ? value : 'Odd';
	}); // string[]
	```
	</details>

- [`InstanceType<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1466-L1469) – Obtain the instance type of a constructor function type.
	<details>
	<summary>
			Example
	</summary>

	[Playground](https://typescript-play.js.org/?target=6#code/MYGwhgzhAECSAmICmBlJAnAbgS2E6A3gFDTTwD2AcuQC4AW2AdgOYAUAlAFzSbnbyEAvkWFFQkGJSQB3GMVI1sNZNwg10TZgG4S0YOUY0kh1es07d+xmvQBXYDXLpWi5UlMaWAGj0GjJ6BtNdkJdBQYIADpXZGgAXmgYpB1ScOwoq38aeN9DYxoU6GFRKzVoJjUwRjwAYXJbPPRuAFkwAAcAHgAxBodsAx9GWwBbACMMAD4cxhloVraOCyYjdAAzMDxoOut1e0d0UNIZ6WhWSPOwdGYIbiqATwBtAF0uaHudUQB6ACpv6ABpJBINqJdAbADW0Do5BOw3u5R2VTwMHIq2gAANtjZ0bkbHsnFCwJh8ONjHp0EgwEZ4JFoN9PkRVr1FAZoMwkDRYIjqkgOrosepoEgAB7+eAwAV2BxOLy6ACCVxgIrFEoMeOl6AACpcwMMORgIB1JRMiBNWKVdhruJKfOdIpdrtwFddXlzKjyACp3Nq842HaDIbL6BrZBIVGhIpB1EMYSLsmjmtWW-YhAA+qegAAYLKQLQj3ZsEsdccmnGcLor2Dn8xGedHGpEIBzEzspfsfMHDNAANTQACMVaIljV5GQkRA5DYmIpVKQAgAJARO9le33BDXIyi0YuLW2nJFGLqkOvxFB0YPdBSaLZ0IwNzyPkO8-xkGgsLh8Al427a3hWAhXwwHA8EHT5PmgAB1bAQBAANJ24adKWpft72RaBUTgRBUCAj89HAM8xCTaBjggABRQx0DuHJv25P9dCkWRZVIAAiBjoFImpmjlFBgA0NpsjadByDacgIDAEAIAAQmYpjoGYgAZSBsmGPw6DtZiiFA8CoJguDmAQmoZ2QvtUKQLdoAYmBTwgdEiCAA)

	```ts
	class IdleService {
			doNothing (): void {}
	}

	class News {
			title: string;
			content: string;

			constructor(title: string, content: string) {
					this.title = title;
					this.content = content;
			}
	}

	const instanceCounter: Map<Function, number> = new Map();

	interface Constructor {
			new(...args: any[]): any;
	}

	// Keep track how many instances of `Constr` constructor have been created.
	function getInstance<
			Constr extends Constructor,
			Args extends ConstructorParameters<Constr>
	>(constructor: Constr, ...args: Args): InstanceType<Constr> {
			let count = instanceCounter.get(constructor) || 0;

			const instance = new constructor(...args);

			instanceCounter.set(constructor, count + 1);

			console.log(`Created ${count + 1} instances of ${Constr.name} class`);

			return instance;
	}


	const idleService = getInstance(IdleService);
	// Will log: `Created 1 instances of IdleService class`
	const newsEntry = getInstance(News, 'New ECMAScript proposals!', 'Last month...');
	// Will log: `Created 1 instances of News class`
	```
	</details>

- [`Omit<T, K>`](https://github.com/microsoft/TypeScript/blob/71af02f7459dc812e85ac31365bfe23daf14b4e4/src/lib/es5.d.ts#L1446) – Constructs a type by picking all properties from T and then removing K.
	<details>
	<summary>
			Example
	</summary>

	[Playground](https://typescript-play.js.org/?target=6#code/JYOwLgpgTgZghgYwgAgIImAWzgG2QbwChlks4BzCAVShwC5kBnMKUcgbmKYAcIFgIjBs1YgOXMpSFMWbANoBdTiW5woFddwAW0kfKWEAvoUIB6U8gDCUCHEiNkICAHdkYAJ69kz4GC3JcPG4oAHteKDABBxCYNAxsPFBIWEQUCAAPJG4wZABySUFcgJAAEzMLXNV1ck0dIuCw6EjBADpy5AB1FAQ4EGQAV0YUP2AHDy8wEOQbUugmBLwtEIA3OcmQnEjuZBgQqE7gAGtgZAhwKHdkHFGwNvGUdDIcAGUliIBJEF3kAF5kAHlML4ADyPBIAGjyBUYRQAPnkqho4NoYQA+TiEGD9EAISIhPozErQMG4AASK2gn2+AApek9pCSXm8wFSQooAJQMUkAFQAsgAZACiOAgmDOOSIJAQ+OYyGl4DgoDmf2QJRCCH6YvALQQNjsEGFovF1NyJWAy1y7OUyHMyE+yRAuFImG4Iq1YDswHxbRINjA-SgfXlHqVUE4xiAA)

	```ts
	interface Animal {
			imageUrl: string;
			species: string;
			images: string[];
			paragraphs: string[];
	}

	// Creates new type with all properties of the `Animal` interface
	// except 'images' and 'paragraphs' properties. We can use this
	// type to render small hover tooltip for a wiki entry list.
	type AnimalShortInfo = Omit<Animal, 'images' | 'paragraphs'>;

	function renderAnimalHoverInfo (animals: AnimalShortInfo[]): HTMLElement {
			const container =  document.createElement('div');
			// Internal implementation.
			return container;
	}
	```
	</details>

- [`Uppercase<S extends string>`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-1.html#template-literal-types) - Transforms every character in a string into uppercase.
	<details>
	<summary>
		Example
	</summary>

	```ts
	type T = Uppercase<'hello'>;  // 'HELLO'

	type T2 = Uppercase<'foo' | 'bar'>;  // 'FOO' | 'BAR'

	type T3<S extends string> = Uppercase<`aB${S}`>;
	type T4 = T30<'xYz'>;  // 'ABXYZ'

	type T5 = Uppercase<string>;  // string
	type T6 = Uppercase<any>;  // any
	type T7 = Uppercase<never>;  // never
	type T8 = Uppercase<42>;  // Error, type 'number' does not satisfy the constraint 'string'
	```
	</details>

- [`Lowercase<S extends string>`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-1.html#template-literal-types) - Transforms every character in a string into lowercase.
	<details>
	<summary>
		Example
	</summary>

	```ts
	type T = Lowercase<'HELLO'>;  // 'hello'

	type T2 = Lowercase<'FOO' | 'BAR'>;  // 'foo' | 'bar'

	type T3<S extends string> = Lowercase<`aB${S}`>;
	type T4 = T32<'xYz'>;  // 'abxyz'

	type T5 = Lowercase<string>;  // string
	type T6 = Lowercase<any>;  // any
	type T7 = Lowercase<never>;  // never
	type T8 = Lowercase<42>;  // Error, type 'number' does not satisfy the constraint 'string'
	```
	</details>

- [`Capitalize<S extends string>`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-1.html#template-literal-types) - Transforms the first character in a string into uppercase.
	<details>
	<summary>
		Example
	</summary>

	```ts
	type T = Capitalize<'hello'>;  // 'Hello'

	type T2 = Capitalize<'foo' | 'bar'>;  // 'Foo' | 'Bar'

	type T3<S extends string> = Capitalize<`aB${S}`>;
	type T4 = T32<'xYz'>;  // 'ABxYz'

	type T5 = Capitalize<string>;  // string
	type T6 = Capitalize<any>;  // any
	type T7 = Capitalize<never>;  // never
	type T8 = Capitalize<42>;  // Error, type 'number' does not satisfy the constraint 'string'
	```
	</details>

- [`Uncapitalize<S extends string>`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-1.html#template-literal-types) - Transforms the first character in a string into lowercase.
	<details>
	<summary>
		Example
	</summary>

	```ts
	type T = Uncapitalize<'Hello'>;  // 'hello'

	type T2 = Uncapitalize<'Foo' | 'Bar'>;  // 'foo' | 'bar'

	type T3<S extends string> = Uncapitalize<`AB${S}`>;
	type T4 = T30<'xYz'>;  // 'aBxYz'

	type T5 = Uncapitalize<string>;  // string
	type T6 = Uncapitalize<any>;  // any
	type T7 = Uncapitalize<never>;  // never
	type T8 = Uncapitalize<42>;  // Error, type 'number' does not satisfy the constraint 'string'
	```
	</details>

You can find some examples in the [TypeScript docs](https://www.typescriptlang.org/docs/handbook/advanced-types.html#predefined-conditional-types).

## Maintainers

- [Sindre Sorhus](https://github.com/sindresorhus)
- [Jarek Radosz](https://github.com/CvX)
- [Dimitri Benin](https://github.com/BendingBender)
- [Pelle Wessman](https://github.com/voxpelli)

## License

(MIT OR CC0-1.0)

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-type-fest?utm_source=npm-type-fest&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

# ansi-escapes

> [ANSI escape codes](http://www.termsys.demon.co.uk/vtansi.htm) for manipulating the terminal

## Install

```
$ npm install ansi-escapes
```

## Usage

```js
const ansiEscapes = require('ansi-escapes');

// Moves the cursor two rows up and to the left
process.stdout.write(ansiEscapes.cursorUp(2) + ansiEscapes.cursorLeft);
//=> '\u001B[2A\u001B[1000D'
```

## API

### cursorTo(x, y?)

Set the absolute position of the cursor. `x0` `y0` is the top left of the screen.

### cursorMove(x, y?)

Set the position of the cursor relative to its current position.

### cursorUp(count)

Move cursor up a specific amount of rows. Default is `1`.

### cursorDown(count)

Move cursor down a specific amount of rows. Default is `1`.

### cursorForward(count)

Move cursor forward a specific amount of columns. Default is `1`.

### cursorBackward(count)

Move cursor backward a specific amount of columns. Default is `1`.

### cursorLeft

Move cursor to the left side.

### cursorSavePosition

Save cursor position.

### cursorRestorePosition

Restore saved cursor position.

### cursorGetPosition

Get cursor position.

### cursorNextLine

Move cursor to the next line.

### cursorPrevLine

Move cursor to the previous line.

### cursorHide

Hide cursor.

### cursorShow

Show cursor.

### eraseLines(count)

Erase from the current cursor position up the specified amount of rows.

### eraseEndLine

Erase from the current cursor position to the end of the current line.

### eraseStartLine

Erase from the current cursor position to the start of the current line.

### eraseLine

Erase the entire current line.

### eraseDown

Erase the screen from the current line down to the bottom of the screen.

### eraseUp

Erase the screen from the current line up to the top of the screen.

### eraseScreen

Erase the screen and move the cursor the top left position.

### scrollUp

Scroll display up one line.

### scrollDown

Scroll display down one line.

### clearScreen

Clear the terminal screen. (Viewport)

### clearTerminal

Clear the whole terminal, including scrollback buffer. (Not just the visible part of it)

### beep

Output a beeping sound.

### link(text, url)

Create a clickable link.

[Supported terminals.](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda) Use [`supports-hyperlinks`](https://github.com/jamestalmage/supports-hyperlinks) to detect link support.

### image(filePath, options?)

Display an image.

*Currently only supported on iTerm2 >=3*

See [term-img](https://github.com/sindresorhus/term-img) for a higher-level module.

#### input

Type: `Buffer`

Buffer of an image. Usually read in with `fs.readFile()`.

#### options

Type: `object`

##### width
##### height

Type: `string | number`

The width and height are given as a number followed by a unit, or the word "auto".

- `N`: N character cells.
- `Npx`: N pixels.
- `N%`: N percent of the session's width or height.
- `auto`: The image's inherent size will be used to determine an appropriate dimension.

##### preserveAspectRatio

Type: `boolean`\
Default: `true`

### iTerm.setCwd(path?)

Type: `string`\
Default: `process.cwd()`

[Inform iTerm2](https://www.iterm2.com/documentation-escape-codes.html) of the current directory to help semantic history and enable [Cmd-clicking relative paths](https://coderwall.com/p/b7e82q/quickly-open-files-in-iterm-with-cmd-click).

### iTerm.annotation(message, options?)

Creates an escape code to display an "annotation" in iTerm2.

An annotation looks like this when shown:

<img src="https://user-images.githubusercontent.com/924465/64382136-b60ac700-cfe9-11e9-8a35-9682e8dc4b72.png" width="500">

See the [iTerm Proprietary Escape Codes documentation](https://iterm2.com/documentation-escape-codes.html) for more information.

#### message

Type: `string`

The message to display within the annotation.

The `|` character is disallowed and will be stripped.

#### options

Type: `object`

##### length

Type: `number`\
Default: The remainder of the line

Nonzero number of columns to annotate.

##### x

Type: `number`\
Default: Cursor position

Starting X coordinate.

Must be used with `y` and `length`.

##### y

Type: `number`\
Default: Cursor position

Starting Y coordinate.

Must be used with `x` and `length`.

##### isHidden

Type: `boolean`\
Default: `false`

Create a "hidden" annotation.

Annotations created this way can be shown using the "Show Annotations" iTerm command.

## Related

- [ansi-styles](https://github.com/chalk/ansi-styles) - ANSI escape codes for styling strings in the terminal

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-ansi-escapes?utm_source=npm-ansi-escapes&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

ansi-html [![NPM version](https://badge.fury.io/js/ansi-html-community.svg)](http://badge.fury.io/js/ansi-html) [![Build Status](https://app.travis-ci.com/mahdyar/ansi-html-community.svg?branch=master)](https://app.travis-ci.com/mahdyar/ansi-html-community)
=========
An elegant lib that converts the chalked (ANSI) text to HTML.

# Coverage
- All styles of [chalk](https://github.com/sindresorhus/chalk) (100%) and [colors](https://github.com/Marak/colors.js).
- There are over **150** randomized test cases under `test`.

# Installation
```
$ npm install ansi-html-community
```

# Usage
```javascript
var ansiHTML = require('ansi-html-community');
var str = ansiHTML('[ANSI_TEXT]');
```

e.g.:
```javascript
var chalk = require('chalk');

var str = chalk.bold.red('foo') + ' bar';
console.log('[ANSI]', str)
console.log('[HTML]', ansiHTML(str));
```

See complete examples under `test` / `examples` directory.

# Set Colors
```javascript
ansiHTML.setColors({
  reset: ['555', '666'], // FOREGROUND-COLOR or [FOREGROUND-COLOR] or [, BACKGROUND-COLOR] or [FOREGROUND-COLOR, BACKGROUND-COLOR]
  black: 'aaa',	// String
  red: 'bbb',
  green: 'ccc',
  yellow: 'ddd',
  blue: 'eee',
  magenta: 'fff',
  cyan: '999',
  lightgrey: '888',
  darkgrey: '777'
});
```

# Reset
```javascript
ansiHTML.reset();
```

# Exposed Tags
```javascript
var openTags = ansiHTML.tags.open;
var closeTags = ansiHTML.tags.close;
```

# Test
```
$ npm install -l
$ npm test
```


---

# ansi-regex

> Regular expression for matching [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code)


## Install

```
$ npm install ansi-regex
```


## Usage

```js
const ansiRegex = require('ansi-regex');

ansiRegex().test('\u001B[4mcake\u001B[0m');
//=> true

ansiRegex().test('cake');
//=> false

'\u001B[4mcake\u001B[0m'.match(ansiRegex());
//=> ['\u001B[4m', '\u001B[0m']

'\u001B[4mcake\u001B[0m'.match(ansiRegex({onlyFirst: true}));
//=> ['\u001B[4m']

'\u001B]8;;https://github.com\u0007click\u001B]8;;\u0007'.match(ansiRegex());
//=> ['\u001B]8;;https://github.com\u0007', '\u001B]8;;\u0007']
```


## API

### ansiRegex(options?)

Returns a regex for matching ANSI escape codes.

#### options

Type: `object`

##### onlyFirst

Type: `boolean`<br>
Default: `false` *(Matches any ANSI escape codes in a string)*

Match only the first ANSI escape.


## FAQ

### Why do you test for codes not in the ECMA 48 standard?

Some of the codes we run as a test are codes that we acquired finding various lists of non-standard or manufacturer specific codes. We test for both standard and non-standard codes, as most of them follow the same or similar format and can be safely matched in strings without the risk of removing actual string content. There are a few non-standard control codes that do not follow the traditional format (i.e. they end in numbers) thus forcing us to exclude them from the test because we cannot reliably match them.

On the historical side, those ECMA standards were established in the early 90's whereas the VT100, for example, was designed in the mid/late 70's. At that point in time, control codes were still pretty ungoverned and engineers used them for a multitude of things, namely to activate hardware ports that may have been proprietary. Somewhere else you see a similar 'anarchy' of codes is in the x86 architecture for processors; there are a ton of "interrupts" that can mean different things on certain brands of processors, most of which have been phased out.


## Maintainers

- [Sindre Sorhus](https://github.com/sindresorhus)
- [Josh Junon](https://github.com/qix-)


---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-ansi-regex?utm_source=npm-ansi-regex&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

# ansi-styles [![Build Status](https://travis-ci.org/chalk/ansi-styles.svg?branch=master)](https://travis-ci.org/chalk/ansi-styles)

> [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors_and_Styles) for styling strings in the terminal

You probably want the higher-level [chalk](https://github.com/chalk/chalk) module for styling your strings.

<img src="screenshot.svg" width="900">

## Install

```
$ npm install ansi-styles
```

## Usage

```js
const style = require('ansi-styles');

console.log(`${style.green.open}Hello world!${style.green.close}`);


// Color conversion between 16/256/truecolor
// NOTE: If conversion goes to 16 colors or 256 colors, the original color
//       may be degraded to fit that color palette. This means terminals
//       that do not support 16 million colors will best-match the
//       original color.
console.log(style.bgColor.ansi.hsl(120, 80, 72) + 'Hello world!' + style.bgColor.close);
console.log(style.color.ansi256.rgb(199, 20, 250) + 'Hello world!' + style.color.close);
console.log(style.color.ansi16m.hex('#abcdef') + 'Hello world!' + style.color.close);
```

## API

Each style has an `open` and `close` property.

## Styles

### Modifiers

- `reset`
- `bold`
- `dim`
- `italic` *(Not widely supported)*
- `underline`
- `inverse`
- `hidden`
- `strikethrough` *(Not widely supported)*

### Colors

- `black`
- `red`
- `green`
- `yellow`
- `blue`
- `magenta`
- `cyan`
- `white`
- `blackBright` (alias: `gray`, `grey`)
- `redBright`
- `greenBright`
- `yellowBright`
- `blueBright`
- `magentaBright`
- `cyanBright`
- `whiteBright`

### Background colors

- `bgBlack`
- `bgRed`
- `bgGreen`
- `bgYellow`
- `bgBlue`
- `bgMagenta`
- `bgCyan`
- `bgWhite`
- `bgBlackBright` (alias: `bgGray`, `bgGrey`)
- `bgRedBright`
- `bgGreenBright`
- `bgYellowBright`
- `bgBlueBright`
- `bgMagentaBright`
- `bgCyanBright`
- `bgWhiteBright`

## Advanced usage

By default, you get a map of styles, but the styles are also available as groups. They are non-enumerable so they don't show up unless you access them explicitly. This makes it easier to expose only a subset in a higher-level module.

- `style.modifier`
- `style.color`
- `style.bgColor`

###### Example

```js
console.log(style.color.green.open);
```

Raw escape codes (i.e. without the CSI escape prefix `\u001B[` and render mode postfix `m`) are available under `style.codes`, which returns a `Map` with the open codes as keys and close codes as values.

###### Example

```js
console.log(style.codes.get(36));
//=> 39
```

## [256 / 16 million (TrueColor) support](https://gist.github.com/XVilka/8346728)

`ansi-styles` uses the [`color-convert`](https://github.com/Qix-/color-convert) package to allow for converting between various colors and ANSI escapes, with support for 256 and 16 million colors.

The following color spaces from `color-convert` are supported:

- `rgb`
- `hex`
- `keyword`
- `hsl`
- `hsv`
- `hwb`
- `ansi`
- `ansi256`

To use these, call the associated conversion function with the intended output, for example:

```js
style.color.ansi.rgb(100, 200, 15); // RGB to 16 color ansi foreground code
style.bgColor.ansi.rgb(100, 200, 15); // RGB to 16 color ansi background code

style.color.ansi256.hsl(120, 100, 60); // HSL to 256 color ansi foreground code
style.bgColor.ansi256.hsl(120, 100, 60); // HSL to 256 color ansi foreground code

style.color.ansi16m.hex('#C0FFEE'); // Hex (RGB) to 16 million color foreground code
style.bgColor.ansi16m.hex('#C0FFEE'); // Hex (RGB) to 16 million color background code
```

## Related

- [ansi-escapes](https://github.com/sindresorhus/ansi-escapes) - ANSI escape codes for manipulating the terminal

## Maintainers

- [Sindre Sorhus](https://github.com/sindresorhus)
- [Josh Junon](https://github.com/qix-)

## For enterprise

Available as part of the Tidelift Subscription.

The maintainers of `ansi-styles` and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-ansi-styles?utm_source=npm-ansi-styles&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)


---

anymatch [![Build Status](https://travis-ci.org/micromatch/anymatch.svg?branch=master)](https://travis-ci.org/micromatch/anymatch) [![Coverage Status](https://img.shields.io/coveralls/micromatch/anymatch.svg?branch=master)](https://coveralls.io/r/micromatch/anymatch?branch=master)
======
Javascript module to match a string against a regular expression, glob, string,
or function that takes the string as an argument and returns a truthy or falsy
value. The matcher can also be an array of any or all of these. Useful for
allowing a very flexible user-defined config to define things like file paths.

__Note: This module has Bash-parity, please be aware that Windows-style backslashes are not supported as separators. See https://github.com/micromatch/micromatch#backslashes for more information.__


Usage
-----
```sh
npm install anymatch
```

#### anymatch(matchers, testString, [returnIndex], [options])
* __matchers__: (_Array|String|RegExp|Function_)
String to be directly matched, string with glob patterns, regular expression
test, function that takes the testString as an argument and returns a truthy
value if it should be matched, or an array of any number and mix of these types.
* __testString__: (_String|Array_) The string to test against the matchers. If
passed as an array, the first element of the array will be used as the
`testString` for non-function matchers, while the entire array will be applied
as the arguments for function matchers.
* __options__: (_Object_ [optional]_) Any of the [picomatch](https://github.com/micromatch/picomatch#options) options.
    * __returnIndex__: (_Boolean [optional]_) If true, return the array index of
the first matcher that that testString matched, or -1 if no match, instead of a
boolean result.

```js
const anymatch = require('anymatch');

const matchers = [ 'path/to/file.js', 'path/anyjs/**/*.js', /foo.js$/, string => string.includes('bar') && string.length > 10 ] ;

anymatch(matchers, 'path/to/file.js'); // true
anymatch(matchers, 'path/anyjs/baz.js'); // true
anymatch(matchers, 'path/to/foo.js'); // true
anymatch(matchers, 'path/to/bar.js'); // true
anymatch(matchers, 'bar.js'); // false

// returnIndex = true
anymatch(matchers, 'foo.js', {returnIndex: true}); // 2
anymatch(matchers, 'path/anyjs/foo.js', {returnIndex: true}); // 1

// any picomatc

// using globs to match directories and their children
anymatch('node_modules', 'node_modules'); // true
anymatch('node_modules', 'node_modules/somelib/index.js'); // false
anymatch('node_modules/**', 'node_modules/somelib/index.js'); // true
anymatch('node_modules/**', '/absolute/path/to/node_modules/somelib/index.js'); // false
anymatch('**/node_modules/**', '/absolute/path/to/node_modules/somelib/index.js'); // true

const matcher = anymatch(matchers);
['foo.js', 'bar.js'].filter(matcher);  // [ 'foo.js' ]
anymatch master* ❯

```

#### anymatch(matchers)
You can also pass in only your matcher(s) to get a curried function that has
already been bound to the provided matching criteria. This can be used as an
`Array#filter` callback.

```js
var matcher = anymatch(matchers);

matcher('path/to/file.js'); // true
matcher('path/anyjs/baz.js', true); // 1

['foo.js', 'bar.js'].filter(matcher); // ['foo.js']
```

Changelog
----------
[See release notes page on GitHub](https://github.com/micromatch/anymatch/releases)

- **v3.0:** Removed `startIndex` and `endIndex` arguments. Node 8.x-only.
- **v2.0:** [micromatch](https://github.com/jonschlinkert/micromatch) moves away from minimatch-parity and inline with Bash. This includes handling backslashes differently (see https://github.com/micromatch/micromatch#backslashes for more information).
- **v1.2:** anymatch uses [micromatch](https://github.com/jonschlinkert/micromatch)
for glob pattern matching. Issues with glob pattern matching should be
reported directly to the [micromatch issue tracker](https://github.com/jonschlinkert/micromatch/issues).

License
-------
[ISC](https://raw.github.com/micromatch/anymatch/master/LICENSE)


---

The MIT License (MIT)

Copyright (c) 2021 Vercel, Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# Arg

`arg` is an unopinionated, no-frills CLI argument parser.

## Installation

```bash
npm install arg
```

## Usage

`arg()` takes either 1 or 2 arguments:

1. Command line specification object (see below)
2. Parse options (_Optional_, defaults to `{permissive: false, argv: process.argv.slice(2), stopAtPositional: false}`)

It returns an object with any values present on the command-line (missing options are thus
missing from the resulting object). Arg performs no validation/requirement checking - we
leave that up to the application.

All parameters that aren't consumed by options (commonly referred to as "extra" parameters)
are added to `result._`, which is _always_ an array (even if no extra parameters are passed,
in which case an empty array is returned).

```javascript
const arg = require('arg');

// `options` is an optional parameter
const args = arg(
	spec,
	(options = { permissive: false, argv: process.argv.slice(2) })
);
```

For example:

```console
$ node ./hello.js --verbose -vvv --port=1234 -n 'My name' foo bar --tag qux --tag=qix -- --foobar
```

```javascript
// hello.js
const arg = require('arg');

const args = arg({
	// Types
	'--help': Boolean,
	'--version': Boolean,
	'--verbose': arg.COUNT, // Counts the number of times --verbose is passed
	'--port': Number, // --port <number> or --port=<number>
	'--name': String, // --name <string> or --name=<string>
	'--tag': [String], // --tag <string> or --tag=<string>

	// Aliases
	'-v': '--verbose',
	'-n': '--name', // -n <string>; result is stored in --name
	'--label': '--name' // --label <string> or --label=<string>;
	//     result is stored in --name
});

console.log(args);
/*
{
	_: ["foo", "bar", "--foobar"],
	'--port': 1234,
	'--verbose': 4,
	'--name': "My name",
	'--tag': ["qux", "qix"]
}
*/
```

The values for each key=&gt;value pair is either a type (function or [function]) or a string (indicating an alias).

- In the case of a function, the string value of the argument's value is passed to it,
  and the return value is used as the ultimate value.

- In the case of an array, the only element _must_ be a type function. Array types indicate
  that the argument may be passed multiple times, and as such the resulting value in the returned
  object is an array with all of the values that were passed using the specified flag.

- In the case of a string, an alias is established. If a flag is passed that matches the _key_,
  then the _value_ is substituted in its place.

Type functions are passed three arguments:

1. The parameter value (always a string)
2. The parameter name (e.g. `--label`)
3. The previous value for the destination (useful for reduce-like operations or for supporting `-v` multiple times, etc.)

This means the built-in `String`, `Number`, and `Boolean` type constructors "just work" as type functions.

Note that `Boolean` and `[Boolean]` have special treatment - an option argument is _not_ consumed or passed, but instead `true` is
returned. These options are called "flags".

For custom handlers that wish to behave as flags, you may pass the function through `arg.flag()`:

```javascript
const arg = require('arg');

const argv = [
	'--foo',
	'bar',
	'-ff',
	'baz',
	'--foo',
	'--foo',
	'qux',
	'-fff',
	'qix'
];

function myHandler(value, argName, previousValue) {
	/* `value` is always `true` */
	return 'na ' + (previousValue || 'batman!');
}

const args = arg(
	{
		'--foo': arg.flag(myHandler),
		'-f': '--foo'
	},
	{
		argv
	}
);

console.log(args);
/*
{
	_: ['bar', 'baz', 'qux', 'qix'],
	'--foo': 'na na na na na na na na batman!'
}
*/
```

As well, `arg` supplies a helper argument handler called `arg.COUNT`, which equivalent to a `[Boolean]` argument's `.length`
property - effectively counting the number of times the boolean flag, denoted by the key, is passed on the command line..
For example, this is how you could implement `ssh`'s multiple levels of verbosity (`-vvvv` being the most verbose).

```javascript
const arg = require('arg');

const argv = ['-AAAA', '-BBBB'];

const args = arg(
	{
		'-A': arg.COUNT,
		'-B': [Boolean]
	},
	{
		argv
	}
);

console.log(args);
/*
{
	_: [],
	'-A': 4,
	'-B': [true, true, true, true]
}
*/
```

### Options

If a second parameter is specified and is an object, it specifies parsing options to modify the behavior of `arg()`.

#### `argv`

If you have already sliced or generated a number of raw arguments to be parsed (as opposed to letting `arg`
slice them from `process.argv`) you may specify them in the `argv` option.

For example:

```javascript
const args = arg(
	{
		'--foo': String
	},
	{
		argv: ['hello', '--foo', 'world']
	}
);
```

results in:

```javascript
const args = {
	_: ['hello'],
	'--foo': 'world'
};
```

#### `permissive`

When `permissive` set to `true`, `arg` will push any unknown arguments
onto the "extra" argument array (`result._`) instead of throwing an error about
an unknown flag.

For example:

```javascript
const arg = require('arg');

const argv = [
	'--foo',
	'hello',
	'--qux',
	'qix',
	'--bar',
	'12345',
	'hello again'
];

const args = arg(
	{
		'--foo': String,
		'--bar': Number
	},
	{
		argv,
		permissive: true
	}
);
```

results in:

```javascript
const args = {
	_: ['--qux', 'qix', 'hello again'],
	'--foo': 'hello',
	'--bar': 12345
};
```

#### `stopAtPositional`

When `stopAtPositional` is set to `true`, `arg` will halt parsing at the first
positional argument.

For example:

```javascript
const arg = require('arg');

const argv = ['--foo', 'hello', '--bar'];

const args = arg(
	{
		'--foo': Boolean,
		'--bar': Boolean
	},
	{
		argv,
		stopAtPositional: true
	}
);
```

results in:

```javascript
const args = {
	_: ['hello', '--bar'],
	'--foo': true
};
```

### Errors

Some errors that `arg` throws provide a `.code` property in order to aid in recovering from user error, or to
differentiate between user error and developer error (bug).

##### ARG_UNKNOWN_OPTION

If an unknown option (not defined in the spec object) is passed, an error with code `ARG_UNKNOWN_OPTION` will be thrown:

```js
// cli.js
try {
	require('arg')({ '--hi': String });
} catch (err) {
	if (err.code === 'ARG_UNKNOWN_OPTION') {
		console.log(err.message);
	} else {
		throw err;
	}
}
```

```shell
node cli.js --extraneous true
Unknown or unexpected option: --extraneous
```

# FAQ

A few questions and answers that have been asked before:

### How do I require an argument with `arg`?

Do the assertion yourself, such as:

```javascript
const args = arg({ '--name': String });

if (!args['--name']) throw new Error('missing required argument: --name');
```

# License

Released under the [MIT License](LICENSE.md).


---

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).


## [2.0.1] - 2020-08-29
### Fixed
- Fix issue with `process.argv` when used with interpreters (`coffee`, `ts-node`, etc.), #150.


## [2.0.0] - 2020-08-14
### Changed
- Full rewrite. Now port from python 3.9.0 & more precise following.
  See [doc](./doc) for difference and migration info.
- node.js 10+ required
- Removed most of local docs in favour of original ones.


## [1.0.10] - 2018-02-15
### Fixed
- Use .concat instead of + for arrays, #122.


## [1.0.9] - 2016-09-29
### Changed
- Rerelease after 1.0.8 - deps cleanup.


## [1.0.8] - 2016-09-29
### Changed
- Maintenance (deps bump, fix node 6.5+ tests, coverage report).


## [1.0.7] - 2016-03-17
### Changed
- Teach `addArgument` to accept string arg names. #97, @tomxtobin.


## [1.0.6] - 2016-02-06
### Changed
- Maintenance: moved to eslint & updated CS.


## [1.0.5] - 2016-02-05
### Changed
- Removed lodash dependency to significantly reduce install size.
  Thanks to @mourner.


## [1.0.4] - 2016-01-17
### Changed
- Maintenance: lodash update to 4.0.0.


## [1.0.3] - 2015-10-27
### Fixed
- Fix parse `=` in args: `--examplepath="C:\myfolder\env=x64"`. #84, @CatWithApple.


## [1.0.2] - 2015-03-22
### Changed
- Relaxed lodash version dependency.


## [1.0.1] - 2015-02-20
### Changed
- Changed dependencies to be compatible with ancient nodejs.


## [1.0.0] - 2015-02-19
### Changed
- Maintenance release.
- Replaced `underscore` with `lodash`.
- Bumped version to 1.0.0 to better reflect semver meaning.
- HISTORY.md -> CHANGELOG.md


## [0.1.16] - 2013-12-01
### Changed
- Maintenance release. Updated dependencies and docs.


## [0.1.15] - 2013-05-13
### Fixed
- Fixed #55, @trebor89


## [0.1.14] - 2013-05-12
### Fixed
- Fixed #62, @maxtaco


## [0.1.13] - 2013-04-08
### Changed
- Added `.npmignore` to reduce package size


## [0.1.12] - 2013-02-10
### Fixed
- Fixed conflictHandler (#46), @hpaulj


## [0.1.11] - 2013-02-07
### Added
- Added 70+ tests (ported from python), @hpaulj
- Added conflictHandler, @applepicke
- Added fromfilePrefixChar, @hpaulj

### Fixed
- Multiple bugfixes, @hpaulj


## [0.1.10] - 2012-12-30
### Added
- Added [mutual exclusion](http://docs.python.org/dev/library/argparse.html#mutual-exclusion)
  support, thanks to @hpaulj

### Fixed
- Fixed options check for `storeConst` & `appendConst` actions, thanks to @hpaulj


## [0.1.9] - 2012-12-27
### Fixed
- Fixed option dest interferens with other options (issue #23), thanks to @hpaulj
- Fixed default value behavior with `*` positionals, thanks to @hpaulj
- Improve `getDefault()` behavior, thanks to @hpaulj
- Improve negative argument parsing, thanks to @hpaulj


## [0.1.8] - 2012-12-01
### Fixed
- Fixed parser parents (issue #19), thanks to @hpaulj
- Fixed negative argument parse (issue #20), thanks to @hpaulj


## [0.1.7] - 2012-10-14
### Fixed
- Fixed 'choices' argument parse (issue #16)
- Fixed stderr output (issue #15)


## [0.1.6] - 2012-09-09
### Fixed
- Fixed check for conflict of options (thanks to @tomxtobin)


## [0.1.5] - 2012-09-03
### Fixed
- Fix parser #setDefaults method (thanks to @tomxtobin)


## [0.1.4] - 2012-07-30
### Fixed
- Fixed pseudo-argument support (thanks to @CGamesPlay)
- Fixed addHelp default (should be true), if not set (thanks to @benblank)


## [0.1.3] - 2012-06-27
### Fixed
- Fixed formatter api name: Formatter -> HelpFormatter


## [0.1.2] - 2012-05-29
### Fixed
- Removed excess whitespace in help
- Fixed error reporting, when parcer with subcommands
  called with empty arguments

### Added
- Added basic tests


## [0.1.1] - 2012-05-23
### Fixed
- Fixed line wrapping in help formatter
- Added better error reporting on invalid arguments


## [0.1.0] - 2012-05-16
### Added
- First release.


[2.0.1]: https://github.com/nodeca/argparse/compare/2.0.0...2.0.1
[2.0.0]: https://github.com/nodeca/argparse/compare/1.0.10...2.0.0
[1.0.10]: https://github.com/nodeca/argparse/compare/1.0.9...1.0.10
[1.0.9]: https://github.com/nodeca/argparse/compare/1.0.8...1.0.9
[1.0.8]: https://github.com/nodeca/argparse/compare/1.0.7...1.0.8
[1.0.7]: https://github.com/nodeca/argparse/compare/1.0.6...1.0.7
[1.0.6]: https://github.com/nodeca/argparse/compare/1.0.5...1.0.6
[1.0.5]: https://github.com/nodeca/argparse/compare/1.0.4...1.0.5
[1.0.4]: https://github.com/nodeca/argparse/compare/1.0.3...1.0.4
[1.0.3]: https://github.com/nodeca/argparse/compare/1.0.2...1.0.3
[1.0.2]: https://github.com/nodeca/argparse/compare/1.0.1...1.0.2
[1.0.1]: https://github.com/nodeca/argparse/compare/1.0.0...1.0.1
[1.0.0]: https://github.com/nodeca/argparse/compare/0.1.16...1.0.0
[0.1.16]: https://github.com/nodeca/argparse/compare/0.1.15...0.1.16
[0.1.15]: https://github.com/nodeca/argparse/compare/0.1.14...0.1.15
[0.1.14]: https://github.com/nodeca/argparse/compare/0.1.13...0.1.14
[0.1.13]: https://github.com/nodeca/argparse/compare/0.1.12...0.1.13
[0.1.12]: https://github.com/nodeca/argparse/compare/0.1.11...0.1.12
[0.1.11]: https://github.com/nodeca/argparse/compare/0.1.10...0.1.11
[0.1.10]: https://github.com/nodeca/argparse/compare/0.1.9...0.1.10
[0.1.9]: https://github.com/nodeca/argparse/compare/0.1.8...0.1.9
[0.1.8]: https://github.com/nodeca/argparse/compare/0.1.7...0.1.8
[0.1.7]: https://github.com/nodeca/argparse/compare/0.1.6...0.1.7
[0.1.6]: https://github.com/nodeca/argparse/compare/0.1.5...0.1.6
[0.1.5]: https://github.com/nodeca/argparse/compare/0.1.4...0.1.5
[0.1.4]: https://github.com/nodeca/argparse/compare/0.1.3...0.1.4
[0.1.3]: https://github.com/nodeca/argparse/compare/0.1.2...0.1.3
[0.1.2]: https://github.com/nodeca/argparse/compare/0.1.1...0.1.2
[0.1.1]: https://github.com/nodeca/argparse/compare/0.1.0...0.1.1
[0.1.0]: https://github.com/nodeca/argparse/releases/tag/0.1.0


---

argparse
========

[![Build Status](https://secure.travis-ci.org/nodeca/argparse.svg?branch=master)](http://travis-ci.org/nodeca/argparse)
[![NPM version](https://img.shields.io/npm/v/argparse.svg)](https://www.npmjs.org/package/argparse)

CLI arguments parser for node.js, with [sub-commands](https://docs.python.org/3.9/library/argparse.html#sub-commands) support. Port of python's [argparse](http://docs.python.org/dev/library/argparse.html) (version [3.9.0](https://github.com/python/cpython/blob/v3.9.0rc1/Lib/argparse.py)).

**Difference with original.**

- JS has no keyword arguments support.
  -  Pass options instead: `new ArgumentParser({ description: 'example', add_help: true })`.
- JS has no python's types `int`, `float`, ...
  - Use string-typed names: `.add_argument('-b', { type: 'int', help: 'help' })`.
- `%r` format specifier uses `require('util').inspect()`.

More details in [doc](./doc).


Example
-------

`test.js` file:

```javascript
#!/usr/bin/env node
'use strict';

const { ArgumentParser } = require('argparse');
const { version } = require('./package.json');

const parser = new ArgumentParser({
  description: 'Argparse example'
});

parser.add_argument('-v', '--version', { action: 'version', version });
parser.add_argument('-f', '--foo', { help: 'foo bar' });
parser.add_argument('-b', '--bar', { help: 'bar foo' });
parser.add_argument('--baz', { help: 'baz bar' });

console.dir(parser.parse_args());
```

Display help:

```
$ ./test.js -h
usage: test.js [-h] [-v] [-f FOO] [-b BAR] [--baz BAZ]

Argparse example

optional arguments:
  -h, --help         show this help message and exit
  -v, --version      show program's version number and exit
  -f FOO, --foo FOO  foo bar
  -b BAR, --bar BAR  bar foo
  --baz BAZ          baz bar
```

Parse arguments:

```
$ ./test.js -f=3 --bar=4 --baz 5
{ foo: '3', bar: '4', baz: '5' }
```


API docs
--------

Since this is a port with minimal divergence, there's no separate documentation.
Use original one instead, with notes about difference.

1. [Original doc](https://docs.python.org/3.9/library/argparse.html).
2. [Original tutorial](https://docs.python.org/3.9/howto/argparse.html).
3. [Difference with python](./doc).


argparse for enterprise
-----------------------

Available as part of the Tidelift Subscription

The maintainers of argparse and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-argparse?utm_source=npm-argparse&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)


---

# Array Flatten

[![NPM version][npm-image]][npm-url]
[![NPM downloads][downloads-image]][downloads-url]
[![Build status][travis-image]][travis-url]
[![Test coverage][coveralls-image]][coveralls-url]

> Flatten an array of nested arrays into a single flat array. Accepts an optional depth.

## Installation

```
npm install array-flatten --save
```

## Usage

```javascript
var flatten = require('array-flatten')

flatten([1, [2, [3, [4, [5], 6], 7], 8], 9])
//=> [1, 2, 3, 4, 5, 6, 7, 8, 9]

flatten([1, [2, [3, [4, [5], 6], 7], 8], 9], 2)
//=> [1, 2, 3, [4, [5], 6], 7, 8, 9]

(function () {
  flatten(arguments) //=> [1, 2, 3]
})(1, [2, 3])
```

## License

MIT

[npm-image]: https://img.shields.io/npm/v/array-flatten.svg?style=flat
[npm-url]: https://npmjs.org/package/array-flatten
[downloads-image]: https://img.shields.io/npm/dm/array-flatten.svg?style=flat
[downloads-url]: https://npmjs.org/package/array-flatten
[travis-image]: https://img.shields.io/travis/blakeembrey/array-flatten.svg?style=flat
[travis-url]: https://travis-ci.org/blakeembrey/array-flatten
[coveralls-image]: https://img.shields.io/coveralls/blakeembrey/array-flatten.svg?style=flat
[coveralls-url]: https://coveralls.io/r/blakeembrey/array-flatten?branch=master


---

# array-union [![Build Status](https://travis-ci.org/sindresorhus/array-union.svg?branch=master)](https://travis-ci.org/sindresorhus/array-union)

> Create an array of unique values, in order, from the input arrays


## Install

```
$ npm install array-union
```


## Usage

```js
const arrayUnion = require('array-union');

arrayUnion([1, 1, 2, 3], [2, 3]);
//=> [1, 2, 3]

arrayUnion(['foo', 'foo', 'bar']);
//=> ['foo', 'bar']

arrayUnion(['🐱', '🦄', '🐻'], ['🦄', '🌈']);
//=> ['🐱', '🦄', '🐻', '🌈']

arrayUnion(['🐱', '🦄'], ['🐻', '🦄'], ['🐶', '🌈', '🌈']);
//=> ['🐱', '🦄', '🐻', '🐶', '🌈']
```


## License

MIT © [Sindre Sorhus](https://sindresorhus.com)


---

# Changelog

All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.

## [1.9.0](https://github.com/davidbonnet/astring/compare/v1.8.6...v1.9.0) (2024-08-25)


### Features

* add import-attributes support ([#712](https://github.com/davidbonnet/astring/issues/712)) ([d22c19e](https://github.com/davidbonnet/astring/commit/d22c19ee636e671a8214e062c1165cf56511b40f))

### [1.8.6](https://github.com/davidbonnet/astring/compare/v1.8.5...v1.8.6) (2023-05-30)


### Bug Fixes

* **nullish:** missing parenthesis ([be1aefb](https://github.com/davidbonnet/astring/commit/be1aefb7396c62b8504d15fc21891e4e9317f492)), closes [#695](https://github.com/davidbonnet/astring/issues/695)

### [1.8.5](https://github.com/davidbonnet/astring/compare/v1.8.4...v1.8.5) (2023-05-19)


### Bug Fixes

* **package:** add type conditional export ([36c0029](https://github.com/davidbonnet/astring/commit/36c00290ab8573a56dec118600721a0b87363a8b))
* incorrect nullish coalescing operator precedence ([#694](https://github.com/davidbonnet/astring/issues/694)) ([ad9ce87](https://github.com/davidbonnet/astring/commit/ad9ce8724453bdd497290b464787dde0a86d42ec))

### [1.8.4](https://github.com/davidbonnet/astring/compare/v1.8.3...v1.8.4) (2022-12-21)


### Bug Fixes

* static computed property ([#672](https://github.com/davidbonnet/astring/issues/672)) ([1630853](https://github.com/davidbonnet/astring/commit/16308537294bf0af26f318dc2f4a535814c3cae4))

### [1.8.3](https://github.com/davidbonnet/astring/compare/v1.8.2...v1.8.3) (2022-04-28)


### Bug Fixes

* add missing definitions ([9bb7bcf](https://github.com/davidbonnet/astring/commit/9bb7bcf7ab946bae3aab48b4d4b5edc72b52c208)), closes [#604](https://github.com/davidbonnet/astring/issues/604)

### [1.8.2](https://github.com/davidbonnet/astring/compare/v1.8.1...v1.8.2) (2022-04-28)


### Bug Fixes

* Does not handle undefined private properties ([e6b8ee6](https://github.com/davidbonnet/astring/commit/e6b8ee645d0e9fa3cc6ff4bb30d2a15e2289a88b)), closes [#609](https://github.com/davidbonnet/astring/issues/609)

### [1.8.1](https://github.com/davidbonnet/astring/compare/v1.8.0...v1.8.1) (2021-11-21)

## [1.8.0](https://github.com/davidbonnet/astring/compare/v1.7.6...v1.8.0) (2021-11-21)


### Features

* support ES2022 ([#593](https://github.com/davidbonnet/astring/issues/593)) ([5a327d1](https://github.com/davidbonnet/astring/commit/5a327d1425cdd620377fb52b987880f8af461b62))

### [1.7.6](https://github.com/davidbonnet/astring/compare/v1.7.5...v1.7.6) (2021-11-21)


### Bug Fixes

* wrong precedence of nullish operator ([#590](https://github.com/davidbonnet/astring/issues/590)) ([10fac23](https://github.com/davidbonnet/astring/commit/10fac23a010feedb26d3baaf0e74e2311504e846))

### [1.7.5](https://github.com/davidbonnet/astring/compare/v1.7.4...v1.7.5) (2021-06-02)

### [1.7.4](https://github.com/davidbonnet/astring/compare/v1.7.3...v1.7.4) (2021-04-07)


### Bug Fixes

* **package:** correctly declare module variant ([45203ca](https://github.com/davidbonnet/astring/commit/45203ca5bdd0307cfa3ed9a838d59718de84c6b5)), closes [#505](https://github.com/davidbonnet/astring/issues/505)

### [1.7.3](https://github.com/davidbonnet/astring/compare/v1.7.2...v1.7.3) (2021-04-05)


### Bug Fixes

* **package:** add "exports" field ([e82e873](https://github.com/davidbonnet/astring/commit/e82e87312f51c2cfa1a3c1104091a30352023bc5))

### [1.7.2](https://github.com/davidbonnet/astring/compare/v1.7.1...v1.7.2) (2021-04-05)


### Bug Fixes

* class, ternary, and arrow function miss parentheses ([#504](https://github.com/davidbonnet/astring/issues/504)) ([5037b94](https://github.com/davidbonnet/astring/commit/5037b94b3a447be7d42ae9edeb1e50ef2b2b776c))

### [1.7.1](https://github.com/davidbonnet/astring/compare/v1.7.0...v1.7.1) (2021-04-05)


### Bug Fixes

* **sourcemaps:** missing sourcemaps on debugger statement ([#503](https://github.com/davidbonnet/astring/issues/503)) ([9822a2a](https://github.com/davidbonnet/astring/commit/9822a2a4432ff957ef18c5959f3c71d10f0e361d))

## [1.7.0](https://github.com/davidbonnet/astring/compare/v1.6.2...v1.7.0) (2021-02-06)


### Features

* add typescript definitions ([#346](https://github.com/davidbonnet/astring/issues/346)) ([d2e197a](https://github.com/davidbonnet/astring/commit/d2e197a6b82efeeffc2d7a6fa2f16295c54c8dea))

### [1.6.2](https://github.com/davidbonnet/astring/compare/v1.6.1...v1.6.2) (2021-02-03)


### Bug Fixes

* lower yield operator precedence ([d3af2fc](https://github.com/davidbonnet/astring/commit/d3af2fcd8096401b5618a7e479bfb5b25e129eed))

### [1.6.1](https://github.com/davidbonnet/astring/compare/v1.6.0...v1.6.1) (2021-02-03)


### Bug Fixes

* adjust await and yield operator precendences ([d6166a2](https://github.com/davidbonnet/astring/commit/d6166a256f8e6f1071440b7469b786c18ddf252f)), closes [#435](https://github.com/davidbonnet/astring/issues/435)

## [1.6.0](https://github.com/davidbonnet/astring/compare/v1.5.1...v1.6.0) (2021-01-04)


### Features

* support custom expression precedence ([#427](https://github.com/davidbonnet/astring/issues/427)) ([76ce709](https://github.com/davidbonnet/astring/commit/76ce7099c4ba391ef130ea6010bcce6ae7392cf4))


### Bug Fixes

* unary and update expression precedence ([0b273a6](https://github.com/davidbonnet/astring/commit/0b273a6cfe7c7672de4cf1bd00f423358d0729f4)), closes [#426](https://github.com/davidbonnet/astring/issues/426)

### [1.5.1](https://github.com/davidbonnet/astring/compare/v1.5.0...v1.5.1) (2021-01-03)


### Bug Fixes

* **source-maps:** map nameless nodes ([102e569](https://github.com/davidbonnet/astring/commit/102e5696482d42f5dcccdb2ce088f7361c7dee94))

## [1.5.0](https://github.com/davidbonnet/astring/compare/v1.4.3...v1.5.0) (2021-01-03)


### Features

* add bigint support ([d061997](https://github.com/davidbonnet/astring/commit/d061997b03095bbd864889dd04b6442fae6363ce))
* add identifier support to export all ([a646dfa](https://github.com/davidbonnet/astring/commit/a646dfa9a6d093111f934b306d37ad61cf32fd9b))
* add optional chaining support ([8c3ef44](https://github.com/davidbonnet/astring/commit/8c3ef44ae6d273562f6e03cb890726d2cc02f9b2)), closes [#424](https://github.com/davidbonnet/astring/issues/424)
* support import expression ([#345](https://github.com/davidbonnet/astring/issues/345)) ([56a1574](https://github.com/davidbonnet/astring/commit/56a1574774533764644107a61bf0acc0d1c7d209))


### Bug Fixes

* **demo:** disable spellcheck on input ([b95ef6a](https://github.com/davidbonnet/astring/commit/b95ef6a4a179b031beba27387dd1bba935b2ce72))
* incorrect awaited arrow function render ([11ec06c](https://github.com/davidbonnet/astring/commit/11ec06cd092cabc1a82ccd8b74c8219fcf98dcb7))
* missing space for repeating unary operator ([#315](https://github.com/davidbonnet/astring/issues/315)) ([48e8a2e](https://github.com/davidbonnet/astring/commit/48e8a2e157858df4e1765cc2db9148b5b708216d))
* sourcemaps for multiline strings are incorrect ([f246aff](https://github.com/davidbonnet/astring/commit/f246affc88b57455bc9eaa7f306fc9d2b6fd645f)), closes [#247](https://github.com/davidbonnet/astring/issues/247)

### [1.4.3](https://github.com/davidbonnet/astring/compare/v1.4.2...v1.4.3) (2019-10-13)


### Bug Fixes

* render TemplateElement nodes ([8e5f77b](https://github.com/davidbonnet/astring/commit/8e5f77b)), closes [#129](https://github.com/davidbonnet/astring/issues/129)

### [1.4.2](https://github.com/davidbonnet/astring/compare/v1.4.1...v1.4.2) (2019-09-15)


### Build System

* **deps-dev:** bump @babel/cli from 7.5.5 to 7.6.0 ([#103](https://github.com/davidbonnet/astring/issues/103)) ([e4681cc](https://github.com/davidbonnet/astring/commit/e4681cc))
* **deps-dev:** bump @babel/core from 7.5.5 to 7.6.0 ([#105](https://github.com/davidbonnet/astring/issues/105)) ([08af974](https://github.com/davidbonnet/astring/commit/08af974))
* **deps-dev:** bump @babel/generator from 7.5.5 to 7.6.0 ([#104](https://github.com/davidbonnet/astring/issues/104)) ([d4e29bd](https://github.com/davidbonnet/astring/commit/d4e29bd))
* **deps-dev:** bump @babel/parser from 7.5.5 to 7.6.0 ([#110](https://github.com/davidbonnet/astring/issues/110)) ([df0414b](https://github.com/davidbonnet/astring/commit/df0414b))
* **deps-dev:** bump @babel/preset-env from 7.5.5 to 7.6.0 ([#106](https://github.com/davidbonnet/astring/issues/106)) ([7616978](https://github.com/davidbonnet/astring/commit/7616978))
* **deps-dev:** bump acorn from 6.2.1 to 6.3.0 ([#86](https://github.com/davidbonnet/astring/issues/86)) ([585e4c6](https://github.com/davidbonnet/astring/commit/585e4c6))
* **deps-dev:** bump ava from 2.2.0 to 2.3.0 ([#89](https://github.com/davidbonnet/astring/issues/89)) ([21c90fa](https://github.com/davidbonnet/astring/commit/21c90fa))
* **deps-dev:** bump babel-preset-minify from 0.5.0 to 0.5.1 ([#88](https://github.com/davidbonnet/astring/issues/88)) ([a9c02a2](https://github.com/davidbonnet/astring/commit/a9c02a2))
* **deps-dev:** bump cross-env from 5.2.0 to 5.2.1 ([#99](https://github.com/davidbonnet/astring/issues/99)) ([d24faef](https://github.com/davidbonnet/astring/commit/d24faef))
* **deps-dev:** bump escodegen from 1.11.1 to 1.12.0 ([#84](https://github.com/davidbonnet/astring/issues/84)) ([09d0a59](https://github.com/davidbonnet/astring/commit/09d0a59))
* **deps-dev:** bump eslint from 6.1.0 to 6.2.0 ([#91](https://github.com/davidbonnet/astring/issues/91)) ([63f193d](https://github.com/davidbonnet/astring/commit/63f193d))
* **deps-dev:** bump eslint from 6.2.0 to 6.2.1 ([#93](https://github.com/davidbonnet/astring/issues/93)) ([f36bd83](https://github.com/davidbonnet/astring/commit/f36bd83))
* **deps-dev:** bump eslint from 6.2.1 to 6.2.2 ([#95](https://github.com/davidbonnet/astring/issues/95)) ([7a0c860](https://github.com/davidbonnet/astring/commit/7a0c860))
* **deps-dev:** bump eslint from 6.2.2 to 6.3.0 ([#97](https://github.com/davidbonnet/astring/issues/97)) ([8ba7db9](https://github.com/davidbonnet/astring/commit/8ba7db9))
* **deps-dev:** bump eslint from 6.3.0 to 6.4.0 ([#111](https://github.com/davidbonnet/astring/issues/111)) ([eefe681](https://github.com/davidbonnet/astring/commit/eefe681))
* **deps-dev:** bump eslint-config-prettier from 6.0.0 to 6.1.0 ([#92](https://github.com/davidbonnet/astring/issues/92)) ([82d33dc](https://github.com/davidbonnet/astring/commit/82d33dc))
* **deps-dev:** bump eslint-config-prettier from 6.1.0 to 6.2.0 ([#101](https://github.com/davidbonnet/astring/issues/101)) ([b4198a4](https://github.com/davidbonnet/astring/commit/b4198a4))
* **deps-dev:** bump eslint-config-prettier from 6.2.0 to 6.3.0 ([#108](https://github.com/davidbonnet/astring/issues/108)) ([f63fd0c](https://github.com/davidbonnet/astring/commit/f63fd0c))
* **deps-dev:** bump husky from 3.0.1 to 3.0.2 ([#77](https://github.com/davidbonnet/astring/issues/77)) ([dbb65dc](https://github.com/davidbonnet/astring/commit/dbb65dc))
* **deps-dev:** bump husky from 3.0.2 to 3.0.3 ([#82](https://github.com/davidbonnet/astring/issues/82)) ([f11579c](https://github.com/davidbonnet/astring/commit/f11579c))
* **deps-dev:** bump husky from 3.0.3 to 3.0.4 ([a686998](https://github.com/davidbonnet/astring/commit/a686998))
* **deps-dev:** bump husky from 3.0.4 to 3.0.5 ([#100](https://github.com/davidbonnet/astring/issues/100)) ([2bff815](https://github.com/davidbonnet/astring/commit/2bff815))
* **deps-dev:** bump meriyah from 1.3.5 to 1.6.0 ([#79](https://github.com/davidbonnet/astring/issues/79)) ([2cad1d4](https://github.com/davidbonnet/astring/commit/2cad1d4))
* **deps-dev:** bump meriyah from 1.6.0 to 1.6.2 ([#81](https://github.com/davidbonnet/astring/issues/81)) ([7ce3afd](https://github.com/davidbonnet/astring/commit/7ce3afd))
* **deps-dev:** bump meriyah from 1.6.10 to 1.6.13 ([#94](https://github.com/davidbonnet/astring/issues/94)) ([49f2899](https://github.com/davidbonnet/astring/commit/49f2899))
* **deps-dev:** bump meriyah from 1.6.13 to 1.6.15 ([#96](https://github.com/davidbonnet/astring/issues/96)) ([9a0ce8f](https://github.com/davidbonnet/astring/commit/9a0ce8f))
* **deps-dev:** bump meriyah from 1.6.15 to 1.6.16 ([#98](https://github.com/davidbonnet/astring/issues/98)) ([4085bf9](https://github.com/davidbonnet/astring/commit/4085bf9))
* **deps-dev:** bump meriyah from 1.6.16 to 1.6.17 ([#102](https://github.com/davidbonnet/astring/issues/102)) ([e56c7c6](https://github.com/davidbonnet/astring/commit/e56c7c6))
* **deps-dev:** bump meriyah from 1.6.17 to 1.6.18 ([#107](https://github.com/davidbonnet/astring/issues/107)) ([2c4fc18](https://github.com/davidbonnet/astring/commit/2c4fc18))
* **deps-dev:** bump meriyah from 1.6.18 to 1.7.0 ([#109](https://github.com/davidbonnet/astring/issues/109)) ([ba3c487](https://github.com/davidbonnet/astring/commit/ba3c487))
* **deps-dev:** bump meriyah from 1.6.2 to 1.6.8 ([#85](https://github.com/davidbonnet/astring/issues/85)) ([0c91697](https://github.com/davidbonnet/astring/commit/0c91697))
* **deps-dev:** bump meriyah from 1.6.8 to 1.6.10 ([#87](https://github.com/davidbonnet/astring/issues/87)) ([036c19d](https://github.com/davidbonnet/astring/commit/036c19d))



### [1.4.1](https://github.com/davidbonnet/astring/compare/v1.4.0...v1.4.1) (2019-07-20)


### Bug Fixes

* **#74:** correct exponentiation precedence ([b267927](https://github.com/davidbonnet/astring/commit/b267927)), closes [#74](https://github.com/davidbonnet/astring/issues/74) [#74](https://github.com/davidbonnet/astring/issues/74)



<a name="1.4.0"></a>
# [1.4.0](https://github.com/davidbonnet/astring/compare/v1.3.1...v1.4.0) (2019-03-30)


### Bug Fixes

* remove Node 6 support ([800c07f](https://github.com/davidbonnet/astring/commit/800c07f))


### Features

* support async loops and rest properties ([294021c](https://github.com/davidbonnet/astring/commit/294021c)), closes [#64](https://github.com/davidbonnet/astring/issues/64)



<a name="1.3.1"></a>
## [1.3.1](https://github.com/davidbonnet/astring/compare/v1.3.0...v1.3.1) (2018-06-23)


---

# Astring

[![NPM Version](https://img.shields.io/npm/v/astring.svg)](https://www.npmjs.org/package/astring)
[![Coverage](https://codecov.io/gh/davidbonnet/astring/branch/master/graph/badge.svg)](https://codecov.io/gh/davidbonnet/astring)

🌳 Tiny and fast JavaScript code generator from an [ESTree](https://github.com/estree/estree)-compliant AST.

### Key features

- Generates JavaScript code up to [version 15 (2024)](https://tc39.github.io/ecma262/) and [stage 3 proposals](https://github.com/tc39/proposals#stage-3).
- Works on [ESTree](https://github.com/estree/estree)-compliant ASTs such as the ones produced by [Meriyah](https://github.com/meriyah/meriyah) or [Acorn](https://github.com/acornjs/acorn).
- Extendable with custom AST node handlers.
- Considerably faster than [Bublé](https://gitlab.com/Rich-Harris/buble) (up to 5×), [Escodegen](https://github.com/estools/escodegen) (up to 10×), [Babel](https://github.com/babel/babel) (up to 50×), [UglifyJS](https://github.com/mishoo/UglifyJS2) (up to 125×), and [Prettier](https://github.com/prettier/prettier) (up to 380×).
- Supports source map generation with [Source Map](https://github.com/mozilla/source-map#sourcemapgenerator).
- Supports comment generation with [Astravel](https://github.com/davidbonnet/astravel).
- No dependencies and small footprint (≈ 16 KB minified, ≈ 4 KB gziped).
- Runs on [🦕 Deno](https://deno.land/x/astring).

## Installation

> :warning: Astring relies on `String.prototype.repeat(amount)` and `String.prototype.endsWith(string)`. If the environment running Astring does not define these methods, use [`string.prototype.repeat`](https://www.npmjs.com/package/string.prototype.repeat), [`string.prototype.endsWith`](https://www.npmjs.com/package/string.prototype.endswith) or [`babel-polyfill`](https://www.npmjs.com/package/babel-polyfill).

Install with the [Node Package Manager](https://www.npmjs.com/package/astring):

```bash
npm install astring
```

Or install with [JSR](https://jsr.io/@davidbonnet/astring):

```bash
deno add @davidbonnet/astring
```

Alternatively, checkout this repository and install the development dependencies to build the module file:

```bash
git clone https://github.com/davidbonnet/astring.git
cd astring
npm install
```

## Import

Import it from [Deno's third party module repository](https://deno.land/x/astring/src/astring.js):

```js
const { generate } = await import('https://deno.land/x/astring/src/astring.js')
```

With JavaScript 6 modules:

```js
import { generate } from 'astring'
```

With CommonJS:

```js
const { generate } = require('astring')
```

A browser-ready minified bundle containing Astring is available at `dist/astring.min.js`. The module exposes a global variable `astring`:

```html
<script src="astring.min.js" type="text/javascript"></script>
<script type="text/javascript">
  var generate = astring.generate
</script>
```

## API

The `astring` module exposes the following properties:

### `generate(node: object, options: object): string | object`

Returns a string representing the rendered code of the provided AST `node`. However, if an `output` stream is provided in the `options`, it writes to that stream and returns it.

The `options` are:

- `indent`: string to use for indentation (defaults to `"␣␣"`)
- `lineEnd`: string to use for line endings (defaults to `"\n"`)
- `startingIndentLevel`: indent level to start from (defaults to `0`)
- `comments`: generate comments if `true` (defaults to `false`)
- `output`: output stream to write the rendered code to (defaults to `null`)
- `generator`: custom code generator (defaults to `GENERATOR`)
- `sourceMap`: [source map generator](https://github.com/mozilla/source-map#sourcemapgenerator) (defaults to `null`)
- `expressionsPrecedence`: custom map of node types and their precedence level (defaults to `EXPRESSIONS_PRECEDENCE`)

### `GENERATOR: object`

Base generator that can be used to [extend Astring](#extending).

### `EXPRESSIONS_PRECEDENCE: object`

Mapping of node types and their precedence level to let the generator know when to use parentheses.

### `NEEDS_PARENTHESES: number`

Default precedence level that always triggers the use of parentheses.

### `baseGenerator: object`

> :warning: Deprecated, use `GENERATOR` instead.

## Benchmark

### Generating code

Operations per second for generating each sample code from a pre-parsed AST:

| code sample (length) | escodegen |   astring |  uglify |   babel | prettier |
| :------------------- | --------: | --------: | ------: | ------: | -------: |
| tiny code (11)       | 1,257,527 | 7,185,642 | 129,467 | 156,184 |      333 |
| everything (8532)    |     1,366 |     8,008 |       0 |     346 |       64 |

### Parsing and generating code

Operations per second for parsing and generating each sample code:

| code sample (length) | acorn + astring | meriyah + astring |  buble | sucrase |
| :------------------- | --------------: | ----------------: | -----: | ------: |
| tiny code (11)       |          92,578 |           864,665 | 25,911 | 575,370 |
| everything (8532)    |             706 |             1,425 |    132 |   1,403 |

## Examples

The following examples are written in JavaScript 5 with Astring imported _à la CommonJS_.

### Generating code

This example uses [Acorn](https://github.com/acornjs/acorn), a blazingly fast JavaScript AST producer and therefore the perfect companion of Astring.

```javascript
// Make sure acorn and astring modules are imported

// Set example code
var code = 'let answer = 4 + 7 * 5 + 3;\n'
// Parse it into an AST
var ast = acorn.parse(code, { ecmaVersion: 6 })
// Format it into a code string
var formattedCode = astring.generate(ast)
// Check it
console.log(code === formattedCode ? 'It works!' : 'Something went wrong…')
```

### Generating source maps

This example uses the source map generator from the [Source Map](https://github.com/mozilla/source-map#sourcemapgenerator) module.

```javascript
// Make sure acorn, sourceMap and astring modules are imported

var code = 'function add(a, b) { return a + b; }\n'
var ast = acorn.parse(code, {
  ecmaVersion: 6,
  sourceType: 'module',
  // Locations are needed in order for the source map generator to work
  locations: true,
})
// Create empty source map generator
var map = new sourceMap.SourceMapGenerator({
  // Source file name must be set and will be used for mappings
  file: 'script.js',
})
var formattedCode = generate(ast, {
  // Enable source maps
  sourceMap: map,
})
// Display generated source map
console.log(map.toString())
```

### Using writable streams

This example for [Node](http://nodejs.org) shows how to use writable streams to get the rendered code.

```javascript
// Make sure acorn and astring modules are imported

// Set example code
var code = 'let answer = 4 + 7 * 5 + 3;\n'
// Parse it into an AST
var ast = acorn.parse(code, { ecmaVersion: 6 })
// Format it and write the result to stdout
var stream = astring.generate(ast, {
  output: process.stdout,
})
// The returned value is the output stream
console.log('Does stream equal process.stdout?', stream === process.stdout)
```

### Generating comments

Astring supports comment generation, provided they are stored on the AST nodes. To do so, this example uses [Astravel](https://github.com/davidbonnet/astravel), a fast AST traveller and modifier.

```javascript
// Make sure acorn, astravel and astring modules are imported

// Set example code
var code =
  [
    '// Compute the answer to everything',
    'let answer = 4 + 7 * 5 + 3;',
    '// Display it',
    'console.log(answer);',
  ].join('\n') + '\n'
// Parse it into an AST and retrieve the list of comments
var comments = []
var ast = acorn.parse(code, {
  ecmaVersion: 6,
  locations: true,
  onComment: comments,
})
// Attach comments to AST nodes
astravel.attachComments(ast, comments)
// Format it into a code string
var formattedCode = astring.generate(ast, {
  comments: true,
})
// Check it
console.log(code === formattedCode ? 'It works!' : 'Something went wrong…')
```

### Extending

Astring can easily be extended by updating or passing a custom code `generator`. A code `generator` consists of a mapping of node names and functions that take two arguments: `node` and `state`. The `node` points to the node from which to generate the code and the `state` exposes the `write` method that takes generated code strings.

This example shows how to support the `await` keyword which is part of the [asynchronous functions proposal](https://github.com/tc39/ecmascript-asyncawait). The corresponding `AwaitExpression` node is based on [this suggested definition](https://github.com/estree/estree/blob/master/es2017.md).

```javascript
// Make sure the astring module is imported and that `Object.assign` is defined

// Create a custom generator that inherits from Astring's base generator
var customGenerator = Object.assign({}, astring.GENERATOR, {
  AwaitExpression: function (node, state) {
    state.write('await ')
    var argument = node.argument
    if (argument != null) {
      this[argument.type](argument, state)
    }
  },
})
// Obtain a custom AST somehow (note that this AST is not obtained from a valid code)
var ast = {
  type: 'AwaitExpression',
  argument: {
    type: 'CallExpression',
    callee: {
      type: 'Identifier',
      name: 'callable',
    },
    arguments: [],
  },
}
// Format it
var code = astring.generate(ast, {
  generator: customGenerator,
})
// Check it
console.log(
  code === 'await callable();\n' ? 'It works!' : 'Something went wrong…',
)
```

## Command line interface

The `bin/astring` utility can be used to convert a JSON-formatted ESTree compliant AST of a JavaScript code. It accepts the following arguments:

- `-i`, `--indent`: string to use as indentation (defaults to `"␣␣"`)
- `-l`, `--line-end`: string to use for line endings (defaults to `"\n"`)
- `-s`, `--starting-indent-level`: indent level to start from (defaults to `0`)
- `-h`, `--help`: print a usage message and exit
- `-v`, `--version`: print package version and exit

The utility reads the AST from a provided list of files or from `stdin` if none is supplied and prints the generated code.

### Example

As in the previous example, these examples use [Acorn](https://github.com/acornjs/acorn) to get the JSON-formatted AST. This command pipes the AST output by Acorn from a `script.js` file to Astring and writes the formatted JavaScript code into a `result.js` file:

```bash
acorn --ecma6 script.js | astring > result.js
```

This command does the same, but reads the AST from an intermediary file:

```bash
acorn --ecma6 script.js > ast.json
astring ast.json > result.js
```

This command reads JavaScript 6 code from `stdin` and outputs a prettified version:

```bash
cat | acorn --ecma6 | astring
```


---

# asynckit [![NPM Module](https://img.shields.io/npm/v/asynckit.svg?style=flat)](https://www.npmjs.com/package/asynckit)

Minimal async jobs utility library, with streams support.

[![PhantomJS Build](https://img.shields.io/travis/alexindigo/asynckit/v0.4.0.svg?label=browser&style=flat)](https://travis-ci.org/alexindigo/asynckit)
[![Linux Build](https://img.shields.io/travis/alexindigo/asynckit/v0.4.0.svg?label=linux:0.12-6.x&style=flat)](https://travis-ci.org/alexindigo/asynckit)
[![Windows Build](https://img.shields.io/appveyor/ci/alexindigo/asynckit/v0.4.0.svg?label=windows:0.12-6.x&style=flat)](https://ci.appveyor.com/project/alexindigo/asynckit)

[![Coverage Status](https://img.shields.io/coveralls/alexindigo/asynckit/v0.4.0.svg?label=code+coverage&style=flat)](https://coveralls.io/github/alexindigo/asynckit?branch=master)
[![Dependency Status](https://img.shields.io/david/alexindigo/asynckit/v0.4.0.svg?style=flat)](https://david-dm.org/alexindigo/asynckit)
[![bitHound Overall Score](https://www.bithound.io/github/alexindigo/asynckit/badges/score.svg)](https://www.bithound.io/github/alexindigo/asynckit)

<!-- [![Readme](https://img.shields.io/badge/readme-tested-brightgreen.svg?style=flat)](https://www.npmjs.com/package/reamde) -->

AsyncKit provides harness for `parallel` and `serial` iterators over list of items represented by arrays or objects.
Optionally it accepts abort function (should be synchronously return by iterator for each item), and terminates left over jobs upon an error event. For specific iteration order built-in (`ascending` and `descending`) and custom sort helpers also supported, via `asynckit.serialOrdered` method.

It ensures async operations to keep behavior more stable and prevent `Maximum call stack size exceeded` errors, from sync iterators.

| compression        |     size |
| :----------------- | -------: |
| asynckit.js        | 12.34 kB |
| asynckit.min.js    |  4.11 kB |
| asynckit.min.js.gz |  1.47 kB |


## Install

```sh
$ npm install --save asynckit
```

## Examples

### Parallel Jobs

Runs iterator over provided array in parallel. Stores output in the `result` array,
on the matching positions. In unlikely event of an error from one of the jobs,
will terminate rest of the active jobs (if abort function is provided)
and return error along with salvaged data to the main callback function.

#### Input Array

```javascript
var parallel = require('asynckit').parallel
  , assert   = require('assert')
  ;

var source         = [ 1, 1, 4, 16, 64, 32, 8, 2 ]
  , expectedResult = [ 2, 2, 8, 32, 128, 64, 16, 4 ]
  , expectedTarget = [ 1, 1, 2, 4, 8, 16, 32, 64 ]
  , target         = []
  ;

parallel(source, asyncJob, function(err, result)
{
  assert.deepEqual(result, expectedResult);
  assert.deepEqual(target, expectedTarget);
});

// async job accepts one element from the array
// and a callback function
function asyncJob(item, cb)
{
  // different delays (in ms) per item
  var delay = item * 25;

  // pretend different jobs take different time to finish
  // and not in consequential order
  var timeoutId = setTimeout(function() {
    target.push(item);
    cb(null, item * 2);
  }, delay);

  // allow to cancel "leftover" jobs upon error
  // return function, invoking of which will abort this job
  return clearTimeout.bind(null, timeoutId);
}
```

More examples could be found in [test/test-parallel-array.js](test/test-parallel-array.js).

#### Input Object

Also it supports named jobs, listed via object.

```javascript
var parallel = require('asynckit/parallel')
  , assert   = require('assert')
  ;

var source         = { first: 1, one: 1, four: 4, sixteen: 16, sixtyFour: 64, thirtyTwo: 32, eight: 8, two: 2 }
  , expectedResult = { first: 2, one: 2, four: 8, sixteen: 32, sixtyFour: 128, thirtyTwo: 64, eight: 16, two: 4 }
  , expectedTarget = [ 1, 1, 2, 4, 8, 16, 32, 64 ]
  , expectedKeys   = [ 'first', 'one', 'two', 'four', 'eight', 'sixteen', 'thirtyTwo', 'sixtyFour' ]
  , target         = []
  , keys           = []
  ;

parallel(source, asyncJob, function(err, result)
{
  assert.deepEqual(result, expectedResult);
  assert.deepEqual(target, expectedTarget);
  assert.deepEqual(keys, expectedKeys);
});

// supports full value, key, callback (shortcut) interface
function asyncJob(item, key, cb)
{
  // different delays (in ms) per item
  var delay = item * 25;

  // pretend different jobs take different time to finish
  // and not in consequential order
  var timeoutId = setTimeout(function() {
    keys.push(key);
    target.push(item);
    cb(null, item * 2);
  }, delay);

  // allow to cancel "leftover" jobs upon error
  // return function, invoking of which will abort this job
  return clearTimeout.bind(null, timeoutId);
}
```

More examples could be found in [test/test-parallel-object.js](test/test-parallel-object.js).

### Serial Jobs

Runs iterator over provided array sequentially. Stores output in the `result` array,
on the matching positions. In unlikely event of an error from one of the jobs,
will not proceed to the rest of the items in the list
and return error along with salvaged data to the main callback function.

#### Input Array

```javascript
var serial = require('asynckit/serial')
  , assert = require('assert')
  ;

var source         = [ 1, 1, 4, 16, 64, 32, 8, 2 ]
  , expectedResult = [ 2, 2, 8, 32, 128, 64, 16, 4 ]
  , expectedTarget = [ 0, 1, 2, 3, 4, 5, 6, 7 ]
  , target         = []
  ;

serial(source, asyncJob, function(err, result)
{
  assert.deepEqual(result, expectedResult);
  assert.deepEqual(target, expectedTarget);
});

// extended interface (item, key, callback)
// also supported for arrays
function asyncJob(item, key, cb)
{
  target.push(key);

  // it will be automatically made async
  // even it iterator "returns" in the same event loop
  cb(null, item * 2);
}
```

More examples could be found in [test/test-serial-array.js](test/test-serial-array.js).

#### Input Object

Also it supports named jobs, listed via object.

```javascript
var serial = require('asynckit').serial
  , assert = require('assert')
  ;

var source         = [ 1, 1, 4, 16, 64, 32, 8, 2 ]
  , expectedResult = [ 2, 2, 8, 32, 128, 64, 16, 4 ]
  , expectedTarget = [ 0, 1, 2, 3, 4, 5, 6, 7 ]
  , target         = []
  ;

var source         = { first: 1, one: 1, four: 4, sixteen: 16, sixtyFour: 64, thirtyTwo: 32, eight: 8, two: 2 }
  , expectedResult = { first: 2, one: 2, four: 8, sixteen: 32, sixtyFour: 128, thirtyTwo: 64, eight: 16, two: 4 }
  , expectedTarget = [ 1, 1, 4, 16, 64, 32, 8, 2 ]
  , target         = []
  ;


serial(source, asyncJob, function(err, result)
{
  assert.deepEqual(result, expectedResult);
  assert.deepEqual(target, expectedTarget);
});

// shortcut interface (item, callback)
// works for object as well as for the arrays
function asyncJob(item, cb)
{
  target.push(item);

  // it will be automatically made async
  // even it iterator "returns" in the same event loop
  cb(null, item * 2);
}
```

More examples could be found in [test/test-serial-object.js](test/test-serial-object.js).

_Note: Since _object_ is an _unordered_ collection of properties,
it may produce unexpected results with sequential iterations.
Whenever order of the jobs' execution is important please use `serialOrdered` method._

### Ordered Serial Iterations

TBD

For example [compare-property](compare-property) package.

### Streaming interface

TBD

## Want to Know More?

More examples can be found in [test folder](test/).

Or open an [issue](https://github.com/alexindigo/asynckit/issues) with questions and/or suggestions.

## License

AsyncKit is licensed under the MIT license.


---

# at-least-node

![npm](https://img.shields.io/npm/v/at-least-node)
![node](https://img.shields.io/node/v/at-least-node)
![NPM](https://img.shields.io/npm/l/at-least-node)

Sometimes you need to check if you're on _at least_ a given Node.js version, but you don't want to pull in the whole [`semver`](https://www.npmjs.com/package/semver) kitchen sink. That's what `at-least-node` is for.

| Package         | Size    |
| --------------- | ------- |
| `at-least-node` | 2.6 kB  |
| `semver`        | 75.5 kB |

```js
const atLeastNode = require('at-least-node')
atLeastNode('10.12.0')
// -> true on Node 10.12.0+, false on anything below that
```

When passing in a version string:

- You cannot include a leading `v` (i.e. `v10.12.0`)
- You cannot omit sections (i.e. `10.12`)
- You cannot use pre-releases (i.e. `1.0.0-beta`)
- There is no input validation, if you make a mistake, the resulting behavior is undefined


---

# Autoprefixer [![Cult Of Martians][cult-img]][cult]

<img align="right" width="94" height="71"
     src="https://postcss.github.io/autoprefixer/logo.svg"
     title="Autoprefixer logo by Anton Lovchikov">

[PostCSS] plugin to parse CSS and add vendor prefixes to CSS rules using values
from [Can I Use]. It is recommended by Google and used in Twitter and Alibaba.

Write your CSS rules without vendor prefixes (in fact, forget about them
entirely):

```css
::placeholder {
  color: gray;
}

.image {
  background-image: url(image@1x.png);
}
@media (min-resolution: 2dppx) {
  .image {
    background-image: url(image@2x.png);
  }
}
```

Autoprefixer will use the data based on current browser popularity and property
support to apply prefixes for you. You can try the [interactive demo]
of Autoprefixer.

```css
::-moz-placeholder {
  color: gray;
}
::placeholder {
  color: gray;
}

.image {
  background-image: url(image@1x.png);
}
@media (-webkit-min-device-pixel-ratio: 2),
       (min-resolution: 2dppx) {
  .image {
    background-image: url(image@2x.png);
  }
}
```

Twitter account for news and releases: [@autoprefixer].

<a href="https://evilmartians.com/?utm_source=autoprefixer">
<img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg" alt="Sponsored by Evil Martians" width="236" height="54">
</a>

[interactive demo]: https://autoprefixer.github.io/
[@autoprefixer]:    https://twitter.com/autoprefixer
[Can I Use]:        https://caniuse.com/
[cult-img]:         https://cultofmartians.com/assets/badges/badge.svg
[PostCSS]:          https://github.com/postcss/postcss
[cult]:             https://cultofmartians.com/tasks/autoprefixer-grid.html


## Docs
Read full docs **[here](https://github.com/postcss/autoprefixer#readme)**.


---

# Changelog

## [1.8.4](https://github.com/axios/axios/compare/v1.8.3...v1.8.4) (2025-03-19)


### Bug Fixes

* **buildFullPath:** handle `allowAbsoluteUrls: false` without `baseURL` ([#6833](https://github.com/axios/axios/issues/6833)) ([f10c2e0](https://github.com/axios/axios/commit/f10c2e0de7fde0051f848609a29c2906d0caa1d9))

### Contributors to this release

- <img src="https://avatars.githubusercontent.com/u/8029107?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Marc Hassan](https://github.com/mhassan1 "+5/-1 (#6833 )")

## [1.8.3](https://github.com/axios/axios/compare/v1.8.2...v1.8.3) (2025-03-10)


### Bug Fixes

* add missing type for allowAbsoluteUrls ([#6818](https://github.com/axios/axios/issues/6818)) ([10fa70e](https://github.com/axios/axios/commit/10fa70ef14fe39558b15a179f0e82f5f5e5d11b2))
* **xhr/fetch:** pass `allowAbsoluteUrls` to `buildFullPath` in `xhr` and `fetch` adapters ([#6814](https://github.com/axios/axios/issues/6814)) ([ec159e5](https://github.com/axios/axios/commit/ec159e507bdf08c04ba1a10fe7710094e9e50ec9))

### Contributors to this release

- <img src="https://avatars.githubusercontent.com/u/3238291?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Ashcon Partovi](https://github.com/Electroid "+6/-0 (#6811 )")
- <img src="https://avatars.githubusercontent.com/u/28559054?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [StefanBRas](https://github.com/StefanBRas "+4/-0 (#6818 )")
- <img src="https://avatars.githubusercontent.com/u/8029107?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Marc Hassan](https://github.com/mhassan1 "+2/-2 (#6814 )")

## [1.8.2](https://github.com/axios/axios/compare/v1.8.1...v1.8.2) (2025-03-07)


### Bug Fixes

* **http-adapter:** add allowAbsoluteUrls to path building ([#6810](https://github.com/axios/axios/issues/6810)) ([fb8eec2](https://github.com/axios/axios/commit/fb8eec214ce7744b5ca787f2c3b8339b2f54b00f))

### Contributors to this release

- <img src="https://avatars.githubusercontent.com/u/14166260?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Fasoro-Joseph Alexander](https://github.com/lexcorp16 "+1/-1 (#6810 )")

## [1.8.1](https://github.com/axios/axios/compare/v1.8.0...v1.8.1) (2025-02-26)


### Bug Fixes

* **utils:** move `generateString` to platform utils to avoid importing crypto module into client builds; ([#6789](https://github.com/axios/axios/issues/6789)) ([36a5a62](https://github.com/axios/axios/commit/36a5a620bec0b181451927f13ac85b9888b86cec))

### Contributors to this release

- <img src="https://avatars.githubusercontent.com/u/12586868?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Dmitriy Mozgovoy](https://github.com/DigitalBrainJS "+51/-47 (#6789 )")

# [1.8.0](https://github.com/axios/axios/compare/v1.7.9...v1.8.0) (2025-02-25)


### Bug Fixes

* **examples:** application crashed when navigating examples in browser ([#5938](https://github.com/axios/axios/issues/5938)) ([1260ded](https://github.com/axios/axios/commit/1260ded634ec101dd5ed05d3b70f8e8f899dba6c))
* missing word in SUPPORT_QUESTION.yml ([#6757](https://github.com/axios/axios/issues/6757)) ([1f890b1](https://github.com/axios/axios/commit/1f890b13f2c25a016f3c84ae78efb769f244133e))
* **utils:** replace getRandomValues with crypto module ([#6788](https://github.com/axios/axios/issues/6788)) ([23a25af](https://github.com/axios/axios/commit/23a25af0688d1db2c396deb09229d2271cc24f6c))


### Features

* Add config for ignoring absolute URLs ([#5902](https://github.com/axios/axios/issues/5902)) ([#6192](https://github.com/axios/axios/issues/6192)) ([32c7bcc](https://github.com/axios/axios/commit/32c7bcc0f233285ba27dec73a4b1e81fb7a219b3))


### Reverts

* Revert "chore: expose fromDataToStream to be consumable (#6731)" (#6732) ([1317261](https://github.com/axios/axios/commit/1317261125e9c419fe9f126867f64d28f9c1efda)), closes [#6731](https://github.com/axios/axios/issues/6731) [#6732](https://github.com/axios/axios/issues/6732)


### BREAKING CHANGES

* code relying on the above will now combine the URLs instead of prefer request URL

* feat: add config option for allowing absolute URLs

* fix: add default value for allowAbsoluteUrls in buildFullPath

* fix: typo in flow control when setting allowAbsoluteUrls

### Contributors to this release

- <img src="https://avatars.githubusercontent.com/u/7661715?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Michael Toscano](https://github.com/GethosTheWalrus "+42/-8 (#6192 )")
- <img src="https://avatars.githubusercontent.com/u/22686401?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Willian Agostini](https://github.com/WillianAgostini "+26/-3 (#6788 #6777 )")
- <img src="https://avatars.githubusercontent.com/u/72578270?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Naron](https://github.com/naronchen "+27/-0 (#5901 )")
- <img src="https://avatars.githubusercontent.com/u/47430686?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [shravan || श्रvan](https://github.com/shravan20 "+7/-3 (#6116 )")
- <img src="https://avatars.githubusercontent.com/u/145078271?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Justin Dhillon](https://github.com/justindhillon "+0/-7 (#6312 )")
- <img src="https://avatars.githubusercontent.com/u/30925732?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [yionr](https://github.com/yionr "+5/-1 (#6129 )")
- <img src="https://avatars.githubusercontent.com/u/534166?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Shin&#x27;ya Ueoka](https://github.com/ueokande "+3/-3 (#5935 )")
- <img src="https://avatars.githubusercontent.com/u/33569?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Dan Dascalescu](https://github.com/dandv "+3/-3 (#5908 #6757 )")
- <img src="https://avatars.githubusercontent.com/u/16476523?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Nitin Ramnani](https://github.com/NitinRamnani "+2/-2 (#5938 )")
- <img src="https://avatars.githubusercontent.com/u/152275799?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Shay Molcho](https://github.com/shaymolcho "+2/-2 (#6770 )")
- <img src="https://avatars.githubusercontent.com/u/4814473?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Jay](https://github.com/jasonsaayman "+0/-3 (#6732 )")
- fancy45daddy
- <img src="https://avatars.githubusercontent.com/u/127725897?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Habip Akyol](https://github.com/habipakyol "+1/-1 (#6030 )")
- <img src="https://avatars.githubusercontent.com/u/54869395?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Bailey Lissington](https://github.com/llamington "+1/-1 (#6771 )")
- <img src="https://avatars.githubusercontent.com/u/14969290?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Bernardo da Eira Duarte](https://github.com/bernardoduarte "+1/-1 (#6480 )")
- <img src="https://avatars.githubusercontent.com/u/117800149?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Shivam Batham](https://github.com/Shivam-Batham "+1/-1 (#5949 )")
- <img src="https://avatars.githubusercontent.com/u/67861627?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Lipin Kariappa](https://github.com/lipinnnnn "+1/-1 (#5936 )")

## [1.7.9](https://github.com/axios/axios/compare/v1.7.8...v1.7.9) (2024-12-04)


### Reverts

* Revert "fix(types): export CJS types from ESM (#6218)" (#6729) ([c44d2f2](https://github.com/axios/axios/commit/c44d2f2316ad289b38997657248ba10de11deb6c)), closes [#6218](https://github.com/axios/axios/issues/6218) [#6729](https://github.com/axios/axios/issues/6729)

### Contributors to this release

- <img src="https://avatars.githubusercontent.com/u/4814473?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Jay](https://github.com/jasonsaayman "+596/-108 (#6729 )")

## [1.7.8](https://github.com/axios/axios/compare/v1.7.7...v1.7.8) (2024-11-25)


### Bug Fixes

* allow passing a callback as paramsSerializer to buildURL ([#6680](https://github.com/axios/axios/issues/6680)) ([eac4619](https://github.com/axios/axios/commit/eac4619fe2e0926e876cd260ee21e3690381dbb5))
* **core:** fixed config merging bug ([#6668](https://github.com/axios/axios/issues/6668)) ([5d99fe4](https://github.com/axios/axios/commit/5d99fe4491202a6268c71e5dcc09192359d73cea))
* fixed width form to not shrink after 'Send Request' button is clicked ([#6644](https://github.com/axios/axios/issues/6644)) ([7ccd5fd](https://github.com/axios/axios/commit/7ccd5fd42402102d38712c32707bf055be72ab54))
* **http:** add support for File objects as payload in http adapter ([#6588](https://github.com/axios/axios/issues/6588)) ([#6605](https://github.com/axios/axios/issues/6605)) ([6841d8d](https://github.com/axios/axios/commit/6841d8d18ddc71cc1bd202ffcfddb3f95622eef3))
* **http:** fixed proxy-from-env module import ([#5222](https://github.com/axios/axios/issues/5222)) ([12b3295](https://github.com/axios/axios/commit/12b32957f1258aee94ef859809ed39f8f88f9dfa))
* **http:** use `globalThis.TextEncoder` when available ([#6634](https://github.com/axios/axios/issues/6634)) ([df956d1](https://github.com/axios/axios/commit/df956d18febc9100a563298dfdf0f102c3d15410))
* ios11 breaks when build ([#6608](https://github.com/axios/axios/issues/6608)) ([7638952](https://github.com/axios/axios/commit/763895270f7b50c7c780c3c9807ae8635de952cd))
* **types:** add missing types for mergeConfig function ([#6590](https://github.com/axios/axios/issues/6590)) ([00de614](https://github.com/axios/axios/commit/00de614cd07b7149af335e202aef0e076c254f49))
* **types:** export CJS types from ESM ([#6218](https://github.com/axios/axios/issues/6218)) ([c71811b](https://github.com/axios/axios/commit/c71811b00f2fcff558e4382ba913bdac4ad7200e))
* updated stream aborted error message to be more clear ([#6615](https://github.com/axios/axios/issues/6615)) ([cc3217a](https://github.com/axios/axios/commit/cc3217a612024d83a663722a56d7a98d8759c6d5))
* use URL API instead of DOM to fix a potential vulnerability warning; ([#6714](https://github.com/axios/axios/issues/6714)) ([0a8d6e1](https://github.com/axios/axios/commit/0a8d6e19da5b9899a2abafaaa06a75ee548597db))

### Contributors to this release

- <img src="https://avatars.githubusercontent.com/u/779047?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Remco Haszing](https://github.com/remcohaszing "+108/-596 (#6218 )")
- <img src="https://avatars.githubusercontent.com/u/4814473?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Jay](https://github.com/jasonsaayman "+281/-19 (#6640 #6619 )")
- <img src="https://avatars.githubusercontent.com/u/140250471?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Aayush Yadav](https://github.com/aayushyadav020 "+124/-111 (#6617 )")
- <img src="https://avatars.githubusercontent.com/u/12586868?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Dmitriy Mozgovoy](https://github.com/DigitalBrainJS "+12/-65 (#6714 )")
- <img src="https://avatars.githubusercontent.com/u/479715?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Ell Bradshaw](https://github.com/cincodenada "+29/-0 (#6489 )")
- <img src="https://avatars.githubusercontent.com/u/60218780?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Amit Saini](https://github.com/amitsainii "+13/-3 (#5237 )")
- <img src="https://avatars.githubusercontent.com/u/19817867?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Tommaso Paulon](https://github.com/guuido "+14/-1 (#6680 )")
- <img src="https://avatars.githubusercontent.com/u/63336443?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Akki](https://github.com/Aakash-Rana "+5/-5 (#6668 )")
- <img src="https://avatars.githubusercontent.com/u/20028934?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Sampo Silvennoinen](https://github.com/stscoundrel "+3/-3 (#6633 )")
- <img src="https://avatars.githubusercontent.com/u/1174718?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Kasper Isager Dalsgarð](https://github.com/kasperisager "+2/-2 (#6634 )")
- <img src="https://avatars.githubusercontent.com/u/3709715?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Christian Clauss](https://github.com/cclauss "+4/-0 (#6683 )")
- <img src="https://avatars.githubusercontent.com/u/1639119?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Pavan Welihinda](https://github.com/pavan168 "+2/-2 (#5222 )")
- <img src="https://avatars.githubusercontent.com/u/5742900?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Taylor Flatt](https://github.com/taylorflatt "+2/-2 (#6615 )")
- <img src="https://avatars.githubusercontent.com/u/79452224?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Kenzo Wada](https://github.com/Kenzo-Wada "+2/-2 (#6608 )")
- <img src="https://avatars.githubusercontent.com/u/50064240?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Ngole Lawson](https://github.com/echelonnought "+3/-0 (#6644 )")
- <img src="https://avatars.githubusercontent.com/u/1262198?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Haven](https://github.com/Baoyx007 "+3/-0 (#6590 )")
- <img src="https://avatars.githubusercontent.com/u/149003676?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Shrivali Dutt](https://github.com/shrivalidutt "+1/-1 (#6637 )")
- <img src="https://avatars.githubusercontent.com/u/1304290?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Henco Appel](https://github.com/hencoappel "+1/-1 (#6605 )")

## [1.7.7](https://github.com/axios/axios/compare/v1.7.6...v1.7.7) (2024-08-31)


### Bug Fixes

* **fetch:** fix stream handling in Safari by fallback to using a stream reader instead of an async iterator; ([#6584](https://github.com/axios/axios/issues/6584)) ([d198085](https://github.com/axios/axios/commit/d1980854fee1765cd02fa0787adf5d6e34dd9dcf))
* **http:** fixed support for IPv6 literal strings in url ([#5731](https://github.com/axios/axios/issues/5731)) ([364993f](https://github.com/axios/axios/commit/364993f0d8bc6e0e06f76b8a35d2d0a35cab054c))

### Contributors to this release

- <img src="https://avatars.githubusercontent.com/u/10539109?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Rishi556](https://github.com/Rishi556 "+39/-1 (#5731 )")
- <img src="https://avatars.githubusercontent.com/u/12586868?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Dmitriy Mozgovoy](https://github.com/DigitalBrainJS "+27/-7 (#6584 )")

## [1.7.6](https://github.com/axios/axios/compare/v1.7.5...v1.7.6) (2024-08-30)


### Bug Fixes

* **fetch:** fix content length calculation for FormData payload; ([#6524](https://github.com/axios/axios/issues/6524)) ([085f568](https://github.com/axios/axios/commit/085f56861a83e9ac02c140ad9d68dac540dfeeaa))
* **fetch:** optimize signals composing logic; ([#6582](https://github.com/axios/axios/issues/6582)) ([df9889b](https://github.com/axios/axios/commit/df9889b83c2cc37e9e6189675a73ab70c60f031f))

### Contributors to this release

- <img src="https://avatars.githubusercontent.com/u/12586868?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Dmitriy Mozgovoy](https://github.com/DigitalBrainJS "+98/-46 (#6582 )")
- <img src="https://avatars.githubusercontent.com/u/3534453?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Jacques Germishuys](https://github.com/jacquesg "+5/-1 (#6524 )")
- <img src="https://avatars.githubusercontent.com/u/53894505?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [kuroino721](https://github.com/kuroino721 "+3/-1 (#6575 )")

## [1.7.5](https://github.com/axios/axios/compare/v1.7.4...v1.7.5) (2024-08-23)


### Bug Fixes

* **adapter:** fix undefined reference to hasBrowserEnv ([#6572](https://github.com/axios/axios/issues/6572)) ([7004707](https://github.com/axios/axios/commit/7004707c4180b416341863bd86913fe4fc2f1df1))
* **core:** add the missed implementation of AxiosError#status property; ([#6573](https://github.com/axios/axios/issues/6573)) ([6700a8a](https://github.com/axios/axios/commit/6700a8adac06942205f6a7a21421ecb36c4e0852))
* **core:** fix `ReferenceError: navigator is not defined` for custom environments; ([#6567](https://github.com/axios/axios/issues/6567)) ([fed1a4b](https://github.com/axios/axios/commit/fed1a4b2d78ed4a588c84e09d32749ed01dc2794))
* **fetch:** fix credentials handling in Cloudflare workers ([#6533](https://github.com/axios/axios/issues/6533)) ([550d885](https://github.com/axios/axios/commit/550d885eb90fd156add7b93bbdc54d30d2f9a98d))

### Contributors to this release

- <img src="https://avatars.githubusercontent.com/u/12586868?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Dmitriy Mozgovoy](https://github.com/DigitalBrainJS "+187/-83 (#6573 #6567 #6566 #6564 #6563 #6557 #6556 #6555 #6554 #6552 )")
- <img src="https://avatars.githubusercontent.com/u/2495809?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Antonin Bas](https://github.com/antoninbas "+6/-6 (#6572 )")
- <img src="https://avatars.githubusercontent.com/u/5406212?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Hans Otto Wirtz](https://github.com/hansottowirtz "+4/-1 (#6533 )")

## [1.7.4](https://github.com/axios/axios/compare/v1.7.3...v1.7.4) (2024-08-13)


### Bug Fixes

* **sec:** CVE-2024-39338 ([#6539](https://github.com/axios/axios/issues/6539)) ([#6543](https://github.com/axios/axios/issues/6543)) ([6b6b605](https://github.com/axios/axios/commit/6b6b605eaf73852fb2dae033f1e786155959de3a))
* **sec:** disregard protocol-relative URL to remediate SSRF ([#6539](https://github.com/axios/axios/issues/6539)) ([07a661a](https://github.com/axios/axios/commit/07a661a2a6b9092c4aa640dcc7f724ec5e65bdda))

### Contributors to this release

- <img src="https://avatars.githubusercontent.com/u/31389480?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Lev Pachmanov](https://github.com/levpachmanov "+47/-11 (#6543 )")
- <img src="https://avatars.githubusercontent.com/u/41283691?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Đỗ Trọng Hải](https://github.com/hainenber "+49/-4 (#6539 )")

## [1.7.3](https://github.com/axios/axios/compare/v1.7.2...v1.7.3) (2024-08-01)


### Bug Fixes

* **adapter:** fix progress event emitting; ([#6518](https://github.com/axios/axios/issues/6518)) ([e3c76fc](https://github.com/axios/axios/commit/e3c76fc9bdd03aa4d98afaf211df943e2031453f))
* **fetch:** fix withCredentials request config ([#6505](https://github.com/axios/axios/issues/6505)) ([85d4d0e](https://github.com/axios/axios/commit/85d4d0ea0aae91082f04e303dec46510d1b4e787))
* **xhr:** return original config on errors from XHR adapter ([#6515](https://github.com/axios/axios/issues/6515)) ([8966ee7](https://github.com/axios/axios/commit/8966ee7ea62ecbd6cfb39a905939bcdab5cf6388))

### Contributors to this release

- <img src="https://avatars.githubusercontent.com/u/12586868?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Dmitriy Mozgovoy](https://github.com/DigitalBrainJS "+211/-159 (#6518 #6519 )")
- <img src="https://avatars.githubusercontent.com/u/10867286?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Valerii Sidorenko](https://github.com/ValeraS "+3/-3 (#6515 )")
- <img src="https://avatars.githubusercontent.com/u/8599535?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [prianYu](https://github.com/prianyu "+2/-2 (#6505 )")

## [1.7.2](https://github.com/axios/axios/compare/v1.7.1...v1.7.2) (2024-05-21)


### Bug Fixes

* **fetch:** enhance fetch API detection; ([#6413](https://github.com/axios/axios/issues/6413)) ([4f79aef](https://github.com/axios/axios/commit/4f79aef81b7c4644328365bfc33acf0a9ef595bc))

### Contributors to this release

- <img src="https://avatars.githubusercontent.com/u/12586868?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Dmitriy Mozgovoy](https://github.com/DigitalBrainJS "+3/-3 (#6413 )")

## [1.7.1](https://github.com/axios/axios/compare/v1.7.0...v1.7.1) (2024-05-20)


### Bug Fixes

* **fetch:** fixed ReferenceError issue when TextEncoder is not available in the environment; ([#6410](https://github.com/axios/axios/issues/6410)) ([733f15f](https://github.com/axios/axios/commit/733f15fe5bd2d67e1fadaee82e7913b70d45dc5e))

### Contributors to this release

- <img src="https://avatars.githubusercontent.com/u/12586868?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Dmitriy Mozgovoy](https://github.com/DigitalBrainJS "+14/-9 (#6410 )")

# [1.7.0](https://github.com/axios/axios/compare/v1.7.0-beta.2...v1.7.0) (2024-05-19)


### Features

* **adapter:** add fetch adapter; ([#6371](https://github.com/axios/axios/issues/6371)) ([a3ff99b](https://github.com/axios/axios/commit/a3ff99b59d8ec2ab5dd049e68c043617a4072e42))

### Bug Fixes

* **core/axios:** handle un-writable error stack ([#6362](https://github.com/axios/axios/issues/6362)) ([81e0455](https://github.com/axios/axios/commit/81e0455b7b57fbaf2be16a73ebe0e6591cc6d8f9))  

### Contributors to this release

- <img src="https://avatars.githubusercontent.com/u/12586868?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Dmitriy Mozgovoy](https://github.com/DigitalBrainJS "+1015/-127 (#6371 )")
- <img src="https://avatars.githubusercontent.com/u/4814473?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Jay](https://github.com/jasonsaayman "+30/-14 ()")
- <img src="https://avatars.githubusercontent.com/u/16711696?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Alexandre ABRIOUX](https://github.com/alexandre-abrioux "+56/-6 (#6362 )")

# [1.7.0-beta.2](https://github.com/axios/axios/compare/v1.7.0-beta.1...v1.7.0-beta.2) (2024-05-19)


### Bug Fixes

* **fetch:** capitalize HTTP method names; ([#6395](https://github.com/axios/axios/issues/6395)) ([ad3174a](https://github.com/axios/axios/commit/ad3174a3515c3c2573f4bcb94818d582826f3914))
* **fetch:** fix & optimize progress capturing for cases when the request data has a nullish value or zero data length ([#6400](https://github.com/axios/axios/issues/6400)) ([95a3e8e](https://github.com/axios/axios/commit/95a3e8e346cfd6a5548e171f2341df3235d0e26b))
* **fetch:** fix headers getting from a stream response; ([#6401](https://github.com/axios/axios/issues/6401)) ([870e0a7](https://github.com/axios/axios/commit/870e0a76f60d0094774a6a63fa606eec52a381af))

### Contributors to this release

- <img src="https://avatars.githubusercontent.com/u/12586868?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Dmitriy Mozgovoy](https://github.com/DigitalBrainJS "+99/-46 (#6405 #6404 #6401 #6400 #6395 )")

# [1.7.0-beta.1](https://github.com/axios/axios/compare/v1.7.0-beta.0...v1.7.0-beta.1) (2024-05-07)


### Bug Fixes

* **core/axios:** handle un-writable error stack ([#6362](https://github.com/axios/axios/issues/6362)) ([81e0455](https://github.com/axios/axios/commit/81e0455b7b57fbaf2be16a73ebe0e6591cc6d8f9))
* **fetch:** fix cases when ReadableStream or Response.body are not available; ([#6377](https://github.com/axios/axios/issues/6377)) ([d1d359d](https://github.com/axios/axios/commit/d1d359da347704e8b28d768e61515a3e96c5b072))
* **fetch:** treat fetch-related TypeError as an AxiosError.ERR_NETWORK error; ([#6380](https://github.com/axios/axios/issues/6380)) ([bb5f9a5](https://github.com/axios/axios/commit/bb5f9a5ab768452de9e166dc28d0ffc234245ef1))

### Contributors to this release

- <img src="https://avatars.githubusercontent.com/u/16711696?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Alexandre ABRIOUX](https://github.com/alexandre-abrioux "+56/-6 (#6362 )")
- <img src="https://avatars.githubusercontent.com/u/12586868?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Dmitriy Mozgovoy](https://github.com/DigitalBrainJS "+42/-17 (#6380 #6377 )")

# [1.7.0-beta.0](https://github.com/axios/axios/compare/v1.6.8...v1.7.0-beta.0) (2024-04-28)


### Features

* **adapter:** add fetch adapter; ([#6371](https://github.com/axios/axios/issues/6371)) ([a3ff99b](https://github.com/axios/axios/commit/a3ff99b59d8ec2ab5dd049e68c043617a4072e42))

### Contributors to this release

- <img src="https://avatars.githubusercontent.com/u/12586868?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Dmitriy Mozgovoy](https://github.com/DigitalBrainJS "+1015/-127 (#6371 )")
- <img src="https://avatars.githubusercontent.com/u/4814473?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Jay](https://github.com/jasonsaayman "+30/-14 ()")

## [1.6.8](https://github.com/axios/axios/compare/v1.6.7...v1.6.8) (2024-03-15)


### Bug Fixes

* **AxiosHeaders:** fix AxiosHeaders conversion to an object during config merging ([#6243](https://github.com/axios/axios/issues/6243)) ([2656612](https://github.com/axios/axios/commit/2656612bc10fe2757e9832b708ed773ab340b5cb))
* **import:** use named export for EventEmitter; ([7320430](https://github.com/axios/axios/commit/7320430aef2e1ba2b89488a0eaf42681165498b1))
* **vulnerability:** update follow-redirects to 1.15.6 ([#6300](https://github.com/axios/axios/issues/6300)) ([8786e0f](https://github.com/axios/axios/commit/8786e0ff55a8c68d4ca989801ad26df924042e27))

### Contributors to this release

- <img src="https://avatars.githubusercontent.com/u/4814473?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Jay](https://github.com/jasonsaayman "+4572/-3446 (#6238 )")
- <img src="https://avatars.githubusercontent.com/u/12586868?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Dmitriy Mozgovoy](https://github.com/DigitalBrainJS "+30/-0 (#6231 )")
- <img src="https://avatars.githubusercontent.com/u/68230846?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Mitchell](https://github.com/Creaous "+9/-9 (#6300 )")
- <img src="https://avatars.githubusercontent.com/u/53797821?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Emmanuel](https://github.com/mannoeu "+2/-2 (#6196 )")
- <img src="https://avatars.githubusercontent.com/u/44109284?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Lucas Keller](https://github.com/ljkeller "+3/-0 (#6194 )")
- <img src="https://avatars.githubusercontent.com/u/72791488?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Aditya Mogili](https://github.com/ADITYA-176 "+1/-1 ()")
- <img src="https://avatars.githubusercontent.com/u/46135319?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Miroslav Petrov](https://github.com/petrovmiroslav "+1/-1 (#6243 )")

## [1.6.7](https://github.com/axios/axios/compare/v1.6.6...v1.6.7) (2024-01-25)


### Bug Fixes

* capture async stack only for rejections with native error objects; ([#6203](https://github.com/axios/axios/issues/6203)) ([1a08f90](https://github.com/axios/axios/commit/1a08f90f402336e4d00e9ee82f211c6adb1640b0))

### Contributors to this release

- <img src="https://avatars.githubusercontent.com/u/12586868?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Dmitriy Mozgovoy](https://github.com/DigitalBrainJS "+30/-26 (#6203 )")
- <img src="https://avatars.githubusercontent.com/u/73059627?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [zhoulixiang](https://github.com/zh-lx "+0/-3 (#6186 )")

## [1.6.6](https://github.com/axios/axios/compare/v1.6.5...v1.6.6) (2024-01-24)


### Bug Fixes

* fixed missed dispatchBeforeRedirect argument ([#5778](https://github.com/axios/axios/issues/5778)) ([a1938ff](https://github.com/axios/axios/commit/a1938ff073fcb0f89011f001dfbc1fa1dc995e39))
* wrap errors to improve async stack trace ([#5987](https://github.com/axios/axios/issues/5987)) ([123f354](https://github.com/axios/axios/commit/123f354b920f154a209ea99f76b7b2ef3d9ebbab))

### Contributors to this release

- <img src="https://avatars.githubusercontent.com/u/1186084?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Ilya Priven](https://github.com/ikonst "+91/-8 (#5987 )")
- <img src="https://avatars.githubusercontent.com/u/1884246?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Zao Soula](https://github.com/zaosoula "+6/-6 (#5778 )")

## [1.6.5](https://github.com/axios/axios/compare/v1.6.4...v1.6.5) (2024-01-05)


### Bug Fixes

* **ci:** refactor notify action as a job of publish action; ([#6176](https://github.com/axios/axios/issues/6176)) ([0736f95](https://github.com/axios/axios/commit/0736f95ce8776366dc9ca569f49ba505feb6373c))
* **dns:** fixed lookup error handling; ([#6175](https://github.com/axios/axios/issues/6175)) ([f4f2b03](https://github.com/axios/axios/commit/f4f2b039dd38eb4829e8583caede4ed6d2dd59be))

### Contributors to this release

- <img src="https://avatars.githubusercontent.com/u/12586868?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Dmitriy Mozgovoy](https://github.com/DigitalBrainJS "+41/-6 (#6176 #6175 )")
- <img src="https://avatars.githubusercontent.com/u/4814473?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Jay](https://github.com/jasonsaayman "+6/-1 ()")

## [1.6.4](https://github.com/axios/axios/compare/v1.6.3...v1.6.4) (2024-01-03)


### Bug Fixes

* **security:** fixed formToJSON prototype pollution vulnerability; ([#6167](https://github.com/axios/axios/issues/6167)) ([3c0c11c](https://github.com/axios/axios/commit/3c0c11cade045c4412c242b5727308cff9897a0e))
* **security:** fixed security vulnerability in follow-redirects ([#6163](https://github.com/axios/axios/issues/6163)) ([75af1cd](https://github.com/axios/axios/commit/75af1cdff5b3a6ca3766d3d3afbc3115bb0811b8))

### Contributors to this release

- <img src="https://avatars.githubusercontent.com/u/4814473?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Jay](https://github.com/jasonsaayman "+34/-6 ()")
- <img src="https://avatars.githubusercontent.com/u/12586868?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Dmitriy Mozgovoy](https://github.com/DigitalBrainJS "+34/-3 (#6172 #6167 )")
- <img src="https://avatars.githubusercontent.com/u/1402060?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Guy Nesher](https://github.com/gnesher "+10/-10 (#6163 )")

## [1.6.3](https://github.com/axios/axios/compare/v1.6.2...v1.6.3) (2023-12-26)


### Bug Fixes

* Regular Expression Denial of Service (ReDoS) ([#6132](https://github.com/axios/axios/issues/6132)) ([5e7ad38](https://github.com/axios/axios/commit/5e7ad38fb0f819fceb19fb2ee5d5d38f56aa837d))

### Contributors to this release

- <img src="https://avatars.githubusercontent.com/u/4814473?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Jay](https://github.com/jasonsaayman "+15/-6 (#6145 )")
- <img src="https://avatars.githubusercontent.com/u/22686401?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Willian Agostini](https://github.com/WillianAgostini "+17/-2 (#6132 )")
- <img src="https://avatars.githubusercontent.com/u/12586868?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Dmitriy Mozgovoy](https://github.com/DigitalBrainJS "+3/-0 (#6084 )")

## [1.6.2](https://github.com/axios/axios/compare/v1.6.1...v1.6.2) (2023-11-14)


### Features

* **withXSRFToken:** added withXSRFToken option as a workaround to achieve the old `withCredentials` behavior; ([#6046](https://github.com/axios/axios/issues/6046)) ([cff9967](https://github.com/axios/axios/commit/cff996779b272a5e94c2b52f5503ccf668bc42dc))

### PRs
- feat(withXSRFToken): added withXSRFToken option as a workaround to achieve the old &#x60;withCredentials&#x60; behavior; ( [#6046](https://api.github.com/repos/axios/axios/pulls/6046) )
```

📢 This PR added &#x27;withXSRFToken&#x27; option as a replacement for old withCredentials behaviour. 
You should now use withXSRFToken along with withCredential to get the old behavior.
This functionality is considered as a fix.
```

### Contributors to this release

- <img src="https://avatars.githubusercontent.com/u/12586868?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Dmitriy Mozgovoy](https://github.com/DigitalBrainJS "+271/-146 (#6081 #6080 #6079 #6078 #6046 #6064 #6063 )")
- <img src="https://avatars.githubusercontent.com/u/79681367?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Ng Choon Khon (CK)](https://github.com/ckng0221 "+4/-4 (#6073 )")
- <img src="https://avatars.githubusercontent.com/u/9162827?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Muhammad Noman](https://github.com/mnomanmemon "+2/-2 (#6048 )")

## [1.6.1](https://github.com/axios/axios/compare/v1.6.0...v1.6.1) (2023-11-08)


### Bug Fixes

* **formdata:** fixed content-type header normalization for non-standard browser environments; ([#6056](https://github.com/axios/axios/issues/6056)) ([dd465ab](https://github.com/axios/axios/commit/dd465ab22bbfa262c6567be6574bf46a057d5288))
* **platform:** fixed emulated browser detection in node.js environment; ([#6055](https://github.com/axios/axios/issues/6055)) ([3dc8369](https://github.com/axios/axios/commit/3dc8369e505e32a4e12c22f154c55fd63ac67fbb))

### Contributors to this release

- <img src="https://avatars.githubusercontent.com/u/12586868?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Dmitriy Mozgovoy](https://github.com/DigitalBrainJS "+432/-65 (#6059 #6056 #6055 )")
- <img src="https://avatars.githubusercontent.com/u/3982806?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Fabian Meyer](https://github.com/meyfa "+5/-2 (#5835 )")

### PRs
- feat(withXSRFToken): added withXSRFToken option as a workaround to achieve the old &#x60;withCredentials&#x60; behavior; ( [#6046](https://api.github.com/repos/axios/axios/pulls/6046) )
```

📢 This PR added &#x27;withXSRFToken&#x27; option as a replacement for old withCredentials behaviour. 
You should now use withXSRFToken along with withCredential to get the old behavior.
This functionality is considered as a fix.
```

# [1.6.0](https://github.com/axios/axios/compare/v1.5.1...v1.6.0) (2023-10-26)


### Bug Fixes

* **CSRF:** fixed CSRF vulnerability CVE-2023-45857 ([#6028](https://github.com/axios/axios/issues/6028)) ([96ee232](https://github.com/axios/axios/commit/96ee232bd3ee4de2e657333d4d2191cd389e14d0))
* **dns:** fixed lookup function decorator to work properly in node v20; ([#6011](https://github.com/axios/axios/issues/6011)) ([5aaff53](https://github.com/axios/axios/commit/5aaff532a6b820bb9ab6a8cd0f77131b47e2adb8))
* **types:** fix AxiosHeaders types; ([#5931](https://github.com/axios/axios/issues/5931)) ([a1c8ad0](https://github.com/axios/axios/commit/a1c8ad008b3c13d53e135bbd0862587fb9d3fc09))

### PRs
- CVE 2023 45857 ( [#6028](https://api.github.com/repos/axios/axios/pulls/6028) )
```

⚠️ Critical vulnerability fix. See https://security.snyk.io/vuln/SNYK-JS-AXIOS-6032459
```

### Contributors to this release

- <img src="https://avatars.githubusercontent.com/u/12586868?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Dmitriy Mozgovoy](https://github.com/DigitalBrainJS "+449/-114 (#6032 #6021 #6011 #5932 #5931 )")
- <img src="https://avatars.githubusercontent.com/u/63700910?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Valentin Panov](https://github.com/valentin-panov "+4/-4 (#6028 )")
- <img src="https://avatars.githubusercontent.com/u/76877078?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Rinku Chaudhari](https://github.com/therealrinku "+1/-1 (#5889 )")

## [1.5.1](https://github.com/axios/axios/compare/v1.5.0...v1.5.1) (2023-09-26)


### Bug Fixes

* **adapters:** improved adapters loading logic to have clear error messages; ([#5919](https://github.com/axios/axios/issues/5919)) ([e410779](https://github.com/axios/axios/commit/e4107797a7a1376f6209fbecfbbce73d3faa7859))
* **formdata:** fixed automatic addition of the `Content-Type` header for FormData in non-browser environments; ([#5917](https://github.com/axios/axios/issues/5917)) ([bc9af51](https://github.com/axios/axios/commit/bc9af51b1886d1b3529617702f2a21a6c0ed5d92))
* **headers:** allow `content-encoding` header to handle case-insensitive values ([#5890](https://github.com/axios/axios/issues/5890)) ([#5892](https://github.com/axios/axios/issues/5892)) ([4c89f25](https://github.com/axios/axios/commit/4c89f25196525e90a6e75eda9cb31ae0a2e18acd))
* **types:** removed duplicated code ([9e62056](https://github.com/axios/axios/commit/9e6205630e1c9cf863adf141c0edb9e6d8d4b149))

### Contributors to this release

- <img src="https://avatars.githubusercontent.com/u/12586868?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Dmitriy Mozgovoy](https://github.com/DigitalBrainJS "+89/-18 (#5919 #5917 )")
- <img src="https://avatars.githubusercontent.com/u/110460234?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [David Dallas](https://github.com/DavidJDallas "+11/-5 ()")
- <img src="https://avatars.githubusercontent.com/u/71556073?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Sean Sattler](https://github.com/fb-sean "+2/-8 ()")
- <img src="https://avatars.githubusercontent.com/u/4294069?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Mustafa Ateş Uzun](https://github.com/0o001 "+4/-4 ()")
- <img src="https://avatars.githubusercontent.com/u/132928043?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Przemyslaw Motacki](https://github.com/sfc-gh-pmotacki "+2/-1 (#5892 )")
- <img src="https://avatars.githubusercontent.com/u/5492927?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Michael Di Prisco](https://github.com/Cadienvan "+1/-1 ()")

### PRs
- CVE 2023 45857 ( [#6028](https://api.github.com/repos/axios/axios/pulls/6028) )
```

⚠️ Critical vulnerability fix. See https://security.snyk.io/vuln/SNYK-JS-AXIOS-6032459
```

# [1.5.0](https://github.com/axios/axios/compare/v1.4.0...v1.5.0) (2023-08-26)


### Bug Fixes

* **adapter:** make adapter loading error more clear by using platform-specific adapters explicitly ([#5837](https://github.com/axios/axios/issues/5837)) ([9a414bb](https://github.com/axios/axios/commit/9a414bb6c81796a95c6c7fe668637825458e8b6d))
* **dns:** fixed `cacheable-lookup` integration; ([#5836](https://github.com/axios/axios/issues/5836)) ([b3e327d](https://github.com/axios/axios/commit/b3e327dcc9277bdce34c7ef57beedf644b00d628))
* **headers:** added support for setting header names that overlap with class methods; ([#5831](https://github.com/axios/axios/issues/5831)) ([d8b4ca0](https://github.com/axios/axios/commit/d8b4ca0ea5f2f05efa4edfe1e7684593f9f68273))
* **headers:** fixed common Content-Type header merging; ([#5832](https://github.com/axios/axios/issues/5832)) ([8fda276](https://github.com/axios/axios/commit/8fda2766b1e6bcb72c3fabc146223083ef13ce17))


### Features

* export getAdapter function ([#5324](https://github.com/axios/axios/issues/5324)) ([ca73eb8](https://github.com/axios/axios/commit/ca73eb878df0ae2dace81fe3a7f1fb5986231bf1))
* **export:** export adapters without `unsafe` prefix ([#5839](https://github.com/axios/axios/issues/5839)) ([1601f4a](https://github.com/axios/axios/commit/1601f4a27a81ab47fea228f1e244b2c4e3ce28bf))

### Contributors to this release

- <img src="https://avatars.githubusercontent.com/u/12586868?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Dmitriy Mozgovoy](https://github.com/DigitalBrainJS "+66/-29 (#5839 #5837 #5836 #5832 #5831 )")
- <img src="https://avatars.githubusercontent.com/u/102841186?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [夜葬](https://github.com/geekact "+42/-0 (#5324 )")
- <img src="https://avatars.githubusercontent.com/u/65978976?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Jonathan Budiman](https://github.com/JBudiman00 "+30/-0 (#5788 )")
- <img src="https://avatars.githubusercontent.com/u/5492927?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Michael Di Prisco](https://github.com/Cadienvan "+3/-5 (#5791 )")

### PRs
- CVE 2023 45857 ( [#6028](https://api.github.com/repos/axios/axios/pulls/6028) )
```

⚠️ Critical vulnerability fix. See https://security.snyk.io/vuln/SNYK-JS-AXIOS-6032459
```

# [1.4.0](https://github.com/axios/axios/compare/v1.3.6...v1.4.0) (2023-04-27)


### Bug Fixes

* **formdata:** add `multipart/form-data` content type for FormData payload on custom client environments; ([#5678](https://github.com/axios/axios/issues/5678)) ([bbb61e7](https://github.com/axios/axios/commit/bbb61e70cb1185adfb1cbbb86eaf6652c48d89d1))
* **package:** export package internals with unsafe path prefix; ([#5677](https://github.com/axios/axios/issues/5677)) ([df38c94](https://github.com/axios/axios/commit/df38c949f26414d88ba29ec1e353c4d4f97eaf09))


### Features

* **dns:** added support for a custom lookup function; ([#5339](https://github.com/axios/axios/issues/5339)) ([2701911](https://github.com/axios/axios/commit/2701911260a1faa5cc5e1afe437121b330a3b7bb))
* **types:** export `AxiosHeaderValue` type. ([#5525](https://github.com/axios/axios/issues/5525)) ([726f1c8](https://github.com/axios/axios/commit/726f1c8e00cffa0461a8813a9bdcb8f8b9d762cf))


### Performance Improvements

* **merge-config:** optimize mergeConfig performance by avoiding duplicate key visits; ([#5679](https://github.com/axios/axios/issues/5679)) ([e6f7053](https://github.com/axios/axios/commit/e6f7053bf1a3e87cf1f9da8677e12e3fe829d68e))

### Contributors to this release

- <img src="https://avatars.githubusercontent.com/u/12586868?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Dmitriy Mozgovoy](https://github.com/DigitalBrainJS "+151/-16 (#5684 #5339 #5679 #5678 #5677 )")
- <img src="https://avatars.githubusercontent.com/u/47537704?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Arthur Fiorette](https://github.com/arthurfiorette "+19/-19 (#5525 )")
- <img src="https://avatars.githubusercontent.com/u/43876655?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [PIYUSH NEGI](https://github.com/npiyush97 "+2/-18 (#5670 )")

### PRs
- CVE 2023 45857 ( [#6028](https://api.github.com/repos/axios/axios/pulls/6028) )
```

⚠️ Critical vulnerability fix. See https://security.snyk.io/vuln/SNYK-JS-AXIOS-6032459
```

## [1.3.6](https://github.com/axios/axios/compare/v1.3.5...v1.3.6) (2023-04-19)


### Bug Fixes

* **types:** added transport to RawAxiosRequestConfig ([#5445](https://github.com/axios/axios/issues/5445)) ([6f360a2](https://github.com/axios/axios/commit/6f360a2531d8d70363fd9becef6a45a323f170e2))
* **utils:** make isFormData detection logic stricter to avoid unnecessary calling of the `toString` method on the target; ([#5661](https://github.com/axios/axios/issues/5661)) ([aa372f7](https://github.com/axios/axios/commit/aa372f7306295dfd1100c1c2c77ce95c95808e76))

### Contributors to this release

- <img src="https://avatars.githubusercontent.com/u/12586868?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Dmitriy Mozgovoy](https://github.com/DigitalBrainJS "+48/-10 (#5665 #5661 #5663 )")
- <img src="https://avatars.githubusercontent.com/u/5492927?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Michael Di Prisco](https://github.com/Cadienvan "+2/-0 (#5445 )")

### PRs
- CVE 2023 45857 ( [#6028](https://api.github.com/repos/axios/axios/pulls/6028) )
```

⚠️ Critical vulnerability fix. See https://security.snyk.io/vuln/SNYK-JS-AXIOS-6032459
```

## [1.3.5](https://github.com/axios/axios/compare/v1.3.4...v1.3.5) (2023-04-05)


### Bug Fixes

* **headers:** fixed isValidHeaderName to support full list of allowed characters; ([#5584](https://github.com/axios/axios/issues/5584)) ([e7decef](https://github.com/axios/axios/commit/e7decef6a99f4627e27ed9ea5b00ce8e201c3841))
* **params:** re-added the ability to set the function as `paramsSerializer` config; ([#5633](https://github.com/axios/axios/issues/5633)) ([a56c866](https://github.com/axios/axios/commit/a56c8661209d5ce5a645a05f294a0e08a6c1f6b3))

### Contributors to this release

- <img src="https://avatars.githubusercontent.com/u/12586868?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Dmitriy Mozgovoy](https://github.com/DigitalBrainJS "+28/-10 (#5633 #5584 )")

### PRs
- CVE 2023 45857 ( [#6028](https://api.github.com/repos/axios/axios/pulls/6028) )
```

⚠️ Critical vulnerability fix. See https://security.snyk.io/vuln/SNYK-JS-AXIOS-6032459
```

## [1.3.4](https://github.com/axios/axios/compare/v1.3.3...v1.3.4) (2023-02-22)


### Bug Fixes

* **blob:** added a check to make sure the Blob class is available in the browser's global scope; ([#5548](https://github.com/axios/axios/issues/5548)) ([3772c8f](https://github.com/axios/axios/commit/3772c8fe74112a56e3e9551f894d899bc3a9443a))
* **http:** fixed regression bug when handling synchronous errors inside the adapter; ([#5564](https://github.com/axios/axios/issues/5564)) ([a3b246c](https://github.com/axios/axios/commit/a3b246c9de5c3bc4b5a742e15add55b375479451))

### Contributors to this release

- <img src="https://avatars.githubusercontent.com/u/12586868?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Dmitriy Mozgovoy](https://github.com/DigitalBrainJS "+38/-26 (#5564 )")
- <img src="https://avatars.githubusercontent.com/u/19550000?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [lcysgsg](https://github.com/lcysgsg "+4/-0 (#5548 )")
- <img src="https://avatars.githubusercontent.com/u/5492927?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Michael Di Prisco](https://github.com/Cadienvan "+3/-0 (#5444 )")

### PRs
- CVE 2023 45857 ( [#6028](https://api.github.com/repos/axios/axios/pulls/6028) )
```

⚠️ Critical vulnerability fix. See https://security.snyk.io/vuln/SNYK-JS-AXIOS-6032459
```

## [1.3.3](https://github.com/axios/axios/compare/v1.3.2...v1.3.3) (2023-02-13)


### Bug Fixes

* **formdata:** added a check to make sure the FormData class is available in the browser's global scope; ([#5545](https://github.com/axios/axios/issues/5545)) ([a6dfa72](https://github.com/axios/axios/commit/a6dfa72010db5ad52db8bd13c0f98e537e8fd05d))
* **formdata:** fixed setting NaN as Content-Length for form payload in some cases; ([#5535](https://github.com/axios/axios/issues/5535)) ([c19f7bf](https://github.com/axios/axios/commit/c19f7bf770f90ae8307f4ea3104f227056912da1))
* **headers:** fixed the filtering logic of the clear method; ([#5542](https://github.com/axios/axios/issues/5542)) ([ea87ebf](https://github.com/axios/axios/commit/ea87ebfe6d1699af072b9e7cd40faf8f14b0ab93))

### Contributors to this release

- <img src="https://avatars.githubusercontent.com/u/12586868?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Dmitriy Mozgovoy](https://github.com/DigitalBrainJS "+11/-7 (#5545 #5535 #5542 )")
- <img src="https://avatars.githubusercontent.com/u/19842213?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [陈若枫](https://github.com/ruofee "+2/-2 (#5467 )")

### PRs
- CVE 2023 45857 ( [#6028](https://api.github.com/repos/axios/axios/pulls/6028) )
```

⚠️ Critical vulnerability fix. See https://security.snyk.io/vuln/SNYK-JS-AXIOS-6032459
```

## [1.3.2](https://github.com/axios/axios/compare/v1.3.1...v1.3.2) (2023-02-03)


### Bug Fixes

* **http:** treat http://localhost as base URL for relative paths to avoid `ERR_INVALID_URL` error; ([#5528](https://github.com/axios/axios/issues/5528)) ([128d56f](https://github.com/axios/axios/commit/128d56f4a0fb8f5f2ed6e0dd80bc9225fee9538c))
* **http:** use explicit import instead of TextEncoder global; ([#5530](https://github.com/axios/axios/issues/5530)) ([6b3c305](https://github.com/axios/axios/commit/6b3c305fc40c56428e0afabedc6f4d29c2830f6f))

### Contributors to this release

- <img src="https://avatars.githubusercontent.com/u/12586868?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Dmitriy Mozgovoy](https://github.com/DigitalBrainJS "+2/-1 (#5530 #5528 )")

### PRs
- CVE 2023 45857 ( [#6028](https://api.github.com/repos/axios/axios/pulls/6028) )
```

⚠️ Critical vulnerability fix. See https://security.snyk.io/vuln/SNYK-JS-AXIOS-6032459
```

## [1.3.1](https://github.com/axios/axios/compare/v1.3.0...v1.3.1) (2023-02-01)


### Bug Fixes

* **formdata:** add hotfix to use the asynchronous API to compute the content-length header value; ([#5521](https://github.com/axios/axios/issues/5521)) ([96d336f](https://github.com/axios/axios/commit/96d336f527619f21da012fe1f117eeb53e5a2120))
* **serializer:** fixed serialization of array-like objects; ([#5518](https://github.com/axios/axios/issues/5518)) ([08104c0](https://github.com/axios/axios/commit/08104c028c0f9353897b1b6691d74c440fd0c32d))

### Contributors to this release

- <img src="https://avatars.githubusercontent.com/u/12586868?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Dmitriy Mozgovoy](https://github.com/DigitalBrainJS "+27/-8 (#5521 #5518 )")

### PRs
- CVE 2023 45857 ( [#6028](https://api.github.com/repos/axios/axios/pulls/6028) )
```

⚠️ Critical vulnerability fix. See https://security.snyk.io/vuln/SNYK-JS-AXIOS-6032459
```

# [1.3.0](https://github.com/axios/axios/compare/v1.2.6...v1.3.0) (2023-01-31)


### Bug Fixes

* **headers:** fixed & optimized clear method; ([#5507](https://github.com/axios/axios/issues/5507)) ([9915635](https://github.com/axios/axios/commit/9915635c69d0ab70daca5738488421f67ca60959))
* **http:** add zlib headers if missing ([#5497](https://github.com/axios/axios/issues/5497)) ([65e8d1e](https://github.com/axios/axios/commit/65e8d1e28ce829f47a837e45129730e541950d3c))


### Features

* **fomdata:** added support for spec-compliant FormData & Blob types; ([#5316](https://github.com/axios/axios/issues/5316)) ([6ac574e](https://github.com/axios/axios/commit/6ac574e00a06731288347acea1e8246091196953))

### Contributors to this release

- <img src="https://avatars.githubusercontent.com/u/12586868?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [Dmitriy Mozgovoy](https://github.com/DigitalBrainJS "+352/-67 (#5514 #5512 #5510 #5509 #5508 #5316 #5507 )")
- <img src="https://avatars.githubusercontent.com/u/35015993?v&#x3D;4&amp;s&#x3D;18" alt="avatar" width="18"/> [ItsNotGoodName](https://github.com/ItsNotGoodName "+43/-2 (#5497 )")

### PRs
- CVE 2023 45857 ( [#6028](https://api.github.com/repos/axios/axios/pulls/6028) )
```

⚠️ Critical vulnerability fix. See https://security.snyk.io/vuln/SNYK-JS-AXIOS-6032459
```

## [1.2.6](https://github.com/axios/axios/compare/v1.2.5...v1.2.6) (2023-01-28)


### Bug Fixes

* **headers:** added missed Authorization accessor; ([#5502](https://github.com/axios/axios/issues/5502)) ([342c0ba](https://github.com/axios/axios/commit/342c0ba9a16ea50f5ed7d2366c5c1a2c877e3f26))
* **types:** fixed `CommonRequestHeadersList` & `CommonResponseHeadersList` types to be private in commonJS; ([#5503](https://github.com/axios/axios/issues/5503)) ([5a3d0a3](https://github.com/axios/axios/commit/5a3d0a3234d77361a1bc7cedee2da1e11df08e2c))

### Contributors to this release

- ![avatar](https://avatars.githubusercontent.com/u/12586868?v&#x3D;4&amp;s&#x3D;16) [Dmitriy Mozgovoy](https://github.com/DigitalBrainJS "+24/-9 (#5503 #5502 )")

### PRs
- CVE 2023 45857 ( [#6028](https://api.github.com/repos/axios/axios/pulls/6028) )
```

⚠️ Critical vulnerability fix. See https://security.snyk.io/vuln/SNYK-JS-AXIOS-6032459
```

## [1.2.5](https://github.com/axios/axios/compare/v1.2.4...v1.2.5) (2023-01-26)


### Bug Fixes

* **types:** fixed AxiosHeaders to handle spread syntax by making all methods non-enumerable; ([#5499](https://github.com/axios/axios/issues/5499)) ([580f1e8](https://github.com/axios/axios/commit/580f1e8033a61baa38149d59fd16019de3932c22))

### Contributors to this release

- ![avatar](https://avatars.githubusercontent.com/u/12586868?v&#x3D;4&amp;s&#x3D;16) [Dmitriy Mozgovoy](https://github.com/DigitalBrainJS "+82/-54 (#5499 )")
- ![avatar](https://avatars.githubusercontent.com/u/20516159?v&#x3D;4&amp;s&#x3D;16) [Elliot Ford](https://github.com/EFord36 "+1/-1 (#5462 )")

### PRs
- CVE 2023 45857 ( [#6028](https://api.github.com/repos/axios/axios/pulls/6028) )
```

⚠️ Critical vulnerability fix. See https://security.snyk.io/vuln/SNYK-JS-AXIOS-6032459
```

## [1.2.4](https://github.com/axios/axios/compare/v1.2.3...v1.2.4) (2023-01-22)


### Bug Fixes

* **types:** renamed `RawAxiosRequestConfig` back to `AxiosRequestConfig`; ([#5486](https://github.com/axios/axios/issues/5486)) ([2a71f49](https://github.com/axios/axios/commit/2a71f49bc6c68495fa419003a3107ed8bd703ad0))
* **types:** fix `AxiosRequestConfig` generic; ([#5478](https://github.com/axios/axios/issues/5478)) ([9bce81b](https://github.com/axios/axios/commit/186ea062da8b7d578ae78b1a5c220986b9bce81b))

### Contributors to this release

- ![avatar](https://avatars.githubusercontent.com/u/12586868?v&#x3D;4&amp;s&#x3D;16) [Dmitriy Mozgovoy](https://github.com/DigitalBrainJS "+242/-108 (#5486 #5482 )")
- ![avatar](https://avatars.githubusercontent.com/u/9430821?v&#x3D;4&amp;s&#x3D;16) [Daniel Hillmann](https://github.com/hilleer "+1/-1 (#5478 )")

### PRs
- CVE 2023 45857 ( [#6028](https://api.github.com/repos/axios/axios/pulls/6028) )
```

⚠️ Critical vulnerability fix. See https://security.snyk.io/vuln/SNYK-JS-AXIOS-6032459
```

## [1.2.3](https://github.com/axios/axios/compare/1.2.2...1.2.3) (2023-01-10)


### Bug Fixes

* **types:** fixed AxiosRequestConfig header interface by refactoring it to RawAxiosRequestConfig; ([#5420](https://github.com/axios/axios/issues/5420)) ([0811963](https://github.com/axios/axios/commit/08119634a22f1d5b19f5c9ea0adccb6d3eebc3bc))

### Contributors to this release

- ![avatar](https://avatars.githubusercontent.com/u/12586868?v&#x3D;4&amp;s&#x3D;16) [Dmitriy Mozgovoy](https://github.com/DigitalBrainJS "+938/-442 (#5456 #5455 #5453 #5451 #5449 #5447 #5446 #5443 #5442 #5439 #5420 )")

### PRs
- CVE 2023 45857 ( [#6028](https://api.github.com/repos/axios/axios/pulls/6028) )
```

⚠️ Critical vulnerability fix. See https://security.snyk.io/vuln/SNYK-JS-AXIOS-6032459
```

## [1.2.2] - 2022-12-29

### Fixed
- fix(ci): fix release script inputs [#5392](https://github.com/axios/axios/pull/5392)
- fix(ci): prerelease scipts [#5377](https://github.com/axios/axios/pull/5377)
- fix(ci): release scripts [#5376](https://github.com/axios/axios/pull/5376)
- fix(ci): typescript tests [#5375](https://github.com/axios/axios/pull/5375)
- fix: Brotli decompression [#5353](https://github.com/axios/axios/pull/5353)
- fix: add missing HttpStatusCode [#5345](https://github.com/axios/axios/pull/5345)

### Chores
- chore(ci): set conventional-changelog header config [#5406](https://github.com/axios/axios/pull/5406)
- chore(ci): fix automatic contributors resolving [#5403](https://github.com/axios/axios/pull/5403)
- chore(ci): improved logging for the contributors list generator [#5398](https://github.com/axios/axios/pull/5398)
- chore(ci): fix release action [#5397](https://github.com/axios/axios/pull/5397)
- chore(ci): fix version bump script by adding bump argument for target version [#5393](https://github.com/axios/axios/pull/5393)
- chore(deps): bump decode-uri-component from 0.2.0 to 0.2.2 [#5342](https://github.com/axios/axios/pull/5342)
- chore(ci): GitHub Actions Release script [#5384](https://github.com/axios/axios/pull/5384)
- chore(ci): release scripts [#5364](https://github.com/axios/axios/pull/5364)

### Contributors to this release
- ![avatar](https://avatars.githubusercontent.com/u/12586868?v&#x3D;4&amp;s&#x3D;16) [Dmitriy Mozgovoy](https://github.com/DigitalBrainJS)
- ![avatar](https://avatars.githubusercontent.com/u/1652293?v&#x3D;4&amp;s&#x3D;16) [Winnie](https://github.com/winniehell)

## [1.2.1] - 2022-12-05

### Changed
- feat(exports): export mergeConfig [#5151](https://github.com/axios/axios/pull/5151)

### Fixed
- fix(CancelledError): include config [#4922](https://github.com/axios/axios/pull/4922)
- fix(general): removing multiple/trailing/leading whitespace [#5022](https://github.com/axios/axios/pull/5022)
- fix(headers): decompression for responses without Content-Length header [#5306](https://github.com/axios/axios/pull/5306)
- fix(webWorker): exception to sending form data in web worker [#5139](https://github.com/axios/axios/pull/5139)

### Refactors
- refactor(types): AxiosProgressEvent.event type to any [#5308](https://github.com/axios/axios/pull/5308)
- refactor(types): add missing types for static AxiosError.from method [#4956](https://github.com/axios/axios/pull/4956)

### Chores
- chore(docs): remove README link to non-existent upgrade guide [#5307](https://github.com/axios/axios/pull/5307)
- chore(docs): typo in issue template name [#5159](https://github.com/axios/axios/pull/5159)

### Contributors to this release

- [Dmitriy Mozgovoy](https://github.com/DigitalBrainJS)
- [Zachary Lysobey](https://github.com/zachlysobey)
- [Kevin Ennis](https://github.com/kevincennis)
- [Philipp Loose](https://github.com/phloose)
- [secondl1ght](https://github.com/secondl1ght)
- [wenzheng](https://github.com/0x30)
- [Ivan Barsukov](https://github.com/ovarn)
- [Arthur Fiorette](https://github.com/arthurfiorette)

### PRs
- CVE 2023 45857 ( [#6028](https://api.github.com/repos/axios/axios/pulls/6028) )
```

⚠️ Critical vulnerability fix. See https://security.snyk.io/vuln/SNYK-JS-AXIOS-6032459
```

## [1.2.0] - 2022-11-10

### Changed

- changed: refactored module exports [#5162](https://github.com/axios/axios/pull/5162)
- change: re-added support for loading Axios with require('axios').default [#5225](https://github.com/axios/axios/pull/5225)

### Fixed

- fix: improve AxiosHeaders class [#5224](https://github.com/axios/axios/pull/5224)
- fix: TypeScript type definitions for commonjs [#5196](https://github.com/axios/axios/pull/5196)
- fix: type definition of use method on AxiosInterceptorManager to match the the README [#5071](https://github.com/axios/axios/pull/5071)
- fix: __dirname is not defined in the sandbox [#5269](https://github.com/axios/axios/pull/5269)
- fix: AxiosError.toJSON method to avoid circular references [#5247](https://github.com/axios/axios/pull/5247)
- fix: Z_BUF_ERROR when content-encoding is set but the response body is empty [#5250](https://github.com/axios/axios/pull/5250)

### Refactors
- refactor: allowing adapters to be loaded by name [#5277](https://github.com/axios/axios/pull/5277)

### Chores

- chore: force CI restart [#5243](https://github.com/axios/axios/pull/5243)
- chore: update ECOSYSTEM.md [#5077](https://github.com/axios/axios/pull/5077)
- chore: update get/index.html [#5116](https://github.com/axios/axios/pull/5116)
- chore: update Sandbox UI/UX [#5205](https://github.com/axios/axios/pull/5205)
- chore:(actions): remove git credentials after checkout [#5235](https://github.com/axios/axios/pull/5235)
- chore(actions): bump actions/dependency-review-action from 2 to 3 [#5266](https://github.com/axios/axios/pull/5266)
- chore(packages): bump loader-utils from 1.4.1 to 1.4.2 [#5295](https://github.com/axios/axios/pull/5295)
- chore(packages): bump engine.io from 6.2.0 to 6.2.1 [#5294](https://github.com/axios/axios/pull/5294)
- chore(packages): bump socket.io-parser from 4.0.4 to 4.0.5 [#5241](https://github.com/axios/axios/pull/5241)
- chore(packages): bump loader-utils from 1.4.0 to 1.4.1 [#5245](https://github.com/axios/axios/pull/5245)
- chore(docs): update Resources links in README [#5119](https://github.com/axios/axios/pull/5119)
- chore(docs): update the link for JSON url [#5265](https://github.com/axios/axios/pull/5265)
- chore(docs): fix broken links [#5218](https://github.com/axios/axios/pull/5218)
- chore(docs): update and rename UPGRADE_GUIDE.md to MIGRATION_GUIDE.md [#5170](https://github.com/axios/axios/pull/5170)
- chore(docs): typo fix line #856 and #920 [#5194](https://github.com/axios/axios/pull/5194)
- chore(docs): typo fix #800 [#5193](https://github.com/axios/axios/pull/5193)
- chore(docs): fix typos [#5184](https://github.com/axios/axios/pull/5184)
- chore(docs): fix punctuation in README.md [#5197](https://github.com/axios/axios/pull/5197)
- chore(docs): update readme in the Handling Errors section - issue reference #5260 [#5261](https://github.com/axios/axios/pull/5261)
- chore: remove \b from filename [#5207](https://github.com/axios/axios/pull/5207)
- chore(docs): update CHANGELOG.md [#5137](https://github.com/axios/axios/pull/5137)
- chore: add sideEffects false to package.json [#5025](https://github.com/axios/axios/pull/5025)

### Contributors to this release

- [Maddy Miller](https://github.com/me4502)
- [Amit Saini](https://github.com/amitsainii)
- [ecyrbe](https://github.com/ecyrbe)
- [Ikko Ashimine](https://github.com/eltociear)
- [Geeth Gunnampalli](https://github.com/thetechie7)
- [Shreem Asati](https://github.com/shreem-123)
- [Frieder Bluemle](https://github.com/friederbluemle)
- [윤세영](https://github.com/yunseyeong)
- [Claudio Busatto](https://github.com/cjcbusatto)
- [Remco Haszing](https://github.com/remcohaszing)
- [Dmitriy Mozgovoy](https://github.com/DigitalBrainJS)
- [Csaba Maulis](https://github.com/om4csaba)
- [MoPaMo](https://github.com/MoPaMo)
- [Daniel Fjeldstad](https://github.com/w3bdesign)
- [Adrien Brunet](https://github.com/adrien-may)
- [Frazer Smith](https://github.com/Fdawgs)
- [HaiTao](https://github.com/836334258)
- [AZM](https://github.com/aziyatali)
- [relbns](https://github.com/relbns)

### PRs
- CVE 2023 45857 ( [#6028](https://api.github.com/repos/axios/axios/pulls/6028) )
```

⚠️ Critical vulnerability fix. See https://security.snyk.io/vuln/SNYK-JS-AXIOS-6032459
```

## [1.1.3] - 2022-10-15

### Added

- Added custom params serializer support [#5113](https://github.com/axios/axios/pull/5113)

### Fixed

- Fixed top-level export to keep them in-line with static properties [#5109](https://github.com/axios/axios/pull/5109)
- Stopped including null values to query string. [#5108](https://github.com/axios/axios/pull/5108)
- Restored proxy config backwards compatibility with 0.x [#5097](https://github.com/axios/axios/pull/5097)
- Added back AxiosHeaders in AxiosHeaderValue [#5103](https://github.com/axios/axios/pull/5103)
- Pin CDN install instructions to a specific version [#5060](https://github.com/axios/axios/pull/5060)
- Handling of array values fixed for AxiosHeaders [#5085](https://github.com/axios/axios/pull/5085)

### Chores

- docs: match badge style, add link to them [#5046](https://github.com/axios/axios/pull/5046)
- chore: fixing comments typo [#5054](https://github.com/axios/axios/pull/5054)
- chore: update issue template [#5061](https://github.com/axios/axios/pull/5061)
- chore: added progress capturing section to the docs; [#5084](https://github.com/axios/axios/pull/5084)

### Contributors to this release

- [Jason Saayman](https://github.com/jasonsaayman)
- [scarf](https://github.com/scarf005)
- [Lenz Weber-Tronic](https://github.com/phryneas)
- [Arvindh](https://github.com/itsarvindh)
- [Félix Legrelle](https://github.com/FelixLgr)
- [Patrick Petrovic](https://github.com/ppati000)
- [Dmitriy Mozgovoy](https://github.com/DigitalBrainJS)
- [littledian](https://github.com/littledian)
- [ChronosMasterOfAllTime](https://github.com/ChronosMasterOfAllTime)

### PRs
- CVE 2023 45857 ( [#6028](https://api.github.com/repos/axios/axios/pulls/6028) )
```

⚠️ Critical vulnerability fix. See https://security.snyk.io/vuln/SNYK-JS-AXIOS-6032459
```

## [1.1.2] - 2022-10-07

### Fixed

- Fixed broken exports for UMD builds.

### Contributors to this release

- [Jason Saayman](https://github.com/jasonsaayman)

### PRs
- CVE 2023 45857 ( [#6028](https://api.github.com/repos/axios/axios/pulls/6028) )
```

⚠️ Critical vulnerability fix. See https://security.snyk.io/vuln/SNYK-JS-AXIOS-6032459
```

## [1.1.1] - 2022-10-07

### Fixed

- Fixed broken exports for common js. This fix breaks a prior fix, I will fix both issues ASAP but the commonJS use is more impactful.

### Contributors to this release

- [Jason Saayman](https://github.com/jasonsaayman)

### PRs
- CVE 2023 45857 ( [#6028](https://api.github.com/repos/axios/axios/pulls/6028) )
```

⚠️ Critical vulnerability fix. See https://security.snyk.io/vuln/SNYK-JS-AXIOS-6032459
```

## [1.1.0] - 2022-10-06

### Fixed

- Fixed missing exports in type definition index.d.ts [#5003](https://github.com/axios/axios/pull/5003)
- Fixed query params composing [#5018](https://github.com/axios/axios/pull/5018)
- Fixed GenericAbortSignal interface by making it more generic [#5021](https://github.com/axios/axios/pull/5021)
- Fixed adding "clear" to AxiosInterceptorManager [#5010](https://github.com/axios/axios/pull/5010)
- Fixed commonjs & umd exports [#5030](https://github.com/axios/axios/pull/5030)
- Fixed inability to access response headers when using axios 1.x with Jest [#5036](https://github.com/axios/axios/pull/5036)

### Contributors to this release

- [Trim21](https://github.com/trim21)
- [Dmitriy Mozgovoy](https://github.com/DigitalBrainJS)
- [shingo.sasaki](https://github.com/s-sasaki-0529)
- [Ivan Pepelko](https://github.com/ivanpepelko)
- [Richard Kořínek](https://github.com/risa)

### PRs
- CVE 2023 45857 ( [#6028](https://api.github.com/repos/axios/axios/pulls/6028) )
```

⚠️ Critical vulnerability fix. See https://security.snyk.io/vuln/SNYK-JS-AXIOS-6032459
```

## [1.0.0] - 2022-10-04

### Added

- Added stack trace to AxiosError [#4624](https://github.com/axios/axios/pull/4624)
- Add AxiosError to AxiosStatic [#4654](https://github.com/axios/axios/pull/4654)
- Replaced Rollup as our build runner [#4596](https://github.com/axios/axios/pull/4596)
- Added generic TS types for the exposed toFormData helper [#4668](https://github.com/axios/axios/pull/4668)
- Added listen callback function [#4096](https://github.com/axios/axios/pull/4096)
- Added instructions for installing using PNPM [#4207](https://github.com/axios/axios/pull/4207)
- Added generic AxiosAbortSignal TS interface to avoid importing AbortController polyfill [#4229](https://github.com/axios/axios/pull/4229)
- Added axios-url-template in ECOSYSTEM.md [#4238](https://github.com/axios/axios/pull/4238)
- Added a clear() function to the request and response interceptors object so a user can ensure that all interceptors have been removed from an axios instance [#4248](https://github.com/axios/axios/pull/4248)
- Added react hook plugin [#4319](https://github.com/axios/axios/pull/4319)
- Adding HTTP status code for transformResponse [#4580](https://github.com/axios/axios/pull/4580)
- Added blob to the list of protocols supported by the browser [#4678](https://github.com/axios/axios/pull/4678)
- Resolving proxy from env on redirect [#4436](https://github.com/axios/axios/pull/4436)
- Added enhanced toFormData implementation with additional options [4704](https://github.com/axios/axios/pull/4704)
- Adding Canceler parameters config and request [#4711](https://github.com/axios/axios/pull/4711)
- Added automatic payload serialization to application/x-www-form-urlencoded [#4714](https://github.com/axios/axios/pull/4714)
- Added the ability for webpack users to overwrite built-ins [#4715](https://github.com/axios/axios/pull/4715)
- Added string[] to AxiosRequestHeaders type [#4322](https://github.com/axios/axios/pull/4322)
- Added the ability for the url-encoded-form serializer to respect the formSerializer config [#4721](https://github.com/axios/axios/pull/4721)
- Added isCancel type assert [#4293](https://github.com/axios/axios/pull/4293)
- Added data URL support for node.js [#4725](https://github.com/axios/axios/pull/4725)
- Adding types for progress event callbacks [#4675](https://github.com/axios/axios/pull/4675)
- URL params serializer [#4734](https://github.com/axios/axios/pull/4734)
- Added axios.formToJSON method [#4735](https://github.com/axios/axios/pull/4735)
- Bower platform add data protocol [#4804](https://github.com/axios/axios/pull/4804)
- Use WHATWG URL API instead of url.parse() [#4852](https://github.com/axios/axios/pull/4852)
- Add ENUM containing Http Status Codes to typings [#4903](https://github.com/axios/axios/pull/4903)
- Improve typing of timeout in index.d.ts [#4934](https://github.com/axios/axios/pull/4934)

### Changed

- Updated AxiosError.config to be optional in the type definition [#4665](https://github.com/axios/axios/pull/4665)
- Updated README emphasizing the URLSearchParam built-in interface over other solutions [#4590](https://github.com/axios/axios/pull/4590)
- Include request and config when creating a CanceledError instance [#4659](https://github.com/axios/axios/pull/4659)
- Changed func-names eslint rule to as-needed [#4492](https://github.com/axios/axios/pull/4492)
- Replacing deprecated substr() with slice() as substr() is deprecated [#4468](https://github.com/axios/axios/pull/4468)
- Updating HTTP links in README.md to use HTTPS [#4387](https://github.com/axios/axios/pull/4387)
- Updated to a better trim() polyfill [#4072](https://github.com/axios/axios/pull/4072)
- Updated types to allow specifying partial default headers on instance create [#4185](https://github.com/axios/axios/pull/4185)
- Expanded isAxiosError types [#4344](https://github.com/axios/axios/pull/4344)
- Updated type definition for axios instance methods [#4224](https://github.com/axios/axios/pull/4224)
- Updated eslint config [#4722](https://github.com/axios/axios/pull/4722)
- Updated Docs [#4742](https://github.com/axios/axios/pull/4742)
- Refactored Axios to use ES2017 [#4787](https://github.com/axios/axios/pull/4787)


### Deprecated
- There are multiple deprecations, refactors and fixes provided in this release. Please read through the full release notes to see how this may impact your project and use case.

### Removed

- Removed incorrect argument for NetworkError constructor [#4656](https://github.com/axios/axios/pull/4656)
- Removed Webpack [#4596](https://github.com/axios/axios/pull/4596)
- Removed function that transform arguments to array [#4544](https://github.com/axios/axios/pull/4544)

### Fixed

- Fixed grammar in README [#4649](https://github.com/axios/axios/pull/4649)
- Fixed code error in README [#4599](https://github.com/axios/axios/pull/4599)
- Optimized the code that checks cancellation [#4587](https://github.com/axios/axios/pull/4587)
- Fix url pointing to defaults.js in README [#4532](https://github.com/axios/axios/pull/4532)
- Use type alias instead of interface for AxiosPromise [#4505](https://github.com/axios/axios/pull/4505)
- Fix some word spelling and lint style in code comments [#4500](https://github.com/axios/axios/pull/4500)
- Edited readme with 3 updated browser icons of Chrome, FireFox and Safari [#4414](https://github.com/axios/axios/pull/4414)
- Bump follow-redirects from 1.14.9 to 1.15.0 [#4673](https://github.com/axios/axios/pull/4673)
- Fixing http tests to avoid hanging when assertions fail [#4435](https://github.com/axios/axios/pull/4435)
- Fix TS definition for AxiosRequestTransformer [#4201](https://github.com/axios/axios/pull/4201)
- Fix grammatical issues in README [#4232](https://github.com/axios/axios/pull/4232)
- Fixing instance.defaults.headers type [#4557](https://github.com/axios/axios/pull/4557)
- Fixed race condition on immediate requests cancellation [#4261](https://github.com/axios/axios/pull/4261)
- Fixing Z_BUF_ERROR when no content [#4701](https://github.com/axios/axios/pull/4701)
- Fixing proxy beforeRedirect regression [#4708](https://github.com/axios/axios/pull/4708)
- Fixed AxiosError status code type [#4717](https://github.com/axios/axios/pull/4717)
- Fixed AxiosError stack capturing [#4718](https://github.com/axios/axios/pull/4718)
- Fixing AxiosRequestHeaders typings [#4334](https://github.com/axios/axios/pull/4334)
- Fixed max body length defaults [#4731](https://github.com/axios/axios/pull/4731)
- Fixed toFormData Blob issue on node>v17 [#4728](https://github.com/axios/axios/pull/4728)
- Bump grunt from 1.5.2 to 1.5.3 [#4743](https://github.com/axios/axios/pull/4743)
- Fixing content-type header repeated [#4745](https://github.com/axios/axios/pull/4745)
- Fixed timeout error message for http [4738](https://github.com/axios/axios/pull/4738)
- Request ignores false, 0 and empty string as body values [#4785](https://github.com/axios/axios/pull/4785)
- Added back missing minified builds [#4805](https://github.com/axios/axios/pull/4805)
- Fixed a type error [#4815](https://github.com/axios/axios/pull/4815)
- Fixed a regression bug with unsubscribing from cancel token; [#4819](https://github.com/axios/axios/pull/4819)
- Remove repeated compression algorithm [#4820](https://github.com/axios/axios/pull/4820)
- The error of calling extend to pass parameters [#4857](https://github.com/axios/axios/pull/4857)
- SerializerOptions.indexes allows boolean | null | undefined [#4862](https://github.com/axios/axios/pull/4862)
- Require interceptors to return values [#4874](https://github.com/axios/axios/pull/4874)
- Removed unused imports [#4949](https://github.com/axios/axios/pull/4949)
- Allow null indexes on formSerializer and paramsSerializer [#4960](https://github.com/axios/axios/pull/4960)

### Chores
- Set permissions for GitHub actions [#4765](https://github.com/axios/axios/pull/4765)
- Included githubactions in the dependabot config [#4770](https://github.com/axios/axios/pull/4770)
- Included dependency review [#4771](https://github.com/axios/axios/pull/4771)
- Update security.md [#4784](https://github.com/axios/axios/pull/4784)
- Remove unnecessary spaces [#4854](https://github.com/axios/axios/pull/4854)
- Simplify the import path of AxiosError [#4875](https://github.com/axios/axios/pull/4875)
- Fix Gitpod dead link [#4941](https://github.com/axios/axios/pull/4941)
- Enable syntax highlighting for a code block [#4970](https://github.com/axios/axios/pull/4970)
- Using Logo Axios in Readme.md [#4993](https://github.com/axios/axios/pull/4993)
- Fix markup for note in README [#4825](https://github.com/axios/axios/pull/4825)
- Fix typo and formatting, add colons [#4853](https://github.com/axios/axios/pull/4853)
- Fix typo in readme [#4942](https://github.com/axios/axios/pull/4942)

### Security

- Update SECURITY.md [#4687](https://github.com/axios/axios/pull/4687)

### Contributors to this release

- [Bertrand Marron](https://github.com/tusbar)
- [Dmitriy Mozgovoy](https://github.com/DigitalBrainJS)
- [Dan Mooney](https://github.com/danmooney)
- [Michael Li](https://github.com/xiaoyu-tamu)
- [aong](https://github.com/yxwzaxns)
- [Des Preston](https://github.com/despreston)
- [Ted Robertson](https://github.com/tredondo)
- [zhoulixiang](https://github.com/zh-lx)
- [Arthur Fiorette](https://github.com/arthurfiorette)
- [Kumar Shanu](https://github.com/Kr-Shanu)
- [JALAL](https://github.com/JLL32)
- [Jingyi Lin](https://github.com/MageeLin)
- [Philipp Loose](https://github.com/phloose)
- [Alexander Shchukin](https://github.com/sashsvamir)
- [Dave Cardwell](https://github.com/davecardwell)
- [Cat Scarlet](https://github.com/catscarlet)
- [Luca Pizzini](https://github.com/lpizzinidev)
- [Kai](https://github.com/Schweinepriester)
- [Maxime Bargiel](https://github.com/mbargiel)
- [Brian Helba](https://github.com/brianhelba)
- [reslear](https://github.com/reslear)
- [Jamie Slome](https://github.com/JamieSlome)
- [Landro3](https://github.com/Landro3)
- [rafw87](https://github.com/rafw87)
- [Afzal Sayed](https://github.com/afzalsayed96)
- [Koki Oyatsu](https://github.com/kaishuu0123)
- [Dave](https://github.com/wangcch)
- [暴走老七](https://github.com/baozouai)
- [Spencer](https://github.com/spalger)
- [Adrian Wieprzkowicz](https://github.com/Argeento)
- [Jamie Telin](https://github.com/lejahmie)
- [毛呆](https://github.com/aweikalee)
- [Kirill Shakirov](https://github.com/turisap)
- [Rraji Abdelbari](https://github.com/estarossa0)
- [Jelle Schutter](https://github.com/jelleschutter)
- [Tom Ceuppens](https://github.com/KyorCode)
- [Johann Cooper](https://github.com/JohannCooper)
- [Dimitris Halatsis](https://github.com/mitsos1os)
- [chenjigeng](https://github.com/chenjigeng)
- [João Gabriel Quaresma](https://github.com/joaoGabriel55)
- [Victor Augusto](https://github.com/VictorAugDB)
- [neilnaveen](https://github.com/neilnaveen)
- [Pavlos](https://github.com/psmoros)
- [Kiryl Valkovich](https://github.com/visortelle)
- [Naveen](https://github.com/naveensrinivasan)
- [wenzheng](https://github.com/0x30)
- [hcwhan](https://github.com/hcwhan)
- [Bassel Rachid](https://github.com/basselworkforce)
- [Grégoire Pineau](https://github.com/lyrixx)
- [felipedamin](https://github.com/felipedamin)
- [Karl Horky](https://github.com/karlhorky)
- [Yue JIN](https://github.com/kingyue737)
- [Usman Ali Siddiqui](https://github.com/usman250994)
- [WD](https://github.com/techbirds)
- [Günther Foidl](https://github.com/gfoidl)
- [Stephen Jennings](https://github.com/jennings)
- [C.T.Lin](https://github.com/chentsulin)
- [mia-z](https://github.com/mia-z)
- [Parth Banathia](https://github.com/Parth0105)
- [parth0105pluang](https://github.com/parth0105pluang)
- [Marco Weber](https://github.com/mrcwbr)
- [Luca Pizzini](https://github.com/lpizzinidev)
- [Willian Agostini](https://github.com/WillianAgostini)
- [Huyen Nguyen](https://github.com/huyenltnguyen)

---

# Migration Guide

## 0.x.x -> 1.1.0


---


<h3 align="center"> 🥇 Gold sponsors <br> </h3> <table align="center" width="100%"><tr width="33.333333333333336%"><td align="center" width="33.333333333333336%"> <a href="https://stytch.com/?utm_source&#x3D;oss-sponsorship&amp;utm_medium&#x3D;paid_sponsorship&amp;utm_content&#x3D;website-link&amp;utm_campaign&#x3D;axios-http" style="padding: 10px; display: inline-block"> <picture> <source width="200px" height="38px" media="(prefers-color-scheme: dark)" srcset="https://axios-http.com/assets/sponsors/stytch_white.png"> <img width="200px" height="38px" src="https://axios-http.com/assets/sponsors/stytch.png" alt="Stytch"/> </picture> </a> <p align="center" title="API-first authentication, authorization, and fraud prevention">API-first authentication, authorization, and fraud prevention</p> <p align="center"> <a href="https://stytch.com/?utm_source&#x3D;oss-sponsorship&amp;utm_medium&#x3D;paid_sponsorship&amp;utm_content&#x3D;website-link&amp;utm_campaign&#x3D;axios-http"><b>Website</b></a> | <a href="https://stytch.com/docs?utm_source&#x3D;oss-sponsorship&amp;utm_medium&#x3D;paid_sponsorship&amp;utm_content&#x3D;docs-link&amp;utm_campaign&#x3D;axios-http"><b>Documentation</b></a> | <a href="https://github.com/stytchauth/stytch-node?utm_source&#x3D;oss-sponsorship&amp;utm_medium&#x3D;paid_sponsorship&amp;utm_content&#x3D;node-sdk&amp;utm_campaign&#x3D;axios-http"><b>Node.js</b></a> </p>
</td><td align="center" width="33.333333333333336%"> <a href="https://www.principal.com/about-us?utm_source&#x3D;axios&amp;utm_medium&#x3D;sponsorlist&amp;utm_campaign&#x3D;sponsorship" style="padding: 10px; display: inline-block"> <img width="133px" height="43px" src="https://axios-http.com/assets/sponsors/principal.svg" alt="Principal Financial Group"/> </a> <p align="center" title="We’re bound by one common purpose: to give you the financial tools, resources and information you need to live your best life.">We’re bound by one common purpose: to give you the financial tools, resources and information you ne...</p> <p align="center"> <a href="https://www.principal.com/about-us?utm_source&#x3D;axios&amp;utm_medium&#x3D;readme_sponsorlist&amp;utm_campaign&#x3D;sponsorship"><b>www.principal.com</b></a> </p>
</td><td align="center" width="33.333333333333336%"> <a href="https://www.descope.com/?utm_source&#x3D;axios&amp;utm_medium&#x3D;referral&amp;utm_campaign&#x3D;axios-oss-sponsorship" style="padding: 10px; display: inline-block"> <picture> <source width="200px" height="52px" media="(prefers-color-scheme: dark)" srcset="https://axios-http.com/assets/sponsors/descope_white.png"> <img width="200px" height="52px" src="https://axios-http.com/assets/sponsors/descope.png" alt="Descope"/> </picture> </a> <p align="center" title="Hi, we&#x27;re Descope! We are building something in the authentication space for app developers and can’t wait to place it in your hands.">Hi, we&#x27;re Descope! We are building something in the authentication space for app developers and...</p> <p align="center"> <a href="https://www.descope.com/?utm_source&#x3D;axios&amp;utm_medium&#x3D;referral&amp;utm_campaign&#x3D;axios-oss-sponsorship"><b>Website</b></a> | <a href="https://docs.descope.com/?utm_source&#x3D;axios&amp;utm_medium&#x3D;referral&amp;utm_campaign&#x3D;axios-oss-sponsorship"><b>Documentation</b></a> | <a href="https://www.descope.com/community?utm_source&#x3D;axios&amp;utm_medium&#x3D;referral&amp;utm_campaign&#x3D;axios-oss-sponsorship"><b>Community</b></a> </p>
</td></tr><tr width="33.333333333333336%"><td align="center" width="33.333333333333336%"> <a href="https://buzzoid.com/buy-instagram-followers/?utm_source&#x3D;axios&amp;utm_medium&#x3D;sponsorlist&amp;utm_campaign&#x3D;sponsorship" style="padding: 10px; display: inline-block"> <img width="62px" height="70px" src="https://axios-http.com/assets/sponsors/opencollective/buzzoid-buy-instagram-followers.png" alt="Buzzoid - Buy Instagram Followers"/> </a> <p align="center" title="At Buzzoid, you can buy Instagram followers quickly, safely, and easily with just a few clicks. Rated world&#x27;s #1 IG service since 2012.">At Buzzoid, you can buy Instagram followers quickly, safely, and easily with just a few clicks. Rate...</p> <p align="center"> <a href="https://buzzoid.com/buy-instagram-followers/?utm_source&#x3D;axios&amp;utm_medium&#x3D;readme_sponsorlist&amp;utm_campaign&#x3D;sponsorship"><b>buzzoid.com</b></a> </p>
</td><td align="center" width="33.333333333333336%"> <a href="https://www.famety.com/?utm_source&#x3D;axios&amp;utm_medium&#x3D;sponsorlist&amp;utm_campaign&#x3D;sponsorship" style="padding: 10px; display: inline-block"> <img width="70px" height="70px" src="https://axios-http.com/assets/sponsors/opencollective/famety-buy-instagram-followers.png" alt="Famety - Buy Instagram Followers"/> </a> <p align="center" title="At Famety, you can grow your social media following quickly, safely, and easily with just a few clicks. Rated the world’s #1 social media service since 2013.">At Famety, you can grow your social media following quickly, safely, and easily with just a few clic...</p> <p align="center"> <a href="https://www.famety.com/?utm_source&#x3D;axios&amp;utm_medium&#x3D;readme_sponsorlist&amp;utm_campaign&#x3D;sponsorship"><b>www.famety.com</b></a> </p>
</td><td align="center" width="33.333333333333336%"> <a href="https://poprey.com/?utm_source&#x3D;axios&amp;utm_medium&#x3D;sponsorlist&amp;utm_campaign&#x3D;sponsorship" style="padding: 10px; display: inline-block"> <img width="70px" height="70px" src="https://axios-http.com/assets/sponsors/opencollective/instagram-likes.png" alt="Poprey - Buy Instagram Likes"/> </a> <p align="center" title="Buy Instagram Likes">Buy Instagram Likes</p> <p align="center"> <a href="https://poprey.com/?utm_source&#x3D;axios&amp;utm_medium&#x3D;readme_sponsorlist&amp;utm_campaign&#x3D;sponsorship"><b>poprey.com</b></a> </p>
</td></tr><tr width="33.333333333333336%"><td align="center" width="33.333333333333336%"> <a href="https://musicza.co.za/?utm_source&#x3D;axios&amp;utm_medium&#x3D;sponsorlist&amp;utm_campaign&#x3D;sponsorship" style="padding: 10px; display: inline-block"> <img width="124px" height="52px" src="https://axios-http.com/assets/sponsors/opencollective/musicza.png" alt="Tubidy"/> </a> <p align="center" title="Tubidy: Free Music and Video Downloads | MP3, MP4">Tubidy: Free Music and Video Downloads | MP3, MP4</p> <p align="center"> <a href="https://musicza.co.za/?utm_source&#x3D;axios&amp;utm_medium&#x3D;readme_sponsorlist&amp;utm_campaign&#x3D;sponsorship"><b>musicza.co.za</b></a> </p>
</td><td align="center" width="33.333333333333336%"> <a href="https://ssmarket.net/buy-youtube-subscribers?utm_source&#x3D;axios&amp;utm_medium&#x3D;sponsorlist&amp;utm_campaign&#x3D;sponsorship" style="padding: 10px; display: inline-block"> <img width="70px" height="70px" src="https://axios-http.com/assets/sponsors/opencollective/youtube-subscribers-ssmarket.png" alt="Buy Youtube Subscribers"/> </a> <p align="center" title="SS Market offers professional social media services that rapidly increase your YouTube subscriber count, elevating your channel to a powerful position.">SS Market offers professional social media services that rapidly increase your YouTube subscriber co...</p> <p align="center"> <a href="https://ssmarket.net/buy-youtube-subscribers?utm_source&#x3D;axios&amp;utm_medium&#x3D;readme_sponsorlist&amp;utm_campaign&#x3D;sponsorship"><b>ssmarket.net</b></a> </p>
</td><td align="center" width="33.333333333333336%"> <a href="https://twicsy.com/buy-instagram-followers?utm_source&#x3D;axios&amp;utm_medium&#x3D;sponsorlist&amp;utm_campaign&#x3D;sponsorship" style="padding: 10px; display: inline-block"> <img width="85px" height="70px" src="https://axios-http.com/assets/sponsors/opencollective/buy-instagram-followers-twicsy.png" alt="Buy Instagram Followers Twicsy"/> </a> <p align="center" title="Buy real Instagram followers from Twicsy starting at only $2.97. Twicsy has been voted the best site to buy followers from the likes of US Magazine.">Buy real Instagram followers from Twicsy starting at only $2.97. Twicsy has been voted the best site...</p> <p align="center"> <a href="https://twicsy.com/buy-instagram-followers?utm_source&#x3D;axios&amp;utm_medium&#x3D;readme_sponsorlist&amp;utm_campaign&#x3D;sponsorship"><b>twicsy.com</b></a> </p>
</td></tr><tr width="33.333333333333336%"><td align="center" width="33.333333333333336%"> <a href="https://opencollective.com/axios/contribute">💜 Become a sponsor</a>
</td><td align="center" width="33.333333333333336%"> <a href="https://opencollective.com/axios/contribute">💜 Become a sponsor</a>
</td><td align="center" width="33.333333333333336%"> <a href="https://opencollective.com/axios/contribute">💜 Become a sponsor</a>
</td></tr></table>

<!--<div>marker</div>-->
<br><br>
<div align="center">
   <a href="https://axios-http.com"><img src="https://axios-http.com/assets/logo.svg" /></a><br>
</div>

<p align="center">Promise based HTTP client for the browser and node.js</p>

<p align="center">
    <a href="https://axios-http.com/"><b>Website</b></a> •
    <a href="https://axios-http.com/docs/intro"><b>Documentation</b></a>
</p>

<div align="center">

[![npm version](https://img.shields.io/npm/v/axios.svg?style=flat-square)](https://www.npmjs.org/package/axios)
[![CDNJS](https://img.shields.io/cdnjs/v/axios.svg?style=flat-square)](https://cdnjs.com/libraries/axios)
[![Build status](https://img.shields.io/github/actions/workflow/status/axios/axios/ci.yml?branch=v1.x&label=CI&logo=github&style=flat-square)](https://github.com/axios/axios/actions/workflows/ci.yml)
[![Gitpod Ready-to-Code](https://img.shields.io/badge/Gitpod-Ready--to--Code-blue?logo=gitpod&style=flat-square)](https://gitpod.io/#https://github.com/axios/axios)
[![code coverage](https://img.shields.io/coveralls/mzabriskie/axios.svg?style=flat-square)](https://coveralls.io/r/mzabriskie/axios)
[![install size](https://img.shields.io/badge/dynamic/json?url=https://packagephobia.com/v2/api.json?p=axios&query=$.install.pretty&label=install%20size&style=flat-square)](https://packagephobia.now.sh/result?p=axios)
[![npm bundle size](https://img.shields.io/bundlephobia/minzip/axios?style=flat-square)](https://bundlephobia.com/package/axios@latest)
[![npm downloads](https://img.shields.io/npm/dm/axios.svg?style=flat-square)](https://npm-stat.com/charts.html?package=axios)
[![gitter chat](https://img.shields.io/gitter/room/mzabriskie/axios.svg?style=flat-square)](https://gitter.im/mzabriskie/axios)
[![code helpers](https://www.codetriage.com/axios/axios/badges/users.svg)](https://www.codetriage.com/axios/axios)
[![Known Vulnerabilities](https://snyk.io/test/npm/axios/badge.svg)](https://snyk.io/test/npm/axios)




</div>

## Table of Contents

  - [Features](#features)
  - [Browser Support](#browser-support)
  - [Installing](#installing)
    - [Package manager](#package-manager)
    - [CDN](#cdn)
  - [Example](#example)
  - [Axios API](#axios-api)
  - [Request method aliases](#request-method-aliases)
  - [Concurrency 👎](#concurrency-deprecated)
  - [Creating an instance](#creating-an-instance)
  - [Instance methods](#instance-methods)
  - [Request Config](#request-config)
  - [Response Schema](#response-schema)
  - [Config Defaults](#config-defaults)
    - [Global axios defaults](#global-axios-defaults)
    - [Custom instance defaults](#custom-instance-defaults)
    - [Config order of precedence](#config-order-of-precedence)
  - [Interceptors](#interceptors)
    - [Multiple Interceptors](#multiple-interceptors)
  - [Handling Errors](#handling-errors)
  - [Cancellation](#cancellation)
    - [AbortController](#abortcontroller)
    - [CancelToken 👎](#canceltoken-deprecated)
  - [Using application/x-www-form-urlencoded format](#using-applicationx-www-form-urlencoded-format)
    - [URLSearchParams](#urlsearchparams)
    - [Query string](#query-string-older-browsers)
    - [🆕 Automatic serialization](#-automatic-serialization-to-urlsearchparams)
  - [Using multipart/form-data format](#using-multipartform-data-format)
    - [FormData](#formdata)
    - [🆕 Automatic serialization](#-automatic-serialization-to-formdata)
  - [Files Posting](#files-posting)
  - [HTML Form Posting](#-html-form-posting-browser)
  - [🆕 Progress capturing](#-progress-capturing)
  - [🆕 Rate limiting](#-progress-capturing)
  - [🆕 AxiosHeaders](#-axiosheaders)
  - [🔥 Fetch adapter](#-fetch-adapter)
  - [Semver](#semver)
  - [Promises](#promises)
  - [TypeScript](#typescript)
  - [Resources](#resources)
  - [Credits](#credits)
  - [License](#license)

## Features

- Make [XMLHttpRequests](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest) from the browser
- Make [http](https://nodejs.org/api/http.html) requests from node.js
- Supports the [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) API
- Intercept request and response
- Transform request and response data
- Cancel requests
- Automatic transforms for [JSON](https://www.json.org/json-en.html) data
- 🆕 Automatic data object serialization to `multipart/form-data` and `x-www-form-urlencoded` body encodings
- Client side support for protecting against [XSRF](https://en.wikipedia.org/wiki/Cross-site_request_forgery)

## Browser Support

![Chrome](https://raw.githubusercontent.com/alrra/browser-logos/main/src/chrome/chrome_48x48.png) | ![Firefox](https://raw.githubusercontent.com/alrra/browser-logos/main/src/firefox/firefox_48x48.png) | ![Safari](https://raw.githubusercontent.com/alrra/browser-logos/main/src/safari/safari_48x48.png) | ![Opera](https://raw.githubusercontent.com/alrra/browser-logos/main/src/opera/opera_48x48.png) | ![Edge](https://raw.githubusercontent.com/alrra/browser-logos/main/src/edge/edge_48x48.png) |
--- | --- | --- | --- | --- |
Latest ✔ | Latest ✔ | Latest ✔ | Latest ✔ | Latest ✔ | 11 ✔ |

[![Browser Matrix](https://saucelabs.com/open_sauce/build_matrix/axios.svg)](https://saucelabs.com/u/axios)

## Installing

### Package manager

Using npm:

```bash
$ npm install axios
```

Using bower:

```bash
$ bower install axios
```

Using yarn:

```bash
$ yarn add axios
```

Using pnpm:

```bash
$ pnpm add axios
```

Using bun:

```bash
$ bun add axios
```

Once the package is installed, you can import the library using `import` or `require` approach:

```js
import axios, {isCancel, AxiosError} from 'axios';
```

You can also use the default export, since the named export is just a re-export from the Axios factory:

```js
import axios from 'axios';

console.log(axios.isCancel('something'));
````

If you use `require` for importing, **only default export is available**:

```js
const axios = require('axios');

console.log(axios.isCancel('something'));
```

For some bundlers and some ES6 linters you may need to do the following:

```js
import { default as axios } from 'axios';
```

For cases where something went wrong when trying to import a module into a custom or legacy environment,
you can try importing the module package directly:

```js
const axios = require('axios/dist/browser/axios.cjs'); // browser commonJS bundle (ES2017)
// const axios = require('axios/dist/node/axios.cjs'); // node commonJS bundle (ES2017)
```

### CDN

Using jsDelivr CDN (ES5 UMD browser module):

```html
<script src="https://cdn.jsdelivr.net/npm/axios@1.6.7/dist/axios.min.js"></script>
```

Using unpkg CDN:

```html
<script src="https://unpkg.com/axios@1.6.7/dist/axios.min.js"></script>
```

## Example

> **Note**: CommonJS usage  
> In order to gain the TypeScript typings (for intellisense / autocomplete) while using CommonJS imports with `require()`, use the following approach:

```js
import axios from 'axios';
//const axios = require('axios'); // legacy way

// Make a request for a user with a given ID
axios.get('/user?ID=12345')
  .then(function (response) {
    // handle success
    console.log(response);
  })
  .catch(function (error) {
    // handle error
    console.log(error);
  })
  .finally(function () {
    // always executed
  });

// Optionally the request above could also be done as
axios.get('/user', {
    params: {
      ID: 12345
    }
  })
  .then(function (response) {
    console.log(response);
  })
  .catch(function (error) {
    console.log(error);
  })
  .finally(function () {
    // always executed
  });

// Want to use async/await? Add the `async` keyword to your outer function/method.
async function getUser() {
  try {
    const response = await axios.get('/user?ID=12345');
    console.log(response);
  } catch (error) {
    console.error(error);
  }
}
```

> **Note**: `async/await` is part of ECMAScript 2017 and is not supported in Internet
> Explorer and older browsers, so use with caution.

Performing a `POST` request

```js
axios.post('/user', {
    firstName: 'Fred',
    lastName: 'Flintstone'
  })
  .then(function (response) {
    console.log(response);
  })
  .catch(function (error) {
    console.log(error);
  });
```

Performing multiple concurrent requests

```js
function getUserAccount() {
  return axios.get('/user/12345');
}

function getUserPermissions() {
  return axios.get('/user/12345/permissions');
}

Promise.all([getUserAccount(), getUserPermissions()])
  .then(function (results) {
    const acct = results[0];
    const perm = results[1];
  });
```

## axios API

Requests can be made by passing the relevant config to `axios`.

##### axios(config)

```js
// Send a POST request
axios({
  method: 'post',
  url: '/user/12345',
  data: {
    firstName: 'Fred',
    lastName: 'Flintstone'
  }
});
```

```js
// GET request for remote image in node.js
axios({
  method: 'get',
  url: 'https://bit.ly/2mTM3nY',
  responseType: 'stream'
})
  .then(function (response) {
    response.data.pipe(fs.createWriteStream('ada_lovelace.jpg'))
  });
```

##### axios(url[, config])

```js
// Send a GET request (default method)
axios('/user/12345');
```

### Request method aliases

For convenience, aliases have been provided for all common request methods.

##### axios.request(config)
##### axios.get(url[, config])
##### axios.delete(url[, config])
##### axios.head(url[, config])
##### axios.options(url[, config])
##### axios.post(url[, data[, config]])
##### axios.put(url[, data[, config]])
##### axios.patch(url[, data[, config]])

###### NOTE
When using the alias methods `url`, `method`, and `data` properties don't need to be specified in config.

### Concurrency (Deprecated)
Please use `Promise.all` to replace the below functions.

Helper functions for dealing with concurrent requests.

axios.all(iterable)
axios.spread(callback)

### Creating an instance

You can create a new instance of axios with a custom config.

##### axios.create([config])

```js
const instance = axios.create({
  baseURL: 'https://some-domain.com/api/',
  timeout: 1000,
  headers: {'X-Custom-Header': 'foobar'}
});
```

### Instance methods

The available instance methods are listed below. The specified config will be merged with the instance config.

##### axios#request(config)
##### axios#get(url[, config])
##### axios#delete(url[, config])
##### axios#head(url[, config])
##### axios#options(url[, config])
##### axios#post(url[, data[, config]])
##### axios#put(url[, data[, config]])
##### axios#patch(url[, data[, config]])
##### axios#getUri([config])

## Request Config

These are the available config options for making requests. Only the `url` is required. Requests will default to `GET` if `method` is not specified.

```js
{
  // `url` is the server URL that will be used for the request
  url: '/user',

  // `method` is the request method to be used when making the request
  method: 'get', // default

  // `baseURL` will be prepended to `url` unless `url` is absolute and option `allowAbsoluteUrls` is set to true.
  // It can be convenient to set `baseURL` for an instance of axios to pass relative URLs
  // to methods of that instance.
  baseURL: 'https://some-domain.com/api/',

  // `allowAbsoluteUrls` determines whether or not absolute URLs will override a configured `baseUrl`.
  // When set to true (default), absolute values for `url` will override `baseUrl`.
  // When set to false, absolute values for `url` will always be prepended by `baseUrl`.
  allowAbsoluteUrls: true,

  // `transformRequest` allows changes to the request data before it is sent to the server
  // This is only applicable for request methods 'PUT', 'POST', 'PATCH' and 'DELETE'
  // The last function in the array must return a string or an instance of Buffer, ArrayBuffer,
  // FormData or Stream
  // You may modify the headers object.
  transformRequest: [function (data, headers) {
    // Do whatever you want to transform the data

    return data;
  }],

  // `transformResponse` allows changes to the response data to be made before
  // it is passed to then/catch
  transformResponse: [function (data) {
    // Do whatever you want to transform the data

    return data;
  }],

  // `headers` are custom headers to be sent
  headers: {'X-Requested-With': 'XMLHttpRequest'},

  // `params` are the URL parameters to be sent with the request
  // Must be a plain object or a URLSearchParams object
  params: {
    ID: 12345
  },
  
  // `paramsSerializer` is an optional config that allows you to customize serializing `params`. 
  paramsSerializer: {

    // Custom encoder function which sends key/value pairs in an iterative fashion.
    encode?: (param: string): string => { /* Do custom operations here and return transformed string */ }, 
    
    // Custom serializer function for the entire parameter. Allows user to mimic pre 1.x behaviour.
    serialize?: (params: Record<string, any>, options?: ParamsSerializerOptions ), 
    
    // Configuration for formatting array indexes in the params. 
    indexes: false // Three available options: (1) indexes: null (leads to no brackets), (2) (default) indexes: false (leads to empty brackets), (3) indexes: true (leads to brackets with indexes).    
  },

  // `data` is the data to be sent as the request body
  // Only applicable for request methods 'PUT', 'POST', 'DELETE , and 'PATCH'
  // When no `transformRequest` is set, must be of one of the following types:
  // - string, plain object, ArrayBuffer, ArrayBufferView, URLSearchParams
  // - Browser only: FormData, File, Blob
  // - Node only: Stream, Buffer, FormData (form-data package)
  data: {
    firstName: 'Fred'
  },

  // syntax alternative to send data into the body
  // method post
  // only the value is sent, not the key
  data: 'Country=Brasil&City=Belo Horizonte',

  // `timeout` specifies the number of milliseconds before the request times out.
  // If the request takes longer than `timeout`, the request will be aborted.
  timeout: 1000, // default is `0` (no timeout)

  // `withCredentials` indicates whether or not cross-site Access-Control requests
  // should be made using credentials
  withCredentials: false, // default

  // `adapter` allows custom handling of requests which makes testing easier.
  // Return a promise and supply a valid response (see lib/adapters/README.md)
  adapter: function (config) {
    /* ... */
  },
  // Also, you can set the name of the built-in adapter, or provide an array with their names
  // to choose the first available in the environment
  adapter: 'xhr', // 'fetch' | 'http' | ['xhr', 'http', 'fetch']

  // `auth` indicates that HTTP Basic auth should be used, and supplies credentials.
  // This will set an `Authorization` header, overwriting any existing
  // `Authorization` custom headers you have set using `headers`.
  // Please note that only HTTP Basic auth is configurable through this parameter.
  // For Bearer tokens and such, use `Authorization` custom headers instead.
  auth: {
    username: 'janedoe',
    password: 's00pers3cret'
  },

  // `responseType` indicates the type of data that the server will respond with
  // options are: 'arraybuffer', 'document', 'json', 'text', 'stream'
  //   browser only: 'blob'
  responseType: 'json', // default

  // `responseEncoding` indicates encoding to use for decoding responses (Node.js only)
  // Note: Ignored for `responseType` of 'stream' or client-side requests
  // options are: 'ascii', 'ASCII', 'ansi', 'ANSI', 'binary', 'BINARY', 'base64', 'BASE64', 'base64url',
  // 'BASE64URL', 'hex', 'HEX', 'latin1', 'LATIN1', 'ucs-2', 'UCS-2', 'ucs2', 'UCS2', 'utf-8', 'UTF-8',
  // 'utf8', 'UTF8', 'utf16le', 'UTF16LE'
  responseEncoding: 'utf8', // default

  // `xsrfCookieName` is the name of the cookie to use as a value for xsrf token
  xsrfCookieName: 'XSRF-TOKEN', // default

  // `xsrfHeaderName` is the name of the http header that carries the xsrf token value
  xsrfHeaderName: 'X-XSRF-TOKEN', // default
    
  // `undefined` (default) - set XSRF header only for the same origin requests
  withXSRFToken: boolean | undefined | ((config: InternalAxiosRequestConfig) => boolean | undefined),

  // `onUploadProgress` allows handling of progress events for uploads
  // browser & node.js
  onUploadProgress: function ({loaded, total, progress, bytes, estimated, rate, upload = true}) {
    // Do whatever you want with the Axios progress event
  },

  // `onDownloadProgress` allows handling of progress events for downloads
  // browser & node.js
  onDownloadProgress: function ({loaded, total, progress, bytes, estimated, rate, download = true}) {
    // Do whatever you want with the Axios progress event
  },

  // `maxContentLength` defines the max size of the http response content in bytes allowed in node.js
  maxContentLength: 2000,

  // `maxBodyLength` (Node only option) defines the max size of the http request content in bytes allowed
  maxBodyLength: 2000,

  // `validateStatus` defines whether to resolve or reject the promise for a given
  // HTTP response status code. If `validateStatus` returns `true` (or is set to `null`
  // or `undefined`), the promise will be resolved; otherwise, the promise will be
  // rejected.
  validateStatus: function (status) {
    return status >= 200 && status < 300; // default
  },

  // `maxRedirects` defines the maximum number of redirects to follow in node.js.
  // If set to 0, no redirects will be followed.
  maxRedirects: 21, // default

  // `beforeRedirect` defines a function that will be called before redirect.
  // Use this to adjust the request options upon redirecting,
  // to inspect the latest response headers,
  // or to cancel the request by throwing an error
  // If maxRedirects is set to 0, `beforeRedirect` is not used.
  beforeRedirect: (options, { headers }) => {
    if (options.hostname === "example.com") {
      options.auth = "user:password";
    }
  },

  // `socketPath` defines a UNIX Socket to be used in node.js.
  // e.g. '/var/run/docker.sock' to send requests to the docker daemon.
  // Only either `socketPath` or `proxy` can be specified.
  // If both are specified, `socketPath` is used.
  socketPath: null, // default
  
  // `transport` determines the transport method that will be used to make the request.
  // If defined, it will be used. Otherwise, if `maxRedirects` is 0,
  // the default `http` or `https` library will be used, depending on the protocol specified in `protocol`.
  // Otherwise, the `httpFollow` or `httpsFollow` library will be used, again depending on the protocol,
  // which can handle redirects.
  transport: undefined, // default

  // `httpAgent` and `httpsAgent` define a custom agent to be used when performing http
  // and https requests, respectively, in node.js. This allows options to be added like
  // `keepAlive` that are not enabled by default.
  httpAgent: new http.Agent({ keepAlive: true }),
  httpsAgent: new https.Agent({ keepAlive: true }),

  // `proxy` defines the hostname, port, and protocol of the proxy server.
  // You can also define your proxy using the conventional `http_proxy` and
  // `https_proxy` environment variables. If you are using environment variables
  // for your proxy configuration, you can also define a `no_proxy` environment
  // variable as a comma-separated list of domains that should not be proxied.
  // Use `false` to disable proxies, ignoring environment variables.
  // `auth` indicates that HTTP Basic auth should be used to connect to the proxy, and
  // supplies credentials.
  // This will set an `Proxy-Authorization` header, overwriting any existing
  // `Proxy-Authorization` custom headers you have set using `headers`.
  // If the proxy server uses HTTPS, then you must set the protocol to `https`.
  proxy: {
    protocol: 'https',
    host: '127.0.0.1',
    // hostname: '127.0.0.1' // Takes precedence over 'host' if both are defined
    port: 9000,
    auth: {
      username: 'mikeymike',
      password: 'rapunz3l'
    }
  },

  // `cancelToken` specifies a cancel token that can be used to cancel the request
  // (see Cancellation section below for details)
  cancelToken: new CancelToken(function (cancel) {
  }),

  // an alternative way to cancel Axios requests using AbortController
  signal: new AbortController().signal,

  // `decompress` indicates whether or not the response body should be decompressed
  // automatically. If set to `true` will also remove the 'content-encoding' header
  // from the responses objects of all decompressed responses
  // - Node only (XHR cannot turn off decompression)
  decompress: true, // default

  // `insecureHTTPParser` boolean.
  // Indicates where to use an insecure HTTP parser that accepts invalid HTTP headers.
  // This may allow interoperability with non-conformant HTTP implementations.
  // Using the insecure parser should be avoided.
  // see options https://nodejs.org/dist/latest-v12.x/docs/api/http.html#http_http_request_url_options_callback
  // see also https://nodejs.org/en/blog/vulnerability/february-2020-security-releases/#strict-http-header-parsing-none
  insecureHTTPParser: undefined, // default

  // transitional options for backward compatibility that may be removed in the newer versions
  transitional: {
    // silent JSON parsing mode
    // `true`  - ignore JSON parsing errors and set response.data to null if parsing failed (old behaviour)
    // `false` - throw SyntaxError if JSON parsing failed (Note: responseType must be set to 'json')
    silentJSONParsing: true, // default value for the current Axios version

    // try to parse the response string as JSON even if `responseType` is not 'json'
    forcedJSONParsing: true,

    // throw ETIMEDOUT error instead of generic ECONNABORTED on request timeouts
    clarifyTimeoutError: false,
  },

  env: {
    // The FormData class to be used to automatically serialize the payload into a FormData object
    FormData: window?.FormData || global?.FormData
  },

  formSerializer: {
      visitor: (value, key, path, helpers) => {}; // custom visitor function to serialize form values
      dots: boolean; // use dots instead of brackets format
      metaTokens: boolean; // keep special endings like {} in parameter key
      indexes: boolean; // array indexes format null - no brackets, false - empty brackets, true - brackets with indexes
  },

  // http adapter only (node.js)
  maxRate: [
    100 * 1024, // 100KB/s upload limit,
    100 * 1024  // 100KB/s download limit
  ]
}
```

## Response Schema

The response for a request contains the following information.

```js
{
  // `data` is the response that was provided by the server
  data: {},

  // `status` is the HTTP status code from the server response
  status: 200,

  // `statusText` is the HTTP status message from the server response
  statusText: 'OK',

  // `headers` the HTTP headers that the server responded with
  // All header names are lowercase and can be accessed using the bracket notation.
  // Example: `response.headers['content-type']`
  headers: {},

  // `config` is the config that was provided to `axios` for the request
  config: {},

  // `request` is the request that generated this response
  // It is the last ClientRequest instance in node.js (in redirects)
  // and an XMLHttpRequest instance in the browser
  request: {}
}
```

When using `then`, you will receive the response as follows:

```js
axios.get('/user/12345')
  .then(function (response) {
    console.log(response.data);
    console.log(response.status);
    console.log(response.statusText);
    console.log(response.headers);
    console.log(response.config);
  });
```

When using `catch`, or passing a [rejection callback](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/then) as second parameter of `then`, the response will be available through the `error` object as explained in the [Handling Errors](#handling-errors) section.

## Config Defaults

You can specify config defaults that will be applied to every request.

### Global axios defaults

```js
axios.defaults.baseURL = 'https://api.example.com';

// Important: If axios is used with multiple domains, the AUTH_TOKEN will be sent to all of them.
// See below for an example using Custom instance defaults instead.
axios.defaults.headers.common['Authorization'] = AUTH_TOKEN;

axios.defaults.headers.post['Content-Type'] = 'application/x-www-form-urlencoded';
```

### Custom instance defaults

```js
// Set config defaults when creating the instance
const instance = axios.create({
  baseURL: 'https://api.example.com'
});

// Alter defaults after instance has been created
instance.defaults.headers.common['Authorization'] = AUTH_TOKEN;
```

### Config order of precedence

Config will be merged with an order of precedence. The order is library defaults found in [lib/defaults/index.js](https://github.com/axios/axios/blob/main/lib/defaults/index.js#L49), then `defaults` property of the instance, and finally `config` argument for the request. The latter will take precedence over the former. Here's an example.

```js
// Create an instance using the config defaults provided by the library
// At this point the timeout config value is `0` as is the default for the library
const instance = axios.create();

// Override timeout default for the library
// Now all requests using this instance will wait 2.5 seconds before timing out
instance.defaults.timeout = 2500;

// Override timeout for this request as it's known to take a long time
instance.get('/longRequest', {
  timeout: 5000
});
```

## Interceptors

You can intercept requests or responses before they are handled by `then` or `catch`.

```js

const instance = axios.create();

// Add a request interceptor
instance.interceptors.request.use(function (config) {
    // Do something before request is sent
    return config;
  }, function (error) {
    // Do something with request error
    return Promise.reject(error);
  });

// Add a response interceptor
instance.interceptors.response.use(function (response) {
    // Any status code that lie within the range of 2xx cause this function to trigger
    // Do something with response data
    return response;
  }, function (error) {
    // Any status codes that falls outside the range of 2xx cause this function to trigger
    // Do something with response error
    return Promise.reject(error);
  });
```

If you need to remove an interceptor later you can.

```js
const instance = axios.create();
const myInterceptor = instance.interceptors.request.use(function () {/*...*/});
axios.interceptors.request.eject(myInterceptor);
```

You can also clear all interceptors for requests or responses.
```js
const instance = axios.create();
instance.interceptors.request.use(function () {/*...*/});
instance.interceptors.request.clear(); // Removes interceptors from requests
instance.interceptors.response.use(function () {/*...*/});
instance.interceptors.response.clear(); // Removes interceptors from responses
```

You can add interceptors to a custom instance of axios.

```js
const instance = axios.create();
instance.interceptors.request.use(function () {/*...*/});
```

When you add request interceptors, they are presumed to be asynchronous by default. This can cause a delay
in the execution of your axios request when the main thread is blocked (a promise is created under the hood for
the interceptor and your request gets put on the bottom of the call stack). If your request interceptors are synchronous you can add a flag
to the options object that will tell axios to run the code synchronously and avoid any delays in request execution.

```js
axios.interceptors.request.use(function (config) {
  config.headers.test = 'I am only a header!';
  return config;
}, null, { synchronous: true });
```

If you want to execute a particular interceptor based on a runtime check,
you can add a `runWhen` function to the options object. The request interceptor will not be executed **if and only if** the return
of `runWhen` is `false`. The function will be called with the config
object (don't forget that you can bind your own arguments to it as well.) This can be handy when you have an
asynchronous request interceptor that only needs to run at certain times.

```js
function onGetCall(config) {
  return config.method === 'get';
}
axios.interceptors.request.use(function (config) {
  config.headers.test = 'special get headers';
  return config;
}, null, { runWhen: onGetCall });
```

> **Note:** options parameter(having `synchronous` and `runWhen` properties) is only supported for request interceptors at the moment.

### Multiple Interceptors

Given you add multiple response interceptors
and when the response was fulfilled
- then each interceptor is executed
- then they are executed in the order they were added
- then only the last interceptor's result is returned
- then every interceptor receives the result of its predecessor
- and when the fulfillment-interceptor throws
    - then the following fulfillment-interceptor is not called
    - then the following rejection-interceptor is called
    - once caught, another following fulfill-interceptor is called again (just like in a promise chain).

Read [the interceptor tests](./test/specs/interceptors.spec.js) for seeing all this in code.

## Error Types

There are many different axios error messages that can appear that can provide basic information about the specifics of the error and where opportunities may lie in debugging.

The general structure of axios errors is as follows:
| Property  | Definition  |
| -------- | ----------  |
| message  | A quick summary of the error message and the status it failed with. |
| name     | This defines where the error originated from. For axios, it will always be an 'AxiosError'. |
| stack    | Provides the stack trace of the error. | 
| config   | An axios config object with specific instance configurations defined by the user from when the request was made |
| code     | Represents an axios identified error. The table below lists out specific definitions for internal axios error.  |
| status   | HTTP response status code. See [here](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) for common HTTP response status code meanings. 

Below is a list of potential axios identified error:
| Code  |  Definition   |
| -------- | ----------  |
| ERR_BAD_OPTION_VALUE | Invalid or unsupported value provided in axios configuration. |
| ERR_BAD_OPTION | Invalid option provided in axios configuration. |
| ECONNABORTED | Request timed out due to exceeding timeout specified in axios configuration. |
| ETIMEDOUT | Request timed out due to exceeding default axios timelimit. |
| ERR_NETWORK | Network-related issue.
| ERR_FR_TOO_MANY_REDIRECTS | Request is redirected too many times; exceeds max redirects specified in axios configuration.
| ERR_DEPRECATED | Deprecated feature or method used in axios. 
| ERR_BAD_RESPONSE | Response cannot be parsed properly or is in an unexpected format. 
| ERR_BAD_REQUEST | Requested has unexpected format or missing required parameters. |
| ERR_CANCELED | Feature or method is canceled explicitly by the user.   
| ERR_NOT_SUPPORT | Feature or method not supported in the current axios environment. 
| ERR_INVALID_URL | Invalid URL provided for axios request.

## Handling Errors

the default behavior is to reject every response that returns with a status code that falls out of the range of 2xx and treat it as an error.

```js
axios.get('/user/12345')
  .catch(function (error) {
    if (error.response) {
      // The request was made and the server responded with a status code
      // that falls out of the range of 2xx
      console.log(error.response.data);
      console.log(error.response.status);
      console.log(error.response.headers);
    } else if (error.request) {
      // The request was made but no response was received
      // `error.request` is an instance of XMLHttpRequest in the browser and an instance of
      // http.ClientRequest in node.js
      console.log(error.request);
    } else {
      // Something happened in setting up the request that triggered an Error
      console.log('Error', error.message);
    }
    console.log(error.config);
  });
```

Using the `validateStatus` config option, you can override the default condition (status >= 200 && status < 300) and define HTTP code(s) that should throw an error.

```js
axios.get('/user/12345', {
  validateStatus: function (status) {
    return status < 500; // Resolve only if the status code is less than 500
  }
})
```

Using `toJSON` you get an object with more information about the HTTP error.

```js
axios.get('/user/12345')
  .catch(function (error) {
    console.log(error.toJSON());
  });
```

## Cancellation

### AbortController

Starting from `v0.22.0` Axios supports AbortController to cancel requests in fetch API way:

```js
const controller = new AbortController();

axios.get('/foo/bar', {
   signal: controller.signal
}).then(function(response) {
   //...
});
// cancel the request
controller.abort()
```

### CancelToken `👎deprecated`

You can also cancel a request using a *CancelToken*.

> The axios cancel token API is based on the withdrawn [cancellable promises proposal](https://github.com/tc39/proposal-cancelable-promises).

> This API is deprecated since v0.22.0 and shouldn't be used in new projects

You can create a cancel token using the `CancelToken.source` factory as shown below:

```js
const CancelToken = axios.CancelToken;
const source = CancelToken.source();

axios.get('/user/12345', {
  cancelToken: source.token
}).catch(function (thrown) {
  if (axios.isCancel(thrown)) {
    console.log('Request canceled', thrown.message);
  } else {
    // handle error
  }
});

axios.post('/user/12345', {
  name: 'new name'
}, {
  cancelToken: source.token
})

// cancel the request (the message parameter is optional)
source.cancel('Operation canceled by the user.');
```

You can also create a cancel token by passing an executor function to the `CancelToken` constructor:

```js
const CancelToken = axios.CancelToken;
let cancel;

axios.get('/user/12345', {
  cancelToken: new CancelToken(function executor(c) {
    // An executor function receives a cancel function as a parameter
    cancel = c;
  })
});

// cancel the request
cancel();
```

> **Note:** you can cancel several requests with the same cancel token/abort controller.
> If a cancellation token is already cancelled at the moment of starting an Axios request, then the request is cancelled immediately, without any attempts to make a real request.

> During the transition period, you can use both cancellation APIs, even for the same request:

## Using `application/x-www-form-urlencoded` format

### URLSearchParams

By default, axios serializes JavaScript objects to `JSON`. To send data in the [`application/x-www-form-urlencoded` format](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST) instead, you can use the [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) API, which is [supported](http://www.caniuse.com/#feat=urlsearchparams) in the vast majority of browsers,and [ Node](https://nodejs.org/api/url.html#url_class_urlsearchparams) starting with v10 (released in 2018).

```js
const params = new URLSearchParams({ foo: 'bar' });
params.append('extraparam', 'value');
axios.post('/foo', params);
```

### Query string (Older browsers)

For compatibility with very old browsers, there is a [polyfill](https://github.com/WebReflection/url-search-params) available (make sure to polyfill the global environment).

Alternatively, you can encode data using the [`qs`](https://github.com/ljharb/qs) library:

```js
const qs = require('qs');
axios.post('/foo', qs.stringify({ 'bar': 123 }));
```

Or in another way (ES6),

```js
import qs from 'qs';
const data = { 'bar': 123 };
const options = {
  method: 'POST',
  headers: { 'content-type': 'application/x-www-form-urlencoded' },
  data: qs.stringify(data),
  url,
};
axios(options);
```

### Older Node.js versions

For older Node.js engines, you can use the [`querystring`](https://nodejs.org/api/querystring.html) module as follows:

```js
const querystring = require('querystring');
axios.post('https://something.com/', querystring.stringify({ foo: 'bar' }));
```

You can also use the [`qs`](https://github.com/ljharb/qs) library.

> **Note**: The `qs` library is preferable if you need to stringify nested objects, as the `querystring` method has [known issues](https://github.com/nodejs/node-v0.x-archive/issues/1665) with that use case.

### 🆕 Automatic serialization to URLSearchParams

Axios will automatically serialize the data object to urlencoded format if the content-type header is set to "application/x-www-form-urlencoded".

```js
const data = {
  x: 1,
  arr: [1, 2, 3],
  arr2: [1, [2], 3],
  users: [{name: 'Peter', surname: 'Griffin'}, {name: 'Thomas', surname: 'Anderson'}],
};

await axios.postForm('https://postman-echo.com/post', data,
  {headers: {'content-type': 'application/x-www-form-urlencoded'}}
);
```

The server will handle it as:

```js
  {
    x: '1',
    'arr[]': [ '1', '2', '3' ],
    'arr2[0]': '1',
    'arr2[1][0]': '2',
    'arr2[2]': '3',
    'arr3[]': [ '1', '2', '3' ],
    'users[0][name]': 'Peter',
    'users[0][surname]': 'griffin',
    'users[1][name]': 'Thomas',
    'users[1][surname]': 'Anderson'
  }
````

If your backend body-parser (like `body-parser` of `express.js`) supports nested objects decoding, you will get the same object on the server-side automatically

```js
  var app = express();

  app.use(bodyParser.urlencoded({ extended: true })); // support encoded bodies

  app.post('/', function (req, res, next) {
     // echo body as JSON
     res.send(JSON.stringify(req.body));
  });

  server = app.listen(3000);
```

## Using `multipart/form-data` format

### FormData

To send the data as a `multipart/formdata` you need to pass a formData instance as a payload.
Setting the `Content-Type` header is not required as Axios guesses it based on the payload type.

```js
const formData = new FormData();
formData.append('foo', 'bar');

axios.post('https://httpbin.org/post', formData);
```

In node.js, you can use the [`form-data`](https://github.com/form-data/form-data) library as follows:

```js
const FormData = require('form-data');

const form = new FormData();
form.append('my_field', 'my value');
form.append('my_buffer', new Buffer(10));
form.append('my_file', fs.createReadStream('/foo/bar.jpg'));

axios.post('https://example.com', form)
```

### 🆕 Automatic serialization to FormData

Starting from `v0.27.0`, Axios supports automatic object serialization to a FormData object if the request `Content-Type`
header is set to `multipart/form-data`.

The following request will submit the data in a FormData format (Browser & Node.js):

```js
import axios from 'axios';

axios.post('https://httpbin.org/post', {x: 1}, {
  headers: {
    'Content-Type': 'multipart/form-data'
  }
}).then(({data}) => console.log(data));
```

In the `node.js` build, the ([`form-data`](https://github.com/form-data/form-data)) polyfill is used by default.

You can overload the FormData class by setting the `env.FormData` config variable,
but you probably won't need it in most cases:

```js
const axios = require('axios');
var FormData = require('form-data');

axios.post('https://httpbin.org/post', {x: 1, buf: new Buffer(10)}, {
  headers: {
    'Content-Type': 'multipart/form-data'
  }
}).then(({data}) => console.log(data));
```

Axios FormData serializer supports some special endings to perform the following operations:

- `{}` - serialize the value with JSON.stringify
- `[]` - unwrap the array-like object as separate fields with the same key

> **Note**: unwrap/expand operation will be used by default on arrays and FileList objects

FormData serializer supports additional options via `config.formSerializer: object` property to handle rare cases:

- `visitor: Function` - user-defined visitor function that will be called recursively to serialize the data object
to a `FormData` object by following custom rules.

- `dots: boolean = false` - use dot notation instead of brackets to serialize arrays and objects;

- `metaTokens: boolean = true` - add the special ending (e.g `user{}: '{"name": "John"}'`) in the FormData key.
The back-end body-parser could potentially use this meta-information to automatically parse the value as JSON.

- `indexes: null|false|true = false` - controls how indexes will be added to unwrapped keys of `flat` array-like objects.

    - `null` - don't add brackets (`arr: 1`, `arr: 2`, `arr: 3`)
    - `false`(default) - add empty brackets (`arr[]: 1`, `arr[]: 2`, `arr[]: 3`)
    - `true` - add brackets with indexes  (`arr[0]: 1`, `arr[1]: 2`, `arr[2]: 3`)

Let's say we have an object like this one:

```js
const obj = {
  x: 1,
  arr: [1, 2, 3],
  arr2: [1, [2], 3],
  users: [{name: 'Peter', surname: 'Griffin'}, {name: 'Thomas', surname: 'Anderson'}],
  'obj2{}': [{x:1}]
};
```

The following steps will be executed by the Axios serializer internally:

```js
const formData = new FormData();
formData.append('x', '1');
formData.append('arr[]', '1');
formData.append('arr[]', '2');
formData.append('arr[]', '3');
formData.append('arr2[0]', '1');
formData.append('arr2[1][0]', '2');
formData.append('arr2[2]', '3');
formData.append('users[0][name]', 'Peter');
formData.append('users[0][surname]', 'Griffin');
formData.append('users[1][name]', 'Thomas');
formData.append('users[1][surname]', 'Anderson');
formData.append('obj2{}', '[{"x":1}]');
```

Axios supports the following shortcut methods: `postForm`, `putForm`, `patchForm`
which are just the corresponding http methods with the `Content-Type` header preset to `multipart/form-data`.

## Files Posting

You can easily submit a single file:

```js
await axios.postForm('https://httpbin.org/post', {
  'myVar' : 'foo',
  'file': document.querySelector('#fileInput').files[0]
});
```

or multiple files as `multipart/form-data`:

```js
await axios.postForm('https://httpbin.org/post', {
  'files[]': document.querySelector('#fileInput').files
});
```

`FileList` object can be passed directly:

```js
await axios.postForm('https://httpbin.org/post', document.querySelector('#fileInput').files)
```

All files will be sent with the same field names: `files[]`.

## 🆕 HTML Form Posting (browser)

Pass HTML Form element as a payload to submit it as `multipart/form-data` content.

```js
await axios.postForm('https://httpbin.org/post', document.querySelector('#htmlForm'));
```

`FormData` and `HTMLForm` objects can also be posted as `JSON` by explicitly setting the `Content-Type` header to `application/json`:

```js
await axios.post('https://httpbin.org/post', document.querySelector('#htmlForm'), {
  headers: {
    'Content-Type': 'application/json'
  }
})
```

For example, the Form

```html
<form id="form">
  <input type="text" name="foo" value="1">
  <input type="text" name="deep.prop" value="2">
  <input type="text" name="deep prop spaced" value="3">
  <input type="text" name="baz" value="4">
  <input type="text" name="baz" value="5">

  <select name="user.age">
    <option value="value1">Value 1</option>
    <option value="value2" selected>Value 2</option>
    <option value="value3">Value 3</option>
  </select>

  <input type="submit" value="Save">
</form>
```

will be submitted as the following JSON object:

```js
{
  "foo": "1",
  "deep": {
    "prop": {
      "spaced": "3"
    }
  },
  "baz": [
    "4",
    "5"
  ],
  "user": {
    "age": "value2"
  }
}
````

Sending `Blobs`/`Files` as JSON (`base64`) is not currently supported.

## 🆕 Progress capturing

Axios supports both browser and node environments to capture request upload/download progress.
The frequency of progress events is forced to be limited to `3` times per second.

```js    
await axios.post(url, data, {
  onUploadProgress: function (axiosProgressEvent) {
    /*{
      loaded: number;
      total?: number;
      progress?: number; // in range [0..1]
      bytes: number; // how many bytes have been transferred since the last trigger (delta)
      estimated?: number; // estimated time in seconds
      rate?: number; // upload speed in bytes
      upload: true; // upload sign
    }*/
  },

  onDownloadProgress: function (axiosProgressEvent) {
    /*{
      loaded: number;
      total?: number;
      progress?: number;
      bytes: number; 
      estimated?: number;
      rate?: number; // download speed in bytes
      download: true; // download sign
    }*/
  }
});  
```

You can also track stream upload/download progress in node.js:

```js
const {data} = await axios.post(SERVER_URL, readableStream, {
   onUploadProgress: ({progress}) => {
     console.log((progress * 100).toFixed(2));
   },
  
   headers: {
    'Content-Length': contentLength
   },

   maxRedirects: 0 // avoid buffering the entire stream
});
````

> **Note:**
> Capturing FormData upload progress is not currently supported in node.js environments.

> **⚠️ Warning**
> It is recommended to disable redirects by setting maxRedirects: 0 to upload the stream in the **node.js** environment,
> as follow-redirects package will buffer the entire stream in RAM without following the "backpressure" algorithm.


## 🆕 Rate limiting

Download and upload rate limits can only be set for the http adapter (node.js):

```js
const {data} = await axios.post(LOCAL_SERVER_URL, myBuffer, {
  onUploadProgress: ({progress, rate}) => {
    console.log(`Upload [${(progress*100).toFixed(2)}%]: ${(rate / 1024).toFixed(2)}KB/s`)
  },
   
  maxRate: [100 * 1024], // 100KB/s limit
});
```

## 🆕 AxiosHeaders

Axios has its own `AxiosHeaders` class to manipulate headers using a Map-like API that guarantees caseless work.
Although HTTP is case-insensitive in headers, Axios will retain the case of the original header for stylistic reasons
and for a workaround when servers mistakenly consider the header's case.
The old approach of directly manipulating headers object is still available, but deprecated and not recommended for future usage.

### Working with headers

An AxiosHeaders object instance can contain different types of internal values. that control setting and merging logic.
The final headers object with string values is obtained by Axios by calling the `toJSON` method.

> Note: By JSON here we mean an object consisting only of string values intended to be sent over the network.

The header value can be one of the following types:
- `string` - normal string value that will be sent to the server
- `null` - skip header when rendering to JSON
- `false` - skip header when rendering to JSON, additionally indicates that `set` method must be called with `rewrite` option set to `true`
  to overwrite this value (Axios uses this internally to allow users to opt out of installing certain headers like `User-Agent` or `Content-Type`)
- `undefined` - value is not set

> Note: The header value is considered set if it is not equal to undefined.

The headers object is always initialized inside interceptors and transformers:

```ts
  axios.interceptors.request.use((request: InternalAxiosRequestConfig) => {
      request.headers.set('My-header', 'value');

      request.headers.set({
        "My-set-header1": "my-set-value1",
        "My-set-header2": "my-set-value2"
      });
      
      request.headers.set('User-Agent', false); // disable subsequent setting the header by Axios

      request.headers.setContentType('text/plain');
    
      request.headers['My-set-header2'] = 'newValue' // direct access is deprecated
    
      return request;
    }
  );
````

You can iterate over an `AxiosHeaders` instance using a `for...of` statement:

````js
const headers = new AxiosHeaders({
  foo: '1',
  bar: '2',
  baz: '3'
});

for(const [header, value] of headers) {
  console.log(header, value);
}

// foo 1
// bar 2
// baz 3
````

### new AxiosHeaders(headers?)

Constructs a new `AxiosHeaders` instance. 

```
constructor(headers?: RawAxiosHeaders | AxiosHeaders | string);
```

If the headers object is a string, it will be parsed as RAW HTTP headers.

````js
const headers = new AxiosHeaders(`
Host: www.bing.com
User-Agent: curl/7.54.0
Accept: */*`);

console.log(headers);

// Object [AxiosHeaders] {
//   host: 'www.bing.com',
//   'user-agent': 'curl/7.54.0',
//   accept: '*/*'
// }
````

### AxiosHeaders#set

```ts
set(headerName, value: Axios, rewrite?: boolean);
set(headerName, value, rewrite?: (this: AxiosHeaders, value: string, name: string, headers: RawAxiosHeaders) => boolean);
set(headers?: RawAxiosHeaders | AxiosHeaders | string, rewrite?: boolean);
```

The `rewrite` argument controls the overwriting behavior:
- `false` - do not overwrite if header's value is set (is not `undefined`)
- `undefined` (default) - overwrite the header unless its value is set to `false`
- `true` - rewrite anyway

The option can also accept a user-defined function that determines whether the value should be overwritten or not.

Returns `this`.

### AxiosHeaders#get(header)

```
  get(headerName: string, matcher?: true | AxiosHeaderMatcher): AxiosHeaderValue;
  get(headerName: string, parser: RegExp): RegExpExecArray | null;
````

Returns the internal value of the header. It can take an extra argument to parse the header's value with `RegExp.exec`,
matcher function or internal key-value parser.

```ts
const headers = new AxiosHeaders({
  'Content-Type': 'multipart/form-data; boundary=Asrf456BGe4h'
});

console.log(headers.get('Content-Type')); 
// multipart/form-data; boundary=Asrf456BGe4h

console.log(headers.get('Content-Type', true)); // parse key-value pairs from a string separated with \s,;= delimiters:
// [Object: null prototype] {
//   'multipart/form-data': undefined,
//    boundary: 'Asrf456BGe4h'
// }


console.log(headers.get('Content-Type', (value, name, headers) => {
  return String(value).replace(/a/g, 'ZZZ');
}));
// multipZZZrt/form-dZZZtZZZ; boundZZZry=Asrf456BGe4h

console.log(headers.get('Content-Type', /boundary=(\w+)/)?.[0]);
// boundary=Asrf456BGe4h

```

Returns the value of the header.

### AxiosHeaders#has(header, matcher?)

```
has(header: string, matcher?: AxiosHeaderMatcher): boolean;
```

Returns `true` if the header is set (has no `undefined` value).

### AxiosHeaders#delete(header, matcher?)

```
delete(header: string | string[], matcher?: AxiosHeaderMatcher): boolean;
```

Returns `true` if at least one header has been removed.

### AxiosHeaders#clear(matcher?)

```
clear(matcher?: AxiosHeaderMatcher): boolean;
```

Removes all headers. 
Unlike the `delete` method matcher, this optional matcher will be used to match against the header name rather than the value.

```ts
const headers = new AxiosHeaders({
  'foo': '1',
  'x-foo': '2',
  'x-bar': '3',
});

console.log(headers.clear(/^x-/)); // true

console.log(headers.toJSON()); // [Object: null prototype] { foo: '1' }
```

Returns `true` if at least one header has been cleared.

### AxiosHeaders#normalize(format);

If the headers object was changed directly, it can have duplicates with the same name but in different cases.
This method normalizes the headers object by combining duplicate keys into one.
Axios uses this method internally after calling each interceptor.
Set `format` to true for converting headers name to lowercase and capitalize the initial letters (`cOntEnt-type` => `Content-Type`)

```js
const headers = new AxiosHeaders({
  'foo': '1',
});

headers.Foo = '2';
headers.FOO = '3';

console.log(headers.toJSON()); // [Object: null prototype] { foo: '1', Foo: '2', FOO: '3' }
console.log(headers.normalize().toJSON()); // [Object: null prototype] { foo: '3' }
console.log(headers.normalize(true).toJSON()); // [Object: null prototype] { Foo: '3' }
```

Returns `this`.

### AxiosHeaders#concat(...targets)

```
concat(...targets: Array<AxiosHeaders | RawAxiosHeaders | string | undefined | null>): AxiosHeaders;
```

Merges the instance with targets into a new `AxiosHeaders` instance. If the target is a string, it will be parsed as RAW HTTP headers.

Returns a new `AxiosHeaders` instance.

### AxiosHeaders#toJSON(asStrings?)

````
toJSON(asStrings?: boolean): RawAxiosHeaders;
````

Resolve all internal headers values into a new null prototype object. 
Set `asStrings` to true to resolve arrays as a string containing all elements, separated by commas.

### AxiosHeaders.from(thing?)

````
from(thing?: AxiosHeaders | RawAxiosHeaders | string): AxiosHeaders;
````

Returns a new `AxiosHeaders` instance created from the raw headers passed in,
or simply returns the given headers object if it's an `AxiosHeaders` instance.

### AxiosHeaders.concat(...targets)

````
concat(...targets: Array<AxiosHeaders | RawAxiosHeaders | string | undefined | null>): AxiosHeaders;
````

Returns a new `AxiosHeaders` instance created by merging the target objects.

### Shortcuts

The following shortcuts are available:

- `setContentType`, `getContentType`, `hasContentType`

- `setContentLength`, `getContentLength`, `hasContentLength`

- `setAccept`, `getAccept`, `hasAccept`

- `setUserAgent`, `getUserAgent`, `hasUserAgent`

- `setContentEncoding`, `getContentEncoding`, `hasContentEncoding`

## 🔥 Fetch adapter

Fetch adapter was introduced in `v1.7.0`. By default, it will be used if `xhr` and `http` adapters are not available in the build,
or not supported by the environment.
To use it by default, it must be selected explicitly:

```js
const {data} = axios.get(url, {
  adapter: 'fetch' // by default ['xhr', 'http', 'fetch']
})
```

You can create a separate instance for this:

```js
const fetchAxios = axios.create({
  adapter: 'fetch'
});

const {data} = fetchAxios.get(url);
```

The adapter supports the same functionality as `xhr` adapter, **including upload and download progress capturing**. 
Also, it supports additional response types such as `stream` and `formdata` (if supported by the environment).

## Semver

Until axios reaches a `1.0` release, breaking changes will be released with a new minor version. For example `0.5.1`, and `0.5.4` will have the same API, but `0.6.0` will have breaking changes.

## Promises

axios depends on a native ES6 Promise implementation to be [supported](https://caniuse.com/promises).
If your environment doesn't support ES6 Promises, you can [polyfill](https://github.com/jakearchibald/es6-promise).

## TypeScript

axios includes [TypeScript](https://typescriptlang.org) definitions and a type guard for axios errors.

```typescript
let user: User = null;
try {
  const { data } = await axios.get('/user?ID=12345');
  user = data.userDetails;
} catch (error) {
  if (axios.isAxiosError(error)) {
    handleAxiosError(error);
  } else {
    handleUnexpectedError(error);
  }
}
```

Because axios dual publishes with an ESM default export and a CJS `module.exports`, there are some caveats.
The recommended setting is to use `"moduleResolution": "node16"` (this is implied by `"module": "node16"`). Note that this requires TypeScript 4.7 or greater.
If use ESM, your settings should be fine.
If you compile TypeScript to CJS and you can’t use `"moduleResolution": "node 16"`, you have to enable `esModuleInterop`.
If you use TypeScript to type check CJS JavaScript code, your only option is to use `"moduleResolution": "node16"`.

## Online one-click setup

You can use Gitpod, an online IDE(which is free for Open Source) for contributing or running the examples online.

[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/axios/axios/blob/main/examples/server.js)


## Resources

* [Changelog](https://github.com/axios/axios/blob/v1.x/CHANGELOG.md)
* [Ecosystem](https://github.com/axios/axios/blob/v1.x/ECOSYSTEM.md)
* [Contributing Guide](https://github.com/axios/axios/blob/v1.x/CONTRIBUTING.md)
* [Code of Conduct](https://github.com/axios/axios/blob/v1.x/CODE_OF_CONDUCT.md)

## Credits

axios is heavily inspired by the [$http service](https://docs.angularjs.org/api/ng/service/$http) provided in [AngularJS](https://angularjs.org/). Ultimately axios is an effort to provide a standalone `$http`-like service for use outside of AngularJS.

## License

[MIT](LICENSE)


---

# axios // adapters

The modules under `adapters/` are modules that handle dispatching a request and settling a returned `Promise` once a response is received.

## Example

```js
var settle = require('./../core/settle');

module.exports = function myAdapter(config) {
  // At this point:
  //  - config has been merged with defaults
  //  - request transformers have already run
  //  - request interceptors have already run
  
  // Make the request using config provided
  // Upon response settle the Promise

  return new Promise(function(resolve, reject) {
  
    var response = {
      data: responseData,
      status: request.status,
      statusText: request.statusText,
      headers: responseHeaders,
      config: config,
      request: request
    };

    settle(resolve, reject, response);

    // From here:
    //  - response transformers will run
    //  - response interceptors will run
  });
}
```


---

# axios // core

The modules found in `core/` should be modules that are specific to the domain logic of axios. These modules would most likely not make sense to be consumed outside of the axios module, as their logic is too specific. Some examples of core modules are:

- Dispatching requests
  - Requests sent via `adapters/` (see lib/adapters/README.md)
- Managing interceptors
- Handling config


---

# axios // env

The `data.js` file is updated automatically when the package version is upgrading. Please do not edit it manually.


---

# axios // helpers

The modules found in `helpers/` should be generic modules that are _not_ specific to the domain logic of axios. These modules could theoretically be published to npm on their own and consumed by other modules or apps. Some examples of generic modules are things like:

- Browser polyfills
- Managing cookies
- Parsing HTTP headers


---

# Changelog

For changes in version v7.0.0 and up please go to [release](https://github.com/babel/babel-loader/releases)

# Old Changelog

## v6.4.1

### 🐛 Bug Fix

- Fixed reset of BABEL_ENV when options.forceEnv is used (#420) @nikopavlica

## v6.4.0

### 🚀 New Feature

- added metadata passing from babel to webpack, which is currently used by react-intl (#398) @Ognian

## v6.3.2

### 😢 Regression

- `forceEnv` was interfering with regular environment handling

## v6.3.1

### 🐛 Bug Fix

 - The new `forceEnv` options wasn't working as expected (#379) @chrisvasz

## v6.3.0

### 🚀 New Feature

- Add new config option `forceEnv` (#368) @moimael

Allow to override BABEL_ENV/NODE_ENV at loader-level. Useful for isomorphic applications which have   separate babel config for client and server.

### 🐛 Bug Fix

- Update loader-utils dependency to ^0.2.16 to fix compatibility with webpack 2 (#371) @leonaves

### 💅 Polish

- Improve FS caching to do less sync calls which improves performance slightly (#375) @akx

## v6.2.10

Support for webpack 2.2-rc has been added in this release

### 🐛 Bug Fix

- If cache directory not writable, try to fallback to tmpdir before failing

## v6.2.9

### 😢 Regression

Source maps on windows did not work correctly with v6.2.8.
Thanks @josephst

### 🏠 Internal

- Add AppVeyor to run tests on windows @danez
- Fix tests on windows (#343) @danez

## v6.2.8

### 🐛 Bug Fix

- gzipped files should have `.gz` as the extension, not `.gzip` (#326) @bjornstar
- fix options.sourceFileName gennerate bug (#260) @creeperyang

### 📝 Documentation

- Update README docs for cacheDirectory's actual behaviour (#245) @sohkai
- updates docs re: transform-runtime (#197) @gbrassey

### 🏠 Internal

- Use eslint and nyc (#321) @danez
- Adjust travis config (#320) @danez
- Use babel to compile babel-loader (#319) @danez

## v6.2.7

### 😢 Regression

Fallback to `os.tmpdir()` if no cachedir found (#318) (fixes #317) @danez

Fixes an issue with v6.2.6 when using `babel-loader` as a global package.

## v6.2.6

### 🐛 Bug Fix

- Use standard cache dir as default `cacheDirectory` (#301) @fson

Use the common cache directory, `./node_modules/.cache/babel-loader`, as the default cache directory (when the cacheDirectory setting is enabled).

```js
query: {
  cacheDirectory: true
}
```

## v6.2.5

- Don't show the call stack for a Babel error (such as when you have a syntax error)

<img width="415" alt="screenshot 2016-08-15 15 24 37" src="https://cloud.githubusercontent.com/assets/30594/17664401/727ba098-62fc-11e6-9f12-42da0cf47f14.png">

- resolve the .babelrc relative to the file path rather than the cwd (current working directory).

 * fix: more concise formatting for Babel errors (#287) (Andrey Popp)
 * fix(resolve-rc): resolve-rc relative file path (#253) (Luke Page)
 * add babel-core and preset-2015 to dev dependencies (#273) (timse)
 * chore(docs): add issue and pr templates (#280) (Joshua Wiens)
 * chore(docs): fix badge formatting (Joshua Wiens)
 * chore(ci): expand travis testing (#278) (Joshua Wiens)
 * Update README: add env vars to cacheIdentifier (#267) (Dominik Ferber)
 * add npm badge [skip ci] (Henry Zhu)
 * update [skip ci] (Henry Zhu)
 * remove jsx references as well [skip ci] (Henry Zhu)
 * Save the transform to devDependencies (Ray Booysen)
 * Remove 'react' preset (Jake Rios)
 * Removed babel-preset-react from README.md (Ben Stephenson)

## v6.2.4
 * change allowed peer deps (all webpack 2 beta versions)

## v6.2.3
 * change allowed peer deps (2.0.7-beta)

## v6.2.2
  * Update peerDependencies to accept webpack 2 [#208](https://github.com/babel/babel-loader/pull/208)
  * Remove duplicated dependencies

## v6.2.0
  * Pass true filenames [#106](https://github.com/babel/babel-loader/issues/106)
  * Remove babel-core from devDependencies

## v6.1.0

  * Merge [PR #146](https://github.com/babel/babel-loader/pull/146) Set source file name relative to options.sourceRoot
  * Merge [PR #136](https://github.com/babel/babel-loader/pull/136) use container-based infrastructure for faster build
  * Merge [PR #121](https://github.com/babel/babel-loader/pull/121) Make babelrc configurable
  * Merge [PR #113](https://github.com/babel/babel-loader/pull/113) Include BABEL_ENV || NODE_ENV in cacheIdentifier

## v6.0.1

  * Update to babel v6.

## v5.3.1

  * Merge [PR #85](https://github.com/babel/babel-loader/pull/85) - Don't override sourcemap if sourcesContent already exists.


## v5.3.1

  * Merge [PR #82](https://github.com/babel/babel-loader/pull/82) - Fallback global options to empty object to avoid conflicts with object-assign polyfill.

## v5.3.0

  * Merge [PR #79](https://github.com/babel/babel-loader/pull/79) - This should allow babel-loader to work with [enhanced-require](https://github.com/webpack/enhanced-require).

## v5.2.0

  * Include `.babelrc` file into the `cacheIdentifier` if it exists


---

> This README is for babel-loader v8/v9 with Babel v7
> If you are using legacy Babel v6, see the [7.x branch](https://github.com/babel/babel-loader/tree/7.x) docs

[![NPM Status](https://img.shields.io/npm/v/babel-loader.svg?style=flat)](https://www.npmjs.com/package/babel-loader)
[![codecov](https://codecov.io/gh/babel/babel-loader/branch/main/graph/badge.svg)](https://codecov.io/gh/babel/babel-loader)

<div align="center">
  <a href="https://github.com/babel/babel">
    <img src="https://rawgit.com/babel/logo/master/babel.svg" alt="Babel logo" width="200" height="200">
  </a>
  <a href="https://github.com/webpack/webpack">
    <img src="https://webpack.js.org/assets/icon-square-big.svg" alt="webpack logo" width="200" height="200">
  </a>
</div>

<h1 align="center">Babel Loader</h1>

This package allows transpiling JavaScript files using [Babel](https://github.com/babel/babel) and [webpack](https://github.com/webpack/webpack).

**Note**: Issues with the output should be reported on the Babel [Issues](https://github.com/babel/babel/issues) tracker.

<h2 align="center">Install</h2>

> | babel-loader | supported webpack versions | supported Babel versions | supported Node.js versions |
> |:-:|:-:|:-:|:-:|
> | 8.x | 4.x or 5.x | 7.x | >= 8.9 |
> | 9.x | 5.x | ^7.12.0 | >= 14.15.0 |


```bash
npm install -D babel-loader @babel/core @babel/preset-env webpack
```

<h2 align="center">Usage</h2>

webpack documentation: [Loaders](https://webpack.js.org/loaders/)

Within your webpack configuration object, you'll need to add the babel-loader to the list of modules, like so:

```javascript
module: {
  rules: [
    {
      test: /\.(?:js|mjs|cjs)$/,
      exclude: /node_modules/,
      use: {
        loader: 'babel-loader',
        options: {
          presets: [
            ['@babel/preset-env', { targets: "defaults" }]
          ]
        }
      }
    }
  ]
}
```

### Options

See the `babel` [options](https://babeljs.io/docs/en/options).

You can pass options to the loader by using the [`options`](https://webpack.js.org/configuration/module/#ruleoptions--rulequery) property:

```javascript
module: {
  rules: [
    {
      test: /\.(?:js|mjs|cjs)$/,
      exclude: /node_modules/,
      use: {
        loader: 'babel-loader',
        options: {
          presets: [
            ['@babel/preset-env', { targets: "defaults" }]
          ],
          plugins: ['@babel/plugin-proposal-class-properties']
        }
      }
    }
  ]
}
```

The `options` passed here will be [merged](https://babeljs.io/docs/configuration#how-babel-merges-config-items) with Babel config files, e.g. `babel.config.js` or `.babelrc`.

This loader also supports the following loader-specific option:

* `cacheDirectory`: Default `false`. When set, the given directory will be used to cache the results of the loader. Future webpack builds will attempt to read from the cache to avoid needing to run the potentially expensive Babel recompilation process on each run. If the value is set to `true` in options (`{cacheDirectory: true}`), the loader will use the default cache directory in `node_modules/.cache/babel-loader` or fallback to the default OS temporary file directory if no `node_modules` folder could be found in any root directory.

* `cacheIdentifier`: Default is a string composed by
  - the `@babel/core`'s version and the `babel-loader`'s version
  - the [merged](https://babeljs.io/docs/configuration#how-babel-merges-config-items) [Babel config](https://babeljs.io/docs/config-files), including options passed to `babel-loader` and the contents of `babel.config.js` or `.babelrc` file if they exist
  - the value of the environment variable `BABEL_ENV` with a fallback to the `NODE_ENV` environment variable.
  This can be set to a custom value to force cache busting if the identifier changes.

* `cacheCompression`: Default `true`. When set, each Babel transform output will be compressed with Gzip. If you want to opt-out of cache compression, set it to `false` -- your project may benefit from this if it transpiles thousands of files.

* `customize`: Default `null`. The path of a module that exports a `custom` callback [like the one that you'd pass to `.custom()`](#customized-loader). Since you already have to make a new file to use this, it is recommended that you instead use `.custom` to create a wrapper loader. Only use this if you _must_ continue using `babel-loader` directly, but still want to customize.

* `metadataSubscribers`: Default `[]`. Takes an array of context function names. E.g. if you passed ['myMetadataPlugin'], you'd assign a subscriber function to `context.myMetadataPlugin` within your webpack plugin's hooks & that function will be called with `metadata`.

## Troubleshooting

### babel-loader is slow!

Make sure you are transforming as few files as possible. Because you are probably matching `/\.m?js$/`, you might be transforming the `node_modules` folder or other unwanted source.

To exclude `node_modules`, see the `exclude` option in the `loaders` config as documented above.

You can also speed up babel-loader by as much as 2x by using the `cacheDirectory` option. This will cache transformations to the filesystem.

### Some files in my node_modules are not transpiled for IE 11

Although we typically recommend not compiling `node_modules`, you may need to when using libraries that do not support IE 11 or any legacy targets.

For this, you can either use a combination of `test` and `not`, or [pass a function](https://webpack.js.org/configuration/module/#condition) to your `exclude` option. You can also use negative lookahead regex as suggested [here](https://github.com/webpack/webpack/issues/2031#issuecomment-294706065).

```javascript
{
    test: /\.(?:js|mjs|cjs)$/,
    exclude: {
      and: [/node_modules/], // Exclude libraries in node_modules ...
      not: [
        // Except for a few of them that needs to be transpiled because they use modern syntax
        /unfetch/,
        /d3-array|d3-scale/,
        /@hapi[\\/]joi-date/,
      ]
    },
    use: {
      loader: 'babel-loader',
      options: {
        presets: [
          ['@babel/preset-env', { targets: "ie 11" }]
        ]
      }
    }
  }
```

### Babel is injecting helpers into each file and bloating my code!

Babel uses very small helpers for common functions such as `_extend`. By default, this will be added to every file that requires it.

You can instead require the Babel runtime as a separate module to avoid the duplication.

The following configuration disables automatic per-file runtime injection in Babel, requiring `@babel/plugin-transform-runtime` instead and making all helper references use it.

See the [docs](https://babeljs.io/docs/plugins/transform-runtime/) for more information.

**NOTE**: You must run `npm install -D @babel/plugin-transform-runtime` to include this in your project and `@babel/runtime` itself as a dependency with `npm install @babel/runtime`.

```javascript
rules: [
  // the 'transform-runtime' plugin tells Babel to
  // require the runtime instead of inlining it.
  {
    test: /\.(?:js|mjs|cjs)$/,
    exclude: /node_modules/,
    use: {
      loader: 'babel-loader',
      options: {
        presets: [
          ['@babel/preset-env', { targets: "defaults" }]
        ],
        plugins: ['@babel/plugin-transform-runtime']
      }
    }
  }
]
```

#### **NOTE**: transform-runtime & custom polyfills (e.g. Promise library)

Since [@babel/plugin-transform-runtime](https://github.com/babel/babel/tree/main/packages/babel-plugin-transform-runtime) includes a polyfill that includes a custom [regenerator-runtime](https://github.com/facebook/regenerator/blob/master/packages/regenerator-runtime/runtime.js) and [core-js](https://github.com/zloirock/core-js), the following usual shimming method using `webpack.ProvidePlugin` will not work:

```javascript
// ...
        new webpack.ProvidePlugin({
            'Promise': 'bluebird'
        }),
// ...
```

The following approach will not work either:

```javascript
require('@babel/runtime/core-js/promise').default = require('bluebird');

var promise = new Promise;
```

which outputs to (using `runtime`):

```javascript
'use strict';

var _Promise = require('@babel/runtime/core-js/promise')['default'];

require('@babel/runtime/core-js/promise')['default'] = require('bluebird');

var promise = new _Promise();
```

The previous `Promise` library is referenced and used before it is overridden.

One approach is to have a "bootstrap" step in your application that would first override the default globals before your application:

```javascript
// bootstrap.js

require('@babel/runtime/core-js/promise').default = require('bluebird');

// ...

require('./app');
```

### The Node.js API for `babel` has been moved to `babel-core`.

If you receive this message, it means that you have the npm package `babel` installed and are using the short notation of the loader in the webpack config (which is not valid anymore as of webpack 2.x):
```javascript
  {
    test: /\.(?:js|mjs|cjs)$/,
    loader: 'babel',
  }
```

webpack then tries to load the `babel` package instead of the `babel-loader`.

To fix this, you should uninstall the npm package `babel`, as it is deprecated in Babel v6. (Instead, install `@babel/cli` or `@babel/core`.)
In the case one of your dependencies is installing `babel` and you cannot uninstall it yourself, use the complete name of the loader in the webpack config:
```javascript
  {
    test: /\.(?:js|mjs|cjs)$/,
    loader: 'babel-loader',
  }
```

### Exclude libraries that should not be transpiled

`core-js` and `webpack/buildin` will cause errors if they are transpiled by Babel.

You will need to exclude them form `babel-loader`.

```js
{
  "loader": "babel-loader",
  "options": {
    "exclude": [
      // \\ for Windows, / for macOS and Linux
      /node_modules[\\/]core-js/,
      /node_modules[\\/]webpack[\\/]buildin/,
    ],
    "presets": [
      "@babel/preset-env"
    ]
  }
}
```

### Top level function (IIFE) is still arrow (on Webpack 5)

That function is injected by Webpack itself _after_ running `babel-loader`. By default Webpack asumes that your target environment supports some ES2015 features, but you can overwrite this behavior using the `output.environment` Webpack option ([documentation](https://webpack.js.org/configuration/output/#outputenvironment)).

To avoid the top-level arrow function, you can use `output.environment.arrowFunction`:

```js
// webpack.config.js
module.exports = {
  // ...
  output: {
    // ...
    environment: {
      // ...
      arrowFunction: false, // <-- this line does the trick
    },
  },
};
```

## Customize config based on webpack target

Webpack supports bundling multiple [targets](https://webpack.js.org/concepts/targets/). For cases where you may want different Babel configurations for each target (like `web` _and_ `node`), this loader provides a `target` property via Babel's [caller](https://babeljs.io/docs/en/config-files#apicallercb) API.

For example, to change the environment targets passed to `@babel/preset-env` based on the webpack target:

```javascript
// babel.config.js

module.exports = api => {
  return {
    plugins: [
      "@babel/plugin-proposal-nullish-coalescing-operator",
      "@babel/plugin-proposal-optional-chaining"
    ],
    presets: [
      [
        "@babel/preset-env",
        {
          useBuiltIns: "entry",
          // caller.target will be the same as the target option from webpack
          targets: api.caller(caller => caller && caller.target === "node")
            ? { node: "current" }
            : { chrome: "58", ie: "11" }
        }
      ]
    ]
  }
}
```

## Customized Loader

`babel-loader` exposes a loader-builder utility that allows users to add custom handling
of Babel's configuration for each file that it processes.

`.custom` accepts a callback that will be called with the loader's instance of
`babel` so that tooling can ensure that it using exactly the same `@babel/core`
instance as the loader itself.

In cases where you want to customize without actually having a file to call `.custom`, you
may also pass the `customize` option with a string pointing at a file that exports
your `custom` callback function.

### Example

```js
// Export from "./my-custom-loader.js" or whatever you want.
module.exports = require("babel-loader").custom(babel => {
  // Extract the custom options in the custom plugin
  function myPlugin(api, { opt1, opt2 }) {
    return {
      visitor: {},
    };
  }

  return {
    // Passed the loader options.
    customOptions({ opt1, opt2, ...loader }) {
      return {
        // Pull out any custom options that the loader might have.
        custom: { opt1, opt2 },

        // Pass the options back with the two custom options removed.
        loader,
      };
    },

    // Passed Babel's 'PartialConfig' object.
    config(cfg, { customOptions }) {
      if (cfg.hasFilesystemConfig()) {
        // Use the normal config
        return cfg.options;
      }

      return {
        ...cfg.options,
        plugins: [
          ...(cfg.options.plugins || []),

          // Include a custom plugin in the options and passing it the customOptions object.
          [myPlugin, customOptions],
        ],
      };
    },

    result(result) {
      return {
        ...result,
        code: result.code + "\n// Generated by some custom loader",
      };
    },
  };
});
```

```js
// And in your Webpack config
module.exports = {
  // ..
  module: {
    rules: [{
      // ...
      loader: path.join(__dirname, 'my-custom-loader.js'),
      // ...
    }]
  }
};
```

### `customOptions(options: Object): { custom: Object, loader: Object }`

Given the loader's options, split custom options out of `babel-loader`'s
options.


### `config(cfg: PartialConfig, options: { source, customOptions }): Object`

Given Babel's `PartialConfig` object, return the `options` object that should
be passed to `babel.transform`.


### `result(result: Result): Result`

Given Babel's result object, allow loaders to make additional tweaks to it.


## License
[MIT](https://couto.mit-license.org/)


---

## Unreleased

## v2.3.3
- [Fix] Generate webpack-compatible output with static string arg (#84)
- [Fix] Handle visiting the same path gracefully (#71)

## v2.3.2
- [Fix] avoid using reserved param name in babel 7 templates
- [Dev Deps] update `airbnb-js-shims`

## v2.3.1
- [Fix] Evaluate `import()` argument synchronously (#85)
- [Dev Deps] update `eslint`, `eslint-config-airbnb-base`, `in-publish`, `rimraf`, `safe-publish-latest`, `tape`

## v2.3.0
- [New] expose createDynamicImportTransform and getImportSource (#75)
- [Docs] Document noInterop option (#70)

## v2.2.0
- [Refactor] remove dependency on babel-plugin-syntax-dynamic-import
- [Dev Deps] update `airbnb-js-shims`, `babel-preset-airbnb`, `eslint`

## v2.1.0
- [New] add `noInterop` option (#57)
- [Docs] Fix typo "correct" -> "correctly" in readme (#55)
- [Dev Deps] update `airbnb-js-shims`, `babel-eslint`, `babel-preset-airbnb`, `eslint`, `eslint-config-airbnb-base`, `eslint-plugin-import`, `safe-publish-latest`

## v2.0.0
- [Breaking] always return a module namespace object (#52, #47)
- [Breaking] remove `.default` on entry points (#27)
- [Docs] removed $ before npm command (#35)
- [Docs] Improve README.md with a code example (#41)
- [Dev Deps] update `airbnb-js-shims`, `babel-core`, `babel-eslint`, `eslint`, `eslint-plugin-import`
- [Tests] switch from mocha to tape, so we can support older nodes

## v1.2.0
- [New] support comments (#37)
- [Refactor] Use template and types from the babel object (#32)
- [Tests] on `node` `v9`; pin included builds to LTS
- [Dev Deps] update `eslint`, `eslint-config-airbnb-base`, `mocha`, `rimraf`

## v1.1.0
- Visit Import nodes instead of CallExpressions (#30)
- [Deps] update `babel-template`, `babel-types`
- [Dev Deps] update `airbnb-js-shims`, `babel-cli`, `babel-core`, `babel-preset-airbnb`, `babel-register`, `chai`, `eslint`, `eslint-config-airbnb-base`, `eslint-plugin-import`, `mocha`
- [Tests] on `node` `v8`
- [Tests] use `nvm install-latest-npm` so newer npm doesn’t break older node

## v1.0.2
- [Fix] Ensure it works with the ES2015 preset too (#12, #16)
- [Deps] update `babel-template`, `babel-types`
- [Dev Deps] update `babel-cli`, `babel-core`, `babel-eslint`, `babel-register`, `eslint`, `eslint-config-airbnb-base`, `mocha`

## v1.0.1
- [Fix] Move `in-publish` to devDeps (#11)
- [Fix] ensure dynamic `import()` input is properly stringified (#2)
- [Fix] async timing of dynamic import to match spec (#3)
- [Fix] Remove spaces in template strings and update Babel (#10)
- [Deps] update `babel-template`, `babel-types`
- [Deps] update `babel-types` (#4, #5, #6)
- [Dev Deps] update `babel-cli`, `babel-core`, `babel-eslint`, `babel-register`, `eslint`, `eslint-config-airbnb-base`, `eslint-plugin-import`, `mocha`, `rimraf`

## v1.0.0
- Initial full release.


---

# babel-plugin-dynamic-import-node

Babel plugin to transpile `import()` to a deferred `require()`, for node. Matches the [proposed spec](https://github.com/domenic/proposal-import-function).

**NOTE:** Babylon >= v6.12.0 is required to correctly parse dynamic imports.

## Installation

```sh
npm install babel-plugin-dynamic-import-node --save-dev
```

## Usage

### Via `.babelrc` (Recommended)

**.babelrc**

```json
{
  "plugins": ["dynamic-import-node"]
}
```

#### Options

- *`noInterop`* - A boolean value, that if true will not interop the require calls. Useful to avoid using `require('module').default` on commonjs modules.

```json
{
  "plugins": [
    ["dynamic-import-node", { "noInterop": true }]
  ]
}
```

### Via CLI

```sh
$ babel --plugins dynamic-import-node script.js
```

### Via Node API

```javascript
require('babel-core').transform('code', {
  plugins: ['dynamic-import-node']
});
```

### Code Example
```javascript
Promise.all([
  import('./lib/import1'),
  import('./lib/import2')
 ]).then(([
   Import1,
   Import2
  ]) => {
   console.log(Import1);
   /* CODE HERE*/
  });
```


---

# babel-plugin-polyfill-corejs2

## Install

Using npm:

```sh
npm install --save-dev babel-plugin-polyfill-corejs2
```

or using yarn:

```sh
yarn add babel-plugin-polyfill-corejs2 --dev
```

## Usage

Add this plugin to your Babel configuration:

```json
{
  "plugins": [["polyfill-corejs2", { "method": "usage-global" }]]
}
```

This package supports the `usage-pure`, `usage-global`, and `entry-global` methods.
When `entry-global` is used, it replaces imports to `core-js`.


---

semver(1) -- The semantic versioner for npm
===========================================

## Install

```bash
npm install semver
````

## Usage

As a node module:

```js
const semver = require('semver')

semver.valid('1.2.3') // '1.2.3'
semver.valid('a.b.c') // null
semver.clean('  =v1.2.3   ') // '1.2.3'
semver.satisfies('1.2.3', '1.x || >=2.5.0 || 5.0.0 - 7.2.3') // true
semver.gt('1.2.3', '9.8.7') // false
semver.lt('1.2.3', '9.8.7') // true
semver.minVersion('>=1.0.0') // '1.0.0'
semver.valid(semver.coerce('v2')) // '2.0.0'
semver.valid(semver.coerce('42.6.7.9.3-alpha')) // '42.6.7'
```

As a command-line utility:

```
$ semver -h

A JavaScript implementation of the https://semver.org/ specification
Copyright Isaac Z. Schlueter

Usage: semver [options] <version> [<version> [...]]
Prints valid versions sorted by SemVer precedence

Options:
-r --range <range>
        Print versions that match the specified range.

-i --increment [<level>]
        Increment a version by the specified level.  Level can
        be one of: major, minor, patch, premajor, preminor,
        prepatch, or prerelease.  Default level is 'patch'.
        Only one version may be specified.

--preid <identifier>
        Identifier to be used to prefix premajor, preminor,
        prepatch or prerelease version increments.

-l --loose
        Interpret versions and ranges loosely

-p --include-prerelease
        Always include prerelease versions in range matching

-c --coerce
        Coerce a string into SemVer if possible
        (does not imply --loose)

--rtl
        Coerce version strings right to left

--ltr
        Coerce version strings left to right (default)

Program exits successfully if any valid version satisfies
all supplied ranges, and prints all satisfying versions.

If no satisfying versions are found, then exits failure.

Versions are printed in ascending order, so supplying
multiple versions to the utility will just sort them.
```

## Versions

A "version" is described by the `v2.0.0` specification found at
<https://semver.org/>.

A leading `"="` or `"v"` character is stripped off and ignored.

## Ranges

A `version range` is a set of `comparators` which specify versions
that satisfy the range.

A `comparator` is composed of an `operator` and a `version`.  The set
of primitive `operators` is:

* `<` Less than
* `<=` Less than or equal to
* `>` Greater than
* `>=` Greater than or equal to
* `=` Equal.  If no operator is specified, then equality is assumed,
  so this operator is optional, but MAY be included.

For example, the comparator `>=1.2.7` would match the versions
`1.2.7`, `1.2.8`, `2.5.3`, and `1.3.9`, but not the versions `1.2.6`
or `1.1.0`.

Comparators can be joined by whitespace to form a `comparator set`,
which is satisfied by the **intersection** of all of the comparators
it includes.

A range is composed of one or more comparator sets, joined by `||`.  A
version matches a range if and only if every comparator in at least
one of the `||`-separated comparator sets is satisfied by the version.

For example, the range `>=1.2.7 <1.3.0` would match the versions
`1.2.7`, `1.2.8`, and `1.2.99`, but not the versions `1.2.6`, `1.3.0`,
or `1.1.0`.

The range `1.2.7 || >=1.2.9 <2.0.0` would match the versions `1.2.7`,
`1.2.9`, and `1.4.6`, but not the versions `1.2.8` or `2.0.0`.

### Prerelease Tags

If a version has a prerelease tag (for example, `1.2.3-alpha.3`) then
it will only be allowed to satisfy comparator sets if at least one
comparator with the same `[major, minor, patch]` tuple also has a
prerelease tag.

For example, the range `>1.2.3-alpha.3` would be allowed to match the
version `1.2.3-alpha.7`, but it would *not* be satisfied by
`3.4.5-alpha.9`, even though `3.4.5-alpha.9` is technically "greater
than" `1.2.3-alpha.3` according to the SemVer sort rules.  The version
range only accepts prerelease tags on the `1.2.3` version.  The
version `3.4.5` *would* satisfy the range, because it does not have a
prerelease flag, and `3.4.5` is greater than `1.2.3-alpha.7`.

The purpose for this behavior is twofold.  First, prerelease versions
frequently are updated very quickly, and contain many breaking changes
that are (by the author's design) not yet fit for public consumption.
Therefore, by default, they are excluded from range matching
semantics.

Second, a user who has opted into using a prerelease version has
clearly indicated the intent to use *that specific* set of
alpha/beta/rc versions.  By including a prerelease tag in the range,
the user is indicating that they are aware of the risk.  However, it
is still not appropriate to assume that they have opted into taking a
similar risk on the *next* set of prerelease versions.

Note that this behavior can be suppressed (treating all prerelease
versions as if they were normal versions, for the purpose of range
matching) by setting the `includePrerelease` flag on the options
object to any
[functions](https://github.com/npm/node-semver#functions) that do
range matching.

#### Prerelease Identifiers

The method `.inc` takes an additional `identifier` string argument that
will append the value of the string as a prerelease identifier:

```javascript
semver.inc('1.2.3', 'prerelease', 'beta')
// '1.2.4-beta.0'
```

command-line example:

```bash
$ semver 1.2.3 -i prerelease --preid beta
1.2.4-beta.0
```

Which then can be used to increment further:

```bash
$ semver 1.2.4-beta.0 -i prerelease
1.2.4-beta.1
```

### Advanced Range Syntax

Advanced range syntax desugars to primitive comparators in
deterministic ways.

Advanced ranges may be combined in the same way as primitive
comparators using white space or `||`.

#### Hyphen Ranges `X.Y.Z - A.B.C`

Specifies an inclusive set.

* `1.2.3 - 2.3.4` := `>=1.2.3 <=2.3.4`

If a partial version is provided as the first version in the inclusive
range, then the missing pieces are replaced with zeroes.

* `1.2 - 2.3.4` := `>=1.2.0 <=2.3.4`

If a partial version is provided as the second version in the
inclusive range, then all versions that start with the supplied parts
of the tuple are accepted, but nothing that would be greater than the
provided tuple parts.

* `1.2.3 - 2.3` := `>=1.2.3 <2.4.0`
* `1.2.3 - 2` := `>=1.2.3 <3.0.0`

#### X-Ranges `1.2.x` `1.X` `1.2.*` `*`

Any of `X`, `x`, or `*` may be used to "stand in" for one of the
numeric values in the `[major, minor, patch]` tuple.

* `*` := `>=0.0.0` (Any version satisfies)
* `1.x` := `>=1.0.0 <2.0.0` (Matching major version)
* `1.2.x` := `>=1.2.0 <1.3.0` (Matching major and minor versions)

A partial version range is treated as an X-Range, so the special
character is in fact optional.

* `""` (empty string) := `*` := `>=0.0.0`
* `1` := `1.x.x` := `>=1.0.0 <2.0.0`
* `1.2` := `1.2.x` := `>=1.2.0 <1.3.0`

#### Tilde Ranges `~1.2.3` `~1.2` `~1`

Allows patch-level changes if a minor version is specified on the
comparator.  Allows minor-level changes if not.

* `~1.2.3` := `>=1.2.3 <1.(2+1).0` := `>=1.2.3 <1.3.0`
* `~1.2` := `>=1.2.0 <1.(2+1).0` := `>=1.2.0 <1.3.0` (Same as `1.2.x`)
* `~1` := `>=1.0.0 <(1+1).0.0` := `>=1.0.0 <2.0.0` (Same as `1.x`)
* `~0.2.3` := `>=0.2.3 <0.(2+1).0` := `>=0.2.3 <0.3.0`
* `~0.2` := `>=0.2.0 <0.(2+1).0` := `>=0.2.0 <0.3.0` (Same as `0.2.x`)
* `~0` := `>=0.0.0 <(0+1).0.0` := `>=0.0.0 <1.0.0` (Same as `0.x`)
* `~1.2.3-beta.2` := `>=1.2.3-beta.2 <1.3.0` Note that prereleases in
  the `1.2.3` version will be allowed, if they are greater than or
  equal to `beta.2`.  So, `1.2.3-beta.4` would be allowed, but
  `1.2.4-beta.2` would not, because it is a prerelease of a
  different `[major, minor, patch]` tuple.

#### Caret Ranges `^1.2.3` `^0.2.5` `^0.0.4`

Allows changes that do not modify the left-most non-zero element in the
`[major, minor, patch]` tuple.  In other words, this allows patch and
minor updates for versions `1.0.0` and above, patch updates for
versions `0.X >=0.1.0`, and *no* updates for versions `0.0.X`.

Many authors treat a `0.x` version as if the `x` were the major
"breaking-change" indicator.

Caret ranges are ideal when an author may make breaking changes
between `0.2.4` and `0.3.0` releases, which is a common practice.
However, it presumes that there will *not* be breaking changes between
`0.2.4` and `0.2.5`.  It allows for changes that are presumed to be
additive (but non-breaking), according to commonly observed practices.

* `^1.2.3` := `>=1.2.3 <2.0.0`
* `^0.2.3` := `>=0.2.3 <0.3.0`
* `^0.0.3` := `>=0.0.3 <0.0.4`
* `^1.2.3-beta.2` := `>=1.2.3-beta.2 <2.0.0` Note that prereleases in
  the `1.2.3` version will be allowed, if they are greater than or
  equal to `beta.2`.  So, `1.2.3-beta.4` would be allowed, but
  `1.2.4-beta.2` would not, because it is a prerelease of a
  different `[major, minor, patch]` tuple.
* `^0.0.3-beta` := `>=0.0.3-beta <0.0.4`  Note that prereleases in the
  `0.0.3` version *only* will be allowed, if they are greater than or
  equal to `beta`.  So, `0.0.3-pr.2` would be allowed.

When parsing caret ranges, a missing `patch` value desugars to the
number `0`, but will allow flexibility within that value, even if the
major and minor versions are both `0`.

* `^1.2.x` := `>=1.2.0 <2.0.0`
* `^0.0.x` := `>=0.0.0 <0.1.0`
* `^0.0` := `>=0.0.0 <0.1.0`

A missing `minor` and `patch` values will desugar to zero, but also
allow flexibility within those values, even if the major version is
zero.

* `^1.x` := `>=1.0.0 <2.0.0`
* `^0.x` := `>=0.0.0 <1.0.0`

### Range Grammar

Putting all this together, here is a Backus-Naur grammar for ranges,
for the benefit of parser authors:

```bnf
range-set  ::= range ( logical-or range ) *
logical-or ::= ( ' ' ) * '||' ( ' ' ) *
range      ::= hyphen | simple ( ' ' simple ) * | ''
hyphen     ::= partial ' - ' partial
simple     ::= primitive | partial | tilde | caret
primitive  ::= ( '<' | '>' | '>=' | '<=' | '=' ) partial
partial    ::= xr ( '.' xr ( '.' xr qualifier ? )? )?
xr         ::= 'x' | 'X' | '*' | nr
nr         ::= '0' | ['1'-'9'] ( ['0'-'9'] ) *
tilde      ::= '~' partial
caret      ::= '^' partial
qualifier  ::= ( '-' pre )? ( '+' build )?
pre        ::= parts
build      ::= parts
parts      ::= part ( '.' part ) *
part       ::= nr | [-0-9A-Za-z]+
```

## Functions

All methods and classes take a final `options` object argument.  All
options in this object are `false` by default.  The options supported
are:

- `loose`  Be more forgiving about not-quite-valid semver strings.
  (Any resulting output will always be 100% strict compliant, of
  course.)  For backwards compatibility reasons, if the `options`
  argument is a boolean value instead of an object, it is interpreted
  to be the `loose` param.
- `includePrerelease`  Set to suppress the [default
  behavior](https://github.com/npm/node-semver#prerelease-tags) of
  excluding prerelease tagged versions from ranges unless they are
  explicitly opted into.

Strict-mode Comparators and Ranges will be strict about the SemVer
strings that they parse.

* `valid(v)`: Return the parsed version, or null if it's not valid.
* `inc(v, release)`: Return the version incremented by the release
  type (`major`,   `premajor`, `minor`, `preminor`, `patch`,
  `prepatch`, or `prerelease`), or null if it's not valid
  * `premajor` in one call will bump the version up to the next major
    version and down to a prerelease of that major version.
    `preminor`, and `prepatch` work the same way.
  * If called from a non-prerelease version, the `prerelease` will work the
    same as `prepatch`. It increments the patch version, then makes a
    prerelease. If the input version is already a prerelease it simply
    increments it.
* `prerelease(v)`: Returns an array of prerelease components, or null
  if none exist. Example: `prerelease('1.2.3-alpha.1') -> ['alpha', 1]`
* `major(v)`: Return the major version number.
* `minor(v)`: Return the minor version number.
* `patch(v)`: Return the patch version number.
* `intersects(r1, r2, loose)`: Return true if the two supplied ranges
  or comparators intersect.
* `parse(v)`: Attempt to parse a string as a semantic version, returning either
  a `SemVer` object or `null`.

### Comparison

* `gt(v1, v2)`: `v1 > v2`
* `gte(v1, v2)`: `v1 >= v2`
* `lt(v1, v2)`: `v1 < v2`
* `lte(v1, v2)`: `v1 <= v2`
* `eq(v1, v2)`: `v1 == v2` This is true if they're logically equivalent,
  even if they're not the exact same string.  You already know how to
  compare strings.
* `neq(v1, v2)`: `v1 != v2` The opposite of `eq`.
* `cmp(v1, comparator, v2)`: Pass in a comparison string, and it'll call
  the corresponding function above.  `"==="` and `"!=="` do simple
  string comparison, but are included for completeness.  Throws if an
  invalid comparison string is provided.
* `compare(v1, v2)`: Return `0` if `v1 == v2`, or `1` if `v1` is greater, or `-1` if
  `v2` is greater.  Sorts in ascending order if passed to `Array.sort()`.
* `rcompare(v1, v2)`: The reverse of compare.  Sorts an array of versions
  in descending order when passed to `Array.sort()`.
* `compareBuild(v1, v2)`: The same as `compare` but considers `build` when two versions
  are equal.  Sorts in ascending order if passed to `Array.sort()`.
  `v2` is greater.  Sorts in ascending order if passed to `Array.sort()`.
* `diff(v1, v2)`: Returns difference between two versions by the release type
  (`major`, `premajor`, `minor`, `preminor`, `patch`, `prepatch`, or `prerelease`),
  or null if the versions are the same.

### Comparators

* `intersects(comparator)`: Return true if the comparators intersect

### Ranges

* `validRange(range)`: Return the valid range or null if it's not valid
* `satisfies(version, range)`: Return true if the version satisfies the
  range.
* `maxSatisfying(versions, range)`: Return the highest version in the list
  that satisfies the range, or `null` if none of them do.
* `minSatisfying(versions, range)`: Return the lowest version in the list
  that satisfies the range, or `null` if none of them do.
* `minVersion(range)`: Return the lowest version that can possibly match
  the given range.
* `gtr(version, range)`: Return `true` if version is greater than all the
  versions possible in the range.
* `ltr(version, range)`: Return `true` if version is less than all the
  versions possible in the range.
* `outside(version, range, hilo)`: Return true if the version is outside
  the bounds of the range in either the high or low direction.  The
  `hilo` argument must be either the string `'>'` or `'<'`.  (This is
  the function called by `gtr` and `ltr`.)
* `intersects(range)`: Return true if any of the ranges comparators intersect

Note that, since ranges may be non-contiguous, a version might not be
greater than a range, less than a range, *or* satisfy a range!  For
example, the range `1.2 <1.2.9 || >2.0.0` would have a hole from `1.2.9`
until `2.0.0`, so the version `1.2.10` would not be greater than the
range (because `2.0.1` satisfies, which is higher), nor less than the
range (since `1.2.8` satisfies, which is lower), and it also does not
satisfy the range.

If you want to know if a version satisfies or does not satisfy a
range, use the `satisfies(version, range)` function.

### Coercion

* `coerce(version, options)`: Coerces a string to semver if possible

This aims to provide a very forgiving translation of a non-semver string to
semver. It looks for the first digit in a string, and consumes all
remaining characters which satisfy at least a partial semver (e.g., `1`,
`1.2`, `1.2.3`) up to the max permitted length (256 characters).  Longer
versions are simply truncated (`4.6.3.9.2-alpha2` becomes `4.6.3`).  All
surrounding text is simply ignored (`v3.4 replaces v3.3.1` becomes
`3.4.0`).  Only text which lacks digits will fail coercion (`version one`
is not valid).  The maximum  length for any semver component considered for
coercion is 16 characters; longer components will be ignored
(`10000000000000000.4.7.4` becomes `4.7.4`).  The maximum value for any
semver component is `Integer.MAX_SAFE_INTEGER || (2**53 - 1)`; higher value
components are invalid (`9999999999999999.4.7.4` is likely invalid).

If the `options.rtl` flag is set, then `coerce` will return the right-most
coercible tuple that does not share an ending index with a longer coercible
tuple.  For example, `1.2.3.4` will return `2.3.4` in rtl mode, not
`4.0.0`.  `1.2.3/4` will return `4.0.0`, because the `4` is not a part of
any other overlapping SemVer tuple.

### Clean

* `clean(version)`: Clean a string to be a valid semver if possible

This will return a cleaned and trimmed semver version. If the provided version is not valid a null will be returned. This does not work for ranges. 

ex.
* `s.clean(' = v 2.1.5foo')`: `null`
* `s.clean(' = v 2.1.5foo', { loose: true })`: `'2.1.5-foo'`
* `s.clean(' = v 2.1.5-foo')`: `null`
* `s.clean(' = v 2.1.5-foo', { loose: true })`: `'2.1.5-foo'`
* `s.clean('=v2.1.5')`: `'2.1.5'`
* `s.clean('  =v2.1.5')`: `2.1.5`
* `s.clean('      2.1.5   ')`: `'2.1.5'`
* `s.clean('~1.0.0')`: `null`


---

# babel-plugin-polyfill-corejs3

## Install

Using npm:

```sh
npm install --save-dev babel-plugin-polyfill-corejs3
```

or using yarn:

```sh
yarn add babel-plugin-polyfill-corejs3 --dev
```

## Usage

Add this plugin to your Babel configuration:

```json
{
  "plugins": [["polyfill-corejs3", { "method": "usage-global", "version": "3.20" }]]
}
```

This package supports the `usage-pure`, `usage-global`, and `entry-global` methods.
When `entry-global` is used, it replaces imports to `core-js`.

## Options

See [here](../../docs/usage.md#options) for a list of options supported by every polyfill provider.

### `version`

`string`, defaults to `"3.0"`.

This option only has an effect when used alongside `"method": "usage-global"` or `"method": "usage-pure"`. It is recommended to specify the minor version you are using as `core-js@3.0` may not include polyfills for the latest features. If you are bundling an app, you can provide the version directly from your node modules:

```js
{
  plugins: [
    ["polyfill-corejs3", {
      "method": "usage-pure",
      // use `core-js/package.json` if you are using `usage-global`
      "version": require("core-js-pure/package.json").version
    }]
  ]
}
```

If you are a library author, specify a reasonably modern `core-js` version in your
`package.json` and provide the plugin the minimal supported version.

```json
{
  "dependencies": {
    "core-js": "^3.20.0"
  }
}
```
```js
{
  plugins: [
    ["polyfill-corejs3", {
      "method": "usage-global",
      // improvise if you have more complicated version spec, e.g. > 3.1.4
      "version": require("./package.json").dependencies["core-js"]
    }]
  ]
}
```

### `proposals`

`boolean`, defaults to `false`.

This option only has an effect when used alongside `"method": "usage-global"` or `"method": "usage-pure"`. When `proposals` are `true`, any ES proposal supported by core-js will be polyfilled as well.

---

`core-js-compat` exposes some files as JSON, and they cannot be
imported by Node.js ESM files.
This folder proxies `core-js-compat` to ensure that every entry
is CJS and can be safely imported.

---

# babel-plugin-polyfill-regenerator

## Install

Using npm:

```sh
npm install --save-dev babel-plugin-polyfill-regenerator
```

or using yarn:

```sh
yarn add babel-plugin-polyfill-regenerator --dev
```

## Usage

Add this plugin to your Babel configuration:

```json
{
  "plugins": [["polyfill-regenerator", { "method": "usage-global" }]]
}
```

This package supports the `usage-pure`, `usage-global`, and `entry-global` methods.
When `entry-global` is used, it replaces imports to `regenerator-runtime`.


---

# bail

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]

Throw if given an error.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`bail(err?)`](#bailerr)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Security](#security)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package throws a given error.

## When should I use this?

Use this package if you’re building some scripts that might theoretically get
errors but frequently don’t and you keep writing `if (error) throw error` over
and over again and you’re just really done with that.

## Install

This package is [ESM only][esm].
In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]:

```sh
npm install bail
```

In Deno with [Skypack][]:

```js
import {bail} from 'https://cdn.skypack.dev/bail@2?dts'
```

In browsers with [Skypack][]:

```html
<script type="module">
  import {bail} from 'https://cdn.skypack.dev/bail@2?min'
</script>
```

## Use

```js
import {bail} from 'bail'

bail()

bail(new Error('failure'))
// Error: failure
//     at repl:1:6
//     at REPLServer.defaultEval (repl.js:154:27)
//     …
```

## API

This package exports the following identifier: `bail`.
There is no default export.

### `bail(err?)`

Throw a given error (`Error?`).

## Types

This package is fully typed with [TypeScript][].
There are no extra exported types.

## Compatibility

This package is at least compatible with all maintained versions of Node.js.
As of now, that is Node.js 12.20+, 14.14+, and 16.0+.
It also works in Deno and modern browsers.

## Security

This package is safe.

## Related

*   [`noop`][noop]
*   [`noop2`][noop2]
*   [`noop3`][noop3]

## Contribute

Yes please!
See [How to Contribute to Open Source][contribute].

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/wooorm/bail/workflows/main/badge.svg

[build]: https://github.com/wooorm/bail/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/bail.svg

[coverage]: https://codecov.io/github/wooorm/bail

[downloads-badge]: https://img.shields.io/npm/dm/bail.svg

[downloads]: https://www.npmjs.com/package/bail

[size-badge]: https://img.shields.io/bundlephobia/minzip/bail.svg

[size]: https://bundlephobia.com/result?p=bail

[npm]: https://docs.npmjs.com/cli/install

[skypack]: https://www.skypack.dev

[license]: license

[author]: https://wooorm.com

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[typescript]: https://www.typescriptlang.org

[contribute]: https://opensource.guide/how-to-contribute/

[noop]: https://www.npmjs.com/package/noop

[noop2]: https://www.npmjs.com/package/noop2

[noop3]: https://www.npmjs.com/package/noop3


---

(MIT)

Copyright (c) 2013 Julian Gruber &lt;julian@juliangruber.com&gt;

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# balanced-match

Match balanced string pairs, like `{` and `}` or `<b>` and `</b>`. Supports regular expressions as well!

[![build status](https://secure.travis-ci.org/juliangruber/balanced-match.svg)](http://travis-ci.org/juliangruber/balanced-match)
[![downloads](https://img.shields.io/npm/dm/balanced-match.svg)](https://www.npmjs.org/package/balanced-match)

[![testling badge](https://ci.testling.com/juliangruber/balanced-match.png)](https://ci.testling.com/juliangruber/balanced-match)

## Example

Get the first matching pair of braces:

```js
var balanced = require('balanced-match');

console.log(balanced('{', '}', 'pre{in{nested}}post'));
console.log(balanced('{', '}', 'pre{first}between{second}post'));
console.log(balanced(/\s+\{\s+/, /\s+\}\s+/, 'pre  {   in{nest}   }  post'));
```

The matches are:

```bash
$ node example.js
{ start: 3, end: 14, pre: 'pre', body: 'in{nested}', post: 'post' }
{ start: 3,
  end: 9,
  pre: 'pre',
  body: 'first',
  post: 'between{second}post' }
{ start: 3, end: 17, pre: 'pre', body: 'in{nest}', post: 'post' }
```

## API

### var m = balanced(a, b, str)

For the first non-nested matching pair of `a` and `b` in `str`, return an
object with those keys:

* **start** the index of the first match of `a`
* **end** the index of the matching `b`
* **pre** the preamble, `a` and `b` not included
* **body** the match, `a` and `b` not included
* **post** the postscript, `a` and `b` not included

If there's no match, `undefined` will be returned.

If the `str` contains more `a` than `b` / there are unmatched pairs, the first match that was closed will be used. For example, `{{a}` will match `['{', 'a', '']` and `{a}}` will match `['', 'a', '}']`.

### var r = balanced.range(a, b, str)

For the first non-nested matching pair of `a` and `b` in `str`, return an
array with indexes: `[ <a index>, <b index> ]`.

If there's no match, `undefined` will be returned.

If the `str` contains more `a` than `b` / there are unmatched pairs, the first match that was closed will be used. For example, `{{a}` will match `[ 1, 3 ]` and `{a}}` will match `[0, 2]`.

## Installation

With [npm](https://npmjs.org) do:

```bash
npm install balanced-match
```

## Security contact information

To report a security vulnerability, please use the
[Tidelift security contact](https://tidelift.com/security).
Tidelift will coordinate the fix and disclosure.

## License

(MIT)

Copyright (c) 2013 Julian Gruber &lt;julian@juliangruber.com&gt;

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

0.6.1 / 2017-05-16
==================

  * fix `process.nextTick` detection in Node.js

0.6.0 / 2017-03-25
==================

  * always invoke end callback asynchronously
  * fix compatibility with component v1
  * fix license field

0.5.3 / 2015-10-01
==================

  * fix for browserify

0.5.2 / 2014-12-22
==================

  * add brower field
  * add license to package.json

0.5.1 / 2014-06-19
==================

 * add repository field to readme (exciting)

0.5.0 / 2013-07-29
==================

 * add `.throws(true)` to opt-in to responding with an array of error objects
 * make `new` optional

0.4.0 / 2013-06-05
==================

 * add catching of immediate callback errors

0.3.2 / 2013-03-15
==================

  * remove Emitter call in constructor

0.3.1 / 2013-03-13
==================

  * add Emitter() mixin for client. Closes #8

0.3.0 / 2013-03-13
==================

  * add component.json
  * add result example
  * add .concurrency support
  * add concurrency example
  * add parallel example

0.2.1 / 2012-11-08
==================

  * add .start, .end, and .duration properties
  * change dependencies to devDependencies

0.2.0 / 2012-10-04
==================

  * add progress events. Closes #5 (__BREAKING CHANGE__)

0.1.1 / 2012-07-03
==================

  * change "complete" event to "progress"

0.1.0 / 2012-07-03
==================

  * add Emitter inheritance and emit "complete" [burcu]

0.0.3 / 2012-06-02
==================

  * Callback results should be in the order of the queued functions.

0.0.2 / 2012-02-12
==================

  * any node

0.0.1 / 2010-01-03
==================

  * Initial release


---


# batch

  Simple async batch with concurrency control and progress reporting.

## Installation

```
$ npm install batch
```

## API

```js
var Batch = require('batch')
  , batch = new Batch;

batch.concurrency(4);

ids.forEach(function(id){
  batch.push(function(done){
    User.get(id, done);
  });
});

batch.on('progress', function(e){

});

batch.end(function(err, users){

});
```

### Progress events

  Contain the "job" index, response value, duration information, and completion data.

```
{ index: 1,
  value: 'bar',
  pending: 2,
  total: 3,
  complete: 2,
  percent: 66,
  start: Thu Oct 04 2012 12:25:53 GMT-0700 (PDT),
  end: Thu Oct 04 2012 12:25:53 GMT-0700 (PDT),
  duration: 0 }
```

## License

[MIT](LICENSE)


---

#### 5.2.2

* 18/10/18
* #109 Remove opencollective dependency.

#### 5.2.1

* Delete *bower.json*.

#### 5.2.0

* 09/10/18
* #63 Allow negative argument for `round`.
* #107 `sqrt` of large number.

#### 5.1.2

* 24/05/18
* #95 Add `browser` field to *package.json*.
* Restore named export to enable `import {Big}`.

#### 5.1.1

* 22/05/18
* #95 Remove named export.

#### 5.1.0

* 22/05/18
* Amend *.mjs* exports.
* Remove extension from `main` field in *package.json*.

#### 5.0.3

* 23/10/17
* #89 Optimisation of internal `round` function.

#### 5.0.2

* 13/10/17
* Update *README.md*.

#### 5.0.1

* 13/10/17
* Correct `Big.version` number.

#### 5.0.0

* 13/10/17
* Return `-0` from `valueOf` for negative zero.
* Refactor the methods which return a string.
* Amend error messaging.
* Update API document and change its colour scheme.
* Add `Big.version`.
* Remove bitcoin address.

#### 4.0.2

* 28/09/17
* Add *big.mjs* for use with Node.js with `--experimental-modules` flag.

#### 4.0.0

* 27/09/17
* Rename `Big.E_POS` to `Big.PE`, `Big.E_NEG` to `Big.NE`.
* Refactor error messaging.
* Throw if `null` is passed to `toFixed` etc.

#### 3.2.0

* 14/09/17 Aid ES6 import.

#### 3.1.3

* Minor documentation updates.

#### 3.1.2

* README typo.

#### 3.1.1

* API documentation update, including FAQ additions.

#### 3.1.0

* Renamed and exposed `TO_EXP_NEG` and `TO_EXP_POS` as `Big.E_NEG` and `Big.E_POS`.

#### 3.0.2

* Remove *.npmignore*, use `files` field in *package.json* instead.

#### 3.0.1

* Added `sub`, `add` and `mul` aliases.
* Clean-up after lint.

#### 3.0.0

* 10/12/14 Added [multiple constructor functionality](http://mikemcl.github.io/big.js/#faq).
* No breaking changes or other additions, but a major code reorganisation, so *v3* seemed appropiate.

#### 2.5.2

* 1/11/14 Added bower.json.

#### 2.5.1

* 8/06/14 Amend README requires.

#### 2.5.0

* 26/01/14 Added `toJSON` method so serialization uses `toString`.

#### 2.4.1

* 17/10/13 Conform signed zero to IEEEE 754 (2008).

#### 2.4.0

* 19/09/13 Throw instances of `Error`.

#### 2.3.0

* 16/09/13 Added `cmp` method.

#### 2.2.0

* 11/07/13 Added 'round up' mode.

#### 2.1.0

* 26/06/13 Allow e.g. `.1` and `2.`.

#### 2.0.0

* 12/05/13 Added `abs` method and replaced `cmp` with `eq`, `gt`, `gte`, `lt`, and `lte` methods.

#### 1.0.1

* Changed default value of MAX_DP to 1E6

#### 1.0.0

* 7/11/2012 Initial release


---

# big.js

**A small, fast JavaScript library for arbitrary-precision decimal arithmetic.**

The little sister to [bignumber.js](https://github.com/MikeMcl/bignumber.js/) and [decimal.js](https://github.com/MikeMcl/decimal.js/). See [here](https://github.com/MikeMcl/big.js/wiki) for some notes on the difference between them.

## Features

  - Faster, smaller and easier-to-use than JavaScript versions of Java's BigDecimal
  - Only 5.9 KB minified and 2.7 KB gzipped
  - Simple API
  - Replicates the `toExponential`, `toFixed` and `toPrecision` methods of JavaScript's Number type
  - Includes a `sqrt` method
  - Stores values in an accessible decimal floating point format
  - No dependencies
  - Comprehensive [documentation](http://mikemcl.github.io/big.js/) and test set

## Set up

The library is the single JavaScript file *big.js* (or *big.min.js*, which is *big.js* minified).

Browser:

```html
<script src='path/to/big.js'></script>
```

[Node.js](http://nodejs.org):

```bash
$ npm install big.js
```

```javascript
const Big = require('big.js');
```

ES6 module:

```javascript
import Big from 'big.mjs';
```
## Use

*In all examples below, `var`, semicolons and `toString` calls are not shown. If a commented-out value is in quotes it means `toString` has been called on the preceding expression.*

The library exports a single function, `Big`, the constructor of Big number instances.
It accepts a value of type number, string or Big number object.

    x = new Big(123.4567)
    y = Big('123456.7e-3')             // 'new' is optional
    z = new Big(x)
    x.eq(y) && x.eq(z) && y.eq(z)      // true

A Big number is immutable in the sense that it is not changed by its methods.

    0.3 - 0.1                          // 0.19999999999999998
    x = new Big(0.3)
    x.minus(0.1)                       // "0.2"
    x                                  // "0.3"

The methods that return a Big number can be chained.

    x.div(y).plus(z).times(9).minus('1.234567801234567e+8').plus(976.54321).div('2598.11772')
    x.sqrt().div(y).pow(3).gt(y.mod(z))    // true

Like JavaScript's Number type, there are `toExponential`, `toFixed` and `toPrecision` methods.

    x = new Big(255.5)
    x.toExponential(5)                 // "2.55500e+2"
    x.toFixed(5)                       // "255.50000"
    x.toPrecision(5)                   // "255.50"

The arithmetic methods always return the exact result except `div`, `sqrt` and `pow`
(with negative exponent), as these methods involve division.

The maximum number of decimal places and the rounding mode used to round the results of these methods is determined by the value of the `DP` and `RM` properties of the `Big` number constructor.

    Big.DP = 10
    Big.RM = 1

    x = new Big(2);
    y = new Big(3);
    z = x.div(y)                       // "0.6666666667"
    z.sqrt()                           // "0.8164965809"
    z.pow(-3)                          // "3.3749999995"
    z.times(z)                         // "0.44444444448888888889"
    z.times(z).round(10)               // "0.4444444445"

Multiple Big number constructors can be created, each with an independent configuration.

The value of a Big number is stored in a decimal floating point format in terms of a coefficient, exponent and sign.

    x = new Big(-123.456);
    x.c                                // [1,2,3,4,5,6]    coefficient (i.e. significand)
    x.e                                // 2                exponent
    x.s                                // -1               sign

For further information see the [API](http://mikemcl.github.io/big.js/) reference from the *doc* folder.

## Test

The *test* directory contains the test scripts for each Big number method.

The tests can be run with Node.js or a browser.

To run all the tests

    $ npm test

To test a single method

    $ node test/toFixed

For the browser, see *single-test.html* and *every-test.html* in the *test/browser* directory.

*big-vs-number.html* is a simple application that enables some of the methods of big.js to be compared with those of JavaScript's Number type.

## Performance

The *perf* directory contains two legacy applications and a *lib* directory containing the BigDecimal libraries used by both.

*big-vs-bigdecimal.html* tests the performance of big.js against the JavaScript translations of two versions of BigDecimal, its use should be more or less self-explanatory.

* [GWT: java.math.BigDecimal](https://github.com/iriscouch/bigdecimal.js)
* [ICU4J: com.ibm.icu.math.BigDecimal](https://github.com/dtrebbien/BigDecimal.js)

The BigDecimal in the npm registry is the GWT version. It has some bugs, see the Node.js script *perf/lib/bigdecimal_GWT/bugs.js* for examples of flaws in its *remainder*, *divide* and *compareTo* methods.

*bigtime.js* is a Node.js command-line application which tests the performance of big.js against the GWT version of
BigDecimal from the npm registry.

For example, to compare the time taken by the big.js `plus` method and the BigDecimal `add` method

    $ node bigtime plus 10000 40

This will time 10000 calls to each, using operands of up to 40 random digits and will check that the results match.

For help

    $ node bigtime -h

## Build

If [uglify-js](https://github.com/mishoo/UglifyJS2) is installed globally

    $ npm install uglify-js -g

then

    $ npm run build

will create *big.min.js*.

## TypeScript

The [DefinitelyTyped](https://github.com/borisyankov/DefinitelyTyped) project has a Typescript type definitions file for big.js.

    $ npm install @types/big.js

Any questions about the TypeScript type definitions file should be addressed to the DefinitelyTyped project.

## Feedback

Bugs/comments/questions?

Open an issue, or email <a href="mailto:M8ch88l@gmail.com">Michael</a>

## Licence

[MIT](LICENCE)

## Contributors

This project exists thanks to all the people who contribute. [[Contribute](CONTRIBUTING.md)].
<a href="graphs/contributors"><img src="https://opencollective.com/bigjs/contributors.svg?width=890&button=false" /></a>


## Backers

Thank you to all our backers! 🙏 [[Become a backer](https://opencollective.com/bigjs#backer)]

<a href="https://opencollective.com/bigjs#backers" target="_blank"><img src="https://opencollective.com/bigjs/backers.svg?width=890"></a>


## Sponsors

Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [[Become a sponsor](https://opencollective.com/bigjs#sponsor)]

<a href="https://opencollective.com/bigjs/sponsor/0/website" target="_blank"><img src="https://opencollective.com/bigjs/sponsor/0/avatar.svg"></a>
<a href="https://opencollective.com/bigjs/sponsor/1/website" target="_blank"><img src="https://opencollective.com/bigjs/sponsor/1/avatar.svg"></a>
<a href="https://opencollective.com/bigjs/sponsor/2/website" target="_blank"><img src="https://opencollective.com/bigjs/sponsor/2/avatar.svg"></a>
<a href="https://opencollective.com/bigjs/sponsor/3/website" target="_blank"><img src="https://opencollective.com/bigjs/sponsor/3/avatar.svg"></a>
<a href="https://opencollective.com/bigjs/sponsor/4/website" target="_blank"><img src="https://opencollective.com/bigjs/sponsor/4/avatar.svg"></a>
<a href="https://opencollective.com/bigjs/sponsor/5/website" target="_blank"><img src="https://opencollective.com/bigjs/sponsor/5/avatar.svg"></a>
<a href="https://opencollective.com/bigjs/sponsor/6/website" target="_blank"><img src="https://opencollective.com/bigjs/sponsor/6/avatar.svg"></a>
<a href="https://opencollective.com/bigjs/sponsor/7/website" target="_blank"><img src="https://opencollective.com/bigjs/sponsor/7/avatar.svg"></a>
<a href="https://opencollective.com/bigjs/sponsor/8/website" target="_blank"><img src="https://opencollective.com/bigjs/sponsor/8/avatar.svg"></a>
<a href="https://opencollective.com/bigjs/sponsor/9/website" target="_blank"><img src="https://opencollective.com/bigjs/sponsor/9/avatar.svg"></a>




---

# binary-extensions

> List of binary file extensions

The list is just a [JSON file](binary-extensions.json) and can be used anywhere.

## Install

```sh
npm install binary-extensions
```

## Usage

```js
const binaryExtensions = require('binary-extensions');

console.log(binaryExtensions);
//=> ['3ds', '3g2', …]
```

## Related

- [is-binary-path](https://github.com/sindresorhus/is-binary-path) - Check if a filepath is a binary file
- [text-extensions](https://github.com/sindresorhus/text-extensions) - List of text file extensions


---

1.20.3 / 2024-09-10
===================

  * deps: qs@6.13.0
  * add `depth` option to customize the depth level in the parser
  * IMPORTANT: The default `depth` level for parsing URL-encoded data is now `32` (previously was `Infinity`)

1.20.2 / 2023-02-21
===================

  * Fix strict json error message on Node.js 19+
  * deps: content-type@~1.0.5
    - perf: skip value escaping when unnecessary
  * deps: raw-body@2.5.2

1.20.1 / 2022-10-06
===================

  * deps: qs@6.11.0
  * perf: remove unnecessary object clone

1.20.0 / 2022-04-02
===================

  * Fix error message for json parse whitespace in `strict`
  * Fix internal error when inflated body exceeds limit
  * Prevent loss of async hooks context
  * Prevent hanging when request already read
  * deps: depd@2.0.0
    - Replace internal `eval` usage with `Function` constructor
    - Use instance methods on `process` to check for listeners
  * deps: http-errors@2.0.0
    - deps: depd@2.0.0
    - deps: statuses@2.0.1
  * deps: on-finished@2.4.1
  * deps: qs@6.10.3
  * deps: raw-body@2.5.1
    - deps: http-errors@2.0.0

1.19.2 / 2022-02-15
===================

  * deps: bytes@3.1.2
  * deps: qs@6.9.7
    * Fix handling of `__proto__` keys
  * deps: raw-body@2.4.3
    - deps: bytes@3.1.2

1.19.1 / 2021-12-10
===================

  * deps: bytes@3.1.1
  * deps: http-errors@1.8.1
    - deps: inherits@2.0.4
    - deps: toidentifier@1.0.1
    - deps: setprototypeof@1.2.0
  * deps: qs@6.9.6
  * deps: raw-body@2.4.2
    - deps: bytes@3.1.1
    - deps: http-errors@1.8.1
  * deps: safe-buffer@5.2.1
  * deps: type-is@~1.6.18

1.19.0 / 2019-04-25
===================

  * deps: bytes@3.1.0
    - Add petabyte (`pb`) support
  * deps: http-errors@1.7.2
    - Set constructor name when possible
    - deps: setprototypeof@1.1.1
    - deps: statuses@'>= 1.5.0 < 2'
  * deps: iconv-lite@0.4.24
    - Added encoding MIK
  * deps: qs@6.7.0
    - Fix parsing array brackets after index
  * deps: raw-body@2.4.0
    - deps: bytes@3.1.0
    - deps: http-errors@1.7.2
    - deps: iconv-lite@0.4.24
  * deps: type-is@~1.6.17
    - deps: mime-types@~2.1.24
    - perf: prevent internal `throw` on invalid type

1.18.3 / 2018-05-14
===================

  * Fix stack trace for strict json parse error
  * deps: depd@~1.1.2
    - perf: remove argument reassignment
  * deps: http-errors@~1.6.3
    - deps: depd@~1.1.2
    - deps: setprototypeof@1.1.0
    - deps: statuses@'>= 1.3.1 < 2'
  * deps: iconv-lite@0.4.23
    - Fix loading encoding with year appended
    - Fix deprecation warnings on Node.js 10+
  * deps: qs@6.5.2
  * deps: raw-body@2.3.3
    - deps: http-errors@1.6.3
    - deps: iconv-lite@0.4.23
  * deps: type-is@~1.6.16
    - deps: mime-types@~2.1.18

1.18.2 / 2017-09-22
===================

  * deps: debug@2.6.9
  * perf: remove argument reassignment

1.18.1 / 2017-09-12
===================

  * deps: content-type@~1.0.4
    - perf: remove argument reassignment
    - perf: skip parameter parsing when no parameters
  * deps: iconv-lite@0.4.19
    - Fix ISO-8859-1 regression
    - Update Windows-1255
  * deps: qs@6.5.1
    - Fix parsing & compacting very deep objects
  * deps: raw-body@2.3.2
    - deps: iconv-lite@0.4.19

1.18.0 / 2017-09-08
===================

  * Fix JSON strict violation error to match native parse error
  * Include the `body` property on verify errors
  * Include the `type` property on all generated errors
  * Use `http-errors` to set status code on errors
  * deps: bytes@3.0.0
  * deps: debug@2.6.8
  * deps: depd@~1.1.1
    - Remove unnecessary `Buffer` loading
  * deps: http-errors@~1.6.2
    - deps: depd@1.1.1
  * deps: iconv-lite@0.4.18
    - Add support for React Native
    - Add a warning if not loaded as utf-8
    - Fix CESU-8 decoding in Node.js 8
    - Improve speed of ISO-8859-1 encoding
  * deps: qs@6.5.0
  * deps: raw-body@2.3.1
    - Use `http-errors` for standard emitted errors
    - deps: bytes@3.0.0
    - deps: iconv-lite@0.4.18
    - perf: skip buffer decoding on overage chunk
  * perf: prevent internal `throw` when missing charset

1.17.2 / 2017-05-17
===================

  * deps: debug@2.6.7
    - Fix `DEBUG_MAX_ARRAY_LENGTH`
    - deps: ms@2.0.0
  * deps: type-is@~1.6.15
    - deps: mime-types@~2.1.15

1.17.1 / 2017-03-06
===================

  * deps: qs@6.4.0
    - Fix regression parsing keys starting with `[`

1.17.0 / 2017-03-01
===================

  * deps: http-errors@~1.6.1
    - Make `message` property enumerable for `HttpError`s
    - deps: setprototypeof@1.0.3
  * deps: qs@6.3.1
    - Fix compacting nested arrays

1.16.1 / 2017-02-10
===================

  * deps: debug@2.6.1
    - Fix deprecation messages in WebStorm and other editors
    - Undeprecate `DEBUG_FD` set to `1` or `2`

1.16.0 / 2017-01-17
===================

  * deps: debug@2.6.0
    - Allow colors in workers
    - Deprecated `DEBUG_FD` environment variable
    - Fix error when running under React Native
    - Use same color for same namespace
    - deps: ms@0.7.2
  * deps: http-errors@~1.5.1
    - deps: inherits@2.0.3
    - deps: setprototypeof@1.0.2
    - deps: statuses@'>= 1.3.1 < 2'
  * deps: iconv-lite@0.4.15
    - Added encoding MS-31J
    - Added encoding MS-932
    - Added encoding MS-936
    - Added encoding MS-949
    - Added encoding MS-950
    - Fix GBK/GB18030 handling of Euro character
  * deps: qs@6.2.1
    - Fix array parsing from skipping empty values
  * deps: raw-body@~2.2.0
    - deps: iconv-lite@0.4.15
  * deps: type-is@~1.6.14
    - deps: mime-types@~2.1.13

1.15.2 / 2016-06-19
===================

  * deps: bytes@2.4.0
  * deps: content-type@~1.0.2
    - perf: enable strict mode
  * deps: http-errors@~1.5.0
    - Use `setprototypeof` module to replace `__proto__` setting
    - deps: statuses@'>= 1.3.0 < 2'
    - perf: enable strict mode
  * deps: qs@6.2.0
  * deps: raw-body@~2.1.7
    - deps: bytes@2.4.0
    - perf: remove double-cleanup on happy path
  * deps: type-is@~1.6.13
    - deps: mime-types@~2.1.11

1.15.1 / 2016-05-05
===================

  * deps: bytes@2.3.0
    - Drop partial bytes on all parsed units
    - Fix parsing byte string that looks like hex
  * deps: raw-body@~2.1.6
    - deps: bytes@2.3.0
  * deps: type-is@~1.6.12
    - deps: mime-types@~2.1.10

1.15.0 / 2016-02-10
===================

  * deps: http-errors@~1.4.0
    - Add `HttpError` export, for `err instanceof createError.HttpError`
    - deps: inherits@2.0.1
    - deps: statuses@'>= 1.2.1 < 2'
  * deps: qs@6.1.0
  * deps: type-is@~1.6.11
    - deps: mime-types@~2.1.9

1.14.2 / 2015-12-16
===================

  * deps: bytes@2.2.0
  * deps: iconv-lite@0.4.13
  * deps: qs@5.2.0
  * deps: raw-body@~2.1.5
    - deps: bytes@2.2.0
    - deps: iconv-lite@0.4.13
  * deps: type-is@~1.6.10
    - deps: mime-types@~2.1.8

1.14.1 / 2015-09-27
===================

  * Fix issue where invalid charset results in 400 when `verify` used
  * deps: iconv-lite@0.4.12
    - Fix CESU-8 decoding in Node.js 4.x
  * deps: raw-body@~2.1.4
    - Fix masking critical errors from `iconv-lite`
    - deps: iconv-lite@0.4.12
  * deps: type-is@~1.6.9
    - deps: mime-types@~2.1.7

1.14.0 / 2015-09-16
===================

  * Fix JSON strict parse error to match syntax errors
  * Provide static `require` analysis in `urlencoded` parser
  * deps: depd@~1.1.0
    - Support web browser loading
  * deps: qs@5.1.0
  * deps: raw-body@~2.1.3
    - Fix sync callback when attaching data listener causes sync read
  * deps: type-is@~1.6.8
    - Fix type error when given invalid type to match against
    - deps: mime-types@~2.1.6

1.13.3 / 2015-07-31
===================

  * deps: type-is@~1.6.6
    - deps: mime-types@~2.1.4

1.13.2 / 2015-07-05
===================

  * deps: iconv-lite@0.4.11
  * deps: qs@4.0.0
    - Fix dropping parameters like `hasOwnProperty`
    - Fix user-visible incompatibilities from 3.1.0
    - Fix various parsing edge cases
  * deps: raw-body@~2.1.2
    - Fix error stack traces to skip `makeError`
    - deps: iconv-lite@0.4.11
  * deps: type-is@~1.6.4
    - deps: mime-types@~2.1.2
    - perf: enable strict mode
    - perf: remove argument reassignment

1.13.1 / 2015-06-16
===================

  * deps: qs@2.4.2
    - Downgraded from 3.1.0 because of user-visible incompatibilities

1.13.0 / 2015-06-14
===================

  * Add `statusCode` property on `Error`s, in addition to `status`
  * Change `type` default to `application/json` for JSON parser
  * Change `type` default to `application/x-www-form-urlencoded` for urlencoded parser
  * Provide static `require` analysis
  * Use the `http-errors` module to generate errors
  * deps: bytes@2.1.0
    - Slight optimizations
  * deps: iconv-lite@0.4.10
    - The encoding UTF-16 without BOM now defaults to UTF-16LE when detection fails
    - Leading BOM is now removed when decoding
  * deps: on-finished@~2.3.0
    - Add defined behavior for HTTP `CONNECT` requests
    - Add defined behavior for HTTP `Upgrade` requests
    - deps: ee-first@1.1.1
  * deps: qs@3.1.0
    - Fix dropping parameters like `hasOwnProperty`
    - Fix various parsing edge cases
    - Parsed object now has `null` prototype
  * deps: raw-body@~2.1.1
    - Use `unpipe` module for unpiping requests
    - deps: iconv-lite@0.4.10
  * deps: type-is@~1.6.3
    - deps: mime-types@~2.1.1
    - perf: reduce try block size
    - perf: remove bitwise operations
  * perf: enable strict mode
  * perf: remove argument reassignment
  * perf: remove delete call

1.12.4 / 2015-05-10
===================

  * deps: debug@~2.2.0
  * deps: qs@2.4.2
    - Fix allowing parameters like `constructor`
  * deps: on-finished@~2.2.1
  * deps: raw-body@~2.0.1
    - Fix a false-positive when unpiping in Node.js 0.8
    - deps: bytes@2.0.1
  * deps: type-is@~1.6.2
    - deps: mime-types@~2.0.11

1.12.3 / 2015-04-15
===================

  * Slight efficiency improvement when not debugging
  * deps: depd@~1.0.1
  * deps: iconv-lite@0.4.8
    - Add encoding alias UNICODE-1-1-UTF-7
  * deps: raw-body@1.3.4
    - Fix hanging callback if request aborts during read
    - deps: iconv-lite@0.4.8

1.12.2 / 2015-03-16
===================

  * deps: qs@2.4.1
    - Fix error when parameter `hasOwnProperty` is present

1.12.1 / 2015-03-15
===================

  * deps: debug@~2.1.3
    - Fix high intensity foreground color for bold
    - deps: ms@0.7.0
  * deps: type-is@~1.6.1
    - deps: mime-types@~2.0.10

1.12.0 / 2015-02-13
===================

  * add `debug` messages
  * accept a function for the `type` option
  * use `content-type` to parse `Content-Type` headers
  * deps: iconv-lite@0.4.7
    - Gracefully support enumerables on `Object.prototype`
  * deps: raw-body@1.3.3
    - deps: iconv-lite@0.4.7
  * deps: type-is@~1.6.0
    - fix argument reassignment
    - fix false-positives in `hasBody` `Transfer-Encoding` check
    - support wildcard for both type and subtype (`*/*`)
    - deps: mime-types@~2.0.9

1.11.0 / 2015-01-30
===================

  * make internal `extended: true` depth limit infinity
  * deps: type-is@~1.5.6
    - deps: mime-types@~2.0.8

1.10.2 / 2015-01-20
===================

  * deps: iconv-lite@0.4.6
    - Fix rare aliases of single-byte encodings
  * deps: raw-body@1.3.2
    - deps: iconv-lite@0.4.6

1.10.1 / 2015-01-01
===================

  * deps: on-finished@~2.2.0
  * deps: type-is@~1.5.5
    - deps: mime-types@~2.0.7

1.10.0 / 2014-12-02
===================

  * make internal `extended: true` array limit dynamic

1.9.3 / 2014-11-21
==================

  * deps: iconv-lite@0.4.5
    - Fix Windows-31J and X-SJIS encoding support
  * deps: qs@2.3.3
    - Fix `arrayLimit` behavior
  * deps: raw-body@1.3.1
    - deps: iconv-lite@0.4.5
  * deps: type-is@~1.5.3
    - deps: mime-types@~2.0.3

1.9.2 / 2014-10-27
==================

  * deps: qs@2.3.2
    - Fix parsing of mixed objects and values

1.9.1 / 2014-10-22
==================

  * deps: on-finished@~2.1.1
    - Fix handling of pipelined requests
  * deps: qs@2.3.0
    - Fix parsing of mixed implicit and explicit arrays
  * deps: type-is@~1.5.2
    - deps: mime-types@~2.0.2

1.9.0 / 2014-09-24
==================

  * include the charset in "unsupported charset" error message
  * include the encoding in "unsupported content encoding" error message
  * deps: depd@~1.0.0

1.8.4 / 2014-09-23
==================

  * fix content encoding to be case-insensitive

1.8.3 / 2014-09-19
==================

  * deps: qs@2.2.4
    - Fix issue with object keys starting with numbers truncated

1.8.2 / 2014-09-15
==================

  * deps: depd@0.4.5

1.8.1 / 2014-09-07
==================

  * deps: media-typer@0.3.0
  * deps: type-is@~1.5.1

1.8.0 / 2014-09-05
==================

  * make empty-body-handling consistent between chunked requests
    - empty `json` produces `{}`
    - empty `raw` produces `new Buffer(0)`
    - empty `text` produces `''`
    - empty `urlencoded` produces `{}`
  * deps: qs@2.2.3
    - Fix issue where first empty value in array is discarded
  * deps: type-is@~1.5.0
    - fix `hasbody` to be true for `content-length: 0`

1.7.0 / 2014-09-01
==================

  * add `parameterLimit` option to `urlencoded` parser
  * change `urlencoded` extended array limit to 100
  * respond with 413 when over `parameterLimit` in `urlencoded`

1.6.7 / 2014-08-29
==================

  * deps: qs@2.2.2
    - Remove unnecessary cloning

1.6.6 / 2014-08-27
==================

  * deps: qs@2.2.0
    - Array parsing fix
    - Performance improvements

1.6.5 / 2014-08-16
==================

  * deps: on-finished@2.1.0

1.6.4 / 2014-08-14
==================

  * deps: qs@1.2.2

1.6.3 / 2014-08-10
==================

  * deps: qs@1.2.1

1.6.2 / 2014-08-07
==================

  * deps: qs@1.2.0
    - Fix parsing array of objects

1.6.1 / 2014-08-06
==================

  * deps: qs@1.1.0
    - Accept urlencoded square brackets
    - Accept empty values in implicit array notation

1.6.0 / 2014-08-05
==================

  * deps: qs@1.0.2
    - Complete rewrite
    - Limits array length to 20
    - Limits object depth to 5
    - Limits parameters to 1,000

1.5.2 / 2014-07-27
==================

  * deps: depd@0.4.4
    - Work-around v8 generating empty stack traces

1.5.1 / 2014-07-26
==================

  * deps: depd@0.4.3
    - Fix exception when global `Error.stackTraceLimit` is too low

1.5.0 / 2014-07-20
==================

  * deps: depd@0.4.2
    - Add `TRACE_DEPRECATION` environment variable
    - Remove non-standard grey color from color output
    - Support `--no-deprecation` argument
    - Support `--trace-deprecation` argument
  * deps: iconv-lite@0.4.4
    - Added encoding UTF-7
  * deps: raw-body@1.3.0
    - deps: iconv-lite@0.4.4
    - Added encoding UTF-7
    - Fix `Cannot switch to old mode now` error on Node.js 0.10+
  * deps: type-is@~1.3.2

1.4.3 / 2014-06-19
==================

  * deps: type-is@1.3.1
    - fix global variable leak

1.4.2 / 2014-06-19
==================

  * deps: type-is@1.3.0
    - improve type parsing

1.4.1 / 2014-06-19
==================

  * fix urlencoded extended deprecation message

1.4.0 / 2014-06-19
==================

  * add `text` parser
  * add `raw` parser
  * check accepted charset in content-type (accepts utf-8)
  * check accepted encoding in content-encoding (accepts identity)
  * deprecate `bodyParser()` middleware; use `.json()` and `.urlencoded()` as needed
  * deprecate `urlencoded()` without provided `extended` option
  * lazy-load urlencoded parsers
  * parsers split into files for reduced mem usage
  * support gzip and deflate bodies
    - set `inflate: false` to turn off
  * deps: raw-body@1.2.2
    - Support all encodings from `iconv-lite`

1.3.1 / 2014-06-11
==================

  * deps: type-is@1.2.1
    - Switch dependency from mime to mime-types@1.0.0

1.3.0 / 2014-05-31
==================

  * add `extended` option to urlencoded parser

1.2.2 / 2014-05-27
==================

  * deps: raw-body@1.1.6
    - assert stream encoding on node.js 0.8
    - assert stream encoding on node.js < 0.10.6
    - deps: bytes@1

1.2.1 / 2014-05-26
==================

  * invoke `next(err)` after request fully read
    - prevents hung responses and socket hang ups

1.2.0 / 2014-05-11
==================

  * add `verify` option
  * deps: type-is@1.2.0
    - support suffix matching

1.1.2 / 2014-05-11
==================

  * improve json parser speed

1.1.1 / 2014-05-11
==================

  * fix repeated limit parsing with every request

1.1.0 / 2014-05-10
==================

  * add `type` option
  * deps: pin for safety and consistency

1.0.2 / 2014-04-14
==================

  * use `type-is` module

1.0.1 / 2014-03-20
==================

  * lower default limits to 100kb


---

# body-parser

[![NPM Version][npm-version-image]][npm-url]
[![NPM Downloads][npm-downloads-image]][npm-url]
[![Build Status][ci-image]][ci-url]
[![Test Coverage][coveralls-image]][coveralls-url]
[![OpenSSF Scorecard Badge][ossf-scorecard-badge]][ossf-scorecard-visualizer]

Node.js body parsing middleware.

Parse incoming request bodies in a middleware before your handlers, available
under the `req.body` property.

**Note** As `req.body`'s shape is based on user-controlled input, all
properties and values in this object are untrusted and should be validated
before trusting. For example, `req.body.foo.toString()` may fail in multiple
ways, for example the `foo` property may not be there or may not be a string,
and `toString` may not be a function and instead a string or other user input.

[Learn about the anatomy of an HTTP transaction in Node.js](https://nodejs.org/en/docs/guides/anatomy-of-an-http-transaction/).

_This does not handle multipart bodies_, due to their complex and typically
large nature. For multipart bodies, you may be interested in the following
modules:

  * [busboy](https://www.npmjs.org/package/busboy#readme) and
    [connect-busboy](https://www.npmjs.org/package/connect-busboy#readme)
  * [multiparty](https://www.npmjs.org/package/multiparty#readme) and
    [connect-multiparty](https://www.npmjs.org/package/connect-multiparty#readme)
  * [formidable](https://www.npmjs.org/package/formidable#readme)
  * [multer](https://www.npmjs.org/package/multer#readme)

This module provides the following parsers:

  * [JSON body parser](#bodyparserjsonoptions)
  * [Raw body parser](#bodyparserrawoptions)
  * [Text body parser](#bodyparsertextoptions)
  * [URL-encoded form body parser](#bodyparserurlencodedoptions)

Other body parsers you might be interested in:

- [body](https://www.npmjs.org/package/body#readme)
- [co-body](https://www.npmjs.org/package/co-body#readme)

## Installation

```sh
$ npm install body-parser
```

## API

```js
var bodyParser = require('body-parser')
```

The `bodyParser` object exposes various factories to create middlewares. All
middlewares will populate the `req.body` property with the parsed body when
the `Content-Type` request header matches the `type` option, or an empty
object (`{}`) if there was no body to parse, the `Content-Type` was not matched,
or an error occurred.

The various errors returned by this module are described in the
[errors section](#errors).

### bodyParser.json([options])

Returns middleware that only parses `json` and only looks at requests where
the `Content-Type` header matches the `type` option. This parser accepts any
Unicode encoding of the body and supports automatic inflation of `gzip` and
`deflate` encodings.

A new `body` object containing the parsed data is populated on the `request`
object after the middleware (i.e. `req.body`).

#### Options

The `json` function takes an optional `options` object that may contain any of
the following keys:

##### inflate

When set to `true`, then deflated (compressed) bodies will be inflated; when
`false`, deflated bodies are rejected. Defaults to `true`.

##### limit

Controls the maximum request body size. If this is a number, then the value
specifies the number of bytes; if it is a string, the value is passed to the
[bytes](https://www.npmjs.com/package/bytes) library for parsing. Defaults
to `'100kb'`.

##### reviver

The `reviver` option is passed directly to `JSON.parse` as the second
argument. You can find more information on this argument
[in the MDN documentation about JSON.parse](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse#Example.3A_Using_the_reviver_parameter).

##### strict

When set to `true`, will only accept arrays and objects; when `false` will
accept anything `JSON.parse` accepts. Defaults to `true`.

##### type

The `type` option is used to determine what media type the middleware will
parse. This option can be a string, array of strings, or a function. If not a
function, `type` option is passed directly to the
[type-is](https://www.npmjs.org/package/type-is#readme) library and this can
be an extension name (like `json`), a mime type (like `application/json`), or
a mime type with a wildcard (like `*/*` or `*/json`). If a function, the `type`
option is called as `fn(req)` and the request is parsed if it returns a truthy
value. Defaults to `application/json`.

##### verify

The `verify` option, if supplied, is called as `verify(req, res, buf, encoding)`,
where `buf` is a `Buffer` of the raw request body and `encoding` is the
encoding of the request. The parsing can be aborted by throwing an error.

### bodyParser.raw([options])

Returns middleware that parses all bodies as a `Buffer` and only looks at
requests where the `Content-Type` header matches the `type` option. This
parser supports automatic inflation of `gzip` and `deflate` encodings.

A new `body` object containing the parsed data is populated on the `request`
object after the middleware (i.e. `req.body`). This will be a `Buffer` object
of the body.

#### Options

The `raw` function takes an optional `options` object that may contain any of
the following keys:

##### inflate

When set to `true`, then deflated (compressed) bodies will be inflated; when
`false`, deflated bodies are rejected. Defaults to `true`.

##### limit

Controls the maximum request body size. If this is a number, then the value
specifies the number of bytes; if it is a string, the value is passed to the
[bytes](https://www.npmjs.com/package/bytes) library for parsing. Defaults
to `'100kb'`.

##### type

The `type` option is used to determine what media type the middleware will
parse. This option can be a string, array of strings, or a function.
If not a function, `type` option is passed directly to the
[type-is](https://www.npmjs.org/package/type-is#readme) library and this
can be an extension name (like `bin`), a mime type (like
`application/octet-stream`), or a mime type with a wildcard (like `*/*` or
`application/*`). If a function, the `type` option is called as `fn(req)`
and the request is parsed if it returns a truthy value. Defaults to
`application/octet-stream`.

##### verify

The `verify` option, if supplied, is called as `verify(req, res, buf, encoding)`,
where `buf` is a `Buffer` of the raw request body and `encoding` is the
encoding of the request. The parsing can be aborted by throwing an error.

### bodyParser.text([options])

Returns middleware that parses all bodies as a string and only looks at
requests where the `Content-Type` header matches the `type` option. This
parser supports automatic inflation of `gzip` and `deflate` encodings.

A new `body` string containing the parsed data is populated on the `request`
object after the middleware (i.e. `req.body`). This will be a string of the
body.

#### Options

The `text` function takes an optional `options` object that may contain any of
the following keys:

##### defaultCharset

Specify the default character set for the text content if the charset is not
specified in the `Content-Type` header of the request. Defaults to `utf-8`.

##### inflate

When set to `true`, then deflated (compressed) bodies will be inflated; when
`false`, deflated bodies are rejected. Defaults to `true`.

##### limit

Controls the maximum request body size. If this is a number, then the value
specifies the number of bytes; if it is a string, the value is passed to the
[bytes](https://www.npmjs.com/package/bytes) library for parsing. Defaults
to `'100kb'`.

##### type

The `type` option is used to determine what media type the middleware will
parse. This option can be a string, array of strings, or a function. If not
a function, `type` option is passed directly to the
[type-is](https://www.npmjs.org/package/type-is#readme) library and this can
be an extension name (like `txt`), a mime type (like `text/plain`), or a mime
type with a wildcard (like `*/*` or `text/*`). If a function, the `type`
option is called as `fn(req)` and the request is parsed if it returns a
truthy value. Defaults to `text/plain`.

##### verify

The `verify` option, if supplied, is called as `verify(req, res, buf, encoding)`,
where `buf` is a `Buffer` of the raw request body and `encoding` is the
encoding of the request. The parsing can be aborted by throwing an error.

### bodyParser.urlencoded([options])

Returns middleware that only parses `urlencoded` bodies and only looks at
requests where the `Content-Type` header matches the `type` option. This
parser accepts only UTF-8 encoding of the body and supports automatic
inflation of `gzip` and `deflate` encodings.

A new `body` object containing the parsed data is populated on the `request`
object after the middleware (i.e. `req.body`). This object will contain
key-value pairs, where the value can be a string or array (when `extended` is
`false`), or any type (when `extended` is `true`).

#### Options

The `urlencoded` function takes an optional `options` object that may contain
any of the following keys:

##### extended

The `extended` option allows to choose between parsing the URL-encoded data
with the `querystring` library (when `false`) or the `qs` library (when
`true`). The "extended" syntax allows for rich objects and arrays to be
encoded into the URL-encoded format, allowing for a JSON-like experience
with URL-encoded. For more information, please
[see the qs library](https://www.npmjs.org/package/qs#readme).

Defaults to `true`, but using the default has been deprecated. Please
research into the difference between `qs` and `querystring` and choose the
appropriate setting.

##### inflate

When set to `true`, then deflated (compressed) bodies will be inflated; when
`false`, deflated bodies are rejected. Defaults to `true`.

##### limit

Controls the maximum request body size. If this is a number, then the value
specifies the number of bytes; if it is a string, the value is passed to the
[bytes](https://www.npmjs.com/package/bytes) library for parsing. Defaults
to `'100kb'`.

##### parameterLimit

The `parameterLimit` option controls the maximum number of parameters that
are allowed in the URL-encoded data. If a request contains more parameters
than this value, a 413 will be returned to the client. Defaults to `1000`.

##### type

The `type` option is used to determine what media type the middleware will
parse. This option can be a string, array of strings, or a function. If not
a function, `type` option is passed directly to the
[type-is](https://www.npmjs.org/package/type-is#readme) library and this can
be an extension name (like `urlencoded`), a mime type (like
`application/x-www-form-urlencoded`), or a mime type with a wildcard (like
`*/x-www-form-urlencoded`). If a function, the `type` option is called as
`fn(req)` and the request is parsed if it returns a truthy value. Defaults
to `application/x-www-form-urlencoded`.

##### verify

The `verify` option, if supplied, is called as `verify(req, res, buf, encoding)`,
where `buf` is a `Buffer` of the raw request body and `encoding` is the
encoding of the request. The parsing can be aborted by throwing an error.

#### depth

The `depth` option is used to configure the maximum depth of the `qs` library when `extended` is `true`. This allows you to limit the amount of keys that are parsed and can be useful to prevent certain types of abuse. Defaults to `32`. It is recommended to keep this value as low as possible.

## Errors

The middlewares provided by this module create errors using the
[`http-errors` module](https://www.npmjs.com/package/http-errors). The errors
will typically have a `status`/`statusCode` property that contains the suggested
HTTP response code, an `expose` property to determine if the `message` property
should be displayed to the client, a `type` property to determine the type of
error without matching against the `message`, and a `body` property containing
the read body, if available.

The following are the common errors created, though any error can come through
for various reasons.

### content encoding unsupported

This error will occur when the request had a `Content-Encoding` header that
contained an encoding but the "inflation" option was set to `false`. The
`status` property is set to `415`, the `type` property is set to
`'encoding.unsupported'`, and the `charset` property will be set to the
encoding that is unsupported.

### entity parse failed

This error will occur when the request contained an entity that could not be
parsed by the middleware. The `status` property is set to `400`, the `type`
property is set to `'entity.parse.failed'`, and the `body` property is set to
the entity value that failed parsing.

### entity verify failed

This error will occur when the request contained an entity that could not be
failed verification by the defined `verify` option. The `status` property is
set to `403`, the `type` property is set to `'entity.verify.failed'`, and the
`body` property is set to the entity value that failed verification.

### request aborted

This error will occur when the request is aborted by the client before reading
the body has finished. The `received` property will be set to the number of
bytes received before the request was aborted and the `expected` property is
set to the number of expected bytes. The `status` property is set to `400`
and `type` property is set to `'request.aborted'`.

### request entity too large

This error will occur when the request body's size is larger than the "limit"
option. The `limit` property will be set to the byte limit and the `length`
property will be set to the request body's length. The `status` property is
set to `413` and the `type` property is set to `'entity.too.large'`.

### request size did not match content length

This error will occur when the request's length did not match the length from
the `Content-Length` header. This typically occurs when the request is malformed,
typically when the `Content-Length` header was calculated based on characters
instead of bytes. The `status` property is set to `400` and the `type` property
is set to `'request.size.invalid'`.

### stream encoding should not be set

This error will occur when something called the `req.setEncoding` method prior
to this middleware. This module operates directly on bytes only and you cannot
call `req.setEncoding` when using this module. The `status` property is set to
`500` and the `type` property is set to `'stream.encoding.set'`.

### stream is not readable

This error will occur when the request is no longer readable when this middleware
attempts to read it. This typically means something other than a middleware from
this module read the request body already and the middleware was also configured to
read the same request. The `status` property is set to `500` and the `type`
property is set to `'stream.not.readable'`.

### too many parameters

This error will occur when the content of the request exceeds the configured
`parameterLimit` for the `urlencoded` parser. The `status` property is set to
`413` and the `type` property is set to `'parameters.too.many'`.

### unsupported charset "BOGUS"

This error will occur when the request had a charset parameter in the
`Content-Type` header, but the `iconv-lite` module does not support it OR the
parser does not support it. The charset is contained in the message as well
as in the `charset` property. The `status` property is set to `415`, the
`type` property is set to `'charset.unsupported'`, and the `charset` property
is set to the charset that is unsupported.

### unsupported content encoding "bogus"

This error will occur when the request had a `Content-Encoding` header that
contained an unsupported encoding. The encoding is contained in the message
as well as in the `encoding` property. The `status` property is set to `415`,
the `type` property is set to `'encoding.unsupported'`, and the `encoding`
property is set to the encoding that is unsupported.

### The input exceeded the depth

This error occurs when using `bodyParser.urlencoded` with the `extended` property set to `true` and the input exceeds the configured `depth` option. The `status` property is set to `400`. It is recommended to review the `depth` option and evaluate if it requires a higher value. When the `depth` option is set to `32` (default value), the error will not be thrown.

## Examples

### Express/Connect top-level generic

This example demonstrates adding a generic JSON and URL-encoded parser as a
top-level middleware, which will parse the bodies of all incoming requests.
This is the simplest setup.

```js
var express = require('express')
var bodyParser = require('body-parser')

var app = express()

// parse application/x-www-form-urlencoded
app.use(bodyParser.urlencoded({ extended: false }))

// parse application/json
app.use(bodyParser.json())

app.use(function (req, res) {
  res.setHeader('Content-Type', 'text/plain')
  res.write('you posted:\n')
  res.end(JSON.stringify(req.body, null, 2))
})
```

### Express route-specific

This example demonstrates adding body parsers specifically to the routes that
need them. In general, this is the most recommended way to use body-parser with
Express.

```js
var express = require('express')
var bodyParser = require('body-parser')

var app = express()

// create application/json parser
var jsonParser = bodyParser.json()

// create application/x-www-form-urlencoded parser
var urlencodedParser = bodyParser.urlencoded({ extended: false })

// POST /login gets urlencoded bodies
app.post('/login', urlencodedParser, function (req, res) {
  res.send('welcome, ' + req.body.username)
})

// POST /api/users gets JSON bodies
app.post('/api/users', jsonParser, function (req, res) {
  // create user in req.body
})
```

### Change accepted type for parsers

All the parsers accept a `type` option which allows you to change the
`Content-Type` that the middleware will parse.

```js
var express = require('express')
var bodyParser = require('body-parser')

var app = express()

// parse various different custom JSON types as JSON
app.use(bodyParser.json({ type: 'application/*+json' }))

// parse some custom thing into a Buffer
app.use(bodyParser.raw({ type: 'application/vnd.custom-type' }))

// parse an HTML body into a string
app.use(bodyParser.text({ type: 'text/html' }))
```

## License

[MIT](LICENSE)

[ci-image]: https://badgen.net/github/checks/expressjs/body-parser/master?label=ci
[ci-url]: https://github.com/expressjs/body-parser/actions/workflows/ci.yml
[coveralls-image]: https://badgen.net/coveralls/c/github/expressjs/body-parser/master
[coveralls-url]: https://coveralls.io/r/expressjs/body-parser?branch=master
[node-version-image]: https://badgen.net/npm/node/body-parser
[node-version-url]: https://nodejs.org/en/download
[npm-downloads-image]: https://badgen.net/npm/dm/body-parser
[npm-url]: https://npmjs.org/package/body-parser
[npm-version-image]: https://badgen.net/npm/v/body-parser
[ossf-scorecard-badge]: https://api.scorecard.dev/projects/github.com/expressjs/body-parser/badge
[ossf-scorecard-visualizer]: https://ossf.github.io/scorecard-visualizer/#/projects/github.com/expressjs/body-parser

---

# Security Policies and Procedures

## Reporting a Bug

The Express team and community take all security bugs seriously. Thank you
for improving the security of Express. We appreciate your efforts and
responsible disclosure and will make every effort to acknowledge your
contributions.

Report security bugs by emailing the current owner(s) of `body-parser`. This
information can be found in the npm registry using the command
`npm owner ls body-parser`.
If unsure or unable to get the information from the above, open an issue
in the [project issue tracker](https://github.com/expressjs/body-parser/issues)
asking for the current contact information.

To ensure the timely response to your report, please ensure that the entirety
of the report is contained within the email body and not solely behind a web
link or an attachment.

At least one owner will acknowledge your email within 48 hours, and will send a
more detailed response within 48 hours indicating the next steps in handling
your report. After the initial reply to your report, the owners will
endeavor to keep you informed of the progress towards a fix and full
announcement, and may ask for additional information or guidance.


---

3.1.2 / 2022-01-27
==================

  * Fix return value for un-parsable strings

3.1.1 / 2021-11-15
==================

  * Fix "thousandsSeparator" incorrecting formatting fractional part

3.1.0 / 2019-01-22
==================

  * Add petabyte (`pb`) support

3.0.0 / 2017-08-31
==================

  * Change "kB" to "KB" in format output
  * Remove support for Node.js 0.6
  * Remove support for ComponentJS

2.5.0 / 2017-03-24
==================

  * Add option "unit"

2.4.0 / 2016-06-01
==================

  * Add option "unitSeparator"

2.3.0 / 2016-02-15
==================

  * Drop partial bytes on all parsed units
  * Fix non-finite numbers to `.format` to return `null`
  * Fix parsing byte string that looks like hex
  * perf: hoist regular expressions

2.2.0 / 2015-11-13
==================

  * add option "decimalPlaces"
  * add option "fixedDecimals"

2.1.0 / 2015-05-21
==================

  * add `.format` export
  * add `.parse` export

2.0.2 / 2015-05-20
==================

  * remove map recreation
  * remove unnecessary object construction

2.0.1 / 2015-05-07
==================

  * fix browserify require
  * remove node.extend dependency

2.0.0 / 2015-04-12
==================

  * add option "case"
  * add option "thousandsSeparator"
  * return "null" on invalid parse input
  * support proper round-trip: bytes(bytes(num)) === num
  * units no longer case sensitive when parsing

1.0.0 / 2014-05-05
==================

 * add negative support. fixes #6

0.3.0 / 2014-03-19
==================

 * added terabyte support

0.2.1 / 2013-04-01
==================

  * add .component

0.2.0 / 2012-10-28
==================

  * bytes(200).should.eql('200b')

0.1.0 / 2012-07-04
==================

  * add bytes to string conversion [yields]


---

# Bytes utility

[![NPM Version][npm-image]][npm-url]
[![NPM Downloads][downloads-image]][downloads-url]
[![Build Status][ci-image]][ci-url]
[![Test Coverage][coveralls-image]][coveralls-url]

Utility to parse a string bytes (ex: `1TB`) to bytes (`1099511627776`) and vice-versa.

## Installation

This is a [Node.js](https://nodejs.org/en/) module available through the
[npm registry](https://www.npmjs.com/). Installation is done using the
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):

```bash
$ npm install bytes
```

## Usage

```js
var bytes = require('bytes');
```

#### bytes(number｜string value, [options]): number｜string｜null

Default export function. Delegates to either `bytes.format` or `bytes.parse` based on the type of `value`.

**Arguments**

| Name    | Type     | Description        |
|---------|----------|--------------------|
| value   | `number`｜`string` | Number value to format or string value to parse |
| options | `Object` | Conversion options for `format` |

**Returns**

| Name    | Type             | Description                                     |
|---------|------------------|-------------------------------------------------|
| results | `string`｜`number`｜`null` | Return null upon error. Numeric value in bytes, or string value otherwise. |

**Example**

```js
bytes(1024);
// output: '1KB'

bytes('1KB');
// output: 1024
```

#### bytes.format(number value, [options]): string｜null

Format the given value in bytes into a string. If the value is negative, it is kept as such. If it is a float, it is
 rounded.

**Arguments**

| Name    | Type     | Description        |
|---------|----------|--------------------|
| value   | `number` | Value in bytes     |
| options | `Object` | Conversion options |

**Options**

| Property          | Type   | Description                                                                             |
|-------------------|--------|-----------------------------------------------------------------------------------------|
| decimalPlaces | `number`｜`null` | Maximum number of decimal places to include in output. Default value to `2`. |
| fixedDecimals | `boolean`｜`null` | Whether to always display the maximum number of decimal places. Default value to `false` |
| thousandsSeparator | `string`｜`null` | Example of values: `' '`, `','` and `'.'`... Default value to `''`. |
| unit | `string`｜`null` | The unit in which the result will be returned (B/KB/MB/GB/TB). Default value to `''` (which means auto detect). |
| unitSeparator | `string`｜`null` | Separator to use between number and unit. Default value to `''`. |

**Returns**

| Name    | Type             | Description                                     |
|---------|------------------|-------------------------------------------------|
| results | `string`｜`null` | Return null upon error. String value otherwise. |

**Example**

```js
bytes.format(1024);
// output: '1KB'

bytes.format(1000);
// output: '1000B'

bytes.format(1000, {thousandsSeparator: ' '});
// output: '1 000B'

bytes.format(1024 * 1.7, {decimalPlaces: 0});
// output: '2KB'

bytes.format(1024, {unitSeparator: ' '});
// output: '1 KB'
```

#### bytes.parse(string｜number value): number｜null

Parse the string value into an integer in bytes. If no unit is given, or `value`
is a number, it is assumed the value is in bytes.

Supported units and abbreviations are as follows and are case-insensitive:

  * `b` for bytes
  * `kb` for kilobytes
  * `mb` for megabytes
  * `gb` for gigabytes
  * `tb` for terabytes
  * `pb` for petabytes

The units are in powers of two, not ten. This means 1kb = 1024b according to this parser.

**Arguments**

| Name          | Type   | Description        |
|---------------|--------|--------------------|
| value   | `string`｜`number` | String to parse, or number in bytes.   |

**Returns**

| Name    | Type        | Description             |
|---------|-------------|-------------------------|
| results | `number`｜`null` | Return null upon error. Value in bytes otherwise. |

**Example**

```js
bytes.parse('1KB');
// output: 1024

bytes.parse('1024');
// output: 1024

bytes.parse(1024);
// output: 1024
```

## License

[MIT](LICENSE)

[ci-image]: https://badgen.net/github/checks/visionmedia/bytes.js/master?label=ci
[ci-url]: https://github.com/visionmedia/bytes.js/actions?query=workflow%3Aci
[coveralls-image]: https://badgen.net/coveralls/c/github/visionmedia/bytes.js/master
[coveralls-url]: https://coveralls.io/r/visionmedia/bytes.js?branch=master
[downloads-image]: https://badgen.net/npm/dm/bytes
[downloads-url]: https://npmjs.org/package/bytes
[npm-image]: https://badgen.net/npm/v/bytes
[npm-url]: https://npmjs.org/package/bytes


---


2.6.9 / 2017-09-22
==================

  * remove ReDoS regexp in %o formatter (#504)

2.6.8 / 2017-05-18
==================

  * Fix: Check for undefined on browser globals (#462, @marbemac)

2.6.7 / 2017-05-16
==================

  * Fix: Update ms to 2.0.0 to fix regular expression denial of service vulnerability (#458, @hubdotcom)
  * Fix: Inline extend function in node implementation (#452, @dougwilson)
  * Docs: Fix typo (#455, @msasad)

2.6.5 / 2017-04-27
==================
  
  * Fix: null reference check on window.documentElement.style.WebkitAppearance (#447, @thebigredgeek)
  * Misc: clean up browser reference checks (#447, @thebigredgeek)
  * Misc: add npm-debug.log to .gitignore (@thebigredgeek)


2.6.4 / 2017-04-20
==================

  * Fix: bug that would occure if process.env.DEBUG is a non-string value. (#444, @LucianBuzzo)
  * Chore: ignore bower.json in npm installations. (#437, @joaovieira)
  * Misc: update "ms" to v0.7.3 (@tootallnate)

2.6.3 / 2017-03-13
==================

  * Fix: Electron reference to `process.env.DEBUG` (#431, @paulcbetts)
  * Docs: Changelog fix (@thebigredgeek)

2.6.2 / 2017-03-10
==================

  * Fix: DEBUG_MAX_ARRAY_LENGTH (#420, @slavaGanzin)
  * Docs: Add backers and sponsors from Open Collective (#422, @piamancini)
  * Docs: Add Slackin invite badge (@tootallnate)

2.6.1 / 2017-02-10
==================

  * Fix: Module's `export default` syntax fix for IE8 `Expected identifier` error
  * Fix: Whitelist DEBUG_FD for values 1 and 2 only (#415, @pi0)
  * Fix: IE8 "Expected identifier" error (#414, @vgoma)
  * Fix: Namespaces would not disable once enabled (#409, @musikov)

2.6.0 / 2016-12-28
==================

  * Fix: added better null pointer checks for browser useColors (@thebigredgeek)
  * Improvement: removed explicit `window.debug` export (#404, @tootallnate)
  * Improvement: deprecated `DEBUG_FD` environment variable (#405, @tootallnate)

2.5.2 / 2016-12-25
==================

  * Fix: reference error on window within webworkers (#393, @KlausTrainer)
  * Docs: fixed README typo (#391, @lurch)
  * Docs: added notice about v3 api discussion (@thebigredgeek)

2.5.1 / 2016-12-20
==================

  * Fix: babel-core compatibility

2.5.0 / 2016-12-20
==================

  * Fix: wrong reference in bower file (@thebigredgeek)
  * Fix: webworker compatibility (@thebigredgeek)
  * Fix: output formatting issue (#388, @kribblo)
  * Fix: babel-loader compatibility (#383, @escwald)
  * Misc: removed built asset from repo and publications (@thebigredgeek)
  * Misc: moved source files to /src (#378, @yamikuronue)
  * Test: added karma integration and replaced babel with browserify for browser tests (#378, @yamikuronue)
  * Test: coveralls integration (#378, @yamikuronue)
  * Docs: simplified language in the opening paragraph (#373, @yamikuronue)

2.4.5 / 2016-12-17
==================

  * Fix: `navigator` undefined in Rhino (#376, @jochenberger)
  * Fix: custom log function (#379, @hsiliev)
  * Improvement: bit of cleanup + linting fixes (@thebigredgeek)
  * Improvement: rm non-maintainted `dist/` dir (#375, @freewil)
  * Docs: simplified language in the opening paragraph. (#373, @yamikuronue)

2.4.4 / 2016-12-14
==================

  * Fix: work around debug being loaded in preload scripts for electron (#368, @paulcbetts)

2.4.3 / 2016-12-14
==================

  * Fix: navigation.userAgent error for react native (#364, @escwald)

2.4.2 / 2016-12-14
==================

  * Fix: browser colors (#367, @tootallnate)
  * Misc: travis ci integration (@thebigredgeek)
  * Misc: added linting and testing boilerplate with sanity check (@thebigredgeek)

2.4.1 / 2016-12-13
==================

  * Fix: typo that broke the package (#356)

2.4.0 / 2016-12-13
==================

  * Fix: bower.json references unbuilt src entry point (#342, @justmatt)
  * Fix: revert "handle regex special characters" (@tootallnate)
  * Feature: configurable util.inspect()`options for NodeJS (#327, @tootallnate)
  * Feature: %O`(big O) pretty-prints objects (#322, @tootallnate)
  * Improvement: allow colors in workers (#335, @botverse)
  * Improvement: use same color for same namespace. (#338, @lchenay)

2.3.3 / 2016-11-09
==================

  * Fix: Catch `JSON.stringify()` errors (#195, Jovan Alleyne)
  * Fix: Returning `localStorage` saved values (#331, Levi Thomason)
  * Improvement: Don't create an empty object when no `process` (Nathan Rajlich)

2.3.2 / 2016-11-09
==================

  * Fix: be super-safe in index.js as well (@TooTallNate)
  * Fix: should check whether process exists (Tom Newby)

2.3.1 / 2016-11-09
==================

  * Fix: Added electron compatibility (#324, @paulcbetts)
  * Improvement: Added performance optimizations (@tootallnate)
  * Readme: Corrected PowerShell environment variable example (#252, @gimre)
  * Misc: Removed yarn lock file from source control (#321, @fengmk2)

2.3.0 / 2016-11-07
==================

  * Fix: Consistent placement of ms diff at end of output (#215, @gorangajic)
  * Fix: Escaping of regex special characters in namespace strings (#250, @zacronos)
  * Fix: Fixed bug causing crash on react-native (#282, @vkarpov15)
  * Feature: Enabled ES6+ compatible import via default export (#212 @bucaran)
  * Feature: Added %O formatter to reflect Chrome's console.log capability (#279, @oncletom)
  * Package: Update "ms" to 0.7.2 (#315, @DevSide)
  * Package: removed superfluous version property from bower.json (#207 @kkirsche)
  * Readme: fix USE_COLORS to DEBUG_COLORS
  * Readme: Doc fixes for format string sugar (#269, @mlucool)
  * Readme: Updated docs for DEBUG_FD and DEBUG_COLORS environment variables (#232, @mattlyons0)
  * Readme: doc fixes for PowerShell (#271 #243, @exoticknight @unreadable)
  * Readme: better docs for browser support (#224, @matthewmueller)
  * Tooling: Added yarn integration for development (#317, @thebigredgeek)
  * Misc: Renamed History.md to CHANGELOG.md (@thebigredgeek)
  * Misc: Added license file (#226 #274, @CantemoInternal @sdaitzman)
  * Misc: Updated contributors (@thebigredgeek)

2.2.0 / 2015-05-09
==================

  * package: update "ms" to v0.7.1 (#202, @dougwilson)
  * README: add logging to file example (#193, @DanielOchoa)
  * README: fixed a typo (#191, @amir-s)
  * browser: expose `storage` (#190, @stephenmathieson)
  * Makefile: add a `distclean` target (#189, @stephenmathieson)

2.1.3 / 2015-03-13
==================

  * Updated stdout/stderr example (#186)
  * Updated example/stdout.js to match debug current behaviour
  * Renamed example/stderr.js to stdout.js
  * Update Readme.md (#184)
  * replace high intensity foreground color for bold (#182, #183)

2.1.2 / 2015-03-01
==================

  * dist: recompile
  * update "ms" to v0.7.0
  * package: update "browserify" to v9.0.3
  * component: fix "ms.js" repo location
  * changed bower package name
  * updated documentation about using debug in a browser
  * fix: security error on safari (#167, #168, @yields)

2.1.1 / 2014-12-29
==================

  * browser: use `typeof` to check for `console` existence
  * browser: check for `console.log` truthiness (fix IE 8/9)
  * browser: add support for Chrome apps
  * Readme: added Windows usage remarks
  * Add `bower.json` to properly support bower install

2.1.0 / 2014-10-15
==================

  * node: implement `DEBUG_FD` env variable support
  * package: update "browserify" to v6.1.0
  * package: add "license" field to package.json (#135, @panuhorsmalahti)

2.0.0 / 2014-09-01
==================

  * package: update "browserify" to v5.11.0
  * node: use stderr rather than stdout for logging (#29, @stephenmathieson)

1.0.4 / 2014-07-15
==================

  * dist: recompile
  * example: remove `console.info()` log usage
  * example: add "Content-Type" UTF-8 header to browser example
  * browser: place %c marker after the space character
  * browser: reset the "content" color via `color: inherit`
  * browser: add colors support for Firefox >= v31
  * debug: prefer an instance `log()` function over the global one (#119)
  * Readme: update documentation about styled console logs for FF v31 (#116, @wryk)

1.0.3 / 2014-07-09
==================

  * Add support for multiple wildcards in namespaces (#122, @seegno)
  * browser: fix lint

1.0.2 / 2014-06-10
==================

  * browser: update color palette (#113, @gscottolson)
  * common: make console logging function configurable (#108, @timoxley)
  * node: fix %o colors on old node <= 0.8.x
  * Makefile: find node path using shell/which (#109, @timoxley)

1.0.1 / 2014-06-06
==================

  * browser: use `removeItem()` to clear localStorage
  * browser, node: don't set DEBUG if namespaces is undefined (#107, @leedm777)
  * package: add "contributors" section
  * node: fix comment typo
  * README: list authors

1.0.0 / 2014-06-04
==================

  * make ms diff be global, not be scope
  * debug: ignore empty strings in enable()
  * node: make DEBUG_COLORS able to disable coloring
  * *: export the `colors` array
  * npmignore: don't publish the `dist` dir
  * Makefile: refactor to use browserify
  * package: add "browserify" as a dev dependency
  * Readme: add Web Inspector Colors section
  * node: reset terminal color for the debug content
  * node: map "%o" to `util.inspect()`
  * browser: map "%j" to `JSON.stringify()`
  * debug: add custom "formatters"
  * debug: use "ms" module for humanizing the diff
  * Readme: add "bash" syntax highlighting
  * browser: add Firebug color support
  * browser: add colors for WebKit browsers
  * node: apply log to `console`
  * rewrite: abstract common logic for Node & browsers
  * add .jshintrc file

0.8.1 / 2014-04-14
==================

  * package: re-add the "component" section

0.8.0 / 2014-03-30
==================

  * add `enable()` method for nodejs. Closes #27
  * change from stderr to stdout
  * remove unnecessary index.js file

0.7.4 / 2013-11-13
==================

  * remove "browserify" key from package.json (fixes something in browserify)

0.7.3 / 2013-10-30
==================

  * fix: catch localStorage security error when cookies are blocked (Chrome)
  * add debug(err) support. Closes #46
  * add .browser prop to package.json. Closes #42

0.7.2 / 2013-02-06
==================

  * fix package.json
  * fix: Mobile Safari (private mode) is broken with debug
  * fix: Use unicode to send escape character to shell instead of octal to work with strict mode javascript

0.7.1 / 2013-02-05
==================

  * add repository URL to package.json
  * add DEBUG_COLORED to force colored output
  * add browserify support
  * fix component. Closes #24

0.7.0 / 2012-05-04
==================

  * Added .component to package.json
  * Added debug.component.js build

0.6.0 / 2012-03-16
==================

  * Added support for "-" prefix in DEBUG [Vinay Pulim]
  * Added `.enabled` flag to the node version [TooTallNate]

0.5.0 / 2012-02-02
==================

  * Added: humanize diffs. Closes #8
  * Added `debug.disable()` to the CS variant
  * Removed padding. Closes #10
  * Fixed: persist client-side variant again. Closes #9

0.4.0 / 2012-02-01
==================

  * Added browser variant support for older browsers [TooTallNate]
  * Added `debug.enable('project:*')` to browser variant [TooTallNate]
  * Added padding to diff (moved it to the right)

0.3.0 / 2012-01-26
==================

  * Added millisecond diff when isatty, otherwise UTC string

0.2.0 / 2012-01-22
==================

  * Added wildcard support

0.1.0 / 2011-12-02
==================

  * Added: remove colors unless stderr isatty [TooTallNate]

0.0.1 / 2010-01-03
==================

  * Initial release


---

# debug
[![Build Status](https://travis-ci.org/visionmedia/debug.svg?branch=master)](https://travis-ci.org/visionmedia/debug)  [![Coverage Status](https://coveralls.io/repos/github/visionmedia/debug/badge.svg?branch=master)](https://coveralls.io/github/visionmedia/debug?branch=master)  [![Slack](https://visionmedia-community-slackin.now.sh/badge.svg)](https://visionmedia-community-slackin.now.sh/) [![OpenCollective](https://opencollective.com/debug/backers/badge.svg)](#backers) 
[![OpenCollective](https://opencollective.com/debug/sponsors/badge.svg)](#sponsors)



A tiny node.js debugging utility modelled after node core's debugging technique.

**Discussion around the V3 API is under way [here](https://github.com/visionmedia/debug/issues/370)**

## Installation

```bash
$ npm install debug
```

## Usage

`debug` exposes a function; simply pass this function the name of your module, and it will return a decorated version of `console.error` for you to pass debug statements to. This will allow you to toggle the debug output for different parts of your module as well as the module as a whole.

Example _app.js_:

```js
var debug = require('debug')('http')
  , http = require('http')
  , name = 'My App';

// fake app

debug('booting %s', name);

http.createServer(function(req, res){
  debug(req.method + ' ' + req.url);
  res.end('hello\n');
}).listen(3000, function(){
  debug('listening');
});

// fake worker of some kind

require('./worker');
```

Example _worker.js_:

```js
var debug = require('debug')('worker');

setInterval(function(){
  debug('doing some work');
}, 1000);
```

 The __DEBUG__ environment variable is then used to enable these based on space or comma-delimited names. Here are some examples:

  ![debug http and worker](http://f.cl.ly/items/18471z1H402O24072r1J/Screenshot.png)

  ![debug worker](http://f.cl.ly/items/1X413v1a3M0d3C2c1E0i/Screenshot.png)

#### Windows note

 On Windows the environment variable is set using the `set` command.

 ```cmd
 set DEBUG=*,-not_this
 ```

 Note that PowerShell uses different syntax to set environment variables.

 ```cmd
 $env:DEBUG = "*,-not_this"
  ```

Then, run the program to be debugged as usual.

## Millisecond diff

  When actively developing an application it can be useful to see when the time spent between one `debug()` call and the next. Suppose for example you invoke `debug()` before requesting a resource, and after as well, the "+NNNms" will show you how much time was spent between calls.

  ![](http://f.cl.ly/items/2i3h1d3t121M2Z1A3Q0N/Screenshot.png)

  When stdout is not a TTY, `Date#toUTCString()` is used, making it more useful for logging the debug information as shown below:

  ![](http://f.cl.ly/items/112H3i0e0o0P0a2Q2r11/Screenshot.png)

## Conventions

  If you're using this in one or more of your libraries, you _should_ use the name of your library so that developers may toggle debugging as desired without guessing names. If you have more than one debuggers you _should_ prefix them with your library name and use ":" to separate features. For example "bodyParser" from Connect would then be "connect:bodyParser".

## Wildcards

  The `*` character may be used as a wildcard. Suppose for example your library has debuggers named "connect:bodyParser", "connect:compress", "connect:session", instead of listing all three with `DEBUG=connect:bodyParser,connect:compress,connect:session`, you may simply do `DEBUG=connect:*`, or to run everything using this module simply use `DEBUG=*`.

  You can also exclude specific debuggers by prefixing them with a "-" character.  For example, `DEBUG=*,-connect:*` would include all debuggers except those starting with "connect:".

## Environment Variables

  When running through Node.js, you can set a few environment variables that will
  change the behavior of the debug logging:

| Name      | Purpose                                         |
|-----------|-------------------------------------------------|
| `DEBUG`   | Enables/disables specific debugging namespaces. |
| `DEBUG_COLORS`| Whether or not to use colors in the debug output. |
| `DEBUG_DEPTH` | Object inspection depth. |
| `DEBUG_SHOW_HIDDEN` | Shows hidden properties on inspected objects. |


  __Note:__ The environment variables beginning with `DEBUG_` end up being
  converted into an Options object that gets used with `%o`/`%O` formatters.
  See the Node.js documentation for
  [`util.inspect()`](https://nodejs.org/api/util.html#util_util_inspect_object_options)
  for the complete list.

## Formatters


  Debug uses [printf-style](https://wikipedia.org/wiki/Printf_format_string) formatting. Below are the officially supported formatters:

| Formatter | Representation |
|-----------|----------------|
| `%O`      | Pretty-print an Object on multiple lines. |
| `%o`      | Pretty-print an Object all on a single line. |
| `%s`      | String. |
| `%d`      | Number (both integer and float). |
| `%j`      | JSON. Replaced with the string '[Circular]' if the argument contains circular references. |
| `%%`      | Single percent sign ('%'). This does not consume an argument. |

### Custom formatters

  You can add custom formatters by extending the `debug.formatters` object. For example, if you wanted to add support for rendering a Buffer as hex with `%h`, you could do something like:

```js
const createDebug = require('debug')
createDebug.formatters.h = (v) => {
  return v.toString('hex')
}

// …elsewhere
const debug = createDebug('foo')
debug('this is hex: %h', new Buffer('hello world'))
//   foo this is hex: 68656c6c6f20776f726c6421 +0ms
```

## Browser support
  You can build a browser-ready script using [browserify](https://github.com/substack/node-browserify),
  or just use the [browserify-as-a-service](https://wzrd.in/) [build](https://wzrd.in/standalone/debug@latest),
  if you don't want to build it yourself.

  Debug's enable state is currently persisted by `localStorage`.
  Consider the situation shown below where you have `worker:a` and `worker:b`,
  and wish to debug both. You can enable this using `localStorage.debug`:

```js
localStorage.debug = 'worker:*'
```

And then refresh the page.

```js
a = debug('worker:a');
b = debug('worker:b');

setInterval(function(){
  a('doing some work');
}, 1000);

setInterval(function(){
  b('doing some work');
}, 1200);
```

#### Web Inspector Colors

  Colors are also enabled on "Web Inspectors" that understand the `%c` formatting
  option. These are WebKit web inspectors, Firefox ([since version
  31](https://hacks.mozilla.org/2014/05/editable-box-model-multiple-selection-sublime-text-keys-much-more-firefox-developer-tools-episode-31/))
  and the Firebug plugin for Firefox (any version).

  Colored output looks something like:

  ![](https://cloud.githubusercontent.com/assets/71256/3139768/b98c5fd8-e8ef-11e3-862a-f7253b6f47c6.png)


## Output streams

  By default `debug` will log to stderr, however this can be configured per-namespace by overriding the `log` method:

Example _stdout.js_:

```js
var debug = require('debug');
var error = debug('app:error');

// by default stderr is used
error('goes to stderr!');

var log = debug('app:log');
// set this namespace to log via console.log
log.log = console.log.bind(console); // don't forget to bind to console!
log('goes to stdout');
error('still goes to stderr!');

// set all output to go via console.info
// overrides all per-namespace log settings
debug.log = console.info.bind(console);
error('now goes to stdout via console.info');
log('still goes to stdout, but via console.info now');
```


## Authors

 - TJ Holowaychuk
 - Nathan Rajlich
 - Andrew Rhyne
 
## Backers

Support us with a monthly donation and help us continue our activities. [[Become a backer](https://opencollective.com/debug#backer)]

<a href="https://opencollective.com/debug/backer/0/website" target="_blank"><img src="https://opencollective.com/debug/backer/0/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/1/website" target="_blank"><img src="https://opencollective.com/debug/backer/1/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/2/website" target="_blank"><img src="https://opencollective.com/debug/backer/2/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/3/website" target="_blank"><img src="https://opencollective.com/debug/backer/3/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/4/website" target="_blank"><img src="https://opencollective.com/debug/backer/4/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/5/website" target="_blank"><img src="https://opencollective.com/debug/backer/5/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/6/website" target="_blank"><img src="https://opencollective.com/debug/backer/6/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/7/website" target="_blank"><img src="https://opencollective.com/debug/backer/7/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/8/website" target="_blank"><img src="https://opencollective.com/debug/backer/8/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/9/website" target="_blank"><img src="https://opencollective.com/debug/backer/9/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/10/website" target="_blank"><img src="https://opencollective.com/debug/backer/10/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/11/website" target="_blank"><img src="https://opencollective.com/debug/backer/11/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/12/website" target="_blank"><img src="https://opencollective.com/debug/backer/12/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/13/website" target="_blank"><img src="https://opencollective.com/debug/backer/13/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/14/website" target="_blank"><img src="https://opencollective.com/debug/backer/14/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/15/website" target="_blank"><img src="https://opencollective.com/debug/backer/15/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/16/website" target="_blank"><img src="https://opencollective.com/debug/backer/16/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/17/website" target="_blank"><img src="https://opencollective.com/debug/backer/17/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/18/website" target="_blank"><img src="https://opencollective.com/debug/backer/18/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/19/website" target="_blank"><img src="https://opencollective.com/debug/backer/19/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/20/website" target="_blank"><img src="https://opencollective.com/debug/backer/20/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/21/website" target="_blank"><img src="https://opencollective.com/debug/backer/21/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/22/website" target="_blank"><img src="https://opencollective.com/debug/backer/22/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/23/website" target="_blank"><img src="https://opencollective.com/debug/backer/23/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/24/website" target="_blank"><img src="https://opencollective.com/debug/backer/24/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/25/website" target="_blank"><img src="https://opencollective.com/debug/backer/25/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/26/website" target="_blank"><img src="https://opencollective.com/debug/backer/26/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/27/website" target="_blank"><img src="https://opencollective.com/debug/backer/27/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/28/website" target="_blank"><img src="https://opencollective.com/debug/backer/28/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/29/website" target="_blank"><img src="https://opencollective.com/debug/backer/29/avatar.svg"></a>


## Sponsors

Become a sponsor and get your logo on our README on Github with a link to your site. [[Become a sponsor](https://opencollective.com/debug#sponsor)]

<a href="https://opencollective.com/debug/sponsor/0/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/0/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/1/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/1/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/2/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/2/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/3/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/3/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/4/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/4/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/5/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/5/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/6/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/6/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/7/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/7/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/8/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/8/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/9/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/9/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/10/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/10/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/11/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/11/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/12/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/12/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/13/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/13/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/14/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/14/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/15/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/15/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/16/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/16/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/17/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/17/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/18/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/18/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/19/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/19/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/20/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/20/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/21/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/21/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/22/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/22/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/23/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/23/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/24/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/24/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/25/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/25/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/26/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/26/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/27/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/27/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/28/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/28/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/29/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/29/avatar.svg"></a>

## License

(The MIT License)

Copyright (c) 2014-2016 TJ Holowaychuk &lt;tj@vision-media.ca&gt;

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
'Software'), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


---

The MIT License (MIT)

Copyright (c) 2016 Zeit, Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# ms

[![Build Status](https://travis-ci.org/zeit/ms.svg?branch=master)](https://travis-ci.org/zeit/ms)
[![Slack Channel](http://zeit-slackin.now.sh/badge.svg)](https://zeit.chat/)

Use this package to easily convert various time formats to milliseconds.

## Examples

```js
ms('2 days')  // 172800000
ms('1d')      // 86400000
ms('10h')     // 36000000
ms('2.5 hrs') // 9000000
ms('2h')      // 7200000
ms('1m')      // 60000
ms('5s')      // 5000
ms('1y')      // 31557600000
ms('100')     // 100
```

### Convert from milliseconds

```js
ms(60000)             // "1m"
ms(2 * 60000)         // "2m"
ms(ms('10 hours'))    // "10h"
```

### Time format written-out

```js
ms(60000, { long: true })             // "1 minute"
ms(2 * 60000, { long: true })         // "2 minutes"
ms(ms('10 hours'), { long: true })    // "10 hours"
```

## Features

- Works both in [node](https://nodejs.org) and in the browser.
- If a number is supplied to `ms`, a string with a unit is returned.
- If a string that contains the number is supplied, it returns it as a number (e.g.: it returns `100` for `'100'`).
- If you pass a string with a number and a valid unit, the number of equivalent ms is returned.

## Caught a bug?

1. [Fork](https://help.github.com/articles/fork-a-repo/) this repository to your own GitHub account and then [clone](https://help.github.com/articles/cloning-a-repository/) it to your local device
2. Link the package to the global module directory: `npm link`
3. Within the module you want to test your local development instance of ms, just link it to the dependencies: `npm link ms`. Instead of the default one from npm, node will now use your clone of ms!

As always, you can run the tests using: `npm test`


---

# bonjour-service

![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/onlxltd/bonjour-service/publish-release.yml?style=flat-square) ![npm bundle size](https://img.shields.io/bundlephobia/min/bonjour-service?style=flat-square) ![GitHub Release Date](https://img.shields.io/github/release-date/onlxltd/bonjour-service?style=flat-square) ![npm](https://img.shields.io/npm/dw/bonjour-service?color=%23888&style=flat-square) ![GitHub](https://img.shields.io/github/license/onlxltd/bonjour-service?style=flat-square) [![DeepScan grade](https://deepscan.io/api/teams/13435/projects/16430/branches/352351/badge/grade.svg?style=flat-square)](https://deepscan.io/dashboard#view=project&tid=13435&pid=16430&bid=352351)

A Bonjour/Zeroconf protocol implementation in TypeScript. Publish
services on the local network or discover existing services using
multicast DNS.

This is a rewrite of the project Bonjour (https://github.com/watson/bonjour) into modern TypeScript.

bonjour-service is supported by [ON LX Limited](https://onlx.ltd/?src=bonjour-service). Check out our projects such as [Ctrl Suite](https://onlx.ltd/ctrl-suite?src=bonjour-service) and [Ctrl for iPad](https://onlx.ltd/ctrl-for-ipad?src=bonjour-service).



## Installation
Add to your project dependencies using Yarn or NPM.

#### Install with Yarn
```
yarn add bonjour-service
```
#### Install with NPM
```
npm install bonjour-service
```

## Usage

```js
import { Bonjour } from 'bonjour-service'

const instance = new Bonjour()

// advertise an HTTP server on port 3000
instance.publish({ name: 'My Web Server', type: 'http', port: 3000 })

// browse for all http services
instance.find({ type: 'http' }, function (service) {
  console.log('Found an HTTP server:', service)
})
```

## API

### Initializing

```js
var instance = new Bonjour({ options }, errorCallback)
```

The `options` are optional and will be used when initializing the
underlying multicast-dns server. For details see [the multicast-dns
documentation](https://github.com/mafintosh/multicast-dns#mdns--multicastdnsoptions).

`errorCallback` is an optional callback used to gracefully handle errors that would otherwise
crash the process. While not being strictly required, providing this is highly recommended

### Publishing

#### `var service = bonjour.publish(options)`

Publishes a new service.

Options are:

- `name` (string)
- `host` (string, optional) - defaults to local hostname
- `port` (number)
- `type` (string)
- `subtypes` (array of strings, optional)
- `protocol` (string, optional) - `udp` or `tcp` (default)
- `txt` (object, optional) - a key/value object to broadcast as the TXT
  record
- `disableIPv6` (boolean, optional) disble IPv6 addresses

IANA maintains a [list of official service types and port
numbers](http://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml).

#### `bonjour.unpublishAll([callback])`

Unpublish all services. The optional `callback` will be called when the
services have been unpublished.

#### `bonjour.destroy()`

Destroy the mdns instance. Closes the udp socket.

### Browser

#### `var browser = bonjour.find(options[, onup])`

Listen for services advertised on the network. An optional callback can
be provided as the 2nd argument and will be added as an event listener
for the `up` event.

Options (all optional):

- `type` (string)
- `subtypes` (array of strings)
- `protocol` (string) - defaults to `tcp`
- `txt` (object) - passed into [dns-txt
  module](https://github.com/watson/dns-txt) contructor. Set to `{
  binary: true }` if you want to keep the TXT records in binary

#### `var browser = bonjour.findOne(options[, callback])`

Listen for and call the `callback` with the first instance of a service
matching the `options`. If no `callback` is given, it's expected that
you listen for the `up` event. The returned `browser` will automatically
stop it self after the first matching service.

Options are the same as given in the `browser.find` function.

#### `Event: up`

Emitted every time a new service is found that matches the browser.

#### `Event: down`

Emitted every time an existing service emmits a goodbye message.

#### `Event: txt-update`

Emitted every time an existing service does a new announcement with an updated TXT record.

#### `browser.services()`

An array of services known by the browser to be online.

#### `browser.start()`

Start looking for matching services.

#### `browser.stop()`

Stop looking for matching services.

#### `browser.update()`

Broadcast the query again.

### Service

#### `Event: up`

Emitted when the service is up.

#### `Event: error`

Emitted if an error occurrs while publishing the service.

#### `service.stop([callback])`

Unpublish the service. The optional `callback` will be called when the
service have been unpublished.

#### `service.start()`

Publish the service.

#### `service.name`

The name of the service, e.g. `Apple TV`.

#### `service.type`

The type of the service, e.g. `http`.

#### `service.subtypes`

An array of subtypes. Note that this property might be `null`.

#### `service.protocol`

The protocol used by the service, e.g. `tcp`.

#### `service.host`

The hostname or ip address where the service resides.

#### `service.port`

The port on which the service listens, e.g. `5000`.

#### `service.fqdn`

The fully qualified domain name of the service. E.g. if given the name
`Foo Bar`, the type `http` and the protocol `tcp`, the `service.fqdn`
property will be `Foo Bar._http._tcp.local`.

#### `service.txt`

The TXT record advertised by the service (a key/value object). Note that
this property might be `null`.

#### `service.published`

A boolean indicating if the service is currently published.

## License

MIT


---

#boolbase
This very simple module provides two basic functions, one that always returns true (`trueFunc`) and one that always returns false (`falseFunc`).

###WTF?

By having only a single instance of these functions around, it's possible to do some nice optimizations. Eg. [`CSSselect`](https://github.com/fb55/CSSselect) uses these functions to determine whether a selector won't match any elements. If that's the case, the DOM doesn't even have to be touched.

###And why is this a separate module?

I'm trying to modularize `CSSselect` and most modules depend on these functions. IMHO, having a separate module is the easiest solution to this problem.

---

# boxen

> Create boxes in the terminal

![](screenshot.png)

## Install

```sh
npm install boxen
```

## Usage

```js
import boxen from 'boxen';

console.log(boxen('unicorn', {padding: 1}));
/*
┌─────────────┐
│             │
│   unicorn   │
│             │
└─────────────┘
*/

console.log(boxen('unicorn', {padding: 1, margin: 1, borderStyle: 'double'}));
/*

   ╔═════════════╗
   ║             ║
   ║   unicorn   ║
   ║             ║
   ╚═════════════╝

*/

console.log(boxen('unicorns love rainbows', {title: 'magical', titleAlignment: 'center'}));
/*
┌────── magical ───────┐
│unicorns love rainbows│
└──────────────────────┘
*/
```

## API

### boxen(text, options?)

#### text

Type: `string`

Text inside the box.

#### options

Type: `object`

##### borderColor

Type: `string`\
Values: `'black'` `'red'` `'green'` `'yellow'` `'blue'` `'magenta'` `'cyan'` `'white'` `'gray'` or a hex value like `'#ff0000'`

Color of the box border.

##### borderStyle

Type: `string | object`\
Default: `'single'`\
Values:
- `'single'`
```
┌───┐
│foo│
└───┘
```
- `'double'`
```
╔═══╗
║foo║
╚═══╝
```
- `'round'` (`'single'` sides with round corners)
```
╭───╮
│foo│
╰───╯
```
- `'bold'`
```
┏━━━┓
┃foo┃
┗━━━┛
```
- `'singleDouble'` (`'single'` on top and bottom, `'double'` on right and left)
```
╓───╖
║foo║
╙───╜
```
- `'doubleSingle'` (`'double'` on top and bottom, `'single'` on right and left)
```
╒═══╕
│foo│
╘═══╛
```
- `'classic'`
```
+---+
|foo|
+---+
```
- `'arrow'`
```
↘↓↓↓↙
→foo←
↗↑↑↑↖
```

Style of the box border.

Can be any of the above predefined styles or an object with the following keys:

```js
{
	topLeft: '+',
	topRight: '+',
	bottomLeft: '+',
	bottomRight: '+',
	top: '-',
	bottom: '-',
	left: '|',
	right: '|'
}
```

##### dimBorder

Type: `boolean`\
Default: `false`

Reduce opacity of the border.

##### title

Type: `string`

Display a title at the top of the box.
If needed, the box will horizontally expand to fit the title.

Example:
```js
console.log(boxen('foo bar', {title: 'example'}));
/*
┌ example ┐
│foo bar  │
└─────────┘
*/
```

##### titleAlignment

Type: `string`\
Default: `'left'`

Align the title in the top bar.

Values:
- `'left'`
```js
/*
┌ example ──────┐
│foo bar foo bar│
└───────────────┘
*/
```
- `'center'`
```js
/*
┌─── example ───┐
│foo bar foo bar│
└───────────────┘
*/
```
- `'right'`
```js
/*
┌────── example ┐
│foo bar foo bar│
└───────────────┘
*/
```

##### width

Type: `number`

Set a fixed width for the box.

*Note:* This disables terminal overflow handling and may cause the box to look broken if the user's terminal is not wide enough.

##### padding

Type: `number | object`\
Default: `0`

Space between the text and box border.

Accepts a number or an object with any of the `top`, `right`, `bottom`, `left` properties. When a number is specified, the left/right padding is 3 times the top/bottom to make it look nice.

##### margin

Type: `number | object`\
Default: `0`

Space around the box.

Accepts a number or an object with any of the `top`, `right`, `bottom`, `left` properties. When a number is specified, the left/right margin is 3 times the top/bottom to make it look nice.

##### float

Type: `string`\
Default: `'left'`\
Values: `'right'` `'center'` `'left'`

Float the box on the available terminal screen space.

##### backgroundColor

Type: `string`\
Values: `'black'` `'red'` `'green'` `'yellow'` `'blue'` `'magenta'` `'cyan'` `'white'` `'gray'` or a hex value like `'#ff0000'`

Color of the background.

##### textAlignment

Type: `string`\
Default: `'left'`\
Values: `'left'` `'center'` `'right'`

Align the text in the box based on the widest line.

## Maintainer

- [Sindre Sorhus](https://github.com/sindresorhus)
- [Caesarovich](https://github.com/Caesarovich)

## Related

- [boxen-cli](https://github.com/sindresorhus/boxen-cli) - CLI for this module
- [cli-boxes](https://github.com/sindresorhus/cli-boxes) - Boxes for use in the terminal
- [ink-box](https://github.com/sindresorhus/ink-box) - Box component for Ink that uses this package

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-boxen?utm_source=npm-boxen&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

# brace-expansion

[Brace expansion](https://www.gnu.org/software/bash/manual/html_node/Brace-Expansion.html), 
as known from sh/bash, in JavaScript.

[![build status](https://secure.travis-ci.org/juliangruber/brace-expansion.svg)](http://travis-ci.org/juliangruber/brace-expansion)
[![downloads](https://img.shields.io/npm/dm/brace-expansion.svg)](https://www.npmjs.org/package/brace-expansion)
[![Greenkeeper badge](https://badges.greenkeeper.io/juliangruber/brace-expansion.svg)](https://greenkeeper.io/)

[![testling badge](https://ci.testling.com/juliangruber/brace-expansion.png)](https://ci.testling.com/juliangruber/brace-expansion)

## Example

```js
var expand = require('brace-expansion');

expand('file-{a,b,c}.jpg')
// => ['file-a.jpg', 'file-b.jpg', 'file-c.jpg']

expand('-v{,,}')
// => ['-v', '-v', '-v']

expand('file{0..2}.jpg')
// => ['file0.jpg', 'file1.jpg', 'file2.jpg']

expand('file-{a..c}.jpg')
// => ['file-a.jpg', 'file-b.jpg', 'file-c.jpg']

expand('file{2..0}.jpg')
// => ['file2.jpg', 'file1.jpg', 'file0.jpg']

expand('file{0..4..2}.jpg')
// => ['file0.jpg', 'file2.jpg', 'file4.jpg']

expand('file-{a..e..2}.jpg')
// => ['file-a.jpg', 'file-c.jpg', 'file-e.jpg']

expand('file{00..10..5}.jpg')
// => ['file00.jpg', 'file05.jpg', 'file10.jpg']

expand('{{A..C},{a..c}}')
// => ['A', 'B', 'C', 'a', 'b', 'c']

expand('ppp{,config,oe{,conf}}')
// => ['ppp', 'pppconfig', 'pppoe', 'pppoeconf']
```

## API

```js
var expand = require('brace-expansion');
```

### var expanded = expand(str)

Return an array of all possible and valid expansions of `str`. If none are
found, `[str]` is returned.

Valid expansions are:

```js
/^(.*,)+(.+)?$/
// {a,b,...}
```

A comma separated list of options, like `{a,b}` or `{a,{b,c}}` or `{,a,}`.

```js
/^-?\d+\.\.-?\d+(\.\.-?\d+)?$/
// {x..y[..incr]}
```

A numeric sequence from `x` to `y` inclusive, with optional increment.
If `x` or `y` start with a leading `0`, all the numbers will be padded
to have equal length. Negative numbers and backwards iteration work too.

```js
/^-?\d+\.\.-?\d+(\.\.-?\d+)?$/
// {x..y[..incr]}
```

An alphabetic sequence from `x` to `y` inclusive, with optional increment.
`x` and `y` must be exactly one character, and if given, `incr` must be a
number.

For compatibility reasons, the string `${` is not eligible for brace expansion.

## Installation

With [npm](https://npmjs.org) do:

```bash
npm install brace-expansion
```

## Contributors

- [Julian Gruber](https://github.com/juliangruber)
- [Isaac Z. Schlueter](https://github.com/isaacs)

## Sponsors

This module is proudly supported by my [Sponsors](https://github.com/juliangruber/sponsors)!

Do you want to support modules like this to improve their quality, stability and weigh in on new features? Then please consider donating to my [Patreon](https://www.patreon.com/juliangruber). Not sure how much of my modules you're using? Try [feross/thanks](https://github.com/feross/thanks)!

## License

(MIT)

Copyright (c) 2013 Julian Gruber &lt;julian@juliangruber.com&gt;

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# braces [![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=W8YFZ425KND68) [![NPM version](https://img.shields.io/npm/v/braces.svg?style=flat)](https://www.npmjs.com/package/braces) [![NPM monthly downloads](https://img.shields.io/npm/dm/braces.svg?style=flat)](https://npmjs.org/package/braces) [![NPM total downloads](https://img.shields.io/npm/dt/braces.svg?style=flat)](https://npmjs.org/package/braces) [![Linux Build Status](https://img.shields.io/travis/micromatch/braces.svg?style=flat&label=Travis)](https://travis-ci.org/micromatch/braces)

> Bash-like brace expansion, implemented in JavaScript. Safer than other brace expansion libs, with complete support for the Bash 4.3 braces specification, without sacrificing speed.

Please consider following this project's author, [Jon Schlinkert](https://github.com/jonschlinkert), and consider starring the project to show your :heart: and support.

## Install

Install with [npm](https://www.npmjs.com/):

```sh
$ npm install --save braces
```

## v3.0.0 Released!!

See the [changelog](CHANGELOG.md) for details.

## Why use braces?

Brace patterns make globs more powerful by adding the ability to match specific ranges and sequences of characters.

- **Accurate** - complete support for the [Bash 4.3 Brace Expansion](www.gnu.org/software/bash/) specification (passes all of the Bash braces tests)
- **[fast and performant](#benchmarks)** - Starts fast, runs fast and [scales well](#performance) as patterns increase in complexity.
- **Organized code base** - The parser and compiler are easy to maintain and update when edge cases crop up.
- **Well-tested** - Thousands of test assertions, and passes all of the Bash, minimatch, and [brace-expansion](https://github.com/juliangruber/brace-expansion) unit tests (as of the date this was written).
- **Safer** - You shouldn't have to worry about users defining aggressive or malicious brace patterns that can break your application. Braces takes measures to prevent malicious regex that can be used for DDoS attacks (see [catastrophic backtracking](https://www.regular-expressions.info/catastrophic.html)).
- [Supports lists](#lists) - (aka "sets") `a/{b,c}/d` => `['a/b/d', 'a/c/d']`
- [Supports sequences](#sequences) - (aka "ranges") `{01..03}` => `['01', '02', '03']`
- [Supports steps](#steps) - (aka "increments") `{2..10..2}` => `['2', '4', '6', '8', '10']`
- [Supports escaping](#escaping) - To prevent evaluation of special characters.

## Usage

The main export is a function that takes one or more brace `patterns` and `options`.

```js
const braces = require('braces');
// braces(patterns[, options]);

console.log(braces(['{01..05}', '{a..e}']));
//=> ['(0[1-5])', '([a-e])']

console.log(braces(['{01..05}', '{a..e}'], { expand: true }));
//=> ['01', '02', '03', '04', '05', 'a', 'b', 'c', 'd', 'e']
```

### Brace Expansion vs. Compilation

By default, brace patterns are compiled into strings that are optimized for creating regular expressions and matching.

**Compiled**

```js
console.log(braces('a/{x,y,z}/b'));
//=> ['a/(x|y|z)/b']
console.log(braces(['a/{01..20}/b', 'a/{1..5}/b']));
//=> [ 'a/(0[1-9]|1[0-9]|20)/b', 'a/([1-5])/b' ]
```

**Expanded**

Enable brace expansion by setting the `expand` option to true, or by using [braces.expand()](#expand) (returns an array similar to what you'd expect from Bash, or `echo {1..5}`, or [minimatch](https://github.com/isaacs/minimatch)):

```js
console.log(braces('a/{x,y,z}/b', { expand: true }));
//=> ['a/x/b', 'a/y/b', 'a/z/b']

console.log(braces.expand('{01..10}'));
//=> ['01','02','03','04','05','06','07','08','09','10']
```

### Lists

Expand lists (like Bash "sets"):

```js
console.log(braces('a/{foo,bar,baz}/*.js'));
//=> ['a/(foo|bar|baz)/*.js']

console.log(braces.expand('a/{foo,bar,baz}/*.js'));
//=> ['a/foo/*.js', 'a/bar/*.js', 'a/baz/*.js']
```

### Sequences

Expand ranges of characters (like Bash "sequences"):

```js
console.log(braces.expand('{1..3}')); // ['1', '2', '3']
console.log(braces.expand('a/{1..3}/b')); // ['a/1/b', 'a/2/b', 'a/3/b']
console.log(braces('{a..c}', { expand: true })); // ['a', 'b', 'c']
console.log(braces('foo/{a..c}', { expand: true })); // ['foo/a', 'foo/b', 'foo/c']

// supports zero-padded ranges
console.log(braces('a/{01..03}/b')); //=> ['a/(0[1-3])/b']
console.log(braces('a/{001..300}/b')); //=> ['a/(0{2}[1-9]|0[1-9][0-9]|[12][0-9]{2}|300)/b']
```

See [fill-range](https://github.com/jonschlinkert/fill-range) for all available range-expansion options.

### Steppped ranges

Steps, or increments, may be used with ranges:

```js
console.log(braces.expand('{2..10..2}'));
//=> ['2', '4', '6', '8', '10']

console.log(braces('{2..10..2}'));
//=> ['(2|4|6|8|10)']
```

When the [.optimize](#optimize) method is used, or [options.optimize](#optionsoptimize) is set to true, sequences are passed to [to-regex-range](https://github.com/jonschlinkert/to-regex-range) for expansion.

### Nesting

Brace patterns may be nested. The results of each expanded string are not sorted, and left to right order is preserved.

**"Expanded" braces**

```js
console.log(braces.expand('a{b,c,/{x,y}}/e'));
//=> ['ab/e', 'ac/e', 'a/x/e', 'a/y/e']

console.log(braces.expand('a/{x,{1..5},y}/c'));
//=> ['a/x/c', 'a/1/c', 'a/2/c', 'a/3/c', 'a/4/c', 'a/5/c', 'a/y/c']
```

**"Optimized" braces**

```js
console.log(braces('a{b,c,/{x,y}}/e'));
//=> ['a(b|c|/(x|y))/e']

console.log(braces('a/{x,{1..5},y}/c'));
//=> ['a/(x|([1-5])|y)/c']
```

### Escaping

**Escaping braces**

A brace pattern will not be expanded or evaluted if _either the opening or closing brace is escaped_:

```js
console.log(braces.expand('a\\{d,c,b}e'));
//=> ['a{d,c,b}e']

console.log(braces.expand('a{d,c,b\\}e'));
//=> ['a{d,c,b}e']
```

**Escaping commas**

Commas inside braces may also be escaped:

```js
console.log(braces.expand('a{b\\,c}d'));
//=> ['a{b,c}d']

console.log(braces.expand('a{d\\,c,b}e'));
//=> ['ad,ce', 'abe']
```

**Single items**

Following bash conventions, a brace pattern is also not expanded when it contains a single character:

```js
console.log(braces.expand('a{b}c'));
//=> ['a{b}c']
```

## Options

### options.maxLength

**Type**: `Number`

**Default**: `10,000`

**Description**: Limit the length of the input string. Useful when the input string is generated or your application allows users to pass a string, et cetera.

```js
console.log(braces('a/{b,c}/d', { maxLength: 3 })); //=> throws an error
```

### options.expand

**Type**: `Boolean`

**Default**: `undefined`

**Description**: Generate an "expanded" brace pattern (alternatively you can use the `braces.expand()` method, which does the same thing).

```js
console.log(braces('a/{b,c}/d', { expand: true }));
//=> [ 'a/b/d', 'a/c/d' ]
```

### options.nodupes

**Type**: `Boolean`

**Default**: `undefined`

**Description**: Remove duplicates from the returned array.

### options.rangeLimit

**Type**: `Number`

**Default**: `1000`

**Description**: To prevent malicious patterns from being passed by users, an error is thrown when `braces.expand()` is used or `options.expand` is true and the generated range will exceed the `rangeLimit`.

You can customize `options.rangeLimit` or set it to `Inifinity` to disable this altogether.

**Examples**

```js
// pattern exceeds the "rangeLimit", so it's optimized automatically
console.log(braces.expand('{1..1000}'));
//=> ['([1-9]|[1-9][0-9]{1,2}|1000)']

// pattern does not exceed "rangeLimit", so it's NOT optimized
console.log(braces.expand('{1..100}'));
//=> ['1', '2', '3', '4', '5', '6', '7', '8', '9', '10', '11', '12', '13', '14', '15', '16', '17', '18', '19', '20', '21', '22', '23', '24', '25', '26', '27', '28', '29', '30', '31', '32', '33', '34', '35', '36', '37', '38', '39', '40', '41', '42', '43', '44', '45', '46', '47', '48', '49', '50', '51', '52', '53', '54', '55', '56', '57', '58', '59', '60', '61', '62', '63', '64', '65', '66', '67', '68', '69', '70', '71', '72', '73', '74', '75', '76', '77', '78', '79', '80', '81', '82', '83', '84', '85', '86', '87', '88', '89', '90', '91', '92', '93', '94', '95', '96', '97', '98', '99', '100']
```

### options.transform

**Type**: `Function`

**Default**: `undefined`

**Description**: Customize range expansion.

**Example: Transforming non-numeric values**

```js
const alpha = braces.expand('x/{a..e}/y', {
  transform(value, index) {
    // When non-numeric values are passed, "value" is a character code.
    return 'foo/' + String.fromCharCode(value) + '-' + index;
  },
});
console.log(alpha);
//=> [ 'x/foo/a-0/y', 'x/foo/b-1/y', 'x/foo/c-2/y', 'x/foo/d-3/y', 'x/foo/e-4/y' ]
```

**Example: Transforming numeric values**

```js
const numeric = braces.expand('{1..5}', {
  transform(value) {
    // when numeric values are passed, "value" is a number
    return 'foo/' + value * 2;
  },
});
console.log(numeric);
//=> [ 'foo/2', 'foo/4', 'foo/6', 'foo/8', 'foo/10' ]
```

### options.quantifiers

**Type**: `Boolean`

**Default**: `undefined`

**Description**: In regular expressions, quanitifiers can be used to specify how many times a token can be repeated. For example, `a{1,3}` will match the letter `a` one to three times.

Unfortunately, regex quantifiers happen to share the same syntax as [Bash lists](#lists)

The `quantifiers` option tells braces to detect when [regex quantifiers](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp#quantifiers) are defined in the given pattern, and not to try to expand them as lists.

**Examples**

```js
const braces = require('braces');
console.log(braces('a/b{1,3}/{x,y,z}'));
//=> [ 'a/b(1|3)/(x|y|z)' ]
console.log(braces('a/b{1,3}/{x,y,z}', { quantifiers: true }));
//=> [ 'a/b{1,3}/(x|y|z)' ]
console.log(braces('a/b{1,3}/{x,y,z}', { quantifiers: true, expand: true }));
//=> [ 'a/b{1,3}/x', 'a/b{1,3}/y', 'a/b{1,3}/z' ]
```

### options.keepEscaping

**Type**: `Boolean`

**Default**: `undefined`

**Description**: Do not strip backslashes that were used for escaping from the result.

## What is "brace expansion"?

Brace expansion is a type of parameter expansion that was made popular by unix shells for generating lists of strings, as well as regex-like matching when used alongside wildcards (globs).

In addition to "expansion", braces are also used for matching. In other words:

- [brace expansion](#brace-expansion) is for generating new lists
- [brace matching](#brace-matching) is for filtering existing lists

<details>
<summary><strong>More about brace expansion</strong> (click to expand)</summary>

There are two main types of brace expansion:

1. **lists**: which are defined using comma-separated values inside curly braces: `{a,b,c}`
2. **sequences**: which are defined using a starting value and an ending value, separated by two dots: `a{1..3}b`. Optionally, a third argument may be passed to define a "step" or increment to use: `a{1..100..10}b`. These are also sometimes referred to as "ranges".

Here are some example brace patterns to illustrate how they work:

**Sets**

```
{a,b,c}       => a b c
{a,b,c}{1,2}  => a1 a2 b1 b2 c1 c2
```

**Sequences**

```
{1..9}        => 1 2 3 4 5 6 7 8 9
{4..-4}       => 4 3 2 1 0 -1 -2 -3 -4
{1..20..3}    => 1 4 7 10 13 16 19
{a..j}        => a b c d e f g h i j
{j..a}        => j i h g f e d c b a
{a..z..3}     => a d g j m p s v y
```

**Combination**

Sets and sequences can be mixed together or used along with any other strings.

```
{a,b,c}{1..3}   => a1 a2 a3 b1 b2 b3 c1 c2 c3
foo/{a,b,c}/bar => foo/a/bar foo/b/bar foo/c/bar
```

The fact that braces can be "expanded" from relatively simple patterns makes them ideal for quickly generating test fixtures, file paths, and similar use cases.

## Brace matching

In addition to _expansion_, brace patterns are also useful for performing regular-expression-like matching.

For example, the pattern `foo/{1..3}/bar` would match any of following strings:

```
foo/1/bar
foo/2/bar
foo/3/bar
```

But not:

```
baz/1/qux
baz/2/qux
baz/3/qux
```

Braces can also be combined with [glob patterns](https://github.com/jonschlinkert/micromatch) to perform more advanced wildcard matching. For example, the pattern `*/{1..3}/*` would match any of following strings:

```
foo/1/bar
foo/2/bar
foo/3/bar
baz/1/qux
baz/2/qux
baz/3/qux
```

## Brace matching pitfalls

Although brace patterns offer a user-friendly way of matching ranges or sets of strings, there are also some major disadvantages and potential risks you should be aware of.

### tldr

**"brace bombs"**

- brace expansion can eat up a huge amount of processing resources
- as brace patterns increase _linearly in size_, the system resources required to expand the pattern increase exponentially
- users can accidentally (or intentially) exhaust your system's resources resulting in the equivalent of a DoS attack (bonus: no programming knowledge is required!)

For a more detailed explanation with examples, see the [geometric complexity](#geometric-complexity) section.

### The solution

Jump to the [performance section](#performance) to see how Braces solves this problem in comparison to other libraries.

### Geometric complexity

At minimum, brace patterns with sets limited to two elements have quadradic or `O(n^2)` complexity. But the complexity of the algorithm increases exponentially as the number of sets, _and elements per set_, increases, which is `O(n^c)`.

For example, the following sets demonstrate quadratic (`O(n^2)`) complexity:

```
{1,2}{3,4}      => (2X2)    => 13 14 23 24
{1,2}{3,4}{5,6} => (2X2X2)  => 135 136 145 146 235 236 245 246
```

But add an element to a set, and we get a n-fold Cartesian product with `O(n^c)` complexity:

```
{1,2,3}{4,5,6}{7,8,9} => (3X3X3) => 147 148 149 157 158 159 167 168 169 247 248
                                    249 257 258 259 267 268 269 347 348 349 357
                                    358 359 367 368 369
```

Now, imagine how this complexity grows given that each element is a n-tuple:

```
{1..100}{1..100}         => (100X100)     => 10,000 elements (38.4 kB)
{1..100}{1..100}{1..100} => (100X100X100) => 1,000,000 elements (5.76 MB)
```

Although these examples are clearly contrived, they demonstrate how brace patterns can quickly grow out of control.

**More information**

Interested in learning more about brace expansion?

- [linuxjournal/bash-brace-expansion](http://www.linuxjournal.com/content/bash-brace-expansion)
- [rosettacode/Brace_expansion](https://rosettacode.org/wiki/Brace_expansion)
- [cartesian product](https://en.wikipedia.org/wiki/Cartesian_product)

</details>

## Performance

Braces is not only screaming fast, it's also more accurate the other brace expansion libraries.

### Better algorithms

Fortunately there is a solution to the ["brace bomb" problem](#brace-matching-pitfalls): _don't expand brace patterns into an array when they're used for matching_.

Instead, convert the pattern into an optimized regular expression. This is easier said than done, and braces is the only library that does this currently.

**The proof is in the numbers**

Minimatch gets exponentially slower as patterns increase in complexity, braces does not. The following results were generated using `braces()` and `minimatch.braceExpand()`, respectively.

| **Pattern**                 | **braces**          | **[minimatch][]**            |
| --------------------------- | ------------------- | ---------------------------- |
| `{1..9007199254740991}`[^1] | `298 B` (5ms 459μs) | N/A (freezes)                |
| `{1..1000000000000000}`     | `41 B` (1ms 15μs)   | N/A (freezes)                |
| `{1..100000000000000}`      | `40 B` (890μs)      | N/A (freezes)                |
| `{1..10000000000000}`       | `39 B` (2ms 49μs)   | N/A (freezes)                |
| `{1..1000000000000}`        | `38 B` (608μs)      | N/A (freezes)                |
| `{1..100000000000}`         | `37 B` (397μs)      | N/A (freezes)                |
| `{1..10000000000}`          | `35 B` (983μs)      | N/A (freezes)                |
| `{1..1000000000}`           | `34 B` (798μs)      | N/A (freezes)                |
| `{1..100000000}`            | `33 B` (733μs)      | N/A (freezes)                |
| `{1..10000000}`             | `32 B` (5ms 632μs)  | `78.89 MB` (16s 388ms 569μs) |
| `{1..1000000}`              | `31 B` (1ms 381μs)  | `6.89 MB` (1s 496ms 887μs)   |
| `{1..100000}`               | `30 B` (950μs)      | `588.89 kB` (146ms 921μs)    |
| `{1..10000}`                | `29 B` (1ms 114μs)  | `48.89 kB` (14ms 187μs)      |
| `{1..1000}`                 | `28 B` (760μs)      | `3.89 kB` (1ms 453μs)        |
| `{1..100}`                  | `22 B` (345μs)      | `291 B` (196μs)              |
| `{1..10}`                   | `10 B` (533μs)      | `20 B` (37μs)                |
| `{1..3}`                    | `7 B` (190μs)       | `5 B` (27μs)                 |

### Faster algorithms

When you need expansion, braces is still much faster.

_(the following results were generated using `braces.expand()` and `minimatch.braceExpand()`, respectively)_

| **Pattern**     | **braces**                  | **[minimatch][]**            |
| --------------- | --------------------------- | ---------------------------- |
| `{1..10000000}` | `78.89 MB` (2s 698ms 642μs) | `78.89 MB` (18s 601ms 974μs) |
| `{1..1000000}`  | `6.89 MB` (458ms 576μs)     | `6.89 MB` (1s 491ms 621μs)   |
| `{1..100000}`   | `588.89 kB` (20ms 728μs)    | `588.89 kB` (156ms 919μs)    |
| `{1..10000}`    | `48.89 kB` (2ms 202μs)      | `48.89 kB` (13ms 641μs)      |
| `{1..1000}`     | `3.89 kB` (1ms 796μs)       | `3.89 kB` (1ms 958μs)        |
| `{1..100}`      | `291 B` (424μs)             | `291 B` (211μs)              |
| `{1..10}`       | `20 B` (487μs)              | `20 B` (72μs)                |
| `{1..3}`        | `5 B` (166μs)               | `5 B` (27μs)                 |

If you'd like to run these comparisons yourself, see [test/support/generate.js](test/support/generate.js).

## Benchmarks

### Running benchmarks

Install dev dependencies:

```bash
npm i -d && npm benchmark
```

### Latest results

Braces is more accurate, without sacrificing performance.

```bash
● expand - range (expanded)
     braces x 53,167 ops/sec ±0.12% (102 runs sampled)
  minimatch x 11,378 ops/sec ±0.10% (102 runs sampled)
● expand - range (optimized for regex)
     braces x 373,442 ops/sec ±0.04% (100 runs sampled)
  minimatch x 3,262 ops/sec ±0.18% (100 runs sampled)
● expand - nested ranges (expanded)
     braces x 33,921 ops/sec ±0.09% (99 runs sampled)
  minimatch x 10,855 ops/sec ±0.28% (100 runs sampled)
● expand - nested ranges (optimized for regex)
     braces x 287,479 ops/sec ±0.52% (98 runs sampled)
  minimatch x 3,219 ops/sec ±0.28% (101 runs sampled)
● expand - set (expanded)
     braces x 238,243 ops/sec ±0.19% (97 runs sampled)
  minimatch x 538,268 ops/sec ±0.31% (96 runs sampled)
● expand - set (optimized for regex)
     braces x 321,844 ops/sec ±0.10% (97 runs sampled)
  minimatch x 140,600 ops/sec ±0.15% (100 runs sampled)
● expand - nested sets (expanded)
     braces x 165,371 ops/sec ±0.42% (96 runs sampled)
  minimatch x 337,720 ops/sec ±0.28% (100 runs sampled)
● expand - nested sets (optimized for regex)
     braces x 242,948 ops/sec ±0.12% (99 runs sampled)
  minimatch x 87,403 ops/sec ±0.79% (96 runs sampled)
```

## About

<details>
<summary><strong>Contributing</strong></summary>

Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).

</details>

<details>
<summary><strong>Running Tests</strong></summary>

Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

```sh
$ npm install && npm test
```

</details>

<details>
<summary><strong>Building docs</strong></summary>

_(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_

To generate the readme, run the following command:

```sh
$ npm install -g verbose/verb#dev verb-generate-readme && verb
```

</details>

### Contributors

| **Commits** | **Contributor**                                               |
| ----------- | ------------------------------------------------------------- |
| 197         | [jonschlinkert](https://github.com/jonschlinkert)             |
| 4           | [doowb](https://github.com/doowb)                             |
| 1           | [es128](https://github.com/es128)                             |
| 1           | [eush77](https://github.com/eush77)                           |
| 1           | [hemanth](https://github.com/hemanth)                         |
| 1           | [wtgtybhertgeghgtwtg](https://github.com/wtgtybhertgeghgtwtg) |

### Author

**Jon Schlinkert**

- [GitHub Profile](https://github.com/jonschlinkert)
- [Twitter Profile](https://twitter.com/jonschlinkert)
- [LinkedIn Profile](https://linkedin.com/in/jonschlinkert)

### License

Copyright © 2019, [Jon Schlinkert](https://github.com/jonschlinkert).
Released under the [MIT License](LICENSE).

---

_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.8.0, on April 08, 2019._


---

# Browserslist [![Cult Of Martians][cult-img]][cult]

<img width="120" height="120" alt="Browserslist logo by Anton Popov"
     src="https://browsersl.ist/logo.svg" align="right">

The config to share target browsers and Node.js versions between different
front-end tools. It is used in:

* [Autoprefixer]
* [Babel]
* [postcss-preset-env]
* [eslint-plugin-compat]
* [stylelint-no-unsupported-browser-features]
* [postcss-normalize]
* [obsolete-webpack-plugin]

All tools will find target browsers automatically,
when you add the following to `package.json`:

```json
  "browserslist": [
    "defaults and fully supports es6-module",
    "maintained node versions"
  ]
```

Or in `.browserslistrc` config:

```yaml
# Browsers that we support

defaults and fully supports es6-module
maintained node versions
```

Developers set their version lists using queries like `last 2 versions`
to be free from updating versions manually.
Browserslist will use [`caniuse-lite`] with [Can I Use] data for this queries.

You can check how config works at our playground: [`browsersl.ist`](https://browsersl.ist/)

<a href="https://browsersl.ist/">
  <img src="/img/screenshot.webp" alt="browsersl.ist website">
</a>

<br>
<br>
<div align="center">
  <a href="https://evilmartians.com/?utm_source=browserslist"><img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg" alt="Sponsored by Evil Martians" width="236" height="54"></a>  <a href="https://cube.dev/?ref=eco-browserslist-github"><img src="https://user-images.githubusercontent.com/986756/154330861-d79ab8ec-aacb-4af8-9e17-1b28f1eccb01.svg" alt="Supported by Cube" width="227" height="46"></a>
</div>

[stylelint-no-unsupported-browser-features]: https://github.com/ismay/stylelint-no-unsupported-browser-features
[obsolete-webpack-plugin]:                   https://github.com/ElemeFE/obsolete-webpack-plugin
[eslint-plugin-compat]:                      https://github.com/amilajack/eslint-plugin-compat
[Browserslist Example]:                      https://github.com/browserslist/browserslist-example
[postcss-preset-env]:                        https://github.com/csstools/postcss-plugins/tree/main/plugin-packs/postcss-preset-env
[postcss-normalize]:                         https://github.com/csstools/postcss-normalize
[`browsersl.ist`]:                           https://browsersl.ist/
[`caniuse-lite`]:                            https://github.com/ben-eb/caniuse-lite
[Autoprefixer]:                              https://github.com/postcss/autoprefixer
[Can I Use]:                                 https://caniuse.com/
[Babel]:                                     https://github.com/babel/babel/tree/master/packages/babel-preset-env
[cult-img]: https://cultofmartians.com/assets/badges/badge.svg
[cult]: https://cultofmartians.com/done.html

## Docs
Read full docs **[here](https://github.com/browserslist/browserslist#readme)**.


---

# Buffer From

A [ponyfill](https://ponyfill.com) for `Buffer.from`, uses native implementation if available.

## Installation

```sh
npm install --save buffer-from
```

## Usage

```js
const bufferFrom = require('buffer-from')

console.log(bufferFrom([1, 2, 3, 4]))
//=> <Buffer 01 02 03 04>

const arr = new Uint8Array([1, 2, 3, 4])
console.log(bufferFrom(arr.buffer, 1, 2))
//=> <Buffer 02 03>

console.log(bufferFrom('test', 'utf8'))
//=> <Buffer 74 65 73 74>

const buf = bufferFrom('test')
console.log(bufferFrom(buf))
//=> <Buffer 74 65 73 74>
```

## API

### bufferFrom(array)

- `array` &lt;Array&gt;

Allocates a new `Buffer` using an `array` of octets.

### bufferFrom(arrayBuffer[, byteOffset[, length]])

- `arrayBuffer` &lt;ArrayBuffer&gt; The `.buffer` property of a TypedArray or ArrayBuffer
- `byteOffset` &lt;Integer&gt; Where to start copying from `arrayBuffer`. **Default:** `0`
- `length` &lt;Integer&gt; How many bytes to copy from `arrayBuffer`. **Default:** `arrayBuffer.length - byteOffset`

When passed a reference to the `.buffer` property of a TypedArray instance, the
newly created `Buffer` will share the same allocated memory as the TypedArray.

The optional `byteOffset` and `length` arguments specify a memory range within
the `arrayBuffer` that will be shared by the `Buffer`.

### bufferFrom(buffer)

- `buffer` &lt;Buffer&gt; An existing `Buffer` to copy data from

Copies the passed `buffer` data onto a new `Buffer` instance.

### bufferFrom(string[, encoding])

- `string` &lt;String&gt; A string to encode.
- `encoding` &lt;String&gt; The encoding of `string`. **Default:** `'utf8'`

Creates a new `Buffer` containing the given JavaScript string `string`. If
provided, the `encoding` parameter identifies the character encoding of
`string`.

## See also

- [buffer-alloc](https://github.com/LinusU/buffer-alloc) A ponyfill for `Buffer.alloc`
- [buffer-alloc-unsafe](https://github.com/LinusU/buffer-alloc-unsafe) A ponyfill for `Buffer.allocUnsafe`


---

3.0.0 / 2017-08-31
==================

  * Change "kB" to "KB" in format output
  * Remove support for Node.js 0.6
  * Remove support for ComponentJS

2.5.0 / 2017-03-24
==================

  * Add option "unit"

2.4.0 / 2016-06-01
==================

  * Add option "unitSeparator"

2.3.0 / 2016-02-15
==================

  * Drop partial bytes on all parsed units
  * Fix non-finite numbers to `.format` to return `null`
  * Fix parsing byte string that looks like hex
  * perf: hoist regular expressions

2.2.0 / 2015-11-13
==================

  * add option "decimalPlaces"
  * add option "fixedDecimals"

2.1.0 / 2015-05-21
==================

  * add `.format` export
  * add `.parse` export

2.0.2 / 2015-05-20
==================

  * remove map recreation
  * remove unnecessary object construction

2.0.1 / 2015-05-07
==================

  * fix browserify require
  * remove node.extend dependency

2.0.0 / 2015-04-12
==================

  * add option "case"
  * add option "thousandsSeparator"
  * return "null" on invalid parse input
  * support proper round-trip: bytes(bytes(num)) === num
  * units no longer case sensitive when parsing

1.0.0 / 2014-05-05
==================

 * add negative support. fixes #6

0.3.0 / 2014-03-19
==================

 * added terabyte support

0.2.1 / 2013-04-01
==================

  * add .component

0.2.0 / 2012-10-28
==================

  * bytes(200).should.eql('200b')

0.1.0 / 2012-07-04
==================

  * add bytes to string conversion [yields]


---

# Bytes utility

[![NPM Version][npm-image]][npm-url]
[![NPM Downloads][downloads-image]][downloads-url]
[![Build Status][travis-image]][travis-url]
[![Test Coverage][coveralls-image]][coveralls-url]

Utility to parse a string bytes (ex: `1TB`) to bytes (`1099511627776`) and vice-versa.

## Installation

This is a [Node.js](https://nodejs.org/en/) module available through the
[npm registry](https://www.npmjs.com/). Installation is done using the
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):

```bash
$ npm install bytes
```

## Usage

```js
var bytes = require('bytes');
```

#### bytes.format(number value, [options]): string｜null

Format the given value in bytes into a string. If the value is negative, it is kept as such. If it is a float, it is
 rounded.

**Arguments**

| Name    | Type     | Description        |
|---------|----------|--------------------|
| value   | `number` | Value in bytes     |
| options | `Object` | Conversion options |

**Options**

| Property          | Type   | Description                                                                             |
|-------------------|--------|-----------------------------------------------------------------------------------------|
| decimalPlaces | `number`｜`null` | Maximum number of decimal places to include in output. Default value to `2`. |
| fixedDecimals | `boolean`｜`null` | Whether to always display the maximum number of decimal places. Default value to `false` |
| thousandsSeparator | `string`｜`null` | Example of values: `' '`, `','` and `.`... Default value to `''`. |
| unit | `string`｜`null` | The unit in which the result will be returned (B/KB/MB/GB/TB). Default value to `''` (which means auto detect). |
| unitSeparator | `string`｜`null` | Separator to use between number and unit. Default value to `''`. |

**Returns**

| Name    | Type             | Description                                     |
|---------|------------------|-------------------------------------------------|
| results | `string`｜`null` | Return null upon error. String value otherwise. |

**Example**

```js
bytes(1024);
// output: '1KB'

bytes(1000);
// output: '1000B'

bytes(1000, {thousandsSeparator: ' '});
// output: '1 000B'

bytes(1024 * 1.7, {decimalPlaces: 0});
// output: '2KB'

bytes(1024, {unitSeparator: ' '});
// output: '1 KB'

```

#### bytes.parse(string｜number value): number｜null

Parse the string value into an integer in bytes. If no unit is given, or `value`
is a number, it is assumed the value is in bytes.

Supported units and abbreviations are as follows and are case-insensitive:

  * `b` for bytes
  * `kb` for kilobytes
  * `mb` for megabytes
  * `gb` for gigabytes
  * `tb` for terabytes

The units are in powers of two, not ten. This means 1kb = 1024b according to this parser.

**Arguments**

| Name          | Type   | Description        |
|---------------|--------|--------------------|
| value   | `string`｜`number` | String to parse, or number in bytes.   |

**Returns**

| Name    | Type        | Description             |
|---------|-------------|-------------------------|
| results | `number`｜`null` | Return null upon error. Value in bytes otherwise. |

**Example**

```js
bytes('1KB');
// output: 1024

bytes('1024');
// output: 1024

bytes(1024);
// output: 1024
```

## License 

[MIT](LICENSE)

[downloads-image]: https://img.shields.io/npm/dm/bytes.svg
[downloads-url]: https://npmjs.org/package/bytes
[npm-image]: https://img.shields.io/npm/v/bytes.svg
[npm-url]: https://npmjs.org/package/bytes
[travis-image]: https://img.shields.io/travis/visionmedia/bytes.js/master.svg
[travis-url]: https://travis-ci.org/visionmedia/bytes.js
[coveralls-image]: https://img.shields.io/coveralls/visionmedia/bytes.js/master.svg
[coveralls-url]: https://coveralls.io/r/visionmedia/bytes.js?branch=master


---

# cacheable-lookup

> A cacheable [`dns.lookup(…)`](https://nodejs.org/api/dns.html#dns_dns_lookup_hostname_options_callback) that respects TTL :tada:

[![Node CI](https://github.com/szmarczak/cacheable-lookup/workflows/Node%20CI/badge.svg)](https://github.com/szmarczak/cacheable-lookup/actions)
[![codecov](https://codecov.io/gh/szmarczak/cacheable-lookup/branch/master/graph/badge.svg)](https://codecov.io/gh/szmarczak/cacheable-lookup)
[![npm](https://img.shields.io/npm/dm/cacheable-lookup.svg)](https://www.npmjs.com/package/cacheable-lookup)
[![install size](https://packagephobia.now.sh/badge?p=cacheable-lookup)](https://packagephobia.now.sh/result?p=cacheable-lookup)

Making lots of HTTP requests? You can save some time by caching DNS lookups :zap:

## Usage

### Using the `lookup` option

```js
import http from 'node:http';
import CacheableLookup from 'cacheable-lookup';

const cacheable = new CacheableLookup();

http.get('http://example.com', {lookup: cacheable.lookup}, response => {
	// Handle the response here
});
```

### Attaching CacheableLookup to an Agent

```js
import http from 'node:http';
import https from 'node:https';
import CacheableLookup from 'cacheable-lookup';

const cacheable = new CacheableLookup();

cacheable.install(http.globalAgent);
cacheable.install(https.globalAgent);

http.get('http://example.com', response => {
	// Handle the response here
});
```

## API

### new CacheableLookup(options)

Returns a new instance of `CacheableLookup`.

#### options

Type: `object`\
Default: `{}`

Options used to cache the DNS lookups.

##### cache

Type: `Map` | [`Keyv`](https://github.com/lukechilds/keyv/)\
Default: `new Map()`

Custom cache instance. If `undefined`, it will create a new one.

**Note**: If you decide to use Keyv instead of the native implementation, the performance will drop by 10x. Memory leaks may occur as it doesn't provide any way to remove all the deprecated values at once.

**Tip**: [`QuickLRU`](https://github.com/sindresorhus/quick-lru) is fully compatible with the Map API, you can use it to limit the amount of cached entries. Example:

```js
import http from 'node:http';
import CacheableLookup from 'cacheable-lookup';
import QuickLRU from 'quick-lru';

const cacheable = new CacheableLookup({
	cache: new QuickLRU({maxSize: 1000})
});

http.get('http://example.com', {lookup: cacheable.lookup}, response => {
	// Handle the response here
});
```

##### options.maxTtl

Type: `number`\
Default: `Infinity`

The maximum lifetime of the entries received from the specifed DNS server (TTL in seconds).

If set to `0`, it will make a new DNS query each time.

**Pro Tip**: This shouldn't be lower than your DNS server response time in order to prevent bottlenecks. For example, if you use Cloudflare, this value should be greater than `0.01`.

##### options.fallbackDuration

Type: `number`\
Default: `3600` (1 hour)

When the DNS server responds with `ENOTFOUND` or `ENODATA` and the OS reports that the entry is available, it will use `dns.lookup(...)` directly for the requested hostnames for the specified amount of time (in seconds).

**Note**: You should avoid setting this to `0` unless the provided DNS servers' database is limited to few domains.

##### options.errorTtl

Type: `number`\
Default: `0.15`

The time how long it needs to remember queries that threw `ENOTFOUND` or `ENODATA` (TTL in seconds).

**Note**: This option is independent, `options.maxTtl` does not affect this.

**Pro Tip**: This shouldn't be lower than your DNS server response time in order to prevent bottlenecks. For example, if you use Cloudflare, this value should be greater than `0.01`.

##### options.resolver

Type: `dns.Resolver | dns.promises.Resolver`\
Default: [`new dns.promises.Resolver()`](https://nodejs.org/api/dns.html#dns_class_dns_resolver)

An instance of [DNS Resolver](https://nodejs.org/api/dns.html#dns_class_dns_resolver) used to make DNS queries.

##### options.lookup

Type: `Function`\
Default: [`dns.lookup`](https://nodejs.org/api/dns.html#dns_dns_lookup_hostname_options_callback)

The fallback function to use when the DNS server responds with `ENOTFOUND` or `ENODATA`.

If you don't query internal hostnames (such as `localhost`, `database.local` etc.), it is strongly recommended to set this to `false`.

### Entry object

Type: `object`

#### address

Type: `string`

The IP address (can be an IPv4 or IPv6 address).

#### family

Type: `number`

The IP family (`4` or `6`).

##### expires

Type: `number`

**Note**: This is not present when falling back to `dns.lookup(...)`!

The timestamp (`Date.now() + ttl * 1000`) when the entry expires.

#### ttl

**Note**: This is not present when falling back to `dns.lookup(...)`!

The time in seconds for its lifetime.

#### source

**Note**: This is not present when falling back to `dns.lookup(...)`!

Whether this entry was loaded from the cache or came from a query (`cache` or `query`)

### Entry object (callback-style)

When `options.all` is `false`, then `callback(error, address, family, expires, ttl)` is called.\
When `options.all` is `true`, then `callback(error, entries)` is called.

### CacheableLookup instance

#### servers

Type: `Array`

The DNS servers used to make queries. Can be overridden - doing so will clear the cache.

#### [lookup(hostname, options, callback)](https://nodejs.org/api/dns.html#dns_dns_lookup_hostname_options_callback)

#### lookupAsync(hostname, options)

The asynchronous version of `dns.lookup(…)`.

Returns an [entry object](#entry-object).\
If `options.all` is true, returns an array of entry objects.

##### hostname

Type: `string`

##### options

Type: `object`

The same as the [`dns.lookup(…)`](https://nodejs.org/api/dns.html#dns_dns_lookup_hostname_options_callback) options.

#### query(hostname)

An asynchronous function which returns cached DNS lookup entries.\
This is the base for `lookupAsync(hostname, options)` and `lookup(hostname, options, callback)`.

**Note**: This function has no options.

Returns an array of objects with `address`, `family`, `ttl` and `expires` properties.

#### queryAndCache(hostname)

An asynchronous function which makes two DNS queries: A and AAAA. The result is cached.\
This is used by `query(hostname)` if no entry in the database is present.

Returns an array of objects with `address`, `family`, `ttl` and `expires` properties.

#### updateInterfaceInfo()

Updates interface info. For example, you need to run this when you plug or unplug your WiFi driver.

**Note:** Running `updateInterfaceInfo()` will trigger `clear()` only on network interface removal.

#### clear(hostname?)

Clears the cache for the given hostname. If the hostname argument is not present, the entire cache will be emptied.

## High performance

Performed on:
- Query: `example.com`
- CPU: i7-7700k
- CPU governor: performance

```
CacheableLookup#lookupAsync                x 2,896,251 ops/sec ±1.07% (85 runs sampled)
CacheableLookup#lookupAsync.all            x 2,842,664 ops/sec ±1.11% (88 runs sampled)
CacheableLookup#lookupAsync.all.ADDRCONFIG x 2,598,283 ops/sec ±1.21% (88 runs sampled)
CacheableLookup#lookup                     x 2,565,913 ops/sec ±1.56% (85 runs sampled)
CacheableLookup#lookup.all                 x 2,609,039 ops/sec ±1.01% (86 runs sampled)
CacheableLookup#lookup.all.ADDRCONFIG      x 2,416,242 ops/sec ±0.89% (85 runs sampled)
dns#lookup                                 x 7,272     ops/sec ±0.36% (86 runs sampled)
dns#lookup.all                             x 7,249     ops/sec ±0.40% (86 runs sampled)
dns#lookup.all.ADDRCONFIG                  x 5,693     ops/sec ±0.28% (85 runs sampled)
Fastest is CacheableLookup#lookupAsync.all
```

## Related

- [cacheable-request](https://github.com/lukechilds/cacheable-request) - Wrap native HTTP requests with RFC compliant cache support


---

<h1 align="center"><br><img width="380" src="https://cacheable.org/assets/images/cacheable_symbol.svg" alt="cacheable logo"><br><br></h1>

# cacheable-request

> Wrap native HTTP requests with RFC compliant cache support

[![tests](https://github.com/jaredwray/cacheable/actions/workflows/tests.yaml/badge.svg)](https://github.com/jaredwray/cacheable/actions/workflows/tests.yaml)
[![codecov](https://codecov.io/gh/jaredwray/cacheable/branch/master/graph/badge.svg?token=LDLaqe4PsI)](https://codecov.io/gh/jaredwray/cacheable)
[![npm](https://img.shields.io/npm/dm/cacheable-request.svg)](https://www.npmjs.com/package/cacheable-request)
[![npm](https://img.shields.io/npm/v/cacheable-request.svg)](https://www.npmjs.com/package/cacheable-request)

[RFC 7234](http://httpwg.org/specs/rfc7234.html) compliant HTTP caching for native Node.js HTTP/HTTPS requests. Caching works out of the box in memory or is easily pluggable with a wide range of storage adapters.

**Note:** This is a low level wrapper around the core HTTP modules, it's not a high level request library.

# Table of Contents
* [Latest Changes](#latest-changes)
* [Features](#features)
* [Install and Usage](#install-and-usage)
* [Storage Adapters](#storage-adapters)
* [API](#api)
* [Using Hooks](#using-hooks)
* [Contributing](#contributing)
* [Ask a Question](#ask-a-question)
* [License](#license) (MIT)

# Latest Changes

## Breaking Changes with v10.0.0
This release contains breaking changes. This is the new way to use this package.

### Usage Before v10
```js
import http from 'http';
import CacheableRequest from 'cacheable-request';

// Then instead of
const req = http.request('http://example.com', cb);
req.end();

// You can do
const cacheableRequest = new CacheableRequest(http.request);
const cacheReq = cacheableRequest('http://example.com', cb);
cacheReq.on('request', req => req.end());
// Future requests to 'example.com' will be returned from cache if still valid

// You pass in any other http.request API compatible method to be wrapped with cache support:
const cacheableRequest = new CacheableRequest(https.request);
const cacheableRequest = new CacheableRequest(electron.net);
```

### Usage After v10.1.0
```js

import CacheableRequest from 'cacheable-request';

// Now You can do
const cacheableRequest = new CacheableRequest(http.request).request();
const cacheReq = cacheableRequest('http://example.com', cb);
cacheReq.on('request', req => req.end());
// Future requests to 'example.com' will be returned from cache if still valid

// You pass in any other http.request API compatible method to be wrapped with cache support:
const cacheableRequest = new CacheableRequest(https.request).request();
const cacheableRequest = new CacheableRequest(electron.net).request();
```

The biggest change is that when you do a `new` CacheableRequest you now want to call `request` method will give you the instance to use. 

```diff
- const cacheableRequest = new CacheableRequest(http.request);
+ const cacheableRequest = new CacheableRequest(http.request).request();
```

### ESM Support in version 9 and higher. 

We are now using pure esm support in our package. If you need to use commonjs you can use v8 or lower. To learn more about using ESM please read this from `sindresorhus`: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

## Features

- Only stores cacheable responses as defined by RFC 7234
- Fresh cache entries are served directly from cache
- Stale cache entries are revalidated with `If-None-Match`/`If-Modified-Since` headers
- 304 responses from revalidation requests use cached body
- Updates `Age` header on cached responses
- Can completely bypass cache on a per request basis
- In memory cache by default
- Official support for Redis, Memcache, Etcd, MongoDB, SQLite, PostgreSQL and MySQL storage adapters
- Easily plug in your own or third-party storage adapters
- If DB connection fails, cache is automatically bypassed ([disabled by default](#optsautomaticfailover))
- Adds cache support to any existing HTTP code with minimal changes
- Uses [http-cache-semantics](https://github.com/pornel/http-cache-semantics) internally for HTTP RFC 7234 compliance

## Install and Usage

```shell
npm install cacheable-request
```

```js
import http from 'http';
import CacheableRequest from 'cacheable-request';

// Then instead of
const req = http.request('http://example.com', cb);
req.end();

// You can do
const cacheableRequest = new CacheableRequest(http.request).createCacheableRequest();
const cacheReq = cacheableRequest('http://example.com', cb);
cacheReq.on('request', req => req.end());
// Future requests to 'example.com' will be returned from cache if still valid

// You pass in any other http.request API compatible method to be wrapped with cache support:
const cacheableRequest = new CacheableRequest(https.request).createCacheableRequest();
const cacheableRequest = new CacheableRequest(electron.net).createCacheableRequest();
```

## Storage Adapters

`cacheable-request` uses [Keyv](https://github.com/jaredwray/keyv) to support a wide range of storage adapters.

For example, to use Redis as a cache backend, you just need to install the official Redis Keyv storage adapter:

```
npm install @keyv/redis
```

And then you can pass `CacheableRequest` your connection string:

```js
const cacheableRequest = new CacheableRequest(http.request, 'redis://user:pass@localhost:6379').createCacheableRequest();
```

[View all official Keyv storage adapters.](https://github.com/jaredwray/keyv#official-storage-adapters)

Keyv also supports anything that follows the Map API so it's easy to write your own storage adapter or use a third-party solution.

e.g The following are all valid storage adapters

```js
const storageAdapter = new Map();
// or
const storageAdapter = require('./my-storage-adapter');
// or
const QuickLRU = require('quick-lru');
const storageAdapter = new QuickLRU({ maxSize: 1000 });

const cacheableRequest = new CacheableRequest(http.request, storageAdapter).createCacheableRequest();
```

View the [Keyv docs](https://github.com/jaredwray/keyv) for more information on how to use storage adapters.

## API

### new cacheableRequest(request, [storageAdapter])

Returns the provided request function wrapped with cache support.

#### request

Type: `function`

Request function to wrap with cache support. Should be [`http.request`](https://nodejs.org/api/http.html#http_http_request_options_callback) or a similar API compatible request function.

#### storageAdapter

Type: `Keyv storage adapter`<br>
Default: `new Map()`

A [Keyv](https://github.com/jaredwray/keyv) storage adapter instance, or connection string if using with an official Keyv storage adapter.

### Instance

#### cacheableRequest(opts, [cb])

Returns an event emitter.

##### opts

Type: `object`, `string`

- Any of the default request functions options.
- Any [`http-cache-semantics`](https://github.com/kornelski/http-cache-semantics#constructor-options) options.
- Any of the following:

###### opts.cache

Type: `boolean`<br>
Default: `true`

If the cache should be used. Setting this to false will completely bypass the cache for the current request.

###### opts.strictTtl

Type: `boolean`<br>
Default: `false`

If set to `true` once a cached resource has expired it is deleted and will have to be re-requested.

If set to `false` (default), after a cached resource's TTL expires it is kept in the cache and will be revalidated on the next request with `If-None-Match`/`If-Modified-Since` headers.

###### opts.maxTtl

Type: `number`<br>
Default: `undefined`

Limits TTL. The `number` represents milliseconds.

###### opts.automaticFailover

Type: `boolean`<br>
Default: `false`

When set to `true`, if the DB connection fails we will automatically fallback to a network request. DB errors will still be emitted to notify you of the problem even though the request callback may succeed.

###### opts.forceRefresh

Type: `boolean`<br>
Default: `false`

Forces refreshing the cache. If the response could be retrieved from the cache, it will perform a new request and override the cache instead.

##### cb

Type: `function`

The callback function which will receive the response as an argument.

The response can be either a [Node.js HTTP response stream](https://nodejs.org/api/http.html#http_class_http_incomingmessage) or a [responselike object](https://github.com/lukechilds/responselike). The response will also have a `fromCache` property set with a boolean value.

##### .on('request', request)

`request` event to get the request object of the request.

**Note:** This event will only fire if an HTTP request is actually made, not when a response is retrieved from cache. However, you should always handle the `request` event to end the request and handle any potential request errors.

##### .on('response', response)

`response` event to get the response object from the HTTP request or cache.

##### .on('error', error)

`error` event emitted in case of an error with the cache.

Errors emitted here will be an instance of `CacheableRequest.RequestError` or `CacheableRequest.CacheError`. You will only ever receive a `RequestError` if the request function throws (normally caused by invalid user input). Normal request errors should be handled inside the `request` event.

To properly handle all error scenarios you should use the following pattern:

```js
cacheableRequest('example.com', cb)
  .on('error', err => {
    if (err instanceof CacheableRequest.CacheError) {
      handleCacheError(err); // Cache error
    } else if (err instanceof CacheableRequest.RequestError) {
      handleRequestError(err); // Request function thrown
    }
  })
  .on('request', req => {
    req.on('error', handleRequestError); // Request error emitted
    req.end();
  });
```
**Note:** Database connection errors are emitted here, however `cacheable-request` will attempt to re-request the resource and bypass the cache on a connection error. Therefore a database connection error doesn't necessarily mean the request won't be fulfilled.


## Using Hooks
Hooks have been implemented since version `v9` and are very useful to modify response before saving it in cache. You can use hooks to modify response before saving it in cache.

### Add Hooks

The hook will pre compute response right before saving it in cache. You can include many hooks and it will run in order you add hook on response object.

```js
import http from 'http';
import CacheableRequest from 'cacheable-request';

const cacheableRequest = new CacheableRequest(request, cache).request();

// adding a hook to decompress response
cacheableRequest.addHook('onResponse', async (value: CacheValue, response: any) => {
  const buffer = await pm(gunzip)(value.body);
  value.body = buffer.toString();
  return value;
});
```

here is also an example of how to add in the remote address

```js
import CacheableRequest, {CacheValue} from 'cacheable-request';

const cacheableRequest = new CacheableRequest(request, cache).request();
cacheableRequest.addHook('onResponse', (value: CacheValue, response: any) => {
  if (response.connection) {
    value.remoteAddress = response.connection.remoteAddress;
  }

  return value;
});
```

### Remove Hooks

You can also remove hook by using below

```js
CacheableRequest.removeHook('onResponse');
```

## How to Contribute

Cacheable-Request is an open source package and community driven that is maintained regularly. In addtion we have a couple of other guidelines for review:

* [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) - Our code of conduct
* [CONTRIBUTING.md](CONTRIBUTING.md) - How to contribute to this project
* [SECURITY.md](SECURITY.md) - Security guidelines and supported versions 

## Post an Issue

To post an issue, navigate to the "Issues" tab in the main repository, and then select "New Issue." Enter a clear title describing the issue, as well as a description containing additional relevant information. Also select the label that best describes your issue type. For a bug report, for example, create an issue with the label "bug." In the description field, Be sure to include replication steps, as well as any relevant error messages.

If you're reporting a security violation, be sure to check out the project's [security policy](SECURITY.md).

Please also refer to our [Code of Conduct](CODE_OF_CONDUCT.md) for more information on how to report issues.

## Ask a Question

To ask a question, create an issue with the label "question." In the issue description, include the related code and any context that can help us answer your question.

## License

This project is under the [MIT](LICENSE) license. 

MIT © Luke Childs 2017-2021 and Jared Wray 2022+


---

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [v1.0.8](https://github.com/ljharb/call-bind/compare/v1.0.7...v1.0.8) - 2024-12-05

### Commits

- [Refactor] extract out some helpers and avoid get-intrinsic usage [`407fd5e`](https://github.com/ljharb/call-bind/commit/407fd5eec34ec58394522a6ce3badfa4788fd5ae)
- [Refactor] replace code with extracted `call-bind-apply-helpers` [`81018fb`](https://github.com/ljharb/call-bind/commit/81018fb78902ff5acbc6c09300780e97f0db6a34)
- [Tests] use `set-function-length/env` [`0fc311d`](https://github.com/ljharb/call-bind/commit/0fc311de0e115cfa6b02969b23a42ad45aadf224)
- [actions] split out node 10-20, and 20+ [`77a0cad`](https://github.com/ljharb/call-bind/commit/77a0cad75f83f5b8050dc13baef4fa2cff537fa3)
- [Dev Deps] update `@ljharb/eslint-config`, `auto-changelog`, `es-value-fixtures`, `gopd`, `object-inspect`, `tape` [`a145d10`](https://github.com/ljharb/call-bind/commit/a145d10fe847f350e11094f8541848b028ee8c91)
- [Tests] replace `aud` with `npm audit` [`30ca3dd`](https://github.com/ljharb/call-bind/commit/30ca3dd7234648eb029947477d06b17879e10727)
- [Deps] update `set-function-length` [`57c79a3`](https://github.com/ljharb/call-bind/commit/57c79a3666022ea797cc2a4a3b43fe089bc97d1b)
- [Dev Deps] add missing peer dep [`601cfa5`](https://github.com/ljharb/call-bind/commit/601cfa5540066b6206039ceb9496cecbd134ff7b)

## [v1.0.7](https://github.com/ljharb/call-bind/compare/v1.0.6...v1.0.7) - 2024-02-12

### Commits

- [Refactor] use `es-define-property` [`09b76a0`](https://github.com/ljharb/call-bind/commit/09b76a01634440461d44a80c9924ec4b500f3b03)
- [Deps] update `get-intrinsic`, `set-function-length` [`ad5136d`](https://github.com/ljharb/call-bind/commit/ad5136ddda2a45c590959829ad3dce0c9f4e3590)

## [v1.0.6](https://github.com/ljharb/call-bind/compare/v1.0.5...v1.0.6) - 2024-02-05

### Commits

- [Dev Deps] update `aud`, `npmignore`, `tape` [`d564d5c`](https://github.com/ljharb/call-bind/commit/d564d5ce3e06a19df4d499c77f8d1a9da44e77aa)
- [Deps] update `get-intrinsic`, `set-function-length` [`cfc2bdc`](https://github.com/ljharb/call-bind/commit/cfc2bdca7b633df0e0e689e6b637f668f1c6792e)
- [Refactor] use `es-errors`, so things that only need those do not need `get-intrinsic` [`64cd289`](https://github.com/ljharb/call-bind/commit/64cd289ae5862c250a4ca80aa8d461047c166af5)
- [meta] add missing `engines.node` [`32a4038`](https://github.com/ljharb/call-bind/commit/32a4038857b62179f7f9b7b3df2c5260036be582)

## [v1.0.5](https://github.com/ljharb/call-bind/compare/v1.0.4...v1.0.5) - 2023-10-19

### Commits

- [Fix] throw an error on non-functions as early as possible [`f262408`](https://github.com/ljharb/call-bind/commit/f262408f822c840fbc268080f3ad7c429611066d)
- [Deps] update `set-function-length` [`3fff271`](https://github.com/ljharb/call-bind/commit/3fff27145a1e3a76a5b74f1d7c3c43d0fa3b9871)

## [v1.0.4](https://github.com/ljharb/call-bind/compare/v1.0.3...v1.0.4) - 2023-10-19

## [v1.0.3](https://github.com/ljharb/call-bind/compare/v1.0.2...v1.0.3) - 2023-10-19

### Commits

- [actions] reuse common workflows [`a994df6`](https://github.com/ljharb/call-bind/commit/a994df69f401f4bf735a4ccd77029b85d1549453)
- [meta] use `npmignore` to autogenerate an npmignore file [`eef3ef2`](https://github.com/ljharb/call-bind/commit/eef3ef21e1f002790837fedb8af2679c761fbdf5)
- [readme] flesh out content [`1845ccf`](https://github.com/ljharb/call-bind/commit/1845ccfd9976a607884cfc7157c93192cc16cf22)
- [actions] use `node/install` instead of `node/run`; use `codecov` action [`5b47d53`](https://github.com/ljharb/call-bind/commit/5b47d53d2fd74af5ea0a44f1d51e503cd42f7a90)
- [Refactor] use `set-function-length` [`a0e165c`](https://github.com/ljharb/call-bind/commit/a0e165c5dc61db781cbc919b586b1c2b8da0b150)
- [Dev Deps] update `@ljharb/eslint-config`, `aud`, `tape` [`9c50103`](https://github.com/ljharb/call-bind/commit/9c50103f44137279a817317cf6cc421a658f85b4)
- [meta] simplify "exports" [`019c6d0`](https://github.com/ljharb/call-bind/commit/019c6d06b0e1246ceed8e579f57e44441cbbf6d9)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `aud`, `auto-changelog`, `safe-publish-latest`, `tape` [`23bd718`](https://github.com/ljharb/call-bind/commit/23bd718a288d3b03042062b4ef5153b3cea83f11)
- [actions] update codecov uploader [`62552d7`](https://github.com/ljharb/call-bind/commit/62552d79cc79e05825e99aaba134ae5b37f33da5)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `aud`, `auto-changelog`, `tape` [`ec81665`](https://github.com/ljharb/call-bind/commit/ec81665b300f87eabff597afdc8b8092adfa7afd)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `safe-publish-latest`, `tape` [`35d67fc`](https://github.com/ljharb/call-bind/commit/35d67fcea883e686650f736f61da5ddca2592de8)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `aud`, `tape` [`0266d8d`](https://github.com/ljharb/call-bind/commit/0266d8d2a45086a922db366d0c2932fa463662ff)
- [Dev Deps] update `@ljharb/eslint-config`, `aud`, `tape` [`43a5b28`](https://github.com/ljharb/call-bind/commit/43a5b28a444e710e1bbf92adb8afb5cf7523a223)
- [Deps] update `define-data-property`, `function-bind`, `get-intrinsic` [`780eb36`](https://github.com/ljharb/call-bind/commit/780eb36552514f8cc99c70821ce698697c2726a5)
- [Dev Deps] update `aud`, `tape` [`90d50ad`](https://github.com/ljharb/call-bind/commit/90d50ad03b061e0268b3380b0065fcaec183dc05)
- [meta] use `prepublishOnly` script for npm 7+ [`44c5433`](https://github.com/ljharb/call-bind/commit/44c5433b7980e02b4870007046407cf6fc543329)
- [Deps] update `get-intrinsic` [`86bfbfc`](https://github.com/ljharb/call-bind/commit/86bfbfcf34afdc6eabc93ce3d408548d0e27d958)
- [Deps] update `get-intrinsic` [`5c53354`](https://github.com/ljharb/call-bind/commit/5c5335489be0294c18cd7a8bb6e08226ee019ff5)
- [actions] update checkout action [`4c393a8`](https://github.com/ljharb/call-bind/commit/4c393a8173b3c8e5b30d5b3297b3b94d48bf87f3)
- [Deps] update `get-intrinsic` [`4e70bde`](https://github.com/ljharb/call-bind/commit/4e70bdec0626acb11616d66250fc14565e716e91)
- [Deps] update `get-intrinsic` [`55ae803`](https://github.com/ljharb/call-bind/commit/55ae803a920bd93c369cd798c20de31f91e9fc60)

## [v1.0.2](https://github.com/ljharb/call-bind/compare/v1.0.1...v1.0.2) - 2021-01-11

### Commits

- [Fix] properly include the receiver in the bound length [`dbae7bc`](https://github.com/ljharb/call-bind/commit/dbae7bc676c079a0d33c0a43e9ef92cb7b01345d)

## [v1.0.1](https://github.com/ljharb/call-bind/compare/v1.0.0...v1.0.1) - 2021-01-08

### Commits

- [Tests] migrate tests to Github Actions [`b6db284`](https://github.com/ljharb/call-bind/commit/b6db284c36f8ccd195b88a6764fe84b7223a0da1)
- [meta] do not publish github action workflow files [`ec7fe46`](https://github.com/ljharb/call-bind/commit/ec7fe46e60cfa4764ee943d2755f5e5a366e578e)
- [Fix] preserve original function’s length when possible [`adbceaa`](https://github.com/ljharb/call-bind/commit/adbceaa3cac4b41ea78bb19d7ccdbaaf7e0bdadb)
- [Tests] gather coverage data on every job [`d69e23c`](https://github.com/ljharb/call-bind/commit/d69e23cc65f101ba1d4c19bb07fa8eb0ec624be8)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `aud`, `tape` [`2fd3586`](https://github.com/ljharb/call-bind/commit/2fd3586c5d47b335364c14293114c6b625ae1f71)
- [Deps] update `get-intrinsic` [`f23e931`](https://github.com/ljharb/call-bind/commit/f23e9318cc271c2add8bb38cfded85ee7baf8eee)
- [Deps] update `get-intrinsic` [`72d9f44`](https://github.com/ljharb/call-bind/commit/72d9f44e184465ba8dd3fb48260bbcff234985f2)
- [meta] fix FUNDING.yml [`e723573`](https://github.com/ljharb/call-bind/commit/e723573438c5a68dcec31fb5d96ea6b7e4a93be8)
- [eslint] ignore coverage output [`15e76d2`](https://github.com/ljharb/call-bind/commit/15e76d28a5f43e504696401e5b31ebb78ee1b532)
- [meta] add Automatic Rebase and Require Allow Edits workflows [`8fa4dab`](https://github.com/ljharb/call-bind/commit/8fa4dabb23ba3dd7bb92c9571c1241c08b56e4b6)

## v1.0.0 - 2020-10-30

### Commits

- Initial commit [`306cf98`](https://github.com/ljharb/call-bind/commit/306cf98c7ec9e7ef66b653ec152277ac1381eb50)
- Tests [`e10d0bb`](https://github.com/ljharb/call-bind/commit/e10d0bbdadc7a10ecedc9a1c035112d3e368b8df)
- Implementation [`43852ed`](https://github.com/ljharb/call-bind/commit/43852eda0f187327b7fad2423ca972149a52bd65)
- npm init [`408f860`](https://github.com/ljharb/call-bind/commit/408f860b773a2f610805fd3613d0d71bac1b6249)
- [meta] add Automatic Rebase and Require Allow Edits workflows [`fb349b2`](https://github.com/ljharb/call-bind/commit/fb349b2e48defbec8b5ec8a8395cc8f69f220b13)
- [meta] add `auto-changelog` [`c4001fc`](https://github.com/ljharb/call-bind/commit/c4001fc43031799ef908211c98d3b0fb2b60fde4)
- [meta] add "funding"; create `FUNDING.yml` [`d4d6d29`](https://github.com/ljharb/call-bind/commit/d4d6d2974a14bc2e98830468eda7fe6d6a776717)
- [Tests] add `npm run lint` [`dedfb98`](https://github.com/ljharb/call-bind/commit/dedfb98bd0ecefb08ddb9a94061bd10cde4332af)
- Only apps should have lockfiles [`54ac776`](https://github.com/ljharb/call-bind/commit/54ac77653db45a7361dc153d2f478e743f110650)
- [meta] add `safe-publish-latest` [`9ea8e43`](https://github.com/ljharb/call-bind/commit/9ea8e435b950ce9b705559cd651039f9bf40140f)


---

# call-bind <sup>[![Version Badge][npm-version-svg]][package-url]</sup>

[![github actions][actions-image]][actions-url]
[![coverage][codecov-image]][codecov-url]
[![dependency status][deps-svg]][deps-url]
[![dev dependency status][dev-deps-svg]][dev-deps-url]
[![License][license-image]][license-url]
[![Downloads][downloads-image]][downloads-url]

[![npm badge][npm-badge-png]][package-url]

Robustly `.call.bind()` a function.

## Getting started

```sh
npm install --save call-bind
```

## Usage/Examples

```js
const assert = require('assert');
const callBind = require('call-bind');
const callBound = require('call-bind/callBound');

function f(a, b) {
	assert.equal(this, 1);
	assert.equal(a, 2);
	assert.equal(b, 3);
	assert.equal(arguments.length, 2);
}

const fBound = callBind(f);

const slice = callBound('Array.prototype.slice');

delete Function.prototype.call;
delete Function.prototype.bind;

fBound(1, 2, 3);

assert.deepEqual(slice([1, 2, 3, 4], 1, -1), [2, 3]);
```

## Tests

Clone the repo, `npm install`, and run `npm test`

[package-url]: https://npmjs.org/package/call-bind
[npm-version-svg]: https://versionbadg.es/ljharb/call-bind.svg
[deps-svg]: https://david-dm.org/ljharb/call-bind.svg
[deps-url]: https://david-dm.org/ljharb/call-bind
[dev-deps-svg]: https://david-dm.org/ljharb/call-bind/dev-status.svg
[dev-deps-url]: https://david-dm.org/ljharb/call-bind#info=devDependencies
[npm-badge-png]: https://nodei.co/npm/call-bind.png?downloads=true&stars=true
[license-image]: https://img.shields.io/npm/l/call-bind.svg
[license-url]: LICENSE
[downloads-image]: https://img.shields.io/npm/dm/call-bind.svg
[downloads-url]: https://npm-stat.com/charts.html?package=call-bind
[codecov-image]: https://codecov.io/gh/ljharb/call-bind/branch/main/graphs/badge.svg
[codecov-url]: https://app.codecov.io/gh/ljharb/call-bind/
[actions-image]: https://img.shields.io/endpoint?url=https://github-actions-badge-u3jn4tfpocch.runkit.sh/ljharb/call-bind
[actions-url]: https://github.com/ljharb/call-bind/actions


---

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [v1.0.2](https://github.com/ljharb/call-bind-apply-helpers/compare/v1.0.1...v1.0.2) - 2025-02-12

### Commits

- [types] improve inferred types [`e6f9586`](https://github.com/ljharb/call-bind-apply-helpers/commit/e6f95860a3c72879cb861a858cdfb8138fbedec1)
- [Dev Deps] update `@arethetypeswrong/cli`, `@ljharb/tsconfig`, `@types/tape`, `es-value-fixtures`, `for-each`, `has-strict-mode`, `object-inspect` [`e43d540`](https://github.com/ljharb/call-bind-apply-helpers/commit/e43d5409f97543bfbb11f345d47d8ce4e066d8c1)

## [v1.0.1](https://github.com/ljharb/call-bind-apply-helpers/compare/v1.0.0...v1.0.1) - 2024-12-08

### Commits

- [types] `reflectApply`: fix types [`4efc396`](https://github.com/ljharb/call-bind-apply-helpers/commit/4efc3965351a4f02cc55e836fa391d3d11ef2ef8)
- [Fix] `reflectApply`: oops, Reflect is not a function [`83cc739`](https://github.com/ljharb/call-bind-apply-helpers/commit/83cc7395de6b79b7730bdf092f1436f0b1263c75)
- [Dev Deps] update `@arethetypeswrong/cli` [`80bd5d3`](https://github.com/ljharb/call-bind-apply-helpers/commit/80bd5d3ae58b4f6b6995ce439dd5a1bcb178a940)

## v1.0.0 - 2024-12-05

### Commits

- Initial implementation, tests, readme [`7879629`](https://github.com/ljharb/call-bind-apply-helpers/commit/78796290f9b7430c9934d6f33d94ae9bc89fce04)
- Initial commit [`3f1dc16`](https://github.com/ljharb/call-bind-apply-helpers/commit/3f1dc164afc43285631b114a5f9dd9137b2b952f)
- npm init [`081df04`](https://github.com/ljharb/call-bind-apply-helpers/commit/081df048c312fcee400922026f6e97281200a603)
- Only apps should have lockfiles [`5b9ca0f`](https://github.com/ljharb/call-bind-apply-helpers/commit/5b9ca0fe8101ebfaf309c549caac4e0a017ed930)


---

# call-bind-apply-helpers <sup>[![Version Badge][npm-version-svg]][package-url]</sup>

[![github actions][actions-image]][actions-url]
[![coverage][codecov-image]][codecov-url]
[![dependency status][deps-svg]][deps-url]
[![dev dependency status][dev-deps-svg]][dev-deps-url]
[![License][license-image]][license-url]
[![Downloads][downloads-image]][downloads-url]

[![npm badge][npm-badge-png]][package-url]

Helper functions around Function call/apply/bind, for use in `call-bind`.

The only packages that should likely ever use this package directly are `call-bind` and `get-intrinsic`.
Please use `call-bind` unless you have a very good reason not to.

## Getting started

```sh
npm install --save call-bind-apply-helpers
```

## Usage/Examples

```js
const assert = require('assert');
const callBindBasic = require('call-bind-apply-helpers');

function f(a, b) {
	assert.equal(this, 1);
	assert.equal(a, 2);
	assert.equal(b, 3);
	assert.equal(arguments.length, 2);
}

const fBound = callBindBasic([f, 1]);

delete Function.prototype.call;
delete Function.prototype.bind;

fBound(2, 3);
```

## Tests

Clone the repo, `npm install`, and run `npm test`

[package-url]: https://npmjs.org/package/call-bind-apply-helpers
[npm-version-svg]: https://versionbadg.es/ljharb/call-bind-apply-helpers.svg
[deps-svg]: https://david-dm.org/ljharb/call-bind-apply-helpers.svg
[deps-url]: https://david-dm.org/ljharb/call-bind-apply-helpers
[dev-deps-svg]: https://david-dm.org/ljharb/call-bind-apply-helpers/dev-status.svg
[dev-deps-url]: https://david-dm.org/ljharb/call-bind-apply-helpers#info=devDependencies
[npm-badge-png]: https://nodei.co/npm/call-bind-apply-helpers.png?downloads=true&stars=true
[license-image]: https://img.shields.io/npm/l/call-bind-apply-helpers.svg
[license-url]: LICENSE
[downloads-image]: https://img.shields.io/npm/dm/call-bind-apply-helpers.svg
[downloads-url]: https://npm-stat.com/charts.html?package=call-bind-apply-helpers
[codecov-image]: https://codecov.io/gh/ljharb/call-bind-apply-helpers/branch/main/graphs/badge.svg
[codecov-url]: https://app.codecov.io/gh/ljharb/call-bind-apply-helpers/
[actions-image]: https://img.shields.io/endpoint?url=https://github-actions-badge-u3jn4tfpocch.runkit.sh/ljharb/call-bind-apply-helpers
[actions-url]: https://github.com/ljharb/call-bind-apply-helpers/actions


---

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [v1.0.4](https://github.com/ljharb/call-bound/compare/v1.0.3...v1.0.4) - 2025-03-03

### Commits

- [types] improve types [`e648922`](https://github.com/ljharb/call-bound/commit/e6489222a9e54f350fbf952ceabe51fd8b6027ff)
- [Dev Deps] update `@arethetypeswrong/cli`, `@ljharb/tsconfig`, `@types/tape`, `es-value-fixtures`, `for-each`, `has-strict-mode`, `object-inspect` [`a42a5eb`](https://github.com/ljharb/call-bound/commit/a42a5ebe6c1b54fcdc7997c7dc64fdca9e936719)
- [Deps] update `call-bind-apply-helpers`, `get-intrinsic` [`f529eac`](https://github.com/ljharb/call-bound/commit/f529eac132404c17156bbc23ab2297a25d0f20b8)

## [v1.0.3](https://github.com/ljharb/call-bound/compare/v1.0.2...v1.0.3) - 2024-12-15

### Commits

- [Refactor] use `call-bind-apply-helpers` instead of `call-bind` [`5e0b134`](https://github.com/ljharb/call-bound/commit/5e0b13496df14fb7d05dae9412f088da8d3f75be)
- [Deps] update `get-intrinsic` [`41fc967`](https://github.com/ljharb/call-bound/commit/41fc96732a22c7b7e8f381f93ccc54bb6293be2e)
- [readme] fix example [`79a0137`](https://github.com/ljharb/call-bound/commit/79a0137723f7c6d09c9c05452bbf8d5efb5d6e49)
- [meta] add `sideEffects` flag [`08b07be`](https://github.com/ljharb/call-bound/commit/08b07be7f1c03f67dc6f3cdaf0906259771859f7)

## [v1.0.2](https://github.com/ljharb/call-bound/compare/v1.0.1...v1.0.2) - 2024-12-10

### Commits

- [Dev Deps] update `@arethetypeswrong/cli`, `@ljharb/tsconfig`, `gopd` [`e6a5ffe`](https://github.com/ljharb/call-bound/commit/e6a5ffe849368fe4f74dfd6cdeca1b9baa39e8d5)
- [Deps] update `call-bind`, `get-intrinsic` [`2aeb5b5`](https://github.com/ljharb/call-bound/commit/2aeb5b521dc2b2683d1345c753ea1161de2d1c14)
- [types] improve return type [`1a0c9fe`](https://github.com/ljharb/call-bound/commit/1a0c9fe3114471e7ca1f57d104e2efe713bb4871)

## v1.0.1 - 2024-12-05

### Commits

- Initial implementation, tests, readme, types [`6d94121`](https://github.com/ljharb/call-bound/commit/6d94121a9243602e506334069f7a03189fe3363d)
- Initial commit [`0eae867`](https://github.com/ljharb/call-bound/commit/0eae867334ea025c33e6e91cdecfc9df96680cf9)
- npm init [`71b2479`](https://github.com/ljharb/call-bound/commit/71b2479c6723e0b7d91a6b663613067e98b7b275)
- Only apps should have lockfiles [`c3754a9`](https://github.com/ljharb/call-bound/commit/c3754a949b7f9132b47e2d18c1729889736741eb)
- [actions] skip `npm ls` in node &lt; 10 [`74275a5`](https://github.com/ljharb/call-bound/commit/74275a5186b8caf6309b6b97472bdcb0df4683a8)
- [Dev Deps] add missing peer dep [`1354de8`](https://github.com/ljharb/call-bound/commit/1354de8679413e4ae9c523d85f76fa7a5e032d97)


---

# call-bound <sup>[![Version Badge][npm-version-svg]][package-url]</sup>

[![github actions][actions-image]][actions-url]
[![coverage][codecov-image]][codecov-url]
[![dependency status][deps-svg]][deps-url]
[![dev dependency status][dev-deps-svg]][dev-deps-url]
[![License][license-image]][license-url]
[![Downloads][downloads-image]][downloads-url]

[![npm badge][npm-badge-png]][package-url]

Robust call-bound JavaScript intrinsics, using `call-bind` and `get-intrinsic`.

## Getting started

```sh
npm install --save call-bound
```

## Usage/Examples

```js
const assert = require('assert');
const callBound = require('call-bound');

const slice = callBound('Array.prototype.slice');

delete Function.prototype.call;
delete Function.prototype.bind;
delete Array.prototype.slice;

assert.deepEqual(slice([1, 2, 3, 4], 1, -1), [2, 3]);
```

## Tests

Clone the repo, `npm install`, and run `npm test`

[package-url]: https://npmjs.org/package/call-bound
[npm-version-svg]: https://versionbadg.es/ljharb/call-bound.svg
[deps-svg]: https://david-dm.org/ljharb/call-bound.svg
[deps-url]: https://david-dm.org/ljharb/call-bound
[dev-deps-svg]: https://david-dm.org/ljharb/call-bound/dev-status.svg
[dev-deps-url]: https://david-dm.org/ljharb/call-bound#info=devDependencies
[npm-badge-png]: https://nodei.co/npm/call-bound.png?downloads=true&stars=true
[license-image]: https://img.shields.io/npm/l/call-bound.svg
[license-url]: LICENSE
[downloads-image]: https://img.shields.io/npm/dm/call-bound.svg
[downloads-url]: https://npm-stat.com/charts.html?package=call-bound
[codecov-image]: https://codecov.io/gh/ljharb/call-bound/branch/main/graphs/badge.svg
[codecov-url]: https://app.codecov.io/gh/ljharb/call-bound/
[actions-image]: https://img.shields.io/endpoint?url=https://github-actions-badge-u3jn4tfpocch.runkit.sh/ljharb/call-bound
[actions-url]: https://github.com/ljharb/call-bound/actions


---

# callsites [![Build Status](https://travis-ci.org/sindresorhus/callsites.svg?branch=master)](https://travis-ci.org/sindresorhus/callsites)

> Get callsites from the [V8 stack trace API](https://v8.dev/docs/stack-trace-api)


## Install

```
$ npm install callsites
```


## Usage

```js
const callsites = require('callsites');

function unicorn() {
	console.log(callsites()[0].getFileName());
	//=> '/Users/sindresorhus/dev/callsites/test.js'
}

unicorn();
```


## API

Returns an array of callsite objects with the following methods:

- `getThis`: returns the value of `this`.
- `getTypeName`: returns the type of `this` as a string. This is the name of the function stored in the constructor field of `this`, if available, otherwise the object's `[[Class]]` internal property.
- `getFunction`: returns the current function.
- `getFunctionName`: returns the name of the current function, typically its `name` property. If a name property is not available an attempt will be made to try to infer a name from the function's context.
- `getMethodName`: returns the name of the property of `this` or one of its prototypes that holds the current function.
- `getFileName`: if this function was defined in a script returns the name of the script.
- `getLineNumber`: if this function was defined in a script returns the current line number.
- `getColumnNumber`: if this function was defined in a script returns the current column number
- `getEvalOrigin`: if this function was created using a call to `eval` returns a string representing the location where `eval` was called.
- `isToplevel`: is this a top-level invocation, that is, is this the global object?
- `isEval`: does this call take place in code defined by a call to `eval`?
- `isNative`: is this call in native V8 code?
- `isConstructor`: is this a constructor call?


## License

MIT © [Sindre Sorhus](https://sindresorhus.com)


---

# Camel Case

[![NPM version][npm-image]][npm-url]
[![NPM downloads][downloads-image]][downloads-url]
[![Bundle size][bundlephobia-image]][bundlephobia-url]

> Transform into a string with the separator denoted by the next word capitalized.

## Installation

```
npm install camel-case --save
```

## Usage

```js
import { camelCase } from "camel-case";

camelCase("string"); //=> "string"
camelCase("dot.case"); //=> "dotCase"
camelCase("PascalCase"); //=> "pascalCase"
camelCase("version 1.2.10"); //=> "version_1_2_10"
```

The function also accepts [`options`](https://github.com/blakeembrey/change-case#options).

### Merge Numbers

If you'd like to remove the behavior prefixing `_` before numbers, you can use `camelCaseTransformMerge`:

```js
import { camelCaseTransformMerge } from "camel-case";

camelCase("version 12", { transform: camelCaseTransformMerge }); //=> "version12"
```

## License

MIT

[npm-image]: https://img.shields.io/npm/v/camel-case.svg?style=flat
[npm-url]: https://npmjs.org/package/camel-case
[downloads-image]: https://img.shields.io/npm/dm/camel-case.svg?style=flat
[downloads-url]: https://npmjs.org/package/camel-case
[bundlephobia-image]: https://img.shields.io/bundlephobia/minzip/camel-case.svg
[bundlephobia-url]: https://bundlephobia.com/result?p=camel-case


---

# camelcase

> Convert a dash/dot/underscore/space separated string to camelCase or PascalCase: `foo-bar` → `fooBar`

Correctly handles Unicode strings.

If you use this on untrusted user input, don't forget to limit the length to something reasonable.

## Install

```
$ npm install camelcase
```

*If you need to support Firefox < 78, stay on version 5 as version 6 uses regex features not available in Firefox < 78.*

## Usage

```js
const camelCase = require('camelcase');

camelCase('foo-bar');
//=> 'fooBar'

camelCase('foo_bar');
//=> 'fooBar'

camelCase('Foo-Bar');
//=> 'fooBar'

camelCase('розовый_пушистый_единорог');
//=> 'розовыйПушистыйЕдинорог'

camelCase('Foo-Bar', {pascalCase: true});
//=> 'FooBar'

camelCase('--foo.bar', {pascalCase: false});
//=> 'fooBar'

camelCase('Foo-BAR', {preserveConsecutiveUppercase: true});
//=> 'fooBAR'

camelCase('fooBAR', {pascalCase: true, preserveConsecutiveUppercase: true}));
//=> 'FooBAR'

camelCase('foo bar');
//=> 'fooBar'

console.log(process.argv[3]);
//=> '--foo-bar'
camelCase(process.argv[3]);
//=> 'fooBar'

camelCase(['foo', 'bar']);
//=> 'fooBar'

camelCase(['__foo__', '--bar'], {pascalCase: true});
//=> 'FooBar'

camelCase(['foo', 'BAR'], {pascalCase: true, preserveConsecutiveUppercase: true})
//=> 'FooBAR'

camelCase('lorem-ipsum', {locale: 'en-US'});
//=> 'loremIpsum'
```

## API

### camelCase(input, options?)

#### input

Type: `string | string[]`

String to convert to camel case.

#### options

Type: `object`

##### pascalCase

Type: `boolean`\
Default: `false`

Uppercase the first character: `foo-bar` → `FooBar`

##### preserveConsecutiveUppercase

Type: `boolean`\
Default: `false`

Preserve the consecutive uppercase characters: `foo-BAR` → `FooBAR`.

##### locale

Type: `false | string | string[]`\
Default: The host environment’s current locale.

The locale parameter indicates the locale to be used to convert to upper/lower case according to any locale-specific case mappings. If multiple locales are given in an array, the best available locale is used.

```js
const camelCase = require('camelcase');

camelCase('lorem-ipsum', {locale: 'en-US'});
//=> 'loremIpsum'

camelCase('lorem-ipsum', {locale: 'tr-TR'});
//=> 'loremİpsum'

camelCase('lorem-ipsum', {locale: ['en-US', 'en-GB']});
//=> 'loremIpsum'

camelCase('lorem-ipsum', {locale: ['tr', 'TR', 'tr-TR']});
//=> 'loremİpsum'
```

Setting `locale: false` ignores the platform locale and uses the [Unicode Default Case Conversion](https://unicode-org.github.io/icu/userguide/transforms/casemappings.html#simple-single-character-case-mapping) algorithm:

```js
const camelCase = require('camelcase');

// On a platform with 'tr-TR'

camelCase('lorem-ipsum');
//=> 'loremİpsum'

camelCase('lorem-ipsum', {locale: false});
//=> 'loremIpsum'
```

## camelcase for enterprise

Available as part of the Tidelift Subscription.

The maintainers of camelcase and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-camelcase?utm_source=npm-camelcase&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)

## Related

- [decamelize](https://github.com/sindresorhus/decamelize) - The inverse of this module
- [uppercamelcase](https://github.com/SamVerschueren/uppercamelcase) - Like this module, but to PascalCase instead of camelCase
- [titleize](https://github.com/sindresorhus/titleize) - Capitalize every word in string
- [humanize-string](https://github.com/sindresorhus/humanize-string) - Convert a camelized/dasherized/underscored string into a humanized one
- [camelcase-keys](https://github.com/sindresorhus/camelcase-keys) - Convert object keys to camel case


---

# 3.0.0 - 2018-07-10

- Upgraded: browserslist

# 2.1.0 - 2018-06-06 (never released to npm)

- Upgraded: browserslist, caniuse-lite

# 2.0.0 - 2017-05-03

- Changed: we now use caniuse-lite instead if caniuse-db
  ([#59](https://github.com/Nyalab/caniuse-api/pull/59))

# 1.6.1 - 2017-04-07

- Added: export the feature list
  ([#48](https://github.com/Nyalab/caniuse-api/pull/48))

# 1.5.3 - 2017-02-01

- Removed unused dependency
  ([#54](https://github.com/Nyalab/caniuse-api/pull/54) - @wtgtybhertgeghgtwtg)

# 1.5.2 - 2016-09-05

- Fixed: no more generation `postinstall` hook ``\o/``.
  ([#47](https://github.com/Nyalab/caniuse-api/pull/47) - @alexisvincent)

# 1.5.1 - 2016-08-06

- Fixed: Do not fail when browserslist gives a browser that caniuse-api doesn't
  know about
  ([#45](https://github.com/Nyalab/caniuse-api/pull/45) - @onigoetz)

# 1.5.0 - 2016-06-01

- Added: JSPM support with explicit file extensions ([#40](https://github.com/Nyalab/caniuse-api/issues/40))
- Upgraded: dependecies (lodash.memoize, lodash.uniq, shelljs, babel-tape-runner, tape, tap-spec)
- Upgraded: ask travis to only test node stable
- Upgraded: some tests fixed, some tests added

# 1.4.1 - 2015-10-18

- Fixed: `generator.js` was missing

# 1.4.0 - 2015-10-18

- Upgraded: browserslist 1.x
- Upgraded: shelljs 0.5.x
- Added: output to notify if generation has been made or not
(related to [#25](https://github.com/Nyalab/caniuse-api/issues/25))

# 1.3.2 - 2015-06-23

- Fixed: lodash.uniq dep
([#31](https://github.com/Nyalab/caniuse-api/issues/31))

# 1.3.1 - 2015-03-31

- Fixed: Windows support

# 1.3.0 - 2015-03-30

- Added: better exception messages
- Added: full browserify compatibility (by avoiding dynamic require)

# 1.2.2 - 2015-02-06

- Fixed: postinstall hook for Windows

# 1.2.1 - 2015-02-04

- Changed: Allow in browser usage by avoiding `require.resolve` and using a generated json instead or reading a directory ([#20](https://github.com/Nyalab/caniuse-api/pull/20)]

# 1.2.0 [YANKED]

# 1.1.0 - 2015-02-03

- Fixed: usage of caniuse-db outside the package itself
- Changed: upgrade to browserslist 0.2.x

# 1.0.0 - 2014-12-16

- Added: package is now automatically tested by [Travis-CI](https://travis-ci.org/Nyalab/caniuse-api)

# 0.1.0 - 2014-12-15

- Changed: complete API changes, released as `caniuse-api` package

# 0.0.1 - 2014-12-09

✨Initial release


---

# caniuse-api [![Build Status](https://travis-ci.org/Nyalab/caniuse-api.svg?branch=master)](https://travis-ci.org/Nyalab/caniuse-api) [![Build status](https://ci.appveyor.com/api/projects/status/6j3na522bv3bxfa5/branch/master?svg=true)](https://ci.appveyor.com/project/MoOx/caniuse-api/branch/master)

request the caniuse data to check browsers compatibilities

## Installation

```console
$ yarn add caniuse-api
```

## Usage

```js
const caniuse = require('caniuse-api')

caniuse.getSupport('border-radius')
caniuse.isSupported('border-radius', 'ie 8, ie 9')
caniuse.setBrowserScope('> 5%, last 1 version')
caniuse.getSupport('border-radius')
// ...
```

## API

#### `caniuse.getSupport(feature)`

_ask since which browsers versions a feature is available_

* `y`: Since which browser version the feature is available
* `n`: Up to which browser version the feature is unavailable
* `a`: Up to which browser version the feature is partially supported
* `x`: Up to which browser version the feature is prefixed

```js
caniuse.getSupport('border-radius', true)
/*
{ and_chr: { y: 67 },
  and_ff: { y: 60 },
  and_qq: { y: 1.2 },
  and_uc: { y: 11.8 },
  android: { y: 2.1, x: 2.1 },
  baidu: { y: 7.12 },
  chrome: { y: 4, x: 4 },
  edge: { y: 12 },
  firefox: { a: 2, x: 3.6, y: 3 },
  ie: { n: 8, y: 9 },
  ie_mob: { y: 10 },
  ios_saf: { y: 3.2, x: 3.2 },
  op_mini: {},
  op_mob: { n: 10, y: 11 },
  opera: { n: 10, y: 10.5 },
  safari: { y: 3.1, x: 4 },
  samsung: { y: 4 } }
*/
```

#### `caniuse.isSupported(feature, browsers)`

_ask if a feature is supported by some browsers_

```js
caniuse.isSupported('border-radius', 'ie 8, ie 9') // false
caniuse.isSupported('border-radius', 'ie 9') // true
```

#### `caniuse.find(query)`

_search for a caniuse feature name_

Ex:

```js
caniuse.find('radius') // ['border-radius']
caniuse.find('nothingness') // []
caniuse.find('css3')
/*
[ 'css3-attr',
  'css3-boxsizing',
  'css3-colors',
  'css3-cursors-grab',
  'css3-cursors-newer',
  'css3-cursors',
  'css3-tabsize' ]
*/
```

#### `caniuse.getLatestStableBrowsers()`

_get the current version for each browser_

```js
caniuse.getLatestStableBrowsers()
/*
[ 'and_chr 67',
  'and_ff 60',
  'and_qq 1.2',
  'and_uc 11.8',
  'android 67',
  'baidu 7.12',
  'bb 10',
  'chrome 67',
  'edge 17',
  'firefox 61',
  'ie 11',
  'ie_mob 11',
  'ios_saf 11.3-11.4',
  'op_mini all',
  'op_mob 46',
  'opera 53',
  'safari 11.1',
  'samsung 7.2' ]
*/
```

#### `caniuse.getBrowserScope()`

_returns a list of browsers currently used for the scope of operations_

```js
caniuse.getBrowserScope()
/*
[ 'and_chr',
  'and_ff',
  'and_qq',
  'and_uc',
  'android',
  'baidu',
  'chrome',
  'edge',
  'firefox',
  'ie',
  'ie_mob',
  'ios_saf',
  'op_mini',
  'op_mob',
  'opera',
  'safari',
  'samsung' ]
*/
```

#### `caniuse.setBrowserScope(browserscope)`

_if you do not like the default browser scope, you can set it globally by using this method_

* browserscope should be a 'autoprefixer' formatted string

```js
caniuse.setBrowserScope('> 5%, last 2 versions, Firefox ESR, Opera 12.1')
```


---

## [Changelog](CHANGELOG.md)

## [License](LICENSE)


---

# caniuse-lite

A smaller version of caniuse-db, with only the essentials!

## Docs
Read full docs **[here](https://github.com/browserslist/caniuse-lite#readme)**.


---

# ccount

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]

Count how often a character (or substring) is used in a string.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`ccount(value, character)`](#ccountvalue-character)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Security](#security)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package is a small utility that helps you find how frequently a substring
occurs in another string.

## When should I use this?

I find this particularly useful when generating code, for example, when building
a string that can either be double or single quoted.
I use this utility to choose single quotes when double quotes are used more
frequently, and double quotes otherwise.

## Install

This package is [ESM only][esm].
In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]:

```sh
npm install ccount
```

In Deno with [Skypack][]:

```js
import {ccount} from 'https://cdn.skypack.dev/ccount@2?dts'
```

In browsers with [Skypack][]:

```html
<script type="module">
  import {ccount} from 'https://cdn.skypack.dev/ccount@2?min'
</script>
```

## Use

```js
import {ccount} from 'ccount'

ccount('foo(bar(baz)', '(') // => 2
ccount('foo(bar(baz)', ')') // => 1
```

## API

This package exports the following identifier: `ccount`.
There is no default export.

### `ccount(value, character)`

Count how often a character (or substring) is used in a string.

###### Parameters

*   `value` (`string`)
    — value to search in
*   `character` (`string`)
    — character (or substring) to look for

###### Returns

`number` — number of times `character` occurred in `value`.

## Types

This package is fully typed with [TypeScript][].

## Compatibility

This package is at least compatible with all maintained versions of Node.js.
As of now, that is Node.js 12.20+, 14.14+, and 16.0+.
It also works in Deno and modern browsers.

## Security

This package is safe.

## Related

*   [`wooorm/longest-streak`](https://github.com/wooorm/longest-streak)
    — count of longest repeating streak of `character` in `value`
*   [`wooorm/direction`](https://github.com/wooorm/direction)
    — detect directionality: left-to-right, right-to-left, or neutral

## Contribute

Yes please!
See [How to Contribute to Open Source][contribute].

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/wooorm/ccount/workflows/main/badge.svg

[build]: https://github.com/wooorm/ccount/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/ccount.svg

[coverage]: https://codecov.io/github/wooorm/ccount

[downloads-badge]: https://img.shields.io/npm/dm/ccount.svg

[downloads]: https://www.npmjs.com/package/ccount

[size-badge]: https://img.shields.io/bundlephobia/minzip/ccount.svg

[size]: https://bundlephobia.com/result?p=ccount

[npm]: https://docs.npmjs.com/cli/install

[skypack]: https://www.skypack.dev

[license]: license

[author]: https://wooorm.com

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[typescript]: https://www.typescriptlang.org

[contribute]: https://opensource.guide/how-to-contribute/


---

<h1 align="center">
	<br>
	<br>
	<img width="320" src="media/logo.svg" alt="Chalk">
	<br>
	<br>
	<br>
</h1>

> Terminal string styling done right

[![Build Status](https://travis-ci.org/chalk/chalk.svg?branch=master)](https://travis-ci.org/chalk/chalk) [![Coverage Status](https://coveralls.io/repos/github/chalk/chalk/badge.svg?branch=master)](https://coveralls.io/github/chalk/chalk?branch=master) [![npm dependents](https://badgen.net/npm/dependents/chalk)](https://www.npmjs.com/package/chalk?activeTab=dependents) [![Downloads](https://badgen.net/npm/dt/chalk)](https://www.npmjs.com/package/chalk) [![](https://img.shields.io/badge/unicorn-approved-ff69b4.svg)](https://www.youtube.com/watch?v=9auOCbH5Ns4) [![XO code style](https://img.shields.io/badge/code_style-XO-5ed9c7.svg)](https://github.com/xojs/xo) ![TypeScript-ready](https://img.shields.io/npm/types/chalk.svg) [![run on repl.it](https://repl.it/badge/github/chalk/chalk)](https://repl.it/github/chalk/chalk)

<img src="https://cdn.jsdelivr.net/gh/chalk/ansi-styles@8261697c95bf34b6c7767e2cbe9941a851d59385/screenshot.svg" width="900">

<br>

---

<div align="center">
	<p>
		<p>
			<sup>
				Sindre Sorhus' open source work is supported by the community on <a href="https://github.com/sponsors/sindresorhus">GitHub Sponsors</a> and <a href="https://stakes.social/0x44d871aebF0126Bf646753E2C976Aa7e68A66c15">Dev</a>
			</sup>
		</p>
		<sup>Special thanks to:</sup>
		<br>
		<br>
		<a href="https://standardresume.co/tech">
			<img src="https://sindresorhus.com/assets/thanks/standard-resume-logo.svg" width="160"/>
		</a>
		<br>
		<br>
		<a href="https://retool.com/?utm_campaign=sindresorhus">
			<img src="https://sindresorhus.com/assets/thanks/retool-logo.svg" width="230"/>
		</a>
		<br>
		<br>
		<a href="https://doppler.com/?utm_campaign=github_repo&utm_medium=referral&utm_content=chalk&utm_source=github">
			<div>
				<img src="https://dashboard.doppler.com/imgs/logo-long.svg" width="240" alt="Doppler">
			</div>
			<b>All your environment variables, in one place</b>
			<div>
				<span>Stop struggling with scattered API keys, hacking together home-brewed tools,</span>
				<br>
				<span>and avoiding access controls. Keep your team and servers in sync with Doppler.</span>
			</div>
		</a>
		<br>
		<a href="https://uibakery.io/?utm_source=chalk&utm_medium=sponsor&utm_campaign=github">
			<div>
				<img src="https://sindresorhus.com/assets/thanks/uibakery-logo.jpg" width="270" alt="UI Bakery">
			</div>
		</a>
	</p>
</div>

---

<br>

## Highlights

- Expressive API
- Highly performant
- Ability to nest styles
- [256/Truecolor color support](#256-and-truecolor-color-support)
- Auto-detects color support
- Doesn't extend `String.prototype`
- Clean and focused
- Actively maintained
- [Used by ~50,000 packages](https://www.npmjs.com/browse/depended/chalk) as of January 1, 2020

## Install

```console
$ npm install chalk
```

## Usage

```js
const chalk = require('chalk');

console.log(chalk.blue('Hello world!'));
```

Chalk comes with an easy to use composable API where you just chain and nest the styles you want.

```js
const chalk = require('chalk');
const log = console.log;

// Combine styled and normal strings
log(chalk.blue('Hello') + ' World' + chalk.red('!'));

// Compose multiple styles using the chainable API
log(chalk.blue.bgRed.bold('Hello world!'));

// Pass in multiple arguments
log(chalk.blue('Hello', 'World!', 'Foo', 'bar', 'biz', 'baz'));

// Nest styles
log(chalk.red('Hello', chalk.underline.bgBlue('world') + '!'));

// Nest styles of the same type even (color, underline, background)
log(chalk.green(
	'I am a green line ' +
	chalk.blue.underline.bold('with a blue substring') +
	' that becomes green again!'
));

// ES2015 template literal
log(`
CPU: ${chalk.red('90%')}
RAM: ${chalk.green('40%')}
DISK: ${chalk.yellow('70%')}
`);

// ES2015 tagged template literal
log(chalk`
CPU: {red ${cpu.totalPercent}%}
RAM: {green ${ram.used / ram.total * 100}%}
DISK: {rgb(255,131,0) ${disk.used / disk.total * 100}%}
`);

// Use RGB colors in terminal emulators that support it.
log(chalk.keyword('orange')('Yay for orange colored text!'));
log(chalk.rgb(123, 45, 67).underline('Underlined reddish color'));
log(chalk.hex('#DEADED').bold('Bold gray!'));
```

Easily define your own themes:

```js
const chalk = require('chalk');

const error = chalk.bold.red;
const warning = chalk.keyword('orange');

console.log(error('Error!'));
console.log(warning('Warning!'));
```

Take advantage of console.log [string substitution](https://nodejs.org/docs/latest/api/console.html#console_console_log_data_args):

```js
const name = 'Sindre';
console.log(chalk.green('Hello %s'), name);
//=> 'Hello Sindre'
```

## API

### chalk.`<style>[.<style>...](string, [string...])`

Example: `chalk.red.bold.underline('Hello', 'world');`

Chain [styles](#styles) and call the last one as a method with a string argument. Order doesn't matter, and later styles take precedent in case of a conflict. This simply means that `chalk.red.yellow.green` is equivalent to `chalk.green`.

Multiple arguments will be separated by space.

### chalk.level

Specifies the level of color support.

Color support is automatically detected, but you can override it by setting the `level` property. You should however only do this in your own code as it applies globally to all Chalk consumers.

If you need to change this in a reusable module, create a new instance:

```js
const ctx = new chalk.Instance({level: 0});
```

| Level | Description |
| :---: | :--- |
| `0` | All colors disabled |
| `1` | Basic color support (16 colors) |
| `2` | 256 color support |
| `3` | Truecolor support (16 million colors) |

### chalk.supportsColor

Detect whether the terminal [supports color](https://github.com/chalk/supports-color). Used internally and handled for you, but exposed for convenience.

Can be overridden by the user with the flags `--color` and `--no-color`. For situations where using `--color` is not possible, use the environment variable `FORCE_COLOR=1` (level 1), `FORCE_COLOR=2` (level 2), or `FORCE_COLOR=3` (level 3) to forcefully enable color, or `FORCE_COLOR=0` to forcefully disable. The use of `FORCE_COLOR` overrides all other color support checks.

Explicit 256/Truecolor mode can be enabled using the `--color=256` and `--color=16m` flags, respectively.

### chalk.stderr and chalk.stderr.supportsColor

`chalk.stderr` contains a separate instance configured with color support detected for `stderr` stream instead of `stdout`. Override rules from `chalk.supportsColor` apply to this too. `chalk.stderr.supportsColor` is exposed for convenience.

## Styles

### Modifiers

- `reset` - Resets the current color chain.
- `bold` - Make text bold.
- `dim` - Emitting only a small amount of light.
- `italic` - Make text italic. *(Not widely supported)*
- `underline` - Make text underline. *(Not widely supported)*
- `inverse`- Inverse background and foreground colors.
- `hidden` - Prints the text, but makes it invisible.
- `strikethrough` - Puts a horizontal line through the center of the text. *(Not widely supported)*
- `visible`- Prints the text only when Chalk has a color level > 0. Can be useful for things that are purely cosmetic.

### Colors

- `black`
- `red`
- `green`
- `yellow`
- `blue`
- `magenta`
- `cyan`
- `white`
- `blackBright` (alias: `gray`, `grey`)
- `redBright`
- `greenBright`
- `yellowBright`
- `blueBright`
- `magentaBright`
- `cyanBright`
- `whiteBright`

### Background colors

- `bgBlack`
- `bgRed`
- `bgGreen`
- `bgYellow`
- `bgBlue`
- `bgMagenta`
- `bgCyan`
- `bgWhite`
- `bgBlackBright` (alias: `bgGray`, `bgGrey`)
- `bgRedBright`
- `bgGreenBright`
- `bgYellowBright`
- `bgBlueBright`
- `bgMagentaBright`
- `bgCyanBright`
- `bgWhiteBright`

## Tagged template literal

Chalk can be used as a [tagged template literal](https://exploringjs.com/es6/ch_template-literals.html#_tagged-template-literals).

```js
const chalk = require('chalk');

const miles = 18;
const calculateFeet = miles => miles * 5280;

console.log(chalk`
	There are {bold 5280 feet} in a mile.
	In {bold ${miles} miles}, there are {green.bold ${calculateFeet(miles)} feet}.
`);
```

Blocks are delimited by an opening curly brace (`{`), a style, some content, and a closing curly brace (`}`).

Template styles are chained exactly like normal Chalk styles. The following three statements are equivalent:

```js
console.log(chalk.bold.rgb(10, 100, 200)('Hello!'));
console.log(chalk.bold.rgb(10, 100, 200)`Hello!`);
console.log(chalk`{bold.rgb(10,100,200) Hello!}`);
```

Note that function styles (`rgb()`, `hsl()`, `keyword()`, etc.) may not contain spaces between parameters.

All interpolated values (`` chalk`${foo}` ``) are converted to strings via the `.toString()` method. All curly braces (`{` and `}`) in interpolated value strings are escaped.

## 256 and Truecolor color support

Chalk supports 256 colors and [Truecolor](https://gist.github.com/XVilka/8346728) (16 million colors) on supported terminal apps.

Colors are downsampled from 16 million RGB values to an ANSI color format that is supported by the terminal emulator (or by specifying `{level: n}` as a Chalk option). For example, Chalk configured to run at level 1 (basic color support) will downsample an RGB value of #FF0000 (red) to 31 (ANSI escape for red).

Examples:

- `chalk.hex('#DEADED').underline('Hello, world!')`
- `chalk.keyword('orange')('Some orange text')`
- `chalk.rgb(15, 100, 204).inverse('Hello!')`

Background versions of these models are prefixed with `bg` and the first level of the module capitalized (e.g. `keyword` for foreground colors and `bgKeyword` for background colors).

- `chalk.bgHex('#DEADED').underline('Hello, world!')`
- `chalk.bgKeyword('orange')('Some orange text')`
- `chalk.bgRgb(15, 100, 204).inverse('Hello!')`

The following color models can be used:

- [`rgb`](https://en.wikipedia.org/wiki/RGB_color_model) - Example: `chalk.rgb(255, 136, 0).bold('Orange!')`
- [`hex`](https://en.wikipedia.org/wiki/Web_colors#Hex_triplet) - Example: `chalk.hex('#FF8800').bold('Orange!')`
- [`keyword`](https://www.w3.org/wiki/CSS/Properties/color/keywords) (CSS keywords) - Example: `chalk.keyword('orange').bold('Orange!')`
- [`hsl`](https://en.wikipedia.org/wiki/HSL_and_HSV) - Example: `chalk.hsl(32, 100, 50).bold('Orange!')`
- [`hsv`](https://en.wikipedia.org/wiki/HSL_and_HSV) - Example: `chalk.hsv(32, 100, 100).bold('Orange!')`
- [`hwb`](https://en.wikipedia.org/wiki/HWB_color_model) - Example: `chalk.hwb(32, 0, 50).bold('Orange!')`
- [`ansi`](https://en.wikipedia.org/wiki/ANSI_escape_code#3/4_bit) - Example: `chalk.ansi(31).bgAnsi(93)('red on yellowBright')`
- [`ansi256`](https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit) - Example: `chalk.bgAnsi256(194)('Honeydew, more or less')`

## Windows

If you're on Windows, do yourself a favor and use [Windows Terminal](https://github.com/microsoft/terminal) instead of `cmd.exe`.

## Origin story

[colors.js](https://github.com/Marak/colors.js) used to be the most popular string styling module, but it has serious deficiencies like extending `String.prototype` which causes all kinds of [problems](https://github.com/yeoman/yo/issues/68) and the package is unmaintained. Although there are other packages, they either do too much or not enough. Chalk is a clean and focused alternative.

## chalk for enterprise

Available as part of the Tidelift Subscription.

The maintainers of chalk and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-chalk?utm_source=npm-chalk&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)

## Related

- [chalk-cli](https://github.com/chalk/chalk-cli) - CLI for this module
- [ansi-styles](https://github.com/chalk/ansi-styles) - ANSI escape codes for styling strings in the terminal
- [supports-color](https://github.com/chalk/supports-color) - Detect whether a terminal supports color
- [strip-ansi](https://github.com/chalk/strip-ansi) - Strip ANSI escape codes
- [strip-ansi-stream](https://github.com/chalk/strip-ansi-stream) - Strip ANSI escape codes from a stream
- [has-ansi](https://github.com/chalk/has-ansi) - Check if a string has ANSI escape codes
- [ansi-regex](https://github.com/chalk/ansi-regex) - Regular expression for matching ANSI escape codes
- [wrap-ansi](https://github.com/chalk/wrap-ansi) - Wordwrap a string with ANSI escape codes
- [slice-ansi](https://github.com/chalk/slice-ansi) - Slice a string with ANSI escape codes
- [color-convert](https://github.com/qix-/color-convert) - Converts colors between different models
- [chalk-animation](https://github.com/bokub/chalk-animation) - Animate strings in the terminal
- [gradient-string](https://github.com/bokub/gradient-string) - Apply color gradients to strings
- [chalk-pipe](https://github.com/LitoMore/chalk-pipe) - Create chalk style schemes with simpler style strings
- [terminal-link](https://github.com/sindresorhus/terminal-link) - Create clickable links in the terminal

## Maintainers

- [Sindre Sorhus](https://github.com/sindresorhus)
- [Josh Junon](https://github.com/qix-)


---

# Char Regex [![Travis CI Build Status](https://img.shields.io/travis/com/Richienb/char-regex/master.svg?style=for-the-badge)](https://travis-ci.com/Richienb/char-regex)

A regex to match any full character, considering weird character ranges. Tested on every single emoji and unicode character. Based on the Lodash implementation.

[![NPM Badge](https://nodei.co/npm/char-regex.png)](https://npmjs.com/package/char-regex)

## Install

```sh
npm install char-regex
```

## Usage

```js
const charRegex = require("char-regex");

"❤️👊🏽".match(/./);
//=> ["", "", "", "", "", "", ""]

"❤️👊🏽".match(charRegex());
//=> ["❤️", "👊🏽"]
```

## API

### charRegex()


---

# character-entities

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]

Map of named character references.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [characterEntities](#characterentities)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Security](#security)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This is a map of named character references in HTML (latest) to the characters
they represent.

## When should I use this?

Maybe when you’re writing an HTML parser or minifier, but otherwise probably
never!
Even then, it might be better to use [`parse-entities`][parse-entities] or
[`stringify-entities`][stringify-entities].

## Install

This package is [ESM only][esm].
In Node.js (version 12.20+, 14.14+, 16.0+, 18.0+), install with [npm][]:

```sh
npm install character-entities
```

In Deno with [`esm.sh`][esmsh]:

```js
import {characterEntities} from 'https://esm.sh/character-entities@2'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {characterEntities} from 'https://esm.sh/character-entities@2?bundle'
</script>
```

## Use

```js
import {characterEntities} from 'character-entities'

console.log(characterEntities.AElig) // => 'Æ'
console.log(characterEntities.aelig) // => 'æ'
console.log(characterEntities.amp) // => '&'
```

## API

This package exports the identifier `characterEntities`.
There is no default export.

### characterEntities

Mapping between (case-sensitive) character entity names to replacements.
See [`html.spec.whatwg.org`][html] for more info.

## Types

This package is fully typed with [TypeScript][].

## Compatibility

This package is at least compatible with all maintained versions of Node.js.
As of now, that is Node.js 12.20+, 14.14+, 16.0+, and 18.0+.
It also works in Deno and modern browsers.

## Security

This package is safe.

## Related

*   [`wooorm/parse-entities`](https://github.com/wooorm/parse-entities)
    — parse (decode) character references
*   [`wooorm/stringify-entities`](https://github.com/wooorm/stringify-entities)
    — serialize (encode) character references
*   [`wooorm/character-entities-html4`](https://github.com/wooorm/character-entities-html4)
    — info on named character references in HTML 4
*   [`character-reference-invalid`](https://github.com/wooorm/character-reference-invalid)
    — info on invalid numeric character references
*   [`character-entities-legacy`](https://github.com/wooorm/character-entities-legacy)
    — info on legacy named character references

## Contribute

Yes please!
See [How to Contribute to Open Source][contribute].

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/wooorm/character-entities/workflows/main/badge.svg

[build]: https://github.com/wooorm/character-entities/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/character-entities.svg

[coverage]: https://codecov.io/github/wooorm/character-entities

[downloads-badge]: https://img.shields.io/npm/dm/character-entities.svg

[downloads]: https://www.npmjs.com/package/character-entities

[size-badge]: https://img.shields.io/bundlephobia/minzip/character-entities.svg

[size]: https://bundlephobia.com/result?p=character-entities

[npm]: https://docs.npmjs.com/cli/install

[esmsh]: https://esm.sh

[license]: license

[author]: https://wooorm.com

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[typescript]: https://www.typescriptlang.org

[contribute]: https://opensource.guide/how-to-contribute/

[parse-entities]: https://github.com/wooorm/parse-entities

[stringify-entities]: https://github.com/wooorm/stringify-entities

[html]: https://html.spec.whatwg.org/multipage/syntax.html#named-character-references


---

# character-entities-html4

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]

Map of named character references from HTML 4.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`characterEntitiesHtml4`](#characterentitieshtml4)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Security](#security)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This is a map of named character references in HTML 4 to the characters they
represent.

## When should I use this?

Maybe when you’re writing an HTML parser or minifier, but otherwise probably
never!
Even then, it might be better to use [`parse-entities`][parse-entities] or
[`stringify-entities`][stringify-entities].

## Install

This package is [ESM only][esm].
In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]:

```sh
npm install character-entities-html4
```

In Deno with [Skypack][]:

```js
import {characterEntitiesHtml4} from 'https://cdn.skypack.dev/character-entities-html4@2?dts'
```

In browsers with [Skypack][]:

```html
<script type="module">
  import {characterEntitiesHtml4} from 'https://cdn.skypack.dev/character-entities-html4@2?min'
</script>
```

## Use

```js
import {characterEntitiesHtml4} from 'character-entities-html4'

console.log(characterEntitiesHtml4.AElig) // => 'Æ'
console.log(characterEntitiesHtml4.aelig) // => 'æ'
console.log(characterEntitiesHtml4.amp) // => '&'
console.log(characterEntitiesHtml4.apos) // => undefined
```

## API

This package exports the following identifiers: `characterEntitiesHtml4`.
There is no default export.

### `characterEntitiesHtml4`

Map of case sensitive named character references from HTML 4.
See [`w3.org`][html] for more info.

## Types

This package is fully typed with [TypeScript][].

## Compatibility

This package is at least compatible with all maintained versions of Node.js.
As of now, that is Node.js 12.20+, 14.14+, and 16.0+.
It also works in Deno and modern browsers.

## Security

This package is safe.

## Related

*   [`parse-entities`](https://github.com/wooorm/parse-entities)
    — parse (decode) character references
*   [`stringify-entities`](https://github.com/wooorm/stringify-entities)
    — serialize (encode) character references
*   [`character-entities`](https://github.com/wooorm/character-entities)
    — info on character entities
*   [`character-entities-invalid`](https://github.com/wooorm/character-entities-invalid)
    — info on invalid numeric character references
*   [`character-entities-legacy`](https://github.com/wooorm/character-entities-legacy)
    — info on legacy named character references

## Contribute

Yes please!
See [How to Contribute to Open Source][contribute].

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/wooorm/character-entities-html4/workflows/main/badge.svg

[build]: https://github.com/wooorm/character-entities-html4/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/character-entities-html4.svg

[coverage]: https://codecov.io/github/wooorm/character-entities-html4

[downloads-badge]: https://img.shields.io/npm/dm/character-entities-html4.svg

[downloads]: https://www.npmjs.com/package/character-entities-html4

[size-badge]: https://img.shields.io/bundlephobia/minzip/character-entities-html4.svg

[size]: https://bundlephobia.com/result?p=character-entities-html4

[npm]: https://docs.npmjs.com/cli/install

[skypack]: https://www.skypack.dev

[license]: license

[author]: https://wooorm.com

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[typescript]: https://www.typescriptlang.org

[contribute]: https://opensource.guide/how-to-contribute/

[parse-entities]: https://github.com/wooorm/parse-entities

[stringify-entities]: https://github.com/wooorm/stringify-entities

[html]: https://www.w3.org/TR/html4/sgml/entities.html


---

# character-entities-legacy

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]

List of legacy HTML named character references that don’t need a trailing
semicolon.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`characterEntitiesLegacy`](#characterentitieslegacy)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Security](#security)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This is a list of certain named character references, that due to legacy
reasons, don’t need a trailing semicolon in HTML.
For example, `&copy` is perfectly fine for `©`!

## When should I use this?

Maybe when you’re writing an HTML parser or minifier, but otherwise probably
never!
Even then, it might be better to use [`parse-entities`][parse-entities] or
[`stringify-entities`][stringify-entities].

## Install

This package is [ESM only][esm].
In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]:

```sh
npm install character-entities-legacy
```

In Deno with [Skypack][]:

```js
import {characterEntitiesLegacy} from 'https://cdn.skypack.dev/character-entities-legacy@2?dts'
```

In browsers with [Skypack][]:

```html
<script type="module">
  import {characterEntitiesLegacy} from 'https://cdn.skypack.dev/character-entities-legacy@2?min'
</script>
```

## Use

```js
import {characterEntitiesLegacy} from 'character-entities-legacy'

console.log(characterEntitiesLegacy.includes('copy')) // => true
console.log(characterEntitiesLegacy.includes('frac34')) // => true
console.log(characterEntitiesLegacy.includes('sup1')) // => true
```

## API

This package exports the following identifiers: `characterEntitiesLegacy`.
There is no default export.

### `characterEntitiesLegacy`

List of (case sensitive) legacy character entity names.
[`wooorm/character-entities`][character-entities] holds their decoded values.
See [`whatwg/html`][html] for more info.

## Types

This package is fully typed with [TypeScript][].

## Compatibility

This package is at least compatible with all maintained versions of Node.js.
As of now, that is Node.js 12.20+, 14.14+, and 16.0+.
It also works in Deno and modern browsers.

## Security

This package is safe.

## Related

*   [`wooorm/parse-entities`](https://github.com/wooorm/parse-entities)
    — parse (decode) character references
*   [`wooorm/stringify-entities`](https://github.com/wooorm/stringify-entities)
    — serialize (encode) character references
*   [`wooorm/character-entities`](https://github.com/wooorm/character-entities)
    — info on character entities
*   [`wooorm/character-entities-html4`](https://github.com/wooorm/character-entities-html4)
    — info on HTML4 character entities
*   [`wooorm/character-reference-invalid`](https://github.com/wooorm/character-reference-invalid)
    — info on invalid numeric character references

## Contribute

Yes please!
See [How to Contribute to Open Source][contribute].

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/wooorm/character-entities-legacy/workflows/main/badge.svg

[build]: https://github.com/wooorm/character-entities-legacy/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/character-entities-legacy.svg

[coverage]: https://codecov.io/github/wooorm/character-entities-legacy

[downloads-badge]: https://img.shields.io/npm/dm/character-entities-legacy.svg

[downloads]: https://www.npmjs.com/package/character-entities-legacy

[size-badge]: https://img.shields.io/bundlephobia/minzip/character-entities-legacy.svg

[size]: https://bundlephobia.com/result?p=character-entities-legacy

[npm]: https://docs.npmjs.com/cli/install

[skypack]: https://www.skypack.dev

[license]: license

[author]: https://wooorm.com

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[typescript]: https://www.typescriptlang.org

[contribute]: https://opensource.guide/how-to-contribute/

[html]: https://github.com/whatwg/html-build/blob/HEAD/entities/json-entities-legacy.inc

[parse-entities]: https://github.com/wooorm/parse-entities

[stringify-entities]: https://github.com/wooorm/stringify-entities

[character-entities]: https://github.com/wooorm/character-entities


---

# character-reference-invalid

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]

Map of invalid numeric character references to their replacements, according to
HTML.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`characterReferenceInvalid`](#characterreferenceinvalid)
*   [Source](#source)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Security](#security)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This is a map from the [HTML spec][source] of C1 ASCII/Unicode control
characters (which are disallowed by HTML) to the characters those code points
would have in Windows 1252.
For example, U+0080 (Padding Character) maps to `€`, because that’s used for
0x80 in Windows 1252.

## When should I use this?

Probably never, unless you’re dealing with parsing HTML or similar XML-like
things, or in a place where Unicode is not the primary encoding (it is in most
places).

## Install

This package is [ESM only][esm].
In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]:

```sh
npm install character-reference-invalid
```

In Deno with [Skypack][]:

```js
import {characterReferenceInvalid} from 'https://cdn.skypack.dev/character-reference-invalid@2?dts'
```

In browsers with [Skypack][]:

```html
<script type="module">
  import {characterReferenceInvalid} from 'https://cdn.skypack.dev/character-reference-invalid@2?min'
</script>
```

## Use

```js
import {characterReferenceInvalid} from 'character-reference-invalid'

console.log(characterReferenceInvalid[0x80]) // => '€'
console.log(characterReferenceInvalid[0x89]) // => '‰'
console.log(characterReferenceInvalid[0x99]) // => '™'
```

## API

This package exports the following identifiers: `characterReferenceInvalid`.
There is no default export.

### `characterReferenceInvalid`

`Record<number, string>` — mapping between invalid numeric character reference
codes to replacements characters.

## Source

See [`html.spec.whatwg.org`][source].

## Types

This package is fully typed with [TypeScript][].

## Compatibility

This package is at least compatible with all maintained versions of Node.js.
As of now, that is Node.js 12.20+, 14.14+, and 16.0+.
It also works in Deno and modern browsers.

## Security

This package is safe.

## Related

*   [`wooorm/character-entities`](https://github.com/wooorm/character-entities)
    — HTML character entity info
*   [`wooorm/character-entities-html4`](https://github.com/wooorm/character-entities-html4)
    — HTML 4 character entity info
*   [`wooorm/character-entities-legacy`](https://github.com/wooorm/character-entities-legacy)
    — legacy character entity info
*   [`wooorm/parse-entities`](https://github.com/wooorm/parse-entities)
    — parse HTML character references
*   [`wooorm/stringify-entities`](https://github.com/wooorm/stringify-entities)
    — serialize HTML character references

## Contribute

Yes please!
See [How to Contribute to Open Source][contribute].

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/wooorm/character-reference-invalid/workflows/main/badge.svg

[build]: https://github.com/wooorm/character-reference-invalid/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/character-reference-invalid.svg

[coverage]: https://codecov.io/github/wooorm/character-reference-invalid

[downloads-badge]: https://img.shields.io/npm/dm/character-reference-invalid.svg

[downloads]: https://www.npmjs.com/package/character-reference-invalid

[size-badge]: https://img.shields.io/bundlephobia/minzip/character-reference-invalid.svg

[size]: https://bundlephobia.com/result?p=character-reference-invalid

[npm]: https://docs.npmjs.com/cli/install

[skypack]: https://www.skypack.dev

[license]: license

[author]: https://wooorm.com

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[typescript]: https://www.typescriptlang.org

[contribute]: https://opensource.guide/how-to-contribute/

[source]: https://html.spec.whatwg.org/multipage/parsing.html#table-charref-overrides


---

<h1 align="center">cheerio</h1>

<h5 align="center">Fast, flexible & lean implementation of core jQuery designed specifically for the server.</h5>

<div align="center">
  <a href="https://github.com/cheeriojs/cheerio/actions?query=workflow%3ACI+branch%3Amain">
    <img src="https://img.shields.io/github/workflow/status/cheeriojs/cheerio/CI/main" alt="Build Status">
  </a>
  <a href="https://coveralls.io/github/cheeriojs/cheerio">
    <img src="https://img.shields.io/coveralls/github/cheeriojs/cheerio/main" alt="Coverage">
  </a>
  <a href="#backers">
    <img src="https://img.shields.io/opencollective/backers/cheerio" alt="OpenCollective backers">
  </a>
  <a href="#sponsors">
    <img src="https://img.shields.io/opencollective/sponsors/cheerio" alt="OpenCollective sponsors">
  </a>
</div>

<br>

[中文文档 (Chinese Readme)](https://github.com/cheeriojs/cheerio/wiki/Chinese-README)

```js
const cheerio = require('cheerio');
const $ = cheerio.load('<h2 class="title">Hello world</h2>');

$('h2.title').text('Hello there!');
$('h2').addClass('welcome');

$.html();
//=> <html><head></head><body><h2 class="title welcome">Hello there!</h2></body></html>
```

## Note

We are currently working on the 1.0.0 release of cheerio on the `main` branch. The source code for the last published version, `0.22.0`, can be found [here](https://github.com/cheeriojs/cheerio/tree/aa90399c9c02f12432bfff97b8f1c7d8ece7c307).

## Installation

`npm install cheerio`

## Features

**&#10084; Familiar syntax:**
Cheerio implements a subset of core jQuery. Cheerio removes all the DOM inconsistencies and browser cruft from the jQuery library, revealing its truly gorgeous API.

**&#991; Blazingly fast:**
Cheerio works with a very simple, consistent DOM model. As a result parsing, manipulating, and rendering are incredibly efficient.

**&#10049; Incredibly flexible:**
Cheerio wraps around [parse5](https://github.com/inikulin/parse5) parser and can optionally use @FB55's forgiving [htmlparser2](https://github.com/fb55/htmlparser2/). Cheerio can parse nearly any HTML or XML document.

## Cheerio is not a web browser

Cheerio parses markup and provides an API for traversing/manipulating the resulting data structure. It does not interpret the result as a web browser does. Specifically, it does _not_ produce a visual rendering, apply CSS, load external resources, or execute JavaScript which is common for a SPA (single page application). This makes Cheerio **much, much faster than other solutions**. If your use case requires any of this functionality, you should consider browser automation software like [Puppeteer](https://github.com/puppeteer/puppeteer) and [Playwright](https://github.com/microsoft/playwright) or DOM emulation projects like [JSDom](https://github.com/jsdom/jsdom).

## API

### Markup example we'll be using:

```html
<ul id="fruits">
  <li class="apple">Apple</li>
  <li class="orange">Orange</li>
  <li class="pear">Pear</li>
</ul>
```

This is the HTML markup we will be using in all of the API examples.

### Loading

First you need to load in the HTML. This step in jQuery is implicit, since jQuery operates on the one, baked-in DOM. With Cheerio, we need to pass in the HTML document.

This is the _preferred_ method:

```js
// ES6 or TypeScript:
import * as cheerio from 'cheerio';

// In other environments:
const cheerio = require('cheerio');

const $ = cheerio.load('<ul id="fruits">...</ul>');

$.html();
//=> <html><head></head><body><ul id="fruits">...</ul></body></html>
```

Similar to web browser contexts, `load` will introduce `<html>`, `<head>`, and `<body>` elements if they are not already present. You can set `load`'s third argument to `false` to disable this.

```js
const $ = cheerio.load('<ul id="fruits">...</ul>', null, false);

$.html();
//=> '<ul id="fruits">...</ul>'
```

Optionally, you can also load in the HTML by passing the string as the context:

```js
$('ul', '<ul id="fruits">...</ul>');
```

Or as the root:

```js
$('li', 'ul', '<ul id="fruits">...</ul>');
```

If you need to modify parsing options for XML input, you may pass an extra
object to `.load()`:

```js
const $ = cheerio.load('<ul id="fruits">...</ul>', {
  xml: {
    normalizeWhitespace: true,
  },
});
```

The options in the `xml` object are taken directly from [htmlparser2](https://github.com/fb55/htmlparser2/wiki/Parser-options), therefore any options that can be used in `htmlparser2` are valid in cheerio as well. When `xml` is set, the default options are:

```js
{
    xmlMode: true,
    decodeEntities: true, // Decode HTML entities.
    withStartIndices: false, // Add a `startIndex` property to nodes.
    withEndIndices: false, // Add an `endIndex` property to nodes.
}
```

For a full list of options and their effects, see [domhandler](https://github.com/fb55/DomHandler) and
[htmlparser2's options](https://github.com/fb55/htmlparser2/wiki/Parser-options).

#### Using `htmlparser2`

Cheerio ships with two parsers, `parse5` and `htmlparser2`. The
former is the default for HTML, the latter the default for XML.

Some users may wish to parse markup with the `htmlparser2` library, and
traverse/manipulate the resulting structure with Cheerio. This may be the case
for those upgrading from pre-1.0 releases of Cheerio (which relied on
`htmlparser2`), for those dealing with invalid markup (because `htmlparser2` is
more forgiving), or for those operating in performance-critical situations
(because `htmlparser2` may be faster in some cases). Note that "more forgiving"
means `htmlparser2` has error-correcting mechanisms that aren't always a match
for the standards observed by web browsers. This behavior may be useful when
parsing non-HTML content.

To support these cases, `load` also accepts a `htmlparser2`-compatible data
structure as its first argument. Users may install `htmlparser2`, use it to
parse input, and pass the result to `load`:

```js
// Usage as of htmlparser2 version 6:
const htmlparser2 = require('htmlparser2');
const dom = htmlparser2.parseDocument(document, options);

const $ = cheerio.load(dom);
```

If you want to save some bytes, you can use Cheerio's _slim_ export, which
always uses `htmlparser2`:

```js
const cheerio = require('cheerio/lib/slim');
```

### Selectors

Cheerio's selector implementation is nearly identical to jQuery's, so the API is very similar.

#### \$( selector, [context], [root] )

`selector` searches within the `context` scope which searches within the `root` scope. `selector` and `context` can be a string expression, DOM Element, array of DOM elements, or cheerio object. `root` is typically the HTML document string.

This selector method is the starting point for traversing and manipulating the document. Like jQuery, it's the primary method for selecting elements in the document.

```js
$('.apple', '#fruits').text();
//=> Apple

$('ul .pear').attr('class');
//=> pear

$('li[class=orange]').html();
//=> Orange
```

##### XML Namespaces

You can select with XML Namespaces but [due to the CSS specification](https://www.w3.org/TR/2011/REC-css3-selectors-20110929/#attribute-selectors), the colon (`:`) needs to be escaped for the selector to be valid.

```js
$('[xml\\:id="main"');
```

### Rendering

When you're ready to render the document, you can call the `html` method on the "root" selection:

```js
$.root().html();
//=>  <html>
//      <head></head>
//      <body>
//        <ul id="fruits">
//          <li class="apple">Apple</li>
//          <li class="orange">Orange</li>
//          <li class="pear">Pear</li>
//        </ul>
//      </body>
//    </html>
```

If you want to render the [`outerHTML`](https://developer.mozilla.org/en-US/docs/Web/API/Element/outerHTML) of a selection, you can use the `html` utility functon:

```js
cheerio.html($('.pear'));
//=> <li class="pear">Pear</li>
```

You may also render the text content of a Cheerio object using the `text` static method:

```js
const $ = cheerio.load('This is <em>content</em>.');
cheerio.text($('body'));
//=> This is content.
```

### Plugins

Once you have loaded a document, you may extend the prototype or the equivalent `fn` property with custom plugin methods:

```js
const $ = cheerio.load('<html><body>Hello, <b>world</b>!</body></html>');
$.prototype.logHtml = function () {
  console.log(this.html());
};

$('body').logHtml(); // logs "Hello, <b>world</b>!" to the console
```

If you're using TypeScript, you should add a type definition for your new method:

```ts
declare module 'cheerio' {
  interface Cheerio<T> {
    logHtml(this: Cheerio<T>): void;
  }
}
```

### The "DOM Node" object

Cheerio collections are made up of objects that bear some resemblance to [browser-based DOM nodes](https://developer.mozilla.org/en-US/docs/Web/API/Node). You can expect them to define the following properties:

- `tagName`
- `parentNode`
- `previousSibling`
- `nextSibling`
- `nodeValue`
- `firstChild`
- `childNodes`
- `lastChild`

## Screencasts

[https://vimeo.com/31950192](https://vimeo.com/31950192)

> This video tutorial is a follow-up to Nettut's "How to Scrape Web Pages with Node.js and jQuery", using cheerio instead of JSDOM + jQuery. This video shows how easy it is to use cheerio and how much faster cheerio is than JSDOM + jQuery.

## Cheerio in the real world

Are you using cheerio in production? Add it to the [wiki](https://github.com/cheeriojs/cheerio/wiki/Cheerio-in-Production)!

## Sponsors

Does your company use Cheerio in production? Please consider [sponsoring this project](https://github.com/cheeriojs/cheerio?sponsor=1)! Your help will allow maintainers to dedicate more time and resources to its development and support.

<!-- BEGIN SPONSORS: sponsor -->

<a href="https://github.com/about" target="_blank" rel="noopener noreferrer">
            <img style="max-height:128px;max-width:128px" src="https://avatars.githubusercontent.com/u/9919?v=4&s=128" title="GitHub" alt="GitHub"></img>
          </a>
<a href="https://cryptocasinos.com/" target="_blank" rel="noopener noreferrer">
            <img style="max-height:128px;max-width:128px" src="https://images.opencollective.com/cryptocasinos/99b168e/logo.png" title="CryptoCasinos" alt="CryptoCasinos"></img>
          </a>
<a href="https://www.casinoonlineaams.com" target="_blank" rel="noopener noreferrer">
            <img style="max-height:128px;max-width:128px" src="https://images.opencollective.com/casinoonlineaamscom/da74236/logo.png" title="Casinoonlineaams.com" alt="Casinoonlineaams.com"></img>
          </a>
<a href="https://casinofiables.com/" target="_blank" rel="noopener noreferrer">
            <img style="max-height:128px;max-width:128px" src="https://images.opencollective.com/casinofiables-com/b824bab/logo.png" title="Casinofiables.com" alt="Casinofiables.com"></img>
          </a>
<a href="https://apify.com/" target="_blank" rel="noopener noreferrer">
            <img style="max-height:128px;max-width:128px" src="https://avatars.githubusercontent.com/u/24586296?v=4&s=128" title="Apify" alt="Apify"></img>
          </a>
<a href="https://freebets.ltd.uk" target="_blank" rel="noopener noreferrer">
            <img style="max-height:128px;max-width:128px" src="https://images.opencollective.com/freebets/e21c41b/logo.png" title="Free Bets" alt="Free Bets"></img>
          </a>
<a href="https://casinoutansvensklicens.co/" target="_blank" rel="noopener noreferrer">
            <img style="max-height:128px;max-width:128px" src="https://images.opencollective.com/casino-utan-svensk-licens3/f7e9357/logo.png" title="Casino utan svensk licens" alt="Casino utan svensk licens"></img>
          </a>
<a href="https://starwarscasinos.com/" target="_blank" rel="noopener noreferrer">
            <img style="max-height:128px;max-width:128px" src="https://images.opencollective.com/casino-utan-svensk-licens1/f3487ff/logo.png" title="Casino utan svensk licens" alt="Casino utan svensk licens"></img>
          </a>

<!-- END SPONSORS -->

## Backers

[Become a backer](https://github.com/cheeriojs/cheerio?sponsor=1) to show your support for Cheerio and help us maintain and improve this open source project.

<!-- BEGIN SPONSORS: backer -->

<a href="https://www.airbnb.com/" target="_blank" rel="noopener noreferrer">
            <img style="max-height:128px;max-width:128px" src="https://images.opencollective.com/airbnb/d327d66/logo.png" title="Airbnb" alt="Airbnb"></img>
          </a>
<a href="https://kafidoff.com" target="_blank" rel="noopener noreferrer">
            <img style="max-height:128px;max-width:128px" src="https://images.opencollective.com/kafidoff-vasy/d7ff85c/avatar.png" title="Vasy Kafidoff" alt="Vasy Kafidoff"></img>
          </a>
<a href="https://medium.com/norch" target="_blank" rel="noopener noreferrer">
            <img style="max-height:128px;max-width:128px" src="https://images.opencollective.com/espenklem/6075b19/avatar.png" title="Espen Klem" alt="Espen Klem"></img>
          </a>
<a href="https://jarrodldavis.com" target="_blank" rel="noopener noreferrer">
            <img style="max-height:128px;max-width:128px" src="https://avatars.githubusercontent.com/u/235875?v=4&s=128" title="Jarrod Davis" alt="Jarrod Davis"></img>
          </a>
<a href="https://nishant-singh.com" target="_blank" rel="noopener noreferrer">
            <img style="max-height:128px;max-width:128px" src="https://avatars.githubusercontent.com/u/10304344?u=2f98c0a745b5352c6e758b9a5bc7a9d9d4e3e969&v=4&s=128" title="Nishant Singh" alt="Nishant Singh"></img>
          </a>
<a href="https://github.com/gauthamchandra" target="_blank" rel="noopener noreferrer">
            <img style="max-height:128px;max-width:128px" src="https://avatars.githubusercontent.com/u/5430280?u=1115bcd3ed7aa8b2a62ff28f62ee4c2b92729903&v=4&s=128" title="Gautham Chandra" alt="Gautham Chandra"></img>
          </a>
<a href="http://www.dr-chuck.com/" target="_blank" rel="noopener noreferrer">
            <img style="max-height:128px;max-width:128px" src="https://avatars.githubusercontent.com/u/1197222?u=d6dc85c064736ab851c6d9e3318dcdd1be00fb2c&v=4&s=128" title="Charles Severance" alt="Charles Severance"></img>
          </a>

<!-- END SPONSORS -->

## Special Thanks

This library stands on the shoulders of some incredible developers. A special thanks to:

**&#8226; @FB55 for node-htmlparser2 & CSSSelect:**
Felix has a knack for writing speedy parsing engines. He completely re-wrote both @tautologistic's `node-htmlparser` and @harry's `node-soupselect` from the ground up, making both of them much faster and more flexible. Cheerio would not be possible without his foundational work

**&#8226; @jQuery team for jQuery:**
The core API is the best of its class and despite dealing with all the browser inconsistencies the code base is extremely clean and easy to follow. Much of cheerio's implementation and documentation is from jQuery. Thanks guys.

**&#8226; @visionmedia:**
The style, the structure, the open-source"-ness" of this library comes from studying TJ's style and using many of his libraries. This dude consistently pumps out high-quality libraries and has always been more than willing to help or answer questions. You rock TJ.

## License

MIT


---

# cheerio-select [![NPM version](http://img.shields.io/npm/v/cheerio-select.svg)](https://npmjs.org/package/cheerio-select) [![Build Status](https://travis-ci.org/cheeriojs/cheerio-select.svg?branch=master)](http://travis-ci.org/cheeriojs/cheerio-select) [![Downloads](https://img.shields.io/npm/dm/cheerio-select.svg)](https://npmjs.org/package/cheerio-select) [![Coverage](https://coveralls.io/repos/cheeriojs/cheerio-select/badge.svg?branch=master)](https://coveralls.io/r/cheeriojs/cheerio-select)

CSS selector engine supporting jQuery selectors, based on [`css-select`](https://github.com/fb55/css-select).

Supports all jQuery positional pseudo-selectors:

-   `:first`
-   `:last`
-   `:eq`
-   `:nth`
-   `:gt`
-   `:lt`
-   `:even`
-   `:odd`
-   `:not(:positional)`, where `:positional` is any of the above.

This library is a thin wrapper around [`css-select`](https://github.com/fb55/css-select).
Only use this module if you will actually use jQuery positional selectors.


---

# Chokidar [![Weekly downloads](https://img.shields.io/npm/dw/chokidar.svg)](https://github.com/paulmillr/chokidar) [![Yearly downloads](https://img.shields.io/npm/dy/chokidar.svg)](https://github.com/paulmillr/chokidar)

> Minimal and efficient cross-platform file watching library

[![NPM](https://nodei.co/npm/chokidar.png)](https://www.npmjs.com/package/chokidar)

## Why?

Node.js `fs.watch`:

* Doesn't report filenames on MacOS.
* Doesn't report events at all when using editors like Sublime on MacOS.
* Often reports events twice.
* Emits most changes as `rename`.
* Does not provide an easy way to recursively watch file trees.
* Does not support recursive watching on Linux.

Node.js `fs.watchFile`:

* Almost as bad at event handling.
* Also does not provide any recursive watching.
* Results in high CPU utilization.

Chokidar resolves these problems.

Initially made for **[Brunch](https://brunch.io/)** (an ultra-swift web app build tool), it is now used in
[Microsoft's Visual Studio Code](https://github.com/microsoft/vscode),
[gulp](https://github.com/gulpjs/gulp/),
[karma](https://karma-runner.github.io/),
[PM2](https://github.com/Unitech/PM2),
[browserify](http://browserify.org/),
[webpack](https://webpack.github.io/),
[BrowserSync](https://www.browsersync.io/),
and [many others](https://www.npmjs.com/browse/depended/chokidar).
It has proven itself in production environments.

Version 3 is out! Check out our blog post about it: [Chokidar 3: How to save 32TB of traffic every week](https://paulmillr.com/posts/chokidar-3-save-32tb-of-traffic/)

## How?

Chokidar does still rely on the Node.js core `fs` module, but when using
`fs.watch` and `fs.watchFile` for watching, it normalizes the events it
receives, often checking for truth by getting file stats and/or dir contents.

On MacOS, chokidar by default uses a native extension exposing the Darwin
`FSEvents` API. This provides very efficient recursive watching compared with
implementations like `kqueue` available on most \*nix platforms. Chokidar still
does have to do some work to normalize the events received that way as well.

On most other platforms, the `fs.watch`-based implementation is the default, which
avoids polling and keeps CPU usage down. Be advised that chokidar will initiate
watchers recursively for everything within scope of the paths that have been
specified, so be judicious about not wasting system resources by watching much
more than needed.

## Getting started

Install with npm:

```sh
npm install chokidar
```

Then `require` and use it in your code:

```javascript
const chokidar = require('chokidar');

// One-liner for current directory
chokidar.watch('.').on('all', (event, path) => {
  console.log(event, path);
});
```

## API

```javascript
// Example of a more typical implementation structure

// Initialize watcher.
const watcher = chokidar.watch('file, dir, glob, or array', {
  ignored: /(^|[\/\\])\../, // ignore dotfiles
  persistent: true
});

// Something to use when events are received.
const log = console.log.bind(console);
// Add event listeners.
watcher
  .on('add', path => log(`File ${path} has been added`))
  .on('change', path => log(`File ${path} has been changed`))
  .on('unlink', path => log(`File ${path} has been removed`));

// More possible events.
watcher
  .on('addDir', path => log(`Directory ${path} has been added`))
  .on('unlinkDir', path => log(`Directory ${path} has been removed`))
  .on('error', error => log(`Watcher error: ${error}`))
  .on('ready', () => log('Initial scan complete. Ready for changes'))
  .on('raw', (event, path, details) => { // internal
    log('Raw event info:', event, path, details);
  });

// 'add', 'addDir' and 'change' events also receive stat() results as second
// argument when available: https://nodejs.org/api/fs.html#fs_class_fs_stats
watcher.on('change', (path, stats) => {
  if (stats) console.log(`File ${path} changed size to ${stats.size}`);
});

// Watch new files.
watcher.add('new-file');
watcher.add(['new-file-2', 'new-file-3', '**/other-file*']);

// Get list of actual paths being watched on the filesystem
var watchedPaths = watcher.getWatched();

// Un-watch some files.
await watcher.unwatch('new-file*');

// Stop watching.
// The method is async!
watcher.close().then(() => console.log('closed'));

// Full list of options. See below for descriptions.
// Do not use this example!
chokidar.watch('file', {
  persistent: true,

  ignored: '*.txt',
  ignoreInitial: false,
  followSymlinks: true,
  cwd: '.',
  disableGlobbing: false,

  usePolling: false,
  interval: 100,
  binaryInterval: 300,
  alwaysStat: false,
  depth: 99,
  awaitWriteFinish: {
    stabilityThreshold: 2000,
    pollInterval: 100
  },

  ignorePermissionErrors: false,
  atomic: true // or a custom 'atomicity delay', in milliseconds (default 100)
});

```

`chokidar.watch(paths, [options])`

* `paths` (string or array of strings). Paths to files, dirs to be watched
recursively, or glob patterns.
    - Note: globs must not contain windows separators (`\`),
    because that's how they work by the standard —
    you'll need to replace them with forward slashes (`/`).
    - Note 2: for additional glob documentation, check out low-level
    library: [picomatch](https://github.com/micromatch/picomatch).
* `options` (object) Options object as defined below:

#### Persistence

* `persistent` (default: `true`). Indicates whether the process
should continue to run as long as files are being watched. If set to
`false` when using `fsevents` to watch, no more events will be emitted
after `ready`, even if the process continues to run.

#### Path filtering

* `ignored` ([anymatch](https://github.com/es128/anymatch)-compatible definition)
Defines files/paths to be ignored. The whole relative or absolute path is
tested, not just filename. If a function with two arguments is provided, it
gets called twice per path - once with a single argument (the path), second
time with two arguments (the path and the
[`fs.Stats`](https://nodejs.org/api/fs.html#fs_class_fs_stats)
object of that path).
* `ignoreInitial` (default: `false`). If set to `false` then `add`/`addDir` events are also emitted for matching paths while
instantiating the watching as chokidar discovers these file paths (before the `ready` event).
* `followSymlinks` (default: `true`). When `false`, only the
symlinks themselves will be watched for changes instead of following
the link references and bubbling events through the link's path.
* `cwd` (no default). The base directory from which watch `paths` are to be
derived. Paths emitted with events will be relative to this.
* `disableGlobbing` (default: `false`). If set to `true` then the strings passed to `.watch()` and `.add()` are treated as
literal path names, even if they look like globs.

#### Performance

* `usePolling` (default: `false`).
Whether to use fs.watchFile (backed by polling), or fs.watch. If polling
leads to high CPU utilization, consider setting this to `false`. It is
typically necessary to **set this to `true` to successfully watch files over
a network**, and it may be necessary to successfully watch files in other
non-standard situations. Setting to `true` explicitly on MacOS overrides the
`useFsEvents` default. You may also set the CHOKIDAR_USEPOLLING env variable
to true (1) or false (0) in order to override this option.
* _Polling-specific settings_ (effective when `usePolling: true`)
  * `interval` (default: `100`). Interval of file system polling, in milliseconds. You may also
    set the CHOKIDAR_INTERVAL env variable to override this option.
  * `binaryInterval` (default: `300`). Interval of file system
  polling for binary files.
  ([see list of binary extensions](https://github.com/sindresorhus/binary-extensions/blob/master/binary-extensions.json))
* `useFsEvents` (default: `true` on MacOS). Whether to use the
`fsevents` watching interface if available. When set to `true` explicitly
and `fsevents` is available this supercedes the `usePolling` setting. When
set to `false` on MacOS, `usePolling: true` becomes the default.
* `alwaysStat` (default: `false`). If relying upon the
[`fs.Stats`](https://nodejs.org/api/fs.html#fs_class_fs_stats)
object that may get passed with `add`, `addDir`, and `change` events, set
this to `true` to ensure it is provided even in cases where it wasn't
already available from the underlying watch events.
* `depth` (default: `undefined`). If set, limits how many levels of
subdirectories will be traversed.
* `awaitWriteFinish` (default: `false`).
By default, the `add` event will fire when a file first appears on disk, before
the entire file has been written. Furthermore, in some cases some `change`
events will be emitted while the file is being written. In some cases,
especially when watching for large files there will be a need to wait for the
write operation to finish before responding to a file creation or modification.
Setting `awaitWriteFinish` to `true` (or a truthy value) will poll file size,
holding its `add` and `change` events until the size does not change for a
configurable amount of time. The appropriate duration setting is heavily
dependent on the OS and hardware. For accurate detection this parameter should
be relatively high, making file watching much less responsive.
Use with caution.
  * *`options.awaitWriteFinish` can be set to an object in order to adjust
  timing params:*
  * `awaitWriteFinish.stabilityThreshold` (default: 2000). Amount of time in
  milliseconds for a file size to remain constant before emitting its event.
  * `awaitWriteFinish.pollInterval` (default: 100). File size polling interval, in milliseconds.

#### Errors

* `ignorePermissionErrors` (default: `false`). Indicates whether to watch files
that don't have read permissions if possible. If watching fails due to `EPERM`
or `EACCES` with this set to `true`, the errors will be suppressed silently.
* `atomic` (default: `true` if `useFsEvents` and `usePolling` are `false`).
Automatically filters out artifacts that occur when using editors that use
"atomic writes" instead of writing directly to the source file. If a file is
re-added within 100 ms of being deleted, Chokidar emits a `change` event
rather than `unlink` then `add`. If the default of 100 ms does not work well
for you, you can override it by setting `atomic` to a custom value, in
milliseconds.

### Methods & Events

`chokidar.watch()` produces an instance of `FSWatcher`. Methods of `FSWatcher`:

* `.add(path / paths)`: Add files, directories, or glob patterns for tracking.
Takes an array of strings or just one string.
* `.on(event, callback)`: Listen for an FS event.
Available events: `add`, `addDir`, `change`, `unlink`, `unlinkDir`, `ready`,
`raw`, `error`.
Additionally `all` is available which gets emitted with the underlying event
name and path for every event other than `ready`, `raw`, and `error`.  `raw` is internal, use it carefully.
* `.unwatch(path / paths)`: Stop watching files, directories, or glob patterns.
Takes an array of strings or just one string.
* `.close()`: **async** Removes all listeners from watched files. Asynchronous, returns Promise. Use with `await` to ensure bugs don't happen.
* `.getWatched()`: Returns an object representing all the paths on the file
system being watched by this `FSWatcher` instance. The object's keys are all the
directories (using absolute paths unless the `cwd` option was used), and the
values are arrays of the names of the items contained in each directory.

## CLI

If you need a CLI interface for your file watching, check out
[chokidar-cli](https://github.com/open-cli-tools/chokidar-cli), allowing you to
execute a command on each change, or get a stdio stream of change events.

## Install Troubleshooting

* `npm WARN optional dep failed, continuing fsevents@n.n.n`
  * This message is normal part of how `npm` handles optional dependencies and is
    not indicative of a problem. Even if accompanied by other related error messages,
    Chokidar should function properly.

* `TypeError: fsevents is not a constructor`
  * Update chokidar by doing `rm -rf node_modules package-lock.json yarn.lock && npm install`, or update your dependency that uses chokidar.

* Chokidar is producing `ENOSP` error on Linux, like this:
  * `bash: cannot set terminal process group (-1): Inappropriate ioctl for device bash: no job control in this shell`
  `Error: watch /home/ ENOSPC`
  * This means Chokidar ran out of file handles and you'll need to increase their count by executing the following command in Terminal:
  `echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p`

## Changelog

For more detailed changelog, see [`full_changelog.md`](.github/full_changelog.md).
- **v3.5 (Jan 6, 2021):** Support for ARM Macs with Apple Silicon. Fixes for deleted symlinks.
- **v3.4 (Apr 26, 2020):** Support for directory-based symlinks. Fixes for macos file replacement.
- **v3.3 (Nov 2, 2019):** `FSWatcher#close()` method became async. That fixes IO race conditions related to close method.
- **v3.2 (Oct 1, 2019):** Improve Linux RAM usage by 50%. Race condition fixes. Windows glob fixes. Improve stability by using tight range of dependency versions.
- **v3.1 (Sep 16, 2019):** dotfiles are no longer filtered out by default. Use `ignored` option if needed. Improve initial Linux scan time by 50%.
- **v3 (Apr 30, 2019):** massive CPU & RAM consumption improvements; reduces deps / package size by a factor of 17x and bumps Node.js requirement to v8.16 and higher.
- **v2 (Dec 29, 2017):** Globs are now posix-style-only; without windows support. Tons of bugfixes.
- **v1 (Apr 7, 2015):** Glob support, symlink support, tons of bugfixes. Node 0.8+ is supported
- **v0.1 (Apr 20, 2012):** Initial release, extracted from [Brunch](https://github.com/brunch/brunch/blob/9847a065aea300da99bd0753f90354cde9de1261/src/helpers.coffee#L66)

## Also

Why was chokidar named this way? What's the meaning behind it?

>Chowkidar is a transliteration of a Hindi word meaning 'watchman, gatekeeper', चौकीदार. This ultimately comes from Sanskrit _ चतुष्क_ (crossway, quadrangle, consisting-of-four). This word is also used in other languages like Urdu as (چوکیدار) which is widely used in Pakistan and India. 

## License

MIT (c) Paul Miller (<https://paulmillr.com>), see [LICENSE](LICENSE) file.


---

# node-trace-event changelog

## 1.3.1 (not yet released)

(nothing yet)


## 1.3.0

- Add `.child(<fields>)` option to `trace_event.createBunyanTracer()` object.


## 1.2.0

- Add `trace_event.createBunyanLogger()` usage for some sugar. See the
  README.md for details.


## 1.1.0

- Rename to 'trace-event', which is a much more accurate name.


## 1.0.0

First release.


---

[![Build Status](https://travis-ci.org/samccone/chrome-trace-event.svg?branch=master)](https://travis-ci.org/samccone/chrome-trace-event)

chrome-trace-event: A node library for creating trace event logs of program
execution according to [Google's Trace Event
format](https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU).
These logs can then be visualized with
[trace-viewer](https://github.com/google/trace-viewer) or chrome devtools to grok one's programs.

# Install

    npm install chrome-trace-event

# Usage

```javascript
const Trace = require("chrome-trace-event").Tracer;
const trace = new Trace({
    noStream: true
});
trace.pipe(fs.createWriteStream(outPath));
trace.flush();
```

# Links

* https://github.com/google/trace-viewer/wiki
* https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU

# License

MIT. See LICENSE.txt.


---

# Changelog

## v3.9.0

- better support for Azure Pipelines ([#116](https://github.com/watson/ci-info/pull/116)), [5ea8d85](https://github.com/watson/ci-info/commit/5ea8d85)
- detect PullRequest in Azure Pipelines [5ea8d85](https://github.com/watson/ci-info/commit/5ea8d85)

## v3.8.0

- support Harness CI [76a2867](https://github.com/watson/ci-info/commit/76a2867)

## v3.7.1

- ignore ci detection when CI is set to `'false'` [24cc450](https://github.com/watson/ci-info/commit/24cc450)

## v3.7.0

- support Sourcehut CI [85b96ea](https://github.com/watson/ci-info/commit/85b96ea)
- support ReleaseHub CI [409d886](https://github.com/watson/ci-info/commit/409d886)

## v3.6.2

- fix VERCEL environment detection ([#98](https://github.com/watson/ci-info/pull/98))

## v3.6.1

- fix error in typings [357b454](https://github.com/watson/ci-info/commit/357b454)

## v3.6.0

This release attempts to bring parity with [@npmcli/ci-detect](https://github.com/npm/ci-detect). See [#95](https://github.com/watson/ci-info/pull/95) for more details.

- support gerrit ([#95](https://github.com/watson/ci-info/pull/95))
- support google cloud build ([#95](https://github.com/watson/ci-info/pull/95))
- support heroku ([#95](https://github.com/watson/ci-info/pull/95))
- support anonymous CI's that exposes BUILD_ID and CI_NAME env vars ([#95](https://github.com/watson/ci-info/pull/95))
- support more vercel environments ([#95](https://github.com/watson/ci-info/pull/95))

## v3.5.0

- support Woodpecker CI ([#90](https://github.com/watson/ci-info/pull/90))

## v3.4.0

- partial support Appflow CI (only CI detection) ([#84](https://github.com/watson/ci-info/pull/84))
- support Codemagic CI ([#85](https://github.com/watson/ci-info/pull/85))
- support Xcode Server CI ([#86](https://github.com/watson/ci-info/pull/86))
- support Xcode Cloud CI ([#86](https://github.com/watson/ci-info/pull/86))

## v3.3.2

- fix: export correct typings for `EAS`

## v3.3.1

- fix: export `EAS_BUILD` constant in typings
- Add support for nodejs v18

## v3.3.0

- support Expo Application Services ([#70](https://github.com/watson/ci-info/pull/70))

## v3.2.0

- support LayerCI ([#68](https://github.com/watson/ci-info/pull/68))
- support Appcircle ([#69](https://github.com/watson/ci-info/pull/69))
- support Codefresh CI ([#65](https://github.com/watson/ci-info/pull/65))
- add support for nodejs v16

## v3.1.1

Bug Fixes:

- remove duplicate declaration in typings

## v3.1.0

Features:

- add typings

## v3.0.0

Features:

- Add support nodejs versions: 14, 15
- support Nevercode ([#30](https://github.com/watson/ci-info/pull/30))
- support Render CI ([#36](https://github.com/watson/ci-info/pull/36))
- support Now CI ([#37](https://github.com/watson/ci-info/pull/37))
- support GitLab PR ([#59](https://github.com/watson/ci-info/pull/59))
- support Screwdriver CD ([#60](https://github.com/watson/ci-info/pull/60))
- support Visual Studio App Center ([#61](https://github.com/watson/ci-info/pull/61))

Bug Fixes:

- update Netlify env constant ([#47](https://github.com/watson/ci-info/pull/47))

Breaking changes:

- Drop support for Node.js end-of-life versions: 6, 13
- replace `Zeit Now` with `Vercel` ([#55](https://github.com/watson/ci-info/pull/55))

## v2.0.0

Breaking changes:

- Drop support for Node.js end-of-life versions: 0.10, 0.12, 4, 5, 7, and 9
- Team Foundation Server will now be detected as Azure Pipelines. The constant `ci.TFS` no longer exists - use
  `ci.AZURE_PIPELINES` instead
- Remove deprecated `ci.TDDIUM` constant - use `ci.SOLANDO` instead

New features:

- feat: support Azure Pipelines ([#23](https://github.com/watson/ci-info/pull/23))
- feat: support Netlify CI ([#26](https://github.com/watson/ci-info/pull/26))
- feat: support Bitbucket pipelines PR detection ([#27](https://github.com/watson/ci-info/pull/27))

## v1.6.0

- feat: add Sail CI support
- feat: add Buddy support
- feat: add Bitrise support
- feat: detect Jenkins PRs
- feat: detect Drone PRs

## v1.5.1

- fix: use full path to vendors.json

## v1.5.0

- feat: add dsari detection ([#15](https://github.com/watson/ci-info/pull/15))
- feat: add ci.isPR ([#16](https://github.com/watson/ci-info/pull/16))

## v1.4.0

- feat: add Cirrus CI detection ([#13](https://github.com/watson/ci-info/pull/13))
- feat: add Shippable CI detection ([#14](https://github.com/watson/ci-info/pull/14))

## v1.3.1

- chore: reduce npm package size by not including `.github` folder content
  ([#11](https://github.com/watson/ci-info/pull/11))

## v1.3.0

- feat: add support for Strider CD
- chore: deprecate vendor constant `TDDIUM` in favor of `SOLANO`
- docs: add missing vendor constant to docs

## v1.2.0

- feat: detect solano-ci ([#9](https://github.com/watson/ci-info/pull/9))

## v1.1.3

- fix: fix spelling of Hunson in `ci.name`

## v1.1.2

- fix: no more false positive matches for Jenkins

## v1.1.1

- docs: sort lists of CI servers in README.md
- docs: add missing AWS CodeBuild to the docs

## v1.1.0

- feat: add AWS CodeBuild to CI detection ([#2](https://github.com/watson/ci-info/pull/2))

## v1.0.1

- chore: reduce npm package size by using an `.npmignore` file ([#3](https://github.com/watson/ci-info/pull/3))

## v1.0.0

- Initial release


---

# ci-info

Get details about the current Continuous Integration environment.

Please [open an
issue](https://github.com/watson/ci-info/issues/new?template=ci-server-not-detected.md)
if your CI server isn't properly detected :)

[![npm](https://img.shields.io/npm/v/ci-info.svg)](https://www.npmjs.com/package/ci-info)
[![Tests](https://github.com/watson/ci-info/workflows/Tests/badge.svg)](https://github.com/watson/ci-info/actions)
[![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat)](https://github.com/feross/standard)

## Installation

```bash
npm install ci-info --save
```

## Usage

```js
var ci = require('ci-info')

if (ci.isCI) {
  console.log('The name of the CI server is:', ci.name)
} else {
  console.log('This program is not running on a CI server')
}
```

## Supported CI tools

Officially supported CI servers:

| Name                                                                            | Constant                | isPR |
| ------------------------------------------------------------------------------- | ----------------------- | ---- |
| [AWS CodeBuild](https://aws.amazon.com/codebuild/)                              | `ci.CODEBUILD`          | 🚫   |
| [AppVeyor](http://www.appveyor.com)                                             | `ci.APPVEYOR`           | ✅   |
| [Azure Pipelines](https://azure.microsoft.com/en-us/services/devops/pipelines/) | `ci.AZURE_PIPELINES`    | ✅   |
| [Appcircle](https://appcircle.io/)                                              | `ci.APPCIRCLE`          | 🚫   |
| [Bamboo](https://www.atlassian.com/software/bamboo) by Atlassian                | `ci.BAMBOO`             | 🚫   |
| [Bitbucket Pipelines](https://bitbucket.org/product/features/pipelines)         | `ci.BITBUCKET`          | ✅   |
| [Bitrise](https://www.bitrise.io/)                                              | `ci.BITRISE`            | ✅   |
| [Buddy](https://buddy.works/)                                                   | `ci.BUDDY`              | ✅   |
| [Buildkite](https://buildkite.com)                                              | `ci.BUILDKITE`          | ✅   |
| [CircleCI](http://circleci.com)                                                 | `ci.CIRCLE`             | ✅   |
| [Cirrus CI](https://cirrus-ci.org)                                              | `ci.CIRRUS`             | ✅   |
| [Codefresh](https://codefresh.io/)                                              | `ci.CODEFRESH`          | ✅   |
| [Codeship](https://codeship.com)                                                | `ci.CODESHIP`           | 🚫   |
| [Drone](https://drone.io)                                                       | `ci.DRONE`              | ✅   |
| [dsari](https://github.com/rfinnie/dsari)                                       | `ci.DSARI`              | 🚫   |
| [Expo Application Services](https://expo.dev/eas)                               | `ci.EAS`                | 🚫   |
| [Gerrit CI](https://www.gerritcodereview.com)                                   | `ci.GERRIT`             | 🚫   |
| [GitHub Actions](https://github.com/features/actions/)                          | `ci.GITHUB_ACTIONS`     | ✅   |
| [GitLab CI](https://about.gitlab.com/gitlab-ci/)                                | `ci.GITLAB`             | ✅   |
| [GoCD](https://www.go.cd/)                                                      | `ci.GOCD`               | 🚫   |
| [Google Cloud Build](https://cloud.google.com/build)                            | `ci.GOOGLE_CLOUD_BUILD` | 🚫   |
| [Harness CI](https://www.harness.io/products/continuous-integration)            | `ci.HARNESS`            | 🚫   |
| [Heroku](https://www.heroku.com)                                                | `ci.HEROKU`             | 🚫   |
| [Hudson](http://hudson-ci.org)                                                  | `ci.HUDSON`             | 🚫   |
| [Jenkins CI](https://jenkins-ci.org)                                            | `ci.JENKINS`            | ✅   |
| [LayerCI](https://layerci.com/)                                                 | `ci.LAYERCI`            | ✅   |
| [Magnum CI](https://magnum-ci.com)                                              | `ci.MAGNUM`             | 🚫   |
| [Netlify CI](https://www.netlify.com/)                                          | `ci.NETLIFY`            | ✅   |
| [Nevercode](http://nevercode.io/)                                               | `ci.NEVERCODE`          | ✅   |
| [ReleaseHub](https://releasehub.com/)                                           | `ci.RELEASEHUB`         | 🚫   |
| [Render](https://render.com/)                                                   | `ci.RENDER`             | ✅   |
| [Sail CI](https://sail.ci/)                                                     | `ci.SAIL`               | ✅   |
| [Screwdriver](https://screwdriver.cd/)                                          | `ci.SCREWDRIVER`        | ✅   |
| [Semaphore](https://semaphoreci.com)                                            | `ci.SEMAPHORE`          | ✅   |
| [Shippable](https://www.shippable.com/)                                         | `ci.SHIPPABLE`          | ✅   |
| [Solano CI](https://www.solanolabs.com/)                                        | `ci.SOLANO`             | ✅   |
| [Sourcehut](https://sourcehut.org/)                                             | `ci.SOURCEHUT`          | 🚫   |
| [Strider CD](https://strider-cd.github.io/)                                     | `ci.STRIDER`            | 🚫   |
| [TaskCluster](http://docs.taskcluster.net)                                      | `ci.TASKCLUSTER`        | 🚫   |
| [TeamCity](https://www.jetbrains.com/teamcity/) by JetBrains                    | `ci.TEAMCITY`           | 🚫   |
| [Travis CI](http://travis-ci.org)                                               | `ci.TRAVIS`             | ✅   |
| [Vercel](https://vercel.com/)                                                   | `ci.VERCEL`             | ✅   |
| [Visual Studio App Center](https://appcenter.ms/)                               | `ci.APPCENTER`          | 🚫   |
| [Woodpecker](https://woodpecker-ci.org/)                                        | `ci.WOODPECKER`         | ✅   |

## API

### `ci.name`

Returns a string containing name of the CI server the code is running on.
If CI server is not detected, it returns `null`.

Don't depend on the value of this string not to change for a specific
vendor. If you find your self writing `ci.name === 'Travis CI'`, you
most likely want to use `ci.TRAVIS` instead.

### `ci.isCI`

Returns a boolean. Will be `true` if the code is running on a CI server,
otherwise `false`.

Some CI servers not listed here might still trigger the `ci.isCI`
boolean to be set to `true` if they use certain vendor neutral
environment variables. In those cases `ci.name` will be `null` and no
vendor specific boolean will be set to `true`.

### `ci.isPR`

Returns a boolean if PR detection is supported for the current CI server. Will
be `true` if a PR is being tested, otherwise `false`. If PR detection is
not supported for the current CI server, the value will be `null`.

### `ci.<VENDOR-CONSTANT>`

A vendor specific boolean constant is exposed for each support CI
vendor. A constant will be `true` if the code is determined to run on
the given CI server, otherwise `false`.

Examples of vendor constants are `ci.TRAVIS` or `ci.APPVEYOR`. For a
complete list, see the support table above.

Deprecated vendor constants that will be removed in the next major
release:

- `ci.TDDIUM` (Solano CI) This have been renamed `ci.SOLANO`

## Ports

ci-info has been ported to the following languages

| Language | Repository |
|----------|------------|
| Go       | https://github.com/hofstadter-io/cinful |
| Rust     | https://github.com/sagiegurari/ci_info |
| Kotlin   | https://github.com/cloudflightio/ci-info |

## License

[MIT](LICENSE)


---

[5.3.3 / 2023-11-30](https://github.com/clean-css/clean-css/compare/v5.3.2...v5.3.3)
==================

* Fixed issue [#1262](https://github.com/clean-css/clean-css/issues/1262) - dynamically require os for edge runtime compatibility.

[5.3.2 / 2023-01-19](https://github.com/clean-css/clean-css/compare/v5.3.1...v5.3.2)
==================

* Fixed issue [#1224](https://github.com/clean-css/clean-css/issues/1224) - incorrect parsing of selectors with double hyphen.
* Fixed issue [#1228](https://github.com/clean-css/clean-css/issues/1228) - incorrect appending of '%' inside rgba colors.
* Fixed issue [#1232](https://github.com/clean-css/clean-css/issues/1232) - support for `@container` keyword.
* Fixed issue [#1239](https://github.com/clean-css/clean-css/issues/1239) - edge case in handling `@import` statements.
* Fixed issue [#1242](https://github.com/clean-css/clean-css/issues/1242) - support for `@layer` keyword.

[5.3.1 / 2022-07-13](https://github.com/clean-css/clean-css/compare/v5.3.0...v5.3.1)
==================

* Fixed issue [#1218](https://github.com/clean-css/clean-css/issues/1218) - double hyphen in at-rule breaks parsing.
* Fixed issue [#1220](https://github.com/clean-css/clean-css/issues/1220) - adds optimization for nth-* rules.

[5.3.0 / 2022-03-31](https://github.com/clean-css/clean-css/compare/v5.2.3...v5.3.0)
==================

* Adds customizable value optimizers for variables.
* Fixed issue [#1159](https://github.com/clean-css/clean-css/issues/1159) - adds optimization for `nth-child` and `nth-of-type`.
* Fixed issue [#1181](https://github.com/clean-css/clean-css/issues/1181) - CSS level 4 color functions with spaces.
* Fixed issue [#1183](https://github.com/clean-css/clean-css/issues/1183) - fraction optimizer breaks `image-set`.
* Fixed issue [#1208](https://github.com/clean-css/clean-css/issues/1208) - handling generic family names.
* Fixed issue [#1210](https://github.com/clean-css/clean-css/issues/1210) - handling `file://` protocol.

[5.2.4 / 2022-01-28](https://github.com/clean-css/clean-css/compare/v5.2.3...v5.2.4)
==================

* Fixed issue [#1196](https://github.com/clean-css/clean-css/issues/1196) - correctly parse variables & comments mix.

[5.2.3 / 2022-01-26](https://github.com/clean-css/clean-css/compare/v5.2.2...v5.2.3)
==================

* Fixed issue [#1185](https://github.com/clean-css/clean-css/issues/1185) - keeping comments inside variables.
* Fixed issue [#1194](https://github.com/clean-css/clean-css/issues/1194) - unexpected end of JSON input when source map is empty.

[5.2.2 / 2021-10-21](https://github.com/clean-css/clean-css/compare/v5.2.1...v5.2.2)
==================

* Fixed an unsafe data URI regex, which, when clean-css is used as a service, could be used in a DOS attack.

[5.2.1 / 2021-09-30](https://github.com/clean-css/clean-css/compare/v5.2.0...v5.2.1)
==================

* Fixed issue [#1186](https://github.com/clean-css/clean-css/issues/1186) - bad error handling in batch mode with promises.

[5.2.0 / 2021-09-25](https://github.com/clean-css/clean-css/compare/5.1...v5.2.0)
==================

* Fixed issue [#1180](https://github.com/clean-css/clean-css/issues/1180) - properly handle empty variable values.

[5.1.5 / 2021-08-05](https://github.com/clean-css/clean-css/compare/v5.1.4...v5.1.5)
==================

* Fixed issue [#1178](https://github.com/clean-css/clean-css/issues/1178) - fixes lack of space removal in variable blocks.

[5.1.4 / 2021-07-29](https://github.com/clean-css/clean-css/compare/v5.1.3...v5.1.4)
==================

* Fixed issue [#1177](https://github.com/clean-css/clean-css/issues/1177) - fix to missing local imports when only remote ones allowed.

[5.1.3 / 2021-06-25](https://github.com/clean-css/clean-css/compare/v5.1.2...v5.1.3)
==================

* Fixed issue [#1160](https://github.com/clean-css/clean-css/issues/1160) - keep zero units when inside multiple functions.
* Fixed issue [#1161](https://github.com/clean-css/clean-css/issues/1161) - extra whitespace in URLs.
* Fixed issue [#1166](https://github.com/clean-css/clean-css/issues/1166) - incorrect compoment splitting when empty multiplex part.

[5.1.2 / 2021-03-19](https://github.com/clean-css/clean-css/compare/v5.1.1...v5.1.2)
==================

* Fixed issue [#996](https://github.com/clean-css/clean-css/issues/996) - space removed from pseudo classes.

[5.1.1 / 2021-03-03](https://github.com/clean-css/clean-css/compare/v5.1.0...v5.1.1)
==================

* Fixed issue [#1156](https://github.com/clean-css/clean-css/issues/1156) - invalid hsl/hsla validation in level 2 optimizations.

[5.1.0 / 2021-02-18](https://github.com/clean-css/clean-css/compare/5.0...v5.1.0)
==================

* Fixes stripping '%' from inside color functions.
* Improves tokenization speed by ~30%.
* Fixed issue [#1143](https://github.com/clean-css/clean-css/issues/1143) - some missing level 1 value optimizations.


[5.0.1 / 2021-01-29](https://github.com/clean-css/clean-css/compare/v5.0.0...v5.0.1)
==================

* Fixed issue [#1139](https://github.com/clean-css/clean-css/issues/1139) - overriding & merging properties without `canOverride` set.

[5.0.0 / 2021-01-29](https://github.com/clean-css/clean-css/compare/4.2...v5.0.0)
==================

* Adds a way process input files without bundling it into one big output file.
* Adds level 1 and level 2 optimization plugins.
* Disables URL rebasing by default.
* Disables URL unquoting by default.
* Drops support for Node.js 6 & 8 to support last 3 Node.js releases: 10, 12, and 14.
* Fixed issue [#889](https://github.com/clean-css/clean-css/issues/889) - whitelisted level 1 optimizations.
* Fixed issue [#975](https://github.com/clean-css/clean-css/issues/975) - incorrect block name optimization.
* Fixed issue [#1009](https://github.com/clean-css/clean-css/issues/1009) - whitespace around comments.
* Fixed issue [#1021](https://github.com/clean-css/clean-css/issues/1021) - allow one- and two-letter property names.
* Fixed issue [#1022](https://github.com/clean-css/clean-css/issues/1022) - merging into shorthands new property positioning.
* Fixed issue [#1032](https://github.com/clean-css/clean-css/issues/1032) - wrong order of merged shorthands with inherit.
* Fixed issue [#1043](https://github.com/clean-css/clean-css/issues/1043) - `calc` fallback removed within other function.
* Fixed issue [#1045](https://github.com/clean-css/clean-css/issues/1045) - non-standard protocol-less URL first slash removed.
* Fixed issue [#1050](https://github.com/clean-css/clean-css/issues/1050) - correctly keeps default animation duration if delay is also set.
* Fixed issue [#1053](https://github.com/clean-css/clean-css/issues/1053) - treats `calc()` as first class width value.
* Fixed issue [#1055](https://github.com/clean-css/clean-css/issues/1055) - supports 4- and 8-character hex with alpha color notation.
* Fixed issue [#1057](https://github.com/clean-css/clean-css/issues/1057) - level 2 optimizations and quoted font family name.
* Fixed issue [#1059](https://github.com/clean-css/clean-css/issues/1059) - animation time units as CSS expressions.
* Fixed issue [#1060](https://github.com/clean-css/clean-css/issues/1060) - variable removed when shorthand's only value.
* Fixed issue [#1062](https://github.com/clean-css/clean-css/issues/1062) - wrong optimization of CSS pseudo-classes with selector list.
* Fixed issue [#1073](https://github.com/clean-css/clean-css/issues/1073) - adds support for non-standard `rpx` units.
* Fixed issue [#1075](https://github.com/clean-css/clean-css/issues/1075) - media merging and variables.
* Fixed issue [#1087](https://github.com/clean-css/clean-css/issues/1087) - allow units with any case.
* Fixed issue [#1088](https://github.com/clean-css/clean-css/issues/1088) - building source maps with source preserved via comments.
* Fixed issue [#1090](https://github.com/clean-css/clean-css/issues/1090) - edge case in merging for `border` and `border-image`.
* Fixed issue [#1103](https://github.com/clean-css/clean-css/issues/1103) - don't allow merging longhand into `unset` shorthand.
* Fixed issue [#1115](https://github.com/clean-css/clean-css/issues/1115) - incorrect multiplex longhand into shorthand merging.
* Fixed issue [#1117](https://github.com/clean-css/clean-css/issues/1117) - don't change zero values inside `min`, `max`, and `clamp` functions.
* Fixed issue [#1122](https://github.com/clean-css/clean-css/issues/1122) - don't wrap data URI in single quotes.
* Fixed issue [#1125](https://github.com/clean-css/clean-css/issues/1125) - quotes stripped from withing `@supports` clause.
* Fixed issue [#1128](https://github.com/clean-css/clean-css/issues/1128) - take variables into account when reordering properties.
* Fixed issue [#1132](https://github.com/clean-css/clean-css/issues/1132) - vendor-prefixed classes inside `:not()`.
* Reworks all level 1 optimizations to conform to plugin style.

[4.2.3 / 2020-01-28](https://github.com/clean-css/clean-css/compare/v4.2.2...v4.2.3)
==================

* Fixed issue [#1106](https://github.com/clean-css/clean-css/issues/1106) - regression in handling RGBA/HSLA colors.

[4.2.2 / 2020-01-25](https://github.com/clean-css/clean-css/compare/v4.2.1...v4.2.2)
==================

* Fixed error when property block has no value.
* Fixed issue [#1077](https://github.com/clean-css/clean-css/issues/1077) - local fonts with color in name.
* Fixed issue [#1082](https://github.com/clean-css/clean-css/issues/1082) - correctly convert colors if alpha >= 1.
* Fixed issue [#1085](https://github.com/clean-css/clean-css/issues/1085) - prevent unquoting of grid elements.

[4.2.1 / 2018-08-07](https://github.com/clean-css/clean-css/compare/v4.2.0...v4.2.1)
==================

* Fixes giving `breakWith` option via a string.

[4.2.0 / 2018-08-02](https://github.com/clean-css/clean-css/compare/4.1...v4.2.0)
==================

* Adds `process` method for compatibility with optimize-css-assets-webpack-plugin.
* Fixed issue [#861](https://github.com/clean-css/clean-css/issues/861) - new `transition` property optimizer.
* Fixed issue [#895](https://github.com/clean-css/clean-css/issues/895) - ignoring specific styles.
* Fixed issue [#947](https://github.com/clean-css/clean-css/issues/947) - selector based filtering.
* Fixed issue [#964](https://github.com/clean-css/clean-css/issues/964) - adds configurable line breaks.
* Fixed issue [#986](https://github.com/clean-css/clean-css/issues/986) - level 2 optimizations and CSS 4 colors.
* Fixed issue [#1000](https://github.com/clean-css/clean-css/issues/1000) - carriage return handling in tokenizer.
* Fixed issue [#1038](https://github.com/clean-css/clean-css/issues/1038) - `font-variation-settings` quoting.
* Fixes ReDOS vulnerabilities in validator code.

[4.1.11 / 2018-03-06](https://github.com/clean-css/clean-css/compare/v4.1.10...v4.1.11)
==================

* Backports fixes to ReDOS vulnerabilities in validator code.

[4.1.10 / 2018-03-05](https://github.com/clean-css/clean-css/compare/v4.1.9...v4.1.10)
==================

* Fixed issue [#988](https://github.com/clean-css/clean-css/issues/988) - edge case in dropping default animation-duration.
* Fixed issue [#989](https://github.com/clean-css/clean-css/issues/989) - edge case in removing unused at rules.
* Fixed issue [#1001](https://github.com/clean-css/clean-css/issues/1001) - corrupted tokenizer state.
* Fixed issue [#1006](https://github.com/clean-css/clean-css/issues/1006) - edge case in handling invalid source maps.
* Fixed issue [#1008](https://github.com/clean-css/clean-css/issues/1008) - edge case in breaking up `font` shorthand.

[4.1.9 / 2017-09-19](https://github.com/clean-css/clean-css/compare/v4.1.8...v4.1.9)
==================

* Fixed issue [#971](https://github.com/clean-css/clean-css/issues/971) - edge case in removing unused at rules.

[4.1.8 / 2017-09-02](https://github.com/clean-css/clean-css/compare/v4.1.7...v4.1.8)
==================

* Fixed issue [#959](https://github.com/clean-css/clean-css/issues/959) - regression in shortening long hex values.
* Fixed issue [#960](https://github.com/clean-css/clean-css/issues/960) - better explanation of `efficiency` stat.
* Fixed issue [#965](https://github.com/clean-css/clean-css/issues/965) - edge case in parsing comment endings.
* Fixed issue [#966](https://github.com/clean-css/clean-css/issues/966) - remote `@import`s referenced from local ones.

[4.1.7 / 2017-07-14](https://github.com/clean-css/clean-css/compare/v4.1.6...v4.1.7)
==================

* Fixed issue [#957](https://github.com/clean-css/clean-css/issues/957) - `0%` minification of `width` property.

[4.1.6 / 2017-07-08](https://github.com/clean-css/clean-css/compare/v4.1.5...v4.1.6)
==================

* Fixed issue [#887](https://github.com/clean-css/clean-css/issues/887) - edge case in serializing comments.
* Fixed issue [#953](https://github.com/clean-css/clean-css/issues/953) - beautify breaks attribute selectors.

[4.1.5 / 2017-06-29](https://github.com/clean-css/clean-css/compare/v4.1.4...v4.1.5)
==================

* Fixed issue [#945](https://github.com/clean-css/clean-css/issues/945) - hex RGBA colors in IE filters.
* Fixed issue [#952](https://github.com/clean-css/clean-css/issues/952) - parsing `@page` according to CSS3 spec.

[4.1.4 / 2017-06-14](https://github.com/clean-css/clean-css/compare/v4.1.3...v4.1.4)
==================

* Fixed issue [#950](https://github.com/clean-css/clean-css/issues/950) - bug in removing unused `@font-face` rules.

[4.1.3 / 2017-05-18](https://github.com/clean-css/clean-css/compare/v4.1.2...v4.1.3)
==================

* Fixed issue [#946](https://github.com/clean-css/clean-css/issues/946) - tokenizing `-ms-grid-columns` repeat syntax.

[4.1.2 / 2017-05-10](https://github.com/clean-css/clean-css/compare/v4.1.1...v4.1.2)
==================

* Fixed issue [#939](https://github.com/clean-css/clean-css/issues/939) - semicolon after `@apply` at rule.
* Fixed issue [#940](https://github.com/clean-css/clean-css/issues/940) - handling more `font` keywords.
* Fixed issue [#941](https://github.com/clean-css/clean-css/issues/941) - breaking up vendor prefixed `animation`.

[4.1.1 / 2017-05-08](https://github.com/clean-css/clean-css/compare/v4.1.0...v4.1.1)
==================

* Fixed issue [#938](https://github.com/clean-css/clean-css/issues/938) - removing unused at-rules with `!important`.

[4.1.0 / 2017-05-07](https://github.com/clean-css/clean-css/compare/4.0...v4.1.0)
==================

* Improves longhand-into-shorthand merging mechanism in complex cases as with `border-*` shorthands.
* Fixed issue [#254](https://github.com/clean-css/clean-css/issues/254) - adds `font` property optimizer.
* Fixed issue [#525](https://github.com/clean-css/clean-css/issues/525) - restores `inherit`-based merging.
* Fixed issue [#755](https://github.com/clean-css/clean-css/issues/755) - adds custom handling of remote requests.
* Fixed issue [#860](https://github.com/clean-css/clean-css/issues/860) - adds `animation` property optimizer.
* Fixed issue [#862](https://github.com/clean-css/clean-css/issues/862) - allows removing unused at rules.
* Fixed issue [#886](https://github.com/clean-css/clean-css/issues/886) - better multi pseudo class / element merging.
* Fixed issue [#890](https://github.com/clean-css/clean-css/issues/890) - adds toggle to disable empty tokens removal.
* Fixed issue [#893](https://github.com/clean-css/clean-css/issues/893) - `inline: false` as alias to `inline: 'none'`.
* Fixed issue [#905](https://github.com/clean-css/clean-css/issues/905) - allows disabling selector sorting.
* Fixed issue [#906](https://github.com/clean-css/clean-css/issues/906) - improves usability of web UI settings.
* Fixed issue [#908](https://github.com/clean-css/clean-css/issues/908) - improved `minify` method signature.
* Fixed issue [#916](https://github.com/clean-css/clean-css/issues/916) - maximum number of merged selectors.
* Fixed issue [#920](https://github.com/clean-css/clean-css/issues/920) - allows skipping certain properties in level 2 optimizations.
* Fixed issue [#934](https://github.com/clean-css/clean-css/issues/934) - smarter longhand into shorthand merging.

[4.0.13 / 2017-05-10](https://github.com/clean-css/clean-css/compare/v4.0.12...v4.0.13)
==================

* Backports [#939](https://github.com/clean-css/clean-css/issues/939) - semicolon after `@apply` at rule.

[4.0.12 / 2017-04-12](https://github.com/clean-css/clean-css/compare/v4.0.11...v4.0.12)
==================

* Fixed issue [#930](https://github.com/clean-css/clean-css/issues/930) - regression in tidying selectors.

[4.0.11 / 2017-04-04](https://github.com/clean-css/clean-css/compare/v4.0.10...v4.0.11)
==================

* Fixed issue [#924](https://github.com/clean-css/clean-css/issues/924) - `hsl` zero percent eager optimization.

[4.0.10 / 2017-03-22](https://github.com/clean-css/clean-css/compare/v4.0.9...v4.0.10)
==================

* Fixed issue [#917](https://github.com/clean-css/clean-css/issues/917) - prevents grid area unquoting.
* Backported [#916](https://github.com/clean-css/clean-css/issues/916) - maximum number of merged selectors.
* Refixed issue [#556](https://github.com/clean-css/clean-css/issues/556) - IE backslash hacks.

[4.0.9 / 2017-03-15](https://github.com/clean-css/clean-css/compare/v4.0.8...v4.0.9)
==================

* Fixed issue [#902](https://github.com/clean-css/clean-css/issues/902) - case insensitive attribute matchers.
* Fixed issue [#903](https://github.com/clean-css/clean-css/issues/903) - web UI and source maps.
* Fixed issue [#907](https://github.com/clean-css/clean-css/issues/907) - space after closing brace in `@supports`.
* Fixed issue [#910](https://github.com/clean-css/clean-css/issues/910) - too aggressive precision optimizations.

[4.0.8 / 2017-02-22](https://github.com/clean-css/clean-css/compare/v4.0.7...v4.0.8)
==================

* Fixes edge case in remote stylesheet fetching.
* Fixed issue [#899](https://github.com/clean-css/clean-css/issues/899) - regression in optimizing pseudo class arguments.

[4.0.7 / 2017-02-14](https://github.com/clean-css/clean-css/compare/v4.0.6...v4.0.7)
==================

* Fixed issue [#891](https://github.com/clean-css/clean-css/issues/891) - merging vendor-prefixed pseudo-classes.

[4.0.6 / 2017-02-10](https://github.com/clean-css/clean-css/compare/v4.0.5...v4.0.6)
==================

* Fixed issue [#885](https://github.com/clean-css/clean-css/issues/885) - unquoting `font-feature-settings`.

[4.0.5 / 2017-02-07](https://github.com/clean-css/clean-css/compare/v4.0.4...v4.0.5)
==================

* Fixed issue [#884](https://github.com/clean-css/clean-css/issues/884) - handling absolute paths on Windows.
* Fixed issue [#881](https://github.com/clean-css/clean-css/issues/881) - incorrect `require` arity.
* Fixed issue [#880](https://github.com/clean-css/clean-css/issues/880) - incorrect token type identification.

[4.0.4 / 2017-02-04](https://github.com/clean-css/clean-css/compare/v4.0.3...v4.0.4)
==================

* Fixed issue [#879](https://github.com/clean-css/clean-css/issues/879) - incorrect handling of spaces in paths.
* Fixed issue [#878](https://github.com/clean-css/clean-css/issues/878) - invalid double backslash tokenization.

[4.0.3 / 2017-01-30](https://github.com/clean-css/clean-css/compare/v4.0.2...v4.0.3)
==================

* Fixed issue [#875](https://github.com/clean-css/clean-css/issues/875) - invalid traversing in semantic merging.

[4.0.2 / 2017-01-26](https://github.com/clean-css/clean-css/compare/v4.0.1...v4.0.2)
==================

* Fixed issue [#874](https://github.com/clean-css/clean-css/issues/874) - regression in at-rule tokenization.

[4.0.1 / 2017-01-25](https://github.com/clean-css/clean-css/compare/v4.0.0...v4.0.1)
==================

* Fixed issue [#866](https://github.com/clean-css/clean-css/issues/866) - edge case in `inline` option.
* Fixed issue [#867](https://github.com/clean-css/clean-css/issues/867) - skip optimizing variable values.
* Fixed issue [#868](https://github.com/clean-css/clean-css/issues/868) - accept absolute paths in input hash.
* Fixed issue [#872](https://github.com/clean-css/clean-css/issues/872) - edge case in CSS tokenization.

[4.0.0 / 2017-01-23](https://github.com/clean-css/clean-css/compare/v3.4.24...v4.0.0)
==================

* Adds more detailed error & warning messages on top of the new tokenizer.
* Disables restructuring optimizations by default until optimized in #533.
* Fixes a bug ignoring incorrect properties in complex restructuring.
* Requires Node.js 4.0+ to run.
* Removes `benchmark` API option as total time is always reported under `stats` property.
* Removes `debug` API switch as stats are always gathered and available under `stats` property.
* Replaces the old tokenizer with a new one which doesn't use any escaping.
* Replaces the old `@import` inlining with one on top of the new tokenizer.
* Re-enables `background-(clip|origin|size)` merging with `background` shorthand.
* Simplifies URL rebasing with a single `rebaseTo` option in API or inferred from `--output` in CLI.
* Splits `inliner` option into `inlineRequest` and `inlineTimeout`.
* Fixed issue [#209](https://github.com/clean-css/clean-css/issues/209) - adds output formatting via `format` flag.
* Fixed issue [#290](https://github.com/clean-css/clean-css/issues/290) - removes aggressive merging.
* Fixed issue [#432](https://github.com/clean-css/clean-css/issues/432) - adds URLs normalization.
* Fixed issue [#460](https://github.com/clean-css/clean-css/issues/460) - unescaped semicolon in selector.
* Fixed issue [#657](https://github.com/clean-css/clean-css/issues/657) - adds property name validation.
* Fixed issue [#685](https://github.com/clean-css/clean-css/issues/685) - adds lowercasing hex colors optimization.
* Fixed issue [#686](https://github.com/clean-css/clean-css/issues/686) - adds rounding precision for all units.
* Fixed issue [#703](https://github.com/clean-css/clean-css/issues/703) - changes default IE compatibility to 10+.
* Fixed issue [#731](https://github.com/clean-css/clean-css/issues/731) - adds granular control over level 2 optimizations.
* Fixed issue [#739](https://github.com/clean-css/clean-css/issues/739) - error when a closing brace is missing.
* Fixed issue [#750](https://github.com/clean-css/clean-css/issues/750) - allows `width` overriding.
* Fixed issue [#756](https://github.com/clean-css/clean-css/issues/756) - adds disabling font-weight optimizations.
* Fixed issue [#758](https://github.com/clean-css/clean-css/issues/758) - ignores rules with empty selector.
* Fixed issue [#767](https://github.com/clean-css/clean-css/issues/767) - disables remote `@import` inlining by default.
* Fixed issue [#773](https://github.com/clean-css/clean-css/issues/773) - adds reordering based on selector specificity.
* Fixed issue [#785](https://github.com/clean-css/clean-css/issues/785) - adds `@font-face` de-duplication.
* Fixed issue [#791](https://github.com/clean-css/clean-css/issues/791) - resolves imports in-memory if possible.
* Fixed issue [#796](https://github.com/clean-css/clean-css/issues/796) - semantic merging for `@media` blocks.
* Fixed issue [#801](https://github.com/clean-css/clean-css/issues/801) - smarter `@import` inlining.
* Fixed issue [#806](https://github.com/clean-css/clean-css/issues/806) - skip optimizing variable properties.
* Fixed issue [#817](https://github.com/clean-css/clean-css/issues/817) - makes `off` disable rounding.
* Fixed issue [#818](https://github.com/clean-css/clean-css/issues/818) - disables `px` rounding by default.
* Fixed issue [#828](https://github.com/clean-css/clean-css/issues/828) - `-chrome-` hack support.
* Fixed issue [#829](https://github.com/clean-css/clean-css/issues/829) - adds more strict selector merging rules.
* Fixed issue [#834](https://github.com/clean-css/clean-css/issues/834) - adds extra line break in nested blocks.
* Fixed issue [#836](https://github.com/clean-css/clean-css/issues/836) - enables level `0` optimizations.
* Fixed issue [#839](https://github.com/clean-css/clean-css/issues/839) - allows URIs in import inlining rules.
* Fixed issue [#840](https://github.com/clean-css/clean-css/issues/840) - allows input source map as map object.
* Fixed issue [#843](https://github.com/clean-css/clean-css/issues/843) - regression in selector handling.
* Fixed issue [#845](https://github.com/clean-css/clean-css/issues/845) - web compatibility of 4.0 branch.
* Fixed issue [#847](https://github.com/clean-css/clean-css/issues/847) - regression in handling invalid selectors.
* Fixed issue [#849](https://github.com/clean-css/clean-css/issues/849) - disables inlining protocol-less resources.
* Fixed issue [#856](https://github.com/clean-css/clean-css/issues/856) - allows `minify` to return a promise.
* Fixed issue [#857](https://github.com/clean-css/clean-css/issues/857) - normalizes CleanCSS API interface.
* Fixed issue [#863](https://github.com/clean-css/clean-css/issues/863) - adds `transform` callback for custom optimizations.

[3.4.26 / 2017-05-10](https://github.com/clean-css/clean-css/compare/v3.4.25...v3.4.26)
==================

* Backports [#939](https://github.com/clean-css/clean-css/issues/939) - semicolon after `@apply` at-rule.

[3.4.25 / 2017-02-22](https://github.com/clean-css/clean-css/compare/v3.4.24...v3.4.25)
==================

* Fixed issue [#897](https://github.com/clean-css/clean-css/issues/897) - tokenization with escaped markers.

[3.4.24 / 2017-01-20](https://github.com/clean-css/clean-css/compare/v3.4.23...v3.4.24)
==================

* Fixed issue [#859](https://github.com/clean-css/clean-css/issues/859) - avoid `-webkit-border-radius` optimizations.

[3.4.23 / 2016-12-17](https://github.com/clean-css/clean-css/compare/v3.4.22...v3.4.23)
==================

* Fixed issue [#844](https://github.com/clean-css/clean-css/issues/844) - regression in property values extraction.

[3.4.22 / 2016-12-12](https://github.com/clean-css/clean-css/compare/v3.4.21...v3.4.22)
==================

* Fixed issue [#841](https://github.com/clean-css/clean-css/issues/841) - disabled importing and files passed as array.
* Ignores `@import` at-rules if appearing after any non-`@import` rules.

[3.4.21 / 2016-11-16](https://github.com/clean-css/clean-css/compare/v3.4.20...v3.4.21)
==================

* Fixed issue [#821](https://github.com/clean-css/clean-css/issues/821) - reducing non-adjacent rules.
* Fixed issue [#830](https://github.com/clean-css/clean-css/issues/830) - reordering border-* properties.
* Fixed issue [#833](https://github.com/clean-css/clean-css/issues/833) - moving `@media` queries.

[3.4.20 / 2016-09-26](https://github.com/clean-css/clean-css/compare/v3.4.19...v3.4.20)
==================

* Fixed issue [#814](https://github.com/clean-css/clean-css/issues/814) - `:selection` rule merging.

[3.4.19 / 2016-07-25](https://github.com/clean-css/clean-css/compare/v3.4.18...v3.4.19)
==================

* Fixed issue [#795](https://github.com/clean-css/clean-css/issues/795) - `!important` and override compacting.

[3.4.18 / 2016-06-15](https://github.com/clean-css/clean-css/compare/v3.4.17...v3.4.18)
==================

* Fixed issue [#787](https://github.com/clean-css/clean-css/issues/787) - regression in processing data URIs.

[3.4.17 / 2016-06-04](https://github.com/clean-css/clean-css/compare/v3.4.16...v3.4.17)
==================

* Fixed issue [#783](https://github.com/clean-css/clean-css/issues/783) - regression in processing data URIs.

[3.4.16 / 2016-06-02](https://github.com/clean-css/clean-css/compare/v3.4.15...v3.4.16)
==================

* Fixed issue [#781](https://github.com/clean-css/clean-css/issues/781) - regression in override compacting.
* Fixed issue [#782](https://github.com/clean-css/clean-css/issues/782) - regression in processing data URIs.

[3.4.15 / 2016-06-01](https://github.com/clean-css/clean-css/compare/v3.4.14...v3.4.15)
==================

* Fixed issue [#776](https://github.com/clean-css/clean-css/issues/776) - edge case in quoted data URIs.
* Fixed issue [#779](https://github.com/clean-css/clean-css/issues/779) - merging `background-(position|size)`.
* Fixed issue [#780](https://github.com/clean-css/clean-css/issues/780) - space after inlined variables.

[3.4.14 / 2016-05-31](https://github.com/clean-css/clean-css/compare/v3.4.13...v3.4.14)
==================

* Fixed issue [#751](https://github.com/clean-css/clean-css/issues/751) - stringifying CSS variables.
* Fixed issue [#763](https://github.com/clean-css/clean-css/issues/763) - data URI SVG and quoting.
* Fixed issue [#765](https://github.com/clean-css/clean-css/issues/765) - two values of border-radius.
* Fixed issue [#768](https://github.com/clean-css/clean-css/issues/768) - invalid border-radius property.

[3.4.13 / 2016-05-23](https://github.com/clean-css/clean-css/compare/v3.4.12...v3.4.13)
==================

* Fixed issue [#734](https://github.com/clean-css/clean-css/issues/769) - Node.js 6.x support.

[3.4.12 / 2016-04-09](https://github.com/clean-css/clean-css/compare/v3.4.11...v3.4.12)
==================

* Fixed issue [#734](https://github.com/clean-css/clean-css/issues/734) - `--root` option edge case.
* Fixed issue [#758](https://github.com/clean-css/clean-css/issues/758) - treats empty rule as unmergeable.

[3.4.11 / 2016-04-01](https://github.com/clean-css/clean-css/compare/v3.4.10...v3.4.11)
==================

* Fixed issue [#738](https://github.com/clean-css/clean-css/issues/738) - edge case in comment processing.
* Fixed issue [#741](https://github.com/clean-css/clean-css/issues/741) - HTTP proxy with HTTPS inlining.
* Fixed issue [#743](https://github.com/clean-css/clean-css/issues/743) - background shorthand and source maps.
* Fixed issue [#745](https://github.com/clean-css/clean-css/issues/745) - matching mixed case `!important`.

[3.4.10 / 2016-02-29](https://github.com/clean-css/clean-css/compare/v3.4.9...v3.4.10)
==================

* Fixed issue [#735](https://github.com/clean-css/clean-css/issues/735) - whitespace removal with escaped chars.

[3.4.9 / 2016-01-03](https://github.com/clean-css/clean-css/compare/v3.4.8...v3.4.9)
==================

* Sped up merging by body advanced optimization.
* Fixed issue [#693](https://github.com/clean-css/clean-css/issues/693) - restructuring edge case.
* Fixed issue [#711](https://github.com/clean-css/clean-css/issues/711) - border fuzzy matching.
* Fixed issue [#714](https://github.com/clean-css/clean-css/issues/714) - stringifying property level at rules.
* Fixed issue [#715](https://github.com/clean-css/clean-css/issues/715) - stack too deep in comment scan.

[3.4.8 / 2015-11-13](https://github.com/clean-css/clean-css/compare/v3.4.7...v3.4.8)
==================

* Fixed issue [#676](https://github.com/clean-css/clean-css/issues/676) - fuzzy matching unqoted data URIs.

[3.4.7 / 2015-11-10](https://github.com/clean-css/clean-css/compare/v3.4.6...v3.4.7)
==================

* Fixed issue [#692](https://github.com/clean-css/clean-css/issues/692) - edge case in URL quoting.
* Fixed issue [#695](https://github.com/clean-css/clean-css/issues/695) - shorthand overriding edge case.
* Fixed issue [#699](https://github.com/clean-css/clean-css/issues/699) - IE9 transparent hack.
* Fixed issue [#701](https://github.com/clean-css/clean-css/issues/701) - `url` quoting with hash arguments.

[3.4.6 / 2015-10-14](https://github.com/clean-css/clean-css/compare/v3.4.5...v3.4.6)
==================

* Fixed issue [#679](https://github.com/clean-css/clean-css/issues/679) - wrong rebasing of remote URLs.

[3.4.5 / 2015-09-28](https://github.com/clean-css/clean-css/compare/v3.4.4...v3.4.5)
==================

* Fixed issue [#681](https://github.com/clean-css/clean-css/issues/681) - property inheritance & restructuring.
* Fixed issue [#675](https://github.com/clean-css/clean-css/issues/675) - overriding with `!important`.

[3.4.4 / 2015-09-21](https://github.com/clean-css/clean-css/compare/v3.4.3...v3.4.4)
==================

* Fixed issue [#626](https://github.com/clean-css/clean-css/issues/626) - edge case in import rebasing.
* Fixed issue [#674](https://github.com/clean-css/clean-css/issues/674) - adjacent merging order.

[3.4.3 / 2015-09-15](https://github.com/clean-css/clean-css/compare/v3.4.2...v3.4.3)
==================

* Fixed issue [#668](https://github.com/clean-css/clean-css/issues/668) - node v4 path.join.
* Fixed issue [#669](https://github.com/clean-css/clean-css/issues/669) - adjacent overriding with `!important`.

[3.4.2 / 2015-09-14](https://github.com/clean-css/clean-css/compare/v3.4.1...v3.4.2)
==================

* Fixed issue [#598](https://github.com/clean-css/clean-css/issues/598) - restructuring border properties.
* Fixed issue [#654](https://github.com/clean-css/clean-css/issues/654) - disables length optimizations.
* Fixed issue [#655](https://github.com/clean-css/clean-css/issues/655) - shorthands override merging.
* Fixed issue [#660](https://github.com/clean-css/clean-css/issues/660) - !important token overriding.
* Fixed issue [#662](https://github.com/clean-css/clean-css/issues/662) - !important selector reducing.
* Fixed issue [#667](https://github.com/clean-css/clean-css/issues/667) - rebasing remote URLs.

[3.4.1 / 2015-08-27](https://github.com/clean-css/clean-css/compare/v3.4.0...v3.4.1)
==================

* Fixed issue [#652](https://github.com/clean-css/clean-css/issues/652) - order of restoring and removing tokens.

[3.4.0 / 2015-08-27](https://github.com/clean-css/clean-css/compare/v3.3.10...v3.4.0)
==================

* Adds an option for a fine-grained `@import` control.
* Adds unit compatibility switches to disable length optimizations.
* Adds inferring proxy settings from HTTP_PROXY environment variable.
* Adds support for Polymer / Web Components special selectors.
* Adds support for Polymer mixins.
* Adds testing source maps in batch mode.
* Unifies wrappers for simple & advanced optimizations.
* Fixed issue [#596](https://github.com/clean-css/clean-css/issues/596) - support for !ie IE<8 hack.
* Fixed issue [#599](https://github.com/clean-css/clean-css/issues/599) - support for inlined source maps.
* Fixed issue [#607](https://github.com/clean-css/clean-css/issues/607) - adds better rule reordering.
* Fixed issue [#612](https://github.com/clean-css/clean-css/issues/612) - adds HTTP proxy support.
* Fixed issue [#618](https://github.com/clean-css/clean-css/issues/618) - adds safer function validation.
* Fixed issue [#625](https://github.com/clean-css/clean-css/issues/625) - adds length unit optimizations.
* Fixed issue [#632](https://github.com/clean-css/clean-css/issues/632) - adds disabling remote `import`s.
* Fixed issue [#635](https://github.com/clean-css/clean-css/issues/635) - adds safer `0%` optimizations.
* Fixed issue [#644](https://github.com/clean-css/clean-css/issues/644) - adds time unit optimizations.
* Fixed issue [#645](https://github.com/clean-css/clean-css/issues/645) - adds bottom to top `media` merging.
* Fixed issue [#648](https://github.com/clean-css/clean-css/issues/648) - adds property level at-rule support.

[3.3.10 / 2015-08-27](https://github.com/clean-css/clean-css/compare/v3.3.9...v3.3.10)
==================

* Adds better comments + keepBreaks handling.
* Adds better text normalizing in source maps mode.
* Fixes non-adjacent optimizations for source maps.
* Fixes removing unused items.
* Improves `outline` break up with source maps.
* Refixed issue [#629](https://github.com/clean-css/clean-css/issues/629) - source maps & background shorthands.

[3.3.9 / 2015-08-09](https://github.com/clean-css/clean-css/compare/v3.3.8...v3.3.9)
==================

* Fixed issue [#640](https://github.com/clean-css/clean-css/issues/640) - URI processing regression.

[3.3.8 / 2015-08-06](https://github.com/clean-css/clean-css/compare/v3.3.7...v3.3.8)
==================

* Fixed issue [#629](https://github.com/clean-css/clean-css/issues/629) - source maps & background shorthands.
* Fixed issue [#630](https://github.com/clean-css/clean-css/issues/630) - vendor prefixed flex optimizations.
* Fixed issue [#633](https://github.com/clean-css/clean-css/issues/633) - handling data URI with brackets.
* Fixed issue [#634](https://github.com/clean-css/clean-css/issues/634) - merging :placeholder selectors.

[3.3.7 / 2015-07-29](https://github.com/clean-css/clean-css/compare/v3.3.6...v3.3.7)
==================

* Fixed issue [#616](https://github.com/clean-css/clean-css/issues/616) - ordering in restructuring.

[3.3.6 / 2015-07-14](https://github.com/clean-css/clean-css/compare/v3.3.5...v3.3.6)
==================

* Fixed issue [#620](https://github.com/clean-css/clean-css/issues/620) - `bold` style in font shorthands.

[3.3.5 / 2015-07-01](https://github.com/clean-css/clean-css/compare/v3.3.4...v3.3.5)
==================

* Fixed issue [#608](https://github.com/clean-css/clean-css/issues/608) - custom URI protocols handling.

[3.3.4 / 2015-06-24](https://github.com/clean-css/clean-css/compare/v3.3.3...v3.3.4)
==================

* Fixed issue [#610](https://github.com/clean-css/clean-css/issues/610) - `border:inherit` restoring.
* Fixed issue [#611](https://github.com/clean-css/clean-css/issues/611) - edge case in quote stripping.

[3.3.3 / 2015-06-16](https://github.com/clean-css/clean-css/compare/v3.3.2...v3.3.3)
==================

* Fixed issue [#603](https://github.com/clean-css/clean-css/issues/603) - IE suffix hack defaults to on.

[3.3.2 / 2015-06-14](https://github.com/clean-css/clean-css/compare/v3.3.1...v3.3.2)
==================

* Fixed issue [#595](https://github.com/clean-css/clean-css/issues/595) - more relaxed block matching.
* Fixed issue [#601](https://github.com/clean-css/clean-css/issues/601) - percentage minifying inside `flex`.
* Fixed issue [#602](https://github.com/clean-css/clean-css/issues/602) - backslash IE hacks after a space.

[3.3.1 / 2015-06-02](https://github.com/clean-css/clean-css/compare/v3.3.0...v3.3.1)
==================

* Fixed issue [#590](https://github.com/clean-css/clean-css/issues/590) - edge case in `@import` processing.

[3.3.0 / 2015-05-31](https://github.com/clean-css/clean-css/compare/v3.2.11...v3.3.0)
==================

* Cleans up url rebase code getting rid of unnecessary state.
* Cleans up tokenizer code getting rid of unnecessary state.
* Moves source maps tracker into lib/source-maps/track.
* Moves tokenizer code into lib/tokenizer.
* Moves URL scanner into lib/urls/reduce (was named incorrectly before).
* Moves URL rebasing & rewriting into lib/urls.
* Fixed issue [#375](https://github.com/clean-css/clean-css/issues/375) - unit compatibility switches.
* Fixed issue [#436](https://github.com/clean-css/clean-css/issues/436) - refactors URI rewriting.
* Fixed issue [#448](https://github.com/clean-css/clean-css/issues/448) - rebasing no protocol URIs.
* Fixed issue [#517](https://github.com/clean-css/clean-css/issues/517) - turning off color optimizations.
* Fixed issue [#542](https://github.com/clean-css/clean-css/issues/542) - space after closing brace in IE.
* Fixed issue [#562](https://github.com/clean-css/clean-css/issues/562) - optimizing invalid color values.
* Fixed issue [#563](https://github.com/clean-css/clean-css/issues/563) - `background:inherit` restoring.
* Fixed issue [#570](https://github.com/clean-css/clean-css/issues/570) - rebasing "no-url()" imports.
* Fixed issue [#574](https://github.com/clean-css/clean-css/issues/574) - rewriting internal URLs.
* Fixed issue [#575](https://github.com/clean-css/clean-css/issues/575) - missing directory as a `target`.
* Fixed issue [#577](https://github.com/clean-css/clean-css/issues/577) - `background-clip` into shorthand.
* Fixed issue [#579](https://github.com/clean-css/clean-css/issues/579) - `background-origin` into shorthand.
* Fixed issue [#580](https://github.com/clean-css/clean-css/issues/580) - mixed `@import` processing.
* Fixed issue [#582](https://github.com/clean-css/clean-css/issues/582) - overriding with prefixed values.
* Fixed issue [#583](https://github.com/clean-css/clean-css/issues/583) - URL quoting for SVG data.
* Fixed issue [#587](https://github.com/clean-css/clean-css/issues/587) - too aggressive `border` reordering.

[3.2.11 / 2015-05-31](https://github.com/clean-css/clean-css/compare/v3.2.10...v3.2.11)
==================

* Fixed issue [#563](https://github.com/clean-css/clean-css/issues/563) - `background:inherit` restoring.
* Fixed issue [#582](https://github.com/clean-css/clean-css/issues/582) - overriding with prefixed values.
* Fixed issue [#583](https://github.com/clean-css/clean-css/issues/583) - URL quoting for SVG data.
* Fixed issue [#587](https://github.com/clean-css/clean-css/issues/587) - too aggressive `border` reordering.

[3.2.10 / 2015-05-14](https://github.com/clean-css/clean-css/compare/v3.2.9...v3.2.10)
==================

* Fixed issue [#572](https://github.com/clean-css/clean-css/issues/572) - empty elements removal.

[3.2.9 / 2015-05-08](https://github.com/clean-css/clean-css/compare/v3.2.8...v3.2.9)
==================

* Fixed issue [#567](https://github.com/clean-css/clean-css/issues/567) - merging colors as functions.

[3.2.8 / 2015-05-04](https://github.com/clean-css/clean-css/compare/v3.2.7...v3.2.8)
==================

* Fixed issue [#561](https://github.com/clean-css/clean-css/issues/561) - restructuring special selectors.

[3.2.7 / 2015-05-03](https://github.com/clean-css/clean-css/compare/v3.2.6...v3.2.7)
==================

* Fixed issue [#551](https://github.com/clean-css/clean-css/issues/551) - edge case in restructuring.
* Fixed issue [#553](https://github.com/clean-css/clean-css/issues/553) - another style of SVG fallback.
* Fixed issue [#558](https://github.com/clean-css/clean-css/issues/558) - units in same selector merging.

[3.2.6 / 2015-04-28](https://github.com/clean-css/clean-css/compare/v3.2.5...v3.2.6)
==================

* Fixed issue [#550](https://github.com/clean-css/clean-css/issues/550) - proper `contentSources` tracking.
* Fixed issue [#556](https://github.com/clean-css/clean-css/issues/556) - regression in IE backslash hacks.

[3.2.5 / 2015-04-25](https://github.com/clean-css/clean-css/compare/v3.2.4...v3.2.5)
==================

* Fixed issue [#543](https://github.com/clean-css/clean-css/issues/543) - better "comment in body" handling.
* Fixed issue [#548](https://github.com/clean-css/clean-css/issues/548) - regression in font minifying.
* Fixed issue [#549](https://github.com/clean-css/clean-css/issues/549) - special comments in source maps.

[3.2.4 / 2015-04-24](https://github.com/clean-css/clean-css/compare/v3.2.3...v3.2.4)
==================

* Fixed issue [#544](https://github.com/clean-css/clean-css/issues/544) - regression in same value merging.
* Fixed issue [#546](https://github.com/clean-css/clean-css/issues/546) - IE<11 `calc()` issue.

[3.2.3 / 2015-04-22](https://github.com/clean-css/clean-css/compare/v3.2.2...v3.2.3)
==================

* Fixed issue [#541](https://github.com/clean-css/clean-css/issues/541) - `outline-style:auto` in shorthand.

[3.2.2 / 2015-04-21](https://github.com/clean-css/clean-css/compare/v3.2.1...v3.2.2)
==================

* Fixed issue [#537](https://github.com/clean-css/clean-css/issues/537) - regression in simple optimizer.

[3.2.1 / 2015-04-20](https://github.com/clean-css/clean-css/compare/v3.2.0...v3.2.1)
==================

* Fixed issue [#534](https://github.com/clean-css/clean-css/issues/534) - wrong `@font-face` stringifying.

[3.2.0 / 2015-04-19](https://github.com/clean-css/clean-css/compare/v3.1.9...v3.2.0)
==================

* Bumps commander to 2.8.x.
* Fixes remote asset rebasing when passing data as a hash.
* Improves path resolution inside source maps.
* Makes `root` option implicitely default to `process.cwd()`.
* Fixed issue [#371](https://github.com/clean-css/clean-css/issues/371) - `background` fallback with `none`.
* Fixed issue [#376](https://github.com/clean-css/clean-css/issues/376) - option to disable `0[unit]` -> `0`.
* Fixed issue [#396](https://github.com/clean-css/clean-css/issues/396) - better input source maps tracking.
* Fixed issue [#397](https://github.com/clean-css/clean-css/issues/397) - support for source map sources.
* Fixed issue [#399](https://github.com/clean-css/clean-css/issues/399) - support compacting with source maps.
* Fixed issue [#429](https://github.com/clean-css/clean-css/issues/429) - unifies data tokenization.
* Fixed issue [#446](https://github.com/clean-css/clean-css/issues/446) - `list-style` fuzzy matching.
* Fixed issue [#468](https://github.com/clean-css/clean-css/issues/468) - bumps `source-map` to 0.4.x.
* Fixed issue [#480](https://github.com/clean-css/clean-css/issues/480) - extracting uppercase property names.
* Fixed issue [#487](https://github.com/clean-css/clean-css/issues/487) - source map paths under Windows.
* Fixed issue [#490](https://github.com/clean-css/clean-css/issues/490) - vendor prefixed multivalue `background`.
* Fixed issue [#500](https://github.com/clean-css/clean-css/issues/500) - merging duplicate adjacent properties.
* Fixed issue [#504](https://github.com/clean-css/clean-css/issues/504) - keeping `url()` quotes.
* Fixed issue [#507](https://github.com/clean-css/clean-css/issues/507) - merging longhands into many shorthands.
* Fixed issue [#508](https://github.com/clean-css/clean-css/issues/508) - removing duplicate media queries.
* Fixed issue [#521](https://github.com/clean-css/clean-css/issues/521) - unit optimizations inside `calc()`.
* Fixed issue [#524](https://github.com/clean-css/clean-css/issues/524) - timeouts in `@import` inlining.
* Fixed issue [#526](https://github.com/clean-css/clean-css/issues/526) - shorthand overriding into a function.
* Fixed issue [#528](https://github.com/clean-css/clean-css/issues/528) - better support for IE<9 hacks.
* Fixed issue [#529](https://github.com/clean-css/clean-css/issues/529) - wrong font weight minification.

[3.1.9 / 2015-04-04](https://github.com/clean-css/clean-css/compare/v3.1.8...v3.1.9)
==================

* Fixes issue [#511](https://github.com/clean-css/clean-css/issues/511) - `)` advanced processing.

[3.1.8 / 2015-03-17](https://github.com/clean-css/clean-css/compare/v3.1.7...v3.1.8)
==================

* Fixes issue [#498](https://github.com/clean-css/clean-css/issues/498) - reordering and flexbox.
* Fixes issue [#499](https://github.com/clean-css/clean-css/issues/499) - too aggressive `-` removal.

[3.1.7 / 2015-03-16](https://github.com/clean-css/clean-css/compare/v3.1.6...v3.1.7)
==================

* Backports fix to [#480](https://github.com/clean-css/clean-css/issues/480) - reordering and uppercase properties.
* Fixes issue [#496](https://github.com/clean-css/clean-css/issues/496) - space after bracket removal.

[3.1.6 / 2015-03-12](https://github.com/clean-css/clean-css/compare/v3.1.5...v3.1.6)
==================

* Fixes issue [#489](https://github.com/clean-css/clean-css/issues/489) - `AlphaImageLoader` IE filter.

[3.1.5 / 2015-03-06](https://github.com/clean-css/clean-css/compare/v3.1.4...v3.1.5)
==================

* Fixes issue [#483](https://github.com/clean-css/clean-css/issues/483) - property order in restructuring.

[3.1.4 / 2015-03-04](https://github.com/clean-css/clean-css/compare/v3.1.3...v3.1.4)
==================

* Fixes issue [#472](https://github.com/clean-css/clean-css/issues/472) - broken function minification.
* Fixes issue [#477](https://github.com/clean-css/clean-css/issues/477) - `@import`s order in restructuring.
* Fixes issue [#478](https://github.com/clean-css/clean-css/issues/478) - ultimate fix to brace whitespace.

[3.1.3 / 2015-03-03](https://github.com/clean-css/clean-css/compare/v3.1.2...v3.1.3)
==================

* Fixes issue [#464](https://github.com/clean-css/clean-css/issues/464) - data URI with quoted braces.
* Fixes issue [#475](https://github.com/clean-css/clean-css/issues/475) - whitespace after closing brace.

[3.1.2 / 2015-03-01](https://github.com/clean-css/clean-css/compare/v3.1.1...v3.1.2)
==================

* Refixed issue [#471](https://github.com/clean-css/clean-css/issues/471) - correct order after restructuring.
* Fixes issue [#466](https://github.com/clean-css/clean-css/issues/466) - rebuilding background shorthand.
* Fixes issue [#462](https://github.com/clean-css/clean-css/issues/462) - escaped apostrophes in selectors.

[3.1.1 / 2015-02-27](https://github.com/clean-css/clean-css/compare/v3.1.0...v3.1.1)
==================

* Fixed issue [#469](https://github.com/clean-css/clean-css/issues/469) - extracting broken property.
* Fixed issue [#470](https://github.com/clean-css/clean-css/issues/470) - negative padding removal.
* Fixed issue [#471](https://github.com/clean-css/clean-css/issues/471) - correct order after restructuring.

[3.1.0 / 2015-02-26](https://github.com/clean-css/clean-css/compare/v3.0.10...v3.1.0)
==================

* Adds `0deg` to `0` minification where possible.
* Adds better non-adjacent selector merging when body is the same.
* Adds official support for node.js 0.12.
* Adds official support for io.js 1.0.
* Adds restructuring optimizations to reorganize selectors, which vastly improves minification.
* Fixed issue [#158](https://github.com/clean-css/clean-css/issues/158) - adds body-based selectors reduction.
* Fixed issue [#182](https://github.com/clean-css/clean-css/issues/182) - removing space after closing brace.
* Fixed issue [#204](https://github.com/clean-css/clean-css/issues/204) - `@media` merging.
* Fixed issue [#351](https://github.com/clean-css/clean-css/issues/351) - remote `@import`s after content.
* Fixed issue [#357](https://github.com/clean-css/clean-css/issues/357) - non-standard but valid URLs.
* Fixed issue [#416](https://github.com/clean-css/clean-css/issues/416) - accepts hash as `minify` argument.
* Fixed issue [#419](https://github.com/clean-css/clean-css/issues/419) - multiple input source maps.
* Fixed issue [#435](https://github.com/clean-css/clean-css/issues/435) - `background-clip` in shorthand.
* Fixed issue [#439](https://github.com/clean-css/clean-css/issues/439) - `background-origin` in shorthand.
* Fixed issue [#442](https://github.com/clean-css/clean-css/issues/442) - space before adjacent `nav`.
* Fixed issue [#445](https://github.com/clean-css/clean-css/issues/445) - regression issue in url processor.
* Fixed issue [#449](https://github.com/clean-css/clean-css/issues/449) - warns of missing close braces.
* Fixed issue [#463](https://github.com/clean-css/clean-css/issues/463) - relative remote `@import` URLs.

[3.0.10 / 2015-02-07](https://github.com/clean-css/clean-css/compare/v3.0.9...v3.0.10)
==================

* Fixed issue [#453](https://github.com/clean-css/clean-css/issues/453) - double `background-repeat`.
* Fixed issue [#455](https://github.com/clean-css/clean-css/issues/455) - property extracting regression.

[3.0.9 / 2015-02-04](https://github.com/clean-css/clean-css/compare/v3.0.8...v3.0.9)
==================

* Fixed issue [#452](https://github.com/clean-css/clean-css/issues/452) - regression in advanced merging.

[3.0.8 / 2015-01-31](https://github.com/clean-css/clean-css/compare/v3.0.7...v3.0.8)
==================

* Fixed issue [#447](https://github.com/clean-css/clean-css/issues/447) - `background-color` in shorthands.
* Fixed issue [#450](https://github.com/clean-css/clean-css/issues/450) - name to hex color converting.

[3.0.7 / 2015-01-22](https://github.com/clean-css/clean-css/compare/v3.0.6...v3.0.7)
==================

* Fixed issue [#441](https://github.com/clean-css/clean-css/issues/441) - hex to name color converting.

[3.0.6 / 2015-01-20](https://github.com/clean-css/clean-css/compare/v3.0.5...v3.0.6)
==================

* Refixed issue [#414](https://github.com/clean-css/clean-css/issues/414) - source maps position fallback.

[3.0.5 / 2015-01-18](https://github.com/clean-css/clean-css/compare/v3.0.4...v3.0.5)
==================

* Fixed issue [#414](https://github.com/clean-css/clean-css/issues/414) - source maps position fallback.
* Fixed issue [#433](https://github.com/clean-css/clean-css/issues/433) - meging `!important` in shorthands.

[3.0.4 / 2015-01-11](https://github.com/clean-css/clean-css/compare/v3.0.3...v3.0.4)
==================

* Fixed issue [#314](https://github.com/clean-css/clean-css/issues/314) - spaces inside `calc`.

[3.0.3 / 2015-01-07](https://github.com/clean-css/clean-css/compare/v3.0.2...v3.0.3)
==================

* Just a version bump as npm incorrectly things 2.2.23 is the latest one.

[3.0.2 / 2015-01-04](https://github.com/clean-css/clean-css/compare/v3.0.1...v3.0.2)
==================

* Fixed issue [#422](https://github.com/clean-css/clean-css/issues/422) - handling `calc` as a unit.

[3.0.1 / 2014-12-19](https://github.com/clean-css/clean-css/compare/v3.0.0...v3.0.1)
==================

* Fixed issue [#410](https://github.com/clean-css/clean-css/issues/410) - advanced merging and comments.
* Fixed issue [#411](https://github.com/clean-css/clean-css/issues/411) - properties and important comments.

[3.0.0 / 2014-12-18](https://github.com/clean-css/clean-css/compare/v2.2.22...v3.0.0)
==================

* Adds more granular control over compatibility settings.
* Adds support for @counter-style at-rule.
* Adds `--source-map`/`sourceMap` switch for building input's source map.
* Adds `--skip-shorthand-compacting`/`shorthandComacting` option for disabling shorthand compacting.
* Allows `target` option to be a path to a folder instead of a file.
* Allows disabling rounding precision. By [@superlukas](https://github.com/superlukas).
* Breaks 2.x compatibility for using CleanCSS as a function.
* Changes `minify` method output to handle multiple outputs.
* Reworks minification to tokenize first then minify.
  See [changes](https://github.com/clean-css/clean-css/compare/b06f37d...dd8c14a).
* Removes support for node.js 0.8.x.
* Renames `noAdvanced` option into `advanced`.
* Renames `noAggressiveMerging` option into `aggressiveMerging`.
* Renames `noRebase` option into `rebase`.
* Speeds up advanced processing by shortening optimize loop.
* Fixed issue [#125](https://github.com/clean-css/clean-css/issues/125) - source maps!
* Fixed issue [#344](https://github.com/clean-css/clean-css/issues/344) - merging `background-size` into shorthand.
* Fixed issue [#352](https://github.com/clean-css/clean-css/issues/352) - honors rebasing in imported stylesheets.
* Fixed issue [#360](https://github.com/clean-css/clean-css/issues/360) - adds 7 extra CSS colors.
* Fixed issue [#363](https://github.com/clean-css/clean-css/issues/363) - `rem` units overriding `px`.
* Fixed issue [#373](https://github.com/clean-css/clean-css/issues/373) - proper `background` shorthand merging.
* Fixed issue [#395](https://github.com/clean-css/clean-css/issues/395) - unescaped brackets in data URIs.
* Fixed issue [#398](https://github.com/clean-css/clean-css/issues/398) - restoring important comments.
* Fixed issue [#400](https://github.com/clean-css/clean-css/issues/400) - API to accept an array of filenames.
* Fixed issue [#403](https://github.com/clean-css/clean-css/issues/403) - tracking input files in source maps.
* Fixed issue [#404](https://github.com/clean-css/clean-css/issues/404) - no state sharing in API.
* Fixed issue [#405](https://github.com/clean-css/clean-css/issues/405) - disables default `background-size` merging.
* Refixed issue [#304](https://github.com/clean-css/clean-css/issues/304) - `background-position` merging.

[2.2.22 / 2014-12-13](https://github.com/clean-css/clean-css/compare/v2.2.21...v2.2.22)
==================

* Backports fix to issue [#304](https://github.com/clean-css/clean-css/issues/304) - `background-position` merging.

[2.2.21 / 2014-12-10](https://github.com/clean-css/clean-css/compare/v2.2.20...v2.2.21)
==================

* Backports fix to issue [#373](https://github.com/clean-css/clean-css/issues/373) - `background` shorthand merging.

[2.2.20 / 2014-12-02](https://github.com/clean-css/clean-css/compare/v2.2.19...v2.2.20)
==================

* Backports fix to issue [#390](https://github.com/clean-css/clean-css/issues/390) - pseudo-class merging.

[2.2.19 / 2014-11-20](https://github.com/clean-css/clean-css/compare/v2.2.18...v2.2.19)
==================

* Fixed issue [#385](https://github.com/clean-css/clean-css/issues/385) - edge cases in processing cut off data.

[2.2.18 / 2014-11-17](https://github.com/clean-css/clean-css/compare/v2.2.17...v2.2.18)
==================

* Fixed issue [#383](https://github.com/clean-css/clean-css/issues/383) - rounding fractions once again.

[2.2.17 / 2014-11-09](https://github.com/clean-css/clean-css/compare/v2.2.16...v2.2.17)
==================

* Fixed issue [#380](https://github.com/clean-css/clean-css/issues/380) - rounding fractions to a whole number.

[2.2.16 / 2014-09-16](https://github.com/clean-css/clean-css/compare/v2.2.15...v2.2.16)
==================

* Fixed issue [#359](https://github.com/clean-css/clean-css/issues/359) - handling escaped double backslash.
* Fixed issue [#358](https://github.com/clean-css/clean-css/issues/358) - property merging in compatibility mode.
* Fixed issue [#356](https://github.com/clean-css/clean-css/issues/356) - preserving `*+html` hack.
* Fixed issue [#354](https://github.com/clean-css/clean-css/issues/354) - `!important` overriding in shorthands.

[2.2.15 / 2014-09-01](https://github.com/clean-css/clean-css/compare/v2.2.14...v2.2.15)
==================

* Fixed issue [#343](https://github.com/clean-css/clean-css/issues/343) - too aggressive `rgba`/`hsla` minification.
* Fixed issue [#345](https://github.com/clean-css/clean-css/issues/345) - URL rebasing for document relative ones.
* Fixed issue [#346](https://github.com/clean-css/clean-css/issues/346) - overriding `!important` by `!important`.
* Fixed issue [#350](https://github.com/clean-css/clean-css/issues/350) - edge cases in `@import` processing.

[2.2.14 / 2014-08-25](https://github.com/clean-css/clean-css/compare/v2.2.13...v2.2.14)
==================

* Makes multival operations idempotent.
* Fixed issue [#339](https://github.com/clean-css/clean-css/issues/339) - skips invalid properties.
* Fixed issue [#341](https://github.com/clean-css/clean-css/issues/341) - ensure output is shorter than input.

[2.2.13 / 2014-08-12](https://github.com/clean-css/clean-css/compare/v2.2.12...v2.2.13)
==================

* Fixed issue [#337](https://github.com/clean-css/clean-css/issues/337) - handling component importance.

[2.2.12 / 2014-08-02](https://github.com/clean-css/clean-css/compare/v2.2.11...v2.2.12)
==================

* Fixed issue with tokenizer removing first selector after an unknown @ rule.
* Fixed issue [#329](https://github.com/clean-css/clean-css/issues/329) - `font` shorthands incorrectly processed.
* Fixed issue [#332](https://github.com/clean-css/clean-css/issues/332) - `background` shorthand with colors.
* Refixed issue [#325](https://github.com/clean-css/clean-css/issues/325) - invalid charset declarations.

[2.2.11 / 2014-07-28](https://github.com/clean-css/clean-css/compare/v2.2.10...v2.2.11)
==================

* Fixed issue [#326](https://github.com/clean-css/clean-css/issues/326) - `background-size` regression.

[2.2.10 / 2014-07-27](https://github.com/clean-css/clean-css/compare/v2.2.9...v2.2.10)
==================

* Improved performance of advanced mode validators.
* Fixed issue [#307](https://github.com/clean-css/clean-css/issues/307) - `background-color` in multiple backgrounds.
* Fixed issue [#322](https://github.com/clean-css/clean-css/issues/322) - adds `background-size` support.
* Fixed issue [#323](https://github.com/clean-css/clean-css/issues/323) - stripping variable references.
* Fixed issue [#325](https://github.com/clean-css/clean-css/issues/325) - removing invalid `@charset` declarations.

[2.2.9 / 2014-07-23](https://github.com/clean-css/clean-css/compare/v2.2.8...v2.2.9)
==================

* Adds `background` normalization according to W3C spec.
* Fixed issue [#316](https://github.com/clean-css/clean-css/issues/316) - incorrect `background` processing.

[2.2.8 / 2014-07-14](https://github.com/clean-css/clean-css/compare/v2.2.7...v2.2.8)
==================

* Fixed issue [#313](https://github.com/clean-css/clean-css/issues/313) - processing comment marks in URLs.
* Fixed issue [#315](https://github.com/clean-css/clean-css/issues/315) - `rgba`/`hsla` -> `transparent` in gradients.

[2.2.7 / 2014-07-10](https://github.com/clean-css/clean-css/compare/v2.2.6...v2.2.7)
==================

* Fixed issue [#304](https://github.com/clean-css/clean-css/issues/304) - merging multiple backgrounds.
* Fixed issue [#312](https://github.com/clean-css/clean-css/issues/312) - merging with mixed repeat.

[2.2.6 / 2014-07-05](https://github.com/clean-css/clean-css/compare/v2.2.5...v2.2.6)
==================

* Adds faster quote matching in QuoteScanner.
* Improves QuoteScanner to handle comments correctly.
* Fixed issue [#308](https://github.com/clean-css/clean-css/issues/308) - parsing comments in quoted URLs.
* Fixed issue [#311](https://github.com/clean-css/clean-css/issues/311) - leading/trailing decimal points.

[2.2.5 / 2014-06-29](https://github.com/clean-css/clean-css/compare/v2.2.4...v2.2.5)
==================

* Adds removing extra spaces around / in border-radius.
* Adds replacing same horizontal & vertical value in border-radius.
* Fixed issue [#305](https://github.com/clean-css/clean-css/issues/305) - allows width keywords in `border-width`.

[2.2.4 / 2014-06-27](https://github.com/clean-css/clean-css/compare/v2.2.3...v2.2.4)
==================

* Fixed issue [#301](https://github.com/clean-css/clean-css/issues/301) - proper `border-radius` processing.
* Fixed issue [#303](https://github.com/clean-css/clean-css/issues/303) - correctly preserves viewport units.

[2.2.3 / 2014-06-24](https://github.com/clean-css/clean-css/compare/v2.2.2...v2.2.3)
==================

* Fixed issue [#302](https://github.com/clean-css/clean-css/issues/302) - handling of `outline-style: auto`.

[2.2.2 / 2014-06-18](https://github.com/clean-css/clean-css/compare/v2.2.1...v2.2.2)
==================

* Fixed issue [#297](https://github.com/clean-css/clean-css/issues/297) - `box-shadow` zeros minification.

[2.2.1 / 2014-06-14](https://github.com/clean-css/clean-css/compare/v2.2.0...v2.2.1)
==================

* Fixes new property optimizer for 'none' values.
* Fixed issue [#294](https://github.com/clean-css/clean-css/issues/294) - space after `rgba`/`hsla` in IE<=11.

[2.2.0 / 2014-06-11](https://github.com/clean-css/clean-css/compare/v2.1.8...v2.2.0)
==================

* Adds a better algorithm for quotation marks' removal.
* Adds a better non-adjacent optimizer compatible with the upcoming new property optimizer.
* Adds minifying remote files directly from CLI.
* Adds `--rounding-precision` to control rounding precision.
* Moves quotation matching into a `QuoteScanner` class.
* Adds `npm run browserify` for creating embeddable version of clean-css.
* Fixed list-style-* advanced processing.
* Fixed issue [#134](https://github.com/clean-css/clean-css/issues/134) - merges properties into shorthand form.
* Fixed issue [#164](https://github.com/clean-css/clean-css/issues/164) - removes default values if not needed.
* Fixed issue [#168](https://github.com/clean-css/clean-css/issues/168) - adds better property merging algorithm.
* Fixed issue [#173](https://github.com/clean-css/clean-css/issues/173) - merges same properties if grouped.
* Fixed issue [#184](https://github.com/clean-css/clean-css/issues/184) - uses `!important` for optimization opportunities.
* Fixed issue [#190](https://github.com/clean-css/clean-css/issues/190) - uses shorthand to override another shorthand.
* Fixed issue [#197](https://github.com/clean-css/clean-css/issues/197) - adds borders merging by understandability.
* Fixed issue [#210](https://github.com/clean-css/clean-css/issues/210) - adds temporary workaround for aggressive merging.
* Fixed issue [#246](https://github.com/clean-css/clean-css/issues/246) - removes IE hacks when not in compatibility mode.
* Fixed issue [#247](https://github.com/clean-css/clean-css/issues/247) - removes deprecated `selectorsMergeMode` switch.
* Refixed issue [#250](https://github.com/clean-css/clean-css/issues/250) - based on new quotation marks removal.
* Fixed issue [#257](https://github.com/clean-css/clean-css/issues/257) - turns `rgba`/`hsla` to `transparent` if possible.
* Fixed issue [#265](https://github.com/clean-css/clean-css/issues/265) - adds support for multiple input files.
* Fixed issue [#275](https://github.com/clean-css/clean-css/issues/275) - handling transform properties.
* Fixed issue [#276](https://github.com/clean-css/clean-css/issues/276) - corrects unicode handling.
* Fixed issue [#288](https://github.com/clean-css/clean-css/issues/288) - adds smarter expression parsing.
* Fixed issue [#293](https://github.com/clean-css/clean-css/issues/293) - handles escaped `@` symbols in class names and IDs.

[2.1.8 / 2014-03-28](https://github.com/clean-css/clean-css/compare/v2.1.7...v2.1.8)
==================

* Fixed issue [#267](https://github.com/clean-css/clean-css/issues/267) - incorrect non-adjacent selector merging.

[2.1.7 / 2014-03-24](https://github.com/clean-css/clean-css/compare/v2.1.6...v2.1.7)
==================

* Fixed issue [#264](https://github.com/clean-css/clean-css/issues/264) - `@import` statements inside comments.

[2.1.6 / 2014-03-10](https://github.com/clean-css/clean-css/compare/v2.1.5...v2.1.6)
==================

* Fixed issue [#258](https://github.com/clean-css/clean-css/issues/258) - wrong `@import` handling in `EmptyRemoval`.

[2.1.5 / 2014-03-07](https://github.com/clean-css/clean-css/compare/v2.1.4...v2.1.5)
==================

* Fixed issue [#255](https://github.com/clean-css/clean-css/issues/255) - incorrect processing of a trailing `-0`.

[2.1.4 / 2014-03-01](https://github.com/clean-css/clean-css/compare/v2.1.3...v2.1.4)
==================

* Fixed issue [#250](https://github.com/clean-css/clean-css/issues/250) - correctly handle JSON data in quotations.

[2.1.3 / 2014-02-26](https://github.com/clean-css/clean-css/compare/v2.1.2...v2.1.3)
==================

* Fixed issue [#248](https://github.com/clean-css/clean-css/issues/248) - incorrect merging for vendor selectors.

[2.1.2 / 2014-02-25](https://github.com/clean-css/clean-css/compare/v2.1.1...v2.1.2)
==================

* Fixed issue [#245](https://github.com/clean-css/clean-css/issues/245) - incorrect handling of backslash IE hack.

[2.1.1 / 2014-02-18](https://github.com/clean-css/clean-css/compare/v2.1.0...v2.1.1)
==================

* Adds faster selectors processing in advanced optimizer.
* Fixed issue [#241](https://github.com/clean-css/clean-css/issues/241) - incorrect handling of `:not()` selectors.

[2.1.0 / 2014-02-13](https://github.com/clean-css/clean-css/compare/v2.0.8...v2.1.0)
==================

* Adds an optional callback to minify method.
* Deprecates `--selectors-merge-mode` / `selectorsMergeMode` in favor to `--compatibility` / `compatibility`.
* Fixes debug mode stats for stylesheets using `@import` statements.
* Skips empty removal if advanced processing is enabled.
* Fixed issue [#85](https://github.com/clean-css/clean-css/issues/85) - resolving protocol `@import`s.
* Fixed issue [#160](https://github.com/clean-css/clean-css/issues/160) - re-runs optimizer until a clean pass.
* Fixed issue [#161](https://github.com/clean-css/clean-css/issues/161) - improves tokenizer performance.
* Fixed issue [#163](https://github.com/clean-css/clean-css/issues/163) - round pixels to 2nd decimal place.
* Fixed issue [#165](https://github.com/clean-css/clean-css/issues/165) - extra space after trailing parenthesis.
* Fixed issue [#186](https://github.com/clean-css/clean-css/issues/186) - strip unit from `0rem`.
* Fixed issue [#207](https://github.com/clean-css/clean-css/issues/207) - bug in parsing protocol `@import`s.
* Fixed issue [#213](https://github.com/clean-css/clean-css/issues/213) - faster `rgb` to `hex` transforms.
* Fixed issue [#215](https://github.com/clean-css/clean-css/issues/215) - leading zeros in numerical values.
* Fixed issue [#217](https://github.com/clean-css/clean-css/issues/217) - whitespace inside attribute selectors and URLs.
* Fixed issue [#218](https://github.com/clean-css/clean-css/issues/218) - `@import` statements cleanup.
* Fixed issue [#220](https://github.com/clean-css/clean-css/issues/220) - selector between comments.
* Fixed issue [#223](https://github.com/clean-css/clean-css/issues/223) - two-pass adjacent selectors merging.
* Fixed issue [#226](https://github.com/clean-css/clean-css/issues/226) - don't minify `border:none` to `border:0`.
* Fixed issue [#229](https://github.com/clean-css/clean-css/issues/229) - improved processing of fraction numbers.
* Fixed issue [#230](https://github.com/clean-css/clean-css/issues/230) - better handling of zero values.
* Fixed issue [#235](https://github.com/clean-css/clean-css/issues/235) - IE7 compatibility mode.
* Fixed issue [#236](https://github.com/clean-css/clean-css/issues/236) - incorrect rebasing with nested `import`s.

[2.0.8 / 2014-02-07](https://github.com/clean-css/clean-css/compare/v2.0.7...v2.0.8)
==================

* Fixed issue [#232](https://github.com/clean-css/clean-css/issues/232) - edge case in non-adjacent selectors merging.

[2.0.7 / 2014-01-16](https://github.com/clean-css/clean-css/compare/v2.0.6...v2.0.7)
==================

* Fixed issue [#208](https://github.com/clean-css/clean-css/issues/208) - don't swallow `@page` and `@viewport`.

[2.0.6 / 2014-01-04](https://github.com/clean-css/clean-css/compare/v2.0.5...v2.0.6)
==================

* Fixed issue [#198](https://github.com/clean-css/clean-css/issues/198) - process comments and `@import`s correctly.
* Fixed issue [#205](https://github.com/clean-css/clean-css/issues/205) - freeze on broken `@import` declaration.

[2.0.5 / 2014-01-03](https://github.com/clean-css/clean-css/compare/v2.0.4...v2.0.5)
==================

* Fixed issue [#199](https://github.com/clean-css/clean-css/issues/199) - keep line breaks with no advanced optimizations.
* Fixed issue [#203](https://github.com/clean-css/clean-css/issues/203) - Buffer as a first argument to minify method.

[2.0.4 / 2013-12-19](https://github.com/clean-css/clean-css/compare/v2.0.3...v2.0.4)
==================

* Fixed issue [#193](https://github.com/clean-css/clean-css/issues/193) - HSL color space normalization.

[2.0.3 / 2013-12-18](https://github.com/clean-css/clean-css/compare/v2.0.2...v2.0.3)
==================

* Fixed issue [#191](https://github.com/clean-css/clean-css/issues/191) - leading numbers in `font`/`animation` names.
* Fixed issue [#192](https://github.com/clean-css/clean-css/issues/192) - many `@import`s inside a comment.

[2.0.2 / 2013-11-18](https://github.com/clean-css/clean-css/compare/v2.0.1...v2.0.2)
==================

* Fixed issue [#177](https://github.com/clean-css/clean-css/issues/177) - process broken content correctly.

[2.0.1 / 2013-11-14](https://github.com/clean-css/clean-css/compare/v2.0.0...v2.0.1)
==================

* Fixed issue [#176](https://github.com/clean-css/clean-css/issues/176) - hangs on `undefined` keyword.

[2.0.0 / 2013-11-04](https://github.com/clean-css/clean-css/compare/v1.1.7...v2.0.0)
==================

* Adds simplified and more advanced text escaping / restoring via `EscapeStore` class.
* Adds simplified and much faster empty elements removal.
* Adds missing `@import` processing to our benchmark (run via `npm run bench`).
* Adds CSS tokenizer which will make it possible to optimize content by reordering and/or merging selectors.
* Adds basic optimizer removing duplicate selectors from a list.
* Adds merging duplicate properties within a single selector's body.
* Adds merging adjacent selectors within a scope (single and multiple ones).
* Changes behavior of `--keep-line-breaks`/`keepBreaks` option to keep breaks after trailing braces only.
* Makes all multiple selectors ordered alphabetically (aids merging).
* Adds property overriding so more coarse properties override more granular ones.
* Adds reducing non-adjacent selectors.
* Adds `--skip-advanced`/`noAdvanced` switch to disable advanced optimizations.
* Adds reducing non-adjacent selectors when overridden by more complex selectors.
* Fixed issue [#138](https://github.com/clean-css/clean-css/issues/138) - makes CleanCSS interface OO.
* Fixed issue [#139](https://github.com/clean-css/clean-css/issues/138) - consistent error & warning handling.
* Fixed issue [#145](https://github.com/clean-css/clean-css/issues/145) - debug mode in library too.
* Fixed issue [#157](https://github.com/clean-css/clean-css/issues/157) - gets rid of `removeEmpty` option.
* Fixed issue [#159](https://github.com/clean-css/clean-css/issues/159) - escaped quotes inside content.
* Fixed issue [#162](https://github.com/clean-css/clean-css/issues/162) - strip quotes from Base64 encoded URLs.
* Fixed issue [#166](https://github.com/clean-css/clean-css/issues/166) - `debug` formatting in CLI
* Fixed issue [#167](https://github.com/clean-css/clean-css/issues/167) - `background:transparent` minification.

[1.1.7 / 2013-10-28](https://github.com/clean-css/clean-css/compare/v1.1.6...v1.1.7)
==================

* Fixed issue [#156](https://github.com/clean-css/clean-css/issues/156) - `@import`s inside comments.

[1.1.6 / 2013-10-26](https://github.com/clean-css/clean-css/compare/v1.1.5...v1.1.6)
==================

* Fixed issue [#155](https://github.com/clean-css/clean-css/issues/155) - broken irregular CSS content.

[1.1.5 / 2013-10-24](https://github.com/clean-css/clean-css/compare/v1.1.4...v1.1.5)
==================

* Fixed issue [#153](https://github.com/clean-css/clean-css/issues/153) - `keepSpecialComments` `0`/`1` as a string.

[1.1.4 / 2013-10-23](https://github.com/clean-css/clean-css/compare/v1.1.3...v1.1.4)
==================

* Fixed issue [#152](https://github.com/clean-css/clean-css/issues/152) - adds an option to disable rebasing.

[1.1.3 / 2013-10-04](https://github.com/clean-css/clean-css/compare/v1.1.2...v1.1.3)
==================

* Fixed issue [#150](https://github.com/clean-css/clean-css/issues/150) - minifying `background:none`.

[1.1.2 / 2013-09-29](https://github.com/clean-css/clean-css/compare/v1.1.1...v1.1.2)
==================

* Fixed issue [#149](https://github.com/clean-css/clean-css/issues/149) - shorthand `font` property.

[1.1.1 / 2013-09-07](https://github.com/clean-css/clean-css/compare/v1.1.0...v1.1.1)
==================

* Fixed issue [#144](https://github.com/clean-css/clean-css/issues/144) - skip URLs rebasing by default.

[1.1.0 / 2013-09-06](https://github.com/clean-css/clean-css/compare/v1.0.12...v1.1.0)
==================

* Renamed lib's `debug` option to `benchmark` when doing per-minification benchmarking.
* Added simplified comments processing & imports.
* Fixed issue [#43](https://github.com/clean-css/clean-css/issues/43) - `--debug` switch for minification stats.
* Fixed issue [#65](https://github.com/clean-css/clean-css/issues/65) - full color name / hex shortening.
* Fixed issue [#84](https://github.com/clean-css/clean-css/issues/84) - support for `@import` with media queries.
* Fixed issue [#124](https://github.com/clean-css/clean-css/issues/124) - raise error on broken imports.
* Fixed issue [#126](https://github.com/clean-css/clean-css/issues/126) - proper CSS expressions handling.
* Fixed issue [#129](https://github.com/clean-css/clean-css/issues/129) - rebasing imported URLs.
* Fixed issue [#130](https://github.com/clean-css/clean-css/issues/130) - better code modularity.
* Fixed issue [#135](https://github.com/clean-css/clean-css/issues/135) - require node.js 0.8+.

[1.0.12 / 2013-07-19](https://github.com/clean-css/clean-css/compare/v1.0.11...v1.0.12)
===================

* Fixed issue [#121](https://github.com/clean-css/clean-css/issues/121) - ability to skip `@import` processing.

[1.0.11 / 2013-07-08](https://github.com/clean-css/clean-css/compare/v1.0.10...v1.0.11)
===================

* Fixed issue [#117](https://github.com/clean-css/clean-css/issues/117) - line break escaping in comments.

[1.0.10 / 2013-06-13](https://github.com/clean-css/clean-css/compare/v1.0.9...v1.0.10)
===================

* Fixed issue [#114](https://github.com/clean-css/clean-css/issues/114) - comments in imported stylesheets.

[1.0.9 / 2013-06-11](https://github.com/clean-css/clean-css/compare/v1.0.8...v1.0.9)
==================

* Fixed issue [#113](https://github.com/clean-css/clean-css/issues/113) - `@import` in comments.

[1.0.8 / 2013-06-10](https://github.com/clean-css/clean-css/compare/v1.0.7...v1.0.8)
==================

* Fixed issue [#112](https://github.com/clean-css/clean-css/issues/112) - reducing `box-shadow` zeros.

[1.0.7 / 2013-06-05](https://github.com/clean-css/clean-css/compare/v1.0.6...v1.0.7)
==================

* Support for `@import` URLs starting with `//`. By [@petetak](https://github.com/petetak).

[1.0.6 / 2013-06-04](https://github.com/clean-css/clean-css/compare/v1.0.5...v1.0.6)
==================

* Fixed issue [#110](https://github.com/clean-css/clean-css/issues/110) - data URIs in URLs.

[1.0.5 / 2013-05-26](https://github.com/clean-css/clean-css/compare/v1.0.4...v1.0.5)
==================

* Fixed issue [#107](https://github.com/clean-css/clean-css/issues/107) - data URIs in imported stylesheets.

1.0.4 / 2013-05-23
==================

* Rewrite relative URLs in imported stylesheets. By [@bluej100](https://github.com/bluej100).

1.0.3 / 2013-05-20
==================

* Support alternative `@import` syntax with file name not wrapped inside `url()` statement.
  By [@bluej100](https://github.com/bluej100).

1.0.2 / 2013-04-29
==================

* Fixed issue [#97](https://github.com/clean-css/clean-css/issues/97) - `--remove-empty` & FontAwesome.

1.0.1 / 2013-04-08
==================

* Do not pick up `bench` and `test` while building `npm` package.
  By [@sindresorhus](https://https://github.com/sindresorhus).

1.0.0 / 2013-03-30
==================

* Fixed issue [#2](https://github.com/clean-css/clean-css/issues/2) - resolving `@import` rules.
* Fixed issue [#44](https://github.com/clean-css/clean-css/issues/44) - examples in `--help`.
* Fixed issue [#46](https://github.com/clean-css/clean-css/issues/46) - preserving special characters in URLs and attributes.
* Fixed issue [#80](https://github.com/clean-css/clean-css/issues/80) - quotation in multi line strings.
* Fixed issue [#83](https://github.com/clean-css/clean-css/issues/83) - HSL to hex color conversions.
* Fixed issue [#86](https://github.com/clean-css/clean-css/issues/86) - broken `@charset` replacing.
* Fixed issue [#88](https://github.com/clean-css/clean-css/issues/88) - removes space in `! important`.
* Fixed issue [#92](https://github.com/clean-css/clean-css/issues/92) - uppercase hex to short versions.

0.10.2 / 2013-03-19
===================

* Fixed issue [#79](https://github.com/clean-css/clean-css/issues/79) - node.js 0.10.x compatibility.

0.10.1 / 2013-02-14
===================

* Fixed issue [#66](https://github.com/clean-css/clean-css/issues/66) - line breaks without extra spaces should
  be handled correctly.

0.10.0 / 2013-02-09
===================

* Switched from [optimist](https://github.com/substack/node-optimist) to
  [commander](https://github.com/visionmedia/commander.js) for CLI processing.
* Changed long options from `--removeempty` to `--remove-empty` and from `--keeplinebreaks` to `--keep-line-breaks`.
* Fixed performance issue with replacing multiple `@charset` declarations and issue
  with line break after `@charset` when using `keepLineBreaks` option. By [@rrjaime](https://github.com/rrjamie).
* Removed Makefile in favor to `npm run` commands (e.g. `make check` -> `npm run check`).
* Fixed issue [#47](https://github.com/clean-css/clean-css/issues/47) - commandline issues on Windows.
* Fixed issue [#49](https://github.com/clean-css/clean-css/issues/49) - remove empty selectors from media query.
* Fixed issue [#52](https://github.com/clean-css/clean-css/issues/52) - strip fraction zeros if not needed.
* Fixed issue [#58](https://github.com/clean-css/clean-css/issues/58) - remove colon where possible.
* Fixed issue [#59](https://github.com/clean-css/clean-css/issues/59) - content property handling.

0.9.1 / 2012-12-19
==================

* Fixed issue [#37](https://github.com/clean-css/clean-css/issues/37) - converting
  `white` and other colors in class names (reported by [@malgorithms](https://github.com/malgorithms)).

0.9.0 / 2012-12-15
==================

* Added stripping quotation from font names (if possible).
* Added stripping quotation from `@keyframes` declaration, `animation` and
  `animation-name` property.
* Added stripping quotations from attributes' value (e.g. `[data-target='x']`).
* Added better hex->name and name->hex color shortening.
* Added `font: normal` and `font: bold` shortening the same way as `font-weight` is.
* Refactored shorthand selectors and added `border-radius`, `border-style`
  and `border-color` shortening.
* Added `margin`, `padding` and `border-width` shortening.
* Added removing line break after commas.
* Fixed removing whitespace inside media query definition.
* Added removing line breaks after a comma, so all declarations are one-liners now.
* Speed optimizations (~10% despite many new features).
* Added [JSHint](https://github.com/jshint/jshint/) validation rules via `make check`.

0.8.3 / 2012-11-29
==================

* Fixed HSL/HSLA colors processing.

0.8.2 / 2012-10-31
==================

* Fixed shortening hex colors and their relation to hashes in URLs.
* Cleanup by [@XhmikosR](https://github.com/XhmikosR).

0.8.1 / 2012-10-28
==================

* Added better zeros processing for `rect(...)` syntax (clip property).

0.8.0 / 2012-10-21
==================

* Added removing URLs quotation if possible.
* Rewrote breaks processing.
* Added `keepBreaks`/`-b` option to keep line breaks in the minimized file.
* Reformatted [lib/clean.js](/lib/clean.js) so it's easier to follow the rules.
* Minimized test data is now minimized with line breaks so it's easier to
  compare the changes line by line.

0.7.0 / 2012-10-14
==================

* Added stripping special comments to CLI (`--s0` and `--s1` options).
* Added stripping special comments to programmatic interface
  (`keepSpecialComments` option).

0.6.0 / 2012-08-05
==================

* Full Windows support with tests (./test.bat).

0.5.0 / 2012-08-02
==================

* Made path to vows local.
* Explicit node.js 0.6 requirement.

0.4.2 / 2012-06-28
==================

* Updated binary `-v` option (version).
* Updated binary to output help when no options given (but not in piped mode).
* Added binary tests.

0.4.1 / 2012-06-10
==================

* Fixed stateless mode where calling `CleanCSS#process` directly was giving
  errors (reported by [@facelessuser](https://github.com/facelessuser)).

0.4.0 / 2012-06-04
==================

* Speed improvements up to 4x thanks to the rewrite of comments and CSS' content
  processing.
* Stripping empty CSS tags is now optional (see [bin/cleancss](/bin/cleancss) for details).
* Improved debugging mode (see [test/bench.js](/test/bench.js))
* Added `make bench` for a one-pass benchmark.

0.3.3 / 2012-05-27
==================

* Fixed tests, [package.json](/package.json) for development, and regex
  for removing empty declarations (thanks to [@vvo](https://github.com/vvo)).

0.3.2 / 2012-01-17
==================

* Fixed output method under node.js 0.6 which incorrectly tried to close
  `process.stdout`.

0.3.1 / 2011-12-16
==================

* Fixed cleaning up `0 0 0 0` expressions.

0.3.0 / 2011-11-29
==================

* Clean-css requires node.js 0.4.0+ to run.
* Removed node.js's 0.2.x 'sys' package dependency
  (thanks to [@jmalonzo](https://github.com/jmalonzo) for a patch).

0.2.6 / 2011-11-27
==================

* Fixed expanding `+` signs in `calc()` when mixed up with adjacent `+` selector.

0.2.5 / 2011-11-27
==================

* Fixed issue with cleaning up spaces inside `calc`/`-moz-calc` declarations
  (thanks to [@cvan](https://github.com/cvan) for reporting it).
* Fixed converting `#f00` to `red` in borders and gradients.

0.2.4 / 2011-05-25
==================

* Fixed problem with expanding `none` to `0` in partial/full background
  declarations.
* Fixed including clean-css library from binary (global to local).

0.2.3 / 2011-04-18
==================

* Fixed problem with optimizing IE filters.

0.2.2 / 2011-04-17
==================

* Fixed problem with space before color in `border` property.

0.2.1 / 2011-03-19
==================

* Added stripping space before `!important` keyword.
* Updated repository location and author information in [package.json](/package.json).

0.2.0 / 2011-03-02
==================

* Added options parsing via optimist.
* Changed code inclusion (thus the version bump).

0.1.0 / 2011-02-27
==================

* First version of clean-css library.
* Implemented all basic CSS transformations.


---

<h1 align="center">
  <br/>
  <img src="./logo.v2.svg" alt="clean-css logo" width="525px"/>
  <br/>
  <br/>
</h1>

[![npm version](https://img.shields.io/npm/v/clean-css.svg?style=flat)](https://www.npmjs.com/package/clean-css)
[![Build Status](https://img.shields.io/github/workflow/status/clean-css/clean-css/Tests/master)](https://github.com/clean-css/clean-css/actions?query=workflow%3ATests+branch%3Amaster)
[![PPC Linux Build Status](https://img.shields.io/travis/clean-css/clean-css/master.svg?style=flat&label=PPC%20Linux%20build)](https://travis-ci.org/clean-css/clean-css)
[![Dependency Status](https://img.shields.io/david/clean-css/clean-css.svg?style=flat)](https://david-dm.org/clean-css/clean-css)
[![npm Downloads](https://img.shields.io/npm/dm/clean-css.svg)](https://npmcharts.com/compare/clean-css?minimal=true)

clean-css is a fast and efficient CSS optimizer for [Node.js](http://nodejs.org/) platform and [any modern browser](https://clean-css.github.io/).

According to [tests](http://goalsmashers.github.io/css-minification-benchmark/) it is one of the best available.

**Table of Contents**

- [Node.js version support](#nodejs-version-support)
- [Install](#install)
- [Use](#use)
  * [What's new in version 5.3](#whats-new-in-version-53)
  * [What's new in version 5.0](#whats-new-in-version-50)
  * [What's new in version 4.2](#whats-new-in-version-42)
  * [What's new in version 4.1](#whats-new-in-version-41)
  * [Important: 4.0 breaking changes](#important-40-breaking-changes)
  * [Constructor options](#constructor-options)
  * [Compatibility modes](#compatibility-modes)
  * [Fetch option](#fetch-option)
  * [Formatting options](#formatting-options)
  * [Inlining options](#inlining-options)
  * [Optimization levels](#optimization-levels)
    + [Level 0 optimizations](#level-0-optimizations)
    + [Level 1 optimizations](#level-1-optimizations)
    + [Level 2 optimizations](#level-2-optimizations)
  * [Plugins](#plugins)
  * [Minify method](#minify-method)
  * [Promise interface](#promise-interface)
  * [CLI utility](#cli-utility)
- [FAQ](#faq)
  * [How to optimize multiple files?](#how-to-optimize-multiple-files)
  * [How to process multiple files without concatenating them into one output file?](#how-to-process-multiple-files-without-concatenating-them-into-one-output-file)
  * [How to process remote `@import`s correctly?](#how-to-process-remote-imports-correctly)
  * [How to apply arbitrary transformations to CSS properties?](#how-to-apply-arbitrary-transformations-to-css-properties)
  * [How to specify a custom rounding precision?](#how-to-specify-a-custom-rounding-precision)
  * [How to keep a CSS fragment intact?](#how-to-keep-a-css-fragment-intact)
  * [How to preserve a comment block?](#how-to-preserve-a-comment-block)
  * [How to rebase relative image URLs?](#how-to-rebase-relative-image-urls)
  * [How to work with source maps?](#how-to-work-with-source-maps)
  * [How to apply level 1 & 2 optimizations at the same time?](#how-to-apply-level-1--2-optimizations-at-the-same-time)
  * [What level 2 optimizations do?](#what-level-2-optimizations-do)
  * [What errors and warnings are?](#what-errors-and-warnings-are)
  * [How to use clean-css with build tools?](#how-to-use-clean-css-with-build-tools)
  * [How to use clean-css from web browser?](#how-to-use-clean-css-from-web-browser)
- [Contributing](#contributing)
  * [How to get started?](#how-to-get-started)
- [Acknowledgments](#acknowledgments)
- [License](#license)

# Node.js version support

clean-css requires Node.js 10.0+ (tested on Linux, OS X, and Windows)

# Install

```
npm install --save-dev clean-css
```

# Use

```js
var CleanCSS = require('clean-css');
var input = 'a{font-weight:bold;}';
var options = { /* options */ };
var output = new CleanCSS(options).minify(input);
```

## What's new in version 5.3

clean-css 5.3 introduces one new feature:

* variables can be optimized using level 1's `variableValueOptimizers` option, which accepts a list of [value optimizers](https://github.com/clean-css/clean-css/blob/master/lib/optimizer/level-1/value-optimizers.js) or a list of their names, e.g. `variableValueOptimizers: ['color', 'fraction']`.

## What's new in version 5.0

clean-css 5.0 introduced some breaking changes:

* Node.js 6.x and 8.x are officially no longer supported;
* `transform` callback in level-1 optimizations is removed in favor of new [plugins](#plugins) interface;
* changes default Internet Explorer compatibility from 10+ to >11, to revert the old default use `{ compatibility: 'ie10' }` flag;
* changes default `rebase` option from `true` to `false` so URLs are not rebased by default. Please note that if you set `rebaseTo` option it still counts as setting `rebase: true` to preserve some of the backward compatibility.

And on the new features side of things:

* format options now accepts numerical values for all breaks, which will allow you to have more control over output formatting, e.g. `format: {breaks: {afterComment: 2}}` means clean-css will add two line breaks after each comment
* a new `batch` option (defaults to `false`) is added, when set to `true` it will process all inputs, given either as an array or a hash, without concatenating them.

## What's new in version 4.2

clean-css 4.2 introduces the following changes / features:

* Adds `process` method for compatibility with optimize-css-assets-webpack-plugin;
* new `transition` property optimizer;
* preserves any CSS content between `/* clean-css ignore:start */` and `/* clean-css ignore:end */` comments;
* allows filtering based on selector in `transform` callback, see [example](#how-to-apply-arbitrary-transformations-to-css-properties);
* adds configurable line breaks via `format: { breakWith: 'lf' }` option.

## What's new in version 4.1

clean-css 4.1 introduces the following changes / features:

* `inline: false` as an alias to `inline: ['none']`;
* `multiplePseudoMerging` compatibility flag controlling merging of rules with multiple pseudo classes / elements;
* `removeEmpty` flag in level 1 optimizations controlling removal of rules and nested blocks;
* `removeEmpty` flag in level 2 optimizations controlling removal of rules and nested blocks;
* `compatibility: { selectors: { mergeLimit: <number> } }` flag in compatibility settings controlling maximum number of selectors in a single rule;
* `minify` method improved signature accepting a list of hashes for a predictable traversal;
* `selectorsSortingMethod` level 1 optimization allows `false` or `'none'` for disabling selector sorting;
* `fetch` option controlling a function for handling remote requests;
* new `font` shorthand and `font-*` longhand optimizers;
* removal of `optimizeFont` flag in level 1 optimizations due to new `font` shorthand optimizer;
* `skipProperties` flag in level 2 optimizations controlling which properties won't be optimized;
* new `animation` shorthand and `animation-*` longhand optimizers;
* `removeUnusedAtRules` level 2 optimization controlling removal of unused `@counter-style`, `@font-face`, `@keyframes`, and `@namespace` at rules;
* the [web interface](https://clean-css.github.io/) gets an improved settings panel with "reset to defaults", instant option changes, and settings being persisted across sessions.

## Important: 4.0 breaking changes

clean-css 4.0 introduces some breaking changes:

* API and CLI interfaces are split, so API stays in this repository while CLI moves to [clean-css-cli](https://github.com/clean-css/clean-css-cli);
* `root`, `relativeTo`, and `target` options are replaced by a single `rebaseTo` option - this means that rebasing URLs and import inlining is much simpler but may not be (YMMV) as powerful as in 3.x;
* `debug` option is gone as stats are always provided in output object under `stats` property;
* `roundingPrecision` is disabled by default;
* `roundingPrecision` applies to **all** units now, not only `px` as in 3.x;
* `processImport` and `processImportFrom` are merged into `inline` option which defaults to `local`. Remote `@import` rules are **NOT** inlined by default anymore;
* splits `inliner: { request: ..., timeout: ... }` option into `inlineRequest` and `inlineTimeout` options;
* remote resources without a protocol, e.g. `//fonts.googleapis.com/css?family=Domine:700`, are not inlined anymore;
* changes default Internet Explorer compatibility from 9+ to 10+, to revert the old default use `{ compatibility: 'ie9' }` flag;
* renames `keepSpecialComments` to `specialComments`;
* moves `roundingPrecision` and `specialComments` to level 1 optimizations options, see examples;
* moves `mediaMerging`, `restructuring`, `semanticMerging`, and `shorthandCompacting` to level 2 optimizations options, see examples below;
* renames `shorthandCompacting` option to `mergeIntoShorthands`;
* level 1 optimizations are the new default, up to 3.x it was level 2;
* `keepBreaks` option is replaced with `{ format: 'keep-breaks' }` to ease transition;
* `sourceMap` option has to be a boolean from now on - to specify an input source map pass it a 2nd argument to `minify` method or via a hash instead;
* `aggressiveMerging` option is removed as aggressive merging is replaced by smarter override merging.

## Constructor options

clean-css constructor accepts a hash as a parameter with the following options available:

* `compatibility` - controls compatibility mode used; defaults to `ie10+`; see [compatibility modes](#compatibility-modes) for examples;
* `fetch` - controls a function for handling remote requests; see [fetch option](#fetch-option) for examples (since 4.1.0);
* `format` - controls output CSS formatting; defaults to `false`; see [formatting options](#formatting-options) for examples;
* `inline` - controls `@import` inlining rules; defaults to `'local'`; see [inlining options](#inlining-options) for examples;
* `inlineRequest` - controls extra options for inlining remote `@import` rules, can be any of [HTTP(S) request options](https://nodejs.org/api/http.html#http_http_request_options_callback);
* `inlineTimeout` - controls number of milliseconds after which inlining a remote `@import` fails; defaults to 5000;
* `level` - controls optimization level used; defaults to `1`; see [optimization levels](#optimization-levels) for examples;
* `rebase` - controls URL rebasing; defaults to `false`;
* `rebaseTo` - controls a directory to which all URLs are rebased, most likely the directory under which the output file will live; defaults to the current directory;
* `returnPromise` - controls whether `minify` method returns a Promise object or not; defaults to `false`; see [promise interface](#promise-interface) for examples;
* `sourceMap` - controls whether an output source map is built; defaults to `false`;
* `sourceMapInlineSources` - controls embedding sources inside a source map's `sourcesContent` field; defaults to false.

## Compatibility modes

There is a certain number of compatibility mode shortcuts, namely:

* `new CleanCSS({ compatibility: '*' })` (default) - Internet Explorer 10+ compatibility mode
* `new CleanCSS({ compatibility: 'ie9' })` - Internet Explorer 9+ compatibility mode
* `new CleanCSS({ compatibility: 'ie8' })` - Internet Explorer 8+ compatibility mode
* `new CleanCSS({ compatibility: 'ie7' })` - Internet Explorer 7+ compatibility mode

Each of these modes is an alias to a [fine grained configuration](https://github.com/clean-css/clean-css/blob/master/lib/options/compatibility.js), with the following options available:

```js
new CleanCSS({
  compatibility: {
    colors: {
      hexAlpha: false, // controls 4- and 8-character hex color support
      opacity: true // controls `rgba()` / `hsla()` color support
    },
    properties: {
      backgroundClipMerging: true, // controls background-clip merging into shorthand
      backgroundOriginMerging: true, // controls background-origin merging into shorthand
      backgroundSizeMerging: true, // controls background-size merging into shorthand
      colors: true, // controls color optimizations
      ieBangHack: false, // controls keeping IE bang hack
      ieFilters: false, // controls keeping IE `filter` / `-ms-filter`
      iePrefixHack: false, // controls keeping IE prefix hack
      ieSuffixHack: false, // controls keeping IE suffix hack
      merging: true, // controls property merging based on understandability
      shorterLengthUnits: false, // controls shortening pixel units into `pc`, `pt`, or `in` units
      spaceAfterClosingBrace: true, // controls keeping space after closing brace - `url() no-repeat` into `url()no-repeat`
      urlQuotes: true, // controls keeping quoting inside `url()`
      zeroUnits: true // controls removal of units `0` value
    },
    selectors: {
      adjacentSpace: false, // controls extra space before `nav` element
      ie7Hack: true, // controls removal of IE7 selector hacks, e.g. `*+html...`
      mergeablePseudoClasses: [':active', ...], // controls a whitelist of mergeable pseudo classes
      mergeablePseudoElements: ['::after', ...], // controls a whitelist of mergeable pseudo elements
      mergeLimit: 8191, // controls maximum number of selectors in a single rule (since 4.1.0)
      multiplePseudoMerging: true // controls merging of rules with multiple pseudo classes / elements (since 4.1.0)
    },
    units: {
      ch: true, // controls treating `ch` as a supported unit
      in: true, // controls treating `in` as a supported unit
      pc: true, // controls treating `pc` as a supported unit
      pt: true, // controls treating `pt` as a supported unit
      rem: true, // controls treating `rem` as a supported unit
      vh: true, // controls treating `vh` as a supported unit
      vm: true, // controls treating `vm` as a supported unit
      vmax: true, // controls treating `vmax` as a supported unit
      vmin: true // controls treating `vmin` as a supported unit
    }
  }
})
```

You can also use a string when setting a compatibility mode, e.g.

```js
new CleanCSS({
  compatibility: 'ie9,-properties.merging' // sets compatibility to IE9 mode with disabled property merging
})
```

## Fetch option

The `fetch` option accepts a function which handles remote resource fetching, e.g.

```js
var request = require('request');
var source = '@import url(http://example.com/path/to/stylesheet.css);';
new CleanCSS({
  fetch: function (uri, inlineRequest, inlineTimeout, callback) {
    request(uri, function (error, response, body) {
      if (error) {
        callback(error, null);
      } else if (response && response.statusCode != 200) {
        callback(response.statusCode, null);
      } else {
        callback(null, body);
      }
    });
  }
}).minify(source);
```

This option provides a convenient way of overriding the default fetching logic if it doesn't support a particular feature, say CONNECT proxies.

Unless given, the default [loadRemoteResource](https://github.com/clean-css/clean-css/blob/master/lib/reader/load-remote-resource.js) logic is used.

## Formatting options

By default output CSS is formatted without any whitespace unless a `format` option is given.
First of all there are two shorthands:

```js
new CleanCSS({
  format: 'beautify' // formats output in a really nice way
})
```

and

```js
new CleanCSS({
  format: 'keep-breaks' // formats output the default way but adds line breaks for improved readability
})
```

however `format` option also accept a fine-grained set of options:

```js
new CleanCSS({
  format: {
    breaks: { // controls where to insert breaks
      afterAtRule: false, // controls if a line break comes after an at-rule; e.g. `@charset`; defaults to `false`
      afterBlockBegins: false, // controls if a line break comes after a block begins; e.g. `@media`; defaults to `false`
      afterBlockEnds: false, // controls if a line break comes after a block ends, defaults to `false`
      afterComment: false, // controls if a line break comes after a comment; defaults to `false`
      afterProperty: false, // controls if a line break comes after a property; defaults to `false`
      afterRuleBegins: false, // controls if a line break comes after a rule begins; defaults to `false`
      afterRuleEnds: false, // controls if a line break comes after a rule ends; defaults to `false`
      beforeBlockEnds: false, // controls if a line break comes before a block ends; defaults to `false`
      betweenSelectors: false // controls if a line break comes between selectors; defaults to `false`
    },
    breakWith: '\n', // controls the new line character, can be `'\r\n'` or `'\n'` (aliased as `'windows'` and `'unix'` or `'crlf'` and `'lf'`); defaults to system one, so former on Windows and latter on Unix
    indentBy: 0, // controls number of characters to indent with; defaults to `0`
    indentWith: 'space', // controls a character to indent with, can be `'space'` or `'tab'`; defaults to `'space'`
    spaces: { // controls where to insert spaces
      aroundSelectorRelation: false, // controls if spaces come around selector relations; e.g. `div > a`; defaults to `false`
      beforeBlockBegins: false, // controls if a space comes before a block begins; e.g. `.block {`; defaults to `false`
      beforeValue: false // controls if a space comes before a value; e.g. `width: 1rem`; defaults to `false`
    },
    wrapAt: false, // controls maximum line length; defaults to `false`
    semicolonAfterLastProperty: false // controls removing trailing semicolons in rule; defaults to `false` - means remove
  }
})
```

Also since clean-css 5.0 you can use numerical values for all line breaks, which will repeat a line break that many times, e.g:

```js
  new CleanCSS({
    format: {
      breaks: {
        afterAtRule: 2,
        afterBlockBegins: 1, // 1 is synonymous with `true`
        afterBlockEnds: 2,
        afterComment: 1,
        afterProperty: 1,
        afterRuleBegins: 1,
        afterRuleEnds: 1,
        beforeBlockEnds: 1,
        betweenSelectors: 0 // 0 is synonymous with `false`
      }
    }
  })
```

which will add nicer spacing between at rules and blocks.

## Inlining options

`inline` option whitelists which `@import` rules will be processed, e.g.

```js
new CleanCSS({
  inline: ['local'] // default; enables local inlining only
})
```

```js
new CleanCSS({
  inline: ['none'] // disables all inlining
})
```

```js
// introduced in clean-css 4.1.0

new CleanCSS({
  inline: false // disables all inlining (alias to `['none']`)
})
```

```js
new CleanCSS({
  inline: ['all'] // enables all inlining, same as ['local', 'remote']
})
```

```js
new CleanCSS({
  inline: ['local', 'mydomain.example.com'] // enables local inlining plus given remote source
})
```

```js
new CleanCSS({
  inline: ['local', 'remote', '!fonts.googleapis.com'] // enables all inlining but from given remote source
})
```

## Optimization levels

The `level` option can be either `0`, `1` (default), or `2`, e.g.

```js
new CleanCSS({
  level: 2
})
```

or a fine-grained configuration given via a hash.

Please note that level 1 optimization options are generally safe while level 2 optimizations should be safe for most users.

### Level 0 optimizations

Level 0 optimizations simply means "no optimizations". Use it when you'd like to inline imports and / or rebase URLs but skip everything else.

### Level 1 optimizations

Level 1 optimizations (default) operate on single properties only, e.g. can remove units when not required, turn rgb colors to a shorter hex representation, remove comments, etc

Here is a full list of available options:

```js
new CleanCSS({
  level: {
    1: {
      cleanupCharsets: true, // controls `@charset` moving to the front of a stylesheet; defaults to `true`
      normalizeUrls: true, // controls URL normalization; defaults to `true`
      optimizeBackground: true, // controls `background` property optimizations; defaults to `true`
      optimizeBorderRadius: true, // controls `border-radius` property optimizations; defaults to `true`
      optimizeFilter: true, // controls `filter` property optimizations; defaults to `true`
      optimizeFont: true, // controls `font` property optimizations; defaults to `true`
      optimizeFontWeight: true, // controls `font-weight` property optimizations; defaults to `true`
      optimizeOutline: true, // controls `outline` property optimizations; defaults to `true`
      removeEmpty: true, // controls removing empty rules and nested blocks; defaults to `true`
      removeNegativePaddings: true, // controls removing negative paddings; defaults to `true`
      removeQuotes: true, // controls removing quotes when unnecessary; defaults to `true`
      removeWhitespace: true, // controls removing unused whitespace; defaults to `true`
      replaceMultipleZeros: true, // contols removing redundant zeros; defaults to `true`
      replaceTimeUnits: true, // controls replacing time units with shorter values; defaults to `true`
      replaceZeroUnits: true, // controls replacing zero values with units; defaults to `true`
      roundingPrecision: false, // rounds pixel values to `N` decimal places; `false` disables rounding; defaults to `false`
      selectorsSortingMethod: 'standard', // denotes selector sorting method; can be `'natural'` or `'standard'`, `'none'`, or false (the last two since 4.1.0); defaults to `'standard'`
      specialComments: 'all', // denotes a number of /*! ... */ comments preserved; defaults to `all`
      tidyAtRules: true, // controls at-rules (e.g. `@charset`, `@import`) optimizing; defaults to `true`
      tidyBlockScopes: true, // controls block scopes (e.g. `@media`) optimizing; defaults to `true`
      tidySelectors: true, // controls selectors optimizing; defaults to `true`,
      variableValueOptimizers: [] // controls value optimizers which are applied to variables
    }
  }
});
```

There is an `all` shortcut for toggling all options at the same time, e.g.

```js
new CleanCSS({
  level: {
    1: {
      all: false, // set all values to `false`
      tidySelectors: true // turns on optimizing selectors
    }
  }
});
```

### Level 2 optimizations

Level 2 optimizations operate at rules or multiple properties level, e.g. can remove duplicate rules, remove properties redefined further down a stylesheet, or restructure rules by moving them around.

Please note that if level 2 optimizations are turned on then, unless explicitely disabled, level 1 optimizations are applied as well.

Here is a full list of available options:

```js
new CleanCSS({
  level: {
    2: {
      mergeAdjacentRules: true, // controls adjacent rules merging; defaults to true
      mergeIntoShorthands: true, // controls merging properties into shorthands; defaults to true
      mergeMedia: true, // controls `@media` merging; defaults to true
      mergeNonAdjacentRules: true, // controls non-adjacent rule merging; defaults to true
      mergeSemantically: false, // controls semantic merging; defaults to false
      overrideProperties: true, // controls property overriding based on understandability; defaults to true
      removeEmpty: true, // controls removing empty rules and nested blocks; defaults to `true`
      reduceNonAdjacentRules: true, // controls non-adjacent rule reducing; defaults to true
      removeDuplicateFontRules: true, // controls duplicate `@font-face` removing; defaults to true
      removeDuplicateMediaBlocks: true, // controls duplicate `@media` removing; defaults to true
      removeDuplicateRules: true, // controls duplicate rules removing; defaults to true
      removeUnusedAtRules: false, // controls unused at rule removing; defaults to false (available since 4.1.0)
      restructureRules: false, // controls rule restructuring; defaults to false
      skipProperties: [] // controls which properties won't be optimized, defaults to `[]` which means all will be optimized (since 4.1.0)
    }
  }
});
```

There is an `all` shortcut for toggling all options at the same time, e.g.

```js
new CleanCSS({
  level: {
    2: {
      all: false, // sets all values to `false`
      removeDuplicateRules: true // turns on removing duplicate rules
    }
  }
});
```

## Plugins

In clean-css version 5 and above you can define plugins which run alongside level 1 and level 2 optimizations, e.g.

```js
var myPlugin = {
  level1: {
    property: function removeRepeatedBackgroundRepeat(_rule, property, _options) {
      // So `background-repeat:no-repeat no-repeat` becomes `background-repeat:no-repeat`
      if (property.name == 'background-repeat' && property.value.length == 2 && property.value[0][1] == property.value[1][1]) {
        property.value.pop();
        property.dirty = true;
      }
    }
  }
}

new CleanCSS({plugins: [myPlugin]})

```

Search `test\module-test.js` for `plugins` or check out `lib/optimizer/level-1/property-optimizers` and `lib/optimizer/level-1/value-optimizers` for more examples.

__Important__: To rewrite your old `transform` as a plugin, check out [this commit](https://github.com/clean-css/clean-css/commit/b6ddc523267fc42cf0f6bd1626a79cad97319e17#diff-a71ef45f934725cdb25860dc0b606bcd59e3acee9788cd6df4f9d05339e8a153).

## Minify method

Once configured clean-css provides a `minify` method to optimize a given CSS, e.g.

```js
var output = new CleanCSS(options).minify(source);
```

The output of the `minify` method is a hash with following fields:

```js
console.log(output.styles); // optimized output CSS as a string
console.log(output.sourceMap); // output source map if requested with `sourceMap` option
console.log(output.errors); // a list of errors raised
console.log(output.warnings); // a list of warnings raised
console.log(output.stats.originalSize); // original content size after import inlining
console.log(output.stats.minifiedSize); // optimized content size
console.log(output.stats.timeSpent); // time spent on optimizations in milliseconds
console.log(output.stats.efficiency); // `(originalSize - minifiedSize) / originalSize`, e.g. 0.25 if size is reduced from 100 bytes to 75 bytes
```
Example: Minifying a CSS string:

```js
const CleanCSS = require("clean-css");

const output = new CleanCSS().minify(`

  a {
    color: blue;
  }
  div {
    margin: 5px
  }

`);

console.log(output);

// Log:
{
  styles: 'a{color:#00f}div{margin:5px}',
  stats: {
    efficiency: 0.6704545454545454,
    minifiedSize: 29,
    originalSize: 88,
    timeSpent: 6
  },
  errors: [],
  inlinedStylesheets: [],
  warnings: []
}
```

The `minify` method also accepts an input source map, e.g.

```js
var output = new CleanCSS(options).minify(source, inputSourceMap);
```

or a callback invoked when optimizations are finished, e.g.

```js
new CleanCSS(options).minify(source, function (error, output) {
  // `output` is the same as in the synchronous call above
});
```

To optimize a single file, without reading it first, pass a path to it to `minify` method as follows:

```js
var output = new CleanCSS(options).minify(['path/to/file.css'])
```

(if you won't enclose the path in an array, it will be treated as a CSS source instead).

There are several ways to optimize multiple files at the same time, see [How to optimize multiple files?](#how-to-optimize-multiple-files).

## Promise interface

If you prefer clean-css to return a Promise object then you need to explicitely ask for it, e.g.

```js
new CleanCSS({ returnPromise: true })
  .minify(source)
  .then(function (output) { console.log(output.styles); })
  .catch(function (error) { // deal with errors });
```

## CLI utility

Clean-css has an associated command line utility that can be installed separately using `npm install clean-css-cli`. For more detailed information, please visit https://github.com/clean-css/clean-css-cli.

# FAQ

## How to optimize multiple files?

It can be done either by passing an array of paths, or, when sources are already available, a hash or an array of hashes:

```js
new CleanCSS().minify(['path/to/file/one', 'path/to/file/two']);
```

```js
new CleanCSS().minify({
  'path/to/file/one': {
    styles: 'contents of file one'
  },
  'path/to/file/two': {
    styles: 'contents of file two'
  }
});
```

```js
new CleanCSS().minify([
  {'path/to/file/one': {styles: 'contents of file one'}},
  {'path/to/file/two': {styles: 'contents of file two'}}
]);
```

Passing an array of hashes allows you to explicitly specify the order in which the input files are concatenated. Whereas when you use a single hash the order is determined by the [traversal order of object properties](http://2ality.com/2015/10/property-traversal-order-es6.html) - available since 4.1.0.

Important note - any `@import` rules already present in the hash will be resolved in memory.

## How to process multiple files without concatenating them into one output file?

Since clean-css 5.0 you can, when passing an array of paths, hash, or array of hashes (see above), ask clean-css not to join styles into one output, but instead return stylesheets optimized one by one, e.g.

```js
var output = new CleanCSS({ batch: true }).minify(['path/to/file/one', 'path/to/file/two']);
var outputOfFile1 = output['path/to/file/one'].styles // all other fields, like errors, warnings, or stats are there too
var outputOfFile2 = output['path/to/file/two'].styles
```

## How to process remote `@import`s correctly?

In order to inline remote `@import` statements you need to provide a callback to minify method as fetching remote assets is an asynchronous operation, e.g.:

```js
var source = '@import url(http://example.com/path/to/remote/styles);';
new CleanCSS({ inline: ['remote'] }).minify(source, function (error, output) {
  // output.styles
});
```

If you don't provide a callback, then remote `@import`s will be left as is.

## How to apply arbitrary transformations to CSS properties?

Please see [plugins](#plugins).

## How to specify a custom rounding precision?

The level 1 `roundingPrecision` optimization option accept a string with per-unit rounding precision settings, e.g.

```js
new CleanCSS({
  level: {
    1: {
      roundingPrecision: 'all=3,px=5'
    }
  }
}).minify(source)
```

which sets all units rounding precision to 3 digits except `px` unit precision of 5 digits.

## How to optimize a stylesheet with custom `rpx` units?

Since `rpx` is a non standard unit (see [#1074](https://github.com/clean-css/clean-css/issues/1074)), it will be dropped by default as an invalid value.

However you can treat `rpx` units as regular ones:

```js
new CleanCSS({
  compatibility: {
    customUnits: {
      rpx: true
    }
  }
}).minify(source)
```

## How to keep a CSS fragment intact?

Note: available since 4.2.0.

Wrap the CSS fragment in special comments which instruct clean-css to preserve it, e.g.

```css
.block-1 {
  color: red
}
/* clean-css ignore:start */
.block-special {
  color: transparent
}
/* clean-css ignore:end */
.block-2 {
  margin: 0
}
```

Optimizing this CSS will result in the following output:

```css
.block-1{color:red}
.block-special {
  color: transparent
}
.block-2{margin:0}
```

## How to preserve a comment block?

Use the `/*!` notation instead of the standard one `/*`:

```css
/*!
  Important comments included in optimized output.
*/
```

## How to rebase relative image URLs?

clean-css will handle it automatically for you in the following cases:

* when full paths to input files are passed in as options;
* when correct paths are passed in via a hash;
* when `rebaseTo` is used with any of above two.

## How to work with source maps?

To generate a source map, use `sourceMap: true` option, e.g.:

```js
new CleanCSS({ sourceMap: true, rebaseTo: pathToOutputDirectory })
  .minify(source, function (error, output) {
    // access output.sourceMap for SourceMapGenerator object
    // see https://github.com/mozilla/source-map/#sourcemapgenerator for more details
});
```

You can also pass an input source map directly as a 2nd argument to `minify` method:

```js
new CleanCSS({ sourceMap: true, rebaseTo: pathToOutputDirectory })
  .minify(source, inputSourceMap, function (error, output) {
    // access output.sourceMap to access SourceMapGenerator object
    // see https://github.com/mozilla/source-map/#sourcemapgenerator for more details
});
```

or even multiple input source maps at once:

```js
new CleanCSS({ sourceMap: true, rebaseTo: pathToOutputDirectory }).minify({
  'path/to/source/1': {
    styles: '...styles...',
    sourceMap: '...source-map...'
  },
  'path/to/source/2': {
    styles: '...styles...',
    sourceMap: '...source-map...'
  }
}, function (error, output) {
  // access output.sourceMap as above
});
```

## How to apply level 1 & 2 optimizations at the same time?

Using the hash configuration specifying both optimization levels, e.g.

```js
new CleanCSS({
  level: {
    1: {
      all: true,
      normalizeUrls: false
    },
    2: {
      restructureRules: true
    }
  }
})
```

will apply level 1 optimizations, except url normalization, and default level 2 optimizations with rule restructuring.

## What level 2 optimizations do?

All level 2 optimizations are dispatched [here](https://github.com/clean-css/clean-css/blob/master/lib/optimizer/level-2/optimize.js#L67), and this is what they do:

* `recursivelyOptimizeBlocks` - does all the following operations on a nested block, like `@media` or `@keyframe`;
* `recursivelyOptimizeProperties` - optimizes properties in rulesets and flat at-rules, like @font-face, by splitting them into components (e.g. `margin` into `margin-(bottom|left|right|top)`), optimizing, and restoring them back. You may want to use `mergeIntoShorthands` option to control whether you want to turn multiple components into shorthands;
* `removeDuplicates` - gets rid of duplicate rulesets with exactly the same set of properties, e.g. when including a Sass / Less partial twice for no good reason;
* `mergeAdjacent` - merges adjacent rulesets with the same selector or rules;
* `reduceNonAdjacent` - identifies which properties are overridden in same-selector non-adjacent rulesets, and removes them;
* `mergeNonAdjacentBySelector` - identifies same-selector non-adjacent rulesets which can be moved (!) to be merged, requires all intermediate rulesets to not redefine the moved properties, or if redefined to have the same value;
* `mergeNonAdjacentByBody` - same as the one above but for same-selector non-adjacent rulesets;
* `restructure` - tries to reorganize different-selector different-rules rulesets so they take less space, e.g. `.one{padding:0}.two{margin:0}.one{margin-bottom:3px}` into `.two{margin:0}.one{padding:0;margin-bottom:3px}`;
* `removeDuplicateFontAtRules` - removes duplicated `@font-face` rules;
* `removeDuplicateMediaQueries` - removes duplicated `@media` nested blocks;
* `mergeMediaQueries` - merges non-adjacent `@media` at-rules by the same rules as `mergeNonAdjacentBy*` above;

## What errors and warnings are?

If clean-css encounters invalid CSS, it will try to remove the invalid part and continue optimizing the rest of the code. It will make you aware of the problem by generating an error or warning. Although clean-css can work with invalid CSS, it is always recommended that you fix warnings and errors in your CSS.

Example: Minify invalid CSS, resulting in two warnings:

```js
const CleanCSS = require("clean-css");

const output = new CleanCSS().minify(`

  a {
    -notarealproperty-: 5px;
    color:
  }
  div {
    margin: 5px
  }

`);

console.log(output);

// Log:
{
  styles: 'div{margin:5px}',
  stats: {
    efficiency: 0.8695652173913043,
    minifiedSize: 15,
    originalSize: 115,
    timeSpent: 1
  },
  errors: [],
  inlinedStylesheets: [],
  warnings: [
    "Invalid property name '-notarealproperty-' at 4:8. Ignoring.",
    "Empty property 'color' at 5:8. Ignoring."
  ]
}
```

Example: Minify invalid CSS, resulting in one error:

```js
const CleanCSS = require("clean-css");

const output = new CleanCSS().minify(`

  @import "idontexist.css";
  a {
    color: blue;
  }
  div {
    margin: 5px
  }

`);

console.log(output);

// Log:
{
  styles: 'a{color:#00f}div{margin:5px}',
  stats: {
    efficiency: 0.7627118644067796,
    minifiedSize: 28,
    originalSize: 118,
    timeSpent: 2
  },
  errors: [
    'Ignoring local @import of "idontexist.css" as resource is missing.'
  ],
  inlinedStylesheets: [],
  warnings: []
}
```
## Clean-css for Gulp
An example of how you can include clean-css in gulp
```js
const { src, dest, series } = require('gulp');
const CleanCSS = require('clean-css');
const concat = require('gulp-concat');

function css() {
    const options = {
        compatibility: '*', // (default) - Internet Explorer 10+ compatibility mode
        inline: ['all'], // enables all inlining, same as ['local', 'remote']
        level: 2 // Optimization levels. The level option can be either 0, 1 (default), or 2, e.g.
        // Please note that level 1 optimization options are generally safe while level 2 optimizations should be safe for most users.
    };

    return src('app/**/*.css')
        .pipe(concat('style.min.css'))
        .on('data', function(file) {
            const buferFile = new CleanCSS(options).minify(file.contents)
            return file.contents = Buffer.from(buferFile.styles)
        })
        .pipe(dest('build'))
}
exports.css = series(css)
```

## How to use clean-css with build tools?

There is a number of 3rd party plugins to popular build tools:

* [Broccoli](https://github.com/broccolijs/broccoli#broccoli): [broccoli-clean-css](https://github.com/shinnn/broccoli-clean-css)
* [Brunch](http://brunch.io/): [clean-css-brunch](https://github.com/brunch/clean-css-brunch)
* [Grunt](http://gruntjs.com): [grunt-contrib-cssmin](https://github.com/gruntjs/grunt-contrib-cssmin)
* [Gulp](http://gulpjs.com/): [gulp-clean-css](https://github.com/scniro/gulp-clean-css)
* [Gulp](http://gulpjs.com/): [using vinyl-map as a wrapper - courtesy of @sogko](https://github.com/clean-css/clean-css/issues/342)
* [component-builder2](https://github.com/component/builder2.js): [builder-clean-css](https://github.com/poying/builder-clean-css)
* [Metalsmith](http://metalsmith.io): [metalsmith-clean-css](https://github.com/aymericbeaumet/metalsmith-clean-css)
* [Lasso](https://github.com/lasso-js/lasso): [lasso-clean-css](https://github.com/yomed/lasso-clean-css)
* [Start](https://github.com/start-runner/start): [start-clean-css](https://github.com/start-runner/clean-css)

## How to use clean-css from web browser?

* https://clean-css.github.io/ (official web interface)
* http://refresh-sf.com/
* http://adamburgess.github.io/clean-css-online/

# Contributing

See [CONTRIBUTING.md](https://github.com/clean-css/clean-css/blob/master/CONTRIBUTING.md).

## How to get started?

First clone the sources:

```bash
git clone git@github.com:clean-css/clean-css.git
```

then install dependencies:

```bash
cd clean-css
npm install
```

then use any of the following commands to verify your copy:

```bash
npm run bench # for clean-css benchmarks (see [test/bench.js](https://github.com/clean-css/clean-css/blob/master/test/bench.js) for details)
npm run browserify # to create the browser-ready clean-css version
npm run check # to lint JS sources with [JSHint](https://github.com/jshint/jshint/)
npm test # to run all tests
```

# Acknowledgments

Sorted alphabetically by GitHub handle:

* [@abarre](https://github.com/abarre) (Anthony Barre) for improvements to `@import` processing;
* [@alexlamsl](https://github.com/alexlamsl) (Alex Lam S.L.) for testing early clean-css 4 versions, reporting bugs, and suggesting numerous improvements.
* [@altschuler](https://github.com/altschuler) (Simon Altschuler) for fixing `@import` processing inside comments;
* [@ben-eb](https://github.com/ben-eb) (Ben Briggs) for sharing ideas about CSS optimizations;
* [@davisjam](https://github.com/davisjam) (Jamie Davis) for disclosing ReDOS vulnerabilities;
* [@facelessuser](https://github.com/facelessuser) (Isaac) for pointing out a flaw in clean-css' stateless mode;
* [@grandrath](https://github.com/grandrath) (Martin Grandrath) for improving `minify` method source traversal in ES6;
* [@jmalonzo](https://github.com/jmalonzo) (Jan Michael Alonzo) for a patch removing node.js' old `sys` package;
* [@lukeapage](https://github.com/lukeapage) (Luke Page) for suggestions and testing the source maps feature;
  Plus everyone else involved in [#125](https://github.com/clean-css/clean-css/issues/125) for pushing it forward;
* [@madwizard-thomas](https://github.com/madwizard-thomas) for sharing ideas about `@import` inlining and URL rebasing.
* [@ngyikp](https://github.com/ngyikp) (Ng Yik Phang) for testing early clean-css 4 versions, reporting bugs, and suggesting numerous improvements.
* [@wagenet](https://github.com/wagenet) (Peter Wagenet) for suggesting improvements to `@import` inlining behavior;
* [@venemo](https://github.com/venemo) (Timur Kristóf) for an outstanding contribution of advanced property optimizer for 2.2 release;
* [@vvo](https://github.com/vvo) (Vincent Voyer) for a patch with better empty element regex and for inspiring us to do many performance improvements in 0.4 release;
* [@xhmikosr](https://github.com/xhmikosr) for suggesting new features, like option to remove special comments and strip out URLs quotation, and pointing out numerous improvements like JSHint, media queries, etc.

# License

clean-css is released under the [MIT License](https://github.com/clean-css/clean-css/blob/master/LICENSE).


---

# clean-stack [![Build Status](https://travis-ci.org/sindresorhus/clean-stack.svg?branch=master)](https://travis-ci.org/sindresorhus/clean-stack)

> Clean up error stack traces

Removes the mostly unhelpful internal Node.js entries.

Also works in Electron.


## Install

```
$ npm install clean-stack
```


## Usage

```js
const cleanStack = require('clean-stack');

const error = new Error('Missing unicorn');

console.log(error.stack);
/*
Error: Missing unicorn
    at Object.<anonymous> (/Users/sindresorhus/dev/clean-stack/unicorn.js:2:15)
    at Module._compile (module.js:409:26)
    at Object.Module._extensions..js (module.js:416:10)
    at Module.load (module.js:343:32)
    at Function.Module._load (module.js:300:12)
    at Function.Module.runMain (module.js:441:10)
    at startup (node.js:139:18)
*/

console.log(cleanStack(error.stack));
/*
Error: Missing unicorn
    at Object.<anonymous> (/Users/sindresorhus/dev/clean-stack/unicorn.js:2:15)
*/
```


## API

### cleanStack(stack, [options])

#### stack

Type: `string`

The `stack` property of an `Error`.

#### options

Type: `Object`

##### pretty

Type: `boolean`<br>
Default: `false`

Prettify the file paths in the stack:

`/Users/sindresorhus/dev/clean-stack/unicorn.js:2:15` → `~/dev/clean-stack/unicorn.js:2:15`


## Related

- [extrack-stack](https://github.com/sindresorhus/extract-stack) - Extract the actual stack of an error
- [stack-utils](https://github.com/tapjs/stack-utils) - Captures and cleans stack traces


## License

MIT © [Sindre Sorhus](https://sindresorhus.com)


---

# cli-boxes

> Boxes for use in the terminal

The list of boxes is just a [JSON file](boxes.json) and can be used anywhere.

## Install

```
$ npm install cli-boxes
```

## Usage

```js
const cliBoxes = require('cli-boxes');

console.log(cliBoxes.single);
/*
{
	topLeft: '┌',
	top: '─',
	topRight: '┐',
	right: '│',
	bottomRight: '┘',
	bottom: '─',
	bottomLeft: '└',
	left: '│'
}
*/
```

## API

### cliBoxes

#### `single`

```
┌────┐
│    │
└────┘
```

#### `double`

```
╔════╗
║    ║
╚════╝
```

#### `round`

```
╭────╮
│    │
╰────╯
```

#### `bold`

```
┏━━━━┓
┃    ┃
┗━━━━┛
```

#### `singleDouble`

```
╓────╖
║    ║
╙────╜
```

#### `doubleSingle`

```
╒════╕
│    │
╘════╛
```

#### `classic`

```
+----+
|    |
+----+
```

#### `arrow`

```
↘↓↓↓↓↙
→    ←
↗↑↑↑↑↖
```

## Related

- [boxen](https://github.com/sindresorhus/boxen) - Create boxes in the terminal

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-cli-boxes?utm_source=npm-cli-boxes&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

cli-table3 
===============================================================================

[![npm version](https://img.shields.io/npm/v/cli-table3.svg)](https://www.npmjs.com/package/cli-table3)
[![Build Status](https://github.com/cli-table/cli-table3/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/cli-table/cli-table3/actions/workflows/test.yml)

This utility allows you to render unicode-aided tables on the command line from
your node.js scripts.

`cli-table3` is based on (and api compatible with) the original [cli-table](https://github.com/Automattic/cli-table),
and [cli-table2](https://github.com/jamestalmage/cli-table2), which are both
unmaintained. `cli-table3` includes all the additional features from
`cli-table2`.

![Screenshot](https://i.imgur.com/sYq4T.png)

## Features not in the original cli-table

- Ability to make cells span columns and/or rows.
- Ability to set custom styles per cell (border characters/colors, padding, etc).
- Vertical alignment (top, bottom, center).
- [Word wrapping options](./basic-usage.md#set-wordwrap-to-true-to-wrap-text-on-word-boundaries).
- More robust truncation of cell text that contains ansi color characters.
- Better handling of text color that spans multiple lines.
- API compatible with the original cli-table.
- Exhaustive test suite including the entire original cli-table test suite.
- Lots of examples auto-generated from the tests ([basic](https://github.com/cli-table/cli-table3/blob/master/basic-usage.md), [advanced](https://github.com/cli-table/cli-table3/blob/master/advanced-usage.md)).

## Features

- Customizable characters that constitute the table.
- Color/background styling in the header through
  [<s>colors.js</s>](https://github.com/marak/colors.js)
  [@colors/colors](https://github.com/DABH/colors.js)
- Column width customization
- Text truncation based on predefined widths
- Text alignment (left, right, center)
- Padding (left, right)
- Easy-to-use API

## Installation

```bash
npm install cli-table3
```

## How to use

A portion of the unit test suite is used to generate examples:
- [basic-usage](https://github.com/cli-table/cli-table3/blob/master/basic-usage.md) - covers basic uses.
- [advanced](https://github.com/cli-table/cli-table3/blob/master/advanced-usage.md) - covers using the new column and row span features.

This package is api compatible with the original [cli-table](https://github.com/Automattic/cli-table).
So all the original documentation still applies (copied below).

### Horizontal Tables
```javascript
var Table = require('cli-table3');

// instantiate
var table = new Table({
    head: ['TH 1 label', 'TH 2 label']
  , colWidths: [100, 200]
});

// table is an Array, so you can `push`, `unshift`, `splice` and friends
table.push(
    ['First value', 'Second value']
  , ['First value', 'Second value']
);

console.log(table.toString());
```

### Vertical Tables
```javascript
var Table = require('cli-table3');
var table = new Table();

table.push(
    { 'Some key': 'Some value' }
  , { 'Another key': 'Another value' }
);

console.log(table.toString());
```
### Cross Tables
Cross tables are very similar to vertical tables, with two key differences:

1. They require a `head` setting when instantiated that has an empty string as the first header
2. The individual rows take the general form of { "Header": ["Row", "Values"] }

```javascript
var Table = require('cli-table3');
var table = new Table({ head: ["", "Top Header 1", "Top Header 2"] });

table.push(
    { 'Left Header 1': ['Value Row 1 Col 1', 'Value Row 1 Col 2'] }
  , { 'Left Header 2': ['Value Row 2 Col 1', 'Value Row 2 Col 2'] }
);

console.log(table.toString());
```

### Custom styles
The ```chars``` property controls how the table is drawn:
```javascript
var table = new Table({
  chars: { 'top': '═' , 'top-mid': '╤' , 'top-left': '╔' , 'top-right': '╗'
         , 'bottom': '═' , 'bottom-mid': '╧' , 'bottom-left': '╚' , 'bottom-right': '╝'
         , 'left': '║' , 'left-mid': '╟' , 'mid': '─' , 'mid-mid': '┼'
         , 'right': '║' , 'right-mid': '╢' , 'middle': '│' }
});

table.push(
    ['foo', 'bar', 'baz']
  , ['frob', 'bar', 'quuz']
);

console.log(table.toString());
// Outputs:
//
//╔══════╤═════╤══════╗
//║ foo  │ bar │ baz  ║
//╟──────┼─────┼──────╢
//║ frob │ bar │ quuz ║
//╚══════╧═════╧══════╝
```

Empty decoration lines will be skipped, to avoid vertical separator rows just
set the 'mid', 'left-mid', 'mid-mid', 'right-mid' to the empty string:
```javascript
var table = new Table({ chars: {'mid': '', 'left-mid': '', 'mid-mid': '', 'right-mid': ''} });
table.push(
    ['foo', 'bar', 'baz']
  , ['frobnicate', 'bar', 'quuz']
);

console.log(table.toString());
// Outputs: (note the lack of the horizontal line between rows)
//┌────────────┬─────┬──────┐
//│ foo        │ bar │ baz  │
//│ frobnicate │ bar │ quuz │
//└────────────┴─────┴──────┘
```

By setting all chars to empty with the exception of 'middle' being set to a
single space and by setting padding to zero, it's possible to get the most
compact layout with no decorations:
```javascript
var table = new Table({
  chars: { 'top': '' , 'top-mid': '' , 'top-left': '' , 'top-right': ''
         , 'bottom': '' , 'bottom-mid': '' , 'bottom-left': '' , 'bottom-right': ''
         , 'left': '' , 'left-mid': '' , 'mid': '' , 'mid-mid': ''
         , 'right': '' , 'right-mid': '' , 'middle': ' ' },
  style: { 'padding-left': 0, 'padding-right': 0 }
});

table.push(
    ['foo', 'bar', 'baz']
  , ['frobnicate', 'bar', 'quuz']
);

console.log(table.toString());
// Outputs:
//foo        bar baz
//frobnicate bar quuz
```

## Debugging

Later versions of cli-table3 supporting debugging your table data.

Enable and use debugging:

```
var table = new Table({ debug: 1 });
table.push([{}, {},}); // etc.

console.log(table.toString());
table.messages.forEach((message) => console.log(message));
```

If you are rendering multiple tables with debugging on run `Table.reset()` after
rendering each table.

## Build Targets

Clone the repository and run `yarn install` to install all its submodules, then run one of the following commands:

###### Run the tests with coverage reports.
```bash
$ yarn test:coverage
```

###### Run the tests every time a file changes.
```bash
$ yarn test:watch
```

###### Update the documentation.
```bash
$ yarn docs
```

## Credits

- James Talmage - author &lt;james.talmage@jrtechnical.com&gt; ([jamestalmage](https://github.com/jamestalmage))
- Guillermo Rauch - author of the original cli-table &lt;guillermo@learnboost.com&gt; ([Rauchg](https://github.com/rauchg))

## License

(The MIT License)

Copyright (c) 2014 James Talmage &lt;james.talmage@jrtechnical.com&gt;

Original cli-table code/documentation: Copyright (c) 2010 LearnBoost &lt;dev@learnboost.com&gt;

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
'Software'), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


---

# emoji-regex [![Build status](https://travis-ci.org/mathiasbynens/emoji-regex.svg?branch=master)](https://travis-ci.org/mathiasbynens/emoji-regex)

_emoji-regex_ offers a regular expression to match all emoji symbols (including textual representations of emoji) as per the Unicode Standard.

This repository contains a script that generates this regular expression based on [the data from Unicode v12](https://github.com/mathiasbynens/unicode-12.0.0). Because of this, the regular expression can easily be updated whenever new emoji are added to the Unicode standard.

## Installation

Via [npm](https://www.npmjs.com/):

```bash
npm install emoji-regex
```

In [Node.js](https://nodejs.org/):

```js
const emojiRegex = require('emoji-regex');
// Note: because the regular expression has the global flag set, this module
// exports a function that returns the regex rather than exporting the regular
// expression itself, to make it impossible to (accidentally) mutate the
// original regular expression.

const text = `
\u{231A}: ⌚ default emoji presentation character (Emoji_Presentation)
\u{2194}\u{FE0F}: ↔️ default text presentation character rendered as emoji
\u{1F469}: 👩 emoji modifier base (Emoji_Modifier_Base)
\u{1F469}\u{1F3FF}: 👩🏿 emoji modifier base followed by a modifier
`;

const regex = emojiRegex();
let match;
while (match = regex.exec(text)) {
  const emoji = match[0];
  console.log(`Matched sequence ${ emoji } — code points: ${ [...emoji].length }`);
}
```

Console output:

```
Matched sequence ⌚ — code points: 1
Matched sequence ⌚ — code points: 1
Matched sequence ↔️ — code points: 2
Matched sequence ↔️ — code points: 2
Matched sequence 👩 — code points: 1
Matched sequence 👩 — code points: 1
Matched sequence 👩🏿 — code points: 2
Matched sequence 👩🏿 — code points: 2
```

To match emoji in their textual representation as well (i.e. emoji that are not `Emoji_Presentation` symbols and that aren’t forced to render as emoji by a variation selector), `require` the other regex:

```js
const emojiRegex = require('emoji-regex/text.js');
```

Additionally, in environments which support ES2015 Unicode escapes, you may `require` ES2015-style versions of the regexes:

```js
const emojiRegex = require('emoji-regex/es2015/index.js');
const emojiRegexText = require('emoji-regex/es2015/text.js');
```

## Author

| [![twitter/mathias](https://gravatar.com/avatar/24e08a9ea84deb17ae121074d0f17125?s=70)](https://twitter.com/mathias "Follow @mathias on Twitter") |
|---|
| [Mathias Bynens](https://mathiasbynens.be/) |

## License

_emoji-regex_ is available under the [MIT](https://mths.be/mit) license.


---

# string-width

> Get the visual width of a string - the number of columns required to display it

Some Unicode characters are [fullwidth](https://en.wikipedia.org/wiki/Halfwidth_and_fullwidth_forms) and use double the normal width. [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code) are stripped and doesn't affect the width.

Useful to be able to measure the actual width of command-line output.


## Install

```
$ npm install string-width
```


## Usage

```js
const stringWidth = require('string-width');

stringWidth('a');
//=> 1

stringWidth('古');
//=> 2

stringWidth('\u001B[1m古\u001B[22m');
//=> 2
```


## Related

- [string-width-cli](https://github.com/sindresorhus/string-width-cli) - CLI for this module
- [string-length](https://github.com/sindresorhus/string-length) - Get the real length of a string
- [widest-line](https://github.com/sindresorhus/widest-line) - Get the visual width of the widest line in a string


---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-string-width?utm_source=npm-string-width&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

# clone-deep [![NPM version](https://img.shields.io/npm/v/clone-deep.svg?style=flat)](https://www.npmjs.com/package/clone-deep) [![NPM monthly downloads](https://img.shields.io/npm/dm/clone-deep.svg?style=flat)](https://npmjs.org/package/clone-deep) [![NPM total downloads](https://img.shields.io/npm/dt/clone-deep.svg?style=flat)](https://npmjs.org/package/clone-deep) [![Linux Build Status](https://img.shields.io/travis/jonschlinkert/clone-deep.svg?style=flat&label=Travis)](https://travis-ci.org/jonschlinkert/clone-deep)

> Recursively (deep) clone JavaScript native types, like Object, Array, RegExp, Date as well as primitives.

Please consider following this project's author, [Jon Schlinkert](https://github.com/jonschlinkert), and consider starring the project to show your :heart: and support.

## Install

Install with [npm](https://www.npmjs.com/):

```sh
$ npm install --save clone-deep
```

## Usage

```js
const cloneDeep = require('clone-deep');

let obj = { a: 'b' };
let arr = [obj];
let copy = cloneDeep(arr);
obj.c = 'd';

console.log(copy);
//=> [{ a: 'b' }]

console.log(arr);
//=> [{ a: 'b', c: 'd' }]
```

## Heads up!

The last argument specifies whether or not to clone instances (objects that are from a custom class or are not created by the `Object` constructor. This value may be `true` or the function use for cloning instances.

When an `instanceClone` function is provided, it will be invoked to clone objects that are not "plain" objects (as defined by [isPlainObject](#isPlainObject)`isPlainObject`). If `instanceClone` is not specified, this library will not attempt to clone non-plain objects, and will simply copy the object reference.

## Attribution

Initially based on [mout's](https://github.com/mout/mout) implementation of deepClone.

## About

<details>
<summary><strong>Contributing</strong></summary>

Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).

</details>

<details>
<summary><strong>Running Tests</strong></summary>

Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

```sh
$ npm install && npm test
```

</details>

<details>
<summary><strong>Building docs</strong></summary>

_(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_

To generate the readme, run the following command:

```sh
$ npm install -g verbose/verb#dev verb-generate-readme && verb
```

</details>

### Related projects

You might also be interested in these projects:

* [is-plain-object](https://www.npmjs.com/package/is-plain-object): Returns true if an object was created by the `Object` constructor. | [homepage](https://github.com/jonschlinkert/is-plain-object "Returns true if an object was created by the `Object` constructor.")
* [isobject](https://www.npmjs.com/package/isobject): Returns true if the value is an object and not an array or null. | [homepage](https://github.com/jonschlinkert/isobject "Returns true if the value is an object and not an array or null.")
* [kind-of](https://www.npmjs.com/package/kind-of): Get the native type of a value. | [homepage](https://github.com/jonschlinkert/kind-of "Get the native type of a value.")
* [shallow-clone](https://www.npmjs.com/package/shallow-clone): Creates a shallow clone of any JavaScript value. | [homepage](https://github.com/jonschlinkert/shallow-clone "Creates a shallow clone of any JavaScript value.")

### Contributors

| **Commits** | **Contributor** |  
| --- | --- |  
| 46 | [jonschlinkert](https://github.com/jonschlinkert) |  
| 2  | [yujunlong2000](https://github.com/yujunlong2000) |  

### Author

**Jon Schlinkert**

* [GitHub Profile](https://github.com/jonschlinkert)
* [Twitter Profile](https://twitter.com/jonschlinkert)
* [LinkedIn Profile](https://linkedin.com/in/jonschlinkert)

### License

Copyright © 2018, [Jon Schlinkert](https://github.com/jonschlinkert).
Released under the [MIT License](LICENSE).

***

_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.8.0, on November 21, 2018._

---

# clsx [![CI](https://github.com/lukeed/clsx/workflows/CI/badge.svg)](https://github.com/lukeed/clsx/actions?query=workflow%3ACI) [![codecov](https://badgen.net/codecov/c/github/lukeed/clsx)](https://codecov.io/gh/lukeed/clsx)

> A tiny (228B) utility for constructing `className` strings conditionally.<Br>Also serves as a [faster](/bench) & smaller drop-in replacement for the `classnames` module.

This module is available in three formats:

* **ES Module**: `dist/clsx.m.js`
* **CommonJS**: `dist/clsx.js`
* **UMD**: `dist/clsx.min.js`


## Install

```
$ npm install --save clsx
```


## Usage

```js
import clsx from 'clsx';
// or
import { clsx } from 'clsx';

// Strings (variadic)
clsx('foo', true && 'bar', 'baz');
//=> 'foo bar baz'

// Objects
clsx({ foo:true, bar:false, baz:isTrue() });
//=> 'foo baz'

// Objects (variadic)
clsx({ foo:true }, { bar:false }, null, { '--foobar':'hello' });
//=> 'foo --foobar'

// Arrays
clsx(['foo', 0, false, 'bar']);
//=> 'foo bar'

// Arrays (variadic)
clsx(['foo'], ['', 0, false, 'bar'], [['baz', [['hello'], 'there']]]);
//=> 'foo bar baz hello there'

// Kitchen sink (with nesting)
clsx('foo', [1 && 'bar', { baz:false, bat:null }, ['hello', ['world']]], 'cya');
//=> 'foo bar hello world cya'
```


## API

### clsx(...input)
Returns: `String`

#### input
Type: `Mixed`

The `clsx` function can take ***any*** number of arguments, each of which can be an Object, Array, Boolean, or String.

> **Important:** _Any_ falsey values are discarded!<br>Standalone Boolean values are discarded as well.

```js
clsx(true, false, '', null, undefined, 0, NaN);
//=> ''
```

## Benchmarks

For snapshots of cross-browser results, check out the [`bench`](/bench) directory~!

## Support

All versions of Node.js are supported.

All browsers that support [`Array.isArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/isArray#Browser_compatibility) are supported (IE9+).

>**Note:** For IE8 support and older, please install `clsx@1.0.x` and beware of [#17](https://github.com/lukeed/clsx/issues/17).


## Related

- [obj-str](https://github.com/lukeed/obj-str) - A smaller (96B) and similiar utility that only works with Objects.

## License

MIT © [Luke Edwards](https://lukeed.com)


---

# collapse-white-space

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]

Collapse white space.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`collapseWhiteSpace(value[, options|style])`](#collapsewhitespacevalue-optionsstyle)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Security](#security)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This is a small package that collapses multiple white space characters into one.

## When should I use this?

You can use this package if you want to HTML or JavaScript (default) white space
to a single character.
You can optionally drop initial and final white space.
By default it collapses to a single space, but optionally line endings can be
preserved.

## Install

This package is [ESM only][esm].
In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]:

```sh
npm install collapse-white-space
```

In Deno with [Skypack][]:

```js
import {collapseWhiteSpace} from 'https://cdn.skypack.dev/collapse-white-space@2?dts'
```

In browsers with [Skypack][]:

```html
<script type="module">
  import {collapseWhiteSpace} from 'https://cdn.skypack.dev/collapse-white-space@2?min'
</script>
```

## Use

```js
import {collapseWhiteSpace} from 'collapse-white-space'

collapseWhiteSpace('\tfoo \n\tbar  \t\r\nbaz') //=> ' foo bar baz'
```

## API

This package exports the following identifier: `collapseWhiteSpace`.
There is no default export.

### `collapseWhiteSpace(value[, options|style])`

Collapse white space in `value` (`string`).

##### `style`

Treated as `options.style`.

##### `options`

Configuration.

###### `options.style`

Style of white space to support (`'html'` or `'js'`, default: `'js'`).
JavaScript white space matches the pattern `\s+`.
HTML white space matches `[\t\n\v\f\r ]`.

###### `options.preserveLineEndings`

Whether to collapse white space containing a line ending to that line ending
(`boolean`, default: `false`).
The default is to collapse to a single space.
Line endings matches the pattern `\r?\n|\r`.

###### `options.trim`

Whether to drop white space at the start and end of `value` (`boolean`, default:
`false`).
The default is to keep it.

###### Returns

`string` – value with collapsed white space.

## Types

This package is fully typed with [TypeScript][].
It exports `Options` and `Style` types, which specify the interface of the
accepted options.

## Compatibility

This package is at least compatible with all maintained versions of Node.js.
As of now, that is Node.js 12.20+, 14.14+, and 16.0+.
It also works in Deno and modern browsers.

## Security

This package is safe.

## Related

*   [`wooorm/is-whitespace-character`](https://github.com/wooorm/is-whitespace-character)
    — check if a character is a white space character
*   [`wooorm/detab`](https://github.com/wooorm/detab)
    — convert tabs to spaces
*   [`wooorm/trim-lines`](https://github.com/wooorm/trim-lines)
    — remove tabs and spaces around line-breaks

## Contribute

Yes please!
See [How to Contribute to Open Source][contribute].

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/wooorm/collapse-white-space/workflows/main/badge.svg

[build]: https://github.com/wooorm/collapse-white-space/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/collapse-white-space.svg

[coverage]: https://codecov.io/github/wooorm/collapse-white-space

[downloads-badge]: https://img.shields.io/npm/dm/collapse-white-space.svg

[downloads]: https://www.npmjs.com/package/collapse-white-space

[size-badge]: https://img.shields.io/bundlephobia/minzip/collapse-white-space.svg

[size]: https://bundlephobia.com/result?p=collapse-white-space

[npm]: https://docs.npmjs.com/cli/install

[skypack]: https://www.skypack.dev

[license]: license

[author]: https://wooorm.com

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[typescript]: https://www.typescriptlang.org

[contribute]: https://opensource.guide/how-to-contribute/


---

# 1.0.0 - 2016-01-07

- Removed: unused speed test
- Added: Automatic routing between previously unsupported conversions
([#27](https://github.com/Qix-/color-convert/pull/27))
- Removed: `xxx2xxx()` and `xxx2xxxRaw()` functions
([#27](https://github.com/Qix-/color-convert/pull/27))
- Removed: `convert()` class
([#27](https://github.com/Qix-/color-convert/pull/27))
- Changed: all functions to lookup dictionary
([#27](https://github.com/Qix-/color-convert/pull/27))
- Changed: `ansi` to `ansi256`
([#27](https://github.com/Qix-/color-convert/pull/27))
- Fixed: argument grouping for functions requiring only one argument
([#27](https://github.com/Qix-/color-convert/pull/27))

# 0.6.0 - 2015-07-23

- Added: methods to handle
[ANSI](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors) 16/256 colors:
  - rgb2ansi16
  - rgb2ansi
  - hsl2ansi16
  - hsl2ansi
  - hsv2ansi16
  - hsv2ansi
  - hwb2ansi16
  - hwb2ansi
  - cmyk2ansi16
  - cmyk2ansi
  - keyword2ansi16
  - keyword2ansi
  - ansi162rgb
  - ansi162hsl
  - ansi162hsv
  - ansi162hwb
  - ansi162cmyk
  - ansi162keyword
  - ansi2rgb
  - ansi2hsl
  - ansi2hsv
  - ansi2hwb
  - ansi2cmyk
  - ansi2keyword
([#18](https://github.com/harthur/color-convert/pull/18))

# 0.5.3 - 2015-06-02

- Fixed: hsl2hsv does not return `NaN` anymore when using `[0,0,0]`
([#15](https://github.com/harthur/color-convert/issues/15))

---

Check out commit logs for older releases


---

# color-convert

[![Build Status](https://travis-ci.org/Qix-/color-convert.svg?branch=master)](https://travis-ci.org/Qix-/color-convert)

Color-convert is a color conversion library for JavaScript and node.
It converts all ways between `rgb`, `hsl`, `hsv`, `hwb`, `cmyk`, `ansi`, `ansi16`, `hex` strings, and CSS `keyword`s (will round to closest):

```js
var convert = require('color-convert');

convert.rgb.hsl(140, 200, 100);             // [96, 48, 59]
convert.keyword.rgb('blue');                // [0, 0, 255]

var rgbChannels = convert.rgb.channels;     // 3
var cmykChannels = convert.cmyk.channels;   // 4
var ansiChannels = convert.ansi16.channels; // 1
```

# Install

```console
$ npm install color-convert
```

# API

Simply get the property of the _from_ and _to_ conversion that you're looking for.

All functions have a rounded and unrounded variant. By default, return values are rounded. To get the unrounded (raw) results, simply tack on `.raw` to the function.

All 'from' functions have a hidden property called `.channels` that indicates the number of channels the function expects (not including alpha).

```js
var convert = require('color-convert');

// Hex to LAB
convert.hex.lab('DEADBF');         // [ 76, 21, -2 ]
convert.hex.lab.raw('DEADBF');     // [ 75.56213190997677, 20.653827952644754, -2.290532499330533 ]

// RGB to CMYK
convert.rgb.cmyk(167, 255, 4);     // [ 35, 0, 98, 0 ]
convert.rgb.cmyk.raw(167, 255, 4); // [ 34.509803921568626, 0, 98.43137254901961, 0 ]
```

### Arrays
All functions that accept multiple arguments also support passing an array.

Note that this does **not** apply to functions that convert from a color that only requires one value (e.g. `keyword`, `ansi256`, `hex`, etc.)

```js
var convert = require('color-convert');

convert.rgb.hex(123, 45, 67);      // '7B2D43'
convert.rgb.hex([123, 45, 67]);    // '7B2D43'
```

## Routing

Conversions that don't have an _explicitly_ defined conversion (in [conversions.js](conversions.js)), but can be converted by means of sub-conversions (e.g. XYZ -> **RGB** -> CMYK), are automatically routed together. This allows just about any color model supported by `color-convert` to be converted to any other model, so long as a sub-conversion path exists. This is also true for conversions requiring more than one step in between (e.g. LCH -> **LAB** -> **XYZ** -> **RGB** -> Hex).

Keep in mind that extensive conversions _may_ result in a loss of precision, and exist only to be complete. For a list of "direct" (single-step) conversions, see [conversions.js](conversions.js).

# Contribute

If there is a new model you would like to support, or want to add a direct conversion between two existing models, please send us a pull request.

# License
Copyright &copy; 2011-2016, Heather Arthur and Josh Junon. Licensed under the [MIT License](LICENSE).


---

A JSON with color names and its values. Based on http://dev.w3.org/csswg/css-color/#named-colors.

[![NPM](https://nodei.co/npm/color-name.png?mini=true)](https://nodei.co/npm/color-name/)


```js
var colors = require('color-name');
colors.red //[255,0,0]
```

<a href="LICENSE"><img src="https://upload.wikimedia.org/wikipedia/commons/0/0c/MIT_logo.svg" width="120"/></a>


---

### 2.9.3

- Fix types export for TypeScript 4.7 ❤️ [@pkishorez](https://github.com/pkishorez)

### 2.9.2

- Fix: Add "package.json" to exports map

### 2.9.1

- Fix: Make minification lossless
- Fix: Minify to name only if color is opaque

### 2.9.0

- New plugin: Color string minification 🗜

### 2.8.0

- New `delta` method to calculate the perceived color difference between two colors ❤️ [@EricRovell](https://github.com/EricRovell)

### 2.7.0

- Improve `mix` plugin by adding new `tints`, `tones` and `shades` methods ❤️ [@EricRovell](https://github.com/EricRovell)

### 2.6.0

- Support "double split complementary" color harmony generation ❤️ [@EricRovell](https://github.com/EricRovell) & [@lbragile](https://github.com/lbragile)

### 2.5.0

- New `closest` option of `toName` method allows you to find the closest color if there is no exact match

### 2.4.0

- New plugin: Color harmonies generator ❤️ [@EricRovell](https://github.com/EricRovell)

### 2.3.0

- Add new `isEqual` method ❤️ [@EricRovell](https://github.com/EricRovell)

### 2.2.0

- New plugin: CMYK color space ❤️ [@EricRovell](https://github.com/EricRovell)

### 2.1.0

- Add new `hue` and `rotate` methods

### 2.0.1

- Improve the precision of alpha values

### 2.0.0

- Strict string color parsing conforming to the CSS Color Level specifications

### 1.7.2

- Simplify package "exports" field to improve different environments support

### 1.7.1

- Parse a color name disregarding the case

### 1.7.0

- New `getFormat` utility
- Support HWB color strings (CSS functional notation)
- Clamp LAB values as defined in CSS Color Level 4 specs

### 1.6.0

- Improvement: You can now use every angle unit supported by CSS (`deg`, `rad`, `grad`, `turn`)

### 1.5.0

- New utility: Random color generation

### 1.4.1

- Mix colors through CIE LAB color space

### 1.4.0

- New plugin: Color mixing
- Adjust XYZ, LAB and LCH conversions to the D50 white point ([according to the latest CSS specs](https://drafts.csswg.org/css-color-5/#color-spaces)).

### 1.3.1

- Support modern CSS notations of RGB, HSL and LCH color functions

### 1.3.0

- New plugin: CIE LCH color space

### 1.2.1

- Fix: Do not treat 7-digit hex as a valid color ❤️ [@subzey](https://github.com/subzey)
- Parser update: Turn NaN input values into valid numbers ❤️ [@subzey](https://github.com/subzey)

### 1.2.0

- New plugin: CIE LAB color space

### 1.1.1

- Make bundle 1% lighter

### 1.1.0

- Add `isValid` method

### 1.0

- An official production-ready release

### 0.10.2

- Sort named colors dictionary for better compression ❤️ [@subzey](https://github.com/subzey)

### 0.10.1

- Ignore `null` input in the parsers

### 0.10

- Shorten conversion method names (`toRgba` to `toRgb`, etc)

### 0.9.3

- New plugin: HWB color model
- More accurate HSL and HSV conversions

### 0.9.2

- Names plugin: Support "transparent" keyword

### 0.9.1

- Improve package exports

### 0.9

- Add CommonJS exports

### 0.8

- New plugin: a11y (Accessibility)

### 0.7

- New plugin: CIE XYZ color space

### 0.6.2

- 20% speed improvement ❤️ [@jeetiss](https://github.com/jeetiss)

### 0.6.1

- 100% code coverage

### 0.6

- Make plugin available in Parcel which doesn't support exports map yet
- Fix names plugin TS declarations export
- Documentation

### 0.5

- New plugin: CSS color names

### 0.4

- Make the library ESM-first
- Add code coverage reports

### 0.3

- Implement Plugin API

### 0.2

- Support 4 and 8 digit Hex

### 0.1

- Basic API


---

MIT License

Copyright (c) 2020 Vlad Shilov omgovich@ya.ru

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

<div align="center">
  <a href="https://colord.omgovich.ru/">
    <img src="assets/logo.png" width="280" height="210" alt="colord" />
  </a>
</div>

<div align="center">
  <a href="https://npmjs.org/package/colord">
    <img alt="npm" src="https://img.shields.io/npm/v/colord.svg?labelColor=dd3a5e&color=6ead0a" />
  </a>
  <a href="https://github.com/omgovich/colord/actions">
    <img alt="build" src="https://img.shields.io/github/workflow/status/omgovich/colord/Node.js%20CI/master.svg?labelColor=dd3a5e&color=6ead0a" />
  </a>
  <a href="https://codecov.io/gh/omgovich/colord">
    <img alt="coverage" src="https://img.shields.io/codecov/c/github/omgovich/colord.svg?labelColor=dd3a5e&color=6ead0a" />
  </a>
  <a href="https://npmjs.org/package/colord">
    <img alt="no dependencies" src="https://badgen.net/bundlephobia/dependency-count/colord?labelColor=dd3a5e&color=6ead0a" />
  </a>
  <a href="https://npmjs.org/package/colord">
    <img alt="types included" src="https://badgen.net/npm/types/colord?labelColor=dd3a5e&color=6ead0a" />
  </a>
</div>

<div align="center">
  <strong>Colord</strong> is a tiny yet powerful tool for high-performance color manipulations and conversions.
</div>

## Features

- 📦 **Small**: Just **1.7 KB** gzipped ([3x+ lighter](#benchmarks) than **color** and **tinycolor2**)
- 🚀 **Fast**: [3x+ faster](#benchmarks) than **color** and **tinycolor2**
- 😍 **Simple**: Chainable API and familiar patterns
- 💪 **Immutable**: No need to worry about data mutations
- 🛡 **Bulletproof**: Written in strict TypeScript and has 100% test coverage
- 🗂 **Typed**: Ships with [types included](#types)
- 🏗 **Extendable**: Built-in [plugin system](#plugins) to add new functionality
- 📚 **CSS-compliant**: Strictly follows CSS Color Level specifications
- 👫 **Works everywhere**: Supports all browsers and Node.js
- 💨 **Dependency-free**

<div><img src="assets/divider.png" width="838" alt="---" /></div>

## Benchmarks

| Library                       | <nobr>Operations/sec</nobr>   | Size<br /> (minified)                                                                                                 | Size<br /> (gzipped)                                                                                                     | Dependencies                                                                                                                         | Type declarations                                                                                                |
| ----------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| <nobr><b>colord 👑</b></nobr> | <nobr><b>3,524,989</b></nobr> | [![](https://badgen.net/bundlephobia/min/colord?color=6ead0a&label=)](https://bundlephobia.com/result?p=colord)       | [![](https://badgen.net/bundlephobia/minzip/colord?color=6ead0a&label=)](https://bundlephobia.com/result?p=colord)       | [![](https://badgen.net/bundlephobia/dependency-count/colord?color=6ead0a&label=)](https://bundlephobia.com/result?p=colord)         | [![](https://badgen.net/npm/types/colord?color=6ead0a&label=)](https://bundlephobia.com/result?p=colord)         |
| color                         | 744,263                       | [![](https://badgen.net/bundlephobia/min/color?color=red&label=)](https://bundlephobia.com/result?p=color)            | [![](https://badgen.net/bundlephobia/minzip/color?color=red&label=)](https://bundlephobia.com/result?p=color)            | [![](https://badgen.net/bundlephobia/dependency-count/color?color=red&label=)](https://bundlephobia.com/result?p=color)              | [![](https://badgen.net/npm/types/color?color=e6591d&label=)](https://bundlephobia.com/result?p=color)           |
| tinycolor2                    | 971,312                       | [![](https://badgen.net/bundlephobia/min/tinycolor2?color=red&label=)](https://bundlephobia.com/result?p=tinycolor2)  | [![](https://badgen.net/bundlephobia/minzip/tinycolor2?color=red&label=)](https://bundlephobia.com/result?p=tinycolor2)  | [![](https://badgen.net/bundlephobia/dependency-count/tinycolor2?color=6ead0a&label=)](https://bundlephobia.com/result?p=tinycolor2) | [![](https://badgen.net/npm/types/tinycolor2?color=e6591d&label=)](https://bundlephobia.com/result?p=tinycolor2) |
| ac-colors                     | 660,722                       | [![](https://badgen.net/bundlephobia/min/ac-colors?color=e6591d&label=)](https://bundlephobia.com/result?p=ac-colors) | [![](https://badgen.net/bundlephobia/minzip/ac-colors?color=e6591d&label=)](https://bundlephobia.com/result?p=ac-colors) | [![](https://badgen.net/bundlephobia/dependency-count/ac-colors?color=6ead0a&label=)](https://bundlephobia.com/result?p=ac-colors)   | [![](https://badgen.net/npm/types/ac-colors?color=red&label=)](https://bundlephobia.com/result?p=ac-colors)      |
| chroma-js                     | 962,967                       | [![](https://badgen.net/bundlephobia/min/chroma-js?color=red&label=)](https://bundlephobia.com/result?p=chroma-js)    | [![](https://badgen.net/bundlephobia/minzip/chroma-js?color=red&label=)](https://bundlephobia.com/result?p=chroma-js)    | [![](https://badgen.net/bundlephobia/dependency-count/chroma-js?color=red&label=)](https://bundlephobia.com/result?p=chroma-js)      | [![](https://badgen.net/npm/types/chroma-js?color=e6591d&label=)](https://bundlephobia.com/result?p=chroma-js)   |

The performance results were generated on a MBP 2019, 2,6 GHz Intel Core i7 by running `npm run benchmark` in the library folder. See [tests/benchmark.ts](https://github.com/omgovich/colord/blob/master/tests/benchmark.ts).

<div><img src="assets/divider.png" width="838" alt="---" /></div>

## Getting Started

```
npm i colord
```

```js
import { colord } from "colord";

colord("#ff0000").grayscale().alpha(0.25).toRgbString(); // "rgba(128, 128, 128, 0.25)"
colord("rgb(192, 192, 192)").isLight(); // true
colord("hsl(0, 50%, 50%)").darken(0.25).toHex(); // "#602020"
```

<div><img src="assets/divider.png" width="838" alt="---" /></div>

## Supported Color Models

- Hexadecimal strings (including 3, 4 and 8 digit notations)
- RGB strings and objects
- HSL strings and objects
- HSV objects
- Color names ([via plugin](#plugins))
- HWB objects and strings ([via plugin](#plugins))
- CMYK objects and strings ([via plugin](#plugins))
- LCH objects and strings ([via plugin](#plugins))
- LAB objects ([via plugin](#plugins))
- XYZ objects ([via plugin](#plugins))

<div><img src="assets/divider.png" width="838" alt="---" /></div>

## API

### Color parsing

<details>
  <summary><b><code>colord(input)</code></b></summary>

Parses the given input and creates a new Colord instance. String parsing strictly conforms to [CSS Color Level Specifications](https://www.w3.org/TR/css-color-4/#color-type).

```js
import { colord } from "colord";

// String input examples
colord("#FFF");
colord("#ffffff");
colord("#ffffffff");
colord("rgb(255, 255, 255)");
colord("rgba(255, 255, 255, 0.5)");
colord("rgba(100% 100% 100% / 50%)");
colord("hsl(90, 100%, 100%)");
colord("hsla(90, 100%, 100%, 0.5)");
colord("hsla(90deg 100% 100% / 50%)");
colord("tomato"); // requires "names" plugin

// Object input examples
colord({ r: 255, g: 255, b: 255 });
colord({ r: 255, g: 255, b: 255, a: 1 });
colord({ h: 360, s: 100, l: 100 });
colord({ h: 360, s: 100, l: 100, a: 1 });
colord({ h: 360, s: 100, v: 100 });
colord({ h: 360, s: 100, v: 100, a: 1 });
```

Check out the ["Plugins"](#plugins) section for more input format examples.

</details>

<details>
  <summary><b><code>getFormat(input)</code></b></summary>

Returns a color model name for the input passed to the function. Uses the same parsing system as `colord` function.

```js
import { getFormat } from "colord";

getFormat("#aabbcc"); // "hex"
getFormat({ r: 13, g: 237, b: 162, a: 0.5 }); // "rgb"
getFormat("hsl(180deg, 50%, 50%)"); // "hsl"
getFormat("WUT?"); // undefined
```

</details>

### Color conversion

<details>
  <summary><b><code>.toHex()</code></b></summary>

Returns the [hexadecimal representation](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#rgb_colors) of a color. When the alpha channel value of the color is less than 1, it outputs `#rrggbbaa` format instead of `#rrggbb`.

```js
colord("rgb(0, 255, 0)").toHex(); // "#00ff00"
colord({ h: 300, s: 100, l: 50 }).toHex(); // "#ff00ff"
colord({ r: 255, g: 255, b: 255, a: 0 }).toHex(); // "#ffffff00"
```

</details>

<details>
  <summary><b><code>.toRgb()</code></b></summary>

```js
colord("#ff0000").toRgb(); // { r: 255, g: 0, b: 0, a: 1 }
colord({ h: 180, s: 100, l: 50, a: 0.5 }).toRgb(); // { r: 0, g: 255, b: 255, a: 0.5 }
```

</details>

<details>
  <summary><b><code>.toRgbString()</code></b></summary>

```js
colord("#ff0000").toRgbString(); // "rgb(255, 0, 0)"
colord({ h: 180, s: 100, l: 50, a: 0.5 }).toRgbString(); // "rgba(0, 255, 255, 0.5)"
```

</details>

<details>
  <summary><b><code>.toHsl()</code></b></summary>

Converts a color to [HSL color space](https://en.wikipedia.org/wiki/HSL_and_HSV) and returns an object.

```js
colord("#ffff00").toHsl(); // { h: 60, s: 100, l: 50, a: 1 }
colord("rgba(0, 0, 255, 0.5) ").toHsl(); // { h: 240, s: 100, l: 50, a: 0.5 }
```

</details>

<details>
  <summary><b><code>.toHslString()</code></b></summary>

Converts a color to [HSL color space](https://en.wikipedia.org/wiki/HSL_and_HSV) and expresses it through the [functional notation](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#hsl_colors).

```js
colord("#ffff00").toHslString(); // "hsl(60, 100%, 50%)"
colord("rgba(0, 0, 255, 0.5)").toHslString(); // "hsla(240, 100%, 50%, 0.5)"
```

</details>

<details>
  <summary><b><code>.toHsv()</code></b></summary>

Converts a color to [HSV color space](https://en.wikipedia.org/wiki/HSL_and_HSV) and returns an object.

```js
colord("#ffff00").toHsv(); // { h: 60, s: 100, v: 100, a: 1 }
colord("rgba(0, 255, 255, 0.5) ").toHsv(); // { h: 180, s: 100, v: 100, a: 1 }
```

</details>

<details>
  <summary><b><code>.toName(options?)</code></b> (<b>names</b> plugin)</summary>

Converts a color to a [CSS keyword](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#color_keywords). Returns `undefined` if the color is not specified in the specs.

```js
import { colord, extend } from "colord";
import namesPlugin from "colord/plugins/names";

extend([namesPlugin]);

colord("#ff6347").toName(); // "tomato"
colord("#00ffff").toName(); // "cyan"
colord("rgba(0, 0, 0, 0)").toName(); // "transparent"

colord("#fe0000").toName(); // undefined (the color is not specified in CSS specs)
colord("#fe0000").toName({ closest: true }); // "red" (closest color available)
```

</details>

<details>
  <summary><b><code>.toCmyk()</code></b> (<b>cmyk</b> plugin)</summary>

Converts a color to [CMYK](https://en.wikipedia.org/wiki/CMYK_color_model) color space.

```js
import { colord, extend } from "colord";
import cmykPlugin from "colord/plugins/cmyk";

extend([cmykPlugin]);

colord("#ffffff").toCmyk(); // { c: 0, m: 0, y: 0, k: 0, a: 1 }
colord("#555aaa").toCmyk(); // { c: 50, m: 47, y: 0, k: 33, a: 1 }
```

</details>

<details>
  <summary><b><code>.toCmykString()</code></b> (<b>cmyk</b> plugin)</summary>

Converts a color to color space.

Converts a color to [CMYK](https://en.wikipedia.org/wiki/CMYK_color_model) color space and expresses it through the [functional notation](https://www.w3.org/TR/css-color-4/#device-cmyk)

```js
import { colord, extend } from "colord";
import cmykPlugin from "colord/plugins/cmyk";

extend([cmykPlugin]);

colord("#99ffff").toCmykString(); // "device-cmyk(40% 0% 0% 0%)"
colord("#00336680").toCmykString(); // "device-cmyk(100% 50% 0% 60% / 0.5)"
```

</details>

<details>
  <summary><b><code>.toHwb()</code></b> (<b>hwb</b> plugin)</summary>

Converts a color to [HWB (Hue-Whiteness-Blackness)](https://en.wikipedia.org/wiki/HWB_color_model) color space.

```js
import { colord, extend } from "colord";
import hwbPlugin from "colord/plugins/hwb";

extend([hwbPlugin]);

colord("#ffffff").toHwb(); // { h: 0, w: 100, b: 0, a: 1 }
colord("#555aaa").toHwb(); // { h: 236, w: 33, b: 33, a: 1 }
```

</details>

<details>
  <summary><b><code>.toHwbString()</code></b> (<b>hwb</b> plugin)</summary>

Converts a color to [HWB (Hue-Whiteness-Blackness)](https://en.wikipedia.org/wiki/HWB_color_model) color space and expresses it through the [functional notation](https://www.w3.org/TR/css-color-4/#the-hwb-notation).

```js
import { colord, extend } from "colord";
import hwbPlugin from "colord/plugins/hwb";

extend([hwbPlugin]);

colord("#999966").toHwbString(); // "hwb(60 40% 40%)"
colord("#99ffff").toHwbString(); // "hwb(180 60% 0%)"
colord("#003366").alpha(0.5).toHwbString(); // "hwb(210 0% 60% / 0.5)"
```

</details>

<details>
  <summary><b><code>.toLab()</code></b> (<b>lab</b> plugin)</summary>

Converts a color to [CIE LAB](https://en.wikipedia.org/wiki/CIELAB_color_space) color space. The conversion logic is ported from [CSS Color Module Level 4 Specification](https://www.w3.org/TR/css-color-4/#color-conversion-code).

```js
import { colord, extend } from "colord";
import labPlugin from "colord/plugins/lab";

extend([labPlugin]);

colord("#ffffff").toLab(); // { l: 100, a: 0, b: 0, alpha: 1 }
colord("#33221180").toLab(); // { l: 14.89, a: 5.77, b: 14.41, alpha: 0.5 }
```

</details>

<details>
  <summary><b><code>.toLch()</code></b> (<b>lch</b> plugin)</summary>

Converts a color to [CIE LCH](https://lea.verou.me/2020/04/lch-colors-in-css-what-why-and-how/) color space. The conversion logic is ported from [CSS Color Module Level 4 Specification](https://www.w3.org/TR/css-color-4/#color-conversion-code).

```js
import { colord, extend } from "colord";
import lchPlugin from "colord/plugins/lch";

extend([lchPlugin]);

colord("#ffffff").toLch(); // { l: 100, c: 0, h: 0, a: 1 }
colord("#213b0b").toLch(); // { l: 21.85, c: 31.95, h: 127.77, a: 1 }
```

</details>

<details>
  <summary><b><code>.toLchString()</code></b> (<b>lch</b> plugin)</summary>

Converts a color to [CIE LCH](https://lea.verou.me/2020/04/lch-colors-in-css-what-why-and-how/) color space and expresses it through the [functional notation](https://www.w3.org/TR/css-color-4/#specifying-lab-lch).

```js
import { colord, extend } from "colord";
import lchPlugin from "colord/plugins/lch";

extend([lchPlugin]);

colord("#ffffff").toLchString(); // "lch(100% 0 0)"
colord("#213b0b").alpha(0.5).toLchString(); // "lch(21.85% 31.95 127.77 / 0.5)"
```

</details>

<details>
  <summary><b><code>.toXyz()</code></b> (<b>xyz</b> plugin)</summary>

Converts a color to [CIE XYZ](https://www.sttmedia.com/colormodel-xyz) color space. The conversion logic is ported from [CSS Color Module Level 4 Specification](https://www.w3.org/TR/css-color-4/#color-conversion-code).

```js
import { colord, extend } from "colord";
import xyzPlugin from "colord/plugins/xyz";

extend([xyzPlugin]);

colord("#ffffff").toXyz(); // { x: 95.047, y: 100, z: 108.883, a: 1 }
```

</details>

### Color manipulation

<details>
  <summary><b><code>.alpha(value)</code></b></summary>

Changes the alpha channel value and returns a new `Colord` instance.

```js
colord("rgb(0, 0, 0)").alpha(0.5).toRgbString(); // "rgba(0, 0, 0, 0.5)"
```

</details>

<details>
  <summary><b><code>.invert()</code></b></summary>

Creates a new `Colord` instance containing an inverted (opposite) version of the color.

```js
colord("#ffffff").invert().toHex(); // "#000000"
colord("#aabbcc").invert().toHex(); // "#554433"
```

</details>

<details>
  <summary><b><code>.saturate(amount = 0.1)</code></b></summary>

Increases the [HSL saturation](https://en.wikipedia.org/wiki/HSL_and_HSV) of a color by the given amount.

```js
colord("#bf4040").saturate(0.25).toHex(); // "#df2020"
colord("hsl(0, 50%, 50%)").saturate(0.5).toHslString(); // "hsl(0, 100%, 50%)"
```

</details>

<details>
  <summary><b><code>.desaturate(amount = 0.1)</code></b></summary>

Decreases the [HSL saturation](https://en.wikipedia.org/wiki/HSL_and_HSV) of a color by the given amount.

```js
colord("#df2020").saturate(0.25).toHex(); // "#bf4040"
colord("hsl(0, 100%, 50%)").saturate(0.5).toHslString(); // "hsl(0, 50%, 50%)"
```

</details>

<details>
  <summary><b><code>.grayscale()</code></b></summary>

Makes a gray color with the same lightness as a source color. Same as calling `desaturate(1)`.

```js
colord("#bf4040").grayscale().toHex(); // "#808080"
colord("hsl(0, 100%, 50%)").grayscale().toHslString(); // "hsl(0, 0%, 50%)"
```

</details>

<details>
  <summary><b><code>.lighten(amount = 0.1)</code></b></summary>

Increases the [HSL lightness](https://en.wikipedia.org/wiki/HSL_and_HSV) of a color by the given amount.

```js
colord("#000000").lighten(0.5).toHex(); // "#808080"
colord("#223344").lighten(0.3).toHex(); // "#5580aa"
colord("hsl(0, 50%, 50%)").lighten(0.5).toHslString(); // "hsl(0, 50%, 100%)"
```

</details>

<details>
  <summary><b><code>.darken(amount = 0.1)</code></b></summary>

Decreases the [HSL lightness](https://en.wikipedia.org/wiki/HSL_and_HSV) of a color by the given amount.

```js
colord("#ffffff").darken(0.5).toHex(); // "#808080"
colord("#5580aa").darken(0.3).toHex(); // "#223344"
colord("hsl(0, 50%, 100%)").lighten(0.5).toHslString(); // "hsl(0, 50%, 50%)"
```

</details>

<details>
  <summary><b><code>.hue(value)</code></b></summary>

Changes the hue value and returns a new `Colord` instance.

```js
colord("hsl(90, 50%, 50%)").hue(180).toHslString(); // "hsl(180, 50%, 50%)"
colord("hsl(90, 50%, 50%)").hue(370).toHslString(); // "hsl(10, 50%, 50%)"
```

</details>

<details>
  <summary><b><code>.rotate(amount = 15)</code></b></summary>

Increases the [HSL](https://en.wikipedia.org/wiki/HSL_and_HSV) hue value of a color by the given amount.

```js
colord("hsl(90, 50%, 50%)").rotate(90).toHslString(); // "hsl(180, 50%, 50%)"
colord("hsl(90, 50%, 50%)").rotate(-180).toHslString(); // "hsl(270, 50%, 50%)"
```

</details>

<details>
  <summary><b><code>.mix(color2, ratio = 0.5)</code></b> (<b>mix</b> plugin)</summary>

Produces a mixture of two colors and returns the result of mixing them (new Colord instance).

In contrast to other libraries that perform RGB values mixing, Colord mixes colors through [LAB color space](https://en.wikipedia.org/wiki/CIELAB_color_space). This approach produces better results and doesn't have the drawbacks the legacy way has.

→ [Online demo](https://3cg7o.csb.app/)

```js
import { colord, extend } from "colord";
import mixPlugin from "colord/plugins/mix";

extend([mixPlugin]);

colord("#ffffff").mix("#000000").toHex(); // "#777777"
colord("#800080").mix("#dda0dd").toHex(); // "#af5cae"
colord("#cd853f").mix("#eee8aa", 0.6).toHex(); // "#e3c07e"
colord("#008080").mix("#808000", 0.35).toHex(); // "#50805d"
```

</details>

<details>
  <summary><b><code>.tints(count = 5)</code></b> (<b>mix</b> plugin)</summary>

Provides functionality to generate [tints](https://en.wikipedia.org/wiki/Tints_and_shades) of a color. Returns an array of `Colord` instances, including the original color.

```js
import { colord, extend } from "colord";
import mixPlugin from "colord/plugins/mix";

extend([mixPlugin]);

const color = colord("#ff0000");
color.tints(3).map((c) => c.toHex()); // ["#ff0000", "#ff9f80", "#ffffff"];
```

</details>

<details>
  <summary><b><code>.shades(count = 5)</code></b> (<b>mix</b> plugin)</summary>

Provides functionality to generate [shades](https://en.wikipedia.org/wiki/Tints_and_shades) of a color. Returns an array of `Colord` instances, including the original color.

```js
import { colord, extend } from "colord";
import mixPlugin from "colord/plugins/mix";

extend([mixPlugin]);

const color = colord("#ff0000");
color.shades(3).map((c) => c.toHex()); // ["#ff0000", "#7a1b0b", "#000000"];
```

</details>

<details>
  <summary><b><code>.tones(count = 5)</code></b> (<b>mix</b> plugin)</summary>

Provides functionality to generate [tones](https://en.wikipedia.org/wiki/Tints_and_shades) of a color. Returns an array of `Colord` instances, including the original color.

```js
import { colord, extend } from "colord";
import mixPlugin from "colord/plugins/mix";

extend([mixPlugin]);

const color = colord("#ff0000");
color.tones(3).map((c) => c.toHex()); // ["#ff0000", "#c86147", "#808080"];
```

</details>

<details>
  <summary><b><code>.harmonies(type = "complementary")</code></b> (<b>harmonies</b> plugin)</summary>

Provides functionality to generate [harmony colors](<https://en.wikipedia.org/wiki/Harmony_(color)>). Returns an array of `Colord` instances.

```js
import { colord, extend } from "colord";
import harmoniesPlugin from "colord/plugins/harmonies";

extend([harmoniesPlugin]);

const color = colord("#ff0000");
color.harmonies("analogous").map((c) => c.toHex()); // ["#ff0080", "#ff0000", "#ff8000"]
color.harmonies("complementary").map((c) => c.toHex()); // ["#ff0000", "#00ffff"]
color.harmonies("double-split-complementary").map((c) => c.toHex()); // ["#ff0080", "#ff0000", "#ff8000", "#00ff80", "#0080ff"]
color.harmonies("rectangle").map((c) => c.toHex()); // ["#ff0000", "#ffff00", "#00ffff", "#0000ff"]
color.harmonies("split-complementary").map((c) => c.toHex()); // ["#ff0000", "#00ff80", "#0080ff"]
color.harmonies("tetradic").map((c) => c.toHex()); // ["#ff0000", "#80ff00", "#00ffff", "#8000ff"]
color.harmonies("triadic").map((c) => c.toHex()); // ["#ff0000", "#00ff00", "#0000ff"]
```

</details>

### Color analysis

<details>
  <summary><b><code>.isValid()</code></b></summary>

Returns a boolean indicating whether or not an input has been parsed successfully.
Note: If parsing is unsuccessful, Colord defaults to black (does not throws an error).

```js
colord("#ffffff").isValid(); // true
colord("#wwuutt").isValid(); // false
colord("abracadabra").isValid(); // false
colord({ r: 0, g: 0, b: 0 }).isValid(); // true
colord({ r: 0, g: 0, v: 0 }).isValid(); // false
```

</details>

<details>
  <summary><b><code>.isEqual(color2)</code></b></summary>

Determines whether two values are the same color.

```js
colord("#000000").isEqual("rgb(0, 0, 0)"); // true
colord("#000000").isEqual("rgb(255, 255, 255)"); // false
```

</details>

<details>
  <summary><b><code>.alpha()</code></b></summary>

```js
colord("#ffffff").alpha(); // 1
colord("rgba(50, 100, 150, 0.5)").alpha(); // 0.5
```

</details>

<details>
  <summary><b><code>.hue()</code></b></summary>

```js
colord("hsl(90, 50%, 50%)").hue(); // 90
colord("hsl(-10, 50%, 50%)").hue(); // 350
```

</details>

<details>
  <summary><b><code>.brightness()</code></b></summary>

Returns the brightness of a color (from 0 to 1). The calculation logic is modified from [Web Content Accessibility Guidelines](https://www.w3.org/TR/AERT/#color-contrast).

```js
colord("#000000").brightness(); // 0
colord("#808080").brightness(); // 0.5
colord("#ffffff").brightness(); // 1
```

</details>

<details>
  <summary><b><code>.isLight()</code></b></summary>

Same as calling `brightness() >= 0.5`.

```js
colord("#111111").isLight(); // false
colord("#aabbcc").isLight(); // true
colord("#ffffff").isLight(); // true
```

</details>

<details>
  <summary><b><code>.isDark()</code></b></summary>

Same as calling `brightness() < 0.5`.

```js
colord("#111111").isDark(); // true
colord("#aabbcc").isDark(); // false
colord("#ffffff").isDark(); // false
```

</details>

<details>
  <summary><b><code>.luminance()</code></b> (<b>a11y</b> plugin)</summary>

Returns the relative luminance of a color, normalized to 0 for darkest black and 1 for lightest white as defined by [WCAG 2.0](https://www.w3.org/TR/WCAG20/#relativeluminancedef).

```js
colord("#000000").luminance(); // 0
colord("#808080").luminance(); // 0.22
colord("#ccddee").luminance(); // 0.71
colord("#ffffff").luminance(); // 1
```

</details>

<details>
  <summary><b><code>.contrast(color2 = "#FFF")</code></b> (<b>a11y</b> plugin)</summary>

Calculates a contrast ratio for a color pair. This luminance difference is expressed as a ratio ranging from 1 (e.g. white on white) to 21 (e.g., black on a white). [WCAG Accessibility Level AA requires](https://webaim.org/articles/contrast/) a ratio of at least 4.5 for normal text and 3 for large text.

```js
colord("#000000").contrast(); // 21 (black on white)
colord("#ffffff").contrast("#000000"); // 21 (white on black)
colord("#777777").contrast(); // 4.47 (gray on white)
colord("#ff0000").contrast(); // 3.99 (red on white)
colord("#0000ff").contrast("#ff000"); // 2.14 (blue on red)
```

</details>

<details>
  <summary><b><code>.isReadable(color2 = "#FFF", options?)</code></b> (<b>a11y</b> plugin)</summary>

Checks that a background and text color pair is readable according to [WCAG 2.0 Contrast and Color Requirements](https://webaim.org/articles/contrast/).

```js
colord("#000000").isReadable(); // true (normal black text on white bg conforms to WCAG AA)
colord("#777777").isReadable(); // false (normal gray text on white bg conforms to WCAG AA)
colord("#ffffff").isReadable("#000000"); // true (normal white text on black bg conforms to WCAG AA)
colord("#e60000").isReadable("#ffff47"); // true (normal red text on yellow bg conforms to WCAG AA)
colord("#e60000").isReadable("#ffff47", { level: "AAA" }); // false (normal red text on yellow bg does not conform to WCAG AAA)
colord("#e60000").isReadable("#ffff47", { level: "AAA", size: "large" }); // true (large red text on yellow bg conforms to WCAG AAA)
```

</details>

<details>
  <summary><b><code>.delta(color2 = "#FFF")</code></b> (<b>lab</b> plugin)</summary>

Calculates the perceived color difference between two colors.
The difference calculated according to [Delta E2000](https://en.wikipedia.org/wiki/Color_difference#CIEDE2000).
The return value is `0` if the colors are equal, `1` if they are entirely different.

```js
colord("#3296fa").delta("#197dc8"); // 0.099
colord("#faf0c8").delta("#ffffff"); // 0.148
colord("#afafaf").delta("#b4b4b4"); // 0.014
colord("#000000").delta("#ffffff"); // 1
```

</details>

### Color utilities

<details>
  <summary><b><code>random()</code></b></summary>

Returns a new Colord instance with a random color value inside.

```js
import { random } from "colord";

random().toHex(); // "#01c8ec"
random().alpha(0.5).toRgb(); // { r: 13, g: 237, b: 162, a: 0.5 }
```

</details>

<details>
  <summary><b><code>.minify(options?)</code></b></summary>

Converts a color to its shortest string representation.

```js
import { colord, extend } from "colord";
import minifyPlugin from "colord/plugins/minify";

extend([minifyPlugin]);

colord("black").minify(); // "#000"
colord("#112233").minify(); // "#123"
colord("darkgray").minify(); // "#a9a9a9"
colord("rgba(170,170,170,0.4)").minify(); // "hsla(0,0%,67%,.4)"
colord("rgba(170,170,170,0.4)").minify({ alphaHex: true }); // "#aaa6"
```

| Option        | Default | Description                                                  |
| ------------- | ------- | ------------------------------------------------------------ |
| `hex`         | `true`  | Enable `#rrggbb` and `#rgb` notations                        |
| `alphaHex`    | `false` | Enable `#rrggbbaa` and `#rgba` notations                     |
| `rgb`         | `true`  | Enable `rgb()` and `rgba()` functional notations             |
| `hsl`         | `true`  | Enable `hsl()` and `hsla()` functional notations             |
| `name`        | `false` | Enable CSS color keywords. Requires `names` plugin installed |
| `transparent` | `false` | Enable `"transparent"` color keyword                         |

</details>

<div><img src="assets/divider.png" width="838" alt="---" /></div>

## Plugins

**Colord** has a built-in plugin system that allows new features and functionality to be easily added.

<details>
  <summary><b><code>a11y</code> (Accessibility)</b> <i>0.38 KB</i></summary>

Adds accessibility and color contrast utilities working according to [Web Content Accessibility Guidelines 2.0](https://www.w3.org/TR/WCAG20/).

```js
import { colord, extend } from "colord";
import a11yPlugin from "colord/plugins/a11y";

extend([a11yPlugin]);

colord("#000000").luminance(); // 0
colord("#ccddee").luminance(); // 0.71
colord("#ffffff").luminance(); // 1

colord("#000000").contrast(); // 21 (black on white)
colord("#ffffff").contrast("#000000"); // 21 (white on black)
colord("#0000ff").contrast("#ff000"); // 2.14 (blue on red)

colord("#000000").isReadable(); // true (black on white)
colord("#ffffff").isReadable("#000000"); // true (white on black)
colord("#777777").isReadable(); // false (gray on white)
colord("#e60000").isReadable("#ffff47"); // true (normal red text on yellow bg conforms to WCAG AA)
colord("#e60000").isReadable("#ffff47", { level: "AAA" }); // false (normal red text on yellow bg does not conform to WCAG AAA)
colord("#e60000").isReadable("#ffff47", { level: "AAA", size: "large" }); // true (large red text on yellow bg conforms to WCAG AAA)
```

</details>

<details>
  <summary><b><code>cmyk</code> (CMYK color space)</b> <i>0.6 KB</i></summary>

Adds support of [CMYK](https://www.sttmedia.com/colormodel-cmyk) color model.

```js
import { colord, extend } from "colord";
import cmykPlugin from "colord/plugins/cmyk";

extend([cmykPlugin]);

colord("#ffffff").toCmyk(); // { c: 0, m: 0, y: 0, k: 0, a: 1 }
colord("#999966").toCmykString(); // "device-cmyk(0% 0% 33% 40%)"
colord({ c: 0, m: 0, y: 0, k: 100, a: 1 }).toHex(); // "#000000"
colord("device-cmyk(0% 61% 72% 0% / 50%)").toHex(); // "#ff634780"
```

</details>

<details>
  <summary><b><code>harmonies</code> (Color harmonies)</b> <i>0.15 KB</i></summary>

Provides functionality to generate [harmony colors](<https://en.wikipedia.org/wiki/Harmony_(color)>).

```js
import { colord, extend } from "colord";
import harmonies from "colord/plugins/harmonies";

extend([harmonies]);

const color = colord("#ff0000");
color.harmonies("analogous").map((c) => c.toHex()); // ["#ff0080", "#ff0000", "#ff8000"]
color.harmonies("complementary").map((c) => c.toHex()); // ["#ff0000", "#00ffff"]
color.harmonies("double-split-complementary").map((c) => c.toHex()); // ["#ff0080", "#ff0000", "#ff8000", "#00ff80", "#0080ff"]
color.harmonies("rectangle").map((c) => c.toHex()); // ["#ff0000", "#ffff00", "#00ffff", "#0000ff"]
color.harmonies("split-complementary").map((c) => c.toHex()); // ["#ff0000", "#00ff80", "#0080ff"]
color.harmonies("tetradic").map((c) => c.toHex()); // ["#ff0000", "#80ff00", "#00ffff", "#8000ff"]
color.harmonies("triadic").map((c) => c.toHex()); // ["#ff0000", "#00ff00", "#0000ff"]
```

</details>

<details>
  <summary><b><code>hwb</code> (HWB color model)</b> <i>0.8 KB</i></summary>

Adds support of [Hue-Whiteness-Blackness](https://en.wikipedia.org/wiki/HWB_color_model) color model.

```js
import { colord, extend } from "colord";
import hwbPlugin from "colord/plugins/hwb";

extend([hwbPlugin]);

colord("#999966").toHwb(); // { h: 60, w: 40, b: 40, a: 1 }
colord("#003366").toHwbString(); // "hwb(210 0% 60%)"

colord({ h: 60, w: 40, b: 40 }).toHex(); // "#999966"
colord("hwb(210 0% 60% / 50%)").toHex(); // "#00336680"
```

</details>

<details>
  <summary><b><code>lab</code> (CIE LAB color space)</b> <i>1.4 KB</i></summary>

Adds support of [CIE LAB](https://en.wikipedia.org/wiki/CIELAB_color_space) color model. The conversion logic is ported from [CSS Color Module Level 4 Specification](https://www.w3.org/TR/css-color-4/#color-conversion-code).

Also plugin provides `.delta` method for [perceived color difference calculations](https://en.wikipedia.org/wiki/Color_difference#CIEDE2000).

```js
import { colord, extend } from "colord";
import labPlugin from "colord/plugins/lab";

extend([labPlugin]);

colord({ l: 53.24, a: 80.09, b: 67.2 }).toHex(); // "#ff0000"
colord("#ffffff").toLab(); // { l: 100, a: 0, b: 0, alpha: 1 }

colord("#afafaf").delta("#b4b4b4"); // 0.014
colord("#000000").delta("#ffffff"); // 1
```

</details>

<details>
  <summary><b><code>lch</code> (CIE LCH color space)</b> <i>1.3 KB</i></summary>

Adds support of [CIE LCH](https://lea.verou.me/2020/04/lch-colors-in-css-what-why-and-how/) color space. The conversion logic is ported from [CSS Color Module Level 4 Specification](https://www.w3.org/TR/css-color-4/#color-conversion-code).

```js
import { colord, extend } from "colord";
import lchPlugin from "colord/plugins/lch";

extend([lchPlugin]);

colord({ l: 100, c: 0, h: 0 }).toHex(); // "#ffffff"
colord("lch(48.25% 30.07 196.38)").toHex(); // "#008080"

colord("#646464").toLch(); // { l: 42.37, c: 0, h: 0, a: 1 }
colord("#646464").alpha(0.5).toLchString(); // "lch(42.37% 0 0 / 0.5)"
```

</details>

<details>
  <summary><b><code>minify</code> (Color string minification)</b> <i>0.5 KB</i></summary>

A plugin adding color string minification utilities.

```js
import { colord, extend } from "colord";
import minifyPlugin from "colord/plugins/minify";

extend([minifyPlugin]);

colord("black").minify(); // "#000"
colord("#112233").minify(); // "#123"
colord("darkgray").minify(); // "#a9a9a9"
colord("rgba(170,170,170,0.4)").minify(); // "hsla(0,0%,67%,.4)"
colord("rgba(170,170,170,0.4)").minify({ alphaHex: true }); // "#aaa6"
```

</details>

<details>
  <summary><b><code>mix</code> (Color mixing)</b> <i>0.96 KB</i></summary>

A plugin adding color mixing utilities.

In contrast to other libraries that perform RGB values mixing, Colord mixes colors through [LAB color space](https://en.wikipedia.org/wiki/CIELAB_color_space). This approach produces better results and doesn't have the drawbacks the legacy way has.

→ [Online demo](https://3cg7o.csb.app/)

```js
import { colord, extend } from "colord";
import mixPlugin from "colord/plugins/mix";

extend([mixPlugin]);

colord("#ffffff").mix("#000000").toHex(); // "#777777"
colord("#800080").mix("#dda0dd").toHex(); // "#af5cae"
colord("#cd853f").mix("#eee8aa", 0.6).toHex(); // "#e3c07e"
colord("#008080").mix("#808000", 0.35).toHex(); // "#50805d"
```

Also, the plugin provides special mixtures such as [tints, shades, and tones](https://en.wikipedia.org/wiki/Tints_and_shades):

<div align="center">
<img src="https://upload.wikimedia.org/wikipedia/commons/thumb/d/d6/Tint-tone-shade.svg/320px-Tint-tone-shade.svg.png" alt="tints, shades, and tones mixtures" />
</div>

```js
const color = colord("#ff0000");
color.tints(3).map((c) => c.toHex()); // ["#ff0000", "#ff9f80", "#ffffff"];
color.shades(3).map((c) => c.toHex()); // ["#ff0000", "#7a1b0b", "#000000"];
color.tones(3).map((c) => c.toHex()); // ["#ff0000", "#c86147", "#808080"];
```

</details>

<details>
  <summary><b><code>names</code> (CSS color keywords)</b> <i>1.45 KB</i></summary>

Provides options to convert a color into a [CSS color keyword](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#color_keywords) and vice versa.

```js
import { colord, extend } from "colord";
import namesPlugin from "colord/plugins/names";

extend([namesPlugin]);

colord("tomato").toHex(); // "#ff6347"
colord("#00ffff").toName(); // "cyan"
colord("rgba(0, 0, 0, 0)").toName(); // "transparent"
colord("#fe0000").toName(); // undefined (the color is not specified in CSS specs)
colord("#fe0000").toName({ closest: true }); // "red" (closest color)
```

</details>

<details>
  <summary><b><code>xyz</code> (CIE XYZ color space)</b> <i>0.7 KB</i></summary>

Adds support of [CIE XYZ](https://www.sttmedia.com/colormodel-xyz) color model. The conversion logic is ported from [CSS Color Module Level 4 Specification](https://www.w3.org/TR/css-color-4/#color-conversion-code).

```js
import { colord, extend } from "colord";
import xyzPlugin from "colord/plugins/xyz";

extend([xyzPlugin]);

colord("#ffffff").toXyz(); // { x: 95.047, y: 100, z: 108.883, a: 1 }
colord({ x: 0, y: 0, z: 0 }).toHex(); // "#000000"
```

</details>

<div><img src="assets/divider.png" width="838" alt="---" /></div>

## Types

**Colord** is written in strict TypeScript and ships with types in the library itself — no need for any other install. We provide everything you need in one tiny package.

While not only typing its own functions and variables, **Colord** can also help you type yours. Depending on the color space you are using, you can also import and use the type that is associated with it.

```ts
import { RgbColor, RgbaColor, HslColor, HslaColor, HsvColor, HsvaColor } from "colord";

const foo: HslColor = { h: 0, s: 0, l: 0 };
const bar: RgbColor = { r: 0, g: 0, v: 0 }; // ERROR
```

<div><img src="assets/divider.png" width="838" alt="---" /></div>

## Projects using Colord

- [cssnano](https://github.com/cssnano/cssnano) — the most popular CSS minification tool
- [Resume.io](https://resume.io/) — online resume builder with over 12,000,000 users worldwide
- [Leva](https://github.com/pmndrs/leva) — open source extensible GUI panel made for React
- [Qui Max](https://github.com/Qvant-lab/qui-max) — Vue.js design system and component library
- and [thousands more](https://github.com/omgovich/colord/network/dependents)...

<div><img src="assets/divider.png" width="838" alt="---" /></div>

## Roadmap

- [x] Parse and convert Hex, RGB(A), HSL(A), HSV(A)
- [x] Saturate, desaturate, grayscale
- [x] Trim an input value
- [x] Clamp input numbers to resolve edge cases (e.g. `rgb(256, -1, 999, 2)`)
- [x] `brightness`, `isDark`, `isLight`
- [x] Set and get `alpha`
- [x] Plugin API
- [x] 4 and 8 digit Hex
- [x] `lighten`, `darken`
- [x] `invert`
- [x] CSS color names (via plugin)
- [x] A11y and contrast utils (via plugin)
- [x] XYZ color space (via plugin)
- [x] [HWB](https://drafts.csswg.org/css-color/#the-hwb-notation) color space (via plugin)
- [x] [LAB](https://www.w3.org/TR/css-color-4/#resolving-lab-lch-values) color space (via plugin)
- [x] [LCH](https://lea.verou.me/2020/04/lch-colors-in-css-what-why-and-how/) color space (via plugin)
- [x] Mix colors (via plugin)
- [x] CMYK color space (via plugin)


---

Copyright © Jorge Bucaran <<https://jorgebucaran.com>>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


---

# 🌈Colorette

> Easily set your terminal text color & styles.

- No dependecies
- Automatic color support detection
- Up to [2x faster](#benchmarks) than alternatives
- TypeScript support
- [`NO_COLOR`](https://no-color.org) friendly
- Node >= `10`

> [**Upgrading from Colorette `1.x`?**](https://github.com/jorgebucaran/colorette/issues/70)

## Quickstart

```js
import { blue, bold, underline } from "colorette"

console.log(
  blue("I'm blue"),
  bold(blue("da ba dee")),
  underline(bold(blue("da ba daa")))
)
```

Here's an example using [template literals](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals).

```js
console.log(`
  There's a ${underline(blue("house"))},
  With a ${bold(blue("window"))},
  And a ${blue("corvette")}
  And everything is blue
`)
```

You can also nest styles without breaking existing color sequences.

```js
console.log(bold(`I'm ${blue(`da ba ${underline("dee")} da ba`)} daa`))
```

Need to override terminal color detection? You can do that too.

```js
import { createColors } from "colorette"

const { blue } = createColors({ useColor: false })

console.log(blue("Blue? Nope, nah"))
```

## Installation

```console
npm install colorette
```

## API

### \<color\>()

> See all [supported colors](#supported-colors).

```js
import { blue } from "colorette"

blue("I'm blue") //=> \x1b[34mI'm blue\x1b[39m
```

### createColors()

Override terminal color detection via `createColors({ useColor })`.

```js
import { createColors } from "colorette"

const { blue } = createColors({ useColor: false })
```

### isColorSupported

`true` if your terminal supports color, `false` otherwise. Used internally, but exposed for convenience.

## Environment

You can override color detection from the CLI by setting the `--no-color` or `--color` flags.

```console
$ ./example.js --no-color | ./consumer.js
```

Or if you can't use CLI flags, by setting the `NO_COLOR=` or `FORCE_COLOR=` environment variables.

```console
$ NO_COLOR= ./example.js | ./consumer.js
```

## Supported colors

| Colors  | Background Colors | Bright Colors | Bright Background Colors | Modifiers         |
| ------- | ----------------- | ------------- | ------------------------ | ----------------- |
| black   | bgBlack           | blackBright   | bgBlackBright            | dim               |
| red     | bgRed             | redBright     | bgRedBright              | **bold**          |
| green   | bgGreen           | greenBright   | bgGreenBright            | hidden            |
| yellow  | bgYellow          | yellowBright  | bgYellowBright           | _italic_          |
| blue    | bgBlue            | blueBright    | bgBlueBright             | <u>underline</u>  |
| magenta | bgMagenta         | magentaBright | bgMagentaBright          | ~~strikethrough~~ |
| cyan    | bgCyan            | cyanBright    | bgCyanBright             | reset             |
| white   | bgWhite           | whiteBright   | bgWhiteBright            |                   |
| gray    |                   |               |                          |                   |

## [Benchmarks](https://github.com/jorgebucaran/colorette/actions/workflows/bench.yml)

```console
npm --prefix bench start
```

```diff
  chalk         1,786,703 ops/sec
  kleur         1,618,960 ops/sec
  colors          646,823 ops/sec
  ansi-colors     786,149 ops/sec
  picocolors    2,871,758 ops/sec
+ colorette     3,002,751 ops/sec
```

## Acknowledgments

Colorette started out in 2015 by [@jorgebucaran](https://github.com/jorgebucaran) as a lightweight alternative to [Chalk](https://github.com/chalk/chalk) and was introduced originally as [Clor](https://github.com/jorgebucaran/colorette/commit/b01b5b9961ceb7df878583a3002e836fae9e37ce). Our terminal color detection logic borrows heavily from [@sindresorhus](https://github.com/sindresorhus) and [@Qix-](https://github.com/Qix-) work on Chalk. The idea of slicing strings to clear bleeding sequences was adapted from a similar technique used by [@alexeyraspopov](https://github.com/alexeyraspopov) in [picocolors](https://github.com/alexeyraspopov/picocolors). Thank you to all our contributors! <3

## License

[MIT](LICENSE.md)


---

# Combine-Promises

[![NPM](https://img.shields.io/npm/dm/combine-promises.svg)](https://www.npmjs.com/package/combine-promises)
[![CI](https://github.com/slorber/combine-promises/actions/workflows/main.yml/badge.svg)](https://github.com/slorber/combine-promises/actions/workflows/main.yml)
![Size min](https://img.shields.io/bundlephobia/min/combine-promises.svg)
![Size minzip](https://img.shields.io/bundlephobia/minzip/combine-promises.svg)

Like `Promise.all([])` but for objects.

```ts
import combinePromises from 'combine-promises';

const { user, company } = await combinePromises({
  user: fetchUser(),
  company: fetchCompany(),
});
```

Why:

- Insensitive to destructuring order
- Simpler async functional code

Features:

- TypeScript support
- Lightweight
- Feature complete
- Well-tested
- ESM / CJS

--- 

# Sponsor

**[ThisWeekInReact.com](https://thisweekinreact.com)**: the best newsletter to stay up-to-date with the React ecosystem:

[![ThisWeekInReact.com banner](https://user-images.githubusercontent.com/749374/136185889-ebdb67cd-ec78-4655-b88b-79a6c134acd2.png)](https://thisweekinreact.com)

---

## Install

```
npm install combine-promises
// OR
yarn add combine-promises
```

## TypeScript support

Good, native and strict TypeScript support:

- Return type correctly inferred from the input object
- All object values should be async
- Only accept objects (reject arrays, null, undefined...)

```ts
const result: { user: User; company: Company } = await combinePromises({
  user: fetchUser(),
  company: fetchCompany(),
});
```

## Insensitive to destructuring order

A common error with `Promise.all` is to have a typo in the destructuring order.

```js
// Bad: destructuring order reversed
const [company, user] = await Promise.all([fetchUser(), fetchCompany()]);
```

This becomes more dangerous as size of the promises array grows.

With `combinePromises`, you are using explicit names instead of array indices, which makes the code more robust and not sensitive to destructuring order:

```js
// Good: we don't care about the order anymore
const { company, user } = await combinePromises({
  user: fetchUser(),
  company: fetchCompany(),
});
```

## Simpler async functional code

Suppose you have an object representing a friendship like `{user1: "userId-1", user2: "userId-2"}`, and you want to transform it to `{user1: User, user2: User}`.

You can easily do that:

```js
import combinePromises from 'combine-promises';
import { mapValues } from 'lodash'; // can be replaced by vanilla ES if you prefer

const friendsIds = { user1: 'userId-1', user2: 'userId-2' };

const friends = await combinePromises(mapValues(friendsIds, fetchUserById));
```

Without this library: good luck to keep your code simple.

## Inspirations

Name inspired by [combineReducers](https://redux.js.org/api/combinereducers) from Redux.


---

# combined-stream

A stream that emits multiple other streams one after another.

**NB** Currently `combined-stream` works with streams version 1 only. There is ongoing effort to switch this library to streams version 2. Any help is welcome. :) Meanwhile you can explore other libraries that provide streams2 support with more or less compatibility with `combined-stream`.

- [combined-stream2](https://www.npmjs.com/package/combined-stream2): A drop-in streams2-compatible replacement for the combined-stream module.

- [multistream](https://www.npmjs.com/package/multistream): A stream that emits multiple other streams one after another.

## Installation

``` bash
npm install combined-stream
```

## Usage

Here is a simple example that shows how you can use combined-stream to combine
two files into one:

``` javascript
var CombinedStream = require('combined-stream');
var fs = require('fs');

var combinedStream = CombinedStream.create();
combinedStream.append(fs.createReadStream('file1.txt'));
combinedStream.append(fs.createReadStream('file2.txt'));

combinedStream.pipe(fs.createWriteStream('combined.txt'));
```

While the example above works great, it will pause all source streams until
they are needed. If you don't want that to happen, you can set `pauseStreams`
to `false`:

``` javascript
var CombinedStream = require('combined-stream');
var fs = require('fs');

var combinedStream = CombinedStream.create({pauseStreams: false});
combinedStream.append(fs.createReadStream('file1.txt'));
combinedStream.append(fs.createReadStream('file2.txt'));

combinedStream.pipe(fs.createWriteStream('combined.txt'));
```

However, what if you don't have all the source streams yet, or you don't want
to allocate the resources (file descriptors, memory, etc.) for them right away?
Well, in that case you can simply provide a callback that supplies the stream
by calling a `next()` function:

``` javascript
var CombinedStream = require('combined-stream');
var fs = require('fs');

var combinedStream = CombinedStream.create();
combinedStream.append(function(next) {
  next(fs.createReadStream('file1.txt'));
});
combinedStream.append(function(next) {
  next(fs.createReadStream('file2.txt'));
});

combinedStream.pipe(fs.createWriteStream('combined.txt'));
```

## API

### CombinedStream.create([options])

Returns a new combined stream object. Available options are:

* `maxDataSize`
* `pauseStreams`

The effect of those options is described below.

### combinedStream.pauseStreams = `true`

Whether to apply back pressure to the underlaying streams. If set to `false`,
the underlaying streams will never be paused. If set to `true`, the
underlaying streams will be paused right after being appended, as well as when
`delayedStream.pipe()` wants to throttle.

### combinedStream.maxDataSize = `2 * 1024 * 1024`

The maximum amount of bytes (or characters) to buffer for all source streams.
If this value is exceeded, `combinedStream` emits an `'error'` event.

### combinedStream.dataSize = `0`

The amount of bytes (or characters) currently buffered by `combinedStream`.

### combinedStream.append(stream)

Appends the given `stream` to the combinedStream object. If `pauseStreams` is
set to `true, this stream will also be paused right away.

`streams` can also be a function that takes one parameter called `next`. `next`
is a function that must be invoked in order to provide the `next` stream, see
example above.

Regardless of how the `stream` is appended, combined-stream always attaches an
`'error'` listener to it, so you don't have to do that manually.

Special case: `stream` can also be a String or Buffer.

### combinedStream.write(data)

You should not call this, `combinedStream` takes care of piping the appended
streams into itself for you.

### combinedStream.resume()

Causes `combinedStream` to start drain the streams it manages. The function is
idempotent, and also emits a `'resume'` event each time which usually goes to
the stream that is currently being drained.

### combinedStream.pause();

If `combinedStream.pauseStreams` is set to `false`, this does nothing.
Otherwise a `'pause'` event is emitted, this goes to the stream that is
currently being drained, so you can use it to apply back pressure.

### combinedStream.end();

Sets `combinedStream.writable` to false, emits an `'end'` event, and removes
all streams from the queue.

### combinedStream.destroy();

Same as `combinedStream.end()`, except it emits a `'close'` event instead of
`'end'`.

## License

combined-stream is licensed under the MIT license.


---

# comma-separated-tokens

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]

Parse and stringify comma-separated tokens.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`parse(value)`](#parsevalue)
    *   [`stringify(values[, options])`](#stringifyvalues-options)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Related](#related)
*   [Contribute](#contribute)
*   [Security](#security)
*   [License](#license)

## What is this?

This is a tiny package that can parse and stringify comma-separated tokens, as
used for example in the HTML `accept` attribute, according to the
[WHATWG spec][spec].

## When should I use this?

This package is rather niche, it’s low-level and particularly useful when
working with [hast][].

## Install

This package is [ESM only][esm].
In Node.js (version 14.14+, 16.0+), install with [npm][]:

```sh
npm install comma-separated-tokens
```

In Deno with [`esm.sh`][esmsh]:

```js
import {parse, stringify} from 'https://esm.sh/comma-separated-tokens@2'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {parse, stringify} from 'https://esm.sh/comma-separated-tokens@2?bundle'
</script>
```

## Use

```js
import {parse, stringify} from 'comma-separated-tokens'

parse(' a ,b,,d d ') //=> ['a', 'b', '', 'd d']
stringify(['a', 'b', '', 'd d']) //=> 'a, b, , d d'
```

## API

This package exports the identifier `parse` and `stringify`.
There is no default export.

### `parse(value)`

Parse commma-separated tokens (`string`) to an array of strings
(`Array<string>`), according to the [WHATWG spec][spec].

### `stringify(values[, options])`

Serialize an array of strings or numbers (`Array<string|number>`) to
comma-separated tokens (`string`).
Handles empty items at start or end correctly.

> 👉 **Note**: it’s not possible to specify initial or final whitespace per
> value.

##### `options`

Configuration (optional).

###### `options.padLeft`

Whether to pad a space before a token (`boolean`, default: `true`).

###### `options.padRight`

Whether to pad a space after a token (`boolean`, default: `false`).

## Types

This package is fully typed with [TypeScript][].
It exports the additional type `Options`.

## Compatibility

This package is at least compatible with all maintained versions of Node.js.
As of now, that is Node.js 14.14+ and 16.0+.
It also works in Deno and modern browsers.

## Related

*   [`space-separated-tokens`](https://github.com/wooorm/space-separated-tokens)
    — parse/stringify space-separated tokens
*   [`collapse-white-space`](https://github.com/wooorm/collapse-white-space)
    — replace multiple white-space characters with a single space
*   [`property-information`](https://github.com/wooorm/property-information)
    — info on HTML properties

## Contribute

Yes please!
See [How to Contribute to Open Source][contribute].

## Security

This package is safe.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/wooorm/comma-separated-tokens/workflows/main/badge.svg

[build]: https://github.com/wooorm/comma-separated-tokens/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/comma-separated-tokens.svg

[coverage]: https://codecov.io/github/wooorm/comma-separated-tokens

[downloads-badge]: https://img.shields.io/npm/dm/comma-separated-tokens.svg

[downloads]: https://www.npmjs.com/package/comma-separated-tokens

[size-badge]: https://img.shields.io/bundlephobia/minzip/comma-separated-tokens.svg

[size]: https://bundlephobia.com/result?p=comma-separated-tokens

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[typescript]: https://www.typescriptlang.org

[contribute]: https://opensource.guide/how-to-contribute/

[license]: license

[author]: https://wooorm.com

[spec]: https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#comma-separated-tokens

[hast]: https://github.com/syntax-tree/hast


---

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html). (Format adopted after v3.0.0.)

<!-- markdownlint-disable MD024 -->

## [5.1.0] (2020-04-25)

### Added

- support for multiple command aliases, the first of which is shown in the auto-generated help ([#531], [#1236])
- configuration support in `addCommand()` for `hidden` and `isDefault` ([#1232])

### Fixed

- omit masked help flags from the displayed help ([#645], [#1247])
- remove old short help flag when change help flags using `helpOption` ([#1248])

### Changed

- remove use of `arguments` to improve auto-generated help in editors ([#1235])
- rename `.command()` configuration `noHelp` to `hidden` (but not remove old support) ([#1232])
- improvements to documentation
- update dependencies
- update tested versions of node
- eliminate lint errors in TypeScript ([#1208])

## [5.0.0] (2020-03-14)

### Added

* support for nested commands with action-handlers ([#1] [#764] [#1149])
* `.addCommand()` for adding a separately configured command ([#764] [#1149])
* allow a non-executable to be set as the default command ([#742] [#1149])
* implicit help command when there are subcommands (previously only if executables) ([#1149])
* customise implicit help command with `.addHelpCommand()` ([#1149])
* display error message for unknown subcommand, by default ([#432] [#1088] [#1149])
* display help for missing subcommand, by default ([#1088] [#1149])
* combined short options as single argument may include boolean flags and value flag and value (e.g. `-a -b -p 80` can be written as `-abp80`) ([#1145])
* `.parseOption()` includes short flag and long flag expansions ([#1145])
* `.helpInformation()` returns help text as a string, previously a private routine ([#1169])
* `.parse()` implicitly uses `process.argv` if arguments not specified ([#1172])
* optionally specify where `.parse()` arguments "from", if not following node conventions ([#512] [#1172])
* suggest help option along with unknown command error ([#1179])
* TypeScript definition for `commands` property of `Command` ([#1184])
* export `program` property ([#1195])
* `createCommand` factory method to simplify subclassing ([#1191])

### Fixed

* preserve argument order in subcommands ([#508] [#962] [#1138])
* do not emit `command:*` for executable subcommands ([#809] [#1149])
* action handler called whether or not there are non-option arguments ([#1062] [#1149])
* combining option short flag and value in single argument now works for subcommands ([#1145])
* only add implicit help command when it will not conflict with other uses of argument ([#1153] [#1149])
* implicit help command works with command aliases ([#948] [#1149])
* options are validated whether or not there is an action handler ([#1149])

### Changed

* *Breaking* `.args` contains command arguments with just recognised options removed ([#1032] [#1138])
* *Breaking* display error if required argument for command is missing ([#995] [#1149])
* tighten TypeScript definition of custom option processing function passed to `.option()` ([#1119])
* *Breaking* `.allowUnknownOption()` ([#802] [#1138])
  * unknown options included in arguments passed to command action handler
  * unknown options included in `.args`
* only recognised option short flags and long flags are expanded (e.g. `-ab` or `--foo=bar`) ([#1145])
* *Breaking* `.parseOptions()` ([#1138])
  * `args` in returned result renamed `operands` and does not include anything after first unknown option
  * `unknown` in returned result has arguments after first unknown option including operands, not just options and values
* *Breaking* `.on('command:*', callback)` and other command events passed (changed) results from `.parseOptions`, i.e. operands and unknown  ([#1138])
* refactor Option from prototype to class ([#1133])
* refactor Command from prototype to class ([#1159])
* changes to error handling ([#1165])
  * throw for author error, not just display message
  * preflight for variadic error
  * add tips to missing subcommand executable
* TypeScript fluent return types changed to be more subclass friendly, return `this` rather than `Command` ([#1180])
* `.parseAsync` returns `Promise<this>` to be consistent with `.parse()` ([#1180])
* update dependencies

### Removed

* removed EventEmitter from TypeScript definition for Command, eliminating implicit peer dependency on `@types/node` ([#1146])
* removed private function `normalize` (the functionality has been integrated into `parseOptions`) ([#1145])
* `parseExpectedArgs` is now private ([#1149])

### Migration Tips

If you use `.on('command:*')` or more complicated tests to detect an unrecognised subcommand, you may be able to delete the code and rely on the default behaviour.

If you use `program.args` or more complicated tests to detect a missing subcommand, you may be able to delete the code and rely on the default behaviour.

If you use `.command('*')` to add a default command, you may be be able to switch to `isDefault:true` with a named command.

## [5.0.0-4] (2020-03-03)

(Released in 5.0.0)

## [5.0.0-3] (2020-02-20)

(Released in 5.0.0)

## [5.0.0-2] (2020-02-10)

(Released in 5.0.0)

## [5.0.0-1] (2020-02-08)

(Released in 5.0.0)

## [5.0.0-0] (2020-02-02)

(Released in 5.0.0)

## [4.1.1] (2020-02-02)

### Fixed

* TypeScript definition for `.action()` should include Promise for async ([#1157])

## [4.1.0] (2020-01-06)

### Added

* two routines to change how option values are handled, and eliminate name clashes with command properties ([#933] [#1102])
  * see storeOptionsAsProperties and passCommandToAction in README
* `.parseAsync` to use instead of `.parse` if supply async action handlers ([#806] [#1118])

### Fixed

* Remove trailing blanks from wrapped help text ([#1096])

### Changed

* update dependencies
* extend security coverage for Commander 2.x to 2020-02-03
* improvements to README
* improvements to TypeScript definition documentation
* move old versions out of main CHANGELOG
* removed explicit use of `ts-node` in tests

## [4.0.1] (2019-11-12)

### Fixed

* display help when requested, even if there are missing required options ([#1091])

## [4.0.0] (2019-11-02)

### Added

* automatically wrap and indent help descriptions for options and commands ([#1051])
* `.exitOverride()` allows override of calls to `process.exit` for additional error handling and to keep program running ([#1040])
* support for declaring required options with `.requiredOptions()` ([#1071])
* GitHub Actions support ([#1027])
* translation links in README

### Changed

* dev: switch tests from Sinon+Should to Jest with major rewrite of tests ([#1035])
* call default subcommand even when there are unknown options ([#1047])
* *Breaking* Commander is only officially supported on Node 8 and above, and requires Node 6 ([#1053])

### Fixed

* *Breaking* keep command object out of program.args when action handler called ([#1048])
  * also, action handler now passed array of unknown arguments
* complain about unknown options when program argument supplied and action handler ([#1049])
  * this changes parameters to `command:*` event to include unknown arguments
* removed deprecated `customFds` option from call to `child_process.spawn` ([#1052])
* rework TypeScript declarations to bring all types into imported namespace ([#1081])

### Migration Tips

#### Testing for no arguments

If you were previously using code like:

```js
if (!program.args.length) ...
```

a partial replacement is:

```js
if (program.rawArgs.length < 3) ...
```

## [4.0.0-1] Prerelease (2019-10-08)

(Released in 4.0.0)

## [4.0.0-0] Prerelease (2019-10-01)

(Released in 4.0.0)

## [2.20.1] (2019-09-29)

### Fixed

* Improve tracking of executable subcommands.

### Changed

* update development dependencies

## [3.0.2] (2019-09-27)

### Fixed

* Improve tracking of executable subcommands.

### Changed

* update development dependencies

## [3.0.1] (2019-08-30)

### Added

* .name and .usage to README ([#1010])
* Table of Contents to README ([#1010])
* TypeScript definition for `executableFile` in CommandOptions ([#1028])

### Changed

* consistently use `const` rather than `var` in README ([#1026])

### Fixed

* help for sub commands with custom executableFile ([#1018])

## [3.0.0] / 2019-08-08

* Add option to specify executable file name ([#999])
  * e.g. `.command('clone', 'clone description', { executableFile: 'myClone' })`
* Change docs for `.command` to contrast action handler vs git-style executable. ([#938] [#990])
* **Breaking** Change TypeScript to use overloaded function for `.command`. ([#938] [#990])
* Change to use straight quotes around strings in error messages (like 'this' instead of `this') ([#915])
* Add TypeScript "reference types" for node ([#974])
* Add support for hyphen as an option argument in subcommands ([#697])
* Add support for a short option flag and its value to be concatenated for action handler subcommands ([#599])
  * e.g. `-p 80` can also be supplied as `-p80`
* Add executable arguments to spawn in win32, for git-style executables ([#611])
  * e.g. `node --harmony myCommand.js clone`
* Add parent command as prefix of subcommand in help ([#980])
* Add optional custom description to `.version` ([#963])
  * e.g. `program.version('0.0.1', '-v, --vers', 'output the current version')`
* Add `.helpOption(flags, description)` routine to customise help flags and description ([#963])
  * e.g. `.helpOption('-e, --HELP', 'read more information')`
* Fix behavior of --no-* options ([#795])
  * can now define both `--foo` and `--no-foo`
  * **Breaking** custom event listeners: `--no-foo` on cli now emits `option:no-foo` (previously `option:foo`)
  * **Breaking** default value: defining `--no-foo` after defining `--foo` leaves the default value unchanged (previously set it to false)
  * allow boolean default value, such as from environment ([#987])
* Increment inspector port for spawned subcommands ([#991])
  * e.g. `node --inspect myCommand.js clone`

### Migration Tips

The custom event for a negated option like `--no-foo` is `option:no-foo` (previously `option:foo`).

```js
program
  .option('--no-foo')
  .on('option:no-foo', () => {
    console.log('removing foo');
  });
```

When using TypeScript, adding a command does not allow an explicit `undefined` for an unwanted executable description (e.g
for a command with an action handler).

```js
program
  .command('action1', undefined, { noHelp: true }) // No longer valid
  .command('action2', { noHelp: true }) // Correct
```

## 3.0.0-0 Prerelease / 2019-07-28

(Released as 3.0.0)

## Older versions

* [2.x](./changelogs/CHANGELOG-2.md)
* [1.x](./changelogs/CHANGELOG-1.md)
* [0.x](./changelogs/CHANGELOG-0.md)

[#1]: https://github.com/tj/commander.js/issues/1
[#432]: https://github.com/tj/commander.js/issues/432
[#508]: https://github.com/tj/commander.js/issues/508
[#512]: https://github.com/tj/commander.js/issues/512
[#531]: https://github.com/tj/commander.js/issues/531
[#599]: https://github.com/tj/commander.js/issues/599
[#611]: https://github.com/tj/commander.js/issues/611
[#645]: https://github.com/tj/commander.js/issues/645
[#697]: https://github.com/tj/commander.js/issues/697
[#742]: https://github.com/tj/commander.js/issues/742
[#764]: https://github.com/tj/commander.js/issues/764
[#795]: https://github.com/tj/commander.js/issues/795
[#802]: https://github.com/tj/commander.js/issues/802
[#806]: https://github.com/tj/commander.js/issues/806
[#809]: https://github.com/tj/commander.js/issues/809
[#915]: https://github.com/tj/commander.js/issues/915
[#938]: https://github.com/tj/commander.js/issues/938
[#948]: https://github.com/tj/commander.js/issues/948
[#962]: https://github.com/tj/commander.js/issues/962
[#963]: https://github.com/tj/commander.js/issues/963
[#974]: https://github.com/tj/commander.js/issues/974
[#980]: https://github.com/tj/commander.js/issues/980
[#987]: https://github.com/tj/commander.js/issues/987
[#990]: https://github.com/tj/commander.js/issues/990
[#991]: https://github.com/tj/commander.js/issues/991
[#993]: https://github.com/tj/commander.js/issues/993
[#995]: https://github.com/tj/commander.js/issues/995
[#999]: https://github.com/tj/commander.js/issues/999
[#1010]: https://github.com/tj/commander.js/pull/1010
[#1018]: https://github.com/tj/commander.js/pull/1018
[#1026]: https://github.com/tj/commander.js/pull/1026
[#1027]: https://github.com/tj/commander.js/pull/1027
[#1028]: https://github.com/tj/commander.js/pull/1028
[#1032]: https://github.com/tj/commander.js/issues/1032
[#1035]: https://github.com/tj/commander.js/pull/1035
[#1040]: https://github.com/tj/commander.js/pull/1040
[#1047]: https://github.com/tj/commander.js/pull/1047
[#1048]: https://github.com/tj/commander.js/pull/1048
[#1049]: https://github.com/tj/commander.js/pull/1049
[#1051]: https://github.com/tj/commander.js/pull/1051
[#1052]: https://github.com/tj/commander.js/pull/1052
[#1053]: https://github.com/tj/commander.js/pull/1053
[#1062]: https://github.com/tj/commander.js/pull/1062
[#1071]: https://github.com/tj/commander.js/pull/1071
[#1081]: https://github.com/tj/commander.js/pull/1081
[#1088]: https://github.com/tj/commander.js/issues/1088
[#1091]: https://github.com/tj/commander.js/pull/1091
[#1096]: https://github.com/tj/commander.js/pull/1096
[#1102]: https://github.com/tj/commander.js/pull/1102
[#1118]: https://github.com/tj/commander.js/pull/1118
[#1119]: https://github.com/tj/commander.js/pull/1119
[#1133]: https://github.com/tj/commander.js/pull/1133
[#1138]: https://github.com/tj/commander.js/pull/1138
[#1145]: https://github.com/tj/commander.js/pull/1145
[#1146]: https://github.com/tj/commander.js/pull/1146
[#1149]: https://github.com/tj/commander.js/pull/1149
[#1153]: https://github.com/tj/commander.js/issues/1153
[#1157]: https://github.com/tj/commander.js/pull/1157
[#1159]: https://github.com/tj/commander.js/pull/1159
[#1165]: https://github.com/tj/commander.js/pull/1165
[#1169]: https://github.com/tj/commander.js/pull/1169
[#1172]: https://github.com/tj/commander.js/pull/1172
[#1179]: https://github.com/tj/commander.js/pull/1179
[#1180]: https://github.com/tj/commander.js/pull/1180
[#1184]: https://github.com/tj/commander.js/pull/1184
[#1191]: https://github.com/tj/commander.js/pull/1191
[#1195]: https://github.com/tj/commander.js/pull/1195
[#1208]: https://github.com/tj/commander.js/pull/1208
[#1232]: https://github.com/tj/commander.js/pull/1232
[#1235]: https://github.com/tj/commander.js/pull/1235
[#1236]: https://github.com/tj/commander.js/pull/1236
[#1247]: https://github.com/tj/commander.js/pull/1247
[#1248]: https://github.com/tj/commander.js/pull/1248

[Unreleased]: https://github.com/tj/commander.js/compare/master...develop
[5.1.0]: https://github.com/tj/commander.js/compare/v5.0.0..v5.1.0
[5.0.0]: https://github.com/tj/commander.js/compare/v4.1.1..v5.0.0
[5.0.0-4]: https://github.com/tj/commander.js/compare/v5.0.0-3..v5.0.0-4
[5.0.0-3]: https://github.com/tj/commander.js/compare/v5.0.0-2..v5.0.0-3
[5.0.0-2]: https://github.com/tj/commander.js/compare/v5.0.0-1..v5.0.0-2
[5.0.0-1]: https://github.com/tj/commander.js/compare/v5.0.0-0..v5.0.0-1
[5.0.0-0]: https://github.com/tj/commander.js/compare/v4.1.1..v5.0.0-0
[4.1.1]: https://github.com/tj/commander.js/compare/v4.1.0..v4.1.1
[4.1.0]: https://github.com/tj/commander.js/compare/v4.0.1..v4.1.0
[4.0.1]: https://github.com/tj/commander.js/compare/v4.0.0..v4.0.1
[4.0.0]: https://github.com/tj/commander.js/compare/v3.0.2..v4.0.0
[4.0.0-1]: https://github.com/tj/commander.js/compare/v4.0.0-0..v4.0.0-1
[4.0.0-0]: https://github.com/tj/commander.js/compare/v3.0.2...v4.0.0-0
[3.0.2]: https://github.com/tj/commander.js/compare/v3.0.1...v3.0.2
[3.0.1]: https://github.com/tj/commander.js/compare/v3.0.0...v3.0.1
[3.0.0]: https://github.com/tj/commander.js/compare/v2.20.1...v3.0.0
[2.20.1]: https://github.com/tj/commander.js/compare/v2.20.0...v2.20.1


---

# Commander.js

[![Build Status](https://api.travis-ci.org/tj/commander.js.svg?branch=master)](http://travis-ci.org/tj/commander.js)
[![NPM Version](http://img.shields.io/npm/v/commander.svg?style=flat)](https://www.npmjs.org/package/commander)
[![NPM Downloads](https://img.shields.io/npm/dm/commander.svg?style=flat)](https://npmcharts.com/compare/commander?minimal=true)
[![Install Size](https://packagephobia.now.sh/badge?p=commander)](https://packagephobia.now.sh/result?p=commander)

The complete solution for [node.js](http://nodejs.org) command-line interfaces, inspired by Ruby's [commander](https://github.com/commander-rb/commander).

Read this in other languages: English | [简体中文](./Readme_zh-CN.md)

- [Commander.js](#commanderjs)
  - [Installation](#installation)
  - [Declaring _program_ variable](#declaring-program-variable)
  - [Options](#options)
    - [Common option types, boolean and value](#common-option-types-boolean-and-value)
    - [Default option value](#default-option-value)
    - [Other option types, negatable boolean and flag|value](#other-option-types-negatable-boolean-and-flagvalue)
    - [Custom option processing](#custom-option-processing)
    - [Required option](#required-option)
    - [Version option](#version-option)
  - [Commands](#commands)
    - [Specify the argument syntax](#specify-the-argument-syntax)
    - [Action handler (sub)commands](#action-handler-subcommands)
    - [Stand-alone executable (sub)commands](#stand-alone-executable-subcommands)
  - [Automated help](#automated-help)
    - [Custom help](#custom-help)
    - [.usage and .name](#usage-and-name)
    - [.help(cb)](#helpcb)
    - [.outputHelp(cb)](#outputhelpcb)
    - [.helpInformation()](#helpinformation)
    - [.helpOption(flags, description)](#helpoptionflags-description)
    - [.addHelpCommand()](#addhelpcommand)
  - [Custom event listeners](#custom-event-listeners)
  - [Bits and pieces](#bits-and-pieces)
    - [.parse() and .parseAsync()](#parse-and-parseasync)
    - [Avoiding option name clashes](#avoiding-option-name-clashes)
    - [TypeScript](#typescript)
    - [createCommand()](#createcommand)
    - [Node options such as `--harmony`](#node-options-such-as---harmony)
    - [Debugging stand-alone executable subcommands](#debugging-stand-alone-executable-subcommands)
    - [Override exit handling](#override-exit-handling)
  - [Examples](#examples)
  - [License](#license)
  - [Support](#support)
    - [Commander for enterprise](#commander-for-enterprise)

## Installation

```bash
npm install commander
```

## Declaring _program_ variable

Commander exports a global object which is convenient for quick programs.
This is used in the examples in this README for brevity.

```js
const { program } = require('commander');
program.version('0.0.1');
```

For larger programs which may use commander in multiple ways, including unit testing, it is better to create a local Command object to use.

 ```js
 const { Command } = require('commander');
 const program = new Command();
 program.version('0.0.1');
 ```

## Options

Options are defined with the `.option()` method, also serving as documentation for the options. Each option can have a short flag (single character) and a long name, separated by a comma or space or vertical bar ('|').

The options can be accessed as properties on the Command object. Multi-word options such as "--template-engine" are camel-cased, becoming `program.templateEngine` etc. See also optional new behaviour to [avoid name clashes](#avoiding-option-name-clashes).

Multiple short flags may optionally be combined in a single argument following the dash: boolean flags, the last flag may take a value, and the value.
For example `-a -b -p 80` may be written as `-ab -p80` or even `-abp80`.

You can use `--` to indicate the end of the options, and any remaining arguments will be used without being interpreted.
This is particularly useful for passing options through to another
command, like: `do -- git --version`.

Options on the command line are not positional, and can be specified before or after other command arguments.

### Common option types, boolean and value

The two most used option types are a boolean flag, and an option which takes a value (declared using angle brackets). Both are `undefined` unless specified on command line.

```js
const { program } = require('commander');

program
  .option('-d, --debug', 'output extra debugging')
  .option('-s, --small', 'small pizza size')
  .option('-p, --pizza-type <type>', 'flavour of pizza');

program.parse(process.argv);

if (program.debug) console.log(program.opts());
console.log('pizza details:');
if (program.small) console.log('- small pizza size');
if (program.pizzaType) console.log(`- ${program.pizzaType}`);
```

```bash
$ pizza-options -d
{ debug: true, small: undefined, pizzaType: undefined }
pizza details:
$ pizza-options -p
error: option '-p, --pizza-type <type>' argument missing
$ pizza-options -ds -p vegetarian
{ debug: true, small: true, pizzaType: 'vegetarian' }
pizza details:
- small pizza size
- vegetarian
$ pizza-options --pizza-type=cheese
pizza details:
- cheese
```

`program.parse(arguments)` processes the arguments, leaving any args not consumed by the program options in the `program.args` array.

### Default option value

You can specify a default value for an option which takes a value.

```js
const { program } = require('commander');

program
  .option('-c, --cheese <type>', 'add the specified type of cheese', 'blue');

program.parse(process.argv);

console.log(`cheese: ${program.cheese}`);
```

```bash
$ pizza-options
cheese: blue
$ pizza-options --cheese stilton
cheese: stilton
```

### Other option types, negatable boolean and flag|value

You can specify a boolean option long name with a leading `no-` to set the option value to false when used.
Defined alone this also makes the option true by default.

If you define `--foo` first, adding `--no-foo` does not change the default value from what it would
otherwise be. You can specify a default boolean value for a boolean flag and it can be overridden on command line.

```js
const { program } = require('commander');

program
  .option('--no-sauce', 'Remove sauce')
  .option('--cheese <flavour>', 'cheese flavour', 'mozzarella')
  .option('--no-cheese', 'plain with no cheese')
  .parse(process.argv);

const sauceStr = program.sauce ? 'sauce' : 'no sauce';
const cheeseStr = (program.cheese === false) ? 'no cheese' : `${program.cheese} cheese`;
console.log(`You ordered a pizza with ${sauceStr} and ${cheeseStr}`);
```

```bash
$ pizza-options
You ordered a pizza with sauce and mozzarella cheese
$ pizza-options --sauce
error: unknown option '--sauce'
$ pizza-options --cheese=blue
You ordered a pizza with sauce and blue cheese
$ pizza-options --no-sauce --no-cheese
You ordered a pizza with no sauce and no cheese
```

You can specify an option which functions as a flag but may also take a value (declared using square brackets).

```js
const { program } = require('commander');

program
  .option('-c, --cheese [type]', 'Add cheese with optional type');

program.parse(process.argv);

if (program.cheese === undefined) console.log('no cheese');
else if (program.cheese === true) console.log('add cheese');
else console.log(`add cheese type ${program.cheese}`);
```

```bash
$ pizza-options
no cheese
$ pizza-options --cheese
add cheese
$ pizza-options --cheese mozzarella
add cheese type mozzarella
```

### Custom option processing

You may specify a function to do custom processing of option values. The callback function receives two parameters, the user specified value and the
previous value for the option. It returns the new value for the option.

This allows you to coerce the option value to the desired type, or accumulate values, or do entirely custom processing.

You can optionally specify the default/starting value for the option after the function.

```js
const { program } = require('commander');

function myParseInt(value, dummyPrevious) {
  // parseInt takes a string and an optional radix
  return parseInt(value);
}

function increaseVerbosity(dummyValue, previous) {
  return previous + 1;
}

function collect(value, previous) {
  return previous.concat([value]);
}

function commaSeparatedList(value, dummyPrevious) {
  return value.split(',');
}

program
  .option('-f, --float <number>', 'float argument', parseFloat)
  .option('-i, --integer <number>', 'integer argument', myParseInt)
  .option('-v, --verbose', 'verbosity that can be increased', increaseVerbosity, 0)
  .option('-c, --collect <value>', 'repeatable value', collect, [])
  .option('-l, --list <items>', 'comma separated list', commaSeparatedList)
;

program.parse(process.argv);

if (program.float !== undefined) console.log(`float: ${program.float}`);
if (program.integer !== undefined) console.log(`integer: ${program.integer}`);
if (program.verbose > 0) console.log(`verbosity: ${program.verbose}`);
if (program.collect.length > 0) console.log(program.collect);
if (program.list !== undefined) console.log(program.list);
```

```bash
$ custom -f 1e2
float: 100
$ custom --integer 2
integer: 2
$ custom -v -v -v
verbose: 3
$ custom -c a -c b -c c
[ 'a', 'b', 'c' ]
$ custom --list x,y,z
[ 'x', 'y', 'z' ]
```

### Required option

You may specify a required (mandatory) option using `.requiredOption`. The option must have a value after parsing, usually specified on the command line, or perhaps from a default value (say from environment). The method is otherwise the same as `.option` in format, taking flags and description, and optional default value or custom processing.

```js
const { program } = require('commander');

program
  .requiredOption('-c, --cheese <type>', 'pizza must have cheese');

program.parse(process.argv);
```

```bash
$ pizza
error: required option '-c, --cheese <type>' not specified
```

### Version option

The optional `version` method adds handling for displaying the command version. The default option flags are `-V` and `--version`, and when present the command prints the version number and exits.

```js
program.version('0.0.1');
```

```bash
$ ./examples/pizza -V
0.0.1
```

You may change the flags and description by passing additional parameters to the `version` method, using
the same syntax for flags as the `option` method. The version flags can be named anything, but a long name is required.

```js
program.version('0.0.1', '-v, --vers', 'output the current version');
```

## Commands

You can specify (sub)commands using `.command()` or `.addCommand()`. There are two ways these can be implemented: using an action handler attached to the command, or as a stand-alone executable file (described in more detail later). The subcommands may be nested ([example](./examples/nestedCommands.js)).

In the first parameter to `.command()` you specify the command name and any command arguments. The arguments may be `<required>` or `[optional]`, and the last argument may also be `variadic...`.

You can use `.addCommand()` to add an already configured subcommand to the program.

For example:

```js
// Command implemented using action handler (description is supplied separately to `.command`)
// Returns new command for configuring.
program
  .command('clone <source> [destination]')
  .description('clone a repository into a newly created directory')
  .action((source, destination) => {
    console.log('clone command called');
  });

// Command implemented using stand-alone executable file (description is second parameter to `.command`)
// Returns `this` for adding more commands.
program
  .command('start <service>', 'start named service')
  .command('stop [service]', 'stop named service, or all if no name supplied');

// Command prepared separately.
// Returns `this` for adding more commands.
program
  .addCommand(build.makeBuildCommand());
```

Configuration options can be passed with the call to `.command()` and `.addCommand()`. Specifying `true` for `opts.hidden` will remove the command from the generated help output. Specifying `true` for `opts.isDefault` will run the subcommand if no other subcommand is specified ([example](./examples/defaultCommand.js)).

### Specify the argument syntax

You use `.arguments` to specify the arguments for the top-level command, and for subcommands they are usually included in the `.command` call. Angled brackets (e.g. `<required>`) indicate required input. Square brackets (e.g. `[optional]`) indicate optional input.

```js
const { program } = require('commander');

program
  .version('0.1.0')
  .arguments('<cmd> [env]')
  .action(function (cmd, env) {
    cmdValue = cmd;
    envValue = env;
  });

program.parse(process.argv);

if (typeof cmdValue === 'undefined') {
  console.error('no command given!');
  process.exit(1);
}
console.log('command:', cmdValue);
console.log('environment:', envValue || "no environment given");
```

 The last argument of a command can be variadic, and only the last argument.  To make an argument variadic you
 append `...` to the argument name. For example:

```js
const { program } = require('commander');

program
  .version('0.1.0')
  .command('rmdir <dir> [otherDirs...]')
  .action(function (dir, otherDirs) {
    console.log('rmdir %s', dir);
    if (otherDirs) {
      otherDirs.forEach(function (oDir) {
        console.log('rmdir %s', oDir);
      });
    }
  });

program.parse(process.argv);
```

The variadic argument is passed to the action handler as an array.

### Action handler (sub)commands

You can add options to a command that uses an action handler.
The action handler gets passed a parameter for each argument you declared, and one additional argument which is the
command object itself. This command argument has the values for the command-specific options added as properties.

```js
const { program } = require('commander');

program
  .command('rm <dir>')
  .option('-r, --recursive', 'Remove recursively')
  .action(function (dir, cmdObj) {
    console.log('remove ' + dir + (cmdObj.recursive ? ' recursively' : ''))
  })

program.parse(process.argv)
```

You may supply an `async` action handler, in which case you call `.parseAsync` rather than `.parse`.

```js
async function run() { /* code goes here */ }

async function main() {
  program
    .command('run')
    .action(run);
  await program.parseAsync(process.argv);
}
```

A command's options on the command line are validated when the command is used. Any unknown options will be reported as an error.

### Stand-alone executable (sub)commands

When `.command()` is invoked with a description argument, this tells Commander that you're going to use stand-alone executables for subcommands.
Commander will search the executables in the directory of the entry script (like `./examples/pm`) with the name `program-subcommand`, like `pm-install`, `pm-search`.
You can specify a custom name with the `executableFile` configuration option.

You handle the options for an executable (sub)command in the executable, and don't declare them at the top-level.

```js
// file: ./examples/pm
const { program } = require('commander');

program
  .version('0.1.0')
  .command('install [name]', 'install one or more packages')
  .command('search [query]', 'search with optional query')
  .command('update', 'update installed packages', {executableFile: 'myUpdateSubCommand'})
  .command('list', 'list packages installed', {isDefault: true})
  .parse(process.argv);
```

If the program is designed to be installed globally, make sure the executables have proper modes, like `755`.

## Automated help

The help information is auto-generated based on the information commander already knows about your program. The default
help option is `-h,--help`. ([example](./examples/pizza))

```bash
$ node ./examples/pizza --help
Usage: pizza [options]

An application for pizzas ordering

Options:
  -V, --version        output the version number
  -p, --peppers        Add peppers
  -c, --cheese <type>  Add the specified type of cheese (default: "marble")
  -C, --no-cheese      You do not want any cheese
  -h, --help           display help for command
```

A `help` command is added by default if your command has subcommands. It can be used alone, or with a subcommand name to show
further help for the subcommand. These are effectively the same if the `shell` program has implicit help:

```bash
shell help
shell --help

shell help spawn
shell spawn --help
```

### Custom help

You can display extra information by listening for "--help". ([example](./examples/custom-help))

```js
program
  .option('-f, --foo', 'enable some foo');

// must be before .parse()
program.on('--help', () => {
  console.log('');
  console.log('Example call:');
  console.log('  $ custom-help --help');
});
```

Yields the following help output:

```Text
Usage: custom-help [options]

Options:
  -f, --foo   enable some foo
  -h, --help  display help for command

Example call:
  $ custom-help --help
```

### .usage and .name

These allow you to customise the usage description in the first line of the help. The name is otherwise
deduced from the (full) program arguments. Given:

```js
program
  .name("my-command")
  .usage("[global options] command")
```

The help will start with:

```Text
Usage: my-command [global options] command
```

### .help(cb)

Output help information and exit immediately. Optional callback cb allows post-processing of help text before it is displayed.

### .outputHelp(cb)

Output help information without exiting.
Optional callback cb allows post-processing of help text before it is displayed.

### .helpInformation()

Get the command help information as a string for processing or displaying yourself. (The text does not include the custom help
from `--help` listeners.)

### .helpOption(flags, description)

Override the default help flags and description.

```js
program
  .helpOption('-e, --HELP', 'read more information');
```

### .addHelpCommand()

You can explicitly turn on or off the implicit help command with `.addHelpCommand()` and `.addHelpCommand(false)`.

You can both turn on and customise the help command by supplying the name and description:

```js
program.addHelpCommand('assist [command]', 'show assistance');
```

## Custom event listeners

You can execute custom actions by listening to command and option events.

```js
program.on('option:verbose', function () {
  process.env.VERBOSE = this.verbose;
});

program.on('command:*', function (operands) {
  console.error(`error: unknown command '${operands[0]}'`);
  const availableCommands = program.commands.map(cmd => cmd.name());
  mySuggestBestMatch(operands[0], availableCommands);
  process.exitCode = 1;
});
```

## Bits and pieces

### .parse() and .parseAsync()

The first argument to `.parse` is the array of strings to parse. You may omit the parameter to implicitly use `process.argv`.

If the arguments follow different conventions than node you can pass a `from` option in the second parameter:

- 'node': default, `argv[0]` is the application and `argv[1]` is the script being run, with user parameters after that
- 'electron': `argv[1]` varies depending on whether the electron application is packaged
- 'user': all of the arguments from the user

For example:

```js
program.parse(process.argv); // Explicit, node conventions
program.parse(); // Implicit, and auto-detect electron
program.parse(['-f', 'filename'], { from: 'user' });
```

### Avoiding option name clashes

The original and default behaviour is that the option values are stored
as properties on the program, and the action handler is passed a
command object with the options values stored as properties.
This is very convenient to code, but the downside is possible clashes with
existing properties of Command.

There are two new routines to change the behaviour, and the default behaviour may change in the future:

- `storeOptionsAsProperties`: whether to store option values as properties on command object, or store separately (specify false) and access using `.opts()`
- `passCommandToAction`: whether to pass command to action handler,
or just the options (specify false)

([example](./examples/storeOptionsAsProperties-action.js))

```js
program
  .storeOptionsAsProperties(false)
  .passCommandToAction(false);

program
  .name('my-program-name')
  .option('-n,--name <name>');

program
  .command('show')
  .option('-a,--action <action>')
  .action((options) => {
    console.log(options.action);
  });

program.parse(process.argv);

const programOptions = program.opts();
console.log(programOptions.name);
```

### TypeScript

The Commander package includes its TypeScript Definition file.

If you use `ts-node` and  stand-alone executable subcommands written as `.ts` files, you need to call your program through node to get the subcommands called correctly. e.g.

```bash
node -r ts-node/register pm.ts
```

### createCommand()

This factory function creates a new command. It is exported and may be used instead of using `new`, like:

```js
const { createCommand } = require('commander');
const program = createCommand();
```

`createCommand` is also a method of the Command object, and creates a new command rather than a subcommand. This gets used internally
when creating subcommands using `.command()`, and you may override it to
customise the new subcommand (examples using [subclass](./examples/custom-command-class.js) and [function](./examples/custom-command-function.js)).

### Node options such as `--harmony`

You can enable `--harmony` option in two ways:

- Use `#! /usr/bin/env node --harmony` in the subcommands scripts. (Note Windows does not support this pattern.)
- Use the `--harmony` option when call the command, like `node --harmony examples/pm publish`. The `--harmony` option will be preserved when spawning subcommand process.

### Debugging stand-alone executable subcommands

An executable subcommand is launched as a separate child process.

If you are using the node inspector for [debugging](https://nodejs.org/en/docs/guides/debugging-getting-started/) executable subcommands using `node --inspect` et al,
the inspector port is incremented by 1 for the spawned subcommand.

If you are using VSCode to debug executable subcommands you need to set the `"autoAttachChildProcesses": true` flag in your launch.json configuration.

### Override exit handling

By default Commander calls `process.exit` when it detects errors, or after displaying the help or version. You can override
this behaviour and optionally supply a callback. The default override throws a `CommanderError`.

The override callback is passed a `CommanderError` with properties `exitCode` number, `code` string, and `message`. The default override behaviour is to throw the error, except for async handling of executable subcommand completion which carries on. The normal display of error messages or version or help
is not affected by the override which is called after the display.

``` js
program.exitOverride();

try {
  program.parse(process.argv);
} catch (err) {
  // custom processing...
}
```

## Examples

```js
const { program } = require('commander');

program
  .version('0.1.0')
  .option('-C, --chdir <path>', 'change the working directory')
  .option('-c, --config <path>', 'set config path. defaults to ./deploy.conf')
  .option('-T, --no-tests', 'ignore test hook');

program
  .command('setup [env]')
  .description('run setup commands for all envs')
  .option("-s, --setup_mode [mode]", "Which setup mode to use")
  .action(function(env, options){
    const mode = options.setup_mode || "normal";
    env = env || 'all';
    console.log('setup for %s env(s) with %s mode', env, mode);
  });

program
  .command('exec <cmd>')
  .alias('ex')
  .description('execute the given remote cmd')
  .option("-e, --exec_mode <mode>", "Which exec mode to use")
  .action(function(cmd, options){
    console.log('exec "%s" using %s mode', cmd, options.exec_mode);
  }).on('--help', function() {
    console.log('');
    console.log('Examples:');
    console.log('');
    console.log('  $ deploy exec sequential');
    console.log('  $ deploy exec async');
  });

program.parse(process.argv);
```

More Demos can be found in the [examples](https://github.com/tj/commander.js/tree/master/examples) directory.

## License

[MIT](https://github.com/tj/commander.js/blob/master/LICENSE)

## Support

Commander 5.x is fully supported on Long Term Support versions of Node, and is likely to work with Node 6 but not tested.
(For versions of Node below Node 6, use Commander 3.x or 2.x.)

The main forum for free and community support is the project [Issues](https://github.com/tj/commander.js/issues) on GitHub.

### Commander for enterprise

Available as part of the Tidelift Subscription

The maintainers of Commander and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-commander?utm_source=npm-commander&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)


---

# common-path-prefix

Computes the longest prefix string that is common to each path, excluding the base component. Tested with Node.js 8 and above.

## Installation

```console
npm install common-path-prefix
```

## Usage

The module has one default export, the `commonPathPrefix` function:

```js
const commonPathPrefix = require('common-path-prefix')
```

Call `commonPathPrefix()` with an array of paths (strings) and an optional separator character:

```js
const paths = ['templates/main.handlebars', 'templates/_partial.handlebars']

commonPathPrefix(paths, '/') // returns 'templates/'
```

If the separator is not provided the first `/` or `\` found in any of the paths is used. Otherwise the platform-default value is used:

```js
commonPathPrefix(['templates/main.handlebars', 'templates/_partial.handlebars']) // returns 'templates/'
commonPathPrefix(['templates\\main.handlebars', 'templates\\_partial.handlebars']) // returns 'templates\\'
```

You can provide any separator, for example:

```js
commonPathPrefix(['foo$bar', 'foo$baz'], '$') // returns 'foo$''
```

An empty string is returned if no common prefix exists:

```js
commonPathPrefix(['foo/bar', 'baz/qux']) // returns ''
commonPathPrefix(['foo/bar']) // returns ''
```

Note that the following *does* have a common prefix:

```js
commonPathPrefix(['/foo/bar', '/baz/qux']) // returns '/'
```


---

2.0.18 / 2020-01-05
===================

  * deps: mime-db@'>= 1.43.0 < 2'
    - Mark `font/ttf` as compressible
    - Remove compressible from `multipart/mixed`

2.0.17 / 2019-04-24
===================

  * deps: mime-db@'>= 1.40.0 < 2'

2.0.16 / 2019-02-18
===================

  * deps: mime-db@'>= 1.38.0 < 2'
    - Mark `text/less` as compressible

2.0.15 / 2018-09-17
===================

  * deps: mime-db@'>= 1.36.0 < 2'

2.0.14 / 2018-06-05
===================

  * deps: mime-db@'>= 1.34.0 < 2'
    - Mark all XML-derived types as compressible

2.0.13 / 2018-02-17
===================

  * deps: mime-db@'>= 1.33.0 < 2'

2.0.12 / 2017-10-20
===================

  * deps: mime-db@'>= 1.30.0 < 2'

2.0.11 / 2017-07-27
===================

  * deps: mime-db@'>= 1.29.0 < 2'

2.0.10 / 2017-03-23
===================

  * deps: mime-db@'>= 1.27.0 < 2'

2.0.9 / 2016-10-31
==================

  * Fix regex fallback to not override `compressible: false` in db
  * deps: mime-db@'>= 1.24.0 < 2'

2.0.8 / 2016-05-12
==================

  * deps: mime-db@'>= 1.23.0 < 2'

2.0.7 / 2016-01-18
==================

  * deps: mime-db@'>= 1.21.0 < 2'

2.0.6 / 2015-09-29
==================

  * deps: mime-db@'>= 1.19.0 < 2'

2.0.5 / 2015-07-30
==================

  * deps: mime-db@'>= 1.16.0 < 2'

2.0.4 / 2015-07-01
==================

  * deps: mime-db@'>= 1.14.0 < 2'
  * perf: enable strict mode

2.0.3 / 2015-06-08
==================

  * Fix regex fallback to work if type exists, but is undefined
  * perf: hoist regex declaration
  * perf: use regex to extract mime
  * deps: mime-db@'>= 1.13.0 < 2'

2.0.2 / 2015-01-31
==================

  * deps: mime-db@'>= 1.1.2 < 2'

2.0.1 / 2014-09-28
==================

  * deps: mime-db@1.x
    - Add new mime types
    - Add additional compressible
    - Update charsets


2.0.0 / 2014-09-02
==================

  * use mime-db
  * remove .get()
  * specifications are now private
  * regex is now private
  * stricter regex


---

# compressible

[![NPM Version][npm-version-image]][npm-url]
[![NPM Downloads][npm-downloads-image]][npm-url]
[![Node.js Version][node-version-image]][node-version-url]
[![Build Status][travis-image]][travis-url]
[![Test Coverage][coveralls-image]][coveralls-url]

Compressible `Content-Type` / `mime` checking.

## Installation

```sh
$ npm install compressible
```

## API

<!-- eslint-disable no-unused-vars -->

```js
var compressible = require('compressible')
```

### compressible(type)

Checks if the given `Content-Type` is compressible. The `type` argument is expected
to be a value MIME type or `Content-Type` string, though no validation is performed.

The MIME is looked up in the [`mime-db`](https://www.npmjs.com/package/mime-db) and
if there is compressible information in the database entry, that is returned. Otherwise,
this module will fallback to `true` for the following types:

  * `text/*`
  * `*/*+json`
  * `*/*+text`
  * `*/*+xml`

If this module is not sure if a type is specifically compressible or specifically
uncompressible, `undefined` is returned.

<!-- eslint-disable no-undef -->

```js
compressible('text/html') // => true
compressible('image/png') // => false
```

## License

[MIT](LICENSE)

[coveralls-image]: https://badgen.net/coveralls/c/github/jshttp/compressible/master
[coveralls-url]: https://coveralls.io/r/jshttp/compressible?branch=master
[node-version-image]: https://badgen.net/npm/node/compressible
[node-version-url]: https://nodejs.org/en/download
[npm-downloads-image]: https://badgen.net/npm/dm/compressible
[npm-url]: https://npmjs.org/package/compressible
[npm-version-image]: https://badgen.net/npm/v/compressible
[travis-image]: https://badgen.net/travis/jshttp/compressible/master
[travis-url]: https://travis-ci.org/jshttp/compressible


---

1.54.0 / 2025-03-17
===================

  * Update mime type for DCM format (#362)
  * mark application/octet-stream as compressible (#163)
  * Fix typo in application/x-zip-compressed mimetype (#359)
  * Add mime-type for Jupyter notebooks (#282)
  * Add Google Drive MIME types (#311)
  * Add .blend file type (#338)
  * Add support for the FBX file extension (#342)
  * Add Adobe DNG file (#340)
  * Add Procreate Brush and Brush Set file Types (#339)
  * Add support for Procreate Dreams  (#341)
  * replace got with undici (#352)
  * Added extensions list for model/step (#293)
  * Add m4b as a type of audio/mp4 (#357)
  * windows 11 application/x-zip-compressed (#346)
  * add dotLottie mime type (#351)
  * Add some MS-related extensions and types (#336)

1.53.0 / 2024-07-12
===================

  * Add extension `.sql` to `application/sql`
  * Add extensions `.aac` and `.adts` to `audio/aac`
  * Add extensions `.js` and `.mjs` to `text/javascript`
  * Add extensions for `application/mp4` from IANA
  * Add extensions from IANA for more MIME types
  * Add Microsoft app installer types and extensions
  * Add new upstream MIME types
  * Fix extensions for `text/markdown` to match IANA
  * Remove extension `.mjs` from `application/javascript`
  * Remove obsolete MIME types from IANA data

1.52.0 / 2022-02-21
===================

  * Add extensions from IANA for more `image/*` types
  * Add extension `.asc` to `application/pgp-keys`
  * Add extensions to various XML types
  * Add new upstream MIME types

1.51.0 / 2021-11-08
===================

  * Add new upstream MIME types
  * Mark `image/vnd.microsoft.icon` as compressible
  * Mark `image/vnd.ms-dds` as compressible

1.50.0 / 2021-09-15
===================

  * Add deprecated iWorks mime types and extensions
  * Add new upstream MIME types

1.49.0 / 2021-07-26
===================

  * Add extension `.trig` to `application/trig`
  * Add new upstream MIME types

1.48.0 / 2021-05-30
===================

  * Add extension `.mvt` to `application/vnd.mapbox-vector-tile`
  * Add new upstream MIME types
  * Mark `text/yaml` as compressible

1.47.0 / 2021-04-01
===================

  * Add new upstream MIME types
  * Remove ambiguous extensions from IANA for `application/*+xml` types
  * Update primary extension to `.es` for `application/ecmascript`

1.46.0 / 2021-02-13
===================

  * Add extension `.amr` to `audio/amr`
  * Add extension `.m4s` to `video/iso.segment`
  * Add extension `.opus` to `audio/ogg`
  * Add new upstream MIME types

1.45.0 / 2020-09-22
===================

  * Add `application/ubjson` with extension `.ubj`
  * Add `image/avif` with extension `.avif`
  * Add `image/ktx2` with extension `.ktx2`
  * Add extension `.dbf` to `application/vnd.dbf`
  * Add extension `.rar` to `application/vnd.rar`
  * Add extension `.td` to `application/urc-targetdesc+xml`
  * Add new upstream MIME types
  * Fix extension of `application/vnd.apple.keynote` to be `.key`

1.44.0 / 2020-04-22
===================

  * Add charsets from IANA
  * Add extension `.cjs` to `application/node`
  * Add new upstream MIME types

1.43.0 / 2020-01-05
===================

  * Add `application/x-keepass2` with extension `.kdbx`
  * Add extension `.mxmf` to `audio/mobile-xmf`
  * Add extensions from IANA for `application/*+xml` types
  * Add new upstream MIME types

1.42.0 / 2019-09-25
===================

  * Add `image/vnd.ms-dds` with extension `.dds`
  * Add new upstream MIME types
  * Remove compressible from `multipart/mixed`

1.41.0 / 2019-08-30
===================

  * Add new upstream MIME types
  * Add `application/toml` with extension `.toml`
  * Mark `font/ttf` as compressible

1.40.0 / 2019-04-20
===================

  * Add extensions from IANA for `model/*` types
  * Add `text/mdx` with extension `.mdx`

1.39.0 / 2019-04-04
===================

  * Add extensions `.siv` and `.sieve` to `application/sieve`
  * Add new upstream MIME types

1.38.0 / 2019-02-04
===================

  * Add extension `.nq` to `application/n-quads`
  * Add extension `.nt` to `application/n-triples`
  * Add new upstream MIME types
  * Mark `text/less` as compressible

1.37.0 / 2018-10-19
===================

  * Add extensions to HEIC image types
  * Add new upstream MIME types

1.36.0 / 2018-08-20
===================

  * Add Apple file extensions from IANA
  * Add extensions from IANA for `image/*` types
  * Add new upstream MIME types

1.35.0 / 2018-07-15
===================

  * Add extension `.owl` to `application/rdf+xml`
  * Add new upstream MIME types
    - Removes extension `.woff` from `application/font-woff`

1.34.0 / 2018-06-03
===================

  * Add extension `.csl` to `application/vnd.citationstyles.style+xml`
  * Add extension `.es` to `application/ecmascript`
  * Add new upstream MIME types
  * Add `UTF-8` as default charset for `text/turtle`
  * Mark all XML-derived types as compressible

1.33.0 / 2018-02-15
===================

  * Add extensions from IANA for `message/*` types
  * Add new upstream MIME types
  * Fix some incorrect OOXML types
  * Remove `application/font-woff2`

1.32.0 / 2017-11-29
===================

  * Add new upstream MIME types
  * Update `text/hjson` to registered `application/hjson`
  * Add `text/shex` with extension `.shex`

1.31.0 / 2017-10-25
===================

  * Add `application/raml+yaml` with extension `.raml`
  * Add `application/wasm` with extension `.wasm`
  * Add new `font` type from IANA
  * Add new upstream font extensions
  * Add new upstream MIME types
  * Add extensions for JPEG-2000 images

1.30.0 / 2017-08-27
===================

  * Add `application/vnd.ms-outlook`
  * Add `application/x-arj`
  * Add extension `.mjs` to `application/javascript`
  * Add glTF types and extensions
  * Add new upstream MIME types
  * Add `text/x-org`
  * Add VirtualBox MIME types
  * Fix `source` records for `video/*` types that are IANA
  * Update `font/opentype` to registered `font/otf`

1.29.0 / 2017-07-10
===================

  * Add `application/fido.trusted-apps+json`
  * Add extension `.wadl` to `application/vnd.sun.wadl+xml`
  * Add new upstream MIME types
  * Add `UTF-8` as default charset for `text/css`

1.28.0 / 2017-05-14
===================

  * Add new upstream MIME types
  * Add extension `.gz` to `application/gzip`
  * Update extensions `.md` and `.markdown` to be `text/markdown`

1.27.0 / 2017-03-16
===================

  * Add new upstream MIME types
  * Add `image/apng` with extension `.apng`

1.26.0 / 2017-01-14
===================

  * Add new upstream MIME types
  * Add extension `.geojson` to `application/geo+json`

1.25.0 / 2016-11-11
===================

  * Add new upstream MIME types

1.24.0 / 2016-09-18
===================

  * Add `audio/mp3`
  * Add new upstream MIME types

1.23.0 / 2016-05-01
===================

  * Add new upstream MIME types
  * Add extension `.3gpp` to `audio/3gpp`

1.22.0 / 2016-02-15
===================

  * Add `text/slim`
  * Add extension `.rng` to `application/xml`
  * Add new upstream MIME types
  * Fix extension of `application/dash+xml` to be `.mpd`
  * Update primary extension to `.m4a` for `audio/mp4`

1.21.0 / 2016-01-06
===================

  * Add Google document types
  * Add new upstream MIME types

1.20.0 / 2015-11-10
===================

  * Add `text/x-suse-ymp`
  * Add new upstream MIME types

1.19.0 / 2015-09-17
===================

  * Add `application/vnd.apple.pkpass`
  * Add new upstream MIME types

1.18.0 / 2015-09-03
===================

  * Add new upstream MIME types

1.17.0 / 2015-08-13
===================

  * Add `application/x-msdos-program`
  * Add `audio/g711-0`
  * Add `image/vnd.mozilla.apng`
  * Add extension `.exe` to `application/x-msdos-program`

1.16.0 / 2015-07-29
===================

  * Add `application/vnd.uri-map`

1.15.0 / 2015-07-13
===================

  * Add `application/x-httpd-php`

1.14.0 / 2015-06-25
===================

  * Add `application/scim+json`
  * Add `application/vnd.3gpp.ussd+xml`
  * Add `application/vnd.biopax.rdf+xml`
  * Add `text/x-processing`

1.13.0 / 2015-06-07
===================

  * Add nginx as a source
  * Add `application/x-cocoa`
  * Add `application/x-java-archive-diff`
  * Add `application/x-makeself`
  * Add `application/x-perl`
  * Add `application/x-pilot`
  * Add `application/x-redhat-package-manager`
  * Add `application/x-sea`
  * Add `audio/x-m4a`
  * Add `audio/x-realaudio`
  * Add `image/x-jng`
  * Add `text/mathml`

1.12.0 / 2015-06-05
===================

  * Add `application/bdoc`
  * Add `application/vnd.hyperdrive+json`
  * Add `application/x-bdoc`
  * Add extension `.rtf` to `text/rtf`

1.11.0 / 2015-05-31
===================

  * Add `audio/wav`
  * Add `audio/wave`
  * Add extension `.litcoffee` to `text/coffeescript`
  * Add extension `.sfd-hdstx` to `application/vnd.hydrostatix.sof-data`
  * Add extension `.n-gage` to `application/vnd.nokia.n-gage.symbian.install`

1.10.0 / 2015-05-19
===================

  * Add `application/vnd.balsamiq.bmpr`
  * Add `application/vnd.microsoft.portable-executable`
  * Add `application/x-ns-proxy-autoconfig`

1.9.1 / 2015-04-19
==================

  * Remove `.json` extension from `application/manifest+json`
    - This is causing bugs downstream

1.9.0 / 2015-04-19
==================

  * Add `application/manifest+json`
  * Add `application/vnd.micro+json`
  * Add `image/vnd.zbrush.pcx`
  * Add `image/x-ms-bmp`

1.8.0 / 2015-03-13
==================

  * Add `application/vnd.citationstyles.style+xml`
  * Add `application/vnd.fastcopy-disk-image`
  * Add `application/vnd.gov.sk.xmldatacontainer+xml`
  * Add extension `.jsonld` to `application/ld+json`

1.7.0 / 2015-02-08
==================

  * Add `application/vnd.gerber`
  * Add `application/vnd.msa-disk-image`

1.6.1 / 2015-02-05
==================

  * Community extensions ownership transferred from `node-mime`

1.6.0 / 2015-01-29
==================

  * Add `application/jose`
  * Add `application/jose+json`
  * Add `application/json-seq`
  * Add `application/jwk+json`
  * Add `application/jwk-set+json`
  * Add `application/jwt`
  * Add `application/rdap+json`
  * Add `application/vnd.gov.sk.e-form+xml`
  * Add `application/vnd.ims.imsccv1p3`

1.5.0 / 2014-12-30
==================

  * Add `application/vnd.oracle.resource+json`
  * Fix various invalid MIME type entries
    - `application/mbox+xml`
    - `application/oscp-response`
    - `application/vwg-multiplexed`
    - `audio/g721`

1.4.0 / 2014-12-21
==================

  * Add `application/vnd.ims.imsccv1p2`
  * Fix various invalid MIME type entries
    - `application/vnd-acucobol`
    - `application/vnd-curl`
    - `application/vnd-dart`
    - `application/vnd-dxr`
    - `application/vnd-fdf`
    - `application/vnd-mif`
    - `application/vnd-sema`
    - `application/vnd-wap-wmlc`
    - `application/vnd.adobe.flash-movie`
    - `application/vnd.dece-zip`
    - `application/vnd.dvb_service`
    - `application/vnd.micrografx-igx`
    - `application/vnd.sealed-doc`
    - `application/vnd.sealed-eml`
    - `application/vnd.sealed-mht`
    - `application/vnd.sealed-ppt`
    - `application/vnd.sealed-tiff`
    - `application/vnd.sealed-xls`
    - `application/vnd.sealedmedia.softseal-html`
    - `application/vnd.sealedmedia.softseal-pdf`
    - `application/vnd.wap-slc`
    - `application/vnd.wap-wbxml`
    - `audio/vnd.sealedmedia.softseal-mpeg`
    - `image/vnd-djvu`
    - `image/vnd-svf`
    - `image/vnd-wap-wbmp`
    - `image/vnd.sealed-png`
    - `image/vnd.sealedmedia.softseal-gif`
    - `image/vnd.sealedmedia.softseal-jpg`
    - `model/vnd-dwf`
    - `model/vnd.parasolid.transmit-binary`
    - `model/vnd.parasolid.transmit-text`
    - `text/vnd-a`
    - `text/vnd-curl`
    - `text/vnd.wap-wml`
  * Remove example template MIME types
    - `application/example`
    - `audio/example`
    - `image/example`
    - `message/example`
    - `model/example`
    - `multipart/example`
    - `text/example`
    - `video/example`

1.3.1 / 2014-12-16
==================

  * Fix missing extensions
    - `application/json5`
    - `text/hjson`

1.3.0 / 2014-12-07
==================

  * Add `application/a2l`
  * Add `application/aml`
  * Add `application/atfx`
  * Add `application/atxml`
  * Add `application/cdfx+xml`
  * Add `application/dii`
  * Add `application/json5`
  * Add `application/lxf`
  * Add `application/mf4`
  * Add `application/vnd.apache.thrift.compact`
  * Add `application/vnd.apache.thrift.json`
  * Add `application/vnd.coffeescript`
  * Add `application/vnd.enphase.envoy`
  * Add `application/vnd.ims.imsccv1p1`
  * Add `text/csv-schema`
  * Add `text/hjson`
  * Add `text/markdown`
  * Add `text/yaml`

1.2.0 / 2014-11-09
==================

  * Add `application/cea`
  * Add `application/dit`
  * Add `application/vnd.gov.sk.e-form+zip`
  * Add `application/vnd.tmd.mediaflex.api+xml`
  * Type `application/epub+zip` is now IANA-registered

1.1.2 / 2014-10-23
==================

  * Rebuild database for `application/x-www-form-urlencoded` change

1.1.1 / 2014-10-20
==================

  * Mark `application/x-www-form-urlencoded` as compressible.

1.1.0 / 2014-09-28
==================

  * Add `application/font-woff2`

1.0.3 / 2014-09-25
==================

  * Fix engine requirement in package

1.0.2 / 2014-09-25
==================

  * Add `application/coap-group+json`
  * Add `application/dcd`
  * Add `application/vnd.apache.thrift.binary`
  * Add `image/vnd.tencent.tap`
  * Mark all JSON-derived types as compressible
  * Update `text/vtt` data

1.0.1 / 2014-08-30
==================

  * Fix extension ordering

1.0.0 / 2014-08-30
==================

  * Add `application/atf`
  * Add `application/merge-patch+json`
  * Add `multipart/x-mixed-replace`
  * Add `source: 'apache'` metadata
  * Add `source: 'iana'` metadata
  * Remove badly-assumed charset data


---

# mime-db

[![NPM Version][npm-version-image]][npm-url]
[![NPM Downloads][npm-downloads-image]][npm-url]
[![Node.js Version][node-image]][node-url]
[![Build Status][ci-image]][ci-url]
[![Coverage Status][coveralls-image]][coveralls-url]

This is a large database of mime types and information about them.
It consists of a single, public JSON file and does not include any logic,
allowing it to remain as un-opinionated as possible with an API.
It aggregates data from the following sources:

- https://www.iana.org/assignments/media-types/media-types.xhtml
- https://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/conf/mime.types
- https://hg.nginx.org/nginx/raw-file/default/conf/mime.types

## Installation

```bash
npm install mime-db
```

### Database Download

If you intend to use this in a web browser, you can conveniently access the JSON file via [jsDelivr](https://www.jsdelivr.com/), a popular CDN (Content Delivery Network). To ensure stability and compatibility, it is advisable to specify [a release tag](https://github.com/jshttp/mime-db/tags) instead of using the 'master' branch. This is because the JSON file's format might change in future updates, and relying on a specific release tag will prevent potential issues arising from these changes.

```
https://cdn.jsdelivr.net/gh/jshttp/mime-db@master/db.json
```

## Usage

```js
var db = require('mime-db')

// grab data on .js files
var data = db['application/javascript']
```

## Data Structure

The JSON file is a map lookup for lowercased mime types.
Each mime type has the following properties:

- `.source` - where the mime type is defined.
    If not set, it's probably a custom media type.
    - `apache` - [Apache common media types](https://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/conf/mime.types)
    - `iana` - [IANA-defined media types](https://www.iana.org/assignments/media-types/media-types.xhtml)
    - `nginx` - [nginx media types](https://hg.nginx.org/nginx/raw-file/default/conf/mime.types)
- `.extensions[]` - known extensions associated with this mime type.
- `.compressible` - whether a file of this type can be gzipped.
- `.charset` - the default charset associated with this type, if any.

If unknown, every property could be `undefined`.

## Note on MIME Type Data and Semver

This package considers the programmatic api as the semver compatibility. This means the MIME type resolution is *not* considered
in the semver bumps. This means that if you want to pin your `mime-db` data you will need to do it in your application. While
this expectation was not set in docs until now, it is how the pacakge operated, so we do not feel this is a breaking change.

## Contributing

The primary way to contribute to this database is by updating the data in
one of the upstream sources. The database is updated from the upstreams
periodically and will pull in any changes.

### Registering Media Types

The best way to get new media types included in this library is to register
them with the IANA. The community registration procedure is outlined in
[RFC 6838 section 5](https://tools.ietf.org/html/rfc6838#section-5). Types
registered with the IANA are automatically pulled into this library.

### Direct Inclusion

If that is not possible / feasible, they can be added directly here as a
"custom" type. To do this, it is required to have a primary source that
definitively lists the media type. If an extension is going to be listed as
associated with this media type, the source must definitively link the
media type and extension as well.

To edit the database, only make PRs against `src/custom-types.json` or
`src/custom-suffix.json`.

The `src/custom-types.json` file is a JSON object with the MIME type as the
keys and the values being an object with the following keys:

- `compressible` - leave out if you don't know, otherwise `true`/`false` to
  indicate whether the data represented by the type is typically compressible.
- `extensions` - include an array of file extensions that are associated with
  the type.
- `notes` - human-readable notes about the type, typically what the type is.
- `sources` - include an array of URLs of where the MIME type and the associated
  extensions are sourced from. This needs to be a [primary source](https://en.wikipedia.org/wiki/Primary_source);
  links to type aggregating sites and Wikipedia are _not acceptable_.

To update the build, run `npm run build`.

[ci-image]: https://badgen.net/github/checks/jshttp/mime-db/master?label=ci
[ci-url]: https://github.com/jshttp/mime-db/actions/workflows/ci.yml
[coveralls-image]: https://badgen.net/coveralls/c/github/jshttp/mime-db/master
[coveralls-url]: https://coveralls.io/r/jshttp/mime-db?branch=master
[node-image]: https://badgen.net/npm/node/mime-db
[node-url]: https://nodejs.org/en/download
[npm-downloads-image]: https://badgen.net/npm/dm/mime-db
[npm-url]: https://npmjs.org/package/mime-db
[npm-version-image]: https://badgen.net/npm/v/mime-db


---

1.8.0 / 2025-02-10
==================

  * Use `res.headersSent` when available
  * Replace `_implicitHeader` with `writeHead` property
  * add brotli support for versions of node that support it
  * Add the enforceEncoding option for requests without `Accept-Encoding` header

1.7.5 / 2024-10-31
==================

  * deps: Replace accepts with negotiator@~0.6.4
    - Add preference option
  * deps: bytes@3.1.2
    - Add petabyte (`pb`) support
    - Fix "thousandsSeparator" incorrecting formatting fractional part
    - Fix return value for un-parsable strings
  * deps: compressible@~2.0.18
    - Mark `font/ttf` as compressible
    - Remove compressible from `multipart/mixed`
    - deps: mime-db@'>= 1.43.0 < 2'
  * deps: safe-buffer@5.2.1

1.7.4 / 2019-03-18
==================

  * deps: compressible@~2.0.16
    - Mark `text/less` as compressible
    - deps: mime-db@'>= 1.38.0 < 2'
  * deps: on-headers@~1.0.2
    - Fix `res.writeHead` patch missing return value
  * perf: prevent unnecessary buffer copy

1.7.3 / 2018-07-15
==================

  * deps: accepts@~1.3.5
    - deps: mime-types@~2.1.18
  * deps: compressible@~2.0.14
    - Mark all XML-derived types as compressible
    - deps: mime-db@'>= 1.34.0 < 2'
  * deps: safe-buffer@5.1.2

1.7.2 / 2018-02-18
==================

  * deps: compressible@~2.0.13
    - deps: mime-db@'>= 1.33.0 < 2'

1.7.1 / 2017-09-26
==================

  * deps: accepts@~1.3.4
    - deps: mime-types@~2.1.16
  * deps: bytes@3.0.0
  * deps: compressible@~2.0.11
    - deps: mime-db@'>= 1.29.0 < 2'
  * deps: debug@2.6.9
  * deps: vary@~1.1.2
    - perf: improve header token parsing speed

1.7.0 / 2017-07-10
==================

  * Use `safe-buffer` for improved Buffer API
  * deps: bytes@2.5.0
  * deps: compressible@~2.0.10
    - Fix regex fallback to not override `compressible: false` in db
    - deps: mime-db@'>= 1.27.0 < 2'
  * deps: debug@2.6.8
    - Allow colors in workers
    - Deprecated `DEBUG_FD` environment variable set to `3` or higher
    - Fix error when running under React Native
    - Fix `DEBUG_MAX_ARRAY_LENGTH`
    - Use same color for same namespace
    - deps: ms@2.0.0
  * deps: vary@~1.1.1
    - perf: hoist regular expression

1.6.2 / 2016-05-12
==================

  * deps: accepts@~1.3.3
    - deps: mime-types@~2.1.11
    - deps: negotiator@0.6.1
  * deps: bytes@2.3.0
    - Drop partial bytes on all parsed units
    - Fix parsing byte string that looks like hex
    - perf: hoist regular expressions
  * deps: compressible@~2.0.8
    - deps: mime-db@'>= 1.23.0 < 2'

1.6.1 / 2016-01-19
==================

  * deps: bytes@2.2.0
  * deps: compressible@~2.0.7
    - deps: mime-db@'>= 1.21.0 < 2'
  * deps: accepts@~1.3.1
    - deps: mime-types@~2.1.9

1.6.0 / 2015-09-29
==================

  * Skip compression when response has `Cache-Control: no-transform`
  * deps: accepts@~1.3.0
    - deps: mime-types@~2.1.7
    - deps: negotiator@0.6.0
  * deps: compressible@~2.0.6
    - deps: mime-db@'>= 1.19.0 < 2'
  * deps: on-headers@~1.0.1
    - perf: enable strict mode
  * deps: vary@~1.1.0
    - Only accept valid field names in the `field` argument

1.5.2 / 2015-07-30
==================

  * deps: accepts@~1.2.12
    - deps: mime-types@~2.1.4
  * deps: compressible@~2.0.5
    - deps: mime-db@'>= 1.16.0 < 2'
  * deps: vary@~1.0.1
    - Fix setting empty header from empty `field`
    - perf: enable strict mode
    - perf: remove argument reassignments

1.5.1 / 2015-07-05
==================

  * deps: accepts@~1.2.10
    - deps: mime-types@~2.1.2
  * deps: compressible@~2.0.4
    - deps: mime-db@'>= 1.14.0 < 2'
    - perf: enable strict mode

1.5.0 / 2015-06-09
==================

  * Fix return value from `.end` and `.write` after end
  * Improve detection of zero-length body without `Content-Length`
  * deps: accepts@~1.2.9
    - deps: mime-types@~2.1.1
    - perf: avoid argument reassignment & argument slice
    - perf: avoid negotiator recursive construction
    - perf: enable strict mode
    - perf: remove unnecessary bitwise operator
  * deps: bytes@2.1.0
    - Slight optimizations
    - Units no longer case sensitive when parsing
  * deps: compressible@~2.0.3
    - Fix regex fallback to work if type exists, but is undefined
    - deps: mime-db@'>= 1.13.0 < 2'
    - perf: hoist regex declaration
    - perf: use regex to extract mime
  * perf: enable strict mode
  * perf: remove flush reassignment
  * perf: simplify threshold detection

1.4.4 / 2015-05-11
==================

  * deps: accepts@~1.2.7
    - deps: mime-types@~2.0.11
    - deps: negotiator@0.5.3
  * deps: debug@~2.2.0
    - deps: ms@0.7.1

1.4.3 / 2015-03-14
==================

  * deps: accepts@~1.2.5
    - deps: mime-types@~2.0.10
  * deps: debug@~2.1.3
    - Fix high intensity foreground color for bold
    - deps: ms@0.7.0

1.4.2 / 2015-03-11
==================

  * Fix error when code calls `res.end(str, encoding)`
    - Specific to Node.js 0.8
  * deps: debug@~2.1.2
    - deps: ms@0.7.0

1.4.1 / 2015-02-15
==================

  * deps: accepts@~1.2.4
    - deps: mime-types@~2.0.9
    - deps: negotiator@0.5.1

1.4.0 / 2015-02-01
==================

  * Prefer `gzip` over `deflate` on the server
    - Not all clients agree on what "deflate" coding means

1.3.1 / 2015-01-31
==================

  * deps: accepts@~1.2.3
    - deps: mime-types@~2.0.8
  * deps: compressible@~2.0.2
    - deps: mime-db@'>= 1.1.2 < 2'

1.3.0 / 2014-12-30
==================

  * Export the default `filter` function for wrapping
  * deps: accepts@~1.2.2
    - deps: mime-types@~2.0.7
    - deps: negotiator@0.5.0
  * deps: debug@~2.1.1

1.2.2 / 2014-12-10
==================

  * Fix `.end` to only proxy to `.end`
    - Fixes an issue with Node.js 0.11.14
  * deps: accepts@~1.1.4
    - deps: mime-types@~2.0.4

1.2.1 / 2014-11-23
==================

  * deps: accepts@~1.1.3
    - deps: mime-types@~2.0.3

1.2.0 / 2014-10-16
==================

  * deps: debug@~2.1.0
    - Implement `DEBUG_FD` env variable support

1.1.2 / 2014-10-15
==================

  * deps: accepts@~1.1.2
    - Fix error when media type has invalid parameter
    - deps: negotiator@0.4.9

1.1.1 / 2014-10-12
==================

  * deps: accepts@~1.1.1
    - deps: mime-types@~2.0.2
    - deps: negotiator@0.4.8
  * deps: compressible@~2.0.1
    - deps: mime-db@1.x

1.1.0 / 2014-09-07
==================

  * deps: accepts@~1.1.0
  * deps: compressible@~2.0.0
  * deps: debug@~2.0.0

1.0.11 / 2014-08-10
===================

  * deps: on-headers@~1.0.0
  * deps: vary@~1.0.0

1.0.10 / 2014-08-05
===================

  * deps: compressible@~1.1.1
    - Fix upper-case Content-Type characters prevent compression

1.0.9 / 2014-07-20
==================

  * Add `debug` messages
  * deps: accepts@~1.0.7
    - deps: negotiator@0.4.7

1.0.8 / 2014-06-20
==================

  * deps: accepts@~1.0.5
    - use `mime-types`

1.0.7 / 2014-06-11
==================

 * use vary module for better `Vary` behavior
 * deps: accepts@1.0.3
 * deps: compressible@1.1.0

1.0.6 / 2014-06-03
==================

 * fix regression when negotiation fails

1.0.5 / 2014-06-03
==================

 * fix listeners for delayed stream creation
   - fixes regression for certain `stream.pipe(res)` situations

1.0.4 / 2014-06-03
==================

 * fix adding `Vary` when value stored as array
 * fix back-pressure behavior
 * fix length check for `res.end`

1.0.3 / 2014-05-29
==================

 * use `accepts` for negotiation
 * use `on-headers` to handle header checking
 * deps: bytes@1.0.0

1.0.2 / 2014-04-29
==================

 * only version compatible with node.js 0.8
 * support headers given to `res.writeHead`
 * deps: bytes@0.3.0
 * deps: negotiator@0.4.3

1.0.1 / 2014-03-08
==================

 * bump negotiator
 * use compressible
 * use .headersSent (drops 0.8 support)
 * handle identity;q=0 case


---

# compression

[![NPM Version][npm-image]][npm-url]
[![NPM Downloads][downloads-image]][downloads-url]
[![Build Status][github-actions-ci-image]][github-actions-ci-url]
[![OpenSSF Scorecard Badge][ossf-scorecard-badge]][ossf-scorecard-visualizer]
[![Funding][funding-image]][funding-url]


Node.js compression middleware.

The following compression codings are supported:

  - deflate
  - gzip
  - br (brotli)

**Note** Brotli is supported only since Node.js versions v11.7.0 and v10.16.0.

## Install

This is a [Node.js](https://nodejs.org/en/) module available through the
[npm registry](https://www.npmjs.com/). Installation is done using the
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):

```bash
$ npm install compression
```

## API

```js
var compression = require('compression')
```

### compression([options])

Returns the compression middleware using the given `options`. The middleware
will attempt to compress response bodies for all requests that traverse through
the middleware, based on the given `options`.

This middleware will never compress responses that include a `Cache-Control`
header with the [`no-transform` directive](https://tools.ietf.org/html/rfc7234#section-5.2.2.4),
as compressing will transform the body.

#### Options

`compression()` accepts these properties in the options object. In addition to
those listed below, [zlib](http://nodejs.org/api/zlib.html) options may be
passed in to the options object or
[brotli](https://nodejs.org/api/zlib.html#zlib_class_brotlioptions) options.

##### chunkSize

Type: `Number`<br>
Default: `zlib.constants.Z_DEFAULT_CHUNK`, or `16384`.

See [Node.js documentation](http://nodejs.org/api/zlib.html#zlib_memory_usage_tuning)
regarding the usage.

##### filter

Type: `Function`

A function to decide if the response should be considered for compression.
This function is called as `filter(req, res)` and is expected to return
`true` to consider the response for compression, or `false` to not compress
the response.

The default filter function uses the [compressible](https://www.npmjs.com/package/compressible)
module to determine if `res.getHeader('Content-Type')` is compressible.

##### level

Type: `Number`<br>
Default: `zlib.constants.Z_DEFAULT_COMPRESSION`, or `-1`

The level of zlib compression to apply to responses. A higher level will result
in better compression, but will take longer to complete. A lower level will
result in less compression, but will be much faster.

This is an integer in the range of `0` (no compression) to `9` (maximum
compression). The special value `-1` can be used to mean the "default
compression level", which is a default compromise between speed and
compression (currently equivalent to level 6).

  - `-1` Default compression level (also `zlib.constants.Z_DEFAULT_COMPRESSION`).
  - `0` No compression (also `zlib.constants.Z_NO_COMPRESSION`).
  - `1` Fastest compression (also `zlib.constants.Z_BEST_SPEED`).
  - `2`
  - `3`
  - `4`
  - `5`
  - `6` (currently what `zlib.constants.Z_DEFAULT_COMPRESSION` points to).
  - `7`
  - `8`
  - `9` Best compression (also `zlib.constants.Z_BEST_COMPRESSION`).

**Note** in the list above, `zlib` is from `zlib = require('zlib')`.

##### memLevel

Type: `Number`<br>
Default: `zlib.constants.Z_DEFAULT_MEMLEVEL`, or `8`

This specifies how much memory should be allocated for the internal compression
state and is an integer in the range of `1` (minimum level) and `9` (maximum
level).

See [Node.js documentation](http://nodejs.org/api/zlib.html#zlib_memory_usage_tuning)
regarding the usage.

##### brotli

Type: `Object`

This specifies the options for configuring Brotli. See [Node.js documentation](https://nodejs.org/api/zlib.html#class-brotlioptions) for a complete list of available options.


##### strategy

Type: `Number`<br>
Default: `zlib.constants.Z_DEFAULT_STRATEGY`

This is used to tune the compression algorithm. This value only affects the
compression ratio, not the correctness of the compressed output, even if it
is not set appropriately.

  - `zlib.constants.Z_DEFAULT_STRATEGY` Use for normal data.
  - `zlib.constants.Z_FILTERED` Use for data produced by a filter (or predictor).
    Filtered data consists mostly of small values with a somewhat random
    distribution. In this case, the compression algorithm is tuned to
    compress them better. The effect is to force more Huffman coding and less
    string matching; it is somewhat intermediate between `zlib.constants.Z_DEFAULT_STRATEGY`
    and `zlib.constants.Z_HUFFMAN_ONLY`.
  - `zlib.constants.Z_FIXED` Use to prevent the use of dynamic Huffman codes, allowing
    for a simpler decoder for special applications.
  - `zlib.constants.Z_HUFFMAN_ONLY` Use to force Huffman encoding only (no string match).
  - `zlib.constants.Z_RLE` Use to limit match distances to one (run-length encoding).
    This is designed to be almost as fast as `zlib.constants.Z_HUFFMAN_ONLY`, but give
    better compression for PNG image data.

**Note** in the list above, `zlib` is from `zlib = require('zlib')`.

##### threshold

Type: `Number` or `String`<br>
Default: `1kb`

The byte threshold for the response body size before compression is considered
for the response. This is a number of bytes or any string
accepted by the [bytes](https://www.npmjs.com/package/bytes) module.

**Note** this is only an advisory setting; if the response size cannot be determined
at the time the response headers are written, then it is assumed the response is
_over_ the threshold. To guarantee the response size can be determined, be sure
set a `Content-Length` response header.

##### windowBits

Type: `Number`<br>
Default: `zlib.constants.Z_DEFAULT_WINDOWBITS`, or `15`

See [Node.js documentation](http://nodejs.org/api/zlib.html#zlib_memory_usage_tuning)
regarding the usage.

##### enforceEncoding

Type: `String`<br>
Default: `identity`

This is the default encoding to use when the client does not specify an encoding in the request's [Accept-Encoding](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding) header.

#### .filter

The default `filter` function. This is used to construct a custom filter
function that is an extension of the default function.

```js
var compression = require('compression')
var express = require('express')

var app = express()

app.use(compression({ filter: shouldCompress }))

function shouldCompress (req, res) {
  if (req.headers['x-no-compression']) {
    // don't compress responses with this request header
    return false
  }

  // fallback to standard filter function
  return compression.filter(req, res)
}
```

### res.flush

This module adds a `res.flush()` method to force the partially-compressed
response to be flushed to the client.

## Examples

### express

When using this module with express, simply `app.use` the module as
high as you like. Requests that pass through the middleware will be compressed.

```js
var compression = require('compression')
var express = require('express')

var app = express()

// compress all responses
app.use(compression())

// add all routes
```

### Node.js HTTP server

```js
var compression = require('compression')({ threshold: 0 })
var http = require('http')

function createServer (fn) {
  return http.createServer(function (req, res) {
    compression(req, res, function (err) {
      if (err) {
        res.statusCode = err.status || 500
        res.end(err.message)
        return
      }

      fn(req, res)
    })
  })
}

var server = createServer(function (req, res) {
  res.setHeader('Content-Type', 'text/plain')
  res.end('hello world!')
})

server.listen(3000, () => {
  console.log('> Listening at http://localhost:3000')
})
```

### Server-Sent Events

Because of the nature of compression this module does not work out of the box
with server-sent events. To compress content, a window of the output needs to
be buffered up in order to get good compression. Typically when using server-sent
events, there are certain block of data that need to reach the client.

You can achieve this by calling `res.flush()` when you need the data written to
actually make it to the client.

```js
var compression = require('compression')
var express = require('express')

var app = express()

// compress responses
app.use(compression())

// server-sent event stream
app.get('/events', function (req, res) {
  res.setHeader('Content-Type', 'text/event-stream')
  res.setHeader('Cache-Control', 'no-cache')

  // send a ping approx every 2 seconds
  var timer = setInterval(function () {
    res.write('data: ping\n\n')

    // !!! this is the important part
    res.flush()
  }, 2000)

  res.on('close', function () {
    clearInterval(timer)
  })
})
```

##  Contributing

The Express.js project welcomes all constructive contributions. Contributions take many forms,
from code for bug fixes and enhancements, to additions and fixes to documentation, additional
tests, triaging incoming pull requests and issues, and more!

See the [Contributing Guide](https://github.com/expressjs/express/blob/master/Contributing.md) for more technical details on contributing.

## License

[MIT](LICENSE)

[npm-image]: https://badgen.net/npm/v/compression
[npm-url]: https://npmjs.org/package/compression
[downloads-image]: https://badgen.net/npm/dm/compression
[downloads-url]: https://npmcharts.com/compare/compression?minimal=true
[github-actions-ci-image]: https://badgen.net/github/checks/expressjs/compression/master?label=CI
[github-actions-ci-url]: https://github.com/expressjs/compression/actions?query=workflow%3Aci
[ossf-scorecard-badge]: https://api.scorecard.dev/projects/github.com/expressjs/compression/badge
[ossf-scorecard-visualizer]: https://ossf.github.io/scorecard-visualizer/#/projects/github.com/expressjs/compression
[funding-url]: https://opencollective.com/express
[funding-image]: https://badgen.net/badge/icon/sponsor/pink?icon=github&label=Open%20Collective

---

3.1.2 / 2022-01-27
==================

  * Fix return value for un-parsable strings

3.1.1 / 2021-11-15
==================

  * Fix "thousandsSeparator" incorrecting formatting fractional part

3.1.0 / 2019-01-22
==================

  * Add petabyte (`pb`) support

3.0.0 / 2017-08-31
==================

  * Change "kB" to "KB" in format output
  * Remove support for Node.js 0.6
  * Remove support for ComponentJS

2.5.0 / 2017-03-24
==================

  * Add option "unit"

2.4.0 / 2016-06-01
==================

  * Add option "unitSeparator"

2.3.0 / 2016-02-15
==================

  * Drop partial bytes on all parsed units
  * Fix non-finite numbers to `.format` to return `null`
  * Fix parsing byte string that looks like hex
  * perf: hoist regular expressions

2.2.0 / 2015-11-13
==================

  * add option "decimalPlaces"
  * add option "fixedDecimals"

2.1.0 / 2015-05-21
==================

  * add `.format` export
  * add `.parse` export

2.0.2 / 2015-05-20
==================

  * remove map recreation
  * remove unnecessary object construction

2.0.1 / 2015-05-07
==================

  * fix browserify require
  * remove node.extend dependency

2.0.0 / 2015-04-12
==================

  * add option "case"
  * add option "thousandsSeparator"
  * return "null" on invalid parse input
  * support proper round-trip: bytes(bytes(num)) === num
  * units no longer case sensitive when parsing

1.0.0 / 2014-05-05
==================

 * add negative support. fixes #6

0.3.0 / 2014-03-19
==================

 * added terabyte support

0.2.1 / 2013-04-01
==================

  * add .component

0.2.0 / 2012-10-28
==================

  * bytes(200).should.eql('200b')

0.1.0 / 2012-07-04
==================

  * add bytes to string conversion [yields]


---

# Bytes utility

[![NPM Version][npm-image]][npm-url]
[![NPM Downloads][downloads-image]][downloads-url]
[![Build Status][ci-image]][ci-url]
[![Test Coverage][coveralls-image]][coveralls-url]

Utility to parse a string bytes (ex: `1TB`) to bytes (`1099511627776`) and vice-versa.

## Installation

This is a [Node.js](https://nodejs.org/en/) module available through the
[npm registry](https://www.npmjs.com/). Installation is done using the
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):

```bash
$ npm install bytes
```

## Usage

```js
var bytes = require('bytes');
```

#### bytes(number｜string value, [options]): number｜string｜null

Default export function. Delegates to either `bytes.format` or `bytes.parse` based on the type of `value`.

**Arguments**

| Name    | Type     | Description        |
|---------|----------|--------------------|
| value   | `number`｜`string` | Number value to format or string value to parse |
| options | `Object` | Conversion options for `format` |

**Returns**

| Name    | Type             | Description                                     |
|---------|------------------|-------------------------------------------------|
| results | `string`｜`number`｜`null` | Return null upon error. Numeric value in bytes, or string value otherwise. |

**Example**

```js
bytes(1024);
// output: '1KB'

bytes('1KB');
// output: 1024
```

#### bytes.format(number value, [options]): string｜null

Format the given value in bytes into a string. If the value is negative, it is kept as such. If it is a float, it is
 rounded.

**Arguments**

| Name    | Type     | Description        |
|---------|----------|--------------------|
| value   | `number` | Value in bytes     |
| options | `Object` | Conversion options |

**Options**

| Property          | Type   | Description                                                                             |
|-------------------|--------|-----------------------------------------------------------------------------------------|
| decimalPlaces | `number`｜`null` | Maximum number of decimal places to include in output. Default value to `2`. |
| fixedDecimals | `boolean`｜`null` | Whether to always display the maximum number of decimal places. Default value to `false` |
| thousandsSeparator | `string`｜`null` | Example of values: `' '`, `','` and `'.'`... Default value to `''`. |
| unit | `string`｜`null` | The unit in which the result will be returned (B/KB/MB/GB/TB). Default value to `''` (which means auto detect). |
| unitSeparator | `string`｜`null` | Separator to use between number and unit. Default value to `''`. |

**Returns**

| Name    | Type             | Description                                     |
|---------|------------------|-------------------------------------------------|
| results | `string`｜`null` | Return null upon error. String value otherwise. |

**Example**

```js
bytes.format(1024);
// output: '1KB'

bytes.format(1000);
// output: '1000B'

bytes.format(1000, {thousandsSeparator: ' '});
// output: '1 000B'

bytes.format(1024 * 1.7, {decimalPlaces: 0});
// output: '2KB'

bytes.format(1024, {unitSeparator: ' '});
// output: '1 KB'
```

#### bytes.parse(string｜number value): number｜null

Parse the string value into an integer in bytes. If no unit is given, or `value`
is a number, it is assumed the value is in bytes.

Supported units and abbreviations are as follows and are case-insensitive:

  * `b` for bytes
  * `kb` for kilobytes
  * `mb` for megabytes
  * `gb` for gigabytes
  * `tb` for terabytes
  * `pb` for petabytes

The units are in powers of two, not ten. This means 1kb = 1024b according to this parser.

**Arguments**

| Name          | Type   | Description        |
|---------------|--------|--------------------|
| value   | `string`｜`number` | String to parse, or number in bytes.   |

**Returns**

| Name    | Type        | Description             |
|---------|-------------|-------------------------|
| results | `number`｜`null` | Return null upon error. Value in bytes otherwise. |

**Example**

```js
bytes.parse('1KB');
// output: 1024

bytes.parse('1024');
// output: 1024

bytes.parse(1024);
// output: 1024
```

## License

[MIT](LICENSE)

[ci-image]: https://badgen.net/github/checks/visionmedia/bytes.js/master?label=ci
[ci-url]: https://github.com/visionmedia/bytes.js/actions?query=workflow%3Aci
[coveralls-image]: https://badgen.net/coveralls/c/github/visionmedia/bytes.js/master
[coveralls-url]: https://coveralls.io/r/visionmedia/bytes.js?branch=master
[downloads-image]: https://badgen.net/npm/dm/bytes
[downloads-url]: https://npmjs.org/package/bytes
[npm-image]: https://badgen.net/npm/v/bytes
[npm-url]: https://npmjs.org/package/bytes


---


2.6.9 / 2017-09-22
==================

  * remove ReDoS regexp in %o formatter (#504)

2.6.8 / 2017-05-18
==================

  * Fix: Check for undefined on browser globals (#462, @marbemac)

2.6.7 / 2017-05-16
==================

  * Fix: Update ms to 2.0.0 to fix regular expression denial of service vulnerability (#458, @hubdotcom)
  * Fix: Inline extend function in node implementation (#452, @dougwilson)
  * Docs: Fix typo (#455, @msasad)

2.6.5 / 2017-04-27
==================
  
  * Fix: null reference check on window.documentElement.style.WebkitAppearance (#447, @thebigredgeek)
  * Misc: clean up browser reference checks (#447, @thebigredgeek)
  * Misc: add npm-debug.log to .gitignore (@thebigredgeek)


2.6.4 / 2017-04-20
==================

  * Fix: bug that would occure if process.env.DEBUG is a non-string value. (#444, @LucianBuzzo)
  * Chore: ignore bower.json in npm installations. (#437, @joaovieira)
  * Misc: update "ms" to v0.7.3 (@tootallnate)

2.6.3 / 2017-03-13
==================

  * Fix: Electron reference to `process.env.DEBUG` (#431, @paulcbetts)
  * Docs: Changelog fix (@thebigredgeek)

2.6.2 / 2017-03-10
==================

  * Fix: DEBUG_MAX_ARRAY_LENGTH (#420, @slavaGanzin)
  * Docs: Add backers and sponsors from Open Collective (#422, @piamancini)
  * Docs: Add Slackin invite badge (@tootallnate)

2.6.1 / 2017-02-10
==================

  * Fix: Module's `export default` syntax fix for IE8 `Expected identifier` error
  * Fix: Whitelist DEBUG_FD for values 1 and 2 only (#415, @pi0)
  * Fix: IE8 "Expected identifier" error (#414, @vgoma)
  * Fix: Namespaces would not disable once enabled (#409, @musikov)

2.6.0 / 2016-12-28
==================

  * Fix: added better null pointer checks for browser useColors (@thebigredgeek)
  * Improvement: removed explicit `window.debug` export (#404, @tootallnate)
  * Improvement: deprecated `DEBUG_FD` environment variable (#405, @tootallnate)

2.5.2 / 2016-12-25
==================

  * Fix: reference error on window within webworkers (#393, @KlausTrainer)
  * Docs: fixed README typo (#391, @lurch)
  * Docs: added notice about v3 api discussion (@thebigredgeek)

2.5.1 / 2016-12-20
==================

  * Fix: babel-core compatibility

2.5.0 / 2016-12-20
==================

  * Fix: wrong reference in bower file (@thebigredgeek)
  * Fix: webworker compatibility (@thebigredgeek)
  * Fix: output formatting issue (#388, @kribblo)
  * Fix: babel-loader compatibility (#383, @escwald)
  * Misc: removed built asset from repo and publications (@thebigredgeek)
  * Misc: moved source files to /src (#378, @yamikuronue)
  * Test: added karma integration and replaced babel with browserify for browser tests (#378, @yamikuronue)
  * Test: coveralls integration (#378, @yamikuronue)
  * Docs: simplified language in the opening paragraph (#373, @yamikuronue)

2.4.5 / 2016-12-17
==================

  * Fix: `navigator` undefined in Rhino (#376, @jochenberger)
  * Fix: custom log function (#379, @hsiliev)
  * Improvement: bit of cleanup + linting fixes (@thebigredgeek)
  * Improvement: rm non-maintainted `dist/` dir (#375, @freewil)
  * Docs: simplified language in the opening paragraph. (#373, @yamikuronue)

2.4.4 / 2016-12-14
==================

  * Fix: work around debug being loaded in preload scripts for electron (#368, @paulcbetts)

2.4.3 / 2016-12-14
==================

  * Fix: navigation.userAgent error for react native (#364, @escwald)

2.4.2 / 2016-12-14
==================

  * Fix: browser colors (#367, @tootallnate)
  * Misc: travis ci integration (@thebigredgeek)
  * Misc: added linting and testing boilerplate with sanity check (@thebigredgeek)

2.4.1 / 2016-12-13
==================

  * Fix: typo that broke the package (#356)

2.4.0 / 2016-12-13
==================

  * Fix: bower.json references unbuilt src entry point (#342, @justmatt)
  * Fix: revert "handle regex special characters" (@tootallnate)
  * Feature: configurable util.inspect()`options for NodeJS (#327, @tootallnate)
  * Feature: %O`(big O) pretty-prints objects (#322, @tootallnate)
  * Improvement: allow colors in workers (#335, @botverse)
  * Improvement: use same color for same namespace. (#338, @lchenay)

2.3.3 / 2016-11-09
==================

  * Fix: Catch `JSON.stringify()` errors (#195, Jovan Alleyne)
  * Fix: Returning `localStorage` saved values (#331, Levi Thomason)
  * Improvement: Don't create an empty object when no `process` (Nathan Rajlich)

2.3.2 / 2016-11-09
==================

  * Fix: be super-safe in index.js as well (@TooTallNate)
  * Fix: should check whether process exists (Tom Newby)

2.3.1 / 2016-11-09
==================

  * Fix: Added electron compatibility (#324, @paulcbetts)
  * Improvement: Added performance optimizations (@tootallnate)
  * Readme: Corrected PowerShell environment variable example (#252, @gimre)
  * Misc: Removed yarn lock file from source control (#321, @fengmk2)

2.3.0 / 2016-11-07
==================

  * Fix: Consistent placement of ms diff at end of output (#215, @gorangajic)
  * Fix: Escaping of regex special characters in namespace strings (#250, @zacronos)
  * Fix: Fixed bug causing crash on react-native (#282, @vkarpov15)
  * Feature: Enabled ES6+ compatible import via default export (#212 @bucaran)
  * Feature: Added %O formatter to reflect Chrome's console.log capability (#279, @oncletom)
  * Package: Update "ms" to 0.7.2 (#315, @DevSide)
  * Package: removed superfluous version property from bower.json (#207 @kkirsche)
  * Readme: fix USE_COLORS to DEBUG_COLORS
  * Readme: Doc fixes for format string sugar (#269, @mlucool)
  * Readme: Updated docs for DEBUG_FD and DEBUG_COLORS environment variables (#232, @mattlyons0)
  * Readme: doc fixes for PowerShell (#271 #243, @exoticknight @unreadable)
  * Readme: better docs for browser support (#224, @matthewmueller)
  * Tooling: Added yarn integration for development (#317, @thebigredgeek)
  * Misc: Renamed History.md to CHANGELOG.md (@thebigredgeek)
  * Misc: Added license file (#226 #274, @CantemoInternal @sdaitzman)
  * Misc: Updated contributors (@thebigredgeek)

2.2.0 / 2015-05-09
==================

  * package: update "ms" to v0.7.1 (#202, @dougwilson)
  * README: add logging to file example (#193, @DanielOchoa)
  * README: fixed a typo (#191, @amir-s)
  * browser: expose `storage` (#190, @stephenmathieson)
  * Makefile: add a `distclean` target (#189, @stephenmathieson)

2.1.3 / 2015-03-13
==================

  * Updated stdout/stderr example (#186)
  * Updated example/stdout.js to match debug current behaviour
  * Renamed example/stderr.js to stdout.js
  * Update Readme.md (#184)
  * replace high intensity foreground color for bold (#182, #183)

2.1.2 / 2015-03-01
==================

  * dist: recompile
  * update "ms" to v0.7.0
  * package: update "browserify" to v9.0.3
  * component: fix "ms.js" repo location
  * changed bower package name
  * updated documentation about using debug in a browser
  * fix: security error on safari (#167, #168, @yields)

2.1.1 / 2014-12-29
==================

  * browser: use `typeof` to check for `console` existence
  * browser: check for `console.log` truthiness (fix IE 8/9)
  * browser: add support for Chrome apps
  * Readme: added Windows usage remarks
  * Add `bower.json` to properly support bower install

2.1.0 / 2014-10-15
==================

  * node: implement `DEBUG_FD` env variable support
  * package: update "browserify" to v6.1.0
  * package: add "license" field to package.json (#135, @panuhorsmalahti)

2.0.0 / 2014-09-01
==================

  * package: update "browserify" to v5.11.0
  * node: use stderr rather than stdout for logging (#29, @stephenmathieson)

1.0.4 / 2014-07-15
==================

  * dist: recompile
  * example: remove `console.info()` log usage
  * example: add "Content-Type" UTF-8 header to browser example
  * browser: place %c marker after the space character
  * browser: reset the "content" color via `color: inherit`
  * browser: add colors support for Firefox >= v31
  * debug: prefer an instance `log()` function over the global one (#119)
  * Readme: update documentation about styled console logs for FF v31 (#116, @wryk)

1.0.3 / 2014-07-09
==================

  * Add support for multiple wildcards in namespaces (#122, @seegno)
  * browser: fix lint

1.0.2 / 2014-06-10
==================

  * browser: update color palette (#113, @gscottolson)
  * common: make console logging function configurable (#108, @timoxley)
  * node: fix %o colors on old node <= 0.8.x
  * Makefile: find node path using shell/which (#109, @timoxley)

1.0.1 / 2014-06-06
==================

  * browser: use `removeItem()` to clear localStorage
  * browser, node: don't set DEBUG if namespaces is undefined (#107, @leedm777)
  * package: add "contributors" section
  * node: fix comment typo
  * README: list authors

1.0.0 / 2014-06-04
==================

  * make ms diff be global, not be scope
  * debug: ignore empty strings in enable()
  * node: make DEBUG_COLORS able to disable coloring
  * *: export the `colors` array
  * npmignore: don't publish the `dist` dir
  * Makefile: refactor to use browserify
  * package: add "browserify" as a dev dependency
  * Readme: add Web Inspector Colors section
  * node: reset terminal color for the debug content
  * node: map "%o" to `util.inspect()`
  * browser: map "%j" to `JSON.stringify()`
  * debug: add custom "formatters"
  * debug: use "ms" module for humanizing the diff
  * Readme: add "bash" syntax highlighting
  * browser: add Firebug color support
  * browser: add colors for WebKit browsers
  * node: apply log to `console`
  * rewrite: abstract common logic for Node & browsers
  * add .jshintrc file

0.8.1 / 2014-04-14
==================

  * package: re-add the "component" section

0.8.0 / 2014-03-30
==================

  * add `enable()` method for nodejs. Closes #27
  * change from stderr to stdout
  * remove unnecessary index.js file

0.7.4 / 2013-11-13
==================

  * remove "browserify" key from package.json (fixes something in browserify)

0.7.3 / 2013-10-30
==================

  * fix: catch localStorage security error when cookies are blocked (Chrome)
  * add debug(err) support. Closes #46
  * add .browser prop to package.json. Closes #42

0.7.2 / 2013-02-06
==================

  * fix package.json
  * fix: Mobile Safari (private mode) is broken with debug
  * fix: Use unicode to send escape character to shell instead of octal to work with strict mode javascript

0.7.1 / 2013-02-05
==================

  * add repository URL to package.json
  * add DEBUG_COLORED to force colored output
  * add browserify support
  * fix component. Closes #24

0.7.0 / 2012-05-04
==================

  * Added .component to package.json
  * Added debug.component.js build

0.6.0 / 2012-03-16
==================

  * Added support for "-" prefix in DEBUG [Vinay Pulim]
  * Added `.enabled` flag to the node version [TooTallNate]

0.5.0 / 2012-02-02
==================

  * Added: humanize diffs. Closes #8
  * Added `debug.disable()` to the CS variant
  * Removed padding. Closes #10
  * Fixed: persist client-side variant again. Closes #9

0.4.0 / 2012-02-01
==================

  * Added browser variant support for older browsers [TooTallNate]
  * Added `debug.enable('project:*')` to browser variant [TooTallNate]
  * Added padding to diff (moved it to the right)

0.3.0 / 2012-01-26
==================

  * Added millisecond diff when isatty, otherwise UTC string

0.2.0 / 2012-01-22
==================

  * Added wildcard support

0.1.0 / 2011-12-02
==================

  * Added: remove colors unless stderr isatty [TooTallNate]

0.0.1 / 2010-01-03
==================

  * Initial release


---

# debug
[![Build Status](https://travis-ci.org/visionmedia/debug.svg?branch=master)](https://travis-ci.org/visionmedia/debug)  [![Coverage Status](https://coveralls.io/repos/github/visionmedia/debug/badge.svg?branch=master)](https://coveralls.io/github/visionmedia/debug?branch=master)  [![Slack](https://visionmedia-community-slackin.now.sh/badge.svg)](https://visionmedia-community-slackin.now.sh/) [![OpenCollective](https://opencollective.com/debug/backers/badge.svg)](#backers) 
[![OpenCollective](https://opencollective.com/debug/sponsors/badge.svg)](#sponsors)



A tiny node.js debugging utility modelled after node core's debugging technique.

**Discussion around the V3 API is under way [here](https://github.com/visionmedia/debug/issues/370)**

## Installation

```bash
$ npm install debug
```

## Usage

`debug` exposes a function; simply pass this function the name of your module, and it will return a decorated version of `console.error` for you to pass debug statements to. This will allow you to toggle the debug output for different parts of your module as well as the module as a whole.

Example _app.js_:

```js
var debug = require('debug')('http')
  , http = require('http')
  , name = 'My App';

// fake app

debug('booting %s', name);

http.createServer(function(req, res){
  debug(req.method + ' ' + req.url);
  res.end('hello\n');
}).listen(3000, function(){
  debug('listening');
});

// fake worker of some kind

require('./worker');
```

Example _worker.js_:

```js
var debug = require('debug')('worker');

setInterval(function(){
  debug('doing some work');
}, 1000);
```

 The __DEBUG__ environment variable is then used to enable these based on space or comma-delimited names. Here are some examples:

  ![debug http and worker](http://f.cl.ly/items/18471z1H402O24072r1J/Screenshot.png)

  ![debug worker](http://f.cl.ly/items/1X413v1a3M0d3C2c1E0i/Screenshot.png)

#### Windows note

 On Windows the environment variable is set using the `set` command.

 ```cmd
 set DEBUG=*,-not_this
 ```

 Note that PowerShell uses different syntax to set environment variables.

 ```cmd
 $env:DEBUG = "*,-not_this"
  ```

Then, run the program to be debugged as usual.

## Millisecond diff

  When actively developing an application it can be useful to see when the time spent between one `debug()` call and the next. Suppose for example you invoke `debug()` before requesting a resource, and after as well, the "+NNNms" will show you how much time was spent between calls.

  ![](http://f.cl.ly/items/2i3h1d3t121M2Z1A3Q0N/Screenshot.png)

  When stdout is not a TTY, `Date#toUTCString()` is used, making it more useful for logging the debug information as shown below:

  ![](http://f.cl.ly/items/112H3i0e0o0P0a2Q2r11/Screenshot.png)

## Conventions

  If you're using this in one or more of your libraries, you _should_ use the name of your library so that developers may toggle debugging as desired without guessing names. If you have more than one debuggers you _should_ prefix them with your library name and use ":" to separate features. For example "bodyParser" from Connect would then be "connect:bodyParser".

## Wildcards

  The `*` character may be used as a wildcard. Suppose for example your library has debuggers named "connect:bodyParser", "connect:compress", "connect:session", instead of listing all three with `DEBUG=connect:bodyParser,connect:compress,connect:session`, you may simply do `DEBUG=connect:*`, or to run everything using this module simply use `DEBUG=*`.

  You can also exclude specific debuggers by prefixing them with a "-" character.  For example, `DEBUG=*,-connect:*` would include all debuggers except those starting with "connect:".

## Environment Variables

  When running through Node.js, you can set a few environment variables that will
  change the behavior of the debug logging:

| Name      | Purpose                                         |
|-----------|-------------------------------------------------|
| `DEBUG`   | Enables/disables specific debugging namespaces. |
| `DEBUG_COLORS`| Whether or not to use colors in the debug output. |
| `DEBUG_DEPTH` | Object inspection depth. |
| `DEBUG_SHOW_HIDDEN` | Shows hidden properties on inspected objects. |


  __Note:__ The environment variables beginning with `DEBUG_` end up being
  converted into an Options object that gets used with `%o`/`%O` formatters.
  See the Node.js documentation for
  [`util.inspect()`](https://nodejs.org/api/util.html#util_util_inspect_object_options)
  for the complete list.

## Formatters


  Debug uses [printf-style](https://wikipedia.org/wiki/Printf_format_string) formatting. Below are the officially supported formatters:

| Formatter | Representation |
|-----------|----------------|
| `%O`      | Pretty-print an Object on multiple lines. |
| `%o`      | Pretty-print an Object all on a single line. |
| `%s`      | String. |
| `%d`      | Number (both integer and float). |
| `%j`      | JSON. Replaced with the string '[Circular]' if the argument contains circular references. |
| `%%`      | Single percent sign ('%'). This does not consume an argument. |

### Custom formatters

  You can add custom formatters by extending the `debug.formatters` object. For example, if you wanted to add support for rendering a Buffer as hex with `%h`, you could do something like:

```js
const createDebug = require('debug')
createDebug.formatters.h = (v) => {
  return v.toString('hex')
}

// …elsewhere
const debug = createDebug('foo')
debug('this is hex: %h', new Buffer('hello world'))
//   foo this is hex: 68656c6c6f20776f726c6421 +0ms
```

## Browser support
  You can build a browser-ready script using [browserify](https://github.com/substack/node-browserify),
  or just use the [browserify-as-a-service](https://wzrd.in/) [build](https://wzrd.in/standalone/debug@latest),
  if you don't want to build it yourself.

  Debug's enable state is currently persisted by `localStorage`.
  Consider the situation shown below where you have `worker:a` and `worker:b`,
  and wish to debug both. You can enable this using `localStorage.debug`:

```js
localStorage.debug = 'worker:*'
```

And then refresh the page.

```js
a = debug('worker:a');
b = debug('worker:b');

setInterval(function(){
  a('doing some work');
}, 1000);

setInterval(function(){
  b('doing some work');
}, 1200);
```

#### Web Inspector Colors

  Colors are also enabled on "Web Inspectors" that understand the `%c` formatting
  option. These are WebKit web inspectors, Firefox ([since version
  31](https://hacks.mozilla.org/2014/05/editable-box-model-multiple-selection-sublime-text-keys-much-more-firefox-developer-tools-episode-31/))
  and the Firebug plugin for Firefox (any version).

  Colored output looks something like:

  ![](https://cloud.githubusercontent.com/assets/71256/3139768/b98c5fd8-e8ef-11e3-862a-f7253b6f47c6.png)


## Output streams

  By default `debug` will log to stderr, however this can be configured per-namespace by overriding the `log` method:

Example _stdout.js_:

```js
var debug = require('debug');
var error = debug('app:error');

// by default stderr is used
error('goes to stderr!');

var log = debug('app:log');
// set this namespace to log via console.log
log.log = console.log.bind(console); // don't forget to bind to console!
log('goes to stdout');
error('still goes to stderr!');

// set all output to go via console.info
// overrides all per-namespace log settings
debug.log = console.info.bind(console);
error('now goes to stdout via console.info');
log('still goes to stdout, but via console.info now');
```


## Authors

 - TJ Holowaychuk
 - Nathan Rajlich
 - Andrew Rhyne
 
## Backers

Support us with a monthly donation and help us continue our activities. [[Become a backer](https://opencollective.com/debug#backer)]

<a href="https://opencollective.com/debug/backer/0/website" target="_blank"><img src="https://opencollective.com/debug/backer/0/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/1/website" target="_blank"><img src="https://opencollective.com/debug/backer/1/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/2/website" target="_blank"><img src="https://opencollective.com/debug/backer/2/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/3/website" target="_blank"><img src="https://opencollective.com/debug/backer/3/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/4/website" target="_blank"><img src="https://opencollective.com/debug/backer/4/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/5/website" target="_blank"><img src="https://opencollective.com/debug/backer/5/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/6/website" target="_blank"><img src="https://opencollective.com/debug/backer/6/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/7/website" target="_blank"><img src="https://opencollective.com/debug/backer/7/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/8/website" target="_blank"><img src="https://opencollective.com/debug/backer/8/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/9/website" target="_blank"><img src="https://opencollective.com/debug/backer/9/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/10/website" target="_blank"><img src="https://opencollective.com/debug/backer/10/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/11/website" target="_blank"><img src="https://opencollective.com/debug/backer/11/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/12/website" target="_blank"><img src="https://opencollective.com/debug/backer/12/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/13/website" target="_blank"><img src="https://opencollective.com/debug/backer/13/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/14/website" target="_blank"><img src="https://opencollective.com/debug/backer/14/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/15/website" target="_blank"><img src="https://opencollective.com/debug/backer/15/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/16/website" target="_blank"><img src="https://opencollective.com/debug/backer/16/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/17/website" target="_blank"><img src="https://opencollective.com/debug/backer/17/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/18/website" target="_blank"><img src="https://opencollective.com/debug/backer/18/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/19/website" target="_blank"><img src="https://opencollective.com/debug/backer/19/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/20/website" target="_blank"><img src="https://opencollective.com/debug/backer/20/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/21/website" target="_blank"><img src="https://opencollective.com/debug/backer/21/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/22/website" target="_blank"><img src="https://opencollective.com/debug/backer/22/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/23/website" target="_blank"><img src="https://opencollective.com/debug/backer/23/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/24/website" target="_blank"><img src="https://opencollective.com/debug/backer/24/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/25/website" target="_blank"><img src="https://opencollective.com/debug/backer/25/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/26/website" target="_blank"><img src="https://opencollective.com/debug/backer/26/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/27/website" target="_blank"><img src="https://opencollective.com/debug/backer/27/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/28/website" target="_blank"><img src="https://opencollective.com/debug/backer/28/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/29/website" target="_blank"><img src="https://opencollective.com/debug/backer/29/avatar.svg"></a>


## Sponsors

Become a sponsor and get your logo on our README on Github with a link to your site. [[Become a sponsor](https://opencollective.com/debug#sponsor)]

<a href="https://opencollective.com/debug/sponsor/0/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/0/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/1/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/1/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/2/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/2/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/3/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/3/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/4/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/4/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/5/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/5/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/6/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/6/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/7/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/7/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/8/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/8/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/9/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/9/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/10/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/10/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/11/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/11/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/12/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/12/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/13/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/13/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/14/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/14/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/15/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/15/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/16/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/16/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/17/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/17/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/18/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/18/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/19/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/19/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/20/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/20/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/21/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/21/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/22/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/22/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/23/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/23/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/24/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/24/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/25/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/25/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/26/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/26/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/27/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/27/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/28/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/28/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/29/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/29/avatar.svg"></a>

## License

(The MIT License)

Copyright (c) 2014-2016 TJ Holowaychuk &lt;tj@vision-media.ca&gt;

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
'Software'), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


---

The MIT License (MIT)

Copyright (c) 2016 Zeit, Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# ms

[![Build Status](https://travis-ci.org/zeit/ms.svg?branch=master)](https://travis-ci.org/zeit/ms)
[![Slack Channel](http://zeit-slackin.now.sh/badge.svg)](https://zeit.chat/)

Use this package to easily convert various time formats to milliseconds.

## Examples

```js
ms('2 days')  // 172800000
ms('1d')      // 86400000
ms('10h')     // 36000000
ms('2.5 hrs') // 9000000
ms('2h')      // 7200000
ms('1m')      // 60000
ms('5s')      // 5000
ms('1y')      // 31557600000
ms('100')     // 100
```

### Convert from milliseconds

```js
ms(60000)             // "1m"
ms(2 * 60000)         // "2m"
ms(ms('10 hours'))    // "10h"
```

### Time format written-out

```js
ms(60000, { long: true })             // "1 minute"
ms(2 * 60000, { long: true })         // "2 minutes"
ms(ms('10 hours'), { long: true })    // "10 hours"
```

## Features

- Works both in [node](https://nodejs.org) and in the browser.
- If a number is supplied to `ms`, a string with a unit is returned.
- If a string that contains the number is supplied, it returns it as a number (e.g.: it returns `100` for `'100'`).
- If you pass a string with a number and a valid unit, the number of equivalent ms is returned.

## Caught a bug?

1. [Fork](https://help.github.com/articles/fork-a-repo/) this repository to your own GitHub account and then [clone](https://help.github.com/articles/cloning-a-repository/) it to your local device
2. Link the package to the global module directory: `npm link`
3. Within the module you want to test your local development instance of ms, just link it to the dependencies: `npm link ms`. Instead of the default one from npm, node will now use your clone of ms!

As always, you can run the tests using: `npm test`


---

# configstore

> Easily load and persist config without having to think about where and how

The config is stored in a JSON file located in `$XDG_CONFIG_HOME` or `~/.config`.\
Example: `~/.config/configstore/some-id.json`

*If you need this for Electron, check out [`electron-store`](https://github.com/sindresorhus/electron-store) instead.*\
*And check out [`conf`](https://github.com/sindresorhus/conf) for a more modern version of `configstore`.*

## Install

```
$ npm install configstore
```

## Usage

```js
import Configstore from 'configstore';

const packageJson = JSON.parse(fs.readFileSync('./package.json', 'utf8'));

// Create a Configstore instance.
const config = new Configstore(packageJson.name, {foo: 'bar'});

console.log(config.get('foo'));
//=> 'bar'

config.set('awesome', true);
console.log(config.get('awesome'));
//=> true

// Use dot-notation to access nested properties.
config.set('bar.baz', true);
console.log(config.get('bar'));
//=> {baz: true}

config.delete('awesome');
console.log(config.get('awesome'));
//=> undefined
```

## API

### Configstore(packageName, defaults?, options?)

Returns a new instance.

#### packageName

Type: `string`

Name of your package.

#### defaults

Type: `object`

Default config.

#### options

Type: `object`

##### globalConfigPath

Type: `boolean`\
Default: `false`

Store the config at `$CONFIG/package-name/config.json` instead of the default `$CONFIG/configstore/package-name.json`. This is not recommended as you might end up conflicting with other tools, rendering the "without having to think" idea moot.

##### configPath

Type: `string`\
Default: Automatic

**Please don't use this option unless absolutely necessary and you know what you're doing.**

Set the path of the config file. Overrides the `packageName` and `globalConfigPath` options.

### Instance

You can use [dot-notation](https://github.com/sindresorhus/dot-prop) in a `key` to access nested properties.

### .set(key, value)

Set an item.

### .set(object)

Set multiple items at once.

### .get(key)

Get an item.

### .has(key)

Check if an item exists.

### .delete(key)

Delete an item.

### .clear()

Delete all items.

### .size

Get the item count.

### .path

Get the path to the config file. Can be used to show the user where the config file is located or even better open it for them.

### .all

Get all the config as an object or replace the current config with an object:

```js
config.all = {
	hello: 'world'
};
```

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-configstore?utm_source=npm-configstore&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

<h1 align="center">connect-history-api-fallback</h1>
<p align="center">Middleware to proxy requests through a specified index page, useful for Single Page Applications that utilise the HTML5 History API.</p>

<h2>Table of Contents</h2>

<!-- TOC depthFrom:2 depthTo:6 withLinks:1 updateOnSave:1 orderedList:0 -->

- [Introduction](#introduction)
- [Usage](#usage)
- [Options](#options)
	- [index](#index)
	- [rewrites](#rewrites)
	- [verbose](#verbose)
	- [htmlAcceptHeaders](#htmlacceptheaders)
	- [disableDotRule](#disabledotrule)

<!-- /TOC -->

## Introduction

Single Page Applications (SPA) typically only utilise one index file that is
accessible by web browsers: usually `index.html`. Navigation in the application
is then commonly handled using JavaScript with the help of the
[HTML5 History API](http://www.w3.org/html/wg/drafts/html/master/single-page.html#the-history-interface).
This results in issues when the user hits the refresh button or is directly
accessing a page other than the landing page, e.g. `/help` or `/help/online`
as the web server bypasses the index file to locate the file at this location.
As your application is a SPA, the web server will fail trying to retrieve the file and return a *404 - Not Found*
message to the user.

This tiny middleware addresses some of the issues. Specifically, it will change
the requested location to the index you specify (default being `/index.html`)
whenever there is a request which fulfills the following criteria:

 1. The request is a `GET` or `HEAD` request
 2. which accepts `text/html`,
 3. is not a direct file request, i.e. the requested path does not contain a
    `.` (DOT) character and
 4. does not match a pattern provided in options.rewrites (see options below)

## Usage

The middleware is available through NPM and can easily be added.

```
npm install --save connect-history-api-fallback
```

Import the library

```javascript
var history = require('connect-history-api-fallback');
```

Now you only need to add the middleware to your application like so

```javascript
var connect = require('connect');

var app = connect()
  .use(history())
  .listen(3000);
```

Of course you can also use this piece of middleware with express:

```javascript
var express = require('express');

var app = express();
app.use(history());
```

## Options
You can optionally pass options to the library when obtaining the middleware

```javascript
var middleware = history({});
```

### index
Override the index (default `/index.html`). This is the request path that will be used when the middleware identifies that the request path needs to be rewritten.

This is not the path to a file on disk. Instead it is the HTTP request path. Downstream connect/express middleware is responsible to turn this rewritten HTTP request path into actual responses, e.g. by reading a file from disk.

```javascript
history({
  index: '/default.html'
});
```

### rewrites
Override the index when the request url matches a regex pattern. You can either rewrite to a static string or use a function to transform the incoming request.

The following will rewrite a request that matches the `/\/soccer/` pattern to `/soccer.html`.
```javascript
history({
  rewrites: [
    { from: /\/soccer/, to: '/soccer.html'}
  ]
});
```

Alternatively functions can be used to have more control over the rewrite process. For instance, the following listing shows how requests to `/libs/jquery/jquery.1.12.0.min.js` and the like can be routed to `./bower_components/libs/jquery/jquery.1.12.0.min.js`. You can also make use of this if you have an API version in the URL path.
```javascript
history({
  rewrites: [
    {
      from: /^\/libs\/.*$/,
      to: function(context) {
        return '/bower_components' + context.parsedUrl.pathname;
      }
    }
  ]
});
```

The function will always be called with a context object that has the following properties:

 - **parsedUrl**: Information about the URL as provided by the [URL module's](https://nodejs.org/api/url.html#url_url_parse_urlstr_parsequerystring_slashesdenotehost) `url.parse`.
 - **match**: An Array of matched results as provided by `String.match(...)`.
 - **request**: The HTTP request object.


### verbose
This middleware does not log any information by default. If you wish to activate logging, then you can do so via the `verbose` option or by specifying a logger function.

```javascript
history({
  verbose: true
});
```

Alternatively use your own logger

```javascript
history({
  logger: console.log.bind(console)
});
```

### htmlAcceptHeaders
Override the default `Accepts:` headers that are queried when matching HTML content requests (Default: `['text/html', '*/*']`).

```javascript
history({
  htmlAcceptHeaders: ['text/html', 'application/xhtml+xml']
})
```

### disableDotRule
Disables the dot rule mentioned above:

> […] is not a direct file request, i.e. the requested path does not contain a `.` (DOT) character […]

```javascript
history({
  disableDotRule: true
})
```


---

# 🐨 Consola

> Elegant Console Wrapper

[![npm version][npm-version-src]][npm-version-href]
[![npm downloads][npm-downloads-src]][npm-downloads-href]
[![bundle][bundle-src]][bundle-href]

<!-- [![Codecov][codecov-src]][codecov-href] -->

## Why Consola?

👌&nbsp; Easy to use<br>
💅&nbsp; Fancy output with fallback for minimal environments<br>
🔌&nbsp; Pluggable reporters<br>
💻&nbsp; Consistent command line interface (CLI) experience<br>
🏷&nbsp; Tag support<br>
🚏&nbsp; Redirect `console` and `stdout/stderr` to consola and easily restore redirect.<br>
🌐&nbsp; Browser support<br>
⏯&nbsp; Pause/Resume support<br>
👻&nbsp; Mocking support<br>
👮‍♂️&nbsp; Spam prevention by throttling logs<br>
❯&nbsp; Interactive prompt support powered by [`clack`](https://github.com/natemoo-re/clack)<br>

## Installation

Using npm:

```bash
npm i consola
```

Using yarn:

```bash
yarn add consola
```

Using pnpm:

```bash
pnpm i consola
```

## Getting Started

```js
// ESM
import { consola, createConsola } from "consola";

// CommonJS
const { consola, createConsola } = require("consola");

consola.info("Using consola 3.0.0");
consola.start("Building project...");
consola.warn("A new version of consola is available: 3.0.1");
consola.success("Project built!");
consola.error(new Error("This is an example error. Everything is fine!"));
consola.box("I am a simple box");
await consola.prompt("Deploy to the production?", {
  type: "confirm",
});
```

Will display in the terminal:

![consola-screenshot](https://github.com/unjs/consola/assets/904724/0e511ee6-2543-43ab-9eda-152f07134d94)

You can use smaller core builds without fancy reporter to save 80% of the bundle size:

```ts
import { consola, createConsola } from "consola/basic";
import { consola, createConsola } from "consola/browser";
import { createConsola } from "consola/core";
```

## Consola Methods

#### `<type>(logObject)` `<type>(args...)`

Log to all reporters.

Example: `consola.info('Message')`

#### `await prompt(message, { type, cancel })`

Show an input prompt. Type can either of `text`, `confirm`, `select` or `multiselect`.

If prompt is canceled by user (with Ctrol+C), default value will be resolved by default. This strategy can be configured by setting `{ cancel: "..." }` option:

- `"default"` - Resolve the promise with the `default` value or `initial` value.
- `"undefined`" - Resolve the promise with `undefined`.
- `"null"` - Resolve the promise with `null`.
- `"symbol"` - Resolve the promise with a symbol `Symbol.for("cancel")`.
- `"reject"` - Reject the promise with an error.

See [examples/prompt.ts](./examples/prompt.ts) for usage examples.

#### `addReporter(reporter)`

- Aliases: `add`

Register a custom reporter instance.

#### `removeReporter(reporter?)`

- Aliases: `remove`, `clear`

Remove a registered reporter.

If no arguments are passed all reporters will be removed.

#### `setReporters(reporter|reporter[])`

Replace all reporters.

#### `create(options)`

Create a new `Consola` instance and inherit all parent options for defaults.

#### `withDefaults(defaults)`

Create a new `Consola` instance with provided defaults

#### `withTag(tag)`

- Aliases: `withScope`

Create a new `Consola` instance with that tag.

#### `wrapConsole()` `restoreConsole()`

Globally redirect all `console.log`, etc calls to consola handlers.

#### `wrapStd()` `restoreStd()`

Globally redirect all stdout/stderr outputs to consola.

#### `wrapAll()` `restoreAll()`

Wrap both, std and console.

console uses std in the underlying so calling `wrapStd` redirects console too.
Benefit of this function is that things like `console.info` will be correctly redirected to the corresponding type.

#### `pauseLogs()` `resumeLogs()`

- Aliases: `pause`/`resume`

**Globally** pause and resume logs.

Consola will enqueue all logs when paused and then sends them to the reported when resumed.

#### `mockTypes`

- Aliases: `mock`

Mock all types. Useful for using with tests.

The first argument passed to `mockTypes` should be a callback function accepting `(typeName, type)` and returning the mocked value:

```js
// Jest
consola.mockTypes((typeName, type) => jest.fn());
// Vitest
consola.mockTypes((typeName, type) => vi.fn());
```

Please note that with the example above, everything is mocked independently for each type. If you need one mocked fn create it outside:

```js
// Jest
const fn = jest.fn();
// Vitest
const fn = vi.fn();
consola.mockTypes(() => fn);
```

If callback function returns a _falsy_ value, that type won't be mocked.

For example if you just need to mock `consola.fatal`:

```js
// Jest
consola.mockTypes((typeName) => typeName === "fatal" && jest.fn());
// Vitest
consola.mockTypes((typeName) => typeName === "fatal" && vi.fn());
```

**NOTE:** Any instance of consola that inherits the mocked instance, will apply provided callback again.
This way, mocking works for `withTag` scoped loggers without need to extra efforts.

## Custom Reporters

Consola ships with 3 built-in reporters out of the box. A fancy colored reporter by default and fallsback to a basic reporter if running in a testing or CI environment detected using [unjs/std-env](https://github.com/unjs/std-env) and a basic browser reporter.

You can create a new reporter object that implements `{ log(logObject): () => { } }` interface.

**Example:** Simple JSON reporter

```ts
import { createConsola } from "consola";

const consola = createConsola({
  reporters: [
    {
      log: (logObj) => {
        console.log(JSON.stringify(logObj));
      },
    },
  ],
});

// Prints {"date":"2023-04-18T12:43:38.693Z","args":["foo bar"],"type":"log","level":2,"tag":""}
consola.log("foo bar");
```

## Log Level

Consola only shows logs with configured log level or below. (Default is `3`)

Available log levels:

- `0`: Fatal and Error
- `1`: Warnings
- `2`: Normal logs
- `3`: Informational logs, success, fail, ready, start, ...
- `4`: Debug logs
- `5`: Trace logs
- `-999`: Silent
- `+999`: Verbose logs

You can set the log level by either:

- Passing `level` option to `createConsola`
- Setting `consola.level` on instance
- Using the `CONSOLA_LEVEL` environment variable (not supported for browser and core builds).

## Log Types

Log types are exposed as `consola.[type](...)` and each is a preset of styles and log level.

A list of all available built-in types is [available here](./src/constants.ts).

## Creating a new instance

Consola has a global instance and is recommended to use everywhere.
In case more control is needed, create a new instance.

```js
import { createConsola } from "consola";

const logger = createConsola({
  // level: 4,
  // fancy: true | false
  // formatOptions: {
  //     columns: 80,
  //     colors: false,
  //     compact: false,
  //     date: false,
  // },
});
```

## Integrations

### With jest or vitest

```js
describe("your-consola-mock-test", () => {
  beforeAll(() => {
    // Redirect std and console to consola too
    // Calling this once is sufficient
    consola.wrapAll();
  });

  beforeEach(() => {
    // Re-mock consola before each test call to remove
    // calls from before
    // Jest
    consola.mockTypes(() => jest.fn());
    // Vitest
    consola.mockTypes(() => vi.fn());
  });

  test("your test", async () => {
    // Some code here

    // Let's retrieve all messages of `consola.log`
    // Get the mock and map all calls to their first argument
    const consolaMessages = consola.log.mock.calls.map((c) => c[0]);
    expect(consolaMessages).toContain("your message");
  });
});
```

### With jsdom

```js
{
  new jsdom.VirtualConsole().sendTo(consola);
}
```

## Console Utils

```ts
// ESM
import {
  stripAnsi,
  centerAlign,
  rightAlign,
  leftAlign,
  align,
  box,
  colors,
  getColor,
  colorize,
} from "consola/utils";

// CommonJS
const { stripAnsi } = require("consola/utils");
```

## Raw logging methods

Objects sent to the reporter could lead to unexpected output when object is close to internal object structure containing either `message` or `args` props. To enforce the object to be interpreted as pure object, you can use the `raw` method chained to any log type.

**Example:**

```js
// Prints "hello"
consola.log({ message: "hello" });

// Prints "{ message: 'hello' }"
consola.log.raw({ message: "hello" });
```

## License

MIT

<!-- Badges -->

[npm-version-src]: https://img.shields.io/npm/v/consola?style=flat&colorA=18181B&colorB=F0DB4F
[npm-version-href]: https://npmjs.com/package/consola
[npm-downloads-src]: https://img.shields.io/npm/dm/consola?style=flat&colorA=18181B&colorB=F0DB4F
[npm-downloads-href]: https://npmjs.com/package/consola
[codecov-src]: https://img.shields.io/codecov/c/gh/unjs/consola/main?style=flat&colorA=18181B&colorB=F0DB4F
[codecov-href]: https://codecov.io/gh/unjs/consola
[bundle-src]: https://img.shields.io/bundlephobia/min/consola?style=flat&colorA=18181B&colorB=F0DB4F
[bundle-href]: https://bundlephobia.com/result?p=consola


---

0.5.2 / 2016-12-08
==================

  * Fix `parse` to accept any linear whitespace character

0.5.1 / 2016-01-17
==================

  * perf: enable strict mode

0.5.0 / 2014-10-11
==================

  * Add `parse` function

0.4.0 / 2014-09-21
==================

  * Expand non-Unicode `filename` to the full ISO-8859-1 charset

0.3.0 / 2014-09-20
==================

  * Add `fallback` option
  * Add `type` option

0.2.0 / 2014-09-19
==================

  * Reduce ambiguity of file names with hex escape in buggy browsers

0.1.2 / 2014-09-19
==================

  * Fix periodic invalid Unicode filename header

0.1.1 / 2014-09-19
==================

  * Fix invalid characters appearing in `filename*` parameter

0.1.0 / 2014-09-18
==================

  * Make the `filename` argument optional

0.0.0 / 2014-09-18
==================

  * Initial release


---

# content-disposition

[![NPM Version][npm-image]][npm-url]
[![NPM Downloads][downloads-image]][downloads-url]
[![Node.js Version][node-version-image]][node-version-url]
[![Build Status][travis-image]][travis-url]
[![Test Coverage][coveralls-image]][coveralls-url]

Create and parse HTTP `Content-Disposition` header

## Installation

```sh
$ npm install content-disposition
```

## API

```js
var contentDisposition = require('content-disposition')
```

### contentDisposition(filename, options)

Create an attachment `Content-Disposition` header value using the given file name,
if supplied. The `filename` is optional and if no file name is desired, but you
want to specify `options`, set `filename` to `undefined`.

```js
res.setHeader('Content-Disposition', contentDisposition('∫ maths.pdf'))
```

**note** HTTP headers are of the ISO-8859-1 character set. If you are writing this
header through a means different from `setHeader` in Node.js, you'll want to specify
the `'binary'` encoding in Node.js.

#### Options

`contentDisposition` accepts these properties in the options object.

##### fallback

If the `filename` option is outside ISO-8859-1, then the file name is actually
stored in a supplemental field for clients that support Unicode file names and
a ISO-8859-1 version of the file name is automatically generated.

This specifies the ISO-8859-1 file name to override the automatic generation or
disables the generation all together, defaults to `true`.

  - A string will specify the ISO-8859-1 file name to use in place of automatic
    generation.
  - `false` will disable including a ISO-8859-1 file name and only include the
    Unicode version (unless the file name is already ISO-8859-1).
  - `true` will enable automatic generation if the file name is outside ISO-8859-1.

If the `filename` option is ISO-8859-1 and this option is specified and has a
different value, then the `filename` option is encoded in the extended field
and this set as the fallback field, even though they are both ISO-8859-1.

##### type

Specifies the disposition type, defaults to `"attachment"`. This can also be
`"inline"`, or any other value (all values except inline are treated like
`attachment`, but can convey additional information if both parties agree to
it). The type is normalized to lower-case.

### contentDisposition.parse(string)

```js
var disposition = contentDisposition.parse('attachment; filename="EURO rates.txt"; filename*=UTF-8\'\'%e2%82%ac%20rates.txt');
```

Parse a `Content-Disposition` header string. This automatically handles extended
("Unicode") parameters by decoding them and providing them under the standard
parameter name. This will return an object with the following properties (examples
are shown for the string `'attachment; filename="EURO rates.txt"; filename*=UTF-8\'\'%e2%82%ac%20rates.txt'`):

 - `type`: The disposition type (always lower case). Example: `'attachment'`

 - `parameters`: An object of the parameters in the disposition (name of parameter
   always lower case and extended versions replace non-extended versions). Example:
   `{filename: "€ rates.txt"}`

## Examples

### Send a file for download

```js
var contentDisposition = require('content-disposition')
var destroy = require('destroy')
var http = require('http')
var onFinished = require('on-finished')

var filePath = '/path/to/public/plans.pdf'

http.createServer(function onRequest(req, res) {
  // set headers
  res.setHeader('Content-Type', 'application/pdf')
  res.setHeader('Content-Disposition', contentDisposition(filePath))

  // send file
  var stream = fs.createReadStream(filePath)
  stream.pipe(res)
  onFinished(res, function (err) {
    destroy(stream)
  })
})
```

## Testing

```sh
$ npm test
```

## References

- [RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1][rfc-2616]
- [RFC 5987: Character Set and Language Encoding for Hypertext Transfer Protocol (HTTP) Header Field Parameters][rfc-5987]
- [RFC 6266: Use of the Content-Disposition Header Field in the Hypertext Transfer Protocol (HTTP)][rfc-6266]
- [Test Cases for HTTP Content-Disposition header field (RFC 6266) and the Encodings defined in RFCs 2047, 2231 and 5987][tc-2231]

[rfc-2616]: https://tools.ietf.org/html/rfc2616
[rfc-5987]: https://tools.ietf.org/html/rfc5987
[rfc-6266]: https://tools.ietf.org/html/rfc6266
[tc-2231]: http://greenbytes.de/tech/tc2231/

## License

[MIT](LICENSE)

[npm-image]: https://img.shields.io/npm/v/content-disposition.svg?style=flat
[npm-url]: https://npmjs.org/package/content-disposition
[node-version-image]: https://img.shields.io/node/v/content-disposition.svg?style=flat
[node-version-url]: https://nodejs.org/en/download
[travis-image]: https://img.shields.io/travis/jshttp/content-disposition.svg?style=flat
[travis-url]: https://travis-ci.org/jshttp/content-disposition
[coveralls-image]: https://img.shields.io/coveralls/jshttp/content-disposition.svg?style=flat
[coveralls-url]: https://coveralls.io/r/jshttp/content-disposition?branch=master
[downloads-image]: https://img.shields.io/npm/dm/content-disposition.svg?style=flat
[downloads-url]: https://npmjs.org/package/content-disposition


---

1.0.5 / 2023-01-29
==================

  * perf: skip value escaping when unnecessary

1.0.4 / 2017-09-11
==================

  * perf: skip parameter parsing when no parameters

1.0.3 / 2017-09-10
==================

  * perf: remove argument reassignment

1.0.2 / 2016-05-09
==================

  * perf: enable strict mode

1.0.1 / 2015-02-13
==================

  * Improve missing `Content-Type` header error message

1.0.0 / 2015-02-01
==================

  * Initial implementation, derived from `media-typer@0.3.0`


---

# content-type

[![NPM Version][npm-version-image]][npm-url]
[![NPM Downloads][npm-downloads-image]][npm-url]
[![Node.js Version][node-image]][node-url]
[![Build Status][ci-image]][ci-url]
[![Coverage Status][coveralls-image]][coveralls-url]

Create and parse HTTP Content-Type header according to RFC 7231

## Installation

```sh
$ npm install content-type
```

## API

```js
var contentType = require('content-type')
```

### contentType.parse(string)

```js
var obj = contentType.parse('image/svg+xml; charset=utf-8')
```

Parse a `Content-Type` header. This will return an object with the following
properties (examples are shown for the string `'image/svg+xml; charset=utf-8'`):

 - `type`: The media type (the type and subtype, always lower case).
   Example: `'image/svg+xml'`

 - `parameters`: An object of the parameters in the media type (name of parameter
   always lower case). Example: `{charset: 'utf-8'}`

Throws a `TypeError` if the string is missing or invalid.

### contentType.parse(req)

```js
var obj = contentType.parse(req)
```

Parse the `Content-Type` header from the given `req`. Short-cut for
`contentType.parse(req.headers['content-type'])`.

Throws a `TypeError` if the `Content-Type` header is missing or invalid.

### contentType.parse(res)

```js
var obj = contentType.parse(res)
```

Parse the `Content-Type` header set on the given `res`. Short-cut for
`contentType.parse(res.getHeader('content-type'))`.

Throws a `TypeError` if the `Content-Type` header is missing or invalid.

### contentType.format(obj)

```js
var str = contentType.format({
  type: 'image/svg+xml',
  parameters: { charset: 'utf-8' }
})
```

Format an object into a `Content-Type` header. This will return a string of the
content type for the given object with the following properties (examples are
shown that produce the string `'image/svg+xml; charset=utf-8'`):

 - `type`: The media type (will be lower-cased). Example: `'image/svg+xml'`

 - `parameters`: An object of the parameters in the media type (name of the
   parameter will be lower-cased). Example: `{charset: 'utf-8'}`

Throws a `TypeError` if the object contains an invalid type or parameter names.

## License

[MIT](LICENSE)

[ci-image]: https://badgen.net/github/checks/jshttp/content-type/master?label=ci
[ci-url]: https://github.com/jshttp/content-type/actions/workflows/ci.yml
[coveralls-image]: https://badgen.net/coveralls/c/github/jshttp/content-type/master
[coveralls-url]: https://coveralls.io/r/jshttp/content-type?branch=master
[node-image]: https://badgen.net/npm/node/content-type
[node-url]: https://nodejs.org/en/download
[npm-downloads-image]: https://badgen.net/npm/dm/content-type
[npm-url]: https://npmjs.org/package/content-type
[npm-version-image]: https://badgen.net/npm/v/content-type


---

# convert-source-map [![Build Status][ci-image]][ci-url]

Converts a source-map from/to  different formats and allows adding/changing properties.

```js
var convert = require('convert-source-map');

var json = convert
  .fromComment('//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYnVpbGQvZm9vLm1pbi5qcyIsInNvdXJjZXMiOlsic3JjL2Zvby5qcyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSIsInNvdXJjZVJvb3QiOiIvIn0=')
  .toJSON();

var modified = convert
  .fromComment('//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYnVpbGQvZm9vLm1pbi5qcyIsInNvdXJjZXMiOlsic3JjL2Zvby5qcyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSIsInNvdXJjZVJvb3QiOiIvIn0=')
  .setProperty('sources', [ 'SRC/FOO.JS' ])
  .toJSON();

console.log(json);
console.log(modified);
```

```json
{"version":3,"file":"build/foo.min.js","sources":["src/foo.js"],"names":[],"mappings":"AAAA","sourceRoot":"/"}
{"version":3,"file":"build/foo.min.js","sources":["SRC/FOO.JS"],"names":[],"mappings":"AAAA","sourceRoot":"/"}
```

## Upgrading

Prior to v2.0.0, the `fromMapFileComment` and `fromMapFileSource` functions took a String directory path and used that to resolve & read the source map file from the filesystem. However, this made the library limited to nodejs environments and broke on sources with querystrings.

In v2.0.0, you now need to pass a function that does the file reading. It will receive the source filename as a String that you can resolve to a filesystem path, URL, or anything else.

If you are using `convert-source-map` in nodejs and want the previous behavior, you'll use a function like such:

```diff
+ var fs = require('fs'); // Import the fs module to read a file
+ var path = require('path'); // Import the path module to resolve a path against your directory
- var conv = convert.fromMapFileSource(css, '../my-dir');
+ var conv = convert.fromMapFileSource(css, function (filename) {
+   return fs.readFileSync(path.resolve('../my-dir', filename), 'utf-8');
+ });
```

## API

### fromObject(obj)

Returns source map converter from given object.

### fromJSON(json)

Returns source map converter from given json string.

### fromURI(uri)

Returns source map converter from given uri encoded json string.

### fromBase64(base64)

Returns source map converter from given base64 encoded json string.

### fromComment(comment)

Returns source map converter from given base64 or uri encoded json string prefixed with `//# sourceMappingURL=...`.

### fromMapFileComment(comment, readMap)

Returns source map converter from given `filename` by parsing `//# sourceMappingURL=filename`.

`readMap` must be a function which receives the source map filename and returns either a String or Buffer of the source map (if read synchronously), or a `Promise` containing a String or Buffer of the source map (if read asynchronously).

If `readMap` doesn't return a `Promise`, `fromMapFileComment` will return a source map converter synchronously.

If `readMap` returns a `Promise`, `fromMapFileComment` will also return `Promise`. The `Promise` will be either resolved with the source map converter or rejected with an error.

#### Examples

**Synchronous read in Node.js:**

```js
var convert = require('convert-source-map');
var fs = require('fs');

function readMap(filename) {
  return fs.readFileSync(filename, 'utf8');
}

var json = convert
  .fromMapFileComment('//# sourceMappingURL=map-file-comment.css.map', readMap)
  .toJSON();
console.log(json);
```


**Asynchronous read in Node.js:**

```js
var convert = require('convert-source-map');
var { promises: fs } = require('fs'); // Notice the `promises` import

function readMap(filename) {
  return fs.readFile(filename, 'utf8');
}

var converter = await convert.fromMapFileComment('//# sourceMappingURL=map-file-comment.css.map', readMap)
var json = converter.toJSON();
console.log(json);
```

**Asynchronous read in the browser:**

```js
var convert = require('convert-source-map');

async function readMap(url) {
  const res = await fetch(url);
  return res.text();
}

const converter = await convert.fromMapFileComment('//# sourceMappingURL=map-file-comment.css.map', readMap)
var json = converter.toJSON();
console.log(json);
```

### fromSource(source)

Finds last sourcemap comment in file and returns source map converter or returns `null` if no source map comment was found.

### fromMapFileSource(source, readMap)

Finds last sourcemap comment in file and returns source map converter or returns `null` if no source map comment was found.

`readMap` must be a function which receives the source map filename and returns either a String or Buffer of the source map (if read synchronously), or a `Promise` containing a String or Buffer of the source map (if read asynchronously).

If `readMap` doesn't return a `Promise`, `fromMapFileSource` will return a source map converter synchronously.

If `readMap` returns a `Promise`, `fromMapFileSource` will also return `Promise`. The `Promise` will be either resolved with the source map converter or rejected with an error.

### toObject()

Returns a copy of the underlying source map.

### toJSON([space])

Converts source map to json string. If `space` is given (optional), this will be passed to
[JSON.stringify](https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/JSON/stringify) when the
JSON string is generated.

### toURI()

Converts source map to uri encoded json string.

### toBase64()

Converts source map to base64 encoded json string.

### toComment([options])

Converts source map to an inline comment that can be appended to the source-file.

By default, the comment is formatted like: `//# sourceMappingURL=...`, which you would
normally see in a JS source file.

When `options.encoding == 'uri'`, the data will be uri encoded, otherwise they will be base64 encoded.

When `options.multiline == true`, the comment is formatted like: `/*# sourceMappingURL=... */`, which you would find in a CSS source file.

### addProperty(key, value)

Adds given property to the source map. Throws an error if property already exists.

### setProperty(key, value)

Sets given property to the source map. If property doesn't exist it is added, otherwise its value is updated.

### getProperty(key)

Gets given property of the source map.

### removeComments(src)

Returns `src` with all source map comments removed

### removeMapFileComments(src)

Returns `src` with all source map comments pointing to map files removed.

### commentRegex

Provides __a fresh__ RegExp each time it is accessed. Can be used to find source map comments.

Breaks down a source map comment into groups: Groups: 1: media type, 2: MIME type, 3: charset, 4: encoding, 5: data.

### mapFileCommentRegex

Provides __a fresh__ RegExp each time it is accessed. Can be used to find source map comments pointing to map files.

### generateMapFileComment(file, [options])

Returns a comment that links to an external source map via `file`.

By default, the comment is formatted like: `//# sourceMappingURL=...`, which you would normally see in a JS source file.

When `options.multiline == true`, the comment is formatted like: `/*# sourceMappingURL=... */`, which you would find in a CSS source file.

[ci-url]: https://github.com/thlorenz/convert-source-map/actions?query=workflow:ci
[ci-image]: https://img.shields.io/github/workflow/status/thlorenz/convert-source-map/CI?style=flat-square


---

# cookie

[![NPM Version][npm-version-image]][npm-url]
[![NPM Downloads][npm-downloads-image]][npm-url]
[![Node.js Version][node-image]][node-url]
[![Build Status][ci-image]][ci-url]
[![Coverage Status][coveralls-image]][coveralls-url]

Basic HTTP cookie parser and serializer for HTTP servers.

## Installation

This is a [Node.js](https://nodejs.org/en/) module available through the
[npm registry](https://www.npmjs.com/). Installation is done using the
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):

```sh
$ npm install cookie
```

## API

```js
var cookie = require('cookie');
```

### cookie.parse(str, options)

Parse an HTTP `Cookie` header string and returning an object of all cookie name-value pairs.
The `str` argument is the string representing a `Cookie` header value and `options` is an
optional object containing additional parsing options.

```js
var cookies = cookie.parse('foo=bar; equation=E%3Dmc%5E2');
// { foo: 'bar', equation: 'E=mc^2' }
```

#### Options

`cookie.parse` accepts these properties in the options object.

##### decode

Specifies a function that will be used to decode a cookie's value. Since the value of a cookie
has a limited character set (and must be a simple string), this function can be used to decode
a previously-encoded cookie value into a JavaScript string or other object.

The default function is the global `decodeURIComponent`, which will decode any URL-encoded
sequences into their byte representations.

**note** if an error is thrown from this function, the original, non-decoded cookie value will
be returned as the cookie's value.

### cookie.serialize(name, value, options)

Serialize a cookie name-value pair into a `Set-Cookie` header string. The `name` argument is the
name for the cookie, the `value` argument is the value to set the cookie to, and the `options`
argument is an optional object containing additional serialization options.

```js
var setCookie = cookie.serialize('foo', 'bar');
// foo=bar
```

#### Options

`cookie.serialize` accepts these properties in the options object.

##### domain

Specifies the value for the [`Domain` `Set-Cookie` attribute][rfc-6265-5.2.3]. By default, no
domain is set, and most clients will consider the cookie to apply to only the current domain.

##### encode

Specifies a function that will be used to encode a cookie's value. Since value of a cookie
has a limited character set (and must be a simple string), this function can be used to encode
a value into a string suited for a cookie's value.

The default function is the global `encodeURIComponent`, which will encode a JavaScript string
into UTF-8 byte sequences and then URL-encode any that fall outside of the cookie range.

##### expires

Specifies the `Date` object to be the value for the [`Expires` `Set-Cookie` attribute][rfc-6265-5.2.1].
By default, no expiration is set, and most clients will consider this a "non-persistent cookie" and
will delete it on a condition like exiting a web browser application.

**note** the [cookie storage model specification][rfc-6265-5.3] states that if both `expires` and
`maxAge` are set, then `maxAge` takes precedence, but it is possible not all clients by obey this,
so if both are set, they should point to the same date and time.

##### httpOnly

Specifies the `boolean` value for the [`HttpOnly` `Set-Cookie` attribute][rfc-6265-5.2.6]. When truthy,
the `HttpOnly` attribute is set, otherwise it is not. By default, the `HttpOnly` attribute is not set.

**note** be careful when setting this to `true`, as compliant clients will not allow client-side
JavaScript to see the cookie in `document.cookie`.

##### maxAge

Specifies the `number` (in seconds) to be the value for the [`Max-Age` `Set-Cookie` attribute][rfc-6265-5.2.2].
The given number will be converted to an integer by rounding down. By default, no maximum age is set.

**note** the [cookie storage model specification][rfc-6265-5.3] states that if both `expires` and
`maxAge` are set, then `maxAge` takes precedence, but it is possible not all clients by obey this,
so if both are set, they should point to the same date and time.

##### partitioned

Specifies the `boolean` value for the [`Partitioned` `Set-Cookie`](rfc-cutler-httpbis-partitioned-cookies)
attribute. When truthy, the `Partitioned` attribute is set, otherwise it is not. By default, the
`Partitioned` attribute is not set.

**note** This is an attribute that has not yet been fully standardized, and may change in the future.
This also means many clients may ignore this attribute until they understand it.

More information about can be found in [the proposal](https://github.com/privacycg/CHIPS).

##### path

Specifies the value for the [`Path` `Set-Cookie` attribute][rfc-6265-5.2.4]. By default, the path
is considered the ["default path"][rfc-6265-5.1.4].

##### priority

Specifies the `string` to be the value for the [`Priority` `Set-Cookie` attribute][rfc-west-cookie-priority-00-4.1].

  - `'low'` will set the `Priority` attribute to `Low`.
  - `'medium'` will set the `Priority` attribute to `Medium`, the default priority when not set.
  - `'high'` will set the `Priority` attribute to `High`.

More information about the different priority levels can be found in
[the specification][rfc-west-cookie-priority-00-4.1].

**note** This is an attribute that has not yet been fully standardized, and may change in the future.
This also means many clients may ignore this attribute until they understand it.

##### sameSite

Specifies the `boolean` or `string` to be the value for the [`SameSite` `Set-Cookie` attribute][rfc-6265bis-09-5.4.7].

  - `true` will set the `SameSite` attribute to `Strict` for strict same site enforcement.
  - `false` will not set the `SameSite` attribute.
  - `'lax'` will set the `SameSite` attribute to `Lax` for lax same site enforcement.
  - `'none'` will set the `SameSite` attribute to `None` for an explicit cross-site cookie.
  - `'strict'` will set the `SameSite` attribute to `Strict` for strict same site enforcement.

More information about the different enforcement levels can be found in
[the specification][rfc-6265bis-09-5.4.7].

**note** This is an attribute that has not yet been fully standardized, and may change in the future.
This also means many clients may ignore this attribute until they understand it.

##### secure

Specifies the `boolean` value for the [`Secure` `Set-Cookie` attribute][rfc-6265-5.2.5]. When truthy,
the `Secure` attribute is set, otherwise it is not. By default, the `Secure` attribute is not set.

**note** be careful when setting this to `true`, as compliant clients will not send the cookie back to
the server in the future if the browser does not have an HTTPS connection.

## Example

The following example uses this module in conjunction with the Node.js core HTTP server
to prompt a user for their name and display it back on future visits.

```js
var cookie = require('cookie');
var escapeHtml = require('escape-html');
var http = require('http');
var url = require('url');

function onRequest(req, res) {
  // Parse the query string
  var query = url.parse(req.url, true, true).query;

  if (query && query.name) {
    // Set a new cookie with the name
    res.setHeader('Set-Cookie', cookie.serialize('name', String(query.name), {
      httpOnly: true,
      maxAge: 60 * 60 * 24 * 7 // 1 week
    }));

    // Redirect back after setting cookie
    res.statusCode = 302;
    res.setHeader('Location', req.headers.referer || '/');
    res.end();
    return;
  }

  // Parse the cookies on the request
  var cookies = cookie.parse(req.headers.cookie || '');

  // Get the visitor name set in the cookie
  var name = cookies.name;

  res.setHeader('Content-Type', 'text/html; charset=UTF-8');

  if (name) {
    res.write('<p>Welcome back, <b>' + escapeHtml(name) + '</b>!</p>');
  } else {
    res.write('<p>Hello, new visitor!</p>');
  }

  res.write('<form method="GET">');
  res.write('<input placeholder="enter your name" name="name"> <input type="submit" value="Set Name">');
  res.end('</form>');
}

http.createServer(onRequest).listen(3000);
```

## Testing

```sh
$ npm test
```

## Benchmark

```
$ npm run bench

> cookie@0.5.0 bench
> node benchmark/index.js

  node@18.18.2
  acorn@8.10.0
  ada@2.6.0
  ares@1.19.1
  brotli@1.0.9
  cldr@43.1
  icu@73.2
  llhttp@6.0.11
  modules@108
  napi@9
  nghttp2@1.57.0
  nghttp3@0.7.0
  ngtcp2@0.8.1
  openssl@3.0.10+quic
  simdutf@3.2.14
  tz@2023c
  undici@5.26.3
  unicode@15.0
  uv@1.44.2
  uvwasi@0.0.18
  v8@10.2.154.26-node.26
  zlib@1.2.13.1-motley

> node benchmark/parse-top.js

  cookie.parse - top sites

  14 tests completed.

  parse accounts.google.com x 2,588,913 ops/sec ±0.74% (186 runs sampled)
  parse apple.com           x 2,370,002 ops/sec ±0.69% (186 runs sampled)
  parse cloudflare.com      x 2,213,102 ops/sec ±0.88% (188 runs sampled)
  parse docs.google.com     x 2,194,157 ops/sec ±1.03% (184 runs sampled)
  parse drive.google.com    x 2,265,084 ops/sec ±0.79% (187 runs sampled)
  parse en.wikipedia.org    x   457,099 ops/sec ±0.81% (186 runs sampled)
  parse linkedin.com        x   504,407 ops/sec ±0.89% (186 runs sampled)
  parse maps.google.com     x 1,230,959 ops/sec ±0.98% (186 runs sampled)
  parse microsoft.com       x   926,294 ops/sec ±0.88% (184 runs sampled)
  parse play.google.com     x 2,311,338 ops/sec ±0.83% (185 runs sampled)
  parse support.google.com  x 1,508,850 ops/sec ±0.86% (186 runs sampled)
  parse www.google.com      x 1,022,582 ops/sec ±1.32% (182 runs sampled)
  parse youtu.be            x   332,136 ops/sec ±1.02% (185 runs sampled)
  parse youtube.com         x   323,833 ops/sec ±0.77% (183 runs sampled)

> node benchmark/parse.js

  cookie.parse - generic

  6 tests completed.

  simple      x 3,214,032 ops/sec ±1.61% (183 runs sampled)
  decode      x   587,237 ops/sec ±1.16% (187 runs sampled)
  unquote     x 2,954,618 ops/sec ±1.35% (183 runs sampled)
  duplicates  x   857,008 ops/sec ±0.89% (187 runs sampled)
  10 cookies  x   292,133 ops/sec ±0.89% (187 runs sampled)
  100 cookies x    22,610 ops/sec ±0.68% (187 runs sampled)
```

## References

- [RFC 6265: HTTP State Management Mechanism][rfc-6265]
- [Same-site Cookies][rfc-6265bis-09-5.4.7]

[rfc-cutler-httpbis-partitioned-cookies]: https://tools.ietf.org/html/draft-cutler-httpbis-partitioned-cookies/
[rfc-west-cookie-priority-00-4.1]: https://tools.ietf.org/html/draft-west-cookie-priority-00#section-4.1
[rfc-6265bis-09-5.4.7]: https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-09#section-5.4.7
[rfc-6265]: https://tools.ietf.org/html/rfc6265
[rfc-6265-5.1.4]: https://tools.ietf.org/html/rfc6265#section-5.1.4
[rfc-6265-5.2.1]: https://tools.ietf.org/html/rfc6265#section-5.2.1
[rfc-6265-5.2.2]: https://tools.ietf.org/html/rfc6265#section-5.2.2
[rfc-6265-5.2.3]: https://tools.ietf.org/html/rfc6265#section-5.2.3
[rfc-6265-5.2.4]: https://tools.ietf.org/html/rfc6265#section-5.2.4
[rfc-6265-5.2.5]: https://tools.ietf.org/html/rfc6265#section-5.2.5
[rfc-6265-5.2.6]: https://tools.ietf.org/html/rfc6265#section-5.2.6
[rfc-6265-5.3]: https://tools.ietf.org/html/rfc6265#section-5.3

## License

[MIT](LICENSE)

[ci-image]: https://badgen.net/github/checks/jshttp/cookie/master?label=ci
[ci-url]: https://github.com/jshttp/cookie/actions/workflows/ci.yml
[coveralls-image]: https://badgen.net/coveralls/c/github/jshttp/cookie/master
[coveralls-url]: https://coveralls.io/r/jshttp/cookie?branch=master
[node-image]: https://badgen.net/npm/node/cookie
[node-url]: https://nodejs.org/en/download
[npm-downloads-image]: https://badgen.net/npm/dm/cookie
[npm-url]: https://npmjs.org/package/cookie
[npm-version-image]: https://badgen.net/npm/v/cookie


---

# Security Policies and Procedures

## Reporting a Bug

The `cookie` team and community take all security bugs seriously. Thank
you for improving the security of the project. We appreciate your efforts and
responsible disclosure and will make every effort to acknowledge your
contributions.

Report security bugs by emailing the current owner(s) of `cookie`. This
information can be found in the npm registry using the command
`npm owner ls cookie`.
If unsure or unable to get the information from the above, open an issue
in the [project issue tracker](https://github.com/jshttp/cookie/issues)
asking for the current contact information.

To ensure the timely response to your report, please ensure that the entirety
of the report is contained within the email body and not solely behind a web
link or an attachment.

At least one owner will acknowledge your email within 48 hours, and will send a
more detailed response within 48 hours indicating the next steps in handling
your report. After the initial reply to your report, the owners will
endeavor to keep you informed of the progress towards a fix and full
announcement, and may ask for additional information or guidance.


---

1.0.6 / 2015-02-03
==================

* use `npm test` instead of `make test` to run tests
* clearer assertion messages when checking input


1.0.5 / 2014-09-05
==================

* add license to package.json

1.0.4 / 2014-06-25
==================

 * corrected avoidance of timing attacks (thanks @tenbits!)

1.0.3 / 2014-01-28
==================

 * [incorrect] fix for timing attacks

1.0.2 / 2014-01-28
==================

 * fix missing repository warning
 * fix typo in test

1.0.1 / 2013-04-15
==================

  * Revert "Changed underlying HMAC algo. to sha512."
  * Revert "Fix for timing attacks on MAC verification."

0.0.1 / 2010-01-03
==================

  * Initial release


---


# cookie-signature

  Sign and unsign cookies.

## Example

```js
var cookie = require('cookie-signature');

var val = cookie.sign('hello', 'tobiiscool');
val.should.equal('hello.DGDUkGlIkCzPz+C0B064FNgHdEjox7ch8tOBGslZ5QI');

var val = cookie.sign('hello', 'tobiiscool');
cookie.unsign(val, 'tobiiscool').should.equal('hello');
cookie.unsign(val, 'luna').should.be.false;
```

## License 

(The MIT License)

Copyright (c) 2012 LearnBoost &lt;tj@learnboost.com&gt;

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
'Software'), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

---

# copy-text-to-clipboard

> Copy text to the clipboard in modern browsers *(0.2 kB)*

[Try it out!](https://jsfiddle.net/sindresorhus/6406v3pf/)

## Comparison

- This module: **0.2 kB**
- [`clipboard.js`](https://github.com/zenorocha/clipboard.js): 3.4 kB

## Install

```sh
npm install copy-text-to-clipboard
```

## Usage

```js
import copy from 'copy-text-to-clipboard';

button.addEventListener('click', () => {
	copy('🦄🌈');
});
```

## API

### copy(text, options?)

Copy `text` to the clipboard.

Returns a `boolean` of whether it succeeded to copy the text.

Must be called in response to a user gesture event, like `click` or `keyup`.

#### options

Type: `object`

##### target

Type: `HTMLElement`\
Default: `document.body`

Specify a DOM element where the temporary, behind-the-scenes `textarea` should be appended, in cases where you need to stay within a focus trap, like in a modal.

## Related

- [clipboardy](https://github.com/sindresorhus/clipboardy) - Access the system clipboard (copy/paste) in Node.js


---

<div align="center">
  <a href="https://github.com/webpack/webpack">
    <img width="200" height="200"
      src="https://webpack.js.org/assets/icon-square-big.svg">
  </a>
</div>

[![npm][npm]][npm-url]
[![node][node]][node-url]
[![deps][deps]][deps-url]
[![tests][tests]][tests-url]
[![cover][cover]][cover-url]
[![chat][chat]][chat-url]
[![size][size]][size-url]

# copy-webpack-plugin

Copies individual files or entire directories, which already exist, to the build directory.

## Getting Started

To begin, you'll need to install `copy-webpack-plugin`:

```console
npm install copy-webpack-plugin --save-dev
```

or

```console
yarn add -D copy-webpack-plugin
```

or

```console
pnpm add -D copy-webpack-plugin
```

Then add the plugin to your `webpack` config. For example:

**webpack.config.js**

```js
const CopyPlugin = require("copy-webpack-plugin");

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        { from: "source", to: "dest" },
        { from: "other", to: "public" },
      ],
    }),
  ],
};
```

> ℹ️ `copy-webpack-plugin` is not designed to copy files generated from the build process; rather, it is to copy files that already exist in the source tree, as part of the build process.

> ℹ️ If you want `webpack-dev-server` to write files to the output directory during development, you can force it with the [`writeToDisk`](https://github.com/webpack/webpack-dev-middleware#writetodisk) option or the [`write-file-webpack-plugin`](https://github.com/gajus/write-file-webpack-plugin).

> ℹ️ You can get the original source filename from [Asset Objects](https://webpack.js.org/api/stats/#asset-objects).

## Options

- **[`patterns`](#patterns)**
- **[`options`](#options-1)**

The plugin's signature:

**webpack.config.js**

```js
const CopyPlugin = require("copy-webpack-plugin");

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        { from: "source", to: "dest" },
        "path/to/source", // absolute or relative, files/directories/globs - see below for examples
      ],
      options: {
        concurrency: 100,
      },
    }),
  ],
};
```

### `Patterns`

- [`from`](#from)
- [`to`](#to)
- [`context`](#context)
- [`globOptions`](#globoptions)
- [`filter`](#filter)
- [`toType`](#totype)
- [`force`](#force)
- [`priority`](#priority)
- [`transform`](#transform)
- [`transformAll`](#transformAll)
- [`noErrorOnMissing`](#noerroronmissing)
- [`info`](#info)

#### `from`

Type:

```ts
type from = string;
```

Default: `undefined`

Glob or path from where we copy files.
Globs accept [fast-glob pattern-syntax](https://github.com/mrmlnc/fast-glob#pattern-syntax).
Glob can only be a `string`.

> ⚠️ Don't use directly `\\` in `from` option if it is a `glob` (i.e `path\to\file.ext`) option because on UNIX the backslash is a valid character inside a path component, i.e., it's not a separator.
> On Windows, the forward slash and the backward slash are both separators.
> Instead please use `/`.

**webpack.config.js**

```js
module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        "relative/path/to/file.ext",
        "relative/path/to/dir",
        path.resolve(__dirname, "src", "file.ext"),
        path.resolve(__dirname, "src", "dir"),
        "**/*",
        {
          from: "**/*",
        },
        // If absolute path is a `glob` we replace backslashes with forward slashes, because only forward slashes can be used in the `glob`
        path.posix.join(
          path.resolve(__dirname, "src").replace(/\\/g, "/"),
          "*.txt"
        ),
      ],
    }),
  ],
};
```

##### `For windows`

If you define `from` as absolute file path or absolute folder path on `Windows`, you can use windows path segment (`\\`)

```js
module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: path.resolve(__dirname, "file.txt"),
        },
      ],
    }),
  ],
};
```

But you should always use forward-slashes in `glob` expressions
See [fast-glob manual](https://github.com/mrmlnc/fast-glob#how-to-write-patterns-on-windows).

```js
module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          // If absolute path is a `glob` we replace backslashes with forward slashes, because only forward slashes can be used in the `glob`
          from: path.posix.join(
            path.resolve(__dirname, "fixtures").replace(/\\/g, "/"),
            "*.txt"
          ),
        },
      ],
    }),
  ],
};
```

The `context` behaves differently depending on what the `from` is (`glob`, `file` or `dir`).
More [`examples`](#examples)

#### `to`

Type:

```ts
type to =
  | string
  | ((pathData: { context: string; absoluteFilename?: string }) => string);
```

Default: `compiler.options.output`

##### `string`

Output path.

> ⚠️ Don't use directly `\\` in `to` (i.e `path\to\dest`) option because on UNIX the backslash is a valid character inside a path component, i.e., it's not a separator.
> On Windows, the forward slash and the backward slash are both separators.
> Instead please use `/` or `path` methods.

**webpack.config.js**

```js
module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "**/*",
          to: "relative/path/to/dest/",
        },
        {
          from: "**/*",
          to: "/absolute/path/to/dest/",
        },
        {
          from: "**/*",
          to: "[path][name].[contenthash][ext]",
        },
      ],
    }),
  ],
};
```

##### `function`

Allows to modify the writing path.

> ⚠️ Don't return directly `\\` in `to` (i.e `path\to\newFile`) option because on UNIX the backslash is a valid character inside a path component, i.e., it's not a separator.
> On Windows, the forward slash and the backward slash are both separators.
> Instead please use `/` or `path` methods.

**webpack.config.js**

```js
module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "src/*.png",
          to({ context, absoluteFilename }) {
            return "dest/newPath/[name][ext]";
          },
        },
      ],
    }),
  ],
};
```

**webpack.config.js**

```js
module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "src/*.png",
          to({ context, absoluteFilename }) {
            return Promise.resolve("dest/newPath/[name][ext]");
          },
        },
      ],
    }),
  ],
};
```

#### `context`

Type:

```ts
type context = string;
```

Default: `options.context|compiler.options.context`

A path that determines how to interpret the `from` path.

> ⚠️ Don't use directly `\\` in `context` (i.e `path\to\context`) option because on UNIX the backslash is a valid character inside a path component, i.e., it's not a separator.
> On Windows, the forward slash and the backward slash are both separators.
> Instead please use `/` or `path` methods.

**webpack.config.js**

```js
module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "src/*.txt",
          to: "dest/",
          context: "app/",
        },
      ],
    }),
  ],
};
```

The `context` option can be an absolute or relative path. If `context` is a relative, then it is converted to absolute based to `compiler.options.context`

To determine the structure from which the found resources will be copied to the destination folder, the `context` option is used.

If `from` is a file, then `context` is equal to the directory in which this file is located. Accordingly, the result will be only the file name.

If `from` is a directory, then `context` is the same as `from` and is equal to the directory itself. In this case, the result will be a hierarchical structure of the found folders and files relative to the specified directory.

If `from` is a glob, then regardless of the `context` option, the result will be the structure specified in the `from` option

More [`examples`](#examples)

#### `globOptions`

Type:

```ts
type globOptions = import("globby").Options;
```

Default: `undefined`

Allows to configure the glob pattern matching library used by the plugin. [See the list of supported options][glob-options]
To exclude files from the selection, you should use [globOptions.ignore option](https://github.com/mrmlnc/fast-glob#ignore)

**webpack.config.js**

```js
module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "public/**/*",
          globOptions: {
            dot: true,
            gitignore: true,
            ignore: ["**/file.*", "**/ignored-directory/**"],
          },
        },
      ],
    }),
  ],
};
```

#### `filter`

Type:

```ts
type filter = (filepath: string) => boolean;
```

Default: `undefined`

> ℹ️ To ignore files by path please use the [`globOptions.ignore`](#globoptions) option.

**webpack.config.js**

```js
const fs = require("fs").promise;

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "public/**/*",
          filter: async (resourcePath) => {
            const data = await fs.promises.readFile(resourcePath);
            const content = data.toString();

            if (content === "my-custom-content") {
              return false;
            }

            return true;
          },
        },
      ],
    }),
  ],
};
```

#### `toType`

Type:

```ts
type toType = "dir" | "file" | "template";
```

Default: `undefined`

Determinate what is `to` option - directory, file or template.
Sometimes it is hard to say what is `to`, example `path/to/dir-with.ext`.
If you want to copy files in directory you need use `dir` option.
We try to automatically determine the `type` so you most likely do not need this option.

|             Name              |   Type   |   Default   | Description                                                                                          |
| :---------------------------: | :------: | :---------: | :--------------------------------------------------------------------------------------------------- |
|      **[`'dir'`](#dir)**      | `string` | `undefined` | If `to` has no extension or ends on `'/'`                                                            |
|     **[`'file'`](#file)**     | `string` | `undefined` | If `to` is not a directory and is not a template                                                     |
| **[`'template'`](#template)** | `string` | `undefined` | If `to` contains [a template pattern](https://webpack.js.org/configuration/output/#template-strings) |

##### `'dir'`

**webpack.config.js**

```js
module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "path/to/file.txt",
          to: "directory/with/extension.ext",
          toType: "dir",
        },
      ],
    }),
  ],
};
```

##### `'file'`

**webpack.config.js**

```js
module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "path/to/file.txt",
          to: "file/without/extension",
          toType: "file",
        },
      ],
    }),
  ],
};
```

##### `'template'`

**webpack.config.js**

```js
module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "src/",
          to: "dest/[name].[contenthash][ext]",
          toType: "template",
        },
      ],
    }),
  ],
};
```

#### `force`

Type:

```ts
type force = boolean;
```

Default: `false`

Overwrites files already in `compilation.assets` (usually added by other plugins/loaders).

**webpack.config.js**

```js
module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "src/**/*",
          to: "dest/",
          force: true,
        },
      ],
    }),
  ],
};
```

#### `priority`

Type:

```ts
type priority = number;
```

Default: `0`

Allows to specify the priority of copying files with the same destination name.
Files for patterns with higher priority will be copied later.
To overwrite files, the [`force`](#force) option must be enabled.

**webpack.config.js**

```js
module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        // Copied second and will overwrite "dir_2/file.txt"
        {
          from: "dir_1/file.txt",
          to: "newfile.txt",
          force: true,
          priority: 10,
        },
        // Copied first
        {
          from: "dir_2/file.txt",
          to: "newfile.txt",
          priority: 5,
        },
      ],
    }),
  ],
};
```

#### `transform`

Type:

```ts
type transform =
  | {
      transformer: (input: string, absoluteFilename: string) => string | Buffer;
      cache?: boolean | TransformerCacheObject | undefined;
    }
  | ((input: string, absoluteFilename: string) => string | Buffer);
```

Default: `undefined`

Allows to modify the file contents.

##### `function`

**webpack.config.js**

```js
module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "src/*.png",
          to: "dest/",
          // The `content` argument is a [`Buffer`](https://nodejs.org/api/buffer.html) object, it could be converted to a `String` to be processed using `content.toString()`
          // The `absoluteFrom` argument is a `String`, it is absolute path from where the file is being copied
          transform(content, absoluteFrom) {
            return optimize(content);
          },
        },
      ],
    }),
  ],
};
```

##### `object`

|               Name                |   Default   | Description                                                                                                      |
| :-------------------------------: | :---------: | :--------------------------------------------------------------------------------------------------------------- |
| **[`transformer`](#transformer)** | `undefined` | Allows to modify the file contents.                                                                              |
|       **[`cache`](#cache)**       |   `false`   | Enable `transform` caching. You can use `transform: { cache: { key: 'my-cache-key' } }` to invalidate the cache. |

###### `transformer`

Type:

```ts
type transformer = (input: string, absoluteFilename: string) => string;
```

Default: `undefined`

**webpack.config.js**

```js
module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "src/*.png",
          to: "dest/",
          // The `content` argument is a [`Buffer`](https://nodejs.org/api/buffer.html) object, it could be converted to a `String` to be processed using `content.toString()`
          // The `absoluteFrom` argument is a `String`, it is absolute path from where the file is being copied
          transform: {
            transformer(content, absoluteFrom) {
              return optimize(content);
            },
          },
        },
      ],
    }),
  ],
};
```

**webpack.config.js**

```js
module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "src/*.png",
          to: "dest/",
          transform: {
            transformer(content, path) {
              return Promise.resolve(optimize(content));
            },
          },
        },
      ],
    }),
  ],
};
```

###### `cache`

Type:

```ts
type cache =
  | boolean
  | {
      keys: {
        [key: string]: any;
      };
    }
  | {
      keys: (
        defaultCacheKeys: {
          [key: string]: any;
        },
        absoluteFilename: string
      ) => Promise<{
        [key: string]: any;
      }>;
    }
  | undefined;
```

Default: `false`

**webpack.config.js**

Enable/disable and configure caching.
Default path to cache directory: `node_modules/.cache/copy-webpack-plugin`.

###### `boolean`

Enables/Disable `transform` caching.

**webpack.config.js**

```js
module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "src/*.png",
          to: "dest/",
          transform: {
            transformer(content, path) {
              return optimize(content);
            },
            cache: true,
          },
        },
      ],
    }),
  ],
};
```

##### `object`

Enables `transform` caching and setup cache directory and invalidation keys.

**webpack.config.js**

```js
module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "src/*.png",
          to: "dest/",
          transform: {
            transformer(content, path) {
              return optimize(content);
            },
            cache: {
              directory: path.resolve(__dirname, "cache-directory"),
              keys: {
                // May be useful for invalidating cache based on external values
                // For example, you can invalid cache based on `process.version` - { node: process.version }
                key: "value",
              },
            },
          },
        },
      ],
    }),
  ],
};
```

You can setup invalidation keys using a function.

Simple function:

**webpack.config.js**

```js
module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "src/*.png",
          to: "dest/",
          transform: {
            transformer(content, path) {
              return optimize(content);
            },
            cache: {
              directory: path.resolve(__dirname, "cache-directory"),
              keys: (defaultCacheKeys, absoluteFrom) => {
                const keys = getCustomCacheInvalidationKeysSync();

                return {
                  ...defaultCacheKeys,
                  keys,
                };
              },
            },
          },
        },
      ],
    }),
  ],
};
```

Async function:

**webpack.config.js**

```js
module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "src/*.png",
          to: "dest/",
          transform: {
            transformer(content, path) {
              return optimize(content);
            },
            cache: {
              directory: path.resolve(__dirname, "cache-directory"),
              keys: async (defaultCacheKeys, absoluteFrom) => {
                const keys = await getCustomCacheInvalidationKeysAsync();

                return {
                  ...defaultCacheKeys,
                  keys,
                };
              },
            },
          },
        },
      ],
    }),
  ],
};
```

#### `transformAll`

Type:

```ts
type transformAll = (
  data: {
    data: Buffer;
    sourceFilename: string;
    absoluteFilename: string;
  }[]
) => any;
```

Default: `undefined`

Allows you to modify the contents of multiple files and save the result to one file.

> ℹ️ The `to` option must be specified and point to a file. It is allowed to use only `[contenthash]` and `[fullhash]` template strings.

**webpack.config.js**

```js
module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "src/**/*.txt",
          to: "dest/file.txt",
          // The `assets` argument is an assets array for the pattern.from ("src/**/*.txt")
          transformAll(assets) {
            const result = assets.reduce((accumulator, asset) => {
              // The asset content can be obtained from `asset.source` using `source` method.
              // The asset content is a [`Buffer`](https://nodejs.org/api/buffer.html) object, it could be converted to a `String` to be processed using `content.toString()`
              const content = asset.data;

              accumulator = `${accumulator}${content}\n`;
              return accumulator;
            }, "");

            return result;
          },
        },
      ],
    }),
  ],
};
```

### `noErrorOnMissing`

Type:

```ts
type noErrorOnMissing = boolean;
```

Default: `false`

Doesn't generate an error on missing file(s).

```js
module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: path.resolve(__dirname, "missing-file.txt"),
          noErrorOnMissing: true,
        },
      ],
    }),
  ],
};
```

#### `info`

Type:

```ts
type info =
  | Record<string, any>
  | ((item: {
      absoluteFilename: string;
      sourceFilename: string;
      filename: string;
      toType: ToType;
    }) => Record<string, any>);
```

Default: `undefined`

Allows to add assets info.

**webpack.config.js**

```js
module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        "relative/path/to/file.ext",
        {
          from: "**/*",
          // Terser skip this file for minimization
          info: { minimized: true },
        },
      ],
    }),
  ],
};
```

**webpack.config.js**

```js
module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        "relative/path/to/file.ext",
        {
          from: "**/*",
          // Terser skip this file for minimization
          info: (file) => ({ minimized: true }),
        },
      ],
    }),
  ],
};
```

### Options

- [`concurrency`](#concurrency)

#### `concurrency`

type:

```ts
type concurrency = number;
```

default: `100`

limits the number of simultaneous requests to fs

**webpack.config.js**

```js
module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [...patterns],
      options: { concurrency: 50 },
    }),
  ],
};
```

### Examples

#### Different variants `from` (`glob`, `file` or `dir`).

Take for example the following file structure:

```
src/directory-nested/deep-nested/deepnested-file.txt
src/directory-nested/nested-file.txt
```

##### From is a Glob

Everything that you specify in `from` will be included in the result:

**webpack.config.js**

```js
module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "src/directory-nested/**/*",
        },
      ],
    }),
  ],
};
```

Result:

```txt
src/directory-nested/deep-nested/deepnested-file.txt,
src/directory-nested/nested-file.txt
```

If you want only content `src/directory-nested/`, you should only indicate `glob` in `from`. The path to the folder in which the search should take place, should be moved to `context`.

**webpack.config.js**

```js
module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "**/*",
          context: path.resolve(__dirname, "src", "directory-nested"),
        },
      ],
    }),
  ],
};
```

Result:

```txt
deep-nested/deepnested-file.txt,
nested-file.txt
```

##### From is a Dir

**webpack.config.js**

```js
module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: path.resolve(__dirname, "src", "directory-nested"),
        },
      ],
    }),
  ],
};
```

Result:

```txt
deep-nested/deepnested-file.txt,
nested-file.txt
```

Technically, this is `**/*` with a predefined context equal to the specified directory.

**webpack.config.js**

```js
module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "**/*",
          context: path.resolve(__dirname, "src", "directory-nested"),
        },
      ],
    }),
  ],
};
```

Result:

```txt
deep-nested/deepnested-file.txt,
nested-file.txt
```

##### From is a File

```js
module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: path.resolve(
            __dirname,
            "src",
            "directory-nested",
            "nested-file.txt"
          ),
        },
      ],
    }),
  ],
};
```

Result:

```txt
nested-file.txt
```

Technically, this is a filename with a predefined context equal to `path.dirname(pathToFile)`.

**webpack.config.js**

```js
module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "nested-file.txt",
          context: path.resolve(__dirname, "src", "directory-nested"),
        },
      ],
    }),
  ],
};
```

Result:

```txt
nested-file.txt
```

#### Ignoring files

**webpack.config.js**

```js
module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: path.posix.join(
            path.resolve(__dirname, "src").replace(/\\/g, "/"),
            "**/*"
          ),
          globOptions: {
            ignore: [
              // Ignore all `txt` files
              "**/*.txt",
              // Ignore all files in all subdirectories
              "**/subdir/**",
            ],
          },
        },
      ],
    }),
  ],
};
```

#### Flatten copy

Removes all directory references and only copies file names.

> ⚠️ If files have the same name, the result is non-deterministic.

**webpack.config.js**

```js
module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "src/**/*",
          to: "[name][ext]",
        },
      ],
    }),
  ],
};
```

Result:

```txt
file-1.txt
file-2.txt
nested-file.txt
```

#### Copy in new directory

**webpack.config.js**

```js
module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          // When copying files starting with a dot, must specify the toType option
          // toType: "file",
          to({ context, absoluteFilename }) {
            return `newdirectory/${path.relative(context, absoluteFilename)}`;
          },
          from: "directory",
        },
      ],
    }),
  ],
};
```

Result:

```txt
"newdirectory/file-1.txt",
"newdirectory/nestedfile.txt",
"newdirectory/nested/deep-nested/deepnested.txt",
"newdirectory/nested/nestedfile.txt",
```

#### Skip running JavaScript files through a minimizer

Useful if you need to simply copy `*.js` files to destination "as is" without evaluating and minimizing them using Terser.

**webpack.config.js**

```js
module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        "relative/path/to/file.ext",
        {
          from: "**/*",
          // Terser skip this file for minimization
          info: { minimized: true },
        },
      ],
    }),
  ],
};
```

##### `yarn workspaces` and `monorepos`

When using `yarn workspaces` or` monorepos`, relative copy paths from node_modules can be broken due to the way packages are hoisting.
To avoid this, should explicitly specify where to copy the files from using `require.resolve`.

**webpack.config.js**

```js
module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: `${path.dirname(
            require.resolve(`${moduleName}/package.json`)
          )}/target`,
          to: "target",
        },
      ],
    }),
  ],
};
```

## Contributing

Please take a moment to read our contributing guidelines if you haven't yet done so.

[CONTRIBUTING](./.github/CONTRIBUTING.md)

## License

[MIT](./LICENSE)

[npm]: https://img.shields.io/npm/v/copy-webpack-plugin.svg
[npm-url]: https://npmjs.com/package/copy-webpack-plugin
[node]: https://img.shields.io/node/v/copy-webpack-plugin.svg
[node-url]: https://nodejs.org
[deps]: https://david-dm.org/webpack-contrib/copy-webpack-plugin.svg
[deps-url]: https://david-dm.org/webpack-contrib/copy-webpack-plugin
[tests]: https://github.com/webpack-contrib/copy-webpack-plugin/workflows/copy-webpack-plugin/badge.svg
[tests-url]: https://github.com/webpack-contrib/copy-webpack-plugin/actions
[cover]: https://codecov.io/gh/webpack-contrib/copy-webpack-plugin/branch/master/graph/badge.svg
[cover-url]: https://codecov.io/gh/webpack-contrib/copy-webpack-plugin
[chat]: https://img.shields.io/badge/gitter-webpack%2Fwebpack-brightgreen.svg
[chat-url]: https://gitter.im/webpack/webpack
[size]: https://packagephobia.now.sh/badge?p=copy-webpack-plugin
[size-url]: https://packagephobia.now.sh/result?p=copy-webpack-plugin
[glob-options]: https://github.com/sindresorhus/globby#options


---

<p align="center">
  <a href="https://gulpjs.com">
    <img height="257" width="114" src="https://raw.githubusercontent.com/gulpjs/artwork/master/gulp-2x.png">
  </a>
</p>

# glob-parent

[![NPM version][npm-image]][npm-url] [![Downloads][downloads-image]][npm-url] [![Build Status][ci-image]][ci-url] [![Coveralls Status][coveralls-image]][coveralls-url]

Extract the non-magic parent path from a glob string.

## Usage

```js
var globParent = require('glob-parent');

globParent('path/to/*.js'); // 'path/to'
globParent('/root/path/to/*.js'); // '/root/path/to'
globParent('/*.js'); // '/'
globParent('*.js'); // '.'
globParent('**/*.js'); // '.'
globParent('path/{to,from}'); // 'path'
globParent('path/!(to|from)'); // 'path'
globParent('path/?(to|from)'); // 'path'
globParent('path/+(to|from)'); // 'path'
globParent('path/*(to|from)'); // 'path'
globParent('path/@(to|from)'); // 'path'
globParent('path/**/*'); // 'path'

// if provided a non-glob path, returns the nearest dir
globParent('path/foo/bar.js'); // 'path/foo'
globParent('path/foo/'); // 'path/foo'
globParent('path/foo'); // 'path' (see issue #3 for details)
```

## API

### `globParent(maybeGlobString, [options])`

Takes a string and returns the part of the path before the glob begins. Be aware of Escaping rules and Limitations below.

#### options

```js
{
  // Disables the automatic conversion of slashes for Windows
  flipBackslashes: true;
}
```

## Escaping

The following characters have special significance in glob patterns and must be escaped if you want them to be treated as regular path characters:

- `?` (question mark) unless used as a path segment alone
- `*` (asterisk)
- `|` (pipe)
- `(` (opening parenthesis)
- `)` (closing parenthesis)
- `{` (opening curly brace)
- `}` (closing curly brace)
- `[` (opening bracket)
- `]` (closing bracket)

**Example**

```js
globParent('foo/[bar]/'); // 'foo'
globParent('foo/\\[bar]/'); // 'foo/[bar]'
```

## Limitations

### Braces & Brackets

This library attempts a quick and imperfect method of determining which path
parts have glob magic without fully parsing/lexing the pattern. There are some
advanced use cases that can trip it up, such as nested braces where the outer
pair is escaped and the inner one contains a path separator. If you find
yourself in the unlikely circumstance of being affected by this or need to
ensure higher-fidelity glob handling in your library, it is recommended that you
pre-process your input with [expand-braces] and/or [expand-brackets].

### Windows

Backslashes are not valid path separators for globs. If a path with backslashes
is provided anyway, for simple cases, glob-parent will replace the path
separator for you and return the non-glob parent path (now with
forward-slashes, which are still valid as Windows path separators).

This cannot be used in conjunction with escape characters.

```js
// BAD
globParent('C:\\Program Files \\(x86\\)\\*.ext'); // 'C:/Program Files /(x86/)'

// GOOD
globParent('C:/Program Files\\(x86\\)/*.ext'); // 'C:/Program Files (x86)'
```

If you are using escape characters for a pattern without path parts (i.e.
relative to `cwd`), prefix with `./` to avoid confusing glob-parent.

```js
// BAD
globParent('foo \\[bar]'); // 'foo '
globParent('foo \\[bar]*'); // 'foo '

// GOOD
globParent('./foo \\[bar]'); // 'foo [bar]'
globParent('./foo \\[bar]*'); // '.'
```

## License

ISC

<!-- prettier-ignore-start -->
[downloads-image]: https://img.shields.io/npm/dm/glob-parent.svg?style=flat-square
[npm-url]: https://www.npmjs.com/package/glob-parent
[npm-image]: https://img.shields.io/npm/v/glob-parent.svg?style=flat-square

[ci-url]: https://github.com/gulpjs/glob-parent/actions?query=workflow:dev
[ci-image]: https://img.shields.io/github/workflow/status/gulpjs/glob-parent/dev?style=flat-square

[coveralls-url]: https://coveralls.io/r/gulpjs/glob-parent
[coveralls-image]: https://img.shields.io/coveralls/gulpjs/glob-parent/master.svg?style=flat-square
<!-- prettier-ignore-end -->

<!-- prettier-ignore-start -->
[expand-braces]: https://github.com/jonschlinkert/expand-braces
[expand-brackets]: https://github.com/jonschlinkert/expand-brackets
<!-- prettier-ignore-end -->


---

# globby

> User-friendly glob matching

Based on [`fast-glob`](https://github.com/mrmlnc/fast-glob) but adds a bunch of useful features.

## Features

- Promise API
- Multiple patterns
- Negated patterns: `['foo*', '!foobar']`
- Expands directories: `foo` → `foo/**/*`
- Supports `.gitignore` and similar ignore config files
- Supports `URL` as `cwd`

## Install

```
$ npm install globby
```

## Usage

```
├── unicorn
├── cake
└── rainbow
```

```js
import {globby} from 'globby';

const paths = await globby(['*', '!cake']);

console.log(paths);
//=> ['unicorn', 'rainbow']
```

## API

Note that glob patterns can only contain forward-slashes, not backward-slashes, so if you want to construct a glob pattern from path components, you need to use `path.posix.join()` instead of `path.join()`.

### globby(patterns, options?)

Returns a `Promise<string[]>` of matching paths.

#### patterns

Type: `string | string[]`

See supported `minimatch` [patterns](https://github.com/isaacs/minimatch#usage).

#### options

Type: `object`

See the [`fast-glob` options](https://github.com/mrmlnc/fast-glob#options-3) in addition to the ones below.

##### expandDirectories

Type: `boolean | string[] | object`\
Default: `true`

If set to `true`, `globby` will automatically glob directories for you. If you define an `Array` it will only glob files that matches the patterns inside the `Array`. You can also define an `object` with `files` and `extensions` like below:

```js
import {globby} from 'globby';

(async () => {
	const paths = await globby('images', {
		expandDirectories: {
			files: ['cat', 'unicorn', '*.jpg'],
			extensions: ['png']
		}
	});

	console.log(paths);
	//=> ['cat.png', 'unicorn.png', 'cow.jpg', 'rainbow.jpg']
})();
```

Note that if you set this option to `false`, you won't get back matched directories unless you set `onlyFiles: false`.

##### gitignore

Type: `boolean`\
Default: `false`

Respect ignore patterns in `.gitignore` files that apply to the globbed files.

##### ignoreFiles

Type: `string | string[]`\
Default: `undefined`

Glob patterns to look for ignore files, which are then used to ignore globbed files.

This is a more generic form of the `gitignore` option, allowing you to find ignore files with a [compatible syntax](http://git-scm.com/docs/gitignore). For instance, this works with Babel's `.babelignore`, Prettier's `.prettierignore`, or ESLint's `.eslintignore` files.

### globbySync(patterns, options?)

Returns `string[]` of matching paths.

### globbyStream(patterns, options?)

Returns a [`stream.Readable`](https://nodejs.org/api/stream.html#stream_readable_streams) of matching paths.

Since Node.js 10, [readable streams are iterable](https://nodejs.org/api/stream.html#stream_readable_symbol_asynciterator), so you can loop over glob matches in a [`for await...of` loop](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of) like this:

```js
import {globbyStream} from 'globby';

(async () => {
	for await (const path of globbyStream('*.tmp')) {
		console.log(path);
	}
})();
```

### generateGlobTasks(patterns, options?)

Returns an `Promise<object[]>` in the format `{patterns: string[], options: Object}`, which can be passed as arguments to [`fast-glob`](https://github.com/mrmlnc/fast-glob). This is useful for other globbing-related packages.

Note that you should avoid running the same tasks multiple times as they contain a file system cache. Instead, run this method each time to ensure file system changes are taken into consideration.

### generateGlobTasksSync(patterns, options?)

Returns an `object[]` in the format `{patterns: string[], options: Object}`, which can be passed as arguments to [`fast-glob`](https://github.com/mrmlnc/fast-glob). This is useful for other globbing-related packages.

Takes the same arguments as `generateGlobTasks`.

### isDynamicPattern(patterns, options?)

Returns a `boolean` of whether there are any special glob characters in the `patterns`.

Note that the options affect the results.

This function is backed by [`fast-glob`](https://github.com/mrmlnc/fast-glob#isdynamicpatternpattern-options).

### isGitIgnored(options?)

Returns a `Promise<(path: URL | string) => boolean>` indicating whether a given path is ignored via a `.gitignore` file.

Takes `cwd?: URL | string` as options.

```js
import {isGitIgnored} from 'globby';

const isIgnored = await isGitIgnored();

console.log(isIgnored('some/file'));
```

### isGitIgnoredSync(options?)

Returns a `(path: URL | string) => boolean` indicating whether a given path is ignored via a `.gitignore` file.

Takes `cwd?: URL | string` as options.

## Globbing patterns

Just a quick overview.

- `*` matches any number of characters, but not `/`
- `?` matches a single character, but not `/`
- `**` matches any number of characters, including `/`, as long as it's the only thing in a path part
- `{}` allows for a comma-separated list of "or" expressions
- `!` at the beginning of a pattern will negate the match

[Various patterns and expected matches.](https://github.com/sindresorhus/multimatch/blob/main/test/test.js)

## globby for enterprise

Available as part of the Tidelift Subscription.

The maintainers of globby and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-globby?utm_source=npm-globby&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)

## Related

- [multimatch](https://github.com/sindresorhus/multimatch) - Match against a list instead of the filesystem
- [matcher](https://github.com/sindresorhus/matcher) - Simple wildcard matching
- [del](https://github.com/sindresorhus/del) - Delete files and directories
- [make-dir](https://github.com/sindresorhus/make-dir) - Make a directory and its parents if needed


---

# slash

> Convert Windows backslash paths to slash paths: `foo\\bar` ➔ `foo/bar`

[Forward-slash paths can be used in Windows](http://superuser.com/a/176395/6877) as long as they're not extended-length paths and don't contain any non-ascii characters.

This was created since the `path` methods in Node.js outputs `\\` paths on Windows.

## Install

```
$ npm install slash
```

## Usage

```js
import path from 'path';
import slash from 'slash';

const string = path.join('foo', 'bar');
// Unix    => foo/bar
// Windows => foo\\bar

slash(string);
// Unix    => foo/bar
// Windows => foo/bar
```

## API

### slash(path)

Type: `string`

Accepts a Windows backslash path and returns a path with forward slashes.

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-slash?utm_source=npm-slash&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

![logo](https://user-images.githubusercontent.com/2213682/146607186-8e13ddef-26a4-4ebf-befd-5aac9d77c090.png)

<div align="center">

[![fundraising](https://opencollective.com/core-js/all/badge.svg?label=fundraising)](https://opencollective.com/core-js) [![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/zloirock/core-js/blob/master/CONTRIBUTING.md) [![version](https://img.shields.io/npm/v/core-js.svg)](https://www.npmjs.com/package/core-js) [![core-js downloads](https://img.shields.io/npm/dm/core-js.svg?label=npm%20i%20core-js)](https://npm-stat.com/charts.html?package=core-js&package=core-js-pure&package=core-js-compat&from=2014-11-18)

</div>

**I highly recommend reading this: [So, what's next?](https://github.com/zloirock/core-js/blob/master/docs/2023-02-14-so-whats-next.md)**
---

> Modular standard library for JavaScript. Includes polyfills for [ECMAScript up to 2023](https://github.com/zloirock/core-js#ecmascript): [promises](https://github.com/zloirock/core-js#ecmascript-promise), [symbols](https://github.com/zloirock/core-js#ecmascript-symbol), [collections](https://github.com/zloirock/core-js#ecmascript-collections), iterators, [typed arrays](https://github.com/zloirock/core-js#ecmascript-typed-arrays), many other features, [ECMAScript proposals](https://github.com/zloirock/core-js#ecmascript-proposals), [some cross-platform WHATWG / W3C features and proposals](#web-standards) like [`URL`](https://github.com/zloirock/core-js#url-and-urlsearchparams). You can load only required features or use it without global namespace pollution.

## Raising funds

`core-js` isn't backed by a company, so the future of this project depends on you. Become a sponsor or a backer if you are interested in `core-js`: [**Open Collective**](https://opencollective.com/core-js), [**Patreon**](https://patreon.com/zloirock), [**Boosty**](https://boosty.to/zloirock), **Bitcoin ( bc1qlea7544qtsmj2rayg0lthvza9fau63ux0fstcz )**, [**Alipay**](https://user-images.githubusercontent.com/2213682/219464783-c17ad329-17ce-4795-82a7-f609493345ed.png).

---

<a href="https://opencollective.com/core-js/sponsor/0/website" target="_blank"><img src="https://opencollective.com/core-js/sponsor/0/avatar.svg"></a><a href="https://opencollective.com/core-js/sponsor/1/website" target="_blank"><img src="https://opencollective.com/core-js/sponsor/1/avatar.svg"></a><a href="https://opencollective.com/core-js/sponsor/2/website" target="_blank"><img src="https://opencollective.com/core-js/sponsor/2/avatar.svg"></a><a href="https://opencollective.com/core-js/sponsor/3/website" target="_blank"><img src="https://opencollective.com/core-js/sponsor/3/avatar.svg"></a><a href="https://opencollective.com/core-js/sponsor/4/website" target="_blank"><img src="https://opencollective.com/core-js/sponsor/4/avatar.svg"></a><a href="https://opencollective.com/core-js/sponsor/5/website" target="_blank"><img src="https://opencollective.com/core-js/sponsor/5/avatar.svg"></a><a href="https://opencollective.com/core-js/sponsor/6/website" target="_blank"><img src="https://opencollective.com/core-js/sponsor/6/avatar.svg"></a><a href="https://opencollective.com/core-js/sponsor/7/website" target="_blank"><img src="https://opencollective.com/core-js/sponsor/7/avatar.svg"></a><a href="https://opencollective.com/core-js/sponsor/8/website" target="_blank"><img src="https://opencollective.com/core-js/sponsor/8/avatar.svg"></a><a href="https://opencollective.com/core-js/sponsor/9/website" target="_blank"><img src="https://opencollective.com/core-js/sponsor/9/avatar.svg"></a><a href="https://opencollective.com/core-js/sponsor/10/website" target="_blank"><img src="https://opencollective.com/core-js/sponsor/10/avatar.svg"></a><a href="https://opencollective.com/core-js/sponsor/11/website" target="_blank"><img src="https://opencollective.com/core-js/sponsor/11/avatar.svg"></a>

---

<a href="https://opencollective.com/core-js#backers" target="_blank"><img src="https://opencollective.com/core-js/backers.svg?width=890"></a>

---

[*Example of usage*](https://tinyurl.com/2mknex43):
```js
import 'core-js/actual';

Promise.resolve(42).then(it => console.log(it)); // => 42

Array.from(new Set([1, 2, 3]).union(new Set([3, 4, 5]))); // => [1, 2, 3, 4, 5]

[1, 2].flatMap(it => [it, it]); // => [1, 1, 2, 2]

(function * (i) { while (true) yield i++; })(1)
  .drop(1).take(5)
  .filter(it => it % 2)
  .map(it => it ** 2)
  .toArray(); // => [9, 25]

structuredClone(new Set([1, 2, 3])); // => new Set([1, 2, 3])
```

*You can load only required features*:
```js
import 'core-js/actual/promise';
import 'core-js/actual/set';
import 'core-js/actual/iterator';
import 'core-js/actual/array/from';
import 'core-js/actual/array/flat-map';
import 'core-js/actual/structured-clone';

Promise.resolve(42).then(it => console.log(it)); // => 42

Array.from(new Set([1, 2, 3]).union(new Set([3, 4, 5]))); // => [1, 2, 3, 4, 5]

[1, 2].flatMap(it => [it, it]); // => [1, 1, 2, 2]

(function * (i) { while (true) yield i++; })(1)
  .drop(1).take(5)
  .filter(it => it % 2)
  .map(it => it ** 2)
  .toArray(); // => [9, 25]

structuredClone(new Set([1, 2, 3])); // => new Set([1, 2, 3])
```

*Or use it without global namespace pollution*:
```js
import Promise from 'core-js-pure/actual/promise';
import Set from 'core-js-pure/actual/set';
import Iterator from 'core-js-pure/actual/iterator';
import from from 'core-js-pure/actual/array/from';
import flatMap from 'core-js-pure/actual/array/flat-map';
import structuredClone from 'core-js-pure/actual/structured-clone';

Promise.resolve(42).then(it => console.log(it)); // => 42

from(new Set([1, 2, 3]).union(new Set([3, 4, 5]))); // => [1, 2, 3, 4, 5]

flatMap([1, 2], it => [it, it]); // => [1, 1, 2, 2]

Iterator.from(function * (i) { while (true) yield i++; }(1))
  .drop(1).take(5)
  .filter(it => it % 2)
  .map(it => it ** 2)
  .toArray(); // => [9, 25]

structuredClone(new Set([1, 2, 3])); // => new Set([1, 2, 3])
```

**It's a global version (first 2 examples), for more info see [`core-js` documentation](https://github.com/zloirock/core-js/blob/master/README.md).**


---

This folder contains entry points for all `core-js` features with dependencies. It's the recommended way for usage only required features.


---

This folder contains entry points for [stable ECMAScript features](https://github.com/zloirock/core-js/#ecmascript) with dependencies.


---

This folder contains entry points for all `core-js` features with dependencies. It's the recommended way for usage only required features.


---

This folder contains internal parts of `core-js` like helpers.


---

This folder contains implementations of polyfills. It's not recommended to include in your projects directly if you don't completely understand what are you doing.


---

This folder contains entry points for all stable `core-js` features with dependencies. It's the recommended way for usage only required features.


---

This folder contains entry points for [ECMAScript proposals](https://github.com/zloirock/core-js#ecmascript-proposals) with dependencies.


---

This folder contains entry points for features from [WHATWG / W3C](https://github.com/zloirock/core-js#web-standards) with dependencies.


---

![logo](https://user-images.githubusercontent.com/2213682/146607186-8e13ddef-26a4-4ebf-befd-5aac9d77c090.png)

<div align="center">

[![fundraising](https://opencollective.com/core-js/all/badge.svg?label=fundraising)](https://opencollective.com/core-js) [![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/zloirock/core-js/blob/master/CONTRIBUTING.md) [![version](https://img.shields.io/npm/v/core-js-compat.svg)](https://www.npmjs.com/package/core-js-compat) [![core-js-compat downloads](https://img.shields.io/npm/dm/core-js-compat.svg?label=npm%20i%20core-js-compat)](https://npm-stat.com/charts.html?package=core-js&package=core-js-pure&package=core-js-compat&from=2014-11-18)

</div>

**I highly recommend reading this: [So, what's next?](https://github.com/zloirock/core-js/blob/master/docs/2023-02-14-so-whats-next.md)**
---

[`core-js-compat` package](https://github.com/zloirock/core-js/tree/master/packages/core-js-compat) contains data about the necessity of [`core-js`](https://github.com/zloirock/core-js) modules and API for getting a list of required core-js modules by browserslist query.

```js
import compat from 'core-js-compat';

const {
  list,                       // array of required modules
  targets,                    // object with targets for each module
} = compat({
  targets: '> 1%',            // browserslist query or object of minimum environment versions to support, see below
  modules: [                  // optional list / filter of modules - regex, string or an array of them:
    'core-js/actual',         // - an entry point
    'esnext.array.unique-by', // - a module name (or just a start of a module name)
    /^web\./,                 // - regex that a module name must satisfy
  ],
  exclude: [                  // optional list / filter of modules to exclude, the signature is similar to `modules` option
    'web.atob',
  ],
  version: '3.41',            // used `core-js` version, by default - the latest
  inverse: false,             // inverse of the result - shows modules that are NOT required for the target environment
});

console.log(targets);
/* =>
{
  'es.error.cause': { ios: '14.5-14.8' },
  'es.aggregate-error.cause': { ios: '14.5-14.8' },
  'es.array.at': { ios: '14.5-14.8' },
  'es.array.find-last': { firefox: '100', ios: '14.5-14.8' },
  'es.array.find-last-index': { firefox: '100', ios: '14.5-14.8' },
  'es.array.includes': { firefox: '100' },
  'es.array.push': { chrome: '100', edge: '101', ios: '14.5-14.8', safari: '15.4' },
  'es.array.unshift': { ios: '14.5-14.8', safari: '15.4' },
  'es.object.has-own': { ios: '14.5-14.8' },
  'es.regexp.flags': { chrome: '100', edge: '101' },
  'es.string.at-alternative': { ios: '14.5-14.8' },
  'es.typed-array.at': { ios: '14.5-14.8' },
  'es.typed-array.find-last': { firefox: '100', ios: '14.5-14.8' },
  'es.typed-array.find-last-index': { firefox: '100', ios: '14.5-14.8' },
  'esnext.array.group': { chrome: '100', edge: '101', firefox: '100', ios: '14.5-14.8', safari: '15.4' },
  'esnext.array.group-by': { chrome: '100', edge: '101', firefox: '100', ios: '14.5-14.8', safari: '15.4' },
  'esnext.array.group-by-to-map': { chrome: '100', edge: '101', firefox: '100', ios: '14.5-14.8', safari: '15.4' },
  'esnext.array.group-to-map': { chrome: '100', edge: '101', firefox: '100', ios: '14.5-14.8', safari: '15.4' },
  'esnext.array.to-reversed': { chrome: '100', edge: '101', firefox: '100', ios: '14.5-14.8', safari: '15.4' },
  'esnext.array.to-sorted': { chrome: '100', edge: '101', firefox: '100', ios: '14.5-14.8', safari: '15.4' },
  'esnext.array.to-spliced': { chrome: '100', edge: '101', firefox: '100', ios: '14.5-14.8', safari: '15.4' },
  'esnext.array.unique-by': { chrome: '100', edge: '101', firefox: '100', ios: '14.5-14.8', safari: '15.4' },
  'esnext.array.with': { chrome: '100', edge: '101', firefox: '100', ios: '14.5-14.8', safari: '15.4' },
  'esnext.typed-array.to-reversed': { chrome: '100', edge: '101', firefox: '100', ios: '14.5-14.8', safari: '15.4' },
  'esnext.typed-array.to-sorted': { chrome: '100', edge: '101', firefox: '100', ios: '14.5-14.8', safari: '15.4' },
  'esnext.typed-array.to-spliced': { chrome: '100', edge: '101', firefox: '100', ios: '14.5-14.8', safari: '15.4' },
  'esnext.typed-array.with': { chrome: '100', edge: '101', firefox: '100', ios: '14.5-14.8', safari: '15.4' },
  'web.dom-exception.stack': { chrome: '100', edge: '101', ios: '14.5-14.8', safari: '15.4' },
  'web.immediate': { chrome: '100', edge: '101', firefox: '100', ios: '14.5-14.8', safari: '15.4' },
  'web.structured-clone': { chrome: '100', edge: '101', firefox: '100', ios: '14.5-14.8', safari: '15.4' }
}
*/
```

### `targets` option
`targets` could be [a `browserslist` query](https://github.com/browserslist/browserslist) or a targets object that specifies minimum environment versions to support:
```js
// browserslist query:
'defaults, not IE 11, maintained node versions';
// object (sure, all those fields optional):
({
  android: '4.0',         // Android WebView version
  bun: '0.1.2',           // Bun version
  chrome: '38',           // Chrome version
  'chrome-android': '18', // Chrome for Android version
  deno: '1.12',           // Deno version
  edge: '13',             // Edge version
  electron: '5.0',        // Electron framework version
  firefox: '15',          // Firefox version
  'firefox-android': '4', // Firefox for Android version
  hermes: '0.11',         // Hermes version
  ie: '8',                // Internet Explorer version
  ios: '13.0',            // iOS Safari version
  node: 'current',        // NodeJS version, you can use 'current' for set it to currently used
  opera: '12',            // Opera version
  'opera-android': '7',   // Opera for Android version
  phantom: '1.9',         // PhantomJS headless browser version
  quest: '5.0',           // Meta Quest Browser version
  'react-native': '0.70', // React Native version (default Hermes engine)
  rhino: '1.7.13',        // Rhino engine version
  safari: '14.0',         // Safari version
  samsung: '14.0',        // Samsung Internet version
  esmodules: true,        // That option set target to minimum supporting ES Modules versions of all browsers
  browsers: '> 0.25%',    // Browserslist query or object with target browsers
});
```

### Additional API:

```js
// equals of of the method from the example above
require('core-js-compat/compat')({ targets, modules, version }); // => { list: Array<ModuleName>, targets: { [ModuleName]: { [EngineName]: EngineVersion } } }
// or
require('core-js-compat').compat({ targets, modules, version }); // => { list: Array<ModuleName>, targets: { [ModuleName]: { [EngineName]: EngineVersion } } }

// full compat data:
require('core-js-compat/data'); // => { [ModuleName]: { [EngineName]: EngineVersion } }
// or
require('core-js-compat').data; // => { [ModuleName]: { [EngineName]: EngineVersion } }

// map of modules by `core-js` entry points:
require('core-js-compat/entries'); // => { [EntryPoint]: Array<ModuleName> }
// or
require('core-js-compat').entries; // => { [EntryPoint]: Array<ModuleName> }

// full list of modules:
require('core-js-compat/modules'); // => Array<ModuleName>
// or
require('core-js-compat').modules; // => Array<ModuleName>

// the subset of modules which available in the passed `core-js` version:
require('core-js-compat/get-modules-list-for-target-version')('3.41'); // => Array<ModuleName>
// or
require('core-js-compat').getModulesListForTargetVersion('3.41'); // => Array<ModuleName>
```

If you wanna help to improve this data, you could take a look at the related section of [`CONTRIBUTING.md`](https://github.com/zloirock/core-js/blob/master/CONTRIBUTING.md#how-to-update-core-js-compat-data). The visualization of compatibility data and the browser tests runner is available [here](http://zloirock.github.io/core-js/compat/), the example:

![compat-table](https://user-images.githubusercontent.com/2213682/217452234-ccdcfc5a-c7d3-40d1-ab3f-86902315b8c3.png)


---

![logo](https://user-images.githubusercontent.com/2213682/146607186-8e13ddef-26a4-4ebf-befd-5aac9d77c090.png)

<div align="center">

[![fundraising](https://opencollective.com/core-js/all/badge.svg?label=fundraising)](https://opencollective.com/core-js) [![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/zloirock/core-js/blob/master/CONTRIBUTING.md) [![version](https://img.shields.io/npm/v/core-js-pure.svg)](https://www.npmjs.com/package/core-js-pure) [![core-js-pure downloads](https://img.shields.io/npm/dm/core-js-pure.svg?label=npm%20i%20core-js-pure)](https://npm-stat.com/charts.html?package=core-js&package=core-js-pure&package=core-js-compat&from=2014-11-18)

</div>

**I highly recommend reading this: [So, what's next?](https://github.com/zloirock/core-js/blob/master/docs/2023-02-14-so-whats-next.md)**
---

> Modular standard library for JavaScript. Includes polyfills for [ECMAScript up to 2023](https://github.com/zloirock/core-js#ecmascript): [promises](https://github.com/zloirock/core-js#ecmascript-promise), [symbols](https://github.com/zloirock/core-js#ecmascript-symbol), [collections](https://github.com/zloirock/core-js#ecmascript-collections), iterators, [typed arrays](https://github.com/zloirock/core-js#ecmascript-typed-arrays), many other features, [ECMAScript proposals](https://github.com/zloirock/core-js#ecmascript-proposals), [some cross-platform WHATWG / W3C features and proposals](#web-standards) like [`URL`](https://github.com/zloirock/core-js#url-and-urlsearchparams). You can load only required features or use it without global namespace pollution.

## Raising funds

`core-js` isn't backed by a company, so the future of this project depends on you. Become a sponsor or a backer if you are interested in `core-js`: [**Open Collective**](https://opencollective.com/core-js), [**Patreon**](https://patreon.com/zloirock), [**Boosty**](https://boosty.to/zloirock), **Bitcoin ( bc1qlea7544qtsmj2rayg0lthvza9fau63ux0fstcz )**, [**Alipay**](https://user-images.githubusercontent.com/2213682/219464783-c17ad329-17ce-4795-82a7-f609493345ed.png).

---

<a href="https://opencollective.com/core-js/sponsor/0/website" target="_blank"><img src="https://opencollective.com/core-js/sponsor/0/avatar.svg"></a><a href="https://opencollective.com/core-js/sponsor/1/website" target="_blank"><img src="https://opencollective.com/core-js/sponsor/1/avatar.svg"></a><a href="https://opencollective.com/core-js/sponsor/2/website" target="_blank"><img src="https://opencollective.com/core-js/sponsor/2/avatar.svg"></a><a href="https://opencollective.com/core-js/sponsor/3/website" target="_blank"><img src="https://opencollective.com/core-js/sponsor/3/avatar.svg"></a><a href="https://opencollective.com/core-js/sponsor/4/website" target="_blank"><img src="https://opencollective.com/core-js/sponsor/4/avatar.svg"></a><a href="https://opencollective.com/core-js/sponsor/5/website" target="_blank"><img src="https://opencollective.com/core-js/sponsor/5/avatar.svg"></a><a href="https://opencollective.com/core-js/sponsor/6/website" target="_blank"><img src="https://opencollective.com/core-js/sponsor/6/avatar.svg"></a><a href="https://opencollective.com/core-js/sponsor/7/website" target="_blank"><img src="https://opencollective.com/core-js/sponsor/7/avatar.svg"></a><a href="https://opencollective.com/core-js/sponsor/8/website" target="_blank"><img src="https://opencollective.com/core-js/sponsor/8/avatar.svg"></a><a href="https://opencollective.com/core-js/sponsor/9/website" target="_blank"><img src="https://opencollective.com/core-js/sponsor/9/avatar.svg"></a><a href="https://opencollective.com/core-js/sponsor/10/website" target="_blank"><img src="https://opencollective.com/core-js/sponsor/10/avatar.svg"></a><a href="https://opencollective.com/core-js/sponsor/11/website" target="_blank"><img src="https://opencollective.com/core-js/sponsor/11/avatar.svg"></a>

---

<a href="https://opencollective.com/core-js#backers" target="_blank"><img src="https://opencollective.com/core-js/backers.svg?width=890"></a>

---

[*Example of usage*](https://tinyurl.com/2mknex43):
```js
import 'core-js/actual';

Promise.resolve(42).then(it => console.log(it)); // => 42

Array.from(new Set([1, 2, 3]).union(new Set([3, 4, 5]))); // => [1, 2, 3, 4, 5]

[1, 2].flatMap(it => [it, it]); // => [1, 1, 2, 2]

(function * (i) { while (true) yield i++; })(1)
  .drop(1).take(5)
  .filter(it => it % 2)
  .map(it => it ** 2)
  .toArray(); // => [9, 25]

structuredClone(new Set([1, 2, 3])); // => new Set([1, 2, 3])
```

*You can load only required features*:
```js
import 'core-js/actual/promise';
import 'core-js/actual/set';
import 'core-js/actual/iterator';
import 'core-js/actual/array/from';
import 'core-js/actual/array/flat-map';
import 'core-js/actual/structured-clone';

Promise.resolve(42).then(it => console.log(it)); // => 42

Array.from(new Set([1, 2, 3]).union(new Set([3, 4, 5]))); // => [1, 2, 3, 4, 5]

[1, 2].flatMap(it => [it, it]); // => [1, 1, 2, 2]

(function * (i) { while (true) yield i++; })(1)
  .drop(1).take(5)
  .filter(it => it % 2)
  .map(it => it ** 2)
  .toArray(); // => [9, 25]

structuredClone(new Set([1, 2, 3])); // => new Set([1, 2, 3])
```

*Or use it without global namespace pollution*:
```js
import Promise from 'core-js-pure/actual/promise';
import Set from 'core-js-pure/actual/set';
import Iterator from 'core-js-pure/actual/iterator';
import from from 'core-js-pure/actual/array/from';
import flatMap from 'core-js-pure/actual/array/flat-map';
import structuredClone from 'core-js-pure/actual/structured-clone';

Promise.resolve(42).then(it => console.log(it)); // => 42

from(new Set([1, 2, 3]).union(new Set([3, 4, 5]))); // => [1, 2, 3, 4, 5]

flatMap([1, 2], it => [it, it]); // => [1, 1, 2, 2]

Iterator.from(function * (i) { while (true) yield i++; }(1))
  .drop(1).take(5)
  .filter(it => it % 2)
  .map(it => it ** 2)
  .toArray(); // => [9, 25]

structuredClone(new Set([1, 2, 3])); // => new Set([1, 2, 3])
```

**It's a version without global namespace pollution (the third example), for more info see [`core-js` documentation](https://github.com/zloirock/core-js/blob/master/README.md)**.


---

This folder contains entry points for all `core-js` features with dependencies. It's the recommended way for usage only required features.


---

This folder contains entry points for [stable ECMAScript features](https://github.com/zloirock/core-js/#ecmascript) with dependencies.


---

This folder contains entry points for all `core-js` features with dependencies. It's the recommended way for usage only required features.


---

This folder contains internal parts of `core-js` like helpers.


---

This folder contains implementations of polyfills. It's not recommended to include in your projects directly if you don't completely understand what are you doing.


---

This folder contains entry points for all stable `core-js` features with dependencies. It's the recommended way for usage only required features.


---

This folder contains entry points for [ECMAScript proposals](https://github.com/zloirock/core-js#ecmascript-proposals) with dependencies.


---

This folder contains entry points for features from [WHATWG / W3C](https://github.com/zloirock/core-js#web-standards) with dependencies.


---

# core-util-is

The `util.is*` functions introduced in Node v0.12.


---

# cosmiconfig

[![codecov](https://codecov.io/gh/cosmiconfig/cosmiconfig/branch/main/graph/badge.svg)](https://codecov.io/gh/cosmiconfig/cosmiconfig)

Cosmiconfig searches for and loads configuration for your program.

It features smart defaults based on conventional expectations in the JavaScript ecosystem.
But it's also flexible enough to search wherever you'd like to search, and load whatever you'd like to load.

By default, Cosmiconfig will start where you tell it to start and search up the directory tree for the following:

- a `package.json` property
- a JSON or YAML, extensionless "rc file"
- an "rc file" with the extensions `.json`, `.yaml`, `.yml`, `.js`, `.ts`, `.mjs`, or `.cjs`
- any of the above two inside a `.config` subdirectory
- a `.config.js`, `.config.ts`, `.config.mjs`, or `.config.cjs` file

For example, if your module's name is "myapp", cosmiconfig will search up the directory tree for configuration in the following places:

- a `myapp` property in `package.json`
- a `.myapprc` file in JSON or YAML format
- a `.myapprc.json`, `.myapprc.yaml`, `.myapprc.yml`, `.myapprc.js`, `.myapprc.ts`, `.myapprc.mjs`, or `.myapprc.cjs` file
- a `myapprc`, `myapprc.json`, `myapprc.yaml`, `myapprc.yml`, `myapprc.js`, `myapprc.ts` or `myapprc.cjs` file inside a `.config` subdirectory
- a `myapp.config.js`, `myapp.config.ts`, `myapp.config.mjs`, or `myapp.config.cjs` file

Cosmiconfig continues to search up the directory tree, checking each of these places in each directory, until it finds some acceptable configuration (or hits the home directory).

## Table of contents

- [Installation](#installation)
- [Usage for tooling developers](#usage-for-tooling-developers)
- [Result](#result)
- [Asynchronous API](#asynchronous-api)
  - [cosmiconfig()](#cosmiconfig-1)
  - [explorer.search()](#explorersearch)
  - [explorer.load()](#explorerload)
  - [explorer.clearLoadCache()](#explorerclearloadcache)
  - [explorer.clearSearchCache()](#explorerclearsearchcache)
  - [explorer.clearCaches()](#explorerclearcaches)
- [Synchronous API](#synchronous-api)
  - [cosmiconfigSync()](#cosmiconfigsync)
  - [explorerSync.search()](#explorersyncsearch)
  - [explorerSync.load()](#explorersyncload)
  - [explorerSync.clearLoadCache()](#explorersyncclearloadcache)
  - [explorerSync.clearSearchCache()](#explorersyncclearsearchcache)
  - [explorerSync.clearCaches()](#explorersyncclearcaches)
- [cosmiconfigOptions](#cosmiconfigoptions)
  - [searchPlaces](#searchplaces)
  - [loaders](#loaders)
  - [packageProp](#packageprop)
  - [stopDir](#stopdir)
  - [cache](#cache)
  - [transform](#transform)
  - [ignoreEmptySearchPlaces](#ignoreemptysearchplaces)
- [Loading JS modules](#loading-js-modules)
- [Caching](#caching)
- [Differences from rc](#differences-from-rc)
- [Usage for end users](#usage-for-end-users)
- [Contributing & Development](#contributing--development)

## Installation

```
npm install cosmiconfig
```

Tested in Node 14+.

## Usage for tooling developers

*If you are an end user (i.e. a user of a tool that uses cosmiconfig, like `prettier` or `stylelint`),
you can skip down to [the end user section](#usage-for-end-users).*

Create a Cosmiconfig explorer, then either `search` for or directly `load` a configuration file.

```js
const { cosmiconfig, cosmiconfigSync } = require('cosmiconfig');
// ...
const explorer = cosmiconfig(moduleName);

// Search for a configuration by walking up directories.
// See documentation for search, below.
explorer.search()
  .then((result) => {
    // result.config is the parsed configuration object.
    // result.filepath is the path to the config file that was found.
    // result.isEmpty is true if there was nothing to parse in the config file.
  })
  .catch((error) => {
    // Do something constructive.
  });

// Load a configuration directly when you know where it should be.
// The result object is the same as for search.
// See documentation for load, below.
explorer.load(pathToConfig).then(..);

// You can also search and load synchronously.
const explorerSync = cosmiconfigSync(moduleName);

const searchedFor = explorerSync.search();
const loaded = explorerSync.load(pathToConfig);
```

## Result

The result object you get from `search` or `load` has the following properties:

- **config:** The parsed configuration object. `undefined` if the file is empty.
- **filepath:** The path to the configuration file that was found.
- **isEmpty:** `true` if the configuration file is empty. This property will not be present if the configuration file is not empty.

## Asynchronous API

### cosmiconfig()

```js
const { cosmiconfig } = require('cosmiconfig');
const explorer = cosmiconfig(moduleName[, cosmiconfigOptions])
```

Creates a cosmiconfig instance ("explorer") configured according to the arguments, and initializes its caches.

#### moduleName

Type: `string`. **Required.**

Your module name. This is used to create the default [`searchPlaces`] and [`packageProp`].

If your [`searchPlaces`] value will include files, as it does by default (e.g. `${moduleName}rc`), your `moduleName` must consist of characters allowed in filenames. That means you should not copy scoped package names, such as `@my-org/my-package`, directly into `moduleName`.

**[`cosmiconfigOptions`] are documented below.**
You may not need them, and should first read about the functions you'll use.

### explorer.search()

```js
explorer.search([searchFrom]).then(result => {..})
```

Searches for a configuration file. Returns a Promise that resolves with a [result] or with `null`, if no configuration file is found.

You can do the same thing synchronously with [`explorerSync.search()`].

Let's say your module name is `goldengrahams` so you initialized with `const explorer = cosmiconfig('goldengrahams');`.
Here's how your default [`search()`] will work:

- Starting from `process.cwd()` (or some other directory defined by the `searchFrom` argument to [`search()`]), look for configuration objects in the following places:
  1. A `goldengrahams` property in a `package.json` file.
  2. A `.goldengrahamsrc` file with JSON or YAML syntax.
  3. A `.goldengrahamsrc.json`, `.goldengrahamsrc.yaml`, `.goldengrahamsrc.yml`, `.goldengrahamsrc.js`, `.goldengrahamsrc.ts`, or `.goldengrahamsrc.cjs` file. (To learn more about how JS files are loaded, see ["Loading JS modules"].)
  4. A `goldengrahamsrc`, `goldengrahamsrc.json`, `goldengrahamsrc.yaml`, `goldengrahamsrc.yml`, `goldengrahamsrc.js`, `goldengrahamsrc.ts`, or `goldengrahamsrc.cjs` file in the `.config` subdirectory.
  5. A `goldengrahams.config.js`, `goldengrahams.config.ts`, `goldengrahams.config.mjs`, or `goldengrahams.config.cjs` file. (To learn more about how JS files are loaded, see ["Loading JS modules"].)
- If none of those searches reveal a configuration object, move up one directory level and try again.
  So the search continues in `./`, `../`, `../../`, `../../../`, etc., checking the same places in each directory.
- Continue searching until arriving at your home directory (or some other directory defined by the cosmiconfig option [`stopDir`]).
- For JS files,
- If at any point a parsable configuration is found, the [`search()`] Promise resolves with its [result] \(or, with [`explorerSync.search()`], the [result] is returned).
- If no configuration object is found, the [`search()`] Promise resolves with `null` (or, with [`explorerSync.search()`], `null` is returned).
- If a configuration object is found *but is malformed* (causing a parsing error), the [`search()`] Promise rejects with that error (so you should `.catch()` it). (Or, with [`explorerSync.search()`], the error is thrown.)

**If you know exactly where your configuration file should be, you can use [`load()`], instead.**

**The search process is highly customizable.**
Use the cosmiconfig options [`searchPlaces`] and [`loaders`] to precisely define where you want to look for configurations and how you want to load them.

#### searchFrom

Type: `string`.
Default: `process.cwd()`.

A filename.
[`search()`] will start its search here.

If the value is a directory, that's where the search starts.
If it's a file, the search starts in that file's directory.

### explorer.load()

```js
explorer.load(loadPath).then(result => {..})
```

Loads a configuration file. Returns a Promise that resolves with a [result] or rejects with an error (if the file does not exist or cannot be loaded).

Use `load` if you already know where the configuration file is and you just need to load it.

```js
explorer.load('load/this/file.json'); // Tries to load load/this/file.json.
```

If you load a `package.json` file, the result will be derived from whatever property is specified as your [`packageProp`].

You can do the same thing synchronously with [`explorerSync.load()`].

### explorer.clearLoadCache()

Clears the cache used in [`load()`].

### explorer.clearSearchCache()

Clears the cache used in [`search()`].

### explorer.clearCaches()

Performs both [`clearLoadCache()`] and [`clearSearchCache()`].

## Synchronous API

### cosmiconfigSync()

```js
const { cosmiconfigSync } = require('cosmiconfig');
const explorerSync = cosmiconfigSync(moduleName[, cosmiconfigOptions])
```

Creates a *synchronous* cosmiconfig instance ("explorerSync") configured according to the arguments, and initializes its caches.

See [`cosmiconfig()`](#cosmiconfig-1).

### explorerSync.search()

```js
const result = explorerSync.search([searchFrom]);
```

Synchronous version of [`explorer.search()`].

Returns a [result] or `null`.

### explorerSync.load()

```js
const result = explorerSync.load(loadPath);
```

Synchronous version of [`explorer.load()`].

Returns a [result].

### explorerSync.clearLoadCache()

Clears the cache used in [`load()`].

### explorerSync.clearSearchCache()

Clears the cache used in [`search()`].

### explorerSync.clearCaches()

Performs both [`clearLoadCache()`] and [`clearSearchCache()`].

## cosmiconfigOptions

Type: `Object`.

Possible options are documented below.

### searchPlaces

Type: `Array<string>`.
Default: See below.

An array of places that [`search()`] will check in each directory as it moves up the directory tree.
Each place is relative to the directory being searched, and the places are checked in the specified order.

**Default `searchPlaces`:**

For the [asynchronous API](#asynchronous-api), these are the default `searchPlaces`:

```js
[
  'package.json',
  `.${moduleName}rc`,
  `.${moduleName}rc.json`,
  `.${moduleName}rc.yaml`,
  `.${moduleName}rc.yml`,
  `.${moduleName}rc.js`,
  `.${moduleName}rc.ts`,
  `.${moduleName}rc.mjs`,
  `.${moduleName}rc.cjs`,
  `.config/${moduleName}rc`,
  `.config/${moduleName}rc.json`,
  `.config/${moduleName}rc.yaml`,
  `.config/${moduleName}rc.yml`,
  `.config/${moduleName}rc.js`,
  `.config/${moduleName}rc.ts`,
  `.config/${moduleName}rc.cjs`,
  `${moduleName}.config.js`,
  `${moduleName}.config.ts`,
  `${moduleName}.config.mjs`,
  `${moduleName}.config.cjs`,
];
```

For the [synchronous API](#synchronous-api), the only difference is that `.mjs` files are not included. See ["Loading JS modules"] for more information.

Create your own array to search more, fewer, or altogether different places.

Every item in `searchPlaces` needs to have a loader in [`loaders`] that corresponds to its extension.
(Common extensions are covered by default loaders.)
Read more about [`loaders`] below.

`package.json` is a special value: When it is included in `searchPlaces`, Cosmiconfig will always parse it as JSON and load a property within it, not the whole file.
That property is defined with the [`packageProp`] option, and defaults to your module name.

Examples, with a module named `porgy`:

```js
// Disallow extensions on rc files:
['package.json', '.porgyrc', 'porgy.config.js'][
  // Limit the options dramatically:
  ('package.json', '.porgyrc')
][
  // Maybe you want to look for a wide variety of JS flavors:
  ('porgy.config.js',
  'porgy.config.mjs',
  'porgy.config.ts',
  'porgy.config.coffee')
][
  // ^^ You will need to designate custom loaders to tell
  // Cosmiconfig how to handle `.ts` and `.coffee` files.

  // Look within a .config/ subdirectory of every searched directory:
  ('package.json',
  '.porgyrc',
  '.config/.porgyrc',
  '.porgyrc.json',
  '.config/.porgyrc.json')
];
```

### loaders

Type: `Object`.
Default: See below.

An object that maps extensions to the loader functions responsible for loading and parsing files with those extensions.

Cosmiconfig exposes its default loaders on the named export `defaultLoaders` and `defaultLoadersSync`.

**Default `loaders`:**

```js
const { defaultLoaders, defaultLoadersSync } = require('cosmiconfig');

console.log(Object.entries(defaultLoaders));
// [
//   [ '.mjs', [Function: loadJs] ],
//   [ '.cjs', [Function: loadJs] ],
//   [ '.js', [Function: loadJs] ],
//   [ '.ts', [Function: loadTs] ],
//   [ '.json', [Function: loadJson] ],
//   [ '.yaml', [Function: loadYaml] ],
//   [ '.yml', [Function: loadYaml] ],
//   [ 'noExt', [Function: loadYaml] ]
// ]

console.log(Object.entries(defaultLoadersSync));
// [
//   [ '.cjs', [Function: loadJsSync] ],
//   [ '.js', [Function: loadJsSync] ],
//   [ '.ts', [Function: loadTsSync] ],
//   [ '.json', [Function: loadJson] ],
//   [ '.yaml', [Function: loadYaml] ],
//   [ '.yml', [Function: loadYaml] ],
//   [ 'noExt', [Function: loadYaml] ]
// ]
```

(YAML is a superset of JSON; which means YAML parsers can parse JSON; which is how extensionless files can be either YAML *or* JSON with only one parser.)

**If you provide a `loaders` object, your object will be *merged* with the defaults.**
So you can override one or two without having to override them all.

**Keys in `loaders`** are extensions (starting with a period), or `noExt` to specify the loader for files *without* extensions, like `.myapprc`.

**Values in `loaders`** are a loader function (described below) whose values are loader functions.

**The most common use case for custom loaders value is to load extensionless `rc` files as strict JSON**, instead of JSON *or* YAML (the default).
To accomplish that, provide the following `loaders` value:

```js
{
  noExt: defaultLoaders['.json'];
}
```

If you want to load files that are not handled by the loader functions Cosmiconfig exposes, you can write a custom loader function or use one from NPM if it exists.

**Third-party loaders:**

- [cosmiconfig-typescript-loader](https://github.com/codex-/cosmiconfig-typescript-loader)

**Use cases for custom loader function:**

- Allow configuration syntaxes that aren't handled by Cosmiconfig's defaults, like JSON5, INI, or XML.
- Allow ES2015 modules from `.mjs` configuration files.
- Parse JS files with Babel before deriving the configuration.

**Custom loader functions** have the following signature:

```js
// Sync
(filepath: string, content: string) => Object | null

// Async
(filepath: string, content: string) => Object | null | Promise<Object | null>
```

Cosmiconfig reads the file when it checks whether the file exists, so it will provide you with both the file's path and its content.
Do whatever you need to, and return either a configuration object or `null` (or, for async-only loaders, a Promise that resolves with one of those).
`null` indicates that no real configuration was found and the search should continue.

A few things to note:

- If you use a custom loader, be aware of whether it's sync or async: you cannot use async customer loaders with the sync API ([`cosmiconfigSync()`]).
- **Special JS syntax can also be handled by using a `require` hook**, because `defaultLoaders['.js']` just uses `require`.
  Whether you use custom loaders or a `require` hook is up to you.

Examples:

```js
// Allow JSON5 syntax:
{
  '.json': json5Loader
}

// Allow a special configuration syntax of your own creation:
{
  '.special': specialLoader
}

// Allow many flavors of JS, using custom loaders:
{
  '.coffee': coffeeScriptLoader
}

// Allow many flavors of JS but rely on require hooks:
{
  '.coffee': defaultLoaders['.js']
}
```

### packageProp

Type: `string | Array<string>`.
Default: `` `${moduleName}` ``.

Name of the property in `package.json` to look for.

Use a period-delimited string or an array of strings to describe a path to nested properties.

For example, the value `'configs.myPackage'` or `['configs', 'myPackage']` will get you the `"myPackage"` value in a `package.json` like this:

```json
{
  "configs": {
    "myPackage": {..}
  }
}
```

If nested property names within the path include periods, you need to use an array of strings. For example, the value `['configs', 'foo.bar', 'baz']` will get you the `"baz"` value in a `package.json` like this:

```json
{
  "configs": {
    "foo.bar": {
      "baz": {..}
    }
  }
}
```

If a string includes period but corresponds to a top-level property name, it will not be interpreted as a period-delimited path. For example, the value `'one.two'` will get you the `"three"` value in a `package.json` like this:

```json
{
  "one.two": "three",
  "one": {
    "two": "four"
  }
}
```

### stopDir

Type: `string`.
Default: Absolute path to your home directory.

Directory where the search will stop.

### cache

Type: `boolean`.
Default: `true`.

If `false`, no caches will be used.
Read more about ["Caching"](#caching) below.

### transform

Type: `(Result) => Promise<Result> | Result`.

A function that transforms the parsed configuration. Receives the [result].

If using [`search()`] or [`load()`] \(which are async), the transform function can return the transformed result or return a Promise that resolves with the transformed result.
If using `cosmiconfigSync`, [`search()`] or [`load()`], the function must be synchronous and return the transformed result.

The reason you might use this option — instead of simply applying your transform function some other way — is that *the transformed result will be cached*. If your transformation involves additional filesystem I/O or other potentially slow processing, you can use this option to avoid repeating those steps every time a given configuration is searched or loaded.

### ignoreEmptySearchPlaces

Type: `boolean`.
Default: `true`.

By default, if [`search()`] encounters an empty file (containing nothing but whitespace) in one of the [`searchPlaces`], it will ignore the empty file and move on.
If you'd like to load empty configuration files, instead, set this option to `false`.

Why might you want to load empty configuration files?
If you want to throw an error, or if an empty configuration file means something to your program.

## Loading JS modules

Your end users can provide JS configuration files as ECMAScript modules (ESM) under the following conditions:

- You (the cosmiconfig user) use cosmiconfig's [asynchronous API](#asynchronous-api).
- Your end user runs a version of Node that supports ESM ([>=12.17.0](https://nodejs.org/en/blog/release/v12.17.0/), or earlier with the `--experimental-modules` flag).
- Your end user provides an `.mjs` configuration file, or a `.js` file whose nearest parent `package.json` file contains `"type": "module"`. (See [Node's method for determining a file's module system](https://nodejs.org/api/packages.html#packages_determining_module_system).)

With cosmiconfig's [asynchronous API](#asynchronous-api), the default [`searchPlaces`] include `.js`, `.ts`, `.mjs`, and `.cjs` files. Cosmiconfig loads all these file types with the [dynamic `import` function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import#dynamic_imports).

With the [synchronous API](#synchronous-api), JS configuration files are always treated as CommonJS, and `.mjs` files are ignored, because there is no synchronous API for the dynamic `import` function.

## Caching

As of v2, cosmiconfig uses caching to reduce the need for repetitious reading of the filesystem or expensive transforms. Every new cosmiconfig instance (created with `cosmiconfig()`) has its own caches.

To avoid or work around caching, you can do the following:

- Set the `cosmiconfig` option [`cache`] to `false`.
- Use the cache-clearing methods [`clearLoadCache()`], [`clearSearchCache()`], and [`clearCaches()`].
- Create separate instances of cosmiconfig (separate "explorers").

## Differences from [rc](https://github.com/dominictarr/rc)

[rc](https://github.com/dominictarr/rc) serves its focused purpose well. cosmiconfig differs in a few key ways — making it more useful for some projects, less useful for others:

- Looks for configuration in some different places: in a `package.json` property, an rc file, a `.config.js` file, and rc files with extensions.
- Built-in support for JSON, YAML, and CommonJS formats.
- Stops at the first configuration found, instead of finding all that can be found up the directory tree and merging them automatically.
- Options.
- Asynchronous by default (though can be run synchronously).

## Usage for end users

When configuring a tool, you can use multiple file formats and put these in multiple places.

Usually, a tool would mention this in its own README file,
but by default, these are the following places, where `{NAME}` represents the name of the tool:

```
package.json
.{NAME}rc
.{NAME}rc.json
.{NAME}rc.yaml
.{NAME}rc.yml
.{NAME}rc.js
.{NAME}rc.ts
.{NAME}rc.cjs
.config/{NAME}rc
.config/{NAME}rc.json
.config/{NAME}rc.yaml
.config/{NAME}rc.yml
.config/{NAME}rc.js
.config/{NAME}rc.ts
.config/{NAME}rc.cjs
{NAME}.config.js
{NAME}.config.ts
{NAME}.config.cjs
```

The contents of these files are defined by the tool.
For example, you can configure prettier to enforce semicolons at the end of the line
using a file named `.config/prettierrc.yml`:

```yaml
semi: true
```

Additionally, you have the option to put a property named after the tool in your `package.json` file,
with the contents of that property being the same as the file contents. To use the same example as above:

```json
{
  "name": "your-project",
  "dependencies": {},
  "prettier": {
    "semi": true
  }
}
```

This has the advantage that you can put the configuration of all tools
(at least the ones that use cosmiconfig) in one file.

You can also add a `cosmiconfig` key within your `package.json` file or create one of the following files
to configure `cosmiconfig` itself:

```
.config.json
.config.yaml
.config.yml
.config.js
.config.ts
.config.cjs
```

The following property is currently actively supported in these places:

```yaml
cosmiconfig:
  # overrides where configuration files are being searched to enforce a custom naming convention and format
  searchPlaces:
    - .config/{name}.yml
```

> **Note:** technically, you can overwrite all options described in [cosmiconfigOptions](#cosmiconfigoptions) here,
> but everything not listed above should be used at your own risk, as it has not been tested explicitly.

You can also add more root properties outside the `cosmiconfig` property
to configure your tools, entirely eliminating the need to look for additional configuration files:

```yaml
cosmiconfig:
  searchPlaces: []

prettier:
  semi: true
```

## Contributing & Development

Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.

And please do participate!

[result]: #result

[`load()`]: #explorerload

[`search()`]: #explorersearch

[`clearloadcache()`]: #explorerclearloadcache

[`clearsearchcache()`]: #explorerclearsearchcache

[`cosmiconfig()`]: #cosmiconfig

[`cosmiconfigSync()`]: #cosmiconfigsync

[`clearcaches()`]: #explorerclearcaches

[`packageprop`]: #packageprop

[`cache`]: #cache

[`stopdir`]: #stopdir

[`searchplaces`]: #searchplaces

[`loaders`]: #loaders

[`cosmiconfigoptions`]: #cosmiconfigoptions

[`explorerSync.search()`]: #explorersyncsearch

[`explorerSync.load()`]: #explorersyncload

[`explorer.search()`]: #explorersearch

[`explorer.load()`]: #explorerload

["Loading JS modules"]: #loading-js-modules


---

# cross-spawn

[![NPM version][npm-image]][npm-url] [![Downloads][downloads-image]][npm-url] [![Build Status][ci-image]][ci-url] [![Build status][appveyor-image]][appveyor-url]

[npm-url]:https://npmjs.org/package/cross-spawn
[downloads-image]:https://img.shields.io/npm/dm/cross-spawn.svg
[npm-image]:https://img.shields.io/npm/v/cross-spawn.svg
[ci-url]:https://github.com/moxystudio/node-cross-spawn/actions/workflows/ci.yaml
[ci-image]:https://github.com/moxystudio/node-cross-spawn/actions/workflows/ci.yaml/badge.svg
[appveyor-url]:https://ci.appveyor.com/project/satazor/node-cross-spawn
[appveyor-image]:https://img.shields.io/appveyor/ci/satazor/node-cross-spawn/master.svg

A cross platform solution to node's spawn and spawnSync.

## Installation

Node.js version 8 and up:
`$ npm install cross-spawn`

Node.js version 7 and under:
`$ npm install cross-spawn@6`

## Why

Node has issues when using spawn on Windows:

- It ignores [PATHEXT](https://github.com/joyent/node/issues/2318)
- It does not support [shebangs](https://en.wikipedia.org/wiki/Shebang_(Unix))
- Has problems running commands with [spaces](https://github.com/nodejs/node/issues/7367)
- Has problems running commands with posix relative paths (e.g.: `./my-folder/my-executable`)
- Has an [issue](https://github.com/moxystudio/node-cross-spawn/issues/82) with command shims (files in `node_modules/.bin/`), where arguments with quotes and parenthesis would result in [invalid syntax error](https://github.com/moxystudio/node-cross-spawn/blob/e77b8f22a416db46b6196767bcd35601d7e11d54/test/index.test.js#L149)
- No `options.shell` support on node `<v4.8`

All these issues are handled correctly by `cross-spawn`.
There are some known modules, such as [win-spawn](https://github.com/ForbesLindesay/win-spawn), that try to solve this but they are either broken or provide faulty escaping of shell arguments.


## Usage

Exactly the same way as node's [`spawn`](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options) or [`spawnSync`](https://nodejs.org/api/child_process.html#child_process_child_process_spawnsync_command_args_options), so it's a drop in replacement.


```js
const spawn = require('cross-spawn');

// Spawn NPM asynchronously
const child = spawn('npm', ['list', '-g', '-depth', '0'], { stdio: 'inherit' });

// Spawn NPM synchronously
const result = spawn.sync('npm', ['list', '-g', '-depth', '0'], { stdio: 'inherit' });
```


## Caveats

### Using `options.shell` as an alternative to `cross-spawn`

Starting from node `v4.8`, `spawn` has a `shell` option that allows you run commands from within a shell. This new option solves
the [PATHEXT](https://github.com/joyent/node/issues/2318) issue but:

- It's not supported in node `<v4.8`
- You must manually escape the command and arguments which is very error prone, specially when passing user input
- There are a lot of other unresolved issues from the [Why](#why) section that you must take into account

If you are using the `shell` option to spawn a command in a cross platform way, consider using `cross-spawn` instead. You have been warned.

### `options.shell` support

While `cross-spawn` adds support for `options.shell` in node `<v4.8`, all of its enhancements are disabled.

This mimics the Node.js behavior. More specifically, the command and its arguments will not be automatically escaped nor shebang support will be offered. This is by design because if you are using `options.shell` you are probably targeting a specific platform anyway and you don't want things to get into your way.

### Shebangs support

While `cross-spawn` handles shebangs on Windows, its support is limited. More specifically, it just supports `#!/usr/bin/env <program>` where `<program>` must not contain any arguments.   
If you would like to have the shebang support improved, feel free to contribute via a pull-request.

Remember to always test your code on Windows!


## Tests

`$ npm test`   
`$ npm test -- --watch` during development


## License

Released under the [MIT License](https://www.opensource.org/licenses/mit-license.php).


---

<div align="center">
	<br>
	<br>
	<img src="media/logo.svg" alt="type-fest" height="300">
	<br>
	<br>
	<b>A collection of essential TypeScript types</b>
	<br>
	<br>
	<br>
	<br>
	<div align="center">
		<p>
			<p>
				<sup>
					<a href="https://github.com/sponsors/sindresorhus">Sindre Sorhus' open source work is supported by the community</a>
				</sup>
			</p>
			<sup>Special thanks to:</sup>
			<br>
			<br>
			<a href="https://standardresume.co/tech">
				<img src="https://sindresorhus.com/assets/thanks/standard-resume-logo.svg" width="180"/>
			</a>
			<br>
			<br>
			<a href="https://workos.com/?utm_campaign=github_repo&utm_medium=referral&utm_content=type-fest&utm_source=github">
				<div>
					<img src="https://sindresorhus.com/assets/thanks/workos-logo-white-bg.svg" width="220" alt="WorkOS">
				</div>
				<b>Your app, enterprise-ready.</b>
				<div>
					<sub>Start selling to enterprise customers with just a few lines of code.</sub>
					<br>
					<sup>Add Single Sign-On (and more) in minutes instead of months.</sup>
				</div>
			</a>
		</p>
	</div>
	<br>
	<hr>
</div>
<br>
<br>

[![](https://img.shields.io/badge/unicorn-approved-ff69b4.svg)](https://giphy.com/gifs/illustration-rainbow-unicorn-26AHG5KGFxSkUWw1i)
[![npm dependents](https://badgen.net/npm/dependents/type-fest)](https://www.npmjs.com/package/type-fest?activeTab=dependents)
[![npm downloads](https://badgen.net/npm/dt/type-fest)](https://www.npmjs.com/package/type-fest)
[![Docs](https://paka.dev/badges/v0/cute.svg)](https://paka.dev/npm/type-fest)

Many of the types here should have been built-in. You can help by suggesting some of them to the [TypeScript project](https://github.com/Microsoft/TypeScript/blob/master/CONTRIBUTING.md).

Either add this package as a dependency or copy-paste the needed types. No credit required. 👌

PR welcome for additional commonly needed types and docs improvements. Read the [contributing guidelines](.github/contributing.md) first.

## Install

```
$ npm install type-fest
```

*Requires TypeScript >=3.8*

## Usage

```ts
import {Except} from 'type-fest';

type Foo = {
	unicorn: string;
	rainbow: boolean;
};

type FooWithoutRainbow = Except<Foo, 'rainbow'>;
//=> {unicorn: string}
```

## API

Click the type names for complete docs.

### Basic

- [`Primitive`](source/primitive.d.ts) - Matches any [primitive value](https://developer.mozilla.org/en-US/docs/Glossary/Primitive).
- [`Class`](source/basic.d.ts) - Matches a [`class` constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes).
- [`TypedArray`](source/typed-array.d.ts) - Matches any [typed array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray), like `Uint8Array` or `Float64Array`.
- [`JsonObject`](source/basic.d.ts) - Matches a JSON object.
- [`JsonArray`](source/basic.d.ts) - Matches a JSON array.
- [`JsonValue`](source/basic.d.ts) - Matches any valid JSON value.
- [`ObservableLike`](source/observable-like.d.ts) - Matches a value that is like an [Observable](https://github.com/tc39/proposal-observable).

### Utilities

- [`Except`](source/except.d.ts) - Create a type from an object type without certain keys. This is a stricter version of [`Omit`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-5.html#the-omit-helper-type).
- [`Mutable`](source/mutable.d.ts) - Create a type that strips `readonly` from all or some of an object's keys. The inverse of `Readonly<T>`.
- [`Merge`](source/merge.d.ts) - Merge two types into a new type. Keys of the second type overrides keys of the first type.
- [`MergeExclusive`](source/merge-exclusive.d.ts) - Create a type that has mutually exclusive keys.
- [`RequireAtLeastOne`](source/require-at-least-one.d.ts) - Create a type that requires at least one of the given keys.
- [`RequireExactlyOne`](source/require-exactly-one.d.ts) - Create a type that requires exactly a single key of the given keys and disallows more.
- [`PartialDeep`](source/partial-deep.d.ts) - Create a deeply optional version of another type. Use [`Partial<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1401-L1406) if you only need one level deep.
- [`ReadonlyDeep`](source/readonly-deep.d.ts) - Create a deeply immutable version of an `object`/`Map`/`Set`/`Array` type. Use [`Readonly<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1415-L1420) if you only need one level deep.
- [`LiteralUnion`](source/literal-union.d.ts) - Create a union type by combining primitive types and literal types without sacrificing auto-completion in IDEs for the literal type part of the union. Workaround for [Microsoft/TypeScript#29729](https://github.com/Microsoft/TypeScript/issues/29729).
- [`Promisable`](source/promisable.d.ts) - Create a type that represents either the value or the value wrapped in `PromiseLike`.
- [`Opaque`](source/opaque.d.ts) - Create an [opaque type](https://codemix.com/opaque-types-in-javascript/).
- [`SetOptional`](source/set-optional.d.ts) - Create a type that makes the given keys optional.
- [`SetRequired`](source/set-required.d.ts) - Create a type that makes the given keys required.
- [`ValueOf`](source/value-of.d.ts) - Create a union of the given object's values, and optionally specify which keys to get the values from.
- [`PromiseValue`](source/promise-value.d.ts) - Returns the type that is wrapped inside a `Promise`.
- [`AsyncReturnType`](source/async-return-type.d.ts) - Unwrap the return type of a function that returns a `Promise`.
- [`ConditionalKeys`](source/conditional-keys.d.ts) - Extract keys from a shape where values extend the given `Condition` type.
- [`ConditionalPick`](source/conditional-pick.d.ts) - Like `Pick` except it selects properties from a shape where the values extend the given `Condition` type.
- [`ConditionalExcept`](source/conditional-except.d.ts) - Like `Omit` except it removes properties from a shape where the values extend the given `Condition` type.
- [`UnionToIntersection`](source/union-to-intersection.d.ts) - Convert a union type to an intersection type.
- [`Stringified`](source/stringified.d.ts) - Create a type with the keys of the given type changed to `string` type.
- [`FixedLengthArray`](source/fixed-length-array.d.ts) - Create a type that represents an array of the given type and length.
- [`IterableElement`](source/iterable-element.d.ts) - Get the element type of an `Iterable`/`AsyncIterable`. For example, an array or a generator.
- [`Entry`](source/entry.d.ts) - Create a type that represents the type of an entry of a collection.
- [`Entries`](source/entries.d.ts) - Create a type that represents the type of the entries of a collection.
- [`SetReturnType`](source/set-return-type.d.ts) - Create a function type with a return type of your choice and the same parameters as the given function type.
- [`Asyncify`](source/asyncify.d.ts) - Create an async version of the given function type.
- [`Includes`](ts41/includes.ts) - Returns a boolean for whether the given array includes the given item.
- [`Simplify`](source/simplify.d.ts) - Flatten the type output to improve type hints shown in editors.

### Template literal types

*Note:* These require [TypeScript 4.1 or newer](https://devblogs.microsoft.com/typescript/announcing-typescript-4-1/#template-literal-types).

- [`CamelCase`](ts41/camel-case.d.ts) – Convert a string literal to camel-case (`fooBar`).
- [`CamelCasedProperties`](ts41/camel-cased-properties.d.ts) – Convert object properties to camel-case  (`fooBar`).
- [`CamelCasedPropertiesDeep`](ts41/camel-cased-properties-deep.d.ts) – Convert object properties to camel-case recursively  (`fooBar`).
- [`KebabCase`](ts41/kebab-case.d.ts) – Convert a string literal to kebab-case (`foo-bar`).
- [`KebabCasedProperties`](ts41/kebab-cased-properties.d.ts) – Convert a object properties to kebab-case recursively (`foo-bar`).
- [`KebabCasedPropertiesDeep`](ts41/kebab-cased-properties-deep.d.ts) – Convert object properties to kebab-case (`foo-bar`).
- [`PascalCase`](ts41/pascal-case.d.ts) – Converts a string literal to pascal-case (`FooBar`)
- [`PascalCasedProperties`](ts41/pascal-cased-properties.d.ts) – Converts object properties to pascal-case (`FooBar`)
- [`PascalCasedPropertiesDeep`](ts41/pascal-cased-properties-deep.d.ts) – Converts object properties to pascal-case (`FooBar`)
- [`SnakeCase`](ts41/snake-case.d.ts) – Convert a string literal to snake-case (`foo_bar`).
- [`SnakeCasedProperties`](ts41/snake-cased-properties-deep.d.ts) – Convert object properties to snake-case (`foo_bar`).
- [`SnakeCasedPropertiesDeep`](ts41/snake-cased-properties-deep.d.ts) – Convert object properties to snake-case recursively (`foo_bar`).
- [`ScreamingSnakeCase`](ts41/screaming-snake-case.d.ts) - Convert a string literal to screaming-snake-case (`FOO_BAR`).
- [`DelimiterCase`](ts41/delimiter-case.d.ts) – Convert a string literal to a custom string delimiter casing.
- [`DelimiterCasedProperties`](ts41/delimiter-cased-properties.d.ts) – Convert object properties to a custom string delimiter casing.
- [`DelimiterCasedPropertiesDeep`](ts41/delimiter-cased-properties-deep.d.ts) – Convert object properties to a custom string delimiter casing recursively.
- [`Split`](ts41/split.d.ts) - Represents an array of strings split using a given character or character set.
- [`Trim`](ts41/trim.d.ts) - Remove leading and trailing spaces from a string.
- [`Get`](ts41/get.d.ts) - Get a deeply-nested property from an object using a key path, like [Lodash's `.get()`](https://lodash.com/docs/latest#get) function.
- [`LastArrayElement`](ts41/last-array-element.d.ts) - Extracts the type of the last element of an array.

### Miscellaneous

- [`PackageJson`](source/package-json.d.ts) - Type for [npm's `package.json` file](https://docs.npmjs.com/creating-a-package-json-file).
- [`TsConfigJson`](source/tsconfig-json.d.ts) - Type for [TypeScript's `tsconfig.json` file](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) (TypeScript 4.4).

## Declined types

*If we decline a type addition, we will make sure to document the better solution here.*

- [`Diff` and `Spread`](https://github.com/sindresorhus/type-fest/pull/7) - The PR author didn't provide any real-world use-cases and the PR went stale. If you think this type is useful, provide some real-world use-cases and we might reconsider.
- [`Dictionary`](https://github.com/sindresorhus/type-fest/issues/33) - You only save a few characters (`Dictionary<number>` vs `Record<string, number>`) from [`Record`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1429-L1434), which is more flexible and well-known. Also, you shouldn't use an object as a dictionary. We have `Map` in JavaScript now.
- [`ExtractProperties` and `ExtractMethods`](https://github.com/sindresorhus/type-fest/pull/4) - The types violate the single responsibility principle. Instead, refine your types into more granular type hierarchies.

## Tips

### Related

- [typed-query-selector](https://github.com/g-plane/typed-query-selector) - Enhances `document.querySelector` and `document.querySelectorAll` with a template literal type that matches element types returned from an HTML element query selector.

### Built-in types

There are many advanced types most users don't know about.

- [`Partial<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1401-L1406) - Make all properties in `T` optional.
	<details>
	<summary>
			Example
	</summary>

	[Playground](https://www.typescriptlang.org/play/#code/JYOwLgpgTgZghgYwgAgHIHsAmEDC6QzADmyA3gLABQyycADnanALYQBcyAzmFKEQNxUaddFDAcQAV2YAjaIMoBfKlQQAbOJ05osEAIIMAQpOBrsUMkOR1eANziRkCfISKSoD4Pg4ZseAsTIALyW1DS0DEysHADkvvoMMQA0VsKi4sgAzAAMuVaKClY2wPaOknSYDrguADwA0sgQAB6QIJjaANYQAJ7oMDp+LsQAfAAUXd0cdUnI9mo+uv6uANp1ALoAlKHhyGAAFsCcAHTOAW4eYF4gyxNrwbNwago0ypRWp66jH8QcAApwYmAjxq8SWIy2FDCNDA3ToKFBQyIdR69wmfQG1TOhShyBgomQX3w3GQE2Q6IA8jIAFYQBBgI4TTiEs5bTQYsFInrLTbbHZOIlgZDlSqQABqj0kKBC3yINx6a2xfOQwH6o2FVXFaklwSCIUkbQghBAEEwENSfNOlykEGefNe5uhB2O6sgS3GPRmLogmslG1tLxUOKgEDA7hAuydtteryAA)

	```ts
	interface NodeConfig {
			appName: string;
			port: number;
	}

	class NodeAppBuilder {
			private configuration: NodeConfig = {
					appName: 'NodeApp',
					port: 3000
			};

			private updateConfig<Key extends keyof NodeConfig>(key: Key, value: NodeConfig[Key]) {
					this.configuration[key] = value;
			}

			config(config: Partial<NodeConfig>) {
					type NodeConfigKey = keyof NodeConfig;

					for (const key of Object.keys(config) as NodeConfigKey[]) {
							const updateValue = config[key];

							if (updateValue === undefined) {
									continue;
							}

							this.updateConfig(key, updateValue);
					}

					return this;
			}
	}

	// `Partial<NodeConfig>`` allows us to provide only a part of the
	// NodeConfig interface.
	new NodeAppBuilder().config({appName: 'ToDoApp'});
	```
	</details>

- [`Required<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1408-L1413) - Make all properties in `T` required.
	<details>
	<summary>
			Example
	</summary>

	[Playground](https://typescript-play.js.org/?target=6#code/AQ4SwOwFwUwJwGYEMDGNgGED21VQGJZwC2wA3gFCjXAzFJgA2A-AFzADOUckA5gNxUaIYjA4ckvGG07c+g6gF8KQkAgCuEFFDA5O6gEbEwUbLm2ESwABQIixACJIoSdgCUYAR3Vg4MACYAPGYuFvYAfACU5Ko0APRxwADKMBD+wFAAFuh2Vv7OSBlYGdmc8ABu8LHKsRyGxqY4oQT21pTCIHQMjOwA5DAAHgACxAAOjDAAdChYxL0ANLHUouKSMH0AEmAAhJhY6ozpAJ77GTCMjMCiV0ToSAb7UJPPC9WRgrEJwAAqR6MwSRQPFGUFocDgRHYxnEfGAowh-zgUCOwF6KwkUl6tXqJhCeEsxDaS1AXSYfUGI3GUxmc0WSneQA)

	```ts
	interface ContactForm {
			email?: string;
			message?: string;
	}

	function submitContactForm(formData: Required<ContactForm>) {
			// Send the form data to the server.
	}

	submitContactForm({
			email: 'ex@mple.com',
			message: 'Hi! Could you tell me more about…',
	});

	// TypeScript error: missing property 'message'
	submitContactForm({
			email: 'ex@mple.com',
	});
	```
	</details>

- [`Readonly<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1415-L1420) - Make all properties in `T` readonly.
	<details>
	<summary>
			Example
	</summary>

	[Playground](https://typescript-play.js.org/?target=6#code/AQ4UwOwVwW2AZA9gc3mAbmANsA3gKFCOAHkAzMgGkOJABEwAjKZa2kAUQCcvEu32AMQCGAF2FYBIAL4BufDRABLCKLBcywgMZgEKZOoDCiCGSXI8i4hGEwwALmABnUVxXJ57YFgzZHSVF8sT1BpBSItLGEnJz1kAy5LLy0TM2RHACUwYQATEywATwAeAITjU3MAPnkrCJMXLigtUT4AClxgGztKbyDgaX99I1TzAEokr1BRAAslJwA6FIqLAF48TtswHp9MHDla9hJGACswZvmyLjAwAC8wVpm5xZHkUZDaMKIwqyWXYCW0oN4sNlsA1h0ug5gAByACyBQAggAHJHQ7ZBIFoXbzBjMCz7OoQP5YIaJNYQMAAdziCVaALGNSIAHomcAACoFJFgADKWjcSNEwG4vC4ji0wggEEQguiTnMEGALWAV1yAFp8gVgEjeFyuKICvMrCTgVxnst5jtsGC4ljsPNhXxGaAWcAAOq6YRXYDCRg+RWIcA5JSC+kWdCepQ+v3RYCU3RInzRMCGwlpC19NYBW1Ye08R1AA)

	```ts
	enum LogLevel {
			Off,
			Debug,
			Error,
			Fatal
	};

	interface LoggerConfig {
			name: string;
			level: LogLevel;
	}

	class Logger {
			config: Readonly<LoggerConfig>;

			constructor({name, level}: LoggerConfig) {
					this.config = {name, level};
					Object.freeze(this.config);
			}
	}

	const config: LoggerConfig = {
		name: 'MyApp',
		level: LogLevel.Debug
	};

	const logger = new Logger(config);

	// TypeScript Error: cannot assign to read-only property.
	logger.config.level = LogLevel.Error;

	// We are able to edit config variable as we please.
	config.level = LogLevel.Error;
	```
	</details>

- [`Pick<T, K>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1422-L1427) - From `T`, pick a set of properties whose keys are in the union `K`.
	<details>
	<summary>
			Example
	</summary>

	[Playground](https://typescript-play.js.org/?target=6#code/AQ4SwOwFwUwJwGYEMDGNgEE5TCgNugN4BQoZwOUBAXMAM5RyQDmA3KeSFABYCuAtgCMISMHloMmENh04oA9tBjQJjFuzIBfYrOAB6PcADCcGElh1gEGAHcKATwAO6ebyjB5CTNlwFwSxFR0BX5HeToYABNgBDh5fm8cfBg6AHIKG3ldA2BHOOcfFNpUygJ0pAhokr4hETFUgDpswywkggAFUwA3MFtgAF5gQgowKhhVKTYKGuFRcXo1aVZgbTIoJ3RW3xhOmB6+wfbcAGsAHi3kgBpgEtGy4AAfG54BWfqAPnZm4AAlZUj4MAkMA8GAGB4vEgfMlLLw6CwPBA8PYRmMgZVgAC6CgmI4cIommQELwICh8RBgKZKvALh1ur0bHQABR5PYMui0Wk7em2ADaAF0AJS0AASABUALIAGQAogR+Mp3CROCAFBBwVC2ikBpj5CgBIqGjizLA5TAFdAmalImAuqlBRoVQh5HBgEy1eDWfs7J5cjzGYKhroVfpDEhHM4MV6GRR5NN0JrtnRg6BVirTFBeHAKYmYY6QNpdB73LmCJZBlSAXAubtvczeSmQMNSuMbmKNgBlHFgPEUNwusBIPAAQlS1xetTmxT0SDoESgdD0C4aACtHMwxytLrohawgA)

	```ts
	interface Article {
			title: string;
			thumbnail: string;
			content: string;
	}

	// Creates new type out of the `Article` interface composed
	// from the Articles' two properties: `title` and `thumbnail`.
	// `ArticlePreview = {title: string; thumbnail: string}`
	type ArticlePreview = Pick<Article, 'title' | 'thumbnail'>;

	// Render a list of articles using only title and description.
	function renderArticlePreviews(previews: ArticlePreview[]): HTMLElement {
			const articles = document.createElement('div');

			for (const preview of previews) {
					// Append preview to the articles.
			}

			return articles;
	}

	const articles = renderArticlePreviews([
			{
				title: 'TypeScript tutorial!',
				thumbnail: '/assets/ts.jpg'
			}
	]);
	```
	</details>

- [`Record<K, T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1429-L1434) - Construct a type with a set of properties `K` of type `T`.
	<details>
	<summary>
			Example
	</summary>

	[Playground](https://typescript-play.js.org/?target=6#code/AQ4ejYAUHsGcCWAXBMB2dgwGbAKYC2ADgDYwCeeemCaWArgE7ADGMxAhmuQHQBQoYEnJE8wALKEARnkaxEKdMAC8wAOS0kstGuAAfdQBM8ANzxlRjXQbVaWACwC0JPB0NqA3HwGgIwAJJoWozYHCxixnAsjAhStADmwESMMJYo1Fi4HMCIaPEu+MRklHj8gpqyoeHAAKJFFFTAAN4+giDYCIxwSAByHAR4AFw5SDF5Xm2gJBzdfQPD3WPxE5PAlBxdAPLYNQAelgh4aOHDaPQEMowrIAC+3oJ+AMKMrlrAXFhSAFZ4LEhC9g4-0BmA4JBISXgiCkBQABpILrJ5MhUGhYcATGD6Bk4Hh-jNgABrPDkOBlXyQAAq9ngYmJpOAAHcEOCRjAXqwYODfoo6DhakUSph+Uh7GI4P0xER4Cj0OSQGwMP8tP1hgAlX7swwAHgRl2RvIANALSA08ABtAC6AD4VM1Wm0Kow0MMrYaHYJjGYLLJXZb3at1HYnC43Go-QHQDcvA6-JsmEJXARgCDgMYWAhjIYhDAU+YiMAAFIwex0ZmilMITCGF79TLAGRsAgJYAAZRwSEZGzEABFTOZUrJ5Yn+jwnWgeER6HB7AAKJrADpdXqS4ZqYultTG6azVfqHswPBbtauLY7fayQ7HIbAAAMwBuAEoYw9IBq2Ixs9h2eFMOQYPQObALQKJgggABeYhghCIpikkKRpOQRIknAsZUiIeCttECBEP8NSMCkjDDAARMGziuIYxHwYOjDCMBmDNnAuTxA6irdCOBB1Lh5Dqpqn66tISIykawBnOCtqqC0gbjqc9DgpGkxegOliyfJDrRkAA)

	```ts
	// Positions of employees in our company.
	type MemberPosition = 'intern' | 'developer' | 'tech-lead';

	// Interface describing properties of a single employee.
	interface Employee {
			firstName: string;
			lastName: string;
			yearsOfExperience: number;
	}

	// Create an object that has all possible `MemberPosition` values set as keys.
	// Those keys will store a collection of Employees of the same position.
	const team: Record<MemberPosition, Employee[]> = {
			intern: [],
			developer: [],
			'tech-lead': [],
	};

	// Our team has decided to help John with his dream of becoming Software Developer.
	team.intern.push({
		firstName: 'John',
		lastName: 'Doe',
		yearsOfExperience: 0
	});

	// `Record` forces you to initialize all of the property keys.
	// TypeScript Error: "tech-lead" property is missing
	const teamEmpty: Record<MemberPosition, null> = {
			intern: null,
			developer: null,
	};
	```
	</details>

- [`Exclude<T, U>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1436-L1439) - Exclude from `T` those types that are assignable to `U`.
	<details>
	<summary>
			Example
	</summary>

	[Playground](https://typescript-play.js.org/?target=6#code/JYOwLgpgTgZghgYwgAgMrQG7QMIHsQzADmyA3gFDLIAOuUYAXMiAK4A2byAPsgM5hRQJHqwC2AI2gBucgF9y5MAE9qKAEoQAjiwj8AEnBAATNtGQBeZAAooWphu26wAGmS3e93bRC8IASgsAPmRDJRlyAHoI5ABRAA8ENhYjFFYOZGVVZBgoXFFkAAM0zh5+QRBhZhYJaAKAOkjogEkQZAQ4X2QAdwALCFbaemRgXmQtFjhOMFwq9K6ULuB0lk6U+HYwZAxJnQaYFhAEMGB8ZCIIMAAFOjAANR2IK0HGWISklIAedCgsKDwCYgAbQA5M9gQBdVzFQJ+JhiSRQMiUYYwayZCC4VHPCzmSzAspCYEBWxgFhQAZwKC+FpgJ43VwARgADH4ZFQSWSBjcZPJyPtDsdTvxKWBvr8rD1DCZoJ5HPopaYoK4EPhCEQmGKcKriLCtrhgEYkVQVT5Nr4fmZLLZtMBbFZgT0wGBqES6ghbHBIJqoBKFdBWQpjfh+DQbhY2tqiHVsbjLMVkAB+ZAAZiZaeQTHOVxu9ySjxNaujNwDVHNvzqbBGkBAdPoAfkQA)

	```ts
	interface ServerConfig {
		port: null | string | number;
	}

	type RequestHandler = (request: Request, response: Response) => void;

	// Exclude `null` type from `null | string | number`.
	// In case the port is equal to `null`, we will use default value.
	function getPortValue(port: Exclude<ServerConfig['port'], null>): number {
		if (typeof port === 'string') {
			return parseInt(port, 10);
		}

		return port;
	}

	function startServer(handler: RequestHandler, config: ServerConfig): void {
		const server = require('http').createServer(handler);

		const port = config.port === null ? 3000 : getPortValue(config.port);
		server.listen(port);
	}
	```
	</details>

- [`Extract<T, U>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1441-L1444) - Extract from `T` those types that are assignable to `U`.
	<details>
	<summary>
			Example
	</summary>

	[Playground](https://typescript-play.js.org/?target=6#code/CYUwxgNghgTiAEAzArgOzAFwJYHtXzSwEdkQBJYACgEoAueVZAWwCMQYBuAKDDwGcM8MgBF4AXngBlAJ6scESgHIRi6ty5ZUGdoihgEABXZ888AN5d48ANoiAuvUat23K6ihMQ9ATE0BzV3goPy8GZjZOLgBfLi4Aejj4AEEICBwAdz54MAALKFQQ+BxEeAAHY1NgKAwoIKy0grr4DByEUpgccpgMaXgAaxBerCzi+B9-ZulygDouFHRsU1z8kKMYE1RhaqgAHkt4AHkWACt4EAAPbVRgLLWNgBp9gGlBs8uQa6yAUUuYPQwdgNpKM7nh7mMML4CgA+R5WABqUAgpDeVxuhxO1he0jsXGh8EoOBO9COx3BQPo2PBADckaR6IjkSA6PBqTgsMBzPsicdrEC7OJWXSQNwYvFEgAVTS9JLXODpeDpKBZFg4GCoWa8VACIJykAKiQWKy2YQOAioYikCg0OEMDyhRSy4DyxS24KhAAMjyi6gS8AAwjh5OD0iBFHAkJoEOksC1mnkMJq8gUQKDNttKPlnfrwYp3J5XfBHXqoKpfYkAOI4ansTxaeDADmoRSCCBYAbxhC6TDx6rwYHIRX5bScjA4bLJwoDmDwDkfbA9JMrVMVdM1TN69LgkTgwgkchUahqIA)

	```ts
	declare function uniqueId(): number;

	const ID = Symbol('ID');

	interface Person {
		[ID]: number;
		name: string;
		age: number;
	}

	// Allows changing the person data as long as the property key is of string type.
	function changePersonData<
		Obj extends Person,
		Key extends Extract<keyof Person, string>,
		Value extends Obj[Key]
	> (obj: Obj, key: Key, value: Value): void {
		obj[key] = value;
	}

	// Tiny Andrew was born.
	const andrew = {
		[ID]: uniqueId(),
		name: 'Andrew',
		age: 0,
	};

	// Cool, we're fine with that.
	changePersonData(andrew, 'name', 'Pony');

	// Goverment didn't like the fact that you wanted to change your identity.
	changePersonData(andrew, ID, uniqueId());
	```
	</details>

- [`NonNullable<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1446-L1449) - Exclude `null` and `undefined` from `T`.
	<details>
	<summary>
			Example
	</summary>
	Works with <code>strictNullChecks</code> set to <code>true</code>. (Read more <a href="https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-0.html">here</a>)

	[Playground](https://typescript-play.js.org/?target=6#code/C4TwDgpgBACg9gJ2AOQK4FsBGEFQLxQDOwCAlgHYDmUAPlORtrnQwDasDcAUFwPQBU-WAEMkUOADMowqAGNWwwoSgATCBIqlgpOOSjAAFsOBRSy1IQgr9cKJlSlW1mZYQA3HFH68u8xcoBlHA8EACEHJ08Aby4oKDBUTFZSWXjEFEYcAEIALihkXTR2YSSIAB54JDQsHAA+blj4xOTUsHSACkMzPKD3HHDHNQQAGjSkPMqMmoQASh7g-oihqBi4uNIpdraxPAI2VhmVxrX9AzMAOm2ppnwoAA4ABifuE4BfKAhWSyOTuK7CS7pao3AhXF5rV48E4ICDAVAIPT-cGQyG+XTEIgLMJLTx7CAAdygvRCA0iCHaMwarhJOIQjUBSHaACJHk8mYdeLwxtdcVAAOSsh58+lXdr7Dlcq7A3n3J4PEUdADMcspUE53OluAIUGVTx46oAKuAIAFZGQwCYAKIIBCILjUxaDHAMnla+iodjcIA)

	```ts
	type PortNumber = string | number | null;

	/** Part of a class definition that is used to build a server */
	class ServerBuilder {
			portNumber!: NonNullable<PortNumber>;

			port(this: ServerBuilder, port: PortNumber): ServerBuilder {
					if (port == null) {
							this.portNumber = 8000;
					} else {
							this.portNumber = port;
					}

					return this;
			}
	}

	const serverBuilder = new ServerBuilder();

	serverBuilder
			.port('8000')   // portNumber = '8000'
			.port(null)     // portNumber =  8000
			.port(3000);    // portNumber =  3000

	// TypeScript error
	serverBuilder.portNumber = null;
	```
	</details>

- [`Parameters<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1451-L1454) - Obtain the parameters of a function type in a tuple.
	<details>
	<summary>
			Example
	</summary>

	[Playground](https://typescript-play.js.org/?target=6#code/GYVwdgxgLglg9mABAZwBYmMANgUwBQxgAOIUAXIgIZgCeA2gLoCUFAbnDACaIDeAUIkQB6IYgCypSlBxUATrMo1ECsJzgBbLEoipqAc0J7EMKMgDkiHLnU4wp46pwAPHMgB0fAL58+oSLARECEosLAA5ABUYG2QAHgAxJGdpVWREPDdMylk9ZApqemZEAF4APipacrw-CApEgBogkKwAYThwckQwEHUAIxxZJl4BYVEImiIZKF0oZRwiWVdbeygJmThgOYgcGFYcbhqApCJsyhtpWXcR1cnEePBoeDAABVPzgbTixFeFd8uEsClADcIxGiygIFkSEOT3SmTc2VydQeRx+ZxwF2QQ34gkEwDgsnSuFmMBKiAADEDjIhYk1Qm0OlSYABqZnYka4xA1DJZHJYkGc7yCbyeRA+CAIZCzNAYbA4CIAdxg2zJwVCkWirjwMswuEaACYmCCgA)

	```ts
	function shuffle(input: any[]): void {
		// Mutate array randomly changing its' elements indexes.
	}

	function callNTimes<Fn extends (...args: any[]) => any> (func: Fn, callCount: number) {
		// Type that represents the type of the received function parameters.
		type FunctionParameters = Parameters<Fn>;

		return function (...args: FunctionParameters) {
			for (let i = 0; i < callCount; i++) {
				func(...args);
			}
		}
	}

	const shuffleTwice = callNTimes(shuffle, 2);
	```
	</details>

- [`ConstructorParameters<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1456-L1459) - Obtain the parameters of a constructor function type in a tuple.
	<details>
	<summary>
			Example
	</summary>

	[Playground](https://typescript-play.js.org/?target=6#code/MYGwhgzhAECCBOAXAlqApgWQPYBM0mgG8AoaaFRENALmgkXmQDsBzAblOmCycTV4D8teo1YdO3JiICuwRFngAKClWENmLAJRFOZRAAtkEAHQq00ALzlklNBzIBfYk+KhIMAJJTEYJsDQAwmDA+mgAPAAq0GgAHnxMODCKTGgA7tCKxllg8CwQtL4AngDaALraFgB80EWa1SRkAA6MAG5gfNAB4FABPDJyCrQR9tDNyG0dwMGhtBhgjWEiGgA00F70vv4RhY3hEZXVVinpc42KmuJkkv3y8Bly8EPaDWTkhiZd7r3e8LK3llwGCMXGQWGhEOsfH5zJlsrl8p0+gw-goAAo5MAAW3BaHgEEilU0tEhmzQ212BJ0ry4SOg+kg+gBBiMximIGA0nAfAQLGk2N4EAAEgzYcYcnkLsRdDTvNEYkYUKwSdCme9WdM0MYwYhFPSIPpJdTkAAzDKxBUaZX+aAAQgsVmkCTQxuYaBw2ng4Ok8CYcotSu8pMur09iG9vuObxZnx6SN+AyUWTF8MN0CcZE4Ywm5jZHK5aB5fP4iCFIqT4oRRTKRLo6lYVNeAHpG50wOzOe1zHr9NLQ+HoABybsD4HOKXXRA1JCoKhBELmI5pNaB6Fz0KKBAodDYPAgSUTmqYsAALx4m5nC6nW9nGq14KtaEUA9gR9PvuNCjQ9BgACNvcwNBtAcLiAA)

	```ts
	class ArticleModel {
		title: string;
		content?: string;

		constructor(title: string) {
			this.title = title;
		}
	}

	class InstanceCache<T extends (new (...args: any[]) => any)> {
		private ClassConstructor: T;
		private cache: Map<string, InstanceType<T>> = new Map();

		constructor (ctr: T) {
			this.ClassConstructor = ctr;
		}

		getInstance (...args: ConstructorParameters<T>): InstanceType<T> {
			const hash = this.calculateArgumentsHash(...args);

			const existingInstance = this.cache.get(hash);
			if (existingInstance !== undefined) {
				return existingInstance;
			}

			return new this.ClassConstructor(...args);
		}

		private calculateArgumentsHash(...args: any[]): string {
			// Calculate hash.
			return 'hash';
		}
	}

	const articleCache = new InstanceCache(ArticleModel);
	const amazonArticle = articleCache.getInstance('Amazon forests burining!');
	```
	</details>

- [`ReturnType<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1461-L1464) – Obtain the return type of a function type.
	<details>
	<summary>
			Example
	</summary>

	[Playground](https://typescript-play.js.org/?target=6#code/MYGwhgzhAECSAmICmBlJAnAbgS2E6A3gFDTTwD2AcuQC4AW2AdgOYAUAlAFzSbnbyEAvkWFFQkGJSQB3GMVI1sNZNwg10TZgG4S0YOUY0kh1es07d+xmvQBXYDXLpWi5UlMaWAGj0GjJ6BtNdkJdBQYIADpXZGgAXmgYpB1ScOwoq38aeN9DYxoU6GFRKzVoJjUwRjwAYXJbPPRuAFkwAAcAHgAxBodsAx9GWwBbACMMAD4cxhloVraOCyYjdAAzMDxoOut1e0d0UNIZ6WhWSPOwdGYIbiqATwBtAF0uaHudUQB6ACpv6ABpJBINqJdAbADW0Do5BOw3u5R2VTwMHIq2gAANtjZ0bkbHsnFCwJh8ONjHp0EgwEZ4JFoN9PkRVr1FAZoMwkDRYIjqkgOrosepoEgAB7+eAwAV2BxOLy6ACCVxgIrFEoMeOl6AACpcwMMORgIB1JRMiBNWKVdhruJKfOdIpdrtwFddXlzKjyACp3Nq842HaDIbL6BrZBIVGhIpB1EMYSLsmjmtWW-YhAA+qegAAYLKQLQj3ZsEsdccmnGcLor2Dn8xGedHGpEIBzEzspfsfMHDNAANTQACMVaIljV5GQkRA5DYmIpVKQAgAJARO9le33BDXIyi0YuLW2nJFGLqkOvxFB0YPdBSaLZ0IwNzyPkO8-xkGgsLh8Al427a3hWAhXwwHA8EHT5PmgAB1bAQBAANJ24adKWpft72RaBUTgRBUCAj89HAM8xCTaBjggABRQx0DuHJv25P9dCkWRZVIAAiBjoFImpmjlFBgA0NpsjadByDacgIDAEAIAAQmYpjoGYgAZSBsmGPw6DtZiiFA8CoJguDmAQmoZ2QvtUKQLdoAYmBTwgdEiCAA)

	```ts
	/** Provides every element of the iterable `iter` into the `callback` function and stores the results in an array. */
	function mapIter<
			Elem,
			Func extends (elem: Elem) => any,
			Ret extends ReturnType<Func>
	>(iter: Iterable<Elem>, callback: Func): Ret[] {
			const mapped: Ret[] = [];

			for (const elem of iter) {
					mapped.push(callback(elem));
			}

			return mapped;
	}

	const setObject: Set<string> = new Set();
	const mapObject: Map<number, string> = new Map();

	mapIter(setObject, (value: string) => value.indexOf('Foo')); // number[]

	mapIter(mapObject, ([key, value]: [number, string]) => {
			return key % 2 === 0 ? value : 'Odd';
	}); // string[]
	```
	</details>

- [`InstanceType<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1466-L1469) – Obtain the instance type of a constructor function type.
	<details>
	<summary>
			Example
	</summary>

	[Playground](https://typescript-play.js.org/?target=6#code/MYGwhgzhAECSAmICmBlJAnAbgS2E6A3gFDTTwD2AcuQC4AW2AdgOYAUAlAFzSbnbyEAvkWFFQkGJSQB3GMVI1sNZNwg10TZgG4S0YOUY0kh1es07d+xmvQBXYDXLpWi5UlMaWAGj0GjJ6BtNdkJdBQYIADpXZGgAXmgYpB1ScOwoq38aeN9DYxoU6GFRKzVoJjUwRjwAYXJbPPRuAFkwAAcAHgAxBodsAx9GWwBbACMMAD4cxhloVraOCyYjdAAzMDxoOut1e0d0UNIZ6WhWSPOwdGYIbiqATwBtAF0uaHudUQB6ACpv6ABpJBINqJdAbADW0Do5BOw3u5R2VTwMHIq2gAANtjZ0bkbHsnFCwJh8ONjHp0EgwEZ4JFoN9PkRVr1FAZoMwkDRYIjqkgOrosepoEgAB7+eAwAV2BxOLy6ACCVxgIrFEoMeOl6AACpcwMMORgIB1JRMiBNWKVdhruJKfOdIpdrtwFddXlzKjyACp3Nq842HaDIbL6BrZBIVGhIpB1EMYSLsmjmtWW-YhAA+qegAAYLKQLQj3ZsEsdccmnGcLor2Dn8xGedHGpEIBzEzspfsfMHDNAANTQACMVaIljV5GQkRA5DYmIpVKQAgAJARO9le33BDXIyi0YuLW2nJFGLqkOvxFB0YPdBSaLZ0IwNzyPkO8-xkGgsLh8Al427a3hWAhXwwHA8EHT5PmgAB1bAQBAANJ24adKWpft72RaBUTgRBUCAj89HAM8xCTaBjggABRQx0DuHJv25P9dCkWRZVIAAiBjoFImpmjlFBgA0NpsjadByDacgIDAEAIAAQmYpjoGYgAZSBsmGPw6DtZiiFA8CoJguDmAQmoZ2QvtUKQLdoAYmBTwgdEiCAA)

	```ts
	class IdleService {
			doNothing (): void {}
	}

	class News {
			title: string;
			content: string;

			constructor(title: string, content: string) {
					this.title = title;
					this.content = content;
			}
	}

	const instanceCounter: Map<Function, number> = new Map();

	interface Constructor {
			new(...args: any[]): any;
	}

	// Keep track how many instances of `Constr` constructor have been created.
	function getInstance<
			Constr extends Constructor,
			Args extends ConstructorParameters<Constr>
	>(constructor: Constr, ...args: Args): InstanceType<Constr> {
			let count = instanceCounter.get(constructor) || 0;

			const instance = new constructor(...args);

			instanceCounter.set(constructor, count + 1);

			console.log(`Created ${count + 1} instances of ${Constr.name} class`);

			return instance;
	}


	const idleService = getInstance(IdleService);
	// Will log: `Created 1 instances of IdleService class`
	const newsEntry = getInstance(News, 'New ECMAScript proposals!', 'Last month...');
	// Will log: `Created 1 instances of News class`
	```
	</details>

- [`Omit<T, K>`](https://github.com/microsoft/TypeScript/blob/71af02f7459dc812e85ac31365bfe23daf14b4e4/src/lib/es5.d.ts#L1446) – Constructs a type by picking all properties from T and then removing K.
	<details>
	<summary>
			Example
	</summary>

	[Playground](https://typescript-play.js.org/?target=6#code/JYOwLgpgTgZghgYwgAgIImAWzgG2QbwChlks4BzCAVShwC5kBnMKUcgbmKYAcIFgIjBs1YgOXMpSFMWbANoBdTiW5woFddwAW0kfKWEAvoUIB6U8gDCUCHEiNkICAHdkYAJ69kz4GC3JcPG4oAHteKDABBxCYNAxsPFBIWEQUCAAPJG4wZABySUFcgJAAEzMLXNV1ck0dIuCw6EjBADpy5AB1FAQ4EGQAV0YUP2AHDy8wEOQbUugmBLwtEIA3OcmQnEjuZBgQqE7gAGtgZAhwKHdkHFGwNvGUdDIcAGUliIBJEF3kAF5kAHlML4ADyPBIAGjyBUYRQAPnkqho4NoYQA+TiEGD9EAISIhPozErQMG4AASK2gn2+AApek9pCSXm8wFSQooAJQMUkAFQAsgAZACiOAgmDOOSIJAQ+OYyGl4DgoDmf2QJRCCH6YvALQQNjsEGFovF1NyJWAy1y7OUyHMyE+yRAuFImG4Iq1YDswHxbRINjA-SgfXlHqVUE4xiAA)

	```ts
	interface Animal {
			imageUrl: string;
			species: string;
			images: string[];
			paragraphs: string[];
	}

	// Creates new type with all properties of the `Animal` interface
	// except 'images' and 'paragraphs' properties. We can use this
	// type to render small hover tooltip for a wiki entry list.
	type AnimalShortInfo = Omit<Animal, 'images' | 'paragraphs'>;

	function renderAnimalHoverInfo (animals: AnimalShortInfo[]): HTMLElement {
			const container =  document.createElement('div');
			// Internal implementation.
			return container;
	}
	```
	</details>

- [`Uppercase<S extends string>`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-1.html#template-literal-types) - Transforms every character in a string into uppercase.
	<details>
	<summary>
		Example
	</summary>

	```ts
	type T = Uppercase<'hello'>;  // 'HELLO'

	type T2 = Uppercase<'foo' | 'bar'>;  // 'FOO' | 'BAR'

	type T3<S extends string> = Uppercase<`aB${S}`>;
	type T4 = T30<'xYz'>;  // 'ABXYZ'

	type T5 = Uppercase<string>;  // string
	type T6 = Uppercase<any>;  // any
	type T7 = Uppercase<never>;  // never
	type T8 = Uppercase<42>;  // Error, type 'number' does not satisfy the constraint 'string'
	```
	</details>

- [`Lowercase<S extends string>`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-1.html#template-literal-types) - Transforms every character in a string into lowercase.
	<details>
	<summary>
		Example
	</summary>

	```ts
	type T = Lowercase<'HELLO'>;  // 'hello'

	type T2 = Lowercase<'FOO' | 'BAR'>;  // 'foo' | 'bar'

	type T3<S extends string> = Lowercase<`aB${S}`>;
	type T4 = T32<'xYz'>;  // 'abxyz'

	type T5 = Lowercase<string>;  // string
	type T6 = Lowercase<any>;  // any
	type T7 = Lowercase<never>;  // never
	type T8 = Lowercase<42>;  // Error, type 'number' does not satisfy the constraint 'string'
	```
	</details>

- [`Capitalize<S extends string>`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-1.html#template-literal-types) - Transforms the first character in a string into uppercase.
	<details>
	<summary>
		Example
	</summary>

	```ts
	type T = Capitalize<'hello'>;  // 'Hello'

	type T2 = Capitalize<'foo' | 'bar'>;  // 'Foo' | 'Bar'

	type T3<S extends string> = Capitalize<`aB${S}`>;
	type T4 = T32<'xYz'>;  // 'ABxYz'

	type T5 = Capitalize<string>;  // string
	type T6 = Capitalize<any>;  // any
	type T7 = Capitalize<never>;  // never
	type T8 = Capitalize<42>;  // Error, type 'number' does not satisfy the constraint 'string'
	```
	</details>

- [`Uncapitalize<S extends string>`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-1.html#template-literal-types) - Transforms the first character in a string into lowercase.
	<details>
	<summary>
		Example
	</summary>

	```ts
	type T = Uncapitalize<'Hello'>;  // 'hello'

	type T2 = Uncapitalize<'Foo' | 'Bar'>;  // 'foo' | 'bar'

	type T3<S extends string> = Uncapitalize<`AB${S}`>;
	type T4 = T30<'xYz'>;  // 'aBxYz'

	type T5 = Uncapitalize<string>;  // string
	type T6 = Uncapitalize<any>;  // any
	type T7 = Uncapitalize<never>;  // never
	type T8 = Uncapitalize<42>;  // Error, type 'number' does not satisfy the constraint 'string'
	```
	</details>

You can find some examples in the [TypeScript docs](https://www.typescriptlang.org/docs/handbook/advanced-types.html#predefined-conditional-types).

## Maintainers

- [Sindre Sorhus](https://github.com/sindresorhus)
- [Jarek Radosz](https://github.com/CvX)
- [Dimitri Benin](https://github.com/BendingBender)
- [Pelle Wessman](https://github.com/voxpelli)

## License

(MIT OR CC0-1.0)

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-type-fest?utm_source=npm-type-fest&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

# crypto-random-string

> Generate a [cryptographically strong](https://en.wikipedia.org/wiki/Strong_cryptography) random string

Can be useful for creating an identifier, slug, salt, PIN code, fixture, etc.

## Install

```
$ npm install crypto-random-string
```

## Usage

```js
import cryptoRandomString from 'crypto-random-string';

cryptoRandomString({length: 10});
//=> '2cf05d94db'

cryptoRandomString({length: 10, type: 'base64'});
//=> 'YMiMbaQl6I'

cryptoRandomString({length: 10, type: 'url-safe'});
//=> 'YN-tqc8pOw'

cryptoRandomString({length: 10, type: 'numeric'});
//=> '8314659141'

cryptoRandomString({length: 6, type: 'distinguishable'});
//=> 'CDEHKM'

cryptoRandomString({length: 10, type: 'ascii-printable'});
//=> '`#Rt8$IK>B'

cryptoRandomString({length: 10, type: 'alphanumeric'});
//=> 'DMuKL8YtE7'

cryptoRandomString({length: 10, characters: 'abc'});
//=> 'abaaccabac'
```

## API

### cryptoRandomString(options)

Returns a randomized string. [Hex](https://en.wikipedia.org/wiki/Hexadecimal) by default.

### cryptoRandomString.async(options)

Returns a promise which resolves to a randomized string. [Hex](https://en.wikipedia.org/wiki/Hexadecimal) by default.

For most use-cases, there's really no good reason to use this async version. From the Node.js docs:

> The `crypto.randomBytes()` method will not complete until there is sufficient entropy available. This should normally never take longer than a few milliseconds. The only time when generating the random bytes may conceivably block for a longer period of time is right after boot, when the whole system is still low on entropy.

In general, anything async comes with some overhead on it's own.

#### options

Type: `object`

##### length

*Required*\
Type: `number`

Length of the returned string.

##### type

Type: `string`\
Default: `'hex'`\
Values: `'hex' | 'base64' | 'url-safe' | 'numeric' | 'distinguishable' | 'ascii-printable' | 'alphanumeric'`

Use only characters from a predefined set of allowed characters.

Cannot be set at the same time as the `characters` option.

The `distinguishable` set contains only uppercase characters that are not easily confused: `CDEHKMPRTUWXY012458`. It can be useful if you need to print out a short string that you'd like users to read and type back in with minimal errors. For example, reading a code off of a screen that needs to be typed into a phone to connect two devices.

The `ascii-printable` set contains all [printable ASCII characters](https://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters): ``!"#$%&\'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`abcdefghijklmnopqrstuvwxyz{|}~`` Useful for generating passwords where all possible ASCII characters should be used.

The `alphanumeric` set contains uppercase letters, lowercase letters, and digits: `ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789`. Useful for generating [nonce](https://developer.mozilla.org/en-US/docs/Web/API/HTMLOrForeignElement/nonce) values.

##### characters

Type: `string`\
Minimum length: `1`\
Maximum length: `65536`

Use only characters from a custom set of allowed characters.

Cannot be set at the same time as the `type` option.

## Related

- [random-int](https://github.com/sindresorhus/random-int) - Generate a random integer
- [random-float](https://github.com/sindresorhus/random-float) - Generate a random float
- [random-item](https://github.com/sindresorhus/random-item) - Get a random item from an array
- [random-boolean](https://github.com/arthurvr/random-boolean) - Get a random boolean
- [random-obj-key](https://github.com/sindresorhus/random-obj-key) - Get a random key from an object
- [random-obj-prop](https://github.com/sindresorhus/random-obj-prop) - Get a random property from an object
- [unique-random](https://github.com/sindresorhus/unique-random) - Generate random numbers that are consecutively unique

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-crypto-random-string?utm_source=npm-crypto-random-string&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

# Changes to CSS Blank Pseudo

### 7.0.1

_October 23, 2024_

- Updated: `postcss-selector-parser`

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/css-blank-pseudo/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Blank Pseudo [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install css-blank-pseudo --save-dev`

[PostCSS Blank Pseudo] lets you style form elements when they are empty, following 
the [Selectors Level 4] specification.

To use this feature you need to do two things :
- add the [PostCSS plugin](#usage) that transforms the selector into a class or attribute
- add the [browser polyfill](#browser) that sets the attribute or class on elements in a browser

```pcss
input:blank {
	background-color: yellow;
}

/* becomes */

input[blank].js-blank-pseudo, .js-blank-pseudo input[blank] {
	background-color: yellow;
}
input:blank {
	background-color: yellow;
}
```

## Usage

Add [PostCSS Blank Pseudo] to your project:

```bash
npm install postcss css-blank-pseudo --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssBlankPseudo = require('css-blank-pseudo');

postcss([
	postcssBlankPseudo(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## Options

### preserve

The `preserve` option determines whether the original notation
is preserved. By default, it is preserved.

```js
postcssBlankPseudo({ preserve: false })
```

```pcss
input:blank {
	background-color: yellow;
}

/* becomes */

input[blank].js-blank-pseudo, .js-blank-pseudo input[blank] {
	background-color: yellow;
}
```

### replaceWith

The `replaceWith` option determines the selector to use when replacing
the `:blank` pseudo. By default is `[blank]`

```js
postcssBlankPseudo({ replaceWith: '.css-blank' })
```

```pcss
input:blank {
	background-color: yellow;
}

/* becomes */

.foo {
	color: blue;
	color: red;
}

.baz {
	color: green;
}
```

Note that changing this option implies that it needs to be passed to the
browser polyfill as well.

### disablePolyfillReadyClass

The `disablePolyfillReadyClass` option determines if selectors are prefixed with an indicator class.
This class is only set on your document if the polyfill loads and is needed.

By default this option is `false`.
Set this to `true` to prevent the class from being added.

```js
postcssBlankPseudo({ disablePolyfillReadyClass: true })
```

```pcss
input:blank {
	background-color: yellow;
}

/* becomes */

input[blank] {
	background-color: yellow;
}
input:blank {
	background-color: yellow;
}
```

## Browser

```js
import cssBlankPseudoInit from 'css-blank-pseudo/browser';

cssBlankPseudoInit();
```

or

```html
<!-- When using a CDN url you will have to manually update the version number -->
<script src="https://unpkg.com/css-blank-pseudo@7.0.1/dist/browser-global.js"></script>
<script>cssBlankPseudoInit()</script>
```

[PostCSS Blank Pseudo] works in all major browsers, including Safari 6+ and
Internet Explorer 9+ without any additional polyfills.

This plugin conditionally uses `MutationObserver` to ensure recently inserted 
inputs get correct styling upon insertion. If you intend to rely on that 
behaviour for browsers that do not support `MutationObserver`, you have two
options:

1. Polyfill `MutationObserver`. As long as it runs before `cssBlankPseudoInit`,
the polyfill will work.
2. If you don't want to polyfill `MutationObserver` you can also manually fire
a `change` event upon insertion so they're automatically inspected by the
polyfill.

### Browser Usage

#### force

The `force` option determines whether the library runs even if the browser 
supports the selector or not. By default, it won't run if the browser does
support the selector.

```js
cssBlankPseudoInit({ force: true });
```

#### replaceWith

Similar to the option for the PostCSS Plugin, `replaceWith` determines the
attribute or class to apply to an element when it's considered to be `:blank`.

```js
cssBlankPseudoInit({ replaceWith: '.css-blank' });
```

This option should be used if it was changed at PostCSS configuration level.
Please note that using a class, leverages `classList` under the hood which 
might  not be supported on some old browsers such as IE9, so you may need 
to polyfill `classList` in those cases.

### Using with Next.js

Given that Next.js imports packages both on the browser and on the server, you need to make sure that the package is only imported on the browser.

As outlined in the [Next.js documentation](https://nextjs.org/docs/advanced-features/dynamic-import#with-external-libraries), you need to load the package with a dynamic import:

```jsx
useEffect(async () => {
	const cssBlankPseudoInit = (await import('css-blank-pseudo/browser')).default;
	cssBlankPseudoInit();
}, []);
```

We recommend you load the polyfill as high up on your Next application as possible, such as your `pages/_app.ts` file.

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#blank-pseudo-class
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/css-blank-pseudo

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Blank Pseudo]: https://github.com/csstools/postcss-plugins/tree/main/plugins/css-blank-pseudo
[Selectors Level 4]: https://www.w3.org/TR/selectors-4/#blank


---

# API Documentation

*Please use only this documented API when working with the parser. Methods
not documented here are subject to change at any point.*

## `parser` function

This is the module's main entry point.

```js
const parser = require('postcss-selector-parser');
```

### `parser([transform], [options])`

Creates a new `processor` instance

```js
const processor = parser();
```

Or, with optional transform function

```js
const transform = selectors => {
    selectors.walkUniversals(selector => {
        selector.remove();
    });
};

const processor = parser(transform)

// Example
const result = processor.processSync('*.class');
// => .class
```

[See processor documentation](#processor)

Arguments:

* `transform (function)`: Provide a function to work with the parsed AST.
* `options (object)`: Provide default options for all calls on the returned `Processor`.

### `parser.attribute([props])`

Creates a new attribute selector.

```js
parser.attribute({attribute: 'href'});
// => [href]
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.className([props])`

Creates a new class selector.

```js
parser.className({value: 'button'});
// => .button
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.combinator([props])`

Creates a new selector combinator.

```js
parser.combinator({value: '+'});
// => +
```

Arguments:

* `props (object)`: The new node's properties.

Notes:
* **Descendant Combinators** The value of descendant combinators created by the
  parser always just a single space (`" "`). For descendant selectors with no
  comments, additional space is now stored in `node.spaces.before`. Depending
  on the location of comments, additional spaces may be stored in
  `node.raws.spaces.before`, `node.raws.spaces.after`, or `node.raws.value`.
* **Named Combinators** Although, nonstandard and unlikely to ever become a standard,
  named combinators like `/deep/` and `/for/` are parsed as combinators. The
  `node.value` is name after being unescaped and normalized as lowercase. The
  original value for the combinator name is stored in `node.raws.value`.


### `parser.comment([props])`

Creates a new comment.

```js
parser.comment({value: '/* Affirmative, Dave. I read you. */'});
// => /* Affirmative, Dave. I read you. */
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.id([props])`

Creates a new id selector.

```js
parser.id({value: 'search'});
// => #search
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.nesting([props])`

Creates a new nesting selector.

```js
parser.nesting();
// => &
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.pseudo([props])`

Creates a new pseudo selector.

```js
parser.pseudo({value: '::before'});
// => ::before
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.root([props])`

Creates a new root node.

```js
parser.root();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.selector([props])`

Creates a new selector node.

```js
parser.selector();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.string([props])`

Creates a new string node.

```js
parser.string();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.tag([props])`

Creates a new tag selector.

```js
parser.tag({value: 'button'});
// => button
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.universal([props])`

Creates a new universal selector.

```js
parser.universal();
// => *
```

Arguments:

* `props (object)`: The new node's properties.

## Node types

### `node.type`

A string representation of the selector type. It can be one of the following;
`attribute`, `class`, `combinator`, `comment`, `id`, `nesting`, `pseudo`,
`root`, `selector`, `string`, `tag`, or `universal`. Note that for convenience,
these constants are exposed on the main `parser` as uppercased keys. So for
example you can get `id` by querying `parser.ID`.

```js
parser.attribute({attribute: 'href'}).type;
// => 'attribute'
```

### `node.parent`

Returns the parent node.

```js
root.nodes[0].parent === root;
```

### `node.toString()`, `String(node)`, or `'' + node`

Returns a string representation of the node.

```js
const id = parser.id({value: 'search'});
console.log(String(id));
// => #search
```

### `node.next()` & `node.prev()`

Returns the next/previous child of the parent node.

```js
const next = id.next();
if (next && next.type !== 'combinator') {
    throw new Error('Qualified IDs are not allowed!');
}
```

### `node.replaceWith(node[,...nodeN])`

Replace a node with another.

```js
const attr = selectors.first.first;
const className = parser.className({value: 'test'});
attr.replaceWith(className);
```

Arguments:

* `node`: The node to substitute the original with.
...
* `nodeN`: The node to substitute the original with.

### `node.remove()`

Removes the node from its parent node.

```js
if (node.type === 'id') {
    node.remove();
}
```

### `node.clone([opts])`

Returns a copy of a node, detached from any parent containers that the
original might have had.

```js
const cloned = node.clone();
```

### `node.isAtPosition(line, column)`

Return a `boolean` indicating whether this node includes the character at the
position of the given line and column. Returns `undefined` if the nodes lack
sufficient source metadata to determine the position.

Arguments:

* `line`: 1-index based line number relative to the start of the selector.
* `column`: 1-index based column number relative to the start of the selector.

### `node.spaces`

Extra whitespaces around the node will be moved into `node.spaces.before` and
`node.spaces.after`. So for example, these spaces will be moved as they have
no semantic meaning:

```css
      h1     ,     h2   {}
```

For descendent selectors, the value is always a single space.

```css
h1        h2 {}
```

Additional whitespace is found in either the `node.spaces.before` and `node.spaces.after` depending on the presence of comments or other whitespace characters. If the actual whitespace does not start or end with a single space, the node's raw value is set to the actual space(s) found in the source.

### `node.source`

An object describing the node's start/end, line/column source position.

Within the following CSS, the `.bar` class node ...

```css
.foo,
  .bar {}
```

... will contain the following `source` object.

```js
source: {
    start: {
        line: 2,
        column: 3
    },
    end: {
        line: 2,
        column: 6
    }
}
```

### `node.sourceIndex`

The zero-based index of the node within the original source string.

Within the following CSS, the `.baz` class node will have a `sourceIndex` of `12`.

```css
.foo, .bar, .baz {}
```

## Container types

The `root`, `selector`, and `pseudo` nodes have some helper methods for working
with their children.

### `container.nodes`

An array of the container's children.

```js
// Input: h1 h2
selectors.at(0).nodes.length   // => 3
selectors.at(0).nodes[0].value // => 'h1'
selectors.at(0).nodes[1].value // => ' '
```

### `container.first` & `container.last`

The first/last child of the container.

```js
selector.first === selector.nodes[0];
selector.last === selector.nodes[selector.nodes.length - 1];
```

### `container.at(index)`

Returns the node at position `index`.

```js
selector.at(0) === selector.first;
selector.at(0) === selector.nodes[0];
```

Arguments:

* `index`: The index of the node to return.

### `container.atPosition(line, column)`

Returns the node at the source position `line` and `column`.

```js
// Input: :not(.foo),\n#foo > :matches(ol, ul)
selector.atPosition(1, 1); // => :not(.foo)
selector.atPosition(2, 1); // => \n#foo
```

Arguments:

* `line`: The line number of the node to return.
* `column`: The column number of the node to return.

### `container.index(node)`

Return the index of the node within its container.

```js
selector.index(selector.nodes[2]) // => 2
```

Arguments:

* `node`: A node within the current container.

### `container.length`

Proxy to the length of the container's nodes.

```js
container.length === container.nodes.length
```

### `container` Array iterators

The container class provides proxies to certain Array methods; these are:

* `container.map === container.nodes.map`
* `container.reduce === container.nodes.reduce`
* `container.every === container.nodes.every`
* `container.some === container.nodes.some`
* `container.filter === container.nodes.filter`
* `container.sort === container.nodes.sort`

Note that these methods only work on a container's immediate children; recursive
iteration is provided by `container.walk`.

### `container.each(callback)`

Iterate the container's immediate children, calling `callback` for each child.
You may return `false` within the callback to break the iteration.

```js
let className;
selectors.each((selector, index) => {
    if (selector.type === 'class') {
        className = selector.value;
        return false;
    }
});
```

Note that unlike `Array#forEach()`, this iterator is safe to use whilst adding
or removing nodes from the container.

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  and `index` arguments.

### `container.walk(callback)`

Like `container#each`, but will also iterate child nodes as long as they are
`container` types.

```js
selectors.walk((selector, index) => {
    // all nodes
});
```

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  and `index` arguments.

This iterator is safe to use whilst mutating `container.nodes`,
like `container#each`.

### `container.walk` proxies

The container class provides proxy methods for iterating over types of nodes,
so that it is easier to write modules that target specific selectors. Those
methods are:

* `container.walkAttributes`
* `container.walkClasses`
* `container.walkCombinators`
* `container.walkComments`
* `container.walkIds`
* `container.walkNesting`
* `container.walkPseudos`
* `container.walkTags`
* `container.walkUniversals`

### `container.split(callback)`

This method allows you to split a group of nodes by returning `true` from
a callback. It returns an array of arrays, where each inner array corresponds
to the groups that you created via the callback.

```js
// (input) => h1 h2>>h3
const list = selectors.first.split(selector => {
    return selector.type === 'combinator';
});

// (node values) => [['h1', ' '], ['h2', '>>'], ['h3']]
```

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  as an argument.

### `container.prepend(node)` & `container.append(node)`

Add a node to the start/end of the container. Note that doing so will set
the parent property of the node to this container.

```js
const id = parser.id({value: 'search'});
selector.append(id);
```

Arguments:

* `node`: The node to add.

### `container.insertBefore(old, new[, ...newNodes])` & `container.insertAfter(old, new[, ...newNodes])`

Add a node before or after an existing node in a container:

```js
selectors.walk(selector => {
    if (selector.type !== 'class') {
        const className = parser.className({value: 'theme-name'});
        selector.parent.insertAfter(selector, className);
    }
});
```

Arguments:

* `old`: The existing node in the container.
* `new`: The new node to add before/after the existing node.

### `container.removeChild(node)`

Remove the node from the container. Note that you can also use
`node.remove()` if you would like to remove just a single node.

```js
selector.length // => 2
selector.remove(id)
selector.length // => 1;
id.parent       // undefined
```

Arguments:

* `node`: The node to remove.

### `container.removeAll()` or `container.empty()`

Remove all children from the container.

```js
selector.removeAll();
selector.length // => 0
```

## Root nodes

A root node represents a comma separated list of selectors. Indeed, all
a root's `toString()` method does is join its selector children with a ','.
Other than this, it has no special functionality and acts like a container.

### `root.trailingComma`

This will be set to `true` if the input has a trailing comma, in order to
support parsing of legacy CSS hacks.

## Selector nodes

A selector node represents a single complex selector. For example, this
selector string `h1 h2 h3, [href] > p`, is represented as two selector nodes.
It has no special functionality of its own.

## Pseudo nodes

A pseudo selector extends a container node; if it has any parameters of its
own (such as `h1:not(h2, h3)`), they will be its children. Note that the pseudo
`value` will always contain the colons preceding the pseudo identifier. This
is so that both `:before` and `::before` are properly represented in the AST.

## Attribute nodes

### `attribute.quoted`

Returns `true` if the attribute's value is wrapped in quotation marks, false if it is not.
Remains `undefined` if there is no attribute value.

```css
[href=foo] /* false */
[href='foo'] /* true */
[href="foo"] /* true */
[href] /* undefined */
```

### `attribute.qualifiedAttribute`

Returns the attribute name qualified with the namespace if one is given.

### `attribute.offsetOf(part)`

 Returns the offset of the attribute part specified relative to the
 start of the node of the output string. This is useful in raising
 error messages about a specific part of the attribute, especially
 in combination with `attribute.sourceIndex`.

 Returns `-1` if the name is invalid or the value doesn't exist in this
 attribute.

 The legal values for `part` are:

 * `"ns"` - alias for "namespace"
 * `"namespace"` - the namespace if it exists.
 * `"attribute"` - the attribute name
 * `"attributeNS"` - the start of the attribute or its namespace
 * `"operator"` - the match operator of the attribute
 * `"value"` - The value (string or identifier)
 * `"insensitive"` - the case insensitivity flag

### `attribute.raws.unquoted`

Returns the unquoted content of the attribute's value.
Remains `undefined` if there is no attribute value.

```css
[href=foo] /* foo */
[href='foo'] /* foo */
[href="foo"] /* foo */
[href] /* undefined */
```

### `attribute.spaces`

Like `node.spaces` with the `before` and `after` values containing the spaces
around the element, the parts of the attribute can also have spaces before
and after them. The for each of `attribute`, `operator`, `value` and
`insensitive` there is corresponding property of the same nam in
`node.spaces` that has an optional `before` or `after` string containing only
whitespace.

Note that corresponding values in `attributes.raws.spaces` contain values
including any comments. If set, these values will override the
`attribute.spaces` value. Take care to remove them if changing
`attribute.spaces`.

### `attribute.raws`

The raws object stores comments and other information necessary to re-render
the node exactly as it was in the source.

If a comment is embedded within the identifiers for the `namespace`, `attribute`
or `value` then a property is placed in the raws for that value containing the full source of the propery including comments.

If a comment is embedded within the space between parts of the attribute
then the raw for that space is set accordingly.

Setting an attribute's property `raws` value to be deleted.

For now, changing the spaces required also updating or removing any of the
raws values that override them.

Example: `[ /*before*/ href /* after-attr */ = /* after-operator */ te/*inside-value*/st/* wow */ /*omg*/i/*bbq*/ /*whodoesthis*/]` would parse as:

```js
{
  attribute: "href",
  operator: "=",
  value: "test",
  spaces: {
    before: '',
    after: '',
    attribute: { before: '  ', after: '  ' },
    operator: { after: '  ' },
    value: { after: ' ' },
    insensitive: { after: ' ' }
  },
  raws: {
    spaces: {
      attribute: { before: ' /*before*/ ', after: ' /* after-attr */ ' },
      operator: { after: ' /* after-operator */ ' },
      value: { after: '/* wow */ /*omg*/' },
      insensitive: { after: '/*bbq*/ /*whodoesthis*/' }
    },
    unquoted: 'test',
    value: 'te/*inside-value*/st'
  }
}
```

## `Processor`

### `ProcessorOptions`

* `lossless` - When `true`, whitespace is preserved. Defaults to `true`.
* `updateSelector` - When `true`, if any processor methods are passed a postcss
  `Rule` node instead of a string, then that Rule's selector is updated
  with the results of the processing. Defaults to `true`.

### `process|processSync(selectors, [options])`

Processes the `selectors`, returning a string from the result of processing.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

**Example:**

```js
const parser = require("postcss-selector-parser");
const processor = parser();

let result = processor.processSync(' .class');
console.log(result);
// =>  .class

// Asynchronous operation
let promise = processor.process(' .class').then(result => {
    console.log(result)
    // => .class
});

// To have the parser normalize whitespace values, utilize the options
result = processor.processSync('  .class  ', {lossless: false});
console.log(result);
// => .class

// For better syntax errors, pass a PostCSS Rule node.
const postcss = require('postcss');
rule = postcss.rule({selector: ' #foo    > a,  .class  '});
processor.process(rule, {lossless: false, updateSelector: true}).then(result => {
    console.log(result);
    // => #foo>a,.class
    console.log("rule:", rule.selector);
    // => rule: #foo>a,.class
})
```

Arguments:

* `selectors (string|postcss.Rule)`: Either a selector string or a PostCSS Rule
  node.
* `[options] (object)`: Process options


### `ast|astSync(selectors, [options])`

Like `process()` and `processSync()` but after
processing the `selectors` these methods return the `Root` node of the result
instead of a string.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

### `transform|transformSync(selectors, [options])`

Like `process()` and `processSync()` but after
processing the `selectors` these methods return the value returned by the
processor callback.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

### Error Handling Within Selector Processors

The root node passed to the selector processor callback
has a method `error(message, options)` that returns an
error object. This method should always be used to raise
errors relating to the syntax of selectors. The options
to this method are passed to postcss's error constructor
([documentation](http://postcss.org/api/#container-error)).

#### Async Error Example

```js
let processor = (root) => {
    return new Promise((resolve, reject) => {
        root.walkClasses((classNode) => {
            if (/^(.*)[-_]/.test(classNode.value)) {
                let msg = "classes may not have underscores or dashes in them";
                reject(root.error(msg, {
                    index: classNode.sourceIndex + RegExp.$1.length + 1,
                    word: classNode.value
                }));
            }
        });
        resolve();
    });
};

const postcss = require("postcss");
const parser = require("postcss-selector-parser");
const selectorProcessor = parser(processor);
const plugin = postcss.plugin('classValidator', (options) => {
    return (root) => {
        let promises = [];
        root.walkRules(rule => {
            promises.push(selectorProcessor.process(rule));
        });
        return Promise.all(promises);
    };
});
postcss(plugin()).process(`
.foo-bar {
  color: red;
}
`.trim(), {from: 'test.css'}).catch((e) => console.error(e.toString()));

// CssSyntaxError: classValidator: ./test.css:1:5: classes may not have underscores or dashes in them
//
// > 1 | .foo-bar {
//     |     ^
//   2 |   color: red;
//   3 | }
```

#### Synchronous Error Example

```js
let processor = (root) => {
    root.walkClasses((classNode) => {
        if (/.*[-_]/.test(classNode.value)) {
            let msg = "classes may not have underscores or dashes in them";
            throw root.error(msg, {
                index: classNode.sourceIndex,
                word: classNode.value
            });
        }
    });
};

const postcss = require("postcss");
const parser = require("postcss-selector-parser");
const selectorProcessor = parser(processor);
const plugin = postcss.plugin('classValidator', (options) => {
    return (root) => {
        root.walkRules(rule => {
            selectorProcessor.processSync(rule);
        });
    };
});
postcss(plugin()).process(`
.foo-bar {
  color: red;
}
`.trim(), {from: 'test.css'}).catch((e) => console.error(e.toString()));

// CssSyntaxError: classValidator: ./test.css:1:5: classes may not have underscores or dashes in them
//
// > 1 | .foo-bar {
//     |     ^
//   2 |   color: red;
//   3 | }
```


---

# 7.1.0

- feat: insert(Before|After) support multiple new node

# 7.0.0

- Feat: make insertions during iteration safe (major)

# 6.1.2

- Fixed: erroneous trailing combinators in pseudos

# 6.1.1

- Fixed: improve typings of constructor helpers (#292)

# 6.1.0

- Feature: add `sourceIndex` to `Selector` nodes (#290)

# 6.0.16

- Fixed: add missing `index` argument to `each`/`walk` callback types (#289)

# 6.0.15

- Fixed: Node#prev and Node#next type for the first/last node

# 6.0.14

- Fixed: type definitions

# 6.0.13

- Fixed: throw on unexpected pipe symbols

# 6.0.12

- Fixed: `clone` arguments should be optional

# 6.0.11

- Fixed: parse attribute case insensitivity flag

# 6.0.10

- Fixed: `isPseudoElement()` supports `:first-letter` and `:first-line`

# 6.0.9

- Fixed: `Combinator.raws` property type

# 6.0.8

- Fixed: reduced size

# 6.0.7

- Fixed: parse animation percents

# 6.0.6

- Fixed: parse quoted attributes containing a newline correctly

# 6.0.5

- Perf: rework unesc for a 63+% performance boost

# 6.0.4

- Fixed: ts errors

# 6.0.3

- Fixed: replace node built-in "util" module with "util-deprecate"
- Fixed: handle uppercase pseudo elements
- Fixed: do not create invalid combinator before comment

# 6.0.2

- Fixed an issue with parsing and stringifying an empty attribute value

# 6.0.1

- Fixed an issue with unicode surrogate pair parsing

# 6.0.0

- Updated: `cssesc` to 3.0.0 (major)
- Fixed: Issues with escaped `id` and `class` selectors

# 5.0.0

- Allow escaped dot within class name.
- Update PostCSS to 7.0.7 (patch)

# 5.0.0-rc.4

- Fixed an issue where comments immediately after an insensitive (in attribute)
  were not parsed correctly.
- Updated `cssesc` to 2.0.0 (major).
- Removed outdated integration tests.
- Added tests for custom selectors, tags with attributes, the universal
  selector with pseudos, and tokens after combinators.

# 5.0.0-rc.1

To ease adoption of the v5.0 release, we have relaxed the node version
check performed by npm at installation time to allow for node 4, which
remains officially unsupported, but likely to continue working for the
time being.

# 5.0.0-rc.0

This release has **BREAKING CHANGES** that were required to fix regressions
in 4.0.0 and to make the Combinator Node API consistent for all combinator
types. Please read carefully.

## Summary of Changes

* The way a descendent combinator that isn't a single space character (E.g. `.a  .b`) is stored in the AST has changed.
* Named Combinators (E.g. `.a /for/ .b`) are now properly parsed as a combinator.
* It is now possible to look up a node based on the source location of a character in that node and to query nodes if they contain some character.
* Several bug fixes that caused the parser to hang and run out of memory when a `/` was encountered have been fixed.
* The minimum supported version of Node is now `v6.0.0`.

### Changes to the Descendent Combinator

In prior releases, the value of a descendant combinator with multiple spaces included all the spaces.

* `.a   .b`: Extra spaces are now stored as space before.
  - Old & Busted:
    - `combinator.value === "   "`
  - New hotness:
    - `combinator.value === " " && combinator.spaces.before === "  "`
* `.a   /*comment*/.b`: A comment at the end of the combinator causes extra space to become after space.
  - Old & Busted:
    - `combinator.value === "   "`
    - `combinator.raws.value === "   /*comment/"`
  - New hotness:
    - `combinator.value === " "`
    - `combinator.spaces.after === "  "`
    - `combinator.raws.spaces.after === "  /*comment*/"`
* `.a<newline>.b`: whitespace that doesn't start or end with a single space character is stored as a raw value.
  - Old & Busted:
    - `combinator.value === "\n"`
    - `combinator.raws.value === undefined`
  - New hotness:
    - `combinator.value === " "`
    - `combinator.raws.value === "\n"`

### Support for "Named Combinators"

Although, nonstandard and unlikely to ever become a standard, combinators like `/deep/` and `/for/` are now properly supported.

Because they've been taken off the standardization track, there is no spec-official name for combinators of the form `/<ident>/`. However, I talked to [Tab Atkins](https://twitter.com/tabatkins) and we agreed to call them "named combinators" so now they are called that.

Before this release such named combinators were parsed without intention and generated three nodes of type `"tag"` where the first and last nodes had a value of `"/"`.

* `.a /for/ .b` is parsed as a combinator.
  - Old & Busted:
    - `root.nodes[0].nodes[1].type === "tag"`
    - `root.nodes[0].nodes[1].value === "/"`
  - New hotness:
    - `root.nodes[0].nodes[1].type === "combinator"`
    - `root.nodes[0].nodes[1].value === "/for/"`
* `.a /F\6fR/ .b` escapes are handled and uppercase is normalized.
  - Old & Busted:
    - `root.nodes[0].nodes[2].type === "tag"`
    - `root.nodes[0].nodes[2].value === "F\\6fR"`
  - New hotness:
    - `root.nodes[0].nodes[1].type === "combinator"`
    - `root.nodes[0].nodes[1].value === "/for/"`
    - `root.nodes[0].nodes[1].raws.value === "/F\\6fR/"`

### Source position checks and lookups

A new API was added to look up a node based on the source location.

```js
const selectorParser = require("postcss-selector-parser");
// You can find the most specific node for any given character
let combinator = selectorParser.astSync(".a > .b").atPosition(1,4);
combinator.toString() === " > ";
// You can check if a node includes a specific character
// Whitespace surrounding the node that is owned by that node
// is included in the check.
[2,3,4,5,6].map(column => combinator.isAtPosition(1, column));
// => [false, true, true, true, false]
```

# 4.0.0

This release has **BREAKING CHANGES** that were required to fix bugs regarding values with escape sequences. Please read carefully.

* **Identifiers with escapes** - CSS escape sequences are now hidden from the public API by default.
  The normal value of a node like a class name or ID, or an aspect of a node such as attribute
  selector's value, is unescaped. Escapes representing Non-ascii characters are unescaped into
  unicode characters. For example: `bu\tton, .\31 00, #i\2764\FE0Fu, [attr="value is \"quoted\""]`
  will parse respectively to the values `button`, `100`, `i❤️u`, `value is "quoted"`.
  The original escape sequences for these values can be found in the corresponding property name
  in `node.raws`. Where possible, deprecation warnings were added, but the nature
  of escape handling makes it impossible to detect what is escaped or not. Our expectation is
  that most users are neither expecting nor handling escape sequences in their use of this library,
  and so for them, this is a bug fix. Users who are taking care to handle escapes correctly can
  now update their code to remove the escape handling and let us do it for them.

* **Mutating values with escapes** - When you make an update to a node property that has escape handling
  The value is assumed to be unescaped, and any special characters are escaped automatically and
  the corresponding `raws` value is immediately updated. This can result in changes to the original
  escape format. Where the exact value of the escape sequence is important there are methods that
  allow both values to be set in conjunction. There are a number of new convenience methods for
  manipulating values that involve escapes, especially for attributes values where the quote mark
  is involved. See https://github.com/postcss/postcss-selector-parser/pull/133 for an extensive
  write-up on these changes.


**Upgrade/API Example**

In `3.x` there was no unescape handling and internal consistency of several properties was the caller's job to maintain. It was very easy for the developer
to create a CSS file that did not parse correctly when some types of values
were in use.

```js
const selectorParser = require("postcss-selector-parser");
let attr = selectorParser.attribute({attribute: "id", operator: "=", value: "a-value"});
attr.value; // => "a-value"
attr.toString(); // => [id=a-value]
// Add quotes to an attribute's value.
// All these values have to be set by the caller to be consistent:
// no internal consistency is maintained.
attr.raws.unquoted = attr.value
attr.value = "'" + attr.value + "'";
attr.value; // => "'a-value'"
attr.quoted = true;
attr.toString();  // => "[id='a-value']"
```

In `4.0` there is a convenient API for setting and mutating values
that may need escaping. Especially for attributes.

```js
const selectorParser = require("postcss-selector-parser");

// The constructor requires you specify the exact escape sequence
let className = selectorParser.className({value: "illegal class name", raws: {value: "illegal\\ class\\ name"}});
className.toString(); // => '.illegal\\ class\\ name'

// So it's better to set the value as a property
className = selectorParser.className();
// Most properties that deal with identifiers work like this
className.value = "escape for me";
className.value; // => 'escape for me'
className.toString(); // => '.escape\\ for\\ me'

// emoji and all non-ascii are escaped to ensure it works in every css file.
className.value = "😱🦄😍";
className.value; // => '😱🦄😍'
className.toString(); // => '.\\1F631\\1F984\\1F60D'

// you can control the escape sequence if you want, or do bad bad things
className.setPropertyAndEscape('value', 'xxxx', 'yyyy');
className.value; // => "xxxx"
className.toString(); // => ".yyyy"

// Pass a value directly through to the css output without escaping it. 
className.setPropertyWithoutEscape('value', '$REPLACE_ME$');
className.value; // => "$REPLACE_ME$"
className.toString(); // => ".$REPLACE_ME$"

// The biggest changes are to the Attribute class
// passing quoteMark explicitly is required to avoid a deprecation warning.
let attr = selectorParser.attribute({attribute: "id", operator: "=", value: "a-value", quoteMark: null});
attr.toString(); // => "[id=a-value]"
// Get the value with quotes on it and any necessary escapes.
// This is the same as reading attr.value in 3.x.
attr.getQuotedValue(); // => "a-value";
attr.quoteMark; // => null

// Add quotes to an attribute's value.
attr.quoteMark = "'"; // This is all that's required.
attr.toString(); // => "[id='a-value']"
attr.quoted; // => true
// The value is still the same, only the quotes have changed.
attr.value; // => a-value
attr.getQuotedValue(); // => "'a-value'";

// deprecated assignment, no warning because there's no escapes
attr.value = "new-value";
// no quote mark is needed so it is removed
attr.getQuotedValue(); // => "new-value";

// deprecated assignment, 
attr.value = "\"a 'single quoted' value\"";
// > (node:27859) DeprecationWarning: Assigning an attribute a value containing characters that might need to be escaped is deprecated. Call attribute.setValue() instead.
attr.getQuotedValue(); // => '"a \'single quoted\' value"';
// quote mark inferred from first and last characters.
attr.quoteMark; // => '"'

// setValue takes options to make manipulating the value simple.
attr.setValue('foo', {smart: true});
// foo doesn't require any escapes or quotes.
attr.toString(); // => '[id=foo]'
attr.quoteMark; // => null 

// An explicit quote mark can be specified
attr.setValue('foo', {quoteMark: '"'});
attr.toString(); // => '[id="foo"]'

// preserves quote mark by default
attr.setValue('bar');
attr.toString(); // => '[id="bar"]'
attr.quoteMark = null;
attr.toString(); // => '[id=bar]'

// with no arguments, it preserves quote mark even when it's not a great idea
attr.setValue('a value \n that should be quoted');
attr.toString(); // => '[id=a\\ value\\ \\A\\ that\\ should\\ be\\ quoted]'

// smart preservation with a specified default
attr.setValue('a value \n that should be quoted', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => "[id='a value \\A  that should be quoted']"
attr.quoteMark = '"';
// => '[id="a value \\A  that should be quoted"]'

// this keeps double quotes because it wants to quote the value and the existing value has double quotes.
attr.setValue('this should be quoted', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => '[id="this should be quoted"]'

// picks single quotes because the value has double quotes
attr.setValue('a "double quoted" value', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => "[id='a "double quoted" value']"

// setPropertyAndEscape lets you do anything you want. Even things that are a bad idea and illegal.
attr.setPropertyAndEscape('value', 'xxxx', 'the password is 42');
attr.value; // => "xxxx"
attr.toString(); // => "[id=the password is 42]"

// Pass a value directly through to the css output without escaping it. 
attr.setPropertyWithoutEscape('value', '$REPLACEMENT$');
attr.value; // => "$REPLACEMENT$"
attr.toString(); // => "[id=$REPLACEMENT$]"
```

# 3.1.2

* Fix: Removed dot-prop dependency since it's no longer written in es5.

# 3.1.1

* Fix: typescript definitions weren't in the published package.

# 3.1.0

* Fixed numerous bugs in attribute nodes relating to the handling of comments
  and whitespace. There's significant changes to `attrNode.spaces` and `attrNode.raws` since the `3.0.0` release.
* Added `Attribute#offsetOf(part)` to get the offset location of
  attribute parts like `"operator"` and `"value"`. This is most
  often added to `Attribute#sourceIndex` for error reporting.

# 3.0.0

## Breaking changes

* Some tweaks to the tokenizer/attribute selector parsing mean that whitespace
  locations might be slightly different to the 2.x code.
* Better attribute selector parsing with more validation; postcss-selector-parser
  no longer uses regular expressions to parse attribute selectors.
* Added an async API (thanks to @jacobp100); the default `process` API is now
  async, and the sync API is now accessed through `processSync` instead.
* `process()` and `processSync()` now return a string instead of the Processor
  instance.
* Tweaks handling of Less interpolation (thanks to @jwilsson).
* Removes support for Node 0.12.

## Other changes

* `ast()` and `astSync()` methods have been added to the `Processor`. These
  return the `Root` node of the selectors after processing them.
* `transform()` and `transformSync()` methods have been added to the
  `Processor`. These return the value returned by the processor callback
  after processing the selectors.
* Set the parent when inserting a node (thanks to @chriseppstein).
* Correctly adjust indices when using insertBefore/insertAfter (thanks to @tivac).
* Fixes handling of namespaces with qualified tag selectors.
* `process`, `ast` and `transform` (and their sync variants) now accept a
  `postcss` rule node. When provided, better errors are generated and selector
  processing is automatically set back to the rule selector (unless the `updateSelector` option is set to `false`.)
* Now more memory efficient when tokenizing selectors.

### Upgrade hints

The pattern of:

`rule.selector = processor.process(rule.selector).result.toString();`

is now:

`processor.processSync(rule)`

# 2.2.3

* Resolves an issue where the parser would not reduce multiple spaces between an
  ampersand and another simple selector in lossy mode (thanks to @adam-26).

# 2.2.2

* No longer hangs on an unescaped semicolon; instead the parser will throw
  an exception for these cases.

# 2.2.1

* Allows a consumer to specify whitespace tokens when creating a new Node
  (thanks to @Semigradsky).

# 2.2.0

* Added a new option to normalize whitespace when parsing the selector string
  (thanks to @adam-26).

# 2.1.1

* Better unquoted value handling within attribute selectors
  (thanks to @evilebottnawi).

# 2.1.0

* Added: Use string constants for all node types & expose them on the main
  parser instance (thanks to @Aweary).

# 2.0.0

This release contains the following breaking changes:

* Renamed all `eachInside` iterators to `walk`. For example, `eachTag` is now
  `walkTags`, and `eachInside` is now `walk`.
* Renamed `Node#removeSelf()` to `Node#remove()`.
* Renamed `Container#remove()` to `Container#removeChild()`.
* Renamed `Node#raw` to `Node#raws` (thanks to @davidtheclark).
* Now parses `&` as the *nesting* selector, rather than a *tag* selector.
* Fixes misinterpretation of Sass interpolation (e.g. `#{foo}`) as an
  id selector (thanks to @davidtheclark).

and;

* Fixes parsing of attribute selectors with equals signs in them
  (e.g. `[data-attr="foo=bar"]`) (thanks to @montmanu).
* Adds `quoted` and `raw.unquoted` properties to attribute nodes
  (thanks to @davidtheclark).

# 1.3.3

* Fixes an infinite loop on `)` and `]` tokens when they had no opening pairs.
  Now postcss-selector-parser will throw when it encounters these lone tokens.

# 1.3.2

* Now uses plain integers rather than `str.charCodeAt(0)` for compiled builds.

# 1.3.1

* Update flatten to v1.x (thanks to @shinnn).

# 1.3.0

* Adds a new node type, `String`, to fix a crash on selectors such as
  `foo:bar("test")`.

# 1.2.1

* Fixes a crash when the parser encountered a trailing combinator.

# 1.2.0

* A more descriptive error is thrown when the parser expects to find a
  pseudo-class/pseudo-element (thanks to @ashelley).
* Adds support for line/column locations for selector nodes, as well as a
  `Node#sourceIndex` method (thanks to @davidtheclark).

# 1.1.4

* Fixes a crash when a selector started with a `>` combinator. The module will
  now no longer throw if a selector has a leading/trailing combinator node.

# 1.1.3

* Fixes a crash on `@` tokens.

# 1.1.2

* Fixes an infinite loop caused by using parentheses in a non-pseudo element
  context.

# 1.1.1

* Fixes a crash when a backslash ended a selector string.

# 1.1.0

* Adds support for replacing multiple nodes at once with `replaceWith`
  (thanks to @jonathantneal).
* Parser no longer throws on sequential IDs and trailing commas, to support
  parsing of selector hacks.

# 1.0.1

* Fixes using `insertAfter` and `insertBefore` during iteration.

# 1.0.0

* Adds `clone` and `replaceWith` methods to nodes.
* Adds `insertBefore` and `insertAfter` to containers.
* Stabilises API.

# 0.0.5

* Fixes crash on extra whitespace inside a pseudo selector's parentheses.
* Adds sort function to the container class.
* Enables the parser to pass its input through without transforming.
* Iteration-safe `each` and `eachInside`.

# 0.0.4

* Tidy up redundant duplication.
* Fixes a bug where the parser would loop infinitely on universal selectors
  inside pseudo selectors.
* Adds `length` getter and `eachInside`, `map`, `reduce` to the container class.
* When a selector has been removed from the tree, the root node will no longer
  cast it to a string.
* Adds node type iterators to the container class (e.g. `eachComment`).
* Adds filter function to the container class.
* Adds split function to the container class.
* Create new node types by doing `parser.id(opts)` etc.
* Adds support for pseudo classes anywhere in the selector.

# 0.0.3

* Adds `next` and `prev` to the node class.
* Adds `first` and `last` getters to the container class.
* Adds `every` and `some` iterators to the container class.
* Add `empty` alias for `removeAll`.
* Combinators are now types of node.
* Fixes the at method so that it is not an alias for `index`.
* Tidy up creation of new nodes in the parser.
* Refactors how namespaces are handled for consistency & less redundant code.
* Refactors AST to use `nodes` exclusively, and eliminates excessive nesting.
* Fixes nested pseudo parsing.
* Fixes whitespace parsing.

# 0.0.2

* Adds support for namespace selectors.
* Adds support for selectors joined by escaped spaces - such as `.\31\ 0`.

# 0.0.1

* Initial release.


---

# postcss-selector-parser [![test](https://github.com/postcss/postcss-selector-parser/actions/workflows/test.yml/badge.svg)](https://github.com/postcss/postcss-selector-parser/actions/workflows/test.yml)

> Selector parser with built in methods for working with selector strings.

## Install

With [npm](https://npmjs.com/package/postcss-selector-parser) do:

```
npm install postcss-selector-parser
```

## Quick Start

```js
const parser = require('postcss-selector-parser');
const transform = selectors => {
    selectors.walk(selector => {
        // do something with the selector
        console.log(String(selector))
    });
};

const transformed = parser(transform).processSync('h1, h2, h3');
```

To normalize selector whitespace:

```js
const parser = require('postcss-selector-parser');
const normalized = parser().processSync('h1, h2, h3', {lossless: false});
// -> h1,h2,h3
```

Async support is provided through `parser.process` and will resolve a Promise
with the resulting selector string.

## API

Please see [API.md](API.md).

## Credits

* Huge thanks to Andrey Sitnik (@ai) for work on PostCSS which helped
  accelerate this module's development.

## License

MIT


---

ISC License

Copyright (c)

Permission to use, copy, modify, and/or distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.


---

<img alt='CSS declaration sorter logo' src='https://raw.githubusercontent.com/Siilwyn/css-declaration-sorter/master/logo.svg?sanitize=true' height='260' align='right'>

# CSS Declaration Sorter
[![npm][npm-badge]][npm]

A Node.js module and [PostCSS] plugin to sort CSS, SCSS or Less declarations based on their property names. Ensuring styling is organized, more consistent and in order... The goal of this package is to sort the source code of a project in the build process or to decrease the distributed CSS gzipped size.

Check out [the Prettier plugin](https://github.com/Siilwyn/prettier-plugin-css-order) for usage with a variety of file formats.

## Niceness
- Up-to-date CSS properties fetched from the [MDN Compatibility Data](https://github.com/mdn/browser-compat-data/) project.
- Choose your wanted order or provide your own.
- Nested rules sorting support.
- SCSS and Less support when combined with either [postcss-scss](https://github.com/postcss/postcss-scss) or [postcss-less](https://github.com/webschik/postcss-less).
- Thought-out sorting orders out of the box, **approved by their authors**.

## Alphabetical example
Input:
```css
body {
    display: block;
    animation: none;
    color: #C55;
    border: 0;
}
```

Output:
```css
body {
    animation: none;
    border: 0;
    color: #C55;
    display: block;
}
```

## Built-in sorting orders
- Alphabetical  
`alphabetical`  
*Default, order in a simple alphabetical manner from a - z.*

- [SMACSS](http://smacss.com/book/formatting#grouping)  
`smacss`  
*Order from most important, flow affecting properties, to least important properties.*
  1. Box
  2. Border
  3. Background
  4. Text
  5. Other

- [Concentric CSS](https://github.com/brandon-rhodes/Concentric-CSS)  
`concentric-css`  
*Order properties applying outside the box model, moving inward to intrinsic changes.*
  1. Positioning
  2. Visibility
  3. Box model
  4. Dimensions
  5. Text

## Usage
Following the PostCSS plugin guidelines, this package depends on PostCSS as a peer dependency:  
`npm install postcss css-declaration-sorter --save-dev`

### CLI
This module does not include its own CLI but works with the official [PostCSS CLI](https://github.com/postcss/postcss-cli). To use the examples below, the `postcss-cli` package is a required dependency.

Piping out result from file:  
`postcss input.css --use css-declaration-sorter | cat`

Sorting multiple files by overwriting:  
`postcss *.css --use css-declaration-sorter --replace --no-map`

Sorting all files in a directory with SCSS syntax using [postcss-scss](https://github.com/postcss/postcss-scss) by overwriting:  
`postcss ./src/**/*.scss --syntax postcss-scss --use css-declaration-sorter --replace --no-map`

Sorting all files in the directory with SCSS syntax and SMACSS order by overwriting, using `package.json` configuration:  
```json
"postcss": {
  "syntax": "postcss-scss",
  "map": false,
  "plugins": {
    "css-declaration-sorter": { "order": "smacss" }
  }
}
```

`postcss ./src/**/*.scss --replace --config package.json`

### Vanilla JS
```js
import postcss from 'postcss';
import { cssDeclarationSorter } from 'css-declaration-sorter';

postcss([cssDeclarationSorter({ order: 'smacss' })])
  .process('a { color: hyperblue; display: block; }', { from: undefined })
  .then(result => console.log(
    result.css === 'a { display: block; color: hyperblue; }'
  ));
```
___

**[View more usage examples](/examples) in combination with other tools.**  

___

## API
### cssDeclarationSorter({ order, keepOverrides })

#### order
Type: `string` or `function`  
Default: `alphabetical`  
Options: `alphabetical`, `smacss`, `concentric-css`

Provide the name of one of the built-in sort orders or a comparison function that is passed to ([`Array.sort`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort)). This function receives two declaration names and is expected to return `-1`, `0` or `1` depending on the wanted order.

#### keepOverrides
Type: `Boolean`  
Default: `false`  

To prevent breaking legacy CSS where shorthand declarations override longhand declarations (also taking into account vendor prefixes) this option can enabled. For example `animation-name: some; animation: greeting;` will be kept in this order when `keepOverrides` is `true`.

[PostCSS]: https://github.com/postcss/postcss

[npm]: https://www.npmjs.com/package/css-declaration-sorter
[npm-badge]: https://tinyshields.dev/npm/css-declaration-sorter.svg


---

# Changes to CSS Has Pseudo

### 7.0.2

_December 13, 2024_

- Fix handling of stylesheets loaded after the polyfill was first started.

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/css-has-pseudo/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Has Pseudo [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install css-has-pseudo --save-dev`

[PostCSS Has Pseudo] lets you style elements relative to other elements in CSS, following the [Selectors Level 4] specification.

To use this feature you need to do two things :
- add the [PostCSS plugin](#usage) that transforms the selector into a class or attribute
- add the [browser polyfill](#browser) that sets the attribute or class on elements in a browser

```css
.title:has(+ p) {
	margin-bottom: 1.5rem;
}

/* becomes */

.js-has-pseudo [csstools-has-1a-38-2x-38-30-2t-1m-2w-2p-37-14-17-w-34-15]:not(does-not-exist) {
	margin-bottom: 1.5rem;
}
.title:has(+ p) {
	margin-bottom: 1.5rem;
}
```

## Usage

Add [PostCSS Has Pseudo] to your project:

```bash
npm install postcss css-has-pseudo --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssHasPseudo = require('css-has-pseudo');

postcss([
	postcssHasPseudo(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## Options

### preserve

The `preserve` option determines whether the original notation
is preserved. By default the original rules are preserved.

```js
postcssHasPseudo({ preserve: false })
```

```css
.title:has(+ p) {
	margin-bottom: 1.5rem;
}

/* becomes */

.js-has-pseudo [csstools-has-1a-38-2x-38-30-2t-1m-2w-2p-37-14-17-w-34-15]:not(does-not-exist) {
	margin-bottom: 1.5rem;
}
```

### specificityMatchingName

The `specificityMatchingName` option allows you to change the selector that is used to adjust specificity.
The default value is `does-not-exist`.
If this is an actual class, id or tag name in your code, you will need to set a different option here.

See how `:not` is used to modify [specificity](#specificity).

```js
postcssHasPseudo({ specificityMatchingName: 'something-random' })
```

[specificity 1, 2, 0](https://polypane.app/css-specificity-calculator/#selector=.x%3Ahas(%3E%20%23a%3Ahover))

Before :

```css
.x:has(> #a:hover) {
	order: 11;
}
```

After :

[specificity 1, 2, 0](https://polypane.app/css-specificity-calculator/#selector=%5Bcsstools-has-1a-3c-1m-2w-2p-37-14-1q-w-z-2p-1m-2w-33-3a-2t-36-15%5D%3Anot(%23does-not-exist)%3Anot(.does-not-exist))

```css
[csstools-has-1a-3c-1m-2w-2p-37-14-1q-w-z-2p-1m-2w-33-3a-2t-36-15]:not(#does-not-exist):not(.does-not-exist) {
	order: 11;
}
```

## ⚠️ Known shortcomings

### Performance

Determining which elements match a `:has` selector is relatively slow through a polyfill compared to the native feature.

A very large DOM or many and complex `:has` selectors can cause performance issues.  
JavaScript frameworks that rewrite the DOM will be particularly affected by this.

_Any contributions to speedup matching are welcome.  
Please open an issue to discuss proposed changes if you are interested in contributing._

### Specificity

`:has` transforms will result in at least one attribute selector with specificity `0, 1, 0`.<br>
If your selector only has tags we won't be able to match the original specificity.

Before :

[specificity 0, 0, 2](https://polypane.app/css-specificity-calculator/#selector=figure%3Ahas(%3E%20img))

```css
figure:has(> img)
```

After :

[specificity 0, 1, 2](https://polypane.app/css-specificity-calculator/#selector=%5Bcsstools-has-2u-2x-2v-39-36-2t-1m-2w-2p-37-14-1q-w-2x-31-2v-15%5D%3Anot(does-not-exist)%3Anot(does-not-exist))

```css
[csstools-has-2u-2x-2v-39-36-2t-1m-2w-2p-37-14-1q-w-2x-31-2v-15]:not(does-not-exist):not(does-not-exist)
```

### Plugin order

As selectors are encoded, this plugin (or `postcss-preset-env`) must be run after any other plugin that transforms selectors.

If other plugins are used, you need to place these in your config before `postcss-preset-env` or `css-has-pseudo`.

Please let us know if you have issues with plugins that transform selectors.
Then we can investigate and maybe fix these.

## Browser

```js
// initialize cssHasPseudo
import cssHasPseudo from 'css-has-pseudo/browser';
cssHasPseudo(document);
```

or

```html
<!-- When using a CDN url you will have to manually update the version number -->
<script src="https://unpkg.com/css-has-pseudo@7.0.2/dist/browser-global.js"></script>
<script>cssHasPseudo(document)</script>
```

> [!TIP]
> Please use a versioned url, like this : `https://unpkg.com/css-has-pseudo@7.0.2/dist/browser-global.js`
> Without the version, you might unexpectedly get a new major version of the library with breaking changes.

[PostCSS Has Pseudo] works in all major browsers, including
Internet Explorer 11. With a [Mutation Observer polyfill](https://github.com/webmodules/mutation-observer), the script will work
down to Internet Explorer 9.

### Browser Usage

#### hover

The `hover` option determines if `:hover` pseudo-class should be tracked.
This is disabled by default because it is an expensive operation.

```js
cssHasPseudo(document, { hover: true });
```

#### observedAttributes

The `observedAttributes` option determines which html attributes are observed.
If you do any client side modification of non-standard attributes and use these in combination with `:has()` you should add these here.

```js
cssHasPseudo(document, { observedAttributes: ['something-not-standard'] });
```

#### forcePolyfill

The `forcePolyfill` option determines if the polyfill is used even when the browser has native support.
This is needed when you set `preserve: false` in the PostCSS plugin config.

```js
cssHasPseudo(document, { forcePolyfill: true });
```

#### debug

The `debug` option determines if errors are emitted to the console in browser.
By default the polyfill will not emit errors or warnings.

```js
cssHasPseudo(document, { debug: true });
```

### Browser Dependencies

Web API's:

- [MutationObserver](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver)
- [requestAnimationFrame](https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame)
- [querySelectorAll](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelectorAll) with support for post CSS 2.1 selectors and `:scope` selectors.

ECMA Script:

- `Array.prototype.filter`
- `Array.prototype.forEach`
- `Array.prototype.indexOf`
- `Array.prototype.join`
- `Array.prototype.map`
- `Array.prototype.splice`
- `RegExp.prototype.exec`
- `String.prototype.match`
- `String.prototype.replace`
- `String.prototype.split`

## CORS

> [!IMPORTANT]
> Applies to you if you load CSS from a different domain than the page.
>
> In this case the CSS is treated as untrusted and will not be made available to the JavaScript polyfill.
> The polyfill will not work without applying the correct configuration for CORS.

Example :

| page | css | CORS applies |
| --- | --- | --- |
| https://example.com/ | https://example.com/style.css | no |
| https://example.com/ | https://other.com/style.css | yes |


**You might see one of these error messages :**

Chrome :

> DOMException: Failed to read the 'cssRules' property from 'CSSStyleSheet': Cannot access rules

Safari :

> SecurityError: Not allowed to access cross-origin stylesheet

Firefox :

> DOMException: CSSStyleSheet.cssRules getter: Not allowed to access cross-origin stylesheet

To resolve CORS errors you need to take two steps :

- add an HTTP header `Access-Control-Allow-Origin: <your-value>` when serving your CSS file.
- add `crossorigin="anonymous"` to the `<link rel="stylesheet">` tag for your CSS file.

In a node server setting the HTTP header might look like this :

```js
// http://localhost:8080 is the domain of your page!
res.setHeader('Access-Control-Allow-Origin', 'https://example.com');
```

You can also configure a wildcard but please be aware that this might be a security risk.
It is better to only set the header for the domain you want to allow and only on the responses you want to allow.

HTML might look like this :

```html
<link rel="stylesheet" href="https://example.com/styles.css" crossorigin="anonymous">
```


### Using with Next.js

Given that Next.js imports packages both on the browser and on the server, you need to make sure that the package is only imported on the browser.

As outlined in the [Next.js documentation](https://nextjs.org/docs/advanced-features/dynamic-import#with-external-libraries), you need to load the package with a dynamic import:

```jsx
useEffect(async () => {
	const cssHasPseudo = (await import('css-has-pseudo/browser')).default;
	cssHasPseudo(document);
}, []);
```

We recommend you load the polyfill as high up on your Next application as possible, such as your `pages/_app.ts` file.

## How it works

The [PostCSS Has Pseudo] clones rules containing `:has()`,
replacing them with an alternative `[csstools-has-]` selector.

```css
.title:has(+ p) {
	margin-bottom: 1.5rem;
}

/* becomes */

.js-has-pseudo [csstools-has-1a-38-2x-38-30-2t-1m-2w-2p-37-14-17-w-34-15]:not(does-not-exist) {
	margin-bottom: 1.5rem;
}
.title:has(+ p) {
	margin-bottom: 1.5rem;
}
```

Next, the [browser script](#browser) adds a `[:has]` attribute to
elements otherwise matching `:has` natively.

```html
<div class="title" [csstools-has-1a-38-2x-38-30-2t-1m-2w-2p-37-14-17-w-34-15]>
	<h1>A title block</h1>
	<p>With an extra paragraph</p>
</div>
```

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#has-pseudo-class
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/css-has-pseudo

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Has Pseudo]: https://github.com/csstools/postcss-plugins/tree/main/plugins/css-has-pseudo
[Selectors Level 4]: https://www.w3.org/TR/selectors-4/#has-pseudo


---

# Changes to Selector Specificity

### 5.0.0

_October 23, 2024_

- Updated: `postcss-selector-parser`

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/packages/selector-specificity/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# Selector Specificity

[<img alt="npm version" src="https://img.shields.io/npm/v/@csstools/selector-specificity.svg" height="20">][npm-url]
[<img alt="Build Status" src="https://github.com/csstools/postcss-plugins/workflows/test/badge.svg" height="20">][cli-url]
[<img alt="Discord" src="https://shields.io/badge/Discord-5865F2?logo=discord&logoColor=white">][discord]

## Usage

Add [Selector Specificity] to your project:

```bash
npm install @csstools/selector-specificity --save-dev
```

```js
import parser from 'postcss-selector-parser';
import { selectorSpecificity } from '@csstools/selector-specificity';

const selectorAST = parser().astSync('#foo:has(> .foo)');
const specificity = selectorSpecificity(selectorAST);

console.log(specificity.a); // 1
console.log(specificity.b); // 1
console.log(specificity.c); // 0
```

_`selectorSpecificity` takes a single selector, not a list of selectors (not : `a, b, c`).
To compare or otherwise manipulate lists of selectors you need to call `selectorSpecificity` on each part._

### Comparing

The package exports a utility function to compare two specificities.

```js
import { selectorSpecificity, compare } from '@csstools/selector-specificity';

const s1 = selectorSpecificity(ast1);
const s2 = selectorSpecificity(ast2);
compare(s1, s2); // -1 | 0 | 1
```

- if `s1 < s2` then `compare(s1, s2)` returns a negative number (`< 0`)
- if `s1 > s2` then `compare(s1, s2)` returns a positive number (`> 0`)
- if `s1 === s2` then `compare(s1, s2)` returns zero (`=== 0`)

## Prior Art

- [keeganstreet/specificity](https://github.com/keeganstreet/specificity)
- [bramus/specificity](https://github.com/bramus/specificity)

For CSSTools we always use `postcss-selector-parser` and want to calculate specificity from this AST.

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/selector-specificity

[Selector Specificity]: https://github.com/csstools/postcss-plugins/tree/main/packages/selector-specificity


---

# API Documentation

*Please use only this documented API when working with the parser. Methods
not documented here are subject to change at any point.*

## `parser` function

This is the module's main entry point.

```js
const parser = require('postcss-selector-parser');
```

### `parser([transform], [options])`

Creates a new `processor` instance

```js
const processor = parser();
```

Or, with optional transform function

```js
const transform = selectors => {
    selectors.walkUniversals(selector => {
        selector.remove();
    });
};

const processor = parser(transform)

// Example
const result = processor.processSync('*.class');
// => .class
```

[See processor documentation](#processor)

Arguments:

* `transform (function)`: Provide a function to work with the parsed AST.
* `options (object)`: Provide default options for all calls on the returned `Processor`.

### `parser.attribute([props])`

Creates a new attribute selector.

```js
parser.attribute({attribute: 'href'});
// => [href]
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.className([props])`

Creates a new class selector.

```js
parser.className({value: 'button'});
// => .button
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.combinator([props])`

Creates a new selector combinator.

```js
parser.combinator({value: '+'});
// => +
```

Arguments:

* `props (object)`: The new node's properties.

Notes:
* **Descendant Combinators** The value of descendant combinators created by the
  parser always just a single space (`" "`). For descendant selectors with no
  comments, additional space is now stored in `node.spaces.before`. Depending
  on the location of comments, additional spaces may be stored in
  `node.raws.spaces.before`, `node.raws.spaces.after`, or `node.raws.value`.
* **Named Combinators** Although, nonstandard and unlikely to ever become a standard,
  named combinators like `/deep/` and `/for/` are parsed as combinators. The
  `node.value` is name after being unescaped and normalized as lowercase. The
  original value for the combinator name is stored in `node.raws.value`.


### `parser.comment([props])`

Creates a new comment.

```js
parser.comment({value: '/* Affirmative, Dave. I read you. */'});
// => /* Affirmative, Dave. I read you. */
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.id([props])`

Creates a new id selector.

```js
parser.id({value: 'search'});
// => #search
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.nesting([props])`

Creates a new nesting selector.

```js
parser.nesting();
// => &
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.pseudo([props])`

Creates a new pseudo selector.

```js
parser.pseudo({value: '::before'});
// => ::before
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.root([props])`

Creates a new root node.

```js
parser.root();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.selector([props])`

Creates a new selector node.

```js
parser.selector();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.string([props])`

Creates a new string node.

```js
parser.string();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.tag([props])`

Creates a new tag selector.

```js
parser.tag({value: 'button'});
// => button
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.universal([props])`

Creates a new universal selector.

```js
parser.universal();
// => *
```

Arguments:

* `props (object)`: The new node's properties.

## Node types

### `node.type`

A string representation of the selector type. It can be one of the following;
`attribute`, `class`, `combinator`, `comment`, `id`, `nesting`, `pseudo`,
`root`, `selector`, `string`, `tag`, or `universal`. Note that for convenience,
these constants are exposed on the main `parser` as uppercased keys. So for
example you can get `id` by querying `parser.ID`.

```js
parser.attribute({attribute: 'href'}).type;
// => 'attribute'
```

### `node.parent`

Returns the parent node.

```js
root.nodes[0].parent === root;
```

### `node.toString()`, `String(node)`, or `'' + node`

Returns a string representation of the node.

```js
const id = parser.id({value: 'search'});
console.log(String(id));
// => #search
```

### `node.next()` & `node.prev()`

Returns the next/previous child of the parent node.

```js
const next = id.next();
if (next && next.type !== 'combinator') {
    throw new Error('Qualified IDs are not allowed!');
}
```

### `node.replaceWith(node[,...nodeN])`

Replace a node with another.

```js
const attr = selectors.first.first;
const className = parser.className({value: 'test'});
attr.replaceWith(className);
```

Arguments:

* `node`: The node to substitute the original with.
...
* `nodeN`: The node to substitute the original with.

### `node.remove()`

Removes the node from its parent node.

```js
if (node.type === 'id') {
    node.remove();
}
```

### `node.clone([opts])`

Returns a copy of a node, detached from any parent containers that the
original might have had.

```js
const cloned = node.clone();
```

### `node.isAtPosition(line, column)`

Return a `boolean` indicating whether this node includes the character at the
position of the given line and column. Returns `undefined` if the nodes lack
sufficient source metadata to determine the position.

Arguments:

* `line`: 1-index based line number relative to the start of the selector.
* `column`: 1-index based column number relative to the start of the selector.

### `node.spaces`

Extra whitespaces around the node will be moved into `node.spaces.before` and
`node.spaces.after`. So for example, these spaces will be moved as they have
no semantic meaning:

```css
      h1     ,     h2   {}
```

For descendent selectors, the value is always a single space.

```css
h1        h2 {}
```

Additional whitespace is found in either the `node.spaces.before` and `node.spaces.after` depending on the presence of comments or other whitespace characters. If the actual whitespace does not start or end with a single space, the node's raw value is set to the actual space(s) found in the source.

### `node.source`

An object describing the node's start/end, line/column source position.

Within the following CSS, the `.bar` class node ...

```css
.foo,
  .bar {}
```

... will contain the following `source` object.

```js
source: {
    start: {
        line: 2,
        column: 3
    },
    end: {
        line: 2,
        column: 6
    }
}
```

### `node.sourceIndex`

The zero-based index of the node within the original source string.

Within the following CSS, the `.baz` class node will have a `sourceIndex` of `12`.

```css
.foo, .bar, .baz {}
```

## Container types

The `root`, `selector`, and `pseudo` nodes have some helper methods for working
with their children.

### `container.nodes`

An array of the container's children.

```js
// Input: h1 h2
selectors.at(0).nodes.length   // => 3
selectors.at(0).nodes[0].value // => 'h1'
selectors.at(0).nodes[1].value // => ' '
```

### `container.first` & `container.last`

The first/last child of the container.

```js
selector.first === selector.nodes[0];
selector.last === selector.nodes[selector.nodes.length - 1];
```

### `container.at(index)`

Returns the node at position `index`.

```js
selector.at(0) === selector.first;
selector.at(0) === selector.nodes[0];
```

Arguments:

* `index`: The index of the node to return.

### `container.atPosition(line, column)`

Returns the node at the source position `line` and `column`.

```js
// Input: :not(.foo),\n#foo > :matches(ol, ul)
selector.atPosition(1, 1); // => :not(.foo)
selector.atPosition(2, 1); // => \n#foo
```

Arguments:

* `line`: The line number of the node to return.
* `column`: The column number of the node to return.

### `container.index(node)`

Return the index of the node within its container.

```js
selector.index(selector.nodes[2]) // => 2
```

Arguments:

* `node`: A node within the current container.

### `container.length`

Proxy to the length of the container's nodes.

```js
container.length === container.nodes.length
```

### `container` Array iterators

The container class provides proxies to certain Array methods; these are:

* `container.map === container.nodes.map`
* `container.reduce === container.nodes.reduce`
* `container.every === container.nodes.every`
* `container.some === container.nodes.some`
* `container.filter === container.nodes.filter`
* `container.sort === container.nodes.sort`

Note that these methods only work on a container's immediate children; recursive
iteration is provided by `container.walk`.

### `container.each(callback)`

Iterate the container's immediate children, calling `callback` for each child.
You may return `false` within the callback to break the iteration.

```js
let className;
selectors.each((selector, index) => {
    if (selector.type === 'class') {
        className = selector.value;
        return false;
    }
});
```

Note that unlike `Array#forEach()`, this iterator is safe to use whilst adding
or removing nodes from the container.

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  and `index` arguments.

### `container.walk(callback)`

Like `container#each`, but will also iterate child nodes as long as they are
`container` types.

```js
selectors.walk((selector, index) => {
    // all nodes
});
```

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  and `index` arguments.

This iterator is safe to use whilst mutating `container.nodes`,
like `container#each`.

### `container.walk` proxies

The container class provides proxy methods for iterating over types of nodes,
so that it is easier to write modules that target specific selectors. Those
methods are:

* `container.walkAttributes`
* `container.walkClasses`
* `container.walkCombinators`
* `container.walkComments`
* `container.walkIds`
* `container.walkNesting`
* `container.walkPseudos`
* `container.walkTags`
* `container.walkUniversals`

### `container.split(callback)`

This method allows you to split a group of nodes by returning `true` from
a callback. It returns an array of arrays, where each inner array corresponds
to the groups that you created via the callback.

```js
// (input) => h1 h2>>h3
const list = selectors.first.split(selector => {
    return selector.type === 'combinator';
});

// (node values) => [['h1', ' '], ['h2', '>>'], ['h3']]
```

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  as an argument.

### `container.prepend(node)` & `container.append(node)`

Add a node to the start/end of the container. Note that doing so will set
the parent property of the node to this container.

```js
const id = parser.id({value: 'search'});
selector.append(id);
```

Arguments:

* `node`: The node to add.

### `container.insertBefore(old, new[, ...newNodes])` & `container.insertAfter(old, new[, ...newNodes])`

Add a node before or after an existing node in a container:

```js
selectors.walk(selector => {
    if (selector.type !== 'class') {
        const className = parser.className({value: 'theme-name'});
        selector.parent.insertAfter(selector, className);
    }
});
```

Arguments:

* `old`: The existing node in the container.
* `new`: The new node to add before/after the existing node.

### `container.removeChild(node)`

Remove the node from the container. Note that you can also use
`node.remove()` if you would like to remove just a single node.

```js
selector.length // => 2
selector.remove(id)
selector.length // => 1;
id.parent       // undefined
```

Arguments:

* `node`: The node to remove.

### `container.removeAll()` or `container.empty()`

Remove all children from the container.

```js
selector.removeAll();
selector.length // => 0
```

## Root nodes

A root node represents a comma separated list of selectors. Indeed, all
a root's `toString()` method does is join its selector children with a ','.
Other than this, it has no special functionality and acts like a container.

### `root.trailingComma`

This will be set to `true` if the input has a trailing comma, in order to
support parsing of legacy CSS hacks.

## Selector nodes

A selector node represents a single complex selector. For example, this
selector string `h1 h2 h3, [href] > p`, is represented as two selector nodes.
It has no special functionality of its own.

## Pseudo nodes

A pseudo selector extends a container node; if it has any parameters of its
own (such as `h1:not(h2, h3)`), they will be its children. Note that the pseudo
`value` will always contain the colons preceding the pseudo identifier. This
is so that both `:before` and `::before` are properly represented in the AST.

## Attribute nodes

### `attribute.quoted`

Returns `true` if the attribute's value is wrapped in quotation marks, false if it is not.
Remains `undefined` if there is no attribute value.

```css
[href=foo] /* false */
[href='foo'] /* true */
[href="foo"] /* true */
[href] /* undefined */
```

### `attribute.qualifiedAttribute`

Returns the attribute name qualified with the namespace if one is given.

### `attribute.offsetOf(part)`

 Returns the offset of the attribute part specified relative to the
 start of the node of the output string. This is useful in raising
 error messages about a specific part of the attribute, especially
 in combination with `attribute.sourceIndex`.

 Returns `-1` if the name is invalid or the value doesn't exist in this
 attribute.

 The legal values for `part` are:

 * `"ns"` - alias for "namespace"
 * `"namespace"` - the namespace if it exists.
 * `"attribute"` - the attribute name
 * `"attributeNS"` - the start of the attribute or its namespace
 * `"operator"` - the match operator of the attribute
 * `"value"` - The value (string or identifier)
 * `"insensitive"` - the case insensitivity flag

### `attribute.raws.unquoted`

Returns the unquoted content of the attribute's value.
Remains `undefined` if there is no attribute value.

```css
[href=foo] /* foo */
[href='foo'] /* foo */
[href="foo"] /* foo */
[href] /* undefined */
```

### `attribute.spaces`

Like `node.spaces` with the `before` and `after` values containing the spaces
around the element, the parts of the attribute can also have spaces before
and after them. The for each of `attribute`, `operator`, `value` and
`insensitive` there is corresponding property of the same nam in
`node.spaces` that has an optional `before` or `after` string containing only
whitespace.

Note that corresponding values in `attributes.raws.spaces` contain values
including any comments. If set, these values will override the
`attribute.spaces` value. Take care to remove them if changing
`attribute.spaces`.

### `attribute.raws`

The raws object stores comments and other information necessary to re-render
the node exactly as it was in the source.

If a comment is embedded within the identifiers for the `namespace`, `attribute`
or `value` then a property is placed in the raws for that value containing the full source of the propery including comments.

If a comment is embedded within the space between parts of the attribute
then the raw for that space is set accordingly.

Setting an attribute's property `raws` value to be deleted.

For now, changing the spaces required also updating or removing any of the
raws values that override them.

Example: `[ /*before*/ href /* after-attr */ = /* after-operator */ te/*inside-value*/st/* wow */ /*omg*/i/*bbq*/ /*whodoesthis*/]` would parse as:

```js
{
  attribute: "href",
  operator: "=",
  value: "test",
  spaces: {
    before: '',
    after: '',
    attribute: { before: '  ', after: '  ' },
    operator: { after: '  ' },
    value: { after: ' ' },
    insensitive: { after: ' ' }
  },
  raws: {
    spaces: {
      attribute: { before: ' /*before*/ ', after: ' /* after-attr */ ' },
      operator: { after: ' /* after-operator */ ' },
      value: { after: '/* wow */ /*omg*/' },
      insensitive: { after: '/*bbq*/ /*whodoesthis*/' }
    },
    unquoted: 'test',
    value: 'te/*inside-value*/st'
  }
}
```

## `Processor`

### `ProcessorOptions`

* `lossless` - When `true`, whitespace is preserved. Defaults to `true`.
* `updateSelector` - When `true`, if any processor methods are passed a postcss
  `Rule` node instead of a string, then that Rule's selector is updated
  with the results of the processing. Defaults to `true`.

### `process|processSync(selectors, [options])`

Processes the `selectors`, returning a string from the result of processing.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

**Example:**

```js
const parser = require("postcss-selector-parser");
const processor = parser();

let result = processor.processSync(' .class');
console.log(result);
// =>  .class

// Asynchronous operation
let promise = processor.process(' .class').then(result => {
    console.log(result)
    // => .class
});

// To have the parser normalize whitespace values, utilize the options
result = processor.processSync('  .class  ', {lossless: false});
console.log(result);
// => .class

// For better syntax errors, pass a PostCSS Rule node.
const postcss = require('postcss');
rule = postcss.rule({selector: ' #foo    > a,  .class  '});
processor.process(rule, {lossless: false, updateSelector: true}).then(result => {
    console.log(result);
    // => #foo>a,.class
    console.log("rule:", rule.selector);
    // => rule: #foo>a,.class
})
```

Arguments:

* `selectors (string|postcss.Rule)`: Either a selector string or a PostCSS Rule
  node.
* `[options] (object)`: Process options


### `ast|astSync(selectors, [options])`

Like `process()` and `processSync()` but after
processing the `selectors` these methods return the `Root` node of the result
instead of a string.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

### `transform|transformSync(selectors, [options])`

Like `process()` and `processSync()` but after
processing the `selectors` these methods return the value returned by the
processor callback.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

### Error Handling Within Selector Processors

The root node passed to the selector processor callback
has a method `error(message, options)` that returns an
error object. This method should always be used to raise
errors relating to the syntax of selectors. The options
to this method are passed to postcss's error constructor
([documentation](http://postcss.org/api/#container-error)).

#### Async Error Example

```js
let processor = (root) => {
    return new Promise((resolve, reject) => {
        root.walkClasses((classNode) => {
            if (/^(.*)[-_]/.test(classNode.value)) {
                let msg = "classes may not have underscores or dashes in them";
                reject(root.error(msg, {
                    index: classNode.sourceIndex + RegExp.$1.length + 1,
                    word: classNode.value
                }));
            }
        });
        resolve();
    });
};

const postcss = require("postcss");
const parser = require("postcss-selector-parser");
const selectorProcessor = parser(processor);
const plugin = postcss.plugin('classValidator', (options) => {
    return (root) => {
        let promises = [];
        root.walkRules(rule => {
            promises.push(selectorProcessor.process(rule));
        });
        return Promise.all(promises);
    };
});
postcss(plugin()).process(`
.foo-bar {
  color: red;
}
`.trim(), {from: 'test.css'}).catch((e) => console.error(e.toString()));

// CssSyntaxError: classValidator: ./test.css:1:5: classes may not have underscores or dashes in them
//
// > 1 | .foo-bar {
//     |     ^
//   2 |   color: red;
//   3 | }
```

#### Synchronous Error Example

```js
let processor = (root) => {
    root.walkClasses((classNode) => {
        if (/.*[-_]/.test(classNode.value)) {
            let msg = "classes may not have underscores or dashes in them";
            throw root.error(msg, {
                index: classNode.sourceIndex,
                word: classNode.value
            });
        }
    });
};

const postcss = require("postcss");
const parser = require("postcss-selector-parser");
const selectorProcessor = parser(processor);
const plugin = postcss.plugin('classValidator', (options) => {
    return (root) => {
        root.walkRules(rule => {
            selectorProcessor.processSync(rule);
        });
    };
});
postcss(plugin()).process(`
.foo-bar {
  color: red;
}
`.trim(), {from: 'test.css'}).catch((e) => console.error(e.toString()));

// CssSyntaxError: classValidator: ./test.css:1:5: classes may not have underscores or dashes in them
//
// > 1 | .foo-bar {
//     |     ^
//   2 |   color: red;
//   3 | }
```


---

# 7.1.0

- feat: insert(Before|After) support multiple new node

# 7.0.0

- Feat: make insertions during iteration safe (major)

# 6.1.2

- Fixed: erroneous trailing combinators in pseudos

# 6.1.1

- Fixed: improve typings of constructor helpers (#292)

# 6.1.0

- Feature: add `sourceIndex` to `Selector` nodes (#290)

# 6.0.16

- Fixed: add missing `index` argument to `each`/`walk` callback types (#289)

# 6.0.15

- Fixed: Node#prev and Node#next type for the first/last node

# 6.0.14

- Fixed: type definitions

# 6.0.13

- Fixed: throw on unexpected pipe symbols

# 6.0.12

- Fixed: `clone` arguments should be optional

# 6.0.11

- Fixed: parse attribute case insensitivity flag

# 6.0.10

- Fixed: `isPseudoElement()` supports `:first-letter` and `:first-line`

# 6.0.9

- Fixed: `Combinator.raws` property type

# 6.0.8

- Fixed: reduced size

# 6.0.7

- Fixed: parse animation percents

# 6.0.6

- Fixed: parse quoted attributes containing a newline correctly

# 6.0.5

- Perf: rework unesc for a 63+% performance boost

# 6.0.4

- Fixed: ts errors

# 6.0.3

- Fixed: replace node built-in "util" module with "util-deprecate"
- Fixed: handle uppercase pseudo elements
- Fixed: do not create invalid combinator before comment

# 6.0.2

- Fixed an issue with parsing and stringifying an empty attribute value

# 6.0.1

- Fixed an issue with unicode surrogate pair parsing

# 6.0.0

- Updated: `cssesc` to 3.0.0 (major)
- Fixed: Issues with escaped `id` and `class` selectors

# 5.0.0

- Allow escaped dot within class name.
- Update PostCSS to 7.0.7 (patch)

# 5.0.0-rc.4

- Fixed an issue where comments immediately after an insensitive (in attribute)
  were not parsed correctly.
- Updated `cssesc` to 2.0.0 (major).
- Removed outdated integration tests.
- Added tests for custom selectors, tags with attributes, the universal
  selector with pseudos, and tokens after combinators.

# 5.0.0-rc.1

To ease adoption of the v5.0 release, we have relaxed the node version
check performed by npm at installation time to allow for node 4, which
remains officially unsupported, but likely to continue working for the
time being.

# 5.0.0-rc.0

This release has **BREAKING CHANGES** that were required to fix regressions
in 4.0.0 and to make the Combinator Node API consistent for all combinator
types. Please read carefully.

## Summary of Changes

* The way a descendent combinator that isn't a single space character (E.g. `.a  .b`) is stored in the AST has changed.
* Named Combinators (E.g. `.a /for/ .b`) are now properly parsed as a combinator.
* It is now possible to look up a node based on the source location of a character in that node and to query nodes if they contain some character.
* Several bug fixes that caused the parser to hang and run out of memory when a `/` was encountered have been fixed.
* The minimum supported version of Node is now `v6.0.0`.

### Changes to the Descendent Combinator

In prior releases, the value of a descendant combinator with multiple spaces included all the spaces.

* `.a   .b`: Extra spaces are now stored as space before.
  - Old & Busted:
    - `combinator.value === "   "`
  - New hotness:
    - `combinator.value === " " && combinator.spaces.before === "  "`
* `.a   /*comment*/.b`: A comment at the end of the combinator causes extra space to become after space.
  - Old & Busted:
    - `combinator.value === "   "`
    - `combinator.raws.value === "   /*comment/"`
  - New hotness:
    - `combinator.value === " "`
    - `combinator.spaces.after === "  "`
    - `combinator.raws.spaces.after === "  /*comment*/"`
* `.a<newline>.b`: whitespace that doesn't start or end with a single space character is stored as a raw value.
  - Old & Busted:
    - `combinator.value === "\n"`
    - `combinator.raws.value === undefined`
  - New hotness:
    - `combinator.value === " "`
    - `combinator.raws.value === "\n"`

### Support for "Named Combinators"

Although, nonstandard and unlikely to ever become a standard, combinators like `/deep/` and `/for/` are now properly supported.

Because they've been taken off the standardization track, there is no spec-official name for combinators of the form `/<ident>/`. However, I talked to [Tab Atkins](https://twitter.com/tabatkins) and we agreed to call them "named combinators" so now they are called that.

Before this release such named combinators were parsed without intention and generated three nodes of type `"tag"` where the first and last nodes had a value of `"/"`.

* `.a /for/ .b` is parsed as a combinator.
  - Old & Busted:
    - `root.nodes[0].nodes[1].type === "tag"`
    - `root.nodes[0].nodes[1].value === "/"`
  - New hotness:
    - `root.nodes[0].nodes[1].type === "combinator"`
    - `root.nodes[0].nodes[1].value === "/for/"`
* `.a /F\6fR/ .b` escapes are handled and uppercase is normalized.
  - Old & Busted:
    - `root.nodes[0].nodes[2].type === "tag"`
    - `root.nodes[0].nodes[2].value === "F\\6fR"`
  - New hotness:
    - `root.nodes[0].nodes[1].type === "combinator"`
    - `root.nodes[0].nodes[1].value === "/for/"`
    - `root.nodes[0].nodes[1].raws.value === "/F\\6fR/"`

### Source position checks and lookups

A new API was added to look up a node based on the source location.

```js
const selectorParser = require("postcss-selector-parser");
// You can find the most specific node for any given character
let combinator = selectorParser.astSync(".a > .b").atPosition(1,4);
combinator.toString() === " > ";
// You can check if a node includes a specific character
// Whitespace surrounding the node that is owned by that node
// is included in the check.
[2,3,4,5,6].map(column => combinator.isAtPosition(1, column));
// => [false, true, true, true, false]
```

# 4.0.0

This release has **BREAKING CHANGES** that were required to fix bugs regarding values with escape sequences. Please read carefully.

* **Identifiers with escapes** - CSS escape sequences are now hidden from the public API by default.
  The normal value of a node like a class name or ID, or an aspect of a node such as attribute
  selector's value, is unescaped. Escapes representing Non-ascii characters are unescaped into
  unicode characters. For example: `bu\tton, .\31 00, #i\2764\FE0Fu, [attr="value is \"quoted\""]`
  will parse respectively to the values `button`, `100`, `i❤️u`, `value is "quoted"`.
  The original escape sequences for these values can be found in the corresponding property name
  in `node.raws`. Where possible, deprecation warnings were added, but the nature
  of escape handling makes it impossible to detect what is escaped or not. Our expectation is
  that most users are neither expecting nor handling escape sequences in their use of this library,
  and so for them, this is a bug fix. Users who are taking care to handle escapes correctly can
  now update their code to remove the escape handling and let us do it for them.

* **Mutating values with escapes** - When you make an update to a node property that has escape handling
  The value is assumed to be unescaped, and any special characters are escaped automatically and
  the corresponding `raws` value is immediately updated. This can result in changes to the original
  escape format. Where the exact value of the escape sequence is important there are methods that
  allow both values to be set in conjunction. There are a number of new convenience methods for
  manipulating values that involve escapes, especially for attributes values where the quote mark
  is involved. See https://github.com/postcss/postcss-selector-parser/pull/133 for an extensive
  write-up on these changes.


**Upgrade/API Example**

In `3.x` there was no unescape handling and internal consistency of several properties was the caller's job to maintain. It was very easy for the developer
to create a CSS file that did not parse correctly when some types of values
were in use.

```js
const selectorParser = require("postcss-selector-parser");
let attr = selectorParser.attribute({attribute: "id", operator: "=", value: "a-value"});
attr.value; // => "a-value"
attr.toString(); // => [id=a-value]
// Add quotes to an attribute's value.
// All these values have to be set by the caller to be consistent:
// no internal consistency is maintained.
attr.raws.unquoted = attr.value
attr.value = "'" + attr.value + "'";
attr.value; // => "'a-value'"
attr.quoted = true;
attr.toString();  // => "[id='a-value']"
```

In `4.0` there is a convenient API for setting and mutating values
that may need escaping. Especially for attributes.

```js
const selectorParser = require("postcss-selector-parser");

// The constructor requires you specify the exact escape sequence
let className = selectorParser.className({value: "illegal class name", raws: {value: "illegal\\ class\\ name"}});
className.toString(); // => '.illegal\\ class\\ name'

// So it's better to set the value as a property
className = selectorParser.className();
// Most properties that deal with identifiers work like this
className.value = "escape for me";
className.value; // => 'escape for me'
className.toString(); // => '.escape\\ for\\ me'

// emoji and all non-ascii are escaped to ensure it works in every css file.
className.value = "😱🦄😍";
className.value; // => '😱🦄😍'
className.toString(); // => '.\\1F631\\1F984\\1F60D'

// you can control the escape sequence if you want, or do bad bad things
className.setPropertyAndEscape('value', 'xxxx', 'yyyy');
className.value; // => "xxxx"
className.toString(); // => ".yyyy"

// Pass a value directly through to the css output without escaping it. 
className.setPropertyWithoutEscape('value', '$REPLACE_ME$');
className.value; // => "$REPLACE_ME$"
className.toString(); // => ".$REPLACE_ME$"

// The biggest changes are to the Attribute class
// passing quoteMark explicitly is required to avoid a deprecation warning.
let attr = selectorParser.attribute({attribute: "id", operator: "=", value: "a-value", quoteMark: null});
attr.toString(); // => "[id=a-value]"
// Get the value with quotes on it and any necessary escapes.
// This is the same as reading attr.value in 3.x.
attr.getQuotedValue(); // => "a-value";
attr.quoteMark; // => null

// Add quotes to an attribute's value.
attr.quoteMark = "'"; // This is all that's required.
attr.toString(); // => "[id='a-value']"
attr.quoted; // => true
// The value is still the same, only the quotes have changed.
attr.value; // => a-value
attr.getQuotedValue(); // => "'a-value'";

// deprecated assignment, no warning because there's no escapes
attr.value = "new-value";
// no quote mark is needed so it is removed
attr.getQuotedValue(); // => "new-value";

// deprecated assignment, 
attr.value = "\"a 'single quoted' value\"";
// > (node:27859) DeprecationWarning: Assigning an attribute a value containing characters that might need to be escaped is deprecated. Call attribute.setValue() instead.
attr.getQuotedValue(); // => '"a \'single quoted\' value"';
// quote mark inferred from first and last characters.
attr.quoteMark; // => '"'

// setValue takes options to make manipulating the value simple.
attr.setValue('foo', {smart: true});
// foo doesn't require any escapes or quotes.
attr.toString(); // => '[id=foo]'
attr.quoteMark; // => null 

// An explicit quote mark can be specified
attr.setValue('foo', {quoteMark: '"'});
attr.toString(); // => '[id="foo"]'

// preserves quote mark by default
attr.setValue('bar');
attr.toString(); // => '[id="bar"]'
attr.quoteMark = null;
attr.toString(); // => '[id=bar]'

// with no arguments, it preserves quote mark even when it's not a great idea
attr.setValue('a value \n that should be quoted');
attr.toString(); // => '[id=a\\ value\\ \\A\\ that\\ should\\ be\\ quoted]'

// smart preservation with a specified default
attr.setValue('a value \n that should be quoted', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => "[id='a value \\A  that should be quoted']"
attr.quoteMark = '"';
// => '[id="a value \\A  that should be quoted"]'

// this keeps double quotes because it wants to quote the value and the existing value has double quotes.
attr.setValue('this should be quoted', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => '[id="this should be quoted"]'

// picks single quotes because the value has double quotes
attr.setValue('a "double quoted" value', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => "[id='a "double quoted" value']"

// setPropertyAndEscape lets you do anything you want. Even things that are a bad idea and illegal.
attr.setPropertyAndEscape('value', 'xxxx', 'the password is 42');
attr.value; // => "xxxx"
attr.toString(); // => "[id=the password is 42]"

// Pass a value directly through to the css output without escaping it. 
attr.setPropertyWithoutEscape('value', '$REPLACEMENT$');
attr.value; // => "$REPLACEMENT$"
attr.toString(); // => "[id=$REPLACEMENT$]"
```

# 3.1.2

* Fix: Removed dot-prop dependency since it's no longer written in es5.

# 3.1.1

* Fix: typescript definitions weren't in the published package.

# 3.1.0

* Fixed numerous bugs in attribute nodes relating to the handling of comments
  and whitespace. There's significant changes to `attrNode.spaces` and `attrNode.raws` since the `3.0.0` release.
* Added `Attribute#offsetOf(part)` to get the offset location of
  attribute parts like `"operator"` and `"value"`. This is most
  often added to `Attribute#sourceIndex` for error reporting.

# 3.0.0

## Breaking changes

* Some tweaks to the tokenizer/attribute selector parsing mean that whitespace
  locations might be slightly different to the 2.x code.
* Better attribute selector parsing with more validation; postcss-selector-parser
  no longer uses regular expressions to parse attribute selectors.
* Added an async API (thanks to @jacobp100); the default `process` API is now
  async, and the sync API is now accessed through `processSync` instead.
* `process()` and `processSync()` now return a string instead of the Processor
  instance.
* Tweaks handling of Less interpolation (thanks to @jwilsson).
* Removes support for Node 0.12.

## Other changes

* `ast()` and `astSync()` methods have been added to the `Processor`. These
  return the `Root` node of the selectors after processing them.
* `transform()` and `transformSync()` methods have been added to the
  `Processor`. These return the value returned by the processor callback
  after processing the selectors.
* Set the parent when inserting a node (thanks to @chriseppstein).
* Correctly adjust indices when using insertBefore/insertAfter (thanks to @tivac).
* Fixes handling of namespaces with qualified tag selectors.
* `process`, `ast` and `transform` (and their sync variants) now accept a
  `postcss` rule node. When provided, better errors are generated and selector
  processing is automatically set back to the rule selector (unless the `updateSelector` option is set to `false`.)
* Now more memory efficient when tokenizing selectors.

### Upgrade hints

The pattern of:

`rule.selector = processor.process(rule.selector).result.toString();`

is now:

`processor.processSync(rule)`

# 2.2.3

* Resolves an issue where the parser would not reduce multiple spaces between an
  ampersand and another simple selector in lossy mode (thanks to @adam-26).

# 2.2.2

* No longer hangs on an unescaped semicolon; instead the parser will throw
  an exception for these cases.

# 2.2.1

* Allows a consumer to specify whitespace tokens when creating a new Node
  (thanks to @Semigradsky).

# 2.2.0

* Added a new option to normalize whitespace when parsing the selector string
  (thanks to @adam-26).

# 2.1.1

* Better unquoted value handling within attribute selectors
  (thanks to @evilebottnawi).

# 2.1.0

* Added: Use string constants for all node types & expose them on the main
  parser instance (thanks to @Aweary).

# 2.0.0

This release contains the following breaking changes:

* Renamed all `eachInside` iterators to `walk`. For example, `eachTag` is now
  `walkTags`, and `eachInside` is now `walk`.
* Renamed `Node#removeSelf()` to `Node#remove()`.
* Renamed `Container#remove()` to `Container#removeChild()`.
* Renamed `Node#raw` to `Node#raws` (thanks to @davidtheclark).
* Now parses `&` as the *nesting* selector, rather than a *tag* selector.
* Fixes misinterpretation of Sass interpolation (e.g. `#{foo}`) as an
  id selector (thanks to @davidtheclark).

and;

* Fixes parsing of attribute selectors with equals signs in them
  (e.g. `[data-attr="foo=bar"]`) (thanks to @montmanu).
* Adds `quoted` and `raw.unquoted` properties to attribute nodes
  (thanks to @davidtheclark).

# 1.3.3

* Fixes an infinite loop on `)` and `]` tokens when they had no opening pairs.
  Now postcss-selector-parser will throw when it encounters these lone tokens.

# 1.3.2

* Now uses plain integers rather than `str.charCodeAt(0)` for compiled builds.

# 1.3.1

* Update flatten to v1.x (thanks to @shinnn).

# 1.3.0

* Adds a new node type, `String`, to fix a crash on selectors such as
  `foo:bar("test")`.

# 1.2.1

* Fixes a crash when the parser encountered a trailing combinator.

# 1.2.0

* A more descriptive error is thrown when the parser expects to find a
  pseudo-class/pseudo-element (thanks to @ashelley).
* Adds support for line/column locations for selector nodes, as well as a
  `Node#sourceIndex` method (thanks to @davidtheclark).

# 1.1.4

* Fixes a crash when a selector started with a `>` combinator. The module will
  now no longer throw if a selector has a leading/trailing combinator node.

# 1.1.3

* Fixes a crash on `@` tokens.

# 1.1.2

* Fixes an infinite loop caused by using parentheses in a non-pseudo element
  context.

# 1.1.1

* Fixes a crash when a backslash ended a selector string.

# 1.1.0

* Adds support for replacing multiple nodes at once with `replaceWith`
  (thanks to @jonathantneal).
* Parser no longer throws on sequential IDs and trailing commas, to support
  parsing of selector hacks.

# 1.0.1

* Fixes using `insertAfter` and `insertBefore` during iteration.

# 1.0.0

* Adds `clone` and `replaceWith` methods to nodes.
* Adds `insertBefore` and `insertAfter` to containers.
* Stabilises API.

# 0.0.5

* Fixes crash on extra whitespace inside a pseudo selector's parentheses.
* Adds sort function to the container class.
* Enables the parser to pass its input through without transforming.
* Iteration-safe `each` and `eachInside`.

# 0.0.4

* Tidy up redundant duplication.
* Fixes a bug where the parser would loop infinitely on universal selectors
  inside pseudo selectors.
* Adds `length` getter and `eachInside`, `map`, `reduce` to the container class.
* When a selector has been removed from the tree, the root node will no longer
  cast it to a string.
* Adds node type iterators to the container class (e.g. `eachComment`).
* Adds filter function to the container class.
* Adds split function to the container class.
* Create new node types by doing `parser.id(opts)` etc.
* Adds support for pseudo classes anywhere in the selector.

# 0.0.3

* Adds `next` and `prev` to the node class.
* Adds `first` and `last` getters to the container class.
* Adds `every` and `some` iterators to the container class.
* Add `empty` alias for `removeAll`.
* Combinators are now types of node.
* Fixes the at method so that it is not an alias for `index`.
* Tidy up creation of new nodes in the parser.
* Refactors how namespaces are handled for consistency & less redundant code.
* Refactors AST to use `nodes` exclusively, and eliminates excessive nesting.
* Fixes nested pseudo parsing.
* Fixes whitespace parsing.

# 0.0.2

* Adds support for namespace selectors.
* Adds support for selectors joined by escaped spaces - such as `.\31\ 0`.

# 0.0.1

* Initial release.


---

# postcss-selector-parser [![test](https://github.com/postcss/postcss-selector-parser/actions/workflows/test.yml/badge.svg)](https://github.com/postcss/postcss-selector-parser/actions/workflows/test.yml)

> Selector parser with built in methods for working with selector strings.

## Install

With [npm](https://npmjs.com/package/postcss-selector-parser) do:

```
npm install postcss-selector-parser
```

## Quick Start

```js
const parser = require('postcss-selector-parser');
const transform = selectors => {
    selectors.walk(selector => {
        // do something with the selector
        console.log(String(selector))
    });
};

const transformed = parser(transform).processSync('h1, h2, h3');
```

To normalize selector whitespace:

```js
const parser = require('postcss-selector-parser');
const normalized = parser().processSync('h1, h2, h3', {lossless: false});
// -> h1,h2,h3
```

Async support is provided through `parser.process` and will resolve a Promise
with the resulting selector string.

## API

Please see [API.md](API.md).

## Credits

* Huge thanks to Andrey Sitnik (@ai) for work on PostCSS which helped
  accelerate this module's development.

## License

MIT


---

<div align="center">
  <img width="180" height="180" vspace="20"
    src="https://cdn.worldvectorlogo.com/logos/css-3.svg">
  <a href="https://github.com/webpack/webpack">
    <img width="200" height="200"
      src="https://webpack.js.org/assets/icon-square-big.svg">
  </a>
</div>

[![npm][npm]][npm-url]
[![node][node]][node-url]
[![tests][tests]][tests-url]
[![coverage][cover]][cover-url]
[![discussion][discussion]][discussion-url]
[![size][size]][size-url]

# css-loader

The `css-loader` interprets `@import` and `url()` like `import/require()` and will resolve them.

## Getting Started

> **Warning**
>
> To use the latest version of css-loader, webpack@5 is required

To begin, you'll need to install `css-loader`:

```console
npm install --save-dev css-loader
```

or

```console
yarn add -D css-loader
```

or

```console
pnpm add -D css-loader
```

Then add the plugin to your `webpack` config. For example:

**file.js**

```js
import css from "file.css";
```

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: ["style-loader", "css-loader"],
      },
    ],
  },
};
```

And run `webpack` via your preferred method.

If, for one reason or another, you need to extract CSS as a file (i.e. do not store CSS in a JS module) you might want to check out the [recommend example](https://github.com/webpack-contrib/css-loader#recommend).

## Options

- **[`url`](#url)**
- **[`import`](#import)**
- **[`modules`](#modules)**
- **[`sourceMap`](#sourcemap)**
- **[`importLoaders`](#importloaders)**
- **[`esModule`](#esmodule)**
- **[`exportType`](#exporttype)**

### `url`

Type:

```ts
type url =
  | boolean
  | {
      filter: (url: string, resourcePath: string) => boolean;
    };
```

Default: `true`

Allow to enable/disables handling the CSS functions `url` and `image-set`.
If set to `false`, `css-loader` will not parse any paths specified in `url` or `image-set`.
A function can also be passed to control this behavior dynamically based on the path to the asset.
Starting with version [4.0.0](https://github.com/webpack-contrib/css-loader/blob/master/CHANGELOG.md#400-2020-07-25), absolute paths are parsed based on the server root.

Examples resolutions:

```js
url(image.png) => require('./image.png')
url('image.png') => require('./image.png')
url(./image.png) => require('./image.png')
url('./image.png') => require('./image.png')
url('http://dontwritehorriblecode.com/2112.png') => require('http://dontwritehorriblecode.com/2112.png')
image-set(url('image2x.png') 1x, url('image1x.png') 2x) => require('./image1x.png') and require('./image2x.png')
```

To import assets from a `node_modules` path (include `resolve.modules`) and for `alias`, prefix it with a `~`:

```js
url(~module/image.png) => require('module/image.png')
url('~module/image.png') => require('module/image.png')
url(~aliasDirectory/image.png) => require('otherDirectory/image.png')
```

#### `boolean`

Enable/disable `url()` resolving.

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          url: true,
        },
      },
    ],
  },
};
```

#### `object`

Allow to filter `url()`. All filtered `url()` will not be resolved (left in the code as they were written).

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          url: {
            filter: (url, resourcePath) => {
              // resourcePath - path to css file

              // Don't handle `img.png` urls
              if (url.includes("img.png")) {
                return false;
              }

              // Don't handle images under root-relative /external_images/
              if (/^\/external_images\//.test(path)) {
                return false;
              }

              return true;
            },
          },
        },
      },
    ],
  },
};
```

### `import`

Type:

<!-- use other name to prettify since import is reserved keyword -->

```ts
type importFn =
  | boolean
  | {
      filter: (
        url: string,
        media: string,
        resourcePath: string,
        supports?: string,
        layer?: string
      ) => boolean;
    };
```

Default: `true`

Allows to enables/disables `@import` at-rules handling.
Control `@import` resolving. Absolute urls in `@import` will be moved in runtime code.

Examples resolutions:

```
@import 'style.css' => require('./style.css')
@import url(style.css) => require('./style.css')
@import url('style.css') => require('./style.css')
@import './style.css' => require('./style.css')
@import url(./style.css) => require('./style.css')
@import url('./style.css') => require('./style.css')
@import url('http://dontwritehorriblecode.com/style.css') => @import url('http://dontwritehorriblecode.com/style.css') in runtime
```

To import styles from a `node_modules` path (include `resolve.modules`) and for `alias`, prefix it with a `~`:

```
@import url(~module/style.css) => require('module/style.css')
@import url('~module/style.css') => require('module/style.css')
@import url(~aliasDirectory/style.css) => require('otherDirectory/style.css')
```

#### `boolean`

Enable/disable `@import` resolving.

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          import: true,
        },
      },
    ],
  },
};
```

#### `object`

##### `filter`

Type:

```ts
type filter = (url: string, media: string, resourcePath: string) => boolean;
```

Default: `undefined`

Allow to filter `@import`. All filtered `@import` will not be resolved (left in the code as they were written).

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          import: {
            filter: (url, media, resourcePath) => {
              // resourcePath - path to css file

              // Don't handle `style.css` import
              if (url.includes("style.css")) {
                return false;
              }

              return true;
            },
          },
        },
      },
    ],
  },
};
```

### `modules`

Type:

```ts
type modules =
  | boolean
  | "local"
  | "global"
  | "pure"
  | "icss"
  | {
      auto: boolean | regExp | ((resourcePath: string) => boolean);
      mode:
        | "local"
        | "global"
        | "pure"
        | "icss"
        | ((resourcePath) => "local" | "global" | "pure" | "icss");
      localIdentName: string;
      localIdentContext: string;
      localIdentHashSalt: string;
      localIdentHashFunction: string;
      localIdentHashDigest: string;
      localIdentRegExp: string | regExp;
      getLocalIdent: (
        context: LoaderContext,
        localIdentName: string,
        localName: string
      ) => string;
      namedExport: boolean;
      exportGlobals: boolean;
      exportLocalsConvention:
        | "asIs"
        | "camelCase"
        | "camelCaseOnly"
        | "dashes"
        | "dashesOnly"
        | ((name: string) => string);
      exportOnlyLocals: boolean;
    };
```

Default: `undefined`

Allows to enable/disable CSS Modules or ICSS and setup configuration:

- `undefined` - enable CSS modules for all files matching `/\.module\.\w+$/i.test(filename)` and `/\.icss\.\w+$/i.test(filename)` regexp.
- `true` - enable CSS modules for all files.
- `false` - disables CSS Modules for all files.
- `string` - disables CSS Modules for all files and set the `mode` option, more information you can read [here](https://github.com/webpack-contrib/css-loader#mode)
- `object` - enable CSS modules for all files, if `modules.auto` option is not specified, otherwise the `modules.auto` option will determine whether if it is CSS modules or not, more information you can read [here](https://github.com/webpack-contrib/css-loader#auto)

The `modules` option enables/disables the **[CSS Modules](https://github.com/css-modules/css-modules)** specification and setup basic behaviour.

Using `false` value increase performance because we avoid parsing **CSS Modules** features, it will be useful for developers who use vanilla css or use other technologies.

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: true,
        },
      },
    ],
  },
};
```

#### `Features`

##### `Scope`

Using `local` value requires you to specify `:global` classes.
Using `global` value requires you to specify `:local` classes.
Using `pure` value requires selectors must contain at least one local class or id.

You can find more information [here](https://github.com/css-modules/css-modules).

Styles can be locally scoped to avoid globally scoping styles.

The syntax `:local(.className)` can be used to declare `className` in the local scope. The local identifiers are exported by the module.

With `:local` (without brackets) local mode can be switched on for this selector.
The `:global(.className)` notation can be used to declare an explicit global selector.
With `:global` (without brackets) global mode can be switched on for this selector.

The loader replaces local selectors with unique identifiers. The chosen unique identifiers are exported by the module.

```css
:local(.className) {
  background: red;
}
:local .className {
  color: green;
}
:local(.className .subClass) {
  color: green;
}
:local .className .subClass :global(.global-class-name) {
  color: blue;
}
```

```css
._23_aKvs-b8bW2Vg3fwHozO {
  background: red;
}
._23_aKvs-b8bW2Vg3fwHozO {
  color: green;
}
._23_aKvs-b8bW2Vg3fwHozO ._13LGdX8RMStbBE9w-t0gZ1 {
  color: green;
}
._23_aKvs-b8bW2Vg3fwHozO ._13LGdX8RMStbBE9w-t0gZ1 .global-class-name {
  color: blue;
}
```

> **Note**
>
> Identifiers are exported

```js
exports.locals = {
  className: "_23_aKvs-b8bW2Vg3fwHozO",
  subClass: "_13LGdX8RMStbBE9w-t0gZ1",
};
```

CamelCase is recommended for local selectors. They are easier to use within the imported JS module.

You can use `:local(#someId)`, but this is not recommended. Use classes instead of ids.

##### `Composing`

When declaring a local classname you can compose a local class from another local classname.

```css
:local(.className) {
  background: red;
  color: yellow;
}

:local(.subClass) {
  composes: className;
  background: blue;
}
```

This doesn't result in any change to the CSS itself but exports multiple classnames.

```js
exports.locals = {
  className: "_23_aKvs-b8bW2Vg3fwHozO",
  subClass: "_13LGdX8RMStbBE9w-t0gZ1 _23_aKvs-b8bW2Vg3fwHozO",
};
```

```css
._23_aKvs-b8bW2Vg3fwHozO {
  background: red;
  color: yellow;
}

._13LGdX8RMStbBE9w-t0gZ1 {
  background: blue;
}
```

##### `Importing`

To import a local classname from another module.

> **Note**
>
> We strongly recommend that you specify the extension when importing a file, since it is possible to import a file with any extension and it is not known in advance which file to use.

```css
:local(.continueButton) {
  composes: button from "library/button.css";
  background: red;
}
```

```css
:local(.nameEdit) {
  composes: edit highlight from "./edit.css";
  background: red;
}
```

To import from multiple modules use multiple `composes:` rules.

```css
:local(.className) {
  composes: edit highlight from "./edit.css", button from "module/button.css", classFromThisModule;
  background: red;
}
```

or

```css
:local(.className) {
  composes: edit highlight from "./edit.css";
  composes: button from "module/button.css";
  composes: classFromThisModule;
  background: red;
}
```

##### `Values`

You can use `@value` to specific values to be reused throughout a document.

We recommend use prefix `v-` for values, `s-` for selectors and `m-` for media at-rules.

```css
@value v-primary: #BF4040;
@value s-black: black-selector;
@value m-large: (min-width: 960px);

.header {
  color: v-primary;
  padding: 0 10px;
}

.s-black {
  color: black;
}

@media m-large {
  .header {
    padding: 0 20px;
  }
}
```

#### `boolean`

Enable **CSS Modules** features.

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: true,
        },
      },
    ],
  },
};
```

#### `string`

Enable **CSS Modules** features and setup `mode`.

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          // Using `local` value has same effect like using `modules: true`
          modules: "global",
        },
      },
    ],
  },
};
```

#### `object`

Enable **CSS Modules** features and setup options for them.

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: {
            mode: "local",
            auto: true,
            exportGlobals: true,
            localIdentName: "[path][name]__[local]--[hash:base64:5]",
            localIdentContext: path.resolve(__dirname, "src"),
            localIdentHashSalt: "my-custom-hash",
            namedExport: true,
            exportLocalsConvention: "camelCase",
            exportOnlyLocals: false,
          },
        },
      },
    ],
  },
};
```

##### `auto`

Type:

```ts
type auto =
  | boolean
  | regExp
  | ((
      resourcePath: string,
      resourceQuery: string,
      resourceFragment: string
    ) => boolean);
```

Default: `undefined`

Allows auto enable CSS modules/ICSS based on the filename, query or fragment when `modules` option is object.

Possible values:

- `undefined` - enable CSS modules for all files.
- `true` - enable CSS modules for all files matching `/\.module\.\w+$/i.test(filename)` and `/\.icss\.\w+$/i.test(filename)` regexp.
- `false` - disables CSS Modules.
- `RegExp` - enable CSS modules for all files matching `/RegExp/i.test(filename)` regexp.
- `function` - enable CSS Modules for files based on the filename satisfying your filter function check.

###### `boolean`

Possible values:

- `true` - enables CSS modules or interoperable CSS format, sets the [`modules.mode`](#mode) option to `local` value for all files which satisfy `/\.module(s)?\.\w+$/i.test(filename)` condition or sets the [`modules.mode`](#mode) option to `icss` value for all files which satisfy `/\.icss\.\w+$/i.test(filename)` condition
- `false` - disables CSS modules or interoperable CSS format based on filename

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: {
            auto: true,
          },
        },
      },
    ],
  },
};
```

###### `RegExp`

Enable CSS modules for files based on the filename satisfying your regex check.

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: {
            auto: /\.custom-module\.\w+$/i,
          },
        },
      },
    ],
  },
};
```

###### `function`

Enable CSS modules for files based on the filename, query or fragment satisfying your filter function check.

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: {
            auto: (resourcePath, resourceQuery, resourceFragment) => {
              return resourcePath.endsWith(".custom-module.css");
            },
          },
        },
      },
    ],
  },
};
```

##### `mode`

Type:

```ts
type mode =
  | "local"
  | "global"
  | "pure"
  | "icss"
  | ((
      resourcePath: string,
      resourceQuery: string,
      resourceFragment: string
    ) => "local" | "global" | "pure" | "icss");
```

Default: `'local'`

Setup `mode` option. You can omit the value when you want `local` mode.

Controls the level of compilation applied to the input styles.

The `local`, `global`, and `pure` handles `class` and `id` scoping and `@value` values.
The `icss` will only compile the low level `Interoperable CSS` format for declaring `:import` and `:export` dependencies between CSS and other languages.

ICSS underpins CSS Module support, and provides a low level syntax for other tools to implement CSS-module variations of their own.

###### `string`

Possible values - `local`, `global`, `pure`, and `icss`.

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: {
            mode: "global",
          },
        },
      },
    ],
  },
};
```

###### `function`

Allows set different values for the `mode` option based on the filename, query or fragment.

Possible return values - `local`, `global`, `pure` and `icss`.

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: {
            // Callback must return "local", "global", or "pure" values
            mode: (resourcePath, resourceQuery, resourceFragment) => {
              if (/pure.css$/i.test(resourcePath)) {
                return "pure";
              }

              if (/global.css$/i.test(resourcePath)) {
                return "global";
              }

              return "local";
            },
          },
        },
      },
    ],
  },
};
```

##### `localIdentName`

Type:

```ts
type localIdentName = string;
```

Default: `'[hash:base64]'`

Allows to configure the generated local ident name.

For more information on options see:

- [webpack template strings](https://webpack.js.org/configuration/output/#template-strings),
- [output.hashDigest](https://webpack.js.org/configuration/output/#outputhashdigest),
- [output.hashDigestLength](https://webpack.js.org/configuration/output/#outputhashdigestlength),
- [output.hashFunction](https://webpack.js.org/configuration/output/#outputhashfunction),
- [output.hashSalt](https://webpack.js.org/configuration/output/#outputhashsalt).

Supported template strings:

- `[name]` the basename of the resource
- `[folder]` the folder the resource relative to the `compiler.context` option or `modules.localIdentContext` option.
- `[path]` the path of the resource relative to the `compiler.context` option or `modules.localIdentContext` option.
- `[file]` - filename and path.
- `[ext]` - extension with leading `.`.
- `[hash]` - the hash of the string, generated based on `localIdentHashSalt`, `localIdentHashFunction`, `localIdentHashDigest`, `localIdentHashDigestLength`, `localIdentContext`, `resourcePath` and `exportName`
- `[<hashFunction>:hash:<hashDigest>:<hashDigestLength>]` - hash with hash settings.
- `[local]` - original class.

Recommendations:

- use `'[path][name]__[local]'` for development
- use `'[hash:base64]'` for production

The `[local]` placeholder contains original class.

**Note:** all reserved (`<>:"/\|?*`) and control filesystem characters (excluding characters in the `[local]` placeholder) will be converted to `-`.

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: {
            localIdentName: "[path][name]__[local]--[hash:base64:5]",
          },
        },
      },
    ],
  },
};
```

##### `localIdentContext`

Type:

```ts
type localIdentContex = string;
```

Default: `compiler.context`

Allows to redefine basic loader context for local ident name.

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: {
            localIdentContext: path.resolve(__dirname, "src"),
          },
        },
      },
    ],
  },
};
```

##### `localIdentHashSalt`

Type:

```ts
type localIdentHashSalt = string;
```

Default: `undefined`

Allows to add custom hash to generate more unique classes.
For more information see [output.hashSalt](https://webpack.js.org/configuration/output/#outputhashsalt).

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: {
            localIdentHashSalt: "hash",
          },
        },
      },
    ],
  },
};
```

##### `localIdentHashFunction`

Type:

```ts
type localIdentHashFunction = string;
```

Default: `md4`

Allows to specify hash function to generate classes .
For more information see [output.hashFunction](https://webpack.js.org/configuration/output/#outputhashfunction).

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: {
            localIdentHashFunction: "md4",
          },
        },
      },
    ],
  },
};
```

##### `localIdentHashDigest`

Type:

```ts
type localIdentHashDigest = string;
```

Default: `hex`

Allows to specify hash digest to generate classes.
For more information see [output.hashDigest](https://webpack.js.org/configuration/output/#outputhashdigest).

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: {
            localIdentHashDigest: "base64",
          },
        },
      },
    ],
  },
};
```

##### `localIdentHashDigestLength`

Type:

```ts
type localIdentHashDigestLength = number;
```

Default: `20`

Allows to specify hash digest length to generate classes.
For more information see [output.hashDigestLength](https://webpack.js.org/configuration/output/#outputhashdigestlength).

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: {
            localIdentHashDigestLength: 5,
          },
        },
      },
    ],
  },
};
```

##### `hashStrategy`

Type: `'resource-path-and-local-name' | 'minimal-subset'`
Default: `'resource-path-and-local-name'`

Should local name be used when computing the hash.

- `'resource-path-and-local-name'` Both resource path and local name are used when hashing. Each identifier in a module gets its own hash digest, always.
- `'minimal-subset'` Auto detect if identifier names can be omitted from hashing. Use this value to optimize the output for better GZIP or Brotli compression.

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: {
            hashStrategy: "minimal-subset",
          },
        },
      },
    ],
  },
};
```

##### `localIdentRegExp`

Type:

```ts
type localIdentRegExp = string | RegExp;
```

Default: `undefined`

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: {
            localIdentRegExp: /page-(.*)\.css/i,
          },
        },
      },
    ],
  },
};
```

##### `getLocalIdent`

Type:

```ts
type getLocalIdent = (
  context: LoaderContext,
  localIdentName: string,
  localName: string
) => string;
```

Default: `undefined`

Allows to specify a function to generate the classname.
By default we use built-in function to generate a classname.
If the custom function returns `null` or `undefined`, we fallback to the
built-in function to generate the classname.

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: {
            getLocalIdent: (context, localIdentName, localName, options) => {
              return "whatever_random_class_name";
            },
          },
        },
      },
    ],
  },
};
```

##### `namedExport`

Type:

```ts
type namedExport = boolean;
```

Default: `false`

Enables/disables ES modules named export for locals.

> **Warning**
>
> Names of locals are converted to camelcase, i.e. the `exportLocalsConvention` option has
> `camelCaseOnly` value by default. You can set this back to any other valid option but selectors
> which are not valid JavaScript identifiers may run into problems which do not implement the entire
> modules specification.

> **Warning**
>
> It is not allowed to use JavaScript reserved words in css class names unless
> `exportLocalsConvention` is `"asIs"`.

**styles.css**

```css
.foo-baz {
  color: red;
}
.bar {
  color: blue;
}
```

**index.js**

```js
import * as styles from "./styles.css";

console.log(styles.fooBaz, styles.bar);
// or if using `exportLocalsConvention: "asIs"`:
console.log(styles["foo-baz"], styles.bar);
```

You can enable a ES module named export using:

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          esModule: true,
          modules: {
            namedExport: true,
          },
        },
      },
    ],
  },
};
```

To set a custom name for namedExport, can use [`exportLocalsConvention`](#exportLocalsConvention) option as a function.
Example below in the [`examples`](#examples) section.

##### `exportGlobals`

Type:

```ts
type exportsGLobals = boolean;
```

Default: `false`

Allow `css-loader` to export names from global class or id, so you can use that as local name.

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: {
            exportGlobals: true,
          },
        },
      },
    ],
  },
};
```

##### `exportLocalsConvention`

Type:

```ts
type exportLocalsConvention =
  | "asIs"
  | "camelCase"
  | "camelCaseOnly"
  | "dashes"
  | "dashesOnly"
  | ((name: string) => string);
```

Default: based on the `modules.namedExport` option value, if `true` - `camelCaseOnly`, otherwise `asIs`

Style of exported class names.

###### `string`

By default, the exported JSON keys mirror the class names (i.e `asIs` value).

|         Name          |   Type   | Description                                                                                      |
| :-------------------: | :------: | :----------------------------------------------------------------------------------------------- |
|     **`'asIs'`**      | `string` | Class names will be exported as is.                                                              |
|   **`'camelCase'`**   | `string` | Class names will be camelized, the original class name will not to be removed from the locals    |
| **`'camelCaseOnly'`** | `string` | Class names will be camelized, the original class name will be removed from the locals           |
|    **`'dashes'`**     | `string` | Only dashes in class names will be camelized                                                     |
|  **`'dashesOnly'`**   | `string` | Dashes in class names will be camelized, the original class name will be removed from the locals |

**file.css**

```css
.class-name {
}
```

**file.js**

```js
import { className } from "file.css";
```

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: {
            exportLocalsConvention: "camelCase",
          },
        },
      },
    ],
  },
};
```

###### `function`

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: {
            exportLocalsConvention: function (name) {
              return name.replace(/-/g, "_");
            },
          },
        },
      },
    ],
  },
};
```

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: {
            exportLocalsConvention: function (name) {
              return [
                name.replace(/-/g, "_"),
                // dashesCamelCase
                name.replace(/-+(\w)/g, (match, firstLetter) =>
                  firstLetter.toUpperCase()
                ),
              ];
            },
          },
        },
      },
    ],
  },
};
```

##### `exportOnlyLocals`

Type:

```ts
type exportOnlyLocals = boolean;
```

Default: `false`

Export only locals.

**Useful** when you use **css modules** for pre-rendering (for example SSR).
For pre-rendering with `mini-css-extract-plugin` you should use this option instead of `style-loader!css-loader` **in the pre-rendering bundle**.
It doesn't embed CSS but only exports the identifier mappings.

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: {
            exportOnlyLocals: true,
          },
        },
      },
    ],
  },
};
```

### `importLoaders`

Type:

```ts
type importLoaders = number;
```

Default: `0`

Allows to enables/disables or setups number of loaders applied before CSS loader for `@import` at-rules, CSS modules and ICSS imports, i.e. `@import`/`composes`/`@value value from './values.css'`/etc.

The option `importLoaders` allows you to configure how many loaders before `css-loader` should be applied to `@import`ed resources and CSS modules/ICSS imports.

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          "style-loader",
          {
            loader: "css-loader",
            options: {
              importLoaders: 2,
              // 0 => no loaders (default);
              // 1 => postcss-loader;
              // 2 => postcss-loader, sass-loader
            },
          },
          "postcss-loader",
          "sass-loader",
        ],
      },
    ],
  },
};
```

This may change in the future when the module system (i. e. webpack) supports loader matching by origin.

### `sourceMap`

Type:

```ts
type sourceMap = boolean;
```

Default: depends on the `compiler.devtool` value

By default generation of source maps depends on the [`devtool`](https://webpack.js.org/configuration/devtool/) option. All values enable source map generation except `eval` and `false` value.

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          sourceMap: true,
        },
      },
    ],
  },
};
```

### `esModule`

Type:

```ts
type esModule = boolean;
```

Default: `true`

By default, `css-loader` generates JS modules that use the ES modules syntax.
There are some cases in which using ES modules is beneficial, like in the case of [module concatenation](https://webpack.js.org/plugins/module-concatenation-plugin/) and [tree shaking](https://webpack.js.org/guides/tree-shaking/).

You can enable a CommonJS modules syntax using:

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          esModule: false,
        },
      },
    ],
  },
};
```

### `exportType`

Type:

```ts
type exportType = "array" | "string" | "css-style-sheet";
```

Default: `'array'`

Allows exporting styles as array with modules, string or [constructable stylesheet](https://developers.google.com/web/updates/2019/02/constructable-stylesheets) (i.e. [`CSSStyleSheet`](https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleSheet)).
Default value is `'array'`, i.e. loader exports array of modules with specific API which is used in `style-loader` or other.

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        assert: { type: "css" },
        loader: "css-loader",
        options: {
          exportType: "css-style-sheet",
        },
      },
    ],
  },
};
```

**src/index.js**

```js
import sheet from "./styles.css" assert { type: "css" };

document.adoptedStyleSheets = [sheet];
shadowRoot.adoptedStyleSheets = [sheet];
```

#### `'array'`

The default export is array of modules with specific API which is used in `style-loader` or other.

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.(sa|sc|c)ss$/i,
        use: ["style-loader", "css-loader", "postcss-loader", "sass-loader"],
      },
    ],
  },
};
```

**src/index.js**

```js
// `style-loader` applies styles to DOM
import "./styles.css";
```

#### `'string'`

> **Warning**
>
> You should not use [`style-loader`](https://github.com/webpack-contrib/style-loader) or [`mini-css-extract-plugin`](https://github.com/webpack-contrib/mini-css-extract-plugin) with this value.

> **Warning**
>
> The `esModule` option should be enabled if you want to use it with [`CSS modules`](https://github.com/webpack-contrib/css-loader#modules), by default for locals will be used [named export](https://github.com/webpack-contrib/css-loader#namedexport).

The default export is `string`.

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.(sa|sc|c)ss$/i,
        use: ["css-loader", "postcss-loader", "sass-loader"],
      },
    ],
  },
};
```

**src/index.js**

```js
import sheet from "./styles.css";

console.log(sheet);
```

#### `'css-style-sheet'`

> **Warning**
>
> `@import` rules not yet allowed, more [information](https://web.dev/css-module-scripts/#@import-rules-not-yet-allowed)

> **Warning**
>
> You don't need [`style-loader`](https://github.com/webpack-contrib/style-loader) anymore, please remove it.

> **Warning**
>
> The `esModule` option should be enabled if you want to use it with [`CSS modules`](https://github.com/webpack-contrib/css-loader#modules), by default for locals will be used [named export](https://github.com/webpack-contrib/css-loader#namedexport).

> **Warning**
>
> Source maps are not currently supported in `Chrome` due [bug](https://bugs.chromium.org/p/chromium/issues/detail?id=1174094&q=CSSStyleSheet%20source%20maps&can=2)

The default export is a [constructable stylesheet](https://developers.google.com/web/updates/2019/02/constructable-stylesheets) (i.e. [`CSSStyleSheet`](https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleSheet)).

Useful for [custom elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) and shadow DOM.

More information:

- [Using CSS Module Scripts to import stylesheets](https://web.dev/css-module-scripts/)
- [Constructable Stylesheets: seamless reusable styles](https://developers.google.com/web/updates/2019/02/constructable-stylesheets)

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        assert: { type: "css" },
        loader: "css-loader",
        options: {
          exportType: "css-style-sheet",
        },
      },

      // For Sass/SCSS:
      //
      // {
      //   assert: { type: "css" },
      //   rules: [
      //     {
      //       loader: "css-loader",
      //       options: {
      //         exportType: "css-style-sheet",
      //         // Other options
      //       },
      //     },
      //     {
      //       loader: "sass-loader",
      //       options: {
      //         // Other options
      //       },
      //     },
      //   ],
      // },
    ],
  },
};
```

**src/index.js**

```js
// Example for Sass/SCSS:
// import sheet from "./styles.scss" assert { type: "css" };

// Example for CSS modules:
// import sheet, { myClass } from "./styles.scss" assert { type: "css" };

// Example for CSS:
import sheet from "./styles.css" assert { type: "css" };

document.adoptedStyleSheets = [sheet];
shadowRoot.adoptedStyleSheets = [sheet];
```

For migration purposes, you can use the following configuration:

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        oneOf: [
          {
            assert: { type: "css" },
            loader: "css-loader",
            options: {
              exportType: "css-style-sheet",
              // Other options
            },
          },
          {
            use: [
              "style-loader",
              {
                loader: "css-loader",
                options: {
                  // Other options
                },
              },
            ],
          },
        ],
      },
    ],
  },
};
```

## Examples

### Recommend

For `production` builds it's recommended to extract the CSS from your bundle being able to use parallel loading of CSS/JS resources later on.
This can be achieved by using the [mini-css-extract-plugin](https://github.com/webpack-contrib/mini-css-extract-plugin), because it creates separate css files.
For `development` mode (including `webpack-dev-server`) you can use [style-loader](https://github.com/webpack-contrib/style-loader), because it injects CSS into the DOM using multiple `<style></style>` and works faster.

> **Note**
>
> Do not use `style-loader` and `mini-css-extract-plugin` together.

**webpack.config.js**

```js
const MiniCssExtractPlugin = require("mini-css-extract-plugin");
const devMode = process.env.NODE_ENV !== "production";

module.exports = {
  module: {
    rules: [
      {
        // If you enable `experiments.css` or `experiments.futureDefaults`, please uncomment line below
        // type: "javascript/auto",
        test: /\.(sa|sc|c)ss$/i,
        use: [
          devMode ? "style-loader" : MiniCssExtractPlugin.loader,
          "css-loader",
          "postcss-loader",
          "sass-loader",
        ],
      },
    ],
  },
  plugins: [].concat(devMode ? [] : [new MiniCssExtractPlugin()]),
};
```

### Disable url resolving using the `/* webpackIgnore: true */` comment

With the help of the `/* webpackIgnore: true */`comment, it is possible to disable sources handling for rules and for individual declarations.

```css
/* webpackIgnore: true */
@import url(./basic.css);
@import /* webpackIgnore: true */ url(./imported.css);

.class {
  /* Disabled url handling for the all urls in the 'background' declaration */
  color: red;
  /* webpackIgnore: true */
  background: url("./url/img.png"), url("./url/img.png");
}

.class {
  /* Disabled url handling for the first url in the 'background' declaration */
  color: red;
  background:
    /* webpackIgnore: true */ url("./url/img.png"), url("./url/img.png");
}

.class {
  /* Disabled url handling for the second url in the 'background' declaration */
  color: red;
  background: url("./url/img.png"),
    /* webpackIgnore: true */ url("./url/img.png");
}

/* prettier-ignore */
.class {
  /* Disabled url handling for the second url in the 'background' declaration */
  color: red;
  background: url("./url/img.png"),
    /* webpackIgnore: true */
    url("./url/img.png");
}

/* prettier-ignore */
.class {
  /* Disabled url handling for third and sixth urls in the 'background-image' declaration */
  background-image: image-set(
    url(./url/img.png) 2x,
    url(./url/img.png) 3x,
    /* webpackIgnore:  true */ url(./url/img.png) 4x,
    url(./url/img.png) 5x,
    url(./url/img.png) 6x,
    /* webpackIgnore:  true */
    url(./url/img.png) 7x
  );
}
```

### Assets

The following `webpack.config.js` can load CSS files, embed small PNG/JPG/GIF/SVG images as well as fonts as [Data URLs](https://tools.ietf.org/html/rfc2397) and copy larger files to the output directory.

**For webpack v5:**

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: ["style-loader", "css-loader"],
      },
      {
        test: /\.(png|jpe?g|gif|svg|eot|ttf|woff|woff2)$/i,
        // More information here https://webpack.js.org/guides/asset-modules/
        type: "asset",
      },
    ],
  },
};
```

### Extract

For production builds it's recommended to extract the CSS from your bundle being able to use parallel loading of CSS/JS resources later on.

- This can be achieved by using the [mini-css-extract-plugin](https://github.com/webpack-contrib/mini-css-extract-plugin) to extract the CSS when running in production mode.

- As an alternative, if seeking better development performance and css outputs that mimic production. [extract-css-chunks-webpack-plugin](https://github.com/faceyspacey/extract-css-chunks-webpack-plugin) offers a hot module reload friendly, extended version of mini-css-extract-plugin. HMR real CSS files in dev, works like mini-css in non-dev

### Pure CSS, CSS modules and PostCSS

When you have pure CSS (without CSS modules), CSS modules and PostCSS in your project you can use this setup:

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        // For pure CSS - /\.css$/i,
        // For Sass/SCSS - /\.((c|sa|sc)ss)$/i,
        // For Less - /\.((c|le)ss)$/i,
        test: /\.((c|sa|sc)ss)$/i,
        use: [
          "style-loader",
          {
            loader: "css-loader",
            options: {
              // Run `postcss-loader` on each CSS `@import` and CSS modules/ICSS imports, do not forget that `sass-loader` compile non CSS `@import`'s into a single file
              // If you need run `sass-loader` and `postcss-loader` on each CSS `@import` please set it to `2`
              importLoaders: 1,
            },
          },
          {
            loader: "postcss-loader",
            options: { plugins: () => [postcssPresetEnv({ stage: 0 })] },
          },
          // Can be `less-loader`
          {
            loader: "sass-loader",
          },
        ],
      },
      // For webpack v5
      {
        test: /\.(png|jpe?g|gif|svg|eot|ttf|woff|woff2)$/i,
        // More information here https://webpack.js.org/guides/asset-modules/
        type: "asset",
      },
    ],
  },
};
```

### Resolve unresolved URLs using an alias

**index.css**

```css
.class {
  background: url(/assets/unresolved/img.png);
}
```

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: ["style-loader", "css-loader"],
      },
    ],
  },
  resolve: {
    alias: {
      "/assets/unresolved/img.png": path.resolve(
        __dirname,
        "assets/real-path-to-img/img.png"
      ),
    },
  },
};
```

### Named export with custom export names

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "css-loader",
        options: {
          modules: {
            namedExport: true,
            exportLocalsConvention: function (name) {
              return name.replace(/-/g, "_");
            },
          },
        },
      },
    ],
  },
};
```

### Separating `Interoperable CSS`-only and `CSS Module` features

The following setup is an example of allowing `Interoperable CSS` features only (such as `:import` and `:export`) without using further `CSS Module` functionality by setting `mode` option for all files that do not match `*.module.scss` naming convention. This is for reference as having `ICSS` features applied to all files was default `css-loader` behavior before v4.
Meanwhile all files matching `*.module.scss` are treated as `CSS Modules` in this example.

An example case is assumed where a project requires canvas drawing variables to be synchronized with CSS - canvas drawing uses the same color (set by color name in JavaScript) as HTML background (set by class name in CSS).

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      // ...
      // --------
      // SCSS ALL EXCEPT MODULES
      {
        test: /\.scss$/i,
        exclude: /\.module\.scss$/i,
        use: [
          {
            loader: "style-loader",
          },
          {
            loader: "css-loader",
            options: {
              importLoaders: 1,
              modules: {
                mode: "icss",
              },
            },
          },
          {
            loader: "sass-loader",
          },
        ],
      },
      // --------
      // SCSS MODULES
      {
        test: /\.module\.scss$/i,
        use: [
          {
            loader: "style-loader",
          },
          {
            loader: "css-loader",
            options: {
              importLoaders: 1,
              modules: {
                mode: "local",
              },
            },
          },
          {
            loader: "sass-loader",
          },
        ],
      },
      // --------
      // ...
    ],
  },
};
```

**variables.scss**

File treated as `ICSS`-only.

```scss
$colorBackground: red;
:export {
  colorBackgroundCanvas: $colorBackground;
}
```

**Component.module.scss**

File treated as `CSS Module`.

```scss
@import "variables.scss";
.componentClass {
  background-color: $colorBackground;
}
```

**Component.jsx**

Using both `CSS Module` functionality as well as SCSS variables directly in JavaScript.

```jsx
import svars from "variables.scss";
import styles from "Component.module.scss";

// Render DOM with CSS modules class name
// <div className={styles.componentClass}>
//   <canvas ref={mountsCanvas}/>
// </div>

// Somewhere in JavaScript canvas drawing code use the variable directly
// const ctx = mountsCanvas.current.getContext('2d',{alpha: false});
ctx.fillStyle = `${svars.colorBackgroundCanvas}`;
```

## Contributing

Please take a moment to read our contributing guidelines if you haven't yet done so.

[CONTRIBUTING](./.github/CONTRIBUTING.md)

## License

[MIT](./LICENSE)

[npm]: https://img.shields.io/npm/v/css-loader.svg
[npm-url]: https://npmjs.com/package/css-loader
[node]: https://img.shields.io/node/v/css-loader.svg
[node-url]: https://nodejs.org
[tests]: https://github.com/webpack-contrib/css-loader/workflows/css-loader/badge.svg
[tests-url]: https://github.com/webpack-contrib/css-loader/actions
[cover]: https://codecov.io/gh/webpack-contrib/css-loader/branch/master/graph/badge.svg
[cover-url]: https://codecov.io/gh/webpack-contrib/css-loader
[discussion]: https://img.shields.io/github/discussions/webpack/webpack
[discussion-url]: https://github.com/webpack/webpack/discussions
[size]: https://packagephobia.now.sh/badge?p=css-loader
[size-url]: https://packagephobia.now.sh/result?p=css-loader


---

# Changelog

All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.

### [5.0.1](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/compare/v5.0.0...v5.0.1) (2023-06-13)


### Bug Fixes

* improve perf ([#235](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/issues/235)) ([959eb89](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/commit/959eb89aa1e37df88d2decbe6f40c096f10a3745))

## [5.0.0](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/compare/v4.2.2...v5.0.0) (2023-03-27)


### ⚠ BREAKING CHANGES

* update `cssnano` to v6 (migration guide - https://github.com/cssnano/cssnano/releases/tag/cssnano%406.0.0) (#224)

### Features

* update `cssnano` to v6 ([#224](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/issues/224)) ([cfcae0c](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/commit/cfcae0c9e2b7afd740774104a8e5eb675fe984db))

### [4.2.2](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/compare/v4.2.1...v4.2.2) (2022-10-13)


### Bug Fixes

* handle `swc` errors ([#202](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/issues/202)) ([b1ce195](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/commit/b1ce195a0de508217ea1a91d7f8e2683e77b495a))

### [4.2.1](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/compare/v4.2.0...v4.2.1) (2022-10-06)


### Bug Fixes

* crash ([#200](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/issues/200)) ([c50b2b2](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/commit/c50b2b25348a78a6bfaff248e0fb356a70a4241c))

## [4.2.0](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/compare/v4.1.0...v4.2.0) (2022-09-29)


### Features

* added `swc` minimizer ([#197](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/issues/197)) ([5461421](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/commit/546142104cb30e4711ba800170961822de7d0097))

## [4.1.0](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/compare/v4.0.0...v4.1.0) (2022-09-09)


### Features

* added `lightningcss` support ([#192](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/issues/192)) ([04a3347](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/commit/04a3347610a0044116bfebfd3f3be50d3ada4e04))

## [4.0.0](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/compare/v3.4.1...v4.0.0) (2022-05-18)


### ⚠ BREAKING CHANGES

* minimum supported `Node.js` version is `14.15.0`

### [3.4.1](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/compare/v3.4.0...v3.4.1) (2022-01-18)


### Bug Fixes

* types ([9c8b0f3](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/commit/9c8b0f35cc6fc8816c387c48c535d71891d8aa65))

## [3.4.0](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/compare/v3.3.1...v3.4.0) (2022-01-18)


### Features

* added `@parcel/css` support ([#154](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/issues/154)) ([5e5fe51](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/commit/5e5fe512c7209f0ad4c7f9c55f47cf9763adfc74))

### [3.3.1](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/compare/v3.3.0...v3.3.1) (2021-12-21)


### Bug Fixes

* cssnano types ([#147](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/issues/147)) ([a51026e](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/commit/a51026e3b948fa14d2334d823b3bbb6ea482c57b))

## [3.3.0](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/compare/v3.2.0...v3.3.0) (2021-12-16)


### Features

* removed cjs wrapper and generated types in commonjs format (`export =` and `namespaces` used in types), now you can directly use exported types ([3262a9a](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/commit/3262a9aee2c89e6aed00c4f76443e0d1e07489f0))

## [3.2.0](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/compare/v3.1.4...v3.2.0) (2021-11-23)


### Features

* added types ([#142](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/issues/142)) ([fb91610](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/commit/fb91610730166b8fb4fb09cee5da781f0ec98e70))

### [3.1.4](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/compare/v3.1.3...v3.1.4) (2021-11-17)


### Chore

* update `schema-utils` package to `4.0.0` version

### [3.1.3](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/compare/v3.1.2...v3.1.3) (2021-11-10)


### Bug Fixes

* source map generation for `cssnano` and `clean-css` ([#135](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/issues/135)) ([a9dd43e](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/commit/a9dd43e1a7284bb713e19eac6fa3f3724fb9d48b))

### [3.1.2](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/compare/v3.1.1...v3.1.2) (2021-11-08)


### Bug Fixes

* handle `esbuild` warnings ([f427f41](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/commit/f427f41d319b340262c9b5061cf5427bdf5a5f78))

### [3.1.1](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/compare/v3.1.0...v3.1.1) (2021-10-05)


### Bug Fixes

* minified result can be empty ([#127](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/issues/127)) ([0a8ad71](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/commit/0a8ad71fa0da86c5f76381f13ddf013db02a60ea))

## [3.1.0](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/compare/v3.0.2...v3.1.0) (2021-10-04)


### Features

* added `esbuild` minimizer ([#122](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/issues/122)) ([987d454](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/commit/987d45402af81d88fbd1489021f8d14e5ff26a74))
* allow returning errors from custom minimize function ([#121](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/issues/121)) ([c9a11b2](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/commit/c9a11b2349d24206bc03cf3670f50a822ef7a52b))
* output documentation links on errors ([4e8afba](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/commit/4e8afbae5c89b0fe52b83b69fb2c5ab8a6382750))


### Bug Fixes

* source map generation for multiple `minify` functions ([b736099](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/commit/b7360993a50a4d998bb92f0a3d491030452fcb0b))

### [3.0.2](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/compare/v3.0.1...v3.0.2) (2021-06-25)

### Chore

* update `serialize-javascript`

### [3.0.1](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/compare/v3.0.0...v3.0.1) (2021-05-31)

### Chore

* update `jest-worker`

## [3.0.0](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/compare/v2.0.0...v3.0.0) (2021-05-12)


### ⚠ BREAKING CHANGES

* minimum supported `Node.js` version is `12.13.0`

## [2.0.0](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/compare/v1.3.0...v2.0.0) (2021-04-10)


### ⚠ BREAKING CHANGES

* update `cssnano` to `5.0.0` version
* drop `webpack` v4 support, 
* removed the `cache` option (respect the [`cache`](https://webpack.js.org/configuration/other-options/#cache) option from `webpack`)
* removed the `cacheKeys` option respect the [`cache`](https://webpack.js.org/configuration/other-options/#cache) option from `webpack`)
* removed the sourceMap option (respect the [`devtool`](https://webpack.js.org/configuration/devtool/) option from `webpack`)

### Features

* added defaults functions for `clean-css` and `csso`, please look at [here](https://github.com/webpack-contrib/css-minimizer-webpack-plugin#minify) ([5211eed](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/commit/5211eed3c816212a30715ebf0798393c886343d0))
* added the ability to pass an array of functions to the minify ([91f9977](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/commit/91f9977e9fdd1447cb45bc6f5d4b56fe7c26fb04))
* update `cssnano` to `5.0.0` version ([4d2a8fd](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/commit/4d2a8fd275ab17f6d98e4581b6c2adf09c73c91c))

## [1.3.0](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/compare/v1.2.0...v1.3.0) (2021-03-15)


### Features

* added support `processorOptions` for `cssnano` ([8865423](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/commit/886542375dc37411e271d151b7060be574fc5898))

## [1.2.0](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/compare/v1.1.5...v1.2.0) (2021-01-08)


### Features

* optimize CSS assets added later by plugins (webpack@5 only) ([#47](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/issues/47)) ([bdb3f52](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/commit/bdb3f524289a2c131e2ec3728cf10b4c9a0010c7))


### Bug Fixes

* crash with source maps when the `parallel` option is `false` ([#53](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/issues/53)) ([4fe95f9](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/commit/4fe95f9b63764d06ffc4e6d6d77a45ba2dd1b76b))

### [1.1.5](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/compare/v1.1.4...v1.1.5) (2020-10-07)

### Chore

* update `schema-utils`

### [1.1.4](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/compare/v1.1.3...v1.1.4) (2020-09-18)


### Bug Fixes

* weak cache
* source map generation
* cache warnings between builds 

### [1.1.3](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/compare/v1.1.2...v1.1.3) (2020-09-03)


### Bug Fixes

* do not crash on the `minify` option ([fd9abac](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/commit/fd9abac59dc82561ef1db603165526caba6e9abe))

### [1.1.2](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/compare/v1.1.1...v1.1.2) (2020-08-24)


### Bug Fixes

* compatibility with webpack 5 ([6232829](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/commit/62328298d6a81f31e773d11ced8811ee41cd0470))

### [1.1.1](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/compare/v1.1.0...v1.1.1) (2020-08-10)


### Bug Fixes

* compatibility with `10.13` version of `Node.js` ([d38ea79](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/commit/d38ea793bc2cefc6289d2fe8f2e5df8c31e487e0))

## [1.1.0](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/compare/v1.0.0...v1.1.0) (2020-08-04)


### Features

* show minimized assets in stats for webpack@5 ([#19](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/issues/19)) ([cb038b9](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/commit/cb038b91b15e934a56c260635506df4f02efd747))


### Bug Fixes

* compatibility cache feature with webpack@5 ([#16](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/issues/16)) ([997e00f](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/commit/997e00f66298219dccfdff8c01c71bebc973df49))
* skip double compression for child compilation ([#18](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/issues/18)) ([ffc71c2](https://github.com/webpack-contrib/css-minimizer-webpack-plugin/commit/ffc71c2c5269ba12c794be87c3257390fdd9c926))

## 1.0.0 - 2020-08-01

Initial release


---

<div align="center">
  <a href="https://github.com/webpack/webpack">
    <img width="200" height="200" src="https://webpack.js.org/assets/icon-square-big.svg">
  </a>
</div>

[![npm][npm]][npm-url]
[![node][node]][node-url]
[![tests][tests]][tests-url]
[![cover][cover]][cover-url]
[![discussion][discussion]][discussion-url]
[![size][size]][size-url]

# css-minimizer-webpack-plugin

This plugin uses [cssnano](https://cssnano.co) to optimize and minify your CSS.

Just like [optimize-css-assets-webpack-plugin](https://github.com/NMFR/optimize-css-assets-webpack-plugin) but more accurate with source maps and assets using query string, allows caching and works in parallel mode.

## Getting Started

To begin, you'll need to install `css-minimizer-webpack-plugin`:

```console
npm install css-minimizer-webpack-plugin --save-dev
```

or

```console
yarn add -D css-minimizer-webpack-plugin
```

or

```console
pnpm add -D css-minimizer-webpack-plugin
```

Then add the plugin to your `webpack` configuration. For example:

**webpack.config.js**

```js
const MiniCssExtractPlugin = require("mini-css-extract-plugin");
const CssMinimizerPlugin = require("css-minimizer-webpack-plugin");

module.exports = {
  module: {
    rules: [
      {
        test: /.s?css$/,
        use: [MiniCssExtractPlugin.loader, "css-loader", "sass-loader"],
      },
    ],
  },
  optimization: {
    minimizer: [
      // For webpack@5 you can use the `...` syntax to extend existing minimizers (i.e. `terser-webpack-plugin`), uncomment the next line
      // `...`,
      new CssMinimizerPlugin(),
    ],
  },
  plugins: [new MiniCssExtractPlugin()],
};
```

This will enable CSS optimization only in production mode.

If you want to run it also in development set the `optimization.minimize` option to `true`:

**webpack.config.js**

```js
// [...]
module.exports = {
  optimization: {
    // [...]
    minimize: true,
  },
};
```

And run `webpack` via your preferred method.

## Note about source maps

**Works only with `source-map`, `inline-source-map`, `hidden-source-map` and `nosources-source-map` values for the [`devtool`](https://webpack.js.org/configuration/devtool/) option.**

Why? Because CSS support only these source map types.

The plugin respect the [`devtool`](https://webpack.js.org/configuration/devtool/) and using the `SourceMapDevToolPlugin` plugin.
Using supported `devtool` values enable source map generation.
Using `SourceMapDevToolPlugin` with enabled the `columns` option enables source map generation.

Use source maps to map error message locations to modules (this slows down the compilation).
If you use your own `minify` function please read the `minify` section for handling source maps correctly.

## Options

|                    Name                     |                      Type                      |              Default               | Description                                                                       |
| :-----------------------------------------: | :--------------------------------------------: | :--------------------------------: | :-------------------------------------------------------------------------------- |
|             **[`test`](#test)**             |    `String\|RegExp\|Array<String\|RegExp>`     |         `/\.css(\?.*)?$/i`         | Test to match files against.                                                      |
|          **[`include`](#include)**          |    `String\|RegExp\|Array<String\|RegExp>`     |            `undefined`             | Files to include.                                                                 |
|          **[`exclude`](#exclude)**          |    `String\|RegExp\|Array<String\|RegExp>`     |            `undefined`             | Files to exclude.                                                                 |
|         **[`parallel`](#parallel)**         |               `Boolean\|Number`                |               `true`               | Enable/disable multi-process parallel running.                                    |
|           **[`minify`](#minify)**           |          `Function\|Array<Function>`           | `CssMinimizerPlugin.cssnanoMinify` | Allows to override default minify function.                                       |
| **[`minimizerOptions`](#minimizeroptions)** |            `Object\|Array<Object>`             |      `{ preset: 'default' }`       | Cssnano optimisations [options](https://cssnano.co/docs/what-are-optimisations/). |
|   **[`warningsFilter`](#warningsfilter)**   | `Function<(warning, file, source) -> Boolean>` |            `() => true`            | Allow to filter css-minimizer warnings.                                           |

### `test`

Type: `String|RegExp|Array<String|RegExp>` - default: `/\.css(\?.*)?$/i`

Test to match files against.

```js
module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new CssMinimizerPlugin({
        test: /\.foo\.css$/i,
      }),
    ],
  },
};
```

### `include`

Type: `String|RegExp|Array<String|RegExp>`
Default: `undefined`

Files to include.

**webpack.config.js**

```js
module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new CssMinimizerPlugin({
        include: /\/includes/,
      }),
    ],
  },
};
```

### `exclude`

Type: `String|RegExp|Array<String|RegExp>`
Default: `undefined`

Files to exclude.

**webpack.config.js**

```js
module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new CssMinimizerPlugin({
        exclude: /\/excludes/,
      }),
    ],
  },
};
```

### `parallel`

Type: `Boolean|Number`
Default: `true`

Use multi-process parallel running to improve the build speed.
Default number of concurrent runs: `os.cpus().length - 1`.

> ℹ️ Parallelization can speed up your build significantly and is therefore **highly recommended**.
> If a parallelization is enabled, the packages in `minimizerOptions` must be required via strings (`packageName` or `require.resolve(packageName)`). Read more in [`minimizerOptions`](#minimizeroptions)

#### `Boolean`

Enable/disable multi-process parallel running.

**webpack.config.js**

```js
module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new CssMinimizerPlugin({
        parallel: true,
      }),
    ],
  },
};
```

#### `Number`

Enable multi-process parallel running and set number of concurrent runs.

**webpack.config.js**

```js
module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new CssMinimizerPlugin({
        parallel: 4,
      }),
    ],
  },
};
```

### `minify`

Type: `Function|Array<Function>`
Default: `CssMinimizerPlugin.cssnanoMinify`

Allows overriding default minify function.
By default, plugin uses [cssnano](https://github.com/cssnano/cssnano) package.
Useful for using and testing unpublished versions or forks.

Possible options:

- `CssMinimizerPlugin.cssnanoMinify`
- `CssMinimizerPlugin.cssoMinify`
- `CssMinimizerPlugin.cleanCssMinify`
- `CssMinimizerPlugin.esbuildMinify`
- `CssMinimizerPlugin.lightningCssMinify` (previously`CssMinimizerPlugin.parcelCssMinify`, the package was renamed, but we keep it for backward compatibility)
- `async (data, inputMap, minimizerOptions) => {return {code: "a{color: red}", map: "...", warnings: [], errors: []}}`

> **Warning**
>
> **Always use `require` inside `minify` function when `parallel` option enabled**.

#### `Function`

**webpack.config.js**

```js
module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new CssMinimizerPlugin({
        minimizerOptions: {
          level: {
            1: {
              roundingPrecision: "all=3,px=5",
            },
          },
        },
        minify: CssMinimizerPlugin.cleanCssMinify,
      }),
    ],
  },
};
```

#### `Array`

If an array of functions is passed to the `minify` option, the `minimizerOptions` must also be an array.
The function index in the `minify` array corresponds to the options object with the same index in the `minimizerOptions` array.

**webpack.config.js**

```js
module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new CssMinimizerPlugin({
        minimizerOptions: [
          {}, // Options for the first function (CssMinimizerPlugin.cssnanoMinify)
          {}, // Options for the second function (CssMinimizerPlugin.cleanCssMinify)
          {}, // Options for the third function
        ],
        minify: [
          CssMinimizerPlugin.cssnanoMinify,
          CssMinimizerPlugin.cleanCssMinify,
          async (data, inputMap, minimizerOptions) => {
            // To do something
            return {
              code: `a{color: red}`,
              map: `{"version": "3", ...}`,
              warnings: [],
              errors: [],
            };
          },
        ],
      }),
    ],
  },
};
```

### `minimizerOptions`

Type: `Object|Array<Object>`
Default: `{ preset: 'default' }`

Cssnano optimisations [options](https://cssnano.co/docs/what-are-optimisations/).

#### `Object`

```js
module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new CssMinimizerPlugin({
        minimizerOptions: {
          preset: [
            "default",
            {
              discardComments: { removeAll: true },
            },
          ],
        },
      }),
    ],
  },
};
```

#### `Array`

The function index in the `minify` array corresponds to the options object with the same index in the `minimizerOptions` array.
If you use `minimizerOptions` like object, all `minify` function accept it.

> If a parallelization is enabled, the packages in `minimizerOptions` must be required via strings (`packageName` or `require.resolve(packageName)`). In this case, we shouldn't use `require`/`import`.

```js
module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new CssMinimizerPlugin({
        minimizerOptions: {
          preset: require.resolve("cssnano-preset-simple"),
        },
      }),
    ],
  },
};
```

##### `processorOptions` (⚠ only cssnano)

Type: `Object`
Default: `{ from: assetName }`

Allows filtering options [`processoptions`](https://postcss.org/api/#processoptions) for the cssnano.
The `parser`,` stringifier` and `syntax` can be either a function or a string indicating the module that will be imported.

> **Warning**
>
> **If a function is passed, the `parallel` option must be disabled.**.

```js
import sugarss from "sugarss";

module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new CssMinimizerPlugin({
        parallel: false,
        minimizerOptions: {
          processorOptions: {
            parser: sugarss,
          },
        },
      }),
    ],
  },
};
```

```js
module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new CssMinimizerPlugin({
        minimizerOptions: {
          processorOptions: {
            parser: "sugarss",
          },
        },
      }),
    ],
  },
};
```

### `warningsFilter`

Type: `Function<(warning, file, source) -> Boolean>`
Default: `() => true`

Allow filtering css-minimizer warnings (By default [cssnano](https://github.com/cssnano/cssnano)).
Return `true` to keep the warning, a falsy value (`false`/`null`/`undefined`) otherwise.

> **Warning**
>
> The `source` argument will contain `undefined` if you don't use source maps.

**webpack.config.js**

```js
module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new CssMinimizerPlugin({
        warningsFilter: (warning, file, source) => {
          if (/Dropping unreachable code/i.test(warning)) {
            return true;
          }

          if (/file\.css/i.test(file)) {
            return true;
          }

          if (/source\.css/i.test(source)) {
            return true;
          }

          return false;
        },
      }),
    ],
  },
};
```

## Examples

### Use sourcemaps

Don't forget to enable `sourceMap` options for all loaders.

```js
const CssMinimizerPlugin = require("css-minimizer-webpack-plugin");

module.exports = {
  devtool: "source-map",
  module: {
    rules: [
      {
        test: /.s?css$/,
        use: [
          MiniCssExtractPlugin.loader,
          { loader: "css-loader", options: { sourceMap: true } },
          { loader: "sass-loader", options: { sourceMap: true } },
        ],
      },
    ],
  },
  optimization: {
    minimizer: [new CssMinimizerPlugin()],
  },
  plugins: [new MiniCssExtractPlugin()],
};
```

### Remove all comments

Remove all comments (including comments starting with `/*!`).

```js
module.exports = {
  optimization: {
    minimizer: [
      new CssMinimizerPlugin({
        minimizerOptions: {
          preset: [
            "default",
            {
              discardComments: { removeAll: true },
            },
          ],
        },
      }),
    ],
  },
};
```

### Using custom minifier [csso](https://github.com/css/csso)

**webpack.config.js**

```js
module.exports = {
  // Uncomment if you need source maps
  // devtool: "source-map",
  optimization: {
    minimize: true,
    minimizer: [
      new CssMinimizerPlugin({
        minify: CssMinimizerPlugin.cssoMinify,
        // Uncomment this line for options
        // minimizerOptions: { restructure: false },
      }),
    ],
  },
};
```

### Using custom minifier [clean-css](https://github.com/jakubpawlowicz/clean-css)

**webpack.config.js**

```js
module.exports = {
  // Uncomment if you need source maps
  // devtool: "source-map",
  optimization: {
    minimize: true,
    minimizer: [
      new CssMinimizerPlugin({
        minify: CssMinimizerPlugin.cleanCssMinify,
        // Uncomment this line for options
        // minimizerOptions: { compatibility: 'ie11,-properties.merging' },
      }),
    ],
  },
};
```

### Using custom minifier [esbuild](https://github.com/evanw/esbuild)

**webpack.config.js**

```js
module.exports = {
  // Uncomment if you need source maps
  // devtool: "source-map",
  optimization: {
    minimize: true,
    minimizer: [
      new CssMinimizerPlugin({
        minify: CssMinimizerPlugin.esbuildMinify,
      }),
    ],
  },
};
```

### Using custom minifier [lightningcss](https://github.com/parcel-bundler/lightningcss), previously `@parcel/css`

**webpack.config.js**

```js
module.exports = {
  // Uncomment if you need source maps
  // devtool: "source-map",
  optimization: {
    minimize: true,
    minimizer: [
      new CssMinimizerPlugin({
        minify: CssMinimizerPlugin.lightningCssMinify,
        // Uncomment this line for options
        // minimizerOptions: { targets: { ie: 11 }, drafts: { nesting: true } },
      }),
    ],
  },
};
```

### Using custom minifier [swc](https://github.com/swc-project/swc)

**webpack.config.js**

```js
module.exports = {
  // Uncomment if you need source maps
  // devtool: "source-map",
  optimization: {
    minimize: true,
    minimizer: [
      new CssMinimizerPlugin({
        minify: CssMinimizerPlugin.swcMinify,
        // Uncomment this line for options
        // minimizerOptions: {},
      }),
    ],
  },
};
```

## Contributing

Please take a moment to read our contributing guidelines if you haven't yet done so.

[CONTRIBUTING](./.github/CONTRIBUTING.md)

## License

[MIT](./LICENSE)

[npm]: https://img.shields.io/npm/v/css-minimizer-webpack-plugin.svg
[npm-url]: https://npmjs.com/package/css-minimizer-webpack-plugin
[node]: https://img.shields.io/node/v/css-minimizer-webpack-plugin.svg
[node-url]: https://nodejs.org
[tests]: https://github.com/webpack-contrib/css-minimizer-webpack-plugin/workflows/css-minimizer-webpack-plugin/badge.svg
[tests-url]: https://github.com/webpack-contrib/css-minimizer-webpack-plugin/actions
[cover]: https://codecov.io/gh/webpack-contrib/css-minimizer-webpack-plugin/branch/master/graph/badge.svg
[cover-url]: https://codecov.io/gh/webpack-contrib/css-minimizer-webpack-plugin
[discussion]: https://img.shields.io/github/discussions/webpack/webpack
[discussion-url]: https://github.com/webpack/webpack/discussions
[size]: https://packagephobia.now.sh/badge?p=css-minimizer-webpack-plugin
[size-url]: https://packagephobia.now.sh/result?p=css-minimizer-webpack-plugin


---

# Changes to Prefers Color Scheme

### 10.0.0

_August 3, 2024_

- Updated: Support for Node v18+ (major).

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/css-prefers-color-scheme/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# Prefers Color Scheme [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install css-prefers-color-scheme --save-dev`

[Prefers Color Scheme] lets you use light and dark color schemes in all browsers, following the [Media Queries] specification.

To use this feature you need to do two things :
- add the [PostCSS plugin](#usage) that transforms the media queries
- add the [browser polyfill](#browser) that triggers specific queries in a browser

```pcss
@media (prefers-color-scheme: dark) {
	:root {
		--site-bgcolor: #1b1b1b;
		--site-color: #fff;
	}
}

@media (prefers-color-scheme: light) {
	:root {
		--site-bgcolor: #fff;
		--site-color: #222;
	}
}

/* becomes */

@media (color: 48842621) {
	:root {
		--site-bgcolor: #1b1b1b;
		--site-color: #fff;
	}
}

@media (prefers-color-scheme: dark) {
	:root {
		--site-bgcolor: #1b1b1b;
		--site-color: #fff;
	}
}

@media (color: 70318723) {
	:root {
		--site-bgcolor: #fff;
		--site-color: #222;
	}
}

@media (prefers-color-scheme: light) {
	:root {
		--site-bgcolor: #fff;
		--site-color: #222;
	}
}
```

## Usage

Add [Prefers Color Scheme] to your project:

```bash
npm install postcss css-prefers-color-scheme --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const prefersColorScheme = require('css-prefers-color-scheme');

postcss([
	prefersColorScheme(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## Options

### preserve

The `preserve` option determines whether the original notation
is preserved. By default, it is preserved.

```js
prefersColorScheme({ preserve: false })
```

```pcss
@media (prefers-color-scheme: dark) {
	:root {
		--site-bgcolor: #1b1b1b;
		--site-color: #fff;
	}
}

@media (prefers-color-scheme: light) {
	:root {
		--site-bgcolor: #fff;
		--site-color: #222;
	}
}

/* becomes */

@media (color: 48842621) {
	:root {
		--site-bgcolor: #1b1b1b;
		--site-color: #fff;
	}
}

@media (color: 70318723) {
	:root {
		--site-bgcolor: #fff;
		--site-color: #222;
	}
}
```

## Browser

```js
// initialize prefersColorScheme (applies the current OS color scheme, if available)
import prefersColorSchemeInit from 'css-prefers-color-scheme/browser';
const prefersColorScheme = prefersColorSchemeInit();

// apply "dark" queries (you can also apply "light")
prefersColorScheme.scheme = 'dark';
```

or

```html
<!-- When using a CDN url you will have to manually update the version number -->
<script src="https://unpkg.com/css-prefers-color-scheme@10.0.0/dist/browser-global.js"></script>
<script>prefersColorSchemeInit()</script>
```

> [!TIP]
> Please use a versioned url, like this : `https://unpkg.com/css-prefers-color-scheme@10.0.0/dist/browser-global.js`
> Without the version, you might unexpectedly get a new major version of the library with breaking changes.

[Prefers Color Scheme] works in all major browsers, including Safari 6+ and
Internet Explorer 9+ without any additional polyfills.

To maintain compatibility with browsers supporting `prefers-color-scheme`, the
library will remove `prefers-color-scheme` media queries in favor of
cross-browser compatible `color` media queries. This ensures a seamless
experience, even when JavaScript is unable to run.

### Browser Usage

Use [Prefers Color Scheme] to activate your `prefers-color-scheme` queries:

```js
import prefersColorSchemeInit from 'css-prefers-color-scheme/browser';
const prefersColorScheme = prefersColorSchemeInit();
```

By default, the current OS color scheme is applied if your browser supports it.
Otherwise, the light color scheme is applied. You may override this by passing
in a color scheme.

```js
import prefersColorSchemeInit from 'css-prefers-color-scheme/browser';
const prefersColorScheme = prefersColorSchemeInit('dark');
```

The `prefersColorScheme` object returns the following properties — `scheme`,
`hasNativeSupport`, `onChange`, and `removeListener`.

#### scheme

The `scheme` property returns the currently preferred color scheme, and it can
be changed.

```js
import prefersColorSchemeInit from 'css-prefers-color-scheme/browser';
const prefersColorScheme = prefersColorSchemeInit();

// log the preferred color scheme
console.log(prefersColorScheme.scheme);

// apply "dark" queries
prefersColorScheme.scheme = 'dark';
```

#### hasNativeSupport

The `hasNativeSupport` boolean represents whether `prefers-color-scheme` is
supported by the browser.

#### onChange

The optional `onChange` function is run when the preferred color scheme is
changed, either from the OS or manually.

#### removeListener

The `removeListener` function removes the native `prefers-color-scheme`
listener, which may or may not be applied, depending on your browser support.
This is provided to give you complete control over plugin cleanup.

#### debug

If styles are not applied you can enable debug mode to log exceptions.

```js
import prefersColorSchemeInit from 'css-prefers-color-scheme/browser';
const prefersColorScheme = prefersColorSchemeInit('light', { debug: true });
```

```html
<script src="https://unpkg.com/css-prefers-color-scheme@10.0.0/dist/browser-global.js"></script>
<script>prefersColorSchemeInit('light', { debug: true })</script>
```


### Browser Dependencies

Web API's:

- [Window.matchMedia](https://developer.mozilla.org/en-US/docs/Web/API/Window/matchMedia)

ECMA Script:

- `Object.defineProperty`
- `Array.prototype.forEach`
- `Array.prototype.indexOf`
- `RegExp.prototype.exec`
- `String.prototype.match`
- `String.prototype.replace`

## CORS

> [!IMPORTANT]
> Applies to you if you load CSS from a different domain than the page.
>
> In this case the CSS is treated as untrusted and will not be made available to the JavaScript polyfill.
> The polyfill will not work without applying the correct configuration for CORS.

Example :

| page | css | CORS applies |
| --- | --- | --- |
| https://example.com/ | https://example.com/style.css | no |
| https://example.com/ | https://other.com/style.css | yes |


**You might see one of these error messages :**

Chrome :

> DOMException: Failed to read the 'cssRules' property from 'CSSStyleSheet': Cannot access rules

Safari :

> SecurityError: Not allowed to access cross-origin stylesheet

Firefox :

> DOMException: CSSStyleSheet.cssRules getter: Not allowed to access cross-origin stylesheet

To resolve CORS errors you need to take two steps :

- add an HTTP header `Access-Control-Allow-Origin: <your-value>` when serving your CSS file.
- add `crossorigin="anonymous"` to the `<link rel="stylesheet">` tag for your CSS file.

In a node server setting the HTTP header might look like this :

```js
// http://localhost:8080 is the domain of your page!
res.setHeader('Access-Control-Allow-Origin', 'https://example.com');
```

You can also configure a wildcard but please be aware that this might be a security risk.
It is better to only set the header for the domain you want to allow and only on the responses you want to allow.

HTML might look like this :

```html
<link rel="stylesheet" href="https://example.com/styles.css" crossorigin="anonymous">
```


### Using with Next.js

Given that Next.js imports packages both on the browser and on the server, you need to make sure that the package is only imported on the browser.

As outlined in the [Next.js documentation](https://nextjs.org/docs/advanced-features/dynamic-import#with-external-libraries), you need to load the package with a dynamic import:

```jsx
useEffect(async () => {
	const prefersColorSchemeInit = (await import('css-prefers-color-scheme/browser')).default;
	const prefersColorScheme = prefersColorSchemeInit();
}, []);
```

## How does it work?

[Prefers Color Scheme] is a [PostCSS] plugin that transforms `prefers-color-scheme` queries into `color` queries.
This changes `prefers-color-scheme: dark` into `(color: 48842621)` and `prefers-color-scheme: light` into `(color: 70318723)`.

The frontend receives these `color` queries, which are understood in all
major browsers going back to Internet Explorer 9.
However, since browsers can only have a reasonably small number of bits per color,
our color scheme values are ignored.

[Prefers Color Scheme] uses a [browser script](#browser) to change
`(color: 48842621)` queries into `(max-color: 48842621)` in order to
activate “dark mode” specific CSS, and it changes `(color: 70318723)` queries
into `(max-color: 48842621)` to activate “light mode” specific CSS.

```css
@media (color: 70318723) { /* prefers-color-scheme: light */
	body {
		background-color: white;
		color: black;
	}
}
```

Since these media queries are accessible to `document.styleSheet`, no CSS
parsing is required.

### Why does the fallback work this way?

The value of `48` is chosen for dark mode because it is the keycode for `0`,
the hexidecimal value of black. Likewise, `70` is chosen for light mode because
it is the keycode for `f`, the hexidecimal value of white.
These are suffixed with a random large number.

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#prefers-color-scheme-query
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/css-prefers-color-scheme

[PostCSS]: https://github.com/postcss/postcss
[Prefers Color Scheme]: https://github.com/csstools/postcss-plugins/tree/main/plugins/css-prefers-color-scheme
[Media Queries]: https://www.w3.org/TR/mediaqueries-5/#prefers-color-scheme


---

# css-select [![NPM version](http://img.shields.io/npm/v/css-select.svg)](https://npmjs.org/package/css-select) [![Build Status](https://travis-ci.com/fb55/css-select.svg?branch=master)](http://travis-ci.com/fb55/css-select) [![Downloads](https://img.shields.io/npm/dm/css-select.svg)](https://npmjs.org/package/css-select) [![Coverage](https://coveralls.io/repos/fb55/css-select/badge.svg?branch=master)](https://coveralls.io/r/fb55/css-select)

A CSS selector compiler and engine

## What?

As a **compiler**, css-select turns CSS selectors into functions that tests if
elements match them.

As an **engine**, css-select looks through a DOM tree, searching for elements.
Elements are tested "from the top", similar to how browsers execute CSS
selectors.

In its default configuration, css-select queries the DOM structure of the
[`domhandler`](https://github.com/fb55/domhandler) module (also known as
htmlparser2 DOM). To query alternative DOM structures, see [`Options`](#options)
below.

**Features:**

-   🔬 Full implementation of CSS3 selectors, as well as most CSS4 selectors
-   🧪 Partial implementation of jQuery/Sizzle extensions (see
    [cheerio-select](https://github.com/cheeriojs/cheerio-select) for the
    remaining selectors)
-   🧑‍🔬 High test coverage, including the full test suites from
    [`Sizzle`](https://github.com/jquery/sizzle),
    [`Qwery`](https://github.com/ded/qwery) and
    [`NWMatcher`](https://github.com/dperini/nwmatcher/) and .
-   🥼 Reliably great performance

## Why?

Most CSS engines written in JavaScript execute selectors left-to-right. That
means thet execute every component of the selector in order, from left to right.
As an example: For the selector `a b`, these engines will first query for `a`
elements, then search these for `b` elements. (That's the approach of eg.
[`Sizzle`](https://github.com/jquery/sizzle),
[`Qwery`](https://github.com/ded/qwery) and
[`NWMatcher`](https://github.com/dperini/nwmatcher/).)

While this works, it has some downsides: Children of `a`s will be checked
multiple times; first, to check if they are also `a`s, then, for every superior
`a` once, if they are `b`s. Using
[Big O notation](http://en.wikipedia.org/wiki/Big_O_notation), that would be
`O(n^(k+1))`, where `k` is the number of descendant selectors (that's the space
in the example above).

The far more efficient approach is to first look for `b` elements, then check if
they have superior `a` elements: Using big O notation again, that would be
`O(n)`. That's called right-to-left execution.

And that's what css-select does – and why it's quite performant.

## How does it work?

By building a stack of functions.

_Wait, what?_

Okay, so let's suppose we want to compile the selector `a b`, for right-to-left
execution. We start by _parsing_ the selector. This turns the selector into an
array of the building blocks. That's what the
[`css-what`](https://github.com/fb55/css-what) module is for, if you want to
have a look.

Anyway, after parsing, we end up with an array like this one:

```js
[
    { type: "tag", name: "a" },
    { type: "descendant" },
    { type: "tag", name: "b" },
];
```

(Actually, this array is wrapped in another array, but that's another story,
involving commas in selectors.)

Now that we know the meaning of every part of the selector, we can compile it.
That is where things become interesting.

The basic idea is to turn every part of the selector into a function, which
takes an element as its only argument. The function checks whether a passed
element matches its part of the selector: If it does, the element is passed to
the next function representing the next part of the selector. That function does
the same. If an element is accepted by all parts of the selector, it _matches_
the selector and double rainbow ALL THE WAY.

As said before, we want to do right-to-left execution with all the big O
improvements. That means elements are passed from the rightmost part of the
selector (`b` in our example) to the leftmost (~~which would be `c`~~ of course
`a`).

For traversals, such as the _descendant_ operating the space between `a` and
`b`, we walk up the DOM tree, starting from the element passed as argument.

_//TODO: More in-depth description. Implementation details. Build a spaceship._

## API

```js
const CSSselect = require("css-select");
```

**Note:** css-select throws errors when invalid selectors are passed to it. This
is done to aid with writing css selectors, but can be unexpected when processing
arbitrary strings.

#### `CSSselect.selectAll(query, elems, options)`

Queries `elems`, returns an array containing all matches.

-   `query` can be either a CSS selector or a function.
-   `elems` can be either an array of elements, or a single element. If it is an
    element, its children will be queried.
-   `options` is described below.

Aliases: `default` export, `CSSselect.iterate(query, elems)`.

#### `CSSselect.compile(query, options)`

Compiles the query, returns a function.

#### `CSSselect.is(elem, query, options)`

Tests whether or not an element is matched by `query`. `query` can be either a
CSS selector or a function.

#### `CSSselect.selectOne(query, elems, options)`

Arguments are the same as for `CSSselect.selectAll(query, elems)`. Only returns
the first match, or `null` if there was no match.

### Options

All options are optional.

-   `xmlMode`: When enabled, tag names will be case-sensitive. Default: `false`.
-   `rootFunc`: The last function in the stack, will be called with the last
    element that's looked at.
-   `adapter`: The adapter to use when interacting with the backing DOM
    structure. By default it uses the `domutils` module.
-   `context`: The context of the current query. Used to limit the scope of
    searches. Can be matched directly using the `:scope` pseudo-class.
-   `relativeSelector`: By default, selectors are relative to the `context`,
    which means that no parent elements of the context will be matched. (Eg.
    `a b c` with context `b` will never give any results.) If `relativeSelector`
    is set to `false`, selectors won't be
    [absolutized](http://www.w3.org/TR/selectors4/#absolutizing) and selectors
    can test for parent elements outside of the `context`.
-   `cacheResults`: Allow css-select to cache results for some selectors,
    sometimes greatly improving querying performance. Disable this if your
    document can change in between queries with the same compiled selector.
    Default: `true`.
-   `pseudos`: A map of pseudo-class names to functions or strings.

#### Custom Adapters

A custom adapter must match the interface described
[here](https://github.com/fb55/css-select/blob/1aa44bdd64aaf2ebdfd7f338e2e76bed36521957/src/types.ts#L6-L96).

You may want to have a look at [`domutils`](https://github.com/fb55/domutils) to
see the default implementation, or at
[`css-select-browser-adapter`](https://github.com/nrkn/css-select-browser-adapter/blob/master/index.js)
for an implementation backed by the DOM.

## Supported selectors

_As defined by CSS 4 and / or jQuery._

-   [Selector lists](https://developer.mozilla.org/en-US/docs/Web/CSS/Selector_list)
    (`,`)
-   [Universal](https://developer.mozilla.org/en-US/docs/Web/CSS/Universal_selectors)
    (`*`)
-   [Type](https://developer.mozilla.org/en-US/docs/Web/CSS/Type_selectors)
    (`<tagname>`)
-   [Descendant](https://developer.mozilla.org/en-US/docs/Web/CSS/Descendant_combinator)
    (` `)
-   [Child](https://developer.mozilla.org/en-US/docs/Web/CSS/Child_combinator)
    (`>`)
-   Parent (`<`)
-   [Adjacent sibling](https://developer.mozilla.org/en-US/docs/Web/CSS/Adjacent_sibling_combinator)
    (`+`)
-   [General sibling](https://developer.mozilla.org/en-US/docs/Web/CSS/General_sibling_combinator)
    (`~`)
-   [Attribute](https://developer.mozilla.org/en-US/docs/Web/CSS/Attribute_selectors)
    (`[attr=foo]`), with supported comparisons:
    -   `[attr]` (existential)
    -   `=`
    -   `~=`
    -   `|=`
    -   `*=`
    -   `^=`
    -   `$=`
    -   `!=`
    -   `i` and `s` can be added after the comparison to make the comparison
        case-insensitive or case-sensitive (eg. `[attr=foo i]`). If neither is
        supplied, css-select will follow the HTML spec's
        [case-sensitivity rules](https://html.spec.whatwg.org/multipage/semantics-other.html#case-sensitivity-of-selectors).
-   Pseudos:
    -   [`:not`](https://developer.mozilla.org/en-US/docs/Web/CSS/:not)
    -   [`:contains`](https://api.jquery.com/contains-selector)
    -   `:icontains` (case-insensitive version of `:contains`)
    -   [`:has`](https://developer.mozilla.org/en-US/docs/Web/CSS/:has)
    -   [`:root`](https://developer.mozilla.org/en-US/docs/Web/CSS/:root)
    -   [`:empty`](https://developer.mozilla.org/en-US/docs/Web/CSS/:empty)
    -   [`:parent`](https://api.jquery.com/parent-selector)
    -   [`:first-child`](https://developer.mozilla.org/en-US/docs/Web/CSS/:first-child),
        [`:last-child`](https://developer.mozilla.org/en-US/docs/Web/CSS/:last-child),
        [`:first-of-type`](https://developer.mozilla.org/en-US/docs/Web/CSS/:first-of-type),
        [`:last-of-type`](https://developer.mozilla.org/en-US/docs/Web/CSS/:last-of-type)
    -   [`:only-of-type`](https://developer.mozilla.org/en-US/docs/Web/CSS/:only-of-type),
        [`:only-child`](https://developer.mozilla.org/en-US/docs/Web/CSS/:only-child)
    -   [`:nth-child`](https://developer.mozilla.org/en-US/docs/Web/CSS/:nth-child),
        [`:nth-last-child`](https://developer.mozilla.org/en-US/docs/Web/CSS/:nth-last-child),
        [`:nth-of-type`](https://developer.mozilla.org/en-US/docs/Web/CSS/:nth-of-type),
        [`:nth-last-of-type`](https://developer.mozilla.org/en-US/docs/Web/CSS/:nth-last-of-type),
    -   [`:link`](https://developer.mozilla.org/en-US/docs/Web/CSS/:link),
        [`:any-link`](https://developer.mozilla.org/en-US/docs/Web/CSS/:any-link)
    -   [`:visited`](https://developer.mozilla.org/en-US/docs/Web/CSS/:visited),
        [`:hover`](https://developer.mozilla.org/en-US/docs/Web/CSS/:hover),
        [`:active`](https://developer.mozilla.org/en-US/docs/Web/CSS/:active)
        (these depend on optional `Adapter` methods, so these will only match
        elements if implemented in `Adapter`)
    -   [`:selected`](https://api.jquery.com/selected-selector),
        [`:checked`](https://developer.mozilla.org/en-US/docs/Web/CSS/:checked)
    -   [`:enabled`](https://developer.mozilla.org/en-US/docs/Web/CSS/:enabled),
        [`:disabled`](https://developer.mozilla.org/en-US/docs/Web/CSS/:disabled)
    -   [`:required`](https://developer.mozilla.org/en-US/docs/Web/CSS/:required),
        [`:optional`](https://developer.mozilla.org/en-US/docs/Web/CSS/:optional)
    -   [`:header`](https://api.jquery.com/header-selector),
        [`:button`](https://api.jquery.com/button-selector),
        [`:input`](https://api.jquery.com/input-selector),
        [`:text`](https://api.jquery.com/text-selector),
        [`:checkbox`](https://api.jquery.com/checkbox-selector),
        [`:file`](https://api.jquery.com/file-selector),
        [`:password`](https://api.jquery.com/password-selector),
        [`:reset`](https://api.jquery.com/reset-selector),
        [`:radio`](https://api.jquery.com/radio-selector) etc.
    -   [`:is`](https://developer.mozilla.org/en-US/docs/Web/CSS/:is), plus its
        legacy alias `:matches`
    -   [`:scope`](https://developer.mozilla.org/en-US/docs/Web/CSS/:scope)
        (uses the context from the passed options)

---

License: BSD-2-Clause

## Security contact information

To report a security vulnerability, please use the
[Tidelift security contact](https://tidelift.com/security). Tidelift will
coordinate the fix and disclosure.

## `css-select` for enterprise

Available as part of the Tidelift Subscription

The maintainers of `css-select` and thousands of other packages are working with
Tidelift to deliver commercial support and maintenance for the open source
dependencies you use to build your applications. Save time, reduce risk, and
improve code health, while paying the maintainers of the exact dependencies you
use.
[Learn more.](https://tidelift.com/subscription/pkg/npm-css-select?utm_source=npm-css-select&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)


---

<img align="right" width="111" height="111"
     alt="CSSTree logo"
     src="https://cloud.githubusercontent.com/assets/270491/19243723/6f9136c6-8f21-11e6-82ac-eeeee4c6c452.png"/>

# CSSTree

[![NPM version](https://img.shields.io/npm/v/css-tree.svg)](https://www.npmjs.com/package/css-tree)
[![Build Status](https://github.com/csstree/csstree/actions/workflows/build.yml/badge.svg)](https://github.com/csstree/csstree/actions/workflows/build.yml)
[![Coverage Status](https://coveralls.io/repos/github/csstree/csstree/badge.svg?branch=master)](https://coveralls.io/github/csstree/csstree?branch=master)
[![NPM Downloads](https://img.shields.io/npm/dm/css-tree.svg)](https://www.npmjs.com/package/css-tree)
[![Twitter](https://img.shields.io/badge/Twitter-@csstree-blue.svg)](https://twitter.com/csstree)

CSSTree is a tool set for CSS: [fast](https://github.com/postcss/benchmark) detailed parser (CSS → AST), walker (AST traversal), generator (AST → CSS) and lexer (validation and matching) based on specs and browser implementations. The main goal is to be efficient and W3C spec compliant, with focus on CSS analyzing and source-to-source transforming tasks.

## Features

- **Detailed parsing with an adjustable level of detail**

  By default CSSTree parses CSS as detailed as possible, i.e. each single logical part is representing with its own AST node (see [AST format](docs/ast.md) for all possible node types). The parsing detail level can be changed through [parser options](docs/parsing.md#parsesource-options), for example, you can disable parsing of selectors or declaration values for component parts.

- **Tolerant to errors by design**

  Parser behaves as [spec says](https://www.w3.org/TR/css-syntax-3/#error-handling): "When errors occur in CSS, the parser attempts to recover gracefully, throwing away only the minimum amount of content before returning to parsing as normal". The only thing the parser departs from the specification is that it doesn't throw away bad content, but wraps it in a special node type (`Raw`) that allows processing it later.

- **Fast and efficient**

  CSSTree is created with focus on performance and effective memory consumption. Therefore it's [one of the fastest CSS parsers](https://github.com/postcss/benchmark) at the moment.

- **Syntax validation**

  The build-in lexer can test CSS against syntaxes defined by W3C. CSSTree uses [mdn/data](https://github.com/mdn/data/) as a basis for lexer's dictionaries and extends it with vendor specific and legacy syntaxes. Lexer can only check the declaration values currently, but this feature will be extended to other parts of the CSS in the future.

## Projects using CSSTree

- [Svelte](https://github.com/sveltejs/svelte) – Cybernetically enhanced web apps
- [SVGO](https://github.com/svg/svgo) – Node.js tool for optimizing SVG files
- [CSSO](https://github.com/css/csso) – CSS minifier with structural optimizations
- [NativeScript](https://github.com/NativeScript/NativeScript) – NativeScript empowers you to access native APIs from JavaScript directly
- [react-native-svg](https://github.com/react-native-svg/react-native-svg) – SVG library for React Native, React Native Web, and plain React web projects
- [penthouse](https://github.com/pocketjoso/penthouse) – Critical Path CSS Generator
- [Bit](https://github.com/teambit/bit) – Bit is the platform for collaborating on components
- and more...

## Documentation

- [AST format](docs/ast.md)
- [Parsing CSS → AST](docs/parsing.md)
  - [parse(source[, options])](docs/parsing.md#parsesource-options)
- [Serialization AST → CSS](docs/generate.md)
  - [generate(ast[, options])](docs/generate.md#generateast-options)
- [AST traversal](docs/traversal.md)
  - [walk(ast, options)](docs/traversal.md#walkast-options)
  - [find(ast, fn)](docs/traversal.md#findast-fn)
  - [findLast(ast, fn)](docs/traversal.md#findlastast-fn)
  - [findAll(ast, fn)](docs/traversal.md#findallast-fn)
- [Util functions](docs/utils.md)
  - Value encoding & decoding
    - [property(name)](docs/utils.md#propertyname)
    - [keyword(name)](docs/utils.md#keywordname)
    - [ident](docs/utils.md#ident)
    - [string](docs/utils.md#string)
    - [url](docs/utils.md#url)
  - AST transforming
    - [clone(ast)](docs/utils.md#cloneast)
    - [fromPlainObject(object)](docs/utils.md#fromplainobjectobject)
    - [toPlainObject(ast)](docs/utils.md#toplainobjectast)
- [Value Definition Syntax](docs/definition-syntax.md)
  - [parse(source)](docs/definition-syntax.md#parsesource)
  - [walk(node, options, context)](docs/definition-syntax.md#walknode-options-context)
  - [generate(node, options)](docs/definition-syntax.md#generatenode-options)
  - [AST format](docs/definition-syntax.md#ast-format)

## Tools

* [AST Explorer](https://astexplorer.net/#/gist/244e2fb4da940df52bf0f4b94277db44/e79aff44611020b22cfd9708f3a99ce09b7d67a8) – explore CSSTree AST format with zero setup
* [CSS syntax reference](https://csstree.github.io/docs/syntax.html)
* [CSS syntax validator](https://csstree.github.io/docs/validator.html)

## Related projects

* [csstree-validator](https://github.com/csstree/validator) – NPM package to validate CSS
* [stylelint-csstree-validator](https://github.com/csstree/stylelint-validator) – plugin for stylelint to validate CSS
* [Grunt plugin](https://github.com/sergejmueller/grunt-csstree-validator)
* [Gulp plugin](https://github.com/csstree/gulp-csstree)
* [Sublime plugin](https://github.com/csstree/SublimeLinter-contrib-csstree)
* [VS Code plugin](https://github.com/csstree/vscode-plugin)
* [Atom plugin](https://github.com/csstree/atom-plugin)

## Usage

Install with npm:

```
npm install css-tree
```

Basic usage:

```js
import * as csstree from 'css-tree';

// parse CSS to AST
const ast = csstree.parse('.example { world: "!" }');

// traverse AST and modify it
csstree.walk(ast, (node) => {
    if (node.type === 'ClassSelector' && node.name === 'example') {
        node.name = 'hello';
    }
});

// generate CSS from AST
console.log(csstree.generate(ast));
// .hello{world:"!"}
```

Syntax matching:

```js
// parse CSS to AST as a declaration value
const ast = csstree.parse('red 1px solid', { context: 'value' });

// match to syntax of `border` property
const matchResult = csstree.lexer.matchProperty('border', ast);

// check first value node is a <color>
console.log(matchResult.isType(ast.children.first, 'color'));
// true

// get a type list matched to a node
console.log(matchResult.getTrace(ast.children.first));
// [ { type: 'Property', name: 'border' },
//   { type: 'Type', name: 'color' },
//   { type: 'Type', name: 'named-color' },
//   { type: 'Keyword', name: 'red' } ]
```

### Exports

Is it possible to import just a needed part of library like a parser or a walker. That's might useful for loading time or bundle size optimisations. 

```js
import * as tokenizer from 'css-tree/tokenizer';
import * as parser from 'css-tree/parser';
import * as walker from 'css-tree/walker';
import * as lexer from 'css-tree/lexer';
import * as definitionSyntax from 'css-tree/definition-syntax';
import * as data from 'css-tree/definition-syntax-data';
import * as dataPatch from 'css-tree/definition-syntax-data-patch';
import * as utils from 'css-tree/utils';
```

### Using in a browser

Bundles are available for use in a browser:

- `dist/csstree.js` – minified IIFE with `csstree` as global
```html
<script src="node_modules/css-tree/dist/csstree.js"></script>
<script>
  csstree.parse('.example { color: green }');
</script>
```

- `dist/csstree.esm.js` – minified ES module
```html
<script type="module">
  import { parse } from 'node_modules/css-tree/dist/csstree.esm.js'
  parse('.example { color: green }');
</script>
```

One of CDN services like `unpkg` or `jsDelivr` can be used. By default (for short path) a ESM version is exposing. For IIFE version a full path to a bundle should be specified:

```html
<!-- ESM -->
<script type="module">
  import * as csstree from 'https://cdn.jsdelivr.net/npm/css-tree';
  import * as csstree from 'https://unpkg.com/css-tree';
</script>

<!-- IIFE with an export to global -->
<script src="https://cdn.jsdelivr.net/npm/css-tree/dist/csstree.js"></script>
<script src="https://unpkg.com/css-tree/dist/csstree.js"></script>
```

## Top level API

![API map](https://cdn.rawgit.com/csstree/csstree/aaf327e/docs/api-map.svg)

## License

MIT


---

# css-what

[![Build Status](https://img.shields.io/github/workflow/status/fb55/css-what/Node.js%20CI/master)](https://github.com/fb55/css-what/actions/workflows/nodejs-test.yml)
[![Coverage](https://img.shields.io/coveralls/github/fb55/css-what/master)](https://coveralls.io/github/fb55/css-what?branch=master)

A CSS selector parser.

## Example

```js
import * as CSSwhat from "css-what";

CSSwhat.parse("foo[bar]:baz")

~> [
    [
        { type: "tag", name: "foo" },
        {
            type: "attribute",
            name: "bar",
            action: "exists",
            value: "",
            ignoreCase: null
        },
        { type: "pseudo", name: "baz", data: null }
    ]
]
```

## API

**`CSSwhat.parse(selector)` - Parses `selector`.**

The function returns a two-dimensional array. The first array represents selectors separated by commas (eg. `sub1, sub2`), the second contains the relevant tokens for that selector. Possible token types are:

| name                | properties                              | example       | output                                                                                   |
| ------------------- | --------------------------------------- | ------------- | ---------------------------------------------------------------------------------------- |
| `tag`               | `name`                                  | `div`         | `{ type: 'tag', name: 'div' }`                                                           |
| `universal`         | -                                       | `*`           | `{ type: 'universal' }`                                                                  |
| `pseudo`            | `name`, `data`                          | `:name(data)` | `{ type: 'pseudo', name: 'name', data: 'data' }`                                         |
| `pseudo`            | `name`, `data`                          | `:name`       | `{ type: 'pseudo', name: 'name', data: null }`                                           |
| `pseudo-element`    | `name`                                  | `::name`      | `{ type: 'pseudo-element', name: 'name' }`                                               |
| `attribute`         | `name`, `action`, `value`, `ignoreCase` | `[attr]`      | `{ type: 'attribute', name: 'attr', action: 'exists', value: '', ignoreCase: false }`    |
| `attribute`         | `name`, `action`, `value`, `ignoreCase` | `[attr=val]`  | `{ type: 'attribute', name: 'attr', action: 'equals', value: 'val', ignoreCase: false }` |
| `attribute`         | `name`, `action`, `value`, `ignoreCase` | `[attr^=val]` | `{ type: 'attribute', name: 'attr', action: 'start', value: 'val', ignoreCase: false }`  |
| `attribute`         | `name`, `action`, `value`, `ignoreCase` | `[attr$=val]` | `{ type: 'attribute', name: 'attr', action: 'end', value: 'val', ignoreCase: false }`    |
| `child`             | -                                       | `>`           | `{ type: 'child' }`                                                                      |
| `parent`            | -                                       | `<`           | `{ type: 'parent' }`                                                                     |
| `sibling`           | -                                       | `~`           | `{ type: 'sibling' }`                                                                    |
| `adjacent`          | -                                       | `+`           | `{ type: 'adjacent' }`                                                                   |
| `descendant`        | -                                       |               | `{ type: 'descendant' }`                                                                 |
| `column-combinator` | -                                       | `\|\|`        | `{ type: 'column-combinator' }`                                                          |

**`CSSwhat.stringify(selector)` - Turns `selector` back into a string.**

---

License: BSD-2-Clause

## Security contact information

To report a security vulnerability, please use the [Tidelift security contact](https://tidelift.com/security).
Tidelift will coordinate the fix and disclosure.

## `css-what` for enterprise

Available as part of the Tidelift Subscription

The maintainers of `css-what` and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-css-what?utm_source=npm-css-what&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)


---

MIT No Attribution (MIT-0)

Copyright © CSS Tools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# cssdb [<img src="https://cssdb.org/images/css.svg" alt="" width="90" height="90" align="right">][cssdb]

[![NPM Version][npm-img]][npm-url]
[![Build Status][cli-img]][cli-url]

[cssdb] is a comprehensive list of CSS features and their positions in
the process of becoming implemented web standards.

---

Did you come here to update the status of a CSS feature or add a new one?
Quick, read [CONTRIBUTING.md](CONTRIBUTING.md).

Did you come here to learn about the stages? Quick, read [STAGES.md](STAGES.md).

---

[cssdb] ranks CSS features by stages that reflect the real-life stability of
new CSS features.

You can read an [inside view of the CSSWG] to learn about the official
(and unofficial) development stages of CSS specifications. In reality,
specifications and browser implementations happen out of sync. For example,
there are stable CSS features missing in all browsers, while other CSS features
developed outside the [CSSWG] have appeared in browsers behind flags. This is
too ambiguous for the web development community, and a more accountable process
is desired.

[cli-img]: https://github.com/csstools/cssdb/actions/workflows/test.yml/badge.svg
[cli-url]: https://github.com/csstools/cssdb/actions/workflows/test.yml
[cssdb]: https://github.com/csstools/cssdb
[CSSWG]: https://wiki.csswg.org/spec
[inside view of the CSSWG]: https://fantasai.inkedblade.net/weblog/2011/inside-csswg/process
[npm-img]: https://img.shields.io/npm/v/cssdb.svg
[npm-url]: https://www.npmjs.com/package/cssdb


---

# cssesc [![Build status](https://travis-ci.org/mathiasbynens/cssesc.svg?branch=master)](https://travis-ci.org/mathiasbynens/cssesc) [![Code coverage status](https://img.shields.io/codecov/c/github/mathiasbynens/cssesc.svg)](https://codecov.io/gh/mathiasbynens/cssesc)

A JavaScript library for escaping CSS strings and identifiers while generating the shortest possible ASCII-only output.

This is a JavaScript library for [escaping text for use in CSS strings or identifiers](https://mathiasbynens.be/notes/css-escapes) while generating the shortest possible valid ASCII-only output. [Here’s an online demo.](https://mothereff.in/css-escapes)

[A polyfill for the CSSOM `CSS.escape()` method is available in a separate repository.](https://mths.be/cssescape) (In comparison, _cssesc_ is much more powerful.)

Feel free to fork if you see possible improvements!

## Installation

Via [npm](https://www.npmjs.com/):

```bash
npm install cssesc
```

In a browser:

```html
<script src="cssesc.js"></script>
```

In [Node.js](https://nodejs.org/):

```js
const cssesc = require('cssesc');
```

In Ruby using [the `ruby-cssesc` wrapper gem](https://github.com/borodean/ruby-cssesc):

```bash
gem install ruby-cssesc
```

```ruby
require 'ruby-cssesc'
CSSEsc.escape('I ♥ Ruby', is_identifier: true)
```

In Sass using [`sassy-escape`](https://github.com/borodean/sassy-escape):

```bash
gem install sassy-escape
```

```scss
body {
  content: escape('I ♥ Sass', $is-identifier: true);
}
```

## API

### `cssesc(value, options)`

This function takes a value and returns an escaped version of the value where any characters that are not printable ASCII symbols are escaped using the shortest possible (but valid) [escape sequences for use in CSS strings or identifiers](https://mathiasbynens.be/notes/css-escapes).

```js
cssesc('Ich ♥ Bücher');
// → 'Ich \\2665  B\\FC cher'

cssesc('foo 𝌆 bar');
// → 'foo \\1D306  bar'
```

By default, `cssesc` returns a string that can be used as part of a CSS string. If the target is a CSS identifier rather than a CSS string, use the `isIdentifier: true` setting (see below).

The optional `options` argument accepts an object with the following options:

#### `isIdentifier`

The default value for the `isIdentifier` option is `false`. This means that the input text will be escaped for use in a CSS string literal. If you want to use the result as a CSS identifier instead (in a selector, for example), set this option to `true`.

```js
cssesc('123a2b');
// → '123a2b'

cssesc('123a2b', {
  'isIdentifier': true
});
// → '\\31 23a2b'
```

#### `quotes`

The default value for the `quotes` option is `'single'`. This means that any occurences of `'` in the input text will be escaped as `\'`, so that the output can be used in a CSS string literal wrapped in single quotes.

```js
cssesc('Lorem ipsum "dolor" sit \'amet\' etc.');
// → 'Lorem ipsum "dolor" sit \\\'amet\\\' etc.'
// → "Lorem ipsum \"dolor\" sit \\'amet\\' etc."

cssesc('Lorem ipsum "dolor" sit \'amet\' etc.', {
  'quotes': 'single'
});
// → 'Lorem ipsum "dolor" sit \\\'amet\\\' etc.'
// → "Lorem ipsum \"dolor\" sit \\'amet\\' etc."
```

If you want to use the output as part of a CSS string literal wrapped in double quotes, set the `quotes` option to `'double'`.

```js
cssesc('Lorem ipsum "dolor" sit \'amet\' etc.', {
  'quotes': 'double'
});
// → 'Lorem ipsum \\"dolor\\" sit \'amet\' etc.'
// → "Lorem ipsum \\\"dolor\\\" sit 'amet' etc."
```

#### `wrap`

The `wrap` option takes a boolean value (`true` or `false`), and defaults to `false` (disabled). When enabled, the output will be a valid CSS string literal wrapped in quotes. The type of quotes can be specified through the `quotes` setting.

```js
cssesc('Lorem ipsum "dolor" sit \'amet\' etc.', {
  'quotes': 'single',
  'wrap': true
});
// → '\'Lorem ipsum "dolor" sit \\\'amet\\\' etc.\''
// → "\'Lorem ipsum \"dolor\" sit \\\'amet\\\' etc.\'"

cssesc('Lorem ipsum "dolor" sit \'amet\' etc.', {
  'quotes': 'double',
  'wrap': true
});
// → '"Lorem ipsum \\"dolor\\" sit \'amet\' etc."'
// → "\"Lorem ipsum \\\"dolor\\\" sit \'amet\' etc.\""
```

#### `escapeEverything`

The `escapeEverything` option takes a boolean value (`true` or `false`), and defaults to `false` (disabled). When enabled, all the symbols in the output will be escaped, even printable ASCII symbols.

```js
cssesc('lolwat"foo\'bar', {
  'escapeEverything': true
});
// → '\\6C\\6F\\6C\\77\\61\\74\\"\\66\\6F\\6F\\\'\\62\\61\\72'
// → "\\6C\\6F\\6C\\77\\61\\74\\\"\\66\\6F\\6F\\'\\62\\61\\72"
```

#### Overriding the default options globally

The global default settings can be overridden by modifying the `css.options` object. This saves you from passing in an `options` object for every call to `encode` if you want to use the non-default setting.

```js
// Read the global default setting for `escapeEverything`:
cssesc.options.escapeEverything;
// → `false` by default

// Override the global default setting for `escapeEverything`:
cssesc.options.escapeEverything = true;

// Using the global default setting for `escapeEverything`, which is now `true`:
cssesc('foo © bar ≠ baz 𝌆 qux');
// → '\\66\\6F\\6F\\ \\A9\\ \\62\\61\\72\\ \\2260\\ \\62\\61\\7A\\ \\1D306\\ \\71\\75\\78'
```

### `cssesc.version`

A string representing the semantic version number.

### Using the `cssesc` binary

To use the `cssesc` binary in your shell, simply install cssesc globally using npm:

```bash
npm install -g cssesc
```

After that you will be able to escape text for use in CSS strings or identifiers from the command line:

```bash
$ cssesc 'föo ♥ bår 𝌆 baz'
f\F6o \2665  b\E5r \1D306  baz
```

If the output needs to be a CSS identifier rather than part of a string literal, use the `-i`/`--identifier` option:

```bash
$ cssesc --identifier 'föo ♥ bår 𝌆 baz'
f\F6o\ \2665\ b\E5r\ \1D306\ baz
```

See `cssesc --help` for the full list of options.

## Support

This library supports the Node.js and browser versions mentioned in [`.babelrc`](https://github.com/mathiasbynens/cssesc/blob/master/.babelrc). For a version that supports a wider variety of legacy browsers and environments out-of-the-box, [see v0.1.0](https://github.com/mathiasbynens/cssesc/releases/tag/v0.1.0).

## Author

| [![twitter/mathias](https://gravatar.com/avatar/24e08a9ea84deb17ae121074d0f17125?s=70)](https://twitter.com/mathias "Follow @mathias on Twitter") |
|---|
| [Mathias Bynens](https://mathiasbynens.be/) |

## License

This library is available under the [MIT](https://mths.be/mit) license.


---

# cssnano

For documentation, please see the following links:

* Repository: https://github.com/cssnano/cssnano
* Website: http://cssnano.github.io/cssnano


---

# cssnano-preset-advanced

> Advanced optimisations for cssnano; may or may not break your CSS!

## Table of Contents

- [Usage](#usage)

  - [Install](#install)
  - [Configuration](#configuration)

- [Plugins](#plugins)

  - [autoprefixer (external)](#autoprefixer-external)
  - [css-declaration-sorter (external)](#css-declaration-sorter-external)
  - [cssnano-utils](#cssnano-utils)
  - [postcss-calc (external)](#postcss-calc-external)
  - [postcss-colormin](#postcss-colormin)
  - [postcss-convert-values](#postcss-convert-values)
  - [postcss-discard-comments](#postcss-discard-comments)
  - [postcss-discard-duplicates](#postcss-discard-duplicates)
  - [postcss-discard-empty](#postcss-discard-empty)
  - [postcss-discard-overridden](#postcss-discard-overridden)
  - [postcss-discard-unused](#postcss-discard-unused)
  - [postcss-merge-idents](#postcss-merge-idents)
  - [postcss-merge-longhand](#postcss-merge-longhand)
  - [postcss-merge-rules](#postcss-merge-rules)
  - [postcss-minify-font-values](#postcss-minify-font-values)
  - [postcss-minify-gradients](#postcss-minify-gradients)
  - [postcss-minify-params](#postcss-minify-params)
  - [postcss-minify-selectors](#postcss-minify-selectors)
  - [postcss-normalize-charset](#postcss-normalize-charset)
  - [postcss-normalize-display-values](#postcss-normalize-display-values)
  - [postcss-normalize-positions](#postcss-normalize-positions)
  - [postcss-normalize-repeat-style](#postcss-normalize-repeat-style)
  - [postcss-normalize-string](#postcss-normalize-string)
  - [postcss-normalize-timing-functions](#postcss-normalize-timing-functions)
  - [postcss-normalize-unicode](#postcss-normalize-unicode)
  - [postcss-normalize-url](#postcss-normalize-url)
  - [postcss-normalize-whitespace](#postcss-normalize-whitespace)
  - [postcss-ordered-values](#postcss-ordered-values)
  - [postcss-reduce-idents](#postcss-reduce-idents)
  - [postcss-reduce-initial](#postcss-reduce-initial)
  - [postcss-reduce-transforms](#postcss-reduce-transforms)
  - [postcss-svgo](#postcss-svgo)
  - [postcss-unique-selectors](#postcss-unique-selectors)
  - [postcss-zindex](#postcss-zindex)

- [Contributors](#contributors)

- [License](#license)

## Usage

### Install

With [npm](https://npmjs.com/package/cssnano-preset-advanced) do:

    npm install cssnano-preset-advanced --save-dev

If you don't have npm then [check out this installation tutorial](https://npmjs.com/package/cssnano-preset-advanced/tutorial).

### Configuration

If you would like to use the preset in its default configuration, specify a section in your `package.json`:

```diff
 {
   "name": "awesome-application",
+  "cssnano": {
+    "preset": "advanced"
+  }
 }
```

But should you wish to customise this, you can pass an array with the second parameter as the options object to use. For example, to remove all comments:

```diff
 {
   "name": "awesome-application",
+  "cssnano": {
+    "preset": [
+      "advanced",
+      {"discardComments": {"removeAll": true}}
+    ]
+  }
 }
```

Depending on your usage, the JSON configuration might not work for you, such as in cases where you would like to use options with customisable function parameters. For this use case, we recommend a `cssnano.config.js` at the same location as your `package.json`. You can then load a preset and export it with your custom parameters:

```js
const advancedPreset = require('cssnano-preset-advanced');

module.exports = advancedPreset({
  discardComments: {
    remove: (comment) => comment[0] === '@',
  },
});
```

Note that you may wish to publish your own preset to npm for reusability, should it differ a lot from this one. This is highly encouraged!

## Plugins

### [`autoprefixer`](https://github.com/postcss/autoprefixer) (external)

> Parse CSS and add vendor prefixes to CSS rules using values from the Can I Use website

This plugin is loaded with the following configuration:

```js
{
  add: false;
}
```

### [`css-declaration-sorter`](https://github.com/Siilwyn/css-declaration-sorter) (external)

> Sorts CSS declarations fast and automatically in a certain order.

This plugin is loaded with the following configuration:

```js
{
  exclude: true;
}
```

### [`cssnano-utils`](https://github.com/cssnano/cssnano/tree/master/packages/cssnano-utils)

> Utility methods used by cssnano

### [`postcss-calc`](https://github.com/postcss/postcss-calc) (external)

> PostCSS plugin to reduce calc()

This plugin is loaded with its default configuration.

### [`postcss-colormin`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-colormin)

> Minify colors in your CSS files with PostCSS.

This plugin is loaded with its default configuration.

### [`postcss-convert-values`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-convert-values)

> Convert values with PostCSS (e.g. ms -> s)

This plugin is loaded with the following configuration:

```js
{
  length: false;
}
```

### [`postcss-discard-comments`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-discard-comments)

> Discard comments in your CSS files with PostCSS.

This plugin is loaded with its default configuration.

### [`postcss-discard-duplicates`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-discard-duplicates)

> Discard duplicate rules in your CSS files with PostCSS.

This plugin is loaded with its default configuration.

### [`postcss-discard-empty`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-discard-empty)

> Discard empty rules and values with PostCSS.

This plugin is loaded with its default configuration.

### [`postcss-discard-overridden`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-discard-overridden)

> PostCSS plugin to discard overridden @keyframes or @counter-style.

This plugin is loaded with its default configuration.

### [`postcss-discard-unused`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-discard-unused)

> Discard unused counter styles, keyframes and fonts.

This plugin is loaded with its default configuration.

### [`postcss-merge-idents`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-merge-idents)

> Merge keyframe and counter style identifiers.

This plugin is loaded with its default configuration.

### [`postcss-merge-longhand`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-merge-longhand)

> Merge longhand properties into shorthand with PostCSS.

This plugin is loaded with its default configuration.

### [`postcss-merge-rules`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-merge-rules)

> Merge CSS rules with PostCSS.

This plugin is loaded with its default configuration.

### [`postcss-minify-font-values`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-minify-font-values)

> Minify font declarations with PostCSS

This plugin is loaded with its default configuration.

### [`postcss-minify-gradients`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-minify-gradients)

> Minify gradient parameters with PostCSS.

This plugin is loaded with its default configuration.

### [`postcss-minify-params`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-minify-params)

> Minify at-rule params with PostCSS

This plugin is loaded with its default configuration.

### [`postcss-minify-selectors`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-minify-selectors)

> Minify selectors with PostCSS.

This plugin is loaded with its default configuration.

### [`postcss-normalize-charset`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-normalize-charset)

> Add necessary or remove extra charset with PostCSS

This plugin is loaded with the following configuration:

```js
{
  add: false;
}
```

### [`postcss-normalize-display-values`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-normalize-display-values)

> Normalize multiple value display syntaxes into single values.

This plugin is loaded with its default configuration.

### [`postcss-normalize-positions`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-normalize-positions)

> Normalize keyword values for position into length values.

This plugin is loaded with its default configuration.

### [`postcss-normalize-repeat-style`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-normalize-repeat-style)

> Convert two value syntax for repeat-style into one value.

This plugin is loaded with its default configuration.

### [`postcss-normalize-string`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-normalize-string)

> Normalize wrapping quotes for CSS string literals.

This plugin is loaded with its default configuration.

### [`postcss-normalize-timing-functions`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-normalize-timing-functions)

> Normalize CSS animation/transition timing functions.

This plugin is loaded with its default configuration.

### [`postcss-normalize-unicode`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-normalize-unicode)

> Normalize unicode-range descriptors, and can convert to wildcard ranges.

This plugin is loaded with its default configuration.

### [`postcss-normalize-url`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-normalize-url)

> Normalize URLs with PostCSS

This plugin is loaded with its default configuration.

### [`postcss-normalize-whitespace`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-normalize-whitespace)

> Trim whitespace inside and around CSS rules & declarations.

This plugin is loaded with its default configuration.

### [`postcss-ordered-values`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-ordered-values)

> Ensure values are ordered consistently in your CSS.

This plugin is loaded with its default configuration.

### [`postcss-reduce-idents`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-reduce-idents)

> Reduce custom identifiers with PostCSS.

This plugin is loaded with its default configuration.

### [`postcss-reduce-initial`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-reduce-initial)

> Reduce initial definitions to the actual initial value, where possible.

This plugin is loaded with its default configuration.

### [`postcss-reduce-transforms`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-reduce-transforms)

> Reduce transform functions with PostCSS.

This plugin is loaded with its default configuration.

### [`postcss-svgo`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-svgo)

> Optimise inline SVG with PostCSS.

This plugin is loaded with its default configuration.

### [`postcss-unique-selectors`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-unique-selectors)

> Ensure CSS selectors are unique.

This plugin is loaded with its default configuration.

### [`postcss-zindex`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-zindex)

> Reduce z-index values with PostCSS.

This plugin is loaded with its default configuration.

## Contributors

See [CONTRIBUTORS.md](https://github.com/cssnano/cssnano/blob/master/CONTRIBUTORS.md).

## License

MIT © [Ben Briggs](http://beneb.info)


---

# cssnano-preset-default

> Safe defaults for cssnano which require minimal configuration.

## Table of Contents

- [Overview](#overview)

- [Usage](#usage)

  - [Install](#install)
  - [Configuration](#configuration)

- [Plugins](#plugins)

  - [css-declaration-sorter (external)](#css-declaration-sorter-external)
  - [cssnano-utils](#cssnano-utils)
  - [postcss-calc (external)](#postcss-calc-external)
  - [postcss-colormin](#postcss-colormin)
  - [postcss-convert-values](#postcss-convert-values)
  - [postcss-discard-comments](#postcss-discard-comments)
  - [postcss-discard-duplicates](#postcss-discard-duplicates)
  - [postcss-discard-empty](#postcss-discard-empty)
  - [postcss-discard-overridden](#postcss-discard-overridden)
  - [postcss-merge-longhand](#postcss-merge-longhand)
  - [postcss-merge-rules](#postcss-merge-rules)
  - [postcss-minify-font-values](#postcss-minify-font-values)
  - [postcss-minify-gradients](#postcss-minify-gradients)
  - [postcss-minify-params](#postcss-minify-params)
  - [postcss-minify-selectors](#postcss-minify-selectors)
  - [postcss-normalize-charset](#postcss-normalize-charset)
  - [postcss-normalize-display-values](#postcss-normalize-display-values)
  - [postcss-normalize-positions](#postcss-normalize-positions)
  - [postcss-normalize-repeat-style](#postcss-normalize-repeat-style)
  - [postcss-normalize-string](#postcss-normalize-string)
  - [postcss-normalize-timing-functions](#postcss-normalize-timing-functions)
  - [postcss-normalize-unicode](#postcss-normalize-unicode)
  - [postcss-normalize-url](#postcss-normalize-url)
  - [postcss-normalize-whitespace](#postcss-normalize-whitespace)
  - [postcss-ordered-values](#postcss-ordered-values)
  - [postcss-reduce-initial](#postcss-reduce-initial)
  - [postcss-reduce-transforms](#postcss-reduce-transforms)
  - [postcss-svgo](#postcss-svgo)
  - [postcss-unique-selectors](#postcss-unique-selectors)

- [Contributors](#contributors)

- [License](#license)

## Overview

This default preset for cssnano only includes transforms that make no
assumptions about your CSS other than what is passed in. In previous
iterations of cssnano, assumptions were made about your CSS which caused
output to look different in certain use cases, but not others. These
transforms have been moved from the defaults to other presets, to make
this preset require only minimal configuration.

## Usage

### Install

Note that this preset comes bundled with cssnano _by default_, so you don't need to install it separately.

### Configuration

If you would like to use the default configuration, then you don't need to add anything to your `package.json`.

But should you wish to customise this, you can pass an array with the second parameter as the options object to use. For example, to remove all comments:

```diff
 {
   "name": "awesome-application",
+  "cssnano": {
+    "preset": [
+      "default",
+      {"discardComments": {"removeAll": true}}
+    ]
+  }
 }
```

Depending on your usage, the JSON configuration might not work for you, such as in cases where you would like to use options with customisable function parameters. For this use case, we recommend a `cssnano.config.js` at the same location as your `package.json`. You can then load a preset and export it with your custom parameters:

```js
const defaultPreset = require('cssnano-preset-default');

module.exports = defaultPreset({
  discardComments: {
    remove: (comment) => comment[0] === '@',
  },
});
```

Note that you may wish to publish your own preset to npm for reusability, should it differ a lot from this one. This is highly encouraged!

## Plugins

### [`css-declaration-sorter`](https://github.com/Siilwyn/css-declaration-sorter) (external)

> Sorts CSS declarations fast and automatically in a certain order.

This plugin is loaded with the following configuration:

```js
{
	keepOverrides: true
}
```

### [`cssnano-utils`](https://github.com/cssnano/cssnano/tree/master/packages/cssnano-utils)

> Utility methods used by cssnano

### [`postcss-calc`](https://github.com/postcss/postcss-calc) (external)

> PostCSS plugin to reduce calc()

This plugin is loaded with its default configuration.

### [`postcss-colormin`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-colormin)

> Minify colors in your CSS files with PostCSS.

This plugin is loaded with its default configuration.

### [`postcss-convert-values`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-convert-values)

> Convert values with PostCSS (e.g. ms -> s)

This plugin is loaded with the following configuration:

```js
{
  length: false;
}
```

### [`postcss-discard-comments`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-discard-comments)

> Discard comments in your CSS files with PostCSS.

This plugin is loaded with its default configuration.

### [`postcss-discard-duplicates`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-discard-duplicates)

> Discard duplicate rules in your CSS files with PostCSS.

This plugin is loaded with its default configuration.

### [`postcss-discard-empty`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-discard-empty)

> Discard empty rules and values with PostCSS.

This plugin is loaded with its default configuration.

### [`postcss-discard-overridden`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-discard-overridden)

> PostCSS plugin to discard overridden @keyframes or @counter-style.

This plugin is loaded with its default configuration.

### [`postcss-merge-longhand`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-merge-longhand)

> Merge longhand properties into shorthand with PostCSS.

This plugin is loaded with its default configuration.

### [`postcss-merge-rules`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-merge-rules)

> Merge CSS rules with PostCSS.

This plugin is loaded with its default configuration.

### [`postcss-minify-font-values`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-minify-font-values)

> Minify font declarations with PostCSS

This plugin is loaded with its default configuration.

### [`postcss-minify-gradients`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-minify-gradients)

> Minify gradient parameters with PostCSS.

This plugin is loaded with its default configuration.

### [`postcss-minify-params`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-minify-params)

> Minify at-rule params with PostCSS

This plugin is loaded with its default configuration.

### [`postcss-minify-selectors`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-minify-selectors)

> Minify selectors with PostCSS.

This plugin is loaded with its default configuration.

### [`postcss-normalize-charset`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-normalize-charset)

> Add necessary or remove extra charset with PostCSS

This plugin is loaded with the following configuration:

```js
{
  add: false;
}
```

### [`postcss-normalize-display-values`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-normalize-display-values)

> Normalize multiple value display syntaxes into single values.

This plugin is loaded with its default configuration.

### [`postcss-normalize-positions`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-normalize-positions)

> Normalize keyword values for position into length values.

This plugin is loaded with its default configuration.

### [`postcss-normalize-repeat-style`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-normalize-repeat-style)

> Convert two value syntax for repeat-style into one value.

This plugin is loaded with its default configuration.

### [`postcss-normalize-string`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-normalize-string)

> Normalize wrapping quotes for CSS string literals.

This plugin is loaded with its default configuration.

### [`postcss-normalize-timing-functions`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-normalize-timing-functions)

> Normalize CSS animation/transition timing functions.

This plugin is loaded with its default configuration.

### [`postcss-normalize-unicode`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-normalize-unicode)

> Normalize unicode-range descriptors, and can convert to wildcard ranges.

This plugin is loaded with its default configuration.

### [`postcss-normalize-url`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-normalize-url)

> Normalize URLs with PostCSS

This plugin is loaded with its default configuration.

### [`postcss-normalize-whitespace`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-normalize-whitespace)

> Trim whitespace inside and around CSS rules & declarations.

This plugin is loaded with its default configuration.

### [`postcss-ordered-values`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-ordered-values)

> Ensure values are ordered consistently in your CSS.

This plugin is loaded with its default configuration.

### [`postcss-reduce-initial`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-reduce-initial)

> Reduce initial definitions to the actual initial value, where possible.

This plugin is loaded with its default configuration.

### [`postcss-reduce-transforms`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-reduce-transforms)

> Reduce transform functions with PostCSS.

This plugin is loaded with its default configuration.

### [`postcss-svgo`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-svgo)

> Optimise inline SVG with PostCSS.

This plugin is loaded with its default configuration.

### [`postcss-unique-selectors`](https://github.com/cssnano/cssnano/tree/master/packages/postcss-unique-selectors)

> Ensure CSS selectors are unique.

This plugin is loaded with its default configuration.

## Contributors

See [CONTRIBUTORS.md](https://github.com/cssnano/cssnano/blob/master/CONTRIBUTORS.md).

## License

MIT © [Ben Briggs](http://beneb.info)


---

# cssnano-utils

Utility methods and plugin for cssnano projects

## List of methods and plugin(s)

| **utility methods** | **description**                                                           |
| ------------------- | ------------------------------------------------------------------------- |
| `rawCache`          | Postcss plugin to manage the raw value formatting for generated AST nodes |
| `getArguments`      | Get a list of arguments, separated by a comma.                            |
| `sameParent`        | Check that two PostCSS nodes share the same parent.                       |

## Contributors

See [CONTRIBUTORS.md](https://github.com/cssnano/cssnano/blob/master/CONTRIBUTORS.md).


---

[![NPM version](https://img.shields.io/npm/v/csso.svg)](https://www.npmjs.com/package/csso)
[![Build Status](https://github.com/css/csso/actions/workflows/build.yml/badge.svg)](https://github.com/css/csso/actions/workflows/build.yml)
[![Coverage Status](https://coveralls.io/repos/github/css/csso/badge.svg?branch=master)](https://coveralls.io/github/css/csso?branch=master)
[![NPM Downloads](https://img.shields.io/npm/dm/csso.svg)](https://www.npmjs.com/package/csso)
[![Twitter](https://img.shields.io/badge/Twitter-@cssoptimizer-blue.svg)](https://twitter.com/cssoptimizer)

CSSO (CSS Optimizer) is a CSS minifier. It performs three sort of transformations: cleaning (removing redundants), compression (replacement for the shorter forms) and restructuring (merge of declarations, rules and so on). As a result an output CSS becomes much smaller in size.

## Install

```
npm install csso
```

## Usage

```js
import { minify } from 'csso';
// CommonJS is also supported
// const { minify } = require('csso');

const minifiedCss = minify('.test { color: #ff0000; }').css;

console.log(minifiedCss);
// .test{color:red}
```

Bundles are also available for use in a browser:

- `dist/csso.js` – minified IIFE with `csso` as global
```html
<script src="node_modules/csso/dist/csso.js"></script>
<script>
  csso.minify('.example { color: green }');
</script>
```

- `dist/csso.esm.js` – minified ES module
```html
<script type="module">
  import { minify } from 'node_modules/csso/dist/csso.esm.js'

  minify('.example { color: green }');
</script>
```

One of CDN services like `unpkg` or `jsDelivr` can be used. By default (for short path) a ESM version is exposing. For IIFE version a full path to a bundle should be specified:

```html
<!-- ESM -->
<script type="module">
  import * as csstree from 'https://cdn.jsdelivr.net/npm/csso';
  import * as csstree from 'https://unpkg.com/csso';
</script>

<!-- IIFE with an export to global -->
<script src="https://cdn.jsdelivr.net/npm/csso/dist/csso.js"></script>
<script src="https://unpkg.com/csso/dist/csso.js"></script>
```

CSSO is based on [CSSTree](https://github.com/csstree/csstree) to parse CSS into AST, AST traversal and to generate AST back to CSS. All `CSSTree` API is available behind `syntax` field extended with `compress()` method. You may minify CSS step by step:

```js
import { syntax } from 'csso';

const ast = syntax.parse('.test { color: #ff0000; }');
const compressedAst = syntax.compress(ast).ast;
const minifiedCss = syntax.generate(compressedAst);

console.log(minifiedCss);
// .test{color:red}
```

Also syntax can be imported using `csso/syntax` entry point:

```js
import { parse, compress, generate } from 'csso/syntax';

const ast = parse('.test { color: #ff0000; }');
const compressedAst = compress(ast).ast;
const minifiedCss = generate(compressedAst);

console.log(minifiedCss);
// .test{color:red}
```

> Warning: CSSO doesn't guarantee API behind a `syntax` field as well as AST format. Both might be changed with changes in CSSTree. If you rely heavily on `syntax` API, a better option might be to use CSSTree directly.

## Related projects

- [Web interface](http://css.github.io/csso/csso.html)
- [csso-cli](https://github.com/css/csso-cli) – command line interface
- [gulp-csso](https://github.com/ben-eb/gulp-csso) – `Gulp` plugin
- [grunt-csso](https://github.com/t32k/grunt-csso) – `Grunt` plugin
- [broccoli-csso](https://github.com/sindresorhus/broccoli-csso) – `Broccoli` plugin
- [postcss-csso](https://github.com/lahmatiy/postcss-csso) – `PostCSS` plugin
- [csso-loader](https://github.com/sandark7/csso-loader) – `webpack` loader
- [csso-webpack-plugin](https://github.com/zoobestik/csso-webpack-plugin) – `webpack` plugin
- [CSSO Visual Studio Code plugin](https://marketplace.visualstudio.com/items?itemName=Aneryu.csso)
- [vscode-csso](https://github.com/1000ch/vscode-csso) - Visual Studio Code plugin
- [atom-csso](https://github.com/1000ch/atom-csso) - Atom plugin
- [Sublime-csso](https://github.com/1000ch/Sublime-csso) - Sublime plugin

## API

<!-- TOC depthfrom:3 -->

- [minify(source[, options])](#minifysource-options)
- [minifyBlock(source[, options])](#minifyblocksource-options)
- [syntax.compress(ast[, options])](#syntaxcompressast-options)
- [Source maps](#source-maps)
- [Usage data](#usage-data)
    - [White list filtering](#white-list-filtering)
    - [Black list filtering](#black-list-filtering)
    - [Scopes](#scopes)

<!-- /TOC -->

### minify(source[, options])

Minify `source` CSS passed as `String`.

```js
const result = csso.minify('.test { color: #ff0000; }', {
    restructure: false,   // don't change CSS structure, i.e. don't merge declarations, rulesets etc
    debug: true           // show additional debug information:
                          // true or number from 1 to 3 (greater number - more details)
});

console.log(result.css);
// > .test{color:red}
```

Returns an object with properties:

- css `String` – resulting CSS
- map `Object` – instance of [`SourceMapGenerator`](https://github.com/mozilla/source-map#sourcemapgenerator) or `null`

Options:

- sourceMap

  Type: `Boolean`  
  Default: `false`

  Generate a source map when `true`.

- filename

  Type: `String`  
  Default: `'<unknown>'`

  Filename of input CSS, uses for source map generation.

- debug

  Type: `Boolean`  
  Default: `false`

  Output debug information to `stderr`.

- beforeCompress

  Type: `function(ast, options)` or `Array<function(ast, options)>` or `null`  
  Default: `null`

  Called right after parse is run.

- afterCompress

  Type: `function(compressResult, options)` or `Array<function(compressResult, options)>` or `null`  
  Default: `null`

  Called right after [`syntax.compress()`](#syntaxcompressast-options) is run.

- Other options are the same as for [`syntax.compress()`](#syntaxcompressast-options) function.

### minifyBlock(source[, options])

The same as `minify()` but for list of declarations. Usually it's a `style` attribute value.

```js
const result = csso.minifyBlock('color: rgba(255, 0, 0, 1); color: #ff0000');

console.log(result.css);
// > color:red
```

### syntax.compress(ast[, options])

Does the main task – compress an AST. This is CSSO's extension in CSSTree syntax API.

> NOTE: `syntax.compress()` performs AST compression by transforming input AST by default (since AST cloning is expensive and needed in rare cases). Use `clone` option with truthy value in case you want to keep input AST untouched.

Returns an object with properties:

- ast `Object` – resulting AST

Options:

- restructure

  Type: `Boolean`  
  Default: `true`

  Disable or enable a structure optimisations.

- forceMediaMerge

  Type: `Boolean`  
  Default: `false`

  Enables merging of `@media` rules with the same media query by splitted by other rules. The optimisation is unsafe in general, but should work fine in most cases. Use it on your own risk.

- clone

  Type: `Boolean`  
  Default: `false`

  Transform a copy of input AST if `true`. Useful in case of AST reuse.

- comments

  Type: `String` or `Boolean`  
  Default: `true`

  Specify what comments to leave:

  - `'exclamation'` or `true` – leave all exclamation comments (i.e. `/*! .. */`)
  - `'first-exclamation'` – remove every comment except first one
  - `false` – remove all comments

- usage

  Type: `Object` or `null`  
  Default: `null`

  Usage data for advanced optimisations (see [Usage data](#usage-data) for details)

- logger

  Type: `Function` or `null`  
  Default: `null`

  Function to track every step of transformation.

### Source maps

To get a source map set `true` for `sourceMap` option. Additianaly `filename` option can be passed to specify source file. When `sourceMap` option is `true`, `map` field of result object will contain a [`SourceMapGenerator`](https://github.com/mozilla/source-map#sourcemapgenerator) instance. This object can be mixed with another source map or translated to string.

```js
const csso = require('csso');
const css = fs.readFileSync('path/to/my.css', 'utf8');
const result = csso.minify(css, {
  filename: 'path/to/my.css', // will be added to source map as reference to source file
  sourceMap: true             // generate source map
});

console.log(result);
// { css: '...minified...', map: SourceMapGenerator {} }

console.log(result.map.toString());
// '{ .. source map content .. }'
```

Example of generating source map with respect of source map from input CSS:

```js
import { SourceMapConsumer } from 'source-map';
import * as csso from 'csso';

const inputFile = 'path/to/my.css';
const input = fs.readFileSync(inputFile, 'utf8');
const inputMap = input.match(/\/\*# sourceMappingURL=(\S+)\s*\*\/\s*$/);
const output = csso.minify(input, {
  filename: inputFile,
  sourceMap: true
});

// apply input source map to output
if (inputMap) {
  output.map.applySourceMap(
    new SourceMapConsumer(inputMap[1]),
    inputFile
  )
}

// result CSS with source map
console.log(
  output.css +
  '/*# sourceMappingURL=data:application/json;base64,' +
  Buffer.from(output.map.toString()).toString('base64') +
  ' */'
);
```

### Usage data

`CSSO` can use data about how `CSS` is used in a markup for better compression. File with this data (`JSON`) can be set using `usage` option. Usage data may contain following sections:

- `blacklist` – a set of black lists (see [Black list filtering](#black-list-filtering))
- `tags` – white list of tags
- `ids` – white list of ids
- `classes` – white list of classes
- `scopes` – groups of classes which never used with classes from other groups on the same element

All sections are optional. Value of `tags`, `ids` and `classes` should be an array of a string, value of `scopes` should be an array of arrays of strings. Other values are ignoring.

#### White list filtering

`tags`, `ids` and `classes` are using on clean stage to filter selectors that contain something not in the lists. Selectors are filtering only by those kind of simple selector which white list is specified. For example, if only `tags` list is specified then type selectors are checking, and if all type selectors in selector present in list or selector has no any type selector it isn't filter.

> `ids` and `classes` are case sensitive, `tags` – is not.

Input CSS:

```css
* { color: green; }
ul, ol, li { color: blue; }
UL.foo, span.bar { color: red; }
```

Usage data:

```json
{
    "tags": ["ul", "LI"]
}
```

Resulting CSS:

```css
*{color:green}ul,li{color:blue}ul.foo{color:red}
```

Filtering performs for nested selectors too. `:not()` pseudos content is ignoring since the result of matching is unpredictable. Example for the same usage data as above:

```css
:nth-child(2n of ul, ol) { color: red }
:nth-child(3n + 1 of img) { color: yellow }
:not(div, ol, ul) { color: green }
:has(:matches(ul, ol), ul, ol) { color: blue }
```

Turns into:

```css
:nth-child(2n of ul){color:red}:not(div,ol,ul){color:green}:has(:matches(ul),ul){color:blue}
```

#### Black list filtering

Black list filtering performs the same as white list filtering, but filters things that mentioned in the lists. `blacklist` can contain the lists `tags`, `ids` and `classes`.

Black list has a higher priority, so when something mentioned in the white list and in the black list then white list occurrence is ignoring. The `:not()` pseudos content ignoring as well.

```css
* { color: green; }
ul, ol, li { color: blue; }
UL.foo, li.bar { color: red; }
```

Usage data:

```json
{
    "blacklist": {
        "tags": ["ul"]
    },
    "tags": ["ul", "LI"]
}
```

Resulting CSS:

```css
*{color:green}li{color:blue}li.bar{color:red}
```

#### Scopes

Scopes is designed for CSS scope isolation solutions such as [css-modules](https://github.com/css-modules/css-modules). Scopes are similar to namespaces and define lists of class names that exclusively used on some markup. This information allows the optimizer to move rules more agressive. Since it assumes selectors from different scopes don't match for the same element. This can improve rule merging.

Suppose we have a file:

```css
.module1-foo { color: red; }
.module1-bar { font-size: 1.5em; background: yellow; }

.module2-baz { color: red; }
.module2-qux { font-size: 1.5em; background: yellow; width: 50px; }
```

It can be assumed that first two rules are never used with the second two on the same markup. But we can't say that for sure without a markup review. The optimizer doesn't know it either and will perform safe transformations only. The result will be the same as input but with no spaces and some semicolons:

```css
.module1-foo{color:red}.module1-bar{font-size:1.5em;background:#ff0}.module2-baz{color:red}.module2-qux{font-size:1.5em;background:#ff0;width:50px}
```

With usage data `CSSO` can produce better output. If follow usage data is provided:

```json
{
    "scopes": [
        ["module1-foo", "module1-bar"],
        ["module2-baz", "module2-qux"]
    ]
}
```

The result will be (29 bytes extra saving):

```css
.module1-foo,.module2-baz{color:red}.module1-bar,.module2-qux{font-size:1.5em;background:#ff0}.module2-qux{width:50px}
```

If class name isn't mentioned in the `scopes` it belongs to default scope. `scopes` data doesn't affect `classes` whitelist. If class name mentioned in `scopes` but missed in `classes` (both sections are specified) it will be filtered.

Note that class name can't be set for several scopes. Also a selector can't have class names from different scopes. In both cases an exception will thrown.

Currently the optimizer doesn't care about changing order safety for out-of-bounds selectors (i.e. selectors that match to elements without class name, e.g. `.scope div` or `.scope ~ :last-child`). It assumes that scoped CSS modules doesn't relay on it's order. It may be fix in future if to be an issue.


---

<img align="right" width="111" height="111"
     alt="CSSTree logo"
     src="https://cloud.githubusercontent.com/assets/270491/19243723/6f9136c6-8f21-11e6-82ac-eeeee4c6c452.png"/>

# CSSTree

[![NPM version](https://img.shields.io/npm/v/css-tree.svg)](https://www.npmjs.com/package/css-tree)
[![Build Status](https://github.com/csstree/csstree/actions/workflows/build.yml/badge.svg)](https://github.com/csstree/csstree/actions/workflows/build.yml)
[![Coverage Status](https://coveralls.io/repos/github/csstree/csstree/badge.svg?branch=master)](https://coveralls.io/github/csstree/csstree?branch=master)
[![NPM Downloads](https://img.shields.io/npm/dm/css-tree.svg)](https://www.npmjs.com/package/css-tree)
[![Twitter](https://img.shields.io/badge/Twitter-@csstree-blue.svg)](https://twitter.com/csstree)

CSSTree is a tool set for CSS: [fast](https://github.com/postcss/benchmark) detailed parser (CSS → AST), walker (AST traversal), generator (AST → CSS) and lexer (validation and matching) based on specs and browser implementations. The main goal is to be efficient and W3C spec compliant, with focus on CSS analyzing and source-to-source transforming tasks.

## Features

- **Detailed parsing with an adjustable level of detail**

  By default CSSTree parses CSS as detailed as possible, i.e. each single logical part is representing with its own AST node (see [AST format](docs/ast.md) for all possible node types). The parsing detail level can be changed through [parser options](docs/parsing.md#parsesource-options), for example, you can disable parsing of selectors or declaration values for component parts.

- **Tolerant to errors by design**

  Parser behaves as [spec says](https://www.w3.org/TR/css-syntax-3/#error-handling): "When errors occur in CSS, the parser attempts to recover gracefully, throwing away only the minimum amount of content before returning to parsing as normal". The only thing the parser departs from the specification is that it doesn't throw away bad content, but wraps it in a special node type (`Raw`) that allows processing it later.

- **Fast and efficient**

  CSSTree is created with focus on performance and effective memory consumption. Therefore it's [one of the fastest CSS parsers](https://github.com/postcss/benchmark) at the moment.

- **Syntax validation**

  The build-in lexer can test CSS against syntaxes defined by W3C. CSSTree uses [mdn/data](https://github.com/mdn/data/) as a basis for lexer's dictionaries and extends it with vendor specific and legacy syntaxes. Lexer can only check the declaration values currently, but this feature will be extended to other parts of the CSS in the future.

## Projects using CSSTree

- [Svelte](https://github.com/sveltejs/svelte) – Cybernetically enhanced web apps
- [SVGO](https://github.com/svg/svgo) – Node.js tool for optimizing SVG files
- [CSSO](https://github.com/css/csso) – CSS minifier with structural optimizations
- [NativeScript](https://github.com/NativeScript/NativeScript) – NativeScript empowers you to access native APIs from JavaScript directly
- [react-native-svg](https://github.com/react-native-svg/react-native-svg) – SVG library for React Native, React Native Web, and plain React web projects
- [penthouse](https://github.com/pocketjoso/penthouse) – Critical Path CSS Generator
- [Bit](https://github.com/teambit/bit) – Bit is the platform for collaborating on components
- and more...

## Documentation

- [AST format](docs/ast.md)
- [Parsing CSS → AST](docs/parsing.md)
  - [parse(source[, options])](docs/parsing.md#parsesource-options)
- [Serialization AST → CSS](docs/generate.md)
  - [generate(ast[, options])](docs/generate.md#generateast-options)
- [AST traversal](docs/traversal.md)
  - [walk(ast, options)](docs/traversal.md#walkast-options)
  - [find(ast, fn)](docs/traversal.md#findast-fn)
  - [findLast(ast, fn)](docs/traversal.md#findlastast-fn)
  - [findAll(ast, fn)](docs/traversal.md#findallast-fn)
- [Util functions](docs/utils.md)
  - Value encoding & decoding
    - [property(name)](docs/utils.md#propertyname)
    - [keyword(name)](docs/utils.md#keywordname)
    - [ident](docs/utils.md#ident)
    - [string](docs/utils.md#string)
    - [url](docs/utils.md#url)
  - AST transforming
    - [clone(ast)](docs/utils.md#cloneast)
    - [fromPlainObject(object)](docs/utils.md#fromplainobjectobject)
    - [toPlainObject(ast)](docs/utils.md#toplainobjectast)
- [Value Definition Syntax](docs/definition-syntax.md)
  - [parse(source)](docs/definition-syntax.md#parsesource)
  - [walk(node, options, context)](docs/definition-syntax.md#walknode-options-context)
  - [generate(node, options)](docs/definition-syntax.md#generatenode-options)
  - [AST format](docs/definition-syntax.md#ast-format)

## Tools

* [AST Explorer](https://astexplorer.net/#/gist/244e2fb4da940df52bf0f4b94277db44/e79aff44611020b22cfd9708f3a99ce09b7d67a8) – explore CSSTree AST format with zero setup
* [CSS syntax reference](https://csstree.github.io/docs/syntax.html)
* [CSS syntax validator](https://csstree.github.io/docs/validator.html)

## Related projects

* [csstree-validator](https://github.com/csstree/validator) – NPM package to validate CSS
* [stylelint-csstree-validator](https://github.com/csstree/stylelint-validator) – plugin for stylelint to validate CSS
* [Grunt plugin](https://github.com/sergejmueller/grunt-csstree-validator)
* [Gulp plugin](https://github.com/csstree/gulp-csstree)
* [Sublime plugin](https://github.com/csstree/SublimeLinter-contrib-csstree)
* [VS Code plugin](https://github.com/csstree/vscode-plugin)
* [Atom plugin](https://github.com/csstree/atom-plugin)

## Usage

Install with npm:

```
npm install css-tree
```

Basic usage:

```js
import * as csstree from 'css-tree';

// parse CSS to AST
const ast = csstree.parse('.example { world: "!" }');

// traverse AST and modify it
csstree.walk(ast, (node) => {
    if (node.type === 'ClassSelector' && node.name === 'example') {
        node.name = 'hello';
    }
});

// generate CSS from AST
console.log(csstree.generate(ast));
// .hello{world:"!"}
```

Syntax matching:

```js
// parse CSS to AST as a declaration value
const ast = csstree.parse('red 1px solid', { context: 'value' });

// match to syntax of `border` property
const matchResult = csstree.lexer.matchProperty('border', ast);

// check first value node is a <color>
console.log(matchResult.isType(ast.children.first, 'color'));
// true

// get a type list matched to a node
console.log(matchResult.getTrace(ast.children.first));
// [ { type: 'Property', name: 'border' },
//   { type: 'Type', name: 'color' },
//   { type: 'Type', name: 'named-color' },
//   { type: 'Keyword', name: 'red' } ]
```

### Exports

Is it possible to import just a needed part of library like a parser or a walker. That's might useful for loading time or bundle size optimisations. 

```js
import * as tokenizer from 'css-tree/tokenizer';
import * as parser from 'css-tree/parser';
import * as walker from 'css-tree/walker';
import * as lexer from 'css-tree/lexer';
import * as definitionSyntax from 'css-tree/definition-syntax';
import * as data from 'css-tree/definition-syntax-data';
import * as dataPatch from 'css-tree/definition-syntax-data-patch';
import * as utils from 'css-tree/utils';
```

### Using in a browser

Bundles are available for use in a browser:

- `dist/csstree.js` – minified IIFE with `csstree` as global
```html
<script src="node_modules/css-tree/dist/csstree.js"></script>
<script>
  csstree.parse('.example { color: green }');
</script>
```

- `dist/csstree.esm.js` – minified ES module
```html
<script type="module">
  import { parse } from 'node_modules/css-tree/dist/csstree.esm.js'
  parse('.example { color: green }');
</script>
```

One of CDN services like `unpkg` or `jsDelivr` can be used. By default (for short path) a ESM version is exposing. For IIFE version a full path to a bundle should be specified:

```html
<!-- ESM -->
<script type="module">
  import * as csstree from 'https://cdn.jsdelivr.net/npm/css-tree';
  import * as csstree from 'https://unpkg.com/css-tree';
</script>

<!-- IIFE with an export to global -->
<script src="https://cdn.jsdelivr.net/npm/css-tree/dist/csstree.js"></script>
<script src="https://unpkg.com/css-tree/dist/csstree.js"></script>
```

## Top level API

![API map](https://cdn.rawgit.com/csstree/csstree/aaf327e/docs/api-map.svg)

## License

MIT


---

# Changelog

## [2.0.28](https://github.com/mdn/data/compare/v2.0.27...v2.0.28) (2022-07-12)


### Bug Fixes

* **css:** correct two syntax examples in selectors ([#589](https://github.com/mdn/data/issues/589)) ([91ab33a](https://github.com/mdn/data/commit/91ab33a40bf2dfd75286a01785453705105533e8))

### [2.0.27](https://github.com/mdn/data/compare/v2.0.26...v2.0.27) (2022-02-24)


### Miscellaneous Chores

* release ([a99ae2e](https://github.com/mdn/data/commit/a99ae2ebfeb930524c18f8d46954e8e32ab6b630))

### [2.0.26](https://www.github.com/mdn/data/compare/v2.0.25...v2.0.26) (2022-01-19)


### Miscellaneous Chores

* release 2.0.26 ([8b1045d](https://www.github.com/mdn/data/commit/8b1045dc488c7b278c933143efd1bdba75b6832f))

### [2.0.25](https://www.github.com/mdn/data/compare/v2.0.24...v2.0.25) (2021-12-21)


### Bug Fixes

* change branch reference to main ([a473261](https://www.github.com/mdn/data/commit/a473261308cf82ee387cec886c70ef3d570fc957))
* remove old clashing workflow ([af9a18c](https://www.github.com/mdn/data/commit/af9a18ce3af2cbca83582debf3c3d3fc0ace7402))


### Miscellaneous Chores

* release 2.0.25 ([db5a54b](https://www.github.com/mdn/data/commit/db5a54ba4f3c28b52d0801e115fd5ff0a0052743))
* release 2.0.25 ([0f453ee](https://www.github.com/mdn/data/commit/0f453eedadbd9065d552203260210bdfafa9d7ff))

### [2.0.24](https://www.github.com/mdn/data/compare/v2.0.24...v2.0.24) (2021-12-17)


### Miscellaneous Chores

* release 2.0.24 ([4d00c38](https://www.github.com/mdn/data/commit/4d00c386efe1cfbf536bb3bc80fed6d687f9ad04))

### [2.0.24](https://www.github.com/mdn/data/compare/v2.0.23...v2.0.24) (2021-12-15)


### Miscellaneous Chores

* release 2.0.24 ([abff6ff](https://www.github.com/mdn/data/commit/abff6ff0fb88e834c65a2cc05f346b105a9b2e99))


---

# MDN data

[https://github.com/mdn/data](https://github.com/mdn/data)

Maintained by the [MDN team at Mozilla](https://wiki.mozilla.org/MDN).

This repository contains general data for Web technologies.

This data is used in MDN documentation, to build
[information boxes](https://developer.mozilla.org/en-US/docs/Web/CSS/background)
or [sidebar navigation](https://developer.mozilla.org/en-US/docs/Web/API/Window).
External tools have started to make use of this data as well.
For example, the [CSSTree](https://github.com/csstree/csstree/) CSS parser.


[![NPM version](https://img.shields.io/npm/v/mdn-data.svg)](https://www.npmjs.com/package/mdn-data)
[![lint](https://github.com/mdn/data/actions/workflows/lint.yml/badge.svg)](https://github.com/mdn/data/actions/workflows/lint.yml)

## Repository contents

There's a top-level directory for each broad area covered: for example, `api`
and `css`. Inside each of these directories is one or more
JSON files containing the data.

### api
Contains data about Web APIs:
* API inheritance (interface inheritance and mixin implementations)

### css
 Contains data about:
* CSS at-rules
* CSS properties
* CSS selectors
* CSS syntaxes
* CSS types
* CSS units

Read more about [CSS data](https://github.com/mdn/data/blob/master/css/readme.md) and the format of the files.


### l10n
The l10n folder contains localization strings that are used in the various
json files throughout this repository.

## Problems?

If you find a problem, please [file an issue](https://github.com/mdn/data/issues/new).

## Contributing

We're very happy to accept contributions to this data. Please familiarize yourself
with the schema for the data you're editing, and send us a pull request. See also the [Contributing file](https://github.com/mdn/data/blob/master/CONTRIBUTING.md) for more information.

## See also
* [https://github.com/mdn/browser-compat-data](https://github.com/mdn/browser-compat-data)
for compatibility data for Web technologies


---

# MDN CSS data

This folder contains data about the different features of the [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS) language.

## Different types of CSS data

The CSS data is split into these parts:

* **at-rules**:
[data](https://github.com/mdn/data/blob/master/css/at-rules.json) |
[schema](https://github.com/mdn/data/blob/master/css/at-rules.schema.json) |
[docs](https://github.com/mdn/data/blob/master/css/at-rules.md)
* **properties**:
[data](https://github.com/mdn/data/blob/master/css/properties.json) |
[schema](https://github.com/mdn/data/blob/master/css/properties.schema.json) |
[docs](https://github.com/mdn/data/blob/master/css/properties.md)
* **selectors**:
[data](https://github.com/mdn/data/blob/master/css/selectors.json) |
[schema](https://github.com/mdn/data/blob/master/css/selectors.schema.json) |
[docs](https://github.com/mdn/data/blob/master/css/selectors.md)
* **syntaxes**:
[data](https://github.com/mdn/data/blob/master/css/syntaxes.json) |
[schema](https://github.com/mdn/data/blob/master/css/syntaxes.schema.json) |
[docs](https://github.com/mdn/data/blob/master/css/syntaxes.md)
* **types**:
[data](https://github.com/mdn/data/blob/master/css/types.json) |
[schema](https://github.com/mdn/data/blob/master/css/types.schema.json) |
[docs](https://github.com/mdn/data/blob/master/css/types.md)
* **units**:
[data](https://github.com/mdn/data/blob/master/css/units.json) |
[schema](https://github.com/mdn/data/blob/master/css/units.schema.json) |
[docs](https://github.com/mdn/data/blob/master/css/units.md)


---

# CSSType

[![npm](https://img.shields.io/npm/v/csstype.svg)](https://www.npmjs.com/package/csstype)

TypeScript and Flow definitions for CSS, generated by [data from MDN](https://github.com/mdn/data). It provides autocompletion and type checking for CSS properties and values.

**TypeScript**

```ts
import type * as CSS from 'csstype';

const style: CSS.Properties = {
  colour: 'white', // Type error on property
  textAlign: 'middle', // Type error on value
};
```

**Flow**

```js
// @flow strict
import * as CSS from 'csstype';

const style: CSS.Properties<> = {
  colour: 'white', // Type error on property
  textAlign: 'middle', // Type error on value
};
```

_Further examples below will be in TypeScript!_

## Getting started

```sh
$ npm install csstype
```

## Table of content

- [Style types](#style-types)
- [At-rule types](#at-rule-types)
- [Pseudo types](#pseudo-types)
- [Generics](#generics)
- [Usage](#usage)
- [What should I do when I get type errors?](#what-should-i-do-when-i-get-type-errors)
- [Version 3.0](#version-30)
- [Contributing](#contributing)

## Style types

Properties are categorized in different uses and in several technical variations to provide typings that suits as many as possible.

|                | Default              | `Hyphen`                   | `Fallback`                   | `HyphenFallback`                   |
| -------------- | -------------------- | -------------------------- | ---------------------------- | ---------------------------------- |
| **All**        | `Properties`         | `PropertiesHyphen`         | `PropertiesFallback`         | `PropertiesHyphenFallback`         |
| **`Standard`** | `StandardProperties` | `StandardPropertiesHyphen` | `StandardPropertiesFallback` | `StandardPropertiesHyphenFallback` |
| **`Vendor`**   | `VendorProperties`   | `VendorPropertiesHyphen`   | `VendorPropertiesFallback`   | `VendorPropertiesHyphenFallback`   |
| **`Obsolete`** | `ObsoleteProperties` | `ObsoletePropertiesHyphen` | `ObsoletePropertiesFallback` | `ObsoletePropertiesHyphenFallback` |
| **`Svg`**      | `SvgProperties`      | `SvgPropertiesHyphen`      | `SvgPropertiesFallback`      | `SvgPropertiesHyphenFallback`      |

Categories:

- **All** - Includes `Standard`, `Vendor`, `Obsolete` and `Svg`
- **`Standard`** - Current properties and extends subcategories `StandardLonghand` and `StandardShorthand` _(e.g. `StandardShorthandProperties`)_
- **`Vendor`** - Vendor prefixed properties and extends subcategories `VendorLonghand` and `VendorShorthand` _(e.g. `VendorShorthandProperties`)_
- **`Obsolete`** - Removed or deprecated properties
- **`Svg`** - SVG-specific properties

Variations:

- **Default** - JavaScript (camel) cased property names
- **`Hyphen`** - CSS (kebab) cased property names
- **`Fallback`** - Also accepts array of values e.g. `string | string[]`

## At-rule types

At-rule interfaces with descriptors.

**TypeScript**: These will be found in the `AtRule` namespace, e.g. `AtRule.Viewport`.  
**Flow**: These will be prefixed with `AtRule$`, e.g. `AtRule$Viewport`.

|                      | Default        | `Hyphen`             | `Fallback`             | `HyphenFallback`             |
| -------------------- | -------------- | -------------------- | ---------------------- | ---------------------------- |
| **`@counter-style`** | `CounterStyle` | `CounterStyleHyphen` | `CounterStyleFallback` | `CounterStyleHyphenFallback` |
| **`@font-face`**     | `FontFace`     | `FontFaceHyphen`     | `FontFaceFallback`     | `FontFaceHyphenFallback`     |
| **`@viewport`**      | `Viewport`     | `ViewportHyphen`     | `ViewportFallback`     | `ViewportHyphenFallback`     |

## Pseudo types

String literals of pseudo classes and pseudo elements

- `Pseudos`

  Extends:

  - `AdvancedPseudos`

    Function-like pseudos e.g. `:not(:first-child)`. The string literal contains the value excluding the parenthesis: `:not`. These are separated because they require an argument that results in infinite number of variations.

  - `SimplePseudos`

    Plain pseudos e.g. `:hover` that can only be **one** variation.

## Generics

All interfaces has two optional generic argument to define length and time: `CSS.Properties<TLength = string | 0, TTime = string>`

- **Length** is the first generic parameter and defaults to `string | 0` because `0` is the only [length where the unit identifier is optional](https://drafts.csswg.org/css-values-3/#lengths). You can specify this, e.g. `string | number`, for platforms and libraries that accepts any numeric value as length with a specific unit.
  ```tsx
  const style: CSS.Properties<string | number> = {
    width: 100,
  };
  ```
- **Time** is the second generic argument and defaults to `string`. You can specify this, e.g. `string | number`, for platforms and libraries that accepts any numeric value as length with a specific unit.
  ```tsx
  const style: CSS.Properties<string | number, number> = {
    transitionDuration: 1000,
  };
  ```

## Usage

```ts
import type * as CSS from 'csstype';

const style: CSS.Properties = {
  width: '10px',
  margin: '1em',
};
```

In some cases, like for CSS-in-JS libraries, an array of values is a way to provide fallback values in CSS. Using `CSS.PropertiesFallback` instead of `CSS.Properties` will add the possibility to use any property value as an array of values.

```ts
import type * as CSS from 'csstype';

const style: CSS.PropertiesFallback = {
  display: ['-webkit-flex', 'flex'],
  color: 'white',
};
```

There's even string literals for pseudo selectors and elements.

```ts
import type * as CSS from 'csstype';

const pseudos: { [P in CSS.SimplePseudos]?: CSS.Properties } = {
  ':hover': {
    display: 'flex',
  },
};
```

Hyphen cased (kebab cased) properties are provided in `CSS.PropertiesHyphen` and `CSS.PropertiesHyphenFallback`. It's not **not** added by default in `CSS.Properties`. To allow both of them, you can simply extend with `CSS.PropertiesHyphen` or/and `CSS.PropertiesHyphenFallback`.

```ts
import type * as CSS from 'csstype';

interface Style extends CSS.Properties, CSS.PropertiesHyphen {}

const style: Style = {
  'flex-grow': 1,
  'flex-shrink': 0,
  'font-weight': 'normal',
  backgroundColor: 'white',
};
```

Adding type checked CSS properties to a `HTMLElement`.

```ts
import type * as CSS from 'csstype';

const style: CSS.Properties = {
  color: 'red',
  margin: '1em',
};

let button = document.createElement('button');

Object.assign(button.style, style);
```

## What should I do when I get type errors?

The goal is to have as perfect types as possible and we're trying to do our best. But with CSS Custom Properties, the CSS specification changing frequently and vendors implementing their own specifications with new releases sometimes causes type errors even if it should work. Here's some steps you could take to get it fixed:

_If you're using CSS Custom Properties you can step directly to step 3._

1.  **First of all, make sure you're doing it right.** A type error could also indicate that you're not :wink:

    - Some CSS specs that some vendors has implemented could have been officially rejected or haven't yet received any official acceptance and are therefor not included
    - If you're using TypeScript, [type widening](https://blog.mariusschulz.com/2017/02/04/TypeScript-2-1-literal-type-widening) could be the reason you get `Type 'string' is not assignable to...` errors

2.  **Have a look in [issues](https://github.com/frenic/csstype/issues) to see if an issue already has been filed. If not, create a new one.** To help us out, please refer to any information you have found.
3.  Fix the issue locally with **TypeScript** (Flow further down):

    - The recommended way is to use **module augmentation**. Here's a few examples:

      ```ts
      // My css.d.ts file
      import type * as CSS from 'csstype';

      declare module 'csstype' {
        interface Properties {
          // Add a missing property
          WebkitRocketLauncher?: string;

          // Add a CSS Custom Property
          '--theme-color'?: 'black' | 'white';

          // Allow namespaced CSS Custom Properties
          [index: `--theme-${string}`]: any;
          
          // Allow any CSS Custom Properties
          [index: `--${string}`]: any;

          // ...or allow any other property
          [index: string]: any;
        }
      }
      ```

    - The alternative way is to use **type assertion**. Here's a few examples:

      ```ts
      const style: CSS.Properties = {
        // Add a missing property
        ['WebkitRocketLauncher' as any]: 'launching',

        // Add a CSS Custom Property
        ['--theme-color' as any]: 'black',
      };
      ```

    Fix the issue locally with **Flow**:

    - Use **type assertion**. Here's a few examples:

      ```js
      const style: $Exact<CSS.Properties<*>> = {
        // Add a missing property
        [('WebkitRocketLauncher': any)]: 'launching',

        // Add a CSS Custom Property
        [('--theme-color': any)]: 'black',
      };
      ```

## Version 3.0

- **All property types are exposed with namespace**  
  TypeScript: `Property.AlignContent` (was `AlignContentProperty` before)  
  Flow: `Property$AlignContent`
- **All at-rules are exposed with namespace**  
  TypeScript: `AtRule.FontFace` (was `FontFace` before)  
  Flow: `AtRule$FontFace`
- **Data types are NOT exposed**  
  E.g. `Color` and `Box`. Because the generation of data types may suddenly be removed or renamed.
- **TypeScript hack for autocompletion**  
  Uses `(string & {})` for literal string unions and `(number & {})` for literal number unions ([related issue](https://github.com/microsoft/TypeScript/issues/29729)). Utilize `PropertyValue<T>` to unpack types from e.g. `(string & {})` to `string`.
- **New generic for time**  
  Read more on the ["Generics"](#generics) section.
- **Flow types improvements**  
  Flow Strict enabled and exact types are used.

## Contributing

**Never modify `index.d.ts` and `index.js.flow` directly. They are generated automatically and committed so that we can easily follow any change it results in.** Therefor it's important that you run `$ git config merge.ours.driver true` after you've forked and cloned. That setting prevents merge conflicts when doing rebase.

### Commands

- `npm run build` Generates typings and type checks them
- `npm run watch` Runs build on each save
- `npm run test` Runs the tests
- `npm run lazy` Type checks, lints and formats everything


---


1.2.1 / 2021-03-09
==================

  * Add CONTRIBUTORS and MIT LICENSE file. (#28)

1.2.0 / 2018-08-14
==================

  * Added a .debounce member to debounce (#21)

1.1.0 / 2017-10-30
==================

  * Ability to force execution (#16)

1.0.2 / 2017-04-21
==================

 * Fixes #3 - Debounced function executing early? (#15)
 * Merge pull request #13 from selbekk/master
 * Remove date-now from package.json
 * Remove date-now dependency from component.json
 * Remove date-now usage

1.0.1 / 2016-07-25
==================

 * add ability to clear timer (#10)

1.0.0 / 2014-06-21
==================

 * Readme: attribute underscore.js in the License section
 * index: rewrite to use underscore.js' implementation (#2, @TooTallNate)
 * component, package: add "date-now" as a dependency
 * test: fix test
 * component, package: add "keywords" array
 * package: adjust "description"
 * package: added "repository" field (#1, @juliangruber)

0.0.3 / 2013-08-21
==================

 * immediate now defaults to `false`

0.0.2 / 2013-07-27
==================

 * consolidated with TJ's debounce

0.0.1 / 2012-11-5
==================

 * Initial release


---


# debounce

  Useful for implementing behavior that should only happen after a repeated
  action has completed.

## Installation

    $ component install component/debounce

  Or in node:

    $ npm install debounce

## Example

```js
var debounce = require('debounce');
window.onresize = debounce(resize, 200);

function resize(e) {
  console.log('height', window.innerHeight);
  console.log('width', window.innerWidth);
}
```

To later clear the timer and cancel currently scheduled executions:
```
window.onresize.clear();
```

To execute any pending invocations and reset the timer:
```
window.onresize.flush();
```

Alternately, if using newer syntax:

```js
import { debounce } from "debounce";
```

## API

### debounce(fn, wait, [ immediate || false ])

  Creates and returns a new debounced version of the passed function that
  will postpone its execution until after wait milliseconds have elapsed
  since the last time it was invoked.

  Pass `true` for the `immediate` parameter to cause debounce to trigger
  the function on the leading edge instead of the trailing edge of the wait
  interval. Useful in circumstances like preventing accidental double-clicks
  on a "submit" button from firing a second time.

  The debounced function returned has a property 'clear' that is a 
  function that will clear any scheduled future executions of your function.

  The debounced function returned has a property 'flush' that is a 
  function that will immediately execute the function if and only if execution is scheduled,
  and reset the execution timer for subsequent invocations of the debounced
  function.

## License

  MIT

  Original implementation is from [`underscore.js`](http://underscorejs.org/)
  which also has an MIT license.


---

# debug
[![Build Status](https://travis-ci.org/debug-js/debug.svg?branch=master)](https://travis-ci.org/debug-js/debug)  [![Coverage Status](https://coveralls.io/repos/github/debug-js/debug/badge.svg?branch=master)](https://coveralls.io/github/debug-js/debug?branch=master)  [![Slack](https://visionmedia-community-slackin.now.sh/badge.svg)](https://visionmedia-community-slackin.now.sh/) [![OpenCollective](https://opencollective.com/debug/backers/badge.svg)](#backers)
[![OpenCollective](https://opencollective.com/debug/sponsors/badge.svg)](#sponsors)

<img width="647" src="https://user-images.githubusercontent.com/71256/29091486-fa38524c-7c37-11e7-895f-e7ec8e1039b6.png">

A tiny JavaScript debugging utility modelled after Node.js core's debugging
technique. Works in Node.js and web browsers.

## Installation

```bash
$ npm install debug
```

## Usage

`debug` exposes a function; simply pass this function the name of your module, and it will return a decorated version of `console.error` for you to pass debug statements to. This will allow you to toggle the debug output for different parts of your module as well as the module as a whole.

Example [_app.js_](./examples/node/app.js):

```js
var debug = require('debug')('http')
  , http = require('http')
  , name = 'My App';

// fake app

debug('booting %o', name);

http.createServer(function(req, res){
  debug(req.method + ' ' + req.url);
  res.end('hello\n');
}).listen(3000, function(){
  debug('listening');
});

// fake worker of some kind

require('./worker');
```

Example [_worker.js_](./examples/node/worker.js):

```js
var a = require('debug')('worker:a')
  , b = require('debug')('worker:b');

function work() {
  a('doing lots of uninteresting work');
  setTimeout(work, Math.random() * 1000);
}

work();

function workb() {
  b('doing some work');
  setTimeout(workb, Math.random() * 2000);
}

workb();
```

The `DEBUG` environment variable is then used to enable these based on space or
comma-delimited names.

Here are some examples:

<img width="647" alt="screen shot 2017-08-08 at 12 53 04 pm" src="https://user-images.githubusercontent.com/71256/29091703-a6302cdc-7c38-11e7-8304-7c0b3bc600cd.png">
<img width="647" alt="screen shot 2017-08-08 at 12 53 38 pm" src="https://user-images.githubusercontent.com/71256/29091700-a62a6888-7c38-11e7-800b-db911291ca2b.png">
<img width="647" alt="screen shot 2017-08-08 at 12 53 25 pm" src="https://user-images.githubusercontent.com/71256/29091701-a62ea114-7c38-11e7-826a-2692bedca740.png">

#### Windows command prompt notes

##### CMD

On Windows the environment variable is set using the `set` command.

```cmd
set DEBUG=*,-not_this
```

Example:

```cmd
set DEBUG=* & node app.js
```

##### PowerShell (VS Code default)

PowerShell uses different syntax to set environment variables.

```cmd
$env:DEBUG = "*,-not_this"
```

Example:

```cmd
$env:DEBUG='app';node app.js
```

Then, run the program to be debugged as usual.

npm script example:
```js
  "windowsDebug": "@powershell -Command $env:DEBUG='*';node app.js",
```

## Namespace Colors

Every debug instance has a color generated for it based on its namespace name.
This helps when visually parsing the debug output to identify which debug instance
a debug line belongs to.

#### Node.js

In Node.js, colors are enabled when stderr is a TTY. You also _should_ install
the [`supports-color`](https://npmjs.org/supports-color) module alongside debug,
otherwise debug will only use a small handful of basic colors.

<img width="521" src="https://user-images.githubusercontent.com/71256/29092181-47f6a9e6-7c3a-11e7-9a14-1928d8a711cd.png">

#### Web Browser

Colors are also enabled on "Web Inspectors" that understand the `%c` formatting
option. These are WebKit web inspectors, Firefox ([since version
31](https://hacks.mozilla.org/2014/05/editable-box-model-multiple-selection-sublime-text-keys-much-more-firefox-developer-tools-episode-31/))
and the Firebug plugin for Firefox (any version).

<img width="524" src="https://user-images.githubusercontent.com/71256/29092033-b65f9f2e-7c39-11e7-8e32-f6f0d8e865c1.png">


## Millisecond diff

When actively developing an application it can be useful to see when the time spent between one `debug()` call and the next. Suppose for example you invoke `debug()` before requesting a resource, and after as well, the "+NNNms" will show you how much time was spent between calls.

<img width="647" src="https://user-images.githubusercontent.com/71256/29091486-fa38524c-7c37-11e7-895f-e7ec8e1039b6.png">

When stdout is not a TTY, `Date#toISOString()` is used, making it more useful for logging the debug information as shown below:

<img width="647" src="https://user-images.githubusercontent.com/71256/29091956-6bd78372-7c39-11e7-8c55-c948396d6edd.png">


## Conventions

If you're using this in one or more of your libraries, you _should_ use the name of your library so that developers may toggle debugging as desired without guessing names. If you have more than one debuggers you _should_ prefix them with your library name and use ":" to separate features. For example "bodyParser" from Connect would then be "connect:bodyParser".  If you append a "*" to the end of your name, it will always be enabled regardless of the setting of the DEBUG environment variable.  You can then use it for normal output as well as debug output.

## Wildcards

The `*` character may be used as a wildcard. Suppose for example your library has
debuggers named "connect:bodyParser", "connect:compress", "connect:session",
instead of listing all three with
`DEBUG=connect:bodyParser,connect:compress,connect:session`, you may simply do
`DEBUG=connect:*`, or to run everything using this module simply use `DEBUG=*`.

You can also exclude specific debuggers by prefixing them with a "-" character.
For example, `DEBUG=*,-connect:*` would include all debuggers except those
starting with "connect:".

## Environment Variables

When running through Node.js, you can set a few environment variables that will
change the behavior of the debug logging:

| Name      | Purpose                                         |
|-----------|-------------------------------------------------|
| `DEBUG`   | Enables/disables specific debugging namespaces. |
| `DEBUG_HIDE_DATE` | Hide date from debug output (non-TTY).  |
| `DEBUG_COLORS`| Whether or not to use colors in the debug output. |
| `DEBUG_DEPTH` | Object inspection depth.                    |
| `DEBUG_SHOW_HIDDEN` | Shows hidden properties on inspected objects. |


__Note:__ The environment variables beginning with `DEBUG_` end up being
converted into an Options object that gets used with `%o`/`%O` formatters.
See the Node.js documentation for
[`util.inspect()`](https://nodejs.org/api/util.html#util_util_inspect_object_options)
for the complete list.

## Formatters

Debug uses [printf-style](https://wikipedia.org/wiki/Printf_format_string) formatting.
Below are the officially supported formatters:

| Formatter | Representation |
|-----------|----------------|
| `%O`      | Pretty-print an Object on multiple lines. |
| `%o`      | Pretty-print an Object all on a single line. |
| `%s`      | String. |
| `%d`      | Number (both integer and float). |
| `%j`      | JSON. Replaced with the string '[Circular]' if the argument contains circular references. |
| `%%`      | Single percent sign ('%'). This does not consume an argument. |


### Custom formatters

You can add custom formatters by extending the `debug.formatters` object.
For example, if you wanted to add support for rendering a Buffer as hex with
`%h`, you could do something like:

```js
const createDebug = require('debug')
createDebug.formatters.h = (v) => {
  return v.toString('hex')
}

// …elsewhere
const debug = createDebug('foo')
debug('this is hex: %h', new Buffer('hello world'))
//   foo this is hex: 68656c6c6f20776f726c6421 +0ms
```


## Browser Support

You can build a browser-ready script using [browserify](https://github.com/substack/node-browserify),
or just use the [browserify-as-a-service](https://wzrd.in/) [build](https://wzrd.in/standalone/debug@latest),
if you don't want to build it yourself.

Debug's enable state is currently persisted by `localStorage`.
Consider the situation shown below where you have `worker:a` and `worker:b`,
and wish to debug both. You can enable this using `localStorage.debug`:

```js
localStorage.debug = 'worker:*'
```

And then refresh the page.

```js
a = debug('worker:a');
b = debug('worker:b');

setInterval(function(){
  a('doing some work');
}, 1000);

setInterval(function(){
  b('doing some work');
}, 1200);
```

In Chromium-based web browsers (e.g. Brave, Chrome, and Electron), the JavaScript console will—by default—only show messages logged by `debug` if the "Verbose" log level is _enabled_.

<img width="647" src="https://user-images.githubusercontent.com/7143133/152083257-29034707-c42c-4959-8add-3cee850e6fcf.png">

## Output streams

  By default `debug` will log to stderr, however this can be configured per-namespace by overriding the `log` method:

Example [_stdout.js_](./examples/node/stdout.js):

```js
var debug = require('debug');
var error = debug('app:error');

// by default stderr is used
error('goes to stderr!');

var log = debug('app:log');
// set this namespace to log via console.log
log.log = console.log.bind(console); // don't forget to bind to console!
log('goes to stdout');
error('still goes to stderr!');

// set all output to go via console.info
// overrides all per-namespace log settings
debug.log = console.info.bind(console);
error('now goes to stdout via console.info');
log('still goes to stdout, but via console.info now');
```

## Extend
You can simply extend debugger 
```js
const log = require('debug')('auth');

//creates new debug instance with extended namespace
const logSign = log.extend('sign');
const logLogin = log.extend('login');

log('hello'); // auth hello
logSign('hello'); //auth:sign hello
logLogin('hello'); //auth:login hello
```

## Set dynamically

You can also enable debug dynamically by calling the `enable()` method :

```js
let debug = require('debug');

console.log(1, debug.enabled('test'));

debug.enable('test');
console.log(2, debug.enabled('test'));

debug.disable();
console.log(3, debug.enabled('test'));

```

print :   
```
1 false
2 true
3 false
```

Usage :  
`enable(namespaces)`  
`namespaces` can include modes separated by a colon and wildcards.
   
Note that calling `enable()` completely overrides previously set DEBUG variable : 

```
$ DEBUG=foo node -e 'var dbg = require("debug"); dbg.enable("bar"); console.log(dbg.enabled("foo"))'
=> false
```

`disable()`

Will disable all namespaces. The functions returns the namespaces currently
enabled (and skipped). This can be useful if you want to disable debugging
temporarily without knowing what was enabled to begin with.

For example:

```js
let debug = require('debug');
debug.enable('foo:*,-foo:bar');
let namespaces = debug.disable();
debug.enable(namespaces);
```

Note: There is no guarantee that the string will be identical to the initial
enable string, but semantically they will be identical.

## Checking whether a debug target is enabled

After you've created a debug instance, you can determine whether or not it is
enabled by checking the `enabled` property:

```javascript
const debug = require('debug')('http');

if (debug.enabled) {
  // do stuff...
}
```

You can also manually toggle this property to force the debug instance to be
enabled or disabled.

## Usage in child processes

Due to the way `debug` detects if the output is a TTY or not, colors are not shown in child processes when `stderr` is piped. A solution is to pass the `DEBUG_COLORS=1` environment variable to the child process.  
For example:

```javascript
worker = fork(WORKER_WRAP_PATH, [workerPath], {
  stdio: [
    /* stdin: */ 0,
    /* stdout: */ 'pipe',
    /* stderr: */ 'pipe',
    'ipc',
  ],
  env: Object.assign({}, process.env, {
    DEBUG_COLORS: 1 // without this settings, colors won't be shown
  }),
});

worker.stderr.pipe(process.stderr, { end: false });
```


## Authors

 - TJ Holowaychuk
 - Nathan Rajlich
 - Andrew Rhyne
 - Josh Junon

## Backers

Support us with a monthly donation and help us continue our activities. [[Become a backer](https://opencollective.com/debug#backer)]

<a href="https://opencollective.com/debug/backer/0/website" target="_blank"><img src="https://opencollective.com/debug/backer/0/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/1/website" target="_blank"><img src="https://opencollective.com/debug/backer/1/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/2/website" target="_blank"><img src="https://opencollective.com/debug/backer/2/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/3/website" target="_blank"><img src="https://opencollective.com/debug/backer/3/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/4/website" target="_blank"><img src="https://opencollective.com/debug/backer/4/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/5/website" target="_blank"><img src="https://opencollective.com/debug/backer/5/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/6/website" target="_blank"><img src="https://opencollective.com/debug/backer/6/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/7/website" target="_blank"><img src="https://opencollective.com/debug/backer/7/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/8/website" target="_blank"><img src="https://opencollective.com/debug/backer/8/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/9/website" target="_blank"><img src="https://opencollective.com/debug/backer/9/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/10/website" target="_blank"><img src="https://opencollective.com/debug/backer/10/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/11/website" target="_blank"><img src="https://opencollective.com/debug/backer/11/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/12/website" target="_blank"><img src="https://opencollective.com/debug/backer/12/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/13/website" target="_blank"><img src="https://opencollective.com/debug/backer/13/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/14/website" target="_blank"><img src="https://opencollective.com/debug/backer/14/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/15/website" target="_blank"><img src="https://opencollective.com/debug/backer/15/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/16/website" target="_blank"><img src="https://opencollective.com/debug/backer/16/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/17/website" target="_blank"><img src="https://opencollective.com/debug/backer/17/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/18/website" target="_blank"><img src="https://opencollective.com/debug/backer/18/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/19/website" target="_blank"><img src="https://opencollective.com/debug/backer/19/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/20/website" target="_blank"><img src="https://opencollective.com/debug/backer/20/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/21/website" target="_blank"><img src="https://opencollective.com/debug/backer/21/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/22/website" target="_blank"><img src="https://opencollective.com/debug/backer/22/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/23/website" target="_blank"><img src="https://opencollective.com/debug/backer/23/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/24/website" target="_blank"><img src="https://opencollective.com/debug/backer/24/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/25/website" target="_blank"><img src="https://opencollective.com/debug/backer/25/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/26/website" target="_blank"><img src="https://opencollective.com/debug/backer/26/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/27/website" target="_blank"><img src="https://opencollective.com/debug/backer/27/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/28/website" target="_blank"><img src="https://opencollective.com/debug/backer/28/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/29/website" target="_blank"><img src="https://opencollective.com/debug/backer/29/avatar.svg"></a>


## Sponsors

Become a sponsor and get your logo on our README on Github with a link to your site. [[Become a sponsor](https://opencollective.com/debug#sponsor)]

<a href="https://opencollective.com/debug/sponsor/0/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/0/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/1/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/1/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/2/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/2/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/3/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/3/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/4/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/4/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/5/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/5/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/6/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/6/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/7/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/7/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/8/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/8/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/9/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/9/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/10/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/10/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/11/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/11/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/12/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/12/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/13/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/13/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/14/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/14/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/15/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/15/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/16/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/16/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/17/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/17/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/18/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/18/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/19/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/19/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/20/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/20/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/21/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/21/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/22/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/22/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/23/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/23/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/24/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/24/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/25/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/25/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/26/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/26/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/27/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/27/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/28/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/28/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/29/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/29/avatar.svg"></a>

## License

(The MIT License)

Copyright (c) 2014-2017 TJ Holowaychuk &lt;tj@vision-media.ca&gt;
Copyright (c) 2018-2021 Josh Junon

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
'Software'), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


---

# decode-named-character-reference

[![Build Status][build-badge]][build]
[![Coverage Status][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]

Decode named character references.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`decodeNamedCharacterReference(value)`](#decodenamedcharacterreferencevalue)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Related](#related)
* [Contribute](#contribute)
* [License](#license)

## What is this?

A workaround for webpack.

## When should I use this?

Never use this.
Use [`parse-entities`][parse-entities].
It uses this.

## Install

This package is [ESM only][esm].
In Node.js (version 14.14+, 16.0+), install with [npm][]:

```sh
npm install decode-named-character-reference
```

In Deno with [`esm.sh`][esmsh]:

```js
import {decodeNamedCharacterReference} from 'https://esm.sh/decode-named-character-reference@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {decodeNamedCharacterReference} from 'https://esm.sh/decode-named-character-reference@1?bundle'
</script>
```

## Use

```js
import {decodeNamedCharacterReference} from 'decode-named-character-reference'

decodeNamedCharacterReference('amp') //=> '&'
```

## API

This package exports the identifier `decodeNamedCharacterReference`.
There is no default export.

### `decodeNamedCharacterReference(value)`

Again, use [`parse-entities`][parse-entities].

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

This package is at least compatible with all maintained versions of Node.js.
As of now, that is Node.js 14.14+ and 16.0+.
It also works in Deno and modern browsers.

## Security

This package is safe.

## Related

* [`parse-entities`][parse-entities]
  — parse (decode) HTML character references

## Contribute

Yes please!
See [How to Contribute to Open Source][contribute].

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[author]: https://wooorm.com

[build]: https://github.com/wooorm/decode-named-character-reference/actions

[build-badge]: https://github.com/wooorm/decode-named-character-reference/workflows/main/badge.svg

[contribute]: https://opensource.guide/how-to-contribute/

[coverage]: https://codecov.io/github/wooorm/decode-named-character-reference

[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/decode-named-character-reference.svg

[downloads]: https://www.npmjs.com/package/decode-named-character-reference

[downloads-badge]: https://img.shields.io/npm/dm/decode-named-character-reference.svg

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[license]: license

[npm]: https://docs.npmjs.com/cli/install

[parse-entities]: https://github.com/wooorm/parse-entities

[size]: https://bundlephobia.com/result?p=decode-named-character-reference

[size-badge]: https://img.shields.io/bundlephobia/minzip/decode-named-character-reference.svg

[typescript]: https://www.typescriptlang.org


---

# mimic-response [![Build Status](https://travis-ci.com/sindresorhus/mimic-response.svg?branch=master)](https://travis-ci.com/sindresorhus/mimic-response)

> Mimic a [Node.js HTTP response stream](https://nodejs.org/api/http.html#http_class_http_incomingmessage)

## Install

```
$ npm install mimic-response
```

## Usage

```js
const stream = require('stream');
const mimicResponse = require('mimic-response');

const responseStream = getHttpResponseStream();
const myStream = new stream.PassThrough();

mimicResponse(responseStream, myStream);

console.log(myStream.statusCode);
//=> 200
```

## API

### mimicResponse(from, to)

**Note #1:** The `from.destroy(error)` function is not proxied. You have to call it manually:

```js
const stream = require('stream');
const mimicResponse = require('mimic-response');

const responseStream = getHttpResponseStream();

const myStream = new stream.PassThrough({
	destroy(error, callback) {
		responseStream.destroy();

		callback(error);
	}
});

myStream.destroy();
```

Please note that `myStream` and `responseStream` never throws. The error is passed to the request instead.

#### from

Type: `Stream`

[Node.js HTTP response stream.](https://nodejs.org/api/http.html#http_class_http_incomingmessage)

#### to

Type: `Stream`

Any stream.

## Related

- [mimic-fn](https://github.com/sindresorhus/mimic-fn) - Make a function mimic another one
- [clone-response](https://github.com/lukechilds/clone-response) - Clone a Node.js response stream

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-mimic-response?utm_source=npm-mimic-response&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

# decompress-response [![Build Status](https://travis-ci.com/sindresorhus/decompress-response.svg?branch=master)](https://travis-ci.com/sindresorhus/decompress-response)

> Decompress a HTTP response if needed

Decompresses the [response](https://nodejs.org/api/http.html#http_class_http_incomingmessage) from [`http.request`](https://nodejs.org/api/http.html#http_http_request_options_callback) if it's gzipped, deflated or compressed with Brotli, otherwise just passes it through.

Used by [`got`](https://github.com/sindresorhus/got).

## Install

```
$ npm install decompress-response
```

## Usage

```js
const http = require('http');
const decompressResponse = require('decompress-response');

http.get('https://sindresorhus.com', response => {
	response = decompressResponse(response);
});
```

## API

### decompressResponse(response)

Returns the decompressed HTTP response stream.

#### response

Type: [`http.IncomingMessage`](https://nodejs.org/api/http.html#http_class_http_incomingmessage)

The HTTP incoming stream with compressed data.

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-decompress-response?utm_source=npm-decompress-response&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

Changelog
=========

v0.6.0
------

- Updated "devDependencies" versions to fix vulnerability alerts
- Dropped support of io.js and node.js v0.12.x and lower since new versions of
  "devDependencies" couldn't work with those old node.js versions
  (minimal supported version of node.js now is v4.0.0)

v0.5.1
------

- Fix prototype pollution vulnerability (thanks to @mwakerman for the PR)
- Avoid using deprecated Buffer API (thanks to @ChALkeR for the PR)

v0.5.0
------

- Auto-testing provided by Travis CI;
- Support older Node.JS versions (`v0.11.x` and `v0.10.x`);
- Removed tests files from npm package.

v0.4.2
------

- Fix for `null` as an argument.

v0.4.1
------

- Removed test code from <b>npm</b> package
  ([see pull request #21](https://github.com/unclechu/node-deep-extend/pull/21));
- Increased minimal version of Node from `0.4.0` to `0.12.0`
  (because can't run tests on lesser version anyway).

v0.4.0
------

- **WARNING!** Broken backward compatibility with `v0.3.x`;
- Fixed bug with extending arrays instead of cloning;
- Deep cloning for arrays;
- Check for own property;
- Fixed some documentation issues;
- Strict JS mode.


---

Deep Extend
===========

Recursive object extending.

[![Build Status](https://api.travis-ci.org/unclechu/node-deep-extend.svg?branch=master)](https://travis-ci.org/unclechu/node-deep-extend)

[![NPM](https://nodei.co/npm/deep-extend.png?downloads=true&downloadRank=true&stars=true)](https://nodei.co/npm/deep-extend/)

Install
-------

```bash
$ npm install deep-extend
```

Usage
-----

```javascript
var deepExtend = require('deep-extend');
var obj1 = {
  a: 1,
  b: 2,
  d: {
    a: 1,
    b: [],
    c: { test1: 123, test2: 321 }
  },
  f: 5,
  g: 123,
  i: 321,
  j: [1, 2]
};
var obj2 = {
  b: 3,
  c: 5,
  d: {
    b: { first: 'one', second: 'two' },
    c: { test2: 222 }
  },
  e: { one: 1, two: 2 },
  f: [],
  g: (void 0),
  h: /abc/g,
  i: null,
  j: [3, 4]
};

deepExtend(obj1, obj2);

console.log(obj1);
/*
{ a: 1,
  b: 3,
  d:
   { a: 1,
     b: { first: 'one', second: 'two' },
     c: { test1: 123, test2: 222 } },
  f: [],
  g: undefined,
  c: 5,
  e: { one: 1, two: 2 },
  h: /abc/g,
  i: null,
  j: [3, 4] }
*/
```

Unit testing
------------

```bash
$ npm test
```

Changelog
---------

[CHANGELOG.md](./CHANGELOG.md)

Any issues?
-----------

Please, report about issues
[here](https://github.com/unclechu/node-deep-extend/issues).

License
-------

[MIT](./LICENSE)


---

# [4.3.1](https://github.com/TehShrike/deepmerge/releases/tag/v4.3.1)

- Fix type definition for arrayMerge options.  [#239](https://github.com/TehShrike/deepmerge/pull/239)

# [4.3.0](https://github.com/TehShrike/deepmerge/releases/tag/v4.3.0)

- Avoid thrown errors if the target doesn't have `propertyIsEnumerable`.  [#252](https://github.com/TehShrike/deepmerge/pull/252)

# [4.2.2](https://github.com/TehShrike/deepmerge/releases/tag/v4.2.2)

- `isMergeableObject` is now only called if there are two values that could be merged.  [a34dd4d2](https://github.com/TehShrike/deepmerge/commit/a34dd4d25bf5e250653540a2022bc832c7b00a19)

# [4.2.1](https://github.com/TehShrike/deepmerge/releases/tag/v4.2.1)

- Fix: falsey values can now be merged.  [#170](https://github.com/TehShrike/deepmerge/issues/170)

# [4.2.0](https://github.com/TehShrike/deepmerge/releases/tag/v4.2.0)

- Properties are now only overwritten if they exist on the target object and are enumerable.  [#164](https://github.com/TehShrike/deepmerge/pull/164)

Technically this could probably be a patch release since "which properties get overwritten" wasn't documented and accidentally overwriting a built-in function or some function up the property chain would almost certainly be undesirable, but it feels like a gray area, so here we are with a feature version bump.

# [4.1.2](https://github.com/TehShrike/deepmerge/releases/tag/v4.1.2)

- Rolled back #167 since `Object.assign` breaks ES5 support.  [55067352](https://github.com/TehShrike/deepmerge/commit/55067352a92c65a6c44a5165f3387720aae1e192)

# [4.1.1](https://github.com/TehShrike/deepmerge/releases/tag/v4.1.1)

- The `options` argument is no longer mutated [#167](https://github.com/TehShrike/deepmerge/pull/167)

# [4.1.0](https://github.com/TehShrike/deepmerge/releases/tag/v4.1.0)

- `cloneUnlessOtherwiseSpecified` is now exposed to the `arrayMerge` function [#165](https://github.com/TehShrike/deepmerge/pull/165)

# [4.0.0](https://github.com/TehShrike/deepmerge/releases/tag/v4.0.0)

- The `main` entry point in `package.json` is now a CommonJS module instead of a UMD module [#155](https://github.com/TehShrike/deepmerge/pull/155)

# [3.3.0](https://github.com/TehShrike/deepmerge/releases/tag/v3.3.0)

- Enumerable Symbol properties are now copied [#151](https://github.com/TehShrike/deepmerge/pull/151)

# [3.2.1](https://github.com/TehShrike/deepmerge/releases/tag/v3.2.1)

- bumping dev dependency versions to try to shut up bogus security warnings from Github/npm [#149](https://github.com/TehShrike/deepmerge/pull/149)

# [3.2.0](https://github.com/TehShrike/deepmerge/releases/tag/v3.2.0)

- feature: added the [`customMerge`](https://github.com/TehShrike/deepmerge#custommerge) option [#133](https://github.com/TehShrike/deepmerge/pull/133)

# [3.1.0](https://github.com/TehShrike/deepmerge/releases/tag/v3.1.0)

- typescript typing: make the `all` function generic [#129](https://github.com/TehShrike/deepmerge/pull/129)

# [3.0.0](https://github.com/TehShrike/deepmerge/releases/tag/v3.0.0)

- drop ES module build [#123](https://github.com/TehShrike/deepmerge/issues/123)

# [2.2.1](https://github.com/TehShrike/deepmerge/releases/tag/v2.2.1)

- bug: typescript export type was wrong [#121](https://github.com/TehShrike/deepmerge/pull/121)

# [2.2.0](https://github.com/TehShrike/deepmerge/releases/tag/v2.2.0)

- feature: added TypeScript typings [#119](https://github.com/TehShrike/deepmerge/pull/119)

# [2.1.1](https://github.com/TehShrike/deepmerge/releases/tag/v2.1.1)

- documentation: Rename "methods" to "api", note ESM syntax [#103](https://github.com/TehShrike/deepmerge/pull/103)
- documentation: Fix grammar [#107](https://github.com/TehShrike/deepmerge/pull/107)
- documentation: Restructure headers for clarity + some wording tweaks [108](https://github.com/TehShrike/deepmerge/pull/108) + [109](https://github.com/TehShrike/deepmerge/pull/109)


# [2.1.0](https://github.com/TehShrike/deepmerge/releases/tag/v2.1.0)

- feature: Support a custom `isMergeableObject` function [#96](https://github.com/TehShrike/deepmerge/pull/96)
- documentation: note a Webpack bug that some users might need to work around [#100](https://github.com/TehShrike/deepmerge/pull/100)

# [2.0.1](https://github.com/TehShrike/deepmerge/releases/tag/v2.0.1)

- documentation: fix the old array merge algorithm in the readme.  [#84](https://github.com/TehShrike/deepmerge/pull/84)

# [2.0.0](https://github.com/TehShrike/deepmerge/releases/tag/v2.0.0)

- breaking: the array merge algorithm has changed from a complicated thing to `target.concat(source).map(element => cloneUnlessOtherwiseSpecified(element, optionsArgument))`
- breaking: The `clone` option now defaults to `true`
- feature: `merge.all` now accepts an array of any size, even 0 or 1 elements

See [pull request 77](https://github.com/TehShrike/deepmerge/pull/77).

# [1.5.2](https://github.com/TehShrike/deepmerge/releases/tag/v1.5.2)

- fix: no longer attempts to merge React elements [#76](https://github.com/TehShrike/deepmerge/issues/76)

# [1.5.1](https://github.com/TehShrike/deepmerge/releases/tag/v1.5.1)

- bower support: officially dropping bower support.  If you use bower, please depend on the [unpkg distribution](https://unpkg.com/deepmerge/dist/umd.js).  See [#63](https://github.com/TehShrike/deepmerge/issues/63)

# [1.5.0](https://github.com/TehShrike/deepmerge/releases/tag/v1.5.0)

- bug fix: merging objects into arrays was allowed, and doesn't make any sense. [#65](https://github.com/TehShrike/deepmerge/issues/65) published as a feature release instead of a patch because it is a decent behavior change.

# [1.4.4](https://github.com/TehShrike/deepmerge/releases/tag/v1.4.4)

- bower support: updated `main` in bower.json

# [1.4.3](https://github.com/TehShrike/deepmerge/releases/tag/v1.4.3)

- bower support: inline is-mergeable-object in a new CommonJS build, so that people using both bower and CommonJS can bundle the library [0b34e6](https://github.com/TehShrike/deepmerge/commit/0b34e6e95f989f2fc8091d25f0d291c08f3d2d24)

# [1.4.2](https://github.com/TehShrike/deepmerge/releases/tag/v1.4.2)

- performance: bump is-mergeable-object dependency version for a slight performance improvement [5906c7](https://github.com/TehShrike/deepmerge/commit/5906c765d691d48e83d76efbb0d4b9ca150dc12c)

# [1.4.1](https://github.com/TehShrike/deepmerge/releases/tag/v1.4.1)

- documentation: fix unpkg link [acc45b](https://github.com/TehShrike/deepmerge/commit/acc45be85519c1df906a72ecb24764b622d18d47)

# [1.4.0](https://github.com/TehShrike/deepmerge/releases/tag/v1.4.0)

- api: instead of only exporting a UMD module, expose a UMD module with `pkg.main`, a CJS module with `pkg.browser`, and an ES module with `pkg.module` [#62](https://github.com/TehShrike/deepmerge/pull/62)

# [1.3.2](https://github.com/TehShrike/deepmerge/releases/tag/v1.3.2)

- documentation: note the minified/gzipped file sizes [56](https://github.com/TehShrike/deepmerge/pull/56)
- documentation: make data structures more readable in merge example: pull request [57](https://github.com/TehShrike/deepmerge/pull/57)

# [1.3.1](https://github.com/TehShrike/deepmerge/releases/tag/v1.3.1)

- documentation: clarify and test some array merging documentation: pull request [51](https://github.com/TehShrike/deepmerge/pull/51)

# [1.3.0](https://github.com/TehShrike/deepmerge/releases/tag/v1.3.0)

- feature: `merge.all`, a merge function that merges any number of objects: pull request [50](https://github.com/TehShrike/deepmerge/pull/50)

# [1.2.0](https://github.com/TehShrike/deepmerge/releases/tag/v1.2.0)

- fix: an error that would be thrown when an array would be merged onto a truthy non-array value: pull request [46](https://github.com/TehShrike/deepmerge/pull/46)
- feature: the ability to clone: Issue [28](https://github.com/TehShrike/deepmerge/issues/28), pull requests [44](https://github.com/TehShrike/deepmerge/pull/44) and [48](https://github.com/TehShrike/deepmerge/pull/48)
- maintenance: added tests + travis to `.npmignore`: pull request [47](https://github.com/TehShrike/deepmerge/pull/47)

# [1.1.1](https://github.com/TehShrike/deepmerge/releases/tag/v1.1.1)

- fix an issue where an error was thrown when merging an array onto a non-array: [Pull request 46](https://github.com/TehShrike/deepmerge/pull/46)

# [1.1.0](https://github.com/TehShrike/deepmerge/releases/tag/v1.1.0)

- allow consumers to specify their own array merging algorithm: [Pull request 37](https://github.com/TehShrike/deepmerge/pull/37)

# [1.0.3](https://github.com/TehShrike/deepmerge/releases/tag/v1.0.3)

- adding bower.json back: [Issue 38](https://github.com/TehShrike/deepmerge/pull/38)
- updating keywords and Github links in package.json [bc3898e](https://github.com/TehShrike/deepmerge/commit/bc3898e587a56f74591328f40f656b0152c1d5eb)

# [1.0.2](https://github.com/TehShrike/deepmerge/releases/tag/v1.0.2)

- Updating the readme: dropping bower, testing that the example works: [7102fc](https://github.com/TehShrike/deepmerge/commit/7102fcc4ddec11e2d33205866f9f18df14e5aeb5)

# [1.0.1](https://github.com/TehShrike/deepmerge/releases/tag/v1.0.1)

- `null`, dates, and regular expressions are now properly merged in arrays: [Issue 18](https://github.com/TehShrike/deepmerge/pull/18), plus commit: [ef1c6b](https://github.com/TehShrike/deepmerge/commit/ef1c6bac8350ba12a24966f0bc7da02560827586)

# 1.0.0

- Should only be a patch change, because this module is READY. [Issue 15](https://github.com/TehShrike/deepmerge/issues/15)
- Regular expressions are now treated like primitive values when merging: [Issue 30](https://github.com/TehShrike/deepmerge/pull/30)
- Dates are now treated like primitives when merging: [Issue 31](https://github.com/TehShrike/deepmerge/issues/31)


---

# deepmerge

Merges the enumerable properties of two or more objects deeply.

> UMD bundle is 723B minified+gzipped

## Getting Started

### Example Usage
<!--js
const merge = require('./')
-->

```js
const x = {
	foo: { bar: 3 },
	array: [{
		does: 'work',
		too: [ 1, 2, 3 ]
	}]
}

const y = {
	foo: { baz: 4 },
	quux: 5,
	array: [{
		does: 'work',
		too: [ 4, 5, 6 ]
	}, {
		really: 'yes'
	}]
}

const output = {
	foo: {
		bar: 3,
		baz: 4
	},
	array: [{
		does: 'work',
		too: [ 1, 2, 3 ]
	}, {
		does: 'work',
		too: [ 4, 5, 6 ]
	}, {
		really: 'yes'
	}],
	quux: 5
}

merge(x, y) // => output
```


### Installation

With [npm](http://npmjs.org) do:

```sh
npm install deepmerge
```

deepmerge can be used directly in the browser without the use of package managers/bundlers as well:  [UMD version from unpkg.com](https://unpkg.com/deepmerge/dist/umd.js).


### Include

deepmerge exposes a CommonJS entry point:

```
const merge = require('deepmerge')
```

The ESM entry point was dropped due to a [Webpack bug](https://github.com/webpack/webpack/issues/6584).

# API


## `merge(x, y, [options])`

Merge two objects `x` and `y` deeply, returning a new merged object with the
elements from both `x` and `y`.

If an element at the same key is present for both `x` and `y`, the value from
`y` will appear in the result.

Merging creates a new object, so that neither `x` or `y` is modified.

**Note:** By default, arrays are merged by concatenating them.

## `merge.all(arrayOfObjects, [options])`

Merges any number of objects into a single result object.

```js
const foobar = { foo: { bar: 3 } }
const foobaz = { foo: { baz: 4 } }
const bar = { bar: 'yay!' }

merge.all([ foobar, foobaz, bar ]) // => { foo: { bar: 3, baz: 4 }, bar: 'yay!' }
```


## Options

### `arrayMerge`

There are multiple ways to merge two arrays, below are a few examples but you can also create your own custom function.

Your `arrayMerge` function will be called with three arguments: a `target` array, the `source` array, and an `options` object with these properties:

- `isMergeableObject(value)`
- `cloneUnlessOtherwiseSpecified(value, options)`

#### `arrayMerge` example: overwrite target array

Overwrites the existing array values completely rather than concatenating them:

```js
const overwriteMerge = (destinationArray, sourceArray, options) => sourceArray

merge(
	[1, 2, 3],
	[3, 2, 1],
	{ arrayMerge: overwriteMerge }
) // => [3, 2, 1]
```

#### `arrayMerge` example: combine arrays

Combines objects at the same index in the two arrays.

This was the default array merging algorithm pre-version-2.0.0.

```js
const combineMerge = (target, source, options) => {
	const destination = target.slice()

	source.forEach((item, index) => {
		if (typeof destination[index] === 'undefined') {
			destination[index] = options.cloneUnlessOtherwiseSpecified(item, options)
		} else if (options.isMergeableObject(item)) {
			destination[index] = merge(target[index], item, options)
		} else if (target.indexOf(item) === -1) {
			destination.push(item)
		}
	})
	return destination
}

merge(
	[{ a: true }],
	[{ b: true }, 'ah yup'],
	{ arrayMerge: combineMerge }
) // => [{ a: true, b: true }, 'ah yup']
```

### `isMergeableObject`

By default, deepmerge clones every property from almost every kind of object.

You may not want this, if your objects are of special types, and you want to copy the whole object instead of just copying its properties.

You can accomplish this by passing in a function for the `isMergeableObject` option.

If you only want to clone properties of plain objects, and ignore all "special" kinds of instantiated objects, you probably want to drop in [`is-plain-object`](https://github.com/jonschlinkert/is-plain-object).

```js
const { isPlainObject } = require('is-plain-object')

function SuperSpecial() {
	this.special = 'oh yeah man totally'
}

const instantiatedSpecialObject = new SuperSpecial()

const target = {
	someProperty: {
		cool: 'oh for sure'
	}
}

const source = {
	someProperty: instantiatedSpecialObject
}

const defaultOutput = merge(target, source)

defaultOutput.someProperty.cool // => 'oh for sure'
defaultOutput.someProperty.special // => 'oh yeah man totally'
defaultOutput.someProperty instanceof SuperSpecial // => false

const customMergeOutput = merge(target, source, {
	isMergeableObject: isPlainObject
})

customMergeOutput.someProperty.cool // => undefined
customMergeOutput.someProperty.special // => 'oh yeah man totally'
customMergeOutput.someProperty instanceof SuperSpecial // => true
```

### `customMerge`

Specifies a function which can be used to override the default merge behavior for a property, based on the property name.

The `customMerge` function will be passed the key for each property, and should return the function which should be used to merge the values for that property.

It may also return undefined, in which case the default merge behaviour will be used.

```js
const alex = {
	name: {
		first: 'Alex',
		last: 'Alexson'
	},
	pets: ['Cat', 'Parrot']
}

const tony = {
	name: {
		first: 'Tony',
		last: 'Tonison'
	},
	pets: ['Dog']
}

const mergeNames = (nameA, nameB) => `${nameA.first} and ${nameB.first}`

const options = {
	customMerge: (key) => {
		if (key === 'name') {
			return mergeNames
		}
	}
}

const result = merge(alex, tony, options)

result.name // => 'Alex and Tony'
result.pets // => ['Cat', 'Parrot', 'Dog']
```


### `clone`

*Deprecated.*

Defaults to `true`.

If `clone` is `false` then child objects will be copied directly instead of being cloned.  This was the default behavior before version 2.x.


# Testing

With [npm](http://npmjs.org) do:

```sh
npm test
```


# License

MIT


---

# default-gateway
[![](https://img.shields.io/npm/v/default-gateway.svg?style=flat)](https://www.npmjs.org/package/default-gateway) [![](https://img.shields.io/npm/dm/default-gateway.svg)](https://www.npmjs.org/package/default-gateway)

Obtains the machine's default gateway through `exec` calls to OS routing interfaces.

- On Linux and Android, the `ip` command must be available (usually provided by the `iproute2` package).
- On Windows, `wmic` must be available.
- On IBM i, the `db2util` command must be available (provided by the `db2util` package).
- On Unix (and macOS), the `netstat` command must be available.

## Installation

```
$ npm i default-gateway
```

## Example

```js
const defaultGateway = require('default-gateway');

const {gateway, interface} = await defaultGateway.v4();
// gateway = '1.2.3.4', interface = 'en1'

const {gateway, interface} = await defaultGateway.v6();
// gateway = '2001:db8::1', interface = 'en2'

const {gateway, interface} = defaultGateway.v4.sync();
// gateway = '1.2.3.4', interface = 'en1'

const {gateway, interface} = defaultGateway.v6.sync();
// gateway = '2001:db8::1', interface = 'en2'
```

## API
### defaultGateway.v4()
### defaultGateway.v6()
### defaultGateway.v4.sync()
### defaultGateway.v6.sync()

Returns: `result` *Object*
  - `gateway`: The IP address of the default gateway.
  - `interface`: The name of the interface. On Windows, this is the network adapter name.

The `.v{4,6}()` methods return a Promise while the `.v{4,6}.sync()` variants will return the result synchronously.

The `gateway` property will always be defined on success, while `interface` can be `null` if it cannot be determined. All methods reject/throw on unexpected conditions.

## License

© [silverwind](https://github.com/silverwind), distributed under BSD licence


---

# defer-to-connect

> The safe way to handle the `connect` socket event

[![Coverage Status](https://coveralls.io/repos/github/szmarczak/defer-to-connect/badge.svg?branch=master)](https://coveralls.io/github/szmarczak/defer-to-connect?branch=master)

Once you receive the socket, it may be already connected (or disconnected).<br>
To avoid checking that, use `defer-to-connect`. It'll do that for you.

## Usage

```js
const deferToConnect = require('defer-to-connect');

deferToConnect(socket, () => {
    console.log('Connected!');
});
```

## API

### deferToConnect(socket, connectListener)

Calls `connectListener()` when connected.

### deferToConnect(socket, listeners)

#### listeners

An object representing `connect`, `secureConnect` and `close` properties.

Calls `connect()` when the socket is connected.<br>
Calls `secureConnect()` when the socket is securely connected.<br>
Calls `close()` when the socket is destroyed.

## License

MIT


---

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [v1.1.4](https://github.com/ljharb/define-data-property/compare/v1.1.3...v1.1.4) - 2024-02-13

### Commits

- [Refactor] use `es-define-property` [`90f2f4c`](https://github.com/ljharb/define-data-property/commit/90f2f4cc20298401e71c28e1e08888db12021453)
- [Dev Deps] update `@types/object.getownpropertydescriptors` [`cd929d9`](https://github.com/ljharb/define-data-property/commit/cd929d9a04f5f2fdcfa9d5be140940b91a083153)

## [v1.1.3](https://github.com/ljharb/define-data-property/compare/v1.1.2...v1.1.3) - 2024-02-12

### Commits

- [types] hand-write d.ts instead of emitting it [`0cbc988`](https://github.com/ljharb/define-data-property/commit/0cbc988203c105f2d97948327c7167ebd33bd318)
- [meta] simplify `exports` [`690781e`](https://github.com/ljharb/define-data-property/commit/690781eed28bbf2d6766237efda0ba6dd591609e)
- [Dev Deps] update `hasown`; clean up DT packages [`6cdfd1c`](https://github.com/ljharb/define-data-property/commit/6cdfd1cb2d91d791bfd18cda5d5cab232fd5d8fc)
- [actions] cleanup [`3142bc6`](https://github.com/ljharb/define-data-property/commit/3142bc6a4bc406a51f5b04f31e98562a27f35ffd)
- [meta] add `funding` [`8474423`](https://github.com/ljharb/define-data-property/commit/847442391a79779af3e0f1bf0b5bb923552b7804)
- [Deps] update `get-intrinsic` [`3e9be00`](https://github.com/ljharb/define-data-property/commit/3e9be00e07784ba34e7c77d8bc0fdbc832ad61de)

## [v1.1.2](https://github.com/ljharb/define-data-property/compare/v1.1.1...v1.1.2) - 2024-02-05

### Commits

- [Dev Deps] update @types packages, `object-inspect`, `tape`, `typescript` [`df41bf8`](https://github.com/ljharb/define-data-property/commit/df41bf84ca3456be6226055caab44e38e3a7fd2f)
- [Dev Deps] update DT packages, `aud`, `npmignore`, `tape`, typescript` [`fab0e4e`](https://github.com/ljharb/define-data-property/commit/fab0e4ec709ee02b79f42d6db3ee5f26e0a34b8a)
- [Dev Deps] use `hasown` instead of `has` [`aa51ef9`](https://github.com/ljharb/define-data-property/commit/aa51ef93f6403d49d9bb72a807bcdb6e418978c0)
- [Refactor] use `es-errors`, so things that only need those do not need `get-intrinsic` [`d89be50`](https://github.com/ljharb/define-data-property/commit/d89be50571175888d391238605122679f7e65ffc)
- [Deps] update `has-property-descriptors` [`7af887c`](https://github.com/ljharb/define-data-property/commit/7af887c9083b59b195b0079e04815cfed9fcee2b)
- [Deps] update `get-intrinsic` [`bb8728e`](https://github.com/ljharb/define-data-property/commit/bb8728ec42cd998505a7157ae24853a560c20646)

## [v1.1.1](https://github.com/ljharb/define-data-property/compare/v1.1.0...v1.1.1) - 2023-10-12

### Commits

- [Tests] fix tests in ES3 engines [`5c6920e`](https://github.com/ljharb/define-data-property/commit/5c6920edd1f52f675b02f417e539c28135b43f94)
- [Dev Deps] update `@types/es-value-fixtures`, `@types/for-each`, `@types/gopd`, `@types/has-property-descriptors`, `tape`, `typescript` [`7d82dfc`](https://github.com/ljharb/define-data-property/commit/7d82dfc20f778b4465bba06335dd53f6f431aea3)
- [Fix] IE 8 has a broken `Object.defineProperty` [`0672e1a`](https://github.com/ljharb/define-data-property/commit/0672e1af2a9fcc787e7c23b96dea60d290df5548)
- [meta] emit types on prepack [`73acb1f`](https://github.com/ljharb/define-data-property/commit/73acb1f903c21b314ec7156bf10f73c7910530c0)
- [Dev Deps] update `tape`, `typescript` [`9489a77`](https://github.com/ljharb/define-data-property/commit/9489a7738bf2ecf0ac71d5b78ec4ca6ad7ba0142)

## [v1.1.0](https://github.com/ljharb/define-data-property/compare/v1.0.1...v1.1.0) - 2023-09-13

### Commits

- [New] add `loose` arg [`155235a`](https://github.com/ljharb/define-data-property/commit/155235a4c4d7741f6de01cd87c99599a56654b72)
- [New] allow `null` to be passed for the non* args [`7d2fa5f`](https://github.com/ljharb/define-data-property/commit/7d2fa5f06be0392736c13b126f7cd38979f34792)

## [v1.0.1](https://github.com/ljharb/define-data-property/compare/v1.0.0...v1.0.1) - 2023-09-12

### Commits

- [meta] add TS types [`43d763c`](https://github.com/ljharb/define-data-property/commit/43d763c6c883f652de1c9c02ef6216ee507ffa69)
- [Dev Deps] update `@types/tape`, `typescript` [`f444985`](https://github.com/ljharb/define-data-property/commit/f444985811c36f3e6448a03ad2f9b7898917f4c7)
- [meta] add `safe-publish-latest`, [`172bb10`](https://github.com/ljharb/define-data-property/commit/172bb10890896ebb160e64398f6ee55760107bee)

## v1.0.0 - 2023-09-12

### Commits

- Initial implementation, tests, readme [`5b43d6b`](https://github.com/ljharb/define-data-property/commit/5b43d6b44e675a904810467a7d4e0adb7efc3196)
- Initial commit [`35e577a`](https://github.com/ljharb/define-data-property/commit/35e577a6ba59a98befa97776d70d90f3bea9009d)
- npm init [`82a0a04`](https://github.com/ljharb/define-data-property/commit/82a0a04a321ca7de220af02d41e2745e8a9962ed)
- Only apps should have lockfiles [`96df244`](https://github.com/ljharb/define-data-property/commit/96df244a3c6f426f9a2437be825d1c6f5dd7158e)
- [meta] use `npmignore` to autogenerate an npmignore file [`a87ff18`](https://github.com/ljharb/define-data-property/commit/a87ff18cb79e14c2eb5720486c4759fd9a189375)


---

# define-data-property <sup>[![Version Badge][npm-version-svg]][package-url]</sup>

[![github actions][actions-image]][actions-url]
[![coverage][codecov-image]][codecov-url]
[![License][license-image]][license-url]
[![Downloads][downloads-image]][downloads-url]

[![npm badge][npm-badge-png]][package-url]

Define a data property on an object. Will fall back to assignment in an engine without descriptors.

The three `non*` argument can also be passed `null`, which will use the existing state if available.

The `loose` argument will mean that if you attempt to set a non-normal data property, in an environment without descriptor support, it will fall back to normal assignment.

## Usage

```javascript
var defineDataProperty = require('define-data-property');
var assert = require('assert');

var obj = {};
defineDataProperty(obj, 'key', 'value');
defineDataProperty(
	obj,
	'key2',
	'value',
	true, // nonEnumerable, optional
	false, // nonWritable, optional
	true, // nonConfigurable, optional
	false // loose, optional
);

assert.deepEqual(
	Object.getOwnPropertyDescriptors(obj),
	{
		key: {
			configurable: true,
			enumerable: true,
			value: 'value',
			writable: true,
		},
		key2: {
			configurable: false,
			enumerable: false,
			value: 'value',
			writable: true,
		},
	}
);
```

[package-url]: https://npmjs.org/package/define-data-property
[npm-version-svg]: https://versionbadg.es/ljharb/define-data-property.svg
[deps-svg]: https://david-dm.org/ljharb/define-data-property.svg
[deps-url]: https://david-dm.org/ljharb/define-data-property
[dev-deps-svg]: https://david-dm.org/ljharb/define-data-property/dev-status.svg
[dev-deps-url]: https://david-dm.org/ljharb/define-data-property#info=devDependencies
[npm-badge-png]: https://nodei.co/npm/define-data-property.png?downloads=true&stars=true
[license-image]: https://img.shields.io/npm/l/define-data-property.svg
[license-url]: LICENSE
[downloads-image]: https://img.shields.io/npm/dm/define-data-property.svg
[downloads-url]: https://npm-stat.com/charts.html?package=define-data-property
[codecov-image]: https://codecov.io/gh/ljharb/define-data-property/branch/main/graphs/badge.svg
[codecov-url]: https://app.codecov.io/gh/ljharb/define-data-property/
[actions-image]: https://img.shields.io/endpoint?url=https://github-actions-badge-u3jn4tfpocch.runkit.sh/ljharb/define-data-property
[actions-url]: https://github.com/ljharb/define-data-property/actions


---

# define-lazy-prop [![Build Status](https://travis-ci.org/sindresorhus/define-lazy-prop.svg?branch=master)](https://travis-ci.org/sindresorhus/define-lazy-prop)

> Define a [lazily evaluated](https://en.wikipedia.org/wiki/Lazy_evaluation) property on an object

Useful when the value of a property is expensive to generate, so you want to delay the computation until the property is needed. For example, improving startup performance by deferring nonessential operations.


## Install

```
$ npm install define-lazy-prop
```


## Usage

```js
const defineLazyProp = require('define-lazy-prop');

const unicorn = {
	// …
};

defineLazyProp(unicorn, 'rainbow', () => expensiveComputation());

app.on('user-action', () => {
	doSomething(unicorn.rainbow);
});
```


## API

### defineLazyProp(object, propertyName, fn)

#### object

Type: `Object`

Object to add property to.

#### propertyName

Type: `string`

Name of the property to add.

#### fn

Type: `Function`

Called the first time `propertyName` is accessed. Expected to return a value.


## Related

- [lazy-value](https://github.com/sindresorhus/lazy-value) - Create a lazily evaluated value
- [import-lazy](https://github.com/sindresorhus/import-lazy) - Import a module lazily
- [p-lazy](https://github.com/sindresorhus/p-lazy) - Create a lazy promise


## License

MIT © [Sindre Sorhus](https://sindresorhus.com)


---

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [v1.2.1](https://github.com/ljharb/define-properties/compare/v1.2.0...v1.2.1) - 2023-09-12

### Commits

- [Refactor] use `define-data-property` [`e7782a7`](https://github.com/ljharb/define-properties/commit/e7782a7480a62f8b6e141b49371e6de4df176c97)
- [actions] use reusable rebase action [`cd249c3`](https://github.com/ljharb/define-properties/commit/cd249c3920607bc8eeb7c0cd5b672b810983cac5)
- [Dev Deps] update `@ljharb/eslint-config`, `aud`, `tape` [`8205f97`](https://github.com/ljharb/define-properties/commit/8205f9734a4da8ee5b3b29798788567a09b330e8)

## [v1.2.0](https://github.com/ljharb/define-properties/compare/v1.1.4...v1.2.0) - 2023-02-10

### Commits

- [New] if the predicate is boolean `true`, it compares the existing value with `===` as the predicate [`d8dd6fc`](https://github.com/ljharb/define-properties/commit/d8dd6fca40d7c5878a4b643b91e66ae5a513a194)
- [meta] add `auto-changelog` [`7ebe2b0`](https://github.com/ljharb/define-properties/commit/7ebe2b0a0f90e62b842942cd45e86864fe75d9f6)
- [meta] use `npmignore` to autogenerate an npmignore file [`647478a`](https://github.com/ljharb/define-properties/commit/647478a8401fbf053fb633c0a3a7c982da6bad74)
- [Dev Deps] update `@ljharb/eslint-config`, `aud`, `tape` [`e620d70`](https://github.com/ljharb/define-properties/commit/e620d707d2e1118a38796f22a862200eb0a53fff)
- [Dev Deps] update `aud`, `tape` [`f1e5072`](https://github.com/ljharb/define-properties/commit/f1e507225c2551a99ed4fe40d3fe71b0f44acf88)
- [actions] update checkout action [`628b3af`](https://github.com/ljharb/define-properties/commit/628b3af5c74b8f0963296d811a8f6fa657baf964)

<!-- auto-changelog-above -->

1.1.4 / 2022-04-14
=================
 * [Refactor] use `has-property-descriptors`
 * [readme] add github actions/codecov badges
 * [Docs] fix header parsing; remove testling
 * [Deps] update `object-keys`
 * [meta] use `prepublishOnly` script for npm 7+
 * [meta] add `funding` field; create FUNDING.yml
 * [actions] add "Allow Edits" workflow; automatic rebasing / merge commit blocking
 * [actions] reuse common workflows
 * [actions] update codecov uploader
 * [actions] use `node/install` instead of `node/run`; use `codecov` action
 * [Tests] migrate tests to Github Actions
 * [Tests] run `nyc` on all tests; use `tape` runner
 * [Tests] use shared travis-ci config
 * [Tests] use `npx aud` instead of `nsp` or `npm audit` with hoops
 * [Tests] remove `jscs`
 * [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `safe-publish-latest`, `tape`; add `aud`, `safe-publish-latest`

1.1.3 / 2018-08-14
=================
 * [Refactor] use a for loop instead of `foreach` to make for smaller bundle sizes
 * [Robustness] cache `Array.prototype.concat` and `Object.defineProperty`
 * [Deps] update `object-keys`
 * [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `nsp`, `tape`, `jscs`; remove unused eccheck script + dep
 * [Tests] use pretest/posttest for linting/security
 * [Tests] fix npm upgrades on older nodes

1.1.2 / 2015-10-14
=================
 * [Docs] Switch from vb.teelaun.ch to versionbadg.es for the npm version badge SVG
 * [Deps] Update `object-keys`
 * [Dev Deps] update `jscs`, `tape`, `eslint`, `@ljharb/eslint-config`, `nsp`
 * [Tests] up to `io.js` `v3.3`, `node` `v4.2`

1.1.1 / 2015-07-21
=================
 * [Deps] Update `object-keys`
 * [Dev Deps] Update `tape`, `eslint`
 * [Tests] Test on `io.js` `v2.4`

1.1.0 / 2015-07-01
=================
 * [New] Add support for symbol-valued properties.
 * [Dev Deps] Update `nsp`, `eslint`
 * [Tests] Test up to `io.js` `v2.3`

1.0.3 / 2015-05-30
=================
 * Using a more reliable check for supported property descriptors.

1.0.2 / 2015-05-23
=================
 * Test up to `io.js` `v2.0`
 * Update `tape`, `jscs`, `nsp`, `eslint`, `object-keys`, `editorconfig-tools`, `covert`

1.0.1 / 2015-01-06
=================
 * Update `object-keys` to fix ES3 support

1.0.0 / 2015-01-04
=================
  * v1.0.0


---

# define-properties <sup>[![Version Badge][npm-version-svg]][package-url]</sup>

[![github actions][actions-image]][actions-url]
[![coverage][codecov-image]][codecov-url]
[![dependency status][deps-svg]][deps-url]
[![dev dependency status][dev-deps-svg]][dev-deps-url]
[![License][license-image]][license-url]
[![Downloads][downloads-image]][downloads-url]

[![npm badge][npm-badge-png]][package-url]

Define multiple non-enumerable properties at once. Uses `Object.defineProperty` when available; falls back to standard assignment in older engines.
Existing properties are not overridden. Accepts a map of property names to a predicate that, when true, force-overrides.

## Example

```js
var define = require('define-properties');
var assert = require('assert');

var obj = define({ a: 1, b: 2 }, {
	a: 10,
	b: 20,
	c: 30
});
assert(obj.a === 1);
assert(obj.b === 2);
assert(obj.c === 30);
if (define.supportsDescriptors) {
	assert.deepEqual(Object.keys(obj), ['a', 'b']);
	assert.deepEqual(Object.getOwnPropertyDescriptor(obj, 'c'), {
		configurable: true,
		enumerable: false,
		value: 30,
		writable: false
	});
}
```

Then, with predicates:
```js
var define = require('define-properties');
var assert = require('assert');

var obj = define({ a: 1, b: 2, c: 3 }, {
	a: 10,
	b: 20,
	c: 30
}, {
	a: function () { return false; },
	b: function () { return true; }
});
assert(obj.a === 1);
assert(obj.b === 20);
assert(obj.c === 3);
if (define.supportsDescriptors) {
	assert.deepEqual(Object.keys(obj), ['a', 'c']);
	assert.deepEqual(Object.getOwnPropertyDescriptor(obj, 'b'), {
		configurable: true,
		enumerable: false,
		value: 20,
		writable: false
	});
}
```

## Tests
Simply clone the repo, `npm install`, and run `npm test`

[package-url]: https://npmjs.org/package/define-properties
[npm-version-svg]: https://versionbadg.es/ljharb/define-properties.svg
[deps-svg]: https://david-dm.org/ljharb/define-properties.svg
[deps-url]: https://david-dm.org/ljharb/define-properties
[dev-deps-svg]: https://david-dm.org/ljharb/define-properties/dev-status.svg
[dev-deps-url]: https://david-dm.org/ljharb/define-properties#info=devDependencies
[npm-badge-png]: https://nodei.co/npm/define-properties.png?downloads=true&stars=true
[license-image]: https://img.shields.io/npm/l/define-properties.svg
[license-url]: LICENSE
[downloads-image]: https://img.shields.io/npm/dm/define-properties.svg
[downloads-url]: https://npm-stat.com/charts.html?package=define-properties
[codecov-image]: https://codecov.io/gh/ljharb/define-properties/branch/main/graphs/badge.svg
[codecov-url]: https://app.codecov.io/gh/ljharb/define-properties/
[actions-image]: https://img.shields.io/endpoint?url=https://github-actions-badge-u3jn4tfpocch.runkit.sh/ljharb/define-properties
[actions-url]: https://github.com/ljharb/define-properties/actions


---

# del

> Delete files and directories using [globs](https://github.com/sindresorhus/globby#globbing-patterns)

Similar to [rimraf](https://github.com/isaacs/rimraf), but with a Promise API and support for multiple files and globbing. It also protects you against deleting the current working directory and above.

## Install

```
$ npm install del
```

## Usage

```js
const del = require('del');

(async () => {
	const deletedFilePaths = await del(['temp/*.js', '!temp/unicorn.js']);
	const deletedDirectoryPaths = await del(['temp', 'public']);

	console.log('Deleted files:\n', deletedFilePaths.join('\n'));
	console.log('\n\n');
	console.log('Deleted directories:\n', deletedDirectoryPaths.join('\n'));
})();
```

## Beware

The glob pattern `**` matches all children and *the parent*.

So this won't work:

```js
del.sync(['public/assets/**', '!public/assets/goat.png']);
```

You have to explicitly ignore the parent directories too:

```js
del.sync(['public/assets/**', '!public/assets', '!public/assets/goat.png']);
```

To delete all subdirectories inside `public/`, you can do:

```js
del.sync(['public/*/']);
```

Suggestions on how to improve this welcome!

## API

Note that glob patterns can only contain forward-slashes, not backward-slashes. Windows file paths can use backward-slashes as long as the path does not contain any glob-like characters, otherwise use `path.posix.join()` instead of `path.join()`.

### del(patterns, options?)

Returns `Promise<string[]>` with the deleted paths.

### del.sync(patterns, options?)

Returns `string[]` with the deleted paths.

#### patterns

Type: `string | string[]`

See the supported [glob patterns](https://github.com/sindresorhus/globby#globbing-patterns).

- [Pattern examples with expected matches](https://github.com/sindresorhus/multimatch/blob/main/test/test.js)
- [Quick globbing pattern overview](https://github.com/sindresorhus/multimatch#globbing-patterns)

#### options

Type: `object`

You can specify any of the [`globby` options](https://github.com/sindresorhus/globby#options) in addition to the below options. In contrast to the `globby` defaults, `expandDirectories`, `onlyFiles`, and `followSymbolicLinks` are `false` by default.

##### force

Type: `boolean`\
Default: `false`

Allow deleting the current working directory and outside.

##### dryRun

Type: `boolean`\
Default: `false`

See what would be deleted.

```js
const del = require('del');

(async () => {
	const deletedPaths = await del(['temp/*.js'], {dryRun: true});

	console.log('Files and directories that would be deleted:\n', deletedPaths.join('\n'));
})();
```

##### concurrency

Type: `number`\
Default: `Infinity`\
Minimum: `1`

Concurrency limit.

##### onProgress

Type: `(progress: ProgressData) => void`

Called after each file or directory is deleted.

```js
import del from 'del';

await del(patterns, {
	onProgress: progress => {
	// …
}});
```

###### ProgressData

```js
{
	totalCount: number,
	deletedCount: number,
	percent: number
}
```

- `percent` is a value between `0` and `1`

## CLI

See [del-cli](https://github.com/sindresorhus/del-cli) for a CLI for this module and [trash-cli](https://github.com/sindresorhus/trash-cli) for a safe version that is suitable for running by hand.

## del for enterprise

Available as part of the Tidelift Subscription.

The maintainers of del and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-del?utm_source=npm-del&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)

## Related

- [make-dir](https://github.com/sindresorhus/make-dir) - Make a directory and its parents if needed
- [globby](https://github.com/sindresorhus/globby) - User-friendly glob matching


---

# delayed-stream

Buffers events from a stream until you are ready to handle them.

## Installation

``` bash
npm install delayed-stream
```

## Usage

The following example shows how to write a http echo server that delays its
response by 1000 ms.

``` javascript
var DelayedStream = require('delayed-stream');
var http = require('http');

http.createServer(function(req, res) {
  var delayed = DelayedStream.create(req);

  setTimeout(function() {
    res.writeHead(200);
    delayed.pipe(res);
  }, 1000);
});
```

If you are not using `Stream#pipe`, you can also manually release the buffered
events by calling `delayedStream.resume()`:

``` javascript
var delayed = DelayedStream.create(req);

setTimeout(function() {
  // Emit all buffered events and resume underlaying source
  delayed.resume();
}, 1000);
```

## Implementation

In order to use this meta stream properly, here are a few things you should
know about the implementation.

### Event Buffering / Proxying

All events of the `source` stream are hijacked by overwriting the `source.emit`
method. Until node implements a catch-all event listener, this is the only way.

However, delayed-stream still continues to emit all events it captures on the
`source`, regardless of whether you have released the delayed stream yet or
not.

Upon creation, delayed-stream captures all `source` events and stores them in
an internal event buffer. Once `delayedStream.release()` is called, all
buffered events are emitted on the `delayedStream`, and the event buffer is
cleared. After that, delayed-stream merely acts as a proxy for the underlaying
source.

### Error handling

Error events on `source` are buffered / proxied just like any other events.
However, `delayedStream.create` attaches a no-op `'error'` listener to the
`source`. This way you only have to handle errors on the `delayedStream`
object, rather than in two places.

### Buffer limits

delayed-stream provides a `maxDataSize` property that can be used to limit
the amount of data being buffered. In order to protect you from bad `source`
streams that don't react to `source.pause()`, this feature is enabled by
default.

## API

### DelayedStream.create(source, [options])

Returns a new `delayedStream`. Available options are:

* `pauseStream`
* `maxDataSize`

The description for those properties can be found below.

### delayedStream.source

The `source` stream managed by this object. This is useful if you are
passing your `delayedStream` around, and you still want to access properties
on the `source` object.

### delayedStream.pauseStream = true

Whether to pause the underlaying `source` when calling
`DelayedStream.create()`. Modifying this property afterwards has no effect.

### delayedStream.maxDataSize = 1024 * 1024

The amount of data to buffer before emitting an `error`.

If the underlaying source is emitting `Buffer` objects, the `maxDataSize`
refers to bytes.

If the underlaying source is emitting JavaScript strings, the size refers to
characters.

If you know what you are doing, you can set this property to `Infinity` to
disable this feature. You can also modify this property during runtime.

### delayedStream.dataSize = 0

The amount of data buffered so far.

### delayedStream.readable

An ECMA5 getter that returns the value of `source.readable`.

### delayedStream.resume()

If the `delayedStream` has not been released so far, `delayedStream.release()`
is called.

In either case, `source.resume()` is called.

### delayedStream.pause()

Calls `source.pause()`.

### delayedStream.pipe(dest)

Calls `delayedStream.resume()` and then proxies the arguments to `source.pipe`.

### delayedStream.release()

Emits and clears all events that have been buffered up so far. This does not
resume the underlaying source, use `delayedStream.resume()` instead.

## License

delayed-stream is licensed under the MIT license.


---

2.0.0 / 2018-10-26
==================

  * Drop support for Node.js 0.6
  * Replace internal `eval` usage with `Function` constructor
  * Use instance methods on `process` to check for listeners

1.1.2 / 2018-01-11
==================

  * perf: remove argument reassignment
  * Support Node.js 0.6 to 9.x

1.1.1 / 2017-07-27
==================

  * Remove unnecessary `Buffer` loading
  * Support Node.js 0.6 to 8.x

1.1.0 / 2015-09-14
==================

  * Enable strict mode in more places
  * Support io.js 3.x
  * Support io.js 2.x
  * Support web browser loading
    - Requires bundler like Browserify or webpack

1.0.1 / 2015-04-07
==================

  * Fix `TypeError`s when under `'use strict'` code
  * Fix useless type name on auto-generated messages
  * Support io.js 1.x
  * Support Node.js 0.12

1.0.0 / 2014-09-17
==================

  * No changes

0.4.5 / 2014-09-09
==================

  * Improve call speed to functions using the function wrapper
  * Support Node.js 0.6

0.4.4 / 2014-07-27
==================

  * Work-around v8 generating empty stack traces

0.4.3 / 2014-07-26
==================

  * Fix exception when global `Error.stackTraceLimit` is too low

0.4.2 / 2014-07-19
==================

  * Correct call site for wrapped functions and properties

0.4.1 / 2014-07-19
==================

  * Improve automatic message generation for function properties

0.4.0 / 2014-07-19
==================

  * Add `TRACE_DEPRECATION` environment variable
  * Remove non-standard grey color from color output
  * Support `--no-deprecation` argument
  * Support `--trace-deprecation` argument
  * Support `deprecate.property(fn, prop, message)`

0.3.0 / 2014-06-16
==================

  * Add `NO_DEPRECATION` environment variable

0.2.0 / 2014-06-15
==================

  * Add `deprecate.property(obj, prop, message)`
  * Remove `supports-color` dependency for node.js 0.8

0.1.0 / 2014-06-15
==================

  * Add `deprecate.function(fn, message)`
  * Add `process.on('deprecation', fn)` emitter
  * Automatically generate message when omitted from `deprecate()`

0.0.1 / 2014-06-15
==================

  * Fix warning for dynamic calls at singe call site

0.0.0 / 2014-06-15
==================

  * Initial implementation


---

# depd

[![NPM Version][npm-version-image]][npm-url]
[![NPM Downloads][npm-downloads-image]][npm-url]
[![Node.js Version][node-image]][node-url]
[![Linux Build][travis-image]][travis-url]
[![Windows Build][appveyor-image]][appveyor-url]
[![Coverage Status][coveralls-image]][coveralls-url]

Deprecate all the things

> With great modules comes great responsibility; mark things deprecated!

## Install

This module is installed directly using `npm`:

```sh
$ npm install depd
```

This module can also be bundled with systems like
[Browserify](http://browserify.org/) or [webpack](https://webpack.github.io/),
though by default this module will alter it's API to no longer display or
track deprecations.

## API

<!-- eslint-disable no-unused-vars -->

```js
var deprecate = require('depd')('my-module')
```

This library allows you to display deprecation messages to your users.
This library goes above and beyond with deprecation warnings by
introspection of the call stack (but only the bits that it is interested
in).

Instead of just warning on the first invocation of a deprecated
function and never again, this module will warn on the first invocation
of a deprecated function per unique call site, making it ideal to alert
users of all deprecated uses across the code base, rather than just
whatever happens to execute first.

The deprecation warnings from this module also include the file and line
information for the call into the module that the deprecated function was
in.

**NOTE** this library has a similar interface to the `debug` module, and
this module uses the calling file to get the boundary for the call stacks,
so you should always create a new `deprecate` object in each file and not
within some central file.

### depd(namespace)

Create a new deprecate function that uses the given namespace name in the
messages and will display the call site prior to the stack entering the
file this function was called from. It is highly suggested you use the
name of your module as the namespace.

### deprecate(message)

Call this function from deprecated code to display a deprecation message.
This message will appear once per unique caller site. Caller site is the
first call site in the stack in a different file from the caller of this
function.

If the message is omitted, a message is generated for you based on the site
of the `deprecate()` call and will display the name of the function called,
similar to the name displayed in a stack trace.

### deprecate.function(fn, message)

Call this function to wrap a given function in a deprecation message on any
call to the function. An optional message can be supplied to provide a custom
message.

### deprecate.property(obj, prop, message)

Call this function to wrap a given property on object in a deprecation message
on any accessing or setting of the property. An optional message can be supplied
to provide a custom message.

The method must be called on the object where the property belongs (not
inherited from the prototype).

If the property is a data descriptor, it will be converted to an accessor
descriptor in order to display the deprecation message.

### process.on('deprecation', fn)

This module will allow easy capturing of deprecation errors by emitting the
errors as the type "deprecation" on the global `process`. If there are no
listeners for this type, the errors are written to STDERR as normal, but if
there are any listeners, nothing will be written to STDERR and instead only
emitted. From there, you can write the errors in a different format or to a
logging source.

The error represents the deprecation and is emitted only once with the same
rules as writing to STDERR. The error has the following properties:

  - `message` - This is the message given by the library
  - `name` - This is always `'DeprecationError'`
  - `namespace` - This is the namespace the deprecation came from
  - `stack` - This is the stack of the call to the deprecated thing

Example `error.stack` output:

```
DeprecationError: my-cool-module deprecated oldfunction
    at Object.<anonymous> ([eval]-wrapper:6:22)
    at Module._compile (module.js:456:26)
    at evalScript (node.js:532:25)
    at startup (node.js:80:7)
    at node.js:902:3
```

### process.env.NO_DEPRECATION

As a user of modules that are deprecated, the environment variable `NO_DEPRECATION`
is provided as a quick solution to silencing deprecation warnings from being
output. The format of this is similar to that of `DEBUG`:

```sh
$ NO_DEPRECATION=my-module,othermod node app.js
```

This will suppress deprecations from being output for "my-module" and "othermod".
The value is a list of comma-separated namespaces. To suppress every warning
across all namespaces, use the value `*` for a namespace.

Providing the argument `--no-deprecation` to the `node` executable will suppress
all deprecations (only available in Node.js 0.8 or higher).

**NOTE** This will not suppress the deperecations given to any "deprecation"
event listeners, just the output to STDERR.

### process.env.TRACE_DEPRECATION

As a user of modules that are deprecated, the environment variable `TRACE_DEPRECATION`
is provided as a solution to getting more detailed location information in deprecation
warnings by including the entire stack trace. The format of this is the same as
`NO_DEPRECATION`:

```sh
$ TRACE_DEPRECATION=my-module,othermod node app.js
```

This will include stack traces for deprecations being output for "my-module" and
"othermod". The value is a list of comma-separated namespaces. To trace every
warning across all namespaces, use the value `*` for a namespace.

Providing the argument `--trace-deprecation` to the `node` executable will trace
all deprecations (only available in Node.js 0.8 or higher).

**NOTE** This will not trace the deperecations silenced by `NO_DEPRECATION`.

## Display

![message](files/message.png)

When a user calls a function in your library that you mark deprecated, they
will see the following written to STDERR (in the given colors, similar colors
and layout to the `debug` module):

```
bright cyan    bright yellow
|              |          reset       cyan
|              |          |           |
▼              ▼          ▼           ▼
my-cool-module deprecated oldfunction [eval]-wrapper:6:22
▲              ▲          ▲           ▲
|              |          |           |
namespace      |          |           location of mycoolmod.oldfunction() call
               |          deprecation message
               the word "deprecated"
```

If the user redirects their STDERR to a file or somewhere that does not support
colors, they see (similar layout to the `debug` module):

```
Sun, 15 Jun 2014 05:21:37 GMT my-cool-module deprecated oldfunction at [eval]-wrapper:6:22
▲                             ▲              ▲          ▲              ▲
|                             |              |          |              |
timestamp of message          namespace      |          |             location of mycoolmod.oldfunction() call
                                             |          deprecation message
                                             the word "deprecated"
```

## Examples

### Deprecating all calls to a function

This will display a deprecated message about "oldfunction" being deprecated
from "my-module" on STDERR.

```js
var deprecate = require('depd')('my-cool-module')

// message automatically derived from function name
// Object.oldfunction
exports.oldfunction = deprecate.function(function oldfunction () {
  // all calls to function are deprecated
})

// specific message
exports.oldfunction = deprecate.function(function () {
  // all calls to function are deprecated
}, 'oldfunction')
```

### Conditionally deprecating a function call

This will display a deprecated message about "weirdfunction" being deprecated
from "my-module" on STDERR when called with less than 2 arguments.

```js
var deprecate = require('depd')('my-cool-module')

exports.weirdfunction = function () {
  if (arguments.length < 2) {
    // calls with 0 or 1 args are deprecated
    deprecate('weirdfunction args < 2')
  }
}
```

When calling `deprecate` as a function, the warning is counted per call site
within your own module, so you can display different deprecations depending
on different situations and the users will still get all the warnings:

```js
var deprecate = require('depd')('my-cool-module')

exports.weirdfunction = function () {
  if (arguments.length < 2) {
    // calls with 0 or 1 args are deprecated
    deprecate('weirdfunction args < 2')
  } else if (typeof arguments[0] !== 'string') {
    // calls with non-string first argument are deprecated
    deprecate('weirdfunction non-string first arg')
  }
}
```

### Deprecating property access

This will display a deprecated message about "oldprop" being deprecated
from "my-module" on STDERR when accessed. A deprecation will be displayed
when setting the value and when getting the value.

```js
var deprecate = require('depd')('my-cool-module')

exports.oldprop = 'something'

// message automatically derives from property name
deprecate.property(exports, 'oldprop')

// explicit message
deprecate.property(exports, 'oldprop', 'oldprop >= 0.10')
```

## License

[MIT](LICENSE)

[appveyor-image]: https://badgen.net/appveyor/ci/dougwilson/nodejs-depd/master?label=windows
[appveyor-url]: https://ci.appveyor.com/project/dougwilson/nodejs-depd
[coveralls-image]: https://badgen.net/coveralls/c/github/dougwilson/nodejs-depd/master
[coveralls-url]: https://coveralls.io/r/dougwilson/nodejs-depd?branch=master
[node-image]: https://badgen.net/npm/node/depd
[node-url]: https://nodejs.org/en/download/
[npm-downloads-image]: https://badgen.net/npm/dm/depd
[npm-url]: https://npmjs.org/package/depd
[npm-version-image]: https://badgen.net/npm/v/depd
[travis-image]: https://badgen.net/travis/dougwilson/nodejs-depd/master?label=linux
[travis-url]: https://travis-ci.org/dougwilson/nodejs-depd


---

# dequal [![CI](https://github.com/lukeed/dequal/workflows/CI/badge.svg)](https://github.com/lukeed/dequal/actions)

> A tiny (304B to 489B) utility to check for deep equality

This module supports comparison of all types, including `Function`, `RegExp`, `Date`, `Set`, `Map`, `TypedArray`s, `DataView`, `null`, `undefined`, and `NaN` values. Complex values (eg, Objects, Arrays, Sets, Maps, etc) are traversed recursively.

> **Important:**
> * key order **within Objects** does not matter
> * value order **within Arrays** _does_ matter
> * values **within Sets and Maps** use value equality
> * keys **within Maps** use value equality


## Install

```
$ npm install --save dequal
```

## Modes

There are two "versions" of `dequal` available:

#### `dequal`
> **Size (gzip):** 489 bytes<br>
> **Availability:** [CommonJS](https://unpkg.com/dequal/dist/index.js), [ES Module](https://unpkg.com/dequal/dist/index.mjs), [UMD](https://unpkg.com/dequal/dist/index.min.js)

#### `dequal/lite`
> **Size (gzip):** 304 bytes<br>
> **Availability:** [CommonJS](https://unpkg.com/dequal/lite/index.js), [ES Module](https://unpkg.com/dequal/lite/index.mjs)

|  | IE9+ | Number | String | Date | RegExp | Object | Array | Class | Set | Map | ArrayBuffer | [TypedArray](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray#TypedArray_objects) | [DataView](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView) |
|-|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
| `dequal` | :x: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| `dequal/lite` | :+1: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | :x: | :x: | :x: | :x: |

> <sup>**Note:** Table scrolls horizontally!</sup>

## Usage

```js
import { dequal } from 'dequal';

dequal(1, 1); //=> true
dequal({}, {}); //=> true
dequal('foo', 'foo'); //=> true
dequal([1, 2, 3], [1, 2, 3]); //=> true
dequal(dequal, dequal); //=> true
dequal(/foo/, /foo/); //=> true
dequal(null, null); //=> true
dequal(NaN, NaN); //=> true
dequal([], []); //=> true
dequal(
  [{ a:1 }, [{ b:{ c:[1] } }]],
  [{ a:1 }, [{ b:{ c:[1] } }]]
); //=> true

dequal(1, '1'); //=> false
dequal(null, undefined); //=> false
dequal({ a:1, b:[2,3] }, { a:1, b:[2,5] }); //=> false
dequal(/foo/i, /bar/g); //=> false
```

## API

### dequal(foo, bar)
Returns: `Boolean`

Both `foo` and `bar` can be of any type.<br>
A `Boolean` is returned indicating if the two were deeply equal.


## Benchmarks

> Running Node v10.13.0

The benchmarks can be found in the [`/bench`](/bench) directory. They are separated into two categories:

* `basic` – compares an object comprised of `String`, `Number`, `Date`, `Array`, and `Object` values.
* `complex` – like `basic`, but adds `RegExp`, `Map`, `Set`, and `Uint8Array` values.

> **Note:** Only candidates that pass validation step(s) are listed. <br>For example, `fast-deep-equal/es6` handles `Set` and `Map` values, but uses _referential equality_ while those listed use _value equality_.

```
Load times:
  assert             0.109ms
  util               0.006ms
  fast-deep-equal    0.479ms
  lodash/isequal    22.826ms
  nano-equal         0.417ms
  dequal             0.396ms
  dequal/lite        0.264ms

Benchmark :: basic
  assert.deepStrictEqual  x    325,262 ops/sec ±0.57% (94 runs sampled)
  util.isDeepStrictEqual  x    318,812 ops/sec ±0.87% (94 runs sampled)
  fast-deep-equal         x  1,332,393 ops/sec ±0.36% (93 runs sampled)
  lodash.isEqual          x    269,129 ops/sec ±0.59% (95 runs sampled)
  nano-equal              x  1,122,053 ops/sec ±0.36% (96 runs sampled)
  dequal/lite             x  1,700,972 ops/sec ±0.31% (94 runs sampled)
  dequal                  x  1,698,972 ops/sec ±0.63% (97 runs sampled)

Benchmark :: complex
  assert.deepStrictEqual  x    124,518 ops/sec ±0.64% (96 runs sampled)
  util.isDeepStrictEqual  x    125,113 ops/sec ±0.24% (96 runs sampled)
  lodash.isEqual          x     58,677 ops/sec ±0.49% (96 runs sampled)
  dequal                  x    345,386 ops/sec ±0.27% (96 runs sampled)
```

## License

MIT © [Luke Edwards](https://lukeed.com)


---

# destroy

[![NPM version][npm-image]][npm-url]
[![Build Status][github-actions-ci-image]][github-actions-ci-url]
[![Test coverage][coveralls-image]][coveralls-url]
[![License][license-image]][license-url]
[![Downloads][downloads-image]][downloads-url]

Destroy a stream.

This module is meant to ensure a stream gets destroyed, handling different APIs
and Node.js bugs.

## API

```js
var destroy = require('destroy')
```

### destroy(stream [, suppress])

Destroy the given stream, and optionally suppress any future `error` events.

In most cases, this is identical to a simple `stream.destroy()` call. The rules
are as follows for a given stream:

  1. If the `stream` is an instance of `ReadStream`, then call `stream.destroy()`
     and add a listener to the `open` event to call `stream.close()` if it is
     fired. This is for a Node.js bug that will leak a file descriptor if
     `.destroy()` is called before `open`.
  2. If the `stream` is an instance of a zlib stream, then call `stream.destroy()`
     and close the underlying zlib handle if open, otherwise call `stream.close()`.
     This is for consistency across Node.js versions and a Node.js bug that will
     leak a native zlib handle.
  3. If the `stream` is not an instance of `Stream`, then nothing happens.
  4. If the `stream` has a `.destroy()` method, then call it.

The function returns the `stream` passed in as the argument.

## Example

```js
var destroy = require('destroy')

var fs = require('fs')
var stream = fs.createReadStream('package.json')

// ... and later
destroy(stream)
```

[npm-image]: https://img.shields.io/npm/v/destroy.svg?style=flat-square
[npm-url]: https://npmjs.org/package/destroy
[github-tag]: http://img.shields.io/github/tag/stream-utils/destroy.svg?style=flat-square
[github-url]: https://github.com/stream-utils/destroy/tags
[coveralls-image]: https://img.shields.io/coveralls/stream-utils/destroy.svg?style=flat-square
[coveralls-url]: https://coveralls.io/r/stream-utils/destroy?branch=master
[license-image]: http://img.shields.io/npm/l/destroy.svg?style=flat-square
[license-url]: LICENSE.md
[downloads-image]: http://img.shields.io/npm/dm/destroy.svg?style=flat-square
[downloads-url]: https://npmjs.org/package/destroy
[github-actions-ci-image]: https://img.shields.io/github/workflow/status/stream-utils/destroy/ci/master?label=ci&style=flat-square
[github-actions-ci-url]: https://github.com/stream-utils/destroy/actions/workflows/ci.yml


---

### Install

```shell
npm install --save detect-node
```

### Usage:

```js
var isNode = require('detect-node');

if (isNode) {
  console.log("Running under Node.JS");
} else {
  alert("Hello from browser (or whatever not-a-node env)");
}
```

The check is performed as:
```js
module.exports = false;

// Only Node.JS has a process variable that is of [[Class]] process
try {
 module.exports = Object.prototype.toString.call(global.process) === '[object process]' 
} catch(e) {}

```

Thanks to Ingvar Stepanyan for the initial idea. This check is both **the most reliable I could find** and it does not use `process` env directly, which would cause browserify to include it into the build.


---

[![logo][logo-image]][logo-url]

---

[![NPM version][npm-image]][npm-url]
[![build status][travis-image]][travis-url]
[![Test coverage][codecov-image]][codecov-url]
[![npm download][download-image]][download-url]

[logo-image]: ./logo.png
[logo-url]: https://npmjs.org/package/detect-port
[npm-image]: https://img.shields.io/npm/v/detect-port.svg
[npm-url]: https://npmjs.org/package/detect-port
[travis-image]: https://img.shields.io/travis/node-modules/detect-port.svg
[travis-url]: https://travis-ci.org/node-modules/detect-port
[codecov-image]: https://img.shields.io/coveralls/node-modules/detect-port.svg
[codecov-url]: https://codecov.io/gh/node-modules/detect-port
[download-image]: https://img.shields.io/npm/dm/detect-port.svg
[download-url]: https://npmjs.org/package/detect-port

> Node.js implementation of port detector

## Who are using or has used

- ⭐⭐⭐[eggjs/egg](//github.com/eggjs/egg)
- ⭐⭐⭐[alibaba/ice](//github.com/alibaba/ice)
- ⭐⭐⭐[alibaba/uirecorder](//github.com/alibaba/uirecorder)
- ⭐⭐⭐[facebook/create-react-app](//github.com/facebook/create-react-app/blob/main/packages/react-dev-utils/package.json)
- ⭐⭐⭐[facebook/flipper](//github.com/facebook/flipper)
- ⭐⭐⭐[umijs/umi](//github.com/umijs/umi)
- ⭐⭐⭐[gatsbyjs/gatsby](//github.com/gatsbyjs/gatsby)
- ⭐⭐⭐[electron-react-boilerplate/electron-react-boilerplate](//github.com/electron-react-boilerplate/electron-react-boilerplate)
- ⭐⭐⭐[zeit/micro](//github.com/zeit/micro)
- ⭐⭐⭐[rails/webpacker](//github.com/rails/webpacker)
- ⭐⭐⭐[storybookjs/storybook](//github.com/storybookjs/storybook)

[For more](//github.com/node-modules/detect-port/network/dependents)

## Usage

```bash
$ npm i detect-port --save
```

```javascript
const detect = require('detect-port');
/**
 * use as a promise
 */

detect(port)
  .then(_port => {
    if (port == _port) {
      console.log(`port: ${port} was not occupied`);
    } else {
      console.log(`port: ${port} was occupied, try port: ${_port}`);
    }
  })
  .catch(err => {
    console.log(err);
  });

```

## Command Line Tool

```bash
$ npm i detect-port -g
```

### Quick Start

```bash
# get an available port randomly
$ detect

# detect pointed port
$ detect 80

# output verbose log
$ detect --verbose

# more help
$ detect --help
```

## FAQ

Most likely network error, check that your `/etc/hosts` and make sure the content below:

```
127.0.0.1       localhost
255.255.255.255 broadcasthost
::1             localhost
```

<!-- GITCONTRIBUTOR_START -->

## Contributors

|[<img src="https://avatars.githubusercontent.com/u/1011681?v=4" width="100px;"/><br/><sub><b>xudafeng</b></sub>](https://github.com/xudafeng)<br/>|[<img src="https://avatars.githubusercontent.com/u/156269?v=4" width="100px;"/><br/><sub><b>fengmk2</b></sub>](https://github.com/fengmk2)<br/>|[<img src="https://avatars.githubusercontent.com/u/1044425?v=4" width="100px;"/><br/><sub><b>ziczhu</b></sub>](https://github.com/ziczhu)<br/>|[<img src="https://avatars.githubusercontent.com/u/810438?v=4" width="100px;"/><br/><sub><b>gaearon</b></sub>](https://github.com/gaearon)<br/>|[<img src="https://avatars.githubusercontent.com/u/34906299?v=4" width="100px;"/><br/><sub><b>chnliquan</b></sub>](https://github.com/chnliquan)<br/>|[<img src="https://avatars.githubusercontent.com/u/360661?v=4" width="100px;"/><br/><sub><b>popomore</b></sub>](https://github.com/popomore)<br/>|
| :---: | :---: | :---: | :---: | :---: | :---: |
[<img src="https://avatars.githubusercontent.com/u/52845048?v=4" width="100px;"/><br/><sub><b>snapre</b></sub>](https://github.com/snapre)<br/>|[<img src="https://avatars.githubusercontent.com/u/56271907?v=4" width="100px;"/><br/><sub><b>yavuzakyuz</b></sub>](https://github.com/yavuzakyuz)<br/>|[<img src="https://avatars.githubusercontent.com/u/197375?v=4" width="100px;"/><br/><sub><b>antife-yinyue</b></sub>](https://github.com/antife-yinyue)<br/>

This project follows the git-contributor [spec](https://github.com/xudafeng/git-contributor), auto updated at `Wed Sep 21 2022 23:10:27 GMT+0800`.

<!-- GITCONTRIBUTOR_END -->

## License

[MIT](LICENSE)


---

# Contributing to detect-port

- Fork the project, make a change, and send a pull request;
- Have a look at code style now before starting;
- Make sure the tests case (`$ make test`) pass before sending a pull request;


---


1.1.2 / 2017-05-11
==================

  * fix: should double check 0.0.0.0 and localhost (#20)
  * docs: ignore type of port when checking if it's occupied (#18)

# 1.1.1 / 2017-03-17

  * fix: try to use next available port (#16)

# 1.1.0 / 2016-01-17

  * Use server listen to detect port

# 1.0.7 / 2016-12-11

  * Early return for rejected promise
  * Prevent promsie swallow in callback

# 1.0.6 / 2016-11-29

  * Bump version for new Repo

# 0.1.4 / 2015-08-24

  * Support promise

# 0.1.2 / 2014-05-31

  * Fix commander

# 0.1.1 / 2014-05-30

  * Add command line support

# 0.1.0  / 2014-05-29

  * Initial release


---

[![logo][logo-image]][logo-url]

---

[![NPM version][npm-image]][npm-url]
[![build status][travis-image]][travis-url]
[![Test coverage][codecov-image]][codecov-url]
[![npm download][download-image]][download-url]

[logo-image]: ./logo.png
[logo-url]: https://npmjs.org/package/detect-port
[npm-image]: https://img.shields.io/npm/v/detect-port.svg?style=flat-square
[npm-url]: https://npmjs.org/package/detect-port
[travis-image]: https://img.shields.io/travis/node-modules/detect-port.svg?style=flat-square
[travis-url]: https://travis-ci.org/node-modules/detect-port
[codecov-image]: https://codecov.io/gh/node-modules/detect-port/branch/master/graph/badge.svg
[codecov-url]: https://codecov.io/gh/node-modules/detect-port
[download-image]: https://img.shields.io/npm/dm/detect-port.svg?style=flat-square
[download-url]: https://npmjs.org/package/detect-port

> JavaScript Implementation of Port Detector

## Usage

```bash
$ npm i detect-port --save
```

```js
const detect = require('detect-port');

/**
 * callback usage
 */

detect(port, (err, _port) => {
  if (err) {
    console.log(err);
  }

  if (port == _port) {
    console.log(`port: ${port} was not occupied`);
  } else {
    console.log(`port: ${port} was occupied, try port: ${_port}`);
  }
});

/**
 * for a yield syntax instead of callback function implement
 */

const co = require('co');

co(function *() {
  const _port = yield detect(port);

  if (port == _port) {
    console.log(`port: ${port} was not occupied`);
  } else {
    console.log(`port: ${port} was occupied, try port: ${_port}`);
  }
});

/**
 * use as a promise
 */

detect(port)
  .then(_port => {
    if (port == _port) {
      console.log(`port: ${port} was not occupied`);
    } else {
      console.log(`port: ${port} was occupied, try port: ${_port}`);
    }
  })
  .catch(err => {
    console.log(err);
  });

```

## Command Line Tool

```shell
$ npm i detect-port -g
```

### Quick Start

```shell
# get an available port randomly
$ detect

# detect pointed port
$ detect 80

# more help
$ detect --help
```

## Authors

- [xudafeng](//github.com/xudafeng)
- [zenzhu](//github.com/zenzhu)

## License

[MIT](LICENSE)


---


2.6.9 / 2017-09-22
==================

  * remove ReDoS regexp in %o formatter (#504)

2.6.8 / 2017-05-18
==================

  * Fix: Check for undefined on browser globals (#462, @marbemac)

2.6.7 / 2017-05-16
==================

  * Fix: Update ms to 2.0.0 to fix regular expression denial of service vulnerability (#458, @hubdotcom)
  * Fix: Inline extend function in node implementation (#452, @dougwilson)
  * Docs: Fix typo (#455, @msasad)

2.6.5 / 2017-04-27
==================
  
  * Fix: null reference check on window.documentElement.style.WebkitAppearance (#447, @thebigredgeek)
  * Misc: clean up browser reference checks (#447, @thebigredgeek)
  * Misc: add npm-debug.log to .gitignore (@thebigredgeek)


2.6.4 / 2017-04-20
==================

  * Fix: bug that would occure if process.env.DEBUG is a non-string value. (#444, @LucianBuzzo)
  * Chore: ignore bower.json in npm installations. (#437, @joaovieira)
  * Misc: update "ms" to v0.7.3 (@tootallnate)

2.6.3 / 2017-03-13
==================

  * Fix: Electron reference to `process.env.DEBUG` (#431, @paulcbetts)
  * Docs: Changelog fix (@thebigredgeek)

2.6.2 / 2017-03-10
==================

  * Fix: DEBUG_MAX_ARRAY_LENGTH (#420, @slavaGanzin)
  * Docs: Add backers and sponsors from Open Collective (#422, @piamancini)
  * Docs: Add Slackin invite badge (@tootallnate)

2.6.1 / 2017-02-10
==================

  * Fix: Module's `export default` syntax fix for IE8 `Expected identifier` error
  * Fix: Whitelist DEBUG_FD for values 1 and 2 only (#415, @pi0)
  * Fix: IE8 "Expected identifier" error (#414, @vgoma)
  * Fix: Namespaces would not disable once enabled (#409, @musikov)

2.6.0 / 2016-12-28
==================

  * Fix: added better null pointer checks for browser useColors (@thebigredgeek)
  * Improvement: removed explicit `window.debug` export (#404, @tootallnate)
  * Improvement: deprecated `DEBUG_FD` environment variable (#405, @tootallnate)

2.5.2 / 2016-12-25
==================

  * Fix: reference error on window within webworkers (#393, @KlausTrainer)
  * Docs: fixed README typo (#391, @lurch)
  * Docs: added notice about v3 api discussion (@thebigredgeek)

2.5.1 / 2016-12-20
==================

  * Fix: babel-core compatibility

2.5.0 / 2016-12-20
==================

  * Fix: wrong reference in bower file (@thebigredgeek)
  * Fix: webworker compatibility (@thebigredgeek)
  * Fix: output formatting issue (#388, @kribblo)
  * Fix: babel-loader compatibility (#383, @escwald)
  * Misc: removed built asset from repo and publications (@thebigredgeek)
  * Misc: moved source files to /src (#378, @yamikuronue)
  * Test: added karma integration and replaced babel with browserify for browser tests (#378, @yamikuronue)
  * Test: coveralls integration (#378, @yamikuronue)
  * Docs: simplified language in the opening paragraph (#373, @yamikuronue)

2.4.5 / 2016-12-17
==================

  * Fix: `navigator` undefined in Rhino (#376, @jochenberger)
  * Fix: custom log function (#379, @hsiliev)
  * Improvement: bit of cleanup + linting fixes (@thebigredgeek)
  * Improvement: rm non-maintainted `dist/` dir (#375, @freewil)
  * Docs: simplified language in the opening paragraph. (#373, @yamikuronue)

2.4.4 / 2016-12-14
==================

  * Fix: work around debug being loaded in preload scripts for electron (#368, @paulcbetts)

2.4.3 / 2016-12-14
==================

  * Fix: navigation.userAgent error for react native (#364, @escwald)

2.4.2 / 2016-12-14
==================

  * Fix: browser colors (#367, @tootallnate)
  * Misc: travis ci integration (@thebigredgeek)
  * Misc: added linting and testing boilerplate with sanity check (@thebigredgeek)

2.4.1 / 2016-12-13
==================

  * Fix: typo that broke the package (#356)

2.4.0 / 2016-12-13
==================

  * Fix: bower.json references unbuilt src entry point (#342, @justmatt)
  * Fix: revert "handle regex special characters" (@tootallnate)
  * Feature: configurable util.inspect()`options for NodeJS (#327, @tootallnate)
  * Feature: %O`(big O) pretty-prints objects (#322, @tootallnate)
  * Improvement: allow colors in workers (#335, @botverse)
  * Improvement: use same color for same namespace. (#338, @lchenay)

2.3.3 / 2016-11-09
==================

  * Fix: Catch `JSON.stringify()` errors (#195, Jovan Alleyne)
  * Fix: Returning `localStorage` saved values (#331, Levi Thomason)
  * Improvement: Don't create an empty object when no `process` (Nathan Rajlich)

2.3.2 / 2016-11-09
==================

  * Fix: be super-safe in index.js as well (@TooTallNate)
  * Fix: should check whether process exists (Tom Newby)

2.3.1 / 2016-11-09
==================

  * Fix: Added electron compatibility (#324, @paulcbetts)
  * Improvement: Added performance optimizations (@tootallnate)
  * Readme: Corrected PowerShell environment variable example (#252, @gimre)
  * Misc: Removed yarn lock file from source control (#321, @fengmk2)

2.3.0 / 2016-11-07
==================

  * Fix: Consistent placement of ms diff at end of output (#215, @gorangajic)
  * Fix: Escaping of regex special characters in namespace strings (#250, @zacronos)
  * Fix: Fixed bug causing crash on react-native (#282, @vkarpov15)
  * Feature: Enabled ES6+ compatible import via default export (#212 @bucaran)
  * Feature: Added %O formatter to reflect Chrome's console.log capability (#279, @oncletom)
  * Package: Update "ms" to 0.7.2 (#315, @DevSide)
  * Package: removed superfluous version property from bower.json (#207 @kkirsche)
  * Readme: fix USE_COLORS to DEBUG_COLORS
  * Readme: Doc fixes for format string sugar (#269, @mlucool)
  * Readme: Updated docs for DEBUG_FD and DEBUG_COLORS environment variables (#232, @mattlyons0)
  * Readme: doc fixes for PowerShell (#271 #243, @exoticknight @unreadable)
  * Readme: better docs for browser support (#224, @matthewmueller)
  * Tooling: Added yarn integration for development (#317, @thebigredgeek)
  * Misc: Renamed History.md to CHANGELOG.md (@thebigredgeek)
  * Misc: Added license file (#226 #274, @CantemoInternal @sdaitzman)
  * Misc: Updated contributors (@thebigredgeek)

2.2.0 / 2015-05-09
==================

  * package: update "ms" to v0.7.1 (#202, @dougwilson)
  * README: add logging to file example (#193, @DanielOchoa)
  * README: fixed a typo (#191, @amir-s)
  * browser: expose `storage` (#190, @stephenmathieson)
  * Makefile: add a `distclean` target (#189, @stephenmathieson)

2.1.3 / 2015-03-13
==================

  * Updated stdout/stderr example (#186)
  * Updated example/stdout.js to match debug current behaviour
  * Renamed example/stderr.js to stdout.js
  * Update Readme.md (#184)
  * replace high intensity foreground color for bold (#182, #183)

2.1.2 / 2015-03-01
==================

  * dist: recompile
  * update "ms" to v0.7.0
  * package: update "browserify" to v9.0.3
  * component: fix "ms.js" repo location
  * changed bower package name
  * updated documentation about using debug in a browser
  * fix: security error on safari (#167, #168, @yields)

2.1.1 / 2014-12-29
==================

  * browser: use `typeof` to check for `console` existence
  * browser: check for `console.log` truthiness (fix IE 8/9)
  * browser: add support for Chrome apps
  * Readme: added Windows usage remarks
  * Add `bower.json` to properly support bower install

2.1.0 / 2014-10-15
==================

  * node: implement `DEBUG_FD` env variable support
  * package: update "browserify" to v6.1.0
  * package: add "license" field to package.json (#135, @panuhorsmalahti)

2.0.0 / 2014-09-01
==================

  * package: update "browserify" to v5.11.0
  * node: use stderr rather than stdout for logging (#29, @stephenmathieson)

1.0.4 / 2014-07-15
==================

  * dist: recompile
  * example: remove `console.info()` log usage
  * example: add "Content-Type" UTF-8 header to browser example
  * browser: place %c marker after the space character
  * browser: reset the "content" color via `color: inherit`
  * browser: add colors support for Firefox >= v31
  * debug: prefer an instance `log()` function over the global one (#119)
  * Readme: update documentation about styled console logs for FF v31 (#116, @wryk)

1.0.3 / 2014-07-09
==================

  * Add support for multiple wildcards in namespaces (#122, @seegno)
  * browser: fix lint

1.0.2 / 2014-06-10
==================

  * browser: update color palette (#113, @gscottolson)
  * common: make console logging function configurable (#108, @timoxley)
  * node: fix %o colors on old node <= 0.8.x
  * Makefile: find node path using shell/which (#109, @timoxley)

1.0.1 / 2014-06-06
==================

  * browser: use `removeItem()` to clear localStorage
  * browser, node: don't set DEBUG if namespaces is undefined (#107, @leedm777)
  * package: add "contributors" section
  * node: fix comment typo
  * README: list authors

1.0.0 / 2014-06-04
==================

  * make ms diff be global, not be scope
  * debug: ignore empty strings in enable()
  * node: make DEBUG_COLORS able to disable coloring
  * *: export the `colors` array
  * npmignore: don't publish the `dist` dir
  * Makefile: refactor to use browserify
  * package: add "browserify" as a dev dependency
  * Readme: add Web Inspector Colors section
  * node: reset terminal color for the debug content
  * node: map "%o" to `util.inspect()`
  * browser: map "%j" to `JSON.stringify()`
  * debug: add custom "formatters"
  * debug: use "ms" module for humanizing the diff
  * Readme: add "bash" syntax highlighting
  * browser: add Firebug color support
  * browser: add colors for WebKit browsers
  * node: apply log to `console`
  * rewrite: abstract common logic for Node & browsers
  * add .jshintrc file

0.8.1 / 2014-04-14
==================

  * package: re-add the "component" section

0.8.0 / 2014-03-30
==================

  * add `enable()` method for nodejs. Closes #27
  * change from stderr to stdout
  * remove unnecessary index.js file

0.7.4 / 2013-11-13
==================

  * remove "browserify" key from package.json (fixes something in browserify)

0.7.3 / 2013-10-30
==================

  * fix: catch localStorage security error when cookies are blocked (Chrome)
  * add debug(err) support. Closes #46
  * add .browser prop to package.json. Closes #42

0.7.2 / 2013-02-06
==================

  * fix package.json
  * fix: Mobile Safari (private mode) is broken with debug
  * fix: Use unicode to send escape character to shell instead of octal to work with strict mode javascript

0.7.1 / 2013-02-05
==================

  * add repository URL to package.json
  * add DEBUG_COLORED to force colored output
  * add browserify support
  * fix component. Closes #24

0.7.0 / 2012-05-04
==================

  * Added .component to package.json
  * Added debug.component.js build

0.6.0 / 2012-03-16
==================

  * Added support for "-" prefix in DEBUG [Vinay Pulim]
  * Added `.enabled` flag to the node version [TooTallNate]

0.5.0 / 2012-02-02
==================

  * Added: humanize diffs. Closes #8
  * Added `debug.disable()` to the CS variant
  * Removed padding. Closes #10
  * Fixed: persist client-side variant again. Closes #9

0.4.0 / 2012-02-01
==================

  * Added browser variant support for older browsers [TooTallNate]
  * Added `debug.enable('project:*')` to browser variant [TooTallNate]
  * Added padding to diff (moved it to the right)

0.3.0 / 2012-01-26
==================

  * Added millisecond diff when isatty, otherwise UTC string

0.2.0 / 2012-01-22
==================

  * Added wildcard support

0.1.0 / 2011-12-02
==================

  * Added: remove colors unless stderr isatty [TooTallNate]

0.0.1 / 2010-01-03
==================

  * Initial release


---

# debug
[![Build Status](https://travis-ci.org/visionmedia/debug.svg?branch=master)](https://travis-ci.org/visionmedia/debug)  [![Coverage Status](https://coveralls.io/repos/github/visionmedia/debug/badge.svg?branch=master)](https://coveralls.io/github/visionmedia/debug?branch=master)  [![Slack](https://visionmedia-community-slackin.now.sh/badge.svg)](https://visionmedia-community-slackin.now.sh/) [![OpenCollective](https://opencollective.com/debug/backers/badge.svg)](#backers) 
[![OpenCollective](https://opencollective.com/debug/sponsors/badge.svg)](#sponsors)



A tiny node.js debugging utility modelled after node core's debugging technique.

**Discussion around the V3 API is under way [here](https://github.com/visionmedia/debug/issues/370)**

## Installation

```bash
$ npm install debug
```

## Usage

`debug` exposes a function; simply pass this function the name of your module, and it will return a decorated version of `console.error` for you to pass debug statements to. This will allow you to toggle the debug output for different parts of your module as well as the module as a whole.

Example _app.js_:

```js
var debug = require('debug')('http')
  , http = require('http')
  , name = 'My App';

// fake app

debug('booting %s', name);

http.createServer(function(req, res){
  debug(req.method + ' ' + req.url);
  res.end('hello\n');
}).listen(3000, function(){
  debug('listening');
});

// fake worker of some kind

require('./worker');
```

Example _worker.js_:

```js
var debug = require('debug')('worker');

setInterval(function(){
  debug('doing some work');
}, 1000);
```

 The __DEBUG__ environment variable is then used to enable these based on space or comma-delimited names. Here are some examples:

  ![debug http and worker](http://f.cl.ly/items/18471z1H402O24072r1J/Screenshot.png)

  ![debug worker](http://f.cl.ly/items/1X413v1a3M0d3C2c1E0i/Screenshot.png)

#### Windows note

 On Windows the environment variable is set using the `set` command.

 ```cmd
 set DEBUG=*,-not_this
 ```

 Note that PowerShell uses different syntax to set environment variables.

 ```cmd
 $env:DEBUG = "*,-not_this"
  ```

Then, run the program to be debugged as usual.

## Millisecond diff

  When actively developing an application it can be useful to see when the time spent between one `debug()` call and the next. Suppose for example you invoke `debug()` before requesting a resource, and after as well, the "+NNNms" will show you how much time was spent between calls.

  ![](http://f.cl.ly/items/2i3h1d3t121M2Z1A3Q0N/Screenshot.png)

  When stdout is not a TTY, `Date#toUTCString()` is used, making it more useful for logging the debug information as shown below:

  ![](http://f.cl.ly/items/112H3i0e0o0P0a2Q2r11/Screenshot.png)

## Conventions

  If you're using this in one or more of your libraries, you _should_ use the name of your library so that developers may toggle debugging as desired without guessing names. If you have more than one debuggers you _should_ prefix them with your library name and use ":" to separate features. For example "bodyParser" from Connect would then be "connect:bodyParser".

## Wildcards

  The `*` character may be used as a wildcard. Suppose for example your library has debuggers named "connect:bodyParser", "connect:compress", "connect:session", instead of listing all three with `DEBUG=connect:bodyParser,connect:compress,connect:session`, you may simply do `DEBUG=connect:*`, or to run everything using this module simply use `DEBUG=*`.

  You can also exclude specific debuggers by prefixing them with a "-" character.  For example, `DEBUG=*,-connect:*` would include all debuggers except those starting with "connect:".

## Environment Variables

  When running through Node.js, you can set a few environment variables that will
  change the behavior of the debug logging:

| Name      | Purpose                                         |
|-----------|-------------------------------------------------|
| `DEBUG`   | Enables/disables specific debugging namespaces. |
| `DEBUG_COLORS`| Whether or not to use colors in the debug output. |
| `DEBUG_DEPTH` | Object inspection depth. |
| `DEBUG_SHOW_HIDDEN` | Shows hidden properties on inspected objects. |


  __Note:__ The environment variables beginning with `DEBUG_` end up being
  converted into an Options object that gets used with `%o`/`%O` formatters.
  See the Node.js documentation for
  [`util.inspect()`](https://nodejs.org/api/util.html#util_util_inspect_object_options)
  for the complete list.

## Formatters


  Debug uses [printf-style](https://wikipedia.org/wiki/Printf_format_string) formatting. Below are the officially supported formatters:

| Formatter | Representation |
|-----------|----------------|
| `%O`      | Pretty-print an Object on multiple lines. |
| `%o`      | Pretty-print an Object all on a single line. |
| `%s`      | String. |
| `%d`      | Number (both integer and float). |
| `%j`      | JSON. Replaced with the string '[Circular]' if the argument contains circular references. |
| `%%`      | Single percent sign ('%'). This does not consume an argument. |

### Custom formatters

  You can add custom formatters by extending the `debug.formatters` object. For example, if you wanted to add support for rendering a Buffer as hex with `%h`, you could do something like:

```js
const createDebug = require('debug')
createDebug.formatters.h = (v) => {
  return v.toString('hex')
}

// …elsewhere
const debug = createDebug('foo')
debug('this is hex: %h', new Buffer('hello world'))
//   foo this is hex: 68656c6c6f20776f726c6421 +0ms
```

## Browser support
  You can build a browser-ready script using [browserify](https://github.com/substack/node-browserify),
  or just use the [browserify-as-a-service](https://wzrd.in/) [build](https://wzrd.in/standalone/debug@latest),
  if you don't want to build it yourself.

  Debug's enable state is currently persisted by `localStorage`.
  Consider the situation shown below where you have `worker:a` and `worker:b`,
  and wish to debug both. You can enable this using `localStorage.debug`:

```js
localStorage.debug = 'worker:*'
```

And then refresh the page.

```js
a = debug('worker:a');
b = debug('worker:b');

setInterval(function(){
  a('doing some work');
}, 1000);

setInterval(function(){
  b('doing some work');
}, 1200);
```

#### Web Inspector Colors

  Colors are also enabled on "Web Inspectors" that understand the `%c` formatting
  option. These are WebKit web inspectors, Firefox ([since version
  31](https://hacks.mozilla.org/2014/05/editable-box-model-multiple-selection-sublime-text-keys-much-more-firefox-developer-tools-episode-31/))
  and the Firebug plugin for Firefox (any version).

  Colored output looks something like:

  ![](https://cloud.githubusercontent.com/assets/71256/3139768/b98c5fd8-e8ef-11e3-862a-f7253b6f47c6.png)


## Output streams

  By default `debug` will log to stderr, however this can be configured per-namespace by overriding the `log` method:

Example _stdout.js_:

```js
var debug = require('debug');
var error = debug('app:error');

// by default stderr is used
error('goes to stderr!');

var log = debug('app:log');
// set this namespace to log via console.log
log.log = console.log.bind(console); // don't forget to bind to console!
log('goes to stdout');
error('still goes to stderr!');

// set all output to go via console.info
// overrides all per-namespace log settings
debug.log = console.info.bind(console);
error('now goes to stdout via console.info');
log('still goes to stdout, but via console.info now');
```


## Authors

 - TJ Holowaychuk
 - Nathan Rajlich
 - Andrew Rhyne
 
## Backers

Support us with a monthly donation and help us continue our activities. [[Become a backer](https://opencollective.com/debug#backer)]

<a href="https://opencollective.com/debug/backer/0/website" target="_blank"><img src="https://opencollective.com/debug/backer/0/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/1/website" target="_blank"><img src="https://opencollective.com/debug/backer/1/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/2/website" target="_blank"><img src="https://opencollective.com/debug/backer/2/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/3/website" target="_blank"><img src="https://opencollective.com/debug/backer/3/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/4/website" target="_blank"><img src="https://opencollective.com/debug/backer/4/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/5/website" target="_blank"><img src="https://opencollective.com/debug/backer/5/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/6/website" target="_blank"><img src="https://opencollective.com/debug/backer/6/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/7/website" target="_blank"><img src="https://opencollective.com/debug/backer/7/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/8/website" target="_blank"><img src="https://opencollective.com/debug/backer/8/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/9/website" target="_blank"><img src="https://opencollective.com/debug/backer/9/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/10/website" target="_blank"><img src="https://opencollective.com/debug/backer/10/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/11/website" target="_blank"><img src="https://opencollective.com/debug/backer/11/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/12/website" target="_blank"><img src="https://opencollective.com/debug/backer/12/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/13/website" target="_blank"><img src="https://opencollective.com/debug/backer/13/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/14/website" target="_blank"><img src="https://opencollective.com/debug/backer/14/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/15/website" target="_blank"><img src="https://opencollective.com/debug/backer/15/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/16/website" target="_blank"><img src="https://opencollective.com/debug/backer/16/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/17/website" target="_blank"><img src="https://opencollective.com/debug/backer/17/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/18/website" target="_blank"><img src="https://opencollective.com/debug/backer/18/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/19/website" target="_blank"><img src="https://opencollective.com/debug/backer/19/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/20/website" target="_blank"><img src="https://opencollective.com/debug/backer/20/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/21/website" target="_blank"><img src="https://opencollective.com/debug/backer/21/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/22/website" target="_blank"><img src="https://opencollective.com/debug/backer/22/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/23/website" target="_blank"><img src="https://opencollective.com/debug/backer/23/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/24/website" target="_blank"><img src="https://opencollective.com/debug/backer/24/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/25/website" target="_blank"><img src="https://opencollective.com/debug/backer/25/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/26/website" target="_blank"><img src="https://opencollective.com/debug/backer/26/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/27/website" target="_blank"><img src="https://opencollective.com/debug/backer/27/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/28/website" target="_blank"><img src="https://opencollective.com/debug/backer/28/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/29/website" target="_blank"><img src="https://opencollective.com/debug/backer/29/avatar.svg"></a>


## Sponsors

Become a sponsor and get your logo on our README on Github with a link to your site. [[Become a sponsor](https://opencollective.com/debug#sponsor)]

<a href="https://opencollective.com/debug/sponsor/0/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/0/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/1/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/1/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/2/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/2/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/3/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/3/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/4/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/4/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/5/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/5/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/6/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/6/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/7/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/7/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/8/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/8/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/9/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/9/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/10/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/10/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/11/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/11/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/12/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/12/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/13/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/13/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/14/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/14/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/15/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/15/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/16/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/16/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/17/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/17/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/18/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/18/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/19/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/19/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/20/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/20/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/21/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/21/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/22/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/22/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/23/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/23/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/24/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/24/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/25/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/25/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/26/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/26/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/27/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/27/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/28/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/28/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/29/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/29/avatar.svg"></a>

## License

(The MIT License)

Copyright (c) 2014-2016 TJ Holowaychuk &lt;tj@vision-media.ca&gt;

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
'Software'), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


---

The MIT License (MIT)

Copyright (c) 2016 Zeit, Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# ms

[![Build Status](https://travis-ci.org/zeit/ms.svg?branch=master)](https://travis-ci.org/zeit/ms)
[![Slack Channel](http://zeit-slackin.now.sh/badge.svg)](https://zeit.chat/)

Use this package to easily convert various time formats to milliseconds.

## Examples

```js
ms('2 days')  // 172800000
ms('1d')      // 86400000
ms('10h')     // 36000000
ms('2.5 hrs') // 9000000
ms('2h')      // 7200000
ms('1m')      // 60000
ms('5s')      // 5000
ms('1y')      // 31557600000
ms('100')     // 100
```

### Convert from milliseconds

```js
ms(60000)             // "1m"
ms(2 * 60000)         // "2m"
ms(ms('10 hours'))    // "10h"
```

### Time format written-out

```js
ms(60000, { long: true })             // "1 minute"
ms(2 * 60000, { long: true })         // "2 minutes"
ms(ms('10 hours'), { long: true })    // "10 hours"
```

## Features

- Works both in [node](https://nodejs.org) and in the browser.
- If a number is supplied to `ms`, a string with a unit is returned.
- If a string that contains the number is supplied, it returns it as a number (e.g.: it returns `100` for `'100'`).
- If you pass a string with a number and a valid unit, the number of equivalent ms is returned.

## Caught a bug?

1. [Fork](https://help.github.com/articles/fork-a-repo/) this repository to your own GitHub account and then [clone](https://help.github.com/articles/cloning-a-repository/) it to your local device
2. Link the package to the global module directory: `npm link`
3. Within the module you want to test your local development instance of ms, just link it to the dependencies: `npm link ms`. Instead of the default one from npm, node will now use your clone of ms!

As always, you can run the tests using: `npm test`


---

# devlop

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]

Some tools to make developing easier while not including code in production.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`deprecate(fn, message[, code])`](#deprecatefn-message-code)
    *   [`equal(actual, expected[, message])`](#equalactual-expected-message)
    *   [`ok(value[, message])`](#okvalue-message)
    *   [`unreachable(message?)`](#unreachablemessage)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Security](#security)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package lets you do things in development that are free in production.
It contains useful `assert` functions and a `deprecate` function that are
useful when developing JavaScript packages while being small in production.

If you know Rust, you might know how nice having a
[`debug_assert!`][rust-debug-assert] is.
This is that, and a bit more.
For more on why they’re nice, see
[“Rust’s Two Kinds of ‘Assert’ Make for Better Code”][rust-two-kinds]

## When should I use this?

Many JavaScript programs do not use assertions at all (perhaps because they’re
typed and so assume type safety) or include lots of code to throw errors when
users do weird things (weighing down production code).
This package hopes to improve the sitation by making assertions free and
deprecations cheap.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install devlop
```

In Deno with [`esm.sh`][esmsh]:

```js
import {deprecate, equal, ok, unreachable} from 'https://esm.sh/devlop@1'
// For development code:
// import {deprecate, equal, ok} from 'https://esm.sh/devlop@1?conditions=development'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {deprecate, equal, ok, unreachable} from 'https://esm.sh/devlop@1?bundle'
  // For development code:
  // import {deprecate, equal, ok} from 'https://esm.sh/devlop@1?bundle&conditions=development'
</script>
```

## Use

Say we have a small ponyfill for the ES5 `String#includes` function.
It’s deprecated, because folks can use `String#includes` nowadays.
It’s nicely typed so users should be able to figure out what to pass but we
include assertions to show nicer errors when they get it wrong.

`example/string-includes.js`:

```js
import {deprecate, ok} from 'devlop'

export const stringIncludes = deprecate(
  includes,
  'Since ES5, please use `String#includes` itself.'
)

/**
 * @deprecated
 *   Since ES5, please use `String#includes` itself.
 * @param {string} value
 *   Value to search in.
 * @param {string} search
 *   Value to search for.
 * @param {number | undefined} [position=0]
 *   Position to search from (default: `0`).
 * @returns {boolean}
 *   Whether the searched for value exists in the searched value after position.
 */
function includes(value, search, position) {
  ok(typeof value === 'string', 'expected string for `value`')
  ok(typeof search === 'string', 'expected string for `search`')
  ok(position === undefined || typeof position === 'number', 'expected number')
  ok(
    position === undefined ||
      (typeof position === 'number' &&
        !(/* #__PURE__ */ Number.isNaN(position))),
    'expected number'
  )
  // eslint-disable-next-line unicorn/prefer-includes
  return value.indexOf(search, position || 0) !== -1
}
```

`example/index.js`:

```js
import {stringIncludes} from './example-includes.js'

console.log(stringIncludes('blue whale', 'dolphin')) //=> false
console.log(stringIncludes('blue whale', 'whale')) //=> true
```

Say we’d bundle that in development with [`esbuild`][esbuild] and check the
gzip size ([`gzip-size-cli`][gzip-size-cli]), we’d get 1.02 kB of code:

```sh
$ esbuild example/index.js --bundle --conditions=development --format=esm --minify --target=es2022 | gzip-size
1.02 kB
```

But because `devlop` is light in production we’d get:

```sh
$ esbuild example/index.js --bundle --format=esm --minify --target=es2022 | gzip-size
169 B
```

The bundle looks as follows:

```js
function u(n){return n}var r=u(c,"Since ES5, please use `String#includes` itself.");function c(n,t,e){return n.indexOf(t,e||0)!==-1}console.log(r("blue whale","dolphin"));console.log(r("blue whale","whale"));
```

It depends a bit on which bundler and minifier you use how small the code is:
esbuild keeps the unused message parameter to the `deprecate` function around
and does not know `Number.isNaN` can be dropped without a `/* #__PURE__ */`
annotation.

[`rollup`][rollup] with [`@rollup/plugin-node-resolve`][node-resolve]
and [`@rollup/plugin-terser`][terser] performs even better:

```sh
$ rollup example/index.js -p node-resolve -p terser | gzip-size
118 B
```

The bundle looks as follows:

```js
const l=function(l,e,o){return-1!==l.indexOf(e,o||0)};console.log(l("blue whale","dolphin")),console.log(l("blue whale","whale"));
```

Rollup doesn’t need the `/* #__PURE__ */` comment either!

## API

This package exports the identifiers [`deprecate`][api-deprecate],
[`equal`][api-equal], [`ok`][api-ok], and [`unreachable`][api-unreachable].
There is no default export.

The export map supports the [`development` condition][node-condition].
Run `node --conditions development module.js` to get dev code.
Without this condition, no-ops are loaded.

### `deprecate(fn, message[, code])`

Wrap a function or class to show a deprecation message when first called.

> 👉 **Important**: only shows a message when the `development` condition is
> used, does nothing in production.

When the resulting wrapped `fn` is called, emits a warning once to
`console.error` (`stderr`).
If a code is given, one warning message will be emitted in total per code.

###### Parameters

*   `fn` (`Function`)
    — function or class
*   `message` (`string`)
    — message explaining deprecation
*   `code` (`string`, optional)
    — deprecation identifier (optional); deprecation messages will be generated
    only once per code

###### Returns

Wrapped `fn`.

### `equal(actual, expected[, message])`

Assert deep strict equivalence.

> 👉 **Important**: only asserts when the `development` condition is used, does
> nothing in production.

###### Parameters

*   `actual` (`unknown`)
    — value
*   `expected` (`unknown`)
    — baseline
*   `message` (`Error` or `string`, default: `'Expected values to be deeply
    equal'`)
    — message for assertion error

###### Returns

Nothing (`undefined`).

###### Throws

Throws (`AssertionError`) when `actual` is not deep strict equal to `expected`.

### `ok(value[, message])`

Assert if `value` is truthy.

> 👉 **Important**: only asserts when the `development` condition is used, does
> nothing in production.

###### Parameters

*   `actual` (`unknown`)
    — value to assert
*   `message` (`Error` or `string`, default: `'Expected value to be truthy'`)
    — message for assertion error

###### Returns

Nothing (`undefined`).

###### Throws

Throws (`AssertionError`) when `value` is falsey.

### `unreachable(message?)`

Assert that a code path never happens.

> 👉 **Important**: only asserts when the `development` condition is used,
> does nothing in production.

###### Parameters

*   `message` (`Error` or `string`, default: `'Unreachable'`)
    — message for assertion error

###### Returns

Never (`never`).

###### Throws

Throws (`AssertionError`), always.

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

This project is compatible with maintained versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, `devlop@^1`,
compatible with Node.js 16.

## Security

This package is safe.

## Related

*   [`babel-plugin-unassert`](https://github.com/unassert-js/babel-plugin-unassert)
    — encourage reliable programming with assertions while compiling them away
    in production (can remove arbitrary `assert` modules, works regardless of
    conditions, so has to be configured by the end user)

## Contribute

Yes please!
See [How to Contribute to Open Source][contribute].

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definition -->

[build-badge]: https://github.com/wooorm/devlop/workflows/main/badge.svg

[build]: https://github.com/wooorm/devlop/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/devlop.svg

[coverage]: https://codecov.io/github/wooorm/devlop

[downloads-badge]: https://img.shields.io/npm/dm/devlop.svg

[downloads]: https://www.npmjs.com/package/devlop

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=devlop

[size]: https://bundlejs.com/?q=devlop

[npm]: https://docs.npmjs.com/cli/install

[esmsh]: https://esm.sh

[license]: license

[author]: https://wooorm.com

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[typescript]: https://www.typescriptlang.org

[contribute]: https://opensource.guide/how-to-contribute/

[node-condition]: https://nodejs.org/api/packages.html#packages_resolving_user_conditions

[rust-debug-assert]: https://doc.rust-lang.org/std/macro.debug_assert.html

[rust-two-kinds]: https://tratt.net/laurie/blog/2023/rusts_two_kinds_of_assert_make_for_better_code.html

[esbuild]: https://esbuild.github.io

[gzip-size-cli]: https://github.com/sindresorhus/gzip-size-cli/tree/main

[rollup]: https://rollupjs.org

[node-resolve]: https://github.com/rollup/plugins/tree/master/packages/node-resolve

[terser]: https://github.com/rollup/plugins/tree/master/packages/terser#readme

[api-deprecate]: #deprecatefn-message-code

[api-equal]: #equalactual-expected-message

[api-ok]: #okvalue-message

[api-unreachable]: #unreachablemessage


---

# dir-glob [![Build Status](https://travis-ci.org/kevva/dir-glob.svg?branch=master)](https://travis-ci.org/kevva/dir-glob)

> Convert directories to glob compatible strings


## Install

```
$ npm install dir-glob
```


## Usage

```js
const dirGlob = require('dir-glob');

(async () => {
	console.log(await dirGlob(['index.js', 'test.js', 'fixtures']));
	//=> ['index.js', 'test.js', 'fixtures/**']

	console.log(await dirGlob(['index.js', 'inner_folder'], {cwd: 'fixtures'}));
	//=> ['index.js', 'inner_folder/**']

	console.log(await dirGlob(['lib/**', 'fixtures'], {
		files: ['test', 'unicorn']
		extensions: ['js']
	}));
	//=> ['lib/**', 'fixtures/**/test.js', 'fixtures/**/unicorn.js']

	console.log(await dirGlob(['lib/**', 'fixtures'], {
		files: ['test', 'unicorn', '*.jsx'],
		extensions: ['js', 'png']
	}));
	//=> ['lib/**', 'fixtures/**/test.{js,png}', 'fixtures/**/unicorn.{js,png}', 'fixtures/**/*.jsx']
})();
```


## API

### dirGlob(input, options?)

Returns a `Promise<string[]>` with globs.

### dirGlob.sync(input, options?)

Returns a `string[]` with globs.

#### input

Type: `string | string[]`

Paths.

#### options

Type: `object`

##### extensions

Type: `string[]`

Append extensions to the end of your globs.

##### files

Type: `string[]`

Only glob for certain files.

##### cwd

Type: `string[]`

Test in specific directory.


---

# dns-packet
[![](https://img.shields.io/npm/v/dns-packet.svg?style=flat)](https://www.npmjs.org/package/dns-packet) [![](https://img.shields.io/npm/dm/dns-packet.svg)](https://www.npmjs.org/package/dns-packet) [![](https://github.com/github/mafintosh/dns-packet/workflows/ci.yml/badge.svg)](https://github.com/github/mafintosh/dns-packet/workflows/ci.yml) [![Coverage Status](https://coveralls.io/repos/github/mafintosh/dns-packet/badge.svg?branch=master)](https://coveralls.io/github/mafintosh/dns-packet?branch=master)

An [abstract-encoding](https://github.com/mafintosh/abstract-encoding) compliant module for encoding / decoding DNS packets. Lifted out of [multicast-dns](https://github.com/mafintosh/multicast-dns) as a separate module.

```
npm install dns-packet
```

## UDP Usage

``` js
const dnsPacket = require('dns-packet')
const dgram = require('dgram')

const socket = dgram.createSocket('udp4')

const buf = dnsPacket.encode({
  type: 'query',
  id: 1,
  flags: dnsPacket.RECURSION_DESIRED,
  questions: [{
    type: 'A',
    name: 'google.com'
  }]
})

socket.on('message', message => {
  console.log(dnsPacket.decode(message)) // prints out a response from google dns
})

socket.send(buf, 0, buf.length, 53, '8.8.8.8')
```

Also see [the UDP example](examples/udp.js).

## TCP, TLS, HTTPS

While DNS has traditionally been used over a datagram transport, it is increasingly being carried over TCP for larger responses commonly including DNSSEC responses and TLS or HTTPS for enhanced security. See below examples on how to use `dns-packet` to wrap DNS packets in these protocols:

- [TCP](examples/tcp.js)
- [DNS over TLS](examples/tls.js)
- [DNS over HTTPS](examples/doh.js)

## API

#### `var buf = packets.encode(packet, [buf], [offset])`

Encodes a DNS packet into a buffer containing a UDP payload.

#### `var packet = packets.decode(buf, [offset])`

Decode a DNS packet from a buffer containing a UDP payload.

#### `var buf = packets.streamEncode(packet, [buf], [offset])`

Encodes a DNS packet into a buffer containing a TCP payload.

#### `var packet = packets.streamDecode(buf, [offset])`

Decode a DNS packet from a buffer containing a TCP payload.

#### `var len = packets.encodingLength(packet)`

Returns how many bytes are needed to encode the DNS packet

## Packets

Packets look like this

``` js
{
  type: 'query|response',
  id: optionalIdNumber,
  flags: optionalBitFlags,
  questions: [...],
  answers: [...],
  additionals: [...],
  authorities: [...]
}
```

The bit flags available are

``` js
packet.RECURSION_DESIRED
packet.RECURSION_AVAILABLE
packet.TRUNCATED_RESPONSE
packet.AUTHORITATIVE_ANSWER
packet.AUTHENTIC_DATA
packet.CHECKING_DISABLED
```

To use more than one flag bitwise-or them together

``` js
var flags = packet.RECURSION_DESIRED | packet.RECURSION_AVAILABLE
```

And to check for a flag use bitwise-and

``` js
var isRecursive = message.flags & packet.RECURSION_DESIRED
```

A question looks like this

``` js
{
  type: 'A', // or SRV, AAAA, etc
  class: 'IN', // one of IN, CS, CH, HS, ANY. Default: IN
  name: 'google.com' // which record are you looking for
}
```

And an answer, additional, or authority looks like this

``` js
{
  type: 'A', // or SRV, AAAA, etc
  class: 'IN', // one of IN, CS, CH, HS
  name: 'google.com', // which name is this record for
  ttl: optionalTimeToLiveInSeconds,
  (record specific data, see below)
}
```

## Supported record types

#### `A`

``` js
{
  data: 'IPv4 address' // fx 127.0.0.1
}
```

#### `AAAA`

``` js
{
  data: 'IPv6 address' // fx fe80::1
}
```

#### `CAA`

``` js
{
  flags: 128, // octet
  tag: 'issue|issuewild|iodef',
  value: 'ca.example.net',
  issuerCritical: false
}
```

#### `CNAME`

``` js
{
  data: 'cname.to.another.record'
}
```

#### `DNAME`

``` js
{
  data: 'dname.to.another.record'
}
```

#### `DNSKEY`

``` js
{
  flags: 257, // 16 bits
  algorithm: 1, // octet
  key: Buffer
}
```

#### `DS`

``` js
{
  keyTag: 12345,
  algorithm: 8,
  digestType: 1,
  digest: Buffer
}
```

#### `HINFO`

``` js
{
  data: {
    cpu: 'cpu info',
    os: 'os info'
  }
}
```

#### `MX`

``` js
{
  preference: 10,
  exchange: 'mail.example.net'
}
```

#### `NAPTR`

``` js
{
  data:
    {
      order: 100,
      preference: 10,
      flags: 's',
      services: 'SIP+D2U',
      regexp: '!^.*$!sip:customer-service@example.com!',
      replacement: '_sip._udp.example.com'
    }
}
```

#### `NS`

``` js
{
  data: nameServer
}
```

#### `NSEC`

``` js
{
  nextDomain: 'a.domain',
  rrtypes: ['A', 'TXT', 'RRSIG']
}
```

#### `NSEC3`

``` js
{
  algorithm: 1,
  flags: 0,
  iterations: 2,
  salt: Buffer,
  nextDomain: Buffer, // Hashed per RFC5155
  rrtypes: ['A', 'TXT', 'RRSIG']
}
```

#### `NULL`

``` js
{
  data: Buffer('any binary data')
}
```

#### `OPT`

[EDNS0](https://tools.ietf.org/html/rfc6891) options.

``` js
{
  type: 'OPT',
  name: '.',
  udpPayloadSize: 4096,
  flags: packet.DNSSEC_OK,
  options: [{
    // pass in any code/data for generic EDNS0 options
    code: 12,
    data: Buffer.alloc(31)
  }, {
    // Several EDNS0 options have enhanced support
    code: 'PADDING',
    length: 31,
  }, {
    code: 'CLIENT_SUBNET',
    family: 2, // 1 for IPv4, 2 for IPv6
    sourcePrefixLength: 64, // used to truncate IP address
    scopePrefixLength: 0,
    ip: 'fe80::',
  }, {
    code: 'TCP_KEEPALIVE',
    timeout: 150 // increments of 100ms.  This means 15s.
  }, {
    code: 'KEY_TAG',
    tags: [1, 2, 3],
  }]
}
```

The options `PADDING`, `CLIENT_SUBNET`, `TCP_KEEPALIVE` and `KEY_TAG` support enhanced de/encoding. See [optionscodes.js](https://github.com/mafintosh/dns-packet/blob/master/optioncodes.js) for all supported option codes. If the `data` property is present on a option, it takes precedence. On decoding, `data` will always be defined.

#### `PTR`

``` js
{
  data: 'points.to.another.record'
}
```

#### `RP`

``` js
{
  mbox: 'admin.example.com',
  txt: 'txt.example.com'
}
```

#### `SSHFP`

``` js
{
  algorithm: 1,
  hash: 1,
  fingerprint: 'A108C9F834354D5B37AF988141C9294822F5BC00'
}
````

#### `RRSIG`

``` js
{
  typeCovered: 'A',
  algorithm: 8,
  labels: 1,
  originalTTL: 3600,
  expiration: timestamp,
  inception: timestamp,
  keyTag: 12345,
  signersName: 'a.name',
  signature: Buffer
}
```

#### `SOA`

``` js
{
  data:
    {
      mname: domainName,
      rname: mailbox,
      serial: zoneSerial,
      refresh: refreshInterval,
      retry: retryInterval,
      expire: expireInterval,
      minimum: minimumTTL
    }
}
```

#### `SRV`

``` js
{
  data: {
    port: servicePort,
    target: serviceHostName,
    priority: optionalServicePriority,
    weight: optionalServiceWeight
  }
}
```

#### `TLSA`

``` js
{
  usage: 3,
  selector: 1,
  matchingType: 1,
  certificate: Buffer
}
```

#### `TXT`

``` js
{
  data: 'text' || Buffer || [ Buffer || 'text' ]
}
```

When encoding, scalar values are converted to an array and strings are converted to UTF-8 encoded Buffers. When decoding, the return value will always be an array of Buffer.

If you need another record type, open an issue and we'll try to add it.

## License

MIT


---

# `docusaurus-theme-search-typesense`

[Typesense](https://typesense.org) search component for Docusaurus powered documentation sites.

This is a fork of the awesome [@docusaurus/theme-search-algolia](https://www.npmjs.com/package/@docusaurus/theme-search-algolia) library customized to work with Typesense.

#### About Typesense

If you're new to Typesense, it is an **open source search engine** that is simple to use, run and scale, with clean APIs and documentation.

Think of it as an open source alternative to Algolia and an easier-to-use, batteries-included alternative to ElasticSearch. Get a quick overview from [this guide](https://typesense.org/guide/).

## Documentation

Read detailed step-by-step instructions on how to first setup the DocSearch scraper and then install this plugin here: [https://typesense.org/docs/guide/docsearch.html](https://typesense.org/docs/guide/docsearch.html).

## Help

If you have any questions or run into any problems, please create a Github issue and we'll try our best to help.


---

# @algolia/autocomplete-core

The [`autocomplete-core`](https://www.algolia.com/doc/ui-libraries/autocomplete/api-reference/autocomplete-core/createAutocomplete) package is the foundation of Autocomplete. It exposes primitives to build an autocomplete experience.

You likely don’t need to use this package directly unless you’re building a [renderer](https://www.algolia.com/doc/ui-libraries/autocomplete/guides/creating-a-renderer).

## Installation

```sh
yarn add @algolia/autocomplete-core
# or
npm install @algolia/autocomplete-core
```

## Documentation

See [**Documentation**](https://www.algolia.com/doc/ui-libraries/autocomplete/api-reference/autocomplete-core).


---

# @algolia/autocomplete-preset-algolia

The Algolia preset provides fetching and highlighting utilities for usage with Algolia.

## Installation

```sh
yarn add @algolia/autocomplete-preset-algolia
# or
npm install @algolia/autocomplete-preset-algolia
```

## Documentation

See [**Documentation**](https://www.algolia.com/doc/ui-libraries/autocomplete/api-reference/autocomplete-preset-algolia).


---

# clsx [![CI](https://github.com/lukeed/clsx/workflows/CI/badge.svg)](https://github.com/lukeed/clsx/actions?query=workflow%3ACI) [![codecov](https://badgen.net/codecov/c/github/lukeed/clsx)](https://codecov.io/gh/lukeed/clsx) [![licenses](https://licenses.dev/b/npm/clsx)](https://licenses.dev/npm/clsx)

> A tiny (239B) utility for constructing `className` strings conditionally.<Br>Also serves as a [faster](bench) & smaller drop-in replacement for the `classnames` module.

This module is available in three formats:

* **ES Module**: `dist/clsx.mjs`
* **CommonJS**: `dist/clsx.js`
* **UMD**: `dist/clsx.min.js`


## Install

```
$ npm install --save clsx
```


## Usage

```js
import clsx from 'clsx';
// or
import { clsx } from 'clsx';

// Strings (variadic)
clsx('foo', true && 'bar', 'baz');
//=> 'foo bar baz'

// Objects
clsx({ foo:true, bar:false, baz:isTrue() });
//=> 'foo baz'

// Objects (variadic)
clsx({ foo:true }, { bar:false }, null, { '--foobar':'hello' });
//=> 'foo --foobar'

// Arrays
clsx(['foo', 0, false, 'bar']);
//=> 'foo bar'

// Arrays (variadic)
clsx(['foo'], ['', 0, false, 'bar'], [['baz', [['hello'], 'there']]]);
//=> 'foo bar baz hello there'

// Kitchen sink (with nesting)
clsx('foo', [1 && 'bar', { baz:false, bat:null }, ['hello', ['world']]], 'cya');
//=> 'foo bar hello world cya'
```


## API

### clsx(...input)
Returns: `String`

#### input
Type: `Mixed`

The `clsx` function can take ***any*** number of arguments, each of which can be an Object, Array, Boolean, or String.

> **Important:** _Any_ falsey values are discarded!<br>Standalone Boolean values are discarded as well.

```js
clsx(true, false, '', null, undefined, 0, NaN);
//=> ''
```

## Modes

There are multiple "versions" of `clsx` available, which allows you to bring only the functionality you need!

#### `clsx`
> **Size (gzip):** 239 bytes<br>
> **Availability:** CommonJS, ES Module, UMD

The default `clsx` module; see [API](#API) for info.

```js
import { clsx } from 'clsx';
// or
import clsx from 'clsx';
```

#### `clsx/lite`
> **Size (gzip):** 140 bytes<br>
> **Availability:** CommonJS, ES Module<br>
> **CAUTION:** Accepts **ONLY** string arguments!

Ideal for applications that ***only*** use the string-builder pattern.

Any non-string arguments are ignored!

```js
import { clsx } from 'clsx/lite';
// or
import clsx from 'clsx/lite';

// string
clsx('hello', true && 'foo', false && 'bar');
// => "hello foo"

// NOTE: Any non-string input(s) ignored
clsx({ foo: true });
//=> ""
```

## Benchmarks

For snapshots of cross-browser results, check out the [`bench`](bench) directory~!

## Support

All versions of Node.js are supported.

All browsers that support [`Array.isArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/isArray#Browser_compatibility) are supported (IE9+).

>**Note:** For IE8 support and older, please install `clsx@1.0.x` and beware of [#17](https://github.com/lukeed/clsx/issues/17).

## Tailwind Support

Here some additional (optional) steps to enable classes autocompletion using `clsx` with Tailwind CSS.

<details>
<summary>
  Visual Studio Code
</summary>

1. [Install the "Tailwind CSS IntelliSense" Visual Studio Code extension](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss)

2. Add the following to your [`settings.json`](https://code.visualstudio.com/docs/getstarted/settings):

  ```json
   {
    "tailwindCSS.experimental.classRegex": [
      ["clsx\\(([^)]*)\\)", "(?:'|\"|`)([^']*)(?:'|\"|`)"]
    ]
   }
  ```
</details>

You may find the [`clsx/lite`](#clsxlite) module useful within Tailwind contexts. This is especially true if/when your application **only** composes classes in this pattern:

```js
clsx('text-base', props.active && 'text-primary', props.className);
```

## Related

- [obj-str](https://github.com/lukeed/obj-str) - A smaller (96B) and similiar utility that only works with Objects.

## License

MIT © [Luke Edwards](https://lukeed.com)


---

# Typesense Docsearch React

This is a fork of Algolia's awesome [React-DocSearch](https://github.com/algolia/docsearch) library, customized to send queries to [Typesense](https://typesense.org).

To be able to use this, you'd first need to setup and run the [Typesense DocSearch Scraper](https://github.com/typesense/typesense-docsearch-scraper).

#### What is Typesense?

If you're new to Typesense, it is an **open source** search engine that is simple to use, run and scale, with clean APIs and documentation.

Think of it as an open source alternative to Algolia and an easier-to-use, batteries-included alternative to ElasticSearch. Get a quick overview from [this guide](https://typesense.org/guide/).

## Usage

```sh
yarn add typesense-docsearch-react
# or
npm install typesense-docsearch-react
```

## Documentation

Read detailed step-by-step instructions on how to configure and setup this version of DocSearch on Typesense's dedicated documentation site: https://typesense.org/docs/latest/guide/docsearch.html.

## Help

If you have any questions or run into any problems, please create a Github issue and we'll try our best to help.


---

# Typesense Instantsearch Adapter

An adapter to use the awesome [Instantsearch.js](https://github.com/algolia/instantsearch.js) library with a [Typesense](https://typesense.org) Search Server, to build rich search interfaces.

[![NPM version][npm-image]][npm-url]
![downloads](https://img.shields.io/npm/dt/typesense-instantsearch-adapter?label=downloads)

Here is an example of UI you can build with this adapater: [songs-search.typesense.org](https://songs-search.typesense.org)

**Note:** If your search interface is built on a custom autocomplete component, or is based on [@algolia/autocomplete-js](https://www.algolia.com/doc/ui-libraries/autocomplete/introduction/what-is-autocomplete/), then you don't need this adapter to use it with Typesense, as [typesense-js](https://github.com/typesense/typesense-js) library already supports client-side fetching data from any async data sources. Read more [here](https://github.com/typesense/typesense-instantsearch-adapter/issues/88#issuecomment-1021597634).

## Quick Links

- [Background](#background)
- [Quick Start](#quick-start)
  - [Starter App](#starter-app)
- [Installation](#installation)
- [Usage](#usage)
  - [With instantsearch.js](#with-instantsearchjs)
  - [With react-instantsearch](#with-react-instantsearch) (also works with React Native)
  - [With vue-instantsearch](#with-vue-instantsearch)
  - [With angular-instantsearch](#with-angular-instantsearch)
- [Widget Specific Instructions](#widget-specific-instructions)
- [Compatibility](#compatibility)
- [Development](#development)
- [Help](#help)

## Background

The good folks over at Algolia have built and open-sourced [Instantsearch.js](https://github.com/algolia/instantsearch.js) which is a collection of out-of-the-box components that you can use to build interactive search experiences swiftly.

With the adapter in this repository, you'll be able to use [Instantsearch](https://github.com/algolia/instantsearch.js) (and its [React](https://github.com/algolia/react-instantsearch), [Vue](https://github.com/algolia/vue-instantsearch) and [Angular](https://github.com/algolia/angular-instantsearch) cousins) with data indexed in a Typesense search server.

If you haven't used Instantsearch before, we recommend going through their Getting Started guide [here](https://www.algolia.com/doc/guides/building-search-ui/getting-started/js/#build-a-simple-ui).
Once you go through the guide, follow the instructions below to plug the Typesense adapter into Instantsearch.

## Quick Start

Here's a guide on building a quick search interface with Typesense and InstantSearch.js: [https://typesense.org/docs/0.20.0/guide/search-ui-components.html](https://typesense.org/docs/0.20.0/guide/search-ui-components.html)

### Starter App

Here's a demo starter app that shows you how to use the adapter: [https://github.com/typesense/typesense-instantsearch-demo](https://github.com/typesense/typesense-instantsearch-demo)

## Installation

```shell
$ npm install --save typesense-instantsearch-adapter @babel/runtime
```

or

```shell
$ yarn add typesense-instantsearch-adapter @babel/runtime
```

or, you can also directly include the adapter via a script tag in your HTML:

```html
<script src="https://cdn.jsdelivr.net/npm/typesense-instantsearch-adapter@2/dist/typesense-instantsearch-adapter.min.js"></script>

<!-- You might want to pin the version of the adapter used if you don't want to always receive the latest minor version -->
```

Since this is an adapter, it **will not install** the Instantsearch library automatically for you. You need to install one of the following in your application directly:

- [instantsearch.js](https://github.com/algolia/instantsearch.js)
- [react-instantsearch](https://github.com/algolia/react-instantsearch)
- [vue-instantsearch](https://github.com/algolia/vue-instantsearch)
- [angular-instantsearch](https://github.com/algolia/angular-instantsearch)

You'll find information on how to get started with each of the above libraries in their respective repos.

We'd also recommend checking out [create-instantsearch-app](https://github.com/algolia/create-instantsearch-app) to create your Search UI from a starter template.

## Usage

### With [instantsearch.js](https://github.com/algolia/instantsearch.js)

```javascript
import instantsearch from "instantsearch.js";
import { searchBox, hits } from "instantsearch.js/es/widgets";
import TypesenseInstantSearchAdapter from "typesense-instantsearch-adapter";

const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "abcd", // Be sure to use an API key that only allows search operations
    nodes: [
      {
        host: "localhost",
        path: "", // Optional. Example: If you have your typesense mounted in localhost:8108/typesense, path should be equal to '/typesense'
        port: "8108",
        protocol: "http",
      },
    ],
    cacheSearchResultsForSeconds: 2 * 60, // Cache search results from server. Defaults to 2 minutes. Set to 0 to disable caching.
  },
  // The following parameters are directly passed to Typesense's search API endpoint.
  //  So you can pass any parameters supported by the search endpoint below.
  //  query_by is required.
  additionalSearchParameters: {
    query_by: "name,description,categories",
  },
});
const searchClient = typesenseInstantsearchAdapter.searchClient;

const search = instantsearch({
  searchClient,
  indexName: "products",
});
search.addWidgets([
  searchBox({
    container: "#searchbox",
  }),
  hits({
    container: "#hits",
    templates: {
      item: `
        <div class="hit-name">
          {{#helpers.highlight}}{ "attribute": "name" }{{/helpers.highlight}}
        </div>
      `,
    },
  }),
]);

search.start();
```

You can add any of the Instantsearch widgets [here](https://www.algolia.com/doc/guides/building-search-ui/widgets/showcase/js/) that are [supported](#widget-compatibility) by the adapter.

You'll also find a working example in [test/support/testground](test/support/testground). To run it, run `npm run testground` from the project root folder.

### With [react-instantsearch](https://github.com/algolia/react-instantsearch)

```jsx harmony
import React from "react";
import ReactDOM from "react-dom";
import { SearchBox } from "react-instantsearch-dom";
import TypesenseInstantSearchAdapter from "typesense-instantsearch-adapter";

const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "abcd", // Be sure to use an API key that only allows search operations
    nodes: [
      {
        host: "localhost",
        port: "8108",
        path: "", // Optional. Example: If you have your typesense mounted in localhost:8108/typesense, path should be equal to '/typesense'
        protocol: "http",
      },
    ],
    cacheSearchResultsForSeconds: 2 * 60, // Cache search results from server. Defaults to 2 minutes. Set to 0 to disable caching.
  },
  // The following parameters are directly passed to Typesense's search API endpoint.
  //  So you can pass any parameters supported by the search endpoint below.
  //  query_by is required.
  additionalSearchParameters: {
    query_by: "name,description,categories",
  },
});
const searchClient = typesenseInstantsearchAdapter.searchClient;

const App = () => (
  <InstantSearch indexName="products" searchClient={searchClient}>
    <SearchBox />
    <Hits />
  </InstantSearch>
);
```

You can then add any of the Instantsearch-React widgets [here](https://www.algolia.com/doc/guides/building-search-ui/widgets/showcase/react/) that are [supported](#widget-compatibility) by the adapter.

The instructions above also apply to React Native.

### With [vue-instantsearch](https://github.com/algolia/vue-instantsearch)

App.vue:

```vue
<template>
  <ais-instant-search :search-client="searchClient" index-name="products">
    <ais-search-box />
    <ais-hits>
      <div slot="item" slot-scope="{ item }">
        <h2>{{ item.name }}</h2>
      </div>
    </ais-hits>
  </ais-instant-search>
</template>

<script>
import TypesenseInstantSearchAdapter from "typesense-instantsearch-adapter";

const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "abcd", // Be sure to use an API key that only allows search operations
    nodes: [
      {
        host: "localhost",
        path: "", // Optional. Example: If you have your typesense mounted in localhost:8108/typesense, path should be equal to '/typesense'
        port: "8108",
        protocol: "http",
      },
    ],
    cacheSearchResultsForSeconds: 2 * 60, // Cache search results from server. Defaults to 2 minutes. Set to 0 to disable caching.
  },
  // The following parameters are directly passed to Typesense's search API endpoint.
  //  So you can pass any parameters supported by the search endpoint below.
  //  query_by is required.
  additionalSearchParameters: {
    query_by: "name,description,categories",
  },
});
const searchClient = typesenseInstantsearchAdapter.searchClient;

export default {
  data() {
    return {
      searchClient,
    };
  },
};
</script>
```

You can then add any of the Instantsearch widgets [here](https://www.algolia.com/doc/guides/building-search-ui/widgets/showcase/vue/) that are [supported](#widget-compatibility) by the adapter.

### With [angular-instantsearch](https://github.com/algolia/angular-instantsearch)

```javascript
// app.component.ts
import { Component } from "@angular/core";
import TypesenseInstantSearchAdapter from "typesense-instantsearch-adapter";

const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "abcd", // Be sure to use an API key that only allows search operations
    nodes: [
      {
        host: "localhost",
        path: "", // Optional. Example: If you have your typesense mounted in localhost:8108/typesense, path should be equal to '/typesense'
        port: "8108",
        protocol: "http",
      },
    ],
    cacheSearchResultsForSeconds: 2 * 60, // Cache search results from server. Defaults to 2 minutes. Set to 0 to disable caching.
  },
  // The following parameters are directly passed to Typesense's search API endpoint.
  //  So you can pass any parameters supported by the search endpoint below.
  //  query_by is required.
  additionalSearchParameters: {
    query_by: "name,description,categories",
  },
});
const searchClient = typesenseInstantsearchAdapter.searchClient;

@Component({
  selector: "app-root",
  templateUrl: "./app.component.html",
  styleUrls: ["./app.component.css"],
})
export class AppComponent {
  config = {
    indexName: "products",
    searchClient,
  };
}
```

You can then add any of the Instantsearch widgets [here](https://www.algolia.com/doc/guides/building-search-ui/widgets/showcase/angular/) that are [supported](#widget-compatibility) by the adapter.

## Widget Specific Instructions

### `hierarchicalMenu`

For this widget, you want to create independent fields in the collection's schema with this specific naming convention:

- `field.lvl0`
- `field.lvl1`
- `field.lvl2`

for a nested hierarchy of `field.lvl0 > field.lvl1 > field.lvl2`

Each of these fields can also hold an array of values. This is useful for handling multiple hierarchies.

### `sortBy`

When instantiating this widget, you want to set the value of the index name to this particular format:

```javascript
search.addWidgets([
  sortBy({
    container: "#sort-by",
    items: [
      { label: "Default", value: "products" },
      { label: "Price (asc)", value: "products/sort/price:asc" },
      { label: "Price (desc)", value: "products/sort/price:desc" },
    ],
  }),
]);
```

The generalized pattern for the value attribute is: `<index_name>[/sort/<sort_by>]`. The adapter will use the value in `<sort_by>` as the value for the `sort_by` search parameter.

### `configure`

If you need to specify a `filter_by` search parameter for Typesense, you want to use the `configure` InstantSearch widget, along with `facetFilters`, `numericFilters` or `filters`.

The format for `facetFilters` and `numericFilters` is the same as Algolia's as described [here](https://www.algolia.com/doc/api-reference/api-parameters/facetFilters/).
But `filters` needs to be in Typesense's `filter_by` format as described in this table [here](https://typesense.org/docs/latest/api/documents.html#query-parameters).

Setting `filter_by` inside the `additionalQueryParameters` config only works when the widgets are loaded initially, because InstantSearch internally overrides the `filter_by` field subsequently.
Read more [here](https://github.com/typesense/typesense-instantsearch-adapter/issues/17#issuecomment-746912375).

### `index`

For Federated / Multi-Index Search, you'd need to use the `index` widget. To then be able to specify different search parameters for each index/collection, you can specify them using the `collectionSpecificSearchParameters` configuration:

```js
const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "abcd", // Be sure to use an API key that only allows search operations
    nodes: [{ host: "localhost", path: "/", port: "8108", protocol: "http" }],
  },
  // Search parameters that are common to all collections/indices go here:
  additionalSearchParameters: {
    numTypos: 3,
  },
  // Search parameters that need to be *overridden* on a per-collection-basis go here:
  collectionSpecificSearchParameters: {
    products: {
      query_by: "name,description,categories",
    },
    brands: {
      query_by: "name",
    },
  },
});
const searchClient = typesenseInstantsearchAdapter.searchClient;
```

Essentially, any parameters set in `collectionSpecificSearchParameters` will be merged with the values in `additionalSearchParameters` when querying Typesense, effectively overriding values in `additionalSearchParameters` on a per-collection-basis.

### `geoSearch`

Algolia uses `_geoloc` by default for the name of the field that stores the lat long values for a record.
In Typesense, you can name the geo location field anything. If you use a name other than `_geoloc`, you need to specify it when initializing the adapter like below, so InstantSearch can access it:

```js
const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "xyz",
    nodes: [
      {
        host: "localhost",
        port: "8108",
        path: "/",
        protocol: "http",
      },
    ],
  },
  geoLocationField: "lat_lng_field", // <<======
  additionalSearchParameters,
});
```

### `dynamicWidgets`

> Available as of Typesense Server `v0.25.0.rc12`

This [`dynamicWidgets`](https://www.algolia.com/doc/api-reference/widgets/dynamic-facets/js/) widget works out of the box with no additional changes,
but if you want to control the order in which these facets are displayed in the UI
Instantsearch expects a parameter called [`renderingContent`](https://www.algolia.com/doc/api-reference/api-parameters/renderingContent/) to be set.

```js
const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "xyz",
    nodes: [
      {
        host: "localhost",
        port: "8108",
        path: "/",
        protocol: "http",
      },
    ],
  },
  renderingContent: {
    // <<===== Add this, only if you want to control the order of the widgets displayed by dynamicWidgets
    facetOrdering: {
      facets: {
        order: ["size", "brand"], // <<===== Change this as needed
      },
    },
  },
  additionalSearchParameters,
});
```

Read more about all available options for `renderingContent` in [Algolia's documentation here](https://www.algolia.com/doc/api-reference/api-parameters/renderingContent/?client=javascript#examples).

### Special characters in field names / values

> Available as of typesense-instantsearch-adapter `2.7.0-2`

- If any string fields in your documents have a colon `:` in their values (for eg, let's say there's a field called `{ brand: "a:b" }`, then you would need to add a parameter like below when instantiating the adapter:

  ```js
  const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
    server: {
      apiKey: "xyz",
      nodes: [
        {
          host: "localhost",
          port: "8108",
          path: "/",
          protocol: "http",
        },
      ],
    },
    facetableFieldsWithSpecialCharacters: ["brand"], // <======= Add string fields that have colons in their values here, to aid in parsing
    additionalSearchParameters,
  });
  ```

- If any numeric field _names_ in your documents have special characters like `>`, `<`, `=` (for eg, let's say there's a field called `{ price>discount: 3.0 }`) then you would need to add a parameter like below when instantiating the adapter:

  ```js
  const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
    server: {
      apiKey: "xyz",
      nodes: [
        {
          host: "localhost",
          port: "8108",
          path: "/",
          protocol: "http",
        },
      ],
    },
    facetableFieldsWithSpecialCharacters: ["price>discount"], // // <======= Add numeric fields that have >, < or = in their names, to aid in parsing
    additionalSearchParameters,
  });
  ```

### Setting `facet_by` options

> Available as of typesense-instantsearch-adapter `2.8.0-1` and Typesense Server `v0.26.0.rc25`

The `facet_by` parameter is managed by InstantSearch internally when you use the various filter widgets.

But if you need to pass custom options to the `facet_by` parameter (eg: server-side sort options), then you can use the `facetByOptions` parameter as shown below:

```js
const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "xyz",
    nodes: [
      {
        host: "localhost",
        port: "8108",
        path: "/",
        protocol: "http",
      },
    ],
  },
  facetByOptions: {
    brand: "(sort_by: _alpha:asc)",
    category: "(sort_by: _alpha:desc)",
  }, // <======= Add any facet_by parameter as a key value pair. Don't forget the surrounding parantheses in the value.
  collectionSpecificFacetByOptions: {
    collection1: {
      brand: "(sort_by: _alpha:desc)",
    },
  }, // <======= Use this parameter if multiple collections share the same field names, and you want to use different options for each field. This will override facetByOptions for that particular collection.
  additionalSearchParameters,
});
```

Note that for sorting in refinementLists, in addition to sorting on the Typesense Server-side, you'd also need to pass the [`sortBy`](https://www.algolia.com/doc/api-reference/widgets/refinement-list/js/#widget-param-sortby) parameter to the refinementList widget to also sort the results appropriately on the client-side.

### Setting `filter_by` options

> Available as of typesense-instantsearch-adapter `2.8.0-5`

The `filter_by` parameter is managed by InstantSearch internally when you use the various filter widgets.

By default, the adapter uses exact filtering (`filter_by: field:=value`) when sending the queries to Typesense.
If you need to configure the adapter to use `:` (non-exact word-level filtering - `filter_by: field:value`), you want to instantiate the adapter using the `filterByOptions` configuration:

```js
const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "xyz",
    nodes: [
      {
        host: "localhost",
        port: "8108",
        path: "/",
        protocol: "http",
      },
    ],
  },
  filterByOptions: {
    brand: { exactMatch: false }, // <========== Add this to do non-exact word-level filtering
    category: { exactMatch: false },
  },
  collectionSpecificFacetByOptions: {
    collection1: {
      brand: { exactMatch: false },
    },
  }, // <======= Use this parameter if multiple collections share the same field names, and you want to use different options for each field. This will override filterByOptions for that particular collection.
  additionalSearchParameters,
});
```

### Grouped Hits

> Available as of typesense-instantsearch-adapter `2.7.1-4`

By default, when `group_by` is used as a search parameters, the adapter flattens the results across all groups into a single list of sequential hits.

If you'd like to preserve the groups, you want to set `flattenGroupedHits: false` when instantiating the adapter.

This will place the first hit in a group as the primary hit, and then add all hits in the group inside a `_grouped_hits` key inside each hit.

```js
const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "xyz",
    nodes: [
      {
        host: "localhost",
        port: "8108",
        path: "/",
        protocol: "http",
      },
    ],
  },
  flattenGroupedHits: false, // <=======
  additionalSearchParameters,
});
```

### Vector Search

> Available as of typesense-instantsearch-adapter `2.7.0-3`

The general idea is to first hook into the query life-cycle of Instantsearch, intercept the typed query and send it to an embedding API, fetch the embeddings and then send the vectors to Typesense to do a nearest neighbor vector search.

Here's a demo that you can run locally to see this in action: [https://github.com/typesense/typesense-instantsearch-semantic-search-demo](https://github.com/typesense/typesense-instantsearch-semantic-search-demo).

Here's how to do this in Instantsearch.js:

```javascript
const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "xyz",
    nodes: [
      {
        host: "localhost",
        port: "8108",
        path: "/",
        protocol: "http",
      },
    ],
  },
  additionalSearchParameters,
});
const searchClient = typesenseInstantsearchAdapter.searchClient;
const search = instantsearch({
  searchClient,
  indexName: "products",
  routing: true,
  async searchFunction(helper) {
    const query = helper.getQuery().query;
    const page = helper.getPage(); // Retrieve the current page
    const totalNearestNeighborsToFetch = 1000;

    if (query !== "") {
      // Get embedding for the query
      let response = await fetch(
        "http://localhost:8000/embedding?" + new URLSearchParams({ q: query }) // <=== Embedding API
      );

      let parsedResponse = await response.json();

      console.log(parsedResponse);

      // Send the embedding to Typesense to do a nearest neighbor search
      helper
        .setQueryParameter(
          "typesenseVectorQuery", // <=== Special parameter that only works in typesense-instantsearch-adapter@2.7.0-3 and above
          `vectors:([${parsedResponse["embedding"].join(",")}], k:${totalNearestNeighborsToFetch})`
        )
        .setPage(page)
        .search();
    } else {
      helper.setQueryParameter("typesenseVectorQuery", null).setPage(page).search();
    }
  },
});
```

## Compatibility

| Typesense Server | typesense-instantsearch-adapter | instantsearch.js | react-instantsearch | vue-instantsearch | angular-instantsearch |
| ---------------- | ------------------------------- | ---------------- | ------------------- | ----------------- | --------------------- |
| \>= v0.25.0      | \>= v2.7.1                      | \>= 4.51         | \>= 6.39            | \>= 4.8           | \>= 4.4               |
| \>= v0.25.0.rc14 | \>= v2.7.0-1                    | \>= 4.51         | \>= 6.39            | \>= 4.8           | \>= 4.4               |
| \>= v0.25.0.rc12 | \>= v2.6.0                      | \>= 4.51         | \>= 6.39            | \>= 4.8           | \>= 4.4               |
| \>= v0.24        | \>= v2.5.0                      | \>= 4.2.0        | \>= 6.0.0           | \>= 2.2.1         | \>= 3.0.0             |
| \>= v0.21        | \>= v2.0.0                      | \>= 4.2.0        | \>= 6.0.0           | \>= 2.2.1         | \>= 3.0.0             |
| \>= v0.19        | \>= v1.0.0                      | \>= 4.2.0        | \>= 6.0.0           | \>= 2.2.1         | \>= 3.0.0             |
| \>= v0.15        | \>= v0.3.0                      | \>= 4.2.0        | \>= 6.0.0           | \>= 2.2.1         | \>= 3.0.0             |
| \>= v0.14        | \>= v0.2.0                      | \>= 4.2.0        | \>= 6.0.0           | \>= 2.2.1         | \>= 3.0.0             |
| \>= v0.13        | \>= v0.1.0                      | \>= 4.2.0        | \>= 6.0.0           | \>= 2.2.1         | \>= 3.0.0             |
| \>= v0.12        | \>= v0.0.4                      | \>= 4.2.0        | \>= 6.0.0           | \>= 2.2.1         | \>= 3.0.0             |

If a particular version of the above libraries don't work with the adapter, please open a Github issue with details.

### Widget Compatibility

This adapter works with all widgets in [this list](https://www.algolia.com/doc/api-reference/widgets/js/), _except_ for the following:

- `queryRuleCustomData`
- `queryRuleContext`

## Development

```shell
$ npm install
$ npm run typesenseServer
$ FORCE_REINDEX=true npm run indexTestData

$ npm link typesense-instantsearch-adapter
$ npm run testground

$ npm test
```

To release a new version, we use the [np](https://github.com/sindresorhus/np) package:

```shell
$ npm install --global np
$ np

# Follow instructions that np shows you

```

## Help

If you have any questions or run into any problems, please create a Github issue and we'll try our best to help.

© 2020-present Typesense, Inc.

[npm-image]: https://badge.fury.io/js/typesense-instantsearch-adapter.svg
[npm-url]: https://npmjs.org/package/typesense-instantsearch-adapter


---

Converts bare objects to DOM objects, compatible with htmlparser2's DOM objects.

This is useful when you want to work with DOM without having to compose/parse html.

---

# dom-serializer [![Build Status](https://travis-ci.com/cheeriojs/dom-serializer.svg?branch=master)](https://travis-ci.com/cheeriojs/dom-serializer)

Renders a [domhandler](https://github.com/fb55/domhandler) DOM node or an array of domhandler DOM nodes to a string.

```js
import render from "dom-serializer";

// OR

const render = require("dom-serializer").default;
```

# API

## `render`

▸ **render**(`node`: Node \| Node[], `options?`: [_Options_](#Options)): _string_

Renders a DOM node or an array of DOM nodes to a string.

Can be thought of as the equivalent of the `outerHTML` of the passed node(s).

#### Parameters:

| Name      | Type                               | Default value | Description                    |
| :-------- | :--------------------------------- | :------------ | :----------------------------- |
| `node`    | Node \| Node[]                     | -             | Node to be rendered.           |
| `options` | [_DomSerializerOptions_](#Options) | {}            | Changes serialization behavior |

**Returns:** _string_

## Options

### `encodeEntities`

• `Optional` **decodeEntities**: _boolean | "utf8"_

Encode characters that are either reserved in HTML or XML.

If `xmlMode` is `true` or the value not `'utf8'`, characters outside of the utf8 range will be encoded as well.

**`default`** `decodeEntities`

---

### `decodeEntities`

• `Optional` **decodeEntities**: _boolean_

Option inherited from parsing; will be used as the default value for `encodeEntities`.

**`default`** true

---

### `emptyAttrs`

• `Optional` **emptyAttrs**: _boolean_

Print an empty attribute's value.

**`default`** xmlMode

**`example`** With <code>emptyAttrs: false</code>: <code>&lt;input checked&gt;</code>

**`example`** With <code>emptyAttrs: true</code>: <code>&lt;input checked=""&gt;</code>

---

### `selfClosingTags`

• `Optional` **selfClosingTags**: _boolean_

Print self-closing tags for tags without contents.

**`default`** xmlMode

**`example`** With <code>selfClosingTags: false</code>: <code>&lt;foo&gt;&lt;/foo&gt;</code>

**`example`** With <code>selfClosingTags: true</code>: <code>&lt;foo /&gt;</code>

---

### `xmlMode`

• `Optional` **xmlMode**: _boolean_ \| _"foreign"_

Treat the input as an XML document; enables the `emptyAttrs` and `selfClosingTags` options.

If the value is `"foreign"`, it will try to correct mixed-case attribute names.

**`default`** false

---

## Ecosystem

| Name                                                          | Description                                             |
| ------------------------------------------------------------- | ------------------------------------------------------- |
| [htmlparser2](https://github.com/fb55/htmlparser2)            | Fast & forgiving HTML/XML parser                        |
| [domhandler](https://github.com/fb55/domhandler)              | Handler for htmlparser2 that turns documents into a DOM |
| [domutils](https://github.com/fb55/domutils)                  | Utilities for working with domhandler's DOM             |
| [css-select](https://github.com/fb55/css-select)              | CSS selector engine, compatible with domhandler's DOM   |
| [cheerio](https://github.com/cheeriojs/cheerio)               | The jQuery API for domhandler's DOM                     |
| [dom-serializer](https://github.com/cheeriojs/dom-serializer) | Serializer for domhandler's DOM                         |

---

LICENSE: MIT


---

All the types of nodes in htmlparser2's DOM.


---

# domhandler [![Build Status](https://travis-ci.com/fb55/domhandler.svg?branch=master)](https://travis-ci.com/fb55/domhandler)

The DOM handler creates a tree containing all nodes of a page.
The tree can be manipulated using the [domutils](https://github.com/fb55/domutils)
or [cheerio](https://github.com/cheeriojs/cheerio) libraries and
rendered using [dom-serializer](https://github.com/cheeriojs/dom-serializer) .

## Usage

```javascript
const handler = new DomHandler([ <func> callback(err, dom), ] [ <obj> options ]);
// const parser = new Parser(handler[, options]);
```

Available options are described below.

## Example

```javascript
const { Parser } = require("htmlparser2");
const { DomHandler } = require("domhandler");
const rawHtml =
    "Xyz <script language= javascript>var foo = '<<bar>>';</script><!--<!-- Waah! -- -->";
const handler = new DomHandler((error, dom) => {
    if (error) {
        // Handle error
    } else {
        // Parsing completed, do something
        console.log(dom);
    }
});
const parser = new Parser(handler);
parser.write(rawHtml);
parser.end();
```

Output:

```javascript
[
    {
        data: "Xyz ",
        type: "text",
    },
    {
        type: "script",
        name: "script",
        attribs: {
            language: "javascript",
        },
        children: [
            {
                data: "var foo = '<bar>';<",
                type: "text",
            },
        ],
    },
    {
        data: "<!-- Waah! -- ",
        type: "comment",
    },
];
```

## Option: `withStartIndices`

Add a `startIndex` property to nodes.
When the parser is used in a non-streaming fashion, `startIndex` is an integer
indicating the position of the start of the node in the document.
The default value is `false`.

## Option: `withEndIndices`

Add an `endIndex` property to nodes.
When the parser is used in a non-streaming fashion, `endIndex` is an integer
indicating the position of the end of the node in the document.
The default value is `false`.

---

License: BSD-2-Clause

## Security contact information

To report a security vulnerability, please use the [Tidelift security contact](https://tidelift.com/security).
Tidelift will coordinate the fix and disclosure.

## `domhandler` for enterprise

Available as part of the Tidelift Subscription

The maintainers of `domhandler` and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-domhandler?utm_source=npm-domhandler&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)


---

# domutils [![Node.js CI](https://github.com/fb55/domutils/actions/workflows/nodejs-test.yml/badge.svg)](https://github.com/fb55/domutils/actions/workflows/nodejs-test.yml)

Utilities for working with [htmlparser2](https://github.com/fb55/htmlparser2)'s DOM.

All functions are exported as a single module. Look [through the docs](https://domutils.js.org/modules.html) to see what is available.

## Ecosystem

| Name                                                          | Description                                             |
| ------------------------------------------------------------- | ------------------------------------------------------- |
| [htmlparser2](https://github.com/fb55/htmlparser2)            | Fast & forgiving HTML/XML parser                        |
| [domhandler](https://github.com/fb55/domhandler)              | Handler for htmlparser2 that turns documents into a DOM |
| [domutils](https://github.com/fb55/domutils)                  | Utilities for working with domhandler's DOM             |
| [css-select](https://github.com/fb55/css-select)              | CSS selector engine, compatible with domhandler's DOM   |
| [cheerio](https://github.com/cheeriojs/cheerio)               | The jQuery API for domhandler's DOM                     |
| [dom-serializer](https://github.com/cheeriojs/dom-serializer) | Serializer for domhandler's DOM                         |

---

License: BSD-2-Clause

## Security contact information

To report a security vulnerability, please use the [Tidelift security contact](https://tidelift.com/security).
Tidelift will coordinate the fix and disclosure.

## `domutils` for enterprise

Available as part of the Tidelift Subscription

The maintainers of `domutils` and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-domutils?utm_source=npm-domutils&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)


---

# Dot Case

[![NPM version][npm-image]][npm-url]
[![NPM downloads][downloads-image]][downloads-url]
[![Bundle size][bundlephobia-image]][bundlephobia-url]

> Transform into a lower case string with a period between words.

## Installation

```
npm install dot-case --save
```

## Usage

```js
import { dotCase } from "dot-case";

dotCase("string"); //=> "string"
dotCase("dot.case"); //=> "dot.case"
dotCase("PascalCase"); //=> "pascal.case"
dotCase("version 1.2.10"); //=> "version.1.2.10"
```

The function also accepts [`options`](https://github.com/blakeembrey/change-case#options).

## License

MIT

[npm-image]: https://img.shields.io/npm/v/dot-case.svg?style=flat
[npm-url]: https://npmjs.org/package/dot-case
[downloads-image]: https://img.shields.io/npm/dm/dot-case.svg?style=flat
[downloads-url]: https://npmjs.org/package/dot-case
[bundlephobia-image]: https://img.shields.io/bundlephobia/minzip/dot-case.svg
[bundlephobia-url]: https://bundlephobia.com/result?p=dot-case


---

# is-obj [![Build Status](https://travis-ci.org/sindresorhus/is-obj.svg?branch=master)](https://travis-ci.org/sindresorhus/is-obj)

> Check if a value is an object

Keep in mind that array, function, regexp, etc, are objects in JavaScript.<br>
See [`is-plain-obj`](https://github.com/sindresorhus/is-plain-obj) if you want to check for plain objects.


## Install

```
$ npm install is-obj
```


## Usage

```js
const isObject = require('is-obj');

isObject({foo: 'bar'});
//=> true

isObject([1, 2, 3]);
//=> true

isObject('foo');
//=> false
```


## Related

- [is](https://github.com/sindresorhus/is) - Type check values


## License

MIT © [Sindre Sorhus](https://sindresorhus.com)


---

# dot-prop [![Build Status](https://travis-ci.com/sindresorhus/dot-prop.svg?branch=master)](https://travis-ci.com/github/sindresorhus/dot-prop)

> Get, set, or delete a property from a nested object using a dot path

## Install

```
$ npm install dot-prop
```

## Usage

```js
const dotProp = require('dot-prop');

// Getter
dotProp.get({foo: {bar: 'unicorn'}}, 'foo.bar');
//=> 'unicorn'

dotProp.get({foo: {bar: 'a'}}, 'foo.notDefined.deep');
//=> undefined

dotProp.get({foo: {bar: 'a'}}, 'foo.notDefined.deep', 'default value');
//=> 'default value'

dotProp.get({foo: {'dot.dot': 'unicorn'}}, 'foo.dot\\.dot');
//=> 'unicorn'

// Setter
const object = {foo: {bar: 'a'}};
dotProp.set(object, 'foo.bar', 'b');
console.log(object);
//=> {foo: {bar: 'b'}}

const foo = dotProp.set({}, 'foo.bar', 'c');
console.log(foo);
//=> {foo: {bar: 'c'}}

dotProp.set(object, 'foo.baz', 'x');
console.log(object);
//=> {foo: {bar: 'b', baz: 'x'}}

// Has
dotProp.has({foo: {bar: 'unicorn'}}, 'foo.bar');
//=> true

// Deleter
const object = {foo: {bar: 'a'}};
dotProp.delete(object, 'foo.bar');
console.log(object);
//=> {foo: {}}

object.foo.bar = {x: 'y', y: 'x'};
dotProp.delete(object, 'foo.bar.x');
console.log(object);
//=> {foo: {bar: {y: 'x'}}}
```

## API

### get(object, path, defaultValue?)

Get the value of the property at the given path.

Returns the value if any.

### set(object, path, value)

Set the property at the given path to the given value.

Returns the object.

### has(object, path)

Check whether the property at the given path exists.

Returns a boolean.

### delete(object, path)

Delete the property at the given path.

Returns a boolean of whether the property existed before being deleted.

#### object

Type: `object`

Object to get, set, or delete the `path` value.

You are allowed to pass in `undefined` as the object to the `get` and `has` functions.

#### path

Type: `string`

Path of the property in the object, using `.` to separate each nested key.

Use `\\.` if you have a `.` in the key.

The following path components are invalid and results in `undefined` being returned: `__proto__`, `prototype`, `constructor`.

#### value

Type: `unknown`

Value to set at `path`.

#### defaultValue

Type: `unknown`

Default value.

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-dot-prop?utm_source=npm-dot-prop&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [v1.0.1](https://github.com/es-shims/dunder-proto/compare/v1.0.0...v1.0.1) - 2024-12-16

### Commits

- [Fix] do not crash when `--disable-proto=throw` [`6c367d9`](https://github.com/es-shims/dunder-proto/commit/6c367d919bc1604778689a297bbdbfea65752847)
- [Tests] ensure noproto tests only use the current version of dunder-proto [`b02365b`](https://github.com/es-shims/dunder-proto/commit/b02365b9cf889c4a2cac7be0c3cfc90a789af36c)
- [Dev Deps] update `@arethetypeswrong/cli`, `@types/tape` [`e3c5c3b`](https://github.com/es-shims/dunder-proto/commit/e3c5c3bd81cf8cef7dff2eca19e558f0e307f666)
- [Deps] update `call-bind-apply-helpers` [`19f1da0`](https://github.com/es-shims/dunder-proto/commit/19f1da028b8dd0d05c85bfd8f7eed2819b686450)

## v1.0.0 - 2024-12-06

### Commits

- Initial implementation, tests, readme, types [`a5b74b0`](https://github.com/es-shims/dunder-proto/commit/a5b74b0082f5270cb0905cd9a2e533cee7498373)
- Initial commit [`73fb5a3`](https://github.com/es-shims/dunder-proto/commit/73fb5a353b51ac2ab00c9fdeb0114daffd4c07a8)
- npm init [`80152dc`](https://github.com/es-shims/dunder-proto/commit/80152dc98155da4eb046d9f67a87ed96e8280a1d)
- Only apps should have lockfiles [`03e6660`](https://github.com/es-shims/dunder-proto/commit/03e6660a1d70dc401f3e217a031475ec537243dd)


---

# dunder-proto <sup>[![Version Badge][npm-version-svg]][package-url]</sup>

[![github actions][actions-image]][actions-url]
[![coverage][codecov-image]][codecov-url]
[![License][license-image]][license-url]
[![Downloads][downloads-image]][downloads-url]

[![npm badge][npm-badge-png]][package-url]

If available, the `Object.prototype.__proto__` accessor and mutator, call-bound.

## Getting started

```sh
npm install --save dunder-proto
```

## Usage/Examples

```js
const assert = require('assert');
const getDunder = require('dunder-proto/get');
const setDunder = require('dunder-proto/set');

const obj = {};

assert.equal('toString' in obj, true);
assert.equal(getDunder(obj), Object.prototype);

setDunder(obj, null);

assert.equal('toString' in obj, false);
assert.equal(getDunder(obj), null);
```

## Tests

Clone the repo, `npm install`, and run `npm test`

[package-url]: https://npmjs.org/package/dunder-proto
[npm-version-svg]: https://versionbadg.es/es-shims/dunder-proto.svg
[deps-svg]: https://david-dm.org/es-shims/dunder-proto.svg
[deps-url]: https://david-dm.org/es-shims/dunder-proto
[dev-deps-svg]: https://david-dm.org/es-shims/dunder-proto/dev-status.svg
[dev-deps-url]: https://david-dm.org/es-shims/dunder-proto#info=devDependencies
[npm-badge-png]: https://nodei.co/npm/dunder-proto.png?downloads=true&stars=true
[license-image]: https://img.shields.io/npm/l/dunder-proto.svg
[license-url]: LICENSE
[downloads-image]: https://img.shields.io/npm/dm/dunder-proto.svg
[downloads-url]: https://npm-stat.com/charts.html?package=dunder-proto
[codecov-image]: https://codecov.io/gh/es-shims/dunder-proto/branch/main/graphs/badge.svg
[codecov-url]: https://app.codecov.io/gh/es-shims/dunder-proto/
[actions-image]: https://img.shields.io/endpoint?url=https://github-actions-badge-u3jn4tfpocch.runkit.sh/es-shims/dunder-proto
[actions-url]: https://github.com/es-shims/dunder-proto/actions


---

# duplexer

[![build status][1]][2] [![dependency status][3]][4]

[![browser support][5]][6]

Creates a duplex stream

Taken from [event-stream][7]

## duplex (writeStream, readStream)

Takes a writable stream and a readable stream and makes them appear as a readable writable stream.

It is assumed that the two streams are connected to each other in some way.

## Example

```js
var cp = require('child_process')
  , duplex = require('duplexer')
  , grep = cp.exec('grep Stream')

duplex(grep.stdin, grep.stdout)
```

## Installation

`npm install duplexer`

## Tests

`npm test`

## Contributors

 - Dominictarr
 - Raynos
 - samccone

## MIT Licenced

  [1]: https://secure.travis-ci.org/Raynos/duplexer.png
  [2]: https://travis-ci.org/Raynos/duplexer
  [3]: https://david-dm.org/Raynos/duplexer.png
  [4]: https://david-dm.org/Raynos/duplexer
  [5]: https://ci.testling.com/Raynos/duplexer.png
  [6]: https://ci.testling.com/Raynos/duplexer
  [7]: https://github.com/dominictarr/event-stream#duplex-writestream-readstream


---

# East Asian Width

Get [East Asian Width](http://www.unicode.org/reports/tr11/) from a character.

'F'(Fullwidth), 'H'(Halfwidth), 'W'(Wide), 'Na'(Narrow), 'A'(Ambiguous) or 'N'(Natural).

Original Code is [東アジアの文字幅 (East Asian Width) の判定 - 中途](http://d.hatena.ne.jp/takenspc/20111126#1322252878).

## Install

    $ npm install eastasianwidth

## Usage

    var eaw = require('eastasianwidth');
    console.log(eaw.eastAsianWidth('￦')) // 'F'
    console.log(eaw.eastAsianWidth('｡')) // 'H'
    console.log(eaw.eastAsianWidth('뀀')) // 'W'
    console.log(eaw.eastAsianWidth('a')) // 'Na'
    console.log(eaw.eastAsianWidth('①')) // 'A'
    console.log(eaw.eastAsianWidth('ف')) // 'N'

    console.log(eaw.characterLength('￦')) // 2
    console.log(eaw.characterLength('｡')) // 1
    console.log(eaw.characterLength('뀀')) // 2
    console.log(eaw.characterLength('a')) // 1
    console.log(eaw.characterLength('①')) // 2
    console.log(eaw.characterLength('ف')) // 1

    console.log(eaw.length('あいうえお')) // 10
    console.log(eaw.length('abcdefg')) // 7
    console.log(eaw.length('￠￦｡ￜㄅ뀀¢⟭a⊙①بف')) // 19


---

# EE First

[![NPM version][npm-image]][npm-url]
[![Build status][travis-image]][travis-url]
[![Test coverage][coveralls-image]][coveralls-url]
[![License][license-image]][license-url]
[![Downloads][downloads-image]][downloads-url]
[![Gittip][gittip-image]][gittip-url]

Get the first event in a set of event emitters and event pairs,
then clean up after itself.

## Install

```sh
$ npm install ee-first
```

## API

```js
var first = require('ee-first')
```

### first(arr, listener)

Invoke `listener` on the first event from the list specified in `arr`. `arr` is
an array of arrays, with each array in the format `[ee, ...event]`. `listener`
will be called only once, the first time any of the given events are emitted. If
`error` is one of the listened events, then if that fires first, the `listener`
will be given the `err` argument.

The `listener` is invoked as `listener(err, ee, event, args)`, where `err` is the
first argument emitted from an `error` event, if applicable; `ee` is the event
emitter that fired; `event` is the string event name that fired; and `args` is an
array of the arguments that were emitted on the event.

```js
var ee1 = new EventEmitter()
var ee2 = new EventEmitter()

first([
  [ee1, 'close', 'end', 'error'],
  [ee2, 'error']
], function (err, ee, event, args) {
  // listener invoked
})
```

#### .cancel()

The group of listeners can be cancelled before being invoked and have all the event
listeners removed from the underlying event emitters.

```js
var thunk = first([
  [ee1, 'close', 'end', 'error'],
  [ee2, 'error']
], function (err, ee, event, args) {
  // listener invoked
})

// cancel and clean up
thunk.cancel()
```

[npm-image]: https://img.shields.io/npm/v/ee-first.svg?style=flat-square
[npm-url]: https://npmjs.org/package/ee-first
[github-tag]: http://img.shields.io/github/tag/jonathanong/ee-first.svg?style=flat-square
[github-url]: https://github.com/jonathanong/ee-first/tags
[travis-image]: https://img.shields.io/travis/jonathanong/ee-first.svg?style=flat-square
[travis-url]: https://travis-ci.org/jonathanong/ee-first
[coveralls-image]: https://img.shields.io/coveralls/jonathanong/ee-first.svg?style=flat-square
[coveralls-url]: https://coveralls.io/r/jonathanong/ee-first?branch=master
[license-image]: http://img.shields.io/npm/l/ee-first.svg?style=flat-square
[license-url]: LICENSE.md
[downloads-image]: http://img.shields.io/npm/dm/ee-first.svg?style=flat-square
[downloads-url]: https://npmjs.org/package/ee-first
[gittip-image]: https://img.shields.io/gittip/jonathanong.svg?style=flat-square
[gittip-url]: https://www.gittip.com/jonathanong/


---

### Made by [@kilianvalkhof](https://twitter.com/kilianvalkhof)

#### Other projects:

- 💻 [Polypane](https://polypane.app) - Develop responsive websites and apps twice as fast on multiple screens at once
- 🖌️ [Superposition](https://superposition.design) - Kickstart your design system by extracting design tokens from your website
- 🗒️ [FromScratch](https://fromscratch.rocks) - A smart but simple autosaving scratchpad

---

# Electron-to-Chromium [![npm](https://img.shields.io/npm/v/electron-to-chromium.svg)](https://www.npmjs.com/package/electron-to-chromium) [![travis](https://img.shields.io/travis/Kilian/electron-to-chromium/master.svg)](https://travis-ci.org/Kilian/electron-to-chromium) [![npm-downloads](https://img.shields.io/npm/dm/electron-to-chromium.svg)](https://www.npmjs.com/package/electron-to-chromium) [![codecov](https://codecov.io/gh/Kilian/electron-to-chromium/branch/master/graph/badge.svg)](https://codecov.io/gh/Kilian/electron-to-chromium)[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2FKilian%2Felectron-to-chromium.svg?type=shield)](https://app.fossa.io/projects/git%2Bgithub.com%2FKilian%2Felectron-to-chromium?ref=badge_shield)

This repository provides a mapping of Electron versions to the Chromium version that it uses.

This package is used in [Browserslist](https://github.com/ai/browserslist), so you can use e.g. `electron >= 1.4` in [Autoprefixer](https://github.com/postcss/autoprefixer), [Stylelint](https://github.com/stylelint/stylelint), [babel-preset-env](https://github.com/babel/babel-preset-env) and [eslint-plugin-compat](https://github.com/amilajack/eslint-plugin-compat).

**Supported by:**

  <a href="https://m.do.co/c/bb22ea58e765">
    <img src="https://opensource.nyc3.cdn.digitaloceanspaces.com/attribution/assets/SVG/DO_Logo_horizontal_blue.svg" width="201px">
  </a>


## Install
Install using `npm install electron-to-chromium`.

## Usage
To include Electron-to-Chromium, require it:

```js
var e2c = require('electron-to-chromium');
```

### Properties
The Electron-to-Chromium object has 4 properties to use:

#### `versions`
An object of key-value pairs with a _major_ Electron version as the key, and the corresponding major Chromium version as the value.

```js
var versions = e2c.versions;
console.log(versions['1.4']);
// returns "53"
```

#### `fullVersions`
An object of key-value pairs with a Electron version as the key, and the corresponding full Chromium version as the value.

```js
var versions = e2c.fullVersions;
console.log(versions['1.4.11']);
// returns "53.0.2785.143"
```

#### `chromiumVersions`
An object of key-value pairs with a _major_ Chromium version as the key, and the corresponding major Electron version as the value.

```js
var versions = e2c.chromiumVersions;
console.log(versions['54']);
// returns "1.4"
```

#### `fullChromiumVersions`
An object of key-value pairs with a Chromium version as the key, and an array of the corresponding major Electron versions as the value.

```js
var versions = e2c.fullChromiumVersions;
console.log(versions['54.0.2840.101']);
// returns ["1.5.1", "1.5.0"]
```
### Functions

#### `electronToChromium(query)`
Arguments:
* Query: string or number, required. A major or full Electron version.

A function that returns the corresponding Chromium version for a given Electron function. Returns a string.

If you provide it with a major Electron version, it will return a major Chromium version:

```js
var chromeVersion = e2c.electronToChromium('1.4');
// chromeVersion is "53"
```

If you provide it with a full Electron version, it will return the full Chromium version.

```js
var chromeVersion = e2c.electronToChromium('1.4.11');
// chromeVersion is "53.0.2785.143"
```

If a query does not match a Chromium version, it will return `undefined`.

```js
var chromeVersion = e2c.electronToChromium('9000');
// chromeVersion is undefined
```

#### `chromiumToElectron(query)`
Arguments:
* Query: string or number, required. A major or full Chromium version.

Returns a string with the corresponding Electron version for a given Chromium query.

If you provide it with a major Chromium version, it will return a major Electron version:

```js
var electronVersion = e2c.chromiumToElectron('54');
// electronVersion is "1.4"
```

If you provide it with a full Chrome version, it will return an array of full Electron versions.

```js
var electronVersions = e2c.chromiumToElectron('56.0.2924.87');
// electronVersions is ["1.6.3", "1.6.2", "1.6.1", "1.6.0"]
```

If a query does not match an Electron version, it will return `undefined`.

```js
var electronVersion = e2c.chromiumToElectron('10');
// electronVersion is undefined
```

#### `electronToBrowserList(query)` **DEPRECATED**
Arguments:
* Query: string or number, required. A major Electron version.

_**Deprecated**: Browserlist already includes electron-to-chromium._

A function that returns a [Browserslist](https://github.com/ai/browserslist) query that matches the given major Electron version. Returns a string.

If you provide it with a major Electron version, it will return a Browserlist query string that matches the Chromium capabilities:

```js
var query = e2c.electronToBrowserList('1.4');
// query is "Chrome >= 53"
```

If a query does not match a Chromium version, it will return `undefined`.

```js
var query = e2c.electronToBrowserList('9000');
// query is undefined
```

### Importing just versions, fullVersions, chromiumVersions and fullChromiumVersions
All lists can be imported on their own, if file size is a concern.

#### `versions`

```js
var versions = require('electron-to-chromium/versions');
```

#### `fullVersions`

```js
var fullVersions = require('electron-to-chromium/full-versions');
```

#### `chromiumVersions`

```js
var chromiumVersions = require('electron-to-chromium/chromium-versions');
```

#### `fullChromiumVersions`

```js
var fullChromiumVersions = require('electron-to-chromium/full-chromium-versions');
```

## Updating
This package will be updated with each new Electron release.

To update the list, run `npm run build.js`. Requires internet access as it downloads from the canonical list of Electron versions.

To verify correct behaviour, run `npm test`.


## License
[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2FKilian%2Felectron-to-chromium.svg?type=large)](https://app.fossa.io/projects/git%2Bgithub.com%2FKilian%2Felectron-to-chromium?ref=badge_large)


---

# emoji-regex [![Build status](https://travis-ci.org/mathiasbynens/emoji-regex.svg?branch=main)](https://travis-ci.org/mathiasbynens/emoji-regex)

_emoji-regex_ offers a regular expression to match all emoji symbols and sequences (including textual representations of emoji) as per the Unicode Standard.

This repository contains a script that generates this regular expression based on [Unicode data](https://github.com/node-unicode/node-unicode-data). Because of this, the regular expression can easily be updated whenever new emoji are added to the Unicode standard.

## Installation

Via [npm](https://www.npmjs.com/):

```bash
npm install emoji-regex
```

In [Node.js](https://nodejs.org/):

```js
const emojiRegex = require('emoji-regex/RGI_Emoji.js');
// Note: because the regular expression has the global flag set, this module
// exports a function that returns the regex rather than exporting the regular
// expression itself, to make it impossible to (accidentally) mutate the
// original regular expression.

const text = `
\u{231A}: ⌚ default emoji presentation character (Emoji_Presentation)
\u{2194}\u{FE0F}: ↔️ default text presentation character rendered as emoji
\u{1F469}: 👩 emoji modifier base (Emoji_Modifier_Base)
\u{1F469}\u{1F3FF}: 👩🏿 emoji modifier base followed by a modifier
`;

const regex = emojiRegex();
let match;
while (match = regex.exec(text)) {
  const emoji = match[0];
  console.log(`Matched sequence ${ emoji } — code points: ${ [...emoji].length }`);
}
```

Console output:

```
Matched sequence ⌚ — code points: 1
Matched sequence ⌚ — code points: 1
Matched sequence ↔️ — code points: 2
Matched sequence ↔️ — code points: 2
Matched sequence 👩 — code points: 1
Matched sequence 👩 — code points: 1
Matched sequence 👩🏿 — code points: 2
Matched sequence 👩🏿 — code points: 2
```

## Regular expression flavors

The package comes with three distinct regular expressions:

```js
// This is the recommended regular expression to use. It matches all
// emoji recommended for general interchange, as defined via the
// `RGI_Emoji` property in the Unicode Standard.
// https://unicode.org/reports/tr51/#def_rgi_set
// When in doubt, use this!
const emojiRegexRGI = require('emoji-regex/RGI_Emoji.js');

// This is the old regular expression, prior to `RGI_Emoji` being
// standardized. In addition to all `RGI_Emoji` sequences, it matches
// some emoji you probably don’t want to match (such as emoji component
// symbols that are not meant to be used separately).
const emojiRegex = require('emoji-regex/index.js');

// This regular expression matches even more emoji than the previous
// one, including emoji that render as text instead of icons (i.e.
// emoji that are not `Emoji_Presentation` symbols and that aren’t
// forced to render as emoji by a variation selector).
const emojiRegexText = require('emoji-regex/text.js');
```

Additionally, in environments which support ES2015 Unicode escapes, you may `require` ES2015-style versions of the regexes:

```js
const emojiRegexRGI = require('emoji-regex/es2015/RGI_Emoji.js');
const emojiRegex = require('emoji-regex/es2015/index.js');
const emojiRegexText = require('emoji-regex/es2015/text.js');
```

## For maintainers

### How to update emoji-regex after new Unicode Standard releases

1. Update the Unicode data dependency in `package.json` by running the following commands:

    ```sh
    # Example: updating from Unicode v12 to Unicode v13.
    npm uninstall @unicode/unicode-12.0.0
    npm install @unicode/unicode-13.0.0 --save-dev
    ````

1. Generate the new output:

    ```sh
    npm run build
    ```

1. Verify that tests still pass:

    ```sh
    npm test
    ```

1. Send a pull request with the changes, and get it reviewed & merged.

1. On the `main` branch, bump the emoji-regex version number in `package.json`:

    ```sh
    npm version patch -m 'Release v%s'
    ```

    Instead of `patch`, use `minor` or `major` [as needed](https://semver.org/).

    Note that this produces a Git commit + tag.

1. Push the release commit and tag:

    ```sh
    git push
    ```

    Our CI then automatically publishes the new release to npm.

## Author

| [![twitter/mathias](https://gravatar.com/avatar/24e08a9ea84deb17ae121074d0f17125?s=70)](https://twitter.com/mathias "Follow @mathias on Twitter") |
|---|
| [Mathias Bynens](https://mathiasbynens.be/) |

## License

_emoji-regex_ is available under the [MIT](https://mths.be/mit) license.


---

# :book: emojilib [![Travis CI build status](https://img.shields.io/travis/muan/emojilib.svg?style=flat-square)](https://travis-ci.org/muan/emojilib) [![NPM](https://img.shields.io/npm/dt/emojilib.svg?style=flat-square&colorB=fd7463)](https://www.npmjs.com/package/emojilib) [![JavaScript Standard Style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat-square&colorB=f1d04a)](https://github.com/feross/standard)

Emoji keyword library.

## Install

### :package: NPM<br>![](https://img.shields.io/npm/v/emojilib.svg?style=flat-square)

```
npm install emojilib --save
```

## Usage

```javascript
> var emoji = require("emojilib")
> emoji.lib
{
  "grinning": {
    "keywords": ["face", "smile", "happy", "joy"],
    "char": "😀",
    "fitzpatrick_scale": false,
    "category": "people"
  },
  "grin": {
    "keywords": ["face", "happy", "smile", "joy"],
    "char": "😁",
    "fitzpatrick_scale": false,
    "category": "people"
  },
  ...
}

> emoji.ordered
[ 'grinning', 'grimacing', 'grin', 'joy', 'smiley', 'smile', 'sweat_smile', ...]

> emoji.fitzpatrick_scale_modifiers
[ '🏻', '🏼', '🏽', '🏾', '🏿' ]

> emoji.lib.v.fitzpatrick_scale
true

> emoji.lib.turtle.fitzpatrick_scale
false

> emoji.lib.v.char + emoji.fitzpatrick_scale_modifiers[4]
'✌🏿'
```

## :electric_plug: Powered by emojilib

* [Emoji Searcher](http://emoji.muan.co) – [muan/emoji](https://github.com/muan/emoji)
* [Megamoji](http://megamoji.muan.co) – [muan/megamoji](https://github.com/muan/megamoji)
* [Emoji-translate](http://meowni.ca/emoji-translate) - [notwaldorf/emoji-translate](https://github.com/notwaldorf/emoji-translate)
* [\<emo-ji\> Custom Element](https://github.com/wbinnssmith/emo-ji)
* [Menubar emoji search: Mojibar](https://github.com/muan/mojibar) – [muan/mojibar](https://github.com/muan/mojibar)
* [Emoji CLI](https://github.com/muan/emoji-cli) – [muan/emoji-cli](https://github.com/muan/emoji-cli)
* [Emoji Lookup for Launchbar](https://github.com/jasonrudolph/launchbar-emoji-lookup) – [jasonrudolph/launchbar-emoji-lookup](https://github.com/jasonrudolph/launchbar-emoji-lookup)
* [commemoji](https://www.npmjs.com/package/commemoji) - [martellaj/commemoji](https://github.com/martellaj/commemoji)
* [Emoji Stream](https://www.npmjs.com/package/emoji-stream) – [johnelliott/emoji-stream](https://github.com/johnelliott/emoji-stream)
* [EmojiPanel for Twitter](http://bit.ly/emojipanel) - [danbovey/EmojiPanel](https://github.com/danbovey/EmojiPanel)
* [mojibrag](https://mojibrag.firebaseapp.com/) - [notwaldorf/mojibrag](https://github.com/notwaldorf/mojibrag)
* [Emoji Alfred Workflow](https://www.npmjs.com/package/emoji-alfred-workflow) - [janclarin/emoji-alfred-workflow](https://github.com/janclarin/emoji-alfred-workflow)
* [(Another) Alfred Workflow for Emoji](https://www.alfredforum.com/topic/11126-alfred-emoji-search-emojis-by-name-or-keyword/) - [jsumners/alfred-emoji](https://github.com/jsumners/alfred-emoji)
* [Emojipasta Generator](http://erikyangs.com/emojipastagenerator/) - [erikyangs/emojipastagenerator](https://github.com/erikyangs/emojipastagenerator)


---

<a name="3.0.0"></a>
# 3.0.0 (2019-05-12)

* build: bye bower ([4acc7c0](https://github.com/kikobeats/emojis-list/commit/4acc7c0))
* build: remove gulp and bower ([12c83f3](https://github.com/kikobeats/emojis-list/commit/12c83f3))
* build: update meta ([de14b12](https://github.com/kikobeats/emojis-list/commit/de14b12))
* moar emojis ([b4a153f](https://github.com/kikobeats/emojis-list/commit/b4a153f))
* chore: drop support for Node.js 0.10 ([20ed4f1](https://github.com/kikobeats/emojis-list/commit/20ed4f1))


### BREAKING CHANGE

* This module no longer supports Node.js 0.10


<a name="2.1.0"></a>
# 2.1.0 (2016-10-03)

* Fetch new emoji ([7dbe84d](https://github.com/kikobeats/emojis-list/commit/7dbe84d))



<a name="2.0.1"></a>
## 2.0.1 (2016-05-12)

* Fix typo ([3808909](https://github.com/kikobeats/emojis-list/commit/3808909))



<a name="2.0.0"></a>
# 2.0.0 (2016-05-12)

* Add update script ([f846dd6](https://github.com/kikobeats/emojis-list/commit/f846dd6))
* Block dependencies in last version ([1d9e0a5](https://github.com/kikobeats/emojis-list/commit/1d9e0a5))
* Extract main file name ([9ffe7bb](https://github.com/kikobeats/emojis-list/commit/9ffe7bb))
* Remove unnecessary files ([4c34729](https://github.com/kikobeats/emojis-list/commit/4c34729))
* Update docs, special webpack setup is not necessary ([c4aefe9](https://github.com/kikobeats/emojis-list/commit/c4aefe9))
* Update example ([1e2ae03](https://github.com/kikobeats/emojis-list/commit/1e2ae03))
* Update how to generate emojis array ([b56bad9](https://github.com/kikobeats/emojis-list/commit/b56bad9))
* Update main file based in the new interface ([996fccb](https://github.com/kikobeats/emojis-list/commit/996fccb))



<a name="1.0.3"></a>
## 1.0.3 (2016-05-12)

* Add standard as linter ([5e939d6](https://github.com/kikobeats/emojis-list/commit/5e939d6))
* Change interface ([16bc0c0](https://github.com/kikobeats/emojis-list/commit/16bc0c0))
* Generate emoji file ([fbcf8e9](https://github.com/kikobeats/emojis-list/commit/fbcf8e9))
* Remove unnecessary special doc ([2b12bec](https://github.com/kikobeats/emojis-list/commit/2b12bec))
* chore(package): update browserify to version 13.0.1 ([e2c98bf](https://github.com/kikobeats/emojis-list/commit/e2c98bf))
* chore(package): update gulp-header to version 1.8.1 ([28de793](https://github.com/kikobeats/emojis-list/commit/28de793))



<a name="1.0.2"></a>
## 1.0.2 (2016-05-05)

* fixed #2 ([9a6abe7](https://github.com/kikobeats/emojis-list/commit/9a6abe7)), closes [#2](https://github.com/kikobeats/emojis-list/issues/2)
* Fomar using standard ([5202f9f](https://github.com/kikobeats/emojis-list/commit/5202f9f))
* Update badge ([53fad9b](https://github.com/kikobeats/emojis-list/commit/53fad9b))



<a name="1.0.1"></a>
## 1.0.1 (2016-04-13)

* lock versions ([4a5d82e](https://github.com/kikobeats/emojis-list/commit/4a5d82e))
* setup devDependencies ([d1de0fc](https://github.com/kikobeats/emojis-list/commit/d1de0fc))
* update bumped ([9941038](https://github.com/kikobeats/emojis-list/commit/9941038))
* Update package.json ([6c14b74](https://github.com/kikobeats/emojis-list/commit/6c14b74))
* Update README.md ([1d9beeb](https://github.com/kikobeats/emojis-list/commit/1d9beeb))
* Update README.md ([73f215e](https://github.com/kikobeats/emojis-list/commit/73f215e))
* Update tests ([a94f7dc](https://github.com/kikobeats/emojis-list/commit/a94f7dc))



<a name="1.0.0"></a>
# 1.0.0 (2015-05-12)

* first commit ([a65b79d](https://github.com/kikobeats/emojis-list/commit/a65b79d))
* updated ([9f0564c](https://github.com/kikobeats/emojis-list/commit/9f0564c))





---

The MIT License (MIT)

Copyright © 2015 Kiko Beats

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


---

# emojis-list

[![Dependency status](http://img.shields.io/david/Kikobeats/emojis-list.svg?style=flat-square)](https://david-dm.org/Kikobeats/emojis-list)
[![Dev Dependencies Status](http://img.shields.io/david/dev/Kikobeats/emojis-list.svg?style=flat-square)](https://david-dm.org/Kikobeats/emojis-list#info=devDependencies)
[![NPM Status](http://img.shields.io/npm/dm/emojis-list.svg?style=flat-square)](https://www.npmjs.org/package/emojis-list)
[![Donate](https://img.shields.io/badge/donate-paypal-blue.svg?style=flat-square)](https://paypal.me/kikobeats)

> Complete list of standard Unicode Hex Character Code that represent emojis.

**NOTE**: The lists is related with the Unicode Hex Character Code. The representation of the emoji depend of the system. Will be possible that the system don't have all the representations.

## Install

```bash
npm install emojis-list --save
```

## Usage

```js
const emojis = require('emojis-list')
console.log(emojis[0])
// => 🀄
```

## Related

* [emojis-unicode](https://github.com/Kikobeats/emojis-unicode) – Complete list of standard Unicode codes that represent emojis.
* [emojis-keywords](https://github.com/Kikobeats/emojis-keywords) – Complete list of am emoji shortcuts.
* [is-emoji-keyword](https://github.com/Kikobeats/is-emoji-keyword) – Check if a word is a emoji shortcut.
* [is-standard-emoji](https://github.com/kikobeats/is-standard-emoji) – Simply way to check if a emoji is a standard emoji.
* [trim-emoji](https://github.com/Kikobeats/trim-emoji) – Deletes ':' from the begin and the end of an emoji shortcut.

## License

MIT © [Kiko Beats](http://www.kikobeats.com)


---

# emoticon

[![Build][badge-build-image]][badge-build-url]
[![Coverage][badge-coverage-image]][badge-coverage-url]
[![Downloads][badge-downloads-image]][badge-downloads-url]
[![Size][badge-size-image]][badge-size-url]

List of emoticons.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`emoticon`](#emoticon-1)
* [List of emoticons](#list-of-emoticons)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Related](#related)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package contains info on ASCII emoticons.
:p

## When should I use this?

You can use this package for several reasons, typically in a build script,
for example to figure out which text emoticons map to what emoji.

## Install

This package is [ESM only][github-gist-esm].
In Node.js (version 14.14+), install with [npm][npm-install]:

```sh
npm install emoticon
```

In Deno with [`esm.sh`][esm-sh]:

```js
import {emoticon} from 'https://esm.sh/emoticon@4'
```

In browsers with [`esm.sh`][esm-sh]:

```html
<script type="module">
  import {emoticon} from 'https://esm.sh/emoticon@4?bundle'
</script>
```

## Use

```js
import {emoticon} from 'emoticon'

console.log(emoticon.slice(0, 3))
```

Yields:

```js
[
  {
    description: 'angry face',
    emoji: '😠',
    emoticons: [
      '>:(',  '>:[',
      '>:-(', '>:-[',
      '>=(',  '>=[',
      '>=-(', '>=-['
    ],
    name: 'angry',
    tags: [ 'mad', 'annoyed' ]
  },
  {
    description: 'smiling face with smiling eyes',
    emoji: '😊',
    emoticons: [
      ':")',  ':"]',  ':"D',
      ':-")', ':-"]', ':-"D',
      '=")',  '="]',  '="D',
      '=-")', '=-"]', '=-"D'
    ],
    name: 'blush',
    tags: [ 'proud' ]
  },
  {
    description: 'broken heart',
    emoji: '💔',
    emoticons: [ '<\\3', '</3' ],
    name: 'broken_heart',
    tags: []
  }
]
```

## API

This package exports the identifier `emoticon`.
There is no default export.

### `emoticon`

List of emoticons (`Array<Emoticon>`), where each entry has the following
fields:

* `description` (`string`)
  — associated description (from [`wooorm/gemoji`][github-gemoji])
* `emoji` (`string`)
  — corresponding emoji
* `emoticons` (`Array<string>`)
  — ASCII emoticons
* `name` (`string`)
  — name of an emoticon (preferred name from [`wooorm/gemoji`][github-gemoji])
* `tags` (`Array<string>`)
  — associated tags (from [`wooorm/gemoji`][github-gemoji])

## List of emoticons

See [`support.md`][file-support].

## Types

This package is fully typed with [TypeScript][].
It exports an additional type `Emoticon`.

## Compatibility

This package is at least compatible with all maintained versions of Node.js.
As of now, that is Node.js 14.14+.
It also works in Deno and modern browsers.

## Security

This package is safe.

## Related

* [`wooorm/gemoji`][github-gemoji]
  — info on gemoji (GitHub emoji)
* [`words/emoji-emotion`](https://github.com/words/emoji-emotion)
  — list of emoji rated for valence
* [`wooorm/emoticon`](https://github.com/wooorm/emoticon)
  — info on ASCII emoticons
* [`wooorm/strip-skin-tone`](https://github.com/wooorm/strip-skin-tone)
  — strip skin-tones from emoji
* [`wooorm.com/checkmoji`](https://wooorm.com/checkmoji/)
  — check emoji across platforms

## Contribute

Yes please!
See [How to Contribute to Open Source][open-source-guide-contribute].

## License

[MIT][file-license] © [Titus Wormer][wooorm]

<!-- Definitions -->

[badge-build-image]: https://github.com/wooorm/emoticon/workflows/main/badge.svg

[badge-build-url]: https://github.com/wooorm/emoticon/actions

[badge-coverage-image]: https://img.shields.io/codecov/c/github/wooorm/emoticon.svg

[badge-coverage-url]: https://codecov.io/github/wooorm/emoticon

[badge-downloads-image]: https://img.shields.io/npm/dm/emoticon.svg

[badge-downloads-url]: https://www.npmjs.com/package/emoticon

[badge-size-image]: https://img.shields.io/bundlejs/size/emoticon

[badge-size-url]: https://bundlejs.com/?q=emoticon

[esm-sh]: https://esm.sh

[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[file-license]: license

[file-support]: support.md

[npm-install]: https://docs.npmjs.com/cli/install

[typescript]: https://www.typescriptlang.org

[wooorm]: https://wooorm.com

[github-gemoji]: https://github.com/wooorm/gemoji

[open-source-guide-contribute]: https://opensource.guide/how-to-contribute/


---

# Encode URL

Encode a URL to a percent-encoded form, excluding already-encoded sequences.

## Installation

```sh
npm install encodeurl
```

## API

```js
var encodeUrl = require('encodeurl')
```

### encodeUrl(url)

Encode a URL to a percent-encoded form, excluding already-encoded sequences.

This function accepts a URL and encodes all the non-URL code points (as UTF-8 byte sequences). It will not encode the "%" character unless it is not part of a valid sequence (`%20` will be left as-is, but `%foo` will be encoded as `%25foo`).

This encode is meant to be "safe" and does not throw errors. It will try as hard as it can to properly encode the given URL, including replacing any raw, unpaired surrogate pairs with the Unicode replacement character prior to encoding.

## Examples

### Encode a URL containing user-controlled data

```js
var encodeUrl = require('encodeurl')
var escapeHtml = require('escape-html')

http.createServer(function onRequest (req, res) {
  // get encoded form of inbound url
  var url = encodeUrl(req.url)

  // create html message
  var body = '<p>Location ' + escapeHtml(url) + ' not found</p>'

  // send a 404
  res.statusCode = 404
  res.setHeader('Content-Type', 'text/html; charset=UTF-8')
  res.setHeader('Content-Length', String(Buffer.byteLength(body, 'utf-8')))
  res.end(body, 'utf-8')
})
```

### Encode a URL for use in a header field

```js
var encodeUrl = require('encodeurl')
var escapeHtml = require('escape-html')
var url = require('url')

http.createServer(function onRequest (req, res) {
  // parse inbound url
  var href = url.parse(req)

  // set new host for redirect
  href.host = 'localhost'
  href.protocol = 'https:'
  href.slashes = true

  // create location header
  var location = encodeUrl(url.format(href))

  // create html message
  var body = '<p>Redirecting to new site: ' + escapeHtml(location) + '</p>'

  // send a 301
  res.statusCode = 301
  res.setHeader('Content-Type', 'text/html; charset=UTF-8')
  res.setHeader('Content-Length', String(Buffer.byteLength(body, 'utf-8')))
  res.setHeader('Location', location)
  res.end(body, 'utf-8')
})
```

## Similarities

This function is _similar_ to the intrinsic function `encodeURI`. However, it will not encode:

* The `\`, `^`, or `|` characters
* The `%` character when it's part of a valid sequence
* `[` and `]` (for IPv6 hostnames)
* Replaces raw, unpaired surrogate pairs with the Unicode replacement character

As a result, the encoding aligns closely with the behavior in the [WHATWG URL specification][whatwg-url]. However, this package only encodes strings and does not do any URL parsing or formatting.

It is expected that any output from `new URL(url)` will not change when used with this package, as the output has already been encoded. Additionally, if we were to encode before `new URL(url)`, we do not expect the before and after encoded formats to be parsed any differently.

## Testing

```sh
$ npm test
$ npm run lint
```

## References

- [RFC 3986: Uniform Resource Identifier (URI): Generic Syntax][rfc-3986]
- [WHATWG URL Living Standard][whatwg-url]

[rfc-3986]: https://tools.ietf.org/html/rfc3986
[whatwg-url]: https://url.spec.whatwg.org/

## License

[MIT](LICENSE)


---

# enhanced-resolve

[![npm][npm]][npm-url]
[![Build Status][build-status]][build-status-url]
[![codecov][codecov-badge]][codecov-url]
[![Install Size][size]][size-url]
[![GitHub Discussions][discussion]][discussion-url]

Offers an async require.resolve function. It's highly configurable.

## Features

- plugin system
- provide a custom filesystem
- sync and async node.js filesystems included

## Getting Started

### Install

```sh
# npm
npm install enhanced-resolve
# or Yarn
yarn add enhanced-resolve
```

### Resolve

There is a Node.js API which allows to resolve requests according to the Node.js resolving rules.
Sync and async APIs are offered. A `create` method allows to create a custom resolve function.

```js
const resolve = require("enhanced-resolve");

resolve("/some/path/to/folder", "module/dir", (err, result) => {
	result; // === "/some/path/node_modules/module/dir/index.js"
});

resolve.sync("/some/path/to/folder", "../../dir");
// === "/some/path/dir/index.js"

const myResolve = resolve.create({
	// or resolve.create.sync
	extensions: [".ts", ".js"]
	// see more options below
});

myResolve("/some/path/to/folder", "ts-module", (err, result) => {
	result; // === "/some/node_modules/ts-module/index.ts"
});
```

### Creating a Resolver

The easiest way to create a resolver is to use the `createResolver` function on `ResolveFactory`, along with one of the supplied File System implementations.

```js
const fs = require("fs");
const { CachedInputFileSystem, ResolverFactory } = require("enhanced-resolve");

// create a resolver
const myResolver = ResolverFactory.createResolver({
	// Typical usage will consume the `fs` + `CachedInputFileSystem`, which wraps Node.js `fs` to add caching.
	fileSystem: new CachedInputFileSystem(fs, 4000),
	extensions: [".js", ".json"]
	/* any other resolver options here. Options/defaults can be seen below */
});

// resolve a file with the new resolver
const context = {};
const lookupStartPath = "/Users/webpack/some/root/dir";
const request = "./path/to-look-up.js";
const resolveContext = {};
myResolver.resolve(context, lookupStartPath, request, resolveContext, (
	err /*Error*/,
	filepath /*string*/
) => {
	// Do something with the path
});
```

#### Resolver Options

| Field            | Default                     | Description                                                                                                                                               |
|------------------|-----------------------------| --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| alias            | []                          | A list of module alias configurations or an object which maps key to value                                                                                |
| aliasFields      | []                          | A list of alias fields in description files                                                                                                               |
| extensionAlias   | {}                          | An object which maps extension to extension aliases                                                                                                       |
| cachePredicate   | function() { return true }; | A function which decides whether a request should be cached or not. An object is passed to the function with `path` and `request` properties.             |
| cacheWithContext | true                        | If unsafe cache is enabled, includes `request.context` in the cache key                                                                                   |
| conditionNames   | []                          | A list of exports field condition names                                                                                                                   |
| descriptionFiles | ["package.json"]            | A list of description files to read from                                                                                                                  |
| enforceExtension | false                       | Enforce that a extension from extensions must be used                                                                                                     |
| exportsFields    | ["exports"]                 | A list of exports fields in description files                                                                                                             |
| extensions       | [".js", ".json", ".node"]   | A list of extensions which should be tried for files                                                                                                      |
| fallback         | []                          | Same as `alias`, but only used if default resolving fails                                                                                                |                                                                                                                                                                                         
| fileSystem       |                             | The file system which should be used                                                                                                                      |
| fullySpecified   | false                       | Request passed to resolve is already fully specified and extensions or main files are not resolved for it (they are still resolved for internal requests) |
| mainFields       | ["main"]                    | A list of main fields in description files                                                                                                                |
| mainFiles        | ["index"]                   | A list of main files in directories                                                                                                                       |
| modules          | ["node_modules"]            | A list of directories to resolve modules from, can be absolute path or folder name                                                                        |
| plugins          | []                          | A list of additional resolve plugins which should be applied                                                                                              |
| resolver         | undefined                   | A prepared Resolver to which the plugins are attached                                                                                                     |
| resolveToContext | false                       | Resolve to a context instead of a file                                                                                                                    |
| preferRelative   | false                       | Prefer to resolve module requests as relative request and fallback to resolving as module                                                                 |
| preferAbsolute   | false                       | Prefer to resolve server-relative urls as absolute paths before falling back to resolve in roots                                                          |
| restrictions     | []                          | A list of resolve restrictions                                                                                                                            |
| roots            | []                          | A list of root paths                                                                                                                                      |
| symlinks         | true                        | Whether to resolve symlinks to their symlinked location                                                                                                   |
| unsafeCache      | false                       | Use this cache object to unsafely cache the successful requests                                                                                           |

## Plugins

Similar to `webpack`, the core of `enhanced-resolve` functionality is implemented as individual plugins that are executed using [`tapable`](https://github.com/webpack/tapable).
These plugins can extend the functionality of the library, adding other ways for files/contexts to be resolved.

A plugin should be a `class` (or its ES5 equivalent) with an `apply` method. The `apply` method will receive a `resolver` instance, that can be used to hook in to the event system.

### Plugin Boilerplate

```js
class MyResolverPlugin {
	constructor(source, target) {
		this.source = source;
		this.target = target;
	}

	apply(resolver) {
		const target = resolver.ensureHook(this.target);
		resolver
			.getHook(this.source)
			.tapAsync("MyResolverPlugin", (request, resolveContext, callback) => {
				// Any logic you need to create a new `request` can go here
				resolver.doResolve(target, request, null, resolveContext, callback);
			});
	}
}
```

Plugins are executed in a pipeline, and register which event they should be executed before/after. In the example above, `source` is the name of the event that starts the pipeline, and `target` is what event this plugin should fire, which is what continues the execution of the pipeline. For an example of how these different plugin events create a chain, see `lib/ResolverFactory.js`, in the `//// pipeline ////` section.

## Escaping

It's allowed to escape `#` as `\0#` to avoid parsing it as fragment.

enhanced-resolve will try to resolve requests containing `#` as path and as fragment, so it will automatically figure out if `./some#thing` means `.../some.js#thing` or `.../some#thing.js`. When a `#` is resolved as path it will be escaped in the result. Here: `.../some\0#thing.js`.

## Tests

```javascript
yarn test
```

## Passing options from webpack

If you are using `webpack`, and you want to pass custom options to `enhanced-resolve`, the options are passed from the `resolve` key of your webpack configuration e.g.:

```
resolve: {
  extensions: ['.js', '.jsx'],
  modules: [path.resolve(__dirname, 'src'), 'node_modules'],
  plugins: [new DirectoryNamedWebpackPlugin()]
  ...
},
```

## License

Copyright (c) 2012-2019 JS Foundation and other contributors

MIT (http://www.opensource.org/licenses/mit-license.php)

[npm]: https://img.shields.io/npm/v/enhanced-resolve.svg
[npm-url]: https://www.npmjs.com/package/enhanced-resolve
[build-status]: https://github.com/webpack/enhanced-resolve/actions/workflows/test.yml/badge.svg
[build-status-url]: https://github.com/webpack/enhanced-resolve/actions
[codecov-badge]: https://codecov.io/gh/webpack/enhanced-resolve/branch/main/graph/badge.svg?token=6B6NxtsZc3
[codecov-url]: https://codecov.io/gh/webpack/enhanced-resolve
[size]: https://packagephobia.com/badge?p=enhanced-resolve
[size-url]: https://packagephobia.com/result?p=enhanced-resolve
[discussion]: https://img.shields.io/github/discussions/webpack/webpack
[discussion-url]: https://github.com/webpack/webpack/discussions


---

# entities [![NPM version](https://img.shields.io/npm/v/entities.svg)](https://npmjs.org/package/entities) [![Downloads](https://img.shields.io/npm/dm/entities.svg)](https://npmjs.org/package/entities) [![Node.js CI](https://github.com/fb55/entities/actions/workflows/nodejs-test.yml/badge.svg)](https://github.com/fb55/entities/actions/workflows/nodejs-test.yml)

Encode & decode HTML & XML entities with ease & speed.

## Features

-   😇 Tried and true: `entities` is used by many popular libraries; eg.
    [`htmlparser2`](https://github.com/fb55/htmlparser2), the official
    [AWS SDK](https://github.com/aws/aws-sdk-js-v3) and
    [`commonmark`](https://github.com/commonmark/commonmark.js) use it to
    process HTML entities.
-   ⚡️ Fast: `entities` is the fastest library for decoding HTML entities (as
    of April 2022); see [performance](#performance).
-   🎛 Configurable: Get an output tailored for your needs. You are fine with
    UTF8? That'll save you some bytes. Prefer to only have ASCII characters? We
    can do that as well!

## How to…

### …install `entities`

    npm install entities

### …use `entities`

```javascript
const entities = require("entities");

// Encoding
entities.escapeUTF8("&#38; ü"); // "&amp;#38; ü"
entities.encodeXML("&#38; ü"); // "&amp;#38; &#xfc;"
entities.encodeHTML("&#38; ü"); // "&amp;&num;38&semi; &uuml;"

// Decoding
entities.decodeXML("asdf &amp; &#xFF; &#xFC; &apos;"); // "asdf & ÿ ü '"
entities.decodeHTML("asdf &amp; &yuml; &uuml; &apos;"); // "asdf & ÿ ü '"
```

## Performance

This is how `entities` compares to other libraries on a very basic benchmark
(see `scripts/benchmark.ts`, for 10,000,000 iterations; **lower is better**):

| Library        | Version | `decode` perf | `encode` perf | `escape` perf |
| -------------- | ------- | ------------- | ------------- | ------------- |
| entities       | `3.0.1` | 1.418s        | 6.786s        | 2.196s        |
| html-entities  | `2.3.2` | 2.530s        | 6.829s        | 2.415s        |
| he             | `1.2.0` | 5.800s        | 24.237s       | 3.624s        |
| parse-entities | `3.0.0` | 9.660s        | N/A           | N/A           |

---

## FAQ

> What methods should I actually use to encode my documents?

If your target supports UTF-8, the `escapeUTF8` method is going to be your best
choice. Otherwise, use either `encodeHTML` or `encodeXML` based on whether
you're dealing with an HTML or an XML document.

You can have a look at the options for the `encode` and `decode` methods to see
everything you can configure.

> When should I use strict decoding?

When strict decoding, entities not terminated with a semicolon will be ignored.
This is helpful for decoding entities in legacy environments.

> Why should I use `entities` instead of alternative modules?

As of April 2022, `entities` is a bit faster than other modules. Still, this is
not a very differentiated space and other modules can catch up.

**More importantly**, you might already have `entities` in your dependency graph
(as a dependency of eg. `cheerio`, or `htmlparser2`), and including it directly
might not even increase your bundle size. The same is true for other entity
libraries, so have a look through your `node_modules` directory!

> Does `entities` support tree shaking?

Yes! `entities` ships as both a CommonJS and a ES module. Note that for best
results, you should not use the `encode` and `decode` functions, as they wrap
around a number of other functions, all of which will remain in the bundle.
Instead, use the functions that you need directly.

---

## Acknowledgements

This library wouldn't be possible without the work of these individuals. Thanks
to

-   [@mathiasbynens](https://github.com/mathiasbynens) for his explanations
    about character encodings, and his library `he`, which was one of the
    inspirations for `entities`
-   [@inikulin](https://github.com/inikulin) for his work on optimized tries for
    decoding HTML entities for the `parse5` project
-   [@mdevils](https://github.com/mdevils) for taking on the challenge of
    producing a quick entity library with his `html-entities` library.
    `entities` would be quite a bit slower if there wasn't any competition.
    Right now `entities` is on top, but we'll see how long that lasts!

---

License: BSD-2-Clause

## Security contact information

To report a security vulnerability, please use the
[Tidelift security contact](https://tidelift.com/security). Tidelift will
coordinate the fix and disclosure.

## `entities` for enterprise

Available as part of the Tidelift Subscription

The maintainers of `entities` and thousands of other packages are working with
Tidelift to deliver commercial support and maintenance for the open source
dependencies you use to build your applications. Save time, reduce risk, and
improve code health, while paying the maintainers of the exact dependencies you
use.
[Learn more.](https://tidelift.com/subscription/pkg/npm-entities?utm_source=npm-entities&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)


---

# node-error-ex [![Travis-CI.org Build Status](https://img.shields.io/travis/Qix-/node-error-ex.svg?style=flat-square)](https://travis-ci.org/Qix-/node-error-ex) [![Coveralls.io Coverage Rating](https://img.shields.io/coveralls/Qix-/node-error-ex.svg?style=flat-square)](https://coveralls.io/r/Qix-/node-error-ex)
> Easily subclass and customize new Error types

## Examples
To include in your project:
```javascript
var errorEx = require('error-ex');
```

To create an error message type with a specific name (note, that `ErrorFn.name`
will not reflect this):
```javascript
var JSONError = errorEx('JSONError');

var err = new JSONError('error');
err.name; //-> JSONError
throw err; //-> JSONError: error
```

To add a stack line:
```javascript
var JSONError = errorEx('JSONError', {fileName: errorEx.line('in %s')});

var err = new JSONError('error')
err.fileName = '/a/b/c/foo.json';
throw err; //-> (line 2)-> in /a/b/c/foo.json
```

To append to the error message:
```javascript
var JSONError = errorEx('JSONError', {fileName: errorEx.append('in %s')});

var err = new JSONError('error');
err.fileName = '/a/b/c/foo.json';
throw err; //-> JSONError: error in /a/b/c/foo.json
```

## API

#### `errorEx([name], [properties])`
Creates a new ErrorEx error type

- `name`: the name of the new type (appears in the error message upon throw;
  defaults to `Error.name`)
- `properties`: if supplied, used as a key/value dictionary of properties to
  use when building up the stack message. Keys are property names that are
  looked up on the error message, and then passed to function values.
	- `line`: if specified and is a function, return value is added as a stack
    entry (error-ex will indent for you). Passed the property value given
    the key.
  - `stack`: if specified and is a function, passed the value of the property
    using the key, and the raw stack lines as a second argument. Takes no
    return value (but the stack can be modified directly).
  - `message`: if specified and is a function, return value is used as new
    `.message` value upon get. Passed the property value of the property named
    by key, and the existing message is passed as the second argument as an
    array of lines (suitable for multi-line messages).

Returns a constructor (Function) that can be used just like the regular Error
constructor.

```javascript
var errorEx = require('error-ex');

var BasicError = errorEx();

var NamedError = errorEx('NamedError');

// --

var AdvancedError = errorEx('AdvancedError', {
	foo: {
		line: function (value, stack) {
			if (value) {
				return 'bar ' + value;
			}
			return null;
		}
	}
}

var err = new AdvancedError('hello, world');
err.foo = 'baz';
throw err;

/*
	AdvancedError: hello, world
	    bar baz
	    at tryReadme() (readme.js:20:1)
*/
```

#### `errorEx.line(str)`
Creates a stack line using a delimiter

> This is a helper function. It is to be used in lieu of writing a value object
> for `properties` values.

- `str`: The string to create
  - Use the delimiter `%s` to specify where in the string the value should go

```javascript
var errorEx = require('error-ex');

var FileError = errorEx('FileError', {fileName: errorEx.line('in %s')});

var err = new FileError('problem reading file');
err.fileName = '/a/b/c/d/foo.js';
throw err;

/*
	FileError: problem reading file
	    in /a/b/c/d/foo.js
	    at tryReadme() (readme.js:7:1)
*/
```

#### `errorEx.append(str)`
Appends to the `error.message` string

> This is a helper function. It is to be used in lieu of writing a value object
> for `properties` values.

- `str`: The string to append
  - Use the delimiter `%s` to specify where in the string the value should go

```javascript
var errorEx = require('error-ex');

var SyntaxError = errorEx('SyntaxError', {fileName: errorEx.append('in %s')});

var err = new SyntaxError('improper indentation');
err.fileName = '/a/b/c/d/foo.js';
throw err;

/*
	SyntaxError: improper indentation in /a/b/c/d/foo.js
	    at tryReadme() (readme.js:7:1)
*/
```

## License
Licensed under the [MIT License](http://opensource.org/licenses/MIT).
You can find a copy of it in [LICENSE](LICENSE).


---

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [v1.0.1](https://github.com/ljharb/es-define-property/compare/v1.0.0...v1.0.1) - 2024-12-06

### Commits

- [types] use shared tsconfig [`954a663`](https://github.com/ljharb/es-define-property/commit/954a66360326e508a0e5daa4b07493d58f5e110e)
- [actions] split out node 10-20, and 20+ [`3a8e84b`](https://github.com/ljharb/es-define-property/commit/3a8e84b23883f26ff37b3e82ff283834228e18c6)
- [Dev Deps] update `@ljharb/eslint-config`, `@ljharb/tsconfig`, `@types/get-intrinsic`, `@types/tape`, `auto-changelog`, `gopd`, `tape` [`86ae27b`](https://github.com/ljharb/es-define-property/commit/86ae27bb8cc857b23885136fad9cbe965ae36612)
- [Refactor] avoid using `get-intrinsic` [`02480c0`](https://github.com/ljharb/es-define-property/commit/02480c0353ef6118965282977c3864aff53d98b1)
- [Tests] replace `aud` with `npm audit` [`f6093ff`](https://github.com/ljharb/es-define-property/commit/f6093ff74ab51c98015c2592cd393bd42478e773)
- [Tests] configure testling [`7139e66`](https://github.com/ljharb/es-define-property/commit/7139e66959247a56086d9977359caef27c6849e7)
- [Dev Deps] update `tape` [`b901b51`](https://github.com/ljharb/es-define-property/commit/b901b511a75e001a40ce1a59fef7d9ffcfc87482)
- [Tests] fix types in tests [`469d269`](https://github.com/ljharb/es-define-property/commit/469d269fd141b1e773ec053a9fa35843493583e0)
- [Dev Deps] add missing peer dep [`733acfb`](https://github.com/ljharb/es-define-property/commit/733acfb0c4c96edf337e470b89a25a5b3724c352)

## v1.0.0 - 2024-02-12

### Commits

- Initial implementation, tests, readme, types [`3e154e1`](https://github.com/ljharb/es-define-property/commit/3e154e11a2fee09127220f5e503bf2c0a31dd480)
- Initial commit [`07d98de`](https://github.com/ljharb/es-define-property/commit/07d98de34a4dc31ff5e83a37c0c3f49e0d85cd50)
- npm init [`c4eb634`](https://github.com/ljharb/es-define-property/commit/c4eb6348b0d3886aac36cef34ad2ee0665ea6f3e)
- Only apps should have lockfiles [`7af86ec`](https://github.com/ljharb/es-define-property/commit/7af86ec1d311ec0b17fdfe616a25f64276903856)


---

# es-define-property <sup>[![Version Badge][npm-version-svg]][package-url]</sup>

[![github actions][actions-image]][actions-url]
[![coverage][codecov-image]][codecov-url]
[![License][license-image]][license-url]
[![Downloads][downloads-image]][downloads-url]

[![npm badge][npm-badge-png]][package-url]

`Object.defineProperty`, but not IE 8's broken one.

## Example

```js
const assert = require('assert');

const $defineProperty = require('es-define-property');

if ($defineProperty) {
    assert.equal($defineProperty, Object.defineProperty);
} else if (Object.defineProperty) {
    assert.equal($defineProperty, false, 'this is IE 8');
} else {
    assert.equal($defineProperty, false, 'this is an ES3 engine');
}
```

## Tests
Simply clone the repo, `npm install`, and run `npm test`

## Security

Please email [@ljharb](https://github.com/ljharb) or see https://tidelift.com/security if you have a potential security vulnerability to report.

[package-url]: https://npmjs.org/package/es-define-property
[npm-version-svg]: https://versionbadg.es/ljharb/es-define-property.svg
[deps-svg]: https://david-dm.org/ljharb/es-define-property.svg
[deps-url]: https://david-dm.org/ljharb/es-define-property
[dev-deps-svg]: https://david-dm.org/ljharb/es-define-property/dev-status.svg
[dev-deps-url]: https://david-dm.org/ljharb/es-define-property#info=devDependencies
[npm-badge-png]: https://nodei.co/npm/es-define-property.png?downloads=true&stars=true
[license-image]: https://img.shields.io/npm/l/es-define-property.svg
[license-url]: LICENSE
[downloads-image]: https://img.shields.io/npm/dm/es-define-property.svg
[downloads-url]: https://npm-stat.com/charts.html?package=es-define-property
[codecov-image]: https://codecov.io/gh/ljharb/es-define-property/branch/main/graphs/badge.svg
[codecov-url]: https://app.codecov.io/gh/ljharb/es-define-property/
[actions-image]: https://img.shields.io/endpoint?url=https://github-actions-badge-u3jn4tfpocch.runkit.sh/ljharb/es-define-property
[actions-url]: https://github.com/ljharb/es-define-property/actions


---

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [v1.3.0](https://github.com/ljharb/es-errors/compare/v1.2.1...v1.3.0) - 2024-02-05

### Commits

- [New] add `EvalError` and `URIError` [`1927627`](https://github.com/ljharb/es-errors/commit/1927627ba68cb6c829d307231376c967db53acdf)

## [v1.2.1](https://github.com/ljharb/es-errors/compare/v1.2.0...v1.2.1) - 2024-02-04

### Commits

- [Fix] add missing `exports` entry [`5bb5f28`](https://github.com/ljharb/es-errors/commit/5bb5f280f98922701109d6ebb82eea2257cecc7e)

## [v1.2.0](https://github.com/ljharb/es-errors/compare/v1.1.0...v1.2.0) - 2024-02-04

### Commits

- [New] add `ReferenceError` [`6d8cf5b`](https://github.com/ljharb/es-errors/commit/6d8cf5bbb6f3f598d02cf6f30e468ba2caa8e143)

## [v1.1.0](https://github.com/ljharb/es-errors/compare/v1.0.0...v1.1.0) - 2024-02-04

### Commits

- [New] add base Error [`2983ab6`](https://github.com/ljharb/es-errors/commit/2983ab65f7bc5441276cb021dc3aa03c78881698)

## v1.0.0 - 2024-02-03

### Commits

- Initial implementation, tests, readme, type [`8f47631`](https://github.com/ljharb/es-errors/commit/8f476317e9ad76f40ad648081829b1a1a3a1288b)
- Initial commit [`ea5d099`](https://github.com/ljharb/es-errors/commit/ea5d099ef18e550509ab9e2be000526afd81c385)
- npm init [`6f5ebf9`](https://github.com/ljharb/es-errors/commit/6f5ebf9cead474dadd72b9e63dad315820a089ae)
- Only apps should have lockfiles [`e1a0aeb`](https://github.com/ljharb/es-errors/commit/e1a0aeb7b80f5cfc56be54d6b2100e915d47def8)
- [meta] add `sideEffects` flag [`a9c7d46`](https://github.com/ljharb/es-errors/commit/a9c7d460a492f1d8a241c836bc25a322a19cc043)


---

# es-errors <sup>[![Version Badge][npm-version-svg]][package-url]</sup>

[![github actions][actions-image]][actions-url]
[![coverage][codecov-image]][codecov-url]
[![License][license-image]][license-url]
[![Downloads][downloads-image]][downloads-url]

[![npm badge][npm-badge-png]][package-url]

A simple cache for a few of the JS Error constructors.

## Example

```js
const assert = require('assert');

const Base = require('es-errors');
const Eval = require('es-errors/eval');
const Range = require('es-errors/range');
const Ref = require('es-errors/ref');
const Syntax = require('es-errors/syntax');
const Type = require('es-errors/type');
const URI = require('es-errors/uri');

assert.equal(Base, Error);
assert.equal(Eval, EvalError);
assert.equal(Range, RangeError);
assert.equal(Ref, ReferenceError);
assert.equal(Syntax, SyntaxError);
assert.equal(Type, TypeError);
assert.equal(URI, URIError);
```

## Tests
Simply clone the repo, `npm install`, and run `npm test`

## Security

Please email [@ljharb](https://github.com/ljharb) or see https://tidelift.com/security if you have a potential security vulnerability to report.

[package-url]: https://npmjs.org/package/es-errors
[npm-version-svg]: https://versionbadg.es/ljharb/es-errors.svg
[deps-svg]: https://david-dm.org/ljharb/es-errors.svg
[deps-url]: https://david-dm.org/ljharb/es-errors
[dev-deps-svg]: https://david-dm.org/ljharb/es-errors/dev-status.svg
[dev-deps-url]: https://david-dm.org/ljharb/es-errors#info=devDependencies
[npm-badge-png]: https://nodei.co/npm/es-errors.png?downloads=true&stars=true
[license-image]: https://img.shields.io/npm/l/es-errors.svg
[license-url]: LICENSE
[downloads-image]: https://img.shields.io/npm/dm/es-errors.svg
[downloads-url]: https://npm-stat.com/charts.html?package=es-errors
[codecov-image]: https://codecov.io/gh/ljharb/es-errors/branch/main/graphs/badge.svg
[codecov-url]: https://app.codecov.io/gh/ljharb/es-errors/
[actions-image]: https://img.shields.io/endpoint?url=https://github-actions-badge-u3jn4tfpocch.runkit.sh/ljharb/es-errors
[actions-url]: https://github.com/ljharb/es-errors/actions


---

# ES Module Lexer

[![Build Status][actions-image]][actions-url]

A JS module syntax lexer used in [es-module-shims](https://github.com/guybedford/es-module-shims).

Outputs the list of exports and locations of import specifiers, including dynamic import and import meta handling.

A very small single JS file (4KiB gzipped) that includes inlined Web Assembly for very fast source analysis of ECMAScript module syntax only.

For an example of the performance, Angular 1 (720KiB) is fully parsed in 5ms, in comparison to the fastest JS parser, Acorn which takes over 100ms.

_Comprehensively handles the JS language grammar while remaining small and fast. - ~10ms per MB of JS cold and ~5ms per MB of JS warm, [see benchmarks](#benchmarks) for more info._

> [Built with](https://github.com/guybedford/es-module-lexer/blob/main/chompfile.toml) [Chomp](https://chompbuild.com/)

### Usage

```
npm install es-module-lexer
```

For use in CommonJS:

```js
const { init, parse } = require('es-module-lexer');

(async () => {
  // either await init, or call parse asynchronously
  // this is necessary for the Web Assembly boot
  await init;

  const source = 'export var p = 5';
  const [imports, exports] = parse(source);
  
  // Returns "p"
  source.slice(exports[0].s, exports[0].e);
  // Returns "p"
  source.slice(exports[0].ls, exports[0].le);
})();
```

An ES module version is also available:

```js
import { init, parse } from 'es-module-lexer';

(async () => {
  await init;

  const source = `
    import { name } from 'mod\\u1011';
    import json from './json.json' assert { type: 'json' }
    export var p = 5;
    export function q () {

    };
    export { x as 'external name' } from 'external';

    // Comments provided to demonstrate edge cases
    import /*comment!*/ (  'asdf', { assert: { type: 'json' }});
    import /*comment!*/.meta.asdf;
  `;

  const [imports, exports] = parse(source, 'optional-sourcename');

  // Returns "modထ"
  imports[0].n
  // Returns "mod\u1011"
  source.slice(imports[0].s, imports[0].e);
  // "s" = start
  // "e" = end

  // Returns "import { name } from 'mod'"
  source.slice(imports[0].ss, imports[0].se);
  // "ss" = statement start
  // "se" = statement end

  // Returns "{ type: 'json' }"
  source.slice(imports[1].a, imports[1].se);
  // "a" = assert, -1 for no assertion

  // Returns "external"
  source.slice(imports[2].s, imports[2].e);

  // Returns "p"
  source.slice(exports[0].s, exports[0].e);
  // Returns "p"
  source.slice(exports[0].ls, exports[0].le);
  // Returns "q"
  source.slice(exports[1].s, exports[1].e);
  // Returns "q"
  source.slice(exports[1].ls, exports[1].le);
  // Returns "'external name'"
  source.slice(exports[2].s, exports[2].e);
  // Returns -1
  exports[2].ls;
  // Returns -1
  exports[2].le;

  // Dynamic imports are indicated by imports[2].d > -1
  // In this case the "d" index is the start of the dynamic import bracket
  // Returns true
  imports[2].d > -1;

  // Returns "asdf" (only for string literal dynamic imports)
  imports[2].n
  // Returns "import /*comment!*/ (  'asdf', { assert: { type: 'json' } })"
  source.slice(imports[3].ss, imports[3].se);
  // Returns "'asdf'"
  source.slice(imports[3].s, imports[3].e);
  // Returns "(  'asdf', { assert: { type: 'json' } })"
  source.slice(imports[3].d, imports[3].se);
  // Returns "{ assert: { type: 'json' } }"
  source.slice(imports[3].a, imports[3].se - 1);

  // For non-string dynamic import expressions:
  // - n will be undefined
  // - a is currently -1 even if there is an assertion
  // - e is currently the character before the closing )

  // For nested dynamic imports, the se value of the outer import is -1 as end tracking does not
  // currently support nested dynamic immports

  // import.meta is indicated by imports[3].d === -2
  // Returns true
  imports[4].d === -2;
  // Returns "import /*comment!*/.meta"
  source.slice(imports[4].s, imports[4].e);
  // ss and se are the same for import meta
})();
```

### CSP asm.js Build

The default version of the library uses Wasm and (safe) eval usage for performance and a minimal footprint.

Neither of these represent security escalation possibilities since there are no execution string injection vectors, but that can still violate existing CSP policies for applications.

For a version that works with CSP eval disabled, use the `es-module-lexer/js` build:

```js
import { parse } from 'es-module-lexer/js';
```

Instead of Web Assembly, this uses an asm.js build which is almost as fast as the Wasm version ([see benchmarks below](#benchmarks)).

### Escape Sequences

To handle escape sequences in specifier strings, the `.n` field of imported specifiers will be provided where possible.

For dynamic import expressions, this field will be empty if not a valid JS string.

### Facade Detection

Facade modules that only use import / export syntax can be detected via the third return value:

```js
const [,, facade] = parse(`
  export * from 'external';
  import * as ns from 'external2';
  export { a as b } from 'external3';
  export { ns };
`);
facade === true;
```

### Environment Support

Node.js 10+, and [all browsers with Web Assembly support](https://caniuse.com/#feat=wasm).

### Grammar Support

* Token state parses all line comments, block comments, strings, template strings, blocks, parens and punctuators.
* Division operator / regex token ambiguity is handled via backtracking checks against punctuator prefixes, including closing brace or paren backtracking.
* Always correctly parses valid JS source, but may parse invalid JS source without errors.

### Limitations

The lexing approach is designed to deal with the full language grammar including RegEx / division operator ambiguity through backtracking and paren / brace tracking.

The only limitation to the reduced parser is that the "exports" list may not correctly gather all export identifiers in the following edge cases:

```js
// Only "a" is detected as an export, "q" isn't
export var a = 'asdf', q = z;

// "b" is not detected as an export
export var { a: b } = asdf;
```

The above cases are handled gracefully in that the lexer will keep going fine, it will just not properly detect the export names above.

### Benchmarks

Benchmarks can be run with `npm run bench`.

Current results for a high spec machine:

#### Wasm Build

```
Module load time
> 5ms
Cold Run, All Samples
test/samples/*.js (3123 KiB)
> 18ms

Warm Runs (average of 25 runs)
test/samples/angular.js (739 KiB)
> 3ms
test/samples/angular.min.js (188 KiB)
> 1ms
test/samples/d3.js (508 KiB)
> 3ms
test/samples/d3.min.js (274 KiB)
> 2ms
test/samples/magic-string.js (35 KiB)
> 0ms
test/samples/magic-string.min.js (20 KiB)
> 0ms
test/samples/rollup.js (929 KiB)
> 4.32ms
test/samples/rollup.min.js (429 KiB)
> 2.16ms

Warm Runs, All Samples (average of 25 runs)
test/samples/*.js (3123 KiB)
> 14.16ms
```

#### JS Build (asm.js)

```
Module load time
> 2ms
Cold Run, All Samples
test/samples/*.js (3123 KiB)
> 34ms

Warm Runs (average of 25 runs)
test/samples/angular.js (739 KiB)
> 3ms
test/samples/angular.min.js (188 KiB)
> 1ms
test/samples/d3.js (508 KiB)
> 3ms
test/samples/d3.min.js (274 KiB)
> 2ms
test/samples/magic-string.js (35 KiB)
> 0ms
test/samples/magic-string.min.js (20 KiB)
> 0ms
test/samples/rollup.js (929 KiB)
> 5ms
test/samples/rollup.min.js (429 KiB)
> 3.04ms

Warm Runs, All Samples (average of 25 runs)
test/samples/*.js (3123 KiB)
> 17.12ms
```

### Building

This project uses [Chomp](https://chompbuild.com) for building.

With Chomp installed, download the WASI SDK 12.0 from https://github.com/WebAssembly/wasi-sdk/releases/tag/wasi-sdk-12.

- [Linux](https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-12/wasi-sdk-12.0-linux.tar.gz)
- [Windows (MinGW)](https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-12/wasi-sdk-12.0-mingw.tar.gz)
- [macOS](https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-12/wasi-sdk-12.0-macos.tar.gz)

Locate the WASI-SDK as a sibling folder, or customize the path via the `WASI_PATH` environment variable.

Emscripten emsdk is also assumed to be a sibling folder or via the `EMSDK_PATH` environment variable.

Example setup:

```
git clone https://github.com:guybedford/es-module-lexer
git clone https://github.com/emscripten-core/emsdk
cd emsdk
git checkout 1.40.1-fastcomp
./emsdk install 1.40.1-fastcomp
cd ..
wget https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-12/wasi-sdk-12.0-linux.tar.gz
gunzip wasi-sdk-12.0-linux.tar.gz
tar -xf wasi-sdk-12.0-linux.tar
mv wasi-sdk-12.0-linux.tar wasi-sdk-12.0
cargo install chompbuild
cd es-module-lexer
chomp test
```

For the `asm.js` build, git clone `emsdk` from  is assumed to be a sibling folder as well.

### License

MIT

[actions-image]: https://github.com/guybedford/es-module-lexer/actions/workflows/build.yml/badge.svg
[actions-url]: https://github.com/guybedford/es-module-lexer/actions/workflows/build.yml



---

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [v1.1.1](https://github.com/ljharb/es-object-atoms/compare/v1.1.0...v1.1.1) - 2025-01-14

### Commits

- [types] `ToObject`: improve types [`cfe8c8a`](https://github.com/ljharb/es-object-atoms/commit/cfe8c8a105c44820cb22e26f62d12ef0ad9715c8)

## [v1.1.0](https://github.com/ljharb/es-object-atoms/compare/v1.0.1...v1.1.0) - 2025-01-14

### Commits

- [New] add `isObject` [`51e4042`](https://github.com/ljharb/es-object-atoms/commit/51e4042df722eb3165f40dc5f4bf33d0197ecb07)

## [v1.0.1](https://github.com/ljharb/es-object-atoms/compare/v1.0.0...v1.0.1) - 2025-01-13

### Commits

- [Dev Deps] update `@ljharb/eslint-config`, `@ljharb/tsconfig`, `@types/tape`, `auto-changelog`, `tape` [`38ab9eb`](https://github.com/ljharb/es-object-atoms/commit/38ab9eb00b62c2f4668644f5e513d9b414ebd595)
- [types] improve types [`7d1beb8`](https://github.com/ljharb/es-object-atoms/commit/7d1beb887958b78b6a728a210a1c8370ab7e2aa1)
- [Tests] replace `aud` with `npm audit` [`25863ba`](https://github.com/ljharb/es-object-atoms/commit/25863baf99178f1d1ad33d1120498db28631907e)
- [Dev Deps] add missing peer dep [`c012309`](https://github.com/ljharb/es-object-atoms/commit/c0123091287e6132d6f4240496340c427433df28)

## v1.0.0 - 2024-03-16

### Commits

- Initial implementation, tests, readme, types [`f1499db`](https://github.com/ljharb/es-object-atoms/commit/f1499db7d3e1741e64979c61d645ab3137705e82)
- Initial commit [`99eedc7`](https://github.com/ljharb/es-object-atoms/commit/99eedc7b5fde38a50a28d3c8b724706e3e4c5f6a)
- [meta] rename repo [`fc851fa`](https://github.com/ljharb/es-object-atoms/commit/fc851fa70616d2d182aaf0bd02c2ed7084dea8fa)
- npm init [`b909377`](https://github.com/ljharb/es-object-atoms/commit/b909377c50049bd0ec575562d20b0f9ebae8947f)
- Only apps should have lockfiles [`7249edd`](https://github.com/ljharb/es-object-atoms/commit/7249edd2178c1b9ddfc66ffcc6d07fdf0d28efc1)


---

# es-object-atoms <sup>[![Version Badge][npm-version-svg]][package-url]</sup>

[![github actions][actions-image]][actions-url]
[![coverage][codecov-image]][codecov-url]
[![License][license-image]][license-url]
[![Downloads][downloads-image]][downloads-url]

[![npm badge][npm-badge-png]][package-url]

ES Object-related atoms: Object, ToObject, RequireObjectCoercible.

## Example

```js
const assert = require('assert');

const $Object = require('es-object-atoms');
const isObject = require('es-object-atoms/isObject');
const ToObject = require('es-object-atoms/ToObject');
const RequireObjectCoercible = require('es-object-atoms/RequireObjectCoercible');

assert.equal($Object, Object);
assert.throws(() => ToObject(null), TypeError);
assert.throws(() => ToObject(undefined), TypeError);
assert.throws(() => RequireObjectCoercible(null), TypeError);
assert.throws(() => RequireObjectCoercible(undefined), TypeError);

assert.equal(isObject(undefined), false);
assert.equal(isObject(null), false);
assert.equal(isObject({}), true);
assert.equal(isObject([]), true);
assert.equal(isObject(function () {}), true);

assert.deepEqual(RequireObjectCoercible(true), true);
assert.deepEqual(ToObject(true), Object(true));

const obj = {};
assert.equal(RequireObjectCoercible(obj), obj);
assert.equal(ToObject(obj), obj);
```

## Tests
Simply clone the repo, `npm install`, and run `npm test`

## Security

Please email [@ljharb](https://github.com/ljharb) or see https://tidelift.com/security if you have a potential security vulnerability to report.

[package-url]: https://npmjs.org/package/es-object-atoms
[npm-version-svg]: https://versionbadg.es/ljharb/es-object-atoms.svg
[deps-svg]: https://david-dm.org/ljharb/es-object-atoms.svg
[deps-url]: https://david-dm.org/ljharb/es-object-atoms
[dev-deps-svg]: https://david-dm.org/ljharb/es-object-atoms/dev-status.svg
[dev-deps-url]: https://david-dm.org/ljharb/es-object-atoms#info=devDependencies
[npm-badge-png]: https://nodei.co/npm/es-object-atoms.png?downloads=true&stars=true
[license-image]: https://img.shields.io/npm/l/es-object-atoms.svg
[license-url]: LICENSE
[downloads-image]: https://img.shields.io/npm/dm/es-object.svg
[downloads-url]: https://npm-stat.com/charts.html?package=es-object-atoms
[codecov-image]: https://codecov.io/gh/ljharb/es-object-atoms/branch/main/graphs/badge.svg
[codecov-url]: https://app.codecov.io/gh/ljharb/es-object-atoms/
[actions-image]: https://img.shields.io/endpoint?url=https://github-actions-badge-u3jn4tfpocch.runkit.sh/ljharb/es-object-atoms
[actions-url]: https://github.com/ljharb/es-object-atoms/actions


---

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [v2.1.0](https://github.com/es-shims/es-set-tostringtag/compare/v2.0.3...v2.1.0) - 2025-01-01

### Commits

- [actions] split out node 10-20, and 20+ [`ede033c`](https://github.com/es-shims/es-set-tostringtag/commit/ede033cc4e506c3966d2d482d4ac5987e329162a)
- [types] use shared config [`28ef164`](https://github.com/es-shims/es-set-tostringtag/commit/28ef164ad7c5bc21837c79f7ef25542a1f258ade)
- [New] add `nonConfigurable` option [`3bee3f0`](https://github.com/es-shims/es-set-tostringtag/commit/3bee3f04caddd318f3932912212ed20b2d62aad7)
- [Fix] validate boolean option argument [`3c8a609`](https://github.com/es-shims/es-set-tostringtag/commit/3c8a609c795a305ccca163f0ff6956caa88cdc0e)
- [Dev Deps] update `@arethetypeswrong/cli`, `@ljharb/eslint-config`, `@ljharb/tsconfig`, `@types/get-intrinsic`, `@types/tape`, `auto-changelog`, `tape` [`501a969`](https://github.com/es-shims/es-set-tostringtag/commit/501a96998484226e07f5ffd447e8f305a998f1d8)
- [Tests] add coverage [`18af289`](https://github.com/es-shims/es-set-tostringtag/commit/18af2897b4e937373c9b8c8831bc338932246470)
- [readme] document `force` option [`bd446a1`](https://github.com/es-shims/es-set-tostringtag/commit/bd446a107b71a2270278442e5124f45590d3ee64)
- [Tests] use `@arethetypeswrong/cli` [`7c2c2fa`](https://github.com/es-shims/es-set-tostringtag/commit/7c2c2fa3cca0f4d263603adb75426b239514598f)
- [Tests] replace `aud` with `npm audit` [`9e372d7`](https://github.com/es-shims/es-set-tostringtag/commit/9e372d7e6db3dab405599a14d9074a99a03b8242)
- [Deps] update `get-intrinsic` [`7df1216`](https://github.com/es-shims/es-set-tostringtag/commit/7df12167295385c2a547410e687cb0c04f3a34b9)
- [Deps] update `hasown` [`993a7d2`](https://github.com/es-shims/es-set-tostringtag/commit/993a7d200e2059fd857ec1a25d0a49c2c34ae6e2)
- [Dev Deps] add missing peer dep [`148ed8d`](https://github.com/es-shims/es-set-tostringtag/commit/148ed8db99a7a94f9af3823fd083e6e437fa1587)

## [v2.0.3](https://github.com/es-shims/es-set-tostringtag/compare/v2.0.2...v2.0.3) - 2024-02-20

### Commits

- add types [`d538513`](https://github.com/es-shims/es-set-tostringtag/commit/d5385133592a32a0a416cb535327918af7fbc4ad)
- [Deps] update `get-intrinsic`, `has-tostringtag`, `hasown` [`d129b29`](https://github.com/es-shims/es-set-tostringtag/commit/d129b29536bccc8a9d03a47887ca4d1f7ad0c5b9)
- [Dev Deps] update `aud`, `npmignore`, `tape` [`132ed23`](https://github.com/es-shims/es-set-tostringtag/commit/132ed23c964a41ed55e4ab4a5a2c3fe185e821c1)
- [Tests] fix hasOwn require [`f89c831`](https://github.com/es-shims/es-set-tostringtag/commit/f89c831fe5f3edf1f979c597b56fee1be6111f56)

## [v2.0.2](https://github.com/es-shims/es-set-tostringtag/compare/v2.0.1...v2.0.2) - 2023-10-20

### Commits

- [Refactor] use `hasown` instead of `has` [`0cc6c4e`](https://github.com/es-shims/es-set-tostringtag/commit/0cc6c4e61fd13e8f00b85424ae6e541ebf289e74)
- [Dev Deps] update `@ljharb/eslint-config`, `aud`, `tape` [`70e447c`](https://github.com/es-shims/es-set-tostringtag/commit/70e447cf9f82b896ddf359fda0a0498c16cf3ed2)
- [Deps] update `get-intrinsic` [`826aab7`](https://github.com/es-shims/es-set-tostringtag/commit/826aab76180392871c8efa99acc0f0bbf775c64e)

## [v2.0.1](https://github.com/es-shims/es-set-tostringtag/compare/v2.0.0...v2.0.1) - 2023-01-05

### Fixed

- [Fix] move `has` to prod deps [`#2`](https://github.com/es-shims/es-set-tostringtag/issues/2)

### Commits

- [Dev Deps] update `@ljharb/eslint-config` [`b9eecd2`](https://github.com/es-shims/es-set-tostringtag/commit/b9eecd23c10b7b43ba75089ac8ff8cc6b295798b)

## [v2.0.0](https://github.com/es-shims/es-set-tostringtag/compare/v1.0.0...v2.0.0) - 2022-12-21

### Commits

- [Tests] refactor tests [`168dcfb`](https://github.com/es-shims/es-set-tostringtag/commit/168dcfbb535c279dc48ccdc89419155125aaec18)
- [Breaking] do not set toStringTag if it is already set [`226ab87`](https://github.com/es-shims/es-set-tostringtag/commit/226ab874192c625d9e5f0e599d3f60d2b2aa83b5)
- [New] add `force` option to set even if already set [`1abd4ec`](https://github.com/es-shims/es-set-tostringtag/commit/1abd4ecb282f19718c4518284b0293a343564505)

## v1.0.0 - 2022-12-21

### Commits

- Initial implementation, tests, readme [`a0e1147`](https://github.com/es-shims/es-set-tostringtag/commit/a0e11473f79a233b46374525c962ea1b4d42418a)
- Initial commit [`ffd4aff`](https://github.com/es-shims/es-set-tostringtag/commit/ffd4afffbeebf29aff0d87a7cfc3f7844e09fe68)
- npm init [`fffe5bd`](https://github.com/es-shims/es-set-tostringtag/commit/fffe5bd1d1146d084730a387a9c672371f4a8fff)
- Only apps should have lockfiles [`d363871`](https://github.com/es-shims/es-set-tostringtag/commit/d36387139465623e161a15dbd39120537f150c62)


---

# es-set-tostringtag <sup>[![Version Badge][npm-version-svg]][package-url]</sup>

[![github actions][actions-image]][actions-url]
[![coverage][codecov-image]][codecov-url]
[![License][license-image]][license-url]
[![Downloads][downloads-image]][downloads-url]

[![npm badge][npm-badge-png]][package-url]

A helper to optimistically set Symbol.toStringTag, when possible.

## Example
Most common usage:
```js
var assert = require('assert');
var setToStringTag = require('es-set-tostringtag');

var obj = {};

assert.equal(Object.prototype.toString.call(obj), '[object Object]');

setToStringTag(obj, 'tagged!');

assert.equal(Object.prototype.toString.call(obj), '[object tagged!]');
```

## Options
An optional options argument can be provided as the third argument. The available options are:

### `force`
If the `force` option is set to `true`, the toStringTag will be set even if it is already set.

### `nonConfigurable`
If the `nonConfigurable` option is set to `true`, the toStringTag will be defined as non-configurable when possible.

## Tests
Simply clone the repo, `npm install`, and run `npm test`

[package-url]: https://npmjs.com/package/es-set-tostringtag
[npm-version-svg]: https://versionbadg.es/es-shims/es-set-tostringtag.svg
[deps-svg]: https://david-dm.org/es-shims/es-set-tostringtag.svg
[deps-url]: https://david-dm.org/es-shims/es-set-tostringtag
[dev-deps-svg]: https://david-dm.org/es-shims/es-set-tostringtag/dev-status.svg
[dev-deps-url]: https://david-dm.org/es-shims/es-set-tostringtag#info=devDependencies
[npm-badge-png]: https://nodei.co/npm/es-set-tostringtag.png?downloads=true&stars=true
[license-image]: https://img.shields.io/npm/l/es-set-tostringtag.svg
[license-url]: LICENSE
[downloads-image]: https://img.shields.io/npm/dm/es-set-tostringtag.svg
[downloads-url]: https://npm-stat.com/charts.html?package=es-set-tostringtag
[codecov-image]: https://codecov.io/gh/es-shims/es-set-tostringtag/branch/main/graphs/badge.svg
[codecov-url]: https://app.codecov.io/gh/es-shims/es-set-tostringtag/
[actions-image]: https://img.shields.io/endpoint?url=https://github-actions-badge-u3jn4tfpocch.runkit.sh/es-shims/es-set-tostringtag
[actions-url]: https://github.com/es-shims/es-set-tostringtag/actions


---

# esast-util-from-estree

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[esast][] utility to transform from [estree][].

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`fromEstree(estree[, options])`](#fromestreeestree-options)
    *   [`Options`](#options)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package applies some transforms to a cloned, given estree to make it
compatible with unist.
It:

*   makes sure nodes are plain JSON
*   adds unist positions
*   normalizes `.bigint`
*   remove `attributes`, `selfClosing` from `JSXOpeningFragment`
*   removes certain discouraged fields

## When should I use this?

The transform applied by this utility is often optional: estrees can be used in
most places where esast can be used, and vice versa.
But, if you come from a unist background and want to deal with JavaScript,
or want to use unist utilities with JavaScript, this helps a lot.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install esast-util-from-estree
```

In Deno with [`esm.sh`][esmsh]:

```js
import {fromEstree} from 'https://esm.sh/esast-util-from-estree@2'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {fromEstree} from 'https://esm.sh/esast-util-from-estree@2?bundle'
</script>
```

## Use

```js
import {parse} from 'acorn'
import {fromEstree} from './index.js'

// Make acorn support comments and positional info.
/** @type {Array<import('acorn').Comment>} */
const comments = []
/** @type {import('estree').Program} */
// @ts-expect-error: acorn looks like estree.
const estree = parse(
  'export function x() { /* Something senseless */ console.log(/(?:)/ + 1n) }',
  {
    sourceType: 'module',
    ecmaVersion: 'latest',
    locations: true,
    onComment: comments
  }
)
estree.comments = comments

const esast = fromEstree(estree)

console.log(esast)
```

Yields:

```js
{
  type: 'Program',
  body: [
    {
      type: 'ExportNamedDeclaration',
      declaration: [Object],
      specifiers: [],
      source: null,
      position: [Object]
    }
  ],
  sourceType: 'module',
  comments: [
    {
      type: 'Block',
      value: ' Something senseless ',
      position: [Object]
    }
  ],
  position: {
    start: {line: 1, column: 1, offset: 0},
    end: {line: 1, column: 75, offset: 74}
  }
}
```

## API

This package exports the identifier [`fromEstree`][api-from-estree].
There is no default export.

### `fromEstree(estree[, options])`

Turn an estree into an esast.

###### Parameters

*   `estree` ([`EstreeNode`][estree])
    — estree
*   `options` ([`Options`][api-options], optional)
    — configuration

###### Returns

Clean clone of `estree` ([`UnistNode`][esast]).

### `Options`

Configuration (TypeScript Type).

###### Fields

*   `dirty` (`boolean`, default: `false`)
    — leave discouraged fields in the tree

## Types

This package is fully typed with [TypeScript][].
It exports the additional type [`Options`][api-options].

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`esast-util-from-estree@^2`, compatible with Node.js 16.

## Contribute

See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
ways to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definition -->

[build-badge]: https://github.com/syntax-tree/esast-util-from-estree/workflows/main/badge.svg

[build]: https://github.com/syntax-tree/esast-util-from-estree/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/esast-util-from-estree.svg

[coverage]: https://codecov.io/github/syntax-tree/esast-util-from-estree

[downloads-badge]: https://img.shields.io/npm/dm/esast-util-from-estree.svg

[downloads]: https://www.npmjs.com/package/esast-util-from-estree

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=esast-util-from-estree

[size]: https://bundlejs.com/?q=esast-util-from-estree

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/syntax-tree/unist/discussions

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[typescript]: https://www.typescriptlang.org

[license]: license

[author]: https://wooorm.com

[health]: https://github.com/syntax-tree/.github

[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md

[support]: https://github.com/syntax-tree/.github/blob/main/support.md

[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md

[esast]: https://github.com/syntax-tree/esast

[estree]: https://github.com/estree/estree

[api-from-estree]: #fromestreeestree-options

[api-options]: #options


---

# esast-util-from-js

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[esast][] (and [estree][]) utility to parse trees from JavaScript.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`fromJs(value[, options])`](#fromjsvalue-options)
    *   [`Options`](#options)
    *   [`Plugin`](#plugin)
    *   [`Value`](#value)
    *   [`Version`](#version-1)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package is a utility that turns a string of JavaScript into an esast
(estree with some extra cleanliness) syntax tree.

## When should I use this?

You can use this utility when you want to deal with ASTs of JavaScript
combined with other [unist][] and [`vfile`][vfile] things.
You can use [`acorn`][acorn] itself if you don’t care about unified.

The utility [`estree-util-to-js`][estree-util-to-js] does the inverse of this
utility.
It turns the tree into a string of JavaScript.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install esast-util-from-js
```

In Deno with [`esm.sh`][esmsh]:

```js
import {fromJs} from 'https://esm.sh/esast-util-from-js@2'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {fromJs} from 'https://esm.sh/esast-util-from-js@2?bundle'
</script>
```

## Use

```js
import fs from 'node:fs/promises'
import {fromJs} from 'esast-util-from-js'

const tree = fromJs(await fs.readFile('example.js'), {module: true})

console.log(tree)
```

Yields:

```js
{
  type: 'Program',
  body: [
    {
      type: 'ImportDeclaration',
      specifiers: [Array],
      source: [Object],
      position: [Object]
    },
    {
      type: 'ImportDeclaration',
      specifiers: [Array],
      source: [Object],
      position: [Object]
    },
    {
      type: 'VariableDeclaration',
      declarations: [Array],
      kind: 'const',
      position: [Object]
    },
    {
      type: 'ExpressionStatement',
      expression: [Object],
      position: [Object]
    }
  ],
  sourceType: 'module',
  comments: [],
  position: {
    start: {line: 1, column: 1, offset: 0},
    end: {line: 7, column: 1, offset: 157}
  }
}
```

## API

This package exports the identifier [`fromJs`][api-from-js].
There is no default export.

### `fromJs(value[, options])`

Parse JavaScript to an esast.

###### Parameters

*   `value` ([`Value`][api-value])
    — serialized JavaScript to parse
*   `options` ([`Options`][api-options], optional)
    — configuration

###### Returns

Tree ([`Node`][node]).

###### Throws

When the JavaScript cannot be parsed with `acorn`, a
[`VFileMessage`][vfile-message] is thrown.

This can for example happen when passing modern syntax (you could maybe use a
newer `version`, or it might be that the syntax is not yet supported), or just
otherwise invalid JavaScript (you might need a plugin).

### `Options`

Configuration (TypeScript type).

##### Fields

###### `version`

JavaScript version ([`Version`][api-version], default: `'latest'`).

When a number, must be a year in the range `2015` and `2023` (both including).
`'latest'` is the same as passing the latest supported year.

> ☢️ **Danger**: `'latest'` is a sliding thing, you could consider it as
> breaking semver.
> Pass an actual year to lock that down.

###### `module`

Whether this is a module (ESM) or a script (`boolean`, default: `false`).

###### `allowReturnOutsideFunction`

Whether a return statement is allowed in the top scope (`boolean`, default:
`false`).

###### `allowImportExportEverywhere`

Whether import/export statements are allowed in the every scope (`boolean`,
default: `false`).

###### `allowAwaitOutsideFunction`

Whether `await` is allowed in the top scope (`boolean`, default: depends).
Defaults to `version >= 2022`.

###### `allowSuperOutsideMethod`

Whether `super` is allowed outside methods (`boolean`, default: `false`).

###### `allowHashBang`

Whether a shell hasbang is allowed (`boolean`, default: `false`).

###### `plugins`

List of acorn plugins ([`Array<Plugin>`][api-plugin], default: `[]`).
Examples are [`acorn-jsx`][acorn-jsx] and [`acorn-stage3`][acorn-stage3].

### `Plugin`

Acorn plugin (TypeScript type).

###### Type

```ts
type Plugin = (Parser: ParserClass) => ParserClass
```

### `Value`

Input value (TypeScript type).

When a typed array, must be UTF-8.

###### Type

```ts
type Value = Uint8Array | string
```

### `Version`

JavaScript version (TypeScript type).

`'latest'` is equivalent to the latest supported year.

###### Type

```ts
type Version = 2015 | 2016 | 2017 | 2018 | 2019 | 2020 | 2021 | 2022 | 2023 | 'latest'
```

## Types

This package is fully typed with [TypeScript][].
It exports the additional types [`Options`][api-options],
[`Plugin`][api-plugin],
[`Value`][api-value], and
[`Version`][api-version].

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, `esast-util-from-js@^2`,
compatible with Node.js 16.

## Contribute

See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
ways to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/syntax-tree/esast-util-from-js/workflows/main/badge.svg

[build]: https://github.com/syntax-tree/esast-util-from-js/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/esast-util-from-js.svg

[coverage]: https://codecov.io/github/syntax-tree/esast-util-from-js

[downloads-badge]: https://img.shields.io/npm/dm/esast-util-from-js.svg

[downloads]: https://www.npmjs.com/package/esast-util-from-js

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=esast-util-from-js

[size]: https://bundlejs.com/?q=esast-util-from-js

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/syntax-tree/unist/discussions

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[typescript]: https://www.typescriptlang.org

[license]: license

[author]: https://wooorm.com

[health]: https://github.com/syntax-tree/.github

[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md

[support]: https://github.com/syntax-tree/.github/blob/main/support.md

[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md

[esast]: https://github.com/syntax-tree/esast

[node]: https://github.com/syntax-tree/esast#node

[estree]: https://github.com/estree/estree

[unist]: https://github.com/syntax-tree/unist

[vfile]: https://github.com/vfile/vfile

[acorn]: https://github.com/acornjs/acorn

[acorn-jsx]: https://github.com/acornjs/acorn-jsx

[acorn-stage3]: https://github.com/acornjs/acorn-stage3

[estree-util-to-js]: https://github.com/syntax-tree/estree-util-to-js

[vfile-message]: https://github.com/vfile/vfile-message

[api-from-js]: #fromjsvalue-options

[api-options]: #options

[api-plugin]: #plugin

[api-value]: #value

[api-version]: #version-1


---

# escalade [![CI](https://github.com/lukeed/escalade/workflows/CI/badge.svg)](https://github.com/lukeed/escalade/actions) [![licenses](https://licenses.dev/b/npm/escalade)](https://licenses.dev/npm/escalade) [![codecov](https://badgen.now.sh/codecov/c/github/lukeed/escalade)](https://codecov.io/gh/lukeed/escalade)

> A tiny (183B to 210B) and [fast](#benchmarks) utility to ascend parent directories

With [escalade](https://en.wikipedia.org/wiki/Escalade), you can scale parent directories until you've found what you're looking for.<br>Given an input file or directory, `escalade` will continue executing your callback function until either:

1) the callback returns a truthy value
2) `escalade` has reached the system root directory (eg, `/`)

> **Important:**<br>Please note that `escalade` only deals with direct ancestry – it will not dive into parents' sibling directories.

---

**Notice:** As of v3.1.0, `escalade` now includes [Deno support](http://deno.land/x/escalade)! Please see [Deno Usage](#deno) below.

---

## Install

```
$ npm install --save escalade
```


## Modes

There are two "versions" of `escalade` available:

#### "async"
> **Node.js:** >= 8.x<br>
> **Size (gzip):** 210 bytes<br>
> **Availability:** [CommonJS](https://unpkg.com/escalade/dist/index.js), [ES Module](https://unpkg.com/escalade/dist/index.mjs)

This is the primary/default mode. It makes use of `async`/`await` and [`util.promisify`](https://nodejs.org/api/util.html#util_util_promisify_original).

#### "sync"
> **Node.js:** >= 6.x<br>
> **Size (gzip):** 183 bytes<br>
> **Availability:** [CommonJS](https://unpkg.com/escalade/sync/index.js), [ES Module](https://unpkg.com/escalade/sync/index.mjs)

This is the opt-in mode, ideal for scenarios where `async` usage cannot be supported.


## Usage

***Example Structure***

```
/Users/lukeed
  └── oss
    ├── license
    └── escalade
      ├── package.json
      └── test
        └── fixtures
          ├── index.js
          └── foobar
            └── demo.js
```

***Example Usage***

```js
//~> demo.js
import { join } from 'path';
import escalade from 'escalade';

const input = join(__dirname, 'demo.js');
// or: const input = __dirname;

const pkg = await escalade(input, (dir, names) => {
  console.log('~> dir:', dir);
  console.log('~> names:', names);
  console.log('---');

  if (names.includes('package.json')) {
    // will be resolved into absolute
    return 'package.json';
  }
});

//~> dir: /Users/lukeed/oss/escalade/test/fixtures/foobar
//~> names: ['demo.js']
//---
//~> dir: /Users/lukeed/oss/escalade/test/fixtures
//~> names: ['index.js', 'foobar']
//---
//~> dir: /Users/lukeed/oss/escalade/test
//~> names: ['fixtures']
//---
//~> dir: /Users/lukeed/oss/escalade
//~> names: ['package.json', 'test']
//---

console.log(pkg);
//=> /Users/lukeed/oss/escalade/package.json

// Now search for "missing123.txt"
// (Assume it doesn't exist anywhere!)
const missing = await escalade(input, (dir, names) => {
  console.log('~> dir:', dir);
  return names.includes('missing123.txt') && 'missing123.txt';
});

//~> dir: /Users/lukeed/oss/escalade/test/fixtures/foobar
//~> dir: /Users/lukeed/oss/escalade/test/fixtures
//~> dir: /Users/lukeed/oss/escalade/test
//~> dir: /Users/lukeed/oss/escalade
//~> dir: /Users/lukeed/oss
//~> dir: /Users/lukeed
//~> dir: /Users
//~> dir: /

console.log(missing);
//=> undefined
```

> **Note:** To run the above example with "sync" mode, import from `escalade/sync` and remove the `await` keyword.


## API

### escalade(input, callback)
Returns: `string|void` or `Promise<string|void>`

When your `callback` locates a file, `escalade` will resolve/return with an absolute path.<br>
If your `callback` was never satisfied, then `escalade` will resolve/return with nothing (undefined).

> **Important:**<br>The `sync` and `async` versions share the same API.<br>The **only** difference is that `sync` is not Promise-based.

#### input
Type: `string`

The path from which to start ascending.

This may be a file or a directory path.<br>However, when `input` is a file, `escalade` will begin with its parent directory.

> **Important:** Unless given an absolute path, `input` will be resolved from `process.cwd()` location.

#### callback
Type: `Function`

The callback to execute for each ancestry level. It always is given two arguments:

1) `dir` - an absolute path of the current parent directory
2) `names` - a list (`string[]`) of contents _relative to_ the `dir` parent

> **Note:** The `names` list can contain names of files _and_ directories.

When your callback returns a _falsey_ value, then `escalade` will continue with `dir`'s parent directory, re-invoking your callback with new argument values.

When your callback returns a string, then `escalade` stops iteration immediately.<br>
If the string is an absolute path, then it's left as is. Otherwise, the string is resolved into an absolute path _from_ the `dir` that housed the satisfying condition.

> **Important:** Your `callback` can be a `Promise/AsyncFunction` when using the "async" version of `escalade`.

## Benchmarks

> Running on Node.js v10.13.0

```
# Load Time
  find-up         3.891ms
  escalade        0.485ms
  escalade/sync   0.309ms

# Levels: 6 (target = "foo.txt"):
  find-up          x 24,856 ops/sec ±6.46% (55 runs sampled)
  escalade         x 73,084 ops/sec ±4.23% (73 runs sampled)
  find-up.sync     x  3,663 ops/sec ±1.12% (83 runs sampled)
  escalade/sync    x  9,360 ops/sec ±0.62% (88 runs sampled)

# Levels: 12 (target = "package.json"):
  find-up          x 29,300 ops/sec ±10.68% (70 runs sampled)
  escalade         x 73,685 ops/sec ± 5.66% (66 runs sampled)
  find-up.sync     x  1,707 ops/sec ± 0.58% (91 runs sampled)
  escalade/sync    x  4,667 ops/sec ± 0.68% (94 runs sampled)

# Levels: 18 (target = "missing123.txt"):
  find-up          x 21,818 ops/sec ±17.37% (14 runs sampled)
  escalade         x 67,101 ops/sec ±21.60% (20 runs sampled)
  find-up.sync     x  1,037 ops/sec ± 2.86% (88 runs sampled)
  escalade/sync    x  1,248 ops/sec ± 0.50% (93 runs sampled)
```

## Deno

As of v3.1.0, `escalade` is available on the Deno registry.

Please note that the [API](#api) is identical and that there are still [two modes](#modes) from which to choose:

```ts
// Choose "async" mode
import escalade from 'https://deno.land/escalade/async.ts';

// Choose "sync" mode
import escalade from 'https://deno.land/escalade/sync.ts';
```

> **Important:** The `allow-read` permission is required!


## Related

- [premove](https://github.com/lukeed/premove) - A tiny (247B) utility to remove items recursively
- [totalist](https://github.com/lukeed/totalist) - A tiny (195B to 224B) utility to recursively list all (total) files in a directory
- [mk-dirs](https://github.com/lukeed/mk-dirs) - A tiny (420B) utility to make a directory and its parents, recursively

## License

MIT © [Luke Edwards](https://lukeed.com)


---

<h1>
	<img src="logo.jpg" width="1280" alt="escape-goat">
</h1>

> Escape a string for use in HTML or the inverse

## Install

```
$ npm install escape-goat
```

## Usage

```js
import {htmlEscape, htmlUnescape} from 'escape-goat';

htmlEscape('🦄 & 🐐');
//=> '🦄 &amp; 🐐'

htmlUnescape('🦄 &amp; 🐐');
//=> '🦄 & 🐐'

htmlEscape('Hello <em>World</em>');
//=> 'Hello &lt;em&gt;World&lt;/em&gt;'

const url = 'https://sindresorhus.com?x="🦄"';

htmlEscape`<a href="${url}">Unicorn</a>`;
//=> '<a href="https://sindresorhus.com?x=&quot;🦄&quot;">Unicorn</a>'

const escapedUrl = 'https://sindresorhus.com?x=&quot;🦄&quot;';

htmlUnescape`URL from HTML: ${escapedUrl}`;
//=> 'URL from HTML: https://sindresorhus.com?x="🦄"'
```

## API

### htmlEscape(string)

Escapes the following characters in the given `string` argument: `&` `<` `>` `"` `'`

The function also works as a [tagged template literal](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Template_literals#Tagged_template_literals) that escapes interpolated values.

### htmlUnescape(htmlString)

Unescapes the following HTML entities in the given `htmlString` argument: `&amp;` `&lt;` `&gt;` `&quot;` `&#39;`

The function also works as a [tagged template literal](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Template_literals#Tagged_template_literals) that unescapes interpolated values.

## Tip

Ensure you always quote your HTML attributes to prevent possible [XSS](https://en.wikipedia.org/wiki/Cross-site_scripting).

## FAQ

### Why yet another HTML escaping package?

I couldn't find one I liked that was tiny, well-tested, and had both escape and unescape methods.


---


# escape-html

  Escape string for use in HTML

## Example

```js
var escape = require('escape-html');
var html = escape('foo & bar');
// -> foo &amp; bar
```

## Benchmark

```
$ npm run-script bench

> escape-html@1.0.3 bench nodejs-escape-html
> node benchmark/index.js


  http_parser@1.0
  node@0.10.33
  v8@3.14.5.9
  ares@1.9.0-DEV
  uv@0.10.29
  zlib@1.2.3
  modules@11
  openssl@1.0.1j

  1 test completed.
  2 tests completed.
  3 tests completed.

  no special characters    x 19,435,271 ops/sec ±0.85% (187 runs sampled)
  single special character x  6,132,421 ops/sec ±0.67% (194 runs sampled)
  many special characters  x  3,175,826 ops/sec ±0.65% (193 runs sampled)
```

## License

  MIT

---

# escape-string-regexp [![Build Status](https://travis-ci.org/sindresorhus/escape-string-regexp.svg?branch=master)](https://travis-ci.org/sindresorhus/escape-string-regexp)

> Escape RegExp special characters

## Install

```
$ npm install escape-string-regexp
```

## Usage

```js
const escapeStringRegexp = require('escape-string-regexp');

const escapedString = escapeStringRegexp('How much $ for a 🦄?');
//=> 'How much \\$ for a 🦄\\?'

new RegExp(escapedString);
```

You can also use this to escape a string that is inserted into the middle of a regex, for example, into a character class.

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-escape-string-regexp?utm_source=npm-escape-string-regexp&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

v5.1.1 - September 12, 2020

* [`9b528d7`](https://github.com/eslint/eslint-scope/commit/9b528d778c381718c12dabfb7f1c0e0dc6b36e49) Upgrade: esrecurse version to ^4.3.0 (#64) (Timofey Kachalov)
* [`f758bbc`](https://github.com/eslint/eslint-scope/commit/f758bbc3d49b9b9ea2289a5d6a6bba8dcf2c4903) Chore: fix definiton -> definition typo in comments (#63) (Kevin Kirsche)
* [`7513734`](https://github.com/eslint/eslint-scope/commit/751373473375b3f2edc4eaf1c8d2763d8435bb72) Chore: move to GitHub Actions (#62) (Kai Cataldo)

v5.1.0 - June 4, 2020

* [`d4a3764`](https://github.com/eslint/eslint-scope/commit/d4a376434b16289c1a428d7e304576e997520873) Update: support new export syntax (#56) (Toru Nagashima)

v5.0.0 - July 20, 2019

* [`e9fa22e`](https://github.com/eslint/eslint-scope/commit/e9fa22ea412c26cf2761fa98af7e715644bdb464) Upgrade: update dependencies after dropping support for Node <8 (#53) (Kai Cataldo)
* [`ee9f7c1`](https://github.com/eslint/eslint-scope/commit/ee9f7c12721aa195ba7e0e69551f49bfdb479951) Breaking: drop support for Node v6 (#54) (Kai Cataldo)

v4.0.3 - March 15, 2019

* [`299df64`](https://github.com/eslint/eslint-scope/commit/299df64bdafb30b4d9372e4b7af0cf51a3818c4a) Fix: arrow function scope strictness (take 2) (#52) (futpib)

v4.0.2 - March 1, 2019

* [`c925600`](https://github.com/eslint/eslint-scope/commit/c925600a684ae0f71b96f85339437a43b4d50d99) Revert "Fix: Arrow function scope strictness (fixes #49) (#50)" (#51) (Teddy Katz)

v4.0.1 - March 1, 2019

* [`2533966`](https://github.com/eslint/eslint-scope/commit/2533966faf317df5a3847fab937ba462c16808b8) Fix: Arrow function scope strictness (fixes #49) (#50) (futpib)
* [`0cbeea5`](https://github.com/eslint/eslint-scope/commit/0cbeea51dfb66ab88ea34b0e3b4ad5e6cc210f2f) Chore: add supported Node.js versions to CI (#47) (Kai Cataldo)
* [`b423057`](https://github.com/eslint/eslint-scope/commit/b42305760638b8edf4667acf1445e450869bd983) Upgrade: eslint-release@1.0.0 (#46) (Teddy Katz)

v4.0.0 - June 21, 2018



v4.0.0-rc.0 - June 9, 2018

* 3b919b8 Build: Adding rc release script to package.json (#38) (Kevin Partington)
* 137732a Chore: avoid creating package-lock.json files (#37) (Teddy Katz)

v4.0.0-alpha.0 - April 27, 2018

* 7cc3769 Upgrade: eslint-release ^0.11.1 (#36) (Teddy Katz)
* c9f6967 Breaking: remove TDZScope (refs eslint/eslint#10245) (#35) (Toru Nagashima)
* 982a71f Fix: wrong resolution about default parameters (#33) (Toru Nagashima)
* 57889f1 Docs: Remove extra header line from LICENSE (#32) (Gyandeep Singh)

v3.7.1 - April 12, 2017

* ced6262 Fix: restore previous Scope API exports from escope (#31) (Vitor Balocco)
* 5c3d966 Fix: Remove and Modify tests that contain invalid ES6 syntax (#29) (Reyad Attiyat)

v3.7.0 - March 17, 2017

* 9e27835 Chore: Add files section to package.json (#24) (Ilya Volodin)
* 3e4d123 Upgrade: eslint-config-eslint to 4.0.0 (#21) (Teddy Katz)
* 38c50fb Chore: Rename src to lib and test to tests (#20) (Corbin Uselton)
* f4cd920 Chore: Remove esprima (#19) (Corbin Uselton)
* f81fad5 Revert "Chore: Remove esprima" (#18) (James Henry)
* 31b0085 Chore: Remove es6-map and es6-weakmap as they are included in node4 (#10) (#13) (Corbin Uselton)
* 12a1ca1 Add Makefile.js and eslint (#15) (Reyad Attiyat)
* 7d23f8e Chore: Remove es6-map and es6-weakmap as they are included in node4 (#10) (Corbin Uselton)
* 019441e Chore: Convert to ES6 that is supported on Node 4, commonjs modules and remove Babel (#14) (Corbin Uselton)
* c647f65 Update: Add check for node.body in referencer (#2) (Corbin Uselton)
* eb5c9db Remove browserify and jsdoc (#12) (Corbin Uselton)
* cf38df0 Chore: Update README.md (#3) (James Henry)
* 8a142ca Chore: Add eslint-release scripts (#6) (James Henry)
* e60d8cb Chore: Remove unused bower.json (#5) (James Henry)
* 049c545 Chore: Fix tests for eslint-scope (#4) (James Henry)
* f026aab Chore: Update package.json for eslint fork (#1) (James Henry)
* a94d281 Chore: Update license with JSF copyright (Nicholas C. Zakas)



---

# ESLint Scope

ESLint Scope is the [ECMAScript](http://www.ecma-international.org/publications/standards/Ecma-262.htm) scope analyzer used in ESLint. It is a fork of [escope](http://github.com/estools/escope).

## Usage

Install:

```
npm i eslint-scope --save
```

Example:

```js
var eslintScope = require('eslint-scope');
var espree = require('espree');
var estraverse = require('estraverse');

var ast = espree.parse(code);
var scopeManager = eslintScope.analyze(ast);

var currentScope = scopeManager.acquire(ast);   // global scope

estraverse.traverse(ast, {
    enter: function(node, parent) {
        // do stuff

        if (/Function/.test(node.type)) {
            currentScope = scopeManager.acquire(node);  // get current function scope
        }
    },
    leave: function(node, parent) {
        if (/Function/.test(node.type)) {
            currentScope = currentScope.upper;  // set to parent scope
        }

        // do stuff
    }
});
```

## Contributing

Issues and pull requests will be triaged and responded to as quickly as possible. We operate under the [ESLint Contributor Guidelines](http://eslint.org/docs/developer-guide/contributing), so please be sure to read them before contributing. If you're not sure where to dig in, check out the [issues](https://github.com/eslint/eslint-scope/issues).

## Build Commands

* `npm test` - run all linting and tests
* `npm run lint` - run all linting

## License

ESLint Scope is licensed under a permissive BSD 2-clause license.


---

[![NPM version](https://img.shields.io/npm/v/esprima.svg)](https://www.npmjs.com/package/esprima)
[![npm download](https://img.shields.io/npm/dm/esprima.svg)](https://www.npmjs.com/package/esprima)
[![Build Status](https://img.shields.io/travis/jquery/esprima/master.svg)](https://travis-ci.org/jquery/esprima)
[![Coverage Status](https://img.shields.io/codecov/c/github/jquery/esprima/master.svg)](https://codecov.io/github/jquery/esprima)

**Esprima** ([esprima.org](http://esprima.org), BSD license) is a high performance,
standard-compliant [ECMAScript](http://www.ecma-international.org/publications/standards/Ecma-262.htm)
parser written in ECMAScript (also popularly known as
[JavaScript](https://en.wikipedia.org/wiki/JavaScript)).
Esprima is created and maintained by [Ariya Hidayat](https://twitter.com/ariyahidayat),
with the help of [many contributors](https://github.com/jquery/esprima/contributors).

### Features

- Full support for ECMAScript 2017 ([ECMA-262 8th Edition](http://www.ecma-international.org/publications/standards/Ecma-262.htm))
- Sensible [syntax tree format](https://github.com/estree/estree/blob/master/es5.md) as standardized by [ESTree project](https://github.com/estree/estree)
- Experimental support for [JSX](https://facebook.github.io/jsx/), a syntax extension for [React](https://facebook.github.io/react/)
- Optional tracking of syntax node location (index-based and line-column)
- [Heavily tested](http://esprima.org/test/ci.html) (~1500 [unit tests](https://github.com/jquery/esprima/tree/master/test/fixtures) with [full code coverage](https://codecov.io/github/jquery/esprima))

### API

Esprima can be used to perform [lexical analysis](https://en.wikipedia.org/wiki/Lexical_analysis) (tokenization) or [syntactic analysis](https://en.wikipedia.org/wiki/Parsing) (parsing) of a JavaScript program.

A simple example on Node.js REPL:

```javascript
> var esprima = require('esprima');
> var program = 'const answer = 42';

> esprima.tokenize(program);
[ { type: 'Keyword', value: 'const' },
  { type: 'Identifier', value: 'answer' },
  { type: 'Punctuator', value: '=' },
  { type: 'Numeric', value: '42' } ]
  
> esprima.parseScript(program);
{ type: 'Program',
  body:
   [ { type: 'VariableDeclaration',
       declarations: [Object],
       kind: 'const' } ],
  sourceType: 'script' }
```

For more information, please read the [complete documentation](http://esprima.org/doc).

---

### Esrecurse [![Build Status](https://travis-ci.org/estools/esrecurse.svg?branch=master)](https://travis-ci.org/estools/esrecurse)

Esrecurse ([esrecurse](https://github.com/estools/esrecurse)) is
[ECMAScript](https://www.ecma-international.org/publications/standards/Ecma-262.htm)
recursive traversing functionality.

### Example Usage

The following code will output all variables declared at the root of a file.

```javascript
esrecurse.visit(ast, {
    XXXStatement: function (node) {
        this.visit(node.left);
        // do something...
        this.visit(node.right);
    }
});
```

We can use `Visitor` instance.

```javascript
var visitor = new esrecurse.Visitor({
    XXXStatement: function (node) {
        this.visit(node.left);
        // do something...
        this.visit(node.right);
    }
});

visitor.visit(ast);
```

We can inherit `Visitor` instance easily.

```javascript
class Derived extends esrecurse.Visitor {
    constructor()
    {
        super(null);
    }

    XXXStatement(node) {
    }
}
```

```javascript
function DerivedVisitor() {
    esrecurse.Visitor.call(/* this for constructor */  this  /* visitor object automatically becomes this. */);
}
util.inherits(DerivedVisitor, esrecurse.Visitor);
DerivedVisitor.prototype.XXXStatement = function (node) {
    this.visit(node.left);
    // do something...
    this.visit(node.right);
};
```

And you can invoke default visiting operation inside custom visit operation.

```javascript
function DerivedVisitor() {
    esrecurse.Visitor.call(/* this for constructor */  this  /* visitor object automatically becomes this. */);
}
util.inherits(DerivedVisitor, esrecurse.Visitor);
DerivedVisitor.prototype.XXXStatement = function (node) {
    // do something...
    this.visitChildren(node);
};
```

The `childVisitorKeys` option does customize the behaviour of `this.visitChildren(node)`.
We can use user-defined node types.

```javascript
// This tree contains a user-defined `TestExpression` node.
var tree = {
    type: 'TestExpression',

    // This 'argument' is the property containing the other **node**.
    argument: {
        type: 'Literal',
        value: 20
    },

    // This 'extended' is the property not containing the other **node**.
    extended: true
};
esrecurse.visit(
    ast,
    {
        Literal: function (node) {
            // do something...
        }
    },
    {
        // Extending the existing traversing rules.
        childVisitorKeys: {
            // TargetNodeName: [ 'keys', 'containing', 'the', 'other', '**node**' ]
            TestExpression: ['argument']
        }
    }
);
```

We can use the `fallback` option as well.
If the `fallback` option is `"iteration"`, `esrecurse` would visit all enumerable properties of unknown nodes.
Please note circular references cause the stack overflow. AST might have circular references in additional properties for some purpose (e.g. `node.parent`).

```javascript
esrecurse.visit(
    ast,
    {
        Literal: function (node) {
            // do something...
        }
    },
    {
        fallback: 'iteration'
    }
);
```

If the `fallback` option is a function, `esrecurse` calls this function to determine the enumerable properties of unknown nodes.
Please note circular references cause the stack overflow. AST might have circular references in additional properties for some purpose (e.g. `node.parent`).

```javascript
esrecurse.visit(
    ast,
    {
        Literal: function (node) {
            // do something...
        }
    },
    {
        fallback: function (node) {
            return Object.keys(node).filter(function(key) {
                return key !== 'argument'
            });
        }
    }
);
```

### License

Copyright (C) 2014 [Yusuke Suzuki](https://github.com/Constellation)
 (twitter: [@Constellation](https://twitter.com/Constellation)) and other contributors.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

  * Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.

  * Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in the
    documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


---

### Estraverse [![Build Status](https://secure.travis-ci.org/estools/estraverse.svg)](http://travis-ci.org/estools/estraverse)

Estraverse ([estraverse](http://github.com/estools/estraverse)) is
[ECMAScript](http://www.ecma-international.org/publications/standards/Ecma-262.htm)
traversal functions from [esmangle project](http://github.com/estools/esmangle).

### Documentation

You can find usage docs at [wiki page](https://github.com/estools/estraverse/wiki/Usage).

### Example Usage

The following code will output all variables declared at the root of a file.

```javascript
estraverse.traverse(ast, {
    enter: function (node, parent) {
        if (node.type == 'FunctionExpression' || node.type == 'FunctionDeclaration')
            return estraverse.VisitorOption.Skip;
    },
    leave: function (node, parent) {
        if (node.type == 'VariableDeclarator')
          console.log(node.id.name);
    }
});
```

We can use `this.skip`, `this.remove` and `this.break` functions instead of using Skip, Remove and Break.

```javascript
estraverse.traverse(ast, {
    enter: function (node) {
        this.break();
    }
});
```

And estraverse provides `estraverse.replace` function. When returning node from `enter`/`leave`, current node is replaced with it.

```javascript
result = estraverse.replace(tree, {
    enter: function (node) {
        // Replace it with replaced.
        if (node.type === 'Literal')
            return replaced;
    }
});
```

By passing `visitor.keys` mapping, we can extend estraverse traversing functionality.

```javascript
// This tree contains a user-defined `TestExpression` node.
var tree = {
    type: 'TestExpression',

    // This 'argument' is the property containing the other **node**.
    argument: {
        type: 'Literal',
        value: 20
    },

    // This 'extended' is the property not containing the other **node**.
    extended: true
};
estraverse.traverse(tree, {
    enter: function (node) { },

    // Extending the existing traversing rules.
    keys: {
        // TargetNodeName: [ 'keys', 'containing', 'the', 'other', '**node**' ]
        TestExpression: ['argument']
    }
});
```

By passing `visitor.fallback` option, we can control the behavior when encountering unknown nodes.

```javascript
// This tree contains a user-defined `TestExpression` node.
var tree = {
    type: 'TestExpression',

    // This 'argument' is the property containing the other **node**.
    argument: {
        type: 'Literal',
        value: 20
    },

    // This 'extended' is the property not containing the other **node**.
    extended: true
};
estraverse.traverse(tree, {
    enter: function (node) { },

    // Iterating the child **nodes** of unknown nodes.
    fallback: 'iteration'
});
```

When `visitor.fallback` is a function, we can determine which keys to visit on each node.

```javascript
// This tree contains a user-defined `TestExpression` node.
var tree = {
    type: 'TestExpression',

    // This 'argument' is the property containing the other **node**.
    argument: {
        type: 'Literal',
        value: 20
    },

    // This 'extended' is the property not containing the other **node**.
    extended: true
};
estraverse.traverse(tree, {
    enter: function (node) { },

    // Skip the `argument` property of each node
    fallback: function(node) {
        return Object.keys(node).filter(function(key) {
            return key !== 'argument';
        });
    }
});
```

### License

Copyright (C) 2012-2016 [Yusuke Suzuki](http://github.com/Constellation)
 (twitter: [@Constellation](http://twitter.com/Constellation)) and other contributors.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

  * Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.

  * Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in the
    documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


---

### Estraverse [![Build Status](https://secure.travis-ci.org/estools/estraverse.svg)](http://travis-ci.org/estools/estraverse)

Estraverse ([estraverse](http://github.com/estools/estraverse)) is
[ECMAScript](http://www.ecma-international.org/publications/standards/Ecma-262.htm)
traversal functions from [esmangle project](http://github.com/estools/esmangle).

### Documentation

You can find usage docs at [wiki page](https://github.com/estools/estraverse/wiki/Usage).

### Example Usage

The following code will output all variables declared at the root of a file.

```javascript
estraverse.traverse(ast, {
    enter: function (node, parent) {
        if (node.type == 'FunctionExpression' || node.type == 'FunctionDeclaration')
            return estraverse.VisitorOption.Skip;
    },
    leave: function (node, parent) {
        if (node.type == 'VariableDeclarator')
          console.log(node.id.name);
    }
});
```

We can use `this.skip`, `this.remove` and `this.break` functions instead of using Skip, Remove and Break.

```javascript
estraverse.traverse(ast, {
    enter: function (node) {
        this.break();
    }
});
```

And estraverse provides `estraverse.replace` function. When returning node from `enter`/`leave`, current node is replaced with it.

```javascript
result = estraverse.replace(tree, {
    enter: function (node) {
        // Replace it with replaced.
        if (node.type === 'Literal')
            return replaced;
    }
});
```

By passing `visitor.keys` mapping, we can extend estraverse traversing functionality.

```javascript
// This tree contains a user-defined `TestExpression` node.
var tree = {
    type: 'TestExpression',

    // This 'argument' is the property containing the other **node**.
    argument: {
        type: 'Literal',
        value: 20
    },

    // This 'extended' is the property not containing the other **node**.
    extended: true
};
estraverse.traverse(tree, {
    enter: function (node) { },

    // Extending the existing traversing rules.
    keys: {
        // TargetNodeName: [ 'keys', 'containing', 'the', 'other', '**node**' ]
        TestExpression: ['argument']
    }
});
```

By passing `visitor.fallback` option, we can control the behavior when encountering unknown nodes.

```javascript
// This tree contains a user-defined `TestExpression` node.
var tree = {
    type: 'TestExpression',

    // This 'argument' is the property containing the other **node**.
    argument: {
        type: 'Literal',
        value: 20
    },

    // This 'extended' is the property not containing the other **node**.
    extended: true
};
estraverse.traverse(tree, {
    enter: function (node) { },

    // Iterating the child **nodes** of unknown nodes.
    fallback: 'iteration'
});
```

When `visitor.fallback` is a function, we can determine which keys to visit on each node.

```javascript
// This tree contains a user-defined `TestExpression` node.
var tree = {
    type: 'TestExpression',

    // This 'argument' is the property containing the other **node**.
    argument: {
        type: 'Literal',
        value: 20
    },

    // This 'extended' is the property not containing the other **node**.
    extended: true
};
estraverse.traverse(tree, {
    enter: function (node) { },

    // Skip the `argument` property of each node
    fallback: function(node) {
        return Object.keys(node).filter(function(key) {
            return key !== 'argument';
        });
    }
});
```

### License

Copyright (C) 2012-2016 [Yusuke Suzuki](http://github.com/Constellation)
 (twitter: [@Constellation](http://twitter.com/Constellation)) and other contributors.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

  * Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.

  * Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in the
    documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


---

# estree-util-attach-comments

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[estree][] utility attach semistandard comment nodes (such as from [acorn][]) to
the nodes in that tree.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`attachComments(tree, comments)`](#attachcommentstree-comments)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package is a utility that you can use to embed comment nodes *inside* a
tree.
This is useful because certain estree parsers give you an array (espree and
acorn) whereas other estree tools expect comments to be embedded on nodes in the
tree.

This package uses one `comments` array where each comment has `leading` and
`trailing` fields, as applied by `acorn`, but does not support the slightly
different non-standard comments made by `espree`.

## When should I use this?

You can use this package when working with comments from Acorn and later working
with a tool such as recast or Babel.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install estree-util-attach-comments
```

In Deno with [`esm.sh`][esmsh]:

```js
import {attachComments} from 'https://esm.sh/estree-util-attach-comments@3'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {attachComments} from 'https://esm.sh/estree-util-attach-comments@3?bundle'
</script>
```

## Use

Say our document `x.js` contains:

```js
/* 1 */ function /* 2 */ a /* 3 */(/* 4 */ b) /* 5 */ {
  /* 6 */ return /* 7 */ b + /* 8 */ 1 /* 9 */
}
```

…and our module `example.js` looks as follows:

```js
import fs from 'node:fs/promises'
import {parse} from 'acorn'
import {attachComments} from 'estree-util-attach-comments'
import recast from 'recast'

const code = String(await fs.readFile('x.js'))
const comments = []
const tree = parse(code, {
  sourceType: 'module',
  ecmaVersion: 'latest',
  onComment: comments
})

attachComments(tree, comments)

console.log(recast.print(tree).code)
```

Yields:

```js
/* 1 */
function /* 2 */
a(
    /* 3 */
    /* 4 */
    b
) /* 5 */
{
    /* 6 */
    return (
        /* 7 */
        b + /* 8 */
        1
    );
}/* 9 */
```

> 👉 **Note**: the lines are added by `recast` in this case.
> And, some of these weird comments are off, but they’re pretty close.

## API

This package exports the identifier [`attachComments`][api-attach-comments].
There is no default export.

### `attachComments(tree, comments)`

Attach semistandard estree comment nodes to the tree.

This mutates the given [`tree`][estree].
It takes `comments`, walks the tree, and adds comments as close as possible
to where they originated.

Comment nodes are given two boolean fields: `leading` (`true` for `/* a */ b`)
and `trailing` (`true` for `a /* b */`).
Both fields are `false` for dangling comments: `[/* a */]`.
This is what `recast` uses too, and is somewhat similar to Babel, which is not
estree but instead uses `leadingComments`, `trailingComments`, and
`innerComments` arrays on nodes.

The algorithm checks any node: even recent (or future) proposals or nonstandard
syntax such as JSX, because it ducktypes to find nodes instead of having a list
of visitor keys.

The algorithm supports `loc` fields (line/column), `range` fields (offsets),
and direct `start` / `end` fields.

###### Parameters

*   `tree` ([`Program`][program])
    — tree to attach to
*   `comments` (`Array<EstreeComment>`)
    — list of comments

###### Returns

Nothing (`undefined`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`estree-util-attach-comments@^3`, compatible with Node.js 16.

## Contribute

See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
ways to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/syntax-tree/estree-util-attach-comments/workflows/main/badge.svg

[build]: https://github.com/syntax-tree/estree-util-attach-comments/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/estree-util-attach-comments.svg

[coverage]: https://codecov.io/github/syntax-tree/estree-util-attach-comments

[downloads-badge]: https://img.shields.io/npm/dm/estree-util-attach-comments.svg

[downloads]: https://www.npmjs.com/package/estree-util-attach-comments

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=estree-util-attach-comments

[size]: https://bundlejs.com/?q=estree-util-attach-comments

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/syntax-tree/unist/discussions

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[typescript]: https://www.typescriptlang.org

[license]: license

[author]: https://wooorm.com

[health]: https://github.com/syntax-tree/.github

[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md

[support]: https://github.com/syntax-tree/.github/blob/main/support.md

[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md

[acorn]: https://github.com/acornjs/acorn

[estree]: https://github.com/estree/estree

[program]: https://github.com/estree/estree/blob/master/es5.md#programs

[api-attach-comments]: #attachcommentstree-comments


---

# estree-util-build-jsx

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[estree][] utility to turn JSX into function calls: `<x />` -> `h('x')`!

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`buildJsx(tree[, options])`](#buildjsxtree-options)
    *   [`Options`](#options)
    *   [`Runtime`](#runtime-1)
*   [Examples](#examples)
    *   [Example: use with Acorn](#example-use-with-acorn)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Related](#related)
*   [Security](#security)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package is a utility that takes an [estree][] (JavaScript) syntax tree as
input that contains embedded JSX nodes (elements, fragments) and turns them into
function calls.

## When should I use this?

If you already have a tree and only need to compile JSX away, use this.
If you have code, use something like [SWC][] or [esbuild][] instead.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install estree-util-build-jsx
```

In Deno with [`esm.sh`][esmsh]:

```js
import {buildJsx} from 'https://esm.sh/estree-util-build-jsx@3'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {buildJsx} from 'https://esm.sh/estree-util-build-jsx@3?bundle'
</script>
```

## Use

Say we have the following `example.jsx`:

```js
import x from 'xastscript'

console.log(
  <album id={123}>
    <name>Born in the U.S.A.</name>
    <artist>Bruce Springsteen</artist>
    <releasedate date="1984-04-06">April 6, 1984</releasedate>
  </album>
)

console.log(
  <>
    {1 + 1}
    <self-closing />
    <x name key="value" key={expression} {...spread} />
  </>
)
```

…and next to it a module `example.js`:

```js
import fs from 'node:fs/promises'
import jsx from 'acorn-jsx'
import {fromJs} from 'esast-util-from-js'
import {buildJsx} from 'estree-util-build-jsx'
import {toJs} from 'estree-util-to-js'

const doc = String(await fs.readFile('example.jsx'))

const tree = fromJs(doc, {module: true, plugins: [jsx()]})

buildJsx(tree, {pragma: 'x', pragmaFrag: 'null'})

console.log(toJs(tree).value)
```

…now running `node example.js` yields:

```js
import x from "xastscript";
console.log(x("album", {
  id: 123
}, x("name", null, "Born in the U.S.A."), x("artist", null, "Bruce Springsteen"), x("releasedate", {
  date: "1984-04-06"
}, "April 6, 1984")));
console.log(x(null, null, 1 + 1, x("self-closing"), x("x", Object.assign({
  name: true,
  key: "value",
  key: expression
}, spread))));
```

## API

This package exports the identifier [`buildJsx`][api-build-jsx].
There is no default export.

### `buildJsx(tree[, options])`

Turn JSX in `tree` into function calls: `<x />` -> `h('x')`!

###### Algorithm

In almost all cases, this utility is the same as the Babel plugin, except that
they work on slightly different syntax trees.

Some differences:

*   no pure annotations things
*   `this` is not a component: `<this>` -> `h('this')`, not `h(this)`
*   namespaces are supported: `<a:b c:d>` -> `h('a:b', {'c:d': true})`,
    which throws by default in Babel or can be turned on with `throwIfNamespace`
*   no `useSpread`, `useBuiltIns`, or `filter` options

###### Parameters

*   `tree` ([`Node`][node])
    — tree to transform (typically [`Program`][program])
*   `options` ([`Options`][api-options], optional)
    — configuration

###### Returns

Nothing (`undefined`).

### `Options`

Configuration (TypeScript type).

> 👉 **Note**: you can also configure `runtime`, `importSource`, `pragma`, and
> `pragmaFrag` from within files through comments.

##### Fields

###### `runtime`

Choose the [runtime][jsx-runtime] ([`Runtime`][api-runtime], default: `'classic'`).

Comment form: `@jsxRuntime theRuntime`.

###### `importSource`

Place to import `jsx`, `jsxs`, `jsxDEV`, and `Fragment` from, when the
effective runtime is automatic (`string`, default: `'react'`).

Comment form: `@jsxImportSource theSource`.

> 👉 **Note**: `/jsx-runtime` or `/jsx-dev-runtime` is appended to this provided
> source.
> In CJS, that can resolve to a file (as in `theSource/jsx-runtime.js`), but for
> ESM an export map needs to be set up to point to files:
>
> ```js
> // …
> "exports": {
>   // …
>   "./jsx-runtime": "./path/to/jsx-runtime.js",
>   "./jsx-dev-runtime": "./path/to/jsx-runtime.js"
>   // …
> ```

###### `pragma`

Identifier or member expression to call when the effective runtime is classic
(`string`, default: `'React.createElement'`).

Comment form: `@jsx identifier`.

###### `pragmaFrag`

Identifier or member expression to use as a symbol for fragments when the
effective runtime is classic (`string`, default: `'React.Fragment'`).

Comment form: `@jsxFrag identifier`.

###### `development`

When in the automatic runtime, whether to import `theSource/jsx-dev-runtime.js`,
use `jsxDEV`, and pass location info when available (`boolean`, default: `false`).

This helps debugging but adds a lot of code that you don’t want in production.

###### `filePath`

File path to the original source file (`string`, example: `'path/to/file.js'`).
Passed in location info to `jsxDEV` when using the automatic runtime with
`development: true`.

### `Runtime`

How to transform JSX (TypeScript type).

###### Type

```ts
type Runtime = 'automatic' | 'classic'
```

## Examples

### Example: use with Acorn

To support configuration from comments in Acorn, those comments have to be in
the program.
This is done by [`espree`][espree] but not automatically by [`acorn`][acorn]:

```js
import {Parser} from 'acorn'
import jsx from 'acorn-jsx'

const doc = '' // To do: get `doc` somehow.

const comments = []
const tree = Parser.extend(jsx()).parse(doc, {onComment: comments})
tree.comments = comments
```

## Types

This package is fully typed with [TypeScript][].
It exports the additional type [`Options`][api-options] and
[`Runtime`][api-runtime].

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, `estree-util-build-jsx@^3`,
compatible with Node.js 166.

## Related

*   [`syntax-tree/hast-util-to-estree`](https://github.com/syntax-tree/hast-util-to-estree)
    — turn [hast](https://github.com/syntax-tree/hast) (HTML) to [estree][]
    JSX
*   [`coderaiser/estree-to-babel`](https://github.com/coderaiser/estree-to-babel)
    — turn [estree][] to Babel trees

## Security

This package is safe.

## Contribute

See [`contributing.md` in `syntax-tree/.github`][contributing] for ways to get
started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/syntax-tree/estree-util-build-jsx/workflows/main/badge.svg

[build]: https://github.com/syntax-tree/estree-util-build-jsx/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/estree-util-build-jsx.svg

[coverage]: https://codecov.io/github/syntax-tree/estree-util-build-jsx

[downloads-badge]: https://img.shields.io/npm/dm/estree-util-build-jsx.svg

[downloads]: https://www.npmjs.com/package/estree-util-build-jsx

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=estree-util-build-jsx

[size]: https://bundlejs.com/?q=estree-util-build-jsx

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/syntax-tree/unist/discussions

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[npm]: https://docs.npmjs.com/cli/install

[esmsh]: https://esm.sh

[license]: license

[author]: https://wooorm.com

[typescript]: https://www.typescriptlang.org

[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md

[support]: https://github.com/syntax-tree/.github/blob/main/support.md

[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md

[acorn]: https://github.com/acornjs/acorn

[estree]: https://github.com/estree/estree

[espree]: https://github.com/eslint/espree

[node]: https://github.com/estree/estree/blob/master/es5.md#node-objects

[program]: https://github.com/estree/estree/blob/master/es5.md#programs

[jsx-runtime]: https://reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html

[swc]: https://swc.rs

[esbuild]: https://esbuild.github.io

[api-build-jsx]: #buildjsxtree-options

[api-options]: #options

[api-runtime]: #runtime-1


---

# estree-util-is-identifier-name

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[estree][] utility to check if something can be an identifier.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`cont(code[, options])`](#contcode-options)
    *   [`name(name[, options])`](#namename-options)
    *   [`start(code)`](#startcode)
    *   [Options](#options)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package is a utility that can be used to check if something can be an
identifier name.
For example, `a`, `_`, and `a1` are fine, but `1` and `-` are not.

## When should I use this?

You can use this utility when generating IDs from strings or parsing IDs.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install estree-util-is-identifier-name
```

In Deno with [`esm.sh`][esmsh]:

```js
import {cont, name, start} from 'https://esm.sh/estree-util-is-identifier-name@3'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {cont, name, start} from 'https://esm.sh/estree-util-is-identifier-name@3?bundle'
</script>
```

## Use

```js
import {cont, name, start} from 'estree-util-is-identifier-name'

name('$something69') // => true
name('69') // => false
name('var') // => true (this does not handle keywords)

start(48) // => false (code point for `'0'`)
cont(48) // => true (code point for `'0'`)
```

## API

This package exports the identifiers [`cont`][api-cont],
[`name`][api-name], and
[`start`][api-start].
There is no default export.

### `cont(code[, options])`

Checks if the given code point can continue an identifier.

###### Parameters

*   `code` (`number`)
    — code point to check
*   `options` ([`Options`][api-options], optional)
    — configuration

###### Returns

Whether `code` can continue an identifier (`boolean`).

### `name(name[, options])`

Checks if the given value is a valid identifier name.

###### Parameters

*   `name` (`string`)
    — identifier to check
*   `options` ([`Options`][api-options], optional)
    — configuration

###### Returns

Whether `name` can be an identifier (`boolean`).

### `start(code)`

Checks if the given code point can start an identifier.

###### Parameters

*   `code` (`number`)
    — code point to check

###### Returns

Whether `code` can start an identifier (`boolean`).

### Options

Configuration (TypeScript type).

###### Fields

*   `jsx` (`boolean`, default: `false`)
    — support JSX identifiers.

## Types

This package is fully typed with [TypeScript][].
It exports the additional type [`Options`][api-options].

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`estree-util-is-identifier-name@^3`, compatible with Node.js 16.

## Related

*   [`goto-bus-stop/estree-is-identifier`](https://github.com/goto-bus-stop/estree-is-identifier)
    — check if an AST node is an identifier

## Contribute

See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
ways to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/syntax-tree/estree-util-is-identifier-name/workflows/main/badge.svg

[build]: https://github.com/syntax-tree/estree-util-is-identifier-name/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/estree-util-is-identifier-name.svg

[coverage]: https://codecov.io/github/syntax-tree/estree-util-is-identifier-name

[downloads-badge]: https://img.shields.io/npm/dm/estree-util-is-identifier-name.svg

[downloads]: https://www.npmjs.com/package/estree-util-is-identifier-name

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=estree-util-is-identifier-name

[size]: https://bundlejs.com/?q=estree-util-is-identifier-name

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/syntax-tree/unist/discussions

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[typescript]: https://www.typescriptlang.org

[license]: license

[author]: https://wooorm.com

[health]: https://github.com/syntax-tree/.github

[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md

[support]: https://github.com/syntax-tree/.github/blob/main/support.md

[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md

[estree]: https://github.com/estree/estree

[api-cont]: #contcode-options

[api-name]: #namename-options

[api-start]: #startcode

[api-options]: #options


---

# estree-util-scope

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[estree][] utility to check what’s defined in a scope.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`Scope`](#scope)
  * [`Visitors`](#visitors)
  * [`createVisitors()`](#createvisitors)
* [Examples](#examples)
  * [Example: just the top scope](#example-just-the-top-scope)
* [Compatibility](#compatibility)
* [Related](#related)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package is a utility that tracks what’s defined in a scope.

## When should I use this?

If you are walking an estree already and want to find out what’s defined,
use this.
If you have more complex scoping needs,
see [`eslint-scope`][github-eslint-scope].

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install estree-util-scope
```

In Deno with [`esm.sh`][esmsh]:

```js
import {createVisitors} from 'https://esm.sh/estree-util-scope@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {createVisitors} from 'https://esm.sh/estree-util-scope@1?bundle'
</script>
```

## Use

Say we have the following `example.js`:

```js
/**
 * @import {Program} from 'estree'
 */

import {Parser} from 'acorn'
import {createVisitors} from 'estree-util-scope'
import {walk} from 'estree-walker'

const tree = /** @type {Program} */ (
  Parser.parse('import {a} from "b"; const c = 1', {
    ecmaVersion: 'latest',
    sourceType: 'module'
  })
)
const visitors = createVisitors()

walk(tree, {enter: visitors.enter, leave: visitors.exit})

console.log(visitors.scopes.at(-1))
```

…now running `node example.js` yields:

```js
{ block: false, defined: [ 'a', 'c' ] }
```

## API

### `Scope`

Scope.

###### Fields

* `block` (`boolean`)
  — whether this is a block scope or not;
  blocks are things made by `for` and `try` and `if`;
  non-blocks are functions and the top-level scope
* `defined` (`Array<string>`)
  — identifiers that are defined in this scope

### `Visitors`

State to track what’s defined;
contains `enter`, `exit` callbacks you must call and `scopes`.

###### Fields

* `enter` (`(node: Node) => undefined`)
  — callback you must call when entering a node
* `exit` (`(node: Node) => undefined`)
  — callback you must call when exiting (leaving) a node
* `scopes` (`[topLevel: Scope, ...rest: Scope[]]`)
  — list of scopes;
  the first scope is the top-level scope;
  the last scope is the current scope

### `createVisitors()`

Create state to track what’s defined.

###### Parameters

There are no parameters.

###### Returns

State (`Visitors`).

## Examples

### Example: just the top scope

Sometimes, you only care about a top-scope.
Or otherwise want to skip a node.
How to do this depends on how you walk the tree.
With `estree-walker`,
you can skip by calling `this.skip`.

```js
/**
 * @import {Program} from 'estree'
 */

import {Parser} from 'acorn'
import {createVisitors} from 'estree-util-scope'
import {walk} from 'estree-walker'

const tree = /** @type {Program} */ (
  Parser.parse(
    'function a(b) { var c = 1; if (d) { var e = 2 } }; if (f) { var g = 2 }',
    {ecmaVersion: 'latest'}
  )
)
const visitors = createVisitors()

walk(tree, {
  enter(node) {
    visitors.enter(node)

    if (
      node.type === 'ArrowFunctionExpression' ||
      node.type === 'FunctionDeclaration' ||
      node.type === 'FunctionExpression'
    ) {
      this.skip()
      visitors.exit(node) // Call the exit handler manually.
    }
  },
  leave: visitors.exit
})

console.log(visitors.scopes.at(-1))
```

…yields:

```js
{ block: false, defined: [ 'a', 'g' ] }
```

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, `estree-util-scope@1`,
compatible with Node.js 16.

## Related

## Security

This package is safe.

## Contribute

See [`contributing.md` in `syntax-tree/.github`][contributing] for ways to get
started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/syntax-tree/estree-util-scope/workflows/main/badge.svg

[build]: https://github.com/syntax-tree/estree-util-scope/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/estree-util-scope.svg

[coverage]: https://codecov.io/github/syntax-tree/estree-util-scope

[downloads-badge]: https://img.shields.io/npm/dm/estree-util-scope.svg

[downloads]: https://www.npmjs.com/package/estree-util-scope

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=estree-util-scope

[size]: https://bundlejs.com/?q=estree-util-scope

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/syntax-tree/unist/discussions

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[npm]: https://docs.npmjs.com/cli/install

[esmsh]: https://esm.sh

[license]: license

[author]: https://wooorm.com

[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md

[support]: https://github.com/syntax-tree/.github/blob/main/support.md

[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md

[estree]: https://github.com/estree/estree

[github-eslint-scope]: https://github.com/eslint/eslint-scope


---

# Source Map

[![Build Status](https://travis-ci.org/mozilla/source-map.png?branch=master)](https://travis-ci.org/mozilla/source-map)

[![Coverage Status](https://coveralls.io/repos/github/mozilla/source-map/badge.svg)](https://coveralls.io/github/mozilla/source-map)

[![NPM](https://nodei.co/npm/source-map.png?downloads=true&downloadRank=true)](https://www.npmjs.com/package/source-map)

This is a library to generate and consume the source map format
[described here][format].

[format]: https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k/edit

## Use with Node

    $ npm install source-map

## Use on the Web

    <script src="https://unpkg.com/source-map@0.7.3/dist/source-map.js"></script>
    <script>
        sourceMap.SourceMapConsumer.initialize({
            "lib/mappings.wasm": "https://unpkg.com/source-map@0.7.3/lib/mappings.wasm"
        });
    </script>

--------------------------------------------------------------------------------

<!-- `npm run toc` to regenerate the Table of Contents -->

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
## Table of Contents

- [Examples](#examples)
  - [Consuming a source map](#consuming-a-source-map)
  - [Generating a source map](#generating-a-source-map)
    - [With SourceNode (high level API)](#with-sourcenode-high-level-api)
    - [With SourceMapGenerator (low level API)](#with-sourcemapgenerator-low-level-api)
- [API](#api)
  - [SourceMapConsumer](#sourcemapconsumer)
    - [SourceMapConsumer.initialize(options)](#sourcemapconsumerinitializeoptions)
    - [new SourceMapConsumer(rawSourceMap)](#new-sourcemapconsumerrawsourcemap)
    - [SourceMapConsumer.with](#sourcemapconsumerwith)
    - [SourceMapConsumer.prototype.destroy()](#sourcemapconsumerprototypedestroy)
    - [SourceMapConsumer.prototype.computeColumnSpans()](#sourcemapconsumerprototypecomputecolumnspans)
    - [SourceMapConsumer.prototype.originalPositionFor(generatedPosition)](#sourcemapconsumerprototypeoriginalpositionforgeneratedposition)
    - [SourceMapConsumer.prototype.generatedPositionFor(originalPosition)](#sourcemapconsumerprototypegeneratedpositionfororiginalposition)
    - [SourceMapConsumer.prototype.allGeneratedPositionsFor(originalPosition)](#sourcemapconsumerprototypeallgeneratedpositionsfororiginalposition)
    - [SourceMapConsumer.prototype.hasContentsOfAllSources()](#sourcemapconsumerprototypehascontentsofallsources)
    - [SourceMapConsumer.prototype.sourceContentFor(source[, returnNullOnMissing])](#sourcemapconsumerprototypesourcecontentforsource-returnnullonmissing)
    - [SourceMapConsumer.prototype.eachMapping(callback, context, order)](#sourcemapconsumerprototypeeachmappingcallback-context-order)
  - [SourceMapGenerator](#sourcemapgenerator)
    - [new SourceMapGenerator([startOfSourceMap])](#new-sourcemapgeneratorstartofsourcemap)
    - [SourceMapGenerator.fromSourceMap(sourceMapConsumer)](#sourcemapgeneratorfromsourcemapsourcemapconsumer)
    - [SourceMapGenerator.prototype.addMapping(mapping)](#sourcemapgeneratorprototypeaddmappingmapping)
    - [SourceMapGenerator.prototype.setSourceContent(sourceFile, sourceContent)](#sourcemapgeneratorprototypesetsourcecontentsourcefile-sourcecontent)
    - [SourceMapGenerator.prototype.applySourceMap(sourceMapConsumer[, sourceFile[, sourceMapPath]])](#sourcemapgeneratorprototypeapplysourcemapsourcemapconsumer-sourcefile-sourcemappath)
    - [SourceMapGenerator.prototype.toString()](#sourcemapgeneratorprototypetostring)
  - [SourceNode](#sourcenode)
    - [new SourceNode([line, column, source[, chunk[, name]]])](#new-sourcenodeline-column-source-chunk-name)
    - [SourceNode.fromStringWithSourceMap(code, sourceMapConsumer[, relativePath])](#sourcenodefromstringwithsourcemapcode-sourcemapconsumer-relativepath)
    - [SourceNode.prototype.add(chunk)](#sourcenodeprototypeaddchunk)
    - [SourceNode.prototype.prepend(chunk)](#sourcenodeprototypeprependchunk)
    - [SourceNode.prototype.setSourceContent(sourceFile, sourceContent)](#sourcenodeprototypesetsourcecontentsourcefile-sourcecontent)
    - [SourceNode.prototype.walk(fn)](#sourcenodeprototypewalkfn)
    - [SourceNode.prototype.walkSourceContents(fn)](#sourcenodeprototypewalksourcecontentsfn)
    - [SourceNode.prototype.join(sep)](#sourcenodeprototypejoinsep)
    - [SourceNode.prototype.replaceRight(pattern, replacement)](#sourcenodeprototypereplacerightpattern-replacement)
    - [SourceNode.prototype.toString()](#sourcenodeprototypetostring)
    - [SourceNode.prototype.toStringWithSourceMap([startOfSourceMap])](#sourcenodeprototypetostringwithsourcemapstartofsourcemap)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## Examples

### Consuming a source map

```js
const rawSourceMap = {
  version: 3,
  file: 'min.js',
  names: ['bar', 'baz', 'n'],
  sources: ['one.js', 'two.js'],
  sourceRoot: 'http://example.com/www/js/',
  mappings: 'CAAC,IAAI,IAAM,SAAUA,GAClB,OAAOC,IAAID;CCDb,IAAI,IAAM,SAAUE,GAClB,OAAOA'
};

const whatever = await SourceMapConsumer.with(rawSourceMap, null, consumer => {

  console.log(consumer.sources);
  // [ 'http://example.com/www/js/one.js',
  //   'http://example.com/www/js/two.js' ]

  console.log(consumer.originalPositionFor({
    line: 2,
    column: 28
  }));
  // { source: 'http://example.com/www/js/two.js',
  //   line: 2,
  //   column: 10,
  //   name: 'n' }

  console.log(consumer.generatedPositionFor({
    source: 'http://example.com/www/js/two.js',
    line: 2,
    column: 10
  }));
  // { line: 2, column: 28 }

  consumer.eachMapping(function (m) {
    // ...
  });

  return computeWhatever();
});
```

### Generating a source map

In depth guide:
[**Compiling to JavaScript, and Debugging with Source Maps**](https://hacks.mozilla.org/2013/05/compiling-to-javascript-and-debugging-with-source-maps/)

#### With SourceNode (high level API)

```js
function compile(ast) {
  switch (ast.type) {
  case 'BinaryExpression':
    return new SourceNode(
      ast.location.line,
      ast.location.column,
      ast.location.source,
      [compile(ast.left), " + ", compile(ast.right)]
    );
  case 'Literal':
    return new SourceNode(
      ast.location.line,
      ast.location.column,
      ast.location.source,
      String(ast.value)
    );
  // ...
  default:
    throw new Error("Bad AST");
  }
}

var ast = parse("40 + 2", "add.js");
console.log(compile(ast).toStringWithSourceMap({
  file: 'add.js'
}));
// { code: '40 + 2',
//   map: [object SourceMapGenerator] }
```

#### With SourceMapGenerator (low level API)

```js
var map = new SourceMapGenerator({
  file: "source-mapped.js"
});

map.addMapping({
  generated: {
    line: 10,
    column: 35
  },
  source: "foo.js",
  original: {
    line: 33,
    column: 2
  },
  name: "christopher"
});

console.log(map.toString());
// '{"version":3,"file":"source-mapped.js","sources":["foo.js"],"names":["christopher"],"mappings":";;;;;;;;;mCAgCEA"}'
```

## API

Get a reference to the module:

```js
// Node.js
var sourceMap = require('source-map');

// Browser builds
var sourceMap = window.sourceMap;

// Inside Firefox
const sourceMap = require("devtools/toolkit/sourcemap/source-map.js");
```

### SourceMapConsumer

A `SourceMapConsumer` instance represents a parsed source map which we can query
for information about the original file positions by giving it a file position
in the generated source.

#### SourceMapConsumer.initialize(options)

When using `SourceMapConsumer` outside of node.js, for example on the Web, it
needs to know from what URL to load `lib/mappings.wasm`. You must inform it by
calling `initialize` before constructing any `SourceMapConsumer`s.

The options object has the following properties:

* `"lib/mappings.wasm"`: A `String` containing the URL of the
  `lib/mappings.wasm` file, or an `ArrayBuffer` with the contents of `lib/mappings.wasm`.

```js
sourceMap.SourceMapConsumer.initialize({
  "lib/mappings.wasm": "https://example.com/source-map/lib/mappings.wasm"
});
```

#### new SourceMapConsumer(rawSourceMap)

The only parameter is the raw source map (either as a string which can be
`JSON.parse`'d, or an object). According to the spec, source maps have the
following attributes:

* `version`: Which version of the source map spec this map is following.

* `sources`: An array of URLs to the original source files.

* `names`: An array of identifiers which can be referenced by individual
  mappings.

* `sourceRoot`: Optional. The URL root from which all sources are relative.

* `sourcesContent`: Optional. An array of contents of the original source files.

* `mappings`: A string of base64 VLQs which contain the actual mappings.

* `file`: Optional. The generated filename this source map is associated with.

The promise of the constructed souce map consumer is returned.

When the `SourceMapConsumer` will no longer be used anymore, you must call its
`destroy` method.

```js
const consumer = await new sourceMap.SourceMapConsumer(rawSourceMapJsonData);
doStuffWith(consumer);
consumer.destroy();
```

Alternatively, you can use `SourceMapConsumer.with` to avoid needing to remember
to call `destroy`.

#### SourceMapConsumer.with

Construct a new `SourceMapConsumer` from `rawSourceMap` and `sourceMapUrl`
(see the `SourceMapConsumer` constructor for details. Then, invoke the `async
function f(SourceMapConsumer) -> T` with the newly constructed consumer, wait
for `f` to complete, call `destroy` on the consumer, and return `f`'s return
value.

You must not use the consumer after `f` completes!

By using `with`, you do not have to remember to manually call `destroy` on
the consumer, since it will be called automatically once `f` completes.

```js
const xSquared = await SourceMapConsumer.with(
  myRawSourceMap,
  null,
  async function (consumer) {
    // Use `consumer` inside here and don't worry about remembering
    // to call `destroy`.

    const x = await whatever(consumer);
    return x * x;
  }
);

// You may not use that `consumer` anymore out here; it has
// been destroyed. But you can use `xSquared`.
console.log(xSquared);
```

#### SourceMapConsumer.prototype.destroy()

Free this source map consumer's associated wasm data that is manually-managed.

```js
consumer.destroy();
```

Alternatively, you can use `SourceMapConsumer.with` to avoid needing to remember
to call `destroy`.

#### SourceMapConsumer.prototype.computeColumnSpans()

Compute the last column for each generated mapping. The last column is
inclusive.

```js
// Before:
consumer.allGeneratedPositionsFor({ line: 2, source: "foo.coffee" })
// [ { line: 2,
//     column: 1 },
//   { line: 2,
//     column: 10 },
//   { line: 2,
//     column: 20 } ]

consumer.computeColumnSpans();

// After:
consumer.allGeneratedPositionsFor({ line: 2, source: "foo.coffee" })
// [ { line: 2,
//     column: 1,
//     lastColumn: 9 },
//   { line: 2,
//     column: 10,
//     lastColumn: 19 },
//   { line: 2,
//     column: 20,
//     lastColumn: Infinity } ]
```

#### SourceMapConsumer.prototype.originalPositionFor(generatedPosition)

Returns the original source, line, and column information for the generated
source's line and column positions provided. The only argument is an object with
the following properties:

* `line`: The line number in the generated source.  Line numbers in
  this library are 1-based (note that the underlying source map
  specification uses 0-based line numbers -- this library handles the
  translation).

* `column`: The column number in the generated source.  Column numbers
  in this library are 0-based.

* `bias`: Either `SourceMapConsumer.GREATEST_LOWER_BOUND` or
  `SourceMapConsumer.LEAST_UPPER_BOUND`. Specifies whether to return the closest
  element that is smaller than or greater than the one we are searching for,
  respectively, if the exact element cannot be found.  Defaults to
  `SourceMapConsumer.GREATEST_LOWER_BOUND`.

and an object is returned with the following properties:

* `source`: The original source file, or null if this information is not
  available.

* `line`: The line number in the original source, or null if this information is
  not available.  The line number is 1-based.

* `column`: The column number in the original source, or null if this
  information is not available.  The column number is 0-based.

* `name`: The original identifier, or null if this information is not available.

```js
consumer.originalPositionFor({ line: 2, column: 10 })
// { source: 'foo.coffee',
//   line: 2,
//   column: 2,
//   name: null }

consumer.originalPositionFor({ line: 99999999999999999, column: 999999999999999 })
// { source: null,
//   line: null,
//   column: null,
//   name: null }
```

#### SourceMapConsumer.prototype.generatedPositionFor(originalPosition)

Returns the generated line and column information for the original source,
line, and column positions provided. The only argument is an object with
the following properties:

* `source`: The filename of the original source.

* `line`: The line number in the original source.  The line number is
  1-based.

* `column`: The column number in the original source.  The column
  number is 0-based.

and an object is returned with the following properties:

* `line`: The line number in the generated source, or null.  The line
  number is 1-based.

* `column`: The column number in the generated source, or null.  The
  column number is 0-based.

```js
consumer.generatedPositionFor({ source: "example.js", line: 2, column: 10 })
// { line: 1,
//   column: 56 }
```

#### SourceMapConsumer.prototype.allGeneratedPositionsFor(originalPosition)

Returns all generated line and column information for the original source, line,
and column provided. If no column is provided, returns all mappings
corresponding to a either the line we are searching for or the next closest line
that has any mappings. Otherwise, returns all mappings corresponding to the
given line and either the column we are searching for or the next closest column
that has any offsets.

The only argument is an object with the following properties:

* `source`: The filename of the original source.

* `line`: The line number in the original source.  The line number is
  1-based.

* `column`: Optional. The column number in the original source.  The
  column number is 0-based.

and an array of objects is returned, each with the following properties:

* `line`: The line number in the generated source, or null.  The line
  number is 1-based.

* `column`: The column number in the generated source, or null.  The
  column number is 0-based.

```js
consumer.allGeneratedpositionsfor({ line: 2, source: "foo.coffee" })
// [ { line: 2,
//     column: 1 },
//   { line: 2,
//     column: 10 },
//   { line: 2,
//     column: 20 } ]
```

#### SourceMapConsumer.prototype.hasContentsOfAllSources()

Return true if we have the embedded source content for every source listed in
the source map, false otherwise.

In other words, if this method returns `true`, then
`consumer.sourceContentFor(s)` will succeed for every source `s` in
`consumer.sources`.

```js
// ...
if (consumer.hasContentsOfAllSources()) {
  consumerReadyCallback(consumer);
} else {
  fetchSources(consumer, consumerReadyCallback);
}
// ...
```

#### SourceMapConsumer.prototype.sourceContentFor(source[, returnNullOnMissing])

Returns the original source content for the source provided. The only
argument is the URL of the original source file.

If the source content for the given source is not found, then an error is
thrown. Optionally, pass `true` as the second param to have `null` returned
instead.

```js
consumer.sources
// [ "my-cool-lib.clj" ]

consumer.sourceContentFor("my-cool-lib.clj")
// "..."

consumer.sourceContentFor("this is not in the source map");
// Error: "this is not in the source map" is not in the source map

consumer.sourceContentFor("this is not in the source map", true);
// null
```

#### SourceMapConsumer.prototype.eachMapping(callback, context, order)

Iterate over each mapping between an original source/line/column and a
generated line/column in this source map.

* `callback`: The function that is called with each mapping. Mappings have the
  form `{ source, generatedLine, generatedColumn, originalLine, originalColumn,
  name }`

* `context`: Optional. If specified, this object will be the value of `this`
  every time that `callback` is called.

* `order`: Either `SourceMapConsumer.GENERATED_ORDER` or
  `SourceMapConsumer.ORIGINAL_ORDER`. Specifies whether you want to iterate over
  the mappings sorted by the generated file's line/column order or the
  original's source/line/column order, respectively. Defaults to
  `SourceMapConsumer.GENERATED_ORDER`.

```js
consumer.eachMapping(function (m) { console.log(m); })
// ...
// { source: 'illmatic.js',
//   generatedLine: 1,
//   generatedColumn: 0,
//   originalLine: 1,
//   originalColumn: 0,
//   name: null }
// { source: 'illmatic.js',
//   generatedLine: 2,
//   generatedColumn: 0,
//   originalLine: 2,
//   originalColumn: 0,
//   name: null }
// ...
```
### SourceMapGenerator

An instance of the SourceMapGenerator represents a source map which is being
built incrementally.

#### new SourceMapGenerator([startOfSourceMap])

You may pass an object with the following properties:

* `file`: The filename of the generated source that this source map is
  associated with.

* `sourceRoot`: A root for all relative URLs in this source map.

* `skipValidation`: Optional. When `true`, disables validation of mappings as
  they are added. This can improve performance but should be used with
  discretion, as a last resort. Even then, one should avoid using this flag when
  running tests, if possible.

```js
var generator = new sourceMap.SourceMapGenerator({
  file: "my-generated-javascript-file.js",
  sourceRoot: "http://example.com/app/js/"
});
```

#### SourceMapGenerator.fromSourceMap(sourceMapConsumer)

Creates a new `SourceMapGenerator` from an existing `SourceMapConsumer` instance.

* `sourceMapConsumer` The SourceMap.

```js
var generator = sourceMap.SourceMapGenerator.fromSourceMap(consumer);
```

#### SourceMapGenerator.prototype.addMapping(mapping)

Add a single mapping from original source line and column to the generated
source's line and column for this source map being created. The mapping object
should have the following properties:

* `generated`: An object with the generated line and column positions.

* `original`: An object with the original line and column positions.

* `source`: The original source file (relative to the sourceRoot).

* `name`: An optional original token name for this mapping.

```js
generator.addMapping({
  source: "module-one.scm",
  original: { line: 128, column: 0 },
  generated: { line: 3, column: 456 }
})
```

#### SourceMapGenerator.prototype.setSourceContent(sourceFile, sourceContent)

Set the source content for an original source file.

* `sourceFile` the URL of the original source file.

* `sourceContent` the content of the source file.

```js
generator.setSourceContent("module-one.scm",
                           fs.readFileSync("path/to/module-one.scm"))
```

#### SourceMapGenerator.prototype.applySourceMap(sourceMapConsumer[, sourceFile[, sourceMapPath]])

Applies a SourceMap for a source file to the SourceMap.
Each mapping to the supplied source file is rewritten using the
supplied SourceMap. Note: The resolution for the resulting mappings
is the minimum of this map and the supplied map.

* `sourceMapConsumer`: The SourceMap to be applied.

* `sourceFile`: Optional. The filename of the source file.
  If omitted, sourceMapConsumer.file will be used, if it exists.
  Otherwise an error will be thrown.

* `sourceMapPath`: Optional. The dirname of the path to the SourceMap
  to be applied. If relative, it is relative to the SourceMap.

  This parameter is needed when the two SourceMaps aren't in the same
  directory, and the SourceMap to be applied contains relative source
  paths. If so, those relative source paths need to be rewritten
  relative to the SourceMap.

  If omitted, it is assumed that both SourceMaps are in the same directory,
  thus not needing any rewriting. (Supplying `'.'` has the same effect.)

#### SourceMapGenerator.prototype.toString()

Renders the source map being generated to a string.

```js
generator.toString()
// '{"version":3,"sources":["module-one.scm"],"names":[],"mappings":"...snip...","file":"my-generated-javascript-file.js","sourceRoot":"http://example.com/app/js/"}'
```

### SourceNode

SourceNodes provide a way to abstract over interpolating and/or concatenating
snippets of generated JavaScript source code, while maintaining the line and
column information associated between those snippets and the original source
code. This is useful as the final intermediate representation a compiler might
use before outputting the generated JS and source map.

#### new SourceNode([line, column, source[, chunk[, name]]])

* `line`: The original line number associated with this source node, or null if
  it isn't associated with an original line.  The line number is 1-based.

* `column`: The original column number associated with this source node, or null
  if it isn't associated with an original column.  The column number
  is 0-based.

* `source`: The original source's filename; null if no filename is provided.

* `chunk`: Optional. Is immediately passed to `SourceNode.prototype.add`, see
  below.

* `name`: Optional. The original identifier.

```js
var node = new SourceNode(1, 2, "a.cpp", [
  new SourceNode(3, 4, "b.cpp", "extern int status;\n"),
  new SourceNode(5, 6, "c.cpp", "std::string* make_string(size_t n);\n"),
  new SourceNode(7, 8, "d.cpp", "int main(int argc, char** argv) {}\n"),
]);
```

#### SourceNode.fromStringWithSourceMap(code, sourceMapConsumer[, relativePath])

Creates a SourceNode from generated code and a SourceMapConsumer.

* `code`: The generated code

* `sourceMapConsumer` The SourceMap for the generated code

* `relativePath` The optional path that relative sources in `sourceMapConsumer`
  should be relative to.

```js
const consumer = await new SourceMapConsumer(fs.readFileSync("path/to/my-file.js.map", "utf8"));
const node = SourceNode.fromStringWithSourceMap(fs.readFileSync("path/to/my-file.js"), consumer);
```

#### SourceNode.prototype.add(chunk)

Add a chunk of generated JS to this source node.

* `chunk`: A string snippet of generated JS code, another instance of
   `SourceNode`, or an array where each member is one of those things.

```js
node.add(" + ");
node.add(otherNode);
node.add([leftHandOperandNode, " + ", rightHandOperandNode]);
```

#### SourceNode.prototype.prepend(chunk)

Prepend a chunk of generated JS to this source node.

* `chunk`: A string snippet of generated JS code, another instance of
   `SourceNode`, or an array where each member is one of those things.

```js
node.prepend("/** Build Id: f783haef86324gf **/\n\n");
```

#### SourceNode.prototype.setSourceContent(sourceFile, sourceContent)

Set the source content for a source file. This will be added to the
`SourceMap` in the `sourcesContent` field.

* `sourceFile`: The filename of the source file

* `sourceContent`: The content of the source file

```js
node.setSourceContent("module-one.scm",
                      fs.readFileSync("path/to/module-one.scm"))
```

#### SourceNode.prototype.walk(fn)

Walk over the tree of JS snippets in this node and its children. The walking
function is called once for each snippet of JS and is passed that snippet and
the its original associated source's line/column location.

* `fn`: The traversal function.

```js
var node = new SourceNode(1, 2, "a.js", [
  new SourceNode(3, 4, "b.js", "uno"),
  "dos",
  [
    "tres",
    new SourceNode(5, 6, "c.js", "quatro")
  ]
]);

node.walk(function (code, loc) { console.log("WALK:", code, loc); })
// WALK: uno { source: 'b.js', line: 3, column: 4, name: null }
// WALK: dos { source: 'a.js', line: 1, column: 2, name: null }
// WALK: tres { source: 'a.js', line: 1, column: 2, name: null }
// WALK: quatro { source: 'c.js', line: 5, column: 6, name: null }
```

#### SourceNode.prototype.walkSourceContents(fn)

Walk over the tree of SourceNodes. The walking function is called for each
source file content and is passed the filename and source content.

* `fn`: The traversal function.

```js
var a = new SourceNode(1, 2, "a.js", "generated from a");
a.setSourceContent("a.js", "original a");
var b = new SourceNode(1, 2, "b.js", "generated from b");
b.setSourceContent("b.js", "original b");
var c = new SourceNode(1, 2, "c.js", "generated from c");
c.setSourceContent("c.js", "original c");

var node = new SourceNode(null, null, null, [a, b, c]);
node.walkSourceContents(function (source, contents) { console.log("WALK:", source, ":", contents); })
// WALK: a.js : original a
// WALK: b.js : original b
// WALK: c.js : original c
```

#### SourceNode.prototype.join(sep)

Like `Array.prototype.join` except for SourceNodes. Inserts the separator
between each of this source node's children.

* `sep`: The separator.

```js
var lhs = new SourceNode(1, 2, "a.rs", "my_copy");
var operand = new SourceNode(3, 4, "a.rs", "=");
var rhs = new SourceNode(5, 6, "a.rs", "orig.clone()");

var node = new SourceNode(null, null, null, [ lhs, operand, rhs ]);
var joinedNode = node.join(" ");
```

#### SourceNode.prototype.replaceRight(pattern, replacement)

Call `String.prototype.replace` on the very right-most source snippet. Useful
for trimming white space from the end of a source node, etc.

* `pattern`: The pattern to replace.

* `replacement`: The thing to replace the pattern with.

```js
// Trim trailing white space.
node.replaceRight(/\s*$/, "");
```

#### SourceNode.prototype.toString()

Return the string representation of this source node. Walks over the tree and
concatenates all the various snippets together to one string.

```js
var node = new SourceNode(1, 2, "a.js", [
  new SourceNode(3, 4, "b.js", "uno"),
  "dos",
  [
    "tres",
    new SourceNode(5, 6, "c.js", "quatro")
  ]
]);

node.toString()
// 'unodostresquatro'
```

#### SourceNode.prototype.toStringWithSourceMap([startOfSourceMap])

Returns the string representation of this tree of source nodes, plus a
SourceMapGenerator which contains all the mappings between the generated and
original sources.

The arguments are the same as those to `new SourceMapGenerator`.

```js
var node = new SourceNode(1, 2, "a.js", [
  new SourceNode(3, 4, "b.js", "uno"),
  "dos",
  [
    "tres",
    new SourceNode(5, 6, "c.js", "quatro")
  ]
]);

node.toStringWithSourceMap({ file: "my-output-file.js" })
// { code: 'unodostresquatro',
//   map: [object SourceMapGenerator] }
```


---

# estree-util-to-js

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[estree][] (and [esast][]) utility to serialize estrees as JavaScript.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`toJs(tree[, options])`](#tojstree-options)
    *   [`jsx`](#jsx)
    *   [`Handler`](#handler)
    *   [`Handlers`](#handlers)
    *   [`Map`](#map)
    *   [`Options`](#options)
    *   [`Result`](#result)
    *   [`State`](#state)
*   [Examples](#examples)
    *   [Example: source maps](#example-source-maps)
    *   [Example: comments](#example-comments)
    *   [Example: JSX](#example-jsx)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package is a utility that turns an estree syntax tree into a string of
JavaScript.

## When should I use this?

You can use this utility when you want to get the serialized JavaScript that is
represented by the syntax tree, either because you’re done with the syntax tree,
or because you’re integrating with another tool that does not support syntax
trees.

This utility is particularly useful when integrating with other unified tools,
such as unist and vfile.

The utility [`esast-util-from-js`][esast-util-from-js] does the inverse of this
utility.
It turns JS into esast.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install estree-util-to-js
```

In Deno with [`esm.sh`][esmsh]:

```js
import {toJs} from 'https://esm.sh/estree-util-to-js@2'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {toJs} from 'https://esm.sh/estree-util-to-js@2?bundle'
</script>
```

## Use

```js
import fs from 'node:fs/promises'
import {parse} from 'acorn'
import {toJs} from 'estree-util-to-js'

const file = String(await fs.readFile('index.js'))

const tree = parse(file, {ecmaVersion: 2022, sourceType: 'module', locations: true})

// @ts-expect-error: acorn is funky but it works fine.
console.log(toJs(tree))
```

Yields:

```js
{
  value: "export {toJs} from './lib/index.js';\nexport {jsx} from './lib/jsx.js';\n",
  map: undefined
}
```

## API

This package exports the identifiers [`jsx`][api-jsx] and [`toJs`][api-to-js].
There is no default export.

### `toJs(tree[, options])`

Serialize an estree as JavaScript.

###### Parameters

*   `tree` ([`Program`][program])
    — estree
*   `options` ([`Options`][api-options])
    — configuration

###### Returns

Result, optionally with source map ([`Result`][api-result]).

### `jsx`

Map of handlers to handle the nodes of JSX extensions in JavaScript
([`Handlers`][api-handlers]).

### `Handler`

Handle a particular node (TypeScript type).

###### Parameters

*   `this` (`Generator`)
    — `astring` generator
*   `node` ([`Node`][node])
    — node to serialize
*   `state` ([`State`][api-state])
    — info passed around

###### Returns

Nothing (`undefined`).

### `Handlers`

Handlers of nodes (TypeScript type).

###### Type

```ts
type Handlers = Partial<Record<Node['type'], Handler>>
```

### `Map`

Raw source map from `source-map` (TypeScript type).

### `Options`

Configuration (TypeScript type).

###### Fields

*   `SourceMapGenerator` ([`SourceMapGenerator`][source-map])
    — generate a source map with this class
*   `filePath` (`string`)
    — path to original input file
*   `handlers` ([`Handlers`][api-handlers])
    — extra handlers

### `Result`

Result (TypeScript type).

###### Fields

*   `value` (`string`)
    — serialized JavaScript
*   `map` ([`Map`][api-map] or `undefined`)
    — source map as (parsed) JSON

### `State`

State from `astring` (TypeScript type).

## Examples

### Example: source maps

Source maps are supported when passing the `SourceMapGenerator` class from
[`source-map`][source-map].
You should also pass `filePath`.
Modified example from § Use above:

```diff
 import fs from 'node:fs/promises'
 import {parse} from 'acorn'
+import {SourceMapGenerator} from 'source-map'
 import {toJs} from 'estree-util-to-js'

-const file = String(await fs.readFile('index.js'))
+const filePath = 'index.js'
+const file = String(await fs.readFile(filePath))

 const tree = parse(file, {
   ecmaVersion: 2022,
@@ -11,4 +13,4 @@ const tree = parse(file, {
 })

 // @ts-expect-error: acorn is funky but it works fine.
-console.log(toJs(tree))
+console.log(toJs(tree, {filePath, SourceMapGenerator}))
```

Yields:

```js
{
  value: "export {toJs} from './lib/index.js';\nexport {jsx} from './lib/jsx.js';\n",
  map: {
    version: 3,
    sources: [ 'index.js' ],
    names: [],
    mappings: 'QAOQ,WAAW;QACX,UAAU',
    file: 'index.js'
  }
}
```

### Example: comments

To get comments to work, they have to be inside the tree.
This is not done by Acorn.
[`estree-util-attach-comments`][estree-util-attach-comments] can do that.
Modified example from § Use above:

```diff
 import fs from 'node:fs/promises'
 import {parse} from 'acorn'
+import {attachComments} from 'estree-util-attach-comments'
 import {toJs} from 'estree-util-to-js'

 const file = String(await fs.readFile('index.js'))

+/** @type {Array<import('estree-jsx').Comment>} */
+const comments = []
 const tree = parse(file, {
   ecmaVersion: 2022,
   sourceType: 'module',
-  locations: true
+  locations: true,
+  // @ts-expect-error: acorn is funky these comments are fine.
+  onComment: comments
 })
+attachComments(tree, comments)

 // @ts-expect-error: acorn is funky but it works fine.
 console.log(toJs(tree))
```

Yields:

```js
{
  value: '/**\n' +
    "* @typedef {import('./lib/index.js').Options} Options\n" +
    "* @typedef {import('./lib/types.js').Handler} Handler\n" +
    "* @typedef {import('./lib/types.js').Handlers} Handlers\n" +
    "* @typedef {import('./lib/types.js').State} State\n" +
    '*/\n' +
    "export {toJs} from './lib/index.js';\n" +
    "export {jsx} from './lib/jsx.js';\n",
  map: undefined
}
```

### Example: JSX

To get JSX to work, handlers need to be registered.
This is not done by default, but they are exported as `jsx` and can be passed.
Modified example from § Use above:

```diff
 import fs from 'node:fs/promises'
-import {parse} from 'acorn'
-import {toJs} from 'estree-util-to-js'
+import {Parser} from 'acorn'
+import acornJsx from 'acorn-jsx'
+import {jsx, toJs} from 'estree-util-to-js'

-const file = String(await fs.readFile('index.js'))
+const file = '<>{1 + 1}</>'

-const tree = parse(file, {
+const tree = Parser.extend(acornJsx()).parse(file, {
   ecmaVersion: 2022,
   sourceType: 'module',
   locations: true
 })

 // @ts-expect-error: acorn is funky but it works fine.
-console.log(toJs(tree))
+console.log(toJs(tree, {handlers: jsx}))
```

Yields:

```js
{ value: '<>{1 + 1}</>;\n', map: undefined }
```

## Types

This package is fully typed with [TypeScript][].
It exports the additional types [`Handler`][api-handler],
[`Handlers`][api-handlers],
[`Map`][api-map],
[`Options`][api-options],
[`Result`][api-result], and
[`State`][api-state].

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, `estree-util-to-js@^2`,
compatible with Node.js 16.

## Contribute

See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
ways to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/syntax-tree/estree-util-to-js/workflows/main/badge.svg

[build]: https://github.com/syntax-tree/estree-util-to-js/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/estree-util-to-js.svg

[coverage]: https://codecov.io/github/syntax-tree/estree-util-to-js

[downloads-badge]: https://img.shields.io/npm/dm/estree-util-to-js.svg

[downloads]: https://www.npmjs.com/package/estree-util-to-js

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=estree-util-to-js

[size]: https://bundlejs.com/?q=estree-util-to-js

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/syntax-tree/unist/discussions

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[typescript]: https://www.typescriptlang.org

[license]: license

[author]: https://wooorm.com

[health]: https://github.com/syntax-tree/.github

[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md

[support]: https://github.com/syntax-tree/.github/blob/main/support.md

[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md

[esast]: https://github.com/syntax-tree/esast

[esast-util-from-js]: https://github.com/syntax-tree/esast-util-from-js

[estree]: https://github.com/estree/estree

[estree-util-attach-comments]: https://github.com/syntax-tree/estree-util-attach-comments

[program]: https://github.com/estree/estree/blob/master/es2015.md#programs

[node]: https://github.com/estree/estree/blob/master/es5.md#node-objects

[source-map]: https://github.com/mozilla/source-map

[api-jsx]: #jsx

[api-to-js]: #tojstree-options

[api-handler]: #handler

[api-handlers]: #handlers

[api-map]: #map

[api-options]: #options

[api-state]: #state

[api-result]: #result


---

# MIT License

Copyright © 2021 Remco Haszing

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
associated documentation files (the “Software”), to deal in the Software without restriction,
including without limitation the rights to use, copy, modify, merge, publish, distribute,
sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial
portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES
OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


---

# estree-util-value-to-estree

[![github actions](https://github.com/remcohaszing/estree-util-value-to-estree/actions/workflows/ci.yaml/badge.svg)](https://github.com/remcohaszing/estree-util-value-to-estree/actions/workflows/ci.yaml)
[![codecov](https://codecov.io/gh/remcohaszing/estree-util-value-to-estree/branch/main/graph/badge.svg)](https://codecov.io/gh/remcohaszing/estree-util-value-to-estree)
[![npm version](https://img.shields.io/npm/v/estree-util-value-to-estree)](https://www.npmjs.com/package/estree-util-value-to-estree)
[![npm downloads](https://img.shields.io/npm/dm/estree-util-value-to-estree)](https://www.npmjs.com/package/estree-util-value-to-estree)

Convert a JavaScript value to an [ESTree](https://github.com/estree/estree) expression.

## Table of Contents

- [Installation](#installation)
- [Usage](#usage)
- [API](#api)
  - [`valueToEstree(value, options?)`](#valuetoestreevalue-options)
- [Compatibility](#compatibility)
- [License](#license)

## Installation

```sh
npm install estree-util-value-to-estree
```

## Usage

This package converts a JavaScript value to an [ESTree](https://github.com/estree/estree) expression
for values that can be constructed without the need for a context.

Currently the following types are supported:

- [`bigint`](https://developer.mozilla.org/docs/Glossary/BigInt)
- [`boolean`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)
- [`null`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Operators/null)
- [`number`](https://developer.mozilla.org/docs/Glossary/Number) (Including
  [Infinity](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Infinity)
  and [NaN](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/NaN))
- [`string`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)
- [`symbol`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Symbol)
  ([shared](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Symbol#shared_symbols_in_the_global_symbol_registry)
  and
  [well-known](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Symbol#well-known_symbols))
- [`object`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)
- [null-prototype `Object`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object#null-prototype_objects)
- [`undefined`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Undefined)
- [`Array`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)
- [`BigInt64Array`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/BigInt64Array)
- [`BigUint64Array`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/BigUint64Array)
- [`Boolean`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)
- [`Buffer`](https://nodejs.org/api/buffer.html)
- [`Date`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date)
- [`Float32Array`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Float32Array)
- [`Float64Array`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Float64Array)
- [`Int16Array`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Int16Array)
- [`Int32Array`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Int32Array)
- [`Int8Array`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Int8Array)
- [`Map`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Map)
- [`Number`](https://developer.mozilla.org/docs/Glossary/Number)
- [`RegExp`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/RegExp)
- [`Set`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Set)
- [`String`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)
- [`Temporal.Duration`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration)
- [`Temporal.Instant`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Instant)
- [`Temporal.PlainDate`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainDate)
- [`Temporal.PlainDateTime`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainDateTime)
- [`Temporal.PlainYearMonth`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainYearMonth)
- [`Temporal.PlainMonthDay`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainMonthDay)
- [`Temporal.PlainTime`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainTime)
- [`Temporal.ZonedDateTime`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime)
- [`Uint8Array`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array)
- [`Uint8ClampedArray`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Uint8ClampedArray)
- [`Uint16Array`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Uint16Array)
- [`Uint32Array`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Uint32Array)
- [`URL`](https://developer.mozilla.org/docs/Web/API/URL)
- [`URLSearchParams`](https://developer.mozilla.org/docs/Web/API/URLSearchParams)

If `options.instanceAsObject` is set to `true`, other objects are turned into plain object.

```ts
import assert from 'node:assert/strict'

import { valueToEstree } from 'estree-util-value-to-estree'

const result = valueToEstree({
  null: null,
  undefined,
  string: 'Hello world!',
  number: 42,
  negativeNumber: -1337,
  infinity: Number.POSITIVE_INFINITY,
  notANumber: Number.NaN,
  regex: /\w+/i,
  date: new Date('1970-01-01'),
  array: ['I’m an array item!'],
  object: { nested: 'value' }
})

assert.deepEqual(result, {
  type: 'ObjectExpression',
  properties: [
    {
      type: 'Property',
      method: false,
      shorthand: false,
      computed: false,
      kind: 'init',
      key: { type: 'Literal', value: 'null' },
      value: { type: 'Literal', value: null }
    },
    {
      type: 'Property',
      method: false,
      shorthand: false,
      computed: false,
      kind: 'init',
      key: { type: 'Literal', value: 'undefined' },
      value: { type: 'Identifier', name: 'undefined' }
    },
    {
      type: 'Property',
      method: false,
      shorthand: false,
      computed: false,
      kind: 'init',
      key: { type: 'Literal', value: 'string' },
      value: { type: 'Literal', value: 'Hello world!' }
    },
    {
      type: 'Property',
      method: false,
      shorthand: false,
      computed: false,
      kind: 'init',
      key: { type: 'Literal', value: 'number' },
      value: { type: 'Literal', value: 42 }
    },
    {
      type: 'Property',
      method: false,
      shorthand: false,
      computed: false,
      kind: 'init',
      key: { type: 'Literal', value: 'negativeNumber' },
      value: {
        type: 'UnaryExpression',
        operator: '-',
        prefix: true,
        argument: { type: 'Literal', value: 1337 }
      }
    },
    {
      type: 'Property',
      method: false,
      shorthand: false,
      computed: false,
      kind: 'init',
      key: { type: 'Literal', value: 'infinity' },
      value: { type: 'Identifier', name: 'Infinity' }
    },
    {
      type: 'Property',
      method: false,
      shorthand: false,
      computed: false,
      kind: 'init',
      key: { type: 'Literal', value: 'notANumber' },
      value: { type: 'Identifier', name: 'NaN' }
    },
    {
      type: 'Property',
      method: false,
      shorthand: false,
      computed: false,
      kind: 'init',
      key: { type: 'Literal', value: 'regex' },
      value: {
        type: 'Literal',
        value: /\w+/i,
        regex: { pattern: '\\w+', flags: 'i' }
      }
    },
    {
      type: 'Property',
      method: false,
      shorthand: false,
      computed: false,
      kind: 'init',
      key: { type: 'Literal', value: 'date' },
      value: {
        type: 'NewExpression',
        callee: { type: 'Identifier', name: 'Date' },
        arguments: [{ type: 'Literal', value: 0 }]
      }
    },
    {
      type: 'Property',
      method: false,
      shorthand: false,
      computed: false,
      kind: 'init',
      key: { type: 'Literal', value: 'array' },
      value: {
        type: 'ArrayExpression',
        elements: [{ type: 'Literal', value: 'I’m an array item!' }]
      }
    },
    {
      type: 'Property',
      method: false,
      shorthand: false,
      computed: false,
      kind: 'init',
      key: { type: 'Literal', value: 'object' },
      value: {
        type: 'ObjectExpression',
        properties: [
          {
            type: 'Property',
            method: false,
            shorthand: false,
            computed: false,
            kind: 'init',
            key: { type: 'Literal', value: 'nested' },
            value: { type: 'Literal', value: 'value' }
          }
        ]
      }
    }
  ]
})

class Point {
  line: number

  column: number

  constructor(line: number, column: number) {
    this.line = line
    this.column = column
  }
}

// Normally complex objects throw.
assert.throws(() => valueToEstree(new Point(2, 3)))

// `instanceAsObject: true` treats them as plain objects.
assert.deepEqual(valueToEstree(new Point(2, 3), { instanceAsObject: true }), {
  type: 'ObjectExpression',
  properties: [
    {
      type: 'Property',
      method: false,
      shorthand: false,
      computed: false,
      kind: 'init',
      key: { type: 'Literal', value: 'line' },
      value: { type: 'Literal', value: 2 }
    },
    {
      type: 'Property',
      method: false,
      shorthand: false,
      computed: false,
      kind: 'init',
      key: { type: 'Literal', value: 'column' },
      value: { type: 'Literal', value: 3 }
    }
  ]
})
```

## API

This API exports the function `valueToEstree`.

### `valueToEstree(value, options?)`

Convert a value to an [ESTree](https://github.com/estree/estree) node.

#### options

- `instanceAsObject` (boolean, default: `false`) — If true, treat objects that have a prototype as
  plain objects.
- `preserveReferences` (boolean, default: `false`) — If true, preserve references to the same object
  found within the input. This also allows to serialize recursive structures. If needed, the
  resulting expression will be an iife.

## Compatibility

This project is compatible with Node.js 16 or greater.

## License

[MIT](LICENSE.md) © [Remco Haszing](https://github.com/remcohaszing)


---

# estree-util-visit

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[estree][] (and [esast][]) utility to visit nodes.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`visit(tree, visitor|visitors)`](#visittree-visitorvisitors)
    *   [`CONTINUE`](#continue)
    *   [`EXIT`](#exit)
    *   [`SKIP`](#skip)
    *   [`Action`](#action)
    *   [`ActionTuple`](#actiontuple)
    *   [`Index`](#index)
    *   [`Visitor`](#visitor)
    *   [`Visitors`](#visitors)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package is a utility that helps you walk the tree.

## When should I use this?

This package helps when dealing with JavaScript ASTs.
Use [`unist-util-visit`][unist-util-visit] for other unist ASTs.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install estree-util-visit
```

In Deno with [`esm.sh`][esmsh]:

```js
import {visit} from 'https://esm.sh/estree-util-visit@2'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {visit} from 'https://esm.sh/estree-util-visit@2?bundle'
</script>
```

## Use

```js
import {parse} from 'acorn'
import {visit} from 'estree-util-visit'

const tree = parse(
  'export function x() { console.log(1 + "2"); process.exit(3) }',
  {sourceType: 'module', ecmaVersion: 2020}
)

visit(tree, function (node) {
  if (node.type === 'Literal' && 'value' in node) console.log(node.value)
})

// Both enter and leave:
walk(tree, {
  enter(node, field, index, parents) { /* … */ },
  leave(node, field, index, parents) { /* … */ }
})
```

Yields:

```txt
1
"2"
3
```

## API

This package exports the identifiers [`CONTINUE`][api-continue],
[`EXIT`][api-exit],
[`SKIP`][api-skip], and
[`visit`][api-visit].
There is no default export.

### `visit(tree, visitor|visitors)`

Visit nodes, with ancestral information.

This algorithm performs [*depth-first*][depth-first]
[*tree traversal*][tree-traversal] in [*preorder*][preorder] (**NLR**) and/or
[*postorder*][postorder] (**LRN**).

Compared to other estree walkers, this does not need a dictionary of which
fields are nodes, because it ducktypes instead.

Walking the tree is an intensive task.
Make use of the return values of the visitor(s) when possible.
Instead of walking a tree multiple times, walk it once, use
[`unist-util-is`][is] to check if a node matches, and then perform different
operations.

###### Parameters

*   `tree` ([`Node`][node])
    — tree to traverse
*   `visitor` ([`Visitor`][api-visitor])
    — same as passing `{enter: visitor}`
*   `visitors` ([`Visitors`][api-visitors])
    — handle each node

###### Returns

Nothing (`undefined`).

### `CONTINUE`

Continue traversing as normal (`symbol`).

### `EXIT`

Stop traversing immediately (`symbol`).

### `SKIP`

Do not traverse this node’s children (`symbol`).

### `Action`

Union of the action types (TypeScript type).

###### Type

```ts
type Action = typeof CONTINUE | typeof EXIT | typeof SKIP
```

### `ActionTuple`

List with one or two values, the first an action, the second an index
(TypeScript type).

###### Type

```ts
type ActionTuple = [
  (Action | null | undefined | void)?,
  (Index | null | undefined)?
]
```

### `Index`

Move to the sibling at `index` next (after node itself is completely
traversed), when moving in an array (TypeScript type).

Useful if mutating the tree, such as removing the node the visitor is currently
on, or any of its previous siblings.
Results less than 0 or greater than or equal to `children.length` stop
traversing the parent.

###### Type

```ts
type Index = number
```

### `Visitor`

Handle a node (TypeScript type).

Visitors are free to transform `node`.
They can also transform the parent of node (the last of `ancestors`).

Replacing `node` itself, if `SKIP` is not returned, still causes its
descendants to be walked (which is a bug).

When adding or removing previous siblings of `node`, the `Visitor` should
return a new `Index` to specify the sibling to traverse after `node` is
traversed.
Adding or removing next siblings of `node` is handled as expected without
needing to return a new `Index`.

###### Parameters

*   `node` ([`Node`][node])
    — found node
*   `key` (`string` or `undefined`)
    — field at which `node` lives in its parent (or where a list of nodes
    lives)
*   `index` (`number` or `undefined`)
    — index where `node` lives if `parent[key]` is an array
*   `ancestors` ([`Array<Node>`][node])
    — ancestors of `node`

###### Returns

What to do next ([`Action`][api-action], [`Index`][api-index], or
[`ActionTuple`][api-action-tuple], optional).

An `Index` is treated as a tuple of `[CONTINUE, Index]`.
An `Action` is treated as a tuple of `[Action]`.

Passing a tuple back only makes sense if the `Action` is `SKIP`.
When the `Action` is `EXIT`, that action can be returned.
When the `Action` is `CONTINUE`, `Index` can be returned.

### `Visitors`

Handle nodes when entering (preorder) and leaving (postorder) (TypeScript
type).

###### Fields

*   `enter` ([`Visitor`][api-visitor], optional)
    — handle nodes when entering (preorder)
*   `leave` ([`Visitor`][api-visitor], optional)
    — handle nodes when leaving (postorder)

## Types

This package is fully typed with [TypeScript][].
It exports the additional types [`Action`][api-action],
[`ActionTuple`][api-action-tuple],
[`Index`][api-index],
[`Visitor`][api-visitor], and
[`Visitors`][api-visitors].

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, `estree-util-visit@^2`,
compatible with Node.js 16.

## Related

*   [`unist-util-visit`](https://github.com/syntax-tree/unist-util-visit)
    — walk any unist tree

## Contribute

See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
ways to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definition -->

[build-badge]: https://github.com/syntax-tree/estree-util-visit/workflows/main/badge.svg

[build]: https://github.com/syntax-tree/estree-util-visit/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/estree-util-visit.svg

[coverage]: https://codecov.io/github/syntax-tree/estree-util-visit

[downloads-badge]: https://img.shields.io/npm/dm/estree-util-visit.svg

[downloads]: https://www.npmjs.com/package/estree-util-visit

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=estree-util-visit

[size]: https://bundlejs.com/?q=estree-util-visit

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/syntax-tree/unist/discussions

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[typescript]: https://www.typescriptlang.org

[license]: license

[author]: https://wooorm.com

[health]: https://github.com/syntax-tree/.github

[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md

[support]: https://github.com/syntax-tree/.github/blob/main/support.md

[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md

[esast]: https://github.com/syntax-tree/esast

[estree]: https://github.com/estree/estree

[depth-first]: https://github.com/syntax-tree/unist#depth-first-traversal

[tree-traversal]: https://github.com/syntax-tree/unist#tree-traversal

[preorder]: https://github.com/syntax-tree/unist#preorder

[postorder]: https://github.com/syntax-tree/unist#postorder

[is]: https://github.com/syntax-tree/unist-util-is

[node]: https://github.com/syntax-tree/esast#node

[unist-util-visit]: https://github.com/syntax-tree/unist-util-visit

[api-continue]: #continue

[api-action]: #action

[api-action-tuple]: #actiontuple

[api-exit]: #exit

[api-index]: #index

[api-skip]: #skip

[api-visit]: #visittree-visitorvisitors

[api-visitor]: #visitor

[api-visitors]: #visitors


---

# estree-walker

Simple utility for walking an [ESTree](https://github.com/estree/estree)-compliant AST, such as one generated by [acorn](https://github.com/marijnh/acorn).


## Installation

```bash
npm i estree-walker
```


## Usage

```js
var walk = require('estree-walker').walk;
var acorn = require('acorn');

ast = acorn.parse(sourceCode, options); // https://github.com/acornjs/acorn

walk(ast, {
  enter(node, parent, prop, index) {
    // some code happens
  },
  leave(node, parent, prop, index) {
    // some code happens
  }
});
```

Inside the `enter` function, calling `this.skip()` will prevent the node's children being walked, or the `leave` function (which is optional) being called.

Call `this.replace(new_node)` in either `enter` or `leave` to replace the current node with a new one.

Call `this.remove()` in either `enter` or `leave` to remove the current node.

## Why not use estraverse?

The ESTree spec is evolving to accommodate ES6/7. I've had a couple of experiences where [estraverse](https://github.com/estools/estraverse) was unable to handle an AST generated by recent versions of acorn, because it hard-codes visitor keys.

estree-walker, by contrast, simply enumerates a node's properties to find child nodes (and child lists of nodes), and is therefore resistant to spec changes. It's also much smaller. (The performance, if you're wondering, is basically identical.)

None of which should be taken as criticism of estraverse, which has more features and has been battle-tested in many more situations, and for which I'm very grateful.


## License

MIT


---

### esutils [![Build Status](https://secure.travis-ci.org/estools/esutils.svg)](http://travis-ci.org/estools/esutils)
esutils ([esutils](http://github.com/estools/esutils)) is
utility box for ECMAScript language tools.

### API

### ast

#### ast.isExpression(node)

Returns true if `node` is an Expression as defined in ECMA262 edition 5.1 section
[11](https://es5.github.io/#x11).

#### ast.isStatement(node)

Returns true if `node` is a Statement as defined in ECMA262 edition 5.1 section
[12](https://es5.github.io/#x12).

#### ast.isIterationStatement(node)

Returns true if `node` is an IterationStatement as defined in ECMA262 edition
5.1 section [12.6](https://es5.github.io/#x12.6).

#### ast.isSourceElement(node)

Returns true if `node` is a SourceElement as defined in ECMA262 edition 5.1
section [14](https://es5.github.io/#x14).

#### ast.trailingStatement(node)

Returns `Statement?` if `node` has trailing `Statement`.
```js
if (cond)
    consequent;
```
When taking this `IfStatement`, returns `consequent;` statement.

#### ast.isProblematicIfStatement(node)

Returns true if `node` is a problematic IfStatement. If `node` is a problematic `IfStatement`, `node` cannot be represented as an one on one JavaScript code.
```js
{
    type: 'IfStatement',
    consequent: {
        type: 'WithStatement',
        body: {
            type: 'IfStatement',
            consequent: {type: 'EmptyStatement'}
        }
    },
    alternate: {type: 'EmptyStatement'}
}
```
The above node cannot be represented as a JavaScript code, since the top level `else` alternate belongs to an inner `IfStatement`.


### code

#### code.isDecimalDigit(code)

Return true if provided code is decimal digit.

#### code.isHexDigit(code)

Return true if provided code is hexadecimal digit.

#### code.isOctalDigit(code)

Return true if provided code is octal digit.

#### code.isWhiteSpace(code)

Return true if provided code is white space. White space characters are formally defined in ECMA262.

#### code.isLineTerminator(code)

Return true if provided code is line terminator. Line terminator characters are formally defined in ECMA262.

#### code.isIdentifierStart(code)

Return true if provided code can be the first character of ECMA262 Identifier. They are formally defined in ECMA262.

#### code.isIdentifierPart(code)

Return true if provided code can be the trailing character of ECMA262 Identifier. They are formally defined in ECMA262.

### keyword

#### keyword.isKeywordES5(id, strict)

Returns `true` if provided identifier string is a Keyword or Future Reserved Word
in ECMA262 edition 5.1. They are formally defined in ECMA262 sections
[7.6.1.1](http://es5.github.io/#x7.6.1.1) and [7.6.1.2](http://es5.github.io/#x7.6.1.2),
respectively. If the `strict` flag is truthy, this function additionally checks whether
`id` is a Keyword or Future Reserved Word under strict mode.

#### keyword.isKeywordES6(id, strict)

Returns `true` if provided identifier string is a Keyword or Future Reserved Word
in ECMA262 edition 6. They are formally defined in ECMA262 sections
[11.6.2.1](http://ecma-international.org/ecma-262/6.0/#sec-keywords) and
[11.6.2.2](http://ecma-international.org/ecma-262/6.0/#sec-future-reserved-words),
respectively. If the `strict` flag is truthy, this function additionally checks whether
`id` is a Keyword or Future Reserved Word under strict mode.

#### keyword.isReservedWordES5(id, strict)

Returns `true` if provided identifier string is a Reserved Word in ECMA262 edition 5.1.
They are formally defined in ECMA262 section [7.6.1](http://es5.github.io/#x7.6.1).
If the `strict` flag is truthy, this function additionally checks whether `id`
is a Reserved Word under strict mode.

#### keyword.isReservedWordES6(id, strict)

Returns `true` if provided identifier string is a Reserved Word in ECMA262 edition 6.
They are formally defined in ECMA262 section [11.6.2](http://ecma-international.org/ecma-262/6.0/#sec-reserved-words).
If the `strict` flag is truthy, this function additionally checks whether `id`
is a Reserved Word under strict mode.

#### keyword.isRestrictedWord(id)

Returns `true` if provided identifier string is one of `eval` or `arguments`.
They are restricted in strict mode code throughout ECMA262 edition 5.1 and
in ECMA262 edition 6 section [12.1.1](http://ecma-international.org/ecma-262/6.0/#sec-identifiers-static-semantics-early-errors).

#### keyword.isIdentifierNameES5(id)

Return true if provided identifier string is an IdentifierName as specified in
ECMA262 edition 5.1 section [7.6](https://es5.github.io/#x7.6).

#### keyword.isIdentifierNameES6(id)

Return true if provided identifier string is an IdentifierName as specified in
ECMA262 edition 6 section [11.6](http://ecma-international.org/ecma-262/6.0/#sec-names-and-keywords).

#### keyword.isIdentifierES5(id, strict)

Return true if provided identifier string is an Identifier as specified in
ECMA262 edition 5.1 section [7.6](https://es5.github.io/#x7.6). If the `strict`
flag is truthy, this function additionally checks whether `id` is an Identifier
under strict mode.

#### keyword.isIdentifierES6(id, strict)

Return true if provided identifier string is an Identifier as specified in
ECMA262 edition 6 section [12.1](http://ecma-international.org/ecma-262/6.0/#sec-identifiers).
If the `strict` flag is truthy, this function additionally checks whether `id`
is an Identifier under strict mode.

### License

Copyright (C) 2013 [Yusuke Suzuki](http://github.com/Constellation)
 (twitter: [@Constellation](http://twitter.com/Constellation)) and other contributors.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

  * Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.

  * Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in the
    documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


---

<p align="center">
  <img align="center" width="50%" src="https://user-images.githubusercontent.com/25597854/93541153-d8c8fe80-f912-11ea-9e65-a0089ca6d2b6.png">
</p>

<h1 align="center" style="text-align: center; width: fit-content; margin-left: auto; margin-right: auto;">eta (η)</h1>

<p align="center">
  <a href="https://eta.js.org">Documentation</a> -
  <a href="https://gitter.im/eta-dev/community">Chat</a> -
  <a href="https://runkit.com/nebrelbug/eta-simple-demo">RunKit Demo</a> -
  <a href="https://eta.js.org/playground">Playground</a>
</p>

<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->

[logo]: https://img.shields.io/badge/all_contributors-10-orange.svg "Number of contributors on All-Contributors"

<!-- ALL-CONTRIBUTORS-BADGE:END -->

<span align="center">

[![GitHub package.json version (master)](https://img.shields.io/github/package-json/v/eta-dev/eta/master?label=current%20version)](https://www.npmjs.com/package/eta)
[![deno module](https://img.shields.io/badge/deno-module-informational?logo=deno)](https://deno.land/x/eta)
[![Travis](https://img.shields.io/travis/com/eta-dev/eta/master.svg)](https://travis-ci.com/eta-dev/eta)
[![All Contributors][logo]](#contributors-)
[![Coveralls](https://img.shields.io/coveralls/eta-dev/eta.svg)](https://coveralls.io/github/eta-dev/eta)
[![Donate](https://img.shields.io/badge/donate-paypal-blue.svg)](https://paypal.me/bengubler)

</span>

**Summary**

Eta is a lightweight and blazing fast embedded JS templating engine that works inside Node, Deno, and the browser. Created by the developers of [Squirrelly](https://squirrelly.js.org), it's written in TypeScript and emphasizes phenomenal performance, configurability, and low bundle size.

### 🌟 Features

- 📦 0 dependencies
- 💡 2.3KB minzipped; size restricted to <3KB forever with [size-limit](https://github.com/ai/size-limit)
- ⚡️ Written in TypeScript
- ✨ Deno support (+ Node and browser)
- 🚀 Super Fast
  - Check out [these benchmarks](https://raw.githack.com/eta-dev/eta/master/browser-tests/benchmark.html)
- 🔧 Configurable
  - Plugins, custom delimiters, caching
- 🔨 Powerful
  - Precompilation, partials, async
  - **Layout support**!
  - ExpressJS support out-of-the-box
- 🔥 Reliable
  - Better quotes/comments support
    - _ex._ `<%= someval + "string %>" %>` compiles correctly, while it fails with doT or EJS
  - Great error reporting
- ⚡️ Exports ES Modules as well as UMD
- 📝 Easy template syntax

## Eta vs other template engines

<details open>
  <summary>
  <b>Eta vs EJS</b>
  </summary>
  
Eta's syntax is very similar to EJS' (most templates should work with either engine), Eta has a similar API, and Eta and EJS share the same file-handling logic. Here are the differences between Eta and EJS:

- Eta is more lightweight. Eta weighs less than **2.5KB gzipped**, while EJS is **4.4KB gzipped**
- Eta compiles and renders templates **_much_ faster than EJS**. Check out these benchmarks: https://rawgit.com/eta-dev/eta/master/browser-tests/benchmark.html
- Eta allows left whitespace control (with `-`), something that doesn't work in EJS because EJS uses `-` on the left side to indicate that the value shouldn't be escaped. Instead, Eta uses `~` to output a raw value
- Eta gives you more flexibility with delimeters -- you could set them to `{{` and `}}`, for example, while with EJS this isn't possible
- Eta adds plugin support
- Comments in Eta use `/* ... */` which allows commenting around template tags
- Eta parses strings correctly. _Example: `<%= "%>" %>` works in Eta, while it breaks in EJS_
- Eta exposes Typescript types and distributes a UMD build
- Eta supports custom tag-type indicators. _Example: you could change `<%=` to `<%*`_

</details>

<details>
  <summary>
  <b>Eta vs doT.js</b>
  </summary>

Eta and doT.js both allow embedded JavaScript, and [both have best-in-class performance](https://ghcdn.rawgit.org/eta-dev/eta/master/browser-tests/benchmark.html) when compared to other template engines (though Eta is slightly faster with HTML-escaped templates). Here are some of the differences between Eta and doT.js:

- Eta allows you to control how you strip preceding and trailing whitespace after tags.
- It's much simpler to set custom delimiters with Eta than doT -- you don't have to rewrite every configuration Regular Expression
- Eta supports plugins
- Eta supports async
- Eta parses strings and multi-line comments correctly. _Example: `<%= "%>" %>` works in Eta, while the equivalent breaks in doT_
- Eta exposes Typescript types and distributes a UMD build
- Eta supports runtime partials and file-handling.

</details>

<details>
  <summary>
  <b>Eta vs Handlebars</b>
  </summary>
  
Eta and Handlebars are very different in some ways -- Eta is an embedded template engine, while Handlebars is a logic-less template engine. Here some additional differences between Eta and Handlebars:

- Eta is more lightweight. Eta weighs less than **2.5KB gzipped**, while Handlebars is **~22KB gzipped**
- Eta compiles and renders templates **_much_ faster than Handlebars** -- around **7x faster**. Check out these benchmarks: https://ghcdn.rawgit.org/eta-dev/eta/master/browser-tests/benchmark.html
- Eta allows you to set custom delimiters
- Eta supports plugins
- Eta exposes Typescript types and distributes a UMD build
- Custom tag-type indicators. _Example: you could change `<%=` to `<%*`_
- With Eta, you don't need to register tons of helpers to do simple tasks like check if one value equals another value
- Note that Eta templates run as **trusted code** -- just like any other JavaScript you write.<br><br>If you are running user-defined/created templates on your machine, server, site, etc., you probably should go with a tool built for that purpose, like Handlebars.

</details>

<details>
  <summary>
  <b>Eta vs ES6 Template Literals</b>
  </summary>

Template literals are a super useful tool, especially for shortening simple string concatenation. But writing complete templates using template literals can quickly get out of hand. Here's a comparison of Eta and template literals:

- Eta compiles templates into JavaScript functions that use string concatenation and have comparable performance with template literals
- Eta lets you control preceding and trailing whitespace around tags
- Eta gives you more flexibility with delimeters -- you could set them to `{{` and `}}`, for example, or set them to `${` and `}` to mimic template literals
- Eta supports plugins
- Eta supports comments with `/* ... */` syntax, just like in regular JavaScript. Template literals require you to stick a blank string after the comment: `/* ... */""`, which is much less readable
- To write conditionals inside template literals, you have to use the ternary operator. Add more conditions or nested conditionals, and it quickly becomes a nightmarish mess of `? ... : ... ? ... : ...`. Writing conditionals in Eta is much simpler and more readable
- Eta supports partials

</details>

## Why Eta?

Simply put, Eta is super: super lightweight, super fast, super powerful, and super simple. Like with EJS, you don't have to worry about learning an entire new templating syntax. Just write JavaScript inside your templates.

### Where did Eta's name come from?

"Eta" means tiny in Esperanto. Plus, it can be used as an acronym for all sorts of cool phrases: "ECMAScript Template Awesomeness", "Embedded Templating Alternative", etc....

Additionally, Eta is a letter of the Greek alphabet (it stands for all sorts of cool things in various mathematical fields, including efficiency) and is three letters long (perfect for a file extension).

## Integrations

<details>
  <summary>
    <b>Visual Studio Code</b>
  </summary>

[@shadowtime2000](https://github.com/shadowtime2000) created [eta-vscode](https://marketplace.visualstudio.com/items?itemName=shadowtime2000.eta-vscode).

</details>

<details>
  <summary>
    <b>ESLint</b>
  </summary>

[eslint-plugin-eta](https://github.com/eta-dev/eslint-plugin-eta) was created to provide an ESLint processor so you can lint your Eta templates.

</details>

<details>
  <summary>
    <b>CLI</b>
  </summary>

An official Eta CLI exists called [etajs-cli](https://github.com/eta-dev/etajs-cli).

</details>

<details>
  <summary>
    <b>Webpack</b>
  </summary>

Currently there is no official Webpack integration but [@clshortfuse](https://github.com/clshortfuse) shared the loader he uses:

```javascript
{
  loader: 'html-loader',
  options: {
    preprocessor(content, loaderContext) {
      return eta.render(content, {}, { filename: loaderContext.resourcePath });
    },
  },
}
```

</details>
  
<details>
  <summary>
    <b>Node-RED</b>
  </summary>

To operate with Eta templates in Node-RED: [@ralphwetzel/node-red-contrib-eta](https://flows.nodered.org/node/@ralphwetzel/node-red-contrib-eta)

  <img width="150" alt="image" src="https://user-images.githubusercontent.com/16342003/160198427-2a69ff10-e8bf-4873-9d99-2929a584ccc8.png">

</details>

## 📜 Docs

We know nobody reads through the long and boring documentation in the ReadMe anyway, so head over to the documentation website:

📝 [https://eta.js.org](https://eta.js.org)

## 📓 Examples

### Simple Template

```javascript
import * as Eta from "eta";
var myTemplate = "<p>My favorite kind of cake is: <%= it.favoriteCake %></p>";

Eta.render(myTemplate, { favoriteCake: "Chocolate!" });
// Returns: '<p>My favorite kind of cake is: Chocolate!</p>'
```

### Conditionals

```ejs
<% if(it.somevalue === 1) { %>
Display this
<% } else { %>
Display this instead
<% } %>
```

### Loops

```ejs
<ul>
<% it.users.forEach(function(user){ %>
<li><%= user.name %></li>
<% }) %>
</ul>
```

### Partials

```ejs
<%~ include('mypartial') %>
```

```ejs
<%~ includeFile('./footer') %>
```

```ejs
<%~ include('users', {users: it.users}) %>
```

## ✔️ Tests

Tests can be run with `npm test`. Multiple tests check that parsing, rendering, and compiling return expected results, formatting follows guidelines, and code coverage is at the expected level.

## Resources

To be added

## Projects using `eta`

- [Docusaurus v2](https://v2.docusaurus.io): open-source documentation framework that uses Eta to generate a SSR build
- [swagger-typescript-api](https://github.com/acacode/swagger-typescript-api): Open source typescript api codegenerator from Swagger. Uses Eta as codegenerator by templates
- [html-bundler-webpack-plugin](https://github.com/webdiscus/html-bundler-webpack-plugin): Webpack plugin make easily to bundle HTML pages from templates, source styles and scripts
- [SmartDeno](https://github.com/guildenstern70/SmartDeno): SmartDeno is an easy to setup web template using Deno & Oak  
- [Add yours!](https://github.com/eta-dev/eta/edit/master/README.md)

## Contributors

Made with ❤ by [@nebrelbug](https://github.com/eta-dev) and all these wonderful contributors ([emoji key](https://github.com/kentcdodds/all-contributors#emoji-key)):

<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
<!-- prettier-ignore-start -->
<!-- markdownlint-disable -->
<table>
  <tbody>
    <tr>
      <td align="center" valign="top" width="14.28%"><a href="http://www.bengubler.com"><img src="https://avatars3.githubusercontent.com/u/25597854?v=4?s=100" width="100px;" alt="Ben Gubler"/><br /><sub><b>Ben Gubler</b></sub></a><br /><a href="https://github.com/eta-dev/eta/commits?author=nebrelbug" title="Code">💻</a> <a href="#question-nebrelbug" title="Answering Questions">💬</a> <a href="https://github.com/eta-dev/eta/commits?author=nebrelbug" title="Documentation">📖</a> <a href="https://github.com/eta-dev/eta/commits?author=nebrelbug" title="Tests">⚠️</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://github.com/clitetailor"><img src="https://avatars1.githubusercontent.com/u/16368559?v=4?s=100" width="100px;" alt="Clite Tailor"/><br /><sub><b>Clite Tailor</b></sub></a><br /><a href="#ideas-clitetailor" title="Ideas, Planning, & Feedback">🤔</a> <a href="https://github.com/eta-dev/eta/commits?author=clitetailor" title="Code">💻</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://twitter.com/ioan_chiriac"><img src="https://avatars2.githubusercontent.com/u/173203?v=4?s=100" width="100px;" alt="Ioan CHIRIAC"/><br /><sub><b>Ioan CHIRIAC</b></sub></a><br /><a href="https://github.com/eta-dev/eta/commits?author=ichiriac" title="Code">💻</a> <a href="#ideas-ichiriac" title="Ideas, Planning, & Feedback">🤔</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://www.linkedin.com/in/craig-morten/"><img src="https://avatars1.githubusercontent.com/u/46491566?v=4?s=100" width="100px;" alt="Craig Morten"/><br /><sub><b>Craig Morten</b></sub></a><br /><a href="https://github.com/eta-dev/eta/commits?author=asos-craigmorten" title="Code">💻</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://github.com/trojanh"><img src="https://avatars0.githubusercontent.com/u/22974490?v=4?s=100" width="100px;" alt="Rajan Tiwari"/><br /><sub><b>Rajan Tiwari</b></sub></a><br /><a href="#example-trojanh" title="Examples">💡</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://shadowtime2000.github.io"><img src="https://avatars1.githubusercontent.com/u/66655515?v=4?s=100" width="100px;" alt="shadowtime2000"/><br /><sub><b>shadowtime2000</b></sub></a><br /><a href="https://github.com/eta-dev/eta/commits?author=shadowtime2000" title="Code">💻</a> <a href="#ideas-shadowtime2000" title="Ideas, Planning, & Feedback">🤔</a> <a href="https://github.com/eta-dev/eta/commits?author=shadowtime2000" title="Tests">⚠️</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://hamidihamza.com"><img src="https://avatars0.githubusercontent.com/u/22576950?v=4?s=100" width="100px;" alt="Hamza Hamidi"/><br /><sub><b>Hamza Hamidi</b></sub></a><br /><a href="https://github.com/eta-dev/eta/commits?author=hamzahamidi" title="Documentation">📖</a></td>
    </tr>
    <tr>
      <td align="center" valign="top" width="14.28%"><a href="http://calumk.com"><img src="https://avatars1.githubusercontent.com/u/1183991?v=4?s=100" width="100px;" alt="Calum Knott"/><br /><sub><b>Calum Knott</b></sub></a><br /><a href="#ideas-calumk" title="Ideas, Planning, & Feedback">🤔</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://github.com/nhaef"><img src="https://avatars.githubusercontent.com/u/16443053?v=4?s=100" width="100px;" alt="nhaef"/><br /><sub><b>nhaef</b></sub></a><br /><a href="https://github.com/eta-dev/eta/commits?author=nhaef" title="Code">💻</a></td>
      <td align="center" valign="top" width="14.28%"><a href="http://heyhey.to/Gün"><img src="https://avatars.githubusercontent.com/u/74139498?v=4?s=100" width="100px;" alt="Gün"/><br /><sub><b>Gün</b></sub></a><br /><a href="https://github.com/eta-dev/eta/commits?author=gurgunday" title="Code">💻</a></td>
    </tr>
  </tbody>
</table>

<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->

<!-- ALL-CONTRIBUTORS-LIST:END -->

This project follows the [all-contributors](https://github.com/kentcdodds/all-contributors) specification. Contributions of any kind are welcome!

## Credits

- Async support and file handling were added based on code from [EJS](https://github.com/mde/ejs), which is licensed under the Apache-2.0 license. Code was modified and refactored to some extent.
- Syntax and some parts of compilation are heavily based off EJS, Nunjucks, and doT.


---

1.8.1 / 2017-09-12
==================

  * perf: replace regular expression with substring

1.8.0 / 2017-02-18
==================

  * Use SHA1 instead of MD5 for ETag hashing
    - Improves performance for larger entities
    - Works with FIPS 140-2 OpenSSL configuration

1.7.0 / 2015-06-08
==================

  * Always include entity length in ETags for hash length extensions
  * Generate non-Stats ETags using MD5 only (no longer CRC32)
  * Improve stat performance by removing hashing
  * Remove base64 padding in ETags to shorten
  * Use MD5 instead of MD4 in weak ETags over 1KB

1.6.0 / 2015-05-10
==================

  * Improve support for JXcore
  * Remove requirement of `atime` in the stats object
  * Support "fake" stats objects in environments without `fs`

1.5.1 / 2014-11-19
==================

  * deps: crc@3.2.1
    - Minor fixes

1.5.0 / 2014-10-14
==================

  * Improve string performance
  * Slightly improve speed for weak ETags over 1KB

1.4.0 / 2014-09-21
==================

  * Support "fake" stats objects
  * Support Node.js 0.6

1.3.1 / 2014-09-14
==================

  * Use the (new and improved) `crc` for crc32

1.3.0 / 2014-08-29
==================

  * Default strings to strong ETags
  * Improve speed for weak ETags over 1KB

1.2.1 / 2014-08-29
==================

  * Use the (much faster) `buffer-crc32` for crc32

1.2.0 / 2014-08-24
==================

  * Add support for file stat objects

1.1.0 / 2014-08-24
==================

  * Add fast-path for empty entity
  * Add weak ETag generation
  * Shrink size of generated ETags

1.0.1 / 2014-08-24
==================

  * Fix behavior of string containing Unicode

1.0.0 / 2014-05-18
==================

  * Initial release


---

# etag

[![NPM Version][npm-image]][npm-url]
[![NPM Downloads][downloads-image]][downloads-url]
[![Node.js Version][node-version-image]][node-version-url]
[![Build Status][travis-image]][travis-url]
[![Test Coverage][coveralls-image]][coveralls-url]

Create simple HTTP ETags

This module generates HTTP ETags (as defined in RFC 7232) for use in
HTTP responses.

## Installation

This is a [Node.js](https://nodejs.org/en/) module available through the
[npm registry](https://www.npmjs.com/). Installation is done using the
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):

```sh
$ npm install etag
```

## API

<!-- eslint-disable no-unused-vars -->

```js
var etag = require('etag')
```

### etag(entity, [options])

Generate a strong ETag for the given entity. This should be the complete
body of the entity. Strings, `Buffer`s, and `fs.Stats` are accepted. By
default, a strong ETag is generated except for `fs.Stats`, which will
generate a weak ETag (this can be overwritten by `options.weak`).

<!-- eslint-disable no-undef -->

```js
res.setHeader('ETag', etag(body))
```

#### Options

`etag` accepts these properties in the options object.

##### weak

Specifies if the generated ETag will include the weak validator mark (that
is, the leading `W/`). The actual entity tag is the same. The default value
is `false`, unless the `entity` is `fs.Stats`, in which case it is `true`.

## Testing

```sh
$ npm test
```

## Benchmark

```bash
$ npm run-script bench

> etag@1.8.1 bench nodejs-etag
> node benchmark/index.js

  http_parser@2.7.0
  node@6.11.1
  v8@5.1.281.103
  uv@1.11.0
  zlib@1.2.11
  ares@1.10.1-DEV
  icu@58.2
  modules@48
  openssl@1.0.2k

> node benchmark/body0-100b.js

  100B body

  4 tests completed.

  buffer - strong x 258,647 ops/sec ±1.07% (180 runs sampled)
  buffer - weak   x 263,812 ops/sec ±0.61% (184 runs sampled)
  string - strong x 259,955 ops/sec ±1.19% (185 runs sampled)
  string - weak   x 264,356 ops/sec ±1.09% (184 runs sampled)

> node benchmark/body1-1kb.js

  1KB body

  4 tests completed.

  buffer - strong x 189,018 ops/sec ±1.12% (182 runs sampled)
  buffer - weak   x 190,586 ops/sec ±0.81% (186 runs sampled)
  string - strong x 144,272 ops/sec ±0.96% (188 runs sampled)
  string - weak   x 145,380 ops/sec ±1.43% (187 runs sampled)

> node benchmark/body2-5kb.js

  5KB body

  4 tests completed.

  buffer - strong x 92,435 ops/sec ±0.42% (188 runs sampled)
  buffer - weak   x 92,373 ops/sec ±0.58% (189 runs sampled)
  string - strong x 48,850 ops/sec ±0.56% (186 runs sampled)
  string - weak   x 49,380 ops/sec ±0.56% (190 runs sampled)

> node benchmark/body3-10kb.js

  10KB body

  4 tests completed.

  buffer - strong x 55,989 ops/sec ±0.93% (188 runs sampled)
  buffer - weak   x 56,148 ops/sec ±0.55% (190 runs sampled)
  string - strong x 27,345 ops/sec ±0.43% (188 runs sampled)
  string - weak   x 27,496 ops/sec ±0.45% (190 runs sampled)

> node benchmark/body4-100kb.js

  100KB body

  4 tests completed.

  buffer - strong x 7,083 ops/sec ±0.22% (190 runs sampled)
  buffer - weak   x 7,115 ops/sec ±0.26% (191 runs sampled)
  string - strong x 3,068 ops/sec ±0.34% (190 runs sampled)
  string - weak   x 3,096 ops/sec ±0.35% (190 runs sampled)

> node benchmark/stats.js

  stat

  4 tests completed.

  real - strong x 871,642 ops/sec ±0.34% (189 runs sampled)
  real - weak   x 867,613 ops/sec ±0.39% (190 runs sampled)
  fake - strong x 401,051 ops/sec ±0.40% (189 runs sampled)
  fake - weak   x 400,100 ops/sec ±0.47% (188 runs sampled)
```

## License

[MIT](LICENSE)

[npm-image]: https://img.shields.io/npm/v/etag.svg
[npm-url]: https://npmjs.org/package/etag
[node-version-image]: https://img.shields.io/node/v/etag.svg
[node-version-url]: https://nodejs.org/en/download/
[travis-image]: https://img.shields.io/travis/jshttp/etag/master.svg
[travis-url]: https://travis-ci.org/jshttp/etag
[coveralls-image]: https://img.shields.io/coveralls/jshttp/etag/master.svg
[coveralls-url]: https://coveralls.io/r/jshttp/etag?branch=master
[downloads-image]: https://img.shields.io/npm/dm/etag.svg
[downloads-url]: https://npmjs.org/package/etag


---

# Eval - require() for module content!

## Overview

This module is a simple way to evaluate a module content in the same way as require() but without loading it from a file. Effectively, it mimicks the javascript evil `eval` function but leverages Node's VM module instead.


## Benefits

Why would you be using the `eval` module over the native`require`? Most of the time `require` is fine but in some situations, I have found myself wishing for the following:

* Ability to supply a context to a module
* Ability to load the module file(s) from non node standard places

Or simply to leverage JavaScript's `eval` but with sandboxing.


## Download

It is published on node package manager (npm). To install, do:

    npm install eval


## Usage

```` javascript
var _eval = require('eval')
var res = _eval(content /*, filename, scope, includeGlobals */)
````

The following options are available:

* `content` (__String__): the content to be evaluated
* `filename` (__String__): optional dummy name to be given (used in stacktraces)
* `scope` (__Object__): scope properties are provided as variables to the content
* `includeGlobals` (__Boolean__): allow/disallow global variables (and require) to be supplied to the content (default=false)


## Examples

```` javascript
var _eval = require('eval')
var res = _eval('var x = 123; exports.x = x')
// => res === { x: 123 }

res = _eval('module.exports = function () { return 123 }')
// => res() === 123

res = _eval('module.exports = require("events")', true)
// => res === require('events')

res = _eval('exports.x = process', true)
// => res.x === process
````


## License

[Here](https://github.com/pierrec/node-eval/tree/master/LICENSE)


---

# EventEmitter3

[![Version npm](https://img.shields.io/npm/v/eventemitter3.svg?style=flat-square)](https://www.npmjs.com/package/eventemitter3)[![Build Status](https://img.shields.io/travis/primus/eventemitter3/master.svg?style=flat-square)](https://travis-ci.org/primus/eventemitter3)[![Dependencies](https://img.shields.io/david/primus/eventemitter3.svg?style=flat-square)](https://david-dm.org/primus/eventemitter3)[![Coverage Status](https://img.shields.io/coveralls/primus/eventemitter3/master.svg?style=flat-square)](https://coveralls.io/r/primus/eventemitter3?branch=master)[![IRC channel](https://img.shields.io/badge/IRC-irc.freenode.net%23primus-00a8ff.svg?style=flat-square)](https://webchat.freenode.net/?channels=primus)

[![Sauce Test Status](https://saucelabs.com/browser-matrix/eventemitter3.svg)](https://saucelabs.com/u/eventemitter3)

EventEmitter3 is a high performance EventEmitter. It has been micro-optimized
for various of code paths making this, one of, if not the fastest EventEmitter
available for Node.js and browsers. The module is API compatible with the
EventEmitter that ships by default with Node.js but there are some slight
differences:

- Domain support has been removed.
- We do not `throw` an error when you emit an `error` event and nobody is
  listening.
- The `newListener` and `removeListener` events have been removed as they
  are useful only in some uncommon use-cases.
- The `setMaxListeners`, `getMaxListeners`, `prependListener` and
  `prependOnceListener` methods are not available.
- Support for custom context for events so there is no need to use `fn.bind`.
- The `removeListener` method removes all matching listeners, not only the
  first.

It's a drop in replacement for existing EventEmitters, but just faster. Free
performance, who wouldn't want that? The EventEmitter is written in EcmaScript 3
so it will work in the oldest browsers and node versions that you need to
support.

## Installation

```bash
$ npm install --save eventemitter3
```

## CDN

Recommended CDN:

```text
https://unpkg.com/eventemitter3@latest/umd/eventemitter3.min.js
```

## Usage

After installation the only thing you need to do is require the module:

```js
var EventEmitter = require('eventemitter3');
```

And you're ready to create your own EventEmitter instances. For the API
documentation, please follow the official Node.js documentation:

http://nodejs.org/api/events.html

### Contextual emits

We've upgraded the API of the `EventEmitter.on`, `EventEmitter.once` and
`EventEmitter.removeListener` to accept an extra argument which is the `context`
or `this` value that should be set for the emitted events. This means you no
longer have the overhead of an event that required `fn.bind` in order to get a
custom `this` value.

```js
var EE = new EventEmitter()
  , context = { foo: 'bar' };

function emitted() {
  console.log(this === context); // true
}

EE.once('event-name', emitted, context);
EE.on('another-event', emitted, context);
EE.removeListener('another-event', emitted, context);
```

### Tests and benchmarks

This module is well tested. You can run:

- `npm test` to run the tests under Node.js.
- `npm run test-browser` to run the tests in real browsers via Sauce Labs.

We also have a set of benchmarks to compare EventEmitter3 with some available
alternatives. To run the benchmarks run `npm run benchmark`.

Tests and benchmarks are not included in the npm package. If you want to play
with them you have to clone the GitHub repository.
Note that you will have to run an additional `npm i` in the benchmarks folder
before `npm run benchmark`.

## License

[MIT](LICENSE)


---

# 3.3.0

 - Support EventTarget emitters in `events.once` from Node.js 12.11.0.

   Now you can use the `events.once` function with objects that implement the EventTarget interface. This interface is used widely in
   the DOM and other web APIs.

   ```js
   var events = require('events');
   var assert = require('assert');

   async function connect() {
     var ws = new WebSocket('wss://example.com');
     await events.once(ws, 'open');
     assert(ws.readyState === WebSocket.OPEN);
   }

   async function onClick() {
     await events.once(document.body, 'click');
     alert('you clicked the page!');
   }
   ```

# 3.2.0

 - Add `events.once` from Node.js 11.13.0.

   To use this function, Promises must be supported in the environment. Use a polyfill like `es6-promise` if you support older browsers.

# 3.1.0 (2020-01-08)

`events` now matches the Node.js 11.12.0 API.

  - pass through return value in wrapped `emitter.once()` listeners

    Now, this works:
    ```js
    emitter.once('myevent', function () { return 1; });
    var listener = emitter.rawListeners('myevent')[0]
    assert(listener() === 1);
    ```
    Previously, `listener()` would return undefined regardless of the implementation.

    Ported from https://github.com/nodejs/node/commit/acc506c2d2771dab8d7bba6d3452bc5180dff7cf

  - Reduce code duplication in listener type check ([#67](https://github.com/Gozala/events/pull/67) by [@friederbluemle](https://github.com/friederbluemle)).
  - Improve `emitter.once()` performance in some engines

# 3.0.0 (2018-05-25)

**This version drops support for IE8.** `events` no longer includes polyfills
for ES5 features. If you need to support older environments, use an ES5 shim
like [es5-shim](https://npmjs.com/package/es5-shim). Both the shim and sham
versions of es5-shim are necessary.

  - Update to events code from Node.js 10.x
    - (semver major) Adds `off()` method
  - Port more tests from Node.js
  - Switch browser tests to airtap, making things more reliable

# 2.1.0 (2018-05-25)

  - add Emitter#rawListeners from Node.js v9.4

# 2.0.0 (2018-02-02)

  - Update to events code from node.js 8.x
    - Adds `prependListener()` and `prependOnceListener()`
    - Adds `eventNames()` method
    - (semver major) Unwrap `once()` listeners in `listeners()`
  - copy tests from node.js

Note that this version doubles the gzipped size, jumping from 1.1KB to 2.1KB,
due to new methods and runtime performance improvements. Be aware of that when
upgrading.

# 1.1.1 (2016-06-22)

  - add more context to errors if they are not instanceof Error

# 1.1.0 (2015-09-29)

  - add Emitter#listerCount (to match node v4 api)

# 1.0.2 (2014-08-28)

  - remove un-reachable code
  - update devDeps

## 1.0.1 / 2014-05-11

  - check for console.trace before using it

## 1.0.0 / 2013-12-10

  - Update to latest events code from node.js 0.10
  - copy tests from node.js

## 0.4.0 / 2011-07-03 ##

  - Switching to graphquire@0.8.0

## 0.3.0 / 2011-07-03 ##

  - Switching to URL based module require.

## 0.2.0 / 2011-06-10 ##

  - Simplified package structure.
  - Graphquire for dependency management.

## 0.1.1 / 2011-05-16 ##

  - Unhandled errors are logged via console.error

## 0.1.0 / 2011-04-22 ##

  - Initial release


---

# events [![Build Status](https://travis-ci.org/Gozala/events.png?branch=master)](https://travis-ci.org/Gozala/events)

> Node's event emitter for all engines.

This implements the Node.js [`events`][node.js docs] module for environments that do not have it, like browsers.

> `events` currently matches the **Node.js 11.13.0** API.

Note that the `events` module uses ES5 features. If you need to support very old browsers like IE8, use a shim like [`es5-shim`](https://www.npmjs.com/package/es5-shim). You need both the shim and the sham versions of `es5-shim`.

This module is maintained, but only by very few people. If you'd like to help, let us know in the [Maintainer Needed](https://github.com/Gozala/events/issues/43) issue!

## Install

You usually do not have to install `events` yourself! If your code runs in Node.js, `events` is built in. If your code runs in the browser, bundlers like [browserify](https://github.com/browserify/browserify) or [webpack](https://github.com/webpack/webpack) also include the `events` module.

But if none of those apply, with npm do:

```
npm install events
```

## Usage

```javascript
var EventEmitter = require('events')

var ee = new EventEmitter()
ee.on('message', function (text) {
  console.log(text)
})
ee.emit('message', 'hello world')
```

## API

See the [Node.js EventEmitter docs][node.js docs]. `events` currently matches the Node.js 11.13.0 API.

## Contributing

PRs are very welcome! The main way to contribute to `events` is by porting features, bugfixes and tests from Node.js. Ideally, code contributions to this module are copy-pasted from Node.js and transpiled to ES5, rather than reimplemented from scratch. Matching the Node.js code as closely as possible makes maintenance simpler when new changes land in Node.js.
This module intends to provide exactly the same API as Node.js, so features that are not available in the core `events` module will not be accepted. Feature requests should instead be directed at [nodejs/node](https://github.com/nodejs/node) and will be added to this module once they are implemented in Node.js.

If there is a difference in behaviour between Node.js's `events` module and this module, please open an issue!

## License

[MIT](./LICENSE)

[node.js docs]: https://nodejs.org/dist/v11.13.0/docs/api/events.html


---

# Security Policy

## Supported Versions
Only the latest major version is supported at any given time.

## Reporting a Vulnerability

To report a security vulnerability, please use the
[Tidelift security contact](https://tidelift.com/security).
Tidelift will coordinate the fix and disclosure.


---

<img src="media/logo.svg" width="400">
<br>

[![Coverage Status](https://codecov.io/gh/sindresorhus/execa/branch/main/graph/badge.svg)](https://codecov.io/gh/sindresorhus/execa)

> Process execution for humans

## Why

This package improves [`child_process`](https://nodejs.org/api/child_process.html) methods with:

- Promise interface.
- [Strips the final newline](#stripfinalnewline) from the output so you don't have to do `stdout.trim()`.
- Supports [shebang](https://en.wikipedia.org/wiki/Shebang_(Unix)) binaries cross-platform.
- [Improved Windows support.](https://github.com/IndigoUnited/node-cross-spawn#why)
- Higher max buffer. 100 MB instead of 200 KB.
- [Executes locally installed binaries by name.](#preferlocal)
- [Cleans up spawned processes when the parent process dies.](#cleanup)
- [Get interleaved output](#all) from `stdout` and `stderr` similar to what is printed on the terminal. [*(Async only)*](#execasyncfile-arguments-options)
- [Can specify file and arguments as a single string without a shell](#execacommandcommand-options)
- More descriptive errors.

## Install

```
$ npm install execa
```

## Usage

```js
const execa = require('execa');

(async () => {
	const {stdout} = await execa('echo', ['unicorns']);
	console.log(stdout);
	//=> 'unicorns'
})();
```

### Pipe the child process stdout to the parent

```js
const execa = require('execa');

execa('echo', ['unicorns']).stdout.pipe(process.stdout);
```

### Handling Errors

```js
const execa = require('execa');

(async () => {
	// Catching an error
	try {
		await execa('unknown', ['command']);
	} catch (error) {
		console.log(error);
		/*
		{
			message: 'Command failed with ENOENT: unknown command spawn unknown ENOENT',
			errno: -2,
			code: 'ENOENT',
			syscall: 'spawn unknown',
			path: 'unknown',
			spawnargs: ['command'],
			originalMessage: 'spawn unknown ENOENT',
			shortMessage: 'Command failed with ENOENT: unknown command spawn unknown ENOENT',
			command: 'unknown command',
			escapedCommand: 'unknown command',
			stdout: '',
			stderr: '',
			all: '',
			failed: true,
			timedOut: false,
			isCanceled: false,
			killed: false
		}
		*/
	}

})();
```

### Cancelling a spawned process

```js
const execa = require('execa');

(async () => {
	const subprocess = execa('node');

	setTimeout(() => {
		subprocess.cancel();
	}, 1000);

	try {
		await subprocess;
	} catch (error) {
		console.log(subprocess.killed); // true
		console.log(error.isCanceled); // true
	}
})()
```

### Catching an error with the sync method

```js
try {
	execa.sync('unknown', ['command']);
} catch (error) {
	console.log(error);
	/*
	{
		message: 'Command failed with ENOENT: unknown command spawnSync unknown ENOENT',
		errno: -2,
		code: 'ENOENT',
		syscall: 'spawnSync unknown',
		path: 'unknown',
		spawnargs: ['command'],
		originalMessage: 'spawnSync unknown ENOENT',
		shortMessage: 'Command failed with ENOENT: unknown command spawnSync unknown ENOENT',
		command: 'unknown command',
		escapedCommand: 'unknown command',
		stdout: '',
		stderr: '',
		all: '',
		failed: true,
		timedOut: false,
		isCanceled: false,
		killed: false
	}
	*/
}
```

### Kill a process

Using SIGTERM, and after 2 seconds, kill it with SIGKILL.

```js
const subprocess = execa('node');

setTimeout(() => {
	subprocess.kill('SIGTERM', {
		forceKillAfterTimeout: 2000
	});
}, 1000);
```

## API

### execa(file, arguments, options?)

Execute a file. Think of this as a mix of [`child_process.execFile()`](https://nodejs.org/api/child_process.html#child_process_child_process_execfile_file_args_options_callback) and [`child_process.spawn()`](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options).

No escaping/quoting is needed.

Unless the [`shell`](#shell) option is used, no shell interpreter (Bash, `cmd.exe`, etc.) is used, so shell features such as variables substitution (`echo $PATH`) are not allowed.

Returns a [`child_process` instance](https://nodejs.org/api/child_process.html#child_process_class_childprocess) which:
  - is also a `Promise` resolving or rejecting with a [`childProcessResult`](#childProcessResult).
  - exposes the following additional methods and properties.

#### kill(signal?, options?)

Same as the original [`child_process#kill()`](https://nodejs.org/api/child_process.html#child_process_subprocess_kill_signal) except: if `signal` is `SIGTERM` (the default value) and the child process is not terminated after 5 seconds, force it by sending `SIGKILL`.

##### options.forceKillAfterTimeout

Type: `number | false`\
Default: `5000`

Milliseconds to wait for the child process to terminate before sending `SIGKILL`.

Can be disabled with `false`.

#### cancel()

Similar to [`childProcess.kill()`](https://nodejs.org/api/child_process.html#child_process_subprocess_kill_signal). This is preferred when cancelling the child process execution as the error is more descriptive and [`childProcessResult.isCanceled`](#iscanceled) is set to `true`.

#### all

Type: `ReadableStream | undefined`

Stream combining/interleaving [`stdout`](https://nodejs.org/api/child_process.html#child_process_subprocess_stdout) and [`stderr`](https://nodejs.org/api/child_process.html#child_process_subprocess_stderr).

This is `undefined` if either:
  - the [`all` option](#all-2) is `false` (the default value)
  - both [`stdout`](#stdout-1) and [`stderr`](#stderr-1) options are set to [`'inherit'`, `'ipc'`, `Stream` or `integer`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio)

### execa.sync(file, arguments?, options?)

Execute a file synchronously.

Returns or throws a [`childProcessResult`](#childProcessResult).

### execa.command(command, options?)

Same as [`execa()`](#execafile-arguments-options) except both file and arguments are specified in a single `command` string. For example, `execa('echo', ['unicorns'])` is the same as `execa.command('echo unicorns')`.

If the file or an argument contains spaces, they must be escaped with backslashes. This matters especially if `command` is not a constant but a variable, for example with `__dirname` or `process.cwd()`. Except for spaces, no escaping/quoting is needed.

The [`shell` option](#shell) must be used if the `command` uses shell-specific features (for example, `&&` or `||`), as opposed to being a simple `file` followed by its `arguments`.

### execa.commandSync(command, options?)

Same as [`execa.command()`](#execacommand-command-options) but synchronous.

Returns or throws a [`childProcessResult`](#childProcessResult).

### execa.node(scriptPath, arguments?, options?)

Execute a Node.js script as a child process.

Same as `execa('node', [scriptPath, ...arguments], options)` except (like [`child_process#fork()`](https://nodejs.org/api/child_process.html#child_process_child_process_fork_modulepath_args_options)):
  - the current Node version and options are used. This can be overridden using the [`nodePath`](#nodepath-for-node-only) and [`nodeOptions`](#nodeoptions-for-node-only) options.
  - the [`shell`](#shell) option cannot be used
  - an extra channel [`ipc`](https://nodejs.org/api/child_process.html#child_process_options_stdio) is passed to [`stdio`](#stdio)

### childProcessResult

Type: `object`

Result of a child process execution. On success this is a plain object. On failure this is also an `Error` instance.

The child process [fails](#failed) when:
- its [exit code](#exitcode) is not `0`
- it was [killed](#killed) with a [signal](#signal)
- [timing out](#timedout)
- [being canceled](#iscanceled)
- there's not enough memory or there are already too many child processes

#### command

Type: `string`

The file and arguments that were run, for logging purposes.

This is not escaped and should not be executed directly as a process, including using [`execa()`](#execafile-arguments-options) or [`execa.command()`](#execacommandcommand-options).

#### escapedCommand

Type: `string`

Same as [`command`](#command) but escaped.

This is meant to be copy and pasted into a shell, for debugging purposes.
Since the escaping is fairly basic, this should not be executed directly as a process, including using [`execa()`](#execafile-arguments-options) or [`execa.command()`](#execacommandcommand-options).

#### exitCode

Type: `number`

The numeric exit code of the process that was run.

#### stdout

Type: `string | Buffer`

The output of the process on stdout.

#### stderr

Type: `string | Buffer`

The output of the process on stderr.

#### all

Type: `string | Buffer | undefined`

The output of the process with `stdout` and `stderr` interleaved.

This is `undefined` if either:
  - the [`all` option](#all-2) is `false` (the default value)
  - `execa.sync()` was used

#### failed

Type: `boolean`

Whether the process failed to run.

#### timedOut

Type: `boolean`

Whether the process timed out.

#### isCanceled

Type: `boolean`

Whether the process was canceled.

#### killed

Type: `boolean`

Whether the process was killed.

#### signal

Type: `string | undefined`

The name of the signal that was used to terminate the process. For example, `SIGFPE`.

If a signal terminated the process, this property is defined and included in the error message. Otherwise it is `undefined`.

#### signalDescription

Type: `string | undefined`

A human-friendly description of the signal that was used to terminate the process. For example, `Floating point arithmetic error`.

If a signal terminated the process, this property is defined and included in the error message. Otherwise it is `undefined`. It is also `undefined` when the signal is very uncommon which should seldomly happen.

#### message

Type: `string`

Error message when the child process failed to run. In addition to the [underlying error message](#originalMessage), it also contains some information related to why the child process errored.

The child process [stderr](#stderr) then [stdout](#stdout) are appended to the end, separated with newlines and not interleaved.

#### shortMessage

Type: `string`

This is the same as the [`message` property](#message) except it does not include the child process stdout/stderr.

#### originalMessage

Type: `string | undefined`

Original error message. This is the same as the `message` property except it includes neither the child process stdout/stderr nor some additional information added by Execa.

This is `undefined` unless the child process exited due to an `error` event or a timeout.

### options

Type: `object`

#### cleanup

Type: `boolean`\
Default: `true`

Kill the spawned process when the parent process exits unless either:
	- the spawned process is [`detached`](https://nodejs.org/api/child_process.html#child_process_options_detached)
	- the parent process is terminated abruptly, for example, with `SIGKILL` as opposed to `SIGTERM` or a normal exit

#### preferLocal

Type: `boolean`\
Default: `false`

Prefer locally installed binaries when looking for a binary to execute.\
If you `$ npm install foo`, you can then `execa('foo')`.

#### localDir

Type: `string`\
Default: `process.cwd()`

Preferred path to find locally installed binaries in (use with `preferLocal`).

#### execPath

Type: `string`\
Default: `process.execPath` (Current Node.js executable)

Path to the Node.js executable to use in child processes.

This can be either an absolute path or a path relative to the [`cwd` option](#cwd).

Requires [`preferLocal`](#preferlocal) to be `true`.

For example, this can be used together with [`get-node`](https://github.com/ehmicky/get-node) to run a specific Node.js version in a child process.

#### buffer

Type: `boolean`\
Default: `true`

Buffer the output from the spawned process. When set to `false`, you must read the output of [`stdout`](#stdout-1) and [`stderr`](#stderr-1) (or [`all`](#all) if the [`all`](#all-2) option is `true`). Otherwise the returned promise will not be resolved/rejected.

If the spawned process fails, [`error.stdout`](#stdout), [`error.stderr`](#stderr), and [`error.all`](#all) will contain the buffered data.

#### input

Type: `string | Buffer | stream.Readable`

Write some input to the `stdin` of your binary.\
Streams are not allowed when using the synchronous methods.

#### stdin

Type: `string | number | Stream | undefined`\
Default: `pipe`

Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio).

#### stdout

Type: `string | number | Stream | undefined`\
Default: `pipe`

Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio).

#### stderr

Type: `string | number | Stream | undefined`\
Default: `pipe`

Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio).

#### all

Type: `boolean`\
Default: `false`

Add an `.all` property on the [promise](#all) and the [resolved value](#all-1). The property contains the output of the process with `stdout` and `stderr` interleaved.

#### reject

Type: `boolean`\
Default: `true`

Setting this to `false` resolves the promise with the error instead of rejecting it.

#### stripFinalNewline

Type: `boolean`\
Default: `true`

Strip the final [newline character](https://en.wikipedia.org/wiki/Newline) from the output.

#### extendEnv

Type: `boolean`\
Default: `true`

Set to `false` if you don't want to extend the environment variables when providing the `env` property.

---

Execa also accepts the below options which are the same as the options for [`child_process#spawn()`](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options)/[`child_process#exec()`](https://nodejs.org/api/child_process.html#child_process_child_process_exec_command_options_callback)

#### cwd

Type: `string`\
Default: `process.cwd()`

Current working directory of the child process.

#### env

Type: `object`\
Default: `process.env`

Environment key-value pairs. Extends automatically from `process.env`. Set [`extendEnv`](#extendenv) to `false` if you don't want this.

#### argv0

Type: `string`

Explicitly set the value of `argv[0]` sent to the child process. This will be set to `file` if not specified.

#### stdio

Type: `string | string[]`\
Default: `pipe`

Child's [stdio](https://nodejs.org/api/child_process.html#child_process_options_stdio) configuration.

#### serialization

Type: `string`\
Default: `'json'`

Specify the kind of serialization used for sending messages between processes when using the [`stdio: 'ipc'`](#stdio) option or [`execa.node()`](#execanodescriptpath-arguments-options):
	- `json`: Uses `JSON.stringify()` and `JSON.parse()`.
	- `advanced`: Uses [`v8.serialize()`](https://nodejs.org/api/v8.html#v8_v8_serialize_value)

Requires Node.js `13.2.0` or later.

[More info.](https://nodejs.org/api/child_process.html#child_process_advanced_serialization)

#### detached

Type: `boolean`

Prepare child to run independently of its parent process. Specific behavior [depends on the platform](https://nodejs.org/api/child_process.html#child_process_options_detached).

#### uid

Type: `number`

Sets the user identity of the process.

#### gid

Type: `number`

Sets the group identity of the process.

#### shell

Type: `boolean | string`\
Default: `false`

If `true`, runs `file` inside of a shell. Uses `/bin/sh` on UNIX and `cmd.exe` on Windows. A different shell can be specified as a string. The shell should understand the `-c` switch on UNIX or `/d /s /c` on Windows.

We recommend against using this option since it is:
- not cross-platform, encouraging shell-specific syntax.
- slower, because of the additional shell interpretation.
- unsafe, potentially allowing command injection.

#### encoding

Type: `string | null`\
Default: `utf8`

Specify the character encoding used to decode the `stdout` and `stderr` output. If set to `null`, then `stdout` and `stderr` will be a `Buffer` instead of a string.

#### timeout

Type: `number`\
Default: `0`

If timeout is greater than `0`, the parent will send the signal identified by the `killSignal` property (the default is `SIGTERM`) if the child runs longer than timeout milliseconds.

#### maxBuffer

Type: `number`\
Default: `100_000_000` (100 MB)

Largest amount of data in bytes allowed on `stdout` or `stderr`.

#### killSignal

Type: `string | number`\
Default: `SIGTERM`

Signal value to be used when the spawned process will be killed.

#### windowsVerbatimArguments

Type: `boolean`\
Default: `false`

If `true`, no quoting or escaping of arguments is done on Windows. Ignored on other platforms. This is set to `true` automatically when the `shell` option is `true`.

#### windowsHide

Type: `boolean`\
Default: `true`

On Windows, do not create a new console window. Please note this also prevents `CTRL-C` [from working](https://github.com/nodejs/node/issues/29837) on Windows.

#### nodePath *(For `.node()` only)*

Type: `string`\
Default: [`process.execPath`](https://nodejs.org/api/process.html#process_process_execpath)

Node.js executable used to create the child process.

#### nodeOptions *(For `.node()` only)*

Type: `string[]`\
Default: [`process.execArgv`](https://nodejs.org/api/process.html#process_process_execargv)

List of [CLI options](https://nodejs.org/api/cli.html#cli_options) passed to the Node.js executable.

## Tips

### Retry on error

Gracefully handle failures by using automatic retries and exponential backoff with the [`p-retry`](https://github.com/sindresorhus/p-retry) package:

```js
const pRetry = require('p-retry');

const run = async () => {
	const results = await execa('curl', ['-sSL', 'https://sindresorhus.com/unicorn']);
	return results;
};

(async () => {
	console.log(await pRetry(run, {retries: 5}));
})();
```

### Save and pipe output from a child process

Let's say you want to show the output of a child process in real-time while also saving it to a variable.

```js
const execa = require('execa');

const subprocess = execa('echo', ['foo']);
subprocess.stdout.pipe(process.stdout);

(async () => {
	const {stdout} = await subprocess;
	console.log('child output:', stdout);
})();
```

### Redirect output to a file

```js
const execa = require('execa');

const subprocess = execa('echo', ['foo'])
subprocess.stdout.pipe(fs.createWriteStream('stdout.txt'))
```

### Redirect input from a file

```js
const execa = require('execa');

const subprocess = execa('cat')
fs.createReadStream('stdin.txt').pipe(subprocess.stdin)
```

### Execute the current package's binary

```js
const {getBinPathSync} = require('get-bin-path');

const binPath = getBinPathSync();
const subprocess = execa(binPath);
```

`execa` can be combined with [`get-bin-path`](https://github.com/ehmicky/get-bin-path) to test the current package's binary. As opposed to hard-coding the path to the binary, this validates that the `package.json` `bin` field is correctly set up.

## Related

- [gulp-execa](https://github.com/ehmicky/gulp-execa) - Gulp plugin for `execa`
- [nvexeca](https://github.com/ehmicky/nvexeca) - Run `execa` using any Node.js version
- [sudo-prompt](https://github.com/jorangreef/sudo-prompt) - Run commands with elevated privileges.

## Maintainers

- [Sindre Sorhus](https://github.com/sindresorhus)
- [@ehmicky](https://github.com/ehmicky)

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-execa?utm_source=npm-execa&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

4.21.2 / 2024-11-06
==========

  * deps: path-to-regexp@0.1.12
    - Fix backtracking protection
  * deps: path-to-regexp@0.1.11
    - Throws an error on invalid path values

4.21.1 / 2024-10-08
==========

  * Backported a fix for [CVE-2024-47764](https://nvd.nist.gov/vuln/detail/CVE-2024-47764)


4.21.0 / 2024-09-11
==========

  * Deprecate `res.location("back")` and `res.redirect("back")` magic string
  * deps: serve-static@1.16.2
    * includes send@0.19.0
  * deps: finalhandler@1.3.1
  * deps: qs@6.13.0

4.20.0 / 2024-09-10
==========
  * deps: serve-static@0.16.0
    * Remove link renderization in html while redirecting
  * deps: send@0.19.0
    * Remove link renderization in html while redirecting
  * deps: body-parser@0.6.0
    * add `depth` option to customize the depth level in the parser
    * IMPORTANT: The default `depth` level for parsing URL-encoded data is now `32` (previously was `Infinity`)
  * Remove link renderization in html while using `res.redirect`
  * deps: path-to-regexp@0.1.10
    - Adds support for named matching groups in the routes using a regex
    - Adds backtracking protection to parameters without regexes defined
  * deps: encodeurl@~2.0.0
    - Removes encoding of `\`, `|`, and `^` to align better with URL spec
  * Deprecate passing `options.maxAge` and `options.expires` to `res.clearCookie`
    - Will be ignored in v5, clearCookie will set a cookie with an expires in the past to instruct clients to delete the cookie

4.19.2 / 2024-03-25
==========

  * Improved fix for open redirect allow list bypass

4.19.1 / 2024-03-20
==========

  * Allow passing non-strings to res.location with new encoding handling checks

4.19.0 / 2024-03-20
==========

  * Prevent open redirect allow list bypass due to encodeurl
  * deps: cookie@0.6.0

4.18.3 / 2024-02-29
==========

  * Fix routing requests without method
  * deps: body-parser@1.20.2
    - Fix strict json error message on Node.js 19+
    - deps: content-type@~1.0.5
    - deps: raw-body@2.5.2
  * deps: cookie@0.6.0
    - Add `partitioned` option

4.18.2 / 2022-10-08
===================

  * Fix regression routing a large stack in a single route
  * deps: body-parser@1.20.1
    - deps: qs@6.11.0
    - perf: remove unnecessary object clone
  * deps: qs@6.11.0

4.18.1 / 2022-04-29
===================

  * Fix hanging on large stack of sync routes

4.18.0 / 2022-04-25
===================

  * Add "root" option to `res.download`
  * Allow `options` without `filename` in `res.download`
  * Deprecate string and non-integer arguments to `res.status`
  * Fix behavior of `null`/`undefined` as `maxAge` in `res.cookie`
  * Fix handling very large stacks of sync middleware
  * Ignore `Object.prototype` values in settings through `app.set`/`app.get`
  * Invoke `default` with same arguments as types in `res.format`
  * Support proper 205 responses using `res.send`
  * Use `http-errors` for `res.format` error
  * deps: body-parser@1.20.0
    - Fix error message for json parse whitespace in `strict`
    - Fix internal error when inflated body exceeds limit
    - Prevent loss of async hooks context
    - Prevent hanging when request already read
    - deps: depd@2.0.0
    - deps: http-errors@2.0.0
    - deps: on-finished@2.4.1
    - deps: qs@6.10.3
    - deps: raw-body@2.5.1
  * deps: cookie@0.5.0
    - Add `priority` option
    - Fix `expires` option to reject invalid dates
  * deps: depd@2.0.0
    - Replace internal `eval` usage with `Function` constructor
    - Use instance methods on `process` to check for listeners
  * deps: finalhandler@1.2.0
    - Remove set content headers that break response
    - deps: on-finished@2.4.1
    - deps: statuses@2.0.1
  * deps: on-finished@2.4.1
    - Prevent loss of async hooks context
  * deps: qs@6.10.3
  * deps: send@0.18.0
    - Fix emitted 416 error missing headers property
    - Limit the headers removed for 304 response
    - deps: depd@2.0.0
    - deps: destroy@1.2.0
    - deps: http-errors@2.0.0
    - deps: on-finished@2.4.1
    - deps: statuses@2.0.1
  * deps: serve-static@1.15.0
    - deps: send@0.18.0
  * deps: statuses@2.0.1
    - Remove code 306
    - Rename `425 Unordered Collection` to standard `425 Too Early`

4.17.3 / 2022-02-16
===================

  * deps: accepts@~1.3.8
    - deps: mime-types@~2.1.34
    - deps: negotiator@0.6.3
  * deps: body-parser@1.19.2
    - deps: bytes@3.1.2
    - deps: qs@6.9.7
    - deps: raw-body@2.4.3
  * deps: cookie@0.4.2
  * deps: qs@6.9.7
    * Fix handling of `__proto__` keys
  * pref: remove unnecessary regexp for trust proxy

4.17.2 / 2021-12-16
===================

  * Fix handling of `undefined` in `res.jsonp`
  * Fix handling of `undefined` when `"json escape"` is enabled
  * Fix incorrect middleware execution with unanchored `RegExp`s
  * Fix `res.jsonp(obj, status)` deprecation message
  * Fix typo in `res.is` JSDoc
  * deps: body-parser@1.19.1
    - deps: bytes@3.1.1
    - deps: http-errors@1.8.1
    - deps: qs@6.9.6
    - deps: raw-body@2.4.2
    - deps: safe-buffer@5.2.1
    - deps: type-is@~1.6.18
  * deps: content-disposition@0.5.4
    - deps: safe-buffer@5.2.1
  * deps: cookie@0.4.1
    - Fix `maxAge` option to reject invalid values
  * deps: proxy-addr@~2.0.7
    - Use `req.socket` over deprecated `req.connection`
    - deps: forwarded@0.2.0
    - deps: ipaddr.js@1.9.1
  * deps: qs@6.9.6
  * deps: safe-buffer@5.2.1
  * deps: send@0.17.2
    - deps: http-errors@1.8.1
    - deps: ms@2.1.3
    - pref: ignore empty http tokens
  * deps: serve-static@1.14.2
    - deps: send@0.17.2
  * deps: setprototypeof@1.2.0

4.17.1 / 2019-05-25
===================

  * Revert "Improve error message for `null`/`undefined` to `res.status`"

4.17.0 / 2019-05-16
===================

  * Add `express.raw` to parse bodies into `Buffer`
  * Add `express.text` to parse bodies into string
  * Improve error message for non-strings to `res.sendFile`
  * Improve error message for `null`/`undefined` to `res.status`
  * Support multiple hosts in `X-Forwarded-Host`
  * deps: accepts@~1.3.7
  * deps: body-parser@1.19.0
    - Add encoding MIK
    - Add petabyte (`pb`) support
    - Fix parsing array brackets after index
    - deps: bytes@3.1.0
    - deps: http-errors@1.7.2
    - deps: iconv-lite@0.4.24
    - deps: qs@6.7.0
    - deps: raw-body@2.4.0
    - deps: type-is@~1.6.17
  * deps: content-disposition@0.5.3
  * deps: cookie@0.4.0
    - Add `SameSite=None` support
  * deps: finalhandler@~1.1.2
    - Set stricter `Content-Security-Policy` header
    - deps: parseurl@~1.3.3
    - deps: statuses@~1.5.0
  * deps: parseurl@~1.3.3
  * deps: proxy-addr@~2.0.5
    - deps: ipaddr.js@1.9.0
  * deps: qs@6.7.0
    - Fix parsing array brackets after index
  * deps: range-parser@~1.2.1
  * deps: send@0.17.1
    - Set stricter CSP header in redirect & error responses
    - deps: http-errors@~1.7.2
    - deps: mime@1.6.0
    - deps: ms@2.1.1
    - deps: range-parser@~1.2.1
    - deps: statuses@~1.5.0
    - perf: remove redundant `path.normalize` call
  * deps: serve-static@1.14.1
    - Set stricter CSP header in redirect response
    - deps: parseurl@~1.3.3
    - deps: send@0.17.1
  * deps: setprototypeof@1.1.1
  * deps: statuses@~1.5.0
    - Add `103 Early Hints`
  * deps: type-is@~1.6.18
    - deps: mime-types@~2.1.24
    - perf: prevent internal `throw` on invalid type

4.16.4 / 2018-10-10
===================

  * Fix issue where `"Request aborted"` may be logged in `res.sendfile`
  * Fix JSDoc for `Router` constructor
  * deps: body-parser@1.18.3
    - Fix deprecation warnings on Node.js 10+
    - Fix stack trace for strict json parse error
    - deps: depd@~1.1.2
    - deps: http-errors@~1.6.3
    - deps: iconv-lite@0.4.23
    - deps: qs@6.5.2
    - deps: raw-body@2.3.3
    - deps: type-is@~1.6.16
  * deps: proxy-addr@~2.0.4
    - deps: ipaddr.js@1.8.0
  * deps: qs@6.5.2
  * deps: safe-buffer@5.1.2

4.16.3 / 2018-03-12
===================

  * deps: accepts@~1.3.5
    - deps: mime-types@~2.1.18
  * deps: depd@~1.1.2
    - perf: remove argument reassignment
  * deps: encodeurl@~1.0.2
    - Fix encoding `%` as last character
  * deps: finalhandler@1.1.1
    - Fix 404 output for bad / missing pathnames
    - deps: encodeurl@~1.0.2
    - deps: statuses@~1.4.0
  * deps: proxy-addr@~2.0.3
    - deps: ipaddr.js@1.6.0
  * deps: send@0.16.2
    - Fix incorrect end tag in default error & redirects
    - deps: depd@~1.1.2
    - deps: encodeurl@~1.0.2
    - deps: statuses@~1.4.0
  * deps: serve-static@1.13.2
    - Fix incorrect end tag in redirects
    - deps: encodeurl@~1.0.2
    - deps: send@0.16.2
  * deps: statuses@~1.4.0
  * deps: type-is@~1.6.16
    - deps: mime-types@~2.1.18

4.16.2 / 2017-10-09
===================

  * Fix `TypeError` in `res.send` when given `Buffer` and `ETag` header set
  * perf: skip parsing of entire `X-Forwarded-Proto` header

4.16.1 / 2017-09-29
===================

  * deps: send@0.16.1
  * deps: serve-static@1.13.1
    - Fix regression when `root` is incorrectly set to a file
    - deps: send@0.16.1

4.16.0 / 2017-09-28
===================

  * Add `"json escape"` setting for `res.json` and `res.jsonp`
  * Add `express.json` and `express.urlencoded` to parse bodies
  * Add `options` argument to `res.download`
  * Improve error message when autoloading invalid view engine
  * Improve error messages when non-function provided as middleware
  * Skip `Buffer` encoding when not generating ETag for small response
  * Use `safe-buffer` for improved Buffer API
  * deps: accepts@~1.3.4
    - deps: mime-types@~2.1.16
  * deps: content-type@~1.0.4
    - perf: remove argument reassignment
    - perf: skip parameter parsing when no parameters
  * deps: etag@~1.8.1
    - perf: replace regular expression with substring
  * deps: finalhandler@1.1.0
    - Use `res.headersSent` when available
  * deps: parseurl@~1.3.2
    - perf: reduce overhead for full URLs
    - perf: unroll the "fast-path" `RegExp`
  * deps: proxy-addr@~2.0.2
    - Fix trimming leading / trailing OWS in `X-Forwarded-For`
    - deps: forwarded@~0.1.2
    - deps: ipaddr.js@1.5.2
    - perf: reduce overhead when no `X-Forwarded-For` header
  * deps: qs@6.5.1
    - Fix parsing & compacting very deep objects
  * deps: send@0.16.0
    - Add 70 new types for file extensions
    - Add `immutable` option
    - Fix missing `</html>` in default error & redirects
    - Set charset as "UTF-8" for .js and .json
    - Use instance methods on steam to check for listeners
    - deps: mime@1.4.1
    - perf: improve path validation speed
  * deps: serve-static@1.13.0
    - Add 70 new types for file extensions
    - Add `immutable` option
    - Set charset as "UTF-8" for .js and .json
    - deps: send@0.16.0
  * deps: setprototypeof@1.1.0
  * deps: utils-merge@1.0.1
  * deps: vary@~1.1.2
    - perf: improve header token parsing speed
  * perf: re-use options object when generating ETags
  * perf: remove dead `.charset` set in `res.jsonp`

4.15.5 / 2017-09-24
===================

  * deps: debug@2.6.9
  * deps: finalhandler@~1.0.6
    - deps: debug@2.6.9
    - deps: parseurl@~1.3.2
  * deps: fresh@0.5.2
    - Fix handling of modified headers with invalid dates
    - perf: improve ETag match loop
    - perf: improve `If-None-Match` token parsing
  * deps: send@0.15.6
    - Fix handling of modified headers with invalid dates
    - deps: debug@2.6.9
    - deps: etag@~1.8.1
    - deps: fresh@0.5.2
    - perf: improve `If-Match` token parsing
  * deps: serve-static@1.12.6
    - deps: parseurl@~1.3.2
    - deps: send@0.15.6
    - perf: improve slash collapsing

4.15.4 / 2017-08-06
===================

  * deps: debug@2.6.8
  * deps: depd@~1.1.1
    - Remove unnecessary `Buffer` loading
  * deps: finalhandler@~1.0.4
    - deps: debug@2.6.8
  * deps: proxy-addr@~1.1.5
    - Fix array argument being altered
    - deps: ipaddr.js@1.4.0
  * deps: qs@6.5.0
  * deps: send@0.15.4
    - deps: debug@2.6.8
    - deps: depd@~1.1.1
    - deps: http-errors@~1.6.2
  * deps: serve-static@1.12.4
    - deps: send@0.15.4

4.15.3 / 2017-05-16
===================

  * Fix error when `res.set` cannot add charset to `Content-Type`
  * deps: debug@2.6.7
    - Fix `DEBUG_MAX_ARRAY_LENGTH`
    - deps: ms@2.0.0
  * deps: finalhandler@~1.0.3
    - Fix missing `</html>` in HTML document
    - deps: debug@2.6.7
  * deps: proxy-addr@~1.1.4
    - deps: ipaddr.js@1.3.0
  * deps: send@0.15.3
    - deps: debug@2.6.7
    - deps: ms@2.0.0
  * deps: serve-static@1.12.3
    - deps: send@0.15.3
  * deps: type-is@~1.6.15
    - deps: mime-types@~2.1.15
  * deps: vary@~1.1.1
    - perf: hoist regular expression

4.15.2 / 2017-03-06
===================

  * deps: qs@6.4.0
    - Fix regression parsing keys starting with `[`

4.15.1 / 2017-03-05
===================

  * deps: send@0.15.1
    - Fix issue when `Date.parse` does not return `NaN` on invalid date
    - Fix strict violation in broken environments
  * deps: serve-static@1.12.1
    - Fix issue when `Date.parse` does not return `NaN` on invalid date
    - deps: send@0.15.1

4.15.0 / 2017-03-01
===================

  * Add debug message when loading view engine
  * Add `next("router")` to exit from router
  * Fix case where `router.use` skipped requests routes did not
  * Remove usage of `res._headers` private field
    - Improves compatibility with Node.js 8 nightly
  * Skip routing when `req.url` is not set
  * Use `%o` in path debug to tell types apart
  * Use `Object.create` to setup request & response prototypes
  * Use `setprototypeof` module to replace `__proto__` setting
  * Use `statuses` instead of `http` module for status messages
  * deps: debug@2.6.1
    - Allow colors in workers
    - Deprecated `DEBUG_FD` environment variable set to `3` or higher
    - Fix error when running under React Native
    - Use same color for same namespace
    - deps: ms@0.7.2
  * deps: etag@~1.8.0
    - Use SHA1 instead of MD5 for ETag hashing
    - Works with FIPS 140-2 OpenSSL configuration
  * deps: finalhandler@~1.0.0
    - Fix exception when `err` cannot be converted to a string
    - Fully URL-encode the pathname in the 404
    - Only include the pathname in the 404 message
    - Send complete HTML document
    - Set `Content-Security-Policy: default-src 'self'` header
    - deps: debug@2.6.1
  * deps: fresh@0.5.0
    - Fix false detection of `no-cache` request directive
    - Fix incorrect result when `If-None-Match` has both `*` and ETags
    - Fix weak `ETag` matching to match spec
    - perf: delay reading header values until needed
    - perf: enable strict mode
    - perf: hoist regular expressions
    - perf: remove duplicate conditional
    - perf: remove unnecessary boolean coercions
    - perf: skip checking modified time if ETag check failed
    - perf: skip parsing `If-None-Match` when no `ETag` header
    - perf: use `Date.parse` instead of `new Date`
  * deps: qs@6.3.1
    - Fix array parsing from skipping empty values
    - Fix compacting nested arrays
  * deps: send@0.15.0
    - Fix false detection of `no-cache` request directive
    - Fix incorrect result when `If-None-Match` has both `*` and ETags
    - Fix weak `ETag` matching to match spec
    - Remove usage of `res._headers` private field
    - Support `If-Match` and `If-Unmodified-Since` headers
    - Use `res.getHeaderNames()` when available
    - Use `res.headersSent` when available
    - deps: debug@2.6.1
    - deps: etag@~1.8.0
    - deps: fresh@0.5.0
    - deps: http-errors@~1.6.1
  * deps: serve-static@1.12.0
    - Fix false detection of `no-cache` request directive
    - Fix incorrect result when `If-None-Match` has both `*` and ETags
    - Fix weak `ETag` matching to match spec
    - Remove usage of `res._headers` private field
    - Send complete HTML document in redirect response
    - Set default CSP header in redirect response
    - Support `If-Match` and `If-Unmodified-Since` headers
    - Use `res.getHeaderNames()` when available
    - Use `res.headersSent` when available
    - deps: send@0.15.0
  * perf: add fast match path for `*` route
  * perf: improve `req.ips` performance

4.14.1 / 2017-01-28
===================

  * deps: content-disposition@0.5.2
  * deps: finalhandler@0.5.1
    - Fix exception when `err.headers` is not an object
    - deps: statuses@~1.3.1
    - perf: hoist regular expressions
    - perf: remove duplicate validation path
  * deps: proxy-addr@~1.1.3
    - deps: ipaddr.js@1.2.0
  * deps: send@0.14.2
    - deps: http-errors@~1.5.1
    - deps: ms@0.7.2
    - deps: statuses@~1.3.1
  * deps: serve-static@~1.11.2
    - deps: send@0.14.2
  * deps: type-is@~1.6.14
    - deps: mime-types@~2.1.13

4.14.0 / 2016-06-16
===================

  * Add `acceptRanges` option to `res.sendFile`/`res.sendfile`
  * Add `cacheControl` option to `res.sendFile`/`res.sendfile`
  * Add `options` argument to `req.range`
    - Includes the `combine` option
  * Encode URL in `res.location`/`res.redirect` if not already encoded
  * Fix some redirect handling in `res.sendFile`/`res.sendfile`
  * Fix Windows absolute path check using forward slashes
  * Improve error with invalid arguments to `req.get()`
  * Improve performance for `res.json`/`res.jsonp` in most cases
  * Improve `Range` header handling in `res.sendFile`/`res.sendfile`
  * deps: accepts@~1.3.3
    - Fix including type extensions in parameters in `Accept` parsing
    - Fix parsing `Accept` parameters with quoted equals
    - Fix parsing `Accept` parameters with quoted semicolons
    - Many performance improvements
    - deps: mime-types@~2.1.11
    - deps: negotiator@0.6.1
  * deps: content-type@~1.0.2
    - perf: enable strict mode
  * deps: cookie@0.3.1
    - Add `sameSite` option
    - Fix cookie `Max-Age` to never be a floating point number
    - Improve error message when `encode` is not a function
    - Improve error message when `expires` is not a `Date`
    - Throw better error for invalid argument to parse
    - Throw on invalid values provided to `serialize`
    - perf: enable strict mode
    - perf: hoist regular expression
    - perf: use for loop in parse
    - perf: use string concatenation for serialization
  * deps: finalhandler@0.5.0
    - Change invalid or non-numeric status code to 500
    - Overwrite status message to match set status code
    - Prefer `err.statusCode` if `err.status` is invalid
    - Set response headers from `err.headers` object
    - Use `statuses` instead of `http` module for status messages
  * deps: proxy-addr@~1.1.2
    - Fix accepting various invalid netmasks
    - Fix IPv6-mapped IPv4 validation edge cases
    - IPv4 netmasks must be contiguous
    - IPv6 addresses cannot be used as a netmask
    - deps: ipaddr.js@1.1.1
  * deps: qs@6.2.0
    - Add `decoder` option in `parse` function
  * deps: range-parser@~1.2.0
    - Add `combine` option to combine overlapping ranges
    - Fix incorrectly returning -1 when there is at least one valid range
    - perf: remove internal function
  * deps: send@0.14.1
    - Add `acceptRanges` option
    - Add `cacheControl` option
    - Attempt to combine multiple ranges into single range
    - Correctly inherit from `Stream` class
    - Fix `Content-Range` header in 416 responses when using `start`/`end` options
    - Fix `Content-Range` header missing from default 416 responses
    - Fix redirect error when `path` contains raw non-URL characters
    - Fix redirect when `path` starts with multiple forward slashes
    - Ignore non-byte `Range` headers
    - deps: http-errors@~1.5.0
    - deps: range-parser@~1.2.0
    - deps: statuses@~1.3.0
    - perf: remove argument reassignment
  * deps: serve-static@~1.11.1
    - Add `acceptRanges` option
    - Add `cacheControl` option
    - Attempt to combine multiple ranges into single range
    - Fix redirect error when `req.url` contains raw non-URL characters
    - Ignore non-byte `Range` headers
    - Use status code 301 for redirects
    - deps: send@0.14.1
  * deps: type-is@~1.6.13
    - Fix type error when given invalid type to match against
    - deps: mime-types@~2.1.11
  * deps: vary@~1.1.0
    - Only accept valid field names in the `field` argument
  * perf: use strict equality when possible

4.13.4 / 2016-01-21
===================

  * deps: content-disposition@0.5.1
    - perf: enable strict mode
  * deps: cookie@0.1.5
    - Throw on invalid values provided to `serialize`
  * deps: depd@~1.1.0
    - Support web browser loading
    - perf: enable strict mode
  * deps: escape-html@~1.0.3
    - perf: enable strict mode
    - perf: optimize string replacement
    - perf: use faster string coercion
  * deps: finalhandler@0.4.1
    - deps: escape-html@~1.0.3
  * deps: merge-descriptors@1.0.1
    - perf: enable strict mode
  * deps: methods@~1.1.2
    - perf: enable strict mode
  * deps: parseurl@~1.3.1
    - perf: enable strict mode
  * deps: proxy-addr@~1.0.10
    - deps: ipaddr.js@1.0.5
    - perf: enable strict mode
  * deps: range-parser@~1.0.3
    - perf: enable strict mode
  * deps: send@0.13.1
    - deps: depd@~1.1.0
    - deps: destroy@~1.0.4
    - deps: escape-html@~1.0.3
    - deps: range-parser@~1.0.3
  * deps: serve-static@~1.10.2
    - deps: escape-html@~1.0.3
    - deps: parseurl@~1.3.0
    - deps: send@0.13.1

4.13.3 / 2015-08-02
===================

  * Fix infinite loop condition using `mergeParams: true`
  * Fix inner numeric indices incorrectly altering parent `req.params`

4.13.2 / 2015-07-31
===================

  * deps: accepts@~1.2.12
    - deps: mime-types@~2.1.4
  * deps: array-flatten@1.1.1
    - perf: enable strict mode
  * deps: path-to-regexp@0.1.7
    - Fix regression with escaped round brackets and matching groups
  * deps: type-is@~1.6.6
    - deps: mime-types@~2.1.4

4.13.1 / 2015-07-05
===================

  * deps: accepts@~1.2.10
    - deps: mime-types@~2.1.2
  * deps: qs@4.0.0
    - Fix dropping parameters like `hasOwnProperty`
    - Fix various parsing edge cases
  * deps: type-is@~1.6.4
    - deps: mime-types@~2.1.2
    - perf: enable strict mode
    - perf: remove argument reassignment

4.13.0 / 2015-06-20
===================

  * Add settings to debug output
  * Fix `res.format` error when only `default` provided
  * Fix issue where `next('route')` in `app.param` would incorrectly skip values
  * Fix hiding platform issues with `decodeURIComponent`
    - Only `URIError`s are a 400
  * Fix using `*` before params in routes
  * Fix using capture groups before params in routes
  * Simplify `res.cookie` to call `res.append`
  * Use `array-flatten` module for flattening arrays
  * deps: accepts@~1.2.9
    - deps: mime-types@~2.1.1
    - perf: avoid argument reassignment & argument slice
    - perf: avoid negotiator recursive construction
    - perf: enable strict mode
    - perf: remove unnecessary bitwise operator
  * deps: cookie@0.1.3
    - perf: deduce the scope of try-catch deopt
    - perf: remove argument reassignments
  * deps: escape-html@1.0.2
  * deps: etag@~1.7.0
    - Always include entity length in ETags for hash length extensions
    - Generate non-Stats ETags using MD5 only (no longer CRC32)
    - Improve stat performance by removing hashing
    - Improve support for JXcore
    - Remove base64 padding in ETags to shorten
    - Support "fake" stats objects in environments without fs
    - Use MD5 instead of MD4 in weak ETags over 1KB
  * deps: finalhandler@0.4.0
    - Fix a false-positive when unpiping in Node.js 0.8
    - Support `statusCode` property on `Error` objects
    - Use `unpipe` module for unpiping requests
    - deps: escape-html@1.0.2
    - deps: on-finished@~2.3.0
    - perf: enable strict mode
    - perf: remove argument reassignment
  * deps: fresh@0.3.0
    - Add weak `ETag` matching support
  * deps: on-finished@~2.3.0
    - Add defined behavior for HTTP `CONNECT` requests
    - Add defined behavior for HTTP `Upgrade` requests
    - deps: ee-first@1.1.1
  * deps: path-to-regexp@0.1.6
  * deps: send@0.13.0
    - Allow Node.js HTTP server to set `Date` response header
    - Fix incorrectly removing `Content-Location` on 304 response
    - Improve the default redirect response headers
    - Send appropriate headers on default error response
    - Use `http-errors` for standard emitted errors
    - Use `statuses` instead of `http` module for status messages
    - deps: escape-html@1.0.2
    - deps: etag@~1.7.0
    - deps: fresh@0.3.0
    - deps: on-finished@~2.3.0
    - perf: enable strict mode
    - perf: remove unnecessary array allocations
  * deps: serve-static@~1.10.0
    - Add `fallthrough` option
    - Fix reading options from options prototype
    - Improve the default redirect response headers
    - Malformed URLs now `next()` instead of 400
    - deps: escape-html@1.0.2
    - deps: send@0.13.0
    - perf: enable strict mode
    - perf: remove argument reassignment
  * deps: type-is@~1.6.3
    - deps: mime-types@~2.1.1
    - perf: reduce try block size
    - perf: remove bitwise operations
  * perf: enable strict mode
  * perf: isolate `app.render` try block
  * perf: remove argument reassignments in application
  * perf: remove argument reassignments in request prototype
  * perf: remove argument reassignments in response prototype
  * perf: remove argument reassignments in routing
  * perf: remove argument reassignments in `View`
  * perf: skip attempting to decode zero length string
  * perf: use saved reference to `http.STATUS_CODES`

4.12.4 / 2015-05-17
===================

  * deps: accepts@~1.2.7
    - deps: mime-types@~2.0.11
    - deps: negotiator@0.5.3
  * deps: debug@~2.2.0
    - deps: ms@0.7.1
  * deps: depd@~1.0.1
  * deps: etag@~1.6.0
    - Improve support for JXcore
    - Support "fake" stats objects in environments without `fs`
  * deps: finalhandler@0.3.6
    - deps: debug@~2.2.0
    - deps: on-finished@~2.2.1
  * deps: on-finished@~2.2.1
    - Fix `isFinished(req)` when data buffered
  * deps: proxy-addr@~1.0.8
    - deps: ipaddr.js@1.0.1
  * deps: qs@2.4.2
   - Fix allowing parameters like `constructor`
  * deps: send@0.12.3
    - deps: debug@~2.2.0
    - deps: depd@~1.0.1
    - deps: etag@~1.6.0
    - deps: ms@0.7.1
    - deps: on-finished@~2.2.1
  * deps: serve-static@~1.9.3
    - deps: send@0.12.3
  * deps: type-is@~1.6.2
    - deps: mime-types@~2.0.11

4.12.3 / 2015-03-17
===================

  * deps: accepts@~1.2.5
    - deps: mime-types@~2.0.10
  * deps: debug@~2.1.3
    - Fix high intensity foreground color for bold
    - deps: ms@0.7.0
  * deps: finalhandler@0.3.4
    - deps: debug@~2.1.3
  * deps: proxy-addr@~1.0.7
    - deps: ipaddr.js@0.1.9
  * deps: qs@2.4.1
    - Fix error when parameter `hasOwnProperty` is present
  * deps: send@0.12.2
    - Throw errors early for invalid `extensions` or `index` options
    - deps: debug@~2.1.3
  * deps: serve-static@~1.9.2
    - deps: send@0.12.2
  * deps: type-is@~1.6.1
    - deps: mime-types@~2.0.10

4.12.2 / 2015-03-02
===================

  * Fix regression where `"Request aborted"` is logged using `res.sendFile`

4.12.1 / 2015-03-01
===================

  * Fix constructing application with non-configurable prototype properties
  * Fix `ECONNRESET` errors from `res.sendFile` usage
  * Fix `req.host` when using "trust proxy" hops count
  * Fix `req.protocol`/`req.secure` when using "trust proxy" hops count
  * Fix wrong `code` on aborted connections from `res.sendFile`
  * deps: merge-descriptors@1.0.0

4.12.0 / 2015-02-23
===================

  * Fix `"trust proxy"` setting to inherit when app is mounted
  * Generate `ETag`s for all request responses
    - No longer restricted to only responses for `GET` and `HEAD` requests
  * Use `content-type` to parse `Content-Type` headers
  * deps: accepts@~1.2.4
    - Fix preference sorting to be stable for long acceptable lists
    - deps: mime-types@~2.0.9
    - deps: negotiator@0.5.1
  * deps: cookie-signature@1.0.6
  * deps: send@0.12.1
    - Always read the stat size from the file
    - Fix mutating passed-in `options`
    - deps: mime@1.3.4
  * deps: serve-static@~1.9.1
    - deps: send@0.12.1
  * deps: type-is@~1.6.0
    - fix argument reassignment
    - fix false-positives in `hasBody` `Transfer-Encoding` check
    - support wildcard for both type and subtype (`*/*`)
    - deps: mime-types@~2.0.9

4.11.2 / 2015-02-01
===================

  * Fix `res.redirect` double-calling `res.end` for `HEAD` requests
  * deps: accepts@~1.2.3
    - deps: mime-types@~2.0.8
  * deps: proxy-addr@~1.0.6
    - deps: ipaddr.js@0.1.8
  * deps: type-is@~1.5.6
    - deps: mime-types@~2.0.8

4.11.1 / 2015-01-20
===================

  * deps: send@0.11.1
    - Fix root path disclosure
  * deps: serve-static@~1.8.1
    - Fix redirect loop in Node.js 0.11.14
    - Fix root path disclosure
    - deps: send@0.11.1

4.11.0 / 2015-01-13
===================

  * Add `res.append(field, val)` to append headers
  * Deprecate leading `:` in `name` for `app.param(name, fn)`
  * Deprecate `req.param()` -- use `req.params`, `req.body`, or `req.query` instead
  * Deprecate `app.param(fn)`
  * Fix `OPTIONS` responses to include the `HEAD` method properly
  * Fix `res.sendFile` not always detecting aborted connection
  * Match routes iteratively to prevent stack overflows
  * deps: accepts@~1.2.2
    - deps: mime-types@~2.0.7
    - deps: negotiator@0.5.0
  * deps: send@0.11.0
    - deps: debug@~2.1.1
    - deps: etag@~1.5.1
    - deps: ms@0.7.0
    - deps: on-finished@~2.2.0
  * deps: serve-static@~1.8.0
    - deps: send@0.11.0

4.10.8 / 2015-01-13
===================

  * Fix crash from error within `OPTIONS` response handler
  * deps: proxy-addr@~1.0.5
    - deps: ipaddr.js@0.1.6

4.10.7 / 2015-01-04
===================

  * Fix `Allow` header for `OPTIONS` to not contain duplicate methods
  * Fix incorrect "Request aborted" for `res.sendFile` when `HEAD` or 304
  * deps: debug@~2.1.1
  * deps: finalhandler@0.3.3
    - deps: debug@~2.1.1
    - deps: on-finished@~2.2.0
  * deps: methods@~1.1.1
  * deps: on-finished@~2.2.0
  * deps: serve-static@~1.7.2
    - Fix potential open redirect when mounted at root
  * deps: type-is@~1.5.5
    - deps: mime-types@~2.0.7

4.10.6 / 2014-12-12
===================

  * Fix exception in `req.fresh`/`req.stale` without response headers

4.10.5 / 2014-12-10
===================

  * Fix `res.send` double-calling `res.end` for `HEAD` requests
  * deps: accepts@~1.1.4
    - deps: mime-types@~2.0.4
  * deps: type-is@~1.5.4
    - deps: mime-types@~2.0.4

4.10.4 / 2014-11-24
===================

  * Fix `res.sendfile` logging standard write errors

4.10.3 / 2014-11-23
===================

  * Fix `res.sendFile` logging standard write errors
  * deps: etag@~1.5.1
  * deps: proxy-addr@~1.0.4
    - deps: ipaddr.js@0.1.5
  * deps: qs@2.3.3
    - Fix `arrayLimit` behavior

4.10.2 / 2014-11-09
===================

  * Correctly invoke async router callback asynchronously
  * deps: accepts@~1.1.3
    - deps: mime-types@~2.0.3
  * deps: type-is@~1.5.3
    - deps: mime-types@~2.0.3

4.10.1 / 2014-10-28
===================

  * Fix handling of URLs containing `://` in the path
  * deps: qs@2.3.2
    - Fix parsing of mixed objects and values

4.10.0 / 2014-10-23
===================

  * Add support for `app.set('views', array)`
    - Views are looked up in sequence in array of directories
  * Fix `res.send(status)` to mention `res.sendStatus(status)`
  * Fix handling of invalid empty URLs
  * Use `content-disposition` module for `res.attachment`/`res.download`
    - Sends standards-compliant `Content-Disposition` header
    - Full Unicode support
  * Use `path.resolve` in view lookup
  * deps: debug@~2.1.0
    - Implement `DEBUG_FD` env variable support
  * deps: depd@~1.0.0
  * deps: etag@~1.5.0
    - Improve string performance
    - Slightly improve speed for weak ETags over 1KB
  * deps: finalhandler@0.3.2
    - Terminate in progress response only on error
    - Use `on-finished` to determine request status
    - deps: debug@~2.1.0
    - deps: on-finished@~2.1.1
  * deps: on-finished@~2.1.1
    - Fix handling of pipelined requests
  * deps: qs@2.3.0
    - Fix parsing of mixed implicit and explicit arrays
  * deps: send@0.10.1
    - deps: debug@~2.1.0
    - deps: depd@~1.0.0
    - deps: etag@~1.5.0
    - deps: on-finished@~2.1.1
  * deps: serve-static@~1.7.1
    - deps: send@0.10.1

4.9.8 / 2014-10-17
==================

  * Fix `res.redirect` body when redirect status specified
  * deps: accepts@~1.1.2
    - Fix error when media type has invalid parameter
    - deps: negotiator@0.4.9

4.9.7 / 2014-10-10
==================

  * Fix using same param name in array of paths

4.9.6 / 2014-10-08
==================

  * deps: accepts@~1.1.1
    - deps: mime-types@~2.0.2
    - deps: negotiator@0.4.8
  * deps: serve-static@~1.6.4
    - Fix redirect loop when index file serving disabled
  * deps: type-is@~1.5.2
    - deps: mime-types@~2.0.2

4.9.5 / 2014-09-24
==================

  * deps: etag@~1.4.0
  * deps: proxy-addr@~1.0.3
    - Use `forwarded` npm module
  * deps: send@0.9.3
    - deps: etag@~1.4.0
  * deps: serve-static@~1.6.3
    - deps: send@0.9.3

4.9.4 / 2014-09-19
==================

  * deps: qs@2.2.4
    - Fix issue with object keys starting with numbers truncated

4.9.3 / 2014-09-18
==================

  * deps: proxy-addr@~1.0.2
    - Fix a global leak when multiple subnets are trusted
    - deps: ipaddr.js@0.1.3

4.9.2 / 2014-09-17
==================

  * Fix regression for empty string `path` in `app.use`
  * Fix `router.use` to accept array of middleware without path
  * Improve error message for bad `app.use` arguments

4.9.1 / 2014-09-16
==================

  * Fix `app.use` to accept array of middleware without path
  * deps: depd@0.4.5
  * deps: etag@~1.3.1
  * deps: send@0.9.2
    - deps: depd@0.4.5
    - deps: etag@~1.3.1
    - deps: range-parser@~1.0.2
  * deps: serve-static@~1.6.2
    - deps: send@0.9.2

4.9.0 / 2014-09-08
==================

  * Add `res.sendStatus`
  * Invoke callback for sendfile when client aborts
    - Applies to `res.sendFile`, `res.sendfile`, and `res.download`
    - `err` will be populated with request aborted error
  * Support IP address host in `req.subdomains`
  * Use `etag` to generate `ETag` headers
  * deps: accepts@~1.1.0
    - update `mime-types`
  * deps: cookie-signature@1.0.5
  * deps: debug@~2.0.0
  * deps: finalhandler@0.2.0
    - Set `X-Content-Type-Options: nosniff` header
    - deps: debug@~2.0.0
  * deps: fresh@0.2.4
  * deps: media-typer@0.3.0
    - Throw error when parameter format invalid on parse
  * deps: qs@2.2.3
    - Fix issue where first empty value in array is discarded
  * deps: range-parser@~1.0.2
  * deps: send@0.9.1
    - Add `lastModified` option
    - Use `etag` to generate `ETag` header
    - deps: debug@~2.0.0
    - deps: fresh@0.2.4
  * deps: serve-static@~1.6.1
    - Add `lastModified` option
    - deps: send@0.9.1
  * deps: type-is@~1.5.1
    - fix `hasbody` to be true for `content-length: 0`
    - deps: media-typer@0.3.0
    - deps: mime-types@~2.0.1
  * deps: vary@~1.0.0
    - Accept valid `Vary` header string as `field`

4.8.8 / 2014-09-04
==================

  * deps: send@0.8.5
    - Fix a path traversal issue when using `root`
    - Fix malicious path detection for empty string path
  * deps: serve-static@~1.5.4
    - deps: send@0.8.5

4.8.7 / 2014-08-29
==================

  * deps: qs@2.2.2
    - Remove unnecessary cloning

4.8.6 / 2014-08-27
==================

  * deps: qs@2.2.0
    - Array parsing fix
    - Performance improvements

4.8.5 / 2014-08-18
==================

  * deps: send@0.8.3
    - deps: destroy@1.0.3
    - deps: on-finished@2.1.0
  * deps: serve-static@~1.5.3
    - deps: send@0.8.3

4.8.4 / 2014-08-14
==================

  * deps: qs@1.2.2
  * deps: send@0.8.2
    - Work around `fd` leak in Node.js 0.10 for `fs.ReadStream`
  * deps: serve-static@~1.5.2
    - deps: send@0.8.2

4.8.3 / 2014-08-10
==================

  * deps: parseurl@~1.3.0
  * deps: qs@1.2.1
  * deps: serve-static@~1.5.1
    - Fix parsing of weird `req.originalUrl` values
    - deps: parseurl@~1.3.0
    - deps: utils-merge@1.0.0

4.8.2 / 2014-08-07
==================

  * deps: qs@1.2.0
    - Fix parsing array of objects

4.8.1 / 2014-08-06
==================

  * fix incorrect deprecation warnings on `res.download`
  * deps: qs@1.1.0
    - Accept urlencoded square brackets
    - Accept empty values in implicit array notation

4.8.0 / 2014-08-05
==================

  * add `res.sendFile`
    - accepts a file system path instead of a URL
    - requires an absolute path or `root` option specified
  * deprecate `res.sendfile` -- use `res.sendFile` instead
  * support mounted app as any argument to `app.use()`
  * deps: qs@1.0.2
    - Complete rewrite
    - Limits array length to 20
    - Limits object depth to 5
    - Limits parameters to 1,000
  * deps: send@0.8.1
    - Add `extensions` option
  * deps: serve-static@~1.5.0
    - Add `extensions` option
    - deps: send@0.8.1

4.7.4 / 2014-08-04
==================

  * fix `res.sendfile` regression for serving directory index files
  * deps: send@0.7.4
    - Fix incorrect 403 on Windows and Node.js 0.11
    - Fix serving index files without root dir
  * deps: serve-static@~1.4.4
    - deps: send@0.7.4

4.7.3 / 2014-08-04
==================

  * deps: send@0.7.3
    - Fix incorrect 403 on Windows and Node.js 0.11
  * deps: serve-static@~1.4.3
    - Fix incorrect 403 on Windows and Node.js 0.11
    - deps: send@0.7.3

4.7.2 / 2014-07-27
==================

  * deps: depd@0.4.4
    - Work-around v8 generating empty stack traces
  * deps: send@0.7.2
    - deps: depd@0.4.4
  * deps: serve-static@~1.4.2

4.7.1 / 2014-07-26
==================

  * deps: depd@0.4.3
    - Fix exception when global `Error.stackTraceLimit` is too low
  * deps: send@0.7.1
    - deps: depd@0.4.3
  * deps: serve-static@~1.4.1

4.7.0 / 2014-07-25
==================

  * fix `req.protocol` for proxy-direct connections
  * configurable query parser with `app.set('query parser', parser)`
    - `app.set('query parser', 'extended')` parse with "qs" module
    - `app.set('query parser', 'simple')` parse with "querystring" core module
    - `app.set('query parser', false)` disable query string parsing
    - `app.set('query parser', true)` enable simple parsing
  * deprecate `res.json(status, obj)` -- use `res.status(status).json(obj)` instead
  * deprecate `res.jsonp(status, obj)` -- use `res.status(status).jsonp(obj)` instead
  * deprecate `res.send(status, body)` -- use `res.status(status).send(body)` instead
  * deps: debug@1.0.4
  * deps: depd@0.4.2
    - Add `TRACE_DEPRECATION` environment variable
    - Remove non-standard grey color from color output
    - Support `--no-deprecation` argument
    - Support `--trace-deprecation` argument
  * deps: finalhandler@0.1.0
    - Respond after request fully read
    - deps: debug@1.0.4
  * deps: parseurl@~1.2.0
    - Cache URLs based on original value
    - Remove no-longer-needed URL mis-parse work-around
    - Simplify the "fast-path" `RegExp`
  * deps: send@0.7.0
    - Add `dotfiles` option
    - Cap `maxAge` value to 1 year
    - deps: debug@1.0.4
    - deps: depd@0.4.2
  * deps: serve-static@~1.4.0
    - deps: parseurl@~1.2.0
    - deps: send@0.7.0
  * perf: prevent multiple `Buffer` creation in `res.send`

4.6.1 / 2014-07-12
==================

  * fix `subapp.mountpath` regression for `app.use(subapp)`

4.6.0 / 2014-07-11
==================

  * accept multiple callbacks to `app.use()`
  * add explicit "Rosetta Flash JSONP abuse" protection
    - previous versions are not vulnerable; this is just explicit protection
  * catch errors in multiple `req.param(name, fn)` handlers
  * deprecate `res.redirect(url, status)` -- use `res.redirect(status, url)` instead
  * fix `res.send(status, num)` to send `num` as json (not error)
  * remove unnecessary escaping when `res.jsonp` returns JSON response
  * support non-string `path` in `app.use(path, fn)`
    - supports array of paths
    - supports `RegExp`
  * router: fix optimization on router exit
  * router: refactor location of `try` blocks
  * router: speed up standard `app.use(fn)`
  * deps: debug@1.0.3
    - Add support for multiple wildcards in namespaces
  * deps: finalhandler@0.0.3
    - deps: debug@1.0.3
  * deps: methods@1.1.0
    - add `CONNECT`
  * deps: parseurl@~1.1.3
    - faster parsing of href-only URLs
  * deps: path-to-regexp@0.1.3
  * deps: send@0.6.0
    - deps: debug@1.0.3
  * deps: serve-static@~1.3.2
    - deps: parseurl@~1.1.3
    - deps: send@0.6.0
  * perf: fix arguments reassign deopt in some `res` methods

4.5.1 / 2014-07-06
==================

 * fix routing regression when altering `req.method`

4.5.0 / 2014-07-04
==================

 * add deprecation message to non-plural `req.accepts*`
 * add deprecation message to `res.send(body, status)`
 * add deprecation message to `res.vary()`
 * add `headers` option to `res.sendfile`
   - use to set headers on successful file transfer
 * add `mergeParams` option to `Router`
   - merges `req.params` from parent routes
 * add `req.hostname` -- correct name for what `req.host` returns
 * deprecate things with `depd` module
 * deprecate `req.host` -- use `req.hostname` instead
 * fix behavior when handling request without routes
 * fix handling when `route.all` is only route
 * invoke `router.param()` only when route matches
 * restore `req.params` after invoking router
 * use `finalhandler` for final response handling
 * use `media-typer` to alter content-type charset
 * deps: accepts@~1.0.7
 * deps: send@0.5.0
   - Accept string for `maxage` (converted by `ms`)
   - Include link in default redirect response
 * deps: serve-static@~1.3.0
   - Accept string for `maxAge` (converted by `ms`)
   - Add `setHeaders` option
   - Include HTML link in redirect response
   - deps: send@0.5.0
 * deps: type-is@~1.3.2

4.4.5 / 2014-06-26
==================

 * deps: cookie-signature@1.0.4
   - fix for timing attacks

4.4.4 / 2014-06-20
==================

 * fix `res.attachment` Unicode filenames in Safari
 * fix "trim prefix" debug message in `express:router`
 * deps: accepts@~1.0.5
 * deps: buffer-crc32@0.2.3

4.4.3 / 2014-06-11
==================

 * fix persistence of modified `req.params[name]` from `app.param()`
 * deps: accepts@1.0.3
   - deps: negotiator@0.4.6
 * deps: debug@1.0.2
 * deps: send@0.4.3
   - Do not throw uncatchable error on file open race condition
   - Use `escape-html` for HTML escaping
   - deps: debug@1.0.2
   - deps: finished@1.2.2
   - deps: fresh@0.2.2
 * deps: serve-static@1.2.3
   - Do not throw uncatchable error on file open race condition
   - deps: send@0.4.3

4.4.2 / 2014-06-09
==================

 * fix catching errors from top-level handlers
 * use `vary` module for `res.vary`
 * deps: debug@1.0.1
 * deps: proxy-addr@1.0.1
 * deps: send@0.4.2
   - fix "event emitter leak" warnings
   - deps: debug@1.0.1
   - deps: finished@1.2.1
 * deps: serve-static@1.2.2
   - fix "event emitter leak" warnings
   - deps: send@0.4.2
 * deps: type-is@1.2.1

4.4.1 / 2014-06-02
==================

 * deps: methods@1.0.1
 * deps: send@0.4.1
   - Send `max-age` in `Cache-Control` in correct format
 * deps: serve-static@1.2.1
   - use `escape-html` for escaping
   - deps: send@0.4.1

4.4.0 / 2014-05-30
==================

 * custom etag control with `app.set('etag', val)`
   - `app.set('etag', function(body, encoding){ return '"etag"' })` custom etag generation
   - `app.set('etag', 'weak')` weak tag
   - `app.set('etag', 'strong')` strong etag
   - `app.set('etag', false)` turn off
   - `app.set('etag', true)` standard etag
 * mark `res.send` ETag as weak and reduce collisions
 * update accepts to 1.0.2
   - Fix interpretation when header not in request
 * update send to 0.4.0
   - Calculate ETag with md5 for reduced collisions
   - Ignore stream errors after request ends
   - deps: debug@0.8.1
 * update serve-static to 1.2.0
   - Calculate ETag with md5 for reduced collisions
   - Ignore stream errors after request ends
   - deps: send@0.4.0

4.3.2 / 2014-05-28
==================

 * fix handling of errors from `router.param()` callbacks

4.3.1 / 2014-05-23
==================

 * revert "fix behavior of multiple `app.VERB` for the same path"
   - this caused a regression in the order of route execution

4.3.0 / 2014-05-21
==================

 * add `req.baseUrl` to access the path stripped from `req.url` in routes
 * fix behavior of multiple `app.VERB` for the same path
 * fix issue routing requests among sub routers
 * invoke `router.param()` only when necessary instead of every match
 * proper proxy trust with `app.set('trust proxy', trust)`
   - `app.set('trust proxy', 1)` trust first hop
   - `app.set('trust proxy', 'loopback')` trust loopback addresses
   - `app.set('trust proxy', '10.0.0.1')` trust single IP
   - `app.set('trust proxy', '10.0.0.1/16')` trust subnet
   - `app.set('trust proxy', '10.0.0.1, 10.0.0.2')` trust list
   - `app.set('trust proxy', false)` turn off
   - `app.set('trust proxy', true)` trust everything
 * set proper `charset` in `Content-Type` for `res.send`
 * update type-is to 1.2.0
   - support suffix matching

4.2.0 / 2014-05-11
==================

 * deprecate `app.del()` -- use `app.delete()` instead
 * deprecate `res.json(obj, status)` -- use `res.json(status, obj)` instead
   - the edge-case `res.json(status, num)` requires `res.status(status).json(num)`
 * deprecate `res.jsonp(obj, status)` -- use `res.jsonp(status, obj)` instead
   - the edge-case `res.jsonp(status, num)` requires `res.status(status).jsonp(num)`
 * fix `req.next` when inside router instance
 * include `ETag` header in `HEAD` requests
 * keep previous `Content-Type` for `res.jsonp`
 * support PURGE method
   - add `app.purge`
   - add `router.purge`
   - include PURGE in `app.all`
 * update debug to 0.8.0
   - add `enable()` method
   - change from stderr to stdout
 * update methods to 1.0.0
   - add PURGE

4.1.2 / 2014-05-08
==================

 * fix `req.host` for IPv6 literals
 * fix `res.jsonp` error if callback param is object

4.1.1 / 2014-04-27
==================

 * fix package.json to reflect supported node version

4.1.0 / 2014-04-24
==================

 * pass options from `res.sendfile` to `send`
 * preserve casing of headers in `res.header` and `res.set`
 * support unicode file names in `res.attachment` and `res.download`
 * update accepts to 1.0.1
   - deps: negotiator@0.4.0
 * update cookie to 0.1.2
   - Fix for maxAge == 0
   - made compat with expires field
 * update send to 0.3.0
   - Accept API options in options object
   - Coerce option types
   - Control whether to generate etags
   - Default directory access to 403 when index disabled
   - Fix sending files with dots without root set
   - Include file path in etag
   - Make "Can't set headers after they are sent." catchable
   - Send full entity-body for multi range requests
   - Set etags to "weak"
   - Support "If-Range" header
   - Support multiple index paths
   - deps: mime@1.2.11
 * update serve-static to 1.1.0
   - Accept options directly to `send` module
   - Resolve relative paths at middleware setup
   - Use parseurl to parse the URL from request
   - deps: send@0.3.0
 * update type-is to 1.1.0
   - add non-array values support
   - add `multipart` as a shorthand

4.0.0 / 2014-04-09
==================

 * remove:
   - node 0.8 support
   - connect and connect's patches except for charset handling
   - express(1) - moved to [express-generator](https://github.com/expressjs/generator)
   - `express.createServer()` - it has been deprecated for a long time. Use `express()`
   - `app.configure` - use logic in your own app code
   - `app.router` - is removed
   - `req.auth` - use `basic-auth` instead
   - `req.accepted*` - use `req.accepts*()` instead
   - `res.location` - relative URL resolution is removed
   - `res.charset` - include the charset in the content type when using `res.set()`
   - all bundled middleware except `static`
 * change:
   - `app.route` -> `app.mountpath` when mounting an express app in another express app
   - `json spaces` no longer enabled by default in development
   - `req.accepts*` -> `req.accepts*s` - i.e. `req.acceptsEncoding` -> `req.acceptsEncodings`
   - `req.params` is now an object instead of an array
   - `res.locals` is no longer a function. It is a plain js object. Treat it as such.
   - `res.headerSent` -> `res.headersSent` to match node.js ServerResponse object
 * refactor:
   - `req.accepts*` with [accepts](https://github.com/expressjs/accepts)
   - `req.is` with [type-is](https://github.com/expressjs/type-is)
   - [path-to-regexp](https://github.com/component/path-to-regexp)
 * add:
   - `app.router()` - returns the app Router instance
   - `app.route()` - Proxy to the app's `Router#route()` method to create a new route
   - Router & Route - public API

3.21.2 / 2015-07-31
===================

  * deps: connect@2.30.2
    - deps: body-parser@~1.13.3
    - deps: compression@~1.5.2
    - deps: errorhandler@~1.4.2
    - deps: method-override@~2.3.5
    - deps: serve-index@~1.7.2
    - deps: type-is@~1.6.6
    - deps: vhost@~3.0.1
  * deps: vary@~1.0.1
    - Fix setting empty header from empty `field`
    - perf: enable strict mode
    - perf: remove argument reassignments

3.21.1 / 2015-07-05
===================

  * deps: basic-auth@~1.0.3
  * deps: connect@2.30.1
    - deps: body-parser@~1.13.2
    - deps: compression@~1.5.1
    - deps: errorhandler@~1.4.1
    - deps: morgan@~1.6.1
    - deps: pause@0.1.0
    - deps: qs@4.0.0
    - deps: serve-index@~1.7.1
    - deps: type-is@~1.6.4

3.21.0 / 2015-06-18
===================

  * deps: basic-auth@1.0.2
    - perf: enable strict mode
    - perf: hoist regular expression
    - perf: parse with regular expressions
    - perf: remove argument reassignment
  * deps: connect@2.30.0
    - deps: body-parser@~1.13.1
    - deps: bytes@2.1.0
    - deps: compression@~1.5.0
    - deps: cookie@0.1.3
    - deps: cookie-parser@~1.3.5
    - deps: csurf@~1.8.3
    - deps: errorhandler@~1.4.0
    - deps: express-session@~1.11.3
    - deps: finalhandler@0.4.0
    - deps: fresh@0.3.0
    - deps: morgan@~1.6.0
    - deps: serve-favicon@~2.3.0
    - deps: serve-index@~1.7.0
    - deps: serve-static@~1.10.0
    - deps: type-is@~1.6.3
  * deps: cookie@0.1.3
    - perf: deduce the scope of try-catch deopt
    - perf: remove argument reassignments
  * deps: escape-html@1.0.2
  * deps: etag@~1.7.0
    - Always include entity length in ETags for hash length extensions
    - Generate non-Stats ETags using MD5 only (no longer CRC32)
    - Improve stat performance by removing hashing
    - Improve support for JXcore
    - Remove base64 padding in ETags to shorten
    - Support "fake" stats objects in environments without fs
    - Use MD5 instead of MD4 in weak ETags over 1KB
  * deps: fresh@0.3.0
    - Add weak `ETag` matching support
  * deps: mkdirp@0.5.1
    - Work in global strict mode
  * deps: send@0.13.0
    - Allow Node.js HTTP server to set `Date` response header
    - Fix incorrectly removing `Content-Location` on 304 response
    - Improve the default redirect response headers
    - Send appropriate headers on default error response
    - Use `http-errors` for standard emitted errors
    - Use `statuses` instead of `http` module for status messages
    - deps: escape-html@1.0.2
    - deps: etag@~1.7.0
    - deps: fresh@0.3.0
    - deps: on-finished@~2.3.0
    - perf: enable strict mode
    - perf: remove unnecessary array allocations

3.20.3 / 2015-05-17
===================

  * deps: connect@2.29.2
    - deps: body-parser@~1.12.4
    - deps: compression@~1.4.4
    - deps: connect-timeout@~1.6.2
    - deps: debug@~2.2.0
    - deps: depd@~1.0.1
    - deps: errorhandler@~1.3.6
    - deps: finalhandler@0.3.6
    - deps: method-override@~2.3.3
    - deps: morgan@~1.5.3
    - deps: qs@2.4.2
    - deps: response-time@~2.3.1
    - deps: serve-favicon@~2.2.1
    - deps: serve-index@~1.6.4
    - deps: serve-static@~1.9.3
    - deps: type-is@~1.6.2
  * deps: debug@~2.2.0
    - deps: ms@0.7.1
  * deps: depd@~1.0.1
  * deps: proxy-addr@~1.0.8
    - deps: ipaddr.js@1.0.1
  * deps: send@0.12.3
    - deps: debug@~2.2.0
    - deps: depd@~1.0.1
    - deps: etag@~1.6.0
    - deps: ms@0.7.1
    - deps: on-finished@~2.2.1

3.20.2 / 2015-03-16
===================

  * deps: connect@2.29.1
    - deps: body-parser@~1.12.2
    - deps: compression@~1.4.3
    - deps: connect-timeout@~1.6.1
    - deps: debug@~2.1.3
    - deps: errorhandler@~1.3.5
    - deps: express-session@~1.10.4
    - deps: finalhandler@0.3.4
    - deps: method-override@~2.3.2
    - deps: morgan@~1.5.2
    - deps: qs@2.4.1
    - deps: serve-index@~1.6.3
    - deps: serve-static@~1.9.2
    - deps: type-is@~1.6.1
  * deps: debug@~2.1.3
    - Fix high intensity foreground color for bold
    - deps: ms@0.7.0
  * deps: merge-descriptors@1.0.0
  * deps: proxy-addr@~1.0.7
    - deps: ipaddr.js@0.1.9
  * deps: send@0.12.2
    - Throw errors early for invalid `extensions` or `index` options
    - deps: debug@~2.1.3

3.20.1 / 2015-02-28
===================

  * Fix `req.host` when using "trust proxy" hops count
  * Fix `req.protocol`/`req.secure` when using "trust proxy" hops count

3.20.0 / 2015-02-18
===================

  * Fix `"trust proxy"` setting to inherit when app is mounted
  * Generate `ETag`s for all request responses
    - No longer restricted to only responses for `GET` and `HEAD` requests
  * Use `content-type` to parse `Content-Type` headers
  * deps: connect@2.29.0
    - Use `content-type` to parse `Content-Type` headers
    - deps: body-parser@~1.12.0
    - deps: compression@~1.4.1
    - deps: connect-timeout@~1.6.0
    - deps: cookie-parser@~1.3.4
    - deps: cookie-signature@1.0.6
    - deps: csurf@~1.7.0
    - deps: errorhandler@~1.3.4
    - deps: express-session@~1.10.3
    - deps: http-errors@~1.3.1
    - deps: response-time@~2.3.0
    - deps: serve-index@~1.6.2
    - deps: serve-static@~1.9.1
    - deps: type-is@~1.6.0
  * deps: cookie-signature@1.0.6
  * deps: send@0.12.1
    - Always read the stat size from the file
    - Fix mutating passed-in `options`
    - deps: mime@1.3.4

3.19.2 / 2015-02-01
===================

  * deps: connect@2.28.3
    - deps: compression@~1.3.1
    - deps: csurf@~1.6.6
    - deps: errorhandler@~1.3.3
    - deps: express-session@~1.10.2
    - deps: serve-index@~1.6.1
    - deps: type-is@~1.5.6
  * deps: proxy-addr@~1.0.6
    - deps: ipaddr.js@0.1.8

3.19.1 / 2015-01-20
===================

  * deps: connect@2.28.2
    - deps: body-parser@~1.10.2
    - deps: serve-static@~1.8.1
  * deps: send@0.11.1
    - Fix root path disclosure

3.19.0 / 2015-01-09
===================

  * Fix `OPTIONS` responses to include the `HEAD` method property
  * Use `readline` for prompt in `express(1)`
  * deps: commander@2.6.0
  * deps: connect@2.28.1
    - deps: body-parser@~1.10.1
    - deps: compression@~1.3.0
    - deps: connect-timeout@~1.5.0
    - deps: csurf@~1.6.4
    - deps: debug@~2.1.1
    - deps: errorhandler@~1.3.2
    - deps: express-session@~1.10.1
    - deps: finalhandler@0.3.3
    - deps: method-override@~2.3.1
    - deps: morgan@~1.5.1
    - deps: serve-favicon@~2.2.0
    - deps: serve-index@~1.6.0
    - deps: serve-static@~1.8.0
    - deps: type-is@~1.5.5
  * deps: debug@~2.1.1
  * deps: methods@~1.1.1
  * deps: proxy-addr@~1.0.5
    - deps: ipaddr.js@0.1.6
  * deps: send@0.11.0
    - deps: debug@~2.1.1
    - deps: etag@~1.5.1
    - deps: ms@0.7.0
    - deps: on-finished@~2.2.0

3.18.6 / 2014-12-12
===================

  * Fix exception in `req.fresh`/`req.stale` without response headers

3.18.5 / 2014-12-11
===================

  * deps: connect@2.27.6
    - deps: compression@~1.2.2
    - deps: express-session@~1.9.3
    - deps: http-errors@~1.2.8
    - deps: serve-index@~1.5.3
    - deps: type-is@~1.5.4

3.18.4 / 2014-11-23
===================

  * deps: connect@2.27.4
    - deps: body-parser@~1.9.3
    - deps: compression@~1.2.1
    - deps: errorhandler@~1.2.3
    - deps: express-session@~1.9.2
    - deps: qs@2.3.3
    - deps: serve-favicon@~2.1.7
    - deps: serve-static@~1.5.1
    - deps: type-is@~1.5.3
  * deps: etag@~1.5.1
  * deps: proxy-addr@~1.0.4
    - deps: ipaddr.js@0.1.5

3.18.3 / 2014-11-09
===================

  * deps: connect@2.27.3
    - Correctly invoke async callback asynchronously
    - deps: csurf@~1.6.3

3.18.2 / 2014-10-28
===================

  * deps: connect@2.27.2
    - Fix handling of URLs containing `://` in the path
    - deps: body-parser@~1.9.2
    - deps: qs@2.3.2

3.18.1 / 2014-10-22
===================

  * Fix internal `utils.merge` deprecation warnings
  * deps: connect@2.27.1
    - deps: body-parser@~1.9.1
    - deps: express-session@~1.9.1
    - deps: finalhandler@0.3.2
    - deps: morgan@~1.4.1
    - deps: qs@2.3.0
    - deps: serve-static@~1.7.1
  * deps: send@0.10.1
    - deps: on-finished@~2.1.1

3.18.0 / 2014-10-17
===================

  * Use `content-disposition` module for `res.attachment`/`res.download`
    - Sends standards-compliant `Content-Disposition` header
    - Full Unicode support
  * Use `etag` module to generate `ETag` headers
  * deps: connect@2.27.0
    - Use `http-errors` module for creating errors
    - Use `utils-merge` module for merging objects
    - deps: body-parser@~1.9.0
    - deps: compression@~1.2.0
    - deps: connect-timeout@~1.4.0
    - deps: debug@~2.1.0
    - deps: depd@~1.0.0
    - deps: express-session@~1.9.0
    - deps: finalhandler@0.3.1
    - deps: method-override@~2.3.0
    - deps: morgan@~1.4.0
    - deps: response-time@~2.2.0
    - deps: serve-favicon@~2.1.6
    - deps: serve-index@~1.5.0
    - deps: serve-static@~1.7.0
  * deps: debug@~2.1.0
    - Implement `DEBUG_FD` env variable support
  * deps: depd@~1.0.0
  * deps: send@0.10.0
    - deps: debug@~2.1.0
    - deps: depd@~1.0.0
    - deps: etag@~1.5.0

3.17.8 / 2014-10-15
===================

  * deps: connect@2.26.6
    - deps: compression@~1.1.2
    - deps: csurf@~1.6.2
    - deps: errorhandler@~1.2.2

3.17.7 / 2014-10-08
===================

  * deps: connect@2.26.5
    - Fix accepting non-object arguments to `logger`
    - deps: serve-static@~1.6.4

3.17.6 / 2014-10-02
===================

  * deps: connect@2.26.4
    - deps: morgan@~1.3.2
    - deps: type-is@~1.5.2

3.17.5 / 2014-09-24
===================

  * deps: connect@2.26.3
    - deps: body-parser@~1.8.4
    - deps: serve-favicon@~2.1.5
    - deps: serve-static@~1.6.3
  * deps: proxy-addr@~1.0.3
    - Use `forwarded` npm module
  * deps: send@0.9.3
    - deps: etag@~1.4.0

3.17.4 / 2014-09-19
===================

  * deps: connect@2.26.2
    - deps: body-parser@~1.8.3
    - deps: qs@2.2.4

3.17.3 / 2014-09-18
===================

  * deps: proxy-addr@~1.0.2
    - Fix a global leak when multiple subnets are trusted
    - deps: ipaddr.js@0.1.3

3.17.2 / 2014-09-15
===================

  * Use `crc` instead of `buffer-crc32` for speed
  * deps: connect@2.26.1
    - deps: body-parser@~1.8.2
    - deps: depd@0.4.5
    - deps: express-session@~1.8.2
    - deps: morgan@~1.3.1
    - deps: serve-favicon@~2.1.3
    - deps: serve-static@~1.6.2
  * deps: depd@0.4.5
  * deps: send@0.9.2
    - deps: depd@0.4.5
    - deps: etag@~1.3.1
    - deps: range-parser@~1.0.2

3.17.1 / 2014-09-08
===================

  * Fix error in `req.subdomains` on empty host

3.17.0 / 2014-09-08
===================

  * Support `X-Forwarded-Host` in `req.subdomains`
  * Support IP address host in `req.subdomains`
  * deps: connect@2.26.0
    - deps: body-parser@~1.8.1
    - deps: compression@~1.1.0
    - deps: connect-timeout@~1.3.0
    - deps: cookie-parser@~1.3.3
    - deps: cookie-signature@1.0.5
    - deps: csurf@~1.6.1
    - deps: debug@~2.0.0
    - deps: errorhandler@~1.2.0
    - deps: express-session@~1.8.1
    - deps: finalhandler@0.2.0
    - deps: fresh@0.2.4
    - deps: media-typer@0.3.0
    - deps: method-override@~2.2.0
    - deps: morgan@~1.3.0
    - deps: qs@2.2.3
    - deps: serve-favicon@~2.1.3
    - deps: serve-index@~1.2.1
    - deps: serve-static@~1.6.1
    - deps: type-is@~1.5.1
    - deps: vhost@~3.0.0
  * deps: cookie-signature@1.0.5
  * deps: debug@~2.0.0
  * deps: fresh@0.2.4
  * deps: media-typer@0.3.0
    - Throw error when parameter format invalid on parse
  * deps: range-parser@~1.0.2
  * deps: send@0.9.1
    - Add `lastModified` option
    - Use `etag` to generate `ETag` header
    - deps: debug@~2.0.0
    - deps: fresh@0.2.4
  * deps: vary@~1.0.0
    - Accept valid `Vary` header string as `field`

3.16.10 / 2014-09-04
====================

  * deps: connect@2.25.10
    - deps: serve-static@~1.5.4
  * deps: send@0.8.5
    - Fix a path traversal issue when using `root`
    - Fix malicious path detection for empty string path

3.16.9 / 2014-08-29
===================

  * deps: connect@2.25.9
    - deps: body-parser@~1.6.7
    - deps: qs@2.2.2

3.16.8 / 2014-08-27
===================

  * deps: connect@2.25.8
    - deps: body-parser@~1.6.6
    - deps: csurf@~1.4.1
    - deps: qs@2.2.0

3.16.7 / 2014-08-18
===================

  * deps: connect@2.25.7
    - deps: body-parser@~1.6.5
    - deps: express-session@~1.7.6
    - deps: morgan@~1.2.3
    - deps: serve-static@~1.5.3
  * deps: send@0.8.3
    - deps: destroy@1.0.3
    - deps: on-finished@2.1.0

3.16.6 / 2014-08-14
===================

  * deps: connect@2.25.6
    - deps: body-parser@~1.6.4
    - deps: qs@1.2.2
    - deps: serve-static@~1.5.2
  * deps: send@0.8.2
    - Work around `fd` leak in Node.js 0.10 for `fs.ReadStream`

3.16.5 / 2014-08-11
===================

  * deps: connect@2.25.5
    - Fix backwards compatibility in `logger`

3.16.4 / 2014-08-10
===================

  * Fix original URL parsing in `res.location`
  * deps: connect@2.25.4
    - Fix `query` middleware breaking with argument
    - deps: body-parser@~1.6.3
    - deps: compression@~1.0.11
    - deps: connect-timeout@~1.2.2
    - deps: express-session@~1.7.5
    - deps: method-override@~2.1.3
    - deps: on-headers@~1.0.0
    - deps: parseurl@~1.3.0
    - deps: qs@1.2.1
    - deps: response-time@~2.0.1
    - deps: serve-index@~1.1.6
    - deps: serve-static@~1.5.1
  * deps: parseurl@~1.3.0

3.16.3 / 2014-08-07
===================

  * deps: connect@2.25.3
    - deps: multiparty@3.3.2

3.16.2 / 2014-08-07
===================

  * deps: connect@2.25.2
    - deps: body-parser@~1.6.2
    - deps: qs@1.2.0

3.16.1 / 2014-08-06
===================

  * deps: connect@2.25.1
    - deps: body-parser@~1.6.1
    - deps: qs@1.1.0

3.16.0 / 2014-08-05
===================

  * deps: connect@2.25.0
    - deps: body-parser@~1.6.0
    - deps: compression@~1.0.10
    - deps: csurf@~1.4.0
    - deps: express-session@~1.7.4
    - deps: qs@1.0.2
    - deps: serve-static@~1.5.0
  * deps: send@0.8.1
    - Add `extensions` option

3.15.3 / 2014-08-04
===================

  * fix `res.sendfile` regression for serving directory index files
  * deps: connect@2.24.3
    - deps: serve-index@~1.1.5
    - deps: serve-static@~1.4.4
  * deps: send@0.7.4
    - Fix incorrect 403 on Windows and Node.js 0.11
    - Fix serving index files without root dir

3.15.2 / 2014-07-27
===================

  * deps: connect@2.24.2
    - deps: body-parser@~1.5.2
    - deps: depd@0.4.4
    - deps: express-session@~1.7.2
    - deps: morgan@~1.2.2
    - deps: serve-static@~1.4.2
  * deps: depd@0.4.4
    - Work-around v8 generating empty stack traces
  * deps: send@0.7.2
    - deps: depd@0.4.4

3.15.1 / 2014-07-26
===================

  * deps: connect@2.24.1
    - deps: body-parser@~1.5.1
    - deps: depd@0.4.3
    - deps: express-session@~1.7.1
    - deps: morgan@~1.2.1
    - deps: serve-index@~1.1.4
    - deps: serve-static@~1.4.1
  * deps: depd@0.4.3
    - Fix exception when global `Error.stackTraceLimit` is too low
  * deps: send@0.7.1
    - deps: depd@0.4.3

3.15.0 / 2014-07-22
===================

  * Fix `req.protocol` for proxy-direct connections
  * Pass options from `res.sendfile` to `send`
  * deps: connect@2.24.0
    - deps: body-parser@~1.5.0
    - deps: compression@~1.0.9
    - deps: connect-timeout@~1.2.1
    - deps: debug@1.0.4
    - deps: depd@0.4.2
    - deps: express-session@~1.7.0
    - deps: finalhandler@0.1.0
    - deps: method-override@~2.1.2
    - deps: morgan@~1.2.0
    - deps: multiparty@3.3.1
    - deps: parseurl@~1.2.0
    - deps: serve-static@~1.4.0
  * deps: debug@1.0.4
  * deps: depd@0.4.2
    - Add `TRACE_DEPRECATION` environment variable
    - Remove non-standard grey color from color output
    - Support `--no-deprecation` argument
    - Support `--trace-deprecation` argument
  * deps: parseurl@~1.2.0
    - Cache URLs based on original value
    - Remove no-longer-needed URL mis-parse work-around
    - Simplify the "fast-path" `RegExp`
  * deps: send@0.7.0
    - Add `dotfiles` option
    - Cap `maxAge` value to 1 year
    - deps: debug@1.0.4
    - deps: depd@0.4.2

3.14.0 / 2014-07-11
===================

 * add explicit "Rosetta Flash JSONP abuse" protection
   - previous versions are not vulnerable; this is just explicit protection
 * deprecate `res.redirect(url, status)` -- use `res.redirect(status, url)` instead
 * fix `res.send(status, num)` to send `num` as json (not error)
 * remove unnecessary escaping when `res.jsonp` returns JSON response
 * deps: basic-auth@1.0.0
   - support empty password
   - support empty username
 * deps: connect@2.23.0
   - deps: debug@1.0.3
   - deps: express-session@~1.6.4
   - deps: method-override@~2.1.0
   - deps: parseurl@~1.1.3
   - deps: serve-static@~1.3.1
  * deps: debug@1.0.3
    - Add support for multiple wildcards in namespaces
  * deps: methods@1.1.0
    - add `CONNECT`
  * deps: parseurl@~1.1.3
    - faster parsing of href-only URLs

3.13.0 / 2014-07-03
===================

 * add deprecation message to `app.configure`
 * add deprecation message to `req.auth`
 * use `basic-auth` to parse `Authorization` header
 * deps: connect@2.22.0
   - deps: csurf@~1.3.0
   - deps: express-session@~1.6.1
   - deps: multiparty@3.3.0
   - deps: serve-static@~1.3.0
 * deps: send@0.5.0
   - Accept string for `maxage` (converted by `ms`)
   - Include link in default redirect response

3.12.1 / 2014-06-26
===================

 * deps: connect@2.21.1
   - deps: cookie-parser@1.3.2
   - deps: cookie-signature@1.0.4
   - deps: express-session@~1.5.2
   - deps: type-is@~1.3.2
 * deps: cookie-signature@1.0.4
   - fix for timing attacks

3.12.0 / 2014-06-21
===================

 * use `media-typer` to alter content-type charset
 * deps: connect@2.21.0
   - deprecate `connect(middleware)` -- use `app.use(middleware)` instead
   - deprecate `connect.createServer()` -- use `connect()` instead
   - fix `res.setHeader()` patch to work with get -> append -> set pattern
   - deps: compression@~1.0.8
   - deps: errorhandler@~1.1.1
   - deps: express-session@~1.5.0
   - deps: serve-index@~1.1.3

3.11.0 / 2014-06-19
===================

 * deprecate things with `depd` module
 * deps: buffer-crc32@0.2.3
 * deps: connect@2.20.2
   - deprecate `verify` option to `json` -- use `body-parser` npm module instead
   - deprecate `verify` option to `urlencoded` -- use `body-parser` npm module instead
   - deprecate things with `depd` module
   - use `finalhandler` for final response handling
   - use `media-typer` to parse `content-type` for charset
   - deps: body-parser@1.4.3
   - deps: connect-timeout@1.1.1
   - deps: cookie-parser@1.3.1
   - deps: csurf@1.2.2
   - deps: errorhandler@1.1.0
   - deps: express-session@1.4.0
   - deps: multiparty@3.2.9
   - deps: serve-index@1.1.2
   - deps: type-is@1.3.1
   - deps: vhost@2.0.0

3.10.5 / 2014-06-11
===================

 * deps: connect@2.19.6
   - deps: body-parser@1.3.1
   - deps: compression@1.0.7
   - deps: debug@1.0.2
   - deps: serve-index@1.1.1
   - deps: serve-static@1.2.3
 * deps: debug@1.0.2
 * deps: send@0.4.3
   - Do not throw uncatchable error on file open race condition
   - Use `escape-html` for HTML escaping
   - deps: debug@1.0.2
   - deps: finished@1.2.2
   - deps: fresh@0.2.2

3.10.4 / 2014-06-09
===================

 * deps: connect@2.19.5
   - fix "event emitter leak" warnings
   - deps: csurf@1.2.1
   - deps: debug@1.0.1
   - deps: serve-static@1.2.2
   - deps: type-is@1.2.1
 * deps: debug@1.0.1
 * deps: send@0.4.2
   - fix "event emitter leak" warnings
   - deps: finished@1.2.1
   - deps: debug@1.0.1

3.10.3 / 2014-06-05
===================

 * use `vary` module for `res.vary`
 * deps: connect@2.19.4
   - deps: errorhandler@1.0.2
   - deps: method-override@2.0.2
   - deps: serve-favicon@2.0.1
 * deps: debug@1.0.0

3.10.2 / 2014-06-03
===================

 * deps: connect@2.19.3
   - deps: compression@1.0.6

3.10.1 / 2014-06-03
===================

 * deps: connect@2.19.2
   - deps: compression@1.0.4
 * deps: proxy-addr@1.0.1

3.10.0 / 2014-06-02
===================

 * deps: connect@2.19.1
   - deprecate `methodOverride()` -- use `method-override` npm module instead
   - deps: body-parser@1.3.0
   - deps: method-override@2.0.1
   - deps: multiparty@3.2.8
   - deps: response-time@2.0.0
   - deps: serve-static@1.2.1
 * deps: methods@1.0.1
 * deps: send@0.4.1
   - Send `max-age` in `Cache-Control` in correct format

3.9.0 / 2014-05-30
==================

 * custom etag control with `app.set('etag', val)`
   - `app.set('etag', function(body, encoding){ return '"etag"' })` custom etag generation
   - `app.set('etag', 'weak')` weak tag
   - `app.set('etag', 'strong')` strong etag
   - `app.set('etag', false)` turn off
   - `app.set('etag', true)` standard etag
 * Include ETag in HEAD requests
 * mark `res.send` ETag as weak and reduce collisions
 * update connect to 2.18.0
   - deps: compression@1.0.3
   - deps: serve-index@1.1.0
   - deps: serve-static@1.2.0
 * update send to 0.4.0
   - Calculate ETag with md5 for reduced collisions
   - Ignore stream errors after request ends
   - deps: debug@0.8.1

3.8.1 / 2014-05-27
==================

 * update connect to 2.17.3
   - deps: body-parser@1.2.2
   - deps: express-session@1.2.1
   - deps: method-override@1.0.2

3.8.0 / 2014-05-21
==================

 * keep previous `Content-Type` for `res.jsonp`
 * set proper `charset` in `Content-Type` for `res.send`
 * update connect to 2.17.1
   - fix `res.charset` appending charset when `content-type` has one
   - deps: express-session@1.2.0
   - deps: morgan@1.1.1
   - deps: serve-index@1.0.3

3.7.0 / 2014-05-18
==================

 * proper proxy trust with `app.set('trust proxy', trust)`
   - `app.set('trust proxy', 1)` trust first hop
   - `app.set('trust proxy', 'loopback')` trust loopback addresses
   - `app.set('trust proxy', '10.0.0.1')` trust single IP
   - `app.set('trust proxy', '10.0.0.1/16')` trust subnet
   - `app.set('trust proxy', '10.0.0.1, 10.0.0.2')` trust list
   - `app.set('trust proxy', false)` turn off
   - `app.set('trust proxy', true)` trust everything
 * update connect to 2.16.2
   - deprecate `res.headerSent` -- use `res.headersSent`
   - deprecate `res.on("header")` -- use on-headers module instead
   - fix edge-case in `res.appendHeader` that would append in wrong order
   - json: use body-parser
   - urlencoded: use body-parser
   - dep: bytes@1.0.0
   - dep: cookie-parser@1.1.0
   - dep: csurf@1.2.0
   - dep: express-session@1.1.0
   - dep: method-override@1.0.1

3.6.0 / 2014-05-09
==================

 * deprecate `app.del()` -- use `app.delete()` instead
 * deprecate `res.json(obj, status)` -- use `res.json(status, obj)` instead
   - the edge-case `res.json(status, num)` requires `res.status(status).json(num)`
 * deprecate `res.jsonp(obj, status)` -- use `res.jsonp(status, obj)` instead
   - the edge-case `res.jsonp(status, num)` requires `res.status(status).jsonp(num)`
 * support PURGE method
   - add `app.purge`
   - add `router.purge`
   - include PURGE in `app.all`
 * update connect to 2.15.0
   * Add `res.appendHeader`
   * Call error stack even when response has been sent
   * Patch `res.headerSent` to return Boolean
   * Patch `res.headersSent` for node.js 0.8
   * Prevent default 404 handler after response sent
   * dep: compression@1.0.2
   * dep: connect-timeout@1.1.0
   * dep: debug@^0.8.0
   * dep: errorhandler@1.0.1
   * dep: express-session@1.0.4
   * dep: morgan@1.0.1
   * dep: serve-favicon@2.0.0
   * dep: serve-index@1.0.2
 * update debug to 0.8.0
   * add `enable()` method
   * change from stderr to stdout
 * update methods to 1.0.0
   - add PURGE
 * update mkdirp to 0.5.0

3.5.3 / 2014-05-08
==================

 * fix `req.host` for IPv6 literals
 * fix `res.jsonp` error if callback param is object

3.5.2 / 2014-04-24
==================

 * update connect to 2.14.5
 * update cookie to 0.1.2
 * update mkdirp to 0.4.0
 * update send to 0.3.0

3.5.1 / 2014-03-25
==================

 * pin less-middleware in generated app

3.5.0 / 2014-03-06
==================

 * bump deps

3.4.8 / 2014-01-13
==================

 * prevent incorrect automatic OPTIONS responses #1868 @dpatti
 * update binary and examples for jade 1.0 #1876 @yossi, #1877 @reqshark, #1892 @matheusazzi
 * throw 400 in case of malformed paths @rlidwka

3.4.7 / 2013-12-10
==================

 * update connect

3.4.6 / 2013-12-01
==================

 * update connect (raw-body)

3.4.5 / 2013-11-27
==================

 * update connect
 * res.location: remove leading ./ #1802 @kapouer
 * res.redirect: fix `res.redirect('toString') #1829 @michaelficarra
 * res.send: always send ETag when content-length > 0
 * router: add Router.all() method

3.4.4 / 2013-10-29
==================

 * update connect
 * update supertest
 * update methods
 * express(1): replace bodyParser() with urlencoded() and json() #1795 @chirag04

3.4.3 / 2013-10-23
==================

 * update connect

3.4.2 / 2013-10-18
==================

 * update connect
 * downgrade commander

3.4.1 / 2013-10-15
==================

 * update connect
 * update commander
 * jsonp: check if callback is a function
 * router: wrap encodeURIComponent in a try/catch #1735 (@lxe)
 * res.format: now includes charset @1747 (@sorribas)
 * res.links: allow multiple calls @1746 (@sorribas)

3.4.0 / 2013-09-07
==================

 * add res.vary(). Closes #1682
 * update connect

3.3.8 / 2013-09-02
==================

 * update connect

3.3.7 / 2013-08-28
==================

 * update connect

3.3.6 / 2013-08-27
==================

 * Revert "remove charset from json responses. Closes #1631" (causes issues in some clients)
 * add: req.accepts take an argument list

3.3.4 / 2013-07-08
==================

 * update send and connect

3.3.3 / 2013-07-04
==================

 * update connect

3.3.2 / 2013-07-03
==================

 * update connect
 * update send
 * remove .version export

3.3.1 / 2013-06-27
==================

 * update connect

3.3.0 / 2013-06-26
==================

 * update connect
 * add support for multiple X-Forwarded-Proto values. Closes #1646
 * change: remove charset from json responses. Closes #1631
 * change: return actual booleans from req.accept* functions
 * fix jsonp callback array throw

3.2.6 / 2013-06-02
==================

 * update connect

3.2.5 / 2013-05-21
==================

 * update connect
 * update node-cookie
 * add: throw a meaningful error when there is no default engine
 * change generation of ETags with res.send() to GET requests only. Closes #1619

3.2.4 / 2013-05-09
==================

  * fix `req.subdomains` when no Host is present
  * fix `req.host` when no Host is present, return undefined

3.2.3 / 2013-05-07
==================

  * update connect / qs

3.2.2 / 2013-05-03
==================

  * update qs

3.2.1 / 2013-04-29
==================

  * add app.VERB() paths array deprecation warning
  * update connect
  * update qs and remove all ~ semver crap
  * fix: accept number as value of Signed Cookie

3.2.0 / 2013-04-15
==================

  * add "view" constructor setting to override view behaviour
  * add req.acceptsEncoding(name)
  * add req.acceptedEncodings
  * revert cookie signature change causing session race conditions
  * fix sorting of Accept values of the same quality

3.1.2 / 2013-04-12
==================

  * add support for custom Accept parameters
  * update cookie-signature

3.1.1 / 2013-04-01
==================

  * add X-Forwarded-Host support to `req.host`
  * fix relative redirects
  * update mkdirp
  * update buffer-crc32
  * remove legacy app.configure() method from app template.

3.1.0 / 2013-01-25
==================

  * add support for leading "." in "view engine" setting
  * add array support to `res.set()`
  * add node 0.8.x to travis.yml
  * add "subdomain offset" setting for tweaking `req.subdomains`
  * add `res.location(url)` implementing `res.redirect()`-like setting of Location
  * use app.get() for x-powered-by setting for inheritance
  * fix colons in passwords for `req.auth`

3.0.6 / 2013-01-04
==================

  * add http verb methods to Router
  * update connect
  * fix mangling of the `res.cookie()` options object
  * fix jsonp whitespace escape. Closes #1132

3.0.5 / 2012-12-19
==================

  * add throwing when a non-function is passed to a route
  * fix: explicitly remove Transfer-Encoding header from 204 and 304 responses
  * revert "add 'etag' option"

3.0.4 / 2012-12-05
==================

  * add 'etag' option to disable `res.send()` Etags
  * add escaping of urls in text/plain in `res.redirect()`
    for old browsers interpreting as html
  * change crc32 module for a more liberal license
  * update connect

3.0.3 / 2012-11-13
==================

  * update connect
  * update cookie module
  * fix cookie max-age

3.0.2 / 2012-11-08
==================

  * add OPTIONS to cors example. Closes #1398
  * fix route chaining regression. Closes #1397

3.0.1 / 2012-11-01
==================

  * update connect

3.0.0 / 2012-10-23
==================

  * add `make clean`
  * add "Basic" check to req.auth
  * add `req.auth` test coverage
  * add cb && cb(payload) to `res.jsonp()`. Closes #1374
  * add backwards compat for `res.redirect()` status. Closes #1336
  * add support for `res.json()` to retain previously defined Content-Types. Closes #1349
  * update connect
  * change `res.redirect()` to utilize a pathname-relative Location again. Closes #1382
  * remove non-primitive string support for `res.send()`
  * fix view-locals example. Closes #1370
  * fix route-separation example

3.0.0rc5 / 2012-09-18
==================

  * update connect
  * add redis search example
  * add static-files example
  * add "x-powered-by" setting (`app.disable('x-powered-by')`)
  * add "application/octet-stream" redirect Accept test case. Closes #1317

3.0.0rc4 / 2012-08-30
==================

  * add `res.jsonp()`. Closes #1307
  * add "verbose errors" option to error-pages example
  * add another route example to express(1) so people are not so confused
  * add redis online user activity tracking example
  * update connect dep
  * fix etag quoting. Closes #1310
  * fix error-pages 404 status
  * fix jsonp callback char restrictions
  * remove old OPTIONS default response

3.0.0rc3 / 2012-08-13
==================

  * update connect dep
  * fix signed cookies to work with `connect.cookieParser()` ("s:" prefix was missing) [tnydwrds]
  * fix `res.render()` clobbering of "locals"

3.0.0rc2 / 2012-08-03
==================

  * add CORS example
  * update connect dep
  * deprecate `.createServer()` & remove old stale examples
  * fix: escape `res.redirect()` link
  * fix vhost example

3.0.0rc1 / 2012-07-24
==================

  * add more examples to view-locals
  * add scheme-relative redirects (`res.redirect("//foo.com")`) support
  * update cookie dep
  * update connect dep
  * update send dep
  * fix `express(1)` -h flag, use -H for hogan. Closes #1245
  * fix `res.sendfile()` socket error handling regression

3.0.0beta7 / 2012-07-16
==================

  * update connect dep for `send()` root normalization regression

3.0.0beta6 / 2012-07-13
==================

  * add `err.view` property for view errors. Closes #1226
  * add "jsonp callback name" setting
  * add support for "/foo/:bar*" non-greedy matches
  * change `res.sendfile()` to use `send()` module
  * change `res.send` to use "response-send" module
  * remove `app.locals.use` and `res.locals.use`, use regular middleware

3.0.0beta5 / 2012-07-03
==================

  * add "make check" support
  * add route-map example
  * add `res.json(obj, status)` support back for BC
  * add "methods" dep, remove internal methods module
  * update connect dep
  * update auth example to utilize cores pbkdf2
  * updated tests to use "supertest"

3.0.0beta4 / 2012-06-25
==================

  * Added `req.auth`
  * Added `req.range(size)`
  * Added `res.links(obj)`
  * Added `res.send(body, status)` support back for backwards compat
  * Added `.default()` support to `res.format()`
  * Added 2xx / 304 check to `req.fresh`
  * Revert "Added + support to the router"
  * Fixed `res.send()` freshness check, respect res.statusCode

3.0.0beta3 / 2012-06-15
==================

  * Added hogan `--hjs` to express(1) [nullfirm]
  * Added another example to content-negotiation
  * Added `fresh` dep
  * Changed: `res.send()` always checks freshness
  * Fixed: expose connects mime module. Closes #1165

3.0.0beta2 / 2012-06-06
==================

  * Added `+` support to the router
  * Added `req.host`
  * Changed `req.param()` to check route first
  * Update connect dep

3.0.0beta1 / 2012-06-01
==================

  * Added `res.format()` callback to override default 406 behaviour
  * Fixed `res.redirect()` 406. Closes #1154

3.0.0alpha5 / 2012-05-30
==================

  * Added `req.ip`
  * Added `{ signed: true }` option to `res.cookie()`
  * Removed `res.signedCookie()`
  * Changed: dont reverse `req.ips`
  * Fixed "trust proxy" setting check for `req.ips`

3.0.0alpha4 / 2012-05-09
==================

  * Added: allow `[]` in jsonp callback. Closes #1128
  * Added `PORT` env var support in generated template. Closes #1118 [benatkin]
  * Updated: connect 2.2.2

3.0.0alpha3 / 2012-05-04
==================

  * Added public `app.routes`. Closes #887
  * Added _view-locals_ example
  * Added _mvc_ example
  * Added `res.locals.use()`. Closes #1120
  * Added conditional-GET support to `res.send()`
  * Added: coerce `res.set()` values to strings
  * Changed: moved `static()` in generated apps below router
  * Changed: `res.send()` only set ETag when not previously set
  * Changed connect 2.2.1 dep
  * Changed: `make test` now runs unit / acceptance tests
  * Fixed req/res proto inheritance

3.0.0alpha2 / 2012-04-26
==================

  * Added `make benchmark` back
  * Added `res.send()` support for `String` objects
  * Added client-side data exposing example
  * Added `res.header()` and `req.header()` aliases for BC
  * Added `express.createServer()` for BC
  * Perf: memoize parsed urls
  * Perf: connect 2.2.0 dep
  * Changed: make `expressInit()` middleware self-aware
  * Fixed: use app.get() for all core settings
  * Fixed redis session example
  * Fixed session example. Closes #1105
  * Fixed generated express dep. Closes #1078

3.0.0alpha1 / 2012-04-15
==================

  * Added `app.locals.use(callback)`
  * Added `app.locals` object
  * Added `app.locals(obj)`
  * Added `res.locals` object
  * Added `res.locals(obj)`
  * Added `res.format()` for content-negotiation
  * Added `app.engine()`
  * Added `res.cookie()` JSON cookie support
  * Added "trust proxy" setting
  * Added `req.subdomains`
  * Added `req.protocol`
  * Added `req.secure`
  * Added `req.path`
  * Added `req.ips`
  * Added `req.fresh`
  * Added `req.stale`
  * Added comma-delimited / array support for `req.accepts()`
  * Added debug instrumentation
  * Added `res.set(obj)`
  * Added `res.set(field, value)`
  * Added `res.get(field)`
  * Added `app.get(setting)`. Closes #842
  * Added `req.acceptsLanguage()`
  * Added `req.acceptsCharset()`
  * Added `req.accepted`
  * Added `req.acceptedLanguages`
  * Added `req.acceptedCharsets`
  * Added "json replacer" setting
  * Added "json spaces" setting
  * Added X-Forwarded-Proto support to `res.redirect()`. Closes #92
  * Added `--less` support to express(1)
  * Added `express.response` prototype
  * Added `express.request` prototype
  * Added `express.application` prototype
  * Added `app.path()`
  * Added `app.render()`
  * Added `res.type()` to replace `res.contentType()`
  * Changed: `res.redirect()` to add relative support
  * Changed: enable "jsonp callback" by default
  * Changed: renamed "case sensitive routes" to "case sensitive routing"
  * Rewrite of all tests with mocha
  * Removed "root" setting
  * Removed `res.redirect('home')` support
  * Removed `req.notify()`
  * Removed `app.register()`
  * Removed `app.redirect()`
  * Removed `app.is()`
  * Removed `app.helpers()`
  * Removed `app.dynamicHelpers()`
  * Fixed `res.sendfile()` with non-GET. Closes #723
  * Fixed express(1) public dir for windows. Closes #866

2.5.9/ 2012-04-02
==================

  * Added support for PURGE request method [pbuyle]
  * Fixed `express(1)` generated app `app.address()` before `listening` [mmalecki]

2.5.8 / 2012-02-08
==================

  * Update mkdirp dep. Closes #991

2.5.7 / 2012-02-06
==================

  * Fixed `app.all` duplicate DELETE requests [mscdex]

2.5.6 / 2012-01-13
==================

  * Updated hamljs dev dep. Closes #953

2.5.5 / 2012-01-08
==================

  * Fixed: set `filename` on cached templates [matthewleon]

2.5.4 / 2012-01-02
==================

  * Fixed `express(1)` eol on 0.4.x. Closes #947

2.5.3 / 2011-12-30
==================

  * Fixed `req.is()` when a charset is present

2.5.2 / 2011-12-10
==================

  * Fixed: express(1) LF -> CRLF for windows

2.5.1 / 2011-11-17
==================

  * Changed: updated connect to 1.8.x
  * Removed sass.js support from express(1)

2.5.0 / 2011-10-24
==================

  * Added ./routes dir for generated app by default
  * Added npm install reminder to express(1) app gen
  * Added 0.5.x support
  * Removed `make test-cov` since it wont work with node 0.5.x
  * Fixed express(1) public dir for windows. Closes #866

2.4.7 / 2011-10-05
==================

  * Added mkdirp to express(1). Closes #795
  * Added simple _json-config_ example
  * Added  shorthand for the parsed request's pathname via `req.path`
  * Changed connect dep to 1.7.x to fix npm issue...
  * Fixed `res.redirect()` __HEAD__ support. [reported by xerox]
  * Fixed `req.flash()`, only escape args
  * Fixed absolute path checking on windows. Closes #829 [reported by andrewpmckenzie]

2.4.6 / 2011-08-22
==================

  * Fixed multiple param callback regression. Closes #824 [reported by TroyGoode]

2.4.5 / 2011-08-19
==================

  * Added support for routes to handle errors. Closes #809
  * Added `app.routes.all()`. Closes #803
  * Added "basepath" setting to work in conjunction with reverse proxies etc.
  * Refactored `Route` to use a single array of callbacks
  * Added support for multiple callbacks for `app.param()`. Closes #801
Closes #805
  * Changed: removed .call(self) for route callbacks
  * Dependency: `qs >= 0.3.1`
  * Fixed `res.redirect()` on windows due to `join()` usage. Closes #808

2.4.4 / 2011-08-05
==================

  * Fixed `res.header()` intention of a set, even when `undefined`
  * Fixed `*`, value no longer required
  * Fixed `res.send(204)` support. Closes #771

2.4.3 / 2011-07-14
==================

  * Added docs for `status` option special-case. Closes #739
  * Fixed `options.filename`, exposing the view path to template engines

2.4.2. / 2011-07-06
==================

  * Revert "removed jsonp stripping" for XSS

2.4.1 / 2011-07-06
==================

  * Added `res.json()` JSONP support. Closes #737
  * Added _extending-templates_ example. Closes #730
  * Added "strict routing" setting for trailing slashes
  * Added support for multiple envs in `app.configure()` calls. Closes #735
  * Changed: `res.send()` using `res.json()`
  * Changed: when cookie `path === null` don't default it
  * Changed; default cookie path to "home" setting. Closes #731
  * Removed _pids/logs_ creation from express(1)

2.4.0 / 2011-06-28
==================

  * Added chainable `res.status(code)`
  * Added `res.json()`, an explicit version of `res.send(obj)`
  * Added simple web-service example

2.3.12 / 2011-06-22
==================

  * \#express is now on freenode! come join!
  * Added `req.get(field, param)`
  * Added links to Japanese documentation, thanks @hideyukisaito!
  * Added; the `express(1)` generated app outputs the env
  * Added `content-negotiation` example
  * Dependency: connect >= 1.5.1 < 2.0.0
  * Fixed view layout bug. Closes #720
  * Fixed; ignore body on 304. Closes #701

2.3.11 / 2011-06-04
==================

  * Added `npm test`
  * Removed generation of dummy test file from `express(1)`
  * Fixed; `express(1)` adds express as a dep
  * Fixed; prune on `prepublish`

2.3.10 / 2011-05-27
==================

  * Added `req.route`, exposing the current route
  * Added _package.json_ generation support to `express(1)`
  * Fixed call to `app.param()` function for optional params. Closes #682

2.3.9 / 2011-05-25
==================

  * Fixed bug-ish with `../' in `res.partial()` calls

2.3.8 / 2011-05-24
==================

  * Fixed `app.options()`

2.3.7 / 2011-05-23
==================

  * Added route `Collection`, ex: `app.get('/user/:id').remove();`
  * Added support for `app.param(fn)` to define param logic
  * Removed `app.param()` support for callback with return value
  * Removed module.parent check from express(1) generated app. Closes #670
  * Refactored router. Closes #639

2.3.6 / 2011-05-20
==================

  * Changed; using devDependencies instead of git submodules
  * Fixed redis session example
  * Fixed markdown example
  * Fixed view caching, should not be enabled in development

2.3.5 / 2011-05-20
==================

  * Added export `.view` as alias for `.View`

2.3.4 / 2011-05-08
==================

  * Added `./examples/say`
  * Fixed `res.sendfile()` bug preventing the transfer of files with spaces

2.3.3 / 2011-05-03
==================

  * Added "case sensitive routes" option.
  * Changed; split methods supported per rfc [slaskis]
  * Fixed route-specific middleware when using the same callback function several times

2.3.2 / 2011-04-27
==================

  * Fixed view hints

2.3.1 / 2011-04-26
==================

  * Added `app.match()` as `app.match.all()`
  * Added `app.lookup()` as `app.lookup.all()`
  * Added `app.remove()` for `app.remove.all()`
  * Added `app.remove.VERB()`
  * Fixed template caching collision issue. Closes #644
  * Moved router over from connect and started refactor

2.3.0 / 2011-04-25
==================

  * Added options support to `res.clearCookie()`
  * Added `res.helpers()` as alias of `res.locals()`
  * Added; json defaults to UTF-8 with `res.send()`. Closes #632. [Daniel   * Dependency `connect >= 1.4.0`
  * Changed; auto set Content-Type in res.attachement [Aaron Heckmann]
  * Renamed "cache views" to "view cache". Closes #628
  * Fixed caching of views when using several apps. Closes #637
  * Fixed gotcha invoking `app.param()` callbacks once per route middleware.
Closes #638
  * Fixed partial lookup precedence. Closes #631
Shaw]

2.2.2 / 2011-04-12
==================

  * Added second callback support for `res.download()` connection errors
  * Fixed `filename` option passing to template engine

2.2.1 / 2011-04-04
==================

  * Added `layout(path)` helper to change the layout within a view. Closes #610
  * Fixed `partial()` collection object support.
    Previously only anything with `.length` would work.
    When `.length` is present one must still be aware of holes,
    however now `{ collection: {foo: 'bar'}}` is valid, exposes
    `keyInCollection` and `keysInCollection`.

  * Performance improved with better view caching
  * Removed `request` and `response` locals
  * Changed; errorHandler page title is now `Express` instead of `Connect`

2.2.0 / 2011-03-30
==================

  * Added `app.lookup.VERB()`, ex `app.lookup.put('/user/:id')`. Closes #606
  * Added `app.match.VERB()`, ex `app.match.put('/user/12')`. Closes #606
  * Added `app.VERB(path)` as alias of `app.lookup.VERB()`.
  * Dependency `connect >= 1.2.0`

2.1.1 / 2011-03-29
==================

  * Added; expose `err.view` object when failing to locate a view
  * Fixed `res.partial()` call `next(err)` when no callback is given [reported by aheckmann]
  * Fixed; `res.send(undefined)` responds with 204 [aheckmann]

2.1.0 / 2011-03-24
==================

  * Added `<root>/_?<name>` partial lookup support. Closes #447
  * Added `request`, `response`, and `app` local variables
  * Added `settings` local variable, containing the app's settings
  * Added `req.flash()` exception if `req.session` is not available
  * Added `res.send(bool)` support (json response)
  * Fixed stylus example for latest version
  * Fixed; wrap try/catch around `res.render()`

2.0.0 / 2011-03-17
==================

  * Fixed up index view path alternative.
  * Changed; `res.locals()` without object returns the locals

2.0.0rc3 / 2011-03-17
==================

  * Added `res.locals(obj)` to compliment `res.local(key, val)`
  * Added `res.partial()` callback support
  * Fixed recursive error reporting issue in `res.render()`

2.0.0rc2 / 2011-03-17
==================

  * Changed; `partial()` "locals" are now optional
  * Fixed `SlowBuffer` support. Closes #584 [reported by tyrda01]
  * Fixed .filename view engine option [reported by drudge]
  * Fixed blog example
  * Fixed `{req,res}.app` reference when mounting [Ben Weaver]

2.0.0rc / 2011-03-14
==================

  * Fixed; expose `HTTPSServer` constructor
  * Fixed express(1) default test charset. Closes #579 [reported by secoif]
  * Fixed; default charset to utf-8 instead of utf8 for lame IE [reported by NickP]

2.0.0beta3 / 2011-03-09
==================

  * Added support for `res.contentType()` literal
    The original `res.contentType('.json')`,
    `res.contentType('application/json')`, and `res.contentType('json')`
    will work now.
  * Added `res.render()` status option support back
  * Added charset option for `res.render()`
  * Added `.charset` support (via connect 1.0.4)
  * Added view resolution hints when in development and a lookup fails
  * Added layout lookup support relative to the page view.
    For example while rendering `./views/user/index.jade` if you create
    `./views/user/layout.jade` it will be used in favour of the root layout.
  * Fixed `res.redirect()`. RFC states absolute url [reported by unlink]
  * Fixed; default `res.send()` string charset to utf8
  * Removed `Partial` constructor (not currently used)

2.0.0beta2 / 2011-03-07
==================

  * Added res.render() `.locals` support back to aid in migration process
  * Fixed flash example

2.0.0beta / 2011-03-03
==================

  * Added HTTPS support
  * Added `res.cookie()` maxAge support
  * Added `req.header()` _Referrer_ / _Referer_ special-case, either works
  * Added mount support for `res.redirect()`, now respects the mount-point
  * Added `union()` util, taking place of `merge(clone())` combo
  * Added stylus support to express(1) generated app
  * Added secret to session middleware used in examples and generated app
  * Added `res.local(name, val)` for progressive view locals
  * Added default param support to `req.param(name, default)`
  * Added `app.disabled()` and `app.enabled()`
  * Added `app.register()` support for omitting leading ".", either works
  * Added `res.partial()`, using the same interface as `partial()` within a view. Closes #539
  * Added `app.param()` to map route params to async/sync logic
  * Added; aliased `app.helpers()` as `app.locals()`. Closes #481
  * Added extname with no leading "." support to `res.contentType()`
  * Added `cache views` setting, defaulting to enabled in "production" env
  * Added index file partial resolution, eg: partial('user') may try _views/user/index.jade_.
  * Added `req.accepts()` support for extensions
  * Changed; `res.download()` and `res.sendfile()` now utilize Connect's
    static file server `connect.static.send()`.
  * Changed; replaced `connect.utils.mime()` with npm _mime_ module
  * Changed; allow `req.query` to be pre-defined (via middleware or other parent
  * Changed view partial resolution, now relative to parent view
  * Changed view engine signature. no longer `engine.render(str, options, callback)`, now `engine.compile(str, options) -> Function`, the returned function accepts `fn(locals)`.
  * Fixed `req.param()` bug returning Array.prototype methods. Closes #552
  * Fixed; using `Stream#pipe()` instead of `sys.pump()` in `res.sendfile()`
  * Fixed; using _qs_ module instead of _querystring_
  * Fixed; strip unsafe chars from jsonp callbacks
  * Removed "stream threshold" setting

1.0.8 / 2011-03-01
==================

  * Allow `req.query` to be pre-defined (via middleware or other parent app)
  * "connect": ">= 0.5.0 < 1.0.0". Closes #547
  * Removed the long deprecated __EXPRESS_ENV__ support

1.0.7 / 2011-02-07
==================

  * Fixed `render()` setting inheritance.
    Mounted apps would not inherit "view engine"

1.0.6 / 2011-02-07
==================

  * Fixed `view engine` setting bug when period is in dirname

1.0.5 / 2011-02-05
==================

  * Added secret to generated app `session()` call

1.0.4 / 2011-02-05
==================

  * Added `qs` dependency to _package.json_
  * Fixed namespaced `require()`s for latest connect support

1.0.3 / 2011-01-13
==================

  * Remove unsafe characters from JSONP callback names [Ryan Grove]

1.0.2 / 2011-01-10
==================

  * Removed nested require, using `connect.router`

1.0.1 / 2010-12-29
==================

  * Fixed for middleware stacked via `createServer()`
    previously the `foo` middleware passed to `createServer(foo)`
    would not have access to Express methods such as `res.send()`
    or props like `req.query` etc.

1.0.0 / 2010-11-16
==================

  * Added; deduce partial object names from the last segment.
    For example by default `partial('forum/post', postObject)` will
    give you the _post_ object, providing a meaningful default.
  * Added http status code string representation to `res.redirect()` body
  * Added; `res.redirect()` supporting _text/plain_ and _text/html_ via __Accept__.
  * Added `req.is()` to aid in content negotiation
  * Added partial local inheritance [suggested by masylum]. Closes #102
    providing access to parent template locals.
  * Added _-s, --session[s]_ flag to express(1) to add session related middleware
  * Added _--template_ flag to express(1) to specify the
    template engine to use.
  * Added _--css_ flag to express(1) to specify the
    stylesheet engine to use (or just plain css by default).
  * Added `app.all()` support [thanks aheckmann]
  * Added partial direct object support.
    You may now `partial('user', user)` providing the "user" local,
    vs previously `partial('user', { object: user })`.
  * Added _route-separation_ example since many people question ways
    to do this with CommonJS modules. Also view the _blog_ example for
    an alternative.
  * Performance; caching view path derived partial object names
  * Fixed partial local inheritance precedence. [reported by Nick Poulden] Closes #454
  * Fixed jsonp support; _text/javascript_ as per mailinglist discussion

1.0.0rc4 / 2010-10-14
==================

  * Added _NODE_ENV_ support, _EXPRESS_ENV_ is deprecated and will be removed in 1.0.0
  * Added route-middleware support (very helpful, see the [docs](http://expressjs.com/guide.html#Route-Middleware))
  * Added _jsonp callback_ setting to enable/disable jsonp autowrapping [Dav Glass]
  * Added callback query check on response.send to autowrap JSON objects for simple webservice implementations [Dav Glass]
  * Added `partial()` support for array-like collections. Closes #434
  * Added support for swappable querystring parsers
  * Added session usage docs. Closes #443
  * Added dynamic helper caching. Closes #439 [suggested by maritz]
  * Added authentication example
  * Added basic Range support to `res.sendfile()` (and `res.download()` etc)
  * Changed; `express(1)` generated app using 2 spaces instead of 4
  * Default env to "development" again [aheckmann]
  * Removed _context_ option is no more, use "scope"
  * Fixed; exposing _./support_ libs to examples so they can run without installs
  * Fixed mvc example

1.0.0rc3 / 2010-09-20
==================

  * Added confirmation for `express(1)` app generation. Closes #391
  * Added extending of flash formatters via `app.flashFormatters`
  * Added flash formatter support. Closes #411
  * Added streaming support to `res.sendfile()` using `sys.pump()` when >= "stream threshold"
  * Added _stream threshold_ setting for `res.sendfile()`
  * Added `res.send()` __HEAD__ support
  * Added `res.clearCookie()`
  * Added `res.cookie()`
  * Added `res.render()` headers option
  * Added `res.redirect()` response bodies
  * Added `res.render()` status option support. Closes #425 [thanks aheckmann]
  * Fixed `res.sendfile()` responding with 403 on malicious path
  * Fixed `res.download()` bug; when an error occurs remove _Content-Disposition_
  * Fixed; mounted apps settings now inherit from parent app [aheckmann]
  * Fixed; stripping Content-Length / Content-Type when 204
  * Fixed `res.send()` 204. Closes #419
  * Fixed multiple _Set-Cookie_ headers via `res.header()`. Closes #402
  * Fixed bug messing with error handlers when `listenFD()` is called instead of `listen()`. [thanks guillermo]


1.0.0rc2 / 2010-08-17
==================

  * Added `app.register()` for template engine mapping. Closes #390
  * Added `res.render()` callback support as second argument (no options)
  * Added callback support to `res.download()`
  * Added callback support for `res.sendfile()`
  * Added support for middleware access via `express.middlewareName()` vs `connect.middlewareName()`
  * Added "partials" setting to docs
  * Added default expresso tests to `express(1)` generated app. Closes #384
  * Fixed `res.sendfile()` error handling, defer via `next()`
  * Fixed `res.render()` callback when a layout is used [thanks guillermo]
  * Fixed; `make install` creating ~/.node_libraries when not present
  * Fixed issue preventing error handlers from being defined anywhere. Closes #387

1.0.0rc / 2010-07-28
==================

  * Added mounted hook. Closes #369
  * Added connect dependency to _package.json_

  * Removed "reload views" setting and support code
    development env never caches, production always caches.

  * Removed _param_ in route callbacks, signature is now
    simply (req, res, next), previously (req, res, params, next).
    Use _req.params_ for path captures, _req.query_ for GET params.

  * Fixed "home" setting
  * Fixed middleware/router precedence issue. Closes #366
  * Fixed; _configure()_ callbacks called immediately. Closes #368

1.0.0beta2 / 2010-07-23
==================

  * Added more examples
  * Added; exporting `Server` constructor
  * Added `Server#helpers()` for view locals
  * Added `Server#dynamicHelpers()` for dynamic view locals. Closes #349
  * Added support for absolute view paths
  * Added; _home_ setting defaults to `Server#route` for mounted apps. Closes #363
  * Added Guillermo Rauch to the contributor list
  * Added support for "as" for non-collection partials. Closes #341
  * Fixed _install.sh_, ensuring _~/.node_libraries_ exists. Closes #362 [thanks jf]
  * Fixed `res.render()` exceptions, now passed to `next()` when no callback is given [thanks guillermo]
  * Fixed instanceof `Array` checks, now `Array.isArray()`
  * Fixed express(1) expansion of public dirs. Closes #348
  * Fixed middleware precedence. Closes #345
  * Fixed view watcher, now async [thanks aheckmann]

1.0.0beta / 2010-07-15
==================

  * Re-write
    - much faster
    - much lighter
    - Check [ExpressJS.com](http://expressjs.com) for migration guide and updated docs

0.14.0 / 2010-06-15
==================

  * Utilize relative requires
  * Added Static bufferSize option [aheckmann]
  * Fixed caching of view and partial subdirectories [aheckmann]
  * Fixed mime.type() comments now that ".ext" is not supported
  * Updated haml submodule
  * Updated class submodule
  * Removed bin/express

0.13.0 / 2010-06-01
==================

  * Added node v0.1.97 compatibility
  * Added support for deleting cookies via Request#cookie('key', null)
  * Updated haml submodule
  * Fixed not-found page, now using charset utf-8
  * Fixed show-exceptions page, now using charset utf-8
  * Fixed view support due to fs.readFile Buffers
  * Changed; mime.type() no longer accepts ".type" due to node extname() changes

0.12.0 / 2010-05-22
==================

  * Added node v0.1.96 compatibility
  * Added view `helpers` export which act as additional local variables
  * Updated haml submodule
  * Changed ETag; removed inode, modified time only
  * Fixed LF to CRLF for setting multiple cookies
  * Fixed cookie compilation; values are now urlencoded
  * Fixed cookies parsing; accepts quoted values and url escaped cookies

0.11.0 / 2010-05-06
==================

  * Added support for layouts using different engines
    - this.render('page.html.haml', { layout: 'super-cool-layout.html.ejs' })
    - this.render('page.html.haml', { layout: 'foo' }) // assumes 'foo.html.haml'
    - this.render('page.html.haml', { layout: false }) // no layout
  * Updated ext submodule
  * Updated haml submodule
  * Fixed EJS partial support by passing along the context. Issue #307

0.10.1 / 2010-05-03
==================

  * Fixed binary uploads.

0.10.0 / 2010-04-30
==================

  * Added charset support via Request#charset (automatically assigned to 'UTF-8' when respond()'s
    encoding is set to 'utf8' or 'utf-8').
  * Added "encoding" option to Request#render(). Closes #299
  * Added "dump exceptions" setting, which is enabled by default.
  * Added simple ejs template engine support
  * Added error response support for text/plain, application/json. Closes #297
  * Added callback function param to Request#error()
  * Added Request#sendHead()
  * Added Request#stream()
  * Added support for Request#respond(304, null) for empty response bodies
  * Added ETag support to Request#sendfile()
  * Added options to Request#sendfile(), passed to fs.createReadStream()
  * Added filename arg to Request#download()
  * Performance enhanced due to pre-reversing plugins so that plugins.reverse() is not called on each request
  * Performance enhanced by preventing several calls to toLowerCase() in Router#match()
  * Changed; Request#sendfile() now streams
  * Changed; Renamed Request#halt() to Request#respond(). Closes #289
  * Changed; Using sys.inspect() instead of JSON.encode() for error output
  * Changed; run() returns the http.Server instance. Closes #298
  * Changed; Defaulting Server#host to null (INADDR_ANY)
  * Changed; Logger "common" format scale of 0.4f
  * Removed Logger "request" format
  * Fixed; Catching ENOENT in view caching, preventing error when "views/partials" is not found
  * Fixed several issues with http client
  * Fixed Logger Content-Length output
  * Fixed bug preventing Opera from retaining the generated session id. Closes #292

0.9.0 / 2010-04-14
==================

  * Added DSL level error() route support
  * Added DSL level notFound() route support
  * Added Request#error()
  * Added Request#notFound()
  * Added Request#render() callback function. Closes #258
  * Added "max upload size" setting
  * Added "magic" variables to collection partials (\_\_index\_\_, \_\_length\_\_, \_\_isFirst\_\_, \_\_isLast\_\_). Closes #254
  * Added [haml.js](http://github.com/visionmedia/haml.js) submodule; removed haml-js
  * Added callback function support to Request#halt() as 3rd/4th arg
  * Added preprocessing of route param wildcards using param(). Closes #251
  * Added view partial support (with collections etc.)
  * Fixed bug preventing falsey params (such as ?page=0). Closes #286
  * Fixed setting of multiple cookies. Closes #199
  * Changed; view naming convention is now NAME.TYPE.ENGINE (for example page.html.haml)
  * Changed; session cookie is now httpOnly
  * Changed; Request is no longer global
  * Changed; Event is no longer global
  * Changed; "sys" module is no longer global
  * Changed; moved Request#download to Static plugin where it belongs
  * Changed; Request instance created before body parsing. Closes #262
  * Changed; Pre-caching views in memory when "cache view contents" is enabled. Closes #253
  * Changed; Pre-caching view partials in memory when "cache view partials" is enabled
  * Updated support to node --version 0.1.90
  * Updated dependencies
  * Removed set("session cookie") in favour of use(Session, { cookie: { ... }})
  * Removed utils.mixin(); use Object#mergeDeep()

0.8.0 / 2010-03-19
==================

  * Added coffeescript example app. Closes #242
  * Changed; cache api now async friendly. Closes #240
  * Removed deprecated 'express/static' support. Use 'express/plugins/static'

0.7.6 / 2010-03-19
==================

  * Added Request#isXHR. Closes #229
  * Added `make install` (for the executable)
  * Added `express` executable for setting up simple app templates
  * Added "GET /public/*" to Static plugin, defaulting to <root>/public
  * Added Static plugin
  * Fixed; Request#render() only calls cache.get() once
  * Fixed; Namespacing View caches with "view:"
  * Fixed; Namespacing Static caches with "static:"
  * Fixed; Both example apps now use the Static plugin
  * Fixed set("views"). Closes #239
  * Fixed missing space for combined log format
  * Deprecated Request#sendfile() and 'express/static'
  * Removed Server#running

0.7.5 / 2010-03-16
==================

  * Added Request#flash() support without args, now returns all flashes
  * Updated ext submodule

0.7.4 / 2010-03-16
==================

  * Fixed session reaper
  * Changed; class.js replacing js-oo Class implementation (quite a bit faster, no browser cruft)

0.7.3 / 2010-03-16
==================

  * Added package.json
  * Fixed requiring of haml / sass due to kiwi removal

0.7.2 / 2010-03-16
==================

  * Fixed GIT submodules (HAH!)

0.7.1 / 2010-03-16
==================

  * Changed; Express now using submodules again until a PM is adopted
  * Changed; chat example using millisecond conversions from ext

0.7.0 / 2010-03-15
==================

  * Added Request#pass() support (finds the next matching route, or the given path)
  * Added Logger plugin (default "common" format replaces CommonLogger)
  * Removed Profiler plugin
  * Removed CommonLogger plugin

0.6.0 / 2010-03-11
==================

  * Added seed.yml for kiwi package management support
  * Added HTTP client query string support when method is GET. Closes #205

  * Added support for arbitrary view engines.
    For example "foo.engine.html" will now require('engine'),
    the exports from this module are cached after the first require().

  * Added async plugin support

  * Removed usage of RESTful route funcs as http client
    get() etc, use http.get() and friends

  * Removed custom exceptions

0.5.0 / 2010-03-10
==================

  * Added ext dependency (library of js extensions)
  * Removed extname() / basename() utils. Use path module
  * Removed toArray() util. Use arguments.values
  * Removed escapeRegexp() util. Use RegExp.escape()
  * Removed process.mixin() dependency. Use utils.mixin()
  * Removed Collection
  * Removed ElementCollection
  * Shameless self promotion of ebook "Advanced JavaScript" (http://dev-mag.com)  ;)

0.4.0 / 2010-02-11
==================

  * Added flash() example to sample upload app
  * Added high level restful http client module (express/http)
  * Changed; RESTful route functions double as HTTP clients. Closes #69
  * Changed; throwing error when routes are added at runtime
  * Changed; defaulting render() context to the current Request. Closes #197
  * Updated haml submodule

0.3.0 / 2010-02-11
==================

  * Updated haml / sass submodules. Closes #200
  * Added flash message support. Closes #64
  * Added accepts() now allows multiple args. fixes #117
  * Added support for plugins to halt. Closes #189
  * Added alternate layout support. Closes #119
  * Removed Route#run(). Closes #188
  * Fixed broken specs due to use(Cookie) missing

0.2.1 / 2010-02-05
==================

  * Added "plot" format option for Profiler (for gnuplot processing)
  * Added request number to Profiler plugin
  * Fixed binary encoding for multipart file uploads, was previously defaulting to UTF8
  * Fixed issue with routes not firing when not files are present. Closes #184
  * Fixed process.Promise -> events.Promise

0.2.0 / 2010-02-03
==================

  * Added parseParam() support for name[] etc. (allows for file inputs with "multiple" attr) Closes #180
  * Added Both Cache and Session option "reapInterval" may be "reapEvery". Closes #174
  * Added expiration support to cache api with reaper. Closes #133
  * Added cache Store.Memory#reap()
  * Added Cache; cache api now uses first class Cache instances
  * Added abstract session Store. Closes #172
  * Changed; cache Memory.Store#get() utilizing Collection
  * Renamed MemoryStore -> Store.Memory
  * Fixed use() of the same plugin several time will always use latest options. Closes #176

0.1.0 / 2010-02-03
==================

  * Changed; Hooks (before / after) pass request as arg as well as evaluated in their context
  * Updated node support to 0.1.27 Closes #169
  * Updated dirname(__filename) -> __dirname
  * Updated libxmljs support to v0.2.0
  * Added session support with memory store / reaping
  * Added quick uid() helper
  * Added multi-part upload support
  * Added Sass.js support / submodule
  * Added production env caching view contents and static files
  * Added static file caching. Closes #136
  * Added cache plugin with memory stores
  * Added support to StaticFile so that it works with non-textual files.
  * Removed dirname() helper
  * Removed several globals (now their modules must be required)

0.0.2 / 2010-01-10
==================

  * Added view benchmarks; currently haml vs ejs
  * Added Request#attachment() specs. Closes #116
  * Added use of node's parseQuery() util. Closes #123
  * Added `make init` for submodules
  * Updated Haml
  * Updated sample chat app to show messages on load
  * Updated libxmljs parseString -> parseHtmlString
  * Fixed `make init` to work with older versions of git
  * Fixed specs can now run independent specs for those who can't build deps. Closes #127
  * Fixed issues introduced by the node url module changes. Closes 126.
  * Fixed two assertions failing due to Collection#keys() returning strings
  * Fixed faulty Collection#toArray() spec due to keys() returning strings
  * Fixed `make test` now builds libxmljs.node before testing

0.0.1 / 2010-01-03
==================

  * Initial release


---

[![Express Logo](https://i.cloudup.com/zfY6lL7eFa-3000x3000.png)](http://expressjs.com/)

**Fast, unopinionated, minimalist web framework for [Node.js](http://nodejs.org).**

**This project has a [Code of Conduct][].**

## Table of contents

* [Installation](#Installation)
* [Features](#Features)
* [Docs & Community](#docs--community)
* [Quick Start](#Quick-Start)
* [Running Tests](#Running-Tests)
* [Philosophy](#Philosophy)
* [Examples](#Examples)
* [Contributing to Express](#Contributing)
* [TC (Technical Committee)](#tc-technical-committee)
* [Triagers](#triagers)
* [License](#license)


[![NPM Version][npm-version-image]][npm-url]
[![NPM Install Size][npm-install-size-image]][npm-install-size-url]
[![NPM Downloads][npm-downloads-image]][npm-downloads-url]
[![OpenSSF Scorecard Badge][ossf-scorecard-badge]][ossf-scorecard-visualizer]


```js
const express = require('express')
const app = express()

app.get('/', function (req, res) {
  res.send('Hello World')
})

app.listen(3000)
```

## Installation

This is a [Node.js](https://nodejs.org/en/) module available through the
[npm registry](https://www.npmjs.com/).

Before installing, [download and install Node.js](https://nodejs.org/en/download/).
Node.js 0.10 or higher is required.

If this is a brand new project, make sure to create a `package.json` first with
the [`npm init` command](https://docs.npmjs.com/creating-a-package-json-file).

Installation is done using the
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):

```console
$ npm install express
```

Follow [our installing guide](http://expressjs.com/en/starter/installing.html)
for more information.

## Features

  * Robust routing
  * Focus on high performance
  * Super-high test coverage
  * HTTP helpers (redirection, caching, etc)
  * View system supporting 14+ template engines
  * Content negotiation
  * Executable for generating applications quickly

## Docs & Community

  * [Website and Documentation](http://expressjs.com/) - [[website repo](https://github.com/expressjs/expressjs.com)]
  * [#express](https://web.libera.chat/#express) on [Libera Chat](https://libera.chat) IRC
  * [GitHub Organization](https://github.com/expressjs) for Official Middleware & Modules
  * Visit the [Wiki](https://github.com/expressjs/express/wiki)
  * [Google Group](https://groups.google.com/group/express-js) for discussion
  * [Gitter](https://gitter.im/expressjs/express) for support and discussion

**PROTIP** Be sure to read [Migrating from 3.x to 4.x](https://github.com/expressjs/express/wiki/Migrating-from-3.x-to-4.x) as well as [New features in 4.x](https://github.com/expressjs/express/wiki/New-features-in-4.x).

## Quick Start

  The quickest way to get started with express is to utilize the executable [`express(1)`](https://github.com/expressjs/generator) to generate an application as shown below:

  Install the executable. The executable's major version will match Express's:

```console
$ npm install -g express-generator@4
```

  Create the app:

```console
$ express /tmp/foo && cd /tmp/foo
```

  Install dependencies:

```console
$ npm install
```

  Start the server:

```console
$ npm start
```

  View the website at: http://localhost:3000

## Philosophy

  The Express philosophy is to provide small, robust tooling for HTTP servers, making
  it a great solution for single page applications, websites, hybrids, or public
  HTTP APIs.

  Express does not force you to use any specific ORM or template engine. With support for over
  14 template engines via [Consolidate.js](https://github.com/tj/consolidate.js),
  you can quickly craft your perfect framework.

## Examples

  To view the examples, clone the Express repo and install the dependencies:

```console
$ git clone https://github.com/expressjs/express.git --depth 1
$ cd express
$ npm install
```

  Then run whichever example you want:

```console
$ node examples/content-negotiation
```

## Contributing

  [![Linux Build][github-actions-ci-image]][github-actions-ci-url]
  [![Windows Build][appveyor-image]][appveyor-url]
  [![Test Coverage][coveralls-image]][coveralls-url]

The Express.js project welcomes all constructive contributions. Contributions take many forms,
from code for bug fixes and enhancements, to additions and fixes to documentation, additional
tests, triaging incoming pull requests and issues, and more!

See the [Contributing Guide](Contributing.md) for more technical details on contributing.

### Security Issues

If you discover a security vulnerability in Express, please see [Security Policies and Procedures](Security.md).

### Running Tests

To run the test suite, first install the dependencies, then run `npm test`:

```console
$ npm install
$ npm test
```

## People

The original author of Express is [TJ Holowaychuk](https://github.com/tj)

[List of all contributors](https://github.com/expressjs/express/graphs/contributors)

### TC (Technical Committee)

* [UlisesGascon](https://github.com/UlisesGascon) - **Ulises Gascón** (he/him)
* [jonchurch](https://github.com/jonchurch) - **Jon Church**
* [wesleytodd](https://github.com/wesleytodd) - **Wes Todd**
* [LinusU](https://github.com/LinusU) - **Linus Unnebäck**
* [blakeembrey](https://github.com/blakeembrey) - **Blake Embrey**
* [sheplu](https://github.com/sheplu) - **Jean Burellier**
* [crandmck](https://github.com/crandmck) - **Rand McKinney**
* [ctcpip](https://github.com/ctcpip) - **Chris de Almeida**

<details>
<summary>TC emeriti members</summary>

#### TC emeriti members

  * [dougwilson](https://github.com/dougwilson) - **Douglas Wilson**
  * [hacksparrow](https://github.com/hacksparrow) - **Hage Yaapa**
  * [jonathanong](https://github.com/jonathanong) - **jongleberry**
  * [niftylettuce](https://github.com/niftylettuce) - **niftylettuce**
  * [troygoode](https://github.com/troygoode) - **Troy Goode**
</details>


### Triagers

* [aravindvnair99](https://github.com/aravindvnair99) - **Aravind Nair**
* [carpasse](https://github.com/carpasse) - **Carlos Serrano**
* [CBID2](https://github.com/CBID2) - **Christine Belzie**
* [enyoghasim](https://github.com/enyoghasim) - **David Enyoghasim**
* [UlisesGascon](https://github.com/UlisesGascon) - **Ulises Gascón** (he/him)
* [mertcanaltin](https://github.com/mertcanaltin) - **Mert Can Altin**
* [0ss](https://github.com/0ss) - **Salah**
* [import-brain](https://github.com/import-brain) - **Eric Cheng** (he/him)
* [3imed-jaberi](https://github.com/3imed-jaberi) - **Imed Jaberi**
* [dakshkhetan](https://github.com/dakshkhetan) - **Daksh Khetan** (he/him)
* [lucasraziel](https://github.com/lucasraziel) - **Lucas Soares Do Rego**
* [IamLizu](https://github.com/IamLizu) - **S M Mahmudul Hasan** (he/him)
* [Sushmeet](https://github.com/Sushmeet) - **Sushmeet Sunger**

<details>
<summary>Triagers emeriti members</summary>

#### Emeritus Triagers

  * [AuggieH](https://github.com/AuggieH) - **Auggie Hudak**
  * [G-Rath](https://github.com/G-Rath) - **Gareth Jones**
  * [MohammadXroid](https://github.com/MohammadXroid) - **Mohammad Ayashi**
  * [NawafSwe](https://github.com/NawafSwe) - **Nawaf Alsharqi**
  * [NotMoni](https://github.com/NotMoni) - **Moni**
  * [VigneshMurugan](https://github.com/VigneshMurugan) - **Vignesh Murugan**
  * [davidmashe](https://github.com/davidmashe) - **David Ashe**
  * [digitaIfabric](https://github.com/digitaIfabric) - **David**
  * [e-l-i-s-e](https://github.com/e-l-i-s-e) - **Elise Bonner**
  * [fed135](https://github.com/fed135) - **Frederic Charette**
  * [firmanJS](https://github.com/firmanJS) - **Firman Abdul Hakim**
  * [getspooky](https://github.com/getspooky) - **Yasser Ameur**
  * [ghinks](https://github.com/ghinks) - **Glenn**
  * [ghousemohamed](https://github.com/ghousemohamed) - **Ghouse Mohamed**
  * [gireeshpunathil](https://github.com/gireeshpunathil) - **Gireesh Punathil**
  * [jake32321](https://github.com/jake32321) - **Jake Reed**
  * [jonchurch](https://github.com/jonchurch) - **Jon Church**
  * [lekanikotun](https://github.com/lekanikotun) - **Troy Goode**
  * [marsonya](https://github.com/marsonya) - **Lekan Ikotun**
  * [mastermatt](https://github.com/mastermatt) - **Matt R. Wilson**
  * [maxakuru](https://github.com/maxakuru) - **Max Edell**
  * [mlrawlings](https://github.com/mlrawlings) - **Michael Rawlings**
  * [rodion-arr](https://github.com/rodion-arr) - **Rodion Abdurakhimov**
  * [sheplu](https://github.com/sheplu) - **Jean Burellier**
  * [tarunyadav1](https://github.com/tarunyadav1) - **Tarun yadav**
  * [tunniclm](https://github.com/tunniclm) - **Mike Tunnicliffe**
</details>


## License

  [MIT](LICENSE)

[appveyor-image]: https://badgen.net/appveyor/ci/dougwilson/express/master?label=windows
[appveyor-url]: https://ci.appveyor.com/project/dougwilson/express
[coveralls-image]: https://badgen.net/coveralls/c/github/expressjs/express/master
[coveralls-url]: https://coveralls.io/r/expressjs/express?branch=master
[github-actions-ci-image]: https://badgen.net/github/checks/expressjs/express/master?label=linux
[github-actions-ci-url]: https://github.com/expressjs/express/actions/workflows/ci.yml
[npm-downloads-image]: https://badgen.net/npm/dm/express
[npm-downloads-url]: https://npmcharts.com/compare/express?minimal=true
[npm-install-size-image]: https://badgen.net/packagephobia/install/express
[npm-install-size-url]: https://packagephobia.com/result?p=express
[npm-url]: https://npmjs.org/package/express
[npm-version-image]: https://badgen.net/npm/v/express
[ossf-scorecard-badge]: https://api.scorecard.dev/projects/github.com/expressjs/express/badge
[ossf-scorecard-visualizer]: https://ossf.github.io/scorecard-visualizer/#/projects/github.com/expressjs/express
[Code of Conduct]: https://github.com/expressjs/express/blob/master/Code-Of-Conduct.md


---

0.5.4 / 2021-12-10
==================

  * deps: safe-buffer@5.2.1

0.5.3 / 2018-12-17
==================

  * Use `safe-buffer` for improved Buffer API

0.5.2 / 2016-12-08
==================

  * Fix `parse` to accept any linear whitespace character

0.5.1 / 2016-01-17
==================

  * perf: enable strict mode

0.5.0 / 2014-10-11
==================

  * Add `parse` function

0.4.0 / 2014-09-21
==================

  * Expand non-Unicode `filename` to the full ISO-8859-1 charset

0.3.0 / 2014-09-20
==================

  * Add `fallback` option
  * Add `type` option

0.2.0 / 2014-09-19
==================

  * Reduce ambiguity of file names with hex escape in buggy browsers

0.1.2 / 2014-09-19
==================

  * Fix periodic invalid Unicode filename header

0.1.1 / 2014-09-19
==================

  * Fix invalid characters appearing in `filename*` parameter

0.1.0 / 2014-09-18
==================

  * Make the `filename` argument optional

0.0.0 / 2014-09-18
==================

  * Initial release


---

# content-disposition

[![NPM Version][npm-image]][npm-url]
[![NPM Downloads][downloads-image]][downloads-url]
[![Node.js Version][node-version-image]][node-version-url]
[![Build Status][github-actions-ci-image]][github-actions-ci-url]
[![Test Coverage][coveralls-image]][coveralls-url]

Create and parse HTTP `Content-Disposition` header

## Installation

```sh
$ npm install content-disposition
```

## API

```js
var contentDisposition = require('content-disposition')
```

### contentDisposition(filename, options)

Create an attachment `Content-Disposition` header value using the given file name,
if supplied. The `filename` is optional and if no file name is desired, but you
want to specify `options`, set `filename` to `undefined`.

```js
res.setHeader('Content-Disposition', contentDisposition('∫ maths.pdf'))
```

**note** HTTP headers are of the ISO-8859-1 character set. If you are writing this
header through a means different from `setHeader` in Node.js, you'll want to specify
the `'binary'` encoding in Node.js.

#### Options

`contentDisposition` accepts these properties in the options object.

##### fallback

If the `filename` option is outside ISO-8859-1, then the file name is actually
stored in a supplemental field for clients that support Unicode file names and
a ISO-8859-1 version of the file name is automatically generated.

This specifies the ISO-8859-1 file name to override the automatic generation or
disables the generation all together, defaults to `true`.

  - A string will specify the ISO-8859-1 file name to use in place of automatic
    generation.
  - `false` will disable including a ISO-8859-1 file name and only include the
    Unicode version (unless the file name is already ISO-8859-1).
  - `true` will enable automatic generation if the file name is outside ISO-8859-1.

If the `filename` option is ISO-8859-1 and this option is specified and has a
different value, then the `filename` option is encoded in the extended field
and this set as the fallback field, even though they are both ISO-8859-1.

##### type

Specifies the disposition type, defaults to `"attachment"`. This can also be
`"inline"`, or any other value (all values except inline are treated like
`attachment`, but can convey additional information if both parties agree to
it). The type is normalized to lower-case.

### contentDisposition.parse(string)

```js
var disposition = contentDisposition.parse('attachment; filename="EURO rates.txt"; filename*=UTF-8\'\'%e2%82%ac%20rates.txt')
```

Parse a `Content-Disposition` header string. This automatically handles extended
("Unicode") parameters by decoding them and providing them under the standard
parameter name. This will return an object with the following properties (examples
are shown for the string `'attachment; filename="EURO rates.txt"; filename*=UTF-8\'\'%e2%82%ac%20rates.txt'`):

 - `type`: The disposition type (always lower case). Example: `'attachment'`

 - `parameters`: An object of the parameters in the disposition (name of parameter
   always lower case and extended versions replace non-extended versions). Example:
   `{filename: "€ rates.txt"}`

## Examples

### Send a file for download

```js
var contentDisposition = require('content-disposition')
var destroy = require('destroy')
var fs = require('fs')
var http = require('http')
var onFinished = require('on-finished')

var filePath = '/path/to/public/plans.pdf'

http.createServer(function onRequest (req, res) {
  // set headers
  res.setHeader('Content-Type', 'application/pdf')
  res.setHeader('Content-Disposition', contentDisposition(filePath))

  // send file
  var stream = fs.createReadStream(filePath)
  stream.pipe(res)
  onFinished(res, function () {
    destroy(stream)
  })
})
```

## Testing

```sh
$ npm test
```

## References

- [RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1][rfc-2616]
- [RFC 5987: Character Set and Language Encoding for Hypertext Transfer Protocol (HTTP) Header Field Parameters][rfc-5987]
- [RFC 6266: Use of the Content-Disposition Header Field in the Hypertext Transfer Protocol (HTTP)][rfc-6266]
- [Test Cases for HTTP Content-Disposition header field (RFC 6266) and the Encodings defined in RFCs 2047, 2231 and 5987][tc-2231]

[rfc-2616]: https://tools.ietf.org/html/rfc2616
[rfc-5987]: https://tools.ietf.org/html/rfc5987
[rfc-6266]: https://tools.ietf.org/html/rfc6266
[tc-2231]: http://greenbytes.de/tech/tc2231/

## License

[MIT](LICENSE)

[npm-image]: https://img.shields.io/npm/v/content-disposition.svg
[npm-url]: https://npmjs.org/package/content-disposition
[node-version-image]: https://img.shields.io/node/v/content-disposition.svg
[node-version-url]: https://nodejs.org/en/download
[coveralls-image]: https://img.shields.io/coveralls/jshttp/content-disposition.svg
[coveralls-url]: https://coveralls.io/r/jshttp/content-disposition?branch=master
[downloads-image]: https://img.shields.io/npm/dm/content-disposition.svg
[downloads-url]: https://npmjs.org/package/content-disposition
[github-actions-ci-image]: https://img.shields.io/github/workflow/status/jshttp/content-disposition/ci/master?label=ci
[github-actions-ci-url]: https://github.com/jshttp/content-disposition?query=workflow%3Aci


---


2.6.9 / 2017-09-22
==================

  * remove ReDoS regexp in %o formatter (#504)

2.6.8 / 2017-05-18
==================

  * Fix: Check for undefined on browser globals (#462, @marbemac)

2.6.7 / 2017-05-16
==================

  * Fix: Update ms to 2.0.0 to fix regular expression denial of service vulnerability (#458, @hubdotcom)
  * Fix: Inline extend function in node implementation (#452, @dougwilson)
  * Docs: Fix typo (#455, @msasad)

2.6.5 / 2017-04-27
==================
  
  * Fix: null reference check on window.documentElement.style.WebkitAppearance (#447, @thebigredgeek)
  * Misc: clean up browser reference checks (#447, @thebigredgeek)
  * Misc: add npm-debug.log to .gitignore (@thebigredgeek)


2.6.4 / 2017-04-20
==================

  * Fix: bug that would occure if process.env.DEBUG is a non-string value. (#444, @LucianBuzzo)
  * Chore: ignore bower.json in npm installations. (#437, @joaovieira)
  * Misc: update "ms" to v0.7.3 (@tootallnate)

2.6.3 / 2017-03-13
==================

  * Fix: Electron reference to `process.env.DEBUG` (#431, @paulcbetts)
  * Docs: Changelog fix (@thebigredgeek)

2.6.2 / 2017-03-10
==================

  * Fix: DEBUG_MAX_ARRAY_LENGTH (#420, @slavaGanzin)
  * Docs: Add backers and sponsors from Open Collective (#422, @piamancini)
  * Docs: Add Slackin invite badge (@tootallnate)

2.6.1 / 2017-02-10
==================

  * Fix: Module's `export default` syntax fix for IE8 `Expected identifier` error
  * Fix: Whitelist DEBUG_FD for values 1 and 2 only (#415, @pi0)
  * Fix: IE8 "Expected identifier" error (#414, @vgoma)
  * Fix: Namespaces would not disable once enabled (#409, @musikov)

2.6.0 / 2016-12-28
==================

  * Fix: added better null pointer checks for browser useColors (@thebigredgeek)
  * Improvement: removed explicit `window.debug` export (#404, @tootallnate)
  * Improvement: deprecated `DEBUG_FD` environment variable (#405, @tootallnate)

2.5.2 / 2016-12-25
==================

  * Fix: reference error on window within webworkers (#393, @KlausTrainer)
  * Docs: fixed README typo (#391, @lurch)
  * Docs: added notice about v3 api discussion (@thebigredgeek)

2.5.1 / 2016-12-20
==================

  * Fix: babel-core compatibility

2.5.0 / 2016-12-20
==================

  * Fix: wrong reference in bower file (@thebigredgeek)
  * Fix: webworker compatibility (@thebigredgeek)
  * Fix: output formatting issue (#388, @kribblo)
  * Fix: babel-loader compatibility (#383, @escwald)
  * Misc: removed built asset from repo and publications (@thebigredgeek)
  * Misc: moved source files to /src (#378, @yamikuronue)
  * Test: added karma integration and replaced babel with browserify for browser tests (#378, @yamikuronue)
  * Test: coveralls integration (#378, @yamikuronue)
  * Docs: simplified language in the opening paragraph (#373, @yamikuronue)

2.4.5 / 2016-12-17
==================

  * Fix: `navigator` undefined in Rhino (#376, @jochenberger)
  * Fix: custom log function (#379, @hsiliev)
  * Improvement: bit of cleanup + linting fixes (@thebigredgeek)
  * Improvement: rm non-maintainted `dist/` dir (#375, @freewil)
  * Docs: simplified language in the opening paragraph. (#373, @yamikuronue)

2.4.4 / 2016-12-14
==================

  * Fix: work around debug being loaded in preload scripts for electron (#368, @paulcbetts)

2.4.3 / 2016-12-14
==================

  * Fix: navigation.userAgent error for react native (#364, @escwald)

2.4.2 / 2016-12-14
==================

  * Fix: browser colors (#367, @tootallnate)
  * Misc: travis ci integration (@thebigredgeek)
  * Misc: added linting and testing boilerplate with sanity check (@thebigredgeek)

2.4.1 / 2016-12-13
==================

  * Fix: typo that broke the package (#356)

2.4.0 / 2016-12-13
==================

  * Fix: bower.json references unbuilt src entry point (#342, @justmatt)
  * Fix: revert "handle regex special characters" (@tootallnate)
  * Feature: configurable util.inspect()`options for NodeJS (#327, @tootallnate)
  * Feature: %O`(big O) pretty-prints objects (#322, @tootallnate)
  * Improvement: allow colors in workers (#335, @botverse)
  * Improvement: use same color for same namespace. (#338, @lchenay)

2.3.3 / 2016-11-09
==================

  * Fix: Catch `JSON.stringify()` errors (#195, Jovan Alleyne)
  * Fix: Returning `localStorage` saved values (#331, Levi Thomason)
  * Improvement: Don't create an empty object when no `process` (Nathan Rajlich)

2.3.2 / 2016-11-09
==================

  * Fix: be super-safe in index.js as well (@TooTallNate)
  * Fix: should check whether process exists (Tom Newby)

2.3.1 / 2016-11-09
==================

  * Fix: Added electron compatibility (#324, @paulcbetts)
  * Improvement: Added performance optimizations (@tootallnate)
  * Readme: Corrected PowerShell environment variable example (#252, @gimre)
  * Misc: Removed yarn lock file from source control (#321, @fengmk2)

2.3.0 / 2016-11-07
==================

  * Fix: Consistent placement of ms diff at end of output (#215, @gorangajic)
  * Fix: Escaping of regex special characters in namespace strings (#250, @zacronos)
  * Fix: Fixed bug causing crash on react-native (#282, @vkarpov15)
  * Feature: Enabled ES6+ compatible import via default export (#212 @bucaran)
  * Feature: Added %O formatter to reflect Chrome's console.log capability (#279, @oncletom)
  * Package: Update "ms" to 0.7.2 (#315, @DevSide)
  * Package: removed superfluous version property from bower.json (#207 @kkirsche)
  * Readme: fix USE_COLORS to DEBUG_COLORS
  * Readme: Doc fixes for format string sugar (#269, @mlucool)
  * Readme: Updated docs for DEBUG_FD and DEBUG_COLORS environment variables (#232, @mattlyons0)
  * Readme: doc fixes for PowerShell (#271 #243, @exoticknight @unreadable)
  * Readme: better docs for browser support (#224, @matthewmueller)
  * Tooling: Added yarn integration for development (#317, @thebigredgeek)
  * Misc: Renamed History.md to CHANGELOG.md (@thebigredgeek)
  * Misc: Added license file (#226 #274, @CantemoInternal @sdaitzman)
  * Misc: Updated contributors (@thebigredgeek)

2.2.0 / 2015-05-09
==================

  * package: update "ms" to v0.7.1 (#202, @dougwilson)
  * README: add logging to file example (#193, @DanielOchoa)
  * README: fixed a typo (#191, @amir-s)
  * browser: expose `storage` (#190, @stephenmathieson)
  * Makefile: add a `distclean` target (#189, @stephenmathieson)

2.1.3 / 2015-03-13
==================

  * Updated stdout/stderr example (#186)
  * Updated example/stdout.js to match debug current behaviour
  * Renamed example/stderr.js to stdout.js
  * Update Readme.md (#184)
  * replace high intensity foreground color for bold (#182, #183)

2.1.2 / 2015-03-01
==================

  * dist: recompile
  * update "ms" to v0.7.0
  * package: update "browserify" to v9.0.3
  * component: fix "ms.js" repo location
  * changed bower package name
  * updated documentation about using debug in a browser
  * fix: security error on safari (#167, #168, @yields)

2.1.1 / 2014-12-29
==================

  * browser: use `typeof` to check for `console` existence
  * browser: check for `console.log` truthiness (fix IE 8/9)
  * browser: add support for Chrome apps
  * Readme: added Windows usage remarks
  * Add `bower.json` to properly support bower install

2.1.0 / 2014-10-15
==================

  * node: implement `DEBUG_FD` env variable support
  * package: update "browserify" to v6.1.0
  * package: add "license" field to package.json (#135, @panuhorsmalahti)

2.0.0 / 2014-09-01
==================

  * package: update "browserify" to v5.11.0
  * node: use stderr rather than stdout for logging (#29, @stephenmathieson)

1.0.4 / 2014-07-15
==================

  * dist: recompile
  * example: remove `console.info()` log usage
  * example: add "Content-Type" UTF-8 header to browser example
  * browser: place %c marker after the space character
  * browser: reset the "content" color via `color: inherit`
  * browser: add colors support for Firefox >= v31
  * debug: prefer an instance `log()` function over the global one (#119)
  * Readme: update documentation about styled console logs for FF v31 (#116, @wryk)

1.0.3 / 2014-07-09
==================

  * Add support for multiple wildcards in namespaces (#122, @seegno)
  * browser: fix lint

1.0.2 / 2014-06-10
==================

  * browser: update color palette (#113, @gscottolson)
  * common: make console logging function configurable (#108, @timoxley)
  * node: fix %o colors on old node <= 0.8.x
  * Makefile: find node path using shell/which (#109, @timoxley)

1.0.1 / 2014-06-06
==================

  * browser: use `removeItem()` to clear localStorage
  * browser, node: don't set DEBUG if namespaces is undefined (#107, @leedm777)
  * package: add "contributors" section
  * node: fix comment typo
  * README: list authors

1.0.0 / 2014-06-04
==================

  * make ms diff be global, not be scope
  * debug: ignore empty strings in enable()
  * node: make DEBUG_COLORS able to disable coloring
  * *: export the `colors` array
  * npmignore: don't publish the `dist` dir
  * Makefile: refactor to use browserify
  * package: add "browserify" as a dev dependency
  * Readme: add Web Inspector Colors section
  * node: reset terminal color for the debug content
  * node: map "%o" to `util.inspect()`
  * browser: map "%j" to `JSON.stringify()`
  * debug: add custom "formatters"
  * debug: use "ms" module for humanizing the diff
  * Readme: add "bash" syntax highlighting
  * browser: add Firebug color support
  * browser: add colors for WebKit browsers
  * node: apply log to `console`
  * rewrite: abstract common logic for Node & browsers
  * add .jshintrc file

0.8.1 / 2014-04-14
==================

  * package: re-add the "component" section

0.8.0 / 2014-03-30
==================

  * add `enable()` method for nodejs. Closes #27
  * change from stderr to stdout
  * remove unnecessary index.js file

0.7.4 / 2013-11-13
==================

  * remove "browserify" key from package.json (fixes something in browserify)

0.7.3 / 2013-10-30
==================

  * fix: catch localStorage security error when cookies are blocked (Chrome)
  * add debug(err) support. Closes #46
  * add .browser prop to package.json. Closes #42

0.7.2 / 2013-02-06
==================

  * fix package.json
  * fix: Mobile Safari (private mode) is broken with debug
  * fix: Use unicode to send escape character to shell instead of octal to work with strict mode javascript

0.7.1 / 2013-02-05
==================

  * add repository URL to package.json
  * add DEBUG_COLORED to force colored output
  * add browserify support
  * fix component. Closes #24

0.7.0 / 2012-05-04
==================

  * Added .component to package.json
  * Added debug.component.js build

0.6.0 / 2012-03-16
==================

  * Added support for "-" prefix in DEBUG [Vinay Pulim]
  * Added `.enabled` flag to the node version [TooTallNate]

0.5.0 / 2012-02-02
==================

  * Added: humanize diffs. Closes #8
  * Added `debug.disable()` to the CS variant
  * Removed padding. Closes #10
  * Fixed: persist client-side variant again. Closes #9

0.4.0 / 2012-02-01
==================

  * Added browser variant support for older browsers [TooTallNate]
  * Added `debug.enable('project:*')` to browser variant [TooTallNate]
  * Added padding to diff (moved it to the right)

0.3.0 / 2012-01-26
==================

  * Added millisecond diff when isatty, otherwise UTC string

0.2.0 / 2012-01-22
==================

  * Added wildcard support

0.1.0 / 2011-12-02
==================

  * Added: remove colors unless stderr isatty [TooTallNate]

0.0.1 / 2010-01-03
==================

  * Initial release


---

# debug
[![Build Status](https://travis-ci.org/visionmedia/debug.svg?branch=master)](https://travis-ci.org/visionmedia/debug)  [![Coverage Status](https://coveralls.io/repos/github/visionmedia/debug/badge.svg?branch=master)](https://coveralls.io/github/visionmedia/debug?branch=master)  [![Slack](https://visionmedia-community-slackin.now.sh/badge.svg)](https://visionmedia-community-slackin.now.sh/) [![OpenCollective](https://opencollective.com/debug/backers/badge.svg)](#backers) 
[![OpenCollective](https://opencollective.com/debug/sponsors/badge.svg)](#sponsors)



A tiny node.js debugging utility modelled after node core's debugging technique.

**Discussion around the V3 API is under way [here](https://github.com/visionmedia/debug/issues/370)**

## Installation

```bash
$ npm install debug
```

## Usage

`debug` exposes a function; simply pass this function the name of your module, and it will return a decorated version of `console.error` for you to pass debug statements to. This will allow you to toggle the debug output for different parts of your module as well as the module as a whole.

Example _app.js_:

```js
var debug = require('debug')('http')
  , http = require('http')
  , name = 'My App';

// fake app

debug('booting %s', name);

http.createServer(function(req, res){
  debug(req.method + ' ' + req.url);
  res.end('hello\n');
}).listen(3000, function(){
  debug('listening');
});

// fake worker of some kind

require('./worker');
```

Example _worker.js_:

```js
var debug = require('debug')('worker');

setInterval(function(){
  debug('doing some work');
}, 1000);
```

 The __DEBUG__ environment variable is then used to enable these based on space or comma-delimited names. Here are some examples:

  ![debug http and worker](http://f.cl.ly/items/18471z1H402O24072r1J/Screenshot.png)

  ![debug worker](http://f.cl.ly/items/1X413v1a3M0d3C2c1E0i/Screenshot.png)

#### Windows note

 On Windows the environment variable is set using the `set` command.

 ```cmd
 set DEBUG=*,-not_this
 ```

 Note that PowerShell uses different syntax to set environment variables.

 ```cmd
 $env:DEBUG = "*,-not_this"
  ```

Then, run the program to be debugged as usual.

## Millisecond diff

  When actively developing an application it can be useful to see when the time spent between one `debug()` call and the next. Suppose for example you invoke `debug()` before requesting a resource, and after as well, the "+NNNms" will show you how much time was spent between calls.

  ![](http://f.cl.ly/items/2i3h1d3t121M2Z1A3Q0N/Screenshot.png)

  When stdout is not a TTY, `Date#toUTCString()` is used, making it more useful for logging the debug information as shown below:

  ![](http://f.cl.ly/items/112H3i0e0o0P0a2Q2r11/Screenshot.png)

## Conventions

  If you're using this in one or more of your libraries, you _should_ use the name of your library so that developers may toggle debugging as desired without guessing names. If you have more than one debuggers you _should_ prefix them with your library name and use ":" to separate features. For example "bodyParser" from Connect would then be "connect:bodyParser".

## Wildcards

  The `*` character may be used as a wildcard. Suppose for example your library has debuggers named "connect:bodyParser", "connect:compress", "connect:session", instead of listing all three with `DEBUG=connect:bodyParser,connect:compress,connect:session`, you may simply do `DEBUG=connect:*`, or to run everything using this module simply use `DEBUG=*`.

  You can also exclude specific debuggers by prefixing them with a "-" character.  For example, `DEBUG=*,-connect:*` would include all debuggers except those starting with "connect:".

## Environment Variables

  When running through Node.js, you can set a few environment variables that will
  change the behavior of the debug logging:

| Name      | Purpose                                         |
|-----------|-------------------------------------------------|
| `DEBUG`   | Enables/disables specific debugging namespaces. |
| `DEBUG_COLORS`| Whether or not to use colors in the debug output. |
| `DEBUG_DEPTH` | Object inspection depth. |
| `DEBUG_SHOW_HIDDEN` | Shows hidden properties on inspected objects. |


  __Note:__ The environment variables beginning with `DEBUG_` end up being
  converted into an Options object that gets used with `%o`/`%O` formatters.
  See the Node.js documentation for
  [`util.inspect()`](https://nodejs.org/api/util.html#util_util_inspect_object_options)
  for the complete list.

## Formatters


  Debug uses [printf-style](https://wikipedia.org/wiki/Printf_format_string) formatting. Below are the officially supported formatters:

| Formatter | Representation |
|-----------|----------------|
| `%O`      | Pretty-print an Object on multiple lines. |
| `%o`      | Pretty-print an Object all on a single line. |
| `%s`      | String. |
| `%d`      | Number (both integer and float). |
| `%j`      | JSON. Replaced with the string '[Circular]' if the argument contains circular references. |
| `%%`      | Single percent sign ('%'). This does not consume an argument. |

### Custom formatters

  You can add custom formatters by extending the `debug.formatters` object. For example, if you wanted to add support for rendering a Buffer as hex with `%h`, you could do something like:

```js
const createDebug = require('debug')
createDebug.formatters.h = (v) => {
  return v.toString('hex')
}

// …elsewhere
const debug = createDebug('foo')
debug('this is hex: %h', new Buffer('hello world'))
//   foo this is hex: 68656c6c6f20776f726c6421 +0ms
```

## Browser support
  You can build a browser-ready script using [browserify](https://github.com/substack/node-browserify),
  or just use the [browserify-as-a-service](https://wzrd.in/) [build](https://wzrd.in/standalone/debug@latest),
  if you don't want to build it yourself.

  Debug's enable state is currently persisted by `localStorage`.
  Consider the situation shown below where you have `worker:a` and `worker:b`,
  and wish to debug both. You can enable this using `localStorage.debug`:

```js
localStorage.debug = 'worker:*'
```

And then refresh the page.

```js
a = debug('worker:a');
b = debug('worker:b');

setInterval(function(){
  a('doing some work');
}, 1000);

setInterval(function(){
  b('doing some work');
}, 1200);
```

#### Web Inspector Colors

  Colors are also enabled on "Web Inspectors" that understand the `%c` formatting
  option. These are WebKit web inspectors, Firefox ([since version
  31](https://hacks.mozilla.org/2014/05/editable-box-model-multiple-selection-sublime-text-keys-much-more-firefox-developer-tools-episode-31/))
  and the Firebug plugin for Firefox (any version).

  Colored output looks something like:

  ![](https://cloud.githubusercontent.com/assets/71256/3139768/b98c5fd8-e8ef-11e3-862a-f7253b6f47c6.png)


## Output streams

  By default `debug` will log to stderr, however this can be configured per-namespace by overriding the `log` method:

Example _stdout.js_:

```js
var debug = require('debug');
var error = debug('app:error');

// by default stderr is used
error('goes to stderr!');

var log = debug('app:log');
// set this namespace to log via console.log
log.log = console.log.bind(console); // don't forget to bind to console!
log('goes to stdout');
error('still goes to stderr!');

// set all output to go via console.info
// overrides all per-namespace log settings
debug.log = console.info.bind(console);
error('now goes to stdout via console.info');
log('still goes to stdout, but via console.info now');
```


## Authors

 - TJ Holowaychuk
 - Nathan Rajlich
 - Andrew Rhyne
 
## Backers

Support us with a monthly donation and help us continue our activities. [[Become a backer](https://opencollective.com/debug#backer)]

<a href="https://opencollective.com/debug/backer/0/website" target="_blank"><img src="https://opencollective.com/debug/backer/0/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/1/website" target="_blank"><img src="https://opencollective.com/debug/backer/1/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/2/website" target="_blank"><img src="https://opencollective.com/debug/backer/2/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/3/website" target="_blank"><img src="https://opencollective.com/debug/backer/3/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/4/website" target="_blank"><img src="https://opencollective.com/debug/backer/4/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/5/website" target="_blank"><img src="https://opencollective.com/debug/backer/5/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/6/website" target="_blank"><img src="https://opencollective.com/debug/backer/6/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/7/website" target="_blank"><img src="https://opencollective.com/debug/backer/7/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/8/website" target="_blank"><img src="https://opencollective.com/debug/backer/8/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/9/website" target="_blank"><img src="https://opencollective.com/debug/backer/9/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/10/website" target="_blank"><img src="https://opencollective.com/debug/backer/10/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/11/website" target="_blank"><img src="https://opencollective.com/debug/backer/11/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/12/website" target="_blank"><img src="https://opencollective.com/debug/backer/12/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/13/website" target="_blank"><img src="https://opencollective.com/debug/backer/13/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/14/website" target="_blank"><img src="https://opencollective.com/debug/backer/14/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/15/website" target="_blank"><img src="https://opencollective.com/debug/backer/15/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/16/website" target="_blank"><img src="https://opencollective.com/debug/backer/16/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/17/website" target="_blank"><img src="https://opencollective.com/debug/backer/17/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/18/website" target="_blank"><img src="https://opencollective.com/debug/backer/18/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/19/website" target="_blank"><img src="https://opencollective.com/debug/backer/19/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/20/website" target="_blank"><img src="https://opencollective.com/debug/backer/20/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/21/website" target="_blank"><img src="https://opencollective.com/debug/backer/21/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/22/website" target="_blank"><img src="https://opencollective.com/debug/backer/22/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/23/website" target="_blank"><img src="https://opencollective.com/debug/backer/23/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/24/website" target="_blank"><img src="https://opencollective.com/debug/backer/24/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/25/website" target="_blank"><img src="https://opencollective.com/debug/backer/25/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/26/website" target="_blank"><img src="https://opencollective.com/debug/backer/26/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/27/website" target="_blank"><img src="https://opencollective.com/debug/backer/27/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/28/website" target="_blank"><img src="https://opencollective.com/debug/backer/28/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/29/website" target="_blank"><img src="https://opencollective.com/debug/backer/29/avatar.svg"></a>


## Sponsors

Become a sponsor and get your logo on our README on Github with a link to your site. [[Become a sponsor](https://opencollective.com/debug#sponsor)]

<a href="https://opencollective.com/debug/sponsor/0/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/0/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/1/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/1/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/2/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/2/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/3/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/3/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/4/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/4/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/5/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/5/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/6/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/6/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/7/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/7/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/8/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/8/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/9/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/9/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/10/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/10/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/11/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/11/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/12/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/12/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/13/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/13/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/14/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/14/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/15/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/15/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/16/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/16/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/17/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/17/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/18/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/18/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/19/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/19/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/20/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/20/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/21/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/21/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/22/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/22/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/23/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/23/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/24/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/24/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/25/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/25/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/26/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/26/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/27/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/27/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/28/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/28/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/29/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/29/avatar.svg"></a>

## License

(The MIT License)

Copyright (c) 2014-2016 TJ Holowaychuk &lt;tj@vision-media.ca&gt;

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
'Software'), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


---

The MIT License (MIT)

Copyright (c) 2016 Zeit, Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# ms

[![Build Status](https://travis-ci.org/zeit/ms.svg?branch=master)](https://travis-ci.org/zeit/ms)
[![Slack Channel](http://zeit-slackin.now.sh/badge.svg)](https://zeit.chat/)

Use this package to easily convert various time formats to milliseconds.

## Examples

```js
ms('2 days')  // 172800000
ms('1d')      // 86400000
ms('10h')     // 36000000
ms('2.5 hrs') // 9000000
ms('2h')      // 7200000
ms('1m')      // 60000
ms('5s')      // 5000
ms('1y')      // 31557600000
ms('100')     // 100
```

### Convert from milliseconds

```js
ms(60000)             // "1m"
ms(2 * 60000)         // "2m"
ms(ms('10 hours'))    // "10h"
```

### Time format written-out

```js
ms(60000, { long: true })             // "1 minute"
ms(2 * 60000, { long: true })         // "2 minutes"
ms(ms('10 hours'), { long: true })    // "10 hours"
```

## Features

- Works both in [node](https://nodejs.org) and in the browser.
- If a number is supplied to `ms`, a string with a unit is returned.
- If a string that contains the number is supplied, it returns it as a number (e.g.: it returns `100` for `'100'`).
- If you pass a string with a number and a valid unit, the number of equivalent ms is returned.

## Caught a bug?

1. [Fork](https://help.github.com/articles/fork-a-repo/) this repository to your own GitHub account and then [clone](https://help.github.com/articles/cloning-a-repository/) it to your local device
2. Link the package to the global module directory: `npm link`
3. Within the module you want to test your local development instance of ms, just link it to the dependencies: `npm link ms`. Instead of the default one from npm, node will now use your clone of ms!

As always, you can run the tests using: `npm test`


---

# Path-to-RegExp

Turn an Express-style path string such as `/user/:name` into a regular expression.

**Note:** This is a legacy branch. You should upgrade to `1.x`.

## Usage

```javascript
var pathToRegexp = require('path-to-regexp');
```

### pathToRegexp(path, keys, options)

 - **path** A string in the express format, an array of such strings, or a regular expression
 - **keys** An array to be populated with the keys present in the url.  Once the function completes, this will be an array of strings.
 - **options**
   - **options.sensitive** Defaults to false, set this to true to make routes case sensitive
   - **options.strict** Defaults to false, set this to true to make the trailing slash matter.
   - **options.end** Defaults to true, set this to false to only match the prefix of the URL.

```javascript
var keys = [];
var exp = pathToRegexp('/foo/:bar', keys);
//keys = ['bar']
//exp = /^\/foo\/(?:([^\/]+?))\/?$/i
```

## Live Demo

You can see a live demo of this library in use at [express-route-tester](http://forbeslindesay.github.com/express-route-tester/).

## License

  MIT


---

1.2.1 / 2019-05-10
==================

  * Improve error when `str` is not a string

1.2.0 / 2016-06-01
==================

  * Add `combine` option to combine overlapping ranges

1.1.0 / 2016-05-13
==================

  * Fix incorrectly returning -1 when there is at least one valid range
  * perf: remove internal function

1.0.3 / 2015-10-29
==================

  * perf: enable strict mode

1.0.2 / 2014-09-08
==================

  * Support Node.js 0.6

1.0.1 / 2014-09-07
==================

  * Move repository to jshttp

1.0.0 / 2013-12-11
==================

  * Add repository to package.json
  * Add MIT license

0.0.4 / 2012-06-17
==================

  * Change ret -1 for unsatisfiable and -2 when invalid

0.0.3 / 2012-06-17
==================

  * Fix last-byte-pos default to len - 1

0.0.2 / 2012-06-14
==================

  * Add `.type`

0.0.1 / 2012-06-11
==================

  * Initial release


---

# range-parser

[![NPM Version][npm-version-image]][npm-url]
[![NPM Downloads][npm-downloads-image]][npm-url]
[![Node.js Version][node-image]][node-url]
[![Build Status][travis-image]][travis-url]
[![Test Coverage][coveralls-image]][coveralls-url]

Range header field parser.

## Installation

This is a [Node.js](https://nodejs.org/en/) module available through the
[npm registry](https://www.npmjs.com/). Installation is done using the
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):

```sh
$ npm install range-parser
```

## API

<!-- eslint-disable no-unused-vars -->

```js
var parseRange = require('range-parser')
```

### parseRange(size, header, options)

Parse the given `header` string where `size` is the maximum size of the resource.
An array of ranges will be returned or negative numbers indicating an error parsing.

  * `-2` signals a malformed header string
  * `-1` signals an unsatisfiable range

<!-- eslint-disable no-undef -->

```js
// parse header from request
var range = parseRange(size, req.headers.range)

// the type of the range
if (range.type === 'bytes') {
  // the ranges
  range.forEach(function (r) {
    // do something with r.start and r.end
  })
}
```

#### Options

These properties are accepted in the options object.

##### combine

Specifies if overlapping & adjacent ranges should be combined, defaults to `false`.
When `true`, ranges will be combined and returned as if they were specified that
way in the header.

<!-- eslint-disable no-undef -->

```js
parseRange(100, 'bytes=50-55,0-10,5-10,56-60', { combine: true })
// => [
//      { start: 0,  end: 10 },
//      { start: 50, end: 60 }
//    ]
```

## License

[MIT](LICENSE)

[coveralls-image]: https://badgen.net/coveralls/c/github/jshttp/range-parser/master
[coveralls-url]: https://coveralls.io/r/jshttp/range-parser?branch=master
[node-image]: https://badgen.net/npm/node/range-parser
[node-url]: https://nodejs.org/en/download
[npm-downloads-image]: https://badgen.net/npm/dm/range-parser
[npm-url]: https://npmjs.org/package/range-parser
[npm-version-image]: https://badgen.net/npm/v/range-parser
[travis-image]: https://badgen.net/travis/jshttp/range-parser/master
[travis-url]: https://travis-ci.org/jshttp/range-parser


---

3.0.2 / 2018-07-19
==================
  * [Fix] Prevent merging `__proto__` property (#48)
  * [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `tape`
  * [Tests] up to `node` `v10.7`, `v9.11`, `v8.11`, `v7.10`, `v6.14`, `v4.9`; use `nvm install-latest-npm`

3.0.1 / 2017-04-27
==================
  * [Fix] deep extending should work with a non-object (#46)
  * [Dev Deps] update `tape`, `eslint`, `@ljharb/eslint-config`
  * [Tests] up to `node` `v7.9`, `v6.10`, `v4.8`; improve matrix
  * [Docs] Switch from vb.teelaun.ch to versionbadg.es for the npm version badge SVG.
  * [Docs] Add example to readme (#34)

3.0.0 / 2015-07-01
==================
  * [Possible breaking change] Use global "strict" directive (#32)
  * [Tests] `int` is an ES3 reserved word
  * [Tests] Test up to `io.js` `v2.3`
  * [Tests] Add `npm run eslint`
  * [Dev Deps] Update `covert`, `jscs`

2.0.1 / 2015-04-25
==================
  * Use an inline `isArray` check, for ES3 browsers. (#27)
  * Some old browsers fail when an identifier is `toString`
  * Test latest `node` and `io.js` versions on `travis-ci`; speed up builds
  * Add license info to package.json (#25)
  * Update `tape`, `jscs`
  * Adding a CHANGELOG

2.0.0 / 2014-10-01
==================
  * Increase code coverage to 100%; run code coverage as part of tests
  * Add `npm run lint`; Run linter as part of tests
  * Remove nodeType and setInterval checks in isPlainObject
  * Updating `tape`, `jscs`, `covert`
  * General style and README cleanup

1.3.0 / 2014-06-20
==================
  * Add component.json for browser support (#18)
  * Use SVG for badges in README (#16)
  * Updating `tape`, `covert`
  * Updating travis-ci to work with multiple node versions
  * Fix `deep === false` bug (returning target as {}) (#14)
  * Fixing constructor checks in isPlainObject
  * Adding additional test coverage
  * Adding `npm run coverage`
  * Add LICENSE (#13)
  * Adding a warning about `false`, per #11
  * General style and whitespace cleanup

1.2.1 / 2013-09-14
==================
  * Fixing hasOwnProperty bugs that would only have shown up in specific browsers. Fixes #8
  * Updating `tape`

1.2.0 / 2013-09-02
==================
  * Updating the README: add badges
  * Adding a missing variable reference.
  * Using `tape` instead of `buster` for tests; add more tests (#7)
  * Adding node 0.10 to Travis CI (#6)
  * Enabling "npm test" and cleaning up package.json (#5)
  * Add Travis CI.

1.1.3 / 2012-12-06
==================
  * Added unit tests.
  * Ensure extend function is named. (Looks nicer in a stack trace.)
  * README cleanup.

1.1.1 / 2012-11-07
==================
  * README cleanup.
  * Added installation instructions.
  * Added a missing semicolon

1.0.0 / 2012-04-08
==================
  * Initial commit



---

[![Build Status][travis-svg]][travis-url]
[![dependency status][deps-svg]][deps-url]
[![dev dependency status][dev-deps-svg]][dev-deps-url]

# extend() for Node.js <sup>[![Version Badge][npm-version-png]][npm-url]</sup>

`node-extend` is a port of the classic extend() method from jQuery. It behaves as you expect. It is simple, tried and true.

Notes:

* Since Node.js >= 4,
  [`Object.assign`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign)
  now offers the same functionality natively (but without the "deep copy" option).
  See [ECMAScript 2015 (ES6) in Node.js](https://nodejs.org/en/docs/es6).
* Some native implementations of `Object.assign` in both Node.js and many
  browsers (since NPM modules are for the browser too) may not be fully
  spec-compliant.
  Check [`object.assign`](https://www.npmjs.com/package/object.assign) module for
  a compliant candidate.

## Installation

This package is available on [npm][npm-url] as: `extend`

``` sh
npm install extend
```

## Usage

**Syntax:** extend **(** [`deep`], `target`, `object1`, [`objectN`] **)**

*Extend one object with one or more others, returning the modified object.*

**Example:**

``` js
var extend = require('extend');
extend(targetObject, object1, object2);
```

Keep in mind that the target object will be modified, and will be returned from extend().

If a boolean true is specified as the first argument, extend performs a deep copy, recursively copying any objects it finds. Otherwise, the copy will share structure with the original object(s).
Undefined properties are not copied. However, properties inherited from the object's prototype will be copied over.
Warning: passing `false` as the first argument is not supported.

### Arguments

* `deep` *Boolean* (optional)
If set, the merge becomes recursive (i.e. deep copy).
* `target`	*Object*
The object to extend.
* `object1`	*Object*
The object that will be merged into the first.
* `objectN` *Object* (Optional)
More objects to merge into the first.

## License

`node-extend` is licensed under the [MIT License][mit-license-url].

## Acknowledgements

All credit to the jQuery authors for perfecting this amazing utility.

Ported to Node.js by [Stefan Thomas][github-justmoon] with contributions by [Jonathan Buchanan][github-insin] and [Jordan Harband][github-ljharb].

[travis-svg]: https://travis-ci.org/justmoon/node-extend.svg
[travis-url]: https://travis-ci.org/justmoon/node-extend
[npm-url]: https://npmjs.org/package/extend
[mit-license-url]: http://opensource.org/licenses/MIT
[github-justmoon]: https://github.com/justmoon
[github-insin]: https://github.com/insin
[github-ljharb]: https://github.com/ljharb
[npm-version-png]: http://versionbadg.es/justmoon/node-extend.svg
[deps-svg]: https://david-dm.org/justmoon/node-extend.svg
[deps-url]: https://david-dm.org/justmoon/node-extend
[dev-deps-svg]: https://david-dm.org/justmoon/node-extend/dev-status.svg
[dev-deps-url]: https://david-dm.org/justmoon/node-extend#info=devDependencies



---

# extend-shallow [![NPM version](https://badge.fury.io/js/extend-shallow.svg)](http://badge.fury.io/js/extend-shallow)  [![Build Status](https://travis-ci.org/jonschlinkert/extend-shallow.svg)](https://travis-ci.org/jonschlinkert/extend-shallow)

> Extend an object with the properties of additional objects. node.js/javascript util.

## Install

Install with [npm](https://www.npmjs.com/)

```sh
$ npm i extend-shallow --save
```

## Usage

```js
var extend = require('extend-shallow');

extend({a: 'b'}, {c: 'd'})
//=> {a: 'b', c: 'd'}
```

Pass an empty object to shallow clone:

```js
var obj = {};
extend(obj, {a: 'b'}, {c: 'd'})
//=> {a: 'b', c: 'd'}
```

## Related

* [extend-shallow](https://github.com/jonschlinkert/extend-shallow): Extend an object with the properties of additional objects. node.js/javascript util.
* [for-own](https://github.com/jonschlinkert/for-own): Iterate over the own enumerable properties of an object, and return an object with properties… [more](https://github.com/jonschlinkert/for-own)
* [for-in](https://github.com/jonschlinkert/for-in): Iterate over the own and inherited enumerable properties of an objecte, and return an object… [more](https://github.com/jonschlinkert/for-in)
* [is-plain-object](https://github.com/jonschlinkert/is-plain-object): Returns true if an object was created by the `Object` constructor.
* [isobject](https://github.com/jonschlinkert/isobject): Returns true if the value is an object and not an array or null.
* [kind-of](https://github.com/jonschlinkert/kind-of): Get the native type of a value.

## Running tests

Install dev dependencies:

```sh
$ npm i -d && npm test
```

## Author

**Jon Schlinkert**

+ [github/jonschlinkert](https://github.com/jonschlinkert)
+ [twitter/jonschlinkert](http://twitter.com/jonschlinkert)

## License

Copyright © 2015 Jon Schlinkert
Released under the MIT license.

***

_This file was generated by [verb-cli](https://github.com/assemble/verb-cli) on June 29, 2015._

---

# fast-deep-equal
The fastest deep equal with ES6 Map, Set and Typed arrays support.

[![Build Status](https://travis-ci.org/epoberezkin/fast-deep-equal.svg?branch=master)](https://travis-ci.org/epoberezkin/fast-deep-equal)
[![npm](https://img.shields.io/npm/v/fast-deep-equal.svg)](https://www.npmjs.com/package/fast-deep-equal)
[![Coverage Status](https://coveralls.io/repos/github/epoberezkin/fast-deep-equal/badge.svg?branch=master)](https://coveralls.io/github/epoberezkin/fast-deep-equal?branch=master)


## Install

```bash
npm install fast-deep-equal
```


## Features

- ES5 compatible
- works in node.js (8+) and browsers (IE9+)
- checks equality of Date and RegExp objects by value.

ES6 equal (`require('fast-deep-equal/es6')`) also supports:
- Maps
- Sets
- Typed arrays


## Usage

```javascript
var equal = require('fast-deep-equal');
console.log(equal({foo: 'bar'}, {foo: 'bar'})); // true
```

To support ES6 Maps, Sets and Typed arrays equality use:

```javascript
var equal = require('fast-deep-equal/es6');
console.log(equal(Int16Array([1, 2]), Int16Array([1, 2]))); // true
```

To use with React (avoiding the traversal of React elements' _owner
property that contains circular references and is not needed when
comparing the elements - borrowed from [react-fast-compare](https://github.com/FormidableLabs/react-fast-compare)):

```javascript
var equal = require('fast-deep-equal/react');
var equal = require('fast-deep-equal/es6/react');
```


## Performance benchmark

Node.js v12.6.0:

```
fast-deep-equal x 261,950 ops/sec ±0.52% (89 runs sampled)
fast-deep-equal/es6 x 212,991 ops/sec ±0.34% (92 runs sampled)
fast-equals x 230,957 ops/sec ±0.83% (85 runs sampled)
nano-equal x 187,995 ops/sec ±0.53% (88 runs sampled)
shallow-equal-fuzzy x 138,302 ops/sec ±0.49% (90 runs sampled)
underscore.isEqual x 74,423 ops/sec ±0.38% (89 runs sampled)
lodash.isEqual x 36,637 ops/sec ±0.72% (90 runs sampled)
deep-equal x 2,310 ops/sec ±0.37% (90 runs sampled)
deep-eql x 35,312 ops/sec ±0.67% (91 runs sampled)
ramda.equals x 12,054 ops/sec ±0.40% (91 runs sampled)
util.isDeepStrictEqual x 46,440 ops/sec ±0.43% (90 runs sampled)
assert.deepStrictEqual x 456 ops/sec ±0.71% (88 runs sampled)

The fastest is fast-deep-equal
```

To run benchmark (requires node.js 6+):

```bash
npm run benchmark
```

__Please note__: this benchmark runs against the available test cases. To choose the most performant library for your application, it is recommended to benchmark against your data and to NOT expect this benchmark to reflect the performance difference in your application.


## Enterprise support

fast-deep-equal package is a part of [Tidelift enterprise subscription](https://tidelift.com/subscription/pkg/npm-fast-deep-equal?utm_source=npm-fast-deep-equal&utm_medium=referral&utm_campaign=enterprise&utm_term=repo) - it provides a centralised commercial support to open-source software users, in addition to the support provided by software maintainers.


## Security contact

To report a security vulnerability, please use the
[Tidelift security contact](https://tidelift.com/security).
Tidelift will coordinate the fix and disclosure. Please do NOT report security vulnerability via GitHub issues.


## License

[MIT](https://github.com/epoberezkin/fast-deep-equal/blob/master/LICENSE)


---

# fast-glob

> It's a very fast and efficient [glob][glob_definition] library for [Node.js][node_js].

This package provides methods for traversing the file system and returning pathnames that matched a defined set of a specified pattern according to the rules used by the Unix Bash shell with some simplifications, meanwhile results are returned in **arbitrary order**. Quick, simple, effective.

## Table of Contents

<details>
<summary><strong>Details</strong></summary>

* [Highlights](#highlights)
* [Old and modern mode](#old-and-modern-mode)
* [Pattern syntax](#pattern-syntax)
  * [Basic syntax](#basic-syntax)
  * [Advanced syntax](#advanced-syntax)
* [Installation](#installation)
* [API](#api)
  * [Asynchronous](#asynchronous)
  * [Synchronous](#synchronous)
  * [Stream](#stream)
    * [patterns](#patterns)
    * [[options]](#options)
  * [Helpers](#helpers)
    * [generateTasks](#generatetaskspatterns-options)
    * [isDynamicPattern](#isdynamicpatternpattern-options)
    * [escapePath](#escapepathpath)
	* [convertPathToPattern](#convertpathtopatternpath)
* [Options](#options-3)
  * [Common](#common)
    * [concurrency](#concurrency)
    * [cwd](#cwd)
    * [deep](#deep)
    * [followSymbolicLinks](#followsymboliclinks)
    * [fs](#fs)
    * [ignore](#ignore)
    * [suppressErrors](#suppresserrors)
    * [throwErrorOnBrokenSymbolicLink](#throwerroronbrokensymboliclink)
  * [Output control](#output-control)
    * [absolute](#absolute)
    * [markDirectories](#markdirectories)
    * [objectMode](#objectmode)
    * [onlyDirectories](#onlydirectories)
    * [onlyFiles](#onlyfiles)
    * [stats](#stats)
    * [unique](#unique)
  * [Matching control](#matching-control)
    * [braceExpansion](#braceexpansion)
    * [caseSensitiveMatch](#casesensitivematch)
    * [dot](#dot)
    * [extglob](#extglob)
    * [globstar](#globstar)
    * [baseNameMatch](#basenamematch)
* [FAQ](#faq)
  * [What is a static or dynamic pattern?](#what-is-a-static-or-dynamic-pattern)
  * [How to write patterns on Windows?](#how-to-write-patterns-on-windows)
  * [Why are parentheses match wrong?](#why-are-parentheses-match-wrong)
  * [How to exclude directory from reading?](#how-to-exclude-directory-from-reading)
  * [How to use UNC path?](#how-to-use-unc-path)
  * [Compatible with `node-glob`?](#compatible-with-node-glob)
* [Benchmarks](#benchmarks)
  * [Server](#server)
  * [Nettop](#nettop)
* [Changelog](#changelog)
* [License](#license)

</details>

## Highlights

* Fast. Probably the fastest.
* Supports multiple and negative patterns.
* Synchronous, Promise and Stream API.
* Object mode. Can return more than just strings.
* Error-tolerant.

## Old and modern mode

This package works in two modes, depending on the environment in which it is used.

* **Old mode**. Node.js below 10.10 or when the [`stats`](#stats) option is *enabled*.
* **Modern mode**. Node.js 10.10+ and the [`stats`](#stats) option is *disabled*.

The modern mode is faster. Learn more about the [internal mechanism][nodelib_fs_scandir_old_and_modern_modern].

## Pattern syntax

> :warning: Always use forward-slashes in glob expressions (patterns and [`ignore`](#ignore) option). Use backslashes for escaping characters.

There is more than one form of syntax: basic and advanced. Below is a brief overview of the supported features. Also pay attention to our [FAQ](#faq).

> :book: This package uses [`micromatch`][micromatch] as a library for pattern matching.

### Basic syntax

* An asterisk (`*`) — matches everything except slashes (path separators), hidden files (names starting with `.`).
* A double star or globstar (`**`) — matches zero or more directories.
* Question mark (`?`) – matches any single character except slashes (path separators).
* Sequence (`[seq]`) — matches any character in sequence.

> :book: A few additional words about the [basic matching behavior][picomatch_matching_behavior].

Some examples:

* `src/**/*.js` — matches all files in the `src` directory (any level of nesting) that have the `.js` extension.
* `src/*.??` — matches all files in the `src` directory (only first level of nesting) that have a two-character extension.
* `file-[01].js` — matches files: `file-0.js`, `file-1.js`.

### Advanced syntax

* [Escapes characters][micromatch_backslashes] (`\\`) — matching special characters (`$^*+?()[]`) as literals.
* [POSIX character classes][picomatch_posix_brackets] (`[[:digit:]]`).
* [Extended globs][micromatch_extglobs] (`?(pattern-list)`).
* [Bash style brace expansions][micromatch_braces] (`{}`).
* [Regexp character classes][micromatch_regex_character_classes] (`[1-5]`).
* [Regex groups][regular_expressions_brackets] (`(a|b)`).

> :book: A few additional words about the [advanced matching behavior][micromatch_extended_globbing].

Some examples:

* `src/**/*.{css,scss}` — matches all files in the `src` directory (any level of nesting) that have the `.css` or `.scss` extension.
* `file-[[:digit:]].js` — matches files: `file-0.js`, `file-1.js`, …, `file-9.js`.
* `file-{1..3}.js` — matches files: `file-1.js`, `file-2.js`, `file-3.js`.
* `file-(1|2)` — matches files: `file-1.js`, `file-2.js`.

## Installation

```console
npm install fast-glob
```

## API

### Asynchronous

```js
fg(patterns, [options])
fg.async(patterns, [options])
fg.glob(patterns, [options])
```

Returns a `Promise` with an array of matching entries.

```js
const fg = require('fast-glob');

const entries = await fg(['.editorconfig', '**/index.js'], { dot: true });

// ['.editorconfig', 'services/index.js']
```

### Synchronous

```js
fg.sync(patterns, [options])
fg.globSync(patterns, [options])
```

Returns an array of matching entries.

```js
const fg = require('fast-glob');

const entries = fg.sync(['.editorconfig', '**/index.js'], { dot: true });

// ['.editorconfig', 'services/index.js']
```

### Stream

```js
fg.stream(patterns, [options])
fg.globStream(patterns, [options])
```

Returns a [`ReadableStream`][node_js_stream_readable_streams] when the `data` event will be emitted with matching entry.

```js
const fg = require('fast-glob');

const stream = fg.stream(['.editorconfig', '**/index.js'], { dot: true });

for await (const entry of stream) {
	// .editorconfig
	// services/index.js
}
```

#### patterns

* Required: `true`
* Type: `string | string[]`

Any correct pattern(s).

> :1234: [Pattern syntax](#pattern-syntax)
>
> :warning: This package does not respect the order of patterns. First, all the negative patterns are applied, and only then the positive patterns. If you want to get a certain order of records, use sorting or split calls.

#### [options]

* Required: `false`
* Type: [`Options`](#options-3)

See [Options](#options-3) section.

### Helpers

#### `generateTasks(patterns, [options])`

Returns the internal representation of patterns ([`Task`](./src/managers/tasks.ts) is a combining patterns by base directory).

```js
fg.generateTasks('*');

[{
    base: '.', // Parent directory for all patterns inside this task
    dynamic: true, // Dynamic or static patterns are in this task
    patterns: ['*'],
    positive: ['*'],
    negative: []
}]
```

##### patterns

* Required: `true`
* Type: `string | string[]`

Any correct pattern(s).

##### [options]

* Required: `false`
* Type: [`Options`](#options-3)

See [Options](#options-3) section.

#### `isDynamicPattern(pattern, [options])`

Returns `true` if the passed pattern is a dynamic pattern.

> :1234: [What is a static or dynamic pattern?](#what-is-a-static-or-dynamic-pattern)

```js
fg.isDynamicPattern('*'); // true
fg.isDynamicPattern('abc'); // false
```

##### pattern

* Required: `true`
* Type: `string`

Any correct pattern.

##### [options]

* Required: `false`
* Type: [`Options`](#options-3)

See [Options](#options-3) section.

#### `escapePath(path)`

Returns the path with escaped special characters depending on the platform.

* Posix:
  * `*?|(){}[]`;
  * `!` at the beginning of line;
  * `@+!` before the opening parenthesis;
  * `\\` before non-special characters;
* Windows:
  * `(){}[]`
  * `!` at the beginning of line;
  * `@+!` before the opening parenthesis;
  * Characters like `*?|` cannot be used in the path ([windows_naming_conventions][windows_naming_conventions]), so they will not be escaped;

```js
fg.escapePath('!abc');
// \\!abc
fg.escapePath('[OpenSource] mrmlnc – fast-glob (Deluxe Edition) 2014') + '/*.flac'
// \\[OpenSource\\] mrmlnc – fast-glob \\(Deluxe Edition\\) 2014/*.flac

fg.posix.escapePath('C:\\Program Files (x86)\\**\\*');
// C:\\\\Program Files \\(x86\\)\\*\\*\\*
fg.win32.escapePath('C:\\Program Files (x86)\\**\\*');
// Windows: C:\\Program Files \\(x86\\)\\**\\*
```

#### `convertPathToPattern(path)`

Converts a path to a pattern depending on the platform, including special character escaping.

* Posix. Works similarly to the `fg.posix.escapePath` method.
* Windows. Works similarly to the `fg.win32.escapePath` method, additionally converting backslashes to forward slashes in cases where they are not escape characters (`!()+@{}[]`).

```js
fg.convertPathToPattern('[OpenSource] mrmlnc – fast-glob (Deluxe Edition) 2014') + '/*.flac';
// \\[OpenSource\\] mrmlnc – fast-glob \\(Deluxe Edition\\) 2014/*.flac

fg.convertPathToPattern('C:/Program Files (x86)/**/*');
// Posix: C:/Program Files \\(x86\\)/\\*\\*/\\*
// Windows: C:/Program Files \\(x86\\)/**/*

fg.convertPathToPattern('C:\\Program Files (x86)\\**\\*');
// Posix: C:\\\\Program Files \\(x86\\)\\*\\*\\*
// Windows: C:/Program Files \\(x86\\)/**/*

fg.posix.convertPathToPattern('\\\\?\\c:\\Program Files (x86)') + '/**/*';
// Posix: \\\\\\?\\\\c:\\\\Program Files \\(x86\\)/**/* (broken pattern)
fg.win32.convertPathToPattern('\\\\?\\c:\\Program Files (x86)') + '/**/*';
// Windows: //?/c:/Program Files \\(x86\\)/**/*
```

## Options

### Common options

#### concurrency

* Type: `number`
* Default: `os.cpus().length`

Specifies the maximum number of concurrent requests from a reader to read directories.

> :book: The higher the number, the higher the performance and load on the file system. If you want to read in quiet mode, set the value to a comfortable number or `1`.

<details>

<summary>More details</summary>

In Node, there are [two types of threads][nodejs_thread_pool]: Event Loop (code) and a Thread Pool (fs, dns, …). The thread pool size controlled by the `UV_THREADPOOL_SIZE` environment variable. Its default size is 4 ([documentation][libuv_thread_pool]). The pool is one for all tasks within a single Node process.

Any code can make 4 real concurrent accesses to the file system. The rest of the FS requests will wait in the queue.

> :book: Each new instance of FG in the same Node process will use the same Thread pool.

But this package also has the `concurrency` option. This option allows you to control the number of concurrent accesses to the FS at the package level. By default, this package has a value equal to the number of cores available for the current Node process. This allows you to set a value smaller than the pool size (`concurrency: 1`) or, conversely, to prepare tasks for the pool queue more quickly (`concurrency: Number.POSITIVE_INFINITY`).

So, in fact, this package can **only make 4 concurrent requests to the FS**. You can increase this value by using an environment variable (`UV_THREADPOOL_SIZE`), but in practice this does not give a multiple advantage.

</details>

#### cwd

* Type: `string`
* Default: `process.cwd()`

The current working directory in which to search.

#### deep

* Type: `number`
* Default: `Infinity`

Specifies the maximum depth of a read directory relative to the start directory.

For example, you have the following tree:

```js
dir/
└── one/            // 1
    └── two/        // 2
        └── file.js // 3
```

```js
// With base directory
fg.sync('dir/**', { onlyFiles: false, deep: 1 }); // ['dir/one']
fg.sync('dir/**', { onlyFiles: false, deep: 2 }); // ['dir/one', 'dir/one/two']

// With cwd option
fg.sync('**', { onlyFiles: false, cwd: 'dir', deep: 1 }); // ['one']
fg.sync('**', { onlyFiles: false, cwd: 'dir', deep: 2 }); // ['one', 'one/two']
```

> :book: If you specify a pattern with some base directory, this directory will not participate in the calculation of the depth of the found directories. Think of it as a [`cwd`](#cwd) option.

#### followSymbolicLinks

* Type: `boolean`
* Default: `true`

Indicates whether to traverse descendants of symbolic link directories when expanding `**` patterns.

> :book: Note that this option does not affect the base directory of the pattern. For example, if `./a` is a symlink to directory `./b` and you specified `['./a**', './b/**']` patterns, then directory `./a` will still be read.

> :book: If the [`stats`](#stats) option is specified, the information about the symbolic link (`fs.lstat`) will be replaced with information about the entry (`fs.stat`) behind it.

#### fs

* Type: `FileSystemAdapter`
* Default: `fs.*`

Custom implementation of methods for working with the file system. Supports objects with enumerable properties only.

```ts
export interface FileSystemAdapter {
    lstat?: typeof fs.lstat;
    stat?: typeof fs.stat;
    lstatSync?: typeof fs.lstatSync;
    statSync?: typeof fs.statSync;
    readdir?: typeof fs.readdir;
    readdirSync?: typeof fs.readdirSync;
}
```

#### ignore

* Type: `string[]`
* Default: `[]`

An array of glob patterns to exclude matches. This is an alternative way to use negative patterns.

```js
dir/
├── package-lock.json
└── package.json
```

```js
fg.sync(['*.json', '!package-lock.json']);            // ['package.json']
fg.sync('*.json', { ignore: ['package-lock.json'] }); // ['package.json']
```

#### suppressErrors

* Type: `boolean`
* Default: `false`

By default this package suppress only `ENOENT` errors. Set to `true` to suppress any error.

> :book: Can be useful when the directory has entries with a special level of access.

#### throwErrorOnBrokenSymbolicLink

* Type: `boolean`
* Default: `false`

Throw an error when symbolic link is broken if `true` or safely return `lstat` call if `false`.

> :book: This option has no effect on errors when reading the symbolic link directory.

### Output control

#### absolute

* Type: `boolean`
* Default: `false`

Return the absolute path for entries.

```js
fg.sync('*.js', { absolute: false }); // ['index.js']
fg.sync('*.js', { absolute: true });  // ['/home/user/index.js']
```

> :book: This option is required if you want to use negative patterns with absolute path, for example, `!${__dirname}/*.js`.

#### markDirectories

* Type: `boolean`
* Default: `false`

Mark the directory path with the final slash.

```js
fg.sync('*', { onlyFiles: false, markDirectories: false }); // ['index.js', 'controllers']
fg.sync('*', { onlyFiles: false, markDirectories: true });  // ['index.js', 'controllers/']
```

#### objectMode

* Type: `boolean`
* Default: `false`

Returns objects (instead of strings) describing entries.

```js
fg.sync('*', { objectMode: false }); // ['src/index.js']
fg.sync('*', { objectMode: true });  // [{ name: 'index.js', path: 'src/index.js', dirent: <fs.Dirent> }]
```

The object has the following fields:

* name (`string`) — the last part of the path (basename)
* path (`string`) — full path relative to the pattern base directory
* dirent ([`fs.Dirent`][node_js_fs_class_fs_dirent]) — instance of `fs.Dirent`

> :book: An object is an internal representation of entry, so getting it does not affect performance.

#### onlyDirectories

* Type: `boolean`
* Default: `false`

Return only directories.

```js
fg.sync('*', { onlyDirectories: false }); // ['index.js', 'src']
fg.sync('*', { onlyDirectories: true });  // ['src']
```

> :book: If `true`, the [`onlyFiles`](#onlyfiles) option is automatically `false`.

#### onlyFiles

* Type: `boolean`
* Default: `true`

Return only files.

```js
fg.sync('*', { onlyFiles: false }); // ['index.js', 'src']
fg.sync('*', { onlyFiles: true });  // ['index.js']
```

#### stats

* Type: `boolean`
* Default: `false`

Enables an [object mode](#objectmode) with an additional field:

* stats ([`fs.Stats`][node_js_fs_class_fs_stats]) — instance of `fs.Stats`

```js
fg.sync('*', { stats: false }); // ['src/index.js']
fg.sync('*', { stats: true });  // [{ name: 'index.js', path: 'src/index.js', dirent: <fs.Dirent>, stats: <fs.Stats> }]
```

> :book: Returns `fs.stat` instead of `fs.lstat` for symbolic links when the [`followSymbolicLinks`](#followsymboliclinks) option is specified.
>
> :warning: Unlike [object mode](#objectmode) this mode requires additional calls to the file system. On average, this mode is slower at least twice. See [old and modern mode](#old-and-modern-mode) for more details.

#### unique

* Type: `boolean`
* Default: `true`

Ensures that the returned entries are unique.

```js
fg.sync(['*.json', 'package.json'], { unique: false }); // ['package.json', 'package.json']
fg.sync(['*.json', 'package.json'], { unique: true });  // ['package.json']
```

If `true` and similar entries are found, the result is the first found.

### Matching control

#### braceExpansion

* Type: `boolean`
* Default: `true`

Enables Bash-like brace expansion.

> :1234: [Syntax description][bash_hackers_syntax_expansion_brace] or more [detailed description][micromatch_braces].

```js
dir/
├── abd
├── acd
└── a{b,c}d
```

```js
fg.sync('a{b,c}d', { braceExpansion: false }); // ['a{b,c}d']
fg.sync('a{b,c}d', { braceExpansion: true });  // ['abd', 'acd']
```

#### caseSensitiveMatch

* Type: `boolean`
* Default: `true`

Enables a [case-sensitive][wikipedia_case_sensitivity] mode for matching files.

```js
dir/
├── file.txt
└── File.txt
```

```js
fg.sync('file.txt', { caseSensitiveMatch: false }); // ['file.txt', 'File.txt']
fg.sync('file.txt', { caseSensitiveMatch: true });  // ['file.txt']
```

#### dot

* Type: `boolean`
* Default: `false`

Allow patterns to match entries that begin with a period (`.`).

> :book: Note that an explicit dot in a portion of the pattern will always match dot files.

```js
dir/
├── .editorconfig
└── package.json
```

```js
fg.sync('*', { dot: false }); // ['package.json']
fg.sync('*', { dot: true });  // ['.editorconfig', 'package.json']
```

#### extglob

* Type: `boolean`
* Default: `true`

Enables Bash-like `extglob` functionality.

> :1234: [Syntax description][micromatch_extglobs].

```js
dir/
├── README.md
└── package.json
```

```js
fg.sync('*.+(json|md)', { extglob: false }); // []
fg.sync('*.+(json|md)', { extglob: true });  // ['README.md', 'package.json']
```

#### globstar

* Type: `boolean`
* Default: `true`

Enables recursively repeats a pattern containing `**`. If `false`, `**` behaves exactly like `*`.

```js
dir/
└── a
    └── b
```

```js
fg.sync('**', { onlyFiles: false, globstar: false }); // ['a']
fg.sync('**', { onlyFiles: false, globstar: true });  // ['a', 'a/b']
```

#### baseNameMatch

* Type: `boolean`
* Default: `false`

If set to `true`, then patterns without slashes will be matched against the basename of the path if it contains slashes.

```js
dir/
└── one/
    └── file.md
```

```js
fg.sync('*.md', { baseNameMatch: false }); // []
fg.sync('*.md', { baseNameMatch: true });  // ['one/file.md']
```

## FAQ

## What is a static or dynamic pattern?

All patterns can be divided into two types:

* **static**. A pattern is considered static if it can be used to get an entry on the file system without using matching mechanisms. For example, the `file.js` pattern is a static pattern because we can just verify that it exists on the file system.
* **dynamic**. A pattern is considered dynamic if it cannot be used directly to find occurrences without using a matching mechanisms. For example, the `*` pattern is a dynamic pattern because we cannot use this pattern directly.

A pattern is considered dynamic if it contains the following characters (`…` — any characters or their absence) or options:

* The [`caseSensitiveMatch`](#casesensitivematch) option is disabled
* `\\` (the escape character)
* `*`, `?`, `!` (at the beginning of line)
* `[…]`
* `(…|…)`
* `@(…)`, `!(…)`, `*(…)`, `?(…)`, `+(…)` (respects the [`extglob`](#extglob) option)
* `{…,…}`, `{…..…}` (respects the [`braceExpansion`](#braceexpansion) option)

## How to write patterns on Windows?

Always use forward-slashes in glob expressions (patterns and [`ignore`](#ignore) option). Use backslashes for escaping characters. With the [`cwd`](#cwd) option use a convenient format.

**Bad**

```ts
[
	'directory\\*',
	path.join(process.cwd(), '**')
]
```

**Good**

```ts
[
	'directory/*',
	fg.convertPathToPattern(process.cwd()) + '/**'
]
```

> :book: Use the [`.convertPathToPattern`](#convertpathtopatternpath) package to convert Windows-style path to a Unix-style path.

Read more about [matching with backslashes][micromatch_backslashes].

## Why are parentheses match wrong?

```js
dir/
└── (special-*file).txt
```

```js
fg.sync(['(special-*file).txt']) // []
```

Refers to Bash. You need to escape special characters:

```js
fg.sync(['\\(special-*file\\).txt']) // ['(special-*file).txt']
```

Read more about [matching special characters as literals][picomatch_matching_special_characters_as_literals]. Or use the [`.escapePath`](#escapepathpath).

## How to exclude directory from reading?

You can use a negative pattern like this: `!**/node_modules` or `!**/node_modules/**`. Also you can use [`ignore`](#ignore) option. Just look at the example below.

```js
first/
├── file.md
└── second/
    └── file.txt
```

If you don't want to read the `second` directory, you must write the following pattern: `!**/second` or `!**/second/**`.

```js
fg.sync(['**/*.md', '!**/second']);                 // ['first/file.md']
fg.sync(['**/*.md'], { ignore: ['**/second/**'] }); // ['first/file.md']
```

> :warning: When you write `!**/second/**/*` it means that the directory will be **read**, but all the entries will not be included in the results.

You have to understand that if you write the pattern to exclude directories, then the directory will not be read under any circumstances.

## How to use UNC path?

You cannot use [Uniform Naming Convention (UNC)][unc_path] paths as patterns (due to syntax) directly, but you can use them as [`cwd`](#cwd) directory or use the `fg.convertPathToPattern` method.

```ts
// cwd
fg.sync('*', { cwd: '\\\\?\\C:\\Python27' /* or //?/C:/Python27 */ });
fg.sync('Python27/*', { cwd: '\\\\?\\C:\\' /* or //?/C:/ */ });

// .convertPathToPattern
fg.sync(fg.convertPathToPattern('\\\\?\\c:\\Python27') + '/*');
```

## Compatible with `node-glob`?

| node-glob    | fast-glob |
| :----------: | :-------: |
| `cwd`        | [`cwd`](#cwd) |
| `root`       | – |
| `dot`        | [`dot`](#dot) |
| `nomount`    | – |
| `mark`       | [`markDirectories`](#markdirectories) |
| `nosort`     | – |
| `nounique`   | [`unique`](#unique) |
| `nobrace`    | [`braceExpansion`](#braceexpansion) |
| `noglobstar` | [`globstar`](#globstar) |
| `noext`      | [`extglob`](#extglob) |
| `nocase`     | [`caseSensitiveMatch`](#casesensitivematch) |
| `matchBase`  | [`baseNameMatch`](#basenamematch) |
| `nodir`      | [`onlyFiles`](#onlyfiles) |
| `ignore`     | [`ignore`](#ignore) |
| `follow`     | [`followSymbolicLinks`](#followsymboliclinks) |
| `realpath`   | – |
| `absolute`   | [`absolute`](#absolute) |

## Benchmarks

You can see results [here](https://github.com/mrmlnc/fast-glob/actions/workflows/benchmark.yml?query=branch%3Amaster) for every commit into the `main` branch.

* **Product benchmark** – comparison with the main competitors.
* **Regress benchmark** – regression between the current version and the version from the npm registry.

## Changelog

See the [Releases section of our GitHub project][github_releases] for changelog for each release version.

## License

This software is released under the terms of the MIT license.

[bash_hackers_syntax_expansion_brace]: https://wiki.bash-hackers.org/syntax/expansion/brace
[github_releases]: https://github.com/mrmlnc/fast-glob/releases
[glob_definition]: https://en.wikipedia.org/wiki/Glob_(programming)
[glob_linux_man]: http://man7.org/linux/man-pages/man3/glob.3.html
[micromatch_backslashes]: https://github.com/micromatch/micromatch#backslashes
[micromatch_braces]: https://github.com/micromatch/braces
[micromatch_extended_globbing]: https://github.com/micromatch/micromatch#extended-globbing
[micromatch_extglobs]: https://github.com/micromatch/micromatch#extglobs
[micromatch_regex_character_classes]: https://github.com/micromatch/micromatch#regex-character-classes
[micromatch]: https://github.com/micromatch/micromatch
[node_js_fs_class_fs_dirent]: https://nodejs.org/api/fs.html#fs_class_fs_dirent
[node_js_fs_class_fs_stats]: https://nodejs.org/api/fs.html#fs_class_fs_stats
[node_js_stream_readable_streams]: https://nodejs.org/api/stream.html#stream_readable_streams
[node_js]: https://nodejs.org/en
[nodelib_fs_scandir_old_and_modern_modern]: https://github.com/nodelib/nodelib/blob/master/packages/fs/fs.scandir/README.md#old-and-modern-mode
[npm_normalize_path]: https://www.npmjs.com/package/normalize-path
[npm_unixify]: https://www.npmjs.com/package/unixify
[picomatch_matching_behavior]: https://github.com/micromatch/picomatch#matching-behavior-vs-bash
[picomatch_matching_special_characters_as_literals]: https://github.com/micromatch/picomatch#matching-special-characters-as-literals
[picomatch_posix_brackets]: https://github.com/micromatch/picomatch#posix-brackets
[regular_expressions_brackets]: https://www.regular-expressions.info/brackets.html
[unc_path]: https://learn.microsoft.com/openspecs/windows_protocols/ms-dtyp/62e862f4-2a51-452e-8eeb-dc4ff5ee33cc
[wikipedia_case_sensitivity]: https://en.wikipedia.org/wiki/Case_sensitivity
[nodejs_thread_pool]: https://nodejs.org/en/docs/guides/dont-block-the-event-loop
[libuv_thread_pool]: http://docs.libuv.org/en/v1.x/threadpool.html
[windows_naming_conventions]: https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file#naming-conventions


---

# fast-json-stable-stringify

Deterministic `JSON.stringify()` - a faster version of [@substack](https://github.com/substack)'s json-stable-strigify without [jsonify](https://github.com/substack/jsonify).

You can also pass in a custom comparison function.

[![Build Status](https://travis-ci.org/epoberezkin/fast-json-stable-stringify.svg?branch=master)](https://travis-ci.org/epoberezkin/fast-json-stable-stringify)
[![Coverage Status](https://coveralls.io/repos/github/epoberezkin/fast-json-stable-stringify/badge.svg?branch=master)](https://coveralls.io/github/epoberezkin/fast-json-stable-stringify?branch=master)

# example

``` js
var stringify = require('fast-json-stable-stringify');
var obj = { c: 8, b: [{z:6,y:5,x:4},7], a: 3 };
console.log(stringify(obj));
```

output:

```
{"a":3,"b":[{"x":4,"y":5,"z":6},7],"c":8}
```


# methods

``` js
var stringify = require('fast-json-stable-stringify')
```

## var str = stringify(obj, opts)

Return a deterministic stringified string `str` from the object `obj`.


## options

### cmp

If `opts` is given, you can supply an `opts.cmp` to have a custom comparison
function for object keys. Your function `opts.cmp` is called with these
parameters:

``` js
opts.cmp({ key: akey, value: avalue }, { key: bkey, value: bvalue })
```

For example, to sort on the object key names in reverse order you could write:

``` js
var stringify = require('fast-json-stable-stringify');

var obj = { c: 8, b: [{z:6,y:5,x:4},7], a: 3 };
var s = stringify(obj, function (a, b) {
    return a.key < b.key ? 1 : -1;
});
console.log(s);
```

which results in the output string:

```
{"c":8,"b":[{"z":6,"y":5,"x":4},7],"a":3}
```

Or if you wanted to sort on the object values in reverse order, you could write:

```
var stringify = require('fast-json-stable-stringify');

var obj = { d: 6, c: 5, b: [{z:3,y:2,x:1},9], a: 10 };
var s = stringify(obj, function (a, b) {
    return a.value < b.value ? 1 : -1;
});
console.log(s);
```

which outputs:

```
{"d":6,"c":5,"b":[{"z":3,"y":2,"x":1},9],"a":10}
```

### cycles

Pass `true` in `opts.cycles` to stringify circular property as `__cycle__` - the result will not be a valid JSON string in this case.

TypeError will be thrown in case of circular object without this option.


# install

With [npm](https://npmjs.org) do:

```
npm install fast-json-stable-stringify
```


# benchmark

To run benchmark (requires Node.js 6+):
```
node benchmark
```

Results:
```
fast-json-stable-stringify x 17,189 ops/sec ±1.43% (83 runs sampled)
json-stable-stringify x 13,634 ops/sec ±1.39% (85 runs sampled)
fast-stable-stringify x 20,212 ops/sec ±1.20% (84 runs sampled)
faster-stable-stringify x 15,549 ops/sec ±1.12% (84 runs sampled)
The fastest is fast-stable-stringify
```


## Enterprise support

fast-json-stable-stringify package is a part of [Tidelift enterprise subscription](https://tidelift.com/subscription/pkg/npm-fast-json-stable-stringify?utm_source=npm-fast-json-stable-stringify&utm_medium=referral&utm_campaign=enterprise&utm_term=repo) - it provides a centralised commercial support to open-source software users, in addition to the support provided by software maintainers.


## Security contact

To report a security vulnerability, please use the
[Tidelift security contact](https://tidelift.com/security).
Tidelift will coordinate the fix and disclosure. Please do NOT report security vulnerability via GitHub issues.


# license

[MIT](https://github.com/epoberezkin/fast-json-stable-stringify/blob/master/LICENSE)


---

# fast-uri

<div align="center">

[![NPM version](https://img.shields.io/npm/v/fast-uri.svg?style=flat)](https://www.npmjs.com/package/fast-uri)
[![CI](https://github.com/fastify/fast-uri/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/fastify/fast-uri/actions/workflows/ci.yml)
[![neostandard javascript style](https://img.shields.io/badge/code_style-neostandard-brightgreen?style=flat)](https://github.com/neostandard/neostandard)

</div>

Dependency-free RFC 3986 URI toolbox.

## Usage

## Options

All of the above functions can accept an additional options argument that is an object that can contain one or more of the following properties:

*	`scheme` (string)
	Indicates the scheme that the URI should be treated as, overriding the URI's normal scheme parsing behavior.

*	`reference` (string)
	If set to `"suffix"`, it indicates that the URI is in the suffix format and the parser will use the option's `scheme` property to determine the URI's scheme.

*	`tolerant` (boolean, false)
	If set to `true`, the parser will relax URI resolving rules.

*	`absolutePath` (boolean, false)
	If set to `true`, the serializer will not resolve a relative `path` component.

*	`unicodeSupport` (boolean, false)
	If set to `true`, the parser will unescape non-ASCII characters in the parsed output as per [RFC 3987](http://www.ietf.org/rfc/rfc3987.txt).

*	`domainHost` (boolean, false)
	If set to `true`, the library will treat the `host` component as a domain name, and convert IDNs (International Domain Names) as per [RFC 5891](http://www.ietf.org/rfc/rfc5891.txt).

### Parse

```js
const uri = require('fast-uri')
uri.parse('uri://user:pass@example.com:123/one/two.three?q1=a1&q2=a2#body')
// Output
{
  scheme: "uri",
  userinfo: "user:pass",
  host: "example.com",
  port: 123,
  path: "/one/two.three",
  query: "q1=a1&q2=a2",
  fragment: "body"
}
```

### Serialize

```js
const uri = require('fast-uri')
uri.serialize({scheme: "http", host: "example.com", fragment: "footer"})
// Output
"http://example.com/#footer"

```

### Resolve

```js
const uri = require('fast-uri')
uri.resolve("uri://a/b/c/d?q", "../../g")
// Output
"uri://a/g"
```

### Equal

```js
const uri = require('fast-uri')
uri.equal("example://a/b/c/%7Bfoo%7D", "eXAMPLE://a/./b/../b/%63/%7bfoo%7d")
// Output
true
```

## Scheme supports

fast-uri supports inserting custom [scheme](http://en.wikipedia.org/wiki/URI_scheme)-dependent processing rules. Currently, fast-uri has built-in support for the following schemes:

*	http \[[RFC 2616](http://www.ietf.org/rfc/rfc2616.txt)\]
*	https \[[RFC 2818](http://www.ietf.org/rfc/rfc2818.txt)\]
*	ws \[[RFC 6455](http://www.ietf.org/rfc/rfc6455.txt)\]
*	wss \[[RFC 6455](http://www.ietf.org/rfc/rfc6455.txt)\]
*	urn \[[RFC 2141](http://www.ietf.org/rfc/rfc2141.txt)\]
*	urn:uuid \[[RFC 4122](http://www.ietf.org/rfc/rfc4122.txt)\]


## Benchmarks

```
fast-uri: parse domain x 1,306,864 ops/sec ±0.31% (100 runs sampled)
urijs: parse domain x 483,001 ops/sec ±0.09% (99 runs sampled)
WHATWG URL: parse domain x 862,461 ops/sec ±0.18% (97 runs sampled)
fast-uri: parse IPv4 x 2,381,452 ops/sec ±0.26% (96 runs sampled)
urijs: parse IPv4 x 384,705 ops/sec ±0.34% (99 runs sampled)
WHATWG URL: parse IPv4 NOT SUPPORTED
fast-uri: parse IPv6 x 923,519 ops/sec ±0.09% (100 runs sampled)
urijs: parse IPv6 x 289,070 ops/sec ±0.07% (95 runs sampled)
WHATWG URL: parse IPv6 NOT SUPPORTED
fast-uri: parse URN x 2,596,395 ops/sec ±0.42% (98 runs sampled)
urijs: parse URN x 1,152,412 ops/sec ±0.09% (97 runs sampled)
WHATWG URL: parse URN x 1,183,307 ops/sec ±0.38% (100 runs sampled)
fast-uri: parse URN uuid x 1,666,861 ops/sec ±0.10% (98 runs sampled)
urijs: parse URN uuid x 852,724 ops/sec ±0.17% (95 runs sampled)
WHATWG URL: parse URN uuid NOT SUPPORTED
fast-uri: serialize uri x 1,741,499 ops/sec ±0.57% (95 runs sampled)
urijs: serialize uri x 389,014 ops/sec ±0.28% (93 runs sampled)
fast-uri: serialize IPv6 x 441,095 ops/sec ±0.37% (97 runs sampled)
urijs: serialize IPv6 x 255,443 ops/sec ±0.58% (94 runs sampled)
fast-uri: serialize ws x 1,448,667 ops/sec ±0.25% (97 runs sampled)
urijs: serialize ws x 352,884 ops/sec ±0.08% (96 runs sampled)
fast-uri: resolve x 340,084 ops/sec ±0.98% (98 runs sampled)
urijs: resolve x 225,759 ops/sec ±0.37% (95 runs sampled)
```

## TODO

- [ ] Support MailTo
- [ ] Be 100% iso compatible with uri-js
- [ ] Add browser test stack

## License

Licensed under [BSD-3-Clause](./LICENSE).


---

# fastq

![ci][ci-url]
[![npm version][npm-badge]][npm-url]

Fast, in memory work queue.

Benchmarks (1 million tasks):

* setImmediate: 812ms
* fastq: 854ms
* async.queue: 1298ms
* neoAsync.queue: 1249ms

Obtained on node 12.16.1, on a dedicated server.

If you need zero-overhead series function call, check out
[fastseries](http://npm.im/fastseries). For zero-overhead parallel
function call, check out [fastparallel](http://npm.im/fastparallel).

[![js-standard-style](https://raw.githubusercontent.com/feross/standard/master/badge.png)](https://github.com/feross/standard)

  * <a href="#install">Installation</a>
  * <a href="#usage">Usage</a>
  * <a href="#api">API</a>
  * <a href="#license">Licence &amp; copyright</a>

## Install

`npm i fastq --save`

## Usage (callback API)

```js
'use strict'

const queue = require('fastq')(worker, 1)

queue.push(42, function (err, result) {
  if (err) { throw err }
  console.log('the result is', result)
})

function worker (arg, cb) {
  cb(null, arg * 2)
}
```

## Usage (promise API)

```js
const queue = require('fastq').promise(worker, 1)

async function worker (arg) {
  return arg * 2
}

async function run () {
  const result = await queue.push(42)
  console.log('the result is', result)
}

run()
```

### Setting "this"

```js
'use strict'

const that = { hello: 'world' }
const queue = require('fastq')(that, worker, 1)

queue.push(42, function (err, result) {
  if (err) { throw err }
  console.log(this)
  console.log('the result is', result)
})

function worker (arg, cb) {
  console.log(this)
  cb(null, arg * 2)
}
```

### Using with TypeScript (callback API)

```ts
'use strict'

import * as fastq from "fastq";
import type { queue, done } from "fastq";

type Task = {
  id: number
}

const q: queue<Task> = fastq(worker, 1)

q.push({ id: 42})

function worker (arg: Task, cb: done) {
  console.log(arg.id)
  cb(null)
}
```

### Using with TypeScript (promise API)

```ts
'use strict'

import * as fastq from "fastq";
import type { queueAsPromised } from "fastq";

type Task = {
  id: number
}

const q: queueAsPromised<Task> = fastq.promise(asyncWorker, 1)

q.push({ id: 42}).catch((err) => console.error(err))

async function asyncWorker (arg: Task): Promise<void> {
  // No need for a try-catch block, fastq handles errors automatically
  console.log(arg.id)
}
```

## API

* <a href="#fastqueue"><code>fastqueue()</code></a>
* <a href="#push"><code>queue#<b>push()</b></code></a>
* <a href="#unshift"><code>queue#<b>unshift()</b></code></a>
* <a href="#pause"><code>queue#<b>pause()</b></code></a>
* <a href="#resume"><code>queue#<b>resume()</b></code></a>
* <a href="#idle"><code>queue#<b>idle()</b></code></a>
* <a href="#length"><code>queue#<b>length()</b></code></a>
* <a href="#getQueue"><code>queue#<b>getQueue()</b></code></a>
* <a href="#kill"><code>queue#<b>kill()</b></code></a>
* <a href="#killAndDrain"><code>queue#<b>killAndDrain()</b></code></a>
* <a href="#error"><code>queue#<b>error()</b></code></a>
* <a href="#concurrency"><code>queue#<b>concurrency</b></code></a>
* <a href="#drain"><code>queue#<b>drain</b></code></a>
* <a href="#empty"><code>queue#<b>empty</b></code></a>
* <a href="#saturated"><code>queue#<b>saturated</b></code></a>
* <a href="#promise"><code>fastqueue.promise()</code></a>

-------------------------------------------------------
<a name="fastqueue"></a>
### fastqueue([that], worker, concurrency)

Creates a new queue.

Arguments:

* `that`, optional context of the `worker` function.
* `worker`, worker function, it would be called with `that` as `this`,
  if that is specified.
* `concurrency`, number of concurrent tasks that could be executed in
  parallel.

-------------------------------------------------------
<a name="push"></a>
### queue.push(task, done)

Add a task at the end of the queue. `done(err, result)` will be called
when the task was processed.

-------------------------------------------------------
<a name="unshift"></a>
### queue.unshift(task, done)

Add a task at the beginning of the queue. `done(err, result)` will be called
when the task was processed.

-------------------------------------------------------
<a name="pause"></a>
### queue.pause()

Pause the processing of tasks. Currently worked tasks are not
stopped.

-------------------------------------------------------
<a name="resume"></a>
### queue.resume()

Resume the processing of tasks.

-------------------------------------------------------
<a name="idle"></a>
### queue.idle()

Returns `false` if there are tasks being processed or waiting to be processed.
`true` otherwise.

-------------------------------------------------------
<a name="length"></a>
### queue.length()

Returns the number of tasks waiting to be processed (in the queue).

-------------------------------------------------------
<a name="getQueue"></a>
### queue.getQueue()

Returns all the tasks be processed (in the queue). Returns empty array when there are no tasks

-------------------------------------------------------
<a name="kill"></a>
### queue.kill()

Removes all tasks waiting to be processed, and reset `drain` to an empty
function.

-------------------------------------------------------
<a name="killAndDrain"></a>
### queue.killAndDrain()

Same than `kill` but the `drain` function will be called before reset to empty.

-------------------------------------------------------
<a name="error"></a>
### queue.error(handler)

Set a global error handler. `handler(err, task)` will be called
each time a task is completed, `err` will be not null if the task has thrown an error.

-------------------------------------------------------
<a name="concurrency"></a>
### queue.concurrency

Property that returns the number of concurrent tasks that could be executed in
parallel. It can be altered at runtime.

-------------------------------------------------------
<a name="paused"></a>
### queue.paused

Property (Read-Only) that returns `true` when the queue is in a paused state.

-------------------------------------------------------
<a name="drain"></a>
### queue.drain

Function that will be called when the last
item from the queue has been processed by a worker.
It can be altered at runtime.

-------------------------------------------------------
<a name="empty"></a>
### queue.empty

Function that will be called when the last
item from the queue has been assigned to a worker.
It can be altered at runtime.

-------------------------------------------------------
<a name="saturated"></a>
### queue.saturated

Function that will be called when the queue hits the concurrency
limit.
It can be altered at runtime.

-------------------------------------------------------
<a name="promise"></a>
### fastqueue.promise([that], worker(arg), concurrency)

Creates a new queue with `Promise` apis. It also offers all the methods
and properties of the object returned by [`fastqueue`](#fastqueue) with the modified
[`push`](#pushPromise) and [`unshift`](#unshiftPromise) methods.

Node v10+ is required to use the promisified version.

Arguments:
* `that`, optional context of the `worker` function.
* `worker`, worker function, it would be called with `that` as `this`,
  if that is specified. It MUST return a `Promise`.
* `concurrency`, number of concurrent tasks that could be executed in
  parallel.

<a name="pushPromise"></a>
#### queue.push(task) => Promise

Add a task at the end of the queue. The returned `Promise`  will be fulfilled (rejected)
when the task is completed successfully (unsuccessfully).

This promise could be ignored as it will not lead to a `'unhandledRejection'`.

<a name="unshiftPromise"></a>
#### queue.unshift(task) => Promise

Add a task at the beginning of the queue. The returned `Promise`  will be fulfilled (rejected)
when the task is completed successfully (unsuccessfully).

This promise could be ignored as it will not lead to a `'unhandledRejection'`.

<a name="drained"></a>
#### queue.drained() => Promise

Wait for the queue to be drained. The returned `Promise` will be resolved when all tasks in the queue have been processed by a worker.

This promise could be ignored as it will not lead to a `'unhandledRejection'`.

## License

ISC

[ci-url]: https://github.com/mcollina/fastq/workflows/ci/badge.svg
[npm-badge]: https://badge.fury.io/js/fastq.svg
[npm-url]: https://badge.fury.io/js/fastq


---

# Security Policy

## Supported Versions

Use this section to tell people about which versions of your project are
currently being supported with security updates.

| Version | Supported          |
| ------- | ------------------ |
| 1.x     | :white_check_mark: |
| < 1.0   | :x:                |

## Reporting a Vulnerability

Please report all vulnerabilities at [https://github.com/mcollina/fastq/security](https://github.com/mcollina/fastq/security).


---

# fault

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]

Functional errors with formatted output.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`fault(format?[, values…])`](#faultformat-values)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Security](#security)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package adds printf-like interpolation to errors.

## When should I use this?

This package useful when you frequently display parameters in error messages
and manual string concatenation is becoming verbose.

## Install

This package is [ESM only][esm].
In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]:

```sh
npm install fault
```

In Deno with [Skypack][]:

```js
import {fault} from 'https://cdn.skypack.dev/fault@2?dts'
```

In browsers with [Skypack][]:

```html
<script type="module">
  import {fault} from 'https://cdn.skypack.dev/fault@2?min'
</script>
```

## Use

```js
import {fault} from 'fault'

throw fault('Hello %s!', 'Eric')
```

Yields:

```text
Error: Hello Eric!
    at FormattedError (~/node_modules/fault/index.js:30:12)
    at Object.<anonymous> (~/example.js:3:7)
    …
```

Or, format a float in a type error:

```js
import {fault} from 'fault'

throw fault.type('Who doesn’t like %f? 🍰', Math.PI)
```

Yields:

```text
TypeError: Who doesn’t like 3.141593? 🍰
    at Function.FormattedError [as type] (~/node_modules/fault/index.js:30:12)
    at Object.<anonymous> (~/example.js:3:7)
```

## API

This package exports the following identifiers: `fault` and `create`.
There is no default export.

### `fault(format?[, values…])`

Create an error with a printf-like formatted message.

###### Parameters

*   `format` (`string`, optional)
    — template string
*   `values` (`*`, optional)
    — values to render in `format`

###### Returns

An [`Error`][error] instance.

###### Formatters

The following formatters are supported in `format`:

*   `%s` — string
*   `%b` — binary
*   `%c` — character
*   `%d` — decimal
*   `%f` — floating point
*   `%o` — octal
*   `%x` — lowercase hexadecimal
*   `%X` — uppercase hexadecimal
*   `%` followed by any other character, prints that character

See [`samsonjs/format`][fmt] for argument parsing.

###### Other errors

*   `fault.eval(format?[, values…])` — [EvalError][]
*   `fault.range(format?[, values…])` — [RangeError][]
*   `fault.reference(format?[, values…])` — [ReferenceError][]
*   `fault.syntax(format?[, values…])` — [SyntaxError][]
*   `fault.type(format?[, values…])` — [TypeError][]
*   `fault.uri(format?[, values…])` — [URIError][]

#### `create(Constructor)`

Factory to create instances of `ErrorConstructor` with support for formatting.
Used internally to wrap the global error constructors and exposed for custom
errors.
Returns a function just like `fault`.

## Types

This package is fully typed with [TypeScript][].
There are no extra exported types.

## Compatibility

This package is at least compatible with all maintained versions of Node.js.
As of now, that is Node.js 12.20+, 14.14+, and 16.0+.
It also works in Deno and modern browsers.

## Security

This package is safe.

## Related

*   [`wooorm/bail`](https://github.com/wooorm/bail)
    — throw if given an error

## Contribute

Yes please!
See [How to Contribute to Open Source][contribute].

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/wooorm/fault/workflows/main/badge.svg

[build]: https://github.com/wooorm/fault/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/fault.svg

[coverage]: https://codecov.io/github/wooorm/fault

[downloads-badge]: https://img.shields.io/npm/dm/fault.svg

[downloads]: https://www.npmjs.com/package/fault

[size-badge]: https://img.shields.io/bundlephobia/minzip/fault.svg

[size]: https://bundlephobia.com/result?p=fault

[npm]: https://docs.npmjs.com/cli/install

[skypack]: https://www.skypack.dev

[license]: license

[author]: https://wooorm.com

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[typescript]: https://www.typescriptlang.org

[contribute]: https://opensource.guide/how-to-contribute/

[fmt]: https://github.com/samsonjs/format

[error]: https://developer.mozilla.org/JavaScript/Reference/Global_Objects/Error

[evalerror]: https://developer.mozilla.org/JavaScript/Reference/Global_Objects/EvalError

[rangeerror]: https://developer.mozilla.org/JavaScript/Reference/Global_Objects/RangeError

[referenceerror]: https://developer.mozilla.org/JavaScript/Reference/Global_Objects/ReferenceError

[syntaxerror]: https://developer.mozilla.org/JavaScript/Reference/Global_Objects/SyntaxError

[typeerror]: https://developer.mozilla.org/JavaScript/Reference/Global_Objects/TypeError

[urierror]: https://developer.mozilla.org/JavaScript/Reference/Global_Objects/URIError.


---

### 0.11.4 / 2021-05-24

- Prevent the client hanging if `close()` is called when already closing

### 0.11.3 / 2019-06-10

- Fix a race condition that caused a timeout not to be cancelled immediately
  when the WebSocket is closed
- Change license from MIT to Apache 2.0

### 0.11.2 / 2019-06-10

(This version was pulled due to an error when publishing)

### 0.11.1 / 2017-01-22

- Forcibly close the I/O stream after a timeout if the peer does not respond
  after calling `close()`

### 0.11.0 / 2016-02-24

- Introduce a `net` option to the `Client` class for setting things like, say,
  `servername`

### 0.10.0 / 2015-07-08

- Add the standard `code` and `reason` parameters to the `close` method

### 0.9.4 / 2015-03-08

- Don't send input to the driver before `start()` is called

### 0.9.3 / 2015-02-19

- Make sure the TCP socket is not left open when closing the connection

### 0.9.2 / 2014-12-21

- Only emit `error` once, and don't emit it after `close`

### 0.9.1 / 2014-12-18

- Check that all options to the WebSocket constructor are recognized

### 0.9.0 / 2014-12-13

- Allow protocol extensions to be passed into websocket-extensions

### 0.8.1 / 2014-11-12

- Send the correct hostname when upgrading a connection to TLS

### 0.8.0 / 2014-11-08

- Support connections via HTTP proxies
- Close the connection cleanly if we're still waiting for a handshake response

### 0.7.3 / 2014-10-04

- Allow sockets to be closed when they are in any state other than `CLOSED`

### 0.7.2 / 2013-12-29

- Make sure the `close` event is emitted by clients on Node v0.10

### 0.7.1 / 2013-12-03

- Support the `maxLength` websocket-driver option
- Make the client emit `error` events on network errors

### 0.7.0 / 2013-09-09

- Allow the server to send custom headers with EventSource responses

### 0.6.1 / 2013-07-05

- Add `ca` option to the client for specifying certificate authorities
- Start the server driver asynchronously so that `onopen` handlers can be added

### 0.6.0 / 2013-05-12

- Add support for custom headers

### 0.5.0 / 2013-05-05

- Extract the protocol handlers into the `websocket-driver` library
- Support the Node streaming API

### 0.4.4 / 2013-02-14

- Emit the `close` event if TCP is closed before CLOSE frame is acked

### 0.4.3 / 2012-07-09

- Add `Connection: close` to EventSource response
- Handle situations where `request.socket` is undefined

### 0.4.2 / 2012-04-06

- Add WebSocket error code `1011`.
- Handle URLs with no path correctly by sending `GET /`

### 0.4.1 / 2012-02-26

- Treat anything other than a `Buffer` as a string when calling `send()`

### 0.4.0 / 2012-02-13

- Add `ping()` method to server-side `WebSocket` and `EventSource`
- Buffer `send()` calls until the draft-76 handshake is complete
- Fix HTTPS problems on Node 0.7

### 0.3.1 / 2012-01-16

- Call `setNoDelay(true)` on `net.Socket` objects to reduce latency

### 0.3.0 / 2012-01-13

- Add support for `EventSource` connections

### 0.2.0 / 2011-12-21

- Add support for `Sec-WebSocket-Protocol` negotiation
- Support `hixie-76` close frames and 75/76 ignored segments
- Improve performance of HyBi parsing/framing functions
- Decouple parsers from TCP and reduce write volume

### 0.1.2 / 2011-12-05

- Detect closed sockets on the server side when TCP connection breaks
- Make `hixie-76` sockets work through HAProxy

### 0.1.1 / 2011-11-30

- Fix `addEventListener()` interface methods

### 0.1.0 / 2011-11-27

- Initial release, based on WebSocket components from Faye


---

Copyright 2010-2021 James Coglan

Licensed under the Apache License, Version 2.0 (the "License"); you may not use
this file except in compliance with the License. You may obtain a copy of the
License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed
under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
CONDITIONS OF ANY KIND, either express or implied. See the License for the
specific language governing permissions and limitations under the License.


---

# faye-websocket

This is a general-purpose WebSocket implementation extracted from the
[Faye](http://faye.jcoglan.com) project. It provides classes for easily building
WebSocket servers and clients in Node. It does not provide a server itself, but
rather makes it easy to handle WebSocket connections within an existing
[Node](https://nodejs.org/) application. It does not provide any abstraction
other than the standard [WebSocket
API](https://html.spec.whatwg.org/multipage/comms.html#network).

It also provides an abstraction for handling
[EventSource](https://html.spec.whatwg.org/multipage/comms.html#server-sent-events)
connections, which are one-way connections that allow the server to push data to
the client. They are based on streaming HTTP responses and can be easier to access
via proxies than WebSockets.


## Installation

```
$ npm install faye-websocket
```


## Handling WebSocket connections in Node

You can handle WebSockets on the server side by listening for HTTP Upgrade
requests, and creating a new socket for the request. This socket object exposes
the usual WebSocket methods for receiving and sending messages. For example this
is how you'd implement an echo server:

```js
var WebSocket = require('faye-websocket'),
    http      = require('http');

var server = http.createServer();

server.on('upgrade', function(request, socket, body) {
  if (WebSocket.isWebSocket(request)) {
    var ws = new WebSocket(request, socket, body);

    ws.on('message', function(event) {
      ws.send(event.data);
    });

    ws.on('close', function(event) {
      console.log('close', event.code, event.reason);
      ws = null;
    });
  }
});

server.listen(8000);
```

`WebSocket` objects are also duplex streams, so you could replace the
`ws.on('message', ...)` line with:

```js
    ws.pipe(ws);
```

Note that under certain circumstances (notably a draft-76 client connecting
through an HTTP proxy), the WebSocket handshake will not be complete after you
call `new WebSocket()` because the server will not have received the entire
handshake from the client yet. In this case, calls to `ws.send()` will buffer
the message in memory until the handshake is complete, at which point any
buffered messages will be sent to the client.

If you need to detect when the WebSocket handshake is complete, you can use the
`onopen` event.

If the connection's protocol version supports it, you can call `ws.ping()` to
send a ping message and wait for the client's response. This method takes a
message string, and an optional callback that fires when a matching pong message
is received. It returns `true` if and only if a ping message was sent. If the
client does not support ping/pong, this method sends no data and returns
`false`.

```js
ws.ping('Mic check, one, two', function() {
  // fires when pong is received
});
```


## Using the WebSocket client

The client supports both the plain-text `ws` protocol and the encrypted `wss`
protocol, and has exactly the same interface as a socket you would use in a web
browser. On the wire it identifies itself as `hybi-13`.

```js
var WebSocket = require('faye-websocket'),
    ws        = new WebSocket.Client('ws://www.example.com/');

ws.on('open', function(event) {
  console.log('open');
  ws.send('Hello, world!');
});

ws.on('message', function(event) {
  console.log('message', event.data);
});

ws.on('close', function(event) {
  console.log('close', event.code, event.reason);
  ws = null;
});
```

The WebSocket client also lets you inspect the status and headers of the
handshake response via its `statusCode` and `headers` properties.

To connect via a proxy, set the `proxy` option to the HTTP origin of the proxy,
including any authorization information, custom headers and TLS config you
require. Only the `origin` setting is required.

```js
var ws = new WebSocket.Client('ws://www.example.com/', [], {
  proxy: {
    origin:  'http://username:password@proxy.example.com',
    headers: { 'User-Agent': 'node' },
    tls:     { cert: fs.readFileSync('client.crt') }
  }
});
```

The `tls` value is an object that will be passed to
[`tls.connect()`](https://nodejs.org/api/tls.html#tls_tls_connect_options_callback).


## Subprotocol negotiation

The WebSocket protocol allows peers to select and identify the application
protocol to use over the connection. On the client side, you can set which
protocols the client accepts by passing a list of protocol names when you
construct the socket:

```js
var ws = new WebSocket.Client('ws://www.example.com/', ['irc', 'amqp']);
```

On the server side, you can likewise pass in the list of protocols the server
supports after the other constructor arguments:

```js
var ws = new WebSocket(request, socket, body, ['irc', 'amqp']);
```

If the client and server agree on a protocol, both the client- and server-side
socket objects expose the selected protocol through the `ws.protocol` property.


## Protocol extensions

faye-websocket is based on the
[websocket-extensions](https://github.com/faye/websocket-extensions-node)
framework that allows extensions to be negotiated via the
`Sec-WebSocket-Extensions` header. To add extensions to a connection, pass an
array of extensions to the `:extensions` option. For example, to add
[permessage-deflate](https://github.com/faye/permessage-deflate-node):

```js
var deflate = require('permessage-deflate');

var ws = new WebSocket(request, socket, body, [], { extensions: [deflate] });
```


## Initialization options

Both the server- and client-side classes allow an options object to be passed in
at initialization time, for example:

```js
var ws = new WebSocket(request, socket, body, protocols, options);
var ws = new WebSocket.Client(url, protocols, options);
```

`protocols` is an array of subprotocols as described above, or `null`.
`options` is an optional object containing any of these fields:

- `extensions` - an array of
  [websocket-extensions](https://github.com/faye/websocket-extensions-node)
  compatible extensions, as described above
- `headers` - an object containing key-value pairs representing HTTP headers to
  be sent during the handshake process
- `maxLength` - the maximum allowed size of incoming message frames, in bytes.
  The default value is `2^26 - 1`, or 1 byte short of 64 MiB.
- `ping` - an integer that sets how often the WebSocket should send ping frames,
  measured in seconds

The client accepts some additional options:

- `proxy` - settings for a proxy as described above
- `net` - an object containing settings for the origin server that will be
  passed to
  [`net.connect()`](https://nodejs.org/api/net.html#net_socket_connect_options_connectlistener)
- `tls` - an object containing TLS settings for the origin server, this will be
  passed to
  [`tls.connect()`](https://nodejs.org/api/tls.html#tls_tls_connect_options_callback)
- `ca` - (legacy) a shorthand for passing `{ tls: { ca: value } }`


## WebSocket API

Both server- and client-side `WebSocket` objects support the following API.

- **`on('open', function(event) {})`** fires when the socket connection is
  established. Event has no attributes.
- **`on('message', function(event) {})`** fires when the socket receives a
  message. Event has one attribute, **`data`**, which is either a `String` (for
  text frames) or a `Buffer` (for binary frames).
- **`on('error', function(event) {})`** fires when there is a protocol error due
  to bad data sent by the other peer. This event is purely informational, you do
  not need to implement error recover.
- **`on('close', function(event) {})`** fires when either the client or the
  server closes the connection. Event has two optional attributes, **`code`**
  and **`reason`**, that expose the status code and message sent by the peer
  that closed the connection.
- **`send(message)`** accepts either a `String` or a `Buffer` and sends a text
  or binary message over the connection to the other peer.
- **`ping(message, function() {})`** sends a ping frame with an optional message
  and fires the callback when a matching pong is received.
- **`close(code, reason)`** closes the connection, sending the given status code
  and reason text, both of which are optional.
- **`version`** is a string containing the version of the `WebSocket` protocol
  the connection is using.
- **`protocol`** is a string (which may be empty) identifying the subprotocol
  the socket is using.


## Handling EventSource connections in Node

EventSource connections provide a very similar interface, although because they
only allow the server to send data to the client, there is no `onmessage` API.
EventSource allows the server to push text messages to the client, where each
message has an optional event-type and ID.

```js
var WebSocket   = require('faye-websocket'),
    EventSource = WebSocket.EventSource,
    http        = require('http');

var server = http.createServer();

server.on('request', function(request, response) {
  if (EventSource.isEventSource(request)) {
    var es = new EventSource(request, response);
    console.log('open', es.url, es.lastEventId);

    // Periodically send messages
    var loop = setInterval(function() { es.send('Hello') }, 1000);

    es.on('close', function() {
      clearInterval(loop);
      es = null;
    });

  } else {
    // Normal HTTP request
    response.writeHead(200, { 'Content-Type': 'text/plain' });
    response.end('Hello');
  }
});

server.listen(8000);
```

The `send` method takes two optional parameters, `event` and `id`. The default
event-type is `'message'` with no ID. For example, to send a `notification`
event with ID `99`:

```js
es.send('Breaking News!', { event: 'notification', id: '99' });
```

The `EventSource` object exposes the following properties:

- **`url`** is a string containing the URL the client used to create the
  EventSource.
- **`lastEventId`** is a string containing the last event ID received by the
  client. You can use this when the client reconnects after a dropped connection
  to determine which messages need resending.

When you initialize an EventSource with ` new EventSource()`, you can pass
configuration options after the `response` parameter. Available options are:

- **`headers`** is an object containing custom headers to be set on the
  EventSource response.
- **`retry`** is a number that tells the client how long (in seconds) it should
  wait after a dropped connection before attempting to reconnect.
- **`ping`** is a number that tells the server how often (in seconds) to send
  'ping' packets to the client to keep the connection open, to defeat timeouts
  set by proxies. The client will ignore these messages.

For example, this creates a connection that allows access from any origin, pings
every 15 seconds and is retryable every 10 seconds if the connection is broken:

```js
var es = new EventSource(request, response, {
  headers: { 'Access-Control-Allow-Origin': '*' },
  ping:    15,
  retry:   10
});
```

You can send a ping message at any time by calling `es.ping()`. Unlike
WebSocket, the client does not send a response to this; it is merely to send
some data over the wire to keep the connection alive.


---

---
name: Bug report
about: Create a report to help us improve

---

**Describe the bug**
A clear and concise description of what the bug is.

**To Reproduce**
Steps to reproduce the behavior:
1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error

**Expected behavior**
A clear and concise description of what you expected to happen.

**Actual behavior**
A clear and concise description of what is the actual outcome.

**Screenshots**
If applicable, add screenshots to help explain your problem.

**Versions (please complete the following information):**
 - NodeJS: 
 - TypeScript:
 - npm/yarn:
 - feed:

**Additional context**
Add any other context about the problem here.


---

---
name: Feature request
about: Suggest an idea for this project

---

**Is your feature request related to a problem? Please describe.**
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

**Describe the solution you'd like**
A clear and concise description of what you want to happen.

**Describe alternatives you've considered**
A clear and concise description of any alternative solutions or features you've considered.

**Additional context**
Add any other context or screenshots about the feature request here. Also make sure to add any documentation related.


---

# Change Log

## [4.2.2](https://github.com/jpmonette/feed/tree/4.2.2) (2021-01-22)
[Full Changelog](https://github.com/jpmonette/feed/compare/4.2.1...4.2.2)

**Implemented enhancements:**

- Export types in feed [\#128](https://github.com/jpmonette/feed/issues/128)

**Merged pull requests:**

- Bump node-notifier from 8.0.0 to 8.0.1 [\#137](https://github.com/jpmonette/feed/pull/137) ([dependabot[bot]](https://github.com/apps/dependabot))
- fix: export types from feed [\#136](https://github.com/jpmonette/feed/pull/136) ([gustavkj](https://github.com/gustavkj))
- Bump deps [\#129](https://github.com/jpmonette/feed/pull/129) ([jpmonette](https://github.com/jpmonette))
- Bump lodash from 4.17.15 to 4.17.19 [\#127](https://github.com/jpmonette/feed/pull/127) ([dependabot[bot]](https://github.com/apps/dependabot))

## [4.2.1](https://github.com/jpmonette/feed/tree/4.2.1) (2020-07-05)
[Full Changelog](https://github.com/jpmonette/feed/compare/4.2.0...4.2.1)

**Closed issues:**

- RSS pubDate set to "date" rather than "published", unlike Atom [\#117](https://github.com/jpmonette/feed/issues/117)

**Merged pull requests:**

- Sanitizing XML feeds [\#125](https://github.com/jpmonette/feed/pull/125) ([decebal](https://github.com/decebal))
- author.uri and author.email should be optional in atom \#115 [\#124](https://github.com/jpmonette/feed/pull/124) ([decebal](https://github.com/decebal))
- fix: 🐛 overwrite pubDate on rss when published is specified [\#121](https://github.com/jpmonette/feed/pull/121) ([decebal](https://github.com/decebal))

## [4.2.0](https://github.com/jpmonette/feed/tree/4.2.0) (2020-05-25)
[Full Changelog](https://github.com/jpmonette/feed/compare/4.1.0...4.2.0)

**Closed issues:**

- Getting an error during Netlify deploy \(and npm run build\) [\#118](https://github.com/jpmonette/feed/issues/118)
- atom:link in RSS feed should point to self, not atom [\#113](https://github.com/jpmonette/feed/issues/113)

**Merged pull requests:**

- Update dependencies + Formatting + Add Comments [\#123](https://github.com/jpmonette/feed/pull/123) ([jpmonette](https://github.com/jpmonette))
- fix: 🐛 atom link needs to point to self [\#122](https://github.com/jpmonette/feed/pull/122) ([decebal](https://github.com/decebal))
- feat: 🎸 add mandatory rss2 attributes on enclosure [\#120](https://github.com/jpmonette/feed/pull/120) ([decebal](https://github.com/decebal))
- Bump acorn from 5.7.3 to 5.7.4 [\#116](https://github.com/jpmonette/feed/pull/116) ([dependabot[bot]](https://github.com/apps/dependabot))

## [4.1.0](https://github.com/jpmonette/feed/tree/4.1.0) (2019-12-29)
[Full Changelog](https://github.com/jpmonette/feed/compare/4.0.0...4.1.0)

**Closed issues:**

- Update the default of date on atom to be published [\#108](https://github.com/jpmonette/feed/issues/108)
- export base xml-js object [\#102](https://github.com/jpmonette/feed/issues/102)
- Add extra attributes on \<rss\> tag [\#98](https://github.com/jpmonette/feed/issues/98)
- item.id is ignored in rss output [\#96](https://github.com/jpmonette/feed/issues/96)
- How to generate \<dc:creator\> [\#90](https://github.com/jpmonette/feed/issues/90)
- Specify namespace and custom attributes [\#88](https://github.com/jpmonette/feed/issues/88)

**Merged pull requests:**

- Bump handlebars from 4.1.2 to 4.5.3 [\#110](https://github.com/jpmonette/feed/pull/110) ([dependabot[bot]](https://github.com/apps/dependabot))
- Item category for all feed types [\#109](https://github.com/jpmonette/feed/pull/109) ([mattimbrain](https://github.com/mattimbrain))
- Bump lodash from 4.17.11 to 4.17.15 [\#106](https://github.com/jpmonette/feed/pull/106) ([dependabot[bot]](https://github.com/apps/dependabot))
- Fix RSS ignoring item.id [\#105](https://github.com/jpmonette/feed/pull/105) ([ArtskydJ](https://github.com/ArtskydJ))
- Change default RSS docs url + Allow docs override [\#97](https://github.com/jpmonette/feed/pull/97) ([sonniesedge](https://github.com/sonniesedge))

## [4.0.0](https://github.com/jpmonette/feed/tree/4.0.0) (2019-07-06)
[Full Changelog](https://github.com/jpmonette/feed/compare/3.0.0...4.0.0)

**Merged pull requests:**

- Push to 4.0.0 [\#95](https://github.com/jpmonette/feed/pull/95) ([jpmonette](https://github.com/jpmonette))
- Update homepage to github repo [\#92](https://github.com/jpmonette/feed/pull/92) ([kevinsimper](https://github.com/kevinsimper))

## [3.0.0](https://github.com/jpmonette/feed/tree/3.0.0) (2019-05-28)
[Full Changelog](https://github.com/jpmonette/feed/compare/2.0.4...3.0.0)

**Merged pull requests:**

- Migrate from xml to xml-js [\#93](https://github.com/jpmonette/feed/pull/93) ([jpmonette](https://github.com/jpmonette))
- Migrate from xml to xml-js [\#91](https://github.com/jpmonette/feed/pull/91) ([jpmonette](https://github.com/jpmonette))

## [2.0.4](https://github.com/jpmonette/feed/tree/2.0.4) (2019-03-02)
[Full Changelog](https://github.com/jpmonette/feed/compare/2.0.0...2.0.4)

**Implemented enhancements:**

- Feed support for Category on Items [\#71](https://github.com/jpmonette/feed/issues/71)

**Closed issues:**

- TypeError: Feed is not a constructor [\#80](https://github.com/jpmonette/feed/issues/80)
- Example Code, `posts` Undefined [\#78](https://github.com/jpmonette/feed/issues/78)
- npm package broken [\#77](https://github.com/jpmonette/feed/issues/77)
- Cannot display the publish time of essay correctly. [\#67](https://github.com/jpmonette/feed/issues/67)
- Feedly.com not accepting it [\#62](https://github.com/jpmonette/feed/issues/62)
- TypeError: d.getUTCFullYear is not a function [\#59](https://github.com/jpmonette/feed/issues/59)
- Extra properties [\#57](https://github.com/jpmonette/feed/issues/57)
- Support paged feeds [\#52](https://github.com/jpmonette/feed/issues/52)
- RSS author is still \(again\) broken [\#50](https://github.com/jpmonette/feed/issues/50)
- writing feed as a stream of articles \[feature request\] [\#44](https://github.com/jpmonette/feed/issues/44)
- New line is not transformed to \<BR\> [\#42](https://github.com/jpmonette/feed/issues/42)
- I would like to provide some custom namespace for my item nodes [\#38](https://github.com/jpmonette/feed/issues/38)
- Missing 'type="image/\*"' attribute for image enclosures [\#37](https://github.com/jpmonette/feed/issues/37)
- How to append items to an existing RSS-2.0 Feed [\#33](https://github.com/jpmonette/feed/issues/33)
- Namespace prefix content on encoded is not defined [\#32](https://github.com/jpmonette/feed/issues/32)
- support for multiple enclosures in one item? [\#31](https://github.com/jpmonette/feed/issues/31)

**Merged pull requests:**

- add optional language field [\#86](https://github.com/jpmonette/feed/pull/86) ([zsolt-dev](https://github.com/zsolt-dev))
- Make `feed` option optional [\#85](https://github.com/jpmonette/feed/pull/85) ([Vinnl](https://github.com/Vinnl))
- Change html\_content to content\_html [\#81](https://github.com/jpmonette/feed/pull/81) ([leereamsnyder](https://github.com/leereamsnyder))
- Fix TypeScript declarations [\#73](https://github.com/jpmonette/feed/pull/73) ([lenovouser](https://github.com/lenovouser))

## [2.0.0](https://github.com/jpmonette/feed/tree/2.0.0) (2018-08-04)
[Full Changelog](https://github.com/jpmonette/feed/compare/1.1.0...2.0.0)

**Closed issues:**

- Items in feed not added image property [\#63](https://github.com/jpmonette/feed/issues/63)

**Merged pull requests:**

- We are moving to TypeScript! [\#72](https://github.com/jpmonette/feed/pull/72) ([jpmonette](https://github.com/jpmonette))
- Remove octal number from example [\#70](https://github.com/jpmonette/feed/pull/70) ([manniL](https://github.com/manniL))
- Push to version 1.1.1 [\#66](https://github.com/jpmonette/feed/pull/66) ([jpmonette](https://github.com/jpmonette))
- fix\(images\): Fixes image enclosures for items [\#65](https://github.com/jpmonette/feed/pull/65) ([zfoster](https://github.com/zfoster))
- add support for extensions in json1 [\#60](https://github.com/jpmonette/feed/pull/60) ([alx](https://github.com/alx))

## [1.1.0](https://github.com/jpmonette/feed/tree/1.1.0) (2017-06-03)
[Full Changelog](https://github.com/jpmonette/feed/compare/1.0.1...1.1.0)

**Closed issues:**

- \</link\> stripped out [\#53](https://github.com/jpmonette/feed/issues/53)
- "updated" broken [\#51](https://github.com/jpmonette/feed/issues/51)
- validateURL is not nice function [\#23](https://github.com/jpmonette/feed/issues/23)

**Merged pull requests:**

- Version 1.1.0 [\#58](https://github.com/jpmonette/feed/pull/58) ([jpmonette](https://github.com/jpmonette))
- Add Support for JSON Feed v1 [\#56](https://github.com/jpmonette/feed/pull/56) ([benmccormick](https://github.com/benmccormick))
- Add custom generator string options.generator [\#55](https://github.com/jpmonette/feed/pull/55) ([VarunBatraIT](https://github.com/VarunBatraIT))

## [1.0.1](https://github.com/jpmonette/feed/tree/1.0.1) (2017-04-02)
**Implemented enhancements:**

- Allow for manual setting of the feed updated date [\#14](https://github.com/jpmonette/feed/issues/14)
- Readme should mention missing stuff [\#3](https://github.com/jpmonette/feed/issues/3)
- Tests [\#2](https://github.com/jpmonette/feed/issues/2)
- Author fields in feed items? [\#1](https://github.com/jpmonette/feed/issues/1)

**Fixed bugs:**

- Forgot a "console.log" [\#5](https://github.com/jpmonette/feed/issues/5)

**Closed issues:**

- Cut a new release [\#47](https://github.com/jpmonette/feed/issues/47)
- RSS author tag for each post should contain only email [\#41](https://github.com/jpmonette/feed/issues/41)
- URL in repo description is a dead link [\#36](https://github.com/jpmonette/feed/issues/36)
- Lots of commits missing in npm [\#35](https://github.com/jpmonette/feed/issues/35)
- AppFog 404 Not Found [\#20](https://github.com/jpmonette/feed/issues/20)
- Generated Atom feed has a few problems according to validator [\#19](https://github.com/jpmonette/feed/issues/19)
- content encoding [\#17](https://github.com/jpmonette/feed/issues/17)
- TypeError: Object July 21, 1983 01:15:00 has no method 'toUTCString' [\#11](https://github.com/jpmonette/feed/issues/11)
- The code breaks when atom feed is requested [\#8](https://github.com/jpmonette/feed/issues/8)
- Author email and link should be optional [\#6](https://github.com/jpmonette/feed/issues/6)

**Merged pull requests:**

- Initial Babel migration commit [\#49](https://github.com/jpmonette/feed/pull/49) ([jpmonette](https://github.com/jpmonette))
- Resolves \#41 - Fix “author” tag based on W3 Validator [\#48](https://github.com/jpmonette/feed/pull/48) ([jpmonette](https://github.com/jpmonette))
- fixed the failing test due to date provided [\#45](https://github.com/jpmonette/feed/pull/45) ([parit](https://github.com/parit))
- Update package.json [\#43](https://github.com/jpmonette/feed/pull/43) ([f0rr0](https://github.com/f0rr0))
- Feed id is required. Demonstrate that in README [\#39](https://github.com/jpmonette/feed/pull/39) ([KyleAMathews](https://github.com/KyleAMathews))
- Support for the entry\#published attribute [\#34](https://github.com/jpmonette/feed/pull/34) ([benilovj](https://github.com/benilovj))
- Validation fixes [\#26](https://github.com/jpmonette/feed/pull/26) ([download13](https://github.com/download13))
- disable url validation [\#24](https://github.com/jpmonette/feed/pull/24) ([bewest](https://github.com/bewest))
- feed.item\(\) is deprecated [\#18](https://github.com/jpmonette/feed/pull/18) ([KyleAMathews](https://github.com/KyleAMathews))
- adding contributors and copyright for atom [\#12](https://github.com/jpmonette/feed/pull/12) ([shafan](https://github.com/shafan))
- Updates to better pass the W3C validator, and other improvements [\#10](https://github.com/jpmonette/feed/pull/10) ([smebberson](https://github.com/smebberson))
- Fixed iterator bug [\#9](https://github.com/jpmonette/feed/pull/9) ([brickcap](https://github.com/brickcap))
- here's my change to ensure array iteration works even if arrays have other properties [\#7](https://github.com/jpmonette/feed/pull/7) ([haszari](https://github.com/haszari))



\* *This Change Log was automatically generated by [github_changelog_generator](https://github.com/skywinder/Github-Changelog-Generator)*

---

# Code of Conduct

## 1. Purpose

A primary goal of Feed is to be inclusive to the largest number of contributors, with the most varied and diverse backgrounds possible. As such, we are committed to providing a friendly, safe and welcoming environment for all, regardless of gender, sexual orientation, ability, ethnicity, socioeconomic status, and religion (or lack thereof).

This code of conduct outlines our expectations for all those who participate in our community, as well as the consequences for unacceptable behavior.

We invite all those who participate in Feed to help us create safe and positive experiences for everyone.

## 2. Open Source Citizenship

A supplemental goal of this Code of Conduct is to increase open source citizenship by encouraging participants to recognize and strengthen the relationships between our actions and their effects on our community.

Communities mirror the societies in which they exist and positive action is essential to counteract the many forms of inequality and abuses of power that exist in society.

If you see someone who is making an extra effort to ensure our community is welcoming, friendly, and encourages all participants to contribute to the fullest extent, we want to know.

## 3. Expected Behavior

The following behaviors are expected and requested of all community members:

*   Participate in an authentic and active way. In doing so, you contribute to the health and longevity of this community.
*   Exercise consideration and respect in your speech and actions.
*   Attempt collaboration before conflict.
*   Refrain from demeaning, discriminatory, or harassing behavior and speech.
*   Be mindful of your surroundings and of your fellow participants. Alert community leaders if you notice a dangerous situation, someone in distress, or violations of this Code of Conduct, even if they seem inconsequential.
*   Remember that community event venues may be shared with members of the public; please be respectful to all patrons of these locations.

## 4. Unacceptable Behavior

The following behaviors are considered harassment and are unacceptable within our community:

*   Violence, threats of violence or violent language directed against another person.
*   Sexist, racist, homophobic, transphobic, ableist or otherwise discriminatory jokes and language.
*   Posting or displaying sexually explicit or violent material.
*   Posting or threatening to post other people’s personally identifying information ("doxing").
*   Personal insults, particularly those related to gender, sexual orientation, race, religion, or disability.
*   Inappropriate photography or recording.
*   Inappropriate physical contact. You should have someone’s consent before touching them.
*   Unwelcome sexual attention. This includes, sexualized comments or jokes; inappropriate touching, groping, and unwelcomed sexual advances.
*   Deliberate intimidation, stalking or following (online or in person).
*   Advocating for, or encouraging, any of the above behavior.
*   Sustained disruption of community events, including talks and presentations.

## 5. Consequences of Unacceptable Behavior

Unacceptable behavior from any community member, including sponsors and those with decision-making authority, will not be tolerated.

Anyone asked to stop unacceptable behavior is expected to comply immediately.

If a community member engages in unacceptable behavior, the community organizers may take any action they deem appropriate, up to and including a temporary ban or permanent expulsion from the community without warning (and without refund in the case of a paid event).

## 6. Reporting Guidelines

If you are subject to or witness unacceptable behavior, or have any other concerns, please notify a community organizer as soon as possible. contact@jpmonette.net.



Additionally, community organizers are available to help community members engage with local law enforcement or to otherwise help those experiencing unacceptable behavior feel safe. In the context of in-person events, organizers will also provide escorts as desired by the person experiencing distress.

## 7. Addressing Grievances

If you feel you have been falsely or unfairly accused of violating this Code of Conduct, you should notify Jean-Philippe Monette with a concise description of your grievance. Your grievance will be handled in accordance with our existing governing policies.



## 8. Scope

We expect all community participants (contributors, paid or otherwise; sponsors; and other guests) to abide by this Code of Conduct in all community venues–online and in-person–as well as in all one-on-one communications pertaining to community business.

This code of conduct and its related procedures also applies to unacceptable behavior occurring outside the scope of community activities when such behavior has the potential to adversely affect the safety and well-being of community members.

## 9. Contact info

contact@jpmonette.net

## 10. License and attribution

This Code of Conduct is distributed under a [Creative Commons Attribution-ShareAlike license](http://creativecommons.org/licenses/by-sa/3.0/).

Portions of text derived from the [Django Code of Conduct](https://www.djangoproject.com/conduct/) and the [Geek Feminism Anti-Harassment Policy](http://geekfeminism.wikia.com/wiki/Conference_anti-harassment/Policy).

Retrieved on November 22, 2016 from [http://citizencodeofconduct.org/](http://citizencodeofconduct.org/)


---

# How to contribute

We'd love to accept your patches and contributions to this project. There are a just a few small guidelines you need to follow.

## Submitting a patch

1. It's generally best to start by opening a new issue describing the bug or
   feature you're intending to fix. Even if you think it's relatively minor,
   it's helpful to know what people are working on. Mention in the initial
   issue that you are planning to work on that bug or feature so that it can
   be assigned to you.

2. Considering each syndication client seem to have their own specificities, make
   sure you provide enough information about the client in question if you want
   to add new elements or update existing ones. Link to their official documentation
   and provide examples.

3. Create and run tests. Your new addition must be covered by unit tests.

4. Follow the normal process of [forking][] the project, and setup a new
   branch to work in.

5. Do your best to have [well-formed commit messages][] for each change.
   This provides consistency throughout the project, and ensures that commit
   messages are able to be formatted properly by various git tools.

6. Finally, push the commits to your fork and submit a [pull request][].

[forking]: https://help.github.com/articles/fork-a-repo
[well-formed commit messages]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
[squash]: http://git-scm.com/book/en/Git-Tools-Rewriting-History#Squashing-Commits
[pull request]: https://help.github.com/articles/creating-a-pull-request


---

Ben McCormick <ben.mccormick@windsorcircle.com>
Jean-Philippe Monette <contact@jpmonette.net>
Pierre Galvez <contact@pierre-galvez.fr>


---

<p align="center">
  <img src="https://user-images.githubusercontent.com/1114325/60746552-2c059a00-9f77-11e9-9632-e21dea9dd06b.png" alt="Feed for Node.js" width="326">
  <br>
  <a href="https://travis-ci.org/jpmonette/feed"><img src="https://travis-ci.org/jpmonette/feed.svg?branch=master" alt="Build Status"></a> <a href='https://coveralls.io/github/jpmonette/feed?branch=master'><img src='https://coveralls.io/repos/github/jpmonette/feed/badge.svg?branch=master' alt='Coverage Status' /></a> <a href="https://badge.fury.io/js/feed"><img src="https://badge.fury.io/js/feed.svg" alt="npm version" height="18"></a> <a href="https://github.com/facebook/jest"><img src="https://img.shields.io/badge/tested_with-jest-99424f.svg" alt="Tested with Jest"></a> <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
</p>
<p align="center"><code>jpmonette/feed</code> - <strong>RSS 2.0, JSON Feed 1.0, and Atom 1.0</strong> generator for <strong>Node.js</strong><br>
Making content syndication simple and intuitive!</p>

---

**👩🏻‍💻 Developer Ready**: Quickly generate syndication feeds for your Website.

**💪🏼 Strongly Typed**: Developed using TypeScript / type-safe.

**🔒 Tested**: Tests & snapshot for each syndication format to avoid regressions.

# Getting Started

## Installation

```bash
$ yarn add feed
```

## Example

```js
import { Feed } from "feed";

const feed = new Feed({
  title: "Feed Title",
  description: "This is my personal feed!",
  id: "http://example.com/",
  link: "http://example.com/",
  language: "en", // optional, used only in RSS 2.0, possible values: http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes
  image: "http://example.com/image.png",
  favicon: "http://example.com/favicon.ico",
  copyright: "All rights reserved 2013, John Doe",
  updated: new Date(2013, 6, 14), // optional, default = today
  generator: "awesome", // optional, default = 'Feed for Node.js'
  feedLinks: {
    json: "https://example.com/json",
    atom: "https://example.com/atom"
  },
  author: {
    name: "John Doe",
    email: "johndoe@example.com",
    link: "https://example.com/johndoe"
  }
});

posts.forEach(post => {
  feed.addItem({
    title: post.title,
    id: post.url,
    link: post.url,
    description: post.description,
    content: post.content,
    author: [
      {
        name: "Jane Doe",
        email: "janedoe@example.com",
        link: "https://example.com/janedoe"
      },
      {
        name: "Joe Smith",
        email: "joesmith@example.com",
        link: "https://example.com/joesmith"
      }
    ],
    contributor: [
      {
        name: "Shawn Kemp",
        email: "shawnkemp@example.com",
        link: "https://example.com/shawnkemp"
      },
      {
        name: "Reggie Miller",
        email: "reggiemiller@example.com",
        link: "https://example.com/reggiemiller"
      }
    ],
    date: post.date,
    image: post.image
  });
});

feed.addCategory("Technologie");

feed.addContributor({
  name: "Johan Cruyff",
  email: "johancruyff@example.com",
  link: "https://example.com/johancruyff"
});

console.log(feed.rss2());
// Output: RSS 2.0

console.log(feed.atom1());
// Output: Atom 1.0

console.log(feed.json1());
// Output: JSON Feed 1.0
```

## Migrating from `< 3.0.0`

If you are migrating from a version older than `3.0.0`, be sure to update your import as we migrated to ES6 named imports.

If your environment supports the ES6 module syntax, you can `import` as described above:

```ts
import { Feed } from "feed";
```

Otherwise, you can stick with `require()`:

```diff
- const Feed = require('feed');
+ const Feed = require('feed').Feed;
```

## More Information

- Follow [@jpmonette](https://twitter.com/jpmonette) on Twitter for updates
- Read my personal blog [Blogue de Jean-Philippe Monette](http://blogue.jpmonette.net/) to learn more about what I do!

## License

Copyright (C) 2013, Jean-Philippe Monette <contact@jpmonette.net>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


---

# escape-string-regexp [![Build Status](https://travis-ci.org/sindresorhus/escape-string-regexp.svg?branch=master)](https://travis-ci.org/sindresorhus/escape-string-regexp)

> Escape RegExp special characters


## Install

```
$ npm install --save escape-string-regexp
```


## Usage

```js
const escapeStringRegexp = require('escape-string-regexp');

const escapedString = escapeStringRegexp('how much $ for a unicorn?');
//=> 'how much \$ for a unicorn\?'

new RegExp(escapedString);
```


## License

MIT © [Sindre Sorhus](http://sindresorhus.com)


---

# figures [![Build Status](https://travis-ci.org/sindresorhus/figures.svg?branch=master)](https://travis-ci.org/sindresorhus/figures)

> Unicode symbols with Windows CMD fallbacks

[![](screenshot.png)](index.js)

[*and more...*](index.js)

Windows CMD only supports a [limited character set](http://en.wikipedia.org/wiki/Code_page_437).

## Install

```
$ npm install figures
```

## Usage

See the [source](index.js) for supported symbols.

```js
const figures = require('figures');

console.log(figures('✔︎ check'));
// On non-Windows OSes:  ✔︎ check
// On Windows:           √ check

console.log(figures.tick);
// On non-Windows OSes:  ✔︎
// On Windows:           √

console.log(figures.main.tick);
// On all OSes:  ✔︎

console.log(figures.windows.tick);
// On all OSes:  √
```

## API

### figures(string)

Returns the input with replaced fallback Unicode symbols on Windows.

All the below [figures](#figures) are attached to the main export as shown in the example above.

#### string

Type: `string`

String where the Unicode symbols will be replaced with fallback symbols depending on the OS.

### figures.main

Symbols to use when not running on Windows.

### figures.windows

Symbols to use when running on Windows.


## Figures

| Name               | Non-Windows | Windows |
| ------------------ | :---------: | :-----: |
| tick               |      ✔      |    √    |
| cross              |      ✖      |    ×    |
| star               |      ★      |    *    |
| square             |      ▇      |    █    |
| squareSmall        |      ◻      |   [ ]   |
| squareSmallFilled  |      ◼      |   [█]   |
| play               |      ▶      |    ►    |
| circle             |      ◯      |   ( )   |
| circleFilled       |      ◉      |   (*)   |
| circleDotted       |      ◌      |   ( )   |
| circleDouble       |      ◎      |   ( )   |
| circleCircle       |      ⓞ      |   (○)   |
| circleCross        |      ⓧ      |   (×)   |
| circlePipe         |      Ⓘ      |   (│)   |
| circleQuestionMark |      ?⃝     |   (?)   |
| bullet             |      ●      |    *    |
| dot                |      ․      |    .    |
| line               |      ─      |    ─    |
| ellipsis           |      …      |   ...   |
| pointer            |      ❯      |    >    |
| pointerSmall       |      ›      |    »    |
| info               |      ℹ      |    i    |
| warning            |      ⚠      |    ‼    |
| hamburger          |      ☰      |    ≡    |
| smiley             |      ㋡      |    ☺    |
| mustache           |      ෴      |   ┌─┐   |
| heart              |      ♥      |    ♥    |
| nodejs             |      ⬢      |    ♦    |
| arrowUp            |      ↑      |    ↑    |
| arrowDown          |      ↓      |    ↓    |
| arrowLeft          |      ←      |    ←    |
| arrowRight         |      →      |    →    |
| radioOn            |      ◉      |   (*)   |
| radioOff           |      ◯      |   ( )   |
| checkboxOn         |      ☒      |   [×]   |
| checkboxOff        |      ☐      |   [ ]   |
| checkboxCircleOn   |      ⓧ      |   (×)   |
| checkboxCircleOff  |      Ⓘ      |   ( )   |
| questionMarkPrefix |      ?⃝     |    ？    |
| oneHalf            |      ½      |   1/2   |
| oneThird           |      ⅓      |   1/3   |
| oneQuarter         |      ¼      |   1/4   |
| oneFifth           |      ⅕      |   1/5   |
| oneSixth           |      ⅙      |   1/6   |
| oneSeventh         |      ⅐      |   1/7   |
| oneEighth          |      ⅛      |   1/8   |
| oneNinth           |      ⅑      |   1/9   |
| oneTenth           |      ⅒      |   1/10  |
| twoThirds          |      ⅔      |   2/3   |
| twoFifths          |      ⅖      |   2/5   |
| threeQuarters      |      ¾      |   3/4   |
| threeFifths        |      ⅗      |   3/5   |
| threeEighths       |      ⅜      |   3/8   |
| fourFifths         |      ⅘      |   4/5   |
| fiveSixths         |      ⅚      |   5/6   |
| fiveEighths        |      ⅝      |   5/8   |
| sevenEighths       |      ⅞      |   7/8   |


## Related

- [log-symbols](https://github.com/sindresorhus/log-symbols) - Colored symbols for various log levels

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-figures?utm_source=npm-figures&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

# Changelog

All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.

## [6.2.0](https://github.com/webpack-contrib/file-loader/compare/v6.1.1...v6.2.0) (2020-10-27)


### Features

* added the `sourceFilename` property to asset info with original filename ([#393](https://github.com/webpack-contrib/file-loader/issues/393)) ([654e0d6](https://github.com/webpack-contrib/file-loader/commit/654e0d641ec067089f6a2d12e30ec3520f00d808))


### Bug Fixes

* immutable flag when the `name` option have hash in query string ([#392](https://github.com/webpack-contrib/file-loader/issues/392)) ([381d8bd](https://github.com/webpack-contrib/file-loader/commit/381d8bda3f2494487bfe840386e365b97b6025fe))

### [6.1.1](https://github.com/webpack-contrib/file-loader/compare/v6.1.0...v6.1.1) (2020-10-09)

### Chore

* update `schema-utils`

## [6.1.0](https://github.com/webpack-contrib/file-loader/compare/v6.0.0...v6.1.0) (2020-08-31)


### Features

* pass immutable flag to asset info ([#383](https://github.com/webpack-contrib/file-loader/issues/383)) ([40fcde8](https://github.com/webpack-contrib/file-loader/commit/40fcde81681d4f8ee19d2ee3845fd34e24459195))

## [6.0.0](https://github.com/webpack-contrib/file-loader/compare/v5.1.0...v6.0.0) (2020-03-17)


### ⚠ BREAKING CHANGES

* use `md4` by default for hashing ([#369](https://github.com/webpack-contrib/file-loader/issues/369)) ([ad39022](https://github.com/webpack-contrib/file-loader/commit/ad3902284d28adeddf667212a39faa4c6bfb2964))

## [5.1.0](https://github.com/webpack-contrib/file-loader/compare/v5.0.2...v5.1.0) (2020-02-19)


### Features

* support the `query` template for the `name` option ([#366](https://github.com/webpack-contrib/file-loader/issues/366)) ([cd8698b](https://github.com/webpack-contrib/file-loader/commit/cd8698b1d9fd560d85e912acca9a1e24f00e18f8))

### [5.0.2](https://github.com/webpack-contrib/file-loader/compare/v5.0.1...v5.0.2) (2019-11-25)


### Chore

*  add the `funding` field in `package.json`



### [5.0.1](https://github.com/webpack-contrib/file-loader/compare/v5.0.0...v5.0.1) (2019-11-25)


### Bug Fixes

* name of `esModule` option in source code ([#346](https://github.com/webpack-contrib/file-loader/issues/346)) ([31d6589](https://github.com/webpack-contrib/file-loader/commit/31d6589b71b471f83908e80380dff9b9eada2d06))

## [5.0.0](https://github.com/webpack-contrib/file-loader/compare/v4.2.0...v5.0.0) (2019-11-22)


### BREAKING CHANGES

* minimum required nodejs version is `10.13.0`
* rename the `esModules` option to `esModule`
* switch to ES modules by default (the option `esModule` is `true` by default)



## [4.3.0](https://github.com/webpack-contrib/file-loader/compare/v4.2.0...v4.3.0) (2019-11-21)


### Features

* new `esModules` option to output ES modules ([#340](https://github.com/webpack-contrib/file-loader/issues/340)) ([9b9cd8d](https://github.com/webpack-contrib/file-loader/commit/9b9cd8d22b3dbe4677be9bdd0bf5fbe07815df54))

## [4.2.0](https://github.com/webpack-contrib/file-loader/compare/v4.1.0...v4.2.0) (2019-08-07)


### Features

* `postTransformPublicPath` option ([#334](https://github.com/webpack-contrib/file-loader/issues/334)) ([c136f44](https://github.com/webpack-contrib/file-loader/commit/c136f44))



## [4.1.0](https://github.com/webpack-contrib/file-loader/compare/v4.0.0...v4.1.0) (2019-07-18)


### Features

* improved validation error messages ([#339](https://github.com/webpack-contrib/file-loader/issues/339)) ([705eed4](https://github.com/webpack-contrib/file-loader/commit/705eed4))



## [4.0.0](https://github.com/webpack-contrib/file-loader/compare/v3.0.1...v4.0.0) (2019-06-05)


### chore

* **deps:** update ([#333](https://github.com/webpack-contrib/file-loader/issues/333)) ([0d2f9b8](https://github.com/webpack-contrib/file-loader/commit/0d2f9b8))


### BREAKING CHANGES

* **deps:** minimum required nodejs version is `8.9.0`



<a name="3.0.1"></a>
## [3.0.1](https://github.com/webpack-contrib/file-loader/compare/v3.0.0...v3.0.1) (2018-12-20)


### Bug Fixes

* relax options validation for additional properties ([#309](https://github.com/webpack-contrib/file-loader/issues/309)) ([c74d44e](https://github.com/webpack-contrib/file-loader/commit/c74d44e))



<a name="3.0.0"></a>
# [3.0.0](https://github.com/webpack-contrib/file-loader/compare/v2.0.0...v3.0.0) (2018-12-20)


### Code Refactoring

* drop support for webpack < 4 ([#303](https://github.com/webpack-contrib/file-loader/issues/303)) ([203a4ee](https://github.com/webpack-contrib/file-loader/commit/203a4ee))
* more validations in `options` schema


### Features

* `resourcePath` is now available in `outputPath` and `publicPath` ([#304](https://github.com/webpack-contrib/file-loader/issues/304)) ([0d66e64](https://github.com/webpack-contrib/file-loader/commit/0d66e64))
* `context` is now available in `outputPath` and `publicPath` ([#305](https://github.com/webpack-contrib/file-loader/issues/305)) ([d5eb823](https://github.com/webpack-contrib/file-loader/commit/d5eb823))


### BREAKING CHANGES

* removed the `useRelativePath` option. It is dangerously and break url when you use multiple entry points.
* drop support for webpack < 4



<a name="2.0.0"></a>
# [2.0.0](https://github.com/webpack-contrib/file-loader/compare/v1.1.11...v2.0.0) (2018-08-21)


### Code Refactoring

* **defaults:** update to latest webpack-defaults ([#268](https://github.com/webpack-contrib/file-loader/issues/268)) ([687f422](https://github.com/webpack-contrib/file-loader/commit/687f422))


### BREAKING CHANGES

* **defaults:** Enforces `engines` of `"node": ">=6.9.0 < 7.0.0 || >= 8.9.0"`



<a name="1.1.11"></a>
## [1.1.11](https://github.com/webpack/file-loader/compare/v1.1.10...v1.1.11) (2018-03-01)


### Reverts

* **index:** `context` takes precedence over `issuer.context` (`options.useRelativePath`) ([#260](https://github.com/webpack/file-loader/issues/260)) ([e73131f](https://github.com/webpack/file-loader/commit/e73131f))



<a name="1.1.10"></a>
## [1.1.10](https://github.com/webpack/file-loader/compare/v1.1.9...v1.1.10) (2018-02-26)


### Bug Fixes

* **package:** add `webpack >= 4` (`peerDependencies`) ([#255](https://github.com/webpack/file-loader/issues/255)) ([3a6a7a1](https://github.com/webpack/file-loader/commit/3a6a7a1))



<a name="1.1.9"></a>
## [1.1.9](https://github.com/webpack/file-loader/compare/v1.1.8...v1.1.9) (2018-02-21)


### Bug Fixes

* **index:** handle protocol URL's correctly (`options.publicPath`) ([#253](https://github.com/webpack/file-loader/issues/253)) ([54fa5a3](https://github.com/webpack/file-loader/commit/54fa5a3))
* **index:** use `path.posix` for platform consistency ([#254](https://github.com/webpack/file-loader/issues/254)) ([2afe0af](https://github.com/webpack/file-loader/commit/2afe0af))



<a name="1.1.8"></a>
## [1.1.8](https://github.com/webpack/file-loader/compare/v1.1.7...v1.1.8) (2018-02-20)


### Bug Fixes

* **index:** `context` takes precedence over `issuer.context` (`options.useRelativePath`) ([3b071f5](https://github.com/webpack/file-loader/commit/3b071f5))
* **index:** don't append `outputPath` to the original `url` (`options.outputPath` `{Function}`) ([4c1ccaa](https://github.com/webpack/file-loader/commit/4c1ccaa))
* **index:** normalize and concat paths via `path.join()` ([26e47ca](https://github.com/webpack/file-loader/commit/26e47ca))



<a name="1.1.7"></a>
## [1.1.7](https://github.com/webpack/file-loader/compare/v1.1.6...v1.1.7) (2018-02-19)


### Bug Fixes

* **index:** don't concat `options.outputPath` and `options.publicPath` ([#246](https://github.com/webpack/file-loader/issues/246)) ([98bf052](https://github.com/webpack/file-loader/commit/98bf052))



<a name="1.1.6"></a>
## [1.1.6](https://github.com/webpack/file-loader/compare/v1.1.5...v1.1.6) (2017-12-16)


### Bug Fixes

* rootContext compatibility fix for legacy / v4 (#237) ([1e4b7cf](https://github.com/webpack/file-loader/commit/1e4b7cf)), closes [#237](https://github.com/webpack/file-loader/issues/237)



<a name="1.1.5"></a>
## [1.1.5](https://github.com/webpack/file-loader/compare/v1.1.4...v1.1.5) (2017-10-05)


### Bug Fixes

* **schema:** allow `name` to be a `{Function}` (`options.name`) ([#216](https://github.com/webpack/file-loader/issues/216)) ([fbfb160](https://github.com/webpack/file-loader/commit/fbfb160))



<a name="1.1.4"></a>
## [1.1.4](https://github.com/webpack/file-loader/compare/v1.1.3...v1.1.4) (2017-09-30)


### Bug Fixes

* **index:** revert to CJS exports ([#212](https://github.com/webpack/file-loader/issues/212)) ([f412b3e](https://github.com/webpack/file-loader/commit/f412b3e))



<a name="1.1.3"></a>
## [1.1.3](https://github.com/webpack/file-loader/compare/v1.1.2...v1.1.3) (2017-09-30)



<a name="1.1.2"></a>
## [1.1.2](https://github.com/webpack/file-loader/compare/v1.1.1...v1.1.2) (2017-09-30)


### Bug Fixes

* **cjs:** export `raw` value ([#183](https://github.com/webpack/file-loader/issues/183)) ([daeff0e](https://github.com/webpack/file-loader/commit/daeff0e))



<a name="1.1.1"></a>
## [1.1.1](https://github.com/webpack/file-loader/compare/v1.1.0...v1.1.1) (2017-09-30)


### Bug Fixes

* **schema:** allow `additionalProperties` ([#207](https://github.com/webpack/file-loader/issues/207)) ([cf7c85a](https://github.com/webpack/file-loader/commit/cf7c85a))



<a name="1.1.0"></a>
# [1.1.0](https://github.com/webpack/file-loader/compare/v1.0.0...v1.1.0) (2017-09-29)


### Features

* add `options` validation (`schema-utils`) ([#184](https://github.com/webpack/file-loader/issues/184)) ([696ca77](https://github.com/webpack/file-loader/commit/696ca77))



<a name="1.0.0"></a>
# [1.0.0](https://github.com/webpack/file-loader/compare/v1.0.0-rc.0...v1.0.0) (2017-07-26)


### Bug Fixes

* remove `=` from default export (`SyntaxError`) ([#178](https://github.com/webpack/file-loader/issues/178)) ([3fe2d12](https://github.com/webpack/file-loader/commit/3fe2d12))


### Code Refactoring

* Upgrade to defaults 1.3.0 ([#170](https://github.com/webpack-contrib/file-loader/pull/170)) ([632ed72](https://github.com/webpack/file-loader/commit/acd6c2f))
* Apply webpack-defaults ([#167](https://github.com/webpack/file-loader/issues/167)) ([632ed72](https://github.com/webpack/file-loader/commit/632ed72))


### BREAKING CHANGES

* Enforces Webpack standard NodeJS engines range.
   at the time of merge `>= 4.3 < 5.0.0 || >= 5.10`.



<a name="1.0.0-rc.0"></a>
# [1.0.0-rc.0](https://github.com/webpack/file-loader/compare/v1.0.0-beta.1...v1.0.0-rc.0) (2017-07-26)


### Bug Fixes

* remove `=` from default export (`SyntaxError`) ([#178](https://github.com/webpack/file-loader/issues/178)) ([3fe2d12](https://github.com/webpack/file-loader/commit/3fe2d12))



<a name="1.0.0-beta.1"></a>
# [1.0.0-beta.1](https://github.com/webpack/file-loader/compare/v1.0.0-beta.0...v1.0.0-beta.1) (2017-06-09)

### Code Refactoring

* Upgrade to defaults 1.3.0 ([#170](https://github.com/webpack-contrib/file-loader/pull/170)) ([632ed72](https://github.com/webpack/file-loader/commit/acd6c2f))


<a name="1.0.0-beta.0"></a>
# [1.0.0-beta.0](https://github.com/webpack/file-loader/compare/v0.11.2...v1.0.0-beta.0) (2017-06-07)


### Code Refactoring

* Apply webpack-defaults ([#167](https://github.com/webpack/file-loader/issues/167)) ([632ed72](https://github.com/webpack/file-loader/commit/632ed72))


### BREAKING CHANGES

* Enforces Webpack standard NodeJS engines range.
   at the time of merge `>= 4.3 < 5.0.0 || >= 5.10`.



<a name="0.11.2"></a>
## [0.11.2](https://github.com/webpack/file-loader/compare/v0.11.1...v0.11.2) (2017-06-05)


### Bug Fixes

* **index:** allow to override publicPath with an empty string ([#145](https://github.com/webpack/file-loader/issues/145)) ([26ab81a](https://github.com/webpack/file-loader/commit/26ab81a))
* init `publicPath` to undefined ([#159](https://github.com/webpack/file-loader/issues/159)) ([e4c0b2a](https://github.com/webpack/file-loader/commit/e4c0b2a))



<a name="0.11.1"></a>
## [0.11.1](https://github.com/webpack/file-loader/compare/v0.11.0...v0.11.1) (2017-04-01)


### Bug Fixes

* outputPath function overriden by useRelativePath ([#139](https://github.com/webpack/file-loader/issues/139)) ([80cdee2](https://github.com/webpack/file-loader/commit/80cdee2))



<a name="0.11.0"></a>
# [0.11.0](https://github.com/webpack/file-loader/compare/v0.10.1...v0.11.0) (2017-03-31)


### Features

* Emit files with relative urls ([#135](https://github.com/webpack/file-loader/issues/135)) ([dbcd6cc](https://github.com/webpack/file-loader/commit/dbcd6cc))



<a name="0.10.1"></a>
## [0.10.1](https://github.com/webpack/file-loader/compare/v0.10.0...v0.10.1) (2017-02-25)


### Bug Fixes

* **getOptions:** deprecation warn in loaderUtils ([#129](https://github.com/webpack/file-loader/issues/129)) ([a8358a0](https://github.com/webpack/file-loader/commit/a8358a0))



<a name="0.10.0"></a>
# [0.10.0](https://github.com/webpack/file-loader/compare/v0.9.0...v0.10.0) (2017-01-28)


### Features

* **resources:** specify custom public file name ([6833c70](https://github.com/webpack/file-loader/commit/6833c70))



# Change Log

All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.


---

<div align="center">
  <a href="https://github.com/webpack/webpack">
    <img width="200" height="200" src="https://webpack.js.org/assets/icon-square-big.svg">
  </a>
</div>

[![npm][npm]][npm-url]
[![node][node]][node-url]
[![deps][deps]][deps-url]
[![tests][tests]][tests-url]
[![coverage][cover]][cover-url]
[![chat][chat]][chat-url]
[![size][size]][size-url]

# file-loader

The `file-loader` resolves `import`/`require()` on a file into a url and emits the file into the output directory.

## Getting Started

To begin, you'll need to install `file-loader`:

```console
$ npm install file-loader --save-dev
```

Import (or `require`) the target file(s) in one of the bundle's files:

**file.js**

```js
import img from './file.png';
```

Then add the loader to your `webpack` config. For example:

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpe?g|gif)$/i,
        use: [
          {
            loader: 'file-loader',
          },
        ],
      },
    ],
  },
};
```

And run `webpack` via your preferred method. This will emit `file.png` as a file
in the output directory (with the specified naming convention, if options are
specified to do so) and returns the public URI of the file.

> ℹ️ By default the filename of the resulting file is the hash of the file's contents with the original extension of the required resource.

## Options

### `name`

Type: `String|Function`
Default: `'[contenthash].[ext]'`

Specifies a custom filename template for the target file(s) using the query
parameter `name`. For example, to emit a file from your `context` directory into
the output directory retaining the full directory structure, you might use:

#### `String`

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpe?g|gif)$/i,
        loader: 'file-loader',
        options: {
          name: '[path][name].[ext]',
        },
      },
    ],
  },
};
```

#### `Function`

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpe?g|gif)$/i,
        loader: 'file-loader',
        options: {
          name(resourcePath, resourceQuery) {
            // `resourcePath` - `/absolute/path/to/file.js`
            // `resourceQuery` - `?foo=bar`

            if (process.env.NODE_ENV === 'development') {
              return '[path][name].[ext]';
            }

            return '[contenthash].[ext]';
          },
        },
      },
    ],
  },
};
```

> ℹ️ By default the path and name you specify will output the file in that same directory, and will also use the same URI path to access the file.

### `outputPath`

Type: `String|Function`
Default: `undefined`

Specify a filesystem path where the target file(s) will be placed.

#### `String`

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpe?g|gif)$/i,
        loader: 'file-loader',
        options: {
          outputPath: 'images',
        },
      },
    ],
  },
};
```

#### `Function`

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpe?g|gif)$/i,
        loader: 'file-loader',
        options: {
          outputPath: (url, resourcePath, context) => {
            // `resourcePath` is original absolute path to asset
            // `context` is directory where stored asset (`rootContext`) or `context` option

            // To get relative path you can use
            // const relativePath = path.relative(context, resourcePath);

            if (/my-custom-image\.png/.test(resourcePath)) {
              return `other_output_path/${url}`;
            }

            if (/images/.test(context)) {
              return `image_output_path/${url}`;
            }

            return `output_path/${url}`;
          },
        },
      },
    ],
  },
};
```

### `publicPath`

Type: `String|Function`
Default: [`__webpack_public_path__`](https://webpack.js.org/api/module-variables/#__webpack_public_path__-webpack-specific-)+outputPath

Specifies a custom public path for the target file(s).

#### `String`

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpe?g|gif)$/i,
        loader: 'file-loader',
        options: {
          publicPath: 'assets',
        },
      },
    ],
  },
};
```

#### `Function`

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpe?g|gif)$/i,
        loader: 'file-loader',
        options: {
          publicPath: (url, resourcePath, context) => {
            // `resourcePath` is original absolute path to asset
            // `context` is directory where stored asset (`rootContext`) or `context` option

            // To get relative path you can use
            // const relativePath = path.relative(context, resourcePath);

            if (/my-custom-image\.png/.test(resourcePath)) {
              return `other_public_path/${url}`;
            }

            if (/images/.test(context)) {
              return `image_output_path/${url}`;
            }

            return `public_path/${url}`;
          },
        },
      },
    ],
  },
};
```

### `postTransformPublicPath`

Type: `Function`
Default: `undefined`

Specifies a custom function to post-process the generated public path. This can be used to prepend or append dynamic global variables that are only available at runtime, like `__webpack_public_path__`. This would not be possible with just `publicPath`, since it stringifies the values.

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpg|gif)$/i,
        loader: 'file-loader',
        options: {
          publicPath: '/some/path/',
          postTransformPublicPath: (p) => `__webpack_public_path__ + ${p}`,
        },
      },
    ],
  },
};
```

### `context`

Type: `String`
Default: [`context`](https://webpack.js.org/configuration/entry-context/#context)

Specifies a custom file context.

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpe?g|gif)$/i,
        use: [
          {
            loader: 'file-loader',
            options: {
              context: 'project',
            },
          },
        ],
      },
    ],
  },
};
```

### `emitFile`

Type: `Boolean`
Default: `true`

If true, emits a file (writes a file to the filesystem). If false, the loader
will return a public URI but **will not** emit the file. It is often useful to
disable this option for server-side packages.

**file.js**

```js
// bundle file
import img from './file.png';
```

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          {
            loader: 'file-loader',
            options: {
              emitFile: false,
            },
          },
        ],
      },
    ],
  },
};
```

### `regExp`

Type: `RegExp`
Default: `undefined`

Specifies a Regular Expression to one or many parts of the target file path.
The capture groups can be reused in the `name` property using `[N]`
[placeholder](https://github.com/webpack-contrib/file-loader#placeholders).

**file.js**

```js
import img from './customer01/file.png';
```

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpe?g|gif)$/i,
        use: [
          {
            loader: 'file-loader',
            options: {
              regExp: /\/([a-z0-9]+)\/[a-z0-9]+\.png$/i,
              name: '[1]-[name].[ext]',
            },
          },
        ],
      },
    ],
  },
};
```

> ℹ️ If `[0]` is used, it will be replaced by the entire tested string, whereas `[1]` will contain the first capturing parenthesis of your regex and so on...

### `esModule`

Type: `Boolean`
Default: `true`

By default, `file-loader` generates JS modules that use the ES modules syntax.
There are some cases in which using ES modules is beneficial, like in the case of [module concatenation](https://webpack.js.org/plugins/module-concatenation-plugin/) and [tree shaking](https://webpack.js.org/guides/tree-shaking/).

You can enable a CommonJS module syntax using:

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          {
            loader: 'file-loader',
            options: {
              esModule: false,
            },
          },
        ],
      },
    ],
  },
};
```

## Placeholders

Full information about placeholders you can find [here](https://github.com/webpack/loader-utils#interpolatename).

### `[ext]`

Type: `String`
Default: `file.extname`

The file extension of the target file/resource.

### `[name]`

Type: `String`
Default: `file.basename`

The basename of the file/resource.

### `[path]`

Type: `String`
Default: `file.directory`

The path of the resource relative to the webpack/config `context`.

### `[folder]`

Type: `String`
Default: `file.folder`

The folder of the resource is in.

### `[query]`

Type: `String`
Default: `file.query`

The query of the resource, i.e. `?foo=bar`.

### `[emoji]`

Type: `String`
Default: `undefined`

A random emoji representation of `content`.

### `[emoji:<length>]`

Type: `String`
Default: `undefined`

Same as above, but with a customizable number of emojis

### `[hash]`

Type: `String`
Default: `md4`

Specifies the hash method to use for hashing the file content.

### `[contenthash]`

Type: `String`
Default: `md4`

Specifies the hash method to use for hashing the file content.

### `[<hashType>:hash:<digestType>:<length>]`

Type: `String`

The hash of options.content (Buffer) (by default it's the hex digest of the hash).

#### `digestType`

Type: `String`
Default: `'hex'`

The [digest](https://en.wikipedia.org/wiki/Cryptographic_hash_function) that the
hash function should use. Valid values include: base26, base32, base36,
base49, base52, base58, base62, base64, and hex.

#### `hashType`

Type: `String`
Default: `'md4'`

The type of hash that the has function should use. Valid values include: `md4`, `md5`, `sha1`, `sha256`, and `sha512`.

#### `length`

Type: `Number`
Default: `undefined`

Users may also specify a length for the computed hash.

### `[N]`

Type: `String`
Default: `undefined`

The n-th match obtained from matching the current file name against the `regExp`.

## Examples

### Names

The following examples show how one might use `file-loader` and what the result would be.

**file.js**

```js
import png from './image.png';
```

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpe?g|gif)$/i,
        use: [
          {
            loader: 'file-loader',
            options: {
              name: 'dirname/[contenthash].[ext]',
            },
          },
        ],
      },
    ],
  },
};
```

Result:

```bash
# result
dirname/0dcbbaa701328ae351f.png
```

---

**file.js**

```js
import png from './image.png';
```

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpe?g|gif)$/i,
        use: [
          {
            loader: 'file-loader',
            options: {
              name: '[sha512:hash:base64:7].[ext]',
            },
          },
        ],
      },
    ],
  },
};
```

Result:

```bash
# result
gdyb21L.png
```

---

**file.js**

```js
import png from './path/to/file.png';
```

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpe?g|gif)$/i,
        use: [
          {
            loader: 'file-loader',
            options: {
              name: '[path][name].[ext]?[contenthash]',
            },
          },
        ],
      },
    ],
  },
};
```

Result:

```bash
# result
path/to/file.png?e43b20c069c4a01867c31e98cbce33c9
```

### CDN

The following examples show how to use `file-loader` for CDN uses query params.

**file.js**

```js
import png from './directory/image.png?width=300&height=300';
```

**webpack.config.js**

```js
module.exports = {
  output: {
    publicPath: 'https://cdn.example.com/',
  },
  module: {
    rules: [
      {
        test: /\.(png|jpe?g|gif)$/i,
        use: [
          {
            loader: 'file-loader',
            options: {
              name: '[path][name].[ext][query]',
            },
          },
        ],
      },
    ],
  },
};
```

Result:

```bash
# result
https://cdn.example.com/directory/image.png?width=300&height=300
```

### Dynamic public path depending on environment variable at run time

An application might want to configure different CDN hosts depending on an environment variable that is only available when running the application. This can be an advantage, as only one build of the application is necessary, which behaves differently depending on environment variables of the deployment environment. Since file-loader is applied when compiling the application, and not when running it, the environment variable cannot be used in the file-loader configuration. A way around this is setting the `__webpack_public_path__` to the desired CDN host depending on the environment variable at the entrypoint of the application. The option `postTransformPublicPath` can be used to configure a custom path depending on a variable like `__webpack_public_path__`.

**main.js**

```js
const assetPrefixForNamespace = (namespace) => {
  switch (namespace) {
    case 'prod':
      return 'https://cache.myserver.net/web';
    case 'uat':
      return 'https://cache-uat.myserver.net/web';
    case 'st':
      return 'https://cache-st.myserver.net/web';
    case 'dev':
      return 'https://cache-dev.myserver.net/web';
    default:
      return '';
  }
};
const namespace = process.env.NAMESPACE;

__webpack_public_path__ = `${assetPrefixForNamespace(namespace)}/`;
```

**file.js**

```js
import png from './image.png';
```

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpg|gif)$/i,
        loader: 'file-loader',
        options: {
          name: '[name].[contenthash].[ext]',
          outputPath: 'static/assets/',
          publicPath: 'static/assets/',
          postTransformPublicPath: (p) => `__webpack_public_path__ + ${p}`,
        },
      },
    ],
  },
};
```

Result when run with `NAMESPACE=prod` env variable:

```bash
# result
https://cache.myserver.net/web/static/assets/image.somehash.png
```

Result when run with `NAMESPACE=dev` env variable:

```bash
# result
https://cache-dev.myserver.net/web/static/assets/image.somehash.png
```

## Contributing

Please take a moment to read our contributing guidelines if you haven't yet done so.

[CONTRIBUTING](./.github/CONTRIBUTING.md)

## License

[MIT](./LICENSE)

[npm]: https://img.shields.io/npm/v/file-loader.svg
[npm-url]: https://npmjs.com/package/file-loader
[node]: https://img.shields.io/node/v/file-loader.svg
[node-url]: https://nodejs.org
[deps]: https://david-dm.org/webpack-contrib/file-loader.svg
[deps-url]: https://david-dm.org/webpack-contrib/file-loader
[tests]: https://github.com/webpack-contrib/file-loader/workflows/file-loader/badge.svg
[tests-url]: https://github.com/webpack-contrib/file-loader/actions
[cover]: https://codecov.io/gh/webpack-contrib/file-loader/branch/master/graph/badge.svg
[cover-url]: https://codecov.io/gh/webpack-contrib/file-loader
[chat]: https://img.shields.io/badge/gitter-webpack%2Fwebpack-brightgreen.svg
[chat-url]: https://gitter.im/webpack/webpack
[size]: https://packagephobia.now.sh/badge?p=file-loader
[size-url]: https://packagephobia.now.sh/result?p=file-loader


---

# Changelog

All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.

## [3.3.0](https://github.com/webpack/schema-utils/compare/v3.2.0...v3.3.0) (2023-06-14)


### Features

* added API to disable and enable validation ([#183](https://github.com/webpack/schema-utils/issues/183)) ([d4d334f](https://github.com/webpack/schema-utils/commit/d4d334f0ba22eb6b6564b1119e8f3ea439e1f2bb))


### Bug Fixes

* **perf:** cache compiled schema ([#182](https://github.com/webpack/schema-utils/issues/182)) ([02aa068](https://github.com/webpack/schema-utils/commit/02aa068df80d99cc576a5ed385f947eb5204c5db))

## [3.2.0](https://github.com/webpack/schema-utils/compare/v3.1.2...v3.2.0) (2023-06-07)


### Features

* implement `undefinedAsNull` keyword for `enum` type ([#176](https://github.com/webpack/schema-utils/issues/176)) ([95826eb](https://github.com/webpack/schema-utils/commit/95826eb9e14bc4b10ab95f962ac2bdca447880a3))

### [3.1.2](https://github.com/webpack/schema-utils/compare/v3.1.1...v3.1.2) (2023-04-15)


### Bug Fixes

* **perf:** reduced initial start time ([#170](https://github.com/webpack/schema-utils/issues/170)) ([8d052e6](https://github.com/webpack/schema-utils/commit/8d052e6764dc9247e7d5b7b1ae8f87ca5047b2b0))

### [3.1.1](https://github.com/webpack/schema-utils/compare/v3.1.0...v3.1.1) (2021-07-19)


### Bug Fixes

* update error message for `integer` ([#136](https://github.com/webpack/schema-utils/issues/136)) ([2daa97e](https://github.com/webpack/schema-utils/commit/2daa97eae87e6790b92711746a6a527b859ac13b))

## [3.1.0](https://github.com/webpack/schema-utils/compare/v3.0.0...v3.1.0) (2021-06-30)


### Features

* added the `link` property in validation error ([589aa59](https://github.com/webpack/schema-utils/commit/589aa5993424a8bc45ec22b67dff55be92c456a9))


### Bug Fixes

* non-empty validation error message ([#116](https://github.com/webpack/schema-utils/issues/116)) ([c51abef](https://github.com/webpack/schema-utils/commit/c51abefa4d4d62e1346b3a105182d36675595077))

## [3.0.0](https://github.com/webpack/schema-utils/compare/v2.7.1...v3.0.0) (2020-10-05)


### ⚠ BREAKING CHANGES

* minimum supported `Node.js` version is `10.13.0`, 
* the packages exports was changed, please use `const { validate } = require('schema-utils');`
* the `ValidateError` export was removed in favor the `ValidationError` export, please use `const { ValidationError } = require('schema-utils');`

### [2.7.1](https://github.com/webpack/schema-utils/compare/v2.7.0...v2.7.1) (2020-08-31)


### Bug Fixes

* remove esModuleInterop from tsconfig ([#110](https://github.com/webpack/schema-utils/issues/110)) ([#111](https://github.com/webpack/schema-utils/issues/111)) ([2f40154](https://github.com/webpack/schema-utils/commit/2f40154b91e45b393258ae9dd8f10cc3b8590b7d))

## [2.7.0](https://github.com/webpack/schema-utils/compare/v2.6.6...v2.7.0) (2020-05-29)


### Features

* improve hints ([a36e535](https://github.com/webpack/schema-utils/commit/a36e535faca1b01e27c3bfa3c8bee9227c3f836c))
* smart not case ([#101](https://github.com/webpack/schema-utils/issues/101)) ([698d8b0](https://github.com/webpack/schema-utils/commit/698d8b05462d86aadb217e25a45c7b953a79a52e))


### Bug Fixes

* move @types/json-schema from devDependencies to dependencies ([#97](https://github.com/webpack/schema-utils/issues/97)) ([#98](https://github.com/webpack/schema-utils/issues/98)) ([945e67d](https://github.com/webpack/schema-utils/commit/945e67db5e19baf7ec7df72813b0739dd56f950d))

### [2.6.6](https://github.com/webpack/schema-utils/compare/v2.6.5...v2.6.6) (2020-04-17)


### Bug Fixes

* improve perf

### [2.6.5](https://github.com/webpack/schema-utils/compare/v2.6.4...v2.6.5) (2020-03-11)


### Bug Fixes

* correct dots at end of sentence ([7284beb](https://github.com/webpack/schema-utils/commit/7284bebe00cd570f1bef2c15951a07b9794038e6))

### [2.6.4](https://github.com/webpack/schema-utils/compare/v2.6.3...v2.6.4) (2020-01-17)


### Bug Fixes

* change `initialised` to `initialized` ([#87](https://github.com/webpack/schema-utils/issues/87)) ([70f12d3](https://github.com/webpack/schema-utils/commit/70f12d33a8eaa27249bc9c1a27f886724cf91ea7))

### [2.6.3](https://github.com/webpack/schema-utils/compare/v2.6.2...v2.6.3) (2020-01-17)


### Bug Fixes

* prefer the `baseDataPath` option from arguments ([#86](https://github.com/webpack/schema-utils/issues/86)) ([e236859](https://github.com/webpack/schema-utils/commit/e236859e85b28e35e1294f86fc1ff596a5031cea))

### [2.6.2](https://github.com/webpack/schema-utils/compare/v2.6.1...v2.6.2) (2020-01-14)


### Bug Fixes

* better handle Windows absolute paths ([#85](https://github.com/webpack/schema-utils/issues/85)) ([1fa2930](https://github.com/webpack/schema-utils/commit/1fa2930a161e907b9fc53a7233d605910afdb883))

### [2.6.1](https://github.com/webpack/schema-utils/compare/v2.6.0...v2.6.1) (2019-11-28)


### Bug Fixes

* typescript declarations ([#84](https://github.com/webpack/schema-utils/issues/84)) ([89d55a9](https://github.com/webpack/schema-utils/commit/89d55a9a8edfa6a8ac8b112f226bb3154e260319))

## [2.6.0](https://github.com/webpack/schema-utils/compare/v2.5.0...v2.6.0) (2019-11-27)


### Features

* support configuration via title ([#81](https://github.com/webpack/schema-utils/issues/81)) ([afddc10](https://github.com/webpack/schema-utils/commit/afddc109f6891cd37a9f1835d50862d119a072bf))


### Bug Fixes

* typescript definitions ([#70](https://github.com/webpack/schema-utils/issues/70)) ([f38158d](https://github.com/webpack/schema-utils/commit/f38158d6d040e2c701622778ae8122fb26a4f990))

## [2.5.0](https://github.com/webpack/schema-utils/compare/v2.4.1...v2.5.0) (2019-10-15)


### Bug Fixes

* rework format for maxLength, minLength ([#67](https://github.com/webpack/schema-utils/issues/67)) ([0d12259](https://github.com/webpack/schema-utils/commit/0d12259))
* support all cases with one number in range ([#64](https://github.com/webpack/schema-utils/issues/64)) ([7fc8069](https://github.com/webpack/schema-utils/commit/7fc8069))
* typescript definition and export naming ([#69](https://github.com/webpack/schema-utils/issues/69)) ([a435b79](https://github.com/webpack/schema-utils/commit/a435b79))


### Features

* "smart" numbers range ([62fb107](https://github.com/webpack/schema-utils/commit/62fb107))

### [2.4.1](https://github.com/webpack/schema-utils/compare/v2.4.0...v2.4.1) (2019-09-27)


### Bug Fixes

* publish definitions ([#58](https://github.com/webpack/schema-utils/issues/58)) ([1885faa](https://github.com/webpack/schema-utils/commit/1885faa))

## [2.4.0](https://github.com/webpack/schema-utils/compare/v2.3.0...v2.4.0) (2019-09-26)


### Features

* better errors when the `type` keyword doesn't exist ([0988be2](https://github.com/webpack/schema-utils/commit/0988be2))
* support $data reference ([#56](https://github.com/webpack/schema-utils/issues/56)) ([d2f11d6](https://github.com/webpack/schema-utils/commit/d2f11d6))
* types definitions ([#52](https://github.com/webpack/schema-utils/issues/52)) ([facb431](https://github.com/webpack/schema-utils/commit/facb431))

## [2.3.0](https://github.com/webpack/schema-utils/compare/v2.2.0...v2.3.0) (2019-09-26)


### Features

* support `not` keyword ([#53](https://github.com/webpack/schema-utils/issues/53)) ([765f458](https://github.com/webpack/schema-utils/commit/765f458))

## [2.2.0](https://github.com/webpack/schema-utils/compare/v2.1.0...v2.2.0) (2019-09-02)


### Features

* better error output for `oneOf` and `anyOf` ([#48](https://github.com/webpack/schema-utils/issues/48)) ([#50](https://github.com/webpack/schema-utils/issues/50)) ([332242f](https://github.com/webpack/schema-utils/commit/332242f))

## [2.1.0](https://github.com/webpack-contrib/schema-utils/compare/v2.0.1...v2.1.0) (2019-08-07)


### Bug Fixes

* throw error on sparse arrays ([#47](https://github.com/webpack-contrib/schema-utils/issues/47)) ([b85ac38](https://github.com/webpack-contrib/schema-utils/commit/b85ac38))


### Features

* export `ValidateError` ([#46](https://github.com/webpack-contrib/schema-utils/issues/46)) ([ff781d7](https://github.com/webpack-contrib/schema-utils/commit/ff781d7))



### [2.0.1](https://github.com/webpack-contrib/schema-utils/compare/v2.0.0...v2.0.1) (2019-07-18)


### Bug Fixes

* error message for empty object ([#44](https://github.com/webpack-contrib/schema-utils/issues/44)) ([0b4b4a2](https://github.com/webpack-contrib/schema-utils/commit/0b4b4a2))



### [2.0.0](https://github.com/webpack-contrib/schema-utils/compare/v1.0.0...v2.0.0) (2019-07-17)


### BREAKING CHANGES

* drop support for Node.js < 8.9.0
* drop support `errorMessage`, please use `description` for links.
* api was changed, please look documentation.
* error messages was fully rewritten.


<a name="1.0.0"></a>
# [1.0.0](https://github.com/webpack-contrib/schema-utils/compare/v0.4.7...v1.0.0) (2018-08-07)


### Features

* **src:** add support for custom error messages ([#33](https://github.com/webpack-contrib/schema-utils/issues/33)) ([1cbe4ef](https://github.com/webpack-contrib/schema-utils/commit/1cbe4ef))



<a name="0.4.7"></a>
## [0.4.7](https://github.com/webpack-contrib/schema-utils/compare/v0.4.6...v0.4.7) (2018-08-07)


### Bug Fixes

* **src:** `node >= v4.0.0` support ([#32](https://github.com/webpack-contrib/schema-utils/issues/32)) ([cb13dd4](https://github.com/webpack-contrib/schema-utils/commit/cb13dd4))



<a name="0.4.6"></a>
## [0.4.6](https://github.com/webpack-contrib/schema-utils/compare/v0.4.5...v0.4.6) (2018-08-06)


### Bug Fixes

* **package:** remove lockfile ([#28](https://github.com/webpack-contrib/schema-utils/issues/28)) ([69f1a81](https://github.com/webpack-contrib/schema-utils/commit/69f1a81))
* **package:** remove unnecessary `webpack` dependency ([#26](https://github.com/webpack-contrib/schema-utils/issues/26)) ([532eaa5](https://github.com/webpack-contrib/schema-utils/commit/532eaa5))



<a name="0.4.5"></a>
## [0.4.5](https://github.com/webpack-contrib/schema-utils/compare/v0.4.4...v0.4.5) (2018-02-13)


### Bug Fixes

* **CHANGELOG:** update broken links ([4483b9f](https://github.com/webpack-contrib/schema-utils/commit/4483b9f))
* **package:** update broken links ([f2494ba](https://github.com/webpack-contrib/schema-utils/commit/f2494ba))



<a name="0.4.4"></a>
## [0.4.4](https://github.com/webpack-contrib/schema-utils/compare/v0.4.3...v0.4.4) (2018-02-13)


### Bug Fixes

* **package:** update `dependencies` ([#22](https://github.com/webpack-contrib/schema-utils/issues/22)) ([3aecac6](https://github.com/webpack-contrib/schema-utils/commit/3aecac6))



<a name="0.4.3"></a>
## [0.4.3](https://github.com/webpack-contrib/schema-utils/compare/v0.4.2...v0.4.3) (2017-12-14)


### Bug Fixes

* **validateOptions:** throw `err` instead of `process.exit(1)` ([#17](https://github.com/webpack-contrib/schema-utils/issues/17)) ([c595eda](https://github.com/webpack-contrib/schema-utils/commit/c595eda))
* **ValidationError:** never return `this` in the ctor ([#16](https://github.com/webpack-contrib/schema-utils/issues/16)) ([c723791](https://github.com/webpack-contrib/schema-utils/commit/c723791))



<a name="0.4.2"></a>
## [0.4.2](https://github.com/webpack-contrib/schema-utils/compare/v0.4.1...v0.4.2) (2017-11-09)


### Bug Fixes

* **validateOptions:** catch `ValidationError` and handle it internally ([#15](https://github.com/webpack-contrib/schema-utils/issues/15)) ([9c5ef5e](https://github.com/webpack-contrib/schema-utils/commit/9c5ef5e))



<a name="0.4.1"></a>
## [0.4.1](https://github.com/webpack-contrib/schema-utils/compare/v0.4.0...v0.4.1) (2017-11-03)


### Bug Fixes

* **ValidationError:** use `Error.captureStackTrace` for `err.stack` handling ([#14](https://github.com/webpack-contrib/schema-utils/issues/14)) ([a6fb974](https://github.com/webpack-contrib/schema-utils/commit/a6fb974))



<a name="0.4.0"></a>
# [0.4.0](https://github.com/webpack-contrib/schema-utils/compare/v0.3.0...v0.4.0) (2017-10-28)


### Features

* add support for `typeof`, `instanceof` (`{Function\|RegExp}`) ([#10](https://github.com/webpack-contrib/schema-utils/issues/10)) ([9f01816](https://github.com/webpack-contrib/schema-utils/commit/9f01816))



<a name="0.3.0"></a>
# [0.3.0](https://github.com/webpack-contrib/schema-utils/compare/v0.2.1...v0.3.0) (2017-04-29)


### Features

* add ValidationError ([#8](https://github.com/webpack-contrib/schema-utils/issues/8)) ([d48f0fb](https://github.com/webpack-contrib/schema-utils/commit/d48f0fb))



<a name="0.2.1"></a>
## [0.2.1](https://github.com/webpack-contrib/schema-utils/compare/v0.2.0...v0.2.1) (2017-03-13)


### Bug Fixes

* Include .babelrc to `files` ([28f0363](https://github.com/webpack-contrib/schema-utils/commit/28f0363))
* Include source to `files` ([43b0f2f](https://github.com/webpack-contrib/schema-utils/commit/43b0f2f))



<a name="0.2.0"></a>
# [0.2.0](https://github.com/webpack-contrib/schema-utils/compare/v0.1.0...v0.2.0) (2017-03-12)

<a name="0.1.0"></a>
# 0.1.0 (2017-03-07)


### Features

* **validations:** add validateOptions module ([ae9b47b](https://github.com/webpack-contrib/schema-utils/commit/ae9b47b))



# Change Log

All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.


---

<div align="center">
  <a href="http://json-schema.org">
    <img width="160" height="160"
      src="https://raw.githubusercontent.com/webpack-contrib/schema-utils/master/.github/assets/logo.png">
  </a>
  <a href="https://github.com/webpack/webpack">
    <img width="200" height="200"
      src="https://webpack.js.org/assets/icon-square-big.svg">
  </a>
</div>

[![npm][npm]][npm-url]
[![node][node]][node-url]
[![deps][deps]][deps-url]
[![tests][tests]][tests-url]
[![coverage][cover]][cover-url]
[![chat][chat]][chat-url]
[![size][size]][size-url]

# schema-utils

Package for validate options in loaders and plugins.

## Getting Started

To begin, you'll need to install `schema-utils`:

```console
npm install schema-utils
```

## API

**schema.json**

```json
{
  "type": "object",
  "properties": {
    "option": {
      "type": "boolean"
    }
  },
  "additionalProperties": false
}
```

```js
import schema from "./path/to/schema.json";
import { validate } from "schema-utils";

const options = { option: true };
const configuration = { name: "Loader Name/Plugin Name/Name" };

validate(schema, options, configuration);
```

### `schema`

Type: `String`

JSON schema.

Simple example of schema:

```json
{
  "type": "object",
  "properties": {
    "name": {
      "description": "This is description of option.",
      "type": "string"
    }
  },
  "additionalProperties": false
}
```

### `options`

Type: `Object`

Object with options.

```js
import schema from "./path/to/schema.json";
import { validate } from "schema-utils";

const options = { foo: "bar" };

validate(schema, { name: 123 }, { name: "MyPlugin" });
```

### `configuration`

Allow to configure validator.

There is an alternative method to configure the `name` and`baseDataPath` options via the `title` property in the schema.
For example:

```json
{
  "title": "My Loader options",
  "type": "object",
  "properties": {
    "name": {
      "description": "This is description of option.",
      "type": "string"
    }
  },
  "additionalProperties": false
}
```

The last word used for the `baseDataPath` option, other words used for the `name` option.
Based on the example above the `name` option equals `My Loader`, the `baseDataPath` option equals `options`.

#### `name`

Type: `Object`
Default: `"Object"`

Allow to setup name in validation errors.

```js
import schema from "./path/to/schema.json";
import { validate } from "schema-utils";

const options = { foo: "bar" };

validate(schema, options, { name: "MyPlugin" });
```

```shell
Invalid configuration object. MyPlugin has been initialised using a configuration object that does not match the API schema.
 - configuration.optionName should be a integer.
```

#### `baseDataPath`

Type: `String`
Default: `"configuration"`

Allow to setup base data path in validation errors.

```js
import schema from "./path/to/schema.json";
import { validate } from "schema-utils";

const options = { foo: "bar" };

validate(schema, options, { name: "MyPlugin", baseDataPath: "options" });
```

```shell
Invalid options object. MyPlugin has been initialised using an options object that does not match the API schema.
 - options.optionName should be a integer.
```

#### `postFormatter`

Type: `Function`
Default: `undefined`

Allow to reformat errors.

```js
import schema from "./path/to/schema.json";
import { validate } from "schema-utils";

const options = { foo: "bar" };

validate(schema, options, {
  name: "MyPlugin",
  postFormatter: (formattedError, error) => {
    if (error.keyword === "type") {
      return `${formattedError}\nAdditional Information.`;
    }

    return formattedError;
  },
});
```

```shell
Invalid options object. MyPlugin has been initialized using an options object that does not match the API schema.
 - options.optionName should be a integer.
   Additional Information.
```

## Examples

**schema.json**

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "test": {
      "anyOf": [
        { "type": "array" },
        { "type": "string" },
        { "instanceof": "RegExp" }
      ]
    },
    "transform": {
      "instanceof": "Function"
    },
    "sourceMap": {
      "type": "boolean"
    }
  },
  "additionalProperties": false
}
```

### `Loader`

```js
import { getOptions } from "loader-utils";
import { validate } from "schema-utils";

import schema from "path/to/schema.json";

function loader(src, map) {
  const options = getOptions(this);

  validate(schema, options, {
    name: "Loader Name",
    baseDataPath: "options",
  });

  // Code...
}

export default loader;
```

### `Plugin`

```js
import { validate } from "schema-utils";

import schema from "path/to/schema.json";

class Plugin {
  constructor(options) {
    validate(schema, options, {
      name: "Plugin Name",
      baseDataPath: "options",
    });

    this.options = options;
  }

  apply(compiler) {
    // Code...
  }
}

export default Plugin;
```

## Contributing

Please take a moment to read our contributing guidelines if you haven't yet done so.

[CONTRIBUTING](./.github/CONTRIBUTING.md)

## License

[MIT](./LICENSE)

[npm]: https://img.shields.io/npm/v/schema-utils.svg
[npm-url]: https://npmjs.com/package/schema-utils
[node]: https://img.shields.io/node/v/schema-utils.svg
[node-url]: https://nodejs.org
[deps]: https://david-dm.org/webpack/schema-utils.svg
[deps-url]: https://david-dm.org/webpack/schema-utils
[tests]: https://github.com/webpack/schema-utils/workflows/schema-utils/badge.svg
[tests-url]: https://github.com/webpack/schema-utils/actions
[cover]: https://codecov.io/gh/webpack/schema-utils/branch/master/graph/badge.svg
[cover-url]: https://codecov.io/gh/webpack/schema-utils
[chat]: https://badges.gitter.im/webpack/webpack.svg
[chat-url]: https://gitter.im/webpack/webpack
[size]: https://packagephobia.com/badge?p=schema-utils
[size-url]: https://packagephobia.com/result?p=schema-utils


---

# filesize.js

[![build status](https://secure.travis-ci.org/avoidwork/filesize.js.svg)](http://travis-ci.org/avoidwork/filesize.js)  [![downloads](https://img.shields.io/npm/dt/filesize.svg)](https://www.npmjs.com/package/filesize) [![CDNJS version](https://img.shields.io/cdnjs/v/filesize.svg)](https://cdnjs.com/libraries/filesize)

filesize.js provides a simple way to get a human readable file size string from a number (float or integer) or string.

## Optional settings

`filesize()` accepts an optional descriptor Object as a second argument, so you can customize the output.

### base
_*(number)*_ Number base, default is `10`

### bits
_*(boolean)*_ Enables `bit` sizes, default is `false`

### exponent
_*(number)*_ Specifies the symbol via exponent, e.g. `2` is `MB` for base 2, default is `-1`

### fullform
_*(boolean)*_ Enables full form of unit of measure, default is `false`

### fullforms
_*(array)*_ Array of full form overrides, default is `[]`

### locale (overrides 'separator')
_*(string || boolean)*_ BCP 47 language tag to specify a locale, or `true` to use default locale, default is `""`

### localeOptions (overrides 'separator', requires string for 'locale' option)
_*(object)*_ Dictionary of options defined by ECMA-402 ([Number.prototype.toLocaleString](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toLocaleString)). Requires locale option to be explicitly passed as a string, otherwise is ignored.

### output
_*(string)*_ Output of function (`array`, `exponent`, `object`, or `string`), default is `string`

### pad
_*(boolean)*_ Decimal place end padding, default is `false`

### precision
_*(number)*_ Sets precision of numerical output, default is `0`

### round
_*(number)*_ Decimal place, default is `2`

### roundingMethod
_*(string)*_ Rounding method, can be `round`, `floor`, or `ceil`, default is `round`

### separator
_*(string)*_ Decimal separator character, default is `.`

### spacer
_*(string)*_ Character between the `result` and `symbol`, default is `" "`

### standard
_*(string)*_ Standard unit of measure, can be `iec` or `jedec`, default is `iec`; can be overruled by `base`

### symbols
_*(object)*_ Dictionary of IEC/JEDEC symbols to replace for localization, defaults to english if no match is found

### unix
_*(boolean)*_ Enables unix style human readable output, e.g `ls -lh`, default is `false`

## Examples

```javascript
filesize(500);                        // "500 B"
filesize(500, {bits: true});          // "4 kbit"
filesize(265318, {base: 2});          // "259.1 KiB"
filesize(265318);                     // "265.32 kB"
filesize(265318, {round: 0});         // "265 kB"
filesize(265318, {output: "array"});  // [265.32, "kB"]
filesize(265318, {output: "object"}); // {value: 265.32, symbol: "kB", exponent: 1, unit: "kB"}
filesize(1, {symbols: {B: "Б"}});     // "1 Б"
filesize(1024);                       // "1.02 kB"
filesize(1024, {exponent: 0});        // "1024 B"
filesize(1024, {output: "exponent"}); // 1
filesize(265318, {standard: "jedec"});  // "259.1 KB"
filesize(265318, {base: 2, fullform: true}); // "259.1 kibibytes"
filesize(12, {fullform: true, fullforms: ["байтов"]});  // "12 байтов"
filesize(265318, {separator: ","});   // "265,32 kB"
filesize(265318, {locale: "de"});   // "265,32 kB"
```

## Partial Application
`filesize.partial()` takes the second parameter of `filesize()` and returns a new function with the configuration applied 
upon execution. This can be used to reduce `Object` creation if you call `filesize()` without caching the `descriptor` 
in lexical scope.

```javascript
const size = filesize.partial({base: 2, standard: "jedec"});

size(265318); // "259.1 KB"
```

## How can I load filesize.js?
filesize.js supports AMD loaders (require.js, curl.js, etc.), node.js & npm (```npm install filesize```), or using a script tag.

An ES6 version is bundled with an npm install, but requires you load it with the full path, e.g. `require(path.join(__dirname, 'node_modules', 'filesize', 'lib', 'filesize.es6.js'))`.

## License
Copyright (c) 2022 Jason Mulligan
Licensed under the BSD-3 license.


---

# fill-range [![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=W8YFZ425KND68) [![NPM version](https://img.shields.io/npm/v/fill-range.svg?style=flat)](https://www.npmjs.com/package/fill-range) [![NPM monthly downloads](https://img.shields.io/npm/dm/fill-range.svg?style=flat)](https://npmjs.org/package/fill-range) [![NPM total downloads](https://img.shields.io/npm/dt/fill-range.svg?style=flat)](https://npmjs.org/package/fill-range) [![Linux Build Status](https://img.shields.io/travis/jonschlinkert/fill-range.svg?style=flat&label=Travis)](https://travis-ci.org/jonschlinkert/fill-range)

> Fill in a range of numbers or letters, optionally passing an increment or `step` to use, or create a regex-compatible range with `options.toRegex`

Please consider following this project's author, [Jon Schlinkert](https://github.com/jonschlinkert), and consider starring the project to show your :heart: and support.

## Install

Install with [npm](https://www.npmjs.com/):

```sh
$ npm install --save fill-range
```

## Usage

Expands numbers and letters, optionally using a `step` as the last argument. _(Numbers may be defined as JavaScript numbers or strings)_.

```js
const fill = require('fill-range');
// fill(from, to[, step, options]);

console.log(fill('1', '10')); //=> ['1', '2', '3', '4', '5', '6', '7', '8', '9', '10']
console.log(fill('1', '10', { toRegex: true })); //=> [1-9]|10
```

**Params**

* `from`: **{String|Number}** the number or letter to start with
* `to`: **{String|Number}** the number or letter to end with
* `step`: **{String|Number|Object|Function}** Optionally pass a [step](#optionsstep) to use.
* `options`: **{Object|Function}**: See all available [options](#options)

## Examples

By default, an array of values is returned.

**Alphabetical ranges**

```js
console.log(fill('a', 'e')); //=> ['a', 'b', 'c', 'd', 'e']
console.log(fill('A', 'E')); //=> [ 'A', 'B', 'C', 'D', 'E' ]
```

**Numerical ranges**

Numbers can be defined as actual numbers or strings.

```js
console.log(fill(1, 5));     //=> [ 1, 2, 3, 4, 5 ]
console.log(fill('1', '5')); //=> [ 1, 2, 3, 4, 5 ]
```

**Negative ranges**

Numbers can be defined as actual numbers or strings.

```js
console.log(fill('-5', '-1')); //=> [ '-5', '-4', '-3', '-2', '-1' ]
console.log(fill('-5', '5')); //=> [ '-5', '-4', '-3', '-2', '-1', '0', '1', '2', '3', '4', '5' ]
```

**Steps (increments)**

```js
// numerical ranges with increments
console.log(fill('0', '25', 4)); //=> [ '0', '4', '8', '12', '16', '20', '24' ]
console.log(fill('0', '25', 5)); //=> [ '0', '5', '10', '15', '20', '25' ]
console.log(fill('0', '25', 6)); //=> [ '0', '6', '12', '18', '24' ]

// alphabetical ranges with increments
console.log(fill('a', 'z', 4)); //=> [ 'a', 'e', 'i', 'm', 'q', 'u', 'y' ]
console.log(fill('a', 'z', 5)); //=> [ 'a', 'f', 'k', 'p', 'u', 'z' ]
console.log(fill('a', 'z', 6)); //=> [ 'a', 'g', 'm', 's', 'y' ]
```

## Options

### options.step

**Type**: `number` (formatted as a string or number)

**Default**: `undefined`

**Description**: The increment to use for the range. Can be used with letters or numbers.

**Example(s)**

```js
// numbers
console.log(fill('1', '10', 2)); //=> [ '1', '3', '5', '7', '9' ]
console.log(fill('1', '10', 3)); //=> [ '1', '4', '7', '10' ]
console.log(fill('1', '10', 4)); //=> [ '1', '5', '9' ]

// letters
console.log(fill('a', 'z', 5)); //=> [ 'a', 'f', 'k', 'p', 'u', 'z' ]
console.log(fill('a', 'z', 7)); //=> [ 'a', 'h', 'o', 'v' ]
console.log(fill('a', 'z', 9)); //=> [ 'a', 'j', 's' ]
```

### options.strictRanges

**Type**: `boolean`

**Default**: `false`

**Description**: By default, `null` is returned when an invalid range is passed. Enable this option to throw a `RangeError` on invalid ranges.

**Example(s)**

The following are all invalid:

```js
fill('1.1', '2');   // decimals not supported in ranges
fill('a', '2');     // incompatible range values
fill(1, 10, 'foo'); // invalid "step" argument
```

### options.stringify

**Type**: `boolean`

**Default**: `undefined`

**Description**: Cast all returned values to strings. By default, integers are returned as numbers.

**Example(s)**

```js
console.log(fill(1, 5));                    //=> [ 1, 2, 3, 4, 5 ]
console.log(fill(1, 5, { stringify: true })); //=> [ '1', '2', '3', '4', '5' ]
```

### options.toRegex

**Type**: `boolean`

**Default**: `undefined`

**Description**: Create a regex-compatible source string, instead of expanding values to an array.

**Example(s)**

```js
// alphabetical range
console.log(fill('a', 'e', { toRegex: true })); //=> '[a-e]'
// alphabetical with step
console.log(fill('a', 'z', 3, { toRegex: true })); //=> 'a|d|g|j|m|p|s|v|y'
// numerical range
console.log(fill('1', '100', { toRegex: true })); //=> '[1-9]|[1-9][0-9]|100'
// numerical range with zero padding
console.log(fill('000001', '100000', { toRegex: true }));
//=> '0{5}[1-9]|0{4}[1-9][0-9]|0{3}[1-9][0-9]{2}|0{2}[1-9][0-9]{3}|0[1-9][0-9]{4}|100000'
```

### options.transform

**Type**: `function`

**Default**: `undefined`

**Description**: Customize each value in the returned array (or [string](#optionstoRegex)). _(you can also pass this function as the last argument to `fill()`)_.

**Example(s)**

```js
// add zero padding
console.log(fill(1, 5, value => String(value).padStart(4, '0')));
//=> ['0001', '0002', '0003', '0004', '0005']
```

## About

<details>
<summary><strong>Contributing</strong></summary>

Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).

</details>

<details>
<summary><strong>Running Tests</strong></summary>

Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

```sh
$ npm install && npm test
```

</details>

<details>
<summary><strong>Building docs</strong></summary>

_(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_

To generate the readme, run the following command:

```sh
$ npm install -g verbose/verb#dev verb-generate-readme && verb
```

</details>

### Contributors

| **Commits** | **Contributor** |  
| --- | --- |  
| 116 | [jonschlinkert](https://github.com/jonschlinkert) |  
| 4   | [paulmillr](https://github.com/paulmillr) |  
| 2   | [realityking](https://github.com/realityking) |  
| 2   | [bluelovers](https://github.com/bluelovers) |  
| 1   | [edorivai](https://github.com/edorivai) |  
| 1   | [wtgtybhertgeghgtwtg](https://github.com/wtgtybhertgeghgtwtg) |  

### Author

**Jon Schlinkert**

* [GitHub Profile](https://github.com/jonschlinkert)
* [Twitter Profile](https://twitter.com/jonschlinkert)
* [LinkedIn Profile](https://linkedin.com/in/jonschlinkert)

Please consider supporting me on Patreon, or [start your own Patreon page](https://patreon.com/invite/bxpbvm)!

<a href="https://www.patreon.com/jonschlinkert">
<img src="https://c5.patreon.com/external/logo/become_a_patron_button@2x.png" height="50">
</a>

### License

Copyright © 2019, [Jon Schlinkert](https://github.com/jonschlinkert).
Released under the [MIT License](LICENSE).

***

_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.8.0, on April 08, 2019._

---

v1.3.1 / 2024-09-11
==================

  * deps: encodeurl@~2.0.0

v1.3.0 / 2024-09-03
==================

  * ignore status message for HTTP/2 (#53)

v1.2.1 / 2024-09-02
==================

  * Gracefully handle when handling an error and socket is null

1.2.0 / 2022-03-22
==================

  * Remove set content headers that break response
  * deps: on-finished@2.4.1
  * deps: statuses@2.0.1
    - Rename `425 Unordered Collection` to standard `425 Too Early`

1.1.2 / 2019-05-09
==================

  * Set stricter `Content-Security-Policy` header
  * deps: parseurl@~1.3.3
  * deps: statuses@~1.5.0

1.1.1 / 2018-03-06
==================

  * Fix 404 output for bad / missing pathnames
  * deps: encodeurl@~1.0.2
    - Fix encoding `%` as last character
  * deps: statuses@~1.4.0

1.1.0 / 2017-09-24
==================

  * Use `res.headersSent` when available

1.0.6 / 2017-09-22
==================

  * deps: debug@2.6.9

1.0.5 / 2017-09-15
==================

  * deps: parseurl@~1.3.2
    - perf: reduce overhead for full URLs
    - perf: unroll the "fast-path" `RegExp`

1.0.4 / 2017-08-03
==================

  * deps: debug@2.6.8

1.0.3 / 2017-05-16
==================

  * deps: debug@2.6.7
    - deps: ms@2.0.0

1.0.2 / 2017-04-22
==================

  * deps: debug@2.6.4
    - deps: ms@0.7.3

1.0.1 / 2017-03-21
==================

  * Fix missing `</html>` in HTML document
  * deps: debug@2.6.3
    - Fix: `DEBUG_MAX_ARRAY_LENGTH`

1.0.0 / 2017-02-15
==================

  * Fix exception when `err` cannot be converted to a string
  * Fully URL-encode the pathname in the 404 message
  * Only include the pathname in the 404 message
  * Send complete HTML document
  * Set `Content-Security-Policy: default-src 'self'` header
  * deps: debug@2.6.1
    - Allow colors in workers
    - Deprecated `DEBUG_FD` environment variable set to `3` or higher
    - Fix error when running under React Native
    - Use same color for same namespace
    - deps: ms@0.7.2

0.5.1 / 2016-11-12
==================

  * Fix exception when `err.headers` is not an object
  * deps: statuses@~1.3.1
  * perf: hoist regular expressions
  * perf: remove duplicate validation path

0.5.0 / 2016-06-15
==================

  * Change invalid or non-numeric status code to 500
  * Overwrite status message to match set status code
  * Prefer `err.statusCode` if `err.status` is invalid
  * Set response headers from `err.headers` object
  * Use `statuses` instead of `http` module for status messages
    - Includes all defined status messages

0.4.1 / 2015-12-02
==================

  * deps: escape-html@~1.0.3
    - perf: enable strict mode
    - perf: optimize string replacement
    - perf: use faster string coercion

0.4.0 / 2015-06-14
==================

  * Fix a false-positive when unpiping in Node.js 0.8
  * Support `statusCode` property on `Error` objects
  * Use `unpipe` module for unpiping requests
  * deps: escape-html@1.0.2
  * deps: on-finished@~2.3.0
    - Add defined behavior for HTTP `CONNECT` requests
    - Add defined behavior for HTTP `Upgrade` requests
    - deps: ee-first@1.1.1
  * perf: enable strict mode
  * perf: remove argument reassignment

0.3.6 / 2015-05-11
==================

  * deps: debug@~2.2.0
    - deps: ms@0.7.1

0.3.5 / 2015-04-22
==================

  * deps: on-finished@~2.2.1
    - Fix `isFinished(req)` when data buffered

0.3.4 / 2015-03-15
==================

  * deps: debug@~2.1.3
    - Fix high intensity foreground color for bold
    - deps: ms@0.7.0

0.3.3 / 2015-01-01
==================

  * deps: debug@~2.1.1
  * deps: on-finished@~2.2.0

0.3.2 / 2014-10-22
==================

  * deps: on-finished@~2.1.1
    - Fix handling of pipelined requests

0.3.1 / 2014-10-16
==================

  * deps: debug@~2.1.0
    - Implement `DEBUG_FD` env variable support

0.3.0 / 2014-09-17
==================

  * Terminate in progress response only on error
  * Use `on-finished` to determine request status

0.2.0 / 2014-09-03
==================

  * Set `X-Content-Type-Options: nosniff` header
  * deps: debug@~2.0.0

0.1.0 / 2014-07-16
==================

  * Respond after request fully read
    - prevents hung responses and socket hang ups
  * deps: debug@1.0.4

0.0.3 / 2014-07-11
==================

  * deps: debug@1.0.3
    - Add support for multiple wildcards in namespaces

0.0.2 / 2014-06-19
==================

  * Handle invalid status codes

0.0.1 / 2014-06-05
==================

  * deps: debug@1.0.2

0.0.0 / 2014-06-05
==================

  * Extracted from connect/express


---

# finalhandler

[![NPM Version][npm-image]][npm-url]
[![NPM Downloads][downloads-image]][downloads-url]
[![Node.js Version][node-image]][node-url]
[![Build Status][github-actions-ci-image]][github-actions-ci-url]
[![Test Coverage][coveralls-image]][coveralls-url]

Node.js function to invoke as the final step to respond to HTTP request.

## Installation

This is a [Node.js](https://nodejs.org/en/) module available through the
[npm registry](https://www.npmjs.com/). Installation is done using the
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):

```sh
$ npm install finalhandler
```

## API

```js
var finalhandler = require('finalhandler')
```

### finalhandler(req, res, [options])

Returns function to be invoked as the final step for the given `req` and `res`.
This function is to be invoked as `fn(err)`. If `err` is falsy, the handler will
write out a 404 response to the `res`. If it is truthy, an error response will
be written out to the `res` or `res` will be terminated if a response has already
started.

When an error is written, the following information is added to the response:

  * The `res.statusCode` is set from `err.status` (or `err.statusCode`). If
    this value is outside the 4xx or 5xx range, it will be set to 500.
  * The `res.statusMessage` is set according to the status code.
  * The body will be the HTML of the status code message if `env` is
    `'production'`, otherwise will be `err.stack`.
  * Any headers specified in an `err.headers` object.

The final handler will also unpipe anything from `req` when it is invoked.

#### options.env

By default, the environment is determined by `NODE_ENV` variable, but it can be
overridden by this option.

#### options.onerror

Provide a function to be called with the `err` when it exists. Can be used for
writing errors to a central location without excessive function generation. Called
as `onerror(err, req, res)`.

## Examples

### always 404

```js
var finalhandler = require('finalhandler')
var http = require('http')

var server = http.createServer(function (req, res) {
  var done = finalhandler(req, res)
  done()
})

server.listen(3000)
```

### perform simple action

```js
var finalhandler = require('finalhandler')
var fs = require('fs')
var http = require('http')

var server = http.createServer(function (req, res) {
  var done = finalhandler(req, res)

  fs.readFile('index.html', function (err, buf) {
    if (err) return done(err)
    res.setHeader('Content-Type', 'text/html')
    res.end(buf)
  })
})

server.listen(3000)
```

### use with middleware-style functions

```js
var finalhandler = require('finalhandler')
var http = require('http')
var serveStatic = require('serve-static')

var serve = serveStatic('public')

var server = http.createServer(function (req, res) {
  var done = finalhandler(req, res)
  serve(req, res, done)
})

server.listen(3000)
```

### keep log of all errors

```js
var finalhandler = require('finalhandler')
var fs = require('fs')
var http = require('http')

var server = http.createServer(function (req, res) {
  var done = finalhandler(req, res, { onerror: logerror })

  fs.readFile('index.html', function (err, buf) {
    if (err) return done(err)
    res.setHeader('Content-Type', 'text/html')
    res.end(buf)
  })
})

server.listen(3000)

function logerror (err) {
  console.error(err.stack || err.toString())
}
```

## License

[MIT](LICENSE)

[npm-image]: https://img.shields.io/npm/v/finalhandler.svg
[npm-url]: https://npmjs.org/package/finalhandler
[node-image]: https://img.shields.io/node/v/finalhandler.svg
[node-url]: https://nodejs.org/en/download
[coveralls-image]: https://img.shields.io/coveralls/pillarjs/finalhandler.svg
[coveralls-url]: https://coveralls.io/r/pillarjs/finalhandler?branch=master
[downloads-image]: https://img.shields.io/npm/dm/finalhandler.svg
[downloads-url]: https://npmjs.org/package/finalhandler
[github-actions-ci-image]: https://github.com/pillarjs/finalhandler/actions/workflows/ci.yml/badge.svg
[github-actions-ci-url]: https://github.com/pillarjs/finalhandler/actions/workflows/ci.yml


---

# Security Policies and Procedures

## Reporting a Bug

The `finalhandler` team and community take all security bugs seriously. Thank
you for improving the security of Express. We appreciate your efforts and
responsible disclosure and will make every effort to acknowledge your
contributions.

Report security bugs by emailing the current owner(s) of `finalhandler`. This
information can be found in the npm registry using the command
`npm owner ls finalhandler`.
If unsure or unable to get the information from the above, open an issue
in the [project issue tracker](https://github.com/pillarjs/finalhandler/issues)
asking for the current contact information.

To ensure the timely response to your report, please ensure that the entirety
of the report is contained within the email body and not solely behind a web
link or an attachment.

At least one owner will acknowledge your email within 48 hours, and will send a
more detailed response within 48 hours indicating the next steps in handling
your report. After the initial reply to your report, the owners will
endeavor to keep you informed of the progress towards a fix and full
announcement, and may ask for additional information or guidance.


---


2.6.9 / 2017-09-22
==================

  * remove ReDoS regexp in %o formatter (#504)

2.6.8 / 2017-05-18
==================

  * Fix: Check for undefined on browser globals (#462, @marbemac)

2.6.7 / 2017-05-16
==================

  * Fix: Update ms to 2.0.0 to fix regular expression denial of service vulnerability (#458, @hubdotcom)
  * Fix: Inline extend function in node implementation (#452, @dougwilson)
  * Docs: Fix typo (#455, @msasad)

2.6.5 / 2017-04-27
==================
  
  * Fix: null reference check on window.documentElement.style.WebkitAppearance (#447, @thebigredgeek)
  * Misc: clean up browser reference checks (#447, @thebigredgeek)
  * Misc: add npm-debug.log to .gitignore (@thebigredgeek)


2.6.4 / 2017-04-20
==================

  * Fix: bug that would occure if process.env.DEBUG is a non-string value. (#444, @LucianBuzzo)
  * Chore: ignore bower.json in npm installations. (#437, @joaovieira)
  * Misc: update "ms" to v0.7.3 (@tootallnate)

2.6.3 / 2017-03-13
==================

  * Fix: Electron reference to `process.env.DEBUG` (#431, @paulcbetts)
  * Docs: Changelog fix (@thebigredgeek)

2.6.2 / 2017-03-10
==================

  * Fix: DEBUG_MAX_ARRAY_LENGTH (#420, @slavaGanzin)
  * Docs: Add backers and sponsors from Open Collective (#422, @piamancini)
  * Docs: Add Slackin invite badge (@tootallnate)

2.6.1 / 2017-02-10
==================

  * Fix: Module's `export default` syntax fix for IE8 `Expected identifier` error
  * Fix: Whitelist DEBUG_FD for values 1 and 2 only (#415, @pi0)
  * Fix: IE8 "Expected identifier" error (#414, @vgoma)
  * Fix: Namespaces would not disable once enabled (#409, @musikov)

2.6.0 / 2016-12-28
==================

  * Fix: added better null pointer checks for browser useColors (@thebigredgeek)
  * Improvement: removed explicit `window.debug` export (#404, @tootallnate)
  * Improvement: deprecated `DEBUG_FD` environment variable (#405, @tootallnate)

2.5.2 / 2016-12-25
==================

  * Fix: reference error on window within webworkers (#393, @KlausTrainer)
  * Docs: fixed README typo (#391, @lurch)
  * Docs: added notice about v3 api discussion (@thebigredgeek)

2.5.1 / 2016-12-20
==================

  * Fix: babel-core compatibility

2.5.0 / 2016-12-20
==================

  * Fix: wrong reference in bower file (@thebigredgeek)
  * Fix: webworker compatibility (@thebigredgeek)
  * Fix: output formatting issue (#388, @kribblo)
  * Fix: babel-loader compatibility (#383, @escwald)
  * Misc: removed built asset from repo and publications (@thebigredgeek)
  * Misc: moved source files to /src (#378, @yamikuronue)
  * Test: added karma integration and replaced babel with browserify for browser tests (#378, @yamikuronue)
  * Test: coveralls integration (#378, @yamikuronue)
  * Docs: simplified language in the opening paragraph (#373, @yamikuronue)

2.4.5 / 2016-12-17
==================

  * Fix: `navigator` undefined in Rhino (#376, @jochenberger)
  * Fix: custom log function (#379, @hsiliev)
  * Improvement: bit of cleanup + linting fixes (@thebigredgeek)
  * Improvement: rm non-maintainted `dist/` dir (#375, @freewil)
  * Docs: simplified language in the opening paragraph. (#373, @yamikuronue)

2.4.4 / 2016-12-14
==================

  * Fix: work around debug being loaded in preload scripts for electron (#368, @paulcbetts)

2.4.3 / 2016-12-14
==================

  * Fix: navigation.userAgent error for react native (#364, @escwald)

2.4.2 / 2016-12-14
==================

  * Fix: browser colors (#367, @tootallnate)
  * Misc: travis ci integration (@thebigredgeek)
  * Misc: added linting and testing boilerplate with sanity check (@thebigredgeek)

2.4.1 / 2016-12-13
==================

  * Fix: typo that broke the package (#356)

2.4.0 / 2016-12-13
==================

  * Fix: bower.json references unbuilt src entry point (#342, @justmatt)
  * Fix: revert "handle regex special characters" (@tootallnate)
  * Feature: configurable util.inspect()`options for NodeJS (#327, @tootallnate)
  * Feature: %O`(big O) pretty-prints objects (#322, @tootallnate)
  * Improvement: allow colors in workers (#335, @botverse)
  * Improvement: use same color for same namespace. (#338, @lchenay)

2.3.3 / 2016-11-09
==================

  * Fix: Catch `JSON.stringify()` errors (#195, Jovan Alleyne)
  * Fix: Returning `localStorage` saved values (#331, Levi Thomason)
  * Improvement: Don't create an empty object when no `process` (Nathan Rajlich)

2.3.2 / 2016-11-09
==================

  * Fix: be super-safe in index.js as well (@TooTallNate)
  * Fix: should check whether process exists (Tom Newby)

2.3.1 / 2016-11-09
==================

  * Fix: Added electron compatibility (#324, @paulcbetts)
  * Improvement: Added performance optimizations (@tootallnate)
  * Readme: Corrected PowerShell environment variable example (#252, @gimre)
  * Misc: Removed yarn lock file from source control (#321, @fengmk2)

2.3.0 / 2016-11-07
==================

  * Fix: Consistent placement of ms diff at end of output (#215, @gorangajic)
  * Fix: Escaping of regex special characters in namespace strings (#250, @zacronos)
  * Fix: Fixed bug causing crash on react-native (#282, @vkarpov15)
  * Feature: Enabled ES6+ compatible import via default export (#212 @bucaran)
  * Feature: Added %O formatter to reflect Chrome's console.log capability (#279, @oncletom)
  * Package: Update "ms" to 0.7.2 (#315, @DevSide)
  * Package: removed superfluous version property from bower.json (#207 @kkirsche)
  * Readme: fix USE_COLORS to DEBUG_COLORS
  * Readme: Doc fixes for format string sugar (#269, @mlucool)
  * Readme: Updated docs for DEBUG_FD and DEBUG_COLORS environment variables (#232, @mattlyons0)
  * Readme: doc fixes for PowerShell (#271 #243, @exoticknight @unreadable)
  * Readme: better docs for browser support (#224, @matthewmueller)
  * Tooling: Added yarn integration for development (#317, @thebigredgeek)
  * Misc: Renamed History.md to CHANGELOG.md (@thebigredgeek)
  * Misc: Added license file (#226 #274, @CantemoInternal @sdaitzman)
  * Misc: Updated contributors (@thebigredgeek)

2.2.0 / 2015-05-09
==================

  * package: update "ms" to v0.7.1 (#202, @dougwilson)
  * README: add logging to file example (#193, @DanielOchoa)
  * README: fixed a typo (#191, @amir-s)
  * browser: expose `storage` (#190, @stephenmathieson)
  * Makefile: add a `distclean` target (#189, @stephenmathieson)

2.1.3 / 2015-03-13
==================

  * Updated stdout/stderr example (#186)
  * Updated example/stdout.js to match debug current behaviour
  * Renamed example/stderr.js to stdout.js
  * Update Readme.md (#184)
  * replace high intensity foreground color for bold (#182, #183)

2.1.2 / 2015-03-01
==================

  * dist: recompile
  * update "ms" to v0.7.0
  * package: update "browserify" to v9.0.3
  * component: fix "ms.js" repo location
  * changed bower package name
  * updated documentation about using debug in a browser
  * fix: security error on safari (#167, #168, @yields)

2.1.1 / 2014-12-29
==================

  * browser: use `typeof` to check for `console` existence
  * browser: check for `console.log` truthiness (fix IE 8/9)
  * browser: add support for Chrome apps
  * Readme: added Windows usage remarks
  * Add `bower.json` to properly support bower install

2.1.0 / 2014-10-15
==================

  * node: implement `DEBUG_FD` env variable support
  * package: update "browserify" to v6.1.0
  * package: add "license" field to package.json (#135, @panuhorsmalahti)

2.0.0 / 2014-09-01
==================

  * package: update "browserify" to v5.11.0
  * node: use stderr rather than stdout for logging (#29, @stephenmathieson)

1.0.4 / 2014-07-15
==================

  * dist: recompile
  * example: remove `console.info()` log usage
  * example: add "Content-Type" UTF-8 header to browser example
  * browser: place %c marker after the space character
  * browser: reset the "content" color via `color: inherit`
  * browser: add colors support for Firefox >= v31
  * debug: prefer an instance `log()` function over the global one (#119)
  * Readme: update documentation about styled console logs for FF v31 (#116, @wryk)

1.0.3 / 2014-07-09
==================

  * Add support for multiple wildcards in namespaces (#122, @seegno)
  * browser: fix lint

1.0.2 / 2014-06-10
==================

  * browser: update color palette (#113, @gscottolson)
  * common: make console logging function configurable (#108, @timoxley)
  * node: fix %o colors on old node <= 0.8.x
  * Makefile: find node path using shell/which (#109, @timoxley)

1.0.1 / 2014-06-06
==================

  * browser: use `removeItem()` to clear localStorage
  * browser, node: don't set DEBUG if namespaces is undefined (#107, @leedm777)
  * package: add "contributors" section
  * node: fix comment typo
  * README: list authors

1.0.0 / 2014-06-04
==================

  * make ms diff be global, not be scope
  * debug: ignore empty strings in enable()
  * node: make DEBUG_COLORS able to disable coloring
  * *: export the `colors` array
  * npmignore: don't publish the `dist` dir
  * Makefile: refactor to use browserify
  * package: add "browserify" as a dev dependency
  * Readme: add Web Inspector Colors section
  * node: reset terminal color for the debug content
  * node: map "%o" to `util.inspect()`
  * browser: map "%j" to `JSON.stringify()`
  * debug: add custom "formatters"
  * debug: use "ms" module for humanizing the diff
  * Readme: add "bash" syntax highlighting
  * browser: add Firebug color support
  * browser: add colors for WebKit browsers
  * node: apply log to `console`
  * rewrite: abstract common logic for Node & browsers
  * add .jshintrc file

0.8.1 / 2014-04-14
==================

  * package: re-add the "component" section

0.8.0 / 2014-03-30
==================

  * add `enable()` method for nodejs. Closes #27
  * change from stderr to stdout
  * remove unnecessary index.js file

0.7.4 / 2013-11-13
==================

  * remove "browserify" key from package.json (fixes something in browserify)

0.7.3 / 2013-10-30
==================

  * fix: catch localStorage security error when cookies are blocked (Chrome)
  * add debug(err) support. Closes #46
  * add .browser prop to package.json. Closes #42

0.7.2 / 2013-02-06
==================

  * fix package.json
  * fix: Mobile Safari (private mode) is broken with debug
  * fix: Use unicode to send escape character to shell instead of octal to work with strict mode javascript

0.7.1 / 2013-02-05
==================

  * add repository URL to package.json
  * add DEBUG_COLORED to force colored output
  * add browserify support
  * fix component. Closes #24

0.7.0 / 2012-05-04
==================

  * Added .component to package.json
  * Added debug.component.js build

0.6.0 / 2012-03-16
==================

  * Added support for "-" prefix in DEBUG [Vinay Pulim]
  * Added `.enabled` flag to the node version [TooTallNate]

0.5.0 / 2012-02-02
==================

  * Added: humanize diffs. Closes #8
  * Added `debug.disable()` to the CS variant
  * Removed padding. Closes #10
  * Fixed: persist client-side variant again. Closes #9

0.4.0 / 2012-02-01
==================

  * Added browser variant support for older browsers [TooTallNate]
  * Added `debug.enable('project:*')` to browser variant [TooTallNate]
  * Added padding to diff (moved it to the right)

0.3.0 / 2012-01-26
==================

  * Added millisecond diff when isatty, otherwise UTC string

0.2.0 / 2012-01-22
==================

  * Added wildcard support

0.1.0 / 2011-12-02
==================

  * Added: remove colors unless stderr isatty [TooTallNate]

0.0.1 / 2010-01-03
==================

  * Initial release


---

# debug
[![Build Status](https://travis-ci.org/visionmedia/debug.svg?branch=master)](https://travis-ci.org/visionmedia/debug)  [![Coverage Status](https://coveralls.io/repos/github/visionmedia/debug/badge.svg?branch=master)](https://coveralls.io/github/visionmedia/debug?branch=master)  [![Slack](https://visionmedia-community-slackin.now.sh/badge.svg)](https://visionmedia-community-slackin.now.sh/) [![OpenCollective](https://opencollective.com/debug/backers/badge.svg)](#backers) 
[![OpenCollective](https://opencollective.com/debug/sponsors/badge.svg)](#sponsors)



A tiny node.js debugging utility modelled after node core's debugging technique.

**Discussion around the V3 API is under way [here](https://github.com/visionmedia/debug/issues/370)**

## Installation

```bash
$ npm install debug
```

## Usage

`debug` exposes a function; simply pass this function the name of your module, and it will return a decorated version of `console.error` for you to pass debug statements to. This will allow you to toggle the debug output for different parts of your module as well as the module as a whole.

Example _app.js_:

```js
var debug = require('debug')('http')
  , http = require('http')
  , name = 'My App';

// fake app

debug('booting %s', name);

http.createServer(function(req, res){
  debug(req.method + ' ' + req.url);
  res.end('hello\n');
}).listen(3000, function(){
  debug('listening');
});

// fake worker of some kind

require('./worker');
```

Example _worker.js_:

```js
var debug = require('debug')('worker');

setInterval(function(){
  debug('doing some work');
}, 1000);
```

 The __DEBUG__ environment variable is then used to enable these based on space or comma-delimited names. Here are some examples:

  ![debug http and worker](http://f.cl.ly/items/18471z1H402O24072r1J/Screenshot.png)

  ![debug worker](http://f.cl.ly/items/1X413v1a3M0d3C2c1E0i/Screenshot.png)

#### Windows note

 On Windows the environment variable is set using the `set` command.

 ```cmd
 set DEBUG=*,-not_this
 ```

 Note that PowerShell uses different syntax to set environment variables.

 ```cmd
 $env:DEBUG = "*,-not_this"
  ```

Then, run the program to be debugged as usual.

## Millisecond diff

  When actively developing an application it can be useful to see when the time spent between one `debug()` call and the next. Suppose for example you invoke `debug()` before requesting a resource, and after as well, the "+NNNms" will show you how much time was spent between calls.

  ![](http://f.cl.ly/items/2i3h1d3t121M2Z1A3Q0N/Screenshot.png)

  When stdout is not a TTY, `Date#toUTCString()` is used, making it more useful for logging the debug information as shown below:

  ![](http://f.cl.ly/items/112H3i0e0o0P0a2Q2r11/Screenshot.png)

## Conventions

  If you're using this in one or more of your libraries, you _should_ use the name of your library so that developers may toggle debugging as desired without guessing names. If you have more than one debuggers you _should_ prefix them with your library name and use ":" to separate features. For example "bodyParser" from Connect would then be "connect:bodyParser".

## Wildcards

  The `*` character may be used as a wildcard. Suppose for example your library has debuggers named "connect:bodyParser", "connect:compress", "connect:session", instead of listing all three with `DEBUG=connect:bodyParser,connect:compress,connect:session`, you may simply do `DEBUG=connect:*`, or to run everything using this module simply use `DEBUG=*`.

  You can also exclude specific debuggers by prefixing them with a "-" character.  For example, `DEBUG=*,-connect:*` would include all debuggers except those starting with "connect:".

## Environment Variables

  When running through Node.js, you can set a few environment variables that will
  change the behavior of the debug logging:

| Name      | Purpose                                         |
|-----------|-------------------------------------------------|
| `DEBUG`   | Enables/disables specific debugging namespaces. |
| `DEBUG_COLORS`| Whether or not to use colors in the debug output. |
| `DEBUG_DEPTH` | Object inspection depth. |
| `DEBUG_SHOW_HIDDEN` | Shows hidden properties on inspected objects. |


  __Note:__ The environment variables beginning with `DEBUG_` end up being
  converted into an Options object that gets used with `%o`/`%O` formatters.
  See the Node.js documentation for
  [`util.inspect()`](https://nodejs.org/api/util.html#util_util_inspect_object_options)
  for the complete list.

## Formatters


  Debug uses [printf-style](https://wikipedia.org/wiki/Printf_format_string) formatting. Below are the officially supported formatters:

| Formatter | Representation |
|-----------|----------------|
| `%O`      | Pretty-print an Object on multiple lines. |
| `%o`      | Pretty-print an Object all on a single line. |
| `%s`      | String. |
| `%d`      | Number (both integer and float). |
| `%j`      | JSON. Replaced with the string '[Circular]' if the argument contains circular references. |
| `%%`      | Single percent sign ('%'). This does not consume an argument. |

### Custom formatters

  You can add custom formatters by extending the `debug.formatters` object. For example, if you wanted to add support for rendering a Buffer as hex with `%h`, you could do something like:

```js
const createDebug = require('debug')
createDebug.formatters.h = (v) => {
  return v.toString('hex')
}

// …elsewhere
const debug = createDebug('foo')
debug('this is hex: %h', new Buffer('hello world'))
//   foo this is hex: 68656c6c6f20776f726c6421 +0ms
```

## Browser support
  You can build a browser-ready script using [browserify](https://github.com/substack/node-browserify),
  or just use the [browserify-as-a-service](https://wzrd.in/) [build](https://wzrd.in/standalone/debug@latest),
  if you don't want to build it yourself.

  Debug's enable state is currently persisted by `localStorage`.
  Consider the situation shown below where you have `worker:a` and `worker:b`,
  and wish to debug both. You can enable this using `localStorage.debug`:

```js
localStorage.debug = 'worker:*'
```

And then refresh the page.

```js
a = debug('worker:a');
b = debug('worker:b');

setInterval(function(){
  a('doing some work');
}, 1000);

setInterval(function(){
  b('doing some work');
}, 1200);
```

#### Web Inspector Colors

  Colors are also enabled on "Web Inspectors" that understand the `%c` formatting
  option. These are WebKit web inspectors, Firefox ([since version
  31](https://hacks.mozilla.org/2014/05/editable-box-model-multiple-selection-sublime-text-keys-much-more-firefox-developer-tools-episode-31/))
  and the Firebug plugin for Firefox (any version).

  Colored output looks something like:

  ![](https://cloud.githubusercontent.com/assets/71256/3139768/b98c5fd8-e8ef-11e3-862a-f7253b6f47c6.png)


## Output streams

  By default `debug` will log to stderr, however this can be configured per-namespace by overriding the `log` method:

Example _stdout.js_:

```js
var debug = require('debug');
var error = debug('app:error');

// by default stderr is used
error('goes to stderr!');

var log = debug('app:log');
// set this namespace to log via console.log
log.log = console.log.bind(console); // don't forget to bind to console!
log('goes to stdout');
error('still goes to stderr!');

// set all output to go via console.info
// overrides all per-namespace log settings
debug.log = console.info.bind(console);
error('now goes to stdout via console.info');
log('still goes to stdout, but via console.info now');
```


## Authors

 - TJ Holowaychuk
 - Nathan Rajlich
 - Andrew Rhyne
 
## Backers

Support us with a monthly donation and help us continue our activities. [[Become a backer](https://opencollective.com/debug#backer)]

<a href="https://opencollective.com/debug/backer/0/website" target="_blank"><img src="https://opencollective.com/debug/backer/0/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/1/website" target="_blank"><img src="https://opencollective.com/debug/backer/1/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/2/website" target="_blank"><img src="https://opencollective.com/debug/backer/2/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/3/website" target="_blank"><img src="https://opencollective.com/debug/backer/3/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/4/website" target="_blank"><img src="https://opencollective.com/debug/backer/4/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/5/website" target="_blank"><img src="https://opencollective.com/debug/backer/5/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/6/website" target="_blank"><img src="https://opencollective.com/debug/backer/6/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/7/website" target="_blank"><img src="https://opencollective.com/debug/backer/7/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/8/website" target="_blank"><img src="https://opencollective.com/debug/backer/8/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/9/website" target="_blank"><img src="https://opencollective.com/debug/backer/9/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/10/website" target="_blank"><img src="https://opencollective.com/debug/backer/10/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/11/website" target="_blank"><img src="https://opencollective.com/debug/backer/11/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/12/website" target="_blank"><img src="https://opencollective.com/debug/backer/12/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/13/website" target="_blank"><img src="https://opencollective.com/debug/backer/13/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/14/website" target="_blank"><img src="https://opencollective.com/debug/backer/14/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/15/website" target="_blank"><img src="https://opencollective.com/debug/backer/15/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/16/website" target="_blank"><img src="https://opencollective.com/debug/backer/16/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/17/website" target="_blank"><img src="https://opencollective.com/debug/backer/17/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/18/website" target="_blank"><img src="https://opencollective.com/debug/backer/18/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/19/website" target="_blank"><img src="https://opencollective.com/debug/backer/19/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/20/website" target="_blank"><img src="https://opencollective.com/debug/backer/20/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/21/website" target="_blank"><img src="https://opencollective.com/debug/backer/21/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/22/website" target="_blank"><img src="https://opencollective.com/debug/backer/22/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/23/website" target="_blank"><img src="https://opencollective.com/debug/backer/23/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/24/website" target="_blank"><img src="https://opencollective.com/debug/backer/24/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/25/website" target="_blank"><img src="https://opencollective.com/debug/backer/25/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/26/website" target="_blank"><img src="https://opencollective.com/debug/backer/26/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/27/website" target="_blank"><img src="https://opencollective.com/debug/backer/27/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/28/website" target="_blank"><img src="https://opencollective.com/debug/backer/28/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/29/website" target="_blank"><img src="https://opencollective.com/debug/backer/29/avatar.svg"></a>


## Sponsors

Become a sponsor and get your logo on our README on Github with a link to your site. [[Become a sponsor](https://opencollective.com/debug#sponsor)]

<a href="https://opencollective.com/debug/sponsor/0/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/0/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/1/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/1/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/2/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/2/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/3/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/3/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/4/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/4/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/5/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/5/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/6/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/6/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/7/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/7/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/8/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/8/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/9/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/9/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/10/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/10/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/11/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/11/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/12/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/12/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/13/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/13/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/14/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/14/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/15/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/15/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/16/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/16/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/17/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/17/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/18/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/18/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/19/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/19/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/20/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/20/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/21/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/21/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/22/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/22/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/23/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/23/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/24/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/24/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/25/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/25/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/26/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/26/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/27/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/27/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/28/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/28/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/29/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/29/avatar.svg"></a>

## License

(The MIT License)

Copyright (c) 2014-2016 TJ Holowaychuk &lt;tj@vision-media.ca&gt;

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
'Software'), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


---

The MIT License (MIT)

Copyright (c) 2016 Zeit, Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# ms

[![Build Status](https://travis-ci.org/zeit/ms.svg?branch=master)](https://travis-ci.org/zeit/ms)
[![Slack Channel](http://zeit-slackin.now.sh/badge.svg)](https://zeit.chat/)

Use this package to easily convert various time formats to milliseconds.

## Examples

```js
ms('2 days')  // 172800000
ms('1d')      // 86400000
ms('10h')     // 36000000
ms('2.5 hrs') // 9000000
ms('2h')      // 7200000
ms('1m')      // 60000
ms('5s')      // 5000
ms('1y')      // 31557600000
ms('100')     // 100
```

### Convert from milliseconds

```js
ms(60000)             // "1m"
ms(2 * 60000)         // "2m"
ms(ms('10 hours'))    // "10h"
```

### Time format written-out

```js
ms(60000, { long: true })             // "1 minute"
ms(2 * 60000, { long: true })         // "2 minutes"
ms(ms('10 hours'), { long: true })    // "10 hours"
```

## Features

- Works both in [node](https://nodejs.org) and in the browser.
- If a number is supplied to `ms`, a string with a unit is returned.
- If a string that contains the number is supplied, it returns it as a number (e.g.: it returns `100` for `'100'`).
- If you pass a string with a number and a valid unit, the number of equivalent ms is returned.

## Caught a bug?

1. [Fork](https://help.github.com/articles/fork-a-repo/) this repository to your own GitHub account and then [clone](https://help.github.com/articles/cloning-a-repository/) it to your local device
2. Link the package to the global module directory: `npm link`
3. Within the module you want to test your local development instance of ms, just link it to the dependencies: `npm link ms`. Instead of the default one from npm, node will now use your clone of ms!

As always, you can run the tests using: `npm test`


---

# find-cache-dir

> Finds the common standard cache directory

The [`nyc`](https://github.com/istanbuljs/nyc) and [`AVA`](https://ava.li) projects decided to standardize on a common directory structure for storing cache information:

```sh
# nyc
./node_modules/.cache/nyc

# ava
./node_modules/.cache/ava

# your-module
./node_modules/.cache/your-module
```

This module makes it easy to correctly locate the cache directory according to this shared spec. If this pattern becomes ubiquitous, clearing the cache for multiple dependencies becomes easy and consistent:

```
rm -rf ./node_modules/.cache
```

## Install

```sh
npm install find-cache-dir
```

## Usage

```js
import findCacheDirectory from 'find-cache-dir';

findCacheDirectory({name: 'unicorns'});
//=> '/user/path/node-modules/.cache/unicorns'
```

## API

### findCacheDirectory(options?)

Finds the cache directory using the supplied options. The algorithm checks for the `CACHE_DIR` environmental variable and uses it if it is not set to `true`, `false`, `1` or `0`. If one is not found, it tries to find a `package.json` file, searching every parent directory of the `cwd` specified (or implied from other options). It returns a `string` containing the absolute path to the cache directory, or `undefined` if `package.json` was never found or if the `node_modules` directory is unwritable.

#### options

Type: `object`

##### name

*Required*\
Type: `string`

Should be the same as your project name in `package.json`.

##### files

Type: `string[] | string`

An array of files that will be searched for a common parent directory. This common parent directory will be used in lieu of the `cwd` option below.

##### cwd

Type: `string`\
Default `process.cwd()`

Directory to start searching for a `package.json` from.

##### create

Type: `boolean`\
Default `false`

If `true`, the directory will be created synchronously before returning.

##### thunk

Type: `boolean`\
Default `false`

If `true`, this modifies the return type to be a function that is a thunk for `path.join(theFoundCacheDirectory)`.

```js
const thunk = findCacheDir({name: 'foo', thunk: true});

thunk();
//=> '/some/path/node_modules/.cache/foo'

thunk('bar.js')
//=> '/some/path/node_modules/.cache/foo/bar.js'

thunk('baz', 'quz.js')
//=> '/some/path/node_modules/.cache/foo/baz/quz.js'
```

This is helpful for actually putting actual files in the cache!

## Tips

- To test modules using `find-cache-dir`, set the `CACHE_DIR` environment variable to temporarily override the directory that is resolved.

## Adopters

- [`ava`](https://avajs.dev)
- [`nyc`](https://github.com/istanbuljs/nyc)
- [`storybook`](https://github.com/storybookjs/storybook)
- [`babel-loader`](https://github.com/babel/babel-loader)
- [`eslint-loader`](https://github.com/MoOx/eslint-loader)
- [More…](https://www.npmjs.com/browse/depended/find-cache-dir)


---

# find-up

> Find a file or directory by walking up parent directories

## Install

```
$ npm install find-up
```

## Usage

```
/
└── Users
    └── sindresorhus
        ├── unicorn.png
        └── foo
            └── bar
                ├── baz
                └── example.js
```

`example.js`

```js
import path from 'node:path';
import {findUp, pathExists} from 'find-up';

console.log(await findUp('unicorn.png'));
//=> '/Users/sindresorhus/unicorn.png'

console.log(await findUp(['rainbow.png', 'unicorn.png']));
//=> '/Users/sindresorhus/unicorn.png'

console.log(await findUp(async directory => {
	const hasUnicorns = await pathExists(path.join(directory, 'unicorn.png'));
	return hasUnicorns && directory;
}, {type: 'directory'}));
//=> '/Users/sindresorhus'
```

## API

### findUp(name, options?)
### findUp(matcher, options?)

Returns a `Promise` for either the path or `undefined` if it couldn't be found.

### findUp([...name], options?)

Returns a `Promise` for either the first path found (by respecting the order of the array) or `undefined` if none could be found.

### findUpMultiple(name, options?)
### findUpMultiple(matcher, options?)

Returns a `Promise` for either an array of paths or an empty array if none could be found.

### findUpMultiple([...name], options?)

Returns a `Promise` for either an array of the first paths found (by respecting the order of the array) or an empty array if none could be found.

### findUpSync(name, options?)
### findUpSync(matcher, options?)

Returns a path or `undefined` if it couldn't be found.

### findUpSync([...name], options?)

Returns the first path found (by respecting the order of the array) or `undefined` if none could be found.

### findUpMultipleSync(name, options?)
### findUpMultipleSync(matcher, options?)

Returns an array of paths or an empty array if none could be found.

### findUpMultipleSync([...name], options?)

Returns an array of the first paths found (by respecting the order of the array) or an empty array if none could be found.

#### name

Type: `string`

The name of the file or directory to find.

#### matcher

Type: `Function`

A function that will be called with each directory until it returns a `string` with the path, which stops the search, or the root directory has been reached and nothing was found. Useful if you want to match files with certain patterns, set of permissions, or other advanced use-cases.

When using async mode, the `matcher` may optionally be an async or promise-returning function that returns the path.

#### options

Type: `object`

##### cwd

Type: `URL | string`\
Default: `process.cwd()`

The directory to start from.

##### type

Type: `string`\
Default: `'file'`\
Values: `'file'` `'directory'`

The type of paths that can match.

##### allowSymlinks

Type: `boolean`\
Default: `true`

Allow symbolic links to match if they point to the chosen path type.

##### stopAt

Type: `string`\
Default: `path.parse(cwd).root`

The path to the directory to stop the search before reaching root if there were no matches before the `stopAt` directory.

### pathExists(path)

Returns a `Promise<boolean>` of whether the path exists.

### pathExistsSync(path)

Returns a `boolean` of whether the path exists.

#### path

Type: `string`

The path to a file or directory.

### findUpStop

A [`Symbol`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol) that can be returned by a `matcher` function to stop the search and cause `findUp` to immediately return `undefined`. Useful as a performance optimization in case the current working directory is deeply nested in the filesystem.

```js
import path from 'node:path';
import {findUp, findUpStop} from 'find-up';

await findUp(directory => {
	return path.basename(directory) === 'work' ? findUpStop : 'logo.png';
});
```

## Related

- [find-up-cli](https://github.com/sindresorhus/find-up-cli) - CLI for this module
- [pkg-up](https://github.com/sindresorhus/pkg-up) - Find the closest package.json file
- [pkg-dir](https://github.com/sindresorhus/pkg-dir) - Find the root directory of an npm package
- [resolve-from](https://github.com/sindresorhus/resolve-from) - Resolve the path of a module like `require.resolve()` but from a given path

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-find-up?utm_source=npm-find-up&utm_medium=referral&utm_campaign=readme">Get professional support for 'find-up' with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

# flat [![Build Status](https://secure.travis-ci.org/hughsk/flat.png?branch=master)](http://travis-ci.org/hughsk/flat)

Take a nested Javascript object and flatten it, or unflatten an object with
delimited keys.

## Installation

``` bash
$ npm install flat
```

## Methods

### flatten(original, options)

Flattens the object - it'll return an object one level deep, regardless of how
nested the original object was:

``` javascript
var flatten = require('flat')

flatten({
    key1: {
        keyA: 'valueI'
    },
    key2: {
        keyB: 'valueII'
    },
    key3: { a: { b: { c: 2 } } }
})

// {
//   'key1.keyA': 'valueI',
//   'key2.keyB': 'valueII',
//   'key3.a.b.c': 2
// }
```

### unflatten(original, options)

Flattening is reversible too, you can call `flatten.unflatten()` on an object:

``` javascript
var unflatten = require('flat').unflatten

unflatten({
    'three.levels.deep': 42,
    'three.levels': {
        nested: true
    }
})

// {
//     three: {
//         levels: {
//             deep: 42,
//             nested: true
//         }
//     }
// }
```

## Options

### delimiter

Use a custom delimiter for (un)flattening your objects, instead of `.`.

### safe

When enabled, both `flat` and `unflatten` will preserve arrays and their
contents. This is disabled by default.

``` javascript
var flatten = require('flat')

flatten({
    this: [
        { contains: 'arrays' },
        { preserving: {
              them: 'for you'
        }}
    ]
}, {
    safe: true
})

// {
//     'this': [
//         { contains: 'arrays' },
//         { preserving: {
//             them: 'for you'
//         }}
//     ]
// }
```

### object

When enabled, arrays will not be created automatically when calling unflatten, like so:

``` javascript
unflatten({
    'hello.you.0': 'ipsum',
    'hello.you.1': 'lorem',
    'hello.other.world': 'foo'
}, { object: true })

// hello: {
//     you: {
//         0: 'ipsum',
//         1: 'lorem',
//     },
//     other: { world: 'foo' }
// }
```

### overwrite

When enabled, existing keys in the unflattened object may be overwritten if they cannot hold a newly encountered nested value:

```javascript
unflatten({
    'TRAVIS': 'true',
    'TRAVIS.DIR': '/home/travis/build/kvz/environmental'
}, { overwrite: true })

// TRAVIS: {
//     DIR: '/home/travis/build/kvz/environmental'
// }
```

Without `overwrite` set to `true`, the `TRAVIS` key would already have been set to a string, thus could not accept the nested `DIR` element.

This only makes sense on ordered arrays, and since we're overwriting data, should be used with care.


### maxDepth

Maximum number of nested objects to flatten.

``` javascript
var flatten = require('flat')

flatten({
    key1: {
        keyA: 'valueI'
    },
    key2: {
        keyB: 'valueII'
    },
    key3: { a: { b: { c: 2 } } }
}, { maxDepth: 2 })

// {
//   'key1.keyA': 'valueI',
//   'key2.keyB': 'valueII',
//   'key3.a': { b: { c: 2 } }
// }
```

### transformKey

Transform each part of a flat key before and after flattening.

```javascript
var flatten = require('flat')
var unflatten = require('flat').unflatten

flatten({
    key1: {
        keyA: 'valueI'
    },
    key2: {
        keyB: 'valueII'
    },
    key3: { a: { b: { c: 2 } } }
}, {
    transformKey: function(key){
      return '__' + key + '__';
    }
})

// {
//   '__key1__.__keyA__': 'valueI',
//   '__key2__.__keyB__': 'valueII',
//   '__key3__.__a__.__b__.__c__': 2
// }

unflatten({
      '__key1__.__keyA__': 'valueI',
      '__key2__.__keyB__': 'valueII',
      '__key3__.__a__.__b__.__c__': 2
}, {
    transformKey: function(key){
      return key.substring(2, key.length - 2)
    }
})

// {
//     key1: {
//         keyA: 'valueI'
//     },
//     key2: {
//         keyB: 'valueII'
//     },
//     key3: { a: { b: { c: 2 } } }
// }
```

## Command Line Usage

`flat` is also available as a command line tool. You can run it with 
[`npx`](https://ghub.io/npx):

```sh
npx flat foo.json
```

Or install the `flat` command globally:
 
```sh
npm i -g flat && flat foo.json
```

Accepts a filename as an argument:

```sh
flat foo.json
```

Also accepts JSON on stdin:

```sh
cat foo.json | flat
```


---

## Follow Redirects

Drop-in replacement for Node's `http` and `https` modules that automatically follows redirects.

[![npm version](https://img.shields.io/npm/v/follow-redirects.svg)](https://www.npmjs.com/package/follow-redirects)
[![Build Status](https://github.com/follow-redirects/follow-redirects/workflows/CI/badge.svg)](https://github.com/follow-redirects/follow-redirects/actions)
[![Coverage Status](https://coveralls.io/repos/follow-redirects/follow-redirects/badge.svg?branch=master)](https://coveralls.io/r/follow-redirects/follow-redirects?branch=master)
[![npm downloads](https://img.shields.io/npm/dm/follow-redirects.svg)](https://www.npmjs.com/package/follow-redirects)
[![Sponsor on GitHub](https://img.shields.io/static/v1?label=Sponsor&message=%F0%9F%92%96&logo=GitHub)](https://github.com/sponsors/RubenVerborgh)

`follow-redirects` provides [request](https://nodejs.org/api/http.html#http_http_request_options_callback) and [get](https://nodejs.org/api/http.html#http_http_get_options_callback)
 methods that behave identically to those found on the native [http](https://nodejs.org/api/http.html#http_http_request_options_callback) and [https](https://nodejs.org/api/https.html#https_https_request_options_callback)
 modules, with the exception that they will seamlessly follow redirects.

```javascript
const { http, https } = require('follow-redirects');

http.get('http://bit.ly/900913', response => {
  response.on('data', chunk => {
    console.log(chunk);
  });
}).on('error', err => {
  console.error(err);
});
```

You can inspect the final redirected URL through the `responseUrl` property on the `response`.
If no redirection happened, `responseUrl` is the original request URL.

```javascript
const request = https.request({
  host: 'bitly.com',
  path: '/UHfDGO',
}, response => {
  console.log(response.responseUrl);
  // 'http://duckduckgo.com/robots.txt'
});
request.end();
```

## Options
### Global options
Global options are set directly on the `follow-redirects` module:

```javascript
const followRedirects = require('follow-redirects');
followRedirects.maxRedirects = 10;
followRedirects.maxBodyLength = 20 * 1024 * 1024; // 20 MB
```

The following global options are supported:

- `maxRedirects` (default: `21`) – sets the maximum number of allowed redirects; if exceeded, an error will be emitted.

- `maxBodyLength` (default: 10MB) – sets the maximum size of the request body; if exceeded, an error will be emitted.

### Per-request options
Per-request options are set by passing an `options` object:

```javascript
const url = require('url');
const { http, https } = require('follow-redirects');

const options = url.parse('http://bit.ly/900913');
options.maxRedirects = 10;
options.beforeRedirect = (options, response, request) => {
  // Use this to adjust the request options upon redirecting,
  // to inspect the latest response headers,
  // or to cancel the request by throwing an error

  // response.headers = the redirect response headers
  // response.statusCode = the redirect response code (eg. 301, 307, etc.)

  // request.url = the requested URL that resulted in a redirect
  // request.headers = the headers in the request that resulted in a redirect
  // request.method = the method of the request that resulted in a redirect
  if (options.hostname === "example.com") {
    options.auth = "user:password";
  }
};
http.request(options);
```

In addition to the [standard HTTP](https://nodejs.org/api/http.html#http_http_request_options_callback) and [HTTPS options](https://nodejs.org/api/https.html#https_https_request_options_callback),
the following per-request options are supported:
- `followRedirects` (default: `true`) – whether redirects should be followed.

- `maxRedirects` (default: `21`) – sets the maximum number of allowed redirects; if exceeded, an error will be emitted.

- `maxBodyLength` (default: 10MB) – sets the maximum size of the request body; if exceeded, an error will be emitted.

- `beforeRedirect` (default: `undefined`) – optionally change the request `options` on redirects, or abort the request by throwing an error.

- `agents` (default: `undefined`) – sets the `agent` option per protocol, since HTTP and HTTPS use different agents. Example value: `{ http: new http.Agent(), https: new https.Agent() }`

- `trackRedirects` (default: `false`) – whether to store the redirected response details into the `redirects` array on the response object.


### Advanced usage
By default, `follow-redirects` will use the Node.js default implementations
of [`http`](https://nodejs.org/api/http.html)
and [`https`](https://nodejs.org/api/https.html).
To enable features such as caching and/or intermediate request tracking,
you might instead want to wrap `follow-redirects` around custom protocol implementations:

```javascript
const { http, https } = require('follow-redirects').wrap({
  http: require('your-custom-http'),
  https: require('your-custom-https'),
});
```

Such custom protocols only need an implementation of the `request` method.

## Browser Usage

Due to the way the browser works,
the `http` and `https` browser equivalents perform redirects by default.

By requiring `follow-redirects` this way:
```javascript
const http = require('follow-redirects/http');
const https = require('follow-redirects/https');
```
you can easily tell webpack and friends to replace
`follow-redirect` by the built-in versions:

```json
{
  "follow-redirects/http"  : "http",
  "follow-redirects/https" : "https"
}
```

## Contributing

Pull Requests are always welcome. Please [file an issue](https://github.com/follow-redirects/follow-redirects/issues)
 detailing your proposal before you invest your valuable time. Additional features and bug fixes should be accompanied
 by tests. You can run the test suite locally with a simple `npm test` command.

## Debug Logging

`follow-redirects` uses the excellent [debug](https://www.npmjs.com/package/debug) for logging. To turn on logging
 set the environment variable `DEBUG=follow-redirects` for debug output from just this module. When running the test
 suite it is sometimes advantageous to set `DEBUG=*` to see output from the express server as well.

## Authors

- [Ruben Verborgh](https://ruben.verborgh.org/)
- [Olivier Lalonde](mailto:olalonde@gmail.com)
- [James Talmage](mailto:james@talmage.io)

## License

[MIT License](https://github.com/follow-redirects/follow-redirects/blob/master/LICENSE)


---

## ⚠️ Next versions are available only on the [GitHub Releases](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/releases) page ⚠️

# [1.3.0-beta.1](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/compare/v1.2.0...v1.3.0-beta.1@beta) (2019-04-30)

### Bug Fixes

- **tests:** fix linter tests that were doing nothing ([d078278](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/commit/d078278))
- **tests:** linter tests - useTypescriptIncrementalApi usage ([e0020d6](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/commit/e0020d6))
- **tests:** rework vue integration tests ([5ad2568](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/commit/5ad2568))

### Features

- **apiincrementalchecker:** improve generation of diagnostics ([ae80e5f](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/commit/ae80e5f)), closes [#257](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/issues/257)

# [1.2.0](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/compare/v1.1.1...v1.2.0) (2019-04-22)

### Bug Fixes

- semantic-release update `CHANGELOG.md` on the git repo ([8ad58af](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/commit/8ad58af))

### Features

- add semantic-release integration ([5fe0653](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/commit/5fe0653))

# [1.2.0-beta.4](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/compare/v1.2.0-beta.3@beta...v1.2.0-beta.4@beta) (2019-04-23)

### Bug Fixes

- **tests:** fix linter tests that were doing nothing ([d078278](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/commit/d078278))
- **tests:** linter tests - useTypescriptIncrementalApi usage ([e0020d6](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/commit/e0020d6))

### Features

- **apiincrementalchecker:** improve generation of diagnostics ([ae80e5f](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/commit/ae80e5f)), closes [#257](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/issues/257)

# [1.2.0-beta.3](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/compare/v1.2.0-beta.2@beta...v1.2.0-beta.3@beta) (2019-04-22)

### Bug Fixes

- **tests:** rework vue integration tests ([5ad2568](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/commit/5ad2568))

# [1.2.0-beta.2](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/compare/v1.2.0-beta.1@beta...v1.2.0-beta.2@beta) (2019-04-22)

### Bug Fixes

- semantic-release update `CHANGELOG.md` on the git repo ([8ad58af](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/commit/8ad58af))

# [1.2.0-beta.1](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/compare/v1.1.0...v1.2.0-beta.1@beta) (2019-04-22)

### Features

- add semantic-release integration ([5fe0653](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/commit/5fe0653))

## v1.1.1

- [Fix a regression w/ plugins like tsconfig-paths-webpack-plugin](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/pull/260)

## v1.1.0

- [Add new custom resolution options](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/pull/250)

## v1.0.4

- [gracefully handle error thrown from the service](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/pull/249)

## v1.0.3

- [use worker-rpc library for inter-process communication](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/pull/231)

## v1.0.2

- [Fix ignoreLintWarning mark warnings as errors](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/pull/243)

## v1.0.1

- [Apply rounding to compilation time](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/pull/235)

## v1.0.0

- [Going 1.0](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/pull/218)

This is the first major version of `fork-ts-checker-webpack-plugin`. A long time coming :-)

There are actually no breaking changes that we're aware of; users of 0.x `fork-ts-checker-webpack-plugin` should be be able to upgrade without any drama. Users of TypeScript 3+ may notice a performance improvement as by default the plugin now uses the [incremental watch API](https://github.com/Microsoft/TypeScript/pull/20234) in TypeScript. Should this prove problematic you can opt out of using it by supplying `useTypescriptIncrementalApi: false`.

We are aware of an [issue with Vue and the incremental API](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/issues/219). We hope it will be fixed soon - a generous member of the community is taking a look. In the meantime, we will _not_ default to using the incremental watch API when in Vue mode.

The plugin supports webpack 2, 3, 4 and 5 alpha and TypeScript 2.1+ alongside tslint 4+.

See also: https://blog.johnnyreilly.com/2019/03/the-big-one-point-oh.html

## v1.0.0-alpha.10

- [Fix incremental api to work with TS 3+ by default](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/pull/223)

## v1.0.0-alpha.9

- [Default to incremental api usage to true if TS 3+](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/pull/217)

## v1.0.0-alpha.8

- [Respect tslint configs hierarchical order](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/pull/214)

## v1.0.0-alpha.7

- [Add ignoreLintWarnings option](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/pull/213)

## v1.0.0-alpha.6

- [don't directly depend upon typescript](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/pull/208)

## v1.0.0-alpha.5

- [can now provide path where typescript can be found](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/pull/204)

## v1.0.0-alpha.4

- [make node 6 compatible](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/pull/202)

## v1.0.0-alpha.3

- [replace peerDeps with runtime checks](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/pull/201)

## v1.0.0-alpha.2

- [Add `useTypescriptIncrementalApi`](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/pull/198) (#196)

## v1.0.0-alpha.1

- [Use object-spread instead of `Object.assign`](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/pull/194) (#194)

## v1.0.0-alpha.0

- [Add support for webpack 5](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/pull/166)

### Breaking Changes

Version `1.x` additionally supports webpack 5 alongside webpack 4, whose hooks are now tapped differently:

```diff
-  compiler.hooks.forkTsCheckerDone.tap(...args)
+  const forkTsCheckerHooks = ForkTsCheckerWebpackPlugin.getCompilerHooks(compiler)
+  forkTsCheckerHooks.done.tap(...args)
```

v1.0.0-alpha.0 drops support for node 6.

## v0.5.2

- [Fix erroneous error on diagnostics at 0 line; remove deprecated fs.existsSync](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/pull/190) (#190)

## v0.5.1

- [Make the checker compile with TypeScript 3.2](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/pull/189)

## 0.5.0

- Removed unused dependency `resolve`.
- Replace `lodash` usage with native calls.
- ** Breaking Changes**:
  - Removed all getters from `NormalizedMessage`, use direct property access instead.
- **Internal**:
  - Test against ts-loader v5
  - Enable all strict type checks
  - Update dev dependencies

## v0.4.15

- [Add `tslintAutoFix` option to be passed on to tslint to auto format typescript files](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/pull/174) (#174)

## v0.4.14

- [Add support for `reportFiles` option](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/pull/179) (#179)

## v0.4.13

- [Merge in `compilerOptions` prior to calling `parseJsonConfigFileContent`](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/pull/176) (#176)

## v0.4.12

- [Add `compilerOptions` option](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/pull/173) (#173)

## v0.4.11

- [Fix os.cpus is not a function](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/pull/172) (#172)

## v0.4.10

- [Allow fork-ts-checker-webpack-plugin to be imported in .ts files using ESM import syntax](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/pull/163) (#163)

## v0.4.9

- [Set "compilationDone" before resolving "forkTsCheckerServiceBeforeStart"](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/pull/146) (#146)

## v0.4.8

- [Fix(types collision): update webpack](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/pull/151) (#142)

## v0.4.7

- [Fix(types collision): update chalk and chokidar](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/pull/147) (#142)
- [Fix(logger): Don't limit Options.logger to Console type](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/pull/143)

## v0.4.6

- [Fix(types): Make options Partial<Options>](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/pull/141) (#140)

## v0.4.5

- [Fix(types): Add types to the plugin](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/pull/139) (#137)
- [Fix(vue): Avoid false positive of no-consecutive-blank-lines TSLint rule in Vue file](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/pull/138) (#130)

## v0.4.4

- [Fix(vue): resolve src attribute on the script block on Vue files](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/pull/130) (#111, #85)
- Add TypeScript ^3.0.0 to peerDependencies

## v0.4.3

- Fix "File system lag can cause Invalid source file errors to slip through" (#127)

## v0.4.2

- Format messages when `async` is false

## v0.4.1

- Fix webpack 4 hooks bug

## v0.4.0

- Support webpack 4

## v0.3.0

- Add `vue` support

## v0.2.10

- Fix #80 "Cannot read property 'getLineAndCharacterOfPosition' of undefined"
- Fix #76 "TypeError: Cannot read property '0' of undefined"

## v0.2.9

- Make errors formatting closer to `ts-loader` style
- Handle tslint exclude option

## v0.2.8

- Add `checkSyntacticErrors` option
- Fix `process.env` pass to the child process
- Add `fork-ts-checker-service-before-start` hook

## v0.2.7

- Fix service is not killed when webpack watch is done

## v0.2.6

- Add diagnostics/lints formatters - `formatter` and `formatterOptions` option

## v0.2.5

- Add `async` option - more information in `README.md`

## v0.2.4

- Fix `ESLint: "fork-ts-checker-webpack-plugin" is not published.` issue

## v0.2.3

- Add support for webpack 3 as peerDependency

## v0.2.2

- Force `isolatedModule: false` in checker compiler for better performance

## v0.2.1

- Fix for `tslint: true` option issue

## v0.2.0

- tsconfig.json and tslint.json path are not printed anymore.
- `watch` option is not used on 'build' mode
- Handle case with no options object (`new ForkTsCheckerWebpacPlugin()`)
- Basic integration tests (along units)
- **Breaking changes**:
  - tslint is not enabled by default - you have to set `tslint: true` or `tslint: './path/to/tslint.json'` to enable it.
  - `blockEmit` option is removed - it choose automatically - blocks always on 'build' mode, never on 'watch' mode.

## v0.1.5

- Disable tslint if module is not installed and no tslint path is passed
- Improve README.md

## v0.1.4

- Fix send to closed channel case
- Fix removed files case
- Add `fork-ts-checker-service-start-error` hook

## v0.1.3

- Fix "Cannot read property 'mtime' of undefined on OSX"

## v0.1.2

- Workers mode works correctly (fixed typo)

## v0.1.1

- Support memory limit in multi-process mode
- Handle already closed channel case on sending ipc message

## v0.1.0

- Initial release - not production ready.


---

<div align="center">

<h1>Fork TS Checker Webpack Plugin</h1>
<p>Webpack plugin that runs TypeScript type checker on a separate process.</p>

[![npm version](https://img.shields.io/npm/v/fork-ts-checker-webpack-plugin.svg)](https://www.npmjs.com/package/fork-ts-checker-webpack-plugin)
[![build status](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/workflows/CI/CD/badge.svg?branch=main&event=push)](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/actions?query=branch%3Amain+event%3Apush)
[![downloads](http://img.shields.io/npm/dm/fork-ts-checker-webpack-plugin.svg)](https://npmjs.org/package/fork-ts-checker-webpack-plugin)
[![commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)
[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)

</div>

## Features

 * Speeds up [TypeScript](https://github.com/Microsoft/TypeScript) type checking and [ESLint](https://eslint.org/) linting (by moving each to a separate process) 🏎
 * Supports modern TypeScript features like [project references](https://www.typescriptlang.org/docs/handbook/project-references.html) and [incremental mode](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-4.html#faster-subsequent-builds-with-the---incremental-flag) ✨
 * Supports [Vue Single File Component](https://vuejs.org/v2/guide/single-file-components.html) ✅ 
 * Displays nice error messages with the [code frame](https://babeljs.io/docs/en/next/babel-code-frame.html) formatter 🌈

## Installation

This plugin requires minimum **Node.js 10**, **Webpack 4**, **TypeScript 2.7** and optionally **ESLint 6**

* If you depend on **Webpack 2**, **Webpack 3**, or **TSLint 4**, please use [version 3](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/tree/v3.1.1) of the plugin. 
* If you depend on **TypeScript >= 2.1** and **< 2.7** or you can't update to **Node 10**, please use [version 4](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/tree/v4.1.4) of the plugin.
```sh
# with npm
npm install --save-dev fork-ts-checker-webpack-plugin

# with yarn
yarn add --dev fork-ts-checker-webpack-plugin
```

The minimal webpack config (with [ts-loader](https://github.com/TypeStrong/ts-loader))

```js
// webpack.config.js
const ForkTsCheckerWebpackPlugin = require('fork-ts-checker-webpack-plugin');

module.exports = {
  context: __dirname, // to automatically find tsconfig.json
  entry: './src/index.ts',
  resolve: {
    extensions: [".ts", ".tsx", ".js"],
  },
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        loader: 'ts-loader',
        exclude: /node_modules/,
        options: {
          // disable type checker - we will use it in fork plugin
          transpileOnly: true
        }
      }
    ]
  },
  plugins: [new ForkTsCheckerWebpackPlugin()]
};
```

> Examples how to configure it with [babel-loader](https://github.com/babel/babel-loader), [ts-loader](https://github.com/TypeStrong/ts-loader),
> [eslint](https://github.com/eslint/eslint) and [Visual Studio Code](https://code.visualstudio.com/) are in the 
> [**examples**](./examples) directory.

## Modules resolution

It's very important to be aware that **this plugin uses [TypeScript](https://github.com/Microsoft/TypeScript)'s, not
[webpack](https://github.com/webpack/webpack)'s modules resolution**. It means that you have to setup `tsconfig.json` correctly. 

> It's because of the performance - with TypeScript's module resolution we don't have to wait for webpack to compile files.
>
> To debug TypeScript's modules resolution, you can use `tsc --traceResolution` command.

## ESLint

If you'd like to use ESLint with the plugin, ensure you have the relevant dependencies installed:

```sh
# with npm
npm install --save-dev eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin

# with yarn
yarn add --dev eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin
```

Then set up ESLint in the plugin. This is the minimal configuration:
```js
// webpack.config.js
const ForkTsCheckerWebpackPlugin = require('fork-ts-checker-webpack-plugin');

module.exports = {
  // ...the webpack configuration
  plugins: [
    new ForkTsCheckerWebpackPlugin({
      eslint: {
        files: './src/**/*.{ts,tsx,js,jsx}' // required - same as command `eslint ./src/**/*.{ts,tsx,js,jsx} --ext .ts,.tsx,.js,.jsx`
      }
    })
  ]
};
```

You should also have an ESLint configuration file in your root project directory. 
Here is a sample `.eslintrc.js` configuration for a TypeScript project:

```js
module.exports = {
  parser: '@typescript-eslint/parser',
  parserOptions: {
    ecmaVersion: 2018,
    sourceType: 'module',
  },
  extends: [
    'plugin:@typescript-eslint/recommended'
  ],
  rules: {
    // place to specify ESLint rules - can be used to overwrite rules specified from the extended configs
    // e.g. "@typescript-eslint/explicit-function-return-type": "off",
  }
};
```

There's a [good explanation on setting up TypeScript ESLint support by Robert Cooper](https://dev.to/robertcoopercode/using-eslint-and-prettier-in-a-typescript-project-53jb).

## Options

This plugin uses [`cosmiconfig`](https://github.com/davidtheclark/cosmiconfig). This means that besides the plugin constructor,
you can place your configuration in the:
 * `"fork-ts-checker"` field in the `package.json`
 * `.fork-ts-checkerrc` file in JSON or YAML format
 * `fork-ts-checker.config.js` file exporting a JS object
  
Options passed to the plugin constructor will overwrite options from the cosmiconfig (using [deepmerge](https://github.com/TehShrike/deepmerge)).

| Name              | Type                               | Default value                                                      | Description |
| ----------------- | ---------------------------------- | ------------------------------------------------------------------ | ----------- |
| `async`           | `boolean`                          | `compiler.options.mode === 'development'`                          | If `true`, reports issues **after** webpack's compilation is done. Thanks to that it doesn't block the compilation. Used only in the `watch` mode. |
| `typescript`      | `object` or `boolean`              | `true`                                                             | If a `boolean`, it enables/disables TypeScript checker. If an `object`, see [TypeScript options](#typescript-options). |
| `eslint`          | `object`                           | `undefined`                                                        | If `undefined`, it disables ESLint linter. If an `object`, see [ESLint options](#eslint-options). |
| `issue`           | `object`                           | `{}`                                                               | See [Issues options](#issues-options). |
| `formatter`       | `string` or `object` or `function` | `codeframe`                                                        | Available formatters are `basic`, `codeframe` and a custom `function`. To [configure](https://babeljs.io/docs/en/babel-code-frame#options) `codeframe` formatter, pass object: `{ type: 'codeframe', options: { <coderame options> } }`. |
| `logger`          | `object`              | `{ infrastructure: 'silent', issues: 'console', devServer: true }` | Available loggers are `silent`, `console`, and `webpack-infrastructure`. Infrastructure logger prints additional information, issue logger prints `issues` in the `async` mode. If `devServer` is set to `false`, errors will not be reported to Webpack Dev Server. |

### TypeScript options

Options for the TypeScript checker (`typescript` option object).

| Name                 | Type      | Default value                                                                                                  | Description |
| -------------------- | --------- | -------------------------------------------------------------------------------------------------------------- | ----------- |
| `enabled`            | `boolean` | `true`                                                                                                         | If `true`, it enables TypeScript checker. |
| `memoryLimit`        | `number`  | `2048`                                                                                                         | Memory limit for the checker process in MB. If the process exits with the allocation failed error, try to increase this number. |
| `configFile`         | `string`  | `'tsconfig.json'`                                                                                              | Path to the `tsconfig.json` file (path relative to the `compiler.options.context` or absolute path) |
| `configOverwrite`    | `object`  | `{ compilerOptions: { skipLibCheck: true, sourceMap: false, inlineSourceMap: false, declarationMap: false } }` | This configuration will overwrite configuration from the `tsconfig.json` file. Supported fields are: `extends`, `compilerOptions`, `include`, `exclude`, `files`, and `references`. |
| `context`            | `string`  | `dirname(configuration.configFile)`                                                                            | The base path for finding files specified in the `tsconfig.json`. Same as the `context` option from the [ts-loader](https://github.com/TypeStrong/ts-loader#context). Useful if you want to keep your `tsconfig.json` in an external package. Keep in mind that **not** having a `tsconfig.json` in your project root can cause different behaviour between `fork-ts-checker-webpack-plugin` and `tsc`. When using editors like `VS Code` it is advised to add a `tsconfig.json` file to the root of the project and extend the config file referenced in option `configFile`.  |
| `build`              | `boolean` | `false`                                                                                                        | The equivalent of the `--build` flag for the `tsc` command. |
| `mode`               | `'readonly'` or `'write-tsbuildinfo'` or `'write-dts'` or `'write-references'` | `'write-tsbuildinfo'`                                      | If you use the `babel-loader`, it's recommended to use `write-references` mode to improve initial compilation time. If you use `ts-loader`, it's recommended to use `write-tsbuildinfo` mode to not overwrite files emitted by the `ts-loader`. If you use `ts-loader` with `transpileOnly` flag set to `true`, use `'write-dts` to emit the type definition files. |
| `diagnosticOptions` | `object`  | `{ syntactic: false, semantic: true, declaration: false, global: false }`                                      | Settings to select which diagnostics do we want to perform. |
| `extensions`         | `object`  | `{}`                                                                                                           | See [TypeScript extensions options](#typescript-extensions-options). |
| `profile`            | `boolean` | `false`                                                                                                        | Measures and prints timings related to the TypeScript performance. |
| `typescriptPath`     | `string`  | `require.resolve('typescript')`                                                                                | If supplied this is a custom path where TypeScript can be found. |

#### TypeScript extensions options

Options for the TypeScript checker extensions (`typescript.extensions` option object).

| Name                 | Type                  | Default value             | Description |
| -------------------- | --------------------- | ------------------------- | ----------- |
| `vue`                | `object` or `boolean` | `false`                   | If `true`, it enables Vue [Single File Component](https://vuejs.org/v2/guide/single-file-components.html) support. |
| `vue.enabled`        | `boolean`             | `false`                   | Same as the `vue` option |
| `vue.compiler`       | `string`              | `'vue-template-compiler'` | The package name of the compiler that will be used to parse `.vue` files. You can use `'nativescript-vue-template-compiler'` if you use [nativescript-vue](https://github.com/nativescript-vue/nativescript-vue) | 

### ESLint options

Options for the ESLint linter (`eslint` option object).

| Name                 | Type                   | Default value             | Description |
| -------------------- | ---------------------- | ------------------------- | ----------- |
| `enabled`            | `boolean`              | `false`                   | If `true`, it enables ESLint linter. If you set the `files` option, it will be `true` by default. |
| `files`              | `string` or `string[]` | This value is required    | One or more [glob patterns](https://en.wikipedia.org/wiki/Glob_(programming)) to the files that should be linted. Works the same as the `eslint` command. |
| `memoryLimit`        | `number`               | `2048`                    | Memory limit for the linter process in MB. If the process exits with the allocation failed error, try to increase this number. |
| `options`            | `object`               | `{}`                      | [Options](https://eslint.org/docs/developer-guide/nodejs-api#cliengine) that can be used to initialize ESLint. |

### Issues options

Options for the issues filtering (`issue` option object).
I could write some plain text explanation of these options but I think code will explain it better:

```typescript
interface Issue {
  origin: 'typescript' | 'eslint';
  severity: 'error' | 'warning';
  code: string;
  file?: string;
}

type IssueMatch = Partial<Issue>; // file field supports glob matching
type IssuePredicate = (issue: Issue) => boolean;
type IssueFilter = IssueMatch | IssuePredicate | (IssueMatch | IssuePredicate)[];
```

| Name      | Type          | Default value | Description |
| --------- | ------------- | ------------- | ----------- |
| `include` | `IssueFilter` | `undefined`   | If `object`, defines issue properties that should be [matched](./src/issue/IssueMatch.ts). If `function`, acts as a predicate where `issue` is an argument. |
| `exclude` | `IssueFilter` | `undefined`   | Same as `include` but issues that match this predicate will be excluded. |

<details>
<summary>Expand example</summary>

Include issues from the `src` directory, exclude eslint issues from `.spec.ts` files:

```js
module.exports = {
  // ...the webpack configuration
  plugins: [
    new ForkTsCheckerWebpackPlugin({
      issue: {
        include: [
          { file: '**/src/**/*' }
        ],
        exclude: [
          { origin: 'eslint', file: '**/*.spec.ts' }
        ]
      }
    })
  ]
};
```

</details>

## Vue.js

⚠️ There are additional **constraints** regarding Vue.js Single File Component support: ⚠️
 * It requires **TypeScript >= 3.8.0** (it's a limitation of the `transpileOnly` mode from `ts-loader`)
 * It doesn't work with the `build` mode (project references)

To enable Vue.js support, follow these steps:

<details>
<summary>Expand Vue.js set up instruction</summary>

1. Ensure you have all required packages installed:
```sh
# with npm
npm install --save vue vue-class-component
npm install --save-dev vue-loader ts-loader css-loader vue-template-compiler 

# with yarn
yarn add vue vue-class-component
yarn add --dev vue-loader ts-loader css-loader vue-template-compiler 
```

2. Add `tsconfig.json` configuration:
```json
{
  "compilerOptions": {
    "experimentalDecorators": true,
    "jsx": "preserve",
    "target": "ES5",
    "lib": ["ES6", "DOM"],
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "~/*": ["src/*"]
    },
    "sourceMap": true,
    "importsNotUsedAsValues": "preserve"
  },
  "include": [
    "src/**/*.ts",
    "src/**/*.vue"
  ],
  "exclude": [
    "node_modules"
  ]
}
```

3. Add `webpack.config.js` configuration:
```js
const path = require('path');
const VueLoaderPlugin = require('vue-loader/lib/plugin');
const ForkTsCheckerWebpackPlugin = require('fork-ts-checker-webpack-plugin');

module.exports = {
  entry: './src/index.ts',
  output: {
    filename: 'index.js',
    path: path.resolve(__dirname, 'dist'),
  },
  module: {
    rules: [
      {
        test: /\.vue$/,
        loader: 'vue-loader'
      },
      {
        test: /\.ts$/,
        loader: 'ts-loader',
        exclude: /node_modules/,
        options: {
          appendTsSuffixTo: [/\.vue$/],
          transpileOnly: true
        }
      },
      {
        test: /\.css$/,
        loader: 'css-loader'
      },
    ],
  },
  resolve: {
    extensions: ['.ts', '.js', '.vue', '.json'],
    alias: {
      '@': path.resolve(__dirname, './src'),
      '~': path.resolve(__dirname, './src'),
    }
  },
  plugins: [
    new VueLoaderPlugin(),
    new ForkTsCheckerWebpackPlugin({
      typescript: {
        extensions: {
          vue: true
        }
      }
    })
  ]
};
```

4. Add `src/types/vue.d.ts` file to shim `.vue` modules:
```typescript
declare module "*.vue" {
  import Vue from "vue";
  export default Vue;
}
```

5. If you are working in VSCode, you can get the [Vetur](https://marketplace.visualstudio.com/items?itemName=octref.vetur) extension to complete the developer workflow.

</details>

## Plugin hooks

This plugin provides some custom webpack hooks:

| Hook key   | Type                       | Params                | Description |
| ---------- | -------------------------- | --------------------- | ----------- |
| `start`    | `AsyncSeriesWaterfallHook` | `change, compilation` | Starts issues checking for a compilation. It's an async waterfall hook, so you can modify the list of changed and removed files or delay the start of the service. |
| `waiting`  | `SyncHook`                 | `compilation`         | Waiting for the issues checking. |
| `canceled` | `SyncHook`                 | `compilation`         | Issues checking for the compilation has been canceled. |
| `error`    | `SyncHook`                 | `compilation`         | An error occurred during issues checking. |
| `issues`   | `SyncWaterfallHook`        | `issues, compilation` | Issues have been received and will be reported. It's a waterfall hook, so you can modify the list of received issues. |

To access plugin hooks and tap into the event, we need to use the `getCompilerHooks` static method.
When we call this method with a [webpack compiler instance](https://webpack.js.org/api/node/), it returns the object with
[tapable](https://github.com/webpack/tapable) hooks where you can pass in your callbacks.

```js
// ./src/webpack/MyWebpackPlugin.js
const ForkTsCheckerWebpackPlugin = require('fork-ts-checker-webpack-plugin');

class MyWebpackPlugin {
  apply(compiler) {
    const hooks = ForkTsCheckerWebpackPlugin.getCompilerHooks(compiler);

    // log some message on waiting
    hooks.waiting.tap('MyPlugin', () => {
      console.log('waiting for issues');
    });
    // don't show warnings
    hooks.issues.tap('MyPlugin', (issues) => 
      issues.filter((issue) => issue.severity === 'error')
    );
  }
}

module.exports = MyWebpackPlugin;

// webpack.config.js
const ForkTsCheckerWebpackPlugin = require('fork-ts-checker-webpack-plugin');
const MyWebpackPlugin = require('./src/webpack/MyWebpackPlugin');

module.exports = {
  /* ... */
  plugins: [
    new ForkTsCheckerWebpackPlugin(),
    new MyWebpackPlugin()
  ]
};
```

## Typings

To use the plugin typings, you have to install `@types/webpack`. It's not included by default to not collide with your
existing typings (`@types/webpack` imports `@types/node`). [It's an old TypeScript issue](https://github.com/microsoft/TypeScript/issues/18588), 
the alternative is to set `skipLibCheck: true` in the `compilerOptions` 😉
```sh
# with npm
npm install --save-dev @types/webpack

# with yarn
yarn add --dev @types/webpack
```

## Profiling types resolution

Starting from TypeScript 4.1.0, you can profile long type checks by
setting "generateTrace" compiler option. This is an instruction from [microsoft/TypeScript#40063](https://github.com/microsoft/TypeScript/pull/40063):

1. Set "generateTrace": "{folderName}" in your `tsconfig.json`
2. Look in the resulting folder. If you used build mode, there will be a `legend.json` telling you what went where. 
   Otherwise, there will be `trace.json` file and `types.json` files.
3. Navigate to [edge://tracing](edge://tracing) or [chrome://tracing](chrome://tracing) and load `trace.json`
4. Expand Process 1 with the little triangle in the left sidebar
5. Click on different blocks to see their payloads in the bottom pane
6. Open `types.json` in an editor
7. When you see a type ID in the tracing output, go-to-line {id} to find data about that type


## Related projects
 
 * [`ts-loader`](https://github.com/TypeStrong/ts-loader) - TypeScript loader for webpack.
 * [`babel-loader`](https://github.com/babel/babel-loader) - Alternative TypeScript loader for webpack.
 * [`fork-ts-checker-notifier-webpack-plugin`](https://github.com/johnnyreilly/fork-ts-checker-notifier-webpack-plugin) - Notifies about build status using system notifications (similar to the [webpack-notifier](https://github.com/Turbo87/webpack-notifier)).

## Credits

This plugin was created in [Realytics](https://www.realytics.io/) in 2017. Thank you for supporting Open Source.

## License

MIT License


---

# Changelog

## 6.0.0

- **Breaking change:** The package now has named exports. See examples below.
- **Breaking change:** Separate async and sync APIs, accessible from different named exports. If you used `explorer.searchSync()` or `explorer.loadSync()`, you'll now create a sync explorer with `cosmiconfigSync()`, then use `explorerSync.search()` and `explorerSync.load()`.

  ```js
  // OLD: cosmiconfig v5
  import cosmiconfig from 'cosmiconfig';

  const explorer = cosmiconfig('example');
  const searchAsyncResult = await explorer.search();
  const loadAsyncResult = await explorer.load('./file/to/load');
  const searchSyncResult = explorer.searchSync();
  const loadSyncResult = explorer.loadSync('./file/to/load');

  // NEW: cosmiconfig v6
  import { cosmiconfig, cosmiconfigSync } from 'cosmiconfig';

  const explorer = cosmiconfig('example');
  const searchAsyncResult = await explorer.search();
  const loadAsyncResult = await explorer.load('./file/to/load');

  const explorerSync = cosmiconfigSync('example');
  const searchSyncResult = explorerSync.search();
  const loadSyncResult = explorerSync.load('./file/to/load');
  ```
- **Breaking change:** Remove support for Node 4 and 6. Requires Node 8+.
- **Breaking change:** Use npm package [yaml](https://www.npmjs.com/package/yaml) to parse YAML instead of npm package [js-yaml](https://www.npmjs.com/package/js-yaml).
- **Breaking change:** Remove `cosmiconfig.loaders` and add named export `defaultLoaders` that exports the default loaders used for each extension.

  ```js
  import { defaultLoaders } from 'cosmiconfig';

  console.log(Object.entries(defaultLoaders))
  // [
  //   [ '.js', [Function: loadJs] ],
  //   [ '.json', [Function: loadJson] ],
  //   [ '.yaml', [Function: loadYaml] ],
  //   [ '.yml', [Function: loadYaml] ],
  //   [ 'noExt', [Function: loadYaml] ]
  // ]
  ```
- Migrate from Flowtype to Typescript.
- Lazy load all default loaders.

## 5.2.1

- Chore: Upgrade `js-yaml` to avoid npm audit warning.

## 5.2.0

- Added: `packageProp` values can be arrays of strings, to allow for property names that include periods. (This was possible before, but not documented or deliberately supported.)
- Chore: Replaced the `lodash.get` dependency with a locally defined function.
- Chore: Upgrade `js-yaml` to avoid npm audit warning.

## 5.1.0

- Added: `packageProp` values can include periods to describe paths to nested objects within `package.json`.

## 5.0.7

- Fixed: JS loader bypasses Node's `require` cache, fixing a bug where updates to `.js` config files would not load even when Cosmiconfig was told not to cache.

## 5.0.6

- Fixed: Better error message if the end user tries an extension Cosmiconfig is not configured to understand.

## 5.0.5

- Fixed: `load` and `loadSync` work with paths relative to `process.cwd()`.

## 5.0.4

- Fixed: `rc` files with `.js` extensions included in default `searchPlaces`.

## 5.0.3

- Docs: Minor corrections to documentation. *Released to update package documentation on npm*.

## 5.0.2

- Fixed: Allow `searchSync` and `loadSync` to load JS configuration files whose export is a Promise.

## 5.0.1

The API has been completely revamped to increase clarity and enable a very wide range of new usage. **Please read the readme for all the details.**

While the defaults remain just as useful as before — and you can still pass no options at all — now you can also do all kinds of wild and crazy things.

- The `loaders` option allows you specify custom functions to derive config objects from files. Your loader functions could parse ES2015 modules or TypeScript, JSON5, even INI or XML. Whatever suits you.
- The `searchPlaces` option allows you to specify exactly where cosmiconfig looks within each directory it searches.
- The combination of `loaders` and `searchPlaces` means that you should be able to load pretty much any kind of configuration file you want, from wherever you want it to look.

Additionally, the overloaded `load()` function has been split up into several clear and focused functions:

- `search()` now searches up the directory tree, and `load()` loads a configuration file that you don't need to search for.
- The `sync` option has been replaced with separate synchronous functions: `searchSync()` and `loadSync()`.
- `clearFileCache()` and `clearDirectoryCache()` have been renamed to `clearLoadCache()` and `clearSearchPath()` respectively.

More details:

- The default JS loader uses `require`, instead of `require-from-string`. So you *could* use `require` hooks to control the loading of JS files (e.g. pass them through esm or Babel). In most cases it is probably preferable to use a custom loader.
- The options `rc`, `js`, and `rcExtensions` have all been removed. You can accomplish the same and more with `searchPlaces`.
- The default `searchPlaces` include `rc` files with extensions, e.g. `.thingrc.json`, `.thingrc.yaml`, `.thingrc.yml`. This is the equivalent of switching the default value of the old `rcExtensions` option to `true`.
- The option `rcStrictJson` has been removed. To get the same effect, you can specify `noExt: cosmiconfig.loadJson` in your `loaders` object.
- `packageProp` no longer accepts `false`. If you don't want to look in `package.json`, write a `searchPlaces` array that does not include it.
- By default, empty files are ignored by `search()`. The new option `ignoreEmptySearchPlaces` allows you to load them, instead, in case you want to do something with empty files.
- The option `configPath` has been removed. Just pass your filepaths directory to `load()`.
- Removed the `format` option.  Formats are now all handled via the file extensions specified in `loaders`.

(If you're wondering with happened to 5.0.0 ... it was a silly publishing mistake.)

## 4.0.0

- Licensing improvement: updated `parse-json` from `3.0.0` to `4.0.0`(see [sindresorhus/parse-json#12][parse-json-pr-12]).
- Changed: error message format for `JSON` parse errors(see [#101][pr-101]). If you were relying on the format of JSON-parsing error messages, this will be a breaking change for you.
- Changed: set default for `searchPath` as `process.cwd()` in `explorer.load`.

## 3.1.0

- Added: infer format based on filePath

## 3.0.1

- Fixed: memory leak due to bug in `require-from-string`.
- Added: for JSON files, append position to end of error message.

## 3.0.0

- Removed: support for loading config path using the `--config` flag. cosmiconfig will not parse command line arguments. Your application can parse command line arguments and pass them to cosmiconfig.
- Removed: `argv` config option.
- Removed: support for Node versions &lt; 4.
- Added: `sync` option.
- Fixed: Throw a clear error on getting empty config file.
- Fixed: when a `options.configPath` is `package.json`, return the package prop, not the entire JSON file.

## 2.2.2

- Fixed: `options.configPath` and `--config` flag are respected.

## 2.2.0, 2.2.1

- 2.2.0 included a number of improvements but somehow broke stylelint. The changes were reverted in 2.2.1, to be restored later.

## 2.1.3

- Licensing improvement: switched from `json-parse-helpfulerror` to `parse-json`.

## 2.1.2

- Fixed: bug where an `ENOENT` error would be thrown is `searchPath` referenced a non-existent file.
- Fixed: JSON parsing errors in Node v7.

## 2.1.1

- Fixed: swapped `graceful-fs` for regular `fs`, fixing a garbage collection problem.

## 2.1.0

- Added: Node 0.12 support.

## 2.0.2

- Fixed: Node version specified in `package.json`.

## 2.0.1

- Fixed: no more infinite loop in Windows.

## 2.0.0

- Changed: module now creates cosmiconfig instances with `load` methods (see README).
- Added: caching (enabled by the change above).
- Removed: support for Node versions &lt;4.

## 1.1.0

- Add `rcExtensions` option.

## 1.0.2

- Fix handling of `require()`'s within JS module configs.

## 1.0.1

- Switch Promise implementation to pinkie-promise.

## 1.0.0

- Initial release.

[parse-json-pr-12]: https://github.com/sindresorhus/parse-json/pull/12

[pr-101]: https://github.com/davidtheclark/cosmiconfig/pull/101


---

# cosmiconfig

[![Build Status](https://img.shields.io/travis/davidtheclark/cosmiconfig/master.svg?label=unix%20build)](https://travis-ci.org/davidtheclark/cosmiconfig) [![Build status](https://img.shields.io/appveyor/ci/davidtheclark/cosmiconfig/master.svg?label=windows%20build)](https://ci.appveyor.com/project/davidtheclark/cosmiconfig/branch/master)
[![codecov](https://codecov.io/gh/davidtheclark/cosmiconfig/branch/master/graph/badge.svg)](https://codecov.io/gh/davidtheclark/cosmiconfig)

Cosmiconfig searches for and loads configuration for your program.

It features smart defaults based on conventional expectations in the JavaScript ecosystem.
But it's also flexible enough to search wherever you'd like to search, and load whatever you'd like to load.

By default, Cosmiconfig will start where you tell it to start and search up the directory tree for the following:

- a `package.json` property
- a JSON or YAML, extensionless "rc file"
- an "rc file" with the extensions `.json`, `.yaml`, `.yml`, or `.js`.
- a `.config.js` CommonJS module

For example, if your module's name is "myapp", cosmiconfig will search up the directory tree for configuration in the following places:

- a `myapp` property in `package.json`
- a `.myapprc` file in JSON or YAML format
- a `.myapprc.json` file
- a `.myapprc.yaml`, `.myapprc.yml`, or `.myapprc.js` file
- a `myapp.config.js` file exporting a JS object

Cosmiconfig continues to search up the directory tree, checking each of these places in each directory, until it finds some acceptable configuration (or hits the home directory).

👀 **Looking for the v5 docs?**
v6 involves slight changes to Cosmiconfig's API, clarifying the difference between synchronous and asynchronous usage.
If you have trouble switching from v5 to v6, please file an issue.
If you are still using v5, those v5 docs are available [in the `5.x.x` tagged code](https://github.com/davidtheclark/cosmiconfig/tree/5.2.1).

## Table of contents

- [Installation](#installation)
- [Usage](#usage)
- [Result](#result)
- [Asynchronous API](#asynchronous-api)
  - [cosmiconfig()](#cosmiconfig)
  - [explorer.search()](#explorersearch)
  - [explorer.load()](#explorerload)
  - [explorer.clearLoadCache()](#explorerclearloadcache)
  - [explorer.clearSearchCache()](#explorerclearsearchcache)
  - [explorer.clearCaches()](#explorerclearcaches)
- [Synchronsous API](#synchronsous-api)
  - [cosmiconfigSync()](#cosmiconfigsync)
  - [explorerSync.search()](#explorersyncsearch)
  - [explorerSync.load()](#explorersyncload)
  - [explorerSync.clearLoadCache()](#explorersyncclearloadcache)
  - [explorerSync.clearSearchCache()](#explorersyncclearsearchcache)
  - [explorerSync.clearCaches()](#explorersyncclearcaches)
- [cosmiconfigOptions](#cosmiconfigoptions)
  - [searchPlaces](#searchplaces)
  - [loaders](#loaders)
  - [packageProp](#packageprop)
  - [stopDir](#stopdir)
  - [cache](#cache)
  - [transform](#transform)
  - [ignoreEmptySearchPlaces](#ignoreemptysearchplaces)
- [Caching](#caching)
- [Differences from rc](#differences-from-rc)
- [Contributing & Development](#contributing--development)

## Installation

```
npm install cosmiconfig
```

Tested in Node 8+.

## Usage

Create a Cosmiconfig explorer, then either `search` for or directly `load` a configuration file.

```js
const { cosmiconfig, cosmiconfigSync } = require('cosmiconfig');
// ...
const explorer = cosmiconfig(moduleName);

// Search for a configuration by walking up directories.
// See documentation for search, below.
explorer.search()
  .then((result) => {
    // result.config is the parsed configuration object.
    // result.filepath is the path to the config file that was found.
    // result.isEmpty is true if there was nothing to parse in the config file.
  })
  .catch((error) => {
    // Do something constructive.
  });

// Load a configuration directly when you know where it should be.
// The result object is the same as for search.
// See documentation for load, below.
explorer.load(pathToConfig).then(..);

// You can also search and load synchronously.
const explorerSync = cosmiconfigSync(moduleName);

const searchedFor = explorerSync.search();
const loaded = explorerSync.load(pathToConfig);
```

## Result

The result object you get from `search` or `load` has the following properties:

- **config:** The parsed configuration object. `undefined` if the file is empty.
- **filepath:** The path to the configuration file that was found.
- **isEmpty:** `true` if the configuration file is empty. This property will not be present if the configuration file is not empty.

## Asynchronous API

### cosmiconfig()

```js
const { cosmiconfig } = require('cosmiconfig');
const explorer = cosmiconfig(moduleName[, cosmiconfigOptions])
```

Creates a cosmiconfig instance ("explorer") configured according to the arguments, and initializes its caches.

#### moduleName

Type: `string`. **Required.**

Your module name. This is used to create the default [`searchPlaces`] and [`packageProp`].

If your [`searchPlaces`] value will include files, as it does by default (e.g. `${moduleName}rc`), your `moduleName` must consist of characters allowed in filenames. That means you should not copy scoped package names, such as `@my-org/my-package`, directly into `moduleName`.

**[`cosmiconfigOptions`] are documented below.**
You may not need them, and should first read about the functions you'll use.

### explorer.search()

```js
explorer.search([searchFrom]).then(result => {..})
```

Searches for a configuration file. Returns a Promise that resolves with a [result] or with `null`, if no configuration file is found.

You can do the same thing synchronously with [`explorerSync.search()`].

Let's say your module name is `goldengrahams` so you initialized with `const explorer = cosmiconfig('goldengrahams');`.
Here's how your default [`search()`] will work:

- Starting from `process.cwd()` (or some other directory defined by the `searchFrom` argument to [`search()`]), look for configuration objects in the following places:
  1. A `goldengrahams` property in a `package.json` file.
  2. A `.goldengrahamsrc` file with JSON or YAML syntax.
  3. A `.goldengrahamsrc.json` file.
  4. A `.goldengrahamsrc.yaml`, `.goldengrahamsrc.yml`, or `.goldengrahamsrc.js` file.
  5. A `goldengrahams.config.js` JS file exporting the object.
- If none of those searches reveal a configuration object, move up one directory level and try again.
  So the search continues in `./`, `../`, `../../`, `../../../`, etc., checking the same places in each directory.
- Continue searching until arriving at your home directory (or some other directory defined by the cosmiconfig option [`stopDir`]).
- If at any point a parsable configuration is found, the [`search()`] Promise resolves with its [result] \(or, with [`explorerSync.search()`], the [result] is returned).
- If no configuration object is found, the [`search()`] Promise resolves with `null` (or, with [`explorerSync.search()`], `null` is returned).
- If a configuration object is found *but is malformed* (causing a parsing error), the [`search()`] Promise rejects with that error (so you should `.catch()` it). (Or, with [`explorerSync.search()`], the error is thrown.)

**If you know exactly where your configuration file should be, you can use [`load()`], instead.**

**The search process is highly customizable.**
Use the cosmiconfig options [`searchPlaces`] and [`loaders`] to precisely define where you want to look for configurations and how you want to load them.

#### searchFrom

Type: `string`.
Default: `process.cwd()`.

A filename.
[`search()`] will start its search here.

If the value is a directory, that's where the search starts.
If it's a file, the search starts in that file's directory.

### explorer.load()

```js
explorer.load(loadPath).then(result => {..})
```

Loads a configuration file. Returns a Promise that resolves with a [result] or rejects with an error (if the file does not exist or cannot be loaded).

Use `load` if you already know where the configuration file is and you just need to load it.

```js
explorer.load('load/this/file.json'); // Tries to load load/this/file.json.
```

If you load a `package.json` file, the result will be derived from whatever property is specified as your [`packageProp`].

You can do the same thing synchronously with [`explorerSync.load()`].

### explorer.clearLoadCache()

Clears the cache used in [`load()`].

### explorer.clearSearchCache()

Clears the cache used in [`search()`].

### explorer.clearCaches()

Performs both [`clearLoadCache()`] and [`clearSearchCache()`].

## Synchronsous API

### cosmiconfigSync()

```js
const { cosmiconfigSync } = require('cosmiconfig');
const explorerSync = cosmiconfigSync(moduleName[, cosmiconfigOptions])
```

Creates a *synchronous* cosmiconfig instance ("explorerSync") configured according to the arguments, and initializes its caches.

See [`cosmiconfig()`].

### explorerSync.search()

```js
const result = explorerSync.search([searchFrom]);
```

Synchronous version of [`explorer.search()`].

Returns a [result] or `null`.

### explorerSync.load()

```js
const result = explorerSync.load(loadPath);
```

Synchronous version of [`explorer.load()`].

Returns a [result].

### explorerSync.clearLoadCache()

Clears the cache used in [`load()`].

### explorerSync.clearSearchCache()

Clears the cache used in [`search()`].

### explorerSync.clearCaches()

Performs both [`clearLoadCache()`] and [`clearSearchCache()`].

## cosmiconfigOptions

Type: `Object`.

Possible options are documented below.

### searchPlaces

Type: `Array<string>`.
Default: See below.

An array of places that [`search()`] will check in each directory as it moves up the directory tree.
Each place is relative to the directory being searched, and the places are checked in the specified order.

**Default `searchPlaces`:**

```js
[
  'package.json',
  `.${moduleName}rc`,
  `.${moduleName}rc.json`,
  `.${moduleName}rc.yaml`,
  `.${moduleName}rc.yml`,
  `.${moduleName}rc.js`,
  `${moduleName}.config.js`,
]
```

Create your own array to search more, fewer, or altogether different places.

Every item in `searchPlaces` needs to have a loader in [`loaders`] that corresponds to its extension.
(Common extensions are covered by default loaders.)
Read more about [`loaders`] below.

`package.json` is a special value: When it is included in `searchPlaces`, Cosmiconfig will always parse it as JSON and load a property within it, not the whole file.
That property is defined with the [`packageProp`] option, and defaults to your module name.

Examples, with a module named `porgy`:

```js
// Disallow extensions on rc files:
[
  'package.json',
  '.porgyrc',
  'porgy.config.js'
]

// ESLint searches for configuration in these places:
[
  '.eslintrc.js',
  '.eslintrc.yaml',
  '.eslintrc.yml',
  '.eslintrc.json',
  '.eslintrc',
  'package.json'
]

// Babel looks in fewer places:
[
  'package.json',
  '.babelrc'
]

// Maybe you want to look for a wide variety of JS flavors:
[
  'porgy.config.js',
  'porgy.config.mjs',
  'porgy.config.ts',
  'porgy.config.coffee'
]
// ^^ You will need to designate custom loaders to tell
// Cosmiconfig how to handle these special JS flavors.

// Look within a .config/ subdirectory of every searched directory:
[
  'package.json',
  '.porgyrc',
  '.config/.porgyrc',
  '.porgyrc.json',
  '.config/.porgyrc.json'
]
```

### loaders

Type: `Object`.
Default: See below.

An object that maps extensions to the loader functions responsible for loading and parsing files with those extensions.

Cosmiconfig exposes its default loaders on a named export `defaultLoaders`.

**Default `loaders`:**

```js
const { defaultLoaders } = require('cosmiconfig');

console.log(Object.entries(defaultLoaders))
// [
//   [ '.js', [Function: loadJs] ],
//   [ '.json', [Function: loadJson] ],
//   [ '.yaml', [Function: loadYaml] ],
//   [ '.yml', [Function: loadYaml] ],
//   [ 'noExt', [Function: loadYaml] ]
// ]
```

(YAML is a superset of JSON; which means YAML parsers can parse JSON; which is how extensionless files can be either YAML *or* JSON with only one parser.)

**If you provide a `loaders` object, your object will be *merged* with the defaults.**
So you can override one or two without having to override them all.

**Keys in `loaders`** are extensions (starting with a period), or `noExt` to specify the loader for files *without* extensions, like `.myapprc`.

**Values in `loaders`** are a loader function (described below) whose values are loader functions.

**The most common use case for custom loaders value is to load extensionless `rc` files as strict JSON**, instead of JSON *or* YAML (the default).
To accomplish that, provide the following `loaders` value:

```js
{
  noExt: defaultLoaders['.json']
}
```

If you want to load files that are not handled by the loader functions Cosmiconfig exposes, you can write a custom loader function or use one from NPM if it exists.

**Third-party loaders:**

- [@endemolshinegroup/cosmiconfig-typescript-loader](https://github.com/EndemolShineGroup/cosmiconfig-typescript-loader)

**Use cases for custom loader function:**

- Allow configuration syntaxes that aren't handled by Cosmiconfig's defaults, like JSON5, INI, or XML.
- Allow ES2015 modules from `.mjs` configuration files.
- Parse JS files with Babel before deriving the configuration.

**Custom loader functions** have the following signature:

```js
// Sync
(filepath: string, content: string) => Object | null

// Async
(filepath: string, content: string) => Object | null | Promise<Object | null>
```

Cosmiconfig reads the file when it checks whether the file exists, so it will provide you with both the file's path and its content.
Do whatever you need to, and return either a configuration object or `null` (or, for async-only loaders, a Promise that resolves with one of those).
`null` indicates that no real configuration was found and the search should continue.

A few things to note:

- If you use a custom loader, be aware of whether it's sync or async: you cannot use async customer loaders with the sync API ([`cosmiconfigSync()`]).
- **Special JS syntax can also be handled by using a `require` hook**, because `defaultLoaders['.js']` just uses `require`.
  Whether you use custom loaders or a `require` hook is up to you.

Examples:

```js
// Allow JSON5 syntax:
{
  '.json': json5Loader
}

// Allow a special configuration syntax of your own creation:
{
  '.special': specialLoader
}

// Allow many flavors of JS, using custom loaders:
{
  '.mjs': esmLoader,
  '.ts': typeScriptLoader,
  '.coffee': coffeeScriptLoader
}

// Allow many flavors of JS but rely on require hooks:
{
  '.mjs': defaultLoaders['.js'],
  '.ts': defaultLoaders['.js'],
  '.coffee': defaultLoaders['.js']
}
```

### packageProp

Type: `string | Array<string>`.
Default: `` `${moduleName}` ``.

Name of the property in `package.json` to look for.

Use a period-delimited string or an array of strings to describe a path to nested properties.

For example, the value `'configs.myPackage'` or `['configs', 'myPackage']` will get you the `"myPackage"` value in a `package.json` like this:

```json
{
  "configs": {
    "myPackage": {..}
  }
}
```

If nested property names within the path include periods, you need to use an array of strings. For example, the value `['configs', 'foo.bar', 'baz']` will get you the `"baz"` value in a `package.json` like this:

```json
{
  "configs": {
    "foo.bar": {
      "baz": {..}
    }
  }
}
```

If a string includes period but corresponds to a top-level property name, it will not be interpreted as a period-delimited path. For example, the value `'one.two'` will get you the `"three"` value in a `package.json` like this:

```json
{
  "one.two": "three",
  "one": {
    "two": "four"
  }
}
```

### stopDir

Type: `string`.
Default: Absolute path to your home directory.

Directory where the search will stop.

### cache

Type: `boolean`.
Default: `true`.

If `false`, no caches will be used.
Read more about ["Caching"](#caching) below.

### transform

Type: `(Result) => Promise<Result> | Result`.

A function that transforms the parsed configuration. Receives the [result].

If using [`search()`] or [`load()`] \(which are async), the transform function can return the transformed result or return a Promise that resolves with the transformed result.
If using `cosmiconfigSync`, [`search()`] or [`load()`], the function must be synchronous and return the transformed result.

The reason you might use this option — instead of simply applying your transform function some other way — is that *the transformed result will be cached*. If your transformation involves additional filesystem I/O or other potentially slow processing, you can use this option to avoid repeating those steps every time a given configuration is searched or loaded.

### ignoreEmptySearchPlaces

Type: `boolean`.
Default: `true`.

By default, if [`search()`] encounters an empty file (containing nothing but whitespace) in one of the [`searchPlaces`], it will ignore the empty file and move on.
If you'd like to load empty configuration files, instead, set this option to `false`.

Why might you want to load empty configuration files?
If you want to throw an error, or if an empty configuration file means something to your program.

## Caching

As of v2, cosmiconfig uses caching to reduce the need for repetitious reading of the filesystem or expensive transforms. Every new cosmiconfig instance (created with `cosmiconfig()`) has its own caches.

To avoid or work around caching, you can do the following:

- Set the `cosmiconfig` option [`cache`] to `false`.
- Use the cache-clearing methods [`clearLoadCache()`], [`clearSearchCache()`], and [`clearCaches()`].
- Create separate instances of cosmiconfig (separate "explorers").

## Differences from [rc](https://github.com/dominictarr/rc)

[rc](https://github.com/dominictarr/rc) serves its focused purpose well. cosmiconfig differs in a few key ways — making it more useful for some projects, less useful for others:

- Looks for configuration in some different places: in a `package.json` property, an rc file, a `.config.js` file, and rc files with extensions.
- Built-in support for JSON, YAML, and CommonJS formats.
- Stops at the first configuration found, instead of finding all that can be found up the directory tree and merging them automatically.
- Options.
- Asynchronous by default (though can be run synchronously).

## Contributing & Development

Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.

And please do participate!

[result]: #result

[`load()`]: #explorerload

[`search()`]: #explorersearch

[`clearloadcache()`]: #explorerclearloadcache

[`clearsearchcache()`]: #explorerclearsearchcache

[`cosmiconfig()`]: #cosmiconfig

[`cosmiconfigSync()`]: #cosmiconfigsync

[`clearcaches()`]: #explorerclearcaches

[`packageprop`]: #packageprop

[`cache`]: #cache

[`stopdir`]: #stopdir

[`searchplaces`]: #searchplaces

[`loaders`]: #loaders

[`cosmiconfigoptions`]: #cosmiconfigoptions

[`explorerSync.search()`]: #explorersyncsearch

[`explorerSync.load()`]: #explorersyncload

[`explorer.search()`]: #explorersearch

[`explorer.load()`]: #explorerload


---

9.1.0 / 2021-01-19
------------------

- Add promise support for `fs.rm()` ([#841](https://github.com/jprichardson/node-fs-extra/issues/841), [#860](https://github.com/jprichardson/node-fs-extra/pull/860))
- Upgrade universalify for performance improvments ([#825](https://github.com/jprichardson/node-fs-extra/pull/825))

9.0.1 / 2020-06-03
------------------

- Fix issue with `ensureFile()` when used with Jest on Windows ([#804](https://github.com/jprichardson/node-fs-extra/issues/804), [#805](https://github.com/jprichardson/node-fs-extra/pull/805))
- Remove unneeded `process.umask()` call ([#791](https://github.com/jprichardson/node-fs-extra/pull/791))
- Docs improvements ([#753](https://github.com/jprichardson/node-fs-extra/pull/753), [#795](https://github.com/jprichardson/node-fs-extra/pull/795), [#797](https://github.com/jprichardson/node-fs-extra/pull/797))

9.0.0 / 2020-03-19
------------------

### Breaking changes

- Requires Node.js version 10 or greater ([#725](https://github.com/jprichardson/node-fs-extra/issues/725), [#751](https://github.com/jprichardson/node-fs-extra/pull/751))
- Switched `ensureDir*` to use a fork of https://github.com/sindresorhus/make-dir to make use of native recursive `fs.mkdir` where possible ([#619](https://github.com/jprichardson/node-fs-extra/issues/619), [#756](https://github.com/jprichardson/node-fs-extra/pull/756))
- Properly preserve `atime` for `copy*` with `preserveTimestamps` option ([#633](https://github.com/jprichardson/node-fs-extra/pull/633))

**The following changes, allthough technically breaking, will not affect the vast majority of users:**

- `outputJson` now outputs objects as they were when the function was called, even if they are mutated later ([#702](https://github.com/jprichardson/node-fs-extra/issues/702), [#768](https://github.com/jprichardson/node-fs-extra/pull/768))
- Cannot pass `null` as an options parameter to `*Json*` methods ([#745](https://github.com/jprichardson/node-fs-extra/issues/745), [#768](https://github.com/jprichardson/node-fs-extra/pull/768))

### Improvements

- Add promise shims for `fs.writev` & `fs.opendir` ([#747](https://github.com/jprichardson/node-fs-extra/pull/747))
- Better errors for `ensureFile` ([#696](https://github.com/jprichardson/node-fs-extra/issues/696), [#744](https://github.com/jprichardson/node-fs-extra/pull/744))
- Better file comparison for older Node versions ([#694](https://github.com/jprichardson/node-fs-extra/pull/694))

### Miscellaneous changes
- Peformance optimizations ([#762](https://github.com/jprichardson/node-fs-extra/issues/762), [#764](https://github.com/jprichardson/node-fs-extra/pull/764))
- Add missing documentation for aliases ([#758](https://github.com/jprichardson/node-fs-extra/issues/758), [#766](https://github.com/jprichardson/node-fs-extra/pull/766))
- Update `universalify` dependency ([#767](https://github.com/jprichardson/node-fs-extra/pull/767))

8.1.0 / 2019-06-28
------------------

- Add support for promisified `fs.realpath.native` in Node v9.2+ ([#650](https://github.com/jprichardson/node-fs-extra/issues/650), [#682](https://github.com/jprichardson/node-fs-extra/pull/682))
- Update `graceful-fs` dependency ([#700](https://github.com/jprichardson/node-fs-extra/pull/700))
- Use `graceful-fs` everywhere ([#700](https://github.com/jprichardson/node-fs-extra/pull/700))

8.0.1 / 2019-05-13
------------------

- Fix bug `Maximum call stack size exceeded` error in `util/stat` ([#679](https://github.com/jprichardson/node-fs-extra/pull/679))

8.0.0 / 2019-05-11
------------------

**NOTE:** Node.js v6 support is deprecated, and will be dropped in the next major release.

- Use `renameSync()` under the hood in `moveSync()`
- Fix bug with bind-mounted directories in `copy*()` ([#613](https://github.com/jprichardson/node-fs-extra/issues/613), [#618](https://github.com/jprichardson/node-fs-extra/pull/618))
- Fix bug in `move()` with case-insensitive file systems
- Use `fs.stat()`'s `bigint` option in `copy*()` & `move*()` where possible ([#657](https://github.com/jprichardson/node-fs-extra/issues/657))

7.0.1 / 2018-11-07
------------------

- Fix `removeSync()` on Windows, in some cases, it would error out with `ENOTEMPTY` ([#646](https://github.com/jprichardson/node-fs-extra/pull/646))
- Document `mode` option for `ensureDir*()` ([#587](https://github.com/jprichardson/node-fs-extra/pull/587))
- Don't include documentation files in npm package tarball ([#642](https://github.com/jprichardson/node-fs-extra/issues/642), [#643](https://github.com/jprichardson/node-fs-extra/pull/643))

7.0.0 / 2018-07-16
------------------

- **BREAKING:** Refine `copy*()` handling of symlinks to properly detect symlinks that point to the same file. ([#582](https://github.com/jprichardson/node-fs-extra/pull/582))
- Fix bug with copying write-protected directories ([#600](https://github.com/jprichardson/node-fs-extra/pull/600))
- Universalify `fs.lchmod()` ([#596](https://github.com/jprichardson/node-fs-extra/pull/596))
- Add `engines` field to `package.json` ([#580](https://github.com/jprichardson/node-fs-extra/pull/580))

6.0.1 / 2018-05-09
------------------

- Fix `fs.promises` `ExperimentalWarning` on Node v10.1.0 ([#578](https://github.com/jprichardson/node-fs-extra/pull/578))

6.0.0 / 2018-05-01
------------------

- Drop support for Node.js versions 4, 5, & 7 ([#564](https://github.com/jprichardson/node-fs-extra/pull/564))
- Rewrite `move` to use `fs.rename` where possible ([#549](https://github.com/jprichardson/node-fs-extra/pull/549))
- Don't convert relative paths to absolute paths for `filter` ([#554](https://github.com/jprichardson/node-fs-extra/pull/554))
- `copy*`'s behavior when `preserveTimestamps` is `false` has been OS-dependent since 5.0.0, but that's now explicitly noted in the docs ([#563](https://github.com/jprichardson/node-fs-extra/pull/563))
- Fix subdirectory detection for `copy*` & `move*` ([#541](https://github.com/jprichardson/node-fs-extra/pull/541))
- Handle case-insensitive paths correctly in `copy*` ([#568](https://github.com/jprichardson/node-fs-extra/pull/568))

5.0.0 / 2017-12-11
------------------

Significant refactor of `copy()` & `copySync()`, including breaking changes. No changes to other functions in this release.

Huge thanks to **[@manidlou](https://github.com/manidlou)** for doing most of the work on this release.

- The `filter` option can no longer be a RegExp (must be a function). This was deprecated since fs-extra v1.0.0. [#512](https://github.com/jprichardson/node-fs-extra/pull/512)
- `copy()`'s `filter` option can now be a function that returns a Promise. [#518](https://github.com/jprichardson/node-fs-extra/pull/518)
- `copy()` & `copySync()` now use `fs.copyFile()`/`fs.copyFileSync()` in environments that support it (currently Node 8.5.0+). Older Node versions still get the old implementation. [#505](https://github.com/jprichardson/node-fs-extra/pull/505)
- Don't allow copying a directory into itself. [#83](https://github.com/jprichardson/node-fs-extra/issues/83)
- Handle copying between identical files. [#198](https://github.com/jprichardson/node-fs-extra/issues/198)
- Error out when copying an empty folder to a path that already exists. [#464](https://github.com/jprichardson/node-fs-extra/issues/464)
- Don't create `dest`'s parent if the `filter` function aborts the `copy()` operation. [#517](https://github.com/jprichardson/node-fs-extra/pull/517)
- Fix `writeStream` not being closed if there was an error in `copy()`. [#516](https://github.com/jprichardson/node-fs-extra/pull/516)

4.0.3 / 2017-12-05
------------------

- Fix wrong `chmod` values in `fs.remove()` [#501](https://github.com/jprichardson/node-fs-extra/pull/501)
- Fix `TypeError` on systems that don't have some `fs` operations like `lchown` [#520](https://github.com/jprichardson/node-fs-extra/pull/520)

4.0.2 / 2017-09-12
------------------

- Added `EOL` option to `writeJson*` & `outputJson*` (via upgrade to jsonfile v4)
- Added promise support to [`fs.copyFile()`](https://nodejs.org/api/fs.html#fs_fs_copyfile_src_dest_flags_callback) in Node 8.5+
- Added `.js` extension to `main` field in `package.json` for better tooling compatibility. [#485](https://github.com/jprichardson/node-fs-extra/pull/485)

4.0.1 / 2017-07-31
------------------

### Fixed

- Previously, `ensureFile()` & `ensureFileSync()` would do nothing if the path was a directory. Now, they error out for consistency with `ensureDir()`. [#465](https://github.com/jprichardson/node-fs-extra/issues/465), [#466](https://github.com/jprichardson/node-fs-extra/pull/466), [#470](https://github.com/jprichardson/node-fs-extra/issues/470)

4.0.0 / 2017-07-14
------------------

### Changed

- **BREAKING:** The promisified versions of `fs.read()` & `fs.write()` now return objects. See [the docs](docs/fs-read-write.md) for details. [#436](https://github.com/jprichardson/node-fs-extra/issues/436), [#449](https://github.com/jprichardson/node-fs-extra/pull/449)
- `fs.move()` now errors out when destination is a subdirectory of source. [#458](https://github.com/jprichardson/node-fs-extra/pull/458)
- Applied upstream fixes from `rimraf` to `fs.remove()` & `fs.removeSync()`. [#459](https://github.com/jprichardson/node-fs-extra/pull/459)

### Fixed

- Got `fs.outputJSONSync()` working again; it was broken due to refactoring. [#428](https://github.com/jprichardson/node-fs-extra/pull/428)

Also clarified the docs in a few places.

3.0.1 / 2017-05-04
------------------

- Fix bug in `move()` & `moveSync()` when source and destination are the same, and source does not exist. [#415](https://github.com/jprichardson/node-fs-extra/pull/415)

3.0.0 / 2017-04-27
------------------

### Added

- **BREAKING:** Added Promise support. All asynchronous native fs methods and fs-extra methods now return a promise if the callback is not passed. [#403](https://github.com/jprichardson/node-fs-extra/pull/403)
- `pathExists()`, a replacement for the deprecated `fs.exists`. `pathExists` has a normal error-first callback signature. Also added `pathExistsSync`, an alias to `fs.existsSync`, for completeness. [#406](https://github.com/jprichardson/node-fs-extra/pull/406)

### Removed

- **BREAKING:** Removed support for setting the default spaces for `writeJson()`, `writeJsonSync()`, `outputJson()`, & `outputJsonSync()`. This was undocumented. [#402](https://github.com/jprichardson/node-fs-extra/pull/402)

### Changed

- Upgraded jsonfile dependency to v3.0.0:
  - **BREAKING:** Changed behavior of `throws` option for `readJsonSync()`; now does not throw filesystem errors when `throws` is `false`.
- **BREAKING:** `writeJson()`, `writeJsonSync()`, `outputJson()`, & `outputJsonSync()` now output minified JSON by default for consistency with `JSON.stringify()`; set the `spaces` option to `2` to override this new behavior. [#402](https://github.com/jprichardson/node-fs-extra/pull/402)
- Use `Buffer.allocUnsafe()` instead of `new Buffer()` in environments that support it. [#394](https://github.com/jprichardson/node-fs-extra/pull/394)

### Fixed

- `removeSync()` silently failed on Windows in some cases. Now throws an `EBUSY` error. [#408](https://github.com/jprichardson/node-fs-extra/pull/408)

2.1.2 / 2017-03-16
------------------

### Fixed

- Weird windows bug that resulted in `ensureDir()`'s callback being called twice in some cases. This bug may have also affected `remove()`. See [#392](https://github.com/jprichardson/node-fs-extra/issues/392), [#393](https://github.com/jprichardson/node-fs-extra/pull/393)

2.1.1 / 2017-03-15
------------------

### Fixed

- Reverted [`5597bd`](https://github.com/jprichardson/node-fs-extra/commit/5597bd5b67f7d060f5f5bf26e9635be48330f5d7), this broke compatibility with Node.js versions v4+ but less than `v4.5.0`.
- Remove `Buffer.alloc()` usage in `moveSync()`.

2.1.0 / 2017-03-15
------------------

Thanks to [Mani Maghsoudlou (@manidlou)](https://github.com/manidlou) & [Jan Peer Stöcklmair (@JPeer264)](https://github.com/JPeer264) for their extraordinary help with this release!

### Added
- `moveSync()` See [#309], [#381](https://github.com/jprichardson/node-fs-extra/pull/381). ([@manidlou](https://github.com/manidlou))
- `copy()` and `copySync()`'s `filter` option now gets the destination path passed as the second parameter. [#366](https://github.com/jprichardson/node-fs-extra/pull/366) ([@manidlou](https://github.com/manidlou))

### Changed
- Use `Buffer.alloc()` instead of deprecated `new Buffer()` in `copySync()`. [#380](https://github.com/jprichardson/node-fs-extra/pull/380) ([@manidlou](https://github.com/manidlou))
- Refactored entire codebase to use ES6 features supported by Node.js v4+ [#355](https://github.com/jprichardson/node-fs-extra/issues/355). [(@JPeer264)](https://github.com/JPeer264)
- Refactored docs. ([@manidlou](https://github.com/manidlou))

### Fixed

- `move()` shouldn't error out when source and dest are the same. [#377](https://github.com/jprichardson/node-fs-extra/issues/377), [#378](https://github.com/jprichardson/node-fs-extra/pull/378) ([@jdalton](https://github.com/jdalton))

2.0.0 / 2017-01-16
------------------

### Removed
- **BREAKING:** Removed support for Node `v0.12`. The Node foundation stopped officially supporting it
on Jan 1st, 2017.
- **BREAKING:** Remove `walk()` and `walkSync()`. `walkSync()` was only part of `fs-extra` for a little
over two months. Use [klaw](https://github.com/jprichardson/node-klaw) instead of `walk()`, in fact, `walk()` was just
an alias to klaw. For `walkSync()` use [klaw-sync](https://github.com/mawni/node-klaw-sync). See: [#338], [#339]

### Changed
- **BREAKING:** Renamed `clobber` to `overwrite`. This affects `copy()`, `copySync()`, and `move()`. [#330], [#333]
- Moved docs, to `docs/`. [#340]

### Fixed
- Apply filters to directories in `copySync()` like in `copy()`. [#324]
- A specific condition when disk is under heavy use, `copy()` can fail. [#326]


1.0.0 / 2016-11-01
------------------

After five years of development, we finally have reach the 1.0.0 milestone! Big thanks goes
to [Ryan Zim](https://github.com/RyanZim) for leading the charge on this release!

### Added
- `walkSync()`

### Changed
- **BREAKING**: dropped Node v0.10 support.
- disabled `rimaf` globbing, wasn't used. [#280]
- deprecate `copy()/copySync()` option `filter` if it's a `RegExp`. `filter` should now be a function.
- inline `rimraf`. This is temporary and was done because `rimraf` depended upon the beefy `glob` which `fs-extra` does not use. [#300]

### Fixed
- bug fix proper closing of file handle on `utimesMillis()` [#271]
- proper escaping of files with dollar signs [#291]
- `copySync()` failed if user didn't own file. [#199], [#301]


0.30.0 / 2016-04-28
-------------------
- Brought back Node v0.10 support. I didn't realize there was still demand. Official support will end **2016-10-01**.

0.29.0 / 2016-04-27
-------------------
- **BREAKING**: removed support for Node v0.10. If you still want to use Node v0.10, everything should work except for `ensureLink()/ensureSymlink()`. Node v0.12 is still supported but will be dropped in the near future as well.

0.28.0 / 2016-04-17
-------------------
- **BREAKING**: removed `createOutputStream()`. Use https://www.npmjs.com/package/create-output-stream. See: [#192][#192]
- `mkdirs()/mkdirsSync()` check for invalid win32 path chars. See: [#209][#209], [#237][#237]
- `mkdirs()/mkdirsSync()` if drive not mounted, error. See: [#93][#93]

0.27.0 / 2016-04-15
-------------------
- add `dereference` option to `copySync()`. [#235][#235]

0.26.7 / 2016-03-16
-------------------
- fixed `copy()` if source and dest are the same. [#230][#230]

0.26.6 / 2016-03-15
-------------------
- fixed if `emptyDir()` does not have a callback: [#229][#229]

0.26.5 / 2016-01-27
-------------------
- `copy()` with two arguments (w/o callback) was broken. See: [#215][#215]

0.26.4 / 2016-01-05
-------------------
- `copySync()` made `preserveTimestamps` default consistent with `copy()` which is `false`. See: [#208][#208]

0.26.3 / 2015-12-17
-------------------
- fixed `copy()` hangup in copying blockDevice / characterDevice / `/dev/null`. See: [#193][#193]

0.26.2 / 2015-11-02
-------------------
- fixed `outputJson{Sync}()` spacing adherence to `fs.spaces`

0.26.1 / 2015-11-02
-------------------
- fixed `copySync()` when `clogger=true` and the destination is read only. See: [#190][#190]

0.26.0 / 2015-10-25
-------------------
- extracted the `walk()` function into its own module [`klaw`](https://github.com/jprichardson/node-klaw).

0.25.0 / 2015-10-24
-------------------
- now has a file walker `walk()`

0.24.0 / 2015-08-28
-------------------
- removed alias `delete()` and `deleteSync()`. See: [#171][#171]

0.23.1 / 2015-08-07
-------------------
- Better handling of errors for `move()` when moving across devices. [#170][#170]
- `ensureSymlink()` and `ensureLink()` should not throw errors if link exists. [#169][#169]

0.23.0 / 2015-08-06
-------------------
- added `ensureLink{Sync}()` and `ensureSymlink{Sync}()`. See: [#165][#165]

0.22.1 / 2015-07-09
-------------------
- Prevent calling `hasMillisResSync()` on module load. See: [#149][#149].
Fixes regression that was introduced in `0.21.0`.

0.22.0 / 2015-07-09
-------------------
- preserve permissions / ownership in `copy()`. See: [#54][#54]

0.21.0 / 2015-07-04
-------------------
- add option to preserve timestamps in `copy()` and `copySync()`. See: [#141][#141]
- updated `graceful-fs@3.x` to `4.x`. This brings in features from `amazing-graceful-fs` (much cleaner code / less hacks)

0.20.1 / 2015-06-23
-------------------
- fixed regression caused by latest jsonfile update: See: https://github.com/jprichardson/node-jsonfile/issues/26

0.20.0 / 2015-06-19
-------------------
- removed `jsonfile` aliases with `File` in the name, they weren't documented and probably weren't in use e.g.
this package had both `fs.readJsonFile` and `fs.readJson` that were aliases to each other, now use `fs.readJson`.
- preliminary walker created. Intentionally not documented. If you use it, it will almost certainly change and break your code.
- started moving tests inline
- upgraded to `jsonfile@2.1.0`, can now pass JSON revivers/replacers to `readJson()`, `writeJson()`, `outputJson()`

0.19.0 / 2015-06-08
-------------------
- `fs.copy()` had support for Node v0.8, dropped support

0.18.4 / 2015-05-22
-------------------
- fixed license field according to this: [#136][#136] and https://github.com/npm/npm/releases/tag/v2.10.0

0.18.3 / 2015-05-08
-------------------
- bugfix: handle `EEXIST` when clobbering on some Linux systems. [#134][#134]

0.18.2 / 2015-04-17
-------------------
- bugfix: allow `F_OK` ([#120][#120])

0.18.1 / 2015-04-15
-------------------
- improved windows support for `move()` a bit. https://github.com/jprichardson/node-fs-extra/commit/92838980f25dc2ee4ec46b43ee14d3c4a1d30c1b
- fixed a lot of tests for Windows (appveyor)

0.18.0 / 2015-03-31
-------------------
- added `emptyDir()` and `emptyDirSync()`

0.17.0 / 2015-03-28
-------------------
- `copySync` added `clobber` option (before always would clobber, now if `clobber` is `false` it throws an error if the destination exists).
**Only works with files at the moment.**
- `createOutputStream()` added. See: [#118][#118]

0.16.5 / 2015-03-08
-------------------
- fixed `fs.move` when `clobber` is `true` and destination is a directory, it should clobber. [#114][#114]

0.16.4 / 2015-03-01
-------------------
- `fs.mkdirs` fix infinite loop on Windows. See: See https://github.com/substack/node-mkdirp/pull/74 and https://github.com/substack/node-mkdirp/issues/66

0.16.3 / 2015-01-28
-------------------
- reverted https://github.com/jprichardson/node-fs-extra/commit/1ee77c8a805eba5b99382a2591ff99667847c9c9


0.16.2 / 2015-01-28
-------------------
- fixed `fs.copy` for Node v0.8 (support is temporary and will be removed in the near future)

0.16.1 / 2015-01-28
-------------------
- if `setImmediate` is not available, fall back to `process.nextTick`

0.16.0 / 2015-01-28
-------------------
- bugfix `fs.move()` into itself. Closes [#104]
- bugfix `fs.move()` moving directory across device. Closes [#108]
- added coveralls support
- bugfix: nasty multiple callback `fs.copy()` bug. Closes [#98]
- misc fs.copy code cleanups

0.15.0 / 2015-01-21
-------------------
- dropped `ncp`, imported code in
- because of previous, now supports `io.js`
- `graceful-fs` is now a dependency

0.14.0 / 2015-01-05
-------------------
- changed `copy`/`copySync` from `fs.copy(src, dest, [filters], callback)` to `fs.copy(src, dest, [options], callback)` [#100][#100]
- removed mockfs tests for mkdirp (this may be temporary, but was getting in the way of other tests)

0.13.0 / 2014-12-10
-------------------
- removed `touch` and `touchSync` methods (they didn't handle permissions like UNIX touch)
- updated `"ncp": "^0.6.0"` to `"ncp": "^1.0.1"`
- imported `mkdirp` => `minimist` and `mkdirp` are no longer dependences, should now appease people who wanted `mkdirp` to be `--use_strict` safe. See [#59]([#59][#59])

0.12.0 / 2014-09-22
-------------------
- copy symlinks in `copySync()` [#85][#85]

0.11.1 / 2014-09-02
-------------------
- bugfix `copySync()` preserve file permissions [#80][#80]

0.11.0 / 2014-08-11
-------------------
- upgraded `"ncp": "^0.5.1"` to `"ncp": "^0.6.0"`
- upgrade `jsonfile": "^1.2.0"` to `jsonfile": "^2.0.0"` => on write, json files now have `\n` at end. Also adds `options.throws` to `readJsonSync()`
see https://github.com/jprichardson/node-jsonfile#readfilesyncfilename-options for more details.

0.10.0 / 2014-06-29
------------------
* bugfix: upgaded `"jsonfile": "~1.1.0"` to `"jsonfile": "^1.2.0"`, bumped minor because of `jsonfile` dep change
from `~` to `^`. [#67]

0.9.1 / 2014-05-22
------------------
* removed Node.js `0.8.x` support, `0.9.0` was published moments ago and should have been done there

0.9.0 / 2014-05-22
------------------
* upgraded `ncp` from `~0.4.2` to `^0.5.1`, [#58]
* upgraded `rimraf` from `~2.2.6` to `^2.2.8`
* upgraded `mkdirp` from `0.3.x` to `^0.5.0`
* added methods `ensureFile()`, `ensureFileSync()`
* added methods `ensureDir()`, `ensureDirSync()` [#31]
* added `move()` method. From: https://github.com/andrewrk/node-mv


0.8.1 / 2013-10-24
------------------
* copy failed to return an error to the callback if a file doesn't exist (ulikoehler [#38], [#39])

0.8.0 / 2013-10-14
------------------
* `filter` implemented on `copy()` and `copySync()`. (Srirangan / [#36])

0.7.1 / 2013-10-12
------------------
* `copySync()` implemented (Srirangan / [#33])
* updated to the latest `jsonfile` version `1.1.0` which gives `options` params for the JSON methods. Closes [#32]

0.7.0 / 2013-10-07
------------------
* update readme conventions
* `copy()` now works if destination directory does not exist. Closes [#29]

0.6.4 / 2013-09-05
------------------
* changed `homepage` field in package.json to remove NPM warning

0.6.3 / 2013-06-28
------------------
* changed JSON spacing default from `4` to `2` to follow Node conventions
* updated `jsonfile` dep
* updated `rimraf` dep

0.6.2 / 2013-06-28
------------------
* added .npmignore, [#25]

0.6.1 / 2013-05-14
------------------
* modified for `strict` mode, closes [#24]
* added `outputJson()/outputJsonSync()`, closes [#23]

0.6.0 / 2013-03-18
------------------
* removed node 0.6 support
* added node 0.10 support
* upgraded to latest `ncp` and `rimraf`.
* optional `graceful-fs` support. Closes [#17]


0.5.0 / 2013-02-03
------------------
* Removed `readTextFile`.
* Renamed `readJSONFile` to `readJSON` and `readJson`, same with write.
* Restructured documentation a bit. Added roadmap.

0.4.0 / 2013-01-28
------------------
* Set default spaces in `jsonfile` from 4 to 2.
* Updated `testutil` deps for tests.
* Renamed `touch()` to `createFile()`
* Added `outputFile()` and `outputFileSync()`
* Changed creation of testing diretories so the /tmp dir is not littered.
* Added `readTextFile()` and `readTextFileSync()`.

0.3.2 / 2012-11-01
------------------
* Added `touch()` and `touchSync()` methods.

0.3.1 / 2012-10-11
------------------
* Fixed some stray globals.

0.3.0 / 2012-10-09
------------------
* Removed all CoffeeScript from tests.
* Renamed `mkdir` to `mkdirs`/`mkdirp`.

0.2.1 / 2012-09-11
------------------
* Updated `rimraf` dep.

0.2.0 / 2012-09-10
------------------
* Rewrote module into JavaScript. (Must still rewrite tests into JavaScript)
* Added all methods of [jsonfile](https://github.com/jprichardson/node-jsonfile)
* Added Travis-CI.

0.1.3 / 2012-08-13
------------------
* Added method `readJSONFile`.

0.1.2 / 2012-06-15
------------------
* Bug fix: `deleteSync()` didn't exist.
* Verified Node v0.8 compatibility.

0.1.1 / 2012-06-15
------------------
* Fixed bug in `remove()`/`delete()` that wouldn't execute the function if a callback wasn't passed.

0.1.0 / 2012-05-31
------------------
* Renamed `copyFile()` to `copy()`. `copy()` can now copy directories (recursively) too.
* Renamed `rmrf()` to `remove()`.
* `remove()` aliased with `delete()`.
* Added `mkdirp` capabilities. Named: `mkdir()`. Hides Node.js native `mkdir()`.
* Instead of exporting the native `fs` module with new functions, I now copy over the native methods to a new object and export that instead.

0.0.4 / 2012-03-14
------------------
* Removed CoffeeScript dependency

0.0.3 / 2012-01-11
------------------
* Added methods rmrf and rmrfSync
* Moved tests from Jasmine to Mocha


[#344]: https://github.com/jprichardson/node-fs-extra/issues/344    "Licence Year"
[#343]: https://github.com/jprichardson/node-fs-extra/pull/343      "Add klaw-sync link to readme"
[#342]: https://github.com/jprichardson/node-fs-extra/pull/342      "allow preserveTimestamps when use move"
[#341]: https://github.com/jprichardson/node-fs-extra/issues/341    "mkdirp(path.dirname(dest) in move() logic needs cleaning up [question]"
[#340]: https://github.com/jprichardson/node-fs-extra/pull/340      "Move docs to seperate docs folder [documentation]"
[#339]: https://github.com/jprichardson/node-fs-extra/pull/339      "Remove walk() & walkSync() [feature-walk]"
[#338]: https://github.com/jprichardson/node-fs-extra/issues/338    "Remove walk() and walkSync() [feature-walk]"
[#337]: https://github.com/jprichardson/node-fs-extra/issues/337    "copy doesn't return a yieldable value"
[#336]: https://github.com/jprichardson/node-fs-extra/pull/336      "Docs enhanced walk sync [documentation, feature-walk]"
[#335]: https://github.com/jprichardson/node-fs-extra/pull/335      "Refactor move() tests [feature-move]"
[#334]: https://github.com/jprichardson/node-fs-extra/pull/334      "Cleanup lib/move/index.js [feature-move]"
[#333]: https://github.com/jprichardson/node-fs-extra/pull/333      "Rename clobber to overwrite [feature-copy, feature-move]"
[#332]: https://github.com/jprichardson/node-fs-extra/pull/332      "BREAKING: Drop Node v0.12 & io.js support"
[#331]: https://github.com/jprichardson/node-fs-extra/issues/331    "Add support for chmodr [enhancement, future]"
[#330]: https://github.com/jprichardson/node-fs-extra/pull/330      "BREAKING: Do not error when copy destination exists & clobber: false [feature-copy]"
[#329]: https://github.com/jprichardson/node-fs-extra/issues/329    "Does .walk() scale to large directories? [question]"
[#328]: https://github.com/jprichardson/node-fs-extra/issues/328    "Copying files corrupts [feature-copy, needs-confirmed]"
[#327]: https://github.com/jprichardson/node-fs-extra/pull/327      "Use writeStream 'finish' event instead of 'close' [bug, feature-copy]"
[#326]: https://github.com/jprichardson/node-fs-extra/issues/326    "fs.copy fails with chmod error when disk under heavy use [bug, feature-copy]"
[#325]: https://github.com/jprichardson/node-fs-extra/issues/325    "ensureDir is difficult to promisify [enhancement]"
[#324]: https://github.com/jprichardson/node-fs-extra/pull/324      "copySync() should apply filter to directories like copy() [bug, feature-copy]"
[#323]: https://github.com/jprichardson/node-fs-extra/issues/323    "Support for `dest` being a directory when using `copy*()`?"
[#322]: https://github.com/jprichardson/node-fs-extra/pull/322      "Add fs-promise as fs-extra-promise alternative"
[#321]: https://github.com/jprichardson/node-fs-extra/issues/321    "fs.copy() with clobber set to false return EEXIST error [feature-copy]"
[#320]: https://github.com/jprichardson/node-fs-extra/issues/320    "fs.copySync: Error: EPERM: operation not permitted, unlink "
[#319]: https://github.com/jprichardson/node-fs-extra/issues/319    "Create directory if not exists"
[#318]: https://github.com/jprichardson/node-fs-extra/issues/318    "Support glob patterns [enhancement, future]"
[#317]: https://github.com/jprichardson/node-fs-extra/pull/317      "Adding copy sync test for src file without write perms"
[#316]: https://github.com/jprichardson/node-fs-extra/pull/316      "Remove move()'s broken limit option [feature-move]"
[#315]: https://github.com/jprichardson/node-fs-extra/pull/315      "Fix move clobber tests to work around graceful-fs bug."
[#314]: https://github.com/jprichardson/node-fs-extra/issues/314    "move() limit option [documentation, enhancement, feature-move]"
[#313]: https://github.com/jprichardson/node-fs-extra/pull/313      "Test that remove() ignores glob characters."
[#312]: https://github.com/jprichardson/node-fs-extra/pull/312      "Enhance walkSync() to return items with path and stats [feature-walk]"
[#311]: https://github.com/jprichardson/node-fs-extra/issues/311    "move() not work when dest name not provided [feature-move]"
[#310]: https://github.com/jprichardson/node-fs-extra/issues/310    "Edit walkSync to return items like what walk emits [documentation, enhancement, feature-walk]"
[#309]: https://github.com/jprichardson/node-fs-extra/issues/309    "moveSync support [enhancement, feature-move]"
[#308]: https://github.com/jprichardson/node-fs-extra/pull/308      "Fix incorrect anchor link"
[#307]: https://github.com/jprichardson/node-fs-extra/pull/307      "Fix coverage"
[#306]: https://github.com/jprichardson/node-fs-extra/pull/306      "Update devDeps, fix lint error"
[#305]: https://github.com/jprichardson/node-fs-extra/pull/305      "Re-add Coveralls"
[#304]: https://github.com/jprichardson/node-fs-extra/pull/304      "Remove path-is-absolute [enhancement]"
[#303]: https://github.com/jprichardson/node-fs-extra/pull/303      "Document copySync filter inconsistency [documentation, feature-copy]"
[#302]: https://github.com/jprichardson/node-fs-extra/pull/302      "fix(console): depreciated -> deprecated"
[#301]: https://github.com/jprichardson/node-fs-extra/pull/301      "Remove chmod call from copySync [feature-copy]"
[#300]: https://github.com/jprichardson/node-fs-extra/pull/300      "Inline Rimraf [enhancement, feature-move, feature-remove]"
[#299]: https://github.com/jprichardson/node-fs-extra/pull/299      "Warn when filter is a RegExp [feature-copy]"
[#298]: https://github.com/jprichardson/node-fs-extra/issues/298    "API Docs [documentation]"
[#297]: https://github.com/jprichardson/node-fs-extra/pull/297      "Warn about using preserveTimestamps on 32-bit node"
[#296]: https://github.com/jprichardson/node-fs-extra/pull/296      "Improve EEXIST error message for copySync [enhancement]"
[#295]: https://github.com/jprichardson/node-fs-extra/pull/295      "Depreciate using regular expressions for copy's filter option [documentation]"
[#294]: https://github.com/jprichardson/node-fs-extra/pull/294      "BREAKING: Refactor lib/copy/ncp.js [feature-copy]"
[#293]: https://github.com/jprichardson/node-fs-extra/pull/293      "Update CI configs"
[#292]: https://github.com/jprichardson/node-fs-extra/issues/292    "Rewrite lib/copy/ncp.js [enhancement, feature-copy]"
[#291]: https://github.com/jprichardson/node-fs-extra/pull/291      "Escape '$' in replacement string for async file copying"
[#290]: https://github.com/jprichardson/node-fs-extra/issues/290    "Exclude files pattern while copying using copy.config.js [question]"
[#289]: https://github.com/jprichardson/node-fs-extra/pull/289      "(Closes #271) lib/util/utimes: properly close file descriptors in the event of an error"
[#288]: https://github.com/jprichardson/node-fs-extra/pull/288      "(Closes #271) lib/util/utimes: properly close file descriptors in the event of an error"
[#287]: https://github.com/jprichardson/node-fs-extra/issues/287    "emptyDir() callback arguments are inconsistent [enhancement, feature-remove]"
[#286]: https://github.com/jprichardson/node-fs-extra/pull/286      "Added walkSync function"
[#285]: https://github.com/jprichardson/node-fs-extra/issues/285    "CITGM test failing on s390"
[#284]: https://github.com/jprichardson/node-fs-extra/issues/284    "outputFile method is missing a check to determine if existing item is a folder or not"
[#283]: https://github.com/jprichardson/node-fs-extra/pull/283      "Apply filter also on directories and symlinks for copySync()"
[#282]: https://github.com/jprichardson/node-fs-extra/pull/282      "Apply filter also on directories and symlinks for copySync()"
[#281]: https://github.com/jprichardson/node-fs-extra/issues/281    "remove function executes 'successfully' but doesn't do anything?"
[#280]: https://github.com/jprichardson/node-fs-extra/pull/280      "Disable rimraf globbing"
[#279]: https://github.com/jprichardson/node-fs-extra/issues/279    "Some code is vendored instead of included [awaiting-reply]"
[#278]: https://github.com/jprichardson/node-fs-extra/issues/278    "copy() does not preserve file/directory ownership"
[#277]: https://github.com/jprichardson/node-fs-extra/pull/277      "Mention defaults for clobber and dereference options"
[#276]: https://github.com/jprichardson/node-fs-extra/issues/276    "Cannot connect to Shared Folder [awaiting-reply]"
[#275]: https://github.com/jprichardson/node-fs-extra/issues/275    "EMFILE, too many open files on Mac OS with JSON API"
[#274]: https://github.com/jprichardson/node-fs-extra/issues/274    "Use with memory-fs? [enhancement, future]"
[#273]: https://github.com/jprichardson/node-fs-extra/pull/273      "tests: rename `remote.test.js` to `remove.test.js`"
[#272]: https://github.com/jprichardson/node-fs-extra/issues/272    "Copy clobber flag never err even when true [bug, feature-copy]"
[#271]: https://github.com/jprichardson/node-fs-extra/issues/271    "Unclosed file handle on futimes error"
[#270]: https://github.com/jprichardson/node-fs-extra/issues/270    "copy not working as desired on Windows [feature-copy, platform-windows]"
[#269]: https://github.com/jprichardson/node-fs-extra/issues/269    "Copying with preserveTimeStamps: true is inaccurate using 32bit node [feature-copy]"
[#268]: https://github.com/jprichardson/node-fs-extra/pull/268      "port fix for mkdirp issue #111"
[#267]: https://github.com/jprichardson/node-fs-extra/issues/267    "WARN deprecated wrench@1.5.9: wrench.js is deprecated!"
[#266]: https://github.com/jprichardson/node-fs-extra/issues/266    "fs-extra"
[#265]: https://github.com/jprichardson/node-fs-extra/issues/265    "Link the `fs.stat fs.exists` etc. methods for replace the `fs` module forever?"
[#264]: https://github.com/jprichardson/node-fs-extra/issues/264    "Renaming a file using move fails when a file inside is open (at least on windows) [wont-fix]"
[#263]: https://github.com/jprichardson/node-fs-extra/issues/263    "ENOSYS: function not implemented, link [needs-confirmed]"
[#262]: https://github.com/jprichardson/node-fs-extra/issues/262    "Add .exists() and .existsSync()"
[#261]: https://github.com/jprichardson/node-fs-extra/issues/261    "Cannot read property 'prototype' of undefined"
[#260]: https://github.com/jprichardson/node-fs-extra/pull/260      "use more specific path for method require"
[#259]: https://github.com/jprichardson/node-fs-extra/issues/259    "Feature Request: isEmpty"
[#258]: https://github.com/jprichardson/node-fs-extra/issues/258    "copy files does not preserve file timestamp"
[#257]: https://github.com/jprichardson/node-fs-extra/issues/257    "Copying a file on windows fails"
[#256]: https://github.com/jprichardson/node-fs-extra/pull/256      "Updated Readme "
[#255]: https://github.com/jprichardson/node-fs-extra/issues/255    "Update rimraf required version"
[#254]: https://github.com/jprichardson/node-fs-extra/issues/254    "request for readTree, readTreeSync, walkSync method"
[#253]: https://github.com/jprichardson/node-fs-extra/issues/253    "outputFile does not touch mtime when file exists"
[#252]: https://github.com/jprichardson/node-fs-extra/pull/252      "Fixing problem when copying file with no write permission"
[#251]: https://github.com/jprichardson/node-fs-extra/issues/251    "Just wanted to say thank you"
[#250]: https://github.com/jprichardson/node-fs-extra/issues/250    "`fs.remove()` not removing files (works with `rm -rf`)"
[#249]: https://github.com/jprichardson/node-fs-extra/issues/249    "Just a Question ... Remove Servers"
[#248]: https://github.com/jprichardson/node-fs-extra/issues/248    "Allow option to not preserve permissions for copy"
[#247]: https://github.com/jprichardson/node-fs-extra/issues/247    "Add TypeScript typing directly in the fs-extra package"
[#246]: https://github.com/jprichardson/node-fs-extra/issues/246    "fse.remove() && fse.removeSync() don't throw error on ENOENT file"
[#245]: https://github.com/jprichardson/node-fs-extra/issues/245    "filter for empty dir [enhancement]"
[#244]: https://github.com/jprichardson/node-fs-extra/issues/244    "copySync doesn't apply the filter to directories"
[#243]: https://github.com/jprichardson/node-fs-extra/issues/243    "Can I request fs.walk() to be synchronous?"
[#242]: https://github.com/jprichardson/node-fs-extra/issues/242    "Accidentally truncates file names ending with $$ [bug, feature-copy]"
[#241]: https://github.com/jprichardson/node-fs-extra/pull/241      "Remove link to createOutputStream"
[#240]: https://github.com/jprichardson/node-fs-extra/issues/240    "walkSync request"
[#239]: https://github.com/jprichardson/node-fs-extra/issues/239    "Depreciate regular expressions for copy's filter [documentation, feature-copy]"
[#238]: https://github.com/jprichardson/node-fs-extra/issues/238    "Can't write to files while in a worker thread."
[#237]: https://github.com/jprichardson/node-fs-extra/issues/237    ".ensureDir(..) fails silently when passed an invalid path..."
[#236]: https://github.com/jprichardson/node-fs-extra/issues/236    "[Removed] Filed under wrong repo"
[#235]: https://github.com/jprichardson/node-fs-extra/pull/235      "Adds symlink dereference option to `fse.copySync` (#191)"
[#234]: https://github.com/jprichardson/node-fs-extra/issues/234    "ensureDirSync fails silent when EACCES: permission denied on travis-ci"
[#233]: https://github.com/jprichardson/node-fs-extra/issues/233    "please make sure the first argument in callback is error object [feature-copy]"
[#232]: https://github.com/jprichardson/node-fs-extra/issues/232    "Copy a folder content  to its child folder.  "
[#231]: https://github.com/jprichardson/node-fs-extra/issues/231    "Adding read/write/output functions for YAML"
[#230]: https://github.com/jprichardson/node-fs-extra/pull/230      "throw error if src and dest are the same to avoid zeroing out + test"
[#229]: https://github.com/jprichardson/node-fs-extra/pull/229      "fix 'TypeError: callback is not a function' in emptyDir"
[#228]: https://github.com/jprichardson/node-fs-extra/pull/228      "Throw error when target is empty so file is not accidentally zeroed out"
[#227]: https://github.com/jprichardson/node-fs-extra/issues/227    "Uncatchable errors when there are invalid arguments [feature-move]"
[#226]: https://github.com/jprichardson/node-fs-extra/issues/226    "Moving to the current directory"
[#225]: https://github.com/jprichardson/node-fs-extra/issues/225    "EBUSY: resource busy or locked, unlink"
[#224]: https://github.com/jprichardson/node-fs-extra/issues/224    "fse.copy ENOENT error"
[#223]: https://github.com/jprichardson/node-fs-extra/issues/223    "Suspicious behavior of fs.existsSync"
[#222]: https://github.com/jprichardson/node-fs-extra/pull/222      "A clearer description of emtpyDir function"
[#221]: https://github.com/jprichardson/node-fs-extra/pull/221      "Update README.md"
[#220]: https://github.com/jprichardson/node-fs-extra/pull/220      "Non-breaking feature: add option 'passStats' to copy methods."
[#219]: https://github.com/jprichardson/node-fs-extra/pull/219      "Add closing parenthesis in copySync example"
[#218]: https://github.com/jprichardson/node-fs-extra/pull/218      "fix #187 #70 options.filter bug"
[#217]: https://github.com/jprichardson/node-fs-extra/pull/217      "fix #187 #70 options.filter bug"
[#216]: https://github.com/jprichardson/node-fs-extra/pull/216      "fix #187 #70 options.filter bug"
[#215]: https://github.com/jprichardson/node-fs-extra/pull/215      "fse.copy throws error when only src and dest provided [bug, documentation, feature-copy]"
[#214]: https://github.com/jprichardson/node-fs-extra/pull/214      "Fixing copySync anchor tag"
[#213]: https://github.com/jprichardson/node-fs-extra/issues/213    "Merge extfs with this repo"
[#212]: https://github.com/jprichardson/node-fs-extra/pull/212      "Update year to 2016 in README.md and LICENSE"
[#211]: https://github.com/jprichardson/node-fs-extra/issues/211    "Not copying all files"
[#210]: https://github.com/jprichardson/node-fs-extra/issues/210    "copy/copySync behave differently when copying a symbolic file [bug, documentation, feature-copy]"
[#209]: https://github.com/jprichardson/node-fs-extra/issues/209    "In Windows invalid directory name causes infinite loop in ensureDir(). [bug]"
[#208]: https://github.com/jprichardson/node-fs-extra/pull/208      "fix options.preserveTimestamps to false in copy-sync by default [feature-copy]"
[#207]: https://github.com/jprichardson/node-fs-extra/issues/207    "Add `compare` suite of functions"
[#206]: https://github.com/jprichardson/node-fs-extra/issues/206    "outputFileSync"
[#205]: https://github.com/jprichardson/node-fs-extra/issues/205    "fix documents about copy/copySync [documentation, feature-copy]"
[#204]: https://github.com/jprichardson/node-fs-extra/pull/204      "allow copy of block and character device files"
[#203]: https://github.com/jprichardson/node-fs-extra/issues/203    "copy method's argument options couldn't be undefined [bug, feature-copy]"
[#202]: https://github.com/jprichardson/node-fs-extra/issues/202    "why there is not a walkSync method?"
[#201]: https://github.com/jprichardson/node-fs-extra/issues/201    "clobber for directories [feature-copy, future]"
[#200]: https://github.com/jprichardson/node-fs-extra/issues/200    "'copySync' doesn't work in sync"
[#199]: https://github.com/jprichardson/node-fs-extra/issues/199    "fs.copySync fails if user does not own file [bug, feature-copy]"
[#198]: https://github.com/jprichardson/node-fs-extra/issues/198    "handle copying between identical files [feature-copy]"
[#197]: https://github.com/jprichardson/node-fs-extra/issues/197    "Missing documentation for `outputFile` `options` 3rd parameter [documentation]"
[#196]: https://github.com/jprichardson/node-fs-extra/issues/196    "copy filter: async function and/or function called with `fs.stat` result [future]"
[#195]: https://github.com/jprichardson/node-fs-extra/issues/195    "How to override with outputFile?"
[#194]: https://github.com/jprichardson/node-fs-extra/pull/194      "allow ensureFile(Sync) to provide data to be written to created file"
[#193]: https://github.com/jprichardson/node-fs-extra/issues/193    "`fs.copy` fails silently if source file is /dev/null [bug, feature-copy]"
[#192]: https://github.com/jprichardson/node-fs-extra/issues/192    "Remove fs.createOutputStream()"
[#191]: https://github.com/jprichardson/node-fs-extra/issues/191    "How to copy symlinks to target as normal folders [feature-copy]"
[#190]: https://github.com/jprichardson/node-fs-extra/pull/190      "copySync to overwrite destination file if readonly and clobber true"
[#189]: https://github.com/jprichardson/node-fs-extra/pull/189      "move.test fix to support CRLF on Windows"
[#188]: https://github.com/jprichardson/node-fs-extra/issues/188    "move.test failing on windows platform"
[#187]: https://github.com/jprichardson/node-fs-extra/issues/187    "Not filter each file, stops on first false [feature-copy]"
[#186]: https://github.com/jprichardson/node-fs-extra/issues/186    "Do you need a .size() function in this module? [future]"
[#185]: https://github.com/jprichardson/node-fs-extra/issues/185    "Doesn't work on NodeJS v4.x"
[#184]: https://github.com/jprichardson/node-fs-extra/issues/184    "CLI equivalent for fs-extra"
[#183]: https://github.com/jprichardson/node-fs-extra/issues/183    "with clobber true, copy and copySync behave differently if destination file is read only [bug, feature-copy]"
[#182]: https://github.com/jprichardson/node-fs-extra/issues/182    "ensureDir(dir, callback) second callback parameter not specified"
[#181]: https://github.com/jprichardson/node-fs-extra/issues/181    "Add ability to remove file securely [enhancement, wont-fix]"
[#180]: https://github.com/jprichardson/node-fs-extra/issues/180    "Filter option doesn't work the same way in copy and copySync [bug, feature-copy]"
[#179]: https://github.com/jprichardson/node-fs-extra/issues/179    "Include opendir"
[#178]: https://github.com/jprichardson/node-fs-extra/issues/178    "ENOTEMPTY is thrown on removeSync "
[#177]: https://github.com/jprichardson/node-fs-extra/issues/177    "fix `remove()` wildcards (introduced by rimraf) [feature-remove]"
[#176]: https://github.com/jprichardson/node-fs-extra/issues/176    "createOutputStream doesn't emit 'end' event"
[#175]: https://github.com/jprichardson/node-fs-extra/issues/175    "[Feature Request].moveSync support [feature-move, future]"
[#174]: https://github.com/jprichardson/node-fs-extra/pull/174      "Fix copy formatting and document options.filter"
[#173]: https://github.com/jprichardson/node-fs-extra/issues/173    "Feature Request: writeJson should mkdirs"
[#172]: https://github.com/jprichardson/node-fs-extra/issues/172    "rename `clobber` flags to `overwrite`"
[#171]: https://github.com/jprichardson/node-fs-extra/issues/171    "remove unnecessary aliases"
[#170]: https://github.com/jprichardson/node-fs-extra/pull/170      "More robust handling of errors moving across virtual drives"
[#169]: https://github.com/jprichardson/node-fs-extra/pull/169      "suppress ensureLink & ensureSymlink dest exists error"
[#168]: https://github.com/jprichardson/node-fs-extra/pull/168      "suppress ensurelink dest exists error"
[#167]: https://github.com/jprichardson/node-fs-extra/pull/167      "Adds basic (string, buffer) support for ensureFile content [future]"
[#166]: https://github.com/jprichardson/node-fs-extra/pull/166      "Adds basic (string, buffer) support for ensureFile content"
[#165]: https://github.com/jprichardson/node-fs-extra/pull/165      "ensure for link & symlink"
[#164]: https://github.com/jprichardson/node-fs-extra/issues/164    "Feature Request: ensureFile to take optional argument for file content"
[#163]: https://github.com/jprichardson/node-fs-extra/issues/163    "ouputJson not formatted out of the box [bug]"
[#162]: https://github.com/jprichardson/node-fs-extra/pull/162      "ensure symlink & link"
[#161]: https://github.com/jprichardson/node-fs-extra/pull/161      "ensure symlink & link"
[#160]: https://github.com/jprichardson/node-fs-extra/pull/160      "ensure symlink & link"
[#159]: https://github.com/jprichardson/node-fs-extra/pull/159      "ensure symlink & link"
[#158]: https://github.com/jprichardson/node-fs-extra/issues/158    "Feature Request: ensureLink and ensureSymlink methods"
[#157]: https://github.com/jprichardson/node-fs-extra/issues/157    "writeJson isn't formatted"
[#156]: https://github.com/jprichardson/node-fs-extra/issues/156    "Promise.promisifyAll doesn't work for some methods"
[#155]: https://github.com/jprichardson/node-fs-extra/issues/155    "Readme"
[#154]: https://github.com/jprichardson/node-fs-extra/issues/154    "/tmp/millis-test-sync"
[#153]: https://github.com/jprichardson/node-fs-extra/pull/153      "Make preserveTimes also work on read-only files. Closes #152"
[#152]: https://github.com/jprichardson/node-fs-extra/issues/152    "fs.copy fails for read-only files with preserveTimestamp=true [feature-copy]"
[#151]: https://github.com/jprichardson/node-fs-extra/issues/151    "TOC does not work correctly on npm [documentation]"
[#150]: https://github.com/jprichardson/node-fs-extra/issues/150    "Remove test file fixtures, create with code."
[#149]: https://github.com/jprichardson/node-fs-extra/issues/149    "/tmp/millis-test-sync"
[#148]: https://github.com/jprichardson/node-fs-extra/issues/148    "split out `Sync` methods in documentation"
[#147]: https://github.com/jprichardson/node-fs-extra/issues/147    "Adding rmdirIfEmpty"
[#146]: https://github.com/jprichardson/node-fs-extra/pull/146      "ensure test.js works"
[#145]: https://github.com/jprichardson/node-fs-extra/issues/145    "Add `fs.exists` and `fs.existsSync` if it doesn't exist."
[#144]: https://github.com/jprichardson/node-fs-extra/issues/144    "tests failing"
[#143]: https://github.com/jprichardson/node-fs-extra/issues/143    "update graceful-fs"
[#142]: https://github.com/jprichardson/node-fs-extra/issues/142    "PrependFile Feature"
[#141]: https://github.com/jprichardson/node-fs-extra/pull/141      "Add option to preserve timestamps"
[#140]: https://github.com/jprichardson/node-fs-extra/issues/140    "Json file reading fails with 'utf8'"
[#139]: https://github.com/jprichardson/node-fs-extra/pull/139      "Preserve file timestamp on copy. Closes #138"
[#138]: https://github.com/jprichardson/node-fs-extra/issues/138    "Preserve timestamps on copying files"
[#137]: https://github.com/jprichardson/node-fs-extra/issues/137    "outputFile/outputJson: Unexpected end of input"
[#136]: https://github.com/jprichardson/node-fs-extra/pull/136      "Update license attribute"
[#135]: https://github.com/jprichardson/node-fs-extra/issues/135    "emptyDir throws Error if no callback is provided"
[#134]: https://github.com/jprichardson/node-fs-extra/pull/134      "Handle EEXIST error when clobbering dir"
[#133]: https://github.com/jprichardson/node-fs-extra/pull/133      "Travis runs with `sudo: false`"
[#132]: https://github.com/jprichardson/node-fs-extra/pull/132      "isDirectory method"
[#131]: https://github.com/jprichardson/node-fs-extra/issues/131    "copySync is not working iojs 1.8.4 on linux [feature-copy]"
[#130]: https://github.com/jprichardson/node-fs-extra/pull/130      "Please review additional features."
[#129]: https://github.com/jprichardson/node-fs-extra/pull/129      "can you review this feature?"
[#128]: https://github.com/jprichardson/node-fs-extra/issues/128    "fsExtra.move(filepath, newPath) broken;"
[#127]: https://github.com/jprichardson/node-fs-extra/issues/127    "consider using fs.access to remove deprecated warnings for fs.exists"
[#126]: https://github.com/jprichardson/node-fs-extra/issues/126    " TypeError: Object #<Object> has no method 'access'"
[#125]: https://github.com/jprichardson/node-fs-extra/issues/125    "Question: What do the *Sync function do different from non-sync"
[#124]: https://github.com/jprichardson/node-fs-extra/issues/124    "move with clobber option 'ENOTEMPTY'"
[#123]: https://github.com/jprichardson/node-fs-extra/issues/123    "Only copy the content of a directory"
[#122]: https://github.com/jprichardson/node-fs-extra/pull/122      "Update section links in README to match current section ids."
[#121]: https://github.com/jprichardson/node-fs-extra/issues/121    "emptyDir is undefined"
[#120]: https://github.com/jprichardson/node-fs-extra/issues/120    "usage bug caused by shallow cloning methods of 'graceful-fs'"
[#119]: https://github.com/jprichardson/node-fs-extra/issues/119    "mkdirs and ensureDir never invoke callback and consume CPU indefinitely if provided a path with invalid characters on Windows"
[#118]: https://github.com/jprichardson/node-fs-extra/pull/118      "createOutputStream"
[#117]: https://github.com/jprichardson/node-fs-extra/pull/117      "Fixed issue with slash separated paths on windows"
[#116]: https://github.com/jprichardson/node-fs-extra/issues/116    "copySync can only copy directories not files [documentation, feature-copy]"
[#115]: https://github.com/jprichardson/node-fs-extra/issues/115    ".Copy & .CopySync [feature-copy]"
[#114]: https://github.com/jprichardson/node-fs-extra/issues/114    "Fails to move (rename) directory to non-empty directory even with clobber: true"
[#113]: https://github.com/jprichardson/node-fs-extra/issues/113    "fs.copy seems to callback early if the destination file already exists"
[#112]: https://github.com/jprichardson/node-fs-extra/pull/112      "Copying a file into an existing directory"
[#111]: https://github.com/jprichardson/node-fs-extra/pull/111      "Moving a file into an existing directory "
[#110]: https://github.com/jprichardson/node-fs-extra/pull/110      "Moving a file into an existing directory"
[#109]: https://github.com/jprichardson/node-fs-extra/issues/109    "fs.move across windows drives fails"
[#108]: https://github.com/jprichardson/node-fs-extra/issues/108    "fse.move directories across multiple devices doesn't work"
[#107]: https://github.com/jprichardson/node-fs-extra/pull/107      "Check if dest path is an existing dir and copy or move source in it"
[#106]: https://github.com/jprichardson/node-fs-extra/issues/106    "fse.copySync crashes while copying across devices D: [feature-copy]"
[#105]: https://github.com/jprichardson/node-fs-extra/issues/105    "fs.copy hangs on iojs"
[#104]: https://github.com/jprichardson/node-fs-extra/issues/104    "fse.move deletes folders [bug]"
[#103]: https://github.com/jprichardson/node-fs-extra/issues/103    "Error: EMFILE with copy"
[#102]: https://github.com/jprichardson/node-fs-extra/issues/102    "touch / touchSync was removed ?"
[#101]: https://github.com/jprichardson/node-fs-extra/issues/101    "fs-extra promisified"
[#100]: https://github.com/jprichardson/node-fs-extra/pull/100      "copy: options object or filter to pass to ncp"
[#99]: https://github.com/jprichardson/node-fs-extra/issues/99      "ensureDir() modes [future]"
[#98]: https://github.com/jprichardson/node-fs-extra/issues/98      "fs.copy() incorrect async behavior [bug]"
[#97]: https://github.com/jprichardson/node-fs-extra/pull/97        "use path.join; fix copySync bug"
[#96]: https://github.com/jprichardson/node-fs-extra/issues/96      "destFolderExists in copySync is always undefined."
[#95]: https://github.com/jprichardson/node-fs-extra/pull/95        "Using graceful-ncp instead of ncp"
[#94]: https://github.com/jprichardson/node-fs-extra/issues/94      "Error: EEXIST, file already exists '../mkdirp/bin/cmd.js' on fs.copySync() [enhancement, feature-copy]"
[#93]: https://github.com/jprichardson/node-fs-extra/issues/93      "Confusing error if drive not mounted [enhancement]"
[#92]: https://github.com/jprichardson/node-fs-extra/issues/92      "Problems with Bluebird"
[#91]: https://github.com/jprichardson/node-fs-extra/issues/91      "fs.copySync('/test', '/haha') is different with 'cp -r /test /haha' [enhancement]"
[#90]: https://github.com/jprichardson/node-fs-extra/issues/90      "Folder creation and file copy is Happening in 64 bit machine but not in 32 bit machine"
[#89]: https://github.com/jprichardson/node-fs-extra/issues/89      "Error: EEXIST using fs-extra's fs.copy to copy a directory on Windows"
[#88]: https://github.com/jprichardson/node-fs-extra/issues/88      "Stacking those libraries"
[#87]: https://github.com/jprichardson/node-fs-extra/issues/87      "createWriteStream + outputFile = ?"
[#86]: https://github.com/jprichardson/node-fs-extra/issues/86      "no moveSync?"
[#85]: https://github.com/jprichardson/node-fs-extra/pull/85        "Copy symlinks in copySync"
[#84]: https://github.com/jprichardson/node-fs-extra/issues/84      "Push latest version to npm ?"
[#83]: https://github.com/jprichardson/node-fs-extra/issues/83      "Prevent copying a directory into itself [feature-copy]"
[#82]: https://github.com/jprichardson/node-fs-extra/pull/82        "README updates for move"
[#81]: https://github.com/jprichardson/node-fs-extra/issues/81      "fd leak after fs.move"
[#80]: https://github.com/jprichardson/node-fs-extra/pull/80        "Preserve file mode in copySync"
[#79]: https://github.com/jprichardson/node-fs-extra/issues/79      "fs.copy only .html file empty"
[#78]: https://github.com/jprichardson/node-fs-extra/pull/78        "copySync was not applying filters to directories"
[#77]: https://github.com/jprichardson/node-fs-extra/issues/77      "Create README reference to bluebird"
[#76]: https://github.com/jprichardson/node-fs-extra/issues/76      "Create README reference to typescript"
[#75]: https://github.com/jprichardson/node-fs-extra/issues/75      "add glob as a dep? [question]"
[#74]: https://github.com/jprichardson/node-fs-extra/pull/74        "including new emptydir module"
[#73]: https://github.com/jprichardson/node-fs-extra/pull/73        "add dependency status in readme"
[#72]: https://github.com/jprichardson/node-fs-extra/pull/72        "Use svg instead of png to get better image quality"
[#71]: https://github.com/jprichardson/node-fs-extra/issues/71      "fse.copy not working on Windows 7 x64 OS, but, copySync does work"
[#70]: https://github.com/jprichardson/node-fs-extra/issues/70      "Not filter each file, stops on first false [bug]"
[#69]: https://github.com/jprichardson/node-fs-extra/issues/69      "How to check if folder exist and read the folder name"
[#68]: https://github.com/jprichardson/node-fs-extra/issues/68      "consider flag to readJsonSync (throw false) [enhancement]"
[#67]: https://github.com/jprichardson/node-fs-extra/issues/67      "docs for readJson incorrectly states that is accepts options"
[#66]: https://github.com/jprichardson/node-fs-extra/issues/66      "ENAMETOOLONG"
[#65]: https://github.com/jprichardson/node-fs-extra/issues/65      "exclude filter in fs.copy"
[#64]: https://github.com/jprichardson/node-fs-extra/issues/64      "Announce: mfs - monitor your fs-extra calls"
[#63]: https://github.com/jprichardson/node-fs-extra/issues/63      "Walk"
[#62]: https://github.com/jprichardson/node-fs-extra/issues/62      "npm install fs-extra doesn't work"
[#61]: https://github.com/jprichardson/node-fs-extra/issues/61      "No longer supports node 0.8 due to use of `^` in package.json dependencies"
[#60]: https://github.com/jprichardson/node-fs-extra/issues/60      "chmod & chown for mkdirs"
[#59]: https://github.com/jprichardson/node-fs-extra/issues/59      "Consider including mkdirp and making fs-extra '--use_strict' safe [question]"
[#58]: https://github.com/jprichardson/node-fs-extra/issues/58      "Stack trace not included in fs.copy error"
[#57]: https://github.com/jprichardson/node-fs-extra/issues/57      "Possible to include wildcards in delete?"
[#56]: https://github.com/jprichardson/node-fs-extra/issues/56      "Crash when have no access to write to destination file in copy "
[#55]: https://github.com/jprichardson/node-fs-extra/issues/55      "Is it possible to have any console output similar to Grunt copy module?"
[#54]: https://github.com/jprichardson/node-fs-extra/issues/54      "`copy` does not preserve file ownership and permissons"
[#53]: https://github.com/jprichardson/node-fs-extra/issues/53      "outputFile() - ability to write data in appending mode"
[#52]: https://github.com/jprichardson/node-fs-extra/pull/52        "This fixes (what I think) is a bug in copySync"
[#51]: https://github.com/jprichardson/node-fs-extra/pull/51        "Add a Bitdeli Badge to README"
[#50]: https://github.com/jprichardson/node-fs-extra/issues/50      "Replace mechanism in createFile"
[#49]: https://github.com/jprichardson/node-fs-extra/pull/49        "update rimraf to v2.2.6"
[#48]: https://github.com/jprichardson/node-fs-extra/issues/48      "fs.copy issue [bug]"
[#47]: https://github.com/jprichardson/node-fs-extra/issues/47      "Bug in copy - callback called on readStream 'close' - Fixed in ncp 0.5.0"
[#46]: https://github.com/jprichardson/node-fs-extra/pull/46        "update copyright year"
[#45]: https://github.com/jprichardson/node-fs-extra/pull/45        "Added note about fse.outputFile() being the one that overwrites"
[#44]: https://github.com/jprichardson/node-fs-extra/pull/44        "Proposal: Stream support"
[#43]: https://github.com/jprichardson/node-fs-extra/issues/43      "Better error reporting "
[#42]: https://github.com/jprichardson/node-fs-extra/issues/42      "Performance issue?"
[#41]: https://github.com/jprichardson/node-fs-extra/pull/41        "There does seem to be a synchronous version now"
[#40]: https://github.com/jprichardson/node-fs-extra/issues/40      "fs.copy throw unexplained error ENOENT, utime "
[#39]: https://github.com/jprichardson/node-fs-extra/pull/39        "Added regression test for copy() return callback on error"
[#38]: https://github.com/jprichardson/node-fs-extra/pull/38        "Return err in copy() fstat cb, because stat could be undefined or null"
[#37]: https://github.com/jprichardson/node-fs-extra/issues/37      "Maybe include a line reader? [enhancement, question]"
[#36]: https://github.com/jprichardson/node-fs-extra/pull/36        "`filter` parameter `fs.copy` and `fs.copySync`"
[#35]: https://github.com/jprichardson/node-fs-extra/pull/35        "`filter` parameter `fs.copy` and `fs.copySync` "
[#34]: https://github.com/jprichardson/node-fs-extra/issues/34      "update docs to include options for JSON methods [enhancement]"
[#33]: https://github.com/jprichardson/node-fs-extra/pull/33        "fs_extra.copySync"
[#32]: https://github.com/jprichardson/node-fs-extra/issues/32      "update to latest jsonfile [enhancement]"
[#31]: https://github.com/jprichardson/node-fs-extra/issues/31      "Add ensure methods [enhancement]"
[#30]: https://github.com/jprichardson/node-fs-extra/issues/30      "update package.json optional dep `graceful-fs`"
[#29]: https://github.com/jprichardson/node-fs-extra/issues/29      "Copy failing if dest directory doesn't exist. Is this intended?"
[#28]: https://github.com/jprichardson/node-fs-extra/issues/28      "homepage field must be a string url. Deleted."
[#27]: https://github.com/jprichardson/node-fs-extra/issues/27      "Update Readme"
[#26]: https://github.com/jprichardson/node-fs-extra/issues/26      "Add readdir recursive method. [enhancement]"
[#25]: https://github.com/jprichardson/node-fs-extra/pull/25        "adding an `.npmignore` file"
[#24]: https://github.com/jprichardson/node-fs-extra/issues/24      "[bug] cannot run in strict mode [bug]"
[#23]: https://github.com/jprichardson/node-fs-extra/issues/23      "`writeJSON()` should create parent directories"
[#22]: https://github.com/jprichardson/node-fs-extra/pull/22        "Add a limit option to mkdirs()"
[#21]: https://github.com/jprichardson/node-fs-extra/issues/21      "touch() in 0.10.0"
[#20]: https://github.com/jprichardson/node-fs-extra/issues/20      "fs.remove yields callback before directory is really deleted"
[#19]: https://github.com/jprichardson/node-fs-extra/issues/19      "fs.copy err is empty array"
[#18]: https://github.com/jprichardson/node-fs-extra/pull/18        "Exposed copyFile Function"
[#17]: https://github.com/jprichardson/node-fs-extra/issues/17      "Use `require('graceful-fs')` if found instead of `require('fs')`"
[#16]: https://github.com/jprichardson/node-fs-extra/pull/16        "Update README.md"
[#15]: https://github.com/jprichardson/node-fs-extra/issues/15      "Implement cp -r but sync aka copySync. [enhancement]"
[#14]: https://github.com/jprichardson/node-fs-extra/issues/14      "fs.mkdirSync is broken in 0.3.1"
[#13]: https://github.com/jprichardson/node-fs-extra/issues/13      "Thoughts on including a directory tree / file watcher? [enhancement, question]"
[#12]: https://github.com/jprichardson/node-fs-extra/issues/12      "copyFile & copyFileSync are global"
[#11]: https://github.com/jprichardson/node-fs-extra/issues/11      "Thoughts on including a file walker? [enhancement, question]"
[#10]: https://github.com/jprichardson/node-fs-extra/issues/10      "move / moveFile API [enhancement]"
[#9]: https://github.com/jprichardson/node-fs-extra/issues/9        "don't import normal fs stuff into fs-extra"
[#8]: https://github.com/jprichardson/node-fs-extra/pull/8          "Update rimraf to latest version"
[#6]: https://github.com/jprichardson/node-fs-extra/issues/6        "Remove CoffeeScript development dependency"
[#5]: https://github.com/jprichardson/node-fs-extra/issues/5        "comments on naming"
[#4]: https://github.com/jprichardson/node-fs-extra/issues/4        "version bump to 0.2"
[#3]: https://github.com/jprichardson/node-fs-extra/pull/3          "Hi! I fixed some code for you!"
[#2]: https://github.com/jprichardson/node-fs-extra/issues/2        "Merge with fs.extra and mkdirp"
[#1]: https://github.com/jprichardson/node-fs-extra/issues/1        "file-extra npm !exist"


---

Node.js: fs-extra
=================

`fs-extra` adds file system methods that aren't included in the native `fs` module and adds promise support to the `fs` methods. It also uses [`graceful-fs`](https://github.com/isaacs/node-graceful-fs) to prevent `EMFILE` errors. It should be a drop in replacement for `fs`.

[![npm Package](https://img.shields.io/npm/v/fs-extra.svg)](https://www.npmjs.org/package/fs-extra)
[![License](https://img.shields.io/npm/l/express.svg)](https://github.com/jprichardson/node-fs-extra/blob/master/LICENSE)
[![build status](https://img.shields.io/travis/jprichardson/node-fs-extra/master.svg)](http://travis-ci.org/jprichardson/node-fs-extra)
[![windows Build status](https://img.shields.io/appveyor/ci/jprichardson/node-fs-extra/master.svg?label=windows%20build)](https://ci.appveyor.com/project/jprichardson/node-fs-extra/branch/master)
[![downloads per month](http://img.shields.io/npm/dm/fs-extra.svg)](https://www.npmjs.org/package/fs-extra)
[![Coverage Status](https://img.shields.io/coveralls/github/jprichardson/node-fs-extra/master.svg)](https://coveralls.io/github/jprichardson/node-fs-extra)
[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)

Why?
----

I got tired of including `mkdirp`, `rimraf`, and `ncp` in most of my projects.




Installation
------------

    npm install fs-extra



Usage
-----

`fs-extra` is a drop in replacement for native `fs`. All methods in `fs` are attached to `fs-extra`. All `fs` methods return promises if the callback isn't passed.

You don't ever need to include the original `fs` module again:

```js
const fs = require('fs') // this is no longer necessary
```

you can now do this:

```js
const fs = require('fs-extra')
```

or if you prefer to make it clear that you're using `fs-extra` and not `fs`, you may want
to name your `fs` variable `fse` like so:

```js
const fse = require('fs-extra')
```

you can also keep both, but it's redundant:

```js
const fs = require('fs')
const fse = require('fs-extra')
```

Sync vs Async vs Async/Await
-------------
Most methods are async by default. All async methods will return a promise if the callback isn't passed.

Sync methods on the other hand will throw if an error occurs.

Also Async/Await will throw an error if one occurs.

Example:

```js
const fs = require('fs-extra')

// Async with promises:
fs.copy('/tmp/myfile', '/tmp/mynewfile')
  .then(() => console.log('success!'))
  .catch(err => console.error(err))

// Async with callbacks:
fs.copy('/tmp/myfile', '/tmp/mynewfile', err => {
  if (err) return console.error(err)
  console.log('success!')
})

// Sync:
try {
  fs.copySync('/tmp/myfile', '/tmp/mynewfile')
  console.log('success!')
} catch (err) {
  console.error(err)
}

// Async/Await:
async function copyFiles () {
  try {
    await fs.copy('/tmp/myfile', '/tmp/mynewfile')
    console.log('success!')
  } catch (err) {
    console.error(err)
  }
}

copyFiles()
```


Methods
-------

### Async

- [copy](docs/copy.md)
- [emptyDir](docs/emptyDir.md)
- [ensureFile](docs/ensureFile.md)
- [ensureDir](docs/ensureDir.md)
- [ensureLink](docs/ensureLink.md)
- [ensureSymlink](docs/ensureSymlink.md)
- [mkdirp](docs/ensureDir.md)
- [mkdirs](docs/ensureDir.md)
- [move](docs/move.md)
- [outputFile](docs/outputFile.md)
- [outputJson](docs/outputJson.md)
- [pathExists](docs/pathExists.md)
- [readJson](docs/readJson.md)
- [remove](docs/remove.md)
- [writeJson](docs/writeJson.md)

### Sync

- [copySync](docs/copy-sync.md)
- [emptyDirSync](docs/emptyDir-sync.md)
- [ensureFileSync](docs/ensureFile-sync.md)
- [ensureDirSync](docs/ensureDir-sync.md)
- [ensureLinkSync](docs/ensureLink-sync.md)
- [ensureSymlinkSync](docs/ensureSymlink-sync.md)
- [mkdirpSync](docs/ensureDir-sync.md)
- [mkdirsSync](docs/ensureDir-sync.md)
- [moveSync](docs/move-sync.md)
- [outputFileSync](docs/outputFile-sync.md)
- [outputJsonSync](docs/outputJson-sync.md)
- [pathExistsSync](docs/pathExists-sync.md)
- [readJsonSync](docs/readJson-sync.md)
- [removeSync](docs/remove-sync.md)
- [writeJsonSync](docs/writeJson-sync.md)


**NOTE:** You can still use the native Node.js methods. They are promisified and copied over to `fs-extra`. See [notes on `fs.read()`, `fs.write()`, & `fs.writev()`](docs/fs-read-write-writev.md)

### What happened to `walk()` and `walkSync()`?

They were removed from `fs-extra` in v2.0.0. If you need the functionality, `walk` and `walkSync` are available as separate packages, [`klaw`](https://github.com/jprichardson/node-klaw) and [`klaw-sync`](https://github.com/manidlou/node-klaw-sync).


Third Party
-----------

### CLI

[fse-cli](https://www.npmjs.com/package/@atao60/fse-cli) allows you to run `fs-extra` from a console or from [npm](https://www.npmjs.com) scripts.

### TypeScript

If you like TypeScript, you can use `fs-extra` with it: https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/fs-extra


### File / Directory Watching

If you want to watch for changes to files or directories, then you should use [chokidar](https://github.com/paulmillr/chokidar).

### Obtain Filesystem (Devices, Partitions) Information

[fs-filesystem](https://github.com/arthurintelligence/node-fs-filesystem) allows you to read the state of the filesystem of the host on which it is run. It returns information about both the devices and the partitions (volumes) of the system.

### Misc.

- [fs-extra-debug](https://github.com/jdxcode/fs-extra-debug) - Send your fs-extra calls to [debug](https://npmjs.org/package/debug).
- [mfs](https://github.com/cadorn/mfs) - Monitor your fs-extra calls.



Hacking on fs-extra
-------------------

Wanna hack on `fs-extra`? Great! Your help is needed! [fs-extra is one of the most depended upon Node.js packages](http://nodei.co/npm/fs-extra.png?downloads=true&downloadRank=true&stars=true). This project
uses [JavaScript Standard Style](https://github.com/feross/standard) - if the name or style choices bother you,
you're gonna have to get over it :) If `standard` is good enough for `npm`, it's good enough for `fs-extra`.

[![js-standard-style](https://cdn.rawgit.com/feross/standard/master/badge.svg)](https://github.com/feross/standard)

What's needed?
- First, take a look at existing issues. Those are probably going to be where the priority lies.
- More tests for edge cases. Specifically on different platforms. There can never be enough tests.
- Improve test coverage. See coveralls output for more info.

Note: If you make any big changes, **you should definitely file an issue for discussion first.**

### Running the Test Suite

fs-extra contains hundreds of tests.

- `npm run lint`: runs the linter ([standard](http://standardjs.com/))
- `npm run unit`: runs the unit tests
- `npm test`: runs both the linter and the tests


### Windows

If you run the tests on the Windows and receive a lot of symbolic link `EPERM` permission errors, it's
because on Windows you need elevated privilege to create symbolic links. You can add this to your Windows's
account by following the instructions here: http://superuser.com/questions/104845/permission-to-make-symbolic-links-in-windows-7
However, I didn't have much luck doing this.

Since I develop on Mac OS X, I use VMWare Fusion for Windows testing. I create a shared folder that I map to a drive on Windows.
I open the `Node.js command prompt` and run as `Administrator`. I then map the network drive running the following command:

    net use z: "\\vmware-host\Shared Folders"

I can then navigate to my `fs-extra` directory and run the tests.


Naming
------

I put a lot of thought into the naming of these functions. Inspired by @coolaj86's request. So he deserves much of the credit for raising the issue. See discussion(s) here:

* https://github.com/jprichardson/node-fs-extra/issues/2
* https://github.com/flatiron/utile/issues/11
* https://github.com/ryanmcgrath/wrench-js/issues/29
* https://github.com/substack/node-mkdirp/issues/17

First, I believe that in as many cases as possible, the [Node.js naming schemes](http://nodejs.org/api/fs.html) should be chosen. However, there are problems with the Node.js own naming schemes.

For example, `fs.readFile()` and `fs.readdir()`: the **F** is capitalized in *File* and the **d** is not capitalized in *dir*. Perhaps a bit pedantic, but they should still be consistent. Also, Node.js has chosen a lot of POSIX naming schemes, which I believe is great. See: `fs.mkdir()`, `fs.rmdir()`, `fs.chown()`, etc.

We have a dilemma though. How do you consistently name methods that perform the following POSIX commands: `cp`, `cp -r`, `mkdir -p`, and `rm -rf`?

My perspective: when in doubt, err on the side of simplicity. A directory is just a hierarchical grouping of directories and files. Consider that for a moment. So when you want to copy it or remove it, in most cases you'll want to copy or remove all of its contents. When you want to create a directory, if the directory that it's suppose to be contained in does not exist, then in most cases you'll want to create that too.

So, if you want to remove a file or a directory regardless of whether it has contents, just call `fs.remove(path)`. If you want to copy a file or a directory whether it has contents, just call `fs.copy(source, destination)`. If you want to create a directory regardless of whether its parent directories exist, just call `fs.mkdirs(path)` or `fs.mkdirp(path)`.


Credit
------

`fs-extra` wouldn't be possible without using the modules from the following authors:

- [Isaac Shlueter](https://github.com/isaacs)
- [Charlie McConnel](https://github.com/avianflu)
- [James Halliday](https://github.com/substack)
- [Andrew Kelley](https://github.com/andrewrk)




License
-------

Licensed under MIT

Copyright (c) 2011-2017 [JP Richardson](https://github.com/jprichardson)

[1]: http://nodejs.org/docs/latest/api/fs.html


[jsonfile]: https://github.com/jprichardson/node-jsonfile


---

# Changelog

All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.

## [2.7.0](https://github.com/webpack/schema-utils/compare/v2.6.6...v2.7.0) (2020-05-29)


### Features

* improve hints ([a36e535](https://github.com/webpack/schema-utils/commit/a36e535faca1b01e27c3bfa3c8bee9227c3f836c))
* smart not case ([#101](https://github.com/webpack/schema-utils/issues/101)) ([698d8b0](https://github.com/webpack/schema-utils/commit/698d8b05462d86aadb217e25a45c7b953a79a52e))


### Bug Fixes

* move @types/json-schema from devDependencies to dependencies ([#97](https://github.com/webpack/schema-utils/issues/97)) ([#98](https://github.com/webpack/schema-utils/issues/98)) ([945e67d](https://github.com/webpack/schema-utils/commit/945e67db5e19baf7ec7df72813b0739dd56f950d))

### [2.6.6](https://github.com/webpack/schema-utils/compare/v2.6.5...v2.6.6) (2020-04-17)


### Bug Fixes

* improve perf

### [2.6.5](https://github.com/webpack/schema-utils/compare/v2.6.4...v2.6.5) (2020-03-11)


### Bug Fixes

* correct dots at end of sentence ([7284beb](https://github.com/webpack/schema-utils/commit/7284bebe00cd570f1bef2c15951a07b9794038e6))

### [2.6.4](https://github.com/webpack/schema-utils/compare/v2.6.3...v2.6.4) (2020-01-17)


### Bug Fixes

* change `initialised` to `initialized` ([#87](https://github.com/webpack/schema-utils/issues/87)) ([70f12d3](https://github.com/webpack/schema-utils/commit/70f12d33a8eaa27249bc9c1a27f886724cf91ea7))

### [2.6.3](https://github.com/webpack/schema-utils/compare/v2.6.2...v2.6.3) (2020-01-17)


### Bug Fixes

* prefer the `baseDataPath` option from arguments ([#86](https://github.com/webpack/schema-utils/issues/86)) ([e236859](https://github.com/webpack/schema-utils/commit/e236859e85b28e35e1294f86fc1ff596a5031cea))

### [2.6.2](https://github.com/webpack/schema-utils/compare/v2.6.1...v2.6.2) (2020-01-14)


### Bug Fixes

* better handle Windows absolute paths ([#85](https://github.com/webpack/schema-utils/issues/85)) ([1fa2930](https://github.com/webpack/schema-utils/commit/1fa2930a161e907b9fc53a7233d605910afdb883))

### [2.6.1](https://github.com/webpack/schema-utils/compare/v2.6.0...v2.6.1) (2019-11-28)


### Bug Fixes

* typescript declarations ([#84](https://github.com/webpack/schema-utils/issues/84)) ([89d55a9](https://github.com/webpack/schema-utils/commit/89d55a9a8edfa6a8ac8b112f226bb3154e260319))

## [2.6.0](https://github.com/webpack/schema-utils/compare/v2.5.0...v2.6.0) (2019-11-27)


### Features

* support configuration via title ([#81](https://github.com/webpack/schema-utils/issues/81)) ([afddc10](https://github.com/webpack/schema-utils/commit/afddc109f6891cd37a9f1835d50862d119a072bf))


### Bug Fixes

* typescript definitions ([#70](https://github.com/webpack/schema-utils/issues/70)) ([f38158d](https://github.com/webpack/schema-utils/commit/f38158d6d040e2c701622778ae8122fb26a4f990))

## [2.5.0](https://github.com/webpack/schema-utils/compare/v2.4.1...v2.5.0) (2019-10-15)


### Bug Fixes

* rework format for maxLength, minLength ([#67](https://github.com/webpack/schema-utils/issues/67)) ([0d12259](https://github.com/webpack/schema-utils/commit/0d12259))
* support all cases with one number in range ([#64](https://github.com/webpack/schema-utils/issues/64)) ([7fc8069](https://github.com/webpack/schema-utils/commit/7fc8069))
* typescript definition and export naming ([#69](https://github.com/webpack/schema-utils/issues/69)) ([a435b79](https://github.com/webpack/schema-utils/commit/a435b79))


### Features

* "smart" numbers range ([62fb107](https://github.com/webpack/schema-utils/commit/62fb107))

### [2.4.1](https://github.com/webpack/schema-utils/compare/v2.4.0...v2.4.1) (2019-09-27)


### Bug Fixes

* publish definitions ([#58](https://github.com/webpack/schema-utils/issues/58)) ([1885faa](https://github.com/webpack/schema-utils/commit/1885faa))

## [2.4.0](https://github.com/webpack/schema-utils/compare/v2.3.0...v2.4.0) (2019-09-26)


### Features

* better errors when the `type` keyword doesn't exist ([0988be2](https://github.com/webpack/schema-utils/commit/0988be2))
* support $data reference ([#56](https://github.com/webpack/schema-utils/issues/56)) ([d2f11d6](https://github.com/webpack/schema-utils/commit/d2f11d6))
* types definitions ([#52](https://github.com/webpack/schema-utils/issues/52)) ([facb431](https://github.com/webpack/schema-utils/commit/facb431))

## [2.3.0](https://github.com/webpack/schema-utils/compare/v2.2.0...v2.3.0) (2019-09-26)


### Features

* support `not` keyword ([#53](https://github.com/webpack/schema-utils/issues/53)) ([765f458](https://github.com/webpack/schema-utils/commit/765f458))

## [2.2.0](https://github.com/webpack/schema-utils/compare/v2.1.0...v2.2.0) (2019-09-02)


### Features

* better error output for `oneOf` and `anyOf` ([#48](https://github.com/webpack/schema-utils/issues/48)) ([#50](https://github.com/webpack/schema-utils/issues/50)) ([332242f](https://github.com/webpack/schema-utils/commit/332242f))

## [2.1.0](https://github.com/webpack-contrib/schema-utils/compare/v2.0.1...v2.1.0) (2019-08-07)


### Bug Fixes

* throw error on sparse arrays ([#47](https://github.com/webpack-contrib/schema-utils/issues/47)) ([b85ac38](https://github.com/webpack-contrib/schema-utils/commit/b85ac38))


### Features

* export `ValidateError` ([#46](https://github.com/webpack-contrib/schema-utils/issues/46)) ([ff781d7](https://github.com/webpack-contrib/schema-utils/commit/ff781d7))



### [2.0.1](https://github.com/webpack-contrib/schema-utils/compare/v2.0.0...v2.0.1) (2019-07-18)


### Bug Fixes

* error message for empty object ([#44](https://github.com/webpack-contrib/schema-utils/issues/44)) ([0b4b4a2](https://github.com/webpack-contrib/schema-utils/commit/0b4b4a2))



### [2.0.0](https://github.com/webpack-contrib/schema-utils/compare/v1.0.0...v2.0.0) (2019-07-17)


### BREAKING CHANGES

* drop support for Node.js < 8.9.0
* drop support `errorMessage`, please use `description` for links.
* api was changed, please look documentation.
* error messages was fully rewritten.


<a name="1.0.0"></a>
# [1.0.0](https://github.com/webpack-contrib/schema-utils/compare/v0.4.7...v1.0.0) (2018-08-07)


### Features

* **src:** add support for custom error messages ([#33](https://github.com/webpack-contrib/schema-utils/issues/33)) ([1cbe4ef](https://github.com/webpack-contrib/schema-utils/commit/1cbe4ef))



<a name="0.4.7"></a>
## [0.4.7](https://github.com/webpack-contrib/schema-utils/compare/v0.4.6...v0.4.7) (2018-08-07)


### Bug Fixes

* **src:** `node >= v4.0.0` support ([#32](https://github.com/webpack-contrib/schema-utils/issues/32)) ([cb13dd4](https://github.com/webpack-contrib/schema-utils/commit/cb13dd4))



<a name="0.4.6"></a>
## [0.4.6](https://github.com/webpack-contrib/schema-utils/compare/v0.4.5...v0.4.6) (2018-08-06)


### Bug Fixes

* **package:** remove lockfile ([#28](https://github.com/webpack-contrib/schema-utils/issues/28)) ([69f1a81](https://github.com/webpack-contrib/schema-utils/commit/69f1a81))
* **package:** remove unnecessary `webpack` dependency ([#26](https://github.com/webpack-contrib/schema-utils/issues/26)) ([532eaa5](https://github.com/webpack-contrib/schema-utils/commit/532eaa5))



<a name="0.4.5"></a>
## [0.4.5](https://github.com/webpack-contrib/schema-utils/compare/v0.4.4...v0.4.5) (2018-02-13)


### Bug Fixes

* **CHANGELOG:** update broken links ([4483b9f](https://github.com/webpack-contrib/schema-utils/commit/4483b9f))
* **package:** update broken links ([f2494ba](https://github.com/webpack-contrib/schema-utils/commit/f2494ba))



<a name="0.4.4"></a>
## [0.4.4](https://github.com/webpack-contrib/schema-utils/compare/v0.4.3...v0.4.4) (2018-02-13)


### Bug Fixes

* **package:** update `dependencies` ([#22](https://github.com/webpack-contrib/schema-utils/issues/22)) ([3aecac6](https://github.com/webpack-contrib/schema-utils/commit/3aecac6))



<a name="0.4.3"></a>
## [0.4.3](https://github.com/webpack-contrib/schema-utils/compare/v0.4.2...v0.4.3) (2017-12-14)


### Bug Fixes

* **validateOptions:** throw `err` instead of `process.exit(1)` ([#17](https://github.com/webpack-contrib/schema-utils/issues/17)) ([c595eda](https://github.com/webpack-contrib/schema-utils/commit/c595eda))
* **ValidationError:** never return `this` in the ctor ([#16](https://github.com/webpack-contrib/schema-utils/issues/16)) ([c723791](https://github.com/webpack-contrib/schema-utils/commit/c723791))



<a name="0.4.2"></a>
## [0.4.2](https://github.com/webpack-contrib/schema-utils/compare/v0.4.1...v0.4.2) (2017-11-09)


### Bug Fixes

* **validateOptions:** catch `ValidationError` and handle it internally ([#15](https://github.com/webpack-contrib/schema-utils/issues/15)) ([9c5ef5e](https://github.com/webpack-contrib/schema-utils/commit/9c5ef5e))



<a name="0.4.1"></a>
## [0.4.1](https://github.com/webpack-contrib/schema-utils/compare/v0.4.0...v0.4.1) (2017-11-03)


### Bug Fixes

* **ValidationError:** use `Error.captureStackTrace` for `err.stack` handling ([#14](https://github.com/webpack-contrib/schema-utils/issues/14)) ([a6fb974](https://github.com/webpack-contrib/schema-utils/commit/a6fb974))



<a name="0.4.0"></a>
# [0.4.0](https://github.com/webpack-contrib/schema-utils/compare/v0.3.0...v0.4.0) (2017-10-28)


### Features

* add support for `typeof`, `instanceof` (`{Function\|RegExp}`) ([#10](https://github.com/webpack-contrib/schema-utils/issues/10)) ([9f01816](https://github.com/webpack-contrib/schema-utils/commit/9f01816))



<a name="0.3.0"></a>
# [0.3.0](https://github.com/webpack-contrib/schema-utils/compare/v0.2.1...v0.3.0) (2017-04-29)


### Features

* add ValidationError ([#8](https://github.com/webpack-contrib/schema-utils/issues/8)) ([d48f0fb](https://github.com/webpack-contrib/schema-utils/commit/d48f0fb))



<a name="0.2.1"></a>
## [0.2.1](https://github.com/webpack-contrib/schema-utils/compare/v0.2.0...v0.2.1) (2017-03-13)


### Bug Fixes

* Include .babelrc to `files` ([28f0363](https://github.com/webpack-contrib/schema-utils/commit/28f0363))
* Include source to `files` ([43b0f2f](https://github.com/webpack-contrib/schema-utils/commit/43b0f2f))



<a name="0.2.0"></a>
# [0.2.0](https://github.com/webpack-contrib/schema-utils/compare/v0.1.0...v0.2.0) (2017-03-12)

<a name="0.1.0"></a>
# 0.1.0 (2017-03-07)


### Features

* **validations:** add validateOptions module ([ae9b47b](https://github.com/webpack-contrib/schema-utils/commit/ae9b47b))



# Change Log

All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.


---

<div align="center">
  <a href="http://json-schema.org">
    <img width="160" height="160"
      src="https://raw.githubusercontent.com/webpack-contrib/schema-utils/master/.github/assets/logo.png">
  </a>
  <a href="https://github.com/webpack/webpack">
    <img width="200" height="200"
      src="https://webpack.js.org/assets/icon-square-big.svg">
  </a>
</div>

[![npm][npm]][npm-url]
[![node][node]][node-url]
[![deps][deps]][deps-url]
[![tests][tests]][tests-url]
[![coverage][cover]][cover-url]
[![chat][chat]][chat-url]
[![size][size]][size-url]

# schema-utils

Package for validate options in loaders and plugins.

## Getting Started

To begin, you'll need to install `schema-utils`:

```console
npm install schema-utils
```

## API

**schema.json**

```json
{
  "type": "object",
  "properties": {
    "option": {
      "type": ["boolean"]
    }
  },
  "additionalProperties": false
}
```

```js
import schema from './path/to/schema.json';
import validate from 'schema-utils';

const options = { option: true };
const configuration = { name: 'Loader Name/Plugin Name/Name' };

validate(schema, options, configuration);
```

### `schema`

Type: `String`

JSON schema.

Simple example of schema:

```json
{
  "type": "object",
  "properties": {
    "name": {
      "description": "This is description of option.",
      "type": "string"
    }
  },
  "additionalProperties": false
}
```

### `options`

Type: `Object`

Object with options.

```js
validate(
  schema,
  {
    name: 123,
  },
  { name: 'MyPlugin' }
);
```

### `configuration`

Allow to configure validator.

There is an alternative method to configure the `name` and`baseDataPath` options via the `title` property in the schema.
For example:

```json
{
  "title": "My Loader options",
  "type": "object",
  "properties": {
    "name": {
      "description": "This is description of option.",
      "type": "string"
    }
  },
  "additionalProperties": false
}
```

The last word used for the `baseDataPath` option, other words used for the `name` option.
Based on the example above the `name` option equals `My Loader`, the `baseDataPath` option equals `options`.

#### `name`

Type: `Object`
Default: `"Object"`

Allow to setup name in validation errors.

```js
validate(schema, options, { name: 'MyPlugin' });
```

```shell
Invalid configuration object. MyPlugin has been initialised using a configuration object that does not match the API schema.
 - configuration.optionName should be a integer.
```

#### `baseDataPath`

Type: `String`
Default: `"configuration"`

Allow to setup base data path in validation errors.

```js
validate(schema, options, { name: 'MyPlugin', baseDataPath: 'options' });
```

```shell
Invalid options object. MyPlugin has been initialised using an options object that does not match the API schema.
 - options.optionName should be a integer.
```

#### `postFormatter`

Type: `Function`
Default: `undefined`

Allow to reformat errors.

```js
validate(schema, options, {
  name: 'MyPlugin',
  postFormatter: (formattedError, error) => {
    if (error.keyword === 'type') {
      return `${formattedError}\nAdditional Information.`;
    }

    return formattedError;
  },
});
```

```shell
Invalid options object. MyPlugin has been initialized using an options object that does not match the API schema.
 - options.optionName should be a integer.
   Additional Information.
```

## Examples

**schema.json**

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "test": {
      "anyOf": [
        { "type": "array" },
        { "type": "string" },
        { "instanceof": "RegExp" }
      ]
    },
    "transform": {
      "instanceof": "Function"
    },
    "sourceMap": {
      "type": "boolean"
    }
  },
  "additionalProperties": false
}
```

### `Loader`

```js
import { getOptions } from 'loader-utils';
import validateOptions from 'schema-utils';

import schema from 'path/to/schema.json';

function loader(src, map) {
  const options = getOptions(this) || {};

  validateOptions(schema, options, {
    name: 'Loader Name',
    baseDataPath: 'options',
  });

  // Code...
}

export default loader;
```

### `Plugin`

```js
import validateOptions from 'schema-utils';

import schema from 'path/to/schema.json';

class Plugin {
  constructor(options) {
    validateOptions(schema, options, {
      name: 'Plugin Name',
      baseDataPath: 'options',
    });

    this.options = options;
  }

  apply(compiler) {
    // Code...
  }
}

export default Plugin;
```

## Contributing

Please take a moment to read our contributing guidelines if you haven't yet done so.

[CONTRIBUTING](./.github/CONTRIBUTING.md)

## License

[MIT](./LICENSE)

[npm]: https://img.shields.io/npm/v/schema-utils.svg
[npm-url]: https://npmjs.com/package/schema-utils
[node]: https://img.shields.io/node/v/schema-utils.svg
[node-url]: https://nodejs.org
[deps]: https://david-dm.org/webpack/schema-utils.svg
[deps-url]: https://david-dm.org/webpack/schema-utils
[tests]: https://github.com/webpack/schema-utils/workflows/schema-utils/badge.svg
[tests-url]: https://github.com/webpack/schema-utils/actions
[cover]: https://codecov.io/gh/webpack/schema-utils/branch/master/graph/badge.svg
[cover-url]: https://codecov.io/gh/webpack/schema-utils
[chat]: https://badges.gitter.im/webpack/webpack.svg
[chat-url]: https://gitter.im/webpack/webpack
[size]: https://packagephobia.now.sh/badge?p=schema-utils
[size-url]: https://packagephobia.now.sh/result?p=schema-utils


---

# Tapable

The tapable package expose many Hook classes, which can be used to create hooks for plugins.

``` javascript
const {
	SyncHook,
	SyncBailHook,
	SyncWaterfallHook,
	SyncLoopHook,
	AsyncParallelHook,
	AsyncParallelBailHook,
	AsyncSeriesHook,
	AsyncSeriesBailHook,
	AsyncSeriesWaterfallHook
 } = require("tapable");
```

## Installation

``` shell
npm install --save tapable
```

## Usage

All Hook constructors take one optional argument, which is a list of argument names as strings.

``` js
const hook = new SyncHook(["arg1", "arg2", "arg3"]);
```

The best practice is to expose all hooks of a class in a `hooks` property:

``` js
class Car {
	constructor() {
		this.hooks = {
			accelerate: new SyncHook(["newSpeed"]),
			brake: new SyncHook(),
			calculateRoutes: new AsyncParallelHook(["source", "target", "routesList"])
		};
	}

	/* ... */
}
```

Other people can now use these hooks:

``` js
const myCar = new Car();

// Use the tap method to add a consument
myCar.hooks.brake.tap("WarningLampPlugin", () => warningLamp.on());
```

It's required to pass a name to identify the plugin/reason.

You may receive arguments:

``` js
myCar.hooks.accelerate.tap("LoggerPlugin", newSpeed => console.log(`Accelerating to ${newSpeed}`));
```

For sync hooks, `tap` is the only valid method to add a plugin. Async hooks also support async plugins:

``` js
myCar.hooks.calculateRoutes.tapPromise("GoogleMapsPlugin", (source, target, routesList) => {
	// return a promise
	return google.maps.findRoute(source, target).then(route => {
		routesList.add(route);
	});
});
myCar.hooks.calculateRoutes.tapAsync("BingMapsPlugin", (source, target, routesList, callback) => {
	bing.findRoute(source, target, (err, route) => {
		if(err) return callback(err);
		routesList.add(route);
		// call the callback
		callback();
	});
});

// You can still use sync plugins
myCar.hooks.calculateRoutes.tap("CachedRoutesPlugin", (source, target, routesList) => {
	const cachedRoute = cache.get(source, target);
	if(cachedRoute)
		routesList.add(cachedRoute);
})
```

The class declaring these hooks need to call them:

``` js
class Car {
	/* ... */

	setSpeed(newSpeed) {
		this.hooks.accelerate.call(newSpeed);
	}

	useNavigationSystemPromise(source, target) {
		const routesList = new List();
		return this.hooks.calculateRoutes.promise(source, target, routesList).then(() => {
			return routesList.getRoutes();
		});
	}

	useNavigationSystemAsync(source, target, callback) {
		const routesList = new List();
		this.hooks.calculateRoutes.callAsync(source, target, routesList, err => {
			if(err) return callback(err);
			callback(null, routesList.getRoutes());
		});
	}
}
```

The Hook will compile a method with the most efficient way of running your plugins. It generates code depending on:
* The number of registered plugins (none, one, many)
* The kind of registered plugins (sync, async, promise)
* The used call method (sync, async, promise)
* The number of arguments
* Whether interception is used

This ensures fastest possible execution.

## Hook types

Each hook can be tapped with one or several functions. How they are executed depends on the hook type:

* Basic hook (without “Waterfall”, “Bail” or “Loop” in its name). This hook simply calls every function it tapped in a row.

* __Waterfall__. A waterfall hook also calls each tapped function in a row. Unlike the basic hook, it passes a return value from each function to the next function.

* __Bail__. A bail hook allows exiting early. When any of the tapped function returns anything, the bail hook will stop executing the remaining ones.

* __Loop__. TODO

Additionally, hooks can be synchronous or asynchronous. To reflect this, there’re “Sync”, “AsyncSeries”, and “AsyncParallel” hook classes:

* __Sync__. A sync hook can only be tapped with synchronous functions (using `myHook.tap()`).

* __AsyncSeries__. An async-series hook can be tapped with synchronous, callback-based and promise-based functions (using `myHook.tap()`, `myHook.tapAsync()` and `myHook.tapPromise()`). They call each async method in a row.

* __AsyncParallel__. An async-parallel hook can also be tapped with synchronous, callback-based and promise-based functions (using `myHook.tap()`, `myHook.tapAsync()` and `myHook.tapPromise()`). However, they run each async method in parallel.

The hook type is reflected in its class name. E.g., `AsyncSeriesWaterfallHook` allows asynchronous functions and runs them in series, passing each function’s return value into the next function.


## Interception

All Hooks offer an additional interception API:

``` js
myCar.hooks.calculateRoutes.intercept({
	call: (source, target, routesList) => {
		console.log("Starting to calculate routes");
	},
	register: (tapInfo) => {
		// tapInfo = { type: "promise", name: "GoogleMapsPlugin", fn: ... }
		console.log(`${tapInfo.name} is doing its job`);
		return tapInfo; // may return a new tapInfo object
	}
})
```

**call**: `(...args) => void` Adding `call` to your interceptor will trigger when hooks are triggered. You have access to the hooks arguments.

**tap**: `(tap: Tap) => void` Adding `tap` to your interceptor will trigger when a plugin taps into a hook. Provided is the `Tap` object. `Tap` object can't be changed.

**loop**: `(...args) => void` Adding `loop` to your interceptor will trigger for each loop of a looping hook.

**register**: `(tap: Tap) => Tap | undefined` Adding `register` to your interceptor will trigger for each added `Tap` and allows to modify it.

## Context

Plugins and interceptors can opt-in to access an optional `context` object, which can be used to pass arbitrary values to subsequent plugins and interceptors.

``` js
myCar.hooks.accelerate.intercept({
	context: true,
	tap: (context, tapInfo) => {
		// tapInfo = { type: "sync", name: "NoisePlugin", fn: ... }
		console.log(`${tapInfo.name} is doing it's job`);

		// `context` starts as an empty object if at least one plugin uses `context: true`.
		// If no plugins use `context: true`, then `context` is undefined.
		if (context) {
			// Arbitrary properties can be added to `context`, which plugins can then access.
			context.hasMuffler = true;
		}
	}
});

myCar.hooks.accelerate.tap({
	name: "NoisePlugin",
	context: true
}, (context, newSpeed) => {
	if (context && context.hasMuffler) {
		console.log("Silence...");
	} else {
		console.log("Vroom!");
	}
});
```

## HookMap

A HookMap is a helper class for a Map with Hooks

``` js
const keyedHook = new HookMap(key => new SyncHook(["arg"]))
```

``` js
keyedHook.tap("some-key", "MyPlugin", (arg) => { /* ... */ });
keyedHook.tapAsync("some-key", "MyPlugin", (arg, callback) => { /* ... */ });
keyedHook.tapPromise("some-key", "MyPlugin", (arg) => { /* ... */ });
```

``` js
const hook = keyedHook.get("some-key");
if(hook !== undefined) {
	hook.callAsync("arg", err => { /* ... */ });
}
```

## Hook/HookMap interface

Public:

``` ts
interface Hook {
	tap: (name: string | Tap, fn: (context?, ...args) => Result) => void,
	tapAsync: (name: string | Tap, fn: (context?, ...args, callback: (err, result: Result) => void) => void) => void,
	tapPromise: (name: string | Tap, fn: (context?, ...args) => Promise<Result>) => void,
	intercept: (interceptor: HookInterceptor) => void
}

interface HookInterceptor {
	call: (context?, ...args) => void,
	loop: (context?, ...args) => void,
	tap: (context?, tap: Tap) => void,
	register: (tap: Tap) => Tap,
	context: boolean
}

interface HookMap {
	for: (key: any) => Hook,
	tap: (key: any, name: string | Tap, fn: (context?, ...args) => Result) => void,
	tapAsync: (key: any, name: string | Tap, fn: (context?, ...args, callback: (err, result: Result) => void) => void) => void,
	tapPromise: (key: any, name: string | Tap, fn: (context?, ...args) => Promise<Result>) => void,
	intercept: (interceptor: HookMapInterceptor) => void
}

interface HookMapInterceptor {
	factory: (key: any, hook: Hook) => Hook
}

interface Tap {
	name: string,
	type: string
	fn: Function,
	stage: number,
	context: boolean
}
```

Protected (only for the class containing the hook):

``` ts
interface Hook {
	isUsed: () => boolean,
	call: (...args) => Result,
	promise: (...args) => Promise<Result>,
	callAsync: (...args, callback: (err, result: Result) => void) => void,
}

interface HookMap {
	get: (key: any) => Hook | undefined,
	for: (key: any) => Hook
}
```

## MultiHook

A helper Hook-like class to redirect taps to multiple other hooks:

``` js
const { MultiHook } = require("tapable");

this.hooks.allHooks = new MultiHook([this.hooks.hookA, this.hooks.hookB]);
```


---

# Form-Data [![NPM Module](https://img.shields.io/npm/v/form-data.svg)](https://www.npmjs.com/package/form-data) [![Join the chat at https://gitter.im/form-data/form-data](http://form-data.github.io/images/gitterbadge.svg)](https://gitter.im/form-data/form-data)

A library to create readable ```"multipart/form-data"``` streams. Can be used to submit forms and file uploads to other web applications.

The API of this library is inspired by the [XMLHttpRequest-2 FormData Interface][xhr2-fd].

[xhr2-fd]: http://dev.w3.org/2006/webapi/XMLHttpRequest-2/Overview.html#the-formdata-interface

[![Linux Build](https://img.shields.io/travis/form-data/form-data/master.svg?label=linux:6.x-12.x)](https://travis-ci.org/form-data/form-data)
[![MacOS Build](https://img.shields.io/travis/form-data/form-data/master.svg?label=macos:6.x-12.x)](https://travis-ci.org/form-data/form-data)
[![Windows Build](https://img.shields.io/travis/form-data/form-data/master.svg?label=windows:6.x-12.x)](https://travis-ci.org/form-data/form-data)

[![Coverage Status](https://img.shields.io/coveralls/form-data/form-data/master.svg?label=code+coverage)](https://coveralls.io/github/form-data/form-data?branch=master)
[![Dependency Status](https://img.shields.io/david/form-data/form-data.svg)](https://david-dm.org/form-data/form-data)

## Install

```
npm install --save form-data
```

## Usage

In this example we are constructing a form with 3 fields that contain a string,
a buffer and a file stream.

``` javascript
var FormData = require('form-data');
var fs = require('fs');

var form = new FormData();
form.append('my_field', 'my value');
form.append('my_buffer', new Buffer(10));
form.append('my_file', fs.createReadStream('/foo/bar.jpg'));
```

Also you can use http-response stream:

``` javascript
var FormData = require('form-data');
var http = require('http');

var form = new FormData();

http.request('http://nodejs.org/images/logo.png', function(response) {
  form.append('my_field', 'my value');
  form.append('my_buffer', new Buffer(10));
  form.append('my_logo', response);
});
```

Or @mikeal's [request](https://github.com/request/request) stream:

``` javascript
var FormData = require('form-data');
var request = require('request');

var form = new FormData();

form.append('my_field', 'my value');
form.append('my_buffer', new Buffer(10));
form.append('my_logo', request('http://nodejs.org/images/logo.png'));
```

In order to submit this form to a web application, call ```submit(url, [callback])``` method:

``` javascript
form.submit('http://example.org/', function(err, res) {
  // res – response object (http.IncomingMessage)  //
  res.resume();
});

```

For more advanced request manipulations ```submit()``` method returns ```http.ClientRequest``` object, or you can choose from one of the alternative submission methods.

### Custom options

You can provide custom options, such as `maxDataSize`:

``` javascript
var FormData = require('form-data');

var form = new FormData({ maxDataSize: 20971520 });
form.append('my_field', 'my value');
form.append('my_buffer', /* something big */);
```

List of available options could be found in [combined-stream](https://github.com/felixge/node-combined-stream/blob/master/lib/combined_stream.js#L7-L15)

### Alternative submission methods

You can use node's http client interface:

``` javascript
var http = require('http');

var request = http.request({
  method: 'post',
  host: 'example.org',
  path: '/upload',
  headers: form.getHeaders()
});

form.pipe(request);

request.on('response', function(res) {
  console.log(res.statusCode);
});
```

Or if you would prefer the `'Content-Length'` header to be set for you:

``` javascript
form.submit('example.org/upload', function(err, res) {
  console.log(res.statusCode);
});
```

To use custom headers and pre-known length in parts:

``` javascript
var CRLF = '\r\n';
var form = new FormData();

var options = {
  header: CRLF + '--' + form.getBoundary() + CRLF + 'X-Custom-Header: 123' + CRLF + CRLF,
  knownLength: 1
};

form.append('my_buffer', buffer, options);

form.submit('http://example.com/', function(err, res) {
  if (err) throw err;
  console.log('Done');
});
```

Form-Data can recognize and fetch all the required information from common types of streams (```fs.readStream```, ```http.response``` and ```mikeal's request```), for some other types of streams you'd need to provide "file"-related information manually:

``` javascript
someModule.stream(function(err, stdout, stderr) {
  if (err) throw err;

  var form = new FormData();

  form.append('file', stdout, {
    filename: 'unicycle.jpg', // ... or:
    filepath: 'photos/toys/unicycle.jpg',
    contentType: 'image/jpeg',
    knownLength: 19806
  });

  form.submit('http://example.com/', function(err, res) {
    if (err) throw err;
    console.log('Done');
  });
});
```

The `filepath` property overrides `filename` and may contain a relative path. This is typically used when uploading [multiple files from a directory](https://wicg.github.io/entries-api/#dom-htmlinputelement-webkitdirectory).

For edge cases, like POST request to URL with query string or to pass HTTP auth credentials, object can be passed to `form.submit()` as first parameter:

``` javascript
form.submit({
  host: 'example.com',
  path: '/probably.php?extra=params',
  auth: 'username:password'
}, function(err, res) {
  console.log(res.statusCode);
});
```

In case you need to also send custom HTTP headers with the POST request, you can use the `headers` key in first parameter of `form.submit()`:

``` javascript
form.submit({
  host: 'example.com',
  path: '/surelynot.php',
  headers: {'x-test-header': 'test-header-value'}
}, function(err, res) {
  console.log(res.statusCode);
});
```

### Methods

- [_Void_ append( **String** _field_, **Mixed** _value_ [, **Mixed** _options_] )](https://github.com/form-data/form-data#void-append-string-field-mixed-value--mixed-options-).
- [_Headers_ getHeaders( [**Headers** _userHeaders_] )](https://github.com/form-data/form-data#array-getheaders-array-userheaders-)
- [_String_ getBoundary()](https://github.com/form-data/form-data#string-getboundary)
- [_Void_ setBoundary()](https://github.com/form-data/form-data#void-setboundary)
- [_Buffer_ getBuffer()](https://github.com/form-data/form-data#buffer-getbuffer)
- [_Integer_ getLengthSync()](https://github.com/form-data/form-data#integer-getlengthsync)
- [_Integer_ getLength( **function** _callback_ )](https://github.com/form-data/form-data#integer-getlength-function-callback-)
- [_Boolean_ hasKnownLength()](https://github.com/form-data/form-data#boolean-hasknownlength)
- [_Request_ submit( _params_, **function** _callback_ )](https://github.com/form-data/form-data#request-submit-params-function-callback-)
- [_String_ toString()](https://github.com/form-data/form-data#string-tostring)

#### _Void_ append( **String** _field_, **Mixed** _value_ [, **Mixed** _options_] )
Append data to the form. You can submit about any format (string, integer, boolean, buffer, etc.). However, Arrays are not supported and need to be turned into strings by the user.
```javascript
var form = new FormData();
form.append( 'my_string', 'my value' );
form.append( 'my_integer', 1 );
form.append( 'my_boolean', true );
form.append( 'my_buffer', new Buffer(10) );
form.append( 'my_array_as_json', JSON.stringify( ['bird','cute'] ) )
```

You may provide a string for options, or an object.
```javascript
// Set filename by providing a string for options
form.append( 'my_file', fs.createReadStream('/foo/bar.jpg'), 'bar.jpg' );

// provide an object.
form.append( 'my_file', fs.createReadStream('/foo/bar.jpg'), {filename: 'bar.jpg', contentType: 'image/jpeg', knownLength: 19806} );
```

#### _Headers_ getHeaders( [**Headers** _userHeaders_] )
This method adds the correct `content-type` header to the provided array of `userHeaders`.

#### _String_ getBoundary()
Return the boundary of the formData. By default, the boundary consists of 26 `-` followed by 24 numbers
for example:
```javascript
--------------------------515890814546601021194782
```

#### _Void_ setBoundary(String _boundary_)
Set the boundary string, overriding the default behavior described above.

_Note: The boundary must be unique and may not appear in the data._

#### _Buffer_ getBuffer()
Return the full formdata request package, as a Buffer. You can insert this Buffer in e.g. Axios to send multipart data.
```javascript
var form = new FormData();
form.append( 'my_buffer', Buffer.from([0x4a,0x42,0x20,0x52,0x6f,0x63,0x6b,0x73]) );
form.append( 'my_file', fs.readFileSync('/foo/bar.jpg') );

axios.post( 'https://example.com/path/to/api',
            form.getBuffer(),
            form.getHeaders()
          )
```
**Note:** Because the output is of type Buffer, you can only append types that are accepted by Buffer: *string, Buffer, ArrayBuffer, Array, or Array-like Object*. A ReadStream for example will result in an error.

#### _Integer_ getLengthSync()
Same as `getLength` but synchronous.

_Note: getLengthSync __doesn't__ calculate streams length._

#### _Integer_ getLength( **function** _callback_ )
Returns the `Content-Length` async. The callback is used to handle errors and continue once the length has been calculated
```javascript
this.getLength(function(err, length) {
  if (err) {
    this._error(err);
    return;
  }

  // add content length
  request.setHeader('Content-Length', length);

  ...
}.bind(this));
```

#### _Boolean_ hasKnownLength()
Checks if the length of added values is known.

#### _Request_ submit( _params_, **function** _callback_ )
Submit the form to a web application.
```javascript
var form = new FormData();
form.append( 'my_string', 'Hello World' );

form.submit( 'http://example.com/', function(err, res) {
  // res – response object (http.IncomingMessage)  //
  res.resume();
} );
```

#### _String_ toString()
Returns the form data as a string. Don't use this if you are sending files or buffers, use `getBuffer()` instead.

### Integration with other libraries

#### Request

Form submission using  [request](https://github.com/request/request):

```javascript
var formData = {
  my_field: 'my_value',
  my_file: fs.createReadStream(__dirname + '/unicycle.jpg'),
};

request.post({url:'http://service.com/upload', formData: formData}, function(err, httpResponse, body) {
  if (err) {
    return console.error('upload failed:', err);
  }
  console.log('Upload successful!  Server responded with:', body);
});
```

For more details see [request readme](https://github.com/request/request#multipartform-data-multipart-form-uploads).

#### node-fetch

You can also submit a form using [node-fetch](https://github.com/bitinn/node-fetch):

```javascript
var form = new FormData();

form.append('a', 1);

fetch('http://example.com', { method: 'POST', body: form })
    .then(function(res) {
        return res.json();
    }).then(function(json) {
        console.log(json);
    });
```

#### axios

In Node.js you can post a file using [axios](https://github.com/axios/axios):
```javascript
const form = new FormData();
const stream = fs.createReadStream(PATH_TO_FILE);

form.append('image', stream);

// In Node.js environment you need to set boundary in the header field 'Content-Type' by calling method `getHeaders`
const formHeaders = form.getHeaders();

axios.post('http://example.com', form, {
  headers: {
    ...formHeaders,
  },
})
.then(response => response)
.catch(error => error)
```

## Notes

- ```getLengthSync()``` method DOESN'T calculate length for streams, use ```knownLength``` options as workaround.
- ```getLength(cb)``` will send an error as first parameter of callback if stream length cannot be calculated (e.g. send in custom streams w/o using ```knownLength```).
- ```submit``` will not add `content-length` if form length is unknown or not calculable.
- Starting version `2.x` FormData has dropped support for `node@0.10.x`.
- Starting version `3.x` FormData has dropped support for `node@4.x`.

## License

Form-Data is released under the [MIT](License) license.


---

# form-data-encoder

Encode `FormData` content into the `multipart/form-data` format

[![Code Coverage](https://codecov.io/github/octet-stream/form-data-encoder/coverage.svg?branch=master)](https://codecov.io/github/octet-stream/form-data-encoder?branch=master)
[![CI](https://github.com/octet-stream/form-data-encoder/workflows/CI/badge.svg)](https://github.com/octet-stream/form-data-encoder/actions/workflows/ci.yml)
[![ESLint](https://github.com/octet-stream/form-data-encoder/workflows/ESLint/badge.svg)](https://github.com/octet-stream/form-data-encoder/actions/workflows/eslint.yml)

## Requirements

- Node.js v14.17 or higher;
- Runtime should support `TextEncoder`, `TextDecoder`, `WeakMap`, `WeakSet` and async generator functions;
- For TypeScript users: tsc v4.3 or higher.

## Installation

You can install this package using npm:

```sh
npm install form-data-encoder
```

Or yarn:

```sh
yarn add form-data-encoder
```

Or pnpm:

```sh
pnpm add form-data-encoder
```

## Usage

1. To start the encoding process, you need to create a new Encoder instance with the FormData you want to encode:

```js
import {Readable} from "stream"

import {FormData, File} from "formdata-node"
import {FormDataEncoder} from "form-data-encoder"

import fetch from "node-fetch"

const form = new FormData()

form.set("greeting", "Hello, World!")
form.set("file", new File(["On Soviet Moon landscape see binoculars through YOU"], "file.txt"))

const encoder = new FormDataEncoder(form)

const options = {
  method: "post",

  // Set request headers provided by the Encoder.
  // The `headers` property has `Content-Type` and `Content-Length` headers.
  headers: encoder.headers,

  // Create a Readable stream from the Encoder.
  // You can omit usage of `Readable.from` for HTTP clients whose support async iterables in request body.
  // The Encoder will yield FormData content portions encoded into the multipart/form-data format as node-fetch consumes the stream.
  body: Readable.from(encoder.encode()) // or just Readable.from(encoder)
}

const response = await fetch("https://httpbin.org/post", options)

console.log(await response.json())
```

2. Encoder support different spec-compatible FormData implementations. Let's try it with [`formdata-polyfill`](https://github.com/jimmywarting/FormData):

```js
import {Readable} from "stream"

import {FormDataEncoder} from "form-data-encoder"
import {FormData} from "formdata-polyfill/esm-min.js"
import {File} from "fetch-blob" // v3

const form = new FormData()

form.set("field", "Some value")
form.set("file", new File(["File content goes here"], "file.txt"))

const encoder = new FormDataEncoder(form)

const options = {
  method: "post",
  headers: encoder.headers,
  body: Readable.from(encoder)
}

await fetch("https://httpbin.org/post", options)
```

3. Because the Encoder is iterable (it has both Symbol.asyncIterator and Symbol.iterator methods), you can use it with different targets. Let's say you want to convert FormData content into `Blob`, for that you can write a function like this:

```js
import {Readable} from "stream"

import {FormDataEncoder} from "form-data-encoder"

import {FormData, File, Blob, fileFromPath} from "formdata-node"

import fetch from "node-fetch"

const form = new FormData()

form.set("field", "Just a random string")
form.set("file", new File(["Using files is class amazing"], "file.txt"))
form.set("fileFromPath", await fileFromPath("path/to/a/file.txt"))

// Note 1: When using with native Blob or fetch-blob@2 you might also need to generate boundary string for your FormDataEncoder instance
// because Blob will lowercase value of the `type` option and default boundary generator produces a string with both lower and upper cased alphabetical characters. Math.random() should be enough to fix this:
// const encoder = new FormDataEncoder(form, String(Math.random()))
const encoder = new FormDataEncoder(form)

const options = {
  method: "post",

  // Note 2: To use this approach with fetch-blob@2 you probably gonna need to convert the encoder parts output to an array first:
  // new Blob([...encoder], {type: encoder.contentType})
  body: new Blob(encoder, {type: encoder.contentType})
}

const response = await fetch("https://httpbin.org/post", options)

console.log(await response.json())
```

4. Here's FormData to Blob conversion with async-iterator approach:

```js
import {FormData} from "formdata-polyfill/esm-min.js"
import {blobFrom} from "fetch-blob/from.js"
import {FormDataEncoder} from "form-data-encoder"

import Blob from "fetch-blob"
import fetch from "node-fetch"

// This approach may require much more RAM compared to the previous one, but it works too.
async function toBlob(form) {
  const encoder = new Encoder(form)
  const chunks = []

  for await (const chunk of encoder) {
    chunks.push(chunk)
  }

  return new Blob(chunks, {type: encoder.contentType})
}

const form = new FormData()

form.set("name", "John Doe")
form.set("avatar", await blobFrom("path/to/an/avatar.png"), "avatar.png")

const options = {
  method: "post",
  body: await toBlob(form)
}

await fetch("https://httpbin.org/post", options)
```

5. Another way to convert FormData parts to blob using `form-data-encoder` is making a Blob-ish class:

```js
import {Readable} from "stream"

import {FormDataEncoder} from "form-data-encoder"
import {FormData} from "formdata-polyfill/esm-min.js"
import {blobFrom} from "fetch-blob/from.js"

import Blob from "fetch-blob"
import fetch from "node-fetch"

class BlobDataItem {
  constructor(encoder) {
    this.#encoder = encoder
    this.#size = encoder.headers["Content-Length"]
    this.#type = encoder.headers["Content-Type"]
  }

  get type() {
    return this.#type
  }

  get size() {
    return this.#size
  }

  stream() {
    return Readable.from(this.#encoder)
  }

  get [Symbol.toStringTag]() {
    return "Blob"
  }
}

const form = new FormData()

form.set("name", "John Doe")
form.set("avatar", await blobFrom("path/to/an/avatar.png"), "avatar.png")

const encoder = new FormDataEncoder(form)

// Note that node-fetch@2 performs more strictness tests for Blob objects, so you may need to do extra steps before you set up request body (like, maybe you'll need to instaniate a Blob with BlobDataItem as one of its blobPart)
const blob = new BlobDataItem(enocoder) // or new Blob([new BlobDataItem(enocoder)], {type: encoder.contentType})

const options = {
  method: "post",
  body: blob
}

await fetch("https://httpbin.org/post", options)
```

6. In this example we will pull FormData content into the ReadableStream:

```js
 // This module is only necessary when you targeting Node.js or need web streams that implement Symbol.asyncIterator
import {ReadableStream} from "web-streams-polyfill/ponyfill/es2018"

import {FormDataEncoder} from "form-data-encoder"
import {FormData} from "formdata-node"

import fetch from "node-fetch"

function toReadableStream(encoder) {
  const iterator = encoder.encode()

  return new ReadableStream({
    async pull(controller) {
      const {value, done} = await iterator.next()

      if (done) {
        return controller.close()
      }

      controller.enqueue(value)
    }
  })
}

const form = new FormData()

form.set("field", "My hovercraft is full of eels")

const encoder = new FormDataEncoder(form)

const options = {
  method: "post",
  headers: encoder.headers,
  body: toReadableStream(encoder)
}

// Note that this example requires `fetch` to support Symbol.asyncIterator, which node-fetch lacks of (but will support eventually)
await fetch("https://httpbin.org/post", options)
```

7. Speaking of async iterables - if HTTP client supports them, you can use encoder like this:

```js
import {FormDataEncoder} from "form-data-encoder"
import {FormData} from "formdata-node"

import fetch from "node-fetch"

const form = new FormData()

form.set("field", "My hovercraft is full of eels")

const encoder = new FormDataEncoder(form)

const options = {
  method: "post",
  headers: encoder.headers,
  body: encoder
}

await fetch("https://httpbin.org/post", options)
```

8. ...And for those client whose supporting form-data-encoder out of the box, the usage will be much, much more simpler:

```js
import {FormData} from "formdata-node" // Or any other spec-compatible implementation

import fetch from "node-fetch"

const form = new FormData()

form.set("field", "My hovercraft is full of eels")

const options = {
  method: "post",
  body: form
}

// Note that node-fetch does NOT support form-data-encoder
await fetch("https://httpbin.org/post", options)
```

## API

### `class FormDataEncoder`

##### `constructor(form[, boundary, options]) -> {FormDataEncoder}`

  - **{FormDataLike}** form - FormData object to encode. This object must be a spec-compatible FormData implementation.
  - **{string}** [boundary] - An optional boundary string that will be used by the encoder. If there's no boundary string is present, FormDataEncoder will generate it automatically.
  - **{object}** [options] - FormDataEncoder options.
  - **{boolean}** [options.enableAdditionalHeaders = false] - When enabled, the encoder will emit additional per part headers, such as `Content-Length`. Please note that the web clients do not include these, so when enabled this option might cause an error if `multipart/form-data` does not consider additional headers.

Creates a `multipart/form-data` encoder.

#### Instance properties

##### `boundary -> {string}`

Returns boundary string.

##### `contentType -> {string}`

Returns Content-Type header.

##### `contentLength -> {string}`

Return Content-Length header.

##### `headers -> {object}`

Returns headers object with Content-Type and Content-Length header.

#### Instance methods

##### `values() -> {Generator<Uint8Array | FileLike, void, undefined>}`

Creates an iterator allowing to go through form-data parts (with metadata).
This method **will not** read the files.

##### `encode() -> {AsyncGenerator<Uint8Array, void, undefined>}`

Creates an async iterator allowing to perform the encoding by portions.
This method **will** also read files.

##### `[Symbol.iterator]() -> {Generator<Uint8Array | FileLike, void, undefined>}`

An alias for `Encoder#values()` method.

##### `[Symbol.asyncIterator]() -> {AsyncGenerator<Uint8Array, void, undefined>}`

An alias for `Encoder#encode()` method.

### `isFile(value) -> {boolean}`

Check if a value is File-ish object.

  - **{unknown}** value - a value to test

### `isFormData(value) -> {boolean}`

Check if a value is FormData-ish object.

  - **{unknown}** value - a value to test


---

format
======

printf, sprintf, and vsprintf for JavaScript


Installation
============

npm install format

The code works in browsers as well, you can copy these functions into your project
or otherwise include them with your other JavaScript.

Usage
=====

    var format = require('format')
      , printf = format.printf
      , vsprintf = format.vsprintf
      // or if you want to keep it old school
      , sprintf = format

    // Print 'hello world'
    printf('%s world', 'hello')

    var what = 'life, the universe, and everything'
    format('%d is the answer to %s', 42, what)
    // => '42 is the answer to life, the universe, and everything'

    vsprintf('%d is the answer to %s', [42, what])
    // => '42 is the answer to life, the universe, and everything'

Supported format specifiers: b, c, d, f, o, s, x, and X.

See `man 3 printf` or `man 1 printf` for details.

Precision is supported for floating point numbers.

License
=======

Copyright 2010 - 2014 Sami Samhuri sami@samhuri.net

[MIT license](http://sjs.mit-license.org)



---

0.2.0 / 2021-05-31
==================

  * Use `req.socket` over deprecated `req.connection`

0.1.2 / 2017-09-14
==================

  * perf: improve header parsing
  * perf: reduce overhead when no `X-Forwarded-For` header

0.1.1 / 2017-09-10
==================

  * Fix trimming leading / trailing OWS
  * perf: hoist regular expression

0.1.0 / 2014-09-21
==================

  * Initial release


---

# forwarded

[![NPM Version][npm-image]][npm-url]
[![NPM Downloads][downloads-image]][downloads-url]
[![Node.js Version][node-version-image]][node-version-url]
[![Build Status][ci-image]][ci-url]
[![Test Coverage][coveralls-image]][coveralls-url]

Parse HTTP X-Forwarded-For header

## Installation

This is a [Node.js](https://nodejs.org/en/) module available through the
[npm registry](https://www.npmjs.com/). Installation is done using the
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):

```sh
$ npm install forwarded
```

## API

```js
var forwarded = require('forwarded')
```

### forwarded(req)

```js
var addresses = forwarded(req)
```

Parse the `X-Forwarded-For` header from the request. Returns an array
of the addresses, including the socket address for the `req`, in reverse
order (i.e. index `0` is the socket address and the last index is the
furthest address, typically the end-user).

## Testing

```sh
$ npm test
```

## License

[MIT](LICENSE)

[ci-image]: https://badgen.net/github/checks/jshttp/forwarded/master?label=ci
[ci-url]: https://github.com/jshttp/forwarded/actions?query=workflow%3Aci
[npm-image]: https://img.shields.io/npm/v/forwarded.svg
[npm-url]: https://npmjs.org/package/forwarded
[node-version-image]: https://img.shields.io/node/v/forwarded.svg
[node-version-url]: https://nodejs.org/en/download/
[coveralls-image]: https://img.shields.io/coveralls/jshttp/forwarded/master.svg
[coveralls-url]: https://coveralls.io/r/jshttp/forwarded?branch=master
[downloads-image]: https://img.shields.io/npm/dm/forwarded.svg
[downloads-url]: https://npmjs.org/package/forwarded


---

# Fraction.js - ℚ in JavaScript

[![NPM Package](https://img.shields.io/npm/v/fraction.js.svg?style=flat)](https://npmjs.org/package/fraction.js "View this project on npm")
[![MIT license](http://img.shields.io/badge/license-MIT-brightgreen.svg)](http://opensource.org/licenses/MIT)


Tired of inprecise numbers represented by doubles, which have to store rational and irrational numbers like PI or sqrt(2) the same way? Obviously the following problem is preventable:

```javascript
1 / 98 * 98 // = 0.9999999999999999
```

If you need more precision or just want a fraction as a result, just include *Fraction.js*:

```javascript
var Fraction = require('fraction.js');
// or
import Fraction from 'fraction.js';
```

and give it a trial:

```javascript
Fraction(1).div(98).mul(98) // = 1
```

Internally, numbers are represented as *numerator / denominator*, which adds just a little overhead. However, the library is written with performance and accuracy in mind, which makes it the perfect basis for [Polynomial.js](https://github.com/infusion/Polynomial.js) and [Math.js](https://github.com/josdejong/mathjs).

Convert decimal to fraction
===
The simplest job for fraction.js is to get a fraction out of a decimal:
```javascript
var x = new Fraction(1.88);
var res = x.toFraction(true); // String "1 22/25"
```

Examples / Motivation
===
A simple example might be

```javascript
var f = new Fraction("9.4'31'"); // 9.4313131313131...
f.mul([-4, 3]).mod("4.'8'"); // 4.88888888888888...
```
The result is

```javascript
console.log(f.toFraction()); // -4154 / 1485
```
You could of course also access the sign (s), numerator (n) and denominator (d) on your own:
```javascript
f.s * f.n / f.d = -1 * 4154 / 1485 = -2.797306...
```

If you would try to calculate it yourself, you would come up with something like:

```javascript
(9.4313131 * (-4 / 3)) % 4.888888 = -2.797308133...
```

Quite okay, but yea - not as accurate as it could be.


Laplace Probability
===
Simple example. What's the probability of throwing a 3, and 1 or 4, and 2 or 4 or 6 with a fair dice?

P({3}):
```javascript
var p = new Fraction([3].length, 6).toString(); // 0.1(6)
```

P({1, 4}):
```javascript
var p = new Fraction([1, 4].length, 6).toString(); // 0.(3)
```

P({2, 4, 6}):
```javascript
var p = new Fraction([2, 4, 6].length, 6).toString(); // 0.5
```

Convert degrees/minutes/seconds to precise rational representation:
===

57+45/60+17/3600
```javascript
var deg = 57; // 57°
var min = 45; // 45 Minutes
var sec = 17; // 17 Seconds

new Fraction(deg).add(min, 60).add(sec, 3600).toString() // -> 57.7547(2)
```


Rational approximation of irrational numbers
===

Now it's getting messy ;d To approximate a number like *sqrt(5) - 2* with a numerator and denominator, you can reformat the equation as follows: *pow(n / d + 2, 2) = 5*.

Then the following algorithm will generate the rational number besides the binary representation.

```javascript
var x = "/", s = "";

var a = new Fraction(0),
    b = new Fraction(1);
for (var n = 0; n <= 10; n++) {

  var c = a.add(b).div(2);

  console.log(n + "\t" + a + "\t" + b + "\t" + c + "\t" + x);

  if (c.add(2).pow(2) < 5) {
    a = c;
    x = "1";
  } else {
    b = c;
    x = "0";
  }
  s+= x;
}
console.log(s)
```

The result is

```
n   a[n]        b[n]        c[n]            x[n]
0   0/1         1/1         1/2             /
1   0/1         1/2         1/4             0
2   0/1         1/4         1/8             0
3   1/8         1/4         3/16            1
4   3/16        1/4         7/32            1
5   7/32        1/4         15/64           1
6   15/64       1/4         31/128          1
7   15/64       31/128      61/256          0
8   15/64       61/256      121/512         0
9   15/64       121/512     241/1024        0
10  241/1024    121/512     483/2048        1
```
Thus the approximation after 11 iterations of the bisection method is *483 / 2048* and the binary representation is 0.00111100011 (see [WolframAlpha](http://www.wolframalpha.com/input/?i=sqrt%285%29-2+binary))


I published another example on how to approximate PI with fraction.js on my [blog](http://www.xarg.org/2014/03/precise-calculations-in-javascript/) (Still not the best idea to approximate irrational numbers, but it illustrates the capabilities of Fraction.js perfectly).


Get the exact fractional part of a number
---
```javascript
var f = new Fraction("-6.(3416)");
console.log("" + f.mod(1).abs()); // 0.(3416)
```

Mathematical correct modulo
---
The behaviour on negative congruences is different to most modulo implementations in computer science. Even the *mod()* function of Fraction.js behaves in the typical way. To solve the problem of having the mathematical correct modulo with Fraction.js you could come up with this:

```javascript
var a = -1;
var b = 10.99;

console.log(new Fraction(a)
  .mod(b)); // Not correct, usual Modulo

console.log(new Fraction(a)
  .mod(b).add(b).mod(b)); // Correct! Mathematical Modulo
```

fmod() impreciseness circumvented
---
It turns out that Fraction.js outperforms almost any fmod() implementation, including JavaScript itself, [php.js](http://phpjs.org/functions/fmod/), C++, Python, Java and even Wolframalpha due to the fact that numbers like 0.05, 0.1, ... are infinite decimal in base 2.

The equation *fmod(4.55, 0.05)* gives *0.04999999999999957*, wolframalpha says *1/20*. The correct answer should be **zero**, as 0.05 divides 4.55 without any remainder.


Parser
===

Any function (see below) as well as the constructor of the *Fraction* class parses its input and reduce it to the smallest term.

You can pass either Arrays, Objects, Integers, Doubles or Strings.

Arrays / Objects
---
```javascript
new Fraction(numerator, denominator);
new Fraction([numerator, denominator]);
new Fraction({n: numerator, d: denominator});
```

Integers
---
```javascript
new Fraction(123);
```

Doubles
---
```javascript
new Fraction(55.4);
```

**Note:** If you pass a double as it is, Fraction.js will perform a number analysis based on Farey Sequences. If you concern performance, cache Fraction.js objects and pass arrays/objects.

The method is really precise, but too large exact numbers, like 1234567.9991829 will result in a wrong approximation. If you want to keep the number as it is, convert it to a string, as the string parser will not perform any further observations. If you have problems with the approximation, in the file `examples/approx.js` is a different approximation algorithm, which might work better in some more specific use-cases.


Strings
---
```javascript
new Fraction("123.45");
new Fraction("123/45"); // A rational number represented as two decimals, separated by a slash
new Fraction("123:45"); // A rational number represented as two decimals, separated by a colon
new Fraction("4 123/45"); // A rational number represented as a whole number and a fraction
new Fraction("123.'456'"); // Note the quotes, see below!
new Fraction("123.(456)"); // Note the brackets, see below!
new Fraction("123.45'6'"); // Note the quotes, see below!
new Fraction("123.45(6)"); // Note the brackets, see below!
```

Two arguments
---
```javascript
new Fraction(3, 2); // 3/2 = 1.5
```

Repeating decimal places
---
*Fraction.js* can easily handle repeating decimal places. For example *1/3* is *0.3333...*. There is only one repeating digit. As you can see in the examples above, you can pass a number like *1/3* as "0.'3'" or "0.(3)", which are synonym. There are no tests to parse something like 0.166666666 to 1/6! If you really want to handle this number, wrap around brackets on your own with the function below for example: 0.1(66666666)

Assume you want to divide 123.32 / 33.6(567). [WolframAlpha](http://www.wolframalpha.com/input/?i=123.32+%2F+%2812453%2F370%29) states that you'll get a period of 1776 digits. *Fraction.js* comes to the same result. Give it a try:

```javascript
var f = new Fraction("123.32");
console.log("Bam: " + f.div("33.6(567)"));
```

To automatically make a number like "0.123123123" to something more Fraction.js friendly like "0.(123)", I hacked this little brute force algorithm in a 10 minutes. Improvements are welcome...

```javascript
function formatDecimal(str) {

  var comma, pre, offset, pad, times, repeat;

  if (-1 === (comma = str.indexOf(".")))
    return str;

  pre = str.substr(0, comma + 1);
  str = str.substr(comma + 1);

  for (var i = 0; i < str.length; i++) {

    offset = str.substr(0, i);

    for (var j = 0; j < 5; j++) {

      pad = str.substr(i, j + 1);

      times = Math.ceil((str.length - offset.length) / pad.length);

      repeat = new Array(times + 1).join(pad); // Silly String.repeat hack

      if (0 === (offset + repeat).indexOf(str)) {
        return pre + offset + "(" + pad + ")";
      }
    }
  }
  return null;
}

var f, x = formatDecimal("13.0123123123"); // = 13.0(123)
if (x !== null) {
  f = new Fraction(x);
}
```

Attributes
===

The Fraction object allows direct access to the numerator, denominator and sign attributes. It is ensured that only the sign-attribute holds sign information so that a sign comparison is only necessary against this attribute.

```javascript
var f = new Fraction('-1/2');
console.log(f.n); // Numerator: 1
console.log(f.d); // Denominator: 2
console.log(f.s); // Sign: -1
```


Functions
===

Fraction abs()
---
Returns the actual number without any sign information

Fraction neg()
---
Returns the actual number with flipped sign in order to get the additive inverse

Fraction add(n)
---
Returns the sum of the actual number and the parameter n

Fraction sub(n)
---
Returns the difference of the actual number and the parameter n

Fraction mul(n)
---
Returns the product of the actual number and the parameter n

Fraction div(n)
---
Returns the quotient of the actual number and the parameter n

Fraction pow(exp)
---
Returns the power of the actual number, raised to an possible rational exponent. If the result becomes non-rational the function returns `null`.

Fraction mod(n)
---
Returns the modulus (rest of the division) of the actual object and n (this % n). It's a much more precise [fmod()](#fmod-impreciseness-circumvented) if you like. Please note that *mod()* is just like the modulo operator of most programming languages. If you want a mathematical correct modulo, see [here](#mathematical-correct-modulo).

Fraction mod()
---
Returns the modulus (rest of the division) of the actual object (numerator mod denominator)

Fraction gcd(n)
---
Returns the fractional greatest common divisor

Fraction lcm(n)
---
Returns the fractional least common multiple

Fraction ceil([places=0-16])
---
Returns the ceiling of a rational number with Math.ceil

Fraction floor([places=0-16])
---
Returns the floor of a rational number with Math.floor

Fraction round([places=0-16])
---
Returns the rational number rounded with Math.round

Fraction roundTo(multiple)
---
Rounds a fraction to the closest multiple of another fraction. 

Fraction inverse()
---
Returns the multiplicative inverse of the actual number (n / d becomes d / n) in order to get the reciprocal

Fraction simplify([eps=0.001])
---
Simplifies the rational number under a certain error threshold. Ex. `0.333` will be `1/3` with `eps=0.001`

boolean equals(n)
---
Check if two numbers are equal

int compare(n)
---
Compare two numbers.
```
result < 0: n is greater than actual number
result > 0: n is smaller than actual number
result = 0: n is equal to the actual number
```

boolean divisible(n)
---
Check if two numbers are divisible (n divides this)

double valueOf()
---
Returns a decimal representation of the fraction

String toString([decimalPlaces=15])
---
Generates an exact string representation of the actual object. For repeated decimal places all digits are collected within brackets, like `1/3 = "0.(3)"`. For all other numbers, up to `decimalPlaces` significant digits are collected - which includes trailing zeros if the number is getting truncated. However, `1/2 = "0.5"` without trailing zeros of course.

**Note:** As `valueOf()` and `toString()` are provided, `toString()` is only called implicitly in a real string context. Using the plus-operator like `"123" + new Fraction` will call valueOf(), because JavaScript tries to combine two primitives first and concatenates them later, as string will be the more dominant type. `alert(new Fraction)` or `String(new Fraction)` on the other hand will do what you expect. If you really want to have control, you should call `toString()` or `valueOf()` explicitly!

String toLatex(excludeWhole=false)
---
Generates an exact LaTeX representation of the actual object. You can see a [live demo](http://www.xarg.org/2014/03/precise-calculations-in-javascript/) on my blog.

The optional boolean parameter indicates if you want to exclude the whole part. "1 1/3" instead of "4/3"

String toFraction(excludeWhole=false)
---
Gets a string representation of the fraction

The optional boolean parameter indicates if you want to exclude the whole part. "1 1/3" instead of "4/3"

Array toContinued()
---
Gets an array of the fraction represented as a continued fraction. The first element always contains the whole part.

```javascript
var f = new Fraction('88/33');
var c = f.toContinued(); // [2, 1, 2]
```

Fraction clone()
---
Creates a copy of the actual Fraction object


Exceptions
===
If a really hard error occurs (parsing error, division by zero), *fraction.js* throws exceptions! Please make sure you handle them correctly.



Installation
===
Installing fraction.js is as easy as cloning this repo or use the following command:

```
npm install fraction.js
```

Using Fraction.js with the browser
===
```html
<script src="fraction.js"></script>
<script>
    console.log(Fraction("123/456"));
</script>
```

Using Fraction.js with TypeScript
===
```js
import Fraction from "fraction.js";
console.log(Fraction("123/456"));
```

Coding Style
===
As every library I publish, fraction.js is also built to be as small as possible after compressing it with Google Closure Compiler in advanced mode. Thus the coding style orientates a little on maxing-out the compression rate. Please make sure you keep this style if you plan to extend the library.


Precision
===
Fraction.js tries to circumvent floating point errors, by having an internal representation of numerator and denominator. As it relies on JavaScript, there is also a limit. The biggest number representable is `Number.MAX_SAFE_INTEGER / 1` and the smallest is `-1 / Number.MAX_SAFE_INTEGER`, with `Number.MAX_SAFE_INTEGER=9007199254740991`. If this is not enough, there is `bigfraction.js` shipped experimentally, which relies on `BigInt` and should become the new Fraction.js eventually. 

Testing
===
If you plan to enhance the library, make sure you add test cases and all the previous tests are passing. You can test the library with

```
npm test
```


Copyright and licensing
===
Copyright (c) 2023, [Robert Eisele](https://raw.org/)
Licensed under the MIT license.


---

0.5.2 / 2017-09-13
==================

  * Fix regression matching multiple ETags in `If-None-Match`
  * perf: improve `If-None-Match` token parsing

0.5.1 / 2017-09-11
==================

  * Fix handling of modified headers with invalid dates
  * perf: improve ETag match loop

0.5.0 / 2017-02-21
==================

  * Fix incorrect result when `If-None-Match` has both `*` and ETags
  * Fix weak `ETag` matching to match spec
  * perf: delay reading header values until needed
  * perf: skip checking modified time if ETag check failed
  * perf: skip parsing `If-None-Match` when no `ETag` header
  * perf: use `Date.parse` instead of `new Date`

0.4.0 / 2017-02-05
==================

  * Fix false detection of `no-cache` request directive
  * perf: enable strict mode
  * perf: hoist regular expressions
  * perf: remove duplicate conditional
  * perf: remove unnecessary boolean coercions

0.3.0 / 2015-05-12
==================

  * Add weak `ETag` matching support

0.2.4 / 2014-09-07
==================

  * Support Node.js 0.6

0.2.3 / 2014-09-07
==================

  * Move repository to jshttp

0.2.2 / 2014-02-19
==================

  * Revert "Fix for blank page on Safari reload"

0.2.1 / 2014-01-29
==================

  * Fix for blank page on Safari reload

0.2.0 / 2013-08-11
==================

  * Return stale for `Cache-Control: no-cache`

0.1.0 / 2012-06-15
==================

  * Add `If-None-Match: *` support

0.0.1 / 2012-06-10
==================

  * Initial release


---

# fresh

[![NPM Version][npm-image]][npm-url]
[![NPM Downloads][downloads-image]][downloads-url]
[![Node.js Version][node-version-image]][node-version-url]
[![Build Status][travis-image]][travis-url]
[![Test Coverage][coveralls-image]][coveralls-url]

HTTP response freshness testing

## Installation

This is a [Node.js](https://nodejs.org/en/) module available through the
[npm registry](https://www.npmjs.com/). Installation is done using the
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):

```
$ npm install fresh
```

## API

<!-- eslint-disable no-unused-vars -->

```js
var fresh = require('fresh')
```

### fresh(reqHeaders, resHeaders)

Check freshness of the response using request and response headers.

When the response is still "fresh" in the client's cache `true` is
returned, otherwise `false` is returned to indicate that the client
cache is now stale and the full response should be sent.

When a client sends the `Cache-Control: no-cache` request header to
indicate an end-to-end reload request, this module will return `false`
to make handling these requests transparent.

## Known Issues

This module is designed to only follow the HTTP specifications, not
to work-around all kinda of client bugs (especially since this module
typically does not recieve enough information to understand what the
client actually is).

There is a known issue that in certain versions of Safari, Safari
will incorrectly make a request that allows this module to validate
freshness of the resource even when Safari does not have a
representation of the resource in the cache. The module
[jumanji](https://www.npmjs.com/package/jumanji) can be used in
an Express application to work-around this issue and also provides
links to further reading on this Safari bug.

## Example

### API usage

<!-- eslint-disable no-redeclare, no-undef -->

```js
var reqHeaders = { 'if-none-match': '"foo"' }
var resHeaders = { 'etag': '"bar"' }
fresh(reqHeaders, resHeaders)
// => false

var reqHeaders = { 'if-none-match': '"foo"' }
var resHeaders = { 'etag': '"foo"' }
fresh(reqHeaders, resHeaders)
// => true
```

### Using with Node.js http server

```js
var fresh = require('fresh')
var http = require('http')

var server = http.createServer(function (req, res) {
  // perform server logic
  // ... including adding ETag / Last-Modified response headers

  if (isFresh(req, res)) {
    // client has a fresh copy of resource
    res.statusCode = 304
    res.end()
    return
  }

  // send the resource
  res.statusCode = 200
  res.end('hello, world!')
})

function isFresh (req, res) {
  return fresh(req.headers, {
    'etag': res.getHeader('ETag'),
    'last-modified': res.getHeader('Last-Modified')
  })
}

server.listen(3000)
```

## License

[MIT](LICENSE)

[npm-image]: https://img.shields.io/npm/v/fresh.svg
[npm-url]: https://npmjs.org/package/fresh
[node-version-image]: https://img.shields.io/node/v/fresh.svg
[node-version-url]: https://nodejs.org/en/
[travis-image]: https://img.shields.io/travis/jshttp/fresh/master.svg
[travis-url]: https://travis-ci.org/jshttp/fresh
[coveralls-image]: https://img.shields.io/coveralls/jshttp/fresh/master.svg
[coveralls-url]: https://coveralls.io/r/jshttp/fresh?branch=master
[downloads-image]: https://img.shields.io/npm/dm/fresh.svg
[downloads-url]: https://npmjs.org/package/fresh


---

Node.js: fs-extra
=================

`fs-extra` adds file system methods that aren't included in the native `fs` module and adds promise support to the `fs` methods. It also uses [`graceful-fs`](https://github.com/isaacs/node-graceful-fs) to prevent `EMFILE` errors. It should be a drop in replacement for `fs`.

[![npm Package](https://img.shields.io/npm/v/fs-extra.svg)](https://www.npmjs.org/package/fs-extra)
[![License](https://img.shields.io/npm/l/fs-extra.svg)](https://github.com/jprichardson/node-fs-extra/blob/master/LICENSE)
[![build status](https://img.shields.io/github/actions/workflow/status/jprichardson/node-fs-extra/ci.yml?branch=master)](https://github.com/jprichardson/node-fs-extra/actions/workflows/ci.yml?query=branch%3Amaster)
[![downloads per month](http://img.shields.io/npm/dm/fs-extra.svg)](https://www.npmjs.org/package/fs-extra)
[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)

Why?
----

I got tired of including `mkdirp`, `rimraf`, and `ncp` in most of my projects.




Installation
------------

    npm install fs-extra



Usage
-----

### CommonJS

`fs-extra` is a drop in replacement for native `fs`. All methods in `fs` are attached to `fs-extra`. All `fs` methods return promises if the callback isn't passed.

You don't ever need to include the original `fs` module again:

```js
const fs = require('fs') // this is no longer necessary
```

you can now do this:

```js
const fs = require('fs-extra')
```

or if you prefer to make it clear that you're using `fs-extra` and not `fs`, you may want
to name your `fs` variable `fse` like so:

```js
const fse = require('fs-extra')
```

you can also keep both, but it's redundant:

```js
const fs = require('fs')
const fse = require('fs-extra')
```

### ESM

There is also an `fs-extra/esm` import, that supports both default and named exports. However, note that `fs` methods are not included in `fs-extra/esm`; you still need to import `fs` and/or `fs/promises` seperately:

```js
import { readFileSync } from 'fs'
import { readFile } from 'fs/promises'
import { outputFile, outputFileSync } from 'fs-extra/esm'
```

Default exports are supported:

```js
import fs from 'fs'
import fse from 'fs-extra/esm'
// fse.readFileSync is not a function; must use fs.readFileSync
```

but you probably want to just use regular `fs-extra` instead of `fs-extra/esm` for default exports:

```js
import fs from 'fs-extra'
// both fs and fs-extra methods are defined
```

Sync vs Async vs Async/Await
-------------
Most methods are async by default. All async methods will return a promise if the callback isn't passed.

Sync methods on the other hand will throw if an error occurs.

Also Async/Await will throw an error if one occurs.

Example:

```js
const fs = require('fs-extra')

// Async with promises:
fs.copy('/tmp/myfile', '/tmp/mynewfile')
  .then(() => console.log('success!'))
  .catch(err => console.error(err))

// Async with callbacks:
fs.copy('/tmp/myfile', '/tmp/mynewfile', err => {
  if (err) return console.error(err)
  console.log('success!')
})

// Sync:
try {
  fs.copySync('/tmp/myfile', '/tmp/mynewfile')
  console.log('success!')
} catch (err) {
  console.error(err)
}

// Async/Await:
async function copyFiles () {
  try {
    await fs.copy('/tmp/myfile', '/tmp/mynewfile')
    console.log('success!')
  } catch (err) {
    console.error(err)
  }
}

copyFiles()
```


Methods
-------

### Async

- [copy](docs/copy.md)
- [emptyDir](docs/emptyDir.md)
- [ensureFile](docs/ensureFile.md)
- [ensureDir](docs/ensureDir.md)
- [ensureLink](docs/ensureLink.md)
- [ensureSymlink](docs/ensureSymlink.md)
- [mkdirp](docs/ensureDir.md)
- [mkdirs](docs/ensureDir.md)
- [move](docs/move.md)
- [outputFile](docs/outputFile.md)
- [outputJson](docs/outputJson.md)
- [pathExists](docs/pathExists.md)
- [readJson](docs/readJson.md)
- [remove](docs/remove.md)
- [writeJson](docs/writeJson.md)

### Sync

- [copySync](docs/copy-sync.md)
- [emptyDirSync](docs/emptyDir-sync.md)
- [ensureFileSync](docs/ensureFile-sync.md)
- [ensureDirSync](docs/ensureDir-sync.md)
- [ensureLinkSync](docs/ensureLink-sync.md)
- [ensureSymlinkSync](docs/ensureSymlink-sync.md)
- [mkdirpSync](docs/ensureDir-sync.md)
- [mkdirsSync](docs/ensureDir-sync.md)
- [moveSync](docs/move-sync.md)
- [outputFileSync](docs/outputFile-sync.md)
- [outputJsonSync](docs/outputJson-sync.md)
- [pathExistsSync](docs/pathExists-sync.md)
- [readJsonSync](docs/readJson-sync.md)
- [removeSync](docs/remove-sync.md)
- [writeJsonSync](docs/writeJson-sync.md)


**NOTE:** You can still use the native Node.js methods. They are promisified and copied over to `fs-extra`. See [notes on `fs.read()`, `fs.write()`, & `fs.writev()`](docs/fs-read-write-writev.md)

### What happened to `walk()` and `walkSync()`?

They were removed from `fs-extra` in v2.0.0. If you need the functionality, `walk` and `walkSync` are available as separate packages, [`klaw`](https://github.com/jprichardson/node-klaw) and [`klaw-sync`](https://github.com/manidlou/node-klaw-sync).


Third Party
-----------

### CLI

[fse-cli](https://www.npmjs.com/package/@atao60/fse-cli) allows you to run `fs-extra` from a console or from [npm](https://www.npmjs.com) scripts.

### TypeScript

If you like TypeScript, you can use `fs-extra` with it: https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/fs-extra


### File / Directory Watching

If you want to watch for changes to files or directories, then you should use [chokidar](https://github.com/paulmillr/chokidar).

### Obtain Filesystem (Devices, Partitions) Information

[fs-filesystem](https://github.com/arthurintelligence/node-fs-filesystem) allows you to read the state of the filesystem of the host on which it is run. It returns information about both the devices and the partitions (volumes) of the system.

### Misc.

- [fs-extra-debug](https://github.com/jdxcode/fs-extra-debug) - Send your fs-extra calls to [debug](https://npmjs.org/package/debug).
- [mfs](https://github.com/cadorn/mfs) - Monitor your fs-extra calls.



Hacking on fs-extra
-------------------

Wanna hack on `fs-extra`? Great! Your help is needed! [fs-extra is one of the most depended upon Node.js packages](http://nodei.co/npm/fs-extra.png?downloads=true&downloadRank=true&stars=true). This project
uses [JavaScript Standard Style](https://github.com/feross/standard) - if the name or style choices bother you,
you're gonna have to get over it :) If `standard` is good enough for `npm`, it's good enough for `fs-extra`.

[![js-standard-style](https://cdn.rawgit.com/feross/standard/master/badge.svg)](https://github.com/feross/standard)

What's needed?
- First, take a look at existing issues. Those are probably going to be where the priority lies.
- More tests for edge cases. Specifically on different platforms. There can never be enough tests.
- Improve test coverage.

Note: If you make any big changes, **you should definitely file an issue for discussion first.**

### Running the Test Suite

fs-extra contains hundreds of tests.

- `npm run lint`: runs the linter ([standard](http://standardjs.com/))
- `npm run unit`: runs the unit tests
- `npm run unit-esm`: runs tests for `fs-extra/esm` exports
- `npm test`: runs the linter and all tests

When running unit tests, set the environment variable `CROSS_DEVICE_PATH` to the absolute path of an empty directory on another device (like a thumb drive) to enable cross-device move tests.


### Windows

If you run the tests on the Windows and receive a lot of symbolic link `EPERM` permission errors, it's
because on Windows you need elevated privilege to create symbolic links. You can add this to your Windows's
account by following the instructions here: http://superuser.com/questions/104845/permission-to-make-symbolic-links-in-windows-7
However, I didn't have much luck doing this.

Since I develop on Mac OS X, I use VMWare Fusion for Windows testing. I create a shared folder that I map to a drive on Windows.
I open the `Node.js command prompt` and run as `Administrator`. I then map the network drive running the following command:

    net use z: "\\vmware-host\Shared Folders"

I can then navigate to my `fs-extra` directory and run the tests.


Naming
------

I put a lot of thought into the naming of these functions. Inspired by @coolaj86's request. So he deserves much of the credit for raising the issue. See discussion(s) here:

* https://github.com/jprichardson/node-fs-extra/issues/2
* https://github.com/flatiron/utile/issues/11
* https://github.com/ryanmcgrath/wrench-js/issues/29
* https://github.com/substack/node-mkdirp/issues/17

First, I believe that in as many cases as possible, the [Node.js naming schemes](http://nodejs.org/api/fs.html) should be chosen. However, there are problems with the Node.js own naming schemes.

For example, `fs.readFile()` and `fs.readdir()`: the **F** is capitalized in *File* and the **d** is not capitalized in *dir*. Perhaps a bit pedantic, but they should still be consistent. Also, Node.js has chosen a lot of POSIX naming schemes, which I believe is great. See: `fs.mkdir()`, `fs.rmdir()`, `fs.chown()`, etc.

We have a dilemma though. How do you consistently name methods that perform the following POSIX commands: `cp`, `cp -r`, `mkdir -p`, and `rm -rf`?

My perspective: when in doubt, err on the side of simplicity. A directory is just a hierarchical grouping of directories and files. Consider that for a moment. So when you want to copy it or remove it, in most cases you'll want to copy or remove all of its contents. When you want to create a directory, if the directory that it's suppose to be contained in does not exist, then in most cases you'll want to create that too.

So, if you want to remove a file or a directory regardless of whether it has contents, just call `fs.remove(path)`. If you want to copy a file or a directory whether it has contents, just call `fs.copy(source, destination)`. If you want to create a directory regardless of whether its parent directories exist, just call `fs.mkdirs(path)` or `fs.mkdirp(path)`.


Credit
------

`fs-extra` wouldn't be possible without using the modules from the following authors:

- [Isaac Shlueter](https://github.com/isaacs)
- [Charlie McConnel](https://github.com/avianflu)
- [James Halliday](https://github.com/substack)
- [Andrew Kelley](https://github.com/andrewrk)




License
-------

Licensed under MIT

Copyright (c) 2011-2024 [JP Richardson](https://github.com/jprichardson)

[1]: http://nodejs.org/docs/latest/api/fs.html


[jsonfile]: https://github.com/jprichardson/node-jsonfile


---

# fs-monkey

[![][npm-img]][npm-url] [![][travis-badge]][travis-url]

Monkey-patches for filesystem related things.

  - Rewrite `require` function to load Node's modules from memory.
  - Or rewrite the whole `fs` filesystem module.

## Install

```shell
npm install --save fs-monkey
```

## Terms

An *fs-like* object is an object that implements methods of Node's
[filesystem API](https://nodejs.org/api/fs.html).
It is denoted as `vol`:

```js
let vol = {
    readFile: () => { /* ... */ },
    readFileSync: () => { /* ... */ },
    // etc...
}
```


## Reference

 - [`patchFs`](./docs/api/patchFs.md) - rewrites Node's filesystem module `fs` with *fs-like* object `vol`
 - [`patchRequire`](./docs/api/patchRequire.md) - rewrites `require` function, patches Node's `module` module to use a given *fs-like* object for module loading


[npm-img]: https://img.shields.io/npm/v/fs-monkey.svg
[npm-url]: https://www.npmjs.com/package/fs-monkey
[travis-url]: https://travis-ci.org/streamich/fs-monkey
[travis-badge]: https://travis-ci.org/streamich/fs-monkey.svg?branch=master


## License

[Unlicense](./LICENSE) - public domain.


---

# `patchFs(vol[, fs])`

Rewrites Node's filesystem module `fs` with *fs-like* object.

 - `vol` - fs-like object
 - `fs` *(optional)* - a filesystem to patch, defaults to `require('fs')`

```js
import {patchFs} from 'fs-monkey';

const myfs = {
    readFileSync: () => 'hello world',
};

patchFs(myfs);
console.log(require('fs').readFileSync('/foo/bar')); // hello world
```

You don't need to create *fs-like* objects yourself, use [`memfs`](https://github.com/streamich/memfs)
to create a virtual filesystem for you:

```js
import {vol} from 'memfs';
import {patchFs} from 'fs-monkey';

vol.fromJSON({'/dir/foo': 'bar'});
patchFs(vol);
console.log(require('fs').readdirSync('/')); // [ 'dir' ]
```


---

# `patchRequire(vol[, unixifyPaths[, Module]])`

Patches Node's `module` module to use a given *fs-like* object `vol` for module loading.

 - `vol` - fs-like object
 - `unixifyPaths` *(optional)* - whether to convert Windows paths to unix style paths, defaults to `false`.
 - `Module` *(optional)* - a module to patch, defaults to `require('module')`

Monkey-patches the `require` function in Node, this way you can make
Node.js to *require* modules from your custom filesystem.

It expects an object with three filesystem methods implemented that are
needed for the `require` function to work.

```js
let vol = {
    readFileSync: () => {},
    realpathSync: () => {},
    statSync: () => {},
};
```

If you want to make Node.js to *require* your files from memory, you
don't need to implement those functions yourself, just use the
[`memfs`](https://github.com/streamich/memfs) package:

```js
import {vol} from 'memfs';
import {patchRequire} from 'fs-monkey';

vol.fromJSON({'/foo/bar.js': 'console.log("obi trice");'});
patchRequire(vol);
require('/foo/bar'); // obi trice
```

Now the `require` function will only load the files from the `vol` file
system, but not from the actual filesystem on the disk.

If you want the `require` function to load modules from both file
systems, use the [`unionfs`](https://github.com/streamich/unionfs) package
to combine both filesystems into a union:

```js
import {vol} from 'memfs';
import {patchRequire} from 'fs-monkey';
import {ufs} from 'unionfs';
import * as fs from 'fs';

vol.fromJSON({'/foo/bar.js': 'console.log("obi trice");'});
ufs
    .use(vol)
    .use(fs);
patchRequire(ufs);
require('/foo/bar.js'); // obi trice
```


---

# fs.realpath

A backwards-compatible fs.realpath for Node v6 and above

In Node v6, the JavaScript implementation of fs.realpath was replaced
with a faster (but less resilient) native implementation.  That raises
new and platform-specific errors and cannot handle long or excessively
symlink-looping paths.

This module handles those cases by detecting the new errors and
falling back to the JavaScript implementation.  On versions of Node
prior to v6, it has no effect.

## USAGE

```js
var rp = require('fs.realpath')

// async version
rp.realpath(someLongAndLoopingPath, function (er, real) {
  // the ELOOP was handled, but it was a bit slower
})

// sync version
var real = rp.realpathSync(someLongAndLoopingPath)

// monkeypatch at your own risk!
// This replaces the fs.realpath/fs.realpathSync builtins
rp.monkeypatch()

// un-do the monkeypatching
rp.unmonkeypatch()
```


---

# Security

Please email [@ljharb](https://github.com/ljharb) or see https://tidelift.com/security if you have a potential security vulnerability to report.


---

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [v1.1.2](https://github.com/ljharb/function-bind/compare/v1.1.1...v1.1.2) - 2023-10-12

### Merged

- Point to the correct file [`#16`](https://github.com/ljharb/function-bind/pull/16)

### Commits

- [Tests] migrate tests to Github Actions [`4f8b57c`](https://github.com/ljharb/function-bind/commit/4f8b57c02f2011fe9ae353d5e74e8745f0988af8)
- [Tests] remove `jscs` [`90eb2ed`](https://github.com/ljharb/function-bind/commit/90eb2edbeefd5b76cd6c3a482ea3454db169b31f)
- [meta] update `.gitignore` [`53fcdc3`](https://github.com/ljharb/function-bind/commit/53fcdc371cd66634d6e9b71c836a50f437e89fed)
- [Tests] up to `node` `v11.10`, `v10.15`, `v9.11`, `v8.15`, `v6.16`, `v4.9`; use `nvm install-latest-npm`; run audit script in tests [`1fe8f6e`](https://github.com/ljharb/function-bind/commit/1fe8f6e9aed0dfa8d8b3cdbd00c7f5ea0cd2b36e)
- [meta] add `auto-changelog` [`1921fcb`](https://github.com/ljharb/function-bind/commit/1921fcb5b416b63ffc4acad051b6aad5722f777d)
- [Robustness] remove runtime dependency on all builtins except `.apply` [`f743e61`](https://github.com/ljharb/function-bind/commit/f743e61aa6bb2360358c04d4884c9db853d118b7)
- Docs: enable badges; update wording [`503cb12`](https://github.com/ljharb/function-bind/commit/503cb12d998b5f91822776c73332c7adcd6355dd)
- [readme] update badges [`290c5db`](https://github.com/ljharb/function-bind/commit/290c5dbbbda7264efaeb886552a374b869a4bb48)
- [Tests] switch to nyc for coverage [`ea360ba`](https://github.com/ljharb/function-bind/commit/ea360ba907fc2601ed18d01a3827fa2d3533cdf8)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `tape` [`cae5e9e`](https://github.com/ljharb/function-bind/commit/cae5e9e07a5578dc6df26c03ee22851ce05b943c)
- [meta] add `funding` field; create FUNDING.yml [`c9f4274`](https://github.com/ljharb/function-bind/commit/c9f4274aa80ea3aae9657a3938fdba41a3b04ca6)
- [Tests] fix eslint errors from #15 [`f69aaa2`](https://github.com/ljharb/function-bind/commit/f69aaa2beb2fdab4415bfb885760a699d0b9c964)
- [actions] fix permissions [`99a0cd9`](https://github.com/ljharb/function-bind/commit/99a0cd9f3b5bac223a0d572f081834cd73314be7)
- [meta] use `npmignore` to autogenerate an npmignore file [`f03b524`](https://github.com/ljharb/function-bind/commit/f03b524ca91f75a109a5d062f029122c86ecd1ae)
- [Dev Deps] update `@ljharb/eslint‑config`, `eslint`, `tape` [`7af9300`](https://github.com/ljharb/function-bind/commit/7af930023ae2ce7645489532821e4fbbcd7a2280)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `covert`, `tape` [`64a9127`](https://github.com/ljharb/function-bind/commit/64a9127ab0bd331b93d6572eaf6e9971967fc08c)
- [Tests] use `aud` instead of `npm audit` [`e75069c`](https://github.com/ljharb/function-bind/commit/e75069c50010a8fcce2a9ce2324934c35fdb4386)
- [Dev Deps] update `@ljharb/eslint-config`, `aud`, `tape` [`d03555c`](https://github.com/ljharb/function-bind/commit/d03555ca59dea3b71ce710045e4303b9e2619e28)
- [meta] add `safe-publish-latest` [`9c8f809`](https://github.com/ljharb/function-bind/commit/9c8f8092aed027d7e80c94f517aa892385b64f09)
- [Dev Deps] update `@ljharb/eslint-config`, `tape` [`baf6893`](https://github.com/ljharb/function-bind/commit/baf6893e27f5b59abe88bc1995e6f6ed1e527397)
- [meta] create SECURITY.md [`4db1779`](https://github.com/ljharb/function-bind/commit/4db17799f1f28ae294cb95e0081ca2b591c3911b)
- [Tests] add `npm run audit` [`c8b38ec`](https://github.com/ljharb/function-bind/commit/c8b38ec40ed3f85dabdee40ed4148f1748375bc2)
- Revert "Point to the correct file" [`05cdf0f`](https://github.com/ljharb/function-bind/commit/05cdf0fa205c6a3c5ba40bbedd1dfa9874f915c9)

## [v1.1.1](https://github.com/ljharb/function-bind/compare/v1.1.0...v1.1.1) - 2017-08-28

### Commits

- [Tests] up to `node` `v8`; newer npm breaks on older node; fix scripts [`817f7d2`](https://github.com/ljharb/function-bind/commit/817f7d28470fdbff8ef608d4d565dd4d1430bc5e)
- [Dev Deps] update `eslint`, `jscs`, `tape`, `@ljharb/eslint-config` [`854288b`](https://github.com/ljharb/function-bind/commit/854288b1b6f5c555f89aceb9eff1152510262084)
- [Dev Deps] update `tape`, `jscs`, `eslint`, `@ljharb/eslint-config` [`83e639f`](https://github.com/ljharb/function-bind/commit/83e639ff74e6cd6921285bccec22c1bcf72311bd)
- Only apps should have lockfiles [`5ed97f5`](https://github.com/ljharb/function-bind/commit/5ed97f51235c17774e0832e122abda0f3229c908)
- Use a SPDX-compliant “license” field. [`5feefea`](https://github.com/ljharb/function-bind/commit/5feefea0dc0193993e83e5df01ded424403a5381)

## [v1.1.0](https://github.com/ljharb/function-bind/compare/v1.0.2...v1.1.0) - 2016-02-14

### Commits

- Update `eslint`, `tape`; use my personal shared `eslint` config [`9c9062a`](https://github.com/ljharb/function-bind/commit/9c9062abbe9dd70b59ea2c3a3c3a81f29b457097)
- Add `npm run eslint` [`dd96c56`](https://github.com/ljharb/function-bind/commit/dd96c56720034a3c1ffee10b8a59a6f7c53e24ad)
- [New] return the native `bind` when available. [`82186e0`](https://github.com/ljharb/function-bind/commit/82186e03d73e580f95ff167e03f3582bed90ed72)
- [Dev Deps] update `tape`, `jscs`, `eslint`, `@ljharb/eslint-config` [`a3dd767`](https://github.com/ljharb/function-bind/commit/a3dd76720c795cb7f4586b0544efabf8aa107b8b)
- Update `eslint` [`3dae2f7`](https://github.com/ljharb/function-bind/commit/3dae2f7423de30a2d20313ddb1edc19660142fe9)
- Update `tape`, `covert`, `jscs` [`a181eee`](https://github.com/ljharb/function-bind/commit/a181eee0cfa24eb229c6e843a971f36e060a2f6a)
- [Tests] up to `node` `v5.6`, `v4.3` [`964929a`](https://github.com/ljharb/function-bind/commit/964929a6a4ddb36fb128de2bcc20af5e4f22e1ed)
- Test up to `io.js` `v2.1` [`2be7310`](https://github.com/ljharb/function-bind/commit/2be7310f2f74886a7124ca925be411117d41d5ea)
- Update `tape`, `jscs`, `eslint`, `@ljharb/eslint-config` [`45f3d68`](https://github.com/ljharb/function-bind/commit/45f3d6865c6ca93726abcef54febe009087af101)
- [Dev Deps] update `tape`, `jscs` [`6e1340d`](https://github.com/ljharb/function-bind/commit/6e1340d94642deaecad3e717825db641af4f8b1f)
- [Tests] up to `io.js` `v3.3`, `node` `v4.1` [`d9bad2b`](https://github.com/ljharb/function-bind/commit/d9bad2b778b1b3a6dd2876087b88b3acf319f8cc)
- Update `eslint` [`935590c`](https://github.com/ljharb/function-bind/commit/935590caa024ab356102e4858e8fc315b2ccc446)
- [Dev Deps] update `jscs`, `eslint`, `@ljharb/eslint-config` [`8c9a1ef`](https://github.com/ljharb/function-bind/commit/8c9a1efd848e5167887aa8501857a0940a480c57)
- Test on `io.js` `v2.2` [`9a3a38c`](https://github.com/ljharb/function-bind/commit/9a3a38c92013aed6e108666e7bd40969b84ac86e)
- Run `travis-ci` tests on `iojs` and `node` v0.12; speed up builds; allow 0.8 failures. [`69afc26`](https://github.com/ljharb/function-bind/commit/69afc2617405b147dd2a8d8ae73ca9e9283f18b4)
- [Dev Deps] Update `tape`, `eslint` [`36c1be0`](https://github.com/ljharb/function-bind/commit/36c1be0ab12b45fe5df6b0fdb01a5d5137fd0115)
- Update `tape`, `jscs` [`98d8303`](https://github.com/ljharb/function-bind/commit/98d8303cd5ca1c6b8f985469f86b0d44d7d45f6e)
- Update `jscs` [`9633a4e`](https://github.com/ljharb/function-bind/commit/9633a4e9fbf82051c240855166e468ba8ba0846f)
- Update `tape`, `jscs` [`c80ef0f`](https://github.com/ljharb/function-bind/commit/c80ef0f46efc9791e76fa50de4414092ac147831)
- Test up to `io.js` `v3.0` [`7e2c853`](https://github.com/ljharb/function-bind/commit/7e2c8537d52ab9cf5a655755561d8917684c0df4)
- Test on `io.js` `v2.4` [`5a199a2`](https://github.com/ljharb/function-bind/commit/5a199a27ba46795ba5eaf0845d07d4b8232895c9)
- Test on `io.js` `v2.3` [`a511b88`](https://github.com/ljharb/function-bind/commit/a511b8896de0bddf3b56862daa416c701f4d0453)
- Fixing a typo from 822b4e1938db02dc9584aa434fd3a45cb20caf43 [`732d6b6`](https://github.com/ljharb/function-bind/commit/732d6b63a9b33b45230e630dbcac7a10855d3266)
- Update `jscs` [`da52a48`](https://github.com/ljharb/function-bind/commit/da52a4886c06d6490f46ae30b15e4163ba08905d)
- Lock covert to v1.0.0. [`d6150fd`](https://github.com/ljharb/function-bind/commit/d6150fda1e6f486718ebdeff823333d9e48e7430)

## [v1.0.2](https://github.com/ljharb/function-bind/compare/v1.0.1...v1.0.2) - 2014-10-04

## [v1.0.1](https://github.com/ljharb/function-bind/compare/v1.0.0...v1.0.1) - 2014-10-03

### Merged

- make CI build faster [`#3`](https://github.com/ljharb/function-bind/pull/3)

### Commits

- Using my standard jscs.json [`d8ee94c`](https://github.com/ljharb/function-bind/commit/d8ee94c993eff0a84cf5744fe6a29627f5cffa1a)
- Adding `npm run lint` [`7571ab7`](https://github.com/ljharb/function-bind/commit/7571ab7dfdbd99b25a1dbb2d232622bd6f4f9c10)
- Using consistent indentation [`e91a1b1`](https://github.com/ljharb/function-bind/commit/e91a1b13a61e99ec1e530e299b55508f74218a95)
- Updating jscs [`7e17892`](https://github.com/ljharb/function-bind/commit/7e1789284bc629bc9c1547a61c9b227bbd8c7a65)
- Using consistent quotes [`c50b57f`](https://github.com/ljharb/function-bind/commit/c50b57fcd1c5ec38320979c837006069ebe02b77)
- Adding keywords [`cb94631`](https://github.com/ljharb/function-bind/commit/cb946314eed35f21186a25fb42fc118772f9ee00)
- Directly export a function expression instead of using a declaration, and relying on hoisting. [`5a33c5f`](https://github.com/ljharb/function-bind/commit/5a33c5f45642de180e0d207110bf7d1843ceb87c)
- Naming npm URL and badge in README; use SVG [`2aef8fc`](https://github.com/ljharb/function-bind/commit/2aef8fcb79d54e63a58ae557c4e60949e05d5e16)
- Naming deps URLs in README [`04228d7`](https://github.com/ljharb/function-bind/commit/04228d766670ee45ca24e98345c1f6a7621065b5)
- Naming travis-ci URLs in README; using SVG [`62c810c`](https://github.com/ljharb/function-bind/commit/62c810c2f54ced956cd4d4ab7b793055addfe36e)
- Make sure functions are invoked correctly (also passing coverage tests) [`2b289b4`](https://github.com/ljharb/function-bind/commit/2b289b4dfbf037ffcfa4dc95eb540f6165e9e43a)
- Removing the strict mode pragmas; they make tests fail. [`1aa701d`](https://github.com/ljharb/function-bind/commit/1aa701d199ddc3782476e8f7eef82679be97b845)
- Adding myself as a contributor [`85fd57b`](https://github.com/ljharb/function-bind/commit/85fd57b0860e5a7af42de9a287f3f265fc6d72fc)
- Adding strict mode pragmas [`915b08e`](https://github.com/ljharb/function-bind/commit/915b08e084c86a722eafe7245e21db74aa21ca4c)
- Adding devDeps URLs to README [`4ccc731`](https://github.com/ljharb/function-bind/commit/4ccc73112c1769859e4ca3076caf4086b3cba2cd)
- Fixing the description. [`a7a472c`](https://github.com/ljharb/function-bind/commit/a7a472cf649af515c635cf560fc478fbe48999c8)
- Using a function expression instead of a function declaration. [`b5d3e4e`](https://github.com/ljharb/function-bind/commit/b5d3e4ea6aaffc63888953eeb1fbc7ff45f1fa14)
- Updating tape [`f086be6`](https://github.com/ljharb/function-bind/commit/f086be6029fb56dde61a258c1340600fa174d1e0)
- Updating jscs [`5f9bdb3`](https://github.com/ljharb/function-bind/commit/5f9bdb375ab13ba48f30852aab94029520c54d71)
- Updating jscs [`9b409ba`](https://github.com/ljharb/function-bind/commit/9b409ba6118e23395a4e5d83ef39152aab9d3bfc)
- Run coverage as part of tests. [`8e1b6d4`](https://github.com/ljharb/function-bind/commit/8e1b6d459f047d1bd4fee814e01247c984c80bd0)
- Run linter as part of tests [`c1ca83f`](https://github.com/ljharb/function-bind/commit/c1ca83f832df94587d09e621beba682fabfaa987)
- Updating covert [`701e837`](https://github.com/ljharb/function-bind/commit/701e83774b57b4d3ef631e1948143f43a72f4bb9)

## [v1.0.0](https://github.com/ljharb/function-bind/compare/v0.2.0...v1.0.0) - 2014-08-09

### Commits

- Make sure old and unstable nodes don't fail Travis [`27adca3`](https://github.com/ljharb/function-bind/commit/27adca34a4ab6ad67b6dfde43942a1b103ce4d75)
- Fixing an issue when the bound function is called as a constructor in ES3. [`e20122d`](https://github.com/ljharb/function-bind/commit/e20122d267d92ce553859b280cbbea5d27c07731)
- Adding `npm run coverage` [`a2e29c4`](https://github.com/ljharb/function-bind/commit/a2e29c4ecaef9e2f6cd1603e868c139073375502)
- Updating tape [`b741168`](https://github.com/ljharb/function-bind/commit/b741168b12b235b1717ff696087645526b69213c)
- Upgrading tape [`63631a0`](https://github.com/ljharb/function-bind/commit/63631a04c7fbe97cc2fa61829cc27246d6986f74)
- Updating tape [`363cb46`](https://github.com/ljharb/function-bind/commit/363cb46dafb23cb3e347729a22f9448051d78464)

## v0.2.0 - 2014-03-23

### Commits

- Updating test coverage to match es5-shim. [`aa94d44`](https://github.com/ljharb/function-bind/commit/aa94d44b8f9d7f69f10e060db7709aa7a694e5d4)
- initial [`942ee07`](https://github.com/ljharb/function-bind/commit/942ee07e94e542d91798137bc4b80b926137e066)
- Setting the bound function's length properly. [`079f46a`](https://github.com/ljharb/function-bind/commit/079f46a2d3515b7c0b308c2c13fceb641f97ca25)
- Ensuring that some older browsers will throw when given a regex. [`36ac55b`](https://github.com/ljharb/function-bind/commit/36ac55b87f460d4330253c92870aa26fbfe8227f)
- Removing npm scripts that don't have dependencies [`9d2be60`](https://github.com/ljharb/function-bind/commit/9d2be600002cb8bc8606f8f3585ad3e05868c750)
- Updating tape [`297a4ac`](https://github.com/ljharb/function-bind/commit/297a4acc5464db381940aafb194d1c88f4e678f3)
- Skipping length tests for now. [`d9891ea`](https://github.com/ljharb/function-bind/commit/d9891ea4d2aaffa69f408339cdd61ff740f70565)
- don't take my tea [`dccd930`](https://github.com/ljharb/function-bind/commit/dccd930bfd60ea10cb178d28c97550c3bc8c1e07)


---

# function-bind <sup>[![Version Badge][npm-version-svg]][package-url]</sup>

[![github actions][actions-image]][actions-url]
<!--[![coverage][codecov-image]][codecov-url]-->
[![dependency status][deps-svg]][deps-url]
[![dev dependency status][dev-deps-svg]][dev-deps-url]
[![License][license-image]][license-url]
[![Downloads][downloads-image]][downloads-url]

[![npm badge][npm-badge-png]][package-url]

Implementation of function.prototype.bind

Old versions of phantomjs, Internet Explorer < 9, and node < 0.6 don't support `Function.prototype.bind`.

## Example

```js
Function.prototype.bind = require("function-bind")
```

## Installation

`npm install function-bind`

## Contributors

 - Raynos

## MIT Licenced

[package-url]: https://npmjs.org/package/function-bind
[npm-version-svg]: https://versionbadg.es/Raynos/function-bind.svg
[deps-svg]: https://david-dm.org/Raynos/function-bind.svg
[deps-url]: https://david-dm.org/Raynos/function-bind
[dev-deps-svg]: https://david-dm.org/Raynos/function-bind/dev-status.svg
[dev-deps-url]: https://david-dm.org/Raynos/function-bind#info=devDependencies
[npm-badge-png]: https://nodei.co/npm/function-bind.png?downloads=true&stars=true
[license-image]: https://img.shields.io/npm/l/function-bind.svg
[license-url]: LICENSE
[downloads-image]: https://img.shields.io/npm/dm/function-bind.svg
[downloads-url]: https://npm-stat.com/charts.html?package=function-bind
[codecov-image]: https://codecov.io/gh/Raynos/function-bind/branch/main/graphs/badge.svg
[codecov-url]: https://app.codecov.io/gh/Raynos/function-bind/
[actions-image]: https://img.shields.io/endpoint?url=https://github-actions-badge-u3jn4tfpocch.runkit.sh/Raynos/function-bind
[actions-url]: https://github.com/Raynos/function-bind/actions


---

# gensync

This module allows for developers to write common code that can share
implementation details, hiding whether an underlying request happens
synchronously or asynchronously. This is in contrast with many current Node
APIs which explicitly implement the same API twice, once with calls to
synchronous functions, and once with asynchronous functions.

Take for example `fs.readFile` and `fs.readFileSync`, if you're writing an API
that loads a file and then performs a synchronous operation on the data, it
can be frustrating to maintain two parallel functions.


## Example

```js
const fs = require("fs");
const gensync = require("gensync");

const readFile = gensync({
  sync: fs.readFileSync,
  errback: fs.readFile,
});

const myOperation = gensync(function* (filename) {
  const code = yield* readFile(filename, "utf8");

  return "// some custom prefix\n" + code;
});

// Load and add the prefix synchronously:
const result = myOperation.sync("./some-file.js");

// Load and add the prefix asynchronously with promises:
myOperation.async("./some-file.js").then(result => {

});

// Load and add the prefix asynchronously with promises:
myOperation.errback("./some-file.js", (err, result) => {

});
```

This could even be exposed as your official API by doing
```js
// Using the common 'Sync' suffix for sync functions, and 'Async' suffix for
// promise-returning versions.
exports.myOperationSync = myOperation.sync;
exports.myOperationAsync = myOperation.async;
exports.myOperation = myOperation.errback;
```
or potentially expose one of the async versions as the default, with a
`.sync` property on the function to expose the synchronous version.
```js
module.exports = myOperation.errback;
module.exports.sync = myOperation.sync;
````


## API

### gensync(generatorFnOrOptions)

Returns a function that can be "await"-ed in another `gensync` generator
function, or executed via

* `.sync(...args)` - Returns the computed value, or throws.
* `.async(...args)` - Returns a promise for the computed value.
* `.errback(...args, (err, result) => {})` - Calls the callback with the computed value, or error.


#### Passed a generator

Wraps the generator to populate the `.sync`/`.async`/`.errback` helpers above to
allow for evaluation of the generator for the final value.

##### Example

```js
const readFile = function* () {
  return 42;
};

const readFileAndMore = gensync(function* (){
  const val = yield* readFile();
  return 42 + val;
});

// In general cases
const code = readFileAndMore.sync("./file.js", "utf8");
readFileAndMore.async("./file.js", "utf8").then(code => {})
readFileAndMore.errback("./file.js", "utf8", (err, code) => {});

// In a generator being called indirectly with .sync/.async/.errback
const code = yield* readFileAndMore("./file.js", "utf8");
```


#### Passed an options object

* `opts.sync`

  Example: `(...args) => 4`

  A function that will be called when `.sync()` is called on the `gensync()`
  result, or when the result is passed to `yield*` in another generator that
  is being run synchronously.

  Also called for `.async()` calls if no async handlers are provided.

* `opts.async`

  Example: `async (...args) => 4`

  A function that will be called when `.async()` or `.errback()` is called on
  the `gensync()` result, or when the result is passed to `yield*` in another
  generator that is being run asynchronously.

* `opts.errback`

  Example: `(...args, cb) => cb(null, 4)`

  A function that will be called when `.async()` or `.errback()` is called on
  the `gensync()` result, or when the result is passed to `yield*` in another
  generator that is being run asynchronously.

  This option allows for simpler compatibility with many existing Node APIs,
  and also avoids introducing the extra even loop turns that promises introduce
  to access the result value.

* `opts.name`

  Example: `"readFile"`

  A string name to apply to the returned function. If no value is provided,
  the name of `errback`/`async`/`sync` functions will be used, with any
  `Sync` or `Async` suffix stripped off. If the callback is simply named
  with ES6 inference (same name as the options property), the name is ignored.

* `opts.arity`

  Example: `4`

  A number for the length to set on the returned function. If no value
  is provided, the length will be carried over from the `sync` function's
  `length` value.

##### Example

```js
const readFile = gensync({
  sync: fs.readFileSync,
  errback: fs.readFile,
});

const code = readFile.sync("./file.js", "utf8");
readFile.async("./file.js", "utf8").then(code => {})
readFile.errback("./file.js", "utf8", (err, code) => {});
```


### gensync.all(iterable)

`Promise.all`-like combinator that works with an iterable of generator objects
that could be passed to `yield*` within a gensync generator.

#### Example

```js
const loadFiles = gensync(function* () {
  return yield* gensync.all([
    readFile("./one.js"),
    readFile("./two.js"),
    readFile("./three.js"),
  ]);
});
```


### gensync.race(iterable)

`Promise.race`-like combinator that works with an iterable of generator objects
that could be passed to `yield*` within a gensync generator.

#### Example

```js
const loadFiles = gensync(function* () {
  return yield* gensync.race([
    readFile("./one.js"),
    readFile("./two.js"),
    readFile("./three.js"),
  ]);
});
```


---

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [v1.3.0](https://github.com/ljharb/get-intrinsic/compare/v1.2.7...v1.3.0) - 2025-02-22

### Commits

- [Dev Deps] update `es-abstract`, `es-value-fixtures`, `for-each`, `object-inspect` [`9b61553`](https://github.com/ljharb/get-intrinsic/commit/9b61553c587f1c1edbd435597e88c7d387da97dd)
- [Deps] update `call-bind-apply-helpers`, `es-object-atoms`, `get-proto` [`a341fee`](https://github.com/ljharb/get-intrinsic/commit/a341fee0f39a403b0f0069e82c97642d5eb11043)
- [New] add `Float16Array` [`de22116`](https://github.com/ljharb/get-intrinsic/commit/de22116b492fb989a0341bceb6e573abfaed73dc)

## [v1.2.7](https://github.com/ljharb/get-intrinsic/compare/v1.2.6...v1.2.7) - 2025-01-02

### Commits

- [Refactor] use `get-proto` directly [`00ab955`](https://github.com/ljharb/get-intrinsic/commit/00ab95546a0980c8ad42a84253daaa8d2adcedf9)
- [Deps] update `math-intrinsics` [`c716cdd`](https://github.com/ljharb/get-intrinsic/commit/c716cdd6bbe36b438057025561b8bb5a879ac8a0)
- [Dev Deps] update `call-bound`, `es-abstract` [`dc648a6`](https://github.com/ljharb/get-intrinsic/commit/dc648a67eb359037dff8d8619bfa71d86debccb1)

## [v1.2.6](https://github.com/ljharb/get-intrinsic/compare/v1.2.5...v1.2.6) - 2024-12-11

### Commits

- [Refactor] use `math-intrinsics` [`841be86`](https://github.com/ljharb/get-intrinsic/commit/841be8641a9254c4c75483b30c8871b5d5065926)
- [Refactor] use `es-object-atoms` [`42057df`](https://github.com/ljharb/get-intrinsic/commit/42057dfa16f66f64787e66482af381cc6f31d2c1)
- [Deps] update `call-bind-apply-helpers` [`45afa24`](https://github.com/ljharb/get-intrinsic/commit/45afa24a9ee4d6d3c172db1f555b16cb27843ef4)
- [Dev Deps] update `call-bound` [`9cba9c6`](https://github.com/ljharb/get-intrinsic/commit/9cba9c6e70212bc163b7a5529cb25df46071646f)

## [v1.2.5](https://github.com/ljharb/get-intrinsic/compare/v1.2.4...v1.2.5) - 2024-12-06

### Commits

- [actions] split out node 10-20, and 20+ [`6e2b9dd`](https://github.com/ljharb/get-intrinsic/commit/6e2b9dd23902665681ebe453256ccfe21d7966f0)
- [Refactor] use `dunder-proto` and `call-bind-apply-helpers` instead of `has-proto` [`c095d17`](https://github.com/ljharb/get-intrinsic/commit/c095d179ad0f4fbfff20c8a3e0cb4fe668018998)
- [Refactor] use `gopd` [`9841d5b`](https://github.com/ljharb/get-intrinsic/commit/9841d5b35f7ab4fd2d193f0c741a50a077920e90)
- [Dev Deps] update `@ljharb/eslint-config`, `auto-changelog`, `es-abstract`, `es-value-fixtures`, `gopd`, `mock-property`, `object-inspect`, `tape` [`2d07e01`](https://github.com/ljharb/get-intrinsic/commit/2d07e01310cee2cbaedfead6903df128b1f5d425)
- [Deps] update `gopd`, `has-proto`, `has-symbols`, `hasown` [`974d8bf`](https://github.com/ljharb/get-intrinsic/commit/974d8bf5baad7939eef35c25cc1dd88c10a30fa6)
- [Dev Deps] update `call-bind`, `es-abstract`, `tape` [`df9dde1`](https://github.com/ljharb/get-intrinsic/commit/df9dde178186631ab8a3165ede056549918ce4bc)
- [Refactor] cache `es-define-property` as well [`43ef543`](https://github.com/ljharb/get-intrinsic/commit/43ef543cb02194401420e3a914a4ca9168691926)
- [Deps] update `has-proto`, `has-symbols`, `hasown` [`ad4949d`](https://github.com/ljharb/get-intrinsic/commit/ad4949d5467316505aad89bf75f9417ed782f7af)
- [Tests] use `call-bound` directly [`ad5c406`](https://github.com/ljharb/get-intrinsic/commit/ad5c4069774bfe90e520a35eead5fe5ca9d69e80)
- [Deps] update `has-proto`, `hasown` [`45414ca`](https://github.com/ljharb/get-intrinsic/commit/45414caa312333a2798953682c68f85c550627dd)
- [Tests] replace `aud` with `npm audit` [`18d3509`](https://github.com/ljharb/get-intrinsic/commit/18d3509f79460e7924da70409ee81e5053087523)
- [Deps] update `es-define-property` [`aadaa3b`](https://github.com/ljharb/get-intrinsic/commit/aadaa3b2188d77ad9bff394ce5d4249c49eb21f5)
- [Dev Deps] add missing peer dep [`c296a16`](https://github.com/ljharb/get-intrinsic/commit/c296a16246d0c9a5981944f4cc5cf61fbda0cf6a)

## [v1.2.4](https://github.com/ljharb/get-intrinsic/compare/v1.2.3...v1.2.4) - 2024-02-05

### Commits

- [Refactor] use all 7 &lt;+ ES6 Errors from `es-errors` [`bcac811`](https://github.com/ljharb/get-intrinsic/commit/bcac811abdc1c982e12abf848a410d6aae148d14)

## [v1.2.3](https://github.com/ljharb/get-intrinsic/compare/v1.2.2...v1.2.3) - 2024-02-03

### Commits

- [Refactor] use `es-errors`, so things that only need those do not need `get-intrinsic` [`f11db9c`](https://github.com/ljharb/get-intrinsic/commit/f11db9c4fb97d87bbd53d3c73ac6b3db3613ad3b)
- [Dev Deps] update `aud`, `es-abstract`, `mock-property`, `npmignore` [`b7ac7d1`](https://github.com/ljharb/get-intrinsic/commit/b7ac7d1616fefb03877b1aed0c8f8d61aad32b6c)
- [meta] simplify `exports` [`faa0cc6`](https://github.com/ljharb/get-intrinsic/commit/faa0cc618e2830ffb51a8202490b0c215d965cbc)
- [meta] add missing `engines.node` [`774dd0b`](https://github.com/ljharb/get-intrinsic/commit/774dd0b3e8f741c3f05a6322d124d6087f146af1)
- [Dev Deps] update `tape` [`5828e8e`](https://github.com/ljharb/get-intrinsic/commit/5828e8e4a04e69312e87a36c0ea39428a7a4c3d8)
- [Robustness] use null objects for lookups [`eb9a11f`](https://github.com/ljharb/get-intrinsic/commit/eb9a11fa9eb3e13b193fcc05a7fb814341b1a7b7)
- [meta] add `sideEffects` flag [`89bcc7a`](https://github.com/ljharb/get-intrinsic/commit/89bcc7a42e19bf07b7c21e3094d5ab177109e6d2)

## [v1.2.2](https://github.com/ljharb/get-intrinsic/compare/v1.2.1...v1.2.2) - 2023-10-20

### Commits

- [Dev Deps] update `@ljharb/eslint-config`, `aud`, `call-bind`, `es-abstract`, `mock-property`, `object-inspect`, `tape` [`f51bcf2`](https://github.com/ljharb/get-intrinsic/commit/f51bcf26412d58d17ce17c91c9afd0ad271f0762)
- [Refactor] use `hasown` instead of `has` [`18d14b7`](https://github.com/ljharb/get-intrinsic/commit/18d14b799bea6b5765e1cec91890830cbcdb0587)
- [Deps] update `function-bind` [`6e109c8`](https://github.com/ljharb/get-intrinsic/commit/6e109c81e03804cc5e7824fb64353cdc3d8ee2c7)

## [v1.2.1](https://github.com/ljharb/get-intrinsic/compare/v1.2.0...v1.2.1) - 2023-05-13

### Commits

- [Fix] avoid a crash in envs without `__proto__` [`7bad8d0`](https://github.com/ljharb/get-intrinsic/commit/7bad8d061bf8721733b58b73a2565af2b6756b64)
- [Dev Deps] update `es-abstract` [`c60e6b7`](https://github.com/ljharb/get-intrinsic/commit/c60e6b7b4cf9660c7f27ed970970fd55fac48dc5)

## [v1.2.0](https://github.com/ljharb/get-intrinsic/compare/v1.1.3...v1.2.0) - 2023-01-19

### Commits

- [actions] update checkout action [`ca6b12f`](https://github.com/ljharb/get-intrinsic/commit/ca6b12f31eaacea4ea3b055e744cd61623385ffb)
- [Dev Deps] update `@ljharb/eslint-config`, `es-abstract`, `object-inspect`, `tape` [`41a3727`](https://github.com/ljharb/get-intrinsic/commit/41a3727d0026fa04273ae216a5f8e12eefd72da8)
- [Fix] ensure `Error.prototype` is undeniable [`c511e97`](https://github.com/ljharb/get-intrinsic/commit/c511e97ae99c764c4524b540dee7a70757af8da3)
- [Dev Deps] update `aud`, `es-abstract`, `tape` [`1bef8a8`](https://github.com/ljharb/get-intrinsic/commit/1bef8a8fd439ebb80863199b6189199e0851ac67)
- [Dev Deps] update `aud`, `es-abstract` [`0d41f16`](https://github.com/ljharb/get-intrinsic/commit/0d41f16bcd500bc28b7bfc98043ebf61ea081c26)
- [New] add `BigInt64Array` and `BigUint64Array` [`a6cca25`](https://github.com/ljharb/get-intrinsic/commit/a6cca25f29635889b7e9bd669baf9e04be90e48c)
- [Tests] use `gopd` [`ecf7722`](https://github.com/ljharb/get-intrinsic/commit/ecf7722240d15cfd16edda06acf63359c10fb9bd)

## [v1.1.3](https://github.com/ljharb/get-intrinsic/compare/v1.1.2...v1.1.3) - 2022-09-12

### Commits

- [Dev Deps] update `es-abstract`, `es-value-fixtures`, `tape` [`07ff291`](https://github.com/ljharb/get-intrinsic/commit/07ff291816406ebe5a12d7f16965bde0942dd688)
- [Fix] properly check for % signs [`50ac176`](https://github.com/ljharb/get-intrinsic/commit/50ac1760fe99c227e64eabde76e9c0e44cd881b5)

## [v1.1.2](https://github.com/ljharb/get-intrinsic/compare/v1.1.1...v1.1.2) - 2022-06-08

### Fixed

- [Fix] properly validate against extra % signs [`#16`](https://github.com/ljharb/get-intrinsic/issues/16)

### Commits

- [actions] reuse common workflows [`0972547`](https://github.com/ljharb/get-intrinsic/commit/0972547efd0abc863fe4c445a6ca7eb4f8c6901d)
- [meta] use `npmignore` to autogenerate an npmignore file [`5ba0b51`](https://github.com/ljharb/get-intrinsic/commit/5ba0b51d8d8d4f1c31d426d74abc0770fd106bad)
- [actions] use `node/install` instead of `node/run`; use `codecov` action [`c364492`](https://github.com/ljharb/get-intrinsic/commit/c364492af4af51333e6f81c0bf21fd3d602c3661)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `aud`, `auto-changelog`, `es-abstract`, `object-inspect`, `tape` [`dc04dad`](https://github.com/ljharb/get-intrinsic/commit/dc04dad86f6e5608775a2640cb0db5927ae29ed9)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `es-abstract`, `object-inspect`, `safe-publish-latest`, `tape` [`1c14059`](https://github.com/ljharb/get-intrinsic/commit/1c1405984e86dd2dc9366c15d8a0294a96a146a5)
- [Tests] use `mock-property` [`b396ef0`](https://github.com/ljharb/get-intrinsic/commit/b396ef05bb73b1d699811abd64b0d9b97997fdda)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `aud`, `auto-changelog`, `object-inspect`, `tape` [`c2c758d`](https://github.com/ljharb/get-intrinsic/commit/c2c758d3b90af4fef0a76910d8d3c292ec8d1d3e)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `aud`, `es-abstract`, `es-value-fixtures`, `object-inspect`, `tape` [`29e3c09`](https://github.com/ljharb/get-intrinsic/commit/29e3c091c2bf3e17099969847e8729d0e46896de)
- [actions] update codecov uploader [`8cbc141`](https://github.com/ljharb/get-intrinsic/commit/8cbc1418940d7a8941f3a7985cbc4ac095c5e13d)
- [Dev Deps] update `@ljharb/eslint-config`, `es-abstract`, `es-value-fixtures`, `object-inspect`, `tape` [`10b6f5c`](https://github.com/ljharb/get-intrinsic/commit/10b6f5c02593fb3680c581d696ac124e30652932)
- [readme] add github actions/codecov badges [`4e25400`](https://github.com/ljharb/get-intrinsic/commit/4e25400d9f51ae9eb059cbe22d9144e70ea214e8)
- [Tests] use `for-each` instead of `foreach` [`c05b957`](https://github.com/ljharb/get-intrinsic/commit/c05b957ad9a7bc7721af7cc9e9be1edbfe057496)
- [Dev Deps] update `es-abstract` [`29b05ae`](https://github.com/ljharb/get-intrinsic/commit/29b05aec3e7330e9ad0b8e0f685a9112c20cdd97)
- [meta] use `prepublishOnly` script for npm 7+ [`95c285d`](https://github.com/ljharb/get-intrinsic/commit/95c285da810516057d3bbfa871176031af38f05d)
- [Deps] update `has-symbols` [`593cb4f`](https://github.com/ljharb/get-intrinsic/commit/593cb4fb38e7922e40e42c183f45274b636424cd)
- [readme] fix repo URLs [`1c8305b`](https://github.com/ljharb/get-intrinsic/commit/1c8305b5365827c9b6fc785434aac0e1328ff2f5)
- [Deps] update `has-symbols` [`c7138b6`](https://github.com/ljharb/get-intrinsic/commit/c7138b6c6d73132d859471fb8c13304e1e7c8b20)
- [Dev Deps] remove unused `has-bigints` [`bd63aff`](https://github.com/ljharb/get-intrinsic/commit/bd63aff6ad8f3a986c557fcda2914187bdaab359)

## [v1.1.1](https://github.com/ljharb/get-intrinsic/compare/v1.1.0...v1.1.1) - 2021-02-03

### Fixed

- [meta] export `./package.json` [`#9`](https://github.com/ljharb/get-intrinsic/issues/9)

### Commits

- [readme] flesh out the readme; use `evalmd` [`d12f12c`](https://github.com/ljharb/get-intrinsic/commit/d12f12c15345a0a0772cc65a7c64369529abd614)
- [eslint] set up proper globals config [`5a8c098`](https://github.com/ljharb/get-intrinsic/commit/5a8c0984e3319d1ac0e64b102f8ec18b64e79f36)
- [Dev Deps] update `eslint` [`7b9a5c0`](https://github.com/ljharb/get-intrinsic/commit/7b9a5c0d31a90ca1a1234181c74988fb046701cd)

## [v1.1.0](https://github.com/ljharb/get-intrinsic/compare/v1.0.2...v1.1.0) - 2021-01-25

### Fixed

- [Refactor] delay `Function` eval until syntax-derived values are requested [`#3`](https://github.com/ljharb/get-intrinsic/issues/3)

### Commits

- [Tests] migrate tests to Github Actions [`2ab762b`](https://github.com/ljharb/get-intrinsic/commit/2ab762b48164aea8af37a40ba105bbc8246ab8c4)
- [meta] do not publish github action workflow files [`5e7108e`](https://github.com/ljharb/get-intrinsic/commit/5e7108e4768b244d48d9567ba4f8a6cab9c65b8e)
- [Tests] add some coverage [`01ac7a8`](https://github.com/ljharb/get-intrinsic/commit/01ac7a87ac29738567e8524cd8c9e026b1fa8cb3)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `call-bind`, `es-abstract`, `tape`; add `call-bind` [`911b672`](https://github.com/ljharb/get-intrinsic/commit/911b672fbffae433a96924c6ce013585e425f4b7)
- [Refactor] rearrange evalled constructors a bit [`7e7e4bf`](https://github.com/ljharb/get-intrinsic/commit/7e7e4bf583f3799c8ac1c6c5e10d2cb553957347)
- [meta] add Automatic Rebase and Require Allow Edits workflows [`0199968`](https://github.com/ljharb/get-intrinsic/commit/01999687a263ffce0a3cb011dfbcb761754aedbc)

## [v1.0.2](https://github.com/ljharb/get-intrinsic/compare/v1.0.1...v1.0.2) - 2020-12-17

### Commits

- [Fix] Throw for non‑existent intrinsics [`68f873b`](https://github.com/ljharb/get-intrinsic/commit/68f873b013c732a05ad6f5fc54f697e55515461b)
- [Fix] Throw for non‑existent segments in the intrinsic path [`8325dee`](https://github.com/ljharb/get-intrinsic/commit/8325deee43128f3654d3399aa9591741ebe17b21)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `aud`, `has-bigints`, `object-inspect` [`0c227a7`](https://github.com/ljharb/get-intrinsic/commit/0c227a7d8b629166f25715fd242553892e458525)
- [meta] do not lint coverage output [`70d2419`](https://github.com/ljharb/get-intrinsic/commit/70d24199b620043cd9110fc5f426d214ebe21dc9)

## [v1.0.1](https://github.com/ljharb/get-intrinsic/compare/v1.0.0...v1.0.1) - 2020-10-30

### Commits

- [Tests] gather coverage data on every job [`d1d280d`](https://github.com/ljharb/get-intrinsic/commit/d1d280dec714e3f0519cc877dbcb193057d9cac6)
- [Fix] add missing dependencies [`5031771`](https://github.com/ljharb/get-intrinsic/commit/5031771bb1095b38be88ce7c41d5de88718e432e)
- [Tests] use `es-value-fixtures` [`af48765`](https://github.com/ljharb/get-intrinsic/commit/af48765a23c5323fb0b6b38dbf00eb5099c7bebc)

## v1.0.0 - 2020-10-29

### Commits

- Implementation [`bbce57c`](https://github.com/ljharb/get-intrinsic/commit/bbce57c6f33d05b2d8d3efa273ceeb3ee01127bb)
- Tests [`17b4f0d`](https://github.com/ljharb/get-intrinsic/commit/17b4f0d56dea6b4059b56fc30ef3ee4d9500ebc2)
- Initial commit [`3153294`](https://github.com/ljharb/get-intrinsic/commit/31532948de363b0a27dd9fd4649e7b7028ec4b44)
- npm init [`fb326c4`](https://github.com/ljharb/get-intrinsic/commit/fb326c4d2817c8419ec31de1295f06bb268a7902)
- [meta] add Automatic Rebase and Require Allow Edits workflows [`48862fb`](https://github.com/ljharb/get-intrinsic/commit/48862fb2508c8f6a57968e6d08b7c883afc9d550)
- [meta] add `auto-changelog` [`5f28ad0`](https://github.com/ljharb/get-intrinsic/commit/5f28ad019e060a353d8028f9f2591a9cc93074a1)
- [meta] add "funding"; create `FUNDING.yml` [`c2bbdde`](https://github.com/ljharb/get-intrinsic/commit/c2bbddeba73a875be61484ee4680b129a6d4e0a1)
- [Tests] add `npm run lint` [`0a84b98`](https://github.com/ljharb/get-intrinsic/commit/0a84b98b22b7cf7a748666f705b0003a493c35fd)
- Only apps should have lockfiles [`9586c75`](https://github.com/ljharb/get-intrinsic/commit/9586c75866c1ee678e4d5d4dbbdef6997e511b05)


---

# get-intrinsic <sup>[![Version Badge][npm-version-svg]][package-url]</sup>

[![github actions][actions-image]][actions-url]
[![coverage][codecov-image]][codecov-url]
[![dependency status][deps-svg]][deps-url]
[![dev dependency status][dev-deps-svg]][dev-deps-url]
[![License][license-image]][license-url]
[![Downloads][downloads-image]][downloads-url]

[![npm badge][npm-badge-png]][package-url]

Get and robustly cache all JS language-level intrinsics at first require time.

See the syntax described [in the JS spec](https://tc39.es/ecma262/#sec-well-known-intrinsic-objects) for reference.

## Example

```js
var GetIntrinsic = require('get-intrinsic');
var assert = require('assert');

// static methods
assert.equal(GetIntrinsic('%Math.pow%'), Math.pow);
assert.equal(Math.pow(2, 3), 8);
assert.equal(GetIntrinsic('%Math.pow%')(2, 3), 8);
delete Math.pow;
assert.equal(GetIntrinsic('%Math.pow%')(2, 3), 8);

// instance methods
var arr = [1];
assert.equal(GetIntrinsic('%Array.prototype.push%'), Array.prototype.push);
assert.deepEqual(arr, [1]);

arr.push(2);
assert.deepEqual(arr, [1, 2]);

GetIntrinsic('%Array.prototype.push%').call(arr, 3);
assert.deepEqual(arr, [1, 2, 3]);

delete Array.prototype.push;
GetIntrinsic('%Array.prototype.push%').call(arr, 4);
assert.deepEqual(arr, [1, 2, 3, 4]);

// missing features
delete JSON.parse; // to simulate a real intrinsic that is missing in the environment
assert.throws(() => GetIntrinsic('%JSON.parse%'));
assert.equal(undefined, GetIntrinsic('%JSON.parse%', true));
```

## Tests
Simply clone the repo, `npm install`, and run `npm test`

## Security

Please email [@ljharb](https://github.com/ljharb) or see https://tidelift.com/security if you have a potential security vulnerability to report.

[package-url]: https://npmjs.org/package/get-intrinsic
[npm-version-svg]: https://versionbadg.es/ljharb/get-intrinsic.svg
[deps-svg]: https://david-dm.org/ljharb/get-intrinsic.svg
[deps-url]: https://david-dm.org/ljharb/get-intrinsic
[dev-deps-svg]: https://david-dm.org/ljharb/get-intrinsic/dev-status.svg
[dev-deps-url]: https://david-dm.org/ljharb/get-intrinsic#info=devDependencies
[npm-badge-png]: https://nodei.co/npm/get-intrinsic.png?downloads=true&stars=true
[license-image]: https://img.shields.io/npm/l/get-intrinsic.svg
[license-url]: LICENSE
[downloads-image]: https://img.shields.io/npm/dm/get-intrinsic.svg
[downloads-url]: https://npm-stat.com/charts.html?package=get-intrinsic
[codecov-image]: https://codecov.io/gh/ljharb/get-intrinsic/branch/main/graphs/badge.svg
[codecov-url]: https://app.codecov.io/gh/ljharb/get-intrinsic/
[actions-image]: https://img.shields.io/endpoint?url=https://github-actions-badge-u3jn4tfpocch.runkit.sh/ljharb/get-intrinsic
[actions-url]: https://github.com/ljharb/get-intrinsic/actions


---

# Changelog

All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.

### [3.0.2](https://github.com/mightyiam/get-own-enumerable-property-symbols/compare/v3.0.1...v3.0.2) (2019-12-10)


### Bug Fixes

* add missing license file ([dbf11c2](https://github.com/mightyiam/get-own-enumerable-property-symbols/commit/dbf11c2b705dcfb42d6ac291f6608adb14ed6fd3)), closes [#87](https://github.com/mightyiam/get-own-enumerable-property-symbols/issues/87)

### [3.0.1](https://github.com/mightyiam/get-own-enumerable-property-symbols/compare/v3.0.0...v3.0.1) (2019-10-04)


---

# get-own-enumerable-property-symbols [![Build Status](https://travis-ci.org/mightyiam/get-own-enumerable-property-symbols.svg?branch=master)](https://travis-ci.org/mightyiam/get-own-enumerable-property-symbols)

Returns an array of all *enumerable* symbol properties found directly upon a given object.

Similar to [`Object.getOwnPropertySymbols`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/getOwnPropertySymbols)
but only [enumerable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Enumerability_and_ownership_of_properties) keys.

```js
import getOwnEnumPropSymbols from 'get-own-enumerable-property-symbols'

getOwnEnumPropSymbols({ [Symbol()]: undefined })
// [Symbol()]
getOwnEnumPropSymbols(Object.defineProperty({}, Symbol(), {enumerable: false}))
// []
```


---

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [v1.0.1](https://github.com/ljharb/get-proto/compare/v1.0.0...v1.0.1) - 2025-01-02

### Commits

- [Fix] for the `Object.getPrototypeOf` window, throw for non-objects [`7fe6508`](https://github.com/ljharb/get-proto/commit/7fe6508b71419ebe1976bedb86001d1feaeaa49a)

## v1.0.0 - 2025-01-01

### Commits

- Initial implementation, tests, readme, types [`5c70775`](https://github.com/ljharb/get-proto/commit/5c707751e81c3deeb2cf980d185fc7fd43611415)
- Initial commit [`7c65c2a`](https://github.com/ljharb/get-proto/commit/7c65c2ad4e33d5dae2f219ebe1a046ae2256972c)
- npm init [`0b8cf82`](https://github.com/ljharb/get-proto/commit/0b8cf824c9634e4a34ef7dd2a2cdc5be6ac79518)
- Only apps should have lockfiles [`a6d1bff`](https://github.com/ljharb/get-proto/commit/a6d1bffc364f5828377cea7194558b2dbef7aea2)


---

# get-proto <sup>[![Version Badge][npm-version-svg]][package-url]</sup>

[![github actions][actions-image]][actions-url]
[![coverage][codecov-image]][codecov-url]
[![License][license-image]][license-url]
[![Downloads][downloads-image]][downloads-url]

[![npm badge][npm-badge-png]][package-url]

Robustly get the [[Prototype]] of an object. Uses the best available method.

## Getting started

```sh
npm install --save get-proto
```

## Usage/Examples

```js
const assert = require('assert');
const getProto = require('get-proto');

const a = { a: 1, b: 2, [Symbol.toStringTag]: 'foo' };
const b = { c: 3, __proto__: a };

assert.equal(getProto(b), a);
assert.equal(getProto(a), Object.prototype);
assert.equal(getProto({ __proto__: null }), null);
```

## Tests

Clone the repo, `npm install`, and run `npm test`

[package-url]: https://npmjs.org/package/get-proto
[npm-version-svg]: https://versionbadg.es/ljharb/get-proto.svg
[deps-svg]: https://david-dm.org/ljharb/get-proto.svg
[deps-url]: https://david-dm.org/ljharb/get-proto
[dev-deps-svg]: https://david-dm.org/ljharb/get-proto/dev-status.svg
[dev-deps-url]: https://david-dm.org/ljharb/get-proto#info=devDependencies
[npm-badge-png]: https://nodei.co/npm/get-proto.png?downloads=true&stars=true
[license-image]: https://img.shields.io/npm/l/get-proto.svg
[license-url]: LICENSE
[downloads-image]: https://img.shields.io/npm/dm/get-proto.svg
[downloads-url]: https://npm-stat.com/charts.html?package=get-proto
[codecov-image]: https://codecov.io/gh/ljharb/get-proto/branch/main/graphs/badge.svg
[codecov-url]: https://app.codecov.io/gh/ljharb/get-proto/
[actions-image]: https://img.shields.io/endpoint?url=https://github-actions-badge-u3jn4tfpocch.runkit.sh/ljharb/get-proto
[actions-url]: https://github.com/ljharb/get-proto/actions


---

# get-stream

> Get a stream as a string, buffer, or array

## Install

```
$ npm install get-stream
```

## Usage

```js
const fs = require('fs');
const getStream = require('get-stream');

(async () => {
	const stream = fs.createReadStream('unicorn.txt');

	console.log(await getStream(stream));
	/*
	              ,,))))))));,
	           __)))))))))))))),
	\|/       -\(((((''''((((((((.
	-*-==//////((''  .     `)))))),
	/|\      ))| o    ;-.    '(((((                                  ,(,
	         ( `|    /  )    ;))))'                               ,_))^;(~
	            |   |   |   ,))((((_     _____------~~~-.        %,;(;(>';'~
	            o_);   ;    )))(((` ~---~  `::           \      %%~~)(v;(`('~
	                  ;    ''''````         `:       `:::|\,__,%%    );`'; ~
	                 |   _                )     /      `:|`----'     `-'
	           ______/\/~    |                 /        /
	         /~;;.____/;;'  /          ___--,-(   `;;;/
	        / //  _;______;'------~~~~~    /;;/\    /
	       //  | |                        / ;   \;;,\
	      (<_  | ;                      /',/-----'  _>
	       \_| ||_                     //~;~~~~~~~~~
	           `\_|                   (,~~
	                                   \~\
	                                    ~~
	*/
})();
```

## API

The methods returns a promise that resolves when the `end` event fires on the stream, indicating that there is no more data to be read. The stream is switched to flowing mode.

### getStream(stream, options?)

Get the `stream` as a string.

#### options

Type: `object`

##### encoding

Type: `string`\
Default: `'utf8'`

[Encoding](https://nodejs.org/api/buffer.html#buffer_buffer) of the incoming stream.

##### maxBuffer

Type: `number`\
Default: `Infinity`

Maximum length of the returned string. If it exceeds this value before the stream ends, the promise will be rejected with a `getStream.MaxBufferError` error.

### getStream.buffer(stream, options?)

Get the `stream` as a buffer.

It honors the `maxBuffer` option as above, but it refers to byte length rather than string length.

### getStream.array(stream, options?)

Get the `stream` as an array of values.

It honors both the `maxBuffer` and `encoding` options. The behavior changes slightly based on the encoding chosen:

- When `encoding` is unset, it assumes an [object mode stream](https://nodesource.com/blog/understanding-object-streams/) and collects values emitted from `stream` unmodified. In this case `maxBuffer` refers to the number of items in the array (not the sum of their sizes).

- When `encoding` is set to `buffer`, it collects an array of buffers. `maxBuffer` refers to the summed byte lengths of every buffer in the array.

- When `encoding` is set to anything else, it collects an array of strings. `maxBuffer` refers to the summed character lengths of every string in the array.

## Errors

If the input stream emits an `error` event, the promise will be rejected with the error. The buffered data will be attached to the `bufferedData` property of the error.

```js
(async () => {
	try {
		await getStream(streamThatErrorsAtTheEnd('unicorn'));
	} catch (error) {
		console.log(error.bufferedData);
		//=> 'unicorn'
	}
})()
```

## FAQ

### How is this different from [`concat-stream`](https://github.com/maxogden/concat-stream)?

This module accepts a stream instead of being one and returns a promise instead of using a callback. The API is simpler and it only supports returning a string, buffer, or array. It doesn't have a fragile type inference. You explicitly choose what you want. And it doesn't depend on the huge `readable-stream` package.

## Related

- [get-stdin](https://github.com/sindresorhus/get-stdin) - Get stdin as a string or buffer

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-get-stream?utm_source=npm-get-stream&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

# github-slugger

[![npm][npm-image]][npm-url]
[![Build][build-badge]][build]

[npm-image]: https://img.shields.io/npm/v/github-slugger.svg?style=flat-square
[npm-url]: https://www.npmjs.com/package/github-slugger
[build-badge]: https://github.com/Flet/github-slugger/workflows/main/badge.svg
[build]: https://github.com/Flet/github-slugger/actions

Generate a slug just like GitHub does for markdown headings. It also ensures slugs are unique in the same way GitHub does it. The overall goal of this package is to emulate the way GitHub handles generating markdown heading anchors as close as possible.

This project is not a Markdown or HTML parser: passing `alpha *bravo* charlie`
or `alpha <em>bravo</em> charlie` doesn’t work.
Instead pass the plain text value of the heading: `alpha bravo charlie`.

## Install

```
npm install github-slugger
```

## Usage

```js
var GithubSlugger = require('github-slugger')
var slugger = new GithubSlugger()

slugger.slug('foo')
// returns 'foo'

slugger.slug('foo')
// returns 'foo-1'

slugger.slug('bar')
// returns 'bar'

slugger.slug('foo')
// returns 'foo-2'

slugger.slug('Привет non-latin 你好')
// returns 'привет-non-latin-你好'

slugger.slug('😄 emoji')
// returns '-emoji'

slugger.reset()

slugger.slug('foo')
// returns 'foo'
```

Check `test/fixtures.json` for more examples.

If you need, you can also use the underlying implementation which does not keep
track of the previously slugged strings (not recommended):

```js
var slug = require('github-slugger').slug;

slug('foo bar baz')
// returns 'foo-bar-baz'

slug('foo bar baz')
// returns the same slug 'foo-bar-baz' because it does not keep track
```

## Contributing

Contributions welcome! Please read the [contributing guidelines](CONTRIBUTING.md) first.

## License

[ISC](LICENSE)


---

# Glob

Match files using the patterns the shell uses, like stars and stuff.

[![Build Status](https://travis-ci.org/isaacs/node-glob.svg?branch=master)](https://travis-ci.org/isaacs/node-glob/) [![Build Status](https://ci.appveyor.com/api/projects/status/kd7f3yftf7unxlsx?svg=true)](https://ci.appveyor.com/project/isaacs/node-glob) [![Coverage Status](https://coveralls.io/repos/isaacs/node-glob/badge.svg?branch=master&service=github)](https://coveralls.io/github/isaacs/node-glob?branch=master)

This is a glob implementation in JavaScript.  It uses the `minimatch`
library to do its matching.

![a fun cartoon logo made of glob characters](logo/glob.png)

## Usage

Install with npm

```
npm i glob
```

```javascript
var glob = require("glob")

// options is optional
glob("**/*.js", options, function (er, files) {
  // files is an array of filenames.
  // If the `nonull` option is set, and nothing
  // was found, then files is ["**/*.js"]
  // er is an error object or null.
})
```

## Glob Primer

"Globs" are the patterns you type when you do stuff like `ls *.js` on
the command line, or put `build/*` in a `.gitignore` file.

Before parsing the path part patterns, braced sections are expanded
into a set.  Braced sections start with `{` and end with `}`, with any
number of comma-delimited sections within.  Braced sections may contain
slash characters, so `a{/b/c,bcd}` would expand into `a/b/c` and `abcd`.

The following characters have special magic meaning when used in a
path portion:

* `*` Matches 0 or more characters in a single path portion
* `?` Matches 1 character
* `[...]` Matches a range of characters, similar to a RegExp range.
  If the first character of the range is `!` or `^` then it matches
  any character not in the range.
* `!(pattern|pattern|pattern)` Matches anything that does not match
  any of the patterns provided.
* `?(pattern|pattern|pattern)` Matches zero or one occurrence of the
  patterns provided.
* `+(pattern|pattern|pattern)` Matches one or more occurrences of the
  patterns provided.
* `*(a|b|c)` Matches zero or more occurrences of the patterns provided
* `@(pattern|pat*|pat?erN)` Matches exactly one of the patterns
  provided
* `**` If a "globstar" is alone in a path portion, then it matches
  zero or more directories and subdirectories searching for matches.
  It does not crawl symlinked directories.

### Dots

If a file or directory path portion has a `.` as the first character,
then it will not match any glob pattern unless that pattern's
corresponding path part also has a `.` as its first character.

For example, the pattern `a/.*/c` would match the file at `a/.b/c`.
However the pattern `a/*/c` would not, because `*` does not start with
a dot character.

You can make glob treat dots as normal characters by setting
`dot:true` in the options.

### Basename Matching

If you set `matchBase:true` in the options, and the pattern has no
slashes in it, then it will seek for any file anywhere in the tree
with a matching basename.  For example, `*.js` would match
`test/simple/basic.js`.

### Empty Sets

If no matching files are found, then an empty array is returned.  This
differs from the shell, where the pattern itself is returned.  For
example:

    $ echo a*s*d*f
    a*s*d*f

To get the bash-style behavior, set the `nonull:true` in the options.

### See Also:

* `man sh`
* `man bash` (Search for "Pattern Matching")
* `man 3 fnmatch`
* `man 5 gitignore`
* [minimatch documentation](https://github.com/isaacs/minimatch)

## glob.hasMagic(pattern, [options])

Returns `true` if there are any special characters in the pattern, and
`false` otherwise.

Note that the options affect the results.  If `noext:true` is set in
the options object, then `+(a|b)` will not be considered a magic
pattern.  If the pattern has a brace expansion, like `a/{b/c,x/y}`
then that is considered magical, unless `nobrace:true` is set in the
options.

## glob(pattern, [options], cb)

* `pattern` `{String}` Pattern to be matched
* `options` `{Object}`
* `cb` `{Function}`
  * `err` `{Error | null}`
  * `matches` `{Array<String>}` filenames found matching the pattern

Perform an asynchronous glob search.

## glob.sync(pattern, [options])

* `pattern` `{String}` Pattern to be matched
* `options` `{Object}`
* return: `{Array<String>}` filenames found matching the pattern

Perform a synchronous glob search.

## Class: glob.Glob

Create a Glob object by instantiating the `glob.Glob` class.

```javascript
var Glob = require("glob").Glob
var mg = new Glob(pattern, options, cb)
```

It's an EventEmitter, and starts walking the filesystem to find matches
immediately.

### new glob.Glob(pattern, [options], [cb])

* `pattern` `{String}` pattern to search for
* `options` `{Object}`
* `cb` `{Function}` Called when an error occurs, or matches are found
  * `err` `{Error | null}`
  * `matches` `{Array<String>}` filenames found matching the pattern

Note that if the `sync` flag is set in the options, then matches will
be immediately available on the `g.found` member.

### Properties

* `minimatch` The minimatch object that the glob uses.
* `options` The options object passed in.
* `aborted` Boolean which is set to true when calling `abort()`.  There
  is no way at this time to continue a glob search after aborting, but
  you can re-use the statCache to avoid having to duplicate syscalls.
* `cache` Convenience object.  Each field has the following possible
  values:
  * `false` - Path does not exist
  * `true` - Path exists
  * `'FILE'` - Path exists, and is not a directory
  * `'DIR'` - Path exists, and is a directory
  * `[file, entries, ...]` - Path exists, is a directory, and the
    array value is the results of `fs.readdir`
* `statCache` Cache of `fs.stat` results, to prevent statting the same
  path multiple times.
* `symlinks` A record of which paths are symbolic links, which is
  relevant in resolving `**` patterns.
* `realpathCache` An optional object which is passed to `fs.realpath`
  to minimize unnecessary syscalls.  It is stored on the instantiated
  Glob object, and may be re-used.

### Events

* `end` When the matching is finished, this is emitted with all the
  matches found.  If the `nonull` option is set, and no match was found,
  then the `matches` list contains the original pattern.  The matches
  are sorted, unless the `nosort` flag is set.
* `match` Every time a match is found, this is emitted with the specific
  thing that matched. It is not deduplicated or resolved to a realpath.
* `error` Emitted when an unexpected error is encountered, or whenever
  any fs error occurs if `options.strict` is set.
* `abort` When `abort()` is called, this event is raised.

### Methods

* `pause` Temporarily stop the search
* `resume` Resume the search
* `abort` Stop the search forever

### Options

All the options that can be passed to Minimatch can also be passed to
Glob to change pattern matching behavior.  Also, some have been added,
or have glob-specific ramifications.

All options are false by default, unless otherwise noted.

All options are added to the Glob object, as well.

If you are running many `glob` operations, you can pass a Glob object
as the `options` argument to a subsequent operation to shortcut some
`stat` and `readdir` calls.  At the very least, you may pass in shared
`symlinks`, `statCache`, `realpathCache`, and `cache` options, so that
parallel glob operations will be sped up by sharing information about
the filesystem.

* `cwd` The current working directory in which to search.  Defaults
  to `process.cwd()`.
* `root` The place where patterns starting with `/` will be mounted
  onto.  Defaults to `path.resolve(options.cwd, "/")` (`/` on Unix
  systems, and `C:\` or some such on Windows.)
* `dot` Include `.dot` files in normal matches and `globstar` matches.
  Note that an explicit dot in a portion of the pattern will always
  match dot files.
* `nomount` By default, a pattern starting with a forward-slash will be
  "mounted" onto the root setting, so that a valid filesystem path is
  returned.  Set this flag to disable that behavior.
* `mark` Add a `/` character to directory matches.  Note that this
  requires additional stat calls.
* `nosort` Don't sort the results.
* `stat` Set to true to stat *all* results.  This reduces performance
  somewhat, and is completely unnecessary, unless `readdir` is presumed
  to be an untrustworthy indicator of file existence.
* `silent` When an unusual error is encountered when attempting to
  read a directory, a warning will be printed to stderr.  Set the
  `silent` option to true to suppress these warnings.
* `strict` When an unusual error is encountered when attempting to
  read a directory, the process will just continue on in search of
  other matches.  Set the `strict` option to raise an error in these
  cases.
* `cache` See `cache` property above.  Pass in a previously generated
  cache object to save some fs calls.
* `statCache` A cache of results of filesystem information, to prevent
  unnecessary stat calls.  While it should not normally be necessary
  to set this, you may pass the statCache from one glob() call to the
  options object of another, if you know that the filesystem will not
  change between calls.  (See "Race Conditions" below.)
* `symlinks` A cache of known symbolic links.  You may pass in a
  previously generated `symlinks` object to save `lstat` calls when
  resolving `**` matches.
* `sync` DEPRECATED: use `glob.sync(pattern, opts)` instead.
* `nounique` In some cases, brace-expanded patterns can result in the
  same file showing up multiple times in the result set.  By default,
  this implementation prevents duplicates in the result set.  Set this
  flag to disable that behavior.
* `nonull` Set to never return an empty set, instead returning a set
  containing the pattern itself.  This is the default in glob(3).
* `debug` Set to enable debug logging in minimatch and glob.
* `nobrace` Do not expand `{a,b}` and `{1..3}` brace sets.
* `noglobstar` Do not match `**` against multiple filenames.  (Ie,
  treat it as a normal `*` instead.)
* `noext` Do not match `+(a|b)` "extglob" patterns.
* `nocase` Perform a case-insensitive match.  Note: on
  case-insensitive filesystems, non-magic patterns will match by
  default, since `stat` and `readdir` will not raise errors.
* `matchBase` Perform a basename-only match if the pattern does not
  contain any slash characters.  That is, `*.js` would be treated as
  equivalent to `**/*.js`, matching all js files in all directories.
* `nodir` Do not match directories, only files.  (Note: to match
  *only* directories, simply put a `/` at the end of the pattern.)
* `ignore` Add a pattern or an array of glob patterns to exclude matches.
  Note: `ignore` patterns are *always* in `dot:true` mode, regardless
  of any other settings.
* `follow` Follow symlinked directories when expanding `**` patterns.
  Note that this can result in a lot of duplicate references in the
  presence of cyclic links.
* `realpath` Set to true to call `fs.realpath` on all of the results.
  In the case of a symlink that cannot be resolved, the full absolute
  path to the matched entry is returned (though it will usually be a
  broken symlink)
* `absolute` Set to true to always receive absolute paths for matched
  files.  Unlike `realpath`, this also affects the values returned in
  the `match` event.
* `fs` File-system object with Node's `fs` API. By default, the built-in
  `fs` module will be used. Set to a volume provided by a library like
  `memfs` to avoid using the "real" file-system.

## Comparisons to other fnmatch/glob implementations

While strict compliance with the existing standards is a worthwhile
goal, some discrepancies exist between node-glob and other
implementations, and are intentional.

The double-star character `**` is supported by default, unless the
`noglobstar` flag is set.  This is supported in the manner of bsdglob
and bash 4.3, where `**` only has special significance if it is the only
thing in a path part.  That is, `a/**/b` will match `a/x/y/b`, but
`a/**b` will not.

Note that symlinked directories are not crawled as part of a `**`,
though their contents may match against subsequent portions of the
pattern.  This prevents infinite loops and duplicates and the like.

If an escaped pattern has no matches, and the `nonull` flag is set,
then glob returns the pattern as-provided, rather than
interpreting the character escapes.  For example,
`glob.match([], "\\*a\\?")` will return `"\\*a\\?"` rather than
`"*a?"`.  This is akin to setting the `nullglob` option in bash, except
that it does not resolve escaped pattern characters.

If brace expansion is not disabled, then it is performed before any
other interpretation of the glob pattern.  Thus, a pattern like
`+(a|{b),c)}`, which would not be valid in bash or zsh, is expanded
**first** into the set of `+(a|b)` and `+(a|c)`, and those patterns are
checked for validity.  Since those two are valid, matching proceeds.

### Comments and Negation

Previously, this module let you mark a pattern as a "comment" if it
started with a `#` character, or a "negated" pattern if it started
with a `!` character.

These options were deprecated in version 5, and removed in version 6.

To specify things that should not match, use the `ignore` option.

## Windows

**Please only use forward-slashes in glob expressions.**

Though windows uses either `/` or `\` as its path separator, only `/`
characters are used by this glob implementation.  You must use
forward-slashes **only** in glob expressions.  Back-slashes will always
be interpreted as escape characters, not path separators.

Results from absolute patterns such as `/foo/*` are mounted onto the
root setting using `path.join`.  On windows, this will by default result
in `/foo/*` matching `C:\foo\bar.txt`.

## Race Conditions

Glob searching, by its very nature, is susceptible to race conditions,
since it relies on directory walking and such.

As a result, it is possible that a file that exists when glob looks for
it may have been deleted or modified by the time it returns the result.

As part of its internal implementation, this program caches all stat
and readdir calls that it makes, in order to cut down on system
overhead.  However, this also makes it even more susceptible to races,
especially if the cache or statCache objects are reused between glob
calls.

Users are thus advised not to use a glob result as a guarantee of
filesystem state in the face of rapid changes.  For the vast majority
of operations, this is never a problem.

## Glob Logo
Glob's logo was created by [Tanya Brassie](http://tanyabrassie.com/). Logo files can be found [here](https://github.com/isaacs/node-glob/tree/master/logo).

The logo is licensed under a [Creative Commons Attribution-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-sa/4.0/).

## Contributing

Any change to behavior (including bugfixes) must come with a test.

Patches that fail tests or reduce performance will be rejected.

```
# to run tests
npm test

# to re-generate test fixtures
npm run test-regen

# to benchmark against bash/zsh
npm run bench

# to profile javascript
npm run prof
```

![](oh-my-glob.gif)


---

### [5.1.2](https://github.com/gulpjs/glob-parent/compare/v5.1.1...v5.1.2) (2021-03-06)


### Bug Fixes

* eliminate ReDoS ([#36](https://github.com/gulpjs/glob-parent/issues/36)) ([f923116](https://github.com/gulpjs/glob-parent/commit/f9231168b0041fea3f8f954b3cceb56269fc6366))

### [5.1.1](https://github.com/gulpjs/glob-parent/compare/v5.1.0...v5.1.1) (2021-01-27)


### Bug Fixes

* unescape exclamation mark ([#26](https://github.com/gulpjs/glob-parent/issues/26)) ([a98874f](https://github.com/gulpjs/glob-parent/commit/a98874f1a59e407f4fb1beb0db4efa8392da60bb))

## [5.1.0](https://github.com/gulpjs/glob-parent/compare/v5.0.0...v5.1.0) (2021-01-27)


### Features

* add `flipBackslashes` option to disable auto conversion of slashes (closes [#24](https://github.com/gulpjs/glob-parent/issues/24)) ([#25](https://github.com/gulpjs/glob-parent/issues/25)) ([eecf91d](https://github.com/gulpjs/glob-parent/commit/eecf91d5e3834ed78aee39c4eaaae654d76b87b3))

## [5.0.0](https://github.com/gulpjs/glob-parent/compare/v4.0.0...v5.0.0) (2021-01-27)


### ⚠ BREAKING CHANGES

* Drop support for node <6 & bump dependencies

### Miscellaneous Chores

* Drop support for node <6 & bump dependencies ([896c0c0](https://github.com/gulpjs/glob-parent/commit/896c0c00b4e7362f60b96e7fc295ae929245255a))

## [4.0.0](https://github.com/gulpjs/glob-parent/compare/v3.1.0...v4.0.0) (2021-01-27)


### ⚠ BREAKING CHANGES

* question marks are valid path characters on Windows so avoid flagging as a glob when alone
* Update is-glob dependency

### Features

* hoist regexps and strings for performance gains ([4a80667](https://github.com/gulpjs/glob-parent/commit/4a80667c69355c76a572a5892b0f133c8e1f457e))
* question marks are valid path characters on Windows so avoid flagging as a glob when alone ([2a551dd](https://github.com/gulpjs/glob-parent/commit/2a551dd0dc3235e78bf3c94843d4107072d17841))
* Update is-glob dependency ([e41fcd8](https://github.com/gulpjs/glob-parent/commit/e41fcd895d1f7bc617dba45c9d935a7949b9c281))

## [3.1.0](https://github.com/gulpjs/glob-parent/compare/v3.0.1...v3.1.0) (2021-01-27)


### Features

* allow basic win32 backslash use ([272afa5](https://github.com/gulpjs/glob-parent/commit/272afa5fd070fc0f796386a5993d4ee4a846988b))
* handle extglobs (parentheses) containing separators ([7db1bdb](https://github.com/gulpjs/glob-parent/commit/7db1bdb0756e55fd14619e8ce31aa31b17b117fd))
* new approach to braces/brackets handling ([8269bd8](https://github.com/gulpjs/glob-parent/commit/8269bd89290d99fac9395a354fb56fdcdb80f0be))
* pre-process braces/brackets sections ([9ef8a87](https://github.com/gulpjs/glob-parent/commit/9ef8a87f66b1a43d0591e7a8e4fc5a18415ee388))
* preserve escaped brace/bracket at end of string ([8cfb0ba](https://github.com/gulpjs/glob-parent/commit/8cfb0ba84202d51571340dcbaf61b79d16a26c76))


### Bug Fixes

* trailing escaped square brackets ([99ec9fe](https://github.com/gulpjs/glob-parent/commit/99ec9fecc60ee488ded20a94dd4f18b4f55c4ccf))

### [3.0.1](https://github.com/gulpjs/glob-parent/compare/v3.0.0...v3.0.1) (2021-01-27)


### Features

* use path-dirname ponyfill ([cdbea5f](https://github.com/gulpjs/glob-parent/commit/cdbea5f32a58a54e001a75ddd7c0fccd4776aacc))


### Bug Fixes

* unescape glob-escaped dirnames on output ([598c533](https://github.com/gulpjs/glob-parent/commit/598c533bdf49c1428bc063aa9b8db40c5a86b030))

## [3.0.0](https://github.com/gulpjs/glob-parent/compare/v2.0.0...v3.0.0) (2021-01-27)


### ⚠ BREAKING CHANGES

* update is-glob dependency

### Features

* update is-glob dependency ([5c5f8ef](https://github.com/gulpjs/glob-parent/commit/5c5f8efcee362a8e7638cf8220666acd8784f6bd))

## [2.0.0](https://github.com/gulpjs/glob-parent/compare/v1.3.0...v2.0.0) (2021-01-27)


### Features

* move up to dirname regardless of glob characters ([f97fb83](https://github.com/gulpjs/glob-parent/commit/f97fb83be2e0a9fc8d3b760e789d2ecadd6aa0c2))

## [1.3.0](https://github.com/gulpjs/glob-parent/compare/v1.2.0...v1.3.0) (2021-01-27)

## [1.2.0](https://github.com/gulpjs/glob-parent/compare/v1.1.0...v1.2.0) (2021-01-27)


### Reverts

* feat: make regex test strings smaller ([dc80fa9](https://github.com/gulpjs/glob-parent/commit/dc80fa9658dca20549cfeba44bbd37d5246fcce0))

## [1.1.0](https://github.com/gulpjs/glob-parent/compare/v1.0.0...v1.1.0) (2021-01-27)


### Features

* make regex test strings smaller ([cd83220](https://github.com/gulpjs/glob-parent/commit/cd832208638f45169f986d80fcf66e401f35d233))

## 1.0.0 (2021-01-27)



---

<p align="center">
  <a href="https://gulpjs.com">
    <img height="257" width="114" src="https://raw.githubusercontent.com/gulpjs/artwork/master/gulp-2x.png">
  </a>
</p>

# glob-parent

[![NPM version][npm-image]][npm-url] [![Downloads][downloads-image]][npm-url] [![Azure Pipelines Build Status][azure-pipelines-image]][azure-pipelines-url] [![Travis Build Status][travis-image]][travis-url] [![AppVeyor Build Status][appveyor-image]][appveyor-url] [![Coveralls Status][coveralls-image]][coveralls-url] [![Gitter chat][gitter-image]][gitter-url]

Extract the non-magic parent path from a glob string.

## Usage

```js
var globParent = require('glob-parent');

globParent('path/to/*.js'); // 'path/to'
globParent('/root/path/to/*.js'); // '/root/path/to'
globParent('/*.js'); // '/'
globParent('*.js'); // '.'
globParent('**/*.js'); // '.'
globParent('path/{to,from}'); // 'path'
globParent('path/!(to|from)'); // 'path'
globParent('path/?(to|from)'); // 'path'
globParent('path/+(to|from)'); // 'path'
globParent('path/*(to|from)'); // 'path'
globParent('path/@(to|from)'); // 'path'
globParent('path/**/*'); // 'path'

// if provided a non-glob path, returns the nearest dir
globParent('path/foo/bar.js'); // 'path/foo'
globParent('path/foo/'); // 'path/foo'
globParent('path/foo'); // 'path' (see issue #3 for details)
```

## API

### `globParent(maybeGlobString, [options])`

Takes a string and returns the part of the path before the glob begins. Be aware of Escaping rules and Limitations below.

#### options

```js
{
  // Disables the automatic conversion of slashes for Windows
  flipBackslashes: true
}
```

## Escaping

The following characters have special significance in glob patterns and must be escaped if you want them to be treated as regular path characters:

- `?` (question mark) unless used as a path segment alone
- `*` (asterisk)
- `|` (pipe)
- `(` (opening parenthesis)
- `)` (closing parenthesis)
- `{` (opening curly brace)
- `}` (closing curly brace)
- `[` (opening bracket)
- `]` (closing bracket)

**Example**

```js
globParent('foo/[bar]/') // 'foo'
globParent('foo/\\[bar]/') // 'foo/[bar]'
```

## Limitations

### Braces & Brackets
This library attempts a quick and imperfect method of determining which path
parts have glob magic without fully parsing/lexing the pattern. There are some
advanced use cases that can trip it up, such as nested braces where the outer
pair is escaped and the inner one contains a path separator. If you find
yourself in the unlikely circumstance of being affected by this or need to
ensure higher-fidelity glob handling in your library, it is recommended that you
pre-process your input with [expand-braces] and/or [expand-brackets].

### Windows
Backslashes are not valid path separators for globs. If a path with backslashes
is provided anyway, for simple cases, glob-parent will replace the path
separator for you and return the non-glob parent path (now with
forward-slashes, which are still valid as Windows path separators).

This cannot be used in conjunction with escape characters.

```js
// BAD
globParent('C:\\Program Files \\(x86\\)\\*.ext') // 'C:/Program Files /(x86/)'

// GOOD
globParent('C:/Program Files\\(x86\\)/*.ext') // 'C:/Program Files (x86)'
```

If you are using escape characters for a pattern without path parts (i.e.
relative to `cwd`), prefix with `./` to avoid confusing glob-parent.

```js
// BAD
globParent('foo \\[bar]') // 'foo '
globParent('foo \\[bar]*') // 'foo '

// GOOD
globParent('./foo \\[bar]') // 'foo [bar]'
globParent('./foo \\[bar]*') // '.'
```

## License

ISC

[expand-braces]: https://github.com/jonschlinkert/expand-braces
[expand-brackets]: https://github.com/jonschlinkert/expand-brackets

[downloads-image]: https://img.shields.io/npm/dm/glob-parent.svg
[npm-url]: https://www.npmjs.com/package/glob-parent
[npm-image]: https://img.shields.io/npm/v/glob-parent.svg

[azure-pipelines-url]: https://dev.azure.com/gulpjs/gulp/_build/latest?definitionId=2&branchName=master
[azure-pipelines-image]: https://dev.azure.com/gulpjs/gulp/_apis/build/status/glob-parent?branchName=master

[travis-url]: https://travis-ci.org/gulpjs/glob-parent
[travis-image]: https://img.shields.io/travis/gulpjs/glob-parent.svg?label=travis-ci

[appveyor-url]: https://ci.appveyor.com/project/gulpjs/glob-parent
[appveyor-image]: https://img.shields.io/appveyor/ci/gulpjs/glob-parent.svg?label=appveyor

[coveralls-url]: https://coveralls.io/r/gulpjs/glob-parent
[coveralls-image]: https://img.shields.io/coveralls/gulpjs/glob-parent/master.svg

[gitter-url]: https://gitter.im/gulpjs/gulp
[gitter-image]: https://badges.gitter.im/gulpjs/gulp.svg


---

# Glob To Regular Expression

[![Build Status](https://travis-ci.org/fitzgen/glob-to-regexp.png?branch=master)](https://travis-ci.org/fitzgen/glob-to-regexp)

Turn a \*-wildcard style glob (`"*.min.js"`) into a regular expression
(`/^.*\.min\.js$/`)!

To match bash-like globs, eg. `?` for any single-character match, `[a-z]` for
character ranges, and `{*.html, *.js}` for multiple alternatives, call with
`{ extended: true }`.

To obey [globstars `**`](https://github.com/isaacs/node-glob#glob-primer) rules set option `{globstar: true}`.
NOTE: This changes the behavior of `*` when `globstar` is `true` as shown below:
When `{globstar: true}`: `/foo/**` will match any string that starts with `/foo/`
like `/foo/index.htm`, `/foo/bar/baz.txt`, etc.  Also, `/foo/**/*.txt` will match
any string that starts with `/foo/` and ends with `.txt` like `/foo/bar.txt`,
`/foo/bar/baz.txt`, etc.
Whereas `/foo/*` (single `*`, not a globstar) will match strings that start with
`/foo/` like `/foo/index.htm`, `/foo/baz.txt` but will not match strings that
contain a `/` to the right like `/foo/bar/baz.txt`, `/foo/bar/baz/qux.dat`, etc.

Set flags on the resulting `RegExp` object by adding the `flags` property to the option object, eg `{ flags: "i" }` for ignoring case.

## Install

    npm install glob-to-regexp

## Usage
```js
var globToRegExp = require('glob-to-regexp');
var re = globToRegExp("p*uck");
re.test("pot luck"); // true
re.test("pluck"); // true
re.test("puck"); // true

re = globToRegExp("*.min.js");
re.test("http://example.com/jquery.min.js"); // true
re.test("http://example.com/jquery.min.js.map"); // false

re = globToRegExp("*/www/*.js");
re.test("http://example.com/www/app.js"); // true
re.test("http://example.com/www/lib/factory-proxy-model-observer.js"); // true

// Extended globs
re = globToRegExp("*/www/{*.js,*.html}", { extended: true });
re.test("http://example.com/www/app.js"); // true
re.test("http://example.com/www/index.html"); // true
```

## License

Copyright (c) 2013, Nick Fitzgerald

All rights reserved.

Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice, this
  list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright notice, this
  list of conditions and the following disclaimer in the documentation and/or
  other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


---

An ini format parser and serializer for node.

Sections are treated as nested objects.  Items before the first
heading are saved on the object directly.

## Usage

Consider an ini-file `config.ini` that looks like this:

    ; this comment is being ignored
    scope = global

    [database]
    user = dbuser
    password = dbpassword
    database = use_this_database

    [paths.default]
    datadir = /var/lib/data
    array[] = first value
    array[] = second value
    array[] = third value

You can read, manipulate and write the ini-file like so:

    var fs = require('fs')
      , ini = require('ini')

    var config = ini.parse(fs.readFileSync('./config.ini', 'utf-8'))

    config.scope = 'local'
    config.database.database = 'use_another_database'
    config.paths.default.tmpdir = '/tmp'
    delete config.paths.default.datadir
    config.paths.default.array.push('fourth value')

    fs.writeFileSync('./config_modified.ini', ini.stringify(config, { section: 'section' }))

This will result in a file called `config_modified.ini` being written
to the filesystem with the following content:

    [section]
    scope=local
    [section.database]
    user=dbuser
    password=dbpassword
    database=use_another_database
    [section.paths.default]
    tmpdir=/tmp
    array[]=first value
    array[]=second value
    array[]=third value
    array[]=fourth value


## API

### decode(inistring)

Decode the ini-style formatted `inistring` into a nested object.

### parse(inistring)

Alias for `decode(inistring)`

### encode(object, [options])

Encode the object `object` into an ini-style formatted string. If the
optional parameter `section` is given, then all top-level properties
of the object are put into this section and the `section`-string is
prepended to all sub-sections, see the usage example above.

The `options` object may contain the following:

* `section` A string which will be the first `section` in the encoded
  ini data.  Defaults to none.
* `whitespace` Boolean to specify whether to put whitespace around the
  `=` character.  By default, whitespace is omitted, to be friendly to
  some persnickety old parsers that don't tolerate it well.  But some
  find that it's more human-readable and pretty with the whitespace.

For backwards compatibility reasons, if a `string` options is passed
in, then it is assumed to be the `section` value.

### stringify(object, [options])

Alias for `encode(object, [options])`

### safe(val)

Escapes the string `val` such that it is safe to be used as a key or
value in an ini-file. Basically escapes quotes. For example

    ini.safe('"unsafe string"')

would result in

    "\"unsafe string\""

### unsafe(val)

Unescapes the string `val`


---

# global-dirs

> Get the directory of globally installed packages and binaries

Uses the same resolution logic as `npm` and `yarn`.

## Install

```
$ npm install global-dirs
```

## Usage

```js
const globalDirectories = require('global-dirs');

console.log(globalDirectories.npm.prefix);
//=> '/usr/local'

console.log(globalDirectories.npm.packages);
//=> '/usr/local/lib/node_modules'

console.log(globalDirectories.npm.binaries);
//=> '/usr/local/bin'

console.log(globalDirectories.yarn.packages);
//=> '/Users/sindresorhus/.config/yarn/global/node_modules'
```

## API

### globalDirectories

#### npm
#### yarn

##### packages

Directory with globally installed packages.

Equivalent to `npm root --global`.

##### binaries

Directory with globally installed binaries.

Equivalent to `npm bin --global`.

##### prefix

Directory with directories for packages and binaries. You probably want either of the above.

Equivalent to `npm prefix --global`.

## Related

- [import-global](https://github.com/sindresorhus/import-global) - Import a globally installed module
- [resolve-global](https://github.com/sindresorhus/resolve-global) - Resolve the path of a globally installed module
- [is-installed-globally](https://github.com/sindresorhus/is-installed-globally) - Check if your package was installed globally

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-global-dirs?utm_source=npm-global-dirs&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

# global-modules [![NPM version](https://img.shields.io/npm/v/global-modules.svg?style=flat)](https://www.npmjs.com/package/global-modules) [![NPM monthly downloads](https://img.shields.io/npm/dm/global-modules.svg?style=flat)](https://npmjs.org/package/global-modules) [![NPM total downloads](https://img.shields.io/npm/dt/global-modules.svg?style=flat)](https://npmjs.org/package/global-modules) [![Linux Build Status](https://img.shields.io/travis/jonschlinkert/global-modules.svg?style=flat&label=Travis)](https://travis-ci.org/jonschlinkert/global-modules)

> The directory used by npm for globally installed npm modules.

Please consider following this project's author, [Jon Schlinkert](https://github.com/jonschlinkert), and consider starring the project to show your :heart: and support.

## Install

Install with [npm](https://www.npmjs.com/):

```sh
$ npm install --save global-modules
```

## Usage

```js
const globalModules = require('global-modules');
console.log(globalModules);
//=> '/usr/local/lib/node_modules' 
```
_(Note that this path might be different based on platform, user-defined configuration settings, etc)_

## About

<details>
<summary><strong>Contributing</strong></summary>

Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).

</details>

<details>
<summary><strong>Running Tests</strong></summary>

Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

```sh
$ npm install && npm test
```

</details>

<details>
<summary><strong>Building docs</strong></summary>

_(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_

To generate the readme, run the following command:

```sh
$ npm install -g verbose/verb#dev verb-generate-readme && verb
```

</details>

### Related projects

You might also be interested in these projects:

* [git-config-path](https://www.npmjs.com/package/git-config-path): Resolve the path to the user's local or global .gitconfig. | [homepage](https://github.com/jonschlinkert/git-config-path "Resolve the path to the user's local or global .gitconfig.")
* [global-prefix](https://www.npmjs.com/package/global-prefix): Get the npm global path prefix. | [homepage](https://github.com/jonschlinkert/global-prefix "Get the npm global path prefix.")
* [npm-paths](https://www.npmjs.com/package/npm-paths): Returns an array of unique "npm" directories based on the user's platform and environment. | [homepage](https://github.com/jonschlinkert/npm-paths "Returns an array of unique "npm" directories based on the user's platform and environment.")

### Contributors

| **Commits** | **Contributor** |  
| --- | --- |  
| 20 | [jonschlinkert](https://github.com/jonschlinkert) |  
| 1  | [Kikobeats](https://github.com/Kikobeats) |  

### Author

**Jon Schlinkert**

* [GitHub Profile](https://github.com/jonschlinkert)
* [Twitter Profile](https://twitter.com/jonschlinkert)
* [LinkedIn Profile](https://linkedin.com/in/jonschlinkert)

### License

Copyright © 2018, [Jon Schlinkert](https://github.com/jonschlinkert).
Released under the [MIT License](LICENSE).

***

_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.8.0, on December 14, 2018._

---

# global-prefix [![NPM version](https://img.shields.io/npm/v/global-prefix.svg?style=flat)](https://www.npmjs.com/package/global-prefix) [![NPM monthly downloads](https://img.shields.io/npm/dm/global-prefix.svg?style=flat)](https://npmjs.org/package/global-prefix) [![NPM total downloads](https://img.shields.io/npm/dt/global-prefix.svg?style=flat)](https://npmjs.org/package/global-prefix) [![Linux Build Status](https://img.shields.io/travis/jonschlinkert/global-prefix.svg?style=flat&label=Travis)](https://travis-ci.org/jonschlinkert/global-prefix) [![Windows Build Status](https://img.shields.io/appveyor/ci/jonschlinkert/global-prefix.svg?style=flat&label=AppVeyor)](https://ci.appveyor.com/project/jonschlinkert/global-prefix)

> Get the npm global path prefix.

Please consider following this project's author, [Jon Schlinkert](https://github.com/jonschlinkert), and consider starring the project to show your :heart: and support.

## Install

Install with [npm](https://www.npmjs.com/):

```sh
$ npm install --save global-prefix
```

This is partially based on the code used by npm internally to resolve the global prefix.

## Usage

```js
var prefix = require('global-prefix');
//=> '/usr/local' (this path will differ by system and user-defined config)
```

## About

<details>
<summary><strong>Contributing</strong></summary>

Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).

</details>

<details>
<summary><strong>Running Tests</strong></summary>

Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

```sh
$ npm install && npm test
```

</details>

<details>
<summary><strong>Building docs</strong></summary>

_(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_

To generate the readme, run the following command:

```sh
$ npm install -g verbose/verb#dev verb-generate-readme && verb
```

</details>

### Related projects

You might also be interested in these projects:

* [global-modules](https://www.npmjs.com/package/global-modules): The directory used by npm for globally installed npm modules. | [homepage](https://github.com/jonschlinkert/global-modules "The directory used by npm for globally installed npm modules.")
* [global-paths](https://www.npmjs.com/package/global-paths): Returns an array of unique "global" directories based on the user's platform and environment. The… [more](https://github.com/jonschlinkert/global-paths) | [homepage](https://github.com/jonschlinkert/global-paths "Returns an array of unique "global" directories based on the user's platform and environment. The resulting paths can be used for doing lookups for generators or other globally installed npm packages. Node.js / JavaScript.")

### Contributors

| **Commits** | **Contributor** | 
| --- | --- |
| 23 | [jonschlinkert](https://github.com/jonschlinkert) |
| 15 | [doowb](https://github.com/doowb) |
| 2 | [phated](https://github.com/phated) |
| 1 | [rmbaad](https://github.com/rmbaad) |
| 1 | [avengerpenguin](https://github.com/avengerpenguin) |
| 1 | [jorrit](https://github.com/jorrit) |
| 1 | [mathiasvr](https://github.com/mathiasvr) |
| 1 | [tunnckoCore](https://github.com/tunnckoCore) |

### Author

**Jon Schlinkert**

* [GitHub Profile](https://github.com/jonschlinkert)
* [Twitter Profile](https://twitter.com/jonschlinkert)
* [LinkedIn Profile](https://linkedin.com/in/jonschlinkert)

### License

Copyright © 2018, [Jon Schlinkert](https://github.com/jonschlinkert).
Released under the [MIT License](LICENSE).

***

_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.6.0, on October 11, 2018._

---

# Changes


## 1.3.1

* update deps
* update travis

## v1.3.0

* Add nothrow option to which.sync
* update tap

## v1.2.14

* appveyor: drop node 5 and 0.x
* travis-ci: add node 6, drop 0.x

## v1.2.13

* test: Pass missing option to pass on windows
* update tap
* update isexe to 2.0.0
* neveragain.tech pledge request

## v1.2.12

* Removed unused require

## v1.2.11

* Prevent changelog script from being included in package

## v1.2.10

* Use env.PATH only, not env.Path

## v1.2.9

* fix for paths starting with ../
* Remove unused `is-absolute` module

## v1.2.8

* bullet items in changelog that contain (but don't start with) #

## v1.2.7

* strip 'update changelog' changelog entries out of changelog

## v1.2.6

* make the changelog bulleted

## v1.2.5

* make a changelog, and keep it up to date
* don't include tests in package
* Properly handle relative-path executables
* appveyor
* Attach error code to Not Found error
* Make tests pass on Windows

## v1.2.4

* Fix typo

## v1.2.3

* update isexe, fix regression in pathExt handling

## v1.2.2

* update deps, use isexe module, test windows

## v1.2.1

* Sometimes windows PATH entries are quoted
* Fixed a bug in the check for group and user mode bits. This bug was introduced during refactoring for supporting strict mode.
* doc cli

## v1.2.0

* Add support for opt.all and -as cli flags
* test the bin
* update travis
* Allow checking for multiple programs in bin/which
* tap 2

## v1.1.2

* travis
* Refactored and fixed undefined error on Windows
* Support strict mode

## v1.1.1

* test +g exes against secondary groups, if available
* Use windows exe semantics on cygwin & msys
* cwd should be first in path on win32, not last
* Handle lower-case 'env.Path' on Windows
* Update docs
* use single-quotes

## v1.1.0

* Add tests, depend on is-absolute

## v1.0.9

* which.js: root is allowed to execute files owned by anyone

## v1.0.8

* don't use graceful-fs

## v1.0.7

* add license to package.json

## v1.0.6

* isc license

## 1.0.5

* Awful typo

## 1.0.4

* Test for path absoluteness properly
* win: Allow '' as a pathext if cmd has a . in it

## 1.0.3

* Remove references to execPath
* Make `which.sync()` work on Windows by honoring the PATHEXT variable.
* Make `isExe()` always return true on Windows.
* MIT

## 1.0.2

* Only files can be exes

## 1.0.1

* Respect the PATHEXT env for win32 support
* should 0755 the bin
* binary
* guts
* package
* 1st


---

# which

Like the unix `which` utility.

Finds the first instance of a specified executable in the PATH
environment variable.  Does not cache the results, so `hash -r` is not
needed when the PATH changes.

## USAGE

```javascript
var which = require('which')

// async usage
which('node', function (er, resolvedPath) {
  // er is returned if no "node" is found on the PATH
  // if it is found, then the absolute path to the exec is returned
})

// sync usage
// throws if not found
var resolved = which.sync('node')

// if nothrow option is used, returns null if not found
resolved = which.sync('node', {nothrow: true})

// Pass options to override the PATH and PATHEXT environment vars.
which('node', { path: someOtherPath }, function (er, resolved) {
  if (er)
    throw er
  console.log('found at %j', resolved)
})
```

## CLI USAGE

Same as the BSD `which(1)` binary.

```
usage: which [-as] program ...
```

## OPTIONS

You may pass an options object as the second argument.

- `path`: Use instead of the `PATH` environment variable.
- `pathExt`: Use instead of the `PATHEXT` environment variable.
- `all`: Return all matches, instead of just the first one.  Note that
  this means the function returns an array of strings instead of a
  single string.


---

# globals [![Build Status](https://travis-ci.org/sindresorhus/globals.svg?branch=master)](https://travis-ci.org/sindresorhus/globals)

> Global identifiers from different JavaScript environments

Extracted from [JSHint](https://github.com/jshint/jshint/blob/3a8efa979dbb157bfb5c10b5826603a55a33b9ad/src/vars.js) and [ESLint](https://github.com/eslint/eslint/blob/b648406218f8a2d7302b98f5565e23199f44eb31/conf/environments.json) and merged.

It's just a [JSON file](globals.json), so use it in whatever environment you like.

**This module [no longer accepts](https://github.com/sindresorhus/globals/issues/82) new environments. If you need it for ESLint, just [create a plugin](http://eslint.org/docs/developer-guide/working-with-plugins#environments-in-plugins).**


## Install

```
$ npm install globals
```


## Usage

```js
const globals = require('globals');

console.log(globals.browser);
/*
{
	addEventListener: false,
	applicationCache: false,
	ArrayBuffer: false,
	atob: false,
	...
}
*/
```

Each global is given a value of `true` or `false`. A value of `true` indicates that the variable may be overwritten. A value of `false` indicates that the variable should be considered read-only. This information is used by static analysis tools to flag incorrect behavior. We assume all variables should be `false` unless we hear otherwise.


## License

MIT © [Sindre Sorhus](https://sindresorhus.com)


---

# globby

> User-friendly glob matching

Based on [`fast-glob`](https://github.com/mrmlnc/fast-glob) but adds a bunch of useful features.

## Features

- Promise API
- Multiple patterns
- Negated patterns: `['foo*', '!foobar']`
- Expands directories: `foo` → `foo/**/*`
- Supports `.gitignore`

## Install

```
$ npm install globby
```

## Usage

```
├── unicorn
├── cake
└── rainbow
```

```js
const globby = require('globby');

(async () => {
	const paths = await globby(['*', '!cake']);

	console.log(paths);
	//=> ['unicorn', 'rainbow']
})();
```

## API

Note that glob patterns can only contain forward-slashes, not backward-slashes, so if you want to construct a glob pattern from path components, you need to use `path.posix.join()` instead of `path.join()`.

### globby(patterns, options?)

Returns a `Promise<string[]>` of matching paths.

#### patterns

Type: `string | string[]`

See supported `minimatch` [patterns](https://github.com/isaacs/minimatch#usage).

#### options

Type: `object`

See the [`fast-glob` options](https://github.com/mrmlnc/fast-glob#options-3) in addition to the ones below.

##### expandDirectories

Type: `boolean | string[] | object`\
Default: `true`

If set to `true`, `globby` will automatically glob directories for you. If you define an `Array` it will only glob files that matches the patterns inside the `Array`. You can also define an `object` with `files` and `extensions` like below:

```js
const globby = require('globby');

(async () => {
	const paths = await globby('images', {
		expandDirectories: {
			files: ['cat', 'unicorn', '*.jpg'],
			extensions: ['png']
		}
	});

	console.log(paths);
	//=> ['cat.png', 'unicorn.png', 'cow.jpg', 'rainbow.jpg']
})();
```

Note that if you set this option to `false`, you won't get back matched directories unless you set `onlyFiles: false`.

##### gitignore

Type: `boolean`\
Default: `false`

Respect ignore patterns in `.gitignore` files that apply to the globbed files.

### globby.sync(patterns, options?)

Returns `string[]` of matching paths.

### globby.stream(patterns, options?)

Returns a [`stream.Readable`](https://nodejs.org/api/stream.html#stream_readable_streams) of matching paths.

Since Node.js 10, [readable streams are iterable](https://nodejs.org/api/stream.html#stream_readable_symbol_asynciterator), so you can loop over glob matches in a [`for await...of` loop](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of) like this:

```js
const globby = require('globby');

(async () => {
	for await (const path of globby.stream('*.tmp')) {
		console.log(path);
	}
})();
```

### globby.generateGlobTasks(patterns, options?)

Returns an `object[]` in the format `{pattern: string, options: Object}`, which can be passed as arguments to [`fast-glob`](https://github.com/mrmlnc/fast-glob). This is useful for other globbing-related packages.

Note that you should avoid running the same tasks multiple times as they contain a file system cache. Instead, run this method each time to ensure file system changes are taken into consideration.

### globby.hasMagic(patterns, options?)

Returns a `boolean` of whether there are any special glob characters in the `patterns`.

Note that the options affect the results.

This function is backed by [`fast-glob`](https://github.com/mrmlnc/fast-glob#isdynamicpatternpattern-options).

### globby.gitignore(options?)

Returns a `Promise<(path: string) => boolean>` indicating whether a given path is ignored via a `.gitignore` file.

Takes `cwd?: string` and `ignore?: string[]` as options. `.gitignore` files matched by the ignore config are not used for the resulting filter function.

```js
const {gitignore} = require('globby');

(async () => {
	const isIgnored = await gitignore();
	console.log(isIgnored('some/file'));
})();
```

### globby.gitignore.sync(options?)

Returns a `(path: string) => boolean` indicating whether a given path is ignored via a `.gitignore` file.

Takes the same options as `globby.gitignore`.

## Globbing patterns

Just a quick overview.

- `*` matches any number of characters, but not `/`
- `?` matches a single character, but not `/`
- `**` matches any number of characters, including `/`, as long as it's the only thing in a path part
- `{}` allows for a comma-separated list of "or" expressions
- `!` at the beginning of a pattern will negate the match

[Various patterns and expected matches.](https://github.com/sindresorhus/multimatch/blob/main/test/test.js)

## globby for enterprise

Available as part of the Tidelift Subscription.

The maintainers of globby and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-globby?utm_source=npm-globby&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)

## Related

- [multimatch](https://github.com/sindresorhus/multimatch) - Match against a list instead of the filesystem
- [matcher](https://github.com/sindresorhus/matcher) - Simple wildcard matching
- [del](https://github.com/sindresorhus/del) - Delete files and directories
- [make-dir](https://github.com/sindresorhus/make-dir) - Make a directory and its parents if needed


---

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [v1.2.0](https://github.com/ljharb/gopd/compare/v1.1.0...v1.2.0) - 2024-12-03

### Commits

- [New] add `gOPD` entry point; remove `get-intrinsic` [`5b61232`](https://github.com/ljharb/gopd/commit/5b61232dedea4591a314bcf16101b1961cee024e)

## [v1.1.0](https://github.com/ljharb/gopd/compare/v1.0.1...v1.1.0) - 2024-11-29

### Commits

- [New] add types [`f585e39`](https://github.com/ljharb/gopd/commit/f585e397886d270e4ba84e53d226e4f9ca2eb0e6)
- [Dev Deps] update `@ljharb/eslint-config`, `auto-changelog`, `tape` [`0b8e4fd`](https://github.com/ljharb/gopd/commit/0b8e4fded64397a7726a9daa144a6cc9a5e2edfa)
- [Dev Deps] update `aud`, `npmignore`, `tape` [`48378b2`](https://github.com/ljharb/gopd/commit/48378b2443f09a4f7efbd0fb6c3ee845a6cabcf3)
- [Dev Deps] update `@ljharb/eslint-config`, `aud`, `tape` [`78099ee`](https://github.com/ljharb/gopd/commit/78099eeed41bfdc134c912280483689cc8861c31)
- [Tests] replace `aud` with `npm audit` [`4e0d0ac`](https://github.com/ljharb/gopd/commit/4e0d0ac47619d24a75318a8e1f543ee04b2a2632)
- [meta] add missing `engines.node` [`1443316`](https://github.com/ljharb/gopd/commit/14433165d07835c680155b3dfd62d9217d735eca)
- [Deps] update `get-intrinsic` [`eee5f51`](https://github.com/ljharb/gopd/commit/eee5f51769f3dbaf578b70e2a3199116b01aa670)
- [Deps] update `get-intrinsic` [`550c378`](https://github.com/ljharb/gopd/commit/550c3780e3a9c77b62565712a001b4ed64ea61f5)
- [Dev Deps] add missing peer dep [`8c2ecf8`](https://github.com/ljharb/gopd/commit/8c2ecf848122e4e30abfc5b5086fb48b390dce75)

## [v1.0.1](https://github.com/ljharb/gopd/compare/v1.0.0...v1.0.1) - 2022-11-01

### Commits

- [Fix] actually export gOPD instead of dP [`4b624bf`](https://github.com/ljharb/gopd/commit/4b624bfbeff788c5e3ff16d9443a83627847234f)

## v1.0.0 - 2022-11-01

### Commits

- Initial implementation, tests, readme [`0911e01`](https://github.com/ljharb/gopd/commit/0911e012cd642092bd88b732c161c58bf4f20bea)
- Initial commit [`b84e33f`](https://github.com/ljharb/gopd/commit/b84e33f5808a805ac57ff88d4247ad935569acbe)
- [actions] add reusable workflows [`12ae28a`](https://github.com/ljharb/gopd/commit/12ae28ae5f50f86e750215b6e2188901646d0119)
- npm init [`280118b`](https://github.com/ljharb/gopd/commit/280118badb45c80b4483836b5cb5315bddf6e582)
- [meta] add `auto-changelog` [`bb78de5`](https://github.com/ljharb/gopd/commit/bb78de5639a180747fb290c28912beaaf1615709)
- [meta] create FUNDING.yml; add `funding` in package.json [`11c22e6`](https://github.com/ljharb/gopd/commit/11c22e6355bb01f24e7fac4c9bb3055eb5b25002)
- [meta] use `npmignore` to autogenerate an npmignore file [`4f4537a`](https://github.com/ljharb/gopd/commit/4f4537a843b39f698c52f072845092e6fca345bb)
- Only apps should have lockfiles [`c567022`](https://github.com/ljharb/gopd/commit/c567022a18573aa7951cf5399445d9840e23e98b)


---

# gopd <sup>[![Version Badge][npm-version-svg]][package-url]</sup>

[![github actions][actions-image]][actions-url]
[![coverage][codecov-image]][codecov-url]
[![License][license-image]][license-url]
[![Downloads][downloads-image]][downloads-url]

[![npm badge][npm-badge-png]][package-url]

`Object.getOwnPropertyDescriptor`, but accounts for IE's broken implementation.

## Usage

```javascript
var gOPD = require('gopd');
var assert = require('assert');

if (gOPD) {
	assert.equal(typeof gOPD, 'function', 'descriptors supported');
	// use gOPD like Object.getOwnPropertyDescriptor here
} else {
	assert.ok(!gOPD, 'descriptors not supported');
}
```

[package-url]: https://npmjs.org/package/gopd
[npm-version-svg]: https://versionbadg.es/ljharb/gopd.svg
[deps-svg]: https://david-dm.org/ljharb/gopd.svg
[deps-url]: https://david-dm.org/ljharb/gopd
[dev-deps-svg]: https://david-dm.org/ljharb/gopd/dev-status.svg
[dev-deps-url]: https://david-dm.org/ljharb/gopd#info=devDependencies
[npm-badge-png]: https://nodei.co/npm/gopd.png?downloads=true&stars=true
[license-image]: https://img.shields.io/npm/l/gopd.svg
[license-url]: LICENSE
[downloads-image]: https://img.shields.io/npm/dm/gopd.svg
[downloads-url]: https://npm-stat.com/charts.html?package=gopd
[codecov-image]: https://codecov.io/gh/ljharb/gopd/branch/main/graphs/badge.svg
[codecov-url]: https://app.codecov.io/gh/ljharb/gopd/
[actions-image]: https://img.shields.io/endpoint?url=https://github-actions-badge-u3jn4tfpocch.runkit.sh/ljharb/gopd
[actions-url]: https://github.com/ljharb/gopd/actions


---

# is

> Type check values

For example, `is.string('🦄') //=> true`

<img src="header.gif" width="182" align="right">

## Highlights

- Written in TypeScript
- [Extensive use of type guards](#type-guards)
- [Supports type assertions](#type-assertions)
- [Aware of generic type parameters](#generic-type-parameters) (use with caution)
- Actively maintained
- ![Millions of downloads per week](https://img.shields.io/npm/dw/@sindresorhus/is)

## Install

```sh
npm install @sindresorhus/is
```

## Usage

```js
import is from '@sindresorhus/is';

is('🦄');
//=> 'string'

is(new Map());
//=> 'Map'

is.number(6);
//=> true
```

[Assertions](#type-assertions) perform the same type checks, but throw an error if the type does not match.

```js
import {assert} from '@sindresorhus/is';

assert.string(2);
//=> Error: Expected value which is `string`, received value of type `number`.
```

And with TypeScript:

```ts
import {assert} from '@sindresorhus/is';

assert.string(foo);
// `foo` is now typed as a `string`.
```

## API

### is(value)

Returns the type of `value`.

Primitives are lowercase and object types are camelcase.

Example:

- `'undefined'`
- `'null'`
- `'string'`
- `'symbol'`
- `'Array'`
- `'Function'`
- `'Object'`

Note: It will throw an error if you try to feed it object-wrapped primitives, as that's a bad practice. For example `new String('foo')`.

### is.{method}

All the below methods accept a value and returns a boolean for whether the value is of the desired type.

#### Primitives

##### .undefined(value)
##### .null(value)

**Note:** TypeScript users must use `.null_()` because of a TypeScript naming limitation.

##### .string(value)
##### .number(value)

Note: `is.number(NaN)` returns `false`. This intentionally deviates from `typeof` behavior to increase user-friendliness of `is` type checks.

##### .boolean(value)
##### .symbol(value)
##### .bigint(value)

#### Built-in types

##### .array(value, assertion?)

Returns true if `value` is an array and all of its items match the assertion (if provided).

```js
is.array(value); // Validate `value` is an array.
is.array(value, is.number); // Validate `value` is an array and all of its items are numbers.
```

##### .function(value)

**Note:** TypeScript users must use `.function_()` because of a TypeScript naming limitation.

##### .buffer(value)
##### .blob(value)
##### .object(value)

Keep in mind that [functions are objects too](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions).

##### .numericString(value)

Returns `true` for a string that represents a number satisfying `is.number`, for example, `'42'` and `'-8.3'`.

Note: `'NaN'` returns `false`, but `'Infinity'` and `'-Infinity'` return `true`.

##### .regExp(value)
##### .date(value)
##### .error(value)
##### .nativePromise(value)
##### .promise(value)

Returns `true` for any object with a `.then()` and `.catch()` method. Prefer this one over `.nativePromise()` as you usually want to allow userland promise implementations too.

##### .generator(value)

Returns `true` for any object that implements its own `.next()` and `.throw()` methods and has a function definition for `Symbol.iterator`.

##### .generatorFunction(value)

##### .asyncFunction(value)

Returns `true` for any `async` function that can be called with the `await` operator.

```js
is.asyncFunction(async () => {});
//=> true

is.asyncFunction(() => {});
//=> false
```

##### .asyncGenerator(value)

```js
is.asyncGenerator(
	(async function * () {
		yield 4;
	})()
);
//=> true

is.asyncGenerator(
	(function * () {
		yield 4;
	})()
);
//=> false
```

##### .asyncGeneratorFunction(value)

```js
is.asyncGeneratorFunction(async function * () {
	yield 4;
});
//=> true

is.asyncGeneratorFunction(function * () {
	yield 4;
});
//=> false
```

##### .boundFunction(value)

Returns `true` for any `bound` function.

```js
is.boundFunction(() => {});
//=> true

is.boundFunction(function () {}.bind(null));
//=> true

is.boundFunction(function () {});
//=> false
```

##### .map(value)
##### .set(value)
##### .weakMap(value)
##### .weakSet(value)
##### .weakRef(value)

#### Typed arrays

##### .int8Array(value)
##### .uint8Array(value)
##### .uint8ClampedArray(value)
##### .int16Array(value)
##### .uint16Array(value)
##### .int32Array(value)
##### .uint32Array(value)
##### .float32Array(value)
##### .float64Array(value)
##### .bigInt64Array(value)
##### .bigUint64Array(value)

#### Structured data

##### .arrayBuffer(value)
##### .sharedArrayBuffer(value)
##### .dataView(value)

##### .enumCase(value, enum)

TypeScript-only. Returns `true` if `value` is a member of `enum`.

```ts
enum Direction {
	Ascending = 'ascending',
	Descending = 'descending'
}

is.enumCase('ascending', Direction);
//=> true

is.enumCase('other', Direction);
//=> false
```

#### Emptiness

##### .emptyString(value)

Returns `true` if the value is a `string` and the `.length` is 0.

##### .emptyStringOrWhitespace(value)

Returns `true` if `is.emptyString(value)` or if it's a `string` that is all whitespace.

##### .nonEmptyString(value)

Returns `true` if the value is a `string` and the `.length` is more than 0.

##### .nonEmptyStringAndNotWhitespace(value)

Returns `true` if the value is a `string` that is not empty and not whitespace.

```js
const values = ['property1', '', null, 'property2', '    ', undefined];

values.filter(is.nonEmptyStringAndNotWhitespace);
//=> ['property1', 'property2']
```

##### .emptyArray(value)

Returns `true` if the value is an `Array` and the `.length` is 0.

##### .nonEmptyArray(value)

Returns `true` if the value is an `Array` and the `.length` is more than 0.

##### .emptyObject(value)

Returns `true` if the value is an `Object` and `Object.keys(value).length` is 0.

Please note that `Object.keys` returns only own enumerable properties. Hence something like this can happen:

```js
const object1 = {};

Object.defineProperty(object1, 'property1', {
	value: 42,
	writable: true,
	enumerable: false,
	configurable: true
});

is.emptyObject(object1);
//=> true
```

##### .nonEmptyObject(value)

Returns `true` if the value is an `Object` and `Object.keys(value).length` is more than 0.

##### .emptySet(value)

Returns `true` if the value is a `Set` and the `.size` is 0.

##### .nonEmptySet(Value)

Returns `true` if the value is a `Set` and the `.size` is more than 0.

##### .emptyMap(value)

Returns `true` if the value is a `Map` and the `.size` is 0.

##### .nonEmptyMap(value)

Returns `true` if the value is a `Map` and the `.size` is more than 0.

#### Miscellaneous

##### .directInstanceOf(value, class)

Returns `true` if `value` is a direct instance of `class`.

```js
is.directInstanceOf(new Error(), Error);
//=> true

class UnicornError extends Error {}

is.directInstanceOf(new UnicornError(), Error);
//=> false
```

##### .urlInstance(value)

Returns `true` if `value` is an instance of the [`URL` class](https://developer.mozilla.org/en-US/docs/Web/API/URL).

```js
const url = new URL('https://example.com');

is.urlInstance(url);
//=> true
```

##### .urlString(value)

Returns `true` if `value` is a URL string.

Note: this only does basic checking using the [`URL` class](https://developer.mozilla.org/en-US/docs/Web/API/URL) constructor.

```js
const url = 'https://example.com';

is.urlString(url);
//=> true

is.urlString(new URL(url));
//=> false
```

##### .truthy(value)

Returns `true` for all values that evaluate to true in a boolean context:

```js
is.truthy('🦄');
//=> true

is.truthy(undefined);
//=> false
```

##### .falsy(value)

Returns `true` if `value` is one of: `false`, `0`, `''`, `null`, `undefined`, `NaN`.

##### .nan(value)
##### .nullOrUndefined(value)
##### .primitive(value)

JavaScript primitives are as follows: `null`, `undefined`, `string`, `number`, `boolean`, `symbol`.

##### .integer(value)

##### .safeInteger(value)

Returns `true` if `value` is a [safe integer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isSafeInteger).

##### .plainObject(value)

An object is plain if it's created by either `{}`, `new Object()`, or `Object.create(null)`.

##### .iterable(value)
##### .asyncIterable(value)
##### .class(value)

Returns `true` for instances created by a class.

**Note:** TypeScript users must use `.class_()` because of a TypeScript naming limitation.

##### .typedArray(value)

##### .arrayLike(value)

A `value` is array-like if it is not a function and has a `value.length` that is a safe integer greater than or equal to 0.

```js
is.arrayLike(document.forms);
//=> true

function foo() {
	is.arrayLike(arguments);
	//=> true
}
foo();
```

##### .tupleLike(value, guards)

A `value` is tuple-like if it matches the provided `guards` array both in `.length` and in types.

```js
is.tupleLike([1], [is.number]);
//=> true
```

```js
function foo() {
	const tuple = [1, '2', true];
	if (is.tupleLike(tuple, [is.number, is.string, is.boolean])) {
		tuple // [number, string, boolean]
	}
}

foo();
```

#### .positiveNumber(value)

Check if `value` is a number and is more than 0.

#### .negativeNumber(value)

Check if `value` is a number and is less than 0.

##### .inRange(value, range)

Check if `value` (number) is in the given `range`. The range is an array of two values, lower bound and upper bound, in no specific order.

```js
is.inRange(3, [0, 5]);
is.inRange(3, [5, 0]);
is.inRange(0, [-2, 2]);
```

##### .inRange(value, upperBound)

Check if `value` (number) is in the range of `0` to `upperBound`.

```js
is.inRange(3, 10);
```

##### .domElement(value)

Returns `true` if `value` is a DOM Element.

##### .nodeStream(value)

Returns `true` if `value` is a Node.js [stream](https://nodejs.org/api/stream.html).

```js
import fs from 'node:fs';

is.nodeStream(fs.createReadStream('unicorn.png'));
//=> true
```

##### .observable(value)

Returns `true` if `value` is an `Observable`.

```js
import {Observable} from 'rxjs';

is.observable(new Observable());
//=> true
```

##### .infinite(value)

Check if `value` is `Infinity` or `-Infinity`.

##### .evenInteger(value)

Returns `true` if `value` is an even integer.

##### .oddInteger(value)

Returns `true` if `value` is an odd integer.

##### .propertyKey(value)

Returns `true` if `value` can be used as an object property key (either `string`, `number`, or `symbol`).

##### .formData(value)

Returns `true` if `value` is an instance of the [`FormData` class](https://developer.mozilla.org/en-US/docs/Web/API/FormData).

```js
const data = new FormData();

is.formData(data);
//=> true
```

##### .urlSearchParams(value)

Returns `true` if `value` is an instance of the [`URLSearchParams` class](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams).

```js
const searchParams = new URLSearchParams();

is.urlSearchParams(searchParams);
//=> true
```

##### .any(predicate | predicate[], ...values)

Using a single `predicate` argument, returns `true` if **any** of the input `values` returns true in the `predicate`:

```js
is.any(is.string, {}, true, '🦄');
//=> true

is.any(is.boolean, 'unicorns', [], new Map());
//=> false
```

Using an array of `predicate[]`, returns `true` if **any** of the input `values` returns true for **any** of the `predicates` provided in an array:

```js
is.any([is.string, is.number], {}, true, '🦄');
//=> true

is.any([is.boolean, is.number], 'unicorns', [], new Map());
//=> false
```

##### .all(predicate, ...values)

Returns `true` if **all** of the input `values` returns true in the `predicate`:

```js
is.all(is.object, {}, new Map(), new Set());
//=> true

is.all(is.string, '🦄', [], 'unicorns');
//=> false
```

## Type guards

When using `is` together with TypeScript, [type guards](http://www.typescriptlang.org/docs/handbook/advanced-types.html#type-guards-and-differentiating-types) are being used extensively to infer the correct type inside if-else statements.

```ts
import is from '@sindresorhus/is';

const padLeft = (value: string, padding: string | number) => {
	if (is.number(padding)) {
		// `padding` is typed as `number`
		return Array(padding + 1).join(' ') + value;
	}

	if (is.string(padding)) {
		// `padding` is typed as `string`
		return padding + value;
	}

	throw new TypeError(`Expected 'padding' to be of type 'string' or 'number', got '${is(padding)}'.`);
}

padLeft('🦄', 3);
//=> '   🦄'

padLeft('🦄', '🌈');
//=> '🌈🦄'
```

## Type assertions

The type guards are also available as [type assertions](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions), which throw an error for unexpected types. It is a convenient one-line version of the often repetitive "if-not-expected-type-throw" pattern.

```ts
import {assert} from '@sindresorhus/is';

const handleMovieRatingApiResponse = (response: unknown) => {
	assert.plainObject(response);
	// `response` is now typed as a plain `object` with `unknown` properties.

	assert.number(response.rating);
	// `response.rating` is now typed as a `number`.

	assert.string(response.title);
	// `response.title` is now typed as a `string`.

	return `${response.title} (${response.rating * 10})`;
};

handleMovieRatingApiResponse({rating: 0.87, title: 'The Matrix'});
//=> 'The Matrix (8.7)'

// This throws an error.
handleMovieRatingApiResponse({rating: '🦄'});
```

## Generic type parameters

The type guards and type assertions are aware of [generic type parameters](https://www.typescriptlang.org/docs/handbook/generics.html), such as `Promise<T>` and `Map<Key, Value>`. The default is `unknown` for most cases, since `is` cannot check them at runtime. If the generic type is known at compile-time, either implicitly (inferred) or explicitly (provided), `is` propagates the type so it can be used later.

Use generic type parameters with caution. They are only checked by the TypeScript compiler, and not checked by `is` at runtime. This can lead to unexpected behavior, where the generic type is _assumed_ at compile-time, but actually is something completely different at runtime. It is best to use `unknown` (default) and type-check the value of the generic type parameter at runtime with `is` or `assert`.

```ts
import {assert} from '@sindresorhus/is';

async function badNumberAssumption(input: unknown) {
	// Bad assumption about the generic type parameter fools the compile-time type system.
	assert.promise<number>(input);
	// `input` is a `Promise` but only assumed to be `Promise<number>`.

	const resolved = await input;
	// `resolved` is typed as `number` but was not actually checked at runtime.

	// Multiplication will return NaN if the input promise did not actually contain a number.
	return 2 * resolved;
}

async function goodNumberAssertion(input: unknown) {
	assert.promise(input);
	// `input` is typed as `Promise<unknown>`

	const resolved = await input;
	// `resolved` is typed as `unknown`

	assert.number(resolved);
	// `resolved` is typed as `number`

	// Uses runtime checks so only numbers will reach the multiplication.
	return 2 * resolved;
}

badNumberAssumption(Promise.resolve('An unexpected string'));
//=> NaN

// This correctly throws an error because of the unexpected string value.
goodNumberAssertion(Promise.resolve('An unexpected string'));
```

## FAQ

### Why yet another type checking module?

There are hundreds of type checking modules on npm, unfortunately, I couldn't find any that fit my needs:

- Includes both type methods and ability to get the type
- Types of primitives returned as lowercase and object types as camelcase
- Covers all built-ins
- Unsurprising behavior
- Well-maintained
- Comprehensive test suite

For the ones I found, pick 3 of these.

The most common mistakes I noticed in these modules was using `instanceof` for type checking, forgetting that functions are objects, and omitting `symbol` as a primitive.

### Why not just use `instanceof` instead of this package?

`instanceof` does not work correctly for all types and it does not work across [realms](https://stackoverflow.com/a/49832343/64949). Examples of realms are iframes, windows, web workers, and the `vm` module in Node.js.

## For enterprise

Available as part of the Tidelift Subscription.

The maintainers of @sindresorhus/is and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-sindresorhus-is?utm_source=npm-sindresorhus-is&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)

## Related

- [ow](https://github.com/sindresorhus/ow) - Function argument validation for humans
- [is-stream](https://github.com/sindresorhus/is-stream) - Check if something is a Node.js stream
- [is-observable](https://github.com/sindresorhus/is-observable) - Check if a value is an Observable
- [file-type](https://github.com/sindresorhus/file-type) - Detect the file type of a Buffer/Uint8Array
- [is-ip](https://github.com/sindresorhus/is-ip) - Check if a string is an IP address
- [is-array-sorted](https://github.com/sindresorhus/is-array-sorted) - Check if an Array is sorted
- [is-error-constructor](https://github.com/sindresorhus/is-error-constructor) - Check if a value is an error constructor
- [is-empty-iterable](https://github.com/sindresorhus/is-empty-iterable) - Check if an Iterable is empty
- [is-blob](https://github.com/sindresorhus/is-blob) - Check if a value is a Blob - File-like object of immutable, raw data
- [has-emoji](https://github.com/sindresorhus/has-emoji) - Check whether a string has any emoji

## Maintainers

- [Sindre Sorhus](https://github.com/sindresorhus)
- [Giora Guttsait](https://github.com/gioragutt)
- [Brandon Smith](https://github.com/brandon93s)


---

<div align="center">
	<br>
	<br>
	<img width="360" src="media/logo.svg" alt="Got">
	<br>
	<br>
	<br>
	<p>
		<p>
			<sup>
				Sindre's open source work is supported by the community.<br>Special thanks to:
			</sup>
		</p>
		<br>
		<a href="https://retool.com/?utm_campaign=sindresorhus">
			<img src="https://sindresorhus.com/assets/thanks/retool-logo.svg" width="210">
		</a>
		<br>
		<br>
		<a href="https://strapi.io/?ref=sindresorhus">
			<div>
				<img src="https://sindresorhus.com/assets/thanks/strapi-logo-white-bg.png" width="200" alt="Strapi">
			</div>
			<b>Strapi is the leading open-source headless CMS.</b>
			<div>
				<sup>It’s 100% JavaScript, fully customizable, and developer-first.</sup>
			</div>
		</a>
		<br>
		<br>
		<br>
		<a href="https://serpapi.com#gh-light-mode-only">
			<div>
				<img src="https://sindresorhus.com/assets/thanks/serpapi-logo-light.svg" width="130" alt="SerpApi">
			</div>
			<b>API to get search engine results with ease.</b>
		</a>
		<a href="https://serpapi.com#gh-dark-mode-only">
			<div>
				<img src="https://sindresorhus.com/assets/thanks/serpapi-logo-dark.svg" width="120" alt="SerpApi">
			</div>
			<b>API to get search engine results with ease.</b>
		</a>
		<br>
		<br>
		<br>
		<br>
		<a href="https://dutchis.net/?ref=sindresorhus#gh-light-mode-only">
			<div>
				<img src="https://sindresorhus.com/assets/thanks/dutchis-logo-light.png" width="200" alt="DutchIS">
			</div>
			<br>
			<b>VPS hosting with taste 😛</b>
		</a>
		<a href="https://dutchis.net/?ref=sindresorhus#gh-dark-mode-only">
			<div>
				<img src="https://sindresorhus.com/assets/thanks/dutchis-logo-dark.png" width="200" alt="DutchIS">
			</div>
			<br>
			<b>VPS hosting with taste 😛</b>
		</a>
		<br>
		<br>
		<br>
		<br>
		<br>
		<br>
	</p>
	<br>
	<br>
</div>

> Human-friendly and powerful HTTP request library for Node.js

<!-- [![Coverage Status](https://codecov.io/gh/sindresorhus/got/branch/main/graph/badge.svg)](https://codecov.io/gh/sindresorhus/got/branch/main) -->
[![Downloads](https://img.shields.io/npm/dm/got.svg)](https://npmjs.com/got)
[![Install size](https://packagephobia.com/badge?p=got)](https://packagephobia.com/result?p=got)

[See how Got compares to other HTTP libraries](#comparison)

---

For browser usage, we recommend [Ky](https://github.com/sindresorhus/ky) by the same people.

---

**Support questions should be asked [here](https://github.com/sindresorhus/got/discussions).**

## Install

```sh
npm install got
```

**Warning:** This package is native [ESM](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) and no longer provides a CommonJS export. If your project uses CommonJS, you will have to [convert to ESM](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c) or use the [dynamic `import()`](https://v8.dev/features/dynamic-import) function. Please don't open issues for questions regarding CommonJS / ESM.

**Got v11 (the previous major version) is no longer maintained and we will not accept any backport requests.**

## Take a peek

**A [quick start](documentation/quick-start.md) guide is available.**

### JSON mode

Got has a dedicated option for handling JSON payload.\
Furthermore, the promise exposes a `.json<T>()` function that returns `Promise<T>`.

```js
import got from 'got';

const {data} = await got.post('https://httpbin.org/anything', {
	json: {
		hello: 'world'
	}
}).json();

console.log(data);
//=> {"hello": "world"}
```

For advanced JSON usage, check out the [`parseJson`](documentation/2-options.md#parsejson) and [`stringifyJson`](documentation/2-options.md#stringifyjson) options.

**For more useful tips like this, visit the [Tips](documentation/tips.md) page.**

## Highlights

- [Used by 8K+ packages and 4M+ repos](https://github.com/sindresorhus/got/network/dependents)
- [Actively maintained](https://github.com/sindresorhus/got/graphs/contributors)
- [Trusted by many companies](#widely-used)

## Documentation

By default, Got will retry on failure. To disable this option, set [`options.retry.limit`](documentation/7-retry.md#retry) to 0.

#### Main API

- [x] [Promise API](documentation/1-promise.md)
- [x] [Options](documentation/2-options.md)
- [x] [Stream API](documentation/3-streams.md)
- [x] [Pagination API](documentation/4-pagination.md)
- [x] [Advanced HTTPS API](documentation/5-https.md)
- [x] [HTTP/2 support](documentation/2-options.md#http2)
- [x] [`Response` class](documentation/3-streams.md#response-2)

#### Timeouts and retries

- [x] [Advanced timeout handling](documentation/6-timeout.md)
- [x] [Retries on failure](documentation/7-retry.md)
- [x] [Errors with metadata](documentation/8-errors.md)

#### Advanced creation

- [x] [Hooks](documentation/9-hooks.md)
- [x] [Instances](documentation/10-instances.md)
- [x] [Progress events & other events](documentation/3-streams.md#events)
- [x] [Plugins](documentation/lets-make-a-plugin.md)
- [x] [Compose](documentation/examples/advanced-creation.js)

#### Cache, Proxy and UNIX sockets

- [x] [RFC compliant caching](documentation/cache.md)
- [x] [Proxy support](documentation/tips.md#proxying)
- [x] [Unix Domain Sockets](documentation/2-options.md#enableunixsockets)

#### Integration

- [x] [TypeScript support](documentation/typescript.md)
- [x] [AWS](documentation/tips.md#aws)
- [x] [Testing](documentation/tips.md#testing)

---

### Migration guides

- [Request migration guide](documentation/migration-guides/request.md)
  - [*(Note that Request is unmaintained)*](https://github.com/request/request/issues/3142)
- [Axios](documentation/migration-guides/axios.md)
- [Node.js](documentation/migration-guides/nodejs.md)

## Got plugins

- [`got4aws`](https://github.com/SamVerschueren/got4aws) - Got convenience wrapper to interact with AWS v4 signed APIs
- [`gh-got`](https://github.com/sindresorhus/gh-got) - Got convenience wrapper to interact with the GitHub API
- [`gl-got`](https://github.com/singapore/gl-got) - Got convenience wrapper to interact with the GitLab API
- [`gotql`](https://github.com/khaosdoctor/gotql) - Got convenience wrapper to interact with GraphQL using JSON-parsed queries instead of strings
- [`got-fetch`](https://github.com/alexghr/got-fetch) - Got with a [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) interface
- [`got-scraping`](https://github.com/apify/got-scraping) - Got wrapper specifically designed for web scraping purposes
- [`got-ssrf`](https://github.com/JaneJeon/got-ssrf) - Got wrapper to protect server-side requests against SSRF attacks

### Legacy

- [travis-got](https://github.com/samverschueren/travis-got) - Got convenience wrapper to interact with the Travis API
- [graphql-got](https://github.com/kevva/graphql-got) - Got convenience wrapper to interact with GraphQL

## Comparison

|                       | `got`               | [`node-fetch`][n0]   | [`ky`][k0]               | [`axios`][a0]      | [`superagent`][s0]     |
|-----------------------|:-------------------:|:--------------------:|:------------------------:|:------------------:|:----------------------:|
| HTTP/2 support        | :heavy_check_mark:¹ | :x:                  | :x:                      | :x:                | :heavy_check_mark:\*\* |
| Browser support       | :x:                 | :heavy_check_mark:\* | :heavy_check_mark:       | :heavy_check_mark: | :heavy_check_mark:     |
| Promise API           | :heavy_check_mark:  | :heavy_check_mark:   | :heavy_check_mark:       | :heavy_check_mark: | :heavy_check_mark:     |
| Stream API            | :heavy_check_mark:  | Node.js only         | :x:                      | :x:                | :heavy_check_mark:     |
| Pagination API        | :heavy_check_mark:  | :x:                  | :x:                      | :x:                | :x:                    |
| Request cancelation   | :heavy_check_mark:  | :heavy_check_mark:   | :heavy_check_mark:       | :heavy_check_mark: | :heavy_check_mark:     |
| RFC compliant caching | :heavy_check_mark:  | :x:                  | :x:                      | :x:                | :x:                    |
| Cookies (out-of-box)  | :heavy_check_mark:  | :x:                  | :x:                      | :x:                | :x:                    |
| Follows redirects     | :heavy_check_mark:  | :heavy_check_mark:   | :heavy_check_mark:       | :heavy_check_mark: | :heavy_check_mark:     |
| Retries on failure    | :heavy_check_mark:  | :x:                  | :heavy_check_mark:       | :x:                | :heavy_check_mark:     |
| Progress events       | :heavy_check_mark:  | :x:                  | :heavy_check_mark:\*\*\* | Browser only       | :heavy_check_mark:     |
| Handles gzip/deflate  | :heavy_check_mark:  | :heavy_check_mark:   | :heavy_check_mark:       | :heavy_check_mark: | :heavy_check_mark:     |
| Advanced timeouts     | :heavy_check_mark:  | :x:                  | :x:                      | :x:                | :x:                    |
| Timings               | :heavy_check_mark:  | :x:                  | :x:                      | :x:                | :x:                    |
| Errors with metadata  | :heavy_check_mark:  | :x:                  | :heavy_check_mark:       | :heavy_check_mark: | :x:                    |
| JSON mode             | :heavy_check_mark:  | :heavy_check_mark:   | :heavy_check_mark:       | :heavy_check_mark: | :heavy_check_mark:     |
| Custom defaults       | :heavy_check_mark:  | :x:                  | :heavy_check_mark:       | :heavy_check_mark: | :x:                    |
| Composable            | :heavy_check_mark:  | :x:                  | :x:                      | :x:                | :heavy_check_mark:     |
| Hooks                 | :heavy_check_mark:  | :x:                  | :heavy_check_mark:       | :heavy_check_mark: | :x:                    |
| Issues open           | [![][gio]][g1]      | [![][nio]][n1]       | [![][kio]][k1]           | [![][aio]][a1]     | [![][sio]][s1]         |
| Issues closed         | [![][gic]][g2]      | [![][nic]][n2]       | [![][kic]][k2]           | [![][aic]][a2]     | [![][sic]][s2]         |
| Downloads             | [![][gd]][g3]       | [![][nd]][n3]        | [![][kd]][k3]            | [![][ad]][a3]      | [![][sd]][s3]          |
| Coverage              | TBD                 | [![][nc]][n4]        | [![][kc]][k4]            | [![][ac]][a4]      | [![][sc]][s4]          |
| Build                 | [![][gb]][g5]       | [![][nb]][n5]        | [![][kb]][k5]            | [![][ab]][a5]      | [![][sb]][s5]          |
| Bugs                  | [![][gbg]][g6]      | [![][nbg]][n6]       | [![][kbg]][k6]           | [![][abg]][a6]     | [![][sbg]][s6]         |
| Dependents            | [![][gdp]][g7]      | [![][ndp]][n7]       | [![][kdp]][k7]           | [![][adp]][a7]     | [![][sdp]][s7]         |
| Install size          | [![][gis]][g8]      | [![][nis]][n8]       | [![][kis]][k8]           | [![][ais]][a8]     | [![][sis]][s8]         |
| GitHub stars          | [![][gs]][g9]       | [![][ns]][n9]        | [![][ks]][k9]            | [![][as]][a9]      | [![][ss]][s9]          |
| TypeScript support    | [![][gts]][g10]     | [![][nts]][n10]      | [![][kts]][k10]          | [![][ats]][a10]    | [![][sts]][s11]        |
| Last commit           | [![][glc]][g11]     | [![][nlc]][n11]      | [![][klc]][k11]          | [![][alc]][a11]    | [![][slc]][s11]        |

\* It's almost API compatible with the browser `fetch` API.\
\*\* Need to switch the protocol manually. Doesn't accept PUSH streams and doesn't reuse HTTP/2 sessions.\
\*\*\* Currently, only `DownloadProgress` event is supported, `UploadProgress` event is not supported.\
¹ Requires Node.js 15.10.0 or above.\
:sparkle: Almost-stable feature, but the API may change. Don't hesitate to try it out!\
:grey_question: Feature in early stage of development. Very experimental.

<!-- GITHUB -->
[k0]: https://github.com/sindresorhus/ky
[n0]: https://github.com/node-fetch/node-fetch
[a0]: https://github.com/axios/axios
[s0]: https://github.com/visionmedia/superagent

<!-- ISSUES OPEN -->
[gio]: https://img.shields.io/github/issues-raw/sindresorhus/got?color=gray&label
[kio]: https://img.shields.io/github/issues-raw/sindresorhus/ky?color=gray&label
[nio]: https://img.shields.io/github/issues-raw/bitinn/node-fetch?color=gray&label
[aio]: https://img.shields.io/github/issues-raw/axios/axios?color=gray&label
[sio]: https://img.shields.io/github/issues-raw/visionmedia/superagent?color=gray&label

[g1]: https://github.com/sindresorhus/got/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc
[k1]: https://github.com/sindresorhus/ky/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc
[n1]: https://github.com/bitinn/node-fetch/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc
[a1]: https://github.com/axios/axios/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc
[s1]: https://github.com/visionmedia/superagent/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc

<!-- ISSUES CLOSED -->
[gic]: https://img.shields.io/github/issues-closed-raw/sindresorhus/got?color=blue&label
[kic]: https://img.shields.io/github/issues-closed-raw/sindresorhus/ky?color=blue&label
[nic]: https://img.shields.io/github/issues-closed-raw/bitinn/node-fetch?color=blue&label
[aic]: https://img.shields.io/github/issues-closed-raw/axios/axios?color=blue&label
[sic]: https://img.shields.io/github/issues-closed-raw/visionmedia/superagent?color=blue&label

[g2]: https://github.com/sindresorhus/got/issues?q=is%3Aissue+is%3Aclosed+sort%3Aupdated-desc
[k2]: https://github.com/sindresorhus/ky/issues?q=is%3Aissue+is%3Aclosed+sort%3Aupdated-desc
[n2]: https://github.com/bitinn/node-fetch/issues?q=is%3Aissue+is%3Aclosed+sort%3Aupdated-desc
[a2]: https://github.com/axios/axios/issues?q=is%3Aissue+is%3Aclosed+sort%3Aupdated-desc
[s2]: https://github.com/visionmedia/superagent/issues?q=is%3Aissue+is%3Aclosed+sort%3Aupdated-desc

<!-- DOWNLOADS -->
[gd]: https://img.shields.io/npm/dm/got?color=darkgreen&label
[kd]: https://img.shields.io/npm/dm/ky?color=darkgreen&label
[nd]: https://img.shields.io/npm/dm/node-fetch?color=darkgreen&label
[ad]: https://img.shields.io/npm/dm/axios?color=darkgreen&label
[sd]: https://img.shields.io/npm/dm/superagent?color=darkgreen&label

[g3]: https://www.npmjs.com/package/got
[k3]: https://www.npmjs.com/package/ky
[n3]: https://www.npmjs.com/package/node-fetch
[a3]: https://www.npmjs.com/package/axios
[s3]: https://www.npmjs.com/package/superagent

<!-- COVERAGE -->
[gc]: https://img.shields.io/coveralls/github/sindresorhus/got?color=0b9062&label
[kc]: https://img.shields.io/codecov/c/github/sindresorhus/ky?color=0b9062&label
[nc]: https://img.shields.io/coveralls/github/bitinn/node-fetch?color=0b9062&label
[ac]: https://img.shields.io/coveralls/github/mzabriskie/axios?color=0b9062&label
[sc]: https://img.shields.io/codecov/c/github/visionmedia/superagent?color=0b9062&label

[g4]: https://coveralls.io/github/sindresorhus/got
[k4]: https://codecov.io/gh/sindresorhus/ky
[n4]: https://coveralls.io/github/bitinn/node-fetch
[a4]: https://coveralls.io/github/mzabriskie/axios
[s4]: https://codecov.io/gh/visionmedia/superagent

<!-- BUILD -->
[gb]: https://github.com/sindresorhus/got/actions/workflows/main.yml/badge.svg
[kb]: https://github.com/sindresorhus/ky/actions/workflows/main.yml/badge.svg
[nb]: https://img.shields.io/travis/bitinn/node-fetch?label
[ab]: https://img.shields.io/travis/axios/axios?label
[sb]: https://img.shields.io/travis/visionmedia/superagent?label

[g5]: https://github.com/sindresorhus/got/actions/workflows/main.yml
[k5]: https://github.com/sindresorhus/ky/actions/workflows/main.yml
[n5]: https://travis-ci.org/github/bitinn/node-fetch
[a5]: https://travis-ci.org/github/axios/axios
[s5]: https://travis-ci.org/github/visionmedia/superagent

<!-- BUGS -->
[gbg]: https://img.shields.io/github/issues-raw/sindresorhus/got/bug?color=darkred&label
[kbg]: https://img.shields.io/github/issues-raw/sindresorhus/ky/bug?color=darkred&label
[nbg]: https://img.shields.io/github/issues-raw/bitinn/node-fetch/bug?color=darkred&label
[abg]: https://img.shields.io/github/issues-raw/axios/axios/bug-fix?color=darkred&label
[sbg]: https://img.shields.io/github/issues-raw/visionmedia/superagent/Bug?color=darkred&label

[g6]: https://github.com/sindresorhus/got/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Abug
[k6]: https://github.com/sindresorhus/ky/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Abug
[n6]: https://github.com/bitinn/node-fetch/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Abug
[a6]: https://github.com/axios/axios/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22bug-fix%22
[s6]: https://github.com/visionmedia/superagent/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3ABug

<!-- DEPENDENTS -->
[gdp]: https://badgen.net/npm/dependents/got?color=orange&label
[kdp]: https://badgen.net/npm/dependents/ky?color=orange&label
[ndp]: https://badgen.net/npm/dependents/node-fetch?color=orange&label
[adp]: https://badgen.net/npm/dependents/axios?color=orange&label
[sdp]: https://badgen.net/npm/dependents/superagent?color=orange&label

[g7]: https://www.npmjs.com/package/got?activeTab=dependents
[k7]: https://www.npmjs.com/package/ky?activeTab=dependents
[n7]: https://www.npmjs.com/package/node-fetch?activeTab=dependents
[a7]: https://www.npmjs.com/package/axios?activeTab=dependents
[s7]: https://www.npmjs.com/package/visionmedia?activeTab=dependents

<!-- INSTALL SIZE -->
[gis]: https://badgen.net/packagephobia/install/got?color=blue&label
[kis]: https://badgen.net/packagephobia/install/ky?color=blue&label
[nis]: https://badgen.net/packagephobia/install/node-fetch?color=blue&label
[ais]: https://badgen.net/packagephobia/install/axios?color=blue&label
[sis]: https://badgen.net/packagephobia/install/superagent?color=blue&label

[g8]: https://packagephobia.com/result?p=got
[k8]: https://packagephobia.com/result?p=ky
[n8]: https://packagephobia.com/result?p=node-fetch
[a8]: https://packagephobia.com/result?p=axios
[s8]: https://packagephobia.com/result?p=superagent

<!-- GITHUB STARS -->
[gs]: https://img.shields.io/github/stars/sindresorhus/got?color=white&label
[ks]: https://img.shields.io/github/stars/sindresorhus/ky?color=white&label
[ns]: https://img.shields.io/github/stars/bitinn/node-fetch?color=white&label
[as]: https://img.shields.io/github/stars/axios/axios?color=white&label
[ss]: https://img.shields.io/github/stars/visionmedia/superagent?color=white&label

[g9]: https://github.com/sindresorhus/got
[k9]: https://github.com/sindresorhus/ky
[n9]: https://github.com/node-fetch/node-fetch
[a9]: https://github.com/axios/axios
[s9]: https://github.com/visionmedia/superagent

<!-- TYPESCRIPT SUPPORT -->
[gts]: https://badgen.net/npm/types/got?label
[kts]: https://badgen.net/npm/types/ky?label
[nts]: https://badgen.net/npm/types/node-fetch?label
[ats]: https://badgen.net/npm/types/axios?label
[sts]: https://badgen.net/npm/types/superagent?label

[g10]: https://github.com/sindresorhus/got
[k10]: https://github.com/sindresorhus/ky
[n10]: https://github.com/node-fetch/node-fetch
[a10]: https://github.com/axios/axios
[s10]: https://github.com/visionmedia/superagent

<!-- LAST COMMIT -->
[glc]: https://img.shields.io/github/last-commit/sindresorhus/got?color=gray&label
[klc]: https://img.shields.io/github/last-commit/sindresorhus/ky?color=gray&label
[nlc]: https://img.shields.io/github/last-commit/bitinn/node-fetch?color=gray&label
[alc]: https://img.shields.io/github/last-commit/axios/axios?color=gray&label
[slc]: https://img.shields.io/github/last-commit/visionmedia/superagent?color=gray&label

[g11]: https://github.com/sindresorhus/got/commits
[k11]: https://github.com/sindresorhus/ky/commits
[n11]: https://github.com/node-fetch/node-fetch/commits
[a11]: https://github.com/axios/axios/commits
[s11]: https://github.com/visionmedia/superagent/commits

[Click here][InstallSizeOfTheDependencies] to see the install size of the Got dependencies.

[InstallSizeOfTheDependencies]: https://packagephobia.com/result?p=@sindresorhus/is@4.0.1,@szmarczak/http-timer@4.0.5,@types/cacheable-request@6.0.1,@types/responselike@1.0.0,cacheable-lookup@6.0.0,cacheable-request@7.0.2,decompress-response@6.0.0,get-stream@6.0.1,http2-wrapper@2.0.5,lowercase-keys@2.0.0,p-cancelable@2.1.1,responselike@2.0.0

## Maintainers

[![Sindre Sorhus](https://github.com/sindresorhus.png?size=100)](https://sindresorhus.com) | [![Szymon Marczak](https://github.com/szmarczak.png?size=100)](https://github.com/szmarczak)
---|---
[Sindre Sorhus](https://sindresorhus.com) | [Szymon Marczak](https://github.com/szmarczak)

###### Former

- [Vsevolod Strukchinsky](https://github.com/floatdrop)
- [Alexander Tesfamichael](https://github.com/alextes)
- [Brandon Smith](https://github.com/brandon93s)
- [Luke Childs](https://github.com/lukechilds)
- [Giovanni Minotti](https://github.com/Giotino)

<a name="widely-used"></a>
## These amazing companies are using Got

<table>
<tbody>
	<tr>
		<td align="center">
			<a href="https://segment.com">
				<img width="90" valign="middle" src="https://user-images.githubusercontent.com/697676/47693700-ddb62500-dbb7-11e8-8332-716a91010c2d.png">
			</a>
		</td>
		<td align="center">
			<a href="https://antora.org">
				<img width="100" valign="middle" src="https://user-images.githubusercontent.com/79351/47706840-d874cc80-dbef-11e8-87c6-5f0c60cbf5dc.png">
			</a>
		</td>
		<td align="center">
			<a href="https://getvoip.com">
				<img width="150" valign="middle" src="https://user-images.githubusercontent.com/10832620/47869404-429e9480-dddd-11e8-8a7a-ca43d7f06020.png">
			</a>
		</td>
		<td align="center">
			<a href="https://github.com/exoframejs/exoframe">
				<img width="150" valign="middle" src="https://user-images.githubusercontent.com/365944/47791460-11a95b80-dd1a-11e8-9070-e8f2a215e03a.png">
			</a>
		</td>
	</tr>
	<tr>
		<td align="center">
			<a href="http://karaokes.moe">
				<img width="140" valign="middle" src="https://camo.githubusercontent.com/6860e5fa4684c14d8e1aa65df0aba4e6808ea1a9/687474703a2f2f6b6172616f6b65732e6d6f652f6173736574732f696d616765732f696e6465782e706e67">
			</a>
		</td>
		<td align="center">
			<a href="https://github.com/renovatebot/renovate">
				<img width="150" valign="middle" src="https://camo.githubusercontent.com/206d470ac709b9a702a97b0c08d6f389a086793d/68747470733a2f2f72656e6f76617465626f742e636f6d2f696d616765732f6c6f676f2e737667">
			</a>
		</td>
		<td align="center">
			<a href="https://resist.bot">
				<img width="150" valign="middle" src="https://user-images.githubusercontent.com/3322287/51992724-28736180-2473-11e9-9764-599cfda4b012.png">
			</a>
		</td>
		<td align="center">
			<a href="https://www.naturalcycles.com">
				<img width="150" valign="middle" src="https://user-images.githubusercontent.com/170270/92244143-d0a8a200-eec2-11ea-9fc0-1c07f90b2113.png">
			</a>
		</td>
	</tr>
	<tr>
		<td align="center">
			<a href="https://microlink.io">
				<img width="150" valign="middle" src="https://user-images.githubusercontent.com/36894700/91992974-1cc5dc00-ed35-11ea-9d04-f58b42ce6a5e.png">
			</a>
		</td>
		<td align="center">
			<a href="https://radity.com">
				<img width="150" valign="middle" src="https://user-images.githubusercontent.com/29518613/91814036-97fb9500-ec44-11ea-8c6c-d198cc23ca29.png">
			</a>
		</td>
		<td align="center">
			<a href="https://apify.com">
				<img width="150" valign="middle" src="https://user-images.githubusercontent.com/23726914/128673143-958b5930-b677-40ef-8087-5698a0c29c45.png">
			</a>
		</td>
	</tr>
</tbody>
</table>

<!-- <br> -->

<!-- *Creating an awesome product? Open an issue to get listed here.* -->

<br>

> Segment is a happy user of Got! Got powers the main backend API that our app talks to. It's used by our in-house RPC client that we use to communicate with all microservices.
>
> — <a href="https://github.com/vadimdemedes">Vadim Demedes</a>

> Antora, a static site generator for creating documentation sites, uses Got to download the UI bundle. In Antora, the UI bundle (aka theme) is maintained as a separate project. That project exports the UI as a zip file we call the UI bundle. The main site generator downloads that UI from a URL using Got and streams it to vinyl-zip to extract the files. Those files go on to be used to create the HTML pages and supporting assets.
>
> — <a href="https://github.com/mojavelinux">Dan Allen</a>

> GetVoIP is happily using Got in production. One of the unique capabilities of Got is the ability to handle Unix sockets which enables us to build a full control interfaces for our docker stack.
>
> — <a href="https://github.com/danielkalen">Daniel Kalen</a>

> We're using Got inside of Exoframe to handle all the communication between CLI and server. Exoframe is a self-hosted tool that allows simple one-command deployments using Docker.
>
> — <a href="https://github.com/yamalight">Tim Ermilov</a>

> Karaoke Mugen uses Got to fetch content updates from its online server.
>
> — <a href="https://github.com/AxelTerizaki">Axel Terizaki</a>

> Renovate uses Got, gh-got and gl-got to send millions of queries per day to GitHub, GitLab, npmjs, PyPi, Packagist, Docker Hub, Terraform, CircleCI, and more.
>
> — <a href="https://github.com/rarkins">Rhys Arkins</a>

> Resistbot uses Got to communicate from the API frontend where all correspondence ingresses to the officials lookup database in back.
>
> — <a href="https://github.com/chris-erickson">Chris Erickson</a>

> Natural Cycles is using Got to communicate with all kinds of 3rd-party REST APIs (over 9000!).
>
> — <a href="https://github.com/kirillgroshkov">Kirill Groshkov</a>

> Microlink is a cloud browser as an API service that uses Got widely as the main HTTP client, serving ~22M requests a month, every time a network call needs to be performed.
>
> — <a href="https://github.com/Kikobeats">Kiko Beats</a>

> We’re using Got at Radity. Thanks for such an amazing work!
>
> — <a href="https://github.com/MirzayevFarid">Mirzayev Farid</a>

> Got has been a crucial component of Apify's scraping for years. We use it to extract data from billions of web pages every month, and we really appreciate the powerful API and extensibility, which allowed us to build our own specialized HTTP client on top of Got. The support has always been stellar too.
>
> — <a href="https://github.com/mnmkng">Ondra Urban</a>

## For enterprise

Available as part of the Tidelift Subscription.

The maintainers of `got` and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-got?utm_source=npm-got&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)


---

# graceful-fs

graceful-fs functions as a drop-in replacement for the fs module,
making various improvements.

The improvements are meant to normalize behavior across different
platforms and environments, and to make filesystem access more
resilient to errors.

## Improvements over [fs module](https://nodejs.org/api/fs.html)

* Queues up `open` and `readdir` calls, and retries them once
  something closes if there is an EMFILE error from too many file
  descriptors.
* fixes `lchmod` for Node versions prior to 0.6.2.
* implements `fs.lutimes` if possible. Otherwise it becomes a noop.
* ignores `EINVAL` and `EPERM` errors in `chown`, `fchown` or
  `lchown` if the user isn't root.
* makes `lchmod` and `lchown` become noops, if not available.
* retries reading a file if `read` results in EAGAIN error.

On Windows, it retries renaming a file for up to one second if `EACCESS`
or `EPERM` error occurs, likely because antivirus software has locked
the directory.

## USAGE

```javascript
// use just like fs
var fs = require('graceful-fs')

// now go and do stuff with it...
fs.readFile('some-file-or-whatever', (err, data) => {
  // Do stuff here.
})
```

## Sync methods

This module cannot intercept or handle `EMFILE` or `ENFILE` errors from sync
methods.  If you use sync methods which open file descriptors then you are
responsible for dealing with any errors.

This is a known limitation, not a bug.

## Global Patching

If you want to patch the global fs module (or any other fs-like
module) you can do this:

```javascript
// Make sure to read the caveat below.
var realFs = require('fs')
var gracefulFs = require('graceful-fs')
gracefulFs.gracefulify(realFs)
```

This should only ever be done at the top-level application layer, in
order to delay on EMFILE errors from any fs-using dependencies.  You
should **not** do this in a library, because it can cause unexpected
delays in other parts of the program.

## Changes

This module is fairly stable at this point, and used by a lot of
things.  That being said, because it implements a subtle behavior
change in a core part of the node API, even modest changes can be
extremely breaking, and the versioning is thus biased towards
bumping the major when in doubt.

The main change between major versions has been switching between
providing a fully-patched `fs` module vs monkey-patching the node core
builtin, and the approach by which a non-monkey-patched `fs` was
created.

The goal is to trade `EMFILE` errors for slower fs operations.  So, if
you try to open a zillion files, rather than crashing, `open`
operations will be queued up and wait for something else to `close`.

There are advantages to each approach.  Monkey-patching the fs means
that no `EMFILE` errors can possibly occur anywhere in your
application, because everything is using the same core `fs` module,
which is patched.  However, it can also obviously cause undesirable
side-effects, especially if the module is loaded multiple times.

Implementing a separate-but-identical patched `fs` module is more
surgical (and doesn't run the risk of patching multiple times), but
also imposes the challenge of keeping in sync with the core module.

The current approach loads the `fs` module, and then creates a
lookalike object that has all the same methods, except a few that are
patched.  It is safe to use in all versions of Node from 0.8 through
7.0.

### v4

* Do not monkey-patch the fs module.  This module may now be used as a
  drop-in dep, and users can opt into monkey-patching the fs builtin
  if their app requires it.

### v3

* Monkey-patch fs, because the eval approach no longer works on recent
  node.
* fixed possible type-error throw if rename fails on windows
* verify that we *never* get EMFILE errors
* Ignore ENOSYS from chmod/chown
* clarify that graceful-fs must be used as a drop-in

### v2.1.0

* Use eval rather than monkey-patching fs.
* readdir: Always sort the results
* win32: requeue a file if error has an OK status

### v2.0

* A return to monkey patching
* wrap process.cwd

### v1.1

* wrap readFile
* Wrap fs.writeFile.
* readdir protection
* Don't clobber the fs builtin
* Handle fs.read EAGAIN errors by trying again
* Expose the curOpen counter
* No-op lchown/lchmod if not implemented
* fs.rename patch only for win32
* Patch fs.rename to handle AV software on Windows
* Close #4 Chown should not fail on einval or eperm if non-root
* Fix isaacs/fstream#1 Only wrap fs one time
* Fix #3 Start at 1024 max files, then back off on EMFILE
* lutimes that doens't blow up on Linux
* A full on-rewrite using a queue instead of just swallowing the EMFILE error
* Wrap Read/Write streams as well

### 1.0

* Update engines for node 0.6
* Be lstat-graceful on Windows
* first


---

# Release history

## 4.0.0 - 2018-04-01

### Breaking changes

- Now requires node v4 or higher. 


## 3.0.0 - 2017-06-30

### Breaking changes

- `toml`, `coffee` and `cson` are no longer supported by default. Please see [`options.engines`](README.md#optionsengines) and the [examples](./examples) to learn how to add engines.

### Added

- Support for [excerpts](README.md#optionsexcerpt).
- The returned object now has non-enumerable `matter` and `stringify` properties.

### Changed

- Refactored engines (parsers), so that it's easier to add parsers and stringifiers.
- `options.parsers` was renamed to [`options.engines`](README.md#optionsengines)


---

# gray-matter [![NPM version](https://img.shields.io/npm/v/gray-matter.svg?style=flat)](https://www.npmjs.com/package/gray-matter) [![NPM monthly downloads](https://img.shields.io/npm/dm/gray-matter.svg?style=flat)](https://npmjs.org/package/gray-matter) [![NPM total downloads](https://img.shields.io/npm/dt/gray-matter.svg?style=flat)](https://npmjs.org/package/gray-matter) [![Linux Build Status](https://img.shields.io/travis/jonschlinkert/gray-matter.svg?style=flat&label=Travis)](https://travis-ci.org/jonschlinkert/gray-matter)

> Parse front-matter from a string or file. Fast, reliable and easy to use. Parses YAML front matter by default, but also has support for YAML, JSON, TOML or Coffee Front-Matter, with options to set custom delimiters. Used by metalsmith, assemble, verb and many other projects.

Please consider following this project's author, [Jon Schlinkert](https://github.com/jonschlinkert), and consider starring the project to show your :heart: and support.

## Install

Install with [npm](https://www.npmjs.com/):

```sh
$ npm install --save gray-matter
```

## Heads up!

Please see the [changelog](CHANGELOG.md) to learn about breaking changes that were made in v3.0.

## What does this do?

<details>
<summary><strong>Run this example</strong></summary>

Add the HTML in the following example to `example.html`, then add the following code to `example.js` and run `$ node example` (without the `$`):

```js
const fs = require('fs');
const matter = require('gray-matter');
const str = fs.readFileSync('example.html', 'utf8');
console.log(matter(str));
```

</details>

Converts a string with front-matter, like this:

```handlebars
---
title: Hello
slug: home
---
<h1>Hello world!</h1>
```

Into an object like this:

```js
{
  content: '<h1>Hello world!</h1>',
  data: { 
    title: 'Hello', 
    slug: 'home' 
  }
}
```

## Why use gray-matter?

* **simple**: main function takes a string and returns an object
* **accurate**: better at catching and handling edge cases than front-matter parsers that rely on regex for parsing
* **fast**: faster than other front-matter parsers that use regex for parsing
* **flexible**: By default, gray-matter is capable of parsing [YAML](https://github.com/nodeca/js-yaml), [JSON](http://en.wikipedia.org/wiki/Json) and JavaScript front-matter. But other [engines](#optionsengines) may be added.
* **extensible**: Use [custom delimiters](#optionsdelimiters), or add support for [any language](#optionsengines), like [TOML](http://github.com/mojombo/toml), [CoffeeScript](http://coffeescript.org), or [CSON](https://github.com/bevry/cson)
* **battle-tested**: used by [assemble](https://github.com/assemble/assemble), [metalsmith](https://github.com/segmentio/metalsmith), [phenomic](https://github.com/phenomic/phenomic), [verb](https://github.com/assemble/verb), [generate](https://github.com/generate/generate), [update](https://github.com/update/update) and many others.

<details>
<summary><strong>Rationale</strong></summary>

**Why did we create gray-matter in the first place?**

We created gray-matter after trying out other libraries that failed to meet our standards and requirements.

Some libraries met most of the requirements, but _none met all of them_.

**Here are the most important**:

* Be usable, if not simple
* Use a dependable and well-supported library for parsing YAML
* Support other languages besides YAML
* Support stringifying back to YAML or another language
* Don't fail when no content exists
* Don't fail when no front matter exists
* Don't use regex for parsing. This is a relatively simple parsing operation, and regex is the slowest and most error-prone way to do it.
* Have no problem reading YAML files directly
* Have no problem with complex content, including **non-front-matter** fenced code blocks that contain examples of YAML front matter. Other parsers fail on this.
* Support stringifying back to front-matter. This is useful for linting, updating properties, etc.
* Allow custom delimiters, when it's necessary for avoiding delimiter collision.
* Should return an object with at least these three properties:
  - `data`: the parsed YAML front matter, as a JSON object
  - `content`: the contents as a string, without the front matter
  - `orig`: the "original" content (for debugging)

</details>

## Usage

Using Node's `require()` system:

```js
const matter = require('gray-matter');
```

Or with [typescript](https://www.typescriptlang.org)

```js
import matter = require('gray-matter');
// OR
import * as matter from 'gray-matter';
```

Pass a string and [options](#options) to gray-matter:

```js
console.log(matter('---\ntitle: Front Matter\n---\nThis is content.'));
```

Returns:

```js
{
  content: '\nThis is content.',
  data: { 
    title: 'Front Matter' 
  } 
}
```

More about the returned object in the following section.

***

## Returned object

gray-matter returns a `file` object with the following properties.

**Enumerable**

* `file.data` **{Object}**: the object created by parsing front-matter
* `file.content` **{String}**: the input string, with `matter` stripped
* `file.excerpt` **{String}**: an excerpt, if [defined on the options](#optionsexcerpt)
* `file.empty` **{String}**: when the front-matter is "empty" (either all whitespace, nothing at all, or just comments and no data), the original string is set on this property. See [#65](https://github.com/jonschlinkert/gray-matter/issues/65) for details regarding use case.
* `file.isEmpty` **{Boolean}**: true if front-matter is empty.

**Non-enumerable**

In addition, the following non-enumberable properties are added to the object to help with debugging.

* `file.orig` **{Buffer}**: the original input string (or buffer)
* `file.language` **{String}**: the front-matter language that was parsed. `yaml` is the default
* `file.matter` **{String}**: the _raw_, un-parsed front-matter string
* `file.stringify` **{Function}**: [stringify](#stringify) the file by converting `file.data` to a string in the given language, wrapping it in delimiters and prepending it to `file.content`.

## Run the examples

If you'd like to test-drive the examples, first clone gray-matter into `my-project` (or wherever you want):

```sh
$ git clone https://github.com/jonschlinkert/gray-matter my-project
```

CD into `my-project` and install dependencies:

```sh
$ cd my-project && npm install
```

Then run any of the [examples](./examples) to see how gray-matter works:

```sh
$ node examples/<example_name>
```

**Links to examples**

* [coffee](examples/coffee.js)
* [excerpt-separator](examples/excerpt-separator.js)
* [excerpt-stringify](examples/excerpt-stringify.js)
* [excerpt](examples/excerpt.js)
* [javascript](examples/javascript.js)
* [json-stringify](examples/json-stringify.js)
* [json](examples/json.js)
* [restore-empty](examples/restore-empty.js)
* [sections-excerpt](examples/sections-excerpt.js)
* [sections](examples/sections.js)
* [toml](examples/toml.js)
* [yaml-stringify](examples/yaml-stringify.js)
* [yaml](examples/yaml.js)

## API

### [matter](index.js#L29)

Takes a string or object with `content` property, extracts and parses front-matter from the string, then returns an object with `data`, `content` and other [useful properties](#returned-object).

**Params**

* `input` **{Object|String}**: String, or object with `content` string
* `options` **{Object}**
* `returns` **{Object}**

**Example**

```js
const matter = require('gray-matter');
console.log(matter('---\ntitle: Home\n---\nOther stuff'));
//=> { data: { title: 'Home'}, content: 'Other stuff' }
```

### [.stringify](index.js#L160)

Stringify an object to YAML or the specified language, and append it to the given string. By default, only YAML and JSON can be stringified. See the [engines](#engines) section to learn how to stringify other languages.

**Params**

* `file` **{String|Object}**: The content string to append to stringified front-matter, or a file object with `file.content` string.
* `data` **{Object}**: Front matter to stringify.
* `options` **{Object}**: [Options](#options) to pass to gray-matter and [js-yaml](https://github.com/nodeca/js-yaml).
* `returns` **{String}**: Returns a string created by wrapping stringified yaml with delimiters, and appending that to the given string.

**Example**

```js
console.log(matter.stringify('foo bar baz', {title: 'Home'}));
// results in:
// ---
// title: Home
// ---
// foo bar baz
```

### [.read](index.js#L178)

Synchronously read a file from the file system and parse front matter. Returns the same object as the [main function](#matter).

**Params**

* `filepath` **{String}**: file path of the file to read.
* `options` **{Object}**: [Options](#options) to pass to gray-matter.
* `returns` **{Object}**: Returns [an object](#returned-object) with `data` and `content`

**Example**

```js
const file = matter.read('./content/blog-post.md');
```

### [.test](index.js#L193)

Returns true if the given `string` has front matter.

**Params**

* `string` **{String}**
* `options` **{Object}**
* `returns` **{Boolean}**: True if front matter exists.

## Options

### options.excerpt

**Type**: `Boolean|Function`

**Default**: `undefined`

Extract an excerpt that directly follows front-matter, or is the first thing in the string if no front-matter exists.

If set to `excerpt: true`, it will look for the frontmatter delimiter, `---` by default and grab everything leading up to it.

**Example**

```js
const str = '---\nfoo: bar\n---\nThis is an excerpt.\n---\nThis is content';
const file = matter(str, { excerpt: true });
```

Results in:

```js
{ 
  content: 'This is an excerpt.\n---\nThis is content',
  data: { foo: 'bar' },
  excerpt: 'This is an excerpt.\n' 
}
```

You can also set `excerpt` to a function. This function uses the 'file' and 'options' that were initially passed to gray-matter as parameters, so you can control how the excerpt is extracted from the content.

**Example**

```js
// returns the first 4 lines of the contents
function firstFourLines(file, options) {
  file.excerpt = file.content.split('\n').slice(0, 4).join(' ');
}

const file =  matter([
  '---',
  'foo: bar',
  '---',
  'Only this',
  'will be',
  'in the',
  'excerpt',
  'but not this...'
].join('\n'), {excerpt: firstFourLines});
```

Results in:

```js
{ 
  content: 'Only this\nwill be\nin the\nexcerpt\nbut not this...',
  data: { foo: 'bar' },
  excerpt: 'Only this will be in the excerpt'
}
```

### options.excerpt_separator

**Type**: `String`

**Default**: `undefined`

Define a custom separator to use for excerpts.

```js
console.log(matter(string, {excerpt_separator: '<!-- end -->'}));
```

**Example**

The following HTML string:

```html
---
title: Blog
---
My awesome blog.
<!-- end -->
<h1>Hello world</h1>
```

Results in:

```js
{ 
  data: { title: 'Blog'}, 
  excerpt: 'My awesome blog.', 
  content: 'My awesome blog.\n<!-- end -->\n<h1>Hello world</h1>' 
}
```

### options.engines

Define custom engines for parsing and/or stringifying front-matter.

**Type**: `Object` Object of engines

**Default**: `JSON`, `YAML` and `JavaScript` are already handled by default.

**Engine format**

Engines may either be an object with `parse` and (optionally) `stringify` methods, or a function that will be used for parsing only.

**Examples**

```js
const toml = require('toml');

/**
 * defined as a function
 */

const file = matter(str, {
  engines: {
    toml: toml.parse.bind(toml),
  }
});

/**
 * Or as an object
 */

const file = matter(str, {
  engines: {
    toml: {
      parse: toml.parse.bind(toml),

      // example of throwing an error to let users know stringifying is
      // not supported (a TOML stringifier might exist, this is just an example)
      stringify: function() {
        throw new Error('cannot stringify to TOML');
      }
    }
  }
});

console.log(file);
```

### options.language

**Type**: `String`

**Default**: `yaml`

Define the engine to use for parsing front-matter.

```js
console.log(matter(string, {language: 'toml'}));
```

**Example**

The following HTML string:

```html
---
title = "TOML"
description = "Front matter"
categories = "front matter toml"
---
This is content
```

Results in:

```js
{ content: 'This is content',
  excerpt: '',
  data:
   { title: 'TOML',
     description: 'Front matter',
     categories: 'front matter toml' } }
```

**Dynamic language detection**

Instead of defining the language on the options, gray-matter will automatically detect the language defined after the first delimiter and select the correct engine to use for parsing.

```html
---toml
title = "TOML"
description = "Front matter"
categories = "front matter toml"
---
This is content
```

### options.delimiters

**Type**: `String`

**Default**: `---`

Open and close delimiters can be passed in as an array of strings.

**Example:**

```js
// format delims as a string
matter.read('file.md', {delims: '~~~'});
// or an array (open/close)
matter.read('file.md', {delims: ['~~~', '~~~']});
```

would parse:

```html
~~~
title: Home
~~~
This is the {{title}} page.
```

## Deprecated options

### options.lang

Decrecated, please use [options.language](#optionslanguage) instead.

### options.delims

Decrecated, please use [options.delimiters](#optionsdelimiters) instead.

### options.parsers

Decrecated, please use [options.engines](#optionsengines) instead.

## About

<details>
<summary><strong>Contributing</strong></summary>

Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).

</details>

<details>
<summary><strong>Running Tests</strong></summary>

Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

```sh
$ npm install && npm test
```

</details>

<details>
<summary><strong>Building docs</strong></summary>

_(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_

To generate the readme, run the following command:

```sh
$ npm install -g verbose/verb#dev verb-generate-readme && verb
```

</details>

### Related projects

You might also be interested in these projects:

* [assemble](https://www.npmjs.com/package/assemble): Get the rocks out of your socks! Assemble makes you fast at creating web projects… [more](https://github.com/assemble/assemble) | [homepage](https://github.com/assemble/assemble "Get the rocks out of your socks! Assemble makes you fast at creating web projects. Assemble is used by thousands of projects for rapid prototyping, creating themes, scaffolds, boilerplates, e-books, UI components, API documentation, blogs, building websit")
* [metalsmith](https://www.npmjs.com/package/metalsmith): An extremely simple, pluggable static site generator. | [homepage](https://github.com/segmentio/metalsmith#readme "An extremely simple, pluggable static site generator.")
* [verb](https://www.npmjs.com/package/verb): Documentation generator for GitHub projects. Verb is extremely powerful, easy to use, and is used… [more](https://github.com/verbose/verb) | [homepage](https://github.com/verbose/verb "Documentation generator for GitHub projects. Verb is extremely powerful, easy to use, and is used on hundreds of projects of all sizes to generate everything from API docs to readmes.")
* [gray-matter-loader](https://github.com/atlassian/gray-matter-loader): A webpack loader for gray-matter. [homepage](https://github.com/atlassian/gray-matter-loader#gray-matter-loader)

### Contributors

| **Commits** | **Contributor** | 
| --- | --- |
| 174 | [jonschlinkert](https://github.com/jonschlinkert) |
| 7 | [RobLoach](https://github.com/RobLoach) |
| 5 | [heymind](https://github.com/heymind) |
| 4 | [doowb](https://github.com/doowb) |
| 3 | [aljopro](https://github.com/aljopro) |
| 2 | [reccanti](https://github.com/reccanti) |
| 2 | [onokumus](https://github.com/onokumus) |
| 2 | [moozzyk](https://github.com/moozzyk) |
| 1 | [Ajedi32](https://github.com/Ajedi32) |
| 1 | [caesar](https://github.com/caesar) |
| 1 | [ianstormtaylor](https://github.com/ianstormtaylor) |
| 1 | [qm3ster](https://github.com/qm3ster) |
| 1 | [zachwhaley](https://github.com/zachwhaley) |

### Author

**Jon Schlinkert**

* [LinkedIn Profile](https://linkedin.com/in/jonschlinkert)
* [GitHub Profile](https://github.com/jonschlinkert)
* [Twitter Profile](https://twitter.com/jonschlinkert)

### License

Copyright © 2018, [Jon Schlinkert](https://github.com/jonschlinkert).
Released under the [MIT License](LICENSE).

***

_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.6.0, on April 01, 2018._

---

1.0.10 / 2018-02-15
------------------

- Use .concat instead of + for arrays, #122.


1.0.9 / 2016-09-29
------------------

- Rerelease after 1.0.8 - deps cleanup.


1.0.8 / 2016-09-29
------------------

- Maintenance (deps bump, fix node 6.5+ tests, coverage report).


1.0.7 / 2016-03-17
------------------

- Teach `addArgument` to accept string arg names. #97, @tomxtobin.


1.0.6 / 2016-02-06
------------------

- Maintenance: moved to eslint & updated CS.


1.0.5 / 2016-02-05
------------------

- Removed lodash dependency to significantly reduce install size.
  Thanks to @mourner.


1.0.4 / 2016-01-17
------------------

- Maintenance: lodash update to 4.0.0.


1.0.3 / 2015-10-27
------------------

- Fix parse `=` in args: `--examplepath="C:\myfolder\env=x64"`. #84, @CatWithApple.


1.0.2 / 2015-03-22
------------------

- Relaxed lodash version dependency.


1.0.1 / 2015-02-20
------------------

- Changed dependencies to be compatible with ancient nodejs.


1.0.0 / 2015-02-19
------------------

- Maintenance release.
- Replaced `underscore` with `lodash`.
- Bumped version to 1.0.0 to better reflect semver meaning.
- HISTORY.md -> CHANGELOG.md


0.1.16 / 2013-12-01
-------------------

- Maintenance release. Updated dependencies and docs.


0.1.15 / 2013-05-13
-------------------

- Fixed #55, @trebor89


0.1.14 / 2013-05-12
-------------------

- Fixed #62, @maxtaco


0.1.13 / 2013-04-08
-------------------

- Added `.npmignore` to reduce package size


0.1.12 / 2013-02-10
-------------------

- Fixed conflictHandler (#46), @hpaulj


0.1.11 / 2013-02-07
-------------------

- Multiple bugfixes, @hpaulj
- Added 70+ tests (ported from python), @hpaulj
- Added conflictHandler, @applepicke
- Added fromfilePrefixChar, @hpaulj


0.1.10 / 2012-12-30
-------------------

- Added [mutual exclusion](http://docs.python.org/dev/library/argparse.html#mutual-exclusion)
  support, thanks to @hpaulj
- Fixed options check for `storeConst` & `appendConst` actions, thanks to @hpaulj


0.1.9 / 2012-12-27
------------------

- Fixed option dest interferens with other options (issue #23), thanks to @hpaulj
- Fixed default value behavior with `*` positionals, thanks to @hpaulj
- Improve `getDefault()` behavior, thanks to @hpaulj
- Imrove negative argument parsing, thanks to @hpaulj


0.1.8 / 2012-12-01
------------------

- Fixed parser parents (issue #19), thanks to @hpaulj
- Fixed negative argument parse (issue #20), thanks to @hpaulj


0.1.7 / 2012-10-14
------------------

- Fixed 'choices' argument parse (issue #16)
- Fixed stderr output (issue #15)


0.1.6 / 2012-09-09
------------------

- Fixed check for conflict of options (thanks to @tomxtobin)


0.1.5 / 2012-09-03
------------------

- Fix parser #setDefaults method (thanks to @tomxtobin)


0.1.4 / 2012-07-30
------------------

- Fixed pseudo-argument support (thanks to @CGamesPlay)
- Fixed addHelp default (should be true), if not set (thanks to @benblank)


0.1.3 / 2012-06-27
------------------

- Fixed formatter api name: Formatter -> HelpFormatter


0.1.2 / 2012-05-29
------------------

- Added basic tests
- Removed excess whitespace in help
- Fixed error reporting, when parcer with subcommands
  called with empty arguments


0.1.1 / 2012-05-23
------------------

- Fixed line wrapping in help formatter
- Added better error reporting on invalid arguments


0.1.0 / 2012-05-16
------------------

- First release.


---

argparse
========

[![Build Status](https://secure.travis-ci.org/nodeca/argparse.svg?branch=master)](http://travis-ci.org/nodeca/argparse)
[![NPM version](https://img.shields.io/npm/v/argparse.svg)](https://www.npmjs.org/package/argparse)

CLI arguments parser for node.js. Javascript port of python's
[argparse](http://docs.python.org/dev/library/argparse.html) module
(original version 3.2). That's a full port, except some very rare options,
recorded in issue tracker.

**NB. Difference with original.**

- Method names changed to camelCase. See [generated docs](http://nodeca.github.com/argparse/).
- Use `defaultValue` instead of `default`.
- Use `argparse.Const.REMAINDER` instead of `argparse.REMAINDER`, and
  similarly for constant values `OPTIONAL`, `ZERO_OR_MORE`, and `ONE_OR_MORE`
  (aliases for `nargs` values `'?'`, `'*'`, `'+'`, respectively), and
  `SUPPRESS`.


Example
=======

test.js file:

```javascript
#!/usr/bin/env node
'use strict';

var ArgumentParser = require('../lib/argparse').ArgumentParser;
var parser = new ArgumentParser({
  version: '0.0.1',
  addHelp:true,
  description: 'Argparse example'
});
parser.addArgument(
  [ '-f', '--foo' ],
  {
    help: 'foo bar'
  }
);
parser.addArgument(
  [ '-b', '--bar' ],
  {
    help: 'bar foo'
  }
);
parser.addArgument(
  '--baz',
  {
    help: 'baz bar'
  }
);
var args = parser.parseArgs();
console.dir(args);
```

Display help:

```
$ ./test.js -h
usage: example.js [-h] [-v] [-f FOO] [-b BAR] [--baz BAZ]

Argparse example

Optional arguments:
  -h, --help         Show this help message and exit.
  -v, --version      Show program's version number and exit.
  -f FOO, --foo FOO  foo bar
  -b BAR, --bar BAR  bar foo
  --baz BAZ          baz bar
```

Parse arguments:

```
$ ./test.js -f=3 --bar=4 --baz 5
{ foo: '3', bar: '4', baz: '5' }
```

More [examples](https://github.com/nodeca/argparse/tree/master/examples).


ArgumentParser objects
======================

```
new ArgumentParser({parameters hash});
```

Creates a new ArgumentParser object.

**Supported params:**

- ```description``` - Text to display before the argument help.
- ```epilog``` - Text to display after the argument help.
- ```addHelp``` - Add a -h/–help option to the parser. (default: true)
- ```argumentDefault``` - Set the global default value for arguments. (default: null)
- ```parents``` - A list of ArgumentParser objects whose arguments should also be included.
- ```prefixChars``` - The set of characters that prefix optional arguments. (default: ‘-‘)
- ```formatterClass``` - A class for customizing the help output.
- ```prog``` - The name of the program (default: `path.basename(process.argv[1])`)
- ```usage``` - The string describing the program usage (default: generated)
- ```conflictHandler``` - Usually unnecessary, defines strategy for resolving conflicting optionals.

**Not supported yet**

- ```fromfilePrefixChars``` - The set of characters that prefix files from which additional arguments should be read.


Details in [original ArgumentParser guide](http://docs.python.org/dev/library/argparse.html#argumentparser-objects)


addArgument() method
====================

```
ArgumentParser.addArgument(name or flag or [name] or [flags...], {options})
```

Defines how a single command-line argument should be parsed.

- ```name or flag or [name] or [flags...]``` - Either a positional name
  (e.g., `'foo'`), a single option (e.g., `'-f'` or `'--foo'`), an array
  of a single positional name (e.g., `['foo']`), or an array of options
  (e.g., `['-f', '--foo']`).

Options:

- ```action``` - The basic type of action to be taken when this argument is encountered at the command line.
- ```nargs```- The number of command-line arguments that should be consumed.
- ```constant``` - A constant value required by some action and nargs selections.
- ```defaultValue``` - The value produced if the argument is absent from the command line.
- ```type``` - The type to which the command-line argument should be converted.
- ```choices``` - A container of the allowable values for the argument.
- ```required``` - Whether or not the command-line option may be omitted (optionals only).
- ```help``` - A brief description of what the argument does.
- ```metavar``` - A name for the argument in usage messages.
- ```dest``` - The name of the attribute to be added to the object returned by parseArgs().

Details in [original add_argument guide](http://docs.python.org/dev/library/argparse.html#the-add-argument-method)


Action (some details)
================

ArgumentParser objects associate command-line arguments with actions.
These actions can do just about anything with the command-line arguments associated
with them, though most actions simply add an attribute to the object returned by
parseArgs(). The action keyword argument specifies how the command-line arguments
should be handled. The supported actions are:

- ```store``` - Just stores the argument’s value. This is the default action.
- ```storeConst``` - Stores value, specified by the const keyword argument.
  (Note that the const keyword argument defaults to the rather unhelpful None.)
  The 'storeConst' action is most commonly used with optional arguments, that
  specify some sort of flag.
- ```storeTrue``` and ```storeFalse``` - Stores values True and False
  respectively. These are special cases of 'storeConst'.
- ```append``` - Stores a list, and appends each argument value to the list.
  This is useful to allow an option to be specified multiple times.
- ```appendConst``` - Stores a list, and appends value, specified by the
  const keyword argument to the list. (Note, that the const keyword argument defaults
  is None.) The 'appendConst' action is typically used when multiple arguments need
  to store constants to the same list.
- ```count``` - Counts the number of times a keyword argument occurs. For example,
  used for increasing verbosity levels.
- ```help``` - Prints a complete help message for all the options in the current
  parser and then exits. By default a help action is automatically added to the parser.
  See ArgumentParser for details of how the output is created.
- ```version``` - Prints version information and exit. Expects a `version=`
  keyword argument in the addArgument() call.

Details in [original action guide](http://docs.python.org/dev/library/argparse.html#action)


Sub-commands
============

ArgumentParser.addSubparsers()

Many programs split their functionality into a number of sub-commands, for
example, the svn program can invoke sub-commands like `svn checkout`, `svn update`,
and `svn commit`. Splitting up functionality this way can be a particularly good
idea when a program performs several different functions which require different
kinds of command-line arguments. `ArgumentParser` supports creation of such
sub-commands with `addSubparsers()` method. The `addSubparsers()` method is
normally called with no arguments and returns an special action object.
This object has a single method `addParser()`, which takes a command name and
any `ArgumentParser` constructor arguments, and returns an `ArgumentParser` object
that can be modified as usual.

Example:

sub_commands.js
```javascript
#!/usr/bin/env node
'use strict';

var ArgumentParser = require('../lib/argparse').ArgumentParser;
var parser = new ArgumentParser({
  version: '0.0.1',
  addHelp:true,
  description: 'Argparse examples: sub-commands',
});

var subparsers = parser.addSubparsers({
  title:'subcommands',
  dest:"subcommand_name"
});

var bar = subparsers.addParser('c1', {addHelp:true});
bar.addArgument(
  [ '-f', '--foo' ],
  {
    action: 'store',
    help: 'foo3 bar3'
  }
);
var bar = subparsers.addParser(
  'c2',
  {aliases:['co'], addHelp:true}
);
bar.addArgument(
  [ '-b', '--bar' ],
  {
    action: 'store',
    type: 'int',
    help: 'foo3 bar3'
  }
);

var args = parser.parseArgs();
console.dir(args);

```

Details in [original sub-commands guide](http://docs.python.org/dev/library/argparse.html#sub-commands)


Contributors
============

- [Eugene Shkuropat](https://github.com/shkuropat)
- [Paul Jacobson](https://github.com/hpaulj)

[others](https://github.com/nodeca/argparse/graphs/contributors)

License
=======

Copyright (c) 2012 [Vitaly Puzrin](https://github.com/puzrin).
Released under the MIT license. See
[LICENSE](https://github.com/nodeca/argparse/blob/master/LICENSE) for details.




---

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).


## [3.14.1] - 2020-12-07
### Security
- Fix possible code execution in (already unsafe) `.load()` (in &anchor).


## [3.14.0] - 2020-05-22
### Changed
- Support `safe/loadAll(input, options)` variant of call.
- CI: drop outdated nodejs versions.
- Dev deps bump.

### Fixed
- Quote `=` in plain scalars #519.
- Check the node type for `!<?>` tag in case user manually specifies it.
- Verify that there are no null-bytes in input.
- Fix wrong quote position when writing condensed flow, #526.


## [3.13.1] - 2019-04-05
### Security
- Fix possible code execution in (already unsafe) `.load()`, #480.


## [3.13.0] - 2019-03-20
### Security
- Security fix: `safeLoad()` can hang when arrays with nested refs
  used as key. Now throws exception for nested arrays. #475.


## [3.12.2] - 2019-02-26
### Fixed
- Fix `noArrayIndent` option for root level, #468.


## [3.12.1] - 2019-01-05
### Added
- Added `noArrayIndent` option, #432.


## [3.12.0] - 2018-06-02
### Changed
- Support arrow functions without a block statement, #421.


## [3.11.0] - 2018-03-05
### Added
- Add arrow functions suport for `!!js/function`.

### Fixed
- Fix dump in bin/octal/hex formats for negative integers, #399.


## [3.10.0] - 2017-09-10
### Fixed
- Fix `condenseFlow` output (quote keys for sure, instead of spaces), #371, #370.
- Dump astrals as codepoints instead of surrogate pair, #368.


## [3.9.1] - 2017-07-08
### Fixed
- Ensure stack is present for custom errors in node 7.+, #351.


## [3.9.0] - 2017-07-08
### Added
- Add `condenseFlow` option (to create pretty URL query params), #346.

### Fixed
- Support array return from safeLoadAll/loadAll, #350.


## [3.8.4] - 2017-05-08
### Fixed
- Dumper: prevent space after dash for arrays that wrap, #343.


## [3.8.3] - 2017-04-05
### Fixed
- Should not allow numbers to begin and end with underscore, #335.


## [3.8.2] - 2017-03-02
### Fixed
- Fix `!!float 123` (integers) parse, #333.
- Don't allow leading zeros in floats (except 0, 0.xxx).
- Allow positive exponent without sign in floats.


## [3.8.1] - 2017-02-07
### Changed
- Maintenance: update browserified build.


## [3.8.0] - 2017-02-07
### Fixed
- Fix reported position for `duplicated mapping key` errors.
  Now points to block start instead of block end.
  (#243, thanks to @shockey).


## [3.7.0] - 2016-11-12
### Added
- Support polymorphism for tags (#300, thanks to @monken).

### Fixed
- Fix parsing of quotes followed by newlines (#304, thanks to @dplepage).


## [3.6.1] - 2016-05-11
### Fixed
- Fix output cut on a pipe, #286.


## [3.6.0] - 2016-04-16
### Fixed
- Dumper rewrite, fix multiple bugs with trailing `\n`.
  Big thanks to @aepsilon!
- Loader: fix leading/trailing newlines in block scalars, @aepsilon.


## [3.5.5] - 2016-03-17
### Fixed
- Date parse fix: don't allow dates with on digit in month and day, #268.


## [3.5.4] - 2016-03-09
### Added
- `noCompatMode` for dumper, to disable quoting YAML 1.1 values.


## [3.5.3] - 2016-02-11
### Changed
- Maintenance release.


## [3.5.2] - 2016-01-11
### Changed
- Maintenance: missed comma in bower config.


## [3.5.1] - 2016-01-11
### Changed
- Removed `inherit` dependency, #239.
- Better browserify workaround for esprima load.
- Demo rewrite.


## [3.5.0] - 2016-01-10
### Fixed
- Dumper. Fold strings only, #217.
- Dumper. `norefs` option, to clone linked objects, #229.
- Loader. Throw a warning for duplicate keys, #166.
- Improved browserify support (mark `esprima` & `Buffer` excluded).


## [3.4.6] - 2015-11-26
### Changed
- Use standalone `inherit` to keep browserified files clear.


## [3.4.5] - 2015-11-23
### Added
- Added `lineWidth` option to dumper.


## [3.4.4] - 2015-11-21
### Fixed
- Fixed floats dump (missed dot for scientific format), #220.
- Allow non-printable characters inside quoted scalars, #192.


## [3.4.3] - 2015-10-10
### Changed
- Maintenance release - deps bump (esprima, argparse).


## [3.4.2] - 2015-09-09
### Fixed
- Fixed serialization of duplicated entries in sequences, #205.
  Thanks to @vogelsgesang.


## [3.4.1] - 2015-09-05
### Fixed
- Fixed stacktrace handling in generated errors, for browsers (FF/IE).


## [3.4.0] - 2015-08-23
### Changed
- Don't throw on warnings anymore. Use `onWarning` option to catch.
- Throw error on unknown tags (was warning before).
- Reworked internals of error class.

### Fixed
- Fixed multiline keys dump, #197. Thanks to @tcr.
- Fixed heading line breaks in some scalars (regression).


## [3.3.1] - 2015-05-13
### Added
- Added `.sortKeys` dumper option, thanks to @rjmunro.

### Fixed
- Fixed astral characters support, #191.


## [3.3.0] - 2015-04-26
### Changed
- Significantly improved long strings formatting in dumper, thanks to @isaacs.
- Strip BOM if exists.


## [3.2.7] - 2015-02-19
### Changed
- Maintenance release.
- Updated dependencies.
- HISTORY.md -> CHANGELOG.md


## [3.2.6] - 2015-02-07
### Fixed
- Fixed encoding of UTF-16 surrogate pairs. (e.g. "\U0001F431" CAT FACE).
- Fixed demo dates dump (#113, thanks to @Hypercubed).


## [3.2.5] - 2014-12-28
### Fixed
- Fixed resolving of all built-in types on empty nodes.
- Fixed invalid warning on empty lines within quoted scalars and flow collections.
- Fixed bug: Tag on an empty node didn't resolve in some cases.


## [3.2.4] - 2014-12-19
### Fixed
- Fixed resolving of !!null tag on an empty node.


## [3.2.3] - 2014-11-08
### Fixed
- Implemented dumping of objects with circular and cross references.
- Partially fixed aliasing of constructed objects. (see issue #141 for details)


## [3.2.2] - 2014-09-07
### Fixed
- Fixed infinite loop on unindented block scalars.
- Rewritten base64 encode/decode in binary type, to keep code licence clear.


## [3.2.1] - 2014-08-24
### Fixed
- Nothig new. Just fix npm publish error.


## [3.2.0] - 2014-08-24
### Added
- Added input piping support to CLI.

### Fixed
- Fixed typo, that could cause hand on initial indent (#139).


## [3.1.0] - 2014-07-07
### Changed
- 1.5x-2x speed boost.
- Removed deprecated `require('xxx.yml')` support.
- Significant code cleanup and refactoring.
- Internal API changed. If you used custom types - see updated examples.
  Others are not affected.
- Even if the input string has no trailing line break character,
  it will be parsed as if it has one.
- Added benchmark scripts.
- Moved bower files to /dist folder
- Bugfixes.


## [3.0.2] - 2014-02-27
### Fixed
- Fixed bug: "constructor" string parsed as `null`.


## [3.0.1] - 2013-12-22
### Fixed
- Fixed parsing of literal scalars. (issue #108)
- Prevented adding unnecessary spaces in object dumps. (issue #68)
- Fixed dumping of objects with very long (> 1024 in length) keys.


## [3.0.0] - 2013-12-16
### Changed
- Refactored code. Changed API for custom types.
- Removed output colors in CLI, dump json by default.
- Removed big dependencies from browser version (esprima, buffer). Load `esprima` manually, if `!!js/function` needed. `!!bin` now returns Array in browser
- AMD support.
- Don't quote dumped strings because of `-` & `?` (if not first char).
- __Deprecated__ loading yaml files via `require()`, as not recommended
  behaviour for node.


## [2.1.3] - 2013-10-16
### Fixed
- Fix wrong loading of empty block scalars.


## [2.1.2] - 2013-10-07
### Fixed
- Fix unwanted line breaks in folded scalars.


## [2.1.1] - 2013-10-02
### Fixed
- Dumper now respects deprecated booleans syntax from YAML 1.0/1.1
- Fixed reader bug in JSON-like sequences/mappings.


## [2.1.0] - 2013-06-05
### Added
- Add standard YAML schemas: Failsafe (`FAILSAFE_SCHEMA`),
  JSON (`JSON_SCHEMA`) and Core (`CORE_SCHEMA`).
- Add `skipInvalid` dumper option.

### Changed
- Rename `DEFAULT_SCHEMA` to `DEFAULT_FULL_SCHEMA`
  and `SAFE_SCHEMA` to `DEFAULT_SAFE_SCHEMA`.
- Use `safeLoad` for `require` extension.

### Fixed
- Bug fix: export `NIL` constant from the public interface.


## [2.0.5] - 2013-04-26
### Security
- Close security issue in !!js/function constructor.
  Big thanks to @nealpoole for security audit.


## [2.0.4] - 2013-04-08
### Changed
- Updated .npmignore to reduce package size


## [2.0.3] - 2013-02-26
### Fixed
- Fixed dumping of empty arrays ans objects. ([] and {} instead of null)


## [2.0.2] - 2013-02-15
### Fixed
- Fixed input validation: tabs are printable characters.


## [2.0.1] - 2013-02-09
### Fixed
- Fixed error, when options not passed to function cass


## [2.0.0] - 2013-02-09
### Changed
- Full rewrite. New architecture. Fast one-stage parsing.
- Changed custom types API.
- Added YAML dumper.


## [1.0.3] - 2012-11-05
### Fixed
- Fixed utf-8 files loading.


## [1.0.2] - 2012-08-02
### Fixed
- Pull out hand-written shims. Use ES5-Shims for old browsers support. See #44.
- Fix timstamps incorectly parsed in local time when no time part specified.


## [1.0.1] - 2012-07-07
### Fixed
- Fixes `TypeError: 'undefined' is not an object` under Safari. Thanks Phuong.
- Fix timestamps incorrectly parsed in local time. Thanks @caolan. Closes #46.


## [1.0.0] - 2012-07-01
### Changed
- `y`, `yes`, `n`, `no`, `on`, `off` are not converted to Booleans anymore.
  Fixes #42.
- `require(filename)` now returns a single document and throws an Error if
  file contains more than one document.
- CLI was merged back from js-yaml.bin


## [0.3.7] - 2012-02-28
### Fixed
- Fix export of `addConstructor()`. Closes #39.


## [0.3.6] - 2012-02-22
### Changed
- Removed AMD parts - too buggy to use. Need help to rewrite from scratch

### Fixed
- Removed YUI compressor warning (renamed `double` variable). Closes #40.


## [0.3.5] - 2012-01-10
### Fixed
- Workagound for .npmignore fuckup under windows. Thanks to airportyh.


## [0.3.4] - 2011-12-24
### Fixed
- Fixes str[] for oldIEs support.
- Adds better has change support for browserified demo.
- improves compact output of Error. Closes #33.


## [0.3.3] - 2011-12-20
### Added
- adds `compact` stringification of Errors.

### Changed
- jsyaml executable moved to separate module.


## [0.3.2] - 2011-12-16
### Added
- Added jsyaml executable.
- Added !!js/function support. Closes #12.

### Fixed
- Fixes ug with block style scalars. Closes #26.
- All sources are passing JSLint now.
- Fixes bug in Safari. Closes #28.
- Fixes bug in Opers. Closes #29.
- Improves browser support. Closes #20.


## [0.3.1] - 2011-11-18
### Added
- Added AMD support for browserified version.
- Added permalinks for online demo YAML snippets. Now we have YPaste service, lol.
- Added !!js/regexp and !!js/undefined types. Partially solves #12.

### Changed
- Wrapped browserified js-yaml into closure.

### Fixed
- Fixed the resolvement of non-specific tags. Closes #17.
- Fixed !!set mapping.
- Fixed month parse in dates. Closes #19.


## [0.3.0] - 2011-11-09
### Added
- Added browserified version. Closes #13.
- Added live demo of browserified version.
- Ported some of the PyYAML tests. See #14.

### Fixed
- Removed JS.Class dependency. Closes #3.
- Fixed timestamp bug when fraction was given.


## [0.2.2] - 2011-11-06
### Fixed
- Fixed crash on docs without ---. Closes #8.
- Fixed multiline string parse
- Fixed tests/comments for using array as key


## [0.2.1] - 2011-11-02
### Fixed
- Fixed short file read (<4k). Closes #9.


## [0.2.0] - 2011-11-02
### Changed
- First public release


[3.14.1]: https://github.com/nodeca/js-yaml/compare/3.14.0...3.14.1
[3.14.0]: https://github.com/nodeca/js-yaml/compare/3.13.1...3.14.0
[3.13.1]: https://github.com/nodeca/js-yaml/compare/3.13.0...3.13.1
[3.13.0]: https://github.com/nodeca/js-yaml/compare/3.12.2...3.13.0
[3.12.2]: https://github.com/nodeca/js-yaml/compare/3.12.1...3.12.2
[3.12.1]: https://github.com/nodeca/js-yaml/compare/3.12.0...3.12.1
[3.12.0]: https://github.com/nodeca/js-yaml/compare/3.11.0...3.12.0
[3.11.0]: https://github.com/nodeca/js-yaml/compare/3.10.0...3.11.0
[3.10.0]: https://github.com/nodeca/js-yaml/compare/3.9.1...3.10.0
[3.9.1]: https://github.com/nodeca/js-yaml/compare/3.9.0...3.9.1
[3.9.0]: https://github.com/nodeca/js-yaml/compare/3.8.4...3.9.0
[3.8.4]: https://github.com/nodeca/js-yaml/compare/3.8.3...3.8.4
[3.8.3]: https://github.com/nodeca/js-yaml/compare/3.8.2...3.8.3
[3.8.2]: https://github.com/nodeca/js-yaml/compare/3.8.1...3.8.2
[3.8.1]: https://github.com/nodeca/js-yaml/compare/3.8.0...3.8.1
[3.8.0]: https://github.com/nodeca/js-yaml/compare/3.7.0...3.8.0
[3.7.0]: https://github.com/nodeca/js-yaml/compare/3.6.1...3.7.0
[3.6.1]: https://github.com/nodeca/js-yaml/compare/3.6.0...3.6.1
[3.6.0]: https://github.com/nodeca/js-yaml/compare/3.5.5...3.6.0
[3.5.5]: https://github.com/nodeca/js-yaml/compare/3.5.4...3.5.5
[3.5.4]: https://github.com/nodeca/js-yaml/compare/3.5.3...3.5.4
[3.5.3]: https://github.com/nodeca/js-yaml/compare/3.5.2...3.5.3
[3.5.2]: https://github.com/nodeca/js-yaml/compare/3.5.1...3.5.2
[3.5.1]: https://github.com/nodeca/js-yaml/compare/3.5.0...3.5.1
[3.5.0]: https://github.com/nodeca/js-yaml/compare/3.4.6...3.5.0
[3.4.6]: https://github.com/nodeca/js-yaml/compare/3.4.5...3.4.6
[3.4.5]: https://github.com/nodeca/js-yaml/compare/3.4.4...3.4.5
[3.4.4]: https://github.com/nodeca/js-yaml/compare/3.4.3...3.4.4
[3.4.3]: https://github.com/nodeca/js-yaml/compare/3.4.2...3.4.3
[3.4.2]: https://github.com/nodeca/js-yaml/compare/3.4.1...3.4.2
[3.4.1]: https://github.com/nodeca/js-yaml/compare/3.4.0...3.4.1
[3.4.0]: https://github.com/nodeca/js-yaml/compare/3.3.1...3.4.0
[3.3.1]: https://github.com/nodeca/js-yaml/compare/3.3.0...3.3.1
[3.3.0]: https://github.com/nodeca/js-yaml/compare/3.2.7...3.3.0
[3.2.7]: https://github.com/nodeca/js-yaml/compare/3.2.6...3.2.7
[3.2.6]: https://github.com/nodeca/js-yaml/compare/3.2.5...3.2.6
[3.2.5]: https://github.com/nodeca/js-yaml/compare/3.2.4...3.2.5
[3.2.4]: https://github.com/nodeca/js-yaml/compare/3.2.3...3.2.4
[3.2.3]: https://github.com/nodeca/js-yaml/compare/3.2.2...3.2.3
[3.2.2]: https://github.com/nodeca/js-yaml/compare/3.2.1...3.2.2
[3.2.1]: https://github.com/nodeca/js-yaml/compare/3.2.0...3.2.1
[3.2.0]: https://github.com/nodeca/js-yaml/compare/3.1.0...3.2.0
[3.1.0]: https://github.com/nodeca/js-yaml/compare/3.0.2...3.1.0
[3.0.2]: https://github.com/nodeca/js-yaml/compare/3.0.1...3.0.2
[3.0.1]: https://github.com/nodeca/js-yaml/compare/3.0.0...3.0.1
[3.0.0]: https://github.com/nodeca/js-yaml/compare/2.1.3...3.0.0
[2.1.3]: https://github.com/nodeca/js-yaml/compare/2.1.2...2.1.3
[2.1.2]: https://github.com/nodeca/js-yaml/compare/2.1.1...2.1.2
[2.1.1]: https://github.com/nodeca/js-yaml/compare/2.1.0...2.1.1
[2.1.0]: https://github.com/nodeca/js-yaml/compare/2.0.5...2.1.0
[2.0.5]: https://github.com/nodeca/js-yaml/compare/2.0.4...2.0.5
[2.0.4]: https://github.com/nodeca/js-yaml/compare/2.0.3...2.0.4
[2.0.3]: https://github.com/nodeca/js-yaml/compare/2.0.2...2.0.3
[2.0.2]: https://github.com/nodeca/js-yaml/compare/2.0.1...2.0.2
[2.0.1]: https://github.com/nodeca/js-yaml/compare/2.0.0...2.0.1
[2.0.0]: https://github.com/nodeca/js-yaml/compare/1.0.3...2.0.0
[1.0.3]: https://github.com/nodeca/js-yaml/compare/1.0.2...1.0.3
[1.0.2]: https://github.com/nodeca/js-yaml/compare/1.0.1...1.0.2
[1.0.1]: https://github.com/nodeca/js-yaml/compare/1.0.0...1.0.1
[1.0.0]: https://github.com/nodeca/js-yaml/compare/0.3.7...1.0.0
[0.3.7]: https://github.com/nodeca/js-yaml/compare/0.3.6...0.3.7
[0.3.6]: https://github.com/nodeca/js-yaml/compare/0.3.5...0.3.6
[0.3.5]: https://github.com/nodeca/js-yaml/compare/0.3.4...0.3.5
[0.3.4]: https://github.com/nodeca/js-yaml/compare/0.3.3...0.3.4
[0.3.3]: https://github.com/nodeca/js-yaml/compare/0.3.2...0.3.3
[0.3.2]: https://github.com/nodeca/js-yaml/compare/0.3.1...0.3.2
[0.3.1]: https://github.com/nodeca/js-yaml/compare/0.3.0...0.3.1
[0.3.0]: https://github.com/nodeca/js-yaml/compare/0.2.2...0.3.0
[0.2.2]: https://github.com/nodeca/js-yaml/compare/0.2.1...0.2.2
[0.2.1]: https://github.com/nodeca/js-yaml/compare/0.2.0...0.2.1
[0.2.0]: https://github.com/nodeca/js-yaml/releases/tag/0.2.0


---

JS-YAML - YAML 1.2 parser / writer for JavaScript
=================================================

[![Build Status](https://travis-ci.org/nodeca/js-yaml.svg?branch=master)](https://travis-ci.org/nodeca/js-yaml)
[![NPM version](https://img.shields.io/npm/v/js-yaml.svg)](https://www.npmjs.org/package/js-yaml)

__[Online Demo](http://nodeca.github.com/js-yaml/)__


This is an implementation of [YAML](http://yaml.org/), a human-friendly data
serialization language. Started as [PyYAML](http://pyyaml.org/) port, it was
completely rewritten from scratch. Now it's very fast, and supports 1.2 spec.


Installation
------------

### YAML module for node.js

```
npm install js-yaml
```


### CLI executable

If you want to inspect your YAML files from CLI, install js-yaml globally:

```
npm install -g js-yaml
```

#### Usage

```
usage: js-yaml [-h] [-v] [-c] [-t] file

Positional arguments:
  file           File with YAML document(s)

Optional arguments:
  -h, --help     Show this help message and exit.
  -v, --version  Show program's version number and exit.
  -c, --compact  Display errors in compact mode
  -t, --trace    Show stack trace on error
```


### Bundled YAML library for browsers

``` html
<!-- esprima required only for !!js/function -->
<script src="esprima.js"></script>
<script src="js-yaml.min.js"></script>
<script type="text/javascript">
var doc = jsyaml.load('greeting: hello\nname: world');
</script>
```

Browser support was done mostly for the online demo. If you find any errors - feel
free to send pull requests with fixes. Also note, that IE and other old browsers
needs [es5-shims](https://github.com/kriskowal/es5-shim) to operate.

Notes:

1. We have no resources to support browserified version. Don't expect it to be
   well tested. Don't expect fast fixes if something goes wrong there.
2. `!!js/function` in browser bundle will not work by default. If you really need
   it - load `esprima` parser first (via amd or directly).
3. `!!bin` in browser will return `Array`, because browsers do not support
   node.js `Buffer` and adding Buffer shims is completely useless on practice.


API
---

Here we cover the most 'useful' methods. If you need advanced details (creating
your own tags), see [wiki](https://github.com/nodeca/js-yaml/wiki) and
[examples](https://github.com/nodeca/js-yaml/tree/master/examples) for more
info.

``` javascript
const yaml = require('js-yaml');
const fs   = require('fs');

// Get document, or throw exception on error
try {
  const doc = yaml.safeLoad(fs.readFileSync('/home/ixti/example.yml', 'utf8'));
  console.log(doc);
} catch (e) {
  console.log(e);
}
```


### safeLoad (string [ , options ])

**Recommended loading way.** Parses `string` as single YAML document. Returns either a
plain object, a string or `undefined`, or throws `YAMLException` on error. By default, does
not support regexps, functions and undefined. This method is safe for untrusted data.

options:

- `filename` _(default: null)_ - string to be used as a file path in
  error/warning messages.
- `onWarning` _(default: null)_ - function to call on warning messages.
  Loader will call this function with an instance of `YAMLException` for each warning.
- `schema` _(default: `DEFAULT_SAFE_SCHEMA`)_ - specifies a schema to use.
  - `FAILSAFE_SCHEMA` - only strings, arrays and plain objects:
    http://www.yaml.org/spec/1.2/spec.html#id2802346
  - `JSON_SCHEMA` - all JSON-supported types:
    http://www.yaml.org/spec/1.2/spec.html#id2803231
  - `CORE_SCHEMA` - same as `JSON_SCHEMA`:
    http://www.yaml.org/spec/1.2/spec.html#id2804923
  - `DEFAULT_SAFE_SCHEMA` - all supported YAML types, without unsafe ones
    (`!!js/undefined`, `!!js/regexp` and `!!js/function`):
    http://yaml.org/type/
  - `DEFAULT_FULL_SCHEMA` - all supported YAML types.
- `json` _(default: false)_ - compatibility with JSON.parse behaviour. If true, then duplicate keys in a mapping will override values rather than throwing an error.

NOTE: This function **does not** understand multi-document sources, it throws
exception on those.

NOTE: JS-YAML **does not** support schema-specific tag resolution restrictions.
So, the JSON schema is not as strictly defined in the YAML specification.
It allows numbers in any notation, use `Null` and `NULL` as `null`, etc.
The core schema also has no such restrictions. It allows binary notation for integers.


### load (string [ , options ])

**Use with care with untrusted sources**. The same as `safeLoad()` but uses
`DEFAULT_FULL_SCHEMA` by default - adds some JavaScript-specific types:
`!!js/function`, `!!js/regexp` and `!!js/undefined`. For untrusted sources, you
must additionally validate object structure to avoid injections:

``` javascript
const untrusted_code = '"toString": !<tag:yaml.org,2002:js/function> "function (){very_evil_thing();}"';

// I'm just converting that string, what could possibly go wrong?
require('js-yaml').load(untrusted_code) + ''
```


### safeLoadAll (string [, iterator] [, options ])

Same as `safeLoad()`, but understands multi-document sources. Applies
`iterator` to each document if specified, or returns array of documents.

``` javascript
const yaml = require('js-yaml');

yaml.safeLoadAll(data, function (doc) {
  console.log(doc);
});
```


### loadAll (string [, iterator] [ , options ])

Same as `safeLoadAll()` but uses `DEFAULT_FULL_SCHEMA` by default.


### safeDump (object [ , options ])

Serializes `object` as a YAML document. Uses `DEFAULT_SAFE_SCHEMA`, so it will
throw an exception if you try to dump regexps or functions. However, you can
disable exceptions by setting the `skipInvalid` option to `true`.

options:

- `indent` _(default: 2)_ - indentation width to use (in spaces).
- `noArrayIndent` _(default: false)_ - when true, will not add an indentation level to array elements
- `skipInvalid` _(default: false)_ - do not throw on invalid types (like function
  in the safe schema) and skip pairs and single values with such types.
- `flowLevel` (default: -1) - specifies level of nesting, when to switch from
  block to flow style for collections. -1 means block style everwhere
- `styles` - "tag" => "style" map. Each tag may have own set of styles.
- `schema` _(default: `DEFAULT_SAFE_SCHEMA`)_ specifies a schema to use.
- `sortKeys` _(default: `false`)_ - if `true`, sort keys when dumping YAML. If a
  function, use the function to sort the keys.
- `lineWidth` _(default: `80`)_ - set max line width.
- `noRefs` _(default: `false`)_ - if `true`, don't convert duplicate objects into references
- `noCompatMode` _(default: `false`)_ - if `true` don't try to be compatible with older
  yaml versions. Currently: don't quote "yes", "no" and so on, as required for YAML 1.1
- `condenseFlow` _(default: `false`)_ - if `true` flow sequences will be condensed, omitting the space between `a, b`. Eg. `'[a,b]'`, and omitting the space between `key: value` and quoting the key. Eg. `'{"a":b}'` Can be useful when using yaml for pretty URL query params as spaces are %-encoded.

The following table show availlable styles (e.g. "canonical",
"binary"...) available for each tag (.e.g. !!null, !!int ...). Yaml
output is shown on the right side after `=>` (default setting) or `->`:

``` none
!!null
  "canonical"   -> "~"
  "lowercase"   => "null"
  "uppercase"   -> "NULL"
  "camelcase"   -> "Null"

!!int
  "binary"      -> "0b1", "0b101010", "0b1110001111010"
  "octal"       -> "01", "052", "016172"
  "decimal"     => "1", "42", "7290"
  "hexadecimal" -> "0x1", "0x2A", "0x1C7A"

!!bool
  "lowercase"   => "true", "false"
  "uppercase"   -> "TRUE", "FALSE"
  "camelcase"   -> "True", "False"

!!float
  "lowercase"   => ".nan", '.inf'
  "uppercase"   -> ".NAN", '.INF'
  "camelcase"   -> ".NaN", '.Inf'
```

Example:

``` javascript
safeDump (object, {
  'styles': {
    '!!null': 'canonical' // dump null as ~
  },
  'sortKeys': true        // sort object keys
});
```

### dump (object [ , options ])

Same as `safeDump()` but without limits (uses `DEFAULT_FULL_SCHEMA` by default).


Supported YAML types
--------------------

The list of standard YAML tags and corresponding JavaScipt types. See also
[YAML tag discussion](http://pyyaml.org/wiki/YAMLTagDiscussion) and
[YAML types repository](http://yaml.org/type/).

```
!!null ''                   # null
!!bool 'yes'                # bool
!!int '3...'                # number
!!float '3.14...'           # number
!!binary '...base64...'     # buffer
!!timestamp 'YYYY-...'      # date
!!omap [ ... ]              # array of key-value pairs
!!pairs [ ... ]             # array or array pairs
!!set { ... }               # array of objects with given keys and null values
!!str '...'                 # string
!!seq [ ... ]               # array
!!map { ... }               # object
```

**JavaScript-specific tags**

```
!!js/regexp /pattern/gim            # RegExp
!!js/undefined ''                   # Undefined
!!js/function 'function () {...}'   # Function
```

Caveats
-------

Note, that you use arrays or objects as key in JS-YAML. JS does not allow objects
or arrays as keys, and stringifies (by calling `toString()` method) them at the
moment of adding them.

``` yaml
---
? [ foo, bar ]
: - baz
? { foo: bar }
: - baz
  - baz
```

``` javascript
{ "foo,bar": ["baz"], "[object Object]": ["baz", "baz"] }
```

Also, reading of properties on implicit block mapping keys is not supported yet.
So, the following YAML document cannot be loaded.

``` yaml
&anchor foo:
  foo: bar
  *anchor: duplicate key
  baz: bat
  *anchor: duplicate key
```


js-yaml for enterprise
----------------------

Available as part of the Tidelift Subscription

The maintainers of js-yaml and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-js-yaml?utm_source=npm-js-yaml&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)


---

# gzip-size [![Build Status](https://travis-ci.com/sindresorhus/gzip-size.svg?branch=master)](https://travis-ci.com/github/sindresorhus/gzip-size)

> Get the gzipped size of a string or buffer

## Install

```
$ npm install gzip-size
```

## Usage

```js
const gzipSize = require('gzip-size');

const text = 'Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus.';

console.log(text.length);
//=> 191

console.log(gzipSize.sync(text));
//=> 78
```

## API

### gzipSize(input, options?)

Returns a `Promise<number>` with the size.

### gzipSize.sync(input, options?)

Returns the size.

#### input

Type: `string | Buffer`

#### options

Type: `object`

Any [`zlib` option](https://nodejs.org/api/zlib.html#zlib_class_options).

### gzipSize.stream(options?)

Returns a [`stream.PassThrough`](https://nodejs.org/api/stream.html#stream_class_stream_passthrough). The stream emits a `gzip-size` event and has a `gzipSize` property.

### gzipSize.file(path, options?)

Returns a `Promise<number>` with the size of the file.

#### path

Type: `string`

### gzipSize.fileSync(path, options?)

Returns the size of the file.

## Related

- [gzip-size-cli](https://github.com/sindresorhus/gzip-size-cli) - CLI for this module

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-gzip-size?utm_source=npm-gzip-size&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

# Handle Thing

[![Build Status](https://travis-ci.org/spdy-http2/handle-thing.svg?branch=master)](http://travis-ci.org/spdy-http2/handle-thing)
[![NPM version](https://badge.fury.io/js/handle-thing.svg)](http://badge.fury.io/js/handle-thing)
[![dependencies Status](https://david-dm.org/spdy-http2/handle-thing/status.svg?style=flat-square)](https://david-dm.org/spdy-http2/handle-thing)
[![Standard - JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg?style=flat-square)](http://standardjs.com/)
[![Waffle](https://img.shields.io/badge/track-waffle-blue.svg?style=flat-square)](https://waffle.io/spdy-http2/node-spdy)

> Wrap Streams2 instance into a HandleWrap. The right thing when you need it

## Usage

### Examples

`soon™`

### API

`soon™`

## LICENSE

This software is licensed under the MIT License.

Copyright Fedor Indutny, 2015.

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to permit
persons to whom the Software is furnished to do so, subject to the
following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
USE OR OTHER DEALINGS IN THE SOFTWARE.


---

# has-flag [![Build Status](https://travis-ci.org/sindresorhus/has-flag.svg?branch=master)](https://travis-ci.org/sindresorhus/has-flag)

> Check if [`argv`](https://nodejs.org/docs/latest/api/process.html#process_process_argv) has a specific flag

Correctly stops looking after an `--` argument terminator.

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-has-flag?utm_source=npm-has-flag&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>

---


## Install

```
$ npm install has-flag
```


## Usage

```js
// foo.js
const hasFlag = require('has-flag');

hasFlag('unicorn');
//=> true

hasFlag('--unicorn');
//=> true

hasFlag('f');
//=> true

hasFlag('-f');
//=> true

hasFlag('foo=bar');
//=> true

hasFlag('foo');
//=> false

hasFlag('rainbow');
//=> false
```

```
$ node foo.js -f --unicorn --foo=bar -- --rainbow
```


## API

### hasFlag(flag, [argv])

Returns a boolean for whether the flag exists.

#### flag

Type: `string`

CLI flag to look for. The `--` prefix is optional.

#### argv

Type: `string[]`<br>
Default: `process.argv`

CLI arguments.


## Security

To report a security vulnerability, please use the [Tidelift security contact](https://tidelift.com/security). Tidelift will coordinate the fix and disclosure.


## License

MIT © [Sindre Sorhus](https://sindresorhus.com)


---

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [v1.0.2](https://github.com/inspect-js/has-property-descriptors/compare/v1.0.1...v1.0.2) - 2024-02-12

### Commits

- [Refactor] use `es-define-property` [`f93a8c8`](https://github.com/inspect-js/has-property-descriptors/commit/f93a8c85eba70cbceab500f2619fb5cce73a1805)
- [Dev Deps] update `aud`, `npmignore`, `tape` [`42b0c9d`](https://github.com/inspect-js/has-property-descriptors/commit/42b0c9d1c23e747755f0f2924923c418ea34a9ee)
- [Deps] update `get-intrinsic` [`35e9b46`](https://github.com/inspect-js/has-property-descriptors/commit/35e9b46a7f14331bf0de98b644dd803676746037)

## [v1.0.1](https://github.com/inspect-js/has-property-descriptors/compare/v1.0.0...v1.0.1) - 2023-10-20

### Commits

- [meta] use `npmignore` to autogenerate an npmignore file [`5bbf4da`](https://github.com/inspect-js/has-property-descriptors/commit/5bbf4dae1b58950d87bb3af508bee7513e640868)
- [actions] update rebase action to use reusable workflow [`3a5585b`](https://github.com/inspect-js/has-property-descriptors/commit/3a5585bf74988f71a8f59e67a07d594e62c51fd8)
- [Dev Deps] update `@ljharb/eslint-config`, `aud`, `tape` [`e5c1212`](https://github.com/inspect-js/has-property-descriptors/commit/e5c1212048a8fda549794c47863724ca60b89cae)
- [Dev Deps] update `aud`, `tape` [`e942917`](https://github.com/inspect-js/has-property-descriptors/commit/e942917b6c2f7c090d5623048989cf20d0834ebf)
- [Deps] update `get-intrinsic` [`f4a44ec`](https://github.com/inspect-js/has-property-descriptors/commit/f4a44ec6d94146fa6c550d3c15c31a2062c83ef4)
- [Deps] update `get-intrinsic` [`eeb275b`](https://github.com/inspect-js/has-property-descriptors/commit/eeb275b473e5d72ca843b61ca25cfcb06a5d4300)

## v1.0.0 - 2022-04-14

### Commits

- Initial implementation, tests [`303559f`](https://github.com/inspect-js/has-property-descriptors/commit/303559f2a72dfe7111573a1aec475ed4a184c35a)
- Initial commit [`3a7ca2d`](https://github.com/inspect-js/has-property-descriptors/commit/3a7ca2dc49f1fff0279a28bb16265e7615e14749)
- read me [`dd73dce`](https://github.com/inspect-js/has-property-descriptors/commit/dd73dce09d89d0f7a4a6e3b1e562a506f979a767)
- npm init [`c1e6557`](https://github.com/inspect-js/has-property-descriptors/commit/c1e655779de632d68cb944c50da6b71bcb7b8c85)
- Only apps should have lockfiles [`e72f7c6`](https://github.com/inspect-js/has-property-descriptors/commit/e72f7c68de534b2d273ee665f8b18d4ecc7f70b0)


---

# has-property-descriptors <sup>[![Version Badge][npm-version-svg]][package-url]</sup>

[![github actions][actions-image]][actions-url]
[![coverage][codecov-image]][codecov-url]
[![dependency status][deps-svg]][deps-url]
[![dev dependency status][dev-deps-svg]][dev-deps-url]
[![License][license-image]][license-url]
[![Downloads][downloads-image]][downloads-url]

[![npm badge][npm-badge-png]][package-url]

Does the environment have full property descriptor support? Handles IE 8's broken defineProperty/gOPD.

## Example

```js
var hasPropertyDescriptors = require('has-property-descriptors');
var assert = require('assert');

assert.equal(hasPropertyDescriptors(), true); // will be `false` in IE 6-8, and ES5 engines

// Arrays can not have their length `[[Defined]]` in some engines
assert.equal(hasPropertyDescriptors.hasArrayLengthDefineBug(), false); // will be `true` in Firefox 4-22, and node v0.6
```

## Tests
Simply clone the repo, `npm install`, and run `npm test`

[package-url]: https://npmjs.org/package/has-property-descriptors
[npm-version-svg]: https://versionbadg.es/inspect-js/has-property-descriptors.svg
[deps-svg]: https://david-dm.org/inspect-js/has-property-descriptors.svg
[deps-url]: https://david-dm.org/inspect-js/has-property-descriptors
[dev-deps-svg]: https://david-dm.org/inspect-js/has-property-descriptors/dev-status.svg
[dev-deps-url]: https://david-dm.org/inspect-js/has-property-descriptors#info=devDependencies
[npm-badge-png]: https://nodei.co/npm/has-property-descriptors.png?downloads=true&stars=true
[license-image]: https://img.shields.io/npm/l/has-property-descriptors.svg
[license-url]: LICENSE
[downloads-image]: https://img.shields.io/npm/dm/has-property-descriptors.svg
[downloads-url]: https://npm-stat.com/charts.html?package=has-property-descriptors
[codecov-image]: https://codecov.io/gh/inspect-js/has-property-descriptors/branch/main/graphs/badge.svg
[codecov-url]: https://app.codecov.io/gh/inspect-js/has-property-descriptors/
[actions-image]: https://img.shields.io/endpoint?url=https://github-actions-badge-u3jn4tfpocch.runkit.sh/inspect-js/has-property-descriptors
[actions-url]: https://github.com/inspect-js/has-property-descriptors/actions


---

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [v1.1.0](https://github.com/inspect-js/has-symbols/compare/v1.0.3...v1.1.0) - 2024-12-02

### Commits

- [actions] update workflows [`548c0bf`](https://github.com/inspect-js/has-symbols/commit/548c0bf8c9b1235458df7a1c0490b0064647a282)
- [actions] further shard; update action deps [`bec56bb`](https://github.com/inspect-js/has-symbols/commit/bec56bb0fb44b43a786686b944875a3175cf3ff3)
- [meta] use `npmignore` to autogenerate an npmignore file [`ac81032`](https://github.com/inspect-js/has-symbols/commit/ac81032809157e0a079e5264e9ce9b6f1275777e)
- [New] add types [`6469cbf`](https://github.com/inspect-js/has-symbols/commit/6469cbff1866cfe367b2b3d181d9296ec14b2a3d)
- [actions] update rebase action to use reusable workflow [`9c9d4d0`](https://github.com/inspect-js/has-symbols/commit/9c9d4d0d8938e4b267acdf8e421f4e92d1716d72)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `aud`, `tape` [`adb5887`](https://github.com/inspect-js/has-symbols/commit/adb5887ca9444849b08beb5caaa9e1d42320cdfb)
- [Dev Deps] update `@ljharb/eslint-config`, `aud`, `tape` [`13ec198`](https://github.com/inspect-js/has-symbols/commit/13ec198ec80f1993a87710af1606a1970b22c7cb)
- [Dev Deps] update `auto-changelog`, `core-js`, `tape` [`941be52`](https://github.com/inspect-js/has-symbols/commit/941be5248387cab1da72509b22acf3fdb223f057)
- [Tests] replace `aud` with `npm audit` [`74f49e9`](https://github.com/inspect-js/has-symbols/commit/74f49e9a9d17a443020784234a1c53ce765b3559)
- [Dev Deps] update `npmignore` [`9c0ac04`](https://github.com/inspect-js/has-symbols/commit/9c0ac0452a834f4c2a4b54044f2d6a89f17e9a70)
- [Dev Deps] add missing peer dep [`52337a5`](https://github.com/inspect-js/has-symbols/commit/52337a5621cced61f846f2afdab7707a8132cc12)

## [v1.0.3](https://github.com/inspect-js/has-symbols/compare/v1.0.2...v1.0.3) - 2022-03-01

### Commits

- [actions] use `node/install` instead of `node/run`; use `codecov` action [`518b28f`](https://github.com/inspect-js/has-symbols/commit/518b28f6c5a516cbccae30794e40aa9f738b1693)
- [meta] add `bugs` and `homepage` fields; reorder package.json [`c480b13`](https://github.com/inspect-js/has-symbols/commit/c480b13fd6802b557e1cef9749872cb5fdeef744)
- [actions] reuse common workflows [`01d0ee0`](https://github.com/inspect-js/has-symbols/commit/01d0ee0a8d97c0947f5edb73eb722027a77b2b07)
- [actions] update codecov uploader [`6424ebe`](https://github.com/inspect-js/has-symbols/commit/6424ebe86b2c9c7c3d2e9bd4413a4e4f168cb275)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `aud`, `auto-changelog`, `tape` [`dfa7e7f`](https://github.com/inspect-js/has-symbols/commit/dfa7e7ff38b594645d8c8222aab895157fa7e282)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `safe-publish-latest`, `tape` [`0c8d436`](https://github.com/inspect-js/has-symbols/commit/0c8d43685c45189cea9018191d4fd7eca91c9d02)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `aud`, `tape` [`9026554`](https://github.com/inspect-js/has-symbols/commit/902655442a1bf88e72b42345494ef0c60f5d36ab)
- [readme] add actions and codecov badges [`eaa9682`](https://github.com/inspect-js/has-symbols/commit/eaa9682f990f481d3acf7a1c7600bec36f7b3adc)
- [Dev Deps] update `eslint`, `tape` [`bc7a3ba`](https://github.com/inspect-js/has-symbols/commit/bc7a3ba46f27b7743f8a2579732d59d1b9ac791e)
- [Dev Deps] update `eslint`, `auto-changelog` [`0ace00a`](https://github.com/inspect-js/has-symbols/commit/0ace00af08a88cdd1e6ce0d60357d941c60c2d9f)
- [meta] use `prepublishOnly` script for npm 7+ [`093f72b`](https://github.com/inspect-js/has-symbols/commit/093f72bc2b0ed00c781f444922a5034257bf561d)
- [Tests] test on all 16 minors [`9b80d3d`](https://github.com/inspect-js/has-symbols/commit/9b80d3d9102529f04c20ec5b1fcc6e38426c6b03)

## [v1.0.2](https://github.com/inspect-js/has-symbols/compare/v1.0.1...v1.0.2) - 2021-02-27

### Fixed

- [Fix] use a universal way to get the original Symbol [`#11`](https://github.com/inspect-js/has-symbols/issues/11)

### Commits

- [Tests] migrate tests to Github Actions [`90ae798`](https://github.com/inspect-js/has-symbols/commit/90ae79820bdfe7bc703d67f5f3c5e205f98556d3)
- [meta] do not publish github action workflow files [`29e60a1`](https://github.com/inspect-js/has-symbols/commit/29e60a1b7c25c7f1acf7acff4a9320d0d10c49b4)
- [Tests] run `nyc` on all tests [`8476b91`](https://github.com/inspect-js/has-symbols/commit/8476b915650d360915abe2522505abf4b0e8f0ae)
- [readme] fix repo URLs, remove defunct badges [`126288e`](https://github.com/inspect-js/has-symbols/commit/126288ecc1797c0a40247a6b78bcb2e0bc5d7036)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `aud`, `auto-changelog`, `core-js`, `get-own-property-symbols` [`d84bdfa`](https://github.com/inspect-js/has-symbols/commit/d84bdfa48ac5188abbb4904b42614cd6c030940a)
- [Tests] fix linting errors [`0df3070`](https://github.com/inspect-js/has-symbols/commit/0df3070b981b6c9f2ee530c09189a7f5c6def839)
- [actions] add "Allow Edits" workflow [`1e6bc29`](https://github.com/inspect-js/has-symbols/commit/1e6bc29b188f32b9648657b07eda08504be5aa9c)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `tape` [`36cea2a`](https://github.com/inspect-js/has-symbols/commit/36cea2addd4e6ec435f35a2656b4e9ef82498e9b)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `aud`, `tape` [`1278338`](https://github.com/inspect-js/has-symbols/commit/127833801865fbc2cc8979beb9ca869c7bfe8222)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `aud`, `tape` [`1493254`](https://github.com/inspect-js/has-symbols/commit/1493254eda13db5fb8fc5e4a3e8324b3d196029d)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `core-js` [`b090bf2`](https://github.com/inspect-js/has-symbols/commit/b090bf214d3679a30edc1e2d729d466ab5183e1d)
- [actions] switch Automatic Rebase workflow to `pull_request_target` event [`4addb7a`](https://github.com/inspect-js/has-symbols/commit/4addb7ab4dc73f927ae99928d68817554fc21dc0)
- [Dev Deps] update `auto-changelog`, `tape` [`81d0baf`](https://github.com/inspect-js/has-symbols/commit/81d0baf3816096a89a8558e8043895f7a7d10d8b)
- [Dev Deps] update `auto-changelog`; add `aud` [`1a4e561`](https://github.com/inspect-js/has-symbols/commit/1a4e5612c25d91c3a03d509721d02630bc4fe3da)
- [readme] remove unused testling URLs [`3000941`](https://github.com/inspect-js/has-symbols/commit/3000941f958046e923ed8152edb1ef4a599e6fcc)
- [Tests] only audit prod deps [`692e974`](https://github.com/inspect-js/has-symbols/commit/692e9743c912410e9440207631a643a34b4741a1)
- [Dev Deps] update `@ljharb/eslint-config` [`51c946c`](https://github.com/inspect-js/has-symbols/commit/51c946c7f6baa793ec5390bb5a45cdce16b4ba76)

## [v1.0.1](https://github.com/inspect-js/has-symbols/compare/v1.0.0...v1.0.1) - 2019-11-16

### Commits

- [Tests] use shared travis-ci configs [`ce396c9`](https://github.com/inspect-js/has-symbols/commit/ce396c9419ff11c43d0da5d05cdbb79f7fb42229)
- [Tests] up to `node` `v12.4`, `v11.15`, `v10.15`, `v9.11`, `v8.15`, `v7.10`, `v6.17`, `v4.9`; use `nvm install-latest-npm` [`0690732`](https://github.com/inspect-js/has-symbols/commit/0690732801f47ab429f39ba1962f522d5c462d6b)
- [meta] add `auto-changelog` [`2163d0b`](https://github.com/inspect-js/has-symbols/commit/2163d0b7f36343076b8f947cd1667dd1750f26fc)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `core-js`, `safe-publish-latest`, `tape` [`8e0951f`](https://github.com/inspect-js/has-symbols/commit/8e0951f1a7a2e52068222b7bb73511761e6e4d9c)
- [actions] add automatic rebasing / merge commit blocking [`b09cdb7`](https://github.com/inspect-js/has-symbols/commit/b09cdb7cd7ee39e7a769878f56e2d6066f5ccd1d)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `safe-publish-latest`, `core-js`, `get-own-property-symbols`, `tape` [`1dd42cd`](https://github.com/inspect-js/has-symbols/commit/1dd42cd86183ed0c50f99b1062345c458babca91)
- [meta] create FUNDING.yml [`aa57a17`](https://github.com/inspect-js/has-symbols/commit/aa57a17b19708906d1927f821ea8e73394d84ca4)
- Only apps should have lockfiles [`a2d8bea`](https://github.com/inspect-js/has-symbols/commit/a2d8bea23a97d15c09eaf60f5b107fcf9a4d57aa)
- [Tests] use `npx aud` instead of `nsp` or `npm audit` with hoops [`9e96cb7`](https://github.com/inspect-js/has-symbols/commit/9e96cb783746cbed0c10ef78e599a8eaa7ebe193)
- [meta] add `funding` field [`a0b32cf`](https://github.com/inspect-js/has-symbols/commit/a0b32cf68e803f963c1639b6d47b0a9d6440bab0)
- [Dev Deps] update `safe-publish-latest` [`cb9f0a5`](https://github.com/inspect-js/has-symbols/commit/cb9f0a521a3a1790f1064d437edd33bb6c3d6af0)

## v1.0.0 - 2016-09-19

### Commits

- Tests. [`ecb6eb9`](https://github.com/inspect-js/has-symbols/commit/ecb6eb934e4883137f3f93b965ba5e0a98df430d)
- package.json [`88a337c`](https://github.com/inspect-js/has-symbols/commit/88a337cee0864a0da35f5d19e69ff0ef0150e46a)
- Initial commit [`42e1e55`](https://github.com/inspect-js/has-symbols/commit/42e1e5502536a2b8ac529c9443984acd14836b1c)
- Initial implementation. [`33f5cc6`](https://github.com/inspect-js/has-symbols/commit/33f5cc6cdff86e2194b081ee842bfdc63caf43fb)
- read me [`01f1170`](https://github.com/inspect-js/has-symbols/commit/01f1170188ff7cb1558aa297f6ba5b516c6d7b0c)


---

# has-symbols <sup>[![Version Badge][2]][1]</sup>

[![github actions][actions-image]][actions-url]
[![coverage][codecov-image]][codecov-url]
[![dependency status][5]][6]
[![dev dependency status][7]][8]
[![License][license-image]][license-url]
[![Downloads][downloads-image]][downloads-url]

[![npm badge][11]][1]

Determine if the JS environment has Symbol support. Supports spec, or shams.

## Example

```js
var hasSymbols = require('has-symbols');

hasSymbols() === true; // if the environment has native Symbol support. Not polyfillable, not forgeable.

var hasSymbolsKinda = require('has-symbols/shams');
hasSymbolsKinda() === true; // if the environment has a Symbol sham that mostly follows the spec.
```

## Supported Symbol shams
 - get-own-property-symbols [npm](https://www.npmjs.com/package/get-own-property-symbols) | [github](https://github.com/WebReflection/get-own-property-symbols)
 - core-js [npm](https://www.npmjs.com/package/core-js) | [github](https://github.com/zloirock/core-js)

## Tests
Simply clone the repo, `npm install`, and run `npm test`

[1]: https://npmjs.org/package/has-symbols
[2]: https://versionbadg.es/inspect-js/has-symbols.svg
[5]: https://david-dm.org/inspect-js/has-symbols.svg
[6]: https://david-dm.org/inspect-js/has-symbols
[7]: https://david-dm.org/inspect-js/has-symbols/dev-status.svg
[8]: https://david-dm.org/inspect-js/has-symbols#info=devDependencies
[11]: https://nodei.co/npm/has-symbols.png?downloads=true&stars=true
[license-image]: https://img.shields.io/npm/l/has-symbols.svg
[license-url]: LICENSE
[downloads-image]: https://img.shields.io/npm/dm/has-symbols.svg
[downloads-url]: https://npm-stat.com/charts.html?package=has-symbols
[codecov-image]: https://codecov.io/gh/inspect-js/has-symbols/branch/main/graphs/badge.svg
[codecov-url]: https://app.codecov.io/gh/inspect-js/has-symbols/
[actions-image]: https://img.shields.io/endpoint?url=https://github-actions-badge-u3jn4tfpocch.runkit.sh/inspect-js/has-symbols
[actions-url]: https://github.com/inspect-js/has-symbols/actions


---

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [v1.0.2](https://github.com/inspect-js/has-tostringtag/compare/v1.0.1...v1.0.2) - 2024-02-01

### Fixed

- [Fix] move `has-symbols` back to prod deps [`#3`](https://github.com/inspect-js/has-tostringtag/issues/3)

## [v1.0.1](https://github.com/inspect-js/has-tostringtag/compare/v1.0.0...v1.0.1) - 2024-02-01

### Commits

- [patch] add types [`9276414`](https://github.com/inspect-js/has-tostringtag/commit/9276414b22fab3eeb234688841722c4be113201f)
- [meta] use `npmignore` to autogenerate an npmignore file [`5c0dcd1`](https://github.com/inspect-js/has-tostringtag/commit/5c0dcd1ff66419562a30d1fd88b966cc36bce5fc)
- [actions] reuse common workflows [`dee9509`](https://github.com/inspect-js/has-tostringtag/commit/dee950904ab5719b62cf8d73d2ac950b09093266)
- [actions] update codecov uploader [`b8cb3a0`](https://github.com/inspect-js/has-tostringtag/commit/b8cb3a0b8ffbb1593012c4c2daa45fb25642825d)
- [Tests] generate coverage [`be5b288`](https://github.com/inspect-js/has-tostringtag/commit/be5b28889e2735cdbcef387f84c2829995f2f05e)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `safe-publish-latest`, `tape` [`69a0827`](https://github.com/inspect-js/has-tostringtag/commit/69a0827974e9b877b2c75b70b057555da8f25a65)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `aud`, `auto-changelog`, `tape` [`4c9e210`](https://github.com/inspect-js/has-tostringtag/commit/4c9e210a5682f0557a3235d36b68ce809d7fb825)
- [actions] update rebase action to use reusable workflow [`ca8dcd3`](https://github.com/inspect-js/has-tostringtag/commit/ca8dcd3a6f3f5805d7e3fd461b654aedba0946e7)
- [Dev Deps] update `@ljharb/eslint-config`, `aud`, `npmignore`, `tape` [`07f3eaf`](https://github.com/inspect-js/has-tostringtag/commit/07f3eafa45dd98208c94479737da77f9a69b94c4)
- [Deps] update `has-symbols` [`999e009`](https://github.com/inspect-js/has-tostringtag/commit/999e0095a7d1749a58f55472ec8bf8108cdfdcf3)
- [Tests] remove staging tests since they fail on modern node [`9d9526b`](https://github.com/inspect-js/has-tostringtag/commit/9d9526b1dc1ca7f2292b52efda4c3d857b0e39bd)

## v1.0.0 - 2021-08-05

### Commits

- Tests [`6b6f573`](https://github.com/inspect-js/has-tostringtag/commit/6b6f5734dc2058badb300ff0783efdad95fe1a65)
- Initial commit [`2f8190e`](https://github.com/inspect-js/has-tostringtag/commit/2f8190e799fac32ba9b95a076c0255e01d7ce475)
- [meta] do not publish github action workflow files [`6e08cc4`](https://github.com/inspect-js/has-tostringtag/commit/6e08cc4e0fea7ec71ef66e70734b2af2c4a8b71b)
- readme [`94bed6c`](https://github.com/inspect-js/has-tostringtag/commit/94bed6c9560cbbfda034f8d6c260bb7b0db33c1a)
- npm init [`be67840`](https://github.com/inspect-js/has-tostringtag/commit/be67840ab92ee7adb98bcc65261975543f815fa5)
- Implementation [`c4914ec`](https://github.com/inspect-js/has-tostringtag/commit/c4914ecc51ddee692c85b471ae0a5d8123030fbf)
- [meta] use `auto-changelog` [`4aaf768`](https://github.com/inspect-js/has-tostringtag/commit/4aaf76895ae01d7b739f2b19f967ef2372506cd7)
- Only apps should have lockfiles [`bc4d99e`](https://github.com/inspect-js/has-tostringtag/commit/bc4d99e4bf494afbaa235c5f098df6e642edf724)
- [meta] add `safe-publish-latest` [`6523c05`](https://github.com/inspect-js/has-tostringtag/commit/6523c05c9b87140f3ae74c9daf91633dd9ff4e1f)


---

# has-tostringtag <sup>[![Version Badge][2]][1]</sup>

[![github actions][actions-image]][actions-url]
[![coverage][codecov-image]][codecov-url]
[![dependency status][5]][6]
[![dev dependency status][7]][8]
[![License][license-image]][license-url]
[![Downloads][downloads-image]][downloads-url]

[![npm badge][11]][1]

Determine if the JS environment has `Symbol.toStringTag` support. Supports spec, or shams.

## Example

```js
var hasSymbolToStringTag = require('has-tostringtag');

hasSymbolToStringTag() === true; // if the environment has native Symbol.toStringTag support. Not polyfillable, not forgeable.

var hasSymbolToStringTagKinda = require('has-tostringtag/shams');
hasSymbolToStringTagKinda() === true; // if the environment has a Symbol.toStringTag sham that mostly follows the spec.
```

## Supported Symbol shams
 - get-own-property-symbols [npm](https://www.npmjs.com/package/get-own-property-symbols) | [github](https://github.com/WebReflection/get-own-property-symbols)
 - core-js [npm](https://www.npmjs.com/package/core-js) | [github](https://github.com/zloirock/core-js)

## Tests
Simply clone the repo, `npm install`, and run `npm test`

[1]: https://npmjs.org/package/has-tostringtag
[2]: https://versionbadg.es/inspect-js/has-tostringtag.svg
[5]: https://david-dm.org/inspect-js/has-tostringtag.svg
[6]: https://david-dm.org/inspect-js/has-tostringtag
[7]: https://david-dm.org/inspect-js/has-tostringtag/dev-status.svg
[8]: https://david-dm.org/inspect-js/has-tostringtag#info=devDependencies
[11]: https://nodei.co/npm/has-tostringtag.png?downloads=true&stars=true
[license-image]: https://img.shields.io/npm/l/has-tostringtag.svg
[license-url]: LICENSE
[downloads-image]: https://img.shields.io/npm/dm/has-tostringtag.svg
[downloads-url]: https://npm-stat.com/charts.html?package=has-tostringtag
[codecov-image]: https://codecov.io/gh/inspect-js/has-tostringtag/branch/main/graphs/badge.svg
[codecov-url]: https://app.codecov.io/gh/inspect-js/has-tostringtag/
[actions-image]: https://img.shields.io/endpoint?url=https://github-actions-badge-u3jn4tfpocch.runkit.sh/inspect-js/has-tostringtag
[actions-url]: https://github.com/inspect-js/has-tostringtag/actions


---

# has-yarn

> Check if a project is using [Yarn](https://yarnpkg.com)

Useful for tools that needs to know whether to use `yarn` or `npm` to install dependencies.

It checks if a `yarn.lock` file is present in the working directory.

## Install

```
$ npm install has-yarn
```

## Usage

```
.
├── foo
│   └── package.json
└── bar
    ├── package.json
    └── yarn.lock
```

```js
import hasYarn from 'has-yarn';

hasYarn('foo');
//=> false

hasYarn('bar');
//=> true
```

## API

### hasYarn(cwd?)

Returns a `boolean` of whether the project uses Yarn.

#### cwd

Type: `string`\
Default: `process.cwd()`

The current working directory.

## Related

- [has-yarn-cli](https://github.com/sindresorhus/has-yarn-cli) - CLI for this module


---

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [v2.0.2](https://github.com/inspect-js/hasOwn/compare/v2.0.1...v2.0.2) - 2024-03-10

### Commits

- [types] use shared config [`68e9d4d`](https://github.com/inspect-js/hasOwn/commit/68e9d4dab6facb4f05f02c6baea94a3f2a4e44b2)
- [actions] remove redundant finisher; use reusable workflow [`241a68e`](https://github.com/inspect-js/hasOwn/commit/241a68e13ea1fe52bec5ba7f74144befc31fae7b)
- [Tests] increase coverage [`4125c0d`](https://github.com/inspect-js/hasOwn/commit/4125c0d6121db56ae30e38346dfb0c000b04f0a7)
- [Tests] skip `npm ls` in old node due to TS [`01b9282`](https://github.com/inspect-js/hasOwn/commit/01b92822f9971dea031eafdd14767df41d61c202)
- [types] improve predicate type [`d340f85`](https://github.com/inspect-js/hasOwn/commit/d340f85ce02e286ef61096cbbb6697081d40a12b)
- [Dev Deps] update `tape` [`70089fc`](https://github.com/inspect-js/hasOwn/commit/70089fcf544e64acc024cbe60f5a9b00acad86de)
- [Tests] use `@arethetypeswrong/cli` [`50b272c`](https://github.com/inspect-js/hasOwn/commit/50b272c829f40d053a3dd91c9796e0ac0b2af084)

## [v2.0.1](https://github.com/inspect-js/hasOwn/compare/v2.0.0...v2.0.1) - 2024-02-10

### Commits

- [types] use a handwritten d.ts file; fix exported type [`012b989`](https://github.com/inspect-js/hasOwn/commit/012b9898ccf91dc441e2ebf594ff70270a5fda58)
- [Dev Deps] update `@types/function-bind`, `@types/mock-property`, `@types/tape`, `aud`, `mock-property`, `npmignore`, `tape`, `typescript` [`977a56f`](https://github.com/inspect-js/hasOwn/commit/977a56f51a1f8b20566f3c471612137894644025)
- [meta] add `sideEffects` flag [`3a60b7b`](https://github.com/inspect-js/hasOwn/commit/3a60b7bf42fccd8c605e5f145a6fcc83b13cb46f)

## [v2.0.0](https://github.com/inspect-js/hasOwn/compare/v1.0.1...v2.0.0) - 2023-10-19

### Commits

- revamped implementation, tests, readme [`72bf8b3`](https://github.com/inspect-js/hasOwn/commit/72bf8b338e77a638f0a290c63ffaed18339c36b4)
- [meta] revamp package.json [`079775f`](https://github.com/inspect-js/hasOwn/commit/079775fb1ec72c1c6334069593617a0be3847458)
- Only apps should have lockfiles [`6640e23`](https://github.com/inspect-js/hasOwn/commit/6640e233d1bb8b65260880f90787637db157d215)

## v1.0.1 - 2023-10-10

### Commits

- Initial commit [`8dbfde6`](https://github.com/inspect-js/hasOwn/commit/8dbfde6e8fb0ebb076fab38d138f2984eb340a62)


---

# hasown <sup>[![Version Badge][npm-version-svg]][package-url]</sup>

[![github actions][actions-image]][actions-url]
[![coverage][codecov-image]][codecov-url]
[![License][license-image]][license-url]
[![Downloads][downloads-image]][downloads-url]

[![npm badge][npm-badge-png]][package-url]

A robust, ES3 compatible, "has own property" predicate.

## Example

```js
const assert = require('assert');
const hasOwn = require('hasown');

assert.equal(hasOwn({}, 'toString'), false);
assert.equal(hasOwn([], 'length'), true);
assert.equal(hasOwn({ a: 42 }, 'a'), true);
```

## Tests
Simply clone the repo, `npm install`, and run `npm test`

[package-url]: https://npmjs.org/package/hasown
[npm-version-svg]: https://versionbadg.es/inspect-js/hasown.svg
[deps-svg]: https://david-dm.org/inspect-js/hasOwn.svg
[deps-url]: https://david-dm.org/inspect-js/hasOwn
[dev-deps-svg]: https://david-dm.org/inspect-js/hasOwn/dev-status.svg
[dev-deps-url]: https://david-dm.org/inspect-js/hasOwn#info=devDependencies
[npm-badge-png]: https://nodei.co/npm/hasown.png?downloads=true&stars=true
[license-image]: https://img.shields.io/npm/l/hasown.svg
[license-url]: LICENSE
[downloads-image]: https://img.shields.io/npm/dm/hasown.svg
[downloads-url]: https://npm-stat.com/charts.html?package=hasown
[codecov-image]: https://codecov.io/gh/inspect-js/hasOwn/branch/main/graphs/badge.svg
[codecov-url]: https://app.codecov.io/gh/inspect-js/hasOwn/
[actions-image]: https://img.shields.io/endpoint?url=https://github-actions-badge-u3jn4tfpocch.runkit.sh/inspect-js/hasOwn
[actions-url]: https://github.com/inspect-js/hasOwn/actions


---

# hast-util-from-parse5

[![Build][badge-build-image]][badge-build-url]
[![Coverage][badge-coverage-image]][badge-coverage-url]
[![Downloads][badge-downloads-image]][badge-downloads-url]
[![Size][badge-size-image]][badge-size-url]

[hast][github-hast] utility to transform from the
[`parse5`][github-parse5] AST.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`fromParse5(tree[, options])`](#fromparse5tree-options)
  * [`Options`](#options)
  * [`Space`](#space-1)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Related](#related)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package is a utility that can turn a parse5 tree into a hast tree.

## When should I use this?

You can use this package when using `parse5` as an HTML parser and wanting to
work with hast.

The utility [`hast-util-to-parse5`][github-hast-util-to-parse5] does the
inverse of this utility.
It generates `parse5`s AST again.

The utility [`hast-util-from-html`][github-hast-util-from-html] wraps this
utility and `parse5` to both parse HTML and generate hast from it.

## Install

This package is [ESM only][github-gist-esm].
In Node.js (version 16+),
install with [npm][npmjs-install]:

```sh
npm install hast-util-from-parse5
```

In Deno with [`esm.sh`][esmsh]:

```js
import {fromParse5} from "https://esm.sh/hast-util-from-parse5@8"
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {fromParse5} from "https://esm.sh/hast-util-from-parse5@8?bundle"
</script>
```

## Use

Say our document `example.html` contains:

```html
<!doctype html><title>Hello!</title><h1 id="world">World!<!--after-->
```

…and our module `example.js` looks as follows:

```js
import {fromParse5} from 'hast-util-from-parse5'
import {parse} from 'parse5'
import {read} from 'to-vfile'
import {inspect} from 'unist-util-inspect'

const file = await read('example.html')
const p5ast = parse(String(file), {sourceCodeLocationInfo: true})
const hast = fromParse5(p5ast, {file})

console.log(inspect(hast))
```

…now running `node example.js` yields:

```text
root[2] (1:1-2:1, 0-70)
│ data: {"quirksMode":false}
├─0 doctype (1:1-1:16, 0-15)
└─1 element<html>[2]
    │ properties: {}
    ├─0 element<head>[1]
    │   │ properties: {}
    │   └─0 element<title>[1] (1:16-1:37, 15-36)
    │       │ properties: {}
    │       └─0 text "Hello!" (1:23-1:29, 22-28)
    └─1 element<body>[1]
        │ properties: {}
        └─0 element<h1>[3] (1:37-2:1, 36-70)
            │ properties: {"id":"world"}
            ├─0 text "World!" (1:52-1:58, 51-57)
            ├─1 comment "after" (1:58-1:70, 57-69)
            └─2 text "\n" (1:70-2:1, 69-70)
```

## API

This package exports the identifier [`fromParse5`][api-from-parse5].
There is no default export.

### `fromParse5(tree[, options])`

Transform a `parse5` AST to hast.

###### Parameters

* `tree`
  ([`Parse5Node`][github-parse5-node])
  — `parse5` tree to transform
* `options`
  ([`Options`][api-options], optional)
  — configuration

###### Returns

hast tree ([`HastNode`][github-hast-nodes]).

### `Options`

Configuration (TypeScript type).

##### Fields

###### `file`

File used to add positional info to nodes
([`VFile`][github-vfile], optional).

If given,
the file should represent the original HTML source.

###### `space`

Which space the document is in
([`Space`][api-space], default: `'html'`).

When an `<svg>` element is found in the HTML space,
this package already automatically switches to and from the SVG space when
entering and exiting it.

###### `verbose`

Whether to add extra positional info about starting tags,
closing tags,
and attributes to elements
(`boolean`, default: `false`).

> 👉 **Note**:
> only used when `file` is given.

For the following HTML:

```html
<img src="http://example.com/fav.ico" alt="foo" title="bar">
```

The verbose info would looks as follows:

```js
{
  type: 'element',
  tagName: 'img',
  properties: {src: 'http://example.com/fav.ico', alt: 'foo', title: 'bar'},
  children: [],
  data: {
    position: {
      opening: {
        start: {line: 1, column: 1, offset: 0},
        end: {line: 1, column: 61, offset: 60}
      },
      closing: null,
      properties: {
        src: {
          start: {line: 1, column: 6, offset: 5},
          end: {line: 1, column: 38, offset: 37}
        },
        alt: {
          start: {line: 1, column: 39, offset: 38},
          end: {line: 1, column: 48, offset: 47}
        },
        title: {
          start: {line: 1, column: 49, offset: 48},
          end: {line: 1, column: 60, offset: 59}
        }
      }
    }
  },
  position: {
    start: {line: 1, column: 1, offset: 0},
    end: {line: 1, column: 61, offset: 60}
  }
}
```

### `Space`

Namespace (TypeScript type).

###### Type

```ts
type Space = 'html' | 'svg'
```

## Types

This package is fully typed with [TypeScript][].
It exports the additional types [`Options`][api-options] and
[`Space`][api-space].

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release,
we drop support for unmaintained versions of Node.
This means we try to keep the current release line,
`hast-util-from-parse5@8`,
compatible with Node.js 16.

## Security

Use of `hast-util-from-parse5` can open you up to a
[cross-site scripting (XSS)][wikipedia-xss] attack if Parse5’s AST is unsafe.

## Related

* [`hast-util-to-parse5`][github-hast-util-to-parse5]
  — transform hast to Parse5’s AST
* [`hast-util-to-nlcst`](https://github.com/syntax-tree/hast-util-to-nlcst)
  — transform hast to nlcst
* [`hast-util-to-mdast`](https://github.com/syntax-tree/hast-util-to-mdast)
  — transform hast to mdast
* [`hast-util-to-xast`](https://github.com/syntax-tree/hast-util-to-xast)
  — transform hast to xast
* [`mdast-util-to-hast`](https://github.com/syntax-tree/mdast-util-to-hast)
  — transform mdast to hast
* [`mdast-util-to-nlcst`](https://github.com/syntax-tree/mdast-util-to-nlcst)
  — transform mdast to nlcst

## Contribute

See [`contributing.md`][health-contributing]
in
[`syntax-tree/.github`][health]
for ways to get started.
See [`support.md`][health-support] for ways to get help.

This project has a [code of conduct][health-coc].
By interacting with this repository,
organization,
or community you agree to abide by its terms.

## License

[MIT][file-license] © [Titus Wormer][wooorm]

<!-- Definitions -->

[api-from-parse5]: #fromparse5tree-options

[api-options]: #options

[api-space]: #space-1

[badge-build-image]: https://github.com/syntax-tree/hast-util-from-parse5/workflows/main/badge.svg

[badge-build-url]: https://github.com/syntax-tree/hast-util-from-parse5/actions

[badge-coverage-image]: https://img.shields.io/codecov/c/github/syntax-tree/hast-util-from-parse5.svg

[badge-coverage-url]: https://codecov.io/github/syntax-tree/hast-util-from-parse5

[badge-downloads-image]: https://img.shields.io/npm/dm/hast-util-from-parse5.svg

[badge-downloads-url]: https://www.npmjs.com/package/hast-util-from-parse5

[badge-size-image]: https://img.shields.io/bundlejs/size/hast-util-from-parse5

[badge-size-url]: https://bundlejs.com/?q=hast-util-from-parse5

[esmsh]: https://esm.sh

[file-license]: license

[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[github-hast]: https://github.com/syntax-tree/hast

[github-hast-nodes]: https://github.com/syntax-tree/hast#nodes

[github-hast-util-from-html]: https://github.com/syntax-tree/hast-util-from-html

[github-hast-util-to-parse5]: https://github.com/syntax-tree/hast-util-to-parse5

[github-parse5]: https://github.com/inikulin/parse5

[github-parse5-node]: https://github.com/inikulin/parse5/blob/master/packages/parse5/lib/tree-adapters/default.ts

[github-vfile]: https://github.com/vfile/vfile

[health]: https://github.com/syntax-tree/.github

[health-coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md

[health-contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md

[health-support]: https://github.com/syntax-tree/.github/blob/main/support.md

[npmjs-install]: https://docs.npmjs.com/cli/install

[typescript]: https://www.typescriptlang.org

[wikipedia-xss]: https://en.wikipedia.org/wiki/Cross-site_scripting

[wooorm]: https://wooorm.com


---

# hast-util-parse-selector

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[hast][] utility to create an element from a simple CSS selector.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`parseSelector(selector?[, defaultTagName])`](#parseselectorselector-defaulttagname)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Security](#security)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package is a tiny utility that helps create elements.

## When should I use this?

This utility is super niche.
You probably want the more powerful [`hastscript`][hastscript] or
[`hast-util-from-selector`][hast-util-from-selector]

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install hast-util-parse-selector
```

In Deno with [`esm.sh`][esmsh]:

```js
import {parseSelector} from 'https://esm.sh/hast-util-parse-selector@4'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {parseSelector} from 'https://esm.sh/hast-util-parse-selector@4?bundle'
</script>
```

## Use

```js
import {parseSelector} from 'hast-util-parse-selector'

console.log(parseSelector('.quux#bar.baz.qux'))
```

Yields:

```js
{ type: 'element',
  tagName: 'div',
  properties: { id: 'bar', className: [ 'quux', 'baz', 'qux' ] },
  children: [] }
```

## API

This package exports the identifier [`parseSelector`][api-parse-selector].
There is no default export.

### `parseSelector(selector?[, defaultTagName])`

Create a hast element from a simple CSS selector.

###### Parameters

*   `selector` (`string`, optional)
    —  simple CSS selector, can contain a tag name (`foo`), classes (`.bar`),
    and an ID (`#baz`), multiple classes are allowed, uses the last ID if
    multiple IDs are found
*   `defaultTagName` (`string`, default: `'div'`)
    — tag name to use if `selector` does not specify one

###### Returns

Built element ([`Element`][element]).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`hast-util-parse-selector@^4`, compatible with Node.js 16.

## Security

Improper use of the `selector` or `defaultTagName` can open you up to a
[cross-site scripting (XSS)][xss] attack as the value of `tagName`, when
resolving to `script`, injects a `script` element into the syntax tree.

Do not use user input in `selector` or use
[`hast-util-santize`][hast-util-sanitize].

## Related

*   [`hast-util-from-selector`](https://github.com/syntax-tree/hast-util-from-selector)
    — parse complex CSS selectors to nodes

## Contribute

See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
ways to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/syntax-tree/hast-util-parse-selector/workflows/main/badge.svg

[build]: https://github.com/syntax-tree/hast-util-parse-selector/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/hast-util-parse-selector.svg

[coverage]: https://codecov.io/github/syntax-tree/hast-util-parse-selector

[downloads-badge]: https://img.shields.io/npm/dm/hast-util-parse-selector.svg

[downloads]: https://www.npmjs.com/package/hast-util-parse-selector

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=hast-util-parse-selector

[size]: https://bundlejs.com/?q=hast-util-parse-selector

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/syntax-tree/unist/discussions

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[typescript]: https://www.typescriptlang.org

[license]: license

[author]: https://wooorm.com

[health]: https://github.com/syntax-tree/.github

[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md

[support]: https://github.com/syntax-tree/.github/blob/main/support.md

[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md

[hast]: https://github.com/syntax-tree/hast

[hast-util-sanitize]: https://github.com/syntax-tree/hast-util-sanitize

[hastscript]: https://github.com/syntax-tree/hastscript

[hast-util-from-selector]: https://github.com/syntax-tree/hast-util-from-selector

[element]: https://github.com/syntax-tree/hast#element

[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting

[api-parse-selector]: #parseselectorselector-defaulttagname


---

# hast-util-raw

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[hast][] utility to parse the tree and semistandard `raw` nodes (strings of
HTML) again, keeping positional info okay.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`Options`](#options)
  * [`raw(tree, options)`](#rawtree-options)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Related](#related)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package is a utility to parse a document again.
It passes each node and embedded raw HTML through an HTML parser
([`parse5`][parse5]), to recreate a tree exactly as how a browser would parse
it, while keeping the original data and positional info intact.

## When should I use this?

This utility is particularly useful when coming from markdown and wanting to
support HTML embedded inside that markdown (which requires passing
`allowDangerousHtml: true` to [`mdast-util-to-hast`][mdast-util-to-hast]).
Markdown dictates how, say, a list item or emphasis can be parsed.
We can use that to turn the markdown syntax tree into an HTML syntax tree.
But markdown also dictates that things that look like HTML, are passed through
untouched, even when it just looks like XML but doesn’t really make sense, so we
can’t normally use these strings of “HTML” to create an HTML syntax tree.
This utility can.
It can be used to take those strings of HTML and include them into the syntax
tree as actual nodes.

If your final result is HTML and you trust content, then “strings” are fine
(you can pass `allowDangerousHtml: true` to `hast-util-to-html`, which passes
HTML through untouched).
But there are two main cases where a proper syntax tree is preferred:

* hast utilities need a proper syntax tree as they operate on actual nodes to
  inspect or transform things, they can’t operate on strings of HTML
* other output formats (React, MDX, etc) need actual nodes and can’t handle
  strings of HTML

The plugin [`rehype-raw`][rehype-raw] wraps this utility at a higher-level
(easier) abstraction.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install hast-util-raw
```

In Deno with [`esm.sh`][esmsh]:

```js
import {raw} from 'https://esm.sh/hast-util-raw@9'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {raw} from 'https://esm.sh/hast-util-raw@9?bundle'
</script>
```

## Use

```js
import {h} from 'hastscript'
import {raw} from 'hast-util-raw'

const tree = h('div', [h('h1', ['Foo ', h('h2', 'Bar'), ' Baz'])])

const reformatted = raw(tree)

console.log(reformatted)
```

Yields:

```js
{ type: 'element',
  tagName: 'div',
  properties: {},
  children:
   [ { type: 'element',
       tagName: 'h1',
       properties: {},
       children: [Object] },
     { type: 'element',
       tagName: 'h2',
       properties: {},
       children: [Object] },
     { type: 'text', value: ' Baz' } ] }
```

## API

### `Options`

Configuration.

###### Fields

* `file?` (`VFile | null | undefined`)
  — corresponding virtual file representing the input document (optional)
* `passThrough?` (`Array<string> | null | undefined`)

  List of custom hast node types to pass through (as in, keep) (optional).

  If the passed through nodes have children, those children are expected to
  be hast again and will be handled.
* `tagfilter?` (`boolean | null | undefined`)

  Whether to disallow irregular tags in `raw` nodes according to GFM
  tagfilter
  (default: `false`).

  This affects the following tags,
  grouped by their kind:
  * `RAWTEXT`: `iframe`, `noembed`, `noframes`, `style`, `xmp`
  * `RCDATA`: `textarea`, `title`
  * `SCRIPT_DATA`: `script`
  * `PLAINTEXT`: `plaintext`
  When you know that you do not want authors to write these tags,
  you can enable this option to prevent their use from running amok.

  See:
  [*Disallowed Raw HTML* in
  `cmark-gfm`](https://github.github.com/gfm/#disallowed-raw-html-extension-).

### `raw(tree, options)`

Pass a hast tree through an HTML parser, which will fix nesting, and turn
raw nodes into actual nodes.

###### Parameters

* `tree` (`Root | RootContent`)
  — original hast tree to transform
* `options?` (`Options | null | undefined`)
  — configuration (optional)

###### Returns

Parsed again tree (`Root | RootContent`).

## Types

This package is fully typed with [TypeScript][].
It exports the additional type [`Options`][api-options].

The `Raw` node type is registered by and exposed from
[`mdast-util-to-hast`][mdast-util-to-hast].

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, `hast-util-raw@^9`,
compatible with Node.js 16.

## Security

Use of `hast-util-raw` can open you up to a [cross-site scripting (XSS)][xss]
attack as `raw` nodes are unsafe.
The following example shows how a raw node is used to inject a script that runs
when loaded in a browser.

```js
raw(u('root', [u('raw', '<script>alert(1)</script>')]))
```

Yields:

```html
<script>alert(1)</script>
```

Either do not use this utility in combination with user input, or use
[`hast-util-santize`][hast-util-sanitize].

## Related

* [`mdast-util-to-hast`][mdast-util-to-hast]
  — transform mdast to hast
* [`rehype-raw`](https://github.com/rehypejs/rehype-raw)
  — rehype plugin

## Contribute

See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
ways to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/syntax-tree/hast-util-raw/workflows/main/badge.svg

[build]: https://github.com/syntax-tree/hast-util-raw/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/hast-util-raw.svg

[coverage]: https://codecov.io/github/syntax-tree/hast-util-raw

[downloads-badge]: https://img.shields.io/npm/dm/hast-util-raw.svg

[downloads]: https://www.npmjs.com/package/hast-util-raw

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=hast-util-raw

[size]: https://bundlejs.com/?q=hast-util-raw

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/syntax-tree/unist/discussions

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[typescript]: https://www.typescriptlang.org

[license]: license

[author]: https://wooorm.com

[health]: https://github.com/syntax-tree/.github

[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md

[support]: https://github.com/syntax-tree/.github/blob/main/support.md

[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md

[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting

[hast]: https://github.com/syntax-tree/hast

[mdast-util-to-hast]: https://github.com/syntax-tree/mdast-util-to-hast

[hast-util-sanitize]: https://github.com/syntax-tree/hast-util-sanitize

[rehype-raw]: https://github.com/rehypejs/rehype-raw

[parse5]: https://github.com/inikulin/parse5

[api-options]: #options


---

# hast-util-to-estree

[![Build][badge-build-image]][badge-build-url]
[![Coverage][badge-coverage-image]][badge-coverage-url]
[![Downloads][badge-downloads-image]][badge-downloads-url]
[![Size][badge-size-image]][badge-size-url]

[hast][github-hast] utility to transform to [estree][github-estree] (JSX).

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`toEstree(tree[, options])`](#toestreetree-options)
  * [`defaultHandlers`](#defaulthandlers)
  * [`ElementAttributeNameCase`](#elementattributenamecase)
  * [`Handle`](#handle)
  * [`Options`](#options)
  * [`Space`](#space)
  * [`State`](#state)
  * [`StylePropertyNameCase`](#stylepropertynamecase)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Related](#related)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package is a utility that takes a
[hast][github-hast] (HTML)
syntax tree as input and turns it into an
[estree][github-estree] (JavaScript)
syntax tree (with a JSX extension).
This package also supports embedded MDX nodes.

## When should I use this?

This project is useful when you want to embed HTML as JSX inside JS while
working with syntax trees.
This is used in [MDX][mdxjs].

## Install

This package is [ESM only][github-gist-esm].
In Node.js (version 16+), install with [npm][npmjs-install]:

```sh
npm install hast-util-to-estree
```

In Deno with [`esm.sh`][esmsh]:

```js
import {toEstree} from 'https://esm.sh/hast-util-to-estree@3'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {toEstree} from 'https://esm.sh/hast-util-to-estree@3?bundle'
</script>
```

## Use

Say our module `example.html` contains:

```html
<!doctype html>
<html lang=en>
<title>Hi!</title>
<link rel=stylesheet href=index.css>
<h1>Hello, world!</h1>
<a download style="width:1;height:10px"></a>
<!--commentz-->
<svg xmlns="http://www.w3.org/2000/svg">
  <title>SVG `&lt;ellipse&gt;` element</title>
  <ellipse
    cx="120"
    cy="70"
    rx="100"
    ry="50"
  />
</svg>
<script src="index.js"></script>
```

…and our module `example.js` looks as follows:

```js
import fs from 'node:fs/promises'
import {jsx, toJs} from 'estree-util-to-js'
import {fromHtml} from 'hast-util-from-html'
import {toEstree} from 'hast-util-to-estree'

const hast = fromHtml(await fs.readFile('example.html'))

const estree = toEstree(hast)

console.log(toJs(estree, {handlers: jsx}).value)
```

…now running `node example.js` (and prettier) yields:

```js
/* Commentz */
;<>
  <html lang="en">
    <head>
      <title>{'Hi!'}</title>
      {'\n'}
      <link rel="stylesheet" href="index.css" />
      {'\n'}
    </head>
    <body>
      <h1>{'Hello, world!'}</h1>
      {'\n'}
      <a
        download
        style={{
          width: '1',
          height: '10px'
        }}
      />
      {'\n'}
      {}
      {'\n'}
      <svg xmlns="http://www.w3.org/2000/svg">
        {'\n  '}
        <title>{'SVG `<ellipse>` element'}</title>
        {'\n  '}
        <ellipse cx="120" cy="70" rx="100" ry="50" />
        {'\n'}
      </svg>
      {'\n'}
      <script src="index.js" />
      {'\n'}
    </body>
  </html>
</>
```

## API

This package exports the identifiers [`defaultHandlers`][api-default-handlers]
and [`toEstree`][api-to-estree].
There is no default export.

### `toEstree(tree[, options])`

Transform a hast tree (with embedded MDX nodes) into an estree (with JSX
nodes).

##### Notes

###### Comments

Comments are attached to the tree in their neighbouring nodes (`recast`,
`babel` style) and also added as a `comments` array on the program node
(`espree` style).
You may have to do `program.comments = undefined` for certain compilers.

###### Frameworks

There are differences between what JSX frameworks accept, such as whether they
accept `class` or `className`, or `background-color` or `backgroundColor`.

For JSX components written in MDX, the author has to be aware of this
difference and write code accordingly.
For hast elements transformed by this project, this will be handled through
options.

| Framework | `elementAttributeNameCase` | `stylePropertyNameCase` |
| --------- | -------------------------- | ----------------------- |
| Preact    | `'html'`                   | `'dom'`                 |
| React     | `'react'`                  | `'dom'`                 |
| Solid     | `'html'`                   | `'css'`                 |
| Vue       | `'html'`                   | `'dom'`                 |

###### Parameters

* `tree` ([`HastNode`][github-hast-nodes])
  — hast tree
* `options` ([`Options`][api-options], optional)
  — configuration

###### Returns

estree program node ([`Program`][github-estree-program]).

The program’s last child in `body` is most likely an `ExpressionStatement`,
whose expression is a `JSXFragment` or a `JSXElement`.

Typically, there is only one node in `body`, however, this utility also supports
embedded MDX nodes in the HTML
(when [`mdast-util-mdx`][github-mdast-util-mdx] is used with mdast to parse
markdown before passing its nodes through to hast).
When MDX ESM import/exports are used, those nodes are added before the fragment
or element in body.

There aren’t many great estree serializers out there that support JSX.
To do that, you can use [`estree-util-to-js`][github-estree-util-to-js].
Or, use [`estree-util-build-jsx`][github-estree-util-build-jsx]
to turn JSX into function calls,
and then serialize with whatever (`astring`, `escodegen`).

### `defaultHandlers`

Default handlers for elements (`Record<string, Handle>`).

Each key is a node type, each value is a [`Handle`][api-handle].

### `ElementAttributeNameCase`

Specify casing to use for attribute names (TypeScript type).

HTML casing is for example `class`, `stroke-linecap`, `xml:lang`.
React casing is for example `className`, `strokeLinecap`, `xmlLang`.

###### Type

```ts
type ElementAttributeNameCase = 'html' | 'react'
```

### `Handle`

Turn a hast node into an estree node (TypeScript type).

###### Parameters

* `node` ([`HastNode`][github-hast-nodes])
  — expected hast node
* `state` ([`State`][api-state])
  — info passed around about the current state

###### Returns

JSX child (`JsxChild`, optional).

You can also add more results to `state.esm` and `state.comments`.

### `Options`

Configuration (TypeScript type).

###### Fields

* `elementAttributeNameCase`
  ([`ElementAttributeNameCase`][api-element-attribute-name-case], default:
  `'react'`)
  — specify casing to use for attribute names; this casing is used for hast
  elements, not for embedded MDX JSX nodes (components that someone authored
  manually)
* `handlers` (`Record<string, Handle>`, optional)
  — custom handlers
* `space` ([`Space`][api-space], default: `'html'`)
  — which space the document is in; when an `<svg>` element is found in the
  HTML space, this package already automatically switches to and from the SVG
  space when entering and exiting it
* `stylePropertyNameCase`
  ([`StylePropertyNameCase`][api-style-property-name-case],
  default: `'dom'`)
  — specify casing to use for property names in `style` objects; this casing
  is used for hast elements, not for embedded MDX JSX nodes (components that
  someone authored manually)
* `tableCellAlignToStyle` (`boolean`, default: `true`)
  — turn obsolete `align` props on `td` and `th` into CSS `style` props

### `Space`

Namespace (TypeScript type).

###### Type

```ts
type Space = 'html' | 'svg'
```

### `State`

Info passed around about the current state (TypeScript type).

###### Fields

* `all` (`(node: HastParent) => EstreeJsxChild | undefined`)
  — transform children of a hast parent to estree
* `comments` (`Array<EstreeComment>`)
  — list of estree comments
* `createJsxAttributeName` (`(name: string) => EstreeJsxAttributeName`)
  — create a JSX attribute name
* `createJsxElementName` (`(name: string) => EstreeJsxElementName`)
  — create a JSX attribute name
* `elementAttributeNameCase`
  ([`ElementAttributeNameCase`][api-element-attribute-name-case])
  — casing to use for attribute names
* `esm` (`Array<EstreeNode>`)
  — list of top-level estree nodes
* `handle` (`(node: HastNode) => EstreeJsxChild | undefined`)
  — transform a hast node to estree
* `inherit` (`(from: HastNode, to: EstreeNode) => undefined`)
  — take positional info and data from `from` (use `patch` if you don’t want
  data)
* `patch` (`(from: HastNode, to: EstreeNode) => undefined`)
  — take positional info from `from` (use `inherit` if you also want data)
* `schema` ([`Schema`][github-property-information-schema])
  — current schema
* `stylePropertyNameCase`
  ([`StylePropertyNameCase`][api-style-property-name-case])
  — casing for property names in `style` objects
* `tableCellAlignToStyle` (`boolean`)
  — turn obsolete `align` props on `td` and `th` into CSS `style` props

### `StylePropertyNameCase`

Casing to use for property names in `style` objects (TypeScript type).

CSS casing is for example `background-color` and `-webkit-line-clamp`.
DOM casing is for example `backgroundColor` and `WebkitLineClamp`.

###### Type

```ts
type StylePropertyNameCase = 'css' | 'dom'
```

## Types

This package is fully typed with [TypeScript][].
It exports the additional types
[`ElementAttributeNameCase`][api-element-attribute-name-case],
[`Handle`][api-handle], [`Options`][api-options],
[`Space`][api-space], [`State`][api-state], and
[`StylePropertyNameCase`][api-style-property-name-case].

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, `hast-util-to-estree@^3`,
compatible with Node.js 16.

## Security

You’re working with JavaScript.
It’s not safe.

## Related

* [`estree-util-build-jsx`][github-estree-util-build-jsx]
  — transform JSX to function calls
* [`hastscript`][github-hastscript]
  — hyperscript compatible interface for creating nodes
* [`hast-util-from-dom`](https://github.com/syntax-tree/hast-util-from-dom)
  — transform a DOM tree to hast

## Contribute

See [`contributing.md`][health-contributing] in [`syntax-tree/.github`][health]
for ways to get started.
See [`support.md`][health-support] for ways to get help.

This project has a [code of conduct][health-coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][file-license] © [Titus Wormer][wooorm]

<!-- Definitions -->

[api-default-handlers]: #defaulthandlers

[api-element-attribute-name-case]: #elementattributenamecase

[api-handle]: #handle

[api-options]: #options

[api-space]: #space

[api-state]: #state

[api-style-property-name-case]: #stylepropertynamecase

[api-to-estree]: #toestreetree-options

[badge-build-image]: https://github.com/syntax-tree/hast-util-to-estree/workflows/main/badge.svg

[badge-build-url]: https://github.com/syntax-tree/hast-util-to-estree/actions

[badge-coverage-image]: https://img.shields.io/codecov/c/github/syntax-tree/hast-util-to-estree.svg

[badge-coverage-url]: https://codecov.io/github/syntax-tree/hast-util-to-estree

[badge-downloads-image]: https://img.shields.io/npm/dm/hast-util-to-estree.svg

[badge-downloads-url]: https://www.npmjs.com/package/hast-util-to-estree

[badge-size-image]: https://img.shields.io/bundlejs/size/hast-util-to-estree

[badge-size-url]: https://bundlejs.com/?q=hast-util-to-estree

[esmsh]: https://esm.sh

[file-license]: license

[github-estree]: https://github.com/estree/estree

[github-estree-program]: https://github.com/estree/estree/blob/master/es5.md#programs

[github-estree-util-build-jsx]: https://github.com/wooorm/estree-util-build-jsx

[github-estree-util-to-js]: https://github.com/syntax-tree/estree-util-to-js

[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[github-hast]: https://github.com/syntax-tree/hast

[github-hast-nodes]: https://github.com/syntax-tree/hast#nodes

[github-hastscript]: https://github.com/syntax-tree/hastscript

[github-mdast-util-mdx]: https://github.com/syntax-tree/mdast-util-mdx

[github-property-information-schema]: https://github.com/wooorm/property-information#api

[health]: https://github.com/syntax-tree/.github

[health-coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md

[health-contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md

[health-support]: https://github.com/syntax-tree/.github/blob/main/support.md

[mdxjs]: https://mdxjs.com

[npmjs-install]: https://docs.npmjs.com/cli/install

[typescript]: https://www.typescriptlang.org

[wooorm]: https://wooorm.com


---

# hast-util-to-jsx-runtime

[![Build][badge-build-image]][badge-build-url]
[![Coverage][badge-coverage-image]][badge-coverage-url]
[![Downloads][badge-downloads-image]][badge-downloads-url]
[![Size][badge-size-image]][badge-size-url]

hast utility to transform a tree to
preact, react, solid, svelte, vue, etcetera,
with an automatic JSX runtime.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`toJsxRuntime(tree, options)`](#tojsxruntimetree-options)
  * [`Components`](#components)
  * [`CreateEvaluater`](#createevaluater)
  * [`ElementAttributeNameCase`](#elementattributenamecase)
  * [`EvaluateExpression`](#evaluateexpression)
  * [`EvaluateProgram`](#evaluateprogram)
  * [`Evaluater`](#evaluater)
  * [`ExtraProps`](#extraprops)
  * [`Fragment`](#fragment)
  * [`Jsx`](#jsx)
  * [`JsxDev`](#jsxdev)
  * [`Options`](#options)
  * [`Props`](#props)
  * [`Source`](#source)
  * [`Space`](#space)
  * [`StylePropertyNameCase`](#stylepropertynamecase)
* [Errors](#errors)
* [Examples](#examples)
  * [Example: Preact](#example-preact)
  * [Example: Solid](#example-solid)
  * [Example: Svelte](#example-svelte)
  * [Example: Vue](#example-vue)
* [Syntax](#syntax)
* [Compatibility](#compatibility)
* [Security](#security)
* [Related](#related)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package is a utility that takes a [hast][github-hast] tree and an
[automatic JSX runtime][reactjs-jsx-runtime] and turns the tree into anything
you wish.

## When should I use this?

You can use this package when you have a hast syntax tree and want to use it
with whatever framework.

This package uses an automatic JSX runtime,
which is a sort of lingua franca for frameworks to support JSX.

Notably,
automatic runtimes have support for passing extra information in development,
and have guaranteed support for fragments.

## Install

This package is [ESM only][github-gist-esm].
In Node.js (version 16+),
install with [npm][npmjs-install]:

```sh
npm install hast-util-to-jsx-runtime
```

In Deno with [`esm.sh`][esmsh]:

```js
import {toJsxRuntime} from 'https://esm.sh/hast-util-to-jsx-runtime@2'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {toJsxRuntime} from 'https://esm.sh/hast-util-to-jsx-runtime@2?bundle'
</script>
```

## Use

```js
import {h} from 'hastscript'
import {toJsxRuntime} from 'hast-util-to-jsx-runtime'
import {Fragment, jsxs, jsx} from 'react/jsx-runtime'
import {renderToStaticMarkup} from 'react-dom/server'

const tree = h('h1', 'Hello, world!')

const doc = renderToStaticMarkup(toJsxRuntime(tree, {Fragment, jsxs, jsx}))

console.log(doc)
```

Yields:

```html
<h1>Hello, world!</h1>
```

> **Note**:
> to add better type support,
> register a global JSX namespace:
>
> ```ts
> import type {JSX as Jsx} from 'react/jsx-runtime'
>
> declare global {
>   namespace JSX {
>     type ElementClass = Jsx.ElementClass
>     type Element = Jsx.Element
>     type IntrinsicElements = Jsx.IntrinsicElements
>   }
> }
> ```

## API

This package exports the identifier [`toJsxRuntime`][api-to-jsx-runtime].
It exports the [TypeScript][] types
[`Components`][api-components],
[`CreateEvaluater`][api-create-evaluater],
[`ElementAttributeNameCase`][api-element-attribute-name-case],
[`EvaluateExpression`][api-evaluate-expression],
[`EvaluateProgram`][api-evaluate-program],
[`Evaluater`][api-evaluater],
[`ExtraProps`][api-extra-props],
[`Fragment`][api-fragment],
[`Jsx`][api-jsx],
[`JsxDev`][api-jsx-dev],
[`Options`][api-options],
[`Props`][api-props],
[`Source`][api-source],
[`Space`][api-Space],
and
[`StylePropertyNameCase`][api-style-property-name-case].
There is no default export.

### `toJsxRuntime(tree, options)`

Transform a hast tree to
preact, react, solid, svelte, vue, etcetera,
with an automatic JSX runtime.

##### Parameters

* `tree`
  ([`Node`][github-hast-nodes])
  — tree to transform
* `options`
  ([`Options`][api-options], required)
  — configuration

##### Returns

Result from your configured JSX runtime
(`JSX.Element` if defined,
otherwise `unknown` which you can cast yourself).

### `Components`

Possible components to use (TypeScript type).

Each key is a tag name typed in `JSX.IntrinsicElements`,
if defined.
Each value is either a different tag name
or a component accepting the corresponding props
(and an optional `node` prop if `passNode` is on).

You can access props at `JSX.IntrinsicElements`.
For example,
to find props for `a`,
use `JSX.IntrinsicElements['a']`.

###### Type

```ts
import type {Element} from 'hast'

type ExtraProps = {node?: Element | undefined}

type Components = {
  [TagName in keyof JSX.IntrinsicElements]:
    | Component<JSX.IntrinsicElements[TagName] & ExtraProps>
    | keyof JSX.IntrinsicElements
}

type Component<ComponentProps> =
  // Class component:
  | (new (props: ComponentProps) => JSX.ElementClass)
  // Function component:
  | ((props: ComponentProps) => JSX.Element | string | null | undefined)
```

### `CreateEvaluater`

Create an evaluator that turns ESTree ASTs from embedded MDX into values
(TypeScript type).

###### Parameters

There are no parameters.

###### Returns

Evaluater ([`Evaluater`][api-evaluater]).

### `ElementAttributeNameCase`

Casing to use for attribute names (TypeScript type).

HTML casing is for example
`class`, `stroke-linecap`, `xml:lang`.
React casing is for example
`className`, `strokeLinecap`, `xmlLang`.

###### Type

```ts
type ElementAttributeNameCase = 'html' | 'react'
```

### `EvaluateExpression`

Turn an MDX expression into a value (TypeScript type).

###### Parameters

* `expression` (`Expression` from `@types/estree`)
  — estree expression

###### Returns

Result of expression (`unknown`).

### `EvaluateProgram`

Turn an MDX program (export/import statements) into a value (TypeScript type).

###### Parameters

* `program` (`Program` from `@types/estree`)
  — estree program

###### Returns

Result of program (`unknown`);
should likely be `undefined` as ESM changes the scope but doesn’t yield
something.

### `Evaluater`

Evaluator that turns ESTree ASTs from embedded MDX into values (TypeScript
type).

###### Fields

* `evaluateExpression` ([`EvaluateExpression`][api-evaluate-expression])
  — evaluate an expression
* `evaluateProgram` ([`EvaluateProgram`][api-evaluate-program])
  — evaluate a program

### `ExtraProps`

Extra fields we pass (TypeScript type).

###### Type

```ts
type ExtraProps = {node?: Element | undefined}
```

### `Fragment`

Represent the children,
typically a symbol (TypeScript type).

###### Type

```ts
type Fragment = unknown
```

### `Jsx`

Create a production element (TypeScript type).

###### Parameters

* `type` (`unknown`)
  — element type:
  `Fragment` symbol,
  tag name (`string`),
  component
* `props` ([`Props`][api-props])
  — element props,
  `children`,
  and maybe `node`
* `key` (`string` or `undefined`)
  — dynamicly generated key to use

###### Returns

Element from your framework
(`JSX.Element` if defined,
otherwise `unknown` which you can cast yourself).

### `JsxDev`

Create a development element (TypeScript type).

###### Parameters

* `type` (`unknown`)
  — element type:
  `Fragment` symbol,
  tag name (`string`),
  component
* `props` ([`Props`][api-props])
  — element props,
  `children`,
  and maybe `node`
* `key` (`string` or `undefined`)
  — dynamicly generated key to use
* `isStaticChildren` (`boolean`)
  — whether two or more children are passed (in an array),
  which is whether `jsxs` or `jsx` would be used
* `source` ([`Source`][api-source])
  — info about source
* `self` (`undefined`)
  — nothing (this is used by frameworks that have components,
  we don’t)

###### Returns

Element from your framework
(`JSX.Element` if defined,
otherwise `unknown` which you can cast yourself).

### `Options`

Configuration (TypeScript type).

###### Fields

* `Fragment` ([`Fragment`][api-fragment], required)
  — fragment
* `jsxDEV` ([`JsxDev`][api-jsx-dev], required in development)
  — development JSX
* `jsxs` ([`Jsx`][api-jsx], required in production)
  — static JSX
* `jsx` ([`Jsx`][api-jsx], required in production)
  — dynamic JSX
* `components` ([`Partial<Components>`][api-components], optional)
  — components to use
* `createEvaluater` ([`CreateEvaluater`][api-create-evaluater], optional)
  — create an evaluator that turns ESTree ASTs into values
* `development` (`boolean`, default: `false`)
  — whether to use `jsxDEV` when on or `jsx` and `jsxs` when off
* `elementAttributeNameCase`
  ([`ElementAttributeNameCase`][api-element-attribute-name-case],
  default: `'react'`)
  — specify casing to use for attribute names
* `filePath` (`string`, optional)
  — file path to the original source file,
  passed in source info to `jsxDEV` when using the automatic runtime with
  `development: true`
* `passNode` (`boolean`, default: `false`)
  — pass the hast element node to components
* `space` ([`Space`][api-space], default: `'html'`)
  — whether `tree` is in the `'html'` or `'svg'` space, when an `<svg>`
  element is found in the HTML space,
  this package already automatically switches to and from the SVG space when
  entering and exiting it
* `stylePropertyNameCase`
  ([`StylePropertyNameCase`][api-style-property-name-case],
  default: `'dom'`)
  — specify casing to use for property names in `style` objects
* `tableCellAlignToStyle`
  (`boolean`, default: `true`)
  — turn obsolete `align` props on `td` and `th` into CSS `style` props

### `Props`

Properties and children (TypeScript type).

###### Type

```ts
import type {Element} from 'hast'

type Props = {
  [prop: string]:
    | Array<JSX.Element | string | null | undefined> // For `children`.
    | Record<string, string> // For `style`.
    | Element // For `node`.
    | boolean
    | number
    | string
    | undefined
  children: Array<JSX.Element | string | null | undefined> | undefined
  node?: Element | undefined
}
```

### `Source`

Info about source (TypeScript type).

###### Fields

* `columnNumber` (`number` or `undefined`)
  — column where thing starts (0-indexed)
* `fileName` (`string` or `undefined`)
  — name of source file
* `lineNumber` (`number` or `undefined`)
  — line where thing starts (1-indexed)

### `Space`

Namespace (TypeScript type).

> 👉 **Note**:
> hast is not XML;
> it supports SVG as embedded in HTML;
> it does not support the features available in XML;
> passing SVG might break but fragments of modern SVG should be fine;
> use `xast` if you need to support SVG as XML.

###### Type

```ts
type Space = 'html' | 'svg'
```

### `StylePropertyNameCase`

Casing to use for property names in `style` objects (TypeScript type).

CSS casing is for example `background-color` and `-webkit-line-clamp`.
DOM casing is for example `backgroundColor` and `WebkitLineClamp`.

###### Type

```ts
type StylePropertyNameCase = 'css' | 'dom'
```

## Errors

The following errors are thrown:

###### ``Expected `Fragment` in options``

This error is thrown when either `options` is not passed at all or
when `options.Fragment` is `undefined`.

The automatic JSX runtime needs a symbol for a fragment to work.

To solve the error,
make sure you are passing the correct fragment symbol from your framework.

###### `` Expected `jsxDEV` in options when `development: true` ``

This error is thrown when `options.development` is turned on (`true`),
but when `options.jsxDEV` is not a function.

The automatic JSX runtime,
in development,
needs this function.

To solve the error,
make sure you are importing the correct runtime functions
(for example, `'react/jsx-dev-runtime'`),
and pass `jsxDEV`.

###### ``Expected `jsx` in production options``

###### ``Expected `jsxs` in production options``

These errors are thrown when `options.development` is *not* turned on
(`false` or not defined),
and when `options.jsx` or `options.jsxs` are not functions.

The automatic JSX runtime,
in production,
needs these functions.

To solve the error,
make sure you are importing the correct runtime functions
(for example, `'react/jsx-runtime'`),
and pass `jsx` and `jsxs`.

###### `` Cannot handle MDX estrees without `createEvaluater` ``

This error is thrown when MDX nodes are passed that represent JavaScript
programs or expressions.

Supporting JavaScript can be unsafe and requires a different project.
To support JavaScript,
pass a `createEvaluater` function in `options`.

###### ``Cannot parse `style` attribute``

This error is thrown when a `style` attribute is found on an element,
which cannot be parsed as CSS.

Most frameworks don’t accept `style` as a string,
so we need to parse it as CSS,
and pass it as an object.
But when broken CSS is used,
such as `style="color:red; /*"`,
we crash.

To solve the error,
make sure authors write valid CSS.
Alternatively,
pass `options.ignoreInvalidStyle: true` to swallow these errors.

## Examples

### Example: Preact

> 👉 **Note**:
> you must set `elementAttributeNameCase: 'html'` for preact.

In Node.js,
do:

```js
import {h} from 'hastscript'
import {toJsxRuntime} from 'hast-util-to-jsx-runtime'
import {Fragment, jsx, jsxs} from 'preact/jsx-runtime'
import {render} from 'preact-render-to-string'

const result = render(
  toJsxRuntime(h('h1', 'hi!'), {
    Fragment,
    jsx,
    jsxs,
    elementAttributeNameCase: 'html'
  })
)

console.log(result)
```

Yields:

```html
<h1>hi!</h1>
```

In a browser,
do:

```js
import {h} from 'https://esm.sh/hastscript@9'
import {toJsxRuntime} from 'https://esm.sh/hast-util-to-jsx-runtime@2'
import {Fragment, jsx, jsxs} from 'https://esm.sh/preact@10/jsx-runtime'
import {render} from 'https://esm.sh/preact@10'

render(
  toJsxRuntime(h('h1', 'hi!'), {
    Fragment,
    jsx,
    jsxs,
    elementAttributeNameCase: 'html'
  }),
  document.getElementById('root')
)
```

To add better type support,
register a global JSX namespace:

```ts
import type {JSX as Jsx} from 'preact/jsx-runtime'

declare global {
  namespace JSX {
    type ElementClass = Jsx.ElementClass
    type Element = Jsx.Element
    type IntrinsicElements = Jsx.IntrinsicElements
  }
}
```

### Example: Solid

> 👉 **Note**:
> you must set `elementAttributeNameCase: 'html'` and
> `stylePropertyNameCase: 'css'` for Solid.

In Node.js,
do:

```js
import {h} from 'hastscript'
import {toJsxRuntime} from 'hast-util-to-jsx-runtime'
import {Fragment, jsx, jsxs} from 'solid-jsx/jsx-runtime'

console.log(
  toJsxRuntime(h('h1', 'hi!'), {
    Fragment,
    jsx,
    jsxs,
    elementAttributeNameCase: 'html',
    stylePropertyNameCase: 'css'
  }).t
)
```

Yields:

```html
<h1 >hi!</h1>
```

In a browser,
do:

```js
import {h} from 'https://esm.sh/hastscript@9'
import {toJsxRuntime} from 'https://esm.sh/hast-util-to-jsx-runtime@2'
import {Fragment, jsx, jsxs} from 'https://esm.sh/solid-js@1/h/jsx-runtime'
import {render} from 'https://esm.sh/solid-js@1/web'

render(Component, document.getElementById('root'))

function Component() {
  return toJsxRuntime(h('h1', 'hi!'), {
    Fragment,
    jsx,
    jsxs,
    elementAttributeNameCase: 'html',
    stylePropertyNameCase: 'css'
  })
}
```

To add better type support,
register a global JSX namespace:

```ts
import type {JSX as Jsx} from 'solid-js/jsx-runtime'

declare global {
  namespace JSX {
    type ElementClass = Jsx.ElementClass
    type Element = Jsx.Element
    type IntrinsicElements = Jsx.IntrinsicElements
  }
}
```

### Example: Svelte

<!-- To do: improve svelte when it fixes a bunch of bugs. -->

I have no clue how to render a Svelte component in Node,
but you can get that component with:

```js
import {h} from 'hastscript'
import {toJsxRuntime} from 'hast-util-to-jsx-runtime'
import {Fragment, jsx, jsxs} from 'svelte-jsx'

const svelteComponent = toJsxRuntime(h('h1', 'hi!'), {Fragment, jsx, jsxs})

console.log(svelteComponent)
```

Yields:

```text
[class Component extends SvelteComponent]
```

Types for Svelte are broken.
Raise it with Svelte.

### Example: Vue

> 👉 **Note**:
> you must set `elementAttributeNameCase: 'html'` for Vue.

In Node.js,
do:

```js
import serverRenderer from '@vue/server-renderer'
import {h} from 'hastscript'
import {toJsxRuntime} from 'hast-util-to-jsx-runtime'
import {Fragment, jsx, jsxs} from 'vue/jsx-runtime' // Available since `vue@3.3`.

console.log(
  await serverRenderer.renderToString(
    toJsxRuntime(h('h1', 'hi!'), {
      Fragment,
      jsx,
      jsxs,
      elementAttributeNameCase: 'html'
    })
  )
)
```

Yields:

```html
<h1>hi!</h1>
```

In a browser,
do:

```js
import {h} from 'https://esm.sh/hastscript@9'
import {toJsxRuntime} from 'https://esm.sh/hast-util-to-jsx-runtime@2'
import {createApp} from 'https://esm.sh/vue@3'
import {Fragment, jsx, jsxs} from 'https://esm.sh/vue@3/jsx-runtime'

createApp(Component).mount('#root')

function Component() {
  return toJsxRuntime(h('h1', 'hi!'), {
    Fragment,
    jsx,
    jsxs,
    elementAttributeNameCase: 'html'
  })
}
```

To add better type support,
register a global JSX namespace:

```ts
import type {JSX as Jsx} from 'vue/jsx-runtime'

declare global {
  namespace JSX {
    type ElementClass = Jsx.ElementClass
    type Element = Jsx.Element
    type IntrinsicElements = Jsx.IntrinsicElements
  }
}
```

## Syntax

HTML is parsed according to WHATWG HTML (the living standard),
which is also followed by browsers such as Chrome,
Firefox,
and Safari.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release,
we drop support for unmaintained versions of Node.
This means we try to keep the current release line,
`hast-util-to-jsx-runtime@2`,
compatible with Node.js 16.

## Security

Be careful with user input in your hast tree.
Use [`hast-util-santize`][github-hast-util-sanitize] to make hast trees safe.

## Related

* [`hastscript`](https://github.com/syntax-tree/hastscript)
  — build hast trees
* [`hast-util-to-html`](https://github.com/syntax-tree/hast-util-to-html)
  — serialize hast as HTML
* [`hast-util-sanitize`][github-hast-util-sanitize]
  — sanitize hast

## Contribute

See [`contributing.md`][health-contributing]
in
[`syntax-tree/.github`][health]
for ways to get started.
See [`support.md`][health-support] for ways to get help.

This project has a [code of conduct][health-coc].
By interacting with this repository,
organization,
or community you agree to abide by its terms.

## License

[MIT][file-license] © [Titus Wormer][wooorm]

<!-- Definitions -->

[api-components]: #components

[api-create-evaluater]: #createevaluater

[api-element-attribute-name-case]: #elementattributenamecase

[api-evaluate-expression]: #evaluateexpression

[api-evaluate-program]: #evaluateprogram

[api-evaluater]: #evaluater

[api-extra-props]: #extraprops

[api-fragment]: #fragment

[api-jsx]: #jsx

[api-jsx-dev]: #jsxdev

[api-options]: #options

[api-props]: #props

[api-source]: #source

[api-space]: #space

[api-style-property-name-case]: #stylepropertynamecase

[api-to-jsx-runtime]: #tojsxruntimetree-options

[badge-build-image]: https://github.com/syntax-tree/hast-util-to-jsx-runtime/workflows/main/badge.svg

[badge-build-url]: https://github.com/syntax-tree/hast-util-to-jsx-runtime/actions

[badge-coverage-image]: https://img.shields.io/codecov/c/github/syntax-tree/hast-util-to-jsx-runtime.svg

[badge-coverage-url]: https://codecov.io/github/syntax-tree/hast-util-to-jsx-runtime

[badge-downloads-image]: https://img.shields.io/npm/dm/hast-util-to-jsx-runtime.svg

[badge-downloads-url]: https://www.npmjs.com/package/hast-util-to-jsx-runtime

[badge-size-image]: https://img.shields.io/bundlejs/size/hast-util-to-jsx-runtime

[badge-size-url]: https://bundlejs.com/?q=hast-util-to-jsx-runtime

[esmsh]: https://esm.sh

[file-license]: license

[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[github-hast]: https://github.com/syntax-tree/hast

[github-hast-nodes]: https://github.com/syntax-tree/hast#nodes

[github-hast-util-sanitize]: https://github.com/syntax-tree/hast-util-sanitize

[health]: https://github.com/syntax-tree/.github

[health-coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md

[health-contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md

[health-support]: https://github.com/syntax-tree/.github/blob/main/support.md

[npmjs-install]: https://docs.npmjs.com/cli/install

[reactjs-jsx-runtime]: https://reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html

[typescript]: https://www.typescriptlang.org

[wooorm]: https://wooorm.com


---

# property-information

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]

Info on the properties and attributes of the web platform (HTML, SVG, ARIA, XML,
XMLNS, XLink).

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`find(schema, name)`](#findschema-name)
    *   [`normalize(name)`](#normalizename)
    *   [`html`](#html)
    *   [`svg`](#svg)
    *   [`hastToReact`](#hasttoreact)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Support](#support)
*   [Security](#security)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package contains lots of info on all the properties and attributes found
on the web platform.
It includes data on HTML, SVG, ARIA, XML, XMLNS, and XLink.
The names of the properties follow [hast][]’s sensible naming scheme.
It includes info on what data types attributes hold, such as whether they’re
booleans or contain lists of space separated numbers.

## When should I use this?

You can use this package if you’re working with hast, which is an AST for HTML,
or have goals related to ASTs, such as figuring out which properties or
attributes are valid, or what data types they hold.

## Install

This package is [ESM only][esm].
In Node.js (version 14.14+, 16.0+), install with [npm][]:

```sh
npm install property-information
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as propertyInformation from 'https://esm.sh/property-information@6'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as propertyInformation from 'https://esm.sh/property-information@6?bundle'
</script>
```

## Use

```js
import {html, svg, find, normalize} from 'property-information'

console.log(find(html, 'className'))
// Or: find(html, 'class')
console.log(find(svg, 'horiz-adv-x'))
// Or: find(svg, 'horizAdvX')
console.log(find(svg, 'xlink:arcrole'))
// Or: find(svg, 'xLinkArcRole')
console.log(find(html, 'xmlLang'))
// Or: find(html, 'xml:lang')
console.log(find(html, 'ariaValueNow'))
// Or: find(html, 'aria-valuenow')
```

Yields:

```js
{space: 'html', attribute: 'class', property: 'className', spaceSeparated: true}
{space: 'svg', attribute: 'horiz-adv-x', property: 'horizAdvX', number: true}
{space: 'xlink', attribute: 'xlink:arcrole', property: 'xLinkArcrole'}
{space: 'xml', attribute: 'xml:lang', property: 'xmlLang'}
{attribute: 'aria-valuenow', property: 'ariaValueNow', number: true}
```

## API

This package exports the identifiers `html`, `svg`, `find`, `normalize`,
and `hastToReact`.
There is no default export.

### `find(schema, name)`

Look up info on a property.

In most cases, the given `schema` contains info on the property.
All standard, most legacy, and some non-standard properties are supported.
For these cases, the returned [`Info`][info] has hints about the value of the
property.

`name` can also be a [valid data attribute or property][data], in which case an
[`Info`][info] object with the correctly cased `attribute` and `property` is
returned.

`name` can be an unknown attribute, in which case an [`Info`][info] object
with `attribute` and `property` set to the given name is returned.
It is not recommended to provide unsupported legacy or recently specced
properties.

#### Parameters

*   `schema` ([`Schema`][schema])
    — either the `html` or `svg` export
*   `name` (`string`)
    — an attribute-like or property-like name that is passed through
    [`normalize`][normalize] to find the correct info

#### Returns

[`Info`][info].

#### Example

Aside from the aforementioned example, which shows known HTML, SVG, XML, XLink,
and ARIA support, data properties, and attributes are also supported:

```js
console.log(find(html, 'data-date-of-birth'))
// Or: find(html, 'dataDateOfBirth')
// => {attribute: 'data-date-of-birth', property: 'dataDateOfBirth'}
```

Unknown values are passed through untouched:

```js
console.log(find(html, 'un-Known'))
// => {attribute: 'un-Known', property: 'un-Known'}
```

### `normalize(name)`

Get the cleaned case insensitive form of an attribute or property.

#### Parameters

*   `name` (`string`)
    — an attribute-like or property-like name

#### Returns

`string` that can be used to look up the properly cased property on a
[`Schema`][schema].

#### Example

```js
html.normal[normalize('for')] // => 'htmlFor'
svg.normal[normalize('VIEWBOX')] // => 'viewBox'
html.normal[normalize('unknown')] // => undefined
html.normal[normalize('accept-charset')] // => 'acceptCharset'
```

### `html`

### `svg`

[`Schema`][schema] for either HTML or SVG, containing info on properties from
the primary space (HTML or SVG) and related embedded spaces (ARIA, XML, XMLNS,
XLink).

#### Example

```js
console.log(html.property.htmlFor)
// => {space: 'html', attribute: 'for', property: 'htmlFor' spaceSeparated: true}
console.log(svg.property.viewBox)
// => {space: 'svg', attribute: 'viewBox', property: 'viewBox'}
console.log(html.property.unknown)
// => undefined
```

#### `Schema`

A schema for a primary space.

*   `space` (`'html'` or `'svg'`)
    — primary space of the schema
*   `normal` (`Record<string, string>`)
    — object mapping normalized attributes and properties to properly cased
    properties
*   `property` ([`Record<string, Info>`][info])
    — object mapping properties to info

#### `Info`

Info on a property.

*   `space` (`'html'`, `'svg'`, `'xml'`, `'xlink'`, `'xmlns'`, optional)
    — [space][namespace] of the property
*   `attribute` (`string`)
    — attribute name for the property that could be used in markup (for
    example: `'aria-describedby'`, `'allowfullscreen'`, `'xml:lang'`, `'for'`,
    or `'charoff'`)
*   `property` (`string`)
    — JavaScript-style camel-cased name, based on the DOM, but sometimes
    different (for example: `'ariaDescribedBy'`, `'allowFullScreen'`,
    `'xmlLang'`, `'htmlFor'`, `'charOff'`)
*   `boolean` (`boolean`)
    — the property is a `boolean` (for example: `hidden`).
    These properties have an on state when defined and an off state when not
    defined
*   `booleanish` (`boolean`)
    — the property is like a `boolean` (for example: `draggable`)
    These properties have both an on and off state when defined, and another
    state when not defined
*   `overloadedBoolean` (`boolean`)
    — the property is like a `boolean` (for example: `download`)
    These properties have an on state plus more states when defined and an off
    state when not defined
*   `number` (`boolean`)
    — the property is a `number` (for example: `height`)
*   `spaceSeparated` (`boolean`)
    — the property is a list separated by spaces (for example: `className`)
*   `commaSeparated` (`boolean`)
    — the property is a list separated by commas (for example: `srcSet`)
*   `commaOrSpaceSeparated` (`boolean`)
    — the property is a list separated by spaces or commas (for example:
    `strokeDashArray`)
*   `mustUseProperty` (`boolean`)
    — useful when working with the DOM, in which case this property has to be
    changed as a field on the element, rather than through `setAttribute`
    (this is true only for `'checked'`, `'multiple'`, `'muted'`, and
    `'selected'`)
*   `defined` (`boolean`)
    — the property is [defined by a space](#support).
    This is true for values in HTML (including data and ARIA), SVG, XML,
    XMLNS, and XLink.
    Undefined properties can only be found through `find`

### `hastToReact`

[hast][] is close to [React][], but differs in a couple of cases.
To get a React property from a hast property, check if it is in `hastToReact`
(`Record<string, string>`), if it is, then use the corresponding value,
otherwise, use the hast property.

## Types

This package is fully typed with [TypeScript][].
It exports the additional types `Info` and `Schema`.

## Compatibility

This package is at least compatible with all maintained versions of Node.js.
As of now, that is Node.js 14.14+ and 16.0+.
It also works in Deno and modern browsers.

## Support

<!--list start-->

| Property                     | Attribute                      | Space         |
| ---------------------------- | ------------------------------ | ------------- |
| `aLink`                      | `alink`                        | `html`        |
| `abbr`                       | `abbr`                         | `html`        |
| `about`                      | `about`                        | `svg`         |
| `accentHeight`               | `accent-height`                | `svg`         |
| `accept`                     | `accept`                       | `html`        |
| `acceptCharset`              | `accept-charset`               | `html`        |
| `accessKey`                  | `accesskey`                    | `html`        |
| `accumulate`                 | `accumulate`                   | `svg`         |
| `action`                     | `action`                       | `html`        |
| `additive`                   | `additive`                     | `svg`         |
| `align`                      | `align`                        | `html`        |
| `alignmentBaseline`          | `alignment-baseline`           | `svg`         |
| `allow`                      | `allow`                        | `html`        |
| `allowFullScreen`            | `allowfullscreen`              | `html`        |
| `allowPaymentRequest`        | `allowpaymentrequest`          | `html`        |
| `allowTransparency`          | `allowtransparency`            | `html`        |
| `allowUserMedia`             | `allowusermedia`               | `html`        |
| `alphabetic`                 | `alphabetic`                   | `svg`         |
| `alt`                        | `alt`                          | `html`        |
| `amplitude`                  | `amplitude`                    | `svg`         |
| `arabicForm`                 | `arabic-form`                  | `svg`         |
| `archive`                    | `archive`                      | `html`        |
| `ariaActiveDescendant`       | `aria-activedescendant`        |               |
| `ariaAtomic`                 | `aria-atomic`                  |               |
| `ariaAutoComplete`           | `aria-autocomplete`            |               |
| `ariaBusy`                   | `aria-busy`                    |               |
| `ariaChecked`                | `aria-checked`                 |               |
| `ariaColCount`               | `aria-colcount`                |               |
| `ariaColIndex`               | `aria-colindex`                |               |
| `ariaColSpan`                | `aria-colspan`                 |               |
| `ariaControls`               | `aria-controls`                |               |
| `ariaCurrent`                | `aria-current`                 |               |
| `ariaDescribedBy`            | `aria-describedby`             |               |
| `ariaDetails`                | `aria-details`                 |               |
| `ariaDisabled`               | `aria-disabled`                |               |
| `ariaDropEffect`             | `aria-dropeffect`              |               |
| `ariaErrorMessage`           | `aria-errormessage`            |               |
| `ariaExpanded`               | `aria-expanded`                |               |
| `ariaFlowTo`                 | `aria-flowto`                  |               |
| `ariaGrabbed`                | `aria-grabbed`                 |               |
| `ariaHasPopup`               | `aria-haspopup`                |               |
| `ariaHidden`                 | `aria-hidden`                  |               |
| `ariaInvalid`                | `aria-invalid`                 |               |
| `ariaKeyShortcuts`           | `aria-keyshortcuts`            |               |
| `ariaLabel`                  | `aria-label`                   |               |
| `ariaLabelledBy`             | `aria-labelledby`              |               |
| `ariaLevel`                  | `aria-level`                   |               |
| `ariaLive`                   | `aria-live`                    |               |
| `ariaModal`                  | `aria-modal`                   |               |
| `ariaMultiLine`              | `aria-multiline`               |               |
| `ariaMultiSelectable`        | `aria-multiselectable`         |               |
| `ariaOrientation`            | `aria-orientation`             |               |
| `ariaOwns`                   | `aria-owns`                    |               |
| `ariaPlaceholder`            | `aria-placeholder`             |               |
| `ariaPosInSet`               | `aria-posinset`                |               |
| `ariaPressed`                | `aria-pressed`                 |               |
| `ariaReadOnly`               | `aria-readonly`                |               |
| `ariaRelevant`               | `aria-relevant`                |               |
| `ariaRequired`               | `aria-required`                |               |
| `ariaRoleDescription`        | `aria-roledescription`         |               |
| `ariaRowCount`               | `aria-rowcount`                |               |
| `ariaRowIndex`               | `aria-rowindex`                |               |
| `ariaRowSpan`                | `aria-rowspan`                 |               |
| `ariaSelected`               | `aria-selected`                |               |
| `ariaSetSize`                | `aria-setsize`                 |               |
| `ariaSort`                   | `aria-sort`                    |               |
| `ariaValueMax`               | `aria-valuemax`                |               |
| `ariaValueMin`               | `aria-valuemin`                |               |
| `ariaValueNow`               | `aria-valuenow`                |               |
| `ariaValueText`              | `aria-valuetext`               |               |
| `as`                         | `as`                           | `html`        |
| `ascent`                     | `ascent`                       | `svg`         |
| `async`                      | `async`                        | `html`        |
| `attributeName`              | `attributeName`                | `svg`         |
| `attributeType`              | `attributeType`                | `svg`         |
| `autoCapitalize`             | `autocapitalize`               | `html`        |
| `autoComplete`               | `autocomplete`                 | `html`        |
| `autoCorrect`                | `autocorrect`                  | `html`        |
| `autoFocus`                  | `autofocus`                    | `html`        |
| `autoPlay`                   | `autoplay`                     | `html`        |
| `autoSave`                   | `autosave`                     | `html`        |
| `axis`                       | `axis`                         | `html`        |
| `azimuth`                    | `azimuth`                      | `svg`         |
| `background`                 | `background`                   | `html`        |
| `bandwidth`                  | `bandwidth`                    | `svg`         |
| `baseFrequency`              | `baseFrequency`                | `svg`         |
| `baseProfile`                | `baseProfile`                  | `svg`         |
| `baselineShift`              | `baseline-shift`               | `svg`         |
| `bbox`                       | `bbox`                         | `svg`         |
| `begin`                      | `begin`                        | `svg`         |
| `bgColor`                    | `bgcolor`                      | `html`        |
| `bias`                       | `bias`                         | `svg`         |
| `blocking`                   | `blocking`                     | `html`        |
| `border`                     | `border`                       | `html`        |
| `borderColor`                | `bordercolor`                  | `html`        |
| `bottomMargin`               | `bottommargin`                 | `html`        |
| `by`                         | `by`                           | `svg`         |
| `calcMode`                   | `calcMode`                     | `svg`         |
| `capHeight`                  | `cap-height`                   | `svg`         |
| `capture`                    | `capture`                      | `html`        |
| `cellPadding`                | `cellpadding`                  | `html`        |
| `cellSpacing`                | `cellspacing`                  | `html`        |
| `char`                       | `char`                         | `html`        |
| `charOff`                    | `charoff`                      | `html`        |
| `charSet`                    | `charset`                      | `html`        |
| `checked`                    | `checked`                      | `html`        |
| `cite`                       | `cite`                         | `html`        |
| `classId`                    | `classid`                      | `html`        |
| `className`                  | `class`                        | `svg`, `html` |
| `clear`                      | `clear`                        | `html`        |
| `clip`                       | `clip`                         | `svg`         |
| `clipPath`                   | `clip-path`                    | `svg`         |
| `clipPathUnits`              | `clipPathUnits`                | `svg`         |
| `clipRule`                   | `clip-rule`                    | `svg`         |
| `code`                       | `code`                         | `html`        |
| `codeBase`                   | `codebase`                     | `html`        |
| `codeType`                   | `codetype`                     | `html`        |
| `colSpan`                    | `colspan`                      | `html`        |
| `color`                      | `color`                        | `svg`, `html` |
| `colorInterpolation`         | `color-interpolation`          | `svg`         |
| `colorInterpolationFilters`  | `color-interpolation-filters`  | `svg`         |
| `colorProfile`               | `color-profile`                | `svg`         |
| `colorRendering`             | `color-rendering`              | `svg`         |
| `cols`                       | `cols`                         | `html`        |
| `compact`                    | `compact`                      | `html`        |
| `content`                    | `content`                      | `svg`, `html` |
| `contentEditable`            | `contenteditable`              | `html`        |
| `contentScriptType`          | `contentScriptType`            | `svg`         |
| `contentStyleType`           | `contentStyleType`             | `svg`         |
| `controls`                   | `controls`                     | `html`        |
| `controlsList`               | `controlslist`                 | `html`        |
| `coords`                     | `coords`                       | `html`        |
| `crossOrigin`                | `crossorigin`                  | `svg`, `html` |
| `cursor`                     | `cursor`                       | `svg`         |
| `cx`                         | `cx`                           | `svg`         |
| `cy`                         | `cy`                           | `svg`         |
| `d`                          | `d`                            | `svg`         |
| `data`                       | `data`                         | `html`        |
| `dataType`                   | `datatype`                     | `svg`         |
| `dateTime`                   | `datetime`                     | `html`        |
| `declare`                    | `declare`                      | `html`        |
| `decoding`                   | `decoding`                     | `html`        |
| `default`                    | `default`                      | `html`        |
| `defaultAction`              | `defaultAction`                | `svg`         |
| `defer`                      | `defer`                        | `html`        |
| `descent`                    | `descent`                      | `svg`         |
| `diffuseConstant`            | `diffuseConstant`              | `svg`         |
| `dir`                        | `dir`                          | `html`        |
| `dirName`                    | `dirname`                      | `html`        |
| `direction`                  | `direction`                    | `svg`         |
| `disablePictureInPicture`    | `disablepictureinpicture`      | `html`        |
| `disableRemotePlayback`      | `disableremoteplayback`        | `html`        |
| `disabled`                   | `disabled`                     | `html`        |
| `display`                    | `display`                      | `svg`         |
| `divisor`                    | `divisor`                      | `svg`         |
| `dominantBaseline`           | `dominant-baseline`            | `svg`         |
| `download`                   | `download`                     | `svg`, `html` |
| `draggable`                  | `draggable`                    | `html`        |
| `dur`                        | `dur`                          | `svg`         |
| `dx`                         | `dx`                           | `svg`         |
| `dy`                         | `dy`                           | `svg`         |
| `edgeMode`                   | `edgeMode`                     | `svg`         |
| `editable`                   | `editable`                     | `svg`         |
| `elevation`                  | `elevation`                    | `svg`         |
| `enableBackground`           | `enable-background`            | `svg`         |
| `encType`                    | `enctype`                      | `html`        |
| `end`                        | `end`                          | `svg`         |
| `enterKeyHint`               | `enterkeyhint`                 | `html`        |
| `event`                      | `event`                        | `svg`, `html` |
| `exponent`                   | `exponent`                     | `svg`         |
| `externalResourcesRequired`  | `externalResourcesRequired`    | `svg`         |
| `face`                       | `face`                         | `html`        |
| `fetchPriority`              | `fetchpriority`                | `html`        |
| `fill`                       | `fill`                         | `svg`         |
| `fillOpacity`                | `fill-opacity`                 | `svg`         |
| `fillRule`                   | `fill-rule`                    | `svg`         |
| `filter`                     | `filter`                       | `svg`         |
| `filterRes`                  | `filterRes`                    | `svg`         |
| `filterUnits`                | `filterUnits`                  | `svg`         |
| `floodColor`                 | `flood-color`                  | `svg`         |
| `floodOpacity`               | `flood-opacity`                | `svg`         |
| `focusHighlight`             | `focusHighlight`               | `svg`         |
| `focusable`                  | `focusable`                    | `svg`         |
| `fontFamily`                 | `font-family`                  | `svg`         |
| `fontSize`                   | `font-size`                    | `svg`         |
| `fontSizeAdjust`             | `font-size-adjust`             | `svg`         |
| `fontStretch`                | `font-stretch`                 | `svg`         |
| `fontStyle`                  | `font-style`                   | `svg`         |
| `fontVariant`                | `font-variant`                 | `svg`         |
| `fontWeight`                 | `font-weight`                  | `svg`         |
| `form`                       | `form`                         | `html`        |
| `formAction`                 | `formaction`                   | `html`        |
| `formEncType`                | `formenctype`                  | `html`        |
| `formMethod`                 | `formmethod`                   | `html`        |
| `formNoValidate`             | `formnovalidate`               | `html`        |
| `formTarget`                 | `formtarget`                   | `html`        |
| `format`                     | `format`                       | `svg`         |
| `fr`                         | `fr`                           | `svg`         |
| `frame`                      | `frame`                        | `html`        |
| `frameBorder`                | `frameborder`                  | `html`        |
| `from`                       | `from`                         | `svg`         |
| `fx`                         | `fx`                           | `svg`         |
| `fy`                         | `fy`                           | `svg`         |
| `g1`                         | `g1`                           | `svg`         |
| `g2`                         | `g2`                           | `svg`         |
| `glyphName`                  | `glyph-name`                   | `svg`         |
| `glyphOrientationHorizontal` | `glyph-orientation-horizontal` | `svg`         |
| `glyphOrientationVertical`   | `glyph-orientation-vertical`   | `svg`         |
| `glyphRef`                   | `glyphRef`                     | `svg`         |
| `gradientTransform`          | `gradientTransform`            | `svg`         |
| `gradientUnits`              | `gradientUnits`                | `svg`         |
| `hSpace`                     | `hspace`                       | `html`        |
| `handler`                    | `handler`                      | `svg`         |
| `hanging`                    | `hanging`                      | `svg`         |
| `hatchContentUnits`          | `hatchContentUnits`            | `svg`         |
| `hatchUnits`                 | `hatchUnits`                   | `svg`         |
| `headers`                    | `headers`                      | `html`        |
| `height`                     | `height`                       | `svg`, `html` |
| `hidden`                     | `hidden`                       | `html`        |
| `high`                       | `high`                         | `html`        |
| `horizAdvX`                  | `horiz-adv-x`                  | `svg`         |
| `horizOriginX`               | `horiz-origin-x`               | `svg`         |
| `horizOriginY`               | `horiz-origin-y`               | `svg`         |
| `href`                       | `href`                         | `svg`, `html` |
| `hrefLang`                   | `hreflang`                     | `svg`, `html` |
| `htmlFor`                    | `for`                          | `html`        |
| `httpEquiv`                  | `http-equiv`                   | `html`        |
| `id`                         | `id`                           | `svg`, `html` |
| `ideographic`                | `ideographic`                  | `svg`         |
| `imageRendering`             | `image-rendering`              | `svg`         |
| `imageSizes`                 | `imagesizes`                   | `html`        |
| `imageSrcSet`                | `imagesrcset`                  | `html`        |
| `in`                         | `in`                           | `svg`         |
| `in2`                        | `in2`                          | `svg`         |
| `inert`                      | `inert`                        | `html`        |
| `initialVisibility`          | `initialVisibility`            | `svg`         |
| `inputMode`                  | `inputmode`                    | `html`        |
| `integrity`                  | `integrity`                    | `html`        |
| `intercept`                  | `intercept`                    | `svg`         |
| `is`                         | `is`                           | `html`        |
| `isMap`                      | `ismap`                        | `html`        |
| `itemId`                     | `itemid`                       | `html`        |
| `itemProp`                   | `itemprop`                     | `html`        |
| `itemRef`                    | `itemref`                      | `html`        |
| `itemScope`                  | `itemscope`                    | `html`        |
| `itemType`                   | `itemtype`                     | `html`        |
| `k`                          | `k`                            | `svg`         |
| `k1`                         | `k1`                           | `svg`         |
| `k2`                         | `k2`                           | `svg`         |
| `k3`                         | `k3`                           | `svg`         |
| `k4`                         | `k4`                           | `svg`         |
| `kernelMatrix`               | `kernelMatrix`                 | `svg`         |
| `kernelUnitLength`           | `kernelUnitLength`             | `svg`         |
| `kerning`                    | `kerning`                      | `svg`         |
| `keyPoints`                  | `keyPoints`                    | `svg`         |
| `keySplines`                 | `keySplines`                   | `svg`         |
| `keyTimes`                   | `keyTimes`                     | `svg`         |
| `kind`                       | `kind`                         | `html`        |
| `label`                      | `label`                        | `html`        |
| `lang`                       | `lang`                         | `svg`, `html` |
| `language`                   | `language`                     | `html`        |
| `leftMargin`                 | `leftmargin`                   | `html`        |
| `lengthAdjust`               | `lengthAdjust`                 | `svg`         |
| `letterSpacing`              | `letter-spacing`               | `svg`         |
| `lightingColor`              | `lighting-color`               | `svg`         |
| `limitingConeAngle`          | `limitingConeAngle`            | `svg`         |
| `link`                       | `link`                         | `html`        |
| `list`                       | `list`                         | `html`        |
| `loading`                    | `loading`                      | `html`        |
| `local`                      | `local`                        | `svg`         |
| `longDesc`                   | `longdesc`                     | `html`        |
| `loop`                       | `loop`                         | `html`        |
| `low`                        | `low`                          | `html`        |
| `lowSrc`                     | `lowsrc`                       | `html`        |
| `manifest`                   | `manifest`                     | `html`        |
| `marginHeight`               | `marginheight`                 | `html`        |
| `marginWidth`                | `marginwidth`                  | `html`        |
| `markerEnd`                  | `marker-end`                   | `svg`         |
| `markerHeight`               | `markerHeight`                 | `svg`         |
| `markerMid`                  | `marker-mid`                   | `svg`         |
| `markerStart`                | `marker-start`                 | `svg`         |
| `markerUnits`                | `markerUnits`                  | `svg`         |
| `markerWidth`                | `markerWidth`                  | `svg`         |
| `mask`                       | `mask`                         | `svg`         |
| `maskContentUnits`           | `maskContentUnits`             | `svg`         |
| `maskUnits`                  | `maskUnits`                    | `svg`         |
| `mathematical`               | `mathematical`                 | `svg`         |
| `max`                        | `max`                          | `svg`, `html` |
| `maxLength`                  | `maxlength`                    | `html`        |
| `media`                      | `media`                        | `svg`, `html` |
| `mediaCharacterEncoding`     | `mediaCharacterEncoding`       | `svg`         |
| `mediaContentEncodings`      | `mediaContentEncodings`        | `svg`         |
| `mediaSize`                  | `mediaSize`                    | `svg`         |
| `mediaTime`                  | `mediaTime`                    | `svg`         |
| `method`                     | `method`                       | `svg`, `html` |
| `min`                        | `min`                          | `svg`, `html` |
| `minLength`                  | `minlength`                    | `html`        |
| `mode`                       | `mode`                         | `svg`         |
| `multiple`                   | `multiple`                     | `html`        |
| `muted`                      | `muted`                        | `html`        |
| `name`                       | `name`                         | `svg`, `html` |
| `navDown`                    | `nav-down`                     | `svg`         |
| `navDownLeft`                | `nav-down-left`                | `svg`         |
| `navDownRight`               | `nav-down-right`               | `svg`         |
| `navLeft`                    | `nav-left`                     | `svg`         |
| `navNext`                    | `nav-next`                     | `svg`         |
| `navPrev`                    | `nav-prev`                     | `svg`         |
| `navRight`                   | `nav-right`                    | `svg`         |
| `navUp`                      | `nav-up`                       | `svg`         |
| `navUpLeft`                  | `nav-up-left`                  | `svg`         |
| `navUpRight`                 | `nav-up-right`                 | `svg`         |
| `noHref`                     | `nohref`                       | `html`        |
| `noModule`                   | `nomodule`                     | `html`        |
| `noResize`                   | `noresize`                     | `html`        |
| `noShade`                    | `noshade`                      | `html`        |
| `noValidate`                 | `novalidate`                   | `html`        |
| `noWrap`                     | `nowrap`                       | `html`        |
| `nonce`                      | `nonce`                        | `html`        |
| `numOctaves`                 | `numOctaves`                   | `svg`         |
| `object`                     | `object`                       | `html`        |
| `observer`                   | `observer`                     | `svg`         |
| `offset`                     | `offset`                       | `svg`         |
| `onAbort`                    | `onabort`                      | `svg`, `html` |
| `onActivate`                 | `onactivate`                   | `svg`         |
| `onAfterPrint`               | `onafterprint`                 | `svg`, `html` |
| `onAuxClick`                 | `onauxclick`                   | `html`        |
| `onBeforeMatch`              | `onbeforematch`                | `html`        |
| `onBeforePrint`              | `onbeforeprint`                | `svg`, `html` |
| `onBeforeToggle`             | `onbeforetoggle`               | `html`        |
| `onBeforeUnload`             | `onbeforeunload`               | `html`        |
| `onBegin`                    | `onbegin`                      | `svg`         |
| `onBlur`                     | `onblur`                       | `html`        |
| `onCanPlay`                  | `oncanplay`                    | `svg`, `html` |
| `onCanPlayThrough`           | `oncanplaythrough`             | `svg`, `html` |
| `onCancel`                   | `oncancel`                     | `svg`, `html` |
| `onChange`                   | `onchange`                     | `svg`, `html` |
| `onClick`                    | `onclick`                      | `svg`, `html` |
| `onClose`                    | `onclose`                      | `svg`, `html` |
| `onContextLost`              | `oncontextlost`                | `html`        |
| `onContextMenu`              | `oncontextmenu`                | `html`        |
| `onContextRestored`          | `oncontextrestored`            | `html`        |
| `onCopy`                     | `oncopy`                       | `svg`, `html` |
| `onCueChange`                | `oncuechange`                  | `svg`, `html` |
| `onCut`                      | `oncut`                        | `svg`, `html` |
| `onDblClick`                 | `ondblclick`                   | `svg`, `html` |
| `onDrag`                     | `ondrag`                       | `svg`, `html` |
| `onDragEnd`                  | `ondragend`                    | `svg`, `html` |
| `onDragEnter`                | `ondragenter`                  | `svg`, `html` |
| `onDragExit`                 | `ondragexit`                   | `svg`, `html` |
| `onDragLeave`                | `ondragleave`                  | `svg`, `html` |
| `onDragOver`                 | `ondragover`                   | `svg`, `html` |
| `onDragStart`                | `ondragstart`                  | `svg`, `html` |
| `onDrop`                     | `ondrop`                       | `svg`, `html` |
| `onDurationChange`           | `ondurationchange`             | `svg`, `html` |
| `onEmptied`                  | `onemptied`                    | `svg`, `html` |
| `onEnd`                      | `onend`                        | `svg`         |
| `onEnded`                    | `onended`                      | `svg`, `html` |
| `onError`                    | `onerror`                      | `svg`, `html` |
| `onFocus`                    | `onfocus`                      | `svg`, `html` |
| `onFocusIn`                  | `onfocusin`                    | `svg`         |
| `onFocusOut`                 | `onfocusout`                   | `svg`         |
| `onFormData`                 | `onformdata`                   | `html`        |
| `onHashChange`               | `onhashchange`                 | `svg`, `html` |
| `onInput`                    | `oninput`                      | `svg`, `html` |
| `onInvalid`                  | `oninvalid`                    | `svg`, `html` |
| `onKeyDown`                  | `onkeydown`                    | `svg`, `html` |
| `onKeyPress`                 | `onkeypress`                   | `svg`, `html` |
| `onKeyUp`                    | `onkeyup`                      | `svg`, `html` |
| `onLanguageChange`           | `onlanguagechange`             | `html`        |
| `onLoad`                     | `onload`                       | `svg`, `html` |
| `onLoadEnd`                  | `onloadend`                    | `html`        |
| `onLoadStart`                | `onloadstart`                  | `svg`, `html` |
| `onLoadedData`               | `onloadeddata`                 | `svg`, `html` |
| `onLoadedMetadata`           | `onloadedmetadata`             | `svg`, `html` |
| `onMessage`                  | `onmessage`                    | `svg`, `html` |
| `onMessageError`             | `onmessageerror`               | `html`        |
| `onMouseDown`                | `onmousedown`                  | `svg`, `html` |
| `onMouseEnter`               | `onmouseenter`                 | `svg`, `html` |
| `onMouseLeave`               | `onmouseleave`                 | `svg`, `html` |
| `onMouseMove`                | `onmousemove`                  | `svg`, `html` |
| `onMouseOut`                 | `onmouseout`                   | `svg`, `html` |
| `onMouseOver`                | `onmouseover`                  | `svg`, `html` |
| `onMouseUp`                  | `onmouseup`                    | `svg`, `html` |
| `onMouseWheel`               | `onmousewheel`                 | `svg`         |
| `onOffline`                  | `onoffline`                    | `svg`, `html` |
| `onOnline`                   | `ononline`                     | `svg`, `html` |
| `onPageHide`                 | `onpagehide`                   | `svg`, `html` |
| `onPageShow`                 | `onpageshow`                   | `svg`, `html` |
| `onPaste`                    | `onpaste`                      | `svg`, `html` |
| `onPause`                    | `onpause`                      | `svg`, `html` |
| `onPlay`                     | `onplay`                       | `svg`, `html` |
| `onPlaying`                  | `onplaying`                    | `svg`, `html` |
| `onPopState`                 | `onpopstate`                   | `svg`, `html` |
| `onProgress`                 | `onprogress`                   | `svg`, `html` |
| `onRateChange`               | `onratechange`                 | `svg`, `html` |
| `onRejectionHandled`         | `onrejectionhandled`           | `html`        |
| `onRepeat`                   | `onrepeat`                     | `svg`         |
| `onReset`                    | `onreset`                      | `svg`, `html` |
| `onResize`                   | `onresize`                     | `svg`, `html` |
| `onScroll`                   | `onscroll`                     | `svg`, `html` |
| `onScrollEnd`                | `onscrollend`                  | `html`        |
| `onSecurityPolicyViolation`  | `onsecuritypolicyviolation`    | `html`        |
| `onSeeked`                   | `onseeked`                     | `svg`, `html` |
| `onSeeking`                  | `onseeking`                    | `svg`, `html` |
| `onSelect`                   | `onselect`                     | `svg`, `html` |
| `onShow`                     | `onshow`                       | `svg`         |
| `onSlotChange`               | `onslotchange`                 | `html`        |
| `onStalled`                  | `onstalled`                    | `svg`, `html` |
| `onStorage`                  | `onstorage`                    | `svg`, `html` |
| `onSubmit`                   | `onsubmit`                     | `svg`, `html` |
| `onSuspend`                  | `onsuspend`                    | `svg`, `html` |
| `onTimeUpdate`               | `ontimeupdate`                 | `svg`, `html` |
| `onToggle`                   | `ontoggle`                     | `svg`, `html` |
| `onUnhandledRejection`       | `onunhandledrejection`         | `html`        |
| `onUnload`                   | `onunload`                     | `svg`, `html` |
| `onVolumeChange`             | `onvolumechange`               | `svg`, `html` |
| `onWaiting`                  | `onwaiting`                    | `svg`, `html` |
| `onWheel`                    | `onwheel`                      | `html`        |
| `onZoom`                     | `onzoom`                       | `svg`         |
| `opacity`                    | `opacity`                      | `svg`         |
| `open`                       | `open`                         | `html`        |
| `operator`                   | `operator`                     | `svg`         |
| `optimum`                    | `optimum`                      | `html`        |
| `order`                      | `order`                        | `svg`         |
| `orient`                     | `orient`                       | `svg`         |
| `orientation`                | `orientation`                  | `svg`         |
| `origin`                     | `origin`                       | `svg`         |
| `overflow`                   | `overflow`                     | `svg`         |
| `overlay`                    | `overlay`                      | `svg`         |
| `overlinePosition`           | `overline-position`            | `svg`         |
| `overlineThickness`          | `overline-thickness`           | `svg`         |
| `paintOrder`                 | `paint-order`                  | `svg`         |
| `panose1`                    | `panose-1`                     | `svg`         |
| `path`                       | `path`                         | `svg`         |
| `pathLength`                 | `pathLength`                   | `svg`         |
| `pattern`                    | `pattern`                      | `html`        |
| `patternContentUnits`        | `patternContentUnits`          | `svg`         |
| `patternTransform`           | `patternTransform`             | `svg`         |
| `patternUnits`               | `patternUnits`                 | `svg`         |
| `phase`                      | `phase`                        | `svg`         |
| `ping`                       | `ping`                         | `svg`, `html` |
| `pitch`                      | `pitch`                        | `svg`         |
| `placeholder`                | `placeholder`                  | `html`        |
| `playbackOrder`              | `playbackorder`                | `svg`         |
| `playsInline`                | `playsinline`                  | `html`        |
| `pointerEvents`              | `pointer-events`               | `svg`         |
| `points`                     | `points`                       | `svg`         |
| `pointsAtX`                  | `pointsAtX`                    | `svg`         |
| `pointsAtY`                  | `pointsAtY`                    | `svg`         |
| `pointsAtZ`                  | `pointsAtZ`                    | `svg`         |
| `popover`                    | `popover`                      | `html`        |
| `popoverTarget`              | `popovertarget`                | `html`        |
| `popoverTargetAction`        | `popovertargetaction`          | `html`        |
| `poster`                     | `poster`                       | `html`        |
| `prefix`                     | `prefix`                       | `html`        |
| `preload`                    | `preload`                      | `html`        |
| `preserveAlpha`              | `preserveAlpha`                | `svg`         |
| `preserveAspectRatio`        | `preserveAspectRatio`          | `svg`         |
| `primitiveUnits`             | `primitiveUnits`               | `svg`         |
| `profile`                    | `profile`                      | `html`        |
| `prompt`                     | `prompt`                       | `html`        |
| `propagate`                  | `propagate`                    | `svg`         |
| `property`                   | `property`                     | `svg`, `html` |
| `r`                          | `r`                            | `svg`         |
| `radius`                     | `radius`                       | `svg`         |
| `readOnly`                   | `readonly`                     | `html`        |
| `refX`                       | `refX`                         | `svg`         |
| `refY`                       | `refY`                         | `svg`         |
| `referrerPolicy`             | `referrerpolicy`               | `svg`, `html` |
| `rel`                        | `rel`                          | `svg`, `html` |
| `renderingIntent`            | `rendering-intent`             | `svg`         |
| `repeatCount`                | `repeatCount`                  | `svg`         |
| `repeatDur`                  | `repeatDur`                    | `svg`         |
| `required`                   | `required`                     | `html`        |
| `requiredExtensions`         | `requiredExtensions`           | `svg`         |
| `requiredFeatures`           | `requiredFeatures`             | `svg`         |
| `requiredFonts`              | `requiredFonts`                | `svg`         |
| `requiredFormats`            | `requiredFormats`              | `svg`         |
| `resource`                   | `resource`                     | `svg`         |
| `restart`                    | `restart`                      | `svg`         |
| `result`                     | `result`                       | `svg`         |
| `results`                    | `results`                      | `html`        |
| `rev`                        | `rev`                          | `svg`, `html` |
| `reversed`                   | `reversed`                     | `html`        |
| `rightMargin`                | `rightmargin`                  | `html`        |
| `role`                       | `role`                         |               |
| `rotate`                     | `rotate`                       | `svg`         |
| `rowSpan`                    | `rowspan`                      | `html`        |
| `rows`                       | `rows`                         | `html`        |
| `rules`                      | `rules`                        | `html`        |
| `rx`                         | `rx`                           | `svg`         |
| `ry`                         | `ry`                           | `svg`         |
| `sandbox`                    | `sandbox`                      | `html`        |
| `scale`                      | `scale`                        | `svg`         |
| `scheme`                     | `scheme`                       | `html`        |
| `scope`                      | `scope`                        | `html`        |
| `scoped`                     | `scoped`                       | `html`        |
| `scrolling`                  | `scrolling`                    | `html`        |
| `seamless`                   | `seamless`                     | `html`        |
| `security`                   | `security`                     | `html`        |
| `seed`                       | `seed`                         | `svg`         |
| `selected`                   | `selected`                     | `html`        |
| `shadowRootClonable`         | `shadowrootclonable`           | `html`        |
| `shadowRootDelegatesFocus`   | `shadowrootdelegatesfocus`     | `html`        |
| `shadowRootMode`             | `shadowrootmode`               | `html`        |
| `shape`                      | `shape`                        | `html`        |
| `shapeRendering`             | `shape-rendering`              | `svg`         |
| `side`                       | `side`                         | `svg`         |
| `size`                       | `size`                         | `html`        |
| `sizes`                      | `sizes`                        | `html`        |
| `slope`                      | `slope`                        | `svg`         |
| `slot`                       | `slot`                         | `html`        |
| `snapshotTime`               | `snapshotTime`                 | `svg`         |
| `spacing`                    | `spacing`                      | `svg`         |
| `span`                       | `span`                         | `html`        |
| `specularConstant`           | `specularConstant`             | `svg`         |
| `specularExponent`           | `specularExponent`             | `svg`         |
| `spellCheck`                 | `spellcheck`                   | `html`        |
| `spreadMethod`               | `spreadMethod`                 | `svg`         |
| `src`                        | `src`                          | `html`        |
| `srcDoc`                     | `srcdoc`                       | `html`        |
| `srcLang`                    | `srclang`                      | `html`        |
| `srcSet`                     | `srcset`                       | `html`        |
| `standby`                    | `standby`                      | `html`        |
| `start`                      | `start`                        | `html`        |
| `startOffset`                | `startOffset`                  | `svg`         |
| `stdDeviation`               | `stdDeviation`                 | `svg`         |
| `stemh`                      | `stemh`                        | `svg`         |
| `stemv`                      | `stemv`                        | `svg`         |
| `step`                       | `step`                         | `html`        |
| `stitchTiles`                | `stitchTiles`                  | `svg`         |
| `stopColor`                  | `stop-color`                   | `svg`         |
| `stopOpacity`                | `stop-opacity`                 | `svg`         |
| `strikethroughPosition`      | `strikethrough-position`       | `svg`         |
| `strikethroughThickness`     | `strikethrough-thickness`      | `svg`         |
| `string`                     | `string`                       | `svg`         |
| `stroke`                     | `stroke`                       | `svg`         |
| `strokeDashArray`            | `stroke-dasharray`             | `svg`         |
| `strokeDashOffset`           | `stroke-dashoffset`            | `svg`         |
| `strokeLineCap`              | `stroke-linecap`               | `svg`         |
| `strokeLineJoin`             | `stroke-linejoin`              | `svg`         |
| `strokeMiterLimit`           | `stroke-miterlimit`            | `svg`         |
| `strokeOpacity`              | `stroke-opacity`               | `svg`         |
| `strokeWidth`                | `stroke-width`                 | `svg`         |
| `style`                      | `style`                        | `svg`, `html` |
| `summary`                    | `summary`                      | `html`        |
| `surfaceScale`               | `surfaceScale`                 | `svg`         |
| `syncBehavior`               | `syncBehavior`                 | `svg`         |
| `syncBehaviorDefault`        | `syncBehaviorDefault`          | `svg`         |
| `syncMaster`                 | `syncMaster`                   | `svg`         |
| `syncTolerance`              | `syncTolerance`                | `svg`         |
| `syncToleranceDefault`       | `syncToleranceDefault`         | `svg`         |
| `systemLanguage`             | `systemLanguage`               | `svg`         |
| `tabIndex`                   | `tabindex`                     | `svg`, `html` |
| `tableValues`                | `tableValues`                  | `svg`         |
| `target`                     | `target`                       | `svg`, `html` |
| `targetX`                    | `targetX`                      | `svg`         |
| `targetY`                    | `targetY`                      | `svg`         |
| `text`                       | `text`                         | `html`        |
| `textAnchor`                 | `text-anchor`                  | `svg`         |
| `textDecoration`             | `text-decoration`              | `svg`         |
| `textLength`                 | `textLength`                   | `svg`         |
| `textRendering`              | `text-rendering`               | `svg`         |
| `timelineBegin`              | `timelinebegin`                | `svg`         |
| `title`                      | `title`                        | `svg`, `html` |
| `to`                         | `to`                           | `svg`         |
| `topMargin`                  | `topmargin`                    | `html`        |
| `transform`                  | `transform`                    | `svg`         |
| `transformBehavior`          | `transformBehavior`            | `svg`         |
| `transformOrigin`            | `transform-origin`             | `svg`         |
| `translate`                  | `translate`                    | `html`        |
| `type`                       | `type`                         | `svg`, `html` |
| `typeMustMatch`              | `typemustmatch`                | `html`        |
| `typeOf`                     | `typeof`                       | `svg`         |
| `u1`                         | `u1`                           | `svg`         |
| `u2`                         | `u2`                           | `svg`         |
| `underlinePosition`          | `underline-position`           | `svg`         |
| `underlineThickness`         | `underline-thickness`          | `svg`         |
| `unicode`                    | `unicode`                      | `svg`         |
| `unicodeBidi`                | `unicode-bidi`                 | `svg`         |
| `unicodeRange`               | `unicode-range`                | `svg`         |
| `unitsPerEm`                 | `units-per-em`                 | `svg`         |
| `unselectable`               | `unselectable`                 | `html`        |
| `useMap`                     | `usemap`                       | `html`        |
| `vAlign`                     | `valign`                       | `html`        |
| `vAlphabetic`                | `v-alphabetic`                 | `svg`         |
| `vHanging`                   | `v-hanging`                    | `svg`         |
| `vIdeographic`               | `v-ideographic`                | `svg`         |
| `vLink`                      | `vlink`                        | `html`        |
| `vMathematical`              | `v-mathematical`               | `svg`         |
| `vSpace`                     | `vspace`                       | `html`        |
| `value`                      | `value`                        | `html`        |
| `valueType`                  | `valuetype`                    | `html`        |
| `values`                     | `values`                       | `svg`         |
| `vectorEffect`               | `vector-effect`                | `svg`         |
| `version`                    | `version`                      | `svg`, `html` |
| `vertAdvY`                   | `vert-adv-y`                   | `svg`         |
| `vertOriginX`                | `vert-origin-x`                | `svg`         |
| `vertOriginY`                | `vert-origin-y`                | `svg`         |
| `viewBox`                    | `viewBox`                      | `svg`         |
| `viewTarget`                 | `viewTarget`                   | `svg`         |
| `visibility`                 | `visibility`                   | `svg`         |
| `width`                      | `width`                        | `svg`, `html` |
| `widths`                     | `widths`                       | `svg`         |
| `wordSpacing`                | `word-spacing`                 | `svg`         |
| `wrap`                       | `wrap`                         | `html`        |
| `writingMode`                | `writing-mode`                 | `svg`         |
| `writingSuggestions`         | `writingsuggestions`           | `html`        |
| `x`                          | `x`                            | `svg`         |
| `x1`                         | `x1`                           | `svg`         |
| `x2`                         | `x2`                           | `svg`         |
| `xChannelSelector`           | `xChannelSelector`             | `svg`         |
| `xHeight`                    | `x-height`                     | `svg`         |
| `xLinkActuate`               | `xlink:actuate`                | `xlink`       |
| `xLinkArcRole`               | `xlink:arcrole`                | `xlink`       |
| `xLinkHref`                  | `xlink:href`                   | `xlink`       |
| `xLinkRole`                  | `xlink:role`                   | `xlink`       |
| `xLinkShow`                  | `xlink:show`                   | `xlink`       |
| `xLinkTitle`                 | `xlink:title`                  | `xlink`       |
| `xLinkType`                  | `xlink:type`                   | `xlink`       |
| `xmlBase`                    | `xml:base`                     | `xml`         |
| `xmlLang`                    | `xml:lang`                     | `xml`         |
| `xmlSpace`                   | `xml:space`                    | `xml`         |
| `xmlns`                      | `xmlns`                        | `xmlns`       |
| `xmlnsXLink`                 | `xmlns:xlink`                  | `xmlns`       |
| `y`                          | `y`                            | `svg`         |
| `y1`                         | `y1`                           | `svg`         |
| `y2`                         | `y2`                           | `svg`         |
| `yChannelSelector`           | `yChannelSelector`             | `svg`         |
| `z`                          | `z`                            | `svg`         |
| `zoomAndPan`                 | `zoomAndPan`                   | `svg`         |

<!--list end-->

## Security

This package is safe.

## Related

*   [`wooorm/web-namespaces`][namespace]
    — list of web namespaces
*   [`wooorm/space-separated-tokens`](https://github.com/wooorm/space-separated-tokens)
    — parse/stringify space separated tokens
*   [`wooorm/comma-separated-tokens`](https://github.com/wooorm/comma-separated-tokens)
    — parse/stringify comma separated tokens
*   [`wooorm/html-tag-names`](https://github.com/wooorm/html-tag-names)
    — list of HTML tag names
*   [`wooorm/mathml-tag-names`](https://github.com/wooorm/mathml-tag-names)
    — list of MathML tag names
*   [`wooorm/svg-tag-names`](https://github.com/wooorm/svg-tag-names)
    — list of SVG tag names
*   [`wooorm/html-void-elements`](https://github.com/wooorm/html-void-elements)
    — list of void HTML tag names
*   [`wooorm/svg-element-attributes`](https://github.com/wooorm/svg-element-attributes)
    — map of SVG elements to allowed attributes
*   [`wooorm/html-element-attributes`](https://github.com/wooorm/html-element-attributes)
    — map of HTML elements to allowed attributes
*   [`wooorm/aria-attributes`](https://github.com/wooorm/aria-attributes)
    — list of ARIA attributes

## Contribute

Yes please!
See [How to Contribute to Open Source][contribute].

## License

[MIT][license] © [Titus Wormer][author]

Derivative work based on [React][source] licensed under
[MIT][source-license], © Facebook, Inc.

[build-badge]: https://github.com/wooorm/property-information/workflows/main/badge.svg

[build]: https://github.com/wooorm/property-information/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/property-information.svg

[coverage]: https://codecov.io/github/wooorm/property-information

[downloads-badge]: https://img.shields.io/npm/dm/property-information.svg

[downloads]: https://www.npmjs.com/package/property-information

[size-badge]: https://img.shields.io/bundlephobia/minzip/property-information.svg

[size]: https://bundlephobia.com/result?p=property-information

[npm]: https://docs.npmjs.com/cli/install

[esmsh]: https://esm.sh

[author]: https://wooorm.com

[license]: license

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[typescript]: https://www.typescriptlang.org

[contribute]: https://opensource.guide/how-to-contribute/

[source]: https://github.com/facebook/react/blob/8ec2ed4089/packages/react-dom/src/shared/DOMProperty.js

[source-license]: https://github.com/facebook/react/blob/8ec2ed4089/LICENSE

[data]: https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dataset

[namespace]: https://github.com/wooorm/web-namespaces

[info]: #info

[schema]: #schema

[normalize]: #normalizename

[react]: https://github.com/facebook/react

[hast]: https://github.com/syntax-tree/hast#propertyname


---

# hast-util-to-parse5

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[hast][] utility to transform to a [`parse5`][parse5] [AST][parse5-node].

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`toParse5(tree[, options])`](#toparse5tree-options)
    *   [`Options`](#options)
    *   [`Space`](#space)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Security](#security)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package is a utility that can turn a hast syntax tree into a `parse5` AST.
Why not use a Parse5 adapter, you might ask?
Well, because it’s more code weight to use adapters, and more fragile.

## When should I use this?

This package is useful when working with `parse5`, and for some reason want to
generate its AST again.
The inverse utility, [`hast-util-from-parse5`][hast-util-from-parse5], is more
likely what you want.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install hast-util-to-parse5
```

In Deno with [`esm.sh`][esmsh]:

```js
import {toParse5} from 'https://esm.sh/hast-util-to-parse5@8'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {toParse5} from 'https://esm.sh/hast-util-to-parse5@8?bundle'
</script>
```

## Use

```js
import {toParse5} from 'hast-util-to-parse5'

const tree = toParse5({
  type: 'element',
  tagName: 'h1',
  properties: {},
  children: [{type: 'text', value: 'World!'}]
})

console.log(tree)
```

Yields:

```js
{ nodeName: 'h1',
  tagName: 'h1',
  attrs: [],
  namespaceURI: 'http://www.w3.org/1999/xhtml',
  childNodes: [ { nodeName: '#text', value: 'World!', parentNode: [Circular] } ] }
```

## API

This package exports the identifier [`toParse5`][api-to-parse5].
There is no default export.

### `toParse5(tree[, options])`

Transform a hast tree to a `parse5` AST.

###### Parameters

*   `tree` ([`HastNode`][hast-node])
    — tree to transform
*   `options` ([`Options`][api-options], optional)
    — configuration

###### Returns

`parse5` node ([`Parse5Node`][parse5-node]).

### `Options`

Configuration (TypeScript type).

###### Fields

*   `space` ([`Space`][api-space], optional)
    — which space the document is in

### `Space`

Namespace (TypeScript type).

###### Type

```ts
type Space = 'html' | 'svg'
```

## Types

This package is fully typed with [TypeScript][].
It exports the additional types [`Options`][api-options] and
[`Space`][api-space].

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, `hast-util-to-parse5@^8`,
compatible with Node.js 16.

## Security

Use of `hast-util-to-parse5` can open you up to a
[cross-site scripting (XSS)][xss] attack if the hast tree is unsafe.

## Related

*   [`hast-util-from-parse5`](https://github.com/syntax-tree/hast-util-from-parse5)
    — transform from Parse5’s AST to hast
*   [`hast-util-to-nlcst`](https://github.com/syntax-tree/hast-util-to-nlcst)
    — transform hast to nlcst
*   [`hast-util-to-mdast`](https://github.com/syntax-tree/hast-util-to-mdast)
    — transform hast to mdast
*   [`hast-util-to-xast`](https://github.com/syntax-tree/hast-util-to-xast)
    — transform hast to xast
*   [`mdast-util-to-hast`](https://github.com/syntax-tree/mdast-util-to-hast)
    — transform mdast to hast
*   [`mdast-util-to-nlcst`](https://github.com/syntax-tree/mdast-util-to-nlcst)
    — transform mdast to nlcst

## Contribute

See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
ways to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/syntax-tree/hast-util-to-parse5/workflows/main/badge.svg

[build]: https://github.com/syntax-tree/hast-util-to-parse5/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/hast-util-to-parse5.svg

[coverage]: https://codecov.io/github/syntax-tree/hast-util-to-parse5

[downloads-badge]: https://img.shields.io/npm/dm/hast-util-to-parse5.svg

[downloads]: https://www.npmjs.com/package/hast-util-to-parse5

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=hast-util-to-parse5

[size]: https://bundlejs.com/?q=hast-util-to-parse5

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/syntax-tree/unist/discussions

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[typescript]: https://www.typescriptlang.org

[license]: license

[author]: https://wooorm.com

[health]: https://github.com/syntax-tree/.github

[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md

[support]: https://github.com/syntax-tree/.github/blob/main/support.md

[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md

[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting

[hast]: https://github.com/syntax-tree/hast

[hast-node]: https://github.com/syntax-tree/hast#nodes

[parse5]: https://github.com/inikulin/parse5

[parse5-node]: https://github.com/inikulin/parse5/blob/master/packages/parse5/lib/tree-adapters/default.ts

[hast-util-from-parse5]: https://github.com/syntax-tree/hast-util-from-parse5

[api-to-parse5]: #toparse5tree-options

[api-options]: #options

[api-space]: #space


---

# hast-util-whitespace

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[hast][] utility to check if a node is [*inter-element whitespace*][spec].

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`whitespace(thing)`](#whitespacething)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Security](#security)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package is a small utility that checks if a node is whitespace according to
HTML.

## When should I use this?

This utility is super niche, if you’re here you probably know what you’re
looking for!

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install hast-util-whitespace
```

In Deno with [`esm.sh`][esmsh]:

```js
import {whitespace} from 'https://esm.sh/hast-util-whitespace@3'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {whitespace} from 'https://esm.sh/hast-util-whitespace@3?bundle'
</script>
```

## Use

```js
import {whitespace} from 'hast-util-whitespace'

whitespace({
  type: 'element',
  tagName: 'div',
  properties: {},
  children: []
}) // => false

whitespace({
  type: 'text',
  value: '\t  \n'
}) // => true

whitespace({
  type: 'text',
  value: '  text\f'
}) // => false
```

## API

This package exports the identifier [`whitespace`][api-whitespace].
There is no default export.

### `whitespace(thing)`

Check if the given value is [*inter-element whitespace*][spec].

###### Parameters

*   `thing` ([`Node`][node] or `string`, optional)
    — thing to check

###### Returns

Whether the `value` is inter-element whitespace (`boolean`): consisting of zero
or more of space, tab (`\t`), line feed (`\n`), carriage return (`\r`), or form
feed (`\f`).
If a node is passed it must be a [`Text`][text] node, whose `value` field is
checked.

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, `hast-util-whitespace@^3`,
compatible with Node.js 16.

## Security

`hast-util-whitespace` does not change the syntax tree so there are no openings
for [cross-site scripting (XSS)][xss] attacks.

## Related

*   [`hast-util-is-element`](https://github.com/syntax-tree/hast-util-is-element)
    — check if a node is a (certain) element
*   [`hast-util-has-property`](https://github.com/syntax-tree/hast-util-has-property)
    — check if a node has a property
*   [`hast-util-transparent`](https://github.com/syntax-tree/hast-util-transparent)
    — check if a node is a transparent element
*   [`hast-util-heading`](https://github.com/syntax-tree/hast-util-heading)
    — check if a node is a heading element
*   [`hast-util-labelable`](https://github.com/syntax-tree/hast-util-labelable)
    — check whether a node is labelable
*   [`hast-util-phrasing`](https://github.com/syntax-tree/hast-util-phrasing)
    — check if a node is phrasing content
*   [`hast-util-embedded`](https://github.com/syntax-tree/hast-util-embedded)
    — check if a node is an embedded element
*   [`hast-util-sectioning`](https://github.com/syntax-tree/hast-util-sectioning)
    — check if a node is a sectioning element
*   [`hast-util-interactive`](https://github.com/syntax-tree/hast-util-interactive)
    — check if a node is interactive
*   [`hast-util-script-supporting`](https://github.com/syntax-tree/hast-util-script-supporting)
    — check if a node is a script-supporting element
*   [`hast-util-is-body-ok-link`](https://github.com/rehypejs/rehype-minify/tree/main/packages/hast-util-is-body-ok-link)
    — check if a node is “Body OK” link element
*   [`hast-util-is-conditional-comment`](https://github.com/rehypejs/rehype-minify/tree/main/packages/hast-util-is-conditional-comment)
    — check if a node is a conditional comment
*   [`hast-util-is-css-link`](https://github.com/rehypejs/rehype-minify/tree/main/packages/hast-util-is-css-link)
    — check if a node is a CSS link element
*   [`hast-util-is-css-style`](https://github.com/rehypejs/rehype-minify/tree/main/packages/hast-util-is-css-style)
    — check if a node is a CSS style element
*   [`hast-util-is-javascript`](https://github.com/rehypejs/rehype-minify/tree/main/packages/hast-util-is-javascript)
    — check if a node is a JavaScript script element

## Contribute

See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
ways to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definition -->

[build-badge]: https://github.com/syntax-tree/hast-util-whitespace/workflows/main/badge.svg

[build]: https://github.com/syntax-tree/hast-util-whitespace/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/hast-util-whitespace.svg

[coverage]: https://codecov.io/github/syntax-tree/hast-util-whitespace

[downloads-badge]: https://img.shields.io/npm/dm/hast-util-whitespace.svg

[downloads]: https://www.npmjs.com/package/hast-util-whitespace

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=hast-util-whitespace

[size]: https://bundlejs.com/?q=hast-util-whitespace

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/syntax-tree/unist/discussions

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[typescript]: https://www.typescriptlang.org

[license]: license

[author]: https://wooorm.com

[health]: https://github.com/syntax-tree/.github

[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md

[support]: https://github.com/syntax-tree/.github/blob/main/support.md

[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md

[hast]: https://github.com/syntax-tree/hast

[spec]: https://html.spec.whatwg.org/multipage/dom.html#inter-element-whitespace

[node]: https://github.com/syntax-tree/hast#nodes

[text]: https://github.com/syntax-tree/hast#text

[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting

[api-whitespace]: #whitespacething


---

# hastscript

[![Build][badge-build-image]][badge-build-url]
[![Coverage][badge-coverage-image]][badge-coverage-url]
[![Downloads][badge-downloads-image]][badge-downloads-url]
[![Size][badge-size-image]][badge-size-url]

[hast][github-hast] utility to create trees with ease.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`h(selector?[, properties][, …children])`](#hselector-properties-children)
  * [`s(selector?[, properties][, …children])`](#sselector-properties-children)
  * [`Child`](#child)
  * [`Properties`](#properties-1)
  * [`Result`](#result)
* [Syntax tree](#syntax-tree)
* [JSX](#jsx)
* [Compatibility](#compatibility)
* [Security](#security)
* [Related](#related)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package is a hyperscript interface (like `createElement` from React and
`h` from Vue and such) to help with creating hast trees.

## When should I use this?

You can use this utility in your project when you generate hast syntax trees
with code.
It helps because it replaces most of the repetition otherwise needed in a syntax
tree with function calls.
It also helps as it improves the attributes you pass by turning them into the
form that is required by hast.

You can instead use [`unist-builder`][github-unist-builder]
when creating any unist nodes and
[`xastscript`][github-xastscript] when creating xast (XML) nodes.

## Install

This package is [ESM only][github-gist-esm].
In Node.js (version 16+),
install with [npm][npmjs-install]:

```sh
npm install hastscript
```

In Deno with [`esm.sh`][esmsh]:

```js
import {h} from 'https://esm.sh/hastscript@9'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {h} from 'https://esm.sh/hastscript@9?bundle'
</script>
```

## Use

```js
import {h, s} from 'hastscript'

console.log(
  h('.foo#some-id', [
    h('span', 'some text'),
    h('input', {type: 'text', value: 'foo'}),
    h('a.alpha', {class: 'bravo charlie', download: 'download'}, [
      'delta',
      'echo'
    ])
  ])
)

console.log(
  s('svg', {viewbox: '0 0 500 500', xmlns: 'http://www.w3.org/2000/svg'}, [
    s('title', 'SVG `<circle>` element'),
    s('circle', {cx: 120, cy: 120, r: 100})
  ])
)
```

Yields:

```js
{
  type: 'element',
  tagName: 'div',
  properties: {className: ['foo'], id: 'some-id'},
  children: [
    {
      type: 'element',
      tagName: 'span',
      properties: {},
      children: [{type: 'text', value: 'some text'}]
    },
    {
      type: 'element',
      tagName: 'input',
      properties: {type: 'text', value: 'foo'},
      children: []
    },
    {
      type: 'element',
      tagName: 'a',
      properties: {className: ['alpha', 'bravo', 'charlie'], download: true},
      children: [{type: 'text', value: 'delta'}, {type: 'text', value: 'echo'}]
    }
  ]
}
{
  type: 'element',
  tagName: 'svg',
  properties: {viewBox: '0 0 500 500', xmlns: 'http://www.w3.org/2000/svg'},
  children: [
    {
      type: 'element',
      tagName: 'title',
      properties: {},
      children: [{type: 'text', value: 'SVG `<circle>` element'}]
    },
    {
      type: 'element',
      tagName: 'circle',
      properties: {cx: 120, cy: 120, r: 100},
      children: []
    }
  ]
}
```

## API

This package exports the identifiers [`h`][api-h] and [`s`][api-s].
There is no default export.
It exports the additional [TypeScript][] types
[`Child`][api-child],
[`Properties`][api-properties],
and
[`Result`][api-result].

The export map supports the automatic JSX runtime.
You can pass `hastscript` or `hastscript/svg` to your build tool
(TypeScript, Babel, SWC)
with an `importSource` option or similar.

### `h(selector?[, properties][, …children])`

Create virtual **[hast][github-hast]** trees for HTML.

##### Signatures

* `h(): root`
* `h(null[, …children]): root`
* `h(selector[, properties][, …children]): element`

##### Parameters

###### `selector`

Simple CSS selector
(`string`, optional).
When string, builds an [`Element`][github-hast-element].
When nullish, builds a [`Root`][github-hast-root] instead.
The selector can contain a tag name (`foo`),
IDs (`#bar`),
and classes (`.baz`).
If the selector is a string but there is no tag name in it then `h` defaults to
build a `div` element and `s` to a `g` element.
`selector` is parsed by
[`hast-util-parse-selector`][github-hast-util-parse-selector].

###### `properties`

Properties of the element
([`Properties`][api-properties], optional).

###### `children`

Children of the node ([`Child`][api-child] or `Array<Child>`, optional).

##### Returns

Created tree ([`Result`][api-result]).

[`Element`][github-hast-element] when a `selector` is passed,
otherwise [`Root`][github-hast-root].

### `s(selector?[, properties][, …children])`

Create virtual **[hast][github-hast]** trees for SVG.

Signatures, parameters, and return value are the same as `h` above.
Importantly,
the `selector` and `properties` parameters are interpreted as SVG.

### `Child`

(Lists of) children (TypeScript type).

When strings or numbers are encountered,
they are turned into [`Text`][github-hast-text]
nodes.
[`Root`][github-hast-root] nodes are treated as “fragments”,
meaning that their children are used instead.

###### Type

```ts
type Child =
  | Array<Node | number | string | null | undefined>
  | Node
  | number
  | string
  | null
  | undefined
```

### `Properties`

Map of properties (TypeScript type).
Keys should match either the HTML attribute name or the DOM property name,
but are case-insensitive.

###### Type

```ts
type Properties = Record<
  string,
  | boolean
  | number
  | string
  | null
  | undefined
  // For comma- and space-separated values such as `className`:
  | Array<number | string>
  // Accepts value for `style` prop as object.
  | Record<string, number | string>
>
```

### `Result`

Result from a `h` (or `s`) call (TypeScript type).

###### Type

```ts
type Result = Element | Root
```

## Syntax tree

The syntax tree is [hast][github-hast].

## JSX

This package can be used with JSX.
You should use the automatic JSX runtime set to `hastscript` or
`hastscript/svg`.

> 👉 **Note**
> while `h` supports dots (`.`) for classes or number signs (`#`)
> for IDs in `selector`,
> those are not supported in JSX.

> 🪦 **Legacy**:
> you can also use the classic JSX runtime,
> but this is not recommended.
> To do so,
> import `h` (or `s`) yourself and define it as the pragma
> (plus set the fragment to `null`).

The Use example above can then be written like so,
using inline pragmas,
so that SVG can be used too:

`example-html.jsx`:

```js
/** @jsxImportSource hastscript */
console.log(
  <div class="foo" id="some-id">
    <span>some text</span>
    <input type="text" value="foo" />
    <a class="alpha bravo charlie" download>
      deltaecho
    </a>
  </div>
)
```

`example-svg.jsx`:

```js
/** @jsxImportSource hastscript/svg */
console.log(
  <svg xmlns="http://www.w3.org/2000/svg" viewbox="0 0 500 500">
    <title>SVG `&lt;circle&gt;` element</title>
    <circle cx={120} cy={120} r={100} />
  </svg>
)
```

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release,
we drop support for unmaintained versions of Node.
This means we try to keep the current release line,
`hastscript@9`,
compatible with Node.js 16.

## Security

Use of `hastscript` can open you up to a
[cross-site scripting (XSS)][wikipedia-xss]
when you pass user-provided input to it because values are injected into the
syntax tree.

The following example shows how an image is injected that fails loading and
therefore runs code in a browser.

```js
const tree = h()

// Somehow someone injected these properties instead of an expected `src` and
// `alt`:
const otherProps = {onError: 'alert(1)', src: 'x'}

tree.children.push(h('img', {src: 'default.png', ...otherProps}))
```

Yields:

```html
<img onerror="alert(1)" src="x">
```

The following example shows how code can run in a browser because someone stored
an object in a database instead of the expected string.

```js
const tree = h()

// Somehow this isn’t the expected `'wooorm'`.
const username = {
  type: 'element',
  tagName: 'script',
  children: [{type: 'text', value: 'alert(2)'}]
}

tree.children.push(h('span.handle', username))
```

Yields:

```html
<span class="handle"><script>alert(2)</script></span>
```

Either do not use user-provided input in `hastscript` or use
[`hast-util-santize`][github-hast-util-sanitize].

## Related

* [`unist-builder`][github-unist-builder]
  — create unist trees
* [`xastscript`][github-xastscript]
  — create xast trees
* [`hast-to-hyperscript`](https://github.com/syntax-tree/hast-to-hyperscript)
  — turn hast into React, Preact, Vue, etc
* [`hast-util-to-html`](https://github.com/syntax-tree/hast-util-to-html)
  — turn hast into HTML
* [`hast-util-to-dom`](https://github.com/syntax-tree/hast-util-to-dom)
  — turn hast into DOM trees
* [`estree-util-build-jsx`](https://github.com/syntax-tree/estree-util-build-jsx)
  — compile JSX away

## Contribute

See
[`contributing.md`][health-contributing]
in
[`syntax-tree/.github`][health]
for ways to get started.
See [`support.md`][health-support] for ways to get help.

This project has a [code of conduct][health-coc].
By interacting with this repository,
organization,
or community you agree to abide by its terms.

## License

[MIT][file-license] © [Titus Wormer][wooorm]

<!-- Definitions -->

[api-child]: #child

[api-h]: #hselector-properties-children

[api-properties]: #properties-1

[api-result]: #result

[api-s]: #sselector-properties-children

[badge-build-image]: https://github.com/syntax-tree/hastscript/workflows/main/badge.svg

[badge-build-url]: https://github.com/syntax-tree/hastscript/actions

[badge-coverage-image]: https://img.shields.io/codecov/c/github/syntax-tree/hastscript.svg

[badge-coverage-url]: https://codecov.io/github/syntax-tree/hastscript

[badge-downloads-image]: https://img.shields.io/npm/dm/hastscript.svg

[badge-downloads-url]: https://www.npmjs.com/package/hastscript

[badge-size-image]: https://img.shields.io/bundlejs/size/hastscript

[badge-size-url]: https://bundlejs.com/?q=hastscript

[esmsh]: https://esm.sh

[file-license]: license

[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[github-hast]: https://github.com/syntax-tree/hast

[github-hast-element]: https://github.com/syntax-tree/hast#element

[github-hast-root]: https://github.com/syntax-tree/hast#root

[github-hast-text]: https://github.com/syntax-tree/hast#text

[github-hast-util-parse-selector]: https://github.com/syntax-tree/hast-util-parse-selector

[github-hast-util-sanitize]: https://github.com/syntax-tree/hast-util-sanitize

[github-unist-builder]: https://github.com/syntax-tree/unist-builder

[github-xastscript]: https://github.com/syntax-tree/xastscript

[health]: https://github.com/syntax-tree/.github

[health-coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md

[health-contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md

[health-support]: https://github.com/syntax-tree/.github/blob/main/support.md

[npmjs-install]: https://docs.npmjs.com/cli/install

[typescript]: https://www.typescriptlang.org

[wikipedia-xss]: https://en.wikipedia.org/wiki/Cross-site_scripting

[wooorm]: https://wooorm.com


---

# he [![Build status](https://travis-ci.org/mathiasbynens/he.svg?branch=master)](https://travis-ci.org/mathiasbynens/he) [![Code coverage status](https://codecov.io/github/mathiasbynens/he/coverage.svg?branch=master)](https://codecov.io/github/mathiasbynens/he?branch=master) [![Dependency status](https://gemnasium.com/mathiasbynens/he.svg)](https://gemnasium.com/mathiasbynens/he)

_he_ (for “HTML entities”) is a robust HTML entity encoder/decoder written in JavaScript. It supports [all standardized named character references as per HTML](https://html.spec.whatwg.org/multipage/syntax.html#named-character-references), handles [ambiguous ampersands](https://mathiasbynens.be/notes/ambiguous-ampersands) and other edge cases [just like a browser would](https://html.spec.whatwg.org/multipage/syntax.html#tokenizing-character-references), has an extensive test suite, and — contrary to many other JavaScript solutions — _he_ handles astral Unicode symbols just fine. [An online demo is available.](https://mothereff.in/html-entities)

## Installation

Via [npm](https://www.npmjs.com/):

```bash
npm install he
```

Via [Bower](http://bower.io/):

```bash
bower install he
```

Via [Component](https://github.com/component/component):

```bash
component install mathiasbynens/he
```

In a browser:

```html
<script src="he.js"></script>
```

In [Node.js](https://nodejs.org/), [io.js](https://iojs.org/), [Narwhal](http://narwhaljs.org/), and [RingoJS](http://ringojs.org/):

```js
var he = require('he');
```

In [Rhino](http://www.mozilla.org/rhino/):

```js
load('he.js');
```

Using an AMD loader like [RequireJS](http://requirejs.org/):

```js
require(
  {
    'paths': {
      'he': 'path/to/he'
    }
  },
  ['he'],
  function(he) {
    console.log(he);
  }
);
```

## API

### `he.version`

A string representing the semantic version number.

### `he.encode(text, options)`

This function takes a string of text and encodes (by default) any symbols that aren’t printable ASCII symbols and `&`, `<`, `>`, `"`, `'`, and `` ` ``, replacing them with character references.

```js
he.encode('foo © bar ≠ baz 𝌆 qux');
// → 'foo &#xA9; bar &#x2260; baz &#x1D306; qux'
```

As long as the input string contains [allowed code points](https://html.spec.whatwg.org/multipage/parsing.html#preprocessing-the-input-stream) only, the return value of this function is always valid HTML. Any [(invalid) code points that cannot be represented using a character reference](https://html.spec.whatwg.org/multipage/syntax.html#table-charref-overrides) in the input are not encoded:

```js
he.encode('foo \0 bar');
// → 'foo \0 bar'
```

However, enabling [the `strict` option](https://github.com/mathiasbynens/he#strict) causes invalid code points to throw an exception. With `strict` enabled, `he.encode` either throws (if the input contains invalid code points) or returns a string of valid HTML.

The `options` object is optional. It recognizes the following properties:

#### `useNamedReferences`

The default value for the `useNamedReferences` option is `false`. This means that `encode()` will not use any named character references (e.g. `&copy;`) in the output — hexadecimal escapes (e.g. `&#xA9;`) will be used instead. Set it to `true` to enable the use of named references.

**Note that if compatibility with older browsers is a concern, this option should remain disabled.**

```js
// Using the global default setting (defaults to `false`):
he.encode('foo © bar ≠ baz 𝌆 qux');
// → 'foo &#xA9; bar &#x2260; baz &#x1D306; qux'

// Passing an `options` object to `encode`, to explicitly disallow named references:
he.encode('foo © bar ≠ baz 𝌆 qux', {
  'useNamedReferences': false
});
// → 'foo &#xA9; bar &#x2260; baz &#x1D306; qux'

// Passing an `options` object to `encode`, to explicitly allow named references:
he.encode('foo © bar ≠ baz 𝌆 qux', {
  'useNamedReferences': true
});
// → 'foo &copy; bar &ne; baz &#x1D306; qux'
```

#### `decimal`

The default value for the `decimal` option is `false`. If the option is enabled, `encode` will generally use decimal escapes (e.g. `&#169;`) rather than hexadecimal escapes (e.g. `&#xA9;`). Beside of this replacement, the basic behavior remains the same when combined with other options. For example: if both options `useNamedReferences` and `decimal` are enabled, named references (e.g. `&copy;`) are used over decimal escapes. HTML entities without a named reference are encoded using decimal escapes.

```js
// Using the global default setting (defaults to `false`):
he.encode('foo © bar ≠ baz 𝌆 qux');
// → 'foo &#xA9; bar &#x2260; baz &#x1D306; qux'

// Passing an `options` object to `encode`, to explicitly disable decimal escapes:
he.encode('foo © bar ≠ baz 𝌆 qux', {
  'decimal': false
});
// → 'foo &#xA9; bar &#x2260; baz &#x1D306; qux'

// Passing an `options` object to `encode`, to explicitly enable decimal escapes:
he.encode('foo © bar ≠ baz 𝌆 qux', {
  'decimal': true
});
// → 'foo &#169; bar &#8800; baz &#119558; qux'

// Passing an `options` object to `encode`, to explicitly allow named references and decimal escapes:
he.encode('foo © bar ≠ baz 𝌆 qux', {
  'useNamedReferences': true,
  'decimal': true
});
// → 'foo &copy; bar &ne; baz &#119558; qux'
```

#### `encodeEverything`

The default value for the `encodeEverything` option is `false`. This means that `encode()` will not use any character references for printable ASCII symbols that don’t need escaping. Set it to `true` to encode every symbol in the input string. When set to `true`, this option takes precedence over `allowUnsafeSymbols` (i.e. setting the latter to `true` in such a case has no effect).

```js
// Using the global default setting (defaults to `false`):
he.encode('foo © bar ≠ baz 𝌆 qux');
// → 'foo &#xA9; bar &#x2260; baz &#x1D306; qux'

// Passing an `options` object to `encode`, to explicitly encode all symbols:
he.encode('foo © bar ≠ baz 𝌆 qux', {
  'encodeEverything': true
});
// → '&#x66;&#x6F;&#x6F;&#x20;&#xA9;&#x20;&#x62;&#x61;&#x72;&#x20;&#x2260;&#x20;&#x62;&#x61;&#x7A;&#x20;&#x1D306;&#x20;&#x71;&#x75;&#x78;'

// This setting can be combined with the `useNamedReferences` option:
he.encode('foo © bar ≠ baz 𝌆 qux', {
  'encodeEverything': true,
  'useNamedReferences': true
});
// → '&#x66;&#x6F;&#x6F;&#x20;&copy;&#x20;&#x62;&#x61;&#x72;&#x20;&ne;&#x20;&#x62;&#x61;&#x7A;&#x20;&#x1D306;&#x20;&#x71;&#x75;&#x78;'
```

#### `strict`

The default value for the `strict` option is `false`. This means that `encode()` will encode any HTML text content you feed it, even if it contains any symbols that cause [parse errors](https://html.spec.whatwg.org/multipage/parsing.html#preprocessing-the-input-stream). To throw an error when such invalid HTML is encountered, set the `strict` option to `true`. This option makes it possible to use _he_ as part of HTML parsers and HTML validators.

```js
// Using the global default setting (defaults to `false`, i.e. error-tolerant mode):
he.encode('\x01');
// → '&#x1;'

// Passing an `options` object to `encode`, to explicitly enable error-tolerant mode:
he.encode('\x01', {
  'strict': false
});
// → '&#x1;'

// Passing an `options` object to `encode`, to explicitly enable strict mode:
he.encode('\x01', {
  'strict': true
});
// → Parse error
```

#### `allowUnsafeSymbols`

The default value for the `allowUnsafeSymbols` option is `false`. This means that characters that are unsafe for use in HTML content (`&`, `<`, `>`, `"`, `'`, and `` ` ``) will be encoded. When set to `true`, only non-ASCII characters will be encoded. If the `encodeEverything` option is set to `true`, this option will be ignored.

```js
he.encode('foo © and & ampersand', {
  'allowUnsafeSymbols': true
});
// → 'foo &#xA9; and & ampersand'
```

#### Overriding default `encode` options globally

The global default setting can be overridden by modifying the `he.encode.options` object. This saves you from passing in an `options` object for every call to `encode` if you want to use the non-default setting.

```js
// Read the global default setting:
he.encode.options.useNamedReferences;
// → `false` by default

// Override the global default setting:
he.encode.options.useNamedReferences = true;

// Using the global default setting, which is now `true`:
he.encode('foo © bar ≠ baz 𝌆 qux');
// → 'foo &copy; bar &ne; baz &#x1D306; qux'
```

### `he.decode(html, options)`

This function takes a string of HTML and decodes any named and numerical character references in it using [the algorithm described in section 12.2.4.69 of the HTML spec](https://html.spec.whatwg.org/multipage/syntax.html#tokenizing-character-references).

```js
he.decode('foo &copy; bar &ne; baz &#x1D306; qux');
// → 'foo © bar ≠ baz 𝌆 qux'
```

The `options` object is optional. It recognizes the following properties:

#### `isAttributeValue`

The default value for the `isAttributeValue` option is `false`. This means that `decode()` will decode the string as if it were used in [a text context in an HTML document](https://html.spec.whatwg.org/multipage/syntax.html#data-state). HTML has different rules for [parsing character references in attribute values](https://html.spec.whatwg.org/multipage/syntax.html#character-reference-in-attribute-value-state) — set this option to `true` to treat the input string as if it were used as an attribute value.

```js
// Using the global default setting (defaults to `false`, i.e. HTML text context):
he.decode('foo&ampbar');
// → 'foo&bar'

// Passing an `options` object to `decode`, to explicitly assume an HTML text context:
he.decode('foo&ampbar', {
  'isAttributeValue': false
});
// → 'foo&bar'

// Passing an `options` object to `decode`, to explicitly assume an HTML attribute value context:
he.decode('foo&ampbar', {
  'isAttributeValue': true
});
// → 'foo&ampbar'
```

#### `strict`

The default value for the `strict` option is `false`. This means that `decode()` will decode any HTML text content you feed it, even if it contains any entities that cause [parse errors](https://html.spec.whatwg.org/multipage/syntax.html#tokenizing-character-references). To throw an error when such invalid HTML is encountered, set the `strict` option to `true`. This option makes it possible to use _he_ as part of HTML parsers and HTML validators.

```js
// Using the global default setting (defaults to `false`, i.e. error-tolerant mode):
he.decode('foo&ampbar');
// → 'foo&bar'

// Passing an `options` object to `decode`, to explicitly enable error-tolerant mode:
he.decode('foo&ampbar', {
  'strict': false
});
// → 'foo&bar'

// Passing an `options` object to `decode`, to explicitly enable strict mode:
he.decode('foo&ampbar', {
  'strict': true
});
// → Parse error
```

#### Overriding default `decode` options globally

The global default settings for the `decode` function can be overridden by modifying the `he.decode.options` object. This saves you from passing in an `options` object for every call to `decode` if you want to use a non-default setting.

```js
// Read the global default setting:
he.decode.options.isAttributeValue;
// → `false` by default

// Override the global default setting:
he.decode.options.isAttributeValue = true;

// Using the global default setting, which is now `true`:
he.decode('foo&ampbar');
// → 'foo&ampbar'
```

### `he.escape(text)`

This function takes a string of text and escapes it for use in text contexts in XML or HTML documents. Only the following characters are escaped: `&`, `<`, `>`, `"`, `'`, and `` ` ``.

```js
he.escape('<img src=\'x\' onerror="prompt(1)">');
// → '&lt;img src=&#x27;x&#x27; onerror=&quot;prompt(1)&quot;&gt;'
```

### `he.unescape(html, options)`

`he.unescape` is an alias for `he.decode`. It takes a string of HTML and decodes any named and numerical character references in it.

### Using the `he` binary

To use the `he` binary in your shell, simply install _he_ globally using npm:

```bash
npm install -g he
```

After that you will be able to encode/decode HTML entities from the command line:

```bash
$ he --encode 'föo ♥ bår 𝌆 baz'
f&#xF6;o &#x2665; b&#xE5;r &#x1D306; baz

$ he --encode --use-named-refs 'föo ♥ bår 𝌆 baz'
f&ouml;o &hearts; b&aring;r &#x1D306; baz

$ he --decode 'f&ouml;o &hearts; b&aring;r &#x1D306; baz'
föo ♥ bår 𝌆 baz
```

Read a local text file, encode it for use in an HTML text context, and save the result to a new file:

```bash
$ he --encode < foo.txt > foo-escaped.html
```

Or do the same with an online text file:

```bash
$ curl -sL "http://git.io/HnfEaw" | he --encode > escaped.html
```

Or, the opposite — read a local file containing a snippet of HTML in a text context, decode it back to plain text, and save the result to a new file:

```bash
$ he --decode < foo-escaped.html > foo.txt
```

Or do the same with an online HTML snippet:

```bash
$ curl -sL "http://git.io/HnfEaw" | he --decode > decoded.txt
```

See `he --help` for the full list of options.

## Support

_he_ has been tested in at least:

* Chrome 27-50
* Firefox 3-45
* Safari 4-9
* Opera 10-12, 15–37
* IE 6–11
* Edge
* Narwhal 0.3.2
* Node.js v0.10, v0.12, v4, v5
* PhantomJS 1.9.0
* Rhino 1.7RC4
* RingoJS 0.8-0.11

## Unit tests & code coverage

After cloning this repository, run `npm install` to install the dependencies needed for he development and testing. You may want to install Istanbul _globally_ using `npm install istanbul -g`.

Once that’s done, you can run the unit tests in Node using `npm test` or `node tests/tests.js`. To run the tests in Rhino, Ringo, Narwhal, and web browsers as well, use `grunt test`.

To generate the code coverage report, use `grunt cover`.

## Acknowledgements

Thanks to [Simon Pieters](https://simon.html5.org/) ([@zcorpan](https://twitter.com/zcorpan)) for the many suggestions.

## Author

| [![twitter/mathias](https://gravatar.com/avatar/24e08a9ea84deb17ae121074d0f17125?s=70)](https://twitter.com/mathias "Follow @mathias on Twitter") |
|---|
| [Mathias Bynens](https://mathiasbynens.be/) |

## License

_he_ is available under the [MIT](https://mths.be/mit) license.


---

# history &middot; [![npm package][npm-badge]][npm] [![Travis][build-badge]][build]

[npm-badge]: https://img.shields.io/npm/v/history.svg?style=flat-square
[npm]: https://www.npmjs.org/package/history
[build-badge]: https://img.shields.io/travis/ReactTraining/history/master.svg?style=flat-square
[build]: https://travis-ci.org/ReactTraining/history

The history library lets you easily manage session history anywhere JavaScript runs. `history` abstracts away the differences in various environments and provides a minimal API that lets you manage the history stack, navigate, and persist state between sessions.

## Documentation

Documentation for the current branch can be found in the [docs](docs) directory.

## Changes

To see the changes that were made in a given release, please lookup the tag on [the releases page](https://github.com/ReactTraining/history/releases).

For changes released in version 4.6.3 and earlier, please see [the `CHANGES.md` file](https://github.com/ReactTraining/history/blob/845d690c5576c7f55ecbe14babe0092e8e5bc2bb/CHANGES.md).

## Development

Development of the current stable release, version 4, happens on [the `master` branch](https://github.com/ReactTraining/history/tree/master). Please keep in mind that this branch may include some work that has not yet been published as part of an official release. However, since `master` is always stable, you should feel free to build your own working release straight from master at any time.

Development of the next major release, version 5, happens on [the `dev` branch](https://github.com/ReactTraining/history/tree/dev).

If you're interested in helping out, please read [our contributing guidelines](CONTRIBUTING.md).

## About

`history` is developed and maintained by [React Training](https://reacttraining.com). If
you're interested in learning more about what React can do for your company, please
[get in touch](mailto:hello@reacttraining.com)!

## Thanks

A big thank-you to [BrowserStack](https://www.browserstack.com/) for providing the infrastructure that allows us to run our build in real browsers.

Also, thanks to [Dan Shaw](https://www.npmjs.com/~dshaw) for letting us use the `history` npm package name. Thanks, Dan!


---

# 3.3.2 (January 22, 2020)
- Fix `React.memo` for v16.12+ (#93)

# 3.3.1 (November 14, 2019)
- Fix for UMD bundle (#85)
- Tooling changes (#83, #84, #87)

# 3.3.0 (January 23, 2019)
- Prevent hoisting of React.memo statics (#73)

# 3.2.1 (December 3, 2018)
- Fixed `defaultProps`, `displayName` and `propTypes` being hoisted from `React.forwardRef` to `React.forwardRef`. ([#71])

# 3.2.0 (November 26, 2018)
- Added support for `getDerivedStateFromError`. ([#68])
- Added support for React versions less than 0.14. ([#69])

# 3.1.0 (October 30, 2018)
- Added support for `contextType`. ([#62])
- Reduced bundle size. ([e89c7a6])
- Removed TypeScript definitions. ([#61])

# 3.0.1 (July 28, 2018)
- Fixed prop-types warnings. ([e0846fe])

# 3.0.0 (July 27, 2018)
- Dropped support for React versions less than 0.14. ([#55])
- Added support for `React.forwardRef` components. ([#55])

[#55]: https://github.com/mridgway/hoist-non-react-statics/pull/55
[#61]: https://github.com/mridgway/hoist-non-react-statics/pull/61
[#62]: https://github.com/mridgway/hoist-non-react-statics/pull/62
[#68]: https://github.com/mridgway/hoist-non-react-statics/pull/68
[#69]: https://github.com/mridgway/hoist-non-react-statics/pull/69
[#71]: https://github.com/mridgway/hoist-non-react-statics/pull/71
[e0846fe]: https://github.com/mridgway/hoist-non-react-statics/commit/e0846feefbad8b34d300de9966ffd607aacb81a3
[e89c7a6]: https://github.com/mridgway/hoist-non-react-statics/commit/e89c7a6168edc19eeadb2d149e600b888e8b0446


---

Software License Agreement (BSD License)
========================================

Copyright (c) 2015, Yahoo! Inc. All rights reserved.
----------------------------------------------------

Redistribution and use of this software in source and binary forms, with or
without modification, are permitted provided that the following conditions are
met:

  * Redistributions of source code must retain the above copyright notice, this
    list of conditions and the following disclaimer.
  * Redistributions in binary form must reproduce the above copyright notice,
    this list of conditions and the following disclaimer in the documentation
    and/or other materials provided with the distribution.
  * Neither the name of Yahoo! Inc. nor the names of YUI's contributors may be
    used to endorse or promote products derived from this software without
    specific prior written permission of Yahoo! Inc.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


---

# hoist-non-react-statics

[![NPM version](https://badge.fury.io/js/hoist-non-react-statics.svg)](http://badge.fury.io/js/hoist-non-react-statics)
[![Build Status](https://img.shields.io/travis/mridgway/hoist-non-react-statics.svg)](https://travis-ci.org/mridgway/hoist-non-react-statics)
[![Coverage Status](https://img.shields.io/coveralls/mridgway/hoist-non-react-statics.svg)](https://coveralls.io/r/mridgway/hoist-non-react-statics?branch=master)
[![Dependency Status](https://img.shields.io/david/mridgway/hoist-non-react-statics.svg)](https://david-dm.org/mridgway/hoist-non-react-statics)
[![devDependency Status](https://img.shields.io/david/dev/mridgway/hoist-non-react-statics.svg)](https://david-dm.org/mridgway/hoist-non-react-statics#info=devDependencies)

Copies non-react specific statics from a child component to a parent component. 
Similar to `Object.assign`, but with React static keywords blacklisted from
being overridden.

```bash
$ npm install --save hoist-non-react-statics
```

## Usage

```js
import hoistNonReactStatics from 'hoist-non-react-statics';

hoistNonReactStatics(targetComponent, sourceComponent);
```

If you have specific statics that you don't want to be hoisted, you can also pass a third parameter to exclude them:

```js
hoistNonReactStatics(targetComponent, sourceComponent, { myStatic: true, myOtherStatic: true });
```

## What does this module do?

See this [explanation](https://facebook.github.io/react/docs/higher-order-components.html#static-methods-must-be-copied-over) from the React docs.

## Compatible React Versions

Please use latest 3.x. Versions prior to 3.x will not support ForwardRefs.

| hoist-non-react-statics Version | Compatible React Version |
|--------------------------|-------------------------------|
| 3.x | 0.13-16.x With ForwardRef Support |
| 2.x | 0.13-16.x Without ForwardRef Support |
| 1.x | 0.13-16.2 |

## Browser Support

This package uses `Object.defineProperty` which has a broken implementation in IE8. In order to use this package in IE8, you will need a polyfill that fixes this method.

## License
This software is free to use under the Yahoo Inc. BSD license.
See the [LICENSE file][] for license text and copyright information.

[LICENSE file]: https://github.com/mridgway/hoist-non-react-statics/blob/master/LICENSE.md

Third-party open source code used are listed in our [package.json file]( https://github.com/mridgway/hoist-non-react-statics/blob/master/package.json).


---

# HPACK.js

[![Build Status](https://secure.travis-ci.org/indutny/hpack.js.png)](http://travis-ci.org/indutny/hpack.js)
[![NPM version](https://badge.fury.io/js/hpack.js.svg)](http://badge.fury.io/js/hpack.js)

Plain-JS implementation of [HPACK][0].

## Usage

```javascript
var hpack = require('hpack.js');

var comp = hpack.compressor.create({ table: { size: 256 } });
var decomp = hpack.decompressor.create({ table: { size: 256 } });

comp.write([ { name: 'host', value: 'localhost' } ]);
var raw = comp.read();
console.log(raw);
// <Buffer 66 86 a0 e4 1d 13 9d 09>

decomp.write(raw);
decomp.execute();
console.log(decomp.read());
// { name: 'host', value: 'localhost', neverIndex: false }
```

#### LICENSE

This software is licensed under the MIT License.

Copyright Fedor Indutny, 2015.

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to permit
persons to whom the Software is furnished to do so, subject to the
following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
USE OR OTHER DEALINGS IN THE SOFTWARE.

[0]: https://tools.ietf.org/html/rfc7541


---


# isarray

`Array#isArray` for older browsers.

[![build status](https://secure.travis-ci.org/juliangruber/isarray.svg)](http://travis-ci.org/juliangruber/isarray)
[![downloads](https://img.shields.io/npm/dm/isarray.svg)](https://www.npmjs.org/package/isarray)

[![browser support](https://ci.testling.com/juliangruber/isarray.png)
](https://ci.testling.com/juliangruber/isarray)

## Usage

```js
var isArray = require('isarray');

console.log(isArray([])); // => true
console.log(isArray({})); // => false
```

## Installation

With [npm](http://npmjs.org) do

```bash
$ npm install isarray
```

Then bundle for the browser with
[browserify](https://github.com/substack/browserify).

With [component](http://component.io) do

```bash
$ component install juliangruber/isarray
```

## License

(MIT)

Copyright (c) 2013 Julian Gruber &lt;julian@juliangruber.com&gt;

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

* (a) The contribution was created in whole or in part by me and I
  have the right to submit it under the open source license
  indicated in the file; or

* (b) The contribution is based upon previous work that, to the best
  of my knowledge, is covered under an appropriate open source
  license and I have the right under that license to submit that
  work with modifications, whether created in whole or in part
  by me, under the same open source license (unless I am
  permitted to submit under a different license), as indicated
  in the file; or

* (c) The contribution was provided directly to me by some other
  person who certified (a), (b) or (c) and I have not modified
  it.

* (d) I understand and agree that this project and the contribution
  are public and that a record of the contribution (including all
  personal information I submit with it, including my sign-off) is
  maintained indefinitely and may be redistributed consistent with
  this project or the open source license(s) involved.

## Moderation Policy

The [Node.js Moderation Policy] applies to this WG.

## Code of Conduct

The [Node.js Code of Conduct][] applies to this WG.

[Node.js Code of Conduct]:
https://github.com/nodejs/node/blob/master/CODE_OF_CONDUCT.md
[Node.js Moderation Policy]:
https://github.com/nodejs/TSC/blob/master/Moderation-Policy.md


---

### Streams Working Group

The Node.js Streams is jointly governed by a Working Group
(WG)
that is responsible for high-level guidance of the project.

The WG has final authority over this project including:

* Technical direction
* Project governance and process (including this policy)
* Contribution policy
* GitHub repository hosting
* Conduct guidelines
* Maintaining the list of additional Collaborators

For the current list of WG members, see the project
[README.md](./README.md#current-project-team-members).

### Collaborators

The readable-stream GitHub repository is
maintained by the WG and additional Collaborators who are added by the
WG on an ongoing basis.

Individuals making significant and valuable contributions are made
Collaborators and given commit-access to the project. These
individuals are identified by the WG and their addition as
Collaborators is discussed during the WG meeting.

_Note:_ If you make a significant contribution and are not considered
for commit-access log an issue or contact a WG member directly and it
will be brought up in the next WG meeting.

Modifications of the contents of the readable-stream repository are
made on
a collaborative basis. Anybody with a GitHub account may propose a
modification via pull request and it will be considered by the project
Collaborators. All pull requests must be reviewed and accepted by a
Collaborator with sufficient expertise who is able to take full
responsibility for the change. In the case of pull requests proposed
by an existing Collaborator, an additional Collaborator is required
for sign-off. Consensus should be sought if additional Collaborators
participate and there is disagreement around a particular
modification. See _Consensus Seeking Process_ below for further detail
on the consensus model used for governance.

Collaborators may opt to elevate significant or controversial
modifications, or modifications that have not found consensus to the
WG for discussion by assigning the ***WG-agenda*** tag to a pull
request or issue. The WG should serve as the final arbiter where
required.

For the current list of Collaborators, see the project
[README.md](./README.md#members).

### WG Membership

WG seats are not time-limited.  There is no fixed size of the WG.
However, the expected target is between 6 and 12, to ensure adequate
coverage of important areas of expertise, balanced with the ability to
make decisions efficiently.

There is no specific set of requirements or qualifications for WG
membership beyond these rules.

The WG may add additional members to the WG by unanimous consensus.

A WG member may be removed from the WG by voluntary resignation, or by
unanimous consensus of all other WG members.

Changes to WG membership should be posted in the agenda, and may be
suggested as any other agenda item (see "WG Meetings" below).

If an addition or removal is proposed during a meeting, and the full
WG is not in attendance to participate, then the addition or removal
is added to the agenda for the subsequent meeting.  This is to ensure
that all members are given the opportunity to participate in all
membership decisions.  If a WG member is unable to attend a meeting
where a planned membership decision is being made, then their consent
is assumed.

No more than 1/3 of the WG members may be affiliated with the same
employer.  If removal or resignation of a WG member, or a change of
employment by a WG member, creates a situation where more than 1/3 of
the WG membership shares an employer, then the situation must be
immediately remedied by the resignation or removal of one or more WG
members affiliated with the over-represented employer(s).

### WG Meetings

The WG meets occasionally on a Google Hangout On Air. A designated moderator
approved by the WG runs the meeting. Each meeting should be
published to YouTube.

Items are added to the WG agenda that are considered contentious or
are modifications of governance, contribution policy, WG membership,
or release process.

The intention of the agenda is not to approve or review all patches;
that should happen continuously on GitHub and be handled by the larger
group of Collaborators.

Any community member or contributor can ask that something be added to
the next meeting's agenda by logging a GitHub Issue. Any Collaborator,
WG member or the moderator can add the item to the agenda by adding
the ***WG-agenda*** tag to the issue.

Prior to each WG meeting the moderator will share the Agenda with
members of the WG. WG members can add any items they like to the
agenda at the beginning of each meeting. The moderator and the WG
cannot veto or remove items.

The WG may invite persons or representatives from certain projects to
participate in a non-voting capacity.

The moderator is responsible for summarizing the discussion of each
agenda item and sends it as a pull request after the meeting.

### Consensus Seeking Process

The WG follows a
[Consensus
Seeking](http://en.wikipedia.org/wiki/Consensus-seeking_decision-making)
decision-making model.

When an agenda item has appeared to reach a consensus the moderator
will ask "Does anyone object?" as a final call for dissent from the
consensus.

If an agenda item cannot reach a consensus a WG member can call for
either a closing vote or a vote to table the issue to the next
meeting. The call for a vote must be seconded by a majority of the WG
or else the discussion will continue. Simple majority wins.

Note that changes to WG membership require a majority consensus.  See
"WG Membership" above.


---

# readable-stream

***Node-core v8.17.0 streams for userland*** [![Build Status](https://travis-ci.org/nodejs/readable-stream.svg?branch=master)](https://travis-ci.org/nodejs/readable-stream)


[![NPM](https://nodei.co/npm/readable-stream.png?downloads=true&downloadRank=true)](https://nodei.co/npm/readable-stream/)
[![NPM](https://nodei.co/npm-dl/readable-stream.png?&months=6&height=3)](https://nodei.co/npm/readable-stream/)


[![Sauce Test Status](https://saucelabs.com/browser-matrix/readable-stream.svg)](https://saucelabs.com/u/readable-stream)

```bash
npm install --save readable-stream
```

***Node-core streams for userland***

This package is a mirror of the Streams2 and Streams3 implementations in
Node-core.

Full documentation may be found on the [Node.js website](https://nodejs.org/dist/v8.17.0/docs/api/stream.html).

If you want to guarantee a stable streams base, regardless of what version of
Node you, or the users of your libraries are using, use **readable-stream** *only* and avoid the *"stream"* module in Node-core, for background see [this blogpost](http://r.va.gg/2014/06/why-i-dont-use-nodes-core-stream-module.html).

As of version 2.0.0 **readable-stream** uses semantic versioning.

# Streams Working Group

`readable-stream` is maintained by the Streams Working Group, which
oversees the development and maintenance of the Streams API within
Node.js. The responsibilities of the Streams Working Group include:

* Addressing stream issues on the Node.js issue tracker.
* Authoring and editing stream documentation within the Node.js project.
* Reviewing changes to stream subclasses within the Node.js project.
* Redirecting changes to streams from the Node.js project to this
  project.
* Assisting in the implementation of stream providers within Node.js.
* Recommending versions of `readable-stream` to be included in Node.js.
* Messaging about the future of streams to give the community advance
  notice of changes.

<a name="members"></a>
## Team Members

* **Chris Dickinson** ([@chrisdickinson](https://github.com/chrisdickinson)) &lt;christopher.s.dickinson@gmail.com&gt;
  - Release GPG key: 9554F04D7259F04124DE6B476D5A82AC7E37093B
* **Calvin Metcalf** ([@calvinmetcalf](https://github.com/calvinmetcalf)) &lt;calvin.metcalf@gmail.com&gt;
  - Release GPG key: F3EF5F62A87FC27A22E643F714CE4FF5015AA242
* **Rod Vagg** ([@rvagg](https://github.com/rvagg)) &lt;rod@vagg.org&gt;
  - Release GPG key: DD8F2338BAE7501E3DD5AC78C273792F7D83545D
* **Sam Newman** ([@sonewman](https://github.com/sonewman)) &lt;newmansam@outlook.com&gt;
* **Mathias Buus** ([@mafintosh](https://github.com/mafintosh)) &lt;mathiasbuus@gmail.com&gt;
* **Domenic Denicola** ([@domenic](https://github.com/domenic)) &lt;d@domenic.me&gt;
* **Matteo Collina** ([@mcollina](https://github.com/mcollina)) &lt;matteo.collina@gmail.com&gt;
  - Release GPG key: 3ABC01543F22DD2239285CDD818674489FBC127E
* **Irina Shestak** ([@lrlna](https://github.com/lrlna)) &lt;shestak.irina@gmail.com&gt;


---

# streams WG Meeting 2015-01-30

## Links

* **Google Hangouts Video**: http://www.youtube.com/watch?v=I9nDOSGfwZg
* **GitHub Issue**: https://github.com/iojs/readable-stream/issues/106
* **Original Minutes Google Doc**: https://docs.google.com/document/d/17aTgLnjMXIrfjgNaTUnHQO7m3xgzHR2VXBTmi03Qii4/

## Agenda

Extracted from https://github.com/iojs/readable-stream/labels/wg-agenda prior to meeting.

* adopt a charter [#105](https://github.com/iojs/readable-stream/issues/105)
* release and versioning strategy [#101](https://github.com/iojs/readable-stream/issues/101)
* simpler stream creation [#102](https://github.com/iojs/readable-stream/issues/102)
* proposal: deprecate implicit flowing of streams [#99](https://github.com/iojs/readable-stream/issues/99)

## Minutes

### adopt a charter

* group: +1's all around

### What versioning scheme should be adopted?
* group: +1’s 3.0.0
* domenic+group: pulling in patches from other sources where appropriate
* mikeal: version independently, suggesting versions for io.js
* mikeal+domenic: work with TC to notify in advance of changes
simpler stream creation

### streamline creation of streams
* sam: streamline creation of streams
* domenic: nice simple solution posted
  but, we lose the opportunity to change the model
  may not be backwards incompatible (double check keys)

  **action item:** domenic will check

### remove implicit flowing of streams on(‘data’)
* add isFlowing / isPaused
* mikeal: worrying that we’re documenting polyfill methods – confuses users
* domenic: more reflective API is probably good, with warning labels for users
* new section for mad scientists (reflective stream access)
* calvin: name the “third state”
* mikeal: maybe borrow the name from whatwg?
* domenic: we’re missing the “third state”
* consensus: kind of difficult to name the third state
* mikeal: figure out differences in states / compat
* mathias: always flow on data – eliminates third state
  * explore what it breaks

**action items:**
* ask isaac for ability to list packages by what public io.js APIs they use (esp. Stream)
* ask rod/build for infrastructure
* **chris**: explore the “flow on data” approach
* add isPaused/isFlowing
* add new docs section
* move isPaused to that section




---

# safe-buffer [![travis][travis-image]][travis-url] [![npm][npm-image]][npm-url] [![downloads][downloads-image]][downloads-url] [![javascript style guide][standard-image]][standard-url]

[travis-image]: https://img.shields.io/travis/feross/safe-buffer/master.svg
[travis-url]: https://travis-ci.org/feross/safe-buffer
[npm-image]: https://img.shields.io/npm/v/safe-buffer.svg
[npm-url]: https://npmjs.org/package/safe-buffer
[downloads-image]: https://img.shields.io/npm/dm/safe-buffer.svg
[downloads-url]: https://npmjs.org/package/safe-buffer
[standard-image]: https://img.shields.io/badge/code_style-standard-brightgreen.svg
[standard-url]: https://standardjs.com

#### Safer Node.js Buffer API

**Use the new Node.js Buffer APIs (`Buffer.from`, `Buffer.alloc`,
`Buffer.allocUnsafe`, `Buffer.allocUnsafeSlow`) in all versions of Node.js.**

**Uses the built-in implementation when available.**

## install

```
npm install safe-buffer
```

## usage

The goal of this package is to provide a safe replacement for the node.js `Buffer`.

It's a drop-in replacement for `Buffer`. You can use it by adding one `require` line to
the top of your node.js modules:

```js
var Buffer = require('safe-buffer').Buffer

// Existing buffer code will continue to work without issues:

new Buffer('hey', 'utf8')
new Buffer([1, 2, 3], 'utf8')
new Buffer(obj)
new Buffer(16) // create an uninitialized buffer (potentially unsafe)

// But you can use these new explicit APIs to make clear what you want:

Buffer.from('hey', 'utf8') // convert from many types to a Buffer
Buffer.alloc(16) // create a zero-filled buffer (safe)
Buffer.allocUnsafe(16) // create an uninitialized buffer (potentially unsafe)
```

## api

### Class Method: Buffer.from(array)
<!-- YAML
added: v3.0.0
-->

* `array` {Array}

Allocates a new `Buffer` using an `array` of octets.

```js
const buf = Buffer.from([0x62,0x75,0x66,0x66,0x65,0x72]);
  // creates a new Buffer containing ASCII bytes
  // ['b','u','f','f','e','r']
```

A `TypeError` will be thrown if `array` is not an `Array`.

### Class Method: Buffer.from(arrayBuffer[, byteOffset[, length]])
<!-- YAML
added: v5.10.0
-->

* `arrayBuffer` {ArrayBuffer} The `.buffer` property of a `TypedArray` or
  a `new ArrayBuffer()`
* `byteOffset` {Number} Default: `0`
* `length` {Number} Default: `arrayBuffer.length - byteOffset`

When passed a reference to the `.buffer` property of a `TypedArray` instance,
the newly created `Buffer` will share the same allocated memory as the
TypedArray.

```js
const arr = new Uint16Array(2);
arr[0] = 5000;
arr[1] = 4000;

const buf = Buffer.from(arr.buffer); // shares the memory with arr;

console.log(buf);
  // Prints: <Buffer 88 13 a0 0f>

// changing the TypedArray changes the Buffer also
arr[1] = 6000;

console.log(buf);
  // Prints: <Buffer 88 13 70 17>
```

The optional `byteOffset` and `length` arguments specify a memory range within
the `arrayBuffer` that will be shared by the `Buffer`.

```js
const ab = new ArrayBuffer(10);
const buf = Buffer.from(ab, 0, 2);
console.log(buf.length);
  // Prints: 2
```

A `TypeError` will be thrown if `arrayBuffer` is not an `ArrayBuffer`.

### Class Method: Buffer.from(buffer)
<!-- YAML
added: v3.0.0
-->

* `buffer` {Buffer}

Copies the passed `buffer` data onto a new `Buffer` instance.

```js
const buf1 = Buffer.from('buffer');
const buf2 = Buffer.from(buf1);

buf1[0] = 0x61;
console.log(buf1.toString());
  // 'auffer'
console.log(buf2.toString());
  // 'buffer' (copy is not changed)
```

A `TypeError` will be thrown if `buffer` is not a `Buffer`.

### Class Method: Buffer.from(str[, encoding])
<!-- YAML
added: v5.10.0
-->

* `str` {String} String to encode.
* `encoding` {String} Encoding to use, Default: `'utf8'`

Creates a new `Buffer` containing the given JavaScript string `str`. If
provided, the `encoding` parameter identifies the character encoding.
If not provided, `encoding` defaults to `'utf8'`.

```js
const buf1 = Buffer.from('this is a tést');
console.log(buf1.toString());
  // prints: this is a tést
console.log(buf1.toString('ascii'));
  // prints: this is a tC)st

const buf2 = Buffer.from('7468697320697320612074c3a97374', 'hex');
console.log(buf2.toString());
  // prints: this is a tést
```

A `TypeError` will be thrown if `str` is not a string.

### Class Method: Buffer.alloc(size[, fill[, encoding]])
<!-- YAML
added: v5.10.0
-->

* `size` {Number}
* `fill` {Value} Default: `undefined`
* `encoding` {String} Default: `utf8`

Allocates a new `Buffer` of `size` bytes. If `fill` is `undefined`, the
`Buffer` will be *zero-filled*.

```js
const buf = Buffer.alloc(5);
console.log(buf);
  // <Buffer 00 00 00 00 00>
```

The `size` must be less than or equal to the value of
`require('buffer').kMaxLength` (on 64-bit architectures, `kMaxLength` is
`(2^31)-1`). Otherwise, a [`RangeError`][] is thrown. A zero-length Buffer will
be created if a `size` less than or equal to 0 is specified.

If `fill` is specified, the allocated `Buffer` will be initialized by calling
`buf.fill(fill)`. See [`buf.fill()`][] for more information.

```js
const buf = Buffer.alloc(5, 'a');
console.log(buf);
  // <Buffer 61 61 61 61 61>
```

If both `fill` and `encoding` are specified, the allocated `Buffer` will be
initialized by calling `buf.fill(fill, encoding)`. For example:

```js
const buf = Buffer.alloc(11, 'aGVsbG8gd29ybGQ=', 'base64');
console.log(buf);
  // <Buffer 68 65 6c 6c 6f 20 77 6f 72 6c 64>
```

Calling `Buffer.alloc(size)` can be significantly slower than the alternative
`Buffer.allocUnsafe(size)` but ensures that the newly created `Buffer` instance
contents will *never contain sensitive data*.

A `TypeError` will be thrown if `size` is not a number.

### Class Method: Buffer.allocUnsafe(size)
<!-- YAML
added: v5.10.0
-->

* `size` {Number}

Allocates a new *non-zero-filled* `Buffer` of `size` bytes.  The `size` must
be less than or equal to the value of `require('buffer').kMaxLength` (on 64-bit
architectures, `kMaxLength` is `(2^31)-1`). Otherwise, a [`RangeError`][] is
thrown. A zero-length Buffer will be created if a `size` less than or equal to
0 is specified.

The underlying memory for `Buffer` instances created in this way is *not
initialized*. The contents of the newly created `Buffer` are unknown and
*may contain sensitive data*. Use [`buf.fill(0)`][] to initialize such
`Buffer` instances to zeroes.

```js
const buf = Buffer.allocUnsafe(5);
console.log(buf);
  // <Buffer 78 e0 82 02 01>
  // (octets will be different, every time)
buf.fill(0);
console.log(buf);
  // <Buffer 00 00 00 00 00>
```

A `TypeError` will be thrown if `size` is not a number.

Note that the `Buffer` module pre-allocates an internal `Buffer` instance of
size `Buffer.poolSize` that is used as a pool for the fast allocation of new
`Buffer` instances created using `Buffer.allocUnsafe(size)` (and the deprecated
`new Buffer(size)` constructor) only when `size` is less than or equal to
`Buffer.poolSize >> 1` (floor of `Buffer.poolSize` divided by two). The default
value of `Buffer.poolSize` is `8192` but can be modified.

Use of this pre-allocated internal memory pool is a key difference between
calling `Buffer.alloc(size, fill)` vs. `Buffer.allocUnsafe(size).fill(fill)`.
Specifically, `Buffer.alloc(size, fill)` will *never* use the internal Buffer
pool, while `Buffer.allocUnsafe(size).fill(fill)` *will* use the internal
Buffer pool if `size` is less than or equal to half `Buffer.poolSize`. The
difference is subtle but can be important when an application requires the
additional performance that `Buffer.allocUnsafe(size)` provides.

### Class Method: Buffer.allocUnsafeSlow(size)
<!-- YAML
added: v5.10.0
-->

* `size` {Number}

Allocates a new *non-zero-filled* and non-pooled `Buffer` of `size` bytes.  The
`size` must be less than or equal to the value of
`require('buffer').kMaxLength` (on 64-bit architectures, `kMaxLength` is
`(2^31)-1`). Otherwise, a [`RangeError`][] is thrown. A zero-length Buffer will
be created if a `size` less than or equal to 0 is specified.

The underlying memory for `Buffer` instances created in this way is *not
initialized*. The contents of the newly created `Buffer` are unknown and
*may contain sensitive data*. Use [`buf.fill(0)`][] to initialize such
`Buffer` instances to zeroes.

When using `Buffer.allocUnsafe()` to allocate new `Buffer` instances,
allocations under 4KB are, by default, sliced from a single pre-allocated
`Buffer`. This allows applications to avoid the garbage collection overhead of
creating many individually allocated Buffers. This approach improves both
performance and memory usage by eliminating the need to track and cleanup as
many `Persistent` objects.

However, in the case where a developer may need to retain a small chunk of
memory from a pool for an indeterminate amount of time, it may be appropriate
to create an un-pooled Buffer instance using `Buffer.allocUnsafeSlow()` then
copy out the relevant bits.

```js
// need to keep around a few small chunks of memory
const store = [];

socket.on('readable', () => {
  const data = socket.read();
  // allocate for retained data
  const sb = Buffer.allocUnsafeSlow(10);
  // copy the data into the new allocation
  data.copy(sb, 0, 0, 10);
  store.push(sb);
});
```

Use of `Buffer.allocUnsafeSlow()` should be used only as a last resort *after*
a developer has observed undue memory retention in their applications.

A `TypeError` will be thrown if `size` is not a number.

### All the Rest

The rest of the `Buffer` API is exactly the same as in node.js.
[See the docs](https://nodejs.org/api/buffer.html).


## Related links

- [Node.js issue: Buffer(number) is unsafe](https://github.com/nodejs/node/issues/4660)
- [Node.js Enhancement Proposal: Buffer.from/Buffer.alloc/Buffer.zalloc/Buffer() soft-deprecate](https://github.com/nodejs/node-eps/pull/4)

## Why is `Buffer` unsafe?

Today, the node.js `Buffer` constructor is overloaded to handle many different argument
types like `String`, `Array`, `Object`, `TypedArrayView` (`Uint8Array`, etc.),
`ArrayBuffer`, and also `Number`.

The API is optimized for convenience: you can throw any type at it, and it will try to do
what you want.

Because the Buffer constructor is so powerful, you often see code like this:

```js
// Convert UTF-8 strings to hex
function toHex (str) {
  return new Buffer(str).toString('hex')
}
```

***But what happens if `toHex` is called with a `Number` argument?***

### Remote Memory Disclosure

If an attacker can make your program call the `Buffer` constructor with a `Number`
argument, then they can make it allocate uninitialized memory from the node.js process.
This could potentially disclose TLS private keys, user data, or database passwords.

When the `Buffer` constructor is passed a `Number` argument, it returns an
**UNINITIALIZED** block of memory of the specified `size`. When you create a `Buffer` like
this, you **MUST** overwrite the contents before returning it to the user.

From the [node.js docs](https://nodejs.org/api/buffer.html#buffer_new_buffer_size):

> `new Buffer(size)`
>
> - `size` Number
>
> The underlying memory for `Buffer` instances created in this way is not initialized.
> **The contents of a newly created `Buffer` are unknown and could contain sensitive
> data.** Use `buf.fill(0)` to initialize a Buffer to zeroes.

(Emphasis our own.)

Whenever the programmer intended to create an uninitialized `Buffer` you often see code
like this:

```js
var buf = new Buffer(16)

// Immediately overwrite the uninitialized buffer with data from another buffer
for (var i = 0; i < buf.length; i++) {
  buf[i] = otherBuf[i]
}
```


### Would this ever be a problem in real code?

Yes. It's surprisingly common to forget to check the type of your variables in a
dynamically-typed language like JavaScript.

Usually the consequences of assuming the wrong type is that your program crashes with an
uncaught exception. But the failure mode for forgetting to check the type of arguments to
the `Buffer` constructor is more catastrophic.

Here's an example of a vulnerable service that takes a JSON payload and converts it to
hex:

```js
// Take a JSON payload {str: "some string"} and convert it to hex
var server = http.createServer(function (req, res) {
  var data = ''
  req.setEncoding('utf8')
  req.on('data', function (chunk) {
    data += chunk
  })
  req.on('end', function () {
    var body = JSON.parse(data)
    res.end(new Buffer(body.str).toString('hex'))
  })
})

server.listen(8080)
```

In this example, an http client just has to send:

```json
{
  "str": 1000
}
```

and it will get back 1,000 bytes of uninitialized memory from the server.

This is a very serious bug. It's similar in severity to the
[the Heartbleed bug](http://heartbleed.com/) that allowed disclosure of OpenSSL process
memory by remote attackers.


### Which real-world packages were vulnerable?

#### [`bittorrent-dht`](https://www.npmjs.com/package/bittorrent-dht)

[Mathias Buus](https://github.com/mafintosh) and I
([Feross Aboukhadijeh](http://feross.org/)) found this issue in one of our own packages,
[`bittorrent-dht`](https://www.npmjs.com/package/bittorrent-dht). The bug would allow
anyone on the internet to send a series of messages to a user of `bittorrent-dht` and get
them to reveal 20 bytes at a time of uninitialized memory from the node.js process.

Here's
[the commit](https://github.com/feross/bittorrent-dht/commit/6c7da04025d5633699800a99ec3fbadf70ad35b8)
that fixed it. We released a new fixed version, created a
[Node Security Project disclosure](https://nodesecurity.io/advisories/68), and deprecated all
vulnerable versions on npm so users will get a warning to upgrade to a newer version.

#### [`ws`](https://www.npmjs.com/package/ws)

That got us wondering if there were other vulnerable packages. Sure enough, within a short
period of time, we found the same issue in [`ws`](https://www.npmjs.com/package/ws), the
most popular WebSocket implementation in node.js.

If certain APIs were called with `Number` parameters instead of `String` or `Buffer` as
expected, then uninitialized server memory would be disclosed to the remote peer.

These were the vulnerable methods:

```js
socket.send(number)
socket.ping(number)
socket.pong(number)
```

Here's a vulnerable socket server with some echo functionality:

```js
server.on('connection', function (socket) {
  socket.on('message', function (message) {
    message = JSON.parse(message)
    if (message.type === 'echo') {
      socket.send(message.data) // send back the user's message
    }
  })
})
```

`socket.send(number)` called on the server, will disclose server memory.

Here's [the release](https://github.com/websockets/ws/releases/tag/1.0.1) where the issue
was fixed, with a more detailed explanation. Props to
[Arnout Kazemier](https://github.com/3rd-Eden) for the quick fix. Here's the
[Node Security Project disclosure](https://nodesecurity.io/advisories/67).


### What's the solution?

It's important that node.js offers a fast way to get memory otherwise performance-critical
applications would needlessly get a lot slower.

But we need a better way to *signal our intent* as programmers. **When we want
uninitialized memory, we should request it explicitly.**

Sensitive functionality should not be packed into a developer-friendly API that loosely
accepts many different types. This type of API encourages the lazy practice of passing
variables in without checking the type very carefully.

#### A new API: `Buffer.allocUnsafe(number)`

The functionality of creating buffers with uninitialized memory should be part of another
API. We propose `Buffer.allocUnsafe(number)`. This way, it's not part of an API that
frequently gets user input of all sorts of different types passed into it.

```js
var buf = Buffer.allocUnsafe(16) // careful, uninitialized memory!

// Immediately overwrite the uninitialized buffer with data from another buffer
for (var i = 0; i < buf.length; i++) {
  buf[i] = otherBuf[i]
}
```


### How do we fix node.js core?

We sent [a PR to node.js core](https://github.com/nodejs/node/pull/4514) (merged as
`semver-major`) which defends against one case:

```js
var str = 16
new Buffer(str, 'utf8')
```

In this situation, it's implied that the programmer intended the first argument to be a
string, since they passed an encoding as a second argument. Today, node.js will allocate
uninitialized memory in the case of `new Buffer(number, encoding)`, which is probably not
what the programmer intended.

But this is only a partial solution, since if the programmer does `new Buffer(variable)`
(without an `encoding` parameter) there's no way to know what they intended. If `variable`
is sometimes a number, then uninitialized memory will sometimes be returned.

### What's the real long-term fix?

We could deprecate and remove `new Buffer(number)` and use `Buffer.allocUnsafe(number)` when
we need uninitialized memory. But that would break 1000s of packages.

~~We believe the best solution is to:~~

~~1. Change `new Buffer(number)` to return safe, zeroed-out memory~~

~~2. Create a new API for creating uninitialized Buffers. We propose: `Buffer.allocUnsafe(number)`~~

#### Update

We now support adding three new APIs:

- `Buffer.from(value)` - convert from any type to a buffer
- `Buffer.alloc(size)` - create a zero-filled buffer
- `Buffer.allocUnsafe(size)` - create an uninitialized buffer with given size

This solves the core problem that affected `ws` and `bittorrent-dht` which is
`Buffer(variable)` getting tricked into taking a number argument.

This way, existing code continues working and the impact on the npm ecosystem will be
minimal. Over time, npm maintainers can migrate performance-critical code to use
`Buffer.allocUnsafe(number)` instead of `new Buffer(number)`.


### Conclusion

We think there's a serious design issue with the `Buffer` API as it exists today. It
promotes insecure software by putting high-risk functionality into a convenient API
with friendly "developer ergonomics".

This wasn't merely a theoretical exercise because we found the issue in some of the
most popular npm packages.

Fortunately, there's an easy fix that can be applied today. Use `safe-buffer` in place of
`buffer`.

```js
var Buffer = require('safe-buffer').Buffer
```

Eventually, we hope that node.js core can switch to this new, safer behavior. We believe
the impact on the ecosystem would be minimal since it's not a breaking change.
Well-maintained, popular packages would be updated to use `Buffer.alloc` quickly, while
older, insecure packages would magically become safe from this attack vector.


## links

- [Node.js PR: buffer: throw if both length and enc are passed](https://github.com/nodejs/node/pull/4514)
- [Node Security Project disclosure for `ws`](https://nodesecurity.io/advisories/67)
- [Node Security Project disclosure for`bittorrent-dht`](https://nodesecurity.io/advisories/68)


## credit

The original issues in `bittorrent-dht`
([disclosure](https://nodesecurity.io/advisories/68)) and
`ws` ([disclosure](https://nodesecurity.io/advisories/67)) were discovered by
[Mathias Buus](https://github.com/mafintosh) and
[Feross Aboukhadijeh](http://feross.org/).

Thanks to [Adam Baldwin](https://github.com/evilpacket) for helping disclose these issues
and for his work running the [Node Security Project](https://nodesecurity.io/).

Thanks to [John Hiesey](https://github.com/jhiesey) for proofreading this README and
auditing the code.


## license

MIT. Copyright (C) [Feross Aboukhadijeh](http://feross.org)


---

# string_decoder

***Node-core v8.9.4 string_decoder for userland***


[![NPM](https://nodei.co/npm/string_decoder.png?downloads=true&downloadRank=true)](https://nodei.co/npm/string_decoder/)
[![NPM](https://nodei.co/npm-dl/string_decoder.png?&months=6&height=3)](https://nodei.co/npm/string_decoder/)


```bash
npm install --save string_decoder
```

***Node-core string_decoder for userland***

This package is a mirror of the string_decoder implementation in Node-core.

Full documentation may be found on the [Node.js website](https://nodejs.org/dist/v8.9.4/docs/api/).

As of version 1.0.0 **string_decoder** uses semantic versioning.

## Previous versions

Previous version numbers match the versions found in Node core, e.g. 0.10.24 matches Node 0.10.24, likewise 0.11.10 matches Node 0.11.10.

## Update

The *build/* directory contains a build script that will scrape the source from the [nodejs/node](https://github.com/nodejs/node) repo given a specific Node version.

## Streams Working Group

`string_decoder` is maintained by the Streams Working Group, which
oversees the development and maintenance of the Streams API within
Node.js. The responsibilities of the Streams Working Group include:

* Addressing stream issues on the Node.js issue tracker.
* Authoring and editing stream documentation within the Node.js project.
* Reviewing changes to stream subclasses within the Node.js project.
* Redirecting changes to streams from the Node.js project to this
  project.
* Assisting in the implementation of stream providers within Node.js.
* Recommending versions of `readable-stream` to be included in Node.js.
* Messaging about the future of streams to give the community advance
  notice of changes.

See [readable-stream](https://github.com/nodejs/readable-stream) for
more details.


---

html-entities
=============

Fastest HTML entities library.

Comes with both TypeScript and Flow types.

Installation
------------

```bash
$ npm install html-entities
```

Usage
-----

### encode(text, options)

Encodes text replacing HTML special characters (`<>&"'`) and/or other character ranges depending on `mode` option value.

```js
import {encode} from 'html-entities';

encode('< > " \' & © ∆');
// -> '&lt; &gt; &quot; &apos; &amp; © ∆'

encode('< ©', {mode: 'nonAsciiPrintable'});
// -> '&lt; &copy;'

encode('< ©', {mode: 'nonAsciiPrintable', level: 'xml'});
// -> '&lt; &#169;'

encode('< > " \' & ©', {mode: 'nonAsciiPrintableOnly', level: 'xml'});
// -> '< > " \' & &#169;'
```

Options:

#### level

 * `all` alias to `html5` (default).
 * `html5` uses `HTML5` named references.
 * `html4` uses `HTML4` named references.
 * `xml` uses `XML` named references.

#### mode

 * `specialChars` encodes only HTML special characters (default).
 * `nonAscii` encodes HTML special characters and everything outside the [ASCII character range](https://en.wikipedia.org/wiki/ASCII).
 * `nonAsciiPrintable` encodes HTML special characters and everything outiside of the [ASCII printable characters](https://en.wikipedia.org/wiki/ASCII#Printable_characters).
 * `nonAsciiPrintableOnly` everything outiside of the [ASCII printable characters](https://en.wikipedia.org/wiki/ASCII#Printable_characters) keeping HTML special characters intact.
 * `extensive` encodes all non-printable characters, non-ASCII characters and all characters with named references.

#### numeric

 * `decimal` uses decimal numbers when encoding html entities. i.e. `&#169;` (default).
 * `hexadecimal` uses hexadecimal numbers when encoding html entities. i.e. `&#xa9;`.


### decode(text, options)

Decodes text replacing entities to characters. Unknown entities are left as is.

```js
import {decode} from 'html-entities';

decode('&lt; &gt; &quot; &apos; &amp; &#169; &#8710;');
// -> '< > " \' & © ∆'

decode('&copy;', {level: 'html5'});
// -> '©'

decode('&copy;', {level: 'xml'});
// -> '&copy;'
```

Options:

#### level

 * `all` alias to `html5` (default).
 * `html5` uses `HTML5` named references.
 * `html4` uses `HTML4` named references.
 * `xml` uses `XML` named references.

#### scope

 * `body` emulates behavior of browser when parsing tag bodies: entities without semicolon are also replaced (default).
 * `attribute` emulates behavior of browser when parsing tag attributes: entities without semicolon are replaced when not followed by equality sign `=`.
 * `strict` ignores entities without semicolon.

### decodeEntity(text, options)

Decodes a single HTML entity. Unknown entitiy is left as is.

```js
import {decodeEntity} from 'html-entities';

decodeEntity('&lt;');
// -> '<'

decodeEntity('&copy;', {level: 'html5'});
// -> '©'

decodeEntity('&copy;', {level: 'xml'});
// -> '&copy;'
```

Options:

#### level

 * `all` alias to `html5` (default).
 * `html5` uses `HTML5` named references.
 * `html4` uses `HTML4` named references.
 * `xml` uses `XML` named references.

Performance
-----------

Statistically significant comparison with other libraries using `benchmark.js`.
Results by this library are marked with `*`.
The source code of the benchmark is available at `benchmark/benchmark.ts`.

```
Common

    Initialization / Load speed

        #1: he x 516 ops/sec ±5.71% (78 runs sampled)
      * #2: html-entities x 407 ops/sec ±5.64% (81 runs sampled)
        #3: entities x 352 ops/sec ±4.16% (80 runs sampled)

HTML5

    Encode test

      * #1: html-entities.encode - html5, extensive x 437,236 ops/sec ±0.90% (98 runs sampled)
        #2: entities.encodeHTML x 335,714 ops/sec ±0.87% (92 runs sampled)

    Encode non-ASCII test

      * #1: html-entities.encode - html5, nonAscii x 749,246 ops/sec ±0.61% (96 runs sampled)
        #2: entities.encodeNonAsciiHTML x 706,984 ops/sec ±1.06% (98 runs sampled)
      * #3: html-entities.encode - html5, nonAsciiPrintable x 691,193 ops/sec ±4.47% (90 runs sampled)
        #4: he.encode x 141,105 ops/sec ±0.87% (92 runs sampled)

    Decode test

        #1: entities.decodeHTML x 678,595 ops/sec ±1.28% (92 runs sampled)
        #2: entities.decodeHTMLStrict x 684,372 ops/sec ±2.76% (82 runs sampled)
      * #3: html-entities.decode - html5, strict x 485,664 ops/sec ±0.80% (94 runs sampled)
      * #4: html-entities.decode - html5, body x 463,074 ops/sec ±1.11% (93 runs sampled)
      * #5: html-entities.decode - html5, attribute x 456,185 ops/sec ±2.24% (91 runs sampled)
        #6: he.decode x 302,668 ops/sec ±2.73% (90 runs sampled)

HTML4

    Encode test

      * #1: html-entities.encode - html4, nonAscii x 737,475 ops/sec ±1.04% (95 runs sampled)
      * #2: html-entities.encode - html4, nonAsciiPrintable x 649,866 ops/sec ±4.28% (79 runs sampled)
      * #3: html-entities.encode - html4, extensive x 202,337 ops/sec ±3.66% (64 runs sampled)

    Decode test

      * #1: html-entities.decode - html4, attribute x 529,674 ops/sec ±0.90% (90 runs sampled)
      * #2: html-entities.decode - html4, body x 499,135 ops/sec ±2.27% (80 runs sampled)
      * #3: html-entities.decode - html4, strict x 489,806 ops/sec ±4.37% (84 runs sampled)

XML

    Encode test

      * #1: html-entities.encode - xml, nonAscii x 823,097 ops/sec ±0.75% (81 runs sampled)
      * #2: html-entities.encode - xml, nonAsciiPrintable x 764,638 ops/sec ±0.93% (93 runs sampled)
        #3: entities.encodeXML x 672,186 ops/sec ±1.51% (92 runs sampled)
      * #4: html-entities.encode - xml, extensive x 376,870 ops/sec ±0.76% (77 runs sampled)

    Decode test

        #1: entities.decodeXML x 930,758 ops/sec ±2.90% (90 runs sampled)
      * #2: html-entities.decode - xml, body x 617,321 ops/sec ±0.74% (83 runs sampled)
      * #3: html-entities.decode - xml, attribute x 611,598 ops/sec ±0.50% (92 runs sampled)
      * #4: html-entities.decode - xml, strict x 607,191 ops/sec ±2.30% (85 runs sampled)

Escaping

    Escape test

        #1: entities.escapeUTF8 x 1,930,874 ops/sec ±0.80% (95 runs sampled)
        #2: he.escape x 1,717,522 ops/sec ±0.75% (84 runs sampled)
      * #3: html-entities.encode - xml, specialChars x 1,611,374 ops/sec ±1.30% (92 runs sampled)
        #4: entities.escape x 673,710 ops/sec ±1.30% (94 runs sampled)
```

License
-------

MIT

Security contact information
----------------------------

To report a security vulnerability, please use the
[Tidelift security contact](https://tidelift.com/security). Tidelift will
coordinate the fix and disclosure.

`html-entities` for enterprise
------------------------------

Available as part of the Tidelift Subscription

The maintainers of `html-entities` and thousands of other packages are working with
Tidelift to deliver commercial support and maintenance for the open source
dependencies you use to build your applications. Save time, reduce risk, and
improve code health, while paying the maintainers of the exact dependencies you
use.
[Learn more.](https://tidelift.com/subscription/pkg/npm-html-entities?utm_source=npm-html-entities&utm_medium=referral&utm_campaign=enterprise)


---

# html-escaper [![Build Status](https://travis-ci.org/WebReflection/html-escaper.svg?branch=master)](https://travis-ci.org/WebReflection/html-escaper) [![Coverage Status](https://coveralls.io/repos/github/WebReflection/html-escaper/badge.svg?branch=master)](https://coveralls.io/github/WebReflection/html-escaper?branch=master)
A simple module to escape/unescape common problematic entities.


### How
This package is available in npm so `npm install html-escaper` is all you need to do, using eventually the global flag too.

Once the module is present
```js
var html = require('html-escaper');

// two basic methods
html.escape('string');
html.unescape('escaped string');
```


### Why
there is basically one rule only: do not **ever** replace one char after another if you are transforming a string into another.

```js
// WARNING: THIS IS WRONG
// if you are that kind of dev that does this
function escape(s) {
  return s.replace(/&/g, "&amp;")
          .replace(/</g, "&lt;")
          .replace(/>/g, "&gt;")
          .replace(/'/g, "&#39;")
          .replace(/"/g, "&quot;");
}

// you might be the same dev that does this too
function unescape(s) {
  return s.replace(/&amp;/g, "&")
          .replace(/&lt;/g, "<")
          .replace(/&gt;/g, ">")
          .replace(/&#39;/g, "'")
          .replace(/&quot;/g, '"');
}

// guess what we have here ?
unescape('&amp;lt;');

// now guess this XSS too ...
unescape('&amp;lt;script&amp;gt;alert("yo")&amp;lt;/script&amp;gt;');


```

The last example will produce `<script>alert("yo")</script>` instead of the expected `&lt;script&gt;alert("yo")&lt;/script&gt;`.

Nothing like this could possibly happen if we grab all chars at once and either ways.
It's just a fortunate case that after swapping `&` with `&amp;` no other replace will be affected, but it's not portable and universally a bad practice.

Grab all chars at once, no excuses!



**more details**
As somebody might think it's an `unescape` issue only, it's not. Being an anti-pattern with side effects works both ways.

As example, changing the order of the replacement in escaping would produce the unexpected:
```js
function escape(s) {
  return s.replace(/</g, "&lt;")
          .replace(/>/g, "&gt;")
          .replace(/'/g, "&#39;")
          .replace(/"/g, "&quot;")
          .replace(/&/g, "&amp;");
}

escape('<'); // &amp;lt; instead of &lt;
```
If we do not want to code with the fear that the order wasn't perfect or that our order in either escaping or unescaping is different from the order another method or function used, if we understand the issue and we agree it's potentially a disaster prone approach, if we add the fact in this case creating 4 RegExp objects each time and invoking 4 times `.replace` trough the `String.prototype` is also potentially slower than creating one function only holding one object, or holding the function too, we should agree there is not absolutely any valid reason to keep proposing a char-by-char implementation.

We have proofs this approach can fail already so ... why should we risk? Just avoid and grab all chars at once or simply use this tiny utility.

### Backtick
Internt explorer < 9 has [some backtick issue](https://html5sec.org/#102)

For compatibility sake with common server-side HTML entities encoders and decoders, and in order to have the most reliable I/O, this little utility will NOT fix this IE < 9 problem.

It is also important to note that if we create valid HTML and we set attributes at runtime through this utility, backticks in strings cannot possibly affect attribute behaviors.

```js
var img = new Image();
img.src = html.escape(
  'x` `<script>alert(1)</script>"` `'
);
// it won't cause problems even in IE < 9
```

**However**, if you use `innerHTML` and you target IE < 9 then [this **might** be a problem](https://github.com/nette/nette/issues/1496).

Accordingly, if you need more chars and/or backticks to be escaped and unescaped, feel free to use alternatives like [lodash](https://github.com/lodash/lodash) or [he](https://www.npmjs.com/package/he)

Here a bit more of [my POV](https://github.com/WebReflection/html-escaper/commit/52d554fc6e8583b6ffdd357967cf71962fc07cf6#commitcomment-10625122) and why I haven't implemented same thing alternatives did. Good news: those are alternatives ;-)

---

# HTMLMinifier

[![NPM version](https://img.shields.io/npm/v/html-minifier-terser.svg)](https://www.npmjs.com/package/html-minifier-terser)
[![Build Status](https://github.com/terser/html-minifier-terser/workflows/CI/badge.svg)](https://github.com/terser/html-minifier-terser/actions?workflow=CI)

[HTMLMinifier](https://terser.org/html-minifier-terser/) is a highly **configurable**, **well-tested**, JavaScript-based HTML minifier.

## Installation

From NPM for use as a command line app:

```shell
npm install html-minifier-terser -g
```

From NPM for programmatic use:

```shell
npm install html-minifier-terser
```

## Usage

**Note** that almost all options are disabled by default. Experiment and find what works best for you and your project.

For command line usage please see `html-minifier-terser --help` for a list of available options.

**Sample command line:**

```bash
html-minifier-terser --collapse-whitespace --remove-comments --minify-js true
```

### Node.js

```js
const { minify } = require('html-minifier-terser');

const result = await minify('<p title="blah" id="moo">foo</p>', {
  removeAttributeQuotes: true,
});
result; // '<p title=blah id=moo>foo</p>'
```

See [corresponding blog post](http://perfectionkills.com/experimenting-with-html-minifier) for all the gory details of [how it works](http://perfectionkills.com/experimenting-with-html-minifier#how_it_works), [description of each option](http://perfectionkills.com/experimenting-with-html-minifier#options), [testing results](http://perfectionkills.com/experimenting-with-html-minifier#field_testing) and [conclusions](http://perfectionkills.com/experimenting-with-html-minifier#cost_and_benefits).

Also see corresponding [Ruby wrapper](https://github.com/stereobooster/html_minifier), and for Node.js, [Grunt plugin](https://github.com/gruntjs/grunt-contrib-htmlmin), [Gulp plugin](https://github.com/pioug/gulp-html-minifier-terser), [Koa middleware wrapper](https://github.com/koajs/html-minifier) and [Express middleware wrapper](https://github.com/melonmanchan/express-minify-html).

For lint-like capabilities take a look at [HTMLLint](https://github.com/kangax/html-lint).

## Minification comparison

How does HTMLMinifier compare to other solutions — [HTML Minifier from Will Peavy](http://www.willpeavy.com/minifier/) (1st result in [Google search for "html minifier"](https://www.google.com/#q=html+minifier)) as well as [htmlcompressor.com](http://htmlcompressor.com) and [minimize](https://github.com/Swaagie/minimize)?

| Site                                                                         | Original size *(KB)* | HTMLMinifier | minimize | Will Peavy | htmlcompressor.com |
| ---------------------------------------------------------------------------- |:--------------------:| ------------:| --------:| ----------:| ------------------:|
| [Google](https://www.google.com/)                                            | 52                   | **48**       | 52       | 54         | n/a                |
| [Stack Overflow](https://stackoverflow.com/)                                 | 177                  | **143**      | 154      | 154        | n/a                |
| [HTMLMinifier](https://github.com/kangax/html-minifier)                      | 252                  | **171**      | 230      | 250        | n/a                |
| [Bootstrap CSS](https://getbootstrap.com/docs/3.3/css/)                      | 271                  | **260**      | 269      | 229        | n/a                |
| [BBC](https://www.bbc.co.uk/)                                                | 355                  | **324**      | 353      | 344        | n/a                |
| [Amazon](https://www.amazon.co.uk/)                                          | 466                  | **430**      | 456      | 474        | n/a                |
| [Twitter](https://twitter.com/)                                              | 469                  | **394**      | 462      | 513        | n/a                |
| [Wikipedia](https://en.wikipedia.org/wiki/President_of_the_United_States)    | 703                  | **569**      | 682      | 708        | n/a                |
| [Eloquent Javascript](https://eloquentjavascript.net/1st_edition/print.html) | 870                  | **815**      | 840      | 864        | n/a                |
| [NBC](https://www.nbc.com/)                                                  | 1701                 | **1566**     | 1689     | 1705       | n/a                |
| [New York Times](https://www.nytimes.com/)                                   | 1731                 | **1583**     | 1726     | 1680       | n/a                |
| [ES draft](https://tc39.github.io/ecma262/)                                  | 6296                 | **5538**     | 5733     | n/a        | n/a                |

## Options Quick Reference

Most of the options are disabled by default.

| Option                         | Description     | Default |
|--------------------------------|-----------------|---------|
| `caseSensitive`                | Treat attributes in case sensitive manner (useful for custom HTML tags) | `false` |
| `collapseBooleanAttributes`    | [Omit attribute values from boolean attributes](http://perfectionkills.com/experimenting-with-html-minifier#collapse_boolean_attributes) | `false` |
| `collapseInlineTagWhitespace`  | Don't leave any spaces between `display:inline;` elements when collapsing. Must be used in conjunction with `collapseWhitespace=true` | `false` |
| `collapseWhitespace`           | [Collapse white space that contributes to text nodes in a document tree](http://perfectionkills.com/experimenting-with-html-minifier#collapse_whitespace) | `false` |
| `conservativeCollapse`         | Always collapse to 1 space (never remove it entirely). Must be used in conjunction with `collapseWhitespace=true` | `false` |
| `continueOnParseError`         | [Handle parse errors](https://html.spec.whatwg.org/multipage/parsing.html#parse-errors) instead of aborting. | `false` |
| `customAttrAssign`             | Arrays of regex'es that allow to support custom attribute assign expressions (e.g. `'<div flex?="{{mode != cover}}"></div>'`) | `[ ]` |
| `customAttrCollapse`           | Regex that specifies custom attribute to strip newlines from (e.g. `/ng-class/`) | |
| `customAttrSurround`           | Arrays of regex'es that allow to support custom attribute surround expressions (e.g. `<input {{#if value}}checked="checked"{{/if}}>`) | `[ ]` |
| `customEventAttributes`        | Arrays of regex'es that allow to support custom event attributes for `minifyJS` (e.g. `ng-click`) | `[ /^on[a-z]{3,}$/ ]` |
| `decodeEntities`               | Use direct Unicode characters whenever possible | `false` |
| `html5`                        | Parse input according to HTML5 specifications | `true` |
| `ignoreCustomComments`         | Array of regex'es that allow to ignore certain comments, when matched | `[ /^!/, /^\s*#/ ]` |
| `ignoreCustomFragments`        | Array of regex'es that allow to ignore certain fragments, when matched (e.g. `<?php ... ?>`, `{{ ... }}`, etc.)  | `[ /<%[\s\S]*?%>/, /<\?[\s\S]*?\?>/ ]` |
| `includeAutoGeneratedTags`     | Insert tags generated by HTML parser | `true` |
| `keepClosingSlash`             | Keep the trailing slash on singleton elements | `false` |
| `maxLineLength`                | Specify a maximum line length. Compressed output will be split by newlines at valid HTML split-points |
| `minifyCSS`                    | Minify CSS in style elements and style attributes (uses [clean-css](https://github.com/jakubpawlowicz/clean-css)) | `false` (could be `true`, `Object`, `Function(text, type)`) |
| `minifyJS`                     | Minify JavaScript in script elements and event attributes (uses [Terser](https://github.com/terser/terser)) | `false` (could be `true`, `Object`, `Function(text, inline)`) |
| `minifyURLs`                   | Minify URLs in various attributes (uses [relateurl](https://github.com/stevenvachon/relateurl)) | `false` (could be `String`, `Object`, `Function(text)`) |
| `noNewlinesBeforeTagClose`     | Never add a newline before a tag that closes an element | `false` |
| `preserveLineBreaks`           | Always collapse to 1 line break (never remove it entirely) when whitespace between tags include a line break. Must be used in conjunction with `collapseWhitespace=true` | `false` |
| `preventAttributesEscaping`    | Prevents the escaping of the values of attributes | `false` |
| `processConditionalComments`   | Process contents of conditional comments through minifier | `false` |
| `processScripts`               | Array of strings corresponding to types of script elements to process through minifier (e.g. `text/ng-template`, `text/x-handlebars-template`, etc.) | `[ ]` |
| `quoteCharacter`               | Type of quote to use for attribute values (' or ") | |
| `removeAttributeQuotes`        | [Remove quotes around attributes when possible](http://perfectionkills.com/experimenting-with-html-minifier#remove_attribute_quotes) | `false` |
| `removeComments`               | [Strip HTML comments](http://perfectionkills.com/experimenting-with-html-minifier#remove_comments) | `false` |
| `removeEmptyAttributes`        | [Remove all attributes with whitespace-only values](http://perfectionkills.com/experimenting-with-html-minifier#remove_empty_or_blank_attributes) | `false` (could be `true`, `Function(attrName, tag)`) |
| `removeEmptyElements`          | [Remove all elements with empty contents](http://perfectionkills.com/experimenting-with-html-minifier#remove_empty_elements) | `false` |
| `removeOptionalTags`           | [Remove optional tags](http://perfectionkills.com/experimenting-with-html-minifier#remove_optional_tags) | `false` |
| `removeRedundantAttributes`    | [Remove attributes when value matches default.](http://perfectionkills.com/experimenting-with-html-minifier#remove_redundant_attributes) | `false` |
| `removeScriptTypeAttributes`   | Remove `type="text/javascript"` from `script` tags. Other `type` attribute values are left intact | `false` |
| `removeStyleLinkTypeAttributes`| Remove `type="text/css"` from `style` and `link` tags. Other `type` attribute values are left intact | `false` |
| `removeTagWhitespace`          | Remove space between attributes whenever possible. **Note that this will result in invalid HTML!** | `false` |
| `sortAttributes`               | [Sort attributes by frequency](#sorting-attributes--style-classes) | `false` |
| `sortClassName`                | [Sort style classes by frequency](#sorting-attributes--style-classes) | `false` |
| `trimCustomFragments`          | Trim white space around `ignoreCustomFragments`. | `false` |
| `useShortDoctype`              | [Replaces the `doctype` with the short (HTML5) doctype](http://perfectionkills.com/experimenting-with-html-minifier#use_short_doctype) | `false` |

### Sorting attributes / style classes

Minifier options like `sortAttributes` and `sortClassName` won't impact the plain-text size of the output. However, they form long repetitive chains of characters that should improve compression ratio of gzip used in HTTP compression.

## Special cases

### Ignoring chunks of markup

If you have chunks of markup you would like preserved, you can wrap them `<!-- htmlmin:ignore -->`.

### Minifying JSON-LD

You can minify script tags with JSON-LD by setting the option `{ processScripts: ['application/ld+json'] }`. Note that this minification is very rudimentary, it is mainly useful for removing newlines and excessive whitespace. 

### Preserving SVG tags

SVG tags are automatically recognized, and when they are minified, both case-sensitivity and closing-slashes are preserved, regardless of the minification settings used for the rest of the file.

### Working with invalid markup

HTMLMinifier **can't work with invalid or partial chunks of markup**. This is because it parses markup into a tree structure, then modifies it (removing anything that was specified for removal, ignoring anything that was specified to be ignored, etc.), then it creates a markup out of that tree and returns it.

Input markup (e.g. `<p id="">foo`)

↓

Internal representation of markup in a form of tree (e.g. `{ tag: "p", attr: "id", children: ["foo"] }`)

↓

Transformation of internal representation (e.g. removal of `id` attribute)

↓

Output of resulting markup (e.g. `<p>foo</p>`)

HTMLMinifier can't know that original markup was only half of the tree; it does its best to try to parse it as a full tree and it loses information about tree being malformed or partial in the beginning. As a result, it can't create a partial/malformed tree at the time of the output.

## Running benchmarks

Benchmarks for minified HTML:

```shell
cd benchmarks
npm install
npm run benchmark
```

## Running local server

```shell
npm run serve
```


---

# Commander.js

[![Build Status](https://github.com/tj/commander.js/workflows/build/badge.svg)](https://github.com/tj/commander.js/actions?query=workflow%3A%22build%22)
[![NPM Version](http://img.shields.io/npm/v/commander.svg?style=flat)](https://www.npmjs.org/package/commander)
[![NPM Downloads](https://img.shields.io/npm/dm/commander.svg?style=flat)](https://npmcharts.com/compare/commander?minimal=true)
[![Install Size](https://packagephobia.now.sh/badge?p=commander)](https://packagephobia.now.sh/result?p=commander)

The complete solution for [node.js](http://nodejs.org) command-line interfaces.

Read this in other languages: English | [简体中文](./Readme_zh-CN.md)

- [Commander.js](#commanderjs)
  - [Installation](#installation)
  - [Quick Start](#quick-start)
  - [Declaring _program_ variable](#declaring-program-variable)
  - [Options](#options)
    - [Common option types, boolean and value](#common-option-types-boolean-and-value)
    - [Default option value](#default-option-value)
    - [Other option types, negatable boolean and boolean|value](#other-option-types-negatable-boolean-and-booleanvalue)
    - [Required option](#required-option)
    - [Variadic option](#variadic-option)
    - [Version option](#version-option)
    - [More configuration](#more-configuration)
    - [Custom option processing](#custom-option-processing)
  - [Commands](#commands)
    - [Command-arguments](#command-arguments)
      - [More configuration](#more-configuration-1)
      - [Custom argument processing](#custom-argument-processing)
    - [Action handler](#action-handler)
    - [Stand-alone executable (sub)commands](#stand-alone-executable-subcommands)
    - [Life cycle hooks](#life-cycle-hooks)
  - [Automated help](#automated-help)
    - [Custom help](#custom-help)
    - [Display help after errors](#display-help-after-errors)
    - [Display help from code](#display-help-from-code)
    - [.name](#name)
    - [.usage](#usage)
    - [.description and .summary](#description-and-summary)
    - [.helpOption(flags, description)](#helpoptionflags-description)
    - [.addHelpCommand()](#addhelpcommand)
    - [More configuration](#more-configuration-2)
  - [Custom event listeners](#custom-event-listeners)
  - [Bits and pieces](#bits-and-pieces)
    - [.parse() and .parseAsync()](#parse-and-parseasync)
    - [Parsing Configuration](#parsing-configuration)
    - [Legacy options as properties](#legacy-options-as-properties)
    - [TypeScript](#typescript)
    - [createCommand()](#createcommand)
    - [Node options such as `--harmony`](#node-options-such-as---harmony)
    - [Debugging stand-alone executable subcommands](#debugging-stand-alone-executable-subcommands)
    - [Display error](#display-error)
    - [Override exit and output handling](#override-exit-and-output-handling)
    - [Additional documentation](#additional-documentation)
  - [Support](#support)
    - [Commander for enterprise](#commander-for-enterprise)

For information about terms used in this document see: [terminology](./docs/terminology.md)

## Installation

```sh
npm install commander
```

## Quick Start

You write code to describe your command line interface.
Commander looks after parsing the arguments into options and command-arguments,
displays usage errors for problems, and implements a help system.

Commander is strict and displays an error for unrecognised options.
The two most used option types are a boolean option, and an option which takes its value from the following argument.

Example file: [split.js](./examples/split.js)

```js
const { program } = require('commander');

program
  .option('--first')
  .option('-s, --separator <char>');

program.parse();

const options = program.opts();
const limit = options.first ? 1 : undefined;
console.log(program.args[0].split(options.separator, limit));
```

```console
$ node split.js -s / --fits a/b/c
error: unknown option '--fits'
(Did you mean --first?)
$ node split.js -s / --first a/b/c
[ 'a' ]
```

Here is a more complete program using a subcommand and with descriptions for the help. In a multi-command program, you have an action handler for each command (or stand-alone executables for the commands).

Example file: [string-util.js](./examples/string-util.js)

```js
const { Command } = require('commander');
const program = new Command();

program
  .name('string-util')
  .description('CLI to some JavaScript string utilities')
  .version('0.8.0');

program.command('split')
  .description('Split a string into substrings and display as an array')
  .argument('<string>', 'string to split')
  .option('--first', 'display just the first substring')
  .option('-s, --separator <char>', 'separator character', ',')
  .action((str, options) => {
    const limit = options.first ? 1 : undefined;
    console.log(str.split(options.separator, limit));
  });

program.parse();
```

```console
$ node string-util.js help split
Usage: string-util split [options] <string>

Split a string into substrings and display as an array.

Arguments:
  string                  string to split

Options:
  --first                 display just the first substring
  -s, --separator <char>  separator character (default: ",")
  -h, --help              display help for command

$ node string-util.js split --separator=/ a/b/c
[ 'a', 'b', 'c' ]
```

More samples can be found in the [examples](https://github.com/tj/commander.js/tree/master/examples) directory.

## Declaring _program_ variable

Commander exports a global object which is convenient for quick programs.
This is used in the examples in this README for brevity.

```js
// CommonJS (.cjs)
const { program } = require('commander');
```

For larger programs which may use commander in multiple ways, including unit testing, it is better to create a local Command object to use.

```js
// CommonJS (.cjs)
const { Command } = require('commander');
const program = new Command();
```

```js
// ECMAScript (.mjs)
import { Command } from 'commander';
const program = new Command();
```

```ts
// TypeScript (.ts)
import { Command } from 'commander';
const program = new Command();
```

## Options

Options are defined with the `.option()` method, also serving as documentation for the options. Each option can have a short flag (single character) and a long name, separated by a comma or space or vertical bar ('|').

The parsed options can be accessed by calling `.opts()` on a `Command` object, and are passed to the action handler.

Multi-word options such as "--template-engine" are camel-cased, becoming `program.opts().templateEngine` etc.

An option and its option-argument can be separated by a space, or combined into the same argument. The option-argument can follow the short option directly or follow an `=` for a long option.

```sh
serve -p 80
serve -p80
serve --port 80
serve --port=80
```

You can use `--` to indicate the end of the options, and any remaining arguments will be used without being interpreted.

By default options on the command line are not positional, and can be specified before or after other arguments.

There are additional related routines for when `.opts()` is not enough:

- `.optsWithGlobals()` returns merged local and global option values
- `.getOptionValue()` and `.setOptionValue()` work with a single option value
- `.getOptionValueSource()` and `.setOptionValueWithSource()` include where the option value came from

### Common option types, boolean and value

The two most used option types are a boolean option, and an option which takes its value
from the following argument (declared with angle brackets like `--expect <value>`). Both are `undefined` unless specified on command line.

Example file: [options-common.js](./examples/options-common.js)

```js
program
  .option('-d, --debug', 'output extra debugging')
  .option('-s, --small', 'small pizza size')
  .option('-p, --pizza-type <type>', 'flavour of pizza');

program.parse(process.argv);

const options = program.opts();
if (options.debug) console.log(options);
console.log('pizza details:');
if (options.small) console.log('- small pizza size');
if (options.pizzaType) console.log(`- ${options.pizzaType}`);
```

```console
$ pizza-options -p
error: option '-p, --pizza-type <type>' argument missing
$ pizza-options -d -s -p vegetarian
{ debug: true, small: true, pizzaType: 'vegetarian' }
pizza details:
- small pizza size
- vegetarian
$ pizza-options --pizza-type=cheese
pizza details:
- cheese
```

Multiple boolean short options may be combined together following the dash, and may be followed by a single short option taking a value.
For example `-d -s -p cheese` may be written as `-ds -p cheese` or even `-dsp cheese`.

Options with an expected option-argument are greedy and will consume the following argument whatever the value.
So `--id -xyz` reads `-xyz` as the option-argument.

`program.parse(arguments)` processes the arguments, leaving any args not consumed by the program options in the `program.args` array. The parameter is optional and defaults to `process.argv`.

### Default option value

You can specify a default value for an option.

Example file: [options-defaults.js](./examples/options-defaults.js)

```js
program
  .option('-c, --cheese <type>', 'add the specified type of cheese', 'blue');

program.parse();

console.log(`cheese: ${program.opts().cheese}`);
```

```console
$ pizza-options
cheese: blue
$ pizza-options --cheese stilton
cheese: stilton
```

### Other option types, negatable boolean and boolean|value

You can define a boolean option long name with a leading `no-` to set the option value to false when used.
Defined alone this also makes the option true by default.

If you define `--foo` first, adding `--no-foo` does not change the default value from what it would
otherwise be.

Example file: [options-negatable.js](./examples/options-negatable.js)

```js
program
  .option('--no-sauce', 'Remove sauce')
  .option('--cheese <flavour>', 'cheese flavour', 'mozzarella')
  .option('--no-cheese', 'plain with no cheese')
  .parse();

const options = program.opts();
const sauceStr = options.sauce ? 'sauce' : 'no sauce';
const cheeseStr = (options.cheese === false) ? 'no cheese' : `${options.cheese} cheese`;
console.log(`You ordered a pizza with ${sauceStr} and ${cheeseStr}`);
```

```console
$ pizza-options
You ordered a pizza with sauce and mozzarella cheese
$ pizza-options --sauce
error: unknown option '--sauce'
$ pizza-options --cheese=blue
You ordered a pizza with sauce and blue cheese
$ pizza-options --no-sauce --no-cheese
You ordered a pizza with no sauce and no cheese
```

You can specify an option which may be used as a boolean option but may optionally take an option-argument
(declared with square brackets like `--optional [value]`).

Example file: [options-boolean-or-value.js](./examples/options-boolean-or-value.js)

```js
program
  .option('-c, --cheese [type]', 'Add cheese with optional type');

program.parse(process.argv);

const options = program.opts();
if (options.cheese === undefined) console.log('no cheese');
else if (options.cheese === true) console.log('add cheese');
else console.log(`add cheese type ${options.cheese}`);
```

```console
$ pizza-options
no cheese
$ pizza-options --cheese
add cheese
$ pizza-options --cheese mozzarella
add cheese type mozzarella
```

Options with an optional option-argument are not greedy and will ignore arguments starting with a dash.
So `id` behaves as a boolean option for `--id -5`, but you can use a combined form if needed like `--id=-5`.

For information about possible ambiguous cases, see [options taking varying arguments](./docs/options-taking-varying-arguments.md).

### Required option

You may specify a required (mandatory) option using `.requiredOption()`. The option must have a value after parsing, usually specified on the command line, or perhaps from a default value (say from environment). The method is otherwise the same as `.option()` in format, taking flags and description, and optional default value or custom processing.

Example file: [options-required.js](./examples/options-required.js)

```js
program
  .requiredOption('-c, --cheese <type>', 'pizza must have cheese');

program.parse();
```

```console
$ pizza
error: required option '-c, --cheese <type>' not specified
```

### Variadic option

You may make an option variadic by appending `...` to the value placeholder when declaring the option. On the command line you
can then specify multiple option-arguments, and the parsed option value will be an array. The extra arguments
are read until the first argument starting with a dash. The special argument `--` stops option processing entirely. If a value
is specified in the same argument as the option then no further values are read.

Example file: [options-variadic.js](./examples/options-variadic.js)

```js
program
  .option('-n, --number <numbers...>', 'specify numbers')
  .option('-l, --letter [letters...]', 'specify letters');

program.parse();

console.log('Options: ', program.opts());
console.log('Remaining arguments: ', program.args);
```

```console
$ collect -n 1 2 3 --letter a b c
Options:  { number: [ '1', '2', '3' ], letter: [ 'a', 'b', 'c' ] }
Remaining arguments:  []
$ collect --letter=A -n80 operand
Options:  { number: [ '80' ], letter: [ 'A' ] }
Remaining arguments:  [ 'operand' ]
$ collect --letter -n 1 -n 2 3 -- operand
Options:  { number: [ '1', '2', '3' ], letter: true }
Remaining arguments:  [ 'operand' ]
```

For information about possible ambiguous cases, see [options taking varying arguments](./docs/options-taking-varying-arguments.md).

### Version option

The optional `version` method adds handling for displaying the command version. The default option flags are `-V` and `--version`, and when present the command prints the version number and exits.

```js
program.version('0.0.1');
```

```console
$ ./examples/pizza -V
0.0.1
```

You may change the flags and description by passing additional parameters to the `version` method, using
the same syntax for flags as the `option` method.

```js
program.version('0.0.1', '-v, --vers', 'output the current version');
```

### More configuration

You can add most options using the `.option()` method, but there are some additional features available
by constructing an `Option` explicitly for less common cases.

Example files: [options-extra.js](./examples/options-extra.js), [options-env.js](./examples/options-env.js), [options-conflicts.js](./examples/options-conflicts.js), [options-implies.js](./examples/options-implies.js)

```js
program
  .addOption(new Option('-s, --secret').hideHelp())
  .addOption(new Option('-t, --timeout <delay>', 'timeout in seconds').default(60, 'one minute'))
  .addOption(new Option('-d, --drink <size>', 'drink size').choices(['small', 'medium', 'large']))
  .addOption(new Option('-p, --port <number>', 'port number').env('PORT'))
  .addOption(new Option('--donate [amount]', 'optional donation in dollars').preset('20').argParser(parseFloat))
  .addOption(new Option('--disable-server', 'disables the server').conflicts('port'))
  .addOption(new Option('--free-drink', 'small drink included free ').implies({ drink: 'small' }));
```

```console
$ extra --help
Usage: help [options]

Options:
  -t, --timeout <delay>  timeout in seconds (default: one minute)
  -d, --drink <size>     drink cup size (choices: "small", "medium", "large")
  -p, --port <number>    port number (env: PORT)
  --donate [amount]      optional donation in dollars (preset: "20")
  --disable-server       disables the server
  --free-drink           small drink included free
  -h, --help             display help for command

$ extra --drink huge
error: option '-d, --drink <size>' argument 'huge' is invalid. Allowed choices are small, medium, large.

$ PORT=80 extra --donate --free-drink
Options:  { timeout: 60, donate: 20, port: '80', freeDrink: true, drink: 'small' }

$ extra --disable-server --port 8000
error: option '--disable-server' cannot be used with option '-p, --port <number>'
```

Specify a required (mandatory) option using the `Option` method `.makeOptionMandatory()`. This matches the `Command` method [.requiredOption()](#required-option).

### Custom option processing

You may specify a function to do custom processing of option-arguments. The callback function receives two parameters,
the user specified option-argument and the previous value for the option. It returns the new value for the option.

This allows you to coerce the option-argument to the desired type, or accumulate values, or do entirely custom processing.

You can optionally specify the default/starting value for the option after the function parameter.

Example file: [options-custom-processing.js](./examples/options-custom-processing.js)

```js
function myParseInt(value, dummyPrevious) {
  // parseInt takes a string and a radix
  const parsedValue = parseInt(value, 10);
  if (isNaN(parsedValue)) {
    throw new commander.InvalidArgumentError('Not a number.');
  }
  return parsedValue;
}

function increaseVerbosity(dummyValue, previous) {
  return previous + 1;
}

function collect(value, previous) {
  return previous.concat([value]);
}

function commaSeparatedList(value, dummyPrevious) {
  return value.split(',');
}

program
  .option('-f, --float <number>', 'float argument', parseFloat)
  .option('-i, --integer <number>', 'integer argument', myParseInt)
  .option('-v, --verbose', 'verbosity that can be increased', increaseVerbosity, 0)
  .option('-c, --collect <value>', 'repeatable value', collect, [])
  .option('-l, --list <items>', 'comma separated list', commaSeparatedList)
;

program.parse();

const options = program.opts();
if (options.float !== undefined) console.log(`float: ${options.float}`);
if (options.integer !== undefined) console.log(`integer: ${options.integer}`);
if (options.verbose > 0) console.log(`verbosity: ${options.verbose}`);
if (options.collect.length > 0) console.log(options.collect);
if (options.list !== undefined) console.log(options.list);
```

```console
$ custom -f 1e2
float: 100
$ custom --integer 2
integer: 2
$ custom -v -v -v
verbose: 3
$ custom -c a -c b -c c
[ 'a', 'b', 'c' ]
$ custom --list x,y,z
[ 'x', 'y', 'z' ]
```

## Commands

You can specify (sub)commands using `.command()` or `.addCommand()`. There are two ways these can be implemented: using an action handler attached to the command, or as a stand-alone executable file (described in more detail later). The subcommands may be nested ([example](./examples/nestedCommands.js)).

In the first parameter to `.command()` you specify the command name. You may append the command-arguments after the command name, or specify them separately using `.argument()`. The arguments may be `<required>` or `[optional]`, and the last argument may also be `variadic...`.

You can use `.addCommand()` to add an already configured subcommand to the program.

For example:

```js
// Command implemented using action handler (description is supplied separately to `.command`)
// Returns new command for configuring.
program
  .command('clone <source> [destination]')
  .description('clone a repository into a newly created directory')
  .action((source, destination) => {
    console.log('clone command called');
  });

// Command implemented using stand-alone executable file, indicated by adding description as second parameter to `.command`.
// Returns `this` for adding more commands.
program
  .command('start <service>', 'start named service')
  .command('stop [service]', 'stop named service, or all if no name supplied');

// Command prepared separately.
// Returns `this` for adding more commands.
program
  .addCommand(build.makeBuildCommand());
```

Configuration options can be passed with the call to `.command()` and `.addCommand()`. Specifying `hidden: true` will
remove the command from the generated help output. Specifying `isDefault: true` will run the subcommand if no other
subcommand is specified ([example](./examples/defaultCommand.js)).

You can add alternative names for a command with `.alias()`. ([example](./examples/alias.js))

For safety, `.addCommand()` does not automatically copy the inherited settings from the parent command. There is a helper routine `.copyInheritedSettings()` for copying the settings when they are wanted.

### Command-arguments

For subcommands, you can specify the argument syntax in the call to `.command()` (as shown above). This
is the only method usable for subcommands implemented using a stand-alone executable, but for other subcommands
you can instead use the following method.

To configure a command, you can use `.argument()` to specify each expected command-argument.
You supply the argument name and an optional description. The argument may be `<required>` or `[optional]`.
You can specify a default value for an optional command-argument.

Example file: [argument.js](./examples/argument.js)

```js
program
  .version('0.1.0')
  .argument('<username>', 'user to login')
  .argument('[password]', 'password for user, if required', 'no password given')
  .action((username, password) => {
    console.log('username:', username);
    console.log('password:', password);
  });
```

 The last argument of a command can be variadic, and only the last argument.  To make an argument variadic you
 append `...` to the argument name. A variadic argument is passed to the action handler as an array. For example:

```js
program
  .version('0.1.0')
  .command('rmdir')
  .argument('<dirs...>')
  .action(function (dirs) {
    dirs.forEach((dir) => {
      console.log('rmdir %s', dir);
    });
  });
```

There is a convenience method to add multiple arguments at once, but without descriptions:

```js
program
  .arguments('<username> <password>');
```

#### More configuration

There are some additional features available by constructing an `Argument` explicitly for less common cases.

Example file: [arguments-extra.js](./examples/arguments-extra.js)

```js
program
  .addArgument(new commander.Argument('<drink-size>', 'drink cup size').choices(['small', 'medium', 'large']))
  .addArgument(new commander.Argument('[timeout]', 'timeout in seconds').default(60, 'one minute'))
```

#### Custom argument processing

You may specify a function to do custom processing of command-arguments (like for option-arguments).
The callback function receives two parameters, the user specified command-argument and the previous value for the argument.
It returns the new value for the argument.

The processed argument values are passed to the action handler, and saved as `.processedArgs`.

You can optionally specify the default/starting value for the argument after the function parameter.

Example file: [arguments-custom-processing.js](./examples/arguments-custom-processing.js)

```js
program
  .command('add')
  .argument('<first>', 'integer argument', myParseInt)
  .argument('[second]', 'integer argument', myParseInt, 1000)
  .action((first, second) => {
    console.log(`${first} + ${second} = ${first + second}`);
  })
;
```

### Action handler

The action handler gets passed a parameter for each command-argument you declared, and two additional parameters
which are the parsed options and the command object itself.

Example file: [thank.js](./examples/thank.js)

```js
program
  .argument('<name>')
  .option('-t, --title <honorific>', 'title to use before name')
  .option('-d, --debug', 'display some debugging')
  .action((name, options, command) => {
    if (options.debug) {
      console.error('Called %s with options %o', command.name(), options);
    }
    const title = options.title ? `${options.title} ` : '';
    console.log(`Thank-you ${title}${name}`);
  });
```

If you prefer, you can work with the command directly and skip declaring the parameters for the action handler. The `this` keyword is set to the running command and can be used from a function expression (but not from an arrow function).

Example file: [action-this.js](./examples/action-this.js)

```js
program
  .command('serve')
  .argument('<script>')
  .option('-p, --port <number>', 'port number', 80)
  .action(function() {
    console.error('Run script %s on port %s', this.args[0], this.opts().port);
  });
```

You may supply an `async` action handler, in which case you call `.parseAsync` rather than `.parse`.

```js
async function run() { /* code goes here */ }

async function main() {
  program
    .command('run')
    .action(run);
  await program.parseAsync(process.argv);
}
```

A command's options and arguments on the command line are validated when the command is used. Any unknown options or missing arguments will be reported as an error. You can suppress the unknown option checks with `.allowUnknownOption()`. By default it is not an error to
pass more arguments than declared, but you can make this an error with `.allowExcessArguments(false)`.

### Stand-alone executable (sub)commands

When `.command()` is invoked with a description argument, this tells Commander that you're going to use stand-alone executables for subcommands.
Commander will search the files in the directory of the entry script for a file with the name combination `command-subcommand`, like `pm-install` or `pm-search` in the example below. The search includes trying common file extensions, like `.js`.
You may specify a custom name (and path) with the `executableFile` configuration option.
You may specify a custom search directory for subcommands with `.executableDir()`.

You handle the options for an executable (sub)command in the executable, and don't declare them at the top-level.

Example file: [pm](./examples/pm)

```js
program
  .name('pm')
  .version('0.1.0')
  .command('install [name]', 'install one or more packages')
  .command('search [query]', 'search with optional query')
  .command('update', 'update installed packages', { executableFile: 'myUpdateSubCommand' })
  .command('list', 'list packages installed', { isDefault: true });

program.parse(process.argv);
```

If the program is designed to be installed globally, make sure the executables have proper modes, like `755`.

### Life cycle hooks

You can add callback hooks to a command for life cycle events.

Example file: [hook.js](./examples/hook.js)

```js
program
  .option('-t, --trace', 'display trace statements for commands')
  .hook('preAction', (thisCommand, actionCommand) => {
    if (thisCommand.opts().trace) {
      console.log(`About to call action handler for subcommand: ${actionCommand.name()}`);
      console.log('arguments: %O', actionCommand.args);
      console.log('options: %o', actionCommand.opts());
    }
  });
```

The callback hook can be `async`, in which case you call `.parseAsync` rather than `.parse`. You can add multiple hooks per event.

The supported events are:

| event name | when hook called | callback parameters |
| :-- | :-- | :-- |
| `preAction`, `postAction` |  before/after action handler for this command and its nested subcommands |   `(thisCommand, actionCommand)` |
| `preSubcommand` | before parsing direct subcommand  | `(thisCommand, subcommand)` |

For an overview of the life cycle events see [parsing life cycle and hooks](./docs/parsing-and-hooks.md).

## Automated help

The help information is auto-generated based on the information commander already knows about your program. The default
help option is `-h,--help`.

Example file: [pizza](./examples/pizza)

```console
$ node ./examples/pizza --help
Usage: pizza [options]

An application for pizza ordering

Options:
  -p, --peppers        Add peppers
  -c, --cheese <type>  Add the specified type of cheese (default: "marble")
  -C, --no-cheese      You do not want any cheese
  -h, --help           display help for command
```

A `help` command is added by default if your command has subcommands. It can be used alone, or with a subcommand name to show
further help for the subcommand. These are effectively the same if the `shell` program has implicit help:

```sh
shell help
shell --help

shell help spawn
shell spawn --help
```

Long descriptions are wrapped to fit the available width. (However, a  description that includes a line-break followed by whitespace is assumed to be pre-formatted and not wrapped.)

### Custom help

You can add extra text to be displayed along with the built-in help.

Example file: [custom-help](./examples/custom-help)

```js
program
  .option('-f, --foo', 'enable some foo');

program.addHelpText('after', `

Example call:
  $ custom-help --help`);
```

Yields the following help output:

```Text
Usage: custom-help [options]

Options:
  -f, --foo   enable some foo
  -h, --help  display help for command

Example call:
  $ custom-help --help
```

The positions in order displayed are:

- `beforeAll`: add to the program for a global banner or header
- `before`: display extra information before built-in help
- `after`: display extra information after built-in help
- `afterAll`: add to the program for a global footer (epilog)

The positions "beforeAll" and "afterAll" apply to the command and all its subcommands.

The second parameter can be a string, or a function returning a string. The function is passed a context object for your convenience. The properties are:

- error: a boolean for whether the help is being displayed due to a usage error
- command: the Command which is displaying the help

### Display help after errors

The default behaviour for usage errors is to just display a short error message.
You can change the behaviour to show the full help or a custom help message after an error.

```js
program.showHelpAfterError();
// or
program.showHelpAfterError('(add --help for additional information)');
```

```console
$ pizza --unknown
error: unknown option '--unknown'
(add --help for additional information)
```

The default behaviour is to suggest correct spelling after an error for an unknown command or option. You
can disable this.

```js
program.showSuggestionAfterError(false);
```

```console
$ pizza --hepl
error: unknown option '--hepl'
(Did you mean --help?)
```

### Display help from code

`.help()`: display help information and exit immediately. You can optionally pass `{ error: true }` to display on stderr and exit with an error status.

`.outputHelp()`: output help information without exiting. You can optionally pass `{ error: true }` to display on stderr.

`.helpInformation()`: get the built-in command help information as a string for processing or displaying yourself.

### .name

The command name appears in the help, and is also used for locating stand-alone executable subcommands.

You may specify the program name using `.name()` or in the Command constructor. For the program, Commander will
fallback to using the script name from the full arguments passed into `.parse()`. However, the script name varies
depending on how your program is launched so you may wish to specify it explicitly.

```js
program.name('pizza');
const pm = new Command('pm');
```

Subcommands get a name when specified using `.command()`. If you create the subcommand yourself to use with `.addCommand()`,
then set the name using `.name()` or in the Command constructor.

### .usage

This allows you to customise the usage description in the first line of the help. Given:

```js
program
  .name("my-command")
  .usage("[global options] command")
```

The help will start with:

```Text
Usage: my-command [global options] command
```

### .description and .summary

The description appears in the help for the command. You can optionally supply a shorter
summary to use when listed as a subcommand of the program.

```js
program
  .command("duplicate")
  .summary("make a copy")
  .description(`Make a copy of the current project.
This may require additional disk space.
  `);
```

### .helpOption(flags, description)

By default every command has a help option. You may change the default help flags and description. Pass false to disable the built-in help option.

```js
program
  .helpOption('-e, --HELP', 'read more information');
```

### .addHelpCommand()

A help command is added by default if your command has subcommands. You can explicitly turn on or off the implicit help command with `.addHelpCommand()` and `.addHelpCommand(false)`.

You can both turn on and customise the help command by supplying the name and description:

```js
program.addHelpCommand('assist [command]', 'show assistance');
```

### More configuration

The built-in help is formatted using the Help class.
You can configure the Help behaviour by modifying data properties and methods using `.configureHelp()`, or by subclassing using `.createHelp()` if you prefer.

The data properties are:

- `helpWidth`: specify the wrap width, useful for unit tests
- `sortSubcommands`: sort the subcommands alphabetically
- `sortOptions`: sort the options alphabetically
- `showGlobalOptions`: show a section with the global options from the parent command(s)

You can override any method on the [Help](./lib/help.js) class. There are methods getting the visible lists of arguments, options, and subcommands. There are methods for formatting the items in the lists, with each item having a _term_ and _description_. Take a look at `.formatHelp()` to see how they are used.

Example file: [configure-help.js](./examples/configure-help.js)

```js
program.configureHelp({
  sortSubcommands: true,
  subcommandTerm: (cmd) => cmd.name() // Just show the name, instead of short usage.
});
```

## Custom event listeners

You can execute custom actions by listening to command and option events.

```js
program.on('option:verbose', function () {
  process.env.VERBOSE = this.opts().verbose;
});
```

## Bits and pieces

### .parse() and .parseAsync()

The first argument to `.parse` is the array of strings to parse. You may omit the parameter to implicitly use `process.argv`.

If the arguments follow different conventions than node you can pass a `from` option in the second parameter:

- 'node': default, `argv[0]` is the application and `argv[1]` is the script being run, with user parameters after that
- 'electron': `argv[1]` varies depending on whether the electron application is packaged
- 'user': all of the arguments from the user

For example:

```js
program.parse(process.argv); // Explicit, node conventions
program.parse(); // Implicit, and auto-detect electron
program.parse(['-f', 'filename'], { from: 'user' });
```

### Parsing Configuration

If the default parsing does not suit your needs, there are some behaviours to support other usage patterns.

By default program options are recognised before and after subcommands. To only look for program options before subcommands, use `.enablePositionalOptions()`. This lets you use
an option for a different purpose in subcommands.

Example file: [positional-options.js](./examples/positional-options.js)

With positional options, the `-b` is a program option in the first line and a subcommand option in the second line:

```sh
program -b subcommand
program subcommand -b
```

By default options are recognised before and after command-arguments. To only process options that come
before the command-arguments, use `.passThroughOptions()`. This lets you pass the  arguments and following options through to another program
without needing to use `--` to end the option processing.
To use pass through options in a subcommand, the program needs to enable positional options.

Example file: [pass-through-options.js](./examples/pass-through-options.js)

With pass through options, the `--port=80` is a program option in the first line and passed through as a command-argument in the second line:

```sh
program --port=80 arg
program arg --port=80
```

By default the option processing shows an error for an unknown option. To have an unknown option treated as an ordinary command-argument and continue looking for options, use `.allowUnknownOption()`. This lets you mix known and unknown options.

By default the argument processing does not display an error for more command-arguments than expected.
To display an error for excess arguments, use`.allowExcessArguments(false)`.

### Legacy options as properties

Before Commander 7, the option values were stored as properties on the command.
This was convenient to code but the downside was possible clashes with
existing properties of `Command`. You can revert to the old behaviour to run unmodified legacy code by using `.storeOptionsAsProperties()`.

```js
program
  .storeOptionsAsProperties()
  .option('-d, --debug')
  .action((commandAndOptions) => {
    if (commandAndOptions.debug) {
      console.error(`Called ${commandAndOptions.name()}`);
    }
  });
```

### TypeScript

extra-typings: There is an optional project to infer extra type information from the option and argument definitions.
This adds strong typing to the options returned by `.opts()` and the parameters to `.action()`.
See [commander-js/extra-typings](https://github.com/commander-js/extra-typings) for more.

```
import { Command } from '@commander-js/extra-typings';
```

ts-node: If you use `ts-node` and  stand-alone executable subcommands written as `.ts` files, you need to call your program through node to get the subcommands called correctly. e.g.

```sh
node -r ts-node/register pm.ts
```

### createCommand()

This factory function creates a new command. It is exported and may be used instead of using `new`, like:

```js
const { createCommand } = require('commander');
const program = createCommand();
```

`createCommand` is also a method of the Command object, and creates a new command rather than a subcommand. This gets used internally
when creating subcommands using `.command()`, and you may override it to
customise the new subcommand (example file [custom-command-class.js](./examples/custom-command-class.js)).

### Node options such as `--harmony`

You can enable `--harmony` option in two ways:

- Use `#! /usr/bin/env node --harmony` in the subcommands scripts. (Note Windows does not support this pattern.)
- Use the `--harmony` option when call the command, like `node --harmony examples/pm publish`. The `--harmony` option will be preserved when spawning subcommand process.

### Debugging stand-alone executable subcommands

An executable subcommand is launched as a separate child process.

If you are using the node inspector for [debugging](https://nodejs.org/en/docs/guides/debugging-getting-started/) executable subcommands using `node --inspect` et al,
the inspector port is incremented by 1 for the spawned subcommand.

If you are using VSCode to debug executable subcommands you need to set the `"autoAttachChildProcesses": true` flag in your launch.json configuration.

### Display error

This routine is available to invoke the Commander error handling for your own error conditions. (See also the next section about exit handling.)

As well as the error message, you can optionally specify the `exitCode` (used with `process.exit`)
and `code` (used with `CommanderError`).

```js
program.error('Password must be longer than four characters');
program.error('Custom processing has failed', { exitCode: 2, code: 'my.custom.error' });
```

### Override exit and output handling

By default Commander calls `process.exit` when it detects errors, or after displaying the help or version. You can override
this behaviour and optionally supply a callback. The default override throws a `CommanderError`.

The override callback is passed a `CommanderError` with properties `exitCode` number, `code` string, and `message`. The default override behaviour is to throw the error, except for async handling of executable subcommand completion which carries on. The normal display of error messages or version or help
is not affected by the override which is called after the display.

```js
program.exitOverride();

try {
  program.parse(process.argv);
} catch (err) {
  // custom processing...
}
```

By default Commander is configured for a command-line application and writes to stdout and stderr.
You can modify this behaviour for custom applications. In addition, you can modify the display of error messages.

Example file: [configure-output.js](./examples/configure-output.js)

```js
function errorColor(str) {
  // Add ANSI escape codes to display text in red.
  return `\x1b[31m${str}\x1b[0m`;
}

program
  .configureOutput({
    // Visibly override write routines as example!
    writeOut: (str) => process.stdout.write(`[OUT] ${str}`),
    writeErr: (str) => process.stdout.write(`[ERR] ${str}`),
    // Highlight errors in color.
    outputError: (str, write) => write(errorColor(str))
  });
```

### Additional documentation

There is more information available about:

- [deprecated](./docs/deprecated.md) features still supported for backwards compatibility
- [options taking varying arguments](./docs/options-taking-varying-arguments.md)
- [parsing life cycle and hooks](./docs/parsing-and-hooks.md)

## Support

The current version of Commander is fully supported on Long Term Support versions of Node.js, and requires at least v14.
(For older versions of Node.js, use an older version of Commander.)

The main forum for free and community support is the project [Issues](https://github.com/tj/commander.js/issues) on GitHub.

### Commander for enterprise

Available as part of the Tidelift Subscription

The maintainers of Commander and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-commander?utm_source=npm-commander&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)


---

# html-tags

> List of standard HTML tags

It's just a couple of JSON files that can be used in any environment.

It intentionally leaves out obsolete tags.

## Install

```
$ npm install html-tags
```

## Usage

```js
const htmlTags = require('html-tags');

console.log(htmlTags);
//=> ['a', 'abbr', 'acronym', …]
```

And void (self-closing) tags:

```js
const voidHtmlTags = require('html-tags/void');

console.log(voidHtmlTags);
//=> ['area', 'base', 'br', …]
```

## Contribute

Make sure to update types in `index.d.ts` when changing HTML elements.


---

# html-void-elements

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]

List of HTML void tag names.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`htmlVoidElements`](#htmlvoidelements)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Security](#security)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This is a list of all void tag names according to HTML.

> 👉 **Note**: includes ancient (such as `basefont` and `bgsound`) tag names
> too.

## When should I use this?

You can use this when you’re writing HTML parsers, minifiers, or compilers.

## Install

This package is [ESM only][esm].
In Node.js (version 14.14+, 16.0+), install with [npm][]:

```sh
npm install html-void-elements
```

In Deno with [`esm.sh`][esmsh]:

```js
import {htmlVoidElements} from 'https://esm.sh/html-void-elements@2'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {htmlVoidElements} from 'https://esm.sh/html-void-elements@2?bundle'
</script>
```

## Use

```js
import {htmlVoidElements} from 'html-void-elements'

console.log(htmlVoidElements)
```

Yields:

```js
[
  'area',
  'base',
  'basefont',
  'bgsound',
  'br',
  'col',
  'command',
  'embed',
  'frame',
  'hr',
  'image',
  'img',
  'input',
  'keygen',
  'link',
  'meta',
  'param',
  'source',
  'track',
  'wbr'
]
```

## API

This package exports the identifier `htmlVoidElements`.
There is no default export.

### `htmlVoidElements`

List of HTML void tag names (`Array<string>`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

This package is at least compatible with all maintained versions of Node.js.
As of now, that is Node.js 14.14+ and 16.0+.
It also works in Deno and modern browsers.

## Security

This package is safe.

## Related

*   [`wooorm/html-tag-names`](https://github.com/wooorm/html-tag-names)
    — list of HTML tag names
*   [`wooorm/html-element-attributes`](https://github.com/wooorm/html-element-attributes)
    — map of HTML elements to attributes

## Contribute

Yes please!
See [How to Contribute to Open Source][contribute].

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definition -->

[build-badge]: https://github.com/wooorm/html-void-elements/workflows/main/badge.svg

[build]: https://github.com/wooorm/html-void-elements/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/html-void-elements.svg

[coverage]: https://codecov.io/github/wooorm/html-void-elements

[downloads-badge]: https://img.shields.io/npm/dm/html-void-elements.svg

[downloads]: https://www.npmjs.com/package/html-void-elements

[size-badge]: https://img.shields.io/bundlephobia/minzip/html-void-elements.svg

[size]: https://bundlephobia.com/result?p=html-void-elements

[npm]: https://docs.npmjs.com/cli/install

[esmsh]: https://esm.sh

[license]: license

[author]: https://wooorm.com

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[typescript]: https://www.typescriptlang.org

[contribute]: https://opensource.guide/how-to-contribute/


---

[![npm][npm]][npm-url]
[![node][node]][node-url]
![npm](https://img.shields.io/npm/dw/html-webpack-plugin.svg)
[![tests][tests]][tests-url]
[![Backers on Open Collective](https://opencollective.com/html-webpack-plugin/backers/badge.svg)](#backers)
[![Sponsors on Open Collective](https://opencollective.com/html-webpack-plugin/sponsors/badge.svg)](#sponsors)

<div align="center">
  <img width="200" height="200" src="https://www.w3.org/html/logo/downloads/HTML5_Badge.svg">
  <a href="https://github.com/webpack/webpack">
    <img width="200" height="200"
      src="https://webpack.js.org/assets/icon-square-big.svg">
  </a>
  <div>
    <img width="100" height="100" title="Webpack Plugin" src="http://michael-ciniawsky.github.io/postcss-load-plugins/logo.svg">
  </div>
  <h1>HTML Webpack Plugin</h1>
  <p>Plugin that simplifies creation of HTML files to serve your bundles</p>
</div>

<h2 align="center">Install</h2>

<h3>Webpack 5</h3>

```bash
  npm i --save-dev html-webpack-plugin
```

```bash
  yarn add --dev html-webpack-plugin
```

<h3>Webpack 4</h3>

```bash
  npm i --save-dev html-webpack-plugin@4
```

```bash
  yarn add --dev html-webpack-plugin@4
```

This is a [webpack](http://webpack.js.org/) plugin that simplifies creation of HTML files to serve your `webpack` bundles. This is especially useful for `webpack` bundles that include a hash in the filename which changes every compilation. You can either let the plugin generate an HTML file for you, supply
your own template using `lodash` templates or use your own loader.

<h2 align="center">Sponsors</h2>

<a href="https://opencollective.com/html-webpack-plugin/sponsor/0/website" target="_blank"><img src="https://opencollective.com/html-webpack-plugin/sponsor/0/avatar.svg"></a>
<a href="https://opencollective.com/html-webpack-plugin/sponsor/1/website" target="_blank"><img src="https://opencollective.com/html-webpack-plugin/sponsor/1/avatar.svg"></a>
<a href="https://opencollective.com/html-webpack-plugin/sponsor/2/website" target="_blank"><img src="https://opencollective.com/html-webpack-plugin/sponsor/2/avatar.svg"></a>
<a href="https://opencollective.com/html-webpack-plugin/sponsor/3/website" target="_blank"><img src="https://opencollective.com/html-webpack-plugin/sponsor/3/avatar.svg"></a>
<a href="https://opencollective.com/html-webpack-plugin/sponsor/4/website" target="_blank"><img src="https://opencollective.com/html-webpack-plugin/sponsor/4/avatar.svg"></a>
<a href="https://opencollective.com/html-webpack-plugin/sponsor/5/website" target="_blank"><img src="https://opencollective.com/html-webpack-plugin/sponsor/5/avatar.svg"></a>
<a href="https://opencollective.com/html-webpack-plugin/sponsor/6/website" target="_blank"><img src="https://opencollective.com/html-webpack-plugin/sponsor/6/avatar.svg"></a>
<a href="https://opencollective.com/html-webpack-plugin/sponsor/7/website" target="_blank"><img src="https://opencollective.com/html-webpack-plugin/sponsor/7/avatar.svg"></a>
<a href="https://opencollective.com/html-webpack-plugin/sponsor/8/website" target="_blank"><img src="https://opencollective.com/html-webpack-plugin/sponsor/8/avatar.svg"></a>
<a href="https://opencollective.com/html-webpack-plugin/sponsor/9/website" target="_blank"><img src="https://opencollective.com/html-webpack-plugin/sponsor/9/avatar.svg"></a>

Thanks for supporting the ongoing improvements to the html-webpack-plugin!

<h2 align="center">Zero Config</h2>

The `html-webpack-plugin` works without configuration.  
It's a great addition to the [⚙️ webpack-config-plugins](https://github.com/namics/webpack-config-plugins/blob/master/README.md#zero-config-webpack-dev-server-example).

<h2 align="center">Plugins</h2>

The `html-webpack-plugin` provides [hooks](https://github.com/jantimon/html-webpack-plugin#events) to extend it to your needs. There are already some really powerful plugins which can be integrated with zero configuration

- [webpack-subresource-integrity](https://www.npmjs.com/package/webpack-subresource-integrity) for enhanced asset security
- [appcache-webpack-plugin](https://github.com/lettertwo/appcache-webpack-plugin) for iOS and Android offline usage
- [favicons-webpack-plugin](https://github.com/jantimon/favicons-webpack-plugin) which generates favicons and icons for iOS, Android and desktop browsers
- [html-webpack-harddisk-plugin](https://github.com/jantimon/html-webpack-harddisk-plugin) can be used to always write to disk the html file, useful when webpack-dev-server / HMR are being used
- [html-webpack-inline-svg-plugin](https://github.com/thegc/html-webpack-inline-svg-plugin) to inline SVGs in the resulting HTML file.
- [html-webpack-exclude-assets-plugin](https://github.com/jamesjieye/html-webpack-exclude-assets-plugin) for excluding assets using regular expressions
- [html-webpack-include-assets-plugin](https://github.com/jharris4/html-webpack-include-assets-plugin) for including lists of js or css file paths (such as those copied by the copy-webpack-plugin).
- [html-webpack-injector](https://github.com/thearchitgarg/html-webpack-injector) to inject chunks in `head` or `body` (different locations ) of same html document.
- [resource-hints-webpack-plugin](https://github.com/jantimon/resource-hints-webpack-plugin) to add resource hints for faster initial page loads using `<link rel='preload'>` and `<link rel='prefetch'>`
- [link-media-html-webpack-plugin](https://github.com/yaycmyk/link-media-html-webpack-plugin) allows for injected stylesheet `<link />` tags to have their media attribute set automatically; useful for providing specific desktop/mobile/print etc. stylesheets that the browser will conditionally download
- [html-webpack-inline-style-plugin](https://github.com/djaax/html-webpack-inline-style-plugin) for inlining styles to HTML elements using [juice](https://github.com/Automattic/juice). Useful for email generation automatisation.
- [html-webpack-exclude-empty-assets-plugin](https://github.com/KnisterPeter/html-webpack-exclude-empty-assets-plugin) removes empty assets from being added to the html. This fixes some problems with extract-text-plugin with webpack 4.
- [webpack-concat-plugin](https://github.com/hxlniada/webpack-concat-plugin) for concat and uglify files that needn't to be webpack bundles(for legacy files) and inject to html-webpack-plugin.
- [html-webpack-link-type-plugin](https://github.com/steadyapp/html-webpack-link-type-plugin) adds a configurable mimetype to resources injected as links (such as adding type="text/css" to external stylesheets) for compatibility with "strict mode".
- [csp-html-webpack-plugin](https://github.com/slackhq/csp-html-webpack-plugin) to add [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) meta tags to the HTML output
- [strict-csp-html-webpack-plugin](https://github.com/google/strict-csp/tree/main/strict-csp-html-webpack-plugin) to add a [**strict** Content-Security-Policy (CSP)](https://web.dev) as a `meta` tag to the HTML output. A strict CSP is specifically efficient against XSS attacks.
- [webpack-nomodule-plugin](https://github.com/swimmadude66/webpack-nomodule-plugin) allows you to add a `nomodule` attribute to specific injected scripts, which prevents the scripts from being loaded by newer browsers. Good for limiting loads of polyfills.
- [html-webpack-skip-assets-plugin](https://github.com/swimmadude66/html-webpack-skip-assets-plugin) Skip adding certain output files to the html file. Built as a drop-in replacement for [html-webpack-exclude-assets-plugin](https://www.npmjs.com/package/html-webpack-exclude-assets-plugin) and works with newer [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin) versions
- [html-webpack-inject-preload](https://github.com/principalstudio/html-webpack-inject-preload) allows to add preload links &lt;link rel='preload'> anywhere you want.
- [inject-body-webpack-plugin](https://github.com/Jaid/inject-body-webpack-plugin) is a simple method of injecting a custom HTML string into the body.
- [html-webpack-plugin-django](https://github.com/TommasoAmici/html-webpack-plugin-django) a Webpack plugin to inject Django static tags.
- [html-webpack-inject-attributes-plugin](https://github.com/dyw934854565/html-webpack-inject-attributes-plugin) add extra attributes to inject assetTags.
- [js-entry-webpack-plugin](https://github.com/liam61/html-webpack-plugin) creates webpack bundles into your js entry

<h2 align="center">Usage</h2>

The plugin will generate an HTML5 file for you that includes all your `webpack`
bundles in the head using `script` tags. Just add the plugin to your `webpack`
config as follows:

**webpack.config.js**

```js
const HtmlWebpackPlugin = require("html-webpack-plugin");

module.exports = {
  entry: "index.js",
  output: {
    path: __dirname + "/dist",
    filename: "index_bundle.js",
  },
  plugins: [new HtmlWebpackPlugin()],
};
```

This will generate a file `dist/index.html` containing the following

```html
<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>Webpack App</title>
    <script defer src="index_bundle.js"></script>
  </head>
  <body></body>
</html>
```

If you have multiple `webpack` entry points, they will all be included with `script` tags in the generated HTML.

If you have any CSS assets in webpack's output (for example, CSS extracted with the [mini-css-extract-plugin](https://github.com/webpack-contrib/mini-css-extract-plugin))
then these will be included with `<link>` tags in the HTML head.

If you have plugins that make use of it, `html-webpack-plugin` should be ordered first before any of the integrated Plugins.

<h2 align="center">Options</h2>

You can pass a hash of configuration options to `html-webpack-plugin`.
Allowed values are as follows:

|           Name           |                         Type                         |                        Default                        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| :----------------------: | :--------------------------------------------------: | :---------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|       **`title`**        |                      `{String}`                      |                     `Webpack App`                     | The title to use for the generated HTML document                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
|      **`filename`**      |                 `{String\|Function}`                 |                    `'index.html'`                     | The file to write the HTML to. Defaults to `index.html`. You can specify a subdirectory here too (eg: `assets/admin.html`). The `[name]` placeholder will be replaced with the entry name. Can also be a function e.g. `(entryName) => entryName + '.html'`.                                                                                                                                                                                                                                                                               |
|      **`template`**      |                      `{String}`                      |                          ``                           | `webpack` relative or absolute path to the template. By default it will use `src/index.ejs` if it exists. Please see the [docs](https://github.com/jantimon/html-webpack-plugin/blob/master/docs/template-option.md) for details                                                                                                                                                                                                                                                                                                           |
|  **`templateContent`**   |             `{string\|Function\|false}`              |                         false                         | Can be used instead of `template` to provide an inline template - please read the [Writing Your Own Templates](https://github.com/jantimon/html-webpack-plugin#writing-your-own-templates) section                                                                                                                                                                                                                                                                                                                                         |
| **`templateParameters`** |            `{Boolean\|Object\|Function}`             |                        `false`                        | Allows to overwrite the parameters used in the template - see [example](https://github.com/jantimon/html-webpack-plugin/tree/master/examples/template-parameters)                                                                                                                                                                                                                                                                                                                                                                          |
|       **`inject`**       |                 `{Boolean\|String}`                  |                        `true`                         | `true \|\| 'head' \|\| 'body' \|\| false` Inject all assets into the given `template` or `templateContent`. When passing `'body'` all javascript resources will be placed at the bottom of the body element. `'head'` will place the scripts in the head element. Passing `true` will add it to the head/body depending on the `scriptLoading` option. Passing `false` will disable automatic injections. - see the [inject:false example](https://github.com/jantimon/html-webpack-plugin/tree/master/examples/custom-insertion-position) |
|     **`publicPath`**     |                  `{String\|'auto'}`                  |                       `'auto'`                        | The publicPath used for script and link tags                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
|   **`scriptLoading`**    | `{'blocking'\|'defer'\|'module'\|'systemjs-module'}` |                       `'defer'`                       | Modern browsers support non blocking javascript loading (`'defer'`) to improve the page startup performance. Setting to `'module'` adds attribute [`type="module"`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules#applying_the_module_to_your_html). This also implies "defer", since modules are automatically deferred.                                                                                                                                                                                          |
|      **`favicon`**       |                      `{String}`                      |                          ``                           | Adds the given favicon path to the output HTML                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
|        **`meta`**        |                      `{Object}`                      |                         `{}`                          | Allows to inject `meta`-tags. E.g. `meta: {viewport: 'width=device-width, initial-scale=1, shrink-to-fit=no'}`                                                                                                                                                                                                                                                                                                                                                                                                                             |
|        **`base`**        |              `{Object\|String\|false}`               |                        `false`                        | Inject a [`base`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/base) tag. E.g. `base: "https://example.com/path/page.html`                                                                                                                                                                                                                                                                                                                                                                                                    |
|       **`minify`**       |                 `{Boolean\|Object}`                  | `true` if `mode` is `'production'`, otherwise `false` | Controls if and in what ways the output should be minified. See [minification](#minification) below for more details.                                                                                                                                                                                                                                                                                                                                                                                                                      |
|        **`hash`**        |                     `{Boolean}`                      |                        `false`                        | If `true` then append a unique `webpack` compilation hash to all included scripts and CSS files (i.e. `main.js?hash=compilation_hash`). This is useful for cache busting                                                                                                                                                                                                                                                                                                                                                                   |
|       **`cache`**        |                     `{Boolean}`                      |                        `true`                         | Emit the file only if it was changed                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
|     **`showErrors`**     |                     `{Boolean}`                      |                        `true`                         | Errors details will be written into the HTML page                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|       **`chunks`**       |                        `{?}`                         |                          `?`                          | Allows you to add only some chunks (e.g only the unit-test chunk)                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|   **`chunksSortMode`**   |                 `{String\|Function}`                 |                        `auto`                         | Allows to control how chunks should be sorted before they are included to the HTML. Allowed values are `'none' \| 'auto' \| 'manual' \| {Function}`                                                                                                                                                                                                                                                                                                                                                                                        |
|   **`excludeChunks`**    |                  `{Array.<string>}`                  |                          ``                           | Allows you to skip some chunks (e.g don't add the unit-test chunk)                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
|       **`xhtml`**        |                     `{Boolean}`                      |                        `false`                        | If `true` render the `link` tags as self-closing (XHTML compliant)                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

Here's an example webpack config illustrating how to use these options

**webpack.config.js**

```js
{
  entry: 'index.js',
  output: {
    path: __dirname + '/dist',
    filename: 'index_bundle.js'
  },
  plugins: [
    new HtmlWebpackPlugin({
      title: 'My App',
      filename: 'assets/admin.html'
    })
  ]
}
```

### Generating Multiple HTML Files

To generate more than one HTML file, declare the plugin more than
once in your plugins array

**webpack.config.js**

```js
{
  entry: 'index.js',
  output: {
    path: __dirname + '/dist',
    filename: 'index_bundle.js'
  },
  plugins: [
    new HtmlWebpackPlugin(), // Generates default index.html
    new HtmlWebpackPlugin({  // Also generate a test.html
      filename: 'test.html',
      template: 'src/assets/test.html'
    })
  ]
}
```

### Writing Your Own Templates

If the default generated HTML doesn't meet your needs you can supply
your own template. The easiest way is to use the `template` option and pass a custom HTML file.
The html-webpack-plugin will automatically inject all necessary CSS, JS, manifest
and favicon files into the markup.

Details of other template loaders are [documented here](https://github.com/jantimon/html-webpack-plugin/blob/master/docs/template-option.md).

```js
plugins: [
  new HtmlWebpackPlugin({
    title: "Custom template",
    // Load a custom template (lodash by default)
    template: "index.html",
  }),
];
```

**index.html**

```html
<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <title><%= htmlWebpackPlugin.options.title %></title>
  </head>
  <body></body>
</html>
```

If you already have a template loader, you can use it to parse the template.
Please note that this will also happen if you specify the html-loader and use `.html` file as template.

**webpack.config.js**

```js
module: {
  loaders: [
    { test: /\.hbs$/, loader: "handlebars-loader" }
  ]
},
plugins: [
  new HtmlWebpackPlugin({
    title: 'Custom template using Handlebars',
    template: 'index.hbs'
  })
]
```

You can use the `lodash` syntax out of the box. If the `inject` feature doesn't fit your needs and you want full control over the asset placement use the [default template](https://github.com/jaketrent/html-webpack-template/blob/86f285d5c790a6c15263f5cc50fd666d51f974fd/index.html) of the [html-webpack-template project](https://github.com/jaketrent/html-webpack-template) as a starting point for writing your own.

The following variables are available in the template by default (you can extend them using the `templateParameters` option):

- `htmlWebpackPlugin`: data specific to this plugin

  - `htmlWebpackPlugin.options`: the options hash that was passed to
    the plugin. In addition to the options actually used by this plugin,
    you can use this hash to pass arbitrary data through to your template.

  - `htmlWebpackPlugin.tags`: the prepared `headTags` and `bodyTags` Array to render the `<base>`, `<meta>`, `<script>` and `<link>` tags.
    Can be used directly in templates and literals. For example:
    ```html
    <html>
      <head>
        <%= htmlWebpackPlugin.tags.headTags %>
      </head>
      <body>
        <%= htmlWebpackPlugin.tags.bodyTags %>
      </body>
    </html>
    ```
  - `htmlWebpackPlugin.files`: direct access to the files used during the compilation.

    ```typescript
    publicPath: string;
    js: string[];
    css: string[];
    manifest?: string;
    favicon?: string;
    ```

- `webpackConfig`: the webpack configuration that was used for this compilation. This
  can be used, for example, to get the `publicPath` (`webpackConfig.output.publicPath`).

- `compilation`: the webpack [compilation object](https://webpack.js.org/api/compilation-object/).
  This can be used, for example, to get the contents of processed assets and inline them
  directly in the page, through `compilation.assets[...].source()`
  (see [the inline template example](examples/inline/template.pug)).

The template can also be directly inlined directly into the options object.  
⚠️ **`templateContent` does not allow to use webpack loaders for your template and will not watch for template file changes**

**webpack.config.js**

```js
new HtmlWebpackPlugin({
  templateContent: `
    <html>
      <body>
        <h1>Hello World</h1>
      </body>
    </html>
  `,
});
```

The `templateContent` can also access all `templateParameters` values.  
⚠️ **`templateContent` does not allow to use webpack loaders for your template and will not watch for template file changes**

**webpack.config.js**

```js
new HtmlWebpackPlugin({
  inject: false,
  templateContent: ({ htmlWebpackPlugin }) => `
    <html>
      <head>
        ${htmlWebpackPlugin.tags.headTags}
      </head>
      <body>
        <h1>Hello World</h1>
        ${htmlWebpackPlugin.tags.bodyTags}
      </body>
    </html>
  `,
});
```

### Filtering Chunks

To include only certain chunks you can limit the chunks being used

**webpack.config.js**

```js
plugins: [
  new HtmlWebpackPlugin({
    chunks: ["app"],
  }),
];
```

It is also possible to exclude certain chunks by setting the `excludeChunks` option

**webpack.config.js**

```js
plugins: [
  new HtmlWebpackPlugin({
    excludeChunks: ["dev-helper"],
  }),
];
```

### Minification

If the `minify` option is set to `true` (the default when webpack's `mode` is `'production'`),
the generated HTML will be minified using [html-minifier-terser](https://github.com/DanielRuf/html-minifier-terser)
and the following options:

```js
{
  collapseWhitespace: true,
  keepClosingSlash: true,
  removeComments: true,
  removeRedundantAttributes: true,
  removeScriptTypeAttributes: true,
  removeStyleLinkTypeAttributes: true,
  useShortDoctype: true
}
```

To use custom [html-minifier options](https://github.com/DanielRuf/html-minifier-terser#options-quick-reference)
pass an object to `minify` instead. This object will not be merged with the defaults above.

To disable minification during production mode set the `minify` option to `false`.

### Meta Tags

If the `meta` option is set the html-webpack-plugin will inject meta tags.  
For the default template the html-webpack-plugin will already provide a default for the `viewport` meta tag.

Please take a look at this well maintained list of almost all [possible meta tags](https://github.com/joshbuchea/HEAD#meta).

#### name/content meta tags

Most meta tags are configured by setting a `name` and a `content` attribute.  
To add those use a key/value pair:

**webpack.config.js**

```js
plugins: [
  new HtmlWebpackPlugin({
    meta: {
      viewport: "width=device-width, initial-scale=1, shrink-to-fit=no",
      // Will generate: <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
      "theme-color": "#4285f4",
      // Will generate: <meta name="theme-color" content="#4285f4">
    },
  }),
];
```

#### Simulate http response headers

The **http-equiv** attribute is essentially used to simulate a HTTP response header.  
This format is supported using an object notation which allows you to add any attribute:

**webpack.config.js**

```js
plugins: [
  new HtmlWebpackPlugin({
    meta: {
      "Content-Security-Policy": {
        "http-equiv": "Content-Security-Policy",
        content: "default-src https:",
      },
      // Will generate: <meta http-equiv="Content-Security-Policy" content="default-src https:">
      // Which equals to the following http header: `Content-Security-Policy: default-src https:`
      "set-cookie": {
        "http-equiv": "set-cookie",
        content: "name=value; expires=date; path=url",
      },
      // Will generate: <meta http-equiv="set-cookie" content="value; expires=date; path=url">
      // Which equals to the following http header: `set-cookie: value; expires=date; path=url`
    },
  }),
];
```

### Base Tag

When the `base` option is used,
html-webpack-plugin will inject a [base tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/base).
By default, a base tag will not be injected.

The following two are identical and will both insert `<base href="http://example.com/some/page.html">`:

```js
new HtmlWebpackPlugin({
  base: "http://example.com/some/page.html",
});
```

```js
new HtmlWebpackPlugin({
  base: { href: "http://example.com/some/page.html" },
});
```

The `target` can be specified with the corresponding key:

```js
new HtmlWebpackPlugin({
  base: {
    href: "http://example.com/some/page.html",
    target: "_blank",
  },
});
```

which will inject the element `<base href="http://example.com/some/page.html" target="_blank">`.

### Long Term Caching

For long term caching add `contenthash` to the filename.

**Example:**

```js
plugins: [
  new HtmlWebpackPlugin({
    filename: "index.[contenthash].html",
  }),
];
```

`contenthash` is the hash of the content of the output file.

Refer webpack's [Template Strings](https://webpack.js.org/configuration/output/#template-strings) for more details

### Events

To allow other [plugins](https://github.com/webpack/docs/wiki/plugins) to alter the HTML this plugin executes
[tapable](https://github.com/webpack/tapable/tree/master) hooks.

The [lib/hooks.js](https://github.com/jantimon/html-webpack-plugin/blob/master/lib/hooks.js) contains all information
about which values are passed.

[![Concept flow uml](https://raw.githubusercontent.com/jantimon/html-webpack-plugin/master/flow.png)](https://github.com/jantimon/html-webpack-plugin/blob/master/flow.puml)

#### `beforeAssetTagGeneration` hook

```
    AsyncSeriesWaterfallHook<{
      assets: {
        publicPath: string,
        js: Array<{string}>,
        css: Array<{string}>,
        favicon?: string | undefined,
        manifest?: string | undefined
      },
      outputName: string,
      plugin: HtmlWebpackPlugin
    }>
```

#### `alterAssetTags` hook

```
    AsyncSeriesWaterfallHook<{
      assetTags: {
        scripts: Array<HtmlTagObject>,
        styles: Array<HtmlTagObject>,
        meta: Array<HtmlTagObject>,
      },
      publicPath: string,
      outputName: string,
      plugin: HtmlWebpackPlugin
    }>
```

#### `alterAssetTagGroups` hook

```
    AsyncSeriesWaterfallHook<{
      headTags: Array<HtmlTagObject | HtmlTagObject>,
      bodyTags: Array<HtmlTagObject | HtmlTagObject>,
      publicPath: string,
      outputName: string,
      plugin: HtmlWebpackPlugin
    }>
```

#### `afterTemplateExecution` hook

```
    AsyncSeriesWaterfallHook<{
      html: string,
      headTags: Array<HtmlTagObject | HtmlTagObject>,
      bodyTags: Array<HtmlTagObject | HtmlTagObject>,
      outputName: string,
      plugin: HtmlWebpackPlugin,
    }>
```

#### `beforeEmit` hook

```
    AsyncSeriesWaterfallHook<{
      html: string,
      outputName: string,
      plugin: HtmlWebpackPlugin,
    }>
```

#### `afterEmit` hook

```
    AsyncSeriesWaterfallHook<{
      outputName: string,
      plugin: HtmlWebpackPlugin
    }>
```

Example implementation: [webpack-subresource-integrity](https://www.npmjs.com/package/webpack-subresource-integrity)

**plugin.js**

```js
// If your plugin is direct dependent to the html webpack plugin:
const HtmlWebpackPlugin = require("html-webpack-plugin");
// If your plugin is using html-webpack-plugin as an optional dependency
// you can use https://github.com/tallesl/node-safe-require instead:
const HtmlWebpackPlugin = require("safe-require")("html-webpack-plugin");

class MyPlugin {
  apply(compiler) {
    compiler.hooks.compilation.tap("MyPlugin", (compilation) => {
      console.log("The compiler is starting a new compilation...");

      // Static Plugin interface |compilation |HOOK NAME | register listener
      HtmlWebpackPlugin.getCompilationHooks(compilation).beforeEmit.tapAsync(
        "MyPlugin", // <-- Set a meaningful name here for stacktraces
        (data, cb) => {
          // Manipulate the content
          data.html += "The Magic Footer";
          // Tell webpack to move on
          cb(null, data);
        },
      );
    });
  }
}

module.exports = MyPlugin;
```

**webpack.config.js**

```js
plugins: [new MyPlugin({ options: "" })];
```

Note that the callback must be passed the HtmlWebpackPluginData in order to pass this onto any other plugins listening on the same `beforeEmit` event

<h2 align="center">Maintainers</h2>

<table>
  <tbody>
    <tr>
      <td align="center">
        <img width="150" height="150"
        src="https://avatars3.githubusercontent.com/u/4113649?v=3&s=150">
        </br>
        <a href="https://github.com/jantimon">Jan Nicklas</a>
      </td>
      <td align="center">
        <img width="150" height="150"
        src="https://avatars2.githubusercontent.com/u/4112409?v=3&s=150">
        </br>
        <a href="https://github.com/mastilver">Thomas Sileghem</a>
      </td>
    </tr>
  <tbody>
</table>

## Backers

Thank you to all our backers!  
If you want to support the project as well [become a sponsor](https://opencollective.com/html-webpack-plugin#sponsor) or a [a backer](https://opencollective.com/html-webpack-plugin#backer).

<a href="https://opencollective.com/html-webpack-plugin/backer/0/website?requireActive=false" target="_blank"><img src="https://opencollective.com/html-webpack-plugin/backer/0/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/html-webpack-plugin/backer/1/website?requireActive=false" target="_blank"><img src="https://opencollective.com/html-webpack-plugin/backer/1/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/html-webpack-plugin/backer/2/website?requireActive=false" target="_blank"><img src="https://opencollective.com/html-webpack-plugin/backer/2/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/html-webpack-plugin/backer/3/website?requireActive=false" target="_blank"><img src="https://opencollective.com/html-webpack-plugin/backer/3/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/html-webpack-plugin/backer/4/website?requireActive=false" target="_blank"><img src="https://opencollective.com/html-webpack-plugin/backer/4/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/html-webpack-plugin/backer/5/website?requireActive=false" target="_blank"><img src="https://opencollective.com/html-webpack-plugin/backer/5/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/html-webpack-plugin/backer/6/website?requireActive=false" target="_blank"><img src="https://opencollective.com/html-webpack-plugin/backer/6/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/html-webpack-plugin/backer/7/website?requireActive=false" target="_blank"><img src="https://opencollective.com/html-webpack-plugin/backer/7/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/html-webpack-plugin/backer/8/website?requireActive=false" target="_blank"><img src="https://opencollective.com/html-webpack-plugin/backer/8/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/html-webpack-plugin/backer/9/website?requireActive=false" target="_blank"><img src="https://opencollective.com/html-webpack-plugin/backer/9/avatar.svg?requireActive=false"></a>

## Contributors

This project exists thanks to all the people who contribute.

You're free to contribute to this project by submitting [issues](https://github.com/jantimon/html-webpack-plugin/issues) and/or [pull requests](https://github.com/jantimon/html-webpack-plugin/pulls). This project is test-driven, so keep in mind that every change and new feature should be covered by tests.

<a href="https://github.com/jantimon/html-webpack-plugin/graphs/contributors"><img src="https://opencollective.com/html-webpack-plugin/contributors.svg?width=890&button=false" /></a>

[npm]: https://img.shields.io/npm/v/html-webpack-plugin.svg
[npm-url]: https://npmjs.com/package/html-webpack-plugin
[node]: https://img.shields.io/node/v/html-webpack-plugin.svg
[node-url]: https://nodejs.org
[tests]: https://github.com/jantimon/html-webpack-plugin/workflows/CI/badge.svg
[tests-url]: https://github.com/jantimon/html-webpack-plugin/actions?query=workflow%3ACI


---

# Commander.js

[![Build Status](https://github.com/tj/commander.js/workflows/build/badge.svg)](https://github.com/tj/commander.js/actions?query=workflow%3A%22build%22)
[![NPM Version](http://img.shields.io/npm/v/commander.svg?style=flat)](https://www.npmjs.org/package/commander)
[![NPM Downloads](https://img.shields.io/npm/dm/commander.svg?style=flat)](https://npmcharts.com/compare/commander?minimal=true)
[![Install Size](https://packagephobia.now.sh/badge?p=commander)](https://packagephobia.now.sh/result?p=commander)

The complete solution for [node.js](http://nodejs.org) command-line interfaces.

Read this in other languages: English | [简体中文](./Readme_zh-CN.md)

- [Commander.js](#commanderjs)
  - [Installation](#installation)
  - [Declaring _program_ variable](#declaring-program-variable)
  - [Options](#options)
    - [Common option types, boolean and value](#common-option-types-boolean-and-value)
    - [Default option value](#default-option-value)
    - [Other option types, negatable boolean and boolean|value](#other-option-types-negatable-boolean-and-booleanvalue)
    - [Required option](#required-option)
    - [Variadic option](#variadic-option)
    - [Version option](#version-option)
    - [More configuration](#more-configuration)
    - [Custom option processing](#custom-option-processing)
  - [Commands](#commands)
    - [Command-arguments](#command-arguments)
      - [More configuration](#more-configuration-1)
      - [Custom argument processing](#custom-argument-processing)
    - [Action handler](#action-handler)
    - [Stand-alone executable (sub)commands](#stand-alone-executable-subcommands)
    - [Life cycle hooks](#life-cycle-hooks)
  - [Automated help](#automated-help)
    - [Custom help](#custom-help)
    - [Display help after errors](#display-help-after-errors)
    - [Display help from code](#display-help-from-code)
    - [.usage and .name](#usage-and-name)
    - [.helpOption(flags, description)](#helpoptionflags-description)
    - [.addHelpCommand()](#addhelpcommand)
    - [More configuration](#more-configuration-2)
  - [Custom event listeners](#custom-event-listeners)
  - [Bits and pieces](#bits-and-pieces)
    - [.parse() and .parseAsync()](#parse-and-parseasync)
    - [Parsing Configuration](#parsing-configuration)
    - [Legacy options as properties](#legacy-options-as-properties)
    - [TypeScript](#typescript)
    - [createCommand()](#createcommand)
    - [Node options such as `--harmony`](#node-options-such-as---harmony)
    - [Debugging stand-alone executable subcommands](#debugging-stand-alone-executable-subcommands)
    - [Override exit and output handling](#override-exit-and-output-handling)
    - [Additional documentation](#additional-documentation)
  - [Examples](#examples)
  - [Support](#support)
    - [Commander for enterprise](#commander-for-enterprise)

For information about terms used in this document see: [terminology](./docs/terminology.md)

## Installation

```bash
npm install commander
```

## Declaring _program_ variable

Commander exports a global object which is convenient for quick programs.
This is used in the examples in this README for brevity.

```js
const { program } = require('commander');
program.version('0.0.1');
```

For larger programs which may use commander in multiple ways, including unit testing, it is better to create a local Command object to use.

```js
const { Command } = require('commander');
const program = new Command();
program.version('0.0.1');
```

For named imports in ECMAScript modules, import from `commander/esm.mjs`.

```js
// index.mjs
import { Command } from 'commander/esm.mjs';
const program = new Command();
```

And in TypeScript:

```ts
// index.ts
import { Command } from 'commander';
const program = new Command();
```

## Options

Options are defined with the `.option()` method, also serving as documentation for the options. Each option can have a short flag (single character) and a long name, separated by a comma or space or vertical bar ('|').

The parsed options can be accessed by calling `.opts()` on a `Command` object, and are passed to the action handler.
(You can also use `.getOptionValue()` and `.setOptionValue()` to work with a single option value,
and `.getOptionValueSource()` and `.setOptionValueWithSource()` when it matters where the option value came from.)

Multi-word options such as "--template-engine" are camel-cased, becoming `program.opts().templateEngine` etc.

Multiple short flags may optionally be combined in a single argument following the dash: boolean flags, followed by a single option taking a value (possibly followed by the value).
For example `-a -b -p 80` may be written as `-ab -p80` or even `-abp80`.

You can use `--` to indicate the end of the options, and any remaining arguments will be used without being interpreted.

By default options on the command line are not positional, and can be specified before or after other arguments.

### Common option types, boolean and value

The two most used option types are a boolean option, and an option which takes its value
from the following argument (declared with angle brackets like `--expect <value>`). Both are `undefined` unless specified on command line.

Example file: [options-common.js](./examples/options-common.js)

```js
program
  .option('-d, --debug', 'output extra debugging')
  .option('-s, --small', 'small pizza size')
  .option('-p, --pizza-type <type>', 'flavour of pizza');

program.parse(process.argv);

const options = program.opts();
if (options.debug) console.log(options);
console.log('pizza details:');
if (options.small) console.log('- small pizza size');
if (options.pizzaType) console.log(`- ${options.pizzaType}`);
```

```bash
$ pizza-options -p
error: option '-p, --pizza-type <type>' argument missing
$ pizza-options -d -s -p vegetarian
{ debug: true, small: true, pizzaType: 'vegetarian' }
pizza details:
- small pizza size
- vegetarian
$ pizza-options --pizza-type=cheese
pizza details:
- cheese
```

`program.parse(arguments)` processes the arguments, leaving any args not consumed by the program options in the `program.args` array. The parameter is optional and defaults to `process.argv`.

### Default option value

You can specify a default value for an option which takes a value.

Example file: [options-defaults.js](./examples/options-defaults.js)

```js
program
  .option('-c, --cheese <type>', 'add the specified type of cheese', 'blue');

program.parse();

console.log(`cheese: ${program.opts().cheese}`);
```

```bash
$ pizza-options
cheese: blue
$ pizza-options --cheese stilton
cheese: stilton
```

### Other option types, negatable boolean and boolean|value

You can define a boolean option long name with a leading `no-` to set the option value to false when used.
Defined alone this also makes the option true by default.

If you define `--foo` first, adding `--no-foo` does not change the default value from what it would
otherwise be. You can specify a default boolean value for a boolean option and it can be overridden on command line.

Example file: [options-negatable.js](./examples/options-negatable.js)

```js
program
  .option('--no-sauce', 'Remove sauce')
  .option('--cheese <flavour>', 'cheese flavour', 'mozzarella')
  .option('--no-cheese', 'plain with no cheese')
  .parse();

const options = program.opts();
const sauceStr = options.sauce ? 'sauce' : 'no sauce';
const cheeseStr = (options.cheese === false) ? 'no cheese' : `${options.cheese} cheese`;
console.log(`You ordered a pizza with ${sauceStr} and ${cheeseStr}`);
```

```bash
$ pizza-options
You ordered a pizza with sauce and mozzarella cheese
$ pizza-options --sauce
error: unknown option '--sauce'
$ pizza-options --cheese=blue
You ordered a pizza with sauce and blue cheese
$ pizza-options --no-sauce --no-cheese
You ordered a pizza with no sauce and no cheese
```

You can specify an option which may be used as a boolean option but may optionally take an option-argument
(declared with square brackets like `--optional [value]`).

Example file: [options-boolean-or-value.js](./examples/options-boolean-or-value.js)

```js
program
  .option('-c, --cheese [type]', 'Add cheese with optional type');

program.parse(process.argv);

const options = program.opts();
if (options.cheese === undefined) console.log('no cheese');
else if (options.cheese === true) console.log('add cheese');
else console.log(`add cheese type ${options.cheese}`);
```

```bash
$ pizza-options
no cheese
$ pizza-options --cheese
add cheese
$ pizza-options --cheese mozzarella
add cheese type mozzarella
```

For information about possible ambiguous cases, see [options taking varying arguments](./docs/options-taking-varying-arguments.md).

### Required option

You may specify a required (mandatory) option using `.requiredOption`. The option must have a value after parsing, usually specified on the command line, or perhaps from a default value (say from environment). The method is otherwise the same as `.option` in format, taking flags and description, and optional default value or custom processing.

Example file: [options-required.js](./examples/options-required.js)

```js
program
  .requiredOption('-c, --cheese <type>', 'pizza must have cheese');

program.parse();
```

```bash
$ pizza
error: required option '-c, --cheese <type>' not specified
```

### Variadic option

You may make an option variadic by appending `...` to the value placeholder when declaring the option. On the command line you
can then specify multiple option-arguments, and the parsed option value will be an array. The extra arguments
are read until the first argument starting with a dash. The special argument `--` stops option processing entirely. If a value
is specified in the same argument as the option then no further values are read.

Example file: [options-variadic.js](./examples/options-variadic.js)

```js
program
  .option('-n, --number <numbers...>', 'specify numbers')
  .option('-l, --letter [letters...]', 'specify letters');

program.parse();

console.log('Options: ', program.opts());
console.log('Remaining arguments: ', program.args);
```

```bash
$ collect -n 1 2 3 --letter a b c
Options:  { number: [ '1', '2', '3' ], letter: [ 'a', 'b', 'c' ] }
Remaining arguments:  []
$ collect --letter=A -n80 operand
Options:  { number: [ '80' ], letter: [ 'A' ] }
Remaining arguments:  [ 'operand' ]
$ collect --letter -n 1 -n 2 3 -- operand
Options:  { number: [ '1', '2', '3' ], letter: true }
Remaining arguments:  [ 'operand' ]
```

For information about possible ambiguous cases, see [options taking varying arguments](./docs/options-taking-varying-arguments.md).

### Version option

The optional `version` method adds handling for displaying the command version. The default option flags are `-V` and `--version`, and when present the command prints the version number and exits.

```js
program.version('0.0.1');
```

```bash
$ ./examples/pizza -V
0.0.1
```

You may change the flags and description by passing additional parameters to the `version` method, using
the same syntax for flags as the `option` method.

```js
program.version('0.0.1', '-v, --vers', 'output the current version');
```

### More configuration

You can add most options using the `.option()` method, but there are some additional features available
by constructing an `Option` explicitly for less common cases.

Example files: [options-extra.js](./examples/options-extra.js), [options-env.js](./examples/options-env.js)

```js
program
  .addOption(new Option('-s, --secret').hideHelp())
  .addOption(new Option('-t, --timeout <delay>', 'timeout in seconds').default(60, 'one minute'))
  .addOption(new Option('-d, --drink <size>', 'drink size').choices(['small', 'medium', 'large']))
  .addOption(new Option('-p, --port <number>', 'port number').env('PORT'));
```

```bash
$ extra --help
Usage: help [options]

Options:
  -t, --timeout <delay>  timeout in seconds (default: one minute)
  -d, --drink <size>     drink cup size (choices: "small", "medium", "large")
  -p, --port <number>    port number (env: PORT)
  -h, --help             display help for command

$ extra --drink huge
error: option '-d, --drink <size>' argument 'huge' is invalid. Allowed choices are small, medium, large.

$ PORT=80 extra 
Options:  { timeout: 60, port: '80' }
```

### Custom option processing

You may specify a function to do custom processing of option-arguments. The callback function receives two parameters,
the user specified option-argument and the previous value for the option. It returns the new value for the option.

This allows you to coerce the option-argument to the desired type, or accumulate values, or do entirely custom processing.

You can optionally specify the default/starting value for the option after the function parameter.

Example file: [options-custom-processing.js](./examples/options-custom-processing.js)

```js
function myParseInt(value, dummyPrevious) {
  // parseInt takes a string and a radix
  const parsedValue = parseInt(value, 10);
  if (isNaN(parsedValue)) {
    throw new commander.InvalidArgumentError('Not a number.');
  }
  return parsedValue;
}

function increaseVerbosity(dummyValue, previous) {
  return previous + 1;
}

function collect(value, previous) {
  return previous.concat([value]);
}

function commaSeparatedList(value, dummyPrevious) {
  return value.split(',');
}

program
  .option('-f, --float <number>', 'float argument', parseFloat)
  .option('-i, --integer <number>', 'integer argument', myParseInt)
  .option('-v, --verbose', 'verbosity that can be increased', increaseVerbosity, 0)
  .option('-c, --collect <value>', 'repeatable value', collect, [])
  .option('-l, --list <items>', 'comma separated list', commaSeparatedList)
;

program.parse();

const options = program.opts();
if (options.float !== undefined) console.log(`float: ${options.float}`);
if (options.integer !== undefined) console.log(`integer: ${options.integer}`);
if (options.verbose > 0) console.log(`verbosity: ${options.verbose}`);
if (options.collect.length > 0) console.log(options.collect);
if (options.list !== undefined) console.log(options.list);
```

```bash
$ custom -f 1e2
float: 100
$ custom --integer 2
integer: 2
$ custom -v -v -v
verbose: 3
$ custom -c a -c b -c c
[ 'a', 'b', 'c' ]
$ custom --list x,y,z
[ 'x', 'y', 'z' ]
```

## Commands

You can specify (sub)commands using `.command()` or `.addCommand()`. There are two ways these can be implemented: using an action handler attached to the command, or as a stand-alone executable file (described in more detail later). The subcommands may be nested ([example](./examples/nestedCommands.js)).

In the first parameter to `.command()` you specify the command name. You may append the command-arguments after the command name, or specify them separately using `.argument()`. The arguments may be `<required>` or `[optional]`, and the last argument may also be `variadic...`.

You can use `.addCommand()` to add an already configured subcommand to the program.

For example:

```js
// Command implemented using action handler (description is supplied separately to `.command`)
// Returns new command for configuring.
program
  .command('clone <source> [destination]')
  .description('clone a repository into a newly created directory')
  .action((source, destination) => {
    console.log('clone command called');
  });

// Command implemented using stand-alone executable file, indicated by adding description as second parameter to `.command`.
// Returns `this` for adding more commands.
program
  .command('start <service>', 'start named service')
  .command('stop [service]', 'stop named service, or all if no name supplied');

// Command prepared separately.
// Returns `this` for adding more commands.
program
  .addCommand(build.makeBuildCommand());
```

Configuration options can be passed with the call to `.command()` and `.addCommand()`. Specifying `hidden: true` will
remove the command from the generated help output. Specifying `isDefault: true` will run the subcommand if no other
subcommand is specified ([example](./examples/defaultCommand.js)).

### Command-arguments

For subcommands, you can specify the argument syntax in the call to `.command()` (as shown above). This
is the only method usable for subcommands implemented using a stand-alone executable, but for other subcommands
you can instead use the following method.

To configure a command, you can use `.argument()` to specify each expected command-argument.
You supply the argument name and an optional description. The argument may be `<required>` or `[optional]`.
You can specify a default value for an optional command-argument.

Example file: [argument.js](./examples/argument.js)

```js
program
  .version('0.1.0')
  .argument('<username>', 'user to login')
  .argument('[password]', 'password for user, if required', 'no password given')
  .action((username, password) => {
    console.log('username:', username);
    console.log('password:', password);
  });
```

 The last argument of a command can be variadic, and only the last argument.  To make an argument variadic you
 append `...` to the argument name. A variadic argument is passed to the action handler as an array. For example:

```js
program
  .version('0.1.0')
  .command('rmdir')
  .argument('<dirs...>')
  .action(function (dirs) {
    dirs.forEach((dir) => {
      console.log('rmdir %s', dir);
    });
  });
```

There is a convenience method to add multiple arguments at once, but without descriptions:

```js
program
  .arguments('<username> <password>');
```

#### More configuration

There are some additional features available by constructing an `Argument` explicitly for less common cases.

Example file: [arguments-extra.js](./examples/arguments-extra.js)

```js
program
  .addArgument(new commander.Argument('<drink-size>', 'drink cup size').choices(['small', 'medium', 'large']))
  .addArgument(new commander.Argument('[timeout]', 'timeout in seconds').default(60, 'one minute'))
```

#### Custom argument processing

You may specify a function to do custom processing of command-arguments (like for option-arguments).
The callback function receives two parameters, the user specified command-argument and the previous value for the argument.
It returns the new value for the argument.

The processed argument values are passed to the action handler, and saved as `.processedArgs`.

You can optionally specify the default/starting value for the argument after the function parameter.

Example file: [arguments-custom-processing.js](./examples/arguments-custom-processing.js)

```js
program
  .command('add')
  .argument('<first>', 'integer argument', myParseInt)
  .argument('[second]', 'integer argument', myParseInt, 1000)
  .action((first, second) => {
    console.log(`${first} + ${second} = ${first + second}`);
  })
;
```

### Action handler

The action handler gets passed a parameter for each command-argument you declared, and two additional parameters
which are the parsed options and the command object itself.

Example file: [thank.js](./examples/thank.js)

```js
program
  .argument('<name>')
  .option('-t, --title <honorific>', 'title to use before name')
  .option('-d, --debug', 'display some debugging')
  .action((name, options, command) => {
    if (options.debug) {
      console.error('Called %s with options %o', command.name(), options);
    }
    const title = options.title ? `${options.title} ` : '';
    console.log(`Thank-you ${title}${name}`);
  });
```

You may supply an `async` action handler, in which case you call `.parseAsync` rather than `.parse`.

```js
async function run() { /* code goes here */ }

async function main() {
  program
    .command('run')
    .action(run);
  await program.parseAsync(process.argv);
}
```

A command's options and arguments on the command line are validated when the command is used. Any unknown options or missing arguments will be reported as an error. You can suppress the unknown option checks with `.allowUnknownOption()`. By default it is not an error to
pass more arguments than declared, but you can make this an error with `.allowExcessArguments(false)`.

### Stand-alone executable (sub)commands

When `.command()` is invoked with a description argument, this tells Commander that you're going to use stand-alone executables for subcommands.
Commander will search the executables in the directory of the entry script (like `./examples/pm`) with the name `program-subcommand`, like `pm-install`, `pm-search`.
You can specify a custom name with the `executableFile` configuration option.

You handle the options for an executable (sub)command in the executable, and don't declare them at the top-level.

Example file: [pm](./examples/pm)

```js
program
  .version('0.1.0')
  .command('install [name]', 'install one or more packages')
  .command('search [query]', 'search with optional query')
  .command('update', 'update installed packages', { executableFile: 'myUpdateSubCommand' })
  .command('list', 'list packages installed', { isDefault: true });

program.parse(process.argv);
```

If the program is designed to be installed globally, make sure the executables have proper modes, like `755`.

### Life cycle hooks

You can add callback hooks to a command for life cycle events.

Example file: [hook.js](./examples/hook.js)

```js
program
  .option('-t, --trace', 'display trace statements for commands')
  .hook('preAction', (thisCommand, actionCommand) => {
    if (thisCommand.opts().trace) {
      console.log(`About to call action handler for subcommand: ${actionCommand.name()}`);
      console.log('arguments: %O', actionCommand.args);
      console.log('options: %o', actionCommand.opts());
    }
  });
```

The callback hook can be `async`, in which case you call `.parseAsync` rather than `.parse`. You can add multiple hooks per event.

The supported events are:

- `preAction`: called before action handler for this command and its subcommands
- `postAction`: called after action handler for this command and its subcommands

The hook is passed the command it was added to, and the command running the action handler.

## Automated help

The help information is auto-generated based on the information commander already knows about your program. The default
help option is `-h,--help`.

Example file: [pizza](./examples/pizza)

```bash
$ node ./examples/pizza --help
Usage: pizza [options]

An application for pizza ordering

Options:
  -p, --peppers        Add peppers
  -c, --cheese <type>  Add the specified type of cheese (default: "marble")
  -C, --no-cheese      You do not want any cheese
  -h, --help           display help for command
```

A `help` command is added by default if your command has subcommands. It can be used alone, or with a subcommand name to show
further help for the subcommand. These are effectively the same if the `shell` program has implicit help:

```bash
shell help
shell --help

shell help spawn
shell spawn --help
```

### Custom help

You can add extra text to be displayed along with the built-in help.

Example file: [custom-help](./examples/custom-help)

```js
program
  .option('-f, --foo', 'enable some foo');

program.addHelpText('after', `

Example call:
  $ custom-help --help`);
```

Yields the following help output:

```Text
Usage: custom-help [options]

Options:
  -f, --foo   enable some foo
  -h, --help  display help for command

Example call:
  $ custom-help --help
```

The positions in order displayed are:

- `beforeAll`: add to the program for a global banner or header
- `before`: display extra information before built-in help
- `after`: display extra information after built-in help
- `afterAll`: add to the program for a global footer (epilog)

The positions "beforeAll" and "afterAll" apply to the command and all its subcommands.

The second parameter can be a string, or a function returning a string. The function is passed a context object for your convenience. The properties are:

- error: a boolean for whether the help is being displayed due to a usage error
- command: the Command which is displaying the help

### Display help after errors

The default behaviour for usage errors is to just display a short error message.
You can change the behaviour to show the full help or a custom help message after an error.

```js
program.showHelpAfterError();
// or
program.showHelpAfterError('(add --help for additional information)');
```

```sh
$ pizza --unknown
error: unknown option '--unknown'
(add --help for additional information)
```

You can also show suggestions after an error for an unknown command or option.

```js
program.showSuggestionAfterError();
```

```sh
$ pizza --hepl
error: unknown option '--hepl'
(Did you mean --help?)
```

### Display help from code

`.help()`: display help information and exit immediately. You can optionally pass `{ error: true }` to display on stderr and exit with an error status.

`.outputHelp()`: output help information without exiting. You can optionally pass `{ error: true }` to display on stderr.

`.helpInformation()`: get the built-in command help information as a string for processing or displaying yourself.

### .usage and .name

These allow you to customise the usage description in the first line of the help. The name is otherwise
deduced from the (full) program arguments. Given:

```js
program
  .name("my-command")
  .usage("[global options] command")
```

The help will start with:

```Text
Usage: my-command [global options] command
```

### .helpOption(flags, description)

By default every command has a help option. Override the default help flags and description. Pass false to disable the built-in help option.

```js
program
  .helpOption('-e, --HELP', 'read more information');
```

### .addHelpCommand()

A help command is added by default if your command has subcommands. You can explicitly turn on or off the implicit help command with `.addHelpCommand()` and `.addHelpCommand(false)`.

You can both turn on and customise the help command by supplying the name and description:

```js
program.addHelpCommand('assist [command]', 'show assistance');
```

### More configuration

The built-in help is formatted using the Help class.
You can configure the Help behaviour by modifying data properties and methods using `.configureHelp()`, or by subclassing using `.createHelp()` if you prefer.

The data properties are:

- `helpWidth`: specify the wrap width, useful for unit tests
- `sortSubcommands`: sort the subcommands alphabetically
- `sortOptions`: sort the options alphabetically

There are methods getting the visible lists of arguments, options, and subcommands. There are methods for formatting the items in the lists, with each item having a _term_ and _description_. Take a look at `.formatHelp()` to see how they are used.

Example file: [configure-help.js](./examples/configure-help.js)

```js
program.configureHelp({
  sortSubcommands: true,
  subcommandTerm: (cmd) => cmd.name() // Just show the name, instead of short usage.
});
```

## Custom event listeners

You can execute custom actions by listening to command and option events.

```js
program.on('option:verbose', function () {
  process.env.VERBOSE = this.opts().verbose;
});
```

## Bits and pieces

### .parse() and .parseAsync()

The first argument to `.parse` is the array of strings to parse. You may omit the parameter to implicitly use `process.argv`.

If the arguments follow different conventions than node you can pass a `from` option in the second parameter:

- 'node': default, `argv[0]` is the application and `argv[1]` is the script being run, with user parameters after that
- 'electron': `argv[1]` varies depending on whether the electron application is packaged
- 'user': all of the arguments from the user

For example:

```js
program.parse(process.argv); // Explicit, node conventions
program.parse(); // Implicit, and auto-detect electron
program.parse(['-f', 'filename'], { from: 'user' });
```

### Parsing Configuration

If the default parsing does not suit your needs, there are some behaviours to support other usage patterns.

By default program options are recognised before and after subcommands. To only look for program options before subcommands, use `.enablePositionalOptions()`. This lets you use
an option for a different purpose in subcommands.

Example file: [positional-options.js](./examples/positional-options.js)

With positional options, the `-b` is a program option in the first line and a subcommand option in the second line:

```sh
program -b subcommand
program subcommand -b
```

By default options are recognised before and after command-arguments. To only process options that come
before the command-arguments, use `.passThroughOptions()`. This lets you pass the  arguments and following options through to another program
without needing to use `--` to end the option processing.
To use pass through options in a subcommand, the program needs to enable positional options.

Example file: [pass-through-options.js](./examples/pass-through-options.js)

With pass through options, the `--port=80` is a program option in the first line and passed through as a command-argument in the second line:

```sh
program --port=80 arg
program arg --port=80
```

By default the option processing shows an error for an unknown option. To have an unknown option treated as an ordinary command-argument and continue looking for options, use `.allowUnknownOption()`. This lets you mix known and unknown options.

By default the argument processing does not display an error for more command-arguments than expected.
To display an error for excess arguments, use`.allowExcessArguments(false)`.

### Legacy options as properties

Before Commander 7, the option values were stored as properties on the command.
This was convenient to code but the downside was possible clashes with
existing properties of `Command`. You can revert to the old behaviour to run unmodified legacy code by using `.storeOptionsAsProperties()`.

```js
program
  .storeOptionsAsProperties()
  .option('-d, --debug')
  .action((commandAndOptions) => {
    if (commandAndOptions.debug) {
      console.error(`Called ${commandAndOptions.name()}`);
    }
  });
```

### TypeScript

If you use `ts-node` and  stand-alone executable subcommands written as `.ts` files, you need to call your program through node to get the subcommands called correctly. e.g.

```bash
node -r ts-node/register pm.ts
```

### createCommand()

This factory function creates a new command. It is exported and may be used instead of using `new`, like:

```js
const { createCommand } = require('commander');
const program = createCommand();
```

`createCommand` is also a method of the Command object, and creates a new command rather than a subcommand. This gets used internally
when creating subcommands using `.command()`, and you may override it to
customise the new subcommand (example file [custom-command-class.js](./examples/custom-command-class.js)).

### Node options such as `--harmony`

You can enable `--harmony` option in two ways:

- Use `#! /usr/bin/env node --harmony` in the subcommands scripts. (Note Windows does not support this pattern.)
- Use the `--harmony` option when call the command, like `node --harmony examples/pm publish`. The `--harmony` option will be preserved when spawning subcommand process.

### Debugging stand-alone executable subcommands

An executable subcommand is launched as a separate child process.

If you are using the node inspector for [debugging](https://nodejs.org/en/docs/guides/debugging-getting-started/) executable subcommands using `node --inspect` et al,
the inspector port is incremented by 1 for the spawned subcommand.

If you are using VSCode to debug executable subcommands you need to set the `"autoAttachChildProcesses": true` flag in your launch.json configuration.

### Override exit and output handling

By default Commander calls `process.exit` when it detects errors, or after displaying the help or version. You can override
this behaviour and optionally supply a callback. The default override throws a `CommanderError`.

The override callback is passed a `CommanderError` with properties `exitCode` number, `code` string, and `message`. The default override behaviour is to throw the error, except for async handling of executable subcommand completion which carries on. The normal display of error messages or version or help
is not affected by the override which is called after the display.

```js
program.exitOverride();

try {
  program.parse(process.argv);
} catch (err) {
  // custom processing...
}
```

By default Commander is configured for a command-line application and writes to stdout and stderr.
You can modify this behaviour for custom applications. In addition, you can modify the display of error messages.

Example file: [configure-output.js](./examples/configure-output.js)

```js
function errorColor(str) {
  // Add ANSI escape codes to display text in red.
  return `\x1b[31m${str}\x1b[0m`;
}

program
  .configureOutput({
    // Visibly override write routines as example!
    writeOut: (str) => process.stdout.write(`[OUT] ${str}`),
    writeErr: (str) => process.stdout.write(`[ERR] ${str}`),
    // Highlight errors in color.
    outputError: (str, write) => write(errorColor(str))
  });
```

### Additional documentation

There is more information available about:

- [deprecated](./docs/deprecated.md) features still supported for backwards compatibility
- [options taking varying arguments](./docs/options-taking-varying-arguments.md)

## Examples

In a single command program, you might not need an action handler.

Example file: [pizza](./examples/pizza)

```js
const { program } = require('commander');

program
  .description('An application for pizza ordering')
  .option('-p, --peppers', 'Add peppers')
  .option('-c, --cheese <type>', 'Add the specified type of cheese', 'marble')
  .option('-C, --no-cheese', 'You do not want any cheese');

program.parse();

const options = program.opts();
console.log('you ordered a pizza with:');
if (options.peppers) console.log('  - peppers');
const cheese = !options.cheese ? 'no' : options.cheese;
console.log('  - %s cheese', cheese);
```

In a multi-command program, you will have action handlers for each command (or stand-alone executables for the commands).

Example file: [deploy](./examples/deploy)

```js
const { Command } = require('commander');
const program = new Command();

program
  .version('0.0.1')
  .option('-c, --config <path>', 'set config path', './deploy.conf');

program
  .command('setup [env]')
  .description('run setup commands for all envs')
  .option('-s, --setup_mode <mode>', 'Which setup mode to use', 'normal')
  .action((env, options) => {
    env = env || 'all';
    console.log('read config from %s', program.opts().config);
    console.log('setup for %s env(s) with %s mode', env, options.setup_mode);
  });

program
  .command('exec <script>')
  .alias('ex')
  .description('execute the given remote cmd')
  .option('-e, --exec_mode <mode>', 'Which exec mode to use', 'fast')
  .action((script, options) => {
    console.log('read config from %s', program.opts().config);
    console.log('exec "%s" using %s mode and config %s', script, options.exec_mode, program.opts().config);
  }).addHelpText('after', `
Examples:
  $ deploy exec sequential
  $ deploy exec async`
  );

program.parse(process.argv);
```

More samples can be found in the [examples](https://github.com/tj/commander.js/tree/master/examples) directory.

## Support

The current version of Commander is fully supported on Long Term Support versions of node, and requires at least node v12.
(For older versions of node, use an older version of Commander. Commander version 2.x has the widest support.)

The main forum for free and community support is the project [Issues](https://github.com/tj/commander.js/issues) on GitHub.

### Commander for enterprise

Available as part of the Tidelift Subscription

The maintainers of Commander and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-commander?utm_source=npm-commander&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)


---

# HTMLMinifier

[![NPM version](https://img.shields.io/npm/v/html-minifier-terser.svg)](https://www.npmjs.com/package/html-minifier-terser)
[![Build Status](https://github.com/terser/html-minifier-terser/workflows/CI/badge.svg)](https://github.com/terser/html-minifier-terser/actions?workflow=CI)

[HTMLMinifier](https://terser.org/html-minifier-terser/) is a highly **configurable**, **well-tested**, JavaScript-based HTML minifier.

See [corresponding blog post](http://perfectionkills.com/experimenting-with-html-minifier/) for all the gory details of [how it works](http://perfectionkills.com/experimenting-with-html-minifier/#how_it_works), [description of each option](http://perfectionkills.com/experimenting-with-html-minifier/#options), [testing results](http://perfectionkills.com/experimenting-with-html-minifier/#field_testing) and [conclusions](http://perfectionkills.com/experimenting-with-html-minifier/#cost_and_benefits).

[Test suite is available online](https://terser.org/html-minifier-terser/tests/).

Also see corresponding [Ruby wrapper](https://github.com/stereobooster/html_minifier), and for Node.js, [Grunt plugin](https://github.com/gruntjs/grunt-contrib-htmlmin), [Gulp module](https://github.com/jonschlinkert/gulp-htmlmin), [Koa middleware wrapper](https://github.com/koajs/html-minifier) and [Express middleware wrapper](https://github.com/melonmanchan/express-minify-html).

For lint-like capabilities take a look at [HTMLLint](https://github.com/kangax/html-lint).

## Minification comparison

How does HTMLMinifier compare to other solutions — [HTML Minifier from Will Peavy](http://www.willpeavy.com/minifier/) (1st result in [Google search for "html minifier"](https://www.google.com/#q=html+minifier)) as well as [htmlcompressor.com](http://htmlcompressor.com) and [minimize](https://github.com/Swaagie/minimize)?

| Site                                                                         | Original size *(KB)* | HTMLMinifier | minimize | Will Peavy | htmlcompressor.com |
| ---------------------------------------------------------------------------- |:--------------------:| ------------:| --------:| ----------:| ------------------:|
| [Google](https://www.google.com/)                                            | 45                   | **41**       | 45       | 46         | 45                 |
| [Stack Overflow](https://stackoverflow.com/)                                 | 115                  | **82**       | 90       | 92         | 88                 |
| [HTMLMinifier](https://github.com/kangax/html-minifier)                      | 132                  | **105**      | 118      | 123        | 118                |
| [Bootstrap CSS](https://getbootstrap.com/docs/3.3/css/)                      | 271                  | **260**      | 269      | 229        | 269                |
| [Twitter](https://twitter.com/)                                              | 289                  | **238**      | 282      | 314        | 282                |
| [BBC](https://www.bbc.co.uk/)                                                | 298                  | **233**      | 289      | 291        | 269                |
| [Wikipedia](https://en.wikipedia.org/wiki/President_of_the_United_States)    | 574                  | **468**      | 557      | 578        | 557                |
| [Amazon](https://www.amazon.co.uk/)                                          | 702                  | **343**      | 692      | 704        | n/a                |
| [NBC](https://www.nbc.com/)                                                  | 844                  | **805**      | 843      | 844        | n/a                |
| [Eloquent Javascript](https://eloquentjavascript.net/1st_edition/print.html) | 870                  | **815**      | 840      | 864        | n/a                |
| [New York Times](https://www.nytimes.com/)                                   | 1304                 | **1183**     | 1301     | 1295       | n/a                |
| [ES draft](https://tc39.github.io/ecma262/)                                  | 6347                 | **5686**     | 5863     | n/a        | n/a                |

## Options Quick Reference

Most of the options are disabled by default.

| Option                         | Description     | Default |
|--------------------------------|-----------------|---------|
| `caseSensitive`                | Treat attributes in case sensitive manner (useful for custom HTML tags) | `false` |
| `collapseBooleanAttributes`    | [Omit attribute values from boolean attributes](http://perfectionkills.com/experimenting-with-html-minifier/#collapse_boolean_attributes) | `false` |
| `collapseInlineTagWhitespace`  | Don't leave any spaces between `display:inline;` elements when collapsing. Must be used in conjunction with `collapseWhitespace=true` | `false` |
| `collapseWhitespace`           | [Collapse white space that contributes to text nodes in a document tree](http://perfectionkills.com/experimenting-with-html-minifier/#collapse_whitespace) | `false` |
| `conservativeCollapse`         | Always collapse to 1 space (never remove it entirely). Must be used in conjunction with `collapseWhitespace=true` | `false` |
| `continueOnParseError`         | [Handle parse errors](https://html.spec.whatwg.org/multipage/parsing.html#parse-errors) instead of aborting. | `false` |
| `customAttrAssign`             | Arrays of regex'es that allow to support custom attribute assign expressions (e.g. `'<div flex?="{{mode != cover}}"></div>'`) | `[ ]` |
| `customAttrCollapse`           | Regex that specifies custom attribute to strip newlines from (e.g. `/ng-class/`) | |
| `customAttrSurround`           | Arrays of regex'es that allow to support custom attribute surround expressions (e.g. `<input {{#if value}}checked="checked"{{/if}}>`) | `[ ]` |
| `customEventAttributes`        | Arrays of regex'es that allow to support custom event attributes for `minifyJS` (e.g. `ng-click`) | `[ /^on[a-z]{3,}$/ ]` |
| `decodeEntities`               | Use direct Unicode characters whenever possible | `false` |
| `html5`                        | Parse input according to HTML5 specifications | `true` |
| `ignoreCustomComments`         | Array of regex'es that allow to ignore certain comments, when matched | `[ /^!/, /^\s*#/ ]` |
| `ignoreCustomFragments`        | Array of regex'es that allow to ignore certain fragments, when matched (e.g. `<?php ... ?>`, `{{ ... }}`, etc.)  | `[ /<%[\s\S]*?%>/, /<\?[\s\S]*?\?>/ ]` |
| `includeAutoGeneratedTags`     | Insert tags generated by HTML parser | `true` |
| `keepClosingSlash`             | Keep the trailing slash on singleton elements | `false` |
| `maxLineLength`                | Specify a maximum line length. Compressed output will be split by newlines at valid HTML split-points |
| `minifyCSS`                    | Minify CSS in style elements and style attributes (uses [clean-css](https://github.com/jakubpawlowicz/clean-css)) | `false` (could be `true`, `Object`, `Function(text, type)`) |
| `minifyJS`                     | Minify JavaScript in script elements and event attributes (uses [Terser](https://github.com/terser/terser)) | `false` (could be `true`, `Object`, `Function(text, inline)`) |
| `minifyURLs`                   | Minify URLs in various attributes (uses [relateurl](https://github.com/stevenvachon/relateurl)) | `false` (could be `String`, `Object`, `Function(text)`) |
| `noNewlinesBeforeTagClose`     | Never add a newline before a tag that closes an element | `false` |
| `preserveLineBreaks`           | Always collapse to 1 line break (never remove it entirely) when whitespace between tags include a line break. Must be used in conjunction with `collapseWhitespace=true` | `false` |
| `preventAttributesEscaping`    | Prevents the escaping of the values of attributes | `false` |
| `processConditionalComments`   | Process contents of conditional comments through minifier | `false` |
| `processScripts`               | Array of strings corresponding to types of script elements to process through minifier (e.g. `text/ng-template`, `text/x-handlebars-template`, etc.) | `[ ]` |
| `quoteCharacter`               | Type of quote to use for attribute values (' or ") | |
| `removeAttributeQuotes`        | [Remove quotes around attributes when possible](http://perfectionkills.com/experimenting-with-html-minifier/#remove_attribute_quotes) | `false` |
| `removeComments`               | [Strip HTML comments](http://perfectionkills.com/experimenting-with-html-minifier/#remove_comments) | `false` |
| `removeEmptyAttributes`        | [Remove all attributes with whitespace-only values](http://perfectionkills.com/experimenting-with-html-minifier/#remove_empty_or_blank_attributes) | `false` (could be `true`, `Function(attrName, tag)`) |
| `removeEmptyElements`          | [Remove all elements with empty contents](http://perfectionkills.com/experimenting-with-html-minifier/#remove_empty_elements) | `false` |
| `removeOptionalTags`           | [Remove optional tags](http://perfectionkills.com/experimenting-with-html-minifier/#remove_optional_tags) | `false` |
| `removeRedundantAttributes`    | [Remove attributes when value matches default.](http://perfectionkills.com/experimenting-with-html-minifier/#remove_redundant_attributes) | `false` |
| `removeScriptTypeAttributes`   | Remove `type="text/javascript"` from `script` tags. Other `type` attribute values are left intact | `false` |
| `removeStyleLinkTypeAttributes`| Remove `type="text/css"` from `style` and `link` tags. Other `type` attribute values are left intact | `false` |
| `removeTagWhitespace`          | Remove space between attributes whenever possible. **Note that this will result in invalid HTML!** | `false` |
| `sortAttributes`               | [Sort attributes by frequency](#sorting-attributes--style-classes) | `false` |
| `sortClassName`                | [Sort style classes by frequency](#sorting-attributes--style-classes) | `false` |
| `trimCustomFragments`          | Trim white space around `ignoreCustomFragments`. | `false` |
| `useShortDoctype`              | [Replaces the `doctype` with the short (HTML5) doctype](http://perfectionkills.com/experimenting-with-html-minifier/#use_short_doctype) | `false` |

### Sorting attributes / style classes

Minifier options like `sortAttributes` and `sortClassName` won't impact the plain-text size of the output. However, they form long repetitive chains of characters that should improve compression ratio of gzip used in HTTP compression.

## Special cases

### Ignoring chunks of markup

If you have chunks of markup you would like preserved, you can wrap them `<!-- htmlmin:ignore -->`.

### Preserving SVG tags

SVG tags are automatically recognized, and when they are minified, both case-sensitivity and closing-slashes are preserved, regardless of the minification settings used for the rest of the file.

### Working with invalid markup

HTMLMinifier **can't work with invalid or partial chunks of markup**. This is because it parses markup into a tree structure, then modifies it (removing anything that was specified for removal, ignoring anything that was specified to be ignored, etc.), then it creates a markup out of that tree and returns it.

Input markup (e.g. `<p id="">foo`)

↓

Internal representation of markup in a form of tree (e.g. `{ tag: "p", attr: "id", children: ["foo"] }`)

↓

Transformation of internal representation (e.g. removal of `id` attribute)

↓

Output of resulting markup (e.g. `<p>foo</p>`)

HTMLMinifier can't know that original markup was only half of the tree; it does its best to try to parse it as a full tree and it loses information about tree being malformed or partial in the beginning. As a result, it can't create a partial/malformed tree at the time of the output.

## Installation Instructions

From NPM for use as a command line app:

```shell
npm install html-minifier-terser -g
```

From NPM for programmatic use:

```shell
npm install html-minifier-terser
```

From Git:

```shell
git clone git://github.com/terser/html-minifier-terser.git
cd html-minifier-terser
npm link .
```

## Usage

Note that almost all options are disabled by default. For command line usage please see `html-minifier-terser --help` for a list of available options. Experiment and find what works best for you and your project.

- **Sample command line:** `html-minifier-terser --collapse-whitespace --remove-comments --remove-optional-tags --remove-redundant-attributes --remove-script-type-attributes --remove-tag-whitespace --use-short-doctype --minify-css true --minify-js true`

### Node.js

```js
const { minify } = require('html-minifier-terser');

const result = await minify('<p title="blah" id="moo">foo</p>', {
  removeAttributeQuotes: true
});
result; // '<p title=blah id=moo>foo</p>'
```

## Running benchmarks

Benchmarks for minified HTML:

```shell
node benchmark.js
```

## Running local server

```shell
npm run serve
```


---

# htmlparser2

[![NPM version](https://img.shields.io/npm/v/htmlparser2.svg)](https://npmjs.org/package/htmlparser2)
[![Downloads](https://img.shields.io/npm/dm/htmlparser2.svg)](https://npmjs.org/package/htmlparser2)
[![Node.js CI](https://github.com/fb55/htmlparser2/actions/workflows/nodejs-test.yml/badge.svg)](https://github.com/fb55/htmlparser2/actions/workflows/nodejs-test.yml)
[![Coverage](https://img.shields.io/coveralls/fb55/htmlparser2.svg)](https://coveralls.io/r/fb55/htmlparser2)

The fast & forgiving HTML/XML parser.

_htmlparser2 is [the fastest HTML parser](#performance), and takes some shortcuts to get there. If you need strict HTML spec compliance, have a look at [parse5](https://github.com/inikulin/parse5)._

## Installation

    npm install htmlparser2

A live demo of `htmlparser2` is available [on AST Explorer](https://astexplorer.net/#/2AmVrGuGVJ).

## Ecosystem

| Name                                                          | Description                                             |
| ------------------------------------------------------------- | ------------------------------------------------------- |
| [htmlparser2](https://github.com/fb55/htmlparser2)            | Fast & forgiving HTML/XML parser                        |
| [domhandler](https://github.com/fb55/domhandler)              | Handler for htmlparser2 that turns documents into a DOM |
| [domutils](https://github.com/fb55/domutils)                  | Utilities for working with domhandler's DOM             |
| [css-select](https://github.com/fb55/css-select)              | CSS selector engine, compatible with domhandler's DOM   |
| [cheerio](https://github.com/cheeriojs/cheerio)               | The jQuery API for domhandler's DOM                     |
| [dom-serializer](https://github.com/cheeriojs/dom-serializer) | Serializer for domhandler's DOM                         |

## Usage

`htmlparser2` itself provides a callback interface that allows consumption of documents with minimal allocations.
For a more ergonomic experience, read [Getting a DOM](#getting-a-dom) below.

```js
import * as htmlparser2 from "htmlparser2";

const parser = new htmlparser2.Parser({
    onopentag(name, attributes) {
        /*
         * This fires when a new tag is opened.
         *
         * If you don't need an aggregated `attributes` object,
         * have a look at the `onopentagname` and `onattribute` events.
         */
        if (name === "script" && attributes.type === "text/javascript") {
            console.log("JS! Hooray!");
        }
    },
    ontext(text) {
        /*
         * Fires whenever a section of text was processed.
         *
         * Note that this can fire at any point within text and you might
         * have to stitch together multiple pieces.
         */
        console.log("-->", text);
    },
    onclosetag(tagname) {
        /*
         * Fires when a tag is closed.
         *
         * You can rely on this event only firing when you have received an
         * equivalent opening tag before. Closing tags without corresponding
         * opening tags will be ignored.
         */
        if (tagname === "script") {
            console.log("That's it?!");
        }
    },
});
parser.write(
    "Xyz <script type='text/javascript'>const foo = '<<bar>>';</script>"
);
parser.end();
```

Output (with multiple text events combined):

```
--> Xyz
JS! Hooray!
--> const foo = '<<bar>>';
That's it?!
```

This example only shows three of the possible events.
Read more about the parser, its events and options in the [wiki](https://github.com/fb55/htmlparser2/wiki/Parser-options).

### Usage with streams

While the `Parser` interface closely resembles Node.js streams, it's not a 100% match.
Use the `WritableStream` interface to process a streaming input:

```js
import { WritableStream } from "htmlparser2/lib/WritableStream";

const parserStream = new WritableStream({
    ontext(text) {
        console.log("Streaming:", text);
    },
});

const htmlStream = fs.createReadStream("./my-file.html");
htmlStream.pipe(parserStream).on("finish", () => console.log("done"));
```

## Getting a DOM

The `DomHandler` produces a DOM (document object model) that can be manipulated using the [`DomUtils`](https://github.com/fb55/DomUtils) helper.

```js
import * as htmlparser2 from "htmlparser2";

const dom = htmlparser2.parseDocument(htmlString);
```

The `DomHandler`, while still bundled with this module, was moved to its [own module](https://github.com/fb55/domhandler).
Have a look at that for further information.

## Parsing RSS/RDF/Atom Feeds

```javascript
const feed = htmlparser2.parseFeed(content, options);
```

Note: While the provided feed handler works for most feeds,
you might want to use [danmactough/node-feedparser](https://github.com/danmactough/node-feedparser), which is much better tested and actively maintained.

## Performance

After having some artificial benchmarks for some time, **@AndreasMadsen** published his [`htmlparser-benchmark`](https://github.com/AndreasMadsen/htmlparser-benchmark), which benchmarks HTML parses based on real-world websites.

At the time of writing, the latest versions of all supported parsers show the following performance characteristics on GitHub Actions (sourced from [here](https://github.com/AndreasMadsen/htmlparser-benchmark/blob/e78cd8fc6c2adac08deedd4f274c33537451186b/stats.txt)):

```
htmlparser2        : 2.17215 ms/file ± 3.81587
node-html-parser   : 2.35983 ms/file ± 1.54487
html5parser        : 2.43468 ms/file ± 2.81501
neutron-html5parser: 2.61356 ms/file ± 1.70324
htmlparser2-dom    : 3.09034 ms/file ± 4.77033
html-dom-parser    : 3.56804 ms/file ± 5.15621
libxmljs           : 4.07490 ms/file ± 2.99869
htmljs-parser      : 6.15812 ms/file ± 7.52497
parse5             : 9.70406 ms/file ± 6.74872
htmlparser         : 15.0596 ms/file ± 89.0826
html-parser        : 28.6282 ms/file ± 22.6652
saxes              : 45.7921 ms/file ± 128.691
html5              : 120.844 ms/file ± 153.944
```

## How does this module differ from [node-htmlparser](https://github.com/tautologistics/node-htmlparser)?

In 2011, this module started as a fork of the `htmlparser` module.
`htmlparser2` was rewritten multiple times and, while it maintains an API that's mostly compatible with `htmlparser`, the projects don't share any code anymore.

The parser now provides a callback interface inspired by [sax.js](https://github.com/isaacs/sax-js) (originally targeted at [readabilitySAX](https://github.com/fb55/readabilitysax)).
As a result, old handlers won't work anymore.

The `DefaultHandler` was renamed to clarify its purpose (to `DomHandler`). The old name is still available when requiring `htmlparser2` and your code should work as expected.

The `RssHandler` was replaced with a `getFeed` function that takes a `DomHandler` DOM and returns a feed object. There is a `parseFeed` helper function that can be used to parse a feed from a string.

## Security contact information

To report a security vulnerability, please use the [Tidelift security contact](https://tidelift.com/security).
Tidelift will coordinate the fix and disclosure.

## `htmlparser2` for enterprise

Available as part of the Tidelift Subscription.

The maintainers of `htmlparser2` and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-htmlparser2?utm_source=npm-htmlparser2&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)


---

# Can I cache this? [![Build Status](https://travis-ci.org/kornelski/http-cache-semantics.svg?branch=master)](https://travis-ci.org/kornelski/http-cache-semantics)

`CachePolicy` tells when responses can be reused from a cache, taking into account [HTTP RFC 7234](http://httpwg.org/specs/rfc7234.html) rules for user agents and shared caches.
It also implements [RFC 5861](https://tools.ietf.org/html/rfc5861), implementing `stale-if-error` and `stale-while-revalidate`.
It's aware of many tricky details such as the `Vary` header, proxy revalidation, and authenticated responses.

## Usage

Cacheability of an HTTP response depends on how it was requested, so both `request` and `response` are required to create the policy.

```js
const policy = new CachePolicy(request, response, options);

if (!policy.storable()) {
    // throw the response away, it's not usable at all
    return;
}

// Cache the data AND the policy object in your cache
// (this is pseudocode, roll your own cache (lru-cache package works))
letsPretendThisIsSomeCache.set(
    request.url,
    { policy, response },
    policy.timeToLive()
);
```

```js
// And later, when you receive a new request:
const { policy, response } = letsPretendThisIsSomeCache.get(newRequest.url);

// It's not enough that it exists in the cache, it has to match the new request, too:
if (policy && policy.satisfiesWithoutRevalidation(newRequest)) {
    // OK, the previous response can be used to respond to the `newRequest`.
    // Response headers have to be updated, e.g. to add Age and remove uncacheable headers.
    response.headers = policy.responseHeaders();
    return response;
}
```

It may be surprising, but it's not enough for an HTTP response to be [fresh](#yo-fresh) to satisfy a request. It may need to match request headers specified in `Vary`. Even a matching fresh response may still not be usable if the new request restricted cacheability, etc.

The key method is `satisfiesWithoutRevalidation(newRequest)`, which checks whether the `newRequest` is compatible with the original request and whether all caching conditions are met.

### Constructor options

Request and response must have a `headers` property with all header names in lower case. `url`, `status` and `method` are optional (defaults are any URL, status `200`, and `GET` method).

```js
const request = {
    url: '/',
    method: 'GET',
    headers: {
        accept: '*/*',
    },
};

const response = {
    status: 200,
    headers: {
        'cache-control': 'public, max-age=7234',
    },
};

const options = {
    shared: true,
    cacheHeuristic: 0.1,
    immutableMinTimeToLive: 24 * 3600 * 1000, // 24h
    ignoreCargoCult: false,
};
```

If `options.shared` is `true` (default), then the response is evaluated from a perspective of a shared cache (i.e. `private` is not cacheable and `s-maxage` is respected). If `options.shared` is `false`, then the response is evaluated from a perspective of a single-user cache (i.e. `private` is cacheable and `s-maxage` is ignored). `shared: true` is recommended for HTTP clients.

`options.cacheHeuristic` is a fraction of response's age that is used as a fallback cache duration. The default is 0.1 (10%), e.g. if a file hasn't been modified for 100 days, it'll be cached for 100\*0.1 = 10 days.

`options.immutableMinTimeToLive` is a number of milliseconds to assume as the default time to cache responses with `Cache-Control: immutable`. Note that [per RFC](http://httpwg.org/http-extensions/immutable.html) these can become stale, so `max-age` still overrides the default.

If `options.ignoreCargoCult` is true, common anti-cache directives will be completely ignored if the non-standard `pre-check` and `post-check` directives are present. These two useless directives are most commonly found in bad StackOverflow answers and PHP's "session limiter" defaults.

### `storable()`

Returns `true` if the response can be stored in a cache. If it's `false` then you MUST NOT store either the request or the response.

### `satisfiesWithoutRevalidation(newRequest)`

This is the most important method. Use this method to check whether the cached response is still fresh in the context of the new request.

If it returns `true`, then the given `request` matches the original response this cache policy has been created with, and the response can be reused without contacting the server. Note that the old response can't be returned without being updated, see `responseHeaders()`.

If it returns `false`, then the response may not be matching at all (e.g. it's for a different URL or method), or may require to be refreshed first (see `revalidationHeaders()`).

### `responseHeaders()`

Returns updated, filtered set of response headers to return to clients receiving the cached response. This function is necessary, because proxies MUST always remove hop-by-hop headers (such as `TE` and `Connection`) and update response's `Age` to avoid doubling cache time.

```js
cachedResponse.headers = cachePolicy.responseHeaders(cachedResponse);
```

### `timeToLive()`

Returns approximate time in _milliseconds_ until the response becomes stale (i.e. not fresh).

After that time (when `timeToLive() <= 0`) the response might not be usable without revalidation. However, there are exceptions, e.g. a client can explicitly allow stale responses, so always check with `satisfiesWithoutRevalidation()`.
`stale-if-error` and `stale-while-revalidate` extend the time to live of the cache, that can still be used if stale.

### `toObject()`/`fromObject(json)`

Chances are you'll want to store the `CachePolicy` object along with the cached response. `obj = policy.toObject()` gives a plain JSON-serializable object. `policy = CachePolicy.fromObject(obj)` creates an instance from it.

### Refreshing stale cache (revalidation)

When a cached response has expired, it can be made fresh again by making a request to the origin server. The server may respond with status 304 (Not Modified) without sending the response body again, saving bandwidth.

The following methods help perform the update efficiently and correctly.

#### `revalidationHeaders(newRequest)`

Returns updated, filtered set of request headers to send to the origin server to check if the cached response can be reused. These headers allow the origin server to return status 304 indicating the response is still fresh. All headers unrelated to caching are passed through as-is.

Use this method when updating cache from the origin server.

```js
updateRequest.headers = cachePolicy.revalidationHeaders(updateRequest);
```

#### `revalidatedPolicy(revalidationRequest, revalidationResponse)`

Use this method to update the cache after receiving a new response from the origin server. It returns an object with two keys:

-   `policy` — A new `CachePolicy` with HTTP headers updated from `revalidationResponse`. You can always replace the old cached `CachePolicy` with the new one.
-   `modified` — Boolean indicating whether the response body has changed.
    -   If `false`, then a valid 304 Not Modified response has been received, and you can reuse the old cached response body. This is also affected by `stale-if-error`.
    -   If `true`, you should use new response's body (if present), or make another request to the origin server without any conditional headers (i.e. don't use `revalidationHeaders()` this time) to get the new resource.

```js
// When serving requests from cache:
const { oldPolicy, oldResponse } = letsPretendThisIsSomeCache.get(
    newRequest.url
);

if (!oldPolicy.satisfiesWithoutRevalidation(newRequest)) {
    // Change the request to ask the origin server if the cached response can be used
    newRequest.headers = oldPolicy.revalidationHeaders(newRequest);

    // Send request to the origin server. The server may respond with status 304
    const newResponse = await makeRequest(newRequest);

    // Create updated policy and combined response from the old and new data
    const { policy, modified } = oldPolicy.revalidatedPolicy(
        newRequest,
        newResponse
    );
    const response = modified ? newResponse : oldResponse;

    // Update the cache with the newer/fresher response
    letsPretendThisIsSomeCache.set(
        newRequest.url,
        { policy, response },
        policy.timeToLive()
    );

    // And proceed returning cached response as usual
    response.headers = policy.responseHeaders();
    return response;
}
```

# Yo, FRESH

![satisfiesWithoutRevalidation](fresh.jpg)

## Used by

-   [ImageOptim API](https://imageoptim.com/api), [make-fetch-happen](https://github.com/zkat/make-fetch-happen), [cacheable-request](https://www.npmjs.com/package/cacheable-request) ([got](https://www.npmjs.com/package/got)), [npm/registry-fetch](https://github.com/npm/registry-fetch), [etc.](https://github.com/kornelski/http-cache-semantics/network/dependents)

## Implemented

-   `Cache-Control` response header with all the quirks.
-   `Expires` with check for bad clocks.
-   `Pragma` response header.
-   `Age` response header.
-   `Vary` response header.
-   Default cacheability of statuses and methods.
-   Requests for stale data.
-   Filtering of hop-by-hop headers.
-   Basic revalidation request
-   `stale-if-error`

## Unimplemented

-   Merging of range requests, `If-Range` (but correctly supports them as non-cacheable)
-   Revalidation of multiple representations

### Trusting server `Date`

Per the RFC, the cache should take into account the time between server-supplied `Date` and the time it received the response. The RFC-mandated behavior creates two problems:

 * Servers with incorrectly set timezone may add several hours to cache age (or more, if the clock is completely wrong).
 * Even reasonably correct clocks may be off by a couple of seconds, breaking `max-age=1` trick (which is useful for reverse proxies on high-traffic servers).

Previous versions of this library had an option to ignore the server date if it was "too inaccurate". To support the `max-age=1` trick the library also has to ignore dates that pretty accurate. There's no point of having an option to trust dates that are only a bit inaccurate, so this library won't trust any server dates. `max-age` will be interpreted from the time the response has been received, not from when it has been sent. This will affect only [RFC 1149 networks](https://tools.ietf.org/html/rfc1149).


---

# HTTP Deceiver

[![Build Status](https://secure.travis-ci.org/indutny/http-deceiver.png)](http://travis-ci.org/indutny/http-deceiver)
[![NPM version](https://badge.fury.io/js/http-deceiver.svg)](http://badge.fury.io/js/http-deceiver)

Deceive!

## LICENSE

This software is licensed under the MIT License.

Copyright Fedor Indutny, 2015.

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to permit
persons to whom the Software is furnished to do so, subject to the
following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
USE OR OTHER DEALINGS IN THE SOFTWARE.


---

2.0.0 / 2021-12-17
==================

  * Drop support for Node.js 0.6
  * Remove `I'mateapot` export; use `ImATeapot` instead
  * Remove support for status being non-first argument
  * Rename `UnorderedCollection` constructor to `TooEarly`
  * deps: depd@2.0.0
    - Replace internal `eval` usage with `Function` constructor
    - Use instance methods on `process` to check for listeners
  * deps: statuses@2.0.1
    - Fix messaging casing of `418 I'm a Teapot`
    - Remove code 306
    - Rename `425 Unordered Collection` to standard `425 Too Early`

2021-11-14 / 1.8.1
==================

  * deps: toidentifier@1.0.1

2020-06-29 / 1.8.0
==================

  * Add `isHttpError` export to determine if value is an HTTP error
  * deps: setprototypeof@1.2.0

2019-06-24 / 1.7.3
==================

  * deps: inherits@2.0.4

2019-02-18 / 1.7.2
==================

  * deps: setprototypeof@1.1.1

2018-09-08 / 1.7.1
==================

  * Fix error creating objects in some environments

2018-07-30 / 1.7.0
==================

  * Set constructor name when possible
  * Use `toidentifier` module to make class names
  * deps: statuses@'>= 1.5.0 < 2'

2018-03-29 / 1.6.3
==================

  * deps: depd@~1.1.2
    - perf: remove argument reassignment
  * deps: setprototypeof@1.1.0
  * deps: statuses@'>= 1.4.0 < 2'

2017-08-04 / 1.6.2
==================

  * deps: depd@1.1.1
    - Remove unnecessary `Buffer` loading

2017-02-20 / 1.6.1
==================

  * deps: setprototypeof@1.0.3
    - Fix shim for old browsers

2017-02-14 / 1.6.0
==================

  * Accept custom 4xx and 5xx status codes in factory
  * Add deprecation message to `"I'mateapot"` export
  * Deprecate passing status code as anything except first argument in factory
  * Deprecate using non-error status codes
  * Make `message` property enumerable for `HttpError`s

2016-11-16 / 1.5.1
==================

  * deps: inherits@2.0.3
    - Fix issue loading in browser
  * deps: setprototypeof@1.0.2
  * deps: statuses@'>= 1.3.1 < 2'

2016-05-18 / 1.5.0
==================

  * Support new code `421 Misdirected Request`
  * Use `setprototypeof` module to replace `__proto__` setting
  * deps: statuses@'>= 1.3.0 < 2'
    - Add `421 Misdirected Request`
    - perf: enable strict mode
  * perf: enable strict mode

2016-01-28 / 1.4.0
==================

  * Add `HttpError` export, for `err instanceof createError.HttpError`
  * deps: inherits@2.0.1
  * deps: statuses@'>= 1.2.1 < 2'
    - Fix message for status 451
    - Remove incorrect nginx status code

2015-02-02 / 1.3.1
==================

  * Fix regression where status can be overwritten in `createError` `props`

2015-02-01 / 1.3.0
==================

  * Construct errors using defined constructors from `createError`
  * Fix error names that are not identifiers
    - `createError["I'mateapot"]` is now `createError.ImATeapot`
  * Set a meaningful `name` property on constructed errors

2014-12-09 / 1.2.8
==================

  * Fix stack trace from exported function
  * Remove `arguments.callee` usage

2014-10-14 / 1.2.7
==================

  * Remove duplicate line

2014-10-02 / 1.2.6
==================

  * Fix `expose` to be `true` for `ClientError` constructor

2014-09-28 / 1.2.5
==================

  * deps: statuses@1

2014-09-21 / 1.2.4
==================

  * Fix dependency version to work with old `npm`s

2014-09-21 / 1.2.3
==================

  * deps: statuses@~1.1.0

2014-09-21 / 1.2.2
==================

  * Fix publish error

2014-09-21 / 1.2.1
==================

  * Support Node.js 0.6
  * Use `inherits` instead of `util`

2014-09-09 / 1.2.0
==================

  * Fix the way inheriting functions
  * Support `expose` being provided in properties argument

2014-09-08 / 1.1.0
==================

  * Default status to 500
  * Support provided `error` to extend

2014-09-08 / 1.0.1
==================

  * Fix accepting string message

2014-09-08 / 1.0.0
==================

  * Initial release


---

# http-errors

[![NPM Version][npm-version-image]][npm-url]
[![NPM Downloads][npm-downloads-image]][node-url]
[![Node.js Version][node-image]][node-url]
[![Build Status][ci-image]][ci-url]
[![Test Coverage][coveralls-image]][coveralls-url]

Create HTTP errors for Express, Koa, Connect, etc. with ease.

## Install

This is a [Node.js](https://nodejs.org/en/) module available through the
[npm registry](https://www.npmjs.com/). Installation is done using the
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):

```console
$ npm install http-errors
```

## Example

```js
var createError = require('http-errors')
var express = require('express')
var app = express()

app.use(function (req, res, next) {
  if (!req.user) return next(createError(401, 'Please login to view this page.'))
  next()
})
```

## API

This is the current API, currently extracted from Koa and subject to change.

### Error Properties

- `expose` - can be used to signal if `message` should be sent to the client,
  defaulting to `false` when `status` >= 500
- `headers` - can be an object of header names to values to be sent to the
  client, defaulting to `undefined`. When defined, the key names should all
  be lower-cased
- `message` - the traditional error message, which should be kept short and all
  single line
- `status` - the status code of the error, mirroring `statusCode` for general
  compatibility
- `statusCode` - the status code of the error, defaulting to `500`

### createError([status], [message], [properties])

Create a new error object with the given message `msg`.
The error object inherits from `createError.HttpError`.

```js
var err = createError(404, 'This video does not exist!')
```

- `status: 500` - the status code as a number
- `message` - the message of the error, defaulting to node's text for that status code.
- `properties` - custom properties to attach to the object

### createError([status], [error], [properties])

Extend the given `error` object with `createError.HttpError`
properties. This will not alter the inheritance of the given
`error` object, and the modified `error` object is the
return value.

<!-- eslint-disable no-redeclare -->

```js
fs.readFile('foo.txt', function (err, buf) {
  if (err) {
    if (err.code === 'ENOENT') {
      var httpError = createError(404, err, { expose: false })
    } else {
      var httpError = createError(500, err)
    }
  }
})
```

- `status` - the status code as a number
- `error` - the error object to extend
- `properties` - custom properties to attach to the object

### createError.isHttpError(val)

Determine if the provided `val` is an `HttpError`. This will return `true`
if the error inherits from the `HttpError` constructor of this module or
matches the "duck type" for an error this module creates. All outputs from
the `createError` factory will return `true` for this function, including
if an non-`HttpError` was passed into the factory.

### new createError\[code || name\](\[msg]\))

Create a new error object with the given message `msg`.
The error object inherits from `createError.HttpError`.

```js
var err = new createError.NotFound()
```

- `code` - the status code as a number
- `name` - the name of the error as a "bumpy case", i.e. `NotFound` or `InternalServerError`.

#### List of all constructors

|Status Code|Constructor Name             |
|-----------|-----------------------------|
|400        |BadRequest                   |
|401        |Unauthorized                 |
|402        |PaymentRequired              |
|403        |Forbidden                    |
|404        |NotFound                     |
|405        |MethodNotAllowed             |
|406        |NotAcceptable                |
|407        |ProxyAuthenticationRequired  |
|408        |RequestTimeout               |
|409        |Conflict                     |
|410        |Gone                         |
|411        |LengthRequired               |
|412        |PreconditionFailed           |
|413        |PayloadTooLarge              |
|414        |URITooLong                   |
|415        |UnsupportedMediaType         |
|416        |RangeNotSatisfiable          |
|417        |ExpectationFailed            |
|418        |ImATeapot                    |
|421        |MisdirectedRequest           |
|422        |UnprocessableEntity          |
|423        |Locked                       |
|424        |FailedDependency             |
|425        |TooEarly                     |
|426        |UpgradeRequired              |
|428        |PreconditionRequired         |
|429        |TooManyRequests              |
|431        |RequestHeaderFieldsTooLarge  |
|451        |UnavailableForLegalReasons   |
|500        |InternalServerError          |
|501        |NotImplemented               |
|502        |BadGateway                   |
|503        |ServiceUnavailable           |
|504        |GatewayTimeout               |
|505        |HTTPVersionNotSupported      |
|506        |VariantAlsoNegotiates        |
|507        |InsufficientStorage          |
|508        |LoopDetected                 |
|509        |BandwidthLimitExceeded       |
|510        |NotExtended                  |
|511        |NetworkAuthenticationRequired|

## License

[MIT](LICENSE)

[ci-image]: https://badgen.net/github/checks/jshttp/http-errors/master?label=ci
[ci-url]: https://github.com/jshttp/http-errors/actions?query=workflow%3Aci
[coveralls-image]: https://badgen.net/coveralls/c/github/jshttp/http-errors/master
[coveralls-url]: https://coveralls.io/r/jshttp/http-errors?branch=master
[node-image]: https://badgen.net/npm/node/http-errors
[node-url]: https://nodejs.org/en/download
[npm-downloads-image]: https://badgen.net/npm/dm/http-errors
[npm-url]: https://npmjs.org/package/http-errors
[npm-version-image]: https://badgen.net/npm/v/http-errors
[travis-image]: https://badgen.net/travis/jshttp/http-errors/master
[travis-url]: https://travis-ci.org/jshttp/http-errors


---

Copyright (c) 2015 Tim Caswell (https://github.com/creationix) and other
contributors. All rights reserved.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.


Some files from the tests folder are from joyent/node and mscedex/io.js, a fork
of nodejs/io.js:

- tests/iojs/test-http-parser-durability.js

  This file is from https://github.com/mscdex/io.js/blob/js-http-parser/test/pummel/test-http-parser-durability.js
  with modifications by Jan Schär (jscissr).

  """
  Copyright io.js contributors. All rights reserved.

  Permission is hereby granted, free of charge, to any person obtaining a copy
  of this software and associated documentation files (the "Software"), to
  deal in the Software without restriction, including without limitation the
  rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
  sell copies of the Software, and to permit persons to whom the Software is
  furnished to do so, subject to the following conditions:

  The above copyright notice and this permission notice shall be included in
  all copies or substantial portions of the Software.

  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
  IN THE SOFTWARE.
  """

- tests/fixtures/*
  tests/parallel/*
  tests/testpy/*
  tests/common.js
  tests/test.py
  tests/utils.py

  These files are from https://github.com/nodejs/node with changes by
  Jan Schär (jscissr).

  Node.js is licensed for use as follows:
  
  """
  Copyright Node.js contributors. All rights reserved.

  Permission is hereby granted, free of charge, to any person obtaining a copy
  of this software and associated documentation files (the "Software"), to
  deal in the Software without restriction, including without limitation the
  rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
  sell copies of the Software, and to permit persons to whom the Software is
  furnished to do so, subject to the following conditions:

  The above copyright notice and this permission notice shall be included in
  all copies or substantial portions of the Software.

  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
  IN THE SOFTWARE.
  """

  This license applies to parts of Node.js originating from the
  https://github.com/joyent/node repository:

  """
  Copyright Joyent, Inc. and other Node contributors. All rights reserved.
  Permission is hereby granted, free of charge, to any person obtaining a copy
  of this software and associated documentation files (the "Software"), to
  deal in the Software without restriction, including without limitation the
  rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
  sell copies of the Software, and to permit persons to whom the Software is
  furnished to do so, subject to the following conditions:

  The above copyright notice and this permission notice shall be included in
  all copies or substantial portions of the Software.

  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
  IN THE SOFTWARE.
  """
  

---

![Node](https://github.com/creationix/http-parser-js/workflows/Node/badge.svg)
![Node-v12](https://github.com/creationix/http-parser-js/workflows/Node-v12/badge.svg)

# HTTP Parser

This library parses HTTP protocol for requests and responses.
It was created to replace `http_parser.c` since calling C++ functions from JS is really slow in V8.
However, it is now primarily useful in having a more flexible/tolerant HTTP parser when dealing with legacy services that do not meet the strict HTTP parsing rules Node's parser follows.

This is packaged as a standalone npm module.
To use in node, monkeypatch HTTPParser.

```js
// Monkey patch before you require http for the first time.
process.binding('http_parser').HTTPParser = require('http-parser-js').HTTPParser;

var http = require('http');
// ...
```

## Testing

Simply run `npm test`.
The tests are copied from node and mscedex/io.js, with some modifcations.

## Status

This should now be usable in any node application, it now supports (nearly) everything `http_parser.c` does while still being tolerant with corrupted headers, and other kinds of malformed data.

### Node versions

`http-parser-js` should work via monkey-patching on Node v6-v11, and v13-14.

Node v12.x renamed the internal http parser, and did not expose it for monkey-patching, so to be able to monkey-patch on Node v12, you must run `node --http-parser=legacy file.js` to opt in to the old, monkey-patchable http_parser binding.

## Standalone usage

While this module is intended to be used as a replacement for the internal Node.js parser, it can be used as a standalone parser. The [`standalone-example.js`](standalone-example.js) demonstrates how to use the somewhat awkward API (coming from compatibility with the Node.js internals) to parse HTTP from raw Buffers.

## License

MIT.
See [LICENSE.md](LICENSE.md)


---

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).

## [v1.18.1](https://github.com/http-party/node-http-proxy/compare/1.18.0...v1.18.1) - 2020-05-17

### Merged

- Skip sending the proxyReq event when the expect header is present [`#1447`](https://github.com/http-party/node-http-proxy/pull/1447)
- Remove node6 support, add node12 to build [`#1397`](https://github.com/http-party/node-http-proxy/pull/1397)

## [1.18.0](https://github.com/http-party/node-http-proxy/compare/1.17.0...1.18.0) - 2019-09-18

### Merged

- Added in auto-changelog module set to keepachangelog format [`#1373`](https://github.com/http-party/node-http-proxy/pull/1373)
- fix 'Modify Response' readme section to avoid unnecessary array copying [`#1300`](https://github.com/http-party/node-http-proxy/pull/1300)
- Fix incorrect target name for reverse proxy example [`#1135`](https://github.com/http-party/node-http-proxy/pull/1135)
- Fix modify response middleware example [`#1139`](https://github.com/http-party/node-http-proxy/pull/1139)
- [dist] Update dependency async to v3 [`#1359`](https://github.com/http-party/node-http-proxy/pull/1359)
- Fix path to local http-proxy in examples. [`#1072`](https://github.com/http-party/node-http-proxy/pull/1072)
- fix reverse-proxy example require path [`#1067`](https://github.com/http-party/node-http-proxy/pull/1067)
- Update README.md [`#970`](https://github.com/http-party/node-http-proxy/pull/970)
- [dist] Update dependency request to ~2.88.0 [SECURITY] [`#1357`](https://github.com/http-party/node-http-proxy/pull/1357)
- [dist] Update dependency eventemitter3 to v4 [`#1365`](https://github.com/http-party/node-http-proxy/pull/1365)
- [dist] Update dependency colors to v1 [`#1360`](https://github.com/http-party/node-http-proxy/pull/1360)
- [dist] Update all non-major dependencies [`#1356`](https://github.com/http-party/node-http-proxy/pull/1356)
- [dist] Update dependency agentkeepalive to v4 [`#1358`](https://github.com/http-party/node-http-proxy/pull/1358)
- [dist] Update dependency nyc to v14 [`#1367`](https://github.com/http-party/node-http-proxy/pull/1367)
- [dist] Update dependency concat-stream to v2 [`#1363`](https://github.com/http-party/node-http-proxy/pull/1363)
- x-forwarded-host overwrite for mutli level proxies [`#1267`](https://github.com/http-party/node-http-proxy/pull/1267)
- [refactor doc] Complete rename to http-party org. [`#1362`](https://github.com/http-party/node-http-proxy/pull/1362)
- Highlight correct lines for createProxyServer [`#1117`](https://github.com/http-party/node-http-proxy/pull/1117)
- Fix docs for rewrite options - 201 also handled [`#1147`](https://github.com/http-party/node-http-proxy/pull/1147)
- Update .nyc_output [`#1339`](https://github.com/http-party/node-http-proxy/pull/1339)
- Configure Renovate [`#1355`](https://github.com/http-party/node-http-proxy/pull/1355)
- [examples] Restream body before proxying, support for Content-Type of application/x-www-form-urlencoded [`#1264`](https://github.com/http-party/node-http-proxy/pull/1264)

### Commits

- [dist] New test fixtures. [`7e4a0e5`](https://github.com/http-party/node-http-proxy/commit/7e4a0e511bc30c059216860153301de2cdd1e97f)
- [dist] End of an era. [`a9b09cc`](https://github.com/http-party/node-http-proxy/commit/a9b09cce43f072db99fb5170030a05536177ccb7)
- [dist] Version bump. 1.18.0 [`9bbe486`](https://github.com/http-party/node-http-proxy/commit/9bbe486c5efcc356fb4d189ef38eee275bbde345)
- [fix] Latest versions. [`59c4403`](https://github.com/http-party/node-http-proxy/commit/59c4403e9dc15ab9b19ee2a3f4aecbfc6c3d94c4)
- [fix test] Update tests. [`dd1d08b`](https://github.com/http-party/node-http-proxy/commit/dd1d08b6319d1def729554446a5b0176978a8dad)
- [dist] Update dependency ws to v3 [SECURITY] [`b00911c`](https://github.com/http-party/node-http-proxy/commit/b00911c93740a00c5cfbacbb91565cb6912ed255)
- [dist] .gitattributes all the things. [`fc93520`](https://github.com/http-party/node-http-proxy/commit/fc93520d741ec80be8ae31ca005f3e9c199e330e)
- [dist] Regenerate package-lock.json. [`16d4f8a`](https://github.com/http-party/node-http-proxy/commit/16d4f8a95162b2e2e4ee6657c500f1208c044b2d)

## [1.17.0](https://github.com/http-party/node-http-proxy/compare/1.16.2...1.17.0) - 2018-04-20

### Merged

- Fix overwriting of global options [`#1074`](https://github.com/http-party/node-http-proxy/pull/1074)
- Update README.md [`#1131`](https://github.com/http-party/node-http-proxy/pull/1131)
- Update README.md with CoC link [`#1120`](https://github.com/http-party/node-http-proxy/pull/1120)
- Add Code Of Conduct [`#1119`](https://github.com/http-party/node-http-proxy/pull/1119)
- [deps] Update eventemitter3 to version 2.0.x [`#1109`](https://github.com/http-party/node-http-proxy/pull/1109)

### Fixed

- Fix "Can't set headers after they are sent" errors [`#930`](https://github.com/http-party/node-http-proxy/issues/930)
- Include websocket non-upgrade response [`#890`](https://github.com/http-party/node-http-proxy/issues/890)

### Commits

- Add followRedirects option [`c9a556c`](https://github.com/http-party/node-http-proxy/commit/c9a556cfa57c7ce0b877e16f2c2e1448d8cc278d)
- [test] add test for selfHandleRequest and remove modifyResponse as selfHandleRequest is the only way that functionality works [`4a37175`](https://github.com/http-party/node-http-proxy/commit/4a37175a5296d2ea2da0fc15a3f8fe08599bb592)
- Adding ability to set cookie path [`2c98416`](https://github.com/http-party/node-http-proxy/commit/2c98416ac2bf17bb5f515b9e10ee4485f5913846)
- Updating docs and adding more tests. [`f5c2381`](https://github.com/http-party/node-http-proxy/commit/f5c2381395e01bf8d6655cc70e14032c8f0aaa67)
- [dist] make tests work reliably, add package-lock.json [`09dcb98`](https://github.com/http-party/node-http-proxy/commit/09dcb984565dabb159a01a75a188b974f8c176ad)
- add support for modify response [`e5c02b8`](https://github.com/http-party/node-http-proxy/commit/e5c02b8a8a902e204eee886acafbbfe46c4a3aef)
- [wip] proper tests and reporting [`f4ff100`](https://github.com/http-party/node-http-proxy/commit/f4ff1006b9e71eb4185a3edf03333dbe514a84c9)
- Add detail about "buffer" option [`6f88caf`](https://github.com/http-party/node-http-proxy/commit/6f88caf6e46d84a809910c591e138250b333b39f)
- Add use case for proxy to HTTPS using a PKCS12 client certificate [`d2f9db8`](https://github.com/http-party/node-http-proxy/commit/d2f9db824136358a06dc3dd566644f3a016f24e2)
- [test] for override method feature [`81d58c5`](https://github.com/http-party/node-http-proxy/commit/81d58c531be3f61efb56d2489a66c73a7b2325fe)
- [dist] doc updates [`e94d529`](https://github.com/http-party/node-http-proxy/commit/e94d52973a26cf817a9de12d97e5ae603093f70d)
- feat: 添加response自处理参数 [`89f9ef8`](https://github.com/http-party/node-http-proxy/commit/89f9ef87e0532d54d086719c5ace1a968a42e51b)
- [dist][test] codecov config [`a4bccc3`](https://github.com/http-party/node-http-proxy/commit/a4bccc332d36d7db93db984674cd7e51b43a1b99)
- Removing unnecessary check since this is a private API [`bc6a237`](https://github.com/http-party/node-http-proxy/commit/bc6a23709c37c65b5b16cc802d05cb57f099b0ce)
- issue #953: stop using writeHead [`2c44039`](https://github.com/http-party/node-http-proxy/commit/2c44039a7c30b190043da654ee7e5aed0304e979)
- [fix] move badges [`543636d`](https://github.com/http-party/node-http-proxy/commit/543636d0f662308ec8c9afdbf641f4036f002bfd)
- fix small typos in README [`8231984`](https://github.com/http-party/node-http-proxy/commit/8231984fb02dca331b4ef77e089db50855eea4f5)
- Added timeout option to docs [`107c187`](https://github.com/http-party/node-http-proxy/commit/107c18720c3906f9049cc14d075b31910c0ccf55)
- [dist] document the feature [`d533a1b`](https://github.com/http-party/node-http-proxy/commit/d533a1be437b37fed5bd25f5e58298eea819f974)
- [fix] slightly more tolerant [`de1b808`](https://github.com/http-party/node-http-proxy/commit/de1b80851ab1b1251b5eaeaf0beab164024f09b6)
- Forgot 'i' flag when changing from regex shorthand to string. [`50f58b4`](https://github.com/http-party/node-http-proxy/commit/50f58b4cd9b4422a11512a6a065432159b5bc806)
- Update common.js [`c5d8466`](https://github.com/http-party/node-http-proxy/commit/c5d846648304f2e36a172b25d9fb8300d8131f8c)
- [fix] rm newline [`e6f24ba`](https://github.com/http-party/node-http-proxy/commit/e6f24ba6173c4fdd26089b3c729de5dbdd71ad74)
- [dist] update package-lock.json [`abf882e`](https://github.com/http-party/node-http-proxy/commit/abf882e03c92cf1665d5b7d4dbdaf87feb50a677)

## [1.16.2](https://github.com/http-party/node-http-proxy/compare/1.16.1...1.16.2) - 2016-12-06

### Merged

- [WIP] Revert default behavior of writeHeaders method [`#1104`](https://github.com/http-party/node-http-proxy/pull/1104)

## [1.16.1](https://github.com/http-party/node-http-proxy/compare/1.16.0...1.16.1) - 2016-12-04

### Commits

- Enable proxy response to have multiple Set-Cookie raw headers #1101 [`8cb451f`](https://github.com/http-party/node-http-proxy/commit/8cb451f20cff0a19fc9576fc2558307fb17a5710)
- [dist] Version bump. 1.16.1 [`ac1a01b`](https://github.com/http-party/node-http-proxy/commit/ac1a01b1f3caa3a2a9433341bf5e7a95072d6612)

## [1.16.0](https://github.com/http-party/node-http-proxy/compare/1.15.2...1.16.0) - 2016-12-02

### Merged

- Fix newly introduced error in error handler for ECONNREFUSED in forward proxy [`#1100`](https://github.com/http-party/node-http-proxy/pull/1100)
- Keep original letter case of response header keys [`#1098`](https://github.com/http-party/node-http-proxy/pull/1098)
- Handle errors for forward request, add test case [`#1099`](https://github.com/http-party/node-http-proxy/pull/1099)

### Commits

- add node 6 to travis [`2f7f037`](https://github.com/http-party/node-http-proxy/commit/2f7f03778cfb94396acf0d778061ea197212fbb5)

## [1.15.2](https://github.com/http-party/node-http-proxy/compare/1.15.1...1.15.2) - 2016-10-22

### Merged

- Add proxy-timeout option to documentation [`#1075`](https://github.com/http-party/node-http-proxy/pull/1075)

### Commits

- Do not rely on func.name (no scope) [`61c2889`](https://github.com/http-party/node-http-proxy/commit/61c28891093b256bbc0dae78e45e2c5f0acf2101)
- Do not rely on func.name (no scope) [`d48f67e`](https://github.com/http-party/node-http-proxy/commit/d48f67eb90d8af66211093e91efdd6638859e0bf)
- Expose full callback names [`220f5fb`](https://github.com/http-party/node-http-proxy/commit/220f5fb795d2977c5a68ae59d7db65089efed50c)
- test case added [`f5217d6`](https://github.com/http-party/node-http-proxy/commit/f5217d6c20c164ed412a3b20f660786b6f88b35b)
- [fix] style nits [`d0f1dfe`](https://github.com/http-party/node-http-proxy/commit/d0f1dfeb8277d46a057017cd888b50e85f6725d6)
- With a comment [`fbc2668`](https://github.com/http-party/node-http-proxy/commit/fbc266809c289fbdb59d7944345816a858303c96)
- Fix browserification [`8eddf45`](https://github.com/http-party/node-http-proxy/commit/8eddf45f2a043e4e1b3f6e33c304e68fe7e1c406)
- not setting connection header in case of http2 as it is deprecated [`2d01edc`](https://github.com/http-party/node-http-proxy/commit/2d01edc5a5ace591784022b85860a3bbc48c5e12)

## [1.15.1](https://github.com/http-party/node-http-proxy/compare/1.15.0...1.15.1) - 2016-09-14

### Merged

- Properly write response header optionally including statusMessage [`#1061`](https://github.com/http-party/node-http-proxy/pull/1061)

### Commits

- [dist] Version bump. 1.15.1 [`912cd3a`](https://github.com/http-party/node-http-proxy/commit/912cd3acaef484f7ea08affc9339250082e04058)

## [1.15.0](https://github.com/http-party/node-http-proxy/compare/1.14.0...1.15.0) - 2016-09-14

### Merged

- Made it not to crash with omited Host http header [`#1050`](https://github.com/http-party/node-http-proxy/pull/1050)
- README.md: fix typo: 'ingoing' should be 'incoming' [`#1060`](https://github.com/http-party/node-http-proxy/pull/1060)
- Fix for Reason-Phrase being overwritten on proxy response. [`#1051`](https://github.com/http-party/node-http-proxy/pull/1051)
- cookieDomainRewrite option [`#1009`](https://github.com/http-party/node-http-proxy/pull/1009)
- Update ntlm-authentication.js [`#1025`](https://github.com/http-party/node-http-proxy/pull/1025)
- Restream body before proxying [`#1027`](https://github.com/http-party/node-http-proxy/pull/1027)
- Location rewriting for responses with status 201 [`#1024`](https://github.com/http-party/node-http-proxy/pull/1024)
- #866 Copy CA from options into outbound proxy [`#1042`](https://github.com/http-party/node-http-proxy/pull/1042)

### Fixed

- Restream body before proxying (#1027) [`#955`](https://github.com/http-party/node-http-proxy/issues/955)

### Commits

- [dist] Version bump. 1.15.0 [`b98c75b`](https://github.com/http-party/node-http-proxy/commit/b98c75b1ff3ebdf7f78224eb0d9aa857af2db1d9)

## [1.14.0](https://github.com/http-party/node-http-proxy/compare/1.13.3...1.14.0) - 2016-06-15

### Merged

- Emit disconnected event instead of error when ECONNRESET [`#966`](https://github.com/http-party/node-http-proxy/pull/966)
- fix test for node 0.10 + socket.io-client@1.4.6 (engine.io-client@1.6.9) [`#1010`](https://github.com/http-party/node-http-proxy/pull/1010)

### Commits

- [dist] Version bump. 1.14.0 [`fcfb0b3`](https://github.com/http-party/node-http-proxy/commit/fcfb0b37f6ac61369565507446377f91d955cf29)

## [1.13.3](https://github.com/http-party/node-http-proxy/compare/1.13.2...1.13.3) - 2016-05-16

### Merged

- fix browserify compatibility [`#975`](https://github.com/http-party/node-http-proxy/pull/975)
- alter message error [`#998`](https://github.com/http-party/node-http-proxy/pull/998)
- Sanitize header keys before setting them [`#997`](https://github.com/http-party/node-http-proxy/pull/997)
- Update ntlm-authentication.js [`#989`](https://github.com/http-party/node-http-proxy/pull/989)
- Add expected datatype to readme [`#983`](https://github.com/http-party/node-http-proxy/pull/983)
- Update README [`#982`](https://github.com/http-party/node-http-proxy/pull/982)
- Fix formatting of the `headers` option [`#974`](https://github.com/http-party/node-http-proxy/pull/974)
- Set the x-forwarded-host flag when xfwd is enabled [`#967`](https://github.com/http-party/node-http-proxy/pull/967)

### Fixed

- Sanitize header keys before setting them (#997) [`#996`](https://github.com/http-party/node-http-proxy/issues/996)

### Commits

- [dist] Update LICENSE to reflect 2015 changes. [`f345a1a`](https://github.com/http-party/node-http-proxy/commit/f345a1ac2dde1884e72b952a685a0a1796059f14)
- [dist] Version bump. 1.13.3 [`5082acc`](https://github.com/http-party/node-http-proxy/commit/5082acc067bbf287f503bbd5b776f798ab169db1)

## [1.13.2](https://github.com/http-party/node-http-proxy/compare/1.13.1...1.13.2) - 2016-02-17

### Merged

- Fixed missing documentation: #options.headers [`#806`](https://github.com/http-party/node-http-proxy/pull/806)
- #949 Proxy example using req instead res on README [`#950`](https://github.com/http-party/node-http-proxy/pull/950)
- mocha: Use default reporter [`#962`](https://github.com/http-party/node-http-proxy/pull/962)
- Remove "transfer-encoding" header if "content-length" is set to zero [`#961`](https://github.com/http-party/node-http-proxy/pull/961)

### Commits

- [dist] Version bump. 1.13.2 [`e1b2f4c`](https://github.com/http-party/node-http-proxy/commit/e1b2f4c31b34464431db251b3b6169689dadf518)

## [1.13.1](https://github.com/http-party/node-http-proxy/compare/1.13.0...1.13.1) - 2016-02-02

### Merged

- README.md: summary to specify reverse proxy [`#932`](https://github.com/http-party/node-http-proxy/pull/932)
- fix(common) urlJoin replace: ":/" -&gt; "http?s:/" [`#947`](https://github.com/http-party/node-http-proxy/pull/947)
- Update README.md [`#948`](https://github.com/http-party/node-http-proxy/pull/948)

### Commits

- [dist] Version bump. 1.13.1 [`9d9fa94`](https://github.com/http-party/node-http-proxy/commit/9d9fa940cff3aa6134c60732c23aea8171fc7296)

## [1.13.0](https://github.com/http-party/node-http-proxy/compare/1.12.1...1.13.0) - 2016-01-26

### Merged

- Fix for #839 (Ignore path and the trailing slash) [`#934`](https://github.com/http-party/node-http-proxy/pull/934)
- Update license year range to 2016 [`#943`](https://github.com/http-party/node-http-proxy/pull/943)

### Commits

- [dist] Version bump. 1.13.0 [`268994e`](https://github.com/http-party/node-http-proxy/commit/268994ea45d9f8737343001ab9542e03023a5c96)

## [1.12.1](https://github.com/http-party/node-http-proxy/compare/1.12.0...1.12.1) - 2016-01-24

### Merged

- Bump version for npm publish [`#942`](https://github.com/http-party/node-http-proxy/pull/942)
- Added check to passes/web-outgoing.js to make sure the header being s… [`#940`](https://github.com/http-party/node-http-proxy/pull/940)
- Created reverse-proxy.js example. [`#825`](https://github.com/http-party/node-http-proxy/pull/825)
- SSE example and test [`#922`](https://github.com/http-party/node-http-proxy/pull/922)
- More structured readme [`#912`](https://github.com/http-party/node-http-proxy/pull/912)
- Updated markdown docs to mention proxy rules module [`#910`](https://github.com/http-party/node-http-proxy/pull/910)
- Add tests for forwarding of continuation frames [`#901`](https://github.com/http-party/node-http-proxy/pull/901)
- Bump requires-port, server and ws [`#904`](https://github.com/http-party/node-http-proxy/pull/904)
- [example] add an example for NTLM authentication [`#903`](https://github.com/http-party/node-http-proxy/pull/903)

### Commits

- Organized README more [`cd1d777`](https://github.com/http-party/node-http-proxy/commit/cd1d7776e8fb5d67e2c52b9ef27d8c932e7b72e2)
- Add tests for testing forwarding of continuation frames [`64fa520`](https://github.com/http-party/node-http-proxy/commit/64fa52078913c6d4fe95673f182aac4924961e8b)
- Added back to top helpers [`6106d4c`](https://github.com/http-party/node-http-proxy/commit/6106d4c32f7c7960f0391591661e6f0d229db52d)
- [ci] use node 4.2 to test and do not allow failures [`f82ce18`](https://github.com/http-party/node-http-proxy/commit/f82ce18d2f187b085c2c4f49d857755d21c582b1)
- [fix] bump requires-port, server and ws [`9ea1e89`](https://github.com/http-party/node-http-proxy/commit/9ea1e89a2fd9c392cd40265bdb13494a3614e290)
- Updated markdown docs to mention proxy rules [`eea79ca`](https://github.com/http-party/node-http-proxy/commit/eea79cab53f27371cad387a524ee3aaefa742c48)
- Fixed tests depending on ignorePath [`f9540de`](https://github.com/http-party/node-http-proxy/commit/f9540de7b13f41091be2dcb68d8f23be65ad3885)
- Added check to passes/web-outgoing.js to make sure the header being set is not undefined, which should be the only falsey value that could accidently show up and break that call. This fixes windows NTLM auth issues behind http-proxy. [`3b39d2c`](https://github.com/http-party/node-http-proxy/commit/3b39d2c3dcb1785cc06043fcb226c652f554941e)
- No longer appends / to path if ignorePath is set [`f2093b5`](https://github.com/http-party/node-http-proxy/commit/f2093b5313c855cd6309cc0ddebb31f369e525ed)
- README.md: introduction to specify reverse proxy [`41414a5`](https://github.com/http-party/node-http-proxy/commit/41414a56a11ddfac3a337711ac4c64124eb62377)
- Added note for appending trailing / when using ignorePath [`0cb1d3c`](https://github.com/http-party/node-http-proxy/commit/0cb1d3c68e793fed9aa4a7624c32a018e796aa95)

## [1.12.0](https://github.com/http-party/node-http-proxy/compare/1.11.3...1.12.0) - 2015-10-22

### Merged

- Issue #896: provide a "proxyReq" event also for websocket connections. [`#897`](https://github.com/http-party/node-http-proxy/pull/897)

### Commits

- Provide a "proxyReq" event also for websocket connections. [`a05fc2d`](https://github.com/http-party/node-http-proxy/commit/a05fc2d1692d038f1eaad6d9b26c174039bc1949)
- fixes after PR review [`9752652`](https://github.com/http-party/node-http-proxy/commit/9752652e76da3bcfb6a635620e4162518ca43203)
- [dist] Version bump. 1.12.0 [`b5a6d0e`](https://github.com/http-party/node-http-proxy/commit/b5a6d0e58396363f4c457f6d1654614bdfcfcb73)

## [1.11.3](https://github.com/http-party/node-http-proxy/compare/1.11.2...1.11.3) - 2015-10-19

### Merged

- Removed unspecified trailing slash in proxy url [`#893`](https://github.com/http-party/node-http-proxy/pull/893)
- Updating the upgrading doc [`#892`](https://github.com/http-party/node-http-proxy/pull/892)

### Commits

- [dist] Update .travis.yml to be more modern. [`302d981`](https://github.com/http-party/node-http-proxy/commit/302d981dd2cf06dbf751b1f64e3dfea08d0f9476)
- [dist] Version bump. 1.11.3 [`60baca5`](https://github.com/http-party/node-http-proxy/commit/60baca5aed4f45ef1d7b3f7edd909375853d344b)
- docs: options.headers [`c86ae51`](https://github.com/http-party/node-http-proxy/commit/c86ae51bb9658309a9628f4f5182d4c45c803b84)

## [1.11.2](https://github.com/http-party/node-http-proxy/compare/v1.11.1...1.11.2) - 2015-08-30

### Merged

- Update gzip-middleware.js [`#870`](https://github.com/http-party/node-http-proxy/pull/870)
- Fix broken option list indentation [`#863`](https://github.com/http-party/node-http-proxy/pull/863)
- Added missing configuration options [`#852`](https://github.com/http-party/node-http-proxy/pull/852)
- Added installation instructions [`#823`](https://github.com/http-party/node-http-proxy/pull/823)
- fixes comment [`#817`](https://github.com/http-party/node-http-proxy/pull/817)

### Commits

- Created reverse-proxy.js example. [`38864d0`](https://github.com/http-party/node-http-proxy/commit/38864d016794b9ff3d8d1d1cb81a730b40a1bf9c)
- Added websocket set-cookie headers test [`855cebd`](https://github.com/http-party/node-http-proxy/commit/855cebdac4d33ef5f2fab4c4c78fdc07cdb61402)
- [fix] make more functional [`cea0e86`](https://github.com/http-party/node-http-proxy/commit/cea0e8676b3e609828320bb03051eaf78cc43b54)
- Modify the set-cookie header fix to work with node 0.10.x. [`da674ec`](https://github.com/http-party/node-http-proxy/commit/da674ec4df2b371f09e912f3b376c48581090a0f)
- Use raw headers instead parsed. [`8bfd90c`](https://github.com/http-party/node-http-proxy/commit/8bfd90c4d9331fd129f17a788ef9fc733654b7e0)
- Replaced Object.keys().map with for in loop. [`3d2350c`](https://github.com/http-party/node-http-proxy/commit/3d2350c54ff0fb9271f5fcfea1d23f22ad97c47c)
- [dist] Version bump. 1.11.2 [`30e3b37`](https://github.com/http-party/node-http-proxy/commit/30e3b371de0116e40e15156394f31c7e0b0aa9f1)
- Websocket key was unnecessary long. [`ca73208`](https://github.com/http-party/node-http-proxy/commit/ca732087498582df01ab78fb7da77912dab8f138)

## [v1.11.1](https://github.com/http-party/node-http-proxy/compare/v1.11.0...v1.11.1) - 2015-04-22

### Commits

- [dist] Version bump. 1.11.1 [`7e6c66a`](https://github.com/http-party/node-http-proxy/commit/7e6c66a7e485a6c0ec3a1c567bbe800fdc56c9fd)
- [fix] dont use bind in the one case we do [`d26ef56`](https://github.com/http-party/node-http-proxy/commit/d26ef56e1bc2a1232b06c01b4740e3bf35d63eda)
- [dist] update to new version of EE3 [`607f96c`](https://github.com/http-party/node-http-proxy/commit/607f96c00cbda2a6b881b8ff1db05437dbf4ce77)
- [fix] use the main export for EE3 [`18c77ca`](https://github.com/http-party/node-http-proxy/commit/18c77cafc7d5479502cf5c4d2b663d8f85cfd6d4)

## [v1.11.0](https://github.com/http-party/node-http-proxy/compare/v1.10.1...v1.11.0) - 2015-04-20

### Merged

- [api] add an ignorePath option if you want to disregard the path of the ... [`#759`](https://github.com/http-party/node-http-proxy/pull/759)

### Commits

- [dist] Version bump. 1.11.0 [`934e6c4`](https://github.com/http-party/node-http-proxy/commit/934e6c4d54292a1b961452074e02fb5d45da729a)

## [v1.10.1](https://github.com/http-party/node-http-proxy/compare/v1.10.0...v1.10.1) - 2015-04-02

### Merged

- Fix default port detection with node 0.12.x [`#799`](https://github.com/http-party/node-http-proxy/pull/799)

### Commits

- [dist] add semver and normalize package.json with --save-dev [`1b89bc9`](https://github.com/http-party/node-http-proxy/commit/1b89bc9a76c229070ff2572f7a0e1b969c4b4701)
- fix protocol and default port detection on node 0.12.x, compatible with 0.10.x [`5f14bca`](https://github.com/http-party/node-http-proxy/commit/5f14bcaa704fe8a5e6f59d3a89722f22958cade9)
- fix expected error message when node 0.12.x [`0ee314c`](https://github.com/http-party/node-http-proxy/commit/0ee314c436226391318b9a1b623cb3f7e8bf4df7)
- force cipher AES128-GCM-SHA256 in https tests [`c33d161`](https://github.com/http-party/node-http-proxy/commit/c33d1616cdbd60587ca2eb326c48b8a87ac56092)
- [fix] properly support iojs with test checking for HTTPS [`c6dfb04`](https://github.com/http-party/node-http-proxy/commit/c6dfb04a67f3b5ac9a402b7b08c1b8baf29f89e6)
- [dist] Version bump. 1.10.1 [`0bd446c`](https://github.com/http-party/node-http-proxy/commit/0bd446c680e9991accfaa3a6a70e411fdac79164)
- [ci] add 0.12 and iojs to travis [`a6ae6c4`](https://github.com/http-party/node-http-proxy/commit/a6ae6c499743ddade9db12b9f7404d980c79f683)

## [v1.10.0](https://github.com/http-party/node-http-proxy/compare/v1.9.1...v1.10.0) - 2015-04-01

### Merged

- Fixes / additions to URL rewriting [`#787`](https://github.com/http-party/node-http-proxy/pull/787)

### Commits

- [dist] Version bump. 1.10.0 [`1dabda2`](https://github.com/http-party/node-http-proxy/commit/1dabda241f3b93eb9195134042e7a3b84fd0ef57)

## [v1.9.1](https://github.com/http-party/node-http-proxy/compare/v1.9.0...v1.9.1) - 2015-04-01

### Merged

- Fix #747 [`#798`](https://github.com/http-party/node-http-proxy/pull/798)

### Fixed

- Merge pull request #798 from damonmcminn/master [`#747`](https://github.com/http-party/node-http-proxy/issues/747)
- Fix https://github.com/nodejitsu/node-http-proxy/issues/747 [`#747`](https://github.com/nodejitsu/node-http-proxy/issues/747)

### Commits

- Add test for https://github.com/nodejitsu/node-http-proxy/issues/747 [`d145152`](https://github.com/http-party/node-http-proxy/commit/d145152655a69479348b0ebc726d4dc19720a12b)
- [dist] Version bump. 1.9.1 [`21b30b7`](https://github.com/http-party/node-http-proxy/commit/21b30b754db4f6410c3d2052bc123b3fdae57c46)

## [v1.9.0](https://github.com/http-party/node-http-proxy/compare/v1.8.1...v1.9.0) - 2015-03-12

### Merged

- Adding the nodejs0.12 auth option [`#792`](https://github.com/http-party/node-http-proxy/pull/792)
- fix "x-forwarded-proto" in node 0.12 and iojs [`#789`](https://github.com/http-party/node-http-proxy/pull/789)
- Add support for auto host rewriting and protocol rewriting [`#1`](https://github.com/http-party/node-http-proxy/pull/1)
- changed highlighted part - very minor [`#756`](https://github.com/http-party/node-http-proxy/pull/756)
- Update README.md for benchmarks [`#625`](https://github.com/http-party/node-http-proxy/pull/625)

### Fixed

- fix "x-forwarded-proto" in node 0.12 and iojs [`#772`](https://github.com/http-party/node-http-proxy/issues/772)
- [api] add an ignorePath option if you want to disregard the path of the incoming request when proxying to the target server fixes #758 [`#758`](https://github.com/http-party/node-http-proxy/issues/758)

### Commits

- added auth header test [`df158bf`](https://github.com/http-party/node-http-proxy/commit/df158bfc53e35e62609d8169f3883f6dcf12b73c)
- added auth header test [`ff1626f`](https://github.com/http-party/node-http-proxy/commit/ff1626f0719652c92895cf80f9aacc22ededadad)
- refactor some tests for greater readability [`14415a5`](https://github.com/http-party/node-http-proxy/commit/14415a50741d1f258da884686455d87d68eb8121)
- only rewrite redirect urls when it matches target [`26029ba`](https://github.com/http-party/node-http-proxy/commit/26029ba7ac948b5dc0befb2091cc9a5862d0641c)
- auth header added [`ab5c3e5`](https://github.com/http-party/node-http-proxy/commit/ab5c3e5c819ca993e0616d178bc1d282af539508)
- [dist] Version bump. 1.9.0 [`87a92a7`](https://github.com/http-party/node-http-proxy/commit/87a92a72802a27f817fcba87382d55831fd04ddb)
- end of file line space [`e907d7b`](https://github.com/http-party/node-http-proxy/commit/e907d7bb2aa2825b43d9355cb1ee25bec47b15ad)
- space instead of tabs [`7298510`](https://github.com/http-party/node-http-proxy/commit/7298510e9170d74ff057487085bc1e898f044177)
- space instead of tabs [`63c9262`](https://github.com/http-party/node-http-proxy/commit/63c9262df5bd04d83432db44fce2a4d5b19a59ea)
- auth header added tests [`f55ffa3`](https://github.com/http-party/node-http-proxy/commit/f55ffa356a259c09685c6b768a404e4b73f674ce)

## [v1.8.1](https://github.com/http-party/node-http-proxy/compare/v1.8.0...v1.8.1) - 2014-12-17

### Commits

- Pass HTTPS client parameters. [`402ab05`](https://github.com/http-party/node-http-proxy/commit/402ab057340a29db7a521ff239c5e21ac0c12be8)
- [dist] Version bump. 1.8.1 [`3311106`](https://github.com/http-party/node-http-proxy/commit/3311106c2c2346f3ac1ffe402b80bca3c7c59275)

## [v1.8.0](https://github.com/http-party/node-http-proxy/compare/v1.7.3...v1.8.0) - 2014-12-17

### Merged

- Fix variables scope in test [`#752`](https://github.com/http-party/node-http-proxy/pull/752)
- Fix typo [`#751`](https://github.com/http-party/node-http-proxy/pull/751)

### Commits

- Added websocket close event test [`8bff3dd`](https://github.com/http-party/node-http-proxy/commit/8bff3ddc1276e3ba18fd68c34d8982148cd21455)
- Deprecated proxySocket event in favor to open event. [`c62610e`](https://github.com/http-party/node-http-proxy/commit/c62610e8e4d59e8ba4642370ff3fb933c6ddb4eb)
- Update README.md [`05d18a4`](https://github.com/http-party/node-http-proxy/commit/05d18a4e1ba6c2de41b0b803cd1793357979384d)
- [fix] style spacing wtf [`ea0a4de`](https://github.com/http-party/node-http-proxy/commit/ea0a4ded803b30144e442344ad5a38a0d34bb3ba)
- [api] add close event in ws-incoming.js [`2653786`](https://github.com/http-party/node-http-proxy/commit/26537866b3ca522927aa4604a958f90774c0c0c0)
- [minor] grammar [`f304861`](https://github.com/http-party/node-http-proxy/commit/f30486195cfa6cfcf6400ac445975d5adada72e4)
- Changed proxyServer and destiny to local variables. [`8a8a894`](https://github.com/http-party/node-http-proxy/commit/8a8a894092ddbec8f0365ced0e94a75b1307ecf1)
- [dist] Version bump. 1.8.0 [`f0db5b3`](https://github.com/http-party/node-http-proxy/commit/f0db5b3f708b0858f617d472dfdd0ba211b774ef)

## [v1.7.3](https://github.com/http-party/node-http-proxy/compare/v1.7.2...v1.7.3) - 2014-12-09

### Fixed

- [fix] use simple regex instead of indexOf to check the protocol to support without the colon fixes #711 [`#711`](https://github.com/http-party/node-http-proxy/issues/711)

### Commits

- [test] show that we support protocol without the colon [`89f9ca1`](https://github.com/http-party/node-http-proxy/commit/89f9ca1e89d679b2b85a8f85b65e8b0878694207)
- [dist] Version bump. 1.7.3 [`6a330ff`](https://github.com/http-party/node-http-proxy/commit/6a330ff904d02a41f9a1cac338a98da1849c54ca)

## [v1.7.2](https://github.com/http-party/node-http-proxy/compare/v1.7.1...v1.7.2) - 2014-12-08

### Merged

- Fix grammar in README.md [`#749`](https://github.com/http-party/node-http-proxy/pull/749)

### Fixed

- [fix] properly include port in host header with changeOrigin in all cases fixes #750 [`#750`](https://github.com/http-party/node-http-proxy/issues/750)

### Commits

- [test] add tests for the changeOrigin cases in properly setting the host header [`71a06aa`](https://github.com/http-party/node-http-proxy/commit/71a06aab0249487ff650c8a47906cc8281561664)
- [dist] pin down deps and add requires-port [`81874f7`](https://github.com/http-party/node-http-proxy/commit/81874f795b7df7929e03d9d4cb98a947b1ef114b)
- [dist] Version bump. 1.7.2 [`2086e49`](https://github.com/http-party/node-http-proxy/commit/2086e4917c97f347f84c54b166799bc8db9f4162)

## [v1.7.1](https://github.com/http-party/node-http-proxy/compare/v1.7.0...v1.7.1) - 2014-12-02

### Merged

- Adding harmon to the README [`#716`](https://github.com/http-party/node-http-proxy/pull/716)

### Fixed

- [fix] fix #738 [`#738`](https://github.com/http-party/node-http-proxy/issues/738)
- [fix] simple fixes #748 #744 #746 [`#748`](https://github.com/http-party/node-http-proxy/issues/748)

### Commits

- [test] add proper failing test case for #738 [`410a8ce`](https://github.com/http-party/node-http-proxy/commit/410a8ce94ccea566a8e50daf3b78e633b82875cb)
- [Bugfix] Allow for multiple ? in outgoing urls. [`70ed1c4`](https://github.com/http-party/node-http-proxy/commit/70ed1c4273bc64500e8bae9b60d7fd6a19135246)
- [dist] Version bump. 1.7.1 [`56a7b77`](https://github.com/http-party/node-http-proxy/commit/56a7b77645b13d337c1a2f879460193d310454c8)

## [v1.7.0](https://github.com/http-party/node-http-proxy/compare/v1.6.2...v1.7.0) - 2014-11-25

### Merged

- Allow optional redirect host rewriting. [`#741`](https://github.com/http-party/node-http-proxy/pull/741)
- Set `Content-Length` header for OPTIONS requests [`#742`](https://github.com/http-party/node-http-proxy/pull/742)
- copy headers instead of referencing them so they don't unexpectedly get overwritten [`#736`](https://github.com/http-party/node-http-proxy/pull/736)
- Updated to support error callback on proxy.web and start/proxyReq/end co... [`#735`](https://github.com/http-party/node-http-proxy/pull/735)

### Commits

- :pencil: Add host rewrite docs and specs. [`add8133`](https://github.com/http-party/node-http-proxy/commit/add81338a90dae132f9e74fd5a5905fbcef030b7)
- [minor] style consistency [`48ae5d8`](https://github.com/http-party/node-http-proxy/commit/48ae5d828c23d6f19c9e2dd8c922d88a09f5ed0f)
- Updated to support error callback on proxy.web and start/proxyReq/end continue working. [`9ba8311`](https://github.com/http-party/node-http-proxy/commit/9ba8311343fd01b32505b8607ecf4294200f9dde)
- style changes [`84036e9`](https://github.com/http-party/node-http-proxy/commit/84036e9ddd1d4d925006c5438b3bcc0f17ba7a48)
- [fix] be defensive and ensure location is in headers before running url.parse() [`8d68ac0`](https://github.com/http-party/node-http-proxy/commit/8d68ac0e0fa3080b31580aa08e92a46cc1f27696)
- [dist] Version bump. 1.7.0 [`276f65a`](https://github.com/http-party/node-http-proxy/commit/276f65a3b810ded01757ec4bfd4fe2b00a1e66a8)

## [v1.6.2](https://github.com/http-party/node-http-proxy/compare/v1.6.1...v1.6.2) - 2014-11-11

### Merged

- do not modify the query string [`#733`](https://github.com/http-party/node-http-proxy/pull/733)

### Commits

- [fix] style changes [`7c5e40a`](https://github.com/http-party/node-http-proxy/commit/7c5e40a429fbc0c538f38d29d74acb633cb9b8d4)
- [minor] this shouldnt be in var block [`3f19e6e`](https://github.com/http-party/node-http-proxy/commit/3f19e6e178e168a16beee74186691f3e0e54d517)
- [dist] Version bump. 1.6.2 [`709b3e9`](https://github.com/http-party/node-http-proxy/commit/709b3e96560d619fab2617f9ddb902b4982b4103)

## [v1.6.1](https://github.com/http-party/node-http-proxy/compare/v1.6.0...v1.6.1) - 2014-11-04

### Merged

- websocket needs to respect `options.secure` too [`#729`](https://github.com/http-party/node-http-proxy/pull/729)
- changeOrigin option docs fix [`#724`](https://github.com/http-party/node-http-proxy/pull/724)

### Commits

- [dist] Version bump. 1.6.1 [`fa797fc`](https://github.com/http-party/node-http-proxy/commit/fa797fca900c10ebc848a2b445204b47da799483)

## [v1.6.0](https://github.com/http-party/node-http-proxy/compare/v1.5.3...v1.6.0) - 2014-10-29

### Merged

- Added changeOrigin option with test and docs [`#723`](https://github.com/http-party/node-http-proxy/pull/723)
- I presume you mean couchdb here [`#717`](https://github.com/http-party/node-http-proxy/pull/717)
- update modify request body eg [`#712`](https://github.com/http-party/node-http-proxy/pull/712)

### Commits

- harmon notes [`9f684d0`](https://github.com/http-party/node-http-proxy/commit/9f684d0439174d889d7b9a4ef6e2353e09481b2d)
- [dist] Version bump. 1.6.0 [`43641b0`](https://github.com/http-party/node-http-proxy/commit/43641b00b34ccc05bdf09f904695061d7c857aeb)

## [v1.5.3](https://github.com/http-party/node-http-proxy/compare/v1.5.2...v1.5.3) - 2014-10-01

### Merged

- close socket if upstream request fails [`#709`](https://github.com/http-party/node-http-proxy/pull/709)

### Commits

- [dist] Version bump. 1.5.3 [`9577a0f`](https://github.com/http-party/node-http-proxy/commit/9577a0faf2b78af606168673407ac47a851c084c)

## [v1.5.2](https://github.com/http-party/node-http-proxy/compare/v1.5.1...v1.5.2) - 2014-10-01

### Merged

- close websocket if proxyReq is closed before upgrade [`#708`](https://github.com/http-party/node-http-proxy/pull/708)

### Commits

- test closing upstream socket prior to upgrade [`7730548`](https://github.com/http-party/node-http-proxy/commit/77305489d9b88d283802477e155340e5dacfcc2c)
- [dist] Version bump. 1.5.2 [`43c6f0c`](https://github.com/http-party/node-http-proxy/commit/43c6f0c7c06d25a670c410500a8623531df458b1)

## [v1.5.1](https://github.com/http-party/node-http-proxy/compare/v1.5.0...v1.5.1) - 2014-09-30

### Commits

- [fix] do a check to make sure the server exists before we try and emit [`10a294a`](https://github.com/http-party/node-http-proxy/commit/10a294af4d4baac30b98ea9bec683a974443b83d)
- [dist] Version bump. 1.5.1 [`f0bf741`](https://github.com/http-party/node-http-proxy/commit/f0bf7418156db2cb87a616b0a34bb1f028db9142)

## [v1.5.0](https://github.com/http-party/node-http-proxy/compare/v1.4.3...v1.5.0) - 2014-09-30

### Merged

- exposing proxySocket on socket to support sniffing messages coming from proxy target [`#706`](https://github.com/http-party/node-http-proxy/pull/706)
- Fixed misleading documentation [`#705`](https://github.com/http-party/node-http-proxy/pull/705)
- Fix typo in README.md [`#702`](https://github.com/http-party/node-http-proxy/pull/702)
- handle 'upgrade' in comma-separated connection header [`#691`](https://github.com/http-party/node-http-proxy/pull/691)

### Commits

- test new detection of connection: upgrade [`ec683b9`](https://github.com/http-party/node-http-proxy/commit/ec683b924b1ef8cbdd2cd2bfb7e141b502773163)
- emitting proxySocket on proxyServer [`000eb53`](https://github.com/http-party/node-http-proxy/commit/000eb533de144cad01cfd97edf9ab6c350593d3c)
- [fix] perf optimization so we have a precompiled regexp [`c0a796b`](https://github.com/http-party/node-http-proxy/commit/c0a796b3e31de4f22eef00d93164e7238d9aa3ba)
- use regex to check for upgrade header [`65a21bc`](https://github.com/http-party/node-http-proxy/commit/65a21bce6dbbc6142a851dc959e237c0ef2b1091)
- [dist] Version bump. 1.5.0 [`232258b`](https://github.com/http-party/node-http-proxy/commit/232258b6ec2229497fe557454a121d917968f5e8)
- [minor] extra space [`e7d50b1`](https://github.com/http-party/node-http-proxy/commit/e7d50b1a376035a50c82db38605e99feb30afd36)

## [v1.4.3](https://github.com/http-party/node-http-proxy/compare/v1.4.2...v1.4.3) - 2014-09-12

### Merged

- Urgent: Fix breaking bug on url joining resulting in paths like `///path`. [`#699`](https://github.com/http-party/node-http-proxy/pull/699)

### Commits

- [minor] Added missing JSDoc comments [`73e8a4c`](https://github.com/http-party/node-http-proxy/commit/73e8a4cdd576868bf61d0848cc51f083a75454f9)
- Fix breaking bug on url joining resulting in paths like `///path`. [`73d865b`](https://github.com/http-party/node-http-proxy/commit/73d865bc9f8940f61c1ad4812f220920ead553b5)
- [minor] Code style adjustment. [`3ab6e95`](https://github.com/http-party/node-http-proxy/commit/3ab6e9591e66c203647605b4f275d374472c9d5f)
- Bump version v1.4.3 [`554f59c`](https://github.com/http-party/node-http-proxy/commit/554f59c5182d58b359df0159a29ff5ea35dd3830)
- [ignore] Ignore npm-debug.log [`a934cb6`](https://github.com/http-party/node-http-proxy/commit/a934cb6a46298c380e9bc794f18873576cf73c4c)

## [v1.4.2](https://github.com/http-party/node-http-proxy/compare/v1.4.1...v1.4.2) - 2014-09-12

### Commits

- [fix] ensure path works on windows because path.join doesnt like URLs [`ed73f06`](https://github.com/http-party/node-http-proxy/commit/ed73f06ed307ad2204e565781cc3154047941a8c)
- [dist] Version bump. 1.4.2 [`df12aeb`](https://github.com/http-party/node-http-proxy/commit/df12aeb12de79de1157898d45f4347fd0037dd70)

## [v1.4.1](https://github.com/http-party/node-http-proxy/compare/v1.3.1...v1.4.1) - 2014-09-11

### Merged

- Trimming contents of distributed npm package. [`#644`](https://github.com/http-party/node-http-proxy/pull/644)
- Remove changelog - it was not maintained [`#669`](https://github.com/http-party/node-http-proxy/pull/669)
- Removed duplicated imported dependencies [`#695`](https://github.com/http-party/node-http-proxy/pull/695)

### Commits

- [test] add test for prependPath option [`e44fabe`](https://github.com/http-party/node-http-proxy/commit/e44fabe58a233b367d42f26f15113e2022f71d7b)
- [api] add prependPath option to go with path change [`9a534c6`](https://github.com/http-party/node-http-proxy/commit/9a534c6ff63d776140918bc839801d247affd18d)
- [dist] Version bump. 1.4.1 [`d5c656b`](https://github.com/http-party/node-http-proxy/commit/d5c656bceb50dc9008ef223bc58b918adcf05352)
- [dist] Version bump. 1.4.0 [`dceef40`](https://github.com/http-party/node-http-proxy/commit/dceef407a1130033679e7e836c6753b76187ce5f)

## [v1.3.1](https://github.com/http-party/node-http-proxy/compare/v1.3.0...v1.3.1) - 2014-09-09

### Merged

- Allow proxy to maintain the original target path [`#693`](https://github.com/http-party/node-http-proxy/pull/693)
- Clarify usable parameters for 'proxyRes' event [`#686`](https://github.com/http-party/node-http-proxy/pull/686)

### Commits

- fix tests for maintaining proxy path [`a65021d`](https://github.com/http-party/node-http-proxy/commit/a65021d52b0ee039486819b5a95f442229458776)
- Fix proxy path [`511b7b3`](https://github.com/http-party/node-http-proxy/commit/511b7b3d4743636de9d9fbe8ff409730d221d273)
- Clarify usable parameters for proxyRes event. [`49a0de1`](https://github.com/http-party/node-http-proxy/commit/49a0de1e7cdcec9b555695605ab914038f99d66b)
- [dist] Version bump. 1.3.1 [`fc73828`](https://github.com/http-party/node-http-proxy/commit/fc73828035baf3cea3664560f8964f2a2a200d0a)
- [ci] remove 0.11.x to avoid failing builds caused by TLS errors [`6b83ae4`](https://github.com/http-party/node-http-proxy/commit/6b83ae47bbf2d5eab8ac94b4d6130e09a21ac85b)

## [v1.3.0](https://github.com/http-party/node-http-proxy/compare/v1.2.1...v1.3.0) - 2014-08-14

### Merged

- Added functionality to close proxy. [`#679`](https://github.com/http-party/node-http-proxy/pull/679)

### Commits

- [fix] cleanup and stylize close function [`261742a`](https://github.com/http-party/node-http-proxy/commit/261742a4295268ef93f45aa0f1e3a04208a2aed3)
- updated close function for safety [`8be9d94`](https://github.com/http-party/node-http-proxy/commit/8be9d945d03169056bbf84d702292b5763b015dc)
- [dist] Version bump. 1.3.0 [`05f0b89`](https://github.com/http-party/node-http-proxy/commit/05f0b891a610fb7779f90916fcd9ed750df818b2)

## [v1.2.1](https://github.com/http-party/node-http-proxy/compare/v1.2.0...v1.2.1) - 2014-08-14

### Commits

- Added close method to proxy server. [`a3d0219`](https://github.com/http-party/node-http-proxy/commit/a3d02196c5e62cd58bc0ebe8a66afcdb905d96b3)
- [fix] emit an error if proper URL is not passed in as a target [`37036dd`](https://github.com/http-party/node-http-proxy/commit/37036dd32565f72ad5777e47509293db18b60ed3)
- [dist] Version bump. 1.2.1 [`0a6b424`](https://github.com/http-party/node-http-proxy/commit/0a6b424e2c3b6cef68362a71f0e56740b2605af7)

## [v1.2.0](https://github.com/http-party/node-http-proxy/compare/v1.1.6...v1.2.0) - 2014-08-05

### Merged

- [api] Add event-based ability to modify pre-flight proxy requests. [`#673`](https://github.com/http-party/node-http-proxy/pull/673)

### Commits

- [dist] Version bump. 1.2.0 [`63c53a1`](https://github.com/http-party/node-http-proxy/commit/63c53a177217283ec14e4f7c2e891db48842ab4b)

## [v1.1.6](https://github.com/http-party/node-http-proxy/compare/v1.1.5...v1.1.6) - 2014-07-17

### Fixed

- do proper checking for a pass not existing. fixes #671 [`#671`](https://github.com/http-party/node-http-proxy/issues/671)

### Commits

- Remove changelog - it was not maintained [`e336b52`](https://github.com/http-party/node-http-proxy/commit/e336b52629276e647abeee300d7091db44e5b885)
- [dist] Version bump. 1.1.6 [`ed9e12b`](https://github.com/http-party/node-http-proxy/commit/ed9e12b0edb0fc206610e94bd696425619868474)

## [v1.1.5](https://github.com/http-party/node-http-proxy/compare/v1.1.4...v1.1.5) - 2014-07-10

### Merged

- Fix simple-balancer example [`#666`](https://github.com/http-party/node-http-proxy/pull/666)
- Added proxyTimeout option and two tests for timeout [`#658`](https://github.com/http-party/node-http-proxy/pull/658)

### Fixed

- Fix #657 [`#657`](https://github.com/http-party/node-http-proxy/issues/657)
- Fix #657 [`#657`](https://github.com/http-party/node-http-proxy/issues/657)

### Commits

- Added targetTimeout option and two tests for timeout [`0f24351`](https://github.com/http-party/node-http-proxy/commit/0f243516e1c6737b95fba220a5028439264b5de6)
- Change name targetTimeout to proxyTimeout [`7b79a74`](https://github.com/http-party/node-http-proxy/commit/7b79a7409ade7a8c79b2ae5761abc4843529063a)
- Trimming contents of distributed npm package. [`431aba7`](https://github.com/http-party/node-http-proxy/commit/431aba79d8d521e228c1403aaf4fd4a26fba03c3)
- [api] also emit the target on a proxy error [`d1baa36`](https://github.com/http-party/node-http-proxy/commit/d1baa3684e449610a2aae270816a7b8a907e588e)
- [dist] Version bump. 1.1.5 [`7104a7c`](https://github.com/http-party/node-http-proxy/commit/7104a7c023073a49091969f825738c79ae036123)
- fix balancer example [`9df4bc1`](https://github.com/http-party/node-http-proxy/commit/9df4bc1e1216a8e53675f0be16fb9081c11da225)

## [v1.1.4](https://github.com/http-party/node-http-proxy/compare/v1.1.3...v1.1.4) - 2014-05-11

### Merged

- `proxyRes` event, provide access to the req and res objects [`#642`](https://github.com/http-party/node-http-proxy/pull/642)

### Commits

- Add a test for the proxyRes event [`1385635`](https://github.com/http-party/node-http-proxy/commit/1385635e18f081af759c8e088f2f6b0219df83db)
- [dist] Version bump. 1.1.4 [`7cb98a4`](https://github.com/http-party/node-http-proxy/commit/7cb98a4e417312f01cf4432b52dbb3773aca60a0)
- Add the req and res objects to the proxyRes event [`1213e46`](https://github.com/http-party/node-http-proxy/commit/1213e46b1b0975ad1d5c5d0aaeace40a0811118f)

## [v1.1.3](https://github.com/http-party/node-http-proxy/compare/v1.1.2...v1.1.3) - 2014-05-11

### Merged

- Don't override connection header if Upgrading [`#640`](https://github.com/http-party/node-http-proxy/pull/640)

### Commits

- Adding test cases on preventing upgrade override [`8aa7c51`](https://github.com/http-party/node-http-proxy/commit/8aa7c519b15f734af7db34d2102781adbeae10aa)
- Update README.md for benchmarks [`4947484`](https://github.com/http-party/node-http-proxy/commit/4947484806f839d5e0a1b615b56a1bc847b8f534)
- [minor] style [`ccad177`](https://github.com/http-party/node-http-proxy/commit/ccad17795417de74bea2bcb6d6c559a4601af76d)
- [dist] Version bump. 1.1.3 [`c472527`](https://github.com/http-party/node-http-proxy/commit/c472527ea60da8b2f737d5742bc61ad2772b7e0b)

## [v1.1.2](https://github.com/http-party/node-http-proxy/compare/v1.1.1...v1.1.2) - 2014-04-14

### Commits

- [fix test] handle proxy error since we are properly aborting the proxy Request [`61c8734`](https://github.com/http-party/node-http-proxy/commit/61c8734e8b1115fab0e0db23fd8eeccbae61eee0)
- [fix] handle error on incoming request as well and properly abort proxy if client request is aborted [`77a1cff`](https://github.com/http-party/node-http-proxy/commit/77a1cff9bcf697eab27819eef054024bdc0a2ba3)
- [dist] Version bump. 1.1.2 [`c54278b`](https://github.com/http-party/node-http-proxy/commit/c54278bd3b00e82f4253393b6f6beb1d5a1b19e5)

## [v1.1.1](https://github.com/http-party/node-http-proxy/compare/v1.1.0...v1.1.1) - 2014-04-11

### Commits

- [dist] Version bump. 1.1.1 [`d908e2a`](https://github.com/http-party/node-http-proxy/commit/d908e2ad61013ed1f6e2f80c4b67a6dce7d0f504)
- [fix] let user make the decision on what to do with the buffer [`4f07dc2`](https://github.com/http-party/node-http-proxy/commit/4f07dc220d700ac90bd8405f7cb0724bdae4b430)

## [v1.1.0](https://github.com/http-party/node-http-proxy/compare/v1.0.3...v1.1.0) - 2014-04-09

### Merged

- Update UPGRADING.md [`#616`](https://github.com/http-party/node-http-proxy/pull/616)

### Fixed

- [fix] always be an eventemitter for consistency fixes #606 [`#606`](https://github.com/http-party/node-http-proxy/issues/606)

### Commits

- [api] emit a start an an end event [`8b48a9f`](https://github.com/http-party/node-http-proxy/commit/8b48a9fdab01624f7249c53f25919b1295eefb10)
- [dist] Version bump. 1.1.0 [`97ceeb3`](https://github.com/http-party/node-http-proxy/commit/97ceeb37d04e5d2195352365985165866323c4d7)
- [minor] missing angle bracket [`eca765a`](https://github.com/http-party/node-http-proxy/commit/eca765a856164c077ff9128949019552cdaf9a67)

## [v1.0.3](https://github.com/http-party/node-http-proxy/compare/v1.0.2...v1.0.3) - 2014-03-27

### Merged

- Fix for #591 [`#592`](https://github.com/http-party/node-http-proxy/pull/592)
- Add Repository field to package.json [`#578`](https://github.com/http-party/node-http-proxy/pull/578)
- Fix doc: option lines [`#575`](https://github.com/http-party/node-http-proxy/pull/575)

### Fixed

- [api] add toProxy method to allow absolute URLs to be sent when sending to another proxy fixes #603 [`#603`](https://github.com/http-party/node-http-proxy/issues/603)

### Commits

- [doc] update docs with toProxy option [`ece85b4`](https://github.com/http-party/node-http-proxy/commit/ece85b4e1ba379b3ed084bd8f606e285c14d4db3)
- [fix] set connection to CLOSE in cases where the agent is false. [`89a22bc`](https://github.com/http-party/node-http-proxy/commit/89a22bc00396f069eeb054ce30891a204077d16d)
- @xtreme-topher-bullock - update package.json to have proper repository key and formatting [`68fa17b`](https://github.com/http-party/node-http-proxy/commit/68fa17bbcaa73ae2d9539cba6f6ddff29f9e30d5)
- [dist] Version bump. 1.0.3 [`07fceb7`](https://github.com/http-party/node-http-proxy/commit/07fceb7c7aed25a8991d0295db4b4a7e50d79cf9)
- Add support for localAddress [`e633b0f`](https://github.com/http-party/node-http-proxy/commit/e633b0f7e4fd719d809eaeb4725e589f79c271ab)

## [v1.0.2](https://github.com/http-party/node-http-proxy/compare/v1.0.1...v1.0.2) - 2014-01-28

### Merged

- Update README.md [`#566`](https://github.com/http-party/node-http-proxy/pull/566)
- Fix argument order for ws stream pass [`#560`](https://github.com/http-party/node-http-proxy/pull/560)
- Extend listen to enable IPv6 support. [`#558`](https://github.com/http-party/node-http-proxy/pull/558)
- Fix before and after type check [`#556`](https://github.com/http-party/node-http-proxy/pull/556)

### Fixed

- Close outgoing ws if incoming ws emits error [`#559`](https://github.com/http-party/node-http-proxy/issues/559)
- [fix] closes #555 [`#555`](https://github.com/http-party/node-http-proxy/issues/555)

### Commits

- [fix] replicate node core behavior and throw an error if the user does not add their own error listener [`daad470`](https://github.com/http-party/node-http-proxy/commit/daad4703f3a80014936c89f4d67affdc3246f478)
- [dist] Version bump. 1.0.2 [`4bdc3e4`](https://github.com/http-party/node-http-proxy/commit/4bdc3e4f455b2749c03961404db74e3112a3e9e8)
- [doc] Fix broken image in npm by using an absolute link [`8004f4e`](https://github.com/http-party/node-http-proxy/commit/8004f4e5fc0f535806e92ec4e1bd973a45367dac)

## [v1.0.1](https://github.com/http-party/node-http-proxy/compare/v1.0.0...v1.0.1) - 2014-01-17

### Fixed

- [fix] closes #553 [`#553`](https://github.com/http-party/node-http-proxy/issues/553)

### Commits

- [dist] bump v1.0.1 [`68c5512`](https://github.com/http-party/node-http-proxy/commit/68c55123039369cdf8a55a64b36b719c96b672cf)
- typo [`689459f`](https://github.com/http-party/node-http-proxy/commit/689459fe46885a1b3b8e32a4df55f2d1339143e5)

## [v1.0.0](https://github.com/http-party/node-http-proxy/compare/v0.10.4...v1.0.0) - 2014-01-16

### Merged

- Http proxy 1.0 [`#552`](https://github.com/http-party/node-http-proxy/pull/552)
- Caronte [`#551`](https://github.com/http-party/node-http-proxy/pull/551)
- Only emit response if a valid server is present [`#549`](https://github.com/http-party/node-http-proxy/pull/549)
- [fix] add `type` to before and after to grab correct `passes`, fixes #537 [`#539`](https://github.com/http-party/node-http-proxy/pull/539)
- export the proxy itself from the main require [`#536`](https://github.com/http-party/node-http-proxy/pull/536)

### Fixed

- [fix] closes #547 [`#547`](https://github.com/http-party/node-http-proxy/issues/547)
- Merge pull request #539 from nodejitsu/fix-before-after [`#537`](https://github.com/http-party/node-http-proxy/issues/537)
- [fix] add `type` to before and after to grab correct `passes`, fixes #537 [`#537`](https://github.com/http-party/node-http-proxy/issues/537)

### Commits

- [nuke] old files [`a4ee8f9`](https://github.com/http-party/node-http-proxy/commit/a4ee8f9d82f71ef423c401b1f5e9f712b13cbc98)
- [docs] upgrade UPGRADING.md [`e599151`](https://github.com/http-party/node-http-proxy/commit/e5991519dbc7838aa4b8aeb5077d1c1ec5a13813)
- [api] export the httpProxy.Server as the main export but preserve the createServer factory [`182c76c`](https://github.com/http-party/node-http-proxy/commit/182c76cd2322d4d4c041c2a964d51db396c5c96b)
- [fix] remove caronte [`d6d2d0c`](https://github.com/http-party/node-http-proxy/commit/d6d2d0c8821bba9888eee7c3881fc408b3b2008e)
- [fix] ee3 error handling [`d23353d`](https://github.com/http-party/node-http-proxy/commit/d23353d980d8aa1b2606e3d36a83d27432952bef)
- [fix] comments [`6fa23e1`](https://github.com/http-party/node-http-proxy/commit/6fa23e11f6dc0b9c09766b268611ade919bfaa08)

## [v0.10.4](https://github.com/http-party/node-http-proxy/compare/v0.10.3...v0.10.4) - 2013-12-27

### Merged

- Update README.md [`#521`](https://github.com/http-party/node-http-proxy/pull/521)
- Better examples [`#520`](https://github.com/http-party/node-http-proxy/pull/520)
- Send path in req.path and not the url [`#416`](https://github.com/http-party/node-http-proxy/pull/416)
- Fix websocket error handing [`#518`](https://github.com/http-party/node-http-proxy/pull/518)
- attempting to fix links to 2 source locations in README.md [`#502`](https://github.com/http-party/node-http-proxy/pull/502)
- [merge] rename codename to actual project name [`#492`](https://github.com/http-party/node-http-proxy/pull/492)
- [merge] Added error handling example [`#484`](https://github.com/http-party/node-http-proxy/pull/484)
- [merge] https & agent [`#482`](https://github.com/http-party/node-http-proxy/pull/482)
- [merge] caronte tests [`#476`](https://github.com/http-party/node-http-proxy/pull/476)
- FIX: ws error event [`#475`](https://github.com/http-party/node-http-proxy/pull/475)
- Fix accidental write to global variable. [`#472`](https://github.com/http-party/node-http-proxy/pull/472)
- [fix] 2 spelling mistakes [`#14`](https://github.com/http-party/node-http-proxy/pull/14)
- [fix] add ability to proxy websockets over HTTPS [`#11`](https://github.com/http-party/node-http-proxy/pull/11)
- Tests [`#3`](https://github.com/http-party/node-http-proxy/pull/3)

### Fixed

- determine x-forwarded-port from host header [`#341`](https://github.com/http-party/node-http-proxy/issues/341)
- [fix] closes #529 [`#529`](https://github.com/http-party/node-http-proxy/issues/529)
- [fix] fixes #341 [`#341`](https://github.com/http-party/node-http-proxy/issues/341)
- [tests] https test pass, fix #511. Exposed the rejectUnauthorized flag [`#511`](https://github.com/http-party/node-http-proxy/issues/511)
- [fix] pass proper options object that extend the global options and parse the per proxy args into options. fixes #510 [`#510`](https://github.com/http-party/node-http-proxy/issues/510)
- [readme] add links to badges on readme, fix #483 [`#483`](https://github.com/http-party/node-http-proxy/issues/483)
- [fix] pooled connections, closes #478 [`#478`](https://github.com/http-party/node-http-proxy/issues/478)
- [fix] add 0.10 link, fixes #459 [`#459`](https://github.com/http-party/node-http-proxy/issues/459)
- [fix] closes #473 [`#473`](https://github.com/http-party/node-http-proxy/issues/473)
- [fix] add 0.10 compatibily.. closes #474 [`#474`](https://github.com/http-party/node-http-proxy/issues/474)
- [fix] headers, closes #469 [`#469`](https://github.com/http-party/node-http-proxy/issues/469)
- [fix] headers, fixes #467 [`#467`](https://github.com/http-party/node-http-proxy/issues/467)
- [fix] yawnt baaaka .. fixes #8 [`#8`](https://github.com/http-party/node-http-proxy/issues/8)

### Commits

- [fix] more jshint intendation [`17399e7`](https://github.com/http-party/node-http-proxy/commit/17399e7c3ef9addf9dd8f7c628b273e693f128a1)
- [fix] tests [`a255f98`](https://github.com/http-party/node-http-proxy/commit/a255f984fecf24c9290f3ad58d1b68e54a7509eb)
- [minor] remove coverage [`335af81`](https://github.com/http-party/node-http-proxy/commit/335af81d0244e62ecb501690bd15bc5a04ec51a3)
- [examples] updated websockets examples [`ed8c9ee`](https://github.com/http-party/node-http-proxy/commit/ed8c9eeba99d60f39f5c36c4f34ed1a781d2cfd8)
- [tests] removed unused tests [`7e25bde`](https://github.com/http-party/node-http-proxy/commit/7e25bded27effc1b3d47121ce21465a4e2ec7c0b)
- [tests] Added a test case for run all the examples [`bc236d7`](https://github.com/http-party/node-http-proxy/commit/bc236d7e95ef10bc17cf551eea2cd2fb9bf265eb)
- [tests] drop the test of own streams, moved the usable tests [`dc9d7e5`](https://github.com/http-party/node-http-proxy/commit/dc9d7e5452c7d39ae1d242cb8021ca75e4f736d4)
- [fix] default port [`d166354`](https://github.com/http-party/node-http-proxy/commit/d1663549ec070e7ae8bc45ffb148f40ee903192f)
- [tests] added the ws passes test and the streams webscokets test [`8b3fe32`](https://github.com/http-party/node-http-proxy/commit/8b3fe32f6ae60ae067bc5e40cdc43015e689467f)
- [refactor minor] s/caronte/http-proxy/ or s/caronte/httpProxy/ where appropriate. [`bb0d28c`](https://github.com/http-party/node-http-proxy/commit/bb0d28c58729e2cc70e8446f7fbf1113a6fa9310)
- [examples] updated bodyDecoder middleware example [`c82ff2c`](https://github.com/http-party/node-http-proxy/commit/c82ff2c3c0c0165421fbc4e7e94fa3f59d59aa38)
- [dist] first [`4d13156`](https://github.com/http-party/node-http-proxy/commit/4d131567211bcefc6ef0b0592d374fef7bd5abd8)
- [examples] update forward and custom error examples [`b726116`](https://github.com/http-party/node-http-proxy/commit/b7261161343c3471201d6de36ba1030aced26425)
- [refactor docs] add descriptions [`d05af4a`](https://github.com/http-party/node-http-proxy/commit/d05af4af60a5f3d308aa68bf09ab0cf9e5528c52)
- [tests] make the tests run with the last refactor [`5bb83b9`](https://github.com/http-party/node-http-proxy/commit/5bb83b967edb514402698eecfe3db7ab5fe60b06)
- [examples] deleted this examples [`bdeabb7`](https://github.com/http-party/node-http-proxy/commit/bdeabb767a537bcb9f98ef74f6efe9762a9b1c34)
- websocket draft [`07551c6`](https://github.com/http-party/node-http-proxy/commit/07551c63e428551e5d6e52362efd9620a14c71b4)
- [fix] naming [`2a59366`](https://github.com/http-party/node-http-proxy/commit/2a593664a5768c90d9b2edf4c298460416b38926)
- [dist doc] Added documentation for consistent benchmarking of node-http-proxy [`f7f5fa7`](https://github.com/http-party/node-http-proxy/commit/f7f5fa727e8f1d3f4946e61ad03830dab1da01a5)
- [examples] update old examples [`7e44d36`](https://github.com/http-party/node-http-proxy/commit/7e44d3669bbd1b13e6452f265d52b22396f68b5d)
- [docs] more short examples to the Readme [`0393b5d`](https://github.com/http-party/node-http-proxy/commit/0393b5da990bb45e873bb80d87a0bc9e4dd6a477)
- [examples] updated old proxy examples [`e02317c`](https://github.com/http-party/node-http-proxy/commit/e02317ce86ff2dabd496cf7e2741e219a22ac817)
- [wip] Initial HTTPS-&gt;HTTP test, updated https-secure example. Work in progress, need to add more https tests [`33a2462`](https://github.com/http-party/node-http-proxy/commit/33a2462d28c7d1fa26b03bcf290242ff7cd83e7a)
- [docs] readme [`886a870`](https://github.com/http-party/node-http-proxy/commit/886a8707078f59d0467b34686455bb5bdfadbc0c)
- [examples] added error-handling using callbacks and HTTP-to-HTTPS examples [`d7064f2`](https://github.com/http-party/node-http-proxy/commit/d7064f2e1e149fe870cbb158932cb99f9f192fce)
- [examples] updated old examples [`588327c`](https://github.com/http-party/node-http-proxy/commit/588327c2c4392618b515164989f08ef20a30842b)
- stuff [`e45bfd6`](https://github.com/http-party/node-http-proxy/commit/e45bfd66a21a2470c5a4a4cc1d6095494bbc0f6b)
- [doc] added some documentation to functions and comments to understand better the code [`5dcdf2b`](https://github.com/http-party/node-http-proxy/commit/5dcdf2b36c24a9584f044b7529265b9ac861d8c7)
- Fixed issue where error callback would not invoke, including new test cases. Added req/res values to error events. [`0bfb9be`](https://github.com/http-party/node-http-proxy/commit/0bfb9be418926f2113489e92504038127d4c04bb)
- [examples] updated balancer examples [`831a44b`](https://github.com/http-party/node-http-proxy/commit/831a44b3c8c3acf6c046c47703a07cd6362a0d1c)
- socket.io stuff [`a74cd85`](https://github.com/http-party/node-http-proxy/commit/a74cd85c8a5aae2851acf7139648fefd6a02a57b)
- [tests] move contributions of @mmoulton to correct place [`7c72f3b`](https://github.com/http-party/node-http-proxy/commit/7c72f3b407a084a896e420c23ababc3e9357feca)
- [tests] this file is not necessary anymore [`881c7e6`](https://github.com/http-party/node-http-proxy/commit/881c7e62e0bef7b4b9f81b6fd121f7ad6641bd77)
- [refactor] move to leaner architecture [`8273cb6`](https://github.com/http-party/node-http-proxy/commit/8273cb6461e4d33f36e583b0354d1bea038d0a56)
- [fix] remove trailing whitespaces [`0aeaba7`](https://github.com/http-party/node-http-proxy/commit/0aeaba7fe6c51f150d0322eb90a77c1701ed88f5)
- [test] added tests for web-outgoing.js [`16a4d9d`](https://github.com/http-party/node-http-proxy/commit/16a4d9da1136b79f40ad80482d3fd17dc74274b1)
- [fix] some stuff start debugging proxystream [`d4f0da8`](https://github.com/http-party/node-http-proxy/commit/d4f0da898e5e8a2d6740e50a7fc34576435e1132)
- [tests] now each test use a different port to avoid some slow opening and closing ports [`c75d06c`](https://github.com/http-party/node-http-proxy/commit/c75d06c5f92eb7c814deb49bb33cf9fffc632d97)
- [tests] fixed inherits problem and listen for the correct event [`c65ffbb`](https://github.com/http-party/node-http-proxy/commit/c65ffbb976467dc1768983dcffe111d18e8f2db1)
- [fix] ProxyStraem now works [`356f43d`](https://github.com/http-party/node-http-proxy/commit/356f43d719998d135e0fc404ac8508e330cf1e5b)
- [examples] fix the copyright header of example files [`e592c53`](https://github.com/http-party/node-http-proxy/commit/e592c53d1a23b7920d603a9e9ac294fc0e841f6d)
- [feature] start working on the new server [`b79bd29`](https://github.com/http-party/node-http-proxy/commit/b79bd29d5e984f34b9c07fbdc803aed83b3fd0bb)
- ENH: updated examples [`f566a42`](https://github.com/http-party/node-http-proxy/commit/f566a42e511f4a6a8f3620f64e05df209e61b64f)
- [examples] add example of gzip using the connect.compress() middleware [`2142c50`](https://github.com/http-party/node-http-proxy/commit/2142c506e08f56d52e1995da5506c3e032f19c3c)
- [fix] refactor error handling [`601dbcb`](https://github.com/http-party/node-http-proxy/commit/601dbcbfe929af31995568b4f36b877245809058)
- [tests] fixed according new refactor and added test to common.setupSocket() [`1cb967b`](https://github.com/http-party/node-http-proxy/commit/1cb967b90aaa5b9da57727b8acbd95108437797a)
- [feature] websocket support [`79a14ac`](https://github.com/http-party/node-http-proxy/commit/79a14acfd2b2bf03f5ae2b334e7a37e619da6bb9)
- keepalive sockets [`dad211e`](https://github.com/http-party/node-http-proxy/commit/dad211e71c9ac3b32eba1ea3755edb688053b9d3)
- [tests] Using target field, tests now pass. We are missing the tests using forward field [`8085178`](https://github.com/http-party/node-http-proxy/commit/8085178dc2c24567adfb872a583863709ce60b5b)
- [fix] callback as optional error handler [`c7924e0`](https://github.com/http-party/node-http-proxy/commit/c7924e01f92aeec07333273f0882c1dd5e9521ae)
- ENH: added new https example, needs to be simplified before merge [`427d8d8`](https://github.com/http-party/node-http-proxy/commit/427d8d85369b0cd1d38afa0dd0f28ac98fa16001)
- [test] proxystream test [`c961279`](https://github.com/http-party/node-http-proxy/commit/c9612798f1207a4c40b616608bf6274d79ad0e4d)
- [lib] initial draft to websockets passes [`79f7f99`](https://github.com/http-party/node-http-proxy/commit/79f7f99528661162ae4153856888f078f666e017)
- [fix] minor [`7599cee`](https://github.com/http-party/node-http-proxy/commit/7599cee3fd03a5ce645e313f35557a41c9ac1aee)
- [tests] added HTTPS to HTTPS test [`31d919b`](https://github.com/http-party/node-http-proxy/commit/31d919b0a3d0b7f574e88fc5eed093c6b1a53548)
- [feature] started working on error propagation, kinda sucks, gotta think it over [`9ab8749`](https://github.com/http-party/node-http-proxy/commit/9ab8749a9bec33b49c495975e8364336ad7be1a3)
- [test] testing the onResponse proxy method [`27df8d7`](https://github.com/http-party/node-http-proxy/commit/27df8d72ad86d02cfce00a6e5c183d93dd50f97e)
- [fix] remove duplicate [`10c0f11`](https://github.com/http-party/node-http-proxy/commit/10c0f11b68e39552051e508c7bf20d65d2d59177)
- [tests] add more tests [`cedc5c4`](https://github.com/http-party/node-http-proxy/commit/cedc5c4bd2059585e1222ec4f03f09e8bcc808fc)
- [docs] Update readme with more how to [`ae0faef`](https://github.com/http-party/node-http-proxy/commit/ae0faef5aa0080d742a9740f9cb38bfd54b7d97e)
- [tests] added test for socket.io proxying [`10a0db4`](https://github.com/http-party/node-http-proxy/commit/10a0db4f0dd4594839f9098b9d67130085a067bc)
- [tests] added test HTTPS to HTTP using own server [`bbe3bfd`](https://github.com/http-party/node-http-proxy/commit/bbe3bfdf98255b82a185a798ff9f29e74615b6ca)
- [examples] update the error-handling example using the new error handle way [`a1b25a1`](https://github.com/http-party/node-http-proxy/commit/a1b25a123b4ff71e731f9beb27c5e078acfead65)
- [fix] quote [`c4ddc4e`](https://github.com/http-party/node-http-proxy/commit/c4ddc4edd324d9910a11eea14561a0e3b953f29c)
- ENH: updated README and added examples file. [`07091b5`](https://github.com/http-party/node-http-proxy/commit/07091b5077a40dfee29f6fd33ecb38d3fa25b801)
- [test] passes/web.js (first 2 funcs) [`d40e4be`](https://github.com/http-party/node-http-proxy/commit/d40e4beb62381b962b6cf3254451de0a39f182b1)
- [test] add test for forwardstream [`8fc3389`](https://github.com/http-party/node-http-proxy/commit/8fc33893672d26013c2b2ff396b777bcf1751527)
- [tests] fixing tests, fixed some typos and changed how passes are stored [`a704213`](https://github.com/http-party/node-http-proxy/commit/a7042132c881656dd32f915d9b0b962f0ef92efb)
- [test] added the lib/caronte/streams/forward.js initial test, one test pending [`2fac7b9`](https://github.com/http-party/node-http-proxy/commit/2fac7b9b009b12a940efb22de3af6db55ee686a9)
- [api] add draft for proxystream [`4f24664`](https://github.com/http-party/node-http-proxy/commit/4f24664e8a50aa9b9a3ea155d067b85f94a8c81b)
- [experiment] new api for proxying [`07cfa6b`](https://github.com/http-party/node-http-proxy/commit/07cfa6b981ff54d8d96eea6c9aa4b560ee3867ec)
- [tests] the options got a problem and this test probe that timeout is not being set [`1d1ee88`](https://github.com/http-party/node-http-proxy/commit/1d1ee8858283d7c8984f1c1d6c5185b6822f9235)
- new error propagation [`3a39e44`](https://github.com/http-party/node-http-proxy/commit/3a39e444ff68a74f6b586f0736bbd3f8a2511ca5)
- [fix] docs [`ec981c5`](https://github.com/http-party/node-http-proxy/commit/ec981c5b74bf43dd36c8ca89833b751f59f01d38)
- [examples] added concurrent proxy example [`04c1011`](https://github.com/http-party/node-http-proxy/commit/04c10113f7a3b568fb95b18f30e4aca3e059d961)
- [fix] closes number #487 [`cde08fb`](https://github.com/http-party/node-http-proxy/commit/cde08fb2ee2df03c9457678d8e6776a5d89165b2)
- [test] started writing tests [`16eacfa`](https://github.com/http-party/node-http-proxy/commit/16eacfa961d2a2d80534e95eba83010ed6ab01b4)
- [tests] added tests for websockets [`02007ed`](https://github.com/http-party/node-http-proxy/commit/02007ed0fb38f798436ae5669bb18d4f27496667)
- Revert "[fix] fixed options and server reference to can access them from passes functions" [`babdf53`](https://github.com/http-party/node-http-proxy/commit/babdf531fecd32f9af0963902909fcfa2cd374f1)
- mm test file [`1a7bef0`](https://github.com/http-party/node-http-proxy/commit/1a7bef0cda58243416a263075dc6eb51f22b6dec)
- [fix] fixed options and server reference to can access them from passes functions [`90fb01d`](https://github.com/http-party/node-http-proxy/commit/90fb01d38ac5af7ef395547b24e985b6f63b4abc)
- [examples] added forward example [`7a3f6df`](https://github.com/http-party/node-http-proxy/commit/7a3f6dfbcc80ba32fa81004438c637e8d29eb029)
- [docs] add UPGRADING.md [`db12f6c`](https://github.com/http-party/node-http-proxy/commit/db12f6c24e22c034c698457cc28ff60c990b55a5)
- DOC: Added error handling example [`32a4088`](https://github.com/http-party/node-http-proxy/commit/32a40889cedfd6b0d92224aa921700a7b7271c68)
- [examples] updated the modifyResponse-middleware example [`de3ff11`](https://github.com/http-party/node-http-proxy/commit/de3ff11656b4a847de3a63b28feed39b6c816480)
- [test] test onError part, proxying to no where [`b85aa16`](https://github.com/http-party/node-http-proxy/commit/b85aa16e75401a223a947cde444d42cf7eeafb67)
- ENH: updated agent options in `common.setupOutgoing` [`12cda56`](https://github.com/http-party/node-http-proxy/commit/12cda561afe534427a5f84da9d7e0beb64a8ecbc)
- [fix] minor and short fixes [`e0faaaf`](https://github.com/http-party/node-http-proxy/commit/e0faaaf81152203b96f0313c68706468e7ee7357)
- support websockets [`4a4607d`](https://github.com/http-party/node-http-proxy/commit/4a4607d075a912746386d1751fd6b0fc98cf6b20)
- [test] COVERAGE [`004a46c`](https://github.com/http-party/node-http-proxy/commit/004a46c09df2f0f7b15d8e8f7119bc6039e0c01c)
- [misc] add a LICENSE file [`584ce76`](https://github.com/http-party/node-http-proxy/commit/584ce76e7576c906e25cdd04a2e079f97bcf86ff)
- ENH: updated https and agent option [`13741a8`](https://github.com/http-party/node-http-proxy/commit/13741a823f1c1c884d4a37e597e4b188598b0e25)
- [fix] write connection header [`2c10f25`](https://github.com/http-party/node-http-proxy/commit/2c10f256b658bc0e906c20f29d94ab7eaf653055)
- [fix] merge #495, thanks @glasser [`d0862af`](https://github.com/http-party/node-http-proxy/commit/d0862aff0c693366dcb11649b6abe1d011268953)
- support forward [`8c8c455`](https://github.com/http-party/node-http-proxy/commit/8c8c455541f21ad9a9ac7ca19d1f37368206a2e2)
- [tests] fix tests set correct host headers [`cfd417d`](https://github.com/http-party/node-http-proxy/commit/cfd417de2352b0f05535b979dc15abff60c1fb96)
- [fix] Optimize fix for `x-forwarded-for-port`. [`2d42709`](https://github.com/http-party/node-http-proxy/commit/2d42709c3283637de16a49e815b03e63432bbd29)
- ENH: updated readme with an example [`edd8e2f`](https://github.com/http-party/node-http-proxy/commit/edd8e2f04e4b39391b062fa6437d61b4ebde8748)
- [doc] update README.md [`dcb873a`](https://github.com/http-party/node-http-proxy/commit/dcb873ad9992b1534615d59b8a0a70e8b87d7884)
- [test] passes/web.js XHeaders func [`c02b721`](https://github.com/http-party/node-http-proxy/commit/c02b721321c455bc287c3fed6b9b21392ce2fc70)
- [fix] fixed passes functions, now 'this' can be used and options are stored on 'this.options' [`9b3e1eb`](https://github.com/http-party/node-http-proxy/commit/9b3e1eb247df29d18ea299ff4ebb2f10eeb71269)
- Revert "[fix] fixed passes functions, now 'this' can be used and options are stored on 'this.options'" [`5e130de`](https://github.com/http-party/node-http-proxy/commit/5e130de8548ad41b821da49299b4fd1c9536c5f0)
- [minor] Remove duplicate dependencies and cleanup of the scripts [`a51b062`](https://github.com/http-party/node-http-proxy/commit/a51b0622780f48160001f9e74340f7d720cbfce6)
- TEST: added agent and header tests [`39b0c46`](https://github.com/http-party/node-http-proxy/commit/39b0c46a6967fda5329760ad93a8ec01bc4a6f14)
- [examples] fix styling and bad spaces [`6a6dfbb`](https://github.com/http-party/node-http-proxy/commit/6a6dfbb79dc156679f75dd519344d19a5b61613b)
- ENH: added error events [`1b867a7`](https://github.com/http-party/node-http-proxy/commit/1b867a7f594f7dfe49fc17ff53451a353ec509d9)
- [test] remove chunked on http1.0 [`ca09263`](https://github.com/http-party/node-http-proxy/commit/ca092635e7ac4d967b554e3b94a16a931946d464)
- [tests] fix test to use the new way to pass options [`52ecd52`](https://github.com/http-party/node-http-proxy/commit/52ecd52ee5aa78603e44ba8d5ff9187410351622)
- [examples] fixed https examples [`a467b7b`](https://github.com/http-party/node-http-proxy/commit/a467b7b4a9614a7cbfdc256524e1495616e3d4d9)
- Revert "[tests] fix test to use the new way to pass options" [`2bf20d6`](https://github.com/http-party/node-http-proxy/commit/2bf20d61d53201e9820c5f9215e641fcf88f5172)
- [fix] better code [`3d8e538`](https://github.com/http-party/node-http-proxy/commit/3d8e5383cd9d527825f95d9071a87865fcebca05)
- [feature] implement _write and _read [`6a4294c`](https://github.com/http-party/node-http-proxy/commit/6a4294cbdfe85fa162969b1393032adc9d418441)
- [fix] use the correct arguments order [`cc09ae6`](https://github.com/http-party/node-http-proxy/commit/cc09ae6a345cfde1689e1d8731c5822675c59d4d)
- [fix] fix the correct order of arguments in ws-incoming passes [`02df9a3`](https://github.com/http-party/node-http-proxy/commit/02df9a33c5cce17ea32a892017acbe5ce57ab2e5)
- [fix] write status [`e08d4ed`](https://github.com/http-party/node-http-proxy/commit/e08d4edad339d0f7f55900b3e6e6a0e770960215)
- [fix] finished jshint fixes [`455f97e`](https://github.com/http-party/node-http-proxy/commit/455f97e14cb4929e0a3a5c746471e9c5e76436fc)
- Update the README to describe middleware err handler. [`25bb3bf`](https://github.com/http-party/node-http-proxy/commit/25bb3bfa7012e0f975e10f0311cae8c39183fa41)
- Prevent headers to be sent twice [`8332e74`](https://github.com/http-party/node-http-proxy/commit/8332e744202ed9de94288d8f1c822cd9fe788983)
- [examples] added package.json with the dependencies needed by examples [`d85ccdd`](https://github.com/http-party/node-http-proxy/commit/d85ccdd333edcfc7551bcf8e0ffd7dc166e38e61)
- [tests] added .travis.yml file [`0602500`](https://github.com/http-party/node-http-proxy/commit/06025002303f351f71d9e5f78a93895257f0d283)
- [dist minor] 2 space indents next time @samalba [`7e8041d`](https://github.com/http-party/node-http-proxy/commit/7e8041d2b687b8375a1d0fe45270029c6e8ddee6)
- [fix] naming [`8931009`](https://github.com/http-party/node-http-proxy/commit/893100972c22febbf133134394bc0bcef47d9e12)
- Fix for #458. Host header may cause some sites not to be proxyable with changeOrigin enabled [`781c038`](https://github.com/http-party/node-http-proxy/commit/781c038f2b4d14a01cc9297e1e0dba6ce39dd6cb)
- [docs] typos, typos everywhere... [`03880d8`](https://github.com/http-party/node-http-proxy/commit/03880d8d069e9e17ca7d7aea6eb760f6626a869c)
- ENH: updated `ws` and `web` functions to use the global options object as a base [`268afe3`](https://github.com/http-party/node-http-proxy/commit/268afe34bb51448d511c9cd73c03e97d1c1baee0)
- [fix] make @mmalecki a happy camper [`c9cd6d2`](https://github.com/http-party/node-http-proxy/commit/c9cd6d2ad324e0e6222932c8f29f27621071e045)
- write [`f97c0c6`](https://github.com/http-party/node-http-proxy/commit/f97c0c6167371c5ff92e6361b1df02e3fd5506d7)
- [fix] [`a9f9e21`](https://github.com/http-party/node-http-proxy/commit/a9f9e21eda2f8e912523e6b62abb0101c0353505)
- [fix] coveralls.. will it work? [`f36cb4d`](https://github.com/http-party/node-http-proxy/commit/f36cb4d5a110fc86272e878278f103f313c86f56)
- ENH: updated target and forward options so that a string may be specified [`ef946a7`](https://github.com/http-party/node-http-proxy/commit/ef946a7697b38b13178881b3d1ebde63681dd4a1)
- added option for eventlistenerCount(max) [`8eb6780`](https://github.com/http-party/node-http-proxy/commit/8eb6780f8705caff13a5375446539b0621d497d7)
- [fix] support buffer [`1204a35`](https://github.com/http-party/node-http-proxy/commit/1204a35e467c6c1855ba0dac8f55d79f899148a6)
- DOC: updated readme with options [`1b5fb1d`](https://github.com/http-party/node-http-proxy/commit/1b5fb1d8fc21421b8383919d93e4149b586b211b)
- ENH: added 'headers' to available options, to add or overwrite existing headers [`7d840d3`](https://github.com/http-party/node-http-proxy/commit/7d840d35151be1aac612798754af47368594781d)
- [fix] move logo [`57abb7f`](https://github.com/http-party/node-http-proxy/commit/57abb7f26c14e281c3be07a8b84e3c79e066f59f)
- FIX: tests. still need to add more tests tho [`a350fad`](https://github.com/http-party/node-http-proxy/commit/a350fadea6bace293131581487f8c66948009449)
- [fix] move logo [`aaff196`](https://github.com/http-party/node-http-proxy/commit/aaff1966e4e2eb42c9890e57737f57a64e8d964a)
- [docs] add travis build status [`6b61878`](https://github.com/http-party/node-http-proxy/commit/6b618787598a2a37850898dbdb3b4fe8f3c3414d)
- [fix] do not send chunked responses to http1.0 clients [`8663ac1`](https://github.com/http-party/node-http-proxy/commit/8663ac1c43505f0081d906c3cd8e702d4b5ddeb0)
- [dist] Bump dependencies. [`a81dd8d`](https://github.com/http-party/node-http-proxy/commit/a81dd8d53e1595cba9acf5cc3ca9517165dcc4aa)
- [fix] readme [`4d3a4e1`](https://github.com/http-party/node-http-proxy/commit/4d3a4e1ee7370347898d1863ab73aa68ed345d8d)
- [fix] proxying to https [`26c4c43`](https://github.com/http-party/node-http-proxy/commit/26c4c43a06263ec6721bc0e8a90644297d0cf217)
- [fix] new logo [`ee3cc38`](https://github.com/http-party/node-http-proxy/commit/ee3cc380665a31ec6af28ddb73dfc543f430d3f8)
- [fix] naming convention [`7d71a86`](https://github.com/http-party/node-http-proxy/commit/7d71a867a8bdc375f7577cec3905cca89bbf415c)
- fix docs [`9243444`](https://github.com/http-party/node-http-proxy/commit/9243444ac006f73c00b0f1f78c4a77f342b0b4e4)
- [fix] short circuit [`a6256ca`](https://github.com/http-party/node-http-proxy/commit/a6256cac1df1739e3da78fe5f0cf122ef7ce6b14)
- [tests] this test is already in web-incoming tests [`920f1e7`](https://github.com/http-party/node-http-proxy/commit/920f1e7707aa1751577533cd368529f8a704d7af)
- Emit middlewareError when on middleware error. [`bc12ca3`](https://github.com/http-party/node-http-proxy/commit/bc12ca39394f9aeed3e3047f59035ba48afa2885)
- DOC: updated readme [`7ad5c0f`](https://github.com/http-party/node-http-proxy/commit/7ad5c0f993294c9e2e7650e15fbc62d11a2cb062)
- [docs] add logo [`8b05626`](https://github.com/http-party/node-http-proxy/commit/8b05626eed5e45e72cf9b1f14a4c4dca1dd2ed0f)
- [fix] making @stoke a happy camper [`34f16e7`](https://github.com/http-party/node-http-proxy/commit/34f16e74647095199f84ab61e10c8dafd60b505a)
- [feature] add buffer support [`e3f8d5f`](https://github.com/http-party/node-http-proxy/commit/e3f8d5fdbe1ebc4f04188d95bbef768d09718d2c)
- [Fix] 2 spelling mistakes [`5823842`](https://github.com/http-party/node-http-proxy/commit/58238421945bcc4236e280ebca7799b831ae29a4)
- [fix] do not call .end [`6e77cd3`](https://github.com/http-party/node-http-proxy/commit/6e77cd390929842088ae9f6deb922a6627ddfecd)
- attempting to fix link to valid options properties [`bbe2b27`](https://github.com/http-party/node-http-proxy/commit/bbe2b2788a7ee3c74fd44fe88b6dcf213264436f)
- [fix] slimmer proxying [`031aa0f`](https://github.com/http-party/node-http-proxy/commit/031aa0fbf30bd377696c4efa508f6fc769bf1070)
- [fix] use agent pool [`abf1d90`](https://github.com/http-party/node-http-proxy/commit/abf1d90fdf05a17ebe05a3e90d464a592e0aee69)
- [tests] fix test using undefined url [`c4d56a5`](https://github.com/http-party/node-http-proxy/commit/c4d56a5faf1e89cdeb911f0ece0efe065eb58c45)
- [fix] legacy [`162a42f`](https://github.com/http-party/node-http-proxy/commit/162a42f58f515c5418ccfac0b68f4c928103b1e1)
- [tests] fixing minor typos [`b333e63`](https://github.com/http-party/node-http-proxy/commit/b333e63648aa67ea1b1aaf17ba684e5fc6f751a6)
- Updated readme [`bd106d6`](https://github.com/http-party/node-http-proxy/commit/bd106d69f074a1c7018e685a4e144e23a17beb8c)
- [misc] use the local mocha instead the global [`f1aeb05`](https://github.com/http-party/node-http-proxy/commit/f1aeb0500cde39b63e570323e0e478530d1222ab)
- added unlimited listeners to the reverproxy event obj. [`1333c0c`](https://github.com/http-party/node-http-proxy/commit/1333c0cc62e7b590843f9b00326fe80137163c5e)
- [tests] throw error when no options, ALL TESTS PASSING! YAY [`86750c7`](https://github.com/http-party/node-http-proxy/commit/86750c7e594c419dfae957aaf7e44e61e1d480e8)
- ENH: updated example [`1c7ace2`](https://github.com/http-party/node-http-proxy/commit/1c7ace26c5a36fb63497f1ab67793c5b75495063)
- [merge] PR #470 [`38e6d7c`](https://github.com/http-party/node-http-proxy/commit/38e6d7cd5449a7264dcf5244b3dfd07b2dda60e1)
- [fix] remove stuff [`6a03e5f`](https://github.com/http-party/node-http-proxy/commit/6a03e5f7cf356416ea13584e279f5bfa3791c058)
- [test][misc] remove node@0.8 to test on travis [`8eff1a1`](https://github.com/http-party/node-http-proxy/commit/8eff1a1f26bb739dfc5a1ad90b140ff2a18921d5)
- merge with @cronopio [`0fb3381`](https://github.com/http-party/node-http-proxy/commit/0fb33810f5e70b714bd9868557d85a531b8e11e3)
- [merge] text [`98f29bd`](https://github.com/http-party/node-http-proxy/commit/98f29bdcfca9b818ffe107b09578539fdf379c8a)
- [fix] woops [`bd3df45`](https://github.com/http-party/node-http-proxy/commit/bd3df45010f282997cae3a699c7ecb885c01bdf8)
- [test] Test on newer version of node [`ebbba73`](https://github.com/http-party/node-http-proxy/commit/ebbba73eda49563ade09f38bdc8aef13d1cf6c00)
- new error propagation - follows [`1993faf`](https://github.com/http-party/node-http-proxy/commit/1993faf8a4227acda3423d46cf2cf13b4d9861e7)
- [fix] minor typo [`5a1504f`](https://github.com/http-party/node-http-proxy/commit/5a1504f0764b7747b53cc0d92a69ff3093e85ade)
- [fix] proxy to http(s) [`3c91ed3`](https://github.com/http-party/node-http-proxy/commit/3c91ed3d26d9af640d0c7a09fb9cdaf80ad673ca)
- Put the arguments the right way around in the README. [`1457980`](https://github.com/http-party/node-http-proxy/commit/145798062e332ac2aed7f8e8e3240e38464c870a)
- [fix] use some [`4480699`](https://github.com/http-party/node-http-proxy/commit/4480699d3a2a5080c051e7b8a100689fd1f58657)
- [fix] layout [`d7078e2`](https://github.com/http-party/node-http-proxy/commit/d7078e2fdd16d23d0b5f8f1d8a7ab3e9011fea4f)
- [docs] logo [`dd0f7b8`](https://github.com/http-party/node-http-proxy/commit/dd0f7b8876ae5b57fffab8857735b25b159f2bdb)
- [fix] url [`0637322`](https://github.com/http-party/node-http-proxy/commit/0637322d96e54bbcf5a14bf009dd73314cada4ce)
- [fix] opts [`adc5be0`](https://github.com/http-party/node-http-proxy/commit/adc5be020c7fff09a1c05ac771d5c5ab61002c23)
- [docs] fix syntax highlighting [`da9de70`](https://github.com/http-party/node-http-proxy/commit/da9de7034a452d1281217a349bc9403fddcc2b7f)
- [fix] typo [`275a519`](https://github.com/http-party/node-http-proxy/commit/275a5192fa257f78287a954b347e65023795487d)
- [tests] fix code coverage, changed pattern on blanket options [`4090250`](https://github.com/http-party/node-http-proxy/commit/40902506af3361b642b8798350b48404fe0a4e78)
- Put the arguments the right way around in emitter. [`7c8ecc8`](https://github.com/http-party/node-http-proxy/commit/7c8ecc8ea85b59fc16b55b9a142372b6ac168b2a)
- [fix] link [`72a89ea`](https://github.com/http-party/node-http-proxy/commit/72a89eab8bafef3742d78e8de8631094f961f427)
- [fix] space [`69f126b`](https://github.com/http-party/node-http-proxy/commit/69f126b34cbd190be8541a854d21f13bfb5a61bf)
- [fix] tests [`8269eca`](https://github.com/http-party/node-http-proxy/commit/8269eca2bb34d08336b8889e06e53d3522fa79fe)
- [fix] console [`18341d5`](https://github.com/http-party/node-http-proxy/commit/18341d559717e0a86f5ee4da024109e4b5a595a7)
- Set travis to run `npm test` while we fix coveralss.io integration [`e2a5d51`](https://github.com/http-party/node-http-proxy/commit/e2a5d513cac3ebceff446787fa106c7f00caf785)
- [fix] making @jcrugzz a happy camper [`2e7343d`](https://github.com/http-party/node-http-proxy/commit/2e7343d728a3187d48821b88ec2e2d4699bb2afe)
- [fix] minor typo [`5d66ce1`](https://github.com/http-party/node-http-proxy/commit/5d66ce11bb7eef7e704a2de2c0ef3b5f754843e9)
- [tests] tests fixed [`d60353f`](https://github.com/http-party/node-http-proxy/commit/d60353f80bbbcba128a2c51066e107365270e878)
- [tests] disabled the examples-test by now [`d83fdf6`](https://github.com/http-party/node-http-proxy/commit/d83fdf69a1121bfcfba72bbffcd3105ae5852c56)
- [fix] _ because it is unused [`590bb60`](https://github.com/http-party/node-http-proxy/commit/590bb604dae11223a0ae80469b59d6d341488f1f)
- [tests] disable test, by now is not throwing without options [`a2b1f0a`](https://github.com/http-party/node-http-proxy/commit/a2b1f0a4c9079342db6255c5f92db4a0cb992707)
- [fix] support target and forward [`961d2f9`](https://github.com/http-party/node-http-proxy/commit/961d2f9400b4cfd236c3c8ccbf401d37f8e871b8)
- [dist] Version bump. 0.10.4 [`840f6d8`](https://github.com/http-party/node-http-proxy/commit/840f6d8d29dffc11d3726123c2d400940ca2bdda)
- [fix] remove old reminescence [`4d65280`](https://github.com/http-party/node-http-proxy/commit/4d65280ea313438a94589bacf55f7a09cc107888)
- [feature] add emit proxyRes [`dda6f7a`](https://github.com/http-party/node-http-proxy/commit/dda6f7a45a46d2bf63e482d0b47b7c36ae548546)
- [docs] test badge [`1ceea3e`](https://github.com/http-party/node-http-proxy/commit/1ceea3e5f9b6232d60d673946bbccb7d8ccb4beb)
- [tests] remove caronte and use http-proxy for file names [`c9f5772`](https://github.com/http-party/node-http-proxy/commit/c9f5772fc18226aca31471bc96c44a6dbff5cbea)
- [logo] [`4c2f2f3`](https://github.com/http-party/node-http-proxy/commit/4c2f2f3b9a5ba65f97403e778a670f14301d52c1)

## [v0.10.3](https://github.com/http-party/node-http-proxy/compare/v0.10.2...v0.10.3) - 2013-06-20

### Merged

- Pass default certs to SNICallback example [`#419`](https://github.com/http-party/node-http-proxy/pull/419)

### Fixed

- Pass default certs to SNICallback example [`#399`](https://github.com/http-party/node-http-proxy/issues/399)

### Commits

- [dist] Bump version to 0.10.3 [`2fd748f`](https://github.com/http-party/node-http-proxy/commit/2fd748fb61dac7de0daa50aabbface7033c6a222)
- [fix] Respect `maxSockets` from `target` options in `RoutingProxy` [`e1d384e`](https://github.com/http-party/node-http-proxy/commit/e1d384e769e9f4adc5a06c516cfb721ff24b4b6d)
- Send path in req.path and not the url [`0c75323`](https://github.com/http-party/node-http-proxy/commit/0c753234c0c85333f909bdbef034ffb6e192bad5)

## [v0.10.2](https://github.com/http-party/node-http-proxy/compare/v0.10.1...v0.10.2) - 2013-04-21

### Merged

- Correct keep-alive responses to HTTP 1.0 clients [`#407`](https://github.com/http-party/node-http-proxy/pull/407)

### Fixed

- [minor] Style compliance. Fixes #402. [`#402`](https://github.com/http-party/node-http-proxy/issues/402)

### Commits

- Correct keep-alive responses to HTTP 1.0 clients. [`a29b5e8`](https://github.com/http-party/node-http-proxy/commit/a29b5e8e289c34c00d2b450e5fb9dd1969db4b97)
- [minor] Strip trailing whitespace. [`7fc39d7`](https://github.com/http-party/node-http-proxy/commit/7fc39d77f47311b82c24ab05f8e1a45a2733305c)
- Add headers on 'handshake' [`985025c`](https://github.com/http-party/node-http-proxy/commit/985025c90f3b2fafede64d8b17c318326f2423d9)
- Don't test raw HTTP 1.0 requests over HTTPS. [`daf53bd`](https://github.com/http-party/node-http-proxy/commit/daf53bd753879223dc84a49c92d0efaf576c1fd3)
- [dist] Version bump. 0.10.2 [`de0928f`](https://github.com/http-party/node-http-proxy/commit/de0928f616dd62165e8a22c00d091cabf31e1e87)

## [v0.10.1](https://github.com/http-party/node-http-proxy/compare/v0.10.0...v0.10.1) - 2013-04-12

### Merged

- Fix for slab buffer retention, leading to large memory consumption [`#370`](https://github.com/http-party/node-http-proxy/pull/370)

### Commits

- [dist] Version bump. 0.10.1 [`9c13ad4`](https://github.com/http-party/node-http-proxy/commit/9c13ad46e416125373d6604f3954ec3df1f55449)

## [v0.10.0](https://github.com/http-party/node-http-proxy/compare/v0.9.1...v0.10.0) - 2013-03-18

### Merged

- Change the emitter of the `proxyResponse` event [`#385`](https://github.com/http-party/node-http-proxy/pull/385)
- Fixing a bug that generates an unexpected TypeError [`#383`](https://github.com/http-party/node-http-proxy/pull/383)
- Mention Harmon used for response modifications in the readme [`#384`](https://github.com/http-party/node-http-proxy/pull/384)

### Commits

- [dist] Update CHANGELOG.md [`8665f3c`](https://github.com/http-party/node-http-proxy/commit/8665f3cc600feecbb4c8229699823149c69a144f)
- Harmon messsage [`35ba0db`](https://github.com/http-party/node-http-proxy/commit/35ba0db554c6bace21b1bacfa8f5fb6df4228db0)
- [fix breaking] Emit the `proxyResponse` event on the HttpProxy instance to reduce listener churn and reference counts. [`2620f06`](https://github.com/http-party/node-http-proxy/commit/2620f06e2db9a267945566f10837c4c2a5df753d)
- [dist] Version bump. 0.10.0 [`71183bf`](https://github.com/http-party/node-http-proxy/commit/71183bf30bc2b9ad2eaf57c51980eeb0bc7edff0)
- Fixing the if statement as it lead to 'TypeError: Parameter 'url' must be a string, not undefined' in certain cases [`c9b6895`](https://github.com/http-party/node-http-proxy/commit/c9b6895c5e14add6aba4f826a2173458a1896a5f)
- Harmon messsage [`4e42354`](https://github.com/http-party/node-http-proxy/commit/4e42354e77d5731a383d516fc0b249d5d0eda745)

## [v0.9.1](https://github.com/http-party/node-http-proxy/compare/v0.9.0...v0.9.1) - 2013-03-09

### Commits

- [dist doc] Updated CHANGELOG.md for `v0.9.1` [`ea5e214`](https://github.com/http-party/node-http-proxy/commit/ea5e214522d8ac34d1129b28ff188c0f232ce63f)
- [dist] Version bump. 0.9.1 [`701dc69`](https://github.com/http-party/node-http-proxy/commit/701dc698e3eb39ca6836a02611d8dce750f4e212)
- [breaking] Ensure that `webSocketProxyError` also receives the error to be consistent with `proxyError` events. [`c78356e`](https://github.com/http-party/node-http-proxy/commit/c78356e9cf27a21c57e4c98ef7dd3c22abe864c2)

## [v0.9.0](https://github.com/http-party/node-http-proxy/compare/v0.8.7...v0.9.0) - 2013-03-09

### Merged

- If HTTP 1.1 is used and backend doesn't return 'Connection' header, expicitly  return Connection: keep-alive. [`#298`](https://github.com/http-party/node-http-proxy/pull/298)
- add "with custom server logic" to the "Proxying WebSockets" section of the readme [`#332`](https://github.com/http-party/node-http-proxy/pull/332)
- routing proxy 'this' reference bug? [`#365`](https://github.com/http-party/node-http-proxy/pull/365)
- fixed issue #364 'proxyError' event emitted twice [`#374`](https://github.com/http-party/node-http-proxy/pull/374)
- Misleading documentation for Websockets via .createServer [`#349`](https://github.com/http-party/node-http-proxy/pull/349)

### Fixed

- [api test] Manually merge #195 from @tglines since that fork was deleted. Update tests to use new macros. Fixes #195. Fixes #60. [`#195`](https://github.com/http-party/node-http-proxy/issues/195) [`#60`](https://github.com/http-party/node-http-proxy/issues/60)
- [fix] Set "content-length" header to "0" if it is not already set on DELETE requests. Fixes #338. [`#338`](https://github.com/http-party/node-http-proxy/issues/338)
- [fix] Do not use "Transfer-Encoding: chunked" header for proxied DELETE requests with no "Content-Length" header. Fixes #373. [`#373`](https://github.com/http-party/node-http-proxy/issues/373)
- [fix] http-proxy should not modify the protocol in redirect request for external sites. Fixes #359. [`#359`](https://github.com/http-party/node-http-proxy/issues/359)
- [fix] Emit `notFound` event when ProxyTable location does not exist. Fixes #355. Fixes #333. [`#355`](https://github.com/http-party/node-http-proxy/issues/355) [`#333`](https://github.com/http-party/node-http-proxy/issues/333)
- [fix] Make options immutable in `RoutingProxy`. Fixes #248. [`#248`](https://github.com/http-party/node-http-proxy/issues/248)
- [fix] Remove special case handling of `304` responses since it was fixed in 182dcd3. Fixes #322. [`#322`](https://github.com/http-party/node-http-proxy/issues/322)
- [fix] Ensure `response.headers.location` is defined. Fixes #276. [`#276`](https://github.com/http-party/node-http-proxy/issues/276)

### Commits

- [minor] s/function(/function (/ s/){/) {/ [`9cecd97`](https://github.com/http-party/node-http-proxy/commit/9cecd97153ccce4f81c5eda35a49079e651fb27a)
- working on x-forwarded-for [`1332409`](https://github.com/http-party/node-http-proxy/commit/133240937dc63aca0007388327837bc24808f79a)
- Routing Proxy was not sending x-forward-*. Fixing It... [`916d44e`](https://github.com/http-party/node-http-proxy/commit/916d44e3d2a17bb9d5178f347ddad9796b988e05)
- Added timeout option and test to test new timeout parameter, added requestFail assertion. [`89d43c2`](https://github.com/http-party/node-http-proxy/commit/89d43c20dd0dec1dda1fd70e57f3f250b9e3b431)
- Add tests for headers bug fixes [`ecb5472`](https://github.com/http-party/node-http-proxy/commit/ecb547223f3f1d9bf551842c2026ee2f1a18638a)
- Added simple round robin example with websocket support [`83fbd42`](https://github.com/http-party/node-http-proxy/commit/83fbd4250660f41de1ab2b5490a3bf58200ae148)
- - support unix donain sockets and windows named pipes (socketPath) on node 0.8.x. On node 0.6.x the support was opaque via port, but on the new node, socketPath should be set explicitely. [`ffe74ed`](https://github.com/http-party/node-http-proxy/commit/ffe74ed299f81206b898147dbcc985519b2921f8)
- pathnameOnly flag added.  Ignores hostname and applies routing table to the paths being requested. [`46b078a`](https://github.com/http-party/node-http-proxy/commit/46b078a98d10de7726a3bbca89121acc57ad7625)
- [doc] added comments to pathnameOnly block. [`5e6be6c`](https://github.com/http-party/node-http-proxy/commit/5e6be6ccf5a39ff450e57d7b24e374a83569fa85)
- remove offending code, final fix for issue #364 [`3b84e27`](https://github.com/http-party/node-http-proxy/commit/3b84e27ab4efd5ce3b8ac837d699d4ff6661c7e7)
- memory leak fix in closing of the scokets [`2055d0c`](https://github.com/http-party/node-http-proxy/commit/2055d0c8ec16699ffb06adf6d64d9506920b2071)
- Fix truncated chunked responses [`ef66833`](https://github.com/http-party/node-http-proxy/commit/ef66833c4d7f07ae9f42026f2bcc0fbca2440579)
- Re-added previous description [`603106a`](https://github.com/http-party/node-http-proxy/commit/603106a13d28c0199fa4456cc9aee1692eb2588c)
- pathnameOnly option documented in the Readme.md [`a1607c1`](https://github.com/http-party/node-http-proxy/commit/a1607c1684a7d7617e5148a0dca882eb08a9f03b)
- [fix minor] Prevent crashes from attempting to remove listeners more than once when proxying websocket requests. [`a681493`](https://github.com/http-party/node-http-proxy/commit/a681493371ae63f026e869bf58b6fea682dc5de3)
- Added comments [`64efa7f`](https://github.com/http-party/node-http-proxy/commit/64efa7f9291a2377a32e942a247700b71b107993)
- Revert "[fix minor] Prevent crashes from attempting to remove listeners more than once when proxying websocket requests." [`c6da760`](https://github.com/http-party/node-http-proxy/commit/c6da760ca9f375025229fe3fc174aca943362f38)
- [doc dist] Update CHANGELOG.md for `v0.9.0`. [`133115c`](https://github.com/http-party/node-http-proxy/commit/133115c9760130dcef447efbd18c470c08795c90)
- add support for loading CA bundles [`10f6b05`](https://github.com/http-party/node-http-proxy/commit/10f6b0577518bdfcb6b43c1f516dc988bdcade53)
- problem: don't want to run my server as root to bind to privileged ports (e.g. 80, 443). [`2c36507`](https://github.com/http-party/node-http-proxy/commit/2c3650746cd90fed63b140a8d393e18bd35cd8f9)
- Add 'proxyResponse' event so observer can modify response headers or abort response. [`3b86a7a`](https://github.com/http-party/node-http-proxy/commit/3b86a7aae3fc366c5fa8645285a4368dbac7a0dc)
- [minor] Move private helper to end of file. [`476cbe7`](https://github.com/http-party/node-http-proxy/commit/476cbe741fc41b7f1eb269d841d922784e8b3c6b)
- Fix for retaining large slab buffers in node core [`d2888c8`](https://github.com/http-party/node-http-proxy/commit/d2888c83f5eab3fb82425ef4fd51e62621bf2764)
- [dist] Update `devDependencies` [`ad21310`](https://github.com/http-party/node-http-proxy/commit/ad213106d06cfc79004841f04b8e73fe7d7ef67a)
- [minor] Small whitespace compliance. [`ea0587a`](https://github.com/http-party/node-http-proxy/commit/ea0587a8f98b1eedc38c66b69293ae091e24be6e)
- [doc fix] Add undefined var in example. [`deca756`](https://github.com/http-party/node-http-proxy/commit/deca7565c51fd678354d26eaae7fe2481e36e2c3)
- working on x-forwarded-for [`31fc94a`](https://github.com/http-party/node-http-proxy/commit/31fc94aa5e43c54033d5384caaf104eebf3889bd)
- Allow event observers to access upstream response headers and data. [`4c130f5`](https://github.com/http-party/node-http-proxy/commit/4c130f5dac5f2cfbfc2618446b86244aff4cb04f)
- [fix doc] Fix bad variable reference in `README.md`. [`440013c`](https://github.com/http-party/node-http-proxy/commit/440013c263a96c6681bfe92a8f56db93b58efa8d)
- Change wording for handling websocket proxy events [`ee6bbe0`](https://github.com/http-party/node-http-proxy/commit/ee6bbe00244c90bd532b11ff1c796aea8c7372f8)
- [dist] Version bump. 0.9.0 [`c68e038`](https://github.com/http-party/node-http-proxy/commit/c68e0389120d8530e578e20496d8ee091e69a580)
- fix 'this' reference in routing proxy listener bindings [`15afc23`](https://github.com/http-party/node-http-proxy/commit/15afc23a275f3fa16653fff6179368122661a0af)
- cleanning [`8d87399`](https://github.com/http-party/node-http-proxy/commit/8d8739999fcaf4cdd8f2471046f6f036c44dc8f7)
- cleanning [`9672b99`](https://github.com/http-party/node-http-proxy/commit/9672b9927156a0dfe3ce4539f380aaf3172f6267)
- Fix typo which slipped in during patch clean-up [`ba65a48`](https://github.com/http-party/node-http-proxy/commit/ba65a485fcf7230e85cee77f6eefcd17e46c8f86)
- Remove data event that is not needed after-all. [`b1c4bd6`](https://github.com/http-party/node-http-proxy/commit/b1c4bd61e8ae5705d4cc97bf719c381554671967)

## [v0.8.7](https://github.com/http-party/node-http-proxy/compare/v0.8.6...v0.8.7) - 2012-12-22

### Commits

- [fix] Handle errors on request object [`edfe869`](https://github.com/http-party/node-http-proxy/commit/edfe86915941e465a06c1d0a3330ee32e5834aa6)
- [dist] Bump version to 0.8.7 [`26d3646`](https://github.com/http-party/node-http-proxy/commit/26d3646ff252129f35525ab0540a31f5617a31d2)
- [fix] Don't remove `error` listener after response ends [`223eacd`](https://github.com/http-party/node-http-proxy/commit/223eacda85a4267f2860f6c46f7dedfa9db8c224)

## [v0.8.6](https://github.com/http-party/node-http-proxy/compare/v0.8.5...v0.8.6) - 2012-12-21

### Merged

- http-proxy: 304 responses should emit 'end' too [`#337`](https://github.com/http-party/node-http-proxy/pull/337)

### Commits

- [bench] Remove silly "benchmarks" [`2bd9cd9`](https://github.com/http-party/node-http-proxy/commit/2bd9cd9adb6cea6763930468d22cb56fffab6218)
- [bench] Add a benchmark for websockets throughput [`6797a27`](https://github.com/http-party/node-http-proxy/commit/6797a2705a309d19a655ab468bcc80ba2e43cf41)
- [fix] Handle socket errors [`2a61ec8`](https://github.com/http-party/node-http-proxy/commit/2a61ec85bdaeed9a5fca2a117efb36a7f76becc4)
- [dist] Update `devDependencies` [`b81d9b7`](https://github.com/http-party/node-http-proxy/commit/b81d9b71daa32a571384cff29d81227993299236)
- [dist] Bump version to 0.8.6 [`6cd78f6`](https://github.com/http-party/node-http-proxy/commit/6cd78f6af9ca08b8797c409896eea2ae6bb6d835)
- [bench] More exact size display [`7bc1a62`](https://github.com/http-party/node-http-proxy/commit/7bc1a628feab78f8931e9e6481737dd871debfeb)

## [v0.8.5](https://github.com/http-party/node-http-proxy/compare/v0.8.4...v0.8.5) - 2012-11-16

### Merged

- lib: allow overriding maxSockets [`#323`](https://github.com/http-party/node-http-proxy/pull/323)

### Fixed

- [fix] Convert strings to numbers if possible in `.createServer` [`#321`](https://github.com/http-party/node-http-proxy/issues/321)

### Commits

- [test] Delete invalid core test [`886a395`](https://github.com/http-party/node-http-proxy/commit/886a395429f20163992ca76e7b0d059256f56ba6)
- [test] Upgrade `common.js` from node core [`fefbf04`](https://github.com/http-party/node-http-proxy/commit/fefbf04ac03126858bdad07df7b10131a46e17d6)
- add "with custom server logic" to the "Proxying WebSockets" section of the readme.md [`03dbe11`](https://github.com/http-party/node-http-proxy/commit/03dbe115c2b088737e5b9abcadf91a8298f56f1f)
- [test] Kill child process when exiting test runner [`74ec175`](https://github.com/http-party/node-http-proxy/commit/74ec1757153c503ce57eb552031648fe79731d48)
- [fix] Correctly kill test processes [`b8c27ed`](https://github.com/http-party/node-http-proxy/commit/b8c27ed565e416827b7c4bb123aa9ee119d008e6)
- [test] Make global detection work with older node versions [`3531fd6`](https://github.com/http-party/node-http-proxy/commit/3531fd609a8ce156d27c27ca38ac912a73aebfeb)
- [dist] Bump version to 0.8.5 [`22639b3`](https://github.com/http-party/node-http-proxy/commit/22639b378189ec78f9962dde64337df050e29a6f)
- [test] Run core tests on `npm test` [`41c9a9c`](https://github.com/http-party/node-http-proxy/commit/41c9a9caad679221b8f1d4dcfb74f9b2bdb8270b)
- [test] Stop testing on `node v0.9`, tests timeout [`9042665`](https://github.com/http-party/node-http-proxy/commit/9042665ea98a6587e1d6800e51d3c354c0a1b20a)

## [v0.8.4](https://github.com/http-party/node-http-proxy/compare/v0.8.2...v0.8.4) - 2012-10-23

### Merged

- Events patch [`#320`](https://github.com/http-party/node-http-proxy/pull/320)
-  documentation for options [`#315`](https://github.com/http-party/node-http-proxy/pull/315)
- Added travis build status [`#308`](https://github.com/http-party/node-http-proxy/pull/308)
- Fix installation instructions: s/http/https/ [`#302`](https://github.com/http-party/node-http-proxy/pull/302)
- If supplied pass changeOrigin option through to HttpProxy instance if set in RoutingProxy [`#285`](https://github.com/http-party/node-http-proxy/pull/285)

### Commits

- [fix test] Fix examples to use newest version of socket.io and helpers. Added tests for ensuring that examples require as expected with no errors. [`fd648a5`](https://github.com/http-party/node-http-proxy/commit/fd648a529090cefc202613fff3fdfec9ba0e6a72)
- [fix] spdy should look like https when forwarding (until we get a client) [`698b01d`](https://github.com/http-party/node-http-proxy/commit/698b01da8e1fe6195b00e5006032d262a0a86f4e)
- [docs] options [`4c8e1d9`](https://github.com/http-party/node-http-proxy/commit/4c8e1d96a36523a548959415903bc669ebcc138d)
- http-proxy: emit websocket:start [`5df6e7b`](https://github.com/http-party/node-http-proxy/commit/5df6e7bdb8d4685a18e94ff1bf117ce8eff8d1c9)
- [fix] `destroy()` websockets in case of an error [`0d00b06`](https://github.com/http-party/node-http-proxy/commit/0d00b06af307dc5c70c36e89617a08486eb665e2)
- [fix] Suppress EADDRINUSE errors from `test/examples-test.js` since we are just looking for require-time errors. Isolate tests to ensure idempotency of ports [`c4a7b15`](https://github.com/http-party/node-http-proxy/commit/c4a7b1584302fe12a8fc06b6774db5ff602c3607)
- [docs] more options [`d4cb9da`](https://github.com/http-party/node-http-proxy/commit/d4cb9dad6ce36a823c9e8970e0bb3266d844e536)
- If HTTP 1.1 is used and backend doesn't return 'Connection' header, explicitly [`850171c`](https://github.com/http-party/node-http-proxy/commit/850171cdc41cb93343f7c31f650ac908a8d2dacb)
- [refactor] Pass all options to `Agent` constructor [`eafdc74`](https://github.com/http-party/node-http-proxy/commit/eafdc744b67b33b5ed3cfc80de84dafcd850bdd0)
- Fix socket leaks when FIN packet isn't responded to [`24b8406`](https://github.com/http-party/node-http-proxy/commit/24b84068eac1c704d9f8df3dc833b976850c328f)
- [fix] Partial fix for rejecting self-signed certs in tests [`2e7d8a8`](https://github.com/http-party/node-http-proxy/commit/2e7d8a88f4b470dcc9da1639fe2a69e03251036c)
- [fix] Dont use `-i` when running vows because it supresses `--target=` and `--proxy=` CLI arguments [`1783ab0`](https://github.com/http-party/node-http-proxy/commit/1783ab0625743355eecc11f5cfd57469c429daa0)
- [test] Add `node v0.9` testing, test all branches [`4f6387c`](https://github.com/http-party/node-http-proxy/commit/4f6387c17f55c23da4aac161cf2e5a4dd2a25c40)
- [minor] Remove `setEncoding` on incoming socket [`812868d`](https://github.com/http-party/node-http-proxy/commit/812868ddfc720b6c4fd26603c2fe4d5ae68f2492)
- [dist] v0.8.3 [`a89a5b8`](https://github.com/http-party/node-http-proxy/commit/a89a5b80889a56dd31634096bc6546b6b7b26da2)
- [fix] Ignore npm version errors when installing dependencies for examples [`a454666`](https://github.com/http-party/node-http-proxy/commit/a454666e7a0465ed65b7bbd29cf1b0c6c126d153)
- [fix] function [`213e03c`](https://github.com/http-party/node-http-proxy/commit/213e03c99844c5c984fbf857bae32095165a1e8f)
- [dist] Bump version to 0.8.4 [`4d7e8a8`](https://github.com/http-party/node-http-proxy/commit/4d7e8a808d83d3db1b729820aba5f481ab3d18f4)
- [minor doc] Correct comment [`cee27fe`](https://github.com/http-party/node-http-proxy/commit/cee27feeddf9b4db06917dfa9e59e6bcd7e14c27)

## [v0.8.2](https://github.com/http-party/node-http-proxy/compare/v0.8.1...v0.8.2) - 2012-07-22

### Merged

- Add example for gzip middleware using a proxy table. [`#221`](https://github.com/http-party/node-http-proxy/pull/221)
- Implement RoutingProxy.prototype.remove [`#246`](https://github.com/http-party/node-http-proxy/pull/246)
- prefer `target.hostname` over `target.host` [`#235`](https://github.com/http-party/node-http-proxy/pull/235)
- add "Using two certificiates" to the https section of the readme.md [`#275`](https://github.com/http-party/node-http-proxy/pull/275)
- Add support for setting the host in the executable [`#268`](https://github.com/http-party/node-http-proxy/pull/268)
- Hi! I fixed some calls to "sys" for you! [`#270`](https://github.com/http-party/node-http-proxy/pull/270)
- Fix bug: x-forwarded-proto set incorrectly as httphttps or wswss [`#266`](https://github.com/http-party/node-http-proxy/pull/266)

### Commits

- [refactor] Rewrite tests to use saner vows idioms. Update tests to use latest socket.io [`4ae7a5b`](https://github.com/http-party/node-http-proxy/commit/4ae7a5b84011bb5b9ec3a36ded4c5e5b3330db80)
- [dist] Remove out-dated docco docs [`2d75510`](https://github.com/http-party/node-http-proxy/commit/2d75510d827c770c30a7292c31ef0f2007da7086)
- [refactor test] Finish removing old test code. [`e2dc7f9`](https://github.com/http-party/node-http-proxy/commit/e2dc7f96937e5d565fea16c9f56b9f5d3e427de2)
- [dist] Complete JSHint compliance except for `too many var statements` [`36226da`](https://github.com/http-party/node-http-proxy/commit/36226daa2e4cbc65fae80d2d09fd64c0e7ce36ba)
- [refactor test] Add support for `http*-to-http*` testing from CLI arguments [`828dbeb`](https://github.com/http-party/node-http-proxy/commit/828dbebcaaf11e338a7727bf9d2fff8bfbd3726e)
- [fix api] Optimize lookups in the ProxyTable. Ensure that RoutingProxy can proxy to `https` by default. [`55286a7`](https://github.com/http-party/node-http-proxy/commit/55286a7c499c0fe267f75d8e8441ff89f1e65f99)
- Whitespace fixes. [`04ce49c`](https://github.com/http-party/node-http-proxy/commit/04ce49c5b289acb6ad72303e9ac70c637ea490b2)
- [refactor tests] Finished refactoring tests to support `ws*-to-ws*` tests based on CLI arguments [`7e854d7`](https://github.com/http-party/node-http-proxy/commit/7e854d778b89201f7cb933e8bbda66316b98b0b4)
- [doc] Minor formatting updates to README.md [`6753951`](https://github.com/http-party/node-http-proxy/commit/67539519faf1f32073fdb562404bd897072e24ee)
- [fix] Changed require('util') to require('util') for compatibility with node v0.8 [`bf7e328`](https://github.com/http-party/node-http-proxy/commit/bf7e328fb837de69455c42f41822b0caae2777b6)
- [test] Add .travis.yml file for Travis CI. [`29e6e74`](https://github.com/http-party/node-http-proxy/commit/29e6e748f780629d05635eebb421e8ee1d125058)
- Use changeOrigin for proxyRequest. [`0273958`](https://github.com/http-party/node-http-proxy/commit/0273958b0a5c7823c6212cb6ce6e4f801a215d3b)
- adding support for setting the host [`06e78f2`](https://github.com/http-party/node-http-proxy/commit/06e78f27475165d023fd66afbe5dd626a6a548af)
- match style requested by @cronopio [`415d4ed`](https://github.com/http-party/node-http-proxy/commit/415d4ed908e45332421d683eb45e0d6873b85ae7)
- Fix bug: x-forwarded-proto set incorrectly [`0933f1c`](https://github.com/http-party/node-http-proxy/commit/0933f1c598c1b62a75e040c3ed3ccb262612d3c9)
- [dist] Version bump. 0.8.2 [`13c34d0`](https://github.com/http-party/node-http-proxy/commit/13c34d09b2f8be14fbbe4be77c49b23066667f1b)

## [v0.8.1](https://github.com/http-party/node-http-proxy/compare/v0.8.0...v0.8.1) - 2012-06-05

### Merged

- [misc] Updating the changelog. Close #137 [`#256`](https://github.com/http-party/node-http-proxy/pull/256)
- Fix problem with req.url not being not properly replaced. [`#218`](https://github.com/http-party/node-http-proxy/pull/218)
- Re-emit 'start', 'forward' and 'end' events in RoutingProxy, and fix some hanging issues. [`#216`](https://github.com/http-party/node-http-proxy/pull/216)
- Fixes to make the websockets example work. [`#225`](https://github.com/http-party/node-http-proxy/pull/225)
- [minor] Syntax error [`#222`](https://github.com/http-party/node-http-proxy/pull/222)
- [docs] Making README links consistent with latest project structure. [`#208`](https://github.com/http-party/node-http-proxy/pull/208)
- [docs] improved grammar [`#205`](https://github.com/http-party/node-http-proxy/pull/205)
- proposed doc addition for #180 [`#189`](https://github.com/http-party/node-http-proxy/pull/189)

### Fixed

- Merge pull request #256 from nodejitsu/changelog [`#137`](https://github.com/http-party/node-http-proxy/issues/137)
- [misc] Updating the changelog. Close #137 [`#137`](https://github.com/http-party/node-http-proxy/issues/137)

### Commits

- Whitespace fixes [`e9fd3f4`](https://github.com/http-party/node-http-proxy/commit/e9fd3f43d7e890f0164b5a03a34f196dd162d043)
- Added example for gzip middleware using a ProxyTable. [`6201328`](https://github.com/http-party/node-http-proxy/commit/62013281b8a980c53a38362f10d746bfbf36c52e)
- [examples] Added simple load balancer example [`fd7fcd8`](https://github.com/http-party/node-http-proxy/commit/fd7fcd8decbf0c7ab00cab84e151991e380b8fae)
- [dist] Update author field for consistency [`27316e2`](https://github.com/http-party/node-http-proxy/commit/27316e22e8e7786252583cdb9131cfd8cacb07c1)
- Add documentation for listening for proxy events to prevent a common mistake. [`4f2bc58`](https://github.com/http-party/node-http-proxy/commit/4f2bc58431c7f44d486ee8c1ee3136b3637f9405)
- Fix RoutingProxy hanging when there is an error [`b26b434`](https://github.com/http-party/node-http-proxy/commit/b26b434e9fc501f7e0c4a966dbee6220c355bc7c)
- prefer `target.hostname` over `target.host` [`c4d185d`](https://github.com/http-party/node-http-proxy/commit/c4d185dca9696c77d5c38d24d897c2679f6762a0)
- [doc] Fix style in websockets example [`ed06af9`](https://github.com/http-party/node-http-proxy/commit/ed06af97efe406ea2533009be64a6b568f9d0601)
- Add tests for remapping URL properly. [`5d839dd`](https://github.com/http-party/node-http-proxy/commit/5d839dd5f8890c6d2af96807b96d1bd5bb0f7276)
- fixed comment typos in examples/http/proxy-https-to-http.js and proxy-https-to-https.js, lines 37 and 46 [`868f7e7`](https://github.com/http-party/node-http-proxy/commit/868f7e7a287c4709c541c077f3e2303f45b1f072)
- [misc] changelog updated to version 0.8.1 [`e9a3a30`](https://github.com/http-party/node-http-proxy/commit/e9a3a3012c5507dff46afd3e5cececf43b1717ae)
- Implement RoutingProxy.prototype.remove [`0532995`](https://github.com/http-party/node-http-proxy/commit/0532995dfa0be53d285c886a9922b8915f297d36)
- Making README links consistent with latest project structure. [`7fa6599`](https://github.com/http-party/node-http-proxy/commit/7fa6599f4f2c92bb29bc5fc8a9ba06d704652c5e)
- Address ticket #180 here since that problem is so hard to discover when you run into it. If there was an error, people would search for the error text, but there isn't. [`73e415a`](https://github.com/http-party/node-http-proxy/commit/73e415a22634bfc9e5993377902f67ac3212714a)
- [tests] used socket.io 0.6.17 fixed version for tests [`45d67f4`](https://github.com/http-party/node-http-proxy/commit/45d67f42cba373db4f47765d6a3dd38a7d19dae6)
- [fix] x-forwarded-proto sets properly [`ca37ad7`](https://github.com/http-party/node-http-proxy/commit/ca37ad74367764cca479a1af63bd7491dc79606b)
- [doc] add missing {} to make an object [`843901e`](https://github.com/http-party/node-http-proxy/commit/843901eeeb24611ad24889f13edcbfd5dee4314d)
- fix the broken english and clarified the sentence (I hope) [`e15db4f`](https://github.com/http-party/node-http-proxy/commit/e15db4fb50db3e2191f3ebd30e12eeed9c376bc2)
- Re-emit 'start', 'forward' and 'end' events in RoutingProxy. [`99ee542`](https://github.com/http-party/node-http-proxy/commit/99ee54259eae70c0c680ee82efc7dd184313f182)
- [doc] call listen() to get the server started [`4fc1ee8`](https://github.com/http-party/node-http-proxy/commit/4fc1ee85d35d9feb468f808ddd11aaf186eaedd4)
- syntax error fixed [`5842d0e`](https://github.com/http-party/node-http-proxy/commit/5842d0ee7de875378d9b8ae240748dd2af567be9)
- [dist] Version bump 0.8.1 [`81f6095`](https://github.com/http-party/node-http-proxy/commit/81f6095cf08f84a84ae2bbda7ca0315729638fe0)
- finally removed hidden char [`4358a4c`](https://github.com/http-party/node-http-proxy/commit/4358a4c1225acf8c13536fd742b845166f3a65a6)
- [minor fix] delete white space [`df650d1`](https://github.com/http-party/node-http-proxy/commit/df650d11dd0a47653a4905f871d8d3d6c327d600)

## [v0.8.0](https://github.com/http-party/node-http-proxy/compare/v0.7.3...v0.8.0) - 2011-12-23

### Merged

- Fix issue where front-end is HTTPS, back-end is HTTP, and server issues a redirect. [`#165`](https://github.com/http-party/node-http-proxy/pull/165)
- Modified the ad-hoc proxy lookup to use _getKey(), rather than the error-prone in-line method. [`#164`](https://github.com/http-party/node-http-proxy/pull/164)
- Allows node-http-proxy to append new values to existing headers for incoming "x-forward-for","x-forward-proto" and "x-forward-port" [`#163`](https://github.com/http-party/node-http-proxy/pull/163)
- [fix] only set one drain listener while paused [`#136`](https://github.com/http-party/node-http-proxy/pull/136)
- [docs] grammar correction [`#134`](https://github.com/http-party/node-http-proxy/pull/134)

### Fixed

- [fix] Avoid `Transfer-Encoding: chunked` for HTTP/1.0 client, closes #59. [`#59`](https://github.com/http-party/node-http-proxy/issues/59)

### Commits

- [refactor minor] Update vendor/websocket.js to be compatible with node@0.6.x [`ea7fea6`](https://github.com/http-party/node-http-proxy/commit/ea7fea627255ed34d39902438b55e740c7c9b08c)
- [test] Add common.js file from core [`543f214`](https://github.com/http-party/node-http-proxy/commit/543f214361605cffdbee7b233029edf343c358c1)
- [test] Add core `test-http-proxy` test [`feb324b`](https://github.com/http-party/node-http-proxy/commit/feb324b0d4c0a2307493b35be944ed08ffc9187a)
- [test] Add core `test-http` test [`25a9e2d`](https://github.com/http-party/node-http-proxy/commit/25a9e2d217cabef07d6f161f5d6ded49342dbb2f)
- [test] Add core `test-http-host-headers` test [`f298411`](https://github.com/http-party/node-http-proxy/commit/f298411f76a106791f34dd4d31ea033a7bdca9c7)
- [test] Add core `test-http-extra-response` test [`c26ab5e`](https://github.com/http-party/node-http-proxy/commit/c26ab5e46ff2649f0ea6585f20d8f58b7d0cadef)
- [test] Add core `test-http-set-cookies` test [`b3b5cce`](https://github.com/http-party/node-http-proxy/commit/b3b5cce3aee98a7fd5b50fb8e1bd6bd5e1c7512f)
- [test] Add core `test-http-client-abort` test [`7bf8d4a`](https://github.com/http-party/node-http-proxy/commit/7bf8d4a7be668591b350144b4546559abf9a0b5f)
- [test] Add core `test-http-client-upload` test [`7648fe5`](https://github.com/http-party/node-http-proxy/commit/7648fe50c1859597dc390e9e628db938372483e7)
- [test] Add core `test-http-client-upload-buf` test [`5ac9878`](https://github.com/http-party/node-http-proxy/commit/5ac987857c934d07073b853f5243d2d8fc6d8c2b)
- [test] Add core `test-http-upgrade-server2` test [`bc98c0d`](https://github.com/http-party/node-http-proxy/commit/bc98c0dbce154ef266eef83d3c2f737a2d60f0e6)
- [test] Implement basic runner for multiple tests [`a4079c6`](https://github.com/http-party/node-http-proxy/commit/a4079c6a1c8b87334d12d47d67f060cbb1214696)
- [test] Add core `test-http-upload-timeout` test [`60ff181`](https://github.com/http-party/node-http-proxy/commit/60ff181af9c22405d3822ce5955f178ab13de79d)
- [test] Add core `test-http-status-code` test [`82060a5`](https://github.com/http-party/node-http-proxy/commit/82060a53430de05f2dc95450d8487bc8139544d5)
- [test] Add core `test-http-many-keep-alive-connections` test [`4e1ca6e`](https://github.com/http-party/node-http-proxy/commit/4e1ca6e61899b11cad1b437cc9d9490b9d856665)
- [test] Add core `test-http-chunked` test [`d7461f3`](https://github.com/http-party/node-http-proxy/commit/d7461f3206cca0691fbd438545ff325589770627)
- [test] Add core `test-http-head-response-has-no-body-end` test [`13389db`](https://github.com/http-party/node-http-proxy/commit/13389db1bef38a7fc7ddc3ada479a608f033020c)
- [test] Add core `test-http-server-multiheaders` test [`d7f15d0`](https://github.com/http-party/node-http-proxy/commit/d7f15d02f7477c76529fc76daddee5029079eb2d)
- [test] Add core `test-http-multi-line-headers` test [`35d2088`](https://github.com/http-party/node-http-proxy/commit/35d2088c96bacb44b17755176b6e9451ed0299dd)
- [test] Add core `test-http-head-response-has-no-body` test [`f79f3ad`](https://github.com/http-party/node-http-proxy/commit/f79f3adf0295ec5bb7fb9f6525b48ba5209d04c6)
- [refactor] Improved event handler cleanup  [`9f92332`](https://github.com/http-party/node-http-proxy/commit/9f923325d08ac018a3325beaa9e0805b5eda61e6)
- [fix minor] Correctly set x-forwarded-proto in WebSocket requests [`c81bae2`](https://github.com/http-party/node-http-proxy/commit/c81bae2fdde3bf0087fe71a39855c61c43ffb145)
- Revert "[refactor] Improved event handler cleanup " [`c83d88e`](https://github.com/http-party/node-http-proxy/commit/c83d88ee88faac10b53cd4296165ed85f26036b4)
- Allowing the common proxy headers' value to be appended in proxy chain scenarios. [`621f9b4`](https://github.com/http-party/node-http-proxy/commit/621f9b425a272421de98a674f1679f0c47912733)
- [test] Add basic test runner [`87999d0`](https://github.com/http-party/node-http-proxy/commit/87999d028880dfccca349c9c44f9e66a613c4d38)
- [examples] Add some hand-crafted middleware [`6e65c20`](https://github.com/http-party/node-http-proxy/commit/6e65c20017a2e1a87dc6d58e847bc6db16440f3c)
- [test] Add core `test-http-malformed-request` test [`a635389`](https://github.com/http-party/node-http-proxy/commit/a6353897cdbe8c380d52a060f5e66784f67ad98e)
- [example] Response modification middleware [`dd83199`](https://github.com/http-party/node-http-proxy/commit/dd8319972c1c2f9421a90a21dce9560fd5ca199f)
- [test] Add core `test-http-head-request` test [`c0857f2`](https://github.com/http-party/node-http-proxy/commit/c0857f2d59c33d91cb3e0c131c44ec1667f592fa)
- [test] Add core `test-http-response-close` test [`f1c0be3`](https://github.com/http-party/node-http-proxy/commit/f1c0be3f0bd2c5e87d44a37ba4f29aafd9903ad4)
- [refactor] core proxy logic. all tests should be passing. [`63ac925`](https://github.com/http-party/node-http-proxy/commit/63ac9252606d23e2003696da1fb34a539abee7ca)
- [test] Add core `test-http-contentLength0` test [`275109b`](https://github.com/http-party/node-http-proxy/commit/275109b2f8c8519c56ca9f456096d4002698fab1)
- [test] Add core `test-http-client-abort2` test [`98bbe54`](https://github.com/http-party/node-http-proxy/commit/98bbe541e4fa581f1b9e2eadb821c0609da6ab81)
- adding tests for url segment proxytable routing [`91e9bb9`](https://github.com/http-party/node-http-proxy/commit/91e9bb90709cc8a361066d6f6b8f51f58bfd7e36)
- [test] Add core `test-http-eof-on-connect` test [`80c216d`](https://github.com/http-party/node-http-proxy/commit/80c216df0cc59b88c6934f795c03ea16a737af34)
- [example] Replace `sys` usages with `util` [`8d701bb`](https://github.com/http-party/node-http-proxy/commit/8d701bb20b593c6cdf0ff1bc35cf83051b21a35e)
- [refactor] Updates to support http2 from @mikeal [`5b52c89`](https://github.com/http-party/node-http-proxy/commit/5b52c896947db42ac01e6038c9170d8859d33aea)
- [refactor] Listen for `socket` events since reverseProxy.socket is no longer set synchronously [`3828616`](https://github.com/http-party/node-http-proxy/commit/38286168161d4f4ad24d2ad95ccd8335e9ed08a4)
- [test] Run tests in `test/core/simple` by default [`68cebbe`](https://github.com/http-party/node-http-proxy/commit/68cebbe0e79ea283eea8a1ca850ab462c66c611a)
- simplify proxytable path segment rewrite logic [`c03a450`](https://github.com/http-party/node-http-proxy/commit/c03a450d9b952e1463ae2609303029e317ff5da2)
- change proxytable routing to route one level shallower [`4d50915`](https://github.com/http-party/node-http-proxy/commit/4d50915373b6afaafc7857a3e9366e8e77315683)
- [docs] Little explanation for test/core directory [`8ca5d83`](https://github.com/http-party/node-http-proxy/commit/8ca5d83497cc106a2456ff7f2ebe3db5c8634d69)
- [minor] Allow user to set `colors.mode` [`48d4a8b`](https://github.com/http-party/node-http-proxy/commit/48d4a8b263faa9acda06651bceeff50881f21b26)
- [minor] Indentation fix [`9e630da`](https://github.com/http-party/node-http-proxy/commit/9e630daf81d10485206ec136c3e1a07fe065ffeb)
- [v0.6] `http.Agent` uses different structure for sockets [`86b4122`](https://github.com/http-party/node-http-proxy/commit/86b4122323ca32d455714b1149b99acce49a9e45)
- [minor] Nicer output from test runner [`5c3d41b`](https://github.com/http-party/node-http-proxy/commit/5c3d41bf4e101d0250fb0b3db4a8dc078104dcad)
- Modified the ad-hoc proxy lookup to use _getKey(), rather than the [`553e7fb`](https://github.com/http-party/node-http-proxy/commit/553e7fbc335a9befd166d472f057aa50452a9d40)
- [fix] When client request is aborted, abort server request [`4d43d81`](https://github.com/http-party/node-http-proxy/commit/4d43d81e5c2d7c8088716d4fd574019f43ebb5ce)
- Fixes memory leak when clients abort connections [`c98ccb4`](https://github.com/http-party/node-http-proxy/commit/c98ccb40e9fe5c5198a1605fa8835efc3ff1856c)
- [fix test] Make test runner exit after test exits [`31a8c68`](https://github.com/http-party/node-http-proxy/commit/31a8c6800ddf8d91b477d980605a4c19284a1648)
- [test dist] Run core tests on `npm test` [`8358ef8`](https://github.com/http-party/node-http-proxy/commit/8358ef8a2bdf817c8ed515be7bc9cec0a9b5f486)
- don't add upgrade handler if a custom handler is passed in [`d6ea3a4`](https://github.com/http-party/node-http-proxy/commit/d6ea3a425c203695394eaba4ce8abd57f7809e98)
- always emit end in 0.4 [`182dcd3`](https://github.com/http-party/node-http-proxy/commit/182dcd34555f361c1bb2b8d2777689e64ce32f87)
- [fix] Fix incorrect depth check. [`3ab02f3`](https://github.com/http-party/node-http-proxy/commit/3ab02f3ad7f2c59d73c621695eb238233c16d09c)
- [minor] Everybody loves Unicode [`38bd906`](https://github.com/http-party/node-http-proxy/commit/38bd906f2bc9322b156b92c47457bb7904f0d23a)
- [test minor] Update copyright notice on test runner [`2ccc5c7`](https://github.com/http-party/node-http-proxy/commit/2ccc5c73eaef30ab5a2af7e456bfcc270583c460)
- [minor] When running tests output only basename [`e109eba`](https://github.com/http-party/node-http-proxy/commit/e109eba9724494737021579938c1094c9dfbc8ee)
- [dist] Version bump. 0.8.0 [`5055689`](https://github.com/http-party/node-http-proxy/commit/5055689a11f3b990f848bf2699e0111d9e708d5f)
- Revert "[dist] Adjusted engines field to allow for 0.6; version bump 0.7.7" [`1e33434`](https://github.com/http-party/node-http-proxy/commit/1e33434fcc4772c233825b5aada7472113c0be50)
- changeOrigin option: set the host header to the proxy destination [`f27d26f`](https://github.com/http-party/node-http-proxy/commit/f27d26f4515c900ea4cf1756ef279257a189e308)
- [dist] Adjusted engines field to allow for 0.6; version bump 0.7.7 [`30dac89`](https://github.com/http-party/node-http-proxy/commit/30dac898f30a8508b4c4b4236e9438987f320167)
- [fix] In routing proxy, match line beginning [`63dfc7f`](https://github.com/http-party/node-http-proxy/commit/63dfc7f1757fc9a1a9bceeb3b035e97be6504692)
- [v0.6] Don't use `agent.appendMessage()` [`6655e01`](https://github.com/http-party/node-http-proxy/commit/6655e0164216449a97090651230266da8ced0150)
- bump version 0.7.4 [`3dfba2b`](https://github.com/http-party/node-http-proxy/commit/3dfba2ba4591e0fcd65ff0bfd012b3ab749a0a02)
- bump version 0.7.6 [`c5dc929`](https://github.com/http-party/node-http-proxy/commit/c5dc9295c711177c165bfb34c67407e1a5a0ed06)
- Revert "update outgoing.headers.host incase the destination does proxying" [`2061c71`](https://github.com/http-party/node-http-proxy/commit/2061c713664b044852fdf67aa5e173e5c3b6d874)
- update outgoing.headers.host incase the destination does proxying [`65b7872`](https://github.com/http-party/node-http-proxy/commit/65b7872e6ad433deae4de823c63629cb341bd649)
- bump version 0.7.5 [`b4d41c3`](https://github.com/http-party/node-http-proxy/commit/b4d41c3628ade82792eb361b095ab014a88d537a)
- [minor] Fix indent on timeout notice [`c4124da`](https://github.com/http-party/node-http-proxy/commit/c4124da4f25860497790fc06c97dde6e8985ab73)
- [minor] Change test runner output order [`b76680b`](https://github.com/http-party/node-http-proxy/commit/b76680b045f69e03759bc119f4827f337a8f395d)
- grammar correction [`729496d`](https://github.com/http-party/node-http-proxy/commit/729496d2898612969f5369e7f1c313cb4034f96c)
- [dist] Test runner depends on `async` [`219b0ff`](https://github.com/http-party/node-http-proxy/commit/219b0ff8f8780cde4714267273b0a1637c84679f)
- [test fix] Remove unnecessary console.log in tests/websocket/websocket-proxy-test.js [`f188f4f`](https://github.com/http-party/node-http-proxy/commit/f188f4ffd8c47b6312cd88c28de7e5ac63565047)
- [test refactor] `test/core/{run =&gt; run-single}` [`004be38`](https://github.com/http-party/node-http-proxy/commit/004be38048792d6f1d3efb361a5e7e66d5dbee8d)

## [v0.7.3](https://github.com/http-party/node-http-proxy/compare/v0.7.2...v0.7.3) - 2011-10-03

### Commits

- added what is necessary for having proxyError on Routing proxywq [`b7adf86`](https://github.com/http-party/node-http-proxy/commit/b7adf866b595f0d64a3ef6bde19271276450e723)
- [dist] Version bump. 0.7.3 [`db185bb`](https://github.com/http-party/node-http-proxy/commit/db185bb303ce9c413b2abccbc885f8ec43b61202)

## [v0.7.2](https://github.com/http-party/node-http-proxy/compare/v0.7.1...v0.7.2) - 2011-09-30

### Merged

- [fix] Examples have working require paths now. [`#118`](https://github.com/http-party/node-http-proxy/pull/118)

### Commits

- [fix] Fixed require paths in examples [`2e8d4c6`](https://github.com/http-party/node-http-proxy/commit/2e8d4c6e49e2e9b27443c0b9ae2b96331715402b)
- [websockets] add latest websockets support [`45ef87e`](https://github.com/http-party/node-http-proxy/commit/45ef87e71bc9cccefe5fb6afc3121fb09b8efbc3)
- [dist] Version bump. 0.7.2 [`ccccc45`](https://github.com/http-party/node-http-proxy/commit/ccccc45f11fbe535017b1806fad43578f143649d)

## [v0.7.1](https://github.com/http-party/node-http-proxy/compare/v0.7.0...v0.7.1) - 2011-09-21

### Merged

- Readme fixes [`#114`](https://github.com/http-party/node-http-proxy/pull/114)
- #107: Set x-forwarded-for header (amongst others) [`#110`](https://github.com/http-party/node-http-proxy/pull/110)
- command line tool - make sure targetPort is an integer [`#109`](https://github.com/http-party/node-http-proxy/pull/109)

### Fixed

- [dist] Version bump v0.7.1, closes #107 #112 [`#107`](https://github.com/http-party/node-http-proxy/issues/107)

### Commits

- [test] Added a test for the "x-forwarded-for" header [`66e9820`](https://github.com/http-party/node-http-proxy/commit/66e982060c6c41ad7dfadce1403c8e13d267781a)
- [docs] Updated examples in README.md for 0.7.x API. [`24ef919`](https://github.com/http-party/node-http-proxy/commit/24ef9194953c27fb11a8f1ceb499e5feca11c30c)
- [examples] Updated examples to v0.7.x API. [`8fc8d96`](https://github.com/http-party/node-http-proxy/commit/8fc8d966c4681d514af00516b348105608e13382)
- [examples] More fixes to examples. [`549360a`](https://github.com/http-party/node-http-proxy/commit/549360a462c134cc2b02301070209084ec94c393)
- [fix] x-forwarded http headers should set properly. [`2677bb6`](https://github.com/http-party/node-http-proxy/commit/2677bb6c44244ea0b584db744955bedf7aee2c62)
- [fix] connection.socket -&gt; socket for source of x-forwarded-for data [`1f33943`](https://github.com/http-party/node-http-proxy/commit/1f33943b231cdf2cb619977801c7b0d4e98ab6df)
- Make sure the target port is an integer [`5ba25aa`](https://github.com/http-party/node-http-proxy/commit/5ba25aa3451f131b6c6c8892848a4f236f5b859e)

## [v0.7.0](https://github.com/http-party/node-http-proxy/compare/v0.6.6...v0.7.0) - 2011-09-10

### Fixed

- [fix] Add `x-forward-*` headers for WebSocket requests. Closes #74 [`#74`](https://github.com/http-party/node-http-proxy/issues/74)
- [doc] Document `setMaxSockets`. Fixes #81 [`#81`](https://github.com/http-party/node-http-proxy/issues/81)

### Commits

- [api test dist] Stubbed out the API for the higher-level `RoutingProxy` object to be exposed by `node-http-proxy` [`5927ecd`](https://github.com/http-party/node-http-proxy/commit/5927ecd62a082269c3b6a0ae4f5b4a673784bcdb)
- [api] Finalized the RoutingProxy API [`f765f90`](https://github.com/http-party/node-http-proxy/commit/f765f90ec37defaa2b493f859a982add51e25b76)
- [minor] Move private methods to the bottom of file(s) [`ec03d72`](https://github.com/http-party/node-http-proxy/commit/ec03d72c5d8749aee835f571869f69816be02265)
- [test] Updated tests to reflect finalized API of the RoutingProxy [`734769f`](https://github.com/http-party/node-http-proxy/commit/734769fa9b2c3054d45e33c3e552af80ce3f4740)
- [api doc] Rebuilt httpProxy.createServer() with the newer high-level RoutingProxy API [`598fe2e`](https://github.com/http-party/node-http-proxy/commit/598fe2e38def56518a1f0a8196b2fcb7f1bc569e)
- [minor] Remove commented out debug statements. [`5575bcf`](https://github.com/http-party/node-http-proxy/commit/5575bcf60c87def74d1755b2e5cc73e085dbf8c3)
- [doc] Updated examples [`13eaec5`](https://github.com/http-party/node-http-proxy/commit/13eaec55dc50e2aae164cb8adaa0f1a3c5a66c68)
- Add flow control [`6a7fd14`](https://github.com/http-party/node-http-proxy/commit/6a7fd14bfa9f25694d75cf490e32817ff15a94fe)
- Add flow control [`2b9e09b`](https://github.com/http-party/node-http-proxy/commit/2b9e09b00ac40e6c6de2b68754df7b8e8c1e3878)
- Emit drain if it doesn't happen on its own in 100ms [`37e2541`](https://github.com/http-party/node-http-proxy/commit/37e25418916a31e4a513ee5866d6013858d579cf)
- resume() can throw [`558a8a4`](https://github.com/http-party/node-http-proxy/commit/558a8a4f79716496dbdee13759c8641606458c05)
- [fix] Memory leak hunting. [`ca1d12c`](https://github.com/http-party/node-http-proxy/commit/ca1d12cf1bbfbe98b5159f9c02e2f6c818a1c749)
- Emit drain if it doesn't happen on its own in 100ms [`84be9f2`](https://github.com/http-party/node-http-proxy/commit/84be9f2c3a244c7dbfe2c6320fa26d85cf80ec31)
- resume() can throw [`0c71119`](https://github.com/http-party/node-http-proxy/commit/0c71119ee58ee84068120be72308ecb28cb3e532)
- [dist] Update examples/package.json to conform to nodejitsu style guidelines [`2937229`](https://github.com/http-party/node-http-proxy/commit/29372298208135f571538cc29dcc05f41f79b01c)
- Fixed large DoS vector in the middleware implementation [`0e36912`](https://github.com/http-party/node-http-proxy/commit/0e36912906640fdb007e0492b75c3f6a7b580ec6)
- [api] Added new `close()` method which cleans up sockets from HttpProxy instances [`0eae2a9`](https://github.com/http-party/node-http-proxy/commit/0eae2a913a2173d85478f8c9deec929388284ee2)
- Fixed large DoS vector in the middleware implementation [`07c8d2e`](https://github.com/http-party/node-http-proxy/commit/07c8d2ee6017264c3d4deac9f42ca264a3740b48)
- [minor] More contextual errors when middleware(s) error [`38315f6`](https://github.com/http-party/node-http-proxy/commit/38315f6b1f7b01bc6e55587878a57590135945c0)
- [dist] Update scripts in package.json [`6e1ade0`](https://github.com/http-party/node-http-proxy/commit/6e1ade0bb8174b744abb58df72b098bd96134ca4)
- [dist] Version bump. 0.7.0 [`0182ba3`](https://github.com/http-party/node-http-proxy/commit/0182ba37cd4c618cd50947ea2addef823349e49f)
- [merge] Merge from significant internal refactor in v0.7.x. No external API changes [`f7010e5`](https://github.com/http-party/node-http-proxy/commit/f7010e5169ac23114b9b35da272e9a041743fbb9)
- [minor] Small update to bin/node-http-proxy [`2cd8256`](https://github.com/http-party/node-http-proxy/commit/2cd8256c4d6089409f603655ea3b3a5ccf1fb065)
- [dist] Update .gitignore [`6c1c554`](https://github.com/http-party/node-http-proxy/commit/6c1c5544515bf17f0e6ed3588e16ae1a75f8a25b)
- [doc] Update README.md [`0ba5023`](https://github.com/http-party/node-http-proxy/commit/0ba5023e82fe8a08ed55194644d147c323368f41)
- [doc] Drop version number from README.md. [`bdf48be`](https://github.com/http-party/node-http-proxy/commit/bdf48bea36eae441c775e9321ab6e17db470bf27)
- [dist] Version bump. 0.7.0 [`00e34a1`](https://github.com/http-party/node-http-proxy/commit/00e34a10bd9ffca9e636b2e5aebb4f18ff6765ec)
- [test] Whitespace fix [`3a4d312`](https://github.com/http-party/node-http-proxy/commit/3a4d312eda08e7a5cecb3c82b04023e22f368e2b)
- [dist] Reorganize examples based on classification(s): http, websocket, or middleware [`81d6c31`](https://github.com/http-party/node-http-proxy/commit/81d6c318758231f77a52fab7de174fcc63b7a243)

## [v0.6.6](https://github.com/http-party/node-http-proxy/compare/v0.6.5...v0.6.6) - 2011-08-31

### Commits

- Memory leak hunting. [`f4fcf93`](https://github.com/http-party/node-http-proxy/commit/f4fcf934030e84c15cceca620e974aafc35f1691)
- [fix] Add guards to every throw-able res.end call [`e1c41d0`](https://github.com/http-party/node-http-proxy/commit/e1c41d06942b56f6cd65a079ae78b54456a8bbe1)
- [fix] Only set `x-forward-*` headers if req.connection and req.connection.socket [`de4a6fe`](https://github.com/http-party/node-http-proxy/commit/de4a6fe8a5f78460b030e635e5f4a63312cd4a76)
- [dist] Version bump. 0.6.6 [`967884c`](https://github.com/http-party/node-http-proxy/commit/967884c5de311f21b8405a5030730ef8db912531)

## [v0.6.5](https://github.com/http-party/node-http-proxy/compare/v0.6.4...v0.6.5) - 2011-08-29

### Commits

- [fix] Use `req.connection` for all x-forward-* headers [`f6dc12a`](https://github.com/http-party/node-http-proxy/commit/f6dc12a971fdd892614b32d2a4fb2ff39ddc0e67)
- [dist] Version bump. 0.6.5 [`7beead5`](https://github.com/http-party/node-http-proxy/commit/7beead54654bdc7f9ab4ed0c17000118a3e7b4fc)

## [v0.6.4](https://github.com/http-party/node-http-proxy/compare/v0.6.3...v0.6.4) - 2011-08-28

### Fixed

- Fix #95 Don't look on req.connection if it's not set. [`#95`](https://github.com/http-party/node-http-proxy/issues/95)

### Commits

- [api breaking] Begin refactor to optimize node-http-proxy by managing one instance of HttpProxy per `host:port` location [`d2b0e43`](https://github.com/http-party/node-http-proxy/commit/d2b0e4399e8026d3e2ece78ac8fdb1def6649950)
- [api test] Updated httpProxy.createServer() for new API exposed by simplified HttpProxy object. [`be4562d`](https://github.com/http-party/node-http-proxy/commit/be4562da9fafef8b26856f7f73f6c5a2c4e389b0)
- [test fix] A few minor fixes to ensure basic WebSocket tests are working. Better scope tests by supported protocol [`daf9231`](https://github.com/http-party/node-http-proxy/commit/daf9231a66f10a25782d2227df1b1501099ac5d1)
- [test] Updates for readability [`db10c4a`](https://github.com/http-party/node-http-proxy/commit/db10c4af918c3e4bc448163f4b9e9b9267145d47)
- Add guards to every throw-able res.end call [`7bda25b`](https://github.com/http-party/node-http-proxy/commit/7bda25b1c60d082f0f2fd12fc61b45a33b74f13d)
- [minor] Dont use `.bind()` [`340be42`](https://github.com/http-party/node-http-proxy/commit/340be42797e87fcc11859a771200075e7fe0c5f1)
- [dist] Version bump. 0.6.4 [`216d46d`](https://github.com/http-party/node-http-proxy/commit/216d46dc81bda1aeb0feb1318e34f37bee38c8fb)

## [v0.6.3](https://github.com/http-party/node-http-proxy/compare/v0.5.11...v0.6.3) - 2011-08-28

### Merged

- This adds a flag to ProxyRequest to disable the setting of x-forwarded-[for|port|proto] [`#73`](https://github.com/http-party/node-http-proxy/pull/73)

### Fixed

- Merge branch 'patch-1' of https://github.com/KimSchneider/node-http-proxy [`#80`](https://github.com/http-party/node-http-proxy/issues/80)

### Commits

- [minor] Style updates and whitespace cleaning for consistency [`f0917a3`](https://github.com/http-party/node-http-proxy/commit/f0917a3f97e8df2d58252f14c15ec54369c969ae)
- [api] refactor out middlewares from examples. [`2cf4e0a`](https://github.com/http-party/node-http-proxy/commit/2cf4e0a9e6c78dfd093c098fc87100ae71bc9450)
- [docs] add middleware examples (first draft) [`020290a`](https://github.com/http-party/node-http-proxy/commit/020290a162146c4996831f4f13d71c1dc949f508)
- [fix] use routing table mhen proxying WebSockets. [`efa17ef`](https://github.com/http-party/node-http-proxy/commit/efa17ef6cf614b763fc3b76570a24e750e2ddd31)
- Tested & fixed url middleware example, added comments. [`4cc18f4`](https://github.com/http-party/node-http-proxy/commit/4cc18f4217739b0bd1b3ac88287cc8a23d486b6b)
- [minor] add middleware to node-http-proxy [`b54666f`](https://github.com/http-party/node-http-proxy/commit/b54666ff69c574d842ce1349700c6b6248484d24)
- [minor] add middleware to node-http-proxy [`c773eed`](https://github.com/http-party/node-http-proxy/commit/c773eedeb6d0b22e2b41ab9215cfdc064a8095e3)
- [minor] add url-proxying middleware example [`45f3df8`](https://github.com/http-party/node-http-proxy/commit/45f3df80937ffd5854727c91ea6b0e09cf77e160)
- [fix] Removed bad example. [`2626308`](https://github.com/http-party/node-http-proxy/commit/2626308cd845982c82a284b0d0bc064090aaf116)
- [minor] add example to test concurrency [`6ec8d6c`](https://github.com/http-party/node-http-proxy/commit/6ec8d6caace3797841c0447feb081aa7920aa0dd)
- [minor] add example of using middleware to gzip response [`d3c0697`](https://github.com/http-party/node-http-proxy/commit/d3c06973a1bf1f1c54ca55a5d7f93b77133ef9a2)
- support old (port,host) and (options) style when using middlewares [`7976de1`](https://github.com/http-party/node-http-proxy/commit/7976de1121a40f963e18ea0a4673d185f847df4c)
- [minor] Added body decoder middleware example.  Needs fixing. [`8eaec35`](https://github.com/http-party/node-http-proxy/commit/8eaec3507456731c1138c0b8ebb4e51dedc7c300)
- [minor dist] Use `pkginfo`. Minor updates to variable scoping in `.createServer()` [`5d0bbb3`](https://github.com/http-party/node-http-proxy/commit/5d0bbb38c3af14907567e2dc7c4f84a915b60ce5)
- [doc] add comments to examples/url-middleware.js [`f6484de`](https://github.com/http-party/node-http-proxy/commit/f6484de4112463c74105db82d27f131d64478f1d)
- Handle cases where res.write throws [`be3a0d8`](https://github.com/http-party/node-http-proxy/commit/be3a0d84a1e75b45bc1fc63fe63cdabd9844eb59)
- [minor] code style changes [`8b48b7e`](https://github.com/http-party/node-http-proxy/commit/8b48b7e0af656fdbd6da2b16ec6365beec47c302)
- [doc] note in readme about middleware [`b5d5eaa`](https://github.com/http-party/node-http-proxy/commit/b5d5eaababa276f7d197e4b6a8a771b364b73139)
- Allow forwarding for x-forwarded-[for|port|proto] to enabled layering of http-proxies. [`404818b`](https://github.com/http-party/node-http-proxy/commit/404818b1dce9e77a917ce9f0c187772eb8c18042)
- [style] tidy [`0f8fe8e`](https://github.com/http-party/node-http-proxy/commit/0f8fe8e2460fd27edfba44989b78aa6b8c9a38e2)
- [fix] do not use middleware code if it's not needed [`2012588`](https://github.com/http-party/node-http-proxy/commit/20125889b362c61c85924810de446e1e7b18d079)
- [minor] minor fixes to gzip middleware example [`caa1f49`](https://github.com/http-party/node-http-proxy/commit/caa1f494ab4effabad6d08272c3606c1d82005ea)
- [minor] default enableXForwarded to true [`e3d95ec`](https://github.com/http-party/node-http-proxy/commit/e3d95ecab24700535184df32f3a97e8699099b7f)
- Updating to enableXForwarded [`ee3506a`](https://github.com/http-party/node-http-proxy/commit/ee3506a8e7262f780eeada331898d42ca0e9838a)
- [api] Expose adapted version of `stack` so it can be used with HttpProxy instances not created by `httpProxy.createServer()` [`5d6e6b9`](https://github.com/http-party/node-http-proxy/commit/5d6e6b9f78eb98b28db01490a36b23c1aade133f)
- The number of maxSockets has to be set after the agent is created. Setting the property in the constructor does not work. [`2caa5d2`](https://github.com/http-party/node-http-proxy/commit/2caa5d2b0d55898c133a0bf3a0048ee969efb121)
- [fix] Dont use res.* in proxyWebSocketRequest [`f7452bc`](https://github.com/http-party/node-http-proxy/commit/f7452bc42d963406f7ee19dfa353d72ce3252dd6)
- [fix] fix syntax errors. close issue #86 [`b8f8499`](https://github.com/http-party/node-http-proxy/commit/b8f84994b0515e12c9d87f89f81a8601be47a6ff)
- [api] merge middleware branch [`e6ff8d6`](https://github.com/http-party/node-http-proxy/commit/e6ff8d6597a977baf0caf4f69c75bfa93d7281f3)
- [dist] Version bump. 0.6.3 [`1389b70`](https://github.com/http-party/node-http-proxy/commit/1389b706b5c1d857c571c2947b7c758b5cc70ca3)
- merged [`5ba0f89`](https://github.com/http-party/node-http-proxy/commit/5ba0f89aa356b2e76f5cf64c16e8578d71c45d8a)
- [fix] handler variable in createServer was global (!)  [`25c06a3`](https://github.com/http-party/node-http-proxy/commit/25c06a3a952068de6a24c643cb0c872f7b9a0846)
- [dist] bump version 6.0 [`03475a5`](https://github.com/http-party/node-http-proxy/commit/03475a59445a1c1c1029d0673aafabe63af1e711)
- [dist] bump version 0.6.2 [`d8068a8`](https://github.com/http-party/node-http-proxy/commit/d8068a832d437790ce8680b9b34a9f171d75786c)
- [dist] bump version 5.12 [`5d33ad7`](https://github.com/http-party/node-http-proxy/commit/5d33ad711895b2afcbd6dd5e1c0449cee1ceae7b)
- [dist] bump version 0.6.1 [`fea371d`](https://github.com/http-party/node-http-proxy/commit/fea371dc0a47dfb4f84427e5740e8756f4e5b285)
- [fix] broken RegExp [`549bfea`](https://github.com/http-party/node-http-proxy/commit/549bfeac233888ec84edeec350ed5a7377f3773e)
- [doc] add note on middleware to Using node-http-proxy section of the README [`5bf2d59`](https://github.com/http-party/node-http-proxy/commit/5bf2d59241a7695f43bb89e5cb41ade2ab7a0ad2)

## [v0.5.11](https://github.com/http-party/node-http-proxy/compare/v0.5.10...v0.5.11) - 2011-06-26

### Fixed

- [api] Simplify the usage for the `.changeHeaders` option. Fixes #34 [`#34`](https://github.com/http-party/node-http-proxy/issues/34)

### Commits

- [api doc test] node-http-proxy now emits `websocket:*` on important WebSocket events. Added tests for these features and updated some code docs [`4f85ca0`](https://github.com/http-party/node-http-proxy/commit/4f85ca04e425a7d4df1e46c9cadd6026eeed32f6)
- [doc] Updated docco docs [`f0649d8`](https://github.com/http-party/node-http-proxy/commit/f0649d8d6a9f84ac61d5f173c585fa4307ffb3c3)
- [doc] Added examples/latent-websocket-proxy.js [`fcfe846`](https://github.com/http-party/node-http-proxy/commit/fcfe84626fff15be21ac83ccd69b96bf3ca1f7a2)
- [doc] Added sample for custom error messages using the `proxyError` event [`4cdbf0e`](https://github.com/http-party/node-http-proxy/commit/4cdbf0e8729a0665904b577376240c00e56ad876)
- [doc] Add examples/standalone-websocket-proxy.js [`1ee8ae7`](https://github.com/http-party/node-http-proxy/commit/1ee8ae710497e239716f72d45e2f61ead3995dc3)
- [dist] Version bump. 0.5.11 [`baf0b9e`](https://github.com/http-party/node-http-proxy/commit/baf0b9e25af53e2738812ff78614cc12966e99e3)
- [doc] Small update to code docs [`9d9509f`](https://github.com/http-party/node-http-proxy/commit/9d9509f791c4c566629c2e323259885f1c3db7ed)
- [minor] Add missing space [`b608a02`](https://github.com/http-party/node-http-proxy/commit/b608a029f8aa26f1a74a917e0bec0ac37e4615a0)

## [v0.5.10](https://github.com/http-party/node-http-proxy/compare/v0.5.9...v0.5.10) - 2011-06-13

### Commits

- [refactor] Manage our own internal list of Agent instances [`887c580`](https://github.com/http-party/node-http-proxy/commit/887c5808c90b7128c040e510e237ddb4d034fe3e)
- [doc] Update docco docs for 0.5.9 [`b4ac4d4`](https://github.com/http-party/node-http-proxy/commit/b4ac4d441fe4fb84d463bd889a5ce8d7f4d596ca)
- [test] Update tests to use `localhost` [`a1cdf00`](https://github.com/http-party/node-http-proxy/commit/a1cdf005b98c422c777c88a7d7baf2eeb91f732d)
- [dist] Version bump. 0.5.10 [`7b574d3`](https://github.com/http-party/node-http-proxy/commit/7b574d3d3e52b09a6445c011b8f2ae0d78282111)
- [doc] Bump version in README.md [`653c6ca`](https://github.com/http-party/node-http-proxy/commit/653c6ca1af607623b653d3148b1bb45a304aab87)

## [v0.5.9](https://github.com/http-party/node-http-proxy/compare/v0.5.8...v0.5.9) - 2011-05-23

### Commits

- [fix] Change sec-websocket-location header when proxying WSS --&gt; WS. Added test coverage for this scenario [`028d204`](https://github.com/http-party/node-http-proxy/commit/028d2044e71d70b7bc21d339de29e2275c3be5c2)
- [dist] Version bump. 0.5.9 [`57ca62c`](https://github.com/http-party/node-http-proxy/commit/57ca62c878c9a953f2344719556e05492ece3435)

## [v0.5.8](https://github.com/http-party/node-http-proxy/compare/v0.5.7...v0.5.8) - 2011-05-21

### Commits

- [doc] Regenerate docco docs [`c5fd368`](https://github.com/http-party/node-http-proxy/commit/c5fd368a8d803b6ab47e32e744a6fd6a6ca5361f)
- [doc] Update docco docs [`74120d8`](https://github.com/http-party/node-http-proxy/commit/74120d8988627bb0686d3a26cb8ec1408cc41287)
- [doc] Update to v0.5.7 in code and README.md [`6fd272a`](https://github.com/http-party/node-http-proxy/commit/6fd272ac18240811d8a8a39c85ee483557c414b3)
- [dist] Version bump. 0.5.8. Forwards compatible with new versions of nodejs [`76ecb51`](https://github.com/http-party/node-http-proxy/commit/76ecb51e7b41a23288f922c9c5df3ce40f67bf80)
- [fix] Dont force `Connection: close` now that Keep-Alive is supported [`a86d18b`](https://github.com/http-party/node-http-proxy/commit/a86d18bc7f93d013df715d1f4d88e651846f645d)
- [test] Update to vows description for web-socket-proxy-test.js [`a865fe6`](https://github.com/http-party/node-http-proxy/commit/a865fe662ff04a4badcc90ce2af80d2380c40a85)

## [v0.5.7](https://github.com/http-party/node-http-proxy/compare/v0.5.6...v0.5.7) - 2011-05-19

### Commits

- [api] Add `x-forwarded-proto` and `x-forwarded-port` to proxied HTTP requests [`421895f`](https://github.com/http-party/node-http-proxy/commit/421895fa308d49628bbbb546d542efa96769c3f4)
- [dist] Version bump. v0.5.7. Only good on node v0.4.7. See issue #48. [`0911c17`](https://github.com/http-party/node-http-proxy/commit/0911c1719e641c6e4342027e8d5d82c47c6f310e)
- [fix] Set `x-forwarded-for` from req.connection.socket.remoteAddress if req.connection.remoteAddress is not defined [`e9b3ec9`](https://github.com/http-party/node-http-proxy/commit/e9b3ec9b1d0ebf427e138176b28af44f0f973670)

## [v0.5.6](https://github.com/http-party/node-http-proxy/compare/v0.5.5...v0.5.6) - 2011-05-19

### Commits

- [fix doc] Add `error` handler to reverseProxy request when proxying WebSockets to prevent unhandled ParseError. Rename some variables in proxyWebSocketRequest to make the code more readable [`76580c2`](https://github.com/http-party/node-http-proxy/commit/76580c292a152c0007352a9d383f59e48993cd03)
- [doc] Regenerate docco docs [`bd45216`](https://github.com/http-party/node-http-proxy/commit/bd45216bc9207e5016f394a4bfee2bdffcc669c7)
- [api minor] Small refactor to emit `webSocketProxyError` from a single helper function on any of the various `error` events in the proxy chain [`5d2192e`](https://github.com/http-party/node-http-proxy/commit/5d2192e654f23e1b76e0b66554debe1590a3af64)
- [api] Manual merge of #46: add custom `proxyError` event and enable production error handling. [`652cca3`](https://github.com/http-party/node-http-proxy/commit/652cca37ea321ec9d1d55125217df0214c8090b6)
- [dist] Version bump. v0.5.6 Only good on node v0.4.7. See issue #48. [`f1c0f64`](https://github.com/http-party/node-http-proxy/commit/f1c0f641aa14dc3c267de37370a7369c3131c636)

## [v0.5.5](https://github.com/http-party/node-http-proxy/compare/v0.5.4...v0.5.5) - 2011-05-19

### Commits

- [fix] Change variable references for Websockets, bugs found from using wsbench [`7bf0cae`](https://github.com/http-party/node-http-proxy/commit/7bf0caef9fae86a34719f04f7b9926095fb6a146)
- [dist] Version bump. 0.5.5. Only good on node v0.4.7. See issue #48. [`acacc05`](https://github.com/http-party/node-http-proxy/commit/acacc0561f2efabc0a7859b9a410e954f2dca6fd)

## [v0.5.4](https://github.com/http-party/node-http-proxy/compare/v0.5.3...v0.5.4) - 2011-05-19

### Commits

- [doc] Update docco docs [`faf2618`](https://github.com/http-party/node-http-proxy/commit/faf2618cf3b53a972779514842bc4264ec9541fa)
- [doc] Update README.md to reflect the new HTTPS to HTTP proxy capabilities [`abc01bc`](https://github.com/http-party/node-http-proxy/commit/abc01bce293f7c1a88f9be08b0540407d2b0f4a1)
- [doc test api] Improve node-http-proxy API to allow for HTTPS to HTTP proxying scenarios. Update tests accordingly. [`895f577`](https://github.com/http-party/node-http-proxy/commit/895f577744e3cbcbb5f479c4aacec5323bb001f7)
- [doc] Update examples for HTTPS to HTTP proxying [`91737fa`](https://github.com/http-party/node-http-proxy/commit/91737fadb640f30d3cd959f29069537473207efd)
- [dist] Version bump. 0.5.4. Only good on node v0.4.7. See issue #48. [`c04eec1`](https://github.com/http-party/node-http-proxy/commit/c04eec1c370ca0eb212c96c0896c27b349f7ea97)
- [minor] Update README.md to conform to Github flavored markdown [`32a15dd`](https://github.com/http-party/node-http-proxy/commit/32a15dd79d860343453c38a7eef8339d7b99718b)
- [minor] Update README.md to conform to Github flavored markdown [`521fe27`](https://github.com/http-party/node-http-proxy/commit/521fe271853632563143fb4b76c032f7afa7831a)

## [v0.5.3](https://github.com/http-party/node-http-proxy/compare/v0.5.2...v0.5.3) - 2011-05-18

### Commits

- [test] Continued work around Origin mismatch tests [`44a8566`](https://github.com/http-party/node-http-proxy/commit/44a85664a80fd67e20bbc36d280816dbd1a796c5)
- [doc] Regenerate docco docs [`9e36d2d`](https://github.com/http-party/node-http-proxy/commit/9e36d2d2e619be322bb73092db2a9d72ef6709e8)
- [fix test api] Only change Origin headers in WebSocket requests when the `changeOrigin` option is set explicitly. Added tests to ensure Origin and sec-websocket-origin headers match when proxying websockets. [`9c6c4b9`](https://github.com/http-party/node-http-proxy/commit/9c6c4b908b7d6ce67144ba9d41702b5694254099)
- [test] Improve websocket tests to inspect outgoing and incoming HTTP headers to test origin mismatch bugs [`6e679c8`](https://github.com/http-party/node-http-proxy/commit/6e679c8019e1eb62b2b1da48628f89b8046203fd)
- [test] Refined tests to begin checking Origin == Sec-Websocket-Origin [`9ab54ab`](https://github.com/http-party/node-http-proxy/commit/9ab54ab47fc43d98f3182da9c41487f524933783)
- [doc minor] Update docs and code docs for v0.5.3 release [`03b9087`](https://github.com/http-party/node-http-proxy/commit/03b908744612faed82d9233f3b6d4af70368cf3c)
- [dist] Version bump. v0.5.3. Only good on node v0.4.7. See issue #48. [`d9fa261`](https://github.com/http-party/node-http-proxy/commit/d9fa261cdc97aee71279064e536a4a22edbe3b5b)

## [v0.5.2](https://github.com/http-party/node-http-proxy/compare/v0.5.1...v0.5.2) - 2011-05-17

### Merged

- Readme: fix syntax error, reformat code blocks [`#52`](https://github.com/http-party/node-http-proxy/pull/52)

### Commits

- format markdown for syntax highlighting on GitHub [`28f6dc1`](https://github.com/http-party/node-http-proxy/commit/28f6dc153a7d9fa9b6a08637c90765cf3a07fd3e)
- [doc] Regenerate docco docs [`a5e1e3e`](https://github.com/http-party/node-http-proxy/commit/a5e1e3e70d02f32ab86b711ec4b262df5955a1a9)
- [test] Fix tests in https mode [`1ee6bef`](https://github.com/http-party/node-http-proxy/commit/1ee6beff6aa3087e332701fd3cfda70b4e968ce8)
- [fix] Manage bookkeeping for incoming requests to the underlying sockets behind reverse proxied websocket events. Only use the appropriate variables in the closure scope of the `upgrade` event from this bookkeeping [`85223ea`](https://github.com/http-party/node-http-proxy/commit/85223ea0800ad63ea82783c9dc2dc4a0e3345ae8)
- [minor] Fix syntax in examples/ [`ff82946`](https://github.com/http-party/node-http-proxy/commit/ff829467d33d326c588861a46acc2bf9adbdddd2)
- add spacing around code blocks to fix README rendering [`ab8c264`](https://github.com/http-party/node-http-proxy/commit/ab8c264e6d729de81c93982f97875006e52240f0)
- [dist] Use devDependencies in package.json [`e6c52d4`](https://github.com/http-party/node-http-proxy/commit/e6c52d431f8a32e11cd347fbabeb7a03d0d40790)
- don't highlight non-javascript as javascript [`d5b9ba7`](https://github.com/http-party/node-http-proxy/commit/d5b9ba7180376b8a67b9cbfebe9acf7399cab3ed)
- fix syntax error in README example [`332d2d7`](https://github.com/http-party/node-http-proxy/commit/332d2d780ab62ccc996157dacd2498c568816ffc)
- [minor] Ignore npm modules and debug logs [`e90cbd6`](https://github.com/http-party/node-http-proxy/commit/e90cbd6f148633ef7d3e2de06aaabe1cc493cc37)
- [dist] Include docco module as a dev dependency [`d08c2bb`](https://github.com/http-party/node-http-proxy/commit/d08c2bb525ec661c0c8e6539e28605972b1ae9b8)
- [dist] Version bump. 0.5.2. Only good on node v0.4.7. See issue #48. [`360e79a`](https://github.com/http-party/node-http-proxy/commit/360e79a005d298f40f36ee0e25c34fe534311b09)

## [v0.5.1](https://github.com/http-party/node-http-proxy/compare/v0.5.0...v0.5.1) - 2011-05-10

### Commits

- [dist] Version bump. 0.5.1. Only good on node v0.4.7. See issue #48. [`6c80177`](https://github.com/http-party/node-http-proxy/commit/6c8017734053bc683f32a2b9f0ba18ba0c014855)
- Revert "Fixed "Invalid argument to getAgent" when proxying HTTP" [`40dc9de`](https://github.com/http-party/node-http-proxy/commit/40dc9dee2d1e617af7f85a056d281b4f220f2802)
- [fix] Fix typo in bin/node-http-proxy [`57127a3`](https://github.com/http-party/node-http-proxy/commit/57127a367193bcf12be2b367e1e01cbc57d685fe)
- Merged pull request #39 from timmattison/master. [`ac425d7`](https://github.com/http-party/node-http-proxy/commit/ac425d70ef63b847fe6eb17dbfc4b084d0dd2d20)
- Fixed "Invalid argument to getAgent" when proxying HTTP [`642e158`](https://github.com/http-party/node-http-proxy/commit/642e15805dbd572835bb4fee9527e4f2da658833)

## [v0.5.0](https://github.com/http-party/node-http-proxy/compare/v0.4.2...v0.5.0) - 2011-04-17

### Commits

- [doc] Breakout demo.js into files in example/. Add web-socket-proxy.js example [`6e4bf6a`](https://github.com/http-party/node-http-proxy/commit/6e4bf6a9cbc400fcd2be420649ce08936417dd83)
- [api test doc] Improve HTTPS support. Update minor documentation. Change tests accordingly. [`bf68dc3`](https://github.com/http-party/node-http-proxy/commit/bf68dc30a5c508bc8f533f52c083206b87963811)
- [api] Update WebSocket support to use http.Agent APIs [`b0b0183`](https://github.com/http-party/node-http-proxy/commit/b0b0183c2b54fa63bd2a6f9c92475c7f56d811a3)
- [api] Update `.proxyRequest()` and `.proxyWebSocketRequest()` APIs to take an options hash instead of a set of arguments. Add HTTPS support. [`cfddd12`](https://github.com/http-party/node-http-proxy/commit/cfddd12e821bd6b07ff2dbf0aa543ddfc3664dca)
- [doc api] Update README.md and CHANGELOG.md for v0.5.0. Update bin/node-http-proxy to read files specified in `config.https` [`212009d`](https://github.com/http-party/node-http-proxy/commit/212009df6b08de3c0c97a4e9ec43f60f6bf49ea6)
- [test] Add WebSocket tests [`4d18ac1`](https://github.com/http-party/node-http-proxy/commit/4d18ac1ae611f84e5e0cc599234124d183d81ffd)
- [doc] Regenerate docco docs [`c485c87`](https://github.com/http-party/node-http-proxy/commit/c485c8742c86b504823020d2cf6c1342a1bcce48)
- [doc test] Small updates to README.md. Update to try require socket.io [`12064d8`](https://github.com/http-party/node-http-proxy/commit/12064d8e5debf674cd5d367e563b699f10a4325e)
- [api] Remove winston logging in favor of custom events [`a89b397`](https://github.com/http-party/node-http-proxy/commit/a89b3976b25516db9b601c0327948f3d90fab006)
- [doc] Update README.md [`bd6a262`](https://github.com/http-party/node-http-proxy/commit/bd6a2622ad67b8c7ec15868037a48048207ce0df)
- [dist] Version bump. v0.5.0 [`ddf31b2`](https://github.com/http-party/node-http-proxy/commit/ddf31b22ec71ef9dacca9c178ee26b6314d9fdf4)
- [api] Update `request` event to be consistent by emitting both `req` and `res`. Add `x-forwarded-for` header. [`a3cb527`](https://github.com/http-party/node-http-proxy/commit/a3cb527be5e42d5192400933bf32a361b8c707c4)
- [api] Emit `end` event when done proxying [`5681fc1`](https://github.com/http-party/node-http-proxy/commit/5681fc1a28ff06dfa91d9bf5512c688235cafac4)
- [minor] Small update to README.md [`40c51a7`](https://github.com/http-party/node-http-proxy/commit/40c51a703baaf050b35f60131d3e78b42e7b0858)
- [dist] Move pgriess' websocket client into vendor/* [`7cbf447`](https://github.com/http-party/node-http-proxy/commit/7cbf44732068dc788d31432553b3bdfcfb39f743)

## [v0.4.2](https://github.com/http-party/node-http-proxy/compare/v0.4.1...v0.4.2) - 2011-04-13

### Commits

- [dist] Version bump. 0.4.2. Remove `eyes` dependency. [`a5d88aa`](https://github.com/http-party/node-http-proxy/commit/a5d88aaacc209bdceaf0799e99ff82bdce1bdc10)

## [v0.4.1](https://github.com/http-party/node-http-proxy/compare/v0.4.0...v0.4.1) - 2011-03-20

### Commits

- [dist] Version bump. 0.4.1. Fix package.json [`0d1a3fe`](https://github.com/http-party/node-http-proxy/commit/0d1a3fe99511dda1ac949536a9eb4a045db39979)

## [v0.4.0](https://github.com/http-party/node-http-proxy/compare/v0.3.1...v0.4.0) - 2011-03-20

### Commits

- [api] Further work on refactor for node 0.4.0 [`e39a9f9`](https://github.com/http-party/node-http-proxy/commit/e39a9f93d2f9ab6ea769fad5e9dda25d022d8a1a)
- [doc] Added docco generated literate coding documentation [`3bc7d16`](https://github.com/http-party/node-http-proxy/commit/3bc7d16adc48ad1aa1161bb02bd0c27d4fb20639)
- [doc api test] Wrap things up for v0.4.0 release: Add hostnameOnly routing to ProxyTable, add more documentation, fix edge-cases until they can be further investigated in node.js core [`5715318`](https://github.com/http-party/node-http-proxy/commit/571531820e2233b0d2f7268a1d4db8510fcabf91)
- [api] First pass at removing pool and working with node v0.4.0 [`9faa924`](https://github.com/http-party/node-http-proxy/commit/9faa924a29544cfd84c28cb1c45489f495e3806a)
- [doc api test] Rename HttpProxy.pause to HttpProxy.resume. Update documentation and tests accordingly [`4110448`](https://github.com/http-party/node-http-proxy/commit/4110448046dd945afe3e092968d9382d573a369a)
- [doc] Added more documentation [`973f19f`](https://github.com/http-party/node-http-proxy/commit/973f19fd5a14e3bfad5f67e54710a4076a469fe0)
- [doc] Regenerate docco docs [`6c42f04`](https://github.com/http-party/node-http-proxy/commit/6c42f045241194061c3786ba5827aebf88070201)
- [api] Force connection header to be `close` until keep-alive is replemented [`3fd3c96`](https://github.com/http-party/node-http-proxy/commit/3fd3c96fa05fda45c7ef9ff44594644ac54f4a1e)
- [dist] Version bump. 0.4.0 [`cbb5fbc`](https://github.com/http-party/node-http-proxy/commit/cbb5fbccd0e65c51eba14e75ef44184714cc8971)
- [api test] All tests are passing when run as individual files [`389159d`](https://github.com/http-party/node-http-proxy/commit/389159da1b91ab60b8de3c379d84e76c703e6b59)
- [minor doc] Update demo and small fix to node-http-proxy [`d8c5406`](https://github.com/http-party/node-http-proxy/commit/d8c54063dc5961fa619f7c04fa2d225da9aa1439)
- [fix] Fixed cli parsing issue when --argument=value is not used [`34cba38`](https://github.com/http-party/node-http-proxy/commit/34cba38c297d6dcb845e95b9e1ce0271da1631d2)
- [test] Small update to proxy-table-test.js [`3588687`](https://github.com/http-party/node-http-proxy/commit/3588687874eb691fe59407a207d38efa418211d0)
- [minor] Expose version on module [`1dd9b3b`](https://github.com/http-party/node-http-proxy/commit/1dd9b3b15088a3c4595faae64822969014a61d52)
- [doc] Update to v0.3.1 in README.md [`8ef2e1f`](https://github.com/http-party/node-http-proxy/commit/8ef2e1fe33e0fca2b80c0d6474dba994e625f094)
- [dist] Change package.json for npm version bump [`0e7f362`](https://github.com/http-party/node-http-proxy/commit/0e7f3626718ecf108f3cafa814b0f4ffb3e6faa2)

## [v0.3.1](https://github.com/http-party/node-http-proxy/compare/v0.3.0...v0.3.1) - 2010-11-22

### Commits

- [api test doc] Updated tests. Added ProxyTable functionality [`bedc7a3`](https://github.com/http-party/node-http-proxy/commit/bedc7a3ae57d5ec07b372a550fa69772f9fbc19e)
- [test] Simplified tests. Added tests for experimental websocket support [`8c3e993`](https://github.com/http-party/node-http-proxy/commit/8c3e993833e2a09376fdb5e7c847ff00b53e70d8)
- [test doc api] Added forward proxy functionality with tests [`c06f4bf`](https://github.com/http-party/node-http-proxy/commit/c06f4bf7fe50f29677dc5a5aad596193fc893018)
- [dist minor] Removed vendored pool. Changed all references of sys to util [`8251296`](https://github.com/http-party/node-http-proxy/commit/8251296d7f5c472ec523316e905d678042b043d3)
- WebSocket proxy support, fixed 304 code halting [`7249ef3`](https://github.com/http-party/node-http-proxy/commit/7249ef3ee776c66acc95036dc76a2d08dc3f6350)
- [api] pseduo-vendor pool until pull request is finalized [`7c2eb5d`](https://github.com/http-party/node-http-proxy/commit/7c2eb5de3531f20ea92c99dd8ab207d26be9dce8)
- No-server fix [`f84880f`](https://github.com/http-party/node-http-proxy/commit/f84880fcd946e55585d8e901e5bc32933f629837)
- [api test bin doc] Added bin script and simple logging [`00014d6`](https://github.com/http-party/node-http-proxy/commit/00014d624c052e7404ce96c7e06769440c4eae2a)
- [debug] Removed pool as a dependency for stress test [`73381cf`](https://github.com/http-party/node-http-proxy/commit/73381cf71ae92b9ed1c2da5986aa7ca31a7cf2e8)
- 'end' event becomes 'close', added more try-catch handling [`cd78af5`](https://github.com/http-party/node-http-proxy/commit/cd78af5feaa67c5005df921a8d1a61575a58fca2)
- Added support of automatic websocket tunneling, added test for it [`56003b5`](https://github.com/http-party/node-http-proxy/commit/56003b527625b2d83a191f3172005c87856aa87d)
- [debug] Better debug messages to try to determine if pool is slowly losing clients to forever busy [`dd1918d`](https://github.com/http-party/node-http-proxy/commit/dd1918dc360dc0f9553c35c82f3f0f93ac3bfb46)
- [doc dist] Version bump. Added CHANGELOG.md [`de53d5e`](https://github.com/http-party/node-http-proxy/commit/de53d5eb2c3d671be0ad0e736a6435c3bf5f55f4)
- Moved error handling to response.on('end'), fixed error handling in websocket's part [`7e61f0c`](https://github.com/http-party/node-http-proxy/commit/7e61f0cf5725dedf37b956545639c2d6129855d3)
- [minor] Pushing hot-fix from Mikeal for vendored pool repo [`60791f3`](https://github.com/http-party/node-http-proxy/commit/60791f361f8a11f9d1bad2c6366bf0ce72b40f66)
- [api] Integrated commits from donnerjack and worked on pool changes [`3bb458e`](https://github.com/http-party/node-http-proxy/commit/3bb458e115037bc27691705d255b0d2e2504a9f1)
- [doc] Updated Copyright ... added Fedor [`9128a8c`](https://github.com/http-party/node-http-proxy/commit/9128a8c5a15d0f64a0bae946f3e741ea708bc56f)
- [minor] Listen to error event on pool so we dont fail out unexpectedly anymore [`711258e`](https://github.com/http-party/node-http-proxy/commit/711258ef469d064cc0dbe0f0320ed1047ed0bd54)
- adding more debugging messages [`5d54ea5`](https://github.com/http-party/node-http-proxy/commit/5d54ea58c93c26635e0de96871e824baffea34dd)
- adding some debug messages for live testing [`4069a7e`](https://github.com/http-party/node-http-proxy/commit/4069a7e98c22a48bae7fd57ad5f315d0e5006dfc)
- [minor] Listen to error events re-emitted by pool into the ClientRequest [`f8bff4c`](https://github.com/http-party/node-http-proxy/commit/f8bff4c618ab2a6b6185ac973cd0e21cea19c23a)
- [minor] Updated max clients for pool [`32aaf74`](https://github.com/http-party/node-http-proxy/commit/32aaf74e95f8a39d847b352ca984145e7abe89a6)
- [debug] Trying to repair pool busy client growth [`7b0ea85`](https://github.com/http-party/node-http-proxy/commit/7b0ea85e2ac58d5f711f64b855f746fb2423a276)
- [debug] Roll back last commit ... connection = close was ineffective [`266e524`](https://github.com/http-party/node-http-proxy/commit/266e5246eacb4877bb6ab557e6e6b9b8434ad612)

## [v0.3.0](https://github.com/http-party/node-http-proxy/compare/v0.2.0...v0.3.0) - 2010-09-10

### Commits

- [api] Revert to old 0.1.x codebase for bug testing and performance comparison [`66afb2a`](https://github.com/http-party/node-http-proxy/commit/66afb2a2a35a479512ce2601c89b82f13596fc9f)
- [api test dist doc] Updated for 0.3.0 release [`a9084b9`](https://github.com/http-party/node-http-proxy/commit/a9084b923afa66c3004abec4951ff02e031631da)
- [api] Object creation is cheap for HttpProxy, so lets take advantage [`9f0aeac`](https://github.com/http-party/node-http-proxy/commit/9f0aeacab1a632136f5905a0d03ad04be9f93f51)
- [doc] Update contributors for 0.3.0 [`6d47d98`](https://github.com/http-party/node-http-proxy/commit/6d47d98f5345b7f335c3b93f8e4a31dd90235dda)

## [v0.2.0](https://github.com/http-party/node-http-proxy/compare/v0.1.5...v0.2.0) - 2010-09-07

### Commits

- [dist] Version bump and update to README + LICENCE. Word to Mikeal for coming thru for 0.2.0 [`69c162d`](https://github.com/http-party/node-http-proxy/commit/69c162dc3da334b2ece0a19be5ea4c8da7e0fe87)
- [api dist] Merge of branch 0.2.0 [`fd61828`](https://github.com/http-party/node-http-proxy/commit/fd618289338ca2d7595f695c0b8531b40145bbca)
- [api] Completely refactored node-http-proxy with help from Mikeal [`1221939`](https://github.com/http-party/node-http-proxy/commit/1221939accf00467adb25f8908e991e984043c85)
- [api minor debug] Remove debug code, set Connection header if not set [`6d08f24`](https://github.com/http-party/node-http-proxy/commit/6d08f24c863e071eb4a0d3ede15656e5e7c27c4b)
- [debug] Added some debugging to figure out why AB wont complete a test with v0.2.0 [`9715ebd`](https://github.com/http-party/node-http-proxy/commit/9715ebd40bdbbe883eb383676d5b0df24968dd72)
- [api] Integrated a little more from Mikeal to make our return headers consistent [`eb39018`](https://github.com/http-party/node-http-proxy/commit/eb39018fd0b5751dd90fabce905997e52f2ffecd)
- [doc] Updated README.md [`f291efb`](https://github.com/http-party/node-http-proxy/commit/f291efbaa4360d6e7ff4004cc11f8df0d737c1d0)

## v0.1.5 - 2010-09-02

### Commits

- [api] More changes for createServer api [`5d94ae2`](https://github.com/http-party/node-http-proxy/commit/5d94ae27bc2d56d1f817b0cf1dfdb01dcc376393)
- added colors and asciimo [`d490b50`](https://github.com/http-party/node-http-proxy/commit/d490b50ada8c1024cb785335966b71d69fae3407)
- [api] First commit of http-proxy [`30b68c1`](https://github.com/http-party/node-http-proxy/commit/30b68c153270619119ec36615bb54ee7a2816ecc)
- updating demo [`c4b7c0d`](https://github.com/http-party/node-http-proxy/commit/c4b7c0d8a0cc5fd7f43257594bd0a71c7bd12a63)
- initial release v0.1.0, sure to have many updates coming. [`85f7372`](https://github.com/http-party/node-http-proxy/commit/85f73723415ec54539721777e77d5d10de383469)
- fleshing out demo [`994f748`](https://github.com/http-party/node-http-proxy/commit/994f7481ce07c15afa5ab993b79d920b8220be44)
- [docs] added benchmarks [`bbed176`](https://github.com/http-party/node-http-proxy/commit/bbed17640f84e56aaea06c6d4eb7d04952957fce)
- updated paths to use npm [`972c8c0`](https://github.com/http-party/node-http-proxy/commit/972c8c05274c72c7320291389f88b0694ac290ca)
- added spark demo [`d0ad931`](https://github.com/http-party/node-http-proxy/commit/d0ad93176d8430301a8a42f8c2b817674ce7ba32)
- [test] Updated tests to include support for latent requests [`095e86a`](https://github.com/http-party/node-http-proxy/commit/095e86aa653c1c8e07cd1403697e0e4b638b8294)
- started to flesh out simple demo based on tests [`2fb5ffb`](https://github.com/http-party/node-http-proxy/commit/2fb5ffba7765462e95badd0f7243e65395a3fd2e)
- added createServer but hated it, gonna remove [`b1eb13e`](https://github.com/http-party/node-http-proxy/commit/b1eb13eb70b67ea76f5ab720d566894677a53ca2)
- [test] Updated node-http-proxy tests [`2f265a2`](https://github.com/http-party/node-http-proxy/commit/2f265a23e4a10971495d0bd7b324b7ba786e5065)
- [api] Updated request hashes to use a unique identifier [`c887a75`](https://github.com/http-party/node-http-proxy/commit/c887a757623f5a3d7d1e0fafeb00b96731c89872)
- [api] Updated http-proxy to work with vows [`ead7567`](https://github.com/http-party/node-http-proxy/commit/ead7567db8099264a2001fd876cded84bc4f111f)
- [dist] Renamed node-proxy to node-http-proxy, updated package.json [`2f49810`](https://github.com/http-party/node-http-proxy/commit/2f49810ef86f49927991f32ae42605f1118b0c25)
- updating docs, almost there [`6e651f4`](https://github.com/http-party/node-http-proxy/commit/6e651f420f4d1e15dbbf823a8e3b311e9533c805)
- changed api to better reflect nodes api. updated demos, tests, docs [`bde98f4`](https://github.com/http-party/node-http-proxy/commit/bde98f489234fe22f49468011b7e342cd108603f)
- updating docs [`341bbd4`](https://github.com/http-party/node-http-proxy/commit/341bbd404f3fd81e65197b3830c3fa9e544bc1e7)
- fixed npm package, i think. bumped version 0.1.1 [`fca40da`](https://github.com/http-party/node-http-proxy/commit/fca40da694d8df17ed6140265e374c0ceabd1167)
- updated demo [`b622702`](https://github.com/http-party/node-http-proxy/commit/b62270210e7ad3c54fd6b2c86bde9f9942328a67)
- added readme [`d6a2f8a`](https://github.com/http-party/node-http-proxy/commit/d6a2f8aa7dae3f6721b9607a702c68b1ad7fc692)
- [api] Corrected chain of argument passing [`da55777`](https://github.com/http-party/node-http-proxy/commit/da55777a92d100a5ddb7a8267e56ba26bd8c2270)
- updated demo [`e9511ea`](https://github.com/http-party/node-http-proxy/commit/e9511eafdf9ada6a0ce6defb3c5f2299411633b1)
- [deploy] Added package.json [`dce80b9`](https://github.com/http-party/node-http-proxy/commit/dce80b9b4546064da1943e0e396e19b41390588a)
- updated readme [`76d0649`](https://github.com/http-party/node-http-proxy/commit/76d0649abcafd80509af922503c5544e646bcebb)
- update to docs and package.json [`d15bba4`](https://github.com/http-party/node-http-proxy/commit/d15bba4c1d2cbdaf0af27f3adcaa1db9b534d968)
- [minor] Removed eyes dependency [`eaeed83`](https://github.com/http-party/node-http-proxy/commit/eaeed8306d6dc6e1b30223cf6d59cda6d5bb76de)
- merge [`93505a4`](https://github.com/http-party/node-http-proxy/commit/93505a422c688b7f41fdaf304270c893ef4cf09a)
- fixed additional port / server mismatches for new api [`15c18b6`](https://github.com/http-party/node-http-proxy/commit/15c18b612d6cd5a1f3ae46b5590dda1fc586fb35)
- [doc] added nodejitsu.com link to ReadMe. http-proxy is used in our front facing load-balancers. look for bugs...try to improve benchmarks.... ^_^ [`6661753`](https://github.com/http-party/node-http-proxy/commit/6661753f07dcf4e5ae684df4d1709f3c238346c9)
- removed extra self, updated colors requirement, bumped to version 0.1.3 [`9bc5b6f`](https://github.com/http-party/node-http-proxy/commit/9bc5b6f8621fb2a37e84524c3e5b91aab9b45675)
- fixed pathing issue, bumped version 0.1.3 [`ede6490`](https://github.com/http-party/node-http-proxy/commit/ede649037e08b615a8995179f46bc701550354d6)
- updated docs [`07d96bb`](https://github.com/http-party/node-http-proxy/commit/07d96bb8887a7880a21a739e0a8f495698e7e79e)
- updated docs [`1594367`](https://github.com/http-party/node-http-proxy/commit/15943675edef490d9b8732345a750bc5ab1f5d7e)
- updated readme [`fb8c5ab`](https://github.com/http-party/node-http-proxy/commit/fb8c5abd3c2a722c1c18046dcf2fffea4fa7d050)
- updated docs [`17b6c69`](https://github.com/http-party/node-http-proxy/commit/17b6c6998544572300fc9d4faa63af1aee4c3d88)
- updated docs [`c8dd8c4`](https://github.com/http-party/node-http-proxy/commit/c8dd8c4e28e09f25c161980316b259d81d5a4e91)
- updated package.json again [`ddba155`](https://github.com/http-party/node-http-proxy/commit/ddba155377942259554842f37de98c508130fe11)
- initial release v0.1.0, sure to have many updates coming. [`6a1baa2`](https://github.com/http-party/node-http-proxy/commit/6a1baa25ccf9fc3a3fc4d1a4764c968993e48cab)
- bumped to version 0.1.5 [`b195a16`](https://github.com/http-party/node-http-proxy/commit/b195a16406534912161671448a53d6633a1f2458)
- updated readme [`9aa2216`](https://github.com/http-party/node-http-proxy/commit/9aa22162f139ab2fa6df6b11e2a96336ee1d2612)
- added spark demo [`d408e39`](https://github.com/http-party/node-http-proxy/commit/d408e39ed6dbd44709d0164a95ad9bc67f76ba13)
- bumped to version 0.1.4. improved on api [`82b8228`](https://github.com/http-party/node-http-proxy/commit/82b822827d35a54501068f9880111473e19c72f9)
- initial release v0.1.0, sure to have many updates coming. [`1e04552`](https://github.com/http-party/node-http-proxy/commit/1e04552bd8f39e3dcba36bbf7fb36674e5c0c9ff)
- updated readme [`0a2eaaa`](https://github.com/http-party/node-http-proxy/commit/0a2eaaa7db690f86aca8c0b952f745e806ad818c)
- updating docs [`198000f`](https://github.com/http-party/node-http-proxy/commit/198000feefd525125a2031557b3556978a057bde)
- [api] Added createServer api to node-http-proxy [`2e2b55f`](https://github.com/http-party/node-http-proxy/commit/2e2b55f113eb3bc81c43717c0db5de695fb694c1)


---

# Contributor Covenant Code of Conduct

## Our Pledge

In the interest of fostering an open and welcoming environment, we as
contributors and maintainers pledge to making participation in our project and
our community a harassment-free experience for everyone, regardless of age, body
size, disability, ethnicity, gender identity and expression, level of experience,
nationality, personal appearance, race, religion, or sexual identity and
orientation.

## Our Standards

Examples of behavior that contributes to creating a positive environment
include:

* Using welcoming and inclusive language
* Being respectful of differing viewpoints and experiences
* Gracefully accepting constructive criticism
* Focusing on what is best for the community
* Showing empathy towards other community members

Examples of unacceptable behavior by participants include:

* The use of sexualized language or imagery and unwelcome sexual attention or
advances
* Trolling, insulting/derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or electronic
  address, without explicit permission
* Other conduct which could reasonably be considered inappropriate in a
  professional setting

## Our Responsibilities

Project maintainers are responsible for clarifying the standards of acceptable
behavior and are expected to take appropriate and fair corrective action in
response to any instances of unacceptable behavior.

Project maintainers have the right and responsibility to remove, edit, or
reject comments, commits, code, wiki edits, issues, and other contributions
that are not aligned to this Code of Conduct, or to ban temporarily or
permanently any contributor for other behaviors that they deem inappropriate,
threatening, offensive, or harmful.

## Scope

This Code of Conduct applies both within project spaces and in public spaces
when an individual is representing the project or its community. Examples of
representing a project or community include using an official project e-mail
address, posting via an official social media account, or acting as an appointed
representative at an online or offline event. Representation of a project may be
further defined and clarified by project maintainers.

## Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported by contacting the project team at <https://github.com/http-party/node-http-proxy>. All
complaints will be reviewed and investigated and will result in a response that
is deemed necessary and appropriate to the circumstances. The project team is
obligated to maintain confidentiality with regard to the reporter of an incident.
Further details of specific enforcement policies may be posted separately.

Project maintainers who do not follow or enforce the Code of Conduct in good
faith may face temporary or permanent repercussions as determined by other
members of the project's leadership.

## Attribution

This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
available at [http://contributor-covenant.org/version/1/4][version]

[homepage]: http://contributor-covenant.org
[version]: http://contributor-covenant.org/version/1/4/


---

<p align="center">
  <img src="https://raw.github.com/http-party/node-http-proxy/master/doc/logo.png"/>
</p>

# node-http-proxy [![Build Status](https://travis-ci.org/http-party/node-http-proxy.svg?branch=master)](https://travis-ci.org/http-party/node-http-proxy) [![codecov](https://codecov.io/gh/http-party/node-http-proxy/branch/master/graph/badge.svg)](https://codecov.io/gh/http-party/node-http-proxy)

`node-http-proxy` is an HTTP programmable proxying library that supports
websockets. It is suitable for implementing components such as reverse
proxies and load balancers.

### Table of Contents
  * [Installation](#installation)
  * [Upgrading from 0.8.x ?](#upgrading-from-08x-)
  * [Core Concept](#core-concept)
  * [Use Cases](#use-cases)
    * [Setup a basic stand-alone proxy server](#setup-a-basic-stand-alone-proxy-server)
    * [Setup a stand-alone proxy server with custom server logic](#setup-a-stand-alone-proxy-server-with-custom-server-logic)
    * [Setup a stand-alone proxy server with proxy request header re-writing](#setup-a-stand-alone-proxy-server-with-proxy-request-header-re-writing)
    * [Modify a response from a proxied server](#modify-a-response-from-a-proxied-server)
    * [Setup a stand-alone proxy server with latency](#setup-a-stand-alone-proxy-server-with-latency)
    * [Using HTTPS](#using-https)
    * [Proxying WebSockets](#proxying-websockets)
  * [Options](#options)
  * [Listening for proxy events](#listening-for-proxy-events)
  * [Shutdown](#shutdown)
  * [Miscellaneous](#miscellaneous)
    * [Test](#test)
    * [ProxyTable API](#proxytable-api)
    * [Logo](#logo)
  * [Contributing and Issues](#contributing-and-issues)
  * [License](#license)

### Installation

`npm install http-proxy --save`

**[Back to top](#table-of-contents)**

### Upgrading from 0.8.x ?

Click [here](UPGRADING.md)

**[Back to top](#table-of-contents)**

### Core Concept

A new proxy is created by calling `createProxyServer` and passing
an `options` object as argument ([valid properties are available here](lib/http-proxy.js#L26-L42))

```javascript
var httpProxy = require('http-proxy');

var proxy = httpProxy.createProxyServer(options); // See (†)
```
†Unless listen(..) is invoked on the object, this does not create a webserver. See below.

An object will be returned with four methods:

* web `req, res, [options]` (used for proxying regular HTTP(S) requests)
* ws `req, socket, head, [options]` (used for proxying WS(S) requests)
* listen `port` (a function that wraps the object in a webserver, for your convenience)
* close `[callback]` (a function that closes the inner webserver and stops listening on given port)

It is then possible to proxy requests by calling these functions

```javascript
http.createServer(function(req, res) {
  proxy.web(req, res, { target: 'http://mytarget.com:8080' });
});
```

Errors can be listened on either using the Event Emitter API

```javascript
proxy.on('error', function(e) {
  ...
});
```

or using the callback API

```javascript
proxy.web(req, res, { target: 'http://mytarget.com:8080' }, function(e) { ... });
```

When a request is proxied it follows two different pipelines ([available here](lib/http-proxy/passes))
which apply transformations to both the `req` and `res` object.
The first pipeline (incoming) is responsible for the creation and manipulation of the stream that connects your client to the target.
The second pipeline (outgoing) is responsible for the creation and manipulation of the stream that, from your target, returns data
to the client.

**[Back to top](#table-of-contents)**

### Use Cases

#### Setup a basic stand-alone proxy server

```js
var http = require('http'),
    httpProxy = require('http-proxy');
//
// Create your proxy server and set the target in the options.
//
httpProxy.createProxyServer({target:'http://localhost:9000'}).listen(8000); // See (†)

//
// Create your target server
//
http.createServer(function (req, res) {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.write('request successfully proxied!' + '\n' + JSON.stringify(req.headers, true, 2));
  res.end();
}).listen(9000);
```
†Invoking listen(..) triggers the creation of a web server. Otherwise, just the proxy instance is created.

**[Back to top](#table-of-contents)**

#### Setup a stand-alone proxy server with custom server logic
This example shows how you can proxy a request using your own HTTP server
and also you can put your own logic to handle the request.

```js
var http = require('http'),
    httpProxy = require('http-proxy');

//
// Create a proxy server with custom application logic
//
var proxy = httpProxy.createProxyServer({});

//
// Create your custom server and just call `proxy.web()` to proxy
// a web request to the target passed in the options
// also you can use `proxy.ws()` to proxy a websockets request
//
var server = http.createServer(function(req, res) {
  // You can define here your custom logic to handle the request
  // and then proxy the request.
  proxy.web(req, res, { target: 'http://127.0.0.1:5050' });
});

console.log("listening on port 5050")
server.listen(5050);
```

**[Back to top](#table-of-contents)**

#### Setup a stand-alone proxy server with proxy request header re-writing
This example shows how you can proxy a request using your own HTTP server that
modifies the outgoing proxy request by adding a special header.

```js
var http = require('http'),
    httpProxy = require('http-proxy');

//
// Create a proxy server with custom application logic
//
var proxy = httpProxy.createProxyServer({});

// To modify the proxy connection before data is sent, you can listen
// for the 'proxyReq' event. When the event is fired, you will receive
// the following arguments:
// (http.ClientRequest proxyReq, http.IncomingMessage req,
//  http.ServerResponse res, Object options). This mechanism is useful when
// you need to modify the proxy request before the proxy connection
// is made to the target.
//
proxy.on('proxyReq', function(proxyReq, req, res, options) {
  proxyReq.setHeader('X-Special-Proxy-Header', 'foobar');
});

var server = http.createServer(function(req, res) {
  // You can define here your custom logic to handle the request
  // and then proxy the request.
  proxy.web(req, res, {
    target: 'http://127.0.0.1:5050'
  });
});

console.log("listening on port 5050")
server.listen(5050);
```

**[Back to top](#table-of-contents)**

#### Modify a response from a proxied server
Sometimes when you have received a HTML/XML document from the server of origin you would like to modify it before forwarding it on.

[Harmon](https://github.com/No9/harmon) allows you to do this in a streaming style so as to keep the pressure on the proxy to a minimum.

**[Back to top](#table-of-contents)**

#### Setup a stand-alone proxy server with latency

```js
var http = require('http'),
    httpProxy = require('http-proxy');

//
// Create a proxy server with latency
//
var proxy = httpProxy.createProxyServer();

//
// Create your server that makes an operation that waits a while
// and then proxies the request
//
http.createServer(function (req, res) {
  // This simulates an operation that takes 500ms to execute
  setTimeout(function () {
    proxy.web(req, res, {
      target: 'http://localhost:9008'
    });
  }, 500);
}).listen(8008);

//
// Create your target server
//
http.createServer(function (req, res) {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.write('request successfully proxied to: ' + req.url + '\n' + JSON.stringify(req.headers, true, 2));
  res.end();
}).listen(9008);
```

**[Back to top](#table-of-contents)**

#### Using HTTPS
You can activate the validation of a secure SSL certificate to the target connection (avoid self-signed certs), just set `secure: true` in the options.

##### HTTPS -> HTTP

```js
//
// Create the HTTPS proxy server in front of a HTTP server
//
httpProxy.createServer({
  target: {
    host: 'localhost',
    port: 9009
  },
  ssl: {
    key: fs.readFileSync('valid-ssl-key.pem', 'utf8'),
    cert: fs.readFileSync('valid-ssl-cert.pem', 'utf8')
  }
}).listen(8009);
```

##### HTTPS -> HTTPS

```js
//
// Create the proxy server listening on port 443
//
httpProxy.createServer({
  ssl: {
    key: fs.readFileSync('valid-ssl-key.pem', 'utf8'),
    cert: fs.readFileSync('valid-ssl-cert.pem', 'utf8')
  },
  target: 'https://localhost:9010',
  secure: true // Depends on your needs, could be false.
}).listen(443);
```

##### HTTP -> HTTPS (using a PKCS12 client certificate)

```js
//
// Create an HTTP proxy server with an HTTPS target
//
httpProxy.createProxyServer({
  target: {
    protocol: 'https:',
    host: 'my-domain-name',
    port: 443,
    pfx: fs.readFileSync('path/to/certificate.p12'),
    passphrase: 'password',
  },
  changeOrigin: true,
}).listen(8000);
```

**[Back to top](#table-of-contents)**

#### Proxying WebSockets
You can activate the websocket support for the proxy using `ws:true` in the options.

```js
//
// Create a proxy server for websockets
//
httpProxy.createServer({
  target: 'ws://localhost:9014',
  ws: true
}).listen(8014);
```

Also you can proxy the websocket requests just calling the `ws(req, socket, head)` method.

```js
//
// Setup our server to proxy standard HTTP requests
//
var proxy = new httpProxy.createProxyServer({
  target: {
    host: 'localhost',
    port: 9015
  }
});
var proxyServer = http.createServer(function (req, res) {
  proxy.web(req, res);
});

//
// Listen to the `upgrade` event and proxy the
// WebSocket requests as well.
//
proxyServer.on('upgrade', function (req, socket, head) {
  proxy.ws(req, socket, head);
});

proxyServer.listen(8015);
```

**[Back to top](#table-of-contents)**

### Options

`httpProxy.createProxyServer` supports the following options:

*  **target**: url string to be parsed with the url module
*  **forward**: url string to be parsed with the url module
*  **agent**: object to be passed to http(s).request (see Node's [https agent](http://nodejs.org/api/https.html#https_class_https_agent) and [http agent](http://nodejs.org/api/http.html#http_class_http_agent) objects)
*  **ssl**: object to be passed to https.createServer()
*  **ws**: true/false, if you want to proxy websockets
*  **xfwd**: true/false, adds x-forward headers
*  **secure**: true/false, if you want to verify the SSL Certs
*  **toProxy**: true/false, passes the absolute URL as the `path` (useful for proxying to proxies)
*  **prependPath**: true/false, Default: true - specify whether you want to prepend the target's path to the proxy path
*  **ignorePath**: true/false, Default: false - specify whether you want to ignore the proxy path of the incoming request (note: you will have to append / manually if required).
*  **localAddress**: Local interface string to bind for outgoing connections
*  **changeOrigin**: true/false, Default: false - changes the origin of the host header to the target URL
*  **preserveHeaderKeyCase**: true/false, Default: false - specify whether you want to keep letter case of response header key
*  **auth**: Basic authentication i.e. 'user:password' to compute an Authorization header.
*  **hostRewrite**: rewrites the location hostname on (201/301/302/307/308) redirects.
*  **autoRewrite**: rewrites the location host/port on (201/301/302/307/308) redirects based on requested host/port. Default: false.
*  **protocolRewrite**: rewrites the location protocol on (201/301/302/307/308) redirects to 'http' or 'https'. Default: null.
*  **cookieDomainRewrite**: rewrites domain of `set-cookie` headers. Possible values:
   * `false` (default): disable cookie rewriting
   * String: new domain, for example `cookieDomainRewrite: "new.domain"`. To remove the domain, use `cookieDomainRewrite: ""`.
   * Object: mapping of domains to new domains, use `"*"` to match all domains.
     For example keep one domain unchanged, rewrite one domain and remove other domains:
     ```
     cookieDomainRewrite: {
       "unchanged.domain": "unchanged.domain",
       "old.domain": "new.domain",
       "*": ""
     }
     ```
*  **cookiePathRewrite**: rewrites path of `set-cookie` headers. Possible values:
   * `false` (default): disable cookie rewriting
   * String: new path, for example `cookiePathRewrite: "/newPath/"`. To remove the path, use `cookiePathRewrite: ""`. To set path to root use `cookiePathRewrite: "/"`.
   * Object: mapping of paths to new paths, use `"*"` to match all paths.
     For example, to keep one path unchanged, rewrite one path and remove other paths:
     ```
     cookiePathRewrite: {
       "/unchanged.path/": "/unchanged.path/",
       "/old.path/": "/new.path/",
       "*": ""
     }
     ```
*  **headers**: object with extra headers to be added to target requests.
*  **proxyTimeout**: timeout (in millis) for outgoing proxy requests
*  **timeout**: timeout (in millis) for incoming requests
*  **followRedirects**: true/false, Default: false - specify whether you want to follow redirects
*  **selfHandleResponse** true/false, if set to true, none of the webOutgoing passes are called and it's your responsibility to appropriately return the response by listening and acting on the `proxyRes` event
*  **buffer**: stream of data to send as the request body.  Maybe you have some middleware that consumes the request stream before proxying it on e.g.  If you read the body of a request into a field called 'req.rawbody' you could restream this field in the buffer option:

    ```
    'use strict';

    const streamify = require('stream-array');
    const HttpProxy = require('http-proxy');
    const proxy = new HttpProxy();

    module.exports = (req, res, next) => {

      proxy.web(req, res, {
        target: 'http://localhost:4003/',
        buffer: streamify(req.rawBody)
      }, next);

    };
    ```

**NOTE:**
`options.ws` and `options.ssl` are optional.
`options.target` and `options.forward` cannot both be missing

If you are using the `proxyServer.listen` method, the following options are also applicable:

 *  **ssl**: object to be passed to https.createServer()
 *  **ws**: true/false, if you want to proxy websockets


**[Back to top](#table-of-contents)**

### Listening for proxy events

* `error`: The error event is emitted if the request to the target fail. **We do not do any error handling of messages passed between client and proxy, and messages passed between proxy and target, so it is recommended that you listen on errors and handle them.**
* `proxyReq`: This event is emitted before the data is sent. It gives you a chance to alter the proxyReq request object. Applies to "web" connections
* `proxyReqWs`: This event is emitted before the data is sent. It gives you a chance to alter the proxyReq request object. Applies to "websocket" connections
* `proxyRes`: This event is emitted if the request to the target got a response.
* `open`: This event is emitted once the proxy websocket was created and piped into the target websocket.
* `close`: This event is emitted once the proxy websocket was closed.
* (DEPRECATED) `proxySocket`: Deprecated in favor of `open`.

```js
var httpProxy = require('http-proxy');
// Error example
//
// Http Proxy Server with bad target
//
var proxy = httpProxy.createServer({
  target:'http://localhost:9005'
});

proxy.listen(8005);

//
// Listen for the `error` event on `proxy`.
proxy.on('error', function (err, req, res) {
  res.writeHead(500, {
    'Content-Type': 'text/plain'
  });

  res.end('Something went wrong. And we are reporting a custom error message.');
});

//
// Listen for the `proxyRes` event on `proxy`.
//
proxy.on('proxyRes', function (proxyRes, req, res) {
  console.log('RAW Response from the target', JSON.stringify(proxyRes.headers, true, 2));
});

//
// Listen for the `open` event on `proxy`.
//
proxy.on('open', function (proxySocket) {
  // listen for messages coming FROM the target here
  proxySocket.on('data', hybiParseAndLogMessage);
});

//
// Listen for the `close` event on `proxy`.
//
proxy.on('close', function (res, socket, head) {
  // view disconnected websocket connections
  console.log('Client disconnected');
});
```

**[Back to top](#table-of-contents)**

### Shutdown

* When testing or running server within another program it may be necessary to close the proxy.
* This will stop the proxy from accepting new connections.

```js
var proxy = new httpProxy.createProxyServer({
  target: {
    host: 'localhost',
    port: 1337
  }
});

proxy.close();
```

**[Back to top](#table-of-contents)**

### Miscellaneous

If you want to handle your own response after receiving the `proxyRes`, you can do
so with `selfHandleResponse`. As you can see below, if you use this option, you
are able to intercept and read the `proxyRes` but you must also make sure to
reply to the `res` itself otherwise the original client will never receive any
data.

### Modify response

```js

    var option = {
      target: target,
      selfHandleResponse : true
    };
    proxy.on('proxyRes', function (proxyRes, req, res) {
        var body = [];
        proxyRes.on('data', function (chunk) {
            body.push(chunk);
        });
        proxyRes.on('end', function () {
            body = Buffer.concat(body).toString();
            console.log("res from proxied server:", body);
            res.end("my response to cli");
        });
    });
    proxy.web(req, res, option);


```

#### ProxyTable API

A proxy table API is available through this add-on [module](https://github.com/donasaur/http-proxy-rules), which lets you define a set of rules to translate matching routes to target routes that the reverse proxy will talk to.

#### Test

```
$ npm test
```

#### Logo

Logo created by [Diego Pasquali](http://dribbble.com/diegopq)

**[Back to top](#table-of-contents)**

### Contributing and Issues

* Read carefully our [Code Of Conduct](https://github.com/http-party/node-http-proxy/blob/master/CODE_OF_CONDUCT.md)
* Search on Google/Github
* If you can't find anything, open an issue
* If you feel comfortable about fixing the issue, fork the repo
* Commit to your local branch (which must be different from `master`)
* Submit your Pull Request (be sure to include tests and update documentation)

**[Back to top](#table-of-contents)**

### License

>The MIT License (MIT)
>
>Copyright (c) 2010 - 2016 Charlie Robbins, Jarrett Cruger & the Contributors.
>
>Permission is hereby granted, free of charge, to any person obtaining a copy
>of this software and associated documentation files (the "Software"), to deal
>in the Software without restriction, including without limitation the rights
>to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
>copies of the Software, and to permit persons to whom the Software is
>furnished to do so, subject to the following conditions:
>
>The above copyright notice and this permission notice shall be included in
>all copies or substantial portions of the Software.
>
>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
>IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
>FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
>AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
>LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
>OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
>THE SOFTWARE.


---

# http-proxy-middleware

[![GitHub Workflow Status (branch)](https://img.shields.io/github/workflow/status/chimurai/http-proxy-middleware/CI/master?style=flat-square)](https://github.com/chimurai/http-proxy-middleware/actions?query=branch%3Amaster)
[![Coveralls](https://img.shields.io/coveralls/chimurai/http-proxy-middleware.svg?style=flat-square)](https://coveralls.io/r/chimurai/http-proxy-middleware)
[![dependency Status](https://snyk.io/test/npm/http-proxy-middleware/badge.svg?style=flat-square)](https://snyk.io/test/npm/http-proxy-middleware)
[![npm](https://img.shields.io/npm/v/http-proxy-middleware?color=%23CC3534&style=flat-square)](https://www.npmjs.com/package/http-proxy-middleware)

Node.js proxying made simple. Configure proxy middleware with ease for [connect](https://github.com/senchalabs/connect), [express](https://github.com/strongloop/express), [browser-sync](https://github.com/BrowserSync/browser-sync) and [many more](#compatible-servers).

Powered by the popular Nodejitsu [`http-proxy`](https://github.com/nodejitsu/node-http-proxy). [![GitHub stars](https://img.shields.io/github/stars/nodejitsu/node-http-proxy.svg?style=social&label=Star)](https://github.com/nodejitsu/node-http-proxy)

## ⚠️ Note <!-- omit in toc -->

This page is showing documentation for version v2.x.x ([release notes](https://github.com/chimurai/http-proxy-middleware/releases))

If you're looking for v0.x documentation. Go to:
https://github.com/chimurai/http-proxy-middleware/tree/v0.21.0#readme

## TL;DR <!-- omit in toc -->

Proxy `/api` requests to `http://www.example.org`

```javascript
// javascript

const express = require('express');
const { createProxyMiddleware } = require('http-proxy-middleware');

const app = express();

app.use('/api', createProxyMiddleware({ target: 'http://www.example.org', changeOrigin: true }));
app.listen(3000);

// http://localhost:3000/api/foo/bar -> http://www.example.org/api/foo/bar
```

```typescript
// typescript

import * as express from 'express';
import { createProxyMiddleware, Filter, Options, RequestHandler } from 'http-proxy-middleware';

const app = express();

app.use('/api', createProxyMiddleware({ target: 'http://www.example.org', changeOrigin: true }));
app.listen(3000);

// http://localhost:3000/api/foo/bar -> http://www.example.org/api/foo/bar
```

_All_ `http-proxy` [options](https://github.com/nodejitsu/node-http-proxy#options) can be used, along with some extra `http-proxy-middleware` [options](#options).

:bulb: **Tip:** Set the option `changeOrigin` to `true` for [name-based virtual hosted sites](http://en.wikipedia.org/wiki/Virtual_hosting#Name-based).

## Table of Contents <!-- omit in toc -->

- [Install](#install)
- [Core concept](#core-concept)
- [Example](#example)
- [Context matching](#context-matching)
- [Options](#options)
  - [http-proxy-middleware options](#http-proxy-middleware-options)
  - [http-proxy events](#http-proxy-events)
  - [http-proxy options](#http-proxy-options)
- [Shorthand](#shorthand)
  - [app.use(path, proxy)](#appusepath-proxy)
- [WebSocket](#websocket)
  - [External WebSocket upgrade](#external-websocket-upgrade)
- [Intercept and manipulate requests](#intercept-and-manipulate-requests)
- [Intercept and manipulate responses](#intercept-and-manipulate-responses)
- [Working examples](#working-examples)
- [Recipes](#recipes)
- [Compatible servers](#compatible-servers)
- [Tests](#tests)
- [Changelog](#changelog)
- [License](#license)

## Install

```bash
$ npm install --save-dev http-proxy-middleware
```

## Core concept

Proxy middleware configuration.

#### createProxyMiddleware([context,] config)

```javascript
const { createProxyMiddleware } = require('http-proxy-middleware');

const apiProxy = createProxyMiddleware('/api', { target: 'http://www.example.org' });
//                                    \____/   \_____________________________/
//                                      |                    |
//                                    context             options

// 'apiProxy' is now ready to be used as middleware in a server.
```

- **context**: Determine which requests should be proxied to the target host.
  (more on [context matching](#context-matching))
- **options.target**: target host to proxy to. _(protocol + host)_

(full list of [`http-proxy-middleware` configuration options](#options))

#### createProxyMiddleware(uri [, config])

```javascript
// shorthand syntax for the example above:
const apiProxy = createProxyMiddleware('http://www.example.org/api');
```

More about the [shorthand configuration](#shorthand).

## Example

An example with `express` server.

```javascript
// include dependencies
const express = require('express');
const { createProxyMiddleware } = require('http-proxy-middleware');

// proxy middleware options
/** @type {import('http-proxy-middleware/dist/types').Options} */
const options = {
  target: 'http://www.example.org', // target host
  changeOrigin: true, // needed for virtual hosted sites
  ws: true, // proxy websockets
  pathRewrite: {
    '^/api/old-path': '/api/new-path', // rewrite path
    '^/api/remove/path': '/path', // remove base path
  },
  router: {
    // when request.headers.host == 'dev.localhost:3000',
    // override target 'http://www.example.org' to 'http://localhost:8000'
    'dev.localhost:3000': 'http://localhost:8000',
  },
};

// create the proxy (without context)
const exampleProxy = createProxyMiddleware(options);

// mount `exampleProxy` in web server
const app = express();
app.use('/api', exampleProxy);
app.listen(3000);
```

## Context matching

Providing an alternative way to decide which requests should be proxied; In case you are not able to use the server's [`path` parameter](http://expressjs.com/en/4x/api.html#app.use) to mount the proxy or when you need more flexibility.

[RFC 3986 `path`](https://tools.ietf.org/html/rfc3986#section-3.3) is used for context matching.

```ascii
         foo://example.com:8042/over/there?name=ferret#nose
         \_/   \______________/\_________/ \_________/ \__/
          |           |            |            |        |
       scheme     authority       path        query   fragment
```

- **path matching**

  - `createProxyMiddleware({...})` - matches any path, all requests will be proxied.
  - `createProxyMiddleware('/', {...})` - matches any path, all requests will be proxied.
  - `createProxyMiddleware('/api', {...})` - matches paths starting with `/api`

- **multiple path matching**

  - `createProxyMiddleware(['/api', '/ajax', '/someotherpath'], {...})`

- **wildcard path matching**

  For fine-grained control you can use wildcard matching. Glob pattern matching is done by _micromatch_. Visit [micromatch](https://www.npmjs.com/package/micromatch) or [glob](https://www.npmjs.com/package/glob) for more globbing examples.

  - `createProxyMiddleware('**', {...})` matches any path, all requests will be proxied.
  - `createProxyMiddleware('**/*.html', {...})` matches any path which ends with `.html`
  - `createProxyMiddleware('/*.html', {...})` matches paths directly under path-absolute
  - `createProxyMiddleware('/api/**/*.html', {...})` matches requests ending with `.html` in the path of `/api`
  - `createProxyMiddleware(['/api/**', '/ajax/**'], {...})` combine multiple patterns
  - `createProxyMiddleware(['/api/**', '!**/bad.json'], {...})` exclusion

  **Note**: In multiple path matching, you cannot use string paths and wildcard paths together.

- **custom matching**

  For full control you can provide a custom function to determine which requests should be proxied or not.

  ```javascript
  /**
   * @return {Boolean}
   */
  const filter = function (pathname, req) {
    return pathname.match('^/api') && req.method === 'GET';
  };

  const apiProxy = createProxyMiddleware(filter, {
    target: 'http://www.example.org',
  });
  ```

## Options

### http-proxy-middleware options

- **option.pathRewrite**: object/function, rewrite target's url path. Object-keys will be used as _RegExp_ to match paths.

  ```javascript
  // rewrite path
  pathRewrite: {'^/old/api' : '/new/api'}

  // remove path
  pathRewrite: {'^/remove/api' : ''}

  // add base path
  pathRewrite: {'^/' : '/basepath/'}

  // custom rewriting
  pathRewrite: function (path, req) { return path.replace('/api', '/base/api') }

  // custom rewriting, returning Promise
  pathRewrite: async function (path, req) {
    const should_add_something = await httpRequestToDecideSomething(path);
    if (should_add_something) path += "something";
    return path;
  }
  ```

- **option.router**: object/function, re-target `option.target` for specific requests.

  ```javascript
  // Use `host` and/or `path` to match requests. First match will be used.
  // The order of the configuration matters.
  router: {
      'integration.localhost:3000' : 'http://localhost:8001',  // host only
      'staging.localhost:3000'     : 'http://localhost:8002',  // host only
      'localhost:3000/api'         : 'http://localhost:8003',  // host + path
      '/rest'                      : 'http://localhost:8004'   // path only
  }

  // Custom router function (string target)
  router: function(req) {
      return 'http://localhost:8004';
  }

  // Custom router function (target object)
  router: function(req) {
      return {
          protocol: 'https:', // The : is required
          host: 'localhost',
          port: 8004
      };
  }

  // Asynchronous router function which returns promise
  router: async function(req) {
      const url = await doSomeIO();
      return url;
  }
  ```

- **option.logLevel**: string, ['debug', 'info', 'warn', 'error', 'silent']. Default: `'info'`

- **option.logProvider**: function, modify or replace log provider. Default: `console`.

  ```javascript
  // simple replace
  function logProvider(provider) {
    // replace the default console log provider.
    return require('winston');
  }
  ```

  ```javascript
  // verbose replacement
  function logProvider(provider) {
    const logger = new (require('winston').Logger)();

    const myCustomProvider = {
      log: logger.log,
      debug: logger.debug,
      info: logger.info,
      warn: logger.warn,
      error: logger.error,
    };
    return myCustomProvider;
  }
  ```

### http-proxy events

Subscribe to [http-proxy events](https://github.com/nodejitsu/node-http-proxy#listening-for-proxy-events):

- **option.onError**: function, subscribe to http-proxy's `error` event for custom error handling.

  ```javascript
  function onError(err, req, res, target) {
    res.writeHead(500, {
      'Content-Type': 'text/plain',
    });
    res.end('Something went wrong. And we are reporting a custom error message.');
  }
  ```

- **option.onProxyRes**: function, subscribe to http-proxy's `proxyRes` event.

  ```javascript
  function onProxyRes(proxyRes, req, res) {
    proxyRes.headers['x-added'] = 'foobar'; // add new header to response
    delete proxyRes.headers['x-removed']; // remove header from response
  }
  ```

- **option.onProxyReq**: function, subscribe to http-proxy's `proxyReq` event.

  ```javascript
  function onProxyReq(proxyReq, req, res) {
    // add custom header to request
    proxyReq.setHeader('x-added', 'foobar');
    // or log the req
  }
  ```

- **option.onProxyReqWs**: function, subscribe to http-proxy's `proxyReqWs` event.

  ```javascript
  function onProxyReqWs(proxyReq, req, socket, options, head) {
    // add custom header
    proxyReq.setHeader('X-Special-Proxy-Header', 'foobar');
  }
  ```

- **option.onOpen**: function, subscribe to http-proxy's `open` event.

  ```javascript
  function onOpen(proxySocket) {
    // listen for messages coming FROM the target here
    proxySocket.on('data', hybridParseAndLogMessage);
  }
  ```

- **option.onClose**: function, subscribe to http-proxy's `close` event.

  ```javascript
  function onClose(res, socket, head) {
    // view disconnected websocket connections
    console.log('Client disconnected');
  }
  ```

### http-proxy options

The following options are provided by the underlying [http-proxy](https://github.com/nodejitsu/node-http-proxy#options) library.

- **option.target**: url string to be parsed with the url module
- **option.forward**: url string to be parsed with the url module
- **option.agent**: object to be passed to http(s).request (see Node's [https agent](http://nodejs.org/api/https.html#https_class_https_agent) and [http agent](http://nodejs.org/api/http.html#http_class_http_agent) objects)
- **option.ssl**: object to be passed to https.createServer()
- **option.ws**: true/false: if you want to proxy websockets
- **option.xfwd**: true/false, adds x-forward headers
- **option.secure**: true/false, if you want to verify the SSL Certs
- **option.toProxy**: true/false, passes the absolute URL as the `path` (useful for proxying to proxies)
- **option.prependPath**: true/false, Default: true - specify whether you want to prepend the target's path to the proxy path
- **option.ignorePath**: true/false, Default: false - specify whether you want to ignore the proxy path of the incoming request (note: you will have to append / manually if required).
- **option.localAddress** : Local interface string to bind for outgoing connections
- **option.changeOrigin**: true/false, Default: false - changes the origin of the host header to the target URL
- **option.preserveHeaderKeyCase**: true/false, Default: false - specify whether you want to keep letter case of response header key
- **option.auth** : Basic authentication i.e. 'user:password' to compute an Authorization header.
- **option.hostRewrite**: rewrites the location hostname on (301/302/307/308) redirects.
- **option.autoRewrite**: rewrites the location host/port on (301/302/307/308) redirects based on requested host/port. Default: false.
- **option.protocolRewrite**: rewrites the location protocol on (301/302/307/308) redirects to 'http' or 'https'. Default: null.
- **option.cookieDomainRewrite**: rewrites domain of `set-cookie` headers. Possible values:
  - `false` (default): disable cookie rewriting
  - String: new domain, for example `cookieDomainRewrite: "new.domain"`. To remove the domain, use `cookieDomainRewrite: ""`.
  - Object: mapping of domains to new domains, use `"*"` to match all domains.  
    For example keep one domain unchanged, rewrite one domain and remove other domains:
    ```json
    cookieDomainRewrite: {
      "unchanged.domain": "unchanged.domain",
      "old.domain": "new.domain",
      "*": ""
    }
    ```
- **option.cookiePathRewrite**: rewrites path of `set-cookie` headers. Possible values:
  - `false` (default): disable cookie rewriting
  - String: new path, for example `cookiePathRewrite: "/newPath/"`. To remove the path, use `cookiePathRewrite: ""`. To set path to root use `cookiePathRewrite: "/"`.
  - Object: mapping of paths to new paths, use `"*"` to match all paths.
    For example, to keep one path unchanged, rewrite one path and remove other paths:
    ```json
    cookiePathRewrite: {
      "/unchanged.path/": "/unchanged.path/",
      "/old.path/": "/new.path/",
      "*": ""
    }
    ```
- **option.headers**: object, adds [request headers](https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#Request_fields). (Example: `{host:'www.example.org'}`)
- **option.proxyTimeout**: timeout (in millis) when proxy receives no response from target
- **option.timeout**: timeout (in millis) for incoming requests
- **option.followRedirects**: true/false, Default: false - specify whether you want to follow redirects
- **option.selfHandleResponse** true/false, if set to true, none of the webOutgoing passes are called and it's your responsibility to appropriately return the response by listening and acting on the `proxyRes` event
- **option.buffer**: stream of data to send as the request body. Maybe you have some middleware that consumes the request stream before proxying it on e.g. If you read the body of a request into a field called 'req.rawbody' you could restream this field in the buffer option:

  ```javascript
  'use strict';

  const streamify = require('stream-array');
  const HttpProxy = require('http-proxy');
  const proxy = new HttpProxy();

  module.exports = (req, res, next) => {
    proxy.web(
      req,
      res,
      {
        target: 'http://localhost:4003/',
        buffer: streamify(req.rawBody),
      },
      next
    );
  };
  ```

## Shorthand

Use the shorthand syntax when verbose configuration is not needed. The `context` and `option.target` will be automatically configured when shorthand is used. Options can still be used if needed.

```javascript
createProxyMiddleware('http://www.example.org:8000/api');
// createProxyMiddleware('/api', {target: 'http://www.example.org:8000'});

createProxyMiddleware('http://www.example.org:8000/api/books/*/**.json');
// createProxyMiddleware('/api/books/*/**.json', {target: 'http://www.example.org:8000'});

createProxyMiddleware('http://www.example.org:8000/api', { changeOrigin: true });
// createProxyMiddleware('/api', {target: 'http://www.example.org:8000', changeOrigin: true});
```

### app.use(path, proxy)

If you want to use the server's `app.use` `path` parameter to match requests;
Create and mount the proxy without the http-proxy-middleware `context` parameter:

```javascript
app.use('/api', createProxyMiddleware({ target: 'http://www.example.org', changeOrigin: true }));
```

`app.use` documentation:

- express: http://expressjs.com/en/4x/api.html#app.use
- connect: https://github.com/senchalabs/connect#mount-middleware
- polka: https://github.com/lukeed/polka#usebase-fn

## WebSocket

```javascript
// verbose api
createProxyMiddleware('/', { target: 'http://echo.websocket.org', ws: true });

// shorthand
createProxyMiddleware('http://echo.websocket.org', { ws: true });

// shorter shorthand
createProxyMiddleware('ws://echo.websocket.org');
```

### External WebSocket upgrade

In the previous WebSocket examples, http-proxy-middleware relies on a initial http request in order to listen to the http `upgrade` event. If you need to proxy WebSockets without the initial http request, you can subscribe to the server's http `upgrade` event manually.

```javascript
const wsProxy = createProxyMiddleware('ws://echo.websocket.org', { changeOrigin: true });

const app = express();
app.use(wsProxy);

const server = app.listen(3000);
server.on('upgrade', wsProxy.upgrade); // <-- subscribe to http 'upgrade'
```

## Intercept and manipulate requests

Intercept requests from downstream by defining `onProxyReq` in `createProxyMiddleware`.

Currently the only pre-provided request interceptor is `fixRequestBody`, which is used to fix proxied POST requests when `bodyParser` is applied before this middleware.

Example:

```javascript
const { createProxyMiddleware, fixRequestBody } = require('http-proxy-middleware');

const proxy = createProxyMiddleware({
  /**
   * Fix bodyParser
   **/
  onProxyReq: fixRequestBody,
});
```

## Intercept and manipulate responses

Intercept responses from upstream with `responseInterceptor`. (Make sure to set `selfHandleResponse: true`)

Responses which are compressed with `brotli`, `gzip` and `deflate` will be decompressed automatically. The response will be returned as `buffer` ([docs](https://nodejs.org/api/buffer.html)) which you can manipulate.

With `buffer`, response manipulation is not limited to text responses (html/css/js, etc...); image manipulation will be possible too. ([example](https://github.com/chimurai/http-proxy-middleware/blob/master/recipes/response-interceptor.md#manipulate-image-response))

NOTE: `responseInterceptor` disables streaming of target's response.

Example:

```javascript
const { createProxyMiddleware, responseInterceptor } = require('http-proxy-middleware');

const proxy = createProxyMiddleware({
  /**
   * IMPORTANT: avoid res.end being called automatically
   **/
  selfHandleResponse: true, // res.end() will be called internally by responseInterceptor()

  /**
   * Intercept response and replace 'Hello' with 'Goodbye'
   **/
  onProxyRes: responseInterceptor(async (responseBuffer, proxyRes, req, res) => {
    const response = responseBuffer.toString('utf8'); // convert buffer to string
    return response.replace('Hello', 'Goodbye'); // manipulate response and return the result
  }),
});
```

Check out [interception recipes](https://github.com/chimurai/http-proxy-middleware/blob/master/recipes/response-interceptor.md#readme) for more examples.

## Working examples

View and play around with [working examples](https://github.com/chimurai/http-proxy-middleware/tree/master/examples).

- Browser-Sync ([example source](https://github.com/chimurai/http-proxy-middleware/tree/master/examples/browser-sync/index.js))
- express ([example source](https://github.com/chimurai/http-proxy-middleware/tree/master/examples/express/index.js))
- connect ([example source](https://github.com/chimurai/http-proxy-middleware/tree/master/examples/connect/index.js))
- WebSocket ([example source](https://github.com/chimurai/http-proxy-middleware/tree/master/examples/websocket/index.js))
- Response Manipulation ([example source](https://github.com/chimurai/http-proxy-middleware/blob/master/examples/response-interceptor/index.js))

## Recipes

View the [recipes](https://github.com/chimurai/http-proxy-middleware/tree/master/recipes) for common use cases.

## Compatible servers

`http-proxy-middleware` is compatible with the following servers:

- [connect](https://www.npmjs.com/package/connect)
- [express](https://www.npmjs.com/package/express)
- [fastify](https://www.npmjs.com/package/fastify)
- [browser-sync](https://www.npmjs.com/package/browser-sync)
- [lite-server](https://www.npmjs.com/package/lite-server)
- [polka](https://github.com/lukeed/polka)
- [grunt-contrib-connect](https://www.npmjs.com/package/grunt-contrib-connect)
- [grunt-browser-sync](https://www.npmjs.com/package/grunt-browser-sync)
- [gulp-connect](https://www.npmjs.com/package/gulp-connect)
- [gulp-webserver](https://www.npmjs.com/package/gulp-webserver)

Sample implementations can be found in the [server recipes](https://github.com/chimurai/http-proxy-middleware/tree/master/recipes/servers.md).

## Tests

Run the test suite:

```bash
# install dependencies
$ yarn

# linting
$ yarn lint
$ yarn lint:fix

# building (compile typescript to js)
$ yarn build

# unit tests
$ yarn test

# code coverage
$ yarn cover

# check spelling mistakes
$ yarn spellcheck
```

## Changelog

- [View changelog](https://github.com/chimurai/http-proxy-middleware/blob/master/CHANGELOG.md)

## License

The MIT License (MIT)

Copyright (c) 2015-2022 Steven Chim


---

# is-plain-obj [![Build Status](https://travis-ci.com/sindresorhus/is-plain-obj.svg?branch=master)](https://travis-ci.com/github/sindresorhus/is-plain-obj)

> Check if a value is a plain object

An object is plain if it's created by either `{}`, `new Object()`, or `Object.create(null)`.

## Install

```
$ npm install is-plain-obj
```

## Usage

```js
const isPlainObject = require('is-plain-obj');

isPlainObject({foo: 'bar'});
//=> true

isPlainObject(new Object());
//=> true

isPlainObject(Object.create(null));
//=> true

isPlainObject([1, 2, 3]);
//=> false

class Unicorn {}
isPlainObject(new Unicorn());
//=> false
```

## Related

- [is-obj](https://github.com/sindresorhus/is-obj) - Check if a value is an object
- [is](https://github.com/sindresorhus/is) - Type check values


---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-is-plain-obj?utm_source=npm-is-plain-obj&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

# http2-wrapper
> HTTP/2 client, just with the familiar `https` API

[![Node CI](https://github.com/szmarczak/http2-wrapper/workflows/Node%20CI/badge.svg)](https://github.com/szmarczak/http2-wrapper/actions)
[![codecov](https://codecov.io/gh/szmarczak/http2-wrapper/branch/master/graph/badge.svg)](https://codecov.io/gh/szmarczak/http2-wrapper)
[![npm](https://img.shields.io/npm/dm/http2-wrapper.svg)](https://www.npmjs.com/package/http2-wrapper)
[![install size](https://packagephobia.now.sh/badge?p=http2-wrapper)](https://packagephobia.now.sh/result?p=http2-wrapper)

This package was created to support HTTP/2 without the need to rewrite your code.<br>
I recommend adapting to the [`http2`](https://nodejs.org/api/http2.html) module if possible - it's much simpler to use and has many cool features!

**Tip**: `http2-wrapper` is very useful when you rely on other modules that use the HTTP/1 API and you want to support HTTP/2.

**Pro Tip**: While the native `http2` doesn't have agents yet, you can use `http2-wrapper` Agents and still operate on the native HTTP/2 streams.

## Installation

> `$ npm install http2-wrapper`<br>
> `$ yarn add http2-wrapper`

## Usage

```js
const http2 = require('http2-wrapper');

const options = {
	hostname: 'nghttp2.org',
	protocol: 'https:',
	path: '/httpbin/post',
	method: 'POST',
	headers: {
		'content-length': 6
	}
};

const request = http2.request(options, response => {
	console.log('statusCode:', response.statusCode);
	console.log('headers:', response.headers);

	const body = [];
	response.on('data', chunk => {
		body.push(chunk);
	});
	response.on('end', () => {
		console.log('body:', Buffer.concat(body).toString());
	});
});

request.on('error', console.error);

request.write('123');
request.end('456');

// statusCode: 200
// headers: [Object: null prototype] {
//   ':status': 200,
//   date: 'Fri, 27 Sep 2019 19:45:46 GMT',
//   'content-type': 'application/json',
//   'access-control-allow-origin': '*',
//   'access-control-allow-credentials': 'true',
//   'content-length': '239',
//   'x-backend-header-rtt': '0.002516',
//   'strict-transport-security': 'max-age=31536000',
//   server: 'nghttpx',
//   via: '1.1 nghttpx',
//   'alt-svc': 'h3-23=":4433"; ma=3600',
//   'x-frame-options': 'SAMEORIGIN',
//   'x-xss-protection': '1; mode=block',
//   'x-content-type-options': 'nosniff'
// }
// body: {
//   "args": {},
//   "data": "123456",
//   "files": {},
//   "form": {},
//   "headers": {
//     "Content-Length": "6",
//     "Host": "nghttp2.org"
//   },
//   "json": 123456,
//   "origin": "xxx.xxx.xxx.xxx",
//   "url": "https://nghttp2.org/httpbin/post"
// }
```

## API

**Note:** The `session` option was renamed to `tlsSession` for better readability.

**Note:** The `timeout` option applies to HTTP/2 streams only. In order to set session timeout, pass an Agent with custom `timeout` option set.

### http2.auto(url, options, callback)

Performs [ALPN](https://nodejs.org/api/tls.html#tls_alpn_and_sni) negotiation.
Returns a Promise giving proper `ClientRequest` instance (depending on the ALPN).

**Note**: The `agent` option represents an object with `http`, `https` and `http2` properties.

```js
const http2 = require('http2-wrapper');

const options = {
	hostname: 'httpbin.org',
	protocol: 'http:', // Try changing this to https:
	path: '/post',
	method: 'POST',
	headers: {
		'content-length': 6
	}
};

(async () => {
	try {
		const request = await http2.auto(options, response => {
			console.log('statusCode:', response.statusCode);
			console.log('headers:', response.headers);

			const body = [];
			response.on('data', chunk => body.push(chunk));
			response.on('end', () => {
				console.log('body:', Buffer.concat(body).toString());
			});
		});

		request.on('error', console.error);

		request.write('123');
		request.end('456');
	} catch (error) {
		console.error(error);
	}
})();

// statusCode: 200
// headers: { connection: 'close',
//   server: 'gunicorn/19.9.0',
//   date: 'Sat, 15 Dec 2018 18:19:32 GMT',
//   'content-type': 'application/json',
//   'content-length': '259',
//   'access-control-allow-origin': '*',
//   'access-control-allow-credentials': 'true',
//   via: '1.1 vegur' }
// body: {
//   "args": {},
//   "data": "123456",
//   "files": {},
//   "form": {},
//   "headers": {
//     "Connection": "close",
//     "Content-Length": "6",
//     "Host": "httpbin.org"
//   },
//   "json": 123456,
//   "origin": "xxx.xxx.xxx.xxx",
//   "url": "http://httpbin.org/post"
// }
```

### http2.auto.protocolCache

An instance of [`quick-lru`](https://github.com/sindresorhus/quick-lru) used for ALPN cache.

There is a maximum of 100 entries. You can modify the limit through `protocolCache.maxSize` - note that the change will be visible globally.

### http2.auto.createResolveProtocol(cache, queue, connect)

#### cache

Type: `Map<string, string>`

This is the store where cached ALPN protocols are put into.

#### queue

Type: `Map<string, Promise>`

This is the store that contains pending ALPN negotiation promises.

#### connect

Type: `(options, callback) => TLSSocket | Promise<TLSSocket>`

See https://github.com/szmarczak/resolve-alpn#connect

### http2.auto.resolveProtocol(options)

Returns a `Promise<{alpnProtocol: string}>`.

### http2.request(url, options, callback)

Same as [`https.request`](https://nodejs.org/api/https.html#https_https_request_options_callback).

##### options.h2session

Type: `Http2Session`<br>

The session used to make the actual request. If none provided, it will use `options.agent` to get one.

### http2.get(url, options, callback)

Same as [`https.get`](https://nodejs.org/api/https.html#https_https_get_options_callback).

### new http2.ClientRequest(url, options, callback)

Same as [`https.ClientRequest`](https://nodejs.org/api/https.html#https_class_https_clientrequest).

### new http2.IncomingMessage(socket)

Same as [`https.IncomingMessage`](https://nodejs.org/api/https.html#https_class_https_incomingmessage).

### new http2.Agent(options)

**Note:** this is **not** compatible with the classic `http.Agent`.

Usage example:

```js
const http2 = require('http2-wrapper');

class MyAgent extends http2.Agent {
	createConnection(origin, options) {
		console.log(`Connecting to ${http2.Agent.normalizeOrigin(origin)}`);
		return http2.Agent.connect(origin, options);
	}
}

http2.get({
	hostname: 'google.com',
	agent: new MyAgent()
}, response => {
	response.on('data', chunk => console.log(`Received chunk of ${chunk.length} bytes`));
});
```

#### options

Each option is an `Agent` property and can be changed later.

##### timeout

Type: `number`<br>
Default: `0`

If there's no activity after `timeout` milliseconds, the session will be closed. If `0`, no timeout is applied.

##### maxSessions

Type: `number`<br>
Default: `Infinity`

The maximum amount of sessions in total.

##### maxEmptySessions

Type: `number`<br>
Default: `10`

The maximum amount of empty sessions in total. An empty session is a session with no pending requests.

##### maxCachedTlsSessions

Type: `number`<br>
Default: `100`

The maximum amount of cached TLS sessions.

#### agent.protocol

Type: `string`<br>
Default: `https:`

#### agent.settings

Type: `object`<br>
Default: `{enablePush: false}`

[Settings](https://nodejs.org/api/http2.html#http2_settings_object) used by the current agent instance.

#### agent.normalizeOptions([options](https://github.com/szmarczak/http2-wrapper/blob/master/source/agent.js))

Returns a string representing normalized options.

```js
Agent.normalizeOptions({servername: 'example.com'});
// => ':::::::::::::::::::::::::::::::::::::'
```

#### agent.getSession(origin, options)

##### [origin](https://nodejs.org/api/http2.html#http2_http2_connect_authority_options_listener)

Type: `string` `URL` `object`

Origin used to create new session.

##### [options](https://nodejs.org/api/http2.html#http2_http2_connect_authority_options_listener)

Type: `object`

Options used to create new session.

Returns a Promise giving free `Http2Session`. If no free sessions are found, a new one is created.

A session is considered free when pending streams count is less than max concurrent streams settings.

#### agent.getSession([origin](#origin), [options](options-1), listener)

##### listener

Type: `object`

```
{
	reject: error => void,
	resolve: session => void
}
```

If the `listener` argument is present, the Promise will resolve immediately. It will use the `resolve` function to pass the session.

#### agent.request([origin](#origin), [options](#options-1), [headers](https://nodejs.org/api/http2.html#http2_headers_object), [streamOptions](https://nodejs.org/api/http2.html#http2_clienthttp2session_request_headers_options))

Returns a Promise giving `Http2Stream`.

#### agent.createConnection([origin](#origin), [options](#options-1))

Returns a new `TLSSocket`. It defaults to `Agent.connect(origin, options)`.

#### agent.closeEmptySessions(count)

##### count

Type: `number`
Default: `Number.POSITIVE_INFINITY`

Makes an attempt to close empty sessions. Only sessions with 0 concurrent streams will be closed.

#### agent.destroy(reason)

Destroys **all** sessions.

#### agent.emptySessionCount

Type: `number`

A number of empty sessions.

#### agent.pendingSessionCount

Type: `number`

A number of pending sessions.

#### agent.sessionCount

Type: `number`

A number of all sessions held by the Agent.

#### Event: 'session'

```js
agent.on('session', session => {
	// A new session has been created by the Agent.
});
```

## Proxy support

Currently `http2-wrapper` provides support for these proxies:

- `HttpOverHttp2`
- `HttpsOverHttp2`
- `Http2OverHttp2`
- `Http2OverHttp`
- `Http2OverHttps`

Any of the above can be accessed via `http2wrapper.proxies`. Check out the [`examples/proxies`](examples/proxies) directory to learn more.

**Note:** If you use the `http2.auto` function, the real IP address will leak. `http2wrapper` is not aware of the context. It will create a connection to the end server using your real IP address to get the ALPN protocol. Then it will create another connection using proxy. To migitate this, you need to pass a custom `resolveProtocol` function as an option:

```js
const resolveAlpnProxy = new URL('https://username:password@localhost:8000');
const connect = async (options, callback) => new Promise((resolve, reject) => {
	const host = `${options.host}:${options.port}`;

	(async () => {
		try {
			const request = await http2.auto(resolveAlpnProxy, {
				method: 'CONNECT',
				headers: {
					host
				},
				path: host,

				// For demo purposes only!
				rejectUnauthorized: false,
			});

			request.end();

			request.once('error', reject);

			request.once('connect', (response, socket, head) => {
				if (head.length > 0) {
					reject(new Error(`Unexpected data before CONNECT tunnel: ${head.length} bytes`));

					socket.destroy();
					return;
				}

				const tlsSocket = tls.connect({
					...options,
					socket
				}, callback);

				resolve(tlsSocket);
			});
		} catch (error) {
			reject(error);
		}
	})();
});

// This is required to prevent leaking real IP address on ALPN negotiation
const resolveProtocol = http2.auto.createResolveProtocol(new Map(), new Map(), connect);

const request = await http2.auto('https://httpbin.org/anything', {
	agent: {…},
	resolveProtocol
}, response => {
	// Read the response here
});

request.end();
```

See [`unknown-over-unknown.js`](examples/proxies/unknown-over-unknown.js) to learn more.

## Mirroring another server

See [`examples/proxies/mirror.js`](examples/proxies/mirror.js) for an example.

## [WebSockets over HTTP/2](https://tools.ietf.org/html/rfc8441)

See [`examples/ws`](examples/ws) for an example.

## Push streams

See [`examples/push-stream`](examples/push-stream) for an example.

## Related

- [`got`](https://github.com/sindresorhus/got) - Simplified HTTP requests
- [`http2-proxy`](https://github.com/nxtedition/node-http2-proxy) - A simple http/2 & http/1.1 spec compliant proxy helper for Node.

## License

MIT


---

# 2.1.0

## TypeScript types

- Add [TypeScript definitions](src/main.d.ts)

# 2.0.0

## Breaking changes

- Minimal supported Node.js version is now `10.17.0`


---

[![Codecov](https://img.shields.io/codecov/c/github/ehmicky/human-signals.svg?label=tested&logo=codecov)](https://codecov.io/gh/ehmicky/human-signals)
[![Travis](https://img.shields.io/badge/cross-platform-4cc61e.svg?logo=travis)](https://travis-ci.org/ehmicky/human-signals)
[![Node](https://img.shields.io/node/v/human-signals.svg?logo=node.js)](https://www.npmjs.com/package/human-signals)
[![Gitter](https://img.shields.io/gitter/room/ehmicky/human-signals.svg?logo=gitter)](https://gitter.im/ehmicky/human-signals)
[![Twitter](https://img.shields.io/badge/%E2%80%8B-twitter-4cc61e.svg?logo=twitter)](https://twitter.com/intent/follow?screen_name=ehmicky)
[![Medium](https://img.shields.io/badge/%E2%80%8B-medium-4cc61e.svg?logo=medium)](https://medium.com/@ehmicky)

Human-friendly process signals.

This is a map of known process signals with some information about each signal.

Unlike
[`os.constants.signals`](https://nodejs.org/api/os.html#os_signal_constants)
this includes:

- human-friendly [descriptions](#description)
- [default actions](#action), including whether they [can be prevented](#forced)
- whether the signal is [supported](#supported) by the current OS

# Example

```js
const { signalsByName, signalsByNumber } = require('human-signals')

console.log(signalsByName.SIGINT)
// {
//   name: 'SIGINT',
//   number: 2,
//   description: 'User interruption with CTRL-C',
//   supported: true,
//   action: 'terminate',
//   forced: false,
//   standard: 'ansi'
// }

console.log(signalsByNumber[8])
// {
//   name: 'SIGFPE',
//   number: 8,
//   description: 'Floating point arithmetic error',
//   supported: true,
//   action: 'core',
//   forced: false,
//   standard: 'ansi'
// }
```

# Install

```bash
npm install human-signals
```

# Usage

## signalsByName

_Type_: `object`

Object whose keys are signal [names](#name) and values are
[signal objects](#signal).

## signalsByNumber

_Type_: `object`

Object whose keys are signal [numbers](#number) and values are
[signal objects](#signal).

## signal

_Type_: `object`

Signal object with the following properties.

### name

_Type_: `string`

Standard name of the signal, for example `'SIGINT'`.

### number

_Type_: `number`

Code number of the signal, for example `2`. While most `number` are
cross-platform, some are different between different OS.

### description

_Type_: `string`

Human-friendly description for the signal, for example
`'User interruption with CTRL-C'`.

### supported

_Type_: `boolean`

Whether the current OS can handle this signal in Node.js using
[`process.on(name, handler)`](https://nodejs.org/api/process.html#process_signal_events).

The list of supported signals
[is OS-specific](https://github.com/ehmicky/cross-platform-node-guide/blob/master/docs/6_networking_ipc/signals.md#cross-platform-signals).

### action

_Type_: `string`\
_Enum_: `'terminate'`, `'core'`, `'ignore'`, `'pause'`, `'unpause'`

What is the default action for this signal when it is not handled.

### forced

_Type_: `boolean`

Whether the signal's default action cannot be prevented. This is `true` for
`SIGTERM`, `SIGKILL` and `SIGSTOP`.

### standard

_Type_: `string`\
_Enum_: `'ansi'`, `'posix'`, `'bsd'`, `'systemv'`, `'other'`

Which standard defined that signal.

# Support

If you found a bug or would like a new feature, _don't hesitate_ to
[submit an issue on GitHub](../../issues).

For other questions, feel free to
[chat with us on Gitter](https://gitter.im/ehmicky/human-signals).

Everyone is welcome regardless of personal background. We enforce a
[Code of conduct](CODE_OF_CONDUCT.md) in order to promote a positive and
inclusive environment.

# Contributing

This project was made with ❤️. The simplest way to give back is by starring and
sharing it online.

If the documentation is unclear or has a typo, please click on the page's `Edit`
button (pencil icon) and suggest a correction.

If you would like to help us fix a bug or add a new feature, please check our
[guidelines](CONTRIBUTING.md). Pull requests are welcome!

Thanks go to our wonderful contributors:

<!-- ALL-CONTRIBUTORS-LIST:START -->
<!-- prettier-ignore-start -->
<!-- markdownlint-disable -->
<table>
  <tr>
    <td align="center"><a href="https://twitter.com/ehmicky"><img src="https://avatars2.githubusercontent.com/u/8136211?v=4" width="100px;" alt=""/><br /><sub><b>ehmicky</b></sub></a><br /><a href="https://github.com/ehmicky/human-signals/commits?author=ehmicky" title="Code">💻</a> <a href="#design-ehmicky" title="Design">🎨</a> <a href="#ideas-ehmicky" title="Ideas, Planning, & Feedback">🤔</a> <a href="https://github.com/ehmicky/human-signals/commits?author=ehmicky" title="Documentation">📖</a></td>
    <td align="center"><a href="http://www.electrovir.com"><img src="https://avatars0.githubusercontent.com/u/1205860?v=4" width="100px;" alt=""/><br /><sub><b>electrovir</b></sub></a><br /><a href="https://github.com/ehmicky/human-signals/commits?author=electrovir" title="Code">💻</a></td>
  </tr>
</table>

<!-- markdownlint-enable -->
<!-- prettier-ignore-end -->

<!-- ALL-CONTRIBUTORS-LIST:END -->


---

# 0.4.24 / 2018-08-22

  * Added MIK encoding (#196, by @Ivan-Kalatchev)


# 0.4.23 / 2018-05-07

  * Fix deprecation warning in Node v10 due to the last usage of `new Buffer` (#185, by @felixbuenemann)
  * Switched from NodeBuffer to Buffer in typings (#155 by @felixfbecker, #186 by @larssn)


# 0.4.22 / 2018-05-05

  * Use older semver style for dependencies to be compatible with Node version 0.10 (#182, by @dougwilson)
  * Fix tests to accomodate fixes in Node v10 (#182, by @dougwilson)


# 0.4.21 / 2018-04-06

  * Fix encoding canonicalization (#156)
  * Fix the paths in the "browser" field in package.json (#174 by @LMLB)
  * Removed "contributors" section in package.json - see Git history instead.


# 0.4.20 / 2018-04-06

  * Updated `new Buffer()` usages with recommended replacements as it's being deprecated in Node v10 (#176, #178 by @ChALkeR)


# 0.4.19 / 2017-09-09

  * Fixed iso8859-1 codec regression in handling untranslatable characters (#162, caused by #147)
  * Re-generated windows1255 codec, because it was updated in iconv project
  * Fixed grammar in error message when iconv-lite is loaded with encoding other than utf8


# 0.4.18 / 2017-06-13

  * Fixed CESU-8 regression in Node v8.


# 0.4.17 / 2017-04-22

 * Updated typescript definition file to support Angular 2 AoT mode (#153 by @larssn)


# 0.4.16 / 2017-04-22

 * Added support for React Native (#150)
 * Changed iso8859-1 encoding to usine internal 'binary' encoding, as it's the same thing (#147 by @mscdex)
 * Fixed typo in Readme (#138 by @jiangzhuo)
 * Fixed build for Node v6.10+ by making correct version comparison
 * Added a warning if iconv-lite is loaded not as utf-8 (see #142)


# 0.4.15 / 2016-11-21

 * Fixed typescript type definition (#137)


# 0.4.14 / 2016-11-20

 * Preparation for v1.0
 * Added Node v6 and latest Node versions to Travis CI test rig
 * Deprecated Node v0.8 support
 * Typescript typings (@larssn)
 * Fix encoding of Euro character in GB 18030 (inspired by @lygstate)
 * Add ms prefix to dbcs windows encodings (@rokoroku)


# 0.4.13 / 2015-10-01

 * Fix silly mistake in deprecation notice.


# 0.4.12 / 2015-09-26

 * Node v4 support:
   * Added CESU-8 decoding (#106)
   * Added deprecation notice for `extendNodeEncodings`
   * Added Travis tests for Node v4 and io.js latest (#105 by @Mithgol)


# 0.4.11 / 2015-07-03

 * Added CESU-8 encoding.


# 0.4.10 / 2015-05-26

 * Changed UTF-16 endianness heuristic to take into account any ASCII chars, not
   just spaces. This should minimize the importance of "default" endianness.


# 0.4.9 / 2015-05-24

 * Streamlined BOM handling: strip BOM by default, add BOM when encoding if 
   addBOM: true. Added docs to Readme.
 * UTF16 now uses UTF16-LE by default.
 * Fixed minor issue with big5 encoding.
 * Added io.js testing on Travis; updated node-iconv version to test against.
   Now we just skip testing SBCS encodings that node-iconv doesn't support.
 * (internal refactoring) Updated codec interface to use classes.
 * Use strict mode in all files.


# 0.4.8 / 2015-04-14
 
 * added alias UNICODE-1-1-UTF-7 for UTF-7 encoding (#94)


# 0.4.7 / 2015-02-05

 * stop official support of Node.js v0.8. Should still work, but no guarantees.
   reason: Packages needed for testing are hard to get on Travis CI.
 * work in environment where Object.prototype is monkey patched with enumerable 
   props (#89).


# 0.4.6 / 2015-01-12
 
 * fix rare aliases of single-byte encodings (thanks @mscdex)
 * double the timeout for dbcs tests to make them less flaky on travis


# 0.4.5 / 2014-11-20

 * fix windows-31j and x-sjis encoding support (@nleush)
 * minor fix: undefined variable reference when internal error happens


# 0.4.4 / 2014-07-16

 * added encodings UTF-7 (RFC2152) and UTF-7-IMAP (RFC3501 Section 5.1.3)
 * fixed streaming base64 encoding


# 0.4.3 / 2014-06-14

 * added encodings UTF-16BE and UTF-16 with BOM


# 0.4.2 / 2014-06-12

 * don't throw exception if `extendNodeEncodings()` is called more than once


# 0.4.1 / 2014-06-11

 * codepage 808 added


# 0.4.0 / 2014-06-10

 * code is rewritten from scratch
 * all widespread encodings are supported
 * streaming interface added
 * browserify compatibility added
 * (optional) extend core primitive encodings to make usage even simpler
 * moved from vows to mocha as the testing framework




---

## Pure JS character encoding conversion [![Build Status](https://travis-ci.org/ashtuchkin/iconv-lite.svg?branch=master)](https://travis-ci.org/ashtuchkin/iconv-lite)

 * Doesn't need native code compilation. Works on Windows and in sandboxed environments like [Cloud9](http://c9.io).
 * Used in popular projects like [Express.js (body_parser)](https://github.com/expressjs/body-parser), 
   [Grunt](http://gruntjs.com/), [Nodemailer](http://www.nodemailer.com/), [Yeoman](http://yeoman.io/) and others.
 * Faster than [node-iconv](https://github.com/bnoordhuis/node-iconv) (see below for performance comparison).
 * Intuitive encode/decode API
 * Streaming support for Node v0.10+
 * [Deprecated] Can extend Node.js primitives (buffers, streams) to support all iconv-lite encodings.
 * In-browser usage via [Browserify](https://github.com/substack/node-browserify) (~180k gzip compressed with Buffer shim included).
 * Typescript [type definition file](https://github.com/ashtuchkin/iconv-lite/blob/master/lib/index.d.ts) included.
 * React Native is supported (need to explicitly `npm install` two more modules: `buffer` and `stream`).
 * License: MIT.

[![NPM Stats](https://nodei.co/npm/iconv-lite.png?downloads=true&downloadRank=true)](https://npmjs.org/packages/iconv-lite/)

## Usage
### Basic API
```javascript
var iconv = require('iconv-lite');

// Convert from an encoded buffer to js string.
str = iconv.decode(Buffer.from([0x68, 0x65, 0x6c, 0x6c, 0x6f]), 'win1251');

// Convert from js string to an encoded buffer.
buf = iconv.encode("Sample input string", 'win1251');

// Check if encoding is supported
iconv.encodingExists("us-ascii")
```

### Streaming API (Node v0.10+)
```javascript

// Decode stream (from binary stream to js strings)
http.createServer(function(req, res) {
    var converterStream = iconv.decodeStream('win1251');
    req.pipe(converterStream);

    converterStream.on('data', function(str) {
        console.log(str); // Do something with decoded strings, chunk-by-chunk.
    });
});

// Convert encoding streaming example
fs.createReadStream('file-in-win1251.txt')
    .pipe(iconv.decodeStream('win1251'))
    .pipe(iconv.encodeStream('ucs2'))
    .pipe(fs.createWriteStream('file-in-ucs2.txt'));

// Sugar: all encode/decode streams have .collect(cb) method to accumulate data.
http.createServer(function(req, res) {
    req.pipe(iconv.decodeStream('win1251')).collect(function(err, body) {
        assert(typeof body == 'string');
        console.log(body); // full request body string
    });
});
```

### [Deprecated] Extend Node.js own encodings
> NOTE: This doesn't work on latest Node versions. See [details](https://github.com/ashtuchkin/iconv-lite/wiki/Node-v4-compatibility).

```javascript
// After this call all Node basic primitives will understand iconv-lite encodings.
iconv.extendNodeEncodings();

// Examples:
buf = new Buffer(str, 'win1251');
buf.write(str, 'gbk');
str = buf.toString('latin1');
assert(Buffer.isEncoding('iso-8859-15'));
Buffer.byteLength(str, 'us-ascii');

http.createServer(function(req, res) {
    req.setEncoding('big5');
    req.collect(function(err, body) {
        console.log(body);
    });
});

fs.createReadStream("file.txt", "shift_jis");

// External modules are also supported (if they use Node primitives, which they probably do).
request = require('request');
request({
    url: "http://github.com/", 
    encoding: "cp932"
});

// To remove extensions
iconv.undoExtendNodeEncodings();
```

## Supported encodings

 *  All node.js native encodings: utf8, ucs2 / utf16-le, ascii, binary, base64, hex.
 *  Additional unicode encodings: utf16, utf16-be, utf-7, utf-7-imap.
 *  All widespread singlebyte encodings: Windows 125x family, ISO-8859 family, 
    IBM/DOS codepages, Macintosh family, KOI8 family, all others supported by iconv library. 
    Aliases like 'latin1', 'us-ascii' also supported.
 *  All widespread multibyte encodings: CP932, CP936, CP949, CP950, GB2312, GBK, GB18030, Big5, Shift_JIS, EUC-JP.

See [all supported encodings on wiki](https://github.com/ashtuchkin/iconv-lite/wiki/Supported-Encodings).

Most singlebyte encodings are generated automatically from [node-iconv](https://github.com/bnoordhuis/node-iconv). Thank you Ben Noordhuis and libiconv authors!

Multibyte encodings are generated from [Unicode.org mappings](http://www.unicode.org/Public/MAPPINGS/) and [WHATWG Encoding Standard mappings](http://encoding.spec.whatwg.org/). Thank you, respective authors!


## Encoding/decoding speed

Comparison with node-iconv module (1000x256kb, on MacBook Pro, Core i5/2.6 GHz, Node v0.12.0). 
Note: your results may vary, so please always check on your hardware.

    operation             iconv@2.1.4   iconv-lite@0.4.7
    ----------------------------------------------------------
    encode('win1251')     ~96 Mb/s      ~320 Mb/s
    decode('win1251')     ~95 Mb/s      ~246 Mb/s

## BOM handling

 * Decoding: BOM is stripped by default, unless overridden by passing `stripBOM: false` in options
   (f.ex. `iconv.decode(buf, enc, {stripBOM: false})`).
   A callback might also be given as a `stripBOM` parameter - it'll be called if BOM character was actually found.
 * If you want to detect UTF-8 BOM when decoding other encodings, use [node-autodetect-decoder-stream](https://github.com/danielgindi/node-autodetect-decoder-stream) module.
 * Encoding: No BOM added, unless overridden by `addBOM: true` option.

## UTF-16 Encodings

This library supports UTF-16LE, UTF-16BE and UTF-16 encodings. First two are straightforward, but UTF-16 is trying to be
smart about endianness in the following ways:
 * Decoding: uses BOM and 'spaces heuristic' to determine input endianness. Default is UTF-16LE, but can be 
   overridden with `defaultEncoding: 'utf-16be'` option. Strips BOM unless `stripBOM: false`.
 * Encoding: uses UTF-16LE and writes BOM by default. Use `addBOM: false` to override.

## Other notes

When decoding, be sure to supply a Buffer to decode() method, otherwise [bad things usually happen](https://github.com/ashtuchkin/iconv-lite/wiki/Use-Buffers-when-decoding).  
Untranslatable characters are set to � or ?. No transliteration is currently supported.  
Node versions 0.10.31 and 0.11.13 are buggy, don't use them (see #65, #77).  

## Testing

```bash
$ git clone git@github.com:ashtuchkin/iconv-lite.git
$ cd iconv-lite
$ npm install
$ npm test
    
$ # To view performance:
$ node test/performance.js

$ # To view test coverage:
$ npm run coverage
$ open coverage/lcov-report/index.html
```


---

# Change Log

All notable changes to this project will be documented in this file.
This project adheres to [Semantic Versioning](http://semver.org/).

## [5.1.0] - 2020-11-19

### Features

- feat: support at-rule versions of `import`/`export`

## [5.0.0] - 2020-10-12

### BREAKING CHANGE

- minimum supported `postcss` version is `^8.1.0`

### Fixes

- minimum supported `Node.js` version is `^10 || ^12 || >= 14`
- compatibility with PostCSS 8

## [5.0.0-rc.0] - 2020-09-21

### BREAKING CHANGE

- minimum supported `Node.js` version is `>= 10.13.0 || >= 12.13.0 || >= 14`
- minimum supported `postcss` version is `^8.0.0`
- `postcss` was moved to `peerDependencies`, you need to install `postcss` in your project before use the plugin
- you need to pass `postcss` API to using `createICSSRules` (third argument)


---

ISC License (ISC)
Copyright 2018 Glen Maddern

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.


---

[![Build Status](https://travis-ci.org/css-modules/icss-utils.svg)](https://travis-ci.org/css-modules/icss-utils)

# ICSS Utils

## replaceSymbols

Governs the way tokens are searched & replaced during the linking stage of ICSS loading.

This is broken into its own module in case the behaviour needs to be replicated in other PostCSS plugins
(i.e. [CSS Modules Values](https://github.com/css-modules/postcss-modules-values))

```js
import { replaceSymbols, replaceValueSymbols } from "icss-utils";

replaceSymbols(css, replacements);
replaceValueSymbols(string, replacements);
```

Where:

- `css` is the PostCSS tree you're working with
- `replacements` is an JS object of `symbol: "replacement"` pairs, where all occurrences of `symbol` are replaced with `replacement`.

A symbol is a string of alphanumeric, `-` or `_` characters. A replacement can be any string. They are replaced in the following places:

- In the value of a declaration, i.e. `color: my_symbol;` or `box-shadow: 0 0 blur spread shadow-color`
- In a media expression i.e. `@media small {}` or `@media screen and not-large {}`

## extractICSS(css, removeRules = true, mode = 'auto')

Extracts and remove (if removeRules is equal true) from PostCSS tree `:import`, `@icss-import`, `:export` and `@icss-export` statements.

```js
import postcss from "postcss";
import { extractICSS } from "icss-utils";

const css = postcss.parse(`
  :import(colors) {
    a: b;
  }
  :export {
    c: d;
  }
`);

extractICSS(css);
/*
  {
    icssImports: {
      colors: {
        a: 'b'
      }
    },
    icssExports: {
      c: 'd'
    }
  }
*/
```

By default both the pseudo and at-rule form of the import and export statements
will be removed. Pass the `mode` option to limit to only one type.

## createICSSRules(icssImports, icssExports, mode = 'rule')

Converts icss imports and exports definitions to postcss ast

```js
createICSSRules(
  {
    colors: {
      a: "b",
    },
  },
  {
    c: "d",
  },
  // Need pass `rule` and `decl` from postcss
  // Please look at `Step 4` https://evilmartians.com/chronicles/postcss-8-plugin-migration
  postcss
);
```

By default it will create pseudo selector rules (`:import` and `:export`). Pass
`at-rule` for `mode` to instead generate `@icss-import` and `@icss-export`, which
may be more resilient to post processing by other tools.

## License

ISC

---

Glen Maddern, Bogdan Chadkin and Evilebottnawi 2015-present.


---

<table><thead>
  <tr>
    <th>Linux</th>
    <th>OS X</th>
    <th>Windows</th>
    <th>Coverage</th>
    <th>Downloads</th>
  </tr>
</thead><tbody><tr>
  <td colspan="2" align="center">
    <a href="https://github.com/kaelzhang/node-ignore/actions/workflows/nodejs.yml">
    <img
      src="https://github.com/kaelzhang/node-ignore/actions/workflows/nodejs.yml/badge.svg"
      alt="Build Status" /></a>
  </td>
  <td align="center">
    <a href="https://ci.appveyor.com/project/kaelzhang/node-ignore">
    <img
      src="https://ci.appveyor.com/api/projects/status/github/kaelzhang/node-ignore?branch=master&svg=true"
      alt="Windows Build Status" /></a>
  </td>
  <td align="center">
    <a href="https://codecov.io/gh/kaelzhang/node-ignore">
    <img
      src="https://codecov.io/gh/kaelzhang/node-ignore/branch/master/graph/badge.svg"
      alt="Coverage Status" /></a>
  </td>
  <td align="center">
    <a href="https://www.npmjs.org/package/ignore">
    <img
      src="http://img.shields.io/npm/dm/ignore.svg"
      alt="npm module downloads per month" /></a>
  </td>
</tr></tbody></table>

# ignore

`ignore` is a manager, filter and parser which implemented in pure JavaScript according to the [.gitignore spec 2.22.1](http://git-scm.com/docs/gitignore).

`ignore` is used by eslint, gitbook and [many others](https://www.npmjs.com/browse/depended/ignore).

Pay **ATTENTION** that [`minimatch`](https://www.npmjs.org/package/minimatch) (which used by `fstream-ignore`) does not follow the gitignore spec.

To filter filenames according to a .gitignore file, I recommend this npm package, `ignore`.

To parse an `.npmignore` file, you should use `minimatch`, because an `.npmignore` file is parsed by npm using `minimatch` and it does not work in the .gitignore way.

### Tested on

`ignore` is fully tested, and has more than **five hundreds** of unit tests.

- Linux + Node: `0.8` - `7.x`
- Windows + Node: `0.10` - `7.x`, node < `0.10` is not tested due to the lack of support of appveyor.

Actually, `ignore` does not rely on any versions of node specially.

Since `4.0.0`, ignore will no longer support `node < 6` by default, to use in node < 6, `require('ignore/legacy')`. For details, see [CHANGELOG](https://github.com/kaelzhang/node-ignore/blob/master/CHANGELOG.md).

## Table Of Main Contents

- [Usage](#usage)
- [`Pathname` Conventions](#pathname-conventions)
- See Also:
  - [`glob-gitignore`](https://www.npmjs.com/package/glob-gitignore) matches files using patterns and filters them according to gitignore rules.
- [Upgrade Guide](#upgrade-guide)

## Install

```sh
npm i ignore
```

## Usage

```js
import ignore from 'ignore'
const ig = ignore().add(['.abc/*', '!.abc/d/'])
```

### Filter the given paths

```js
const paths = [
  '.abc/a.js',    // filtered out
  '.abc/d/e.js'   // included
]

ig.filter(paths)        // ['.abc/d/e.js']
ig.ignores('.abc/a.js') // true
```

### As the filter function

```js
paths.filter(ig.createFilter()); // ['.abc/d/e.js']
```

### Win32 paths will be handled

```js
ig.filter(['.abc\\a.js', '.abc\\d\\e.js'])
// if the code above runs on windows, the result will be
// ['.abc\\d\\e.js']
```

## Why another ignore?

- `ignore` is a standalone module, and is much simpler so that it could easy work with other programs, unlike [isaacs](https://npmjs.org/~isaacs)'s [fstream-ignore](https://npmjs.org/package/fstream-ignore) which must work with the modules of the fstream family.

- `ignore` only contains utility methods to filter paths according to the specified ignore rules, so
  - `ignore` never try to find out ignore rules by traversing directories or fetching from git configurations.
  - `ignore` don't cares about sub-modules of git projects.

- Exactly according to [gitignore man page](http://git-scm.com/docs/gitignore), fixes some known matching issues of fstream-ignore, such as:
  - '`/*.js`' should only match '`a.js`', but not '`abc/a.js`'.
  - '`**/foo`' should match '`foo`' anywhere.
  - Prevent re-including a file if a parent directory of that file is excluded.
  - Handle trailing whitespaces:
    - `'a '`(one space) should not match `'a  '`(two spaces).
    - `'a \ '` matches `'a  '`
  - All test cases are verified with the result of `git check-ignore`.

# Methods

## .add(pattern: string | Ignore): this
## .add(patterns: Array<string | Ignore>): this

- **pattern** `String | Ignore` An ignore pattern string, or the `Ignore` instance
- **patterns** `Array<String | Ignore>` Array of ignore patterns.

Adds a rule or several rules to the current manager.

Returns `this`

Notice that a line starting with `'#'`(hash) is treated as a comment. Put a backslash (`'\'`) in front of the first hash for patterns that begin with a hash, if you want to ignore a file with a hash at the beginning of the filename.

```js
ignore().add('#abc').ignores('#abc')    // false
ignore().add('\\#abc').ignores('#abc')   // true
```

`pattern` could either be a line of ignore pattern or a string of multiple ignore patterns, which means we could just `ignore().add()` the content of a ignore file:

```js
ignore()
.add(fs.readFileSync(filenameOfGitignore).toString())
.filter(filenames)
```

`pattern` could also be an `ignore` instance, so that we could easily inherit the rules of another `Ignore` instance.

## <strike>.addIgnoreFile(path)</strike>

REMOVED in `3.x` for now.

To upgrade `ignore@2.x` up to `3.x`, use

```js
import fs from 'fs'

if (fs.existsSync(filename)) {
  ignore().add(fs.readFileSync(filename).toString())
}
```

instead.

## .filter(paths: Array&lt;Pathname&gt;): Array&lt;Pathname&gt;

```ts
type Pathname = string
```

Filters the given array of pathnames, and returns the filtered array.

- **paths** `Array.<Pathname>` The array of `pathname`s to be filtered.

### `Pathname` Conventions:

#### 1. `Pathname` should be a `path.relative()`d pathname

`Pathname` should be a string that have been `path.join()`ed, or the return value of `path.relative()` to the current directory,

```js
// WRONG, an error will be thrown
ig.ignores('./abc')

// WRONG, for it will never happen, and an error will be thrown
// If the gitignore rule locates at the root directory,
// `'/abc'` should be changed to `'abc'`.
// ```
// path.relative('/', '/abc')  -> 'abc'
// ```
ig.ignores('/abc')

// WRONG, that it is an absolute path on Windows, an error will be thrown
ig.ignores('C:\\abc')

// Right
ig.ignores('abc')

// Right
ig.ignores(path.join('./abc'))  // path.join('./abc') -> 'abc'
```

In other words, each `Pathname` here should be a relative path to the directory of the gitignore rules.

Suppose the dir structure is:

```
/path/to/your/repo
    |-- a
    |   |-- a.js
    |
    |-- .b
    |
    |-- .c
         |-- .DS_store
```

Then the `paths` might be like this:

```js
[
  'a/a.js'
  '.b',
  '.c/.DS_store'
]
```

#### 2. filenames and dirnames

`node-ignore` does NO `fs.stat` during path matching, so for the example below:

```js
// First, we add a ignore pattern to ignore a directory
ig.add('config/')

// `ig` does NOT know if 'config', in the real world,
//   is a normal file, directory or something.

ig.ignores('config')
// `ig` treats `config` as a file, so it returns `false`

ig.ignores('config/')
// returns `true`
```

Specially for people who develop some library based on `node-ignore`, it is important to understand that.

Usually, you could use [`glob`](http://npmjs.org/package/glob) with `option.mark = true` to fetch the structure of the current directory:

```js
import glob from 'glob'

glob('**', {
  // Adds a / character to directory matches.
  mark: true
}, (err, files) => {
  if (err) {
    return console.error(err)
  }

  let filtered = ignore().add(patterns).filter(files)
  console.log(filtered)
})
```

## .ignores(pathname: Pathname): boolean

> new in 3.2.0

Returns `Boolean` whether `pathname` should be ignored.

```js
ig.ignores('.abc/a.js')    // true
```

## .createFilter()

Creates a filter function which could filter an array of paths with `Array.prototype.filter`.

Returns `function(path)` the filter function.

## .test(pathname: Pathname) since 5.0.0

Returns `TestResult`

```ts
interface TestResult {
  ignored: boolean
  // true if the `pathname` is finally unignored by some negative pattern
  unignored: boolean
}
```

- `{ignored: true, unignored: false}`: the `pathname` is ignored
- `{ignored: false, unignored: true}`: the `pathname` is unignored
- `{ignored: false, unignored: false}`: the `pathname` is never matched by any ignore rules.

## static `ignore.isPathValid(pathname): boolean` since 5.0.0

Check whether the `pathname` is an valid `path.relative()`d path according to the [convention](#1-pathname-should-be-a-pathrelatived-pathname).

This method is **NOT** used to check if an ignore pattern is valid.

```js
ignore.isPathValid('./foo')  // false
```

## ignore(options)

### `options.ignorecase` since 4.0.0

Similar as the `core.ignorecase` option of [git-config](https://git-scm.com/docs/git-config), `node-ignore` will be case insensitive if `options.ignorecase` is set to `true` (the default value), otherwise case sensitive.

```js
const ig = ignore({
  ignorecase: false
})

ig.add('*.png')

ig.ignores('*.PNG')  // false
```

### `options.ignoreCase?: boolean` since 5.2.0

Which is alternative to `options.ignoreCase`

### `options.allowRelativePaths?: boolean` since 5.2.0

This option brings backward compatibility with projects which based on `ignore@4.x`. If `options.allowRelativePaths` is `true`, `ignore` will not check whether the given path to be tested is [`path.relative()`d](#pathname-conventions).

However, passing a relative path, such as `'./foo'` or `'../foo'`, to test if it is ignored or not is not a good practise, which might lead to unexpected behavior

```js
ignore({
  allowRelativePaths: true
}).ignores('../foo/bar.js') // And it will not throw
```

****

# Upgrade Guide

## Upgrade 4.x -> 5.x

Since `5.0.0`, if an invalid `Pathname` passed into `ig.ignores()`, an error will be thrown, unless `options.allowRelative = true` is passed to the `Ignore` factory.

While `ignore < 5.0.0` did not make sure what the return value was, as well as

```ts
.ignores(pathname: Pathname): boolean

.filter(pathnames: Array<Pathname>): Array<Pathname>

.createFilter(): (pathname: Pathname) => boolean

.test(pathname: Pathname): {ignored: boolean, unignored: boolean}
```

See the convention [here](#1-pathname-should-be-a-pathrelatived-pathname) for details.

If there are invalid pathnames, the conversion and filtration should be done by users.

```js
import {isPathValid} from 'ignore' // introduced in 5.0.0

const paths = [
  // invalid
  //////////////////
  '',
  false,
  '../foo',
  '.',
  //////////////////

  // valid
  'foo'
]
.filter(isValidPath)

ig.filter(paths)
```

## Upgrade 3.x -> 4.x

Since `4.0.0`, `ignore` will no longer support node < 6, to use `ignore` in node < 6:

```js
var ignore = require('ignore/legacy')
```

## Upgrade 2.x -> 3.x

- All `options` of 2.x are unnecessary and removed, so just remove them.
- `ignore()` instance is no longer an [`EventEmitter`](nodejs.org/api/events.html), and all events are unnecessary and removed.
- `.addIgnoreFile()` is removed, see the [.addIgnoreFile](#addignorefilepath) section for details.

****

# Collaborators

- [@whitecolor](https://github.com/whitecolor) *Alex*
- [@SamyPesse](https://github.com/SamyPesse) *Samy Pessé*
- [@azproduction](https://github.com/azproduction) *Mikhail Davydov*
- [@TrySound](https://github.com/TrySound) *Bogdan Chadkin*
- [@JanMattner](https://github.com/JanMattner) *Jan Mattner*
- [@ntwb](https://github.com/ntwb) *Stephen Edgar*
- [@kasperisager](https://github.com/kasperisager) *Kasper Isager*
- [@sandersn](https://github.com/sandersn) *Nathan Shively-Sanders*


---

# image-size

[![Build Status](https://circleci.com/gh/image-size/image-size.svg?style=shield)](https://circleci.com/gh/image-size/image-size)
[![Package Version](https://img.shields.io/npm/v/image-size.svg)](https://www.npmjs.com/package/image-size)
[![Downloads](https://img.shields.io/npm/dm/image-size.svg)](http://npm-stat.com/charts.html?package=image-size&author=&from=&to=)

A [Node](https://nodejs.org/en/) module to get dimensions of any image file

## Supported formats

- BMP
- CUR
- DDS
- GIF
- HEIC (HEIF, AVCI, AVIF)
- ICNS
- ICO
- J2C
- JPEG-2000 (JP2)
- JPEG
- JPEG-XL
- KTX (1 and 2)
- PNG
- PNM (PAM, PBM, PFM, PGM, PPM)
- PSD
- SVG
- TGA
- TIFF
- WebP

## Programmatic Usage

```shell
npm install image-size --save
```

or

```shell
yarn add image-size
```

### Synchronous

```javascript
const sizeOf = require("image-size")
const dimensions = sizeOf("images/funny-cats.png")
console.log(dimensions.width, dimensions.height)
```

### Asynchronous

```javascript
const sizeOf = require("image-size")
sizeOf("images/funny-cats.png", function (err, dimensions) {
  console.log(dimensions.width, dimensions.height)
})
```

NOTE: The asynchronous version doesn't work if the input is a Buffer. Use synchronous version instead.

Also, the asynchronous functions have a default concurrency limit of **100**
To change this limit, you can call the `setConcurrency` function like this:

```javascript
const sizeOf = require("image-size")
sizeOf.setConcurrency(123456)
```

### Using promises (nodejs 10.x+)

```javascript
const { promisify } = require("util")
const sizeOf = promisify(require("image-size"))
sizeOf("images/funny-cats.png")
  .then((dimensions) => {
    console.log(dimensions.width, dimensions.height)
  })
  .catch((err) => console.error(err))
```

### Async/Await (Typescript & ES7)

```javascript
const { promisify } = require("util")
const sizeOf = promisify(require("image-size"))(async () => {
  try {
    const dimensions = await sizeOf("images/funny-cats.png")
    console.log(dimensions.width, dimensions.height)
  } catch (err) {
    console.error(err)
  }
})().then((c) => console.log(c))
```

### Multi-size

If the target file is an icon (.ico) or a cursor (.cur), the `width` and `height` will be the ones of the first found image.

An additional `images` array is available and returns the dimensions of all the available images

```javascript
const sizeOf = require("image-size")
const images = sizeOf("images/multi-size.ico").images
for (const dimensions of images) {
  console.log(dimensions.width, dimensions.height)
}
```

### Using a URL

```javascript
const url = require("url")
const http = require("http")

const sizeOf = require("image-size")

const imgUrl = "http://my-amazing-website.com/image.jpeg"
const options = url.parse(imgUrl)

http.get(options, function (response) {
  const chunks = []
  response
    .on("data", function (chunk) {
      chunks.push(chunk)
    })
    .on("end", function () {
      const buffer = Buffer.concat(chunks)
      console.log(sizeOf(buffer))
    })
})
```

You can optionally check the buffer lengths & stop downloading the image after a few kilobytes.
**You don't need to download the entire image**

### Disabling certain image types

```javascript
const imageSize = require("image-size")
imageSize.disableTypes(["tiff", "ico"])
```

### Disabling all file-system reads

```javascript
const imageSize = require("image-size")
imageSize.disableFS(true)
```

### JPEG image orientation

If the orientation is present in the JPEG EXIF metadata, it will be returned by the function. The orientation value is a [number between 1 and 8](https://exiftool.org/TagNames/EXIF.html#:~:text=0x0112,8%20=%20Rotate%20270%20CW) representing a type of orientation.

```javascript
const sizeOf = require("image-size")
const dimensions = sizeOf("images/photo.jpeg")
console.log(dimensions.orientation)
```

## Command-Line Usage (CLI)

```shell
npm install image-size --global
```

or

```shell
yarn global add image-size
```

followed by

```shell
image-size image1 [image2] [image3] ...
```

## Credits

not a direct port, but an attempt to have something like
[dabble's imagesize](https://github.com/dabble/imagesize/blob/master/lib/image_size.rb) as a node module.

## [Contributors](Contributors.md)


---

<img src="images/immer-logo.svg" height="200px" align="right"/>

# Immer

[![npm](https://img.shields.io/npm/v/immer.svg)](https://www.npmjs.com/package/immer) [![Build Status](https://travis-ci.org/immerjs/immer.svg?branch=main)](https://travis-ci.org/immerjs/immer) [![Coverage Status](https://coveralls.io/repos/github/mweststrate/immer/badge.svg?branch=main)](https://coveralls.io/github/mweststrate/immer?branch=main) [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier) [![OpenCollective](https://opencollective.com/immer/backers/badge.svg)](#backers) [![OpenCollective](https://opencollective.com/immer/sponsors/badge.svg)](#sponsors) [![Gitpod Ready-to-Code](https://img.shields.io/badge/Gitpod-Ready--to--Code-blue?logo=gitpod)](https://gitpod.io/#https://github.com/immerjs/immer)

_Create the next immutable state tree by simply modifying the current tree_

Winner of the "Breakthrough of the year" [React open source award](https://osawards.com/react/) and "Most impactful contribution" [JavaScript open source award](https://osawards.com/javascript/) in 2019

## Contribute using one-click online setup

You can use Gitpod (a free online VS Code like IDE) for contributing online. With a single click it will launch a workspace and automatically:

- clone the immer repo.
- install the dependencies.
- run `yarn run start`.

so that you can start coding straight away.

[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/from-referrer/)

## Documentation

The documentation of this package is hosted at https://immerjs.github.io/immer/

## Support

Did Immer make a difference to your project? Join the open collective at https://opencollective.com/immer!

## Release notes

https://github.com/immerjs/immer/releases


---

# import-fresh

> Import a module while bypassing the [cache](https://nodejs.org/api/modules.html#modules_caching)

Useful for testing purposes when you need to freshly import a module.

## ESM

For ESM, you can use this snippet:

```js
const importFresh = moduleName => import(`${moduleName}?${Date.now()}`);

const {default: foo} = await importFresh('foo');
```

**This snippet causes a memory leak, so only use it for short-lived tests.**

## Install

```sh
npm install import-fresh
```

## Usage

```js
// foo.js
let i = 0;
module.exports = () => ++i;
```

```js
const importFresh = require('import-fresh');

require('./foo')();
//=> 1

require('./foo')();
//=> 2

importFresh('./foo')();
//=> 1

importFresh('./foo')();
//=> 1
```

## Related

- [clear-module](https://github.com/sindresorhus/clear-module) - Clear a module from the import cache
- [import-from](https://github.com/sindresorhus/import-from) - Import a module from a given path
- [import-cwd](https://github.com/sindresorhus/import-cwd) - Import a module from the current working directory
- [import-lazy](https://github.com/sindresorhus/import-lazy) - Import modules lazily


---

# import-lazy [![Build Status](https://travis-ci.org/sindresorhus/import-lazy.svg?branch=master)](https://travis-ci.org/sindresorhus/import-lazy)

> Import a module lazily


## Install

```
$ npm install import-lazy
```


## Usage

```js
// Pass in `require` or a custom import function
const importLazy = require('import-lazy')(require);
const _ = importLazy('lodash');

// Instead of referring to its exported properties directly…
_.isNumber(2);

// …it's cached on consecutive calls
_.isNumber('unicorn');

// Works out of the box for functions and regular properties
const stuff = importLazy('./math-lib');
console.log(stuff.sum(1, 2)); // => 3
console.log(stuff.PHI); // => 1.618033
```

### Warning: Destructuring will cause it to fetch eagerly

While you may be tempted to do leverage destructuring, like this:

```js
const {isNumber, isString} = importLazy('lodash');
```

Note that this will cause immediate property access, negating the lazy loading, and is equivalent to:

```js
import {isNumber, isString} from 'lodash';
```

## Related

- [resolve-from](https://github.com/sindresorhus/resolve-from) - Resolve the path of a module from a given path
- [import-from](https://github.com/sindresorhus/import-from) - Import a module from a given path
- [resolve-pkg](https://github.com/sindresorhus/resolve-pkg) - Resolve the path of a package regardless of it having an entry point
- [lazy-value](https://github.com/sindresorhus/lazy-value) - Create a lazily evaluated value
- [define-lazy-prop](https://github.com/sindresorhus/define-lazy-prop) - Define a lazily evaluated property on an object


## License

MIT © [Sindre Sorhus](https://sindresorhus.com)


---

iMurmurHash.js
==============

An incremental implementation of the MurmurHash3 (32-bit) hashing algorithm for JavaScript based on [Gary Court's implementation](https://github.com/garycourt/murmurhash-js) with [kazuyukitanimura's modifications](https://github.com/kazuyukitanimura/murmurhash-js).

This version works significantly faster than the non-incremental version if you need to hash many small strings into a single hash, since string concatenation (to build the single string to pass the non-incremental version) is fairly costly. In one case tested, using the incremental version was about 50% faster than concatenating 5-10 strings and then hashing.

Installation
------------

To use iMurmurHash in the browser, [download the latest version](https://raw.github.com/jensyt/imurmurhash-js/master/imurmurhash.min.js) and include it as a script on your site.

```html
<script type="text/javascript" src="/scripts/imurmurhash.min.js"></script>
<script>
// Your code here, access iMurmurHash using the global object MurmurHash3
</script>
```

---

To use iMurmurHash in Node.js, install the module using NPM:

```bash
npm install imurmurhash
```

Then simply include it in your scripts:

```javascript
MurmurHash3 = require('imurmurhash');
```

Quick Example
-------------

```javascript
// Create the initial hash
var hashState = MurmurHash3('string');

// Incrementally add text
hashState.hash('more strings');
hashState.hash('even more strings');

// All calls can be chained if desired
hashState.hash('and').hash('some').hash('more');

// Get a result
hashState.result();
// returns 0xe4ccfe6b
```

Functions
---------

### MurmurHash3 ([string], [seed])
Get a hash state object, optionally initialized with the given _string_ and _seed_. _Seed_ must be a positive integer if provided. Calling this function without the `new` keyword will return a cached state object that has been reset. This is safe to use as long as the object is only used from a single thread and no other hashes are created while operating on this one. If this constraint cannot be met, you can use `new` to create a new state object. For example:

```javascript
// Use the cached object, calling the function again will return the same
// object (but reset, so the current state would be lost)
hashState = MurmurHash3();
...

// Create a new object that can be safely used however you wish. Calling the
// function again will simply return a new state object, and no state loss
// will occur, at the cost of creating more objects.
hashState = new MurmurHash3();
```

Both methods can be mixed however you like if you have different use cases.

---

### MurmurHash3.prototype.hash (string)
Incrementally add _string_ to the hash. This can be called as many times as you want for the hash state object, including after a call to `result()`. Returns `this` so calls can be chained.

---

### MurmurHash3.prototype.result ()
Get the result of the hash as a 32-bit positive integer. This performs the tail and finalizer portions of the algorithm, but does not store the result in the state object. This means that it is perfectly safe to get results and then continue adding strings via `hash`.

```javascript
// Do the whole string at once
MurmurHash3('this is a test string').result();
// 0x70529328

// Do part of the string, get a result, then the other part
var m = MurmurHash3('this is a');
m.result();
// 0xbfc4f834
m.hash(' test string').result();
// 0x70529328 (same as above)
```

---

### MurmurHash3.prototype.reset ([seed])
Reset the state object for reuse, optionally using the given _seed_ (defaults to 0 like the constructor). Returns `this` so calls can be chained.

---

License (MIT)
-------------
Copyright (c) 2013 Gary Court, Jens Taylor

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


---

# indent-string [![Build Status](https://travis-ci.org/sindresorhus/indent-string.svg?branch=master)](https://travis-ci.org/sindresorhus/indent-string)

> Indent each line in a string


## Install

```
$ npm install indent-string
```


## Usage

```js
const indentString = require('indent-string');

indentString('Unicorns\nRainbows', 4);
//=> '    Unicorns\n    Rainbows'

indentString('Unicorns\nRainbows', 4, {indent: '♥'});
//=> '♥♥♥♥Unicorns\n♥♥♥♥Rainbows'
```


## API

### indentString(string, [count], [options])

#### string

Type: `string`

The string to indent.

#### count

Type: `number`<br>
Default: `1`

How many times you want `options.indent` repeated.

#### options

Type: `object`

##### indent

Type: `string`<br>
Default: `' '`

The string to use for the indent.

##### includeEmptyLines

Type: `boolean`<br>
Default: `false`

Also indent empty lines.


## Related

- [indent-string-cli](https://github.com/sindresorhus/indent-string-cli) - CLI for this module
- [strip-indent](https://github.com/sindresorhus/strip-indent) - Strip leading whitespace from every line in a string


## License

MIT © [Sindre Sorhus](https://sindresorhus.com)


---

# inflight

Add callbacks to requests in flight to avoid async duplication

## USAGE

```javascript
var inflight = require('inflight')

// some request that does some stuff
function req(key, callback) {
  // key is any random string.  like a url or filename or whatever.
  //
  // will return either a falsey value, indicating that the
  // request for this key is already in flight, or a new callback
  // which when called will call all callbacks passed to inflightk
  // with the same key
  callback = inflight(key, callback)

  // If we got a falsey value back, then there's already a req going
  if (!callback) return

  // this is where you'd fetch the url or whatever
  // callback is also once()-ified, so it can safely be assigned
  // to multiple events etc.  First call wins.
  setTimeout(function() {
    callback(null, key)
  }, 100)
}

// only assigns a single setTimeout
// when it dings, all cbs get called
req('foo', cb1)
req('foo', cb2)
req('foo', cb3)
req('foo', cb4)
```


---

Browser-friendly inheritance fully compatible with standard node.js
[inherits](http://nodejs.org/api/util.html#util_util_inherits_constructor_superconstructor).

This package exports standard `inherits` from node.js `util` module in
node environment, but also provides alternative browser-friendly
implementation through [browser
field](https://gist.github.com/shtylman/4339901). Alternative
implementation is a literal copy of standard one located in standalone
module to avoid requiring of `util`. It also has a shim for old
browsers with no `Object.create` support.

While keeping you sure you are using standard `inherits`
implementation in node.js environment, it allows bundlers such as
[browserify](https://github.com/substack/node-browserify) to not
include full `util` package to your client code if all you need is
just `inherits` function. It worth, because browser shim for `util`
package is large and `inherits` is often the single function you need
from it.

It's recommended to use this package instead of
`require('util').inherits` for any code that has chances to be used
not only in node.js but in browser too.

## usage

```js
var inherits = require('inherits');
// then use exactly as the standard one
```

## note on version ~1.0

Version ~1.0 had completely different motivation and is not compatible
neither with 2.0 nor with standard node.js `inherits`.

If you are using version ~1.0 and planning to switch to ~2.0, be
careful:

* new version uses `super_` instead of `super` for referencing
  superclass
* new version overwrites current prototype while old one preserves any
  existing fields on it


---

An ini format parser and serializer for node.

Sections are treated as nested objects.  Items before the first
heading are saved on the object directly.

## Usage

Consider an ini-file `config.ini` that looks like this:

    ; this comment is being ignored
    scope = global

    [database]
    user = dbuser
    password = dbpassword
    database = use_this_database

    [paths.default]
    datadir = /var/lib/data
    array[] = first value
    array[] = second value
    array[] = third value

You can read, manipulate and write the ini-file like so:

    var fs = require('fs')
      , ini = require('ini')

    var config = ini.parse(fs.readFileSync('./config.ini', 'utf-8'))

    config.scope = 'local'
    config.database.database = 'use_another_database'
    config.paths.default.tmpdir = '/tmp'
    delete config.paths.default.datadir
    config.paths.default.array.push('fourth value')

    fs.writeFileSync('./config_modified.ini', ini.stringify(config, { section: 'section' }))

This will result in a file called `config_modified.ini` being written
to the filesystem with the following content:

    [section]
    scope=local
    [section.database]
    user=dbuser
    password=dbpassword
    database=use_another_database
    [section.paths.default]
    tmpdir=/tmp
    array[]=first value
    array[]=second value
    array[]=third value
    array[]=fourth value


## API

### decode(inistring)

Decode the ini-style formatted `inistring` into a nested object.

### parse(inistring)

Alias for `decode(inistring)`

### encode(object, [options])

Encode the object `object` into an ini-style formatted string. If the
optional parameter `section` is given, then all top-level properties
of the object are put into this section and the `section`-string is
prepended to all sub-sections, see the usage example above.

The `options` object may contain the following:

* `section` A string which will be the first `section` in the encoded
  ini data.  Defaults to none.
* `whitespace` Boolean to specify whether to put whitespace around the
  `=` character.  By default, whitespace is omitted, to be friendly to
  some persnickety old parsers that don't tolerate it well.  But some
  find that it's more human-readable and pretty with the whitespace.

For backwards compatibility reasons, if a `string` options is passed
in, then it is assumed to be the `section` value.

### stringify(object, [options])

Alias for `encode(object, [options])`

### safe(val)

Escapes the string `val` such that it is safe to be used as a key or
value in an ini-file. Basically escapes quotes. For example

    ini.safe('"unsafe string"')

would result in

    "\"unsafe string\""

### unsafe(val)

Unescapes the string `val`


---

# inline-style-parser

[![NPM](https://nodei.co/npm/inline-style-parser.png)](https://nodei.co/npm/inline-style-parser/)

[![NPM version](https://badgen.net/npm/v/inline-style-parser)](https://www.npmjs.com/package/inline-style-parser)
[![Bundlephobia minified + gzip](https://badgen.net/bundlephobia/minzip/inline-style-parser)](https://bundlephobia.com/package/inline-style-parser)
[![build](https://github.com/remarkablemark/inline-style-parser/actions/workflows/build.yml/badge.svg)](https://github.com/remarkablemark/inline-style-parser/actions/workflows/build.yml)
[![codecov](https://codecov.io/gh/remarkablemark/inline-style-parser/branch/master/graph/badge.svg?token=B8EEK5709W)](https://codecov.io/gh/remarkablemark/inline-style-parser)
[![NPM downloads](https://badgen.net/npm/dm/inline-style-parser)](https://www.npmjs.com/package/inline-style-parser)

Inline style parser copied from [`css/lib/parse/index.js`](https://github.com/reworkcss/css/blob/v2.2.4/lib/parse/index.js):

```
InlineStyleParser(string)
```

Example:

```js
const parse = require('inline-style-parser');

parse('color: #BADA55;');
```

Output:

```js
[ { type: 'declaration',
    property: 'color',
    value: '#BADA55',
    position: Position { start: [Object], end: [Object], source: undefined } } ]
```

[JSFiddle](https://jsfiddle.net/remarkablemark/hcxbpwq8/) | [Replit](https://replit.com/@remarkablemark/inline-style-parser) | [Examples](https://github.com/remarkablemark/inline-style-parser/tree/master/examples)

## Installation

[NPM](https://www.npmjs.com/package/inline-style-parser):

```sh
npm install inline-style-parser --save
```

[Yarn](https://yarnpkg.com/package/inline-style-parser):

```sh
yarn add inline-style-parser
```

[CDN](https://unpkg.com/inline-style-parser/):

```html
<script src="https://unpkg.com/inline-style-parser@latest/dist/inline-style-parser.min.js"></script>
<script>
  window.InlineStyleParser(/* string */);
</script>
```

## Usage

Import with ES Modules:

```js
import parse from 'inline-style-parser';
```

Or require with CommonJS:

```js
const parse = require('inline-style-parser');
```

Parse single declaration:

```js
parse('left: 0');
```

Output:

```js
[
  {
    type: 'declaration',
    property: 'left',
    value: '0',
    position: {
      start: { line: 1, column: 1 },
      end: { line: 1, column: 8 },
      source: undefined
    }
  }
]
```

Parse multiple declarations:

```js
parse('left: 0; right: 100px;');
```

Output:

```js
[
  {
    type: 'declaration',
    property: 'left',
    value: '0',
    position: {
      start: { line: 1, column: 1 },
      end: { line: 1, column: 8 },
      source: undefined
    }
  },
  {
    type: 'declaration',
    property: 'right',
    value: '100px',
    position: {
      start: { line: 1, column: 10 },
      end: { line: 1, column: 22 },
      source: undefined
    }
  }
]
```

Parse declaration with missing value:

```js
parse('top:');
```

Output:

```js
[
  {
    type: 'declaration',
    property: 'top',
    value: '',
    position: {
      start: { line: 1, column: 1 },
      end: { line: 1, column: 5 },
      source: undefined
    }
  }
]
```

Parse unknown declaration:

```js
parse('answer: 42;');
```

Output:

```js
[
  {
    type: 'declaration',
    property: 'answer',
    value: '42',
    position: {
      start: { line: 1, column: 1 },
      end: { line: 1, column: 11 },
      source: undefined
    }
  }
]
```

Invalid declarations:

```js
parse('');      // []
parse();        // throws TypeError
parse(1);       // throws TypeError
parse('width'); // throws Error
parse('/*');    // throws Error
```

## Testing

Run tests:

```sh
npm test
```

Run tests in watch mode:

```sh
npm run test:watch
```

Run tests with coverage:

```sh
npm run test:coverage
```

Run tests in CI mode:

```sh
npm run test:ci
```

Lint files:

```sh
npm run lint
```

Fix lint errors:

```sh
npm run lint:fix
```

## Release

Release and publish are automated by [Release Please](https://github.com/googleapis/release-please).

## License

[MIT](https://github.com/remarkablemark/inline-style-parser/blob/master/LICENSE). See the [license](https://github.com/reworkcss/css/blob/v2.2.4/LICENSE) from the original project.


---

<p align="center">
  <a href="http://gulpjs.com">
    <img height="257" width="114" src="https://raw.githubusercontent.com/gulpjs/artwork/master/gulp-2x.png">
  </a>
</p>

# interpret

[![NPM version][npm-image]][npm-url] [![Downloads][downloads-image]][npm-url] [![Travis Build Status][travis-image]][travis-url] [![AppVeyor Build Status][appveyor-image]][appveyor-url] [![Coveralls Status][coveralls-image]][coveralls-url] [![Gitter chat][gitter-image]][gitter-url]

A dictionary of file extensions and associated module loaders.

## What is it
This is used by [Liftoff](http://github.com/tkellen/node-liftoff) to automatically require dependencies for configuration files, and by [rechoir](http://github.com/tkellen/node-rechoir) for registering module loaders.

## API

### extensions
Map file types to modules which provide a [require.extensions] loader.

```js
{
  '.babel.js': [
    {
      module: '@babel/register',
      register: function(hook) {
        // register on .js extension due to https://github.com/joyent/node/blob/v0.12.0/lib/module.js#L353
        // which only captures the final extension (.babel.js -> .js)
        hook({ extensions: '.js' });
      },
    },
    {
      module: 'babel-register',
      register: function(hook) {
        hook({ extensions: '.js' });
      },
    },
    {
      module: 'babel-core/register',
      register: function(hook) {
        hook({ extensions: '.js' });
      },
    },
    {
      module: 'babel/register',
      register: function(hook) {
        hook({ extensions: '.js' });
      },
    },
  ],
  '.babel.ts': [
    {
      module: '@babel/register',
      register: function(hook) {
        hook({ extensions: '.ts' });
      },
    },
  ],
  '.buble.js': 'buble/register',
  '.cirru': 'cirru-script/lib/register',
  '.cjsx': 'node-cjsx/register',
  '.co': 'coco',
  '.coffee': ['coffeescript/register', 'coffee-script/register', 'coffeescript', 'coffee-script'],
  '.coffee.md': ['coffeescript/register', 'coffee-script/register', 'coffeescript', 'coffee-script'],
  '.csv': 'require-csv',
  '.eg': 'earlgrey/register',
  '.esm.js': {
    module: 'esm',
    register: function(hook) {
      // register on .js extension due to https://github.com/joyent/node/blob/v0.12.0/lib/module.js#L353
      // which only captures the final extension (.babel.js -> .js)
      var esmLoader = hook(module);
      require.extensions['.js'] = esmLoader('module')._extensions['.js'];
    },
  },
  '.iced': ['iced-coffee-script/register', 'iced-coffee-script'],
  '.iced.md': 'iced-coffee-script/register',
  '.ini': 'require-ini',
  '.js': null,
  '.json': null,
  '.json5': 'json5/lib/require',
  '.jsx': [
    {
      module: '@babel/register',
      register: function(hook) {
        hook({ extensions: '.jsx' });
      },
    },
    {
      module: 'babel-register',
      register: function(hook) {
        hook({ extensions: '.jsx' });
      },
    },
    {
      module: 'babel-core/register',
      register: function(hook) {
        hook({ extensions: '.jsx' });
      },
    },
    {
      module: 'babel/register',
      register: function(hook) {
        hook({ extensions: '.jsx' });
      },
    },
    {
      module: 'node-jsx',
      register: function(hook) {
        hook.install({ extension: '.jsx', harmony: true });
      },
    },
  ],
  '.litcoffee': ['coffeescript/register', 'coffee-script/register', 'coffeescript', 'coffee-script'],
  '.liticed': 'iced-coffee-script/register',
  '.ls': ['livescript', 'LiveScript'],
  '.mjs': '/absolute/path/to/interpret/mjs-stub.js',
  '.node': null,
  '.toml': {
    module: 'toml-require',
    register: function(hook) {
      hook.install();
    },
  },
  '.ts': [
    'ts-node/register',
    'typescript-node/register',
    'typescript-register',
    'typescript-require',
    'sucrase/register/ts',
    {
      module: '@babel/register',
      register: function(hook) {
        hook({ extensions: '.ts' });
      },
    },
  ],
  '.tsx': [
    'ts-node/register',
    'typescript-node/register',
    'sucrase/register',
    {
      module: '@babel/register',
      register: function(hook) {
        hook({ extensions: '.tsx' });
      },
    },
  ],
  '.wisp': 'wisp/engine/node',
  '.xml': 'require-xml',
  '.yaml': 'require-yaml',
  '.yml': 'require-yaml',
}
```

### jsVariants
Same as above, but only include the extensions which are javascript variants.

## How to use it

Consumers should use the exported `extensions` or `jsVariants` object to determine which module should be loaded for a given extension. If a matching extension is found, consumers should do the following:

1. If the value is null, do nothing.

2. If the value is a string, try to require it.

3. If the value is an object, try to require the `module` property. If successful, the `register` property (a function) should be called with the module passed as the first argument.

4. If the value is an array, iterate over it, attempting step #2 or #3 until one of the attempts does not throw.

[require.extensions]: http://nodejs.org/api/globals.html#globals_require_extensions

[downloads-image]: http://img.shields.io/npm/dm/interpret.svg
[npm-url]: https://www.npmjs.com/package/interpret
[npm-image]: http://img.shields.io/npm/v/interpret.svg

[travis-url]: https://travis-ci.org/gulpjs/interpret
[travis-image]: http://img.shields.io/travis/gulpjs/interpret.svg?label=travis-ci

[appveyor-url]: https://ci.appveyor.com/project/gulpjs/interpret
[appveyor-image]: https://img.shields.io/appveyor/ci/gulpjs/interpret.svg?label=appveyor

[coveralls-url]: https://coveralls.io/r/gulpjs/interpret
[coveralls-image]: http://img.shields.io/coveralls/gulpjs/interpret/master.svg

[gitter-url]: https://gitter.im/gulpjs/gulp
[gitter-image]: https://badges.gitter.im/gulpjs/gulp.svg


---

2.2.4 / 2018-03-13
==================

  * Use flow strict mode (i.e. `@flow strict`).

2.2.3 / 2018-02-19
==================

  * Change license from BSD+Patents to MIT.

2.2.2 / 2016-11-15
==================

  * Add LICENSE file.
  * Misc housekeeping.

2.2.1 / 2016-03-09
==================

  * Use `NODE_ENV` variable instead of `__DEV__` to cache `process.env.NODE_ENV`.

2.2.0 / 2015-11-17
==================

  * Use `error.name` instead of `Invariant Violation`.

2.1.3 / 2015-11-17
==================

  * Remove `@provideModule` pragma.

2.1.2 / 2015-10-27
==================

  * Fix license.

2.1.1 / 2015-09-20
==================

  * Use correct SPDX license.
  * Test "browser.js" using browserify.
  * Switch from "envify" to "loose-envify".

2.1.0 / 2015-06-03
==================

  * Add "envify" as a dependency.
  * Fixed license field in "package.json".

2.0.0 / 2015-02-21
==================

  * Switch to using the "browser" field. There are now browser and server versions that respect the "format" in production.

1.0.2 / 2014-09-24
==================

  * Added tests, npmignore and gitignore.
  * Clarifications in README.

1.0.1 / 2014-09-24
==================

  * Actually include 'invariant.js'.

1.0.0 / 2014-09-24
==================

  * Initial release.


---

# invariant

[![Build Status](https://travis-ci.org/zertosh/invariant.svg?branch=master)](https://travis-ci.org/zertosh/invariant)

A mirror of Facebook's `invariant` (e.g. [React](https://github.com/facebook/react/blob/v0.13.3/src/vendor/core/invariant.js), [flux](https://github.com/facebook/flux/blob/2.0.2/src/invariant.js)).

A way to provide descriptive errors in development but generic errors in production.

## Install

With [npm](http://npmjs.org) do:

```sh
npm install invariant
```

## `invariant(condition, message)`

```js
var invariant = require('invariant');

invariant(someTruthyVal, 'This will not throw');
// No errors

invariant(someFalseyVal, 'This will throw an error with this message');
// Error: Invariant Violation: This will throw an error with this message
```

**Note:** When `process.env.NODE_ENV` is not `production`, the message is required. If omitted, `invariant` will throw regardless of the truthiness of the condition. When `process.env.NODE_ENV` is `production`, the message is optional – so they can be minified away.

### Browser

When used with [browserify](https://github.com/substack/node-browserify), it'll use `browser.js` (instead of `invariant.js`) and the [envify](https://github.com/hughsk/envify) transform will inline the value of `process.env.NODE_ENV`.

### Node

The node version is optimized around the performance implications of accessing `process.env`. The value of `process.env.NODE_ENV` is cached, and repeatedly used instead of reading `process.env`. See [Server rendering is slower with npm react #812](https://github.com/facebook/react/issues/812)


---

# ipaddr.js — an IPv6 and IPv4 address manipulation library

[![Build Status](https://github.com/whitequark/ipaddr.js/workflows/CI%20Tests/badge.svg)](https://github.com/whitequark/ipaddr.js/actions?query=workflow%3A%22CI+Tests%22)

ipaddr.js is a small (1.9K minified and gzipped) library for manipulating
IP addresses in JavaScript environments. It runs on both CommonJS runtimes
(e.g. [nodejs]) and in a web browser.

ipaddr.js allows you to verify and parse string representation of an IP
address, match it against a CIDR range or range list, determine if it falls
into some reserved ranges (examples include loopback and private ranges),
and convert between IPv4 and IPv4-mapped IPv6 addresses.

[nodejs]: http://nodejs.org

## Installation

`npm install ipaddr.js`

or

`bower install ipaddr.js`

## Older Node support

Use 2.x release for nodejs versions 10+.
Use the 1.x release for versions of nodejs older than 10.

## API

ipaddr.js defines one object in the global scope: `ipaddr`. In CommonJS,
it is exported from the module:

```js
const ipaddr = require('ipaddr.js');
```

The API consists of several global methods and two classes: ipaddr.IPv6 and ipaddr.IPv4.

### Global methods

There are four global methods defined: `ipaddr.isValid`, `ipaddr.isValidCIDR`, 
`ipaddr.parse`, and `ipaddr.process`. All of them receive a string as a single
parameter.

The `ipaddr.isValid` method returns `true` if the address is a valid IPv4 or
IPv6 address, and `false` otherwise. It does not throw any exceptions.

The `ipaddr.isValidCIDR` method returns `true` if the address is a valid IPv4 or
IPv6 address in CIDR notation, and `false` otherwise. It does not throw any exceptions.

The `ipaddr.parse` method returns an object representing the IP address,
or throws an `Error` if the passed string is not a valid representation of an
IP address.

The `ipaddr.process` method works just like the `ipaddr.parse` one, but it
automatically converts IPv4-mapped IPv6 addresses to their IPv4 counterparts
before returning. It is useful when you have a Node.js instance listening
on an IPv6 socket, and the `net.ivp6.bindv6only` sysctl parameter (or its
equivalent on non-Linux OS) is set to 0. In this case, you can accept IPv4
connections on your IPv6-only socket, but the remote address will be mangled.
Use `ipaddr.process` method to automatically demangle it.

### Object representation

Parsing methods return an object which descends from `ipaddr.IPv6` or
`ipaddr.IPv4`. These objects share some properties, but most of them differ.

#### Shared properties

One can determine the type of address by calling `addr.kind()`. It will return
either `"ipv6"` or `"ipv4"`.

An address can be converted back to its string representation with `addr.toString()`.
Note that this method:
 * does not return the original string used to create the object (in fact, there is
   no way of getting that string)
 * returns a compact representation (when it is applicable)

A `match(range, bits)` method can be used to check if the address falls into a
certain CIDR range. Note that an address can be (obviously) matched only against an address of the same type.

For example:

```js
const addr  = ipaddr.parse('2001:db8:1234::1');
const range = ipaddr.parse('2001:db8::');

addr.match(range, 32); // => true
```

Alternatively, `match` can also be called as `match([range, bits])`. In this way, it can be used together with the `parseCIDR(string)` method, which parses an IP address together with a CIDR range.

For example:

```js
const addr = ipaddr.parse('2001:db8:1234::1');

addr.match(ipaddr.parseCIDR('2001:db8::/32')); // => true
```

A `range()` method returns one of predefined names for several special ranges defined by IP protocols. The exact names (and their respective CIDR ranges) can be looked up in the source: [IPv6 ranges] and [IPv4 ranges]. Some common ones include `"unicast"` (the default one) and `"reserved"`.

You can match against your own range list by using
`ipaddr.subnetMatch(address, rangeList, defaultName)` method. It can work with a mix of IPv6 or IPv4 addresses, and accepts a name-to-subnet map as the range list. For example:

```js
const rangeList = {
  documentationOnly: [ ipaddr.parse('2001:db8::'), 32 ],
  tunnelProviders: [
    [ ipaddr.parse('2001:470::'), 32 ], // he.net
    [ ipaddr.parse('2001:5c0::'), 32 ]  // freenet6
  ]
};
ipaddr.subnetMatch(ipaddr.parse('2001:470:8:66::1'), rangeList, 'unknown'); // => "tunnelProviders"
```

The addresses can be converted to their byte representation with `toByteArray()`. (Actually, JavaScript mostly does not know about byte buffers. They are emulated with arrays of numbers, each in range of 0..255.)

```js
const bytes = ipaddr.parse('2a00:1450:8007::68').toByteArray(); // ipv6.google.com
bytes // => [42, 0x00, 0x14, 0x50, 0x80, 0x07, 0x00, <zeroes...>, 0x00, 0x68 ]
```

The `ipaddr.IPv4` and `ipaddr.IPv6` objects have some methods defined, too. All of them have the same interface for both protocols, and are similar to global methods.

`ipaddr.IPvX.isValid(string)` can be used to check if the string is a valid address for particular protocol, and `ipaddr.IPvX.parse(string)` is the error-throwing parser.

`ipaddr.IPvX.isValid(string)` uses the same format for parsing as the POSIX `inet_ntoa` function, which accepts unusual formats like `0xc0.168.1.1` or `0x10000000`. The function `ipaddr.IPv4.isValidFourPartDecimal(string)` validates the IPv4 address and also ensures that it is written in four-part decimal format.

[IPv6 ranges]: https://github.com/whitequark/ipaddr.js/blob/master/lib/ipaddr.js#L530
[IPv4 ranges]: https://github.com/whitequark/ipaddr.js/blob/master/lib/ipaddr.js#L182

#### IPv6 properties

Sometimes you will want to convert IPv6 not to a compact string representation (with the `::` substitution); the `toNormalizedString()` method will return an address where all zeroes are explicit.

For example:

```js
const addr = ipaddr.parse('2001:0db8::0001');
addr.toString(); // => '2001:db8::1'
addr.toNormalizedString(); // => '2001:db8:0:0:0:0:0:1'
```

The `isIPv4MappedAddress()` method will return `true` if this address is an IPv4-mapped
one, and `toIPv4Address()` will return an IPv4 object address.

To access the underlying binary representation of the address, use `addr.parts`.

```js
const addr = ipaddr.parse('2001:db8:10::1234:DEAD');
addr.parts // => [0x2001, 0xdb8, 0x10, 0, 0, 0, 0x1234, 0xdead]
```

A IPv6 zone index can be accessed via `addr.zoneId`:

```js
const addr = ipaddr.parse('2001:db8::%eth0');
addr.zoneId // => 'eth0'
```

#### IPv4 properties

`toIPv4MappedAddress()` will return a corresponding IPv4-mapped IPv6 address.

To access the underlying representation of the address, use `addr.octets`.

```js
const addr = ipaddr.parse('192.168.1.1');
addr.octets // => [192, 168, 1, 1]
```

`prefixLengthFromSubnetMask()` will return a CIDR prefix length for a valid IPv4 netmask or
null if the netmask is not valid.

```js
ipaddr.IPv4.parse('255.255.255.240').prefixLengthFromSubnetMask() == 28
ipaddr.IPv4.parse('255.192.164.0').prefixLengthFromSubnetMask()  == null
```

`subnetMaskFromPrefixLength()` will return an IPv4 netmask for a valid CIDR prefix length.

```js
ipaddr.IPv4.subnetMaskFromPrefixLength(24) == '255.255.255.0'
ipaddr.IPv4.subnetMaskFromPrefixLength(29) == '255.255.255.248'
```

`broadcastAddressFromCIDR()` will return the broadcast address for a given IPv4 interface and netmask in CIDR notation.
```js
ipaddr.IPv4.broadcastAddressFromCIDR('172.0.0.1/24') == '172.0.0.255'
```
`networkAddressFromCIDR()` will return the network address for a given IPv4 interface and netmask in CIDR notation.
```js
ipaddr.IPv4.networkAddressFromCIDR('172.0.0.1/24') == '172.0.0.0'
```

#### Conversion

IPv4 and IPv6 can be converted bidirectionally to and from network byte order (MSB) byte arrays.

The `fromByteArray()` method will take an array and create an appropriate IPv4 or IPv6 object
if the input satisfies the requirements. For IPv4 it has to be an array of four 8-bit values,
while for IPv6 it has to be an array of sixteen 8-bit values.

For example:
```js
const addr = ipaddr.fromByteArray([0x7f, 0, 0, 1]);
addr.toString(); // => '127.0.0.1'
```

or

```js
const addr = ipaddr.fromByteArray([0x20, 1, 0xd, 0xb8, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1])
addr.toString(); // => '2001:db8::1'
```

Both objects also offer a `toByteArray()` method, which returns an array in network byte order (MSB).

For example:
```js
const addr = ipaddr.parse('127.0.0.1');
addr.toByteArray(); // => [0x7f, 0, 0, 1]
```

or

```js
const addr = ipaddr.parse('2001:db8::1');
addr.toByteArray(); // => [0x20, 1, 0xd, 0xb8, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1]
```


---

# is-alphabetical

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]

Check if a character is alphabetical.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`isAlphabetical(character|code)`](#isalphabeticalcharactercode)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Security](#security)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This is a function that checks if a given character is ASCII alphabetical:
matching `[a-z]`, case insensitive.

## When should I use this?

Not often, as it’s relatively simple to do yourself.
This package exists because it’s needed in several related packages, at which
point it becomes useful to defer to one shared function.

## Install

This package is [ESM only][esm].
In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]:

```sh
npm install is-alphabetical
```

In Deno with [Skypack][]:

```js
import {isAlphabetical} from 'https://cdn.skypack.dev/is-alphabetical@2?dts'
```

In browsers with [Skypack][]:

```html
<script type="module">
  import {isAlphabetical} from 'https://cdn.skypack.dev/is-alphabetical@2?min'
</script>
```

## Use

```js
import {isAlphabetical} from 'is-alphabetical'

isAlphabetical('a') // => true
isAlphabetical('B') // => true
isAlphabetical('0') // => false
isAlphabetical('💩') // => false
```

## API

This package exports the following identifier: `isAlphabetical`.
There is no default export.

### `isAlphabetical(character|code)`

Check whether the given character code (`number`), or the character code at the
first position (`string`), is alphabetical.

## Types

This package is fully typed with [TypeScript][].

## Compatibility

This package is at least compatible with all maintained versions of Node.js.
As of now, that is Node.js 12.20+, 14.14+, and 16.0+.
It also works in Deno and modern browsers.

## Security

This package is safe.

## Related

*   [`wooorm/is-decimal`](https://github.com/wooorm/is-decimal)
*   [`wooorm/is-hexadecimal`](https://github.com/wooorm/is-hexadecimal)
*   [`wooorm/is-alphanumerical`](https://github.com/wooorm/is-alphanumerical)
*   [`wooorm/is-whitespace-character`](https://github.com/wooorm/is-whitespace-character)
*   [`wooorm/is-word-character`](https://github.com/wooorm/is-word-character)

## Contribute

Yes please!
See [How to Contribute to Open Source][contribute].

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/wooorm/is-alphabetical/workflows/main/badge.svg

[build]: https://github.com/wooorm/is-alphabetical/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/is-alphabetical.svg

[coverage]: https://codecov.io/github/wooorm/is-alphabetical

[downloads-badge]: https://img.shields.io/npm/dm/is-alphabetical.svg

[downloads]: https://www.npmjs.com/package/is-alphabetical

[size-badge]: https://img.shields.io/bundlephobia/minzip/is-alphabetical.svg

[size]: https://bundlephobia.com/result?p=is-alphabetical

[npm]: https://docs.npmjs.com/cli/install

[skypack]: https://www.skypack.dev

[license]: license

[author]: https://wooorm.com

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[typescript]: https://www.typescriptlang.org

[contribute]: https://opensource.guide/how-to-contribute/


---

# is-alphanumerical

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]

Check if a character is alphanumerical.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`isAlphanumerical(character)`](#isalphanumericalcharacter)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Security](#security)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This is a function that checks if a given character is ASCII alphanumerical:
it matches `[a-zA-Z0-9]`.

## When should I use this?

Not often, as it’s relatively simple to do yourself.
This package exists because it’s needed in several related packages, at which
point it becomes useful to defer to one shared function.

## Install

This package is [ESM only][esm].
In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]:

```sh
npm install is-alphanumerical
```

In Deno with [Skypack][]:

```js
import {isAlphanumerical} from 'https://cdn.skypack.dev/is-alphanumerical@2?dts'
```

In browsers with [Skypack][]:

```html
<script type="module">
  import {isAlphanumerical} from 'https://cdn.skypack.dev/is-alphanumerical@2?min'
</script>
```

## Use

```js
import {isAlphanumerical} from 'is-alphanumerical'

isAlphanumerical('a') // => true
isAlphanumerical('Z') // => true
isAlphanumerical('0') // => true
isAlphanumerical(' ') // => false
isAlphanumerical('💩') // => false
```

## API

This package exports the following identifier: `isAlphanumerical`.
There is no default export.

### `isAlphanumerical(character)`

Check whether the given character code (`number`), or the character code at the
first position (`string`), is alphanumerical.

## Types

This package is fully typed with [TypeScript][].

## Compatibility

This package is at least compatible with all maintained versions of Node.js.
As of now, that is Node.js 12.20+, 14.14+, and 16.0+.
It also works in Deno and modern browsers.

## Security

This package is safe.

## Related

*   [`wooorm/is-alphabetical`](https://github.com/wooorm/is-alphabetical)
*   [`wooorm/is-decimal`](https://github.com/wooorm/is-decimal)
*   [`wooorm/is-hexadecimal`](https://github.com/wooorm/is-hexadecimal)
*   [`wooorm/is-whitespace-character`](https://github.com/wooorm/is-whitespace-character)
*   [`wooorm/is-word-character`](https://github.com/wooorm/is-word-character)

## Contribute

Yes please!
See [How to Contribute to Open Source][contribute].

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/wooorm/is-alphanumerical/workflows/main/badge.svg

[build]: https://github.com/wooorm/is-alphanumerical/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/is-alphanumerical.svg

[coverage]: https://codecov.io/github/wooorm/is-alphanumerical

[downloads-badge]: https://img.shields.io/npm/dm/is-alphanumerical.svg

[downloads]: https://www.npmjs.com/package/is-alphanumerical

[size-badge]: https://img.shields.io/bundlephobia/minzip/is-alphanumerical.svg

[size]: https://bundlephobia.com/result?p=is-alphanumerical

[npm]: https://docs.npmjs.com/cli/install

[skypack]: https://www.skypack.dev

[license]: license

[author]: https://wooorm.com

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[typescript]: https://www.typescriptlang.org

[contribute]: https://opensource.guide/how-to-contribute/


---

# node-is-arrayish [![Travis-CI.org Build Status](https://img.shields.io/travis/Qix-/node-is-arrayish.svg?style=flat-square)](https://travis-ci.org/Qix-/node-is-arrayish) [![Coveralls.io Coverage Rating](https://img.shields.io/coveralls/Qix-/node-is-arrayish.svg?style=flat-square)](https://coveralls.io/r/Qix-/node-is-arrayish)
> Determines if an object can be used like an Array

## Example
```javascript
var isArrayish = require('is-arrayish');

isArrayish([]); // true
isArrayish({__proto__: []}); // true
isArrayish({}); // false
isArrayish({length:10}); // false
```

## License
Licensed under the [MIT License](http://opensource.org/licenses/MIT).
You can find a copy of it in [LICENSE](LICENSE).


---

# is-binary-path [![Build Status](https://travis-ci.org/sindresorhus/is-binary-path.svg?branch=master)](https://travis-ci.org/sindresorhus/is-binary-path)

> Check if a file path is a binary file


## Install

```
$ npm install is-binary-path
```


## Usage

```js
const isBinaryPath = require('is-binary-path');

isBinaryPath('source/unicorn.png');
//=> true

isBinaryPath('source/unicorn.txt');
//=> false
```


## Related

- [binary-extensions](https://github.com/sindresorhus/binary-extensions) - List of binary file extensions
- [is-text-path](https://github.com/sindresorhus/is-text-path) - Check if a filepath is a text file


## License

MIT © [Sindre Sorhus](https://sindresorhus.com), [Paul Miller](https://paulmillr.com)


---

# Changelog

## v3.0.1

- remove `.github` folder from published files ([dd15229](https://github.com/watson/is-ci/commit/dd15229))

## v3.0.0

Breaking changes:

- update to `ci-info` v3. This drops support for EOL node versions 6, 13

## v2.0.0

Breaking changes:

- Drop support for Node.js end-of-life versions: 0.10, 0.12, 4, 5, 7,
  and 9

Other changes:

See [ci-info
changelog](https://github.com/watson/ci-info/blob/master/CHANGELOG.md#v200)
for a list of newly supported CI servers.


---

# is-ci

Returns `true` if the current environment is a Continuous Integration
server.

Please [open an issue](https://github.com/watson/is-ci/issues) if your
CI server isn't properly detected :)

[![npm](https://img.shields.io/npm/v/is-ci.svg)](https://www.npmjs.com/package/is-ci)
[![Tests](https://github.com/watson/is-ci/workflows/Tests/badge.svg)](https://github.com/watson/is-ci/actions)
[![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat)](https://github.com/feross/standard)

## Installation

```bash
npm install is-ci --save
```

## Programmatic Usage

```js
const isCI = require('is-ci')

if (isCI) {
  console.log('The code is running on a CI server')
}
```

## CLI Usage

For CLI usage you need to have the `is-ci` executable in your `PATH`.
There's a few ways to do that:

- Either install the module globally using `npm install is-ci -g`
- Or add the module as a dependency to your app in which case it can be
  used inside your package.json scripts as is
- Or provide the full path to the executable, e.g.
  `./node_modules/.bin/is-ci`

```bash
is-ci && echo "This is a CI server"
```

## Supported CI tools

Refer to [ci-info](https://github.com/watson/ci-info#supported-ci-tools) docs for all supported CI's

## License

[MIT](LICENSE)


---

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [v2.16.1](https://github.com/inspect-js/is-core-module/compare/v2.16.0...v2.16.1) - 2024-12-21

### Fixed

- [Fix] `node:sqlite` is available in node ^22.13 [`#17`](https://github.com/inspect-js/is-core-module/issues/17)

## [v2.16.0](https://github.com/inspect-js/is-core-module/compare/v2.15.1...v2.16.0) - 2024-12-13

### Commits

- [New] add `node:sqlite` [`1ee94d2`](https://github.com/inspect-js/is-core-module/commit/1ee94d20857e22cdb24e9b4bb1a2097f2e03e26f)
- [Dev Deps] update `auto-changelog`, `tape` [`aa84aa3`](https://github.com/inspect-js/is-core-module/commit/aa84aa34face677f14e08ec1c737f0c4bba27260)

## [v2.15.1](https://github.com/inspect-js/is-core-module/compare/v2.15.0...v2.15.1) - 2024-08-21

### Commits

- [Tests] add `process.getBuiltinModule` tests [`28c7791`](https://github.com/inspect-js/is-core-module/commit/28c7791c196d58c64cfdf638b7e68ed1b62a4da0)
- [Fix] `test/mock_loader` is no longer exposed as of v22.7 [`68b08b0`](https://github.com/inspect-js/is-core-module/commit/68b08b0d7963447dbffa5142e8810dca550383af)
- [Tests] replace `aud` with `npm audit` [`32f8060`](https://github.com/inspect-js/is-core-module/commit/32f806026dac14f9016be4401a643851240c76b9)
- [Dev Deps] update `mock-property` [`f7d3c8f`](https://github.com/inspect-js/is-core-module/commit/f7d3c8f01e922be49621683eb41477c4f50522e1)
- [Dev Deps] add missing peer dep [`eaee885`](https://github.com/inspect-js/is-core-module/commit/eaee885b67238819e9c8ed5bd2098766e1d05331)

## [v2.15.0](https://github.com/inspect-js/is-core-module/compare/v2.14.0...v2.15.0) - 2024-07-17

### Commits

- [New] add `node:sea` [`2819fb3`](https://github.com/inspect-js/is-core-module/commit/2819fb3eae312fa64643bc5430ebd06ec0f3fb88)

## [v2.14.0](https://github.com/inspect-js/is-core-module/compare/v2.13.1...v2.14.0) - 2024-06-20

### Commits

- [Dev Deps] update `@ljharb/eslint-config`, `aud`, `mock-property`, `npmignore`, `tape` [`0e43200`](https://github.com/inspect-js/is-core-module/commit/0e432006d97237cc082d41e6a593e87c81068364)
- [meta] add missing `engines.node` [`4ea3af8`](https://github.com/inspect-js/is-core-module/commit/4ea3af88891a1d4f96026f0ec0ef08c67cd1bd24)
- [New] add `test/mock_loader` [`e9fbd29`](https://github.com/inspect-js/is-core-module/commit/e9fbd2951383be070aeffb9ebbf3715237282610)
- [Deps] update `hasown` [`57f1940`](https://github.com/inspect-js/is-core-module/commit/57f1940947b3e368abdf529232d2f17d88909358)

## [v2.13.1](https://github.com/inspect-js/is-core-module/compare/v2.13.0...v2.13.1) - 2023-10-20

### Commits

- [Refactor] use `hasown` instead of `has` [`0e52096`](https://github.com/inspect-js/is-core-module/commit/0e520968b0a725276b67420ab4b877486b243ae0)
- [Dev Deps] update `mock-property`, `tape` [`8736b35`](https://github.com/inspect-js/is-core-module/commit/8736b35464d0f297b55da2c6b30deee04b8303c5)

## [v2.13.0](https://github.com/inspect-js/is-core-module/compare/v2.12.1...v2.13.0) - 2023-08-05

### Commits

- [Dev Deps] update `@ljharb/eslint-config`, `aud`, `semver`, `tape` [`c75b263`](https://github.com/inspect-js/is-core-module/commit/c75b263d047cb53430c3970107e5eb64d6cd6c0c)
- [New] `node:test/reporters` and `wasi`/`node:wasi` are in v18.17 [`d76cbf8`](https://github.com/inspect-js/is-core-module/commit/d76cbf8e9b208acfd98913fed5a5f45cb15fe5dc)

## [v2.12.1](https://github.com/inspect-js/is-core-module/compare/v2.12.0...v2.12.1) - 2023-05-16

### Commits

- [Fix] `test/reporters` now requires the `node:` prefix as of v20.2 [`12183d0`](https://github.com/inspect-js/is-core-module/commit/12183d0d8e4edf56b6ce18a1b3be54bfce10175b)

## [v2.12.0](https://github.com/inspect-js/is-core-module/compare/v2.11.0...v2.12.0) - 2023-04-10

### Commits

- [actions] update rebase action to use reusable workflow [`c0a7251`](https://github.com/inspect-js/is-core-module/commit/c0a7251f734f3c621932c5fcdfd1bf966b42ca32)
- [Dev Deps] update `@ljharb/eslint-config`, `aud`, `tape` [`9ae8b7f`](https://github.com/inspect-js/is-core-module/commit/9ae8b7fac03c369861d0991b4a2ce8d4848e6a7d)
- [New] `test/reporters` added in v19.9, `wasi` added in v20 [`9d5341a`](https://github.com/inspect-js/is-core-module/commit/9d5341ab32053f25b7fa7db3c0e18461db24a79c)
- [Dev Deps] add missing `in-publish` dep [`5980245`](https://github.com/inspect-js/is-core-module/commit/59802456e9ac919fa748f53be9d8fbf304a197df)

## [v2.11.0](https://github.com/inspect-js/is-core-module/compare/v2.10.0...v2.11.0) - 2022-10-18

### Commits

- [meta] use `npmignore` to autogenerate an npmignore file [`3360011`](https://github.com/inspect-js/is-core-module/commit/33600118857b46177178072fba2affcdeb009d12)
- [Dev Deps] update `aud`, `tape` [`651c6b0`](https://github.com/inspect-js/is-core-module/commit/651c6b0cc2799d4130866cf43ad333dcade3d26c)
- [New] `inspector/promises` and `node:inspector/promises` is now available in node 19 [`22d332f`](https://github.com/inspect-js/is-core-module/commit/22d332fe22ac050305444e0781ff85af819abcb0)

## [v2.10.0](https://github.com/inspect-js/is-core-module/compare/v2.9.0...v2.10.0) - 2022-08-03

### Commits

- [New] `node:test` is now available in node ^16.17 [`e8fd36e`](https://github.com/inspect-js/is-core-module/commit/e8fd36e9b86c917775a07cc473b62a3294f459f2)
- [Tests] improve skip message [`c014a4c`](https://github.com/inspect-js/is-core-module/commit/c014a4c0cd6eb15fff573ae4709191775e70cab4)

## [v2.9.0](https://github.com/inspect-js/is-core-module/compare/v2.8.1...v2.9.0) - 2022-04-19

### Commits

- [New] add `node:test`, in node 18+ [`f853eca`](https://github.com/inspect-js/is-core-module/commit/f853eca801d0a7d4e1dbb670f1b6d9837d9533c5)
- [Tests] use `mock-property` [`03b3644`](https://github.com/inspect-js/is-core-module/commit/03b3644dff4417f4ba5a7d0aa0138f5f6b3e5c46)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `aud`, `auto-changelog`, `tape` [`7c0e2d0`](https://github.com/inspect-js/is-core-module/commit/7c0e2d06ed2a89acf53abe2ab34d703ed5b03455)
- [meta] simplify "exports" [`d6ed201`](https://github.com/inspect-js/is-core-module/commit/d6ed201eba7fbba0e59814a9050fc49a6e9878c8)

## [v2.8.1](https://github.com/inspect-js/is-core-module/compare/v2.8.0...v2.8.1) - 2022-01-05

### Commits

- [actions] reuse common workflows [`cd2cf9b`](https://github.com/inspect-js/is-core-module/commit/cd2cf9b3b66c8d328f65610efe41e9325db7716d)
- [Fix] update node 0.4 results [`062195d`](https://github.com/inspect-js/is-core-module/commit/062195d89f0876a88b95d378b43f7fcc1205bc5b)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `safe-publish-latest`, `tape` [`0790b62`](https://github.com/inspect-js/is-core-module/commit/0790b6222848c6167132f9f73acc3520fa8d1298)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `tape` [`7d139a6`](https://github.com/inspect-js/is-core-module/commit/7d139a6d767709eabf0a0251e074ec1fb230c06e)
- [Tests] run `nyc` in `tests-only`, not `test` [`780e8a0`](https://github.com/inspect-js/is-core-module/commit/780e8a049951c71cf78b1707f0871c48a28bde14)

## [v2.8.0](https://github.com/inspect-js/is-core-module/compare/v2.7.0...v2.8.0) - 2021-10-14

### Commits

- [actions] update codecov uploader [`0cfe94e`](https://github.com/inspect-js/is-core-module/commit/0cfe94e106a7d005ea03e008c0a21dec13a77904)
- [New] add `readline/promises` to node v17+ [`4f78c30`](https://github.com/inspect-js/is-core-module/commit/4f78c3008b1b58b4db6dc91d99610b1bc859da7e)
- [Tests] node ^14.18 supports `node:` prefixes for CJS [`43e2f17`](https://github.com/inspect-js/is-core-module/commit/43e2f177452cea2f0eaf34f61b5407217bbdb6f4)

## [v2.7.0](https://github.com/inspect-js/is-core-module/compare/v2.6.0...v2.7.0) - 2021-09-27

### Commits

- [New] node `v14.18` added `node:`-prefixed core modules to `require` [`6d943ab`](https://github.com/inspect-js/is-core-module/commit/6d943abe81382b9bbe344384d80fbfebe1cc0526)
- [Tests] add coverage for Object.prototype pollution [`c6baf5f`](https://github.com/inspect-js/is-core-module/commit/c6baf5f942311a1945c1af41167bb80b84df2af7)
- [Dev Deps] update `@ljharb/eslint-config` [`6717f00`](https://github.com/inspect-js/is-core-module/commit/6717f000d063ea57beb772bded36c2f056ac404c)
- [eslint] fix linter warning [`594c10b`](https://github.com/inspect-js/is-core-module/commit/594c10bb7d39d7eb00925c90924199ff596184b2)
- [meta] add `sideEffects` flag [`c32cfa5`](https://github.com/inspect-js/is-core-module/commit/c32cfa5195632944c4dd4284a142b8476e75be13)

## [v2.6.0](https://github.com/inspect-js/is-core-module/compare/v2.5.0...v2.6.0) - 2021-08-17

### Commits

- [Dev Deps] update `eslint`, `tape` [`6cc928f`](https://github.com/inspect-js/is-core-module/commit/6cc928f8a4bba66aeeccc4f6beeac736d4bd3081)
- [New] add `stream/consumers` to node `&gt;= 16.7` [`a1a423e`](https://github.com/inspect-js/is-core-module/commit/a1a423e467e4cc27df180234fad5bab45943e67d)
- [Refactor] Remove duplicated `&&` operand [`86faea7`](https://github.com/inspect-js/is-core-module/commit/86faea738213a2433c62d1098488dc9314dca832)
- [Tests] include prereleases [`a4da7a6`](https://github.com/inspect-js/is-core-module/commit/a4da7a6abf7568e2aa4fd98e69452179f1850963)

## [v2.5.0](https://github.com/inspect-js/is-core-module/compare/v2.4.0...v2.5.0) - 2021-07-12

### Commits

- [Dev Deps] update `auto-changelog`, `eslint` [`6334cc9`](https://github.com/inspect-js/is-core-module/commit/6334cc94f3af7469685bd8f236740991baaf2705)
- [New] add `stream/web` to node v16.5+ [`17ac59b`](https://github.com/inspect-js/is-core-module/commit/17ac59b662d63e220a2e5728625f005c24f177b2)

## [v2.4.0](https://github.com/inspect-js/is-core-module/compare/v2.3.0...v2.4.0) - 2021-05-09

### Commits

- [readme] add actions and codecov badges [`82b7faa`](https://github.com/inspect-js/is-core-module/commit/82b7faa12b56dbe47fbea67e1a5b9e447027ba40)
- [Dev Deps] update `@ljharb/eslint-config`, `aud` [`8096868`](https://github.com/inspect-js/is-core-module/commit/8096868c024a161ccd4d44110b136763e92eace8)
- [Dev Deps] update `eslint` [`6726824`](https://github.com/inspect-js/is-core-module/commit/67268249b88230018c510f6532a8046d7326346f)
- [New] add `diagnostics_channel` to node `^14.17` [`86c6563`](https://github.com/inspect-js/is-core-module/commit/86c65634201b8ff9b3e48a9a782594579c7f5c3c)
- [meta] fix prepublish script [`697a01e`](https://github.com/inspect-js/is-core-module/commit/697a01e3c9c0be074066520954f30fb28532ec57)

## [v2.3.0](https://github.com/inspect-js/is-core-module/compare/v2.2.0...v2.3.0) - 2021-04-24

### Commits

- [meta] do not publish github action workflow files [`060d4bb`](https://github.com/inspect-js/is-core-module/commit/060d4bb971a29451c19ff336eb56bee27f9fa95a)
- [New] add support for `node:` prefix, in node 16+ [`7341223`](https://github.com/inspect-js/is-core-module/commit/73412230a769f6e81c05eea50b6520cebf54ed2f)
- [actions] use `node/install` instead of `node/run`; use `codecov` action [`016269a`](https://github.com/inspect-js/is-core-module/commit/016269abae9f6657a5254adfbb813f09a05067f9)
- [patch] remove unneeded `.0` in version ranges [`cb466a6`](https://github.com/inspect-js/is-core-module/commit/cb466a6d89e52b8389e5c12715efcd550c41cea3)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `aud`, `tape` [`c9f9c39`](https://github.com/inspect-js/is-core-module/commit/c9f9c396ace60ef81906f98059c064e6452473ed)
- [actions] update workflows [`3ee4a89`](https://github.com/inspect-js/is-core-module/commit/3ee4a89fd5a02fccd43882d905448ea6a98e9a3c)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config` [`dee4fed`](https://github.com/inspect-js/is-core-module/commit/dee4fed79690c1d43a22f7fa9426abebdc6d727f)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config` [`7d046ba`](https://github.com/inspect-js/is-core-module/commit/7d046ba07ae8c9292e43652694ca808d7b309de8)
- [meta] use `prepublishOnly` script for npm 7+ [`149e677`](https://github.com/inspect-js/is-core-module/commit/149e6771a5ede6d097e71785b467a9c4b4977cc7)
- [readme] remove travis badge [`903b51d`](https://github.com/inspect-js/is-core-module/commit/903b51d6b69b98abeabfbc3695c345b02646f19c)

## [v2.2.0](https://github.com/inspect-js/is-core-module/compare/v2.1.0...v2.2.0) - 2020-11-26

### Commits

- [Tests] migrate tests to Github Actions [`c919f57`](https://github.com/inspect-js/is-core-module/commit/c919f573c0a92d10a0acad0b650b5aecb033d426)
- [patch] `core.json`: %s/    /\t/g [`db3f685`](https://github.com/inspect-js/is-core-module/commit/db3f68581f53e73cc09cd675955eb1bdd6a5a39b)
- [Tests] run `nyc` on all tests [`b2f925f`](https://github.com/inspect-js/is-core-module/commit/b2f925f8866f210ef441f39fcc8cc42692ab89b1)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `aud`; add `safe-publish-latest` [`89f02a2`](https://github.com/inspect-js/is-core-module/commit/89f02a2b4162246dea303a6ee31bb9a550b05c72)
- [New] add `path/posix`, `path/win32`, `util/types` [`77f94f1`](https://github.com/inspect-js/is-core-module/commit/77f94f1e90ffd7c0be2a3f1aa8574ebf7fd981b3)

## [v2.1.0](https://github.com/inspect-js/is-core-module/compare/v2.0.0...v2.1.0) - 2020-11-04

### Commits

- [Dev Deps] update `eslint` [`5e0034e`](https://github.com/inspect-js/is-core-module/commit/5e0034eae57c09c8f1bd769f502486a00f56c6e4)
- [New] Add `diagnostics_channel` [`c2d83d0`](https://github.com/inspect-js/is-core-module/commit/c2d83d0a0225a1a658945d9bab7036ea347d29ec)

## [v2.0.0](https://github.com/inspect-js/is-core-module/compare/v1.0.2...v2.0.0) - 2020-09-29

### Commits

- v2 implementation [`865aeb5`](https://github.com/inspect-js/is-core-module/commit/865aeb5ca0e90248a3dfff5d7622e4751fdeb9cd)
- Only apps should have lockfiles [`5a5e660`](https://github.com/inspect-js/is-core-module/commit/5a5e660d568e37eb44e17fb1ebb12a105205fc2b)
- Initial commit for v2 [`5a51524`](https://github.com/inspect-js/is-core-module/commit/5a51524e06f92adece5fbb138c69b7b9748a2348)
- Tests [`116eae4`](https://github.com/inspect-js/is-core-module/commit/116eae4fccd01bc72c1fd3cc4b7561c387afc496)
- [meta] add `auto-changelog` [`c24388b`](https://github.com/inspect-js/is-core-module/commit/c24388bee828d223040519d1f5b226ca35beee63)
- [actions] add "Automatic Rebase" and "require allow edits" actions [`34292db`](https://github.com/inspect-js/is-core-module/commit/34292dbcbadae0868aff03c22dbd8b7b8a11558a)
- [Tests] add `npm run lint` [`4f9eeee`](https://github.com/inspect-js/is-core-module/commit/4f9eeee7ddff10698bbf528620f4dc8d4fa3e697)
- [readme] fix travis badges, https all URLs [`e516a73`](https://github.com/inspect-js/is-core-module/commit/e516a73b0dccce20938c432b1ba512eae8eff9e9)
- [meta] create FUNDING.yml [`1aabebc`](https://github.com/inspect-js/is-core-module/commit/1aabebca98d01f8a04e46bc2e2520fa93cf21ac6)
- [Fix] `domain`: domain landed sometime &gt; v0.7.7 and &lt;= v0.7.12 [`2df7d37`](https://github.com/inspect-js/is-core-module/commit/2df7d37595d41b15eeada732b706b926c2771655)
- [Fix] `sys`: worked in 0.6, not 0.7, and 0.8+ [`a75c134`](https://github.com/inspect-js/is-core-module/commit/a75c134229e1e9441801f6b73f6a52489346eb65)

## [v1.0.2](https://github.com/inspect-js/is-core-module/compare/v1.0.1...v1.0.2) - 2014-09-28

### Commits

- simpler [`66fe90f`](https://github.com/inspect-js/is-core-module/commit/66fe90f9771581b9adc0c3900baa52c21b5baea2)

## [v1.0.1](https://github.com/inspect-js/is-core-module/compare/v1.0.0...v1.0.1) - 2014-09-28

### Commits

- remove stupid [`f21f906`](https://github.com/inspect-js/is-core-module/commit/f21f906f882c2bd656a5fc5ed6fbe48ddaffb2ac)
- update readme [`1eff0ec`](https://github.com/inspect-js/is-core-module/commit/1eff0ec69798d1ec65771552d1562911e90a8027)

## v1.0.0 - 2014-09-28

### Commits

- init [`48e5e76`](https://github.com/inspect-js/is-core-module/commit/48e5e76cac378fddb8c1f7d4055b8dfc943d6b96)


---

# is-core-module <sup>[![Version Badge][2]][1]</sup>

[![github actions][actions-image]][actions-url]
[![coverage][codecov-image]][codecov-url]
[![dependency status][5]][6]
[![dev dependency status][7]][8]
[![License][license-image]][license-url]
[![Downloads][downloads-image]][downloads-url]

[![npm badge][11]][1]

Is this specifier a node.js core module? Optionally provide a node version to check; defaults to the current node version.

## Example

```js
var isCore = require('is-core-module');
var assert = require('assert');
assert(isCore('fs'));
assert(!isCore('butts'));
```

## Tests
Clone the repo, `npm install`, and run `npm test`

[1]: https://npmjs.org/package/is-core-module
[2]: https://versionbadg.es/inspect-js/is-core-module.svg
[5]: https://david-dm.org/inspect-js/is-core-module.svg
[6]: https://david-dm.org/inspect-js/is-core-module
[7]: https://david-dm.org/inspect-js/is-core-module/dev-status.svg
[8]: https://david-dm.org/inspect-js/is-core-module#info=devDependencies
[11]: https://nodei.co/npm/is-core-module.png?downloads=true&stars=true
[license-image]: https://img.shields.io/npm/l/is-core-module.svg
[license-url]: LICENSE
[downloads-image]: https://img.shields.io/npm/dm/is-core-module.svg
[downloads-url]: https://npm-stat.com/charts.html?package=is-core-module
[codecov-image]: https://codecov.io/gh/inspect-js/is-core-module/branch/main/graphs/badge.svg
[codecov-url]: https://app.codecov.io/gh/inspect-js/is-core-module/
[actions-image]: https://img.shields.io/endpoint?url=https://github-actions-badge-u3jn4tfpocch.runkit.sh/inspect-js/is-core-module
[actions-url]: https://github.com/inspect-js/is-core-module/actions


---

# is-decimal

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]

Check if a character is a decimal.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`isDecimal(character|code)`](#isdecimalcharactercode)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Security](#security)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This is a function that checks if a given character is an ASCII decimal.

## When should I use this?

Not often, as it’s relatively simple to do yourself.
This package exists because it’s needed in several related packages, at which
point it becomes useful to defer to one shared function.

## Install

This package is [ESM only][esm].
In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]:

```sh
npm install is-decimal
```

In Deno with [Skypack][]:

```js
import {isDecimal} from 'https://cdn.skypack.dev/is-decimal@2?dts'
```

In browsers with [Skypack][]:

```html
<script type="module">
  import {isDecimal} from 'https://cdn.skypack.dev/is-decimal@2?min'
</script>
```

## Use

```js
import {isDecimal} from 'is-decimal'

isDecimal('0') // => true
isDecimal('9') // => true
isDecimal('a') // => false
isDecimal('💩') // => false
```

## API

This package exports the following identifiers: `isDecimal`.
There is no default export.

### `isDecimal(character|code)`

Check whether the given character code (`number`), or the character code at the
first position (`string`), is decimal.

## Types

This package is fully typed with [TypeScript][].

## Compatibility

This package is at least compatible with all maintained versions of Node.js.
As of now, that is Node.js 12.20+, 14.14+, and 16.0+.
It also works in Deno and modern browsers.

## Security

This package is safe.

## Related

*   [`wooorm/is-alphabetical`](https://github.com/wooorm/is-alphabetical)
*   [`wooorm/is-hexadecimal`](https://github.com/wooorm/is-hexadecimal)
*   [`wooorm/is-whitespace-character`](https://github.com/wooorm/is-whitespace-character)
*   [`wooorm/is-word-character`](https://github.com/wooorm/is-word-character)

## Contribute

Yes please!
See [How to Contribute to Open Source][contribute].

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/wooorm/is-decimal/workflows/main/badge.svg

[build]: https://github.com/wooorm/is-decimal/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/is-decimal.svg

[coverage]: https://codecov.io/github/wooorm/is-decimal

[downloads-badge]: https://img.shields.io/npm/dm/is-decimal.svg

[downloads]: https://www.npmjs.com/package/is-decimal

[size-badge]: https://img.shields.io/bundlephobia/minzip/is-decimal.svg

[size]: https://bundlephobia.com/result?p=is-decimal

[npm]: https://docs.npmjs.com/cli/install

[skypack]: https://www.skypack.dev

[license]: license

[author]: https://wooorm.com

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[typescript]: https://www.typescriptlang.org

[contribute]: https://opensource.guide/how-to-contribute/


---

# is-docker

> Check if the process is running inside a Docker container

## Install

```
$ npm install is-docker
```

## Usage

```js
const isDocker = require('is-docker');

if (isDocker()) {
	console.log('Running inside a Docker container');
}
```

## CLI

```
$ is-docker
```

Exits with code 0 if inside a Docker container and 2 if not.


---

# is-extendable [![NPM version](https://badge.fury.io/js/is-extendable.svg)](http://badge.fury.io/js/is-extendable)

> Returns true if a value is any of the object types: array, regexp, plain object, function or date. This is useful for determining if a value can be extended, e.g. "can the value have keys?"

## Install

Install with [npm](https://www.npmjs.com/)

```sh
$ npm i is-extendable --save
```

## Usage

```js
var isExtendable = require('is-extendable');
```

Returns true if the value is any of the following:

* `array`
* `regexp`
* `plain object`
* `function`
* `date`
* `error`

## Notes

All objects in JavaScript can have keys, but it's a pain to check for this, since we ether need to verify that the value is not `null` or `undefined` and:

* the value is not a primitive, or
* that the object is an `object`, `function`

Also note that an `extendable` object is not the same as an [extensible object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/isExtensible), which is one that (in es6) is not sealed, frozen, or marked as non-extensible using `preventExtensions`.

## Related projects

* [assign-deep](https://github.com/jonschlinkert/assign-deep): Deeply assign the enumerable properties of source objects to a destination object.
* [extend-shallow](https://github.com/jonschlinkert/extend-shallow): Extend an object with the properties of additional objects. node.js/javascript util.
* [isobject](https://github.com/jonschlinkert/isobject): Returns true if the value is an object and not an array or null.
* [is-plain-object](https://github.com/jonschlinkert/is-plain-object): Returns true if an object was created by the `Object` constructor.
* [is-equal-shallow](https://github.com/jonschlinkert/is-equal-shallow): Does a shallow comparison of two objects, returning false if the keys or values differ.
* [kind-of](https://github.com/jonschlinkert/kind-of): Get the native type of a value.

## Running tests

Install dev dependencies:

```sh
$ npm i -d && npm test
```

## Contributing

Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](https://github.com/jonschlinkert/is-extendable/issues/new)

## Author

**Jon Schlinkert**

+ [github/jonschlinkert](https://github.com/jonschlinkert)
+ [twitter/jonschlinkert](http://twitter.com/jonschlinkert)

## License

Copyright © 2015 Jon Schlinkert
Released under the MIT license.

***

_This file was generated by [verb-cli](https://github.com/assemble/verb-cli) on July 04, 2015._

---

# is-extglob [![NPM version](https://img.shields.io/npm/v/is-extglob.svg?style=flat)](https://www.npmjs.com/package/is-extglob) [![NPM downloads](https://img.shields.io/npm/dm/is-extglob.svg?style=flat)](https://npmjs.org/package/is-extglob) [![Build Status](https://img.shields.io/travis/jonschlinkert/is-extglob.svg?style=flat)](https://travis-ci.org/jonschlinkert/is-extglob)

> Returns true if a string has an extglob.

## Install

Install with [npm](https://www.npmjs.com/):

```sh
$ npm install --save is-extglob
```

## Usage

```js
var isExtglob = require('is-extglob');
```

**True**

```js
isExtglob('?(abc)');
isExtglob('@(abc)');
isExtglob('!(abc)');
isExtglob('*(abc)');
isExtglob('+(abc)');
```

**False**

Escaped extglobs:

```js
isExtglob('\\?(abc)');
isExtglob('\\@(abc)');
isExtglob('\\!(abc)');
isExtglob('\\*(abc)');
isExtglob('\\+(abc)');
```

Everything else...

```js
isExtglob('foo.js');
isExtglob('!foo.js');
isExtglob('*.js');
isExtglob('**/abc.js');
isExtglob('abc/*.js');
isExtglob('abc/(aaa|bbb).js');
isExtglob('abc/[a-z].js');
isExtglob('abc/{a,b}.js');
isExtglob('abc/?.js');
isExtglob('abc.js');
isExtglob('abc/def/ghi.js');
```

## History

**v2.0**

Adds support for escaping. Escaped exglobs no longer return true.

## About

### Related projects

* [has-glob](https://www.npmjs.com/package/has-glob): Returns `true` if an array has a glob pattern. | [homepage](https://github.com/jonschlinkert/has-glob "Returns `true` if an array has a glob pattern.")
* [is-glob](https://www.npmjs.com/package/is-glob): Returns `true` if the given string looks like a glob pattern or an extglob pattern… [more](https://github.com/jonschlinkert/is-glob) | [homepage](https://github.com/jonschlinkert/is-glob "Returns `true` if the given string looks like a glob pattern or an extglob pattern. This makes it easy to create code that only uses external modules like node-glob when necessary, resulting in much faster code execution and initialization time, and a bet")
* [micromatch](https://www.npmjs.com/package/micromatch): Glob matching for javascript/node.js. A drop-in replacement and faster alternative to minimatch and multimatch. | [homepage](https://github.com/jonschlinkert/micromatch "Glob matching for javascript/node.js. A drop-in replacement and faster alternative to minimatch and multimatch.")

### Contributing

Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).

### Building docs

_(This document was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme) (a [verb](https://github.com/verbose/verb) generator), please don't edit the readme directly. Any changes to the readme must be made in [.verb.md](.verb.md).)_

To generate the readme and API documentation with [verb](https://github.com/verbose/verb):

```sh
$ npm install -g verb verb-generate-readme && verb
```

### Running tests

Install dev dependencies:

```sh
$ npm install -d && npm test
```

### Author

**Jon Schlinkert**

* [github/jonschlinkert](https://github.com/jonschlinkert)
* [twitter/jonschlinkert](http://twitter.com/jonschlinkert)

### License

Copyright © 2016, [Jon Schlinkert](https://github.com/jonschlinkert).
Released under the [MIT license](https://github.com/jonschlinkert/is-extglob/blob/master/LICENSE).

***

_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.1.31, on October 12, 2016._

---

# is-fullwidth-code-point [![Build Status](https://travis-ci.org/sindresorhus/is-fullwidth-code-point.svg?branch=master)](https://travis-ci.org/sindresorhus/is-fullwidth-code-point)

> Check if the character represented by a given [Unicode code point](https://en.wikipedia.org/wiki/Code_point) is [fullwidth](https://en.wikipedia.org/wiki/Halfwidth_and_fullwidth_forms)


## Install

```
$ npm install is-fullwidth-code-point
```


## Usage

```js
const isFullwidthCodePoint = require('is-fullwidth-code-point');

isFullwidthCodePoint('谢'.codePointAt(0));
//=> true

isFullwidthCodePoint('a'.codePointAt(0));
//=> false
```


## API

### isFullwidthCodePoint(codePoint)

#### codePoint

Type: `number`

The [code point](https://en.wikipedia.org/wiki/Code_point) of a character.


## License

MIT © [Sindre Sorhus](https://sindresorhus.com)


---

# is-glob [![NPM version](https://img.shields.io/npm/v/is-glob.svg?style=flat)](https://www.npmjs.com/package/is-glob) [![NPM monthly downloads](https://img.shields.io/npm/dm/is-glob.svg?style=flat)](https://npmjs.org/package/is-glob) [![NPM total downloads](https://img.shields.io/npm/dt/is-glob.svg?style=flat)](https://npmjs.org/package/is-glob) [![Build Status](https://img.shields.io/github/workflow/status/micromatch/is-glob/dev)](https://github.com/micromatch/is-glob/actions)

> Returns `true` if the given string looks like a glob pattern or an extglob pattern. This makes it easy to create code that only uses external modules like node-glob when necessary, resulting in much faster code execution and initialization time, and a better user experience.

Please consider following this project's author, [Jon Schlinkert](https://github.com/jonschlinkert), and consider starring the project to show your :heart: and support.

## Install

Install with [npm](https://www.npmjs.com/):

```sh
$ npm install --save is-glob
```

You might also be interested in [is-valid-glob](https://github.com/jonschlinkert/is-valid-glob) and [has-glob](https://github.com/jonschlinkert/has-glob).

## Usage

```js
var isGlob = require('is-glob');
```

### Default behavior

**True**

Patterns that have glob characters or regex patterns will return `true`:

```js
isGlob('!foo.js');
isGlob('*.js');
isGlob('**/abc.js');
isGlob('abc/*.js');
isGlob('abc/(aaa|bbb).js');
isGlob('abc/[a-z].js');
isGlob('abc/{a,b}.js');
//=> true
```

Extglobs

```js
isGlob('abc/@(a).js');
isGlob('abc/!(a).js');
isGlob('abc/+(a).js');
isGlob('abc/*(a).js');
isGlob('abc/?(a).js');
//=> true
```

**False**

Escaped globs or extglobs return `false`:

```js
isGlob('abc/\\@(a).js');
isGlob('abc/\\!(a).js');
isGlob('abc/\\+(a).js');
isGlob('abc/\\*(a).js');
isGlob('abc/\\?(a).js');
isGlob('\\!foo.js');
isGlob('\\*.js');
isGlob('\\*\\*/abc.js');
isGlob('abc/\\*.js');
isGlob('abc/\\(aaa|bbb).js');
isGlob('abc/\\[a-z].js');
isGlob('abc/\\{a,b}.js');
//=> false
```

Patterns that do not have glob patterns return `false`:

```js
isGlob('abc.js');
isGlob('abc/def/ghi.js');
isGlob('foo.js');
isGlob('abc/@.js');
isGlob('abc/+.js');
isGlob('abc/?.js');
isGlob();
isGlob(null);
//=> false
```

Arrays are also `false` (If you want to check if an array has a glob pattern, use [has-glob](https://github.com/jonschlinkert/has-glob)):

```js
isGlob(['**/*.js']);
isGlob(['foo.js']);
//=> false
```

### Option strict

When `options.strict === false` the behavior is less strict in determining if a pattern is a glob. Meaning that
some patterns that would return `false` may return `true`. This is done so that matching libraries like [micromatch](https://github.com/micromatch/micromatch) have a chance at determining if the pattern is a glob or not.

**True**

Patterns that have glob characters or regex patterns will return `true`:

```js
isGlob('!foo.js', {strict: false});
isGlob('*.js', {strict: false});
isGlob('**/abc.js', {strict: false});
isGlob('abc/*.js', {strict: false});
isGlob('abc/(aaa|bbb).js', {strict: false});
isGlob('abc/[a-z].js', {strict: false});
isGlob('abc/{a,b}.js', {strict: false});
//=> true
```

Extglobs

```js
isGlob('abc/@(a).js', {strict: false});
isGlob('abc/!(a).js', {strict: false});
isGlob('abc/+(a).js', {strict: false});
isGlob('abc/*(a).js', {strict: false});
isGlob('abc/?(a).js', {strict: false});
//=> true
```

**False**

Escaped globs or extglobs return `false`:

```js
isGlob('\\!foo.js', {strict: false});
isGlob('\\*.js', {strict: false});
isGlob('\\*\\*/abc.js', {strict: false});
isGlob('abc/\\*.js', {strict: false});
isGlob('abc/\\(aaa|bbb).js', {strict: false});
isGlob('abc/\\[a-z].js', {strict: false});
isGlob('abc/\\{a,b}.js', {strict: false});
//=> false
```

## About

<details>
<summary><strong>Contributing</strong></summary>

Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).

</details>

<details>
<summary><strong>Running Tests</strong></summary>

Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

```sh
$ npm install && npm test
```

</details>

<details>
<summary><strong>Building docs</strong></summary>

_(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_

To generate the readme, run the following command:

```sh
$ npm install -g verbose/verb#dev verb-generate-readme && verb
```

</details>

### Related projects

You might also be interested in these projects:

* [assemble](https://www.npmjs.com/package/assemble): Get the rocks out of your socks! Assemble makes you fast at creating web projects… [more](https://github.com/assemble/assemble) | [homepage](https://github.com/assemble/assemble "Get the rocks out of your socks! Assemble makes you fast at creating web projects. Assemble is used by thousands of projects for rapid prototyping, creating themes, scaffolds, boilerplates, e-books, UI components, API documentation, blogs, building websit")
* [base](https://www.npmjs.com/package/base): Framework for rapidly creating high quality, server-side node.js applications, using plugins like building blocks | [homepage](https://github.com/node-base/base "Framework for rapidly creating high quality, server-side node.js applications, using plugins like building blocks")
* [update](https://www.npmjs.com/package/update): Be scalable! Update is a new, open source developer framework and CLI for automating updates… [more](https://github.com/update/update) | [homepage](https://github.com/update/update "Be scalable! Update is a new, open source developer framework and CLI for automating updates of any kind in code projects.")
* [verb](https://www.npmjs.com/package/verb): Documentation generator for GitHub projects. Verb is extremely powerful, easy to use, and is used… [more](https://github.com/verbose/verb) | [homepage](https://github.com/verbose/verb "Documentation generator for GitHub projects. Verb is extremely powerful, easy to use, and is used on hundreds of projects of all sizes to generate everything from API docs to readmes.")

### Contributors

| **Commits** | **Contributor** |  
| --- | --- |  
| 47 | [jonschlinkert](https://github.com/jonschlinkert) |  
| 5  | [doowb](https://github.com/doowb) |  
| 1  | [phated](https://github.com/phated) |  
| 1  | [danhper](https://github.com/danhper) |  
| 1  | [paulmillr](https://github.com/paulmillr) |  

### Author

**Jon Schlinkert**

* [GitHub Profile](https://github.com/jonschlinkert)
* [Twitter Profile](https://twitter.com/jonschlinkert)
* [LinkedIn Profile](https://linkedin.com/in/jonschlinkert)

### License

Copyright © 2019, [Jon Schlinkert](https://github.com/jonschlinkert).
Released under the [MIT License](LICENSE).

***

_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.8.0, on March 27, 2019._

---

# is-hexadecimal

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]

Check if a character is hexadecimal.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`isHexadecimal(character|code)`](#ishexadecimalcharactercode)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Security](#security)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This is a function that checks if a given character is a white space character:
whether it matches `[a-f0-9]`, case insensitive.

## When should I use this?

Not often, as it’s relatively simple to do yourself.
This package exists because it’s needed in several related packages, at which
point it becomes useful to defer to one shared function.

## Install

This package is [ESM only][esm].
In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]:

```sh
npm install is-hexadecimal
```

In Deno with [Skypack][]:

```js
import {isHexadecimal} from 'https://cdn.skypack.dev/is-hexadecimal@2?dts'
```

In browsers with [Skypack][]:

```html
<script type="module">
  import {isHexadecimal} from 'https://cdn.skypack.dev/is-hexadecimal@2?min'
</script>
```

## Use

```js
import {isHexadecimal} from 'is-hexadecimal'

isHexadecimal('a') // => true
isHexadecimal('0') // => true
isHexadecimal('G') // => false
isHexadecimal('💩') // => false
```

## API

This package exports the following identifier: `isHexadecimal`.
There is no default export.

### `isHexadecimal(character|code)`

Check whether the given character code (`number`), or the character code at the
first position (`string`), is isHexadecimal.

## Types

This package is fully typed with [TypeScript][].

## Compatibility

This package is at least compatible with all maintained versions of Node.js.
As of now, that is Node.js 12.20+, 14.14+, and 16.0+.
It also works in Deno and modern browsers.

## Security

This package is safe.

## Related

*   [`wooorm/is-alphabetical`](https://github.com/wooorm/is-alphabetical)
*   [`wooorm/is-alphanumerical`](https://github.com/wooorm/is-alphabetical)
*   [`wooorm/is-decimal`](https://github.com/wooorm/is-decimal)
*   [`wooorm/is-whitespace-character`](https://github.com/wooorm/is-whitespace-character)
*   [`wooorm/is-word-character`](https://github.com/wooorm/is-word-character)

## Contribute

Yes please!
See [How to Contribute to Open Source][contribute].

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/wooorm/is-hexadecimal/workflows/main/badge.svg

[build]: https://github.com/wooorm/is-hexadecimal/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/is-hexadecimal.svg

[coverage]: https://codecov.io/github/wooorm/is-hexadecimal

[downloads-badge]: https://img.shields.io/npm/dm/is-hexadecimal.svg

[downloads]: https://www.npmjs.com/package/is-hexadecimal

[size-badge]: https://img.shields.io/bundlephobia/minzip/is-hexadecimal.svg

[size]: https://bundlephobia.com/result?p=is-hexadecimal

[npm]: https://docs.npmjs.com/cli/install

[skypack]: https://www.skypack.dev

[license]: license

[author]: https://wooorm.com

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[typescript]: https://www.typescriptlang.org

[contribute]: https://opensource.guide/how-to-contribute/


---

# is-installed-globally

> Check if your package was installed globally

Can be useful if your CLI needs different behavior when installed globally and locally.

## Install

```
$ npm install is-installed-globally
```

## Usage

```js
const isInstalledGlobally = require('is-installed-globally');

// With `npm install your-package`
console.log(isInstalledGlobally);
//=> false

// With `npm install --global your-package`
console.log(isInstalledGlobally);
//=> true
```

## Related

- [import-global](https://github.com/sindresorhus/import-global) - Import a globally installed module
- [resolve-global](https://github.com/sindresorhus/resolve-global) - Resolve the path of a globally installed module
- [global-dirs](https://github.com/sindresorhus/global-dirs) - Get the directory of globally installed packages and binaries


---

# is-npm

> Check if your code is running as an [npm](https://docs.npmjs.com/misc/scripts) or [yarn](https://yarnpkg.com/lang/en/docs/cli/run/) script

## Install

```sh
npm install is-npm
```

## Usage

```js
import {isNpmOrYarn, isNpm, isYarn} from 'is-npm';

console.table({isNpmOrYarn, isNpm, isYarn});
```

```sh
$ node foo.js
# ┌─────────────┬────────┐
# │   (index)   │ Values │
# ├─────────────┼────────┤
# │ isNpmOrYarn │ false  │
# │    isNpm    │ false  │
# │   isYarn    │ false  │
# └─────────────┴────────┘
$ npm run foo
# ┌─────────────┬────────┐
# │   (index)   │ Values │
# ├─────────────┼────────┤
# │ isNpmOrYarn │  true  │
# │    isNpm    │  true  │
# │   isYarn    │ false  │
# └─────────────┴────────┘
$ yarn run foo
# ┌─────────────┬────────┐
# │   (index)   │ Values │
# ├─────────────┼────────┤
# │ isNpmOrYarn │  true  │
# │    isNpm    │ false  │
# │   isYarn    │  true  │
# └─────────────┴────────┘
```

## Related

- [is-npm-cli](https://github.com/sindresorhus/is-npm-cli) - CLI for this module

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-is-npm?utm_source=npm-is-npm&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

# is-number [![NPM version](https://img.shields.io/npm/v/is-number.svg?style=flat)](https://www.npmjs.com/package/is-number) [![NPM monthly downloads](https://img.shields.io/npm/dm/is-number.svg?style=flat)](https://npmjs.org/package/is-number) [![NPM total downloads](https://img.shields.io/npm/dt/is-number.svg?style=flat)](https://npmjs.org/package/is-number) [![Linux Build Status](https://img.shields.io/travis/jonschlinkert/is-number.svg?style=flat&label=Travis)](https://travis-ci.org/jonschlinkert/is-number)

> Returns true if the value is a finite number.

Please consider following this project's author, [Jon Schlinkert](https://github.com/jonschlinkert), and consider starring the project to show your :heart: and support.

## Install

Install with [npm](https://www.npmjs.com/):

```sh
$ npm install --save is-number
```

## Why is this needed?

In JavaScript, it's not always as straightforward as it should be to reliably check if a value is a number. It's common for devs to use `+`, `-`, or `Number()` to cast a string value to a number (for example, when values are returned from user input, regex matches, parsers, etc). But there are many non-intuitive edge cases that yield unexpected results:

```js
console.log(+[]); //=> 0
console.log(+''); //=> 0
console.log(+'   '); //=> 0
console.log(typeof NaN); //=> 'number'
```

This library offers a performant way to smooth out edge cases like these.

## Usage

```js
const isNumber = require('is-number');
```

See the [tests](./test.js) for more examples.

### true

```js
isNumber(5e3);               // true
isNumber(0xff);              // true
isNumber(-1.1);              // true
isNumber(0);                 // true
isNumber(1);                 // true
isNumber(1.1);               // true
isNumber(10);                // true
isNumber(10.10);             // true
isNumber(100);               // true
isNumber('-1.1');            // true
isNumber('0');               // true
isNumber('012');             // true
isNumber('0xff');            // true
isNumber('1');               // true
isNumber('1.1');             // true
isNumber('10');              // true
isNumber('10.10');           // true
isNumber('100');             // true
isNumber('5e3');             // true
isNumber(parseInt('012'));   // true
isNumber(parseFloat('012')); // true
```

### False

Everything else is false, as you would expect:

```js
isNumber(Infinity);          // false
isNumber(NaN);               // false
isNumber(null);              // false
isNumber(undefined);         // false
isNumber('');                // false
isNumber('   ');             // false
isNumber('foo');             // false
isNumber([1]);               // false
isNumber([]);                // false
isNumber(function () {});    // false
isNumber({});                // false
```

## Release history

### 7.0.0

* Refactor. Now uses `.isFinite` if it exists.
* Performance is about the same as v6.0 when the value is a string or number. But it's now 3x-4x faster when the value is not a string or number.

### 6.0.0

* Optimizations, thanks to @benaadams.

### 5.0.0

**Breaking changes**

* removed support for `instanceof Number` and `instanceof String`

## Benchmarks

As with all benchmarks, take these with a grain of salt. See the [benchmarks](./benchmark/index.js) for more detail.

```
# all
v7.0 x 413,222 ops/sec ±2.02% (86 runs sampled)
v6.0 x 111,061 ops/sec ±1.29% (85 runs sampled)
parseFloat x 317,596 ops/sec ±1.36% (86 runs sampled)
fastest is 'v7.0'

# string
v7.0 x 3,054,496 ops/sec ±1.05% (89 runs sampled)
v6.0 x 2,957,781 ops/sec ±0.98% (88 runs sampled)
parseFloat x 3,071,060 ops/sec ±1.13% (88 runs sampled)
fastest is 'parseFloat,v7.0'

# number
v7.0 x 3,146,895 ops/sec ±0.89% (89 runs sampled)
v6.0 x 3,214,038 ops/sec ±1.07% (89 runs sampled)
parseFloat x 3,077,588 ops/sec ±1.07% (87 runs sampled)
fastest is 'v6.0'
```

## About

<details>
<summary><strong>Contributing</strong></summary>

Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).

</details>

<details>
<summary><strong>Running Tests</strong></summary>

Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

```sh
$ npm install && npm test
```

</details>

<details>
<summary><strong>Building docs</strong></summary>

_(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_

To generate the readme, run the following command:

```sh
$ npm install -g verbose/verb#dev verb-generate-readme && verb
```

</details>

### Related projects

You might also be interested in these projects:

* [is-plain-object](https://www.npmjs.com/package/is-plain-object): Returns true if an object was created by the `Object` constructor. | [homepage](https://github.com/jonschlinkert/is-plain-object "Returns true if an object was created by the `Object` constructor.")
* [is-primitive](https://www.npmjs.com/package/is-primitive): Returns `true` if the value is a primitive.  | [homepage](https://github.com/jonschlinkert/is-primitive "Returns `true` if the value is a primitive. ")
* [isobject](https://www.npmjs.com/package/isobject): Returns true if the value is an object and not an array or null. | [homepage](https://github.com/jonschlinkert/isobject "Returns true if the value is an object and not an array or null.")
* [kind-of](https://www.npmjs.com/package/kind-of): Get the native type of a value. | [homepage](https://github.com/jonschlinkert/kind-of "Get the native type of a value.")

### Contributors

| **Commits** | **Contributor** | 
| --- | --- |
| 49 | [jonschlinkert](https://github.com/jonschlinkert) |
| 5 | [charlike-old](https://github.com/charlike-old) |
| 1 | [benaadams](https://github.com/benaadams) |
| 1 | [realityking](https://github.com/realityking) |

### Author

**Jon Schlinkert**

* [LinkedIn Profile](https://linkedin.com/in/jonschlinkert)
* [GitHub Profile](https://github.com/jonschlinkert)
* [Twitter Profile](https://twitter.com/jonschlinkert)

### License

Copyright © 2018, [Jon Schlinkert](https://github.com/jonschlinkert).
Released under the [MIT License](LICENSE).

***

_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.6.0, on June 15, 2018._

---

# is-obj [![Build Status](https://travis-ci.org/sindresorhus/is-obj.svg?branch=master)](https://travis-ci.org/sindresorhus/is-obj)

> Check if a value is an object

Keep in mind that array, function, regexp, etc, are objects in JavaScript.<br>
See [`is-plain-obj`](https://github.com/sindresorhus/is-plain-obj) if you want to check for plain objects.


## Install

```
$ npm install --save is-obj
```


## Usage

```js
const isObj = require('is-obj');

isObj({foo: 'bar'});
//=> true

isObj([1, 2, 3]);
//=> true

isObj('foo');
//=> false
```


## License

MIT © [Sindre Sorhus](https://sindresorhus.com)


---

# is-path-cwd [![Build Status](https://travis-ci.org/sindresorhus/is-path-cwd.svg?branch=master)](https://travis-ci.org/sindresorhus/is-path-cwd)

> Check if a path is the [current working directory](https://en.wikipedia.org/wiki/Working_directory)


## Install

```
$ npm install is-path-cwd
```


## Usage

```js
const isPathCwd = require('is-path-cwd');

isPathCwd(process.cwd());
//=> true

isPathCwd('unicorn');
//=> false
```


## License

MIT © [Sindre Sorhus](https://sindresorhus.com)


---

# is-path-inside

> Check if a path is inside another path


## Install

```
$ npm install is-path-inside
```


## Usage

```js
const isPathInside = require('is-path-inside');

isPathInside('a/b/c', 'a/b');
//=> true

isPathInside('a/b/c', 'x/y');
//=> false

isPathInside('a/b/c', 'a/b/c');
//=> false

isPathInside('/Users/sindresorhus/dev/unicorn', '/Users/sindresorhus');
//=> true
```


## API

### isPathInside(childPath, parentPath)

Note that relative paths are resolved against `process.cwd()` to make them absolute.

**Important:** This package is meant for use with path manipulation. It does not check if the paths exist nor does it resolve symlinks. You should not use this as a security mechanism to guard against access to certain places on the file system.

#### childPath

Type: `string`

The path that should be inside `parentPath`.

#### parentPath

Type: `string`

The path that should contain `childPath`.


---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-is-path-inside?utm_source=npm-is-path-inside&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

# is-plain-obj

> Check if a value is a plain object

An object is plain if it's created by either `{}`, `new Object()`, or `Object.create(null)`.

## Install

```
$ npm install is-plain-obj
```

## Usage

```js
import isPlainObject from 'is-plain-obj';
import {runInNewContext} from 'node:vm';

isPlainObject({foo: 'bar'});
//=> true

isPlainObject(new Object());
//=> true

isPlainObject(Object.create(null));
//=> true

// This works across realms
isPlainObject(runInNewContext('({})'));
//=> true

isPlainObject([1, 2, 3]);
//=> false

class Unicorn {}
isPlainObject(new Unicorn());
//=> false

isPlainObject(Math);
//=> false
```

## Related

- [is-obj](https://github.com/sindresorhus/is-obj) - Check if a value is an object
- [is](https://github.com/sindresorhus/is) - Type check values

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-is-plain-obj?utm_source=npm-is-plain-obj&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

# is-plain-object [![NPM version](https://img.shields.io/npm/v/is-plain-object.svg?style=flat)](https://www.npmjs.com/package/is-plain-object) [![NPM monthly downloads](https://img.shields.io/npm/dm/is-plain-object.svg?style=flat)](https://npmjs.org/package/is-plain-object) [![NPM total downloads](https://img.shields.io/npm/dt/is-plain-object.svg?style=flat)](https://npmjs.org/package/is-plain-object) [![Linux Build Status](https://img.shields.io/travis/jonschlinkert/is-plain-object.svg?style=flat&label=Travis)](https://travis-ci.org/jonschlinkert/is-plain-object)

> Returns true if an object was created by the `Object` constructor.

## Install

Install with [npm](https://www.npmjs.com/):

```sh
$ npm install --save is-plain-object
```

Use [isobject](https://github.com/jonschlinkert/isobject) if you only want to check if the value is an object and not an array or null.

## Usage

```js
var isPlainObject = require('is-plain-object');
```

**true** when created by the `Object` constructor.

```js
isPlainObject(Object.create({}));
//=> true
isPlainObject(Object.create(Object.prototype));
//=> true
isPlainObject({foo: 'bar'});
//=> true
isPlainObject({});
//=> true
```

**false** when not created by the `Object` constructor.

```js
isPlainObject(1);
//=> false
isPlainObject(['foo', 'bar']);
//=> false
isPlainObject([]);
//=> false
isPlainObject(new Foo);
//=> false
isPlainObject(null);
//=> false
isPlainObject(Object.create(null));
//=> false
```

## About

### Related projects

* [is-number](https://www.npmjs.com/package/is-number): Returns true if the value is a number. comprehensive tests. | [homepage](https://github.com/jonschlinkert/is-number "Returns true if the value is a number. comprehensive tests.")
* [isobject](https://www.npmjs.com/package/isobject): Returns true if the value is an object and not an array or null. | [homepage](https://github.com/jonschlinkert/isobject "Returns true if the value is an object and not an array or null.")
* [kind-of](https://www.npmjs.com/package/kind-of): Get the native type of a value. | [homepage](https://github.com/jonschlinkert/kind-of "Get the native type of a value.")

### Contributing

Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).

### Contributors

| **Commits** | **Contributor** | 
| --- | --- |
| 17 | [jonschlinkert](https://github.com/jonschlinkert) |
| 6 | [stevenvachon](https://github.com/stevenvachon) |
| 3 | [onokumus](https://github.com/onokumus) |
| 1 | [wtgtybhertgeghgtwtg](https://github.com/wtgtybhertgeghgtwtg) |

### Building docs

_(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_

To generate the readme, run the following command:

```sh
$ npm install -g verbose/verb#dev verb-generate-readme && verb
```

### Running tests

Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

```sh
$ npm install && npm test
```

### Author

**Jon Schlinkert**

* [github/jonschlinkert](https://github.com/jonschlinkert)
* [twitter/jonschlinkert](https://twitter.com/jonschlinkert)

### License

Copyright © 2017, [Jon Schlinkert](https://github.com/jonschlinkert).
Released under the [MIT License](LICENSE).

***

_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.6.0, on July 11, 2017._

---

# is-regexp [![Build Status](https://travis-ci.org/sindresorhus/is-regexp.svg?branch=master)](https://travis-ci.org/sindresorhus/is-regexp)

> Check whether a variable is a regular expression


## Install

```sh
$ npm install --save is-regexp
```


## Usage

```js
var isRegexp = require('is-regexp');

isRegexp('unicorn');
//=> false

isRegexp(/unicorn/);
//=> true

isRegexp(new RegExp('unicorn'));
//=> true
```


## License

MIT © [Sindre Sorhus](http://sindresorhus.com)


---

# is-root [![Build Status](https://travis-ci.org/sindresorhus/is-root.svg?branch=master)](https://travis-ci.org/sindresorhus/is-root)

> Check if the process is running as root user, for example, one started with `sudo`


## Install

```
$ npm install is-root
```


## Usage

```
$ sudo node index.js
```

```js
// index.js
const isRoot = require('is-root');

isRoot();
//=> true
```


## Related

- [is-elevated](https://github.com/sindresorhus/is-elevated) - Check if the process is running with elevated privileges *(cross-platform)*


## License

MIT © [Sindre Sorhus](https://sindresorhus.com)


---

# is-stream

> Check if something is a [Node.js stream](https://nodejs.org/api/stream.html)

## Install

```
$ npm install is-stream
```

## Usage

```js
const fs = require('fs');
const isStream = require('is-stream');

isStream(fs.createReadStream('unicorn.png'));
//=> true

isStream({});
//=> false
```

## API

### isStream(stream)

Returns a `boolean` for whether it's a [`Stream`](https://nodejs.org/api/stream.html#stream_stream).

#### isStream.writable(stream)

Returns a `boolean` for whether it's a [`stream.Writable`](https://nodejs.org/api/stream.html#stream_class_stream_writable).

#### isStream.readable(stream)

Returns a `boolean` for whether it's a [`stream.Readable`](https://nodejs.org/api/stream.html#stream_class_stream_readable).

#### isStream.duplex(stream)

Returns a `boolean` for whether it's a [`stream.Duplex`](https://nodejs.org/api/stream.html#stream_class_stream_duplex).

#### isStream.transform(stream)

Returns a `boolean` for whether it's a [`stream.Transform`](https://nodejs.org/api/stream.html#stream_class_stream_transform).

## Related

- [is-file-stream](https://github.com/jamestalmage/is-file-stream) - Detect if a stream is a file stream

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-is-stream?utm_source=npm-is-stream&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

This software is released under the MIT license:

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


---

# is-typedarray [![locked](http://badges.github.io/stability-badges/dist/locked.svg)](http://github.com/badges/stability-badges)

Detect whether or not an object is a
[Typed Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Typed_arrays).

## Usage

[![NPM](https://nodei.co/npm/is-typedarray.png)](https://nodei.co/npm/is-typedarray/)

### isTypedArray(array)

Returns `true` when array is a Typed Array, and `false` when it is not.

## License

MIT. See [LICENSE.md](http://github.com/hughsk/is-typedarray/blob/master/LICENSE.md) for details.


---

# is-wsl [![Build Status](https://travis-ci.org/sindresorhus/is-wsl.svg?branch=master)](https://travis-ci.org/sindresorhus/is-wsl)

> Check if the process is running inside [Windows Subsystem for Linux](https://msdn.microsoft.com/commandline/wsl/about) (Bash on Windows)

Can be useful if you need to work around unimplemented or buggy features in WSL. Supports both WSL 1 and WSL 2.


## Install

```
$ npm install is-wsl
```


## Usage

```js
const isWsl = require('is-wsl');

// When running inside Windows Subsystem for Linux
console.log(isWsl);
//=> true
```


---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-is-wsl?utm_source=npm-is-wsl&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

# is-yarn-global

[![](https://img.shields.io/npm/v/is-yarn-global.svg)](https://www.npmjs.com/package/is-yarn-global)
[![](https://img.shields.io/npm/l/is-yarn-global.svg)](https://github.com/LitoMore/is-yarn-global/blob/master/LICENSE)
[![](https://img.shields.io/badge/code_style-XO-5ed9c7.svg)](https://github.com/xojs/xo)

Check if installed by yarn globally without any `fs` calls

## Install

```bash
$ npm install is-yarn-global
```

## Usage

Just require it in your package.

```javascript
import isYarnGlobal from 'is-yarn-global';

console.log(isYarnGlobal());
```

## License

MIT © [LitoMore](https://github.com/LitoMore)


---


# isarray

`Array#isArray` for older browsers.

## Usage

```js
var isArray = require('isarray');

console.log(isArray([])); // => true
console.log(isArray({})); // => false
```

## Installation

With [npm](http://npmjs.org) do

```bash
$ npm install isarray
```

Then bundle for the browser with
[browserify](https://github.com/substack/browserify).

With [component](http://component.io) do

```bash
$ component install juliangruber/isarray
```

## License

(MIT)

Copyright (c) 2013 Julian Gruber &lt;julian@juliangruber.com&gt;

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# isexe

Minimal module to check if a file is executable, and a normal file.

Uses `fs.stat` and tests against the `PATHEXT` environment variable on
Windows.

## USAGE

```javascript
var isexe = require('isexe')
isexe('some-file-name', function (err, isExe) {
  if (err) {
    console.error('probably file does not exist or something', err)
  } else if (isExe) {
    console.error('this thing can be run')
  } else {
    console.error('cannot be run')
  }
})

// same thing but synchronous, throws errors
var isExe = isexe.sync('some-file-name')

// treat errors as just "not executable"
isexe('maybe-missing-file', { ignoreErrors: true }, callback)
var isExe = isexe.sync('maybe-missing-file', { ignoreErrors: true })
```

## API

### `isexe(path, [options], [callback])`

Check if the path is executable.  If no callback provided, and a
global `Promise` object is available, then a Promise will be returned.

Will raise whatever errors may be raised by `fs.stat`, unless
`options.ignoreErrors` is set to true.

### `isexe.sync(path, [options])`

Same as `isexe` but returns the value and throws any errors raised.

### Options

* `ignoreErrors` Treat all errors as "no, this is not executable", but
  don't raise them.
* `uid` Number to use as the user id
* `gid` Number to use as the group id
* `pathExt` List of path extensions to use instead of `PATHEXT`
  environment variable on Windows.


---

# isobject [![NPM version](https://img.shields.io/npm/v/isobject.svg?style=flat)](https://www.npmjs.com/package/isobject) [![NPM monthly downloads](https://img.shields.io/npm/dm/isobject.svg?style=flat)](https://npmjs.org/package/isobject)  [![NPM total downloads](https://img.shields.io/npm/dt/isobject.svg?style=flat)](https://npmjs.org/package/isobject) [![Linux Build Status](https://img.shields.io/travis/jonschlinkert/isobject.svg?style=flat&label=Travis)](https://travis-ci.org/jonschlinkert/isobject)

> Returns true if the value is an object and not an array or null.

## Install

Install with [npm](https://www.npmjs.com/):

```sh
$ npm install --save isobject
```

Install with [yarn](https://yarnpkg.com):

```sh
$ yarn add isobject
```

Use [is-plain-object](https://github.com/jonschlinkert/is-plain-object) if you want only objects that are created by the `Object` constructor.

## Install

Install with [npm](https://www.npmjs.com/):

```sh
$ npm install isobject
```
Install with [bower](https://bower.io/)

```sh
$ bower install isobject
```

## Usage

```js
var isObject = require('isobject');
```

**True**

All of the following return `true`:

```js
isObject({});
isObject(Object.create({}));
isObject(Object.create(Object.prototype));
isObject(Object.create(null));
isObject({});
isObject(new Foo);
isObject(/foo/);
```

**False**

All of the following return `false`:

```js
isObject();
isObject(function () {});
isObject(1);
isObject([]);
isObject(undefined);
isObject(null);
```

## About

### Related projects

* [extend-shallow](https://www.npmjs.com/package/extend-shallow): Extend an object with the properties of additional objects. node.js/javascript util. | [homepage](https://github.com/jonschlinkert/extend-shallow "Extend an object with the properties of additional objects. node.js/javascript util.")
* [is-plain-object](https://www.npmjs.com/package/is-plain-object): Returns true if an object was created by the `Object` constructor. | [homepage](https://github.com/jonschlinkert/is-plain-object "Returns true if an object was created by the `Object` constructor.")
* [kind-of](https://www.npmjs.com/package/kind-of): Get the native type of a value. | [homepage](https://github.com/jonschlinkert/kind-of "Get the native type of a value.")
* [merge-deep](https://www.npmjs.com/package/merge-deep): Recursively merge values in a javascript object. | [homepage](https://github.com/jonschlinkert/merge-deep "Recursively merge values in a javascript object.")

### Contributing

Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).

### Contributors

| **Commits** | **Contributor** |  
| --- | --- |  
| 29 | [jonschlinkert](https://github.com/jonschlinkert) |  
| 4  | [doowb](https://github.com/doowb) |  
| 1  | [magnudae](https://github.com/magnudae) |  
| 1  | [LeSuisse](https://github.com/LeSuisse) |  
| 1  | [tmcw](https://github.com/tmcw) |  

### Building docs

_(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_

To generate the readme, run the following command:

```sh
$ npm install -g verbose/verb#dev verb-generate-readme && verb
```

### Running tests

Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

```sh
$ npm install && npm test
```

### Author

**Jon Schlinkert**

* [github/jonschlinkert](https://github.com/jonschlinkert)
* [twitter/jonschlinkert](https://twitter.com/jonschlinkert)

### License

Copyright © 2017, [Jon Schlinkert](https://github.com/jonschlinkert).
Released under the [MIT License](LICENSE).

***

_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.6.0, on June 30, 2017._

---

# `@jest/utils`

This packages is a collection of utilities and helper functions

## `ErrorWithStack`

This custom error class can be useful when you need to capture the stack trace of an error and provide additional context to the error message. By default, JavaScript errors only capture the stack trace when they are thrown, but this class allows you to capture the stack trace at any point in your code by calling its constructor.

## `clearLine`

It ensures that the clearing operation is only performed when running in a terminal environment, and not when the output is redirected to a file or another non-terminal destination.

## `convertDescriptorToString`

It defines a function named `convertDescriptorToString` that takes a descriptor as input and converts it to a string based on its type. It handles various types such as functions, numbers, strings, and undefined values. If the input doesn't match any of these types, it throws an error with a descriptive message.

## `createDirectory`

It creates new directory and also allows creation of nested directories.

## `deepCyclicCopy`

The `deepCyclicCopy` function provides deep copying of JavaScript objects and arrays, including handling circular references. It offers optional customization through a `DeepCyclicCopyOptions` parameter, allowing users to blacklist properties and preserve object prototypes. The function returns a completely independent deep copy of the input data structure.

## `formatTime`

This function is useful for formatting time values with appropriate SI unit prefixes for readability. It expresses time in various units (e.g., milliseconds, microseconds, nanoseconds) while ensuring the formatting is consistent and human-readable.

## `globsToMatcher`

The code efficiently converts a list of glob patterns into a reusable function for matching paths against those patterns, considering negated patterns and optimizing for performance.

## `installCommonGlobals`

Sets up various global variables and functions needed by the Jest testing framework. It ensures that these globals are properly set up for testing scenarios while maintaining compatibility with the environment's global object.

## `interopRequireDefault`

Provides a way to ensure compatibility between ES modules and CommonJS modules by handling the default export behavior appropriately.

## `invariant`

It is a utility used for asserting that a given condition is true. It's often used as a debugging aid during development to catch situations where an expected condition is not met.

## `isInteractive`

Checks whether the current environment is suitable for interactive terminal interactions.

## `isNonNullable`

Used to narrow down the type of a variable within a TypeScript code block, ensuring that it is safe to assume that the value is non-nullable. This can help avoid runtime errors related to null or undefined values.

## `isPromise`

It helps in order to determine whether a given value conforms to the structure of a Promise-like object, which typically has a `then` method. This can be useful when working with asynchronous code to ensure dealing with promises correctly.

## `pluralize`

This function is used to easily generate grammatically correct phrases in text output that depend on the count of items. It ensures that the word is correctly pluralized when needed.

## `preRunMessage`

These functions are intended for use in interactive command-line tools or scripts which provide informative messages to the user while ensuring a clean and responsive interface.

## `replacePathSepForGlob`

The function takes a string `path` as input and replaces backslashes ('\\') with forward slashes ('/') in the path. Used to normalize file paths to be compatible with glob patterns, ensuring consistency in path representation for different operating systems.

## `requireOrImportModule`

This function provides a unified way to load modules regardless of whether they use CommonJS or ESM syntax. It ensures that the default export is applied consistently when needed, allowing users to work with modules that might use different module systems.

## `setGlobal`

Used to set properties with specified values within a global object. It is designed to work in both browser-like and Node.js environments by accepting different types of global objects as input.

## `specialChars`

It defines constants and conditional values for handling platform-specific behaviors in a terminal environment. It determines if the current platform is Windows ('win32') and sets up constants for various symbols and terminal screen clearing escape sequences accordingly, ensuring proper display and behavior on both Windows and non-Windows operating systems.

## `testPathPatternToRegExp`

This function is used for consistency when serializing/deserializing global configurations and ensures that consistent regular expressions are produced for matching test paths.

## `tryRealpath`

Used to resolve the real path of a given path, but if the path doesn't exist or is a directory, it doesn't throw an error and returns the original path string. This can be useful for gracefully handling path resolution in scenarios where some paths might not exist or might be directories.


---

# jest-worker

Module for executing heavy tasks under forked processes in parallel, by providing a `Promise` based interface, minimum overhead, and bound workers.

The module works by providing an absolute path of the module to be loaded in all forked processes. All methods are exposed on the parent process as promises, so they can be `await`'ed. Child (worker) methods can either be synchronous or asynchronous.

The module also implements support for bound workers. Binding a worker means that, based on certain parameters, the same task will always be executed by the same worker. The way bound workers work is by using the returned string of the `computeWorkerKey` method. If the string was used before for a task, the call will be queued to the related worker that processed the task earlier; if not, it will be executed by the first available worker, then sticked to the worker that executed it; so the next time it will be processed by the same worker. If you have no preference on the worker executing the task, but you have defined a `computeWorkerKey` method because you want _some_ of the tasks to be sticked, you can return `null` from it.

The list of exposed methods can be explicitly provided via the `exposedMethods` option. If it is not provided, it will be obtained by requiring the child module into the main process, and analyzed via reflection. Check the "minimal example" section for a valid one.

## Install

```sh
yarn add jest-worker
```

## Example

This example covers the minimal usage:

### File `parent.js`

```js
import {Worker as JestWorker} from 'jest-worker';

async function main() {
  const worker = new JestWorker(require.resolve('./worker'));
  const result = await worker.hello('Alice'); // "Hello, Alice"
}

main();
```

### File `worker.js`

```js
export function hello(param) {
  return `Hello, ${param}`;
}
```

## Experimental worker

Node shipped with [`worker_threads`](https://nodejs.org/api/worker_threads.html), a "threading API" that uses `SharedArrayBuffers` to communicate between the main process and its child threads. This feature can significantly improve the communication time between parent and child processes in `jest-worker`.

To use `worker_threads` instead of default `child_process` you have to pass `enableWorkerThreads: true` when instantiating the worker.

## API

The `Worker` export is a constructor that is initialized by passing the worker path, plus an options object.

### `workerPath: string | URL` (required)

Node module name or absolute path or file URL of the file to be loaded in the child processes. You can use `require.resolve` to transform a relative path into an absolute one.

### `options: Object` (optional)

#### `computeWorkerKey: (method: string, ...args: Array<unknown>) => string | null` (optional)

Every time a method exposed via the API is called, `computeWorkerKey` is also called in order to bound the call to a worker. This is useful for workers that are able to cache the result or part of it. You bound calls to a worker by making `computeWorkerKey` return the same identifier for all different calls. If you do not want to bind the call to any worker, return `null`.

The callback you provide is called with the method name, plus all the rest of the arguments of the call. Thus, you have full control to decide what to return. Check a practical example on bound workers under the "bound worker usage" section.

By default, no process is bound to any worker.

#### `enableWorkerThreads: boolean` (optional)

By default, `jest-worker` will use `child_process` threads to spawn new Node.js processes. If you prefer [`worker_threads`](https://nodejs.org/api/worker_threads.html) instead, pass `enableWorkerThreads: true`.

#### `exposedMethods: ReadonlyArray<string>` (optional)

List of method names that can be called on the child processes from the parent process. You cannot expose any method named like a public `Worker` method, or starting with `_`. If you use method auto-discovery, then these methods will not be exposed, even if they exist.

#### `forkOptions: ForkOptions` (optional)

Allow customizing all options passed to `child_process.fork`. By default, some values are set (`cwd`, `env`, `execArgv` and `serialization`), but you can override them and customize the rest. For a list of valid values, check [the Node documentation](https://nodejs.org/api/child_process.html#child_process_child_process_fork_modulepath_args_options).

#### `idleMemoryLimit: number` (optional)

Specifies the memory limit for workers before they are recycled and is primarily a work-around for [this issue](https://github.com/jestjs/jest/issues/11956);

After the worker has executed a task the memory usage of it is checked. If it exceeds the value specified the worker is killed and restarted. If no limit is set this process does not occur. The limit can be specified in 2 ways:

- `<= 1` - The value is assumed to be a percentage of system memory. So 0.5 sets the memory limit of the worker to half of the total system memory
- `\> 1` - Assumed to be a fixed byte value. Because of the previous rule if you wanted a value of 1 byte (I don't know why) you could use `1.1`.

#### `maxRetries: number` (optional)

Maximum amount of times that a dead child can be re-spawned, per call. Defaults to `3`, pass `Infinity` to allow endless retries.

#### `numWorkers: number` (optional)

Amount of workers to spawn. Defaults to the number of CPUs minus 1.

#### `resourceLimits: ResourceLimits` (optional)

The `resourceLimits` option which will be passed to `worker_threads` workers.

#### `silent: Boolean` (optional)

Set to false for `stdout` and `stderr` to be logged to console.

By default this is true.

#### `setupArgs: Array<unknown>` (optional)

The arguments that will be passed to the `setup` method during initialization.

#### `taskQueue: TaskQueue` (optional)

The task queue defines in which order tasks (method calls) are processed by the workers. `jest-worker` ships with a `FifoQueue` and `PriorityQueue`:

- `FifoQueue` (default): Processes the method calls (tasks) in the call order.
- `PriorityQueue`: Processes the method calls by a computed priority in natural ordering (lower priorities first). Tasks with the same priority are processed in any order (FIFO not guaranteed). The constructor accepts a single argument, the function that is passed the name of the called function and the arguments and returns a numerical value for the priority: `new require('jest-worker').PriorityQueue((method, filename) => filename.length)`.

#### `WorkerPool: new (workerPath: string, options?: WorkerPoolOptions) => WorkerPoolInterface` (optional)

Provide a custom WorkerPool class to be used for spawning child processes.

#### `workerSchedulingPolicy: 'round-robin' | 'in-order'` (optional)

Specifies the policy how tasks are assigned to workers if multiple workers are _idle_:

- `round-robin` (default): The task will be sequentially distributed onto the workers. The first task is assigned to the worker 1, the second to the worker 2, to ensure that the work is distributed across workers.
- `in-order`: The task will be assigned to the first free worker starting with worker 1 and only assign the work to worker 2 if the worker 1 is busy.

Tasks are always assigned to the first free worker as soon as tasks start to queue up. The scheduling policy does not define the task scheduling which is always first-in, first-out.

## JestWorker

### Methods

The returned `JestWorker` instance has all the exposed methods, plus some additional ones to interact with the workers itself:

#### `getStdout(): Readable`

Returns a `ReadableStream` where the standard output of all workers is piped. Note that the `silent` option of the child workers must be set to `true` to make it work. This is the default set by `jest-worker`, but keep it in mind when overriding options through `forkOptions`.

#### `getStderr(): Readable`

Returns a `ReadableStream` where the standard error of all workers is piped. Note that the `silent` option of the child workers must be set to `true` to make it work. This is the default set by `jest-worker`, but keep it in mind when overriding options through `forkOptions`.

#### `start()`

Starts up every worker and calls their `setup` function, if it exists. Returns a `Promise` which resolves when all workers are running and have completed their `setup`.

This is useful if you want to start up all your workers eagerly before they are used to call any other functions.

#### `end()`

Finishes the workers by killing all workers. No further calls can be done to the `Worker` instance.

Returns a `Promise` that resolves with `{ forceExited: boolean }` once all workers are dead. If `forceExited` is `true`, at least one of the workers did not exit gracefully, which likely happened because it executed a leaky task that left handles open. This should be avoided, force exiting workers is a last resort to prevent creating lots of orphans.

**Note:**

`await`ing the `end()` Promise immediately after the workers are no longer needed before proceeding to do other useful things in your program may not be a good idea. If workers have to be force exited, `jest-worker` may go through multiple stages of force exiting (e.g. SIGTERM, later SIGKILL) and give the worker overall around 1 second time to exit on its own. During this time, your program will wait, even though it may not be necessary that all workers are dead before continuing execution.

Consider deliberately leaving this Promise floating (unhandled resolution). After your program has done the rest of its work and is about to exit, the Node process will wait for the Promise to resolve after all workers are dead as the last event loop task. That way you parallelized computation time of your program and waiting time and you didn't delay the outputs of your program unnecessarily.

### Worker IDs

Each worker has a unique id (index that starts with `'1'`), which is available inside the worker as `process.env.JEST_WORKER_ID`.

## Setting up and tearing down the child process

The child process can define two special methods (both of them can be asynchronous):

- `setup()`: If defined, it's executed before the first call to any method in the child.
- `teardown()`: If defined, it's executed when the farm ends.

# More examples

## Standard usage

This example covers the standard usage:

### File `parent.js`

```js
import {Worker as JestWorker} from 'jest-worker';

async function main() {
  const myWorker = new JestWorker(require.resolve('./worker'), {
    exposedMethods: ['foo', 'bar', 'getWorkerId'],
    numWorkers: 4,
  });

  console.log(await myWorker.foo('Alice')); // "Hello from foo: Alice"
  console.log(await myWorker.bar('Bob')); // "Hello from bar: Bob"
  console.log(await myWorker.getWorkerId()); // "3" -> this message has sent from the 3rd worker

  const {forceExited} = await myWorker.end();
  if (forceExited) {
    console.error('Workers failed to exit gracefully');
  }
}

main();
```

### File `worker.js`

```js
export function foo(param) {
  return `Hello from foo: ${param}`;
}

export function bar(param) {
  return `Hello from bar: ${param}`;
}

export function getWorkerId() {
  return process.env.JEST_WORKER_ID;
}
```

## Bound worker usage:

This example covers the usage with a `computeWorkerKey` method:

### File `parent.js`

```js
import {Worker as JestWorker} from 'jest-worker';

async function main() {
  const myWorker = new JestWorker(require.resolve('./worker'), {
    computeWorkerKey: (method, filename) => filename,
  });

  // Transform the given file, within the first available worker.
  console.log(await myWorker.transform('/tmp/foo.js'));

  // Wait a bit.
  await sleep(10000);

  // Transform the same file again. Will immediately return because the
  // transformed file is cached in the worker, and `computeWorkerKey` ensures
  // the same worker that processed the file the first time will process it now.
  console.log(await myWorker.transform('/tmp/foo.js'));

  const {forceExited} = await myWorker.end();
  if (forceExited) {
    console.error('Workers failed to exit gracefully');
  }
}

main();
```

### File `worker.js`

```js
import babel from '@babel/core';

const cache = Object.create(null);

export function transform(filename) {
  if (cache[filename]) {
    return cache[filename];
  }

  // jest-worker can handle both immediate results and thenables. If a
  // thenable is returned, it will be await'ed until it resolves.
  return babel.transformFileAsync(filename).then(result => {
    cache[filename] = result;

    return result;
  });
}
```


---

# supports-color

> Detect whether a terminal supports color

## Install

```
$ npm install supports-color
```

## Usage

```js
const supportsColor = require('supports-color');

if (supportsColor.stdout) {
	console.log('Terminal stdout supports color');
}

if (supportsColor.stdout.has256) {
	console.log('Terminal stdout supports 256 colors');
}

if (supportsColor.stderr.has16m) {
	console.log('Terminal stderr supports 16 million colors (truecolor)');
}
```

## API

Returns an `Object` with a `stdout` and `stderr` property for testing either streams. Each property is an `Object`, or `false` if color is not supported.

The `stdout`/`stderr` objects specifies a level of support for color through a `.level` property and a corresponding flag:

- `.level = 1` and `.hasBasic = true`: Basic color support (16 colors)
- `.level = 2` and `.has256 = true`: 256 color support
- `.level = 3` and `.has16m = true`: Truecolor support (16 million colors)

### `require('supports-color').supportsColor(stream, options?)`

Additionally, `supports-color` exposes the `.supportsColor()` function that takes an arbitrary write stream (e.g. `process.stdout`) and an optional options object to (re-)evaluate color support for an arbitrary stream.

For example, `require('supports-color').stdout` is the equivalent of `require('supports-color').supportsColor(process.stdout)`.

The options object supports a single boolean property `sniffFlags`. By default it is `true`, which instructs `supportsColor()` to sniff `process.argv` for the multitude of `--color` flags (see _Info_ below). If `false`, then `process.argv` is not considered when determining color support.

## Info

It obeys the `--color` and `--no-color` CLI flags.

For situations where using `--color` is not possible, use the environment variable `FORCE_COLOR=1` (level 1), `FORCE_COLOR=2` (level 2), or `FORCE_COLOR=3` (level 3) to forcefully enable color, or `FORCE_COLOR=0` to forcefully disable. The use of `FORCE_COLOR` overrides all other color support checks.

Explicit 256/Truecolor mode can be enabled using the `--color=256` and `--color=16m` flags, respectively.

## Related

- [supports-color-cli](https://github.com/chalk/supports-color-cli) - CLI for this module
- [chalk](https://github.com/chalk/chalk) - Terminal string styling done right

## Maintainers

- [Sindre Sorhus](https://github.com/sindresorhus)
- [Josh Junon](https://github.com/qix-)

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-supports-color?utm_source=npm-supports-color&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>

---


---

# jiti

[![npm version][npm-version-src]][npm-version-href]
[![npm downloads][npm-downloads-src]][npm-downloads-href]
[![bundle][bundle-src]][bundle-href]
[![License][license-src]][license-href]

Runtime Typescript and ESM support for Node.js.

> [!IMPORTANT]
> This is the support branch for jiti v1. Check out [jiti/main](https://github.com/unjs/jiti/tree/main) for the latest version and [unjs/jiti#174](https://github.com/unjs/jiti/issues/174) for the roadmap.

## Features

- Seamless typescript and ESM syntax support
- Seamless interoperability between ESM and CommonJS
- Synchronous API to replace `require`
- Super slim and zero dependency
- Smart syntax detection to avoid extra transforms
- CommonJS cache integration
- Filesystem transpile hard cache
- V8 compile cache
- Custom resolve alias

## Usage

### Programmatic

```js
const jiti = require("jiti")(__filename);

jiti("./path/to/file.ts");
```

You can also pass options as second argument:

```js
const jiti = require("jiti")(__filename, { debug: true });
```

### CLI

```bash
jiti index.ts
# or npx jiti index.ts
```

### Register require hook

```bash
node -r jiti/register index.ts
```

Alternatively, you can register `jiti` as a require hook programmatically:

```js
const jiti = require("jiti")();
const unregister = jiti.register();
```

## Options

### `debug`

- Type: Boolean
- Default: `false`
- Environment Variable: `JITI_DEBUG`

Enable debug to see which files are transpiled

### `cache`

- Type: Boolean | String
- Default: `true`
- Environment Variable: `JITI_CACHE`

Use transpile cache

If set to `true` will use `node_modules/.cache/jiti` (if exists) or `{TMP_DIR}/node-jiti`

### `esmResolve`

- Type: Boolean | String
- Default: `false`
- Environment Variable: `JITI_ESM_RESOLVE`

Using esm resolution algorithm to support `import` condition.

### `transform`

- Type: Function
- Default: Babel (lazy loaded)

Transform function. See [src/babel](./src/babel.ts) for more details

### `sourceMaps`

- Type: Boolean
- Default `false`
- Environment Variable: `JITI_SOURCE_MAPS`

Add inline source map to transformed source for better debugging.

### `interopDefault`

- Type: Boolean
- Default: `false`

Return the `.default` export of a module at the top-level.

### `alias`

- Type: Object
- Default: -
- Environment Variable: `JITI_ALIAS`

Custom alias map used to resolve ids.

### `nativeModules`

- Type: Array
- Default: ['typescript`]
- Environment Variable: `JITI_NATIVE_MODULES`

List of modules (within `node_modules`) to always use native require for them.

### `transformModules`

- Type: Array
- Default: []
- Environment Variable: `JITI_TRANSFORM_MODULES`

List of modules (within `node_modules`) to transform them regardless of syntax.

### `experimentalBun`

- Type: Boolean
- Default: Enabled if `process.versions.bun` exists (Bun runtime)
- Environment Variable: `JITI_EXPERIMENTAL_BUN`

Enable experimental native Bun support for transformations.

## Development

- Clone this repository
- Enable [Corepack](https://github.com/nodejs/corepack) using `corepack enable`
- Install dependencies using `pnpm install`
- Run `pnpm dev`
- Run `pnpm jiti ./test/path/to/file.ts`

## License

MIT. Made with 💖

<!-- Badged -->

[npm-version-src]: https://img.shields.io/npm/v/jiti?style=flat&colorA=18181B&colorB=F0DB4F
[npm-version-href]: https://npmjs.com/package/jiti
[npm-downloads-src]: https://img.shields.io/npm/dm/jiti?style=flat&colorA=18181B&colorB=F0DB4F
[npm-downloads-href]: https://npmjs.com/package/jiti
[bundle-src]: https://img.shields.io/bundlephobia/minzip/jiti?style=flat&colorA=18181B&colorB=F0DB4F
[bundle-href]: https://bundlephobia.com/result?p=h3
[license-src]: https://img.shields.io/github/license/unjs/jiti.svg?style=flat&colorA=18181B&colorB=F0DB4F
[license-href]: https://github.com/unjs/jiti/blob/main/LICENSE


---

Copyright (c) 2012-2022, Project contributors.
Copyright (c) 2012-2022, Sideway. Inc.
Copyright (c) 2012-2014, Walmart.
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
* The names of any contributors may not be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS AND CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


---

# joi

#### The most powerful schema description language and data validator for JavaScript.

## Installation
`npm install joi`

### Visit the [joi.dev](https://joi.dev) Developer Portal for tutorials, documentation, and support

## Useful resources

- [Documentation and API](https://joi.dev/api/)
- [Versions status](https://joi.dev/resources/status/#joi)
- [Changelog](https://joi.dev/resources/changelog/)
- [Project policies](https://joi.dev/policies/)


---

### Version 4.0.0 (2018-01-28) ###

- Added: Support for ES2018. The only change needed was recognizing the `s`
  regex flag.
- Changed: _All_ tokens returned by the `matchToToken` function now have a
  `closed` property. It is set to `undefined` for the tokens where “closed”
  doesn’t make sense. This means that all tokens objects have the same shape,
  which might improve performance.

These are the breaking changes:

- `'/a/s'.match(jsTokens)` no longer returns `['/', 'a', '/', 's']`, but
  `['/a/s']`. (There are of course other variations of this.)
- Code that rely on some token objects not having the `closed` property could
  now behave differently.


### Version 3.0.2 (2017-06-28) ###

- No code changes. Just updates to the readme.


### Version 3.0.1 (2017-01-30) ###

- Fixed: ES2015 unicode escapes with more than 6 hex digits are now matched
  correctly.


### Version 3.0.0 (2017-01-11) ###

This release contains one breaking change, that should [improve performance in
V8][v8-perf]:

> So how can you, as a JavaScript developer, ensure that your RegExps are fast?
> If you are not interested in hooking into RegExp internals, make sure that
> neither the RegExp instance, nor its prototype is modified in order to get the
> best performance:
>
> ```js
> var re = /./g;
> re.exec('');  // Fast path.
> re.new_property = 'slow';
> ```

This module used to export a single regex, with `.matchToToken` bolted
on, just like in the above example. This release changes the exports of
the module to avoid this issue.

Before:

```js
import jsTokens from "js-tokens"
// or:
var jsTokens = require("js-tokens")
var matchToToken = jsTokens.matchToToken
```

After:

```js
import jsTokens, {matchToToken} from "js-tokens"
// or:
var jsTokens = require("js-tokens").default
var matchToToken = require("js-tokens").matchToToken
```

[v8-perf]: http://v8project.blogspot.se/2017/01/speeding-up-v8-regular-expressions.html


### Version 2.0.0 (2016-06-19) ###

- Added: Support for ES2016. In other words, support for the `**` exponentiation
  operator.

These are the breaking changes:

- `'**'.match(jsTokens)` no longer returns `['*', '*']`, but `['**']`.
- `'**='.match(jsTokens)` no longer returns `['*', '*=']`, but `['**=']`.


### Version 1.0.3 (2016-03-27) ###

- Improved: Made the regex ever so slightly smaller.
- Updated: The readme.


### Version 1.0.2 (2015-10-18) ###

- Improved: Limited npm package contents for a smaller download. Thanks to
  @zertosh!


### Version 1.0.1 (2015-06-20) ###

- Fixed: Declared an undeclared variable.


### Version 1.0.0 (2015-02-26) ###

- Changed: Merged the 'operator' and 'punctuation' types into 'punctuator'. That
  type is now equivalent to the Punctuator token in the ECMAScript
  specification. (Backwards-incompatible change.)
- Fixed: A `-` followed by a number is now correctly matched as a punctuator
  followed by a number. It used to be matched as just a number, but there is no
  such thing as negative number literals. (Possibly backwards-incompatible
  change.)


### Version 0.4.1 (2015-02-21) ###

- Added: Support for the regex `u` flag.


### Version 0.4.0 (2015-02-21) ###

- Improved: `jsTokens.matchToToken` performance.
- Added: Support for octal and binary number literals.
- Added: Support for template strings.


### Version 0.3.1 (2015-01-06) ###

- Fixed: Support for unicode spaces. They used to be allowed in names (which is
  very confusing), and some unicode newlines were wrongly allowed in strings and
  regexes.


### Version 0.3.0 (2014-12-19) ###

- Changed: The `jsTokens.names` array has been replaced with the
  `jsTokens.matchToToken` function. The capturing groups of `jsTokens` are no
  longer part of the public API; instead use said function. See this [gist] for
  an example. (Backwards-incompatible change.)
- Changed: The empty string is now considered an “invalid” token, instead an
  “empty” token (its own group). (Backwards-incompatible change.)
- Removed: component support. (Backwards-incompatible change.)

[gist]: https://gist.github.com/lydell/be49dbf80c382c473004


### Version 0.2.0 (2014-06-19) ###

- Changed: Match ES6 function arrows (`=>`) as an operator, instead of its own
  category (“functionArrow”), for simplicity. (Backwards-incompatible change.)
- Added: ES6 splats (`...`) are now matched as an operator (instead of three
  punctuations). (Backwards-incompatible change.)


### Version 0.1.0 (2014-03-08) ###

- Initial release.


---

Overview [![Build Status](https://travis-ci.org/lydell/js-tokens.svg?branch=master)](https://travis-ci.org/lydell/js-tokens)
========

A regex that tokenizes JavaScript.

```js
var jsTokens = require("js-tokens").default

var jsString = "var foo=opts.foo;\n..."

jsString.match(jsTokens)
// ["var", " ", "foo", "=", "opts", ".", "foo", ";", "\n", ...]
```


Installation
============

`npm install js-tokens`

```js
import jsTokens from "js-tokens"
// or:
var jsTokens = require("js-tokens").default
```


Usage
=====

### `jsTokens` ###

A regex with the `g` flag that matches JavaScript tokens.

The regex _always_ matches, even invalid JavaScript and the empty string.

The next match is always directly after the previous.

### `var token = matchToToken(match)` ###

```js
import {matchToToken} from "js-tokens"
// or:
var matchToToken = require("js-tokens").matchToToken
```

Takes a `match` returned by `jsTokens.exec(string)`, and returns a `{type:
String, value: String}` object. The following types are available:

- string
- comment
- regex
- number
- name
- punctuator
- whitespace
- invalid

Multi-line comments and strings also have a `closed` property indicating if the
token was closed or not (see below).

Comments and strings both come in several flavors. To distinguish them, check if
the token starts with `//`, `/*`, `'`, `"` or `` ` ``.

Names are ECMAScript IdentifierNames, that is, including both identifiers and
keywords. You may use [is-keyword-js] to tell them apart.

Whitespace includes both line terminators and other whitespace.

[is-keyword-js]: https://github.com/crissdev/is-keyword-js


ECMAScript support
==================

The intention is to always support the latest ECMAScript version whose feature
set has been finalized.

If adding support for a newer version requires changes, a new version with a
major verion bump will be released.

Currently, ECMAScript 2018 is supported.


Invalid code handling
=====================

Unterminated strings are still matched as strings. JavaScript strings cannot
contain (unescaped) newlines, so unterminated strings simply end at the end of
the line. Unterminated template strings can contain unescaped newlines, though,
so they go on to the end of input.

Unterminated multi-line comments are also still matched as comments. They
simply go on to the end of the input.

Unterminated regex literals are likely matched as division and whatever is
inside the regex.

Invalid ASCII characters have their own capturing group.

Invalid non-ASCII characters are treated as names, to simplify the matching of
names (except unicode spaces which are treated as whitespace). Note: See also
the [ES2018](#es2018) section.

Regex literals may contain invalid regex syntax. They are still matched as
regex literals. They may also contain repeated regex flags, to keep the regex
simple.

Strings may contain invalid escape sequences.


Limitations
===========

Tokenizing JavaScript using regexes—in fact, _one single regex_—won’t be
perfect. But that’s not the point either.

You may compare jsTokens with [esprima] by using `esprima-compare.js`.
See `npm run esprima-compare`!

[esprima]: http://esprima.org/

### Template string interpolation ###

Template strings are matched as single tokens, from the starting `` ` `` to the
ending `` ` ``, including interpolations (whose tokens are not matched
individually).

Matching template string interpolations requires recursive balancing of `{` and
`}`—something that JavaScript regexes cannot do. Only one level of nesting is
supported.

### Division and regex literals collision ###

Consider this example:

```js
var g = 9.82
var number = bar / 2/g

var regex = / 2/g
```

A human can easily understand that in the `number` line we’re dealing with
division, and in the `regex` line we’re dealing with a regex literal. How come?
Because humans can look at the whole code to put the `/` characters in context.
A JavaScript regex cannot. It only sees forwards. (Well, ES2018 regexes can also
look backwards. See the [ES2018](#es2018) section).

When the `jsTokens` regex scans throught the above, it will see the following
at the end of both the `number` and `regex` rows:

```js
/ 2/g
```

It is then impossible to know if that is a regex literal, or part of an
expression dealing with division.

Here is a similar case:

```js
foo /= 2/g
foo(/= 2/g)
```

The first line divides the `foo` variable with `2/g`. The second line calls the
`foo` function with the regex literal `/= 2/g`. Again, since `jsTokens` only
sees forwards, it cannot tell the two cases apart.

There are some cases where we _can_ tell division and regex literals apart,
though.

First off, we have the simple cases where there’s only one slash in the line:

```js
var foo = 2/g
foo /= 2
```

Regex literals cannot contain newlines, so the above cases are correctly
identified as division. Things are only problematic when there are more than
one non-comment slash in a single line.

Secondly, not every character is a valid regex flag.

```js
var number = bar / 2/e
```

The above example is also correctly identified as division, because `e` is not a
valid regex flag. I initially wanted to future-proof by allowing `[a-zA-Z]*`
(any letter) as flags, but it is not worth it since it increases the amount of
ambigous cases. So only the standard `g`, `m`, `i`, `y` and `u` flags are
allowed. This means that the above example will be identified as division as
long as you don’t rename the `e` variable to some permutation of `gmiyus` 1 to 6
characters long.

Lastly, we can look _forward_ for information.

- If the token following what looks like a regex literal is not valid after a
  regex literal, but is valid in a division expression, then the regex literal
  is treated as division instead. For example, a flagless regex cannot be
  followed by a string, number or name, but all of those three can be the
  denominator of a division.
- Generally, if what looks like a regex literal is followed by an operator, the
  regex literal is treated as division instead. This is because regexes are
  seldomly used with operators (such as `+`, `*`, `&&` and `==`), but division
  could likely be part of such an expression.

Please consult the regex source and the test cases for precise information on
when regex or division is matched (should you need to know). In short, you
could sum it up as:

If the end of a statement looks like a regex literal (even if it isn’t), it
will be treated as one. Otherwise it should work as expected (if you write sane
code).

### ES2018 ###

ES2018 added some nice regex improvements to the language.

- [Unicode property escapes] should allow telling names and invalid non-ASCII
  characters apart without blowing up the regex size.
- [Lookbehind assertions] should allow matching telling division and regex
  literals apart in more cases.
- [Named capture groups] might simplify some things.

These things would be nice to do, but are not critical. They probably have to
wait until the oldest maintained Node.js LTS release supports those features.

[Unicode property escapes]: http://2ality.com/2017/07/regexp-unicode-property-escapes.html
[Lookbehind assertions]: http://2ality.com/2017/05/regexp-lookbehind-assertions.html
[Named capture groups]: http://2ality.com/2017/05/regexp-named-capture-groups.html


License
=======

[MIT](LICENSE).


---

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).


## [4.1.0] - 2021-04-15
### Added
- Types are now exported as `yaml.types.XXX`.
- Every type now has `options` property with original arguments kept as they were
  (see `yaml.types.int.options` as an example).

### Changed
- `Schema.extend()` now keeps old type order in case of conflicts
  (e.g. Schema.extend([ a, b, c ]).extend([ b, a, d ]) is now ordered as `abcd` instead of `cbad`).


## [4.0.0] - 2021-01-03
### Changed
- Check [migration guide](migrate_v3_to_v4.md) to see details for all breaking changes.
- Breaking: "unsafe" tags `!!js/function`, `!!js/regexp`, `!!js/undefined` are
  moved to [js-yaml-js-types](https://github.com/nodeca/js-yaml-js-types) package.
- Breaking: removed `safe*` functions. Use `load`, `loadAll`, `dump`
  instead which are all now safe by default.
- `yaml.DEFAULT_SAFE_SCHEMA` and `yaml.DEFAULT_FULL_SCHEMA` are removed, use
  `yaml.DEFAULT_SCHEMA` instead.
- `yaml.Schema.create(schema, tags)` is removed, use `schema.extend(tags)` instead.
- `!!binary` now always mapped to `Uint8Array` on load.
- Reduced nesting of `/lib` folder.
- Parse numbers according to YAML 1.2 instead of YAML 1.1 (`01234` is now decimal,
  `0o1234` is octal, `1:23` is parsed as string instead of base60).
- `dump()` no longer quotes `:`, `[`, `]`, `(`, `)` except when necessary, #470, #557.
- Line and column in exceptions are now formatted as `(X:Y)` instead of
  `at line X, column Y` (also present in compact format), #332.
- Code snippet created in exceptions now contains multiple lines with line numbers.
- `dump()` now serializes `undefined` as `null` in collections and removes keys with
  `undefined` in mappings, #571.
- `dump()` with `skipInvalid=true` now serializes invalid items in collections as null.
- Custom tags starting with `!` are now dumped as `!tag` instead of `!<!tag>`, #576.
- Custom tags starting with `tag:yaml.org,2002:` are now shorthanded using `!!`, #258.

### Added
- Added `.mjs` (es modules) support.
- Added `quotingType` and `forceQuotes` options for dumper to configure
  string literal style, #290, #529.
- Added `styles: { '!!null': 'empty' }` option for dumper
  (serializes `{ foo: null }` as "`foo: `"), #570.
- Added `replacer` option (similar to option in JSON.stringify), #339.
- Custom `Tag` can now handle all tags or multiple tags with the same prefix, #385.

### Fixed
- Astral characters are no longer encoded by `dump()`, #587.
- "duplicate mapping key" exception now points at the correct column, #452.
- Extra commas in flow collections (e.g. `[foo,,bar]`) now throw an exception
  instead of producing null, #321.
- `__proto__` key no longer overrides object prototype, #164.
- Removed `bower.json`.
- Tags are now url-decoded in `load()` and url-encoded in `dump()`
  (previously usage of custom non-ascii tags may have led to invalid YAML that can't be parsed).
- Anchors now work correctly with empty nodes, #301.
- Fix incorrect parsing of invalid block mapping syntax, #418.
- Throw an error if block sequence/mapping indent contains a tab, #80.


## [3.14.1] - 2020-12-07
### Security
- Fix possible code execution in (already unsafe) `.load()` (in &anchor).


## [3.14.0] - 2020-05-22
### Changed
- Support `safe/loadAll(input, options)` variant of call.
- CI: drop outdated nodejs versions.
- Dev deps bump.

### Fixed
- Quote `=` in plain scalars #519.
- Check the node type for `!<?>` tag in case user manually specifies it.
- Verify that there are no null-bytes in input.
- Fix wrong quote position when writing condensed flow, #526.


## [3.13.1] - 2019-04-05
### Security
- Fix possible code execution in (already unsafe) `.load()`, #480.


## [3.13.0] - 2019-03-20
### Security
- Security fix: `safeLoad()` can hang when arrays with nested refs
  used as key. Now throws exception for nested arrays. #475.


## [3.12.2] - 2019-02-26
### Fixed
- Fix `noArrayIndent` option for root level, #468.


## [3.12.1] - 2019-01-05
### Added
- Added `noArrayIndent` option, #432.


## [3.12.0] - 2018-06-02
### Changed
- Support arrow functions without a block statement, #421.


## [3.11.0] - 2018-03-05
### Added
- Add arrow functions suport for `!!js/function`.

### Fixed
- Fix dump in bin/octal/hex formats for negative integers, #399.


## [3.10.0] - 2017-09-10
### Fixed
- Fix `condenseFlow` output (quote keys for sure, instead of spaces), #371, #370.
- Dump astrals as codepoints instead of surrogate pair, #368.


## [3.9.1] - 2017-07-08
### Fixed
- Ensure stack is present for custom errors in node 7.+, #351.


## [3.9.0] - 2017-07-08
### Added
- Add `condenseFlow` option (to create pretty URL query params), #346.

### Fixed
- Support array return from safeLoadAll/loadAll, #350.


## [3.8.4] - 2017-05-08
### Fixed
- Dumper: prevent space after dash for arrays that wrap, #343.


## [3.8.3] - 2017-04-05
### Fixed
- Should not allow numbers to begin and end with underscore, #335.


## [3.8.2] - 2017-03-02
### Fixed
- Fix `!!float 123` (integers) parse, #333.
- Don't allow leading zeros in floats (except 0, 0.xxx).
- Allow positive exponent without sign in floats.


## [3.8.1] - 2017-02-07
### Changed
- Maintenance: update browserified build.


## [3.8.0] - 2017-02-07
### Fixed
- Fix reported position for `duplicated mapping key` errors.
  Now points to block start instead of block end.
  (#243, thanks to @shockey).


## [3.7.0] - 2016-11-12
### Added
- Support polymorphism for tags (#300, thanks to @monken).

### Fixed
- Fix parsing of quotes followed by newlines (#304, thanks to @dplepage).


## [3.6.1] - 2016-05-11
### Fixed
- Fix output cut on a pipe, #286.


## [3.6.0] - 2016-04-16
### Fixed
- Dumper rewrite, fix multiple bugs with trailing `\n`.
  Big thanks to @aepsilon!
- Loader: fix leading/trailing newlines in block scalars, @aepsilon.


## [3.5.5] - 2016-03-17
### Fixed
- Date parse fix: don't allow dates with on digit in month and day, #268.


## [3.5.4] - 2016-03-09
### Added
- `noCompatMode` for dumper, to disable quoting YAML 1.1 values.


## [3.5.3] - 2016-02-11
### Changed
- Maintenance release.


## [3.5.2] - 2016-01-11
### Changed
- Maintenance: missed comma in bower config.


## [3.5.1] - 2016-01-11
### Changed
- Removed `inherit` dependency, #239.
- Better browserify workaround for esprima load.
- Demo rewrite.


## [3.5.0] - 2016-01-10
### Fixed
- Dumper. Fold strings only, #217.
- Dumper. `norefs` option, to clone linked objects, #229.
- Loader. Throw a warning for duplicate keys, #166.
- Improved browserify support (mark `esprima` & `Buffer` excluded).


## [3.4.6] - 2015-11-26
### Changed
- Use standalone `inherit` to keep browserified files clear.


## [3.4.5] - 2015-11-23
### Added
- Added `lineWidth` option to dumper.


## [3.4.4] - 2015-11-21
### Fixed
- Fixed floats dump (missed dot for scientific format), #220.
- Allow non-printable characters inside quoted scalars, #192.


## [3.4.3] - 2015-10-10
### Changed
- Maintenance release - deps bump (esprima, argparse).


## [3.4.2] - 2015-09-09
### Fixed
- Fixed serialization of duplicated entries in sequences, #205.
  Thanks to @vogelsgesang.


## [3.4.1] - 2015-09-05
### Fixed
- Fixed stacktrace handling in generated errors, for browsers (FF/IE).


## [3.4.0] - 2015-08-23
### Changed
- Don't throw on warnings anymore. Use `onWarning` option to catch.
- Throw error on unknown tags (was warning before).
- Reworked internals of error class.

### Fixed
- Fixed multiline keys dump, #197. Thanks to @tcr.
- Fixed heading line breaks in some scalars (regression).


## [3.3.1] - 2015-05-13
### Added
- Added `.sortKeys` dumper option, thanks to @rjmunro.

### Fixed
- Fixed astral characters support, #191.


## [3.3.0] - 2015-04-26
### Changed
- Significantly improved long strings formatting in dumper, thanks to @isaacs.
- Strip BOM if exists.


## [3.2.7] - 2015-02-19
### Changed
- Maintenance release.
- Updated dependencies.
- HISTORY.md -> CHANGELOG.md


## [3.2.6] - 2015-02-07
### Fixed
- Fixed encoding of UTF-16 surrogate pairs. (e.g. "\U0001F431" CAT FACE).
- Fixed demo dates dump (#113, thanks to @Hypercubed).


## [3.2.5] - 2014-12-28
### Fixed
- Fixed resolving of all built-in types on empty nodes.
- Fixed invalid warning on empty lines within quoted scalars and flow collections.
- Fixed bug: Tag on an empty node didn't resolve in some cases.


## [3.2.4] - 2014-12-19
### Fixed
- Fixed resolving of !!null tag on an empty node.


## [3.2.3] - 2014-11-08
### Fixed
- Implemented dumping of objects with circular and cross references.
- Partially fixed aliasing of constructed objects. (see issue #141 for details)


## [3.2.2] - 2014-09-07
### Fixed
- Fixed infinite loop on unindented block scalars.
- Rewritten base64 encode/decode in binary type, to keep code licence clear.


## [3.2.1] - 2014-08-24
### Fixed
- Nothig new. Just fix npm publish error.


## [3.2.0] - 2014-08-24
### Added
- Added input piping support to CLI.

### Fixed
- Fixed typo, that could cause hand on initial indent (#139).


## [3.1.0] - 2014-07-07
### Changed
- 1.5x-2x speed boost.
- Removed deprecated `require('xxx.yml')` support.
- Significant code cleanup and refactoring.
- Internal API changed. If you used custom types - see updated examples.
  Others are not affected.
- Even if the input string has no trailing line break character,
  it will be parsed as if it has one.
- Added benchmark scripts.
- Moved bower files to /dist folder
- Bugfixes.


## [3.0.2] - 2014-02-27
### Fixed
- Fixed bug: "constructor" string parsed as `null`.


## [3.0.1] - 2013-12-22
### Fixed
- Fixed parsing of literal scalars. (issue #108)
- Prevented adding unnecessary spaces in object dumps. (issue #68)
- Fixed dumping of objects with very long (> 1024 in length) keys.


## [3.0.0] - 2013-12-16
### Changed
- Refactored code. Changed API for custom types.
- Removed output colors in CLI, dump json by default.
- Removed big dependencies from browser version (esprima, buffer). Load `esprima` manually, if `!!js/function` needed. `!!bin` now returns Array in browser
- AMD support.
- Don't quote dumped strings because of `-` & `?` (if not first char).
- __Deprecated__ loading yaml files via `require()`, as not recommended
  behaviour for node.


## [2.1.3] - 2013-10-16
### Fixed
- Fix wrong loading of empty block scalars.


## [2.1.2] - 2013-10-07
### Fixed
- Fix unwanted line breaks in folded scalars.


## [2.1.1] - 2013-10-02
### Fixed
- Dumper now respects deprecated booleans syntax from YAML 1.0/1.1
- Fixed reader bug in JSON-like sequences/mappings.


## [2.1.0] - 2013-06-05
### Added
- Add standard YAML schemas: Failsafe (`FAILSAFE_SCHEMA`),
  JSON (`JSON_SCHEMA`) and Core (`CORE_SCHEMA`).
- Add `skipInvalid` dumper option.

### Changed
- Rename `DEFAULT_SCHEMA` to `DEFAULT_FULL_SCHEMA`
  and `SAFE_SCHEMA` to `DEFAULT_SAFE_SCHEMA`.
- Use `safeLoad` for `require` extension.

### Fixed
- Bug fix: export `NIL` constant from the public interface.


## [2.0.5] - 2013-04-26
### Security
- Close security issue in !!js/function constructor.
  Big thanks to @nealpoole for security audit.


## [2.0.4] - 2013-04-08
### Changed
- Updated .npmignore to reduce package size


## [2.0.3] - 2013-02-26
### Fixed
- Fixed dumping of empty arrays ans objects. ([] and {} instead of null)


## [2.0.2] - 2013-02-15
### Fixed
- Fixed input validation: tabs are printable characters.


## [2.0.1] - 2013-02-09
### Fixed
- Fixed error, when options not passed to function cass


## [2.0.0] - 2013-02-09
### Changed
- Full rewrite. New architecture. Fast one-stage parsing.
- Changed custom types API.
- Added YAML dumper.


## [1.0.3] - 2012-11-05
### Fixed
- Fixed utf-8 files loading.


## [1.0.2] - 2012-08-02
### Fixed
- Pull out hand-written shims. Use ES5-Shims for old browsers support. See #44.
- Fix timstamps incorectly parsed in local time when no time part specified.


## [1.0.1] - 2012-07-07
### Fixed
- Fixes `TypeError: 'undefined' is not an object` under Safari. Thanks Phuong.
- Fix timestamps incorrectly parsed in local time. Thanks @caolan. Closes #46.


## [1.0.0] - 2012-07-01
### Changed
- `y`, `yes`, `n`, `no`, `on`, `off` are not converted to Booleans anymore.
  Fixes #42.
- `require(filename)` now returns a single document and throws an Error if
  file contains more than one document.
- CLI was merged back from js-yaml.bin


## [0.3.7] - 2012-02-28
### Fixed
- Fix export of `addConstructor()`. Closes #39.


## [0.3.6] - 2012-02-22
### Changed
- Removed AMD parts - too buggy to use. Need help to rewrite from scratch

### Fixed
- Removed YUI compressor warning (renamed `double` variable). Closes #40.


## [0.3.5] - 2012-01-10
### Fixed
- Workagound for .npmignore fuckup under windows. Thanks to airportyh.


## [0.3.4] - 2011-12-24
### Fixed
- Fixes str[] for oldIEs support.
- Adds better has change support for browserified demo.
- improves compact output of Error. Closes #33.


## [0.3.3] - 2011-12-20
### Added
- adds `compact` stringification of Errors.

### Changed
- jsyaml executable moved to separate module.


## [0.3.2] - 2011-12-16
### Added
- Added jsyaml executable.
- Added !!js/function support. Closes #12.

### Fixed
- Fixes ug with block style scalars. Closes #26.
- All sources are passing JSLint now.
- Fixes bug in Safari. Closes #28.
- Fixes bug in Opers. Closes #29.
- Improves browser support. Closes #20.


## [0.3.1] - 2011-11-18
### Added
- Added AMD support for browserified version.
- Added permalinks for online demo YAML snippets. Now we have YPaste service, lol.
- Added !!js/regexp and !!js/undefined types. Partially solves #12.

### Changed
- Wrapped browserified js-yaml into closure.

### Fixed
- Fixed the resolvement of non-specific tags. Closes #17.
- Fixed !!set mapping.
- Fixed month parse in dates. Closes #19.


## [0.3.0] - 2011-11-09
### Added
- Added browserified version. Closes #13.
- Added live demo of browserified version.
- Ported some of the PyYAML tests. See #14.

### Fixed
- Removed JS.Class dependency. Closes #3.
- Fixed timestamp bug when fraction was given.


## [0.2.2] - 2011-11-06
### Fixed
- Fixed crash on docs without ---. Closes #8.
- Fixed multiline string parse
- Fixed tests/comments for using array as key


## [0.2.1] - 2011-11-02
### Fixed
- Fixed short file read (<4k). Closes #9.


## [0.2.0] - 2011-11-02
### Changed
- First public release


[4.1.0]: https://github.com/nodeca/js-yaml/compare/4.0.0...4.1.0
[4.0.0]: https://github.com/nodeca/js-yaml/compare/3.14.0...4.0.0
[3.14.0]: https://github.com/nodeca/js-yaml/compare/3.13.1...3.14.0
[3.13.1]: https://github.com/nodeca/js-yaml/compare/3.13.0...3.13.1
[3.13.0]: https://github.com/nodeca/js-yaml/compare/3.12.2...3.13.0
[3.12.2]: https://github.com/nodeca/js-yaml/compare/3.12.1...3.12.2
[3.12.1]: https://github.com/nodeca/js-yaml/compare/3.12.0...3.12.1
[3.12.0]: https://github.com/nodeca/js-yaml/compare/3.11.0...3.12.0
[3.11.0]: https://github.com/nodeca/js-yaml/compare/3.10.0...3.11.0
[3.10.0]: https://github.com/nodeca/js-yaml/compare/3.9.1...3.10.0
[3.9.1]: https://github.com/nodeca/js-yaml/compare/3.9.0...3.9.1
[3.9.0]: https://github.com/nodeca/js-yaml/compare/3.8.4...3.9.0
[3.8.4]: https://github.com/nodeca/js-yaml/compare/3.8.3...3.8.4
[3.8.3]: https://github.com/nodeca/js-yaml/compare/3.8.2...3.8.3
[3.8.2]: https://github.com/nodeca/js-yaml/compare/3.8.1...3.8.2
[3.8.1]: https://github.com/nodeca/js-yaml/compare/3.8.0...3.8.1
[3.8.0]: https://github.com/nodeca/js-yaml/compare/3.7.0...3.8.0
[3.7.0]: https://github.com/nodeca/js-yaml/compare/3.6.1...3.7.0
[3.6.1]: https://github.com/nodeca/js-yaml/compare/3.6.0...3.6.1
[3.6.0]: https://github.com/nodeca/js-yaml/compare/3.5.5...3.6.0
[3.5.5]: https://github.com/nodeca/js-yaml/compare/3.5.4...3.5.5
[3.5.4]: https://github.com/nodeca/js-yaml/compare/3.5.3...3.5.4
[3.5.3]: https://github.com/nodeca/js-yaml/compare/3.5.2...3.5.3
[3.5.2]: https://github.com/nodeca/js-yaml/compare/3.5.1...3.5.2
[3.5.1]: https://github.com/nodeca/js-yaml/compare/3.5.0...3.5.1
[3.5.0]: https://github.com/nodeca/js-yaml/compare/3.4.6...3.5.0
[3.4.6]: https://github.com/nodeca/js-yaml/compare/3.4.5...3.4.6
[3.4.5]: https://github.com/nodeca/js-yaml/compare/3.4.4...3.4.5
[3.4.4]: https://github.com/nodeca/js-yaml/compare/3.4.3...3.4.4
[3.4.3]: https://github.com/nodeca/js-yaml/compare/3.4.2...3.4.3
[3.4.2]: https://github.com/nodeca/js-yaml/compare/3.4.1...3.4.2
[3.4.1]: https://github.com/nodeca/js-yaml/compare/3.4.0...3.4.1
[3.4.0]: https://github.com/nodeca/js-yaml/compare/3.3.1...3.4.0
[3.3.1]: https://github.com/nodeca/js-yaml/compare/3.3.0...3.3.1
[3.3.0]: https://github.com/nodeca/js-yaml/compare/3.2.7...3.3.0
[3.2.7]: https://github.com/nodeca/js-yaml/compare/3.2.6...3.2.7
[3.2.6]: https://github.com/nodeca/js-yaml/compare/3.2.5...3.2.6
[3.2.5]: https://github.com/nodeca/js-yaml/compare/3.2.4...3.2.5
[3.2.4]: https://github.com/nodeca/js-yaml/compare/3.2.3...3.2.4
[3.2.3]: https://github.com/nodeca/js-yaml/compare/3.2.2...3.2.3
[3.2.2]: https://github.com/nodeca/js-yaml/compare/3.2.1...3.2.2
[3.2.1]: https://github.com/nodeca/js-yaml/compare/3.2.0...3.2.1
[3.2.0]: https://github.com/nodeca/js-yaml/compare/3.1.0...3.2.0
[3.1.0]: https://github.com/nodeca/js-yaml/compare/3.0.2...3.1.0
[3.0.2]: https://github.com/nodeca/js-yaml/compare/3.0.1...3.0.2
[3.0.1]: https://github.com/nodeca/js-yaml/compare/3.0.0...3.0.1
[3.0.0]: https://github.com/nodeca/js-yaml/compare/2.1.3...3.0.0
[2.1.3]: https://github.com/nodeca/js-yaml/compare/2.1.2...2.1.3
[2.1.2]: https://github.com/nodeca/js-yaml/compare/2.1.1...2.1.2
[2.1.1]: https://github.com/nodeca/js-yaml/compare/2.1.0...2.1.1
[2.1.0]: https://github.com/nodeca/js-yaml/compare/2.0.5...2.1.0
[2.0.5]: https://github.com/nodeca/js-yaml/compare/2.0.4...2.0.5
[2.0.4]: https://github.com/nodeca/js-yaml/compare/2.0.3...2.0.4
[2.0.3]: https://github.com/nodeca/js-yaml/compare/2.0.2...2.0.3
[2.0.2]: https://github.com/nodeca/js-yaml/compare/2.0.1...2.0.2
[2.0.1]: https://github.com/nodeca/js-yaml/compare/2.0.0...2.0.1
[2.0.0]: https://github.com/nodeca/js-yaml/compare/1.0.3...2.0.0
[1.0.3]: https://github.com/nodeca/js-yaml/compare/1.0.2...1.0.3
[1.0.2]: https://github.com/nodeca/js-yaml/compare/1.0.1...1.0.2
[1.0.1]: https://github.com/nodeca/js-yaml/compare/1.0.0...1.0.1
[1.0.0]: https://github.com/nodeca/js-yaml/compare/0.3.7...1.0.0
[0.3.7]: https://github.com/nodeca/js-yaml/compare/0.3.6...0.3.7
[0.3.6]: https://github.com/nodeca/js-yaml/compare/0.3.5...0.3.6
[0.3.5]: https://github.com/nodeca/js-yaml/compare/0.3.4...0.3.5
[0.3.4]: https://github.com/nodeca/js-yaml/compare/0.3.3...0.3.4
[0.3.3]: https://github.com/nodeca/js-yaml/compare/0.3.2...0.3.3
[0.3.2]: https://github.com/nodeca/js-yaml/compare/0.3.1...0.3.2
[0.3.1]: https://github.com/nodeca/js-yaml/compare/0.3.0...0.3.1
[0.3.0]: https://github.com/nodeca/js-yaml/compare/0.2.2...0.3.0
[0.2.2]: https://github.com/nodeca/js-yaml/compare/0.2.1...0.2.2
[0.2.1]: https://github.com/nodeca/js-yaml/compare/0.2.0...0.2.1
[0.2.0]: https://github.com/nodeca/js-yaml/releases/tag/0.2.0


---

JS-YAML - YAML 1.2 parser / writer for JavaScript
=================================================

[![CI](https://github.com/nodeca/js-yaml/workflows/CI/badge.svg?branch=master)](https://github.com/nodeca/js-yaml/actions)
[![NPM version](https://img.shields.io/npm/v/js-yaml.svg)](https://www.npmjs.org/package/js-yaml)

__[Online Demo](http://nodeca.github.com/js-yaml/)__


This is an implementation of [YAML](http://yaml.org/), a human-friendly data
serialization language. Started as [PyYAML](http://pyyaml.org/) port, it was
completely rewritten from scratch. Now it's very fast, and supports 1.2 spec.


Installation
------------

### YAML module for node.js

```
npm install js-yaml
```


### CLI executable

If you want to inspect your YAML files from CLI, install js-yaml globally:

```
npm install -g js-yaml
```

#### Usage

```
usage: js-yaml [-h] [-v] [-c] [-t] file

Positional arguments:
  file           File with YAML document(s)

Optional arguments:
  -h, --help     Show this help message and exit.
  -v, --version  Show program's version number and exit.
  -c, --compact  Display errors in compact mode
  -t, --trace    Show stack trace on error
```


API
---

Here we cover the most 'useful' methods. If you need advanced details (creating
your own tags), see [examples](https://github.com/nodeca/js-yaml/tree/master/examples)
for more info.

``` javascript
const yaml = require('js-yaml');
const fs   = require('fs');

// Get document, or throw exception on error
try {
  const doc = yaml.load(fs.readFileSync('/home/ixti/example.yml', 'utf8'));
  console.log(doc);
} catch (e) {
  console.log(e);
}
```


### load (string [ , options ])

Parses `string` as single YAML document. Returns either a
plain object, a string, a number, `null` or `undefined`, or throws `YAMLException` on error. By default, does
not support regexps, functions and undefined.

options:

- `filename` _(default: null)_ - string to be used as a file path in
  error/warning messages.
- `onWarning` _(default: null)_ - function to call on warning messages.
  Loader will call this function with an instance of `YAMLException` for each warning.
- `schema` _(default: `DEFAULT_SCHEMA`)_ - specifies a schema to use.
  - `FAILSAFE_SCHEMA` - only strings, arrays and plain objects:
    http://www.yaml.org/spec/1.2/spec.html#id2802346
  - `JSON_SCHEMA` - all JSON-supported types:
    http://www.yaml.org/spec/1.2/spec.html#id2803231
  - `CORE_SCHEMA` - same as `JSON_SCHEMA`:
    http://www.yaml.org/spec/1.2/spec.html#id2804923
  - `DEFAULT_SCHEMA` - all supported YAML types.
- `json` _(default: false)_ - compatibility with JSON.parse behaviour. If true, then duplicate keys in a mapping will override values rather than throwing an error.

NOTE: This function **does not** understand multi-document sources, it throws
exception on those.

NOTE: JS-YAML **does not** support schema-specific tag resolution restrictions.
So, the JSON schema is not as strictly defined in the YAML specification.
It allows numbers in any notation, use `Null` and `NULL` as `null`, etc.
The core schema also has no such restrictions. It allows binary notation for integers.


### loadAll (string [, iterator] [, options ])

Same as `load()`, but understands multi-document sources. Applies
`iterator` to each document if specified, or returns array of documents.

``` javascript
const yaml = require('js-yaml');

yaml.loadAll(data, function (doc) {
  console.log(doc);
});
```


### dump (object [ , options ])

Serializes `object` as a YAML document. Uses `DEFAULT_SCHEMA`, so it will
throw an exception if you try to dump regexps or functions. However, you can
disable exceptions by setting the `skipInvalid` option to `true`.

options:

- `indent` _(default: 2)_ - indentation width to use (in spaces).
- `noArrayIndent` _(default: false)_ - when true, will not add an indentation level to array elements
- `skipInvalid` _(default: false)_ - do not throw on invalid types (like function
  in the safe schema) and skip pairs and single values with such types.
- `flowLevel` _(default: -1)_ - specifies level of nesting, when to switch from
  block to flow style for collections. -1 means block style everwhere
- `styles` - "tag" => "style" map. Each tag may have own set of styles.
- `schema` _(default: `DEFAULT_SCHEMA`)_ specifies a schema to use.
- `sortKeys` _(default: `false`)_ - if `true`, sort keys when dumping YAML. If a
  function, use the function to sort the keys.
- `lineWidth` _(default: `80`)_ - set max line width. Set `-1` for unlimited width.
- `noRefs` _(default: `false`)_ - if `true`, don't convert duplicate objects into references
- `noCompatMode` _(default: `false`)_ - if `true` don't try to be compatible with older
  yaml versions. Currently: don't quote "yes", "no" and so on, as required for YAML 1.1
- `condenseFlow` _(default: `false`)_ - if `true` flow sequences will be condensed, omitting the space between `a, b`. Eg. `'[a,b]'`, and omitting the space between `key: value` and quoting the key. Eg. `'{"a":b}'` Can be useful when using yaml for pretty URL query params as spaces are %-encoded.
- `quotingType` _(`'` or `"`, default: `'`)_ - strings will be quoted using this quoting style. If you specify single quotes, double quotes will still be used for non-printable characters.
- `forceQuotes` _(default: `false`)_ - if `true`, all non-key strings will be quoted even if they normally don't need to.
- `replacer` - callback `function (key, value)` called recursively on each key/value in source object (see `replacer` docs for `JSON.stringify`).

The following table show availlable styles (e.g. "canonical",
"binary"...) available for each tag (.e.g. !!null, !!int ...). Yaml
output is shown on the right side after `=>` (default setting) or `->`:

``` none
!!null
  "canonical"   -> "~"
  "lowercase"   => "null"
  "uppercase"   -> "NULL"
  "camelcase"   -> "Null"

!!int
  "binary"      -> "0b1", "0b101010", "0b1110001111010"
  "octal"       -> "0o1", "0o52", "0o16172"
  "decimal"     => "1", "42", "7290"
  "hexadecimal" -> "0x1", "0x2A", "0x1C7A"

!!bool
  "lowercase"   => "true", "false"
  "uppercase"   -> "TRUE", "FALSE"
  "camelcase"   -> "True", "False"

!!float
  "lowercase"   => ".nan", '.inf'
  "uppercase"   -> ".NAN", '.INF'
  "camelcase"   -> ".NaN", '.Inf'
```

Example:

``` javascript
dump(object, {
  'styles': {
    '!!null': 'canonical' // dump null as ~
  },
  'sortKeys': true        // sort object keys
});
```

Supported YAML types
--------------------

The list of standard YAML tags and corresponding JavaScript types. See also
[YAML tag discussion](http://pyyaml.org/wiki/YAMLTagDiscussion) and
[YAML types repository](http://yaml.org/type/).

```
!!null ''                   # null
!!bool 'yes'                # bool
!!int '3...'                # number
!!float '3.14...'           # number
!!binary '...base64...'     # buffer
!!timestamp 'YYYY-...'      # date
!!omap [ ... ]              # array of key-value pairs
!!pairs [ ... ]             # array or array pairs
!!set { ... }               # array of objects with given keys and null values
!!str '...'                 # string
!!seq [ ... ]               # array
!!map { ... }               # object
```

**JavaScript-specific tags**

See [js-yaml-js-types](https://github.com/nodeca/js-yaml-js-types) for
extra types.


Caveats
-------

Note, that you use arrays or objects as key in JS-YAML. JS does not allow objects
or arrays as keys, and stringifies (by calling `toString()` method) them at the
moment of adding them.

``` yaml
---
? [ foo, bar ]
: - baz
? { foo: bar }
: - baz
  - baz
```

``` javascript
{ "foo,bar": ["baz"], "[object Object]": ["baz", "baz"] }
```

Also, reading of properties on implicit block mapping keys is not supported yet.
So, the following YAML document cannot be loaded.

``` yaml
&anchor foo:
  foo: bar
  *anchor: duplicate key
  baz: bat
  *anchor: duplicate key
```


js-yaml for enterprise
----------------------

Available as part of the Tidelift Subscription

The maintainers of js-yaml and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-js-yaml?utm_source=npm-js-yaml&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)


---

# jsesc

Given some data, _jsesc_ returns a stringified representation of that data. jsesc is similar to `JSON.stringify()` except:

1. it outputs JavaScript instead of JSON [by default](#json), enabling support for data structures like ES6 maps and sets;
2. it offers [many options](#api) to customize the output;
3. its output is ASCII-safe [by default](#minimal), thanks to its use of [escape sequences](https://mathiasbynens.be/notes/javascript-escapes) where needed.

For any input, jsesc generates the shortest possible valid printable-ASCII-only output. [Here’s an online demo.](https://mothereff.in/js-escapes)

jsesc’s output can be used instead of `JSON.stringify`’s to avoid [mojibake](https://en.wikipedia.org/wiki/Mojibake) and other encoding issues, or even to [avoid errors](https://twitter.com/annevk/status/380000829643571200) when passing JSON-formatted data (which may contain U+2028 LINE SEPARATOR, U+2029 PARAGRAPH SEPARATOR, or [lone surrogates](https://esdiscuss.org/topic/code-points-vs-unicode-scalar-values#content-14)) to a JavaScript parser or an UTF-8 encoder.

## Installation

Via [npm](https://www.npmjs.com/):

```bash
npm install jsesc
```

In [Node.js](https://nodejs.org/):

```js
const jsesc = require('jsesc');
```

## API

### `jsesc(value, options)`

This function takes a value and returns an escaped version of the value where any characters that are not printable ASCII symbols are escaped using the shortest possible (but valid) [escape sequences for use in JavaScript strings](https://mathiasbynens.be/notes/javascript-escapes). The first supported value type is strings:

```js
jsesc('Ich ♥ Bücher');
// → 'Ich \\u2665 B\\xFCcher'

jsesc('foo 𝌆 bar');
// → 'foo \\uD834\\uDF06 bar'
```

Instead of a string, the `value` can also be an array, an object, a map, a set, or a buffer. In such cases, `jsesc` returns a stringified version of the value where any characters that are not printable ASCII symbols are escaped in the same way.

```js
// Escaping an array
jsesc([
  'Ich ♥ Bücher', 'foo 𝌆 bar'
]);
// → '[\'Ich \\u2665 B\\xFCcher\',\'foo \\uD834\\uDF06 bar\']'

// Escaping an object
jsesc({
  'Ich ♥ Bücher': 'foo 𝌆 bar'
});
// → '{\'Ich \\u2665 B\\xFCcher\':\'foo \\uD834\\uDF06 bar\'}'
```

The optional `options` argument accepts an object with the following options:

#### `quotes`

The default value for the `quotes` option is `'single'`. This means that any occurrences of `'` in the input string are escaped as `\'`, so that the output can be used in a string literal wrapped in single quotes.

```js
jsesc('`Lorem` ipsum "dolor" sit \'amet\' etc.');
// → 'Lorem ipsum "dolor" sit \\\'amet\\\' etc.'

jsesc('`Lorem` ipsum "dolor" sit \'amet\' etc.', {
  'quotes': 'single'
});
// → '`Lorem` ipsum "dolor" sit \\\'amet\\\' etc.'
// → "`Lorem` ipsum \"dolor\" sit \\'amet\\' etc."
```

If you want to use the output as part of a string literal wrapped in double quotes, set the `quotes` option to `'double'`.

```js
jsesc('`Lorem` ipsum "dolor" sit \'amet\' etc.', {
  'quotes': 'double'
});
// → '`Lorem` ipsum \\"dolor\\" sit \'amet\' etc.'
// → "`Lorem` ipsum \\\"dolor\\\" sit 'amet' etc."
```

If you want to use the output as part of a template literal (i.e. wrapped in backticks), set the `quotes` option to `'backtick'`.

```js
jsesc('`Lorem` ipsum "dolor" sit \'amet\' etc.', {
  'quotes': 'backtick'
});
// → '\\`Lorem\\` ipsum "dolor" sit \'amet\' etc.'
// → "\\`Lorem\\` ipsum \"dolor\" sit 'amet' etc."
// → `\\\`Lorem\\\` ipsum "dolor" sit 'amet' etc.`
```

This setting also affects the output for arrays and objects:

```js
jsesc({ 'Ich ♥ Bücher': 'foo 𝌆 bar' }, {
  'quotes': 'double'
});
// → '{"Ich \\u2665 B\\xFCcher":"foo \\uD834\\uDF06 bar"}'

jsesc([ 'Ich ♥ Bücher', 'foo 𝌆 bar' ], {
  'quotes': 'double'
});
// → '["Ich \\u2665 B\\xFCcher","foo \\uD834\\uDF06 bar"]'
```

#### `numbers`

The default value for the `numbers` option is `'decimal'`. This means that any numeric values are represented using decimal integer literals. Other valid options are `binary`, `octal`, and `hexadecimal`, which result in binary integer literals, octal integer literals, and hexadecimal integer literals, respectively.

```js
jsesc(42, {
  'numbers': 'binary'
});
// → '0b101010'

jsesc(42, {
  'numbers': 'octal'
});
// → '0o52'

jsesc(42, {
  'numbers': 'decimal'
});
// → '42'

jsesc(42, {
  'numbers': 'hexadecimal'
});
// → '0x2A'
```

#### `wrap`

The `wrap` option takes a boolean value (`true` or `false`), and defaults to `false` (disabled). When enabled, the output is a valid JavaScript string literal wrapped in quotes. The type of quotes can be specified through the `quotes` setting.

```js
jsesc('Lorem ipsum "dolor" sit \'amet\' etc.', {
  'quotes': 'single',
  'wrap': true
});
// → '\'Lorem ipsum "dolor" sit \\\'amet\\\' etc.\''
// → "\'Lorem ipsum \"dolor\" sit \\\'amet\\\' etc.\'"

jsesc('Lorem ipsum "dolor" sit \'amet\' etc.', {
  'quotes': 'double',
  'wrap': true
});
// → '"Lorem ipsum \\"dolor\\" sit \'amet\' etc."'
// → "\"Lorem ipsum \\\"dolor\\\" sit \'amet\' etc.\""
```

#### `es6`

The `es6` option takes a boolean value (`true` or `false`), and defaults to `false` (disabled). When enabled, any astral Unicode symbols in the input are escaped using [ECMAScript 6 Unicode code point escape sequences](https://mathiasbynens.be/notes/javascript-escapes#unicode-code-point) instead of using separate escape sequences for each surrogate half. If backwards compatibility with ES5 environments is a concern, don’t enable this setting. If the `json` setting is enabled, the value for the `es6` setting is ignored (as if it was `false`).

```js
// By default, the `es6` option is disabled:
jsesc('foo 𝌆 bar 💩 baz');
// → 'foo \\uD834\\uDF06 bar \\uD83D\\uDCA9 baz'

// To explicitly disable it:
jsesc('foo 𝌆 bar 💩 baz', {
  'es6': false
});
// → 'foo \\uD834\\uDF06 bar \\uD83D\\uDCA9 baz'

// To enable it:
jsesc('foo 𝌆 bar 💩 baz', {
  'es6': true
});
// → 'foo \\u{1D306} bar \\u{1F4A9} baz'
```

#### `escapeEverything`

The `escapeEverything` option takes a boolean value (`true` or `false`), and defaults to `false` (disabled). When enabled, all the symbols in the output are escaped — even printable ASCII symbols.

```js
jsesc('lolwat"foo\'bar', {
  'escapeEverything': true
});
// → '\\x6C\\x6F\\x6C\\x77\\x61\\x74\\"\\x66\\x6F\\x6F\\\'\\x62\\x61\\x72'
// → "\\x6C\\x6F\\x6C\\x77\\x61\\x74\\\"\\x66\\x6F\\x6F\\'\\x62\\x61\\x72"
```

This setting also affects the output for string literals within arrays and objects.

#### `minimal`

The `minimal` option takes a boolean value (`true` or `false`), and defaults to `false` (disabled). When enabled, only a limited set of symbols in the output are escaped:

* U+0000 `\0`
* U+0008 `\b`
* U+0009 `\t`
* U+000A `\n`
* U+000C `\f`
* U+000D `\r`
* U+005C `\\`
* U+2028 `\u2028`
* U+2029 `\u2029`
* whatever symbol is being used for wrapping string literals (based on [the `quotes` option](#quotes))
* [lone surrogates](https://esdiscuss.org/topic/code-points-vs-unicode-scalar-values#content-14)

Note: with this option enabled, jsesc output is no longer guaranteed to be ASCII-safe.

```js
jsesc('foo\u2029bar\nbaz©qux𝌆flops', {
  'minimal': false
});
// → 'foo\\u2029bar\\nbaz©qux𝌆flops'
```

#### `isScriptContext`

The `isScriptContext` option takes a boolean value (`true` or `false`), and defaults to `false` (disabled). When enabled, occurrences of [`</script` and `</style`](https://mathiasbynens.be/notes/etago) in the output are escaped as `<\/script` and `<\/style`, and [`<!--`](https://mathiasbynens.be/notes/etago#comment-8) is escaped as `\x3C!--` (or `\u003C!--` when the `json` option is enabled). This setting is useful when jsesc’s output ends up as part of a `<script>` or `<style>` element in an HTML document.

```js
jsesc('foo</script>bar', {
  'isScriptContext': true
});
// → 'foo<\\/script>bar'
```

#### `compact`

The `compact` option takes a boolean value (`true` or `false`), and defaults to `true` (enabled). When enabled, the output for arrays and objects is as compact as possible; it’s not formatted nicely.

```js
jsesc({ 'Ich ♥ Bücher': 'foo 𝌆 bar' }, {
  'compact': true // this is the default
});
// → '{\'Ich \u2665 B\xFCcher\':\'foo \uD834\uDF06 bar\'}'

jsesc({ 'Ich ♥ Bücher': 'foo 𝌆 bar' }, {
  'compact': false
});
// → '{\n\t\'Ich \u2665 B\xFCcher\': \'foo \uD834\uDF06 bar\'\n}'

jsesc([ 'Ich ♥ Bücher', 'foo 𝌆 bar' ], {
  'compact': false
});
// → '[\n\t\'Ich \u2665 B\xFCcher\',\n\t\'foo \uD834\uDF06 bar\'\n]'
```

This setting has no effect on the output for strings.

#### `indent`

The `indent` option takes a string value, and defaults to `'\t'`. When the `compact` setting is disabled (`false`), the value of the `indent` option is used to format the output for arrays and objects.

```js
jsesc({ 'Ich ♥ Bücher': 'foo 𝌆 bar' }, {
  'compact': false,
  'indent': '\t' // this is the default
});
// → '{\n\t\'Ich \u2665 B\xFCcher\': \'foo \uD834\uDF06 bar\'\n}'

jsesc({ 'Ich ♥ Bücher': 'foo 𝌆 bar' }, {
  'compact': false,
  'indent': '  '
});
// → '{\n  \'Ich \u2665 B\xFCcher\': \'foo \uD834\uDF06 bar\'\n}'

jsesc([ 'Ich ♥ Bücher', 'foo 𝌆 bar' ], {
  'compact': false,
  'indent': '  '
});
// → '[\n  \'Ich \u2665 B\xFCcher\',\n\  t\'foo \uD834\uDF06 bar\'\n]'
```

This setting has no effect on the output for strings.

#### `indentLevel`

The `indentLevel` option takes a numeric value, and defaults to `0`. It represents the current indentation level, i.e. the number of times the value of [the `indent` option](#indent) is repeated.

```js
jsesc(['a', 'b', 'c'], {
  'compact': false,
  'indentLevel': 1
});
// → '[\n\t\t\'a\',\n\t\t\'b\',\n\t\t\'c\'\n\t]'

jsesc(['a', 'b', 'c'], {
  'compact': false,
  'indentLevel': 2
});
// → '[\n\t\t\t\'a\',\n\t\t\t\'b\',\n\t\t\t\'c\'\n\t\t]'
```

#### `json`

The `json` option takes a boolean value (`true` or `false`), and defaults to `false` (disabled). When enabled, the output is valid JSON. [Hexadecimal character escape sequences](https://mathiasbynens.be/notes/javascript-escapes#hexadecimal) and [the `\v` or `\0` escape sequences](https://mathiasbynens.be/notes/javascript-escapes#single) are not used. Setting `json: true` implies `quotes: 'double', wrap: true, es6: false`, although these values can still be overridden if needed — but in such cases, the output won’t be valid JSON anymore.

```js
jsesc('foo\x00bar\xFF\uFFFDbaz', {
  'json': true
});
// → '"foo\\u0000bar\\u00FF\\uFFFDbaz"'

jsesc({ 'foo\x00bar\xFF\uFFFDbaz': 'foo\x00bar\xFF\uFFFDbaz' }, {
  'json': true
});
// → '{"foo\\u0000bar\\u00FF\\uFFFDbaz":"foo\\u0000bar\\u00FF\\uFFFDbaz"}'

jsesc([ 'foo\x00bar\xFF\uFFFDbaz', 'foo\x00bar\xFF\uFFFDbaz' ], {
  'json': true
});
// → '["foo\\u0000bar\\u00FF\\uFFFDbaz","foo\\u0000bar\\u00FF\\uFFFDbaz"]'

// Values that are acceptable in JSON but aren’t strings, arrays, or object
// literals can’t be escaped, so they’ll just be preserved:
jsesc([ 'foo\x00bar', [1, '©', { 'foo': true, 'qux': null }], 42 ], {
  'json': true
});
// → '["foo\\u0000bar",[1,"\\u00A9",{"foo":true,"qux":null}],42]'
// Values that aren’t allowed in JSON are run through `JSON.stringify()`:
jsesc([ undefined, -Infinity ], {
  'json': true
});
// → '[null,null]'
```

**Note:** Using this option on objects or arrays that contain non-string values relies on `JSON.stringify()`. For legacy environments like IE ≤ 7, use [a `JSON` polyfill](http://bestiejs.github.io/json3/).

#### `lowercaseHex`

The `lowercaseHex` option takes a boolean value (`true` or `false`), and defaults to `false` (disabled). When enabled, any alphabetical hexadecimal digits in escape sequences as well as any hexadecimal integer literals (see [the `numbers` option](#numbers)) in the output are in lowercase.

```js
jsesc('Ich ♥ Bücher', {
  'lowercaseHex': true
});
// → 'Ich \\u2665 B\\xfccher'
//                    ^^

jsesc(42, {
  'numbers': 'hexadecimal',
  'lowercaseHex': true
});
// → '0x2a'
//      ^^
```

### `jsesc.version`

A string representing the semantic version number.

### Using the `jsesc` binary

To use the `jsesc` binary in your shell, simply install jsesc globally using npm:

```bash
npm install -g jsesc
```

After that you’re able to escape strings from the command line:

```bash
$ jsesc 'föo ♥ bår 𝌆 baz'
f\xF6o \u2665 b\xE5r \uD834\uDF06 baz
```

To escape arrays or objects containing string values, use the `-o`/`--object` option:

```bash
$ jsesc --object '{ "föo": "♥", "bår": "𝌆 baz" }'
{'f\xF6o':'\u2665','b\xE5r':'\uD834\uDF06 baz'}
```

To prettify the output in such cases, use the `-p`/`--pretty` option:

```bash
$ jsesc --pretty '{ "föo": "♥", "bår": "𝌆 baz" }'
{
  'f\xF6o': '\u2665',
  'b\xE5r': '\uD834\uDF06 baz'
}
```

For valid JSON output, use the `-j`/`--json` option:

```bash
$ jsesc --json --pretty '{ "föo": "♥", "bår": "𝌆 baz" }'
{
  "f\u00F6o": "\u2665",
  "b\u00E5r": "\uD834\uDF06 baz"
}
```

Read a local JSON file, escape any non-ASCII symbols, and save the result to a new file:

```bash
$ jsesc --json --object < data-raw.json > data-escaped.json
```

Or do the same with an online JSON file:

```bash
$ curl -sL "http://git.io/aorKgQ" | jsesc --json --object > data-escaped.json
```

See `jsesc --help` for the full list of options.

## Support

As of v3.0.0, jsesc supports Node.js v6+ only.

Older versions (up to jsesc v1.3.0) support Chrome 27, Firefox 3, Safari 4, Opera 10, IE 6, Node.js v6.0.0, Narwhal 0.3.2, RingoJS 0.8-0.11, PhantomJS 1.9.0, and Rhino 1.7RC4. **Note:** Using the `json` option on objects or arrays that contain non-string values relies on `JSON.parse()`. For legacy environments like IE ≤ 7, use [a `JSON` polyfill](https://bestiejs.github.io/json3/).

## Author

| [![twitter/mathias](https://gravatar.com/avatar/24e08a9ea84deb17ae121074d0f17125?s=70)](https://twitter.com/mathias "Follow @mathias on Twitter") |
|---|
| [Mathias Bynens](https://mathiasbynens.be/) |

## License

This library is available under the [MIT](https://mths.be/mit) license.


---

# json-buffer

JSON functions that can convert buffers!

[![build status](https://secure.travis-ci.org/dominictarr/json-buffer.png)](http://travis-ci.org/dominictarr/json-buffer)

[![testling badge](https://ci.testling.com/dominictarr/json-buffer.png)](https://ci.testling.com/dominictarr/json-buffer)

JSON mangles buffers by converting to an array...
which isn't helpful. json-buffers converts to base64 instead,
and deconverts base64 to a buffer.

``` js
var JSONB = require('json-buffer')
var Buffer = require('buffer').Buffer

var str = JSONB.stringify(Buffer.from('hello there!'))

console.log(JSONB.parse(str)) //GET a BUFFER back
```

## License

MIT


---

# Change Log

All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.

## 2.0.0

* Add custom error classes

<a name="1.0.2"></a>
## [1.0.2](https://github.com/npm/json-parse-even-better-errors/compare/v1.0.1...v1.0.2) (2018-03-30)


### Bug Fixes

* **messages:** More friendly messages for non-string ([#1](https://github.com/npm/json-parse-even-better-errors/issues/1)) ([a476d42](https://github.com/npm/json-parse-even-better-errors/commit/a476d42))



<a name="1.0.1"></a>
## [1.0.1](https://github.com/npm/json-parse-even-better-errors/compare/v1.0.0...v1.0.1) (2017-08-16)


### Bug Fixes

* **license:** oops. Forgot to update license.md ([efe2958](https://github.com/npm/json-parse-even-better-errors/commit/efe2958))



<a name="1.0.0"></a>
# 1.0.0 (2017-08-15)


### Features

* **init:** Initial Commit ([562c977](https://github.com/npm/json-parse-even-better-errors/commit/562c977))


### BREAKING CHANGES

* **init:** This is the first commit!



<a name="0.1.0"></a>
# 0.1.0 (2017-08-15)


### Features

* **init:** Initial Commit ([9dd1a19](https://github.com/npm/json-parse-even-better-errors/commit/9dd1a19))


---

Copyright 2017 Kat Marchán
Copyright npm, Inc.

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.

---

This library is a fork of 'better-json-errors' by Kat Marchán, extended and
distributed under the terms of the MIT license above.


---

# json-parse-even-better-errors

[`json-parse-even-better-errors`](https://github.com/npm/json-parse-even-better-errors)
is a Node.js library for getting nicer errors out of `JSON.parse()`,
including context and position of the parse errors.

It also preserves the newline and indentation styles of the JSON data, by
putting them in the object or array in the `Symbol.for('indent')` and
`Symbol.for('newline')` properties.

## Install

`$ npm install --save json-parse-even-better-errors`

## Table of Contents

* [Example](#example)
* [Features](#features)
* [Contributing](#contributing)
* [API](#api)
  * [`parse`](#parse)

### Example

```javascript
const parseJson = require('json-parse-even-better-errors')

parseJson('"foo"') // returns the string 'foo'
parseJson('garbage') // more useful error message
parseJson.noExceptions('garbage') // returns undefined
```

### Features

* Like JSON.parse, but the errors are better.
* Strips a leading byte-order-mark that you sometimes get reading files.
* Has a `noExceptions` method that returns undefined rather than throwing.
* Attaches the newline character(s) used to the `Symbol.for('newline')`
  property on objects and arrays.
* Attaches the indentation character(s) used to the `Symbol.for('indent')`
  property on objects and arrays.

## Indentation

To preserve indentation when the file is saved back to disk, use
`data[Symbol.for('indent')]` as the third argument to `JSON.stringify`, and
if you want to preserve windows `\r\n` newlines, replace the `\n` chars in
the string with `data[Symbol.for('newline')]`.

For example:

```js
const txt = await readFile('./package.json', 'utf8')
const data = parseJsonEvenBetterErrors(txt)
const indent = Symbol.for('indent')
const newline = Symbol.for('newline')
// .. do some stuff to the data ..
const string = JSON.stringify(data, null, data[indent]) + '\n'
const eolFixed = data[newline] === '\n' ? string
  : string.replace(/\n/g, data[newline])
await writeFile('./package.json', eolFixed)
```

Indentation is determined by looking at the whitespace between the initial
`{` and `[` and the character that follows it.  If you have lots of weird
inconsistent indentation, then it won't track that or give you any way to
preserve it.  Whether this is a bug or a feature is debatable ;)

### API

#### <a name="parse"></a> `parse(txt, reviver = null, context = 20)`

Works just like `JSON.parse`, but will include a bit more information when
an error happens, and attaches a `Symbol.for('indent')` and
`Symbol.for('newline')` on objects and arrays.  This throws a
`JSONParseError`.

#### <a name="parse"></a> `parse.noExceptions(txt, reviver = null)`

Works just like `JSON.parse`, but will return `undefined` rather than
throwing an error.

#### <a name="jsonparseerror"></a> `class JSONParseError(er, text, context = 20, caller = null)`

Extends the JavaScript `SyntaxError` class to parse the message and provide
better metadata.

Pass in the error thrown by the built-in `JSON.parse`, and the text being
parsed, and it'll parse out the bits needed to be helpful.

`context` defaults to 20.

Set a `caller` function to trim internal implementation details out of the
stack trace.  When calling `parseJson`, this is set to the `parseJson`
function.  If not set, then the constructor defaults to itself, so the
stack trace will point to the spot where you call `new JSONParseError`.


---

# json-schema-traverse
Traverse JSON Schema passing each schema object to callback

[![Build Status](https://travis-ci.org/epoberezkin/json-schema-traverse.svg?branch=master)](https://travis-ci.org/epoberezkin/json-schema-traverse)
[![npm version](https://badge.fury.io/js/json-schema-traverse.svg)](https://www.npmjs.com/package/json-schema-traverse)
[![Coverage Status](https://coveralls.io/repos/github/epoberezkin/json-schema-traverse/badge.svg?branch=master)](https://coveralls.io/github/epoberezkin/json-schema-traverse?branch=master)


## Install

```
npm install json-schema-traverse
```


## Usage

```javascript
const traverse = require('json-schema-traverse');
const schema = {
  properties: {
    foo: {type: 'string'},
    bar: {type: 'integer'}
  }
};

traverse(schema, {cb});
// cb is called 3 times with:
// 1. root schema
// 2. {type: 'string'}
// 3. {type: 'integer'}

// Or:

traverse(schema, {cb: {pre, post}});
// pre is called 3 times with:
// 1. root schema
// 2. {type: 'string'}
// 3. {type: 'integer'}
//
// post is called 3 times with:
// 1. {type: 'string'}
// 2. {type: 'integer'}
// 3. root schema

```

Callback function `cb` is called for each schema object (not including draft-06 boolean schemas), including the root schema, in pre-order traversal. Schema references ($ref) are not resolved, they are passed as is.  Alternatively, you can pass a `{pre, post}` object as `cb`, and then `pre` will be called before traversing child elements, and `post` will be called after all child elements have been traversed.

Callback is passed these parameters:

- _schema_: the current schema object
- _JSON pointer_: from the root schema to the current schema object
- _root schema_: the schema passed to `traverse` object
- _parent JSON pointer_: from the root schema to the parent schema object (see below)
- _parent keyword_: the keyword inside which this schema appears (e.g. `properties`, `anyOf`, etc.)
- _parent schema_: not necessarily parent object/array; in the example above the parent schema for `{type: 'string'}` is the root schema
- _index/property_: index or property name in the array/object containing multiple schemas; in the example above for `{type: 'string'}` the property name is `'foo'`


## Traverse objects in all unknown keywords

```javascript
const traverse = require('json-schema-traverse');
const schema = {
  mySchema: {
    minimum: 1,
    maximum: 2
  }
};

traverse(schema, {allKeys: true, cb});
// cb is called 2 times with:
// 1. root schema
// 2. mySchema
```

Without option `allKeys: true` callback will be called only with root schema.


## License

[MIT](https://github.com/epoberezkin/json-schema-traverse/blob/master/LICENSE)


---

MIT License

Copyright (c) 2012-2018 Aseem Kishore, and [others].

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

[others]: https://github.com/json5/json5/contributors


---

# JSON5 – JSON for Humans

[![Build Status](https://app.travis-ci.com/json5/json5.svg?branch=main)][Build
Status] [![Coverage
Status](https://coveralls.io/repos/github/json5/json5/badge.svg)][Coverage
Status]

JSON5 is an extension to the popular [JSON] file format that aims to be
easier to **write and maintain _by hand_ (e.g. for config files)**.
It is _not intended_ to be used for machine-to-machine communication.
(Keep using JSON or other file formats for that. 🙂)

JSON5 was started in 2012, and as of 2022, now gets **[>65M downloads/week](https://www.npmjs.com/package/json5)**,
ranks in the **[top 0.1%](https://gist.github.com/anvaka/8e8fa57c7ee1350e3491)** of the most depended-upon packages on npm,
and has been adopted by major projects like
**[Chromium](https://source.chromium.org/chromium/chromium/src/+/main:third_party/blink/renderer/platform/runtime_enabled_features.json5;drc=5de823b36e68fd99009a29281b17bc3a1d6b329c),
[Next.js](https://github.com/vercel/next.js/blob/b88f20c90bf4659b8ad5cb2a27956005eac2c7e8/packages/next/lib/find-config.ts#L43-L46),
[Babel](https://babeljs.io/docs/en/config-files#supported-file-extensions),
[Retool](https://community.retool.com/t/i-am-attempting-to-append-several-text-fields-to-a-google-sheet-but-receiving-a-json5-invalid-character-error/7626),
[WebStorm](https://www.jetbrains.com/help/webstorm/json.html),
and [more](https://github.com/json5/json5/wiki/In-the-Wild)**.
It's also natively supported on **[Apple platforms](https://developer.apple.com/documentation/foundation/jsondecoder/3766916-allowsjson5)**
like **MacOS** and **iOS**.

Formally, the **[JSON5 Data Interchange Format](https://spec.json5.org/)** is a superset of JSON
(so valid JSON files will always be valid JSON5 files)
that expands its syntax to include some productions from [ECMAScript 5.1] (ES5).
It's also a strict _subset_ of ES5, so valid JSON5 files will always be valid ES5.

This JavaScript library is a reference implementation for JSON5 parsing and serialization,
and is directly used in many of the popular projects mentioned above
(where e.g. extreme performance isn't necessary),
but others have created [many other libraries](https://github.com/json5/json5/wiki/In-the-Wild)
across many other platforms.

[Build Status]: https://app.travis-ci.com/json5/json5

[Coverage Status]: https://coveralls.io/github/json5/json5

[JSON]: https://tools.ietf.org/html/rfc7159

[ECMAScript 5.1]: https://www.ecma-international.org/ecma-262/5.1/

## Summary of Features
The following ECMAScript 5.1 features, which are not supported in JSON, have
been extended to JSON5.

### Objects
- Object keys may be an ECMAScript 5.1 _[IdentifierName]_.
- Objects may have a single trailing comma.

### Arrays
- Arrays may have a single trailing comma.

### Strings
- Strings may be single quoted.
- Strings may span multiple lines by escaping new line characters.
- Strings may include character escapes.

### Numbers
- Numbers may be hexadecimal.
- Numbers may have a leading or trailing decimal point.
- Numbers may be [IEEE 754] positive infinity, negative infinity, and NaN.
- Numbers may begin with an explicit plus sign.

### Comments
- Single and multi-line comments are allowed.

### White Space
- Additional white space characters are allowed.

[IdentifierName]: https://www.ecma-international.org/ecma-262/5.1/#sec-7.6

[IEEE 754]: http://ieeexplore.ieee.org/servlet/opac?punumber=4610933

## Example
Kitchen-sink example:

```js
{
  // comments
  unquoted: 'and you can quote me on that',
  singleQuotes: 'I can use "double quotes" here',
  lineBreaks: "Look, Mom! \
No \\n's!",
  hexadecimal: 0xdecaf,
  leadingDecimalPoint: .8675309, andTrailing: 8675309.,
  positiveSign: +1,
  trailingComma: 'in objects', andIn: ['arrays',],
  "backwardsCompatible": "with JSON",
}
```

A more real-world example is [this config file](https://github.com/chromium/chromium/blob/feb3c9f670515edf9a88f185301cbd7794ee3e52/third_party/blink/renderer/platform/runtime_enabled_features.json5)
from the Chromium/Blink project.

## Specification
For a detailed explanation of the JSON5 format, please read the [official
specification](https://json5.github.io/json5-spec/).

## Installation and Usage
### Node.js
```sh
npm install json5
```

#### CommonJS
```js
const JSON5 = require('json5')
```

#### Modules
```js
import JSON5 from 'json5'
```

### Browsers
#### UMD
```html
<!-- This will create a global `JSON5` variable. -->
<script src="https://unpkg.com/json5@2/dist/index.min.js"></script>
```

#### Modules
```html
<script type="module">
  import JSON5 from 'https://unpkg.com/json5@2/dist/index.min.mjs'
</script>
```

## API
The JSON5 API is compatible with the [JSON API].

[JSON API]:
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON

### JSON5.parse()
Parses a JSON5 string, constructing the JavaScript value or object described by
the string. An optional reviver function can be provided to perform a
transformation on the resulting object before it is returned.

#### Syntax
    JSON5.parse(text[, reviver])

#### Parameters
- `text`: The string to parse as JSON5.
- `reviver`: If a function, this prescribes how the value originally produced by
  parsing is transformed, before being returned.

#### Return value
The object corresponding to the given JSON5 text.

### JSON5.stringify()
Converts a JavaScript value to a JSON5 string, optionally replacing values if a
replacer function is specified, or optionally including only the specified
properties if a replacer array is specified.

#### Syntax
    JSON5.stringify(value[, replacer[, space]])
    JSON5.stringify(value[, options])

#### Parameters
- `value`: The value to convert to a JSON5 string.
- `replacer`: A function that alters the behavior of the stringification
  process, or an array of String and Number objects that serve as a whitelist
  for selecting/filtering the properties of the value object to be included in
  the JSON5 string. If this value is null or not provided, all properties of the
  object are included in the resulting JSON5 string.
- `space`: A String or Number object that's used to insert white space into the
  output JSON5 string for readability purposes. If this is a Number, it
  indicates the number of space characters to use as white space; this number is
  capped at 10 (if it is greater, the value is just 10). Values less than 1
  indicate that no space should be used. If this is a String, the string (or the
  first 10 characters of the string, if it's longer than that) is used as white
  space. If this parameter is not provided (or is null), no white space is used.
  If white space is used, trailing commas will be used in objects and arrays.
- `options`: An object with the following properties:
  - `replacer`: Same as the `replacer` parameter.
  - `space`: Same as the `space` parameter.
  - `quote`: A String representing the quote character to use when serializing
    strings.

#### Return value
A JSON5 string representing the value.

### Node.js `require()` JSON5 files
When using Node.js, you can `require()` JSON5 files by adding the following
statement.

```js
require('json5/lib/register')
```

Then you can load a JSON5 file with a Node.js `require()` statement. For
example:

```js
const config = require('./config.json5')
```

## CLI
Since JSON is more widely used than JSON5, this package includes a CLI for
converting JSON5 to JSON and for validating the syntax of JSON5 documents.

### Installation
```sh
npm install --global json5
```

### Usage
```sh
json5 [options] <file>
```

If `<file>` is not provided, then STDIN is used.

#### Options:
- `-s`, `--space`: The number of spaces to indent or `t` for tabs
- `-o`, `--out-file [file]`: Output to the specified file, otherwise STDOUT
- `-v`, `--validate`: Validate JSON5 but do not output JSON
- `-V`, `--version`: Output the version number
- `-h`, `--help`: Output usage information

## Contributing
### Development
```sh
git clone https://github.com/json5/json5
cd json5
npm install
```

When contributing code, please write relevant tests and run `npm test` and `npm
run lint` before submitting pull requests. Please use an editor that supports
[EditorConfig](http://editorconfig.org/).

### Issues
To report bugs or request features regarding the JSON5 **data format**,
please submit an issue to the official
**[_specification_ repository](https://github.com/json5/json5-spec)**.

Note that we will never add any features that make JSON5 incompatible with ES5;
that compatibility is a fundamental premise of JSON5.

To report bugs or request features regarding this **JavaScript implementation**
of JSON5, please submit an issue to **_this_ repository**.

### Security Vulnerabilities and Disclosures
To report a security vulnerability, please follow the follow the guidelines
described in our [security policy](./SECURITY.md).

## License
MIT. See [LICENSE.md](./LICENSE.md) for details.

## Credits
[Aseem Kishore](https://github.com/aseemk) founded this project.
He wrote a [blog post](https://aseemk.substack.com/p/ignore-the-f-ing-haters-json5)
about the journey and lessons learned 10 years in.

[Michael Bolin](http://bolinfest.com/) independently arrived at and published
some of these same ideas with awesome explanations and detail. Recommended
reading: [Suggested Improvements to JSON](http://bolinfest.com/essays/json.html)

[Douglas Crockford](http://www.crockford.com/) of course designed and built
JSON, but his state machine diagrams on the [JSON website](http://json.org/), as
cheesy as it may sound, gave us motivation and confidence that building a new
parser to implement these ideas was within reach! The original
implementation of JSON5 was also modeled directly off of Doug’s open-source
[json_parse.js] parser. We’re grateful for that clean and well-documented
code.

[json_parse.js]:
https://github.com/douglascrockford/JSON-js/blob/03157639c7a7cddd2e9f032537f346f1a87c0f6d/json_parse.js

[Max Nanasy](https://github.com/MaxNanasy) has been an early and prolific
supporter, contributing multiple patches and ideas.

[Andrew Eisenberg](https://github.com/aeisenberg) contributed the original
`stringify` method.

[Jordan Tucker](https://github.com/jordanbtucker) has aligned JSON5 more closely
with ES5, wrote the official JSON5 specification, completely rewrote the
codebase from the ground up, and is actively maintaining this project.


---

6.1.0 / 2020-10-31
------------------

- Add `finalEOL` option to disable writing final EOL ([#115](https://github.com/jprichardson/node-jsonfile/issues/115), [#137](https://github.com/jprichardson/node-jsonfile/pull/137))
- Update dependency ([#138](https://github.com/jprichardson/node-jsonfile/pull/138))

6.0.1 / 2020-03-07
------------------

- Update dependency ([#130](https://github.com/jprichardson/node-jsonfile/pull/130))
- Fix code style ([#129](https://github.com/jprichardson/node-jsonfile/pull/129))

6.0.0 / 2020-02-24
------------------

- **BREAKING:** Drop support for Node 6 & 8 ([#128](https://github.com/jprichardson/node-jsonfile/pull/128))
- **BREAKING:** Do not allow passing `null` as options to `readFile()` or `writeFile()` ([#128](https://github.com/jprichardson/node-jsonfile/pull/128))
- Refactor internals ([#128](https://github.com/jprichardson/node-jsonfile/pull/128))

5.0.0 / 2018-09-08
------------------

- **BREAKING:** Drop Node 4 support
- **BREAKING:** If no callback is passed to an asynchronous method, a promise is now returned ([#109](https://github.com/jprichardson/node-jsonfile/pull/109))
- Cleanup docs

4.0.0 / 2017-07-12
------------------

- **BREAKING:** Remove global `spaces` option.
- **BREAKING:** Drop support for Node 0.10, 0.12, and io.js.
- Remove undocumented `passParsingErrors` option.
- Added `EOL` override option to `writeFile` when using `spaces`. [#89]

3.0.1 / 2017-07-05
------------------

- Fixed bug in `writeFile` when there was a serialization error & no callback was passed. In previous versions, an empty file would be written; now no file is written.

3.0.0 / 2017-04-25
------------------

- Changed behavior of `throws` option for `readFileSync`; now does not throw filesystem errors when `throws` is `false`

2.4.0 / 2016-09-15
------------------
### Changed
- added optional support for `graceful-fs` [#62]

2.3.1 / 2016-05-13
------------------
- fix to support BOM. [#45][#45]

2.3.0 / 2016-04-16
------------------
- add `throws` to `readFile()`. See [#39][#39]
- add support for any arbitrary `fs` module. Useful with [mock-fs](https://www.npmjs.com/package/mock-fs)

2.2.3 / 2015-10-14
------------------
- include file name in parse error. See: https://github.com/jprichardson/node-jsonfile/pull/34

2.2.2 / 2015-09-16
------------------
- split out tests into separate files
- fixed `throws` when set to `true` in `readFileSync()`. See: https://github.com/jprichardson/node-jsonfile/pull/33

2.2.1 / 2015-06-25
------------------
- fixed regression when passing in string as encoding for options in `writeFile()` and `writeFileSync()`. See: https://github.com/jprichardson/node-jsonfile/issues/28

2.2.0 / 2015-06-25
------------------
- added `options.spaces` to `writeFile()` and `writeFileSync()`

2.1.2 / 2015-06-22
------------------
- fixed if passed `readFileSync(file, 'utf8')`. See: https://github.com/jprichardson/node-jsonfile/issues/25

2.1.1 / 2015-06-19
------------------
- fixed regressions if `null` is passed for options. See: https://github.com/jprichardson/node-jsonfile/issues/24

2.1.0 / 2015-06-19
------------------
- cleanup: JavaScript Standard Style, rename files, dropped terst for assert
- methods now support JSON revivers/replacers

2.0.1 / 2015-05-24
------------------
- update license attribute https://github.com/jprichardson/node-jsonfile/pull/21

2.0.0 / 2014-07-28
------------------
* added `\n` to end of file on write. [#14](https://github.com/jprichardson/node-jsonfile/pull/14)
* added `options.throws` to `readFileSync()`
* dropped support for Node v0.8

1.2.0 / 2014-06-29
------------------
* removed semicolons
* bugfix: passed `options` to `fs.readFile` and `fs.readFileSync`. This technically changes behavior, but
changes it according to docs. [#12][#12]

1.1.1 / 2013-11-11
------------------
* fixed catching of callback bug (ffissore / #5)

1.1.0 / 2013-10-11
------------------
* added `options` param to methods, (seanodell / #4)

1.0.1 / 2013-09-05
------------------
* removed `homepage` field from package.json to remove NPM warning

1.0.0 / 2013-06-28
------------------
* added `.npmignore`, #1
* changed spacing default from `4` to `2` to follow Node conventions

0.0.1 / 2012-09-10
------------------
* Initial release.

[#89]: https://github.com/jprichardson/node-jsonfile/pull/89
[#45]: https://github.com/jprichardson/node-jsonfile/issues/45    "Reading of UTF8-encoded (w/ BOM) files fails"
[#44]: https://github.com/jprichardson/node-jsonfile/issues/44    "Extra characters in written file"
[#43]: https://github.com/jprichardson/node-jsonfile/issues/43    "Prettyfy json when written to file"
[#42]: https://github.com/jprichardson/node-jsonfile/pull/42      "Moved fs.readFileSync within the try/catch"
[#41]: https://github.com/jprichardson/node-jsonfile/issues/41    "Linux: Hidden file not working"
[#40]: https://github.com/jprichardson/node-jsonfile/issues/40    "autocreate folder doesn't work from Path-value"
[#39]: https://github.com/jprichardson/node-jsonfile/pull/39      "Add `throws` option for readFile (async)"
[#38]: https://github.com/jprichardson/node-jsonfile/pull/38      "Update README.md writeFile[Sync] signature"
[#37]: https://github.com/jprichardson/node-jsonfile/pull/37      "support append file"
[#36]: https://github.com/jprichardson/node-jsonfile/pull/36      "Add typescript definition file."
[#35]: https://github.com/jprichardson/node-jsonfile/pull/35      "Add typescript definition file."
[#34]: https://github.com/jprichardson/node-jsonfile/pull/34      "readFile JSON parse error includes filename"
[#33]: https://github.com/jprichardson/node-jsonfile/pull/33      "fix throw->throws typo in readFileSync()"
[#32]: https://github.com/jprichardson/node-jsonfile/issues/32    "readFile & readFileSync can possible have strip-comments as an option?"
[#31]: https://github.com/jprichardson/node-jsonfile/pull/31      "[Modify] Support string include is unicode escape string"
[#30]: https://github.com/jprichardson/node-jsonfile/issues/30    "How to use Jsonfile package in Meteor.js App?"
[#29]: https://github.com/jprichardson/node-jsonfile/issues/29    "writefile callback if no error?"
[#28]: https://github.com/jprichardson/node-jsonfile/issues/28    "writeFile options argument broken "
[#27]: https://github.com/jprichardson/node-jsonfile/pull/27      "Use svg instead of png to get better image quality"
[#26]: https://github.com/jprichardson/node-jsonfile/issues/26    "Breaking change to fs-extra"
[#25]: https://github.com/jprichardson/node-jsonfile/issues/25    "support string encoding param for read methods"
[#24]: https://github.com/jprichardson/node-jsonfile/issues/24    "readFile: Passing in null options with a callback throws an error"
[#23]: https://github.com/jprichardson/node-jsonfile/pull/23      "Add appendFile and appendFileSync"
[#22]: https://github.com/jprichardson/node-jsonfile/issues/22    "Default value for spaces in readme.md is outdated"
[#21]: https://github.com/jprichardson/node-jsonfile/pull/21      "Update license attribute"
[#20]: https://github.com/jprichardson/node-jsonfile/issues/20    "Add simple caching functionallity"
[#19]: https://github.com/jprichardson/node-jsonfile/pull/19      "Add appendFileSync method"
[#18]: https://github.com/jprichardson/node-jsonfile/issues/18    "Add updateFile and updateFileSync methods"
[#17]: https://github.com/jprichardson/node-jsonfile/issues/17    "seem read & write sync has sequentially problem"
[#16]: https://github.com/jprichardson/node-jsonfile/pull/16      "export spaces defaulted to null"
[#15]: https://github.com/jprichardson/node-jsonfile/issues/15    "`jsonfile.spaces` should default to `null`"
[#14]: https://github.com/jprichardson/node-jsonfile/pull/14      "Add EOL at EOF"
[#13]: https://github.com/jprichardson/node-jsonfile/issues/13    "Add a final newline"
[#12]: https://github.com/jprichardson/node-jsonfile/issues/12    "readFile doesn't accept options"
[#11]: https://github.com/jprichardson/node-jsonfile/pull/11      "Added try,catch to readFileSync"
[#10]: https://github.com/jprichardson/node-jsonfile/issues/10    "No output or error from writeFile"
[#9]: https://github.com/jprichardson/node-jsonfile/pull/9        "Change 'js' to 'jf' in example."
[#8]: https://github.com/jprichardson/node-jsonfile/pull/8        "Updated forgotten module.exports to me."
[#7]: https://github.com/jprichardson/node-jsonfile/pull/7        "Add file name in error message"
[#6]: https://github.com/jprichardson/node-jsonfile/pull/6        "Use graceful-fs when possible"
[#5]: https://github.com/jprichardson/node-jsonfile/pull/5        "Jsonfile doesn't behave nicely when used inside a test suite."
[#4]: https://github.com/jprichardson/node-jsonfile/pull/4        "Added options parameter to writeFile and writeFileSync"
[#3]: https://github.com/jprichardson/node-jsonfile/issues/3      "test2"
[#2]: https://github.com/jprichardson/node-jsonfile/issues/2      "homepage field must be a string url. Deleted."
[#1]: https://github.com/jprichardson/node-jsonfile/pull/1        "adding an `.npmignore` file"


---

Node.js - jsonfile
================

Easily read/write JSON files in Node.js. _Note: this module cannot be used in the browser._

[![npm Package](https://img.shields.io/npm/v/jsonfile.svg?style=flat-square)](https://www.npmjs.org/package/jsonfile)
[![build status](https://secure.travis-ci.org/jprichardson/node-jsonfile.svg)](http://travis-ci.org/jprichardson/node-jsonfile)
[![windows Build status](https://img.shields.io/appveyor/ci/jprichardson/node-jsonfile/master.svg?label=windows%20build)](https://ci.appveyor.com/project/jprichardson/node-jsonfile/branch/master)

<a href="https://github.com/feross/standard"><img src="https://cdn.rawgit.com/feross/standard/master/sticker.svg" alt="Standard JavaScript" width="100"></a>

Why?
----

Writing `JSON.stringify()` and then `fs.writeFile()` and `JSON.parse()` with `fs.readFile()` enclosed in `try/catch` blocks became annoying.



Installation
------------

    npm install --save jsonfile



API
---

* [`readFile(filename, [options], callback)`](#readfilefilename-options-callback)
* [`readFileSync(filename, [options])`](#readfilesyncfilename-options)
* [`writeFile(filename, obj, [options], callback)`](#writefilefilename-obj-options-callback)
* [`writeFileSync(filename, obj, [options])`](#writefilesyncfilename-obj-options)

----

### readFile(filename, [options], callback)

`options` (`object`, default `undefined`): Pass in any [`fs.readFile`](https://nodejs.org/api/fs.html#fs_fs_readfile_path_options_callback) options or set `reviver` for a [JSON reviver](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse).
  - `throws` (`boolean`, default: `true`). If `JSON.parse` throws an error, pass this error to the callback.
  If `false`, returns `null` for the object.


```js
const jsonfile = require('jsonfile')
const file = '/tmp/data.json'
jsonfile.readFile(file, function (err, obj) {
  if (err) console.error(err)
  console.dir(obj)
})
```

You can also use this method with promises. The `readFile` method will return a promise if you do not pass a callback function.

```js
const jsonfile = require('jsonfile')
const file = '/tmp/data.json'
jsonfile.readFile(file)
  .then(obj => console.dir(obj))
  .catch(error => console.error(error))
```

----

### readFileSync(filename, [options])

`options` (`object`, default `undefined`): Pass in any [`fs.readFileSync`](https://nodejs.org/api/fs.html#fs_fs_readfilesync_path_options) options or set `reviver` for a [JSON reviver](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse).
- `throws` (`boolean`, default: `true`). If an error is encountered reading or parsing the file, throw the error. If `false`, returns `null` for the object.

```js
const jsonfile = require('jsonfile')
const file = '/tmp/data.json'

console.dir(jsonfile.readFileSync(file))
```

----

### writeFile(filename, obj, [options], callback)

`options`: Pass in any [`fs.writeFile`](https://nodejs.org/api/fs.html#fs_fs_writefile_file_data_options_callback) options or set `replacer` for a [JSON replacer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify). Can also pass in `spaces`, or override `EOL` string or set `finalEOL` flag as `false` to not save the file with `EOL` at the end.


```js
const jsonfile = require('jsonfile')

const file = '/tmp/data.json'
const obj = { name: 'JP' }

jsonfile.writeFile(file, obj, function (err) {
  if (err) console.error(err)
})
```
Or use with promises as follows:

```js
const jsonfile = require('jsonfile')

const file = '/tmp/data.json'
const obj = { name: 'JP' }

jsonfile.writeFile(file, obj)
  .then(res => {
    console.log('Write complete')
  })
  .catch(error => console.error(error))
```


**formatting with spaces:**

```js
const jsonfile = require('jsonfile')

const file = '/tmp/data.json'
const obj = { name: 'JP' }

jsonfile.writeFile(file, obj, { spaces: 2 }, function (err) {
  if (err) console.error(err)
})
```

**overriding EOL:**

```js
const jsonfile = require('jsonfile')

const file = '/tmp/data.json'
const obj = { name: 'JP' }

jsonfile.writeFile(file, obj, { spaces: 2, EOL: '\r\n' }, function (err) {
  if (err) console.error(err)
})
```


**disabling the EOL at the end of file:**

```js
const jsonfile = require('jsonfile')

const file = '/tmp/data.json'
const obj = { name: 'JP' }

jsonfile.writeFile(file, obj, { spaces: 2, finalEOL: false }, function (err) {
  if (err) console.log(err)
})
```

**appending to an existing JSON file:**

You can use `fs.writeFile` option `{ flag: 'a' }` to achieve this.

```js
const jsonfile = require('jsonfile')

const file = '/tmp/mayAlreadyExistedData.json'
const obj = { name: 'JP' }

jsonfile.writeFile(file, obj, { flag: 'a' }, function (err) {
  if (err) console.error(err)
})
```

----

### writeFileSync(filename, obj, [options])

`options`: Pass in any [`fs.writeFileSync`](https://nodejs.org/api/fs.html#fs_fs_writefilesync_file_data_options) options or set `replacer` for a [JSON replacer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify). Can also pass in `spaces`, or override `EOL` string or set `finalEOL` flag as `false` to not save the file with `EOL` at the end.

```js
const jsonfile = require('jsonfile')

const file = '/tmp/data.json'
const obj = { name: 'JP' }

jsonfile.writeFileSync(file, obj)
```

**formatting with spaces:**

```js
const jsonfile = require('jsonfile')

const file = '/tmp/data.json'
const obj = { name: 'JP' }

jsonfile.writeFileSync(file, obj, { spaces: 2 })
```

**overriding EOL:**

```js
const jsonfile = require('jsonfile')

const file = '/tmp/data.json'
const obj = { name: 'JP' }

jsonfile.writeFileSync(file, obj, { spaces: 2, EOL: '\r\n' })
```

**disabling the EOL at the end of file:**

```js
const jsonfile = require('jsonfile')

const file = '/tmp/data.json'
const obj = { name: 'JP' }

jsonfile.writeFileSync(file, obj, { spaces: 2, finalEOL: false })
```

**appending to an existing JSON file:**

You can use `fs.writeFileSync` option `{ flag: 'a' }` to achieve this.

```js
const jsonfile = require('jsonfile')

const file = '/tmp/mayAlreadyExistedData.json'
const obj = { name: 'JP' }

jsonfile.writeFileSync(file, obj, { flag: 'a' })
```

License
-------

(MIT License)

Copyright 2012-2016, JP Richardson  <jprichardson@gmail.com>


---

<h1 align="center">
	<img width="250" src="https://jaredwray.com/images/keyv.svg" alt="keyv">
	<br>
	<br>
</h1>

> Simple key-value storage with support for multiple backends

[![build](https://github.com/jaredwray/keyv/actions/workflows/tests.yaml/badge.svg)](https://github.com/jaredwray/keyv/actions/workflows/tests.yaml)
[![codecov](https://codecov.io/gh/jaredwray/keyv/branch/main/graph/badge.svg?token=bRzR3RyOXZ)](https://codecov.io/gh/jaredwray/keyv)
[![npm](https://img.shields.io/npm/dm/keyv.svg)](https://www.npmjs.com/package/keyv)
[![npm](https://img.shields.io/npm/v/keyv.svg)](https://www.npmjs.com/package/keyv)

Keyv provides a consistent interface for key-value storage across multiple backends via storage adapters. It supports TTL based expiry, making it suitable as a cache or a persistent key-value store.

## Features

There are a few existing modules similar to Keyv, however Keyv is different because it:

- Isn't bloated
- Has a simple Promise based API
- Suitable as a TTL based cache or persistent key-value store
- [Easily embeddable](#add-cache-support-to-your-module) inside another module
- Works with any storage that implements the [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) API
- Handles all JSON types plus `Buffer`
- Supports namespaces
- Wide range of [**efficient, well tested**](#official-storage-adapters) storage adapters
- Connection errors are passed through (db failures won't kill your app)
- Supports the current active LTS version of Node.js or higher

## Usage

Install Keyv.

```
npm install --save keyv
```

By default everything is stored in memory, you can optionally also install a storage adapter.

```
npm install --save @keyv/redis
npm install --save @keyv/mongo
npm install --save @keyv/sqlite
npm install --save @keyv/postgres
npm install --save @keyv/mysql
npm install --save @keyv/etcd
```

Create a new Keyv instance, passing your connection string if applicable. Keyv will automatically load the correct storage adapter.

```js
const Keyv = require('keyv');

// One of the following
const keyv = new Keyv();
const keyv = new Keyv('redis://user:pass@localhost:6379');
const keyv = new Keyv('mongodb://user:pass@localhost:27017/dbname');
const keyv = new Keyv('sqlite://path/to/database.sqlite');
const keyv = new Keyv('postgresql://user:pass@localhost:5432/dbname');
const keyv = new Keyv('mysql://user:pass@localhost:3306/dbname');
const keyv = new Keyv('etcd://localhost:2379');

// Handle DB connection errors
keyv.on('error', err => console.log('Connection Error', err));

await keyv.set('foo', 'expires in 1 second', 1000); // true
await keyv.set('foo', 'never expires'); // true
await keyv.get('foo'); // 'never expires'
await keyv.delete('foo'); // true
await keyv.clear(); // undefined
```

### Namespaces

You can namespace your Keyv instance to avoid key collisions and allow you to clear only a certain namespace while using the same database.

```js
const users = new Keyv('redis://user:pass@localhost:6379', { namespace: 'users' });
const cache = new Keyv('redis://user:pass@localhost:6379', { namespace: 'cache' });

await users.set('foo', 'users'); // true
await cache.set('foo', 'cache'); // true
await users.get('foo'); // 'users'
await cache.get('foo'); // 'cache'
await users.clear(); // undefined
await users.get('foo'); // undefined
await cache.get('foo'); // 'cache'
```

### Custom Serializers

Keyv uses [`json-buffer`](https://github.com/dominictarr/json-buffer) for data serialization to ensure consistency across different backends.

You can optionally provide your own serialization functions to support extra data types or to serialize to something other than JSON.

```js
const keyv = new Keyv({ serialize: JSON.stringify, deserialize: JSON.parse });
```

**Warning:** Using custom serializers means you lose any guarantee of data consistency. You should do extensive testing with your serialisation functions and chosen storage engine.

## Official Storage Adapters

The official storage adapters are covered by [over 150 integration tests](https://github.com/jaredwray/keyv/actions/workflows/tests.yaml) to guarantee consistent behaviour. They are lightweight, efficient wrappers over the DB clients making use of indexes and native TTLs where available.

Database | Adapter | Native TTL
---|---|---
Redis | [@keyv/redis](https://github.com/jaredwray/keyv/tree/master/packages/redis) | Yes
MongoDB | [@keyv/mongo](https://github.com/jaredwray/keyv/tree/master/packages/mongo) | Yes 
SQLite | [@keyv/sqlite](https://github.com/jaredwray/keyv/tree/master/packages/sqlite) | No 
PostgreSQL | [@keyv/postgres](https://github.com/jaredwray/keyv/tree/master/packages/postgres) | No 
MySQL | [@keyv/mysql](https://github.com/jaredwray/keyv/tree/master/packages/mysql) | No 
Etcd | [@keyv/etcd](https://github.com/jaredwray/keyv/tree/master/packages/etcd) | Yes
Memcache | [@keyv/memcache](https://github.com/jaredwray/keyv/tree/master/packages/memcache) | Yes

## Third-party Storage Adapters

You can also use third-party storage adapters or build your own. Keyv will wrap these storage adapters in TTL functionality and handle complex types internally.

```js
const Keyv = require('keyv');
const myAdapter = require('./my-storage-adapter');

const keyv = new Keyv({ store: myAdapter });
```

Any store that follows the [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) api will work.

```js
new Keyv({ store: new Map() });
```

For example, [`quick-lru`](https://github.com/sindresorhus/quick-lru) is a completely unrelated module that implements the Map API.

```js
const Keyv = require('keyv');
const QuickLRU = require('quick-lru');

const lru = new QuickLRU({ maxSize: 1000 });
const keyv = new Keyv({ store: lru });
```

The following are third-party storage adapters compatible with Keyv:

- [quick-lru](https://github.com/sindresorhus/quick-lru) - Simple "Least Recently Used" (LRU) cache
- [keyv-file](https://github.com/zaaack/keyv-file) - File system storage adapter for Keyv
- [keyv-dynamodb](https://www.npmjs.com/package/keyv-dynamodb) - DynamoDB storage adapter for Keyv
- [keyv-lru](https://www.npmjs.com/package/keyv-lru) - LRU storage adapter for Keyv
- [keyv-null](https://www.npmjs.com/package/keyv-null) - Null storage adapter for Keyv
- [keyv-firestore ](https://github.com/goto-bus-stop/keyv-firestore) – Firebase Cloud Firestore adapter for Keyv
- [keyv-mssql](https://github.com/pmorgan3/keyv-mssql) - Microsoft Sql Server adapter for Keyv
- [keyv-azuretable](https://github.com/howlowck/keyv-azuretable) - Azure Table Storage/API adapter for Keyv
- [keyv-arango](https://github.com/TimMikeladze/keyv-arango) - ArangoDB storage adapter for Keyv
- [keyv-momento](https://github.com/momentohq/node-keyv-adaptor/) - Momento storage adapter for Keyv

## Add Cache Support to your Module

Keyv is designed to be easily embedded into other modules to add cache support. The recommended pattern is to expose a `cache` option in your modules options which is passed through to Keyv. Caching will work in memory by default and users have the option to also install a Keyv storage adapter and pass in a connection string, or any other storage that implements the `Map` API.

You should also set a namespace for your module so you can safely call `.clear()` without clearing unrelated app data.

Inside your module:

```js
class AwesomeModule {
	constructor(opts) {
		this.cache = new Keyv({
			uri: typeof opts.cache === 'string' && opts.cache,
			store: typeof opts.cache !== 'string' && opts.cache,
			namespace: 'awesome-module'
		});
	}
}
```

Now it can be consumed like this:

```js
const AwesomeModule = require('awesome-module');

// Caches stuff in memory by default
const awesomeModule = new AwesomeModule();

// After npm install --save keyv-redis
const awesomeModule = new AwesomeModule({ cache: 'redis://localhost' });

// Some third-party module that implements the Map API
const awesomeModule = new AwesomeModule({ cache: some3rdPartyStore });
```

## Compression

Keyv supports `gzip` and `brotli` compression. To enable compression, pass the `compress` option to the constructor.

```js
const KeyvGzip = require('@keyv/compress-gzip');
const Keyv = require('keyv');

const keyvGzip = new KeyvGzip();
const keyv = new Keyv({ compression: KeyvGzip });
```

You can also pass a custom compression function to the `compression` option. Following the pattern of the official compression adapters.

### Want to build your own? 

Great! Keyv is designed to be easily extended. You can build your own compression adapter by following the pattern of the official compression adapters based on this interface:

```typescript
interface CompressionAdapter {
	async compress(value: any, options?: any);
	async decompress(value: any, options?: any);
	async serialize(value: any);
	async deserialize(value: any);
}
```

In addition to the interface, you can test it with our compression test suite using @keyv/test-suite:

```js
const {keyvCompresstionTests} = require('@keyv/test-suite');
const KeyvGzip = require('@keyv/compress-gzip');

keyvCompresstionTests(test, new KeyvGzip());
```

## API

### new Keyv([uri], [options])

Returns a new Keyv instance.

The Keyv instance is also an `EventEmitter` that will emit an `'error'` event if the storage adapter connection fails.

### uri

Type: `String`<br>
Default: `undefined`

The connection string URI.

Merged into the options object as options.uri.

### options

Type: `Object`

The options object is also passed through to the storage adapter. Check your storage adapter docs for any extra options.

#### options.namespace

Type: `String`<br>
Default: `'keyv'`

Namespace for the current instance.

#### options.ttl

Type: `Number`<br>
Default: `undefined`

Default TTL. Can be overridden by specififying a TTL on `.set()`.

#### options.compression

Type: `@keyv/compress-<compression_package_name>`<br>
Default: `undefined`

Compression package to use. See [Compression](#compression) for more details.

#### options.serialize

Type: `Function`<br>
Default: `JSONB.stringify`

A custom serialization function.

#### options.deserialize

Type: `Function`<br>
Default: `JSONB.parse`

A custom deserialization function.

#### options.store

Type: `Storage adapter instance`<br>
Default: `new Map()`

The storage adapter instance to be used by Keyv.

#### options.adapter

Type: `String`<br>
Default: `undefined`

Specify an adapter to use. e.g `'redis'` or `'mongodb'`.

### Instance

Keys must always be strings. Values can be of any type.

#### .set(key, value, [ttl])

Set a value.

By default keys are persistent. You can set an expiry TTL in milliseconds.

Returns a promise which resolves to `true`.

#### .get(key, [options])

Returns a promise which resolves to the retrieved value.

##### options.raw

Type: `Boolean`<br>
Default: `false`

If set to true the raw DB object Keyv stores internally will be returned instead of just the value.

This contains the TTL timestamp.

#### .delete(key)

Deletes an entry.

Returns a promise which resolves to `true` if the key existed, `false` if not.

#### .clear()

Delete all entries in the current namespace.

Returns a promise which is resolved when the entries have been cleared.

#### .iterator()

Iterate over all entries of the current namespace.

Returns a iterable that can be iterated by for-of loops. For example:

```js
// please note that the "await" keyword should be used here
for await (const [key, value] of this.keyv.iterator()) {
  console.log(key, value);
};
```

# How to Contribute

In this section of the documentation we will cover:

1) How to set up this repository locally
2) How to get started with running commands
3) How to contribute changes using Pull Requests

## Dependencies

This package requires the following dependencies to run:

1) [Yarn V1](https://yarnpkg.com/getting-started/install)
3) [Docker](https://docs.docker.com/get-docker/)

## Setting up your workspace

To contribute to this repository, start by setting up this project locally:

1) Fork this repository into your Git account
2) Clone the forked repository to your local directory using `git clone`
3) Install any of the above missing dependencies

## Launching the project

Once the project is installed locally, you are ready to start up its services:

1) Ensure that your Docker service is running.
2) From the root directory of your project, run the `yarn` command in the command prompt to install yarn.
3) Run the `yarn bootstrap` command to  install any necessary dependencies.
4) Run `yarn test:services:start` to start up this project's Docker container. The container will launch all services within your workspace.

## Available Commands

Once the project is running, you can execute a variety of commands. The root workspace and each subpackage contain a `package.json` file with a  `scripts` field listing all the commands that can be executed from that directory. This project also supports native `yarn`, and `docker` commands.

Here, we'll cover the primary commands that can be executed from the root directory. Unless otherwise noted, these commands can also be executed from a subpackage. If executed from a subpackage, they will only affect that subpackage, rather than the entire workspace.

### `yarn`

The `yarn` command installs yarn in the workspace.

### `yarn bootstrap`

The `yarn bootstrap` command installs all dependencies in the workspace.

### `yarn test:services:start`

The `yarn test:services:start` command starts up the project's Docker container, launching all services in the workspace. This command must be executed from the root directory.

### `yarn test:services:stop`

The `yarn test:services:stop` command brings down the project's Docker container, halting all services. This command must be executed from the root directory.

### `yarn test`

The `yarn test` command runs all tests in the workspace.

### `yarn clean`

The `yarn clean` command removes yarn and all dependencies installed by yarn. After executing this command, you must repeat the steps in *Setting up your workspace* to rebuild your workspace.

## Contributing Changes

Now that you've set up your workspace, you're ready to contribute changes to the `keyv` repository.

1) Make any changes that you would like to contribute in your local workspace.
2) After making these changes, ensure that the project's tests still pass by executing the `yarn test` command in the root directory.
3) Commit your changes and push them to your forked repository.
4) Navigate to the original `keyv` repository and go the *Pull Requests* tab.
5) Click the *New pull request* button, and open a pull request for the branch in your repository that contains your changes.
6) Once your pull request is created, ensure that all checks have passed and that your branch has no conflicts with the base branch. If there are any issues, resolve these changes in your local repository, and then commit and push them to git.
7) Similarly, respond to any reviewer comments or requests for changes by making edits to your local repository and pushing them to Git.
8) Once the pull request has been reviewed, those with write access to the branch will be able to merge your changes into the `keyv` repository.

If you need more information on the steps to create a pull request, you can find a detailed walkthrough in the [Github documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork)

## License

MIT © Jared Wray


---

# Release history

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).

<details>
  <summary><strong>Guiding Principles</strong></summary>

- Changelogs are for humans, not machines.
- There should be an entry for every single version.
- The same types of changes should be grouped.
- Versions and sections should be linkable.
- The latest version comes first.
- The release date of each versions is displayed.
- Mention whether you follow Semantic Versioning.

</details>

<details>
  <summary><strong>Types of changes</strong></summary>

Changelog entries are classified using the following labels _(from [keep-a-changelog](http://keepachangelog.com/)_):

- `Added` for new features.
- `Changed` for changes in existing functionality.
- `Deprecated` for soon-to-be removed features.
- `Removed` for now removed features.
- `Fixed` for any bug fixes.
- `Security` in case of vulnerabilities.

</details>

## [6.0.3] - 2020-01-16

- Merge pull request #31 for issue #30

## [6.0.0] - 2017-10-13

- refactor code to be more performant
- refactor benchmarks

## [5.1.0] - 2017-10-13

**Added**

- Merge pull request #15 from aretecode/patch-1
- adds support and tests for string & array iterators

**Changed**

- updates benchmarks

## [5.0.2] - 2017-08-02

- Merge pull request #14 from struct78/master
- Added `undefined` check

## [5.0.0] - 2017-06-21

- Merge pull request #12 from aretecode/iterator
- Set Iterator + Map Iterator
- streamline `isbuffer`, minor edits

## [4.0.0] - 2017-05-19

- Merge pull request #8 from tunnckoCore/master
- update deps

## [3.2.2] - 2017-05-16

- fix version

## [3.2.1] - 2017-05-16

- add browserify

## [3.2.0] - 2017-04-25

- Merge pull request #10 from ksheedlo/unrequire-buffer
- add `promise` support and tests
- Remove unnecessary `Buffer` check

## [3.1.0] - 2016-12-07

- Merge pull request #7 from laggingreflex/err
- add support for `error` and tests
- run update

## [3.0.4] - 2016-07-29

- move tests
- run update

## [3.0.3] - 2016-05-03

- fix prepublish script
- remove unused dep

## [3.0.0] - 2015-11-17

- add typed array support
- Merge pull request #5 from miguelmota/typed-arrays
- adds new tests

## [2.0.1] - 2015-08-21

- use `is-buffer` module

## [2.0.0] - 2015-05-31

- Create fallback for `Array.isArray` if used as a browser package
- Merge pull request #2 from dtothefp/patch-1
- Merge pull request #3 from pdehaan/patch-1
- Merge branch 'master' of https://github.com/chorks/kind-of into chorks-master
- optimizations, mostly date and regex

## [1.1.0] - 2015-02-09

- adds `buffer` support
- adds tests for `buffer`

## [1.0.0] - 2015-01-19

- update benchmarks
- optimizations based on benchmarks

## [0.1.2] - 2014-10-26

- return `typeof` value if it's not an object. very slight speed improvement
- use `.slice`
- adds benchmarks

## [0.1.0] - 2014-9-26

- first commit

[6.0.0]: https://github.com/jonschlinkert/kind-of/compare/5.1.0...6.0.0
[5.1.0]: https://github.com/jonschlinkert/kind-of/compare/5.0.2...5.1.0
[5.0.2]: https://github.com/jonschlinkert/kind-of/compare/5.0.1...5.0.2
[5.0.1]: https://github.com/jonschlinkert/kind-of/compare/5.0.0...5.0.1
[5.0.0]: https://github.com/jonschlinkert/kind-of/compare/4.0.0...5.0.0
[4.0.0]: https://github.com/jonschlinkert/kind-of/compare/3.2.2...4.0.0
[3.2.2]: https://github.com/jonschlinkert/kind-of/compare/3.2.1...3.2.2
[3.2.1]: https://github.com/jonschlinkert/kind-of/compare/3.2.0...3.2.1
[3.2.0]: https://github.com/jonschlinkert/kind-of/compare/3.1.0...3.2.0
[3.1.0]: https://github.com/jonschlinkert/kind-of/compare/3.0.4...3.1.0
[3.0.4]: https://github.com/jonschlinkert/kind-of/compare/3.0.3...3.0.4
[3.0.3]: https://github.com/jonschlinkert/kind-of/compare/3.0.0...3.0.3
[3.0.0]: https://github.com/jonschlinkert/kind-of/compare/2.0.1...3.0.0
[2.0.1]: https://github.com/jonschlinkert/kind-of/compare/2.0.0...2.0.1
[2.0.0]: https://github.com/jonschlinkert/kind-of/compare/1.1.0...2.0.0
[1.1.0]: https://github.com/jonschlinkert/kind-of/compare/1.0.0...1.1.0
[1.0.0]: https://github.com/jonschlinkert/kind-of/compare/0.1.2...1.0.0
[0.1.2]: https://github.com/jonschlinkert/kind-of/compare/0.1.0...0.1.2
[0.1.0]: https://github.com/jonschlinkert/kind-of/commit/2fae09b0b19b1aadb558e9be39f0c3ef6034eb87

[Unreleased]: https://github.com/jonschlinkert/kind-of/compare/0.1.2...HEAD
[keep-a-changelog]: https://github.com/olivierlacan/keep-a-changelog

---

# kind-of [![NPM version](https://img.shields.io/npm/v/kind-of.svg?style=flat)](https://www.npmjs.com/package/kind-of) [![NPM monthly downloads](https://img.shields.io/npm/dm/kind-of.svg?style=flat)](https://npmjs.org/package/kind-of) [![NPM total downloads](https://img.shields.io/npm/dt/kind-of.svg?style=flat)](https://npmjs.org/package/kind-of) [![Linux Build Status](https://img.shields.io/travis/jonschlinkert/kind-of.svg?style=flat&label=Travis)](https://travis-ci.org/jonschlinkert/kind-of)

> Get the native type of a value.

Please consider following this project's author, [Jon Schlinkert](https://github.com/jonschlinkert), and consider starring the project to show your :heart: and support.

## Install

Install with [npm](https://www.npmjs.com/):

```sh
$ npm install --save kind-of
```

Install with [bower](https://bower.io/)

```sh
$ bower install kind-of --save
```

## Why use this?

1. [it's fast](#benchmarks) | [optimizations](#optimizations)
2. [better type checking](#better-type-checking)

## Usage

> es5, es6, and browser ready

```js
var kindOf = require('kind-of');

kindOf(undefined);
//=> 'undefined'

kindOf(null);
//=> 'null'

kindOf(true);
//=> 'boolean'

kindOf(false);
//=> 'boolean'

kindOf(new Buffer(''));
//=> 'buffer'

kindOf(42);
//=> 'number'

kindOf('str');
//=> 'string'

kindOf(arguments);
//=> 'arguments'

kindOf({});
//=> 'object'

kindOf(Object.create(null));
//=> 'object'

kindOf(new Test());
//=> 'object'

kindOf(new Date());
//=> 'date'

kindOf([1, 2, 3]);
//=> 'array'

kindOf(/foo/);
//=> 'regexp'

kindOf(new RegExp('foo'));
//=> 'regexp'

kindOf(new Error('error'));
//=> 'error'

kindOf(function () {});
//=> 'function'

kindOf(function * () {});
//=> 'generatorfunction'

kindOf(Symbol('str'));
//=> 'symbol'

kindOf(new Map());
//=> 'map'

kindOf(new WeakMap());
//=> 'weakmap'

kindOf(new Set());
//=> 'set'

kindOf(new WeakSet());
//=> 'weakset'

kindOf(new Int8Array());
//=> 'int8array'

kindOf(new Uint8Array());
//=> 'uint8array'

kindOf(new Uint8ClampedArray());
//=> 'uint8clampedarray'

kindOf(new Int16Array());
//=> 'int16array'

kindOf(new Uint16Array());
//=> 'uint16array'

kindOf(new Int32Array());
//=> 'int32array'

kindOf(new Uint32Array());
//=> 'uint32array'

kindOf(new Float32Array());
//=> 'float32array'

kindOf(new Float64Array());
//=> 'float64array'
```

## Benchmarks

Benchmarked against [typeof](http://github.com/CodingFu/typeof) and [type-of](https://github.com/ForbesLindesay/type-of).

```bash
# arguments (32 bytes)
  kind-of x 17,024,098 ops/sec ±1.90% (86 runs sampled)
  lib-type-of x 11,926,235 ops/sec ±1.34% (83 runs sampled)
  lib-typeof x 9,245,257 ops/sec ±1.22% (87 runs sampled)

  fastest is kind-of (by 161% avg)

# array (22 bytes)
  kind-of x 17,196,492 ops/sec ±1.07% (88 runs sampled)
  lib-type-of x 8,838,283 ops/sec ±1.02% (87 runs sampled)
  lib-typeof x 8,677,848 ops/sec ±0.87% (87 runs sampled)

  fastest is kind-of (by 196% avg)

# boolean (24 bytes)
  kind-of x 16,841,600 ops/sec ±1.10% (86 runs sampled)
  lib-type-of x 8,096,787 ops/sec ±0.95% (87 runs sampled)
  lib-typeof x 8,423,345 ops/sec ±1.15% (86 runs sampled)

  fastest is kind-of (by 204% avg)

# buffer (38 bytes)
  kind-of x 14,848,060 ops/sec ±1.05% (86 runs sampled)
  lib-type-of x 3,671,577 ops/sec ±1.49% (87 runs sampled)
  lib-typeof x 8,360,236 ops/sec ±1.24% (86 runs sampled)

  fastest is kind-of (by 247% avg)

# date (30 bytes)
  kind-of x 16,067,761 ops/sec ±1.58% (86 runs sampled)
  lib-type-of x 8,954,436 ops/sec ±1.40% (87 runs sampled)
  lib-typeof x 8,488,307 ops/sec ±1.51% (84 runs sampled)

  fastest is kind-of (by 184% avg)

# error (36 bytes)
  kind-of x 9,634,090 ops/sec ±1.12% (89 runs sampled)
  lib-type-of x 7,735,624 ops/sec ±1.32% (86 runs sampled)
  lib-typeof x 7,442,160 ops/sec ±1.11% (90 runs sampled)

  fastest is kind-of (by 127% avg)

# function (34 bytes)
  kind-of x 10,031,494 ops/sec ±1.27% (86 runs sampled)
  lib-type-of x 9,502,757 ops/sec ±1.17% (89 runs sampled)
  lib-typeof x 8,278,985 ops/sec ±1.08% (88 runs sampled)

  fastest is kind-of (by 113% avg)

# null (24 bytes)
  kind-of x 18,159,808 ops/sec ±1.92% (86 runs sampled)
  lib-type-of x 12,927,635 ops/sec ±1.01% (88 runs sampled)
  lib-typeof x 7,958,234 ops/sec ±1.21% (89 runs sampled)

  fastest is kind-of (by 174% avg)

# number (22 bytes)
  kind-of x 17,846,779 ops/sec ±0.91% (85 runs sampled)
  lib-type-of x 3,316,636 ops/sec ±1.19% (86 runs sampled)
  lib-typeof x 2,329,477 ops/sec ±2.21% (85 runs sampled)

  fastest is kind-of (by 632% avg)

# object-plain (47 bytes)
  kind-of x 7,085,155 ops/sec ±1.05% (88 runs sampled)
  lib-type-of x 8,870,930 ops/sec ±1.06% (83 runs sampled)
  lib-typeof x 8,716,024 ops/sec ±1.05% (87 runs sampled)

  fastest is lib-type-of (by 112% avg)

# regex (25 bytes)
  kind-of x 14,196,052 ops/sec ±1.65% (84 runs sampled)
  lib-type-of x 9,554,164 ops/sec ±1.25% (88 runs sampled)
  lib-typeof x 8,359,691 ops/sec ±1.07% (87 runs sampled)

  fastest is kind-of (by 158% avg)

# string (33 bytes)
  kind-of x 16,131,428 ops/sec ±1.41% (85 runs sampled)
  lib-type-of x 7,273,172 ops/sec ±1.05% (87 runs sampled)
  lib-typeof x 7,382,635 ops/sec ±1.17% (85 runs sampled)

  fastest is kind-of (by 220% avg)

# symbol (34 bytes)
  kind-of x 17,011,537 ops/sec ±1.24% (86 runs sampled)
  lib-type-of x 3,492,454 ops/sec ±1.23% (89 runs sampled)
  lib-typeof x 7,471,235 ops/sec ±2.48% (87 runs sampled)

  fastest is kind-of (by 310% avg)

# template-strings (36 bytes)
  kind-of x 15,434,250 ops/sec ±1.46% (83 runs sampled)
  lib-type-of x 7,157,907 ops/sec ±0.97% (87 runs sampled)
  lib-typeof x 7,517,986 ops/sec ±0.92% (86 runs sampled)

  fastest is kind-of (by 210% avg)

# undefined (29 bytes)
  kind-of x 19,167,115 ops/sec ±1.71% (87 runs sampled)
  lib-type-of x 15,477,740 ops/sec ±1.63% (85 runs sampled)
  lib-typeof x 19,075,495 ops/sec ±1.17% (83 runs sampled)

  fastest is lib-typeof,kind-of

```

## Optimizations

In 7 out of 8 cases, this library is 2x-10x faster than other top libraries included in the benchmarks. There are a few things that lead to this performance advantage, none of them hard and fast rules, but all of them simple and repeatable in almost any code library:

1. Optimize around the fastest and most common use cases first. Of course, this will change from project-to-project, but I took some time to understand how and why `typeof` checks were being used in my own libraries and other libraries I use a lot.
2. Optimize around bottlenecks - In other words, the order in which conditionals are implemented is significant, because each check is only as fast as the failing checks that came before it. Here, the biggest bottleneck by far is checking for plain objects (an object that was created by the `Object` constructor). I opted to make this check happen by process of elimination rather than brute force up front (e.g. by using something like `val.constructor.name`), so that every other type check would not be penalized it.
3. Don't do uneccessary processing - why do `.slice(8, -1).toLowerCase();` just to get the word `regex`? It's much faster to do `if (type === '[object RegExp]') return 'regex'`
4. There is no reason to make the code in a microlib as terse as possible, just to win points for making it shorter. It's always better to favor performant code over terse code. You will always only be using a single `require()` statement to use the library anyway, regardless of how the code is written.

## Better type checking

kind-of seems to be more consistently "correct" than other type checking libs I've looked at. For example, here are some differing results from other popular libs:

### [typeof](https://github.com/CodingFu/typeof) lib

Incorrectly identifies instances of custom constructors (pretty common):

```js
var typeOf = require('typeof');
function Test() {}
console.log(typeOf(new Test()));
//=> 'test'
```

Returns `object` instead of `arguments`:

```js
function foo() {
  console.log(typeOf(arguments)) //=> 'object'
}
foo();
```

### [type-of](https://github.com/ForbesLindesay/type-of) lib

Incorrectly returns `object` for generator functions, buffers, `Map`, `Set`, `WeakMap` and `WeakSet`:

```js
function * foo() {}
console.log(typeOf(foo));
//=> 'object'
console.log(typeOf(new Buffer('')));
//=> 'object'
console.log(typeOf(new Map()));
//=> 'object'
console.log(typeOf(new Set()));
//=> 'object'
console.log(typeOf(new WeakMap()));
//=> 'object'
console.log(typeOf(new WeakSet()));
//=> 'object'
```

## About

<details>
<summary><strong>Contributing</strong></summary>

Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).

</details>

<details>
<summary><strong>Running Tests</strong></summary>

Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

```sh
$ npm install && npm test
```

</details>

<details>
<summary><strong>Building docs</strong></summary>

_(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_

To generate the readme, run the following command:

```sh
$ npm install -g verbose/verb#dev verb-generate-readme && verb
```

</details>

### Related projects

You might also be interested in these projects:

* [is-glob](https://www.npmjs.com/package/is-glob): Returns `true` if the given string looks like a glob pattern or an extglob pattern… [more](https://github.com/micromatch/is-glob) | [homepage](https://github.com/micromatch/is-glob "Returns `true` if the given string looks like a glob pattern or an extglob pattern. This makes it easy to create code that only uses external modules like node-glob when necessary, resulting in much faster code execution and initialization time, and a bet")
* [is-number](https://www.npmjs.com/package/is-number): Returns true if a number or string value is a finite number. Useful for regex… [more](https://github.com/jonschlinkert/is-number) | [homepage](https://github.com/jonschlinkert/is-number "Returns true if a number or string value is a finite number. Useful for regex matches, parsing, user input, etc.")
* [is-primitive](https://www.npmjs.com/package/is-primitive): Returns `true` if the value is a primitive.  | [homepage](https://github.com/jonschlinkert/is-primitive "Returns `true` if the value is a primitive. ")

### Contributors

| **Commits** | **Contributor** |  
| --- | --- |  
| 102 | [jonschlinkert](https://github.com/jonschlinkert) |  
| 3   | [aretecode](https://github.com/aretecode) |  
| 2   | [miguelmota](https://github.com/miguelmota) |  
| 1   | [doowb](https://github.com/doowb) |  
| 1   | [dtothefp](https://github.com/dtothefp) |  
| 1   | [ianstormtaylor](https://github.com/ianstormtaylor) |  
| 1   | [ksheedlo](https://github.com/ksheedlo) |  
| 1   | [pdehaan](https://github.com/pdehaan) |  
| 1   | [laggingreflex](https://github.com/laggingreflex) |  
| 1   | [tunnckoCore](https://github.com/tunnckoCore) |  
| 1   | [xiaofen9](https://github.com/xiaofen9) |  

### Author

**Jon Schlinkert**

* [GitHub Profile](https://github.com/jonschlinkert)
* [Twitter Profile](https://twitter.com/jonschlinkert)
* [LinkedIn Profile](https://linkedin.com/in/jonschlinkert)

### License

Copyright © 2020, [Jon Schlinkert](https://github.com/jonschlinkert).
Released under the [MIT License](LICENSE).

***

_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.8.0, on January 16, 2020._

---

<div align="center">
  <img src="shots/logo.png" alt="kleur" height="120" />
</div>

<div align="center">
  <a href="https://npmjs.org/package/kleur">
    <img src="https://badgen.now.sh/npm/v/kleur" alt="version" />
  </a>
  <a href="https://travis-ci.org/lukeed/kleur">
    <img src="https://badgen.now.sh/travis/lukeed/kleur" alt="travis" />
  </a>
  <a href="https://npmjs.org/package/kleur">
    <img src="https://badgen.now.sh/npm/dm/kleur" alt="downloads" />
  </a>
  <a href="https://packagephobia.now.sh/result?p=kleur">
    <img src="https://packagephobia.now.sh/badge?p=kleur" alt="install size" />
  </a>
</div>

<div align="center">The fastest Node.js library for formatting terminal text with ANSI colors~!</div>

## Features

* No dependencies
* Super [lightweight](#load-time) & [performant](#performance)
* Supports [nested](#nested-methods) & [chained](#chained-methods) colors
* No `String.prototype` modifications
* Conditional [color support](#conditional-support)
* Familiar [API](#api)

---

As of `v3.0` the Chalk-style syntax (magical getter) is no longer used.<br>If you need or require that syntax, consider using [`ansi-colors`](https://github.com/doowb/ansi-colors), which maintains `chalk` parity.

---


## Install

```
$ npm install --save kleur
```


## Usage

```js
const { red, white, blue, bold } = require('kleur');

// basic usage
red('red text');

// chained methods
blue().bold().underline('howdy partner');

// nested methods
bold(`${ white().bgRed('[ERROR]') } ${ red().italic('Something happened')}`);
```

### Chained Methods

```js
console.log(bold().red('this is a bold red message'));
console.log(bold().italic('this is a bold italicized message'));
console.log(bold().yellow().bgRed().italic('this is a bold yellow italicized message'));
console.log(green().bold().underline('this is a bold green underlined message'));
```

<img src="shots/1.png" width="300" />

### Nested Methods

```js
const { yellow, red, cyan } = require('kleur');

console.log(yellow(`foo ${red().bold('red')} bar ${cyan('cyan')} baz`));
console.log(yellow('foo ' + red().bold('red') + ' bar ' + cyan('cyan') + ' baz'));
```

<img src="shots/2.png" width="300" />


### Conditional Support

Toggle color support as needed; `kleur` includes simple auto-detection which may not cover all cases.

```js
const kleur = require('kleur');

// manually disable
kleur.enabled = false;

// or use another library to detect support
kleur.enabled = require('color-support').level;

console.log(kleur.red('I will only be colored red if the terminal supports colors'));
```


## API

Any `kleur` method returns a `String` when invoked with input; otherwise chaining is expected.

> It's up to the developer to pass the output to destinations like `console.log`, `process.stdout.write`, etc.

The methods below are grouped by type for legibility purposes only. They each can be [chained](#chained-methods) or [nested](#nested-methods) with one another.

***Colors:***
> black &mdash; red &mdash; green &mdash; yellow &mdash; blue &mdash; magenta &mdash; cyan &mdash; white &mdash; gray &mdash; grey

***Backgrounds:***
> bgBlack &mdash; bgRed &mdash; bgGreen &mdash; bgYellow &mdash; bgBlue &mdash; bgMagenta &mdash; bgCyan &mdash; bgWhite

***Modifiers:***
> reset &mdash; bold &mdash; dim &mdash; italic* &mdash; underline &mdash; inverse &mdash; hidden &mdash; strikethrough*

<sup>* <em>Not widely supported</em></sup>


## Benchmarks

> Using Node v10.13.0

### Load time

```
chalk       :: 14.543ms
kleur       ::  0.474ms
ansi-colors ::  1.923ms
```

### Performance

```
# All Colors
  ansi-colors  x 199,381 ops/sec ±1.04% (96 runs sampled)
  chalk        x  12,107 ops/sec ±2.07% (87 runs sampled)
  kleur        x 715,334 ops/sec ±0.30% (93 runs sampled)

# Stacked colors
  ansi-colors  x 24,494 ops/sec ±1.03% (93 runs sampled)
  chalk        x  2,650 ops/sec ±2.06% (85 runs sampled)
  kleur        x 75,798 ops/sec ±0.19% (97 runs sampled)

# Nested colors
  ansi-colors  x  77,766 ops/sec ±0.32% (94 runs sampled)
  chalk        x   5,596 ops/sec ±1.85% (86 runs sampled)
  kleur        x 137,660 ops/sec ±0.31% (93 runs sampled)
```


## Credits

This project originally forked [Brian Woodward](https://github.com/doowb)'s awesome [`ansi-colors`](https://github.com/doowb/ansi-colors) library.

Beginning with `kleur@3.0`, the Chalk-style syntax (magical getter) has been replaced with function calls per key:

```js
// Old:
c.red.bold.underline('old');

// New:
c.red().bold().underline('new');
```
> <sup><em>As I work more with Rust, the newer syntax feels so much better & more natural!</em></sup>

If you prefer the old syntax, you may migrate to `ansi-colors`. Versions below `kleur@3.0` have been deprecated.


## License

MIT © [Luke Edwards](https://lukeed.com)


---

# latest-version

> Get the latest version of an npm package

Fetches the version directly from the registry instead of depending on the massive [npm](https://github.com/npm/npm/blob/8b5e7b6ae5b4cd2d7d62eaf93b1428638b387072/package.json#L37-L85) module like the [latest](https://github.com/bahamas10/node-latest) module does.

## Install

```sh
npm install latest-version
```

## Usage

```js
import latestVersion from 'latest-version';

console.log(await latestVersion('ava'));
//=> '0.18.0'

console.log(await latestVersion('@sindresorhus/df'));
//=> '1.0.1'

// Also works with semver ranges and dist-tags
console.log(await latestVersion('npm', {version: 'latest-5'}));
//=> '5.5.1'
```

## Related

- [latest-version-cli](https://github.com/sindresorhus/latest-version-cli) - CLI for this module
- [package-json](https://github.com/sindresorhus/package-json) - Get the package.json of a package from the npm registry

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-latest-version?utm_source=npm-latest-version&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

# leven [![Build Status](https://travis-ci.org/sindresorhus/leven.svg?branch=master)](https://travis-ci.org/sindresorhus/leven)

> Measure the difference between two strings<br>
> One of the fastest JS implementations of the [Levenshtein distance](https://en.wikipedia.org/wiki/Levenshtein_distance) algorithm


## Install

```
$ npm install leven
```


## Usage

```js
const leven = require('leven');

leven('cat', 'cow');
//=> 2
```


## Benchmark

```
$ npm run bench
```

```
         165,926 op/s » leven
         164,398 op/s » talisman
           1,044 op/s » levenshtein-edit-distance
             628 op/s » fast-levenshtein
             497 op/s » levenshtein-component
             195 op/s » ld
             190 op/s » levenshtein
             168 op/s » levdist
              10 op/s » natural
```


## Related

- [leven-cli](https://github.com/sindresorhus/leven-cli) - CLI for this module


## License

MIT © [Sindre Sorhus](https://sindresorhus.com)


---

# Lilconfig ⚙️
[![npm version](https://badge.fury.io/js/lilconfig.svg)](https://badge.fury.io/js/lilconfig)
[![install size](https://packagephobia.now.sh/badge?p=lilconfig)](https://packagephobia.now.sh/result?p=lilconfig)
[![Coverage Status](https://coveralls.io/repos/github/antonk52/lilconfig/badge.svg)](https://coveralls.io/github/antonk52/lilconfig)

A zero-dependency alternative to [cosmiconfig](https://www.npmjs.com/package/cosmiconfig) with the same API.

## Installation

```sh
npm install lilconfig
```

## Usage

```js
import {lilconfig, lilconfigSync} from 'lilconfig';

// all keys are optional
const options = {
    stopDir: '/Users/you/some/dir',
    searchPlaces: ['package.json', 'myapp.conf.js'],
    ignoreEmptySearchPlaces: false
}

lilconfig(
    'myapp',
    options // optional
).search() // Promise<LilconfigResult>

lilconfigSync(
    'myapp',
    options // optional
).load(pathToConfig) // LilconfigResult

/**
 * LilconfigResult
 * {
 *   config: any; // your config
 *   filepath: string;
 * }
 */
```

## ESM

ESM configs can be loaded with **async API only**. Specifically `js` files in projects with `"type": "module"` in `package.json` or `mjs` files.

## Difference to `cosmiconfig`
Lilconfig does not intend to be 100% compatible with `cosmiconfig` but tries to mimic it where possible. The key difference is **no** support for yaml files out of the box(`lilconfig` attempts to parse files with no extension as JSON instead of YAML). You can still add the support for YAML files by providing a loader, see an [example](#yaml-loader) below.

### Options difference between the two.

|cosmiconfig option      | lilconfig |
|------------------------|-----------|
|cache                   | ✅        |
|loaders                 | ✅        |
|ignoreEmptySearchPlaces | ✅        |
|packageProp             | ✅        |
|searchPlaces            | ✅        |
|stopDir                 | ✅        |
|transform               | ✅        |

## Loaders examples

### Yaml loader

If you need the YAML support you can provide your own loader

```js
import {lilconfig} from 'lilconfig';
import yaml from 'yaml';

function loadYaml(filepath, content) {
    return yaml.parse(content);
}

const options = {
    loaders: {
        '.yaml': loadYaml,
        '.yml': loadYaml,
        // loader for files with no extension
        noExt: loadYaml
    }
};

lilconfig('myapp', options)
    .search()
    .then(result => {
        result // {config, filepath}
    });
```

## Version correlation

- lilconig v1 → cosmiconfig v6
- lilconig v2 → cosmiconfig v7
- lilconig v3 → cosmiconfig v8


---

# lines-and-columns

Maps lines and columns to character offsets and back. This is useful for parsers
and other text processors that deal in character ranges but process text with
meaningful lines and columns.

## Install

```
$ npm install [--save] lines-and-columns
```

## Usage

```js
import { LinesAndColumns } from 'lines-and-columns'

const lines = new LinesAndColumns(
  `table {
  border: 0
}`
)

lines.locationForIndex(9)
// { line: 1, column: 1 }

lines.indexForLocation({ line: 1, column: 2 })
// 10
```

## License

MIT


---

# loader-runner

``` js
import { runLoaders } from "loader-runner";

runLoaders({
	resource: "/abs/path/to/file.txt?query",
	// String: Absolute path to the resource (optionally including query string)

	loaders: ["/abs/path/to/loader.js?query"],
	// String[]: Absolute paths to the loaders (optionally including query string)
	// {loader, options}[]: Absolute paths to the loaders with options object

	context: { minimize: true },
	// Additional loader context which is used as base context

	processResource: (loaderContext, resourcePath, callback) => { ... },
	// Optional: A function to process the resource
	// Must have signature function(context, path, function(err, buffer))
	// By default readResource is used and the resource is added a fileDependency

	readResource: fs.readFile.bind(fs)
	// Optional: A function to read the resource
	// Only used when 'processResource' is not provided
	// Must have signature function(path, function(err, buffer))
	// By default fs.readFile is used
}, function(err, result) {
	// err: Error?

	// result.result: Buffer | String
	// The result
	// only available when no error occured

	// result.resourceBuffer: Buffer
	// The raw resource as Buffer (useful for SourceMaps)
	// only available when no error occured

	// result.cacheable: Bool
	// Is the result cacheable or do it require reexecution?

	// result.fileDependencies: String[]
	// An array of paths (existing files) on which the result depends on

	// result.missingDependencies: String[]
	// An array of paths (not existing files) on which the result depends on

	// result.contextDependencies: String[]
	// An array of paths (directories) on which the result depends on
})
```

More documentation following...



---

# loader-utils

## Methods

### `getOptions`

Recommended way to retrieve the options of a loader invocation:

```javascript
// inside your loader
const options = loaderUtils.getOptions(this);
```

1. If `this.query` is a string:
	- Tries to parse the query string and returns a new object
	- Throws if it's not a valid query string
2. If `this.query` is object-like, it just returns `this.query`
3. In any other case, it just returns `null`

**Please note:** The returned `options` object is *read-only*. It may be re-used across multiple invocations.
If you pass it on to another library, make sure to make a *deep copy* of it:

```javascript
const options = Object.assign(
	{},
	defaultOptions,
	loaderUtils.getOptions(this) // it is safe to pass null to Object.assign()
);
// don't forget nested objects or arrays
options.obj = Object.assign({}, options.obj); 
options.arr = options.arr.slice();
someLibrary(options);
```

[clone](https://www.npmjs.com/package/clone) is a good library to make a deep copy of the options.

#### Options as query strings

If the loader options have been passed as loader query string (`loader?some&params`), the string is parsed by using [`parseQuery`](#parsequery).

### `parseQuery`

Parses a passed string (e.g. `loaderContext.resourceQuery`) as a query string, and returns an object.

``` javascript
const params = loaderUtils.parseQuery(this.resourceQuery); // resource: `file?param1=foo`
if (params.param1 === "foo") {
	// do something
}
```

The string is parsed like this:

``` text
                             -> Error
?                            -> {}
?flag                        -> { flag: true }
?+flag                       -> { flag: true }
?-flag                       -> { flag: false }
?xyz=test                    -> { xyz: "test" }
?xyz=1                       -> { xyz: "1" } // numbers are NOT parsed
?xyz[]=a                     -> { xyz: ["a"] }
?flag1&flag2                 -> { flag1: true, flag2: true }
?+flag1,-flag2               -> { flag1: true, flag2: false }
?xyz[]=a,xyz[]=b             -> { xyz: ["a", "b"] }
?a%2C%26b=c%2C%26d           -> { "a,&b": "c,&d" }
?{data:{a:1},isJSON5:true}   -> { data: { a: 1 }, isJSON5: true }
```

### `stringifyRequest`

Turns a request into a string that can be used inside `require()` or `import` while avoiding absolute paths.
Use it instead of `JSON.stringify(...)` if you're generating code inside a loader.

**Why is this necessary?** Since webpack calculates the hash before module paths are translated into module ids, we must avoid absolute paths to ensure
consistent hashes across different compilations.

This function:

- resolves absolute requests into relative requests if the request and the module are on the same hard drive
- replaces `\` with `/` if the request and the module are on the same hard drive
- won't change the path at all if the request and the module are on different hard drives
- applies `JSON.stringify` to the result

```javascript
loaderUtils.stringifyRequest(this, "./test.js");
// "\"./test.js\""

loaderUtils.stringifyRequest(this, ".\\test.js");
// "\"./test.js\""

loaderUtils.stringifyRequest(this, "test");
// "\"test\""

loaderUtils.stringifyRequest(this, "test/lib/index.js");
// "\"test/lib/index.js\""

loaderUtils.stringifyRequest(this, "otherLoader?andConfig!test?someConfig");
// "\"otherLoader?andConfig!test?someConfig\""

loaderUtils.stringifyRequest(this, require.resolve("test"));
// "\"../node_modules/some-loader/lib/test.js\""

loaderUtils.stringifyRequest(this, "C:\\module\\test.js");
// "\"../../test.js\"" (on Windows, in case the module and the request are on the same drive)

loaderUtils.stringifyRequest(this, "C:\\module\\test.js");
// "\"C:\\module\\test.js\"" (on Windows, in case the module and the request are on different drives)

loaderUtils.stringifyRequest(this, "\\\\network-drive\\test.js");
// "\"\\\\network-drive\\\\test.js\"" (on Windows, in case the module and the request are on different drives)
```

### `urlToRequest`

Converts some resource URL to a webpack module request.

> i Before call `urlToRequest` you need call `isUrlRequest` to ensure it is requestable url

```javascript
const url = "path/to/module.js";

if (loaderUtils.isUrlRequest(url)) {
  // Logic for requestable url
  const request = loaderUtils.urlToRequest(url);
} else {
  // Logic for not requestable url
}
```

Simple example:

```javascript
const url = "path/to/module.js";
const request = loaderUtils.urlToRequest(url); // "./path/to/module.js"
```

#### Module URLs

Any URL containing a `~` will be interpreted as a module request. Anything after the `~` will be considered the request path.

```javascript
const url = "~path/to/module.js";
const request = loaderUtils.urlToRequest(url); // "path/to/module.js"
```

#### Root-relative URLs

URLs that are root-relative (start with `/`) can be resolved relative to some arbitrary path by using the `root` parameter:

```javascript
const url = "/path/to/module.js";
const root = "./root";
const request = loaderUtils.urlToRequest(url, root); // "./root/path/to/module.js"
```

To convert a root-relative URL into a module URL, specify a `root` value that starts with `~`:

```javascript
const url = "/path/to/module.js";
const root = "~";
const request = loaderUtils.urlToRequest(url, root); // "path/to/module.js"
```

### `interpolateName`

Interpolates a filename template using multiple placeholders and/or a regular expression.
The template and regular expression are set as query params called `name` and `regExp` on the current loader's context.

```javascript
const interpolatedName = loaderUtils.interpolateName(loaderContext, name, options);
```

The following tokens are replaced in the `name` parameter:

* `[ext]` the extension of the resource
* `[name]` the basename of the resource
* `[path]` the path of the resource relative to the `context` query parameter or option.
* `[folder]` the folder the resource is in
* `[query]` the queryof the resource, i.e. `?foo=bar`
* `[emoji]` a random emoji representation of `options.content`
* `[emoji:<length>]` same as above, but with a customizable number of emojis
* `[contenthash]` the hash of `options.content` (Buffer) (by default it's the hex digest of the md4 hash)
* `[<hashType>:contenthash:<digestType>:<length>]` optionally one can configure
  * other `hashType`s, i. e. `sha1`, `md4`, `md5`, `sha256`, `sha512`
  * other `digestType`s, i. e. `hex`, `base26`, `base32`, `base36`, `base49`, `base52`, `base58`, `base62`, `base64`
  * and `length` the length in chars
* `[hash]` the hash of `options.content` (Buffer) (by default it's the hex digest of the md4 hash)
* `[<hashType>:hash:<digestType>:<length>]` optionally one can configure
  * other `hashType`s, i. e. `sha1`, `md4`, `md5`, `sha256`, `sha512`
  * other `digestType`s, i. e. `hex`, `base26`, `base32`, `base36`, `base49`, `base52`, `base58`, `base62`, `base64`
  * and `length` the length in chars
* `[N]` the N-th match obtained from matching the current file name against `options.regExp`

In loader context `[hash]` and `[contenthash]` are the same, but we recommend using `[contenthash]` for avoid misleading.

Examples

``` javascript
// loaderContext.resourcePath = "/absolute/path/to/app/js/javascript.js"
loaderUtils.interpolateName(loaderContext, "js/[hash].script.[ext]", { content: ... });
// => js/9473fdd0d880a43c21b7778d34872157.script.js

// loaderContext.resourcePath = "/absolute/path/to/app/js/javascript.js"
// loaderContext.resourceQuery = "?foo=bar"
loaderUtils.interpolateName(loaderContext, "js/[hash].script.[ext][query]", { content: ... });
// => js/9473fdd0d880a43c21b7778d34872157.script.js?foo=bar

// loaderContext.resourcePath = "/absolute/path/to/app/js/javascript.js"
loaderUtils.interpolateName(loaderContext, "js/[contenthash].script.[ext]", { content: ... });
// => js/9473fdd0d880a43c21b7778d34872157.script.js

// loaderContext.resourcePath = "/absolute/path/to/app/page.html"
loaderUtils.interpolateName(loaderContext, "html-[hash:6].html", { content: ... });
// => html-9473fd.html

// loaderContext.resourcePath = "/absolute/path/to/app/flash.txt"
loaderUtils.interpolateName(loaderContext, "[hash]", { content: ... });
// => c31e9820c001c9c4a86bce33ce43b679

// loaderContext.resourcePath = "/absolute/path/to/app/img/image.gif"
loaderUtils.interpolateName(loaderContext, "[emoji]", { content: ... });
// => 👍

// loaderContext.resourcePath = "/absolute/path/to/app/img/image.gif"
loaderUtils.interpolateName(loaderContext, "[emoji:4]", { content: ... });
// => 🙍🏢📤🐝

// loaderContext.resourcePath = "/absolute/path/to/app/img/image.png"
loaderUtils.interpolateName(loaderContext, "[sha512:hash:base64:7].[ext]", { content: ... });
// => 2BKDTjl.png
// use sha512 hash instead of md4 and with only 7 chars of base64

// loaderContext.resourcePath = "/absolute/path/to/app/img/myself.png"
// loaderContext.query.name =
loaderUtils.interpolateName(loaderContext, "picture.png");
// => picture.png

// loaderContext.resourcePath = "/absolute/path/to/app/dir/file.png"
loaderUtils.interpolateName(loaderContext, "[path][name].[ext]?[hash]", { content: ... });
// => /app/dir/file.png?9473fdd0d880a43c21b7778d34872157

// loaderContext.resourcePath = "/absolute/path/to/app/js/page-home.js"
loaderUtils.interpolateName(loaderContext, "script-[1].[ext]", { regExp: "page-(.*)\\.js", content: ... });
// => script-home.js

// loaderContext.resourcePath = "/absolute/path/to/app/js/javascript.js"
// loaderContext.resourceQuery = "?foo=bar"
loaderUtils.interpolateName(
  loaderContext, 
  (resourcePath, resourceQuery) => { 
    // resourcePath - `/app/js/javascript.js`
    // resourceQuery - `?foo=bar`

    return "js/[hash].script.[ext]"; 
  }, 
  { content: ... }
);
// => js/9473fdd0d880a43c21b7778d34872157.script.js
```

### `getHashDigest`

``` javascript
const digestString = loaderUtils.getHashDigest(buffer, hashType, digestType, maxLength);
```

* `buffer` the content that should be hashed
* `hashType` one of `sha1`, `md4`, `md5`, `sha256`, `sha512` or any other node.js supported hash type
* `digestType` one of `hex`, `base26`, `base32`, `base36`, `base49`, `base52`, `base58`, `base62`, `base64`
* `maxLength` the maximum length in chars

## License

MIT (http://www.opensource.org/licenses/mit-license.php)


---

# locate-path

> Get the first path that exists on disk of multiple paths

## Install

```
$ npm install locate-path
```

## Usage

Here we find the first file that exists on disk, in array order.

```js
import {locatePath} from 'locate-path';

const files = [
	'unicorn.png',
	'rainbow.png', // Only this one actually exists on disk
	'pony.png'
];

console(await locatePath(files));
//=> 'rainbow'
```

## API

### locatePath(paths, options?)

Returns a `Promise<string>` for the first path that exists or `undefined` if none exists.

#### paths

Type: `Iterable<string>`

The paths to check.

#### options

Type: `object`

##### concurrency

Type: `number`\
Default: `Infinity`\
Minimum: `1`

The number of concurrently pending promises.

##### preserveOrder

Type: `boolean`\
Default: `true`

Preserve `paths` order when searching.

Disable this to improve performance if you don't care about the order.

##### cwd

Type: `URL | string`\
Default: `process.cwd()`

The current working directory.

##### type

Type: `string`\
Default: `'file'`\
Values: `'file' | 'directory'`

The type of paths that can match.

##### allowSymlinks

Type: `boolean`\
Default: `true`

Allow symbolic links to match if they point to the chosen path type.

### locatePathSync(paths, options?)

Returns the first path that exists or `undefined` if none exists.

#### paths

Type: `Iterable<string>`

The paths to check.

#### options

Type: `object`

##### cwd

Same as above.

##### type

Same as above.

##### allowSymlinks

Same as above.

## Related

- [path-exists](https://github.com/sindresorhus/path-exists) - Check if a path exists

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-locate-path?utm_source=npm-locate-path&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

# lodash v4.17.21

The [Lodash](https://lodash.com/) library exported as [Node.js](https://nodejs.org/) modules.

## Installation

Using npm:
```shell
$ npm i -g npm
$ npm i --save lodash
```

In Node.js:
```js
// Load the full build.
var _ = require('lodash');
// Load the core build.
var _ = require('lodash/core');
// Load the FP build for immutable auto-curried iteratee-first data-last methods.
var fp = require('lodash/fp');

// Load method categories.
var array = require('lodash/array');
var object = require('lodash/fp/object');

// Cherry-pick methods for smaller browserify/rollup/webpack bundles.
var at = require('lodash/at');
var curryN = require('lodash/fp/curryN');
```

See the [package source](https://github.com/lodash/lodash/tree/4.17.21-npm) for more details.

**Note:**<br>
Install [n_](https://www.npmjs.com/package/n_) for Lodash use in the Node.js < 6 REPL.

## Support

Tested in Chrome 74-75, Firefox 66-67, IE 11, Edge 18, Safari 11-12, & Node.js 8-12.<br>
Automated [browser](https://saucelabs.com/u/lodash) & [CI](https://travis-ci.org/lodash/lodash/) test runs are available.


---

npm run build
npm run doc
npm i
git clone --depth=10 --branch=master git@github.com:lodash-archive/lodash-cli.git ./node_modules/lodash-cli
mkdir -p ./node_modules/lodash-cli/node_modules/lodash; cd $_; cp ../../../../lodash.js ./lodash.js; cp ../../../../package.json ./package.json
cd ../../; npm i --production; cd ../../
node ./node_modules/lodash-cli/bin/lodash core exports=node -o ./npm-package/core.js
node ./node_modules/lodash-cli/bin/lodash modularize exports=node -o ./npm-package
cp lodash.js npm-package/lodash.js
cp dist/lodash.min.js npm-package/lodash.min.js
cp LICENSE npm-package/LICENSE

1. Clone two repos
Bump lodash version in package.json, readme, package=locak, lodash.js
npm run build
npm run doc

2. update mappings in ldoash-cli
3. copy ldoash into lodash-cli node modules and package json.

node ./node_modules/lodash-cli/bin/lodash core exports=node -o ./npm-package/core.js
node ./node_modules/lodash-cli/bin/lodash modularize exports=node -o ./npm-package



1. Clone the two repositories:
```sh
$ git clone https://github.com/lodash/lodash.git
$ git clone https://github.com/bnjmnt4n/lodash-cli.git
```
2. Update lodash-cli to accomdate changes in lodash source. This can typically involve adding new function dependency mappings in lib/mappings.js. Sometimes, additional changes might be needed for more involved functions.
3. In the lodash repository, update references to the lodash version in README.md, lodash.js, package.jsona nd package-lock.json
4. Run:
```sh
npm run build
npm run doc
node ../lodash-cli/bin/lodash core -o ./dist/lodash.core.js
```
5. Add a commit and tag the release
mkdir ../lodash-temp
cp lodash.js dist/lodash.min.js dist/lodash.core.js dist/lodash.core.min.js ../lodash-temp/
node ../lodash-cli/bin/lodash modularize exports=node -o .
cp ../lodash-temp/lodash.core.js core.js
cp ../lodash-temp/lodash.core.min.js core.min.js
cp ../lodash-temp/lodash.js lodash.js
cp ../lodash-temp/lodash.min.js lodash.min.js

❯ node ../lodash-cli/bin/lodash modularize exports=es -o .


---

# lodash.debounce v4.0.8

The [lodash](https://lodash.com/) method `_.debounce` exported as a [Node.js](https://nodejs.org/) module.

## Installation

Using npm:
```bash
$ {sudo -H} npm i -g npm
$ npm i --save lodash.debounce
```

In Node.js:
```js
var debounce = require('lodash.debounce');
```

See the [documentation](https://lodash.com/docs#debounce) or [package source](https://github.com/lodash/lodash/blob/4.0.8-npm-packages/lodash.debounce) for more details.


---

# lodash.memoize v4.1.2

The [lodash](https://lodash.com/) method `_.memoize` exported as a [Node.js](https://nodejs.org/) module.

## Installation

Using npm:
```bash
$ {sudo -H} npm i -g npm
$ npm i --save lodash.memoize
```

In Node.js:
```js
var memoize = require('lodash.memoize');
```

See the [documentation](https://lodash.com/docs#memoize) or [package source](https://github.com/lodash/lodash/blob/4.1.2-npm-packages/lodash.memoize) for more details.


---

# lodash.uniq v4.5.0

The [lodash](https://lodash.com/) method `_.uniq` exported as a [Node.js](https://nodejs.org/) module.

## Installation

Using npm:
```bash
$ {sudo -H} npm i -g npm
$ npm i --save lodash.uniq
```

In Node.js:
```js
var uniq = require('lodash.uniq');
```

See the [documentation](https://lodash.com/docs#uniq) or [package source](https://github.com/lodash/lodash/blob/4.5.0-npm-packages/lodash.uniq) for more details.


---

Filing tickets against loglevel
===============================

If you'd like to file a bug or a feature request for loglevel, the best option is to [open an issue on Github](https://github.com/pimterry/loglevel/issues/new).

If you're filing a feature request, please remember:

* Feature requests significantly expanding the scope of loglevel outside the description in [the readme](https://github.com/pimterry/loglevel/blob/master/README.md) will probably be rejected.
* Features that can't be meaningfully implemented in a cross-environment compatible manner won't be implemented.
* Please check the previously opened issues to see if somebody else has suggested it first.
* Consider submitting a pull request to add the feature instead, if you're confident it fits within the above.

If you're filing a bug, please remember:

* To provide detailed steps to reproduce the behaviour.
* If possible, provide a Jasmine test which reproduces the behaviour.
* Please specify the exact details of the environment in which it fails: OS + Environment (i.e. Browser or Node) + version.
* Consider submitting a pull request to fix the bug instead.

Helping develop loglevel
================================

If you'd like to help develop loglevel further, please submit a pull request! I'm very keen to improve loglevel further, and good pull requests will be enthusiastically merged.

Before submitting a pull request to fix a bug or add a new feature, please check the lists above to ensure it'll be accepted. Browser compatibility is particularly important here; if you add a feature or fix a bug which breaks things on other browsers it will not be merged, no matter how awesome it may be.

To be more specific, before submitting your pull request please ensure:

* You haven't broken the existing test suite in any obvious browsers (at least check latest IE/FF/Chrome).
* You've added relevant tests for the bug you're fixing/the new feature you're adding/etc, which pass in all the relevant browsers.
* JSHint is happy with your new code.
* You've updated the API docs (in `README.md`) to detail any changes you've made to the public interface.
* Your change is backward-compatible (or you've explicitly said that it's not; this isn't great, but will be considered).
* You haven't changed any files in `dist/` (these are auto-generated, and should only be changed on release).

Compatibility and JavaScript Runtimes
-------------------------------------

loglevel aims to stay compatible with browsers, Node.js versions, and other JS runtimes that may be fairly old at this point! Please take care to match existing conventions and JavaScript language features wherever possible. For example, loglevel uses `var` instead of the newer `let` and `const` keywords to define variables, uses old-style `for` loops instead of the newer `for...of` loop, and so on.

That said, loglevel's *test and development tools* utilize newer JavaScript and Node.js features. To run most tests or build releases, you will need a newer version of Node.js than is required at runtime (see details below in ["how to make your change…"](#how-to-make-your-change-and-submit-it)). Using newer features or making breaking changes to the *dev tools* is OK.

Project structure
-----------------

The core project code is all in [`lib/loglevel.js`](./lib/loglevel.js), and this should be the only file you need to touch for functional changes themselves.

The released code is in `dist/*.js`, and should not be touched by anything except releases (pull requests should *not* update these files).

The test suite is entirely in `test/*.js`:

* Every file ending in `-test.js` is a unit test, is written in RequireJS, and should pass in any environment.
* `global-integration.js` and `node-integration.js` are quick integration smoke tests for node and for browser global usage.
* `test-helpers.js` contains some test utilities.
* `manual-test.html` is a test page which includes the current loglevel build, so you can manually check that it works in a given browser.

How to make your change and submit it
-------------------------------------

1. Ensure you have Node.js v14 or later (some tests can run on earlier versions, but the full suite requires this version).
2. Fork loglevel.
3. Clone your fork locally.
4. Create a branch from `master` for your change.
5. Write some tests in `test/` for your change, as relevant.
6. Make your code changes in `lib/loglevel.js`.
7. Check your code all passes (run `npm test`). If you have issues and need to debug the tests, see the details on ["running tests"](#running-tests) below.
8. Commit your changes.
9. Open a pull request back to `master` in loglevel.

Running Tests
-------------

There are several types of tests and test tools that loglevel uses to verify different types of support in different environments. When you run `npm test`, *all* of these tests are run automatically. However, you may want to run individual types of tests during development, or run some tests manually to debug them.

Test commands (see `"scripts"` in `package.json` for a complete list of tools):
- `npm test` — Runs all the below tests.
- `npm run test-browser` — Runs detailed tests in a headless browser. There are actually 3 sub-groups here:
    - `npx grunt jasmine:global` — Tests general usage of the global `log` variable.
    - `npx grunt test-browser-context` — Tests usage when loglevel is injected into an anonymous function instead of included as a regular script on the page.
    - `npx grunt jasmine:requirejs` — Tests the main test suite via Jasmine & RequireJS.
- `npm run test-node` — Runs tests that check loglevel in Node.js.
- `npm run test-types` — Runs tests of the TypeScript type definitions for loglevel.

Alternatively, you might want to run tests manually in your browser in order to use debugging tools to step through the code:
1. Run `npx grunt integration-test` to start a test server on port `8000`.
2. Your default browser should open the tests automatically, but if not, open `http://127.0.0.1:8000/_SpecRunner.html` in any browser.
3. Open your browser's dev tools and place breakpoints where you'd like to debug a test.
4. Reload the page to re-run the tests and pause on breakpoints.

You can also open a blank webpage with loglevel pre-loaded to experiment in your browser's console:
1. Run `npx grunt integration-test` to start a test server on port `8000`.
2. In whatever browser you want to test, open `http://127.0.0.1:8000/test/manual-test.html`.
3. Play around with the global `log` object in the browser's dev console.

Reporting security issues
-------------------------

Tidelift acts as the security contact for loglevel. Issues can be reported to security@tidelift.com, see https://tidelift.com/security for more details.


---


# loglevel [![NPM version][npm-image]][npm-url] [![NPM downloads](https://img.shields.io/npm/dw/loglevel.svg)](https://www.npmjs.com/package/loglevel) [![Build Status](https://github.com/pimterry/loglevel/actions/workflows/ci.yml/badge.svg)](https://github.com/pimterry/loglevel/actions/workflows/ci.yml)

[npm-image]: https://img.shields.io/npm/v/loglevel.svg?style=flat
[npm-url]: https://npmjs.org/package/loglevel

> _Don't debug with logs alone - check out [HTTP Toolkit](https://httptoolkit.tech/javascript): beautiful, powerful & open-source tools for building, testing & debugging HTTP(S)_

Minimal lightweight simple logging for JavaScript (browsers, node.js or elsewhere). loglevel extends `console.log()` & friends with level-based logging and filtering, with none of console's downsides.

Test it out live in your browser console at https://pimterry.github.io/loglevel/demo/index.html

Loglevel is a barebones reliable everyday logging library. It does not do fancy things, it does not let you reconfigure appenders or add complex log filtering rules or boil tea (more's the pity), but it does have the all core functionality that you actually use:

## Features

### Simple

* Log things at a given level (trace/debug/info/warn/error) to the `console` object (as seen in all modern browsers & node.js).
* Filter logging by level (all the above or 'silent'), so you can disable all but error logging in production, and then run `log.setLevel("trace")` in your console to turn it all back on for a furious debugging session.
* Single file, no dependencies, weighs in at 1.4 KB minified and gzipped.

### Effective

* Log methods gracefully fall back to simpler console logging methods if more specific ones aren't available: so calls to `log.debug()` go to `console.debug()` if possible, or `console.log()` if not.
* Logging calls still succeed even if there's no `console` object at all, so your site doesn't break when people visit with old browsers that don't support the `console` object (here's looking at you, IE) and similar.
* This then comes together giving a consistent reliable API that works in every JavaScript environment with a console available, and never breaks anything anywhere else.

### Convenient

* Log output keeps line numbers: most JS logging frameworks call `console.log` methods through wrapper functions, clobbering your stacktrace and making the extra info many browsers provide useless. We'll have none of that thanks.
* It works with all the standard JavaScript loading systems out of the box (CommonJS, AMD, or just as a global).
* Logging is filtered to "warn" level by default, to keep your live site clean in normal usage (or you can trivially re-enable everything with an initial `log.enableAll()` call).
* Magically handles situations where console logging is not initially available (IE8/9), and automatically enables logging as soon as it does become available (when developer console is opened).
* TypeScript type definitions included, so no need for extra `@types` packages.
* Extensible, to add other log redirection, filtering, or formatting functionality, while keeping all the above (except you will clobber your stacktrace, see [“Plugins”](#plugins) below).

## Downloading loglevel

If you're using NPM, you can just run `npm install loglevel`.

Alternatively, loglevel is also available via [Bower](https://github.com/bower/bower) (`bower install loglevel`), as a [Webjar](http://www.webjars.org/), or an [Atmosphere package](https://atmospherejs.com/spacejamio/loglevel) (for Meteor)

Alternatively if you just want to grab the file yourself, you can download either the current stable [production version][min] or the [development version][max] directly, or reference it remotely on unpkg at [`https://unpkg.com/loglevel/dist/loglevel.min.js`][cdn] (this will redirect to a latest version, use the resulting redirected URL if you want to pin that version).

Finally, if you want to tweak loglevel to your own needs or you immediately need the cutting-edge version, clone this repo and see [Developing & Contributing](#developing--contributing) below for build instructions.

[min]: https://raw.github.com/pimterry/loglevel/master/dist/loglevel.min.js
[max]: https://raw.github.com/pimterry/loglevel/master/dist/loglevel.js
[cdn]: https://unpkg.com/loglevel/dist/loglevel.min.js

## Setting it up

loglevel supports AMD (e.g. RequireJS), CommonJS (e.g. Node.js) and direct usage (e.g. loading globally with a `<script>` tag) loading methods. You should be able to do nearly anything, and then skip to the next section anyway and have it work. Just in case, though, here's some specific examples that definitely do the right thing:

### CommonsJS (e.g. Node)

```javascript
var log = require('loglevel');
log.warn("unreasonably simple");
```

### AMD (e.g. RequireJS)

```javascript
define(['loglevel'], function(log) {
   log.warn("dangerously convenient");
});
```

### Directly in your web page

```html
<script src="loglevel.min.js"></script>
<script>
log.warn("too easy");
</script>
```

### As an ES6 module

loglevel is written as a UMD module, with a single object exported. Unfortunately, ES6 module loaders & transpilers don't all handle this the same way. Some will treat the object as the default export, while others use it as the root exported object. In addition, loglevel includes a `default` property on the root object, designed to help handle this difference. Nonetheless, there are two possible syntaxes that might work for you:

For most tools, using the default import is the most convenient and flexible option:

```javascript
import log from 'loglevel';
log.warn("module-tastic");
```

For some tools though, it might better to wildcard import the whole object:

```javascript
import * as log from 'loglevel';
log.warn("module-tastic");
```

There's no major difference, unless you're using TypeScript & building a loglevel plugin (in that case, see <https://github.com/pimterry/loglevel/issues/149>). In general though, just use whichever suits your environment, and everything should work out fine.

### With noConflict()

If you're using another JavaScript library that exposes a `log` global, you can run into conflicts with loglevel. Similarly to jQuery, you can solve this by putting loglevel into no-conflict mode immediately after it is loaded onto the page. This resets the `log` global to its value before loglevel was loaded (typically `undefined`), and returns the loglevel object, which you can then bind to another name yourself.

For example:

```html
<script src="loglevel.min.js"></script>
<script>
var logging = log.noConflict();

logging.warn("still pretty easy");
</script>
```

### TypeScript

loglevel includes its own type definitions, assuming you're using a modern module environment (e.g. Node.JS, webpack, etc), you should be able to use the ES6 syntax above, and everything will work immediately. If not, file a bug!

If you really want to use LogLevel as a global however, but from TypeScript, you'll need to declare it as such first. To do that:

* Create a `loglevel.d.ts` file
* Ensure that file is included in your build (e.g. add it to `include` in your tsconfig, pass it on the command line, or use `///<reference path="./loglevel.d.ts" />`)
* In that file, add:

  ```typescript
  import * as log from 'loglevel';
  export as namespace log;
  export = log;
  ```

## Documentation

### Methods

The loglevel API is extremely minimal. All methods are available on the root loglevel object, which we suggest you name `log` (this is the default if you import it globally, and is what's set up in the above examples). The API consists of:

#### Logging Methods

5 actual logging methods, ordered and available as:

* `log.trace(msg)`
* `log.debug(msg)`
* `log.info(msg)`
* `log.warn(msg)`
* `log.error(msg)`

`log.log(msg)` is also available, as an alias for `log.debug(msg)`, to improve compatibility with `console`, and make migration easier.

Exact output formatting of these will depend on the console available in the current context of your application. For example, many environments will include a full stack trace with all `trace()` calls, and icons or similar to highlight other calls.

These methods should never fail in any environment, even if no `console` object is currently available, and should always fall back to an available log method even if the specific method called (e.g. `warn`) isn't available.

Be aware that this means that these methods won't always produce exactly the output you expect in every environment; loglevel only guarantees that these methods will never explode on you, and that it will call the most relevant method it can find, with your argument. For example, `log.trace(msg)` in Firefox before version 64 prints the stacktrace by itself, and doesn't include your message (see [#84](https://github.com/pimterry/loglevel/issues/84)).

#### `log.setLevel(level, [persist])`

This disables all logging below the given level, so that after a `log.setLevel("warn")` call `log.warn("something")` or `log.error("something")` will output messages, but `log.info("something")` will not.

This can take either a log level name or `'silent'` (which disables everything) in one of a few forms:

* As a log level from the internal levels list, e.g. `log.levels.SILENT` ← _for type safety_
* As a string, like `'error'` (case-insensitive) ← _for a reasonable practical balance_
* As a numeric index from `0` (trace) to `5` (silent) ← _deliciously terse, and more easily programmable (...although, why?)_

Where possible, the log level will be persisted. LocalStorage will be used if available, falling back to cookies if not. If neither is available in the current environment (e.g. in Node), or if you pass `false` as the optional 'persist' second argument, persistence will be skipped.

If `log.setLevel()` is called when a `console` object is not available (in IE 8 or 9 before the developer tools have been opened, for example) logging will remain silent until the console becomes available, and then begin logging at the requested level.

#### `log.setDefaultLevel(level)`

This sets the current log level only if one has not been persisted and can’t be loaded. This is useful when initializing modules or scripts; if a developer or user has previously called `setLevel()`, this won’t alter their settings. For example, your application might use `setDefaultLevel("error")` set the log level to `error` in a production environment, but when debugging an issue, you might call `setLevel("trace")` on the console to see all the logs. If that `error` setting was set using `setDefaultLevel()`, it will still stay as `trace` on subsequent page loads and refreshes instead of resetting to `error`.

The `level` argument takes the same values that you might pass to `setLevel()`. Levels set using `setDefaultLevel()` never persist to subsequent page loads.

#### `log.resetLevel()`

This resets the current log level to the logger's default level (if no explicit default was set, then it resets it to the root logger's level, or to `WARN`) and clears the persisted level if one was previously persisted.

#### `log.enableAll()` and `log.disableAll()`

These enable or disable all log messages, and are equivalent to `log.setLevel("trace")` and `log.setLevel("silent")`, respectively.

#### `log.getLevel()`

Returns the current logging level, as a number from `0` (trace) to `5` (silent)

It's very unlikely you'll need to use this for normal application logging; it's provided partly to help plugin development, and partly to let you optimize logging code as below, where debug data is only generated if the level is set such that it'll actually be logged. This probably doesn't affect you, unless you've run profiling on your code and you have hard numbers telling you that your log data generation is a real performance problem.

```javascript
if (log.getLevel() <= log.levels.DEBUG) {
  var logData = runExpensiveDataGeneration();
  log.debug(logData);
}
```

This notably isn't the right solution to avoid the cost of string concatenation in your logging. Firstly, it's very unlikely that string concatenation in your logging is really an important performance problem. Even if you do genuinely have hard metrics showing that it is, though, the better solution that wrapping your log statements in this is to use multiple arguments, as below. The underlying console API will automatically concatenate these for you if logging is enabled, and if it isn't then all log methods are no-ops, and no concatenation will be done at all.

```javascript
// Prints 'My concatenated log message'
log.debug("My", "concatenated", "log message");
```

#### `log.getLogger(loggerName)`

This gets you a new logger object that works exactly like the root `log` object, but can have its level and logging methods set independently. All loggers must have a name (which is a non-empty string, or a [Symbol](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol)). Calling `getLogger()` multiple times with the same name will return an identical logger object.

In large applications, it can be incredibly useful to turn logging on and off for particular modules as you are working with them. Using the `getLogger()` method lets you create a separate logger for each part of your application with its own logging level.

Likewise, for small, independent modules, using a named logger instead of the default root logger allows developers using your module to selectively turn on deep, trace-level logging when trying to debug problems, while logging only errors or silencing logging altogether under normal circumstances.

Example usage _(using CommonJS modules, but you could do the same with any module system):_

```javascript
// In module-one.js:
var log = require("loglevel").getLogger("module-one");
function doSomethingAmazing() {
  log.debug("Amazing message from module one.");
}

// In module-two.js:
var log = require("loglevel").getLogger("module-two");
function doSomethingSpecial() {
  log.debug("Special message from module two.");
}

// In your main application module:
var log = require("loglevel");
var moduleOne = require("module-one");
var moduleTwo = require("module-two");
log.getLogger("module-two").setLevel("TRACE");

moduleOne.doSomethingAmazing();
moduleTwo.doSomethingSpecial();
// logs "Special message from module two."
// (but nothing from module one.)
```

Loggers returned by `getLogger()` support all the same properties and methods as the default root logger, excepting `noConflict()` and the `getLogger()` method itself.

Like the root logger, other loggers can have their logging level saved. If a logger’s level has not been saved, it will inherit the root logger’s level when it is first created. If the root logger’s level changes later, the new level will not affect other loggers that have already been created. Loggers with Symbol names (rather than string names) will always be considered unique instances, and will never have their logging level saved or restored.

Likewise, loggers inherit the root logger’s `methodFactory`. After creation, each logger can have its `methodFactory` independently set. See the _plugins_ section below for more about `methodFactory`.

#### `log.getLoggers()`

This will return the dictionary of all loggers created with `getLogger()`, keyed by their names.

#### `log.rebuild()`

Ensure the various logging methods (`log.info()`, `log.warn()`, etc.) behave as expected given the currently set logging level and `methodFactory`. It will also rebuild all child loggers of the logger this was called on.

This is mostly useful for plugin development. When you call `log.setLevel()` or `log.setDefaultLevel()`, the logger is rebuilt automatically. However, if you change the logger’s `methodFactory`, you should use this to rebuild all the logging methods with your new factory.

It is also useful if you change the level of the root logger and want it to affect child loggers that you’ve already created (and have not called `someChildLogger.setLevel()` or `someChildLogger.setDefaultLevel()` on). For example:

```js
var childLogger1 = log.getLogger("child1");
childLogger1.getLevel();  // WARN (inherited from the root logger)

var childLogger2 = log.getLogger("child2");
childLogger2.setDefaultLevel("TRACE");
childLogger2.getLevel();  // TRACE

log.setLevel("ERROR");

// At this point, the child loggers have not changed:
childLogger1.getLevel();  // WARN
childLogger2.getLevel();  // TRACE

// To update them:
log.rebuild();
childLogger1.getLevel();  // ERROR (still inheriting from root logger)
childLogger2.getLevel();  // TRACE (no longer inheriting because `.setDefaultLevel() was called`)
```

## Plugins

### Existing plugins

[loglevel-plugin-prefix](https://github.com/kutuluk/loglevel-plugin-prefix) - plugin for loglevel message prefixing.

[loglevel-plugin-remote](https://github.com/kutuluk/loglevel-plugin-remote) - plugin for sending loglevel messages to a remote log server.

[loglevel-serverSend](https://github.com/artemyarulin/loglevel-serverSend) - Forward your log messages to a remote server.

[loglevel-debug](https://github.com/vectrlabs/loglevel-debug) - Control logging from a DEBUG environmental variable (similar to the classic [Debug](https://github.com/visionmedia/debug) module).

### Writing plugins

Loglevel provides a simple, reliable, minimal base for console logging that works everywhere. This means it doesn't include lots of fancy functionality that might be useful in some cases, such as log formatting and redirection (e.g. also sending log messages to a server over AJAX)

Including that would increase the size and complexity of the library, but more importantly would remove stacktrace information. Currently log methods are either disabled, or enabled with directly bound versions of the `console.log` methods (where possible). This means your browser shows the log message as coming from your code at the call to `log.info("message!")` not from within loglevel, since it really calls the bound console method directly, without indirection. The indirection required to dynamically format, further filter, or redirect log messages would stop this.

There's clearly enough enthusiasm for this even at that cost that loglevel now includes a plugin API. To use it, redefine `log.methodFactory(methodName, logLevel, loggerName)` with a function of your own. This will be called for each enabled method each time the level is set (including initially), and should return a function to be used for the given log method `methodName`, at the given _configured_ (not actual) level `logLevel`, for a logger with the given name `loggerName`. If you'd like to retain all the reliability and features of loglevel, we recommended that you wrap the initially provided value of `log.methodFactory`.

For example, a plugin to prefix all log messages with "Newsflash: " would look like:

```javascript
var originalFactory = log.methodFactory;
log.methodFactory = function (methodName, logLevel, loggerName) {
    var rawMethod = originalFactory(methodName, logLevel, loggerName);

    return function (message) {
        rawMethod("Newsflash: " + message);
    };
};
log.rebuild(); // Be sure to call the rebuild method in order to apply plugin.
```

*(The above supports only a single string `log.warn("...")` argument for clarity, but it's easy to extend to a [fuller variadic version](http://jsbin.com/xehoye/edit?html,console).)*

If you develop and release a plugin, please get in contact! I'd be happy to reference it here for future users. Some consistency is helpful; naming your plugin 'loglevel-PLUGINNAME' (e.g. loglevel-newsflash) is preferred, as is giving it the 'loglevel-plugin' keyword in your `package.json`.

## Developing & Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality.

Builds can be run with npm: run `npm run dist` to build a distributable version of the project (in `dist/`), or `npm test` to just run the tests and linting. During development you can run `npm run watch` and it will monitor source files, and rerun the tests and linting as appropriate when they're changed.

_Also, please don't manually edit files in the `dist/` subdirectory as they are generated via Grunt. You'll find source code in the `lib/` subdirectory!_

#### Release process

To do a release of loglevel:

* Update the version number in `package.json` and `bower.json`.
* Run `npm run dist` to build a distributable version in `dist/`.
* Update the release history in this file (below).
* Commit the built code, tagging it with the version number and a brief message about the release.
* Push to Github.
* Run `npm publish .` to publish to NPM.

## Release History

v0.1.0 - First working release with apparent compatibility with everything tested

v0.2.0 - Updated release with various tweaks and polish and real proper documentation attached

v0.3.0 - Some bugfixes ([#12](https://github.com/pimterry/loglevel/issues/12), [#14](https://github.com/pimterry/loglevel/issues/14)), cookie-based log level persistence, doc tweaks, support for Bower and JamJS

v0.3.1 - Fixed incorrect text in release build banner, various other minor tweaks

v0.4.0 - Use LocalStorage for level persistence if available, compatibility improvements for IE, improved error messages, multi-environment tests

v0.5.0 - Fix for Modernizr+IE8 issues, improved setLevel error handling, support for auto-activation of desired logging when console eventually turns up in IE8

v0.6.0 - Handle logging in Safari private browsing mode ([#33](https://github.com/pimterry/loglevel/issues/33)), fix `TRACE` level persistence bug ([#35](https://github.com/pimterry/loglevel/issues/35)), plus various minor tweaks

v1.0.0 - Official stable release! Fixed a bug with localStorage in Android webviews, improved CommonJS detection, and added `noConflict()`.

v1.1.0 - Added support for including loglevel with preprocessing and `.apply()` ([#50](https://github.com/pimterry/loglevel/issues/50)), and fixed QUnit dep version which made tests potentially unstable.

v1.2.0 - New plugin API! Plus various bits of refactoring and tidy up, nicely simplifying things and trimming the size down.

v1.3.0 - Make persistence optional in `setLevel()`, plus lots of documentation updates and other small tweaks

v1.3.1 - With the new optional persistence, stop unnecessarily persisting the initially set default level (`WARN`)

v1.4.0 - Add `getLevel()`, `setDefaultLevel()` and `getLogger()` functionality for more fine-grained log level control

v1.4.1 - Reorder UMD ([#92](https://github.com/pimterry/loglevel/issues/92)) to improve bundling tool compatibility

v1.5.0 - Fix `log.debug` ([#111](https://github.com/pimterry/loglevel/issues/111)) after V8 changes deprecating console.debug, check for `window` upfront ([#104](https://github.com/pimterry/loglevel/issues/104)), and add `.log` alias for `.debug` ([#64](https://github.com/pimterry/loglevel/issues/64))

v1.5.1 - Fix bug ([#112](https://github.com/pimterry/loglevel/issues/112)) in level-persistence cookie fallback, which failed if it wasn't the first cookie present

v1.6.0 - Add a name property to loggers and add `log.getLoggers()` ([#114](https://github.com/pimterry/loglevel/issues/114)), and recommend unpkg as CDN instead of CDNJS.

v1.6.1 - Various small documentation & test updates

v1.6.2 - Include TypeScript type definitions in the package itself

v1.6.3 - Avoid TypeScript type conflicts with other global `log` types (e.g. `core-js`)

v1.6.4 - Ensure `package.json`'s `"main"` is a fully qualified path, to fix webpack issues

v1.6.5 - Ensure the provided message is included when calling `trace()` in IE11

v1.6.6 - Fix bugs in v1.6.5, which caused issues in node.js & IE < 9

v1.6.7 - Fix a bug in environments with `window` defined but no `window.navigator`

v1.6.8 - Update TypeScript type definitions to include `log.log()`.

v1.7.0 - Add support for Symbol-named loggers, and a `.default` property to help with ES6 module usage.

v1.7.1 - Update TypeScript types to support Symbol-named loggers.

v1.8.0 - Add `resetLevel()` method to clear persisted levels & reset to defaults

v1.8.1 - Fix incorrect type definitions for `MethodFactory`

v1.9.0 - Added `rebuild()` method, overhaul dev & test setup, and fix some bugs (notably around cookies) en route

v1.9.1 - Fix a bug introduced in 1.9.0 that broke `setLevel()` in some ESM-focused runtime environments

v1.9.2 - Remove unnecessarily extra test & CI files from deployed package

## `loglevel` for enterprise

Available as part of the Tidelift Subscription.

The maintainers of `loglevel` and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-loglevel?utm_source=npm-loglevel&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)

## License

Copyright (c) 2013 Tim Perry
Licensed under the MIT license. See [`LICENSE-MIT`](./LICENSE-MIT) for full license text.


---

# longest-streak

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]

Get the count of the longest repeating streak of `substring` in `value`.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`longestStreak(value, substring)`](#longeststreakvalue-substring)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Security](#security)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This is a tiny package that finds the count of the longest adjacent repeating
substring.

## When should I use this?

This package is rather niche.
I use it for serializing markdown ASTs (particularly fenced code and math).

You can use [`ccount`][ccount] if you need the total count of substrings
occuring in a value.

## Install

This package is [ESM only][esm].
In Node.js (version 14.14+, 16.0+), install with [npm][]:

```sh
npm install longest-streak
```

In Deno with [`esm.sh`][esmsh]:

```js
import {longestStreak} from 'https://esm.sh/longest-streak@3'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {longestStreak} from 'https://esm.sh/longest-streak@3?bundle'
</script>
```

## Use

```js
import {longestStreak} from 'longest-streak'

longestStreak('` foo `` bar `', '`') // => 2
```

## API

This package exports the identifier `longestStreak`.
There is no default export.

### `longestStreak(value, substring)`

Get the count of the longest repeating streak of `substring` in `value`.

###### Parameters

*   `value` (`string`) — content to search in
*   `substring` (`string`) — substring to look for, typically one character

###### Returns

Count of most frequent adjacent `substring`s in `value` (`number`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

This package is at least compatible with all maintained versions of Node.js.
As of now, that is Node.js 14.14+ and 16.0+.
It also works in Deno and modern browsers.

## Security

This package is safe.

## Related

*   [`wooorm/ccount`](https://github.com/wooorm/ccount)
    — count the total number of `substring`s in `value`
*   [`wooorm/direction`](https://github.com/wooorm/direction)
    — detect directionality: left-to-right, right-to-left, or neutral

## Contribute

Yes please!
See [How to Contribute to Open Source][contribute].

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/wooorm/longest-streak/workflows/main/badge.svg

[build]: https://github.com/wooorm/longest-streak/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/longest-streak.svg

[coverage]: https://codecov.io/github/wooorm/longest-streak

[downloads-badge]: https://img.shields.io/npm/dm/longest-streak.svg

[downloads]: https://www.npmjs.com/package/longest-streak

[size-badge]: https://img.shields.io/bundlephobia/minzip/longest-streak.svg

[size]: https://bundlephobia.com/result?p=longest-streak

[npm]: https://docs.npmjs.com/cli/install

[esmsh]: https://esm.sh

[license]: license

[author]: https://wooorm.com

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[typescript]: https://www.typescriptlang.org

[contribute]: https://opensource.guide/how-to-contribute/

[ccount]: https://github.com/wooorm/ccount


---

# loose-envify

[![Build Status](https://travis-ci.org/zertosh/loose-envify.svg?branch=master)](https://travis-ci.org/zertosh/loose-envify)

Fast (and loose) selective `process.env` replacer using [js-tokens](https://github.com/lydell/js-tokens) instead of an AST. Works just like [envify](https://github.com/hughsk/envify) but much faster.

## Gotchas

* Doesn't handle broken syntax.
* Doesn't look inside embedded expressions in template strings.
  - **this won't work:**
  ```js
  console.log(`the current env is ${process.env.NODE_ENV}`);
  ```
* Doesn't replace oddly-spaced or oddly-commented expressions.
  - **this won't work:**
  ```js
  console.log(process./*won't*/env./*work*/NODE_ENV);
  ```

## Usage/Options

loose-envify has the exact same interface as [envify](https://github.com/hughsk/envify), including the CLI.

## Benchmark

```
envify:

  $ for i in {1..5}; do node bench/bench.js 'envify'; done
  708ms
  727ms
  791ms
  719ms
  720ms

loose-envify:

  $ for i in {1..5}; do node bench/bench.js '../'; done
  51ms
  52ms
  52ms
  52ms
  52ms
```


---

# Lower Case

[![NPM version][npm-image]][npm-url]
[![NPM downloads][downloads-image]][downloads-url]
[![Bundle size][bundlephobia-image]][bundlephobia-url]

> Transforms the string to lower case.

## Installation

```
npm install lower-case --save
```

## Usage

```js
import { lowerCase, localeLowerCase } from "lower-case";

lowerCase("string"); //=> "string"
lowerCase("PascalCase"); //=> "pascalcase"

localeLowerCase("STRING", "tr"); //=> "strıng"
```

## License

MIT

[npm-image]: https://img.shields.io/npm/v/lower-case.svg?style=flat
[npm-url]: https://npmjs.org/package/lower-case
[downloads-image]: https://img.shields.io/npm/dm/lower-case.svg?style=flat
[downloads-url]: https://npmjs.org/package/lower-case
[bundlephobia-image]: https://img.shields.io/bundlephobia/minzip/lower-case.svg
[bundlephobia-url]: https://bundlephobia.com/result?p=lower-case


---

# lowercase-keys

> Lowercase the keys of an object

Check out [`map-obj`](https://github.com/sindresorhus/map-obj) if you need support for deep iteration.

## Install

```sh
npm install lowercase-keys
```

## Usage

```js
import lowercaseKeys from 'lowercase-keys';

lowercaseKeys({FOO: true, bAr: false});
//=> {foo: true, bar: false}
```

## API

### lowercaseKeys(object)

Returns a new object with the keys lowercased.

## lowercase-keys for enterprise

Available as part of the Tidelift Subscription.

The maintainers of lowercase-keys and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-lowercase-keys?utm_source=npm-lowercase-keys&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)


---

# lru cache

A cache object that deletes the least-recently-used items.

[![Build Status](https://travis-ci.org/isaacs/node-lru-cache.svg?branch=master)](https://travis-ci.org/isaacs/node-lru-cache) [![Coverage Status](https://coveralls.io/repos/isaacs/node-lru-cache/badge.svg?service=github)](https://coveralls.io/github/isaacs/node-lru-cache)

## Installation:

```javascript
npm install lru-cache --save
```

## Usage:

```javascript
var LRU = require("lru-cache")
  , options = { max: 500
              , length: function (n, key) { return n * 2 + key.length }
              , dispose: function (key, n) { n.close() }
              , maxAge: 1000 * 60 * 60 }
  , cache = new LRU(options)
  , otherCache = new LRU(50) // sets just the max size

cache.set("key", "value")
cache.get("key") // "value"

// non-string keys ARE fully supported
// but note that it must be THE SAME object, not
// just a JSON-equivalent object.
var someObject = { a: 1 }
cache.set(someObject, 'a value')
// Object keys are not toString()-ed
cache.set('[object Object]', 'a different value')
assert.equal(cache.get(someObject), 'a value')
// A similar object with same keys/values won't work,
// because it's a different object identity
assert.equal(cache.get({ a: 1 }), undefined)

cache.reset()    // empty the cache
```

If you put more stuff in it, then items will fall out.

If you try to put an oversized thing in it, then it'll fall out right
away.

## Options

* `max` The maximum size of the cache, checked by applying the length
  function to all values in the cache.  Not setting this is kind of
  silly, since that's the whole purpose of this lib, but it defaults
  to `Infinity`.  Setting it to a non-number or negative number will
  throw a `TypeError`.  Setting it to 0 makes it be `Infinity`.
* `maxAge` Maximum age in ms.  Items are not pro-actively pruned out
  as they age, but if you try to get an item that is too old, it'll
  drop it and return undefined instead of giving it to you.
  Setting this to a negative value will make everything seem old!
  Setting it to a non-number will throw a `TypeError`.
* `length` Function that is used to calculate the length of stored
  items.  If you're storing strings or buffers, then you probably want
  to do something like `function(n, key){return n.length}`.  The default is
  `function(){return 1}`, which is fine if you want to store `max`
  like-sized things.  The item is passed as the first argument, and
  the key is passed as the second argumnet.
* `dispose` Function that is called on items when they are dropped
  from the cache.  This can be handy if you want to close file
  descriptors or do other cleanup tasks when items are no longer
  accessible.  Called with `key, value`.  It's called *before*
  actually removing the item from the internal cache, so if you want
  to immediately put it back in, you'll have to do that in a
  `nextTick` or `setTimeout` callback or it won't do anything.
* `stale` By default, if you set a `maxAge`, it'll only actually pull
  stale items out of the cache when you `get(key)`.  (That is, it's
  not pre-emptively doing a `setTimeout` or anything.)  If you set
  `stale:true`, it'll return the stale value before deleting it.  If
  you don't set this, then it'll return `undefined` when you try to
  get a stale entry, as if it had already been deleted.
* `noDisposeOnSet` By default, if you set a `dispose()` method, then
  it'll be called whenever a `set()` operation overwrites an existing
  key.  If you set this option, `dispose()` will only be called when a
  key falls out of the cache, not when it is overwritten.
* `updateAgeOnGet` When using time-expiring entries with `maxAge`,
  setting this to `true` will make each item's effective time update
  to the current time whenever it is retrieved from cache, causing it
  to not expire.  (It can still fall out of cache based on recency of
  use, of course.)

## API

* `set(key, value, maxAge)`
* `get(key) => value`

    Both of these will update the "recently used"-ness of the key.
    They do what you think. `maxAge` is optional and overrides the
    cache `maxAge` option if provided.

    If the key is not found, `get()` will return `undefined`.

    The key and val can be any value.

* `peek(key)`

    Returns the key value (or `undefined` if not found) without
    updating the "recently used"-ness of the key.

    (If you find yourself using this a lot, you *might* be using the
    wrong sort of data structure, but there are some use cases where
    it's handy.)

* `del(key)`

    Deletes a key out of the cache.

* `reset()`

    Clear the cache entirely, throwing away all values.

* `has(key)`

    Check if a key is in the cache, without updating the recent-ness
    or deleting it for being stale.

* `forEach(function(value,key,cache), [thisp])`

    Just like `Array.prototype.forEach`.  Iterates over all the keys
    in the cache, in order of recent-ness.  (Ie, more recently used
    items are iterated over first.)

* `rforEach(function(value,key,cache), [thisp])`

    The same as `cache.forEach(...)` but items are iterated over in
    reverse order.  (ie, less recently used items are iterated over
    first.)

* `keys()`

    Return an array of the keys in the cache.

* `values()`

    Return an array of the values in the cache.

* `length`

    Return total length of objects in cache taking into account
    `length` options function.

* `itemCount`

    Return total quantity of objects currently in cache. Note, that
    `stale` (see options) items are returned as part of this item
    count.

* `dump()`

    Return an array of the cache entries ready for serialization and usage
    with 'destinationCache.load(arr)`.

* `load(cacheEntriesArray)`

    Loads another cache entries array, obtained with `sourceCache.dump()`,
    into the cache. The destination cache is reset before loading new entries

* `prune()`

    Manually iterates over the entire cache proactively pruning old entries


---

# markdown-extensions

> List of Markdown file extensions

The list is just a [JSON file](markdown-extensions.json) and can be used anywhere.

## Install

```sh
npm install markdown-extensions
```

## Usage

```js
import markdownExtensions from 'markdown-extensions';

console.log(markdownExtensions);
//=> ['md', …]
```


---

# markdown-table

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]

Generate a markdown ([GFM][]) table.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`markdownTable(table[, options])`](#markdowntabletable-options)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Inspiration](#inspiration)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This is a simple package that takes table data and generates a [GitHub flavored
markdown (GFM)][gfm] table.

## When should I use this?

You can use this package when you want to generate the source code of a GFM
table from some data.

This is a simple solution in that it doesn’t handle escapes or HTML or any of
that.
For a complete but heavier solution, build an AST and serialize it with
[`mdast-util-to-markdown`][mdast-util-to-markdown] (with
[`mdast-util-gfm`][mdast-util-gfm]).

## Install

This package is [ESM only][esm].
In Node.js (version 14.14+, 16.0+), install with [npm][]:

```sh
npm install markdown-table
```

In Deno with [`esm.sh`][esmsh]:

```js
import {markdownTable} from 'https://esm.sh/markdown-table@3'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {markdownTable} from 'https://esm.sh/markdown-table@3?bundle'
</script>
```

## Use

Typical usage (defaults to align left):

```js
import {markdownTable} from 'markdown-table'

markdownTable([
  ['Branch', 'Commit'],
  ['main', '0123456789abcdef'],
  ['staging', 'fedcba9876543210']
])
```

Yields:

```markdown
| Branch  | Commit           |
| ------- | ---------------- |
| main    | 0123456789abcdef |
| staging | fedcba9876543210 |
```

With align:

```js
markdownTable(
  [
    ['Beep', 'No.', 'Boop'],
    ['beep', '1024', 'xyz'],
    ['boop', '3388450', 'tuv'],
    ['foo', '10106', 'qrstuv'],
    ['bar', '45', 'lmno']
  ],
  {align: ['l', 'c', 'r']}
)
```

Yields:

```markdown
| Beep |   No.   |   Boop |
| :--- | :-----: | -----: |
| beep |   1024  |    xyz |
| boop | 3388450 |    tuv |
| foo  |  10106  | qrstuv |
| bar  |    45   |   lmno |
```

## API

This package exports the identifier `markdownTable`.
There is no default export.

### `markdownTable(table[, options])`

Generate a markdown table from table data (matrix of strings).

##### `options`

Configuration (optional).

###### `options.align`

One style for all columns, or styles for their respective columns (`string` or
`Array<string>`).
Each style is either `'l'` (left), `'r'` (right), or `'c'` (center).
Other values are treated as `''`, which doesn’t place the colon in the alignment
row but does align left.
*Only the lowercased first character is used, so `Right` is fine.*

###### `options.padding`

Whether to add a space of padding between delimiters and cells (`boolean`,
default: `true`).

When `true`, there is padding:

```markdown
| Alpha | B     |
| ----- | ----- |
| C     | Delta |
```

When `false`, there is no padding:

```markdown
|Alpha|B    |
|-----|-----|
|C    |Delta|
```

###### `options.delimiterStart`

Whether to begin each row with the delimiter (`boolean`, default: `true`).

> 👉 **Note**: please don’t use this: it could create fragile structures that
> aren’t understandable to some markdown parsers.

When `true`, there are starting delimiters:

```markdown
| Alpha | B     |
| ----- | ----- |
| C     | Delta |
```

When `false`, there are no starting delimiters:

```markdown
Alpha | B     |
----- | ----- |
C     | Delta |
```

###### `options.delimiterEnd`

Whether to end each row with the delimiter (`boolean`, default: `true`).

> 👉 **Note**: please don’t use this: it could create fragile structures that
> aren’t understandable to some markdown parsers.

When `true`, there are ending delimiters:

```markdown
| Alpha | B     |
| ----- | ----- |
| C     | Delta |
```

When `false`, there are no ending delimiters:

```markdown
| Alpha | B
| ----- | -----
| C     | Delta
```

###### `options.alignDelimiters`

Whether to align the delimiters (`boolean`, default: `true`).
By default, they are aligned:

```markdown
| Alpha | B     |
| ----- | ----- |
| C     | Delta |
```

Pass `false` to make them staggered:

```markdown
| Alpha | B |
| - | - |
| C | Delta |
```

###### `options.stringLength`

Function to detect the length of table cell content (`Function`, default:
`s => s.length`).
This is used when aligning the delimiters (`|`) between table cells.
Full-width characters and emoji mess up delimiter alignment when viewing the
markdown source.
To fix this, you can pass this function, which receives the cell content and
returns its “visible” size.
Note that what is and isn’t visible depends on where the text is displayed.

Without such a function, the following:

```js
markdownTable([
  ['Alpha', 'Bravo'],
  ['中文', 'Charlie'],
  ['👩‍❤️‍👩', 'Delta']
])
```

Yields:

```markdown
| Alpha | Bravo |
| - | - |
| 中文 | Charlie |
| 👩‍❤️‍👩 | Delta |
```

With [`string-width`][string-width]:

```js
import stringWidth from 'string-width'

markdownTable(
  [
    ['Alpha', 'Bravo'],
    ['中文', 'Charlie'],
    ['👩‍❤️‍👩', 'Delta']
  ],
  {stringLength: stringWidth}
)
```

Yields:

```markdown
| Alpha | Bravo   |
| ----- | ------- |
| 中文  | Charlie |
| 👩‍❤️‍👩    | Delta   |
```

## Types

This package is fully typed with [TypeScript][].
It exports the additional type `Options`.

## Compatibility

This package is at least compatible with all maintained versions of Node.js.
As of now, that is Node.js 14.14+ and 16.0+.
It also works in Deno and modern browsers.

## Security

This package is safe.

## Inspiration

The original idea and basic implementation was inspired by James Halliday’s
[`text-table`][text-table] library.

## Contribute

Yes please!
See [How to Contribute to Open Source][contribute].

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/wooorm/markdown-table/workflows/main/badge.svg

[build]: https://github.com/wooorm/markdown-table/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/markdown-table.svg

[coverage]: https://codecov.io/github/wooorm/markdown-table

[downloads-badge]: https://img.shields.io/npm/dm/markdown-table.svg

[downloads]: https://www.npmjs.com/package/markdown-table

[size-badge]: https://img.shields.io/bundlephobia/minzip/markdown-table.svg

[size]: https://bundlephobia.com/result?p=markdown-table

[npm]: https://docs.npmjs.com/cli/install

[esmsh]: https://esm.sh

[license]: license

[author]: https://wooorm.com

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[typescript]: https://www.typescriptlang.org

[contribute]: https://opensource.guide/how-to-contribute/

[gfm]: https://docs.github.com/en/github/writing-on-github/working-with-advanced-formatting/organizing-information-with-tables

[text-table]: https://github.com/substack/text-table

[string-width]: https://github.com/sindresorhus/string-width

[mdast-util-to-markdown]: https://github.com/syntax-tree/mdast-util-to-markdown

[mdast-util-gfm]: https://github.com/syntax-tree/mdast-util-gfm


---

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [v1.1.0](https://github.com/es-shims/math-intrinsics/compare/v1.0.0...v1.1.0) - 2024-12-18

### Commits

- [New] add `round` [`7cfb044`](https://github.com/es-shims/math-intrinsics/commit/7cfb04460c0fbdf1ca101eecbac3f59d11994130)
- [Tests] add attw [`e96be8f`](https://github.com/es-shims/math-intrinsics/commit/e96be8fbf58449eafe976446a0470e6ea561ad8d)
- [Dev Deps] update `@types/tape` [`30d0023`](https://github.com/es-shims/math-intrinsics/commit/30d00234ce8a3fa0094a61cd55d6686eb91e36ec)

## v1.0.0 - 2024-12-11

### Commits

- Initial implementation, tests, readme, types [`b898caa`](https://github.com/es-shims/math-intrinsics/commit/b898caae94e9994a94a42b8740f7bbcfd0a868fe)
- Initial commit [`02745b0`](https://github.com/es-shims/math-intrinsics/commit/02745b03a62255af8a332771987b55d127538d9c)
- [New] add `constants/maxArrayLength`, `mod` [`b978178`](https://github.com/es-shims/math-intrinsics/commit/b978178a57685bd23ed1c7efe2137f3784f5fcc5)
- npm init [`a39fc57`](https://github.com/es-shims/math-intrinsics/commit/a39fc57e5639a645d0bd52a0dc56202480223be2)
- Only apps should have lockfiles [`9451580`](https://github.com/es-shims/math-intrinsics/commit/94515800fb34db4f3cc7e99290042d45609ac7bd)


---

# math-intrinsics <sup>[![Version Badge][npm-version-svg]][package-url]</sup>

[![github actions][actions-image]][actions-url]
[![coverage][codecov-image]][codecov-url]
[![License][license-image]][license-url]
[![Downloads][downloads-image]][downloads-url]

[![npm badge][npm-badge-png]][package-url]

ES Math-related intrinsics and helpers, robustly cached.

 - `abs`
 - `floor`
 - `isFinite`
 - `isInteger`
 - `isNaN`
 - `isNegativeZero`
 - `max`
 - `min`
 - `mod`
 - `pow`
 - `round`
 - `sign`
 - `constants/maxArrayLength`
 - `constants/maxSafeInteger`
 - `constants/maxValue`


## Tests
Simply clone the repo, `npm install`, and run `npm test`

## Security

Please email [@ljharb](https://github.com/ljharb) or see https://tidelift.com/security if you have a potential security vulnerability to report.

[package-url]: https://npmjs.org/package/math-intrinsics
[npm-version-svg]: https://versionbadg.es/es-shims/math-intrinsics.svg
[deps-svg]: https://david-dm.org/es-shims/math-intrinsics.svg
[deps-url]: https://david-dm.org/es-shims/math-intrinsics
[dev-deps-svg]: https://david-dm.org/es-shims/math-intrinsics/dev-status.svg
[dev-deps-url]: https://david-dm.org/es-shims/math-intrinsics#info=devDependencies
[npm-badge-png]: https://nodei.co/npm/math-intrinsics.png?downloads=true&stars=true
[license-image]: https://img.shields.io/npm/l/math-intrinsics.svg
[license-url]: LICENSE
[downloads-image]: https://img.shields.io/npm/dm/es-object.svg
[downloads-url]: https://npm-stat.com/charts.html?package=math-intrinsics
[codecov-image]: https://codecov.io/gh/es-shims/math-intrinsics/branch/main/graphs/badge.svg
[codecov-url]: https://app.codecov.io/gh/es-shims/math-intrinsics/
[actions-image]: https://img.shields.io/endpoint?url=https://github-actions-badge-u3jn4tfpocch.runkit.sh/es-shims/math-intrinsics
[actions-url]: https://github.com/es-shims/math-intrinsics/actions


---

# mdast-util-directive

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[mdast][] extensions to parse and serialize [generic directives proposal][prop]
(`:cite[smith04]`, `::youtube[Video of a cat in a box]{v=01ab2cd3efg}`, and
such).

## Contents

* [What is this?](#what-is-this)
* [When to use this](#when-to-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`directiveFromMarkdown()`](#directivefrommarkdown)
  * [`directiveToMarkdown(options?)`](#directivetomarkdownoptions)
  * [`ContainerDirective`](#containerdirective)
  * [`Directives`](#directives)
  * [`LeafDirective`](#leafdirective)
  * [`TextDirective`](#textdirective)
  * [`ToMarkdownOptions`](#tomarkdownoptions)
* [HTML](#html)
* [Syntax](#syntax)
* [Syntax tree](#syntax-tree)
  * [Nodes](#nodes)
  * [Mixin](#mixin)
* [Types](#types)
* [Compatibility](#compatibility)
* [Related](#related)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package contains two extensions that add support for directive syntax in
markdown to [mdast][].
These extensions plug into
[`mdast-util-from-markdown`][mdast-util-from-markdown] (to support parsing
directives in markdown into a syntax tree) and
[`mdast-util-to-markdown`][mdast-util-to-markdown] (to support serializing
directives in syntax trees to markdown).

## When to use this

Directives are one of the four ways to extend markdown: an arbitrary extension
syntax (see [Extending markdown][extending-markdown] in micromark’s docs for
the alternatives and more info).
This mechanism works well when you control the content: who authors it, what
tools handle it, and where it’s displayed.
When authors can read a guide on how to embed a tweet but are not expected to
know the ins and outs of HTML or JavaScript.
Directives don’t work well if you don’t know who authors content, what tools
handle it, and where it ends up.
Example use cases are a docs website for a project or product, or blogging tools
and static site generators.

You can use these extensions when you are working with
`mdast-util-from-markdown` and `mdast-util-to-markdown` already.

When working with `mdast-util-from-markdown`, you must combine this package
with [`micromark-extension-directive`][extension].

When you don’t need a syntax tree, you can use [`micromark`][micromark]
directly with `micromark-extension-directive`.

All these packages are used [`remark-directive`][remark-directive], which
focusses on making it easier to transform content by abstracting these
internals away.

This package only handles the syntax tree.
For example, it does not handle how markdown is turned to HTML.
You can use this with some more code to match your specific needs, to allow for
anything from callouts, citations, styled blocks, forms, embeds, spoilers, etc.
[Traverse the tree][traversal] to change directives to whatever you please.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install mdast-util-directive
```

In Deno with [`esm.sh`][esmsh]:

```js
import {directiveFromMarkdown, directiveToMarkdown} from 'https://esm.sh/mdast-util-directive@3'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {directiveFromMarkdown, directiveToMarkdown} from 'https://esm.sh/mdast-util-directive@3?bundle'
</script>
```

## Use

Say our document `example.md` contains:

```markdown
A lovely language know as :abbr[HTML]{title="HyperText Markup Language"}.
```

…and our module `example.js` looks as follows:

```js
import fs from 'node:fs/promises'
import {fromMarkdown} from 'mdast-util-from-markdown'
import {toMarkdown} from 'mdast-util-to-markdown'
import {directive} from 'micromark-extension-directive'
import {directiveFromMarkdown, directiveToMarkdown} from 'mdast-util-directive'

const doc = await fs.readFile('example.md')

const tree = fromMarkdown(doc, {
  extensions: [directive()],
  mdastExtensions: [directiveFromMarkdown()]
})

console.log(tree)

const out = toMarkdown(tree, {extensions: [directiveToMarkdown()]})

console.log(out)
```

…now running `node example.js` yields (positional info removed for brevity):

```js
{
  type: 'root',
  children: [
    {
      type: 'paragraph',
      children: [
        {type: 'text', value: 'A lovely language know as '},
        {
          type: 'textDirective',
          name: 'abbr',
          attributes: {title: 'HyperText Markup Language'},
          children: [{type: 'text', value: 'HTML'}]
        },
        {type: 'text', value: '.'}
      ]
    }
  ]
}
```

```markdown
A lovely language know as :abbr[HTML]{title="HyperText Markup Language"}.
```

## API

This package exports the identifiers
[`directiveFromMarkdown`][api-directive-from-markdown] and
[`directiveToMarkdown`][api-directive-to-markdown].
There is no default export.

### `directiveFromMarkdown()`

Create an extension for [`mdast-util-from-markdown`][mdast-util-from-markdown]
to enable directives in markdown.

###### Returns

Extension for `mdast-util-from-markdown` to enable directives
([`FromMarkdownExtension`][from-markdown-extension]).

### `directiveToMarkdown(options?)`

Create an extension for [`mdast-util-to-markdown`][mdast-util-to-markdown]
to enable directives in markdown.

###### Parameters

* `options`
  ([`ToMarkdownOptions`][api-to-markdown-options], optional)
  — configuration

###### Returns

Extension for `mdast-util-to-markdown` to enable directives
([`ToMarkdownExtension`][to-markdown-extension]).

### `ContainerDirective`

Directive in flow content (such as in the root document, or block quotes),
which contains further flow content (TypeScript type).

###### Type

```ts
import type {BlockContent, DefinitionContent, Parent} from 'mdast'

interface ContainerDirective extends Parent {
  type: 'containerDirective'
  name: string
  attributes?: Record<string, string | null | undefined> | null | undefined
  children: Array<BlockContent | DefinitionContent>
}
```

### `Directives`

The different directive nodes (TypeScript type).

###### Type

```ts
type Directives = ContainerDirective | LeafDirective | TextDirective
```

### `LeafDirective`

Directive in flow content (such as in the root document, or block quotes),
which contains nothing (TypeScript type).

###### Type

```ts
import type {PhrasingContent, Parent} from 'mdast'

interface LeafDirective extends Parent {
  type: 'leafDirective'
  name: string
  attributes?: Record<string, string | null | undefined> | null | undefined
  children: Array<PhrasingContent>
}
```

### `TextDirective`

Directive in phrasing content (such as in paragraphs, headings) (TypeScript
type).

###### Type

```ts
import type {PhrasingContent, Parent} from 'mdast'

interface TextDirective extends Parent {
  type: 'textDirective'
  name: string
  attributes?: Record<string, string | null | undefined> | null | undefined
  children: Array<PhrasingContent>
}
```

### `ToMarkdownOptions`

Configuration.

###### Parameters

* `collapseEmptyAttributes`
  (`boolean`, default: `true`)
  — collapse empty attributes: get `title` instead of `title=""`
* `preferShortcut`
  (`boolean`, default: `true`)
  — prefer `#` and `.` shortcuts for `id` and `class`
* `preferUnquoted`
  (`boolean`, default: `false`)
  — leave attributes unquoted if that results in less bytes
* `quoteSmart`
  (`boolean`, default: `false`)
  — use the other quote if that results in less bytes
* `quote`
  (`'"'` or `"'"`,
  default: the [`quote`][quote] used by `mdast-util-to-markdown` for titles)
  — preferred quote to use around attribute values

## HTML

This utility does not handle how markdown is turned to HTML.
You can use this with some more code to match your specific needs, to allow for
anything from callouts, citations, styled blocks, forms, embeds, spoilers, etc.
[Traverse the tree][traversal] to change directives to whatever you please.

## Syntax

See [Syntax in `micromark-extension-directive`][syntax].

## Syntax tree

The following interfaces are added to **[mdast][]** by this utility.

### Nodes

#### `TextDirective`

```idl
interface TextDirective <: Parent {
  type: 'textDirective'
  children: [PhrasingContent]
}

TextDirective includes Directive
```

**TextDirective** (**[Parent][dfn-parent]**) is a directive.
It can be used where **[phrasing][dfn-phrasing-content]** content is expected.
Its content model is also **[phrasing][dfn-phrasing-content]** content.
It includes the mixin **[Directive][dfn-mxn-directive]**.

For example, the following Markdown:

```markdown
:name[Label]{#x.y.z key=value}
```

Yields:

```js
{
  type: 'textDirective',
  name: 'name',
  attributes: {id: 'x', class: 'y z', key: 'value'},
  children: [{type: 'text', value: 'Label'}]
}
```

#### `LeafDirective`

```idl
interface LeafDirective <: Parent {
  type: 'leafDirective'
  children: [PhrasingContent]
}

LeafDirective includes Directive
```

**LeafDirective** (**[Parent][dfn-parent]**) is a directive.
It can be used where **[flow][dfn-flow-content]** content is expected.
Its content model is **[phrasing][dfn-phrasing-content]** content.
It includes the mixin **[Directive][dfn-mxn-directive]**.

For example, the following Markdown:

```markdown
::youtube[Label]{v=123}
```

Yields:

```js
{
  type: 'leafDirective',
  name: 'youtube',
  attributes: {v: '123'},
  children: [{type: 'text', value: 'Label'}]
}
```

#### `ContainerDirective`

```idl
interface ContainerDirective <: Parent {
  type: 'containerDirective'
  children: [FlowContent]
}

ContainerDirective includes Directive
```

**ContainerDirective** (**[Parent][dfn-parent]**) is a directive.
It can be used where **[flow][dfn-flow-content]** content is expected.
Its content model is also **[flow][dfn-flow-content]** content.
It includes the mixin **[Directive][dfn-mxn-directive]**.

The phrasing in the label is, when available, added as a paragraph with a
`directiveLabel: true` field, as the head of its content.

For example, the following Markdown:

```markdown
:::spoiler[Open at your own peril]
He dies.
:::
```

Yields:

```js
{
  type: 'containerDirective',
  name: 'spoiler',
  attributes: {},
  children: [
    {
      type: 'paragraph',
      data: {directiveLabel: true},
      children: [{type: 'text', value: 'Open at your own peril'}]
    },
    {
      type: 'paragraph',
      children: [{type: 'text', value: 'He dies.'}]
    }
  ]
}
```

### Mixin

#### `Directive`

```idl
interface mixin Directive {
  name: string
  attributes: Attributes?
}

interface Attributes {}
typedef string AttributeName
typedef string AttributeValue
```

**Directive** represents something defined by an extension.

The `name` field must be present and represents an identifier of an extension.

The `attributes` field represents information associated with the node.
The value of the `attributes` field implements the **Attributes** interface.

In the **Attributes** interface, every field must be an `AttributeName` and
every value an `AttributeValue`.
The fields and values can be anything: there are no semantics (such as by HTML
or hast).

> In JSON, the value `null` must be treated as if the attribute was not
> included.
> In JavaScript, both `null` and `undefined` must be similarly ignored.

## Types

This package is fully typed with [TypeScript][].
It exports the additional types [`ContainerDirective`][api-container-directive],
[`Directives`][api-directives], [`LeafDirective`][api-leaf-directive], and
[`TextDirective`][api-text-directive].

It also registers the node types with `@types/mdast`.
If you’re working with the syntax tree, make sure to import this utility
somewhere in your types, as that registers the new node types in the tree.

```js
/**
 * @import {} from 'mdast-util-directive'
 * @import {Root} from 'mdast'
 */

import {visit} from 'unist-util-visit'

/** @type {Root} */
const tree = getMdastNodeSomeHow()

visit(tree, function (node) {
  // `node` can now be one of the nodes for directives.
})
```

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, `mdast-util-directive@^3`,
compatible with Node.js 16.

This utility works with `mdast-util-from-markdown` version 2+ and
`mdast-util-to-markdown` version 2+.

## Related

* [`remarkjs/remark-directive`][remark-directive]
  — remark plugin to support generic directives
* [`micromark/micromark-extension-directive`][extension]
  — micromark extension to parse directives

## Contribute

See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
ways to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/syntax-tree/mdast-util-directive/workflows/main/badge.svg

[build]: https://github.com/syntax-tree/mdast-util-directive/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/mdast-util-directive.svg

[coverage]: https://codecov.io/github/syntax-tree/mdast-util-directive

[downloads-badge]: https://img.shields.io/npm/dm/mdast-util-directive.svg

[downloads]: https://www.npmjs.com/package/mdast-util-directive

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=mdast-util-directive

[size]: https://bundlejs.com/?q=mdast-util-directive

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/syntax-tree/unist/discussions

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[typescript]: https://www.typescriptlang.org

[license]: license

[author]: https://wooorm.com

[health]: https://github.com/syntax-tree/.github

[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md

[support]: https://github.com/syntax-tree/.github/blob/main/support.md

[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md

[mdast]: https://github.com/syntax-tree/mdast

[mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown

[mdast-util-to-markdown]: https://github.com/syntax-tree/mdast-util-to-markdown

[quote]: https://github.com/syntax-tree/mdast-util-to-markdown#optionsquote

[micromark]: https://github.com/micromark/micromark

[extension]: https://github.com/micromark/micromark-extension-directive

[syntax]: https://github.com/micromark/micromark-extension-directive#syntax

[remark-directive]: https://github.com/remarkjs/remark-directive

[extending-markdown]: https://github.com/micromark/micromark#extending-markdown

[prop]: https://talk.commonmark.org/t/generic-directives-plugins-syntax/444

[traversal]: https://unifiedjs.com/learn/recipe/tree-traversal/

[dfn-parent]: https://github.com/syntax-tree/mdast#parent

[dfn-flow-content]: https://github.com/syntax-tree/mdast#flowcontent

[dfn-phrasing-content]: https://github.com/syntax-tree/mdast#phrasingcontent

[from-markdown-extension]: https://github.com/syntax-tree/mdast-util-from-markdown#extension

[to-markdown-extension]: https://github.com/syntax-tree/mdast-util-to-markdown#options

[api-directive-from-markdown]: #directivefrommarkdown

[api-directive-to-markdown]: #directivetomarkdownoptions

[api-to-markdown-options]: #tomarkdownoptions

[api-container-directive]: #containerdirective

[api-directives]: #directives

[api-leaf-directive]: #leafdirective

[api-text-directive]: #textdirective

[dfn-mxn-directive]: #directive


---

# escape-string-regexp

> Escape RegExp special characters

## Install

```
$ npm install escape-string-regexp
```

## Usage

```js
import escapeStringRegexp from 'escape-string-regexp';

const escapedString = escapeStringRegexp('How much $ for a 🦄?');
//=> 'How much \\$ for a 🦄\\?'

new RegExp(escapedString);
```

You can also use this to escape a string that is inserted into the middle of a regex, for example, into a character class.

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-escape-string-regexp?utm_source=npm-escape-string-regexp&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

# mdast-util-find-and-replace

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[mdast][] utility to find and replace things.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`findAndReplace(tree, list[, options])`](#findandreplacetree-list-options)
  * [`Find`](#find)
  * [`FindAndReplaceList`](#findandreplacelist)
  * [`FindAndReplaceTuple`](#findandreplacetuple)
  * [`Options`](#options)
  * [`RegExpMatchObject`](#regexpmatchobject)
  * [`Replace`](#replace)
  * [`ReplaceFunction`](#replacefunction)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Related](#related)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package is a utility that lets you find patterns (`string`, `RegExp`) in
text and replace them with nodes.

## When should I use this?

This utility is typically useful when you have regexes and want to modify mdast.
One example is when you have some form of “mentions” (such as
`/@([a-z][_a-z0-9])\b/gi`) and want to create links to persons from them.

A similar package, [`hast-util-find-and-replace`][hast-util-find-and-replace]
does the same but on [hast][].

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install mdast-util-find-and-replace
```

In Deno with [`esm.sh`][esmsh]:

```js
import {findAndReplace} from 'https://esm.sh/mdast-util-find-and-replace@3'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {findAndReplace} from 'https://esm.sh/mdast-util-find-and-replace@3?bundle'
</script>
```

## Use

```js
import {findAndReplace} from 'mdast-util-find-and-replace'
import {u} from 'unist-builder'
import {inspect} from 'unist-util-inspect'

const tree = u('paragraph', [
  u('text', 'Some '),
  u('emphasis', [u('text', 'emphasis')]),
  u('text', ' and '),
  u('strong', [u('text', 'importance')]),
  u('text', '.')
])

findAndReplace(tree, [
  [/and/gi, 'or'],
  [/emphasis/gi, 'em'],
  [/importance/gi, 'strong'],
  [
    /Some/g,
    function ($0) {
      return u('link', {url: '//example.com#' + $0}, [u('text', $0)])
    }
  ]
])

console.log(inspect(tree))
```

Yields:

```txt
paragraph[8]
├─0 link[1]
│   │ url: "//example.com#Some"
│   └─0 text "Some"
├─1 text " "
├─2 emphasis[1]
│   └─0 text "em"
├─3 text " "
├─4 text "or"
├─5 text " "
├─6 strong[1]
│   └─0 text "strong"
└─7 text "."
```

## API

This package exports the identifier [`findAndReplace`][api-find-and-replace].
There is no default export.

### `findAndReplace(tree, list[, options])`

Find patterns in a tree and replace them.

The algorithm searches the tree in *[preorder][]* for complete values in
[`Text`][text] nodes.
Partial matches are not supported.

###### Parameters

* `tree` ([`Node`][node])
  — tree to change
* `list` ([`FindAndReplaceList`][api-find-and-replace-list] or
  [`FindAndReplaceTuple`][api-find-and-replace-tuple])
  — one or more find-and-replace pairs
* `options` ([`Options`][api-options])
  — configuration

###### Returns

Nothing (`undefined`).

### `Find`

Pattern to find (TypeScript type).

Strings are escaped and then turned into global expressions.

###### Type

```ts
type Find = RegExp | string
```

### `FindAndReplaceList`

Several find and replaces, in array form (TypeScript type).

###### Type

```ts
type FindAndReplaceList = Array<FindAndReplaceTuple>
```

See [`FindAndReplaceTuple`][api-find-and-replace-tuple].

### `FindAndReplaceTuple`

Find and replace in tuple form (TypeScript type).

###### Type

```ts
type FindAndReplaceTuple = [Find, Replace?]
```

See [`Find`][api-find] and [`Replace`][api-replace].

### `Options`

Configuration (TypeScript type).

###### Fields

* `ignore` ([`Test`][test], optional)
  — test for which elements to ignore

### `RegExpMatchObject`

Info on the match (TypeScript type).

###### Fields

* `index` (`number`)
  — the index of the search at which the result was found
* `input` (`string`)
  — a copy of the search string in the text node
* `stack` ([`Array<Node>`][node])
  — all ancestors of the text node, where the last node is the text itself

### `Replace`

Thing to replace with (TypeScript type).

###### Type

```ts
type Replace = ReplaceFunction | string
```

See [`ReplaceFunction`][api-replace-function].

### `ReplaceFunction`

Callback called when a search matches (TypeScript type).

###### Parameters

The parameters are the result of corresponding search expression:

* `value` (`string`)
  — whole match
* `...capture` (`Array<string>`)
  — matches from regex capture groups
* `match` ([`RegExpMatchObject`][api-regexp-match-object])
  — info on the match

###### Returns

Thing to replace with:

* when `null`, `undefined`, `''`, remove the match
* …or when `false`, do not replace at all
* …or when `string`, replace with a text node of that value
* …or when `Node` or `Array<Node>`, replace with those nodes

## Types

This package is fully typed with [TypeScript][].
It exports the additional types [`Find`][api-find],
[`FindAndReplaceList`][api-find-and-replace-list],
[`FindAndReplaceTuple`][api-find-and-replace-tuple],
[`Options`][api-options],
[`RegExpMatchObject`][api-regexp-match-object],
[`Replace`][api-replace], and
[`ReplaceFunction`][api-replace-function].

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`mdast-util-find-and-replace@^3`, compatible with Node.js 16.

## Security

Use of `mdast-util-find-and-replace` does not involve [hast][] or user content
so there are no openings for [cross-site scripting (XSS)][xss] attacks.

## Related

* [`hast-util-find-and-replace`](https://github.com/syntax-tree/hast-util-find-and-replace)
  — find and replace in hast
* [`hast-util-select`](https://github.com/syntax-tree/hast-util-select)
  — `querySelector`, `querySelectorAll`, and `matches`
* [`unist-util-select`](https://github.com/syntax-tree/unist-util-select)
  — select unist nodes with CSS-like selectors

## Contribute

See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
ways to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definition -->

[build-badge]: https://github.com/syntax-tree/mdast-util-find-and-replace/workflows/main/badge.svg

[build]: https://github.com/syntax-tree/mdast-util-find-and-replace/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/mdast-util-find-and-replace.svg

[coverage]: https://codecov.io/github/syntax-tree/mdast-util-find-and-replace

[downloads-badge]: https://img.shields.io/npm/dm/mdast-util-find-and-replace.svg

[downloads]: https://www.npmjs.com/package/mdast-util-find-and-replace

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=mdast-util-find-and-replace

[size]: https://bundlejs.com/?q=mdast-util-find-and-replace

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/syntax-tree/unist/discussions

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[typescript]: https://www.typescriptlang.org

[license]: license

[author]: https://wooorm.com

[health]: https://github.com/syntax-tree/.github

[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md

[support]: https://github.com/syntax-tree/.github/blob/main/support.md

[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md

[hast]: https://github.com/syntax-tree/hast

[mdast]: https://github.com/syntax-tree/mdast

[node]: https://github.com/syntax-tree/mdast#nodes

[preorder]: https://github.com/syntax-tree/unist#preorder

[text]: https://github.com/syntax-tree/mdast#text

[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting

[test]: https://github.com/syntax-tree/unist-util-is#api

[hast-util-find-and-replace]: https://github.com/syntax-tree/hast-util-find-and-replace

[api-find-and-replace]: #findandreplacetree-list-options

[api-options]: #options

[api-find]: #find

[api-replace]: #replace

[api-replace-function]: #replacefunction

[api-find-and-replace-list]: #findandreplacelist

[api-find-and-replace-tuple]: #findandreplacetuple

[api-regexp-match-object]: #regexpmatchobject


---

# micromark-util-symbol

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility with symbols.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes constants used throughout the micromark ecosystem.

## When should I use this?

This package is useful when you are making your own micromark extensions.
It’s useful to reference these constants by name instead of value while
developing.
[`micromark-build`][micromark-build] compiles them away for production code.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-symbol
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as symbol from 'https://esm.sh/micromark-util-symbol@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as symbol from 'https://esm.sh/micromark-util-symbol@1?bundle'
</script>
```

## Use

```js
import {codes, constants, types, values} from 'micromark-util-symbol'

console.log(codes.atSign) // 64
console.log(constants.characterReferenceNamedSizeMax) // 31
console.log(types.definitionDestinationRaw) // 'definitionDestinationRaw'
console.log(values.atSign) // '@'
```

## API

This package exports the identifiers `codes`, `constants`, `types`, and
`values`.
There is no default export.

Each identifier is an object mapping strings to values.
See the code for the exposed data.

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-symbol@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-symbol.svg

[downloads]: https://www.npmjs.com/package/micromark-util-symbol

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-symbol

[bundle-size]: https://bundlejs.com/?q=micromark-util-symbol

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[micromark-build]: https://github.com/micromark/micromark/tree/main/packages/micromark-build


---

# mdast-util-from-markdown

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

**[mdast][]** utility that turns markdown into a syntax tree.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`fromMarkdown(value[, encoding][, options])`](#frommarkdownvalue-encoding-options)
  * [`CompileContext`](#compilecontext)
  * [`CompileData`](#compiledata)
  * [`Encoding`](#encoding)
  * [`Extension`](#extension)
  * [`Handle`](#handle)
  * [`OnEnterError`](#onentererror)
  * [`OnExitError`](#onexiterror)
  * [`Options`](#options)
  * [`Token`](#token)
  * [`Transform`](#transform)
  * [`Value`](#value)
* [List of extensions](#list-of-extensions)
* [Syntax](#syntax)
* [Syntax tree](#syntax-tree)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Related](#related)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package is a utility that takes markdown input and turns it into an
[mdast][] syntax tree.

This utility uses [`micromark`][micromark], which turns markdown into tokens,
and then turns those tokens into nodes.
This package is used inside [`remark-parse`][remark-parse], which focusses on
making it easier to transform content by abstracting these internals away.

## When should I use this?

If you want to handle syntax trees manually, use this.
When you *just* want to turn markdown into HTML, use [`micromark`][micromark]
instead.
For an easier time processing content, use the **[remark][]** ecosystem instead.

You can combine this package with other packages to add syntax extensions to
markdown.
Notable examples that deeply integrate with this package are
[`mdast-util-gfm`][mdast-util-gfm],
[`mdast-util-mdx`][mdast-util-mdx],
[`mdast-util-frontmatter`][mdast-util-frontmatter],
[`mdast-util-math`][mdast-util-math], and
[`mdast-util-directive`][mdast-util-directive].

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install mdast-util-from-markdown
```

In Deno with [`esm.sh`][esmsh]:

```js
import {fromMarkdown} from 'https://esm.sh/mdast-util-from-markdown@2'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {fromMarkdown} from 'https://esm.sh/mdast-util-from-markdown@2?bundle'
</script>
```

## Use

Say we have the following markdown file `example.md`:

```markdown
## Hello, *World*!
```

…and our module `example.js` looks as follows:

```js
import fs from 'node:fs/promises'
import {fromMarkdown} from 'mdast-util-from-markdown'

const doc = await fs.readFile('example.md')
const tree = fromMarkdown(doc)

console.log(tree)
```

…now running `node example.js` yields (positional info removed for brevity):

```js
{
  type: 'root',
  children: [
    {
      type: 'heading',
      depth: 2,
      children: [
        {type: 'text', value: 'Hello, '},
        {type: 'emphasis', children: [{type: 'text', value: 'World'}]},
        {type: 'text', value: '!'}
      ]
    }
  ]
}
```

## API

This package exports the identifier [`fromMarkdown`][api-from-markdown].
There is no default export.

The export map supports the [`development` condition][development].
Run `node --conditions development example.js` to get instrumented dev code.
Without this condition, production code is loaded.

### `fromMarkdown(value[, encoding][, options])`

Turn markdown into a syntax tree.

###### Overloads

* `(value: Value, encoding: Encoding, options?: Options) => Root`
* `(value: Value, options?: Options) => Root`

###### Parameters

* `value` ([`Value`][api-value])
  — markdown to parse
* `encoding` ([`Encoding`][api-encoding], default: `'utf8'`)
  — [character encoding][encoding] for when `value` is
  [`Uint8Array`][uint8-array]
* `options` ([`Options`][api-options], optional)
  — configuration

###### Returns

mdast tree ([`Root`][root]).

### `CompileContext`

mdast compiler context (TypeScript type).

###### Fields

* `stack` ([`Array<Node>`][node])
  — stack of nodes
* `tokenStack` (`Array<[Token, OnEnterError | undefined]>`)
  — stack of tokens
* `data` ([`CompileData`][api-compile-data])
  — info passed around; key/value store
* `buffer` (`() => undefined`)
  — capture some of the output data
* `resume` (`() => string`)
  — stop capturing and access the output data
* `enter` (`(node: Node, token: Token, onError?: OnEnterError) => undefined`)
  — enter a node
* `exit` (`(token: Token, onError?: OnExitError) => undefined`)
  — exit a node
* `sliceSerialize` (`(token: Token, expandTabs?: boolean) => string`)
  — get the string value of a token
* `config` (`Required<Extension>`)
  — configuration

### `CompileData`

Interface of tracked data (TypeScript type).

###### Type

```ts
interface CompileData { /* see code */ }
```

When working on extensions that use more data, extend the corresponding
interface to register their types:

```ts
declare module 'mdast-util-from-markdown' {
  interface CompileData {
    // Register a new field.
    mathFlowInside?: boolean | undefined
  }
}
```

### `Encoding`

Encodings supported by the [`Uint8Array`][uint8-array] class (TypeScript type).

See [`micromark`][micromark-api] for more info.

###### Type

```ts
type Encoding = 'utf8' | /* … */
```

### `Extension`

Change how markdown tokens from micromark are turned into mdast (TypeScript
type).

###### Properties

* `canContainEols` (`Array<string>`, optional)
  — token types where line endings are used
* `enter` ([`Record<string, Handle>`][api-handle], optional)
  — opening handles
* `exit` ([`Record<string, Handle>`][api-handle], optional)
  — closing handles
* `transforms` ([`Array<Transform>`][api-transform], optional)
  — tree transforms

### `Handle`

Handle a token (TypeScript type).

###### Parameters

* `this` ([`CompileContext`][api-compile-context])
  — context
* `token` ([`Token`][api-token])
  — current token

###### Returns

Nothing (`undefined`).

### `OnEnterError`

Handle the case where the `right` token is open, but it is closed (by the
`left` token) or because we reached the end of the document (TypeScript type).

###### Parameters

* `this` ([`CompileContext`][api-compile-context])
  — context
* `left` ([`Token`][api-token] or `undefined`)
  — left token
* `right` ([`Token`][api-token])
  — right token

###### Returns

Nothing (`undefined`).

### `OnExitError`

Handle the case where the `right` token is open but it is closed by
exiting the `left` token (TypeScript type).

###### Parameters

* `this` ([`CompileContext`][api-compile-context])
  — context
* `left` ([`Token`][api-token])
  — left token
* `right` ([`Token`][api-token])
  — right token

###### Returns

Nothing (`undefined`).

### `Options`

Configuration (TypeScript type).

###### Properties

* `extensions` ([`Array<MicromarkExtension>`][micromark-extension], optional)
  — micromark extensions to change how markdown is parsed
* `mdastExtensions` ([`Array<Extension | Array<Extension>>`][api-extension],
  optional)
  — extensions for this utility to change how tokens are turned into a tree

### `Token`

Token from micromark (TypeScript type).

###### Type

```ts
type Token = { /* … */ }
```

### `Transform`

Extra transform, to change the AST afterwards (TypeScript type).

###### Parameters

* `tree` ([`Root`][root])
  — tree to transform

###### Returns

New tree ([`Root`][root]) or nothing (in which case the current tree is used).

### `Value`

Contents of the file (TypeScript type).

See [`micromark`][micromark-api] for more info.

###### Type

```ts
type Value = Uint8Array | string
```

## List of extensions

* [`syntax-tree/mdast-util-directive`](https://github.com/syntax-tree/mdast-util-directive)
  — directives
* [`syntax-tree/mdast-util-frontmatter`](https://github.com/syntax-tree/mdast-util-frontmatter)
  — frontmatter (YAML, TOML, more)
* [`syntax-tree/mdast-util-gfm`](https://github.com/syntax-tree/mdast-util-gfm)
  — GFM
* [`syntax-tree/mdast-util-gfm-autolink-literal`](https://github.com/syntax-tree/mdast-util-gfm-autolink-literal)
  — GFM autolink literals
* [`syntax-tree/mdast-util-gfm-footnote`](https://github.com/syntax-tree/mdast-util-gfm-footnote)
  — GFM footnotes
* [`syntax-tree/mdast-util-gfm-strikethrough`](https://github.com/syntax-tree/mdast-util-gfm-strikethrough)
  — GFM strikethrough
* [`syntax-tree/mdast-util-gfm-table`](https://github.com/syntax-tree/mdast-util-gfm-table)
  — GFM tables
* [`syntax-tree/mdast-util-gfm-task-list-item`](https://github.com/syntax-tree/mdast-util-gfm-task-list-item)
  — GFM task list items
* [`syntax-tree/mdast-util-math`](https://github.com/syntax-tree/mdast-util-math)
  — math
* [`syntax-tree/mdast-util-mdx`](https://github.com/syntax-tree/mdast-util-mdx)
  — MDX
* [`syntax-tree/mdast-util-mdx-expression`](https://github.com/syntax-tree/mdast-util-mdx-expression)
  — MDX expressions
* [`syntax-tree/mdast-util-mdx-jsx`](https://github.com/syntax-tree/mdast-util-mdx-jsx)
  — MDX JSX
* [`syntax-tree/mdast-util-mdxjs-esm`](https://github.com/syntax-tree/mdast-util-mdxjs-esm)
  — MDX ESM

## Syntax

Markdown is parsed according to CommonMark.
Extensions can add support for other syntax.
If you’re interested in extending markdown,
[more information is available in micromark’s readme][micromark-extension].

## Syntax tree

The syntax tree is [mdast][].

## Types

This package is fully typed with [TypeScript][].
It exports the additional types [`CompileContext`][api-compile-context],
[`CompileData`][api-compile-data],
[`Encoding`][api-encoding],
[`Extension`][api-extension],
[`Handle`][api-handle],
[`OnEnterError`][api-on-enter-error],
[`OnExitError`][api-on-exit-error],
[`Options`][api-options],
[`Token`][api-token],
[`Transform`][api-transform], and
[`Value`][api-value].

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`mdast-util-from-markdown@^2`, compatible with Node.js 16.

## Security

As markdown is sometimes used for HTML, and improper use of HTML can open you up
to a [cross-site scripting (XSS)][xss] attack, use of `mdast-util-from-markdown`
can also be unsafe.
When going to HTML, use this utility in combination with
[`hast-util-sanitize`][hast-util-sanitize] to make the tree safe.

## Related

* [`syntax-tree/mdast-util-to-markdown`](https://github.com/syntax-tree/mdast-util-to-markdown)
  — serialize mdast as markdown
* [`micromark/micromark`](https://github.com/micromark/micromark)
  — parse markdown
* [`remarkjs/remark`](https://github.com/remarkjs/remark)
  — process markdown

## Contribute

See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
ways to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/syntax-tree/mdast-util-from-markdown/workflows/main/badge.svg

[build]: https://github.com/syntax-tree/mdast-util-from-markdown/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/mdast-util-from-markdown.svg

[coverage]: https://codecov.io/github/syntax-tree/mdast-util-from-markdown

[downloads-badge]: https://img.shields.io/npm/dm/mdast-util-from-markdown.svg

[downloads]: https://www.npmjs.com/package/mdast-util-from-markdown

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=mdast-util-from-markdown

[size]: https://bundlejs.com/?q=mdast-util-from-markdown

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/syntax-tree/unist/discussions

[npm]: https://docs.npmjs.com/cli/install

[esmsh]: https://esm.sh

[license]: license

[author]: https://wooorm.com

[health]: https://github.com/syntax-tree/.github

[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md

[support]: https://github.com/syntax-tree/.github/blob/main/support.md

[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[typescript]: https://www.typescriptlang.org

[mdast]: https://github.com/syntax-tree/mdast

[node]: https://github.com/syntax-tree/mdast#nodes

[mdast-util-gfm]: https://github.com/syntax-tree/mdast-util-gfm

[mdast-util-mdx]: https://github.com/syntax-tree/mdast-util-mdx

[mdast-util-frontmatter]: https://github.com/syntax-tree/mdast-util-frontmatter

[mdast-util-math]: https://github.com/syntax-tree/mdast-util-math

[mdast-util-directive]: https://github.com/syntax-tree/mdast-util-directive

[root]: https://github.com/syntax-tree/mdast#root

[uint8-array]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array

[encoding]: https://nodejs.org/api/util.html#whatwg-supported-encodings

[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting

[hast-util-sanitize]: https://github.com/syntax-tree/hast-util-sanitize

[micromark]: https://github.com/micromark/micromark

[micromark-api]: https://github.com/micromark/micromark/tree/main/packages/micromark#micromarkvalue-encoding-options

[micromark-extension]: https://github.com/micromark/micromark#extensions

[remark]: https://github.com/remarkjs/remark

[remark-parse]: https://github.com/remarkjs/remark/tree/main/packages/remark-parse

[development]: https://nodejs.org/api/packages.html#packages_resolving_user_conditions

[api-from-markdown]: #frommarkdownvalue-encoding-options

[api-compile-context]: #compilecontext

[api-compile-data]: #compiledata

[api-encoding]: #encoding

[api-extension]: #extension

[api-handle]: #handle

[api-on-enter-error]: #onentererror

[api-on-exit-error]: #onexiterror

[api-options]: #options

[api-token]: #token

[api-transform]: #transform

[api-value]: #value


---

# escape-string-regexp

> Escape RegExp special characters

## Install

```
$ npm install escape-string-regexp
```

## Usage

```js
import escapeStringRegexp from 'escape-string-regexp';

const escapedString = escapeStringRegexp('How much $ for a 🦄?');
//=> 'How much \\$ for a 🦄\\?'

new RegExp(escapedString);
```

You can also use this to escape a string that is inserted into the middle of a regex, for example, into a character class.

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-escape-string-regexp?utm_source=npm-escape-string-regexp&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

# mdast-util-frontmatter

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[mdast][] extensions to parse and serialize frontmatter (YAML, TOML, and more).

## Contents

*   [What is this?](#what-is-this)
*   [When to use this](#when-to-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`frontmatterFromMarkdown(options?)`](#frontmatterfrommarkdownoptions)
    *   [`frontmatterToMarkdown(options?)`](#frontmattertomarkdownoptions)
    *   [`Info`](#info)
    *   [`Matter`](#matter)
    *   [`Options`](#options)
*   [Syntax](#syntax)
*   [Syntax tree](#syntax-tree)
    *   [Nodes](#nodes)
    *   [Content model](#content-model)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package contains two extensions that add support for frontmatter syntax
as often used in markdown to [mdast][].
These extensions plug into
[`mdast-util-from-markdown`][mdast-util-from-markdown] (to support parsing
frontmatter in markdown into a syntax tree) and
[`mdast-util-to-markdown`][mdast-util-to-markdown] (to support serializing
frontmatter in syntax trees to markdown).

Frontmatter is a metadata format in front of the content.
It’s typically written in YAML and is often used with markdown.
Frontmatter does not work everywhere so it makes markdown less portable.

These extensions follow how GitHub handles frontmatter.
GitHub only supports YAML frontmatter, but these extensions also support
different flavors (such as TOML).

## When to use this

You can use these extensions when you are working with
`mdast-util-from-markdown` and `mdast-util-to-markdown` already.

When working with `mdast-util-from-markdown`, you must combine this package
with [`micromark-extension-frontmatter`][micromark-extension-frontmatter].

When you don’t need a syntax tree, you can use [`micromark`][micromark]
directly with
[`micromark-extension-frontmatter`][micromark-extension-frontmatter].

All these packages are used [`remark-frontmatter`][remark-frontmatter], which
focusses on making it easier to transform content by abstracting these
internals away.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install mdast-util-frontmatter
```

In Deno with [`esm.sh`][esmsh]:

```js
import {frontmatterFromMarkdown, frontmatterToMarkdown} from 'https://esm.sh/mdast-util-frontmatter@2'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {frontmatterFromMarkdown, frontmatterToMarkdown} from 'https://esm.sh/mdast-util-frontmatter@2?bundle'
</script>
```

## Use

Say our document `example.md` contains:

```markdown
+++
title = "New Website"
+++

# Other markdown
```

…and our module `example.js` looks as follows:

```js
import fs from 'node:fs/promises'
import {frontmatter} from 'micromark-extension-frontmatter'
import {fromMarkdown} from 'mdast-util-from-markdown'
import {frontmatterFromMarkdown, frontmatterToMarkdown} from 'mdast-util-frontmatter'
import {toMarkdown} from 'mdast-util-to-markdown'

const doc = await fs.readFile('example.md')

const tree = fromMarkdown(doc, {
  extensions: [frontmatter(['yaml', 'toml'])],
  mdastExtensions: [frontmatterFromMarkdown(['yaml', 'toml'])]
})

console.log(tree)

const out = toMarkdown(tree, {extensions: [frontmatterToMarkdown(['yaml', 'toml'])]})

console.log(out)
```

…now running `node example.js` yields (positional info removed for brevity):

```js
{
  type: 'root',
  children: [
    {type: 'toml', value: 'title = "New Website"'},
    {
      type: 'heading',
      depth: 1,
      children: [{type: 'text', value: 'Other markdown'}]
    }
  ]
}
```

```markdown
+++
title = "New Website"
+++

# Other markdown
```

## API

This package exports the identifiers
[`frontmatterFromMarkdown`][api-frontmatter-from-markdown] and
[`frontmatterToMarkdown`][api-frontmatter-to-markdown].
There is no default export.

### `frontmatterFromMarkdown(options?)`

Create an extension for
[`mdast-util-from-markdown`][mdast-util-from-markdown].

###### Parameters

*   `options` ([`Options`][api-options], optional)
    — configuration

###### Returns

Extension for `mdast-util-from-markdown`
([`FromMarkdownExtension`][from-markdown-extension]).

### `frontmatterToMarkdown(options?)`

Create an extension for
[`mdast-util-to-markdown`][mdast-util-to-markdown].

###### Parameters

*   `options` ([`Options`][api-options], optional)
    — configuration

###### Returns

Extension for `mdast-util-to-markdown`
([`ToMarkdownExtension`][to-markdown-extension]).

### `Info`

Structure of marker or fence (TypeScript type).

Same as [`Info` from `micromark-extension-frontmatter`][micromark-info].

### `Matter`

Structure of matter (TypeScript type).

Same as [`Matter` from `micromark-extension-frontmatter`][micromark-matter].

### `Options`

Configuration (TypeScript type).

Same as [`Options` from `micromark-extension-frontmatter`][micromark-options].

## Syntax

See [Syntax in `micromark-extension-frontmatter`][syntax].

## Syntax tree

The following interfaces are added to **[mdast][]** by this utility.

### Nodes

> 👉 **Note**: other nodes are not enabled by default, but when passing options
> to enable them, they work the same as YAML.

#### `YAML`

```idl
interface YAML <: Literal {
  type: "yaml"
}
```

**YAML** (**[Literal][dfn-literal]**) represents a collection of metadata for
the document in the YAML data serialization language.

**YAML** can be used where **[frontmatter][dfn-frontmatter-content]** content
is expected.
Its content is represented by its `value` field.

For example, the following markdown:

```markdown
---
foo: bar
---
```

Yields:

```js
{type: 'yaml', value: 'foo: bar'}
```

### Content model

#### `FrontmatterContent`

```idl
type FrontmatterContent = YAML
```

**Frontmatter** content represent out-of-band information about the document.

If frontmatter is present, it must be limited to one node in the
*[tree][term-tree]*, and can only exist as a *[head][term-head]*.

#### `FlowContent` (frontmatter)

```idl
type FlowContentFrontmatter = FrontmatterContent | FlowContent
```

## Types

This package is fully typed with [TypeScript][].
It exports the additional types [`Info`][api-info], [`Matter`][api-matter],
and [`Options`][api-options].

The YAML node type is supported in `@types/mdast` by default.
To add other node types, register them by adding them to
`FrontmatterContentMap`:

```ts
import type {Literal} from 'mdast'

interface Toml extends Literal {
  type: 'toml'
}

declare module 'mdast' {
  interface FrontmatterContentMap {
    // Allow using TOML nodes defined by `mdast-util-frontmatter`.
    toml: Toml
  }
}
```

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`mdast-util-frontmatter@^2`, compatible with Node.js 16.

This utility works with `mdast-util-from-markdown` version 2+ and
`mdast-util-to-markdown` version 2+.

## Related

*   [`remark-frontmatter`][remark-frontmatter]
    — remark plugin to support frontmatter
*   [`micromark-extension-frontmatter`][micromark-extension-frontmatter]
    — micromark extension to parse frontmatter

## Contribute

See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
ways to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/syntax-tree/mdast-util-frontmatter/workflows/main/badge.svg

[build]: https://github.com/syntax-tree/mdast-util-frontmatter/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/mdast-util-frontmatter.svg

[coverage]: https://codecov.io/github/syntax-tree/mdast-util-frontmatter

[downloads-badge]: https://img.shields.io/npm/dm/mdast-util-frontmatter.svg

[downloads]: https://www.npmjs.com/package/mdast-util-frontmatter

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=mdast-util-frontmatter

[size]: https://bundlejs.com/?q=mdast-util-frontmatter

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/syntax-tree/unist/discussions

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[typescript]: https://www.typescriptlang.org

[license]: license

[author]: https://wooorm.com

[health]: https://github.com/syntax-tree/.github

[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md

[support]: https://github.com/syntax-tree/.github/blob/main/support.md

[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md

[mdast]: https://github.com/syntax-tree/mdast

[remark-frontmatter]: https://github.com/remarkjs/remark-frontmatter

[mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown

[mdast-util-to-markdown]: https://github.com/syntax-tree/mdast-util-to-markdown

[micromark]: https://github.com/micromark/micromark

[micromark-extension-frontmatter]: https://github.com/micromark/micromark-extension-frontmatter

[micromark-info]: https://github.com/micromark/micromark-extension-frontmatter#info

[micromark-matter]: https://github.com/micromark/micromark-extension-frontmatter#matter

[micromark-options]: https://github.com/micromark/micromark-extension-frontmatter#options

[syntax]: https://github.com/micromark/micromark-extension-frontmatter#syntax

[dfn-literal]: https://github.com/syntax-tree/mdast#literal

[term-tree]: https://github.com/syntax-tree/unist#tree

[term-head]: https://github.com/syntax-tree/unist#head

[from-markdown-extension]: https://github.com/syntax-tree/mdast-util-from-markdown#extension

[to-markdown-extension]: https://github.com/syntax-tree/mdast-util-to-markdown#options

[dfn-frontmatter-content]: #frontmattercontent

[api-frontmatter-from-markdown]: #frontmatterfrommarkdownoptions

[api-frontmatter-to-markdown]: #frontmattertomarkdownoptions

[api-info]: #info

[api-matter]: #matter

[api-options]: #options


---

# mdast-util-gfm

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[mdast][] extensions to parse and serialize [GFM][] (autolink literals,
footnotes, strikethrough, tables, tasklists).

## Contents

* [What is this?](#what-is-this)
* [When to use this](#when-to-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`gfmFromMarkdown()`](#gfmfrommarkdown)
  * [`gfmToMarkdown(options?)`](#gfmtomarkdownoptions)
  * [`Options`](#options)
* [HTML](#html)
* [Syntax](#syntax)
* [Syntax tree](#syntax-tree)
* [Types](#types)
* [Compatibility](#compatibility)
* [Related](#related)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package contains two extensions that add support for GFM syntax in
markdown to [mdast][]: autolink literals (`www.x.com`), footnotes (`[^1]`),
strikethrough (`~~stuff~~`), tables (`| cell |…`), and tasklists (`* [x]`).
These extensions plug into
[`mdast-util-from-markdown`][mdast-util-from-markdown] (to support parsing
GFM in markdown into a syntax tree) and
[`mdast-util-to-markdown`][mdast-util-to-markdown] (to support serializing
GFM in syntax trees to markdown).

## When to use this

This project is useful when you want to support the same features that GitHub
does in files in a repo, Gists, and several other places.
Users frequently believe that some of these extensions, specifically autolink
literals and tables, are part of normal markdown, so using `mdast-util-gfm` will
help match your implementation to their understanding of markdown.
There are several edge cases where GitHub’s implementation works in unexpected
ways or even different than described in their spec, so *writing* in GFM is not
always the best choice.

You can use these extensions when you are working with
`mdast-util-from-markdown` and `mdast-util-to-markdown` already.

When working with `mdast-util-from-markdown`, you must combine this package
with [`micromark-extension-gfm`][extension].

Instead of this package, you can also use the extensions separately:

* [`mdast-util-gfm-autolink-literal`](https://github.com/syntax-tree/mdast-util-gfm-autolink-literal)
  — support GFM autolink literals
* [`mdast-util-gfm-footnote`](https://github.com/syntax-tree/mdast-util-gfm-footnote)
  — support GFM footnotes
* [`mdast-util-gfm-strikethrough`](https://github.com/syntax-tree/mdast-util-gfm-strikethrough)
  — support GFM strikethrough
* [`mdast-util-gfm-table`](https://github.com/syntax-tree/mdast-util-gfm-table)
  — support GFM tables
* [`mdast-util-gfm-task-list-item`](https://github.com/syntax-tree/mdast-util-gfm-task-list-item)
  — support GFM tasklists

A different utility, [`mdast-util-frontmatter`][mdast-util-frontmatter], adds
support for frontmatter.
GitHub supports YAML frontmatter for files in repos and Gists but they don’t
treat it as part of GFM.

All these packages are used in [`remark-gfm`][remark-gfm], which
focusses on making it easier to transform content by abstracting these
internals away.

This utility does not handle how markdown is turned to HTML.
That’s done by [`mdast-util-to-hast`][mdast-util-to-hast].
If your content is not in English, you should configure that utility.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install mdast-util-gfm
```

In Deno with [`esm.sh`][esmsh]:

```js
import {gfmFromMarkdown, gfmToMarkdown} from 'https://esm.sh/mdast-util-gfm@3'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {gfmFromMarkdown, gfmToMarkdown} from 'https://esm.sh/mdast-util-gfm@3?bundle'
</script>
```

## Use

Say our document `example.md` contains:

```markdown
# GFM

## Autolink literals

www.example.com, https://example.com, and contact@example.com.

## Footnote

A note[^1]

[^1]: Big note.

## Strikethrough

~one~ or ~~two~~ tildes.

## Table

| a | b  |  c |  d  |
| - | :- | -: | :-: |

## Tasklist

* [ ] to do
* [x] done
```

…and our module `example.js` looks as follows:

```js
import fs from 'node:fs/promises'
import {fromMarkdown} from 'mdast-util-from-markdown'
import {gfmFromMarkdown, gfmToMarkdown} from 'mdast-util-gfm'
import {toMarkdown} from 'mdast-util-to-markdown'
import {gfm} from 'micromark-extension-gfm'

const value = await fs.readFile('example.md', 'utf8')

const tree = fromMarkdown(value, {
  extensions: [gfm()],
  mdastExtensions: [gfmFromMarkdown()]
})

console.log(tree)

const result = toMarkdown(tree, {extensions: [gfmToMarkdown()]})

console.log(result)
```

…now running `node example.js` yields (positional info removed for brevity):

```js
{
  type: 'root',
  children: [
    {type: 'heading', depth: 1, children: [{type: 'text', value: 'GFM'}]},
    {
      type: 'heading',
      depth: 2,
      children: [{type: 'text', value: 'Autolink literals'}]
    },
    {
      type: 'paragraph',
      children: [
        {
          type: 'link',
          title: null,
          url: 'http://www.example.com',
          children: [{type: 'text', value: 'www.example.com'}]
        },
        {type: 'text', value: ', '},
        {
          type: 'link',
          title: null,
          url: 'https://example.com',
          children: [{type: 'text', value: 'https://example.com'}]
        },
        {type: 'text', value: ', and '},
        {
          type: 'link',
          title: null,
          url: 'mailto:contact@example.com',
          children: [{type: 'text', value: 'contact@example.com'}]
        },
        {type: 'text', value: '.'}
      ]
    },
    {type: 'heading', depth: 2, children: [{type: 'text', value: 'Footnote'}]},
    {
      type: 'paragraph',
      children: [
        {type: 'text', value: 'A note'},
        {type: 'footnoteReference', identifier: '1', label: '1'}
      ]
    },
    {
      type: 'footnoteDefinition',
      identifier: '1',
      label: '1',
      children: [
        {type: 'paragraph', children: [{type: 'text', value: 'Big note.'}]}
      ]
    },
    {
      type: 'heading',
      depth: 2,
      children: [{type: 'text', value: 'Strikethrough'}]
    },
    {
      type: 'paragraph',
      children: [
        {
          type: 'delete',
          children: [{type: 'text', value: 'one'}]
        },
        {type: 'text', value: ' or '},
        {
          type: 'delete',
          children: [{type: 'text', value: 'two'}]
        },
        {type: 'text', value: ' tildes.'}
      ]
    },
    {type: 'heading', depth: 2, children: [{type: 'text', value: 'Table'}]},
    {
      type: 'table',
      align: [null, 'left', 'right', 'center'],
      children: [
        {
          type: 'tableRow',
          children: [
            {type: 'tableCell', children: [{type: 'text', value: 'a'}]},
            {type: 'tableCell', children: [{type: 'text', value: 'b'}]},
            {type: 'tableCell', children: [{type: 'text', value: 'c'}]},
            {type: 'tableCell', children: [{type: 'text', value: 'd'}]}
          ]
        }
      ]
    },
    {type: 'heading', depth: 2, children: [{type: 'text', value: 'Tasklist'}]},
    {
      type: 'list',
      ordered: false,
      start: null,
      spread: false,
      children: [
        {
          type: 'listItem',
          spread: false,
          checked: false,
          children: [
            {type: 'paragraph', children: [{type: 'text', value: 'to do'}]}
          ]
        },
        {
          type: 'listItem',
          spread: false,
          checked: true,
          children: [
            {type: 'paragraph', children: [{type: 'text', value: 'done'}]}
          ]
        }
      ]
    }
  ]
}
```

```markdown
# GFM

## Autolink literals

[www.example.com](http://www.example.com), <https://example.com>, and <contact@example.com>.

## Footnote

A note[^1]

[^1]: Big note.

## Strikethrough

~~one~~ or ~~two~~ tildes.

## Table

| a | b  |  c |  d  |
| - | :- | -: | :-: |

## Tasklist

*   [ ] to do
*   [x] done
```

## API

This package exports the identifiers [`gfmFromMarkdown`][api-gfm-from-markdown]
and [`gfmToMarkdown`][api-gfm-to-markdown].
There is no default export.

### `gfmFromMarkdown()`

Create an extension for [`mdast-util-from-markdown`][mdast-util-from-markdown]
to enable GFM (autolink literals, footnotes, strikethrough, tables, tasklists).

###### Returns

Extension for `mdast-util-from-markdown` to enable GFM
([`Array<FromMarkdownExtension>`][from-markdown-extension]).

### `gfmToMarkdown(options?)`

Create an extension for [`mdast-util-to-markdown`][mdast-util-to-markdown]
to enable GFM (autolink literals, footnotes, strikethrough, tables, tasklists).

###### Parameters

* `options` ([`Options`][api-options])
  — configuration

###### Returns

Extension for `mdast-util-to-markdown` to enable GFM
([`Array<ToMarkdownExtension>`][to-markdown-extension]).

### `Options`

Configuration (TypeScript type).

###### Fields

* `firstLineBlank` (`boolean`, default: `false`)
  — use a blank line for the first line of footnote definitions
* `stringLength` (`((value: string) => number)`, default: `s => s.length`)
  — function to detect the length of table cell content, used when aligning
  the delimiters between cells
* `tableCellPadding` (`boolean`, default: `true`)
  — whether to add a space of padding between delimiters and cells
* `tablePipeAlign` (`boolean`, default: `true`)
  — whether to align the delimiters

## HTML

This utility does not handle how markdown is turned to HTML.
That’s done by [`mdast-util-to-hast`][mdast-util-to-hast].

## Syntax

See [Syntax in `micromark-extension-gfm`][syntax].

## Syntax tree

This utility combines several mdast utilities.
See their readmes for the node types supported in the tree:

* [`mdast-util-gfm-autolink-literal`](https://github.com/syntax-tree/mdast-util-gfm-autolink-literal#syntax-tree)
  — GFM autolink literals
* [`mdast-util-gfm-footnote`](https://github.com/syntax-tree/mdast-util-gfm-footnote#syntax-tree)
  — GFM footnotes
* [`mdast-util-gfm-strikethrough`](https://github.com/syntax-tree/mdast-util-gfm-strikethrough#syntax-tree)
  — GFM strikethrough
* [`mdast-util-gfm-table`](https://github.com/syntax-tree/mdast-util-gfm-table#syntax-tree)
  — GFM tables
* [`mdast-util-gfm-task-list-item`](https://github.com/syntax-tree/mdast-util-gfm-task-list-item#syntax-tree)
  — GFM tasklists

## Types

This package is fully typed with [TypeScript][].
It exports the additional type [`Options`][api-options].

The `Delete`, `FootnoteDefinition`, `FootnoteReference`, `Table`, `TableRow`,
and `TableCell` types of the mdast nodes are exposed from `@types/mdast`.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, `mdast-util-gfm@^3`,
compatible with Node.js 16.

## Related

* [`remark-gfm`][remark-gfm]
  — remark plugin to support GFM
* [`micromark-extension-gfm`][extension]
  — micromark extension to parse GFM

## Contribute

See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
ways to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[api-gfm-from-markdown]: #gfmfrommarkdown

[api-gfm-to-markdown]: #gfmtomarkdownoptions

[api-options]: #options

[author]: https://wooorm.com

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[build]: https://github.com/syntax-tree/mdast-util-gfm/actions

[build-badge]: https://github.com/syntax-tree/mdast-util-gfm/workflows/main/badge.svg

[chat]: https://github.com/syntax-tree/unist/discussions

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md

[collective]: https://opencollective.com/unified

[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md

[coverage]: https://codecov.io/github/syntax-tree/mdast-util-gfm

[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/mdast-util-gfm.svg

[downloads]: https://www.npmjs.com/package/mdast-util-gfm

[downloads-badge]: https://img.shields.io/npm/dm/mdast-util-gfm.svg

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[extension]: https://github.com/micromark/micromark-extension-gfm

[from-markdown-extension]: https://github.com/syntax-tree/mdast-util-from-markdown#extension

[gfm]: https://github.github.com/gfm/

[health]: https://github.com/syntax-tree/.github

[license]: license

[mdast]: https://github.com/syntax-tree/mdast

[mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown

[mdast-util-frontmatter]: https://github.com/syntax-tree/mdast-util-frontmatter

[mdast-util-to-hast]: https://github.com/syntax-tree/mdast-util-to-hast

[mdast-util-to-markdown]: https://github.com/syntax-tree/mdast-util-to-markdown

[npm]: https://docs.npmjs.com/cli/install

[remark-gfm]: https://github.com/remarkjs/remark-gfm

[size]: https://bundlejs.com/?q=mdast-util-gfm

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=mdast-util-gfm

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[support]: https://github.com/syntax-tree/.github/blob/main/support.md

[syntax]: https://github.com/micromark/micromark-extension-gfm#syntax

[to-markdown-extension]: https://github.com/syntax-tree/mdast-util-to-markdown#options

[typescript]: https://www.typescriptlang.org


---

# micromark-util-character

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility to handle [character codes][code].

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`asciiAlpha(code)`](#asciialphacode)
  * [`asciiAlphanumeric(code)`](#asciialphanumericcode)
  * [`asciiAtext(code)`](#asciiatextcode)
  * [`asciiControl(code)`](#asciicontrolcode)
  * [`asciiDigit(code)`](#asciidigitcode)
  * [`asciiHexDigit(code)`](#asciihexdigitcode)
  * [`asciiPunctuation(code)`](#asciipunctuationcode)
  * [`markdownLineEnding(code)`](#markdownlineendingcode)
  * [`markdownLineEndingOrSpace(code)`](#markdownlineendingorspacecode)
  * [`markdownSpace(code)`](#markdownspacecode)
  * [`unicodePunctuation(code)`](#unicodepunctuationcode)
  * [`unicodeWhitespace(code)`](#unicodewhitespacecode)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes algorithms to check whether characters match groups.

## When should I use this?

This package might be useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-character
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as character from 'https://esm.sh/micromark-util-character@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as character from 'https://esm.sh/micromark-util-character@1?bundle'
</script>
```

## Use

```js
import {asciiAlpha} from 'micromark-util-character'

console.log(asciiAlpha(64)) // false
console.log(asciiAlpha(65)) // true
```

## API

This module exports the identifiers
[`asciiAlpha`][api-ascii-alpha],
[`asciiAlphanumeric`][api-ascii-alphanumeric],
[`asciiAtext`][api-ascii-atext],
[`asciiControl`][api-ascii-control],
[`asciiDigit`][api-ascii-digit],
[`asciiHexDigit`][api-ascii-hex-digit],
[`asciiPunctuation`][api-ascii-punctuation],
[`markdownLineEnding`][api-markdown-line-ending],
[`markdownLineEndingOrSpace`][api-markdown-line-ending-or-space],
[`markdownSpace`][api-markdown-space],
[`unicodePunctuation`][api-unicode-punctuation],
[`unicodeWhitespace`][api-unicode-whitespace].
There is no default export.

### `asciiAlpha(code)`

Check whether the [character code][code] represents an ASCII alpha (`a` through
`z`, case insensitive).

An **ASCII alpha** is an ASCII upper alpha or ASCII lower alpha.

An **ASCII upper alpha** is a character in the inclusive range U+0041 (`A`)
to U+005A (`Z`).

An **ASCII lower alpha** is a character in the inclusive range U+0061 (`a`)
to U+007A (`z`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiAlphanumeric(code)`

Check whether the [character code][code] represents an ASCII alphanumeric (`a`
through `z`, case insensitive, or `0` through `9`).

An **ASCII alphanumeric** is an ASCII digit (see `asciiDigit`) or ASCII alpha
(see `asciiAlpha`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiAtext(code)`

Check whether the [character code][code] represents an ASCII atext.

atext is an ASCII alphanumeric (see `asciiAlphanumeric`), or a character in
the inclusive ranges U+0023 NUMBER SIGN (`#`) to U+0027 APOSTROPHE (`'`),
U+002A ASTERISK (`*`), U+002B PLUS SIGN (`+`), U+002D DASH (`-`), U+002F
SLASH (`/`), U+003D EQUALS TO (`=`), U+003F QUESTION MARK (`?`), U+005E
CARET (`^`) to U+0060 GRAVE ACCENT (`` ` ``), or U+007B LEFT CURLY BRACE
(`{`) to U+007E TILDE (`~`) (**\[RFC5322]**).

See **\[RFC5322]**:\
[Internet Message Format](https://tools.ietf.org/html/rfc5322).\
P. Resnick.\
IETF.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiControl(code)`

Check whether a [character code][code] is an ASCII control character.

An **ASCII control** is a character in the inclusive range U+0000 NULL (NUL)
to U+001F (US), or U+007F (DEL).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiDigit(code)`

Check whether the [character code][code] represents an ASCII digit (`0` through
`9`).

An **ASCII digit** is a character in the inclusive range U+0030 (`0`) to
U+0039 (`9`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiHexDigit(code)`

Check whether the [character code][code] represents an ASCII hex digit (`a`
through `f`, case insensitive, or `0` through `9`).

An **ASCII hex digit** is an ASCII digit (see `asciiDigit`), ASCII upper hex
digit, or an ASCII lower hex digit.

An **ASCII upper hex digit** is a character in the inclusive range U+0041
(`A`) to U+0046 (`F`).

An **ASCII lower hex digit** is a character in the inclusive range U+0061
(`a`) to U+0066 (`f`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiPunctuation(code)`

Check whether the [character code][code] represents ASCII punctuation.

An **ASCII punctuation** is a character in the inclusive ranges U+0021
EXCLAMATION MARK (`!`) to U+002F SLASH (`/`), U+003A COLON (`:`) to U+0040 AT
SIGN (`@`), U+005B LEFT SQUARE BRACKET (`[`) to U+0060 GRAVE ACCENT
(`` ` ``), or U+007B LEFT CURLY BRACE (`{`) to U+007E TILDE (`~`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownLineEnding(code)`

Check whether a [character code][code] is a markdown line ending.

A **markdown line ending** is the virtual characters M-0003 CARRIAGE RETURN
LINE FEED (CRLF), M-0004 LINE FEED (LF) and M-0005 CARRIAGE RETURN (CR).

In micromark, the actual character U+000A LINE FEED (LF) and U+000D CARRIAGE
RETURN (CR) are replaced by these virtual characters depending on whether
they occurred together.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownLineEndingOrSpace(code)`

Check whether a [character code][code] is a markdown line ending (see
`markdownLineEnding`) or markdown space (see `markdownSpace`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownSpace(code)`

Check whether a [character code][code] is a markdown space.

A **markdown space** is the concrete character U+0020 SPACE (SP) and the
virtual characters M-0001 VIRTUAL SPACE (VS) and M-0002 HORIZONTAL TAB (HT).

In micromark, the actual character U+0009 CHARACTER TABULATION (HT) is
replaced by one M-0002 HORIZONTAL TAB (HT) and between 0 and 3 M-0001 VIRTUAL
SPACE (VS) characters, depending on the column at which the tab occurred.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `unicodePunctuation(code)`

Check whether the [character code][code] represents Unicode punctuation.

A **Unicode punctuation** is a character in the Unicode `Pc` (Punctuation,
Connector), `Pd` (Punctuation, Dash), `Pe` (Punctuation, Close), `Pf`
(Punctuation, Final quote), `Pi` (Punctuation, Initial quote), `Po`
(Punctuation, Other), or `Ps` (Punctuation, Open) categories, or an ASCII
punctuation (see `asciiPunctuation`) (**\[UNICODE]**).

See **\[UNICODE]**:\
[The Unicode Standard](https://www.unicode.org/versions/).\
Unicode Consortium.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `unicodeWhitespace(code)`

Check whether the [character code][code] represents Unicode whitespace.

Note that this does handle micromark specific markdown whitespace characters.
See `markdownLineEndingOrSpace` to check that.

A **Unicode whitespace** is a character in the Unicode `Zs` (Separator,
Space) category, or U+0009 CHARACTER TABULATION (HT), U+000A LINE FEED (LF),
U+000C (FF), or U+000D CARRIAGE RETURN (CR) (**\[UNICODE]**).

See **\[UNICODE]**:\
[The Unicode Standard](https://www.unicode.org/versions/).\
Unicode Consortium.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-character@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-character.svg

[downloads]: https://www.npmjs.com/package/micromark-util-character

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-character

[bundle-size]: https://bundlejs.com/?q=micromark-util-character

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[code]: https://github.com/micromark/micromark#preprocess

[api-ascii-alpha]: #asciialphacode

[api-ascii-alphanumeric]: #asciialphanumericcode

[api-ascii-atext]: #asciiatextcode

[api-ascii-control]: #asciicontrolcode

[api-ascii-digit]: #asciidigitcode

[api-ascii-hex-digit]: #asciihexdigitcode

[api-ascii-punctuation]: #asciipunctuationcode

[api-markdown-line-ending]: #markdownlineendingcode

[api-markdown-line-ending-or-space]: #markdownlineendingorspacecode

[api-markdown-space]: #markdownspacecode

[api-unicode-punctuation]: #unicodepunctuationcode

[api-unicode-whitespace]: #unicodewhitespacecode


---

# micromark-util-symbol

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility with symbols.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes constants used throughout the micromark ecosystem.

## When should I use this?

This package is useful when you are making your own micromark extensions.
It’s useful to reference these constants by name instead of value while
developing.
[`micromark-build`][micromark-build] compiles them away for production code.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-symbol
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as symbol from 'https://esm.sh/micromark-util-symbol@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as symbol from 'https://esm.sh/micromark-util-symbol@1?bundle'
</script>
```

## Use

```js
import {codes, constants, types, values} from 'micromark-util-symbol'

console.log(codes.atSign) // 64
console.log(constants.characterReferenceNamedSizeMax) // 31
console.log(types.definitionDestinationRaw) // 'definitionDestinationRaw'
console.log(values.atSign) // '@'
```

## API

This package exports the identifiers `codes`, `constants`, `types`, and
`values`.
There is no default export.

Each identifier is an object mapping strings to values.
See the code for the exposed data.

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-symbol@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-symbol.svg

[downloads]: https://www.npmjs.com/package/micromark-util-symbol

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-symbol

[bundle-size]: https://bundlejs.com/?q=micromark-util-symbol

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[micromark-build]: https://github.com/micromark/micromark/tree/main/packages/micromark-build


---

# mdast-util-gfm-autolink-literal

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[mdast][] extensions to parse and serialize [GFM][] autolink literals.

## Contents

* [What is this?](#what-is-this)
* [When to use this](#when-to-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`gfmAutolinkLiteralFromMarkdown()`](#gfmautolinkliteralfrommarkdown)
  * [`gfmAutolinkLiteralToMarkdown()`](#gfmautolinkliteraltomarkdown)
* [HTML](#html)
* [Syntax](#syntax)
* [Syntax tree](#syntax-tree)
* [Types](#types)
* [Compatibility](#compatibility)
* [Related](#related)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package contains two extensions that add support for GFM autolink literals
syntax in markdown to [mdast][].
These extensions plug into
[`mdast-util-from-markdown`][mdast-util-from-markdown] (to support parsing
GFM autolinks in markdown into a syntax tree) and
[`mdast-util-to-markdown`][mdast-util-to-markdown] (to support serializing
GFM autolinks in syntax trees to markdown).

GitHub employs different algorithms to autolink: one at parse time and one at
transform time (similar to how `@mentions` are done at transform time).
This difference can be observed because character references and escapes are
handled differently.
But also because issues/PRs/comments omit (perhaps by accident?) the second
algorithm for `www.`, `http://`, and `https://` links (but not for email links).

As the corresponding micromark extension
[`micromark-extension-gfm-autolink-literal`][extension] is a syntax extension,
it can only perform the first algorithm.
The tree extension `gfmAutolinkLiteralFromMarkdown` from this package can
perform the second algorithm, and as they are combined, both are done.

## When to use this

You can use these extensions when you are working with
`mdast-util-from-markdown` and `mdast-util-to-markdown` already.

When working with `mdast-util-from-markdown`, you must combine this package
with
[`micromark-extension-gfm-autolink-literal`][extension].

When you don’t need a syntax tree, you can use [`micromark`][micromark]
directly with `micromark-extension-gfm-autolink-literal`.

When you are working with syntax trees and want all of GFM, use
[`mdast-util-gfm`][mdast-util-gfm] instead.

All these packages are used [`remark-gfm`][remark-gfm], which
focusses on making it easier to transform content by abstracting these
internals away.

This utility does not handle how markdown is turned to HTML.
That’s done by [`mdast-util-to-hast`][mdast-util-to-hast].

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install mdast-util-gfm-autolink-literal
```

In Deno with [`esm.sh`][esmsh]:

```js
import {gfmAutolinkLiteralFromMarkdown, gfmAutolinkLiteralToMarkdown} from 'https://esm.sh/mdast-util-gfm-autolink-literal@2'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {gfmAutolinkLiteralFromMarkdown, gfmAutolinkLiteralToMarkdown} from 'https://esm.sh/mdast-util-gfm-autolink-literal@2?bundle'
</script>
```

## Use

Say our document `example.md` contains:

```markdown
www.example.com, https://example.com, and contact@example.com.
```

…and our module `example.js` looks as follows:

```js
import fs from 'node:fs/promises'
import {gfmAutolinkLiteral} from 'micromark-extension-gfm-autolink-literal'
import {fromMarkdown} from 'mdast-util-from-markdown'
import {
  gfmAutolinkLiteralFromMarkdown,
  gfmAutolinkLiteralToMarkdown
} from 'mdast-util-gfm-autolink-literal'
import {toMarkdown} from 'mdast-util-to-markdown'

const doc = await fs.readFile('example.md')

const tree = fromMarkdown(doc, {
  extensions: [gfmAutolinkLiteral()],
  mdastExtensions: [gfmAutolinkLiteralFromMarkdown()]
})

console.log(tree)

const out = toMarkdown(tree, {extensions: [gfmAutolinkLiteralToMarkdown()]})

console.log(out)
```

…now running `node example.js` yields (positional info removed for brevity):

```js
{
  type: 'root',
  children: [
    {
      type: 'paragraph',
      children: [
        {
          type: 'link',
          title: null,
          url: 'http://www.example.com',
          children: [{type: 'text', value: 'www.example.com'}]
        },
        {type: 'text', value: ', '},
        {
          type: 'link',
          title: null,
          url: 'https://example.com',
          children: [{type: 'text', value: 'https://example.com'}]
        },
        {type: 'text', value: ', and '},
        {
          type: 'link',
          title: null,
          url: 'mailto:contact@example.com',
          children: [{type: 'text', value: 'contact@example.com'}]
        },
        {type: 'text', value: '.'}
      ]
    }
  ]
}
```

```markdown
[www.example.com](http://www.example.com), <https://example.com>, and <contact@example.com>.
```

## API

This package exports the identifiers
[`gfmAutolinkLiteralFromMarkdown`][api-gfm-autolink-literal-from-markdown] and
[`gfmAutolinkLiteralToMarkdown`][api-gfm-autolink-literal-to-markdown].
There is no default export.

### `gfmAutolinkLiteralFromMarkdown()`

Create an extension for [`mdast-util-from-markdown`][mdast-util-from-markdown]
to enable GFM autolink literals in markdown.

###### Returns

Extension for `mdast-util-to-markdown` to enable GFM autolink literals
([`FromMarkdownExtension`][from-markdown-extension]).

### `gfmAutolinkLiteralToMarkdown()`

Create an extension for [`mdast-util-to-markdown`][mdast-util-to-markdown] to
enable GFM autolink literals in markdown.

###### Returns

Extension for `mdast-util-to-markdown` to enable GFM autolink literals
([`ToMarkdownExtension`][to-markdown-extension]).

## HTML

This utility does not handle how markdown is turned to HTML.
That’s done by [`mdast-util-to-hast`][mdast-util-to-hast].

## Syntax

See [Syntax in `micromark-extension-gfm-autolink-literal`][syntax].

## Syntax tree

There are no interfaces added to **[mdast][]** by this utility, as it reuses
the existing **[Link][dfn-link]** interface.

## Types

This package is fully typed with [TypeScript][].
It does not export additional types.

The `Link` type of the mdast nodes is exposed from `@types/mdast`.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`mdast-util-gfm-autolink-literal@^2`, compatible with Node.js 16.

This utility works with `mdast-util-from-markdown` version 2+ and
`mdast-util-to-markdown` version 2+.

## Related

* [`remarkjs/remark-gfm`][remark-gfm]
  — remark plugin to support GFM
* [`syntax-tree/mdast-util-gfm`][mdast-util-gfm]
  — same but all of GFM (autolink literals, footnotes, strikethrough, tables,
  tasklists)
* [`micromark/micromark-extension-gfm-autolink-literal`][extension]
  — micromark extension to parse GFM autolink literals

## Contribute

See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
ways to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/syntax-tree/mdast-util-gfm-autolink-literal/workflows/main/badge.svg

[build]: https://github.com/syntax-tree/mdast-util-gfm-autolink-literal/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/mdast-util-gfm-autolink-literal.svg

[coverage]: https://codecov.io/github/syntax-tree/mdast-util-gfm-autolink-literal

[downloads-badge]: https://img.shields.io/npm/dm/mdast-util-gfm-autolink-literal.svg

[downloads]: https://www.npmjs.com/package/mdast-util-gfm-autolink-literal

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=mdast-util-gfm-autolink-literal

[size]: https://bundlejs.com/?q=mdast-util-gfm-autolink-literal

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/syntax-tree/unist/discussions

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[typescript]: https://www.typescriptlang.org

[license]: license

[author]: https://wooorm.com

[health]: https://github.com/syntax-tree/.github

[contributing]: https://github.com/syntax-tree/.github/blob/HEAD/contributing.md

[support]: https://github.com/syntax-tree/.github/blob/HEAD/support.md

[coc]: https://github.com/syntax-tree/.github/blob/HEAD/code-of-conduct.md

[mdast]: https://github.com/syntax-tree/mdast

[mdast-util-gfm]: https://github.com/syntax-tree/mdast-util-gfm

[mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown

[mdast-util-to-markdown]: https://github.com/syntax-tree/mdast-util-to-markdown

[mdast-util-to-hast]: https://github.com/syntax-tree/mdast-util-to-hast

[remark-gfm]: https://github.com/remarkjs/remark-gfm

[micromark]: https://github.com/micromark/micromark

[extension]: https://github.com/micromark/micromark-extension-gfm-autolink-literal

[syntax]: https://github.com/micromark/micromark-extension-gfm-autolink-literal#syntax

[gfm]: https://github.github.com/gfm/

[dfn-link]: https://github.com/syntax-tree/mdast#link

[from-markdown-extension]: https://github.com/syntax-tree/mdast-util-from-markdown#extension

[to-markdown-extension]: https://github.com/syntax-tree/mdast-util-to-markdown#options

[api-gfm-autolink-literal-from-markdown]: #gfmautolinkliteralfrommarkdown

[api-gfm-autolink-literal-to-markdown]: #gfmautolinkliteraltomarkdown


---

# mdast-util-gfm-footnote

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[mdast][] extensions to parse and serialize [GFM][] footnotes.

## Contents

* [What is this?](#what-is-this)
* [When to use this](#when-to-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`gfmFootnoteFromMarkdown()`](#gfmfootnotefrommarkdown)
  * [`gfmFootnoteToMarkdown(options?)`](#gfmfootnotetomarkdownoptions)
  * [`ToMarkdownOptions`](#tomarkdownoptions)
* [HTML](#html)
* [Syntax](#syntax)
* [Syntax tree](#syntax-tree)
  * [Nodes](#nodes)
  * [Content model](#content-model)
* [Types](#types)
* [Compatibility](#compatibility)
* [Related](#related)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package contains two extensions that add support for GFM footnote syntax
in markdown to [mdast][].
These extensions plug into
[`mdast-util-from-markdown`][mdast-util-from-markdown] (to support parsing
footnotes in markdown into a syntax tree) and
[`mdast-util-to-markdown`][mdast-util-to-markdown] (to support serializing
footnotes in syntax trees to markdown).

GFM footnotes were [announced September 30, 2021][post] but are not specified.
Their implementation on github.com is currently buggy.
The bugs have been reported on [`cmark-gfm`][cmark-gfm].

## When to use this

You can use these extensions when you are working with
`mdast-util-from-markdown` and `mdast-util-to-markdown` already.

When working with `mdast-util-from-markdown`, you must combine this package
with [`micromark-extension-gfm-footnote`][micromark-extension-gfm-footnote].

When you don’t need a syntax tree, you can use [`micromark`][micromark]
directly with `micromark-extension-gfm-footnote`.

When you are working with syntax trees and want all of GFM, use
[`mdast-util-gfm`][mdast-util-gfm] instead.

All these packages are used [`remark-gfm`][remark-gfm], which
focusses on making it easier to transform content by abstracting these
internals away.

This utility does not handle how markdown is turned to HTML.
That’s done by [`mdast-util-to-hast`][mdast-util-to-hast].
If your content is not in English, you should configure that utility.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install mdast-util-gfm-footnote
```

In Deno with [`esm.sh`][esmsh]:

```js
import {gfmFootnoteFromMarkdown, gfmFootnoteToMarkdown} from 'https://esm.sh/mdast-util-gfm-footnote@2'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {gfmFootnoteFromMarkdown, gfmFootnoteToMarkdown} from 'https://esm.sh/mdast-util-gfm-footnote@2?bundle'
</script>
```

## Use

Say our document `example.md` contains:

```markdown
In the Solar System, Mercury[^mercury] and Venus[^venus] have very small tilts.

[^mercury]:
    **Mercury** is the first planet from the Sun and the smallest
    in the Solar System.

[^venus]:
    **Venus** is the second planet from
    the Sun.
```

…and our module `example.js` looks as follows:

```js
import fs from 'node:fs/promises'
import {fromMarkdown} from 'mdast-util-from-markdown'
import {
  gfmFootnoteFromMarkdown,
  gfmFootnoteToMarkdown
} from 'mdast-util-gfm-footnote'
import {toMarkdown} from 'mdast-util-to-markdown'
import {gfmFootnote} from 'micromark-extension-gfm-footnote'

const value = await fs.readFile('example.md', 'utf8')

const tree = fromMarkdown(value, {
  extensions: [gfmFootnote()],
  mdastExtensions: [gfmFootnoteFromMarkdown()]
})

console.log(tree)

const result = toMarkdown(tree, {
  extensions: [gfmFootnoteToMarkdown({firstLineBlank: true})]
})

console.log(result)
```

…now running `node example.js` yields (positional info removed for brevity):

```js
{
  type: 'root',
  children: [
    {
      type: 'paragraph',
      children: [
        {type: 'text', value: 'In the Solar System, Mercury'},
        {type: 'footnoteReference', identifier: 'mercury', label: 'mercury'},
        {type: 'text', value: ' and Venus'},
        {type: 'footnoteReference', identifier: 'venus', label: 'venus'},
        {type: 'text', value: ' have very small tilts.'}
      ]
    },
    {
      type: 'footnoteDefinition',
      identifier: 'mercury',
      label: 'mercury',
      children: [
        {
          type: 'paragraph',
          children: [
            {type: 'strong', children: [{type: 'text', value: 'Mercury'}]},
            {
              type: 'text',
              value:
                ' is the first planet from the Sun and the smallest\n' +
                'in the Solar System.'
            }
          ]
        }
      ]
    },
    {
      type: 'footnoteDefinition',
      identifier: 'venus',
      label: 'venus',
      children: [
        {
          type: 'paragraph',
          children: [
            {type: 'strong', children: [{type: 'text', value: 'Venus'}]},
            {type: 'text', value: ' is the second planet from\nthe Sun.'}
          ]
        }
      ]
    }
  ]
}
```

```markdown
In the Solar System, Mercury[^mercury] and Venus[^venus] have very small tilts.

[^mercury]:
    **Mercury** is the first planet from the Sun and the smallest
    in the Solar System.

[^venus]:
    **Venus** is the second planet from
    the Sun.
```

## API

This package exports the identifiers
[`gfmFootnoteFromMarkdown`][api-gfmfootnotefrommarkdown] and
[`gfmFootnoteToMarkdown`][api-gfmfootnotetomarkdown].
There is no default export.
It exports the type [`ToMarkdownOptions`][api-to-markdown-options].

### `gfmFootnoteFromMarkdown()`

Create an extension for
[`mdast-util-from-markdown`][mdast-util-from-markdown]
to enable GFM footnotes in markdown.

###### Returns

Extension for `mdast-util-from-markdown`
([`FromMarkdownExtension`][frommarkdownextension]).

### `gfmFootnoteToMarkdown(options?)`

Create an extension for
[`mdast-util-to-markdown`][mdast-util-to-markdown]
to enable GFM footnotes in markdown.

###### Parameters

* `options` ([`ToMarkdownOptions`][api-to-markdown-options], optional)
  — configuration

###### Returns

Extension for `mdast-util-to-markdown`
([`ToMarkdownExtension`][tomarkdownextension]).

### `ToMarkdownOptions`

Configuration (TypeScript type).

###### Fields

* `firstLineBlank` (`boolean`, default: `false`)
  — use a blank line for the first line of footnote definitions

## HTML

This utility does not handle how markdown is turned to HTML.
That’s done by [`mdast-util-to-hast`][mdast-util-to-hast].
If your content is not in English, you should configure that utility.

## Syntax

See [Syntax in `micromark-extension-gfm-footnote`][syntax].

## Syntax tree

The following interfaces are added to **[mdast][]** by this utility.

### Nodes

#### `FootnoteDefinition`

```idl
interface FootnoteDefinition <: Parent {
  type: 'footnoteDefinition'
  children: [FlowContent]
}

FootnoteDefinition includes Association
```

**FootnoteDefinition** (**[Parent][dfn-parent]**) represents content relating
to the document that is outside its flow.

**FootnoteDefinition** can be used where **[flow][dfn-flow-content]** content
is expected.
Its content model is also **[flow][dfn-flow-content]** content.

**FootnoteDefinition** includes the mixin
**[Association][dfn-mxn-association]**.

**FootnoteDefinition** should be associated with
**[FootnoteReferences][dfn-footnote-reference]**.

For example, the following markdown:

```markdown
[^alpha]: bravo and charlie.
```

Yields:

```js
{
  type: 'footnoteDefinition',
  identifier: 'alpha',
  label: 'alpha',
  children: [{
    type: 'paragraph',
    children: [{type: 'text', value: 'bravo and charlie.'}]
  }]
}
```

#### `FootnoteReference`

```idl
interface FootnoteReference <: Node {
  type: 'footnoteReference'
}

FootnoteReference includes Association
```

**FootnoteReference** (**[Node][dfn-node]**) represents a marker through
association.

**FootnoteReference** can be used where
**[phrasing][dfn-phrasing-content]** content is expected.
It has no content model.

**FootnoteReference** includes the mixin **[Association][dfn-mxn-association]**.

**FootnoteReference** should be associated with a
**[FootnoteDefinition][dfn-footnote-definition]**.

For example, the following markdown:

```markdown
[^alpha]
```

Yields:

```js
{
  type: 'footnoteReference',
  identifier: 'alpha',
  label: 'alpha'
}
```

### Content model

#### `FlowContent` (GFM footnotes)

```idl
type FlowContentGfm = FootnoteDefinition | FlowContent
```

#### `PhrasingContent` (GFM footnotes)

```idl
type PhrasingContentGfm = FootnoteReference | PhrasingContent
```

## Types

This package is fully typed with [TypeScript][].
It does not export additional types.

The `FootnoteDefinition` and `FootnoteReference` types of the mdast nodes are
exposed from `@types/mdast`.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`mdast-util-gfm-footnote@^2`, compatible with Node.js 16.

## Related

* [`remark-gfm`][remark-gfm]
  — remark plugin to support GFM
* [`mdast-util-gfm`][mdast-util-gfm]
  — same but all of GFM (autolink literals, footnotes, strikethrough, tables,
  tasklists)
* [`micromark-extension-gfm-footnote`][micromark-extension-gfm-footnote]
  — micromark extension to parse GFM footnotes

## Contribute

See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
ways to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[api-gfmfootnotefrommarkdown]: #gfmfootnotefrommarkdown

[api-gfmfootnotetomarkdown]: #gfmfootnotetomarkdownoptions

[api-to-markdown-options]: #tomarkdownoptions

[author]: https://wooorm.com

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[build]: https://github.com/syntax-tree/mdast-util-gfm-footnote/actions

[build-badge]: https://github.com/syntax-tree/mdast-util-gfm-footnote/workflows/main/badge.svg

[chat]: https://github.com/syntax-tree/unist/discussions

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[cmark-gfm]: https://github.com/github/cmark-gfm

[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md

[collective]: https://opencollective.com/unified

[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md

[coverage]: https://codecov.io/github/syntax-tree/mdast-util-gfm-footnote

[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/mdast-util-gfm-footnote.svg

[dfn-flow-content]: #flowcontent-gfm-footnotes

[dfn-footnote-definition]: #footnotedefinition

[dfn-footnote-reference]: #footnotereference

[dfn-mxn-association]: https://github.com/syntax-tree/mdast#association

[dfn-node]: https://github.com/syntax-tree/unist#node

[dfn-parent]: https://github.com/syntax-tree/mdast#parent

[dfn-phrasing-content]: #phrasingcontent-gfm-footnotes

[downloads]: https://www.npmjs.com/package/mdast-util-gfm-footnote

[downloads-badge]: https://img.shields.io/npm/dm/mdast-util-gfm-footnote.svg

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[frommarkdownextension]: https://github.com/syntax-tree/mdast-util-from-markdown#extension

[gfm]: https://github.github.com/gfm/

[health]: https://github.com/syntax-tree/.github

[license]: license

[mdast]: https://github.com/syntax-tree/mdast

[mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown

[mdast-util-gfm]: https://github.com/syntax-tree/mdast-util-gfm

[mdast-util-to-hast]: https://github.com/syntax-tree/mdast-util-to-hast

[mdast-util-to-markdown]: https://github.com/syntax-tree/mdast-util-to-markdown

[micromark]: https://github.com/micromark/micromark

[micromark-extension-gfm-footnote]: https://github.com/micromark/micromark-extension-gfm-footnote

[npm]: https://docs.npmjs.com/cli/install

[post]: https://github.blog/changelog/2021-09-30-footnotes-now-supported-in-markdown-fields/

[remark-gfm]: https://github.com/remarkjs/remark-gfm

[size]: https://bundlejs.com/?q=mdast-util-gfm-footnote

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=mdast-util-gfm-footnote

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[support]: https://github.com/syntax-tree/.github/blob/main/support.md

[syntax]: https://github.com/micromark/micromark-extension-gfm-footnote#syntax

[tomarkdownextension]: https://github.com/syntax-tree/mdast-util-to-markdown#options

[typescript]: https://www.typescriptlang.org


---

# mdast-util-gfm-strikethrough

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[mdast][] extensions to parse and serialize [GFM][] strikethrough.

## Contents

*   [What is this?](#what-is-this)
*   [When to use this](#when-to-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`gfmStrikethroughFromMarkdown()`](#gfmstrikethroughfrommarkdown)
    *   [`gfmStrikethroughToMarkdown()`](#gfmstrikethroughtomarkdown)
*   [HTML](#html)
*   [Syntax](#syntax)
*   [Syntax tree](#syntax-tree)
    *   [Nodes](#nodes)
    *   [Content model](#content-model)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package contains two extensions that add support for GFM strikethrough
syntax in markdown to [mdast][].
These extensions plug into
[`mdast-util-from-markdown`][mdast-util-from-markdown] (to support parsing
strikethrough in markdown into a syntax tree) and
[`mdast-util-to-markdown`][mdast-util-to-markdown] (to support serializing
strikethrough in syntax trees to markdown).

## When to use this

You can use these extensions when you are working with
`mdast-util-from-markdown` and `mdast-util-to-markdown` already.

When working with `mdast-util-from-markdown`, you must combine this package
with [`micromark-extension-gfm-strikethrough`][extension].

When you don’t need a syntax tree, you can use [`micromark`][micromark]
directly with `micromark-extension-gfm-strikethrough`.

When you are working with syntax trees and want all of GFM, use
[`mdast-util-gfm`][mdast-util-gfm] instead.

All these packages are used [`remark-gfm`][remark-gfm], which
focusses on making it easier to transform content by abstracting these
internals away.

This utility does not handle how markdown is turned to HTML.
That’s done by [`mdast-util-to-hast`][mdast-util-to-hast].
If you want a different element, you should configure that utility.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install mdast-util-gfm-strikethrough
```

In Deno with [`esm.sh`][esmsh]:

```js
import {gfmStrikethroughFromMarkdown, gfmStrikethroughToMarkdown} from 'https://esm.sh/mdast-util-gfm-strikethrough@2'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {gfmStrikethroughFromMarkdown, gfmStrikethroughToMarkdown} from 'https://esm.sh/mdast-util-gfm-strikethrough@2?bundle'
</script>
```

## Use

Say our document `example.md` contains:

```markdown
*Emphasis*, **importance**, and ~~strikethrough~~.
```

…and our module `example.js` looks as follows:

```js
import fs from 'node:fs/promises'
import {gfmStrikethrough} from 'micromark-extension-gfm-strikethrough'
import {fromMarkdown} from 'mdast-util-from-markdown'
import {gfmStrikethroughFromMarkdown, gfmStrikethroughToMarkdown} from 'mdast-util-gfm-strikethrough'
import {toMarkdown} from 'mdast-util-to-markdown'

const doc = await fs.readFile('example.md')

const tree = fromMarkdown(doc, {
  extensions: [gfmStrikethrough()],
  mdastExtensions: [gfmStrikethroughFromMarkdown()]
})

console.log(tree)

const out = toMarkdown(tree, {extensions: [gfmStrikethroughToMarkdown()]})

console.log(out)
```

Now, running `node example` yields:

```js
{
  type: 'root',
  children: [
    {
      type: 'paragraph',
      children: [
        {type: 'emphasis', children: [{type: 'text', value: 'Emphasis'}]},
        {type: 'text', value: ', '},
        {type: 'strong', children: [{type: 'text', value: 'importance'}]},
        {type: 'text', value: ', and '},
        {type: 'delete', children: [{type: 'text', value: 'strikethrough'}]},
        {type: 'text', value: '.'}
      ]
    }
  ]
}
```

```markdown
*Emphasis*, **importance**, and ~~strikethrough~~.
```

## API

This package exports the identifiers
[`gfmStrikethroughFromMarkdown`][api-gfm-strikethrough-from-markdown] and
[`gfmStrikethroughToMarkdown`][api-gfm-strikethrough-to-markdown].
There is no default export.

### `gfmStrikethroughFromMarkdown()`

Create an extension for [`mdast-util-from-markdown`][mdast-util-from-markdown]
to enable GFM strikethrough in markdown.

###### Returns

Extension for `mdast-util-from-markdown` to enable GFM strikethrough
([`FromMarkdownExtension`][from-markdown-extension]).

### `gfmStrikethroughToMarkdown()`

Create an extension for [`mdast-util-to-markdown`][mdast-util-to-markdown] to
enable GFM strikethrough in markdown.

###### Returns

Extension for `mdast-util-to-markdown` to enable GFM strikethrough
([`ToMarkdownExtension`][to-markdown-extension]).

## HTML

This utility does not handle how markdown is turned to HTML.
That’s done by [`mdast-util-to-hast`][mdast-util-to-hast].
If you want a different element, you should configure that utility.

## Syntax

See [Syntax in `micromark-extension-gfm-strikethrough`][syntax].

## Syntax tree

The following interfaces are added to **[mdast][]** by this utility.

### Nodes

#### `Delete`

```idl
interface Delete <: Parent {
  type: 'delete'
  children: [TransparentContent]
}
```

**Delete** (**[Parent][dfn-parent]**) represents contents that are no longer
accurate or no longer relevant.

**Delete** can be used where **[phrasing][dfn-phrasing-content]**
content is expected.
Its content model is **[transparent][dfn-transparent-content]** content.

For example, the following markdown:

```markdown
~~alpha~~
```

Yields:

```js
{
  type: 'delete',
  children: [{type: 'text', value: 'alpha'}]
}
```

### Content model

#### `PhrasingContent` (GFM strikethrough)

```idl
type PhrasingContentGfm = Delete | PhrasingContent
```

## Types

This package is fully typed with [TypeScript][].
It does not export additional types.

The `Delete` type of the mdast node is exposed from `@types/mdast`.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`mdast-util-gfm-strikethrough@^2`, compatible with Node.js 16.

This utility works with `mdast-util-from-markdown` version 2+ and
`mdast-util-to-markdown` version 2+.

## Related

*   [`remarkjs/remark-gfm`][remark-gfm]
    — remark plugin to support GFM
*   [`syntax-tree/mdast-util-gfm`][mdast-util-gfm]
    — same but all of GFM (autolink literals, footnotes, strikethrough, tables,
    tasklists)
*   [`micromark/micromark-extension-gfm-strikethrough`][extension]
    — micromark extension to parse GFM strikethrough

## Contribute

See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
ways to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/syntax-tree/mdast-util-gfm-strikethrough/workflows/main/badge.svg

[build]: https://github.com/syntax-tree/mdast-util-gfm-strikethrough/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/mdast-util-gfm-strikethrough.svg

[coverage]: https://codecov.io/github/syntax-tree/mdast-util-gfm-strikethrough

[downloads-badge]: https://img.shields.io/npm/dm/mdast-util-gfm-strikethrough.svg

[downloads]: https://www.npmjs.com/package/mdast-util-gfm-strikethrough

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=mdast-util-gfm-strikethrough

[size]: https://bundlejs.com/?q=mdast-util-gfm-strikethrough

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/syntax-tree/unist/discussions

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[typescript]: https://www.typescriptlang.org

[license]: license

[author]: https://wooorm.com

[health]: https://github.com/syntax-tree/.github

[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md

[support]: https://github.com/syntax-tree/.github/blob/main/support.md

[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md

[gfm]: https://github.github.com/gfm/

[remark-gfm]: https://github.com/remarkjs/remark-gfm

[mdast]: https://github.com/syntax-tree/mdast

[dfn-transparent-content]: https://github.com/syntax-tree/mdast#transparentcontent

[mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown

[from-markdown-extension]: https://github.com/syntax-tree/mdast-util-from-markdown#extension

[mdast-util-to-markdown]: https://github.com/syntax-tree/mdast-util-to-markdown

[to-markdown-extension]: https://github.com/syntax-tree/mdast-util-to-markdown#options

[mdast-util-gfm]: https://github.com/syntax-tree/mdast-util-gfm

[mdast-util-to-hast]: https://github.com/syntax-tree/mdast-util-to-hast

[micromark]: https://github.com/micromark/micromark

[extension]: https://github.com/micromark/micromark-extension-gfm-strikethrough

[syntax]: https://github.com/micromark/micromark-extension-gfm-strikethrough#syntax

[dfn-parent]: https://github.com/syntax-tree/mdast#parent

[dfn-phrasing-content]: #phrasingcontent-gfm-strikethrough

[api-gfm-strikethrough-from-markdown]: #gfmstrikethroughfrommarkdown

[api-gfm-strikethrough-to-markdown]: #gfmstrikethroughtomarkdown


---

# mdast-util-gfm-table

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[mdast][] extensions to parse and serialize [GFM][] tables.

## Contents

*   [What is this?](#what-is-this)
*   [When to use this](#when-to-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`gfmTableFromMarkdown`](#gfmtablefrommarkdown)
    *   [`gfmTableToMarkdown(options?)`](#gfmtabletomarkdownoptions)
    *   [`Options`](#options)
*   [Examples](#examples)
    *   [Example: `stringLength`](#example-stringlength)
*   [HTML](#html)
*   [Syntax](#syntax)
*   [Syntax tree](#syntax-tree)
    *   [Nodes](#nodes)
    *   [Enumeration](#enumeration)
    *   [Content model](#content-model)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package contains two extensions that add support for GFM table syntax in
markdown to [mdast][].
These extensions plug into
[`mdast-util-from-markdown`][mdast-util-from-markdown] (to support parsing
tables in markdown into a syntax tree) and
[`mdast-util-to-markdown`][mdast-util-to-markdown] (to support serializing
tables in syntax trees to markdown).

## When to use this

You can use these extensions when you are working with
`mdast-util-from-markdown` and `mdast-util-to-markdown` already.

When working with `mdast-util-from-markdown`, you must combine this package
with [`micromark-extension-gfm-table`][extension].

When you don’t need a syntax tree, you can use [`micromark`][micromark]
directly with `micromark-extension-gfm-table`.

When you are working with syntax trees and want all of GFM, use
[`mdast-util-gfm`][mdast-util-gfm] instead.

All these packages are used [`remark-gfm`][remark-gfm], which
focusses on making it easier to transform content by abstracting these
internals away.

This utility does not handle how markdown is turned to HTML.
That’s done by [`mdast-util-to-hast`][mdast-util-to-hast].

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install mdast-util-gfm-table
```

In Deno with [`esm.sh`][esmsh]:

```js
import {gfmTableFromMarkdown, gfmTableToMarkdown} from 'https://esm.sh/mdast-util-gfm-table@2'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {gfmTableFromMarkdown, gfmTableToMarkdown} from 'https://esm.sh/mdast-util-gfm-table@2?bundle'
</script>
```

## Use

Say our document `example.md` contains:

```markdown
| a | b | c | d |
| - | :- | -: | :-: |
| e | f |
| g | h | i | j | k |
```

…and our module `example.js` looks as follows:

```js
import fs from 'node:fs/promises'
import {gfmTable} from 'micromark-extension-gfm-table'
import {fromMarkdown} from 'mdast-util-from-markdown'
import {gfmTableFromMarkdown, gfmTableToMarkdown} from 'mdast-util-gfm-table'
import {toMarkdown} from 'mdast-util-to-markdown'

const doc = await fs.readFile('example.md')

const tree = fromMarkdown(doc, {
  extensions: [gfmTable()],
  mdastExtensions: [gfmTableFromMarkdown()]
})

console.log(tree)

const out = toMarkdown(tree, {extensions: [gfmTableToMarkdown()]})

console.log(out)
```

…now running `node example.js` yields (positional info removed for brevity):

```js
{
  type: 'root',
  children: [
    {
      type: 'table',
      align: [null, 'left', 'right', 'center'],
      children: [
        {
          type: 'tableRow',
          children: [
            {type: 'tableCell', children: [{type: 'text', value: 'a'}]},
            {type: 'tableCell', children: [{type: 'text', value: 'b'}]},
            {type: 'tableCell', children: [{type: 'text', value: 'c'}]},
            {type: 'tableCell', children: [{type: 'text', value: 'd'}]}
          ]
        },
        {
          type: 'tableRow',
          children: [
            {type: 'tableCell', children: [{type: 'text', value: 'e'}]},
            {type: 'tableCell', children: [{type: 'text', value: 'f'}]}
          ]
        },
        {
          type: 'tableRow',
          children: [
            {type: 'tableCell', children: [{type: 'text', value: 'g'}]},
            {type: 'tableCell', children: [{type: 'text', value: 'h'}]},
            {type: 'tableCell', children: [{type: 'text', value: 'i'}]},
            {type: 'tableCell', children: [{type: 'text', value: 'j'}]},
            {type: 'tableCell', children: [{type: 'text', value: 'k'}]}
          ]
        }
      ]
    }
  ]
}
```

```markdown
| a | b  |  c |  d  |   |
| - | :- | -: | :-: | - |
| e | f  |    |     |   |
| g | h  |  i |  j  | k |
```

## API

This package exports the identifiers
[`gfmTableFromMarkdown`][api-gfm-table-from-markdown] and
[`gfmTableToMarkdown`][api-gfm-table-to-markdown].
There is no default export.

### `gfmTableFromMarkdown`

Create an extension for [`mdast-util-from-markdown`][mdast-util-from-markdown]
to enable GFM tables in markdown.

###### Returns

Extension for `mdast-util-from-markdown` to enable GFM tables
([`FromMarkdownExtension`][from-markdown-extension]).

### `gfmTableToMarkdown(options?)`

Create an extension for [`mdast-util-to-markdown`][mdast-util-to-markdown] to
enable GFM tables in markdown.

###### Parameters

*   `options` ([`Options`][api-options], optional)
    — configuration

###### Returns

Extension for `mdast-util-to-markdown` to enable GFM tables
([`ToMarkdownExtension`][to-markdown-extension]).

### `Options`

Configuration (TypeScript type).

###### Fields

*   `tableCellPadding` (`boolean`, default: `true`)
    — whether to add a space of padding between delimiters and cells
*   `tablePipeAlign` (`boolean`, default: `true`)
    — whether to align the delimiters
*   `stringLength` (`((value: string) => number)`, default: `s => s.length`)
    — function to detect the length of table cell content, used when aligning
    the delimiters between cells

## Examples

### Example: `stringLength`

It’s possible to align tables based on the visual width of cells.
First, let’s show the problem:

```js
import {gfmTable} from 'micromark-extension-gfm-table'
import {fromMarkdown} from 'mdast-util-from-markdown'
import {gfmTableFromMarkdown, gfmTableToMarkdown} from 'mdast-util-gfm-table'
import {toMarkdown} from 'mdast-util-to-markdown'

const doc = `| Alpha | Bravo |
| - | - |
| 中文 | Charlie |
| 👩‍❤️‍👩 | Delta |`

const tree = fromMarkdown(doc, {
  extensions: [gfmTable],
  mdastExtensions: [gfmTableFromMarkdown]
})

console.log(toMarkdown(tree, {extensions: [gfmTableToMarkdown()]}))
```

The above code shows how these utilities can be used to format markdown.
The output is as follows:

```markdown
| Alpha    | Bravo   |
| -------- | ------- |
| 中文       | Charlie |
| 👩‍❤️‍👩 | Delta   |
```

To improve the alignment of these full-width characters and emoji, pass a
`stringLength` function that calculates the visual width of cells.
One such algorithm is [`string-width`][string-width].
It can be used like so:

```diff
@@ -2,6 +2,7 @@ import {gfmTable} from 'micromark-extension-gfm-table'
 import {fromMarkdown} from 'mdast-util-from-markdown'
 import {gfmTableFromMarkdown, gfmTableToMarkdown} from 'mdast-util-gfm-table'
 import {toMarkdown} from 'mdast-util-to-markdown'
+import stringWidth from 'string-width'

 const doc = `| Alpha | Bravo |
 | - | - |
@@ -13,4 +14,8 @@ const tree = fromMarkdown(doc, {
   mdastExtensions: [gfmTableFromMarkdown()]
 })

-console.log(toMarkdown(tree, {extensions: [gfmTableToMarkdown()]}))
+console.log(
+  toMarkdown(tree, {
+    extensions: [gfmTableToMarkdown({stringLength: stringWidth})]
+  })
+)
```

The output of our code with these changes is as follows:

```markdown
| Alpha | Bravo   |
| ----- | ------- |
| 中文  | Charlie |
| 👩‍❤️‍👩    | Delta   |
```

## HTML

This utility does not handle how markdown is turned to HTML.
That’s done by [`mdast-util-to-hast`][mdast-util-to-hast].

## Syntax

See [Syntax in `micromark-extension-gfm-table`][syntax].

## Syntax tree

The following interfaces are added to **[mdast][]** by this utility.

### Nodes

#### `Table`

```idl
interface Table <: Parent {
  type: 'table'
  align: [alignType]?
  children: [TableContent]
}
```

**Table** (**[Parent][dfn-parent]**) represents two-dimensional data.

**Table** can be used where **[flow][dfn-flow-content]** content is expected.
Its content model is **[table][dfn-table-content]** content.

The *[head][term-head]* of the node represents the labels of the columns.

An `align` field can be present.
If present, it must be a list of **[alignTypes][dfn-enum-align-type]**.
It represents how cells in columns are aligned.

For example, the following markdown:

```markdown
| foo | bar |
| :-- | :-: |
| baz | qux |
```

Yields:

```js
{
  type: 'table',
  align: ['left', 'center'],
  children: [
    {
      type: 'tableRow',
      children: [
        {
          type: 'tableCell',
          children: [{type: 'text', value: 'foo'}]
        },
        {
          type: 'tableCell',
          children: [{type: 'text', value: 'bar'}]
        }
      ]
    },
    {
      type: 'tableRow',
      children: [
        {
          type: 'tableCell',
          children: [{type: 'text', value: 'baz'}]
        },
        {
          type: 'tableCell',
          children: [{type: 'text', value: 'qux'}]
        }
      ]
    }
  ]
}
```

#### `TableRow`

```idl
interface TableRow <: Parent {
  type: "tableRow"
  children: [RowContent]
}
```

**TableRow** (**[Parent][dfn-parent]**) represents a row of cells in a table.

**TableRow** can be used where **[table][dfn-table-content]** content is
expected.
Its content model is **[row][dfn-row-content]** content.

If the node is a *[head][term-head]*, it represents the labels of the columns
for its parent **[Table][dfn-table]**.

For an example, see **[Table][dfn-table]**.

#### `TableCell`

```idl
interface TableCell <: Parent {
  type: "tableCell"
  children: [PhrasingContent]
}
```

**TableCell** (**[Parent][dfn-parent]**) represents a header cell in a
**[Table][dfn-table]**, if its parent is a *[head][term-head]*, or a data
cell otherwise.

**TableCell** can be used where **[row][dfn-row-content]** content is expected.
Its content model is **[phrasing][dfn-phrasing-content]** content excluding
**[Break][dfn-break]** nodes.

For an example, see **[Table][dfn-table]**.

### Enumeration

#### `alignType`

```idl
enum alignType {
  'center' | 'left' | 'right' | null
}
```

**alignType** represents how phrasing content is aligned
([\[CSSTEXT\]][css-text]).

*   **`'left'`**: See the [`left`][css-left] value of the `text-align` CSS
    property
*   **`'right'`**: See the [`right`][css-right] value of the `text-align`
    CSS property
*   **`'center'`**: See the [`center`][css-center] value of the `text-align`
    CSS property
*   **`null`**: phrasing content is aligned as defined by the host environment

### Content model

#### `FlowContent` (GFM table)

```idl
type FlowContentGfm = Table | FlowContent
```

#### `TableContent`

```idl
type TableContent = TableRow
```

**Table** content represent the rows in a table.

#### `RowContent`

```idl
type RowContent = TableCell
```

**Row** content represent the cells in a row.

## Types

This package is fully typed with [TypeScript][].
It exports the additional type [`Options`][api-options].

The `Table`, `TableRow`, and `TableCell` types of the mdast nodes are exposed
from `@types/mdast`.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, `mdast-util-gfm-table@^2`,
compatible with Node.js 16.

This utility works with `mdast-util-from-markdown` version 2+ and
`mdast-util-to-markdown` version 2+.

## Related

*   [`remarkjs/remark-gfm`][remark-gfm]
    — remark plugin to support GFM
*   [`syntax-tree/mdast-util-gfm`][mdast-util-gfm]
    — same but all of GFM (autolink literals, footnotes, strikethrough, tables,
    tasklists)
*   [`micromark/micromark-extension-gfm-table`][extension]
    — micromark extension to parse GFM tables

## Contribute

See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
ways to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/syntax-tree/mdast-util-gfm-table/workflows/main/badge.svg

[build]: https://github.com/syntax-tree/mdast-util-gfm-table/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/mdast-util-gfm-table.svg

[coverage]: https://codecov.io/github/syntax-tree/mdast-util-gfm-table

[downloads-badge]: https://img.shields.io/npm/dm/mdast-util-gfm-table.svg

[downloads]: https://www.npmjs.com/package/mdast-util-gfm-table

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=mdast-util-gfm-table

[size]: https://bundlejs.com/?q=mdast-util-gfm-table

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/syntax-tree/unist/discussions

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[typescript]: https://www.typescriptlang.org

[license]: license

[author]: https://wooorm.com

[health]: https://github.com/syntax-tree/.github

[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md

[support]: https://github.com/syntax-tree/.github/blob/main/support.md

[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md

[remark-gfm]: https://github.com/remarkjs/remark-gfm

[mdast]: https://github.com/syntax-tree/mdast

[mdast-util-gfm]: https://github.com/syntax-tree/mdast-util-gfm

[mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown

[mdast-util-to-markdown]: https://github.com/syntax-tree/mdast-util-to-markdown

[mdast-util-to-hast]: https://github.com/syntax-tree/mdast-util-to-hast

[micromark]: https://github.com/micromark/micromark

[extension]: https://github.com/micromark/micromark-extension-gfm-table

[syntax]: https://github.com/micromark/micromark-extension-gfm-table#syntax

[gfm]: https://github.github.com/gfm/

[string-width]: https://github.com/sindresorhus/string-width

[css-text]: https://drafts.csswg.org/css-text/

[css-left]: https://drafts.csswg.org/css-text/#valdef-text-align-left

[css-right]: https://drafts.csswg.org/css-text/#valdef-text-align-right

[css-center]: https://drafts.csswg.org/css-text/#valdef-text-align-center

[term-head]: https://github.com/syntax-tree/unist#head

[dfn-parent]: https://github.com/syntax-tree/mdast#parent

[dfn-phrasing-content]: https://github.com/syntax-tree/mdast#phrasingcontent

[dfn-break]: https://github.com/syntax-tree/mdast#break

[from-markdown-extension]: https://github.com/syntax-tree/mdast-util-from-markdown#extension

[to-markdown-extension]: https://github.com/syntax-tree/mdast-util-to-markdown#options

[api-gfm-table-from-markdown]: #gfmtablefrommarkdown

[api-gfm-table-to-markdown]: #gfmtabletomarkdownoptions

[api-options]: #options

[dfn-flow-content]: #flowcontent-gfm-table

[dfn-table-content]: #tablecontent

[dfn-enum-align-type]: #aligntype

[dfn-row-content]: #rowcontent

[dfn-table]: #table


---

# mdast-util-gfm-task-list-item

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[mdast][] extensions to parse and serialize [GFM][] task list items.

## Contents

*   [What is this?](#what-is-this)
*   [When to use this](#when-to-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`gfmTaskListItemFromMarkdown()`](#gfmtasklistitemfrommarkdown)
    *   [`gfmTaskListItemToMarkdown()`](#gfmtasklistitemtomarkdown)
*   [HTML](#html)
*   [Syntax](#syntax)
*   [Syntax tree](#syntax-tree)
    *   [Nodes](#nodes)
    *   [Content model](#content-model)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package contains two extensions that add support for GFM task list item
syntax in markdown to [mdast][].
These extensions plug into
[`mdast-util-from-markdown`][mdast-util-from-markdown] (to support parsing
task lists in markdown into a syntax tree) and
[`mdast-util-to-markdown`][mdast-util-to-markdown] (to support serializing
task lists in syntax trees to markdown).

## When to use this

You can use these extensions when you are working with
`mdast-util-from-markdown` and `mdast-util-to-markdown` already.

When working with `mdast-util-from-markdown`, you must combine this package
with
[`micromark-extension-gfm-task-list-item`][extension].

When you don’t need a syntax tree, you can use [`micromark`][micromark]
directly with `micromark-extension-gfm-task-list-item`.

When you are working with syntax trees and want all of GFM, use
[`mdast-util-gfm`][mdast-util-gfm] instead.

All these packages are used [`remark-gfm`][remark-gfm], which
focusses on making it easier to transform content by abstracting these
internals away.

This utility does not handle how markdown is turned to HTML.
That’s done by [`mdast-util-to-hast`][mdast-util-to-hast].

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install mdast-util-gfm-task-list-item
```

In Deno with [`esm.sh`][esmsh]:

```js
import {gfmTaskListItemFromMarkdown, gfmTaskListItemToMarkdown} from 'https://esm.sh/mdast-util-gfm-task-list-item@2'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {gfmTaskListItemFromMarkdown, gfmTaskListItemToMarkdown} from 'https://esm.sh/mdast-util-gfm-task-list-item@2?bundle'
</script>
```

## Use

Say our document `example.md` contains:

```markdown
* [ ] To do
* [x] Done

1. Mixed…
2. [x] …messages
```

…and our module `example.js` looks as follows:

```js
import fs from 'node:fs/promises'
import {gfmTaskListItem} from 'micromark-extension-gfm-task-list-item'
import {fromMarkdown} from 'mdast-util-from-markdown'
import {gfmTaskListItemFromMarkdown, gfmTaskListItemToMarkdown} from 'mdast-util-gfm-task-list-item'
import {toMarkdown} from 'mdast-util-to-markdown'

const doc = await fs.readFile('example.md')

const tree = fromMarkdown(doc, {
  extensions: [gfmTaskListItem],
  mdastExtensions: [gfmTaskListItemFromMarkdown]
})

console.log(tree)

const out = toMarkdown(tree, {extensions: [gfmTaskListItemToMarkdown]})

console.log(out)
```

…now running `node example.js` yields (positional info removed for brevity):

```js
{
 type: 'root',
 children: [
   {
     type: 'list',
     ordered: false,
     start: null,
     spread: false,
     children: [
       {
         type: 'listItem',
         spread: false,
         checked: false,
         children: [
           {type: 'paragraph', children: [{type: 'text', value: 'To do'}]}
         ]
       },
       {
         type: 'listItem',
         spread: false,
         checked: true,
         children: [
           {type: 'paragraph', children: [{type: 'text', value: 'Done'}]}
         ]
       }
     ]
   },
   {
     type: 'list',
     ordered: true,
     start: 1,
     spread: false,
     children: [
       {
         type: 'listItem',
         spread: false,
         checked: null,
         children: [
           {type: 'paragraph', children: [{type: 'text', value: 'Mixed…'}]}
         ]
       },
       {
         type: 'listItem',
         spread: false,
         checked: true,
         children: [
           {type: 'paragraph', children: [{type: 'text', value: '…messages'}]}
         ]
       }
     ]
   }
 ]
}
```

```markdown
*   [ ] To do
*   [x] Done

1.  Mixed…
2.  [x] …messages
```

## API

This package exports the identifiers
[`gfmTaskListItemFromMarkdown`][api-gfm-task-list-item-from-markdown] and
[`gfmTaskListItemToMarkdown`][api-gfm-task-list-item-to-markdown].
There is no default export.

### `gfmTaskListItemFromMarkdown()`

Create an extension for [`mdast-util-from-markdown`][mdast-util-from-markdown]
to enable GFM task list items in markdown.

###### Returns

Extension for `mdast-util-from-markdown` to enable GFM task list items
([`FromMarkdownExtension`][frommarkdownextension]).

### `gfmTaskListItemToMarkdown()`

Create an extension for [`mdast-util-to-markdown`][mdast-util-to-markdown] to
enable GFM task list items in markdown.

###### Returns

Extension for `mdast-util-to-markdown` to enable GFM task list items
([`ToMarkdownExtension`][tomarkdownextension]).

## HTML

This utility does not handle how markdown is turned to HTML.
That’s done by [`mdast-util-to-hast`][mdast-util-to-hast].

## Syntax

See [Syntax in `micromark-extension-gfm-task-list-item`][syntax].

## Syntax tree

The following interfaces are added to **[mdast][]** by this utility.

### Nodes

#### `ListItem` (GFM)

```idl
interface ListItemGfm <: ListItem {
  checked: boolean?
}
```

In GFM, a `checked` field can be present.
It represents whether the item is done (when `true`), not done (when `false`),
or indeterminate or not applicable (when `null` or not present).

### Content model

#### `ListContent` (GFM)

```idl
type ListContentGfm = ListItemGfm
```

## Types

This package is fully typed with [TypeScript][].
It does not export additional types.

The `ListItem` type of the mdast nodes are exposed from `@types/mdast`.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`mdast-util-gfm-task-list-item@^2`, compatible with Node.js 16.

## Related

*   [`remarkjs/remark-gfm`][remark-gfm]
    — remark plugin to support GFM
*   [`syntax-tree/mdast-util-gfm`][mdast-util-gfm]
    — same but all of GFM (autolink literals, footnotes, strikethrough, tables,
    tasklists)
*   [`micromark/micromark-extension-gfm-task-list-item`][extension]
    — micromark extension to parse GFM task list items

## Contribute

See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
ways to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/syntax-tree/mdast-util-gfm-task-list-item/workflows/main/badge.svg

[build]: https://github.com/syntax-tree/mdast-util-gfm-task-list-item/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/mdast-util-gfm-task-list-item.svg

[coverage]: https://codecov.io/github/syntax-tree/mdast-util-gfm-task-list-item

[downloads-badge]: https://img.shields.io/npm/dm/mdast-util-gfm-task-list-item.svg

[downloads]: https://www.npmjs.com/package/mdast-util-gfm-task-list-item

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=mdast-util-gfm-task-list-item

[size]: https://bundlejs.com/?q=mdast-util-gfm-task-list-item

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/syntax-tree/unist/discussions

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[typescript]: https://www.typescriptlang.org

[license]: license

[author]: https://wooorm.com

[health]: https://github.com/syntax-tree/.github

[contributing]: https://github.com/syntax-tree/.github/blob/HEAD/contributing.md

[support]: https://github.com/syntax-tree/.github/blob/HEAD/support.md

[coc]: https://github.com/syntax-tree/.github/blob/HEAD/code-of-conduct.md

[mdast]: https://github.com/syntax-tree/mdast

[remark-gfm]: https://github.com/remarkjs/remark-gfm

[mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown

[mdast-util-to-markdown]: https://github.com/syntax-tree/mdast-util-to-markdown

[mdast-util-gfm]: https://github.com/syntax-tree/mdast-util-gfm

[mdast-util-to-hast]: https://github.com/syntax-tree/mdast-util-to-hast

[micromark]: https://github.com/micromark/micromark

[extension]: https://github.com/micromark/micromark-extension-gfm-task-list-item

[syntax]: https://github.com/micromark/micromark-extension-gfm-task-list-item#syntax

[frommarkdownextension]: https://github.com/syntax-tree/mdast-util-from-markdown#extension

[tomarkdownextension]: https://github.com/syntax-tree/mdast-util-to-markdown#options

[gfm]: https://github.github.com/gfm/

[api-gfm-task-list-item-from-markdown]: #gfmtasklistitemfrommarkdown

[api-gfm-task-list-item-to-markdown]: #gfmtasklistitemtomarkdown


---

# mdast-util-mdx

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[mdast][] extensions to parse and serialize [MDX][]: ESM, JSX, and expressions.

## Contents

*   [What is this?](#what-is-this)
*   [When to use this](#when-to-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`mdxFromMarkdown()`](#mdxfrommarkdown)
    *   [`mdxToMarkdown(options?)`](#mdxtomarkdownoptions)
    *   [`ToMarkdownOptions`](#tomarkdownoptions)
*   [HTML](#html)
*   [Syntax](#syntax)
*   [Syntax tree](#syntax-tree)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package contains two extensions that add support for MDX syntax in
markdown to [mdast][]: ESM (`import x from 'y'`), JSX (`<a />`), and
expressions (`{Math.PI}`).
These extensions plug into
[`mdast-util-from-markdown`][mdast-util-from-markdown] (to support parsing
MDX in markdown into a syntax tree) and
[`mdast-util-to-markdown`][mdast-util-to-markdown] (to support serializing
MDX in syntax trees to markdown).

## When to use this

You can use these extensions when you are working with
`mdast-util-from-markdown` and `mdast-util-to-markdown` already.

When working with `mdast-util-from-markdown`, you must combine this package
with [`micromark-extension-mdx`][mdx] or [`micromark-extension-mdxjs`][mdxjs].

Instead of this package, you can also use the extensions separately:

*   [`mdast-util-mdx-expression`](https://github.com/syntax-tree/mdast-util-mdx-expression)
    — support MDX expressions
*   [`mdast-util-mdx-jsx`](https://github.com/syntax-tree/mdast-util-mdx-jsx)
    — support MDX JSX
*   [`mdast-util-mdxjs-esm`](https://github.com/syntax-tree/mdast-util-mdxjs-esm)
    — support MDX ESM

All these packages are used in [`remark-mdx`][remark-mdx], which
focusses on making it easier to transform content by abstracting these
internals away.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install mdast-util-mdx
```

In Deno with [`esm.sh`][esmsh]:

```js
import {mdxFromMarkdown, mdxToMarkdown} from 'https://esm.sh/mdast-util-mdx@3'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {mdxFromMarkdown, mdxToMarkdown} from 'https://esm.sh/mdast-util-mdx@3?bundle'
</script>
```

## Use

Say our document `example.mdx` contains:

```mdx
import Box from "place"

Here’s an expression:

{
  1 + 1 /* } */
}

Which you can also put inline: {1+1}.

<Box>
  <SmallerBox>
    - Lists, which can be indented.
  </SmallerBox>
</Box>
```

…and our module `example.js` looks as follows:

```js
import fs from 'node:fs/promises'
import {mdxjs} from 'micromark-extension-mdxjs'
import {fromMarkdown} from 'mdast-util-from-markdown'
import {mdxFromMarkdown, mdxToMarkdown} from 'mdast-util-mdx'
import {toMarkdown} from 'mdast-util-to-markdown'

const doc = await fs.readFile('example.mdx')

const tree = fromMarkdown(doc, {
  extensions: [mdxjs()],
  mdastExtensions: [mdxFromMarkdown()]
})

console.log(tree)

const out = toMarkdown(tree, {extensions: [mdxToMarkdown()]})

console.log(out)
```

…now running `node example.js` yields (positional info removed for brevity):

```js
{
  type: 'root',
  children: [
    {
      type: 'mdxjsEsm',
      value: 'import Box from "place"',
      data: {
        estree: {
          type: 'Program',
          body: [
            {
              type: 'ImportDeclaration',
              specifiers: [
                {
                  type: 'ImportDefaultSpecifier',
                  local: {type: 'Identifier', name: 'Box'}
                }
              ],
              source: {type: 'Literal', value: 'place', raw: '"place"'}
            }
          ],
          sourceType: 'module'
        }
      }
    },
    {
      type: 'paragraph',
      children: [{type: 'text', value: 'Here’s an expression:'}]
    },
    {
      type: 'mdxFlowExpression',
      value: '\n1 + 1 /* } */\n',
      data: {
        estree: {
          type: 'Program',
          body: [
            {
              type: 'ExpressionStatement',
              expression: {
                type: 'BinaryExpression',
                left: {type: 'Literal', value: 1, raw: '1'},
                operator: '+',
                right: {type: 'Literal', value: 1, raw: '1'}
              }
            }
          ],
          sourceType: 'module'
        }
      }
    },
    {
      type: 'paragraph',
      children: [
        {type: 'text', value: 'Which you can also put inline: '},
        {
          type: 'mdxTextExpression',
          value: '1+1',
          data: {
            estree: {
              type: 'Program',
              body: [
                {
                  type: 'ExpressionStatement',
                  expression: {
                    type: 'BinaryExpression',
                    left: {type: 'Literal', value: 1, raw: '1'},
                    operator: '+',
                    right: {type: 'Literal', value: 1, raw: '1'}
                  }
                }
              ],
              sourceType: 'module'
            }
          }
        },
        {type: 'text', value: '.'}
      ]
    },
    {
      type: 'mdxJsxFlowElement',
      name: 'Box',
      attributes: [],
      children: [
        {
          type: 'mdxJsxFlowElement',
          name: 'SmallerBox',
          attributes: [],
          children: [
            {
              type: 'list',
              ordered: false,
              start: null,
              spread: false,
              children: [
                {
                  type: 'listItem',
                  spread: false,
                  checked: null,
                  children: [
                    {
                      type: 'paragraph',
                      children: [
                        {type: 'text', value: 'Lists, which can be indented.'}
                      ]
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

```mdx
import Box from "place"

Here’s an expression:

{
  1 + 1 /* } */
}

Which you can also put inline: {1+1}.

<Box>
  <SmallerBox>
    *   Lists, which can be indented.
  </SmallerBox>
</Box>
```

## API

This package exports the identifiers [`mdxFromMarkdown`][api-mdx-from-markdown]
and [`mdxToMarkdown`][api-mdx-to-markdown].
There is no default export.

### `mdxFromMarkdown()`

Create an extension for [`mdast-util-from-markdown`][mdast-util-from-markdown]
to enable MDX (ESM, JSX, expressions).

###### Returns

Extension for `mdast-util-from-markdown` to enable MDX
([`FromMarkdownExtension`][from-markdown-extension]).

When using the [syntax extensions with `addResult`][mdxjs], ESM and expression
nodes will have `data.estree` fields set to ESTree [`Program`][program] node.

### `mdxToMarkdown(options?)`

Create an extension for [`mdast-util-to-markdown`][mdast-util-to-markdown]
to enable MDX (ESM, JSX, expressions).

Extension for [`mdast-util-to-markdown`][mdast-util-to-markdown].

###### Parameters

*   `options` ([`ToMarkdownOptions`][api-to-markdown-options])
    — configuration

###### Returns

Extension for `mdast-util-to-markdown` to enable MDX
([`FromMarkdownExtension`][to-markdown-extension]).

### `ToMarkdownOptions`

Configuration (TypeScript type).

###### Fields

*   `quote` (`'"'` or `"'"`, default: `'"'`)
    — preferred quote to use around attribute values
*   `quoteSmart` (`boolean`, default: `false`)
    — use the other quote if that results in less bytes
*   `tightSelfClosing` (`boolean`, default: `false`)
    — do not use an extra space when closing self-closing elements: `<img/>`
    instead of `<img />`
*   `printWidth` (`number`, default: `Infinity`)
    — try and wrap syntax at this width.
    When set to a finite number (say, `80`), the formatter will print
    attributes on separate lines when a tag doesn’t fit on one line.
    The normal behavior is to print attributes with spaces between them instead
    of line endings

## HTML

MDX has no representation in HTML.
Though, when you are dealing with MDX, you will likely go *through* hast.
You can enable passing MDX through to hast by configuring
[`mdast-util-to-hast`][mdast-util-to-hast] with `passThrough: ['mdxjsEsm',
'mdxFlowExpression', 'mdxJsxFlowElement', 'mdxJsxTextElement', 'mdxTextExpression']`.

## Syntax

See [Syntax in `micromark-extension-mdxjs`][mdxjs].

## Syntax tree

This utility combines several mdast utilities.
See their readmes for the node types supported in the tree:

*   [`mdast-util-mdx-expression`](https://github.com/syntax-tree/mdast-util-mdx-expression#syntax-tree)
    — support MDX expressions
*   [`mdast-util-mdx-jsx`](https://github.com/syntax-tree/mdast-util-mdx-jsx#syntax-tree)
    — support MDX JSX
*   [`mdast-util-mdxjs-esm`](https://github.com/syntax-tree/mdast-util-mdxjs-esm#syntax-tree)
    — support MDX ESM

## Types

This package is fully typed with [TypeScript][].
It exports the additional types
`MdxFlowExpression` and `MdxTextExpression`
from `mdast-util-mdx-expression`;
`MdxJsxAttribute`,
`MdxJsxAttributeValueExpression`,
`MdxJsxExpressionAttribute`,
`MdxJsxFlowElement`,
`MdxJsxTextElement`,
and [`ToMarkdownOptions`][api-to-markdown-options]
from `mdast-util-mdx-jsx`;
and `MdxjsEsm` from `mdast-util-mdxjs-esm`.

It also registers the node types with `@types/mdast` and `@types/hast`.
If you’re working with the syntax tree, make sure to import this utility
somewhere in your types, as that registers the new node types in the tree.

```js
/**
 * @typedef {import('mdast-util-mdx')}
 */

import {visit} from 'unist-util-visit'

/** @type {import('mdast').Root} */
const tree = getMdastNodeSomeHow()

visit(tree, function (node) {
  // `node` can now be an expression, JSX, or ESM node.
})
```

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, `mdast-util-mdx@^3`,
compatible with Node.js 16.

This utility works with `mdast-util-from-markdown` version 2+ and
`mdast-util-to-markdown` version 2+.

## Related

*   [`remark-mdx`][remark-mdx]
    — remark plugin to support MDX
*   [`micromark-extension-mdx`][mdx]
    — micromark extension to parse MDX
*   [`micromark-extension-mdxjs`][mdxjs]
    — micromark extension to parse JavaScript-aware MDX

## Contribute

See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
ways to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/syntax-tree/mdast-util-mdx/workflows/main/badge.svg

[build]: https://github.com/syntax-tree/mdast-util-mdx/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/mdast-util-mdx.svg

[coverage]: https://codecov.io/github/syntax-tree/mdast-util-mdx

[downloads-badge]: https://img.shields.io/npm/dm/mdast-util-mdx.svg

[downloads]: https://www.npmjs.com/package/mdast-util-mdx

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=mdast-util-mdx

[size]: https://bundlejs.com/?q=mdast-util-mdx

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/syntax-tree/unist/discussions

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[typescript]: https://www.typescriptlang.org

[license]: license

[author]: https://wooorm.com

[health]: https://github.com/syntax-tree/.github

[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md

[support]: https://github.com/syntax-tree/.github/blob/main/support.md

[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md

[mdast]: https://github.com/syntax-tree/mdast

[mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown

[from-markdown-extension]: https://github.com/syntax-tree/mdast-util-from-markdown#extension

[mdast-util-to-markdown]: https://github.com/syntax-tree/mdast-util-to-markdown

[to-markdown-extension]: https://github.com/syntax-tree/mdast-util-to-markdown#options

[mdast-util-to-hast]: https://github.com/syntax-tree/mdast-util-to-hast

[mdx]: https://github.com/micromark/micromark-extension-mdx

[mdxjs]: https://github.com/micromark/micromark-extension-mdxjs

[remark-mdx]: https://github.com/mdx-js/mdx/tree/next/packages/remark-mdx

[program]: https://github.com/estree/estree/blob/master/es2015.md#programs

[api-mdx-from-markdown]: #mdxfrommarkdown

[api-mdx-to-markdown]: #mdxtomarkdownoptions

[api-to-markdown-options]: #tomarkdownoptions


---

# mdast-util-mdx-expression

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[mdast][] extensions to parse and serialize [MDX][] expressions (`{Math.PI}`).

## Contents

* [What is this?](#what-is-this)
* [When to use this](#when-to-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`mdxExpressionFromMarkdown()`](#mdxexpressionfrommarkdown)
  * [`mdxExpressionToMarkdown()`](#mdxexpressiontomarkdown)
  * [`MdxFlowExpression`](#mdxflowexpression)
  * [`MdxTextExpression`](#mdxtextexpression)
  * [`MdxFlowExpressionHast`](#mdxflowexpressionhast)
  * [`MdxTextExpressionHast`](#mdxtextexpressionhast)
* [HTML](#html)
* [Syntax](#syntax)
* [Syntax tree](#syntax-tree)
  * [Nodes](#nodes)
  * [Content model](#content-model)
* [Types](#types)
* [Compatibility](#compatibility)
* [Related](#related)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package contains two extensions that add support for MDX expression syntax
in markdown to [mdast][].
These extensions plug into
[`mdast-util-from-markdown`][mdast-util-from-markdown] (to support parsing
expressions in markdown into a syntax tree) and
[`mdast-util-to-markdown`][mdast-util-to-markdown] (to support serializing
expressions in syntax trees to markdown).

## When to use this

You can use these extensions when you are working with
`mdast-util-from-markdown` and `mdast-util-to-markdown` already.

When working with `mdast-util-from-markdown`, you must combine this package
with [`micromark-extension-mdx-expression`][extension].

When you are working with syntax trees and want all of MDX, use
[`mdast-util-mdx`][mdast-util-mdx] instead.

All these packages are used in [`remark-mdx`][remark-mdx], which
focusses on making it easier to transform content by abstracting these
internals away.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install mdast-util-mdx-expression
```

In Deno with [`esm.sh`][esmsh]:

```js
import {mdxExpressionFromMarkdown, mdxExpressionToMarkdown} from 'https://esm.sh/mdast-util-mdx-expression@2'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {mdxExpressionFromMarkdown, mdxExpressionToMarkdown} from 'https://esm.sh/mdast-util-mdx-expression@2?bundle'
</script>
```

## Use

Say our document `example.mdx` contains:

```mdx
{
  a + 1
}

b {true}.
```

…and our module `example.js` looks as follows:

```js
import fs from 'node:fs/promises'
import * as acorn from 'acorn'
import {mdxExpression} from 'micromark-extension-mdx-expression'
import {fromMarkdown} from 'mdast-util-from-markdown'
import {mdxExpressionFromMarkdown, mdxExpressionToMarkdown} from 'mdast-util-mdx-expression'
import {toMarkdown} from 'mdast-util-to-markdown'

const doc = await fs.readFile('example.mdx')

const tree = fromMarkdown(doc, {
  extensions: [mdxExpression({acorn, addResult: true})],
  mdastExtensions: [mdxExpressionFromMarkdown()]
})

console.log(tree)

const out = toMarkdown(tree, {extensions: [mdxExpressionToMarkdown()]})

console.log(out)
```

…now running `node example.js` yields (positional info removed for brevity):

```js
{
  type: 'root',
  children: [
    {
      type: 'mdxFlowExpression',
      value: '\na + 1\n',
      data: {
        estree: {
          type: 'Program',
          body: [
            {
              type: 'ExpressionStatement',
              expression: {
                type: 'BinaryExpression',
                left: {type: 'Identifier', name: 'a'},
                operator: '+',
                right: {type: 'Literal', value: 1, raw: '1'}
              }
            }
          ],
          sourceType: 'module'
        }
      }
    },
    {
      type: 'paragraph',
      children: [
        {type: 'text', value: 'b '},
        {
          type: 'mdxTextExpression',
          value: 'true',
          data: {
            estree: {
              type: 'Program',
              body: [
                {
                  type: 'ExpressionStatement',
                  expression: {type: 'Literal', value: true, raw: 'true'}
                }
              ],
              sourceType: 'module'
            }
          }
        },
        {type: 'text', value: '.'}
      ]
    }
  ]
}
```

```markdown
{
  a + 1
}

b {true}.
```

## API

This package exports the identifiers
[`mdxExpressionFromMarkdown`][api-mdx-expression-from-markdown] and
[`mdxExpressionToMarkdown`][api-mdx-expression-to-markdown].
There is no default export.

### `mdxExpressionFromMarkdown()`

Create an extension for [`mdast-util-from-markdown`][mdast-util-from-markdown]
to enable MDX expressions in markdown.

When using the [micromark syntax extension][extension] with `addResult`, nodes
will have a `data.estree` field set to an ESTree [`Program`][program] node.

###### Returns

Extension for `mdast-util-from-markdown` to enable MDX expressions
([`FromMarkdownExtension`][from-markdown-extension]).

### `mdxExpressionToMarkdown()`

Create an extension for [`mdast-util-to-markdown`][mdast-util-to-markdown]
to enable MDX expressions in markdown.

###### Returns

Extension for `mdast-util-to-markdown` to enable MDX expressions
([`ToMarkdownExtension`][to-markdown-extension]).

### `MdxFlowExpression`

MDX expression node, occurring in flow (block) (TypeScript type).

###### Type

```ts
import type {Program} from 'estree-jsx'
import type {Data, Literal} from 'mdast'

interface MdxFlowExpression extends Literal {
  type: 'mdxFlowExpression'
  data?: MdxFlowExpressionData | undefined
}

interface MdxFlowExpressionData extends Data {
  estree?: Program | null | undefined
}
```

### `MdxTextExpression`

MDX expression node, occurring in text (block) (TypeScript type).

###### Type

```ts
import type {Program} from 'estree-jsx'
import type {Data, Literal} from 'mdast'

interface MdxTextExpression extends Literal {
  type: 'mdxTextExpression'
  data?: MdxTextExpressionData | undefined
}

interface MdxTextExpressionData extends Data {
  estree?: Program | null | undefined
}
```

### `MdxFlowExpressionHast`

Same as [`MdxFlowExpression`][api-mdx-flow-expression], but registered with
`@types/hast` (TypeScript type).

###### Type

```ts
import type {Program} from 'estree-jsx'
import type {Data, Literal} from 'hast'

interface MdxFlowExpressionHast extends Literal {
  type: 'mdxFlowExpression'
  data?: MdxFlowExpressionData | undefined
}

interface MdxFlowExpressionData extends Data {
  estree?: Program | null | undefined
}
```

### `MdxTextExpressionHast`

Same as [`MdxTextExpression`][api-mdx-text-expression], but registered with
`@types/hast` (TypeScript type).

###### Type

```ts
import type {Program} from 'estree-jsx'
import type {Data, Literal} from 'hast'

interface MdxTextExpressionHast extends Literal {
  type: 'mdxTextExpression'
  data?: MdxTextExpressionData | undefined
}

interface MdxTextExpressionData extends Data {
  estree?: Program | null | undefined
}
```

## HTML

MDX expressions have no representation in HTML.
Though, when you are dealing with MDX, you will likely go *through* hast.
You can enable passing MDX expressions through to hast by configuring
[`mdast-util-to-hast`][mdast-util-to-hast] with
`passThrough: ['mdxFlowExpression', 'mdxTextExpression']`.

## Syntax

See [Syntax in `micromark-extension-mdx-expression`][syntax].

## Syntax tree

The following interfaces are added to **[mdast][]** by this utility.

### Nodes

#### `MdxFlowExpression`

```idl
interface MdxFlowExpression <: Literal {
  type: 'mdxFlowExpression'
}
```

**MdxFlowExpression** (**[Literal][dfn-literal]**) represents a JavaScript
expression embedded in flow (block).
It can be used where **[flow][dfn-flow-content]** content is expected.
Its content is represented by its `value` field.

For example, the following markdown:

```markdown
{
  1 + 1
}
```

Yields:

```js
{type: 'mdxFlowExpression', value: '\n1 + 1\n'}
```

#### `MdxTextExpression`

```idl
interface MdxTextExpression <: Literal {
  type: 'mdxTextExpression"
}
```

**MdxTextExpression** (**[Literal][dfn-literal]**) represents a JavaScript
expression embedded in text (span, inline).
It can be used where **[phrasing][dfn-phrasing-content]** content is expected.
Its content is represented by its `value` field.

For example, the following markdown:

```markdown
a {1 + 1} b.
```

Yields:

```js
{type: 'mdxTextExpression', value: '1 + 1'}
```

### Content model

#### `FlowContent` (MDX expression)

```idl
type FlowContentMdxExpression = MdxFlowExpression | FlowContent
```

#### `PhrasingContent` (MDX expression)

```idl
type PhrasingContentMdxExpression = MdxTextExpression | PhrasingContent
```

## Types

This package is fully typed with [TypeScript][].
It exports the additional types [`MdxFlowExpression`][api-mdx-flow-expression],
[`MdxFlowExpressionHast`][api-mdx-flow-expression-hast],
[`MdxTextExpression`][api-mdx-text-expression], and
[`MdxTextExpressionHast`][api-mdx-text-expression-hast].

It also registers the node types with `@types/mdast` and `@types/hast`.
If you’re working with the syntax tree, make sure to import this utility
somewhere in your types, as that registers the new node types in the tree.

```js
/**
 * @import {} from 'mdast-util-mdx-expression'
 * @import {Root} from 'mdast'
 */

import {visit} from 'unist-util-visit'

/** @type {Root} */
const tree = getMdastNodeSomeHow()

visit(tree, function (node) {
  // `node` can now be an expression node.
})
```

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`mdast-util-mdx-expression@^2`, compatible with Node.js 16.

This utility works with `mdast-util-from-markdown` version 2+ and
`mdast-util-to-markdown` version 2+.

## Related

* [`remarkjs/remark-mdx`][remark-mdx]
  — remark plugin to support MDX
* [`syntax-tree/mdast-util-mdx`][mdast-util-mdx]
  — mdast utility to support MDX
* [`micromark/micromark-extension-mdx-expression`][extension]
  — micromark extension to parse MDX expressions

## Contribute

See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
ways to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/syntax-tree/mdast-util-mdx-expression/workflows/main/badge.svg

[build]: https://github.com/syntax-tree/mdast-util-mdx-expression/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/mdast-util-mdx-expression.svg

[coverage]: https://codecov.io/github/syntax-tree/mdast-util-mdx-expression

[downloads-badge]: https://img.shields.io/npm/dm/mdast-util-mdx-expression.svg

[downloads]: https://www.npmjs.com/package/mdast-util-mdx-expression

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=mdast-util-mdx-expression

[size]: https://bundlejs.com/?q=mdast-util-mdx-expression

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/syntax-tree/unist/discussions

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[typescript]: https://www.typescriptlang.org

[license]: license

[author]: https://wooorm.com

[health]: https://github.com/syntax-tree/.github

[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md

[support]: https://github.com/syntax-tree/.github/blob/main/support.md

[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md

[mdast]: https://github.com/syntax-tree/mdast

[mdast-util-to-hast]: https://github.com/syntax-tree/mdast-util-to-hast

[mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown

[mdast-util-to-markdown]: https://github.com/syntax-tree/mdast-util-to-markdown

[mdast-util-mdx]: https://github.com/syntax-tree/mdast-util-mdx

[extension]: https://github.com/micromark/micromark-extension-mdx-expression

[syntax]: https://github.com/micromark/micromark-extension-mdx-expression#syntax

[program]: https://github.com/estree/estree/blob/master/es2015.md#programs

[dfn-literal]: https://github.com/syntax-tree/mdast#literal

[remark-mdx]: https://mdxjs.com/packages/remark-mdx/

[mdx]: https://mdxjs.com

[from-markdown-extension]: https://github.com/syntax-tree/mdast-util-from-markdown#extension

[to-markdown-extension]: https://github.com/syntax-tree/mdast-util-to-markdown#options

[api-mdx-expression-from-markdown]: #mdxexpressionfrommarkdown

[api-mdx-expression-to-markdown]: #mdxexpressiontomarkdown

[api-mdx-flow-expression]: #mdxflowexpression

[api-mdx-text-expression]: #mdxtextexpression

[api-mdx-flow-expression-hast]: #mdxflowexpressionhast

[api-mdx-text-expression-hast]: #mdxtextexpressionhast

[dfn-flow-content]: #flowcontent-mdx-expression

[dfn-phrasing-content]: #phrasingcontent-mdx-expression


---

# mdast-util-mdx-jsx

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[mdast][] extensions to parse and serialize [MDX][] JSX (`<a />`).

## Contents

* [What is this?](#what-is-this)
* [When to use this](#when-to-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`mdxJsxFromMarkdown()`](#mdxjsxfrommarkdown)
  * [`mdxJsxToMarkdown(options?)`](#mdxjsxtomarkdownoptions)
  * [`MdxJsxAttribute`](#mdxjsxattribute)
  * [`MdxJsxAttributeValueExpression`](#mdxjsxattributevalueexpression)
  * [`MdxJsxExpressionAttribute`](#mdxjsxexpressionattribute)
  * [`MdxJsxFlowElement`](#mdxjsxflowelement)
  * [`MdxJsxFlowElementHast`](#mdxjsxflowelementhast)
  * [`MdxJsxTextElement`](#mdxjsxtextelement)
  * [`MdxJsxTextElementHast`](#mdxjsxtextelementhast)
  * [`ToMarkdownOptions`](#tomarkdownoptions)
* [HTML](#html)
* [Syntax](#syntax)
* [Syntax tree](#syntax-tree)
  * [Nodes](#nodes)
  * [Mixin](#mixin)
  * [Content model](#content-model)
* [Types](#types)
* [Compatibility](#compatibility)
* [Related](#related)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package contains two extensions that add support for MDX JSX syntax in
markdown to [mdast][].
These extensions plug into
[`mdast-util-from-markdown`][mdast-util-from-markdown] (to support parsing
JSX in markdown into a syntax tree) and
[`mdast-util-to-markdown`][mdast-util-to-markdown] (to support serializing
JSX in syntax trees to markdown).

[JSX][] is an XML-like syntax extension to ECMAScript (JavaScript), which MDX
brings to markdown.
For more info on MDX, see [What is MDX?][what-is-mdx]

## When to use this

You can use these extensions when you are working with
`mdast-util-from-markdown` and `mdast-util-to-markdown` already.

When working with `mdast-util-from-markdown`, you must combine this package
with [`micromark-extension-mdx-jsx`][micromark-extension-mdx-jsx].

When you are working with syntax trees and want all of MDX, use
[`mdast-util-mdx`][mdast-util-mdx] instead.

All these packages are used in [`remark-mdx`][remark-mdx], which
focusses on making it easier to transform content by abstracting these
internals away.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install mdast-util-mdx-jsx
```

In Deno with [`esm.sh`][esmsh]:

```js
import {mdxJsxFromMarkdown, mdxJsxToMarkdown} from 'https://esm.sh/mdast-util-mdx-jsx@3'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {mdxJsxFromMarkdown, mdxJsxToMarkdown} from 'https://esm.sh/mdast-util-mdx-jsx@3?bundle'
</script>
```

## Use

Say our document `example.mdx` contains:

```mdx
<Box>
  - a list
</Box>

<MyComponent {...props} />

<abbr title="Hypertext Markup Language">HTML</abbr> is a lovely language.
```

…and our module `example.js` looks as follows:

```js
import fs from 'node:fs/promises'
import * as acorn from 'acorn'
import {mdxJsx} from 'micromark-extension-mdx-jsx'
import {fromMarkdown} from 'mdast-util-from-markdown'
import {mdxJsxFromMarkdown, mdxJsxToMarkdown} from 'mdast-util-mdx-jsx'
import {toMarkdown} from 'mdast-util-to-markdown'

const doc = await fs.readFile('example.mdx')

const tree = fromMarkdown(doc, {
  extensions: [mdxJsx({acorn, addResult: true})],
  mdastExtensions: [mdxJsxFromMarkdown()]
})

console.log(tree)

const out = toMarkdown(tree, {extensions: [mdxJsxToMarkdown()]})

console.log(out)
```

…now running `node example.js` yields (positional info removed for brevity):

```js
{
  type: 'root',
  children: [
    {
      type: 'mdxJsxFlowElement',
      name: 'Box',
      attributes: [],
      children: [
        {
          type: 'list',
          ordered: false,
          start: null,
          spread: false,
          children: [
            {
              type: 'listItem',
              spread: false,
              checked: null,
              children: [
                {type: 'paragraph', children: [{type: 'text', value: 'a list'}]}
              ]
            }
          ]
        }
      ]
    },
    {
      type: 'mdxJsxFlowElement',
      name: 'MyComponent',
      attributes: [
        {
          type: 'mdxJsxExpressionAttribute',
          value: '...props',
          data: {
            estree: {
              type: 'Program',
              body: [
                {
                  type: 'ExpressionStatement',
                  expression: {
                    type: 'ObjectExpression',
                    properties: [
                      {
                        type: 'SpreadElement',
                        argument: {type: 'Identifier', name: 'props'}
                      }
                    ]
                  }
                }
              ],
              sourceType: 'module'
            }
          }
        }
      ],
      children: []
    },
    {
      type: 'paragraph',
      children: [
        {
          type: 'mdxJsxTextElement',
          name: 'abbr',
          attributes: [
            {
              type: 'mdxJsxAttribute',
              name: 'title',
              value: 'Hypertext Markup Language'
            }
          ],
          children: [{type: 'text', value: 'HTML'}]
        },
        {type: 'text', value: ' is a lovely language.'}
      ]
    }
  ]
}
```

```markdown
<Box>
  *   a list
</Box>

<MyComponent {...props} />

<abbr title="Hypertext Markup Language">HTML</abbr> is a lovely language.
```

## API

This package exports the identifiers
[`mdxJsxFromMarkdown`][api-mdx-jsx-from-markdown] and
[`mdxJsxToMarkdown`][api-mdx-jsx-to-markdown].
There is no default export.

### `mdxJsxFromMarkdown()`

Create an extension for
[`mdast-util-from-markdown`][mdast-util-from-markdown]
to enable MDX JSX.

###### Returns

Extension for `mdast-util-from-markdown` to enable MDX JSX
([`FromMarkdownExtension`][from-markdown-extension]).

When using the [micromark syntax extension][micromark-extension-mdx-jsx] with
`addResult`, nodes will have a `data.estree` field set to an ESTree
[`Program`][program] node.

### `mdxJsxToMarkdown(options?)`

Create an extension for
[`mdast-util-to-markdown`][mdast-util-to-markdown]
to enable MDX JSX.

This extension configures `mdast-util-to-markdown` with
[`options.fences: true`][mdast-util-to-markdown-fences] and
[`options.resourceLink: true`][mdast-util-to-markdown-resourcelink] too, do not
overwrite them!

###### Parameters

* `options` ([`ToMarkdownOptions`][api-to-markdown-options])
  — configuration

###### Returns

Extension for `mdast-util-to-markdown` to enable MDX JSX
([`FromMarkdownExtension`][to-markdown-extension]).

### `MdxJsxAttribute`

MDX JSX attribute with a key (TypeScript type).

###### Type

```ts
import type {Literal} from 'mdast'

interface MdxJsxAttribute extends Literal {
  type: 'mdxJsxAttribute'
  name: string
  value?: MdxJsxAttributeValueExpression | string | null | undefined
}
```

### `MdxJsxAttributeValueExpression`

MDX JSX attribute value set to an expression (TypeScript type).

###### Type

```ts
import type {Program} from 'estree-jsx'
import type {Literal} from 'mdast'

interface MdxJsxAttributeValueExpression extends Literal {
  type: 'mdxJsxAttributeValueExpression'
  data?: {estree?: Program | null | undefined} & Literal['data']
}
```

### `MdxJsxExpressionAttribute`

MDX JSX attribute as an expression (TypeScript type).

###### Type

```ts
import type {Program} from 'estree-jsx'
import type {Literal} from 'mdast'

interface MdxJsxExpressionAttribute extends Literal {
  type: 'mdxJsxExpressionAttribute'
  data?: {estree?: Program | null | undefined} & Literal['data']
}
```

### `MdxJsxFlowElement`

MDX JSX element node, occurring in flow (block) (TypeScript type).

###### Type

```ts
import type {BlockContent, DefinitionContent, Parent} from 'mdast'

export interface MdxJsxFlowElement extends Parent {
  type: 'mdxJsxFlowElement'
  name: string | null
  attributes: Array<MdxJsxAttribute | MdxJsxExpressionAttribute>
  children: Array<BlockContent | DefinitionContent>
}
```

### `MdxJsxFlowElementHast`

Same as [`MdxJsxFlowElement`][api-mdx-jsx-flow-element], but registered with
`@types/hast` (TypeScript type).

###### Type

```ts
import type {ElementContent, Parent} from 'hast'

export interface MdxJsxFlowElementHast extends Parent {
  type: 'mdxJsxFlowElement'
  name: string | null
  attributes: Array<MdxJsxAttribute | MdxJsxExpressionAttribute>
  children: Array<ElementContent>
}
```

### `MdxJsxTextElement`

MDX JSX element node, occurring in text (phrasing) (TypeScript type).

###### Type

```ts
import type {Parent, PhrasingContent} from 'mdast'

export interface MdxJsxTextElement extends Parent {
  type: 'mdxJsxTextElement'
  name: string | null
  attributes: Array<MdxJsxAttribute | MdxJsxExpressionAttribute>
  children: Array<PhrasingContent>
}
```

### `MdxJsxTextElementHast`

Same as [`MdxJsxTextElement`][api-mdx-jsx-text-element], but registered with
`@types/hast` (TypeScript type).

###### Type

```ts
import type {ElementContent, Parent} from 'hast'

export interface MdxJsxTextElementHast extends Parent {
  type: 'mdxJsxTextElement'
  name: string | null
  attributes: Array<MdxJsxAttribute | MdxJsxExpressionAttribute>
  children: Array<ElementContent>
}
```

### `ToMarkdownOptions`

Configuration (TypeScript type).

##### Fields

* `quote` (`'"'` or `"'"`, default: `'"'`)
  — preferred quote to use around attribute values
* `quoteSmart` (`boolean`, default: `false`)
  — use the other quote if that results in less bytes
* `tightSelfClosing` (`boolean`, default: `false`)
  — do not use an extra space when closing self-closing elements: `<img/>`
  instead of `<img />`
* `printWidth` (`number`, default: `Infinity`)
  — try and wrap syntax at this width.
  When set to a finite number (say, `80`), the formatter will print
  attributes on separate lines when a tag doesn’t fit on one line.
  The normal behavior is to print attributes with spaces between them instead
  of line endings

## HTML

MDX JSX has no representation in HTML.
Though, when you are dealing with MDX, you will likely go *through* hast.
You can enable passing MDX JSX through to hast by configuring
[`mdast-util-to-hast`][mdast-util-to-hast] with
`passThrough: ['mdxJsxFlowElement', 'mdxJsxTextElement']`.

## Syntax

See [Syntax in `micromark-extension-mdx-jsx`][syntax].

## Syntax tree

The following interfaces are added to **[mdast][]** by this utility.

### Nodes

#### `MdxJsxFlowElement`

```idl
interface MdxJsxFlowElement <: Parent {
  type: 'mdxJsxFlowElement'
}

MdxJsxFlowElement includes MdxJsxElement
```

**MdxJsxFlowElement** (**[Parent][dfn-parent]**) represents JSX in flow (block).
It can be used where **[flow][dfn-content-flow]** content is expected.
It includes the mixin **[MdxJsxElement][dfn-mixin-mdx-jsx-element]**.

For example, the following markdown:

```markdown
<w x="y">
  z
</w>
```

Yields:

```js
{
  type: 'mdxJsxFlowElement',
  name: 'w',
  attributes: [{type: 'mdxJsxAttribute', name: 'x', value: 'y'}],
  children: [{type: 'paragraph', children: [{type: 'text', value: 'z'}]}]
}
```

#### `MdxJsxTextElement`

```idl
interface MdxJsxTextElement <: Parent {
  type: 'mdxJsxTextElement'
}

MdxJsxTextElement includes MdxJsxElement
```

**MdxJsxTextElement** (**[Parent][dfn-parent]**) represents JSX in text (span,
inline).
It can be used where **[phrasing][dfn-content-phrasing]** content is
expected.
It includes the mixin **[MdxJsxElement][dfn-mixin-mdx-jsx-element]**.

For example, the following markdown:

```markdown
a <b c>d</b> e.
```

Yields:

```js
{
  type: 'mdxJsxTextElement',
  name: 'b',
  attributes: [{type: 'mdxJsxAttribute', name: 'c', value: null}],
  children: [{type: 'text', value: 'd'}]
}
```

### Mixin

#### `MdxJsxElement`

```idl
interface mixin MdxJsxElement {
  name: string?
  attributes: [MdxJsxExpressionAttribute | MdxJsxAttribute]
}

interface MdxJsxExpressionAttribute <: Literal {
  type: 'mdxJsxExpressionAttribute'
}

interface MdxJsxAttribute <: Node {
  type: 'mdxJsxAttribute'
  name: string
  value: MdxJsxAttributeValueExpression | string?
}

interface MdxJsxAttributeValueExpression <: Literal {
  type: 'mdxJsxAttributeValueExpression'
}
```

**MdxJsxElement** represents a JSX element.

The `name` field can be present and represents an identifier.
Without `name`, the element represents a fragment, in which case no attributes
must be present.

The `attributes` field represents information associated with the node.
The value of the `attributes` field is a list of **MdxJsxExpressionAttribute**
and **MdxJsxAttribute** nodes.

**MdxJsxExpressionAttribute** represents an expression (typically in a
programming language) that when evaluated results in multiple attributes.

**MdxJsxAttribute** represents a single attribute.
The `name` field must be present.
The `value` field can be present, in which case it is either a string (a static
value) or an expression (typically in a programming language) that when
evaluated results in an attribute value.

### Content model

###### `FlowContent` (MDX JSX)

```idl
type MdxJsxFlowContent = MdxJsxFlowElement | FlowContent
```

###### `PhrasingContent` (MDX JSX)

```idl
type MdxJsxPhrasingContent = MdxJsxTextElement | PhrasingContent
```

## Types

This package is fully typed with [TypeScript][].
It exports the additional types  [`MdxJsxAttribute`][api-mdx-jsx-attribute],
[`MdxJsxAttributeValueExpression`][api-mdx-jsx-attribute-value-expression],
[`MdxJsxExpressionAttribute`][api-mdx-jsx-expression-attribute],
[`MdxJsxFlowElement`][api-mdx-jsx-flow-element],
[`MdxJsxFlowElementHast`][api-mdx-jsx-flow-element-hast],
[`MdxJsxTextElement`][api-mdx-jsx-text-element],
[`MdxJsxTextElementHast`][api-mdx-jsx-text-element-hast], and
[`ToMarkdownOptions`][api-to-markdown-options].

It also registers the node types with `@types/mdast` and `@types/hast`.
If you’re working with the syntax tree, make sure to import this utility
somewhere in your types, as that registers the new node types in the tree.

```js
/**
 * @import {} from 'mdast-util-mdx-jsx'
 * @import {Root} from 'mdast'
 */

import {visit} from 'unist-util-visit'

/** @type {Root} */
const tree = getMdastNodeSomeHow()

visit(tree, function (node) {
  // `node` can now be one of the JSX nodes.
})
```

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, `mdast-util-mdx-jsx@3`,
compatible with Node.js 16.

This utility works with `mdast-util-from-markdown` version 2+ and
`mdast-util-to-markdown` version 2+.

## Related

* [`micromark/micromark-extension-mdx-jsx`][micromark-extension-mdx-jsx]
  — support MDX JSX in micromark
* [`syntax-tree/mdast-util-mdx`][mdast-util-mdx]
  — support MDX in mdast
* [`remarkjs/remark-mdx`][remark-mdx]
  — support MDX in remark

## Contribute

See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
ways to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

[build-badge]: https://github.com/syntax-tree/mdast-util-mdx-jsx/workflows/main/badge.svg

[build]: https://github.com/syntax-tree/mdast-util-mdx-jsx/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/mdast-util-mdx-jsx.svg

[coverage]: https://codecov.io/github/syntax-tree/mdast-util-mdx-jsx

[downloads-badge]: https://img.shields.io/npm/dm/mdast-util-mdx-jsx.svg

[downloads]: https://www.npmjs.com/package/mdast-util-mdx-jsx

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=mdast-util-mdx-jsx

[size]: https://bundlejs.com/?q=mdast-util-mdx-jsx

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/syntax-tree/unist/discussions

[npm]: https://docs.npmjs.com/cli/install

[esmsh]: https://esm.sh

[license]: license

[author]: https://wooorm.com

[health]: https://github.com/syntax-tree/.github

[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md

[support]: https://github.com/syntax-tree/.github/blob/main/support.md

[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[typescript]: https://www.typescriptlang.org

[mdast]: https://github.com/syntax-tree/mdast

[mdast-util-to-hast]: https://github.com/syntax-tree/mdast-util-to-hast

[mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown

[from-markdown-extension]: https://github.com/syntax-tree/mdast-util-from-markdown#extension

[mdast-util-to-markdown]: https://github.com/syntax-tree/mdast-util-to-markdown

[to-markdown-extension]: https://github.com/syntax-tree/mdast-util-to-markdown#options

[mdast-util-mdx]: https://github.com/syntax-tree/mdast-util-mdx

[program]: https://github.com/estree/estree/blob/master/es2015.md#programs

[dfn-parent]: https://github.com/syntax-tree/mdast#parent

[dfn-content-flow]: #flowcontent-mdx-jsx

[dfn-content-phrasing]: #phrasingcontent-mdx-jsx

[dfn-mixin-mdx-jsx-element]: #mdxjsxelement

[jsx]: https://facebook.github.io/jsx/

[what-is-mdx]: https://mdxjs.com/docs/what-is-mdx/

[micromark-extension-mdx-jsx]: https://github.com/micromark/micromark-extension-mdx-jsx

[syntax]: https://github.com/micromark/micromark-extension-mdx-jsx#syntax

[mdast-util-to-markdown-fences]: https://github.com/syntax-tree/mdast-util-to-markdown#optionsfences

[mdast-util-to-markdown-resourcelink]: https://github.com/syntax-tree/mdast-util-to-markdown#optionsresourcelink

[remark-mdx]: https://mdxjs.com/packages/remark-mdx/

[mdx]: https://mdxjs.com

[api-mdx-jsx-from-markdown]: #mdxjsxfrommarkdown

[api-mdx-jsx-to-markdown]: #mdxjsxtomarkdownoptions

[api-mdx-jsx-attribute]: #mdxjsxattribute

[api-mdx-jsx-attribute-value-expression]: #mdxjsxattributevalueexpression

[api-mdx-jsx-expression-attribute]: #mdxjsxexpressionattribute

[api-mdx-jsx-flow-element]: #mdxjsxflowelement

[api-mdx-jsx-flow-element-hast]: #mdxjsxflowelementhast

[api-mdx-jsx-text-element]: #mdxjsxtextelement

[api-mdx-jsx-text-element-hast]: #mdxjsxtextelementhast

[api-to-markdown-options]: #tomarkdownoptions


---

# mdast-util-mdxjs-esm

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[mdast][] extensions to parse and serialize [MDX][] ESM (import/exports).

## Contents

*   [What is this?](#what-is-this)
*   [When to use this](#when-to-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`mdxjsEsmFromMarkdown()`](#mdxjsesmfrommarkdown)
    *   [`mdxjsEsmToMarkdown()`](#mdxjsesmtomarkdown)
    *   [`MdxjsEsm`](#mdxjsesm)
    *   [`MdxjsEsmHast`](#mdxjsesmhast)
*   [HTML](#html)
*   [Syntax](#syntax)
*   [Syntax tree](#syntax-tree)
    *   [Nodes](#nodes)
    *   [Content model](#content-model)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package contains two extensions that add support for MDX ESM syntax in
markdown to [mdast][].
These extensions plug into
[`mdast-util-from-markdown`][mdast-util-from-markdown] (to support parsing
ESM in markdown into a syntax tree) and
[`mdast-util-to-markdown`][mdast-util-to-markdown] (to support serializing
ESM in syntax trees to markdown).

## When to use this

You can use these extensions when you are working with
`mdast-util-from-markdown` and `mdast-util-to-markdown` already.

When working with `mdast-util-from-markdown`, you must combine this package
with [`micromark-extension-mdxjs-esm`][extension].

When you are working with syntax trees and want all of MDX, use
[`mdast-util-mdx`][mdast-util-mdx] instead.

All these packages are used in [`remark-mdx`][remark-mdx], which
focusses on making it easier to transform content by abstracting these
internals away.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install mdast-util-mdxjs-esm
```

In Deno with [`esm.sh`][esmsh]:

```js
import {mdxjsEsmFromMarkdown, mdxjsEsmToMarkdown} from 'https://esm.sh/mdast-util-mdxjs-esm@2'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {mdxjsEsmFromMarkdown, mdxjsEsmToMarkdown} from 'https://esm.sh/mdast-util-mdxjs-esm@2?bundle'
</script>
```

## Use

Say our document `example.mdx` contains:

```mdx
import a from 'b'
export const c = ''

d
```

…and our module `example.js` looks as follows:

```js
import fs from 'node:fs/promises'
import * as acorn from 'acorn'
import {fromMarkdown} from 'mdast-util-from-markdown'
import {toMarkdown} from 'mdast-util-to-markdown'
import {mdxjsEsm} from 'micromark-extension-mdxjs-esm'
import {mdxjsEsmFromMarkdown, mdxjsEsmToMarkdown} from 'mdast-util-mdxjs-esm'

const doc = await fs.readFile('example.mdx')

const tree = fromMarkdown(doc, {
  extensions: [mdxjsEsm({acorn, addResult: true})],
  mdastExtensions: [mdxjsEsmFromMarkdown()]
})

console.log(tree)

const out = toMarkdown(tree, {extensions: [mdxjsEsmToMarkdown()]})

console.log(out)
```

…now running `node example.js` yields (positional info removed for brevity):

```js
{
  type: 'root',
  children: [
    {
      type: 'mdxjsEsm',
      value: "import a from 'b'\nexport const c = ''",
      data: {
        estree: {
          type: 'Program',
          body: [
            {
              type: 'ImportDeclaration',
              specifiers: [
                {
                  type: 'ImportDefaultSpecifier',
                  local: {type: 'Identifier', name: 'a'}
                }
              ],
              source: {type: 'Literal', value: 'b', raw: "'b'"}
            },
            {
              type: 'ExportNamedDeclaration',
              declaration: {
                type: 'VariableDeclaration',
                declarations: [
                  {
                    type: 'VariableDeclarator',
                    id: {type: 'Identifier', name: 'c'},
                    init: {type: 'Literal', value: '', raw: "''"}
                  }
                ],
                kind: 'const'
              },
              specifiers: [],
              source: null
            }
          ],
          sourceType: 'module'
        }
      }
    },
    {type: 'paragraph', children: [{type: 'text', value: 'd'}]}
  ]
}
```

```markdown
import a from 'b'
export const c = ''

d
```

## API

This package exports the identifiers
[`mdxjsEsmFromMarkdown`][api-mdxjs-esm-from-markdown] and
[`mdxjsEsmToMarkdown`][api-mdxjs-esm-to-markdown].
There is no default export.

### `mdxjsEsmFromMarkdown()`

Create an extension for [`mdast-util-from-markdown`][mdast-util-from-markdown]
to enable MDX.js ESM in markdown.

When using the [micromark syntax extension][extension] with `addResult`, nodes
will have a `data.estree` field set to an ESTree [`Program`][program] node.

###### Returns

Extension for `mdast-util-from-markdown` to enable MDX.js ESM
([`FromMarkdownExtension`][from-markdown-extension]).

### `mdxjsEsmToMarkdown()`

Create an extension for [`mdast-util-to-markdown`][mdast-util-to-markdown]
to enable MDX.js ESM in markdown.

###### Returns

Extension for `mdast-util-to-markdown` to enable MDX.js ESM
([`ToMarkdownExtension`][to-markdown-extension]).

### `MdxjsEsm`

MDX ESM (import/export) node (TypeScript type).

###### Type

```ts
import type {Program} from 'estree-jsx'
import type {Data, Literal} from 'mdast'

interface MdxjsEsm extends Literal {
  type: 'mdxjsEsm'
  data?: MdxjsEsmData | undefined
}

export interface MdxjsEsmData extends Data {
  estree?: Program | null | undefined
}
```

### `MdxjsEsmHast`

Same as [`MdxjsEsm`][api-mdxjs-esm], but registered with `@types/hast`
(TypeScript type).

###### Type

```ts
import type {Program} from 'estree-jsx'
import type {Data, Literal} from 'hast'

interface MdxjsEsmHast extends Literal {
  type: 'mdxjsEsm'
  data?: MdxjsEsmHastData | undefined
}

export interface MdxjsEsmHastData extends Data {
  estree?: Program | null | undefined
}
```

## HTML

MDX ESM has no representation in HTML.
Though, when you are dealing with MDX, you will likely go *through* hast.
You can enable passing MDX ESM through to hast by configuring
[`mdast-util-to-hast`][mdast-util-to-hast] with `passThrough: ['mdxjsEsm']`.

## Syntax

See [Syntax in `micromark-extension-mdxjs-esm`][syntax].

## Syntax tree

The following interfaces are added to **[mdast][]** by this utility.

### Nodes

#### `MdxjsEsm`

```idl
interface MdxjsEsm <: Literal {
  type: 'mdxjsEsm'
}
```

**MdxjsEsm** (**[Literal][dfn-literal]**) represents ESM import/exports
embedded in MDX.
It can be used where **[flow][dfn-flow-content]** content is expected.
Its content is represented by its `value` field.

For example, the following Markdown:

```markdown
import a from 'b'
```

Yields:

```js
{
  type: 'mdxjsEsm',
  value: 'import a from \'b\''
}
```

### Content model

#### `FlowContent` (MDX.js ESM)

```idl
type FlowContentMdxjsEsm = MdxjsEsm | FlowContent
```

Note that when ESM is present, it can only exist as top-level content: if it has
a *[parent][dfn-parent]*, that parent must be **[Root][dfn-root]**.

## Types

This package is fully typed with [TypeScript][].
It exports the additional types [`MdxjsEsm`][api-mdxjs-esm] and
[`MdxjsEsmHast`][api-mdxjs-esm-hast].

It also registers the node type with `@types/mdast` and `@types/hast`.
If you’re working with the syntax tree, make sure to import this utility
somewhere in your types, as that registers the new node types in the tree.

```js
/**
 * @typedef {import('mdast-util-mdxjs-esm')}
 */

import {visit} from 'unist-util-visit'

/** @type {import('mdast').Root} */
const tree = getMdastNodeSomeHow()

visit(tree, function (node) {
  // `node` can now be an ESM node.
})
```

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, `mdast-util-mdxjs-esm@^2`,
compatible with Node.js 16.

This utility works with `mdast-util-from-markdown` version 2+ and
`mdast-util-to-markdown` version 2+.

## Related

*   [`remarkjs/remark-mdx`][remark-mdx]
    — remark plugin to support MDX
*   [`syntax-tree/mdast-util-mdx`][mdast-util-mdx]
    — mdast utility to support MDX
*   [`micromark/micromark-extension-mdxjs-esm`][extension]
    — micromark extension to parse MDX.js ESM

## Contribute

See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
ways to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/syntax-tree/mdast-util-mdxjs-esm/workflows/main/badge.svg

[build]: https://github.com/syntax-tree/mdast-util-mdxjs-esm/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/mdast-util-mdxjs-esm.svg

[coverage]: https://codecov.io/github/syntax-tree/mdast-util-mdxjs-esm

[downloads-badge]: https://img.shields.io/npm/dm/mdast-util-mdxjs-esm.svg

[downloads]: https://www.npmjs.com/package/mdast-util-mdxjs-esm

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=mdast-util-mdxjs-esm

[size]: https://bundlejs.com/?q=mdast-util-mdxjs-esm

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/syntax-tree/unist/discussions

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[typescript]: https://www.typescriptlang.org

[license]: license

[author]: https://wooorm.com

[health]: https://github.com/syntax-tree/.github

[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md

[support]: https://github.com/syntax-tree/.github/blob/main/support.md

[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md

[mdast]: https://github.com/syntax-tree/mdast

[mdast-util-to-hast]: https://github.com/syntax-tree/mdast-util-to-hast

[mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown

[mdast-util-to-markdown]: https://github.com/syntax-tree/mdast-util-to-markdown

[mdast-util-mdx]: https://github.com/syntax-tree/mdast-util-mdx

[extension]: https://github.com/micromark/micromark-extension-mdxjs-esm

[syntax]: https://github.com/micromark/micromark-extension-mdxjs-esm#syntax

[program]: https://github.com/estree/estree/blob/master/es2015.md#programs

[dfn-literal]: https://github.com/syntax-tree/mdast#literal

[dfn-parent]: https://github.com/syntax-tree/unist#parent-1

[dfn-root]: https://github.com/syntax-tree/mdast#root

[remark-mdx]: https://mdxjs.com/packages/remark-mdx/

[mdx]: https://mdxjs.com

[from-markdown-extension]: https://github.com/syntax-tree/mdast-util-from-markdown#extension

[to-markdown-extension]: https://github.com/syntax-tree/mdast-util-to-markdown#options

[dfn-flow-content]: #flowcontent-mdxjs-esm

[api-mdxjs-esm-from-markdown]: #mdxjsesmfrommarkdown

[api-mdxjs-esm-to-markdown]: #mdxjsesmtomarkdown

[api-mdxjs-esm]: #mdxjsesm

[api-mdxjs-esm-hast]: #mdxjsesmhast


---

# mdast-util-phrasing

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[mdast][] utility to check if a node is phrasing content.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`phrasing(value)`](#phrasingvalue)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Security](#security)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package is a tiny utility to check that a given [node][] is [phrasing
content][phrasing].

## When should I use this?

This utility is typically useful if you’re making other utilities.
It uses [`unist-util-is`][unist-util-is], which you can use for your own checks.

A different utility, [`hast-util-phrasing`][hast-util-phrasing], does the same
but on [hast][].

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install mdast-util-phrasing
```

In Deno with [`esm.sh`][esmsh]:

```js
import {phrasing} from 'https://esm.sh/mdast-util-phrasing@4'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {phrasing} from 'https://esm.sh/mdast-util-phrasing@4?bundle'
</script>
```

## Use

```js
import {phrasing} from 'mdast-util-phrasing'

phrasing({type: 'paragraph', children: [{type: 'text', value: 'Alpha'}]})
// => false

phrasing({type: 'strong', children: [{type: 'text', value: 'Delta'}]})
// => true
```

## API

This package exports the identifier [`phrasing`][api-phrasing].
There is no default export.

### `phrasing(value)`

Check if the given value is *[phrasing content][phrasing]*.

> 👉 **Note**: Excludes `html`, which can be both phrasing or flow.

###### Parameters

*   `value` (`unknown`)
    — thing to check, typically [`Node`][node]

###### Returns

Whether `value` is phrasing content (`boolean`).

## Types

This package is fully typed with [TypeScript][].
It does not export extra types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, `mdast-util-phrasing@^4`,
compatible with Node.js 16.

## Security

Use of `mdast-util-phrasing` does not involve **[hast][]**, user content, or
change the tree, so there are no openings for [cross-site scripting (XSS)][xss]
attacks.

## Related

*   [`hast-util-phrasing`](https://github.com/syntax-tree/hast-util-phrasing)
    — check if a hast node is phrasing content
*   [`unist-util-is`](https://github.com/syntax-tree/unist-util-is)
    — check if a node passes a test

## Contribute

See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
ways to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Victor Felder][author]

<!-- Definitions -->

[build-badge]: https://github.com/syntax-tree/mdast-util-phrasing/workflows/main/badge.svg

[build]: https://github.com/syntax-tree/mdast-util-phrasing/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/mdast-util-phrasing.svg

[coverage]: https://codecov.io/github/syntax-tree/mdast-util-phrasing

[downloads-badge]: https://img.shields.io/npm/dm/mdast-util-phrasing.svg

[downloads]: https://www.npmjs.com/package/mdast-util-phrasing

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=mdast-util-phrasing

[size]: https://bundlejs.com/?q=mdast-util-phrasing

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/syntax-tree/unist/discussions

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[typescript]: https://www.typescriptlang.org

[license]: license

[author]: https://draft.li

[health]: https://github.com/syntax-tree/.github

[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md

[support]: https://github.com/syntax-tree/.github/blob/main/support.md

[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md

[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting

[hast]: https://github.com/syntax-tree/hast

[mdast]: https://github.com/syntax-tree/mdast

[node]: https://github.com/syntax-tree/mdast#nodes

[phrasing]: https://github.com/syntax-tree/mdast#phrasingcontent

[unist-util-is]: https://github.com/syntax-tree/unist-util-is

[hast-util-phrasing]: https://github.com/syntax-tree/hast-util-phrasing

[api-phrasing]: #phrasingvalue


---

# mdast-util-to-hast

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[mdast][] utility to transform to [hast][].

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`defaultFootnoteBackContent(referenceIndex, rereferenceIndex)`](#defaultfootnotebackcontentreferenceindex-rereferenceindex)
  * [`defaultFootnoteBackLabel(referenceIndex, rereferenceIndex)`](#defaultfootnotebacklabelreferenceindex-rereferenceindex)
  * [`defaultHandlers`](#defaulthandlers)
  * [`toHast(tree[, options])`](#tohasttree-options)
  * [`FootnoteBackContentTemplate`](#footnotebackcontenttemplate)
  * [`FootnoteBackLabelTemplate`](#footnotebacklabeltemplate)
  * [`Handler`](#handler)
  * [`Handlers`](#handlers)
  * [`Options`](#options)
  * [`Raw`](#raw)
  * [`State`](#state)
* [Examples](#examples)
  * [Example: supporting HTML in markdown naïvely](#example-supporting-html-in-markdown-naïvely)
  * [Example: supporting HTML in markdown properly](#example-supporting-html-in-markdown-properly)
  * [Example: footnotes in languages other than English](#example-footnotes-in-languages-other-than-english)
  * [Example: supporting custom nodes](#example-supporting-custom-nodes)
* [Algorithm](#algorithm)
  * [Default handling](#default-handling)
  * [Fields on nodes](#fields-on-nodes)
* [CSS](#css)
* [Syntax tree](#syntax-tree)
  * [Nodes](#nodes)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Related](#related)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package is a utility that takes an [mdast][] (markdown) syntax tree as
input and turns it into a [hast][] (HTML) syntax tree.

## When should I use this?

This project is useful when you want to deal with ASTs and turn markdown to
HTML.

The hast utility [`hast-util-to-mdast`][hast-util-to-mdast] does the inverse of
this utility.
It turns HTML into markdown.

The remark plugin [`remark-rehype`][remark-rehype] wraps this utility to also
turn markdown to HTML at a higher-level (easier) abstraction.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install mdast-util-to-hast
```

In Deno with [`esm.sh`][esmsh]:

```js
import {toHast} from 'https://esm.sh/mdast-util-to-hast@13'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {toHast} from 'https://esm.sh/mdast-util-to-hast@13?bundle'
</script>
```

## Use

Say we have the following `example.md`:

```markdown
## Hello **World**!
```

…and next to it a module `example.js`:

```js
import {fs} from 'node:fs/promises'
import {toHtml} from 'hast-util-to-html'
import {fromMarkdown} from 'mdast-util-from-markdown'
import {toHast} from 'mdast-util-to-hast'

const markdown = String(await fs.readFile('example.md'))
const mdast = fromMarkdown(markdown)
const hast = toHast(mdast)
const html = toHtml(hast)

console.log(html)
```

…now running `node example.js` yields:

```html
<h2>Hello <strong>World</strong>!</h2>
```

## API

This package exports the identifiers
[`defaultFootnoteBackContent`][api-default-footnote-back-content],
[`defaultFootnoteBackLabel`][api-default-footnote-back-label],
[`defaultHandlers`][api-default-handlers], and
[`toHast`][api-to-hast].
There is no default export.

### `defaultFootnoteBackContent(referenceIndex, rereferenceIndex)`

Generate the default content that GitHub uses on backreferences.

###### Parameters

* `referenceIndex` (`number`)
  — index of the definition in the order that they are first referenced,
  0-indexed
* `rereferenceIndex` (`number`)
  — index of calls to the same definition, 0-indexed

###### Returns

Content (`Array<ElementContent>`).

### `defaultFootnoteBackLabel(referenceIndex, rereferenceIndex)`

Generate the default label that GitHub uses on backreferences.

###### Parameters

* `referenceIndex` (`number`)
  — index of the definition in the order that they are first referenced,
  0-indexed
* `rereferenceIndex` (`number`)
  — index of calls to the same definition, 0-indexed

###### Returns

Label (`string`).

### `defaultHandlers`

Default handlers for nodes ([`Handlers`][api-handlers]).

### `toHast(tree[, options])`

Transform mdast to hast.

###### Parameters

* `tree` ([`MdastNode`][mdast-node])
  — mdast tree
* `options` ([`Options`][api-options], optional)
  — configuration

###### Returns

hast tree ([`HastNode`][hast-node]).

##### Notes

###### HTML

Raw HTML is available in mdast as [`html`][mdast-html] nodes and can be embedded
in hast as semistandard `raw` nodes.
Most utilities ignore `raw` nodes but two notable ones don’t:

* [`hast-util-to-html`][hast-util-to-html] also has an option
  `allowDangerousHtml` which will output the raw HTML.
  This is typically discouraged as noted by the option name but is useful if
  you completely trust authors
* [`hast-util-raw`][hast-util-raw] can handle the raw embedded HTML strings by
  parsing them into standard hast nodes (`element`, `text`, etc).
  This is a heavy task as it needs a full HTML parser, but it is the only way
  to support untrusted content

###### Footnotes

Many options supported here relate to footnotes.
Footnotes are not specified by CommonMark, which we follow by default.
They are supported by GitHub, so footnotes can be enabled in markdown with
[`mdast-util-gfm`][mdast-util-gfm].

The options `footnoteBackLabel` and `footnoteLabel` define natural language
that explains footnotes, which is hidden for sighted users but shown to
assistive technology.
When your page is not in English, you must define translated values.

Back references use ARIA attributes, but the section label itself uses a
heading that is hidden with an `sr-only` class.
To show it to sighted users, define different attributes in
`footnoteLabelProperties`.

###### Clobbering

Footnotes introduces a problem, as it links footnote calls to footnote
definitions on the page through `id` attributes generated from user content,
which results in DOM clobbering.

DOM clobbering is this:

```html
<p id=x></p>
<script>alert(x) // `x` now refers to the DOM `p#x` element</script>
```

Elements by their ID are made available by browsers on the `window` object,
which is a security risk.
Using a prefix solves this problem.

More information on how to handle clobbering and the prefix is explained in
[Example: headings (DOM clobbering) in `rehype-sanitize`][clobber-example].

###### Unknown nodes

Unknown nodes are nodes with a type that isn’t in `handlers` or `passThrough`.
The default behavior for unknown nodes is:

* when the node has a `value` (and doesn’t have `data.hName`,
  `data.hProperties`, or `data.hChildren`, see later), create a hast `text`
  node
* otherwise, create a `<div>` element (which could be changed with
  `data.hName`), with its children mapped from mdast to hast as well

This behavior can be changed by passing an `unknownHandler`.

### `FootnoteBackContentTemplate`

Generate content for the backreference dynamically.

For the following markdown:

```markdown
Alpha[^micromark], bravo[^micromark], and charlie[^remark].

[^remark]: things about remark
[^micromark]: things about micromark
```

This function will be called with:

* `0` and `0` for the backreference from `things about micromark` to
  `alpha`, as it is the first used definition, and the first call to it
* `0` and `1` for the backreference from `things about micromark` to
  `bravo`, as it is the first used definition, and the second call to it
* `1` and `0` for the backreference from `things about remark` to
  `charlie`, as it is the second used definition

###### Parameters

* `referenceIndex` (`number`)
  — index of the definition in the order that they are first referenced,
  0-indexed
* `rereferenceIndex` (`number`)
  — index of calls to the same definition, 0-indexed

###### Returns

Content for the backreference when linking back from definitions to their
reference (`Array<ElementContent>`, `ElementContent`, or `string`).

### `FootnoteBackLabelTemplate`

Generate a back label dynamically.

For the following markdown:

```markdown
Alpha[^micromark], bravo[^micromark], and charlie[^remark].

[^remark]: things about remark
[^micromark]: things about micromark
```

This function will be called with:

* `0` and `0` for the backreference from `things about micromark` to
  `alpha`, as it is the first used definition, and the first call to it
* `0` and `1` for the backreference from `things about micromark` to
  `bravo`, as it is the first used definition, and the second call to it
* `1` and `0` for the backreference from `things about remark` to
  `charlie`, as it is the second used definition

###### Parameters

* `referenceIndex` (`number`)
  — index of the definition in the order that they are first referenced,
  0-indexed
* `rereferenceIndex` (`number`)
  — index of calls to the same definition, 0-indexed

###### Returns

Back label to use when linking back from definitions to their reference
(`string`).

### `Handler`

Handle a node (TypeScript type).

###### Parameters

* `state` ([`State`][api-state])
  — info passed around
* `node` ([`MdastNode`][mdast-node])
  — node to handle
* `parent` ([`MdastNode | undefined`][mdast-node])
  — parent of `node`

###### Returns

Result ([`Array<HastNode> | HastNode | undefined`][hast-node]).

### `Handlers`

Handle nodes (TypeScript type).

###### Type

```ts
type Handlers = Partial<Record<Nodes['type'], Handler>>
```

### `Options`

Configuration (TypeScript type).

###### Fields

* `allowDangerousHtml` (`boolean`, default: `false`)
  — whether to persist raw HTML in markdown in the hast tree
* `clobberPrefix` (`string`, default: `'user-content-'`)
  — prefix to use before the `id` property on footnotes to prevent them from
  *clobbering*
* `file` ([`VFile`][vfile], optional)
  — corresponding virtual file representing the input document
* `footnoteBackContent`
  ([`FootnoteBackContentTemplate`][api-footnote-back-content-template]
  or `string`, default:
  [`defaultFootnoteBackContent`][api-default-footnote-back-content])
  — content of the backreference back to references
* `footnoteBackLabel`
  ([`FootnoteBackLabelTemplate`][api-footnote-back-label-template]
  or `string`, default:
  [`defaultFootnoteBackLabel`][api-default-footnote-back-label])
  — label to describe the backreference back to references
* `footnoteLabel` (`string`, default: `'Footnotes'`)
  — label to use for the footnotes section (affects screen readers)
* `footnoteLabelProperties`
  ([`Properties`][properties], default: `{className: ['sr-only']}`)
  — properties to use on the footnote label
  (note that `id: 'footnote-label'` is always added as footnote calls use it
  with `aria-describedby` to provide an accessible label)
* `footnoteLabelTagName` (`string`, default: `h2`)
  — tag name to use for the footnote label
* `handlers` ([`Handlers`][api-handlers], optional)
  — extra handlers for nodes
* `passThrough` (`Array<Nodes['type']>`, optional)
  — list of custom mdast node types to pass through (keep) in hast (note that
  the node itself is passed, but eventual children are transformed)
* `unknownHandler` ([`Handler`][api-handler], optional)
  — handle all unknown nodes

### `Raw`

Raw string of HTML embedded into HTML AST (TypeScript type).

###### Type

```ts
import type {Data, Literal} from 'hast'

interface Raw extends Literal {
  type: 'raw'
  data?: RawData | undefined
}

interface RawData extends Data {}
```

### `State`

Info passed around about the current state (TypeScript type).

###### Fields

* `all` (`(node: MdastNode) => Array<HastNode>`)
  — transform the children of an mdast parent to hast
* `applyData` (`<Type extends HastNode>(from: MdastNode, to: Type) => Type | HastElement`)
  — honor the `data` of `from` and maybe generate an element instead of `to`
* `definitionById` (`Map<string, Definition>`)
  — definitions by their uppercased identifier
* `footnoteById` (`Map<string, FootnoteDefinition>`)
  — footnote definitions by their uppercased identifier
* `footnoteCounts` (`Map<string, number>`)
  — counts for how often the same footnote was called
* `footnoteOrder` (`Array<string>`)
  — identifiers of order when footnote calls first appear in tree order
* `handlers` ([`Handlers`][api-handlers])
  — applied node handlers
* `one` (`(node: MdastNode, parent: MdastNode | undefined) => HastNode | Array<HastNode> | undefined`)
  — transform an mdast node to hast
* `options` ([`Options`][api-options])
  — configuration
* `patch` (`(from: MdastNode, to: HastNode) => undefined`)
* `wrap` (`<Type extends HastNode>(nodes: Array<Type>, loose?: boolean) => Array<Type | HastText>`)
  — wrap `nodes` with line endings between each node, adds initial/final line
  endings when `loose`

## Examples

### Example: supporting HTML in markdown naïvely

If you completely trust authors (or plugins) and want to allow them to HTML *in*
markdown, and the last utility has an `allowDangerousHtml` option as well (such
as `hast-util-to-html`) you can pass `allowDangerousHtml` to this utility
(`mdast-util-to-hast`):

```js
import {fromMarkdown} from 'mdast-util-from-markdown'
import {toHast} from 'mdast-util-to-hast'
import {toHtml} from 'hast-util-to-html'

const markdown = 'It <i>works</i>! <img onerror="alert(1)">'
const mdast = fromMarkdown(markdown)
const hast = toHast(mdast, {allowDangerousHtml: true})
const html = toHtml(hast, {allowDangerousHtml: true})

console.log(html)
```

…now running `node example.js` yields:

```html
<p>It <i>works</i>! <img onerror="alert(1)"></p>
```

> ⚠️ **Danger**: observe that the XSS attack through the `onerror` attribute
> is still present.

### Example: supporting HTML in markdown properly

If you do not trust the authors of the input markdown, or if you want to make
sure that further utilities can see HTML embedded in markdown, use
[`hast-util-raw`][hast-util-raw].
The following example passes `allowDangerousHtml` to this utility
(`mdast-util-to-hast`), then turns the raw embedded HTML into proper HTML nodes
(`hast-util-raw`), and finally sanitizes the HTML by only allowing safe things
(`hast-util-sanitize`):

```js
import {raw} from 'hast-util-raw'
import {sanitize} from 'hast-util-sanitize'
import {toHtml} from 'hast-util-to-html'
import {fromMarkdown} from 'mdast-util-from-markdown'
import {toHast} from 'mdast-util-to-hast'

const markdown = 'It <i>works</i>! <img onerror="alert(1)">'
const mdast = fromMarkdown(markdown)
const hast = raw(toHast(mdast, {allowDangerousHtml: true}))
const safeHast = sanitize(hast)
const html = toHtml(safeHast)

console.log(html)
```

…now running `node example.js` yields:

```html
<p>It <i>works</i>! <img></p>
```

> 👉 **Note**: observe that the XSS attack through the `onerror` attribute
> is no longer present.

### Example: footnotes in languages other than English

If you know that the markdown is authored in a language other than English,
and you’re using `micromark-extension-gfm` and `mdast-util-gfm` to match how
GitHub renders markdown, and you know that footnotes are (or can?) be used, you
should translate the labels associated with them.

Let’s first set the stage:

```js
import {toHtml} from 'hast-util-to-html'
import {gfm} from 'micromark-extension-gfm'
import {fromMarkdown} from 'mdast-util-from-markdown'
import {gfmFromMarkdown} from 'mdast-util-gfm'
import {toHast} from 'mdast-util-to-hast'

const markdown = 'Bonjour[^1]\n\n[^1]: Monde!'
const mdast = fromMarkdown(markdown, {
  extensions: [gfm()],
  mdastExtensions: [gfmFromMarkdown()]
})
const hast = toHast(mdast)
const html = toHtml(hast)

console.log(html)
```

…now running `node example.js` yields:

```html
<p>Bonjour<sup><a href="#user-content-fn-1" id="user-content-fnref-1" data-footnote-ref aria-describedby="footnote-label">1</a></sup></p>
<section data-footnotes class="footnotes"><h2 class="sr-only" id="footnote-label">Footnotes</h2>
<ol>
<li id="user-content-fn-1">
<p>Monde! <a href="#user-content-fnref-1" data-footnote-backref="" aria-label="Back to reference 1" class="data-footnote-backref">↩</a></p>
</li>
</ol>
</section>
```

This is a mix of English and French that screen readers can’t handle nicely.
Let’s say our program does know that the markdown is in French.
In that case, it’s important to translate and define the labels relating to
footnotes so that screen reader users can properly pronounce the page:

```diff
@@ -9,7 +9,16 @@ const mdast = fromMarkdown(markdown, {
   extensions: [gfm()],
   mdastExtensions: [gfmFromMarkdown()]
 })
-const hast = toHast(mdast)
+const hast = toHast(mdast, {
+  footnoteLabel: 'Notes de bas de page',
+  footnoteBackLabel(referenceIndex, rereferenceIndex) {
+    return (
+      'Retour à la référence ' +
+      (referenceIndex + 1) +
+      (rereferenceIndex > 1 ? '-' + rereferenceIndex : '')
+    )
+  }
+})
 const html = toHtml(hast)

 console.log(html)
```

…now running `node example.js` with the above patch applied yields:

```diff
@@ -1,8 +1,8 @@
 <p>Bonjour<sup><a href="#user-content-fn-1" id="user-content-fnref-1" data-footnote-ref aria-describedby="footnote-label">1</a></sup></p>
-<section data-footnotes class="footnotes"><h2 class="sr-only" id="footnote-label">Footnotes</h2>
+<section data-footnotes class="footnotes"><h2 class="sr-only" id="footnote-label">Notes de bas de page</h2>
 <ol>
 <li id="user-content-fn-1">
-<p>Monde! <a href="#user-content-fnref-1" data-footnote-backref="" aria-label="Back to reference 1" class="data-footnote-backref">↩</a></p>
+<p>Monde! <a href="#user-content-fnref-1" data-footnote-backref="" aria-label="Retour à la référence 1" class="data-footnote-backref">↩</a></p>
 </li>
 </ol>
 </section>
```

### Example: supporting custom nodes

This project supports CommonMark and the GFM constructs (footnotes,
strikethrough, tables) and the frontmatter constructs YAML and TOML.
Support can be extended to other constructs in two ways: a) with handlers, b)
through fields on nodes.

For example, when we represent a mark element in markdown and want to turn it
into a `<mark>` element in HTML, we can use a handler:

```js
import {toHtml} from 'hast-util-to-html'
import {toHast} from 'mdast-util-to-hast'

const mdast = {
  type: 'paragraph',
  children: [{type: 'mark', children: [{type: 'text', value: 'x'}]}]
}

const hast = toHast(mdast, {
  handlers: {
    mark(state, node) {
      return {
        type: 'element',
        tagName: 'mark',
        properties: {},
        children: state.all(node)
      }
    }
  }
})

console.log(toHtml(hast))
```

We can do the same through certain fields on nodes:

```js
import {toHtml} from 'hast-util-to-html'
import {toHast} from 'mdast-util-to-hast'

const mdast = {
  type: 'paragraph',
  children: [
    {
      type: 'mark',
      children: [{type: 'text', value: 'x'}],
      data: {hName: 'mark'}
    }
  ]
}

console.log(toHtml(toHast(mdast)))
```

## Algorithm

This project by default handles CommonMark, GFM (footnotes, strikethrough,
tables) and common frontmatter (YAML, TOML).

Existing handlers can be overwritten and handlers for more nodes can be added.
It’s also possible to define how mdast is turned into hast through fields on
nodes.

### Default handling

The following table gives insight into what input turns into what output:

<table>
<thead>
<tr>
<th scope="col">mdast node</th>
<th scope="col">markdown example</th>
<th scope="col">hast node</th>
<th scope="col">html example</th>
</tr>
</thead>
<tbody>
<tr>
<th scope="row">

[`blockquote`](https://github.com/syntax-tree/mdast#blockquote)

</th>
<td>

```markdown
> A greater than…
```

</td>
<td>

[`element`](https://github.com/syntax-tree/hast#element) (`blockquote`)

</td>
<td>

```html
<blockquote>
<p>A greater than…</p>
</blockquote>
```

</td>
</tr>
<tr>
<th scope="row">

[`break`](https://github.com/syntax-tree/mdast#break)

</th>
<td>

```markdown
A backslash\
before a line break…
```

</td>
<td>

[`element`](https://github.com/syntax-tree/hast#element) (`br`)

</td>
<td>

```html
<p>A backslash<br>
before a line break…</p>
```

</td>
</tr>
<tr>
<th scope="row">

[`code`](https://github.com/syntax-tree/mdast#code)

</th>
<td>

````markdown
```js
backtick.fences('for blocks')
```
````

</td>
<td>

[`element`](https://github.com/syntax-tree/hast#element) (`pre` and `code`)

</td>
<td>

```html
<pre><code className="language-js">backtick.fences('for blocks')
</code></pre>
```

</td>
</tr>
<tr>
<th scope="row">

[`delete`](https://github.com/syntax-tree/mdast#delete) (GFM)

</th>
<td>

```markdown
Two ~~tildes~~ for delete.
```

</td>
<td>

[`element`](https://github.com/syntax-tree/hast#element) (`del`)

</td>
<td>

```html
<p>Two <del>tildes</del> for delete.</p>
```

</td>
</tr>
<tr>
<th scope="row">

[`emphasis`](https://github.com/syntax-tree/mdast#emphasis)

</th>
<td>

```markdown
Some *asterisks* for emphasis.
```

</td>
<td>

[`element`](https://github.com/syntax-tree/hast#element) (`em`)

</td>
<td>

```html
<p>Some <em>asterisks</em> for emphasis.</p>
```

</td>
</tr>
<tr>
<th scope="row">

[`footnoteReference`](https://github.com/syntax-tree/mdast#footnotereference),
[`footnoteDefinition`](https://github.com/syntax-tree/mdast#footnotedefinition)
(GFM)

</th>
<td>

```markdown
With a [^caret].

[^caret]: Stuff
```

</td>
<td>

[`element`](https://github.com/syntax-tree/hast#element) (`section`, `sup`, `a`)

</td>
<td>

```html
<p>With a <sup><a href="#fn-caret" …>1</a></sup>.</p>…
```

</td>
</tr>
<tr>
<th scope="row">

[`heading`](https://github.com/syntax-tree/mdast#heading)

</th>
<td>

```markdown
# One number sign…
###### Six number signs…
```

</td>
<td>

[`element`](https://github.com/syntax-tree/hast#element) (`h1`…`h6`)

</td>
<td>

```html
<h1>One number sign…</h1>
<h6>Six number signs…</h6>
```

</td>
</tr>
<tr>
<th scope="row">

[`html`](https://github.com/syntax-tree/mdast#html)

</th>
<td>

```html
<kbd>CMD+S</kbd>
```

</td>
<td>

Nothing (default), `raw` (when `allowDangerousHtml: true`)

</td>
<td>

n/a

</td>
</tr>
<tr>
<th scope="row">

[`image`](https://github.com/syntax-tree/mdast#image)

</th>
<td>

```markdown
![Alt text](/logo.png "title")
```

</td>
<td>

[`element`](https://github.com/syntax-tree/hast#element) (`img`)

</td>
<td>

```html
<p><img src="/logo.png" alt="Alt text" title="title"></p>
```

</td>
</tr>
<tr>
<th scope="row">

[`imageReference`](https://github.com/syntax-tree/mdast#imagereference),
[`definition`](https://github.com/syntax-tree/mdast#definition)

</th>
<td>

```markdown
![Alt text][logo]

[logo]: /logo.png "title"
```

</td>
<td>

[`element`](https://github.com/syntax-tree/hast#element) (`img`)

</td>
<td>

```html
<p><img src="/logo.png" alt="Alt text" title="title"></p>
```

</td>
</tr>
<tr>
<th scope="row">

[`inlineCode`](https://github.com/syntax-tree/mdast#inlinecode)

</th>
<td>

```markdown
Some `backticks` for inline code.
```

</td>
<td>

[`element`](https://github.com/syntax-tree/hast#element) (`code`)

</td>
<td>

```html
<p>Some <code>backticks</code> for inline code.</p>
```

</td>
</tr>
<tr>
<th scope="row">

[`link`](https://github.com/syntax-tree/mdast#link)

</th>
<td>

```markdown
[Example](https://example.com "title")
```

</td>
<td>

[`element`](https://github.com/syntax-tree/hast#element) (`a`)

</td>
<td>

```html
<p><a href="https://example.com" title="title">Example</a></p>
```

</td>
</tr>
<tr>
<th scope="row">

[`linkReference`](https://github.com/syntax-tree/mdast#linkreference),
[`definition`](https://github.com/syntax-tree/mdast#definition)

</th>
<td>

```markdown
[Example][]

[example]: https://example.com "title"
```

</td>
<td>

[`element`](https://github.com/syntax-tree/hast#element) (`a`)

</td>
<td>

```html
<p><a href="https://example.com" title="title">Example</a></p>
```

</td>
</tr>
<tr>
<th scope="row">

[`list`](https://github.com/syntax-tree/mdast#list),
[`listItem`](https://github.com/syntax-tree/mdast#listitem)

</th>
<td>

```markdown
* asterisks for unordered items

1. decimals and a dot for ordered items
```

</td>
<td>

[`element`](https://github.com/syntax-tree/hast#element) (`li` and `ol` or `ul`)

</td>
<td>

```html
<ul>
<li>asterisks for unordered items</li>
</ul>
<ol>
<li>decimals and a dot for ordered items</li>
</ol>
```

</td>
</tr>
<tr>
<th scope="row">

[`paragraph`](https://github.com/syntax-tree/mdast#paragraph)

</th>
<td>

```markdown
Just some text…
```

</td>
<td>

[`element`](https://github.com/syntax-tree/hast#element) (`p`)

</td>
<td>

```html
<p>Just some text…</p>
```

</td>
</tr>
<tr>
<th scope="row">

[`root`](https://github.com/syntax-tree/mdast#root)

</th>
<td>

```markdown
Anything!
```

</td>
<td>

[`root`](https://github.com/syntax-tree/hast#root)

</td>
<td>

```html
<p>Anything!</p>
```

</td>
</tr>
<tr>
<th scope="row">

[`strong`](https://github.com/syntax-tree/mdast#strong)

</th>
<td>

```markdown
Two **asterisks** for strong.
```

</td>
<td>

[`element`](https://github.com/syntax-tree/hast#element) (`strong`)

</td>
<td>

```html
<p>Two <strong>asterisks</strong> for strong.</p>
```

</td>
</tr>
<tr>
<th scope="row">

[`text`](https://github.com/syntax-tree/mdast#text)

</th>
<td>

```markdown
Anything!
```

</td>
<td>

[`text`](https://github.com/syntax-tree/hast#text)

</td>
<td>

```html
<p>Anything!</p>
```

</td>
</tr>
<tr>
<th scope="row">

[`table`](https://github.com/syntax-tree/mdast#table),
[`tableRow`](https://github.com/syntax-tree/mdast#tablerow),
[`tableCell`](https://github.com/syntax-tree/mdast#tablecell)

</th>
<td>

```markdown
| Pipes |
| ----- |
```

</td>
<td>

[`element`](https://github.com/syntax-tree/hast#element) (`table`, `thead`,
`tbody`, `tr`, `td`, `th`)

</td>
<td>

```html
<table>
<thead>
<tr>
<th>Pipes</th>
</tr>
</thead>
</table>
```

</td>
</tr>
<tr>
<th scope="row">

[`thematicBreak`](https://github.com/syntax-tree/mdast#thematicbreak)

</th>
<td>

```markdown
Three asterisks for a thematic break:

***
```

</td>
<td>

[`element`](https://github.com/syntax-tree/hast#element) (`hr`)

</td>
<td>

```html
<p>Three asterisks for a thematic break:</p>
<hr>
```

</td>
</tr>
<tr>
<th scope="row">

`toml` (frontmatter)

</th>
<td>

```markdown
+++
fenced = true
+++
```

</td>
<td>

Nothing

</td>
<td>

n/a

</td>
</tr>
<tr>
<th scope="row">

[`yaml`](https://github.com/syntax-tree/mdast#yaml) (frontmatter)

</th>
<td>

```markdown
---
fenced: yes
---
```

</td>
<td>

Nothing

</td>
<td>

n/a

</td>
</tr>
</tbody>
</table>

> 👉 **Note**: GFM prescribes that the obsolete `align` attribute on `td` and
> `th` elements is used.
> To use `style` attributes instead of obsolete features, combine this utility
> with [`@mapbox/hast-util-table-cell-style`][hast-util-table-cell-style].

> 🧑‍🏫 **Info**: this project is concerned with turning one syntax tree into
> another.
> It does not deal with markdown syntax or HTML syntax.
> The preceding examples are illustrative rather than authoritative or
> exhaustive.

### Fields on nodes

A frequent problem arises when having to turn one syntax tree into another.
As the original tree (in this case, mdast for markdown) is in some cases
limited compared to the destination (in this case, hast for HTML) tree,
is it possible to provide more info in the original to define what the
result will be in the destination?
This is possible by defining data on mdast nodes, which this utility will read
as instructions on what hast nodes to create.

An example is math, which is a nonstandard markdown extension, that this utility
doesn’t understand.
To solve this, `mdast-util-math` defines instructions on mdast nodes that this
plugin does understand because they define a certain hast structure.

The following fields can be used:

* `node.data.hName` — define the element’s tag name
* `node.data.hProperties` — define extra properties to use
* `node.data.hChildren` — define hast children to use

###### `hName`

`node.data.hName` sets the tag name of an element.
The following [mdast][]:

```js
{
  type: 'strong',
  data: {hName: 'b'},
  children: [{type: 'text', value: 'Alpha'}]
}
```

…yields ([hast][]):

```js
{
  type: 'element',
  tagName: 'b',
  properties: {},
  children: [{type: 'text', value: 'Alpha'}]
}
```

###### `hProperties`

`node.data.hProperties` sets the properties of an element.
The following [mdast][]:

```js
{
  type: 'image',
  src: 'circle.svg',
  alt: 'Big red circle on a black background',
  data: {hProperties: {className: ['responsive']}}
}
```

…yields ([hast][]):

```js
{
  type: 'element',
  tagName: 'img',
  properties: {
    src: 'circle.svg',
    alt: 'Big red circle on a black background',
    className: ['responsive']
  },
  children: []
}
```

###### `hChildren`

`node.data.hChildren` sets the children of an element.
The following [mdast][]:

```js
{
  type: 'code',
  lang: 'js',
  data: {
    hChildren: [
      {
        type: 'element',
        tagName: 'span',
        properties: {className: ['hljs-meta']},
        children: [{type: 'text', value: '"use strict"'}]
      },
      {type: 'text', value: ';'}
    ]
  },
  value: '"use strict";'
}
```

…yields ([hast][]):

```js
{
  type: 'element',
  tagName: 'pre',
  properties: {},
  children: [{
    type: 'element',
    tagName: 'code',
    properties: {className: ['language-js']},
    children: [
      {
        type: 'element',
        tagName: 'span',
        properties: {className: ['hljs-meta']},
        children: [{type: 'text', value: '"use strict"'}]
      },
      {type: 'text', value: ';'}
    ]
  }]
}
```

> 👉 **Note**: the `pre` and `language-js` class are normal `mdast-util-to-hast`
> functionality.

## CSS

Assuming you know how to use (semantic) HTML and CSS, then it should generally
be straightforward to style the HTML produced by this plugin.
With CSS, you can get creative and style the results as you please.

Some semistandard features, notably GFMs tasklists and footnotes, generate HTML
that be unintuitive, as it matches exactly what GitHub produces for their
website.
There is a project, [`sindresorhus/github-markdown-css`][github-markdown-css],
that exposes the stylesheet that GitHub uses for rendered markdown, which might
either be inspirational for more complex features, or can be used as-is to
exactly match how GitHub styles rendered markdown.

The following CSS is needed to make footnotes look a bit like GitHub:

```css
/* Style the footnotes section. */
.footnotes {
  font-size: smaller;
  color: #8b949e;
  border-top: 1px solid #30363d;
}

/* Hide the section label for visual users. */
.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  word-wrap: normal;
  border: 0;
}

/* Place `[` and `]` around footnote calls. */
[data-footnote-ref]::before {
  content: '[';
}

[data-footnote-ref]::after {
  content: ']';
}
```

## Syntax tree

The following interfaces are added to **[hast][]** by this utility.

### Nodes

#### `Raw`

```idl
interface Raw <: Literal {
  type: 'raw'
}
```

**Raw** (**[Literal][dfn-literal]**) represents a string if raw HTML inside
hast.
Raw nodes are typically ignored but are handled by
[`hast-util-to-html`][hast-util-to-html] and [`hast-util-raw`][hast-util-raw].

## Types

This package is fully typed with [TypeScript][].
It exports the
[`FootnoteBackContentTemplate`][api-footnote-back-content-template],
[`FootnoteBackLabelTemplate`][api-footnote-back-label-template],
[`Handler`][api-handler],
[`Handlers`][api-handlers],
[`Options`][api-options],
[`Raw`][api-raw], and
[`State`][api-state] types.

It also registers the `Raw` node type with `@types/hast`.
If you’re working with the syntax tree (and you pass
`allowDangerousHtml: true`), make sure to import this utility somewhere in your
types, as that registers the new node type in the tree.

```js
/**
 * @typedef {import('mdast-util-to-hast')}
 */

import {visit} from 'unist-util-visit'

/** @type {import('hast').Root} */
const tree = { /* … */ }

visit(tree, function (node) {
  // `node` can now be `raw`.
})
```

Finally, it also registers the `hChildren`, `hName`, and `hProperties` fields
on `Data` of `@types/mdast`.
If you’re working with the syntax tree, make sure to import this utility
somewhere in your types, as that registers the data fields in the tree.

```js
/**
 * @typedef {import('mdast-util-to-hast')}
 */

import {visit} from 'unist-util-visit'

/** @type {import('hast').Root} */
const tree = { /* … */ }

console.log(tree.data?.hName) // Types as `string | undefined`.
```

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, `mdast-util-to-hast@^13`,
compatible with Node.js 16.

## Security

Use of `mdast-util-to-hast` can open you up to a
[cross-site scripting (XSS)][xss] attack.
Embedded hast properties (`hName`, `hProperties`, `hChildren`), custom handlers,
and the `allowDangerousHtml` option all provide openings.

The following example shows how a script is injected where a benign code block
is expected with embedded hast properties:

```js
const code = {type: 'code', value: 'alert(1)'}

code.data = {hName: 'script'}
```

Yields:

```html
<script>alert(1)</script>
```

The following example shows how an image is changed to fail loading and
therefore run code in a browser.

```js
const image = {type: 'image', url: 'existing.png'}

image.data = {hProperties: {src: 'missing', onError: 'alert(2)'}}
```

Yields:

```html
<img src="missing" onerror="alert(2)">
```

The following example shows the default handling of embedded HTML:

```markdown
# Hello

<script>alert(3)</script>
```

Yields:

```html
<h1>Hello</h1>
```

Passing `allowDangerousHtml: true` to `mdast-util-to-hast` is typically still
not enough to run unsafe code:

```html
<h1>Hello</h1>
&#x3C;script>alert(3)&#x3C;/script>
```

If `allowDangerousHtml: true` is also given to `hast-util-to-html` (or
`rehype-stringify`), the unsafe code runs:

```html
<h1>Hello</h1>
<script>alert(3)</script>
```

Use [`hast-util-sanitize`][hast-util-sanitize] to make the hast tree safe.

## Related

* [`hast-util-to-mdast`](https://github.com/syntax-tree/hast-util-to-mdast)
  — transform hast to mdast
* [`hast-util-to-xast`](https://github.com/syntax-tree/hast-util-to-xast)
  — transform hast to xast
* [`hast-util-sanitize`](https://github.com/syntax-tree/hast-util-sanitize)
  — sanitize hast nodes

## Contribute

See [`contributing.md` in `syntax-tree/.github`][contributing] for ways to get
started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/syntax-tree/mdast-util-to-hast/workflows/main/badge.svg

[build]: https://github.com/syntax-tree/mdast-util-to-hast/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/mdast-util-to-hast.svg

[coverage]: https://codecov.io/github/syntax-tree/mdast-util-to-hast

[downloads-badge]: https://img.shields.io/npm/dm/mdast-util-to-hast.svg

[downloads]: https://www.npmjs.com/package/mdast-util-to-hast

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=mdast-util-to-hast

[size]: https://bundlejs.com/?q=mdast-util-to-hast

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/syntax-tree/unist/discussions

[npm]: https://docs.npmjs.com/cli/install

[license]: license

[author]: https://wooorm.com

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[typescript]: https://www.typescriptlang.org

[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md

[support]: https://github.com/syntax-tree/.github/blob/main/support.md

[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md

[mdast]: https://github.com/syntax-tree/mdast

[mdast-node]: https://github.com/syntax-tree/mdast#nodes

[mdast-html]: https://github.com/syntax-tree/mdast#html

[mdast-util-gfm]: https://github.com/syntax-tree/mdast-util-gfm

[hast]: https://github.com/syntax-tree/hast

[hast-node]: https://github.com/syntax-tree/hast#nodes

[properties]: https://github.com/syntax-tree/hast#properties

[hast-util-table-cell-style]: https://github.com/mapbox/hast-util-table-cell-style

[hast-util-to-mdast]: https://github.com/syntax-tree/hast-util-to-mdast

[hast-util-to-html]: https://github.com/syntax-tree/hast-util-to-html

[hast-util-raw]: https://github.com/syntax-tree/hast-util-raw

[hast-util-sanitize]: https://github.com/syntax-tree/hast-util-sanitize

[remark-rehype]: https://github.com/remarkjs/remark-rehype

[vfile]: https://github.com/vfile/vfile

[clobber-example]: https://github.com/rehypejs/rehype-sanitize#example-headings-dom-clobbering

[github-markdown-css]: https://github.com/sindresorhus/github-markdown-css

[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting

[dfn-literal]: https://github.com/syntax-tree/hast#literal

[api-default-footnote-back-content]: #defaultfootnotebackcontentreferenceindex-rereferenceindex

[api-default-footnote-back-label]: #defaultfootnotebacklabelreferenceindex-rereferenceindex

[api-default-handlers]: #defaulthandlers

[api-footnote-back-content-template]: #footnotebackcontenttemplate

[api-footnote-back-label-template]: #footnotebacklabeltemplate

[api-handler]: #handler

[api-handlers]: #handlers

[api-options]: #options

[api-raw]: #raw

[api-state]: #state

[api-to-hast]: #tohasttree-options


---

# mdast-util-to-markdown

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

**[mdast][]** utility that turns a syntax tree into markdown.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`toMarkdown(tree[, options])`](#tomarkdowntree-options)
  * [`defaultHandlers`](#defaulthandlers)
  * [`ConstructName`](#constructname)
  * [`ConstructNameMap`](#constructnamemap)
  * [`Handle`](#handle)
  * [`Handlers`](#handlers)
  * [`Info`](#info)
  * [`Join`](#join)
  * [`Map`](#map)
  * [`Options`](#options)
  * [`SafeConfig`](#safeconfig)
  * [`State`](#state)
  * [`Tracker`](#tracker)
  * [`Unsafe`](#unsafe)
* [List of extensions](#list-of-extensions)
* [Syntax](#syntax)
* [Syntax tree](#syntax-tree)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Related](#related)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package is a utility that takes an [mdast][] syntax tree as input and turns
it into serialized markdown.

This utility is a low level project.
It’s used in [`remark-stringify`][remark-stringify], which focusses on making it
easier to transform content by abstracting these internals away.

## When should I use this?

If you want to handle syntax trees manually, use this.
For an easier time processing content, use the **[remark][]** ecosystem instead.

You can combine this utility with other utilities to add syntax extensions.
Notable examples that deeply integrate with it are
[`mdast-util-gfm`][mdast-util-gfm],
[`mdast-util-mdx`][mdast-util-mdx],
[`mdast-util-frontmatter`][mdast-util-frontmatter],
[`mdast-util-math`][mdast-util-math], and
[`mdast-util-directive`][mdast-util-directive].

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install mdast-util-to-markdown
```

In Deno with [`esm.sh`][esmsh]:

```js
import {toMarkdown} from 'https://esm.sh/mdast-util-to-markdown@2'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {toMarkdown} from 'https://esm.sh/mdast-util-to-markdown@2?bundle'
</script>
```

## Use

Say our module `example.js` looks as follows:

```js
/**
 * @import {Root} from 'mdast'
 */

import {toMarkdown} from 'mdast-util-to-markdown'

/** @type {Root} */
const tree = {
  type: 'root',
  children: [
    {
      type: 'blockquote',
      children: [
        {type: 'thematicBreak'},
        {
          type: 'paragraph',
          children: [
            {type: 'text', value: '- a\nb !'},
            {
              type: 'link',
              url: 'example.com',
              children: [{type: 'text', value: 'd'}]
            }
          ]
        }
      ]
    }
  ]
}

console.log(toMarkdown(tree))
```

…now running `node example.js` yields:

```markdown
> ***
>
> \- a
> b \![d](example.com)
```

> 👉 **Note**: observe the properly escaped characters which would otherwise
> turn into a list and image respectively.

## API

This package exports the identifiers [`defaultHandlers`][api-default-handlers]
and [`toMarkdown`][api-to-markdown].
There is no default export.

### `toMarkdown(tree[, options])`

Turn an **[mdast][]** syntax tree into markdown.

###### Parameters

* `tree` ([`Node`][node])
  — tree to serialize
* `options` ([`Options`][api-options], optional)
  — configuration

###### Returns

Serialized markdown representing `tree` (`string`).

### `defaultHandlers`

Default (CommonMark) handlers ([`Handlers`][api-handlers]).

### `ConstructName`

Construct names for things generated by `mdast-util-to-markdown` (TypeScript
type).

This is an enum of strings, each being a semantic label, useful to know when
serializing whether we’re for example in a double (`"`) or single (`'`) quoted
title.

###### Type

```ts
type ConstructName = ConstructNameMap[keyof ConstructNameMap]
```

### `ConstructNameMap`

Interface of registered constructs (TypeScript type).

###### Type

```ts
interface ConstructNameMap { /* see code */ }
```

When working on extensions that use new constructs, extend the corresponding
interface to register its name:

```ts
declare module 'mdast-util-to-markdown' {
  interface ConstructNameMap {
    // Register a new construct name (value is used, key should match it).
    gfmStrikethrough: 'gfmStrikethrough'
  }
}
```

### `Handle`

Handle a particular node (TypeScript type).

###### Parameters

* `node` (`any`)
  — expected mdast node
* `parent` ([`Node`][node], optional)
  — parent of `node`
* `state` ([`State`][api-state])
  — info passed around about the current state
* `info` ([`Info`][api-info])
  — info on the surrounding of the node that is serialized

###### Returns

Serialized markdown representing `node` (`string`).

### `Handlers`

Handle particular nodes (TypeScript type).

Each key is a node type (`Node['type']`), each value its corresponding handler
([`Handle`][api-handle]).

###### Type

```ts
type Handlers = Record<Node['type'], Handle>
```

### `Info`

Info on the surrounding of the node that is serialized (TypeScript type).

###### Fields

* `now` ([`Point`][point])
  — current point
* `lineShift` (`number`)
  — number of columns each line will be shifted by wrapping nodes
* `before` (`string`)
  — characters before this (guaranteed to be one, can be more)
* `after` (`string`)
  — characters after this (guaranteed to be one, can be more)

### `Join`

How to join two blocks (TypeScript type).

“Blocks” are typically joined by one blank line.
Sometimes it’s nicer to have them flush next to each other, yet other times
they cannot occur together at all.

Join functions receive two adjacent siblings and their parent and what they
return defines how many blank lines to use between them.

###### Parameters

* `left` ([`Node`][node])
  — first of two adjacent siblings
* `right` ([`Node`][node])
  — second of two adjacent siblings
* `parent` ([`Node`][node])
  — parent of the two siblings
* `state` ([`State`][api-state])
  — info passed around about the current state

###### Returns

How many blank lines to use between the siblings (`boolean`, `number`,
optional).

Where `true` is as passing `1` and `false` means the nodes cannot be
joined by a blank line, such as two adjacent block quotes or indented code
after a list, in which case a comment will be injected to break them up:

```markdown
> Quote 1

<!---->

> Quote 2
```

> 👉 **Note**: abusing this feature will break markdown.
> One such example is when returning `0` for two paragraphs, which will result
> in the text running together, and in the future to be seen as one paragraph.

### `Map`

Map function to pad a single line (TypeScript type).

###### Parameters

* `value` (`string`)
  — a single line of serialized markdown
* `line` (`number`)
  — line number relative to the fragment
* `blank` (`boolean`)
  — whether the line is considered blank in markdown

###### Returns

Padded line (`string`).

### `Options`

Configuration (TypeScript type).

##### Fields

The following fields influence how markdown is serialized.

###### `options.bullet`

Marker to use for bullets of items in unordered lists (`'*'`, `'+'`, or `'-'`,
default: `'*'`).

There are three cases where the primary bullet cannot be used:

* when three or more list items are on their own, the last one is empty, and
  `bullet` is also a valid `rule`: `* - +`; this would turn into a thematic
  break if serialized with three primary bullets; `bulletOther` is used for
  the last item
* when a thematic break is the first child of a list item and `bullet` is the
  same character as `rule`: `- ***`; this would turn into a single thematic
  break if serialized with primary bullets; `bulletOther` is used for the
  item
* when two unordered lists appear next to each other: `* a\n- b`;
  `bulletOther` is used for such lists

###### `options.bulletOther`

Marker to use in certain cases where the primary bullet doesn’t work (`'*'`,
`'+'`, or `'-'`, default: `'-'` when `bullet` is `'*'`, `'*'` otherwise).

Cannot be equal to `bullet`.

###### `options.bulletOrdered`

Marker to use for bullets of items in ordered lists (`'.'` or `')'`, default:
`'.'`).

There is one case where the primary bullet for ordered items cannot be used:

* when two ordered lists appear next to each other: `1. a\n2) b`; to solve
  that, `'.'` will be used when `bulletOrdered` is `')'`, and `'.'` otherwise

###### `options.closeAtx`

Whether to add the same number of number signs (`#`) at the end of an ATX
heading as the opening sequence (`boolean`, default: `false`).

###### `options.emphasis`

Marker to use for emphasis (`'*'` or `'_'`, default: `'*'`).

###### `options.fence`

Marker to use for fenced code (``'`'`` or `'~'`, default: ``'`'``).

###### `options.fences`

Whether to use fenced code always (`boolean`, default: `true`).
The default is to use fenced code if there is a language defined, if the code is
empty, or if it starts or ends in blank lines.

###### `options.incrementListMarker`

Whether to increment the counter of ordered lists items (`boolean`, default:
`true`).

###### `options.listItemIndent`

How to indent the content of list items (`'mixed'`, `'one'`, or `'tab'`,
default: `'one'`).
Either with the size of the bullet plus one space (when `'one'`), a tab stop
(`'tab'`), or depending on the item and its parent list (`'mixed'`, uses `'one'`
if the item and list are tight and `'tab'` otherwise).

###### `options.quote`

Marker to use for titles (`'"'` or `"'"`, default: `'"'`).

###### `options.resourceLink`

Whether to always use resource links (`boolean`, default: `false`).
The default is to use autolinks (`<https://example.com>`) when possible
and resource links (`[text](url)`) otherwise.

###### `options.rule`

Marker to use for thematic breaks (`'*'`, `'-'`, or `'_'`, default: `'*'`).

###### `options.ruleRepetition`

Number of markers to use for thematic breaks (`number`, default: `3`, min: `3`).

###### `options.ruleSpaces`

Whether to add spaces between markers in thematic breaks (`boolean`, default:
`false`).

###### `options.setext`

Whether to use setext headings when possible (`boolean`, default: `false`).
The default is to always use ATX headings (`# heading`) instead of setext
headings (`heading\n=======`).
Setext headings cannot be used for empty headings or headings with a rank of
three or more.

###### `options.strong`

Marker to use for strong (`'*'` or `'_'`, default: `'*'`).

###### `options.tightDefinitions`

Whether to join definitions without a blank line (`boolean`, default: `false`).

The default is to add blank lines between any flow (“block”) construct.
Turning this option on is a shortcut for a [`Join`][api-join] function like so:

```js
function joinTightDefinitions(left, right) {
  if (left.type === 'definition' && right.type === 'definition') {
    return 0
  }
}
```

###### `options.handlers`

Handle particular nodes ([`Handlers`][api-handlers], optional).

###### `options.join`

How to join blocks ([`Array<Join>`][api-join], optional).

###### `options.unsafe`

Schemas that define when characters cannot occur
([`Array<Unsafe>`][api-unsafe], optional).

###### `options.extensions`

List of extensions (`Array<Options>`, default: `[]`).
Each extension is an object with the same interface as `Options` itself.

### `SafeConfig`

Configuration passed to `state.safe` (TypeScript type).

###### Fields

* `before` (`string`)
  — characters before this (guaranteed to be one, can be more)
* `after` (`string`)
  — characters after this (guaranteed to be one, can be more)
* `encode` (`Array<string>`, optional)
  — extra characters that *must* be encoded (as character references) instead
  of escaped (character escapes).
  Only ASCII punctuation will use character escapes, so you never need to
  pass non-ASCII-punctuation here

### `State`

Info passed around about the current state (TypeScript type).

###### Fields

* `stack` ([`Array<ConstructName>`][api-construct-name])
  — stack of constructs we’re in
* `indexStack` (`Array<number>`)
  — positions of child nodes in their parents
* `associationId` (`(node: Association) => string`)
  — get an identifier from an association to match it to others (see
  [`Association`][association])
* `enter` (`(construct: ConstructName) => () => undefined`)
  — enter a construct (returns a corresponding exit function)
  (see [`ConstructName`][api-construct-name])
* `indentLines` (`(value: string, map: Map) => string`)
  — pad serialized markdown (see [`Map`][api-map])
* `compilePattern` (`(pattern: Unsafe) => RegExp`)
  — compile an unsafe pattern to a regex (see [`Unsafe`][api-unsafe])
* `containerFlow` (`(parent: Node, info: Info) => string`)
  — serialize flow children (see [`Info`][api-info])
* `containerPhrasing` (`(parent: Node, info: Info) => string`)
  — serialize phrasing children (see [`Info`][api-info])
* `createTracker` (`(info: Info) => Tracker`)
  — track positional info in the output (see [`Info`][api-info],
  [`Tracker`][api-tracker])
* `safe` (`(value: string, config: SafeConfig) => string`)
  — make a string safe for embedding (see [`SafeConfig`][api-safe-config])
* `options` ([`Options`][api-options])
  — applied user configuration
* `unsafe` ([`Array<Unsafe>`][api-unsafe])
  — applied unsafe patterns
* `join` ([`Array<Join>`][api-join])
  — applied join handlers
* `handle` ([`Handle`][api-handle])
  — call the configured handler for the given node
* `handlers` ([`Handlers`][api-handlers])
  — applied handlers
* `bulletCurrent` (`string` or `undefined`)
  — list marker currently in use
* `bulletLastUsed` (`string` or `undefined`)
  — list marker previously in use

### `Tracker`

Track positional info in the output (TypeScript type).

This info isn’t used yet but such functionality will allow line wrapping,
source maps, etc.

###### Fields

* `current` (`() => Info`)
  — get current tracked info
* `shift` (`(value: number) => undefined`)
  — define a relative increased line shift (the typical indent for lines)
* `move` (`(value: string) => string`)
  — move past some generated markdown

### `Unsafe`

Schema that defines when a character cannot occur (TypeScript type).

###### Fields

* `character` (`string`)
  — single unsafe character
* `inConstruct` ([`Array<ConstructName>`][api-construct-name],
  `ConstructName`, optional)
  — constructs where this is bad
* `notInConstruct` ([`Array<ConstructName>`][api-construct-name],
  `ConstructName`, optional)
  — constructs where this is fine again
* `before` (`string`, optional)
  — `character` is bad when this is before it (cannot be used together with
  `atBreak`)
* `after` (`string`, optional)
  — `character` is bad when this is after it
* `atBreak` (`boolean`, optional)
  — `character` is bad at a break (cannot be used together with `before`)

## List of extensions

* [`syntax-tree/mdast-util-directive`](https://github.com/syntax-tree/mdast-util-directive)
  — directives
* [`syntax-tree/mdast-util-frontmatter`](https://github.com/syntax-tree/mdast-util-frontmatter)
  — frontmatter (YAML, TOML, more)
* [`syntax-tree/mdast-util-gfm`](https://github.com/syntax-tree/mdast-util-gfm)
  — GFM
* [`syntax-tree/mdast-util-gfm-autolink-literal`](https://github.com/syntax-tree/mdast-util-gfm-autolink-literal)
  — GFM autolink literals
* [`syntax-tree/mdast-util-gfm-footnote`](https://github.com/syntax-tree/mdast-util-gfm-footnote)
  — GFM footnotes
* [`syntax-tree/mdast-util-gfm-strikethrough`](https://github.com/syntax-tree/mdast-util-gfm-strikethrough)
  — GFM strikethrough
* [`syntax-tree/mdast-util-gfm-table`](https://github.com/syntax-tree/mdast-util-gfm-table)
  — GFM tables
* [`syntax-tree/mdast-util-gfm-task-list-item`](https://github.com/syntax-tree/mdast-util-gfm-task-list-item)
  — GFM task list items
* [`syntax-tree/mdast-util-math`](https://github.com/syntax-tree/mdast-util-math)
  — math
* [`syntax-tree/mdast-util-mdx`](https://github.com/syntax-tree/mdast-util-mdx)
  — MDX
* [`syntax-tree/mdast-util-mdx-expression`](https://github.com/syntax-tree/mdast-util-mdx-expression)
  — MDX expressions
* [`syntax-tree/mdast-util-mdx-jsx`](https://github.com/syntax-tree/mdast-util-mdx-jsx)
  — MDX JSX
* [`syntax-tree/mdast-util-mdxjs-esm`](https://github.com/syntax-tree/mdast-util-mdxjs-esm)
  — MDX ESM

## Syntax

Markdown is serialized according to CommonMark but care is taken to format in
such a way that the resulting markdown should work with most markdown parsers.
Extensions can add support for custom syntax.

## Syntax tree

The syntax tree is [mdast][].

## Types

This package is fully typed with [TypeScript][].
It exports the additional types
[`ConstructName`][api-construct-name],
[`ConstructNameMap`][api-construct-name-map],
[`Handle`][api-handle],
[`Handlers`][api-handlers],
[`Info`][api-info],
[`Join`][api-join],
[`Map`][api-map],
[`Options`][api-options],
[`SafeConfig`][api-safe-config],
[`State`][api-State], and
[`Unsafe`][api-Unsafe].

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, `mdast-util-to-markdown@^2`,
compatible with Node.js 16.

## Security

`mdast-util-to-markdown` will do its best to serialize markdown to match the
syntax tree, but there are several cases where that is impossible.
It’ll do its best, but complete roundtripping is impossible given that any value
could be injected into the tree.

As markdown is sometimes used for HTML, and improper use of HTML can open you up
to a [cross-site scripting (XSS)][xss] attack, use of `mdast-util-to-markdown`
and parsing it again later could potentially be unsafe.
When parsing markdown afterwards and then going to HTML, use something like
[`hast-util-sanitize`][hast-util-sanitize] to make the tree safe.

## Related

* [`syntax-tree/mdast-util-from-markdown`](https://github.com/syntax-tree/mdast-util-from-markdown)
  — parse markdown to mdast
* [`micromark/micromark`](https://github.com/micromark/micromark)
  — parse markdown
* [`remarkjs/remark`](https://github.com/remarkjs/remark)
  — process markdown

## Contribute

See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
ways to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/syntax-tree/mdast-util-to-markdown/workflows/main/badge.svg

[build]: https://github.com/syntax-tree/mdast-util-to-markdown/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/mdast-util-to-markdown.svg

[coverage]: https://codecov.io/github/syntax-tree/mdast-util-to-markdown

[downloads-badge]: https://img.shields.io/npm/dm/mdast-util-to-markdown.svg

[downloads]: https://www.npmjs.com/package/mdast-util-to-markdown

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=mdast-util-to-markdown

[size]: https://bundlejs.com/?q=mdast-util-to-markdown

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/syntax-tree/unist/discussions

[npm]: https://docs.npmjs.com/cli/install

[esmsh]: https://esm.sh

[license]: license

[author]: https://wooorm.com

[health]: https://github.com/syntax-tree/.github

[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md

[support]: https://github.com/syntax-tree/.github/blob/main/support.md

[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[typescript]: https://www.typescriptlang.org

[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting

[hast-util-sanitize]: https://github.com/syntax-tree/hast-util-sanitize

[point]: https://github.com/syntax-tree/unist#point

[mdast]: https://github.com/syntax-tree/mdast

[node]: https://github.com/syntax-tree/mdast#nodes

[association]: https://github.com/syntax-tree/mdast#association

[mdast-util-gfm]: https://github.com/syntax-tree/mdast-util-gfm

[mdast-util-mdx]: https://github.com/syntax-tree/mdast-util-mdx

[mdast-util-frontmatter]: https://github.com/syntax-tree/mdast-util-frontmatter

[mdast-util-math]: https://github.com/syntax-tree/mdast-util-math

[mdast-util-directive]: https://github.com/syntax-tree/mdast-util-directive

[remark]: https://github.com/remarkjs/remark

[remark-stringify]: https://github.com/remarkjs/remark/tree/main/packages/remark-stringify

[api-construct-name]: #constructname

[api-construct-name-map]: #constructnamemap

[api-default-handlers]: #defaulthandlers

[api-handle]: #handle

[api-handlers]: #handlers

[api-info]: #info

[api-join]: #join

[api-map]: #map

[api-options]: #options

[api-safe-config]: #safeconfig

[api-state]: #state

[api-to-markdown]: #tomarkdowntree-options

[api-tracker]: #tracker

[api-unsafe]: #unsafe


---

# mdast-util-to-string

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[mdast][] utility to get the text content of a node.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`toString(value[, options])`](#tostringvalue-options)
    *   [`Options`](#options)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Security](#security)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package is a tiny utility that gets the textual content of a node.

## When should I use this?

This utility is useful when you have a node, say a heading, and want to get the
text inside it.

This package does not serialize markdown, that’s what
[`mdast-util-to-markdown`][mdast-util-to-markdown] does.

Similar packages, [`hast-util-to-string`][hast-util-to-string] and
[`hast-util-to-text`][hast-util-to-text], do the same but on [hast][].

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install mdast-util-to-string
```

In Deno with [`esm.sh`][esmsh]:

```js
import {toString} from 'https://esm.sh/mdast-util-to-string@4'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {toString} from 'https://esm.sh/mdast-util-to-string@4?bundle'
</script>
```

## Use

```js
import {fromMarkdown} from 'mdast-util-from-markdown'
import {toString} from 'mdast-util-to-string'

const tree = fromMarkdown('Some _emphasis_, **importance**, and `code`.')

console.log(toString(tree)) // => 'Some emphasis, importance, and code.'
```

## API

This package exports the identifier [`toString`][api-to-string].
There is no default export.

### `toString(value[, options])`

Get the text content of a node or list of nodes.

Prefers the node’s plain-text fields, otherwise serializes its children,
and if the given value is an array, serialize the nodes in it.

###### Parameters

*   `value` (`unknown`)
    — thing to serialize, typically [`Node`][node]
*   `options` ([`Options`][api-options], optional)
    — configuration

###### Returns

Serialized `value` (`string`).

### `Options`

Configuration (TypeScript type).

###### Fields

*   `includeImageAlt` (`boolean`, default: `true`)
    — whether to use `alt` for `image`s
*   `includeHtml` (`boolean`, default: `true`)
    — whether to use `value` of HTML

## Types

This package is fully typed with [TypeScript][].
It exports the additional type [`Options`][api-options].

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, `mdast-util-to-string@^4`,
compatible with Node.js 16.

## Security

Use of `mdast-util-to-string` does not involve **[hast][]**, user content, or
change the tree, so there are no openings for [cross-site scripting (XSS)][xss]
attacks.

## Related

*   [`hast-util-to-string`](https://github.com/wooorm/rehype-minify/tree/main/packages/hast-util-to-string)
    — get text content in hast
*   [`hast-util-to-text`](https://github.com/syntax-tree/hast-util-to-text)
    — get text content in hast according to the `innerText` algorithm

## Contribute

See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
ways to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/syntax-tree/mdast-util-to-string/workflows/main/badge.svg

[build]: https://github.com/syntax-tree/mdast-util-to-string/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/mdast-util-to-string.svg

[coverage]: https://codecov.io/github/syntax-tree/mdast-util-to-string

[downloads-badge]: https://img.shields.io/npm/dm/mdast-util-to-string.svg

[downloads]: https://www.npmjs.com/package/mdast-util-to-string

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=mdast-util-to-string

[size]: https://bundlejs.com/?q=mdast-util-to-string

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/syntax-tree/unist/discussions

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[typescript]: https://www.typescriptlang.org

[license]: license

[author]: https://wooorm.com

[health]: https://github.com/syntax-tree/.github

[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md

[support]: https://github.com/syntax-tree/.github/blob/main/support.md

[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md

[mdast]: https://github.com/syntax-tree/mdast

[mdast-util-to-markdown]: https://github.com/syntax-tree/mdast-util-to-markdown

[hast]: https://github.com/syntax-tree/hast

[hast-util-to-string]: https://github.com/rehypejs/rehype-minify/tree/main/packages/hast-util-to-string

[hast-util-to-text]: https://github.com/syntax-tree/hast-util-to-text

[node]: https://github.com/syntax-tree/mdast#nodes

[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting

[api-to-string]: #tostringvalue-options

[api-options]: #options


---

# Changelog

## [2.0.30](https://github.com/mdn/data/compare/v2.0.29...v2.0.30) (2022-10-28)


### Bug Fixes

* correct mask-repeat initial value ([b36469e](https://github.com/mdn/data/commit/b36469e253ba551ba2a5a9738b814522309e5f6a))
* correct scroll-timeline-axis and mask-repeat initial value ([#622](https://github.com/mdn/data/issues/622)) ([e48302d](https://github.com/mdn/data/commit/e48302df0348c753db319c059cd5827b3603807d))
* correct scroll-timeline-axis initial value ([5144622](https://github.com/mdn/data/commit/51446221397120b25d39125bb608a2572c47b0d2))

## [2.0.29](https://github.com/mdn/data/compare/v2.0.28...v2.0.29) (2022-08-30)


### Miscellaneous Chores

* release 2.0.29 ([da9510f](https://github.com/mdn/data/commit/da9510f7c6cbb79e6eeda6dda51bc39358301ea6))

## [2.0.28](https://github.com/mdn/data/compare/v2.0.27...v2.0.28) (2022-07-12)


### Bug Fixes

* **css:** correct two syntax examples in selectors ([#589](https://github.com/mdn/data/issues/589)) ([91ab33a](https://github.com/mdn/data/commit/91ab33a40bf2dfd75286a01785453705105533e8))

### [2.0.27](https://github.com/mdn/data/compare/v2.0.26...v2.0.27) (2022-02-24)


### Miscellaneous Chores

* release ([a99ae2e](https://github.com/mdn/data/commit/a99ae2ebfeb930524c18f8d46954e8e32ab6b630))

### [2.0.26](https://www.github.com/mdn/data/compare/v2.0.25...v2.0.26) (2022-01-19)


### Miscellaneous Chores

* release 2.0.26 ([8b1045d](https://www.github.com/mdn/data/commit/8b1045dc488c7b278c933143efd1bdba75b6832f))

### [2.0.25](https://www.github.com/mdn/data/compare/v2.0.24...v2.0.25) (2021-12-21)


### Bug Fixes

* change branch reference to main ([a473261](https://www.github.com/mdn/data/commit/a473261308cf82ee387cec886c70ef3d570fc957))
* remove old clashing workflow ([af9a18c](https://www.github.com/mdn/data/commit/af9a18ce3af2cbca83582debf3c3d3fc0ace7402))


### Miscellaneous Chores

* release 2.0.25 ([db5a54b](https://www.github.com/mdn/data/commit/db5a54ba4f3c28b52d0801e115fd5ff0a0052743))
* release 2.0.25 ([0f453ee](https://www.github.com/mdn/data/commit/0f453eedadbd9065d552203260210bdfafa9d7ff))

### [2.0.24](https://www.github.com/mdn/data/compare/v2.0.24...v2.0.24) (2021-12-17)


### Miscellaneous Chores

* release 2.0.24 ([4d00c38](https://www.github.com/mdn/data/commit/4d00c386efe1cfbf536bb3bc80fed6d687f9ad04))

### [2.0.24](https://www.github.com/mdn/data/compare/v2.0.23...v2.0.24) (2021-12-15)


### Miscellaneous Chores

* release 2.0.24 ([abff6ff](https://www.github.com/mdn/data/commit/abff6ff0fb88e834c65a2cc05f346b105a9b2e99))


---

# MDN data

> **Note:** We are in the process of deprecating the `mdn/data` package in favor of [`w3c/webref`](https://github.com/w3c/webref). If this could present a problem to your project, please contact us via our [GitHub discussions](https://github.com/mdn/mdn-community/discussions/categories/platform). Thank you.

[https://github.com/mdn/data](https://github.com/mdn/data)

Maintained by the [MDN team at Mozilla](https://wiki.mozilla.org/MDN).

This repository contains general data for Web technologies.

This data is used in MDN documentation, to build
[information boxes](https://developer.mozilla.org/en-US/docs/Web/CSS/background)
or [sidebar navigation](https://developer.mozilla.org/en-US/docs/Web/API/Window).
External tools have started to make use of this data as well.
For example, the [CSSTree](https://github.com/csstree/csstree/) CSS parser.

[![NPM version](https://img.shields.io/npm/v/mdn-data.svg)](https://www.npmjs.com/package/mdn-data)
[![lint](https://github.com/mdn/data/actions/workflows/lint.yml/badge.svg)](https://github.com/mdn/data/actions/workflows/lint.yml)

## Repository contents

There's a top-level directory for each broad area covered: for example, `api`
and `css`. Inside each of these directories is one or more
JSON files containing the data.

### api

Contains data about Web APIs:

- API inheritance (interface inheritance and mixin implementations)

### css

Contains data about:

- CSS at-rules
- CSS properties
- CSS selectors
- CSS syntaxes
- CSS types
- CSS units

Read more about [CSS data](https://github.com/mdn/data/blob/master/css/readme.md) and the format of the files.

### l10n

The l10n folder contains localization strings that are used in the various
json files throughout this repository.

## Problems?

If you find a problem, please [file an issue](https://github.com/mdn/data/issues/new).

## Contributing

We're very happy to accept contributions to this data. Please familiarize yourself
with the schema for the data you're editing, and send us a pull request. See also the [Contributing file](https://github.com/mdn/data/blob/master/CONTRIBUTING.md) for more information.

## See also

- [https://github.com/mdn/browser-compat-data](https://github.com/mdn/browser-compat-data)
  for compatibility data for Web technologies


---

# MDN CSS data

This folder contains data about the different features of the [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS) language.

## Different types of CSS data

The CSS data is split into these parts:

* **at-rules**:
[data](https://github.com/mdn/data/blob/master/css/at-rules.json) |
[schema](https://github.com/mdn/data/blob/master/css/at-rules.schema.json) |
[docs](https://github.com/mdn/data/blob/master/css/at-rules.md)
* **properties**:
[data](https://github.com/mdn/data/blob/master/css/properties.json) |
[schema](https://github.com/mdn/data/blob/master/css/properties.schema.json) |
[docs](https://github.com/mdn/data/blob/master/css/properties.md)
* **selectors**:
[data](https://github.com/mdn/data/blob/master/css/selectors.json) |
[schema](https://github.com/mdn/data/blob/master/css/selectors.schema.json) |
[docs](https://github.com/mdn/data/blob/master/css/selectors.md)
* **syntaxes**:
[data](https://github.com/mdn/data/blob/master/css/syntaxes.json) |
[schema](https://github.com/mdn/data/blob/master/css/syntaxes.schema.json) |
[docs](https://github.com/mdn/data/blob/master/css/syntaxes.md)
* **types**:
[data](https://github.com/mdn/data/blob/master/css/types.json) |
[schema](https://github.com/mdn/data/blob/master/css/types.schema.json) |
[docs](https://github.com/mdn/data/blob/master/css/types.md)
* **units**:
[data](https://github.com/mdn/data/blob/master/css/units.json) |
[schema](https://github.com/mdn/data/blob/master/css/units.schema.json) |
[docs](https://github.com/mdn/data/blob/master/css/units.md)


---

0.3.0 / 2014-09-07
==================

  * Support Node.js 0.6
  * Throw error when parameter format invalid on parse

0.2.0 / 2014-06-18
==================

  * Add `typer.format()` to format media types

0.1.0 / 2014-06-17
==================

  * Accept `req` as argument to `parse`
  * Accept `res` as argument to `parse`
  * Parse media type with extra LWS between type and first parameter

0.0.0 / 2014-06-13
==================

  * Initial implementation


---

# media-typer

[![NPM Version][npm-image]][npm-url]
[![NPM Downloads][downloads-image]][downloads-url]
[![Node.js Version][node-version-image]][node-version-url]
[![Build Status][travis-image]][travis-url]
[![Test Coverage][coveralls-image]][coveralls-url]

Simple RFC 6838 media type parser

## Installation

```sh
$ npm install media-typer
```

## API

```js
var typer = require('media-typer')
```

### typer.parse(string)

```js
var obj = typer.parse('image/svg+xml; charset=utf-8')
```

Parse a media type string. This will return an object with the following
properties (examples are shown for the string `'image/svg+xml; charset=utf-8'`):

 - `type`: The type of the media type (always lower case). Example: `'image'`

 - `subtype`: The subtype of the media type (always lower case). Example: `'svg'`

 - `suffix`: The suffix of the media type (always lower case). Example: `'xml'`

 - `parameters`: An object of the parameters in the media type (name of parameter always lower case). Example: `{charset: 'utf-8'}`

### typer.parse(req)

```js
var obj = typer.parse(req)
```

Parse the `content-type` header from the given `req`. Short-cut for
`typer.parse(req.headers['content-type'])`.

### typer.parse(res)

```js
var obj = typer.parse(res)
```

Parse the `content-type` header set on the given `res`. Short-cut for
`typer.parse(res.getHeader('content-type'))`.

### typer.format(obj)

```js
var obj = typer.format({type: 'image', subtype: 'svg', suffix: 'xml'})
```

Format an object into a media type string. This will return a string of the
mime type for the given object. For the properties of the object, see the
documentation for `typer.parse(string)`.

## License

[MIT](LICENSE)

[npm-image]: https://img.shields.io/npm/v/media-typer.svg?style=flat
[npm-url]: https://npmjs.org/package/media-typer
[node-version-image]: https://img.shields.io/badge/node.js-%3E%3D_0.6-brightgreen.svg?style=flat
[node-version-url]: http://nodejs.org/download/
[travis-image]: https://img.shields.io/travis/jshttp/media-typer.svg?style=flat
[travis-url]: https://travis-ci.org/jshttp/media-typer
[coveralls-image]: https://img.shields.io/coveralls/jshttp/media-typer.svg?style=flat
[coveralls-url]: https://coveralls.io/r/jshttp/media-typer
[downloads-image]: https://img.shields.io/npm/dm/media-typer.svg?style=flat
[downloads-url]: https://npmjs.org/package/media-typer


---

# memfs

[![][chat-badge]][chat] [![][npm-badge]][npm-url] [![][travis-badge]][travis-url]

In-memory file-system with [Node's `fs` API](https://nodejs.org/api/fs.html).

- Node's `fs` API implemented, see [_old API Status_](./docs/api-status.md), [missing list](https://github.com/streamich/memfs/issues/735), [missing `opendir`](https://github.com/streamich/memfs/issues/663)
- Stores files in memory, in `Buffer`s
- Throws sameish\* errors as Node.js
- Has concept of _i-nodes_
- Implements _hard links_
- Implements _soft links_ (aka symlinks, symbolic links)
- Permissions may\* be implemented in the future
- Can be used in browser, see [`memfs-webpack`](https://github.com/streamich/memfs-webpack)

### Install

```shell
npm install --save memfs
```

## Usage

```js
import { fs } from 'memfs';

fs.writeFileSync('/hello.txt', 'World!');
fs.readFileSync('/hello.txt', 'utf8'); // World!
```

Create a file system from a plain JSON:

```js
import { fs, vol } from 'memfs';

const json = {
  './README.md': '1',
  './src/index.js': '2',
  './node_modules/debug/index.js': '3',
};
vol.fromJSON(json, '/app');

fs.readFileSync('/app/README.md', 'utf8'); // 1
vol.readFileSync('/app/src/index.js', 'utf8'); // 2
```

Export to JSON:

```js
vol.writeFileSync('/script.sh', 'sudo rm -rf *');
vol.toJSON(); // {"/script.sh": "sudo rm -rf *"}
```

Use it for testing:

```js
vol.writeFileSync('/foo', 'bar');
expect(vol.toJSON()).toEqual({ '/foo': 'bar' });
```

Create as many filesystem volumes as you need:

```js
import { Volume } from 'memfs';

const vol = Volume.fromJSON({ '/foo': 'bar' });
vol.readFileSync('/foo'); // bar

const vol2 = Volume.fromJSON({ '/foo': 'bar 2' });
vol2.readFileSync('/foo'); // bar 2
```

Use `memfs` together with [`unionfs`][unionfs] to create one filesystem
from your in-memory volumes and the real disk filesystem:

```js
import * as fs from 'fs';
import { ufs } from 'unionfs';

ufs.use(fs).use(vol);

ufs.readFileSync('/foo'); // bar
```

Use [`fs-monkey`][fs-monkey] to monkey-patch Node's `require` function:

```js
import { patchRequire } from 'fs-monkey';

vol.writeFileSync('/index.js', 'console.log("hi world")');
patchRequire(vol);
require('/index'); // hi world
```

## Docs

- [Reference](./docs/reference.md)
- [Relative paths](./docs/relative-paths.md)
- [API status](./docs/api-status.md)
- [Dependencies](./docs/dependencies.md)

## See also

- [`spyfs`][spyfs] - spies on filesystem actions
- [`unionfs`][unionfs] - creates a union of multiple filesystem volumes
- [`linkfs`][linkfs] - redirects filesystem paths
- [`fs-monkey`][fs-monkey] - monkey-patches Node's `fs` module and `require` function
- [`libfs`](https://github.com/streamich/full-js/blob/master/src/lib/fs.ts) - real filesystem (that executes UNIX system calls) implemented in JavaScript

[chat]: https://onp4.com/@vadim/~memfs
[chat-badge]: https://img.shields.io/badge/Chat-%F0%9F%92%AC-green?style=flat&logo=chat&link=https://onp4.com/@vadim/~memfs
[npm-url]: https://www.npmjs.com/package/memfs
[npm-badge]: https://img.shields.io/npm/v/memfs.svg
[travis-url]: https://travis-ci.org/streamich/memfs
[travis-badge]: https://travis-ci.org/streamich/memfs.svg?branch=master
[memfs]: https://github.com/streamich/memfs
[unionfs]: https://github.com/streamich/unionfs
[linkfs]: https://github.com/streamich/linkfs
[spyfs]: https://github.com/streamich/spyfs
[fs-monkey]: https://github.com/streamich/fs-monkey

## License

[Unlicense](./LICENSE) - public domain.


---

1.0.1 / 2016-01-17
==================

  * perf: enable strict mode

1.0.0 / 2015-03-01
==================

  * Add option to only add new descriptors
  * Add simple argument validation
  * Add jsdoc to source file

0.0.2 / 2013-12-14
==================

  * Move repository to `component` organization

0.0.1 / 2013-10-29
==================

  * Initial release


---

# merge-descriptors

[![NPM Version][npm-image]][npm-url]
[![NPM Downloads][downloads-image]][downloads-url]
[![Build Status][travis-image]][travis-url]
[![Test Coverage][coveralls-image]][coveralls-url]

Merge objects using descriptors.

```js
var thing = {
  get name() {
    return 'jon'
  }
}

var animal = {

}

merge(animal, thing)

animal.name === 'jon'
```

## API

### merge(destination, source)

Redefines `destination`'s descriptors with `source`'s. The return value is the
`destination` object.

### merge(destination, source, false)

Defines `source`'s descriptors on `destination` if `destination` does not have
a descriptor by the same name. The return value is the `destination` object.

## License

[MIT](LICENSE)

[npm-image]: https://img.shields.io/npm/v/merge-descriptors.svg
[npm-url]: https://npmjs.org/package/merge-descriptors
[travis-image]: https://img.shields.io/travis/component/merge-descriptors/master.svg
[travis-url]: https://travis-ci.org/component/merge-descriptors
[coveralls-image]: https://img.shields.io/coveralls/component/merge-descriptors/master.svg
[coveralls-url]: https://coveralls.io/r/component/merge-descriptors?branch=master
[downloads-image]: https://img.shields.io/npm/dm/merge-descriptors.svg
[downloads-url]: https://npmjs.org/package/merge-descriptors


---

# merge-stream

Merge (interleave) a bunch of streams.

[![build status](https://secure.travis-ci.org/grncdr/merge-stream.svg?branch=master)](http://travis-ci.org/grncdr/merge-stream)

## Synopsis

```javascript
var stream1 = new Stream();
var stream2 = new Stream();

var merged = mergeStream(stream1, stream2);

var stream3 = new Stream();
merged.add(stream3);
merged.isEmpty();
//=> false
```

## Description

This is adapted from [event-stream](https://github.com/dominictarr/event-stream) separated into a new module, using Streams3.

## API

### `mergeStream`

Type: `function`

Merges an arbitrary number of streams. Returns a merged stream.

#### `merged.add`

A method to dynamically add more sources to the stream. The argument supplied to `add` can be either a source or an array of sources.

#### `merged.isEmpty`

A method that tells you if the merged stream is empty.

When a stream is "empty" (aka. no sources were added), it could not be returned to a gulp task.

So, we could do something like this:

```js
stream = require('merge-stream')();
// Something like a loop to add some streams to the merge stream
// stream.add(streamA);
// stream.add(streamB);
return stream.isEmpty() ? null : stream;
```

## Gulp example

An example use case for **merge-stream** is to combine parts of a task in a project's **gulpfile.js** like this:

```js
const gulp =          require('gulp');
const htmlValidator = require('gulp-w3c-html-validator');
const jsHint =        require('gulp-jshint');
const mergeStream =   require('merge-stream');

function lint() {
  return mergeStream(
    gulp.src('src/*.html')
      .pipe(htmlValidator())
      .pipe(htmlValidator.reporter()),
    gulp.src('src/*.js')
      .pipe(jsHint())
      .pipe(jsHint.reporter())
  );
}
gulp.task('lint', lint);
```

## License

MIT


---

# merge2

Merge multiple streams into one stream in sequence or parallel.

[![NPM version][npm-image]][npm-url]
[![Build Status][travis-image]][travis-url]
[![Downloads][downloads-image]][downloads-url]

## Install

Install with [npm](https://npmjs.org/package/merge2)

```sh
npm install merge2
```

## Usage

```js
const gulp = require('gulp')
const merge2 = require('merge2')
const concat = require('gulp-concat')
const minifyHtml = require('gulp-minify-html')
const ngtemplate = require('gulp-ngtemplate')

gulp.task('app-js', function () {
  return merge2(
      gulp.src('static/src/tpl/*.html')
        .pipe(minifyHtml({empty: true}))
        .pipe(ngtemplate({
          module: 'genTemplates',
          standalone: true
        })
      ), gulp.src([
        'static/src/js/app.js',
        'static/src/js/locale_zh-cn.js',
        'static/src/js/router.js',
        'static/src/js/tools.js',
        'static/src/js/services.js',
        'static/src/js/filters.js',
        'static/src/js/directives.js',
        'static/src/js/controllers.js'
      ])
    )
    .pipe(concat('app.js'))
    .pipe(gulp.dest('static/dist/js/'))
})
```

```js
const stream = merge2([stream1, stream2], stream3, {end: false})
//...
stream.add(stream4, stream5)
//..
stream.end()
```

```js
// equal to merge2([stream1, stream2], stream3)
const stream = merge2()
stream.add([stream1, stream2])
stream.add(stream3)
```

```js
// merge order:
//   1. merge `stream1`;
//   2. merge `stream2` and `stream3` in parallel after `stream1` merged;
//   3. merge 'stream4' after `stream2` and `stream3` merged;
const stream = merge2(stream1, [stream2, stream3], stream4)

// merge order:
//   1. merge `stream5` and `stream6` in parallel after `stream4` merged;
//   2. merge 'stream7' after `stream5` and `stream6` merged;
stream.add([stream5, stream6], stream7)
```

```js
// nest merge
// equal to merge2(stream1, stream2, stream6, stream3, [stream4, stream5]);
const streamA = merge2(stream1, stream2)
const streamB = merge2(stream3, [stream4, stream5])
const stream = merge2(streamA, streamB)
streamA.add(stream6)
```

## API

```js
const merge2 = require('merge2')
```

### merge2()

### merge2(options)

### merge2(stream1, stream2, ..., streamN)

### merge2(stream1, stream2, ..., streamN, options)

### merge2(stream1, [stream2, stream3, ...], streamN, options)

return a duplex stream (mergedStream). streams in array will be merged in parallel.

### mergedStream.add(stream)

### mergedStream.add(stream1, [stream2, stream3, ...], ...)

return the mergedStream.

### mergedStream.on('queueDrain', function() {})

It will emit 'queueDrain' when all streams merged. If you set `end === false` in options, this event give you a notice that should add more streams to merge or end the mergedStream.

#### stream

*option*
Type: `Readable` or `Duplex` or `Transform` stream.

#### options

*option*
Type: `Object`.

* **end** - `Boolean` - if `end === false` then mergedStream will not be auto ended, you should end by yourself. **Default:** `undefined`

* **pipeError** - `Boolean` - if `pipeError === true` then mergedStream will emit `error` event from source streams. **Default:** `undefined`

* **objectMode** - `Boolean` . **Default:** `true`

`objectMode` and other options(`highWaterMark`, `defaultEncoding` ...) is same as Node.js `Stream`.

## License

MIT © [Teambition](https://www.teambition.com)

[npm-url]: https://npmjs.org/package/merge2
[npm-image]: http://img.shields.io/npm/v/merge2.svg

[travis-url]: https://travis-ci.org/teambition/merge2
[travis-image]: http://img.shields.io/travis/teambition/merge2.svg

[downloads-url]: https://npmjs.org/package/merge2
[downloads-image]: http://img.shields.io/npm/dm/merge2.svg?style=flat-square


---

1.1.2 / 2016-01-17
==================

  * perf: enable strict mode

1.1.1 / 2014-12-30
==================

  * Improve `browserify` support

1.1.0 / 2014-07-05
==================

  * Add `CONNECT` method
 
1.0.1 / 2014-06-02
==================

  * Fix module to work with harmony transform

1.0.0 / 2014-05-08
==================

  * Add `PURGE` method

0.1.0 / 2013-10-28
==================

  * Add `http.METHODS` support


---

# Methods

[![NPM Version][npm-image]][npm-url]
[![NPM Downloads][downloads-image]][downloads-url]
[![Node.js Version][node-version-image]][node-version-url]
[![Build Status][travis-image]][travis-url]
[![Test Coverage][coveralls-image]][coveralls-url]

HTTP verbs that Node.js core's HTTP parser supports.

This module provides an export that is just like `http.METHODS` from Node.js core,
with the following differences:

  * All method names are lower-cased.
  * Contains a fallback list of methods for Node.js versions that do not have a
    `http.METHODS` export (0.10 and lower).
  * Provides the fallback list when using tools like `browserify` without pulling
    in the `http` shim module.

## Install

```bash
$ npm install methods
```

## API

```js
var methods = require('methods')
```

### methods

This is an array of lower-cased method names that Node.js supports. If Node.js
provides the `http.METHODS` export, then this is the same array lower-cased,
otherwise it is a snapshot of the verbs from Node.js 0.10.

## License

[MIT](LICENSE)

[npm-image]: https://img.shields.io/npm/v/methods.svg?style=flat
[npm-url]: https://npmjs.org/package/methods
[node-version-image]: https://img.shields.io/node/v/methods.svg?style=flat
[node-version-url]: https://nodejs.org/en/download/
[travis-image]: https://img.shields.io/travis/jshttp/methods.svg?style=flat
[travis-url]: https://travis-ci.org/jshttp/methods
[coveralls-image]: https://img.shields.io/coveralls/jshttp/methods.svg?style=flat
[coveralls-url]: https://coveralls.io/r/jshttp/methods?branch=master
[downloads-image]: https://img.shields.io/npm/dm/methods.svg?style=flat
[downloads-url]: https://npmjs.org/package/methods


---

# micromark-factory-space

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] factory to parse [markdown space][markdown-space] (found in lots
of places).

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`factorySpace(…)`](#factoryspace)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes states to parse spaces and/or tabs.

## When should I use this?

This package is useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-factory-space
```

In Deno with [`esm.sh`][esmsh]:

```js
import {factorySpace} from 'https://esm.sh/micromark-factory-space@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {factorySpace} from 'https://esm.sh/micromark-factory-space@1?bundle'
</script>
```

## Use

```js
import {factorySpace} from 'micromark-factory-space'
import {codes, types} from 'micromark-util-symbol'

// A micromark tokenizer that uses the factory:
/**
 * @this {TokenizeContext}
 *   Context.
 * @type {Tokenizer}
 */
function tokenizeCodeFenced(effects, ok, nok) {
  return start

  // …

  /** @type {State} */
  function info(code) {
    if (code === codes.eof || markdownLineEndingOrSpace(code)) {
      effects.exit(types.chunkString)
      effects.exit(types.codeFencedFenceInfo)
      return factorySpace(effects, infoAfter, types.whitespace)(code)
    }

    if (code === codes.graveAccent && code === marker) return nok(code)
    effects.consume(code)
    return info
  }

  // …
}
```

## API

This module exports the identifier [`factorySpace`][api-factory-space].
There is no default export.

### `factorySpace(…)`

Parse spaces and tabs.

There is no `nok` parameter:

* spaces in markdown are often optional, in which case this factory can be
  used and `ok` will be switched to whether spaces were found or not
* one line ending or space can be detected with `markdownSpace(code)` right
  before using `factorySpace`

###### Examples

Where `␉` represents a tab (plus how much it expands) and `␠` represents a
single space.

```markdown
␉
␠␠␠␠
␉␠
```

###### Parameters

* `effects` (`Effects`)
  — context
* `ok` (`State`)
  — state switched to when successful
* `type` (`string`)
  — type (`' \t'`)
* `max` (`number`, default: `Infinity`)
  — max (exclusive)

###### Returns

Start state (`State`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-factory-space@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-factory-space.svg

[downloads]: https://www.npmjs.com/package/micromark-factory-space

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-factory-space

[bundle-size]: https://bundlejs.com/?q=micromark-factory-space

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[markdown-space]: https://github.com/micromark/micromark/tree/main/packages/micromark-util-character#markdownspacecode

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[api-factory-space]: #factoryspace


---

# micromark-util-character

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility to handle [character codes][code].

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`asciiAlpha(code)`](#asciialphacode)
  * [`asciiAlphanumeric(code)`](#asciialphanumericcode)
  * [`asciiAtext(code)`](#asciiatextcode)
  * [`asciiControl(code)`](#asciicontrolcode)
  * [`asciiDigit(code)`](#asciidigitcode)
  * [`asciiHexDigit(code)`](#asciihexdigitcode)
  * [`asciiPunctuation(code)`](#asciipunctuationcode)
  * [`markdownLineEnding(code)`](#markdownlineendingcode)
  * [`markdownLineEndingOrSpace(code)`](#markdownlineendingorspacecode)
  * [`markdownSpace(code)`](#markdownspacecode)
  * [`unicodePunctuation(code)`](#unicodepunctuationcode)
  * [`unicodeWhitespace(code)`](#unicodewhitespacecode)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes algorithms to check whether characters match groups.

## When should I use this?

This package might be useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-character
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as character from 'https://esm.sh/micromark-util-character@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as character from 'https://esm.sh/micromark-util-character@1?bundle'
</script>
```

## Use

```js
import {asciiAlpha} from 'micromark-util-character'

console.log(asciiAlpha(64)) // false
console.log(asciiAlpha(65)) // true
```

## API

This module exports the identifiers
[`asciiAlpha`][api-ascii-alpha],
[`asciiAlphanumeric`][api-ascii-alphanumeric],
[`asciiAtext`][api-ascii-atext],
[`asciiControl`][api-ascii-control],
[`asciiDigit`][api-ascii-digit],
[`asciiHexDigit`][api-ascii-hex-digit],
[`asciiPunctuation`][api-ascii-punctuation],
[`markdownLineEnding`][api-markdown-line-ending],
[`markdownLineEndingOrSpace`][api-markdown-line-ending-or-space],
[`markdownSpace`][api-markdown-space],
[`unicodePunctuation`][api-unicode-punctuation],
[`unicodeWhitespace`][api-unicode-whitespace].
There is no default export.

### `asciiAlpha(code)`

Check whether the [character code][code] represents an ASCII alpha (`a` through
`z`, case insensitive).

An **ASCII alpha** is an ASCII upper alpha or ASCII lower alpha.

An **ASCII upper alpha** is a character in the inclusive range U+0041 (`A`)
to U+005A (`Z`).

An **ASCII lower alpha** is a character in the inclusive range U+0061 (`a`)
to U+007A (`z`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiAlphanumeric(code)`

Check whether the [character code][code] represents an ASCII alphanumeric (`a`
through `z`, case insensitive, or `0` through `9`).

An **ASCII alphanumeric** is an ASCII digit (see `asciiDigit`) or ASCII alpha
(see `asciiAlpha`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiAtext(code)`

Check whether the [character code][code] represents an ASCII atext.

atext is an ASCII alphanumeric (see `asciiAlphanumeric`), or a character in
the inclusive ranges U+0023 NUMBER SIGN (`#`) to U+0027 APOSTROPHE (`'`),
U+002A ASTERISK (`*`), U+002B PLUS SIGN (`+`), U+002D DASH (`-`), U+002F
SLASH (`/`), U+003D EQUALS TO (`=`), U+003F QUESTION MARK (`?`), U+005E
CARET (`^`) to U+0060 GRAVE ACCENT (`` ` ``), or U+007B LEFT CURLY BRACE
(`{`) to U+007E TILDE (`~`) (**\[RFC5322]**).

See **\[RFC5322]**:\
[Internet Message Format](https://tools.ietf.org/html/rfc5322).\
P. Resnick.\
IETF.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiControl(code)`

Check whether a [character code][code] is an ASCII control character.

An **ASCII control** is a character in the inclusive range U+0000 NULL (NUL)
to U+001F (US), or U+007F (DEL).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiDigit(code)`

Check whether the [character code][code] represents an ASCII digit (`0` through
`9`).

An **ASCII digit** is a character in the inclusive range U+0030 (`0`) to
U+0039 (`9`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiHexDigit(code)`

Check whether the [character code][code] represents an ASCII hex digit (`a`
through `f`, case insensitive, or `0` through `9`).

An **ASCII hex digit** is an ASCII digit (see `asciiDigit`), ASCII upper hex
digit, or an ASCII lower hex digit.

An **ASCII upper hex digit** is a character in the inclusive range U+0041
(`A`) to U+0046 (`F`).

An **ASCII lower hex digit** is a character in the inclusive range U+0061
(`a`) to U+0066 (`f`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiPunctuation(code)`

Check whether the [character code][code] represents ASCII punctuation.

An **ASCII punctuation** is a character in the inclusive ranges U+0021
EXCLAMATION MARK (`!`) to U+002F SLASH (`/`), U+003A COLON (`:`) to U+0040 AT
SIGN (`@`), U+005B LEFT SQUARE BRACKET (`[`) to U+0060 GRAVE ACCENT
(`` ` ``), or U+007B LEFT CURLY BRACE (`{`) to U+007E TILDE (`~`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownLineEnding(code)`

Check whether a [character code][code] is a markdown line ending.

A **markdown line ending** is the virtual characters M-0003 CARRIAGE RETURN
LINE FEED (CRLF), M-0004 LINE FEED (LF) and M-0005 CARRIAGE RETURN (CR).

In micromark, the actual character U+000A LINE FEED (LF) and U+000D CARRIAGE
RETURN (CR) are replaced by these virtual characters depending on whether
they occurred together.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownLineEndingOrSpace(code)`

Check whether a [character code][code] is a markdown line ending (see
`markdownLineEnding`) or markdown space (see `markdownSpace`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownSpace(code)`

Check whether a [character code][code] is a markdown space.

A **markdown space** is the concrete character U+0020 SPACE (SP) and the
virtual characters M-0001 VIRTUAL SPACE (VS) and M-0002 HORIZONTAL TAB (HT).

In micromark, the actual character U+0009 CHARACTER TABULATION (HT) is
replaced by one M-0002 HORIZONTAL TAB (HT) and between 0 and 3 M-0001 VIRTUAL
SPACE (VS) characters, depending on the column at which the tab occurred.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `unicodePunctuation(code)`

Check whether the [character code][code] represents Unicode punctuation.

A **Unicode punctuation** is a character in the Unicode `Pc` (Punctuation,
Connector), `Pd` (Punctuation, Dash), `Pe` (Punctuation, Close), `Pf`
(Punctuation, Final quote), `Pi` (Punctuation, Initial quote), `Po`
(Punctuation, Other), or `Ps` (Punctuation, Open) categories, or an ASCII
punctuation (see `asciiPunctuation`) (**\[UNICODE]**).

See **\[UNICODE]**:\
[The Unicode Standard](https://www.unicode.org/versions/).\
Unicode Consortium.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `unicodeWhitespace(code)`

Check whether the [character code][code] represents Unicode whitespace.

Note that this does handle micromark specific markdown whitespace characters.
See `markdownLineEndingOrSpace` to check that.

A **Unicode whitespace** is a character in the Unicode `Zs` (Separator,
Space) category, or U+0009 CHARACTER TABULATION (HT), U+000A LINE FEED (LF),
U+000C (FF), or U+000D CARRIAGE RETURN (CR) (**\[UNICODE]**).

See **\[UNICODE]**:\
[The Unicode Standard](https://www.unicode.org/versions/).\
Unicode Consortium.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-character@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-character.svg

[downloads]: https://www.npmjs.com/package/micromark-util-character

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-character

[bundle-size]: https://bundlejs.com/?q=micromark-util-character

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[code]: https://github.com/micromark/micromark#preprocess

[api-ascii-alpha]: #asciialphacode

[api-ascii-alphanumeric]: #asciialphanumericcode

[api-ascii-atext]: #asciiatextcode

[api-ascii-control]: #asciicontrolcode

[api-ascii-digit]: #asciidigitcode

[api-ascii-hex-digit]: #asciihexdigitcode

[api-ascii-punctuation]: #asciipunctuationcode

[api-markdown-line-ending]: #markdownlineendingcode

[api-markdown-line-ending-or-space]: #markdownlineendingorspacecode

[api-markdown-space]: #markdownspacecode

[api-unicode-punctuation]: #unicodepunctuationcode

[api-unicode-whitespace]: #unicodewhitespacecode


---

# micromark-util-symbol

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility with symbols.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes constants used throughout the micromark ecosystem.

## When should I use this?

This package is useful when you are making your own micromark extensions.
It’s useful to reference these constants by name instead of value while
developing.
[`micromark-build`][micromark-build] compiles them away for production code.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-symbol
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as symbol from 'https://esm.sh/micromark-util-symbol@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as symbol from 'https://esm.sh/micromark-util-symbol@1?bundle'
</script>
```

## Use

```js
import {codes, constants, types, values} from 'micromark-util-symbol'

console.log(codes.atSign) // 64
console.log(constants.characterReferenceNamedSizeMax) // 31
console.log(types.definitionDestinationRaw) // 'definitionDestinationRaw'
console.log(values.atSign) // '@'
```

## API

This package exports the identifiers `codes`, `constants`, `types`, and
`values`.
There is no default export.

Each identifier is an object mapping strings to values.
See the code for the exposed data.

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-symbol@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-symbol.svg

[downloads]: https://www.npmjs.com/package/micromark-util-symbol

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-symbol

[bundle-size]: https://bundlejs.com/?q=micromark-util-symbol

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[micromark-build]: https://github.com/micromark/micromark/tree/main/packages/micromark-build


---

# micromark

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

Markdown parser.

> **Note**: this is the `micromark` package from the micromark monorepo.
> See the [monorepo readme][micromark] for more on the project.
> See this readme for how to use it.

## Feature highlights

<!-- Note: this section has to be in sync with the monorepo readme. -->

* [x] **[compliant][commonmark]** (100% to CommonMark)
* [x] **[extensions][]** (100% [GFM][], 100% [MDX.js][mdxjs], [directives][],
  [frontmatter][], [math][])
* [x] **[safe][security]** (by default)
* [x] **[robust][test]** (±2k tests, 100% coverage, fuzz testing)
* [x] **[small][size-debug]** (smallest CM parser at ±14kb)

## Contents

* [When should I use this?](#when-should-i-use-this)
* [What is this?](#what-is-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`micromark(value[, encoding][, options])`](#micromarkvalue-encoding-options)
  * [`stream(options?)`](#streamoptions)
  * [`Options`](#options)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [Sponsor](#sponsor)
* [License](#license)

## When should I use this?

<!-- Note: this section has to be in sync with the monorepo readme. -->

* If you *just* want to turn markdown into HTML (with maybe a few extensions)
* If you want to do *really complex things* with markdown

See [§ Comparison][comparison] for more info

## What is this?

<!-- Note: this section has to be in sync with the monorepo readme. -->

`micromark` is an open source markdown parser written in JavaScript.
It’s implemented as a state machine that emits concrete tokens, so that every
byte is accounted for, with positional info.
It then compiles those tokens directly to HTML, but other tools can take the
data and for example build an AST which is easier to work with
([`mdast-util-to-markdown`][mdast-util-to-markdown]).

While most markdown parsers work towards compliancy with CommonMark (or GFM),
this project goes further by following how the reference parsers (`cmark`,
`cmark-gfm`) work, which is confirmed with thousands of extra tests.

Other than CommonMark and GFM, micromark also supports common extensions to
markdown such as MDX, math, and frontmatter.

These npm packages have a sibling project in Rust:
[`markdown-rs`][markdown-rs].

* to learn markdown, see this [cheatsheet and tutorial][cheat]
* for more about us, see [`unifiedjs.com`][site]
* for questions, see [Discussions][chat]
* to help, see [contribute][] and [sponsor][] below

## Install

<!-- Note: this section has to be in sync with the monorepo readme. -->

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark
```

In Deno with [`esm.sh`][esmsh]:

```js
import {micromark} from 'https://esm.sh/micromark@3'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {micromark} from 'https://esm.sh/micromark@3?bundle'
</script>
```

## Use

<!-- Note: this section has to be in sync with the `micromark` readme. -->

Typical use (buffering):

```js
import {micromark} from 'micromark'

console.log(micromark('## Hello, *world*!'))
```

Yields:

```html
<h2>Hello, <em>world</em>!</h2>
```

You can pass extensions (in this case [`micromark-extension-gfm`][gfm]):

```js
import {micromark} from 'micromark'
import {gfmHtml, gfm} from 'micromark-extension-gfm'

const value = '* [x] contact@example.com ~~strikethrough~~'

const result = micromark(value, {
  extensions: [gfm()],
  htmlExtensions: [gfmHtml()]
})

console.log(result)
```

Yields:

```html
<ul>
<li><input checked="" disabled="" type="checkbox"> <a href="mailto:contact@example.com">contact@example.com</a> <del>strikethrough</del></li>
</ul>
```

Streaming interface:

```js
import {createReadStream} from 'node:fs'
import {stream} from 'micromark/stream'

createReadStream('example.md')
  .on('error', handleError)
  .pipe(stream())
  .pipe(process.stdout)

function handleError(error) {
  // Handle your error here!
  throw error
}
```

## API

`micromark` core has two entries in its export map: `micromark` and
`micromark/stream`.

`micromark` exports the identifier [`micromark`][api-micromark].
`micromark/stream` exports the identifier [`stream`][api-stream].
There are no default exports.

The export map supports the [`development` condition][development].
Run `node --conditions development module.js` to get instrumented dev code.
Without this condition, production code is loaded.
See [§ Size & debug][size-debug] for more info.

### `micromark(value[, encoding][, options])`

Compile markdown to HTML.

> Note: which encodings are supported depends on the engine.
> For info on Node.js, see *[WHATWG supported encodings][encoding]*.

###### Parameters

* `value` (`string` or [`Uint8Array`][uint8-array])
  — markdown to parse
* `encoding` (`string`, default: `'utf8'`)
  — [character encoding][encoding] to understand `value` as when it’s a
  [`Uint8Array`][uint8-array]
* `options` ([`Options`][api-options], optional)
  — configuration

###### Returns

Compiled HTML (`string`).

### `stream(options?)`

Create a duplex (readable and writable) stream.

Some of the work to parse markdown can be done streaming, but in the
end buffering is required.

micromark does not handle errors for you, so you must handle errors on whatever
streams you pipe into it.
As markdown does not know errors, `micromark` itself does not emit errors.

###### Parameters

* `options` ([`Options`][api-options], optional)
  — configuration

###### Returns

Duplex stream.

### `Options`

Configuration (TypeScript type).

##### Fields

###### `allowDangerousHtml`

Whether to allow (dangerous) HTML (`boolean`, default: `false`).

The default is `false`, which still parses the HTML according to `CommonMark`
but shows the HTML as text instead of as elements.

Pass `true` for trusted content to get actual HTML elements.
See [§ Security][security].

###### `allowDangerousProtocol`

Whether to allow dangerous protocols in links and images (`boolean`, default:
`false`).

The default is `false`, which drops URLs in links and images that use dangerous
protocols.

Pass `true` for trusted content to support all protocols.

URLs that have no protocol (which means it’s relative to the current page, such
as `./some/page.html`) and URLs that have a safe protocol (for images: `http`,
`https`; for links: `http`, `https`, `irc`, `ircs`, `mailto`, `xmpp`), are
safe.
All other URLs are dangerous and dropped.
See [§ Security][security].

###### `defaultLineEnding`

Default line ending to use when compiling to HTML, for line endings not in
`value` (`'\r'`, `'\n'`, or `'\r\n'`; default: first line ending or `'\n'`).

Generally, `micromark` copies line endings (`\r`, `\n`, `\r\n`) in the markdown
document over to the compiled HTML.
In some cases, such as `> a`, CommonMark requires that extra line endings are
added: `<blockquote>\n<p>a</p>\n</blockquote>`.

To create that line ending, the document is checked for the first line ending
that is used.
If there is no line ending, `defaultLineEnding` is used.
If that isn’t configured, `\n` is used.

###### `extensions`

Array of syntax extensions (`Array<SyntaxExtension>`, default: `[]`).
See [§ Extensions][extensions].

###### `htmlExtensions`

Array of syntax extensions (`Array<HtmlExtension>`, default: `[]`).
See [§ Extensions][extensions].

## Types

This package is fully typed with [TypeScript][].
It exports the additional type [`Options`][api-options].

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, `micromark@4`, compatible
with Node.js 16.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## Sponsor

<!-- Note: this section has to be in sync with the monorepo readme. -->

Support this effort and give back by sponsoring on [OpenCollective][]!

<table>
<tr valign="middle">
<td width="100%" align="center" colspan="10">
  <br>
  <a href="https://www.salesforce.com">Salesforce</a> 🏅<br><br>
  <a href="https://www.salesforce.com"><img src="https://images.opencollective.com/salesforce/ca8f997/logo/512.png" width="256"></a>
</td>
</tr>
<tr valign="middle">
<td width="20%" align="center" rowspan="2" colspan="2">
  <a href="https://vercel.com">Vercel</a><br><br>
  <a href="https://vercel.com"><img src="https://avatars1.githubusercontent.com/u/14985020?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
  <a href="https://motif.land">Motif</a><br><br>
  <a href="https://motif.land"><img src="https://avatars1.githubusercontent.com/u/74457950?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
  <a href="https://www.hashicorp.com">HashiCorp</a><br><br>
  <a href="https://www.hashicorp.com"><img src="https://avatars1.githubusercontent.com/u/761456?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
  <a href="https://www.gitbook.com">GitBook</a><br><br>
  <a href="https://www.gitbook.com"><img src="https://avatars1.githubusercontent.com/u/7111340?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
  <a href="https://www.gatsbyjs.org">Gatsby</a><br><br>
  <a href="https://www.gatsbyjs.org"><img src="https://avatars1.githubusercontent.com/u/12551863?s=256&v=4" width="128"></a>
</td>
</tr>
<tr valign="middle">
</tr>
<tr valign="middle">
<td width="20%" align="center" rowspan="2" colspan="2">
  <a href="https://www.netlify.com">Netlify</a><br><br>
  <!--OC has a sharper image-->
  <a href="https://www.netlify.com"><img src="https://images.opencollective.com/netlify/4087de2/logo/256.png" width="128"></a>
</td>
<td width="10%" align="center">
  <a href="https://www.coinbase.com">Coinbase</a><br><br>
  <a href="https://www.coinbase.com"><img src="https://avatars1.githubusercontent.com/u/1885080?s=256&v=4" width="64"></a>
</td>
<td width="10%" align="center">
  <a href="https://themeisle.com">ThemeIsle</a><br><br>
  <a href="https://themeisle.com"><img src="https://avatars1.githubusercontent.com/u/58979018?s=128&v=4" width="64"></a>
</td>
<td width="10%" align="center">
  <a href="https://expo.io">Expo</a><br><br>
  <a href="https://expo.io"><img src="https://avatars1.githubusercontent.com/u/12504344?s=128&v=4" width="64"></a>
</td>
<td width="10%" align="center">
  <a href="https://boostnote.io">Boost Note</a><br><br>
  <a href="https://boostnote.io"><img src="https://images.opencollective.com/boosthub/6318083/logo/128.png" width="64"></a>
</td>
<td width="10%" align="center">
  <a href="https://markdown.space">Markdown Space</a><br><br>
  <a href="https://markdown.space"><img src="https://images.opencollective.com/markdown-space/e1038ed/logo/128.png" width="64"></a>
</td>
<td width="10%" align="center">
  <a href="https://www.holloway.com">Holloway</a><br><br>
  <a href="https://www.holloway.com"><img src="https://avatars1.githubusercontent.com/u/35904294?s=128&v=4" width="64"></a>
</td>
<td width="10%"></td>
<td width="10%"></td>
</tr>
<tr valign="middle">
<td width="100%" align="center" colspan="8">
  <br>
  <a href="https://opencollective.com/unified"><strong>You?</strong></a>
  <br><br>
</td>
</tr>
</table>

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[api-micromark]: #micromarkvalue-encoding-options

[api-options]: #options

[api-stream]: #streamoptions

[author]: https://wooorm.com

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[build]: https://github.com/micromark/micromark/actions

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[bundle-size]: https://bundlejs.com/?q=micromark

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark

[chat]: https://github.com/micromark/micromark/discussions

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[cheat]: https://commonmark.org/help/

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[commonmark]: https://commonmark.org

[comparison]: https://github.com/micromark/micromark#comparison

[contribute]: #contribute

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[coverage]: https://codecov.io/github/micromark/micromark

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[development]: https://nodejs.org/api/packages.html#packages_resolving_user_conditions

[directives]: https://github.com/micromark/micromark-extension-directive

[downloads]: https://www.npmjs.com/package/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark.svg

[encoding]: https://nodejs.org/api/util.html#whatwg-supported-encodings

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[extensions]: https://github.com/micromark/micromark#extensions

[frontmatter]: https://github.com/micromark/micromark-extension-frontmatter

[gfm]: https://github.com/micromark/micromark-extension-gfm

[health]: https://github.com/micromark/.github

[license]: https://github.com/micromark/micromark/blob/main/license

[markdown-rs]: https://github.com/wooorm/markdown-rs

[math]: https://github.com/micromark/micromark-extension-math

[mdast-util-to-markdown]: https://github.com/syntax-tree/mdast-util-to-markdown

[mdxjs]: https://github.com/micromark/micromark-extension-mdxjs

[micromark]: https://github.com/micromark/micromark

[npm]: https://docs.npmjs.com/cli/install

[opencollective]: https://opencollective.com/unified

[security]: #security

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[site]: https://unifiedjs.com

[size-debug]: https://github.com/micromark/micromark#size--debug

[sponsor]: #sponsor

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[support]: https://github.com/micromark/.github/blob/main/support.md

[test]: https://github.com/micromark/micromark#test

[typescript]: https://www.typescriptlang.org

[uint8-array]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array


---

# micromark-factory-space

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] factory to parse [markdown space][markdown-space] (found in lots
of places).

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`factorySpace(…)`](#factoryspace)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes states to parse spaces and/or tabs.

## When should I use this?

This package is useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-factory-space
```

In Deno with [`esm.sh`][esmsh]:

```js
import {factorySpace} from 'https://esm.sh/micromark-factory-space@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {factorySpace} from 'https://esm.sh/micromark-factory-space@1?bundle'
</script>
```

## Use

```js
import {factorySpace} from 'micromark-factory-space'
import {codes, types} from 'micromark-util-symbol'

// A micromark tokenizer that uses the factory:
/**
 * @this {TokenizeContext}
 *   Context.
 * @type {Tokenizer}
 */
function tokenizeCodeFenced(effects, ok, nok) {
  return start

  // …

  /** @type {State} */
  function info(code) {
    if (code === codes.eof || markdownLineEndingOrSpace(code)) {
      effects.exit(types.chunkString)
      effects.exit(types.codeFencedFenceInfo)
      return factorySpace(effects, infoAfter, types.whitespace)(code)
    }

    if (code === codes.graveAccent && code === marker) return nok(code)
    effects.consume(code)
    return info
  }

  // …
}
```

## API

This module exports the identifier [`factorySpace`][api-factory-space].
There is no default export.

### `factorySpace(…)`

Parse spaces and tabs.

There is no `nok` parameter:

* spaces in markdown are often optional, in which case this factory can be
  used and `ok` will be switched to whether spaces were found or not
* one line ending or space can be detected with `markdownSpace(code)` right
  before using `factorySpace`

###### Examples

Where `␉` represents a tab (plus how much it expands) and `␠` represents a
single space.

```markdown
␉
␠␠␠␠
␉␠
```

###### Parameters

* `effects` (`Effects`)
  — context
* `ok` (`State`)
  — state switched to when successful
* `type` (`string`)
  — type (`' \t'`)
* `max` (`number`, default: `Infinity`)
  — max (exclusive)

###### Returns

Start state (`State`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-factory-space@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-factory-space.svg

[downloads]: https://www.npmjs.com/package/micromark-factory-space

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-factory-space

[bundle-size]: https://bundlejs.com/?q=micromark-factory-space

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[markdown-space]: https://github.com/micromark/micromark/tree/main/packages/micromark-util-character#markdownspacecode

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[api-factory-space]: #factoryspace


---

# micromark-util-character

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility to handle [character codes][code].

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`asciiAlpha(code)`](#asciialphacode)
  * [`asciiAlphanumeric(code)`](#asciialphanumericcode)
  * [`asciiAtext(code)`](#asciiatextcode)
  * [`asciiControl(code)`](#asciicontrolcode)
  * [`asciiDigit(code)`](#asciidigitcode)
  * [`asciiHexDigit(code)`](#asciihexdigitcode)
  * [`asciiPunctuation(code)`](#asciipunctuationcode)
  * [`markdownLineEnding(code)`](#markdownlineendingcode)
  * [`markdownLineEndingOrSpace(code)`](#markdownlineendingorspacecode)
  * [`markdownSpace(code)`](#markdownspacecode)
  * [`unicodePunctuation(code)`](#unicodepunctuationcode)
  * [`unicodeWhitespace(code)`](#unicodewhitespacecode)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes algorithms to check whether characters match groups.

## When should I use this?

This package might be useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-character
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as character from 'https://esm.sh/micromark-util-character@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as character from 'https://esm.sh/micromark-util-character@1?bundle'
</script>
```

## Use

```js
import {asciiAlpha} from 'micromark-util-character'

console.log(asciiAlpha(64)) // false
console.log(asciiAlpha(65)) // true
```

## API

This module exports the identifiers
[`asciiAlpha`][api-ascii-alpha],
[`asciiAlphanumeric`][api-ascii-alphanumeric],
[`asciiAtext`][api-ascii-atext],
[`asciiControl`][api-ascii-control],
[`asciiDigit`][api-ascii-digit],
[`asciiHexDigit`][api-ascii-hex-digit],
[`asciiPunctuation`][api-ascii-punctuation],
[`markdownLineEnding`][api-markdown-line-ending],
[`markdownLineEndingOrSpace`][api-markdown-line-ending-or-space],
[`markdownSpace`][api-markdown-space],
[`unicodePunctuation`][api-unicode-punctuation],
[`unicodeWhitespace`][api-unicode-whitespace].
There is no default export.

### `asciiAlpha(code)`

Check whether the [character code][code] represents an ASCII alpha (`a` through
`z`, case insensitive).

An **ASCII alpha** is an ASCII upper alpha or ASCII lower alpha.

An **ASCII upper alpha** is a character in the inclusive range U+0041 (`A`)
to U+005A (`Z`).

An **ASCII lower alpha** is a character in the inclusive range U+0061 (`a`)
to U+007A (`z`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiAlphanumeric(code)`

Check whether the [character code][code] represents an ASCII alphanumeric (`a`
through `z`, case insensitive, or `0` through `9`).

An **ASCII alphanumeric** is an ASCII digit (see `asciiDigit`) or ASCII alpha
(see `asciiAlpha`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiAtext(code)`

Check whether the [character code][code] represents an ASCII atext.

atext is an ASCII alphanumeric (see `asciiAlphanumeric`), or a character in
the inclusive ranges U+0023 NUMBER SIGN (`#`) to U+0027 APOSTROPHE (`'`),
U+002A ASTERISK (`*`), U+002B PLUS SIGN (`+`), U+002D DASH (`-`), U+002F
SLASH (`/`), U+003D EQUALS TO (`=`), U+003F QUESTION MARK (`?`), U+005E
CARET (`^`) to U+0060 GRAVE ACCENT (`` ` ``), or U+007B LEFT CURLY BRACE
(`{`) to U+007E TILDE (`~`) (**\[RFC5322]**).

See **\[RFC5322]**:\
[Internet Message Format](https://tools.ietf.org/html/rfc5322).\
P. Resnick.\
IETF.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiControl(code)`

Check whether a [character code][code] is an ASCII control character.

An **ASCII control** is a character in the inclusive range U+0000 NULL (NUL)
to U+001F (US), or U+007F (DEL).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiDigit(code)`

Check whether the [character code][code] represents an ASCII digit (`0` through
`9`).

An **ASCII digit** is a character in the inclusive range U+0030 (`0`) to
U+0039 (`9`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiHexDigit(code)`

Check whether the [character code][code] represents an ASCII hex digit (`a`
through `f`, case insensitive, or `0` through `9`).

An **ASCII hex digit** is an ASCII digit (see `asciiDigit`), ASCII upper hex
digit, or an ASCII lower hex digit.

An **ASCII upper hex digit** is a character in the inclusive range U+0041
(`A`) to U+0046 (`F`).

An **ASCII lower hex digit** is a character in the inclusive range U+0061
(`a`) to U+0066 (`f`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiPunctuation(code)`

Check whether the [character code][code] represents ASCII punctuation.

An **ASCII punctuation** is a character in the inclusive ranges U+0021
EXCLAMATION MARK (`!`) to U+002F SLASH (`/`), U+003A COLON (`:`) to U+0040 AT
SIGN (`@`), U+005B LEFT SQUARE BRACKET (`[`) to U+0060 GRAVE ACCENT
(`` ` ``), or U+007B LEFT CURLY BRACE (`{`) to U+007E TILDE (`~`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownLineEnding(code)`

Check whether a [character code][code] is a markdown line ending.

A **markdown line ending** is the virtual characters M-0003 CARRIAGE RETURN
LINE FEED (CRLF), M-0004 LINE FEED (LF) and M-0005 CARRIAGE RETURN (CR).

In micromark, the actual character U+000A LINE FEED (LF) and U+000D CARRIAGE
RETURN (CR) are replaced by these virtual characters depending on whether
they occurred together.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownLineEndingOrSpace(code)`

Check whether a [character code][code] is a markdown line ending (see
`markdownLineEnding`) or markdown space (see `markdownSpace`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownSpace(code)`

Check whether a [character code][code] is a markdown space.

A **markdown space** is the concrete character U+0020 SPACE (SP) and the
virtual characters M-0001 VIRTUAL SPACE (VS) and M-0002 HORIZONTAL TAB (HT).

In micromark, the actual character U+0009 CHARACTER TABULATION (HT) is
replaced by one M-0002 HORIZONTAL TAB (HT) and between 0 and 3 M-0001 VIRTUAL
SPACE (VS) characters, depending on the column at which the tab occurred.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `unicodePunctuation(code)`

Check whether the [character code][code] represents Unicode punctuation.

A **Unicode punctuation** is a character in the Unicode `Pc` (Punctuation,
Connector), `Pd` (Punctuation, Dash), `Pe` (Punctuation, Close), `Pf`
(Punctuation, Final quote), `Pi` (Punctuation, Initial quote), `Po`
(Punctuation, Other), or `Ps` (Punctuation, Open) categories, or an ASCII
punctuation (see `asciiPunctuation`) (**\[UNICODE]**).

See **\[UNICODE]**:\
[The Unicode Standard](https://www.unicode.org/versions/).\
Unicode Consortium.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `unicodeWhitespace(code)`

Check whether the [character code][code] represents Unicode whitespace.

Note that this does handle micromark specific markdown whitespace characters.
See `markdownLineEndingOrSpace` to check that.

A **Unicode whitespace** is a character in the Unicode `Zs` (Separator,
Space) category, or U+0009 CHARACTER TABULATION (HT), U+000A LINE FEED (LF),
U+000C (FF), or U+000D CARRIAGE RETURN (CR) (**\[UNICODE]**).

See **\[UNICODE]**:\
[The Unicode Standard](https://www.unicode.org/versions/).\
Unicode Consortium.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-character@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-character.svg

[downloads]: https://www.npmjs.com/package/micromark-util-character

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-character

[bundle-size]: https://bundlejs.com/?q=micromark-util-character

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[code]: https://github.com/micromark/micromark#preprocess

[api-ascii-alpha]: #asciialphacode

[api-ascii-alphanumeric]: #asciialphanumericcode

[api-ascii-atext]: #asciiatextcode

[api-ascii-control]: #asciicontrolcode

[api-ascii-digit]: #asciidigitcode

[api-ascii-hex-digit]: #asciihexdigitcode

[api-ascii-punctuation]: #asciipunctuationcode

[api-markdown-line-ending]: #markdownlineendingcode

[api-markdown-line-ending-or-space]: #markdownlineendingorspacecode

[api-markdown-space]: #markdownspacecode

[api-unicode-punctuation]: #unicodepunctuationcode

[api-unicode-whitespace]: #unicodewhitespacecode


---

# micromark-util-symbol

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility with symbols.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes constants used throughout the micromark ecosystem.

## When should I use this?

This package is useful when you are making your own micromark extensions.
It’s useful to reference these constants by name instead of value while
developing.
[`micromark-build`][micromark-build] compiles them away for production code.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-symbol
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as symbol from 'https://esm.sh/micromark-util-symbol@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as symbol from 'https://esm.sh/micromark-util-symbol@1?bundle'
</script>
```

## Use

```js
import {codes, constants, types, values} from 'micromark-util-symbol'

console.log(codes.atSign) // 64
console.log(constants.characterReferenceNamedSizeMax) // 31
console.log(types.definitionDestinationRaw) // 'definitionDestinationRaw'
console.log(values.atSign) // '@'
```

## API

This package exports the identifiers `codes`, `constants`, `types`, and
`values`.
There is no default export.

Each identifier is an object mapping strings to values.
See the code for the exposed data.

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-symbol@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-symbol.svg

[downloads]: https://www.npmjs.com/package/micromark-util-symbol

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-symbol

[bundle-size]: https://bundlejs.com/?q=micromark-util-symbol

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[micromark-build]: https://github.com/micromark/micromark/tree/main/packages/micromark-build


---

# micromark-core-commonmark

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] constructs that make up the core of CommonMark.
Some of these can be [turned off][disable], but they are often essential to
markdown and weird things might happen.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes the default constructs.

## When should I use this?

This package is useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-core-commonmark
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as core from 'https://esm.sh/micromark-core-commonmark@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as core from 'https://esm.sh/micromark-core-commonmark@1?bundle'
</script>
```

## Use

```js
import {autolink} from 'micromark-core-commonmark'

console.log(autolink) // Do things with `autolink`.
```

## API

This module exports the following identifiers: `attention`, `autolink`,
`blankLine`, `blockQuote`, `characterEscape`, `characterReference`,
`codeFenced`, `codeIndented`, `codeText`, `content`, `definition`,
`hardBreakEscape`, `headingAtx`, `htmlFlow`, `htmlText`, `labelEnd`,
`labelStartImage`, `labelStartLink`, `lineEnding`, `list`, `setextUnderline`,
`thematicBreak`.
There is no default export.

Each identifier refers to a [construct][].

See the code for more on the exported constructs.

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-core-commonmark@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[author]: https://wooorm.com

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[build]: https://github.com/micromark/micromark/actions

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[bundle-size]: https://bundlejs.com/?q=micromark-core-commonmark

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-core-commonmark

[chat]: https://github.com/micromark/micromark/discussions

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[construct]: https://github.com/micromark/micromark#constructs

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[coverage]: https://codecov.io/github/micromark/micromark

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[disable]: https://github.com/micromark/micromark#case-turn-off-constructs

[downloads]: https://www.npmjs.com/package/micromark-core-commonmark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-core-commonmark.svg

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[health]: https://github.com/micromark/.github

[license]: https://github.com/micromark/micromark/blob/main/license

[micromark]: https://github.com/micromark/micromark

[npm]: https://docs.npmjs.com/cli/install

[opencollective]: https://opencollective.com/unified

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[support]: https://github.com/micromark/.github/blob/main/support.md

[typescript]: https://www.typescriptlang.org


---

# micromark-factory-space

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] factory to parse [markdown space][markdown-space] (found in lots
of places).

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`factorySpace(…)`](#factoryspace)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes states to parse spaces and/or tabs.

## When should I use this?

This package is useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-factory-space
```

In Deno with [`esm.sh`][esmsh]:

```js
import {factorySpace} from 'https://esm.sh/micromark-factory-space@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {factorySpace} from 'https://esm.sh/micromark-factory-space@1?bundle'
</script>
```

## Use

```js
import {factorySpace} from 'micromark-factory-space'
import {codes, types} from 'micromark-util-symbol'

// A micromark tokenizer that uses the factory:
/**
 * @this {TokenizeContext}
 *   Context.
 * @type {Tokenizer}
 */
function tokenizeCodeFenced(effects, ok, nok) {
  return start

  // …

  /** @type {State} */
  function info(code) {
    if (code === codes.eof || markdownLineEndingOrSpace(code)) {
      effects.exit(types.chunkString)
      effects.exit(types.codeFencedFenceInfo)
      return factorySpace(effects, infoAfter, types.whitespace)(code)
    }

    if (code === codes.graveAccent && code === marker) return nok(code)
    effects.consume(code)
    return info
  }

  // …
}
```

## API

This module exports the identifier [`factorySpace`][api-factory-space].
There is no default export.

### `factorySpace(…)`

Parse spaces and tabs.

There is no `nok` parameter:

* spaces in markdown are often optional, in which case this factory can be
  used and `ok` will be switched to whether spaces were found or not
* one line ending or space can be detected with `markdownSpace(code)` right
  before using `factorySpace`

###### Examples

Where `␉` represents a tab (plus how much it expands) and `␠` represents a
single space.

```markdown
␉
␠␠␠␠
␉␠
```

###### Parameters

* `effects` (`Effects`)
  — context
* `ok` (`State`)
  — state switched to when successful
* `type` (`string`)
  — type (`' \t'`)
* `max` (`number`, default: `Infinity`)
  — max (exclusive)

###### Returns

Start state (`State`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-factory-space@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-factory-space.svg

[downloads]: https://www.npmjs.com/package/micromark-factory-space

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-factory-space

[bundle-size]: https://bundlejs.com/?q=micromark-factory-space

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[markdown-space]: https://github.com/micromark/micromark/tree/main/packages/micromark-util-character#markdownspacecode

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[api-factory-space]: #factoryspace


---

# micromark-util-character

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility to handle [character codes][code].

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`asciiAlpha(code)`](#asciialphacode)
  * [`asciiAlphanumeric(code)`](#asciialphanumericcode)
  * [`asciiAtext(code)`](#asciiatextcode)
  * [`asciiControl(code)`](#asciicontrolcode)
  * [`asciiDigit(code)`](#asciidigitcode)
  * [`asciiHexDigit(code)`](#asciihexdigitcode)
  * [`asciiPunctuation(code)`](#asciipunctuationcode)
  * [`markdownLineEnding(code)`](#markdownlineendingcode)
  * [`markdownLineEndingOrSpace(code)`](#markdownlineendingorspacecode)
  * [`markdownSpace(code)`](#markdownspacecode)
  * [`unicodePunctuation(code)`](#unicodepunctuationcode)
  * [`unicodeWhitespace(code)`](#unicodewhitespacecode)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes algorithms to check whether characters match groups.

## When should I use this?

This package might be useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-character
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as character from 'https://esm.sh/micromark-util-character@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as character from 'https://esm.sh/micromark-util-character@1?bundle'
</script>
```

## Use

```js
import {asciiAlpha} from 'micromark-util-character'

console.log(asciiAlpha(64)) // false
console.log(asciiAlpha(65)) // true
```

## API

This module exports the identifiers
[`asciiAlpha`][api-ascii-alpha],
[`asciiAlphanumeric`][api-ascii-alphanumeric],
[`asciiAtext`][api-ascii-atext],
[`asciiControl`][api-ascii-control],
[`asciiDigit`][api-ascii-digit],
[`asciiHexDigit`][api-ascii-hex-digit],
[`asciiPunctuation`][api-ascii-punctuation],
[`markdownLineEnding`][api-markdown-line-ending],
[`markdownLineEndingOrSpace`][api-markdown-line-ending-or-space],
[`markdownSpace`][api-markdown-space],
[`unicodePunctuation`][api-unicode-punctuation],
[`unicodeWhitespace`][api-unicode-whitespace].
There is no default export.

### `asciiAlpha(code)`

Check whether the [character code][code] represents an ASCII alpha (`a` through
`z`, case insensitive).

An **ASCII alpha** is an ASCII upper alpha or ASCII lower alpha.

An **ASCII upper alpha** is a character in the inclusive range U+0041 (`A`)
to U+005A (`Z`).

An **ASCII lower alpha** is a character in the inclusive range U+0061 (`a`)
to U+007A (`z`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiAlphanumeric(code)`

Check whether the [character code][code] represents an ASCII alphanumeric (`a`
through `z`, case insensitive, or `0` through `9`).

An **ASCII alphanumeric** is an ASCII digit (see `asciiDigit`) or ASCII alpha
(see `asciiAlpha`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiAtext(code)`

Check whether the [character code][code] represents an ASCII atext.

atext is an ASCII alphanumeric (see `asciiAlphanumeric`), or a character in
the inclusive ranges U+0023 NUMBER SIGN (`#`) to U+0027 APOSTROPHE (`'`),
U+002A ASTERISK (`*`), U+002B PLUS SIGN (`+`), U+002D DASH (`-`), U+002F
SLASH (`/`), U+003D EQUALS TO (`=`), U+003F QUESTION MARK (`?`), U+005E
CARET (`^`) to U+0060 GRAVE ACCENT (`` ` ``), or U+007B LEFT CURLY BRACE
(`{`) to U+007E TILDE (`~`) (**\[RFC5322]**).

See **\[RFC5322]**:\
[Internet Message Format](https://tools.ietf.org/html/rfc5322).\
P. Resnick.\
IETF.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiControl(code)`

Check whether a [character code][code] is an ASCII control character.

An **ASCII control** is a character in the inclusive range U+0000 NULL (NUL)
to U+001F (US), or U+007F (DEL).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiDigit(code)`

Check whether the [character code][code] represents an ASCII digit (`0` through
`9`).

An **ASCII digit** is a character in the inclusive range U+0030 (`0`) to
U+0039 (`9`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiHexDigit(code)`

Check whether the [character code][code] represents an ASCII hex digit (`a`
through `f`, case insensitive, or `0` through `9`).

An **ASCII hex digit** is an ASCII digit (see `asciiDigit`), ASCII upper hex
digit, or an ASCII lower hex digit.

An **ASCII upper hex digit** is a character in the inclusive range U+0041
(`A`) to U+0046 (`F`).

An **ASCII lower hex digit** is a character in the inclusive range U+0061
(`a`) to U+0066 (`f`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiPunctuation(code)`

Check whether the [character code][code] represents ASCII punctuation.

An **ASCII punctuation** is a character in the inclusive ranges U+0021
EXCLAMATION MARK (`!`) to U+002F SLASH (`/`), U+003A COLON (`:`) to U+0040 AT
SIGN (`@`), U+005B LEFT SQUARE BRACKET (`[`) to U+0060 GRAVE ACCENT
(`` ` ``), or U+007B LEFT CURLY BRACE (`{`) to U+007E TILDE (`~`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownLineEnding(code)`

Check whether a [character code][code] is a markdown line ending.

A **markdown line ending** is the virtual characters M-0003 CARRIAGE RETURN
LINE FEED (CRLF), M-0004 LINE FEED (LF) and M-0005 CARRIAGE RETURN (CR).

In micromark, the actual character U+000A LINE FEED (LF) and U+000D CARRIAGE
RETURN (CR) are replaced by these virtual characters depending on whether
they occurred together.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownLineEndingOrSpace(code)`

Check whether a [character code][code] is a markdown line ending (see
`markdownLineEnding`) or markdown space (see `markdownSpace`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownSpace(code)`

Check whether a [character code][code] is a markdown space.

A **markdown space** is the concrete character U+0020 SPACE (SP) and the
virtual characters M-0001 VIRTUAL SPACE (VS) and M-0002 HORIZONTAL TAB (HT).

In micromark, the actual character U+0009 CHARACTER TABULATION (HT) is
replaced by one M-0002 HORIZONTAL TAB (HT) and between 0 and 3 M-0001 VIRTUAL
SPACE (VS) characters, depending on the column at which the tab occurred.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `unicodePunctuation(code)`

Check whether the [character code][code] represents Unicode punctuation.

A **Unicode punctuation** is a character in the Unicode `Pc` (Punctuation,
Connector), `Pd` (Punctuation, Dash), `Pe` (Punctuation, Close), `Pf`
(Punctuation, Final quote), `Pi` (Punctuation, Initial quote), `Po`
(Punctuation, Other), or `Ps` (Punctuation, Open) categories, or an ASCII
punctuation (see `asciiPunctuation`) (**\[UNICODE]**).

See **\[UNICODE]**:\
[The Unicode Standard](https://www.unicode.org/versions/).\
Unicode Consortium.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `unicodeWhitespace(code)`

Check whether the [character code][code] represents Unicode whitespace.

Note that this does handle micromark specific markdown whitespace characters.
See `markdownLineEndingOrSpace` to check that.

A **Unicode whitespace** is a character in the Unicode `Zs` (Separator,
Space) category, or U+0009 CHARACTER TABULATION (HT), U+000A LINE FEED (LF),
U+000C (FF), or U+000D CARRIAGE RETURN (CR) (**\[UNICODE]**).

See **\[UNICODE]**:\
[The Unicode Standard](https://www.unicode.org/versions/).\
Unicode Consortium.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-character@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-character.svg

[downloads]: https://www.npmjs.com/package/micromark-util-character

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-character

[bundle-size]: https://bundlejs.com/?q=micromark-util-character

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[code]: https://github.com/micromark/micromark#preprocess

[api-ascii-alpha]: #asciialphacode

[api-ascii-alphanumeric]: #asciialphanumericcode

[api-ascii-atext]: #asciiatextcode

[api-ascii-control]: #asciicontrolcode

[api-ascii-digit]: #asciidigitcode

[api-ascii-hex-digit]: #asciihexdigitcode

[api-ascii-punctuation]: #asciipunctuationcode

[api-markdown-line-ending]: #markdownlineendingcode

[api-markdown-line-ending-or-space]: #markdownlineendingorspacecode

[api-markdown-space]: #markdownspacecode

[api-unicode-punctuation]: #unicodepunctuationcode

[api-unicode-whitespace]: #unicodewhitespacecode


---

# micromark-util-symbol

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility with symbols.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes constants used throughout the micromark ecosystem.

## When should I use this?

This package is useful when you are making your own micromark extensions.
It’s useful to reference these constants by name instead of value while
developing.
[`micromark-build`][micromark-build] compiles them away for production code.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-symbol
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as symbol from 'https://esm.sh/micromark-util-symbol@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as symbol from 'https://esm.sh/micromark-util-symbol@1?bundle'
</script>
```

## Use

```js
import {codes, constants, types, values} from 'micromark-util-symbol'

console.log(codes.atSign) // 64
console.log(constants.characterReferenceNamedSizeMax) // 31
console.log(types.definitionDestinationRaw) // 'definitionDestinationRaw'
console.log(values.atSign) // '@'
```

## API

This package exports the identifiers `codes`, `constants`, `types`, and
`values`.
There is no default export.

Each identifier is an object mapping strings to values.
See the code for the exposed data.

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-symbol@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-symbol.svg

[downloads]: https://www.npmjs.com/package/micromark-util-symbol

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-symbol

[bundle-size]: https://bundlejs.com/?q=micromark-util-symbol

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[micromark-build]: https://github.com/micromark/micromark/tree/main/packages/micromark-build


---

# micromark-extension-directive

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[micromark][] extensions to support [directives][prop] (`:cite[smith04]` and
such).

## Contents

* [What is this?](#what-is-this)
* [When to use this](#when-to-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`directive()`](#directive)
  * [`directiveHtml(options?)`](#directivehtmloptions)
  * [`Directive`](#directive-1)
  * [`Handle`](#handle)
  * [`HtmlOptions`](#htmloptions)
* [Authoring](#authoring)
* [HTML](#html)
* [CSS](#css)
* [Syntax](#syntax)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Related](#related)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package contains two extensions that add support for directive syntax in
markdown to [`micromark`][micromark].

## When to use this

This project is useful when you want to solve the need for an infinite number
of potential extensions to markdown in a single markdown-esque way.

You can use these extensions when you are working with [`micromark`][micromark]
already.

When you need a syntax tree, you can combine this package with
[`mdast-util-directive`][mdast-util-directive].

All these packages are used [`remark-directive`][remark-directive], which
focusses on making it easier to transform content by abstracting these
internals away.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

[npm][]:

```sh
npm install micromark-extension-directive
```

In Deno with [`esm.sh`][esmsh]:

```js
import {directive, directiveHtml} from 'https://esm.sh/micromark-extension-directive@3'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {directive, directiveHtml} from 'https://esm.sh/micromark-extension-directive@3?bundle'
</script>
```

## Use

Say our document `example.md` contains:

```markdown
A lovely language know as :abbr[HTML]{title="HyperText Markup Language"}.
```

…and our module `example.js` looks as follows:

```js
/**
 * @import {Handle} from 'micromark-extension-directive'
 * @import {CompileContext} from 'micromark-util-types'
 */

import fs from 'node:fs/promises'
import {micromark} from 'micromark'
import {directive, directiveHtml} from 'micromark-extension-directive'

const output = micromark(await fs.readFile('example.md'), {
  extensions: [directive()],
  htmlExtensions: [directiveHtml({abbr})]
})

console.log(output)

/**
 * @this {CompileContext}
 * @type {Handle}
 * @returns {undefined}
 */
function abbr(d) {
  if (d.type !== 'textDirective') return false

  this.tag('<abbr')

  if (d.attributes && 'title' in d.attributes) {
    this.tag(' title="' + this.encode(d.attributes.title) + '"')
  }

  this.tag('>')
  this.raw(d.label || '')
  this.tag('</abbr>')
}
```

…now running `node example.js` yields:

```html
<p>A lovely language know as <abbr title="HyperText Markup Language">HTML</abbr>.</p>
```

## API

This package exports the identifiers [`directive`][api-directive] and
[`directiveHtml`][api-directive-html].
There is no default export.

The export map supports the [`development` condition][development].
Run `node --conditions development module.js` to get instrumented dev code.
Without this condition, production code is loaded.

### `directive()`

Create an extension for `micromark` to enable directive syntax.

###### Returns

Extension for `micromark` that can be passed in `extensions`, to enable
directive syntax ([`Extension`][micromark-extension]).

### `directiveHtml(options?)`

Create an extension for `micromark` to support directives when serializing to
HTML.

> 👉 **Note**: this uses KaTeX to render math.

###### Parameters

* `options` ([`HtmlOptions`][api-html-options], default: `{}`)
  — configuration

###### Returns

Extension for `micromark` that can be passed in `htmlExtensions`, to
support directives when serializing to HTML
([`HtmlExtension`][micromark-html-extension]).

### `Directive`

Structure representing a directive (TypeScript type).

###### Fields

* `type` (`'containerDirective'`, `'leafDirective'`, or `'textDirective'`)
  — kind
* `name` (`string`)
  — name of directive
* `label` (`string` or `undefined`)
  — compiled HTML content that was in `[brackets]`
* `attributes` (`Record<string, string>` or `undefined`)
  — object w/ HTML attributes
* `content` (`string` or `undefined`)
  — compiled HTML content inside container directive

### `Handle`

Handle a directive (TypeScript type).

###### Parameters

* `this` ([`CompileContext`][micromark-compile-context])
  — current context
* `directive` ([`Directive`][api-directive-type])
  — directive

###### Returns

Signal whether the directive was handled (`boolean`, default: `true`).
Yield `false` to let the fallback (a special handle for `'*'`) handle it.

### `HtmlOptions`

Configuration (TypeScript type).

> 👉 **Note**: the special field `'*'` can be used to specify a fallback handle
> to handle all otherwise unhandled directives.

###### Type

```ts
type HtmlOptions = Record<string, Handle>
```

## Authoring

When authoring markdown with directives, keep in mind that they don’t work in
most places.
On your own site it can be great!

## HTML

You can define how directives are turned into HTML.
If directives are not handled, they do not emit anything.

## CSS

How to display directives is left as an exercise for the reader.

## Syntax

The syntax looks like this:

```markdown
Directives in text can form with a single colon, such as :cite[smith04].
Their syntax is `:name[label]{attributes}`.

Leafs (block without content) can form by using two colons:

::youtube[Video of a cat in a box]{vid=01ab2cd3efg}

Their syntax is `::name[label]{attributes}` on its own line.

Containers (blocks with content) can form by using three colons:

:::spoiler
He dies.
:::

The `name` part is required.  The first character must be a letter, other
characters can be alphanumerical, `-`, and `_`.
`-` or `_` cannot end a name.

The `[label]` part is optional (`:x` and `:x[]` are equivalent)†.
When used, it can include text constructs such as emphasis and so on: `x[a *b*
c]`.

The `{attributes}` part is optional (`:x` and `:x{}` are equivalent)†.
When used, it is handled like HTML attributes, such as that `{a}`, `{a=""}`,
, `{a=''}` but also `{a=b}`, `{a="b"}`, and `{a='b'}` are equivalent.
Shortcuts are available for `id=` (`{#readme}` for `{id=readme}`) and
`class` (`{.big}` for `{class=big}`).
When multiple ids are found, the last is used; when multiple classes are found,
they are combined: `{.red class=green .blue}` is equivalent to
`{.red .green .blue}` and `{class="red green blue"}`.

† there is one case where a name must be followed by an empty label or empty
attributes: a *text* directive that only has a name, cannot be followed by a
colon. So, `:red:` doesn’t work. Use either `:red[]` or `:red{}` instead.
The reason for this is to allow GitHub emoji (gemoji) and directives to coexist.

Containers can be nested by using more colons outside:

::::spoiler
He dies.

:::spoiler
She is born.
:::
::::

The closing fence must include the same or more colons as the opening.
If no closing is found, the container runs to the end of its parent container
(block quote, list item, document, or other container).

::::spoiler
These three are not enough to close
:::
So this line is also part of the container.
```

Note that while other implementations are sometimes loose in what they allow,
this implementation mimics CommonMark as closely as possible:

* Whitespace is not allowed between colons and name (~~`: a`~~), name and
  label (~~`:a []`~~), name and attributes (~~`:a {}`~~), or label and
  attributes (~~`:a[] {}`~~) — because it’s not allowed in links either
  (~~`[] ()`~~)
* No trailing colons allowed on the opening fence of a container
  (~~`:::a:::`~~) — because it’s not allowed in fenced code either
* The label and attributes in a leaf or container cannot include line endings
  (~~`::a[b\nc]`~~) — because it’s not allowed in fenced code either

## Types

This package is fully typed with [TypeScript][].
It exports the additional types [`Directive`][api-directive-type],
[`Handle`][api-handle], and [`HtmlOptions`][api-html-options].

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-extension-directive@^3`, compatible with Node.js 16.

This package works with `micromark` version `3` and later.

## Security

This package is safe assuming that you write safe handlers.
Any vulnerability in your code could open you to a
[cross-site scripting (XSS)][xss] attack.

## Related

* [`remark-directive`][remark-directive]
  — remark plugin to support directives
* [`mdast-util-directive`][mdast-util-directive]
  — mdast utility to support directives

## Contribute

See [`contributing.md` in `micromark/.github`][contributing] for ways to get
started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark-extension-directive/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark-extension-directive/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark-extension-directive.svg

[coverage]: https://codecov.io/github/micromark/micromark-extension-directive

[downloads-badge]: https://img.shields.io/npm/dm/micromark-extension-directive.svg

[downloads]: https://www.npmjs.com/package/micromark-extension-directive

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-extension-directive

[size]: https://bundlejs.com/?q=micromark-extension-directive

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[npm]: https://docs.npmjs.com/cli/install

[esmsh]: https://esm.sh

[license]: license

[author]: https://wooorm.com

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[typescript]: https://www.typescriptlang.org

[development]: https://nodejs.org/api/packages.html#packages_resolving_user_conditions

[micromark]: https://github.com/micromark/micromark

[micromark-html-extension]: https://github.com/micromark/micromark#htmlextension

[micromark-extension]: https://github.com/micromark/micromark#syntaxextension

[micromark-compile-context]: https://github.com/micromark/micromark/blob/41e3c4c/packages/micromark-util-types/index.js#L457

[mdast-util-directive]: https://github.com/syntax-tree/mdast-util-directive

[remark-directive]: https://github.com/remarkjs/remark-directive

[prop]: https://talk.commonmark.org/t/generic-directives-plugins-syntax/444

[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting

[api-directive]: #directive

[api-directive-html]: #directivehtmloptions

[api-directive-type]: #directive-1

[api-handle]: #handle

[api-html-options]: #htmloptions


---

# micromark-util-character

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility to handle [character codes][code].

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`asciiAlpha(code)`](#asciialphacode)
  * [`asciiAlphanumeric(code)`](#asciialphanumericcode)
  * [`asciiAtext(code)`](#asciiatextcode)
  * [`asciiControl(code)`](#asciicontrolcode)
  * [`asciiDigit(code)`](#asciidigitcode)
  * [`asciiHexDigit(code)`](#asciihexdigitcode)
  * [`asciiPunctuation(code)`](#asciipunctuationcode)
  * [`markdownLineEnding(code)`](#markdownlineendingcode)
  * [`markdownLineEndingOrSpace(code)`](#markdownlineendingorspacecode)
  * [`markdownSpace(code)`](#markdownspacecode)
  * [`unicodePunctuation(code)`](#unicodepunctuationcode)
  * [`unicodeWhitespace(code)`](#unicodewhitespacecode)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes algorithms to check whether characters match groups.

## When should I use this?

This package might be useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-character
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as character from 'https://esm.sh/micromark-util-character@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as character from 'https://esm.sh/micromark-util-character@1?bundle'
</script>
```

## Use

```js
import {asciiAlpha} from 'micromark-util-character'

console.log(asciiAlpha(64)) // false
console.log(asciiAlpha(65)) // true
```

## API

This module exports the identifiers
[`asciiAlpha`][api-ascii-alpha],
[`asciiAlphanumeric`][api-ascii-alphanumeric],
[`asciiAtext`][api-ascii-atext],
[`asciiControl`][api-ascii-control],
[`asciiDigit`][api-ascii-digit],
[`asciiHexDigit`][api-ascii-hex-digit],
[`asciiPunctuation`][api-ascii-punctuation],
[`markdownLineEnding`][api-markdown-line-ending],
[`markdownLineEndingOrSpace`][api-markdown-line-ending-or-space],
[`markdownSpace`][api-markdown-space],
[`unicodePunctuation`][api-unicode-punctuation],
[`unicodeWhitespace`][api-unicode-whitespace].
There is no default export.

### `asciiAlpha(code)`

Check whether the [character code][code] represents an ASCII alpha (`a` through
`z`, case insensitive).

An **ASCII alpha** is an ASCII upper alpha or ASCII lower alpha.

An **ASCII upper alpha** is a character in the inclusive range U+0041 (`A`)
to U+005A (`Z`).

An **ASCII lower alpha** is a character in the inclusive range U+0061 (`a`)
to U+007A (`z`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiAlphanumeric(code)`

Check whether the [character code][code] represents an ASCII alphanumeric (`a`
through `z`, case insensitive, or `0` through `9`).

An **ASCII alphanumeric** is an ASCII digit (see `asciiDigit`) or ASCII alpha
(see `asciiAlpha`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiAtext(code)`

Check whether the [character code][code] represents an ASCII atext.

atext is an ASCII alphanumeric (see `asciiAlphanumeric`), or a character in
the inclusive ranges U+0023 NUMBER SIGN (`#`) to U+0027 APOSTROPHE (`'`),
U+002A ASTERISK (`*`), U+002B PLUS SIGN (`+`), U+002D DASH (`-`), U+002F
SLASH (`/`), U+003D EQUALS TO (`=`), U+003F QUESTION MARK (`?`), U+005E
CARET (`^`) to U+0060 GRAVE ACCENT (`` ` ``), or U+007B LEFT CURLY BRACE
(`{`) to U+007E TILDE (`~`) (**\[RFC5322]**).

See **\[RFC5322]**:\
[Internet Message Format](https://tools.ietf.org/html/rfc5322).\
P. Resnick.\
IETF.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiControl(code)`

Check whether a [character code][code] is an ASCII control character.

An **ASCII control** is a character in the inclusive range U+0000 NULL (NUL)
to U+001F (US), or U+007F (DEL).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiDigit(code)`

Check whether the [character code][code] represents an ASCII digit (`0` through
`9`).

An **ASCII digit** is a character in the inclusive range U+0030 (`0`) to
U+0039 (`9`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiHexDigit(code)`

Check whether the [character code][code] represents an ASCII hex digit (`a`
through `f`, case insensitive, or `0` through `9`).

An **ASCII hex digit** is an ASCII digit (see `asciiDigit`), ASCII upper hex
digit, or an ASCII lower hex digit.

An **ASCII upper hex digit** is a character in the inclusive range U+0041
(`A`) to U+0046 (`F`).

An **ASCII lower hex digit** is a character in the inclusive range U+0061
(`a`) to U+0066 (`f`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiPunctuation(code)`

Check whether the [character code][code] represents ASCII punctuation.

An **ASCII punctuation** is a character in the inclusive ranges U+0021
EXCLAMATION MARK (`!`) to U+002F SLASH (`/`), U+003A COLON (`:`) to U+0040 AT
SIGN (`@`), U+005B LEFT SQUARE BRACKET (`[`) to U+0060 GRAVE ACCENT
(`` ` ``), or U+007B LEFT CURLY BRACE (`{`) to U+007E TILDE (`~`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownLineEnding(code)`

Check whether a [character code][code] is a markdown line ending.

A **markdown line ending** is the virtual characters M-0003 CARRIAGE RETURN
LINE FEED (CRLF), M-0004 LINE FEED (LF) and M-0005 CARRIAGE RETURN (CR).

In micromark, the actual character U+000A LINE FEED (LF) and U+000D CARRIAGE
RETURN (CR) are replaced by these virtual characters depending on whether
they occurred together.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownLineEndingOrSpace(code)`

Check whether a [character code][code] is a markdown line ending (see
`markdownLineEnding`) or markdown space (see `markdownSpace`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownSpace(code)`

Check whether a [character code][code] is a markdown space.

A **markdown space** is the concrete character U+0020 SPACE (SP) and the
virtual characters M-0001 VIRTUAL SPACE (VS) and M-0002 HORIZONTAL TAB (HT).

In micromark, the actual character U+0009 CHARACTER TABULATION (HT) is
replaced by one M-0002 HORIZONTAL TAB (HT) and between 0 and 3 M-0001 VIRTUAL
SPACE (VS) characters, depending on the column at which the tab occurred.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `unicodePunctuation(code)`

Check whether the [character code][code] represents Unicode punctuation.

A **Unicode punctuation** is a character in the Unicode `Pc` (Punctuation,
Connector), `Pd` (Punctuation, Dash), `Pe` (Punctuation, Close), `Pf`
(Punctuation, Final quote), `Pi` (Punctuation, Initial quote), `Po`
(Punctuation, Other), or `Ps` (Punctuation, Open) categories, or an ASCII
punctuation (see `asciiPunctuation`) (**\[UNICODE]**).

See **\[UNICODE]**:\
[The Unicode Standard](https://www.unicode.org/versions/).\
Unicode Consortium.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `unicodeWhitespace(code)`

Check whether the [character code][code] represents Unicode whitespace.

Note that this does handle micromark specific markdown whitespace characters.
See `markdownLineEndingOrSpace` to check that.

A **Unicode whitespace** is a character in the Unicode `Zs` (Separator,
Space) category, or U+0009 CHARACTER TABULATION (HT), U+000A LINE FEED (LF),
U+000C (FF), or U+000D CARRIAGE RETURN (CR) (**\[UNICODE]**).

See **\[UNICODE]**:\
[The Unicode Standard](https://www.unicode.org/versions/).\
Unicode Consortium.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-character@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-character.svg

[downloads]: https://www.npmjs.com/package/micromark-util-character

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-character

[bundle-size]: https://bundlejs.com/?q=micromark-util-character

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[code]: https://github.com/micromark/micromark#preprocess

[api-ascii-alpha]: #asciialphacode

[api-ascii-alphanumeric]: #asciialphanumericcode

[api-ascii-atext]: #asciiatextcode

[api-ascii-control]: #asciicontrolcode

[api-ascii-digit]: #asciidigitcode

[api-ascii-hex-digit]: #asciihexdigitcode

[api-ascii-punctuation]: #asciipunctuationcode

[api-markdown-line-ending]: #markdownlineendingcode

[api-markdown-line-ending-or-space]: #markdownlineendingorspacecode

[api-markdown-space]: #markdownspacecode

[api-unicode-punctuation]: #unicodepunctuationcode

[api-unicode-whitespace]: #unicodewhitespacecode


---

# micromark-util-symbol

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility with symbols.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes constants used throughout the micromark ecosystem.

## When should I use this?

This package is useful when you are making your own micromark extensions.
It’s useful to reference these constants by name instead of value while
developing.
[`micromark-build`][micromark-build] compiles them away for production code.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-symbol
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as symbol from 'https://esm.sh/micromark-util-symbol@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as symbol from 'https://esm.sh/micromark-util-symbol@1?bundle'
</script>
```

## Use

```js
import {codes, constants, types, values} from 'micromark-util-symbol'

console.log(codes.atSign) // 64
console.log(constants.characterReferenceNamedSizeMax) // 31
console.log(types.definitionDestinationRaw) // 'definitionDestinationRaw'
console.log(values.atSign) // '@'
```

## API

This package exports the identifiers `codes`, `constants`, `types`, and
`values`.
There is no default export.

Each identifier is an object mapping strings to values.
See the code for the exposed data.

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-symbol@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-symbol.svg

[downloads]: https://www.npmjs.com/package/micromark-util-symbol

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-symbol

[bundle-size]: https://bundlejs.com/?q=micromark-util-symbol

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[micromark-build]: https://github.com/micromark/micromark/tree/main/packages/micromark-build


---

# micromark-extension-frontmatter

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[micromark][] extensions to support frontmatter (YAML, TOML, and more).

## Contents

*   [What is this?](#what-is-this)
*   [When to use this](#when-to-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`frontmatter(options?)`](#frontmatteroptions)
    *   [`frontmatterHtml(options?)`](#frontmatterhtmloptions)
    *   [`toMatters(options?)`](#tomattersoptions)
    *   [`Info`](#info)
    *   [`Matter`](#matter)
    *   [`Options`](#options)
    *   [`Preset`](#preset)
*   [Examples](#examples)
*   [Authoring](#authoring)
*   [HTML](#html)
*   [CSS](#css)
*   [Syntax](#syntax)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Security](#security)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package contains two extensions that add support for frontmatter syntax
as often used in markdown to [`micromark`][micromark].

Frontmatter is a metadata format in front of the content.
It’s typically written in YAML and is often used with markdown.
Frontmatter does not work everywhere so it makes markdown less portable.

As there is no spec for frontmatter in markdown, these extensions follow how
YAML frontmatter works on `github.com`.
It can also parse TOML frontmatter, just like YAML except that it uses a `+`.

## When to use this

You can use these extensions when you are working with [`micromark`][micromark]
already.

When you need a syntax tree, you can combine this package with
[`mdast-util-frontmatter`][mdast-util-frontmatter].

All these packages are used [`remark-frontmatter`][remark-frontmatter], which
focusses on making it easier to transform content by abstracting these
internals away.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-extension-frontmatter
```

In Deno with [`esm.sh`][esmsh]:

```js
import {frontmatter, frontmatterHtml} from 'https://esm.sh/micromark-extension-frontmatter@2'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {frontmatter, frontmatterHtml} from 'https://esm.sh/micromark-extension-frontmatter@2?bundle'
</script>
```

## Use

Say our module `example.js` looks as follows:

```js
import {micromark} from 'micromark'
import {frontmatter, frontmatterHtml} from 'micromark-extension-frontmatter'

const output = micromark('---\na: b\n---\n# c', {
  extensions: [frontmatter()],
  htmlExtensions: [frontmatterHtml()]
})

console.log(output)
```

…now running `node example.js` yields:

```html
<h1>c</h1>
```

## API

This package exports the identifiers [`frontmatter`][api-frontmatter],
[`frontmatterHtml`][api-frontmatter-html], and [`toMatters`][api-to-matters].
There is no default export.

The export map supports the [`development` condition][development].
Run `node --conditions development module.js` to get instrumented dev code.
Without this condition, production code is loaded.

### `frontmatter(options?)`

Create an extension for [`micromark`][micromark] to enable frontmatter syntax.

###### Parameters

*   `options` ([`Options`][api-options], default: `['yaml']`)
    — configuration

###### Returns

Extension for `micromark` that can be passed in `extensions`, to enable
frontmatter syntax ([`Extension`][micromark-extension]).

### `frontmatterHtml(options?)`

Create an extension for `micromark` to support frontmatter when serializing to
HTML.

> 👉 **Note**: this makes sure nothing is generated in the output HTML for
> frontmatter.

###### Parameters

*   `options` ([`Options`][api-options], default: `['yaml']`)
    — configuration

###### Returns

Extension for `micromark` that can be passed in `htmlExtensions`, to support
frontmatter when serializing to HTML
([`HtmlExtension`][micromark-html-extension]).

### `toMatters(options?)`

Simplify options by normalizing them to an array of matters.

###### Parameters

*   `options` ([`Options`][api-options], default: `['yaml']`)
    — configuration

###### Returns

List of matters ([`Array<Matter>`][api-matter]).

### `Info`

Sequence (TypeScript type).

Depending on how this structure is used, it reflects a marker or a fence.

###### Fields

*   `open` (`string`)
    — opening
*   `close` (`string`)
    — closing

### `Matter`

Fields describing a kind of matter (TypeScript type).

> 👉 **Note**: using `anywhere` is a terrible idea.
> It’s called frontmatter, not matter-in-the-middle or so.
> This makes your markdown less portable.

> 👉 **Note**: `marker` and `fence` are mutually exclusive.
> If `marker` is set, `fence` must not be set, and vice versa.

###### Fields

*   `type` (`string`)
    — node type to tokenize as
*   `marker` (`string` or [`Info`][api-info])
    — character repeated 3 times, used as complete fences
*   `fence` (`string` or [`Info`][api-info])
    — complete fences
*   `anywhere` (`boolean`, default: `false`)
    — whether matter can be found anywhere in the document, normally only
    matter at the start of the document is recognized

### `Options`

Configuration (TypeScript type).

###### Type

```ts
type Options = Array<Matter | Preset> | Matter | Preset
```

### `Preset`

Known name of a frontmatter style (TypeScript type).

*   `'yaml'` — [`Matter`][api-matter] defined as `{type: 'yaml', marker: '-'}`
*   `'toml'` — [`Matter`][api-matter] defined as `{type: 'toml', marker: '+'}`

###### Type

```ts
type Preset = 'toml' | 'yaml'
```

## Examples

Here are a couple of example of different matter objects and what frontmatter
they match.

To match frontmatter with the same opening and closing fence, namely three of
the same markers, use for example `{type: 'yaml', marker: '-'}`, which matches:

```yaml
---
key: value
---
```

To match frontmatter with different opening and closing fences, which each use
three different markers, use for example
`{type: 'custom', marker: {open: '<', close: '>'}}`, which matches:

```text
<<<
data
>>>
```

To match frontmatter with the same opening and closing fences, which both use
the same custom string, use for example `{type: 'custom', fence: '+=+=+=+'}`,
which matches:

```text
+=+=+=+
data
+=+=+=+
```

To match frontmatter with different opening and closing fences, which each use
different custom strings, use for example
`{type: 'json', fence: {open: '{', close: '}'}}`, which matches:

```json
{
  "key": "value"
}
```

## Authoring

When authoring markdown with frontmatter, it’s recommended to use YAML
frontmatter if possible.
While YAML has some warts, it works in the most places, so using it guarantees
the highest chance of portability.

In certain ecosystems, other flavors are widely used.
For example, in the Rust ecosystem, TOML is often used.
In such cases, using TOML is an okay choice.

When possible, do not use other types of frontmatter, and do not allow
frontmatter anywhere.

## HTML

Frontmatter does not relate to HTML elements.
It is typically stripped, which is what these extensions do.

## CSS

This package does not relate to CSS.

## Syntax

Frontmatter forms with the following BNF:

```bnf
frontmatter ::= fence_open *( eol *line ) eol fence_close
fence_open ::= sequence_open *space_or_tab
fence_close ::= sequence_close *space_or_tab
; Note: options can define custom sequences.
sequence_open ::= 3'+' | 3'-'
; Note: options can define custom sequences.
; Restriction: `sequence_close` must correspond to `sequence_open`.
sequence_close ::= 3'+' | 3'-'

; Character groups for informational purposes.
byte ::= 0x00..=0xFFFF
eol ::= '\n' | '\r' | '\r\n'
line ::= byte - eol
```

Frontmatter can only occur once.
It cannot occur in a container.
It must have a closing fence.
Like flow constructs, it must be followed by an eol (line ending) or
eof (end of file).

## Types

This package is fully typed with [TypeScript][].
It exports the additional types [`Info`][api-info], [`Matter`][api-matter],
[`Options`][api-options], [`Preset`][api-preset].

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-extension-frontmatter@^2`, compatible with Node.js 16.

This package works with `micromark` version `3` and later.

## Security

This package is safe.

## Related

*   [`remark-frontmatter`][remark-frontmatter]
    — remark plugin using this to support frontmatter
*   [`mdast-util-frontmatter`][mdast-util-frontmatter]
    — mdast utility to support frontmatter

## Contribute

See [`contributing.md` in `micromark/.github`][contributing] for ways to get
started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark-extension-frontmatter/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark-extension-frontmatter/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark-extension-frontmatter.svg

[coverage]: https://codecov.io/github/micromark/micromark-extension-frontmatter

[downloads-badge]: https://img.shields.io/npm/dm/micromark-extension-frontmatter.svg

[downloads]: https://www.npmjs.com/package/micromark-extension-frontmatter

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-extension-frontmatter

[size]: https://bundlejs.com/?q=micromark-extension-frontmatter

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[npm]: https://docs.npmjs.com/cli/install

[esmsh]: https://esm.sh

[license]: license

[author]: https://wooorm.com

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[typescript]: https://www.typescriptlang.org

[development]: https://nodejs.org/api/packages.html#packages_resolving_user_conditions

[micromark]: https://github.com/micromark/micromark

[mdast-util-frontmatter]: https://github.com/syntax-tree/mdast-util-frontmatter

[remark-frontmatter]: https://github.com/remarkjs/remark-frontmatter

[micromark-extension]: https://github.com/micromark/micromark#syntaxextension

[micromark-html-extension]: https://github.com/micromark/micromark#htmlextension

[api-frontmatter]: #frontmatteroptions

[api-frontmatter-html]: #frontmatterhtmloptions

[api-to-matters]: #tomattersoptions

[api-info]: #info

[api-matter]: #matter

[api-options]: #options

[api-preset]: #preset


---

# micromark-extension-gfm

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[micromark][] extensions to support [GitHub flavored markdown][gfm] (GFM).

## Contents

*   [What is this?](#what-is-this)
*   [When to use this](#when-to-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`gfm(options?)`](#gfmoptions)
    *   [`gfmHtml(options?)`](#gfmhtmloptions)
    *   [`Options`](#options)
    *   [`HtmlOptions`](#htmloptions)
*   [Bugs](#bugs)
*   [Authoring](#authoring)
*   [HTML](#html)
*   [CSS](#css)
*   [Syntax](#syntax)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Security](#security)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package contains extensions that add support for all features enabled by
GFM to [`micromark`][micromark].
It supports autolink literals, footnotes, strikethrough, tables, tagfilter, and
tasklists.

## When to use this

This project is useful when you want to support GFM in markdown.

You can use these extensions when you are working with [`micromark`][micromark].
Alternatively, you can also use the underlying features separately:

*   [`micromark-extension-gfm-autolink-literal`][gfm-autolink-literal]
    — support GFM [autolink literals][]
*   [`micromark-extension-gfm-footnote`][gfm-footnote]
    — support GFM [footnotes][]
*   [`micromark-extension-gfm-strikethrough`][gfm-strikethrough]
    — support GFM [strikethrough][]
*   [`micromark-extension-gfm-table`][gfm-table]
    — support GFM [tables][]
*   [`micromark-extension-gfm-tagfilter`][gfm-tagfilter]
    — support GFM [tagfilter][]
*   [`micromark-extension-gfm-task-list-item`][gfm-task-list-item]
    — support GFM [tasklists][]

When you need a syntax tree, combine this package with
[`mdast-util-gfm`][mdast-util-gfm].

All these packages are used in [`remark-gfm`][remark-gfm], which focusses on
making it easier to transform content by abstracting these internals away.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-extension-gfm
```

In Deno with [`esm.sh`][esmsh]:

```js
import {gfm, gfmHtml} from 'https://esm.sh/micromark-extension-gfm@3'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {gfm, gfmHtml} from 'https://esm.sh/micromark-extension-gfm@3?bundle'
</script>
```

## Use

Say our document `example.md` contains:

```markdown
# GFM

## Autolink literals

www.example.com, https://example.com, and contact@example.com.

## Footnote

A note[^1]

[^1]: Big note.

## Strikethrough

~one~ or ~~two~~ tildes.

## Table

| a | b  |  c |  d  |
| - | :- | -: | :-: |

## Tag filter

<plaintext>

## Tasklist

* [ ] to do
* [x] done
```

…and our module `example.js` looks as follows:

```js
import fs from 'node:fs/promises'
import {micromark} from 'micromark'
import {gfm, gfmHtml} from 'micromark-extension-gfm'

const output = micromark(await fs.readFile('example.md'), {
  allowDangerousHtml: true,
  extensions: [gfm()],
  htmlExtensions: [gfmHtml()]
})

console.log(output)
```

…now running `node example.js` yields:

```html
<h1>GFM</h1>
<h2>Autolink literals</h2>
<p><a href="http://www.example.com">www.example.com</a>, <a href="https://example.com">https://example.com</a>, and <a href="mailto:contact@example.com">contact@example.com</a>.</p>
<h2>Footnote</h2>
<p>A note<sup><a href="#user-content-fn-1" id="user-content-fnref-1" data-footnote-ref="" aria-describedby="footnote-label">1</a></sup></p>
<h2>Strikethrough</h2>
<p><del>one</del> or <del>two</del> tildes.</p>
<h2>Table</h2>
<table>
<thead>
<tr>
<th>a</th>
<th align="left">b</th>
<th align="right">c</th>
<th align="center">d</th>
</tr>
</thead>
</table>
<h2>Tag filter</h2>
&lt;plaintext>
<h2>Tasklist</h2>
<ul>
<li><input type="checkbox" disabled="" /> to do</li>
<li><input type="checkbox" disabled="" checked="" /> done</li>
</ul>
<section data-footnotes="" class="footnotes"><h2 id="footnote-label" class="sr-only">Footnotes</h2>
<ol>
<li id="user-content-fn-1">
<p>Big note. <a href="#user-content-fnref-1" data-footnote-backref="" class="data-footnote-backref" aria-label="Back to content">↩</a></p>
</li>
</ol>
</section>
```

## API

This package exports the identifiers [`gfm`][api-gfm] and
[`gfmHtml`][api-gfm-html].
There is no default export.

The separate extensions support the [`development` condition][development].
Run `node --conditions development module.js` to get instrumented dev code.
Without this condition, production code is loaded.

### `gfm(options?)`

Create an extension for `micromark` to enable GFM syntax.

###### Parameters

*   `options` ([`Options`][api-options], optional)
    — configuration; passed to
    [`micromark-extens-gfm-strikethrough`][gfm-strikethrough-options]

###### Returns

Extension for `micromark` that can be passed in `extensions` to enable GFM
syntax ([`Extension`][micromark-extension]).

### `gfmHtml(options?)`

Create an extension for `micromark` to support GFM when serializing to HTML.

###### Parameters

*   `options` ([`HtmlOptions`][api-html-options], optional)
    — configuration; passed to
    [`micromark-extens-gfm-footnote`][gfm-footnote-html-options]

###### Returns

Extension for `micromark` that can be passed in `htmlExtensions` to support GFM
when serializing to HTML ([`HtmlExtension`][micromark-html-extension]).

### `Options`

Configuration for syntax (TypeScript type).

###### Type

```ts
export type {Options} from 'micromark-extension-gfm-strikethrough'
```

[See `Options`][gfm-strikethrough-options].

### `HtmlOptions`

Configuration for HTML (TypeScript type).

###### Type

```ts
export type {HtmlOptions} from 'micromark-extension-gfm-footnote'
```

[See `HtmlOptions`][gfm-footnote-html-options].

## Bugs

For bugs present in GFM but not here, or other peculiarities that are
supported, see each corresponding readme:

*   [autolink literal](https://github.com/micromark/micromark-extension-gfm-autolink-literal#bugs)
*   [footnote](https://github.com/micromark/micromark-extension-gfm-footnote#bugs)
*   strikethrough: n/a
*   [table](https://github.com/micromark/micromark-extension-gfm-table#bugs)
*   tagfilter: n/a
*   tasklists: n/a

## Authoring

For recommendations on how to author GFM, see each corresponding readme:

*   [autolink literal](https://github.com/micromark/micromark-extension-gfm-autolink-literal#authoring)
*   [footnote](https://github.com/micromark/micromark-extension-gfm-footnote#authoring)
*   [strikethrough](https://github.com/micromark/micromark-extension-gfm-strikethrough#authoring)
*   [table](https://github.com/micromark/micromark-extension-gfm-table#authoring)
*   tagfilter: n/a
*   [tasklists](https://github.com/micromark/micromark-extension-gfm-task-list-item#authoring)

## HTML

For info on what HTML features GFM relates to, see each corresponding readme:

*   [autolink literal](https://github.com/micromark/micromark-extension-gfm-autolink-literal#html)
*   [footnote](https://github.com/micromark/micromark-extension-gfm-footnote#html)
*   [strikethrough](https://github.com/micromark/micromark-extension-gfm-strikethrough#html)
*   [table](https://github.com/micromark/micromark-extension-gfm-table#html)
*   [tagfilter](https://github.com/micromark/micromark-extension-gfm-tagfilter#html)
*   [tasklists](https://github.com/micromark/micromark-extension-gfm-task-list-item#html)

## CSS

For info on how GitHub styles these features, see each corresponding readme:

*   [autolink literal](https://github.com/micromark/micromark-extension-gfm-autolink-literal#css)
*   [footnote](https://github.com/micromark/micromark-extension-gfm-footnote#css)
*   [strikethrough](https://github.com/micromark/micromark-extension-gfm-strikethrough#css)
*   [table](https://github.com/micromark/micromark-extension-gfm-table#css)
*   tagfilter: n/a
*   [tasklists](https://github.com/micromark/micromark-extension-gfm-task-list-item#css)

## Syntax

For info on the syntax of these features, see each corresponding readme:

*   [autolink literal](https://github.com/micromark/micromark-extension-gfm-autolink-literal#syntax)
*   [footnote](https://github.com/micromark/micromark-extension-gfm-footnote#syntax)
*   [strikethrough](https://github.com/micromark/micromark-extension-gfm-strikethrough#syntax)
*   [table](https://github.com/micromark/micromark-extension-gfm-table#syntax)
*   tagfilter: n/a
*   [tasklists](https://github.com/micromark/micromark-extension-gfm-task-list-item#syntax)

## Types

This package is fully typed with [TypeScript][].
It exports the additional types [`HtmlOptions`][api-html-options] and
[`Options`][api-options].

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-extension-gfm@^3`, compatible with Node.js 16.

This package works with `micromark` version `3` and later.

## Security

This package is safe.
Setting `clobberPrefix = ''` is dangerous, it opens you up to DOM clobbering.
The `labelTagName` and `labelAttributes` options are unsafe when used with user
content, they allow defining arbitrary HTML.

## Contribute

See [`contributing.md` in `micromark/.github`][contributing] for ways to get
started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark-extension-gfm/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark-extension-gfm/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark-extension-gfm.svg

[coverage]: https://codecov.io/github/micromark/micromark-extension-gfm

[downloads-badge]: https://img.shields.io/npm/dm/micromark-extension-gfm.svg

[downloads]: https://www.npmjs.com/package/micromark-extension-gfm

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-extension-gfm

[size]: https://bundlejs.com/?q=micromark-extension-gfm

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[npm]: https://docs.npmjs.com/cli/install

[esmsh]: https://esm.sh

[license]: license

[author]: https://wooorm.com

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[development]: https://nodejs.org/api/packages.html#packages_resolving_user_conditions

[typescript]: https://www.typescriptlang.org

[gfm]: https://github.github.com/gfm/

[strikethrough]: https://github.github.com/gfm/#strikethrough-extension-

[tables]: https://github.github.com/gfm/#tables-extension-

[tasklists]: https://github.github.com/gfm/#task-list-items-extension-

[autolink literals]: https://github.github.com/gfm/#autolinks-extension-

[tagfilter]: https://github.github.com/gfm/#disallowed-raw-html-extension-

[footnotes]: https://github.blog/changelog/2021-09-30-footnotes-now-supported-in-markdown-fields/

[micromark]: https://github.com/micromark/micromark

[micromark-extension]: https://github.com/micromark/micromark#syntaxextension

[micromark-html-extension]: https://github.com/micromark/micromark#htmlextension

[gfm-strikethrough]: https://github.com/micromark/micromark-extension-gfm-strikethrough

[gfm-strikethrough-options]: https://github.com/micromark/micromark-extension-gfm-strikethrough#options

[gfm-autolink-literal]: https://github.com/micromark/micromark-extension-gfm-autolink-literal

[gfm-footnote]: https://github.com/micromark/micromark-extension-gfm-footnote

[gfm-footnote-html-options]: https://github.com/micromark/micromark-extension-gfm-footnote#htmloptions

[gfm-table]: https://github.com/micromark/micromark-extension-gfm-table

[gfm-tagfilter]: https://github.com/micromark/micromark-extension-gfm-tagfilter

[gfm-task-list-item]: https://github.com/micromark/micromark-extension-gfm-task-list-item

[remark-gfm]: https://github.com/remarkjs/remark-gfm

[mdast-util-gfm]: https://github.com/syntax-tree/mdast-util-gfm

[api-gfm]: #gfmoptions

[api-gfm-html]: #gfmhtmloptions

[api-options]: #options

[api-html-options]: #htmloptions


---

# micromark-util-character

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility to handle [character codes][code].

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`asciiAlpha(code)`](#asciialphacode)
  * [`asciiAlphanumeric(code)`](#asciialphanumericcode)
  * [`asciiAtext(code)`](#asciiatextcode)
  * [`asciiControl(code)`](#asciicontrolcode)
  * [`asciiDigit(code)`](#asciidigitcode)
  * [`asciiHexDigit(code)`](#asciihexdigitcode)
  * [`asciiPunctuation(code)`](#asciipunctuationcode)
  * [`markdownLineEnding(code)`](#markdownlineendingcode)
  * [`markdownLineEndingOrSpace(code)`](#markdownlineendingorspacecode)
  * [`markdownSpace(code)`](#markdownspacecode)
  * [`unicodePunctuation(code)`](#unicodepunctuationcode)
  * [`unicodeWhitespace(code)`](#unicodewhitespacecode)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes algorithms to check whether characters match groups.

## When should I use this?

This package might be useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-character
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as character from 'https://esm.sh/micromark-util-character@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as character from 'https://esm.sh/micromark-util-character@1?bundle'
</script>
```

## Use

```js
import {asciiAlpha} from 'micromark-util-character'

console.log(asciiAlpha(64)) // false
console.log(asciiAlpha(65)) // true
```

## API

This module exports the identifiers
[`asciiAlpha`][api-ascii-alpha],
[`asciiAlphanumeric`][api-ascii-alphanumeric],
[`asciiAtext`][api-ascii-atext],
[`asciiControl`][api-ascii-control],
[`asciiDigit`][api-ascii-digit],
[`asciiHexDigit`][api-ascii-hex-digit],
[`asciiPunctuation`][api-ascii-punctuation],
[`markdownLineEnding`][api-markdown-line-ending],
[`markdownLineEndingOrSpace`][api-markdown-line-ending-or-space],
[`markdownSpace`][api-markdown-space],
[`unicodePunctuation`][api-unicode-punctuation],
[`unicodeWhitespace`][api-unicode-whitespace].
There is no default export.

### `asciiAlpha(code)`

Check whether the [character code][code] represents an ASCII alpha (`a` through
`z`, case insensitive).

An **ASCII alpha** is an ASCII upper alpha or ASCII lower alpha.

An **ASCII upper alpha** is a character in the inclusive range U+0041 (`A`)
to U+005A (`Z`).

An **ASCII lower alpha** is a character in the inclusive range U+0061 (`a`)
to U+007A (`z`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiAlphanumeric(code)`

Check whether the [character code][code] represents an ASCII alphanumeric (`a`
through `z`, case insensitive, or `0` through `9`).

An **ASCII alphanumeric** is an ASCII digit (see `asciiDigit`) or ASCII alpha
(see `asciiAlpha`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiAtext(code)`

Check whether the [character code][code] represents an ASCII atext.

atext is an ASCII alphanumeric (see `asciiAlphanumeric`), or a character in
the inclusive ranges U+0023 NUMBER SIGN (`#`) to U+0027 APOSTROPHE (`'`),
U+002A ASTERISK (`*`), U+002B PLUS SIGN (`+`), U+002D DASH (`-`), U+002F
SLASH (`/`), U+003D EQUALS TO (`=`), U+003F QUESTION MARK (`?`), U+005E
CARET (`^`) to U+0060 GRAVE ACCENT (`` ` ``), or U+007B LEFT CURLY BRACE
(`{`) to U+007E TILDE (`~`) (**\[RFC5322]**).

See **\[RFC5322]**:\
[Internet Message Format](https://tools.ietf.org/html/rfc5322).\
P. Resnick.\
IETF.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiControl(code)`

Check whether a [character code][code] is an ASCII control character.

An **ASCII control** is a character in the inclusive range U+0000 NULL (NUL)
to U+001F (US), or U+007F (DEL).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiDigit(code)`

Check whether the [character code][code] represents an ASCII digit (`0` through
`9`).

An **ASCII digit** is a character in the inclusive range U+0030 (`0`) to
U+0039 (`9`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiHexDigit(code)`

Check whether the [character code][code] represents an ASCII hex digit (`a`
through `f`, case insensitive, or `0` through `9`).

An **ASCII hex digit** is an ASCII digit (see `asciiDigit`), ASCII upper hex
digit, or an ASCII lower hex digit.

An **ASCII upper hex digit** is a character in the inclusive range U+0041
(`A`) to U+0046 (`F`).

An **ASCII lower hex digit** is a character in the inclusive range U+0061
(`a`) to U+0066 (`f`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiPunctuation(code)`

Check whether the [character code][code] represents ASCII punctuation.

An **ASCII punctuation** is a character in the inclusive ranges U+0021
EXCLAMATION MARK (`!`) to U+002F SLASH (`/`), U+003A COLON (`:`) to U+0040 AT
SIGN (`@`), U+005B LEFT SQUARE BRACKET (`[`) to U+0060 GRAVE ACCENT
(`` ` ``), or U+007B LEFT CURLY BRACE (`{`) to U+007E TILDE (`~`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownLineEnding(code)`

Check whether a [character code][code] is a markdown line ending.

A **markdown line ending** is the virtual characters M-0003 CARRIAGE RETURN
LINE FEED (CRLF), M-0004 LINE FEED (LF) and M-0005 CARRIAGE RETURN (CR).

In micromark, the actual character U+000A LINE FEED (LF) and U+000D CARRIAGE
RETURN (CR) are replaced by these virtual characters depending on whether
they occurred together.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownLineEndingOrSpace(code)`

Check whether a [character code][code] is a markdown line ending (see
`markdownLineEnding`) or markdown space (see `markdownSpace`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownSpace(code)`

Check whether a [character code][code] is a markdown space.

A **markdown space** is the concrete character U+0020 SPACE (SP) and the
virtual characters M-0001 VIRTUAL SPACE (VS) and M-0002 HORIZONTAL TAB (HT).

In micromark, the actual character U+0009 CHARACTER TABULATION (HT) is
replaced by one M-0002 HORIZONTAL TAB (HT) and between 0 and 3 M-0001 VIRTUAL
SPACE (VS) characters, depending on the column at which the tab occurred.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `unicodePunctuation(code)`

Check whether the [character code][code] represents Unicode punctuation.

A **Unicode punctuation** is a character in the Unicode `Pc` (Punctuation,
Connector), `Pd` (Punctuation, Dash), `Pe` (Punctuation, Close), `Pf`
(Punctuation, Final quote), `Pi` (Punctuation, Initial quote), `Po`
(Punctuation, Other), or `Ps` (Punctuation, Open) categories, or an ASCII
punctuation (see `asciiPunctuation`) (**\[UNICODE]**).

See **\[UNICODE]**:\
[The Unicode Standard](https://www.unicode.org/versions/).\
Unicode Consortium.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `unicodeWhitespace(code)`

Check whether the [character code][code] represents Unicode whitespace.

Note that this does handle micromark specific markdown whitespace characters.
See `markdownLineEndingOrSpace` to check that.

A **Unicode whitespace** is a character in the Unicode `Zs` (Separator,
Space) category, or U+0009 CHARACTER TABULATION (HT), U+000A LINE FEED (LF),
U+000C (FF), or U+000D CARRIAGE RETURN (CR) (**\[UNICODE]**).

See **\[UNICODE]**:\
[The Unicode Standard](https://www.unicode.org/versions/).\
Unicode Consortium.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-character@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-character.svg

[downloads]: https://www.npmjs.com/package/micromark-util-character

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-character

[bundle-size]: https://bundlejs.com/?q=micromark-util-character

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[code]: https://github.com/micromark/micromark#preprocess

[api-ascii-alpha]: #asciialphacode

[api-ascii-alphanumeric]: #asciialphanumericcode

[api-ascii-atext]: #asciiatextcode

[api-ascii-control]: #asciicontrolcode

[api-ascii-digit]: #asciidigitcode

[api-ascii-hex-digit]: #asciihexdigitcode

[api-ascii-punctuation]: #asciipunctuationcode

[api-markdown-line-ending]: #markdownlineendingcode

[api-markdown-line-ending-or-space]: #markdownlineendingorspacecode

[api-markdown-space]: #markdownspacecode

[api-unicode-punctuation]: #unicodepunctuationcode

[api-unicode-whitespace]: #unicodewhitespacecode


---

# micromark-util-symbol

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility with symbols.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes constants used throughout the micromark ecosystem.

## When should I use this?

This package is useful when you are making your own micromark extensions.
It’s useful to reference these constants by name instead of value while
developing.
[`micromark-build`][micromark-build] compiles them away for production code.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-symbol
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as symbol from 'https://esm.sh/micromark-util-symbol@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as symbol from 'https://esm.sh/micromark-util-symbol@1?bundle'
</script>
```

## Use

```js
import {codes, constants, types, values} from 'micromark-util-symbol'

console.log(codes.atSign) // 64
console.log(constants.characterReferenceNamedSizeMax) // 31
console.log(types.definitionDestinationRaw) // 'definitionDestinationRaw'
console.log(values.atSign) // '@'
```

## API

This package exports the identifiers `codes`, `constants`, `types`, and
`values`.
There is no default export.

Each identifier is an object mapping strings to values.
See the code for the exposed data.

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-symbol@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-symbol.svg

[downloads]: https://www.npmjs.com/package/micromark-util-symbol

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-symbol

[bundle-size]: https://bundlejs.com/?q=micromark-util-symbol

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[micromark-build]: https://github.com/micromark/micromark/tree/main/packages/micromark-build


---

# micromark-extension-gfm-autolink-literal

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[micromark][] extensions to support GFM [literal autolinks][spec].

## Contents

* [What is this?](#what-is-this)
* [When to use this](#when-to-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`gfmAutolinkLiteral()`](#gfmautolinkliteral)
  * [`gfmAutolinkLiteralHtml()`](#gfmautolinkliteralhtml)
* [Bugs](#bugs)
* [Authoring](#authoring)
* [HTML](#html)
* [CSS](#css)
* [Syntax](#syntax)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Related](#related)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package contains extensions that add support for the extra autolink syntax
enabled by GFM to [`micromark`][micromark].

GitHub employs different algorithms to autolink: one at parse time and one at
transform time (similar to how @mentions are done at transform time).
This difference can be observed because character references and escapes are
handled differently.
But also because issues/PRs/comments omit (perhaps by accident?) the second
algorithm for `www.`, `http://`, and `https://` links (but not for email links).

As this is a syntax extension, it focuses on the first algorithm.
The second algorithm is performed by
[`mdast-util-gfm-autolink-literal`][mdast-util-gfm-autolink-literal].
The `html` part of this micromark extension does not operate on an AST and hence
can’t perform the second algorithm.

The implementation of autolink literal on github.com is currently buggy.
The bugs have been reported on [`cmark-gfm`][cmark-gfm].
This micromark extension matches github.com except for its bugs.

## When to use this

This project is useful when you want to support autolink literals in markdown.

You can use these extensions when you are working with [`micromark`][micromark].
To support all GFM features, use
[`micromark-extension-gfm`][micromark-extension-gfm] instead.

When you need a syntax tree, combine this package with
[`mdast-util-gfm-autolink-literal`][mdast-util-gfm-autolink-literal].

All these packages are used in [`remark-gfm`][remark-gfm], which focusses on
making it easier to transform content by abstracting these internals away.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-extension-gfm-autolink-literal
```

In Deno with [`esm.sh`][esmsh]:

```js
import {gfmAutolinkLiteral, gfmAutolinkLiteralHtml} from 'https://esm.sh/micromark-extension-gfm-autolink-literal@2'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {gfmAutolinkLiteral, gfmAutolinkLiteralHtml} from 'https://esm.sh/micromark-extension-gfm-autolink-literal@2?bundle'
</script>
```

## Use

```js
import {micromark} from 'micromark'
import {
  gfmAutolinkLiteral,
  gfmAutolinkLiteralHtml
} from 'micromark-extension-gfm-autolink-literal'

const output = micromark('Just a URL: www.example.com.', {
  extensions: [gfmAutolinkLiteral()],
  htmlExtensions: [gfmAutolinkLiteralHtml()]
})

console.log(output)
```

Yields:

```html
<p>Just a URL: <a href="http://www.example.com">www.example.com</a>.</p>
```

## API

This package exports the identifiers
[`gfmAutolinkLiteral`][api-gfm-autolink-literal] and
[`gfmAutolinkLiteralHtml`][api-gfm-autolink-literal-html].
There is no default export.

The export map supports the [`development` condition][development].
Run `node --conditions development module.js` to get instrumented dev code.
Without this condition, production code is loaded.

### `gfmAutolinkLiteral()`

Create an extension for `micromark` to support GitHub autolink literal
syntax.

###### Parameters

Extension for `micromark` that can be passed in `extensions` to enable GFM
autolink literal syntax ([`Extension`][micromark-extension]).

### `gfmAutolinkLiteralHtml()`

Create an HTML extension for `micromark` to support GitHub autolink literal
when serializing to HTML.

###### Parameters

Extension for `micromark` that can be passed in `htmlExtensions` to support
GitHub autolink literal when serializing to HTML
([`HtmlExtension`][micromark-html-extension]).

## Bugs

GitHub’s own algorithm to parse autolink literals contains three bugs.
A smaller bug is left unfixed in this project for consistency.
Two main bugs are not present in this project.
The issues relating to autolink literals are:

* [GFM autolink extension (`www.`, `https?://` parts): links don’t work when
  after bracket](https://github.com/github/cmark-gfm/issues/278)\
  fixed here ✅
* [GFM autolink extension (`www.` part): uppercase does not match on
  issues/PRs/comments](https://github.com/github/cmark-gfm/issues/280)\
  fixed here ✅
* [GFM autolink extension (`www.` part): the word `www`
  matches](https://github.com/github/cmark-gfm/issues/279)\
  present here for consistency

## Authoring

It is recommended to use labels, either with a resource or a definition,
instead of autolink literals, as those allow relative URLs and descriptive
text to explain the URL in prose.

## HTML

GFM autolink literals relate to the `<a>` element in HTML.
See [*§ 4.5.1 The `a` element*][html-a] in the HTML spec for more info.
When an email autolink is used, the string `mailto:` is prepended when
generating the `href` attribute of the hyperlink.
When a www autolink is used, the string `http://` is prepended.

## CSS

As hyperlinks are the fundamental thing that makes the web, you will most
definitely have CSS for `a` elements already.
The same CSS can be used for autolink literals, too.

GitHub itself does not apply interesting CSS to autolink literals.
For any link, it currently (June 2022) [uses][css]:

```css
a {
  background-color: transparent;
  color: #58a6ff;
  text-decoration: none;
}

a:active,
a:hover {
  outline-width: 0;
}

a:hover {
  text-decoration: underline;
}

a:not([href]) {
  color: inherit;
  text-decoration: none;
}
```

## Syntax

Autolink literals form with, roughly, the following BNF:

```bnf
gfm_autolink_literal ::= gfm_protocol_autolink | gfm_www_autolink | gfm_email_autolink

; Restriction: the code before must be `www_autolink_before`.
; Restriction: the code after `.` must not be eof.
www_autolink ::= 3('w' | 'W') '.' [domain [path]]
www_autolink_before ::= eof | eol | space_or_tab | '(' | '*' | '_' | '[' | ']' | '~'

; Restriction: the code before must be `http_autolink_before`.
; Restriction: the code after the protocol must be `http_autolink_protocol_after`.
http_autolink ::= ('h' | 'H') 2('t' | 'T') ('p' | 'P') ['s' | 'S'] ':' 2'/' domain [path]
http_autolink_before ::= byte - ascii_alpha
http_autolink_protocol_after ::= byte - eof - eol - ascii_control - unicode_whitespace - ode_punctuation

; Restriction: the code before must be `email_autolink_before`.
; Restriction: `ascii_digit` may not occur in the last label part of the label.
email_autolink ::= 1*('+' | '-' | '.' | '_' | ascii_alphanumeric) '@' 1*(1*label_segment l_dot_cont) 1*label_segment
email_autolink_before ::= byte - ascii_alpha - '/'

; Restriction: `_` may not occur in the last two domain parts.
domain ::= 1*(url_ampt_cont | domain_punct_cont | '-' | byte - eof - ascii_control - ode_whitespace - unicode_punctuation)
; Restriction: must not be followed by `punct`.
domain_punct_cont ::= '.' | '_'
; Restriction: must not be followed by `char-ref`.
url_ampt_cont ::= '&'

; Restriction: a counter `balance = 0` is increased for every `(`, and decreased for every `)`.
; Restriction: `)` must not be `paren_at_end`.
path ::= 1*(url_ampt_cont | path_punctuation_cont | '(' | ')' | byte - eof - eol - space_or_tab)
; Restriction: must not be followed by `punct`.
path_punctuation_cont ::= trailing_punctuation - '<'
; Restriction: must be followed by `punct` and `balance` must be less than `0`.
paren_at_end ::= ')'

label_segment ::= label_dash_underscore_cont | ascii_alpha | ascii_digit
; Restriction: if followed by `punct`, the whole email autolink is invalid.
label_dash_underscore_cont ::= '-' | '_'
; Restriction: must not be followed by `punct`.
label_dot_cont ::= '.'

punct ::= *trailing_punctuation ( byte - eof - eol - space_or_tab - '<' )
char_ref ::= *ascii_alpha ';' path_end
trailing_punctuation ::= '!' | '"' | '\'' | ')' | '*' | ',' | '.' | ':' | ';' | '<' | '?' | '_' | '~'
```

The grammar for GFM autolink literal is very relaxed: basically anything
except for whitespace is allowed after a prefix.
To use whitespace characters and otherwise impossible characters, in URLs,
you can use percent encoding:

```markdown
https://example.com/alpha%20bravo
```

Yields:

```html
<p><a href="https://example.com/alpha%20bravo">https://example.com/alpha%20bravo</a></p>
```

There are several cases where incorrect encoding of URLs would, in other
languages, result in a parse error.
In markdown, there are no errors, and URLs are normalized.
In addition, many characters are percent encoded
([`sanitizeUri`][micromark-util-sanitize-uri]).
For example:

```markdown
www.a👍b%
```

Yields:

```html
<p><a href="http://www.a%F0%9F%91%8Db%25">www.a👍b%</a></p>
```

There is a big difference between how www and protocol literals work
compared to how email literals work.
The first two are done when parsing, and work like anything else in
markdown.
But email literals are handled afterwards: when everything is parsed, we
look back at the events to figure out if there were email addresses.
This particularly affects how they interleave with character escapes and
character references.

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-extension-gfm-autolink-literal@^2`, compatible with Node.js 16.

This package works with `micromark` version `3` and later.

## Security

This package is safe.
Unlike other links in CommonMark, which allow arbitrary protocols, this
construct always produces safe links.

## Related

* [`micromark-extension-gfm`][micromark-extension-gfm]
  — support all of GFM
* [`mdast-util-gfm-autolink-literal`][mdast-util-gfm-autolink-literal]
  — support all of GFM in mdast
* [`mdast-util-gfm`][mdast-util-gfm]
  — support all of GFM in mdast
* [`remark-gfm`][remark-gfm]
  — support all of GFM in remark

## Contribute

See [`contributing.md` in `micromark/.github`][contributing] for ways to get
started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark-extension-gfm-autolink-literal/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark-extension-gfm-autolink-literal/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark-extension-gfm-autolink-literal.svg

[coverage]: https://codecov.io/github/micromark/micromark-extension-gfm-autolink-literal

[downloads-badge]: https://img.shields.io/npm/dm/micromark-extension-gfm-autolink-literal.svg

[downloads]: https://www.npmjs.com/package/micromark-extension-gfm-autolink-literal

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-extension-gfm-autolink-literal

[size]: https://bundlejs.com/?q=micromark-extension-gfm-autolink-literal

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[npm]: https://docs.npmjs.com/cli/install

[esmsh]: https://esm.sh

[license]: license

[author]: https://wooorm.com

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[typescript]: https://www.typescriptlang.org

[development]: https://nodejs.org/api/packages.html#packages_resolving_user_conditions

[micromark]: https://github.com/micromark/micromark

[micromark-extension-gfm]: https://github.com/micromark/micromark-extension-gfm

[micromark-util-sanitize-uri]: https://github.com/micromark/micromark/tree/main/packages/micromark-util-sanitize-uri

[micromark-extension]: https://github.com/micromark/micromark#syntaxextension

[micromark-html-extension]: https://github.com/micromark/micromark#htmlextension

[mdast-util-gfm]: https://github.com/syntax-tree/mdast-util-gfm

[mdast-util-gfm-autolink-literal]: https://github.com/syntax-tree/mdast-util-gfm-autolink-literal

[remark-gfm]: https://github.com/remarkjs/remark-gfm

[spec]: https://github.github.com/gfm/#autolinks-extension-

[html-a]: https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-a-element

[css]: https://github.com/sindresorhus/github-markdown-css

[cmark-gfm]: https://github.com/github/cmark-gfm

[api-gfm-autolink-literal]: #gfmautolinkliteral

[api-gfm-autolink-literal-html]: #gfmautolinkliteralhtml


---

# micromark-factory-space

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] factory to parse [markdown space][markdown-space] (found in lots
of places).

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`factorySpace(…)`](#factoryspace)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes states to parse spaces and/or tabs.

## When should I use this?

This package is useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-factory-space
```

In Deno with [`esm.sh`][esmsh]:

```js
import {factorySpace} from 'https://esm.sh/micromark-factory-space@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {factorySpace} from 'https://esm.sh/micromark-factory-space@1?bundle'
</script>
```

## Use

```js
import {factorySpace} from 'micromark-factory-space'
import {codes, types} from 'micromark-util-symbol'

// A micromark tokenizer that uses the factory:
/**
 * @this {TokenizeContext}
 *   Context.
 * @type {Tokenizer}
 */
function tokenizeCodeFenced(effects, ok, nok) {
  return start

  // …

  /** @type {State} */
  function info(code) {
    if (code === codes.eof || markdownLineEndingOrSpace(code)) {
      effects.exit(types.chunkString)
      effects.exit(types.codeFencedFenceInfo)
      return factorySpace(effects, infoAfter, types.whitespace)(code)
    }

    if (code === codes.graveAccent && code === marker) return nok(code)
    effects.consume(code)
    return info
  }

  // …
}
```

## API

This module exports the identifier [`factorySpace`][api-factory-space].
There is no default export.

### `factorySpace(…)`

Parse spaces and tabs.

There is no `nok` parameter:

* spaces in markdown are often optional, in which case this factory can be
  used and `ok` will be switched to whether spaces were found or not
* one line ending or space can be detected with `markdownSpace(code)` right
  before using `factorySpace`

###### Examples

Where `␉` represents a tab (plus how much it expands) and `␠` represents a
single space.

```markdown
␉
␠␠␠␠
␉␠
```

###### Parameters

* `effects` (`Effects`)
  — context
* `ok` (`State`)
  — state switched to when successful
* `type` (`string`)
  — type (`' \t'`)
* `max` (`number`, default: `Infinity`)
  — max (exclusive)

###### Returns

Start state (`State`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-factory-space@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-factory-space.svg

[downloads]: https://www.npmjs.com/package/micromark-factory-space

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-factory-space

[bundle-size]: https://bundlejs.com/?q=micromark-factory-space

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[markdown-space]: https://github.com/micromark/micromark/tree/main/packages/micromark-util-character#markdownspacecode

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[api-factory-space]: #factoryspace


---

# micromark-util-character

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility to handle [character codes][code].

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`asciiAlpha(code)`](#asciialphacode)
  * [`asciiAlphanumeric(code)`](#asciialphanumericcode)
  * [`asciiAtext(code)`](#asciiatextcode)
  * [`asciiControl(code)`](#asciicontrolcode)
  * [`asciiDigit(code)`](#asciidigitcode)
  * [`asciiHexDigit(code)`](#asciihexdigitcode)
  * [`asciiPunctuation(code)`](#asciipunctuationcode)
  * [`markdownLineEnding(code)`](#markdownlineendingcode)
  * [`markdownLineEndingOrSpace(code)`](#markdownlineendingorspacecode)
  * [`markdownSpace(code)`](#markdownspacecode)
  * [`unicodePunctuation(code)`](#unicodepunctuationcode)
  * [`unicodeWhitespace(code)`](#unicodewhitespacecode)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes algorithms to check whether characters match groups.

## When should I use this?

This package might be useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-character
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as character from 'https://esm.sh/micromark-util-character@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as character from 'https://esm.sh/micromark-util-character@1?bundle'
</script>
```

## Use

```js
import {asciiAlpha} from 'micromark-util-character'

console.log(asciiAlpha(64)) // false
console.log(asciiAlpha(65)) // true
```

## API

This module exports the identifiers
[`asciiAlpha`][api-ascii-alpha],
[`asciiAlphanumeric`][api-ascii-alphanumeric],
[`asciiAtext`][api-ascii-atext],
[`asciiControl`][api-ascii-control],
[`asciiDigit`][api-ascii-digit],
[`asciiHexDigit`][api-ascii-hex-digit],
[`asciiPunctuation`][api-ascii-punctuation],
[`markdownLineEnding`][api-markdown-line-ending],
[`markdownLineEndingOrSpace`][api-markdown-line-ending-or-space],
[`markdownSpace`][api-markdown-space],
[`unicodePunctuation`][api-unicode-punctuation],
[`unicodeWhitespace`][api-unicode-whitespace].
There is no default export.

### `asciiAlpha(code)`

Check whether the [character code][code] represents an ASCII alpha (`a` through
`z`, case insensitive).

An **ASCII alpha** is an ASCII upper alpha or ASCII lower alpha.

An **ASCII upper alpha** is a character in the inclusive range U+0041 (`A`)
to U+005A (`Z`).

An **ASCII lower alpha** is a character in the inclusive range U+0061 (`a`)
to U+007A (`z`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiAlphanumeric(code)`

Check whether the [character code][code] represents an ASCII alphanumeric (`a`
through `z`, case insensitive, or `0` through `9`).

An **ASCII alphanumeric** is an ASCII digit (see `asciiDigit`) or ASCII alpha
(see `asciiAlpha`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiAtext(code)`

Check whether the [character code][code] represents an ASCII atext.

atext is an ASCII alphanumeric (see `asciiAlphanumeric`), or a character in
the inclusive ranges U+0023 NUMBER SIGN (`#`) to U+0027 APOSTROPHE (`'`),
U+002A ASTERISK (`*`), U+002B PLUS SIGN (`+`), U+002D DASH (`-`), U+002F
SLASH (`/`), U+003D EQUALS TO (`=`), U+003F QUESTION MARK (`?`), U+005E
CARET (`^`) to U+0060 GRAVE ACCENT (`` ` ``), or U+007B LEFT CURLY BRACE
(`{`) to U+007E TILDE (`~`) (**\[RFC5322]**).

See **\[RFC5322]**:\
[Internet Message Format](https://tools.ietf.org/html/rfc5322).\
P. Resnick.\
IETF.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiControl(code)`

Check whether a [character code][code] is an ASCII control character.

An **ASCII control** is a character in the inclusive range U+0000 NULL (NUL)
to U+001F (US), or U+007F (DEL).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiDigit(code)`

Check whether the [character code][code] represents an ASCII digit (`0` through
`9`).

An **ASCII digit** is a character in the inclusive range U+0030 (`0`) to
U+0039 (`9`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiHexDigit(code)`

Check whether the [character code][code] represents an ASCII hex digit (`a`
through `f`, case insensitive, or `0` through `9`).

An **ASCII hex digit** is an ASCII digit (see `asciiDigit`), ASCII upper hex
digit, or an ASCII lower hex digit.

An **ASCII upper hex digit** is a character in the inclusive range U+0041
(`A`) to U+0046 (`F`).

An **ASCII lower hex digit** is a character in the inclusive range U+0061
(`a`) to U+0066 (`f`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiPunctuation(code)`

Check whether the [character code][code] represents ASCII punctuation.

An **ASCII punctuation** is a character in the inclusive ranges U+0021
EXCLAMATION MARK (`!`) to U+002F SLASH (`/`), U+003A COLON (`:`) to U+0040 AT
SIGN (`@`), U+005B LEFT SQUARE BRACKET (`[`) to U+0060 GRAVE ACCENT
(`` ` ``), or U+007B LEFT CURLY BRACE (`{`) to U+007E TILDE (`~`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownLineEnding(code)`

Check whether a [character code][code] is a markdown line ending.

A **markdown line ending** is the virtual characters M-0003 CARRIAGE RETURN
LINE FEED (CRLF), M-0004 LINE FEED (LF) and M-0005 CARRIAGE RETURN (CR).

In micromark, the actual character U+000A LINE FEED (LF) and U+000D CARRIAGE
RETURN (CR) are replaced by these virtual characters depending on whether
they occurred together.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownLineEndingOrSpace(code)`

Check whether a [character code][code] is a markdown line ending (see
`markdownLineEnding`) or markdown space (see `markdownSpace`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownSpace(code)`

Check whether a [character code][code] is a markdown space.

A **markdown space** is the concrete character U+0020 SPACE (SP) and the
virtual characters M-0001 VIRTUAL SPACE (VS) and M-0002 HORIZONTAL TAB (HT).

In micromark, the actual character U+0009 CHARACTER TABULATION (HT) is
replaced by one M-0002 HORIZONTAL TAB (HT) and between 0 and 3 M-0001 VIRTUAL
SPACE (VS) characters, depending on the column at which the tab occurred.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `unicodePunctuation(code)`

Check whether the [character code][code] represents Unicode punctuation.

A **Unicode punctuation** is a character in the Unicode `Pc` (Punctuation,
Connector), `Pd` (Punctuation, Dash), `Pe` (Punctuation, Close), `Pf`
(Punctuation, Final quote), `Pi` (Punctuation, Initial quote), `Po`
(Punctuation, Other), or `Ps` (Punctuation, Open) categories, or an ASCII
punctuation (see `asciiPunctuation`) (**\[UNICODE]**).

See **\[UNICODE]**:\
[The Unicode Standard](https://www.unicode.org/versions/).\
Unicode Consortium.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `unicodeWhitespace(code)`

Check whether the [character code][code] represents Unicode whitespace.

Note that this does handle micromark specific markdown whitespace characters.
See `markdownLineEndingOrSpace` to check that.

A **Unicode whitespace** is a character in the Unicode `Zs` (Separator,
Space) category, or U+0009 CHARACTER TABULATION (HT), U+000A LINE FEED (LF),
U+000C (FF), or U+000D CARRIAGE RETURN (CR) (**\[UNICODE]**).

See **\[UNICODE]**:\
[The Unicode Standard](https://www.unicode.org/versions/).\
Unicode Consortium.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-character@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-character.svg

[downloads]: https://www.npmjs.com/package/micromark-util-character

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-character

[bundle-size]: https://bundlejs.com/?q=micromark-util-character

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[code]: https://github.com/micromark/micromark#preprocess

[api-ascii-alpha]: #asciialphacode

[api-ascii-alphanumeric]: #asciialphanumericcode

[api-ascii-atext]: #asciiatextcode

[api-ascii-control]: #asciicontrolcode

[api-ascii-digit]: #asciidigitcode

[api-ascii-hex-digit]: #asciihexdigitcode

[api-ascii-punctuation]: #asciipunctuationcode

[api-markdown-line-ending]: #markdownlineendingcode

[api-markdown-line-ending-or-space]: #markdownlineendingorspacecode

[api-markdown-space]: #markdownspacecode

[api-unicode-punctuation]: #unicodepunctuationcode

[api-unicode-whitespace]: #unicodewhitespacecode


---

# micromark-util-symbol

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility with symbols.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes constants used throughout the micromark ecosystem.

## When should I use this?

This package is useful when you are making your own micromark extensions.
It’s useful to reference these constants by name instead of value while
developing.
[`micromark-build`][micromark-build] compiles them away for production code.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-symbol
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as symbol from 'https://esm.sh/micromark-util-symbol@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as symbol from 'https://esm.sh/micromark-util-symbol@1?bundle'
</script>
```

## Use

```js
import {codes, constants, types, values} from 'micromark-util-symbol'

console.log(codes.atSign) // 64
console.log(constants.characterReferenceNamedSizeMax) // 31
console.log(types.definitionDestinationRaw) // 'definitionDestinationRaw'
console.log(values.atSign) // '@'
```

## API

This package exports the identifiers `codes`, `constants`, `types`, and
`values`.
There is no default export.

Each identifier is an object mapping strings to values.
See the code for the exposed data.

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-symbol@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-symbol.svg

[downloads]: https://www.npmjs.com/package/micromark-util-symbol

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-symbol

[bundle-size]: https://bundlejs.com/?q=micromark-util-symbol

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[micromark-build]: https://github.com/micromark/micromark/tree/main/packages/micromark-build


---

# micromark-extension-gfm-footnote

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[micromark][] extensions to support GFM [footnotes][post].

## Contents

* [What is this?](#what-is-this)
* [When to use this](#when-to-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`defaultBackLabel(referenceIndex, rereferenceIndex)`](#defaultbacklabelreferenceindex-rereferenceindex)
  * [`gfmFootnote()`](#gfmfootnote)
  * [`gfmFootnoteHtml(options?)`](#gfmfootnotehtmloptions)
  * [`BackLabelTemplate`](#backlabeltemplate)
  * [`HtmlOptions`](#htmloptions)
* [Bugs](#bugs)
* [Authoring](#authoring)
* [HTML](#html)
* [CSS](#css)
* [Syntax](#syntax)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Related](#related)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package contains extensions that add support for footnotes as enabled by
GFM to [`micromark`][micromark].

GitHub announced footnotes [on September 30, 2021][post] but did not specify
them in their GFM spec.
As they are implemented in their parser and supported in all places where
other GFM features work, they can be considered part of GFM.
GitHub employs several other features (such as mentions or frontmatter) that
are either not in their parser, or not in all places where GFM features work,
which should not be considered GFM.

The implementation of footnotes on github.com is currently buggy.
The bugs have been reported on [`cmark-gfm`][cmark-gfm].
This micromark extension matches github.com except for its bugs.

## When to use this

This project is useful when you want to support footnotes in markdown.

You can use these extensions when you are working with [`micromark`][micromark].
To support all GFM features, use
[`micromark-extension-gfm`][micromark-extension-gfm] instead.

When you need a syntax tree, combine this package with
[`mdast-util-gfm-footnote`][mdast-util-gfm-footnote].

All these packages are used in [`remark-gfm`][remark-gfm], which focusses on
making it easier to transform content by abstracting these internals away.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-extension-gfm-footnote
```

In Deno with [`esm.sh`][esmsh]:

```js
import {gfmFootnote, gfmFootnoteHtml} from 'https://esm.sh/micromark-extension-gfm-footnote@2'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {gfmFootnote, gfmFootnoteHtml} from 'https://esm.sh/micromark-extension-gfm-footnote@2?bundle'
</script>
```

## Use

Say our document `example.md` contains:

````markdown
Using footnotes is fun![^1] They let you reference relevant information without disrupting the flow of what you’re trying to say.[^bignote]

[^1]: This is the first footnote.
[^bignote]: Here’s one with multiple paragraphs and code.

    Indent paragraphs to include them in the footnote.

    ```
    my code
    ```

    Add as many paragraphs as you like.

Text here and here and here.
[Learn more about markdown and footnotes in markdown](https://docs.github.com/en/github/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#footnotes)
````

…and our module `example.js` looks as follows:

```js
import fs from 'node:fs/promises'
import {micromark} from 'micromark'
import {gfmFootnote, gfmFootnoteHtml} from 'micromark-extension-gfm-footnote'

const output = micromark(await fs.readFile('example.md'), {
  extensions: [gfmFootnote()],
  htmlExtensions: [gfmFootnoteHtml()]
})

console.log(output)
```

…now running `node example.js` yields:

```html
<p>Using footnotes is fun!<sup><a href="#user-content-fn-1" id="user-content-fnref-1" data-footnote-ref="" aria-describedby="footnote-label">1</a></sup> They let you reference relevant information without disrupting the flow of what you’re trying to say.<sup><a href="#user-content-fn-bignote" id="user-content-fnref-bignote" data-footnote-ref="" aria-describedby="footnote-label">2</a></sup></p>
<p>Text here and here and here.
<a href="https://docs.github.com/en/github/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#footnotes">Learn more about markdown and footnotes in markdown</a></p>
<section data-footnotes="" class="footnotes"><h2 id="footnote-label" class="sr-only">Footnotes</h2>
<ol>
<li id="user-content-fn-1">
<p>This is the first footnote. <a href="#user-content-fnref-1" data-footnote-backref="" class="data-footnote-backref" aria-label="Back to content">↩</a></p>
</li>
<li id="user-content-fn-bignote">
<p>Here’s one with multiple paragraphs and code.</p>
<p>Indent paragraphs to include them in the footnote.</p>
<pre><code>my code
</code></pre>
<p>Add as many paragraphs as you like. <a href="#user-content-fnref-bignote" data-footnote-backref="" class="data-footnote-backref" aria-label="Back to content">↩</a></p>
</li>
</ol>
</section>
```

## API

This package exports the identifiers
[`defaultBackLabel`][api-default-back-label],
[`gfmFootnote`][api-gfm-footnote], and
[`gfmFootnoteHtml`][api-gfm-footnote-html].
There is no default export.

The export map supports the [`development` condition][development].
Run `node --conditions development module.js` to get instrumented dev code.
Without this condition, production code is loaded.

### `defaultBackLabel(referenceIndex, rereferenceIndex)`

Generate the default label that GitHub uses on backreferences
([`BackLabelTemplate`][api-back-label-template]).

### `gfmFootnote()`

Create an extension for `micromark` to enable GFM footnote syntax.

###### Returns

Extension for `micromark` that can be passed in `extensions` to enable GFM
footnote syntax ([`Extension`][micromark-extension]).

### `gfmFootnoteHtml(options?)`

Create an extension for `micromark` to support GFM footnotes when serializing
to HTML.

###### Parameters

* `options` ([`HtmlOptions`][api-html-options], optional)
  — configuration

###### Returns

Extension for `micromark` that can be passed in `htmlExtensions` to support GFM
footnotes when serializing to HTML
([`HtmlExtension`][micromark-html-extension]).

### `BackLabelTemplate`

Generate a back label dynamically (TypeScript type).

For the following markdown:

```markdown
Alpha[^micromark], bravo[^micromark], and charlie[^remark].

[^remark]: things about remark
[^micromark]: things about micromark
```

This function will be called with:

* `0` and `0` for the backreference from `things about micromark` to
  `alpha`, as it is the first used definition, and the first call to it
* `0` and `1` for the backreference from `things about micromark` to
  `bravo`, as it is the first used definition, and the second call to it
* `1` and `0` for the backreference from `things about remark` to
  `charlie`, as it is the second used definition

###### Parameters

* `referenceIndex` (`number`)
  — index of the definition in the order that they are first referenced,
  0-indexed
* `rereferenceIndex` (`number`)
  — index of calls to the same definition, 0-indexed

###### Returns

Back label to use when linking back from definitions to their reference
(`string`).

### `HtmlOptions`

Configuration (TypeScript type).

##### Fields

###### `clobberPrefix`

Prefix to use before the `id` attribute on footnotes to prevent them from
*clobbering* (`string`, default: `'user-content-'`).

Pass `''` for trusted markdown and when you are careful with polyfilling.
You could pass a different prefix.

DOM clobbering is this:

```html
<p id="x"></p>
<script>alert(x) // `x` now refers to the `p#x` DOM element</script>
```

The above example shows that elements are made available by browsers, by their
ID, on the `window` object.
This is a security risk because you might be expecting some other variable at
that place.
It can also break polyfills.
Using a prefix solves these problems.

###### `label`

Textual label to use for the footnotes section (`string`, default:
`'Footnotes'`).

Change it when the markdown is not in English.

This label is typically hidden visually (assuming a `sr-only` CSS class
is defined that does that) and so affects screen readers only.

###### `labelAttributes`

Attributes to use on the footnote label (`string`, default:
`'class="sr-only"'`).

Change it to show the label and add other attributes.

This label is typically hidden visually (assuming an `sr-only` CSS class
is defined that does that) and so affects screen readers only.
If you do have such a class, but want to show this section to everyone,
pass an empty string.
You can also add different attributes.

> 👉 **Note**: `id="footnote-label"` is always added, because footnote
> calls use it with `aria-describedby` to provide an accessible label.

###### `labelTagName`

HTML tag name to use for the footnote label element (`string`, default:
`'h2'`).

Change it to match your document structure.

This label is typically hidden visually (assuming a `sr-only` CSS class
is defined that does that) and so affects screen readers only.

###### `backLabel`

Textual label to describe the backreference back to footnote calls
([`BackLabelTemplate`][api-back-label-template] or `string`,
default: [`defaultBackLabel`][api-default-back-label]).

Change it when the markdown is not in English.

This label is used in the [`aria-label`][aria-label] attribute on each
backreference (the `↩` links).
It affects users of assistive technology.

## Bugs

GitHub’s own algorithm to parse footnote definitions contains several bugs.
These are not present in this project.
The issues relating to footnote definitions are:

* [Footnote reference call identifiers are trimmed, but definition
  identifiers aren’t](https://github.com/github/cmark-gfm/issues/237)\
  — initial and final whitespace in labels causes them not to match
* [Footnotes are matched case-insensitive, but links keep their casing,
  breaking them](https://github.com/github/cmark-gfm/issues/239)\
  — using uppercase (or any character that will be percent encoded) in
  identifiers breaks links
* [Colons in footnotes generate links w/o
  `href`](https://github.com/github/cmark-gfm/issues/250)\
  — colons in identifiers generate broken links
* [Character escape of `]` does not work in footnote
  identifiers](https://github.com/github/cmark-gfm/issues/240)\
  — some character escapes don’t work
* [Footnotes in links are
  broken](https://github.com/github/cmark-gfm/issues/249)\
  — while `CommonMark` prevents links in links, GitHub does not prevent
  footnotes (which turn into links) in links
* [Footnote-like brackets around image, break that
  image](https://github.com/github/cmark-gfm/issues/275)\
  — images can’t be used in what looks like a footnote call
* [GFM footnotes: line ending in footnote definition label causes text to
  disappear](https://github.com/github/cmark-gfm/issues/282)\
  — line endings in footnote definitions cause text to disappear

## Authoring

When authoring markdown with footnotes it’s recommended to use words instead
of numbers (or letters or anything with an order) as identifiers.
That makes it easier to reuse and reorder footnotes.

It’s recommended to place footnotes definitions at the bottom of the document.

## HTML

GFM footnotes do not, on their own, relate to anything in HTML.
When a footnote reference matches with a definition, they each relate to several
elements in HTML.

The reference relates to `<sup>` and `<a>` elements in HTML:

```html
<sup><a href="#user-content-fn-x" id="user-content-fnref-x" data-footnote-ref="" aria-describedby="footnote-label">1</a></sup></p>
```

…where `x` is the identifier used in the markdown source and `1` the number of
corresponding, listed, definition.

See [*§ 4.5.19 The `sub` and `sup` elements*][html-sup],
[*§ 4.5.1 The `a` element*][html-a], and
[*§ 3.2.6.6 Embedding custom non-visible data with the `data-*`
attributes*][html-data]
in the HTML spec, and
[*§ 6.8 `aria-describedby` property*][aria-describedby]
in WAI-ARIA, for more info.

When one or more definitions are referenced, a footnote section is generated at
the end of the document, using `<section>`, `<h2>`, and `<ol>` elements:

```html
<section data-footnotes="" class="footnotes"><h2 id="footnote-label" class="sr-only">Footnotes</h2>
<ol>…</ol>
</section>
```

Each definition is generated as a `<li>` in the `<ol>` in the order they were
first referenced:

```html
<li id="user-content-fn-1">…</li>
```

Backreferences are injected at the end of the first paragraph, or, when there
is no paragraph, at the end of the definition.
When a definition is referenced multiple times, multiple backreferences are
generated.
Further backreferences use an extra counter in the `href` attribute and
visually in a `<span>` after `↩`.

```html
<a href="#user-content-fnref-1" data-footnote-backref="" class="data-footnote-backref" aria-label="Back to content">↩</a> <a href="#user-content-fnref-1-2" data-footnote-backref="" class="data-footnote-backref" aria-label="Back to content">↩<sup>2</sup></a>
```

See
[*§ 4.5.1 The `a` element*][html-a],
[*§ 4.3.6 The `h1`, `h2`, `h3`, `h4`, `h5`, and `h6` elements*][html-h],
[*§ 4.4.8 The `li` element*][html-li],
[*§ 4.4.5 The `ol` element*][html-ol],
[*§ 4.4.1 The `p` element*][html-p],
[*§ 4.3.3 The `section` element*][html-section], and
[*§ 4.5.19 The `sub` and `sup` elements*][html-sup]
in the HTML spec, and
[*§ 6.8 `aria-label` property*][aria-label]
in WAI-ARIA, for more info.

## CSS

The following CSS is needed to make footnotes look a bit like GitHub (and fixes
a bug).
For the complete actual CSS see
[`sindresorhus/github-markdown-css`](https://github.com/sindresorhus/github-markdown-css).

```css
/* Style the footnotes section. */
.footnotes {
  font-size: smaller;
  color: #8b949e;
  border-top: 1px solid #30363d;
}

/* Hide the section label for visual users. */
.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  word-wrap: normal;
  border: 0;
}

/* Place `[` and `]` around footnote references. */
[data-footnote-ref]::before {
  content: '[';
}

[data-footnote-ref]::after {
  content: ']';
}
```

## Syntax

Footnotes form with, roughly, the following BNF:

```bnf
gfm_footnote_reference ::= gfm_footnote_label

gfm_footnote_definition_start ::= gfm_footnote_label ':' *space_or_tab
; Restriction: blank line allowed.
gfm_footnote_definition_cont ::= 4(space_or_tab)

; Restriction: maximum `999` codes between `^` and `]`.
gfm_footnote_label ::= '[' '^' 1*(gfm_footnote_label_byte | gfm_footnote_label_escape) ']'
gfm_footnote_label_byte ::= text - '[' - '\\' - ']'
gfm_footnote_label_escape ::= '\\' ['[' | '\\' | ']']

; Any byte (u8)
byte ::= 0x00..=0xFFFF
space_or_tab ::= '\t' | ' '
eol ::= '\n' | '\r' | '\r\n'
line ::= byte - eol
text ::= line - space_or_tab
```

Further lines after `gfm_footnote_definition_start` that are not prefixed with
`gfm_footnote_definition_cont` cause the footnote definition to be exited,
except when those lines are lazy continuation or blank.
Like so many things in markdown, footnote definition too are complex.
See [*§ Phase 1: block structure* in `CommonMark`][commonmark-block] for more
on parsing details.

The identifiers in the `label` parts are interpreted as the
[string][micromark-content-types] content type.
That means that character escapes and character references are allowed.

Definitions match to references through identifiers.
To match, both labels must be equal after normalizing with
[`normalizeIdentifier`][micromark-normalize-identifier].
One definition can match to multiple calls.
Multiple definitions with the same, normalized, identifier are ignored: the
first definition is preferred.
To illustrate, the definition with the content of `x` wins:

```markdown
[^a]: x
[^a]: y

[^a]
```

Importantly, while labels *can* include [string][micromark-content-types]
content (character escapes and character references), these are not considered
when matching.
To illustrate, neither definition matches the reference:

```markdown
[^a&amp;b]: x
[^a\&b]: y

[^a&b]
```

Because footnote definitions are containers (like block quotes and list items),
they can contain more footnote definitions.
They can even include references to themselves.

## Types

This package is fully typed with [TypeScript][].
It exports the additional types [`BackLabelTemplate`][api-back-label-template]
and [`HtmlOptions`][api-html-options].

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-extension-gfm-footnote@^2`, compatible with Node.js 16.

This package works with `micromark` version `3` and later.

## Security

This package is safe.
Setting `clobberPrefix = ''` is dangerous, it opens you up to DOM clobbering.
The `labelTagName` and `labelAttributes` options are unsafe when used with user
content, they allow defining arbitrary HTML.

## Related

* [`micromark-extension-gfm`][micromark-extension-gfm]
  — support all of GFM
* [`mdast-util-gfm-footnote`][mdast-util-gfm-footnote]
  — support all of GFM in mdast
* [`mdast-util-gfm`][mdast-util-gfm]
  — support all of GFM in mdast
* [`remark-gfm`][remark-gfm]
  — support all of GFM in remark

## Contribute

See [`contributing.md` in `micromark/.github`][contributing] for ways to get
started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark-extension-gfm-footnote/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark-extension-gfm-footnote/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark-extension-gfm-footnote.svg

[coverage]: https://codecov.io/github/micromark/micromark-extension-gfm-footnote

[downloads-badge]: https://img.shields.io/npm/dm/micromark-extension-gfm-footnote.svg

[downloads]: https://www.npmjs.com/package/micromark-extension-gfm-footnote

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-extension-gfm-footnote

[size]: https://bundlejs.com/?q=micromark-extension-gfm-footnote

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[npm]: https://docs.npmjs.com/cli/install

[esmsh]: https://esm.sh

[license]: license

[author]: https://wooorm.com

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[typescript]: https://www.typescriptlang.org

[development]: https://nodejs.org/api/packages.html#packages_resolving_user_conditions

[micromark]: https://github.com/micromark/micromark

[micromark-content-types]: https://github.com/micromark/micromark#content-types

[micromark-extension]: https://github.com/micromark/micromark#syntaxextension

[micromark-html-extension]: https://github.com/micromark/micromark#htmlextension

[micromark-normalize-identifier]: https://github.com/micromark/micromark/tree/main/packages/micromark-util-normalize-identifier

[micromark-extension-gfm]: https://github.com/micromark/micromark-extension-gfm

[mdast-util-gfm-footnote]: https://github.com/syntax-tree/mdast-util-gfm-footnote

[mdast-util-gfm]: https://github.com/syntax-tree/mdast-util-gfm

[remark-gfm]: https://github.com/remarkjs/remark-gfm

[post]: https://github.blog/changelog/2021-09-30-footnotes-now-supported-in-markdown-fields/

[cmark-gfm]: https://github.com/github/cmark-gfm

[commonmark-block]: https://spec.commonmark.org/0.30/#phase-1-block-structure

[html-a]: https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-a-element

[html-data]: https://html.spec.whatwg.org/multipage/dom.html#embedding-custom-non-visible-data-with-the-data-*-attributes

[html-h]: https://html.spec.whatwg.org/multipage/sections.html#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements

[html-li]: https://html.spec.whatwg.org/multipage/grouping-content.html#the-li-element

[html-ol]: https://html.spec.whatwg.org/multipage/grouping-content.html#the-ol-element

[html-p]: https://html.spec.whatwg.org/multipage/grouping-content.html#the-p-element

[html-section]: https://html.spec.whatwg.org/multipage/sections.html#the-section-element

[html-sup]: https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-sub-and-sup-elements

[aria-describedby]: https://w3c.github.io/aria/#aria-describedby

[aria-label]: https://w3c.github.io/aria/#aria-label

[api-gfm-footnote]: #gfmfootnote

[api-gfm-footnote-html]: #gfmfootnotehtmloptions

[api-html-options]: #htmloptions

[api-default-back-label]: #defaultbacklabelreferenceindex-rereferenceindex

[api-back-label-template]: #backlabeltemplate


---

# micromark-util-symbol

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility with symbols.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes constants used throughout the micromark ecosystem.

## When should I use this?

This package is useful when you are making your own micromark extensions.
It’s useful to reference these constants by name instead of value while
developing.
[`micromark-build`][micromark-build] compiles them away for production code.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-symbol
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as symbol from 'https://esm.sh/micromark-util-symbol@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as symbol from 'https://esm.sh/micromark-util-symbol@1?bundle'
</script>
```

## Use

```js
import {codes, constants, types, values} from 'micromark-util-symbol'

console.log(codes.atSign) // 64
console.log(constants.characterReferenceNamedSizeMax) // 31
console.log(types.definitionDestinationRaw) // 'definitionDestinationRaw'
console.log(values.atSign) // '@'
```

## API

This package exports the identifiers `codes`, `constants`, `types`, and
`values`.
There is no default export.

Each identifier is an object mapping strings to values.
See the code for the exposed data.

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-symbol@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-symbol.svg

[downloads]: https://www.npmjs.com/package/micromark-util-symbol

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-symbol

[bundle-size]: https://bundlejs.com/?q=micromark-util-symbol

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[micromark-build]: https://github.com/micromark/micromark/tree/main/packages/micromark-build


---

# micromark-extension-gfm-strikethrough

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[micromark][] extensions to support GFM [strikethrough][].

## Contents

* [What is this?](#what-is-this)
* [When to use this](#when-to-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`gfmStrikethrough(options?)`](#gfmstrikethroughoptions)
  * [`gfmStrikethroughHtml()`](#gfmstrikethroughhtml)
  * [`Options`](#options)
* [Authoring](#authoring)
* [HTML](#html)
* [CSS](#css)
* [Syntax](#syntax)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Related](#related)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package contains extensions that add support for strikethrough as enabled
by GFM to [`micromark`][micromark].

## When to use this

This project is useful when you want to support strikethrough in markdown.

You can use these extensions when you are working with [`micromark`][micromark].
To support all GFM features, use
[`micromark-extension-gfm`][micromark-extension-gfm].

When you need a syntax tree, you can combine this package with
[`mdast-util-gfm-strikethrough`][mdast-util-gfm-strikethrough].

All these packages are used [`remark-gfm`][remark-gfm], which focusses on making
it easier to transform content by abstracting these internals away.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-extension-gfm-strikethrough
```

In Deno with [`esm.sh`][esmsh]:

```js
import {gfmStrikethrough, gfmStrikethroughHtml} from 'https://esm.sh/micromark-extension-gfm-strikethrough@2'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {gfmStrikethrough, gfmStrikethroughHtml} from 'https://esm.sh/micromark-extension-gfm-strikethrough@2?bundle'
</script>
```

## Use

```js
import {micromark} from 'micromark'
import {
  gfmStrikethrough,
  gfmStrikethroughHtml
} from 'micromark-extension-gfm-strikethrough'

const output = micromark('Some ~strikethrough~.', {
  extensions: [gfmStrikethrough()],
  htmlExtensions: [gfmStrikethroughHtml()]
})

console.log(output)
```

Yields:

```html
<p>Some <del>strikethrough</del></p>.
```

## API

This package exports the identifiers
[`gfmStrikethrough`][api-gfm-strikethrough] and
[`gfmStrikethroughHtml`][api-gfm-strikethrough-html].
There is no default export.

The export map supports the [`development` condition][development].
Run `node --conditions development module.js` to get instrumented dev code.
Without this condition, production code is loaded.

### `gfmStrikethrough(options?)`

Create an extension for `micromark` to enable GFM strikethrough syntax.

###### Parameters

* `options` ([`Options`][api-options], optional)
  — configuration

###### Returns

Extension for `micromark` that can be passed in `extensions`, to
enable GFM strikethrough syntax ([`Extension`][micromark-extension]).

### `gfmStrikethroughHtml()`

Create an HTML extension for `micromark` to support GFM strikethrough when
serializing to HTML.

###### Returns

Extension for `micromark` that can be passed in `htmlExtensions`, to support
GFM strikethrough when serializing to HTML
([`HtmlExtension`][micromark-html-extension]).

### `Options`

Configuration (TypeScript type).

###### Fields

* `singleTilde` (`boolean`, default: `true`)
  — whether to support strikethrough with a single tilde.
  Single tildes work on github.com, but are technically prohibited by the GFM
  spec

## Authoring

When authoring markdown with strikethrough, it is recommended to use two
markers.
While `github.com` allows single tildes too, it technically prohibits it in
their spec.

## HTML

When tilde sequences match, they together relate to the `<del>` element in
HTML.
See [*§ 4.7.2 The `del` element*][html-del] in the HTML spec for more info.

## CSS

GitHub itself does not apply interesting CSS to `del` elements.
It currently (July 2022) does change `code` in `del`.

```css
del code {
  text-decoration: inherit;
}
```

For the complete actual CSS see
[`sindresorhus/github-markdown-css`][github-markdown-css].

## Syntax

Strikethrough sequences form with the following BNF:

```bnf
gfm_attention_sequence ::= 1*'~'
```

Sequences are matched together to form strikethrough based on which character
they contain, how long they are, and what character occurs before and after
each sequence.
Otherwise they are turned into data.

## Types

This package is fully typed with [TypeScript][].
It exports the additional type [`Options`][api-options].

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-extension-gfm-strikethrough@^2`, compatible with Node.js 16.

This package works with `micromark` version `3` and later.

## Security

This package is safe.

## Related

* [`micromark-extension-gfm`][micromark-extension-gfm]
  — support all of GFM
* [`mdast-util-gfm-strikethrough`][mdast-util-gfm-strikethrough]
  — support all of GFM in mdast
* [`mdast-util-gfm`][mdast-util-gfm]
  — support all of GFM in mdast
* [`remark-gfm`][remark-gfm]
  — support all of GFM in remark

## Contribute

See [`contributing.md` in `micromark/.github`][contributing] for ways to get
started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark-extension-gfm-strikethrough/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark-extension-gfm-strikethrough/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark-extension-gfm-strikethrough.svg

[coverage]: https://codecov.io/github/micromark/micromark-extension-gfm-strikethrough

[downloads-badge]: https://img.shields.io/npm/dm/micromark-extension-gfm-strikethrough.svg

[downloads]: https://www.npmjs.com/package/micromark-extension-gfm-strikethrough

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-extension-gfm-strikethrough

[size]: https://bundlejs.com/?q=micromark-extension-gfm-strikethrough

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[npm]: https://docs.npmjs.com/cli/install

[esmsh]: https://esm.sh

[license]: license

[author]: https://wooorm.com

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[typescript]: https://www.typescriptlang.org

[development]: https://nodejs.org/api/packages.html#packages_resolving_user_conditions

[micromark]: https://github.com/micromark/micromark

[micromark-html-extension]: https://github.com/micromark/micromark#htmlextension

[micromark-extension]: https://github.com/micromark/micromark#syntaxextension

[micromark-extension-gfm]: https://github.com/micromark/micromark-extension-gfm

[mdast-util-gfm-strikethrough]: https://github.com/syntax-tree/mdast-util-gfm-strikethrough

[mdast-util-gfm]: https://github.com/syntax-tree/mdast-util-gfm

[remark-gfm]: https://github.com/remarkjs/remark-gfm

[strikethrough]: https://github.github.com/gfm/#strikethrough-extension-

[github-markdown-css]: https://github.com/sindresorhus/github-markdown-css

[html-del]: https://html.spec.whatwg.org/multipage/edits.html#the-del-element

[api-gfm-strikethrough]: #gfmstrikethroughoptions

[api-gfm-strikethrough-html]: #gfmstrikethroughhtml

[api-options]: #options


---

# micromark-factory-space

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] factory to parse [markdown space][markdown-space] (found in lots
of places).

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`factorySpace(…)`](#factoryspace)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes states to parse spaces and/or tabs.

## When should I use this?

This package is useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-factory-space
```

In Deno with [`esm.sh`][esmsh]:

```js
import {factorySpace} from 'https://esm.sh/micromark-factory-space@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {factorySpace} from 'https://esm.sh/micromark-factory-space@1?bundle'
</script>
```

## Use

```js
import {factorySpace} from 'micromark-factory-space'
import {codes, types} from 'micromark-util-symbol'

// A micromark tokenizer that uses the factory:
/**
 * @this {TokenizeContext}
 *   Context.
 * @type {Tokenizer}
 */
function tokenizeCodeFenced(effects, ok, nok) {
  return start

  // …

  /** @type {State} */
  function info(code) {
    if (code === codes.eof || markdownLineEndingOrSpace(code)) {
      effects.exit(types.chunkString)
      effects.exit(types.codeFencedFenceInfo)
      return factorySpace(effects, infoAfter, types.whitespace)(code)
    }

    if (code === codes.graveAccent && code === marker) return nok(code)
    effects.consume(code)
    return info
  }

  // …
}
```

## API

This module exports the identifier [`factorySpace`][api-factory-space].
There is no default export.

### `factorySpace(…)`

Parse spaces and tabs.

There is no `nok` parameter:

* spaces in markdown are often optional, in which case this factory can be
  used and `ok` will be switched to whether spaces were found or not
* one line ending or space can be detected with `markdownSpace(code)` right
  before using `factorySpace`

###### Examples

Where `␉` represents a tab (plus how much it expands) and `␠` represents a
single space.

```markdown
␉
␠␠␠␠
␉␠
```

###### Parameters

* `effects` (`Effects`)
  — context
* `ok` (`State`)
  — state switched to when successful
* `type` (`string`)
  — type (`' \t'`)
* `max` (`number`, default: `Infinity`)
  — max (exclusive)

###### Returns

Start state (`State`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-factory-space@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-factory-space.svg

[downloads]: https://www.npmjs.com/package/micromark-factory-space

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-factory-space

[bundle-size]: https://bundlejs.com/?q=micromark-factory-space

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[markdown-space]: https://github.com/micromark/micromark/tree/main/packages/micromark-util-character#markdownspacecode

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[api-factory-space]: #factoryspace


---

# micromark-util-character

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility to handle [character codes][code].

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`asciiAlpha(code)`](#asciialphacode)
  * [`asciiAlphanumeric(code)`](#asciialphanumericcode)
  * [`asciiAtext(code)`](#asciiatextcode)
  * [`asciiControl(code)`](#asciicontrolcode)
  * [`asciiDigit(code)`](#asciidigitcode)
  * [`asciiHexDigit(code)`](#asciihexdigitcode)
  * [`asciiPunctuation(code)`](#asciipunctuationcode)
  * [`markdownLineEnding(code)`](#markdownlineendingcode)
  * [`markdownLineEndingOrSpace(code)`](#markdownlineendingorspacecode)
  * [`markdownSpace(code)`](#markdownspacecode)
  * [`unicodePunctuation(code)`](#unicodepunctuationcode)
  * [`unicodeWhitespace(code)`](#unicodewhitespacecode)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes algorithms to check whether characters match groups.

## When should I use this?

This package might be useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-character
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as character from 'https://esm.sh/micromark-util-character@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as character from 'https://esm.sh/micromark-util-character@1?bundle'
</script>
```

## Use

```js
import {asciiAlpha} from 'micromark-util-character'

console.log(asciiAlpha(64)) // false
console.log(asciiAlpha(65)) // true
```

## API

This module exports the identifiers
[`asciiAlpha`][api-ascii-alpha],
[`asciiAlphanumeric`][api-ascii-alphanumeric],
[`asciiAtext`][api-ascii-atext],
[`asciiControl`][api-ascii-control],
[`asciiDigit`][api-ascii-digit],
[`asciiHexDigit`][api-ascii-hex-digit],
[`asciiPunctuation`][api-ascii-punctuation],
[`markdownLineEnding`][api-markdown-line-ending],
[`markdownLineEndingOrSpace`][api-markdown-line-ending-or-space],
[`markdownSpace`][api-markdown-space],
[`unicodePunctuation`][api-unicode-punctuation],
[`unicodeWhitespace`][api-unicode-whitespace].
There is no default export.

### `asciiAlpha(code)`

Check whether the [character code][code] represents an ASCII alpha (`a` through
`z`, case insensitive).

An **ASCII alpha** is an ASCII upper alpha or ASCII lower alpha.

An **ASCII upper alpha** is a character in the inclusive range U+0041 (`A`)
to U+005A (`Z`).

An **ASCII lower alpha** is a character in the inclusive range U+0061 (`a`)
to U+007A (`z`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiAlphanumeric(code)`

Check whether the [character code][code] represents an ASCII alphanumeric (`a`
through `z`, case insensitive, or `0` through `9`).

An **ASCII alphanumeric** is an ASCII digit (see `asciiDigit`) or ASCII alpha
(see `asciiAlpha`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiAtext(code)`

Check whether the [character code][code] represents an ASCII atext.

atext is an ASCII alphanumeric (see `asciiAlphanumeric`), or a character in
the inclusive ranges U+0023 NUMBER SIGN (`#`) to U+0027 APOSTROPHE (`'`),
U+002A ASTERISK (`*`), U+002B PLUS SIGN (`+`), U+002D DASH (`-`), U+002F
SLASH (`/`), U+003D EQUALS TO (`=`), U+003F QUESTION MARK (`?`), U+005E
CARET (`^`) to U+0060 GRAVE ACCENT (`` ` ``), or U+007B LEFT CURLY BRACE
(`{`) to U+007E TILDE (`~`) (**\[RFC5322]**).

See **\[RFC5322]**:\
[Internet Message Format](https://tools.ietf.org/html/rfc5322).\
P. Resnick.\
IETF.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiControl(code)`

Check whether a [character code][code] is an ASCII control character.

An **ASCII control** is a character in the inclusive range U+0000 NULL (NUL)
to U+001F (US), or U+007F (DEL).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiDigit(code)`

Check whether the [character code][code] represents an ASCII digit (`0` through
`9`).

An **ASCII digit** is a character in the inclusive range U+0030 (`0`) to
U+0039 (`9`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiHexDigit(code)`

Check whether the [character code][code] represents an ASCII hex digit (`a`
through `f`, case insensitive, or `0` through `9`).

An **ASCII hex digit** is an ASCII digit (see `asciiDigit`), ASCII upper hex
digit, or an ASCII lower hex digit.

An **ASCII upper hex digit** is a character in the inclusive range U+0041
(`A`) to U+0046 (`F`).

An **ASCII lower hex digit** is a character in the inclusive range U+0061
(`a`) to U+0066 (`f`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiPunctuation(code)`

Check whether the [character code][code] represents ASCII punctuation.

An **ASCII punctuation** is a character in the inclusive ranges U+0021
EXCLAMATION MARK (`!`) to U+002F SLASH (`/`), U+003A COLON (`:`) to U+0040 AT
SIGN (`@`), U+005B LEFT SQUARE BRACKET (`[`) to U+0060 GRAVE ACCENT
(`` ` ``), or U+007B LEFT CURLY BRACE (`{`) to U+007E TILDE (`~`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownLineEnding(code)`

Check whether a [character code][code] is a markdown line ending.

A **markdown line ending** is the virtual characters M-0003 CARRIAGE RETURN
LINE FEED (CRLF), M-0004 LINE FEED (LF) and M-0005 CARRIAGE RETURN (CR).

In micromark, the actual character U+000A LINE FEED (LF) and U+000D CARRIAGE
RETURN (CR) are replaced by these virtual characters depending on whether
they occurred together.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownLineEndingOrSpace(code)`

Check whether a [character code][code] is a markdown line ending (see
`markdownLineEnding`) or markdown space (see `markdownSpace`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownSpace(code)`

Check whether a [character code][code] is a markdown space.

A **markdown space** is the concrete character U+0020 SPACE (SP) and the
virtual characters M-0001 VIRTUAL SPACE (VS) and M-0002 HORIZONTAL TAB (HT).

In micromark, the actual character U+0009 CHARACTER TABULATION (HT) is
replaced by one M-0002 HORIZONTAL TAB (HT) and between 0 and 3 M-0001 VIRTUAL
SPACE (VS) characters, depending on the column at which the tab occurred.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `unicodePunctuation(code)`

Check whether the [character code][code] represents Unicode punctuation.

A **Unicode punctuation** is a character in the Unicode `Pc` (Punctuation,
Connector), `Pd` (Punctuation, Dash), `Pe` (Punctuation, Close), `Pf`
(Punctuation, Final quote), `Pi` (Punctuation, Initial quote), `Po`
(Punctuation, Other), or `Ps` (Punctuation, Open) categories, or an ASCII
punctuation (see `asciiPunctuation`) (**\[UNICODE]**).

See **\[UNICODE]**:\
[The Unicode Standard](https://www.unicode.org/versions/).\
Unicode Consortium.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `unicodeWhitespace(code)`

Check whether the [character code][code] represents Unicode whitespace.

Note that this does handle micromark specific markdown whitespace characters.
See `markdownLineEndingOrSpace` to check that.

A **Unicode whitespace** is a character in the Unicode `Zs` (Separator,
Space) category, or U+0009 CHARACTER TABULATION (HT), U+000A LINE FEED (LF),
U+000C (FF), or U+000D CARRIAGE RETURN (CR) (**\[UNICODE]**).

See **\[UNICODE]**:\
[The Unicode Standard](https://www.unicode.org/versions/).\
Unicode Consortium.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-character@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-character.svg

[downloads]: https://www.npmjs.com/package/micromark-util-character

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-character

[bundle-size]: https://bundlejs.com/?q=micromark-util-character

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[code]: https://github.com/micromark/micromark#preprocess

[api-ascii-alpha]: #asciialphacode

[api-ascii-alphanumeric]: #asciialphanumericcode

[api-ascii-atext]: #asciiatextcode

[api-ascii-control]: #asciicontrolcode

[api-ascii-digit]: #asciidigitcode

[api-ascii-hex-digit]: #asciihexdigitcode

[api-ascii-punctuation]: #asciipunctuationcode

[api-markdown-line-ending]: #markdownlineendingcode

[api-markdown-line-ending-or-space]: #markdownlineendingorspacecode

[api-markdown-space]: #markdownspacecode

[api-unicode-punctuation]: #unicodepunctuationcode

[api-unicode-whitespace]: #unicodewhitespacecode


---

# micromark-util-symbol

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility with symbols.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes constants used throughout the micromark ecosystem.

## When should I use this?

This package is useful when you are making your own micromark extensions.
It’s useful to reference these constants by name instead of value while
developing.
[`micromark-build`][micromark-build] compiles them away for production code.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-symbol
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as symbol from 'https://esm.sh/micromark-util-symbol@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as symbol from 'https://esm.sh/micromark-util-symbol@1?bundle'
</script>
```

## Use

```js
import {codes, constants, types, values} from 'micromark-util-symbol'

console.log(codes.atSign) // 64
console.log(constants.characterReferenceNamedSizeMax) // 31
console.log(types.definitionDestinationRaw) // 'definitionDestinationRaw'
console.log(values.atSign) // '@'
```

## API

This package exports the identifiers `codes`, `constants`, `types`, and
`values`.
There is no default export.

Each identifier is an object mapping strings to values.
See the code for the exposed data.

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-symbol@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-symbol.svg

[downloads]: https://www.npmjs.com/package/micromark-util-symbol

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-symbol

[bundle-size]: https://bundlejs.com/?q=micromark-util-symbol

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[micromark-build]: https://github.com/micromark/micromark/tree/main/packages/micromark-build


---

# micromark-extension-gfm-table

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[micromark][] extensions to support GFM [tables][].

## Contents

* [What is this?](#what-is-this)
* [When to use this](#when-to-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`gfmTable()`](#gfmtable)
  * [`gfmTableHtml()`](#gfmtablehtml)
* [Bugs](#bugs)
* [Authoring](#authoring)
* [HTML](#html)
* [CSS](#css)
* [Syntax](#syntax)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Related](#related)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package contains extensions that add support for the table syntax enabled
by GFM to [`micromark`][micromark].
These extensions match github.com.

## When to use this

This project is useful when you want to support tables in markdown.

You can use these extensions when you are working with [`micromark`][micromark].
To support all GFM features, use
[`micromark-extension-gfm`][micromark-extension-gfm] instead.

When you need a syntax tree, combine this package with
[`mdast-util-gfm-table`][mdast-util-gfm-table].

All these packages are used in [`remark-gfm`][remark-gfm], which focusses on
making it easier to transform content by abstracting these internals away.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-extension-gfm-table
```

In Deno with [`esm.sh`][esmsh]:

```js
import {gfmTable, gfmTableHtml} from 'https://esm.sh/micromark-extension-gfm-table@2'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {gfmTable, gfmTableHtml} from 'https://esm.sh/micromark-extension-gfm-table@2?bundle'
</script>
```

## Use

```js
import {micromark} from 'micromark'
import {gfmTable, gfmTableHtml} from 'micromark-extension-gfm-table'

const output = micromark('| a |\n| - |', {
  extensions: [gfmTable()],
  htmlExtensions: [gfmTableHtml()]
})

console.log(output)
```

Yields:

```html
<table>
<thead>
<tr>
<th>a</th>
</tr>
</thead>
</table>
```

## API

This package exports the identifiers [`gfmTable`][api-gfm-table] and
[`gfmTableHtml`][api-gfm-table-html].
There is no default export.

The export map supports the [`development` condition][development].
Run `node --conditions development module.js` to get instrumented dev code.
Without this condition, production code is loaded.

### `gfmTable()`

Create an HTML extension for `micromark` to support GitHub tables syntax.

###### Returns

Extension for `micromark` that can be passed in `extensions` to enable GFM
table syntax ([`Extension`][micromark-extension]).

### `gfmTableHtml()`

Create an HTML extension for `micromark` to support GitHub tables when
serializing to HTML.

###### Returns

Extension for `micromark` that can be passed in `htmlExtensions` to support
GFM tables when serializing to HTML
([`HtmlExtension`][micromark-html-extension]).

## Bugs

GitHub’s own algorithm to parse tables contains a bug.
This bug is not present in this project.
The issue relating to tables is:

* [GFM tables: escaped escapes are incorrectly treated as
  escapes](https://github.com/github/cmark-gfm/issues/277)

## Authoring

When authoring markdown with GFM tables, it’s recommended to *always* put
pipes around cells.
Without them, it can be hard to infer whether the table will work, how many
columns there are, and which column you are currently editing.

It is recommended to not use many columns, as it results in very long lines,
making it hard to infer which column you are currently editing.

For larger tables, particularly when cells vary in size, it is recommended
*not* to manually “pad” cell text.
While it can look better, it results in a lot of time spent realigning
everything when a new, longer cell is added or the longest cell removed, as
every row then must be changed.
Other than costing time, it also causes large diffs in Git.

To illustrate, when authoring large tables, it is discouraged to pad cells
like this:

```markdown
| Alpha bravo charlie |              delta |
| ------------------- | -----------------: |
| Echo                | Foxtrot golf hotel |
```

Instead, use single spaces (and single filler dashes):

```markdown
| Alpha bravo charlie | delta |
| - | -: |
| Echo | Foxtrot golf hotel |
```

## HTML

GFM tables relate to several HTML elements: `<table>`, `<tbody>`, `<td>`,
`<th>`, `<thead>`, and `<tr>`.
See
[*§ 4.9.1 The `table` element*][html-table],
[*§ 4.9.5 The `tbody` element*][html-tbody],
[*§ 4.9.9 The `td` element*][html-td],
[*§ 4.9.10 The `th` element*][html-th],
[*§ 4.9.6 The `thead` element*][html-thead], and
[*§ 4.9.8 The `tr` element*][html-tr]
in the HTML spec for more info.

If the alignment of a column is left, right, or center, a deprecated
`align` attribute is added to each `<th>` and `<td>` element belonging to
that column.
That attribute is interpreted by browsers as if a CSS `text-align` property
was included, with its value set to that same keyword.

## CSS

The following CSS is needed to make tables look a bit like GitHub.
For the complete actual CSS see
[`sindresorhus/github-markdown-css`][github-markdown-css]

```css
/* Light theme. */
:root {
  --color-canvas-default: #ffffff;
  --color-canvas-subtle: #f6f8fa;
  --color-border-default: #d0d7de;
  --color-border-muted: hsla(210, 18%, 87%, 1);
}

/* Dark theme. */
@media (prefers-color-scheme: dark) {
  :root {
    --color-canvas-default: #0d1117;
    --color-canvas-subtle: #161b22;
    --color-border-default: #30363d;
    --color-border-muted: #21262d;
  }
}

table {
  border-spacing: 0;
  border-collapse: collapse;
  display: block;
  margin-top: 0;
  margin-bottom: 16px;
  width: max-content;
  max-width: 100%;
  overflow: auto;
}

tr {
  background-color: var(--color-canvas-default);
  border-top: 1px solid var(--color-border-muted);
}

tr:nth-child(2n) {
  background-color: var(--color-canvas-subtle);
}

td,
th {
  padding: 6px 13px;
  border: 1px solid var(--color-border-default);
}

th {
  font-weight: 600;
}

table img {
  background-color: transparent;
}
```

## Syntax

Tables form with the following BNF:

```abnf
gfmTable ::= gfmTableHead 0*(eol gfmTableBodyRow)

; Restriction: both rows must have the same number of cells.
gfmTableHead ::= gfmTableRow eol gfmTableDelimiterRow

gfmTableRow ::= ["|"] gfmTableCell 0*("|" gfmTableCell) ["|"] *spaceOrTab
gfmTableCell ::= *spaceOrTab gfmTableText *spaceOrTab
gfmTableText ::= 0*(line - "\\" - "|" / "\\" ["\\" / "|"])

gfmTableDelimiterRow ::= ["|"] gfmTableDelimiterCell 0*("|" gfmTableDelimiterCell) ["|"] *spaceOrTab
gfmTableDelimiterCell ::= *spaceOrTab gfmTableDelimiterValue *spaceOrTab
gfmTableDelimiterValue ::= [":"] 1*"-" [":"]
```

As this construct occurs in flow, like all flow constructs, it must be
followed by an eol (line ending) or eof (end of file).

The above grammar shows that basically anything can be a cell or a row.
The main thing that makes something a row, is that it occurs directly before
or after a delimiter row, or after another row.

It is not required for a table to have a body: it can end right after the
delimiter row.

Each column can be marked with an alignment.
The alignment marker is a colon (`:`) used before and/or after delimiter row
filler.
To illustrate:

```markdown
| none | left | right | center |
| ---- | :--- | ----: | :----: |
```

The number of cells in the delimiter row, is the number of columns of the
table.
Only the head row is required to have the same number of cells.
Body rows are not required to have a certain number of cells.
For body rows that have less cells than the number of columns of the table,
empty cells are injected.
When a row has more cells than the number of columns of the table, the
superfluous cells are dropped.
To illustrate:

```markdown
| a | b |
| - | - |
| c |
| d | e | f |
```

Yields:

```html
<table>
<thead>
<tr>
<th>a</th>
<th>b</th>
</tr>
</thead>
<tbody>
<tr>
<td>c</td>
<td></td>
</tr>
<tr>
<td>d</td>
<td>e</td>
</tr>
</tbody>
</table>
```

Each cell’s text is interpreted as the [text][micromark-content-type] content
type.
That means that it can include constructs such as attention (emphasis, strong).

The grammar for cells prohibits the use of `|` in them.
To use pipes in cells, encode them as a character reference or character
escape: `&vert;` (or `&VerticalLine;`, `&verbar;`, `&#124;`, `&#x7c;`) or
`\|`.

Escapes will typically work, but they are not supported in
code (text) (and the math (text) extension).
To work around this, GitHub came up with a rather weird “trick”.
When inside a table cell *and* inside code, escaped pipes *are* decoded.
To illustrate:

```markdown
| Name | Character |
| - | - |
| Left curly brace | `{` |
| Pipe | `\|` |
| Right curly brace | `}` |
```

Yields:

```html
<table>
<thead>
<tr>
<th>Name</th>
<th>Character</th>
</tr>
</thead>
<tbody>
<tr>
<td>Left curly brace</td>
<td><code>{</code></td>
</tr>
<tr>
<td>Pipe</td>
<td><code>|</code></td>
</tr>
<tr>
<td>Right curly brace</td>
<td><code>}</code></td>
</tr>
</tbody>
</table>
```

> 👉 **Note**: no other character can be escaped like this.
> Escaping pipes in code does not work when not inside a table, either.

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-extension-gfm-table@^2`, compatible with Node.js 16.

This package works with `micromark` version `3` and later.

## Security

This package is safe.

## Related

* [`micromark-extension-gfm`][micromark-extension-gfm]
  — support all of GFM
* [`mdast-util-gfm-table`][mdast-util-gfm-table]
  — support all of GFM in mdast
* [`mdast-util-gfm`][mdast-util-gfm]
  — support all of GFM in mdast
* [`remark-gfm`][remark-gfm]
  — support all of GFM in remark

## Contribute

See [`contributing.md` in `micromark/.github`][contributing] for ways to get
started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark-extension-gfm-table/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark-extension-gfm-table/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark-extension-gfm-table.svg

[coverage]: https://codecov.io/github/micromark/micromark-extension-gfm-table

[downloads-badge]: https://img.shields.io/npm/dm/micromark-extension-gfm-table.svg

[downloads]: https://www.npmjs.com/package/micromark-extension-gfm-table

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-extension-gfm-table

[size]: https://bundlejs.com/?q=micromark-extension-gfm-table

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[npm]: https://docs.npmjs.com/cli/install

[esmsh]: https://esm.sh

[license]: license

[author]: https://wooorm.com

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[typescript]: https://www.typescriptlang.org

[development]: https://nodejs.org/api/packages.html#packages_resolving_user_conditions

[micromark]: https://github.com/micromark/micromark

[micromark-extension]: https://github.com/micromark/micromark#syntaxextension

[micromark-html-extension]: https://github.com/micromark/micromark#htmlextension

[micromark-content-type]: https://github.com/micromark/micromark#content-types

[micromark-extension-gfm]: https://github.com/micromark/micromark-extension-gfm

[mdast-util-gfm]: https://github.com/syntax-tree/mdast-util-gfm

[mdast-util-gfm-table]: https://github.com/syntax-tree/mdast-util-gfm-table

[remark-gfm]: https://github.com/remarkjs/remark-gfm

[tables]: https://github.github.com/gfm/#tables-extension-

[html-table]: https://html.spec.whatwg.org/multipage/tables.html#the-table-element

[html-tbody]: https://html.spec.whatwg.org/multipage/tables.html#the-tbody-element

[html-thead]: https://html.spec.whatwg.org/multipage/tables.html#the-thead-element

[html-tr]: https://html.spec.whatwg.org/multipage/tables.html#the-tr-element

[html-td]: https://html.spec.whatwg.org/multipage/tables.html#the-td-element

[html-th]: https://html.spec.whatwg.org/multipage/tables.html#the-th-element

[github-markdown-css]: https://github.com/sindresorhus/github-markdown-css

[api-gfm-table]: #gfmtable

[api-gfm-table-html]: #gfmtablehtml


---

# micromark-extension-gfm-tagfilter

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[micromark][] extension to support GFM [tag filter][].

## Contents

*   [What is this?](#what-is-this)
*   [When to use this](#when-to-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`gfmTagfilterHtml()`](#gfmtagfilterhtml)
*   [Authoring](#authoring)
*   [HTML](#html)
*   [CSS](#css)
*   [Syntax](#syntax)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Security](#security)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package contains an extension that adds support for the tagfilter enabled
by GFM to [`micromark`][micromark].
The tagfilter is kinda weird and kinda useless.
This package exists for completeness.
The tag filter is a naïve attempt at XSS protection.
You should use a proper HTML sanitizing algorithm.

## When to use this

This project is useful when you want to match how GitHub works.
You can use this extension when you are working with [`micromark`][micromark]
already.
When you do, you can instead use
[`micromark-extension-gfm`][micromark-extension-gfm], which includes this
extension, to support all GFM features.

When you want to deal with syntax trees, you should instead use
[`hast-util-sanitize`][hast-util-sanitize].

When you use remark and rehype, you should use
[`rehype-sanitize`][rehype-sanitize].

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-extension-gfm-tagfilter
```

In Deno with [`esm.sh`][esmsh]:

```js
import {gfmTagfilterHtml} from 'https://esm.sh/micromark-extension-gfm-tagfilter@2'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {gfmTagfilterHtml} from 'https://esm.sh/micromark-extension-gfm-tagfilter@2?bundle'
</script>
```

## Use

```js
import {micromark} from 'micromark'
import {gfmTagfilterHtml} from 'micromark-extension-gfm-tagfilter'

const output = micromark('XSS! <script>alert(1)</script>', {
  allowDangerousHtml: true,
  htmlExtensions: [gfmTagfilterHtml()]
})

console.log(output)
```

Yields:

```html
<p>XSS! &lt;script>alert(1)&lt;/script></p>
```

## API

This package exports the identifier
[`gfmTagfilterHtml`][api-gfm-tagfilter-html].
There is no default export.

### `gfmTagfilterHtml()`

Create an HTML extension for `micromark` to support GitHubs weird and
useless tagfilter when serializing to HTML.

###### Returns

Extension for `micromark` that can be passed in `htmlExtensions` to support
GitHubs weird and useless tagfilter when serializing to HTML
([`HtmlExtension`][micromark-html-extension]).

## Authoring

This package relates to malicious authors, not decent authors.

## HTML

GFM tagfilter removes certain dangerous HTML tags: `iframe`, `noembed`,
`noframes`, `plaintext`, `script`, `style`, `title`, `textarea`, and `xmp`.

## CSS

This package does not relate to CSS.

## Syntax

This package does not change how markdown is parsed.

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-extension-gfm-tagfilter@^2`, compatible with Node.js 16.

This package works with `micromark` version `3` and later.

## Security

While micromark is safe by default, this extension only does something when
`allowDangerousHtml: true` is passed, which is an unsafe option.
This package is **not safe**.

## Related

*   [`micromark-extension-gfm`][micromark-extension-gfm]
    — support all of GFM
*   [`hast-util-sanitize`][hast-util-sanitize]
    — hast utility to make trees safe
*   [`rehype-sanitize`][rehype-sanitize]
    — rehype plugin to sanitize HTML

## Contribute

See [`contributing.md` in `micromark/.github`][contributing] for ways to get
started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark-extension-gfm-tagfilter/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark-extension-gfm-tagfilter/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark-extension-gfm-tagfilter.svg

[coverage]: https://codecov.io/github/micromark/micromark-extension-gfm-tagfilter

[downloads-badge]: https://img.shields.io/npm/dm/micromark-extension-gfm-tagfilter.svg

[downloads]: https://www.npmjs.com/package/micromark-extension-gfm-tagfilter

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-extension-gfm-tagfilter

[size]: https://bundlejs.com/?q=micromark-extension-gfm-tagfilter

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[npm]: https://docs.npmjs.com/cli/install

[esmsh]: https://esm.sh

[license]: license

[author]: https://wooorm.com

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[micromark-html-extension]: https://github.com/micromark/micromark#htmlextension

[micromark-extension-gfm]: https://github.com/micromark/micromark-extension-gfm

[rehype-sanitize]: https://github.com/rehypejs/rehype-sanitize

[hast-util-sanitize]: https://github.com/syntax-tree/hast-util-sanitize

[tag filter]: https://github.github.com/gfm/#disallowed-raw-html-extension-

[api-gfm-tagfilter-html]: #gfmtagfilterhtml


---

# micromark-factory-space

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] factory to parse [markdown space][markdown-space] (found in lots
of places).

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`factorySpace(…)`](#factoryspace)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes states to parse spaces and/or tabs.

## When should I use this?

This package is useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-factory-space
```

In Deno with [`esm.sh`][esmsh]:

```js
import {factorySpace} from 'https://esm.sh/micromark-factory-space@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {factorySpace} from 'https://esm.sh/micromark-factory-space@1?bundle'
</script>
```

## Use

```js
import {factorySpace} from 'micromark-factory-space'
import {codes, types} from 'micromark-util-symbol'

// A micromark tokenizer that uses the factory:
/**
 * @this {TokenizeContext}
 *   Context.
 * @type {Tokenizer}
 */
function tokenizeCodeFenced(effects, ok, nok) {
  return start

  // …

  /** @type {State} */
  function info(code) {
    if (code === codes.eof || markdownLineEndingOrSpace(code)) {
      effects.exit(types.chunkString)
      effects.exit(types.codeFencedFenceInfo)
      return factorySpace(effects, infoAfter, types.whitespace)(code)
    }

    if (code === codes.graveAccent && code === marker) return nok(code)
    effects.consume(code)
    return info
  }

  // …
}
```

## API

This module exports the identifier [`factorySpace`][api-factory-space].
There is no default export.

### `factorySpace(…)`

Parse spaces and tabs.

There is no `nok` parameter:

* spaces in markdown are often optional, in which case this factory can be
  used and `ok` will be switched to whether spaces were found or not
* one line ending or space can be detected with `markdownSpace(code)` right
  before using `factorySpace`

###### Examples

Where `␉` represents a tab (plus how much it expands) and `␠` represents a
single space.

```markdown
␉
␠␠␠␠
␉␠
```

###### Parameters

* `effects` (`Effects`)
  — context
* `ok` (`State`)
  — state switched to when successful
* `type` (`string`)
  — type (`' \t'`)
* `max` (`number`, default: `Infinity`)
  — max (exclusive)

###### Returns

Start state (`State`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-factory-space@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-factory-space.svg

[downloads]: https://www.npmjs.com/package/micromark-factory-space

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-factory-space

[bundle-size]: https://bundlejs.com/?q=micromark-factory-space

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[markdown-space]: https://github.com/micromark/micromark/tree/main/packages/micromark-util-character#markdownspacecode

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[api-factory-space]: #factoryspace


---

# micromark-util-character

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility to handle [character codes][code].

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`asciiAlpha(code)`](#asciialphacode)
  * [`asciiAlphanumeric(code)`](#asciialphanumericcode)
  * [`asciiAtext(code)`](#asciiatextcode)
  * [`asciiControl(code)`](#asciicontrolcode)
  * [`asciiDigit(code)`](#asciidigitcode)
  * [`asciiHexDigit(code)`](#asciihexdigitcode)
  * [`asciiPunctuation(code)`](#asciipunctuationcode)
  * [`markdownLineEnding(code)`](#markdownlineendingcode)
  * [`markdownLineEndingOrSpace(code)`](#markdownlineendingorspacecode)
  * [`markdownSpace(code)`](#markdownspacecode)
  * [`unicodePunctuation(code)`](#unicodepunctuationcode)
  * [`unicodeWhitespace(code)`](#unicodewhitespacecode)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes algorithms to check whether characters match groups.

## When should I use this?

This package might be useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-character
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as character from 'https://esm.sh/micromark-util-character@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as character from 'https://esm.sh/micromark-util-character@1?bundle'
</script>
```

## Use

```js
import {asciiAlpha} from 'micromark-util-character'

console.log(asciiAlpha(64)) // false
console.log(asciiAlpha(65)) // true
```

## API

This module exports the identifiers
[`asciiAlpha`][api-ascii-alpha],
[`asciiAlphanumeric`][api-ascii-alphanumeric],
[`asciiAtext`][api-ascii-atext],
[`asciiControl`][api-ascii-control],
[`asciiDigit`][api-ascii-digit],
[`asciiHexDigit`][api-ascii-hex-digit],
[`asciiPunctuation`][api-ascii-punctuation],
[`markdownLineEnding`][api-markdown-line-ending],
[`markdownLineEndingOrSpace`][api-markdown-line-ending-or-space],
[`markdownSpace`][api-markdown-space],
[`unicodePunctuation`][api-unicode-punctuation],
[`unicodeWhitespace`][api-unicode-whitespace].
There is no default export.

### `asciiAlpha(code)`

Check whether the [character code][code] represents an ASCII alpha (`a` through
`z`, case insensitive).

An **ASCII alpha** is an ASCII upper alpha or ASCII lower alpha.

An **ASCII upper alpha** is a character in the inclusive range U+0041 (`A`)
to U+005A (`Z`).

An **ASCII lower alpha** is a character in the inclusive range U+0061 (`a`)
to U+007A (`z`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiAlphanumeric(code)`

Check whether the [character code][code] represents an ASCII alphanumeric (`a`
through `z`, case insensitive, or `0` through `9`).

An **ASCII alphanumeric** is an ASCII digit (see `asciiDigit`) or ASCII alpha
(see `asciiAlpha`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiAtext(code)`

Check whether the [character code][code] represents an ASCII atext.

atext is an ASCII alphanumeric (see `asciiAlphanumeric`), or a character in
the inclusive ranges U+0023 NUMBER SIGN (`#`) to U+0027 APOSTROPHE (`'`),
U+002A ASTERISK (`*`), U+002B PLUS SIGN (`+`), U+002D DASH (`-`), U+002F
SLASH (`/`), U+003D EQUALS TO (`=`), U+003F QUESTION MARK (`?`), U+005E
CARET (`^`) to U+0060 GRAVE ACCENT (`` ` ``), or U+007B LEFT CURLY BRACE
(`{`) to U+007E TILDE (`~`) (**\[RFC5322]**).

See **\[RFC5322]**:\
[Internet Message Format](https://tools.ietf.org/html/rfc5322).\
P. Resnick.\
IETF.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiControl(code)`

Check whether a [character code][code] is an ASCII control character.

An **ASCII control** is a character in the inclusive range U+0000 NULL (NUL)
to U+001F (US), or U+007F (DEL).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiDigit(code)`

Check whether the [character code][code] represents an ASCII digit (`0` through
`9`).

An **ASCII digit** is a character in the inclusive range U+0030 (`0`) to
U+0039 (`9`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiHexDigit(code)`

Check whether the [character code][code] represents an ASCII hex digit (`a`
through `f`, case insensitive, or `0` through `9`).

An **ASCII hex digit** is an ASCII digit (see `asciiDigit`), ASCII upper hex
digit, or an ASCII lower hex digit.

An **ASCII upper hex digit** is a character in the inclusive range U+0041
(`A`) to U+0046 (`F`).

An **ASCII lower hex digit** is a character in the inclusive range U+0061
(`a`) to U+0066 (`f`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiPunctuation(code)`

Check whether the [character code][code] represents ASCII punctuation.

An **ASCII punctuation** is a character in the inclusive ranges U+0021
EXCLAMATION MARK (`!`) to U+002F SLASH (`/`), U+003A COLON (`:`) to U+0040 AT
SIGN (`@`), U+005B LEFT SQUARE BRACKET (`[`) to U+0060 GRAVE ACCENT
(`` ` ``), or U+007B LEFT CURLY BRACE (`{`) to U+007E TILDE (`~`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownLineEnding(code)`

Check whether a [character code][code] is a markdown line ending.

A **markdown line ending** is the virtual characters M-0003 CARRIAGE RETURN
LINE FEED (CRLF), M-0004 LINE FEED (LF) and M-0005 CARRIAGE RETURN (CR).

In micromark, the actual character U+000A LINE FEED (LF) and U+000D CARRIAGE
RETURN (CR) are replaced by these virtual characters depending on whether
they occurred together.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownLineEndingOrSpace(code)`

Check whether a [character code][code] is a markdown line ending (see
`markdownLineEnding`) or markdown space (see `markdownSpace`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownSpace(code)`

Check whether a [character code][code] is a markdown space.

A **markdown space** is the concrete character U+0020 SPACE (SP) and the
virtual characters M-0001 VIRTUAL SPACE (VS) and M-0002 HORIZONTAL TAB (HT).

In micromark, the actual character U+0009 CHARACTER TABULATION (HT) is
replaced by one M-0002 HORIZONTAL TAB (HT) and between 0 and 3 M-0001 VIRTUAL
SPACE (VS) characters, depending on the column at which the tab occurred.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `unicodePunctuation(code)`

Check whether the [character code][code] represents Unicode punctuation.

A **Unicode punctuation** is a character in the Unicode `Pc` (Punctuation,
Connector), `Pd` (Punctuation, Dash), `Pe` (Punctuation, Close), `Pf`
(Punctuation, Final quote), `Pi` (Punctuation, Initial quote), `Po`
(Punctuation, Other), or `Ps` (Punctuation, Open) categories, or an ASCII
punctuation (see `asciiPunctuation`) (**\[UNICODE]**).

See **\[UNICODE]**:\
[The Unicode Standard](https://www.unicode.org/versions/).\
Unicode Consortium.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `unicodeWhitespace(code)`

Check whether the [character code][code] represents Unicode whitespace.

Note that this does handle micromark specific markdown whitespace characters.
See `markdownLineEndingOrSpace` to check that.

A **Unicode whitespace** is a character in the Unicode `Zs` (Separator,
Space) category, or U+0009 CHARACTER TABULATION (HT), U+000A LINE FEED (LF),
U+000C (FF), or U+000D CARRIAGE RETURN (CR) (**\[UNICODE]**).

See **\[UNICODE]**:\
[The Unicode Standard](https://www.unicode.org/versions/).\
Unicode Consortium.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-character@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-character.svg

[downloads]: https://www.npmjs.com/package/micromark-util-character

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-character

[bundle-size]: https://bundlejs.com/?q=micromark-util-character

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[code]: https://github.com/micromark/micromark#preprocess

[api-ascii-alpha]: #asciialphacode

[api-ascii-alphanumeric]: #asciialphanumericcode

[api-ascii-atext]: #asciiatextcode

[api-ascii-control]: #asciicontrolcode

[api-ascii-digit]: #asciidigitcode

[api-ascii-hex-digit]: #asciihexdigitcode

[api-ascii-punctuation]: #asciipunctuationcode

[api-markdown-line-ending]: #markdownlineendingcode

[api-markdown-line-ending-or-space]: #markdownlineendingorspacecode

[api-markdown-space]: #markdownspacecode

[api-unicode-punctuation]: #unicodepunctuationcode

[api-unicode-whitespace]: #unicodewhitespacecode


---

# micromark-util-symbol

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility with symbols.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes constants used throughout the micromark ecosystem.

## When should I use this?

This package is useful when you are making your own micromark extensions.
It’s useful to reference these constants by name instead of value while
developing.
[`micromark-build`][micromark-build] compiles them away for production code.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-symbol
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as symbol from 'https://esm.sh/micromark-util-symbol@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as symbol from 'https://esm.sh/micromark-util-symbol@1?bundle'
</script>
```

## Use

```js
import {codes, constants, types, values} from 'micromark-util-symbol'

console.log(codes.atSign) // 64
console.log(constants.characterReferenceNamedSizeMax) // 31
console.log(types.definitionDestinationRaw) // 'definitionDestinationRaw'
console.log(values.atSign) // '@'
```

## API

This package exports the identifiers `codes`, `constants`, `types`, and
`values`.
There is no default export.

Each identifier is an object mapping strings to values.
See the code for the exposed data.

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-symbol@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-symbol.svg

[downloads]: https://www.npmjs.com/package/micromark-util-symbol

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-symbol

[bundle-size]: https://bundlejs.com/?q=micromark-util-symbol

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[micromark-build]: https://github.com/micromark/micromark/tree/main/packages/micromark-build


---

# micromark-extension-gfm-task-list-item

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[micromark][] extensions to support GFM [task list items][].

## Contents

* [What is this?](#what-is-this)
* [When to use this](#when-to-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`gfmTaskListItem()`](#gfmtasklistitem)
  * [`gfmTaskListItemHtml()`](#gfmtasklistitemhtml)
* [Authoring](#authoring)
* [HTML](#html)
* [CSS](#css)
* [Syntax](#syntax)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Related](#related)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package contains extensions that add support for task lists as enabled by
GFM to [`micromark`][micromark].
It matches how task list items work on `github.com`.

## When to use this

This project is useful when you want to support task lists in markdown.

You can use these extensions when you are working with [`micromark`][micromark].
To support all GFM features, use
[`micromark-extension-gfm`][micromark-extension-gfm].

When you need a syntax tree, you can combine this package with
[`mdast-util-gfm-task-list-item`][mdast-util-gfm-task-list-item].

All these packages are used [`remark-gfm`][remark-gfm], which focusses on making
it easier to transform content by abstracting these internals away.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-extension-gfm-task-list-item
```

In Deno with [`esm.sh`][esmsh]:

```js
import {gfmTaskListItem, gfmTaskListItemHtml} from 'https://esm.sh/micromark-extension-gfm-task-list-item@2'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {gfmTaskListItem, gfmTaskListItemHtml} from 'https://esm.sh/micromark-extension-gfm-task-list-item@2?bundle'
</script>
```

## Use

```js
import {micromark} from 'micromark'
import {
  gfmTaskListItem,
  gfmTaskListItemHtml
} from 'micromark-extension-gfm-task-list-item'

const output = micromark('* [x] a\n* [ ] b', {
  extensions: [gfmTaskListItem()],
  htmlExtensions: [gfmTaskListItemHtml()]
})

console.log(output)
```

Yields:

```html
<ul>
<li><input type="checkbox" disabled="" checked="" /> a</li>
<li><input type="checkbox" disabled="" /> b</li>
</ul>
```

## API

This package exports the identifiers [`gfmTaskListItem`][api-gfm-task-list-item]
and [`gfmTaskListItemHtml`][api-gfm-task-list-item-html].
There is no default export.

The export map supports the [`development` condition][development].
Run `node --conditions development module.js` to get instrumented dev code.
Without this condition, production code is loaded.

### `gfmTaskListItem()`

Create an HTML extension for `micromark` to support GFM task list items
syntax.

###### Returns

Extension for `micromark` that can be passed in `extensions`, to enable GFM
task list items syntax ([`Extension`][micromark-extension]).

### `gfmTaskListItemHtml()`

Create an HTML extension for `micromark` to support GFM task list items when
serializing to HTML.

###### Returns

Extension for `micromark` that can be passed in `htmlExtensions` to support GFM
task list items when serializing to HTML
([`HtmlExtension`][micromark-html-extension]).

## Authoring

It is recommended to use lowercase `x` (instead of uppercase `X`), because in
markdown, it is more common to use lowercase in places where casing does not
matter.
It is also recommended to use a space (instead of a tab), as there is no benefit
of using tabs in this case.

## HTML

Checks relate to the `<input>` element, in the checkbox state (`type=checkbox`),
in HTML.
See [*§ 4.10.5.1.15 Checkbox state (`type=checkbox`)*][html-input-checkbox]
in the HTML spec for more info.

```html
<!--…-->
<li><input type="checkbox" disabled="" /> foo</li>
<li><input type="checkbox" disabled="" checked="" /> bar</li>
<!--…-->
```

## CSS

GitHub itself uses slightly different markup for task list items than they
define in their spec.
When following the spec, as this extension does, only inputs are added.
They can be styled with the following CSS:

```css
input[type="checkbox"] {
  margin: 0 .2em .25em -1.6em;
  vertical-align: middle;
}

input[type="checkbox"]:dir(rtl) {
  margin: 0 -1.6em .25em .2em;
}
```

For the complete actual CSS see
[`sindresorhus/github-markdown-css`][github-markdown-css].

## Syntax

Checks form with the following BNF:

```bnf
gfm_task_list_item_check ::= '[' (0x09 | ' ' | 'X' | 'x') ']'
```

The check is only allowed at the start of the first paragraph, optionally
following zero or more definitions or a blank line, in a list item.
The check must be followed by whitespace (`[\t\n\r ]*`), which is in turn
followed by non-whitespace.

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-extension-gfm-task-list-item@^2`, compatible with Node.js 16.

This package works with `micromark` version `3` and later.

## Security

This package is safe.

## Related

* [`micromark-extension-gfm`][micromark-extension-gfm]
  — support all of GFM
* [`mdast-util-gfm-task-list-item`][mdast-util-gfm-task-list-item]
  — support all of GFM in mdast
* [`mdast-util-gfm`][mdast-util-gfm]
  — support all of GFM in mdast
* [`remark-gfm`][remark-gfm]
  — support all of GFM in remark

## Contribute

See [`contributing.md` in `micromark/.github`][contributing] for ways to get
started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark-extension-gfm-task-list-item/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark-extension-gfm-task-list-item/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark-extension-gfm-task-list-item.svg

[coverage]: https://codecov.io/github/micromark/micromark-extension-gfm-task-list-item

[downloads-badge]: https://img.shields.io/npm/dm/micromark-extension-gfm-task-list-item.svg

[downloads]: https://www.npmjs.com/package/micromark-extension-gfm-task-list-item

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-extension-gfm-task-list-item

[size]: https://bundlejs.com/?q=micromark-extension-gfm-task-list-item

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[npm]: https://docs.npmjs.com/cli/install

[esmsh]: https://esm.sh

[license]: license

[author]: https://wooorm.com

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[typescript]: https://www.typescriptlang.org

[development]: https://nodejs.org/api/packages.html#packages_resolving_user_conditions

[micromark]: https://github.com/micromark/micromark

[micromark-html-extension]: https://github.com/micromark/micromark#htmlextension

[micromark-extension]: https://github.com/micromark/micromark#syntaxextension

[micromark-extension-gfm]: https://github.com/micromark/micromark-extension-gfm

[mdast-util-gfm-task-list-item]: https://github.com/syntax-tree/mdast-util-gfm-task-list-item

[mdast-util-gfm]: https://github.com/syntax-tree/mdast-util-gfm

[remark-gfm]: https://github.com/remarkjs/remark-gfm

[task list items]: https://github.github.com/gfm/#task-list-items-extension-

[github-markdown-css]: https://github.com/sindresorhus/github-markdown-css

[html-input-checkbox]: https://html.spec.whatwg.org/multipage/input.html#checkbox-state-\(type=checkbox\)

[api-gfm-task-list-item]: #gfmtasklistitem

[api-gfm-task-list-item-html]: #gfmtasklistitemhtml


---

# micromark-factory-space

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] factory to parse [markdown space][markdown-space] (found in lots
of places).

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`factorySpace(…)`](#factoryspace)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes states to parse spaces and/or tabs.

## When should I use this?

This package is useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-factory-space
```

In Deno with [`esm.sh`][esmsh]:

```js
import {factorySpace} from 'https://esm.sh/micromark-factory-space@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {factorySpace} from 'https://esm.sh/micromark-factory-space@1?bundle'
</script>
```

## Use

```js
import {factorySpace} from 'micromark-factory-space'
import {codes, types} from 'micromark-util-symbol'

// A micromark tokenizer that uses the factory:
/**
 * @this {TokenizeContext}
 *   Context.
 * @type {Tokenizer}
 */
function tokenizeCodeFenced(effects, ok, nok) {
  return start

  // …

  /** @type {State} */
  function info(code) {
    if (code === codes.eof || markdownLineEndingOrSpace(code)) {
      effects.exit(types.chunkString)
      effects.exit(types.codeFencedFenceInfo)
      return factorySpace(effects, infoAfter, types.whitespace)(code)
    }

    if (code === codes.graveAccent && code === marker) return nok(code)
    effects.consume(code)
    return info
  }

  // …
}
```

## API

This module exports the identifier [`factorySpace`][api-factory-space].
There is no default export.

### `factorySpace(…)`

Parse spaces and tabs.

There is no `nok` parameter:

* spaces in markdown are often optional, in which case this factory can be
  used and `ok` will be switched to whether spaces were found or not
* one line ending or space can be detected with `markdownSpace(code)` right
  before using `factorySpace`

###### Examples

Where `␉` represents a tab (plus how much it expands) and `␠` represents a
single space.

```markdown
␉
␠␠␠␠
␉␠
```

###### Parameters

* `effects` (`Effects`)
  — context
* `ok` (`State`)
  — state switched to when successful
* `type` (`string`)
  — type (`' \t'`)
* `max` (`number`, default: `Infinity`)
  — max (exclusive)

###### Returns

Start state (`State`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-factory-space@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-factory-space.svg

[downloads]: https://www.npmjs.com/package/micromark-factory-space

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-factory-space

[bundle-size]: https://bundlejs.com/?q=micromark-factory-space

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[markdown-space]: https://github.com/micromark/micromark/tree/main/packages/micromark-util-character#markdownspacecode

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[api-factory-space]: #factoryspace


---

# micromark-util-character

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility to handle [character codes][code].

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`asciiAlpha(code)`](#asciialphacode)
  * [`asciiAlphanumeric(code)`](#asciialphanumericcode)
  * [`asciiAtext(code)`](#asciiatextcode)
  * [`asciiControl(code)`](#asciicontrolcode)
  * [`asciiDigit(code)`](#asciidigitcode)
  * [`asciiHexDigit(code)`](#asciihexdigitcode)
  * [`asciiPunctuation(code)`](#asciipunctuationcode)
  * [`markdownLineEnding(code)`](#markdownlineendingcode)
  * [`markdownLineEndingOrSpace(code)`](#markdownlineendingorspacecode)
  * [`markdownSpace(code)`](#markdownspacecode)
  * [`unicodePunctuation(code)`](#unicodepunctuationcode)
  * [`unicodeWhitespace(code)`](#unicodewhitespacecode)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes algorithms to check whether characters match groups.

## When should I use this?

This package might be useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-character
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as character from 'https://esm.sh/micromark-util-character@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as character from 'https://esm.sh/micromark-util-character@1?bundle'
</script>
```

## Use

```js
import {asciiAlpha} from 'micromark-util-character'

console.log(asciiAlpha(64)) // false
console.log(asciiAlpha(65)) // true
```

## API

This module exports the identifiers
[`asciiAlpha`][api-ascii-alpha],
[`asciiAlphanumeric`][api-ascii-alphanumeric],
[`asciiAtext`][api-ascii-atext],
[`asciiControl`][api-ascii-control],
[`asciiDigit`][api-ascii-digit],
[`asciiHexDigit`][api-ascii-hex-digit],
[`asciiPunctuation`][api-ascii-punctuation],
[`markdownLineEnding`][api-markdown-line-ending],
[`markdownLineEndingOrSpace`][api-markdown-line-ending-or-space],
[`markdownSpace`][api-markdown-space],
[`unicodePunctuation`][api-unicode-punctuation],
[`unicodeWhitespace`][api-unicode-whitespace].
There is no default export.

### `asciiAlpha(code)`

Check whether the [character code][code] represents an ASCII alpha (`a` through
`z`, case insensitive).

An **ASCII alpha** is an ASCII upper alpha or ASCII lower alpha.

An **ASCII upper alpha** is a character in the inclusive range U+0041 (`A`)
to U+005A (`Z`).

An **ASCII lower alpha** is a character in the inclusive range U+0061 (`a`)
to U+007A (`z`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiAlphanumeric(code)`

Check whether the [character code][code] represents an ASCII alphanumeric (`a`
through `z`, case insensitive, or `0` through `9`).

An **ASCII alphanumeric** is an ASCII digit (see `asciiDigit`) or ASCII alpha
(see `asciiAlpha`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiAtext(code)`

Check whether the [character code][code] represents an ASCII atext.

atext is an ASCII alphanumeric (see `asciiAlphanumeric`), or a character in
the inclusive ranges U+0023 NUMBER SIGN (`#`) to U+0027 APOSTROPHE (`'`),
U+002A ASTERISK (`*`), U+002B PLUS SIGN (`+`), U+002D DASH (`-`), U+002F
SLASH (`/`), U+003D EQUALS TO (`=`), U+003F QUESTION MARK (`?`), U+005E
CARET (`^`) to U+0060 GRAVE ACCENT (`` ` ``), or U+007B LEFT CURLY BRACE
(`{`) to U+007E TILDE (`~`) (**\[RFC5322]**).

See **\[RFC5322]**:\
[Internet Message Format](https://tools.ietf.org/html/rfc5322).\
P. Resnick.\
IETF.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiControl(code)`

Check whether a [character code][code] is an ASCII control character.

An **ASCII control** is a character in the inclusive range U+0000 NULL (NUL)
to U+001F (US), or U+007F (DEL).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiDigit(code)`

Check whether the [character code][code] represents an ASCII digit (`0` through
`9`).

An **ASCII digit** is a character in the inclusive range U+0030 (`0`) to
U+0039 (`9`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiHexDigit(code)`

Check whether the [character code][code] represents an ASCII hex digit (`a`
through `f`, case insensitive, or `0` through `9`).

An **ASCII hex digit** is an ASCII digit (see `asciiDigit`), ASCII upper hex
digit, or an ASCII lower hex digit.

An **ASCII upper hex digit** is a character in the inclusive range U+0041
(`A`) to U+0046 (`F`).

An **ASCII lower hex digit** is a character in the inclusive range U+0061
(`a`) to U+0066 (`f`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiPunctuation(code)`

Check whether the [character code][code] represents ASCII punctuation.

An **ASCII punctuation** is a character in the inclusive ranges U+0021
EXCLAMATION MARK (`!`) to U+002F SLASH (`/`), U+003A COLON (`:`) to U+0040 AT
SIGN (`@`), U+005B LEFT SQUARE BRACKET (`[`) to U+0060 GRAVE ACCENT
(`` ` ``), or U+007B LEFT CURLY BRACE (`{`) to U+007E TILDE (`~`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownLineEnding(code)`

Check whether a [character code][code] is a markdown line ending.

A **markdown line ending** is the virtual characters M-0003 CARRIAGE RETURN
LINE FEED (CRLF), M-0004 LINE FEED (LF) and M-0005 CARRIAGE RETURN (CR).

In micromark, the actual character U+000A LINE FEED (LF) and U+000D CARRIAGE
RETURN (CR) are replaced by these virtual characters depending on whether
they occurred together.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownLineEndingOrSpace(code)`

Check whether a [character code][code] is a markdown line ending (see
`markdownLineEnding`) or markdown space (see `markdownSpace`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownSpace(code)`

Check whether a [character code][code] is a markdown space.

A **markdown space** is the concrete character U+0020 SPACE (SP) and the
virtual characters M-0001 VIRTUAL SPACE (VS) and M-0002 HORIZONTAL TAB (HT).

In micromark, the actual character U+0009 CHARACTER TABULATION (HT) is
replaced by one M-0002 HORIZONTAL TAB (HT) and between 0 and 3 M-0001 VIRTUAL
SPACE (VS) characters, depending on the column at which the tab occurred.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `unicodePunctuation(code)`

Check whether the [character code][code] represents Unicode punctuation.

A **Unicode punctuation** is a character in the Unicode `Pc` (Punctuation,
Connector), `Pd` (Punctuation, Dash), `Pe` (Punctuation, Close), `Pf`
(Punctuation, Final quote), `Pi` (Punctuation, Initial quote), `Po`
(Punctuation, Other), or `Ps` (Punctuation, Open) categories, or an ASCII
punctuation (see `asciiPunctuation`) (**\[UNICODE]**).

See **\[UNICODE]**:\
[The Unicode Standard](https://www.unicode.org/versions/).\
Unicode Consortium.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `unicodeWhitespace(code)`

Check whether the [character code][code] represents Unicode whitespace.

Note that this does handle micromark specific markdown whitespace characters.
See `markdownLineEndingOrSpace` to check that.

A **Unicode whitespace** is a character in the Unicode `Zs` (Separator,
Space) category, or U+0009 CHARACTER TABULATION (HT), U+000A LINE FEED (LF),
U+000C (FF), or U+000D CARRIAGE RETURN (CR) (**\[UNICODE]**).

See **\[UNICODE]**:\
[The Unicode Standard](https://www.unicode.org/versions/).\
Unicode Consortium.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-character@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-character.svg

[downloads]: https://www.npmjs.com/package/micromark-util-character

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-character

[bundle-size]: https://bundlejs.com/?q=micromark-util-character

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[code]: https://github.com/micromark/micromark#preprocess

[api-ascii-alpha]: #asciialphacode

[api-ascii-alphanumeric]: #asciialphanumericcode

[api-ascii-atext]: #asciiatextcode

[api-ascii-control]: #asciicontrolcode

[api-ascii-digit]: #asciidigitcode

[api-ascii-hex-digit]: #asciihexdigitcode

[api-ascii-punctuation]: #asciipunctuationcode

[api-markdown-line-ending]: #markdownlineendingcode

[api-markdown-line-ending-or-space]: #markdownlineendingorspacecode

[api-markdown-space]: #markdownspacecode

[api-unicode-punctuation]: #unicodepunctuationcode

[api-unicode-whitespace]: #unicodewhitespacecode


---

# micromark-util-symbol

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility with symbols.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes constants used throughout the micromark ecosystem.

## When should I use this?

This package is useful when you are making your own micromark extensions.
It’s useful to reference these constants by name instead of value while
developing.
[`micromark-build`][micromark-build] compiles them away for production code.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-symbol
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as symbol from 'https://esm.sh/micromark-util-symbol@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as symbol from 'https://esm.sh/micromark-util-symbol@1?bundle'
</script>
```

## Use

```js
import {codes, constants, types, values} from 'micromark-util-symbol'

console.log(codes.atSign) // 64
console.log(constants.characterReferenceNamedSizeMax) // 31
console.log(types.definitionDestinationRaw) // 'definitionDestinationRaw'
console.log(values.atSign) // '@'
```

## API

This package exports the identifiers `codes`, `constants`, `types`, and
`values`.
There is no default export.

Each identifier is an object mapping strings to values.
See the code for the exposed data.

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-symbol@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-symbol.svg

[downloads]: https://www.npmjs.com/package/micromark-util-symbol

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-symbol

[bundle-size]: https://bundlejs.com/?q=micromark-util-symbol

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[micromark-build]: https://github.com/micromark/micromark/tree/main/packages/micromark-build


---

# micromark-extension-mdx-expression

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[micromark][] extension to support [MDX][mdxjs] expressions (`{Math.PI}`).

## Contents

* [What is this?](#what-is-this)
* [When to use this](#when-to-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`mdxExpression(options?)`](#mdxexpressionoptions)
  * [Options](#options)
* [Authoring](#authoring)
* [Syntax](#syntax)
* [Errors](#errors)
  * [Unexpected end of file in expression, expected a corresponding closing brace for `{`](#unexpected-end-of-file-in-expression-expected-a-corresponding-closing-brace-for-)
  * [Unexpected lazy line in expression in container, expected line to be prefixed…](#unexpected-lazy-line-in-expression-in-container-expected-line-to-be-prefixed)
  * [Unexpected `$type` in code: expected an object spread (`{...spread}`)](#unexpected-type-in-code-expected-an-object-spread-spread)
  * [Unexpected extra content in spread: only a single spread is supported](#unexpected-extra-content-in-spread-only-a-single-spread-is-supported)
  * [Could not parse expression with acorn](#could-not-parse-expression-with-acorn)
* [Tokens](#tokens)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Related](#related)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package contains an extension that adds support for the expression syntax
enabled by [MDX][mdxjs] to [`micromark`][micromark].
These extensions are used inside MDX.

This package can be made aware or unaware of JavaScript syntax.
When unaware, expressions could include Rust or variables or whatnot.

## When to use this

This project is useful when you want to support expressions in markdown.

You can use this extension when you are working with [`micromark`][micromark].
To support all MDX features, use
[`micromark-extension-mdxjs`][micromark-extension-mdxjs] instead.

When you need a syntax tree, combine this package with
[`mdast-util-mdx-expression`][mdast-util-mdx-expression].

All these packages are used in [`remark-mdx`][remark-mdx], which focusses on
making it easier to transform content by abstracting these internals away.

When you are using [`mdx-js/mdx`][mdxjs], all of this is already included.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-extension-mdx-expression
```

In Deno with [`esm.sh`][esmsh]:

```js
import {mdxExpression} from 'https://esm.sh/micromark-extension-mdx-expression@2'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {mdxExpression} from 'https://esm.sh/micromark-extension-mdx-expression@2?bundle'
</script>
```

## Use

```js
import {Parser} from 'acorn'
import acornJsx from 'acorn-jsx'
import {micromark} from 'micromark'
import {mdxExpression} from 'micromark-extension-mdx-expression'

// Unaware of JavaScript (“agnostic”) (balanced braces):
const output = micromark('a {1 + 1} b', {extensions: [mdxExpression()]})

console.log(output)

// Aware of JavaScript:
micromark('a {!} b', {extensions: [mdxExpression({acorn: Parser.extend(acornJsx())})]})
```

Yields:

```html
<p>a  b</p>
```

```text
[1:5: Could not parse expression with acorn] {
  ancestors: undefined,
  cause: SyntaxError: Unexpected token
      at pp$4.raise (file:///Users/tilde/Projects/oss/micromark-extension-mdx-expression/node_modules/acorn/dist/acorn.mjs:3547:13)
      at pp$9.unexpected (file:///Users/tilde/Projects/oss/micromark-extension-mdx-expression/node_modules/acorn/dist/acorn.mjs:758:8)
      …
    pos: 4,
    loc: { line: 1, column: 4 },
    raisedAt: 1
  },
  column: 5,
  fatal: undefined,
  line: 1,
  place: { line: 1, column: 5, offset: 4 },
  reason: 'Could not parse expression with acorn',
  ruleId: 'acorn',
  source: 'micromark-extension-mdx-expression',
  url: 'https://github.com/micromark/micromark-extension-mdx-expression/tree/main/packages/micromark-extension-mdx-expression#could-not-parse-expression-with-acorn'
}
```

…which is useless: go to a syntax tree with
[`mdast-util-from-markdown`][mdast-util-from-markdown] and
[`mdast-util-mdx-expression`][mdast-util-mdx-expression] instead.

## API

This package exports the identifier [`mdxExpression`][api-mdx-expression].
There is no default export.

The export map supports the [`development` condition][development].
Run `node --conditions development module.js` to get instrumented dev code.
Without this condition, production code is loaded.

### `mdxExpression(options?)`

Create an extension for `micromark` to enable MDX expression syntax.

###### Parameters

* `options` ([`Options`][api-options], optional)
  — configuration

###### Returns

Extension for `micromark` that can be passed in `extensions` to enable MDX
expression syntax ([`Extension`][micromark-extension]).

### Options

Configuration (TypeScript type).

###### Fields

* `acorn` ([`Acorn`][acorn], optional)
  — acorn parser to use
* `acornOptions` ([`AcornOptions`][acorn-options], default:
  `{ecmaVersion: 2024, locations: true, sourceType: 'module'}`)
  — configuration for acorn; all fields except `locations` can be set
* `addResult` (`boolean`, default: `false`)
  — whether to add `estree` fields to tokens with results from acorn

<!-- Note: `spread` and `allowEmpty` are intentionally not documented. -->

## Authoring

When authoring markdown with JavaScript, keep in mind that MDX is a whitespace
sensitive and line-based language, while JavaScript is insensitive to
whitespace.
This affects how markdown and JavaScript interleave with eachother in MDX.
For more info on how it works, see [§ Interleaving][mdxjs-interleaving] on the
MDX site.

## Syntax

This extension supports MDX both aware and unaware to JavaScript (respectively
gnostic and agnostic).
Depending on whether acorn is passed, either valid JavaScript must be used in
expressions, or arbitrary text (such as Rust code or so) can be used.

There are two types of expressions: in text (inline, span) or in flow (block).
They start with `{`.

Depending on whether `acorn` is passed, expressions are either parsed in several
tries until whole JavaScript is found (as in, nested curly braces depend on JS
expression nesting), or they are counted and must be balanced.

Expressions end with `}`.

For flow (block) expressions, optionally markdown spaces (` ` or `\t`) can occur
after the closing brace, and finally a markdown line ending (`\r`, `\n`) or the
end of the file must follow.

While markdown typically knows no errors, for MDX it is decided to instead
throw on invalid syntax.

```mdx
Here is an expression in a heading:

## Hello, {1 + 1}!

In agnostic mode, balanced braces can occur: {a + {b} + c}.

In gnostic mode, the value of the expression must be JavaScript, so
this would fail: {!}.
But, in gnostic mode, braces can be in comments, strings, or in other
places: {1 /* { */ + 2}.

The previous examples were text (inline, span) expressions, they can
also be flow (block):

{
  1 + 1
}

This is incorrect, because there are further characters:

{
  1 + 1
}!
```

```mdx-invalid
Blank lines cannot occur in text, because markdown has already split them in
separate constructs, so this is incorrect: {1 +

1}
```

```mdx
In flow, you can have blank lines:

{
  1 +

  2
}
```

## Errors

### Unexpected end of file in expression, expected a corresponding closing brace for `{`

This error occurs if a `{` was seen without a `}` (source:
`micromark-extension-mdx-expression`, rule id: `unexpected-eof`).
For example:

```mdx-invalid
a { b
```

### Unexpected lazy line in expression in container, expected line to be prefixed…

This error occurs if a `{` was seen in a container which then has lazy content
(source: `micromark-extension-mdx-expression`, rule id: `unexpected-lazy`).
For example:

```mdx-invalid
> {a
b}
```

### Unexpected `$type` in code: expected an object spread (`{...spread}`)

This error occurs if a spread was expected but something else was found
(source: `micromark-extension-mdx-expression`, rule id: `non-spread`).
For example:

```mdx-invalid
<a {b=c}={} d>
```

### Unexpected extra content in spread: only a single spread is supported

This error occurs if a spread was expected but more was found after it
(source: `micromark-extension-mdx-expression`, rule id: `spread-extra`).
For example:

```mdx-invalid
<a {...b,c} d>
```

### Could not parse expression with acorn

This error occurs if acorn crashes or when there is more content after a JS
expression (source: `micromark-extension-mdx-expression`, rule id: `acorn`).
For example:

```mdx-invalid
a {"b" "c"} d
```

```mdx-invalid
a {var b = "c"} d
```

## Tokens

Two tokens are used, `mdxFlowExpression` and `mdxTextExpression`, to reflect
flow and text expressions.

They include:

* `lineEnding` for the markdown line endings `\r`, `\n`, and `\r\n`
* `mdxFlowExpressionMarker` and `mdxTextExpressionMarker` for the braces
* `whitespace` for markdown spaces and tabs in blank lines
* `mdxFlowExpressionChunk` and `mdxTextExpressionChunk` for chunks of
  expression content

## Types

This package is fully typed with [TypeScript][].
It exports the additional type [`Options`][api-options].

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-extension-mdx-expression@^2`, compatible with Node.js 16.

This package works with `micromark` version `3` and later.

## Security

This package is safe.

## Related

* [`micromark-extension-mdxjs`][micromark-extension-mdxjs]
  — support all MDX syntax
* [`mdast-util-mdx-expression`][mdast-util-mdx-expression]
  — support MDX expressions in mdast
* [`remark-mdx`][remark-mdx]
  — support all MDX syntax in remark

## Contribute

See [`contributing.md` in `micromark/.github`][contributing] for ways to get
started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[acorn]: https://github.com/acornjs/acorn

[acorn-options]: https://github.com/acornjs/acorn/blob/96c721dbf89d0ccc3a8c7f39e69ef2a6a3c04dfa/acorn/dist/acorn.d.ts#L16

[api-mdx-expression]: #mdxexpressionoptions

[api-options]: #options

[author]: https://wooorm.com

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[build]: https://github.com/micromark/micromark-extension-mdx-expression/actions

[build-badge]: https://github.com/micromark/micromark-extension-mdx-expression/workflows/main/badge.svg

[chat]: https://github.com/micromark/micromark/discussions

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[collective]: https://opencollective.com/unified

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[coverage]: https://codecov.io/github/micromark/micromark-extension-mdx-expression

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark-extension-mdx-expression.svg

[development]: https://nodejs.org/api/packages.html#packages_resolving_user_conditions

[downloads]: https://www.npmjs.com/package/micromark-extension-mdx-expression

[downloads-badge]: https://img.shields.io/npm/dm/micromark-extension-mdx-expression.svg

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[license]: https://github.com/micromark/micromark-extension-mdx-expression/blob/main/license

[mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown

[mdast-util-mdx-expression]: https://github.com/syntax-tree/mdast-util-mdx-expression

[mdxjs]: https://mdxjs.com

[mdxjs-interleaving]: https://mdxjs.com/docs/what-is-mdx/#interleaving

[micromark]: https://github.com/micromark/micromark

[micromark-extension]: https://github.com/micromark/micromark#syntaxextension

[micromark-extension-mdxjs]: https://github.com/micromark/micromark-extension-mdxjs

[npm]: https://docs.npmjs.com/cli/install

[remark-mdx]: https://mdxjs.com/packages/remark-mdx/

[size]: https://bundlejs.com/?q=micromark-extension-mdx-expression

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-extension-mdx-expression

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[support]: https://github.com/micromark/.github/blob/main/support.md

[typescript]: https://www.typescriptlang.org


---

# micromark-factory-space

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] factory to parse [markdown space][markdown-space] (found in lots
of places).

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`factorySpace(…)`](#factoryspace)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes states to parse spaces and/or tabs.

## When should I use this?

This package is useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-factory-space
```

In Deno with [`esm.sh`][esmsh]:

```js
import {factorySpace} from 'https://esm.sh/micromark-factory-space@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {factorySpace} from 'https://esm.sh/micromark-factory-space@1?bundle'
</script>
```

## Use

```js
import {factorySpace} from 'micromark-factory-space'
import {codes, types} from 'micromark-util-symbol'

// A micromark tokenizer that uses the factory:
/**
 * @this {TokenizeContext}
 *   Context.
 * @type {Tokenizer}
 */
function tokenizeCodeFenced(effects, ok, nok) {
  return start

  // …

  /** @type {State} */
  function info(code) {
    if (code === codes.eof || markdownLineEndingOrSpace(code)) {
      effects.exit(types.chunkString)
      effects.exit(types.codeFencedFenceInfo)
      return factorySpace(effects, infoAfter, types.whitespace)(code)
    }

    if (code === codes.graveAccent && code === marker) return nok(code)
    effects.consume(code)
    return info
  }

  // …
}
```

## API

This module exports the identifier [`factorySpace`][api-factory-space].
There is no default export.

### `factorySpace(…)`

Parse spaces and tabs.

There is no `nok` parameter:

* spaces in markdown are often optional, in which case this factory can be
  used and `ok` will be switched to whether spaces were found or not
* one line ending or space can be detected with `markdownSpace(code)` right
  before using `factorySpace`

###### Examples

Where `␉` represents a tab (plus how much it expands) and `␠` represents a
single space.

```markdown
␉
␠␠␠␠
␉␠
```

###### Parameters

* `effects` (`Effects`)
  — context
* `ok` (`State`)
  — state switched to when successful
* `type` (`string`)
  — type (`' \t'`)
* `max` (`number`, default: `Infinity`)
  — max (exclusive)

###### Returns

Start state (`State`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-factory-space@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-factory-space.svg

[downloads]: https://www.npmjs.com/package/micromark-factory-space

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-factory-space

[bundle-size]: https://bundlejs.com/?q=micromark-factory-space

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[markdown-space]: https://github.com/micromark/micromark/tree/main/packages/micromark-util-character#markdownspacecode

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[api-factory-space]: #factoryspace


---

# micromark-util-character

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility to handle [character codes][code].

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`asciiAlpha(code)`](#asciialphacode)
  * [`asciiAlphanumeric(code)`](#asciialphanumericcode)
  * [`asciiAtext(code)`](#asciiatextcode)
  * [`asciiControl(code)`](#asciicontrolcode)
  * [`asciiDigit(code)`](#asciidigitcode)
  * [`asciiHexDigit(code)`](#asciihexdigitcode)
  * [`asciiPunctuation(code)`](#asciipunctuationcode)
  * [`markdownLineEnding(code)`](#markdownlineendingcode)
  * [`markdownLineEndingOrSpace(code)`](#markdownlineendingorspacecode)
  * [`markdownSpace(code)`](#markdownspacecode)
  * [`unicodePunctuation(code)`](#unicodepunctuationcode)
  * [`unicodeWhitespace(code)`](#unicodewhitespacecode)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes algorithms to check whether characters match groups.

## When should I use this?

This package might be useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-character
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as character from 'https://esm.sh/micromark-util-character@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as character from 'https://esm.sh/micromark-util-character@1?bundle'
</script>
```

## Use

```js
import {asciiAlpha} from 'micromark-util-character'

console.log(asciiAlpha(64)) // false
console.log(asciiAlpha(65)) // true
```

## API

This module exports the identifiers
[`asciiAlpha`][api-ascii-alpha],
[`asciiAlphanumeric`][api-ascii-alphanumeric],
[`asciiAtext`][api-ascii-atext],
[`asciiControl`][api-ascii-control],
[`asciiDigit`][api-ascii-digit],
[`asciiHexDigit`][api-ascii-hex-digit],
[`asciiPunctuation`][api-ascii-punctuation],
[`markdownLineEnding`][api-markdown-line-ending],
[`markdownLineEndingOrSpace`][api-markdown-line-ending-or-space],
[`markdownSpace`][api-markdown-space],
[`unicodePunctuation`][api-unicode-punctuation],
[`unicodeWhitespace`][api-unicode-whitespace].
There is no default export.

### `asciiAlpha(code)`

Check whether the [character code][code] represents an ASCII alpha (`a` through
`z`, case insensitive).

An **ASCII alpha** is an ASCII upper alpha or ASCII lower alpha.

An **ASCII upper alpha** is a character in the inclusive range U+0041 (`A`)
to U+005A (`Z`).

An **ASCII lower alpha** is a character in the inclusive range U+0061 (`a`)
to U+007A (`z`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiAlphanumeric(code)`

Check whether the [character code][code] represents an ASCII alphanumeric (`a`
through `z`, case insensitive, or `0` through `9`).

An **ASCII alphanumeric** is an ASCII digit (see `asciiDigit`) or ASCII alpha
(see `asciiAlpha`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiAtext(code)`

Check whether the [character code][code] represents an ASCII atext.

atext is an ASCII alphanumeric (see `asciiAlphanumeric`), or a character in
the inclusive ranges U+0023 NUMBER SIGN (`#`) to U+0027 APOSTROPHE (`'`),
U+002A ASTERISK (`*`), U+002B PLUS SIGN (`+`), U+002D DASH (`-`), U+002F
SLASH (`/`), U+003D EQUALS TO (`=`), U+003F QUESTION MARK (`?`), U+005E
CARET (`^`) to U+0060 GRAVE ACCENT (`` ` ``), or U+007B LEFT CURLY BRACE
(`{`) to U+007E TILDE (`~`) (**\[RFC5322]**).

See **\[RFC5322]**:\
[Internet Message Format](https://tools.ietf.org/html/rfc5322).\
P. Resnick.\
IETF.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiControl(code)`

Check whether a [character code][code] is an ASCII control character.

An **ASCII control** is a character in the inclusive range U+0000 NULL (NUL)
to U+001F (US), or U+007F (DEL).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiDigit(code)`

Check whether the [character code][code] represents an ASCII digit (`0` through
`9`).

An **ASCII digit** is a character in the inclusive range U+0030 (`0`) to
U+0039 (`9`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiHexDigit(code)`

Check whether the [character code][code] represents an ASCII hex digit (`a`
through `f`, case insensitive, or `0` through `9`).

An **ASCII hex digit** is an ASCII digit (see `asciiDigit`), ASCII upper hex
digit, or an ASCII lower hex digit.

An **ASCII upper hex digit** is a character in the inclusive range U+0041
(`A`) to U+0046 (`F`).

An **ASCII lower hex digit** is a character in the inclusive range U+0061
(`a`) to U+0066 (`f`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiPunctuation(code)`

Check whether the [character code][code] represents ASCII punctuation.

An **ASCII punctuation** is a character in the inclusive ranges U+0021
EXCLAMATION MARK (`!`) to U+002F SLASH (`/`), U+003A COLON (`:`) to U+0040 AT
SIGN (`@`), U+005B LEFT SQUARE BRACKET (`[`) to U+0060 GRAVE ACCENT
(`` ` ``), or U+007B LEFT CURLY BRACE (`{`) to U+007E TILDE (`~`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownLineEnding(code)`

Check whether a [character code][code] is a markdown line ending.

A **markdown line ending** is the virtual characters M-0003 CARRIAGE RETURN
LINE FEED (CRLF), M-0004 LINE FEED (LF) and M-0005 CARRIAGE RETURN (CR).

In micromark, the actual character U+000A LINE FEED (LF) and U+000D CARRIAGE
RETURN (CR) are replaced by these virtual characters depending on whether
they occurred together.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownLineEndingOrSpace(code)`

Check whether a [character code][code] is a markdown line ending (see
`markdownLineEnding`) or markdown space (see `markdownSpace`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownSpace(code)`

Check whether a [character code][code] is a markdown space.

A **markdown space** is the concrete character U+0020 SPACE (SP) and the
virtual characters M-0001 VIRTUAL SPACE (VS) and M-0002 HORIZONTAL TAB (HT).

In micromark, the actual character U+0009 CHARACTER TABULATION (HT) is
replaced by one M-0002 HORIZONTAL TAB (HT) and between 0 and 3 M-0001 VIRTUAL
SPACE (VS) characters, depending on the column at which the tab occurred.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `unicodePunctuation(code)`

Check whether the [character code][code] represents Unicode punctuation.

A **Unicode punctuation** is a character in the Unicode `Pc` (Punctuation,
Connector), `Pd` (Punctuation, Dash), `Pe` (Punctuation, Close), `Pf`
(Punctuation, Final quote), `Pi` (Punctuation, Initial quote), `Po`
(Punctuation, Other), or `Ps` (Punctuation, Open) categories, or an ASCII
punctuation (see `asciiPunctuation`) (**\[UNICODE]**).

See **\[UNICODE]**:\
[The Unicode Standard](https://www.unicode.org/versions/).\
Unicode Consortium.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `unicodeWhitespace(code)`

Check whether the [character code][code] represents Unicode whitespace.

Note that this does handle micromark specific markdown whitespace characters.
See `markdownLineEndingOrSpace` to check that.

A **Unicode whitespace** is a character in the Unicode `Zs` (Separator,
Space) category, or U+0009 CHARACTER TABULATION (HT), U+000A LINE FEED (LF),
U+000C (FF), or U+000D CARRIAGE RETURN (CR) (**\[UNICODE]**).

See **\[UNICODE]**:\
[The Unicode Standard](https://www.unicode.org/versions/).\
Unicode Consortium.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-character@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-character.svg

[downloads]: https://www.npmjs.com/package/micromark-util-character

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-character

[bundle-size]: https://bundlejs.com/?q=micromark-util-character

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[code]: https://github.com/micromark/micromark#preprocess

[api-ascii-alpha]: #asciialphacode

[api-ascii-alphanumeric]: #asciialphanumericcode

[api-ascii-atext]: #asciiatextcode

[api-ascii-control]: #asciicontrolcode

[api-ascii-digit]: #asciidigitcode

[api-ascii-hex-digit]: #asciihexdigitcode

[api-ascii-punctuation]: #asciipunctuationcode

[api-markdown-line-ending]: #markdownlineendingcode

[api-markdown-line-ending-or-space]: #markdownlineendingorspacecode

[api-markdown-space]: #markdownspacecode

[api-unicode-punctuation]: #unicodepunctuationcode

[api-unicode-whitespace]: #unicodewhitespacecode


---

# micromark-util-symbol

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility with symbols.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes constants used throughout the micromark ecosystem.

## When should I use this?

This package is useful when you are making your own micromark extensions.
It’s useful to reference these constants by name instead of value while
developing.
[`micromark-build`][micromark-build] compiles them away for production code.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-symbol
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as symbol from 'https://esm.sh/micromark-util-symbol@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as symbol from 'https://esm.sh/micromark-util-symbol@1?bundle'
</script>
```

## Use

```js
import {codes, constants, types, values} from 'micromark-util-symbol'

console.log(codes.atSign) // 64
console.log(constants.characterReferenceNamedSizeMax) // 31
console.log(types.definitionDestinationRaw) // 'definitionDestinationRaw'
console.log(values.atSign) // '@'
```

## API

This package exports the identifiers `codes`, `constants`, `types`, and
`values`.
There is no default export.

Each identifier is an object mapping strings to values.
See the code for the exposed data.

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-symbol@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-symbol.svg

[downloads]: https://www.npmjs.com/package/micromark-util-symbol

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-symbol

[bundle-size]: https://bundlejs.com/?q=micromark-util-symbol

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[micromark-build]: https://github.com/micromark/micromark/tree/main/packages/micromark-build


---

# micromark-extension-mdx-jsx

[![Build][badge-build-image]][badge-build-url]
[![Coverage][badge-coverage-image]][badge-coverage-url]
[![Downloads][badge-downloads-image]][badge-downloads-url]
[![Size][badge-size-image]][badge-size-url]

[micromark][github-micromark] extension to support [MDX][mdxjs] JSX
(`<Component />`).

## Contents

* [What is this?](#what-is-this)
* [When to use this](#when-to-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`mdxJsx(options?)`](#mdxjsxoptions)
  * [`Options`](#options)
* [Authoring](#authoring)
* [Syntax](#syntax)
* [Errors](#errors)
  * [Unexpected end of file $at, expected $expect](#unexpected-end-of-file-at-expected-expect)
  * [Unexpected character $at, expected $expect](#unexpected-character-at-expected-expect)
  * [Unexpected lazy line in container, expected line to be…](#unexpected-lazy-line-in-container-expected-line-to-be)
* [Tokens](#tokens)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Related](#related)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package contains an extension that adds support for the JSX syntax enabled
by [MDX][mdxjs] to [`micromark`][github-micromark].
These extensions are used inside MDX.
It mostly matches how JSX works in most places that support it
(TypeScript, Babel, esbuild, SWC, etc).

This package can be made aware or unaware of JavaScript syntax.
When unaware,
expressions could include Rust or variables or whatnot.

## When to use this

This project is useful when you want to support JSX in markdown.

You can use this extension when you are working with
[`micromark`][github-micromark].
To support all MDX features,
use [`micromark-extension-mdxjs`][github-micromark-extension-mdxjs] instead.

When you need a syntax tree,
combine this package with [`mdast-util-mdx-jsx`][github-mdast-util-mdx-jsx].

All these packages are used in [`remark-mdx`][mdxjs-remark-mdx],
which focusses on making it easier to transform content by abstracting these
internals away.

When you are using [`mdx-js/mdx`][mdxjs],
all of this is already included.

## Install

This package is [ESM only][github-gist-esm].
In Node.js (version 16+),
install with [npm][npmjs-install]:

```sh
npm install micromark-extension-mdx-jsx
```

In Deno with [`esm.sh`][esmsh]:

```js
import {mdxJsx} from 'https://esm.sh/micromark-extension-mdx-jsx@2'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {mdxJsx} from 'https://esm.sh/micromark-extension-mdx-jsx@2?bundle'
</script>
```

## Use

```js
import {micromark} from 'micromark'
import {mdxJsx} from 'micromark-extension-mdx-jsx'

const output = micromark('a <b c d="e" /> f', {extensions: [mdxJsx()]})

console.log(output)
```

Yields:

```html
<p>a  f</p>
```

…which is useless:
go to a syntax tree with
[`mdast-util-from-markdown`][github-mdast-util-from-markdown] and
[`mdast-util-mdx-jsx`][github-mdast-util-mdx-jsx] instead.

## API

This package exports the identifier [`mdxJsx`][api-mdx-jsx].
There is no default export.

The export map supports the [`development` condition][nodejs-api-conditions].
Run `node --conditions development module.js` to get instrumented dev code.
Without this condition,
production code is loaded.

### `mdxJsx(options?)`

Create an extension for `micromark` to enable MDX JSX syntax.

###### Parameters

* `options`
  ([`Options`][api-options], optional)
  — configuration

###### Returns

Extension for `micromark` that can be passed in `extensions` to enable MDX
JSX syntax ([`Extension`][github-micromark-extension]).

### `Options`

Configuration (TypeScript type).

###### Fields

* `acorn`
  ([`Acorn`][github-acorn], optional)
  — acorn parser to use
* `acornOptions`
  ([`AcornOptions`][github-acorn-options],
  default:
  `{ecmaVersion: 2024, locations: true, sourceType: 'module'}`)
  — configuration for acorn;
  all fields except `locations` can be set
* `addResult`
  (`boolean`, default: `false`)
  — whether to add `estree` fields to tokens with results from acorn

## Authoring

When authoring markdown with JSX,
keep in mind that MDX is a whitespace sensitive and line-based language,
while JavaScript is insensitive to whitespace.
This affects how markdown and JSX interleave with eachother in MDX.
For more info on how it works,
see [§ Interleaving][mdxjs-interleaving] on the MDX site.

###### Comments inside tags

JavaScript comments in JSX are not supported.

Incorrect:

```mdx-invalid
<hi/*comment!*//>
<hello// comment!
/>
```

Correct:

```mdx
<hi/>
<hello
/>
```

A PR that adds support for them would be accepted.

###### Element or fragment attribute values

JSX elements or JSX fragments as attribute values are not supported.
The reason for this change is that it would be confusing whether markdown
would work.

Incorrect:

```mdx-invalid
<welcome name=<>Venus</> />
<welcome name=<span>Pluto</span> />
```

Correct:

```mdx
<welcome name='Mars' />
<welcome name={<span>Jupiter</span>} />
```

###### Greater than (`>`) and right curly brace (`}`)

JSX does not allow U+003E GREATER THAN (`>`) or U+007D RIGHT CURLY BRACE
(`}`) literally in text,
they need to be encoded as character references
(or expressions).
There is no good reason for this (some JSX parsers agree with us and don’t
crash either).
Therefore,
in MDX,
U+003E GREATER THAN (`>`) and U+007D RIGHT CURLY BRACE (`}`) are fine literally
and don’t need to be encoded.

## Syntax

JSX forms with the following BNF:

<!--grammar start-->

<pre><code><a id=x-mdx-jsx-flow href=#x-mdx-jsx-flow>mdx_jsx_flow</a> ::= <a href=#x-mdx-jsx>mdx_jsx</a> *<a href=#x-space-or-tab>space_or_tab</a> [<a href=#x-mdx-jsx>mdx_jsx</a> *<a href=#x-space-or-tab>space_or_tab</a>]
<a id=x-mdx-jsx-text href=#x-mdx-jsx-text>mdx_jsx_text</a> ::= <a href=#x-mdx-jsx>mdx_jsx</a>

; constraint: markdown whitespace (`<a href=#x-space-or-tab>space_or_tab</a> | <a href=#x-eol>eol</a>`) is NOT
; allowed directly after `&lt;` in order to allow `1 &lt; 3` in markdown.
<a id=x-mdx-jsx href=#x-mdx-jsx>mdx_jsx</a> ::=
  '&lt;' [<a href=#x-closing>closing</a>]
  [*<a href=#x-whitespace>whitespace</a> <a href=#x-name>name</a> [<a href=#x-attributes-after-identifier>attributes_after_identifier</a>] [<a href=#x-closing>closing</a>]]
  *<a href=#x-whitespace>whitespace</a> '>'

<a id=x-attributes-after-identifier href=#x-attributes-after-identifier>attributes_after_identifier</a> ::=
  1*<a href=#x-whitespace>whitespace</a> (<a href=#x-attributes-boolean>attributes_boolean</a> | <a href=#x-attributes-value>attributes_value</a>) |
  *<a href=#x-whitespace>whitespace</a> <a href=#x-attributes-expression>attributes_expression</a> |
<a id=x-attributes-after-value href=#x-attributes-after-value>attributes_after_value</a> ::=
  *<a href=#x-whitespace>whitespace</a> (<a href=#x-attributes-boolean>attributes_boolean</a> | <a href=#x-attributes-expression>attributes_expression</a> | <a href=#x-attributes-value>attributes_value</a>)
<a id=x-attributes-boolean href=#x-attributes-boolean>attributes_boolean</a> ::= <a href=#x-key>key</a> [<a href=#x-attributes-after-identifier>attributes_after_identifier</a>]
; Note: in gnostic mode the value of the expression must instead be a single valid ES spread
; expression
<a id=x-attributes-expression href=#x-attributes-expression>attributes_expression</a> ::= <a href=#x-expression>expression</a> [<a href=#x-attributes-after-value>attributes_after_value</a>]
<a id=x-attributes-value href=#x-attributes-value>attributes_value</a> ::= <a href=#x-key>key</a> <a href=#x-initializer>initializer</a> [<a href=#x-attributes-after-value>attributes_after_value</a>]

<a id=x-closing href=#x-closing>closing</a> ::= *<a href=#x-whitespace>whitespace</a> '/'

<a id=x-name href=#x-name>name</a> ::= <a href=#x-identifier>identifier</a> [<a href=#x-local>local</a> | <a href=#x-members>members</a>]
<a id=x-key href=#x-key>key</a> ::= <a href=#x-identifier>identifier</a> [<a href=#x-local>local</a>]
<a id=x-local href=#x-local>local</a> ::= *<a href=#x-whitespace>whitespace</a> ':' *<a href=#x-whitespace>whitespace</a> <a href=#x-identifier>identifier</a>
<a id=x-members href=#x-members>members</a> ::= <a href=#x-member>member</a> *<a href=#x-member>member</a>
<a id=x-member href=#x-member>member</a> ::= *<a href=#x-whitespace>whitespace</a> '.' *<a href=#x-whitespace>whitespace</a> <a href=#x-identifier>identifier</a>

<a id=x-identifier href=#x-identifier>identifier</a> ::= <a href=#x-identifier-start>identifier_start</a> *<a href=#x-identifier-part>identifier_part</a>
<a id=x-initializer href=#x-initializer>initializer</a> ::= *<a href=#x-whitespace>whitespace</a> '=' *<a href=#x-whitespace>whitespace</a> <a href=#x-value>value</a>
<a id=x-value href=#x-value>value</a> ::= <a href=#x-double-quoted>double_quoted</a> | <a href=#x-single-quoted>single_quoted</a> | <a href=#x-expression>expression</a>
; Note: in gnostic mode the value must instead be a single valid ES expression
<a id=x-expression href=#x-expression>expression</a> ::= '{' *(<a href=#x-expression-text>expression_text</a> | <a href=#x-expression>expression</a>) '}'

<a id=x-double-quoted href=#x-double-quoted>double_quoted</a> ::= '"' *<a href=#x-double-quoted-text>double_quoted_text</a> '"'
<a id=x-single-quoted href=#x-single-quoted>single_quoted</a> ::= "'" *<a href=#x-single-quoted-text>single_quoted_text</a> "'"

<a id=x-whitespace href=#x-whitespace>whitespace</a> ::= <a href=#x-es-whitespace>es_whitespace</a>
<a id=x-double-quoted-text href=#x-double-quoted-text>double_quoted_text</a> ::= char - '"'
<a id=x-single-quoted-text href=#x-single-quoted-text>single_quoted_text</a> ::= char - "'"
<a id=x-expression-text href=#x-expression-text>expression_text</a> ::= char - '{' - '}'
<a id=x-identifier-start href=#x-identifier-start>identifier_start</a> ::= <a href=#x-es-identifier-start>es_identifier_start</a>
<a id=x-identifier-part href=#x-identifier-part>identifier_part</a> ::= <a href=#x-es-identifier-part>es_identifier_part</a> | '-'

<a id=x-space-or-tab href=#x-space-or-tab>space_or_tab</a> ::= '\t' | ' '
<a id=x-eol href=#x-eol>eol</a> ::= '\n' | '\r' | '\r\n'

; ECMAScript
; See “IdentifierStart”: &lt;<a href=https://tc39.es/ecma262/#prod-IdentifierStart>https://tc39.es/ecma262/#prod-IdentifierStart</a>>
<a id=x-es-identifier-start href=#x-es-identifier-start>es_identifier_start</a> ::= ?
; See “IdentifierPart”: &lt;<a href=https://tc39.es/ecma262/#prod-IdentifierPart>https://tc39.es/ecma262/#prod-IdentifierPart</a>>
<a id=x-es-identifier-part href=#x-es-identifier-part>es_identifier_part</a> ::= ?
; See “Whitespace”: &lt;<a href=https://tc39.es/ecma262/#prod-WhiteSpace>https://tc39.es/ecma262/#prod-WhiteSpace</a>>
<a id=x-es-whitespace href=#x-es-whitespace>es_whitespace</a> ::= ?
</code></pre>

<!--grammar end-->

As the flow construct occurs in flow,
like all flow constructs,
it must be followed by an eol (line ending) or eof (end of file).

The grammar for JSX in markdown is much stricter than that of HTML in
markdown.
The primary benefit of this is that tags are parsed into tokens,
and thus can be processed.
Another,
arguable,
benefit of this is that it comes with syntax errors:
if an author types something that is nonsensical,
an error is thrown with information about where it happened,
what occurred,
and what was expected instead.

This extension supports expressions both aware and unaware to JavaScript
(respectively gnostic and agnostic).
Depending on whether acorn is passed,
either valid JavaScript must be used in expressions,
or arbitrary text (such as Rust code or so) can be used.

More on this can be found in
[§ Syntax of `micromark-extension-mdx-expression`][github-expression-syntax].

## Errors

In aware (gnostic) mode,
expressions are parsed with
[`micromark-extension-mdx-expression`][github-micromark-expression],
which throws some more errors.

### Unexpected end of file $at, expected $expect

This error occurs for many different reasons if something was opened but not
closed
(source: `micromark-extension-mdx-jsx`, rule id: `unexpected-eof`).

Some examples are:

```mdx-invalid
<
</
<a
<a:
<a.
<a b
<a b:
<a b=
<a b="
<a b='
<a b={
<a/
```

### Unexpected character $at, expected $expect

This error occurs for many different reasons if an unexpected character is seen
(source: `micromark-extension-mdx-jsx`, rule id: `unexpected-character`).

Some examples are:

```mdx-invalid
<.>
</.>
<a?>
<a:+>
<a./>
<a b!>
<a b:1>
<a b=>
<a/->
```

### Unexpected lazy line in container, expected line to be…

This error occurs if a `<` was seen in a container which then has lazy content
(source: `micromark-extension-mdx-jsx`, rule id: `unexpected-lazy`).
For example:

```mdx-invalid
> <a
b>
```

## Tokens

Many tokens are used:

* `mdxJsxFlowTag` for the whole JSX tag (`<a>`)
* `mdxJsxTextTag` ^
* `mdxJsxFlowTagMarker` for the tag markers (`<`, `>`)
* `mdxJsxTextTagMarker` ^
* `mdxJsxFlowTagClosingMarker` for the `/` marking a closing tag (`</a>`)
* `mdxJsxTextTagClosingMarker` ^
* `mdxJsxFlowTagSelfClosingMarker` for the `/` marking a self-closing tag
  (`<a/>`)
* `mdxJsxTextTagSelfClosingMarker` ^
* `mdxJsxFlowTagName` for the whole tag name (`a:b` in `<a:b>`)
* `mdxJsxTextTagName` ^
* `mdxJsxFlowTagNamePrimary` for the first name (`a` in `<a:b>`)
* `mdxJsxTextTagNamePrimary` ^
* `mdxJsxFlowTagNameMemberMarker` for the `.` marking in members (`<a.b>`)
* `mdxJsxTextTagNameMemberMarker` ^
* `mdxJsxFlowTagNameMember` for member names (`b` in `<a:b>`)
* `mdxJsxTextTagNameMember` ^
* `mdxJsxFlowTagNamePrefixMarker` for the `:` between primary and local
  (`<a:b>`)
* `mdxJsxTextTagNamePrefixMarker` ^
* `mdxJsxFlowTagNameLocal` for the local name (`b` in `<a:b>`)
* `mdxJsxTextTagNameLocal` ^
* `mdxJsxFlowTagExpressionAttribute` for whole expression attributes
  (`<a {...b}>`)
* `mdxJsxTextTagExpressionAttribute` ^
* `mdxJsxFlowTagExpressionAttributeMarker` for `{`, `}` in expression
  attributes
* `mdxJsxTextTagExpressionAttributeMarker` ^
* `mdxJsxFlowTagExpressionAttributeValue` for chunks of what’s inside
  expression attributes
* `mdxJsxTextTagExpressionAttributeValue` ^
* `mdxJsxFlowTagAttribute` for a whole normal attribute (`<a b>`)
* `mdxJsxTextTagAttribute` ^
* `mdxJsxFlowTagAttributeName` for the whole name of an attribute (`b:c` in
  `<a b:c>`)
* `mdxJsxTextTagAttributeName` ^
* `mdxJsxFlowTagAttributeNamePrimary` for the first name of an attribute (`b`
  in `<a b:c>`)
* `mdxJsxTextTagAttributeNamePrimary` ^
* `mdxJsxFlowTagAttributeNamePrefixMarker` for the `:` between primary and
  local (`<a b:c>`)
* `mdxJsxTextTagAttributeNamePrefixMarker` ^
* `mdxJsxFlowTagAttributeNameLocal` for the local name of an attribute (`c`
  in `<a b:c>`)
* `mdxJsxTextTagAttributeNameLocal` ^
* `mdxJsxFlowTagAttributeInitializerMarker` for the `=` between an attribute
  name and value
* `mdxJsxTextTagAttributeInitializerMarker` ^
* `mdxJsxFlowTagAttributeValueLiteral` for a string attribute value
  (`<a b="">`)
* `mdxJsxTextTagAttributeValueLiteral` ^
* `mdxJsxFlowTagAttributeValueLiteralMarker` for the quotes around a string
  attribute value (`"` or `'`)
* `mdxJsxTextTagAttributeValueLiteralMarker` ^
* `mdxJsxFlowTagAttributeValueLiteralValue` for chunks of what’s inside
  string attribute values
* `mdxJsxTextTagAttributeValueLiteralValue` ^
* `mdxJsxFlowTagAttributeValueExpression` for an expression attribute value
  (`<a b={1}>`)
* `mdxJsxTextTagAttributeValueExpression` ^
* `mdxJsxFlowTagAttributeValueExpressionMarker` for the `{` and `}` of
  expression attribute values
* `mdxJsxTextTagAttributeValueExpressionMarker` ^
* `mdxJsxFlowTagAttributeValueExpressionValue` for chunks of what’s inside
  expression attribute values
* `mdxJsxTextTagAttributeValueExpressionValue` ^

## Types

This package is fully typed with [TypeScript][].
It exports the additional type [`Options`][api-options].

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release,
we drop support for unmaintained versions of Node.
This means we try to keep the current release line,
`micromark-extension-mdx-jsx@2`,
compatible with Node.js 16.

This package works with `micromark` version `3` and later.

## Security

This package is safe.

## Related

* [`micromark-extension-mdxjs`][github-micromark-extension-mdxjs]
  — support all MDX syntax
* [`mdast-util-mdx-jsx`][github-mdast-util-mdx-jsx]
  — support MDX JSX in mdast
* [`remark-mdx`][mdxjs-remark-mdx]
  — support all MDX syntax in remark

## Contribute

See [`contributing.md` in `micromark/.github`][health-contributing] for ways
to get started.
See [`support.md`][health-support] for ways to get help.

This project has a [code of conduct][health-coc].
By interacting with this repository,
organization,
or community you agree to abide by its terms.

## License

[MIT][file-license] © [Titus Wormer][wooorm]

<!-- Definitions -->

[api-mdx-jsx]: #mdxjsxoptions

[api-options]: #options

[badge-build-image]: https://github.com/micromark/micromark-extension-mdx-jsx/workflows/main/badge.svg

[badge-build-url]: https://github.com/micromark/micromark-extension-mdx-jsx/actions

[badge-coverage-image]: https://img.shields.io/codecov/c/github/micromark/micromark-extension-mdx-jsx.svg

[badge-coverage-url]: https://codecov.io/github/micromark/micromark-extension-mdx-jsx

[badge-downloads-image]: https://img.shields.io/npm/dm/micromark-extension-mdx-jsx.svg

[badge-downloads-url]: https://www.npmjs.com/package/micromark-extension-mdx-jsx

[badge-size-image]: https://img.shields.io/bundlejs/size/micromark-extension-mdx-jsx

[badge-size-url]: https://bundlejs.com/?q=micromark-extension-mdx-jsx

[esmsh]: https://esm.sh

[file-license]: license

[github-acorn]: https://github.com/acornjs/acorn

[github-acorn-options]: https://github.com/acornjs/acorn/blob/96c721dbf89d0ccc3a8c7f39e69ef2a6a3c04dfa/acorn/dist/acorn.d.ts#L16

[github-expression-syntax]: https://github.com/micromark/micromark-extension-mdx-expression/blob/main/packages/micromark-extension-mdx-expression/readme.md#syntax

[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[github-mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown

[github-mdast-util-mdx-jsx]: https://github.com/syntax-tree/mdast-util-mdx-jsx

[github-micromark]: https://github.com/micromark/micromark

[github-micromark-expression]: https://github.com/micromark/micromark-extension-mdx-expression

[github-micromark-extension]: https://github.com/micromark/micromark#syntaxextension

[github-micromark-extension-mdxjs]: https://github.com/micromark/micromark-extension-mdxjs

[health-coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[health-contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[health-support]: https://github.com/micromark/.github/blob/main/support.md

[mdxjs]: https://mdxjs.com

[mdxjs-interleaving]: https://mdxjs.com/docs/what-is-mdx/#interleaving

[mdxjs-remark-mdx]: https://mdxjs.com/packages/remark-mdx/

[nodejs-api-conditions]: https://nodejs.org/api/packages.html#packages_resolving_user_conditions

[npmjs-install]: https://docs.npmjs.com/cli/install

[typescript]: https://www.typescriptlang.org

[wooorm]: https://wooorm.com


---

# micromark-extension-mdx-md

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[micromark][] extension to turn some markdown features off for [MDX][mdxjs].

## Contents

*   [What is this?](#what-is-this)
*   [When to use this](#when-to-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`mdxMd()`](#mdxmd)
*   [Authoring](#authoring)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Security](#security)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package contains an extension to turn off some markdown constructs when
parsing.

## When to use this

This project is useful when you want to disable support for code (indented),
autolinks, and HTML (flow and text) in markdown.

You can use this extension when you are working with [`micromark`][micromark].
To support all MDX features, use
[`micromark-extension-mdxjs`][micromark-extension-mdxjs] instead.

All these packages are used in [`remark-mdx`][remark-mdx], which focusses on
making it easier to transform content by abstracting these internals away.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-extension-mdx-md
```

In Deno with [`esm.sh`][esmsh]:

```js
import {mdxMd} from 'https://esm.sh/micromark-extension-mdx-md@2'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {mdxMd} from 'https://esm.sh/micromark-extension-mdx-md@2?bundle'
</script>
```

## Use

```js
import {micromark} from 'micromark'
import {mdxMd} from 'micromark-extension-mdx-md'

const output = micromark('\ta', {extensions: [mdxMd()]})

console.log(output)
```

Yields:

```html
<p>a</p>
```

## API

This package exports the identifier [`mdxMd`][api-mdx-md].
There is no default export.

### `mdxMd()`

Create an extension for `micromark` to disable some CommonMark syntax (code
(indented), autolinks, and HTML (flow and text)) for MDX.

###### Returns

Extension for `micromark` that can be passed in `extensions` to disable some
CommonMark syntax for MDX ([`Extension`][micromark-extension]).

## Authoring

To improve authoring the new constructs MDX adds (ESM, expressions, and
JSX), some markdown features are turned off by this extension.
There are good alternatives.

###### Code (indented)

Use fenced code instead.
Change the following markdown:

```markdown
    console.log(1)
```

…into:

````markdown
```js
console.log(1)
```
````

###### Autolinks

Use links (with a resource or a reference) instead.
Change the following markdown:

```markdown
<https://some-link-here.com>
```

…into:

```markdown
[descriptive text](https://and-the-link-here.com)
```

###### HTML (flow and text)

Use JSX instead: change `<img>` into `<img />`.
Not supporting HTML also means that HTML comments are not supported.
Use a comment in an empty expression instead.
Change `<!-- comment -->` into `{/* comment */}`.

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, `micromark-extension-mdx-md@^2`,
compatible with Node.js 16.
This package works with `micromark@^3`.

## Security

This package is safe.

## Related

*   [`micromark-extension-mdxjs`][micromark-extension-mdxjs]
    — support all of MDX
*   [`remark-mdx`][remark-mdx]
    — support all of MDX in remark

## Contribute

See [`contributing.md` in `micromark/.github`][contributing] for ways to get
started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark-extension-mdx-md/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark-extension-mdx-md/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark-extension-mdx-md.svg

[coverage]: https://codecov.io/github/micromark/micromark-extension-mdx-md

[downloads-badge]: https://img.shields.io/npm/dm/micromark-extension-mdx-md.svg

[downloads]: https://www.npmjs.com/package/micromark-extension-mdx-md

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-extension-mdx-md

[size]: https://bundlejs.com/?q=micromark-extension-mdx-md

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[npm]: https://docs.npmjs.com/cli/install

[esmsh]: https://esm.sh

[license]: license

[author]: https://wooorm.com

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[typescript]: https://www.typescriptlang.org

[mdxjs]: https://mdxjs.com

[micromark]: https://github.com/micromark/micromark

[micromark-extension]: https://github.com/micromark/micromark#syntaxextension

[micromark-extension-mdxjs]: https://github.com/micromark/micromark-extension-mdxjs

[remark-mdx]: https://mdxjs.com/packages/remark-mdx/

[api-mdx-md]: #mdxmd


---

# micromark-extension-mdxjs

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[micromark][] extensions to support [MDX][mdxjs].

## Contents

*   [What is this?](#what-is-this)
*   [When to use this](#when-to-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`mdxjs(options?)`](#mdxjsoptions)
    *   [`Options`](#options)
*   [Authoring](#authoring)
*   [Syntax](#syntax)
*   [Errors](#errors)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Security](#security)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package contains an extension that adds support for the syntax enabled
by [MDX][mdxjs] to [`micromark`][micromark].
This extension is used inside MDX.
It supports export/imports, expressions, JSX, and turns some markdown features
off.

## When to use this

This project is useful when you want to support MDX.

You can use this extension when you are working with [`micromark`][micromark].

This package is aware of JavaScript syntax.
If you want to be unaware of JavaScript, for example because expressions can
include Rust or variables or whatnot, use
[`micromark-extension-mdx`][micromark-extension-mdx].

Alternatively, you can also use the underlying syntax extensions separately:

*   [`micromark-extension-mdx-expression`][micromark-extension-mdx-expression]
    — support MDX expressions
*   [`micromark-extension-mdx-jsx`][micromark-extension-mdx-jsx]
    — support MDX JSX
*   [`micromark-extension-mdx-md`][micromark-extension-mdx-md]
    — turn some CommonMark features off
*   [`micromark-extension-mdxjs-esm`][micromark-extension-mdxjs-esm]
    — support MDX export/imports

When you need a syntax tree, combine this package with
[`mdast-util-mdx`][mdast-util-mdx].

All these packages are used in [`remark-mdx`][remark-mdx], which focusses on
making it easier to transform content by abstracting these internals away.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-extension-mdxjs
```

In Deno with [`esm.sh`][esmsh]:

```js
import {mdxjs} from 'https://esm.sh/micromark-extension-mdxjs@2'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {mdxjs} from 'https://esm.sh/micromark-extension-mdxjs@2?bundle'
</script>
```

## Use

```js
import {micromark} from 'micromark'
import {mdxjs} from 'micromark-extension-mdxjs'

const output = micromark('import a from "b"\n\na <b /> c {1 + 1} d', {
  extensions: [mdxjs()]
})

console.log(output)
```

Yields:

```html
<p>a  c  d</p>
```

…which is useless: go to a syntax tree with
[`mdast-util-from-markdown`][mdast-util-from-markdown] and
[`mdast-util-mdx`][mdast-util-mdx] instead.

## API

This package exports the identifier [`mdxjs`][api-mdxjs].
There is no default export.

The separate extensions support the [`development` condition][development].
Run `node --conditions development module.js` to get instrumented dev code.
Without this condition, production code is loaded.

### `mdxjs(options?)`

Create an extension for `micromark` to enable MDX syntax.

###### Parameters

*   `options` ([`Options`][api-options], optional)
    — configuration; passed to all extensions

###### Returns

Extension for `micromark` that can be passed in `extensions` to enable MDX
syntax ([`Extension`][micromark-extension]).

### `Options`

Configuration (TypeScript type).

###### Type

```ts
export type {Options} from 'micromark-extension-mdx-expression'
```

See [`Options`][micromark-extension-mdx-expression-options].

## Authoring

For recommendations on how to author MDX, see each corresponding readme:

*   [expressions](https://github.com/micromark/micromark-extension-mdx-expression/tree/main/packages/micromark-extension-mdx-expression#authoring)
*   [JSX](https://github.com/micromark/micromark-extension-mdx-jsx#authoring)
*   [ESM](https://github.com/micromark/micromark-extension-mdxjs-esm#authoring)
*   [CommonMark features not in MDX](https://github.com/micromark/micromark-extension-mdx-md#authoring)

## Syntax

For info on the syntax of these features, see each corresponding readme:

*   [expressions](https://github.com/micromark/micromark-extension-mdx-expression/tree/main/packages/micromark-extension-mdx-expression#syntax)
*   [JSX](https://github.com/micromark/micromark-extension-mdx-jsx#syntax)
*   [ESM](https://github.com/micromark/micromark-extension-mdxjs-esm#syntax)
*   CommonMark features not in MDX: n/a

## Errors

For info on what errors are thrown, see each corresponding readme:

*   [expressions](https://github.com/micromark/micromark-extension-mdx-expression/tree/main/packages/micromark-extension-mdx-expression#errors)
*   [JSX](https://github.com/micromark/micromark-extension-mdx-jsx#errors)
*   [ESM](https://github.com/micromark/micromark-extension-mdxjs-esm#errors)
*   CommonMark features not in MDX: n/a

## Types

This package is fully typed with [TypeScript][].
It exports the additional type [`Options`][api-options].

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-extension-mdxjs@^2`, compatible with Node.js 16.

This package works with `micromark` version `3` and later.

## Security

This package is safe.

## Related

*   [`micromark-extension-mdx`][micromark-extension-mdx]
    — support MDX unaware of JS
*   [`mdast-util-mdx`][mdast-util-mdx]
    — support MDX in mdast
*   [`remark-mdx`][remark-mdx]
    — support MDX syntax in remark

## Contribute

See [`contributing.md` in `micromark/.github`][contributing] for ways to get
started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark-extension-mdxjs/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark-extension-mdxjs/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark-extension-mdxjs.svg

[coverage]: https://codecov.io/github/micromark/micromark-extension-mdxjs

[downloads-badge]: https://img.shields.io/npm/dm/micromark-extension-mdxjs.svg

[downloads]: https://www.npmjs.com/package/micromark-extension-mdxjs

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-extension-mdxjs

[size]: https://bundlejs.com/?q=micromark-extension-mdxjs

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[npm]: https://docs.npmjs.com/cli/install

[esmsh]: https://esm.sh

[license]: license

[author]: https://wooorm.com

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[typescript]: https://www.typescriptlang.org

[development]: https://nodejs.org/api/packages.html#packages_resolving_user_conditions

[micromark]: https://github.com/micromark/micromark

[micromark-extension]: https://github.com/micromark/micromark#syntaxextension

[micromark-extension-mdx]: https://github.com/micromark/micromark-extension-mdx

[micromark-extension-mdx-expression]: https://github.com/micromark/micromark-extension-mdx-expression

[micromark-extension-mdx-jsx]: https://github.com/micromark/micromark-extension-mdx-jsx

[micromark-extension-mdx-md]: https://github.com/micromark/micromark-extension-mdx-md

[micromark-extension-mdxjs-esm]: https://github.com/micromark/micromark-extension-mdxjs-esm

[mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown

[mdast-util-mdx]: https://github.com/syntax-tree/mdast-util-mdx

[remark-mdx]: https://mdxjs.com/packages/remark-mdx/

[mdxjs]: https://mdxjs.com

[api-mdxjs]: #mdxjsoptions

[api-options]: #options

[micromark-extension-mdx-expression-options]: https://github.com/micromark/micromark-extension-mdx-expression/blob/main/packages/micromark-extension-mdx-expression/readme.md#options


---

# micromark-util-character

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility to handle [character codes][code].

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`asciiAlpha(code)`](#asciialphacode)
  * [`asciiAlphanumeric(code)`](#asciialphanumericcode)
  * [`asciiAtext(code)`](#asciiatextcode)
  * [`asciiControl(code)`](#asciicontrolcode)
  * [`asciiDigit(code)`](#asciidigitcode)
  * [`asciiHexDigit(code)`](#asciihexdigitcode)
  * [`asciiPunctuation(code)`](#asciipunctuationcode)
  * [`markdownLineEnding(code)`](#markdownlineendingcode)
  * [`markdownLineEndingOrSpace(code)`](#markdownlineendingorspacecode)
  * [`markdownSpace(code)`](#markdownspacecode)
  * [`unicodePunctuation(code)`](#unicodepunctuationcode)
  * [`unicodeWhitespace(code)`](#unicodewhitespacecode)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes algorithms to check whether characters match groups.

## When should I use this?

This package might be useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-character
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as character from 'https://esm.sh/micromark-util-character@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as character from 'https://esm.sh/micromark-util-character@1?bundle'
</script>
```

## Use

```js
import {asciiAlpha} from 'micromark-util-character'

console.log(asciiAlpha(64)) // false
console.log(asciiAlpha(65)) // true
```

## API

This module exports the identifiers
[`asciiAlpha`][api-ascii-alpha],
[`asciiAlphanumeric`][api-ascii-alphanumeric],
[`asciiAtext`][api-ascii-atext],
[`asciiControl`][api-ascii-control],
[`asciiDigit`][api-ascii-digit],
[`asciiHexDigit`][api-ascii-hex-digit],
[`asciiPunctuation`][api-ascii-punctuation],
[`markdownLineEnding`][api-markdown-line-ending],
[`markdownLineEndingOrSpace`][api-markdown-line-ending-or-space],
[`markdownSpace`][api-markdown-space],
[`unicodePunctuation`][api-unicode-punctuation],
[`unicodeWhitespace`][api-unicode-whitespace].
There is no default export.

### `asciiAlpha(code)`

Check whether the [character code][code] represents an ASCII alpha (`a` through
`z`, case insensitive).

An **ASCII alpha** is an ASCII upper alpha or ASCII lower alpha.

An **ASCII upper alpha** is a character in the inclusive range U+0041 (`A`)
to U+005A (`Z`).

An **ASCII lower alpha** is a character in the inclusive range U+0061 (`a`)
to U+007A (`z`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiAlphanumeric(code)`

Check whether the [character code][code] represents an ASCII alphanumeric (`a`
through `z`, case insensitive, or `0` through `9`).

An **ASCII alphanumeric** is an ASCII digit (see `asciiDigit`) or ASCII alpha
(see `asciiAlpha`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiAtext(code)`

Check whether the [character code][code] represents an ASCII atext.

atext is an ASCII alphanumeric (see `asciiAlphanumeric`), or a character in
the inclusive ranges U+0023 NUMBER SIGN (`#`) to U+0027 APOSTROPHE (`'`),
U+002A ASTERISK (`*`), U+002B PLUS SIGN (`+`), U+002D DASH (`-`), U+002F
SLASH (`/`), U+003D EQUALS TO (`=`), U+003F QUESTION MARK (`?`), U+005E
CARET (`^`) to U+0060 GRAVE ACCENT (`` ` ``), or U+007B LEFT CURLY BRACE
(`{`) to U+007E TILDE (`~`) (**\[RFC5322]**).

See **\[RFC5322]**:\
[Internet Message Format](https://tools.ietf.org/html/rfc5322).\
P. Resnick.\
IETF.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiControl(code)`

Check whether a [character code][code] is an ASCII control character.

An **ASCII control** is a character in the inclusive range U+0000 NULL (NUL)
to U+001F (US), or U+007F (DEL).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiDigit(code)`

Check whether the [character code][code] represents an ASCII digit (`0` through
`9`).

An **ASCII digit** is a character in the inclusive range U+0030 (`0`) to
U+0039 (`9`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiHexDigit(code)`

Check whether the [character code][code] represents an ASCII hex digit (`a`
through `f`, case insensitive, or `0` through `9`).

An **ASCII hex digit** is an ASCII digit (see `asciiDigit`), ASCII upper hex
digit, or an ASCII lower hex digit.

An **ASCII upper hex digit** is a character in the inclusive range U+0041
(`A`) to U+0046 (`F`).

An **ASCII lower hex digit** is a character in the inclusive range U+0061
(`a`) to U+0066 (`f`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiPunctuation(code)`

Check whether the [character code][code] represents ASCII punctuation.

An **ASCII punctuation** is a character in the inclusive ranges U+0021
EXCLAMATION MARK (`!`) to U+002F SLASH (`/`), U+003A COLON (`:`) to U+0040 AT
SIGN (`@`), U+005B LEFT SQUARE BRACKET (`[`) to U+0060 GRAVE ACCENT
(`` ` ``), or U+007B LEFT CURLY BRACE (`{`) to U+007E TILDE (`~`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownLineEnding(code)`

Check whether a [character code][code] is a markdown line ending.

A **markdown line ending** is the virtual characters M-0003 CARRIAGE RETURN
LINE FEED (CRLF), M-0004 LINE FEED (LF) and M-0005 CARRIAGE RETURN (CR).

In micromark, the actual character U+000A LINE FEED (LF) and U+000D CARRIAGE
RETURN (CR) are replaced by these virtual characters depending on whether
they occurred together.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownLineEndingOrSpace(code)`

Check whether a [character code][code] is a markdown line ending (see
`markdownLineEnding`) or markdown space (see `markdownSpace`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownSpace(code)`

Check whether a [character code][code] is a markdown space.

A **markdown space** is the concrete character U+0020 SPACE (SP) and the
virtual characters M-0001 VIRTUAL SPACE (VS) and M-0002 HORIZONTAL TAB (HT).

In micromark, the actual character U+0009 CHARACTER TABULATION (HT) is
replaced by one M-0002 HORIZONTAL TAB (HT) and between 0 and 3 M-0001 VIRTUAL
SPACE (VS) characters, depending on the column at which the tab occurred.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `unicodePunctuation(code)`

Check whether the [character code][code] represents Unicode punctuation.

A **Unicode punctuation** is a character in the Unicode `Pc` (Punctuation,
Connector), `Pd` (Punctuation, Dash), `Pe` (Punctuation, Close), `Pf`
(Punctuation, Final quote), `Pi` (Punctuation, Initial quote), `Po`
(Punctuation, Other), or `Ps` (Punctuation, Open) categories, or an ASCII
punctuation (see `asciiPunctuation`) (**\[UNICODE]**).

See **\[UNICODE]**:\
[The Unicode Standard](https://www.unicode.org/versions/).\
Unicode Consortium.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `unicodeWhitespace(code)`

Check whether the [character code][code] represents Unicode whitespace.

Note that this does handle micromark specific markdown whitespace characters.
See `markdownLineEndingOrSpace` to check that.

A **Unicode whitespace** is a character in the Unicode `Zs` (Separator,
Space) category, or U+0009 CHARACTER TABULATION (HT), U+000A LINE FEED (LF),
U+000C (FF), or U+000D CARRIAGE RETURN (CR) (**\[UNICODE]**).

See **\[UNICODE]**:\
[The Unicode Standard](https://www.unicode.org/versions/).\
Unicode Consortium.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-character@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-character.svg

[downloads]: https://www.npmjs.com/package/micromark-util-character

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-character

[bundle-size]: https://bundlejs.com/?q=micromark-util-character

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[code]: https://github.com/micromark/micromark#preprocess

[api-ascii-alpha]: #asciialphacode

[api-ascii-alphanumeric]: #asciialphanumericcode

[api-ascii-atext]: #asciiatextcode

[api-ascii-control]: #asciicontrolcode

[api-ascii-digit]: #asciidigitcode

[api-ascii-hex-digit]: #asciihexdigitcode

[api-ascii-punctuation]: #asciipunctuationcode

[api-markdown-line-ending]: #markdownlineendingcode

[api-markdown-line-ending-or-space]: #markdownlineendingorspacecode

[api-markdown-space]: #markdownspacecode

[api-unicode-punctuation]: #unicodepunctuationcode

[api-unicode-whitespace]: #unicodewhitespacecode


---

# micromark-util-symbol

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility with symbols.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes constants used throughout the micromark ecosystem.

## When should I use this?

This package is useful when you are making your own micromark extensions.
It’s useful to reference these constants by name instead of value while
developing.
[`micromark-build`][micromark-build] compiles them away for production code.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-symbol
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as symbol from 'https://esm.sh/micromark-util-symbol@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as symbol from 'https://esm.sh/micromark-util-symbol@1?bundle'
</script>
```

## Use

```js
import {codes, constants, types, values} from 'micromark-util-symbol'

console.log(codes.atSign) // 64
console.log(constants.characterReferenceNamedSizeMax) // 31
console.log(types.definitionDestinationRaw) // 'definitionDestinationRaw'
console.log(values.atSign) // '@'
```

## API

This package exports the identifiers `codes`, `constants`, `types`, and
`values`.
There is no default export.

Each identifier is an object mapping strings to values.
See the code for the exposed data.

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-symbol@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-symbol.svg

[downloads]: https://www.npmjs.com/package/micromark-util-symbol

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-symbol

[bundle-size]: https://bundlejs.com/?q=micromark-util-symbol

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[micromark-build]: https://github.com/micromark/micromark/tree/main/packages/micromark-build


---

# micromark-extension-mdxjs-esm

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[micromark][] extension to support [MDX][mdxjs] ESM (`import x from 'y'`).

## Contents

*   [What is this?](#what-is-this)
*   [When to use this](#when-to-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`mdxjsEsm(options)`](#mdxjsesmoptions)
    *   [`Options`](#options)
*   [Authoring](#authoring)
*   [Syntax](#syntax)
*   [Errors](#errors)
    *   [Could not parse import/exports with acorn](#could-not-parse-importexports-with-acorn)
    *   [Unexpected `$type` in code: only import/exports are supported](#unexpected-type-in-code-only-importexports-are-supported)
*   [Tokens](#tokens)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Security](#security)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package contains an extension that adds support for the ESM syntax enabled
by [MDX][mdxjs] to [`micromark`][micromark].
These extensions are used inside MDX.
It matches how imports and exports work in JavaScript through acorn.

This package is aware of JavaScript syntax.

## When to use this

This project is useful when you want to support ESM in markdown.

You can use this extension when you are working with [`micromark`][micromark].
To support all MDX features, use
[`micromark-extension-mdxjs`][micromark-extension-mdxjs] instead.

When you need a syntax tree, combine this package with
[`mdast-util-mdxjs-esm`][mdast-util-mdxjs-esm].

All these packages are used in [`remark-mdx`][remark-mdx], which focusses on
making it easier to transform content by abstracting these internals away.

When you are using [`mdx-js/mdx`][mdxjs], all of this is already included.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-extension-mdxjs-esm
```

In Deno with [`esm.sh`][esmsh]:

```js
import {mdxjsEsm} from 'https://esm.sh/micromark-extension-mdxjs-esm@2'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {mdxjsEsm} from 'https://esm.sh/micromark-extension-mdxjs-esm@2?bundle'
</script>
```

## Use

```js
import {Parser} from 'acorn'
import acornJsx from 'acorn-jsx'
import {micromark} from 'micromark'
import {mdxjsEsm} from 'micromark-extension-mdxjs-esm'

const acorn = Parser.extend(acornJsx())

const output = micromark('import a from "b"\n\n# c', {
  extensions: [mdxjsEsm({acorn})]
})

console.log(output)
```

Yields:

```html
<h1>c</h1>
```

…which is useless: go to a syntax tree with
[`mdast-util-from-markdown`][mdast-util-from-markdown] and
[`mdast-util-mdxjs-esm`][mdast-util-mdxjs-esm] instead.

## API

This package exports the identifier [`mdxjsEsm`][api-mdxjs-esm].
There is no default export.

The export map supports the [`development` condition][development].
Run `node --conditions development module.js` to get instrumented dev code.
Without this condition, production code is loaded.

### `mdxjsEsm(options)`

Create an extension for `micromark` to enable MDX ESM syntax.

###### Parameters

*   `options` ([`Options`][api-options], required)
    — configuration

###### Returns

Extension for `micromark` that can be passed in `extensions` to enable MDX
ESM syntax ([`Extension`][micromark-extension]).

### `Options`

Configuration (TypeScript type).

###### Fields

*   `acorn` ([`Acorn`][acorn], required)
    — acorn parser to use
*   `acornOptions` ([`AcornOptions`][acorn-options], default:
    `{ecmaVersion: 2024, locations: true, sourceType: 'module'}`)
    — configuration for acorn; all fields except `locations` can be set
*   `addResult` (`boolean`, default: `false`)
    — whether to add `estree` fields to tokens with results from acorn

## Authoring

When authoring markdown with ESM, make sure to follow export and import
statements with blank lines before more markdown.

All valid imports and exports are supported, depending on what the given acorn
instance and configuration supports.

When the lowercase strings `export` or `import` are found, followed by a space,
we expect JavaScript.
Otherwise, like normal in markdown, we exit and it’ll end up as a paragraph.
We continue parsing until we find a blank line.
At that point, we parse with acorn: it if parses, we found our block.
Otherwise, if parsing failed at the last character, we assume it’s a blank line
in code: we continue on until the next blank line and try again.
Otherwise, the acorn error is thrown.

Some examples of valid export and import statements:

```mdx
import a from 'b'
import * as a from 'b'
import {a} from 'b'
import {a as b} from 'c'
import a, {b as c} from 'd'
import a, * as b from 'c'
import 'a'

export var a = ''
export const a = ''
export let a = ''
export var a, b
export var a = 'a', b = 'b'
export function a() {}
export class a {}
export var {a} = {}
export var {a: b} = {}
export var [a] = []
export default a = 1
export default function a() {}
export default class a {}
export * from 'a'
export * as a from 'b'
export {a} from 'b'
export {a as b} from 'c'
export {default} from 'b'
export {default as a, b} from 'c'

{/* Blank lines are supported in expressions: */}

export function a() {

  return 'b'

}
```

```mdx-invalid
{/* A blank line must be used after import/exports: this is incorrect! */}

import a from 'b'
## Hello, world!
```

## Syntax

ESM forms with the following BNF:

```bnf
; Restriction: the entire construct must be valid JavaScript.
mdx_esm ::= word ' ' *line *(eol *line)

word ::= 'e' 'x' 'p' 'o' 'r' 't' | 'i' 'm' 'p' 'o' 'r' 't'
```

This construct must be followed by a blank line or eof (end of file).

## Errors

### Could not parse import/exports with acorn

This error occurs if acorn crashes (source: `micromark-extension-mdxjs-esm`,
rule id: `acorn`).
For example:

```mdx-invalid
import 1/1
```

### Unexpected `$type` in code: only import/exports are supported

This error occurs when a non-ESM construct is found (source:
`micromark-extension-mdxjs-esm`, rule id: `non-esm`).
For example:

```mdx-invalid
export var a = 1
var b
```

## Tokens

An `mdxjsEsm` token is used to reflect the block of import/exports in markdown.

It includes:

*   `lineEnding` for the `\r`, `\n`, and `\r\n`
*   `lineEndingBlank` for the same characters but when after potential
    whitespace and another line ending
*   `whitespace` for markdown spaces and tabs in blank lines
*   `mdxjsEsmData` for any character in a line of `mdxjsEsm`

## Types

This package is fully typed with [TypeScript][].
It exports the additional type [`Options`][api-options].

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-extension-mdxjs-esm@^2`, compatible with Node.js 16.

This package works with `micromark` version `3` and later.

## Security

This package is safe.

## Related

*   [`micromark-extension-mdxjs`][micromark-extension-mdxjs]
    — support all MDX syntax
*   [`mdast-util-mdxjs-esm`][mdast-util-mdxjs-esm]
    — support MDX ESM in mdast
*   [`remark-mdx`][remark-mdx]
    — support all MDX syntax in remark

## Contribute

See [`contributing.md` in `micromark/.github`][contributing] for ways to get
started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark-extension-mdxjs-esm/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark-extension-mdxjs-esm/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark-extension-mdxjs-esm.svg

[coverage]: https://codecov.io/github/micromark/micromark-extension-mdxjs-esm

[downloads-badge]: https://img.shields.io/npm/dm/micromark-extension-mdxjs-esm.svg

[downloads]: https://www.npmjs.com/package/micromark-extension-mdxjs-esm

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-extension-mdxjs-esm

[size]: https://bundlejs.com/?q=micromark-extension-mdxjs-esm

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[npm]: https://docs.npmjs.com/cli/install

[esmsh]: https://esm.sh

[license]: license

[author]: https://wooorm.com

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[typescript]: https://www.typescriptlang.org

[development]: https://nodejs.org/api/packages.html#packages_resolving_user_conditions

[micromark]: https://github.com/micromark/micromark

[micromark-extension]: https://github.com/micromark/micromark#syntaxextension

[micromark-extension-mdxjs]: https://github.com/micromark/micromark-extension-mdxjs

[mdast-util-mdxjs-esm]: https://github.com/syntax-tree/mdast-util-mdxjs-esm

[mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown

[remark-mdx]: https://mdxjs.com/packages/remark-mdx/

[mdxjs]: https://mdxjs.com

[acorn]: https://github.com/acornjs/acorn

[acorn-options]: https://github.com/acornjs/acorn/blob/96c721dbf89d0ccc3a8c7f39e69ef2a6a3c04dfa/acorn/dist/acorn.d.ts#L16

[api-mdxjs-esm]: #mdxjsesmoptions

[api-options]: #options


---

# micromark-util-character

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility to handle [character codes][code].

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`asciiAlpha(code)`](#asciialphacode)
  * [`asciiAlphanumeric(code)`](#asciialphanumericcode)
  * [`asciiAtext(code)`](#asciiatextcode)
  * [`asciiControl(code)`](#asciicontrolcode)
  * [`asciiDigit(code)`](#asciidigitcode)
  * [`asciiHexDigit(code)`](#asciihexdigitcode)
  * [`asciiPunctuation(code)`](#asciipunctuationcode)
  * [`markdownLineEnding(code)`](#markdownlineendingcode)
  * [`markdownLineEndingOrSpace(code)`](#markdownlineendingorspacecode)
  * [`markdownSpace(code)`](#markdownspacecode)
  * [`unicodePunctuation(code)`](#unicodepunctuationcode)
  * [`unicodeWhitespace(code)`](#unicodewhitespacecode)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes algorithms to check whether characters match groups.

## When should I use this?

This package might be useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-character
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as character from 'https://esm.sh/micromark-util-character@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as character from 'https://esm.sh/micromark-util-character@1?bundle'
</script>
```

## Use

```js
import {asciiAlpha} from 'micromark-util-character'

console.log(asciiAlpha(64)) // false
console.log(asciiAlpha(65)) // true
```

## API

This module exports the identifiers
[`asciiAlpha`][api-ascii-alpha],
[`asciiAlphanumeric`][api-ascii-alphanumeric],
[`asciiAtext`][api-ascii-atext],
[`asciiControl`][api-ascii-control],
[`asciiDigit`][api-ascii-digit],
[`asciiHexDigit`][api-ascii-hex-digit],
[`asciiPunctuation`][api-ascii-punctuation],
[`markdownLineEnding`][api-markdown-line-ending],
[`markdownLineEndingOrSpace`][api-markdown-line-ending-or-space],
[`markdownSpace`][api-markdown-space],
[`unicodePunctuation`][api-unicode-punctuation],
[`unicodeWhitespace`][api-unicode-whitespace].
There is no default export.

### `asciiAlpha(code)`

Check whether the [character code][code] represents an ASCII alpha (`a` through
`z`, case insensitive).

An **ASCII alpha** is an ASCII upper alpha or ASCII lower alpha.

An **ASCII upper alpha** is a character in the inclusive range U+0041 (`A`)
to U+005A (`Z`).

An **ASCII lower alpha** is a character in the inclusive range U+0061 (`a`)
to U+007A (`z`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiAlphanumeric(code)`

Check whether the [character code][code] represents an ASCII alphanumeric (`a`
through `z`, case insensitive, or `0` through `9`).

An **ASCII alphanumeric** is an ASCII digit (see `asciiDigit`) or ASCII alpha
(see `asciiAlpha`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiAtext(code)`

Check whether the [character code][code] represents an ASCII atext.

atext is an ASCII alphanumeric (see `asciiAlphanumeric`), or a character in
the inclusive ranges U+0023 NUMBER SIGN (`#`) to U+0027 APOSTROPHE (`'`),
U+002A ASTERISK (`*`), U+002B PLUS SIGN (`+`), U+002D DASH (`-`), U+002F
SLASH (`/`), U+003D EQUALS TO (`=`), U+003F QUESTION MARK (`?`), U+005E
CARET (`^`) to U+0060 GRAVE ACCENT (`` ` ``), or U+007B LEFT CURLY BRACE
(`{`) to U+007E TILDE (`~`) (**\[RFC5322]**).

See **\[RFC5322]**:\
[Internet Message Format](https://tools.ietf.org/html/rfc5322).\
P. Resnick.\
IETF.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiControl(code)`

Check whether a [character code][code] is an ASCII control character.

An **ASCII control** is a character in the inclusive range U+0000 NULL (NUL)
to U+001F (US), or U+007F (DEL).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiDigit(code)`

Check whether the [character code][code] represents an ASCII digit (`0` through
`9`).

An **ASCII digit** is a character in the inclusive range U+0030 (`0`) to
U+0039 (`9`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiHexDigit(code)`

Check whether the [character code][code] represents an ASCII hex digit (`a`
through `f`, case insensitive, or `0` through `9`).

An **ASCII hex digit** is an ASCII digit (see `asciiDigit`), ASCII upper hex
digit, or an ASCII lower hex digit.

An **ASCII upper hex digit** is a character in the inclusive range U+0041
(`A`) to U+0046 (`F`).

An **ASCII lower hex digit** is a character in the inclusive range U+0061
(`a`) to U+0066 (`f`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiPunctuation(code)`

Check whether the [character code][code] represents ASCII punctuation.

An **ASCII punctuation** is a character in the inclusive ranges U+0021
EXCLAMATION MARK (`!`) to U+002F SLASH (`/`), U+003A COLON (`:`) to U+0040 AT
SIGN (`@`), U+005B LEFT SQUARE BRACKET (`[`) to U+0060 GRAVE ACCENT
(`` ` ``), or U+007B LEFT CURLY BRACE (`{`) to U+007E TILDE (`~`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownLineEnding(code)`

Check whether a [character code][code] is a markdown line ending.

A **markdown line ending** is the virtual characters M-0003 CARRIAGE RETURN
LINE FEED (CRLF), M-0004 LINE FEED (LF) and M-0005 CARRIAGE RETURN (CR).

In micromark, the actual character U+000A LINE FEED (LF) and U+000D CARRIAGE
RETURN (CR) are replaced by these virtual characters depending on whether
they occurred together.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownLineEndingOrSpace(code)`

Check whether a [character code][code] is a markdown line ending (see
`markdownLineEnding`) or markdown space (see `markdownSpace`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownSpace(code)`

Check whether a [character code][code] is a markdown space.

A **markdown space** is the concrete character U+0020 SPACE (SP) and the
virtual characters M-0001 VIRTUAL SPACE (VS) and M-0002 HORIZONTAL TAB (HT).

In micromark, the actual character U+0009 CHARACTER TABULATION (HT) is
replaced by one M-0002 HORIZONTAL TAB (HT) and between 0 and 3 M-0001 VIRTUAL
SPACE (VS) characters, depending on the column at which the tab occurred.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `unicodePunctuation(code)`

Check whether the [character code][code] represents Unicode punctuation.

A **Unicode punctuation** is a character in the Unicode `Pc` (Punctuation,
Connector), `Pd` (Punctuation, Dash), `Pe` (Punctuation, Close), `Pf`
(Punctuation, Final quote), `Pi` (Punctuation, Initial quote), `Po`
(Punctuation, Other), or `Ps` (Punctuation, Open) categories, or an ASCII
punctuation (see `asciiPunctuation`) (**\[UNICODE]**).

See **\[UNICODE]**:\
[The Unicode Standard](https://www.unicode.org/versions/).\
Unicode Consortium.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `unicodeWhitespace(code)`

Check whether the [character code][code] represents Unicode whitespace.

Note that this does handle micromark specific markdown whitespace characters.
See `markdownLineEndingOrSpace` to check that.

A **Unicode whitespace** is a character in the Unicode `Zs` (Separator,
Space) category, or U+0009 CHARACTER TABULATION (HT), U+000A LINE FEED (LF),
U+000C (FF), or U+000D CARRIAGE RETURN (CR) (**\[UNICODE]**).

See **\[UNICODE]**:\
[The Unicode Standard](https://www.unicode.org/versions/).\
Unicode Consortium.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-character@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-character.svg

[downloads]: https://www.npmjs.com/package/micromark-util-character

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-character

[bundle-size]: https://bundlejs.com/?q=micromark-util-character

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[code]: https://github.com/micromark/micromark#preprocess

[api-ascii-alpha]: #asciialphacode

[api-ascii-alphanumeric]: #asciialphanumericcode

[api-ascii-atext]: #asciiatextcode

[api-ascii-control]: #asciicontrolcode

[api-ascii-digit]: #asciidigitcode

[api-ascii-hex-digit]: #asciihexdigitcode

[api-ascii-punctuation]: #asciipunctuationcode

[api-markdown-line-ending]: #markdownlineendingcode

[api-markdown-line-ending-or-space]: #markdownlineendingorspacecode

[api-markdown-space]: #markdownspacecode

[api-unicode-punctuation]: #unicodepunctuationcode

[api-unicode-whitespace]: #unicodewhitespacecode


---

# micromark-util-symbol

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility with symbols.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes constants used throughout the micromark ecosystem.

## When should I use this?

This package is useful when you are making your own micromark extensions.
It’s useful to reference these constants by name instead of value while
developing.
[`micromark-build`][micromark-build] compiles them away for production code.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-symbol
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as symbol from 'https://esm.sh/micromark-util-symbol@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as symbol from 'https://esm.sh/micromark-util-symbol@1?bundle'
</script>
```

## Use

```js
import {codes, constants, types, values} from 'micromark-util-symbol'

console.log(codes.atSign) // 64
console.log(constants.characterReferenceNamedSizeMax) // 31
console.log(types.definitionDestinationRaw) // 'definitionDestinationRaw'
console.log(values.atSign) // '@'
```

## API

This package exports the identifiers `codes`, `constants`, `types`, and
`values`.
There is no default export.

Each identifier is an object mapping strings to values.
See the code for the exposed data.

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-symbol@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-symbol.svg

[downloads]: https://www.npmjs.com/package/micromark-util-symbol

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-symbol

[bundle-size]: https://bundlejs.com/?q=micromark-util-symbol

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[micromark-build]: https://github.com/micromark/micromark/tree/main/packages/micromark-build


---

# micromark-factory-destination

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] factory to parse destinations (found in resources, definitions).

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`factoryDestination(…)`](#factorydestination)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes states to parse destinations.

## When should I use this?

This package is useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-factory-destination
```

In Deno with [`esm.sh`][esmsh]:

```js
import {factoryDestination} from 'https://esm.sh/micromark-factory-destination@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {factoryDestination} from 'https://esm.sh/micromark-factory-destination@1?bundle'
</script>
```

## Use

```js
import {factoryDestination} from 'micromark-factory-destination'
import {codes, types} from 'micromark-util-symbol'

// A micromark tokenizer that uses the factory:
/**
 * @this {TokenizeContext}
 *   Context.
 * @type {Tokenizer}
 */
function tokenizeResource(effects, ok, nok) {
  return start

  // …

  /** @type {State} */
  function open(code) {
    if (code === codes.rightParenthesis) {
      return end(code)
    }

    return factoryDestination(
      effects,
      destinationAfter,
      nok,
      types.resourceDestination,
      types.resourceDestinationLiteral,
      types.resourceDestinationLiteralMarker,
      types.resourceDestinationRaw,
      types.resourceDestinationString,
      constants.linkResourceDestinationBalanceMax
    )(code)
  }

  // …
}
```

## API

This module exports the identifier
[`factoryDestination`][api-factory-destination].
There is no default export.

### `factoryDestination(…)`

Parse destinations.

###### Examples

```markdown
<a>
<a\>b>
<a b>
<a)>
a
a\)b
a(b)c
a(b)
```

###### Parameters

* `effects` (`Effects`)
  — context
* `ok` (`State`)
  — state switched to when successful
* `nok` (`State`)
  — state switched to when unsuccessful
* `type` (`string`)
  — type for whole (`<a>` or `b`)
* `literalType` (`string`)
  — type when enclosed (`<a>`)
* `literalMarkerType` (`string`)
  — type for enclosing (`<` and `>`)
* `rawType` (`string`)
  — type when not enclosed (`b`)
* `stringType` (`string`)
  — type for the value (`a` or `b`)
* `max` (`number`, default: `Infinity`)
  — depth of nested parens (inclusive)

###### Returns

Start state (`State`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-factory-destination@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-factory-destination.svg

[downloads]: https://www.npmjs.com/package/micromark-factory-destination

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-factory-destination

[bundle-size]: https://bundlejs.com/?q=micromark-factory-destination

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[api-factory-destination]: #factorydestination


---

# micromark-util-character

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility to handle [character codes][code].

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`asciiAlpha(code)`](#asciialphacode)
  * [`asciiAlphanumeric(code)`](#asciialphanumericcode)
  * [`asciiAtext(code)`](#asciiatextcode)
  * [`asciiControl(code)`](#asciicontrolcode)
  * [`asciiDigit(code)`](#asciidigitcode)
  * [`asciiHexDigit(code)`](#asciihexdigitcode)
  * [`asciiPunctuation(code)`](#asciipunctuationcode)
  * [`markdownLineEnding(code)`](#markdownlineendingcode)
  * [`markdownLineEndingOrSpace(code)`](#markdownlineendingorspacecode)
  * [`markdownSpace(code)`](#markdownspacecode)
  * [`unicodePunctuation(code)`](#unicodepunctuationcode)
  * [`unicodeWhitespace(code)`](#unicodewhitespacecode)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes algorithms to check whether characters match groups.

## When should I use this?

This package might be useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-character
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as character from 'https://esm.sh/micromark-util-character@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as character from 'https://esm.sh/micromark-util-character@1?bundle'
</script>
```

## Use

```js
import {asciiAlpha} from 'micromark-util-character'

console.log(asciiAlpha(64)) // false
console.log(asciiAlpha(65)) // true
```

## API

This module exports the identifiers
[`asciiAlpha`][api-ascii-alpha],
[`asciiAlphanumeric`][api-ascii-alphanumeric],
[`asciiAtext`][api-ascii-atext],
[`asciiControl`][api-ascii-control],
[`asciiDigit`][api-ascii-digit],
[`asciiHexDigit`][api-ascii-hex-digit],
[`asciiPunctuation`][api-ascii-punctuation],
[`markdownLineEnding`][api-markdown-line-ending],
[`markdownLineEndingOrSpace`][api-markdown-line-ending-or-space],
[`markdownSpace`][api-markdown-space],
[`unicodePunctuation`][api-unicode-punctuation],
[`unicodeWhitespace`][api-unicode-whitespace].
There is no default export.

### `asciiAlpha(code)`

Check whether the [character code][code] represents an ASCII alpha (`a` through
`z`, case insensitive).

An **ASCII alpha** is an ASCII upper alpha or ASCII lower alpha.

An **ASCII upper alpha** is a character in the inclusive range U+0041 (`A`)
to U+005A (`Z`).

An **ASCII lower alpha** is a character in the inclusive range U+0061 (`a`)
to U+007A (`z`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiAlphanumeric(code)`

Check whether the [character code][code] represents an ASCII alphanumeric (`a`
through `z`, case insensitive, or `0` through `9`).

An **ASCII alphanumeric** is an ASCII digit (see `asciiDigit`) or ASCII alpha
(see `asciiAlpha`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiAtext(code)`

Check whether the [character code][code] represents an ASCII atext.

atext is an ASCII alphanumeric (see `asciiAlphanumeric`), or a character in
the inclusive ranges U+0023 NUMBER SIGN (`#`) to U+0027 APOSTROPHE (`'`),
U+002A ASTERISK (`*`), U+002B PLUS SIGN (`+`), U+002D DASH (`-`), U+002F
SLASH (`/`), U+003D EQUALS TO (`=`), U+003F QUESTION MARK (`?`), U+005E
CARET (`^`) to U+0060 GRAVE ACCENT (`` ` ``), or U+007B LEFT CURLY BRACE
(`{`) to U+007E TILDE (`~`) (**\[RFC5322]**).

See **\[RFC5322]**:\
[Internet Message Format](https://tools.ietf.org/html/rfc5322).\
P. Resnick.\
IETF.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiControl(code)`

Check whether a [character code][code] is an ASCII control character.

An **ASCII control** is a character in the inclusive range U+0000 NULL (NUL)
to U+001F (US), or U+007F (DEL).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiDigit(code)`

Check whether the [character code][code] represents an ASCII digit (`0` through
`9`).

An **ASCII digit** is a character in the inclusive range U+0030 (`0`) to
U+0039 (`9`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiHexDigit(code)`

Check whether the [character code][code] represents an ASCII hex digit (`a`
through `f`, case insensitive, or `0` through `9`).

An **ASCII hex digit** is an ASCII digit (see `asciiDigit`), ASCII upper hex
digit, or an ASCII lower hex digit.

An **ASCII upper hex digit** is a character in the inclusive range U+0041
(`A`) to U+0046 (`F`).

An **ASCII lower hex digit** is a character in the inclusive range U+0061
(`a`) to U+0066 (`f`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiPunctuation(code)`

Check whether the [character code][code] represents ASCII punctuation.

An **ASCII punctuation** is a character in the inclusive ranges U+0021
EXCLAMATION MARK (`!`) to U+002F SLASH (`/`), U+003A COLON (`:`) to U+0040 AT
SIGN (`@`), U+005B LEFT SQUARE BRACKET (`[`) to U+0060 GRAVE ACCENT
(`` ` ``), or U+007B LEFT CURLY BRACE (`{`) to U+007E TILDE (`~`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownLineEnding(code)`

Check whether a [character code][code] is a markdown line ending.

A **markdown line ending** is the virtual characters M-0003 CARRIAGE RETURN
LINE FEED (CRLF), M-0004 LINE FEED (LF) and M-0005 CARRIAGE RETURN (CR).

In micromark, the actual character U+000A LINE FEED (LF) and U+000D CARRIAGE
RETURN (CR) are replaced by these virtual characters depending on whether
they occurred together.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownLineEndingOrSpace(code)`

Check whether a [character code][code] is a markdown line ending (see
`markdownLineEnding`) or markdown space (see `markdownSpace`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownSpace(code)`

Check whether a [character code][code] is a markdown space.

A **markdown space** is the concrete character U+0020 SPACE (SP) and the
virtual characters M-0001 VIRTUAL SPACE (VS) and M-0002 HORIZONTAL TAB (HT).

In micromark, the actual character U+0009 CHARACTER TABULATION (HT) is
replaced by one M-0002 HORIZONTAL TAB (HT) and between 0 and 3 M-0001 VIRTUAL
SPACE (VS) characters, depending on the column at which the tab occurred.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `unicodePunctuation(code)`

Check whether the [character code][code] represents Unicode punctuation.

A **Unicode punctuation** is a character in the Unicode `Pc` (Punctuation,
Connector), `Pd` (Punctuation, Dash), `Pe` (Punctuation, Close), `Pf`
(Punctuation, Final quote), `Pi` (Punctuation, Initial quote), `Po`
(Punctuation, Other), or `Ps` (Punctuation, Open) categories, or an ASCII
punctuation (see `asciiPunctuation`) (**\[UNICODE]**).

See **\[UNICODE]**:\
[The Unicode Standard](https://www.unicode.org/versions/).\
Unicode Consortium.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `unicodeWhitespace(code)`

Check whether the [character code][code] represents Unicode whitespace.

Note that this does handle micromark specific markdown whitespace characters.
See `markdownLineEndingOrSpace` to check that.

A **Unicode whitespace** is a character in the Unicode `Zs` (Separator,
Space) category, or U+0009 CHARACTER TABULATION (HT), U+000A LINE FEED (LF),
U+000C (FF), or U+000D CARRIAGE RETURN (CR) (**\[UNICODE]**).

See **\[UNICODE]**:\
[The Unicode Standard](https://www.unicode.org/versions/).\
Unicode Consortium.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-character@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-character.svg

[downloads]: https://www.npmjs.com/package/micromark-util-character

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-character

[bundle-size]: https://bundlejs.com/?q=micromark-util-character

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[code]: https://github.com/micromark/micromark#preprocess

[api-ascii-alpha]: #asciialphacode

[api-ascii-alphanumeric]: #asciialphanumericcode

[api-ascii-atext]: #asciiatextcode

[api-ascii-control]: #asciicontrolcode

[api-ascii-digit]: #asciidigitcode

[api-ascii-hex-digit]: #asciihexdigitcode

[api-ascii-punctuation]: #asciipunctuationcode

[api-markdown-line-ending]: #markdownlineendingcode

[api-markdown-line-ending-or-space]: #markdownlineendingorspacecode

[api-markdown-space]: #markdownspacecode

[api-unicode-punctuation]: #unicodepunctuationcode

[api-unicode-whitespace]: #unicodewhitespacecode


---

# micromark-util-symbol

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility with symbols.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes constants used throughout the micromark ecosystem.

## When should I use this?

This package is useful when you are making your own micromark extensions.
It’s useful to reference these constants by name instead of value while
developing.
[`micromark-build`][micromark-build] compiles them away for production code.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-symbol
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as symbol from 'https://esm.sh/micromark-util-symbol@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as symbol from 'https://esm.sh/micromark-util-symbol@1?bundle'
</script>
```

## Use

```js
import {codes, constants, types, values} from 'micromark-util-symbol'

console.log(codes.atSign) // 64
console.log(constants.characterReferenceNamedSizeMax) // 31
console.log(types.definitionDestinationRaw) // 'definitionDestinationRaw'
console.log(values.atSign) // '@'
```

## API

This package exports the identifiers `codes`, `constants`, `types`, and
`values`.
There is no default export.

Each identifier is an object mapping strings to values.
See the code for the exposed data.

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-symbol@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-symbol.svg

[downloads]: https://www.npmjs.com/package/micromark-util-symbol

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-symbol

[bundle-size]: https://bundlejs.com/?q=micromark-util-symbol

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[micromark-build]: https://github.com/micromark/micromark/tree/main/packages/micromark-build


---

# micromark-factory-label

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] factory to parse labels (found in media, definitions).

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`factoryLabel(…)`](#factorylabel)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes states to parse labels.

## When should I use this?

This package is useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-factory-label
```

In Deno with [`esm.sh`][esmsh]:

```js
import {factoryLabel} from 'https://esm.sh/micromark-factory-label@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {factoryLabel} from 'https://esm.sh/micromark-factory-label@1?bundle'
</script>
```

## Use

```js
import {ok as assert} from 'devlop'
import {factoryLabel} from 'micromark-factory-label'
import {codes, types} from 'micromark-util-symbol'

// A micromark tokenizer that uses the factory:
/**
 * @this {TokenizeContext}
 *   Context.
 * @type {Tokenizer}
 */
function tokenizeDefinition(effects, ok, nok) {
  return start

  // …

  /** @type {State} */
  function start(code) {
    assert(code === codes.leftSquareBracket, 'expected `[`')
    effects.enter(types.definition)
    return factoryLabel.call(
      self,
      effects,
      labelAfter,
      nok,
      types.definitionLabel,
      types.definitionLabelMarker,
      types.definitionLabelString
    )(code)
  }

  // …
}
```

## API

This module exports the identifier [`factoryLabel`][api-factory-label].
There is no default export.

### `factoryLabel(…)`

Parse labels.

> 👉 **Note**: labels in markdown are capped at 999 characters in the string.

###### Examples

```markdown
[a]
[a
b]
[a\]b]
```

###### Parameters

* `this` (`TokenizeContext`)
  — tokenize context
* `effects` (`Effects`)
  — context
* `ok` (`State`)
  — state switched to when successful
* `nok` (`State`)
  — state switched to when unsuccessful
* `type` (`string`)
  — type of the whole label (`[a]`)
* `markerType` (`string`)
  — type for the markers (`[` and `]`)
* `stringType` (`string`)
  — type for the identifier (`a`)

###### Returns

Start state (`State`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-factory-label@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-factory-label.svg

[downloads]: https://www.npmjs.com/package/micromark-factory-label

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-factory-label

[bundle-size]: https://bundlejs.com/?q=micromark-factory-label

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[api-factory-label]: #factorylabel


---

# micromark-factory-space

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] factory to parse [markdown space][markdown-space] (found in lots
of places).

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`factorySpace(…)`](#factoryspace)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes states to parse spaces and/or tabs.

## When should I use this?

This package is useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-factory-space
```

In Deno with [`esm.sh`][esmsh]:

```js
import {factorySpace} from 'https://esm.sh/micromark-factory-space@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {factorySpace} from 'https://esm.sh/micromark-factory-space@1?bundle'
</script>
```

## Use

```js
import {factorySpace} from 'micromark-factory-space'
import {codes, types} from 'micromark-util-symbol'

// A micromark tokenizer that uses the factory:
/**
 * @this {TokenizeContext}
 *   Context.
 * @type {Tokenizer}
 */
function tokenizeCodeFenced(effects, ok, nok) {
  return start

  // …

  /** @type {State} */
  function info(code) {
    if (code === codes.eof || markdownLineEndingOrSpace(code)) {
      effects.exit(types.chunkString)
      effects.exit(types.codeFencedFenceInfo)
      return factorySpace(effects, infoAfter, types.whitespace)(code)
    }

    if (code === codes.graveAccent && code === marker) return nok(code)
    effects.consume(code)
    return info
  }

  // …
}
```

## API

This module exports the identifier [`factorySpace`][api-factory-space].
There is no default export.

### `factorySpace(…)`

Parse spaces and tabs.

There is no `nok` parameter:

* spaces in markdown are often optional, in which case this factory can be
  used and `ok` will be switched to whether spaces were found or not
* one line ending or space can be detected with `markdownSpace(code)` right
  before using `factorySpace`

###### Examples

Where `␉` represents a tab (plus how much it expands) and `␠` represents a
single space.

```markdown
␉
␠␠␠␠
␉␠
```

###### Parameters

* `effects` (`Effects`)
  — context
* `ok` (`State`)
  — state switched to when successful
* `type` (`string`)
  — type (`' \t'`)
* `max` (`number`, default: `Infinity`)
  — max (exclusive)

###### Returns

Start state (`State`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-factory-space@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-factory-space.svg

[downloads]: https://www.npmjs.com/package/micromark-factory-space

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-factory-space

[bundle-size]: https://bundlejs.com/?q=micromark-factory-space

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[markdown-space]: https://github.com/micromark/micromark/tree/main/packages/micromark-util-character#markdownspacecode

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[api-factory-space]: #factoryspace


---

# micromark-util-character

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility to handle [character codes][code].

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`asciiAlpha(code)`](#asciialphacode)
  * [`asciiAlphanumeric(code)`](#asciialphanumericcode)
  * [`asciiAtext(code)`](#asciiatextcode)
  * [`asciiControl(code)`](#asciicontrolcode)
  * [`asciiDigit(code)`](#asciidigitcode)
  * [`asciiHexDigit(code)`](#asciihexdigitcode)
  * [`asciiPunctuation(code)`](#asciipunctuationcode)
  * [`markdownLineEnding(code)`](#markdownlineendingcode)
  * [`markdownLineEndingOrSpace(code)`](#markdownlineendingorspacecode)
  * [`markdownSpace(code)`](#markdownspacecode)
  * [`unicodePunctuation(code)`](#unicodepunctuationcode)
  * [`unicodeWhitespace(code)`](#unicodewhitespacecode)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes algorithms to check whether characters match groups.

## When should I use this?

This package might be useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-character
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as character from 'https://esm.sh/micromark-util-character@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as character from 'https://esm.sh/micromark-util-character@1?bundle'
</script>
```

## Use

```js
import {asciiAlpha} from 'micromark-util-character'

console.log(asciiAlpha(64)) // false
console.log(asciiAlpha(65)) // true
```

## API

This module exports the identifiers
[`asciiAlpha`][api-ascii-alpha],
[`asciiAlphanumeric`][api-ascii-alphanumeric],
[`asciiAtext`][api-ascii-atext],
[`asciiControl`][api-ascii-control],
[`asciiDigit`][api-ascii-digit],
[`asciiHexDigit`][api-ascii-hex-digit],
[`asciiPunctuation`][api-ascii-punctuation],
[`markdownLineEnding`][api-markdown-line-ending],
[`markdownLineEndingOrSpace`][api-markdown-line-ending-or-space],
[`markdownSpace`][api-markdown-space],
[`unicodePunctuation`][api-unicode-punctuation],
[`unicodeWhitespace`][api-unicode-whitespace].
There is no default export.

### `asciiAlpha(code)`

Check whether the [character code][code] represents an ASCII alpha (`a` through
`z`, case insensitive).

An **ASCII alpha** is an ASCII upper alpha or ASCII lower alpha.

An **ASCII upper alpha** is a character in the inclusive range U+0041 (`A`)
to U+005A (`Z`).

An **ASCII lower alpha** is a character in the inclusive range U+0061 (`a`)
to U+007A (`z`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiAlphanumeric(code)`

Check whether the [character code][code] represents an ASCII alphanumeric (`a`
through `z`, case insensitive, or `0` through `9`).

An **ASCII alphanumeric** is an ASCII digit (see `asciiDigit`) or ASCII alpha
(see `asciiAlpha`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiAtext(code)`

Check whether the [character code][code] represents an ASCII atext.

atext is an ASCII alphanumeric (see `asciiAlphanumeric`), or a character in
the inclusive ranges U+0023 NUMBER SIGN (`#`) to U+0027 APOSTROPHE (`'`),
U+002A ASTERISK (`*`), U+002B PLUS SIGN (`+`), U+002D DASH (`-`), U+002F
SLASH (`/`), U+003D EQUALS TO (`=`), U+003F QUESTION MARK (`?`), U+005E
CARET (`^`) to U+0060 GRAVE ACCENT (`` ` ``), or U+007B LEFT CURLY BRACE
(`{`) to U+007E TILDE (`~`) (**\[RFC5322]**).

See **\[RFC5322]**:\
[Internet Message Format](https://tools.ietf.org/html/rfc5322).\
P. Resnick.\
IETF.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiControl(code)`

Check whether a [character code][code] is an ASCII control character.

An **ASCII control** is a character in the inclusive range U+0000 NULL (NUL)
to U+001F (US), or U+007F (DEL).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiDigit(code)`

Check whether the [character code][code] represents an ASCII digit (`0` through
`9`).

An **ASCII digit** is a character in the inclusive range U+0030 (`0`) to
U+0039 (`9`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiHexDigit(code)`

Check whether the [character code][code] represents an ASCII hex digit (`a`
through `f`, case insensitive, or `0` through `9`).

An **ASCII hex digit** is an ASCII digit (see `asciiDigit`), ASCII upper hex
digit, or an ASCII lower hex digit.

An **ASCII upper hex digit** is a character in the inclusive range U+0041
(`A`) to U+0046 (`F`).

An **ASCII lower hex digit** is a character in the inclusive range U+0061
(`a`) to U+0066 (`f`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiPunctuation(code)`

Check whether the [character code][code] represents ASCII punctuation.

An **ASCII punctuation** is a character in the inclusive ranges U+0021
EXCLAMATION MARK (`!`) to U+002F SLASH (`/`), U+003A COLON (`:`) to U+0040 AT
SIGN (`@`), U+005B LEFT SQUARE BRACKET (`[`) to U+0060 GRAVE ACCENT
(`` ` ``), or U+007B LEFT CURLY BRACE (`{`) to U+007E TILDE (`~`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownLineEnding(code)`

Check whether a [character code][code] is a markdown line ending.

A **markdown line ending** is the virtual characters M-0003 CARRIAGE RETURN
LINE FEED (CRLF), M-0004 LINE FEED (LF) and M-0005 CARRIAGE RETURN (CR).

In micromark, the actual character U+000A LINE FEED (LF) and U+000D CARRIAGE
RETURN (CR) are replaced by these virtual characters depending on whether
they occurred together.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownLineEndingOrSpace(code)`

Check whether a [character code][code] is a markdown line ending (see
`markdownLineEnding`) or markdown space (see `markdownSpace`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownSpace(code)`

Check whether a [character code][code] is a markdown space.

A **markdown space** is the concrete character U+0020 SPACE (SP) and the
virtual characters M-0001 VIRTUAL SPACE (VS) and M-0002 HORIZONTAL TAB (HT).

In micromark, the actual character U+0009 CHARACTER TABULATION (HT) is
replaced by one M-0002 HORIZONTAL TAB (HT) and between 0 and 3 M-0001 VIRTUAL
SPACE (VS) characters, depending on the column at which the tab occurred.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `unicodePunctuation(code)`

Check whether the [character code][code] represents Unicode punctuation.

A **Unicode punctuation** is a character in the Unicode `Pc` (Punctuation,
Connector), `Pd` (Punctuation, Dash), `Pe` (Punctuation, Close), `Pf`
(Punctuation, Final quote), `Pi` (Punctuation, Initial quote), `Po`
(Punctuation, Other), or `Ps` (Punctuation, Open) categories, or an ASCII
punctuation (see `asciiPunctuation`) (**\[UNICODE]**).

See **\[UNICODE]**:\
[The Unicode Standard](https://www.unicode.org/versions/).\
Unicode Consortium.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `unicodeWhitespace(code)`

Check whether the [character code][code] represents Unicode whitespace.

Note that this does handle micromark specific markdown whitespace characters.
See `markdownLineEndingOrSpace` to check that.

A **Unicode whitespace** is a character in the Unicode `Zs` (Separator,
Space) category, or U+0009 CHARACTER TABULATION (HT), U+000A LINE FEED (LF),
U+000C (FF), or U+000D CARRIAGE RETURN (CR) (**\[UNICODE]**).

See **\[UNICODE]**:\
[The Unicode Standard](https://www.unicode.org/versions/).\
Unicode Consortium.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-character@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-character.svg

[downloads]: https://www.npmjs.com/package/micromark-util-character

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-character

[bundle-size]: https://bundlejs.com/?q=micromark-util-character

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[code]: https://github.com/micromark/micromark#preprocess

[api-ascii-alpha]: #asciialphacode

[api-ascii-alphanumeric]: #asciialphanumericcode

[api-ascii-atext]: #asciiatextcode

[api-ascii-control]: #asciicontrolcode

[api-ascii-digit]: #asciidigitcode

[api-ascii-hex-digit]: #asciihexdigitcode

[api-ascii-punctuation]: #asciipunctuationcode

[api-markdown-line-ending]: #markdownlineendingcode

[api-markdown-line-ending-or-space]: #markdownlineendingorspacecode

[api-markdown-space]: #markdownspacecode

[api-unicode-punctuation]: #unicodepunctuationcode

[api-unicode-whitespace]: #unicodewhitespacecode


---

# micromark-util-symbol

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility with symbols.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes constants used throughout the micromark ecosystem.

## When should I use this?

This package is useful when you are making your own micromark extensions.
It’s useful to reference these constants by name instead of value while
developing.
[`micromark-build`][micromark-build] compiles them away for production code.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-symbol
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as symbol from 'https://esm.sh/micromark-util-symbol@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as symbol from 'https://esm.sh/micromark-util-symbol@1?bundle'
</script>
```

## Use

```js
import {codes, constants, types, values} from 'micromark-util-symbol'

console.log(codes.atSign) // 64
console.log(constants.characterReferenceNamedSizeMax) // 31
console.log(types.definitionDestinationRaw) // 'definitionDestinationRaw'
console.log(values.atSign) // '@'
```

## API

This package exports the identifiers `codes`, `constants`, `types`, and
`values`.
There is no default export.

Each identifier is an object mapping strings to values.
See the code for the exposed data.

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-symbol@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-symbol.svg

[downloads]: https://www.npmjs.com/package/micromark-util-symbol

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-symbol

[bundle-size]: https://bundlejs.com/?q=micromark-util-symbol

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[micromark-build]: https://github.com/micromark/micromark/tree/main/packages/micromark-build


---

# micromark-factory-mdx-expression

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] factory to parse MDX expressions (found in JSX attributes, flow,
text).

## Contents

* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`factoryMdxExpression(…)`](#factorymdxexpression)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-factory-mdx-expression
```

In Deno with [`esm.sh`][esmsh]:

```js
import {factoryMdxExpression} from 'https://esm.sh/micromark-factory-mdx-expression@2'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {factoryMdxExpression} from 'https://esm.sh/micromark-factory-mdx-expression@2?bundle'
</script>
```

## Use

```js
import {ok as assert} from 'devlop'
import {factoryMdxExpression} from 'micromark-factory-mdx-expression'
import {codes} from 'micromark-util-symbol'

// A micromark tokenizer that uses the factory:
/** @type {Tokenizer} */
function tokenizeFlowExpression(effects, ok, nok) {
  return start

  // …

  /** @type {State} */
  function start(code) {
    assert(code === codes.leftCurlyBrace, 'expected `{`')
    return factoryMdxExpression.call(
      self,
      effects,
      factorySpace(effects, after, types.whitespace),
      'mdxFlowExpression',
      'mdxFlowExpressionMarker',
      'mdxFlowExpressionChunk',
      acorn,
      acornOptions,
      addResult,
      spread,
      allowEmpty
    )(code)
  }

  // …
}
```

## API

This module exports the identifier
[`factoryMdxExpression`][api-factory-mdx-expression].
There is no default export.

The export map supports the [`development` condition][development].
Run `node --conditions development module.js` to get instrumented dev code.
Without this condition, production code is loaded.

### `factoryMdxExpression(…)`

###### Parameters

* `effects` (`Effects`)
  — context
* `ok` (`State`)
  — state switched to when successful
* `type` (`string`)
  — token type for whole (`{}`)
* `markerType` (`string`)
  — token type for the markers (`{`, `}`)
* `chunkType` (`string`)
  — token type for the value (`1`)
* `acorn` (`Acorn`)
  — object with `acorn.parse` and `acorn.parseExpressionAt`
* `acornOptions` ([`AcornOptions`][acorn-options])
  — configuration for acorn
* `boolean` (`addResult`, default: `false`)
  — add `estree` to token
* `boolean` (`spread`, default: `false`)
  — support a spread (`{...a}`) only
* `boolean` (`allowEmpty`, default: `false`)
  — support an empty expression
* `boolean` (`allowLazy`, default: `false`)
  — support lazy continuation of an expression

###### Returns

`State`.

## Types

This package is fully typed with [TypeScript][].
It exports the additional types [`Acorn`][acorn] and
[`AcornOptions`][acorn-options].

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-factory-mdx-expression@^2`, compatible with Node.js 16.

This package works with `micromark` version `3` and later.

## Security

This package is safe.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[acorn]: https://github.com/acornjs/acorn

[acorn-options]: https://github.com/acornjs/acorn/blob/96c721dbf89d0ccc3a8c7f39e69ef2a6a3c04dfa/acorn/dist/acorn.d.ts#L16

[api-factory-mdx-expression]: #micromark-factory-mdx-expression

[author]: https://wooorm.com

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[build]: https://github.com/micromark/micromark-extension-mdx-expression/actions

[build-badge]: https://github.com/micromark/micromark-extension-mdx-expression/workflows/main/badge.svg

[chat]: https://github.com/micromark/micromark/discussions

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[coverage]: https://codecov.io/github/micromark/micromark-extension-mdx-expression

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark-extension-mdx-expression.svg

[development]: https://nodejs.org/api/packages.html#packages_resolving_user_conditions

[downloads]: https://www.npmjs.com/package/micromark-factory-mdx-expression

[downloads-badge]: https://img.shields.io/npm/dm/micromark-factory-mdx-expression.svg

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[health]: https://github.com/micromark/.github

[license]: https://github.com/micromark/micromark-extension-mdx-expression/blob/main/license

[micromark]: https://github.com/micromark/micromark

[npm]: https://docs.npmjs.com/cli/install

[opencollective]: https://opencollective.com/unified

[size]: https://bundlejs.com/?q=micromark-factory-mdx-expression

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-factory-mdx-expression

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[support]: https://github.com/micromark/.github/blob/main/support.md

[typescript]: https://www.typescriptlang.org


---

# micromark-util-types

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility package with TypeScript types.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Security](#security)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package exposes TypeScript types shared throughout the micromark
ecosystem.

## When should I use this?

This package is useful when you are making your own, typed, micromark
extensions.

## Install

In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-types
```

In Deno with [`esm.sh`][esmsh]:

```js
import type {Point, /* … */} from 'https://esm.sh/micromark-util-types@1'
```

## Use

```js
/**
 * @typedef {import('micromark-util-types').Point} Point
 */
```

## API

This module exports no identifiers.
There is no default export.

See [the code][code] for all about the exposed types.

## Types

This package is just [TypeScript][] types.
It exports lots of different types.

## Compatibility

Projects maintained by the unified collective are compatible with all maintained
versions of Node.js.
As of now, that is Node.js 16+.
Our projects sometimes work with older versions, but this is not guaranteed.

This package work with `micromark` version 3+.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-encode.svg

[downloads]: https://www.npmjs.com/package/micromark-util-encode

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-encode

[bundle-size]: https://bundlejs.com/?q=micromark-util-encode

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[code]: https://github.com/micromark/micromark/blob/main/packages/micromark-util-types/index.d.ts


---

# micromark-factory-space

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] factory to parse [markdown space][markdown-space] (found in lots
of places).

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`factorySpace(…)`](#factoryspace)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Security](#security)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package exposes states to parse spaces and/or tabs.

## When should I use this?

This package is useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-factory-space
```

In Deno with [`esm.sh`][esmsh]:

```js
import {factorySpace} from 'https://esm.sh/micromark-factory-space@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {factorySpace} from 'https://esm.sh/micromark-factory-space@1?bundle'
</script>
```

## Use

```js
import {factorySpace} from 'micromark-factory-space'
import {codes} from 'micromark-util-symbol/codes'
import {types} from 'micromark-util-symbol/types'

// A micromark tokenizer that uses the factory:
/**
 * @this {TokenizeContext}
 * @type {Tokenizer}
 */
function tokenizeCodeFenced(effects, ok, nok) {
  return start

  // …

  /** @type {State} */
  function info(code) {
    if (code === codes.eof || markdownLineEndingOrSpace(code)) {
      effects.exit(types.chunkString)
      effects.exit(types.codeFencedFenceInfo)
      return factorySpace(effects, infoAfter, types.whitespace)(code)
    }

    if (code === codes.graveAccent && code === marker) return nok(code)
    effects.consume(code)
    return info
  }

  // …
}
```

## API

This module exports the identifier [`factorySpace`][api-factory-space].
There is no default export.

### `factorySpace(…)`

Parse spaces and tabs.

There is no `nok` parameter:

*   spaces in markdown are often optional, in which case this factory can be
    used and `ok` will be switched to whether spaces were found or not
*   one line ending or space can be detected with `markdownSpace(code)` right
    before using `factorySpace`

###### Examples

Where `␉` represents a tab (plus how much it expands) and `␠` represents a
single space.

```markdown
␉
␠␠␠␠
␉␠
```

###### Parameters

*   `effects` (`Effects`)
    — context
*   `ok` (`State`)
    — state switched to when successful
*   `type` (`string`)
    — type (`' \t'`)
*   `max` (`number`, default: `Infinity`)
    — max (exclusive)

###### Returns

Start state (`State`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with all maintained
versions of Node.js.
As of now, that is Node.js 16+.
Our projects sometimes work with older versions, but this is not guaranteed.

This package works with `micromark` version 3+.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-factory-space.svg

[downloads]: https://www.npmjs.com/package/micromark-factory-space

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-factory-space

[bundle-size]: https://bundlejs.com/?q=micromark-factory-space

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[markdown-space]: https://github.com/micromark/micromark/tree/main/packages/micromark-util-character#markdownspacecode

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[api-factory-space]: #factoryspace


---

# micromark-factory-space

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] factory to parse [markdown space][markdown-space] (found in lots
of places).

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`factorySpace(…)`](#factoryspace)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes states to parse spaces and/or tabs.

## When should I use this?

This package is useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-factory-space
```

In Deno with [`esm.sh`][esmsh]:

```js
import {factorySpace} from 'https://esm.sh/micromark-factory-space@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {factorySpace} from 'https://esm.sh/micromark-factory-space@1?bundle'
</script>
```

## Use

```js
import {factorySpace} from 'micromark-factory-space'
import {codes, types} from 'micromark-util-symbol'

// A micromark tokenizer that uses the factory:
/**
 * @this {TokenizeContext}
 *   Context.
 * @type {Tokenizer}
 */
function tokenizeCodeFenced(effects, ok, nok) {
  return start

  // …

  /** @type {State} */
  function info(code) {
    if (code === codes.eof || markdownLineEndingOrSpace(code)) {
      effects.exit(types.chunkString)
      effects.exit(types.codeFencedFenceInfo)
      return factorySpace(effects, infoAfter, types.whitespace)(code)
    }

    if (code === codes.graveAccent && code === marker) return nok(code)
    effects.consume(code)
    return info
  }

  // …
}
```

## API

This module exports the identifier [`factorySpace`][api-factory-space].
There is no default export.

### `factorySpace(…)`

Parse spaces and tabs.

There is no `nok` parameter:

* spaces in markdown are often optional, in which case this factory can be
  used and `ok` will be switched to whether spaces were found or not
* one line ending or space can be detected with `markdownSpace(code)` right
  before using `factorySpace`

###### Examples

Where `␉` represents a tab (plus how much it expands) and `␠` represents a
single space.

```markdown
␉
␠␠␠␠
␉␠
```

###### Parameters

* `effects` (`Effects`)
  — context
* `ok` (`State`)
  — state switched to when successful
* `type` (`string`)
  — type (`' \t'`)
* `max` (`number`, default: `Infinity`)
  — max (exclusive)

###### Returns

Start state (`State`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-factory-space@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-factory-space.svg

[downloads]: https://www.npmjs.com/package/micromark-factory-space

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-factory-space

[bundle-size]: https://bundlejs.com/?q=micromark-factory-space

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[markdown-space]: https://github.com/micromark/micromark/tree/main/packages/micromark-util-character#markdownspacecode

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[api-factory-space]: #factoryspace


---

# micromark-util-character

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility to handle [character codes][code].

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`asciiAlpha(code)`](#asciialphacode)
  * [`asciiAlphanumeric(code)`](#asciialphanumericcode)
  * [`asciiAtext(code)`](#asciiatextcode)
  * [`asciiControl(code)`](#asciicontrolcode)
  * [`asciiDigit(code)`](#asciidigitcode)
  * [`asciiHexDigit(code)`](#asciihexdigitcode)
  * [`asciiPunctuation(code)`](#asciipunctuationcode)
  * [`markdownLineEnding(code)`](#markdownlineendingcode)
  * [`markdownLineEndingOrSpace(code)`](#markdownlineendingorspacecode)
  * [`markdownSpace(code)`](#markdownspacecode)
  * [`unicodePunctuation(code)`](#unicodepunctuationcode)
  * [`unicodeWhitespace(code)`](#unicodewhitespacecode)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes algorithms to check whether characters match groups.

## When should I use this?

This package might be useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-character
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as character from 'https://esm.sh/micromark-util-character@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as character from 'https://esm.sh/micromark-util-character@1?bundle'
</script>
```

## Use

```js
import {asciiAlpha} from 'micromark-util-character'

console.log(asciiAlpha(64)) // false
console.log(asciiAlpha(65)) // true
```

## API

This module exports the identifiers
[`asciiAlpha`][api-ascii-alpha],
[`asciiAlphanumeric`][api-ascii-alphanumeric],
[`asciiAtext`][api-ascii-atext],
[`asciiControl`][api-ascii-control],
[`asciiDigit`][api-ascii-digit],
[`asciiHexDigit`][api-ascii-hex-digit],
[`asciiPunctuation`][api-ascii-punctuation],
[`markdownLineEnding`][api-markdown-line-ending],
[`markdownLineEndingOrSpace`][api-markdown-line-ending-or-space],
[`markdownSpace`][api-markdown-space],
[`unicodePunctuation`][api-unicode-punctuation],
[`unicodeWhitespace`][api-unicode-whitespace].
There is no default export.

### `asciiAlpha(code)`

Check whether the [character code][code] represents an ASCII alpha (`a` through
`z`, case insensitive).

An **ASCII alpha** is an ASCII upper alpha or ASCII lower alpha.

An **ASCII upper alpha** is a character in the inclusive range U+0041 (`A`)
to U+005A (`Z`).

An **ASCII lower alpha** is a character in the inclusive range U+0061 (`a`)
to U+007A (`z`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiAlphanumeric(code)`

Check whether the [character code][code] represents an ASCII alphanumeric (`a`
through `z`, case insensitive, or `0` through `9`).

An **ASCII alphanumeric** is an ASCII digit (see `asciiDigit`) or ASCII alpha
(see `asciiAlpha`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiAtext(code)`

Check whether the [character code][code] represents an ASCII atext.

atext is an ASCII alphanumeric (see `asciiAlphanumeric`), or a character in
the inclusive ranges U+0023 NUMBER SIGN (`#`) to U+0027 APOSTROPHE (`'`),
U+002A ASTERISK (`*`), U+002B PLUS SIGN (`+`), U+002D DASH (`-`), U+002F
SLASH (`/`), U+003D EQUALS TO (`=`), U+003F QUESTION MARK (`?`), U+005E
CARET (`^`) to U+0060 GRAVE ACCENT (`` ` ``), or U+007B LEFT CURLY BRACE
(`{`) to U+007E TILDE (`~`) (**\[RFC5322]**).

See **\[RFC5322]**:\
[Internet Message Format](https://tools.ietf.org/html/rfc5322).\
P. Resnick.\
IETF.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiControl(code)`

Check whether a [character code][code] is an ASCII control character.

An **ASCII control** is a character in the inclusive range U+0000 NULL (NUL)
to U+001F (US), or U+007F (DEL).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiDigit(code)`

Check whether the [character code][code] represents an ASCII digit (`0` through
`9`).

An **ASCII digit** is a character in the inclusive range U+0030 (`0`) to
U+0039 (`9`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiHexDigit(code)`

Check whether the [character code][code] represents an ASCII hex digit (`a`
through `f`, case insensitive, or `0` through `9`).

An **ASCII hex digit** is an ASCII digit (see `asciiDigit`), ASCII upper hex
digit, or an ASCII lower hex digit.

An **ASCII upper hex digit** is a character in the inclusive range U+0041
(`A`) to U+0046 (`F`).

An **ASCII lower hex digit** is a character in the inclusive range U+0061
(`a`) to U+0066 (`f`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiPunctuation(code)`

Check whether the [character code][code] represents ASCII punctuation.

An **ASCII punctuation** is a character in the inclusive ranges U+0021
EXCLAMATION MARK (`!`) to U+002F SLASH (`/`), U+003A COLON (`:`) to U+0040 AT
SIGN (`@`), U+005B LEFT SQUARE BRACKET (`[`) to U+0060 GRAVE ACCENT
(`` ` ``), or U+007B LEFT CURLY BRACE (`{`) to U+007E TILDE (`~`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownLineEnding(code)`

Check whether a [character code][code] is a markdown line ending.

A **markdown line ending** is the virtual characters M-0003 CARRIAGE RETURN
LINE FEED (CRLF), M-0004 LINE FEED (LF) and M-0005 CARRIAGE RETURN (CR).

In micromark, the actual character U+000A LINE FEED (LF) and U+000D CARRIAGE
RETURN (CR) are replaced by these virtual characters depending on whether
they occurred together.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownLineEndingOrSpace(code)`

Check whether a [character code][code] is a markdown line ending (see
`markdownLineEnding`) or markdown space (see `markdownSpace`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownSpace(code)`

Check whether a [character code][code] is a markdown space.

A **markdown space** is the concrete character U+0020 SPACE (SP) and the
virtual characters M-0001 VIRTUAL SPACE (VS) and M-0002 HORIZONTAL TAB (HT).

In micromark, the actual character U+0009 CHARACTER TABULATION (HT) is
replaced by one M-0002 HORIZONTAL TAB (HT) and between 0 and 3 M-0001 VIRTUAL
SPACE (VS) characters, depending on the column at which the tab occurred.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `unicodePunctuation(code)`

Check whether the [character code][code] represents Unicode punctuation.

A **Unicode punctuation** is a character in the Unicode `Pc` (Punctuation,
Connector), `Pd` (Punctuation, Dash), `Pe` (Punctuation, Close), `Pf`
(Punctuation, Final quote), `Pi` (Punctuation, Initial quote), `Po`
(Punctuation, Other), or `Ps` (Punctuation, Open) categories, or an ASCII
punctuation (see `asciiPunctuation`) (**\[UNICODE]**).

See **\[UNICODE]**:\
[The Unicode Standard](https://www.unicode.org/versions/).\
Unicode Consortium.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `unicodeWhitespace(code)`

Check whether the [character code][code] represents Unicode whitespace.

Note that this does handle micromark specific markdown whitespace characters.
See `markdownLineEndingOrSpace` to check that.

A **Unicode whitespace** is a character in the Unicode `Zs` (Separator,
Space) category, or U+0009 CHARACTER TABULATION (HT), U+000A LINE FEED (LF),
U+000C (FF), or U+000D CARRIAGE RETURN (CR) (**\[UNICODE]**).

See **\[UNICODE]**:\
[The Unicode Standard](https://www.unicode.org/versions/).\
Unicode Consortium.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-character@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-character.svg

[downloads]: https://www.npmjs.com/package/micromark-util-character

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-character

[bundle-size]: https://bundlejs.com/?q=micromark-util-character

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[code]: https://github.com/micromark/micromark#preprocess

[api-ascii-alpha]: #asciialphacode

[api-ascii-alphanumeric]: #asciialphanumericcode

[api-ascii-atext]: #asciiatextcode

[api-ascii-control]: #asciicontrolcode

[api-ascii-digit]: #asciidigitcode

[api-ascii-hex-digit]: #asciihexdigitcode

[api-ascii-punctuation]: #asciipunctuationcode

[api-markdown-line-ending]: #markdownlineendingcode

[api-markdown-line-ending-or-space]: #markdownlineendingorspacecode

[api-markdown-space]: #markdownspacecode

[api-unicode-punctuation]: #unicodepunctuationcode

[api-unicode-whitespace]: #unicodewhitespacecode


---

# micromark-util-symbol

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility with symbols.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes constants used throughout the micromark ecosystem.

## When should I use this?

This package is useful when you are making your own micromark extensions.
It’s useful to reference these constants by name instead of value while
developing.
[`micromark-build`][micromark-build] compiles them away for production code.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-symbol
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as symbol from 'https://esm.sh/micromark-util-symbol@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as symbol from 'https://esm.sh/micromark-util-symbol@1?bundle'
</script>
```

## Use

```js
import {codes, constants, types, values} from 'micromark-util-symbol'

console.log(codes.atSign) // 64
console.log(constants.characterReferenceNamedSizeMax) // 31
console.log(types.definitionDestinationRaw) // 'definitionDestinationRaw'
console.log(values.atSign) // '@'
```

## API

This package exports the identifiers `codes`, `constants`, `types`, and
`values`.
There is no default export.

Each identifier is an object mapping strings to values.
See the code for the exposed data.

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-symbol@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-symbol.svg

[downloads]: https://www.npmjs.com/package/micromark-util-symbol

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-symbol

[bundle-size]: https://bundlejs.com/?q=micromark-util-symbol

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[micromark-build]: https://github.com/micromark/micromark/tree/main/packages/micromark-build


---

# micromark-factory-title

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] factory to parse markdown titles (found in resources,
definitions).

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`factoryTitle(…)`](#factorytitle)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes states to parse titles.

## When should I use this?

This package is useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-factory-title
```

In Deno with [`esm.sh`][esmsh]:

```js
import {factorySpace} from 'https://esm.sh/micromark-factory-title@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {factorySpace} from 'https://esm.sh/micromark-factory-title@1?bundle'
</script>
```

## Use

```js
import {factoryTitle} from 'micromark-factory-title'
import {codes, types} from 'micromark-util-symbol'

// A micromark tokenizer that uses the factory:
/**
 * @this {TokenizeContext}
 *   Context.
 * @type {Tokenizer}
 */
function tokenizeDefinition(effects, ok, nok) {
  return start

  // …

  /** @type {State} */
  function before(code) {
    if (
      code === codes.quotationMark ||
      code === codes.apostrophe ||
      code === codes.leftParenthesis
    ) {
      return factoryTitle(
        effects,
        factorySpace(effects, after, types.whitespace),
        nok,
        types.definitionTitle,
        types.definitionTitleMarker,
        types.definitionTitleString
      )(code)
    }

    return nok(code)
  }

  // …
}
```

## API

This module exports the identifier [`factoryTitle`][api-factory-title].
There is no default export.

### `factoryTitle(…)`

Parse titles.

###### Examples

```markdown
"a"
'b'
(c)
"a
b"
'a
    b'
(a\)b)
```

###### Parameters

* `effects` (`Effects`)
  — context
* `ok` (`State`)
  — state switched to when successful
* `nok` (`State`)
  — state switched to when unsuccessful
* `type` (`string`)
  — type of the whole title (`"a"`, `'b'`, `(c)`)
* `markerType` (`string`)
  — type for the markers (`"`, `'`, `(`, and `)`)
* `stringType` (`string`)
  — type for the value (`a`)

###### Returns

Start state (`State`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-factory-title@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-factory-title.svg

[downloads]: https://www.npmjs.com/package/micromark-factory-title

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-factory-title

[bundle-size]: https://bundlejs.com/?q=micromark-factory-title

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[api-factory-title]: #factorytitle


---

# micromark-factory-space

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] factory to parse [markdown space][markdown-space] (found in lots
of places).

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`factorySpace(…)`](#factoryspace)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes states to parse spaces and/or tabs.

## When should I use this?

This package is useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-factory-space
```

In Deno with [`esm.sh`][esmsh]:

```js
import {factorySpace} from 'https://esm.sh/micromark-factory-space@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {factorySpace} from 'https://esm.sh/micromark-factory-space@1?bundle'
</script>
```

## Use

```js
import {factorySpace} from 'micromark-factory-space'
import {codes, types} from 'micromark-util-symbol'

// A micromark tokenizer that uses the factory:
/**
 * @this {TokenizeContext}
 *   Context.
 * @type {Tokenizer}
 */
function tokenizeCodeFenced(effects, ok, nok) {
  return start

  // …

  /** @type {State} */
  function info(code) {
    if (code === codes.eof || markdownLineEndingOrSpace(code)) {
      effects.exit(types.chunkString)
      effects.exit(types.codeFencedFenceInfo)
      return factorySpace(effects, infoAfter, types.whitespace)(code)
    }

    if (code === codes.graveAccent && code === marker) return nok(code)
    effects.consume(code)
    return info
  }

  // …
}
```

## API

This module exports the identifier [`factorySpace`][api-factory-space].
There is no default export.

### `factorySpace(…)`

Parse spaces and tabs.

There is no `nok` parameter:

* spaces in markdown are often optional, in which case this factory can be
  used and `ok` will be switched to whether spaces were found or not
* one line ending or space can be detected with `markdownSpace(code)` right
  before using `factorySpace`

###### Examples

Where `␉` represents a tab (plus how much it expands) and `␠` represents a
single space.

```markdown
␉
␠␠␠␠
␉␠
```

###### Parameters

* `effects` (`Effects`)
  — context
* `ok` (`State`)
  — state switched to when successful
* `type` (`string`)
  — type (`' \t'`)
* `max` (`number`, default: `Infinity`)
  — max (exclusive)

###### Returns

Start state (`State`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-factory-space@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-factory-space.svg

[downloads]: https://www.npmjs.com/package/micromark-factory-space

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-factory-space

[bundle-size]: https://bundlejs.com/?q=micromark-factory-space

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[markdown-space]: https://github.com/micromark/micromark/tree/main/packages/micromark-util-character#markdownspacecode

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[api-factory-space]: #factoryspace


---

# micromark-util-character

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility to handle [character codes][code].

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`asciiAlpha(code)`](#asciialphacode)
  * [`asciiAlphanumeric(code)`](#asciialphanumericcode)
  * [`asciiAtext(code)`](#asciiatextcode)
  * [`asciiControl(code)`](#asciicontrolcode)
  * [`asciiDigit(code)`](#asciidigitcode)
  * [`asciiHexDigit(code)`](#asciihexdigitcode)
  * [`asciiPunctuation(code)`](#asciipunctuationcode)
  * [`markdownLineEnding(code)`](#markdownlineendingcode)
  * [`markdownLineEndingOrSpace(code)`](#markdownlineendingorspacecode)
  * [`markdownSpace(code)`](#markdownspacecode)
  * [`unicodePunctuation(code)`](#unicodepunctuationcode)
  * [`unicodeWhitespace(code)`](#unicodewhitespacecode)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes algorithms to check whether characters match groups.

## When should I use this?

This package might be useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-character
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as character from 'https://esm.sh/micromark-util-character@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as character from 'https://esm.sh/micromark-util-character@1?bundle'
</script>
```

## Use

```js
import {asciiAlpha} from 'micromark-util-character'

console.log(asciiAlpha(64)) // false
console.log(asciiAlpha(65)) // true
```

## API

This module exports the identifiers
[`asciiAlpha`][api-ascii-alpha],
[`asciiAlphanumeric`][api-ascii-alphanumeric],
[`asciiAtext`][api-ascii-atext],
[`asciiControl`][api-ascii-control],
[`asciiDigit`][api-ascii-digit],
[`asciiHexDigit`][api-ascii-hex-digit],
[`asciiPunctuation`][api-ascii-punctuation],
[`markdownLineEnding`][api-markdown-line-ending],
[`markdownLineEndingOrSpace`][api-markdown-line-ending-or-space],
[`markdownSpace`][api-markdown-space],
[`unicodePunctuation`][api-unicode-punctuation],
[`unicodeWhitespace`][api-unicode-whitespace].
There is no default export.

### `asciiAlpha(code)`

Check whether the [character code][code] represents an ASCII alpha (`a` through
`z`, case insensitive).

An **ASCII alpha** is an ASCII upper alpha or ASCII lower alpha.

An **ASCII upper alpha** is a character in the inclusive range U+0041 (`A`)
to U+005A (`Z`).

An **ASCII lower alpha** is a character in the inclusive range U+0061 (`a`)
to U+007A (`z`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiAlphanumeric(code)`

Check whether the [character code][code] represents an ASCII alphanumeric (`a`
through `z`, case insensitive, or `0` through `9`).

An **ASCII alphanumeric** is an ASCII digit (see `asciiDigit`) or ASCII alpha
(see `asciiAlpha`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiAtext(code)`

Check whether the [character code][code] represents an ASCII atext.

atext is an ASCII alphanumeric (see `asciiAlphanumeric`), or a character in
the inclusive ranges U+0023 NUMBER SIGN (`#`) to U+0027 APOSTROPHE (`'`),
U+002A ASTERISK (`*`), U+002B PLUS SIGN (`+`), U+002D DASH (`-`), U+002F
SLASH (`/`), U+003D EQUALS TO (`=`), U+003F QUESTION MARK (`?`), U+005E
CARET (`^`) to U+0060 GRAVE ACCENT (`` ` ``), or U+007B LEFT CURLY BRACE
(`{`) to U+007E TILDE (`~`) (**\[RFC5322]**).

See **\[RFC5322]**:\
[Internet Message Format](https://tools.ietf.org/html/rfc5322).\
P. Resnick.\
IETF.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiControl(code)`

Check whether a [character code][code] is an ASCII control character.

An **ASCII control** is a character in the inclusive range U+0000 NULL (NUL)
to U+001F (US), or U+007F (DEL).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiDigit(code)`

Check whether the [character code][code] represents an ASCII digit (`0` through
`9`).

An **ASCII digit** is a character in the inclusive range U+0030 (`0`) to
U+0039 (`9`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiHexDigit(code)`

Check whether the [character code][code] represents an ASCII hex digit (`a`
through `f`, case insensitive, or `0` through `9`).

An **ASCII hex digit** is an ASCII digit (see `asciiDigit`), ASCII upper hex
digit, or an ASCII lower hex digit.

An **ASCII upper hex digit** is a character in the inclusive range U+0041
(`A`) to U+0046 (`F`).

An **ASCII lower hex digit** is a character in the inclusive range U+0061
(`a`) to U+0066 (`f`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiPunctuation(code)`

Check whether the [character code][code] represents ASCII punctuation.

An **ASCII punctuation** is a character in the inclusive ranges U+0021
EXCLAMATION MARK (`!`) to U+002F SLASH (`/`), U+003A COLON (`:`) to U+0040 AT
SIGN (`@`), U+005B LEFT SQUARE BRACKET (`[`) to U+0060 GRAVE ACCENT
(`` ` ``), or U+007B LEFT CURLY BRACE (`{`) to U+007E TILDE (`~`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownLineEnding(code)`

Check whether a [character code][code] is a markdown line ending.

A **markdown line ending** is the virtual characters M-0003 CARRIAGE RETURN
LINE FEED (CRLF), M-0004 LINE FEED (LF) and M-0005 CARRIAGE RETURN (CR).

In micromark, the actual character U+000A LINE FEED (LF) and U+000D CARRIAGE
RETURN (CR) are replaced by these virtual characters depending on whether
they occurred together.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownLineEndingOrSpace(code)`

Check whether a [character code][code] is a markdown line ending (see
`markdownLineEnding`) or markdown space (see `markdownSpace`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownSpace(code)`

Check whether a [character code][code] is a markdown space.

A **markdown space** is the concrete character U+0020 SPACE (SP) and the
virtual characters M-0001 VIRTUAL SPACE (VS) and M-0002 HORIZONTAL TAB (HT).

In micromark, the actual character U+0009 CHARACTER TABULATION (HT) is
replaced by one M-0002 HORIZONTAL TAB (HT) and between 0 and 3 M-0001 VIRTUAL
SPACE (VS) characters, depending on the column at which the tab occurred.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `unicodePunctuation(code)`

Check whether the [character code][code] represents Unicode punctuation.

A **Unicode punctuation** is a character in the Unicode `Pc` (Punctuation,
Connector), `Pd` (Punctuation, Dash), `Pe` (Punctuation, Close), `Pf`
(Punctuation, Final quote), `Pi` (Punctuation, Initial quote), `Po`
(Punctuation, Other), or `Ps` (Punctuation, Open) categories, or an ASCII
punctuation (see `asciiPunctuation`) (**\[UNICODE]**).

See **\[UNICODE]**:\
[The Unicode Standard](https://www.unicode.org/versions/).\
Unicode Consortium.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `unicodeWhitespace(code)`

Check whether the [character code][code] represents Unicode whitespace.

Note that this does handle micromark specific markdown whitespace characters.
See `markdownLineEndingOrSpace` to check that.

A **Unicode whitespace** is a character in the Unicode `Zs` (Separator,
Space) category, or U+0009 CHARACTER TABULATION (HT), U+000A LINE FEED (LF),
U+000C (FF), or U+000D CARRIAGE RETURN (CR) (**\[UNICODE]**).

See **\[UNICODE]**:\
[The Unicode Standard](https://www.unicode.org/versions/).\
Unicode Consortium.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-character@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-character.svg

[downloads]: https://www.npmjs.com/package/micromark-util-character

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-character

[bundle-size]: https://bundlejs.com/?q=micromark-util-character

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[code]: https://github.com/micromark/micromark#preprocess

[api-ascii-alpha]: #asciialphacode

[api-ascii-alphanumeric]: #asciialphanumericcode

[api-ascii-atext]: #asciiatextcode

[api-ascii-control]: #asciicontrolcode

[api-ascii-digit]: #asciidigitcode

[api-ascii-hex-digit]: #asciihexdigitcode

[api-ascii-punctuation]: #asciipunctuationcode

[api-markdown-line-ending]: #markdownlineendingcode

[api-markdown-line-ending-or-space]: #markdownlineendingorspacecode

[api-markdown-space]: #markdownspacecode

[api-unicode-punctuation]: #unicodepunctuationcode

[api-unicode-whitespace]: #unicodewhitespacecode


---

# micromark-util-symbol

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility with symbols.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes constants used throughout the micromark ecosystem.

## When should I use this?

This package is useful when you are making your own micromark extensions.
It’s useful to reference these constants by name instead of value while
developing.
[`micromark-build`][micromark-build] compiles them away for production code.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-symbol
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as symbol from 'https://esm.sh/micromark-util-symbol@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as symbol from 'https://esm.sh/micromark-util-symbol@1?bundle'
</script>
```

## Use

```js
import {codes, constants, types, values} from 'micromark-util-symbol'

console.log(codes.atSign) // 64
console.log(constants.characterReferenceNamedSizeMax) // 31
console.log(types.definitionDestinationRaw) // 'definitionDestinationRaw'
console.log(values.atSign) // '@'
```

## API

This package exports the identifiers `codes`, `constants`, `types`, and
`values`.
There is no default export.

Each identifier is an object mapping strings to values.
See the code for the exposed data.

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-symbol@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-symbol.svg

[downloads]: https://www.npmjs.com/package/micromark-util-symbol

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-symbol

[bundle-size]: https://bundlejs.com/?q=micromark-util-symbol

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[micromark-build]: https://github.com/micromark/micromark/tree/main/packages/micromark-build


---

# micromark-factory-whitespace

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] factory to parse [markdown line endings or spaces][ws] (found in
lots of places).

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`factoryWhitespace(…)`](#factorywhitespace)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes states to parse whitespace.

## When should I use this?

This package is useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-factory-whitespace
```

In Deno with [`esm.sh`][esmsh]:

```js
import {factoryWhitespace} from 'https://esm.sh/micromark-factory-whitespace@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {factoryWhitespace} from 'https://esm.sh/micromark-factory-whitespace@1?bundle'
</script>
```

## Use

```js
import {factoryWhitespace} from 'micromark-factory-whitespace'
import {codes, types} from 'micromark-util-symbol'

// A micromark tokenizer that uses the factory:
/**
 * @this {TokenizeContext}
 *   Context.
 * @type {Tokenizer}
 */
function tokenizeTitle(effects, ok, nok) {
  return start

  /** @type {State} */
  function start(code) {
    return markdownLineEndingOrSpace(code)
      ? factoryWhitespace(effects, before)(code)
      : nok(code)
  }

  // …
}
```

## API

This module exports the identifier
[`factoryWhitespace`][api-factory-whitespace].
There is no default export.

### `factoryWhitespace(…)`

Parse spaces and tabs.

There is no `nok` parameter:

* line endings or spaces in markdown are often optional, in which case this
  factory can be used and `ok` will be switched to whether spaces were found
  or not
* one line ending or space can be detected with
  [`markdownLineEndingOrSpace(code)`][ws] right before using
  `factoryWhitespace`

###### Parameters

* `effects` (`Effects`)
  — context
* `ok` (`State`)
  — state switched to when successful

###### Returns

Start state (`State`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-factory-whitespace@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-factory-whitespace.svg

[downloads]: https://www.npmjs.com/package/micromark-factory-whitespace

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-factory-whitespace

[bundle-size]: https://bundlejs.com/?q=micromark-factory-whitespace

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[ws]: https://github.com/micromark/micromark/tree/main/packages/micromark-util-character#markdownlineendingorspacecode

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[api-factory-whitespace]: #factorywhitespace


---

# micromark-util-types

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility package with TypeScript types.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Security](#security)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package exposes TypeScript types shared throughout the micromark
ecosystem.

## When should I use this?

This package is useful when you are making your own, typed, micromark
extensions.

## Install

In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-types
```

In Deno with [`esm.sh`][esmsh]:

```js
import type {Point, /* … */} from 'https://esm.sh/micromark-util-types@1'
```

## Use

```js
/**
 * @typedef {import('micromark-util-types').Point} Point
 */
```

## API

This module exports no identifiers.
There is no default export.

See [the code][code] for all about the exposed types.

## Types

This package is just [TypeScript][] types.
It exports lots of different types.

## Compatibility

Projects maintained by the unified collective are compatible with all maintained
versions of Node.js.
As of now, that is Node.js 16+.
Our projects sometimes work with older versions, but this is not guaranteed.

This package work with `micromark` version 3+.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-encode.svg

[downloads]: https://www.npmjs.com/package/micromark-util-encode

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-encode

[bundle-size]: https://bundlejs.com/?q=micromark-util-encode

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[code]: https://github.com/micromark/micromark/blob/main/packages/micromark-util-types/index.d.ts


---

# micromark-util-character

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility to handle [character codes][code].

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`asciiAlpha(code)`](#asciialphacode)
    *   [`asciiAlphanumeric(code)`](#asciialphanumericcode)
    *   [`asciiAtext(code)`](#asciiatextcode)
    *   [`asciiControl(code)`](#asciicontrolcode)
    *   [`asciiDigit(code)`](#asciidigitcode)
    *   [`asciiHexDigit(code)`](#asciihexdigitcode)
    *   [`asciiPunctuation(code)`](#asciipunctuationcode)
    *   [`markdownLineEnding(code)`](#markdownlineendingcode)
    *   [`markdownLineEndingOrSpace(code)`](#markdownlineendingorspacecode)
    *   [`markdownSpace(code)`](#markdownspacecode)
    *   [`unicodePunctuation(code)`](#unicodepunctuationcode)
    *   [`unicodeWhitespace(code)`](#unicodewhitespacecode)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Security](#security)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package exposes algorithms to check whether characters match groups.

## When should I use this?

This package might be useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-character
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as character from 'https://esm.sh/micromark-util-character@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as character from 'https://esm.sh/micromark-util-character@1?bundle'
</script>
```

## Use

```js
import {asciiAlpha} from 'micromark-util-character'

console.log(asciiAlpha(64)) // false
console.log(asciiAlpha(65)) // true
```

## API

This module exports the identifiers
[`asciiAlpha`][api-ascii-alpha],
[`asciiAlphanumeric`][api-ascii-alphanumeric],
[`asciiAtext`][api-ascii-atext],
[`asciiControl`][api-ascii-control],
[`asciiDigit`][api-ascii-digit],
[`asciiHexDigit`][api-ascii-hex-digit],
[`asciiPunctuation`][api-ascii-punctuation],
[`markdownLineEnding`][api-markdown-line-ending],
[`markdownLineEndingOrSpace`][api-markdown-line-ending-or-space],
[`markdownSpace`][api-markdown-space],
[`unicodePunctuation`][api-unicode-punctuation],
[`unicodeWhitespace`][api-unicode-whitespace].
There is no default export.

### `asciiAlpha(code)`

Check whether the [character code][code] represents an ASCII alpha (`a` through
`z`, case insensitive).

An **ASCII alpha** is an ASCII upper alpha or ASCII lower alpha.

An **ASCII upper alpha** is a character in the inclusive range U+0041 (`A`)
to U+005A (`Z`).

An **ASCII lower alpha** is a character in the inclusive range U+0061 (`a`)
to U+007A (`z`).

###### Parameters

*   `code` (`Code`)
    — code

###### Returns

Whether it matches (`boolean`).

### `asciiAlphanumeric(code)`

Check whether the [character code][code] represents an ASCII alphanumeric (`a`
through `z`, case insensitive, or `0` through `9`).

An **ASCII alphanumeric** is an ASCII digit (see `asciiDigit`) or ASCII alpha
(see `asciiAlpha`).

###### Parameters

*   `code` (`Code`)
    — code

###### Returns

Whether it matches (`boolean`).

### `asciiAtext(code)`

Check whether the [character code][code] represents an ASCII atext.

atext is an ASCII alphanumeric (see `asciiAlphanumeric`), or a character in
the inclusive ranges U+0023 NUMBER SIGN (`#`) to U+0027 APOSTROPHE (`'`),
U+002A ASTERISK (`*`), U+002B PLUS SIGN (`+`), U+002D DASH (`-`), U+002F
SLASH (`/`), U+003D EQUALS TO (`=`), U+003F QUESTION MARK (`?`), U+005E
CARET (`^`) to U+0060 GRAVE ACCENT (`` ` ``), or U+007B LEFT CURLY BRACE
(`{`) to U+007E TILDE (`~`) (**\[RFC5322]**).

See **\[RFC5322]**:\
[Internet Message Format](https://tools.ietf.org/html/rfc5322).\
P. Resnick.\
IETF.

###### Parameters

*   `code` (`Code`)
    — code

###### Returns

Whether it matches (`boolean`).

### `asciiControl(code)`

Check whether a [character code][code] is an ASCII control character.

An **ASCII control** is a character in the inclusive range U+0000 NULL (NUL)
to U+001F (US), or U+007F (DEL).

###### Parameters

*   `code` (`Code`)
    — code

###### Returns

Whether it matches (`boolean`).

### `asciiDigit(code)`

Check whether the [character code][code] represents an ASCII digit (`0` through
`9`).

An **ASCII digit** is a character in the inclusive range U+0030 (`0`) to
U+0039 (`9`).

###### Parameters

*   `code` (`Code`)
    — code

###### Returns

Whether it matches (`boolean`).

### `asciiHexDigit(code)`

Check whether the [character code][code] represents an ASCII hex digit (`a`
through `f`, case insensitive, or `0` through `9`).

An **ASCII hex digit** is an ASCII digit (see `asciiDigit`), ASCII upper hex
digit, or an ASCII lower hex digit.

An **ASCII upper hex digit** is a character in the inclusive range U+0041
(`A`) to U+0046 (`F`).

An **ASCII lower hex digit** is a character in the inclusive range U+0061
(`a`) to U+0066 (`f`).

###### Parameters

*   `code` (`Code`)
    — code

###### Returns

Whether it matches (`boolean`).

### `asciiPunctuation(code)`

Check whether the [character code][code] represents ASCII punctuation.

An **ASCII punctuation** is a character in the inclusive ranges U+0021
EXCLAMATION MARK (`!`) to U+002F SLASH (`/`), U+003A COLON (`:`) to U+0040 AT
SIGN (`@`), U+005B LEFT SQUARE BRACKET (`[`) to U+0060 GRAVE ACCENT
(`` ` ``), or U+007B LEFT CURLY BRACE (`{`) to U+007E TILDE (`~`).

###### Parameters

*   `code` (`Code`)
    — code

###### Returns

Whether it matches (`boolean`).

### `markdownLineEnding(code)`

Check whether a [character code][code] is a markdown line ending.

A **markdown line ending** is the virtual characters M-0003 CARRIAGE RETURN
LINE FEED (CRLF), M-0004 LINE FEED (LF) and M-0005 CARRIAGE RETURN (CR).

In micromark, the actual character U+000A LINE FEED (LF) and U+000D CARRIAGE
RETURN (CR) are replaced by these virtual characters depending on whether
they occurred together.

###### Parameters

*   `code` (`Code`)
    — code

###### Returns

Whether it matches (`boolean`).

### `markdownLineEndingOrSpace(code)`

Check whether a [character code][code] is a markdown line ending (see
`markdownLineEnding`) or markdown space (see `markdownSpace`).

###### Parameters

*   `code` (`Code`)
    — code

###### Returns

Whether it matches (`boolean`).

### `markdownSpace(code)`

Check whether a [character code][code] is a markdown space.

A **markdown space** is the concrete character U+0020 SPACE (SP) and the
virtual characters M-0001 VIRTUAL SPACE (VS) and M-0002 HORIZONTAL TAB (HT).

In micromark, the actual character U+0009 CHARACTER TABULATION (HT) is
replaced by one M-0002 HORIZONTAL TAB (HT) and between 0 and 3 M-0001 VIRTUAL
SPACE (VS) characters, depending on the column at which the tab occurred.

###### Parameters

*   `code` (`Code`)
    — code

###### Returns

Whether it matches (`boolean`).

### `unicodePunctuation(code)`

Check whether the [character code][code] represents Unicode punctuation.

A **Unicode punctuation** is a character in the Unicode `Pc` (Punctuation,
Connector), `Pd` (Punctuation, Dash), `Pe` (Punctuation, Close), `Pf`
(Punctuation, Final quote), `Pi` (Punctuation, Initial quote), `Po`
(Punctuation, Other), or `Ps` (Punctuation, Open) categories, or an ASCII
punctuation (see `asciiPunctuation`) (**\[UNICODE]**).

See **\[UNICODE]**:\
[The Unicode Standard](https://www.unicode.org/versions/).\
Unicode Consortium.

###### Parameters

*   `code` (`Code`)
    — code

###### Returns

Whether it matches (`boolean`).

### `unicodeWhitespace(code)`

Check whether the [character code][code] represents Unicode whitespace.

Note that this does handle micromark specific markdown whitespace characters.
See `markdownLineEndingOrSpace` to check that.

A **Unicode whitespace** is a character in the Unicode `Zs` (Separator,
Space) category, or U+0009 CHARACTER TABULATION (HT), U+000A LINE FEED (LF),
U+000C (FF), or U+000D CARRIAGE RETURN (CR) (**\[UNICODE]**).

See **\[UNICODE]**:\
[The Unicode Standard](https://www.unicode.org/versions/).\
Unicode Consortium.

###### Parameters

*   `code` (`Code`)
    — code

###### Returns

Whether it matches (`boolean`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with all maintained
versions of Node.js.
As of now, that is Node.js 16+.
Our projects sometimes work with older versions, but this is not guaranteed.

This package works with `micromark` version 3+.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-character.svg

[downloads]: https://www.npmjs.com/package/micromark-util-character

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-character

[bundle-size]: https://bundlejs.com/?q=micromark-util-character

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[code]: https://github.com/micromark/micromark#preprocess

[api-ascii-alpha]: #asciialphacode

[api-ascii-alphanumeric]: #asciialphanumericcode

[api-ascii-atext]: #asciiatextcode

[api-ascii-control]: #asciicontrolcode

[api-ascii-digit]: #asciidigitcode

[api-ascii-hex-digit]: #asciihexdigitcode

[api-ascii-punctuation]: #asciipunctuationcode

[api-markdown-line-ending]: #markdownlineendingcode

[api-markdown-line-ending-or-space]: #markdownlineendingorspacecode

[api-markdown-space]: #markdownspacecode

[api-unicode-punctuation]: #unicodepunctuationcode

[api-unicode-whitespace]: #unicodewhitespacecode


---

# micromark-util-symbol

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility with symbols.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes constants used throughout the micromark ecosystem.

## When should I use this?

This package is useful when you are making your own micromark extensions.
It’s useful to reference these constants by name instead of value while
developing.
[`micromark-build`][micromark-build] compiles them away for production code.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-symbol
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as symbol from 'https://esm.sh/micromark-util-symbol@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as symbol from 'https://esm.sh/micromark-util-symbol@1?bundle'
</script>
```

## Use

```js
import {codes, constants, types, values} from 'micromark-util-symbol'

console.log(codes.atSign) // 64
console.log(constants.characterReferenceNamedSizeMax) // 31
console.log(types.definitionDestinationRaw) // 'definitionDestinationRaw'
console.log(values.atSign) // '@'
```

## API

This package exports the identifiers `codes`, `constants`, `types`, and
`values`.
There is no default export.

Each identifier is an object mapping strings to values.
See the code for the exposed data.

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-symbol@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-symbol.svg

[downloads]: https://www.npmjs.com/package/micromark-util-symbol

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-symbol

[bundle-size]: https://bundlejs.com/?q=micromark-util-symbol

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[micromark-build]: https://github.com/micromark/micromark/tree/main/packages/micromark-build


---

# micromark-util-chunked

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility to splice and push with giant arrays.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`push(list, items)`](#pushlist-items)
  * [`splice(list, start, remove, items)`](#splicelist-start-remove-items)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes an algorithm to splice for giant arrays, which V8 bugs
out on.

## When should I use this?

This package might be useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-chunked
```

In Deno with [`esm.sh`][esmsh]:

```js
import {push, splice} from 'https://esm.sh/micromark-util-chunked@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {push, splice} from 'https://esm.sh/micromark-util-chunked@1?bundle'
</script>
```

## Use

```js
import {push, splice} from 'micromark-util-chunked'

// …

nextEvents = push(nextEvents, [
  ['enter', events[open][1], context],
  ['exit', events[open][1], context]
])

// …

splice(events, open - 1, index - open + 3, nextEvents)

// …
```

## API

This module exports the identifiers [`push`][api-push]
and [`splice`][api-splice].
There is no default export.

### `push(list, items)`

Append `items` (an array) at the end of `list` (another array).
When `list` was empty, returns `items` instead.

This prevents a potentially expensive operation when `list` is empty,
and adds items in batches to prevent V8 from hanging.

###### Parameters

* `list` (`Array<unknown>`)
  — list to operate on
* `items` (`Array<unknown>`)
  — items to add to `list`

###### Returns

Either `list` or `items` (`Array<unknown>`).

### `splice(list, start, remove, items)`

Like `Array#splice`, but smarter for giant arrays.

`Array#splice` takes all items to be inserted as individual argument which
causes a stack overflow in V8 when trying to insert 100k items for instance.

Otherwise, this does not return the removed items, and takes `items` as an
array instead of rest parameters.

###### Parameters

* `list` (`Array<unknown>`)
  — list to operate on
* `start` (`number`)
  — index to remove/insert at (can be negative)
* `remove` (`number`)
  — number of items to remove
* `items` (`Array<unknown>`)
  — items to inject into `list`

###### Returns

Nothing (`undefined`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-chunked@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-chunked.svg

[downloads]: https://www.npmjs.com/package/micromark-util-chunked

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-chunked

[bundle-size]: https://bundlejs.com/?q=micromark-util-chunked

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[api-push]: #pushlist-items

[api-splice]: #splicelist-start-remove-items


---

# micromark-util-character

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility to handle [character codes][code].

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`asciiAlpha(code)`](#asciialphacode)
  * [`asciiAlphanumeric(code)`](#asciialphanumericcode)
  * [`asciiAtext(code)`](#asciiatextcode)
  * [`asciiControl(code)`](#asciicontrolcode)
  * [`asciiDigit(code)`](#asciidigitcode)
  * [`asciiHexDigit(code)`](#asciihexdigitcode)
  * [`asciiPunctuation(code)`](#asciipunctuationcode)
  * [`markdownLineEnding(code)`](#markdownlineendingcode)
  * [`markdownLineEndingOrSpace(code)`](#markdownlineendingorspacecode)
  * [`markdownSpace(code)`](#markdownspacecode)
  * [`unicodePunctuation(code)`](#unicodepunctuationcode)
  * [`unicodeWhitespace(code)`](#unicodewhitespacecode)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes algorithms to check whether characters match groups.

## When should I use this?

This package might be useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-character
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as character from 'https://esm.sh/micromark-util-character@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as character from 'https://esm.sh/micromark-util-character@1?bundle'
</script>
```

## Use

```js
import {asciiAlpha} from 'micromark-util-character'

console.log(asciiAlpha(64)) // false
console.log(asciiAlpha(65)) // true
```

## API

This module exports the identifiers
[`asciiAlpha`][api-ascii-alpha],
[`asciiAlphanumeric`][api-ascii-alphanumeric],
[`asciiAtext`][api-ascii-atext],
[`asciiControl`][api-ascii-control],
[`asciiDigit`][api-ascii-digit],
[`asciiHexDigit`][api-ascii-hex-digit],
[`asciiPunctuation`][api-ascii-punctuation],
[`markdownLineEnding`][api-markdown-line-ending],
[`markdownLineEndingOrSpace`][api-markdown-line-ending-or-space],
[`markdownSpace`][api-markdown-space],
[`unicodePunctuation`][api-unicode-punctuation],
[`unicodeWhitespace`][api-unicode-whitespace].
There is no default export.

### `asciiAlpha(code)`

Check whether the [character code][code] represents an ASCII alpha (`a` through
`z`, case insensitive).

An **ASCII alpha** is an ASCII upper alpha or ASCII lower alpha.

An **ASCII upper alpha** is a character in the inclusive range U+0041 (`A`)
to U+005A (`Z`).

An **ASCII lower alpha** is a character in the inclusive range U+0061 (`a`)
to U+007A (`z`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiAlphanumeric(code)`

Check whether the [character code][code] represents an ASCII alphanumeric (`a`
through `z`, case insensitive, or `0` through `9`).

An **ASCII alphanumeric** is an ASCII digit (see `asciiDigit`) or ASCII alpha
(see `asciiAlpha`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiAtext(code)`

Check whether the [character code][code] represents an ASCII atext.

atext is an ASCII alphanumeric (see `asciiAlphanumeric`), or a character in
the inclusive ranges U+0023 NUMBER SIGN (`#`) to U+0027 APOSTROPHE (`'`),
U+002A ASTERISK (`*`), U+002B PLUS SIGN (`+`), U+002D DASH (`-`), U+002F
SLASH (`/`), U+003D EQUALS TO (`=`), U+003F QUESTION MARK (`?`), U+005E
CARET (`^`) to U+0060 GRAVE ACCENT (`` ` ``), or U+007B LEFT CURLY BRACE
(`{`) to U+007E TILDE (`~`) (**\[RFC5322]**).

See **\[RFC5322]**:\
[Internet Message Format](https://tools.ietf.org/html/rfc5322).\
P. Resnick.\
IETF.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiControl(code)`

Check whether a [character code][code] is an ASCII control character.

An **ASCII control** is a character in the inclusive range U+0000 NULL (NUL)
to U+001F (US), or U+007F (DEL).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiDigit(code)`

Check whether the [character code][code] represents an ASCII digit (`0` through
`9`).

An **ASCII digit** is a character in the inclusive range U+0030 (`0`) to
U+0039 (`9`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiHexDigit(code)`

Check whether the [character code][code] represents an ASCII hex digit (`a`
through `f`, case insensitive, or `0` through `9`).

An **ASCII hex digit** is an ASCII digit (see `asciiDigit`), ASCII upper hex
digit, or an ASCII lower hex digit.

An **ASCII upper hex digit** is a character in the inclusive range U+0041
(`A`) to U+0046 (`F`).

An **ASCII lower hex digit** is a character in the inclusive range U+0061
(`a`) to U+0066 (`f`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiPunctuation(code)`

Check whether the [character code][code] represents ASCII punctuation.

An **ASCII punctuation** is a character in the inclusive ranges U+0021
EXCLAMATION MARK (`!`) to U+002F SLASH (`/`), U+003A COLON (`:`) to U+0040 AT
SIGN (`@`), U+005B LEFT SQUARE BRACKET (`[`) to U+0060 GRAVE ACCENT
(`` ` ``), or U+007B LEFT CURLY BRACE (`{`) to U+007E TILDE (`~`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownLineEnding(code)`

Check whether a [character code][code] is a markdown line ending.

A **markdown line ending** is the virtual characters M-0003 CARRIAGE RETURN
LINE FEED (CRLF), M-0004 LINE FEED (LF) and M-0005 CARRIAGE RETURN (CR).

In micromark, the actual character U+000A LINE FEED (LF) and U+000D CARRIAGE
RETURN (CR) are replaced by these virtual characters depending on whether
they occurred together.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownLineEndingOrSpace(code)`

Check whether a [character code][code] is a markdown line ending (see
`markdownLineEnding`) or markdown space (see `markdownSpace`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownSpace(code)`

Check whether a [character code][code] is a markdown space.

A **markdown space** is the concrete character U+0020 SPACE (SP) and the
virtual characters M-0001 VIRTUAL SPACE (VS) and M-0002 HORIZONTAL TAB (HT).

In micromark, the actual character U+0009 CHARACTER TABULATION (HT) is
replaced by one M-0002 HORIZONTAL TAB (HT) and between 0 and 3 M-0001 VIRTUAL
SPACE (VS) characters, depending on the column at which the tab occurred.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `unicodePunctuation(code)`

Check whether the [character code][code] represents Unicode punctuation.

A **Unicode punctuation** is a character in the Unicode `Pc` (Punctuation,
Connector), `Pd` (Punctuation, Dash), `Pe` (Punctuation, Close), `Pf`
(Punctuation, Final quote), `Pi` (Punctuation, Initial quote), `Po`
(Punctuation, Other), or `Ps` (Punctuation, Open) categories, or an ASCII
punctuation (see `asciiPunctuation`) (**\[UNICODE]**).

See **\[UNICODE]**:\
[The Unicode Standard](https://www.unicode.org/versions/).\
Unicode Consortium.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `unicodeWhitespace(code)`

Check whether the [character code][code] represents Unicode whitespace.

Note that this does handle micromark specific markdown whitespace characters.
See `markdownLineEndingOrSpace` to check that.

A **Unicode whitespace** is a character in the Unicode `Zs` (Separator,
Space) category, or U+0009 CHARACTER TABULATION (HT), U+000A LINE FEED (LF),
U+000C (FF), or U+000D CARRIAGE RETURN (CR) (**\[UNICODE]**).

See **\[UNICODE]**:\
[The Unicode Standard](https://www.unicode.org/versions/).\
Unicode Consortium.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-character@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-character.svg

[downloads]: https://www.npmjs.com/package/micromark-util-character

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-character

[bundle-size]: https://bundlejs.com/?q=micromark-util-character

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[code]: https://github.com/micromark/micromark#preprocess

[api-ascii-alpha]: #asciialphacode

[api-ascii-alphanumeric]: #asciialphanumericcode

[api-ascii-atext]: #asciiatextcode

[api-ascii-control]: #asciicontrolcode

[api-ascii-digit]: #asciidigitcode

[api-ascii-hex-digit]: #asciihexdigitcode

[api-ascii-punctuation]: #asciipunctuationcode

[api-markdown-line-ending]: #markdownlineendingcode

[api-markdown-line-ending-or-space]: #markdownlineendingorspacecode

[api-markdown-space]: #markdownspacecode

[api-unicode-punctuation]: #unicodepunctuationcode

[api-unicode-whitespace]: #unicodewhitespacecode


---

# micromark-util-symbol

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility with symbols.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes constants used throughout the micromark ecosystem.

## When should I use this?

This package is useful when you are making your own micromark extensions.
It’s useful to reference these constants by name instead of value while
developing.
[`micromark-build`][micromark-build] compiles them away for production code.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-symbol
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as symbol from 'https://esm.sh/micromark-util-symbol@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as symbol from 'https://esm.sh/micromark-util-symbol@1?bundle'
</script>
```

## Use

```js
import {codes, constants, types, values} from 'micromark-util-symbol'

console.log(codes.atSign) // 64
console.log(constants.characterReferenceNamedSizeMax) // 31
console.log(types.definitionDestinationRaw) // 'definitionDestinationRaw'
console.log(values.atSign) // '@'
```

## API

This package exports the identifiers `codes`, `constants`, `types`, and
`values`.
There is no default export.

Each identifier is an object mapping strings to values.
See the code for the exposed data.

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-symbol@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-symbol.svg

[downloads]: https://www.npmjs.com/package/micromark-util-symbol

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-symbol

[bundle-size]: https://bundlejs.com/?q=micromark-util-symbol

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[micromark-build]: https://github.com/micromark/micromark/tree/main/packages/micromark-build


---

# micromark-util-classify-character

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility to classify whether a character is whitespace or
punctuation.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`classifyCharacter(code)`](#classifycharactercode)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes an algorithm to classify characters into 3 categories.

## When should I use this?

This package might be useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-classify-character
```

In Deno with [`esm.sh`][esmsh]:

```js
import {classifyCharacter} from 'https://esm.sh/micromark-util-classify-character@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {classifyCharacter} from 'https://esm.sh/micromark-util-classify-character@1?bundle'
</script>
```

## Use

```js
/**
 * @this {TokenizeContext}
 *   Context.
 * @type {Tokenizer}
 */
function tokenizeAttention(effects, ok) {
  return start

  // …

  /** @type {State} */
  function sequence(code) {
    if (code === marker) {
      // …
    }

    const token = effects.exit('attentionSequence')
    const after = classifyCharacter(code)
    const open =
      !after || (after === constants.characterGroupPunctuation && before)
    const close =
      !before || (before === constants.characterGroupPunctuation && after)
    // …
  }

  // …
}
```

## API

This module exports the identifier
[`classifyCharacter`][api-classify-character].
There is no default export.

### `classifyCharacter(code)`

Classify whether a code represents whitespace, punctuation, or something
else.

Used for attention (emphasis, strong), whose sequences can open or close
based on the class of surrounding characters.

> 👉 **Note**: eof (`null`) is seen as whitespace.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Group (`constants.characterGroupWhitespace`,
`constants.characterGroupPunctuation`, or `undefined`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-classify-character@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-classify-character.svg

[downloads]: https://www.npmjs.com/package/micromark-util-classify-character

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-classify-character

[bundle-size]: https://bundlejs.com/?q=micromark-util-classify-character

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[api-classify-character]: #classifycharactercode


---

# micromark-util-combine-extensions

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility to combine [syntax][] or [html][] extensions.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`combineExtensions(extensions)`](#combineextensionsextensions)
  * [`combineHtmlExtensions(htmlExtensions)`](#combinehtmlextensionshtmlextensions)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package can merge multiple extensions into one.

## When should I use this?

This package might be useful when you are making “presets”, such as
[`micromark-extension-gfm`][micromark-extension-gfm].

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-combine-extensions
```

In Deno with [`esm.sh`][esmsh]:

```js
import {combineExtensions} from 'https://esm.sh/micromark-util-combine-extensions@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {combineExtensions} from 'https://esm.sh/micromark-util-combine-extensions@1?bundle'
</script>
```

## Use

```js
import {gfmAutolinkLiteral} from 'micromark-extension-gfm-autolink-literal'
import {gfmStrikethrough} from 'micromark-extension-gfm-strikethrough'
import {gfmTable} from 'micromark-extension-gfm-table'
import {gfmTaskListItem} from 'micromark-extension-gfm-task-list-item'
import {combineExtensions} from 'micromark-util-combine-extensions'

const gfm = combineExtensions([gfmAutolinkLiteral, gfmStrikethrough(), gfmTable, gfmTaskListItem])
```

## API

This module exports the identifiers
[`combineExtensions`][api-combine-extensions] and
[`combineHtmlExtensions`][api-combine-html-extensions].
There is no default export.

### `combineExtensions(extensions)`

Combine multiple syntax extensions into one.

###### Parameters

* `extensions` (`Array<Extension>`)
  — list of syntax extensions

###### Returns

A single combined extension (`Extension`).

### `combineHtmlExtensions(htmlExtensions)`

Combine multiple html extensions into one.

###### Parameters

* `htmlExtensions` (`Array<HtmlExtension>`)
  — list of HTML extensions

###### Returns

A single combined HTML extension (`HtmlExtension`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-combine-extensions@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-combine-extensions.svg

[downloads]: https://www.npmjs.com/package/micromark-util-combine-extensions

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-combine-extensions

[bundle-size]: https://bundlejs.com/?q=micromark-util-combine-extensions

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[syntax]: https://github.com/micromark/micromark#syntaxextension

[html]: https://github.com/micromark/micromark#htmlextension

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[micromark-extension-gfm]: https://github.com/micromark/micromark-extension-gfm

[api-combine-extensions]: #combineextensionsextensions

[api-combine-html-extensions]: #combinehtmlextensionshtmlextensions


---

# micromark-util-symbol

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility with symbols.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes constants used throughout the micromark ecosystem.

## When should I use this?

This package is useful when you are making your own micromark extensions.
It’s useful to reference these constants by name instead of value while
developing.
[`micromark-build`][micromark-build] compiles them away for production code.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-symbol
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as symbol from 'https://esm.sh/micromark-util-symbol@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as symbol from 'https://esm.sh/micromark-util-symbol@1?bundle'
</script>
```

## Use

```js
import {codes, constants, types, values} from 'micromark-util-symbol'

console.log(codes.atSign) // 64
console.log(constants.characterReferenceNamedSizeMax) // 31
console.log(types.definitionDestinationRaw) // 'definitionDestinationRaw'
console.log(values.atSign) // '@'
```

## API

This package exports the identifiers `codes`, `constants`, `types`, and
`values`.
There is no default export.

Each identifier is an object mapping strings to values.
See the code for the exposed data.

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-symbol@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-symbol.svg

[downloads]: https://www.npmjs.com/package/micromark-util-symbol

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-symbol

[bundle-size]: https://bundlejs.com/?q=micromark-util-symbol

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[micromark-build]: https://github.com/micromark/micromark/tree/main/packages/micromark-build


---

# micromark-util-decode-numeric-character-reference

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility to decode numeric character references.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`decodeNumericCharacterReference(value, base)`](#decodenumericcharacterreferencevalue-base)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes an algorithm to decode numeric character references.

## When should I use this?

This package might be useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-decode-numeric-character-reference
```

In Deno with [`esm.sh`][esmsh]:

```js
import {decodeNumericCharacterReference} from 'https://esm.sh/micromark-util-decode-numeric-character-reference@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {decodeNumericCharacterReference} from 'https://esm.sh/micromark-util-decode-numeric-character-reference@1?bundle'
</script>
```

## Use

```js
import {decodeNumericCharacterReference} from 'micromark-util-decode-numeric-character-reference'

decodeNumericCharacterReference('41', 16) // 'A'
decodeNumericCharacterReference('65', 10) // 'A'
decodeNumericCharacterReference('A', 16) // '\n'
decodeNumericCharacterReference('7F', 16) // '�' - Control
decodeNumericCharacterReference('110000', 16) // '�' - Out of range
```

## API

This module exports the identifier:
[`decodeNumericCharacterReference`][api-decode-numeric-character-reference].
There is no default export.

### `decodeNumericCharacterReference(value, base)`

Turn the number (in string form as either hexa- or plain decimal) coming from
a numeric character reference into a character.

Sort of like `String.fromCodePoint(Number.parseInt(value, base))`, but makes
non-characters and control characters safe.

###### Parameters

* `value` (`string`)
  — value to decode
* `base` (`number`, probably `10` or `16`)
  — numeric base

###### Returns

Character (`string`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-decode-numeric-character-reference@2`, compatible with
Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-normalize-identifier.svg

[downloads]: https://www.npmjs.com/package/micromark-util-normalize-identifier

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-normalize-identifier

[bundle-size]: https://bundlejs.com/?q=micromark-util-normalize-identifier

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[api-decode-numeric-character-reference]: #decodenumericcharacterreferencevalue-base


---

# micromark-util-character

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility to handle [character codes][code].

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`asciiAlpha(code)`](#asciialphacode)
  * [`asciiAlphanumeric(code)`](#asciialphanumericcode)
  * [`asciiAtext(code)`](#asciiatextcode)
  * [`asciiControl(code)`](#asciicontrolcode)
  * [`asciiDigit(code)`](#asciidigitcode)
  * [`asciiHexDigit(code)`](#asciihexdigitcode)
  * [`asciiPunctuation(code)`](#asciipunctuationcode)
  * [`markdownLineEnding(code)`](#markdownlineendingcode)
  * [`markdownLineEndingOrSpace(code)`](#markdownlineendingorspacecode)
  * [`markdownSpace(code)`](#markdownspacecode)
  * [`unicodePunctuation(code)`](#unicodepunctuationcode)
  * [`unicodeWhitespace(code)`](#unicodewhitespacecode)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes algorithms to check whether characters match groups.

## When should I use this?

This package might be useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-character
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as character from 'https://esm.sh/micromark-util-character@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as character from 'https://esm.sh/micromark-util-character@1?bundle'
</script>
```

## Use

```js
import {asciiAlpha} from 'micromark-util-character'

console.log(asciiAlpha(64)) // false
console.log(asciiAlpha(65)) // true
```

## API

This module exports the identifiers
[`asciiAlpha`][api-ascii-alpha],
[`asciiAlphanumeric`][api-ascii-alphanumeric],
[`asciiAtext`][api-ascii-atext],
[`asciiControl`][api-ascii-control],
[`asciiDigit`][api-ascii-digit],
[`asciiHexDigit`][api-ascii-hex-digit],
[`asciiPunctuation`][api-ascii-punctuation],
[`markdownLineEnding`][api-markdown-line-ending],
[`markdownLineEndingOrSpace`][api-markdown-line-ending-or-space],
[`markdownSpace`][api-markdown-space],
[`unicodePunctuation`][api-unicode-punctuation],
[`unicodeWhitespace`][api-unicode-whitespace].
There is no default export.

### `asciiAlpha(code)`

Check whether the [character code][code] represents an ASCII alpha (`a` through
`z`, case insensitive).

An **ASCII alpha** is an ASCII upper alpha or ASCII lower alpha.

An **ASCII upper alpha** is a character in the inclusive range U+0041 (`A`)
to U+005A (`Z`).

An **ASCII lower alpha** is a character in the inclusive range U+0061 (`a`)
to U+007A (`z`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiAlphanumeric(code)`

Check whether the [character code][code] represents an ASCII alphanumeric (`a`
through `z`, case insensitive, or `0` through `9`).

An **ASCII alphanumeric** is an ASCII digit (see `asciiDigit`) or ASCII alpha
(see `asciiAlpha`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiAtext(code)`

Check whether the [character code][code] represents an ASCII atext.

atext is an ASCII alphanumeric (see `asciiAlphanumeric`), or a character in
the inclusive ranges U+0023 NUMBER SIGN (`#`) to U+0027 APOSTROPHE (`'`),
U+002A ASTERISK (`*`), U+002B PLUS SIGN (`+`), U+002D DASH (`-`), U+002F
SLASH (`/`), U+003D EQUALS TO (`=`), U+003F QUESTION MARK (`?`), U+005E
CARET (`^`) to U+0060 GRAVE ACCENT (`` ` ``), or U+007B LEFT CURLY BRACE
(`{`) to U+007E TILDE (`~`) (**\[RFC5322]**).

See **\[RFC5322]**:\
[Internet Message Format](https://tools.ietf.org/html/rfc5322).\
P. Resnick.\
IETF.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiControl(code)`

Check whether a [character code][code] is an ASCII control character.

An **ASCII control** is a character in the inclusive range U+0000 NULL (NUL)
to U+001F (US), or U+007F (DEL).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiDigit(code)`

Check whether the [character code][code] represents an ASCII digit (`0` through
`9`).

An **ASCII digit** is a character in the inclusive range U+0030 (`0`) to
U+0039 (`9`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiHexDigit(code)`

Check whether the [character code][code] represents an ASCII hex digit (`a`
through `f`, case insensitive, or `0` through `9`).

An **ASCII hex digit** is an ASCII digit (see `asciiDigit`), ASCII upper hex
digit, or an ASCII lower hex digit.

An **ASCII upper hex digit** is a character in the inclusive range U+0041
(`A`) to U+0046 (`F`).

An **ASCII lower hex digit** is a character in the inclusive range U+0061
(`a`) to U+0066 (`f`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiPunctuation(code)`

Check whether the [character code][code] represents ASCII punctuation.

An **ASCII punctuation** is a character in the inclusive ranges U+0021
EXCLAMATION MARK (`!`) to U+002F SLASH (`/`), U+003A COLON (`:`) to U+0040 AT
SIGN (`@`), U+005B LEFT SQUARE BRACKET (`[`) to U+0060 GRAVE ACCENT
(`` ` ``), or U+007B LEFT CURLY BRACE (`{`) to U+007E TILDE (`~`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownLineEnding(code)`

Check whether a [character code][code] is a markdown line ending.

A **markdown line ending** is the virtual characters M-0003 CARRIAGE RETURN
LINE FEED (CRLF), M-0004 LINE FEED (LF) and M-0005 CARRIAGE RETURN (CR).

In micromark, the actual character U+000A LINE FEED (LF) and U+000D CARRIAGE
RETURN (CR) are replaced by these virtual characters depending on whether
they occurred together.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownLineEndingOrSpace(code)`

Check whether a [character code][code] is a markdown line ending (see
`markdownLineEnding`) or markdown space (see `markdownSpace`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownSpace(code)`

Check whether a [character code][code] is a markdown space.

A **markdown space** is the concrete character U+0020 SPACE (SP) and the
virtual characters M-0001 VIRTUAL SPACE (VS) and M-0002 HORIZONTAL TAB (HT).

In micromark, the actual character U+0009 CHARACTER TABULATION (HT) is
replaced by one M-0002 HORIZONTAL TAB (HT) and between 0 and 3 M-0001 VIRTUAL
SPACE (VS) characters, depending on the column at which the tab occurred.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `unicodePunctuation(code)`

Check whether the [character code][code] represents Unicode punctuation.

A **Unicode punctuation** is a character in the Unicode `Pc` (Punctuation,
Connector), `Pd` (Punctuation, Dash), `Pe` (Punctuation, Close), `Pf`
(Punctuation, Final quote), `Pi` (Punctuation, Initial quote), `Po`
(Punctuation, Other), or `Ps` (Punctuation, Open) categories, or an ASCII
punctuation (see `asciiPunctuation`) (**\[UNICODE]**).

See **\[UNICODE]**:\
[The Unicode Standard](https://www.unicode.org/versions/).\
Unicode Consortium.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `unicodeWhitespace(code)`

Check whether the [character code][code] represents Unicode whitespace.

Note that this does handle micromark specific markdown whitespace characters.
See `markdownLineEndingOrSpace` to check that.

A **Unicode whitespace** is a character in the Unicode `Zs` (Separator,
Space) category, or U+0009 CHARACTER TABULATION (HT), U+000A LINE FEED (LF),
U+000C (FF), or U+000D CARRIAGE RETURN (CR) (**\[UNICODE]**).

See **\[UNICODE]**:\
[The Unicode Standard](https://www.unicode.org/versions/).\
Unicode Consortium.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-character@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-character.svg

[downloads]: https://www.npmjs.com/package/micromark-util-character

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-character

[bundle-size]: https://bundlejs.com/?q=micromark-util-character

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[code]: https://github.com/micromark/micromark#preprocess

[api-ascii-alpha]: #asciialphacode

[api-ascii-alphanumeric]: #asciialphanumericcode

[api-ascii-atext]: #asciiatextcode

[api-ascii-control]: #asciicontrolcode

[api-ascii-digit]: #asciidigitcode

[api-ascii-hex-digit]: #asciihexdigitcode

[api-ascii-punctuation]: #asciipunctuationcode

[api-markdown-line-ending]: #markdownlineendingcode

[api-markdown-line-ending-or-space]: #markdownlineendingorspacecode

[api-markdown-space]: #markdownspacecode

[api-unicode-punctuation]: #unicodepunctuationcode

[api-unicode-whitespace]: #unicodewhitespacecode


---

# micromark-util-symbol

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility with symbols.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes constants used throughout the micromark ecosystem.

## When should I use this?

This package is useful when you are making your own micromark extensions.
It’s useful to reference these constants by name instead of value while
developing.
[`micromark-build`][micromark-build] compiles them away for production code.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-symbol
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as symbol from 'https://esm.sh/micromark-util-symbol@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as symbol from 'https://esm.sh/micromark-util-symbol@1?bundle'
</script>
```

## Use

```js
import {codes, constants, types, values} from 'micromark-util-symbol'

console.log(codes.atSign) // 64
console.log(constants.characterReferenceNamedSizeMax) // 31
console.log(types.definitionDestinationRaw) // 'definitionDestinationRaw'
console.log(values.atSign) // '@'
```

## API

This package exports the identifiers `codes`, `constants`, `types`, and
`values`.
There is no default export.

Each identifier is an object mapping strings to values.
See the code for the exposed data.

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-symbol@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-symbol.svg

[downloads]: https://www.npmjs.com/package/micromark-util-symbol

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-symbol

[bundle-size]: https://bundlejs.com/?q=micromark-util-symbol

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[micromark-build]: https://github.com/micromark/micromark/tree/main/packages/micromark-build


---

# micromark-util-decode-string

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility to decode markdown strings.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`decodeString(value)`](#decodestringvalue)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes an algorithm to parse character escapes and character
references.

## When should I use this?

This package might be useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-decode-string
```

In Deno with [`esm.sh`][esmsh]:

```js
import {decodeString} from 'https://esm.sh/micromark-util-decode-string@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {decodeString} from 'https://esm.sh/micromark-util-decode-string@1?bundle'
</script>
```

## Use

```js
import {decodeString} from 'micromark-util-decode-string'

decodeString('a &semi; b') // 'a ; b'
decodeString('a \\; b') // 'a ; b'
decodeString('a ; b') // 'a ; b'
```

## API

This module exports the identifier [`decodeString`][api-decode-string].
There is no default export.

### `decodeString(value)`

Decode markdown strings (which occur in places such as fenced code info strings,
destinations, labels, and titles).

The “string” content type allows character escapes and -references.
This decodes those.

###### Parameters

* `value` (`string`)
  — value to decode

###### Returns

Decoded value (`string`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-decode-string@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-normalize-identifier.svg

[downloads]: https://www.npmjs.com/package/micromark-util-normalize-identifier

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-normalize-identifier

[bundle-size]: https://bundlejs.com/?q=micromark-util-normalize-identifier

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[api-decode-string]: #decodestringvalue


---

# micromark-util-encode

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility to encode dangerous html characters.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`encode(value)`](#encodevalue)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes an algorithm to make text safe for embedding in HTML.

## When should I use this?

This package might be useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-encode
```

In Deno with [`esm.sh`][esmsh]:

```js
import {encode} from 'https://esm.sh/micromark-util-encode@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {encode} from 'https://esm.sh/micromark-util-encode@1?bundle'
</script>
```

## Use

```js
import {encode} from 'micromark-util-encode'

encode('<3') // '&lt;3'
```

## API

This module exports the identifier [`encode`][api-encode].
There is no default export.

### `encode(value)`

Encode only the dangerous HTML characters.

This ensures that certain characters which have special meaning in HTML are
dealt with.
Technically, we can skip `>` and `"` in many cases, but CM includes them.

###### Parameters

* `value` (`string`)
  — value to encode

###### Returns

Encoded value (`string`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-encode@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-encode.svg

[downloads]: https://www.npmjs.com/package/micromark-util-encode

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-encode

[bundle-size]: https://bundlejs.com/?q=micromark-util-encode

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[api-encode]: #encodevalue


---

# micromark-util-symbol

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility with symbols.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes constants used throughout the micromark ecosystem.

## When should I use this?

This package is useful when you are making your own micromark extensions.
It’s useful to reference these constants by name instead of value while
developing.
[`micromark-build`][micromark-build] compiles them away for production code.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-symbol
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as symbol from 'https://esm.sh/micromark-util-symbol@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as symbol from 'https://esm.sh/micromark-util-symbol@1?bundle'
</script>
```

## Use

```js
import {codes, constants, types, values} from 'micromark-util-symbol'

console.log(codes.atSign) // 64
console.log(constants.characterReferenceNamedSizeMax) // 31
console.log(types.definitionDestinationRaw) // 'definitionDestinationRaw'
console.log(values.atSign) // '@'
```

## API

This package exports the identifiers `codes`, `constants`, `types`, and
`values`.
There is no default export.

Each identifier is an object mapping strings to values.
See the code for the exposed data.

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-symbol@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-symbol.svg

[downloads]: https://www.npmjs.com/package/micromark-util-symbol

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-symbol

[bundle-size]: https://bundlejs.com/?q=micromark-util-symbol

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[micromark-build]: https://github.com/micromark/micromark/tree/main/packages/micromark-build


---

# micromark-util-events-to-acorn

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility to try and parse events with acorn.

## Contents

* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`eventsToAcorn(events, options)`](#eventstoacornevents-options)
  * [`Options`](#options)
  * [`Result`](#result)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-events-to-acorn
```

In Deno with [`esm.sh`][esmsh]:

```js
import {eventsToAcorn} from 'https://esm.sh/micromark-util-events-to-acorn@2'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {eventsToAcorn} from 'https://esm.sh/micromark-util-events-to-acorn@2?bundle'
</script>
```

## Use

```js
import {eventsToAcorn} from 'micromark-util-events-to-acorn'

// A factory that uses the utility:
/** @type {Tokenizer} */
function factoryMdxExpression(effects, ok, nok) {
  return start

  // …

    // …

    // Gnostic mode: parse w/ acorn.
    const result = eventsToAcorn(this.events.slice(eventStart), {
      acorn,
      acornOptions,
      start: pointStart,
      expression: true,
      allowEmpty,
      prefix: spread ? '({' : '',
      suffix: spread ? '})' : ''
    })

    // …

  // …
}
```

## API

This module exports the identifier [`eventsToAcorn`][api-events-to-acorn].
There is no default export.

The export map supports the [`development` condition][development].
Run `node --conditions development module.js` to get instrumented dev code.
Without this condition, production code is loaded.

### `eventsToAcorn(events, options)`

###### Parameters

* `events` (`Array<Event>`)
  — events
* `options` ([`Options`][api-options])
  — configuration (required)

###### Returns

Result ([`Result`][api-result]).

### `Options`

Configuration (TypeScript type).

###### Fields

* `acorn` ([`Acorn`][acorn], required)
  — typically `acorn`, object with `parse` and `parseExpressionAt` fields
* `tokenTypes` (`Array<TokenType>`], required)
  — names of (void) tokens to consider as data; `'lineEnding'` is always
  included
* `acornOptions` ([`AcornOptions`][acorn-options], optional)
  — configuration for `acorn`
* `start` (`Point`, optional, required if `allowEmpty`)
  — place where events start
* `prefix` (`string`, default: `''`)
  — text to place before events
* `suffix` (`string`, default: `''`)
  — text to place after events
* `expression` (`boolean`, default: `false`)
  — whether this is a program or expression
* `allowEmpty` (`boolean`, default: `false`)
  — whether an empty expression is allowed (programs are always allowed to be
  empty)

### `Result`

Result (TypeScript type).

###### Fields

* `estree` ([`Program`][program] or `undefined`)
  — Program
* `error` (`Error` or `undefined`)
  — error if unparseable
* `swallow` (`boolean`)
  — whether the error, if there is one, can be swallowed and more JavaScript
  could be valid

## Types

This package is fully typed with [TypeScript][].
It exports the additional types [`Acorn`][acorn],
[`AcornOptions`][acorn-options], [`Options`][api-options], and
[`Result`][api-result].

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-events-to-acorn@^2`, compatible with Node.js 16.

This package works with `micromark` version `3` and later.

## Security

This package is safe.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[acorn]: https://github.com/acornjs/acorn

[acorn-options]: https://github.com/acornjs/acorn/blob/96c721dbf89d0ccc3a8c7f39e69ef2a6a3c04dfa/acorn/dist/acorn.d.ts#L16

[api-events-to-acorn]: #eventstoacornevents-options

[api-options]: #options

[api-result]: #result

[author]: https://wooorm.com

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[build]: https://github.com/micromark/micromark-extension-mdx-expression/actions

[build-badge]: https://github.com/micromark/micromark-extension-mdx-expression/workflows/main/badge.svg

[chat]: https://github.com/micromark/micromark/discussions

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[coverage]: https://codecov.io/github/micromark/micromark-extension-mdx-expression

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark-extension-mdx-expression.svg

[development]: https://nodejs.org/api/packages.html#packages_resolving_user_conditions

[downloads]: https://www.npmjs.com/package/micromark-util-events-to-acorn

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-events-to-acorn.svg

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[health]: https://github.com/micromark/.github

[license]: https://github.com/micromark/micromark-extension-mdx-expression/blob/main/license

[micromark]: https://github.com/micromark/micromark

[npm]: https://docs.npmjs.com/cli/install

[opencollective]: https://opencollective.com/unified

[program]: https://github.com/estree/estree/blob/master/es2015.md#programs

[size]: https://bundlejs.com/?q=micromark-util-events-to-acorn

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-events-to-acorn

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[support]: https://github.com/micromark/.github/blob/main/support.md

[typescript]: https://www.typescriptlang.org


---

# micromark-util-html-tag-name

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility with list of html tag names.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`htmlBlockNames`](#htmlblocknames)
  * [`htmlRawNames`](#htmlrawnames)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes a list of known tag names to markdown.

## When should I use this?

This package is only useful if you want to build an alternative to micromark.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-html-tag-name
```

In Deno with [`esm.sh`][esmsh]:

```js
import {htmlBlockNames, htmlRawNames} from 'https://esm.sh/micromark-util-html-tag-name@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {htmlBlockNames, htmlRawNames} from 'https://esm.sh/micromark-util-html-tag-name@1?bundle'
</script>
```

## Use

```js
import {htmlBlockNames, htmlRawNames} from 'micromark-util-html-tag-name'

console.log(htmlBlockNames) // ['address', 'article', …]
console.log(htmlRawNames) // ['pre', 'script', …]
```

## API

This module exports the identifiers [`htmlBlockNames`][api-html-block-names]
and [`htmlRawNames`][api-html-raw-names].
There is no default export.

### `htmlBlockNames`

List of lowercase HTML “block” tag names (`Array<string>`).

The list, when parsing HTML (flow), results in more relaxed rules (condition
6\).
Because they are known blocks, the HTML-like syntax doesn’t have to be strictly
parsed.
For tag names not in this list, a more strict algorithm (condition 7) is used
to detect whether the HTML-like syntax is seen as HTML (flow) or not.

This is copied from:
<https://spec.commonmark.org/0.30/#html-blocks>.

> 👉 **Note**: `search` was added in `CommonMark@0.31`.

### `htmlRawNames`

List of lowercase HTML “raw” tag names (`Array<string>`).

The list, when parsing HTML (flow), results in HTML that can include lines
without exiting, until a closing tag also in this list is found (condition
1\).

This module is copied from:
<https://spec.commonmark.org/0.30/#html-blocks>.

> 👉 **Note**: `textarea` was added in `CommonMark@0.30`.

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-html-tag-name@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-html-tag-name.svg

[downloads]: https://www.npmjs.com/package/micromark-util-html-tag-name

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-html-tag-name

[bundle-size]: https://bundlejs.com/?q=micromark-util-html-tag-name

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[api-html-block-names]: #htmlblocknames

[api-html-raw-names]: #htmlrawnames


---

# micromark-util-symbol

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility with symbols.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes constants used throughout the micromark ecosystem.

## When should I use this?

This package is useful when you are making your own micromark extensions.
It’s useful to reference these constants by name instead of value while
developing.
[`micromark-build`][micromark-build] compiles them away for production code.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-symbol
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as symbol from 'https://esm.sh/micromark-util-symbol@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as symbol from 'https://esm.sh/micromark-util-symbol@1?bundle'
</script>
```

## Use

```js
import {codes, constants, types, values} from 'micromark-util-symbol'

console.log(codes.atSign) // 64
console.log(constants.characterReferenceNamedSizeMax) // 31
console.log(types.definitionDestinationRaw) // 'definitionDestinationRaw'
console.log(values.atSign) // '@'
```

## API

This package exports the identifiers `codes`, `constants`, `types`, and
`values`.
There is no default export.

Each identifier is an object mapping strings to values.
See the code for the exposed data.

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-symbol@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-symbol.svg

[downloads]: https://www.npmjs.com/package/micromark-util-symbol

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-symbol

[bundle-size]: https://bundlejs.com/?q=micromark-util-symbol

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[micromark-build]: https://github.com/micromark/micromark/tree/main/packages/micromark-build


---

# micromark-util-normalize-identifier

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility normalize identifiers.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`normalizeIdentifier(value)`](#normalizeidentifiervalue)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes an algorithm to normalize identifiers found in markdown.

## When should I use this?

This package might be useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-normalize-identifier
```

In Deno with [`esm.sh`][esmsh]:

```js
import {normalizeIdentifier} from 'https://esm.sh/micromark-util-normalize-identifier@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {normalizeIdentifier} from 'https://esm.sh/micromark-util-normalize-identifier@1?bundle'
</script>
```

## Use

```js
import {normalizeIdentifier} from 'micromark-util-normalize-identifier'

normalizeIdentifier(' a ') // 'A'
normalizeIdentifier('a\t\r\nb') // 'A B'
normalizeIdentifier('ТОЛПОЙ') // 'ТОЛПОЙ'
normalizeIdentifier('Толпой') // 'ТОЛПОЙ'
```

## API

This module exports the identifier
[`normalizeIdentifier`][api-normalize-identifier].
There is no default export.

### `normalizeIdentifier(value)`

Normalize an identifier (as found in references, definitions).

Collapses markdown whitespace, trim, and then lower- and uppercase.

Some characters are considered “uppercase”, such as U+03F4 (`ϴ`), but if their
lowercase counterpart (U+03B8 (`θ`)) is uppercased will result in a different
uppercase character (U+0398 (`Θ`)).
So, to get a canonical form, we perform both lower- and uppercase.

Using uppercase last makes sure keys will never interact with default
prototypal values (such as `constructor`): nothing in the prototype of `Object`
is uppercase.

###### Parameters

* `value` (`string`)
  — identifier to normalize

###### Returns

Normalized identifier (`string`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-normalize-identifier@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-normalize-identifier.svg

[downloads]: https://www.npmjs.com/package/micromark-util-normalize-identifier

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-normalize-identifier

[bundle-size]: https://bundlejs.com/?q=micromark-util-normalize-identifier

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[api-normalize-identifier]: #normalizeidentifiervalue


---

# micromark-util-resolve-all

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility to resolve subtokens.

[Resolvers][resolver] are functions that take events and manipulate them.
This is needed for example because media (links, images) and attention (strong,
italic) aren’t parsed left-to-right.
Instead, their openings and closings are parsed, and when done, their openings
and closings are matched, and left overs are turned into plain text.
Because media and attention can’t overlap, we need to perform that operation
when one closing matches an opening, too.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`resolveAll(constructs, events, context)`](#resolveallconstructs-events-context)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes a micromark internal that you probably don’t need.

## When should I use this?

This package might be useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-resolve-all
```

In Deno with [`esm.sh`][esmsh]:

```js
import {resolveAll} from 'https://esm.sh/micromark-util-resolve-all@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {resolveAll} from 'https://esm.sh/micromark-util-resolve-all@1?bundle'
</script>
```

## Use

```js
import {push} from 'micromark-util-chunked'
import {resolveAll} from 'micromark-util-resolve-all'

/**
 * @type {Resolver}
 */
function resolveAllAttention(events, context) {
  // …

  // Walk through all events.
  while (++index < events.length) {
    // Find a token that can close.
    if (
      events[index][0] === 'enter' &&
      events[index][1].type === 'attentionSequence' &&
      events[index][1]._close
    ) {
      open = index

      // Now walk back to find an opener.
      while (open--) {
        // Find a token that can open the closer.
        if (
          // …
        ) {
          // …

          // Opening.
          nextEvents = push(nextEvents, [
            // …
          ])

          // Between.
          nextEvents = push(
            nextEvents,
            resolveAll(
              context.parser.constructs.insideSpan.null,
              events.slice(open + 1, index),
              context
            )
          )

          // Closing.
          nextEvents = push(nextEvents, [
            // …
          ])

          // …
        }
      }
    }
  }

  // …
}
```

## API

This module exports the identifier [`resolveAll`][api-resolve-all].
There is no default export.

### `resolveAll(constructs, events, context)`

Call all `resolveAll`s in `constructs`.

###### Parameters

* `constructs` (`Array<Construct>`)
  — list of constructs, optionally with `resolveAll`s
* `events` (`Array<Event>`)
  — list of events
* `context` (`TokenizeContext`)
  — context used by `tokenize`

###### Returns

Changed events (`Array<Events>`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-resolve-all@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-resolve-all.svg

[downloads]: https://www.npmjs.com/package/micromark-util-resolve-all

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-resolve-all

[bundle-size]: https://bundlejs.com/?q=micromark-util-resolve-all

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[resolver]: https://github.com/micromark/micromark/blob/a571c09/packages/micromark-util-types/index.js#L219

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[api-resolve-all]: #resolveallconstructs-events-context


---

# micromark-util-character

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility to handle [character codes][code].

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`asciiAlpha(code)`](#asciialphacode)
  * [`asciiAlphanumeric(code)`](#asciialphanumericcode)
  * [`asciiAtext(code)`](#asciiatextcode)
  * [`asciiControl(code)`](#asciicontrolcode)
  * [`asciiDigit(code)`](#asciidigitcode)
  * [`asciiHexDigit(code)`](#asciihexdigitcode)
  * [`asciiPunctuation(code)`](#asciipunctuationcode)
  * [`markdownLineEnding(code)`](#markdownlineendingcode)
  * [`markdownLineEndingOrSpace(code)`](#markdownlineendingorspacecode)
  * [`markdownSpace(code)`](#markdownspacecode)
  * [`unicodePunctuation(code)`](#unicodepunctuationcode)
  * [`unicodeWhitespace(code)`](#unicodewhitespacecode)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes algorithms to check whether characters match groups.

## When should I use this?

This package might be useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-character
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as character from 'https://esm.sh/micromark-util-character@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as character from 'https://esm.sh/micromark-util-character@1?bundle'
</script>
```

## Use

```js
import {asciiAlpha} from 'micromark-util-character'

console.log(asciiAlpha(64)) // false
console.log(asciiAlpha(65)) // true
```

## API

This module exports the identifiers
[`asciiAlpha`][api-ascii-alpha],
[`asciiAlphanumeric`][api-ascii-alphanumeric],
[`asciiAtext`][api-ascii-atext],
[`asciiControl`][api-ascii-control],
[`asciiDigit`][api-ascii-digit],
[`asciiHexDigit`][api-ascii-hex-digit],
[`asciiPunctuation`][api-ascii-punctuation],
[`markdownLineEnding`][api-markdown-line-ending],
[`markdownLineEndingOrSpace`][api-markdown-line-ending-or-space],
[`markdownSpace`][api-markdown-space],
[`unicodePunctuation`][api-unicode-punctuation],
[`unicodeWhitespace`][api-unicode-whitespace].
There is no default export.

### `asciiAlpha(code)`

Check whether the [character code][code] represents an ASCII alpha (`a` through
`z`, case insensitive).

An **ASCII alpha** is an ASCII upper alpha or ASCII lower alpha.

An **ASCII upper alpha** is a character in the inclusive range U+0041 (`A`)
to U+005A (`Z`).

An **ASCII lower alpha** is a character in the inclusive range U+0061 (`a`)
to U+007A (`z`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiAlphanumeric(code)`

Check whether the [character code][code] represents an ASCII alphanumeric (`a`
through `z`, case insensitive, or `0` through `9`).

An **ASCII alphanumeric** is an ASCII digit (see `asciiDigit`) or ASCII alpha
(see `asciiAlpha`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiAtext(code)`

Check whether the [character code][code] represents an ASCII atext.

atext is an ASCII alphanumeric (see `asciiAlphanumeric`), or a character in
the inclusive ranges U+0023 NUMBER SIGN (`#`) to U+0027 APOSTROPHE (`'`),
U+002A ASTERISK (`*`), U+002B PLUS SIGN (`+`), U+002D DASH (`-`), U+002F
SLASH (`/`), U+003D EQUALS TO (`=`), U+003F QUESTION MARK (`?`), U+005E
CARET (`^`) to U+0060 GRAVE ACCENT (`` ` ``), or U+007B LEFT CURLY BRACE
(`{`) to U+007E TILDE (`~`) (**\[RFC5322]**).

See **\[RFC5322]**:\
[Internet Message Format](https://tools.ietf.org/html/rfc5322).\
P. Resnick.\
IETF.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiControl(code)`

Check whether a [character code][code] is an ASCII control character.

An **ASCII control** is a character in the inclusive range U+0000 NULL (NUL)
to U+001F (US), or U+007F (DEL).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiDigit(code)`

Check whether the [character code][code] represents an ASCII digit (`0` through
`9`).

An **ASCII digit** is a character in the inclusive range U+0030 (`0`) to
U+0039 (`9`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiHexDigit(code)`

Check whether the [character code][code] represents an ASCII hex digit (`a`
through `f`, case insensitive, or `0` through `9`).

An **ASCII hex digit** is an ASCII digit (see `asciiDigit`), ASCII upper hex
digit, or an ASCII lower hex digit.

An **ASCII upper hex digit** is a character in the inclusive range U+0041
(`A`) to U+0046 (`F`).

An **ASCII lower hex digit** is a character in the inclusive range U+0061
(`a`) to U+0066 (`f`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `asciiPunctuation(code)`

Check whether the [character code][code] represents ASCII punctuation.

An **ASCII punctuation** is a character in the inclusive ranges U+0021
EXCLAMATION MARK (`!`) to U+002F SLASH (`/`), U+003A COLON (`:`) to U+0040 AT
SIGN (`@`), U+005B LEFT SQUARE BRACKET (`[`) to U+0060 GRAVE ACCENT
(`` ` ``), or U+007B LEFT CURLY BRACE (`{`) to U+007E TILDE (`~`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownLineEnding(code)`

Check whether a [character code][code] is a markdown line ending.

A **markdown line ending** is the virtual characters M-0003 CARRIAGE RETURN
LINE FEED (CRLF), M-0004 LINE FEED (LF) and M-0005 CARRIAGE RETURN (CR).

In micromark, the actual character U+000A LINE FEED (LF) and U+000D CARRIAGE
RETURN (CR) are replaced by these virtual characters depending on whether
they occurred together.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownLineEndingOrSpace(code)`

Check whether a [character code][code] is a markdown line ending (see
`markdownLineEnding`) or markdown space (see `markdownSpace`).

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `markdownSpace(code)`

Check whether a [character code][code] is a markdown space.

A **markdown space** is the concrete character U+0020 SPACE (SP) and the
virtual characters M-0001 VIRTUAL SPACE (VS) and M-0002 HORIZONTAL TAB (HT).

In micromark, the actual character U+0009 CHARACTER TABULATION (HT) is
replaced by one M-0002 HORIZONTAL TAB (HT) and between 0 and 3 M-0001 VIRTUAL
SPACE (VS) characters, depending on the column at which the tab occurred.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `unicodePunctuation(code)`

Check whether the [character code][code] represents Unicode punctuation.

A **Unicode punctuation** is a character in the Unicode `Pc` (Punctuation,
Connector), `Pd` (Punctuation, Dash), `Pe` (Punctuation, Close), `Pf`
(Punctuation, Final quote), `Pi` (Punctuation, Initial quote), `Po`
(Punctuation, Other), or `Ps` (Punctuation, Open) categories, or an ASCII
punctuation (see `asciiPunctuation`) (**\[UNICODE]**).

See **\[UNICODE]**:\
[The Unicode Standard](https://www.unicode.org/versions/).\
Unicode Consortium.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

### `unicodeWhitespace(code)`

Check whether the [character code][code] represents Unicode whitespace.

Note that this does handle micromark specific markdown whitespace characters.
See `markdownLineEndingOrSpace` to check that.

A **Unicode whitespace** is a character in the Unicode `Zs` (Separator,
Space) category, or U+0009 CHARACTER TABULATION (HT), U+000A LINE FEED (LF),
U+000C (FF), or U+000D CARRIAGE RETURN (CR) (**\[UNICODE]**).

See **\[UNICODE]**:\
[The Unicode Standard](https://www.unicode.org/versions/).\
Unicode Consortium.

###### Parameters

* `code` (`Code`)
  — code

###### Returns

Whether it matches (`boolean`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-character@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-character.svg

[downloads]: https://www.npmjs.com/package/micromark-util-character

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-character

[bundle-size]: https://bundlejs.com/?q=micromark-util-character

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[code]: https://github.com/micromark/micromark#preprocess

[api-ascii-alpha]: #asciialphacode

[api-ascii-alphanumeric]: #asciialphanumericcode

[api-ascii-atext]: #asciiatextcode

[api-ascii-control]: #asciicontrolcode

[api-ascii-digit]: #asciidigitcode

[api-ascii-hex-digit]: #asciihexdigitcode

[api-ascii-punctuation]: #asciipunctuationcode

[api-markdown-line-ending]: #markdownlineendingcode

[api-markdown-line-ending-or-space]: #markdownlineendingorspacecode

[api-markdown-space]: #markdownspacecode

[api-unicode-punctuation]: #unicodepunctuationcode

[api-unicode-whitespace]: #unicodewhitespacecode


---

# micromark-util-symbol

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility with symbols.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes constants used throughout the micromark ecosystem.

## When should I use this?

This package is useful when you are making your own micromark extensions.
It’s useful to reference these constants by name instead of value while
developing.
[`micromark-build`][micromark-build] compiles them away for production code.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-symbol
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as symbol from 'https://esm.sh/micromark-util-symbol@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as symbol from 'https://esm.sh/micromark-util-symbol@1?bundle'
</script>
```

## Use

```js
import {codes, constants, types, values} from 'micromark-util-symbol'

console.log(codes.atSign) // 64
console.log(constants.characterReferenceNamedSizeMax) // 31
console.log(types.definitionDestinationRaw) // 'definitionDestinationRaw'
console.log(values.atSign) // '@'
```

## API

This package exports the identifiers `codes`, `constants`, `types`, and
`values`.
There is no default export.

Each identifier is an object mapping strings to values.
See the code for the exposed data.

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-symbol@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-symbol.svg

[downloads]: https://www.npmjs.com/package/micromark-util-symbol

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-symbol

[bundle-size]: https://bundlejs.com/?q=micromark-util-symbol

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[micromark-build]: https://github.com/micromark/micromark/tree/main/packages/micromark-build


---

# micromark-util-sanitize-uri

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility to sanitize urls.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`normalizeUri(value)`](#normalizeurivalue)
  * [`sanitizeUri(url[, pattern])`](#sanitizeuriurl-pattern)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes an algorithm to make URLs safe.

## When should I use this?

This package might be useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-sanitize-uri
```

In Deno with [`esm.sh`][esmsh]:

```js
import {sanitizeUri} from 'https://esm.sh/micromark-util-sanitize-uri@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {sanitizeUri} from 'https://esm.sh/micromark-util-sanitize-uri@1?bundle'
</script>
```

## Use

```js
import {sanitizeUri} from 'micromark-util-sanitize-uri'

sanitizeUri('https://example.com/a&amp;b') // 'https://example.com/a&amp;amp;b'
sanitizeUri('https://example.com/a%b') // 'https://example.com/a%25b'
sanitizeUri('https://example.com/a%20b') // 'https://example.com/a%20b'
sanitizeUri('https://example.com/👍') // 'https://example.com/%F0%9F%91%8D'
sanitizeUri('https://example.com/', /^https?$/i) // 'https://example.com/'
sanitizeUri('javascript:alert(1)', /^https?$/i) // ''
sanitizeUri('./example.jpg', /^https?$/i) // './example.jpg'
sanitizeUri('#a', /^https?$/i) // '#a'
```

## API

This module exports the identifiers [`normalizeUri`][api-normalize-uri] and
[`sanitizeUri`][api-sanitize-uri].
There is no default export.

### `normalizeUri(value)`

Normalize a URL.

Encode unsafe characters with percent-encoding, skipping already encoded
sequences.

###### Parameters

* `value` (`string`)
  — URI to normalize

###### Returns

Normalized URI (`string`).

### `sanitizeUri(url[, pattern])`

Make a value safe for injection as a URL.

This encodes unsafe characters with percent-encoding and skips already
encoded sequences (see [`normalizeUri`][api-normalize-uri]).
Further unsafe characters are encoded as character references (see
[`micromark-util-encode`][micromark-util-encode]).

A regex of allowed protocols can be given, in which case the URL is sanitized.
For example, `/^(https?|ircs?|mailto|xmpp)$/i` can be used for `a[href]`, or
`/^https?$/i` for `img[src]` (this is what `github.com` allows).
If the URL includes an unknown protocol (one not matched by `protocol`, such
as a dangerous example, `javascript:`), the value is ignored.

###### Parameters

* `url` (`string`)
  — URI to sanitize
* `pattern` (`RegExp`, optional)
  — allowed protocols

###### Returns

Sanitized URI (`string`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-sanitize-uri@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-sanitize-uri.svg

[downloads]: https://www.npmjs.com/package/micromark-util-sanitize-uri

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-sanitize-uri

[bundle-size]: https://bundlejs.com/?q=micromark-util-sanitize-uri

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[micromark-util-encode]: https://github.com/micromark/micromark/tree/main/packages/micromark-util-encode

[api-normalize-uri]: #normalizeurivalue

[api-sanitize-uri]: #sanitizeuriurl-pattern


---

# micromark-util-symbol

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility with symbols.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes constants used throughout the micromark ecosystem.

## When should I use this?

This package is useful when you are making your own micromark extensions.
It’s useful to reference these constants by name instead of value while
developing.
[`micromark-build`][micromark-build] compiles them away for production code.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-symbol
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as symbol from 'https://esm.sh/micromark-util-symbol@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as symbol from 'https://esm.sh/micromark-util-symbol@1?bundle'
</script>
```

## Use

```js
import {codes, constants, types, values} from 'micromark-util-symbol'

console.log(codes.atSign) // 64
console.log(constants.characterReferenceNamedSizeMax) // 31
console.log(types.definitionDestinationRaw) // 'definitionDestinationRaw'
console.log(values.atSign) // '@'
```

## API

This package exports the identifiers `codes`, `constants`, `types`, and
`values`.
There is no default export.

Each identifier is an object mapping strings to values.
See the code for the exposed data.

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-symbol@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-symbol.svg

[downloads]: https://www.npmjs.com/package/micromark-util-symbol

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-symbol

[bundle-size]: https://bundlejs.com/?q=micromark-util-symbol

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[micromark-build]: https://github.com/micromark/micromark/tree/main/packages/micromark-build


---

# micromark-util-subtokenize

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility to tokenize subtokens.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`subtokenize(events)`](#subtokenizeevents)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes a micromark internal that you probably don’t need.

## When should I use this?

This package might be useful when you are making your own micromark extensions.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-subtokenize
```

In Deno with [`esm.sh`][esmsh]:

```js
import {subtokenize} from 'https://esm.sh/micromark-util-subtokenize@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {subtokenize} from 'https://esm.sh/micromark-util-subtokenize@1?bundle'
</script>
```

## Use

```js
import {subtokenize} from 'micromark-util-subtokenize'

/**
 * Content is transparent: it’s parsed right now. That way, definitions are also
 * parsed right now: before text in paragraphs (specifically, media) are parsed.
 *
 * @type {Resolver}
 */
function resolveContent(events) {
  subtokenize(events)
  return events
}
```

## API

This module exports the identifiers [`subtokenize`][api-subtokenize].
There is no default export.

### `subtokenize(events)`

Tokenize subcontent.

###### Parameters

* `events` (`Array<Event>`)
  — list of events

###### Returns

Whether subtokens were found (`boolean`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-subtokenize@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[api-subtokenize]: #subtokenizeevents

[author]: https://wooorm.com

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[build]: https://github.com/micromark/micromark/actions

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[bundle-size]: https://bundlejs.com/?q=micromark-util-subtokenize

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-subtokenize

[chat]: https://github.com/micromark/micromark/discussions

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[coverage]: https://codecov.io/github/micromark/micromark

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[downloads]: https://www.npmjs.com/package/micromark-util-subtokenize

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-subtokenize.svg

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[health]: https://github.com/micromark/.github

[license]: https://github.com/micromark/micromark/blob/main/license

[micromark]: https://github.com/micromark/micromark

[npm]: https://docs.npmjs.com/cli/install

[opencollective]: https://opencollective.com/unified

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[support]: https://github.com/micromark/.github/blob/main/support.md

[typescript]: https://www.typescriptlang.org


---

# micromark-util-symbol

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility with symbols.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Security](#security)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package exposes constants used throughout the micromark ecosystem.

## When should I use this?

This package is useful when you are making your own micromark extensions.
It’s useful to reference these constants by name instead of value while
developing.
[`micromark-build`][micromark-build] compiles them away for production code.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-symbol
```

In Deno with [`esm.sh`][esmsh]:

```js
import {codes} from 'https://esm.sh/micromark-util-symbol/codes@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {codes} from 'https://esm.sh/micromark-util-symbol/codes@1?bundle'
</script>
```

## Use

```js
import {codes} from 'micromark-util-symbol/codes'
import {constants} from 'micromark-util-symbol/constants'
import {types} from 'micromark-util-symbol/types'
import {values} from 'micromark-util-symbol/values'

console.log(codes.atSign) // 64
console.log(constants.characterReferenceNamedSizeMax) // 31
console.log(types.definitionDestinationRaw) // 'definitionDestinationRaw'
console.log(values.atSign) // '@'
```

## API

This package has four entries in its export map: `micromark-util-symbol/codes`,
`micromark-util-symbol/constants`, `micromark-util-symbol/types`,
`micromark-util-symbol/values`.

Each module exports an identifier with the same name (for example,
`micromark-util-symbol/codes` has `codes`), which is an object mapping strings
to other values.

See the code for the exposed data.

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with all maintained
versions of Node.js.
As of now, that is Node.js 16+.
Our projects sometimes work with older versions, but this is not guaranteed.

This package works with `micromark` version 3+.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[build]: https://github.com/micromark/micromark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[coverage]: https://codecov.io/github/micromark/micromark

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-symbol.svg

[downloads]: https://www.npmjs.com/package/micromark-util-symbol

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-symbol

[bundle-size]: https://bundlejs.com/?q=micromark-util-symbol

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[opencollective]: https://opencollective.com/unified

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/micromark/micromark/discussions

[license]: https://github.com/micromark/micromark/blob/main/license

[author]: https://wooorm.com

[health]: https://github.com/micromark/.github

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[support]: https://github.com/micromark/.github/blob/main/support.md

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[typescript]: https://www.typescriptlang.org

[micromark]: https://github.com/micromark/micromark

[micromark-build]: https://github.com/micromark/micromark/tree/main/packages/micromark-build


---

# micromark-util-types

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][bundle-size-badge]][bundle-size]
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]

[micromark][] utility package with TypeScript types.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package exposes TypeScript types shared throughout the micromark
ecosystem.

## When should I use this?

This package is useful when you are making your own, typed, micromark
extensions.

## Install

In Node.js (version 16+), install with [npm][]:

```sh
npm install micromark-util-types
```

In Deno with [`esm.sh`][esmsh]:

```js
import type {Point, /* … */} from 'https://esm.sh/micromark-util-types@1'
```

## Use

```js
/**
 * @import {Point} from 'micromark-util-types'
 */
```

## API

This module exports no identifiers.
There is no default export.

See [the code][code] for all about the exposed types.

## Types

This package is just [TypeScript][] types.
It exports lots of different types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`micromark-util-types@2`, compatible with Node.js 16.
This package works with `micromark@3`.

## Security

This package is safe.
See [`security.md`][securitymd] in [`micromark/.github`][health] for how to
submit a security report.

## Contribute

See [`contributing.md`][contributing] in [`micromark/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[author]: https://wooorm.com

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[build]: https://github.com/micromark/micromark/actions

[build-badge]: https://github.com/micromark/micromark/workflows/main/badge.svg

[bundle-size]: https://bundlejs.com/?q=micromark-util-encode

[bundle-size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-util-encode

[chat]: https://github.com/micromark/micromark/discussions

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md

[code]: https://github.com/micromark/micromark/blob/main/packages/micromark-util-types/index.d.ts

[contributing]: https://github.com/micromark/.github/blob/main/contributing.md

[coverage]: https://codecov.io/github/micromark/micromark

[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark.svg

[downloads]: https://www.npmjs.com/package/micromark-util-encode

[downloads-badge]: https://img.shields.io/npm/dm/micromark-util-encode.svg

[esmsh]: https://esm.sh

[health]: https://github.com/micromark/.github

[license]: https://github.com/micromark/micromark/blob/main/license

[micromark]: https://github.com/micromark/micromark

[npm]: https://docs.npmjs.com/cli/install

[opencollective]: https://opencollective.com/unified

[securitymd]: https://github.com/micromark/.github/blob/main/security.md

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[support]: https://github.com/micromark/.github/blob/main/support.md

[typescript]: https://www.typescriptlang.org


---

# micromatch [![NPM version](https://img.shields.io/npm/v/micromatch.svg?style=flat)](https://www.npmjs.com/package/micromatch) [![NPM monthly downloads](https://img.shields.io/npm/dm/micromatch.svg?style=flat)](https://npmjs.org/package/micromatch) [![NPM total downloads](https://img.shields.io/npm/dt/micromatch.svg?style=flat)](https://npmjs.org/package/micromatch)  [![Tests](https://github.com/micromatch/micromatch/actions/workflows/test.yml/badge.svg)](https://github.com/micromatch/micromatch/actions/workflows/test.yml)

> Glob matching for javascript/node.js. A replacement and faster alternative to minimatch and multimatch.

Please consider following this project's author, [Jon Schlinkert](https://github.com/jonschlinkert), and consider starring the project to show your :heart: and support.

## Table of Contents

<details>
<summary><strong>Details</strong></summary>

  * [Install](#install)
- [Sponsors](#sponsors)
  * [Gold Sponsors](#gold-sponsors)
  * [Quickstart](#quickstart)
  * [Why use micromatch?](#why-use-micromatch)
    + [Matching features](#matching-features)
  * [Switching to micromatch](#switching-to-micromatch)
    + [From minimatch](#from-minimatch)
    + [From multimatch](#from-multimatch)
  * [API](#api)
  * [Options](#options)
  * [Options Examples](#options-examples)
    + [options.basename](#optionsbasename)
    + [options.bash](#optionsbash)
    + [options.expandRange](#optionsexpandrange)
    + [options.format](#optionsformat)
    + [options.ignore](#optionsignore)
    + [options.matchBase](#optionsmatchbase)
    + [options.noextglob](#optionsnoextglob)
    + [options.nonegate](#optionsnonegate)
    + [options.noglobstar](#optionsnoglobstar)
    + [options.nonull](#optionsnonull)
    + [options.nullglob](#optionsnullglob)
    + [options.onIgnore](#optionsonignore)
    + [options.onMatch](#optionsonmatch)
    + [options.onResult](#optionsonresult)
    + [options.posixSlashes](#optionsposixslashes)
    + [options.unescape](#optionsunescape)
  * [Extended globbing](#extended-globbing)
    + [Extglobs](#extglobs)
    + [Braces](#braces)
    + [Regex character classes](#regex-character-classes)
    + [Regex groups](#regex-groups)
    + [POSIX bracket expressions](#posix-bracket-expressions)
  * [Notes](#notes)
    + [Bash 4.3 parity](#bash-43-parity)
    + [Backslashes](#backslashes)
  * [Benchmarks](#benchmarks)
    + [Running benchmarks](#running-benchmarks)
    + [Latest results](#latest-results)
  * [Contributing](#contributing)
  * [About](#about)

</details>

## Install

Install with [npm](https://www.npmjs.com/):

```sh
$ npm install --save micromatch
```

<br />

# Sponsors

[Become a Sponsor](https://github.com/sponsors/jonschlinkert) to add your logo to this README, or any of [my other projects](https://github.com/jonschlinkert?tab=repositories&q=&type=&language=&sort=stargazers)

<br />

## Quickstart

```js
const micromatch = require('micromatch');
// micromatch(list, patterns[, options]);
```

The [main export](#micromatch) takes a list of strings and one or more glob patterns:

```js
console.log(micromatch(['foo', 'bar', 'baz', 'qux'], ['f*', 'b*'])) //=> ['foo', 'bar', 'baz']
console.log(micromatch(['foo', 'bar', 'baz', 'qux'], ['*', '!b*'])) //=> ['foo', 'qux']
```

Use [.isMatch()](#ismatch) to for boolean matching:

```js
console.log(micromatch.isMatch('foo', 'f*')) //=> true
console.log(micromatch.isMatch('foo', ['b*', 'f*'])) //=> true
```

[Switching](#switching-to-micromatch) from minimatch and multimatch is easy!

<br>

## Why use micromatch?

> micromatch is a [replacement](#switching-to-micromatch) for minimatch and multimatch

* Supports all of the same matching features as [minimatch](https://github.com/isaacs/minimatch) and [multimatch](https://github.com/sindresorhus/multimatch)
* More complete support for the Bash 4.3 specification than minimatch and multimatch. Micromatch passes _all of the spec tests_ from bash, including some that bash still fails.
* **Fast & Performant** - Loads in about 5ms and performs [fast matches](#benchmarks).
* **Glob matching** - Using wildcards (`*` and `?`), globstars (`**`) for nested directories
* **[Advanced globbing](#extended-globbing)** - Supports [extglobs](#extglobs), [braces](#braces-1), and [POSIX brackets](#posix-bracket-expressions), and support for escaping special characters with `\` or quotes.
* **Accurate** - Covers more scenarios [than minimatch](https://github.com/yarnpkg/yarn/pull/3339)
* **Well tested** - More than 5,000 [test assertions](./test)
* **Windows support** - More reliable windows support than minimatch and multimatch.
* **[Safe](https://github.com/micromatch/braces#braces-is-safe)** - Micromatch is not subject to DoS with brace patterns like minimatch and multimatch.

### Matching features

* Support for multiple glob patterns (no need for wrappers like multimatch)
* Wildcards (`**`, `*.js`)
* Negation (`'!a/*.js'`, `'*!(b).js'`)
* [extglobs](#extglobs) (`+(x|y)`, `!(a|b)`)
* [POSIX character classes](#posix-bracket-expressions) (`[[:alpha:][:digit:]]`)
* [brace expansion](https://github.com/micromatch/braces) (`foo/{1..5}.md`, `bar/{a,b,c}.js`)
* regex character classes (`foo-[1-5].js`)
* regex logical "or" (`foo/(abc|xyz).js`)

You can mix and match these features to create whatever patterns you need!

## Switching to micromatch

_(There is one notable difference between micromatch and minimatch in regards to how backslashes are handled. See [the notes about backslashes](#backslashes) for more information.)_

### From minimatch

Use [micromatch.isMatch()](#ismatch) instead of `minimatch()`:

```js
console.log(micromatch.isMatch('foo', 'b*')); //=> false
```

Use [micromatch.match()](#match) instead of `minimatch.match()`:

```js
console.log(micromatch.match(['foo', 'bar'], 'b*')); //=> 'bar'
```

### From multimatch

Same signature:

```js
console.log(micromatch(['foo', 'bar', 'baz'], ['f*', '*z'])); //=> ['foo', 'baz']
```

## API

**Params**

* `list` **{String|Array<string>}**: List of strings to match.
* `patterns` **{String|Array<string>}**: One or more glob patterns to use for matching.
* `options` **{Object}**: See available [options](#options)
* `returns` **{Array}**: Returns an array of matches

**Example**

```js
const mm = require('micromatch');
// mm(list, patterns[, options]);

console.log(mm(['a.js', 'a.txt'], ['*.js']));
//=> [ 'a.js' ]
```

### [.matcher](index.js#L109)

Returns a matcher function from the given glob `pattern` and `options`. The returned function takes a string to match as its only argument and returns true if the string is a match.

**Params**

* `pattern` **{String}**: Glob pattern
* `options` **{Object}**
* `returns` **{Function}**: Returns a matcher function.

**Example**

```js
const mm = require('micromatch');
// mm.matcher(pattern[, options]);

const isMatch = mm.matcher('*.!(*a)');
console.log(isMatch('a.a')); //=> false
console.log(isMatch('a.b')); //=> true
```

### [.isMatch](index.js#L128)

Returns true if **any** of the given glob `patterns` match the specified `string`.

**Params**

* `str` **{String}**: The string to test.
* `patterns` **{String|Array}**: One or more glob patterns to use for matching.
* `[options]` **{Object}**: See available [options](#options).
* `returns` **{Boolean}**: Returns true if any patterns match `str`

**Example**

```js
const mm = require('micromatch');
// mm.isMatch(string, patterns[, options]);

console.log(mm.isMatch('a.a', ['b.*', '*.a'])); //=> true
console.log(mm.isMatch('a.a', 'b.*')); //=> false
```

### [.not](index.js#L153)

Returns a list of strings that _**do not match any**_ of the given `patterns`.

**Params**

* `list` **{Array}**: Array of strings to match.
* `patterns` **{String|Array}**: One or more glob pattern to use for matching.
* `options` **{Object}**: See available [options](#options) for changing how matches are performed
* `returns` **{Array}**: Returns an array of strings that **do not match** the given patterns.

**Example**

```js
const mm = require('micromatch');
// mm.not(list, patterns[, options]);

console.log(mm.not(['a.a', 'b.b', 'c.c'], '*.a'));
//=> ['b.b', 'c.c']
```

### [.contains](index.js#L193)

Returns true if the given `string` contains the given pattern. Similar to [.isMatch](#isMatch) but the pattern can match any part of the string.

**Params**

* `str` **{String}**: The string to match.
* `patterns` **{String|Array}**: Glob pattern to use for matching.
* `options` **{Object}**: See available [options](#options) for changing how matches are performed
* `returns` **{Boolean}**: Returns true if any of the patterns matches any part of `str`.

**Example**

```js
var mm = require('micromatch');
// mm.contains(string, pattern[, options]);

console.log(mm.contains('aa/bb/cc', '*b'));
//=> true
console.log(mm.contains('aa/bb/cc', '*d'));
//=> false
```

### [.matchKeys](index.js#L235)

Filter the keys of the given object with the given `glob` pattern and `options`. Does not attempt to match nested keys. If you need this feature, use [glob-object](https://github.com/jonschlinkert/glob-object) instead.

**Params**

* `object` **{Object}**: The object with keys to filter.
* `patterns` **{String|Array}**: One or more glob patterns to use for matching.
* `options` **{Object}**: See available [options](#options) for changing how matches are performed
* `returns` **{Object}**: Returns an object with only keys that match the given patterns.

**Example**

```js
const mm = require('micromatch');
// mm.matchKeys(object, patterns[, options]);

const obj = { aa: 'a', ab: 'b', ac: 'c' };
console.log(mm.matchKeys(obj, '*b'));
//=> { ab: 'b' }
```

### [.some](index.js#L264)

Returns true if some of the strings in the given `list` match any of the given glob `patterns`.

**Params**

* `list` **{String|Array}**: The string or array of strings to test. Returns as soon as the first match is found.
* `patterns` **{String|Array}**: One or more glob patterns to use for matching.
* `options` **{Object}**: See available [options](#options) for changing how matches are performed
* `returns` **{Boolean}**: Returns true if any `patterns` matches any of the strings in `list`

**Example**

```js
const mm = require('micromatch');
// mm.some(list, patterns[, options]);

console.log(mm.some(['foo.js', 'bar.js'], ['*.js', '!foo.js']));
// true
console.log(mm.some(['foo.js'], ['*.js', '!foo.js']));
// false
```

### [.every](index.js#L300)

Returns true if every string in the given `list` matches any of the given glob `patterns`.

**Params**

* `list` **{String|Array}**: The string or array of strings to test.
* `patterns` **{String|Array}**: One or more glob patterns to use for matching.
* `options` **{Object}**: See available [options](#options) for changing how matches are performed
* `returns` **{Boolean}**: Returns true if all `patterns` matches all of the strings in `list`

**Example**

```js
const mm = require('micromatch');
// mm.every(list, patterns[, options]);

console.log(mm.every('foo.js', ['foo.js']));
// true
console.log(mm.every(['foo.js', 'bar.js'], ['*.js']));
// true
console.log(mm.every(['foo.js', 'bar.js'], ['*.js', '!foo.js']));
// false
console.log(mm.every(['foo.js'], ['*.js', '!foo.js']));
// false
```

### [.all](index.js#L339)

Returns true if **all** of the given `patterns` match the specified string.

**Params**

* `str` **{String|Array}**: The string to test.
* `patterns` **{String|Array}**: One or more glob patterns to use for matching.
* `options` **{Object}**: See available [options](#options) for changing how matches are performed
* `returns` **{Boolean}**: Returns true if any patterns match `str`

**Example**

```js
const mm = require('micromatch');
// mm.all(string, patterns[, options]);

console.log(mm.all('foo.js', ['foo.js']));
// true

console.log(mm.all('foo.js', ['*.js', '!foo.js']));
// false

console.log(mm.all('foo.js', ['*.js', 'foo.js']));
// true

console.log(mm.all('foo.js', ['*.js', 'f*', '*o*', '*o.js']));
// true
```

### [.capture](index.js#L366)

Returns an array of matches captured by `pattern` in `string, or`null` if the pattern did not match.

**Params**

* `glob` **{String}**: Glob pattern to use for matching.
* `input` **{String}**: String to match
* `options` **{Object}**: See available [options](#options) for changing how matches are performed
* `returns` **{Array|null}**: Returns an array of captures if the input matches the glob pattern, otherwise `null`.

**Example**

```js
const mm = require('micromatch');
// mm.capture(pattern, string[, options]);

console.log(mm.capture('test/*.js', 'test/foo.js'));
//=> ['foo']
console.log(mm.capture('test/*.js', 'foo/bar.css'));
//=> null
```

### [.makeRe](index.js#L392)

Create a regular expression from the given glob `pattern`.

**Params**

* `pattern` **{String}**: A glob pattern to convert to regex.
* `options` **{Object}**
* `returns` **{RegExp}**: Returns a regex created from the given pattern.

**Example**

```js
const mm = require('micromatch');
// mm.makeRe(pattern[, options]);

console.log(mm.makeRe('*.js'));
//=> /^(?:(\.[\\\/])?(?!\.)(?=.)[^\/]*?\.js)$/
```

### [.scan](index.js#L408)

Scan a glob pattern to separate the pattern into segments. Used by the [split](#split) method.

**Params**

* `pattern` **{String}**
* `options` **{Object}**
* `returns` **{Object}**: Returns an object with

**Example**

```js
const mm = require('micromatch');
const state = mm.scan(pattern[, options]);
```

### [.parse](index.js#L424)

Parse a glob pattern to create the source string for a regular expression.

**Params**

* `glob` **{String}**
* `options` **{Object}**
* `returns` **{Object}**: Returns an object with useful properties and output to be used as regex source string.

**Example**

```js
const mm = require('micromatch');
const state = mm.parse(pattern[, options]);
```

### [.braces](index.js#L451)

Process the given brace `pattern`.

**Params**

* `pattern` **{String}**: String with brace pattern to process.
* `options` **{Object}**: Any [options](#options) to change how expansion is performed. See the [braces](https://github.com/micromatch/braces) library for all available options.
* `returns` **{Array}**

**Example**

```js
const { braces } = require('micromatch');
console.log(braces('foo/{a,b,c}/bar'));
//=> [ 'foo/(a|b|c)/bar' ]

console.log(braces('foo/{a,b,c}/bar', { expand: true }));
//=> [ 'foo/a/bar', 'foo/b/bar', 'foo/c/bar' ]
```

## Options

| **Option** | **Type** | **Default value** | **Description** |
| --- | --- | --- | --- |
| `basename`            | `boolean`      | `false`     | If set, then patterns without slashes will be matched against the basename of the path if it contains slashes.  For example, `a?b` would match the path `/xyz/123/acb`, but not `/xyz/acb/123`. |
| `bash`                | `boolean`      | `false`     | Follow bash matching rules more strictly - disallows backslashes as escape characters, and treats single stars as globstars (`**`). |
| `capture`             | `boolean`      | `undefined` | Return regex matches in supporting methods. |
| `contains`            | `boolean`      | `undefined` | Allows glob to match any part of the given string(s). |
| `cwd`                 | `string`       | `process.cwd()` | Current working directory. Used by `picomatch.split()` |
| `debug`               | `boolean`      | `undefined` | Debug regular expressions when an error is thrown. |
| `dot`                 | `boolean`      | `false`     | Match dotfiles. Otherwise dotfiles are ignored unless a `.` is explicitly defined in the pattern. |
| `expandRange`         | `function`     | `undefined` | Custom function for expanding ranges in brace patterns, such as `{a..z}`. The function receives the range values as two arguments, and it must return a string to be used in the generated regex. It's recommended that returned strings be wrapped in parentheses. This option is overridden by the `expandBrace` option. |
| `failglob`            | `boolean`      | `false`     | Similar to the `failglob` behavior in Bash, throws an error when no matches are found. Based on the bash option of the same name. |
| `fastpaths`           | `boolean`      | `true`      | To speed up processing, full parsing is skipped for a handful common glob patterns. Disable this behavior by setting this option to `false`. |
| `flags`               | `boolean`      | `undefined` | Regex flags to use in the generated regex. If defined, the `nocase` option will be overridden. |
| [format](#optionsformat) | `function` | `undefined` | Custom function for formatting the returned string. This is useful for removing leading slashes, converting Windows paths to Posix paths, etc. |
| `ignore`              | `array\|string` | `undefined` | One or more glob patterns for excluding strings that should not be matched from the result. |
| `keepQuotes`          | `boolean`      | `false`     | Retain quotes in the generated regex, since quotes may also be used as an alternative to backslashes.  |
| `literalBrackets`     | `boolean`      | `undefined` | When `true`, brackets in the glob pattern will be escaped so that only literal brackets will be matched. |
| `lookbehinds`         | `boolean`      | `true`      | Support regex positive and negative lookbehinds. Note that you must be using Node 8.1.10 or higher to enable regex lookbehinds. |
| `matchBase`           | `boolean`      | `false`     | Alias for `basename` |
| `maxLength`           | `boolean`      | `65536`     | Limit the max length of the input string. An error is thrown if the input string is longer than this value. |
| `nobrace`             | `boolean`      | `false`     | Disable brace matching, so that `{a,b}` and `{1..3}` would be treated as literal characters. |
| `nobracket`           | `boolean`      | `undefined` | Disable matching with regex brackets. |
| `nocase`              | `boolean`      | `false`     | Perform case-insensitive matching. Equivalent to the regex `i` flag. Note that this option is ignored when the `flags` option is defined. |
| `nodupes`             | `boolean`      | `true`      | Deprecated, use `nounique` instead. This option will be removed in a future major release. By default duplicates are removed. Disable uniquification by setting this option to false. |
| `noext`               | `boolean`      | `false`     | Alias for `noextglob` |
| `noextglob`           | `boolean`      | `false`     | Disable support for matching with [extglobs](#extglobs) (like `+(a\|b)`) |
| `noglobstar`          | `boolean`      | `false`     | Disable support for matching nested directories with globstars (`**`) |
| `nonegate`            | `boolean`      | `false`     | Disable support for negating with leading `!` |
| `noquantifiers`       | `boolean`      | `false`     | Disable support for regex quantifiers (like `a{1,2}`) and treat them as brace patterns to be expanded. |
| [onIgnore](#optionsonIgnore) | `function` | `undefined` | Function to be called on ignored items. |
| [onMatch](#optionsonMatch) | `function` | `undefined` | Function to be called on matched items. |
| [onResult](#optionsonResult) | `function` | `undefined` | Function to be called on all items, regardless of whether or not they are matched or ignored. |
| `posix`               | `boolean`      | `false`     | Support [POSIX character classes](#posix-bracket-expressions) ("posix brackets"). |
| `posixSlashes`        | `boolean`      | `undefined` | Convert all slashes in file paths to forward slashes. This does not convert slashes in the glob pattern itself |
| `prepend`             | `string`       | `undefined` | String to prepend to the generated regex used for matching. |
| `regex`               | `boolean`      | `false`     | Use regular expression rules for `+` (instead of matching literal `+`), and for stars that follow closing parentheses or brackets (as in `)*` and `]*`). |
| `strictBrackets`      | `boolean`      | `undefined` | Throw an error if brackets, braces, or parens are imbalanced. |
| `strictSlashes`       | `boolean`      | `undefined` | When true, picomatch won't match trailing slashes with single stars. |
| `unescape`            | `boolean`      | `undefined` | Remove preceding backslashes from escaped glob characters before creating the regular expression to perform matches. |
| `unixify`             | `boolean`      | `undefined` | Alias for `posixSlashes`, for backwards compatitibility. |

## Options Examples

### options.basename

Allow glob patterns without slashes to match a file path based on its basename. Same behavior as [minimatch](https://github.com/isaacs/minimatch) option `matchBase`.

**Type**: `Boolean`

**Default**: `false`

**Example**

```js
micromatch(['a/b.js', 'a/c.md'], '*.js');
//=> []

micromatch(['a/b.js', 'a/c.md'], '*.js', { basename: true });
//=> ['a/b.js']
```

### options.bash

Enabled by default, this option enforces bash-like behavior with stars immediately following a bracket expression. Bash bracket expressions are similar to regex character classes, but unlike regex, a star following a bracket expression **does not repeat the bracketed characters**. Instead, the star is treated the same as any other star.

**Type**: `Boolean`

**Default**: `true`

**Example**

```js
const files = ['abc', 'ajz'];
console.log(micromatch(files, '[a-c]*'));
//=> ['abc', 'ajz']

console.log(micromatch(files, '[a-c]*', { bash: false }));
```

### options.expandRange

**Type**: `function`

**Default**: `undefined`

Custom function for expanding ranges in brace patterns. The [fill-range](https://github.com/jonschlinkert/fill-range) library is ideal for this purpose, or you can use custom code to do whatever you need.

**Example**

The following example shows how to create a glob that matches a numeric folder name between `01` and `25`, with leading zeros.

```js
const fill = require('fill-range');
const regex = micromatch.makeRe('foo/{01..25}/bar', {
  expandRange(a, b) {
    return `(${fill(a, b, { toRegex: true })})`;
  }
});

console.log(regex)
//=> /^(?:foo\/((?:0[1-9]|1[0-9]|2[0-5]))\/bar)$/

console.log(regex.test('foo/00/bar')) // false
console.log(regex.test('foo/01/bar')) // true
console.log(regex.test('foo/10/bar')) // true
console.log(regex.test('foo/22/bar')) // true
console.log(regex.test('foo/25/bar')) // true
console.log(regex.test('foo/26/bar')) // false
```

### options.format

**Type**: `function`

**Default**: `undefined`

Custom function for formatting strings before they're matched.

**Example**

```js
// strip leading './' from strings
const format = str => str.replace(/^\.\//, '');
const isMatch = picomatch('foo/*.js', { format });
console.log(isMatch('./foo/bar.js')) //=> true
```

### options.ignore

String or array of glob patterns to match files to ignore.

**Type**: `String|Array`

**Default**: `undefined`

```js
const isMatch = micromatch.matcher('*', { ignore: 'f*' });
console.log(isMatch('foo')) //=> false
console.log(isMatch('bar')) //=> true
console.log(isMatch('baz')) //=> true
```

### options.matchBase

Alias for [options.basename](#options-basename).

### options.noextglob

Disable extglob support, so that [extglobs](#extglobs) are regarded as literal characters.

**Type**: `Boolean`

**Default**: `undefined`

**Examples**

```js
console.log(micromatch(['a/z', 'a/b', 'a/!(z)'], 'a/!(z)'));
//=> ['a/b', 'a/!(z)']

console.log(micromatch(['a/z', 'a/b', 'a/!(z)'], 'a/!(z)', { noextglob: true }));
//=> ['a/!(z)'] (matches only as literal characters)
```

### options.nonegate

Disallow negation (`!`) patterns, and treat leading `!` as a literal character to match.

**Type**: `Boolean`

**Default**: `undefined`

### options.noglobstar

Disable matching with globstars (`**`).

**Type**: `Boolean`

**Default**: `undefined`

```js
micromatch(['a/b', 'a/b/c', 'a/b/c/d'], 'a/**');
//=> ['a/b', 'a/b/c', 'a/b/c/d']

micromatch(['a/b', 'a/b/c', 'a/b/c/d'], 'a/**', {noglobstar: true});
//=> ['a/b']
```

### options.nonull

Alias for [options.nullglob](#options-nullglob).

### options.nullglob

If `true`, when no matches are found the actual (arrayified) glob pattern is returned instead of an empty array. Same behavior as [minimatch](https://github.com/isaacs/minimatch) option `nonull`.

**Type**: `Boolean`

**Default**: `undefined`

### options.onIgnore

```js
const onIgnore = ({ glob, regex, input, output }) => {
  console.log({ glob, regex, input, output });
  // { glob: '*', regex: /^(?:(?!\.)(?=.)[^\/]*?\/?)$/, input: 'foo', output: 'foo' }
};

const isMatch = micromatch.matcher('*', { onIgnore, ignore: 'f*' });
isMatch('foo');
isMatch('bar');
isMatch('baz');
```

### options.onMatch

```js
const onMatch = ({ glob, regex, input, output }) => {
  console.log({ input, output });
  // { input: 'some\\path', output: 'some/path' }
  // { input: 'some\\path', output: 'some/path' }
  // { input: 'some\\path', output: 'some/path' }
};

const isMatch = micromatch.matcher('**', { onMatch, posixSlashes: true });
isMatch('some\\path');
isMatch('some\\path');
isMatch('some\\path');
```

### options.onResult

```js
const onResult = ({ glob, regex, input, output }) => {
  console.log({ glob, regex, input, output });
};

const isMatch = micromatch('*', { onResult, ignore: 'f*' });
isMatch('foo');
isMatch('bar');
isMatch('baz');
```

### options.posixSlashes

Convert path separators on returned files to posix/unix-style forward slashes. Aliased as `unixify` for backwards compatibility.

**Type**: `Boolean`

**Default**: `true` on windows, `false` everywhere else.

**Example**

```js
console.log(micromatch.match(['a\\b\\c'], 'a/**'));
//=> ['a/b/c']

console.log(micromatch.match(['a\\b\\c'], { posixSlashes: false }));
//=> ['a\\b\\c']
```

### options.unescape

Remove backslashes from escaped glob characters before creating the regular expression to perform matches.

**Type**: `Boolean`

**Default**: `undefined`

**Example**

In this example we want to match a literal `*`:

```js
console.log(micromatch.match(['abc', 'a\\*c'], 'a\\*c'));
//=> ['a\\*c']

console.log(micromatch.match(['abc', 'a\\*c'], 'a\\*c', { unescape: true }));
//=> ['a*c']
```

<br>
<br>

## Extended globbing

Micromatch supports the following extended globbing features.

### Extglobs

Extended globbing, as described by the bash man page:

| **pattern** | **regex equivalent** | **description** |
| --- | --- | --- |
| `?(pattern)` | `(pattern)?` | Matches zero or one occurrence of the given patterns |
| `*(pattern)` | `(pattern)*` | Matches zero or more occurrences of the given patterns |
| `+(pattern)` | `(pattern)+` | Matches one or more occurrences of the given patterns |
| `@(pattern)` | `(pattern)` <sup>*</sup> | Matches one of the given patterns |
| `!(pattern)` | N/A (equivalent regex is much more complicated) | Matches anything except one of the given patterns |

<sup><strong>*</strong></sup> Note that `@` isn't a regex character.

### Braces

Brace patterns can be used to match specific ranges or sets of characters.

**Example**

The pattern `{f,b}*/{1..3}/{b,q}*` would match any of following strings:

```
foo/1/bar
foo/2/bar
foo/3/bar
baz/1/qux
baz/2/qux
baz/3/qux
```

Visit [braces](https://github.com/micromatch/braces) to see the full range of features and options related to brace expansion, or to create brace matching or expansion related issues.

### Regex character classes

Given the list: `['a.js', 'b.js', 'c.js', 'd.js', 'E.js']`:

* `[ac].js`: matches both `a` and `c`, returning `['a.js', 'c.js']`
* `[b-d].js`: matches from `b` to `d`, returning `['b.js', 'c.js', 'd.js']`
* `a/[A-Z].js`: matches and uppercase letter, returning `['a/E.md']`

Learn about [regex character classes](http://www.regular-expressions.info/charclass.html).

### Regex groups

Given `['a.js', 'b.js', 'c.js', 'd.js', 'E.js']`:

* `(a|c).js`: would match either `a` or `c`, returning `['a.js', 'c.js']`
* `(b|d).js`: would match either `b` or `d`, returning `['b.js', 'd.js']`
* `(b|[A-Z]).js`: would match either `b` or an uppercase letter, returning `['b.js', 'E.js']`

As with regex, parens can be nested, so patterns like `((a|b)|c)/b` will work. Although brace expansion might be friendlier to use, depending on preference.

### POSIX bracket expressions

POSIX brackets are intended to be more user-friendly than regex character classes. This of course is in the eye of the beholder.

**Example**

```js
console.log(micromatch.isMatch('a1', '[[:alpha:][:digit:]]')) //=> true
console.log(micromatch.isMatch('a1', '[[:alpha:][:alpha:]]')) //=> false
```

***

## Notes

### Bash 4.3 parity

Whenever possible matching behavior is based on behavior Bash 4.3, which is mostly consistent with minimatch.

However, it's suprising how many edge cases and rabbit holes there are with glob matching, and since there is no real glob specification, and micromatch is more accurate than both Bash and minimatch, there are cases where best-guesses were made for behavior. In a few cases where Bash had no answers, we used wildmatch (used by git) as a fallback.

### Backslashes

There is an important, notable difference between minimatch and micromatch _in regards to how backslashes are handled_ in glob patterns.

* Micromatch exclusively and explicitly reserves backslashes for escaping characters in a glob pattern, even on windows, which is consistent with bash behavior. _More importantly, unescaping globs can result in unsafe regular expressions_.
* Minimatch converts all backslashes to forward slashes, which means you can't use backslashes to escape any characters in your glob patterns.

We made this decision for micromatch for a couple of reasons:

* Consistency with bash conventions.
* Glob patterns are not filepaths. They are a type of [regular language](https://en.wikipedia.org/wiki/Regular_language) that is converted to a JavaScript regular expression. Thus, when forward slashes are defined in a glob pattern, the resulting regular expression will match windows or POSIX path separators just fine.

**A note about joining paths to globs**

Note that when you pass something like `path.join('foo', '*')` to micromatch, you are creating a filepath and expecting it to still work as a glob pattern. This causes problems on windows, since the `path.sep` is `\\`.

In other words, since `\\` is reserved as an escape character in globs, on windows `path.join('foo', '*')` would result in `foo\\*`, which tells micromatch to match `*` as a literal character. This is the same behavior as bash.

To solve this, you might be inspired to do something like `'foo\\*'.replace(/\\/g, '/')`, but this causes another, potentially much more serious, problem.

## Benchmarks

### Running benchmarks

Install dependencies for running benchmarks:

```sh
$ cd bench && npm install
```

Run the benchmarks:

```sh
$ npm run bench
```

### Latest results

As of August 23, 2024 (longer bars are better):

```sh
# .makeRe star
  micromatch x 2,232,802 ops/sec ±2.34% (89 runs sampled))
  minimatch x 781,018 ops/sec ±6.74% (92 runs sampled))

# .makeRe star; dot=true
  micromatch x 1,863,453 ops/sec ±0.74% (93 runs sampled)
  minimatch x 723,105 ops/sec ±0.75% (93 runs sampled)

# .makeRe globstar
  micromatch x 1,624,179 ops/sec ±2.22% (91 runs sampled)
  minimatch x 1,117,230 ops/sec ±2.78% (86 runs sampled))

# .makeRe globstars
  micromatch x 1,658,642 ops/sec ±0.86% (92 runs sampled)
  minimatch x 741,224 ops/sec ±1.24% (89 runs sampled))

# .makeRe with leading star
  micromatch x 1,525,014 ops/sec ±1.63% (90 runs sampled)
  minimatch x 561,074 ops/sec ±3.07% (89 runs sampled)

# .makeRe - braces
  micromatch x 172,478 ops/sec ±2.37% (78 runs sampled)
  minimatch x 96,087 ops/sec ±2.34% (88 runs sampled)))

# .makeRe braces - range (expanded)
  micromatch x 26,973 ops/sec ±0.84% (89 runs sampled)
  minimatch x 3,023 ops/sec ±0.99% (90 runs sampled))

# .makeRe braces - range (compiled)
  micromatch x 152,892 ops/sec ±1.67% (83 runs sampled)
  minimatch x 992 ops/sec ±3.50% (89 runs sampled)d))

# .makeRe braces - nested ranges (expanded)
  micromatch x 15,816 ops/sec ±13.05% (80 runs sampled)
  minimatch x 2,953 ops/sec ±1.64% (91 runs sampled)

# .makeRe braces - nested ranges (compiled)
  micromatch x 110,881 ops/sec ±1.85% (82 runs sampled)
  minimatch x 1,008 ops/sec ±1.51% (91 runs sampled)

# .makeRe braces - set (compiled)
  micromatch x 134,930 ops/sec ±3.54% (63 runs sampled))
  minimatch x 43,242 ops/sec ±0.60% (93 runs sampled)

# .makeRe braces - nested sets (compiled)
  micromatch x 94,455 ops/sec ±1.74% (69 runs sampled))
  minimatch x 27,720 ops/sec ±1.84% (93 runs sampled))
```

## Contributing

All contributions are welcome! Please read [the contributing guide](.github/contributing.md) to get started.

**Bug reports**

Please create an issue if you encounter a bug or matching behavior that doesn't seem correct. If you find a matching-related issue, please:

* [research existing issues first](../../issues) (open and closed)
* visit the [GNU Bash documentation](https://www.gnu.org/software/bash/manual/) to see how Bash deals with the pattern
* visit the [minimatch](https://github.com/isaacs/minimatch) documentation to cross-check expected behavior in node.js
* if all else fails, since there is no real specification for globs we will probably need to discuss expected behavior and decide how to resolve it. which means any detail you can provide to help with this discussion would be greatly appreciated.

**Platform issues**

It's important to us that micromatch work consistently on all platforms. If you encounter any platform-specific matching or path related issues, please let us know (pull requests are also greatly appreciated).

## About

<details>
<summary><strong>Contributing</strong></summary>

Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).

Please read the [contributing guide](.github/contributing.md) for advice on opening issues, pull requests, and coding standards.

</details>

<details>
<summary><strong>Running Tests</strong></summary>

Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

```sh
$ npm install && npm test
```

</details>

<details>
<summary><strong>Building docs</strong></summary>

_(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_

To generate the readme, run the following command:

```sh
$ npm install -g verbose/verb#dev verb-generate-readme && verb
```

</details>

### Related projects

You might also be interested in these projects:

* [braces](https://www.npmjs.com/package/braces): Bash-like brace expansion, implemented in JavaScript. Safer than other brace expansion libs, with complete support… [more](https://github.com/micromatch/braces) | [homepage](https://github.com/micromatch/braces "Bash-like brace expansion, implemented in JavaScript. Safer than other brace expansion libs, with complete support for the Bash 4.3 braces specification, without sacrificing speed.")
* [expand-brackets](https://www.npmjs.com/package/expand-brackets): Expand POSIX bracket expressions (character classes) in glob patterns. | [homepage](https://github.com/micromatch/expand-brackets "Expand POSIX bracket expressions (character classes) in glob patterns.")
* [extglob](https://www.npmjs.com/package/extglob): Extended glob support for JavaScript. Adds (almost) the expressive power of regular expressions to glob… [more](https://github.com/micromatch/extglob) | [homepage](https://github.com/micromatch/extglob "Extended glob support for JavaScript. Adds (almost) the expressive power of regular expressions to glob patterns.")
* [fill-range](https://www.npmjs.com/package/fill-range): Fill in a range of numbers or letters, optionally passing an increment or `step` to… [more](https://github.com/jonschlinkert/fill-range) | [homepage](https://github.com/jonschlinkert/fill-range "Fill in a range of numbers or letters, optionally passing an increment or `step` to use, or create a regex-compatible range with `options.toRegex`")
* [nanomatch](https://www.npmjs.com/package/nanomatch): Fast, minimal glob matcher for node.js. Similar to micromatch, minimatch and multimatch, but complete Bash… [more](https://github.com/micromatch/nanomatch) | [homepage](https://github.com/micromatch/nanomatch "Fast, minimal glob matcher for node.js. Similar to micromatch, minimatch and multimatch, but complete Bash 4.3 wildcard support only (no support for exglobs, posix brackets or braces)")

### Contributors

| **Commits** | **Contributor** |  
| --- | --- |  
| 523 | [jonschlinkert](https://github.com/jonschlinkert) |  
| 12  | [es128](https://github.com/es128) |  
| 9   | [danez](https://github.com/danez) |  
| 8   | [doowb](https://github.com/doowb) |  
| 6   | [paulmillr](https://github.com/paulmillr) |  
| 5   | [mrmlnc](https://github.com/mrmlnc) |  
| 3   | [DrPizza](https://github.com/DrPizza) |  
| 2   | [Tvrqvoise](https://github.com/Tvrqvoise) |  
| 2   | [antonyk](https://github.com/antonyk) |  
| 2   | [MartinKolarik](https://github.com/MartinKolarik) |  
| 2   | [Glazy](https://github.com/Glazy) |  
| 2   | [mceIdo](https://github.com/mceIdo) |  
| 2   | [TrySound](https://github.com/TrySound) |  
| 1   | [yvele](https://github.com/yvele) |  
| 1   | [wtgtybhertgeghgtwtg](https://github.com/wtgtybhertgeghgtwtg) |  
| 1   | [simlu](https://github.com/simlu) |  
| 1   | [curbengh](https://github.com/curbengh) |  
| 1   | [fidian](https://github.com/fidian) |  
| 1   | [tomByrer](https://github.com/tomByrer) |  
| 1   | [ZoomerTedJackson](https://github.com/ZoomerTedJackson) |  
| 1   | [styfle](https://github.com/styfle) |  
| 1   | [sebdeckers](https://github.com/sebdeckers) |  
| 1   | [muescha](https://github.com/muescha) |  
| 1   | [juszczykjakub](https://github.com/juszczykjakub) |  
| 1   | [joyceerhl](https://github.com/joyceerhl) |  
| 1   | [donatj](https://github.com/donatj) |  
| 1   | [frangio](https://github.com/frangio) |  
| 1   | [UltCombo](https://github.com/UltCombo) |  
| 1   | [DianeLooney](https://github.com/DianeLooney) |  
| 1   | [devongovett](https://github.com/devongovett) |  
| 1   | [Cslove](https://github.com/Cslove) |  
| 1   | [amilajack](https://github.com/amilajack) |  

### Author

**Jon Schlinkert**

* [GitHub Profile](https://github.com/jonschlinkert)
* [Twitter Profile](https://twitter.com/jonschlinkert)
* [LinkedIn Profile](https://linkedin.com/in/jonschlinkert)

### License

Copyright © 2024, [Jon Schlinkert](https://github.com/jonschlinkert).
Released under the [MIT License](LICENSE).

***

_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.8.0, on August 23, 2024._

---

# Changelog

## v1.6.0 (24/11/2017)
*No changelog for this release.*

---

## v2.0.4 (24/11/2017)
- [**closed**] Switch to mime-score module for resolving extension contention issues. [#182](https://github.com/broofa/node-mime/issues/182)
- [**closed**] Update mime-db to 1.31.0 in v1.x branch [#181](https://github.com/broofa/node-mime/issues/181)

---

## v1.5.0 (22/11/2017)
- [**closed**] need ES5 version ready in npm package [#179](https://github.com/broofa/node-mime/issues/179)
- [**closed**] mime-db no trace of iWork - pages / numbers / etc. [#178](https://github.com/broofa/node-mime/issues/178)
- [**closed**] How it works in brownser ? [#176](https://github.com/broofa/node-mime/issues/176)
- [**closed**] Missing `./Mime` [#175](https://github.com/broofa/node-mime/issues/175)
- [**closed**] Vulnerable Regular Expression [#167](https://github.com/broofa/node-mime/issues/167)

---

## v2.0.3 (25/09/2017)
*No changelog for this release.*

---

## v1.4.1 (25/09/2017)
- [**closed**] Issue when bundling with webpack [#172](https://github.com/broofa/node-mime/issues/172)

---

## v2.0.2 (15/09/2017)
- [**V2**] fs.readFileSync is not a function [#165](https://github.com/broofa/node-mime/issues/165)
- [**closed**] The extension for video/quicktime should map to .mov, not .qt [#164](https://github.com/broofa/node-mime/issues/164)
- [**V2**] [v2 Feedback request] Mime class API [#163](https://github.com/broofa/node-mime/issues/163)
- [**V2**] [v2 Feedback request] Resolving conflicts over extensions [#162](https://github.com/broofa/node-mime/issues/162)
- [**V2**] Allow callers to load module with official, full, or no defined types.  [#161](https://github.com/broofa/node-mime/issues/161)
- [**V2**] Use "facets" to resolve extension conflicts [#160](https://github.com/broofa/node-mime/issues/160)
- [**V2**] Remove fs and path dependencies [#152](https://github.com/broofa/node-mime/issues/152)
- [**V2**] Default content-type should not be application/octet-stream [#139](https://github.com/broofa/node-mime/issues/139)
- [**V2**] reset mime-types [#124](https://github.com/broofa/node-mime/issues/124)
- [**V2**] Extensionless paths should return null or false [#113](https://github.com/broofa/node-mime/issues/113)

---

## v2.0.1 (14/09/2017)
- [**closed**] Changelog for v2.0 does not mention breaking changes [#171](https://github.com/broofa/node-mime/issues/171)
- [**closed**] MIME breaking with 'class' declaration as it is without 'use strict mode' [#170](https://github.com/broofa/node-mime/issues/170)

---

## v2.0.0 (12/09/2017)
- [**closed**] woff and woff2 [#168](https://github.com/broofa/node-mime/issues/168)

---

## v1.4.0 (28/08/2017)
- [**closed**] support for ac3 voc files [#159](https://github.com/broofa/node-mime/issues/159)
- [**closed**] Help understanding change from application/xml to text/xml [#158](https://github.com/broofa/node-mime/issues/158)
- [**closed**] no longer able to override mimetype [#157](https://github.com/broofa/node-mime/issues/157)
- [**closed**] application/vnd.adobe.photoshop [#147](https://github.com/broofa/node-mime/issues/147)
- [**closed**] Directories should appear as something other than application/octet-stream [#135](https://github.com/broofa/node-mime/issues/135)
- [**closed**] requested features [#131](https://github.com/broofa/node-mime/issues/131)
- [**closed**] Make types.json loading optional? [#129](https://github.com/broofa/node-mime/issues/129)
- [**closed**] Cannot find module './types.json' [#120](https://github.com/broofa/node-mime/issues/120)
- [**V2**] .wav files show up as "audio/x-wav" instead of "audio/x-wave" [#118](https://github.com/broofa/node-mime/issues/118)
- [**closed**] Don't be a pain in the ass for node community [#108](https://github.com/broofa/node-mime/issues/108)
- [**closed**] don't make default_type global [#78](https://github.com/broofa/node-mime/issues/78)
- [**closed**] mime.extension() fails if the content-type is parameterized [#74](https://github.com/broofa/node-mime/issues/74)

---

## v1.3.6 (11/05/2017)
- [**closed**] .md should be text/markdown as of March 2016 [#154](https://github.com/broofa/node-mime/issues/154)
- [**closed**] Error while installing mime [#153](https://github.com/broofa/node-mime/issues/153)
- [**closed**] application/manifest+json [#149](https://github.com/broofa/node-mime/issues/149)
- [**closed**] Dynamic adaptive streaming over HTTP (DASH) file extension typo [#141](https://github.com/broofa/node-mime/issues/141)
- [**closed**] charsets image/png undefined [#140](https://github.com/broofa/node-mime/issues/140)
- [**closed**] Mime-db dependency out of date [#130](https://github.com/broofa/node-mime/issues/130)
- [**closed**] how to support plist？ [#126](https://github.com/broofa/node-mime/issues/126)
- [**closed**] how does .types file format look like? [#123](https://github.com/broofa/node-mime/issues/123)
- [**closed**] Feature: support for expanding MIME patterns [#121](https://github.com/broofa/node-mime/issues/121)
- [**closed**] DEBUG_MIME doesn't work [#117](https://github.com/broofa/node-mime/issues/117)

---

## v1.3.4 (06/02/2015)
*No changelog for this release.*

---

## v1.3.3 (06/02/2015)
*No changelog for this release.*

---

## v1.3.1 (05/02/2015)
- [**closed**] Consider adding support for Handlebars .hbs file ending [#111](https://github.com/broofa/node-mime/issues/111)
- [**closed**] Consider adding support for hjson. [#110](https://github.com/broofa/node-mime/issues/110)
- [**closed**] Add mime type for Opus audio files [#94](https://github.com/broofa/node-mime/issues/94)
- [**closed**] Consider making the `Requesting New Types` information more visible [#77](https://github.com/broofa/node-mime/issues/77)

---

## v1.3.0 (05/02/2015)
- [**closed**] Add common name? [#114](https://github.com/broofa/node-mime/issues/114)
- [**closed**] application/x-yaml [#104](https://github.com/broofa/node-mime/issues/104)
- [**closed**] Add mime type for WOFF file format 2.0 [#102](https://github.com/broofa/node-mime/issues/102)
- [**closed**] application/x-msi for .msi [#99](https://github.com/broofa/node-mime/issues/99)
- [**closed**] Add mimetype for gettext translation files [#98](https://github.com/broofa/node-mime/issues/98)
- [**closed**] collaborators [#88](https://github.com/broofa/node-mime/issues/88)
- [**closed**] getting errot in installation of mime module...any1 can help? [#87](https://github.com/broofa/node-mime/issues/87)
- [**closed**] should application/json's charset be utf8? [#86](https://github.com/broofa/node-mime/issues/86)
- [**closed**] Add "license" and "licenses" to package.json [#81](https://github.com/broofa/node-mime/issues/81)
- [**closed**] lookup with extension-less file on Windows returns wrong type [#68](https://github.com/broofa/node-mime/issues/68)

---

## v1.2.11 (15/08/2013)
- [**closed**] Update mime.types [#65](https://github.com/broofa/node-mime/issues/65)
- [**closed**] Publish a new version [#63](https://github.com/broofa/node-mime/issues/63)
- [**closed**] README should state upfront that "application/octet-stream" is default for unknown extension [#55](https://github.com/broofa/node-mime/issues/55)
- [**closed**] Suggested improvement to the charset API [#52](https://github.com/broofa/node-mime/issues/52)

---

## v1.2.10 (25/07/2013)
- [**closed**] Mime type for woff files should be application/font-woff and not application/x-font-woff [#62](https://github.com/broofa/node-mime/issues/62)
- [**closed**] node.types in conflict with mime.types [#51](https://github.com/broofa/node-mime/issues/51)

---

## v1.2.9 (17/01/2013)
- [**closed**] Please update "mime" NPM [#49](https://github.com/broofa/node-mime/issues/49)
- [**closed**] Please add semicolon [#46](https://github.com/broofa/node-mime/issues/46)
- [**closed**] parse full mime types [#43](https://github.com/broofa/node-mime/issues/43)

---

## v1.2.8 (10/01/2013)
- [**closed**] /js directory mime is application/javascript. Is it correct? [#47](https://github.com/broofa/node-mime/issues/47)
- [**closed**] Add mime types for lua code. [#45](https://github.com/broofa/node-mime/issues/45)

---

## v1.2.7 (19/10/2012)
- [**closed**] cannot install 1.2.7 via npm [#41](https://github.com/broofa/node-mime/issues/41)
- [**closed**] Transfer ownership to @broofa [#36](https://github.com/broofa/node-mime/issues/36)
- [**closed**] it's wrong to set charset to UTF-8 for text [#30](https://github.com/broofa/node-mime/issues/30)
- [**closed**] Allow multiple instances of MIME types container [#27](https://github.com/broofa/node-mime/issues/27)

---

## v1.2.5 (16/02/2012)
- [**closed**] When looking up a types, check hasOwnProperty [#23](https://github.com/broofa/node-mime/issues/23)
- [**closed**] Bump version to 1.2.2 [#18](https://github.com/broofa/node-mime/issues/18)
- [**closed**] No license [#16](https://github.com/broofa/node-mime/issues/16)
- [**closed**] Some types missing that are used by html5/css3 [#13](https://github.com/broofa/node-mime/issues/13)
- [**closed**] npm install fails for 1.2.1 [#12](https://github.com/broofa/node-mime/issues/12)
- [**closed**] image/pjpeg + image/x-png [#10](https://github.com/broofa/node-mime/issues/10)
- [**closed**] symlink [#8](https://github.com/broofa/node-mime/issues/8)
- [**closed**] gzip [#2](https://github.com/broofa/node-mime/issues/2)
- [**closed**] ALL CAPS filenames return incorrect mime type [#1](https://github.com/broofa/node-mime/issues/1)


---

# mime

Comprehensive MIME type mapping API based on mime-db module.

## Install

Install with [npm](http://github.com/isaacs/npm):

    npm install mime

## Contributing / Testing

    npm run test

## Command Line

    mime [path_string]

E.g.

    > mime scripts/jquery.js
    application/javascript

## API - Queries

### mime.lookup(path)
Get the mime type associated with a file, if no mime type is found `application/octet-stream` is returned. Performs a case-insensitive lookup using the extension in `path` (the substring after the last '/' or '.').  E.g.

```js
var mime = require('mime');

mime.lookup('/path/to/file.txt');         // => 'text/plain'
mime.lookup('file.txt');                  // => 'text/plain'
mime.lookup('.TXT');                      // => 'text/plain'
mime.lookup('htm');                       // => 'text/html'
```

### mime.default_type
Sets the mime type returned when `mime.lookup` fails to find the extension searched for. (Default is `application/octet-stream`.)

### mime.extension(type)
Get the default extension for `type`

```js
mime.extension('text/html');                 // => 'html'
mime.extension('application/octet-stream');  // => 'bin'
```

### mime.charsets.lookup()

Map mime-type to charset

```js
mime.charsets.lookup('text/plain');        // => 'UTF-8'
```

(The logic for charset lookups is pretty rudimentary.  Feel free to suggest improvements.)

## API - Defining Custom Types

Custom type mappings can be added on a per-project basis via the following APIs.

### mime.define()

Add custom mime/extension mappings

```js
mime.define({
    'text/x-some-format': ['x-sf', 'x-sft', 'x-sfml'],
    'application/x-my-type': ['x-mt', 'x-mtt'],
    // etc ...
});

mime.lookup('x-sft');                 // => 'text/x-some-format'
```

The first entry in the extensions array is returned by `mime.extension()`. E.g.

```js
mime.extension('text/x-some-format'); // => 'x-sf'
```

### mime.load(filepath)

Load mappings from an Apache ".types" format file

```js
mime.load('./my_project.types');
```
The .types file format is simple -  See the `types` dir for examples.


---

1.33.0 / 2018-02-15
===================

  * Add extensions from IANA for `message/*` types
  * Add new upstream MIME types
  * Fix some incorrect OOXML types
  * Remove `application/font-woff2`

1.32.0 / 2017-11-29
===================

  * Add new upstream MIME types
  * Update `text/hjson` to registered `application/hjson`
  * Add `text/shex` with extension `.shex`

1.31.0 / 2017-10-25
===================

  * Add `application/raml+yaml` with extension `.raml`
  * Add `application/wasm` with extension `.wasm`
  * Add new `font` type from IANA
  * Add new upstream font extensions
  * Add new upstream MIME types
  * Add extensions for JPEG-2000 images

1.30.0 / 2017-08-27
===================

  * Add `application/vnd.ms-outlook`
  * Add `application/x-arj`
  * Add extension `.mjs` to `application/javascript`
  * Add glTF types and extensions
  * Add new upstream MIME types
  * Add `text/x-org`
  * Add VirtualBox MIME types
  * Fix `source` records for `video/*` types that are IANA
  * Update `font/opentype` to registered `font/otf`

1.29.0 / 2017-07-10
===================

  * Add `application/fido.trusted-apps+json`
  * Add extension `.wadl` to `application/vnd.sun.wadl+xml`
  * Add new upstream MIME types
  * Add `UTF-8` as default charset for `text/css`

1.28.0 / 2017-05-14
===================

  * Add new upstream MIME types
  * Add extension `.gz` to `application/gzip`
  * Update extensions `.md` and `.markdown` to be `text/markdown`

1.27.0 / 2017-03-16
===================

  * Add new upstream MIME types
  * Add `image/apng` with extension `.apng`

1.26.0 / 2017-01-14
===================

  * Add new upstream MIME types
  * Add extension `.geojson` to `application/geo+json`

1.25.0 / 2016-11-11
===================

  * Add new upstream MIME types

1.24.0 / 2016-09-18
===================

  * Add `audio/mp3`
  * Add new upstream MIME types

1.23.0 / 2016-05-01
===================

  * Add new upstream MIME types
  * Add extension `.3gpp` to `audio/3gpp`

1.22.0 / 2016-02-15
===================

  * Add `text/slim`
  * Add extension `.rng` to `application/xml`
  * Add new upstream MIME types
  * Fix extension of `application/dash+xml` to be `.mpd`
  * Update primary extension to `.m4a` for `audio/mp4`

1.21.0 / 2016-01-06
===================

  * Add Google document types
  * Add new upstream MIME types

1.20.0 / 2015-11-10
===================

  * Add `text/x-suse-ymp`
  * Add new upstream MIME types

1.19.0 / 2015-09-17
===================

  * Add `application/vnd.apple.pkpass`
  * Add new upstream MIME types

1.18.0 / 2015-09-03
===================

  * Add new upstream MIME types

1.17.0 / 2015-08-13
===================

  * Add `application/x-msdos-program`
  * Add `audio/g711-0`
  * Add `image/vnd.mozilla.apng`
  * Add extension `.exe` to `application/x-msdos-program`

1.16.0 / 2015-07-29
===================

  * Add `application/vnd.uri-map`

1.15.0 / 2015-07-13
===================

  * Add `application/x-httpd-php`

1.14.0 / 2015-06-25
===================

  * Add `application/scim+json`
  * Add `application/vnd.3gpp.ussd+xml`
  * Add `application/vnd.biopax.rdf+xml`
  * Add `text/x-processing`

1.13.0 / 2015-06-07
===================

  * Add nginx as a source
  * Add `application/x-cocoa`
  * Add `application/x-java-archive-diff`
  * Add `application/x-makeself`
  * Add `application/x-perl`
  * Add `application/x-pilot`
  * Add `application/x-redhat-package-manager`
  * Add `application/x-sea`
  * Add `audio/x-m4a`
  * Add `audio/x-realaudio`
  * Add `image/x-jng`
  * Add `text/mathml`

1.12.0 / 2015-06-05
===================

  * Add `application/bdoc`
  * Add `application/vnd.hyperdrive+json`
  * Add `application/x-bdoc`
  * Add extension `.rtf` to `text/rtf`

1.11.0 / 2015-05-31
===================

  * Add `audio/wav`
  * Add `audio/wave`
  * Add extension `.litcoffee` to `text/coffeescript`
  * Add extension `.sfd-hdstx` to `application/vnd.hydrostatix.sof-data`
  * Add extension `.n-gage` to `application/vnd.nokia.n-gage.symbian.install`

1.10.0 / 2015-05-19
===================

  * Add `application/vnd.balsamiq.bmpr`
  * Add `application/vnd.microsoft.portable-executable`
  * Add `application/x-ns-proxy-autoconfig`

1.9.1 / 2015-04-19
==================

  * Remove `.json` extension from `application/manifest+json`
    - This is causing bugs downstream

1.9.0 / 2015-04-19
==================

  * Add `application/manifest+json`
  * Add `application/vnd.micro+json`
  * Add `image/vnd.zbrush.pcx`
  * Add `image/x-ms-bmp`

1.8.0 / 2015-03-13
==================

  * Add `application/vnd.citationstyles.style+xml`
  * Add `application/vnd.fastcopy-disk-image`
  * Add `application/vnd.gov.sk.xmldatacontainer+xml`
  * Add extension `.jsonld` to `application/ld+json`

1.7.0 / 2015-02-08
==================

  * Add `application/vnd.gerber`
  * Add `application/vnd.msa-disk-image`

1.6.1 / 2015-02-05
==================

  * Community extensions ownership transferred from `node-mime`

1.6.0 / 2015-01-29
==================

  * Add `application/jose`
  * Add `application/jose+json`
  * Add `application/json-seq`
  * Add `application/jwk+json`
  * Add `application/jwk-set+json`
  * Add `application/jwt`
  * Add `application/rdap+json`
  * Add `application/vnd.gov.sk.e-form+xml`
  * Add `application/vnd.ims.imsccv1p3`

1.5.0 / 2014-12-30
==================

  * Add `application/vnd.oracle.resource+json`
  * Fix various invalid MIME type entries
    - `application/mbox+xml`
    - `application/oscp-response`
    - `application/vwg-multiplexed`
    - `audio/g721`

1.4.0 / 2014-12-21
==================

  * Add `application/vnd.ims.imsccv1p2`
  * Fix various invalid MIME type entries
    - `application/vnd-acucobol`
    - `application/vnd-curl`
    - `application/vnd-dart`
    - `application/vnd-dxr`
    - `application/vnd-fdf`
    - `application/vnd-mif`
    - `application/vnd-sema`
    - `application/vnd-wap-wmlc`
    - `application/vnd.adobe.flash-movie`
    - `application/vnd.dece-zip`
    - `application/vnd.dvb_service`
    - `application/vnd.micrografx-igx`
    - `application/vnd.sealed-doc`
    - `application/vnd.sealed-eml`
    - `application/vnd.sealed-mht`
    - `application/vnd.sealed-ppt`
    - `application/vnd.sealed-tiff`
    - `application/vnd.sealed-xls`
    - `application/vnd.sealedmedia.softseal-html`
    - `application/vnd.sealedmedia.softseal-pdf`
    - `application/vnd.wap-slc`
    - `application/vnd.wap-wbxml`
    - `audio/vnd.sealedmedia.softseal-mpeg`
    - `image/vnd-djvu`
    - `image/vnd-svf`
    - `image/vnd-wap-wbmp`
    - `image/vnd.sealed-png`
    - `image/vnd.sealedmedia.softseal-gif`
    - `image/vnd.sealedmedia.softseal-jpg`
    - `model/vnd-dwf`
    - `model/vnd.parasolid.transmit-binary`
    - `model/vnd.parasolid.transmit-text`
    - `text/vnd-a`
    - `text/vnd-curl`
    - `text/vnd.wap-wml`
  * Remove example template MIME types
    - `application/example`
    - `audio/example`
    - `image/example`
    - `message/example`
    - `model/example`
    - `multipart/example`
    - `text/example`
    - `video/example`

1.3.1 / 2014-12-16
==================

  * Fix missing extensions
    - `application/json5`
    - `text/hjson`

1.3.0 / 2014-12-07
==================

  * Add `application/a2l`
  * Add `application/aml`
  * Add `application/atfx`
  * Add `application/atxml`
  * Add `application/cdfx+xml`
  * Add `application/dii`
  * Add `application/json5`
  * Add `application/lxf`
  * Add `application/mf4`
  * Add `application/vnd.apache.thrift.compact`
  * Add `application/vnd.apache.thrift.json`
  * Add `application/vnd.coffeescript`
  * Add `application/vnd.enphase.envoy`
  * Add `application/vnd.ims.imsccv1p1`
  * Add `text/csv-schema`
  * Add `text/hjson`
  * Add `text/markdown`
  * Add `text/yaml`

1.2.0 / 2014-11-09
==================

  * Add `application/cea`
  * Add `application/dit`
  * Add `application/vnd.gov.sk.e-form+zip`
  * Add `application/vnd.tmd.mediaflex.api+xml`
  * Type `application/epub+zip` is now IANA-registered

1.1.2 / 2014-10-23
==================

  * Rebuild database for `application/x-www-form-urlencoded` change

1.1.1 / 2014-10-20
==================

  * Mark `application/x-www-form-urlencoded` as compressible.

1.1.0 / 2014-09-28
==================

  * Add `application/font-woff2`

1.0.3 / 2014-09-25
==================

  * Fix engine requirement in package

1.0.2 / 2014-09-25
==================

  * Add `application/coap-group+json`
  * Add `application/dcd`
  * Add `application/vnd.apache.thrift.binary`
  * Add `image/vnd.tencent.tap`
  * Mark all JSON-derived types as compressible
  * Update `text/vtt` data

1.0.1 / 2014-08-30
==================

  * Fix extension ordering

1.0.0 / 2014-08-30
==================

  * Add `application/atf`
  * Add `application/merge-patch+json`
  * Add `multipart/x-mixed-replace`
  * Add `source: 'apache'` metadata
  * Add `source: 'iana'` metadata
  * Remove badly-assumed charset data


---

# mime-db

[![NPM Version][npm-version-image]][npm-url]
[![NPM Downloads][npm-downloads-image]][npm-url]
[![Node.js Version][node-image]][node-url]
[![Build Status][travis-image]][travis-url]
[![Coverage Status][coveralls-image]][coveralls-url]

This is a database of all mime types.
It consists of a single, public JSON file and does not include any logic,
allowing it to remain as un-opinionated as possible with an API.
It aggregates data from the following sources:

- http://www.iana.org/assignments/media-types/media-types.xhtml
- http://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/conf/mime.types
- http://hg.nginx.org/nginx/raw-file/default/conf/mime.types

## Installation

```bash
npm install mime-db
```

### Database Download

If you're crazy enough to use this in the browser, you can just grab the
JSON file using [RawGit](https://rawgit.com/). It is recommended to replace
`master` with [a release tag](https://github.com/jshttp/mime-db/tags) as the
JSON format may change in the future.

```
https://cdn.rawgit.com/jshttp/mime-db/master/db.json
```

## Usage

```js
var db = require('mime-db');

// grab data on .js files
var data = db['application/javascript'];
```

## Data Structure

The JSON file is a map lookup for lowercased mime types.
Each mime type has the following properties:

- `.source` - where the mime type is defined.
    If not set, it's probably a custom media type.
    - `apache` - [Apache common media types](http://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/conf/mime.types)
    - `iana` - [IANA-defined media types](http://www.iana.org/assignments/media-types/media-types.xhtml)
    - `nginx` - [nginx media types](http://hg.nginx.org/nginx/raw-file/default/conf/mime.types)
- `.extensions[]` - known extensions associated with this mime type.
- `.compressible` - whether a file of this type can be gzipped.
- `.charset` - the default charset associated with this type, if any.

If unknown, every property could be `undefined`.

## Contributing

To edit the database, only make PRs against `src/custom.json` or
`src/custom-suffix.json`.

The `src/custom.json` file is a JSON object with the MIME type as the keys
and the values being an object with the following keys:

- `compressible` - leave out if you don't know, otherwise `true`/`false` for
  if the data represented by the time is typically compressible.
- `extensions` - include an array of file extensions that are associated with
  the type.
- `notes` - human-readable notes about the type, typically what the type is.
- `sources` - include an array of URLs of where the MIME type and the associated
  extensions are sourced from. This needs to be a [primary source](https://en.wikipedia.org/wiki/Primary_source);
  links to type aggregating sites and Wikipedia are _not acceptible_.

To update the build, run `npm run build`.

## Adding Custom Media Types

The best way to get new media types included in this library is to register
them with the IANA. The community registration procedure is outlined in
[RFC 6838 section 5](http://tools.ietf.org/html/rfc6838#section-5). Types
registered with the IANA are automatically pulled into this library.

[npm-version-image]: https://img.shields.io/npm/v/mime-db.svg
[npm-downloads-image]: https://img.shields.io/npm/dm/mime-db.svg
[npm-url]: https://npmjs.org/package/mime-db
[travis-image]: https://img.shields.io/travis/jshttp/mime-db/master.svg
[travis-url]: https://travis-ci.org/jshttp/mime-db
[coveralls-image]: https://img.shields.io/coveralls/jshttp/mime-db/master.svg
[coveralls-url]: https://coveralls.io/r/jshttp/mime-db?branch=master
[node-image]: https://img.shields.io/node/v/mime-db.svg
[node-url]: https://nodejs.org/en/download/


---

2.1.18 / 2018-02-16
===================

  * deps: mime-db@~1.33.0
    - Add `application/raml+yaml` with extension `.raml`
    - Add `application/wasm` with extension `.wasm`
    - Add `text/shex` with extension `.shex`
    - Add extensions for JPEG-2000 images
    - Add extensions from IANA for `message/*` types
    - Add new upstream MIME types
    - Update font MIME types
    - Update `text/hjson` to registered `application/hjson`

2.1.17 / 2017-09-01
===================

  * deps: mime-db@~1.30.0
    - Add `application/vnd.ms-outlook`
    - Add `application/x-arj`
    - Add extension `.mjs` to `application/javascript`
    - Add glTF types and extensions
    - Add new upstream MIME types
    - Add `text/x-org`
    - Add VirtualBox MIME types
    - Fix `source` records for `video/*` types that are IANA
    - Update `font/opentype` to registered `font/otf`

2.1.16 / 2017-07-24
===================

  * deps: mime-db@~1.29.0
    - Add `application/fido.trusted-apps+json`
    - Add extension `.wadl` to `application/vnd.sun.wadl+xml`
    - Add extension `.gz` to `application/gzip`
    - Add new upstream MIME types
    - Update extensions `.md` and `.markdown` to be `text/markdown`

2.1.15 / 2017-03-23
===================

  * deps: mime-db@~1.27.0
    - Add new mime types
    - Add `image/apng`

2.1.14 / 2017-01-14
===================

  * deps: mime-db@~1.26.0
    - Add new mime types

2.1.13 / 2016-11-18
===================

  * deps: mime-db@~1.25.0
    - Add new mime types

2.1.12 / 2016-09-18
===================

  * deps: mime-db@~1.24.0
    - Add new mime types
    - Add `audio/mp3`

2.1.11 / 2016-05-01
===================

  * deps: mime-db@~1.23.0
    - Add new mime types

2.1.10 / 2016-02-15
===================

  * deps: mime-db@~1.22.0
    - Add new mime types
    - Fix extension of `application/dash+xml`
    - Update primary extension for `audio/mp4`

2.1.9 / 2016-01-06
==================

  * deps: mime-db@~1.21.0
    - Add new mime types

2.1.8 / 2015-11-30
==================

  * deps: mime-db@~1.20.0
    - Add new mime types

2.1.7 / 2015-09-20
==================

  * deps: mime-db@~1.19.0
    - Add new mime types

2.1.6 / 2015-09-03
==================

  * deps: mime-db@~1.18.0
    - Add new mime types

2.1.5 / 2015-08-20
==================

  * deps: mime-db@~1.17.0
    - Add new mime types

2.1.4 / 2015-07-30
==================

  * deps: mime-db@~1.16.0
    - Add new mime types

2.1.3 / 2015-07-13
==================

  * deps: mime-db@~1.15.0
    - Add new mime types

2.1.2 / 2015-06-25
==================

  * deps: mime-db@~1.14.0
    - Add new mime types

2.1.1 / 2015-06-08
==================

  * perf: fix deopt during mapping

2.1.0 / 2015-06-07
==================

  * Fix incorrectly treating extension-less file name as extension
    - i.e. `'path/to/json'` will no longer return `application/json`
  * Fix `.charset(type)` to accept parameters
  * Fix `.charset(type)` to match case-insensitive
  * Improve generation of extension to MIME mapping
  * Refactor internals for readability and no argument reassignment
  * Prefer `application/*` MIME types from the same source
  * Prefer any type over `application/octet-stream`
  * deps: mime-db@~1.13.0
    - Add nginx as a source
    - Add new mime types

2.0.14 / 2015-06-06
===================

  * deps: mime-db@~1.12.0
    - Add new mime types

2.0.13 / 2015-05-31
===================

  * deps: mime-db@~1.11.0
    - Add new mime types

2.0.12 / 2015-05-19
===================

  * deps: mime-db@~1.10.0
    - Add new mime types

2.0.11 / 2015-05-05
===================

  * deps: mime-db@~1.9.1
    - Add new mime types

2.0.10 / 2015-03-13
===================

  * deps: mime-db@~1.8.0
    - Add new mime types

2.0.9 / 2015-02-09
==================

  * deps: mime-db@~1.7.0
    - Add new mime types
    - Community extensions ownership transferred from `node-mime`

2.0.8 / 2015-01-29
==================

  * deps: mime-db@~1.6.0
    - Add new mime types

2.0.7 / 2014-12-30
==================

  * deps: mime-db@~1.5.0
    - Add new mime types
    - Fix various invalid MIME type entries

2.0.6 / 2014-12-30
==================

  * deps: mime-db@~1.4.0
    - Add new mime types
    - Fix various invalid MIME type entries
    - Remove example template MIME types

2.0.5 / 2014-12-29
==================

  * deps: mime-db@~1.3.1
    - Fix missing extensions

2.0.4 / 2014-12-10
==================

  * deps: mime-db@~1.3.0
    - Add new mime types

2.0.3 / 2014-11-09
==================

  * deps: mime-db@~1.2.0
    - Add new mime types

2.0.2 / 2014-09-28
==================

  * deps: mime-db@~1.1.0
    - Add new mime types
    - Add additional compressible
    - Update charsets

2.0.1 / 2014-09-07
==================

  * Support Node.js 0.6

2.0.0 / 2014-09-02
==================

  * Use `mime-db`
  * Remove `.define()`

1.0.2 / 2014-08-04
==================

  * Set charset=utf-8 for `text/javascript`

1.0.1 / 2014-06-24
==================

  * Add `text/jsx` type

1.0.0 / 2014-05-12
==================

  * Return `false` for unknown types
  * Set charset=utf-8 for `application/json`

0.1.0 / 2014-05-02
==================

  * Initial release


---

# mime-types

[![NPM Version][npm-image]][npm-url]
[![NPM Downloads][downloads-image]][downloads-url]
[![Node.js Version][node-version-image]][node-version-url]
[![Build Status][travis-image]][travis-url]
[![Test Coverage][coveralls-image]][coveralls-url]

The ultimate javascript content-type utility.

Similar to [the `mime@1.x` module](https://www.npmjs.com/package/mime), except:

- __No fallbacks.__ Instead of naively returning the first available type,
  `mime-types` simply returns `false`, so do
  `var type = mime.lookup('unrecognized') || 'application/octet-stream'`.
- No `new Mime()` business, so you could do `var lookup = require('mime-types').lookup`.
- No `.define()` functionality
- Bug fixes for `.lookup(path)`

Otherwise, the API is compatible with `mime` 1.x.

## Install

This is a [Node.js](https://nodejs.org/en/) module available through the
[npm registry](https://www.npmjs.com/). Installation is done using the
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):

```sh
$ npm install mime-types
```

## Adding Types

All mime types are based on [mime-db](https://www.npmjs.com/package/mime-db),
so open a PR there if you'd like to add mime types.

## API

```js
var mime = require('mime-types')
```

All functions return `false` if input is invalid or not found.

### mime.lookup(path)

Lookup the content-type associated with a file.

```js
mime.lookup('json')             // 'application/json'
mime.lookup('.md')              // 'text/markdown'
mime.lookup('file.html')        // 'text/html'
mime.lookup('folder/file.js')   // 'application/javascript'
mime.lookup('folder/.htaccess') // false

mime.lookup('cats') // false
```

### mime.contentType(type)

Create a full content-type header given a content-type or extension.

```js
mime.contentType('markdown')  // 'text/x-markdown; charset=utf-8'
mime.contentType('file.json') // 'application/json; charset=utf-8'

// from a full path
mime.contentType(path.extname('/path/to/file.json')) // 'application/json; charset=utf-8'
```

### mime.extension(type)

Get the default extension for a content-type.

```js
mime.extension('application/octet-stream') // 'bin'
```

### mime.charset(type)

Lookup the implied default charset of a content-type.

```js
mime.charset('text/markdown') // 'UTF-8'
```

### var type = mime.types[extension]

A map of content-types by extension.

### [extensions...] = mime.extensions[type]

A map of extensions by content-type.

## License

[MIT](LICENSE)

[npm-image]: https://img.shields.io/npm/v/mime-types.svg
[npm-url]: https://npmjs.org/package/mime-types
[node-version-image]: https://img.shields.io/node/v/mime-types.svg
[node-version-url]: https://nodejs.org/en/download/
[travis-image]: https://img.shields.io/travis/jshttp/mime-types/master.svg
[travis-url]: https://travis-ci.org/jshttp/mime-types
[coveralls-image]: https://img.shields.io/coveralls/jshttp/mime-types/master.svg
[coveralls-url]: https://coveralls.io/r/jshttp/mime-types
[downloads-image]: https://img.shields.io/npm/dm/mime-types.svg
[downloads-url]: https://npmjs.org/package/mime-types


---

# mimic-fn [![Build Status](https://travis-ci.org/sindresorhus/mimic-fn.svg?branch=master)](https://travis-ci.org/sindresorhus/mimic-fn)

> Make a function mimic another one

Useful when you wrap a function in another function and like to preserve the original name and other properties.


## Install

```
$ npm install mimic-fn
```


## Usage

```js
const mimicFn = require('mimic-fn');

function foo() {}
foo.unicorn = '🦄';

function wrapper() {
	return foo();
}

console.log(wrapper.name);
//=> 'wrapper'

mimicFn(wrapper, foo);

console.log(wrapper.name);
//=> 'foo'

console.log(wrapper.unicorn);
//=> '🦄'
```


## API

It will copy over the properties `name`, `length`, `displayName`, and any custom properties you may have set.

### mimicFn(to, from)

Modifies the `to` function and returns it.

#### to

Type: `Function`

Mimicking function.

#### from

Type: `Function`

Function to mimic.


## Related

- [rename-fn](https://github.com/sindresorhus/rename-fn) - Rename a function
- [keep-func-props](https://github.com/ehmicky/keep-func-props) - Wrap a function without changing its name, length and other properties


## License

MIT © [Sindre Sorhus](https://sindresorhus.com)


---

# mimic-response

> Mimic a [Node.js HTTP response stream](https://nodejs.org/api/http.html#http_class_http_incomingmessage)

## Install

```
$ npm install mimic-response
```

## Usage

```js
import {PassThrough as PassThroughStream} from 'node:stream';
import mimicResponse from 'mimic-response';

const responseStream = getHttpResponseStream();
const myStream = new PassThroughStream();

mimicResponse(responseStream, myStream);

console.log(myStream.statusCode);
//=> 200
```

## API

### mimicResponse(from, to)

**Note #1:** The `from.destroy(error)` function is not proxied. You have to call it manually:

```js
import {PassThrough as PassThroughStream} from 'node:stream';
import mimicResponse from 'mimic-response';

const responseStream = getHttpResponseStream();

const myStream = new PassThroughStream({
	destroy(error, callback) {
		responseStream.destroy();

		callback(error);
	}
});

myStream.destroy();
```

Please note that `myStream` and `responseStream` never throw. The error is passed to the request instead.

#### from

Type: `Stream`

[Node.js HTTP response stream.](https://nodejs.org/api/http.html#http_class_http_incomingmessage)

#### to

Type: `Stream`

Any stream.

## Related

- [mimic-fn](https://github.com/sindresorhus/mimic-fn) - Make a function mimic another one
- [clone-response](https://github.com/lukechilds/clone-response) - Clone a Node.js response stream

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-mimic-response?utm_source=npm-mimic-response&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

<div align="center">
  <img width="200" height="200" src="https://cdn.worldvectorlogo.com/logos/logo-javascript.svg">
  <a href="https://webpack.js.org/">
    <img width="200" height="200" vspace="" hspace="25" src="https://cdn.rawgit.com/webpack/media/e7485eb2/logo/icon-square-big.svg">
  </a>
  <h1>mini-css-extract-plugin</h1>
</div>

[![npm][npm]][npm-url]
[![node][node]][node-url]
[![tests][tests]][tests-url]
[![coverage][cover]][cover-url]
[![discussion][discussion]][discussion-url]
[![size][size]][size-url]

# mini-css-extract-plugin

This plugin extracts CSS into separate files. It creates a CSS file per JS file which contains CSS. It supports On-Demand-Loading of CSS and SourceMaps.

It builds on top of a new webpack v5 feature and requires webpack 5 to work.

Compared to the extract-text-webpack-plugin:

- Async loading
- No duplicate compilation (performance)
- Easier to use
- Specific to CSS

## Getting Started

To begin, you'll need to install `mini-css-extract-plugin`:

```console
npm install --save-dev mini-css-extract-plugin
```

or

```console
yarn add -D mini-css-extract-plugin
```

or

```console
pnpm add -D mini-css-extract-plugin
```

It's recommended to combine `mini-css-extract-plugin` with the [`css-loader`](https://github.com/webpack-contrib/css-loader)

Then add the loader and the plugin to your `webpack` config. For example:

**style.css**

```css
body {
  background: green;
}
```

**component.js**

```js
import "./style.css";
```

**webpack.config.js**

```js
const MiniCssExtractPlugin = require("mini-css-extract-plugin");

module.exports = {
  plugins: [new MiniCssExtractPlugin()],
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [MiniCssExtractPlugin.loader, "css-loader"],
      },
    ],
  },
};
```

> [!WARNING]
>
> Note that if you import CSS from your webpack entrypoint or import styles in the [initial](https://webpack.js.org/concepts/under-the-hood/#chunks) chunk, `mini-css-extract-plugin` will not load this CSS into the page. Please use [`html-webpack-plugin`](https://github.com/jantimon/html-webpack-plugin) for automatic generation `link` tags or create `index.html` file with `link` tag.

> [!WARNING]
>
> Source maps works only for `source-map`/`nosources-source-map`/`hidden-nosources-source-map`/`hidden-source-map` values because CSS only supports source maps with the `sourceMappingURL` comment (i.e. `//# sourceMappingURL=style.css.map`). If you need set `devtool` to another value you can enable source maps generation for extracted CSS using [`sourceMap: true`](https://github.com/webpack-contrib/css-loader#sourcemap) for `css-loader`.

## Options

### Plugin Options

- **[`filename`](#filename)**
- **[`chunkFilename`](#chunkFilename)**
- **[`ignoreOrder`](#ignoreOrder)**
- **[`insert`](#insert)**
- **[`attributes`](#attributes)**
- **[`linkType`](#linkType)**
- **[`runtime`](#runtime)**
- **[`experimentalUseImportModule`](#experimentalUseImportModule)**

#### `filename`

Type:

```ts
type filename =
  | string
  | ((pathData: PathData, assetInfo?: AssetInfo) => string);
```

Default: `[name].css`

This option determines the name of each output CSS file.

Works like [`output.filename`](https://webpack.js.org/configuration/output/#outputfilename)

#### `chunkFilename`

Type:

```ts
type chunkFilename =
  | string
  | ((pathData: PathData, assetInfo?: AssetInfo) => string);
```

Default: `based on filename`

> Specifying `chunkFilename` as a `function` is only available in webpack@5

This option determines the name of non-entry chunk files.

Works like [`output.chunkFilename`](https://webpack.js.org/configuration/output/#outputchunkfilename)

#### `ignoreOrder`

Type:

```ts
type ignoreOrder = boolean;
```

Default: `false`

Remove Order Warnings.
See [examples](#remove-order-warnings) below for details.

#### `insert`

Type:

```ts
type insert = string | ((linkTag: HTMLLinkElement) => void);
```

Default: `document.head.appendChild(linkTag);`

Inserts the `link` tag at the given position for [non-initial (async)](https://webpack.js.org/concepts/under-the-hood/#chunks) CSS chunks

> [!WARNING]
>
> Only for [non-initial (async)](https://webpack.js.org/concepts/under-the-hood/#chunks) chunks.

By default, the `mini-css-extract-plugin` appends styles (`<link>` elements) to `document.head` of the current `window`.

However in some circumstances it might be necessary to have finer control over the append target or even delay `link` elements insertion.
For example this is the case when you asynchronously load styles for an application that runs inside of an iframe.
In such cases `insert` can be configured to be a function or a custom selector.

If you target an [iframe](https://developer.mozilla.org/en-US/docs/Web/API/HTMLIFrameElement) make sure that the parent document has sufficient access rights to reach into the frame document and append elements to it.

##### `string`

Allows to setup custom [query selector](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector).
A new `<link>` element will be inserted after the found item.

**webpack.config.js**

```js
new MiniCssExtractPlugin({
  insert: "#some-element",
});
```

A new `<link>` element will be inserted after the element with id `some-element`.

##### `function`

Allows to override default behavior and insert styles at any position.

> ⚠ Do not forget that this code will run in the browser alongside your application. Since not all browsers support latest ECMA features like `let`, `const`, `arrow function expression` and etc we recommend you to use only ECMA 5 features and syntax.

> > ⚠ The `insert` function is serialized to string and passed to the plugin. This means that it won't have access to the scope of the webpack configuration module.

**webpack.config.js**

```js
new MiniCssExtractPlugin({
  insert: function (linkTag) {
    var reference = document.querySelector("#some-element");
    if (reference) {
      reference.parentNode.insertBefore(linkTag, reference);
    }
  },
});
```

A new `<link>` element will be inserted before the element with id `some-element`.

#### `attributes`

Type:

```ts
type attributes = Record<string, string>};
```

Default: `{}`

> [!WARNING]
>
> Only for [non-initial (async)](https://webpack.js.org/concepts/under-the-hood/#chunks) chunks.

If defined, the `mini-css-extract-plugin` will attach given attributes with their values on `<link>` element.

**webpack.config.js**

```js
const MiniCssExtractPlugin = require("mini-css-extract-plugin");

module.exports = {
  plugins: [
    new MiniCssExtractPlugin({
      attributes: {
        id: "target",
        "data-target": "example",
      },
    }),
  ],
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [MiniCssExtractPlugin.loader, "css-loader"],
      },
    ],
  },
};
```

> [!NOTE]
>
> It's only applied to dynamically loaded css chunks, if you want to modify link attributes inside html file, please using [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin)

#### `linkType`

Type:

```ts
type linkType = string | boolean;
```

Default: `text/css`

This option allows loading asynchronous chunks with a custom link type, such as `<link type="text/css" ...>`.

##### `string`

Possible values: `text/css`

**webpack.config.js**

```js
const MiniCssExtractPlugin = require("mini-css-extract-plugin");

module.exports = {
  plugins: [
    new MiniCssExtractPlugin({
      linkType: "text/css",
    }),
  ],
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [MiniCssExtractPlugin.loader, "css-loader"],
      },
    ],
  },
};
```

##### `boolean`

`false` disables the link `type` attribute

**webpack.config.js**

```js
const MiniCssExtractPlugin = require("mini-css-extract-plugin");

module.exports = {
  plugins: [
    new MiniCssExtractPlugin({
      linkType: false,
    }),
  ],
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [MiniCssExtractPlugin.loader, "css-loader"],
      },
    ],
  },
};
```

#### `runtime`

Type:

```ts
type runtime = boolean;
```

Default: `true`

Allows to enable/disable the runtime generation.
CSS will be still extracted and can be used for a custom loading methods.
For example, you can use [assets-webpack-plugin](https://github.com/ztoben/assets-webpack-plugin) to retrieve them then use your own runtime code to download assets when needed.

`false` to skip.

**webpack.config.js**

```js
const MiniCssExtractPlugin = require("mini-css-extract-plugin");

module.exports = {
  plugins: [
    new MiniCssExtractPlugin({
      runtime: false,
    }),
  ],
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [MiniCssExtractPlugin.loader, "css-loader"],
      },
    ],
  },
};
```

#### `experimentalUseImportModule`

Type:

```ts
type experimentalUseImportModule = boolean;
```

Default: `undefined`

Enabled by default if not explicitly enabled (i.e. `true` and `false` allow you to explicitly control this option) and new API is available (at least webpack `5.52.0` is required).
Boolean values are available since version `5.33.2`, but you need to enable `experiments.executeModule` (not required from webpack `5.52.0`).

Use a new webpack API to execute modules instead of child compilers.
This improves performance and memory usage a lot.

When combined with `experiments.layers`, this adds a `layer` option to the loader options to specify the layer of the css execution.

**webpack.config.js**

```js
const MiniCssExtractPlugin = require("mini-css-extract-plugin");

module.exports = {
  plugins: [
    new MiniCssExtractPlugin({
      // You don't need this for `>= 5.52.0` due to the fact that this is enabled by default
      // Required only for `>= 5.33.2 & <= 5.52.0`
      // Not available/unsafe for `<= 5.33.2`
      experimentalUseImportModule: true,
    }),
  ],
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [MiniCssExtractPlugin.loader, "css-loader"],
      },
    ],
  },
};
```

### Loader Options

- **[`publicPath`](#publicPath)**
- **[`emit`](#emit)**
- **[`esModule`](#esModule)**
- **[`defaultExport`](#defaultExport)**

#### `publicPath`

Type:

```ts
type publicPath =
  | string
  | ((resourcePath: string, rootContext: string) => string);
```

Default: the `publicPath` in `webpackOptions.output`

Specifies a custom public path for the external resources like images, files, etc inside `CSS`.
Works like [`output.publicPath`](https://webpack.js.org/configuration/output/#outputpublicpath)

##### `string`

**webpack.config.js**

```js
const MiniCssExtractPlugin = require("mini-css-extract-plugin");

module.exports = {
  plugins: [
    new MiniCssExtractPlugin({
      // Options similar to the same options in webpackOptions.output
      // both options are optional
      filename: "[name].css",
      chunkFilename: "[id].css",
    }),
  ],
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          {
            loader: MiniCssExtractPlugin.loader,
            options: {
              publicPath: "/public/path/to/",
            },
          },
          "css-loader",
        ],
      },
    ],
  },
};
```

##### `function`

**webpack.config.js**

```js
const MiniCssExtractPlugin = require("mini-css-extract-plugin");

module.exports = {
  plugins: [
    new MiniCssExtractPlugin({
      // Options similar to the same options in webpackOptions.output
      // both options are optional
      filename: "[name].css",
      chunkFilename: "[id].css",
    }),
  ],
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          {
            loader: MiniCssExtractPlugin.loader,
            options: {
              publicPath: (resourcePath, context) => {
                return path.relative(path.dirname(resourcePath), context) + "/";
              },
            },
          },
          "css-loader",
        ],
      },
    ],
  },
};
```

#### `emit`

Type:

```ts
type emit = boolean;
```

Default: `true`

If true, emits a file (writes a file to the filesystem). If false, the plugin will extract the CSS but **will not** emit the file.
It is often useful to disable this option for server-side packages.

#### `esModule`

Type:

```ts
type esModule = boolean;
```

Default: `true`

By default, `mini-css-extract-plugin` generates JS modules that use the ES modules syntax.
There are some cases in which using ES modules is beneficial, like in the case of [module concatenation](https://webpack.js.org/plugins/module-concatenation-plugin/) and [tree shaking](https://webpack.js.org/guides/tree-shaking/).

You can enable a CommonJS syntax using:

**webpack.config.js**

```js
const MiniCssExtractPlugin = require("mini-css-extract-plugin");

module.exports = {
  plugins: [new MiniCssExtractPlugin()],
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          {
            loader: MiniCssExtractPlugin.loader,
            options: {
              esModule: false,
            },
          },
          "css-loader",
        ],
      },
    ],
  },
};
```

#### `defaultExport`

Type:

```ts
type defaultExport = boolean;
```

Default: `false`

> [!NOTE]
>
> This option will work only when you set `namedExport` to `true` in `css-loader`

By default, `mini-css-extract-plugin` generates JS modules based on the `esModule` and `namedExport` options in `css-loader`.
Using the `esModule` and `namedExport` options will allow you to better optimize your code.
If you set `esModule: true` and `namedExport: true` for `css-loader` `mini-css-extract-plugin` will generate **only** a named export.
Our official recommendation is to use only named export for better future compatibility.
But for some applications, it is not easy to quickly rewrite the code from the default export to a named export.

In case you need both default and named exports, you can enable this option:

**webpack.config.js**

```js
const MiniCssExtractPlugin = require("mini-css-extract-plugin");

module.exports = {
  plugins: [new MiniCssExtractPlugin()],
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          {
            loader: MiniCssExtractPlugin.loader,
            options: {
              defaultExport: true,
            },
          },
          {
            loader: "css-loader",
            options: {
              esModule: true,
              modules: {
                namedExport: true,
              },
            },
          },
        ],
      },
    ],
  },
};
```

## Examples

### Recommended

For `production` builds it's recommended to extract the CSS from your bundle being able to use parallel loading of CSS/JS resources later on.
This can be achieved by using the `mini-css-extract-plugin`, because it creates separate css files.
For `development` mode (including `webpack-dev-server`) you can use [style-loader](https://github.com/webpack-contrib/style-loader), because it injects CSS into the DOM using multiple <style></style> and works faster.

> Do not use `style-loader` and `mini-css-extract-plugin` together.

**webpack.config.js**

```js
const MiniCssExtractPlugin = require("mini-css-extract-plugin");
const devMode = process.env.NODE_ENV !== "production";

module.exports = {
  module: {
    rules: [
      {
        // If you enable `experiments.css` or `experiments.futureDefaults`, please uncomment line below
        // type: "javascript/auto",
        test: /\.(sa|sc|c)ss$/,
        use: [
          devMode ? "style-loader" : MiniCssExtractPlugin.loader,
          "css-loader",
          "postcss-loader",
          "sass-loader",
        ],
      },
    ],
  },
  plugins: [].concat(devMode ? [] : [new MiniCssExtractPlugin()]),
};
```

### Minimal example

**webpack.config.js**

```js
const MiniCssExtractPlugin = require("mini-css-extract-plugin");

module.exports = {
  plugins: [
    new MiniCssExtractPlugin({
      // Options similar to the same options in webpackOptions.output
      // all options are optional
      filename: "[name].css",
      chunkFilename: "[id].css",
      ignoreOrder: false, // Enable to remove warnings about conflicting order
    }),
  ],
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          {
            loader: MiniCssExtractPlugin.loader,
            options: {
              // you can specify a publicPath here
              // by default it uses publicPath in webpackOptions.output
              publicPath: "../",
            },
          },
          "css-loader",
        ],
      },
    ],
  },
};
```

### Named export for CSS Modules

> ⚠ Names of locals are converted to `camelCase`.

> ⚠ It is not allowed to use JavaScript reserved words in css class names.

> ⚠ Options `esModule` and `modules.namedExport` in `css-loader` should be enabled.

**styles.css**

```css
.foo-baz {
  color: red;
}
.bar {
  color: blue;
}
```

**index.js**

```js
import { fooBaz, bar } from "./styles.css";

console.log(fooBaz, bar);
```

You can enable a ES module named export using:

**webpack.config.js**

```js
const MiniCssExtractPlugin = require("mini-css-extract-plugin");

module.exports = {
  plugins: [new MiniCssExtractPlugin()],
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          {
            loader: MiniCssExtractPlugin.loader,
          },
          {
            loader: "css-loader",
            options: {
              esModule: true,
              modules: {
                namedExport: true,
                localIdentName: "foo__[name]__[local]",
              },
            },
          },
        ],
      },
    ],
  },
};
```

### The `publicPath` option as function

**webpack.config.js**

```js
const MiniCssExtractPlugin = require("mini-css-extract-plugin");

module.exports = {
  plugins: [
    new MiniCssExtractPlugin({
      // Options similar to the same options in webpackOptions.output
      // both options are optional
      filename: "[name].css",
      chunkFilename: "[id].css",
    }),
  ],
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          {
            loader: MiniCssExtractPlugin.loader,
            options: {
              publicPath: (resourcePath, context) => {
                // publicPath is the relative path of the resource to the context
                // e.g. for ./css/admin/main.css the publicPath will be ../../
                // while for ./css/main.css the publicPath will be ../
                return path.relative(path.dirname(resourcePath), context) + "/";
              },
            },
          },
          "css-loader",
        ],
      },
    ],
  },
};
```

### Advanced configuration example

This plugin should not be used with `style-loader` in the loaders chain.

Here is an example to have both HMR in `development` and your styles extracted in a file for `production` builds.

(Loaders options left out for clarity, adapt accordingly to your needs.)

You should not use `HotModuleReplacementPlugin` plugin if you are using a `webpack-dev-server`.
`webpack-dev-server` enables / disables HMR using `hot` option.

**webpack.config.js**

```js
const webpack = require("webpack");
const MiniCssExtractPlugin = require("mini-css-extract-plugin");
const devMode = process.env.NODE_ENV !== "production";

const plugins = [
  new MiniCssExtractPlugin({
    // Options similar to the same options in webpackOptions.output
    // both options are optional
    filename: devMode ? "[name].css" : "[name].[contenthash].css",
    chunkFilename: devMode ? "[id].css" : "[id].[contenthash].css",
  }),
];
if (devMode) {
  // only enable hot in development
  plugins.push(new webpack.HotModuleReplacementPlugin());
}

module.exports = {
  plugins,
  module: {
    rules: [
      {
        test: /\.(sa|sc|c)ss$/,
        use: [
          MiniCssExtractPlugin.loader,
          "css-loader",
          "postcss-loader",
          "sass-loader",
        ],
      },
    ],
  },
};
```

### Hot Module Reloading (HMR)

> [!NOTE]
>
> HMR is automatically supported in webpack 5. No need to configure it. Skip the following:

The `mini-css-extract-plugin` supports hot reloading of actual css files in development.
Some options are provided to enable HMR of both standard stylesheets and locally scoped CSS or CSS modules.
Below is an example configuration of mini-css for HMR use with CSS modules.

You should not use `HotModuleReplacementPlugin` plugin if you are using a `webpack-dev-server`.
`webpack-dev-server` enables / disables HMR using `hot` option.

**webpack.config.js**

```js
const webpack = require("webpack");
const MiniCssExtractPlugin = require("mini-css-extract-plugin");

const plugins = [
  new MiniCssExtractPlugin({
    // Options similar to the same options in webpackOptions.output
    // both options are optional
    filename: devMode ? "[name].css" : "[name].[contenthash].css",
    chunkFilename: devMode ? "[id].css" : "[id].[contenthash].css",
  }),
];
if (devMode) {
  // only enable hot in development
  plugins.push(new webpack.HotModuleReplacementPlugin());
}

module.exports = {
  plugins,
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          {
            loader: MiniCssExtractPlugin.loader,
            options: {},
          },
          "css-loader",
        ],
      },
    ],
  },
};
```

### Minimizing For Production

To minify the output, use a plugin like [css-minimizer-webpack-plugin](https://github.com/webpack-contrib/css-minimizer-webpack-plugin).

**webpack.config.js**

```js
const MiniCssExtractPlugin = require("mini-css-extract-plugin");
const CssMinimizerPlugin = require("css-minimizer-webpack-plugin");

module.exports = {
  plugins: [
    new MiniCssExtractPlugin({
      filename: "[name].css",
      chunkFilename: "[id].css",
    }),
  ],
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [MiniCssExtractPlugin.loader, "css-loader"],
      },
    ],
  },
  optimization: {
    minimizer: [
      // For webpack@5 you can use the `...` syntax to extend existing minimizers (i.e. `terser-webpack-plugin`), uncomment the next line
      // `...`,
      new CssMinimizerPlugin(),
    ],
  },
};
```

This will enable CSS optimization only in production mode. If you want to run it also in development set the `optimization.minimize` option to true.

### Using preloaded or inlined CSS

The runtime code detects already added CSS via `<link>` or `<style>` tag.
This can be useful when injecting CSS on server-side for Server-Side-Rendering.
The `href` of the `<link>` tag has to match the URL that will be used for loading the CSS chunk.
The `data-href` attribute can be used for `<link>` and `<style>` too.
When inlining CSS `data-href` must be used.

### Extracting all CSS in a single file

The CSS can be extracted in one CSS file using `optimization.splitChunks.cacheGroups`.

**webpack.config.js**

```js
const MiniCssExtractPlugin = require("mini-css-extract-plugin");

module.exports = {
  optimization: {
    splitChunks: {
      cacheGroups: {
        styles: {
          name: "styles",
          type: "css/mini-extract",
          chunks: "all",
          enforce: true,
        },
      },
    },
  },
  plugins: [
    new MiniCssExtractPlugin({
      filename: "[name].css",
    }),
  ],
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [MiniCssExtractPlugin.loader, "css-loader"],
      },
    ],
  },
};
```

Note that `type` should be used instead of `test` in Webpack 5, or else an extra `.js` file can be generated besides the `.css` file. This is because `test` doesn't know which modules should be dropped (in this case, it won't detect that `.js` should be dropped).

### Extracting CSS based on entry

You may also extract the CSS based on the webpack entry name.
This is especially useful if you import routes dynamically but want to keep your CSS bundled according to entry.
This also prevents the CSS duplication issue one had with the ExtractTextPlugin.

```js
const path = require("path");
const MiniCssExtractPlugin = require("mini-css-extract-plugin");

module.exports = {
  entry: {
    foo: path.resolve(__dirname, "src/foo"),
    bar: path.resolve(__dirname, "src/bar"),
  },
  optimization: {
    splitChunks: {
      cacheGroups: {
        fooStyles: {
          type: "css/mini-extract",
          name: "styles_foo",
          chunks: (chunk) => {
            return chunk.name === "foo";
          },
          enforce: true,
        },
        barStyles: {
          type: "css/mini-extract",
          name: "styles_bar",
          chunks: (chunk) => {
            return chunk.name === "bar";
          },
          enforce: true,
        },
      },
    },
  },
  plugins: [
    new MiniCssExtractPlugin({
      filename: "[name].css",
    }),
  ],
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [MiniCssExtractPlugin.loader, "css-loader"],
      },
    ],
  },
};
```

### Filename Option as function

With the `filename` option you can use chunk data to customize the filename.
This is particularly useful when dealing with multiple entry points and wanting to get more control out of the filename for a given entry point/chunk.
In the example below, we'll use `filename` to output the generated css into a different directory.

**webpack.config.js**

```js
const MiniCssExtractPlugin = require("mini-css-extract-plugin");

module.exports = {
  plugins: [
    new MiniCssExtractPlugin({
      filename: ({ chunk }) => `${chunk.name.replace("/js/", "/css/")}.css`,
    }),
  ],
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [MiniCssExtractPlugin.loader, "css-loader"],
      },
    ],
  },
};
```

### Long Term Caching

For long term caching use `filename: "[contenthash].css"`. Optionally add `[name]`.

**webpack.config.js**

```js
const MiniCssExtractPlugin = require("mini-css-extract-plugin");

module.exports = {
  plugins: [
    new MiniCssExtractPlugin({
      filename: "[name].[contenthash].css",
      chunkFilename: "[id].[contenthash].css",
    }),
  ],
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [MiniCssExtractPlugin.loader, "css-loader"],
      },
    ],
  },
};
```

### Remove Order Warnings

For projects where css ordering has been mitigated through consistent use of scoping or naming conventions, such as [CSS Modules](https://github.com/css-modules/css-modules), the css order warnings can be disabled by setting the ignoreOrder flag to true for the plugin.

**webpack.config.js**

```js
const MiniCssExtractPlugin = require("mini-css-extract-plugin");

module.exports = {
  plugins: [
    new MiniCssExtractPlugin({
      ignoreOrder: true,
    }),
  ],
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [MiniCssExtractPlugin.loader, "css-loader"],
      },
    ],
  },
};
```

### Multiple Themes

**webpack.config.js**

```js
const MiniCssExtractPlugin = require("mini-css-extract-plugin");

module.exports = {
  entry: "./src/index.js",
  module: {
    rules: [
      {
        test: /\.s[ac]ss$/i,
        oneOf: [
          {
            resourceQuery: "?dark",
            use: [
              MiniCssExtractPlugin.loader,
              "css-loader",
              {
                loader: "sass-loader",
                options: {
                  additionalData: `@use 'dark-theme/vars' as vars;`,
                },
              },
            ],
          },
          {
            use: [
              MiniCssExtractPlugin.loader,
              "css-loader",
              {
                loader: "sass-loader",
                options: {
                  additionalData: `@use 'light-theme/vars' as vars;`,
                },
              },
            ],
          },
        ],
      },
    ],
  },
  plugins: [
    new MiniCssExtractPlugin({
      filename: "[name].css",
      attributes: {
        id: "theme",
      },
    }),
  ],
};
```

**src/index.js**

```js
import "./style.scss";

let theme = "light";
const themes = {};

themes[theme] = document.querySelector("#theme");

async function loadTheme(newTheme) {
  // eslint-disable-next-line no-console
  console.log(`CHANGE THEME - ${newTheme}`);

  const themeElement = document.querySelector("#theme");

  if (themeElement) {
    themeElement.remove();
  }

  if (themes[newTheme]) {
    // eslint-disable-next-line no-console
    console.log(`THEME ALREADY LOADED - ${newTheme}`);

    document.head.appendChild(themes[newTheme]);

    return;
  }

  if (newTheme === "dark") {
    // eslint-disable-next-line no-console
    console.log(`LOADING THEME - ${newTheme}`);

    import(/* webpackChunkName: "dark" */ "./style.scss?dark").then(() => {
      themes[newTheme] = document.querySelector("#theme");

      // eslint-disable-next-line no-console
      console.log(`LOADED - ${newTheme}`);
    });
  }
}

document.onclick = () => {
  if (theme === "light") {
    theme = "dark";
  } else {
    theme = "light";
  }

  loadTheme(theme);
};
```

**src/dark-theme/\_vars.scss**

```scss
$background: black;
```

**src/light-theme/\_vars.scss**

```scss
$background: white;
```

**src/styles.scss**

```scss
body {
  background-color: vars.$background;
}
```

**public/index.html**

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Document</title>
    <link id="theme" rel="stylesheet" type="text/css" href="./main.css" />
  </head>
  <body>
    <script src="./main.js"></script>
  </body>
</html>
```

### Media Query Plugin

If you'd like to extract the media queries from the extracted CSS (so mobile users don't need to load desktop or tablet specific CSS anymore) you should use one of the following plugins:

- [Media Query Plugin](https://github.com/SassNinja/media-query-plugin)
- [Media Query Splitting Plugin](https://github.com/mike-diamond/media-query-splitting-plugin)

## Hooks

The mini-css-extract-plugin provides hooks to extend it to your needs.

### beforeTagInsert

`SyncWaterfallHook`

Called before inject the insert code for link tag. Should return a string

```javascript
MiniCssExtractPlugin.getCompilationHooks(compilation).beforeTagInsert.tap(
  "changeHref",
  (source, varNames) =>
    Template.asString([
      source,
      `${varNames.tag}.setAttribute("href", "https://github.com/webpack-contrib/mini-css-extract-plugin");`,
    ])
);
```

## Contributing

Please take a moment to read our contributing guidelines if you haven't yet done so.

[CONTRIBUTING](./.github/CONTRIBUTING.md)

## License

[MIT](./LICENSE)

[npm]: https://img.shields.io/npm/v/mini-css-extract-plugin.svg
[npm-url]: https://npmjs.com/package/mini-css-extract-plugin
[node]: https://img.shields.io/node/v/mini-css-extract-plugin.svg
[node-url]: https://nodejs.org
[tests]: https://github.com/webpack-contrib/mini-css-extract-plugin/workflows/mini-css-extract-plugin/badge.svg
[tests-url]: https://github.com/webpack-contrib/mini-css-extract-plugin/actions
[cover]: https://codecov.io/gh/webpack-contrib/mini-css-extract-plugin/branch/master/graph/badge.svg
[cover-url]: https://codecov.io/gh/webpack-contrib/mini-css-extract-plugin
[discussion]: https://img.shields.io/github/discussions/webpack/webpack
[discussion-url]: https://github.com/webpack/webpack/discussions
[size]: https://packagephobia.now.sh/badge?p=mini-css-extract-plugin
[size-url]: https://packagephobia.now.sh/result?p=mini-css-extract-plugin


---

minimalistic-assert
===

very minimalistic assert module.


---

# minimatch

A minimal matching utility.

[![Build Status](https://travis-ci.org/isaacs/minimatch.svg?branch=master)](http://travis-ci.org/isaacs/minimatch)


This is the matching library used internally by npm.

It works by converting glob expressions into JavaScript `RegExp`
objects.

## Usage

```javascript
var minimatch = require("minimatch")

minimatch("bar.foo", "*.foo") // true!
minimatch("bar.foo", "*.bar") // false!
minimatch("bar.foo", "*.+(bar|foo)", { debug: true }) // true, and noisy!
```

## Features

Supports these glob features:

* Brace Expansion
* Extended glob matching
* "Globstar" `**` matching

See:

* `man sh`
* `man bash`
* `man 3 fnmatch`
* `man 5 gitignore`

## Minimatch Class

Create a minimatch object by instantiating the `minimatch.Minimatch` class.

```javascript
var Minimatch = require("minimatch").Minimatch
var mm = new Minimatch(pattern, options)
```

### Properties

* `pattern` The original pattern the minimatch object represents.
* `options` The options supplied to the constructor.
* `set` A 2-dimensional array of regexp or string expressions.
  Each row in the
  array corresponds to a brace-expanded pattern.  Each item in the row
  corresponds to a single path-part.  For example, the pattern
  `{a,b/c}/d` would expand to a set of patterns like:

        [ [ a, d ]
        , [ b, c, d ] ]

    If a portion of the pattern doesn't have any "magic" in it
    (that is, it's something like `"foo"` rather than `fo*o?`), then it
    will be left as a string rather than converted to a regular
    expression.

* `regexp` Created by the `makeRe` method.  A single regular expression
  expressing the entire pattern.  This is useful in cases where you wish
  to use the pattern somewhat like `fnmatch(3)` with `FNM_PATH` enabled.
* `negate` True if the pattern is negated.
* `comment` True if the pattern is a comment.
* `empty` True if the pattern is `""`.

### Methods

* `makeRe` Generate the `regexp` member if necessary, and return it.
  Will return `false` if the pattern is invalid.
* `match(fname)` Return true if the filename matches the pattern, or
  false otherwise.
* `matchOne(fileArray, patternArray, partial)` Take a `/`-split
  filename, and match it against a single row in the `regExpSet`.  This
  method is mainly for internal use, but is exposed so that it can be
  used by a glob-walker that needs to avoid excessive filesystem calls.

All other methods are internal, and will be called as necessary.

### minimatch(path, pattern, options)

Main export.  Tests a path against the pattern using the options.

```javascript
var isJS = minimatch(file, "*.js", { matchBase: true })
```

### minimatch.filter(pattern, options)

Returns a function that tests its
supplied argument, suitable for use with `Array.filter`.  Example:

```javascript
var javascripts = fileList.filter(minimatch.filter("*.js", {matchBase: true}))
```

### minimatch.match(list, pattern, options)

Match against the list of
files, in the style of fnmatch or glob.  If nothing is matched, and
options.nonull is set, then return a list containing the pattern itself.

```javascript
var javascripts = minimatch.match(fileList, "*.js", {matchBase: true}))
```

### minimatch.makeRe(pattern, options)

Make a regular expression object from the pattern.

## Options

All options are `false` by default.

### debug

Dump a ton of stuff to stderr.

### nobrace

Do not expand `{a,b}` and `{1..3}` brace sets.

### noglobstar

Disable `**` matching against multiple folder names.

### dot

Allow patterns to match filenames starting with a period, even if
the pattern does not explicitly have a period in that spot.

Note that by default, `a/**/b` will **not** match `a/.d/b`, unless `dot`
is set.

### noext

Disable "extglob" style patterns like `+(a|b)`.

### nocase

Perform a case-insensitive match.

### nonull

When a match is not found by `minimatch.match`, return a list containing
the pattern itself if this option is set.  When not set, an empty list
is returned if there are no matches.

### matchBase

If set, then patterns without slashes will be matched
against the basename of the path if it contains slashes.  For example,
`a?b` would match the path `/xyz/123/acb`, but not `/xyz/acb/123`.

### nocomment

Suppress the behavior of treating `#` at the start of a pattern as a
comment.

### nonegate

Suppress the behavior of treating a leading `!` character as negation.

### flipNegate

Returns from negate expressions the same as if they were not negated.
(Ie, true on a hit, false on a miss.)

### partial

Compare a partial path to a pattern.  As long as the parts of the path that
are present are not contradicted by the pattern, it will be treated as a
match.  This is useful in applications where you're walking through a
folder structure, and don't yet have the full path, but want to ensure that
you do not walk down paths that can never be a match.

For example,

```js
minimatch('/a/b', '/a/*/c/d', { partial: true })  // true, might be /a/b/c/d
minimatch('/a/b', '/**/d', { partial: true })     // true, might be /a/b/.../d
minimatch('/x/y/z', '/a/**/z', { partial: true }) // false, because x !== a
```

### allowWindowsEscape

Windows path separator `\` is by default converted to `/`, which
prohibits the usage of `\` as a escape character. This flag skips that
behavior and allows using the escape character.

## Comparisons to other fnmatch/glob implementations

While strict compliance with the existing standards is a worthwhile
goal, some discrepancies exist between minimatch and other
implementations, and are intentional.

If the pattern starts with a `!` character, then it is negated.  Set the
`nonegate` flag to suppress this behavior, and treat leading `!`
characters normally.  This is perhaps relevant if you wish to start the
pattern with a negative extglob pattern like `!(a|B)`.  Multiple `!`
characters at the start of a pattern will negate the pattern multiple
times.

If a pattern starts with `#`, then it is treated as a comment, and
will not match anything.  Use `\#` to match a literal `#` at the
start of a line, or set the `nocomment` flag to suppress this behavior.

The double-star character `**` is supported by default, unless the
`noglobstar` flag is set.  This is supported in the manner of bsdglob
and bash 4.1, where `**` only has special significance if it is the only
thing in a path part.  That is, `a/**/b` will match `a/x/y/b`, but
`a/**b` will not.

If an escaped pattern has no matches, and the `nonull` flag is set,
then minimatch.match returns the pattern as-provided, rather than
interpreting the character escapes.  For example,
`minimatch.match([], "\\*a\\?")` will return `"\\*a\\?"` rather than
`"*a?"`.  This is akin to setting the `nullglob` option in bash, except
that it does not resolve escaped pattern characters.

If brace expansion is not disabled, then it is performed before any
other interpretation of the glob pattern.  Thus, a pattern like
`+(a|{b),c)}`, which would not be valid in bash or zsh, is expanded
**first** into the set of `+(a|b)` and `+(a|c)`, and those patterns are
checked for validity.  Since those two are valid, matching proceeds.


---

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [v1.2.8](https://github.com/minimistjs/minimist/compare/v1.2.7...v1.2.8) - 2023-02-09

### Merged

- [Fix] Fix long option followed by single dash [`#17`](https://github.com/minimistjs/minimist/pull/17)
- [Tests] Remove duplicate test [`#12`](https://github.com/minimistjs/minimist/pull/12)
- [Fix] opt.string works with multiple aliases [`#10`](https://github.com/minimistjs/minimist/pull/10)

### Fixed

- [Fix] Fix long option followed by single dash (#17) [`#15`](https://github.com/minimistjs/minimist/issues/15)
- [Tests] Remove duplicate test (#12) [`#8`](https://github.com/minimistjs/minimist/issues/8)
- [Fix] Fix long option followed by single dash [`#15`](https://github.com/minimistjs/minimist/issues/15)
- [Fix] opt.string works with multiple aliases (#10) [`#9`](https://github.com/minimistjs/minimist/issues/9)
- [Fix] Fix handling of short option with non-trivial equals [`#5`](https://github.com/minimistjs/minimist/issues/5)
- [Tests] Remove duplicate test [`#8`](https://github.com/minimistjs/minimist/issues/8)
- [Fix] opt.string works with multiple aliases [`#9`](https://github.com/minimistjs/minimist/issues/9)

### Commits

- Merge tag 'v0.2.3' [`a026794`](https://github.com/minimistjs/minimist/commit/a0267947c7870fc5847cf2d437fbe33f392767da)
- [eslint] fix indentation and whitespace [`5368ca4`](https://github.com/minimistjs/minimist/commit/5368ca4147e974138a54cc0dc4cea8f756546b70)
- [eslint] fix indentation and whitespace [`e5f5067`](https://github.com/minimistjs/minimist/commit/e5f5067259ceeaf0b098d14bec910f87e58708c7)
- [eslint] more cleanup [`62fde7d`](https://github.com/minimistjs/minimist/commit/62fde7d935f83417fb046741531a9e2346a36976)
- [eslint] more cleanup [`36ac5d0`](https://github.com/minimistjs/minimist/commit/36ac5d0d95e4947d074e5737d94814034ca335d1)
- [meta] add `auto-changelog` [`73923d2`](https://github.com/minimistjs/minimist/commit/73923d223553fca08b1ba77e3fbc2a492862ae4c)
- [actions] add reusable workflows [`d80727d`](https://github.com/minimistjs/minimist/commit/d80727df77bfa9e631044d7f16368d8f09242c91)
- [eslint] add eslint; rules to enable later are warnings [`48bc06a`](https://github.com/minimistjs/minimist/commit/48bc06a1b41f00e9cdf183db34f7a51ba70e98d4)
- [eslint] fix indentation [`34b0f1c`](https://github.com/minimistjs/minimist/commit/34b0f1ccaa45183c3c4f06a91f9b405180a6f982)
- [readme] rename and add badges [`5df0fe4`](https://github.com/minimistjs/minimist/commit/5df0fe49211bd09a3636f8686a7cb3012c3e98f0)
- [Dev Deps] switch from `covert` to `nyc` [`a48b128`](https://github.com/minimistjs/minimist/commit/a48b128fdb8d427dfb20a15273f83e38d97bef07)
- [Dev Deps] update `covert`, `tape`; remove unnecessary `tap` [`f0fb958`](https://github.com/minimistjs/minimist/commit/f0fb958e9a1fe980cdffc436a211b0bda58f621b)
- [meta] create FUNDING.yml; add `funding` in package.json [`3639e0c`](https://github.com/minimistjs/minimist/commit/3639e0c819359a366387e425ab6eabf4c78d3caa)
- [meta] use `npmignore` to autogenerate an npmignore file [`be2e038`](https://github.com/minimistjs/minimist/commit/be2e038c342d8333b32f0fde67a0026b79c8150e)
- Only apps should have lockfiles [`282b570`](https://github.com/minimistjs/minimist/commit/282b570e7489d01b03f2d6d3dabf79cd3e5f84cf)
- isConstructorOrProto adapted from PR [`ef9153f`](https://github.com/minimistjs/minimist/commit/ef9153fc52b6cea0744b2239921c5dcae4697f11)
- [Dev Deps] update `@ljharb/eslint-config`, `aud` [`098873c`](https://github.com/minimistjs/minimist/commit/098873c213cdb7c92e55ae1ef5aa1af3a8192a79)
- [Dev Deps] update `@ljharb/eslint-config`, `aud` [`3124ed3`](https://github.com/minimistjs/minimist/commit/3124ed3e46306301ebb3c834874ce0241555c2c4)
- [meta] add `safe-publish-latest` [`4b927de`](https://github.com/minimistjs/minimist/commit/4b927de696d561c636b4f43bf49d4597cb36d6d6)
- [Tests] add `aud` in `posttest` [`b32d9bd`](https://github.com/minimistjs/minimist/commit/b32d9bd0ab340f4e9f8c3a97ff2a4424f25fab8c)
- [meta] update repo URLs [`f9fdfc0`](https://github.com/minimistjs/minimist/commit/f9fdfc032c54884d9a9996a390c63cd0719bbe1a)
- [actions] Avoid 0.6 tests due to build failures [`ba92fe6`](https://github.com/minimistjs/minimist/commit/ba92fe6ebbdc0431cca9a2ea8f27beb492f5e4ec)
- [Dev Deps] update `tape` [`950eaa7`](https://github.com/minimistjs/minimist/commit/950eaa74f112e04d23e9c606c67472c46739b473)
- [Dev Deps] add missing `npmignore` dev dep [`3226afa`](https://github.com/minimistjs/minimist/commit/3226afaf09e9d127ca369742437fe6e88f752d6b)
- Merge tag 'v0.2.2' [`980d7ac`](https://github.com/minimistjs/minimist/commit/980d7ac61a0b4bd552711251ac107d506b23e41f)

## [v1.2.7](https://github.com/minimistjs/minimist/compare/v1.2.6...v1.2.7) - 2022-10-10

### Commits

- [meta] add `auto-changelog` [`0ebf4eb`](https://github.com/minimistjs/minimist/commit/0ebf4ebcd5f7787a5524d31a849ef41316b83c3c)
- [actions] add reusable workflows [`e115b63`](https://github.com/minimistjs/minimist/commit/e115b63fa9d3909f33b00a2db647ff79068388de)
- [eslint] add eslint; rules to enable later are warnings [`f58745b`](https://github.com/minimistjs/minimist/commit/f58745b9bb84348e1be72af7dbba5840c7c13013)
- [Dev Deps] switch from `covert` to `nyc` [`ab03356`](https://github.com/minimistjs/minimist/commit/ab033567b9c8b31117cb026dc7f1e592ce455c65)
- [readme] rename and add badges [`236f4a0`](https://github.com/minimistjs/minimist/commit/236f4a07e4ebe5ee44f1496ec6974991ab293ffd)
- [meta] create FUNDING.yml; add `funding` in package.json [`783a49b`](https://github.com/minimistjs/minimist/commit/783a49bfd47e8335d3098a8cac75662cf71eb32a)
- [meta] use `npmignore` to autogenerate an npmignore file [`f81ece6`](https://github.com/minimistjs/minimist/commit/f81ece6aaec2fa14e69ff4f1e0407a8c4e2635a2)
- Only apps should have lockfiles [`56cad44`](https://github.com/minimistjs/minimist/commit/56cad44c7f879b9bb5ec18fcc349308024a89bfc)
- [Dev Deps] update `covert`, `tape`; remove unnecessary `tap` [`49c5f9f`](https://github.com/minimistjs/minimist/commit/49c5f9fb7e6a92db9eb340cc679de92fb3aacded)
- [Tests] add `aud` in `posttest` [`228ae93`](https://github.com/minimistjs/minimist/commit/228ae938f3cd9db9dfd8bd7458b076a7b2aef280)
- [meta] add `safe-publish-latest` [`01fc23f`](https://github.com/minimistjs/minimist/commit/01fc23f5104f85c75059972e01dd33796ab529ff)
- [meta] update repo URLs [`6b164c7`](https://github.com/minimistjs/minimist/commit/6b164c7d68e0b6bf32f894699effdfb7c63041dd)

## [v1.2.6](https://github.com/minimistjs/minimist/compare/v1.2.5...v1.2.6) - 2022-03-21

### Commits

- test from prototype pollution PR [`bc8ecee`](https://github.com/minimistjs/minimist/commit/bc8ecee43875261f4f17eb20b1243d3ed15e70eb)
- isConstructorOrProto adapted from PR [`c2b9819`](https://github.com/minimistjs/minimist/commit/c2b981977fa834b223b408cfb860f933c9811e4d)
- security notice for additional prototype pollution issue [`ef88b93`](https://github.com/minimistjs/minimist/commit/ef88b9325f77b5ee643ccfc97e2ebda577e4c4e2)

## [v1.2.5](https://github.com/minimistjs/minimist/compare/v1.2.4...v1.2.5) - 2020-03-12

## [v1.2.4](https://github.com/minimistjs/minimist/compare/v1.2.3...v1.2.4) - 2020-03-11

### Commits

- security notice [`4cf1354`](https://github.com/minimistjs/minimist/commit/4cf1354839cb972e38496d35e12f806eea92c11f)
- additional test for constructor prototype pollution [`1043d21`](https://github.com/minimistjs/minimist/commit/1043d212c3caaf871966e710f52cfdf02f9eea4b)

## [v1.2.3](https://github.com/minimistjs/minimist/compare/v1.2.2...v1.2.3) - 2020-03-10

### Commits

- more failing proto pollution tests [`13c01a5`](https://github.com/minimistjs/minimist/commit/13c01a5327736903704984b7f65616b8476850cc)
- even more aggressive checks for protocol pollution [`38a4d1c`](https://github.com/minimistjs/minimist/commit/38a4d1caead72ef99e824bb420a2528eec03d9ab)

## [v1.2.2](https://github.com/minimistjs/minimist/compare/v1.2.1...v1.2.2) - 2020-03-10

### Commits

- failing test for protocol pollution [`0efed03`](https://github.com/minimistjs/minimist/commit/0efed0340ec8433638758f7ca0c77cb20a0bfbab)
- cleanup [`67d3722`](https://github.com/minimistjs/minimist/commit/67d3722413448d00a62963d2d30c34656a92d7e2)
- console.dir -&gt; console.log [`47acf72`](https://github.com/minimistjs/minimist/commit/47acf72c715a630bf9ea013867f47f1dd69dfc54)
- don't assign onto __proto__ [`63e7ed0`](https://github.com/minimistjs/minimist/commit/63e7ed05aa4b1889ec2f3b196426db4500cbda94)

## [v1.2.1](https://github.com/minimistjs/minimist/compare/v1.2.0...v1.2.1) - 2020-03-10

### Merged

- move the `opts['--']` example back where it belongs [`#63`](https://github.com/minimistjs/minimist/pull/63)

### Commits

- add test [`6be5dae`](https://github.com/minimistjs/minimist/commit/6be5dae35a32a987bcf4137fcd6c19c5200ee909)
- fix bad boolean regexp [`ac3fc79`](https://github.com/minimistjs/minimist/commit/ac3fc796e63b95128fdbdf67ea7fad71bd59aa76)

## [v1.2.0](https://github.com/minimistjs/minimist/compare/v1.1.3...v1.2.0) - 2015-08-24

### Commits

- failing -k=v short test [`63416b8`](https://github.com/minimistjs/minimist/commit/63416b8cd1d0d70e4714564cce465a36e4dd26d7)
- kv short fix [`6bbe145`](https://github.com/minimistjs/minimist/commit/6bbe14529166245e86424f220a2321442fe88dc3)
- failing kv short test [`f72ab7f`](https://github.com/minimistjs/minimist/commit/f72ab7f4572adc52902c9b6873cc969192f01b10)
- fixed kv test [`f5a48c3`](https://github.com/minimistjs/minimist/commit/f5a48c3e50e40ca54f00c8e84de4b4d6e9897fa8)
- enforce space between arg key and value [`86b321a`](https://github.com/minimistjs/minimist/commit/86b321affe648a8e016c095a4f0efa9d9074f502)

## [v1.1.3](https://github.com/minimistjs/minimist/compare/v1.1.2...v1.1.3) - 2015-08-06

### Commits

- add failing test - boolean alias array [`0fa3c5b`](https://github.com/minimistjs/minimist/commit/0fa3c5b3dd98551ddecf5392831b4c21211743fc)
- fix boolean values with multiple aliases [`9c0a6e7`](https://github.com/minimistjs/minimist/commit/9c0a6e7de25a273b11bbf9a7464f0bd833779795)

## [v1.1.2](https://github.com/minimistjs/minimist/compare/v1.1.1...v1.1.2) - 2015-07-22

### Commits

- Convert boolean arguments to boolean values [`8f3dc27`](https://github.com/minimistjs/minimist/commit/8f3dc27cf833f1d54671b6d0bcb55c2fe19672a9)
- use non-ancient npm, node 0.12 and iojs [`61ed1d0`](https://github.com/minimistjs/minimist/commit/61ed1d034b9ec7282764ce76f3992b1a0b4906ae)
- an older npm for 0.8 [`25cf778`](https://github.com/minimistjs/minimist/commit/25cf778b1220e7838a526832ad6972f75244054f)

## [v1.1.1](https://github.com/minimistjs/minimist/compare/v1.1.0...v1.1.1) - 2015-03-10

### Commits

- check that they type of a value is a boolean, not just that it is currently set to a boolean [`6863198`](https://github.com/minimistjs/minimist/commit/6863198e36139830ff1f20ffdceaddd93f2c1db9)
- upgrade tape, fix type issues from old tape version [`806712d`](https://github.com/minimistjs/minimist/commit/806712df91604ed02b8e39aa372b84aea659ee34)
- test for setting a boolean to a null default [`8c444fe`](https://github.com/minimistjs/minimist/commit/8c444fe89384ded7d441c120915ea60620b01dd3)
- if the previous value was a boolean, without an default (or with an alias) don't make an array either [`e5f419a`](https://github.com/minimistjs/minimist/commit/e5f419a3b5b3bc3f9e5ac71b7040621af70ed2dd)

## [v1.1.0](https://github.com/minimistjs/minimist/compare/v1.0.0...v1.1.0) - 2014-08-10

### Commits

- add support for handling "unknown" options not registered with the parser. [`6f3cc5d`](https://github.com/minimistjs/minimist/commit/6f3cc5d4e84524932a6ef2ce3592acc67cdd4383)
- reformat package.json [`02ed371`](https://github.com/minimistjs/minimist/commit/02ed37115194d3697ff358e8e25e5e66bab1d9f8)
- coverage script [`e5531ba`](https://github.com/minimistjs/minimist/commit/e5531ba0479da3b8138d3d8cac545d84ccb1c8df)
- extra fn to get 100% coverage again [`a6972da`](https://github.com/minimistjs/minimist/commit/a6972da89e56bf77642f8ec05a13b6558db93498)

## [v1.0.0](https://github.com/minimistjs/minimist/compare/v0.2.3...v1.0.0) - 2014-08-10

### Commits

- added stopEarly option [`471c7e4`](https://github.com/minimistjs/minimist/commit/471c7e4a7e910fc7ad8f9df850a186daf32c64e9)
- fix list [`fef6ae7`](https://github.com/minimistjs/minimist/commit/fef6ae79c38b9dc1c49569abb7cd04eb965eac5e)

## [v0.2.3](https://github.com/minimistjs/minimist/compare/v0.2.2...v0.2.3) - 2023-02-09

### Merged

- [Fix] Fix long option followed by single dash [`#17`](https://github.com/minimistjs/minimist/pull/17)
- [Tests] Remove duplicate test [`#12`](https://github.com/minimistjs/minimist/pull/12)
- [Fix] opt.string works with multiple aliases [`#10`](https://github.com/minimistjs/minimist/pull/10)

### Fixed

- [Fix] Fix long option followed by single dash (#17) [`#15`](https://github.com/minimistjs/minimist/issues/15)
- [Tests] Remove duplicate test (#12) [`#8`](https://github.com/minimistjs/minimist/issues/8)
- [Fix] opt.string works with multiple aliases (#10) [`#9`](https://github.com/minimistjs/minimist/issues/9)

### Commits

- [eslint] fix indentation and whitespace [`e5f5067`](https://github.com/minimistjs/minimist/commit/e5f5067259ceeaf0b098d14bec910f87e58708c7)
- [eslint] more cleanup [`36ac5d0`](https://github.com/minimistjs/minimist/commit/36ac5d0d95e4947d074e5737d94814034ca335d1)
- [eslint] fix indentation [`34b0f1c`](https://github.com/minimistjs/minimist/commit/34b0f1ccaa45183c3c4f06a91f9b405180a6f982)
- isConstructorOrProto adapted from PR [`ef9153f`](https://github.com/minimistjs/minimist/commit/ef9153fc52b6cea0744b2239921c5dcae4697f11)
- [Dev Deps] update `@ljharb/eslint-config`, `aud` [`098873c`](https://github.com/minimistjs/minimist/commit/098873c213cdb7c92e55ae1ef5aa1af3a8192a79)
- [Dev Deps] add missing `npmignore` dev dep [`3226afa`](https://github.com/minimistjs/minimist/commit/3226afaf09e9d127ca369742437fe6e88f752d6b)

## [v0.2.2](https://github.com/minimistjs/minimist/compare/v0.2.1...v0.2.2) - 2022-10-10

### Commits

- [meta] add `auto-changelog` [`73923d2`](https://github.com/minimistjs/minimist/commit/73923d223553fca08b1ba77e3fbc2a492862ae4c)
- [actions] add reusable workflows [`d80727d`](https://github.com/minimistjs/minimist/commit/d80727df77bfa9e631044d7f16368d8f09242c91)
- [eslint] add eslint; rules to enable later are warnings [`48bc06a`](https://github.com/minimistjs/minimist/commit/48bc06a1b41f00e9cdf183db34f7a51ba70e98d4)
- [readme] rename and add badges [`5df0fe4`](https://github.com/minimistjs/minimist/commit/5df0fe49211bd09a3636f8686a7cb3012c3e98f0)
- [Dev Deps] switch from `covert` to `nyc` [`a48b128`](https://github.com/minimistjs/minimist/commit/a48b128fdb8d427dfb20a15273f83e38d97bef07)
- [Dev Deps] update `covert`, `tape`; remove unnecessary `tap` [`f0fb958`](https://github.com/minimistjs/minimist/commit/f0fb958e9a1fe980cdffc436a211b0bda58f621b)
- [meta] create FUNDING.yml; add `funding` in package.json [`3639e0c`](https://github.com/minimistjs/minimist/commit/3639e0c819359a366387e425ab6eabf4c78d3caa)
- [meta] use `npmignore` to autogenerate an npmignore file [`be2e038`](https://github.com/minimistjs/minimist/commit/be2e038c342d8333b32f0fde67a0026b79c8150e)
- Only apps should have lockfiles [`282b570`](https://github.com/minimistjs/minimist/commit/282b570e7489d01b03f2d6d3dabf79cd3e5f84cf)
- [meta] add `safe-publish-latest` [`4b927de`](https://github.com/minimistjs/minimist/commit/4b927de696d561c636b4f43bf49d4597cb36d6d6)
- [Tests] add `aud` in `posttest` [`b32d9bd`](https://github.com/minimistjs/minimist/commit/b32d9bd0ab340f4e9f8c3a97ff2a4424f25fab8c)
- [meta] update repo URLs [`f9fdfc0`](https://github.com/minimistjs/minimist/commit/f9fdfc032c54884d9a9996a390c63cd0719bbe1a)

## [v0.2.1](https://github.com/minimistjs/minimist/compare/v0.2.0...v0.2.1) - 2020-03-12

## [v0.2.0](https://github.com/minimistjs/minimist/compare/v0.1.0...v0.2.0) - 2014-06-19

### Commits

- support all-boolean mode [`450a97f`](https://github.com/minimistjs/minimist/commit/450a97f6e2bc85c7a4a13185c19a818d9a5ebe69)

## [v0.1.0](https://github.com/minimistjs/minimist/compare/v0.0.10...v0.1.0) - 2014-05-12

### Commits

- Provide a mechanism to segregate -- arguments [`ce4a1e6`](https://github.com/minimistjs/minimist/commit/ce4a1e63a7e8d5ab88d2a3768adefa6af98a445a)
- documented argv['--'] [`14db0e6`](https://github.com/minimistjs/minimist/commit/14db0e6dbc6d2b9e472adaa54dad7004b364634f)
- Adding a test-case for notFlags segregation [`715c1e3`](https://github.com/minimistjs/minimist/commit/715c1e3714be223f998f6c537af6b505f0236c16)

## [v0.0.10](https://github.com/minimistjs/minimist/compare/v0.0.9...v0.0.10) - 2014-05-11

### Commits

- dedicated boolean test [`46e448f`](https://github.com/minimistjs/minimist/commit/46e448f9f513cfeb2bcc8b688b9b47ba1e515c2b)
- dedicated num test [`9bf2d36`](https://github.com/minimistjs/minimist/commit/9bf2d36f1d3b8795be90b8f7de0a937f098aa394)
- aliased values treated as strings [`1ab743b`](https://github.com/minimistjs/minimist/commit/1ab743bad4484d69f1259bed42f9531de01119de)
- cover the case of already numbers, at 100% coverage [`b2bb044`](https://github.com/minimistjs/minimist/commit/b2bb04436599d77a2ce029e8e555e25b3aa55d13)
- another test for higher coverage [`3662624`](https://github.com/minimistjs/minimist/commit/3662624be976d5489d486a856849c048d13be903)

## [v0.0.9](https://github.com/minimistjs/minimist/compare/v0.0.8...v0.0.9) - 2014-05-08

### Commits

- Eliminate `longest` fn. [`824f642`](https://github.com/minimistjs/minimist/commit/824f642038d1b02ede68b6261d1d65163390929a)

## [v0.0.8](https://github.com/minimistjs/minimist/compare/v0.0.7...v0.0.8) - 2014-02-20

### Commits

- return '' if flag is string and empty [`fa63ed4`](https://github.com/minimistjs/minimist/commit/fa63ed4651a4ef4eefddce34188e0d98d745a263)
- handle joined single letters [`66c248f`](https://github.com/minimistjs/minimist/commit/66c248f0241d4d421d193b022e9e365f11178534)

## [v0.0.7](https://github.com/minimistjs/minimist/compare/v0.0.6...v0.0.7) - 2014-02-08

### Commits

- another swap of .test for .match [`d1da408`](https://github.com/minimistjs/minimist/commit/d1da40819acbe846d89a5c02721211e3c1260dde)

## [v0.0.6](https://github.com/minimistjs/minimist/compare/v0.0.5...v0.0.6) - 2014-02-08

### Commits

- use .test() instead of .match() to not crash on non-string values in the arguments array [`7e0d1ad`](https://github.com/minimistjs/minimist/commit/7e0d1add8c9e5b9b20a4d3d0f9a94d824c578da1)

## [v0.0.5](https://github.com/minimistjs/minimist/compare/v0.0.4...v0.0.5) - 2013-09-18

### Commits

- Improve '--' handling. [`b11822c`](https://github.com/minimistjs/minimist/commit/b11822c09cc9d2460f30384d12afc0b953c037a4)

## [v0.0.4](https://github.com/minimistjs/minimist/compare/v0.0.3...v0.0.4) - 2013-09-17

## [v0.0.3](https://github.com/minimistjs/minimist/compare/v0.0.2...v0.0.3) - 2013-09-12

### Commits

- failing test for single dash preceeding a double dash [`b465514`](https://github.com/minimistjs/minimist/commit/b465514b82c9ae28972d714facd951deb2ad762b)
- fix for the dot test [`6a095f1`](https://github.com/minimistjs/minimist/commit/6a095f1d364c8fab2d6753d2291a0649315d297a)

## [v0.0.2](https://github.com/minimistjs/minimist/compare/v0.0.1...v0.0.2) - 2013-08-28

### Commits

- allow dotted aliases & defaults [`321c33e`](https://github.com/minimistjs/minimist/commit/321c33e755485faaeb44eeb1c05d33b2e0a5a7c4)
- use a better version of ff [`e40f611`](https://github.com/minimistjs/minimist/commit/e40f61114cf7be6f7947f7b3eed345853a67dbbb)

## [v0.0.1](https://github.com/minimistjs/minimist/compare/v0.0.0...v0.0.1) - 2013-06-25

### Commits

- remove trailing commas [`6ff0fa0`](https://github.com/minimistjs/minimist/commit/6ff0fa055064f15dbe06d50b89d5173a6796e1db)

## v0.0.0 - 2013-06-25

### Commits

- half of the parse test ported [`3079326`](https://github.com/minimistjs/minimist/commit/307932601325087de6cf94188eb798ffc4f3088a)
- stripped down code and a passing test from optimist [`7cced88`](https://github.com/minimistjs/minimist/commit/7cced88d82e399d1a03ed23eb667f04d3f320d10)
- ported parse tests completely over [`9448754`](https://github.com/minimistjs/minimist/commit/944875452e0820df6830b1408c26a0f7d3e1db04)
- docs, package.json [`a5bf46a`](https://github.com/minimistjs/minimist/commit/a5bf46ac9bb3bd114a9c340276c62c1091e538d5)
- move more short tests into short.js [`503edb5`](https://github.com/minimistjs/minimist/commit/503edb5c41d89c0d40831ee517154fc13b0f18b9)
- default bool test was wrong, not the code [`1b9f5db`](https://github.com/minimistjs/minimist/commit/1b9f5db4741b49962846081b68518de824992097)
- passing long tests ripped out of parse.js [`7972c4a`](https://github.com/minimistjs/minimist/commit/7972c4aff1f4803079e1668006658e2a761a0428)
- badges [`84c0370`](https://github.com/minimistjs/minimist/commit/84c037063664d42878aace715fe6572ce01b6f3b)
- all the tests now ported, some failures [`64239ed`](https://github.com/minimistjs/minimist/commit/64239edfe92c711c4eb0da254fcdfad2a5fdb605)
- failing short test [`f8a5341`](https://github.com/minimistjs/minimist/commit/f8a534112dd1138d2fad722def56a848480c446f)
- fixed the numeric test [`6b034f3`](https://github.com/minimistjs/minimist/commit/6b034f37c79342c60083ed97fd222e16928aac51)


---

# minimist <sup>[![Version Badge][npm-version-svg]][package-url]</sup>

[![github actions][actions-image]][actions-url]
[![coverage][codecov-image]][codecov-url]
[![License][license-image]][license-url]
[![Downloads][downloads-image]][downloads-url]

[![npm badge][npm-badge-png]][package-url]

parse argument options

This module is the guts of optimist's argument parser without all the
fanciful decoration.

# example

``` js
var argv = require('minimist')(process.argv.slice(2));
console.log(argv);
```

```
$ node example/parse.js -a beep -b boop
{ _: [], a: 'beep', b: 'boop' }
```

```
$ node example/parse.js -x 3 -y 4 -n5 -abc --beep=boop foo bar baz
{
	_: ['foo', 'bar', 'baz'],
	x: 3,
	y: 4,
	n: 5,
	a: true,
	b: true,
	c: true,
	beep: 'boop'
}
```

# security

Previous versions had a prototype pollution bug that could cause privilege
escalation in some circumstances when handling untrusted user input.

Please use version 1.2.6 or later:

* https://security.snyk.io/vuln/SNYK-JS-MINIMIST-2429795 (version <=1.2.5)
* https://snyk.io/vuln/SNYK-JS-MINIMIST-559764 (version <=1.2.3)

# methods

``` js
var parseArgs = require('minimist')
```

## var argv = parseArgs(args, opts={})

Return an argument object `argv` populated with the array arguments from `args`.

`argv._` contains all the arguments that didn't have an option associated with
them.

Numeric-looking arguments will be returned as numbers unless `opts.string` or
`opts.boolean` is set for that argument name.

Any arguments after `'--'` will not be parsed and will end up in `argv._`.

options can be:

* `opts.string` - a string or array of strings argument names to always treat as
strings
* `opts.boolean` - a boolean, string or array of strings to always treat as
booleans. if `true` will treat all double hyphenated arguments without equal signs
as boolean (e.g. affects `--foo`, not `-f` or `--foo=bar`)
* `opts.alias` - an object mapping string names to strings or arrays of string
argument names to use as aliases
* `opts.default` - an object mapping string argument names to default values
* `opts.stopEarly` - when true, populate `argv._` with everything after the
first non-option
* `opts['--']` - when true, populate `argv._` with everything before the `--`
and `argv['--']` with everything after the `--`. Here's an example:

  ```
  > require('./')('one two three -- four five --six'.split(' '), { '--': true })
  {
    _: ['one', 'two', 'three'],
    '--': ['four', 'five', '--six']
  }
  ```

  Note that with `opts['--']` set, parsing for arguments still stops after the
  `--`.

* `opts.unknown` - a function which is invoked with a command line parameter not
defined in the `opts` configuration object. If the function returns `false`, the
unknown option is not added to `argv`.

# install

With [npm](https://npmjs.org) do:

```
npm install minimist
```

# license

MIT

[package-url]: https://npmjs.org/package/minimist
[npm-version-svg]: https://versionbadg.es/minimistjs/minimist.svg
[npm-badge-png]: https://nodei.co/npm/minimist.png?downloads=true&stars=true
[license-image]: https://img.shields.io/npm/l/minimist.svg
[license-url]: LICENSE
[downloads-image]: https://img.shields.io/npm/dm/minimist.svg
[downloads-url]: https://npm-stat.com/charts.html?package=minimist
[codecov-image]: https://codecov.io/gh/minimistjs/minimist/branch/main/graphs/badge.svg
[codecov-url]: https://app.codecov.io/gh/minimistjs/minimist/
[actions-image]: https://img.shields.io/endpoint?url=https://github-actions-badge-u3jn4tfpocch.runkit.sh/minimistjs/minimist
[actions-url]: https://github.com/minimistjs/minimist/actions


---

<div align="center">
  <img src="logo.png" alt="mrmime" width="320" />
</div>

<div align="center">
  <a href="https://npmjs.org/package/mrmime">
    <img src="https://badgen.now.sh/npm/v/mrmime" alt="version" />
  </a>
  <a href="https://github.com/lukeed/mrmime/actions">
    <img src="https://github.com/lukeed/mrmime/workflows/CI/badge.svg" alt="CI" />
  </a>
  <a href="https://licenses.dev/npm/mrmime">
    <img src="https://licenses.dev/b/npm/mrmime" alt="licenses" />
  </a>
  <a href="https://npmjs.org/package/mrmime">
    <img src="https://badgen.now.sh/npm/dm/mrmime" alt="downloads" />
  </a>
  <a href="https://packagephobia.now.sh/result?p=mrmime">
    <img src="https://packagephobia.now.sh/badge?p=mrmime" alt="install size" />
  </a>
</div>

<div align="center">
  A tiny (2.8kB) and fast utility for getting a MIME type from an extension or filename
</div>


## Features

* Lightweight – 2.8kB gzip<br>
  _Only includes standard mime types; all experimental and vendor-specific mimetypes removed._

* [Performant](#benchmarks)<br>
  _All lookups are O(1) with minimal processing._

* Comprehensive Dictionary<br>
  _Generated from [`mime-db`](https://github.com/jshttp/mime-db), which aggregates the IANA, NGINX, and Apache datasets._

* Customizable<br>
  _Exposes the `mimes` dictionary for easy additions or overrides._

* Supports Native ESM and [Deno](https://deno.land/x/mrmime)<br>
  _Ships with CommonJS and ESM support!_


## Install

```
$ npm install --save mrmime
```


## Usage

```js
import { lookup, mimes } from 'mrmime';

// Get a MIME type
// ---
lookup('txt'); //=> "text/plain"
lookup('.txt'); //=> "text/plain"
lookup('a.txt'); //=> "text/plain"

// Unknown extension
// ---
lookup('.xyz'); //=> undefined

// Add extension to dictionary
// ---
mimes['xyz'] = 'hello/world';
lookup('xyz'); //=> "hello/world"
```


## API

### lookup(input)
Returns: `string` or `undefined`

#### input
Type: `string`

The extension or filename to lookup.

> **Important:**
>   * Any `input` value is cast to string, lowercased, and trimmed.
>   * If a filename or filepath is provided, only the extension will be used.


## Benchmarks

> Running on Node v16.8.0

```
Load times:
  mrmime     0.963ms
  mime/lite  3.281ms
  mime       6.751ms

Benchmark :: plain ("ext")
  mime          x 598,849 ops/sec ±0.28% (94 runs sampled)
  mime/lite     x 536,643 ops/sec ±0.11% (97 runs sampled)
  mrmime        x 835,885 ops/sec ±0.20% (97 runs sampled)

Benchmark :: leading (".ext")
  mime          x 368,656 ops/sec ±0.19% (99 runs sampled)
  mime/lite     x 368,318 ops/sec ±0.13% (97 runs sampled)
  mrmime        x 533,643 ops/sec ±0.10% (96 runs sampled)

Benchmark :: filename ("file.ext")
  mime          x 326,907 ops/sec ±0.17% (95 runs sampled)
  mime/lite     x 327,479 ops/sec ±0.12% (98 runs sampled)
  mrmime        x 512,823 ops/sec ±0.12% (99 runs sampled)
```


## Credits

Of course, a thank-you to [`mime`](https://github.com/broofa/mime) serving the community all these years & for being a all-encompassing MIME type library. I've only ever needed lookup/`getType` functionality – and now ESM support – so `mrmime` can only ever support 1/3 of what `mime` offers, at best.

This would not be possible without the team behind [`mime-db`](https://github.com/jshttp/mime-db), who have painstakingly maintained an amazing database for 7+ years.

Artwork created by [mintinol](https://www.deviantart.com/mintinol), which I found [here](https://www.deviantart.com/mintinol/art/Mr-Mime-373927920).

Finally, thanks to [Tim Branyen](https://github.com/tbranyen) for donating the package name :)


## License

MIT © [Luke Edwards](https://lukeed.com)


---

The MIT License (MIT)

Copyright (c) 2016 Zeit, Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# ms

[![Build Status](https://travis-ci.org/zeit/ms.svg?branch=master)](https://travis-ci.org/zeit/ms)
[![Join the community on Spectrum](https://withspectrum.github.io/badge/badge.svg)](https://spectrum.chat/zeit)

Use this package to easily convert various time formats to milliseconds.

## Examples

```js
ms('2 days')  // 172800000
ms('1d')      // 86400000
ms('10h')     // 36000000
ms('2.5 hrs') // 9000000
ms('2h')      // 7200000
ms('1m')      // 60000
ms('5s')      // 5000
ms('1y')      // 31557600000
ms('100')     // 100
ms('-3 days') // -259200000
ms('-1h')     // -3600000
ms('-200')    // -200
```

### Convert from Milliseconds

```js
ms(60000)             // "1m"
ms(2 * 60000)         // "2m"
ms(-3 * 60000)        // "-3m"
ms(ms('10 hours'))    // "10h"
```

### Time Format Written-Out

```js
ms(60000, { long: true })             // "1 minute"
ms(2 * 60000, { long: true })         // "2 minutes"
ms(-3 * 60000, { long: true })        // "-3 minutes"
ms(ms('10 hours'), { long: true })    // "10 hours"
```

## Features

- Works both in [Node.js](https://nodejs.org) and in the browser
- If a number is supplied to `ms`, a string with a unit is returned
- If a string that contains the number is supplied, it returns it as a number (e.g.: it returns `100` for `'100'`)
- If you pass a string with a number and a valid unit, the number of equivalent milliseconds is returned

## Related Packages

- [ms.macro](https://github.com/knpwrs/ms.macro) - Run `ms` as a macro at build-time.

## Caught a Bug?

1. [Fork](https://help.github.com/articles/fork-a-repo/) this repository to your own GitHub account and then [clone](https://help.github.com/articles/cloning-a-repository/) it to your local device
2. Link the package to the global module directory: `npm link`
3. Within the module you want to test your local development instance of ms, just link it to the dependencies: `npm link ms`. Instead of the default one from npm, Node.js will now use your clone of ms!

As always, you can run the tests using: `npm test`


---

# multicast-dns

Low level multicast-dns implementation in pure javascript

```
npm install multicast-dns
```

[![build status](http://img.shields.io/travis/mafintosh/multicast-dns.svg?style=flat)](http://travis-ci.org/mafintosh/multicast-dns)

## Usage

``` js
var mdns = require('multicast-dns')()

mdns.on('response', function(response) {
  console.log('got a response packet:', response)
})

mdns.on('query', function(query) {
  console.log('got a query packet:', query)
})

// lets query for an A record for 'brunhilde.local'
mdns.query({
  questions:[{
    name: 'brunhilde.local',
    type: 'A'
  }]
})
```

Running the above (change `brunhilde.local` to `your-own-hostname.local`) will print an echo of the query packet first

``` js
got a query packet: { type: 'query',
  questions: [ { name: 'brunhilde.local', type: 'A', class: 1 } ],
  answers: [],
  authorities: [],
  additionals: [] }
```

And then a response packet

``` js
got a response packet: { type: 'response',
  questions: [],
  answers:
   [ { name: 'brunhilde.local',
       type: 'A',
       class: 'IN',
       ttl: 120,
       flush: true,
       data: '192.168.1.5' } ],
  authorities: [],
  additionals:
   [ { name: 'brunhilde.local',
       type: 'A',
       class: 'IN',
       ttl: 120,
       flush: true,
       data: '192.168.1.5' },
     { name: 'brunhilde.local',
       type: 'AAAA',
       class: 'IN',
       ttl: 120,
       flush: true,
       data: 'fe80::5ef9:38ff:fe8c:ceaa' } ] }
```


# CLI

```
npm install -g multicast-dns
```

```
multicast-dns brunhilde.local
> 192.168.1.1
```

# API

A packet has the following format

``` js
{
  questions: [{
    name: 'brunhilde.local',
    type: 'A'
  }],
  answers: [{
    name: 'brunhilde.local',
    type: 'A',
    ttl: seconds,
    data: (record type specific data)
  }],
  additionals: [
    (same format as answers)
  ],
  authorities: [
    (same format as answers)
  ]
}
```

Currently data from `SRV`, `A`, `PTR`, `TXT`, `AAAA` and `HINFO` records is passed

#### `mdns = multicastdns([options])`

Creates a new `mdns` instance. Options can contain the following

``` js
{
  multicast: true // use udp multicasting
  interface: '192.168.0.2' // explicitly specify a network interface. defaults to all
  port: 5353, // set the udp port
  ip: '224.0.0.251', // set the udp ip
  ttl: 255, // set the multicast ttl
  loopback: true, // receive your own packets
  reuseAddr: true // set the reuseAddr option when creating the socket (requires node >=0.11.13)
}
```

#### `mdns.on('query', (packet, rinfo))`

Emitted when a query packet is received.

``` js
mdns.on('query', function(query) {
  if (query.questions[0] && query.questions[0].name === 'brunhilde.local') {
    mdns.respond(someResponse) // see below
  }
})
```

#### `mdns.on('response', (packet, rinfo))`

Emitted when a response packet is received.

The response might not be a response to a query you send as this
is the result of someone multicasting a response.

#### `mdns.query(packet, [cb])`

Send a dns query. The callback will be called when the packet was sent.

The following shorthands are equivalent

``` js
mdns.query('brunhilde.local', 'A')
mdns.query([{name:'brunhilde.local', type:'A'}])
mdns.query({
  questions: [{name:'brunhilde.local', type:'A'}]
})
```

#### `mdns.respond(packet, [cb])`

Send a dns response. The callback will be called when the packet was sent.

``` js
// reply with a SRV and a A record as an answer
mdns.respond({
  answers: [{
    name: 'my-service',
    type: 'SRV',
    data: {
      port: 9999,
      weight: 0,
      priority: 10,
      target: 'my-service.example.com'
    }
  }, {
    name: 'brunhilde.local',
    type: 'A',
    ttl: 300,
    data: '192.168.1.5'
  }]
})
```

The following shorthands are equivalent

``` js
mdns.respond([{name:'brunhilde.local', type:'A', data:'192.158.1.5'}])
mdns.respond({
  answers: [{name:'brunhilde.local', type:'A', data:'192.158.1.5'}]
})
```

#### `mdns.destroy()`

Destroy the mdns instance. Closes the udp socket.

# Development

To start hacking on this module you can use this example to get started

```
git clone git://github.com/mafintosh/multicast-dns.git
npm install
node example.js
node cli.js $(hostname).local
```

## License

MIT


---

# Nano ID

<img src="https://ai.github.io/nanoid/logo.svg" align="right"
     alt="Nano ID logo by Anton Lovchikov" width="180" height="94">

**English** | [Русский](./README.ru.md) | [简体中文](./README.zh-CN.md) | [Bahasa Indonesia](./README.id-ID.md)

A tiny, secure, URL-friendly, unique string ID generator for JavaScript.

> “An amazing level of senseless perfectionism,
> which is simply impossible not to respect.”

* **Small.** 130 bytes (minified and gzipped). No dependencies.
  [Size Limit] controls the size.
* **Fast.** It is 2 times faster than UUID.
* **Safe.** It uses hardware random generator. Can be used in clusters.
* **Short IDs.** It uses a larger alphabet than UUID (`A-Za-z0-9_-`).
  So ID size was reduced from 36 to 21 symbols.
* **Portable.** Nano ID was ported
  to [20 programming languages](#other-programming-languages).

```js
import { nanoid } from 'nanoid'
model.id = nanoid() //=> "V1StGXR8_Z5jdHi6B-myT"
```

Supports modern browsers, IE [with Babel], Node.js and React Native.

[online tool]: https://gitpod.io/#https://github.com/ai/nanoid/
[with Babel]:  https://developer.epages.com/blog/coding/how-to-transpile-node-modules-with-babel-and-webpack-in-a-monorepo/
[Size Limit]:  https://github.com/ai/size-limit

<a href="https://evilmartians.com/?utm_source=nanoid">
  <img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg"
       alt="Sponsored by Evil Martians" width="236" height="54">
</a>

## Docs
Read full docs **[here](https://github.com/ai/nanoid#readme)**.


---

unreleased
==================

  * Added an option preferred encodings array #59

0.6.3 / 2022-01-22
==================

  * Revert "Lazy-load modules from main entry point"

0.6.2 / 2019-04-29
==================

  * Fix sorting charset, encoding, and language with extra parameters

0.6.1 / 2016-05-02
==================

  * perf: improve `Accept` parsing speed
  * perf: improve `Accept-Charset` parsing speed
  * perf: improve `Accept-Encoding` parsing speed
  * perf: improve `Accept-Language` parsing speed

0.6.0 / 2015-09-29
==================

  * Fix including type extensions in parameters in `Accept` parsing
  * Fix parsing `Accept` parameters with quoted equals
  * Fix parsing `Accept` parameters with quoted semicolons
  * Lazy-load modules from main entry point
  * perf: delay type concatenation until needed
  * perf: enable strict mode
  * perf: hoist regular expressions
  * perf: remove closures getting spec properties
  * perf: remove a closure from media type parsing
  * perf: remove property delete from media type parsing

0.5.3 / 2015-05-10
==================

  * Fix media type parameter matching to be case-insensitive

0.5.2 / 2015-05-06
==================

  * Fix comparing media types with quoted values
  * Fix splitting media types with quoted commas

0.5.1 / 2015-02-14
==================

  * Fix preference sorting to be stable for long acceptable lists

0.5.0 / 2014-12-18
==================

  * Fix list return order when large accepted list
  * Fix missing identity encoding when q=0 exists
  * Remove dynamic building of Negotiator class

0.4.9 / 2014-10-14
==================

  * Fix error when media type has invalid parameter

0.4.8 / 2014-09-28
==================

  * Fix all negotiations to be case-insensitive
  * Stable sort preferences of same quality according to client order
  * Support Node.js 0.6

0.4.7 / 2014-06-24
==================

  * Handle invalid provided languages
  * Handle invalid provided media types

0.4.6 / 2014-06-11
==================

  *  Order by specificity when quality is the same

0.4.5 / 2014-05-29
==================

  * Fix regression in empty header handling

0.4.4 / 2014-05-29
==================

  * Fix behaviors when headers are not present

0.4.3 / 2014-04-16
==================

  * Handle slashes on media params correctly

0.4.2 / 2014-02-28
==================

  * Fix media type sorting
  * Handle media types params strictly

0.4.1 / 2014-01-16
==================

  * Use most specific matches

0.4.0 / 2014-01-09
==================

  * Remove preferred prefix from methods


---

# negotiator

[![NPM Version][npm-image]][npm-url]
[![NPM Downloads][downloads-image]][downloads-url]
[![Node.js Version][node-version-image]][node-version-url]
[![Build Status][github-actions-ci-image]][github-actions-ci-url]
[![Test Coverage][coveralls-image]][coveralls-url]

An HTTP content negotiator for Node.js

## Installation

```sh
$ npm install negotiator
```

## API

```js
var Negotiator = require('negotiator')
```

### Accept Negotiation

```js
availableMediaTypes = ['text/html', 'text/plain', 'application/json']

// The negotiator constructor receives a request object
negotiator = new Negotiator(request)

// Let's say Accept header is 'text/html, application/*;q=0.2, image/jpeg;q=0.8'

negotiator.mediaTypes()
// -> ['text/html', 'image/jpeg', 'application/*']

negotiator.mediaTypes(availableMediaTypes)
// -> ['text/html', 'application/json']

negotiator.mediaType(availableMediaTypes)
// -> 'text/html'
```

You can check a working example at `examples/accept.js`.

#### Methods

##### mediaType()

Returns the most preferred media type from the client.

##### mediaType(availableMediaType)

Returns the most preferred media type from a list of available media types.

##### mediaTypes()

Returns an array of preferred media types ordered by the client preference.

##### mediaTypes(availableMediaTypes)

Returns an array of preferred media types ordered by priority from a list of
available media types.

### Accept-Language Negotiation

```js
negotiator = new Negotiator(request)

availableLanguages = ['en', 'es', 'fr']

// Let's say Accept-Language header is 'en;q=0.8, es, pt'

negotiator.languages()
// -> ['es', 'pt', 'en']

negotiator.languages(availableLanguages)
// -> ['es', 'en']

language = negotiator.language(availableLanguages)
// -> 'es'
```

You can check a working example at `examples/language.js`.

#### Methods

##### language()

Returns the most preferred language from the client.

##### language(availableLanguages)

Returns the most preferred language from a list of available languages.

##### languages()

Returns an array of preferred languages ordered by the client preference.

##### languages(availableLanguages)

Returns an array of preferred languages ordered by priority from a list of
available languages.

### Accept-Charset Negotiation

```js
availableCharsets = ['utf-8', 'iso-8859-1', 'iso-8859-5']

negotiator = new Negotiator(request)

// Let's say Accept-Charset header is 'utf-8, iso-8859-1;q=0.8, utf-7;q=0.2'

negotiator.charsets()
// -> ['utf-8', 'iso-8859-1', 'utf-7']

negotiator.charsets(availableCharsets)
// -> ['utf-8', 'iso-8859-1']

negotiator.charset(availableCharsets)
// -> 'utf-8'
```

You can check a working example at `examples/charset.js`.

#### Methods

##### charset()

Returns the most preferred charset from the client.

##### charset(availableCharsets)

Returns the most preferred charset from a list of available charsets.

##### charsets()

Returns an array of preferred charsets ordered by the client preference.

##### charsets(availableCharsets)

Returns an array of preferred charsets ordered by priority from a list of
available charsets.

### Accept-Encoding Negotiation

```js
availableEncodings = ['identity', 'gzip']

negotiator = new Negotiator(request)

// Let's say Accept-Encoding header is 'gzip, compress;q=0.2, identity;q=0.5'

negotiator.encodings()
// -> ['gzip', 'identity', 'compress']

negotiator.encodings(availableEncodings)
// -> ['gzip', 'identity']

negotiator.encoding(availableEncodings)
// -> 'gzip'
```

You can check a working example at `examples/encoding.js`.

#### Methods

##### encoding()

Returns the most preferred encoding from the client.

##### encoding(availableEncodings)

Returns the most preferred encoding from a list of available encodings.

##### encoding(availableEncodings, preferred)

Returns the most preferred encoding from a list of available encodings, while prioritizing based on `preferred` array between same-quality encodings.

##### encodings()

Returns an array of preferred encodings ordered by the client preference.

##### encodings(availableEncodings)

Returns an array of preferred encodings ordered by priority from a list of
available encodings.

##### encodings(availableEncodings, preferred)

Returns an array of preferred encodings ordered by priority from a list of
available encodings, while prioritizing based on `preferred` array between same-quality encodings.

## See Also

The [accepts](https://npmjs.org/package/accepts#readme) module builds on
this module and provides an alternative interface, mime type validation,
and more.

## License

[MIT](LICENSE)

[npm-image]: https://img.shields.io/npm/v/negotiator.svg
[npm-url]: https://npmjs.org/package/negotiator
[node-version-image]: https://img.shields.io/node/v/negotiator.svg
[node-version-url]: https://nodejs.org/en/download/
[coveralls-image]: https://img.shields.io/coveralls/jshttp/negotiator/master.svg
[coveralls-url]: https://coveralls.io/r/jshttp/negotiator?branch=master
[downloads-image]: https://img.shields.io/npm/dm/negotiator.svg
[downloads-url]: https://npmjs.org/package/negotiator
[github-actions-ci-image]: https://img.shields.io/github/workflow/status/jshttp/negotiator/ci/master?label=ci
[github-actions-ci-url]: https://github.com/jshttp/negotiator/actions/workflows/ci.yml


---

<h1 align="center">Neo-Async</h1>

<p align="center">
  <img src="https://raw.githubusercontent.com/wiki/suguru03/neo-async/images/neo_async_v2.png" width="250px" />
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/neo-async"><img alt="npm" src="https://img.shields.io/npm/v/neo-async.svg"></a>
  <a href="https://travis-ci.org/suguru03/neo-async"><img alt="Travis Status" src="https://img.shields.io/travis/suguru03/neo-async.svg"></a>
  <a href="https://codecov.io/gh/suguru03/neo-async"><img alt="Coverage Status" src="https://img.shields.io/codecov/c/github/suguru03/neo-async/master.svg"></a>
  <a href="https://www.npmjs.com/package/neo-async"><img alt="download" src="https://img.shields.io/npm/dm/neo-async.svg"></a>
  <a href="https://lgtm.com/projects/g/suguru03/neo-async/context:javascript"><img src="https://img.shields.io/lgtm/grade/javascript/g/suguru03/neo-async.svg?logo=lgtm&logoWidth=18" alt="Code Quality: Javascript" height="18"></a>
  <a href="https://lgtm.com/projects/g/suguru03/neo-async/alerts"><img src="https://img.shields.io/lgtm/alerts/g/suguru03/neo-async.svg?logo=lgtm&logoWidth=18" alt="Total Alerts" height="18"></a>
  <a href="https://app.fossa.io/projects/git%2Bgithub.com%2Fsuguru03%2Fneo-async?ref=badge_shield"><img src="https://app.fossa.io/api/projects/git%2Bgithub.com%2Fsuguru03%2Fneo-async.svg?type=shield" alt="FOSSA" height="18"></a>
</p>

Neo-Async is thought to be used as a drop-in replacement for [Async](https://github.com/caolan/async), it almost fully covers its functionality and runs [faster](#benchmark).

Benchmark is [here](#benchmark)!

Bluebird's benchmark is [here](https://github.com/suguru03/bluebird/tree/aigle/benchmark)!

## Code Coverage
![coverage](https://raw.githubusercontent.com/wiki/suguru03/neo-async/images/coverage.png)

## Installation

### In a browser
```html
<script src="async.min.js"></script>
```

### In an AMD loader
```js
require(['async'], function(async) {});
```

### Promise and async/await

I recommend to use [`Aigle`](https://github.com/suguru03/aigle).

It is optimized for Promise handling and has almost the same functionality as `neo-async`.

### Node.js

#### standard

```bash
$ npm install neo-async
```
```js
var async = require('neo-async');
```

#### replacement
```bash
$ npm install neo-async
$ ln -s ./node_modules/neo-async ./node_modules/async
```
```js
var async = require('async');
```

### Bower

```bash
bower install neo-async
```

## Feature

[JSDoc](http://suguru03.github.io/neo-async/doc/async.html)

\* not in Async

### Collections

- [`each`](http://suguru03.github.io/neo-async/doc/async.each.html)
- [`eachSeries`](http://suguru03.github.io/neo-async/doc/async.eachSeries.html)
- [`eachLimit`](http://suguru03.github.io/neo-async/doc/async.eachLimit.html)
- [`forEach`](http://suguru03.github.io/neo-async/doc/async.each.html) -> [`each`](http://suguru03.github.io/neo-async/doc/async.each.html)
- [`forEachSeries`](http://suguru03.github.io/neo-async/doc/async.eachSeries.html) -> [`eachSeries`](http://suguru03.github.io/neo-async/doc/async.eachSeries.html)
- [`forEachLimit`](http://suguru03.github.io/neo-async/doc/async.eachLimit.html) -> [`eachLimit`](http://suguru03.github.io/neo-async/doc/async.eachLimit.html)
- [`eachOf`](http://suguru03.github.io/neo-async/doc/async.each.html) -> [`each`](http://suguru03.github.io/neo-async/doc/async.each.html)
- [`eachOfSeries`](http://suguru03.github.io/neo-async/doc/async.eachSeries.html) -> [`eachSeries`](http://suguru03.github.io/neo-async/doc/async.eachSeries.html)
- [`eachOfLimit`](http://suguru03.github.io/neo-async/doc/async.eachLimit.html) -> [`eachLimit`](http://suguru03.github.io/neo-async/doc/async.eachLimit.html)
- [`forEachOf`](http://suguru03.github.io/neo-async/doc/async.each.html) -> [`each`](http://suguru03.github.io/neo-async/doc/async.each.html)
- [`forEachOfSeries`](http://suguru03.github.io/neo-async/doc/async.eachSeries.html) -> [`eachSeries`](http://suguru03.github.io/neo-async/doc/async.eachSeries.html)
- [`eachOfLimit`](http://suguru03.github.io/neo-async/doc/async.eachLimit.html) -> [`forEachLimit`](http://suguru03.github.io/neo-async/doc/async.eachLimit.html)
- [`map`](http://suguru03.github.io/neo-async/doc/async.map.html)
- [`mapSeries`](http://suguru03.github.io/neo-async/doc/async.mapSeries.html)
- [`mapLimit`](http://suguru03.github.io/neo-async/doc/async.mapLimit.html)
- [`mapValues`](http://suguru03.github.io/neo-async/doc/async.mapValues.html)
- [`mapValuesSeries`](http://suguru03.github.io/neo-async/doc/async.mapValuesSeries.html)
- [`mapValuesLimit`](http://suguru03.github.io/neo-async/doc/async.mapValuesLimit.html)
- [`filter`](http://suguru03.github.io/neo-async/doc/async.filter.html)
- [`filterSeries`](http://suguru03.github.io/neo-async/doc/async.filterSeries.html)
- [`filterLimit`](http://suguru03.github.io/neo-async/doc/async.filterLimit.html)
- [`select`](http://suguru03.github.io/neo-async/doc/async.filter.html) -> [`filter`](http://suguru03.github.io/neo-async/doc/async.filter.html)
- [`selectSeries`](http://suguru03.github.io/neo-async/doc/async.filterSeries.html) -> [`filterSeries`](http://suguru03.github.io/neo-async/doc/async.filterSeries.html)
- [`selectLimit`](http://suguru03.github.io/neo-async/doc/async.filterLimit.html) -> [`filterLimit`](http://suguru03.github.io/neo-async/doc/async.filterLimit.html)
- [`reject`](http://suguru03.github.io/neo-async/doc/async.reject.html)
- [`rejectSeries`](http://suguru03.github.io/neo-async/doc/async.rejectSeries.html)
- [`rejectLimit`](http://suguru03.github.io/neo-async/doc/async.rejectLimit.html)
- [`detect`](http://suguru03.github.io/neo-async/doc/async.detect.html)
- [`detectSeries`](http://suguru03.github.io/neo-async/doc/async.detectSeries.html)
- [`detectLimit`](http://suguru03.github.io/neo-async/doc/async.detectLimit.html)
- [`find`](http://suguru03.github.io/neo-async/doc/async.detect.html) -> [`detect`](http://suguru03.github.io/neo-async/doc/async.detect.html)
- [`findSeries`](http://suguru03.github.io/neo-async/doc/async.detectSeries.html) -> [`detectSeries`](http://suguru03.github.io/neo-async/doc/async.detectSeries.html)
- [`findLimit`](http://suguru03.github.io/neo-async/doc/async.detectLimit.html) -> [`detectLimit`](http://suguru03.github.io/neo-async/doc/async.detectLimit.html)
- [`pick`](http://suguru03.github.io/neo-async/doc/async.pick.html) *
- [`pickSeries`](http://suguru03.github.io/neo-async/doc/async.pickSeries.html) *
- [`pickLimit`](http://suguru03.github.io/neo-async/doc/async.pickLimit.html) *
- [`omit`](http://suguru03.github.io/neo-async/doc/async.omit.html) *
- [`omitSeries`](http://suguru03.github.io/neo-async/doc/async.omitSeries.html) *
- [`omitLimit`](http://suguru03.github.io/neo-async/doc/async.omitLimit.html) *
- [`reduce`](http://suguru03.github.io/neo-async/doc/async.reduce.html)
- [`inject`](http://suguru03.github.io/neo-async/doc/async.reduce.html) -> [`reduce`](http://suguru03.github.io/neo-async/doc/async.reduce.html)
- [`foldl`](http://suguru03.github.io/neo-async/doc/async.reduce.html) -> [`reduce`](http://suguru03.github.io/neo-async/doc/async.reduce.html)
- [`reduceRight`](http://suguru03.github.io/neo-async/doc/async.reduceRight.html)
- [`foldr`](http://suguru03.github.io/neo-async/doc/async.reduceRight.html) -> [`reduceRight`](http://suguru03.github.io/neo-async/doc/async.reduceRight.html)
- [`transform`](http://suguru03.github.io/neo-async/doc/async.transform.html)
- [`transformSeries`](http://suguru03.github.io/neo-async/doc/async.transformSeries.html) *
- [`transformLimit`](http://suguru03.github.io/neo-async/doc/async.transformLimit.html) *
- [`sortBy`](http://suguru03.github.io/neo-async/doc/async.sortBy.html)
- [`sortBySeries`](http://suguru03.github.io/neo-async/doc/async.sortBySeries.html) *
- [`sortByLimit`](http://suguru03.github.io/neo-async/doc/async.sortByLimit.html) *
- [`some`](http://suguru03.github.io/neo-async/doc/async.some.html)
- [`someSeries`](http://suguru03.github.io/neo-async/doc/async.someSeries.html)
- [`someLimit`](http://suguru03.github.io/neo-async/doc/async.someLimit.html)
- [`any`](http://suguru03.github.io/neo-async/doc/async.some.html) -> [`some`](http://suguru03.github.io/neo-async/doc/async.some.html)
- [`anySeries`](http://suguru03.github.io/neo-async/doc/async.someSeries.html) -> [`someSeries`](http://suguru03.github.io/neo-async/doc/async.someSeries.html)
- [`anyLimit`](http://suguru03.github.io/neo-async/doc/async.someLimit.html) -> [`someLimit`](http://suguru03.github.io/neo-async/doc/async.someLimit.html)
- [`every`](http://suguru03.github.io/neo-async/doc/async.every.html)
- [`everySeries`](http://suguru03.github.io/neo-async/doc/async.everySeries.html)
- [`everyLimit`](http://suguru03.github.io/neo-async/doc/async.everyLimit.html)
- [`all`](http://suguru03.github.io/neo-async/doc/async.every.html) -> [`every`](http://suguru03.github.io/neo-async/doc/async.every.html)
- [`allSeries`](http://suguru03.github.io/neo-async/doc/async.everySeries.html) -> [`every`](http://suguru03.github.io/neo-async/doc/async.everySeries.html)
- [`allLimit`](http://suguru03.github.io/neo-async/doc/async.everyLimit.html) -> [`every`](http://suguru03.github.io/neo-async/doc/async.everyLimit.html)
- [`concat`](http://suguru03.github.io/neo-async/doc/async.concat.html)
- [`concatSeries`](http://suguru03.github.io/neo-async/doc/async.concatSeries.html)
- [`concatLimit`](http://suguru03.github.io/neo-async/doc/async.concatLimit.html) *

### Control Flow

- [`parallel`](http://suguru03.github.io/neo-async/doc/async.parallel.html)
- [`series`](http://suguru03.github.io/neo-async/doc/async.series.html)
- [`parallelLimit`](http://suguru03.github.io/neo-async/doc/async.series.html)
- [`tryEach`](http://suguru03.github.io/neo-async/doc/async.tryEach.html)
- [`waterfall`](http://suguru03.github.io/neo-async/doc/async.waterfall.html)
- [`angelFall`](http://suguru03.github.io/neo-async/doc/async.angelFall.html) *
- [`angelfall`](http://suguru03.github.io/neo-async/doc/async.angelFall.html) -> [`angelFall`](http://suguru03.github.io/neo-async/doc/async.angelFall.html) *
- [`whilst`](#whilst)
- [`doWhilst`](#doWhilst)
- [`until`](#until)
- [`doUntil`](#doUntil)
- [`during`](#during)
- [`doDuring`](#doDuring)
- [`forever`](#forever)
- [`compose`](#compose)
- [`seq`](#seq)
- [`applyEach`](#applyEach)
- [`applyEachSeries`](#applyEachSeries)
- [`queue`](#queue)
- [`priorityQueue`](#priorityQueue)
- [`cargo`](#cargo)
- [`auto`](#auto)
- [`autoInject`](#autoInject)
- [`retry`](#retry)
- [`retryable`](#retryable)
- [`iterator`](#iterator)
- [`times`](http://suguru03.github.io/neo-async/doc/async.times.html)
- [`timesSeries`](http://suguru03.github.io/neo-async/doc/async.timesSeries.html)
- [`timesLimit`](http://suguru03.github.io/neo-async/doc/async.timesLimit.html)
- [`race`](#race)

### Utils
- [`apply`](#apply)
- [`setImmediate`](#setImmediate)
- [`nextTick`](#nextTick)
- [`memoize`](#memoize)
- [`unmemoize`](#unmemoize)
- [`ensureAsync`](#ensureAsync)
- [`constant`](#constant)
- [`asyncify`](#asyncify)
- [`wrapSync`](#asyncify) -> [`asyncify`](#asyncify)
- [`log`](#log)
- [`dir`](#dir)
- [`timeout`](http://suguru03.github.io/neo-async/doc/async.timeout.html)
- [`reflect`](#reflect)
- [`reflectAll`](#reflectAll)
- [`createLogger`](#createLogger)

## Mode
- [`safe`](#safe) *
- [`fast`](#fast) *

## Benchmark

[Benchmark: Async vs Neo-Async](http://suguru03.hatenablog.com/entry/2016/06/10/135559)

### How to check

```bash
$ node perf
```

### Environment

* Darwin 17.3.0 x64
* Node.js v8.9.4
* async v2.6.0
* neo-async v2.5.0
* benchmark v2.1.4

### Result

The value is the ratio (Neo-Async/Async) of the average speed.

#### Collections
|function|benchmark|
|---|--:|
|each/forEach|2.43|
|eachSeries/forEachSeries|1.75|
|eachLimit/forEachLimit|1.68|
|eachOf|3.29|
|eachOfSeries|1.50|
|eachOfLimit|1.59|
|map|3.95|
|mapSeries|1.81|
|mapLimit|1.27|
|mapValues|2.73|
|mapValuesSeries|1.59|
|mapValuesLimit|1.23|
|filter|3.00|
|filterSeries|1.74|
|filterLimit|1.17|
|reject|4.59|
|rejectSeries|2.31|
|rejectLimit|1.58|
|detect|4.30|
|detectSeries|1.86|
|detectLimit|1.32|
|reduce|1.82|
|transform|2.46|
|sortBy|4.08|
|some|2.19|
|someSeries|1.83|
|someLimit|1.32|
|every|2.09|
|everySeries|1.84|
|everyLimit|1.35|
|concat|3.79|
|concatSeries|4.45|

#### Control Flow
|funciton|benchmark|
|---|--:|
|parallel|2.93|
|series|1.96|
|waterfall|1.29|
|whilst|1.00|
|doWhilst|1.12|
|until|1.12|
|doUntil|1.12|
|during|1.18|
|doDuring|2.42|
|times|4.25|
|auto|1.97|


## License
[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fsuguru03%2Fneo-async.svg?type=large)](https://app.fossa.io/projects/git%2Bgithub.com%2Fsuguru03%2Fneo-async?ref=badge_large)


---

# No Case

[![NPM version][npm-image]][npm-url]
[![NPM downloads][downloads-image]][downloads-url]
[![Bundle size][bundlephobia-image]][bundlephobia-url]

> Transform into a lower cased string with spaces between words.

## Installation

```
npm install no-case --save
```

## Usage

```js
import { noCase } from "no-case";

noCase("string"); //=> "string"
noCase("dot.case"); //=> "dot case"
noCase("PascalCase"); //=> "pascal case"
noCase("version 1.2.10"); //=> "version 1 2 10"
```

The function also accepts [`options`](https://github.com/blakeembrey/change-case#options).

## License

MIT

[npm-image]: https://img.shields.io/npm/v/no-case.svg?style=flat
[npm-url]: https://npmjs.org/package/no-case
[downloads-image]: https://img.shields.io/npm/dm/no-case.svg?style=flat
[downloads-url]: https://npmjs.org/package/no-case
[bundlephobia-image]: https://img.shields.io/bundlephobia/minzip/no-case.svg
[bundlephobia-url]: https://bundlephobia.com/result?p=no-case


---

# MIT License

Copyright (c) 2014-2023 Daniel Bugl

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
'Software'), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


---

<h1 align="center">node-emoji</h1>

<p align="center">Friendly emoji lookups and parsing utilities for Node.js. 💖</p>

<p align="center">
	<!-- prettier-ignore-start -->
	<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
  <a href="#contributors" target="_blank"><img alt="All Contributors: 32 👪" src="https://img.shields.io/badge/all_contributors-32_👪-21bb42.svg" /></a>
  <!-- ALL-CONTRIBUTORS-BADGE:END -->
	<!-- prettier-ignore-end -->
	<a href="https://codecov.io/gh/JoshuaKGoldberg/node-emoji" target="_blank"><img alt="Codecov Test Coverage" src="https://codecov.io/gh/JoshuaKGoldberg/node-emoji/branch/main/graph/badge.svg"/></a>
	<a href="https://github.com/JoshuaKGoldberg/node-emoji/blob/main/.github/CODE_OF_CONDUCT.md" target="_blank"><img alt="Contributor Covenant" src="https://img.shields.io/badge/code_of_conduct-enforced-21bb42" /></a>
	<a href="https://github.com/JoshuaKGoldberg/node-emoji/blob/main/LICENSE.md" target="_blank"><img alt="License: MIT" src="https://img.shields.io/github/license/JoshuaKGoldberg/node-emoji?color=21bb42"></a>
	<a href="https://github.com/sponsors/omnidan" target="_blank"><img alt="Sponsor: On GitHub" src="https://img.shields.io/badge/sponsor-on_github-21bb42.svg" /></a>
	<img alt="Style: Prettier" src="https://img.shields.io/badge/style-prettier-21bb42.svg" />
	<img alt="TypeScript: Strict" src="https://img.shields.io/badge/typescript-strict-21bb42.svg" />
	<img alt="npm package version" src="https://img.shields.io/npm/v/node-emoji?color=21bb42" />
	<img alt="Contributor Covenant" src="https://img.shields.io/badge/code_of_conduct-enforced-21bb42" />
</p>

`node-emoji` provides a fun, straightforward interface on top of the following excellent libraries:

- [`emojilib`](https://npmjs.org/package/emojilib): provides a list of emojis and keyword search on top of it
- [`skin-tone`](https://npmjs.org/package/skin-tone): parses out base emojis from skin tones

## Install

```sh
npm install node-emoji
```

### 2.0 Release 🚀

This is the new 2.0 release of node-emoji, supporting ESM, new emoji and a new API.

If you want to use the old version, please check out the [legacy branch](https://github.com/omnidan/node-emoji/tree/legacy).

## Usage

```js
import * as emoji from 'node-emoji'

emoji.emojify('I :heart: :coffee:!') // 'I ❤️ ☕️!'

emoji.find('heart') // { emoji: '❤', name: 'heart' }
emoji.find('❤️') // { emoji: '❤', name: 'heart' }

emoji.get('unicorn') // 🦄
emoji.get(':unicorn:') // 🦄

emoji.has(':pizza:') // true
emoji.has('🍕') // true
emoji.has('unknown') // false

emoji.random() // { name: 'house', emoji: '🏠' }

emoji.replace('I ❤️ coffee!', 'love', { preserveSpaces: true }) // 'I love coffee!'

emoji.search(':uni:') // [ { emoji: '🦄', name: 'unicorn' }, ... ]

emoji.strip('I ❤️ coffee!') // 'I coffee!'

emoji.unemojify('🍕 for 💃') // ':pizza: for :dancer:'

emoji.which('🦄') // 'unicorn'
```

## API

### emoji.emojify(input, options?)

Parse all markdown-encoded emojis in a string.

Parameters:

1. **`input`** (`string`): The input string containing the markdown-encoding emojis.
1. **`options`** _(optional)_:
   - **`fallback`** (`string`; default: `""`): The string to fallback to if an emoji was not found.
   - **`format`** (`() => (emoji: string, part: string, string: string) => string`; default: `value => value`): Add a middleware layer to modify each matched emoji after parsing.

```js
import * as emoji from 'node-emoji'

console.log(emoji.emojify('The :unicorn: is a fictitious animal.'))
// 'The 🦄 is a fictitious animal.'
```

### emoji.find(emoji)

Get the name and character of an emoji.

Parameters:

1. **`emoji`** (`string`): The emoji to get the data of.

```js
import * as emoji from 'node-emoji'

console.log(emoji.find('🦄'))
// { name: 'unicorn', emoji: '🦄' }
```

### emoji.get(name)

Get an emoji from an emoji name.

Parameters:

1. **`name`** (`string`): The name of the emoji to get.

```js
import * as emoji from 'node-emoji'

console.log(emoji.get('unicorn'))
// '🦄'
```

### emoji.has(emoji)

Check if this library supports a specific emoji.

Parameters:

1. **`emoji`** (`string`): The emoji to check.

```js
import * as emoji from 'node-emoji'

console.log(emoji.has('🦄'))
// true
```

### emoji.random()

Get a random emoji.

```js
import * as emoji from 'node-emoji'

console.log(emoji.random())
// { name: 'unicorn', emoji: '🦄' }
```

### emoji.replace(input, replacement)

Replace the emojis in a string.

Parameters:

- **`input`** (`string`): The input string.
- **`replacement`** (`string | (emoji: string, index: number, string: string) => string`): The character to replace the emoji with.
  Can be either a string or a callback that returns a string.

```js
import * as emoji from 'node-emoji'

console.log(emoji.replace('The 🦄 is a fictitious animal.', 'unicorn'))
// 'The unicorn is a fictitious animal.'
```

### emoji.search(keyword)

Search for emojis containing the provided name in their name.

Parameters:

1. **`keyword`** (`string`): The keyword to search for.

```js
import * as emoji from 'node-emoji'

console.log(emoji.search('honey'))
// [ { name: 'honeybee', emoji: '🐝' }, { name: 'honey_pot', emoji: '🍯' } ]
```

### emoji.strip(input, options?)

Remove all of the emojis from a string.

Parameters:

1. **`input`** (`string`): The input string to strip the emojis from.
1. **`options`** _(optional)_:

   - **`preserveSpaces`** (`boolean`): Whether to keep the extra space after a stripped emoji.

```js
import * as emoji from 'node-emoji'

console.log(emoji.strip('🦄 The unicorn is a fictitious animal.'))
// 'The unicorn is a fictitious animal.'

console.log(
  emoji.strip('🦄 The unicorn is a fictitious animal.', {
    preserveSpaces: true,
  }),
)
// ' The unicorn is a fictitious animal.'
```

### emoji.unemojify(input)

Convert all emojis in a string to their markdown-encoded counterparts.

Parameters:

1. **`input`** (`string`): The input string containing the emojis.

```js
import * as emoji from 'node-emoji'

console.log(emoji.unemojify('The 🦄 is a fictitious animal.'))
// 'The :unicorn: is a fictitious animal.'
```

### emoji.which(emoji, options?)

Get an emoji name from an emoji.

Parameters:

1. **`emoji`** (`string`): The emoji to get the name of.
1. **`options`** _(optional)_:
   - **`markdown`** (`boolean`; default: `false`): Whether to return a `":emoji:"` string instead of `"emoji"`

```js
import * as emoji from 'node-emoji'

console.log(emoji.which('🦄'))
// 'unicorn'
```

## Development

See _[`.github/Development.md`](./github/Development.md)_.

## License

[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fomnidan%2Fnode-emoji.svg?type=large)](https://app.fossa.io/projects/git%2Bgithub.com%2Fomnidan%2Fnode-emoji?ref=badge_large)

### Special Thanks

...to Anand Chowdhary (@AnandChowdhary) and his company [Pabio](https://github.com/pabio) for sponsoring this project via [GitHub Sponsors](https://github.com/sponsors/omnidan)!

## Contributors

<!-- spellchecker: disable -->
<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
<!-- prettier-ignore-start -->
<!-- markdownlint-disable -->
<table>
  <tbody>
    <tr>
      <td align="center" valign="top" width="14.28%"><a href="https://www.linkedin.com/in/cagataycali/"><img src="https://avatars.githubusercontent.com/u/9213230?v=4?s=100" width="100px;" alt="./c²"/><br /><sub><b>./c²</b></sub></a><br /><a href="https://github.com/omnidan/node-emoji/commits?author=cagataycali" title="Code">💻</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://github.com/askoufis"><img src="https://avatars.githubusercontent.com/u/5663042?v=4?s=100" width="100px;" alt="Adam Skoufis"/><br /><sub><b>Adam Skoufis</b></sub></a><br /><a href="https://github.com/omnidan/node-emoji/commits?author=askoufis" title="Code">💻</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://adriancarolli.surge.sh/"><img src="https://avatars.githubusercontent.com/u/3059371?v=4?s=100" width="100px;" alt="Adrian Carolli"/><br /><sub><b>Adrian Carolli</b></sub></a><br /><a href="https://github.com/omnidan/node-emoji/commits?author=watadarkstar" title="Code">💻</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://github.com/alexlitel"><img src="https://avatars.githubusercontent.com/u/12000084?v=4?s=100" width="100px;" alt="Alex Litel"/><br /><sub><b>Alex Litel</b></sub></a><br /><a href="https://github.com/omnidan/node-emoji/commits?author=alexlitel" title="Code">💻</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://alex-rudenko.com/"><img src="https://avatars.githubusercontent.com/u/399150?v=4?s=100" width="100px;" alt="Alex Rudenko"/><br /><sub><b>Alex Rudenko</b></sub></a><br /><a href="https://github.com/omnidan/node-emoji/commits?author=OrKoN" title="Code">💻</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://github.com/ahanriat"><img src="https://avatars.githubusercontent.com/u/1374161?v=4?s=100" width="100px;" alt="Antoine Hanriat"/><br /><sub><b>Antoine Hanriat</b></sub></a><br /><a href="https://github.com/omnidan/node-emoji/commits?author=ahanriat" title="Code">💻</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://omnidan.net/"><img src="https://avatars.githubusercontent.com/u/668674?v=4?s=100" width="100px;" alt="Daniel Bugl"/><br /><sub><b>Daniel Bugl</b></sub></a><br /><a href="https://github.com/omnidan/node-emoji/issues?q=author%3Aomnidan" title="Bug reports">🐛</a> <a href="https://github.com/omnidan/node-emoji/commits?author=omnidan" title="Code">💻</a> <a href="#fundingFinding-omnidan" title="Funding Finding">🔍</a> <a href="#ideas-omnidan" title="Ideas, Planning, & Feedback">🤔</a> <a href="#infra-omnidan" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a> <a href="#tool-omnidan" title="Tools">🔧</a> <a href="#maintenance-omnidan" title="Maintenance">🚧</a></td>
    </tr>
    <tr>
      <td align="center" valign="top" width="14.28%"><a href="https://github.com/DanielHilton"><img src="https://avatars.githubusercontent.com/u/28859662?v=4?s=100" width="100px;" alt="Daniel Hilton"/><br /><sub><b>Daniel Hilton</b></sub></a><br /><a href="https://github.com/omnidan/node-emoji/commits?author=DanielHilton" title="Code">💻</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://github.com/emctackett"><img src="https://avatars.githubusercontent.com/u/19399698?v=4?s=100" width="100px;" alt="Elizabeth"/><br /><sub><b>Elizabeth</b></sub></a><br /><a href="https://github.com/omnidan/node-emoji/commits?author=emctackett" title="Code">💻</a> <a href="#maintenance-emctackett" title="Maintenance">🚧</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://www.gabrielcsapo.com/"><img src="https://avatars.githubusercontent.com/u/1854811?v=4?s=100" width="100px;" alt="Gabriel Csapo"/><br /><sub><b>Gabriel Csapo</b></sub></a><br /><a href="https://github.com/omnidan/node-emoji/commits?author=gabrielcsapo" title="Code">💻</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://greenkeeper.io/"><img src="https://avatars.githubusercontent.com/u/14790466?v=4?s=100" width="100px;" alt="Greenkeeper"/><br /><sub><b>Greenkeeper</b></sub></a><br /><a href="https://github.com/omnidan/node-emoji/commits?author=greenkeeperio-bot" title="Code">💻</a></td>
      <td align="center" valign="top" width="14.28%"><a href="http://www.joshuakgoldberg.com/"><img src="https://avatars.githubusercontent.com/u/3335181?v=4?s=100" width="100px;" alt="Josh Goldberg ✨"/><br /><sub><b>Josh Goldberg ✨</b></sub></a><br /><a href="#tool-JoshuaKGoldberg" title="Tools">🔧</a> <a href="https://github.com/omnidan/node-emoji/commits?author=JoshuaKGoldberg" title="Code">💻</a> <a href="#infra-JoshuaKGoldberg" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a> <a href="#maintenance-JoshuaKGoldberg" title="Maintenance">🚧</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://cooperka.com/"><img src="https://avatars.githubusercontent.com/u/2047062?v=4?s=100" width="100px;" alt="Kevin Cooper"/><br /><sub><b>Kevin Cooper</b></sub></a><br /><a href="https://github.com/omnidan/node-emoji/commits?author=cooperka" title="Code">💻</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://github.com/merceyz"><img src="https://avatars.githubusercontent.com/u/3842800?v=4?s=100" width="100px;" alt="Kristoffer K."/><br /><sub><b>Kristoffer K.</b></sub></a><br /><a href="https://github.com/omnidan/node-emoji/commits?author=merceyz" title="Code">💻</a></td>
    </tr>
    <tr>
      <td align="center" valign="top" width="14.28%"><a href="https://github.com/ludorenzetti"><img src="https://avatars.githubusercontent.com/u/8739517?v=4?s=100" width="100px;" alt="Ludo Renzetti"/><br /><sub><b>Ludo Renzetti</b></sub></a><br /><a href="https://github.com/omnidan/node-emoji/commits?author=ludorenzetti" title="Code">💻</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://charpeni.com/"><img src="https://avatars.githubusercontent.com/u/7189823?v=4?s=100" width="100px;" alt="Nicolas Charpentier"/><br /><sub><b>Nicolas Charpentier</b></sub></a><br /><a href="#maintenance-charpeni" title="Maintenance">🚧</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://ngryman.sh/"><img src="https://avatars.githubusercontent.com/u/892048?v=4?s=100" width="100px;" alt="Nicolas Gryman"/><br /><sub><b>Nicolas Gryman</b></sub></a><br /><a href="https://github.com/omnidan/node-emoji/commits?author=ngryman" title="Code">💻</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://github.com/HistoireDeBabar"><img src="https://avatars.githubusercontent.com/u/6544057?v=4?s=100" width="100px;" alt="Paul Barber"/><br /><sub><b>Paul Barber</b></sub></a><br /><a href="https://github.com/omnidan/node-emoji/commits?author=HistoireDeBabar" title="Code">💻</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://richienb.github.io/"><img src="https://avatars.githubusercontent.com/u/29491356?v=4?s=100" width="100px;" alt="Richie Bendall"/><br /><sub><b>Richie Bendall</b></sub></a><br /><a href="https://github.com/omnidan/node-emoji/commits?author=Richienb" title="Code">💻</a> <a href="#maintenance-Richienb" title="Maintenance">🚧</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://thetechinfinite.com/"><img src="https://avatars.githubusercontent.com/u/47841501?v=4?s=100" width="100px;" alt="Ritik Banger"/><br /><sub><b>Ritik Banger</b></sub></a><br /><a href="https://github.com/omnidan/node-emoji/commits?author=ritikbanger" title="Code">💻</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://roopakv.com/"><img src="https://avatars.githubusercontent.com/u/678239?v=4?s=100" width="100px;" alt="Roopak Venkatakrishnan"/><br /><sub><b>Roopak Venkatakrishnan</b></sub></a><br /><a href="https://github.com/omnidan/node-emoji/commits?author=roopakv" title="Code">💻</a></td>
    </tr>
    <tr>
      <td align="center" valign="top" width="14.28%"><a href="https://shivkanth.com/"><img src="https://avatars.githubusercontent.com/u/3232159?v=4?s=100" width="100px;" alt="Shivkanth Bagavathy"/><br /><sub><b>Shivkanth Bagavathy</b></sub></a><br /><a href="https://github.com/omnidan/node-emoji/commits?author=shivkanthb" title="Code">💻</a></td>
      <td align="center" valign="top" width="14.28%"><a href="http://siddharthbatra.com/"><img src="https://avatars.githubusercontent.com/u/622674?v=4?s=100" width="100px;" alt="Siddharth Batra"/><br /><sub><b>Siddharth Batra</b></sub></a><br /><a href="https://github.com/omnidan/node-emoji/commits?author=sidbatra" title="Code">💻</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://github.com/smeijer"><img src="https://avatars.githubusercontent.com/u/1196524?v=4?s=100" width="100px;" alt="Stephan Meijer"/><br /><sub><b>Stephan Meijer</b></sub></a><br /><a href="https://github.com/omnidan/node-emoji/commits?author=smeijer" title="Code">💻</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://github.com/Thomas101"><img src="https://avatars.githubusercontent.com/u/103586?v=4?s=100" width="100px;" alt="Thomas Beverley"/><br /><sub><b>Thomas Beverley</b></sub></a><br /><a href="https://github.com/omnidan/node-emoji/issues?q=author%3AThomas101" title="Bug reports">🐛</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://timr.co/"><img src="https://avatars.githubusercontent.com/u/249800?v=4?s=100" width="100px;" alt="Tim Ruffles"/><br /><sub><b>Tim Ruffles</b></sub></a><br /><a href="https://github.com/omnidan/node-emoji/commits?author=timruffles" title="Code">💻</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://toddmazierski.com/"><img src="https://avatars.githubusercontent.com/u/544541?v=4?s=100" width="100px;" alt="Todd Mazierski"/><br /><sub><b>Todd Mazierski</b></sub></a><br /><a href="https://github.com/omnidan/node-emoji/issues?q=author%3Atoddmazierski" title="Bug reports">🐛</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://fossa.com/"><img src="https://avatars.githubusercontent.com/u/29791463?v=4?s=100" width="100px;" alt="fossabot"/><br /><sub><b>fossabot</b></sub></a><br /><a href="https://github.com/omnidan/node-emoji/commits?author=fossabot" title="Code">💻</a></td>
    </tr>
    <tr>
      <td align="center" valign="top" width="14.28%"><a href="https://github.com/goodjun"><img src="https://avatars.githubusercontent.com/u/18377597?v=4?s=100" width="100px;" alt="goodjun"/><br /><sub><b>goodjun</b></sub></a><br /><a href="https://github.com/omnidan/node-emoji/issues?q=author%3Agoodjun" title="Bug reports">🐛</a></td>
      <td align="center" valign="top" width="14.28%"><a href="http://jackieluo.com/"><img src="https://avatars.githubusercontent.com/u/8452682?v=4?s=100" width="100px;" alt="jackie luo"/><br /><sub><b>jackie luo</b></sub></a><br /><a href="https://github.com/omnidan/node-emoji/commits?author=jackiehluo" title="Code">💻</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://github.com/tgbtyty"><img src="https://avatars.githubusercontent.com/u/10119245?v=4?s=100" width="100px;" alt="tgbtyty"/><br /><sub><b>tgbtyty</b></sub></a><br /><a href="https://github.com/omnidan/node-emoji/commits?author=tgbtyty" title="Code">💻</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://github.com/wtgtybhertgeghgtwtg"><img src="https://avatars.githubusercontent.com/u/18507762?v=4?s=100" width="100px;" alt="wtgtybhertgeghgtwtg"/><br /><sub><b>wtgtybhertgeghgtwtg</b></sub></a><br /><a href="https://github.com/omnidan/node-emoji/commits?author=wtgtybhertgeghgtwtg" title="Code">💻</a></td>
    </tr>
  </tbody>
</table>

<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->

<!-- ALL-CONTRIBUTORS-LIST:END -->
<!-- spellchecker: enable -->


---

Forge ChangeLog
===============

## 1.3.1 - 2022-03-29

### Fixes
- RFC 3447 and RFC 8017 allow for optional `DigestAlgorithm` `NULL` parameters
  for `sha*` algorithms and require `NULL` paramters for `md2` and `md5`
  algorithms.

## 1.3.0 - 2022-03-17

### Security
- Three RSA PKCS#1 v1.5 signature verification issues were reported by Moosa
  Yahyazadeh (moosa-yahyazadeh@uiowa.edu).
- **HIGH**: Leniency in checking `digestAlgorithm` structure can lead to
  signature forgery.
  - The code is lenient in checking the digest algorithm structure. This can
    allow a crafted structure that steals padding bytes and uses unchecked
    portion of the PKCS#1 encoded message to forge a signature when a low
    public exponent is being used. For more information, please see
    ["Bleichenbacher's RSA signature forgery based on implementation
    error"](https://mailarchive.ietf.org/arch/msg/openpgp/5rnE9ZRN1AokBVj3VqblGlP63QE/)
    by Hal Finney.
  - CVE ID: [CVE-2022-24771](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-24771)
  - GHSA ID: [GHSA-cfm4-qjh2-4765](https://github.com/digitalbazaar/forge/security/advisories/GHSA-cfm4-qjh2-4765)
- **HIGH**: Failing to check tailing garbage bytes can lead to signature
  forgery.
  - The code does not check for tailing garbage bytes after decoding a
    `DigestInfo` ASN.1 structure. This can allow padding bytes to be removed
    and garbage data added to forge a signature when a low public exponent is
    being used.  For more information, please see ["Bleichenbacher's RSA
    signature forgery based on implementation
    error"](https://mailarchive.ietf.org/arch/msg/openpgp/5rnE9ZRN1AokBVj3VqblGlP63QE/)
    by Hal Finney.
  - CVE ID: [CVE-2022-24772](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-24772)
  - GHSA ID: [GHSA-x4jg-mjrx-434g](https://github.com/digitalbazaar/forge/security/advisories/GHSA-x4jg-mjrx-434g)
- **MEDIUM**: Leniency in checking type octet.
  - `DigestInfo` is not properly checked for proper ASN.1 structure. This can
    lead to successful verification with signatures that contain invalid
    structures but a valid digest.
  - CVE ID: [CVE-2022-24773](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-24773)
  - GHSA ID: [GHSA-2r2c-g63r-vccr](https://github.com/digitalbazaar/forge/security/advisories/GHSA-2r2c-g63r-vccr)

### Fixed
- [asn1] Add fallback to pretty print invalid UTF8 data.
- [asn1] `fromDer` is now more strict and will default to ensuring all input
  bytes are parsed or throw an error. A new option `parseAllBytes` can disable
  this behavior.
  - **NOTE**: The previous behavior is being changed since it can lead to
    security issues with crafted inputs. It is possible that code doing custom
    DER parsing may need to adapt to this new behavior and optional flag.
- [rsa] Add and use a validator to check for proper structure of parsed ASN.1
  `RSASSA-PKCS-v1_5` `DigestInfo` data. Additionally check that the hash
  algorithm identifier is a known value from RFC 8017
  `PKCS1-v1-5DigestAlgorithms`. An invalid `DigestInfo` or algorithm identifier
  will now throw an error.
  - **NOTE**: The previous lenient behavior is being changed to be more strict
    since it could lead to security issues with crafted inputs. It is possible
    that code may have to handle the errors from these stricter checks.

### Added
- [oid] Added missing RFC 8017 PKCS1-v1-5DigestAlgorithms algorithm
  identifiers:
  - `1.2.840.113549.2.2` / `md2`
  - `2.16.840.1.101.3.4.2.4` / `sha224`
  - `2.16.840.1.101.3.4.2.5` / `sha512-224`
  - `2.16.840.1.101.3.4.2.6` / `sha512-256`

## 1.2.1 - 2022-01-11

### Fixed
- [tests]: Load entire module to improve top-level testing and coverage
  reporting.
- [log]: Refactor logging setup to avoid use of `URLSearchParams`.

## 1.2.0 - 2022-01-07

### Fixed
- [x509] 'Expected' and 'Actual' issuers were backwards in verification failure
  message.

### Added
- [oid,x509]: Added OID `1.3.14.3.2.29 / sha1WithRSASignature` for sha1 with
  RSA. Considered a deprecated equivalent to `1.2.840.113549.1.1.5 /
  sha1WithRSAEncryption`. See [discussion and
  links](https://github.com/digitalbazaar/forge/issues/825).

### Changed
- [x509]: Reduce duplicate code. Add helper function to create a signature
  digest given an signature algorithm OID. Add helper function to verify
  signatures.

## 1.1.0 - 2022-01-06

### Fixed
- [x509]: Correctly compute certificate issuer and subject hashes to match
  behavior of openssl.
- [pem]: Accept certificate requests with "NEW" in the label. "BEGIN NEW
  CERTIFICATE REQUEST" handled as "BEGIN CERTIFICATE REQUEST".

## 1.0.0 - 2022-01-04

### Notes
- **1.0.0**!
- This project is over a decade old! Time for a 1.0.0 release.
- The URL related changes may expose bugs in some of the networking related
  code (unrelated to the much wider used cryptography code). The automated and
  manual test coverage for this code is weak at best. Issues or patches to
  update the code or tests would be appreciated.

### Removed
- **SECURITY**, **BREAKING**: Remove `forge.debug` API. The API has the
  potential for prototype pollution. This API was only briefly used by the
  maintainers for internal project debug purposes and was never intended to be
  used with untrusted user inputs. This API was not documented or advertised
  and is being removed rather than fixed.
- **SECURITY**, **BREAKING**: Remove `forge.util.parseUrl()` (and
  `forge.http.parseUrl` alias) and use the [WHATWG URL
  Standard](https://url.spec.whatwg.org/). `URL` is supported by modern browers
  and modern Node.js. This change is needed to address URL parsing security
  issues. If `forge.util.parseUrl()` is used directly or through `forge.xhr` or
  `forge.http` APIs, and support is needed for environments without `URL`
  support, then a polyfill must be used.
- **BREAKING**: Remove `forge.task` API. This API was never used, documented,
  or advertised by the maintainers. If anyone was using this API and wishes to
  continue development it in other project, please let the maintainers know.
  Due to use in the test suite, a modified version is located in
  `tests/support/`.
- **BREAKING**: Remove `forge.util.makeLink`, `forge.util.makeRequest`,
  `forge.util.parseFragment`, `forge.util.getQueryVariables`. Replace with
  `URL`, `URLSearchParams`, and custom code as needed.

### Changed
- **BREAKING**: Increase supported Node.js version to 6.13.0 for URL support.
- **BREAKING**: Renamed `master` branch to `main`.
- **BREAKING**: Release process updated to use tooling that prefixes versions
  with `v`. Other tools, scripts, or scanners may need to adapt.
- **BREAKING**: Remove docs related to Bower and
  [forge-dist](https://github.com/digitalbazaar/forge-dist). Install using
  [another method](./README.md#installation).

### Added
- OIDs for `surname`, `title`, and `givenName`.

### Fixed
- **BREAKING**: OID 2.5.4.5 name fixed from `serialName` to `serialNumber`.
  Depending on how applications used this id to name association it could cause
  compatibility issues.

## 0.10.0 - 2020-09-01

### Changed
- **BREAKING**: Node.js 4 no longer supported. The code *may* still work, and
  non-invasive patches to keep it working will be considered. However, more
  modern tools no longer support old Node.js versions making testing difficult.

### Removed
- **BREAKING**: Remove `util.getPath`, `util.setPath`, and `util.deletePath`.
  `util.setPath` had a potential prototype pollution security issue when used
  with unsafe inputs. These functions are not used by `forge` itself. They date
  from an early time when `forge` was targeted at providing general helper
  functions. The library direction changed to be more focused on cryptography.
  Many other excellent libraries are more suitable for general utilities. If
  you need a replacement for these functions, consider `get`, `set`, and `unset`
  from [lodash](https://lodash.com/). But also consider the potential similar
  security issues with those APIs.

## 0.9.2 - 2020-09-01

### Changed
- Added `util.setPath` security note to function docs and to README.

### Notes
- **SECURITY**: The `util.setPath` function has the potential to cause
  prototype pollution if used with unsafe input.
  - This function is **not** used internally by `forge`.
  - The rest of the library is unaffected by this issue.
  - **Do not** use unsafe input with this function.
  - Usage with known input should function as expected. (Including input
    intentionally using potentially problematic keys.)
  - No code changes will be made to address this issue in 0.9.x. The current
    behavior *could* be considered a feature rather than a security issue.
    0.10.0 will be released that removes `util.getPath` and `util.setPath`.
    Consider `get` and `set` from [lodash](https://lodash.com/) if you need
    replacements. But also consider the potential similar security issues with
    those APIs.
  - https://snyk.io/vuln/SNYK-JS-NODEFORGE-598677
  - https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-7720

## 0.9.1 - 2019-09-26

### Fixed
- Ensure DES-CBC given IV is long enough for block size.

## 0.9.0 - 2019-09-04

### Added
- Add ed25519.publicKeyFromAsn1 and ed25519.privateKeyFromAsn1 APIs.
- A few OIDs used in EV certs.

### Fixed
- Improve ed25519 NativeBuffer check.

## 0.8.5 - 2019-06-18

### Fixed
- Remove use of `const`.

## 0.8.4 - 2019-05-22

### Changed
- Replace all instances of Node.js `new Buffer` with `Buffer.from` and `Buffer.alloc`.

## 0.8.3 - 2019-05-15

### Fixed
- Use basic character set for code.

## 0.8.2 - 2019-03-18

### Fixed
- Fix tag calculation when continuing an AES-GCM block.

### Changed
- Switch to eslint.

## 0.8.1 - 2019-02-23

### Fixed
- Fix off-by-1 bug with kem random generation.

## 0.8.0 - 2019-01-31

### Fixed
- Handle creation of certificates with `notBefore` and `notAfter` dates less
  than Jan 1, 1950 or greater than or equal to Jan 1, 2050.

### Added
- Add OID 2.5.4.13 "description".
- Add OID 2.16.840.1.113730.1.13 "nsComment".
  - Also handle extension when creating a certificate.
- `pki.verifyCertificateChain`:
  - Add `validityCheckDate` option to allow checking the certificate validity
    period against an arbitrary `Date` or `null` for no check at all. The
    current date is used by default.
- `tls.createConnection`:
  - Add `verifyOptions` option that passes through to
    `pki.verifyCertificateChain`. Can be used for the above `validityCheckDate`
    option.

### Changed
- Support WebCrypto API in web workers.
- `rsa.generateKeyPair`:
  - Use `crypto.generateKeyPair`/`crypto.generateKeyPairSync` on Node.js if
    available (10.12.0+) and not in pure JS mode.
  - Use JS fallback in `rsa.generateKeyPair` if `prng` option specified since
    this isn't supported by current native APIs.
  - Only run key generation comparison tests if keys will be deterministic.
- PhantomJS is deprecated, now using Headless Chrome with Karma.
- **Note**: Using Headless Chrome vs PhantomJS may cause newer JS features to
  slip into releases without proper support for older runtimes and browsers.
  Please report such issues and they will be addressed.
- `pki.verifyCertificateChain`:
  - Signature changed to `(caStore, chain, options)`. Older `(caStore, chain,
    verify)` signature is still supported. New style is to to pass in a
    `verify` option.

## 0.7.6 - 2018-08-14

### Added
- Test on Node.js 10.x.
- Support for PKCS#7 detached signatures.

### Changed
- Improve webpack/browser detection.

## 0.7.5 - 2018-03-30

### Fixed
- Remove use of `const`.

## 0.7.4 - 2018-03-07

### Fixed
- Potential regex denial of service in form.js.

### Added
- Support for ED25519.
- Support for baseN/base58.

## 0.7.3 - 2018-03-05

- Re-publish with npm 5.6.0 due to file timestamp issues.

## 0.7.2 - 2018-02-27

### Added
- Support verification of SHA-384 certificates.
- `1.2.840.10040.4.3'`/`dsa-with-sha1` OID.

### Fixed
- Support importing PKCS#7 data with no certificates. RFC 2315 sec 9.1 states
  certificates are optional.
- `asn1.equals` loop bug.
- Fortuna implementation bugs.

## 0.7.1 - 2017-03-27

### Fixed

- Fix digestLength for hashes based on SHA-512.

## 0.7.0 - 2017-02-07

### Fixed

- Fix test looping bugs so all tests are run.
- Improved ASN.1 parsing. Many failure cases eliminated. More sanity checks.
  Better behavior in default mode of parsing BIT STRINGs. Better handling of
  parsed BIT STRINGs in `toDer()`. More tests.
- Improve X.509 BIT STRING handling by using new capture modes.

### Changed

- Major refactor to use CommonJS plus a browser build system.
- Updated tests, examples, docs.
- Updated dependencies.
- Updated flash build system.
- Improve OID mapping code.
- Change test servers from Python to JavaScript.
- Improve PhantomJS support.
- Move Bower/bundle support to
  [forge-dist](https://github.com/digitalbazaar/forge-dist).
- **BREAKING**: Require minimal digest algorithm dependencies from individual
  modules.
- Enforce currently supported bit param values for byte buffer access. May be
  **BREAKING** for code that depended on unspecified and/or incorrect behavior.
- Improve `asn1.prettyPrint()` BIT STRING display.

### Added

- webpack bundler support via `npm run build`:
  - Builds `.js`, `.min.js`, and basic sourcemaps.
  - Basic build: `forge.js`.
  - Build with extra utils and networking support: `forge.all.js`.
  - Build WebWorker support: `prime.worker.js`.
- Browserify support in package.json.
- Karma browser testing.
- `forge.options` field.
- `forge.options.usePureJavaScript` flag.
- `forge.util.isNodejs` flag (used to select "native" APIs).
- Run PhantomJS tests in Travis-CI.
- Add "Donations" section to README.
- Add IRC to "Contact" section of README.
- Add "Security Considerations" section to README.
- Add pbkdf2 usePureJavaScript test.
- Add rsa.generateKeyPair async and usePureJavaScript tests.
- Add .editorconfig support.
- Add `md.all.js` which includes all digest algorithms.
- Add asn1 `equals()` and `copy()`.
- Add asn1 `validate()` capture options for BIT STRING contents and value.

### Removed

- **BREAKING**: Can no longer call `forge({...})` to create new instances.
- Remove a large amount of old cruft.

### Migration from 0.6.x to 0.7.x

- (all) If you used the feature to create a new forge instance with new
  configuration options you will need to rework your code. That ability has
  been removed due to implementation complexity. The main rare use was to set
  the option to use pure JavaScript. That is now available as a library global
  flag `forge.options.usePureJavaScript`.
- (npm,bower) If you used the default main file there is little to nothing to
  change.
- (npm) If you accessed a sub-resource like `forge/js/pki` you should either
  switch to just using the main `forge` and access `forge.pki` or update to
  `forge/lib/pki`.
- (bower) If you used a sub-resource like `forge/js/pki` you should switch to
  just using `forge` and access `forge.pki`. The bower release bundles
  everything in one minified file.
- (bower) A configured workerScript like
  `/bower_components/forge/js/prime.worker.js` will need to change to
  `/bower_components/forge/dist/prime.worker.min.js`.
- (all) If you used the networking support or flash socket support, you will
  need to use a custom build and/or adjust where files are loaded from. This
  functionality is not included in the bower distribution by default and is
  also now in a different directory.
- (all) The library should now directly support building custom bundles with
  webpack, browserify, or similar.
- (all) If building a custom bundle ensure the correct dependencies are
  included. In particular, note there is now a `md.all.js` file to include all
  digest algorithms. Individual files limit what they include by default to
  allow smaller custom builds. For instance, `pbdkf2.js` has a `sha1` default
  but does not include any algorithm files by default. This allows the
  possibility to include only `sha256` without the overhead of `sha1` and
  `sha512`.

### Notes

- This major update requires updating the version to 0.7.x. The existing
  work-in-progress "0.7.x" branch will be painfully rebased on top of this new
  0.7.x and moved forward to 0.8.x or later as needed.
- 0.7.x is a start of simplifying forge based on common issues and what has
  appeared to be the most common usage. Please file issues with feedback if the
  changes are problematic for your use cases.

## 0.6.x - 2016 and earlier

- See Git commit log or https://github.com/digitalbazaar/forge.


---

# Forge

[![npm package](https://nodei.co/npm/node-forge.png?downloads=true&downloadRank=true&stars=true)](https://nodei.co/npm/node-forge/)

[![Build Status](https://github.com/digitalbazaar/forge/workflows/Main%20Checks/badge.svg)](https://github.com/digitalbazaar/forge/actions?query=workflow%3A%22Main+Checks%22)

A native implementation of [TLS][] (and various other cryptographic tools) in
[JavaScript][].

Introduction
------------

The Forge software is a fully native implementation of the [TLS][] protocol
in JavaScript, a set of cryptography utilities, and a set of tools for
developing Web Apps that utilize many network resources.

Performance
------------

Forge is fast. Benchmarks against other popular JavaScript cryptography
libraries can be found here:

* http://dominictarr.github.io/crypto-bench/
* http://cryptojs.altervista.org/test/simulate-threading-speed_test.html

Documentation
-------------

* [Introduction](#introduction)
* [Performance](#performance)
* [Installation](#installation)
* [Testing](#testing)
* [Contributing](#contributing)

### API

* [Options](#options)

### Transports

* [TLS](#tls)
* [HTTP](#http)
* [SSH](#ssh)
* [XHR](#xhr)
* [Sockets](#socket)

### Ciphers

* [CIPHER](#cipher)
* [AES](#aes)
* [DES](#des)
* [RC2](#rc2)

### PKI

* [ED25519](#ed25519)
* [RSA](#rsa)
* [RSA-KEM](#rsakem)
* [X.509](#x509)
* [PKCS#5](#pkcs5)
* [PKCS#7](#pkcs7)
* [PKCS#8](#pkcs8)
* [PKCS#10](#pkcs10)
* [PKCS#12](#pkcs12)
* [ASN.1](#asn)

### Message Digests

* [SHA1](#sha1)
* [SHA256](#sha256)
* [SHA384](#sha384)
* [SHA512](#sha512)
* [MD5](#md5)
* [HMAC](#hmac)

### Utilities

* [Prime](#prime)
* [PRNG](#prng)
* [Tasks](#task)
* [Utilities](#util)
* [Logging](#log)
* [Flash Networking Support](#flash)

### Other

* [Security Considerations](#security-considerations)
* [Library Background](#library-background)
* [Contact](#contact)
* [Donations](#donations)

---------------------------------------

Installation
------------

**Note**: Please see the [Security Considerations](#security-considerations)
section before using packaging systems and pre-built files.

Forge uses a [CommonJS][] module structure with a build process for browser
bundles. The older [0.6.x][] branch with standalone files is available but will
not be regularly updated.

### Node.js

If you want to use forge with [Node.js][], it is available through `npm`:

https://www.npmjs.com/package/node-forge

Installation:

    npm install node-forge

You can then use forge as a regular module:

```js
var forge = require('node-forge');
```

The npm package includes pre-built `forge.min.js`, `forge.all.min.js`, and
`prime.worker.min.js` using the [UMD][] format.

### jsDelivr CDN

To use it via [jsDelivr](https://www.jsdelivr.com/package/npm/node-forge) include this in your html:

```html
<script src="https://cdn.jsdelivr.net/npm/node-forge@1.0.0/dist/forge.min.js"></script>
```

### unpkg CDN

To use it via [unpkg](https://unpkg.com/#/) include this in your html:

```html
<script src="https://unpkg.com/node-forge@1.0.0/dist/forge.min.js"></script>
```

### Development Requirements

The core JavaScript has the following requirements to build and test:

* Building a browser bundle:
  * Node.js
  * npm
* Testing
  * Node.js
  * npm
  * Chrome, Firefox, Safari (optional)

Some special networking features can optionally use a Flash component.  See the
[Flash README](./flash/README.md) for details.

### Building for a web browser

To create single file bundles for use with browsers run the following:

    npm install
    npm run build

This will create single non-minimized and minimized files that can be
included in the browser:

    dist/forge.js
    dist/forge.min.js

A bundle that adds some utilities and networking support is also available:

    dist/forge.all.js
    dist/forge.all.min.js

Include the file via:

```html
<script src="YOUR_SCRIPT_PATH/forge.js"></script>
```
or
```html
<script src="YOUR_SCRIPT_PATH/forge.min.js"></script>
```

The above bundles will synchronously create a global 'forge' object.

**Note**: These bundles will not include any WebWorker scripts (eg:
`dist/prime.worker.js`), so these will need to be accessible from the browser
if any WebWorkers are used.

### Building a custom browser bundle

The build process uses [webpack][] and the [config](./webpack.config.js) file
can be modified to generate a file or files that only contain the parts of
forge you need.

[Browserify][] override support is also present in `package.json`.

Testing
-------

### Prepare to run tests

    npm install

### Running automated tests with Node.js

Forge natively runs in a [Node.js][] environment:

    npm test

### Running automated tests with Headless Chrome

Automated testing is done via [Karma][]. By default it will run the tests with
Headless Chrome.

    npm run test-karma

Is 'mocha' reporter output too verbose? Other reporters are available. Try
'dots', 'progress', or 'tap'.

    npm run test-karma -- --reporters progress

By default [webpack][] is used. [Browserify][] can also be used.

    BUNDLER=browserify npm run test-karma

### Running automated tests with one or more browsers

You can also specify one or more browsers to use.

    npm run test-karma -- --browsers Chrome,Firefox,Safari,ChromeHeadless

The reporter option and `BUNDLER` environment variable can also be used.

### Running manual tests in a browser

Testing in a browser uses [webpack][] to combine forge and all tests and then
loading the result in a browser. A simple web server is provided that will
output the HTTP or HTTPS URLs to load. It also will start a simple Flash Policy
Server. Unit tests and older legacy tests are provided. Custom ports can be
used by running `node tests/server.js` manually.

To run the unit tests in a browser a special forge build is required:

    npm run test-build

To run legacy browser based tests the main forge build is required:

    npm run build

The tests are run with a custom server that prints out the URLs to use:

    npm run test-server

### Running other tests

There are some other random tests and benchmarks available in the tests
directory.

### Coverage testing

To perform coverage testing of the unit tests, run the following. The results
will be put in the `coverage/` directory. Note that coverage testing can slow
down some tests considerably.

    npm install
    npm run coverage

Contributing
------------

Any contributions (eg: PRs) that are accepted will be brought under the same
license used by the rest of the Forge project. This license allows Forge to
be used under the terms of either the BSD License or the GNU General Public
License (GPL) Version 2.

See: [LICENSE](https://github.com/digitalbazaar/forge/blob/cbebca3780658703d925b61b2caffb1d263a6c1d/LICENSE)

If a contribution contains 3rd party source code with its own license, it
may retain it, so long as that license is compatible with the Forge license.

API
---

<a name="options" />

### Options

If at any time you wish to disable the use of native code, where available,
for particular forge features like its secure random number generator, you
may set the ```forge.options.usePureJavaScript``` flag to ```true```. It is
not recommended that you set this flag as native code is typically more
performant and may have stronger security properties. It may be useful to
set this flag to test certain features that you plan to run in environments
that are different from your testing environment.

To disable native code when including forge in the browser:

```js
// run this *after* including the forge script
forge.options.usePureJavaScript = true;
```

To disable native code when using Node.js:

```js
var forge = require('node-forge');
forge.options.usePureJavaScript = true;
```

Transports
----------

<a name="tls" />

### TLS

Provides a native javascript client and server-side [TLS][] implementation.

__Examples__

```js
// create TLS client
var client = forge.tls.createConnection({
  server: false,
  caStore: /* Array of PEM-formatted certs or a CA store object */,
  sessionCache: {},
  // supported cipher suites in order of preference
  cipherSuites: [
    forge.tls.CipherSuites.TLS_RSA_WITH_AES_128_CBC_SHA,
    forge.tls.CipherSuites.TLS_RSA_WITH_AES_256_CBC_SHA],
  virtualHost: 'example.com',
  verify: function(connection, verified, depth, certs) {
    if(depth === 0) {
      var cn = certs[0].subject.getField('CN').value;
      if(cn !== 'example.com') {
        verified = {
          alert: forge.tls.Alert.Description.bad_certificate,
          message: 'Certificate common name does not match hostname.'
        };
      }
    }
    return verified;
  },
  connected: function(connection) {
    console.log('connected');
    // send message to server
    connection.prepare(forge.util.encodeUtf8('Hi server!'));
    /* NOTE: experimental, start heartbeat retransmission timer
    myHeartbeatTimer = setInterval(function() {
      connection.prepareHeartbeatRequest(forge.util.createBuffer('1234'));
    }, 5*60*1000);*/
  },
  /* provide a client-side cert if you want
  getCertificate: function(connection, hint) {
    return myClientCertificate;
  },
  /* the private key for the client-side cert if provided */
  getPrivateKey: function(connection, cert) {
    return myClientPrivateKey;
  },
  tlsDataReady: function(connection) {
    // TLS data (encrypted) is ready to be sent to the server
    sendToServerSomehow(connection.tlsData.getBytes());
    // if you were communicating with the server below, you'd do:
    // server.process(connection.tlsData.getBytes());
  },
  dataReady: function(connection) {
    // clear data from the server is ready
    console.log('the server sent: ' +
      forge.util.decodeUtf8(connection.data.getBytes()));
    // close connection
    connection.close();
  },
  /* NOTE: experimental
  heartbeatReceived: function(connection, payload) {
    // restart retransmission timer, look at payload
    clearInterval(myHeartbeatTimer);
    myHeartbeatTimer = setInterval(function() {
      connection.prepareHeartbeatRequest(forge.util.createBuffer('1234'));
    }, 5*60*1000);
    payload.getBytes();
  },*/
  closed: function(connection) {
    console.log('disconnected');
  },
  error: function(connection, error) {
    console.log('uh oh', error);
  }
});

// start the handshake process
client.handshake();

// when encrypted TLS data is received from the server, process it
client.process(encryptedBytesFromServer);

// create TLS server
var server = forge.tls.createConnection({
  server: true,
  caStore: /* Array of PEM-formatted certs or a CA store object */,
  sessionCache: {},
  // supported cipher suites in order of preference
  cipherSuites: [
    forge.tls.CipherSuites.TLS_RSA_WITH_AES_128_CBC_SHA,
    forge.tls.CipherSuites.TLS_RSA_WITH_AES_256_CBC_SHA],
  // require a client-side certificate if you want
  verifyClient: true,
  verify: function(connection, verified, depth, certs) {
    if(depth === 0) {
      var cn = certs[0].subject.getField('CN').value;
      if(cn !== 'the-client') {
        verified = {
          alert: forge.tls.Alert.Description.bad_certificate,
          message: 'Certificate common name does not match expected client.'
        };
      }
    }
    return verified;
  },
  connected: function(connection) {
    console.log('connected');
    // send message to client
    connection.prepare(forge.util.encodeUtf8('Hi client!'));
    /* NOTE: experimental, start heartbeat retransmission timer
    myHeartbeatTimer = setInterval(function() {
      connection.prepareHeartbeatRequest(forge.util.createBuffer('1234'));
    }, 5*60*1000);*/
  },
  getCertificate: function(connection, hint) {
    return myServerCertificate;
  },
  getPrivateKey: function(connection, cert) {
    return myServerPrivateKey;
  },
  tlsDataReady: function(connection) {
    // TLS data (encrypted) is ready to be sent to the client
    sendToClientSomehow(connection.tlsData.getBytes());
    // if you were communicating with the client above you'd do:
    // client.process(connection.tlsData.getBytes());
  },
  dataReady: function(connection) {
    // clear data from the client is ready
    console.log('the client sent: ' +
      forge.util.decodeUtf8(connection.data.getBytes()));
    // close connection
    connection.close();
  },
  /* NOTE: experimental
  heartbeatReceived: function(connection, payload) {
    // restart retransmission timer, look at payload
    clearInterval(myHeartbeatTimer);
    myHeartbeatTimer = setInterval(function() {
      connection.prepareHeartbeatRequest(forge.util.createBuffer('1234'));
    }, 5*60*1000);
    payload.getBytes();
  },*/
  closed: function(connection) {
    console.log('disconnected');
  },
  error: function(connection, error) {
    console.log('uh oh', error);
  }
});

// when encrypted TLS data is received from the client, process it
server.process(encryptedBytesFromClient);
```

Connect to a TLS server using node's net.Socket:

```js
var socket = new net.Socket();

var client = forge.tls.createConnection({
  server: false,
  verify: function(connection, verified, depth, certs) {
    // skip verification for testing
    console.log('[tls] server certificate verified');
    return true;
  },
  connected: function(connection) {
    console.log('[tls] connected');
    // prepare some data to send (note that the string is interpreted as
    // 'binary' encoded, which works for HTTP which only uses ASCII, use
    // forge.util.encodeUtf8(str) otherwise
    client.prepare('GET / HTTP/1.0\r\n\r\n');
  },
  tlsDataReady: function(connection) {
    // encrypted data is ready to be sent to the server
    var data = connection.tlsData.getBytes();
    socket.write(data, 'binary'); // encoding should be 'binary'
  },
  dataReady: function(connection) {
    // clear data from the server is ready
    var data = connection.data.getBytes();
    console.log('[tls] data received from the server: ' + data);
  },
  closed: function() {
    console.log('[tls] disconnected');
  },
  error: function(connection, error) {
    console.log('[tls] error', error);
  }
});

socket.on('connect', function() {
  console.log('[socket] connected');
  client.handshake();
});
socket.on('data', function(data) {
  client.process(data.toString('binary')); // encoding should be 'binary'
});
socket.on('end', function() {
  console.log('[socket] disconnected');
});

// connect to google.com
socket.connect(443, 'google.com');

// or connect to gmail's imap server (but don't send the HTTP header above)
//socket.connect(993, 'imap.gmail.com');
```

<a name="http" />

### HTTP

Provides a native [JavaScript][] mini-implementation of an http client that
uses pooled sockets.

__Examples__

```js
// create an HTTP GET request
var request = forge.http.createRequest({method: 'GET', path: url.path});

// send the request somewhere
sendSomehow(request.toString());

// receive response
var buffer = forge.util.createBuffer();
var response = forge.http.createResponse();
var someAsyncDataHandler = function(bytes) {
  if(!response.bodyReceived) {
    buffer.putBytes(bytes);
    if(!response.headerReceived) {
      if(response.readHeader(buffer)) {
        console.log('HTTP response header: ' + response.toString());
      }
    }
    if(response.headerReceived && !response.bodyReceived) {
      if(response.readBody(buffer)) {
        console.log('HTTP response body: ' + response.body);
      }
    }
  }
};
```

<a name="ssh" />

### SSH

Provides some SSH utility functions.

__Examples__

```js
// encodes (and optionally encrypts) a private RSA key as a Putty PPK file
forge.ssh.privateKeyToPutty(privateKey, passphrase, comment);

// encodes a public RSA key as an OpenSSH file
forge.ssh.publicKeyToOpenSSH(key, comment);

// encodes a private RSA key as an OpenSSH file
forge.ssh.privateKeyToOpenSSH(privateKey, passphrase);

// gets the SSH public key fingerprint in a byte buffer
forge.ssh.getPublicKeyFingerprint(key);

// gets a hex-encoded, colon-delimited SSH public key fingerprint
forge.ssh.getPublicKeyFingerprint(key, {encoding: 'hex', delimiter: ':'});
```

<a name="xhr" />

### XHR

Provides an XmlHttpRequest implementation using forge.http as a backend.

__Examples__

```js
// TODO
```

<a name="socket" />

### Sockets

Provides an interface to create and use raw sockets provided via Flash.

__Examples__

```js
// TODO
```

Ciphers
-------

<a name="cipher" />

### CIPHER

Provides a basic API for block encryption and decryption. There is built-in
support for the ciphers: [AES][], [3DES][], and [DES][], and for the modes
of operation: [ECB][], [CBC][], [CFB][], [OFB][], [CTR][], and [GCM][].

These algorithms are currently supported:

* AES-ECB
* AES-CBC
* AES-CFB
* AES-OFB
* AES-CTR
* AES-GCM
* 3DES-ECB
* 3DES-CBC
* DES-ECB
* DES-CBC

When using an [AES][] algorithm, the key size will determine whether
AES-128, AES-192, or AES-256 is used (all are supported). When a [DES][]
algorithm is used, the key size will determine whether [3DES][] or regular
[DES][] is used. Use a [3DES][] algorithm to enforce Triple-DES.

__Examples__

```js
// generate a random key and IV
// Note: a key size of 16 bytes will use AES-128, 24 => AES-192, 32 => AES-256
var key = forge.random.getBytesSync(16);
var iv = forge.random.getBytesSync(16);

/* alternatively, generate a password-based 16-byte key
var salt = forge.random.getBytesSync(128);
var key = forge.pkcs5.pbkdf2('password', salt, numIterations, 16);
*/

// encrypt some bytes using CBC mode
// (other modes include: ECB, CFB, OFB, CTR, and GCM)
// Note: CBC and ECB modes use PKCS#7 padding as default
var cipher = forge.cipher.createCipher('AES-CBC', key);
cipher.start({iv: iv});
cipher.update(forge.util.createBuffer(someBytes));
cipher.finish();
var encrypted = cipher.output;
// outputs encrypted hex
console.log(encrypted.toHex());

// decrypt some bytes using CBC mode
// (other modes include: CFB, OFB, CTR, and GCM)
var decipher = forge.cipher.createDecipher('AES-CBC', key);
decipher.start({iv: iv});
decipher.update(encrypted);
var result = decipher.finish(); // check 'result' for true/false
// outputs decrypted hex
console.log(decipher.output.toHex());

// decrypt bytes using CBC mode and streaming
// Performance can suffer for large multi-MB inputs due to buffer
// manipulations. Stream processing in chunks can offer significant
// improvement. CPU intensive update() calls could also be performed with
// setImmediate/setTimeout to avoid blocking the main browser UI thread (not
// shown here). Optimal block size depends on the JavaScript VM and other
// factors. Encryption can use a simple technique for increased performance.
var encryptedBytes = encrypted.bytes();
var decipher = forge.cipher.createDecipher('AES-CBC', key);
decipher.start({iv: iv});
var length = encryptedBytes.length;
var chunkSize = 1024 * 64;
var index = 0;
var decrypted = '';
do {
  decrypted += decipher.output.getBytes();
  var buf = forge.util.createBuffer(encryptedBytes.substr(index, chunkSize));
  decipher.update(buf);
  index += chunkSize;
} while(index < length);
var result = decipher.finish();
assert(result);
decrypted += decipher.output.getBytes();
console.log(forge.util.bytesToHex(decrypted));

// encrypt some bytes using GCM mode
var cipher = forge.cipher.createCipher('AES-GCM', key);
cipher.start({
  iv: iv, // should be a 12-byte binary-encoded string or byte buffer
  additionalData: 'binary-encoded string', // optional
  tagLength: 128 // optional, defaults to 128 bits
});
cipher.update(forge.util.createBuffer(someBytes));
cipher.finish();
var encrypted = cipher.output;
var tag = cipher.mode.tag;
// outputs encrypted hex
console.log(encrypted.toHex());
// outputs authentication tag
console.log(tag.toHex());

// decrypt some bytes using GCM mode
var decipher = forge.cipher.createDecipher('AES-GCM', key);
decipher.start({
  iv: iv,
  additionalData: 'binary-encoded string', // optional
  tagLength: 128, // optional, defaults to 128 bits
  tag: tag // authentication tag from encryption
});
decipher.update(encrypted);
var pass = decipher.finish();
// pass is false if there was a failure (eg: authentication tag didn't match)
if(pass) {
  // outputs decrypted hex
  console.log(decipher.output.toHex());
}
```

Using forge in Node.js to match openssl's "enc" command line tool (**Note**: OpenSSL "enc" uses a non-standard file format with a custom key derivation function and a fixed iteration count of 1, which some consider less secure than alternatives such as [OpenPGP](https://tools.ietf.org/html/rfc4880)/[GnuPG](https://www.gnupg.org/)):

```js
var forge = require('node-forge');
var fs = require('fs');

// openssl enc -des3 -in input.txt -out input.enc
function encrypt(password) {
  var input = fs.readFileSync('input.txt', {encoding: 'binary'});

  // 3DES key and IV sizes
  var keySize = 24;
  var ivSize = 8;

  // get derived bytes
  // Notes:
  // 1. If using an alternative hash (eg: "-md sha1") pass
  //   "forge.md.sha1.create()" as the final parameter.
  // 2. If using "-nosalt", set salt to null.
  var salt = forge.random.getBytesSync(8);
  // var md = forge.md.sha1.create(); // "-md sha1"
  var derivedBytes = forge.pbe.opensslDeriveBytes(
    password, salt, keySize + ivSize/*, md*/);
  var buffer = forge.util.createBuffer(derivedBytes);
  var key = buffer.getBytes(keySize);
  var iv = buffer.getBytes(ivSize);

  var cipher = forge.cipher.createCipher('3DES-CBC', key);
  cipher.start({iv: iv});
  cipher.update(forge.util.createBuffer(input, 'binary'));
  cipher.finish();

  var output = forge.util.createBuffer();

  // if using a salt, prepend this to the output:
  if(salt !== null) {
    output.putBytes('Salted__'); // (add to match openssl tool output)
    output.putBytes(salt);
  }
  output.putBuffer(cipher.output);

  fs.writeFileSync('input.enc', output.getBytes(), {encoding: 'binary'});
}

// openssl enc -d -des3 -in input.enc -out input.dec.txt
function decrypt(password) {
  var input = fs.readFileSync('input.enc', {encoding: 'binary'});

  // parse salt from input
  input = forge.util.createBuffer(input, 'binary');
  // skip "Salted__" (if known to be present)
  input.getBytes('Salted__'.length);
  // read 8-byte salt
  var salt = input.getBytes(8);

  // Note: if using "-nosalt", skip above parsing and use
  // var salt = null;

  // 3DES key and IV sizes
  var keySize = 24;
  var ivSize = 8;

  var derivedBytes = forge.pbe.opensslDeriveBytes(
    password, salt, keySize + ivSize);
  var buffer = forge.util.createBuffer(derivedBytes);
  var key = buffer.getBytes(keySize);
  var iv = buffer.getBytes(ivSize);

  var decipher = forge.cipher.createDecipher('3DES-CBC', key);
  decipher.start({iv: iv});
  decipher.update(input);
  var result = decipher.finish(); // check 'result' for true/false

  fs.writeFileSync(
    'input.dec.txt', decipher.output.getBytes(), {encoding: 'binary'});
}
```

<a name="aes" />

### AES

Provides [AES][] encryption and decryption in [CBC][], [CFB][], [OFB][],
[CTR][], and [GCM][] modes. See [CIPHER](#cipher) for examples.

<a name="des" />

### DES

Provides [3DES][] and [DES][] encryption and decryption in [ECB][] and
[CBC][] modes. See [CIPHER](#cipher) for examples.

<a name="rc2" />

### RC2

__Examples__

```js
// generate a random key and IV
var key = forge.random.getBytesSync(16);
var iv = forge.random.getBytesSync(8);

// encrypt some bytes
var cipher = forge.rc2.createEncryptionCipher(key);
cipher.start(iv);
cipher.update(forge.util.createBuffer(someBytes));
cipher.finish();
var encrypted = cipher.output;
// outputs encrypted hex
console.log(encrypted.toHex());

// decrypt some bytes
var cipher = forge.rc2.createDecryptionCipher(key);
cipher.start(iv);
cipher.update(encrypted);
cipher.finish();
// outputs decrypted hex
console.log(cipher.output.toHex());
```

PKI
---

Provides [X.509][] certificate support, ED25519 key generation and
signing/verifying, and RSA public and private key encoding, decoding,
encryption/decryption, and signing/verifying.

<a name="ed25519" />

### ED25519

Special thanks to [TweetNaCl.js][] for providing the bulk of the implementation.

__Examples__

```js
var ed25519 = forge.pki.ed25519;

// generate a random ED25519 keypair
var keypair = ed25519.generateKeyPair();
// `keypair.publicKey` is a node.js Buffer or Uint8Array
// `keypair.privateKey` is a node.js Buffer or Uint8Array

// generate a random ED25519 keypair based on a random 32-byte seed
var seed = forge.random.getBytesSync(32);
var keypair = ed25519.generateKeyPair({seed: seed});

// generate a random ED25519 keypair based on a "password" 32-byte seed
var password = 'Mai9ohgh6ahxee0jutheew0pungoozil';
var seed = new forge.util.ByteBuffer(password, 'utf8');
var keypair = ed25519.generateKeyPair({seed: seed});

// sign a UTF-8 message
var signature = ED25519.sign({
  message: 'test',
  // also accepts `binary` if you want to pass a binary string
  encoding: 'utf8',
  // node.js Buffer, Uint8Array, forge ByteBuffer, binary string
  privateKey: privateKey
});
// `signature` is a node.js Buffer or Uint8Array

// sign a message passed as a buffer
var signature = ED25519.sign({
  // also accepts a forge ByteBuffer or Uint8Array
  message: Buffer.from('test', 'utf8'),
  privateKey: privateKey
});

// sign a message digest (shorter "message" == better performance)
var md = forge.md.sha256.create();
md.update('test', 'utf8');
var signature = ED25519.sign({
  md: md,
  privateKey: privateKey
});

// verify a signature on a UTF-8 message
var verified = ED25519.verify({
  message: 'test',
  encoding: 'utf8',
  // node.js Buffer, Uint8Array, forge ByteBuffer, or binary string
  signature: signature,
  // node.js Buffer, Uint8Array, forge ByteBuffer, or binary string
  publicKey: publicKey
});
// `verified` is true/false

// sign a message passed as a buffer
var verified = ED25519.verify({
  // also accepts a forge ByteBuffer or Uint8Array
  message: Buffer.from('test', 'utf8'),
  // node.js Buffer, Uint8Array, forge ByteBuffer, or binary string
  signature: signature,
  // node.js Buffer, Uint8Array, forge ByteBuffer, or binary string
  publicKey: publicKey
});

// verify a signature on a message digest
var md = forge.md.sha256.create();
md.update('test', 'utf8');
var verified = ED25519.verify({
  md: md,
  // node.js Buffer, Uint8Array, forge ByteBuffer, or binary string
  signature: signature,
  // node.js Buffer, Uint8Array, forge ByteBuffer, or binary string
  publicKey: publicKey
});
```

<a name="rsa" />

### RSA

__Examples__

```js
var rsa = forge.pki.rsa;

// generate an RSA key pair synchronously
// *NOT RECOMMENDED*: Can be significantly slower than async and may block
// JavaScript execution. Will use native Node.js 10.12.0+ API if possible.
var keypair = rsa.generateKeyPair({bits: 2048, e: 0x10001});

// generate an RSA key pair asynchronously (uses web workers if available)
// use workers: -1 to run a fast core estimator to optimize # of workers
// *RECOMMENDED*: Can be significantly faster than sync. Will use native
// Node.js 10.12.0+ or WebCrypto API if possible.
rsa.generateKeyPair({bits: 2048, workers: 2}, function(err, keypair) {
  // keypair.privateKey, keypair.publicKey
});

// generate an RSA key pair in steps that attempt to run for a specified period
// of time on the main JS thread
var state = rsa.createKeyPairGenerationState(2048, 0x10001);
var step = function() {
  // run for 100 ms
  if(!rsa.stepKeyPairGenerationState(state, 100)) {
    setTimeout(step, 1);
  }
  else {
    // done, turn off progress indicator, use state.keys
  }
};
// turn on progress indicator, schedule generation to run
setTimeout(step);

// sign data with a private key and output DigestInfo DER-encoded bytes
// (defaults to RSASSA PKCS#1 v1.5)
var md = forge.md.sha1.create();
md.update('sign this', 'utf8');
var signature = privateKey.sign(md);

// verify data with a public key
// (defaults to RSASSA PKCS#1 v1.5)
var verified = publicKey.verify(md.digest().bytes(), signature);

// sign data using RSASSA-PSS where PSS uses a SHA-1 hash, a SHA-1 based
// masking function MGF1, and a 20 byte salt
var md = forge.md.sha1.create();
md.update('sign this', 'utf8');
var pss = forge.pss.create({
  md: forge.md.sha1.create(),
  mgf: forge.mgf.mgf1.create(forge.md.sha1.create()),
  saltLength: 20
  // optionally pass 'prng' with a custom PRNG implementation
  // optionalls pass 'salt' with a forge.util.ByteBuffer w/custom salt
});
var signature = privateKey.sign(md, pss);

// verify RSASSA-PSS signature
var pss = forge.pss.create({
  md: forge.md.sha1.create(),
  mgf: forge.mgf.mgf1.create(forge.md.sha1.create()),
  saltLength: 20
  // optionally pass 'prng' with a custom PRNG implementation
});
var md = forge.md.sha1.create();
md.update('sign this', 'utf8');
publicKey.verify(md.digest().getBytes(), signature, pss);

// encrypt data with a public key (defaults to RSAES PKCS#1 v1.5)
var encrypted = publicKey.encrypt(bytes);

// decrypt data with a private key (defaults to RSAES PKCS#1 v1.5)
var decrypted = privateKey.decrypt(encrypted);

// encrypt data with a public key using RSAES PKCS#1 v1.5
var encrypted = publicKey.encrypt(bytes, 'RSAES-PKCS1-V1_5');

// decrypt data with a private key using RSAES PKCS#1 v1.5
var decrypted = privateKey.decrypt(encrypted, 'RSAES-PKCS1-V1_5');

// encrypt data with a public key using RSAES-OAEP
var encrypted = publicKey.encrypt(bytes, 'RSA-OAEP');

// decrypt data with a private key using RSAES-OAEP
var decrypted = privateKey.decrypt(encrypted, 'RSA-OAEP');

// encrypt data with a public key using RSAES-OAEP/SHA-256
var encrypted = publicKey.encrypt(bytes, 'RSA-OAEP', {
  md: forge.md.sha256.create()
});

// decrypt data with a private key using RSAES-OAEP/SHA-256
var decrypted = privateKey.decrypt(encrypted, 'RSA-OAEP', {
  md: forge.md.sha256.create()
});

// encrypt data with a public key using RSAES-OAEP/SHA-256/MGF1-SHA-1
// compatible with Java's RSA/ECB/OAEPWithSHA-256AndMGF1Padding
var encrypted = publicKey.encrypt(bytes, 'RSA-OAEP', {
  md: forge.md.sha256.create(),
  mgf1: {
    md: forge.md.sha1.create()
  }
});

// decrypt data with a private key using RSAES-OAEP/SHA-256/MGF1-SHA-1
// compatible with Java's RSA/ECB/OAEPWithSHA-256AndMGF1Padding
var decrypted = privateKey.decrypt(encrypted, 'RSA-OAEP', {
  md: forge.md.sha256.create(),
  mgf1: {
    md: forge.md.sha1.create()
  }
});

```

<a name="rsakem" />

### RSA-KEM

__Examples__

```js
// generate an RSA key pair asynchronously (uses web workers if available)
// use workers: -1 to run a fast core estimator to optimize # of workers
forge.rsa.generateKeyPair({bits: 2048, workers: -1}, function(err, keypair) {
  // keypair.privateKey, keypair.publicKey
});

// generate and encapsulate a 16-byte secret key
var kdf1 = new forge.kem.kdf1(forge.md.sha1.create());
var kem = forge.kem.rsa.create(kdf1);
var result = kem.encrypt(keypair.publicKey, 16);
// result has 'encapsulation' and 'key'

// encrypt some bytes
var iv = forge.random.getBytesSync(12);
var someBytes = 'hello world!';
var cipher = forge.cipher.createCipher('AES-GCM', result.key);
cipher.start({iv: iv});
cipher.update(forge.util.createBuffer(someBytes));
cipher.finish();
var encrypted = cipher.output.getBytes();
var tag = cipher.mode.tag.getBytes();

// send 'encrypted', 'iv', 'tag', and result.encapsulation to recipient

// decrypt encapsulated 16-byte secret key
var kdf1 = new forge.kem.kdf1(forge.md.sha1.create());
var kem = forge.kem.rsa.create(kdf1);
var key = kem.decrypt(keypair.privateKey, result.encapsulation, 16);

// decrypt some bytes
var decipher = forge.cipher.createDecipher('AES-GCM', key);
decipher.start({iv: iv, tag: tag});
decipher.update(forge.util.createBuffer(encrypted));
var pass = decipher.finish();
// pass is false if there was a failure (eg: authentication tag didn't match)
if(pass) {
  // outputs 'hello world!'
  console.log(decipher.output.getBytes());
}

```

<a name="x509" />

### X.509

__Examples__

```js
var pki = forge.pki;

// convert a PEM-formatted public key to a Forge public key
var publicKey = pki.publicKeyFromPem(pem);

// convert a Forge public key to PEM-format
var pem = pki.publicKeyToPem(publicKey);

// convert an ASN.1 SubjectPublicKeyInfo to a Forge public key
var publicKey = pki.publicKeyFromAsn1(subjectPublicKeyInfo);

// convert a Forge public key to an ASN.1 SubjectPublicKeyInfo
var subjectPublicKeyInfo = pki.publicKeyToAsn1(publicKey);

// gets a SHA-1 RSAPublicKey fingerprint a byte buffer
pki.getPublicKeyFingerprint(key);

// gets a SHA-1 SubjectPublicKeyInfo fingerprint a byte buffer
pki.getPublicKeyFingerprint(key, {type: 'SubjectPublicKeyInfo'});

// gets a hex-encoded, colon-delimited SHA-1 RSAPublicKey public key fingerprint
pki.getPublicKeyFingerprint(key, {encoding: 'hex', delimiter: ':'});

// gets a hex-encoded, colon-delimited SHA-1 SubjectPublicKeyInfo public key fingerprint
pki.getPublicKeyFingerprint(key, {
  type: 'SubjectPublicKeyInfo',
  encoding: 'hex',
  delimiter: ':'
});

// gets a hex-encoded, colon-delimited MD5 RSAPublicKey public key fingerprint
pki.getPublicKeyFingerprint(key, {
  md: forge.md.md5.create(),
  encoding: 'hex',
  delimiter: ':'
});

// creates a CA store
var caStore = pki.createCaStore([/* PEM-encoded cert */, ...]);

// add a certificate to the CA store
caStore.addCertificate(certObjectOrPemString);

// gets the issuer (its certificate) for the given certificate
var issuerCert = caStore.getIssuer(subjectCert);

// verifies a certificate chain against a CA store
pki.verifyCertificateChain(caStore, chain, customVerifyCallback);

// signs a certificate using the given private key
cert.sign(privateKey);

// signs a certificate using SHA-256 instead of SHA-1
cert.sign(privateKey, forge.md.sha256.create());

// verifies an issued certificate using the certificates public key
var verified = issuer.verify(issued);

// generate a keypair and create an X.509v3 certificate
var keys = pki.rsa.generateKeyPair(2048);
var cert = pki.createCertificate();
cert.publicKey = keys.publicKey;
// alternatively set public key from a csr
//cert.publicKey = csr.publicKey;
// NOTE: serialNumber is the hex encoded value of an ASN.1 INTEGER.
// Conforming CAs should ensure serialNumber is:
// - no more than 20 octets
// - non-negative (prefix a '00' if your value starts with a '1' bit)
cert.serialNumber = '01';
cert.validity.notBefore = new Date();
cert.validity.notAfter = new Date();
cert.validity.notAfter.setFullYear(cert.validity.notBefore.getFullYear() + 1);
var attrs = [{
  name: 'commonName',
  value: 'example.org'
}, {
  name: 'countryName',
  value: 'US'
}, {
  shortName: 'ST',
  value: 'Virginia'
}, {
  name: 'localityName',
  value: 'Blacksburg'
}, {
  name: 'organizationName',
  value: 'Test'
}, {
  shortName: 'OU',
  value: 'Test'
}];
cert.setSubject(attrs);
// alternatively set subject from a csr
//cert.setSubject(csr.subject.attributes);
cert.setIssuer(attrs);
cert.setExtensions([{
  name: 'basicConstraints',
  cA: true
}, {
  name: 'keyUsage',
  keyCertSign: true,
  digitalSignature: true,
  nonRepudiation: true,
  keyEncipherment: true,
  dataEncipherment: true
}, {
  name: 'extKeyUsage',
  serverAuth: true,
  clientAuth: true,
  codeSigning: true,
  emailProtection: true,
  timeStamping: true
}, {
  name: 'nsCertType',
  client: true,
  server: true,
  email: true,
  objsign: true,
  sslCA: true,
  emailCA: true,
  objCA: true
}, {
  name: 'subjectAltName',
  altNames: [{
    type: 6, // URI
    value: 'http://example.org/webid#me'
  }, {
    type: 7, // IP
    ip: '127.0.0.1'
  }]
}, {
  name: 'subjectKeyIdentifier'
}]);
/* alternatively set extensions from a csr
var extensions = csr.getAttribute({name: 'extensionRequest'}).extensions;
// optionally add more extensions
extensions.push.apply(extensions, [{
  name: 'basicConstraints',
  cA: true
}, {
  name: 'keyUsage',
  keyCertSign: true,
  digitalSignature: true,
  nonRepudiation: true,
  keyEncipherment: true,
  dataEncipherment: true
}]);
cert.setExtensions(extensions);
*/
// self-sign certificate
cert.sign(keys.privateKey);

// convert a Forge certificate to PEM
var pem = pki.certificateToPem(cert);

// convert a Forge certificate from PEM
var cert = pki.certificateFromPem(pem);

// convert an ASN.1 X.509x3 object to a Forge certificate
var cert = pki.certificateFromAsn1(obj);

// convert a Forge certificate to an ASN.1 X.509v3 object
var asn1Cert = pki.certificateToAsn1(cert);
```

<a name="pkcs5" />

### PKCS#5

Provides the password-based key-derivation function from [PKCS#5][].

__Examples__

```js
// generate a password-based 16-byte key
// note an optional message digest can be passed as the final parameter
var salt = forge.random.getBytesSync(128);
var derivedKey = forge.pkcs5.pbkdf2('password', salt, numIterations, 16);

// generate key asynchronously
// note an optional message digest can be passed before the callback
forge.pkcs5.pbkdf2('password', salt, numIterations, 16, function(err, derivedKey) {
  // do something w/derivedKey
});
```

<a name="pkcs7" />

### PKCS#7

Provides cryptographically protected messages from [PKCS#7][].

__Examples__

```js
// convert a message from PEM
var p7 = forge.pkcs7.messageFromPem(pem);
// look at p7.recipients

// find a recipient by the issuer of a certificate
var recipient = p7.findRecipient(cert);

// decrypt
p7.decrypt(p7.recipients[0], privateKey);

// create a p7 enveloped message
var p7 = forge.pkcs7.createEnvelopedData();

// add a recipient
var cert = forge.pki.certificateFromPem(certPem);
p7.addRecipient(cert);

// set content
p7.content = forge.util.createBuffer('Hello');

// encrypt
p7.encrypt();

// convert message to PEM
var pem = forge.pkcs7.messageToPem(p7);

// create a degenerate PKCS#7 certificate container
// (CRLs not currently supported, only certificates)
var p7 = forge.pkcs7.createSignedData();
p7.addCertificate(certOrCertPem1);
p7.addCertificate(certOrCertPem2);
var pem = forge.pkcs7.messageToPem(p7);

// create PKCS#7 signed data with authenticatedAttributes
// attributes include: PKCS#9 content-type, message-digest, and signing-time
var p7 = forge.pkcs7.createSignedData();
p7.content = forge.util.createBuffer('Some content to be signed.', 'utf8');
p7.addCertificate(certOrCertPem);
p7.addSigner({
  key: privateKeyAssociatedWithCert,
  certificate: certOrCertPem,
  digestAlgorithm: forge.pki.oids.sha256,
  authenticatedAttributes: [{
    type: forge.pki.oids.contentType,
    value: forge.pki.oids.data
  }, {
    type: forge.pki.oids.messageDigest
    // value will be auto-populated at signing time
  }, {
    type: forge.pki.oids.signingTime,
    // value can also be auto-populated at signing time
    value: new Date()
  }]
});
p7.sign();
var pem = forge.pkcs7.messageToPem(p7);

// PKCS#7 Sign in detached mode.
// Includes the signature and certificate without the signed data.
p7.sign({detached: true});

```

<a name="pkcs8" />

### PKCS#8

__Examples__

```js
var pki = forge.pki;

// convert a PEM-formatted private key to a Forge private key
var privateKey = pki.privateKeyFromPem(pem);

// convert a Forge private key to PEM-format
var pem = pki.privateKeyToPem(privateKey);

// convert an ASN.1 PrivateKeyInfo or RSAPrivateKey to a Forge private key
var privateKey = pki.privateKeyFromAsn1(rsaPrivateKey);

// convert a Forge private key to an ASN.1 RSAPrivateKey
var rsaPrivateKey = pki.privateKeyToAsn1(privateKey);

// wrap an RSAPrivateKey ASN.1 object in a PKCS#8 ASN.1 PrivateKeyInfo
var privateKeyInfo = pki.wrapRsaPrivateKey(rsaPrivateKey);

// convert a PKCS#8 ASN.1 PrivateKeyInfo to PEM
var pem = pki.privateKeyInfoToPem(privateKeyInfo);

// encrypts a PrivateKeyInfo using a custom password and
// outputs an EncryptedPrivateKeyInfo
var encryptedPrivateKeyInfo = pki.encryptPrivateKeyInfo(
  privateKeyInfo, 'myCustomPasswordHere', {
    algorithm: 'aes256', // 'aes128', 'aes192', 'aes256', '3des'
  });

// decrypts an ASN.1 EncryptedPrivateKeyInfo that was encrypted
// with a custom password
var privateKeyInfo = pki.decryptPrivateKeyInfo(
  encryptedPrivateKeyInfo, 'myCustomPasswordHere');

// converts an EncryptedPrivateKeyInfo to PEM
var pem = pki.encryptedPrivateKeyToPem(encryptedPrivateKeyInfo);

// converts a PEM-encoded EncryptedPrivateKeyInfo to ASN.1 format
var encryptedPrivateKeyInfo = pki.encryptedPrivateKeyFromPem(pem);

// wraps and encrypts a Forge private key and outputs it in PEM format
var pem = pki.encryptRsaPrivateKey(privateKey, 'password');

// encrypts a Forge private key and outputs it in PEM format using OpenSSL's
// proprietary legacy format + encapsulated PEM headers (DEK-Info)
var pem = pki.encryptRsaPrivateKey(privateKey, 'password', {legacy: true});

// decrypts a PEM-formatted, encrypted private key
var privateKey = pki.decryptRsaPrivateKey(pem, 'password');

// sets an RSA public key from a private key
var publicKey = pki.setRsaPublicKey(privateKey.n, privateKey.e);
```

<a name="pkcs10" />

### PKCS#10

Provides certification requests or certificate signing requests (CSR) from
[PKCS#10][].

__Examples__

```js
// generate a key pair
var keys = forge.pki.rsa.generateKeyPair(2048);

// create a certification request (CSR)
var csr = forge.pki.createCertificationRequest();
csr.publicKey = keys.publicKey;
csr.setSubject([{
  name: 'commonName',
  value: 'example.org'
}, {
  name: 'countryName',
  value: 'US'
}, {
  shortName: 'ST',
  value: 'Virginia'
}, {
  name: 'localityName',
  value: 'Blacksburg'
}, {
  name: 'organizationName',
  value: 'Test'
}, {
  shortName: 'OU',
  value: 'Test'
}]);
// set (optional) attributes
csr.setAttributes([{
  name: 'challengePassword',
  value: 'password'
}, {
  name: 'unstructuredName',
  value: 'My Company, Inc.'
}, {
  name: 'extensionRequest',
  extensions: [{
    name: 'subjectAltName',
    altNames: [{
      // 2 is DNS type
      type: 2,
      value: 'test.domain.com'
    }, {
      type: 2,
      value: 'other.domain.com',
    }, {
      type: 2,
      value: 'www.domain.net'
    }]
  }]
}]);

// sign certification request
csr.sign(keys.privateKey);

// verify certification request
var verified = csr.verify();

// convert certification request to PEM-format
var pem = forge.pki.certificationRequestToPem(csr);

// convert a Forge certification request from PEM-format
var csr = forge.pki.certificationRequestFromPem(pem);

// get an attribute
csr.getAttribute({name: 'challengePassword'});

// get extensions array
csr.getAttribute({name: 'extensionRequest'}).extensions;

```

<a name="pkcs12" />

### PKCS#12

Provides the cryptographic archive file format from [PKCS#12][].

**Note for Chrome/Firefox/iOS/similar users**: If you have trouble importing
a PKCS#12 container, try using the TripleDES algorithm. It can be passed
to `forge.pkcs12.toPkcs12Asn1` using the `{algorithm: '3des'}` option.

__Examples__

```js
// decode p12 from base64
var p12Der = forge.util.decode64(p12b64);
// get p12 as ASN.1 object
var p12Asn1 = forge.asn1.fromDer(p12Der);
// decrypt p12 using the password 'password'
var p12 = forge.pkcs12.pkcs12FromAsn1(p12Asn1, 'password');
// decrypt p12 using non-strict parsing mode (resolves some ASN.1 parse errors)
var p12 = forge.pkcs12.pkcs12FromAsn1(p12Asn1, false, 'password');
// decrypt p12 using literally no password (eg: Mac OS X/apple push)
var p12 = forge.pkcs12.pkcs12FromAsn1(p12Asn1);
// decrypt p12 using an "empty" password (eg: OpenSSL with no password input)
var p12 = forge.pkcs12.pkcs12FromAsn1(p12Asn1, '');
// p12.safeContents is an array of safe contents, each of
// which contains an array of safeBags

// get bags by friendlyName
var bags = p12.getBags({friendlyName: 'test'});
// bags are key'd by attribute type (here "friendlyName")
// and the key values are an array of matching objects
var cert = bags.friendlyName[0];

// get bags by localKeyId
var bags = p12.getBags({localKeyId: buffer});
// bags are key'd by attribute type (here "localKeyId")
// and the key values are an array of matching objects
var cert = bags.localKeyId[0];

// get bags by localKeyId (input in hex)
var bags = p12.getBags({localKeyIdHex: '7b59377ff142d0be4565e9ac3d396c01401cd879'});
// bags are key'd by attribute type (here "localKeyId", *not* "localKeyIdHex")
// and the key values are an array of matching objects
var cert = bags.localKeyId[0];

// get bags by type
var bags = p12.getBags({bagType: forge.pki.oids.certBag});
// bags are key'd by bagType and each bagType key's value
// is an array of matches (in this case, certificate objects)
var cert = bags[forge.pki.oids.certBag][0];

// get bags by friendlyName and filter on bag type
var bags = p12.getBags({
  friendlyName: 'test',
  bagType: forge.pki.oids.certBag
});

// get key bags
var bags = p12.getBags({bagType: forge.pki.oids.keyBag});
// get key
var bag = bags[forge.pki.oids.keyBag][0];
var key = bag.key;
// if the key is in a format unrecognized by forge then
// bag.key will be `null`, use bag.asn1 to get the ASN.1
// representation of the key
if(bag.key === null) {
  var keyAsn1 = bag.asn1;
  // can now convert back to DER/PEM/etc for export
}

// generate a p12 using AES (default)
var p12Asn1 = forge.pkcs12.toPkcs12Asn1(
  privateKey, certificateChain, 'password');

// generate a p12 that can be imported by Chrome/Firefox/iOS
// (requires the use of Triple DES instead of AES)
var p12Asn1 = forge.pkcs12.toPkcs12Asn1(
  privateKey, certificateChain, 'password',
  {algorithm: '3des'});

// base64-encode p12
var p12Der = forge.asn1.toDer(p12Asn1).getBytes();
var p12b64 = forge.util.encode64(p12Der);

// create download link for p12
var a = document.createElement('a');
a.download = 'example.p12';
a.setAttribute('href', 'data:application/x-pkcs12;base64,' + p12b64);
a.appendChild(document.createTextNode('Download'));
```

<a name="asn" />

### ASN.1

Provides [ASN.1][] DER encoding and decoding.

__Examples__

```js
var asn1 = forge.asn1;

// create a SubjectPublicKeyInfo
var subjectPublicKeyInfo =
  asn1.create(asn1.Class.UNIVERSAL, asn1.Type.SEQUENCE, true, [
    // AlgorithmIdentifier
    asn1.create(asn1.Class.UNIVERSAL, asn1.Type.SEQUENCE, true, [
      // algorithm
      asn1.create(asn1.Class.UNIVERSAL, asn1.Type.OID, false,
        asn1.oidToDer(pki.oids['rsaEncryption']).getBytes()),
      // parameters (null)
      asn1.create(asn1.Class.UNIVERSAL, asn1.Type.NULL, false, '')
    ]),
    // subjectPublicKey
    asn1.create(asn1.Class.UNIVERSAL, asn1.Type.BITSTRING, false, [
      // RSAPublicKey
      asn1.create(asn1.Class.UNIVERSAL, asn1.Type.SEQUENCE, true, [
        // modulus (n)
        asn1.create(asn1.Class.UNIVERSAL, asn1.Type.INTEGER, false,
          _bnToBytes(key.n)),
        // publicExponent (e)
        asn1.create(asn1.Class.UNIVERSAL, asn1.Type.INTEGER, false,
          _bnToBytes(key.e))
      ])
    ])
  ]);

// serialize an ASN.1 object to DER format
var derBuffer = asn1.toDer(subjectPublicKeyInfo);

// deserialize to an ASN.1 object from a byte buffer filled with DER data
var object = asn1.fromDer(derBuffer);

// convert an OID dot-separated string to a byte buffer
var derOidBuffer = asn1.oidToDer('1.2.840.113549.1.1.5');

// convert a byte buffer with a DER-encoded OID to a dot-separated string
console.log(asn1.derToOid(derOidBuffer));
// output: 1.2.840.113549.1.1.5

// validates that an ASN.1 object matches a particular ASN.1 structure and
// captures data of interest from that structure for easy access
var publicKeyValidator = {
  name: 'SubjectPublicKeyInfo',
  tagClass: asn1.Class.UNIVERSAL,
  type: asn1.Type.SEQUENCE,
  constructed: true,
  captureAsn1: 'subjectPublicKeyInfo',
  value: [{
    name: 'SubjectPublicKeyInfo.AlgorithmIdentifier',
    tagClass: asn1.Class.UNIVERSAL,
    type: asn1.Type.SEQUENCE,
    constructed: true,
    value: [{
      name: 'AlgorithmIdentifier.algorithm',
      tagClass: asn1.Class.UNIVERSAL,
      type: asn1.Type.OID,
      constructed: false,
      capture: 'publicKeyOid'
    }]
  }, {
    // subjectPublicKey
    name: 'SubjectPublicKeyInfo.subjectPublicKey',
    tagClass: asn1.Class.UNIVERSAL,
    type: asn1.Type.BITSTRING,
    constructed: false,
    value: [{
      // RSAPublicKey
      name: 'SubjectPublicKeyInfo.subjectPublicKey.RSAPublicKey',
      tagClass: asn1.Class.UNIVERSAL,
      type: asn1.Type.SEQUENCE,
      constructed: true,
      optional: true,
      captureAsn1: 'rsaPublicKey'
    }]
  }]
};

var capture = {};
var errors = [];
if(!asn1.validate(
  publicKeyValidator, subjectPublicKeyInfo, validator, capture, errors)) {
  throw 'ASN.1 object is not a SubjectPublicKeyInfo.';
}
// capture.subjectPublicKeyInfo contains the full ASN.1 object
// capture.rsaPublicKey contains the full ASN.1 object for the RSA public key
// capture.publicKeyOid only contains the value for the OID
var oid = asn1.derToOid(capture.publicKeyOid);
if(oid !== pki.oids['rsaEncryption']) {
  throw 'Unsupported OID.';
}

// pretty print an ASN.1 object to a string for debugging purposes
asn1.prettyPrint(object);
```

Message Digests
----------------

<a name="sha1" />

### SHA1

Provides [SHA-1][] message digests.

__Examples__

```js
var md = forge.md.sha1.create();
md.update('The quick brown fox jumps over the lazy dog');
console.log(md.digest().toHex());
// output: 2fd4e1c67a2d28fced849ee1bb76e7391b93eb12
```

<a name="sha256" />

### SHA256

Provides [SHA-256][] message digests.

__Examples__

```js
var md = forge.md.sha256.create();
md.update('The quick brown fox jumps over the lazy dog');
console.log(md.digest().toHex());
// output: d7a8fbb307d7809469ca9abcb0082e4f8d5651e46d3cdb762d02d0bf37c9e592
```

<a name="sha384" />

### SHA384

Provides [SHA-384][] message digests.

__Examples__

```js
var md = forge.md.sha384.create();
md.update('The quick brown fox jumps over the lazy dog');
console.log(md.digest().toHex());
// output: ca737f1014a48f4c0b6dd43cb177b0afd9e5169367544c494011e3317dbf9a509cb1e5dc1e85a941bbee3d7f2afbc9b1
```

<a name="sha512" />

### SHA512

Provides [SHA-512][] message digests.

__Examples__

```js
// SHA-512
var md = forge.md.sha512.create();
md.update('The quick brown fox jumps over the lazy dog');
console.log(md.digest().toHex());
// output: 07e547d9586f6a73f73fbac0435ed76951218fb7d0c8d788a309d785436bbb642e93a252a954f23912547d1e8a3b5ed6e1bfd7097821233fa0538f3db854fee6

// SHA-512/224
var md = forge.md.sha512.sha224.create();
md.update('The quick brown fox jumps over the lazy dog');
console.log(md.digest().toHex());
// output: 944cd2847fb54558d4775db0485a50003111c8e5daa63fe722c6aa37

// SHA-512/256
var md = forge.md.sha512.sha256.create();
md.update('The quick brown fox jumps over the lazy dog');
console.log(md.digest().toHex());
// output: dd9d67b371519c339ed8dbd25af90e976a1eeefd4ad3d889005e532fc5bef04d
```

<a name="md5" />

### MD5

Provides [MD5][] message digests.

__Examples__

```js
var md = forge.md.md5.create();
md.update('The quick brown fox jumps over the lazy dog');
console.log(md.digest().toHex());
// output: 9e107d9d372bb6826bd81d3542a419d6
```

<a name="hmac" />

### HMAC

Provides [HMAC][] w/any supported message digest algorithm.

__Examples__

```js
var hmac = forge.hmac.create();
hmac.start('sha1', 'Jefe');
hmac.update('what do ya want for nothing?');
console.log(hmac.digest().toHex());
// output: effcdf6ae5eb2fa2d27416d5f184df9c259a7c79
```

Utilities
---------

<a name="prime" />

### Prime

Provides an API for generating large, random, probable primes.

__Examples__

```js
// generate a random prime on the main JS thread
var bits = 1024;
forge.prime.generateProbablePrime(bits, function(err, num) {
  console.log('random prime', num.toString(16));
});

// generate a random prime using Web Workers (if available, otherwise
// falls back to the main thread)
var bits = 1024;
var options = {
  algorithm: {
    name: 'PRIMEINC',
    workers: -1 // auto-optimize # of workers
  }
};
forge.prime.generateProbablePrime(bits, options, function(err, num) {
  console.log('random prime', num.toString(16));
});
```

<a name="prng" />

### PRNG

Provides a [Fortuna][]-based cryptographically-secure pseudo-random number
generator, to be used with a cryptographic function backend, e.g. [AES][]. An
implementation using [AES][] as a backend is provided. An API for collecting
entropy is given, though if window.crypto.getRandomValues is available, it will
be used automatically.

__Examples__

```js
// get some random bytes synchronously
var bytes = forge.random.getBytesSync(32);
console.log(forge.util.bytesToHex(bytes));

// get some random bytes asynchronously
forge.random.getBytes(32, function(err, bytes) {
  console.log(forge.util.bytesToHex(bytes));
});

// collect some entropy if you'd like
forge.random.collect(someRandomBytes);
jQuery().mousemove(function(e) {
  forge.random.collectInt(e.clientX, 16);
  forge.random.collectInt(e.clientY, 16);
});

// specify a seed file for use with the synchronous API if you'd like
forge.random.seedFileSync = function(needed) {
  // get 'needed' number of random bytes from somewhere
  return fetchedRandomBytes;
};

// specify a seed file for use with the asynchronous API if you'd like
forge.random.seedFile = function(needed, callback) {
  // get the 'needed' number of random bytes from somewhere
  callback(null, fetchedRandomBytes);
});

// register the main thread to send entropy or a Web Worker to receive
// entropy on demand from the main thread
forge.random.registerWorker(self);

// generate a new instance of a PRNG with no collected entropy
var myPrng = forge.random.createInstance();
```

<a name="task" />

### Tasks

Provides queuing and synchronizing tasks in a web application.

__Examples__

```js
// TODO
```

<a name="util" />

### Utilities

Provides utility functions, including byte buffer support, base64,
bytes to/from hex, zlib inflate/deflate, etc.

__Examples__

```js
// encode/decode base64
var encoded = forge.util.encode64(str);
var str = forge.util.decode64(encoded);

// encode/decode UTF-8
var encoded = forge.util.encodeUtf8(str);
var str = forge.util.decodeUtf8(encoded);

// bytes to/from hex
var bytes = forge.util.hexToBytes(hex);
var hex = forge.util.bytesToHex(bytes);

// create an empty byte buffer
var buffer = forge.util.createBuffer();
// create a byte buffer from raw binary bytes
var buffer = forge.util.createBuffer(input, 'raw');
// create a byte buffer from utf8 bytes
var buffer = forge.util.createBuffer(input, 'utf8');

// get the length of the buffer in bytes
buffer.length();
// put bytes into the buffer
buffer.putBytes(bytes);
// put a 32-bit integer into the buffer
buffer.putInt32(10);
// buffer to hex
buffer.toHex();
// get a copy of the bytes in the buffer
bytes.bytes(/* count */);
// empty this buffer and get its contents
bytes.getBytes(/* count */);

// convert a forge buffer into a Node.js Buffer
// make sure you specify the encoding as 'binary'
var forgeBuffer = forge.util.createBuffer();
var nodeBuffer = Buffer.from(forgeBuffer.getBytes(), 'binary');

// convert a Node.js Buffer into a forge buffer
// make sure you specify the encoding as 'binary'
var nodeBuffer = Buffer.from('CAFE', 'hex');
var forgeBuffer = forge.util.createBuffer(nodeBuffer.toString('binary'));
```

<a name="log" />

### Logging

Provides logging to a javascript console using various categories and
levels of verbosity.

__Examples__

```js
// TODO
```

<a name="flash" />

### Flash Networking Support

The [flash README](./flash/README.md) provides details on rebuilding the
optional Flash component used for networking. It also provides details on
Policy Server support.

Security Considerations
-----------------------

When using this code please keep the following in mind:

- Cryptography is hard. Please review and test this code before depending on it
  for critical functionality.
- The nature of JavaScript is that execution of this code depends on trusting a
  very large set of JavaScript tools and systems. Consider runtime variations,
  runtime characteristics, runtime optimization, code optimization, code
  minimization, code obfuscation, bundling tools, possible bugs, the Forge code
  itself, and so on.
- If using pre-built bundles from [NPM][], another CDN, or similar, be aware
  someone else ran the tools to create those files.
- Use a secure transport channel such as [TLS][] to load scripts and consider
  using additional security mechanisms such as [Subresource Integrity][] script
  attributes.
- Use "native" functionality where possible. This can be critical when dealing
  with performance and random number generation. Note that the JavaScript
  random number algorithms should perform well if given suitable entropy.
- Understand possible attacks against cryptographic systems. For instance side
  channel and timing attacks may be possible due to the difficulty in
  implementing constant time algorithms in pure JavaScript.
- Certain features in this library are less susceptible to attacks depending on
  usage. This primarily includes features that deal with data format
  manipulation or those that are not involved in communication.

Library Background
------------------

* https://digitalbazaar.com/2010/07/20/javascript-tls-1/
* https://digitalbazaar.com/2010/07/20/javascript-tls-2/

Contact
-------

* Code: https://github.com/digitalbazaar/forge
* Bugs: https://github.com/digitalbazaar/forge/issues
* Email: support@digitalbazaar.com
* IRC: [#forgejs][] on [Libera.Chat][] (people may also be on [freenode][] for
  historical reasons).

Donations
---------

Financial support is welcome and helps contribute to futher development:

* For [PayPal][] please send to paypal@digitalbazaar.com.
* Something else? Please contact support@digitalbazaar.com.

[#forgejs]: https://webchat.freenode.net/?channels=#forgejs
[0.6.x]: https://github.com/digitalbazaar/forge/tree/0.6.x
[3DES]: https://en.wikipedia.org/wiki/Triple_DES
[AES]: https://en.wikipedia.org/wiki/Advanced_Encryption_Standard
[ASN.1]: https://en.wikipedia.org/wiki/ASN.1
[Browserify]: http://browserify.org/
[CBC]: https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation
[CFB]: https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation
[CTR]: https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation
[CommonJS]: https://en.wikipedia.org/wiki/CommonJS
[DES]: https://en.wikipedia.org/wiki/Data_Encryption_Standard
[ECB]: https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation
[Fortuna]: https://en.wikipedia.org/wiki/Fortuna_(PRNG)
[GCM]: https://en.wikipedia.org/wiki/GCM_mode
[HMAC]: https://en.wikipedia.org/wiki/HMAC
[JavaScript]: https://en.wikipedia.org/wiki/JavaScript
[Karma]: https://karma-runner.github.io/
[Libera.Chat]: https://libera.chat/
[MD5]: https://en.wikipedia.org/wiki/MD5
[NPM]: https://www.npmjs.com/
[Node.js]: https://nodejs.org/
[OFB]: https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation
[PKCS#10]: https://en.wikipedia.org/wiki/Certificate_signing_request
[PKCS#12]: https://en.wikipedia.org/wiki/PKCS_%E2%99%AF12
[PKCS#5]: https://en.wikipedia.org/wiki/PKCS
[PKCS#7]: https://en.wikipedia.org/wiki/Cryptographic_Message_Syntax
[PayPal]: https://www.paypal.com/
[RC2]: https://en.wikipedia.org/wiki/RC2
[SHA-1]: https://en.wikipedia.org/wiki/SHA-1
[SHA-256]: https://en.wikipedia.org/wiki/SHA-256
[SHA-384]: https://en.wikipedia.org/wiki/SHA-384
[SHA-512]: https://en.wikipedia.org/wiki/SHA-512
[Subresource Integrity]: https://www.w3.org/TR/SRI/
[TLS]: https://en.wikipedia.org/wiki/Transport_Layer_Security
[UMD]: https://github.com/umdjs/umd
[X.509]: https://en.wikipedia.org/wiki/X.509
[freenode]: https://freenode.net/
[unpkg]: https://unpkg.com/
[webpack]: https://webpack.github.io/
[TweetNaCl.js]: https://github.com/dchest/tweetnacl-js


---

Forge Flash Support
===================

SocketPool.swf
--------------

Some special networking features can optionally use a Flash component.
Building the output SWF file requires the [Flex SDK][].  A pre-built component
is included: `swf/SocketPool.swf`.

Building the output SWF requires the `mxmlc` tool from the [Flex SDK][]. If
that tools is already installed then look in the `package.json` file for the
commands to rebuild it. If you need the SDK installed, there is a npm module that installs it:

    npm install

To build a regular component:

    npm run build

Additional debug support can be built in with the following:

    npm run build-debug

Policy Server
-------------

Flash support requires the use of a Policy Server.

### Apache Flash Socket Policy Module

[mod_fsp](./mod_fsp) provides an [Apache][] module that can serve up a Flash
Socket Policy. See `mod_fsp/README` for more details. This module makes it easy
to modify an [Apache][] server to allow cross domain requests to be made to it.

### Simple Python Policy Server

`policyserver.py` provides a very simple test policy server.

### Simple Node.js Policy Server

`policyserver.js` provides a very simple test policy server.  If a server is
needed for production environments, please use another option such as perhaps
[nodejs_socket_policy_server][].

[Apache]: http://httpd.apache.org/
[Flex SDK]: https://flex.apache.org/
[nodejs_socket_policy_server]: https://github.com/bichinger/nodejs_socket_policy_server


---

# Node.js releases data

All data is located in `data` directory.

`data/processed` contains `envs.json` with node.js releases data preprocessed to be used by [Browserslist](https://github.com/ai/browserslist) and other projects. Each version in this file contains only necessary info: version, release date, LTS flag/name, and security flag.

`data/release-schedule` contains `release-schedule.json` with node.js releases date and end of life date.

## Installation
```bash
npm install node-releases
```


---

# normalize-path [![NPM version](https://img.shields.io/npm/v/normalize-path.svg?style=flat)](https://www.npmjs.com/package/normalize-path) [![NPM monthly downloads](https://img.shields.io/npm/dm/normalize-path.svg?style=flat)](https://npmjs.org/package/normalize-path) [![NPM total downloads](https://img.shields.io/npm/dt/normalize-path.svg?style=flat)](https://npmjs.org/package/normalize-path) [![Linux Build Status](https://img.shields.io/travis/jonschlinkert/normalize-path.svg?style=flat&label=Travis)](https://travis-ci.org/jonschlinkert/normalize-path)

> Normalize slashes in a file path to be posix/unix-like forward slashes. Also condenses repeat slashes to a single slash and removes and trailing slashes, unless disabled.

Please consider following this project's author, [Jon Schlinkert](https://github.com/jonschlinkert), and consider starring the project to show your :heart: and support.

## Install

Install with [npm](https://www.npmjs.com/):

```sh
$ npm install --save normalize-path
```

## Usage

```js
const normalize = require('normalize-path');

console.log(normalize('\\foo\\bar\\baz\\')); 
//=> '/foo/bar/baz'
```

**win32 namespaces**

```js
console.log(normalize('\\\\?\\UNC\\Server01\\user\\docs\\Letter.txt')); 
//=> '//?/UNC/Server01/user/docs/Letter.txt'

console.log(normalize('\\\\.\\CdRomX')); 
//=> '//./CdRomX'
```

**Consecutive slashes**

Condenses multiple consecutive forward slashes (except for leading slashes in win32 namespaces) to a single slash.

```js
console.log(normalize('.//foo//bar///////baz/')); 
//=> './foo/bar/baz'
```

### Trailing slashes

By default trailing slashes are removed. Pass `false` as the last argument to disable this behavior and _**keep** trailing slashes_:

```js
console.log(normalize('foo\\bar\\baz\\', false)); //=> 'foo/bar/baz/'
console.log(normalize('./foo/bar/baz/', false)); //=> './foo/bar/baz/'
```

## Release history

### v3.0

No breaking changes in this release.

* a check was added to ensure that [win32 namespaces](https://msdn.microsoft.com/library/windows/desktop/aa365247(v=vs.85).aspx#namespaces) are handled properly by win32 `path.parse()` after a path has been normalized by this library.
* a minor optimization was made to simplify how the trailing separator was handled

## About

<details>
<summary><strong>Contributing</strong></summary>

Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).

</details>

<details>
<summary><strong>Running Tests</strong></summary>

Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

```sh
$ npm install && npm test
```

</details>

<details>
<summary><strong>Building docs</strong></summary>

_(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_

To generate the readme, run the following command:

```sh
$ npm install -g verbose/verb#dev verb-generate-readme && verb
```

</details>

### Related projects

Other useful path-related libraries:

* [contains-path](https://www.npmjs.com/package/contains-path): Return true if a file path contains the given path. | [homepage](https://github.com/jonschlinkert/contains-path "Return true if a file path contains the given path.")
* [is-absolute](https://www.npmjs.com/package/is-absolute): Returns true if a file path is absolute. Does not rely on the path module… [more](https://github.com/jonschlinkert/is-absolute) | [homepage](https://github.com/jonschlinkert/is-absolute "Returns true if a file path is absolute. Does not rely on the path module and can be used as a polyfill for node.js native `path.isAbolute`.")
* [is-relative](https://www.npmjs.com/package/is-relative): Returns `true` if the path appears to be relative. | [homepage](https://github.com/jonschlinkert/is-relative "Returns `true` if the path appears to be relative.")
* [parse-filepath](https://www.npmjs.com/package/parse-filepath): Pollyfill for node.js `path.parse`, parses a filepath into an object. | [homepage](https://github.com/jonschlinkert/parse-filepath "Pollyfill for node.js `path.parse`, parses a filepath into an object.")
* [path-ends-with](https://www.npmjs.com/package/path-ends-with): Return `true` if a file path ends with the given string/suffix. | [homepage](https://github.com/jonschlinkert/path-ends-with "Return `true` if a file path ends with the given string/suffix.")
* [unixify](https://www.npmjs.com/package/unixify): Convert Windows file paths to unix paths. | [homepage](https://github.com/jonschlinkert/unixify "Convert Windows file paths to unix paths.")

### Contributors

| **Commits** | **Contributor** | 
| --- | --- |
| 35 | [jonschlinkert](https://github.com/jonschlinkert) |
| 1 | [phated](https://github.com/phated) |

### Author

**Jon Schlinkert**

* [LinkedIn Profile](https://linkedin.com/in/jonschlinkert)
* [GitHub Profile](https://github.com/jonschlinkert)
* [Twitter Profile](https://twitter.com/jonschlinkert)

### License

Copyright © 2018, [Jon Schlinkert](https://github.com/jonschlinkert).
Released under the [MIT License](LICENSE).

***

_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.6.0, on April 19, 2018._

---

# normalize-range 

Utility for normalizing a numeric range, with a wrapping function useful for polar coordinates.

[![Build Status](https://travis-ci.org/jamestalmage/normalize-range.svg?branch=master)](https://travis-ci.org/jamestalmage/normalize-range)
[![Coverage Status](https://coveralls.io/repos/jamestalmage/normalize-range/badge.svg?branch=master&service=github)](https://coveralls.io/github/jamestalmage/normalize-range?branch=master)
[![Code Climate](https://codeclimate.com/github/jamestalmage/normalize-range/badges/gpa.svg)](https://codeclimate.com/github/jamestalmage/normalize-range)
[![Dependency Status](https://david-dm.org/jamestalmage/normalize-range.svg)](https://david-dm.org/jamestalmage/normalize-range)
[![devDependency Status](https://david-dm.org/jamestalmage/normalize-range/dev-status.svg)](https://david-dm.org/jamestalmage/normalize-range#info=devDependencies)

[![NPM](https://nodei.co/npm/normalize-range.png)](https://nodei.co/npm/normalize-range/)

## Usage

```js
var nr = require('normalize-range');

nr.wrap(0, 360, 400);
//=> 40

nr.wrap(0, 360, -90);
//=> 270

nr.limit(0, 100, 500);
//=> 100

nr.limit(0, 100, -20);
//=> 0

// There is a convenient currying function
var wrapAngle = nr.curry(0, 360).wrap;
var limitTo10 = nr.curry(0, 10).limit;

wrapAngle(-30);
//=> 330
```
## API

### wrap(min, max, value)

Normalizes a values that "wraps around". For example, in a polar coordinate system, 270˚ can also be
represented as -90˚. 
For wrapping purposes we assume `max` is functionally equivalent to `min`, and that `wrap(max + 1) === wrap(min + 1)`.
Wrap always assumes that `min` is *inclusive*, and `max` is *exclusive*.
In other words, if `value === max` the function will wrap it, and return `min`, but `min` will not be wrapped.

```js
nr.wrap(0, 360, 0) === 0;
nr.wrap(0, 360, 360) === 0;
nr.wrap(0, 360, 361) === 1;
nr.wrap(0, 360, -1) === 359;
```

You are not restricted to whole numbers, and ranges can be negative.

```js
var π = Math.PI;
var radianRange = nr.curry(-π, π);

redianRange.wrap(0) === 0;
nr.wrap(π) === -π;
nr.wrap(4 * π / 3) === -2 * π / 3;
```

### limit(min, max, value)

Normalize the value by bringing it within the range.
If `value` is greater than `max`, `max` will be returned.
If `value` is less than `min`, `min` will be returned.
Otherwise, `value` is returned unaltered.
Both ends of this range are *inclusive*.

### test(min, max, value, [minExclusive], [maxExclusive])

Returns `true` if `value` is within the range, `false` otherwise.
It defaults to `inclusive` on both ends of the range, but that can be
changed by setting `minExclusive` and/or `maxExclusive` to a truthy value.

### validate(min, max, value, [minExclusive], [maxExclusive])

Returns `value` or throws an error if `value` is outside the specified range.

### name(min, max, value, [minExclusive], [maxExclusive])

Returns a string representing this range in 
[range notation](https://en.wikipedia.org/wiki/Interval_(mathematics)#Classification_of_intervals).

### curry(min, max, [minExclusive], [maxExclusive])

Convenience method for currying all method arguments except `value`.

```js
var angle = require('normalize-range').curry(-180, 180, false, true);

angle.wrap(270)
//=> -90

angle.limit(200)
//=> 180

angle.test(0)
//=> true

angle.validate(300)
//=> throws an Error

angle.toString() // or angle.name()
//=> "[-180,180)"
```

#### min

*Required*  
Type: `number`

The minimum value (inclusive) of the range.

#### max

*Required*  
Type: `number`

The maximum value (exclusive) of the range.

#### value

*Required*  
Type: `number`

The value to be normalized.

#### returns

Type: `number`

The normalized value.

## Building and Releasing

- `npm test`: tests, linting, coverage and style checks.
- `npm run watch`: autotest mode for active development.
- `npm run debug`: run tests without coverage (istanbul can obscure line #'s) 

Release via `cut-release` tool.

## License

MIT © [James Talmage](http://github.com/jamestalmage)


---

# normalize-url [![Coverage Status](https://codecov.io/gh/sindresorhus/normalize-url/branch/main/graph/badge.svg)](https://codecov.io/gh/sindresorhus/normalize-url)

> [Normalize](https://en.wikipedia.org/wiki/URL_normalization) a URL

Useful when you need to display, store, deduplicate, sort, compare, etc, URLs.

**Note:** This package does **not** do URL sanitization. [Garbage in, garbage out.](https://en.wikipedia.org/wiki/Garbage_in,_garbage_out) If you use this in a server context and accept URLs as user input, it's up to you to protect against invalid URLs, [path traversal attacks](https://owasp.org/www-community/attacks/Path_Traversal), etc.

## Install

```sh
npm install normalize-url
```

## Usage

```js
import normalizeUrl from 'normalize-url';

normalizeUrl('sindresorhus.com');
//=> 'http://sindresorhus.com'

normalizeUrl('//www.sindresorhus.com:80/../baz?b=bar&a=foo');
//=> 'http://sindresorhus.com/baz?a=foo&b=bar'
```

## API

### normalizeUrl(url, options?)

URLs with custom protocols are not normalized and just passed through by default. Supported protocols are: `https`, `http`, `file`, and `data`.

Human-friendly URLs with basic auth (for example, `user:password@sindresorhus.com`) are not handled because basic auth conflicts with custom protocols. [Basic auth URLs are also deprecated.](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication#access_using_credentials_in_the_url)

#### url

Type: `string`

URL to normalize, including [data URL](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs).

#### options

Type: `object`

##### defaultProtocol

Type: `string`\
Default: `'http'`\
Values: `'https' | 'http'`

##### normalizeProtocol

Type: `boolean`\
Default: `true`

Prepend `defaultProtocol` to the URL if it's protocol-relative.

```js
normalizeUrl('//sindresorhus.com');
//=> 'http://sindresorhus.com'

normalizeUrl('//sindresorhus.com', {normalizeProtocol: false});
//=> '//sindresorhus.com'
```

##### forceHttp

Type: `boolean`\
Default: `false`

Normalize HTTPS to HTTP.

```js
normalizeUrl('https://sindresorhus.com');
//=> 'https://sindresorhus.com'

normalizeUrl('https://sindresorhus.com', {forceHttp: true});
//=> 'http://sindresorhus.com'
```

##### forceHttps

Type: `boolean`\
Default: `false`

Normalize HTTP to HTTPS.

```js
normalizeUrl('http://sindresorhus.com');
//=> 'http://sindresorhus.com'

normalizeUrl('http://sindresorhus.com', {forceHttps: true});
//=> 'https://sindresorhus.com'
```

This option cannot be used with the `forceHttp` option at the same time.

##### stripAuthentication

Type: `boolean`\
Default: `true`

Strip the [authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) part of the URL.

```js
normalizeUrl('https://user:password@sindresorhus.com');
//=> 'https://sindresorhus.com'

normalizeUrl('https://user:password@sindresorhus.com', {stripAuthentication: false});
//=> 'https://user:password@sindresorhus.com'
```

##### stripHash

Type: `boolean`\
Default: `false`

Strip the hash part of the URL.

```js
normalizeUrl('sindresorhus.com/about.html#contact');
//=> 'http://sindresorhus.com/about.html#contact'

normalizeUrl('sindresorhus.com/about.html#contact', {stripHash: true});
//=> 'http://sindresorhus.com/about.html'
```

##### stripProtocol

Type: `boolean`\
Default: `false`

Remove the protocol from the URL: `http://sindresorhus.com` → `sindresorhus.com`.

It will only remove `https://` and `http://` protocols.

```js
normalizeUrl('https://sindresorhus.com');
//=> 'https://sindresorhus.com'

normalizeUrl('https://sindresorhus.com', {stripProtocol: true});
//=> 'sindresorhus.com'
```

##### stripTextFragment

Type: `boolean`\
Default: `true`

Strip the [text fragment](https://web.dev/text-fragments/) part of the URL.

**Note:** The text fragment will always be removed if the `stripHash` option is set to `true`, as the hash contains the text fragment.

```js
normalizeUrl('http://sindresorhus.com/about.html#:~:text=hello');
//=> 'http://sindresorhus.com/about.html#'

normalizeUrl('http://sindresorhus.com/about.html#section:~:text=hello');
//=> 'http://sindresorhus.com/about.html#section'

normalizeUrl('http://sindresorhus.com/about.html#:~:text=hello', {stripTextFragment: false});
//=> 'http://sindresorhus.com/about.html#:~:text=hello'

normalizeUrl('http://sindresorhus.com/about.html#section:~:text=hello', {stripTextFragment: false});
//=> 'http://sindresorhus.com/about.html#section:~:text=hello'
```

##### stripWWW

Type: `boolean`\
Default: `true`

Remove `www.` from the URL.

```js
normalizeUrl('http://www.sindresorhus.com');
//=> 'http://sindresorhus.com'

normalizeUrl('http://www.sindresorhus.com', {stripWWW: false});
//=> 'http://www.sindresorhus.com'
```

##### removeQueryParameters

Type: `Array<RegExp | string> | boolean`\
Default: `[/^utm_\w+/i]`

Remove query parameters that matches any of the provided strings or regexes.

```js
normalizeUrl('www.sindresorhus.com?foo=bar&ref=test_ref', {
	removeQueryParameters: ['ref']
});
//=> 'http://sindresorhus.com/?foo=bar'
```

If a boolean is provided, `true` will remove all the query parameters.

```js
normalizeUrl('www.sindresorhus.com?foo=bar', {
	removeQueryParameters: true
});
//=> 'http://sindresorhus.com'
```

`false` will not remove any query parameter.

```js
normalizeUrl('www.sindresorhus.com?foo=bar&utm_medium=test&ref=test_ref', {
	removeQueryParameters: false
});
//=> 'http://www.sindresorhus.com/?foo=bar&ref=test_ref&utm_medium=test'
```

##### keepQueryParameters

Type: `Array<RegExp | string>`\
Default: `undefined`

Keeps only query parameters that matches any of the provided strings or regexes.

**Note:** It overrides the `removeQueryParameters` option.

```js
normalizeUrl('https://sindresorhus.com?foo=bar&ref=unicorn', {
	keepQueryParameters: ['ref']
});
//=> 'https://sindresorhus.com/?ref=unicorn'
```

##### removeTrailingSlash

Type: `boolean`\
Default: `true`

Remove trailing slash.

**Note:** Trailing slash is always removed if the URL doesn't have a pathname unless the `removeSingleSlash` option is set to `false`.

```js
normalizeUrl('http://sindresorhus.com/redirect/');
//=> 'http://sindresorhus.com/redirect'

normalizeUrl('http://sindresorhus.com/redirect/', {removeTrailingSlash: false});
//=> 'http://sindresorhus.com/redirect/'

normalizeUrl('http://sindresorhus.com/', {removeTrailingSlash: false});
//=> 'http://sindresorhus.com'
```

##### removeSingleSlash

Type: `boolean`\
Default: `true`

Remove a sole `/` pathname in the output. This option is independent of `removeTrailingSlash`.

```js
normalizeUrl('https://sindresorhus.com/');
//=> 'https://sindresorhus.com'

normalizeUrl('https://sindresorhus.com/', {removeSingleSlash: false});
//=> 'https://sindresorhus.com/'
```

##### removeDirectoryIndex

Type: `boolean | Array<RegExp | string>`\
Default: `false`

Removes the default directory index file from path that matches any of the provided strings or regexes. When `true`, the regex `/^index\.[a-z]+$/` is used.

```js
normalizeUrl('www.sindresorhus.com/foo/default.php', {
	removeDirectoryIndex: [/^default\.[a-z]+$/]
});
//=> 'http://sindresorhus.com/foo'
```

##### removeExplicitPort

Type: `boolean`\
Default: `false`

Removes an explicit port number from the URL.

Port 443 is always removed from HTTPS URLs and 80 is always removed from HTTP URLs regardless of this option.

```js
normalizeUrl('sindresorhus.com:123', {
	removeExplicitPort: true
});
//=> 'http://sindresorhus.com'
```

##### sortQueryParameters

Type: `boolean`\
Default: `true`

Sorts the query parameters alphabetically by key.

```js
normalizeUrl('www.sindresorhus.com?b=two&a=one&c=three', {
	sortQueryParameters: false
});
//=> 'http://sindresorhus.com/?b=two&a=one&c=three'
```

## Related

- [compare-urls](https://github.com/sindresorhus/compare-urls) - Compare URLs by first normalizing them


---

# npm-run-path [![Build Status](https://travis-ci.org/sindresorhus/npm-run-path.svg?branch=master)](https://travis-ci.org/sindresorhus/npm-run-path)

> Get your [PATH](https://en.wikipedia.org/wiki/PATH_(variable)) prepended with locally installed binaries

In [npm run scripts](https://docs.npmjs.com/cli/run-script) you can execute locally installed binaries by name. This enables the same outside npm.


## Install

```
$ npm install npm-run-path
```


## Usage

```js
const childProcess = require('child_process');
const npmRunPath = require('npm-run-path');

console.log(process.env.PATH);
//=> '/usr/local/bin'

console.log(npmRunPath());
//=> '/Users/sindresorhus/dev/foo/node_modules/.bin:/Users/sindresorhus/dev/node_modules/.bin:/Users/sindresorhus/node_modules/.bin:/Users/node_modules/.bin:/node_modules/.bin:/usr/local/bin'

// `foo` is a locally installed binary
childProcess.execFileSync('foo', {
	env: npmRunPath.env()
});
```


## API

### npmRunPath(options?)

Returns the augmented path string.

#### options

Type: `object`

##### cwd

Type: `string`<br>
Default: `process.cwd()`

Working directory.

##### path

Type: `string`<br>
Default: [`PATH`](https://github.com/sindresorhus/path-key)

PATH to be appended.<br>
Set it to an empty string to exclude the default PATH.

##### execPath

Type: `string`<br>
Default: `process.execPath`

Path to the current Node.js executable. Its directory is pushed to the front of PATH.

This can be either an absolute path or a path relative to the [`cwd` option](#cwd).

### npmRunPath.env(options?)

Returns the augmented [`process.env`](https://nodejs.org/api/process.html#process_process_env) object.

#### options

Type: `object`

##### cwd

Type: `string`<br>
Default: `process.cwd()`

Working directory.

##### env

Type: `Object`

Accepts an object of environment variables, like `process.env`, and modifies the PATH using the correct [PATH key](https://github.com/sindresorhus/path-key). Use this if you're modifying the PATH for use in the `child_process` options.

##### execPath

Type: `string`<br>
Default: `process.execPath`

Path to the Node.js executable to use in child processes if that is different from the current one. Its directory is pushed to the front of PATH.

This can be either an absolute path or a path relative to the [`cwd` option](#cwd).


## Related

- [npm-run-path-cli](https://github.com/sindresorhus/npm-run-path-cli) - CLI for this module
- [execa](https://github.com/sindresorhus/execa) - Execute a locally installed binary


---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-npm-run-path?utm_source=npm-npm-run-path&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

## [v0.2.0] - May 13, 2015

 * [#93] - Remove jQuery dependency in component ([@slang800])
 * [#120] - Fix the Readme showing a wrong example for `ease` ([@teeceepee])

Minor changes:

 * [#92] - Fix typo in Readme ([@FND])
 * [#90] - Fix typo in Readme ([@mdxs])
 * [#119] - Fix typo in Readme ([@infertux])
 * [#53] - Use `===` instead of `==` ([@drodil])

## [v0.1.6] - June 25, 2014

 * [#86] - Add support for specifying a different parent container. ([@jonjaques], [#14], [#33], [#39])
 * [#64] - Fix Require.js support ([#75], [#85])
 * [#54] - Fix component support

## [v0.1.5] - June 21, 2014

 * [#82] - Release properly to the npm registry

## [v0.1.4] - June 21, 2014

 * [#65] - Bower: don't download package.json. Fixes browserify + jquery problem. ([@amelon])
 * [#75] - Fix compatibility with Karma. ([@shaqq])
 
Internal changes:

 * [#77] - Use SVG to display Travis-CI badge. ([@Mithgol])
 * [#34] - Readme: update .inc() and .status docs ([@lacivert])
 * [#73] - Readme: update year ([@rwholmes])

## [v0.1.3] - March 26, 2014

 * [#7] - Remove jQuery dependency ([#28], [#17], [@rurjur])
 * [#73] - Update Readme to change year to 2014. ([@rwholmes])

## [v0.1.2] - August 21, 2013

Minor update for proper [Bower] and [Component] support.

 * Add Bower support.
 * Fix Component support and use `component/jquery` as a dependency.

## [v0.1.1] - August 21, 2013

Minor fixes.

 * Removed the busy cursor that occurs when loading.
 * Added support for IE7 to IE9. ([#3], [@markbao])
 * Implement `trickleRate` and `trickleSpeed` options.
 * [#5] - Implement the `showSpinner` option to allow removing the spinner. ([#9], [@rahulcs])
 * Registered as a Component in Component.io.
 * [#8] - Updated the Readme with better Turbolinks instructions.

## v0.1.0 - August 20, 2013

Initial release.

[Bower]: http://bower.io
[Component]: http://component.io
[#119]: https://github.com/rstacruz/nprogress/issues/119
[#120]: https://github.com/rstacruz/nprogress/issues/120
[#14]: https://github.com/rstacruz/nprogress/issues/14
[#17]: https://github.com/rstacruz/nprogress/issues/17
[#28]: https://github.com/rstacruz/nprogress/issues/28
[#33]: https://github.com/rstacruz/nprogress/issues/33
[#34]: https://github.com/rstacruz/nprogress/issues/34
[#39]: https://github.com/rstacruz/nprogress/issues/39
[#3]: https://github.com/rstacruz/nprogress/issues/3
[#54]: https://github.com/rstacruz/nprogress/issues/84
[#5]: https://github.com/rstacruz/nprogress/issues/5
[#64]: https://github.com/rstacruz/nprogress/issues/64
[#65]: https://github.com/rstacruz/nprogress/issues/65
[#73]: https://github.com/rstacruz/nprogress/issues/73
[#75]: https://github.com/rstacruz/nprogress/issues/75
[#77]: https://github.com/rstacruz/nprogress/issues/77
[#7]: https://github.com/rstacruz/nprogress/issues/7
[#82]: https://github.com/rstacruz/nprogress/issues/82
[#84]: https://github.com/rstacruz/nprogress/issues/84
[#85]: https://github.com/rstacruz/nprogress/issues/85
[#86]: https://github.com/rstacruz/nprogress/issues/86
[#8]: https://github.com/rstacruz/nprogress/issues/8
[#90]: https://github.com/rstacruz/nprogress/issues/90
[#92]: https://github.com/rstacruz/nprogress/issues/92
[#93]: https://github.com/rstacruz/nprogress/issues/93
[#9]: https://github.com/rstacruz/nprogress/issues/9
[@slang800]: https://github.com/slang800
[@teeceepee]: https://github.com/teeceepee
[@FND]: https://github.com/FND
[@mdxs]: https://github.com/mdxs
[@infertux]: https://github.com/infertux
[@jonjaques]: https://github.com/jonjaques
[@amelon]: https://github.com/amelon
[@shaqq]: https://github.com/shaqq
[@Mithgol]: https://github.com/Mithgol
[@lacivert]: https://github.com/lacivert
[@rwholmes]: https://github.com/rwholmes
[@rurjur]: https://github.com/rurjur
[@markbao]: https://github.com/markbao
[@rahulcs]: https://github.com/rahulcs
[v0.1.6]: https://github.com/rstacruz/nprogress/compare/v0.1.5...v0.1.6
[v0.1.5]: https://github.com/rstacruz/nprogress/compare/v0.1.4...v0.1.5
[v0.1.4]: https://github.com/rstacruz/nprogress/compare/v0.1.3...v0.1.4
[v0.1.3]: https://github.com/rstacruz/nprogress/compare/v0.1.2...v0.1.3
[v0.1.2]: https://github.com/rstacruz/nprogress/compare/v0.1.1...v0.1.2
[v0.1.1]: https://github.com/rstacruz/nprogress/compare/v0.1.0...v0.1.1
[#53]: https://github.com/rstacruz/nprogress/issues/53
[v0.2.0]: https://github.com/rstacruz/nprogress/compare/v0.1.6...v0.2.0


---

Copyright (c) 2013-2014 Rico Sta. Cruz

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.


---

Testing
-------

    $ npm install
    $ npm test

or try it out in the browser:

    $ open test/index.html

Testing component build
-----------------------

    $ component install
    $ component build
    $ open test/component.html

Releasing
---------

    $ npm test
    $ bump *.json nprogress.js          # bump version numbers
    $ git release 0.1.1                 # release to bower/github
    $ npm publish                       # release to npm
    $ git push origin master:gh-pages   # update the site


---

NProgress
=========

Slim progress bars for Ajax'y applications. Inspired by Google, YouTube, and
Medium.


Installation
------------

Add [nprogress.js] and [nprogress.css] to your project.

```html
<script src='nprogress.js'></script>
<link rel='stylesheet' href='nprogress.css'/>
```

NProgress is available via [bower] and [npm] and [spm].

    $ bower install --save nprogress
    $ npm install --save nprogress

[bower]: http://bower.io/search/?q=nprogress
[npm]: https://www.npmjs.org/package/nprogress
[spm]: http://spmjs.io/package/nprogress

Basic usage
-----------

Simply call `start()` and `done()` to control the progress bar.

~~~ js
NProgress.start();
NProgress.done();
~~~

Using [Turbolinks] or similar? Ensure you're using Turbolinks 1.3.0+, and use 
this: (explained 
    [here](https://github.com/rstacruz/nprogress/issues/8#issuecomment-23010560))

~~~ js
$(document).on('page:fetch',   function() { NProgress.start(); });
$(document).on('page:change',  function() { NProgress.done(); });
$(document).on('page:restore', function() { NProgress.remove(); });
~~~

Ideas
-----

 * Add progress to your Ajax calls! Bind it to the jQuery `ajaxStart` and
 `ajaxStop` events.

 * Make a fancy loading bar even without Turbolinks/Pjax! Bind it to
 `$(document).ready` and `$(window).load`.

Advanced usage
--------------

__Percentages:__ To set a progress percentage, call `.set(n)`, where *n* is a
number between `0..1`.

~~~ js
NProgress.set(0.0);     // Sorta same as .start()
NProgress.set(0.4);
NProgress.set(1.0);     // Sorta same as .done()
~~~

__Incrementing:__ To increment the progress bar, just use `.inc()`. This
increments it with a random amount. This will never get to 100%: use it for
every image load (or similar).

~~~ js
NProgress.inc();
~~~

If you want to increment by a specific value, you can pass that as a parameter:

~~~ js
NProgress.inc(0.2);    // This will get the current status value and adds 0.2 until status is 0.994
~~~

__Force-done:__ By passing `true` to `done()`, it will show the progress bar
even if it's not being shown. (The default behavior is that *.done()* will not
    do anything if *.start()* isn't called)

~~~ js
NProgress.done(true);
~~~

__Get the status value:__ To get the status value, use `.status`

Configuration
-------------

#### `minimum`
Changes the minimum percentage used upon starting. (default: `0.08`)

~~~ js
NProgress.configure({ minimum: 0.1 });
~~~

#### `template`
You can change the markup using `template`. To keep the progress
bar working, keep an element with `role='bar'` in there. See the [default template]
for reference.

~~~ js
NProgress.configure({
  template: "<div class='....'>...</div>"
});
~~~

#### `easing` and `speed`
Adjust animation settings using *easing* (a CSS easing string)
and *speed* (in ms). (default: `ease` and `200`)

~~~ js
NProgress.configure({ easing: 'ease', speed: 500 });
~~~

#### `trickle`
Turn off the automatic incrementing behavior by setting this to `false`. (default: `true`)

~~~ js
NProgress.configure({ trickle: false });
~~~

#### `trickleRate` and `trickleSpeed`
You can adjust the *trickleRate* (how much to increase per trickle) and 
*trickleSpeed* (how often to trickle, in ms).

~~~ js
NProgress.configure({ trickleRate: 0.02, trickleSpeed: 800 });
~~~

#### `showSpinner`
Turn off loading spinner by setting it to false. (default: `true`)

~~~ js
NProgress.configure({ showSpinner: false });
~~~

#### `parent`
specify this to change the parent container. (default: `body`)

~~~ js
NProgress.configure({ parent: '#container' });
~~~

Customization
-------------

Just edit `nprogress.css` to your liking. Tip: you probably only want to find
and replace occurrences of `#29d`.

The included CSS file is pretty minimal... in fact, feel free to scrap it and
make your own!

Resources
---------

 * [New UI Pattern: Website Loading Bars](http://www.usabilitypost.com/2013/08/19/new-ui-pattern-website-loading-bars/) (usabilitypost.com)

Support
-------

__Bugs and requests__: submit them through the project's issues tracker.<br>
[![Issues](http://img.shields.io/github/issues/rstacruz/nprogress.svg)]( https://github.com/rstacruz/nprogress/issues )

__Questions__: ask them at StackOverflow with the tag *nprogress*.<br>
[![StackOverflow](http://img.shields.io/badge/stackoverflow-nprogress-brightgreen.svg)]( http://stackoverflow.com/questions/tagged/nprogress )

__Chat__: join us at gitter.im.<br>
[![Chat](http://img.shields.io/badge/gitter-rstacruz / nprogress-brightgreen.svg)]( https://gitter.im/rstacruz/nprogress )

[default template]: 
https://github.com/rstacruz/nprogress/blob/master/nprogress.js#L31
[Turbolinks]: https://github.com/rails/turbolinks
[nprogress.js]: http://ricostacruz.com/nprogress/nprogress.js
[nprogress.css]: http://ricostacruz.com/nprogress/nprogress.css

Thanks
------

**NProgress** © 2013-2014, Rico Sta. Cruz. Released under the [MIT License].<br>
Authored and maintained by Rico Sta. Cruz with help from [contributors].

> [ricostacruz.com](http://ricostacruz.com) &nbsp;&middot;&nbsp;
> GitHub [@rstacruz](https://github.com/rstacruz) &nbsp;&middot;&nbsp;
> Twitter [@rstacruz](https://twitter.com/rstacruz)

[MIT License]: http://mit-license.org/
[contributors]: http://github.com/rstacruz/nprogress/contributors

[![Status](https://api.travis-ci.org/rstacruz/nprogress.svg?branch=master)](http://travis-ci.org/rstacruz/nprogress) 
[![npm version](https://img.shields.io/npm/v/nprogress.png)](https://npmjs.org/package/nprogress "View this project on npm")
[![spm package](http://spmjs.io/badge/nprogress)](http://spmjs.io/package/nprogress)


---

# nth-check [![Build Status](https://travis-ci.org/fb55/nth-check.svg)](https://travis-ci.org/fb55/nth-check)

Parses and compiles CSS nth-checks to highly optimized functions.

### About

This module can be used to parse & compile nth-checks, as they are found in CSS 3's `nth-child()` and `nth-last-of-type()`. It can be used to check if a given index matches a given nth-rule, or to generate a sequence of indices matching a given nth-rule.

`nth-check` focusses on speed, providing optimized functions for different kinds of nth-child formulas, while still following the [spec](http://www.w3.org/TR/css3-selectors/#nth-child-pseudo).

### API

```js
import nthCheck, { parse, compile } from "nth-check";
```

##### `nthCheck(formula)`

Parses and compiles a formula to a highly optimized function. Combination of `parse` and `compile`.

If the formula doesn't match any elements, it returns [`boolbase`](https://github.com/fb55/boolbase)'s `falseFunc`. Otherwise, a function accepting an _index_ is returned, which returns whether or not the passed _index_ matches the formula.

**Note**: The nth-rule starts counting at `1`, the returned function at `0`.

**Example:**

```js
const check = nthCheck("2n+3");

check(0); // `false`
check(1); // `false`
check(2); // `true`
check(3); // `false`
check(4); // `true`
check(5); // `false`
check(6); // `true`
```

##### `parse(formula)`

Parses the expression, throws an `Error` if it fails. Otherwise, returns an array containing the integer step size and the integer offset of the nth rule.

**Example:**

```js
parse("2n+3"); // [2, 3]
```

##### `compile([a, b])`

Takes an array with two elements (as returned by `.parse`) and returns a highly optimized function.

**Example:**

```js
const check = compile([2, 3]);

check(0); // `false`
check(1); // `false`
check(2); // `true`
check(3); // `false`
check(4); // `true`
check(5); // `false`
check(6); // `true`
```

##### `generate([a, b])`

Returns a function that produces a monotonously increasing sequence of indices.

If the sequence has an end, the returned function will return `null` after the last index in the sequence.

**Example:** An always increasing sequence

```js
const gen = nthCheck.generate([2, 3]);

gen(); // `1`
gen(); // `3`
gen(); // `5`
gen(); // `8`
gen(); // `11`
```

**Example:** With an end value

```js
const gen = nthCheck.generate([-2, 5]);

gen(); // 0
gen(); // 2
gen(); // 4
gen(); // null
```

##### `sequence(formula)`

Parses and compiles a formula to a generator that produces a sequence of indices. Combination of `parse` and `generate`.

**Example:** An always increasing sequence

```js
const gen = nthCheck.sequence("2n+3");

gen(); // `1`
gen(); // `3`
gen(); // `5`
gen(); // `8`
gen(); // `11`
```

**Example:** With an end value

```js
const gen = nthCheck.sequence("-2n+5");

gen(); // 0
gen(); // 2
gen(); // 4
gen(); // null
```

---

License: BSD-2-Clause

## Security contact information

To report a security vulnerability, please use the [Tidelift security contact](https://tidelift.com/security).
Tidelift will coordinate the fix and disclosure.

## `nth-check` for enterprise

Available as part of the Tidelift Subscription

The maintainers of `nth-check` and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-nth-check?utm_source=npm-nth-check&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)


---

# Changelog

All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.

### [4.0.1](https://github.com/webpack-contrib/null-loader/compare/v4.0.0...v4.0.1) (2020-10-09)

### Chore

* update `schema-utils`

## [4.0.0](https://github.com/webpack-contrib/null-loader/compare/v3.0.0...v4.0.0) (2020-04-15)


### Bug Fixes

* support `webpack@5`

### ⚠ BREAKING CHANGES

* minimum required Nodejs version is `10.13`

## [3.0.0](https://github.com/webpack-contrib/null-loader/compare/v2.0.0...v3.0.0) (2019-06-05)


### chore

* **deps:** update ([#25](https://github.com/webpack-contrib/null-loader/issues/25)) ([46163ef](https://github.com/webpack-contrib/null-loader/commit/46163ef))


### BREAKING CHANGES

* **deps:** minimum required nodejs version is `8.9.0`



## [2.0.0](https://github.com/webpack-contrib/null-loader/compare/v1.0.0...v2.0.0) (2019-05-15)


### Bug Fixes

* handle not javascript modules ([#24](https://github.com/webpack-contrib/null-loader/issues/24)) ([9dcd860](https://github.com/webpack-contrib/null-loader/commit/9dcd860))


### BREAKING CHANGES

* loader don't generate comment by default



<a name="1.0.0"></a>
# [1.0.0](https://github.com/webpack-contrib/css-loader/compare/v1.0.0) (2019-04-23)


### Bug Fixes

* don't create binary file
* relax `engines` field in `package-lock.json`

### Features

* validation schema


### BREAKING CHANGES

* validation schema


---

<div align="center">
  <a href="https://github.com/webpack/webpack">
    <img width="200" height="200" src="https://webpack.js.org/assets/icon-square-big.svg">
  </a>
</div>

[![npm][npm]][npm-url]
[![node][node]][node-url]
[![deps][deps]][deps-url]
[![tests][tests]][tests-url]
[![chat][chat]][chat-url]
[![size][size]][size-url]

# null-loader

A webpack loader that returns an empty module.

One use for this loader is to silence modules imported by a dependency. Say, for
example, your project relies on an ES6 library that imports a polyfill you don't
need, so removing it will cause no loss in functionality.

## Getting Started

To begin, you'll need to install `null-loader`:

```console
$ npm install null-loader --save-dev
```

Then add the loader to your `webpack` config. For example:

```js
// webpack.config.js
const path = require('path');

module.exports = {
  module: {
    rules: [
      {
        // Test for a polyfill (or any file) and it won't be included in your
        // bundle
        test: path.resolve(__dirname, 'node_modules/library/polyfill.js'),
        use: 'null-loader',
      },
    ],
  },
};
```

And run `webpack` via your preferred method.

## Contributing

Please take a moment to read our contributing guidelines if you haven't yet done so.

[CONTRIBUTING](./.github/CONTRIBUTING.md)

## License

[MIT](./LICENSE)

[npm]: https://img.shields.io/npm/v/null-loader.svg
[npm-url]: https://npmjs.com/package/null-loader
[node]: https://img.shields.io/node/v/null-loader.svg
[node-url]: https://nodejs.org
[deps]: https://david-dm.org/webpack-contrib/null-loader.svg
[deps-url]: https://david-dm.org/webpack-contrib/null-loader
[tests]: https://github.com/webpack-contrib/null-loader/workflows/null-loader/badge.svg
[tests-url]: https://github.com/webpack-contrib/null-loader/actions
[cover]: https://codecov.io/gh/webpack-contrib/null-loader/branch/master/graph/badge.svg
[cover-url]: https://codecov.io/gh/webpack-contrib/null-loader
[chat]: https://img.shields.io/badge/gitter-webpack%2Fwebpack-brightgreen.svg
[chat-url]: https://gitter.im/webpack/webpack
[size]: https://packagephobia.now.sh/badge?p=null-loader
[size-url]: https://packagephobia.now.sh/result?p=null-loader


---

# Changelog

All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.

## [3.3.0](https://github.com/webpack/schema-utils/compare/v3.2.0...v3.3.0) (2023-06-14)


### Features

* added API to disable and enable validation ([#183](https://github.com/webpack/schema-utils/issues/183)) ([d4d334f](https://github.com/webpack/schema-utils/commit/d4d334f0ba22eb6b6564b1119e8f3ea439e1f2bb))


### Bug Fixes

* **perf:** cache compiled schema ([#182](https://github.com/webpack/schema-utils/issues/182)) ([02aa068](https://github.com/webpack/schema-utils/commit/02aa068df80d99cc576a5ed385f947eb5204c5db))

## [3.2.0](https://github.com/webpack/schema-utils/compare/v3.1.2...v3.2.0) (2023-06-07)


### Features

* implement `undefinedAsNull` keyword for `enum` type ([#176](https://github.com/webpack/schema-utils/issues/176)) ([95826eb](https://github.com/webpack/schema-utils/commit/95826eb9e14bc4b10ab95f962ac2bdca447880a3))

### [3.1.2](https://github.com/webpack/schema-utils/compare/v3.1.1...v3.1.2) (2023-04-15)


### Bug Fixes

* **perf:** reduced initial start time ([#170](https://github.com/webpack/schema-utils/issues/170)) ([8d052e6](https://github.com/webpack/schema-utils/commit/8d052e6764dc9247e7d5b7b1ae8f87ca5047b2b0))

### [3.1.1](https://github.com/webpack/schema-utils/compare/v3.1.0...v3.1.1) (2021-07-19)


### Bug Fixes

* update error message for `integer` ([#136](https://github.com/webpack/schema-utils/issues/136)) ([2daa97e](https://github.com/webpack/schema-utils/commit/2daa97eae87e6790b92711746a6a527b859ac13b))

## [3.1.0](https://github.com/webpack/schema-utils/compare/v3.0.0...v3.1.0) (2021-06-30)


### Features

* added the `link` property in validation error ([589aa59](https://github.com/webpack/schema-utils/commit/589aa5993424a8bc45ec22b67dff55be92c456a9))


### Bug Fixes

* non-empty validation error message ([#116](https://github.com/webpack/schema-utils/issues/116)) ([c51abef](https://github.com/webpack/schema-utils/commit/c51abefa4d4d62e1346b3a105182d36675595077))

## [3.0.0](https://github.com/webpack/schema-utils/compare/v2.7.1...v3.0.0) (2020-10-05)


### ⚠ BREAKING CHANGES

* minimum supported `Node.js` version is `10.13.0`, 
* the packages exports was changed, please use `const { validate } = require('schema-utils');`
* the `ValidateError` export was removed in favor the `ValidationError` export, please use `const { ValidationError } = require('schema-utils');`

### [2.7.1](https://github.com/webpack/schema-utils/compare/v2.7.0...v2.7.1) (2020-08-31)


### Bug Fixes

* remove esModuleInterop from tsconfig ([#110](https://github.com/webpack/schema-utils/issues/110)) ([#111](https://github.com/webpack/schema-utils/issues/111)) ([2f40154](https://github.com/webpack/schema-utils/commit/2f40154b91e45b393258ae9dd8f10cc3b8590b7d))

## [2.7.0](https://github.com/webpack/schema-utils/compare/v2.6.6...v2.7.0) (2020-05-29)


### Features

* improve hints ([a36e535](https://github.com/webpack/schema-utils/commit/a36e535faca1b01e27c3bfa3c8bee9227c3f836c))
* smart not case ([#101](https://github.com/webpack/schema-utils/issues/101)) ([698d8b0](https://github.com/webpack/schema-utils/commit/698d8b05462d86aadb217e25a45c7b953a79a52e))


### Bug Fixes

* move @types/json-schema from devDependencies to dependencies ([#97](https://github.com/webpack/schema-utils/issues/97)) ([#98](https://github.com/webpack/schema-utils/issues/98)) ([945e67d](https://github.com/webpack/schema-utils/commit/945e67db5e19baf7ec7df72813b0739dd56f950d))

### [2.6.6](https://github.com/webpack/schema-utils/compare/v2.6.5...v2.6.6) (2020-04-17)


### Bug Fixes

* improve perf

### [2.6.5](https://github.com/webpack/schema-utils/compare/v2.6.4...v2.6.5) (2020-03-11)


### Bug Fixes

* correct dots at end of sentence ([7284beb](https://github.com/webpack/schema-utils/commit/7284bebe00cd570f1bef2c15951a07b9794038e6))

### [2.6.4](https://github.com/webpack/schema-utils/compare/v2.6.3...v2.6.4) (2020-01-17)


### Bug Fixes

* change `initialised` to `initialized` ([#87](https://github.com/webpack/schema-utils/issues/87)) ([70f12d3](https://github.com/webpack/schema-utils/commit/70f12d33a8eaa27249bc9c1a27f886724cf91ea7))

### [2.6.3](https://github.com/webpack/schema-utils/compare/v2.6.2...v2.6.3) (2020-01-17)


### Bug Fixes

* prefer the `baseDataPath` option from arguments ([#86](https://github.com/webpack/schema-utils/issues/86)) ([e236859](https://github.com/webpack/schema-utils/commit/e236859e85b28e35e1294f86fc1ff596a5031cea))

### [2.6.2](https://github.com/webpack/schema-utils/compare/v2.6.1...v2.6.2) (2020-01-14)


### Bug Fixes

* better handle Windows absolute paths ([#85](https://github.com/webpack/schema-utils/issues/85)) ([1fa2930](https://github.com/webpack/schema-utils/commit/1fa2930a161e907b9fc53a7233d605910afdb883))

### [2.6.1](https://github.com/webpack/schema-utils/compare/v2.6.0...v2.6.1) (2019-11-28)


### Bug Fixes

* typescript declarations ([#84](https://github.com/webpack/schema-utils/issues/84)) ([89d55a9](https://github.com/webpack/schema-utils/commit/89d55a9a8edfa6a8ac8b112f226bb3154e260319))

## [2.6.0](https://github.com/webpack/schema-utils/compare/v2.5.0...v2.6.0) (2019-11-27)


### Features

* support configuration via title ([#81](https://github.com/webpack/schema-utils/issues/81)) ([afddc10](https://github.com/webpack/schema-utils/commit/afddc109f6891cd37a9f1835d50862d119a072bf))


### Bug Fixes

* typescript definitions ([#70](https://github.com/webpack/schema-utils/issues/70)) ([f38158d](https://github.com/webpack/schema-utils/commit/f38158d6d040e2c701622778ae8122fb26a4f990))

## [2.5.0](https://github.com/webpack/schema-utils/compare/v2.4.1...v2.5.0) (2019-10-15)


### Bug Fixes

* rework format for maxLength, minLength ([#67](https://github.com/webpack/schema-utils/issues/67)) ([0d12259](https://github.com/webpack/schema-utils/commit/0d12259))
* support all cases with one number in range ([#64](https://github.com/webpack/schema-utils/issues/64)) ([7fc8069](https://github.com/webpack/schema-utils/commit/7fc8069))
* typescript definition and export naming ([#69](https://github.com/webpack/schema-utils/issues/69)) ([a435b79](https://github.com/webpack/schema-utils/commit/a435b79))


### Features

* "smart" numbers range ([62fb107](https://github.com/webpack/schema-utils/commit/62fb107))

### [2.4.1](https://github.com/webpack/schema-utils/compare/v2.4.0...v2.4.1) (2019-09-27)


### Bug Fixes

* publish definitions ([#58](https://github.com/webpack/schema-utils/issues/58)) ([1885faa](https://github.com/webpack/schema-utils/commit/1885faa))

## [2.4.0](https://github.com/webpack/schema-utils/compare/v2.3.0...v2.4.0) (2019-09-26)


### Features

* better errors when the `type` keyword doesn't exist ([0988be2](https://github.com/webpack/schema-utils/commit/0988be2))
* support $data reference ([#56](https://github.com/webpack/schema-utils/issues/56)) ([d2f11d6](https://github.com/webpack/schema-utils/commit/d2f11d6))
* types definitions ([#52](https://github.com/webpack/schema-utils/issues/52)) ([facb431](https://github.com/webpack/schema-utils/commit/facb431))

## [2.3.0](https://github.com/webpack/schema-utils/compare/v2.2.0...v2.3.0) (2019-09-26)


### Features

* support `not` keyword ([#53](https://github.com/webpack/schema-utils/issues/53)) ([765f458](https://github.com/webpack/schema-utils/commit/765f458))

## [2.2.0](https://github.com/webpack/schema-utils/compare/v2.1.0...v2.2.0) (2019-09-02)


### Features

* better error output for `oneOf` and `anyOf` ([#48](https://github.com/webpack/schema-utils/issues/48)) ([#50](https://github.com/webpack/schema-utils/issues/50)) ([332242f](https://github.com/webpack/schema-utils/commit/332242f))

## [2.1.0](https://github.com/webpack-contrib/schema-utils/compare/v2.0.1...v2.1.0) (2019-08-07)


### Bug Fixes

* throw error on sparse arrays ([#47](https://github.com/webpack-contrib/schema-utils/issues/47)) ([b85ac38](https://github.com/webpack-contrib/schema-utils/commit/b85ac38))


### Features

* export `ValidateError` ([#46](https://github.com/webpack-contrib/schema-utils/issues/46)) ([ff781d7](https://github.com/webpack-contrib/schema-utils/commit/ff781d7))



### [2.0.1](https://github.com/webpack-contrib/schema-utils/compare/v2.0.0...v2.0.1) (2019-07-18)


### Bug Fixes

* error message for empty object ([#44](https://github.com/webpack-contrib/schema-utils/issues/44)) ([0b4b4a2](https://github.com/webpack-contrib/schema-utils/commit/0b4b4a2))



### [2.0.0](https://github.com/webpack-contrib/schema-utils/compare/v1.0.0...v2.0.0) (2019-07-17)


### BREAKING CHANGES

* drop support for Node.js < 8.9.0
* drop support `errorMessage`, please use `description` for links.
* api was changed, please look documentation.
* error messages was fully rewritten.


<a name="1.0.0"></a>
# [1.0.0](https://github.com/webpack-contrib/schema-utils/compare/v0.4.7...v1.0.0) (2018-08-07)


### Features

* **src:** add support for custom error messages ([#33](https://github.com/webpack-contrib/schema-utils/issues/33)) ([1cbe4ef](https://github.com/webpack-contrib/schema-utils/commit/1cbe4ef))



<a name="0.4.7"></a>
## [0.4.7](https://github.com/webpack-contrib/schema-utils/compare/v0.4.6...v0.4.7) (2018-08-07)


### Bug Fixes

* **src:** `node >= v4.0.0` support ([#32](https://github.com/webpack-contrib/schema-utils/issues/32)) ([cb13dd4](https://github.com/webpack-contrib/schema-utils/commit/cb13dd4))



<a name="0.4.6"></a>
## [0.4.6](https://github.com/webpack-contrib/schema-utils/compare/v0.4.5...v0.4.6) (2018-08-06)


### Bug Fixes

* **package:** remove lockfile ([#28](https://github.com/webpack-contrib/schema-utils/issues/28)) ([69f1a81](https://github.com/webpack-contrib/schema-utils/commit/69f1a81))
* **package:** remove unnecessary `webpack` dependency ([#26](https://github.com/webpack-contrib/schema-utils/issues/26)) ([532eaa5](https://github.com/webpack-contrib/schema-utils/commit/532eaa5))



<a name="0.4.5"></a>
## [0.4.5](https://github.com/webpack-contrib/schema-utils/compare/v0.4.4...v0.4.5) (2018-02-13)


### Bug Fixes

* **CHANGELOG:** update broken links ([4483b9f](https://github.com/webpack-contrib/schema-utils/commit/4483b9f))
* **package:** update broken links ([f2494ba](https://github.com/webpack-contrib/schema-utils/commit/f2494ba))



<a name="0.4.4"></a>
## [0.4.4](https://github.com/webpack-contrib/schema-utils/compare/v0.4.3...v0.4.4) (2018-02-13)


### Bug Fixes

* **package:** update `dependencies` ([#22](https://github.com/webpack-contrib/schema-utils/issues/22)) ([3aecac6](https://github.com/webpack-contrib/schema-utils/commit/3aecac6))



<a name="0.4.3"></a>
## [0.4.3](https://github.com/webpack-contrib/schema-utils/compare/v0.4.2...v0.4.3) (2017-12-14)


### Bug Fixes

* **validateOptions:** throw `err` instead of `process.exit(1)` ([#17](https://github.com/webpack-contrib/schema-utils/issues/17)) ([c595eda](https://github.com/webpack-contrib/schema-utils/commit/c595eda))
* **ValidationError:** never return `this` in the ctor ([#16](https://github.com/webpack-contrib/schema-utils/issues/16)) ([c723791](https://github.com/webpack-contrib/schema-utils/commit/c723791))



<a name="0.4.2"></a>
## [0.4.2](https://github.com/webpack-contrib/schema-utils/compare/v0.4.1...v0.4.2) (2017-11-09)


### Bug Fixes

* **validateOptions:** catch `ValidationError` and handle it internally ([#15](https://github.com/webpack-contrib/schema-utils/issues/15)) ([9c5ef5e](https://github.com/webpack-contrib/schema-utils/commit/9c5ef5e))



<a name="0.4.1"></a>
## [0.4.1](https://github.com/webpack-contrib/schema-utils/compare/v0.4.0...v0.4.1) (2017-11-03)


### Bug Fixes

* **ValidationError:** use `Error.captureStackTrace` for `err.stack` handling ([#14](https://github.com/webpack-contrib/schema-utils/issues/14)) ([a6fb974](https://github.com/webpack-contrib/schema-utils/commit/a6fb974))



<a name="0.4.0"></a>
# [0.4.0](https://github.com/webpack-contrib/schema-utils/compare/v0.3.0...v0.4.0) (2017-10-28)


### Features

* add support for `typeof`, `instanceof` (`{Function\|RegExp}`) ([#10](https://github.com/webpack-contrib/schema-utils/issues/10)) ([9f01816](https://github.com/webpack-contrib/schema-utils/commit/9f01816))



<a name="0.3.0"></a>
# [0.3.0](https://github.com/webpack-contrib/schema-utils/compare/v0.2.1...v0.3.0) (2017-04-29)


### Features

* add ValidationError ([#8](https://github.com/webpack-contrib/schema-utils/issues/8)) ([d48f0fb](https://github.com/webpack-contrib/schema-utils/commit/d48f0fb))



<a name="0.2.1"></a>
## [0.2.1](https://github.com/webpack-contrib/schema-utils/compare/v0.2.0...v0.2.1) (2017-03-13)


### Bug Fixes

* Include .babelrc to `files` ([28f0363](https://github.com/webpack-contrib/schema-utils/commit/28f0363))
* Include source to `files` ([43b0f2f](https://github.com/webpack-contrib/schema-utils/commit/43b0f2f))



<a name="0.2.0"></a>
# [0.2.0](https://github.com/webpack-contrib/schema-utils/compare/v0.1.0...v0.2.0) (2017-03-12)

<a name="0.1.0"></a>
# 0.1.0 (2017-03-07)


### Features

* **validations:** add validateOptions module ([ae9b47b](https://github.com/webpack-contrib/schema-utils/commit/ae9b47b))



# Change Log

All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.


---

<div align="center">
  <a href="http://json-schema.org">
    <img width="160" height="160"
      src="https://raw.githubusercontent.com/webpack-contrib/schema-utils/master/.github/assets/logo.png">
  </a>
  <a href="https://github.com/webpack/webpack">
    <img width="200" height="200"
      src="https://webpack.js.org/assets/icon-square-big.svg">
  </a>
</div>

[![npm][npm]][npm-url]
[![node][node]][node-url]
[![deps][deps]][deps-url]
[![tests][tests]][tests-url]
[![coverage][cover]][cover-url]
[![chat][chat]][chat-url]
[![size][size]][size-url]

# schema-utils

Package for validate options in loaders and plugins.

## Getting Started

To begin, you'll need to install `schema-utils`:

```console
npm install schema-utils
```

## API

**schema.json**

```json
{
  "type": "object",
  "properties": {
    "option": {
      "type": "boolean"
    }
  },
  "additionalProperties": false
}
```

```js
import schema from "./path/to/schema.json";
import { validate } from "schema-utils";

const options = { option: true };
const configuration = { name: "Loader Name/Plugin Name/Name" };

validate(schema, options, configuration);
```

### `schema`

Type: `String`

JSON schema.

Simple example of schema:

```json
{
  "type": "object",
  "properties": {
    "name": {
      "description": "This is description of option.",
      "type": "string"
    }
  },
  "additionalProperties": false
}
```

### `options`

Type: `Object`

Object with options.

```js
import schema from "./path/to/schema.json";
import { validate } from "schema-utils";

const options = { foo: "bar" };

validate(schema, { name: 123 }, { name: "MyPlugin" });
```

### `configuration`

Allow to configure validator.

There is an alternative method to configure the `name` and`baseDataPath` options via the `title` property in the schema.
For example:

```json
{
  "title": "My Loader options",
  "type": "object",
  "properties": {
    "name": {
      "description": "This is description of option.",
      "type": "string"
    }
  },
  "additionalProperties": false
}
```

The last word used for the `baseDataPath` option, other words used for the `name` option.
Based on the example above the `name` option equals `My Loader`, the `baseDataPath` option equals `options`.

#### `name`

Type: `Object`
Default: `"Object"`

Allow to setup name in validation errors.

```js
import schema from "./path/to/schema.json";
import { validate } from "schema-utils";

const options = { foo: "bar" };

validate(schema, options, { name: "MyPlugin" });
```

```shell
Invalid configuration object. MyPlugin has been initialised using a configuration object that does not match the API schema.
 - configuration.optionName should be a integer.
```

#### `baseDataPath`

Type: `String`
Default: `"configuration"`

Allow to setup base data path in validation errors.

```js
import schema from "./path/to/schema.json";
import { validate } from "schema-utils";

const options = { foo: "bar" };

validate(schema, options, { name: "MyPlugin", baseDataPath: "options" });
```

```shell
Invalid options object. MyPlugin has been initialised using an options object that does not match the API schema.
 - options.optionName should be a integer.
```

#### `postFormatter`

Type: `Function`
Default: `undefined`

Allow to reformat errors.

```js
import schema from "./path/to/schema.json";
import { validate } from "schema-utils";

const options = { foo: "bar" };

validate(schema, options, {
  name: "MyPlugin",
  postFormatter: (formattedError, error) => {
    if (error.keyword === "type") {
      return `${formattedError}\nAdditional Information.`;
    }

    return formattedError;
  },
});
```

```shell
Invalid options object. MyPlugin has been initialized using an options object that does not match the API schema.
 - options.optionName should be a integer.
   Additional Information.
```

## Examples

**schema.json**

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "test": {
      "anyOf": [
        { "type": "array" },
        { "type": "string" },
        { "instanceof": "RegExp" }
      ]
    },
    "transform": {
      "instanceof": "Function"
    },
    "sourceMap": {
      "type": "boolean"
    }
  },
  "additionalProperties": false
}
```

### `Loader`

```js
import { getOptions } from "loader-utils";
import { validate } from "schema-utils";

import schema from "path/to/schema.json";

function loader(src, map) {
  const options = getOptions(this);

  validate(schema, options, {
    name: "Loader Name",
    baseDataPath: "options",
  });

  // Code...
}

export default loader;
```

### `Plugin`

```js
import { validate } from "schema-utils";

import schema from "path/to/schema.json";

class Plugin {
  constructor(options) {
    validate(schema, options, {
      name: "Plugin Name",
      baseDataPath: "options",
    });

    this.options = options;
  }

  apply(compiler) {
    // Code...
  }
}

export default Plugin;
```

## Contributing

Please take a moment to read our contributing guidelines if you haven't yet done so.

[CONTRIBUTING](./.github/CONTRIBUTING.md)

## License

[MIT](./LICENSE)

[npm]: https://img.shields.io/npm/v/schema-utils.svg
[npm-url]: https://npmjs.com/package/schema-utils
[node]: https://img.shields.io/node/v/schema-utils.svg
[node-url]: https://nodejs.org
[deps]: https://david-dm.org/webpack/schema-utils.svg
[deps-url]: https://david-dm.org/webpack/schema-utils
[tests]: https://github.com/webpack/schema-utils/workflows/schema-utils/badge.svg
[tests-url]: https://github.com/webpack/schema-utils/actions
[cover]: https://codecov.io/gh/webpack/schema-utils/branch/master/graph/badge.svg
[cover-url]: https://codecov.io/gh/webpack/schema-utils
[chat]: https://badges.gitter.im/webpack/webpack.svg
[chat-url]: https://gitter.im/webpack/webpack
[size]: https://packagephobia.com/badge?p=schema-utils
[size-url]: https://packagephobia.com/result?p=schema-utils


---

# object-assign [![Build Status](https://travis-ci.org/sindresorhus/object-assign.svg?branch=master)](https://travis-ci.org/sindresorhus/object-assign)

> ES2015 [`Object.assign()`](http://www.2ality.com/2014/01/object-assign.html) [ponyfill](https://ponyfill.com)


## Use the built-in

Node.js 4 and up, as well as every evergreen browser (Chrome, Edge, Firefox, Opera, Safari),
support `Object.assign()` :tada:. If you target only those environments, then by all
means, use `Object.assign()` instead of this package.


## Install

```
$ npm install --save object-assign
```


## Usage

```js
const objectAssign = require('object-assign');

objectAssign({foo: 0}, {bar: 1});
//=> {foo: 0, bar: 1}

// multiple sources
objectAssign({foo: 0}, {bar: 1}, {baz: 2});
//=> {foo: 0, bar: 1, baz: 2}

// overwrites equal keys
objectAssign({foo: 0}, {foo: 1}, {foo: 2});
//=> {foo: 2}

// ignores null and undefined sources
objectAssign({foo: 0}, null, {bar: 1}, undefined);
//=> {foo: 0, bar: 1}
```


## API

### objectAssign(target, [source, ...])

Assigns enumerable own properties of `source` objects to the `target` object and returns the `target` object. Additional `source` objects will overwrite previous ones.


## Resources

- [ES2015 spec - Object.assign](https://people.mozilla.org/~jorendorff/es6-draft.html#sec-object.assign)


## Related

- [deep-assign](https://github.com/sindresorhus/deep-assign) - Recursive `Object.assign()`


## License

MIT © [Sindre Sorhus](https://sindresorhus.com)


---

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [v1.13.4](https://github.com/inspect-js/object-inspect/compare/v1.13.3...v1.13.4) - 2025-02-04

### Commits

- [Fix] avoid being fooled by a `Symbol.toStringTag` [`fa5870d`](https://github.com/inspect-js/object-inspect/commit/fa5870da468a525d2f20193700f70752f506cbf7)
- [Tests] fix tests in node v6.0 - v6.4 [`2abfe1b`](https://github.com/inspect-js/object-inspect/commit/2abfe1bc3c69f9293c07c5cd65a9d7d87a628b84)
- [Dev Deps] update `es-value-fixtures`, `for-each`, `has-symbols` [`3edfb01`](https://github.com/inspect-js/object-inspect/commit/3edfb01cc8cce220fba0dfdfe2dc8bc955758cdd)

## [v1.13.3](https://github.com/inspect-js/object-inspect/compare/v1.13.2...v1.13.3) - 2024-11-09

### Commits

- [actions] split out node 10-20, and 20+ [`44395a8`](https://github.com/inspect-js/object-inspect/commit/44395a8fc1deda6718a5e125e86b9ffcaa1c7580)
- [Fix] `quoteStyle`: properly escape only the containing quotes [`5137f8f`](https://github.com/inspect-js/object-inspect/commit/5137f8f7bea69a7fc671bb683fd35f244f38fc52)
- [Refactor] clean up `quoteStyle` code [`450680c`](https://github.com/inspect-js/object-inspect/commit/450680cd50de4e689ee3b8e1d6db3a1bcf3fc18c)
- [Tests] add `quoteStyle` escaping tests [`e997c59`](https://github.com/inspect-js/object-inspect/commit/e997c595aeaea84fd98ca35d7e1c3b5ab3ae26e0)
- [Dev Deps] update `auto-changelog`, `es-value-fixtures`, `tape` [`d5a469c`](https://github.com/inspect-js/object-inspect/commit/d5a469c99ec07ccaeafc36ac4b36a93285086d48)
- [Tests] replace `aud` with `npm audit` [`fb7815f`](https://github.com/inspect-js/object-inspect/commit/fb7815f9b72cae277a04f65bbb0543f85b88be62)
- [Dev Deps] update `mock-property` [`11c817b`](https://github.com/inspect-js/object-inspect/commit/11c817bf10392aa017755962ba6bc89d731359ee)

## [v1.13.2](https://github.com/inspect-js/object-inspect/compare/v1.13.1...v1.13.2) - 2024-06-21

### Commits

- [readme] update badges [`8a51e6b`](https://github.com/inspect-js/object-inspect/commit/8a51e6bedaf389ec40cc4659e9df53e8543d176e)
- [Dev Deps] update `@ljharb/eslint-config`, `tape` [`ef05f58`](https://github.com/inspect-js/object-inspect/commit/ef05f58c9761a41416ab907299bf0fa79517014b)
- [Dev Deps] update `error-cause`, `has-tostringtag`, `tape` [`c0c6c26`](https://github.com/inspect-js/object-inspect/commit/c0c6c26c44cee6671f7c5d43d2b91d27c5c00d90)
- [Fix] Don't throw when `global` is not defined [`d4d0965`](https://github.com/inspect-js/object-inspect/commit/d4d096570f7dbd0e03266a96de11d05eb7b63e0f)
- [meta] add missing `engines.node` [`17a352a`](https://github.com/inspect-js/object-inspect/commit/17a352af6fe1ba6b70a19081674231eb1a50c940)
- [Dev Deps] update `globalthis` [`9c08884`](https://github.com/inspect-js/object-inspect/commit/9c08884aa662a149e2f11403f413927736b97da7)
- [Dev Deps] update `error-cause` [`6af352d`](https://github.com/inspect-js/object-inspect/commit/6af352d7c3929a4cc4c55768c27bf547a5e900f4)
- [Dev Deps] update `npmignore` [`94e617d`](https://github.com/inspect-js/object-inspect/commit/94e617d38831722562fa73dff4c895746861d267)
- [Dev Deps] update `mock-property` [`2ac24d7`](https://github.com/inspect-js/object-inspect/commit/2ac24d7e58cd388ad093c33249e413e05bbfd6c3)
- [Dev Deps] update `tape` [`46125e5`](https://github.com/inspect-js/object-inspect/commit/46125e58f1d1dcfb170ed3d1ea69da550ea8d77b)

## [v1.13.1](https://github.com/inspect-js/object-inspect/compare/v1.13.0...v1.13.1) - 2023-10-19

### Commits

- [Fix] in IE 8, global can !== window despite them being prototypes of each other [`30d0859`](https://github.com/inspect-js/object-inspect/commit/30d0859dc4606cf75c2410edcd5d5c6355f8d372)

## [v1.13.0](https://github.com/inspect-js/object-inspect/compare/v1.12.3...v1.13.0) - 2023-10-14

### Commits

- [New] add special handling for the global object [`431bab2`](https://github.com/inspect-js/object-inspect/commit/431bab21a490ee51d35395966a504501e8c685da)
- [Dev Deps] update `@ljharb/eslint-config`, `aud`, `tape` [`fd4f619`](https://github.com/inspect-js/object-inspect/commit/fd4f6193562b4b0e95dcf5c0201b4e8cbbc4f58d)
- [Dev Deps] update `mock-property`, `tape` [`b453f6c`](https://github.com/inspect-js/object-inspect/commit/b453f6ceeebf8a1b738a1029754092e0367a4134)
- [Dev Deps] update `error-cause` [`e8ffc57`](https://github.com/inspect-js/object-inspect/commit/e8ffc577d73b92bb6a4b00c44f14e3319e374888)
- [Dev Deps] update `tape` [`054b8b9`](https://github.com/inspect-js/object-inspect/commit/054b8b9b98633284cf989e582450ebfbbe53503c)
- [Dev Deps] temporarily remove `aud` due to breaking change in transitive deps [`2476845`](https://github.com/inspect-js/object-inspect/commit/2476845e0678dd290c541c81cd3dec8420782c52)
- [Dev Deps] pin `glob`, since v10.3.8+ requires a broken `jackspeak` [`383fa5e`](https://github.com/inspect-js/object-inspect/commit/383fa5eebc0afd705cc778a4b49d8e26452e49a8)
- [Dev Deps] pin `jackspeak` since 2.1.2+ depends on npm aliases, which kill the install process in npm &lt; 6 [`68c244c`](https://github.com/inspect-js/object-inspect/commit/68c244c5174cdd877e5dcb8ee90aa3f44b2f25be)

## [v1.12.3](https://github.com/inspect-js/object-inspect/compare/v1.12.2...v1.12.3) - 2023-01-12

### Commits

- [Fix] in eg FF 24, collections lack forEach [`75fc226`](https://github.com/inspect-js/object-inspect/commit/75fc22673c82d45f28322b1946bb0eb41b672b7f)
- [actions] update rebase action to use reusable workflow [`250a277`](https://github.com/inspect-js/object-inspect/commit/250a277a095e9dacc029ab8454dcfc15de549dcd)
- [Dev Deps] update `aud`, `es-value-fixtures`, `tape` [`66a19b3`](https://github.com/inspect-js/object-inspect/commit/66a19b3209ccc3c5ef4b34c3cb0160e65d1ce9d5)
- [Dev Deps] update `@ljharb/eslint-config`, `aud`, `error-cause` [`c43d332`](https://github.com/inspect-js/object-inspect/commit/c43d3324b48384a16fd3dc444e5fc589d785bef3)
- [Tests] add `@pkgjs/support` to `postlint` [`e2618d2`](https://github.com/inspect-js/object-inspect/commit/e2618d22a7a3fa361b6629b53c1752fddc9c4d80)

## [v1.12.2](https://github.com/inspect-js/object-inspect/compare/v1.12.1...v1.12.2) - 2022-05-26

### Commits

- [Fix] use `util.inspect` for a custom inspection symbol method [`e243bf2`](https://github.com/inspect-js/object-inspect/commit/e243bf2eda6c4403ac6f1146fddb14d12e9646c1)
- [meta] add support info [`ca20ba3`](https://github.com/inspect-js/object-inspect/commit/ca20ba35713c17068ca912a86c542f5e8acb656c)
- [Fix] ignore `cause` in node v16.9 and v16.10 where it has a bug [`86aa553`](https://github.com/inspect-js/object-inspect/commit/86aa553a4a455562c2c56f1540f0bf857b9d314b)

## [v1.12.1](https://github.com/inspect-js/object-inspect/compare/v1.12.0...v1.12.1) - 2022-05-21

### Commits

- [Tests] use `mock-property` [`4ec8893`](https://github.com/inspect-js/object-inspect/commit/4ec8893ea9bfd28065ca3638cf6762424bf44352)
- [meta] use `npmignore` to autogenerate an npmignore file [`07f868c`](https://github.com/inspect-js/object-inspect/commit/07f868c10bd25a9d18686528339bb749c211fc9a)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `aud`, `auto-changelog`, `tape` [`b05244b`](https://github.com/inspect-js/object-inspect/commit/b05244b4f331e00c43b3151bc498041be77ccc91)
- [Dev Deps] update `@ljharb/eslint-config`, `error-cause`, `es-value-fixtures`, `functions-have-names`, `tape` [`d037398`](https://github.com/inspect-js/object-inspect/commit/d037398dcc5d531532e4c19c4a711ed677f579c1)
- [Fix] properly handle callable regexes in older engines [`848fe48`](https://github.com/inspect-js/object-inspect/commit/848fe48bd6dd0064ba781ee6f3c5e54a94144c37)

## [v1.12.0](https://github.com/inspect-js/object-inspect/compare/v1.11.1...v1.12.0) - 2021-12-18

### Commits

- [New] add `numericSeparator` boolean option [`2d2d537`](https://github.com/inspect-js/object-inspect/commit/2d2d537f5359a4300ce1c10241369f8024f89e11)
- [Robustness] cache more prototype methods [`191533d`](https://github.com/inspect-js/object-inspect/commit/191533da8aec98a05eadd73a5a6e979c9c8653e8)
- [New] ensure an Error’s `cause` is displayed [`53bc2ce`](https://github.com/inspect-js/object-inspect/commit/53bc2cee4e5a9cc4986f3cafa22c0685f340715e)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config` [`bc164b6`](https://github.com/inspect-js/object-inspect/commit/bc164b6e2e7d36b263970f16f54de63048b84a36)
- [Robustness] cache `RegExp.prototype.test` [`a314ab8`](https://github.com/inspect-js/object-inspect/commit/a314ab8271b905cbabc594c82914d2485a8daf12)
- [meta] fix auto-changelog settings [`5ed0983`](https://github.com/inspect-js/object-inspect/commit/5ed0983be72f73e32e2559997517a95525c7e20d)

## [v1.11.1](https://github.com/inspect-js/object-inspect/compare/v1.11.0...v1.11.1) - 2021-12-05

### Commits

- [meta] add `auto-changelog` [`7dbdd22`](https://github.com/inspect-js/object-inspect/commit/7dbdd228401d6025d8b7391476d88aee9ea9bbdf)
- [actions] reuse common workflows [`c8823bc`](https://github.com/inspect-js/object-inspect/commit/c8823bc0a8790729680709d45fb6e652432e91aa)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `safe-publish-latest`, `tape` [`7532b12`](https://github.com/inspect-js/object-inspect/commit/7532b120598307497b712890f75af8056f6d37a6)
- [Refactor] use `has-tostringtag` to behave correctly in the presence of symbol shams [`94abb5d`](https://github.com/inspect-js/object-inspect/commit/94abb5d4e745bf33253942dea86b3e538d2ff6c6)
- [actions] update codecov uploader [`5ed5102`](https://github.com/inspect-js/object-inspect/commit/5ed51025267a00e53b1341357315490ac4eb0874)
- [Dev Deps] update `eslint`, `tape` [`37b2ad2`](https://github.com/inspect-js/object-inspect/commit/37b2ad26c08d94bfd01d5d07069a0b28ef4e2ad7)
- [meta] add `sideEffects` flag [`d341f90`](https://github.com/inspect-js/object-inspect/commit/d341f905ef8bffa6a694cda6ddc5ba343532cd4f)

## [v1.11.0](https://github.com/inspect-js/object-inspect/compare/v1.10.3...v1.11.0) - 2021-07-12

### Commits

- [New] `customInspect`: add `symbol` option, to mimic modern util.inspect behavior [`e973a6e`](https://github.com/inspect-js/object-inspect/commit/e973a6e21f8140c5837cf25e9d89bdde88dc3120)
- [Dev Deps] update `eslint` [`05f1cb3`](https://github.com/inspect-js/object-inspect/commit/05f1cb3cbcfe1f238e8b51cf9bc294305b7ed793)

## [v1.10.3](https://github.com/inspect-js/object-inspect/compare/v1.10.2...v1.10.3) - 2021-05-07

### Commits

- [Fix] handle core-js Symbol shams [`4acfc2c`](https://github.com/inspect-js/object-inspect/commit/4acfc2c4b503498759120eb517abad6d51c9c5d6)
- [readme] update badges [`95c323a`](https://github.com/inspect-js/object-inspect/commit/95c323ad909d6cbabb95dd6015c190ba6db9c1f2)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `aud` [`cb38f48`](https://github.com/inspect-js/object-inspect/commit/cb38f485de6ec7a95109b5a9bbd0a1deba2f6611)

## [v1.10.2](https://github.com/inspect-js/object-inspect/compare/v1.10.1...v1.10.2) - 2021-04-17

### Commits

- [Fix] use a robust check for a boxed Symbol [`87f12d6`](https://github.com/inspect-js/object-inspect/commit/87f12d6e69ce530be04659c81a4cd502943acac5)

## [v1.10.1](https://github.com/inspect-js/object-inspect/compare/v1.10.0...v1.10.1) - 2021-04-17

### Commits

- [Fix] use a robust check for a boxed bigint [`d5ca829`](https://github.com/inspect-js/object-inspect/commit/d5ca8298b6d2e5c7b9334a5b21b96ed95d225c91)

## [v1.10.0](https://github.com/inspect-js/object-inspect/compare/v1.9.0...v1.10.0) - 2021-04-17

### Commits

- [Tests] increase coverage [`d8abb8a`](https://github.com/inspect-js/object-inspect/commit/d8abb8a62c2f084919df994a433b346e0d87a227)
- [actions] use `node/install` instead of `node/run`; use `codecov` action [`4bfec2e`](https://github.com/inspect-js/object-inspect/commit/4bfec2e30aaef6ddef6cbb1448306f9f8b9520b7)
- [New] respect `Symbol.toStringTag` on objects [`799b58f`](https://github.com/inspect-js/object-inspect/commit/799b58f536a45e4484633a8e9daeb0330835f175)
- [Fix] do not allow Symbol.toStringTag to masquerade as builtins [`d6c5b37`](https://github.com/inspect-js/object-inspect/commit/d6c5b37d7e94427796b82432fb0c8964f033a6ab)
- [New] add `WeakRef` support [`b6d898e`](https://github.com/inspect-js/object-inspect/commit/b6d898ee21868c780a7ee66b28532b5b34ed7f09)
- [meta] do not publish github action workflow files [`918cdfc`](https://github.com/inspect-js/object-inspect/commit/918cdfc4b6fe83f559ff6ef04fe66201e3ff5cbd)
- [meta] create `FUNDING.yml` [`0bb5fc5`](https://github.com/inspect-js/object-inspect/commit/0bb5fc516dbcd2cd728bd89cee0b580acc5ce301)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `aud`, `tape` [`22c8dc0`](https://github.com/inspect-js/object-inspect/commit/22c8dc0cac113d70f4781e49a950070923a671be)
- [meta] use `prepublishOnly` script for npm 7+ [`e52ee09`](https://github.com/inspect-js/object-inspect/commit/e52ee09e8050b8dbac94ef57f786675567728223)
- [Dev Deps] update `eslint` [`7c4e6fd`](https://github.com/inspect-js/object-inspect/commit/7c4e6fdedcd27cc980e13c9ad834d05a96f3d40c)

## [v1.9.0](https://github.com/inspect-js/object-inspect/compare/v1.8.0...v1.9.0) - 2020-11-30

### Commits

- [Tests] migrate tests to Github Actions [`d262251`](https://github.com/inspect-js/object-inspect/commit/d262251e13e16d3490b5473672f6b6d6ff86675d)
- [New] add enumerable own Symbols to plain object output [`ee60c03`](https://github.com/inspect-js/object-inspect/commit/ee60c033088cff9d33baa71e59a362a541b48284)
- [Tests] add passing tests [`01ac3e4`](https://github.com/inspect-js/object-inspect/commit/01ac3e4b5a30f97875a63dc9b1416b3bd626afc9)
- [actions] add "Require Allow Edits" action [`c2d7746`](https://github.com/inspect-js/object-inspect/commit/c2d774680cde4ca4af332d84d4121b26f798ba9e)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `aud`, `core-js` [`70058de`](https://github.com/inspect-js/object-inspect/commit/70058de1579fc54d1d15ed6c2dbe246637ce70ff)
- [Fix] hex characters in strings should be uppercased, to match node `assert` [`6ab8faa`](https://github.com/inspect-js/object-inspect/commit/6ab8faaa0abc08fe7a8e2afd8b39c6f1f0e00113)
- [Tests] run `nyc` on all tests [`4c47372`](https://github.com/inspect-js/object-inspect/commit/4c473727879ddc8e28b599202551ddaaf07b6210)
- [Tests] node 0.8 has an unpredictable property order; fix `groups` test by removing property [`f192069`](https://github.com/inspect-js/object-inspect/commit/f192069a978a3b60e6f0e0d45ac7df260ab9a778)
- [New] add enumerable properties to Function inspect result, per node’s `assert` [`fd38e1b`](https://github.com/inspect-js/object-inspect/commit/fd38e1bc3e2a1dc82091ce3e021917462eee64fc)
- [Tests] fix tests for node &lt; 10, due to regex match `groups` [`2ac6462`](https://github.com/inspect-js/object-inspect/commit/2ac6462cc4f72eaa0b63a8cfee9aabe3008b2330)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config` [`44b59e2`](https://github.com/inspect-js/object-inspect/commit/44b59e2676a7f825ef530dfd19dafb599e3b9456)
- [Robustness] cache `Symbol.prototype.toString` [`f3c2074`](https://github.com/inspect-js/object-inspect/commit/f3c2074d8f32faf8292587c07c9678ea931703dd)
- [Dev Deps] update `eslint` [`9411294`](https://github.com/inspect-js/object-inspect/commit/94112944b9245e3302e25453277876402d207e7f)
- [meta] `require-allow-edits` no longer requires an explicit github token [`36c0220`](https://github.com/inspect-js/object-inspect/commit/36c02205de3c2b0e84d53777c5c9fd54a36c48ab)
- [actions] update rebase checkout action to v2 [`55a39a6`](https://github.com/inspect-js/object-inspect/commit/55a39a64e944f19c6a7d8efddf3df27700f20d14)
- [actions] switch Automatic Rebase workflow to `pull_request_target` event [`f59fd3c`](https://github.com/inspect-js/object-inspect/commit/f59fd3cf406c3a7c7ece140904a80bbc6bacfcca)
- [Dev Deps] update `eslint` [`a492bec`](https://github.com/inspect-js/object-inspect/commit/a492becec644b0155c9c4bc1caf6f9fac11fb2c7)

## [v1.8.0](https://github.com/inspect-js/object-inspect/compare/v1.7.0...v1.8.0) - 2020-06-18

### Fixed

- [New] add `indent` option [`#27`](https://github.com/inspect-js/object-inspect/issues/27)

### Commits

- [Tests] add codecov [`4324cbb`](https://github.com/inspect-js/object-inspect/commit/4324cbb1a2bd7710822a4151ff373570db22453e)
- [New] add `maxStringLength` option [`b3995cb`](https://github.com/inspect-js/object-inspect/commit/b3995cb71e15b5ee127a3094c43994df9d973502)
- [New] add `customInspect` option, to disable custom inspect methods [`28b9179`](https://github.com/inspect-js/object-inspect/commit/28b9179ee802bb3b90810100c11637db90c2fb6d)
- [Tests] add Date and RegExp tests [`3b28eca`](https://github.com/inspect-js/object-inspect/commit/3b28eca57b0367aeadffac604ea09e8bdae7d97b)
- [actions] add automatic rebasing / merge commit blocking [`0d9c6c0`](https://github.com/inspect-js/object-inspect/commit/0d9c6c044e83475ff0bfffb9d35b149834c83a2e)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `core-js`, `tape`; add `aud` [`7c204f2`](https://github.com/inspect-js/object-inspect/commit/7c204f22b9e41bc97147f4d32d4cb045b17769a6)
- [readme] fix repo URLs, remove testling [`34ca9a0`](https://github.com/inspect-js/object-inspect/commit/34ca9a0dabfe75bd311f806a326fadad029909a3)
- [Fix] when truncating a deep array, note it as `[Array]` instead of just `[Object]` [`f74c82d`](https://github.com/inspect-js/object-inspect/commit/f74c82dd0b35386445510deb250f34c41be3ec0e)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `tape` [`1a8a5ea`](https://github.com/inspect-js/object-inspect/commit/1a8a5ea069ea2bee89d77caedad83ffa23d35711)
- [Fix] do not be fooled by a function’s own `toString` method [`7cb5c65`](https://github.com/inspect-js/object-inspect/commit/7cb5c657a976f94715c19c10556a30f15bb7d5d7)
- [patch] indicate explicitly that anon functions are anonymous, to match node [`81ebdd4`](https://github.com/inspect-js/object-inspect/commit/81ebdd4215005144074bbdff3f6bafa01407910a)
- [Dev Deps] loosen the `core-js` dep [`e7472e8`](https://github.com/inspect-js/object-inspect/commit/e7472e8e242117670560bd995830c2a4d12080f5)
- [Dev Deps] update `tape` [`699827e`](https://github.com/inspect-js/object-inspect/commit/699827e6b37258b5203c33c78c009bf4b0e6a66d)
- [meta] add `safe-publish-latest` [`c5d2868`](https://github.com/inspect-js/object-inspect/commit/c5d2868d6eb33c472f37a20f89ceef2787046088)
- [Dev Deps] update `@ljharb/eslint-config` [`9199501`](https://github.com/inspect-js/object-inspect/commit/919950195d486114ccebacbdf9d74d7f382693b0)

## [v1.7.0](https://github.com/inspect-js/object-inspect/compare/v1.6.0...v1.7.0) - 2019-11-10

### Commits

- [Tests] use shared travis-ci configs [`19899ed`](https://github.com/inspect-js/object-inspect/commit/19899edbf31f4f8809acf745ce34ad1ce1bfa63b)
- [Tests] add linting [`a00f057`](https://github.com/inspect-js/object-inspect/commit/a00f057d917f66ea26dd37769c6b810ec4af97e8)
- [Tests] lint last file [`2698047`](https://github.com/inspect-js/object-inspect/commit/2698047b58af1e2e88061598ef37a75f228dddf6)
- [Tests] up to `node` `v12.7`, `v11.15`, `v10.16`, `v8.16`, `v6.17` [`589e87a`](https://github.com/inspect-js/object-inspect/commit/589e87a99cadcff4b600e6a303418e9d922836e8)
- [New] add support for `WeakMap` and `WeakSet` [`3ddb3e4`](https://github.com/inspect-js/object-inspect/commit/3ddb3e4e0c8287130c61a12e0ed9c104b1549306)
- [meta] clean up license so github can detect it properly [`27527bb`](https://github.com/inspect-js/object-inspect/commit/27527bb801520c9610c68cc3b55d6f20a2bee56d)
- [Tests] cover `util.inspect.custom` [`36d47b9`](https://github.com/inspect-js/object-inspect/commit/36d47b9c59056a57ef2f1491602c726359561800)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `core-js`, `tape` [`b614eaa`](https://github.com/inspect-js/object-inspect/commit/b614eaac901da0e5c69151f534671f990a94cace)
- [Tests] fix coverage thresholds [`7b7b176`](https://github.com/inspect-js/object-inspect/commit/7b7b176e15f8bd6e8b2f261ff5a493c2fe78d9c2)
- [Tests] bigint tests now can run on unflagged node [`063af31`](https://github.com/inspect-js/object-inspect/commit/063af31ce9cd13c202e3b67c07ba06dc9b7c0f81)
- [Refactor] add early bailout to `isMap` and `isSet` checks [`fc51047`](https://github.com/inspect-js/object-inspect/commit/fc5104714a3671d37e225813db79470d6335683b)
- [meta] add `funding` field [`7f9953a`](https://github.com/inspect-js/object-inspect/commit/7f9953a113eec7b064a6393cf9f90ba15f1d131b)
- [Tests] Fix invalid strict-mode syntax with hexadecimal [`a8b5425`](https://github.com/inspect-js/object-inspect/commit/a8b542503b4af1599a275209a1a99f5fdedb1ead)
- [Dev Deps] update `@ljharb/eslint-config` [`98df157`](https://github.com/inspect-js/object-inspect/commit/98df1577314d9188a3fc3f17fdcf2fba697ae1bd)
- add copyright to LICENSE [`bb69fd0`](https://github.com/inspect-js/object-inspect/commit/bb69fd017a062d299e44da1f9b2c7dcd67f621e6)
- [Tests] use `npx aud` in `posttest` [`4838353`](https://github.com/inspect-js/object-inspect/commit/4838353593974cf7f905b9ef04c03c094f0cdbe2)
- [Tests] move `0.6` to allowed failures, because it won‘t build on travis [`1bff32a`](https://github.com/inspect-js/object-inspect/commit/1bff32aa52e8aea687f0856b28ba754b3e43ebf7)

## [v1.6.0](https://github.com/inspect-js/object-inspect/compare/v1.5.0...v1.6.0) - 2018-05-02

### Commits

- [New] add support for boxed BigInt primitives [`356c66a`](https://github.com/inspect-js/object-inspect/commit/356c66a410e7aece7162c8319880a5ef647beaa9)
- [Tests] up to `node` `v10.0`, `v9.11`, `v8.11`, `v6.14`, `v4.9` [`c77b65b`](https://github.com/inspect-js/object-inspect/commit/c77b65bba593811b906b9ec57561c5cba92e2db3)
- [New] Add support for upcoming `BigInt` [`1ac548e`](https://github.com/inspect-js/object-inspect/commit/1ac548e4b27e26466c28c9a5e63e5d4e0591c31f)
- [Tests] run bigint tests in CI with --harmony-bigint flag [`d31b738`](https://github.com/inspect-js/object-inspect/commit/d31b73831880254b5c6cf5691cda9a149fbc5f04)
- [Dev Deps] update `core-js`, `tape` [`ff9eff6`](https://github.com/inspect-js/object-inspect/commit/ff9eff67113341ee1aaf80c1c22d683f43bfbccf)
- [Docs] fix example to use `safer-buffer` [`48cae12`](https://github.com/inspect-js/object-inspect/commit/48cae12a73ec6cacc955175bc56bbe6aee6a211f)

## [v1.5.0](https://github.com/inspect-js/object-inspect/compare/v1.4.1...v1.5.0) - 2017-12-25

### Commits

- [New] add `quoteStyle` option [`f5a72d2`](https://github.com/inspect-js/object-inspect/commit/f5a72d26edb3959b048f74c056ca7100a6b091e4)
- [Tests] add more test coverage [`30ebe4e`](https://github.com/inspect-js/object-inspect/commit/30ebe4e1fa943b99ecbb85be7614256d536e2759)
- [Tests] require 0.6 to pass [`99a008c`](https://github.com/inspect-js/object-inspect/commit/99a008ccace189a60fd7da18bf00e32c9572b980)

## [v1.4.1](https://github.com/inspect-js/object-inspect/compare/v1.4.0...v1.4.1) - 2017-12-19

### Commits

- [Tests] up to `node` `v9.3`, `v8.9`, `v6.12` [`6674476`](https://github.com/inspect-js/object-inspect/commit/6674476cc56acaac1bde96c84fed5ef631911906)
- [Fix] `inspect(Object(-0))` should be “Object(-0)”, not “Object(0)” [`d0a031f`](https://github.com/inspect-js/object-inspect/commit/d0a031f1cbb3024ee9982bfe364dd18a7e4d1bd3)

## [v1.4.0](https://github.com/inspect-js/object-inspect/compare/v1.3.0...v1.4.0) - 2017-10-24

### Commits

- [Tests] add `npm run coverage` [`3b48fb2`](https://github.com/inspect-js/object-inspect/commit/3b48fb25db037235eeb808f0b2830aad7aa36f70)
- [Tests] remove commented-out osx builds [`71e24db`](https://github.com/inspect-js/object-inspect/commit/71e24db8ad6ee3b9b381c5300b0475f2ba595a73)
- [New] add support for `util.inspect.custom`, in node only. [`20cca77`](https://github.com/inspect-js/object-inspect/commit/20cca7762d7e17f15b21a90793dff84acce155df)
- [Tests] up to `node` `v8.6`; use `nvm install-latest-npm` to ensure new npm doesn’t break old node [`252952d`](https://github.com/inspect-js/object-inspect/commit/252952d230d8065851dd3d4d5fe8398aae068529)
- [Tests] up to `node` `v8.8` [`4aa868d`](https://github.com/inspect-js/object-inspect/commit/4aa868d3a62914091d489dd6ec6eed194ee67cd3)
- [Dev Deps] update `core-js`, `tape` [`59483d1`](https://github.com/inspect-js/object-inspect/commit/59483d1df418f852f51fa0db7b24aa6b0209a27a)

## [v1.3.0](https://github.com/inspect-js/object-inspect/compare/v1.2.2...v1.3.0) - 2017-07-31

### Fixed

- [Fix] Map/Set: work around core-js bug &lt; v2.5.0 [`#9`](https://github.com/inspect-js/object-inspect/issues/9)

### Commits

- [New] add support for arrays with additional object keys [`0d19937`](https://github.com/inspect-js/object-inspect/commit/0d199374ee37959e51539616666f420ccb29acb9)
- [Tests] up to `node` `v8.2`, `v7.10`, `v6.11`; fix new npm breaking on older nodes [`e24784a`](https://github.com/inspect-js/object-inspect/commit/e24784a90c49117787157a12a63897c49cf89bbb)
- Only apps should have lockfiles [`c6faebc`](https://github.com/inspect-js/object-inspect/commit/c6faebcb2ee486a889a4a1c4d78c0776c7576185)
- [Dev Deps] update `tape` [`7345a0a`](https://github.com/inspect-js/object-inspect/commit/7345a0aeba7e91b888a079c10004d17696a7f586)

## [v1.2.2](https://github.com/inspect-js/object-inspect/compare/v1.2.1...v1.2.2) - 2017-03-24

### Commits

- [Tests] up to `node` `v7.7`, `v6.10`, `v4.8`; improve test matrix [`a2ddc15`](https://github.com/inspect-js/object-inspect/commit/a2ddc15a1f2c65af18076eea1c0eb9cbceb478a0)
- [Tests] up to `node` `v7.0`, `v6.9`, `v5.12`, `v4.6`, `io.js` `v3.3`; improve test matrix [`a48949f`](https://github.com/inspect-js/object-inspect/commit/a48949f6b574b2d4d2298109d8e8d0eb3e7a83e7)
- [Performance] check for primitive types as early as possible. [`3b8092a`](https://github.com/inspect-js/object-inspect/commit/3b8092a2a4deffd0575f94334f00194e2d48dad3)
- [Refactor] remove unneeded `else`s. [`7255034`](https://github.com/inspect-js/object-inspect/commit/725503402e08de4f96f6bf2d8edef44ac36f26b6)
- [Refactor] avoid recreating `lowbyte` function every time. [`81edd34`](https://github.com/inspect-js/object-inspect/commit/81edd3475bd15bdd18e84de7472033dcf5004aaa)
- [Fix] differentiate -0 from 0 [`521d345`](https://github.com/inspect-js/object-inspect/commit/521d3456b009da7bf1c5785c8a9df5a9f8718264)
- [Refactor] move object key gathering into separate function [`aca6265`](https://github.com/inspect-js/object-inspect/commit/aca626536eaeef697196c6e9db3e90e7e0355b6a)
- [Refactor] consolidate wrapping logic for boxed primitives into a function. [`4e440cd`](https://github.com/inspect-js/object-inspect/commit/4e440cd9065df04802a2a1dead03f48c353ca301)
- [Robustness] use `typeof` instead of comparing to literal `undefined` [`5ca6f60`](https://github.com/inspect-js/object-inspect/commit/5ca6f601937506daff8ed2fcf686363b55807b69)
- [Refactor] consolidate Map/Set notations. [`4e576e5`](https://github.com/inspect-js/object-inspect/commit/4e576e5d7ed2f9ec3fb7f37a0d16732eb10758a9)
- [Tests] ensure that this function remains anonymous, despite ES6 name inference. [`7540ae5`](https://github.com/inspect-js/object-inspect/commit/7540ae591278756db614fa4def55ca413150e1a3)
- [Refactor] explicitly coerce Error objects to strings. [`7f4ca84`](https://github.com/inspect-js/object-inspect/commit/7f4ca8424ee8dc2c0ca5a422d94f7fac40327261)
- [Refactor] split up `var` declarations for debuggability [`6f2c11e`](https://github.com/inspect-js/object-inspect/commit/6f2c11e6a85418586a00292dcec5e97683f89bc3)
- [Robustness] cache `Object.prototype.toString` [`df44a20`](https://github.com/inspect-js/object-inspect/commit/df44a20adfccf31529d60d1df2079bfc3c836e27)
- [Dev Deps] update `tape` [`3ec714e`](https://github.com/inspect-js/object-inspect/commit/3ec714eba57bc3f58a6eb4fca1376f49e70d300a)
- [Dev Deps] update `tape` [`beb72d9`](https://github.com/inspect-js/object-inspect/commit/beb72d969653747d7cde300393c28755375329b0)

## [v1.2.1](https://github.com/inspect-js/object-inspect/compare/v1.2.0...v1.2.1) - 2016-04-09

### Fixed

- [Fix] fix Boolean `false` object inspection. [`#7`](https://github.com/substack/object-inspect/pull/7)

## [v1.2.0](https://github.com/inspect-js/object-inspect/compare/v1.1.0...v1.2.0) - 2016-04-09

### Fixed

- [New] add support for inspecting String/Number/Boolean objects. [`#6`](https://github.com/inspect-js/object-inspect/issues/6)

### Commits

- [Dev Deps] update `tape` [`742caa2`](https://github.com/inspect-js/object-inspect/commit/742caa262cf7af4c815d4821c8bd0129c1446432)

## [v1.1.0](https://github.com/inspect-js/object-inspect/compare/1.0.2...v1.1.0) - 2015-12-14

### Merged

- [New] add ES6 Map/Set support. [`#4`](https://github.com/inspect-js/object-inspect/pull/4)

### Fixed

- [New] add ES6 Map/Set support. [`#3`](https://github.com/inspect-js/object-inspect/issues/3)

### Commits

- Update `travis.yml` to test on bunches of `iojs` and `node` versions. [`4c1fd65`](https://github.com/inspect-js/object-inspect/commit/4c1fd65cc3bd95307e854d114b90478324287fd2)
- [Dev Deps] update `tape` [`88a907e`](https://github.com/inspect-js/object-inspect/commit/88a907e33afbe408e4b5d6e4e42a33143f88848c)

## [1.0.2](https://github.com/inspect-js/object-inspect/compare/1.0.1...1.0.2) - 2015-08-07

### Commits

- [Fix] Cache `Object.prototype.hasOwnProperty` in case it's deleted later. [`1d0075d`](https://github.com/inspect-js/object-inspect/commit/1d0075d3091dc82246feeb1f9871cb2b8ed227b3)
- [Dev Deps] Update `tape` [`ca8d5d7`](https://github.com/inspect-js/object-inspect/commit/ca8d5d75635ddbf76f944e628267581e04958457)
- gitignore node_modules since this is a reusable modules. [`ed41407`](https://github.com/inspect-js/object-inspect/commit/ed41407811743ca530cdeb28f982beb96026af82)

## [1.0.1](https://github.com/inspect-js/object-inspect/compare/1.0.0...1.0.1) - 2015-07-19

### Commits

- Make `inspect` work with symbol primitives and objects, including in node 0.11 and 0.12. [`ddf1b94`](https://github.com/inspect-js/object-inspect/commit/ddf1b94475ab951f1e3bccdc0a48e9073cfbfef4)
- bump tape [`103d674`](https://github.com/inspect-js/object-inspect/commit/103d67496b504bdcfdd765d303a773f87ec106e2)
- use newer travis config [`d497276`](https://github.com/inspect-js/object-inspect/commit/d497276c1da14234bb5098a59cf20de75fbc316a)

## [1.0.0](https://github.com/inspect-js/object-inspect/compare/0.4.0...1.0.0) - 2014-08-05

### Commits

- error inspect works properly [`260a22d`](https://github.com/inspect-js/object-inspect/commit/260a22d134d3a8a482c67d52091c6040c34f4299)
- seen coverage [`57269e8`](https://github.com/inspect-js/object-inspect/commit/57269e8baa992a7439047f47325111fdcbcb8417)
- htmlelement instance coverage [`397ffe1`](https://github.com/inspect-js/object-inspect/commit/397ffe10a1980350868043ef9de65686d438979f)
- more element coverage [`6905cc2`](https://github.com/inspect-js/object-inspect/commit/6905cc2f7df35600177e613b0642b4df5efd3eca)
- failing test for type errors [`385b615`](https://github.com/inspect-js/object-inspect/commit/385b6152e49b51b68449a662f410b084ed7c601a)
- fn name coverage [`edc906d`](https://github.com/inspect-js/object-inspect/commit/edc906d40fca6b9194d304062c037ee8e398c4c2)
- server-side element test [`362d1d3`](https://github.com/inspect-js/object-inspect/commit/362d1d3e86f187651c29feeb8478110afada385b)
- custom inspect fn [`e89b0f6`](https://github.com/inspect-js/object-inspect/commit/e89b0f6fe6d5e03681282af83732a509160435a6)
- fixed browser test [`b530882`](https://github.com/inspect-js/object-inspect/commit/b5308824a1c8471c5617e394766a03a6977102a9)
- depth test, matches node [`1cfd9e0`](https://github.com/inspect-js/object-inspect/commit/1cfd9e0285a4ae1dff44101ad482915d9bf47e48)
- exercise hasOwnProperty path [`8d753fb`](https://github.com/inspect-js/object-inspect/commit/8d753fb362a534fa1106e4d80f2ee9bea06a66d9)
- more cases covered for errors [`c5c46a5`](https://github.com/inspect-js/object-inspect/commit/c5c46a569ec4606583497e8550f0d8c7ad39a4a4)
- \W obj key test case [`b0eceee`](https://github.com/inspect-js/object-inspect/commit/b0eceeea6e0eb94d686c1046e99b9e25e5005f75)
- coverage for explicit depth param [`e12b91c`](https://github.com/inspect-js/object-inspect/commit/e12b91cd59683362f3a0e80f46481a0211e26c15)

## [0.4.0](https://github.com/inspect-js/object-inspect/compare/0.3.1...0.4.0) - 2014-03-21

### Commits

- passing lowbyte interpolation test [`b847511`](https://github.com/inspect-js/object-inspect/commit/b8475114f5def7e7961c5353d48d3d8d9a520985)
- lowbyte test [`4a2b0e1`](https://github.com/inspect-js/object-inspect/commit/4a2b0e142667fc933f195472759385ac08f3946c)

## [0.3.1](https://github.com/inspect-js/object-inspect/compare/0.3.0...0.3.1) - 2014-03-04

### Commits

- sort keys [`a07b19c`](https://github.com/inspect-js/object-inspect/commit/a07b19cc3b1521a82d4fafb6368b7a9775428a05)

## [0.3.0](https://github.com/inspect-js/object-inspect/compare/0.2.0...0.3.0) - 2014-03-04

### Commits

- [] and {} instead of [ ] and { } [`654c44b`](https://github.com/inspect-js/object-inspect/commit/654c44b2865811f3519e57bb8526e0821caf5c6b)

## [0.2.0](https://github.com/inspect-js/object-inspect/compare/0.1.3...0.2.0) - 2014-03-04

### Commits

- failing holes test [`99cdfad`](https://github.com/inspect-js/object-inspect/commit/99cdfad03c6474740275a75636fe6ca86c77737a)
- regex already work [`e324033`](https://github.com/inspect-js/object-inspect/commit/e324033267025995ec97d32ed0a65737c99477a6)
- failing undef/null test [`1f88a00`](https://github.com/inspect-js/object-inspect/commit/1f88a00265d3209719dda8117b7e6360b4c20943)
- holes in the all example [`7d345f3`](https://github.com/inspect-js/object-inspect/commit/7d345f3676dcbe980cff89a4f6c243269ebbb709)
- check for .inspect(), fixes Buffer use-case [`c3f7546`](https://github.com/inspect-js/object-inspect/commit/c3f75466dbca125347d49847c05262c292f12b79)
- fixes for holes [`ce25f73`](https://github.com/inspect-js/object-inspect/commit/ce25f736683de4b92ff27dc5471218415e2d78d8)
- weird null behavior [`405c1ea`](https://github.com/inspect-js/object-inspect/commit/405c1ea72cd5a8cf3b498c3eaa903d01b9fbcab5)
- tape is actually a devDependency, upgrade [`703b0ce`](https://github.com/inspect-js/object-inspect/commit/703b0ce6c5817b4245a082564bccd877e0bb6990)
- put date in the example [`a342219`](https://github.com/inspect-js/object-inspect/commit/a3422190eeaa013215f46df2d0d37b48595ac058)
- passing the null test [`4ab737e`](https://github.com/inspect-js/object-inspect/commit/4ab737ebf862a75d247ebe51e79307a34d6380d4)

## [0.1.3](https://github.com/inspect-js/object-inspect/compare/0.1.1...0.1.3) - 2013-07-26

### Commits

- special isElement() check [`882768a`](https://github.com/inspect-js/object-inspect/commit/882768a54035d30747be9de1baf14e5aa0daa128)
- oh right old IEs don't have indexOf either [`36d1275`](https://github.com/inspect-js/object-inspect/commit/36d12756c38b08a74370b0bb696c809e529913a5)

## [0.1.1](https://github.com/inspect-js/object-inspect/compare/0.1.0...0.1.1) - 2013-07-26

### Commits

- tests! [`4422fd9`](https://github.com/inspect-js/object-inspect/commit/4422fd95532c2745aa6c4f786f35f1090be29998)
- fix for ie&lt;9, doesn't have hasOwnProperty [`6b7d611`](https://github.com/inspect-js/object-inspect/commit/6b7d61183050f6da801ea04473211da226482613)
- fix for all IEs: no f.name [`4e0c2f6`](https://github.com/inspect-js/object-inspect/commit/4e0c2f6dfd01c306d067d7163319acc97c94ee50)
- badges [`5ed0d88`](https://github.com/inspect-js/object-inspect/commit/5ed0d88e4e407f9cb327fa4a146c17921f9680f3)

## [0.1.0](https://github.com/inspect-js/object-inspect/compare/0.0.0...0.1.0) - 2013-07-26

### Commits

- [Function] for functions [`ad5c485`](https://github.com/inspect-js/object-inspect/commit/ad5c485098fc83352cb540a60b2548ca56820e0b)

## 0.0.0 - 2013-07-26

### Commits

- working browser example [`34be6b6`](https://github.com/inspect-js/object-inspect/commit/34be6b6548f9ce92bdc3c27572857ba0c4a1218d)
- package.json etc [`cad51f2`](https://github.com/inspect-js/object-inspect/commit/cad51f23fc6bcf1a456ed6abe16088256c2f632f)
- docs complete [`b80cce2`](https://github.com/inspect-js/object-inspect/commit/b80cce2490c4e7183a9ee11ea89071f0abec4446)
- circular example [`4b4a7b9`](https://github.com/inspect-js/object-inspect/commit/4b4a7b92209e4e6b4630976cb6bcd17d14165a59)
- string rep [`7afb479`](https://github.com/inspect-js/object-inspect/commit/7afb479baa798d27f09e0a178b72ea327f60f5c8)


---

1.1.1 / 2019-04-06
=================
  * [Fix] exclude deprecated Firefox keys (#53)

1.1.0 / 2019-02-10
=================
  * [New] [Refactor] move full implementation to `implementation` entry point
  * [Refactor] only evaluate the implementation if `Object.keys` is not present
  * [Tests] up to `node` `v11.8`, `v10.15`, `v8.15`, `v6.16`
  * [Tests] remove jscs
  * [Tests] switch to `npm audit` from `nsp`

1.0.12 / 2018-06-18
=================
  * [Fix] avoid accessing `window.applicationCache`, to avoid issues with latest Chrome on HTTP (#46)

1.0.11 / 2016-07-05
=================
  * [Fix] exclude keys regarding the style (eg. `pageYOffset`) on `window` to avoid reflow (#32)

1.0.10 / 2016-07-04
=================
  * [Fix] exclude `height` and `width` keys on `window` to avoid reflow (#31)
  * [Fix] In IE 6, `window.external` makes `Object.keys` throw
  * [Tests] up to `node` `v6.2`, `v5.10`, `v4.4`
  * [Tests] use pretest/posttest for linting/security
  * [Dev Deps] update `tape`, `jscs`, `nsp`, `eslint`, `@ljharb/eslint-config`
  * [Dev Deps] remove unused eccheck script + dep

1.0.9 / 2015-10-19
=================
  * [Fix] Blacklist 'frame' property on window (#16, #17)
  * [Dev Deps] update `jscs`, `eslint`, `@ljharb/eslint-config`

1.0.8 / 2015-10-14
=================
  * [Fix] wrap automation equality bug checking in try/catch, per [es5-shim#327](https://github.com/es-shims/es5-shim/issues/327)
  * [Fix] Blacklist 'window.frameElement' per [es5-shim#322](https://github.com/es-shims/es5-shim/issues/322)
  * [Docs] Switch from vb.teelaun.ch to versionbadg.es for the npm version badge SVG
  * [Tests] up to `io.js` `v3.3`, `node` `v4.2`
  * [Dev Deps] update `eslint`, `tape`, `@ljharb/eslint-config`, `jscs`

1.0.7 / 2015-07-18
=================
  * [Fix] A proper fix for 176f03335e90d5c8d0d8125a99f27819c9b9cdad / https://github.com/es-shims/es5-shim/issues/275 that doesn't break dontEnum/constructor fixes in IE 8.
  * [Fix] Remove deprecation message in Chrome by touching deprecated window properties (#15)
  * [Tests] Improve test output for automation equality bugfix
  * [Tests] Test on `io.js` `v2.4`

1.0.6 / 2015-07-09
=================
  * [Fix] Use an object lookup rather than ES5's `indexOf` (#14)
  * [Tests] ES3 browsers don't have `Array.isArray`
  * [Tests] Fix `no-shadow` rule, as well as an IE 8 bug caused by engine NFE shadowing bugs.

1.0.5 / 2015-07-03
=================
  * [Fix] Fix a flabbergasting IE 8 bug where `localStorage.constructor.prototype === localStorage` throws
  * [Tests] Test up to `io.js` `v2.3`
  * [Dev Deps] Update `nsp`, `eslint`

1.0.4 / 2015-05-23
=================
  * Fix a Safari 5.0 bug with `Object.keys` not working with `arguments`
  * Test on latest `node` and `io.js`
  * Update `jscs`, `tape`, `eslint`, `nsp`, `is`, `editorconfig-tools`, `covert`

1.0.3 / 2015-01-06
=================
  * Revert "Make `object-keys` more robust against later environment tampering" to maintain ES3 compliance

1.0.2 / 2014-12-28
=================
  * Update lots of dev dependencies
  * Tweaks to README
  * Make `object-keys` more robust against later environment tampering

1.0.1 / 2014-09-03
=================
  * Update URLs and badges in README

1.0.0 / 2014-08-26
=================
  * v1.0.0

0.6.1 / 2014-08-25
=================
  * v0.6.1
  * Updating dependencies (tape, covert, is)
  * Update badges in readme
  * Use separate var statements

0.6.0 / 2014-04-23
=================
  * v0.6.0
  * Updating dependencies (tape, covert)
  * Make sure boxed primitives, and arguments objects, work properly in ES3 browsers
  * Improve test matrix: test all node versions, but only latest two stables are a failure
  * Remove internal foreach shim.

0.5.1 / 2014-03-09
=================
  * 0.5.1
  * Updating dependencies (tape, covert, is)
  * Removing forEach from the module (but keeping it in tests)

0.5.0 / 2014-01-30
=================
  * 0.5.0
  * Explicitly returning the shim, instead of returning native Object.keys when present
  * Adding a changelog.
  * Cleaning up IIFE wrapping
  * Testing on node 0.4 through 0.11

0.4.0 / 2013-08-14
==================

  * v0.4.0
  * In Chrome 4-10 and Safari 4, typeof (new RegExp) === 'function'
  * If it's a string, make sure to use charAt instead of brackets.
  * Only use Function#call if necessary.
  * Making sure the context tests actually run.
  * Better function detection
  * Adding the android browser
  * Fixing testling files
  * Updating tape
  * Removing the "is" dependency.
  * Making an isArguments shim.
  * Adding a local forEach shim and tests.
  * Updating paths.
  * Moving the shim test.
  * v0.3.0

0.3.0 / 2013-05-18
==================

  * README tweak.
  * Fixing constructor enum issue. Fixes [#5](https://github.com/ljharb/object-keys/issues/5).
  * Adding a test for [#5](https://github.com/ljharb/object-keys/issues/5)
  * Updating readme.
  * Updating dependencies.
  * Giving credit to lodash.
  * Make sure that a prototype's constructor property is not enumerable. Fixes [#3](https://github.com/ljharb/object-keys/issues/3).
  * Adding additional tests to handle arguments objects, and to skip "prototype" in functions. Fixes [#2](https://github.com/ljharb/object-keys/issues/2).
  * Fixing a typo on this test for [#3](https://github.com/ljharb/object-keys/issues/3).
  * Adding node 0.10 to travis.
  * Adding an IE < 9 test per [#3](https://github.com/ljharb/object-keys/issues/3)
  * Adding an iOS 5 mobile Safari test per [#2](https://github.com/ljharb/object-keys/issues/2)
  * Moving "indexof" and "is" to be dev dependencies.
  * Making sure the shim works with functions.
  * Flattening the tests.

0.2.0 / 2013-05-10
==================

  * v0.2.0
  * Object.keys should work with arrays.

0.1.8 / 2013-05-10
==================

  * v0.1.8
  * Upgrading dependencies.
  * Using a simpler check.
  * Fixing a bug in hasDontEnumBug browsers.
  * Using the newest tape!
  * Fixing this error test.
  * "undefined" is probably a reserved word in ES3.
  * Better test message.

0.1.7 / 2013-04-17
==================

  * Upgrading "is" once more.
  * The key "null" is breaking some browsers.

0.1.6 / 2013-04-17
==================

  * v0.1.6
  * Upgrading "is"

0.1.5 / 2013-04-14
==================

  * Bumping version.
  * Adding more testling browsers.
  * Updating "is"

0.1.4 / 2013-04-08
==================

  * Using "is" instead of "is-extended".

0.1.3 / 2013-04-07
==================

  * Using "foreach" instead of my own shim.
  * Removing "tap"; I'll just wait for "tape" to fix its node 0.10 bug.

0.1.2 / 2013-04-03
==================

  * Adding dependency status; moving links to an index at the bottom.
  * Upgrading is-extended; version 0.1.2
  * Adding an npm version badge.

0.1.1 / 2013-04-01
==================

  * Adding Travis CI.
  * Bumping the version.
  * Adding indexOf since IE sucks.
  * Adding a forEach shim since older browsers don't have Array#forEach.
  * Upgrading tape - 0.3.2 uses Array#map
  * Using explicit end instead of plan.
  * Can't test with Array.isArray in older browsers.
  * Using is-extended.
  * Fixing testling files.
  * JSHint/JSLint-ing.
  * Removing an unused object.
  * Using strict mode.

0.1.0 / 2013-03-30
==================

  * Changing the exports should have meant a higher version bump.
  * Oops, fixing the repo URL.
  * Adding more tests.
  * 0.0.2
  * Merge branch 'export_one_thing'; closes [#1](https://github.com/ljharb/object-keys/issues/1)
  * Move shim export to a separate file.


---

#object-keys <sup>[![Version Badge][npm-version-svg]][package-url]</sup>

[![Build Status][travis-svg]][travis-url]
[![dependency status][deps-svg]][deps-url]
[![dev dependency status][dev-deps-svg]][dev-deps-url]
[![License][license-image]][license-url]
[![Downloads][downloads-image]][downloads-url]

[![npm badge][npm-badge-png]][package-url]

[![browser support][testling-svg]][testling-url]

An Object.keys shim. Invoke its "shim" method to shim Object.keys if it is unavailable.

Most common usage:
```js
var keys = Object.keys || require('object-keys');
```

## Example

```js
var keys = require('object-keys');
var assert = require('assert');
var obj = {
	a: true,
	b: true,
	c: true
};

assert.deepEqual(keys(obj), ['a', 'b', 'c']);
```

```js
var keys = require('object-keys');
var assert = require('assert');
/* when Object.keys is not present */
delete Object.keys;
var shimmedKeys = keys.shim();
assert.equal(shimmedKeys, keys);
assert.deepEqual(Object.keys(obj), keys(obj));
```

```js
var keys = require('object-keys');
var assert = require('assert');
/* when Object.keys is present */
var shimmedKeys = keys.shim();
assert.equal(shimmedKeys, Object.keys);
assert.deepEqual(Object.keys(obj), keys(obj));
```

## Source
Implementation taken directly from [es5-shim][es5-shim-url], with modifications, including from [lodash][lodash-url].

## Tests
Simply clone the repo, `npm install`, and run `npm test`

[package-url]: https://npmjs.org/package/object-keys
[npm-version-svg]: http://versionbadg.es/ljharb/object-keys.svg
[travis-svg]: https://travis-ci.org/ljharb/object-keys.svg
[travis-url]: https://travis-ci.org/ljharb/object-keys
[deps-svg]: https://david-dm.org/ljharb/object-keys.svg
[deps-url]: https://david-dm.org/ljharb/object-keys
[dev-deps-svg]: https://david-dm.org/ljharb/object-keys/dev-status.svg
[dev-deps-url]: https://david-dm.org/ljharb/object-keys#info=devDependencies
[testling-svg]: https://ci.testling.com/ljharb/object-keys.png
[testling-url]: https://ci.testling.com/ljharb/object-keys
[es5-shim-url]: https://github.com/es-shims/es5-shim/blob/master/es5-shim.js#L542-589
[lodash-url]: https://github.com/lodash/lodash
[npm-badge-png]: https://nodei.co/npm/object-keys.png?downloads=true&stars=true
[license-image]: http://img.shields.io/npm/l/object-keys.svg
[license-url]: LICENSE
[downloads-image]: http://img.shields.io/npm/dm/object-keys.svg
[downloads-url]: http://npm-stat.com/charts.html?package=object-keys



---

4.1.7 / 2024-12-18
==================
  * [Deps] add missing `es-object-atoms` (#86)

4.1.6 / 2024-12-18
==================
  * [Refactor] use `call-bound` directly; use `es-object-atoms`
  * [Deps] update `call-bind`, `has-symbols`
  * [Dev Deps] update `@es-shims/api`, `@ljharb/eslint-config`, `hasown`, `mock-property`, `ses`, `tape`
  * [actions] split out node 10-20, and 20+
  * [actions] remove redundant finisher
  * [Tests] replace `aud` with `npm audit`

4.1.5 / 2023-11-30
==================
  * [meta] republish without testing HTML file (#85)
  * [Deps] update `call-bind`, `define-properties`
  * [Dev Deps] use `hasown` instead of `has`
  * [Dev Deps] update `@es-shims/api`, `@ljharb/eslint-config`, `aud`, `npmignore`, `mock-property`, `tape`
  * [actions] update rebase action

4.1.4 / 2022-08-16
==================
  * [meta] fix `npmignore` integration (#83)

4.1.3 / 2022-08-05
==================
  * [Refactor] make steps closer to actual spec
  * [Refactor] simplify object coercible check
  * [readme] remove defunct badges, add coverage and actions badges
  * [eslint] ignore coverage output
  * [meta] use `npmignore` to autogenerate an npmignore file
  * [meta] remove audit-level
  * [Deps] update `call-bind`, `define-properties`, `has-symbols`
  * [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `@es-shims/api`, `aud`, `functions-have-names`, `safe-publish-latest`, `ses`, `tape`
  * [actions] use `node/install` instead of `node/run`; use `codecov` action
  * [actions] reuse common workflows
  * [actions] update codecov uploader
  * [Tests] add implementation tests
  * [Tests] use `mock-property`
  * [Tests] disable posttest pending `aud` handling `file:` deps
  * [Tests] migrate remaining tests to Github Actions (#81)
  * [Tests] gitignore coverage output
  * [Tests] test node v1-v9 on Github Actions instead of travis; resume testing all minors (#80)

4.1.2 / 2020-10-30
==================
  * [Refactor] use extracted `call-bind` instead of full `es-abstract`
  * [Dev Deps] update `eslint`, `ses`, `browserify`
  * [Tests] run tests in SES
  * [Tests] ses-compat: show error stacks

4.1.1 / 2020-09-11
==================
  * [Fix] avoid mutating `Object.assign` in modern engines
  * [Refactor] use `callBind` from `es-abstract` instead of `function-bind`
  * [Deps] update `has-symbols`, `object-keys`, `define-properties`
  * [meta] add `funding` field, FUNDING.yml
  * [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `@es-shims/api`, `browserify`, `covert`, `for-each`, `is`, `tape`, `functions-have-names`; add `aud`, `safe-publish-latest`; remove `jscs`
  * [actions] add Require Allow Edits workflow
  * [actions] add automatic rebasing / merge commit blocking
  * [Tests] ses-compat - add test to ensure package initializes correctly after ses lockdown (#77)
  * [Tests] Add passing test for a source of `window.location` (#68)
  * [Tests] use shared travis-ci config
  * [Tests] use `npx aud` instead of `npm audit` with hoops or `nsp`
  * [Tests] use `functions-have-names`

4.1.0 / 2017-12-21
==================
  * [New] add `auto` entry point (#52)
  * [Refactor] Use `has-symbols` module
  * [Deps] update `function-bind`, `object-keys`
  * [Dev Deps] update `@es-shims/api`, `browserify`, `nsp`, `eslint`, `@ljharb/eslint-config`, `is`
  * [Tests] up to `node` `v9.3`, `v8.9`, `v6.12`; use `nvm install-latest-npm`; pin included builds to LTS

4.0.4 / 2016-07-04
==================
  * [Fix] Cache original `getOwnPropertySymbols`, and use that when `Object.getOwnPropertySymbols` is unavailable
  * [Deps] update `object-keys`
  * [Dev Deps] update `eslint`, `get-own-property-symbols`, `core-js`, `jscs`, `nsp`, `browserify`, `@ljharb/eslint-config`, `tape`, `@es-shims/api`
  * [Tests] up to `node` `v6.2`, `v5.10`, `v4.4`
  * [Tests] run sham tests on node 0.10
  * [Tests] use pretest/posttest for linting/security

4.0.3 / 2015-10-21
==================
  * [Fix] Support core-js's Symbol sham (#17)
  * [Fix] Ensure that properties removed or made non-enumerable during enumeration are not assigned (#16)
  * [Fix] Avoid looking up keys and values more than once
  * [Tests] Avoid using `reduce` so `npm run test:shams:corejs` passes in `node` `v0.8` ([core-js#122](https://github.com/zloirock/core-js/issues/122))
  * [Tests] Refactor to use my conventional structure that separates shimmed, implementation, and common tests
  * [Tests] Create `npm run test:shams` and better organize tests for symbol shams
  * [Tests] Remove `nsp` in favor of `requiresafe`

4.0.2 / 2015-10-20
==================
  * [Fix] Ensure correct property enumeration order, particularly in v8 (#15)
  * [Deps] update `object-keys`, `define-properties`
  * [Dev Deps] update `browserify`, `is`, `tape`, `jscs`, `eslint`, `@ljharb/eslint-config`
  * [Tests] up to `io.js` `v3.3`, `node` `v4.2`

4.0.1 / 2015-08-16
==================
  * [Docs] Add `Symbol` note to readme

4.0.0 / 2015-08-15
==================
  * [Breaking] Implement the [es-shim API](es-shims/api).
  * [Robustness] Make implementation robust against later modification of environment methods.
  * [Refactor] Move implementation to `implementation.js`
  * [Docs] Switch from vb.teelaun.ch to versionbadg.es for the npm version badge SVG
  * [Deps] update `object-keys`, `define-properties`
  * [Dev Deps] update `browserify`, `tape`, `eslint`, `jscs`, `browserify`
  * [Tests] Add `npm run tests-only`
  * [Tests] use my personal shared `eslint` config.
  * [Tests] up to `io.js` `v3.0`

3.0.1 / 2015-06-28
==================
  * Cache `Object` and `Array#push` to make the shim more robust.
  * [Fix] Remove use of `Array#filter`, which isn't in ES3.
  * [Deps] Update `object-keys`, `define-properties`
  * [Dev Deps] Update `get-own-property-symbols`, `browserify`, `eslint`, `nsp`
  * [Tests] Test up to `io.js` `v2.3`
  * [Tests] Adding `Object.assign` tests for non-object targets, per https://github.com/paulmillr/es6-shim/issues/348

3.0.0 / 2015-05-20
==================
  * Attempt to feature-detect Symbols, even if `typeof Symbol() !== 'symbol'` (#12)
  * Make a separate `hasSymbols` internal module
  * Update `browserify`, `eslint`

2.0.3 / 2015-06-28
==================
  * Cache `Object` and `Array#push` to make the shim more robust.
  * [Fix] Remove use of `Array#filter`, which isn't in ES3
  * [Deps] Update `object-keys`, `define-properties`
  * [Dev Deps] Update `browserify`, `nsp`, `eslint`
  * [Tests] Test up to `io.js` `v2.3`

2.0.2 / 2015-05-20
==================
  * Make sure `.shim` is non-enumerable.
  * Refactor `.shim` implementation to use `define-properties` predicates, rather than `delete`ing the original.
  * Update docs to match spec/implementation. (#11)
  * Add `npm run eslint`
  * Test up to `io.js` `v2.0`
  * Update `jscs`, `browserify`, `covert`

2.0.1 / 2015-04-12
==================
  * Make sure non-enumerable Symbols are excluded.

2.0.0 / 2015-04-12
==================
  * Make sure the shim function overwrites a broken implementation with pending exceptions.
  * Ensure shim is not enumerable using `define-properties`
  * Ensure `Object.assign` includes symbols.
  * All grade A-supported `node`/`iojs` versions now ship with an `npm` that understands `^`.
  * Run `travis-ci` tests on `iojs` and `node` v0.12; speed up builds; allow 0.8 failures.
  * Add `npm run security` via `nsp`
  * Update `browserify`, `jscs`, `tape`, `object-keys`, `is`

1.1.1 / 2014-12-14
==================
  * Actually include the browser build in `npm`

1.1.0 / 2014-12-14
==================
  * Add `npm run build`, and build an automatic-shimming browser distribution as part of the npm publish process.
  * Update `is`, `jscs`

1.0.3 / 2014-11-29
==================
  * Revert "optimize --production installs"

1.0.2 / 2014-11-27
==================
  * Update `jscs`, `is`, `object-keys`, `tape`
  * Add badges to README
  * Name URLs in README
  * Lock `covert` to `v1.0.0`
  * Optimize --production installs

1.0.1 / 2014-08-26
==================
  * Update `is`, `covert`

1.0.0 / 2014-08-07
==================
  * Update `object-keys`, `tape`

0.5.0 / 2014-07-31
==================
  * Object.assign no longer throws on null or undefined sources, per https://bugs.ecmascript.org/show_bug.cgi?id=3096

0.4.3 / 2014-07-30
==================
  * Don’t modify vars in the function signature, since it deoptimizes v8

0.4.2 / 2014-07-30
==================
  * Fixing the version number: v0.4.2

0.4.1 / 2014-07-19
==================
  * Revert "Use the native Object.keys if it’s available."

0.4.0 / 2014-07-19
==================
  * Use the native Object.keys if it’s available.
  * Fixes [#2](https://github.com/ljharb/object.assign/issues/2).
  * Adding failing tests for [#2](https://github.com/ljharb/object.assign/issues/2).
  * Fix indentation.
  * Adding `npm run lint`
  * Update `tape`, `covert`
  * README: Use SVG badge for Travis [#1](https://github.com/ljharb/object.assign/issues/1) from mathiasbynens/patch-1

0.3.1 / 2014-04-10
==================
  * Object.assign does partially modify objects if it throws, per https://twitter.com/awbjs/status/454320863093862400

0.3.0 / 2014-04-10
==================
  * Update with newest ES6 behavior - Object.assign now takes a variable number of source objects.
  * Update `tape`
  * Make sure old and unstable nodes don’t fail Travis

0.2.1 / 2014-03-16
==================
  * Let object-keys handle the fallback
  * Update dependency badges
  * Adding bower.json

0.2.0 / 2014-03-16
==================
  * Use a for loop, because ES3 browsers don’t have "reduce"

0.1.1 / 2014-03-14
==================
  * Updating readme

0.1.0 / 2014-03-14
==================
  * Initial release.



---

# object.assign <sup>[![Version Badge][npm-version-svg]][npm-url]</sup>

[![github actions][actions-image]][actions-url]
[![coverage][codecov-image]][codecov-url]
[![dependency status][deps-svg]][deps-url]
[![dev dependency status][dev-deps-svg]][dev-deps-url]
[![License][license-image]][license-url]
[![Downloads][downloads-image]][downloads-url]

[![npm badge][npm-badge-png]][npm-url]

An Object.assign shim. Invoke its "shim" method to shim Object.assign if it is unavailable.

This package implements the [es-shim API](https://github.com/es-shims/api) interface. It works in an ES3-supported environment and complies with the [spec](http://www.ecma-international.org/ecma-262/6.0/#sec-object.assign). In an ES6 environment, it will also work properly with `Symbol`s.

Takes a minimum of 2 arguments: `target` and `source`.
Takes a variable sized list of source arguments - at least 1, as many as you want.
Throws a TypeError if the `target` argument is `null` or `undefined`.

Most common usage:
```js
var assign = require('object.assign').getPolyfill(); // returns native method if compliant
	/* or */
var assign = require('object.assign/polyfill')(); // returns native method if compliant
```

## Example

```js
var assert = require('assert');

// Multiple sources!
var target = { a: true };
var source1 = { b: true };
var source2 = { c: true };
var sourceN = { n: true };

var expected = {
	a: true,
	b: true,
	c: true,
	n: true
};

assign(target, source1, source2, sourceN);
assert.deepEqual(target, expected); // AWESOME!
```

```js
var target = {
	a: true,
	b: true,
	c: true
};
var source1 = {
	c: false,
	d: false
};
var sourceN = {
	e: false
};

var assigned = assign(target, source1, sourceN);
assert.equal(target, assigned); // returns the target object
assert.deepEqual(assigned, {
	a: true,
	b: true,
	c: false,
	d: false,
	e: false
});
```

```js
/* when Object.assign is not present */
delete Object.assign;
var shimmedAssign = require('object.assign').shim();
	/* or */
var shimmedAssign = require('object.assign/shim')();

assert.equal(shimmedAssign, assign);

var target = {
	a: true,
	b: true,
	c: true
};
var source = {
	c: false,
	d: false,
	e: false
};

var assigned = assign(target, source);
assert.deepEqual(Object.assign(target, source), assign(target, source));
```

```js
/* when Object.assign is present */
var shimmedAssign = require('object.assign').shim();
assert.equal(shimmedAssign, Object.assign);

var target = {
	a: true,
	b: true,
	c: true
};
var source = {
	c: false,
	d: false,
	e: false
};

assert.deepEqual(Object.assign(target, source), assign(target, source));
```

## Tests
Simply clone the repo, `npm install`, and run `npm test`

[npm-url]: https://npmjs.org/package/object.assign
[npm-version-svg]: http://versionbadg.es/ljharb/object.assign.svg
[travis-svg]: https://travis-ci.org/ljharb/object.assign.svg
[travis-url]: https://travis-ci.org/ljharb/object.assign
[deps-svg]: https://david-dm.org/ljharb/object.assign.svg?theme=shields.io
[deps-url]: https://david-dm.org/ljharb/object.assign
[dev-deps-svg]: https://david-dm.org/ljharb/object.assign/dev-status.svg?theme=shields.io
[dev-deps-url]: https://david-dm.org/ljharb/object.assign#info=devDependencies
[npm-badge-png]: https://nodei.co/npm/object.assign.png?downloads=true&stars=true
[license-image]: http://img.shields.io/npm/l/object.assign.svg
[license-url]: LICENSE
[downloads-image]: http://img.shields.io/npm/dm/object.assign.svg
[downloads-url]: http://npm-stat.com/charts.html?package=object.assign
[codecov-image]: https://codecov.io/gh/ljharb/object.assign/branch/main/graphs/badge.svg
[codecov-url]: https://app.codecov.io/gh/ljharb/object.assign/
[actions-image]: https://img.shields.io/endpoint?url=https://github-actions-badge-u3jn4tfpocch.runkit.sh/ljharb/object.assign
[actions-url]: https://github.com/ljharb/object.assign/actions


---

# obuf - Offset buffer implementation.

Byte buffer specialized for data in chunks with special cases for dropping
bytes in the front, merging bytes in to various integer types and
abandoning buffer without penalty for previous chunk merges.

Used in spyd-transport, part of spdy support for http2.

This software is licensed under the MIT License.

By Fedor Indutny, 2015.



---

2.4.1 / 2022-02-22
==================

  * Fix error on early async hooks implementations

2.4.0 / 2022-02-21
==================

  * Prevent loss of async hooks context

2.3.0 / 2015-05-26
==================

  * Add defined behavior for HTTP `CONNECT` requests
  * Add defined behavior for HTTP `Upgrade` requests
  * deps: ee-first@1.1.1

2.2.1 / 2015-04-22
==================

  * Fix `isFinished(req)` when data buffered

2.2.0 / 2014-12-22
==================

  * Add message object to callback arguments

2.1.1 / 2014-10-22
==================

  * Fix handling of pipelined requests

2.1.0 / 2014-08-16
==================

  * Check if `socket` is detached
  * Return `undefined` for `isFinished` if state unknown

2.0.0 / 2014-08-16
==================

  * Add `isFinished` function
  * Move to `jshttp` organization
  * Remove support for plain socket argument
  * Rename to `on-finished`
  * Support both `req` and `res` as arguments
  * deps: ee-first@1.0.5

1.2.2 / 2014-06-10
==================

  * Reduce listeners added to emitters
    - avoids "event emitter leak" warnings when used multiple times on same request

1.2.1 / 2014-06-08
==================

  * Fix returned value when already finished

1.2.0 / 2014-06-05
==================

  * Call callback when called on already-finished socket

1.1.4 / 2014-05-27
==================

  * Support node.js 0.8

1.1.3 / 2014-04-30
==================

  * Make sure errors passed as instanceof `Error`

1.1.2 / 2014-04-18
==================

  * Default the `socket` to passed-in object

1.1.1 / 2014-01-16
==================

  * Rename module to `finished`

1.1.0 / 2013-12-25
==================

  * Call callback when called on already-errored socket

1.0.1 / 2013-12-20
==================

  * Actually pass the error to the callback

1.0.0 / 2013-12-20
==================

  * Initial release


---

# on-finished

[![NPM Version][npm-version-image]][npm-url]
[![NPM Downloads][npm-downloads-image]][npm-url]
[![Node.js Version][node-image]][node-url]
[![Build Status][ci-image]][ci-url]
[![Coverage Status][coveralls-image]][coveralls-url]

Execute a callback when a HTTP request closes, finishes, or errors.

## Install

This is a [Node.js](https://nodejs.org/en/) module available through the
[npm registry](https://www.npmjs.com/). Installation is done using the
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):

```sh
$ npm install on-finished
```

## API

```js
var onFinished = require('on-finished')
```

### onFinished(res, listener)

Attach a listener to listen for the response to finish. The listener will
be invoked only once when the response finished. If the response finished
to an error, the first argument will contain the error. If the response
has already finished, the listener will be invoked.

Listening to the end of a response would be used to close things associated
with the response, like open files.

Listener is invoked as `listener(err, res)`.

<!-- eslint-disable handle-callback-err -->

```js
onFinished(res, function (err, res) {
  // clean up open fds, etc.
  // err contains the error if request error'd
})
```

### onFinished(req, listener)

Attach a listener to listen for the request to finish. The listener will
be invoked only once when the request finished. If the request finished
to an error, the first argument will contain the error. If the request
has already finished, the listener will be invoked.

Listening to the end of a request would be used to know when to continue
after reading the data.

Listener is invoked as `listener(err, req)`.

<!-- eslint-disable handle-callback-err -->

```js
var data = ''

req.setEncoding('utf8')
req.on('data', function (str) {
  data += str
})

onFinished(req, function (err, req) {
  // data is read unless there is err
})
```

### onFinished.isFinished(res)

Determine if `res` is already finished. This would be useful to check and
not even start certain operations if the response has already finished.

### onFinished.isFinished(req)

Determine if `req` is already finished. This would be useful to check and
not even start certain operations if the request has already finished.

## Special Node.js requests

### HTTP CONNECT method

The meaning of the `CONNECT` method from RFC 7231, section 4.3.6:

> The CONNECT method requests that the recipient establish a tunnel to
> the destination origin server identified by the request-target and,
> if successful, thereafter restrict its behavior to blind forwarding
> of packets, in both directions, until the tunnel is closed.  Tunnels
> are commonly used to create an end-to-end virtual connection, through
> one or more proxies, which can then be secured using TLS (Transport
> Layer Security, [RFC5246]).

In Node.js, these request objects come from the `'connect'` event on
the HTTP server.

When this module is used on a HTTP `CONNECT` request, the request is
considered "finished" immediately, **due to limitations in the Node.js
interface**. This means if the `CONNECT` request contains a request entity,
the request will be considered "finished" even before it has been read.

There is no such thing as a response object to a `CONNECT` request in
Node.js, so there is no support for one.

### HTTP Upgrade request

The meaning of the `Upgrade` header from RFC 7230, section 6.1:

> The "Upgrade" header field is intended to provide a simple mechanism
> for transitioning from HTTP/1.1 to some other protocol on the same
> connection.

In Node.js, these request objects come from the `'upgrade'` event on
the HTTP server.

When this module is used on a HTTP request with an `Upgrade` header, the
request is considered "finished" immediately, **due to limitations in the
Node.js interface**. This means if the `Upgrade` request contains a request
entity, the request will be considered "finished" even before it has been
read.

There is no such thing as a response object to a `Upgrade` request in
Node.js, so there is no support for one.

## Example

The following code ensures that file descriptors are always closed
once the response finishes.

```js
var destroy = require('destroy')
var fs = require('fs')
var http = require('http')
var onFinished = require('on-finished')

http.createServer(function onRequest (req, res) {
  var stream = fs.createReadStream('package.json')
  stream.pipe(res)
  onFinished(res, function () {
    destroy(stream)
  })
})
```

## License

[MIT](LICENSE)

[ci-image]: https://badgen.net/github/checks/jshttp/on-finished/master?label=ci
[ci-url]: https://github.com/jshttp/on-finished/actions/workflows/ci.yml
[coveralls-image]: https://badgen.net/coveralls/c/github/jshttp/on-finished/master
[coveralls-url]: https://coveralls.io/r/jshttp/on-finished?branch=master
[node-image]: https://badgen.net/npm/node/on-finished
[node-url]: https://nodejs.org/en/download
[npm-downloads-image]: https://badgen.net/npm/dm/on-finished
[npm-url]: https://npmjs.org/package/on-finished
[npm-version-image]: https://badgen.net/npm/v/on-finished


---

1.0.2 / 2019-02-21
==================

  * Fix `res.writeHead` patch missing return value

1.0.1 / 2015-09-29
==================

  * perf: enable strict mode

1.0.0 / 2014-08-10
==================

  * Honor `res.statusCode` change in `listener`
  * Move to `jshttp` organization
  * Prevent `arguments`-related de-opt

0.0.0 / 2014-05-13
==================

  * Initial implementation


---

# on-headers

[![NPM Version][npm-version-image]][npm-url]
[![NPM Downloads][npm-downloads-image]][npm-url]
[![Node.js Version][node-version-image]][node-version-url]
[![Build Status][travis-image]][travis-url]
[![Test Coverage][coveralls-image]][coveralls-url]

Execute a listener when a response is about to write headers.

## Installation

This is a [Node.js](https://nodejs.org/en/) module available through the
[npm registry](https://www.npmjs.com/). Installation is done using the
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):

```sh
$ npm install on-headers
```

## API

<!-- eslint-disable no-unused-vars -->

```js
var onHeaders = require('on-headers')
```

### onHeaders(res, listener)

This will add the listener `listener` to fire when headers are emitted for `res`.
The listener is passed the `response` object as it's context (`this`). Headers are
considered to be emitted only once, right before they are sent to the client.

When this is called multiple times on the same `res`, the `listener`s are fired
in the reverse order they were added.

## Examples

```js
var http = require('http')
var onHeaders = require('on-headers')

http
  .createServer(onRequest)
  .listen(3000)

function addPoweredBy () {
  // set if not set by end of request
  if (!this.getHeader('X-Powered-By')) {
    this.setHeader('X-Powered-By', 'Node.js')
  }
}

function onRequest (req, res) {
  onHeaders(res, addPoweredBy)

  res.setHeader('Content-Type', 'text/plain')
  res.end('hello!')
}
```

## Testing

```sh
$ npm test
```

## License

[MIT](LICENSE)

[coveralls-image]: https://badgen.net/coveralls/c/github/jshttp/on-headers/master
[coveralls-url]: https://coveralls.io/r/jshttp/on-headers?branch=master
[node-version-image]: https://badgen.net/npm/node/on-headers
[node-version-url]: https://nodejs.org/en/download
[npm-downloads-image]: https://badgen.net/npm/dm/on-headers
[npm-url]: https://npmjs.org/package/on-headers
[npm-version-image]: https://badgen.net/npm/v/on-headers
[travis-image]: https://badgen.net/travis/jshttp/on-headers/master
[travis-url]: https://travis-ci.org/jshttp/on-headers


---

# once

Only call a function once.

## usage

```javascript
var once = require('once')

function load (file, cb) {
  cb = once(cb)
  loader.load('file')
  loader.once('load', cb)
  loader.once('error', cb)
}
```

Or add to the Function.prototype in a responsible way:

```javascript
// only has to be done once
require('once').proto()

function load (file, cb) {
  cb = cb.once()
  loader.load('file')
  loader.once('load', cb)
  loader.once('error', cb)
}
```

Ironically, the prototype feature makes this module twice as
complicated as necessary.

To check whether you function has been called, use `fn.called`. Once the
function is called for the first time the return value of the original
function is saved in `fn.value` and subsequent calls will continue to
return this value.

```javascript
var once = require('once')

function load (cb) {
  cb = once(cb)
  var stream = createStream()
  stream.once('data', cb)
  stream.once('end', function () {
    if (!cb.called) cb(new Error('not found'))
  })
}
```

## `once.strict(func)`

Throw an error if the function is called twice.

Some functions are expected to be called only once. Using `once` for them would
potentially hide logical errors.

In the example below, the `greet` function has to call the callback only once:

```javascript
function greet (name, cb) {
  // return is missing from the if statement
  // when no name is passed, the callback is called twice
  if (!name) cb('Hello anonymous')
  cb('Hello ' + name)
}

function log (msg) {
  console.log(msg)
}

// this will print 'Hello anonymous' but the logical error will be missed
greet(null, once(msg))

// once.strict will print 'Hello anonymous' and throw an error when the callback will be called the second time
greet(null, once.strict(msg))
```


---

# onetime [![Build Status](https://travis-ci.com/sindresorhus/onetime.svg?branch=master)](https://travis-ci.com/github/sindresorhus/onetime)

> Ensure a function is only called once

When called multiple times it will return the return value from the first call.

*Unlike the module [once](https://github.com/isaacs/once), this one isn't naughty and extending `Function.prototype`.*

## Install

```
$ npm install onetime
```

## Usage

```js
const onetime = require('onetime');

let i = 0;

const foo = onetime(() => ++i);

foo(); //=> 1
foo(); //=> 1
foo(); //=> 1

onetime.callCount(foo); //=> 3
```

```js
const onetime = require('onetime');

const foo = onetime(() => {}, {throw: true});

foo();

foo();
//=> Error: Function `foo` can only be called once
```

## API

### onetime(fn, options?)

Returns a function that only calls `fn` once.

#### fn

Type: `Function`

Function that should only be called once.

#### options

Type: `object`

##### throw

Type: `boolean`\
Default: `false`

Throw an error when called more than once.

### onetime.callCount(fn)

Returns a number representing how many times `fn` has been called.

Note: It throws an error if you pass in a function that is not wrapped by `onetime`.

```js
const onetime = require('onetime');

const foo = onetime(() => {});

foo();
foo();
foo();

console.log(onetime.callCount(foo));
//=> 3
```

#### fn

Type: `Function`

Function to get call count from.

## onetime for enterprise

Available as part of the Tidelift Subscription.

The maintainers of onetime and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-onetime?utm_source=npm-onetime&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)


---

# open

> Open stuff like URLs, files, executables. Cross-platform.

This is meant to be used in command-line tools and scripts, not in the browser.

If you need this for Electron, use [`shell.openPath()`](https://www.electronjs.org/docs/api/shell#shellopenpathpath) instead.

This package does not make any security guarantees. If you pass in untrusted input, it's up to you to properly sanitize it.

#### Why?

- Actively maintained.
- Supports app arguments.
- Safer as it uses `spawn` instead of `exec`.
- Fixes most of the original `node-open` issues.
- Includes the latest [`xdg-open` script](https://gitlab.freedesktop.org/xdg/xdg-utils/-/blob/master/scripts/xdg-open.in) for Linux.
- Supports WSL paths to Windows apps.

## Install

```sh
npm install open
```

## Usage

```js
const open = require('open');

// Opens the image in the default image viewer and waits for the opened app to quit.
await open('unicorn.png', {wait: true});
console.log('The image viewer app quit');

// Opens the URL in the default browser.
await open('https://sindresorhus.com');

// Opens the URL in a specified browser.
await open('https://sindresorhus.com', {app: {name: 'firefox'}});

// Specify app arguments.
await open('https://sindresorhus.com', {app: {name: 'google chrome', arguments: ['--incognito']}});

// Open an app
await open.openApp('xcode');

// Open an app with arguments
await open.openApp(open.apps.chrome, {arguments: ['--incognito']});
```

## API

It uses the command `open` on macOS, `start` on Windows and `xdg-open` on other platforms.

### open(target, options?)

Returns a promise for the [spawned child process](https://nodejs.org/api/child_process.html#child_process_class_childprocess). You would normally not need to use this for anything, but it can be useful if you'd like to attach custom event listeners or perform other operations directly on the spawned process.

#### target

Type: `string`

The thing you want to open. Can be a URL, file, or executable.

Opens in the default app for the file type. For example, URLs opens in your default browser.

#### options

Type: `object`

##### wait

Type: `boolean`\
Default: `false`

Wait for the opened app to exit before fulfilling the promise. If `false` it's fulfilled immediately when opening the app.

Note that it waits for the app to exit, not just for the window to close.

On Windows, you have to explicitly specify an app for it to be able to wait.

##### background <sup>(macOS only)</sup>

Type: `boolean`\
Default: `false`

Do not bring the app to the foreground.

##### newInstance <sup>(macOS only)</sup>

Type: `boolean`\
Default: `false`

Open a new instance of the app even it's already running.

A new instance is always opened on other platforms.

##### app

Type: `{name: string | string[], arguments?: string[]} | Array<{name: string | string[], arguments: string[]}>`

Specify the `name` of the app to open the `target` with, and optionally, app `arguments`. `app` can be an array of apps to try to open and `name` can be an array of app names to try. If each app fails, the last error will be thrown.

The app name is platform dependent. Don't hard code it in reusable modules. For example, Chrome is `google chrome` on macOS, `google-chrome` on Linux and `chrome` on Windows. If possible, use [`open.apps`](#openapps) which auto-detects the correct binary to use.

You may also pass in the app's full path. For example on WSL, this can be `/mnt/c/Program Files (x86)/Google/Chrome/Application/chrome.exe` for the Windows installation of Chrome.

The app `arguments` are app dependent. Check the app's documentation for what arguments it accepts.

##### allowNonzeroExitCode

Type: `boolean`\
Default: `false`

Allow the opened app to exit with nonzero exit code when the `wait` option is `true`.

We do not recommend setting this option. The convention for success is exit code zero.

### open.apps

An object containing auto-detected binary names for common apps. Useful to work around [cross-platform differences](#app).

```js
const open = require('open');

await open('https://google.com', {
	app: {
		name: open.apps.chrome
	}
});
```

#### Supported apps

- [`chrome`](https://www.google.com/chrome) - Web browser
- [`firefox`](https://www.mozilla.org/firefox) - Web browser
- [`edge`](https://www.microsoft.com/edge) - Web browser

### open.openApp(name, options?)

Open an app.

Returns a promise for the [spawned child process](https://nodejs.org/api/child_process.html#child_process_class_childprocess). You would normally not need to use this for anything, but it can be useful if you'd like to attach custom event listeners or perform other operations directly on the spawned process.

#### name

Type: `string`

The app name is platform dependent. Don't hard code it in reusable modules. For example, Chrome is `google chrome` on macOS, `google-chrome` on Linux and `chrome` on Windows. If possible, use [`open.apps`](#openapps) which auto-detects the correct binary to use.

You may also pass in the app's full path. For example on WSL, this can be `/mnt/c/Program Files (x86)/Google/Chrome/Application/chrome.exe` for the Windows installation of Chrome.

#### options

Type: `object`

Same options as [`open`](#options) except `app` and with the following additions:

##### arguments

Type: `string[]`\
Default: `[]`

Arguments passed to the app.

These arguments are app dependent. Check the app's documentation for what arguments it accepts.

## Related

- [open-cli](https://github.com/sindresorhus/open-cli) - CLI for this module
- [open-editor](https://github.com/sindresorhus/open-editor) - Open files in your editor at a specific line and column


---

# It Opens Stuff

That is, in your desktop environment. This will make *actual windows pop up*, with stuff in them:

```bash
npm install opener -g

opener http://google.com
opener ./my-file.txt
opener firefox
opener npm run lint
```

Also if you want to use it programmatically you can do that too:

```js
var opener = require("opener");

opener("http://google.com");
opener("./my-file.txt");
opener("firefox");
opener("npm run lint");
```

Plus, it returns the child process created, so you can do things like let your script exit while the window stays open:

```js
var editor = opener("documentation.odt");
editor.unref();
// These other unrefs may be necessary if your OS's opener process
// exits before the process it started is complete.
editor.stdin.unref();
editor.stdout.unref();
editor.stderr.unref();
```

## Use It for Good

Like opening the user's browser with a test harness in your package's test script:

```json
{
    "scripts": {
        "test": "opener ./test/runner.html"
    },
    "devDependencies": {
        "opener": "*"
    }
}
```

## Why

Because Windows has `start`, Macs have `open`, and *nix has `xdg-open`. At least [according to some person on StackOverflow](http://stackoverflow.com/q/1480971/3191). And I like things that work on all three. Like Node.js. And Opener.


---

# p-cancelable

> Create a promise that can be canceled

Useful for animation, loading resources, long-running async computations, async iteration, etc.

*If you target [Node.js 15](https://medium.com/@nodejs/node-js-v15-0-0-is-here-deb00750f278) or later, this package is [less useful](https://github.com/sindresorhus/p-cancelable/issues/27) and you should probably use [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) instead.*

## Install

```
$ npm install p-cancelable
```

## Usage

```js
import PCancelable from 'p-cancelable';

const cancelablePromise = new PCancelable((resolve, reject, onCancel) => {
	const worker = new SomeLongRunningOperation();

	onCancel(() => {
		worker.close();
	});

	worker.on('finish', resolve);
	worker.on('error', reject);
});

// Cancel the operation after 10 seconds
setTimeout(() => {
	cancelablePromise.cancel('Unicorn has changed its color');
}, 10000);

try {
	console.log('Operation finished successfully:', await cancelablePromise);
} catch (error) {
	if (cancelablePromise.isCanceled) {
		// Handle the cancelation here
		console.log('Operation was canceled');
		return;
	}

	throw error;
}
```

## API

### new PCancelable(executor)

Same as the [`Promise` constructor](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise), but with an appended `onCancel` parameter in `executor`.

Cancelling will reject the promise with `CancelError`. To avoid that, set `onCancel.shouldReject` to `false`.

```js
import PCancelable from 'p-cancelable';

const cancelablePromise = new PCancelable((resolve, reject, onCancel) => {
	const job = new Job();

	onCancel.shouldReject = false;
	onCancel(() => {
		job.stop();
	});

	job.on('finish', resolve);
});

cancelablePromise.cancel(); // Doesn't throw an error
```

`PCancelable` is a subclass of `Promise`.

#### onCanceled(fn)

Type: `Function`

Accepts a function that is called when the promise is canceled.

You're not required to call this function. You can call this function multiple times to add multiple cancel handlers.

### PCancelable#cancel(reason?)

Type: `Function`

Cancel the promise and optionally provide a reason.

The cancellation is synchronous. Calling it after the promise has settled or multiple times does nothing.

### PCancelable#isCanceled

Type: `boolean`

Whether the promise is canceled.

### PCancelable.fn(fn)

Convenience method to make your promise-returning or async function cancelable.

The function you specify will have `onCancel` appended to its parameters.

```js
import PCancelable from 'p-cancelable';

const fn = PCancelable.fn((input, onCancel) => {
	const job = new Job();

	onCancel(() => {
		job.cleanup();
	});

	return job.start(); //=> Promise
});

const cancelablePromise = fn('input'); //=> PCancelable

// …

cancelablePromise.cancel();
```

### CancelError

Type: `Error`

Rejection reason when `.cancel()` is called.

It includes a `.isCanceled` property for convenience.

## FAQ

### Cancelable vs. Cancellable

[In American English, the verb cancel is usually inflected canceled and canceling—with one l.](http://grammarist.com/spelling/cancel/) Both a [browser API](https://developer.mozilla.org/en-US/docs/Web/API/Event/cancelable) and the [Cancelable Promises proposal](https://github.com/tc39/proposal-cancelable-promises) use this spelling.

### What about the official [Cancelable Promises proposal](https://github.com/tc39/proposal-cancelable-promises)?

~~It's still an early draft and I don't really like its current direction. It complicates everything and will require deep changes in the ecosystem to adapt to it. And the way you have to use cancel tokens is verbose and convoluted. I much prefer the more pragmatic and less invasive approach in this module.~~ The proposal was withdrawn.

## p-cancelable for enterprise

Available as part of the Tidelift Subscription.

The maintainers of p-cancelable and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-p-cancelable?utm_source=npm-p-cancelable&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)

## Related

- [p-progress](https://github.com/sindresorhus/p-progress) - Create a promise that reports progress
- [p-lazy](https://github.com/sindresorhus/p-lazy) - Create a lazy promise that defers execution until `.then()` or `.catch()` is called
- [More…](https://github.com/sindresorhus/promise-fun)


---

# p-limit

> Run multiple promise-returning & async functions with limited concurrency

## Install

```
$ npm install p-limit
```

## Usage

```js
import pLimit from 'p-limit';

const limit = pLimit(1);

const input = [
	limit(() => fetchSomething('foo')),
	limit(() => fetchSomething('bar')),
	limit(() => doSomething())
];

// Only one promise is run at once
const result = await Promise.all(input);
console.log(result);
```

## API

### pLimit(concurrency)

Returns a `limit` function.

#### concurrency

Type: `number`\
Minimum: `1`\
Default: `Infinity`

Concurrency limit.

### limit(fn, ...args)

Returns the promise returned by calling `fn(...args)`.

#### fn

Type: `Function`

Promise-returning/async function.

#### args

Any arguments to pass through to `fn`.

Support for passing arguments on to the `fn` is provided in order to be able to avoid creating unnecessary closures. You probably don't need this optimization unless you're pushing a *lot* of functions.

### limit.activeCount

The number of promises that are currently running.

### limit.pendingCount

The number of promises that are waiting to run (i.e. their internal `fn` was not called yet).

### limit.clearQueue()

Discard pending promises that are waiting to run.

This might be useful if you want to teardown the queue at the end of your program's lifecycle or discard any function calls referencing an intermediary state of your app.

Note: This does not cancel promises that are already running.

## FAQ

### How is this different from the [`p-queue`](https://github.com/sindresorhus/p-queue) package?

This package is only about limiting the number of concurrent executions, while `p-queue` is a fully featured queue implementation with lots of different options, introspection, and ability to pause the queue.

## Related

- [p-queue](https://github.com/sindresorhus/p-queue) - Promise queue with concurrency control
- [p-throttle](https://github.com/sindresorhus/p-throttle) - Throttle promise-returning & async functions
- [p-debounce](https://github.com/sindresorhus/p-debounce) - Debounce promise-returning & async functions
- [p-all](https://github.com/sindresorhus/p-all) - Run promise-returning & async functions concurrently with optional limited concurrency
- [More…](https://github.com/sindresorhus/promise-fun)

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-p-limit?utm_source=npm-p-limit&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

# p-locate

> Get the first fulfilled promise that satisfies the provided testing function

Think of it like an async version of [`Array#find`](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Array/find).

## Install

```
$ npm install p-locate
```

## Usage

Here we find the first file that exists on disk, in array order.

```js
import {pathExists} from 'path-exists';
import pLocate from 'p-locate';

const files = [
	'unicorn.png',
	'rainbow.png', // Only this one actually exists on disk
	'pony.png'
];

const foundPath = await pLocate(files, file => pathExists(file));

console.log(foundPath);
//=> 'rainbow'
```

*The above is just an example. Use [`locate-path`](https://github.com/sindresorhus/locate-path) if you need this.*

## API

### pLocate(input, tester, options?)

Returns a `Promise` that is fulfilled when `tester` resolves to `true` or the iterable is done, or rejects if any of the promises reject. The fulfilled value is the current iterable value or `undefined` if `tester` never resolved to `true`.

#### input

Type: `Iterable<Promise | unknown>`

An iterable of promises/values to test.

#### tester(element)

Type: `Function`

This function will receive resolved values from `input` and is expected to return a `Promise<boolean>` or `boolean`.

#### options

Type: `object`

##### concurrency

Type: `number`\
Default: `Infinity`\
Minimum: `1`

The number of concurrently pending promises returned by `tester`.

##### preserveOrder

Type: `boolean`\
Default: `true`

Preserve `input` order when searching.

Disable this to improve performance if you don't care about the order.

## Related

- [p-map](https://github.com/sindresorhus/p-map) - Map over promises concurrently
- [p-filter](https://github.com/sindresorhus/p-filter) - Filter promises concurrently
- [p-any](https://github.com/sindresorhus/p-any) - Wait for any promise to be fulfilled
- [More…](https://github.com/sindresorhus/promise-fun)

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-p-locate?utm_source=npm-p-locate&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

# p-map [![Build Status](https://travis-ci.org/sindresorhus/p-map.svg?branch=master)](https://travis-ci.org/sindresorhus/p-map)

> Map over promises concurrently

Useful when you need to run promise-returning & async functions multiple times with different inputs concurrently.

## Install

```
$ npm install p-map
```

## Usage

```js
const pMap = require('p-map');
const got = require('got');

const sites = [
	getWebsiteFromUsername('https://sindresorhus'), //=> Promise
	'https://ava.li',
	'https://github.com'
];

(async () => {
	const mapper = async site => {
		const {requestUrl} = await got.head(site);
		return requestUrl;
	};

 	const result = await pMap(sites, mapper, {concurrency: 2});

	console.log(result);
	//=> ['https://sindresorhus.com/', 'https://ava.li/', 'https://github.com/']
})();
```

## API

### pMap(input, mapper, options?)

Returns a `Promise` that is fulfilled when all promises in `input` and ones returned from `mapper` are fulfilled, or rejects if any of the promises reject. The fulfilled value is an `Array` of the fulfilled values returned from `mapper` in `input` order.

#### input

Type: `Iterable<Promise | unknown>`

Iterated over concurrently in the `mapper` function.

#### mapper(element, index)

Type: `Function`

Expected to return a `Promise` or value.

#### options

Type: `object`

##### concurrency

Type: `number` (Integer)\
Default: `Infinity`\
Minimum: `1`

Number of concurrently pending promises returned by `mapper`.

##### stopOnError

Type: `boolean`\
Default: `true`

When set to `false`, instead of stopping when a promise rejects, it will wait for all the promises to settle and then reject with an [aggregated error](https://github.com/sindresorhus/aggregate-error) containing all the errors from the rejected promises.

## p-map for enterprise

Available as part of the Tidelift Subscription.

The maintainers of p-map and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-p-map?utm_source=npm-p-map&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)

## Related

- [p-all](https://github.com/sindresorhus/p-all) - Run promise-returning & async functions concurrently with optional limited concurrency
- [p-filter](https://github.com/sindresorhus/p-filter) - Filter promises concurrently
- [p-times](https://github.com/sindresorhus/p-times) - Run promise-returning & async functions a specific number of times concurrently
- [p-props](https://github.com/sindresorhus/p-props) - Like `Promise.all()` but for `Map` and `Object`
- [p-map-series](https://github.com/sindresorhus/p-map-series) - Map over promises serially
- [p-queue](https://github.com/sindresorhus/p-queue) - Promise queue with concurrency control
- [More…](https://github.com/sindresorhus/promise-fun)


---

# p-retry

> Retry a promise-returning or async function

It does exponential backoff and supports custom retry strategies for failed operations.

## Install

```
$ npm install p-retry
```

## Usage

```js
const pRetry = require('p-retry');
const fetch = require('node-fetch');

const run = async () => {
	const response = await fetch('https://sindresorhus.com/unicorn');

	// Abort retrying if the resource doesn't exist
	if (response.status === 404) {
		throw new pRetry.AbortError(response.statusText);
	}

	return response.blob();
};

(async () => {
	console.log(await pRetry(run, {retries: 5}));
})();
```

## API

### pRetry(input, options?)

Returns a `Promise` that is fulfilled when calling `input` returns a fulfilled promise. If calling `input` returns a rejected promise, `input` is called again until the maximum number of retries is reached. It then rejects with the last rejection reason.


Does not retry on most `TypeErrors`, with the exception of network errors. This is done on a best case basis as different browsers have different [messages](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch#Checking_that_the_fetch_was_successful) to indicate this. See [whatwg/fetch#526 (comment)](https://github.com/whatwg/fetch/issues/526#issuecomment-554604080)


#### input

Type: `Function`

Receives the current attempt number as the first argument and is expected to return a `Promise` or any value.

#### options

Type: `object`

Options are passed to the [`retry`](https://github.com/tim-kos/node-retry#retryoperationoptions) module.

##### onFailedAttempt(error)

Type: `Function`

Callback invoked on each retry. Receives the error thrown by `input` as the first argument with properties `attemptNumber` and `retriesLeft` which indicate the current attempt number and the number of attempts left, respectively.

```js
const run = async () => {
	const response = await fetch('https://sindresorhus.com/unicorn');

	if (!response.ok) {
		throw new Error(response.statusText);
	}

	return response.json();
};

(async () => {
	const result = await pRetry(run, {
		onFailedAttempt: error => {
			console.log(`Attempt ${error.attemptNumber} failed. There are ${error.retriesLeft} retries left.`);
			// 1st request => Attempt 1 failed. There are 4 retries left.
			// 2nd request => Attempt 2 failed. There are 3 retries left.
			// …
		},
		retries: 5
	});

	console.log(result);
})();
```

The `onFailedAttempt` function can return a promise. For example, you can do some async logging:

```js
const pRetry = require('p-retry');
const logger = require('./some-logger');

const run = async () => { … };

(async () => {
	const result = await pRetry(run, {
		onFailedAttempt: async error => {
			await logger.log(error);
		}
	});
})();
```

If the `onFailedAttempt` function throws, all retries will be aborted and the original promise will reject with the thrown error.

### pRetry.AbortError(message)
### pRetry.AbortError(error)

Abort retrying and reject the promise.

### message

Type: `string`

Error message.

### error

Type: `Error`

Custom error.

## Tip

You can pass arguments to the function being retried by wrapping it in an inline arrow function:

```js
const pRetry = require('p-retry');

const run = async emoji => {
	// …
};

(async () => {
	// Without arguments
	await pRetry(run, {retries: 5});

	// With arguments
	await pRetry(() => run('🦄'), {retries: 5});
})();
```

## Related

- [p-timeout](https://github.com/sindresorhus/p-timeout) - Timeout a promise after a specified amount of time
- [More…](https://github.com/sindresorhus/promise-fun)


---

# p-try [![Build Status](https://travis-ci.org/sindresorhus/p-try.svg?branch=master)](https://travis-ci.org/sindresorhus/p-try)

> Start a promise chain

[How is it useful?](http://cryto.net/~joepie91/blog/2016/05/11/what-is-promise-try-and-why-does-it-matter/)


## Install

```
$ npm install p-try
```


## Usage

```js
const pTry = require('p-try');

(async () => {
	try {
		const value = await pTry(() => {
			return synchronousFunctionThatMightThrow();
		});
		console.log(value);
	} catch (error) {
		console.error(error);
	}
})();
```


## API

### pTry(fn, ...arguments)

Returns a `Promise` resolved with the value of calling `fn(...arguments)`. If the function throws an error, the returned `Promise` will be rejected with that error.

Support for passing arguments on to the `fn` is provided in order to be able to avoid creating unnecessary closures. You probably don't need this optimization unless you're pushing a *lot* of functions.

#### fn

The function to run to start the promise chain.

#### arguments

Arguments to pass to `fn`.


## Related

- [p-finally](https://github.com/sindresorhus/p-finally) - `Promise#finally()` ponyfill - Invoked when the promise is settled regardless of outcome
- [More…](https://github.com/sindresorhus/promise-fun)


## License

MIT © [Sindre Sorhus](https://sindresorhus.com)


---

# package-json

> Get metadata of a package from the npm registry

## Install

```sh
npm install package-json
```

## Usage

```js
import packageJson from 'package-json';

console.log(await packageJson('ava'));
//=> {name: 'ava', …}

// Also works with scoped packages
console.log(await packageJson('@sindresorhus/df'));
```

## API

### packageJson(packageName, options?)

#### packageName

Type: `string`

Name of the package.

#### options

Type: `object`

##### version

Type: `string`\
Default: `latest`

Package version such as `1.0.0` or a [dist tag](https://docs.npmjs.com/cli/dist-tag) such as `latest`.

The version can also be in any format supported by the [semver](https://github.com/npm/node-semver) module. For example:

- `1` - Get the latest `1.x.x`
- `1.2` - Get the latest `1.2.x`
- `^1.2.3` - Get the latest `1.x.x` but at least `1.2.3`
- `~1.2.3` - Get the latest `1.2.x` but at least `1.2.3`

##### fullMetadata

Type: `boolean`\
Default: `false`

By default, only an abbreviated metadata object is returned for performance reasons. [Read more.](https://github.com/npm/registry/blob/master/docs/responses/package-metadata.md)

##### allVersions

Type: `boolean`\
Default: `false`

Return the [main entry](https://registry.npmjs.org/ava) containing all versions.

##### registryUrl

Type: `string`\
Default: Auto-detected

The registry URL is by default inferred from the npm defaults and `.npmrc`. This is beneficial as `package-json` and any project using it will work just like npm. This option is **only** intended for internal tools. You should **not** use this option in reusable packages. Prefer just using `.npmrc` whenever possible.

##### agent

Type: `object`

Overwrite the `agent` option that is passed down to [`got`](https://github.com/sindresorhus/got#agent). This might be useful to add [proxy support](https://github.com/sindresorhus/got#proxies).

### PackageNotFoundError

The error thrown when the given package name cannot be found.

### VersionNotFoundError

The error thrown when the given package version cannot be found.

## Authentication

Both public and private registries are supported, for both scoped and unscoped packages, as long as the registry uses either bearer tokens or basic authentication.

## Related

- [package-json-cli](https://github.com/sindresorhus/package-json-cli) - CLI for this module
- [latest-version](https://github.com/sindresorhus/latest-version) - Get the latest version of an npm package
- [pkg-versions](https://github.com/sindresorhus/pkg-versions) - Get the version numbers of a package from the npm registry
- [npm-keyword](https://github.com/sindresorhus/npm-keyword) - Get a list of npm packages with a certain keyword
- [npm-user](https://github.com/sindresorhus/npm-user) - Get user info of an npm user
- [npm-email](https://github.com/sindresorhus/npm-email) - Get the email of an npm user


---

# Param Case

[![NPM version][npm-image]][npm-url]
[![NPM downloads][downloads-image]][downloads-url]
[![Bundle size][bundlephobia-image]][bundlephobia-url]

> Transform into a lower cased string with dashes between words.

## Installation

```
npm install param-case --save
```

## Usage

```js
import { paramCase } from "param-case";

paramCase("string"); //=> "string"
paramCase("dot.case"); //=> "dot-case"
paramCase("PascalCase"); //=> "pascal-case"
paramCase("version 1.2.10"); //=> "version-1-2-10"
```

The function also accepts [`options`](https://github.com/blakeembrey/change-case#options).

## License

MIT

[npm-image]: https://img.shields.io/npm/v/param-case.svg?style=flat
[npm-url]: https://npmjs.org/package/param-case
[downloads-image]: https://img.shields.io/npm/dm/param-case.svg?style=flat
[downloads-url]: https://npmjs.org/package/param-case
[bundlephobia-image]: https://img.shields.io/bundlephobia/minzip/param-case.svg
[bundlephobia-url]: https://bundlephobia.com/result?p=param-case


---

# parent-module [![Build Status](https://travis-ci.org/sindresorhus/parent-module.svg?branch=master)](https://travis-ci.org/sindresorhus/parent-module)

> Get the path of the parent module

Node.js exposes `module.parent`, but it only gives you the first cached parent, which is not necessarily the actual parent.


## Install

```
$ npm install parent-module
```


## Usage

```js
// bar.js
const parentModule = require('parent-module');

module.exports = () => {
	console.log(parentModule());
	//=> '/Users/sindresorhus/dev/unicorn/foo.js'
};
```

```js
// foo.js
const bar = require('./bar');

bar();
```


## API

### parentModule([filepath])

By default, it will return the path of the immediate parent.

#### filepath

Type: `string`<br>
Default: [`__filename`](https://nodejs.org/api/globals.html#globals_filename)

Filepath of the module of which to get the parent path.

Useful if you want it to work [multiple module levels down](https://github.com/sindresorhus/parent-module/tree/master/fixtures/filepath).


## Tip

Combine it with [`read-pkg-up`](https://github.com/sindresorhus/read-pkg-up) to read the package.json of the parent module.

```js
const path = require('path');
const readPkgUp = require('read-pkg-up');
const parentModule = require('parent-module');

console.log(readPkgUp.sync({cwd: path.dirname(parentModule())}).pkg);
//=> {name: 'chalk', version: '1.0.0', …}
```


## License

MIT © [Sindre Sorhus](https://sindresorhus.com)


---

# Installation
> `npm install --save @types/unist`

# Summary
This package contains type definitions for unist (https://github.com/syntax-tree/unist).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/unist/v2.
## [index.d.ts](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/unist/v2/index.d.ts)
````ts
/**
 * Syntactic units in unist syntax trees are called nodes.
 *
 * @typeParam TData Information from the ecosystem. Useful for more specific {@link Node.data}.
 */
export interface Node<TData extends object = Data> {
    /**
     * The variant of a node.
     */
    type: string;

    /**
     * Information from the ecosystem.
     */
    data?: TData | undefined;

    /**
     * Location of a node in a source document.
     * Must not be present if a node is generated.
     */
    position?: Position | undefined;
}

/**
 * Information associated by the ecosystem with the node.
 * Space is guaranteed to never be specified by unist or specifications
 * implementing unist.
 */
export interface Data {
    [key: string]: unknown;
}

/**
 * Location of a node in a source file.
 */
export interface Position {
    /**
     * Place of the first character of the parsed source region.
     */
    start: Point;

    /**
     * Place of the first character after the parsed source region.
     */
    end: Point;

    /**
     * Start column at each index (plus start line) in the source region,
     * for elements that span multiple lines.
     */
    indent?: number[] | undefined;
}

/**
 * One place in a source file.
 */
export interface Point {
    /**
     * Line in a source file (1-indexed integer).
     */
    line: number;

    /**
     * Column in a source file (1-indexed integer).
     */
    column: number;
    /**
     * Character in a source file (0-indexed integer).
     */
    offset?: number | undefined;
}

/**
 * Util for extracting type of {@link Node.data}
 *
 * @typeParam TNode Specific node type such as {@link Node} with {@link Data}, {@link Literal}, etc.
 *
 * @example `NodeData<Node<{ key: string }>>` -> `{ key: string }`
 */
export type NodeData<TNode extends Node<object>> = TNode extends Node<infer TData> ? TData : never;

/**
 * Nodes containing other nodes.
 *
 * @typeParam ChildNode Node item of {@link Parent.children}
 */
export interface Parent<ChildNode extends Node<object> = Node, TData extends object = NodeData<ChildNode>>
    extends Node<TData>
{
    /**
     * List representing the children of a node.
     */
    children: ChildNode[];
}

/**
 * Nodes containing a value.
 *
 * @typeParam Value Specific value type of {@link Literal.value} such as `string` for `Text` node
 */
export interface Literal<Value = unknown, TData extends object = Data> extends Node<TData> {
    value: Value;
}

````

### Additional Details
 * Last updated: Thu, 15 Aug 2024 02:18:53 GMT
 * Dependencies: none

# Credits
These definitions were written by [bizen241](https://github.com/bizen241), [Jun Lu](https://github.com/lujun2), [Hernan Rajchert](https://github.com/hrajchert), [Titus Wormer](https://github.com/wooorm), [Junyoung Choi](https://github.com/rokt33r), [Ben Moon](https://github.com/GuiltyDolphin), and [JounQin](https://github.com/JounQin).


---

# parse-entities

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]

Parse HTML character references.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`parseEntities(value[, options])`](#parseentitiesvalue-options)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Related](#related)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This is a small and powerful decoder of HTML character references (often called
entities).

## When should I use this?

You can use this for spec-compliant decoding of character references.
It’s small and fast enough to do that well.
You can also use this when making a linter, because there are different warnings
emitted with reasons for why and positional info on where they happened.

## Install

This package is [ESM only][esm].
In Node.js (version 14.14+, 16.0+), install with [npm][]:

```sh
npm install parse-entities
```

In Deno with [`esm.sh`][esmsh]:

```js
import {parseEntities} from 'https://esm.sh/parse-entities@3'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {parseEntities} from 'https://esm.sh/parse-entities@3?bundle'
</script>
```

## Use

```js
import {parseEntities} from 'parse-entities'

console.log(parseEntities('alpha &amp bravo')))
// => alpha & bravo

console.log(parseEntities('charlie &copycat; delta'))
// => charlie ©cat; delta

console.log(parseEntities('echo &copy; foxtrot &#8800; golf &#x1D306; hotel'))
// => echo © foxtrot ≠ golf 𝌆 hotel
```

## API

This package exports the identifier `parseEntities`.
There is no default export.

### `parseEntities(value[, options])`

Parse HTML character references.

##### `options`

Configuration (optional).

###### `options.additional`

Additional character to accept (`string?`, default: `''`).
This allows other characters, without error, when following an ampersand.

###### `options.attribute`

Whether to parse `value` as an attribute value (`boolean?`, default: `false`).
This results in slightly different behavior.

###### `options.nonTerminated`

Whether to allow nonterminated references (`boolean`, default: `true`).
For example, `&copycat` for `©cat`.
This behavior is compliant to the spec but can lead to unexpected results.

###### `options.position`

Starting `position` of `value` (`Position` or `Point`, optional).
Useful when dealing with values nested in some sort of syntax tree.
The default is:

```js
{line: 1, column: 1, offset: 0}
```

###### `options.warning`

Error handler ([`Function?`][warning]).

###### `options.text`

Text handler ([`Function?`][text]).

###### `options.reference`

Reference handler ([`Function?`][reference]).

###### `options.warningContext`

Context used when calling `warning` (`'*'`, optional).

###### `options.textContext`

Context used when calling `text` (`'*'`, optional).

###### `options.referenceContext`

Context used when calling `reference` (`'*'`, optional)

##### Returns

`string` — decoded `value`.

#### `function warning(reason, point, code)`

Error handler.

###### Parameters

* `this` (`*`) — refers to `warningContext` when given to `parseEntities`
* `reason` (`string`) — human readable reason for emitting a parse error
* `point` ([`Point`][point]) — place where the error occurred
* `code` (`number`) — machine readable code the error

The following codes are used:

| Code | Example            | Note                                          |
| ---- | ------------------ | --------------------------------------------- |
| `1`  | `foo &amp bar`     | Missing semicolon (named)                     |
| `2`  | `foo &#123 bar`    | Missing semicolon (numeric)                   |
| `3`  | `Foo &bar baz`     | Empty (named)                                 |
| `4`  | `Foo &#`           | Empty (numeric)                               |
| `5`  | `Foo &bar; baz`    | Unknown (named)                               |
| `6`  | `Foo &#128; baz`   | [Disallowed reference][invalid]               |
| `7`  | `Foo &#xD800; baz` | Prohibited: outside permissible unicode range |

#### `function text(value, position)`

Text handler.

###### Parameters

* `this` (`*`) — refers to `textContext` when given to `parseEntities`
* `value` (`string`) — string of content
* `position` ([`Position`][position]) — place where `value` starts and ends

#### `function reference(value, position, source)`

Character reference handler.

###### Parameters

* `this` (`*`) — refers to `referenceContext` when given to `parseEntities`
* `value` (`string`) — decoded character reference
* `position` ([`Position`][position]) — place where `source` starts and ends
* `source` (`string`) — raw source of character reference

## Types

This package is fully typed with [TypeScript][].
It exports the additional types `Options`, `WarningHandler`,
`ReferenceHandler`, and `TextHandler`.

## Compatibility

This package is at least compatible with all maintained versions of Node.js.
As of now, that is Node.js 14.14+ and 16.0+.
It also works in Deno and modern browsers.

## Security

This package is safe: it matches the HTML spec to parse character references.

## Related

* [`wooorm/stringify-entities`](https://github.com/wooorm/stringify-entities)
  — encode HTML character references
* [`wooorm/character-entities`](https://github.com/wooorm/character-entities)
  — info on character references
* [`wooorm/character-entities-html4`](https://github.com/wooorm/character-entities-html4)
  — info on HTML4 character references
* [`wooorm/character-entities-legacy`](https://github.com/wooorm/character-entities-legacy)
  — info on legacy character references
* [`wooorm/character-reference-invalid`](https://github.com/wooorm/character-reference-invalid)
  — info on invalid numeric character references

## Contribute

Yes please!
See [How to Contribute to Open Source][contribute].

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/wooorm/parse-entities/workflows/main/badge.svg

[build]: https://github.com/wooorm/parse-entities/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/parse-entities.svg

[coverage]: https://codecov.io/github/wooorm/parse-entities

[downloads-badge]: https://img.shields.io/npm/dm/parse-entities.svg

[downloads]: https://www.npmjs.com/package/parse-entities

[size-badge]: https://img.shields.io/bundlephobia/minzip/parse-entities.svg

[size]: https://bundlephobia.com/result?p=parse-entities

[npm]: https://docs.npmjs.com/cli/install

[esmsh]: https://esm.sh

[license]: license

[author]: https://wooorm.com

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[typescript]: https://www.typescriptlang.org

[warning]: #function-warningreason-point-code

[text]: #function-textvalue-position

[reference]: #function-referencevalue-position-source

[invalid]: https://github.com/wooorm/character-reference-invalid

[point]: https://github.com/syntax-tree/unist#point

[position]: https://github.com/syntax-tree/unist#position

[contribute]: https://opensource.guide/how-to-contribute/


---

# parse-json

> Parse JSON with more helpful errors

## Install

```
$ npm install parse-json
```

## Usage

```js
const parseJson = require('parse-json');

const json = '{\n\t"foo": true,\n}';


JSON.parse(json);
/*
undefined:3
}
^
SyntaxError: Unexpected token }
*/


parseJson(json);
/*
JSONError: Unexpected token } in JSON at position 16 while parsing near '{      "foo": true,}'

  1 | {
  2 |   "foo": true,
> 3 | }
    | ^
*/


parseJson(json, 'foo.json');
/*
JSONError: Unexpected token } in JSON at position 16 while parsing near '{      "foo": true,}' in foo.json

  1 | {
  2 |   "foo": true,
> 3 | }
    | ^
*/


// You can also add the filename at a later point
try {
	parseJson(json);
} catch (error) {
	if (error instanceof parseJson.JSONError) {
		error.fileName = 'foo.json';
	}

	throw error;
}
/*
JSONError: Unexpected token } in JSON at position 16 while parsing near '{      "foo": true,}' in foo.json

  1 | {
  2 |   "foo": true,
> 3 | }
    | ^
*/
```

## API

### parseJson(string, reviver?, filename?)

Throws a `JSONError` when there is a parsing error.

#### string

Type: `string`

#### reviver

Type: `Function`

Prescribes how the value originally produced by parsing is transformed, before being returned. See [`JSON.parse` docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse#Using_the_reviver_parameter
) for more.

#### filename

Type: `string`

Filename displayed in the error message.

### parseJson.JSONError

Exposed for `instanceof` checking.

#### fileName

Type: `string`

The filename displayed in the error message.

#### codeFrame

Type: `string`

The printable section of the JSON which produces the error.

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-parse-json?utm_source=npm-parse-json&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

node-parse-numeric-range
========================

Parses expressions like 1-10,20-30. Returns an energetic (as opposed to lazy) array.


## Supported Expressions
Comprehensive supported expression examples:

| Expression | result       |
|:----------:|:------------:|
|            |   []         |
|     1      |   [1]        |
|    1,2     |  [1,2]       |
|    -10     |  [-10]       |
|   -3,-3    |[-3, -3]      |
|  -1-2,-2   |[-1,0,1,2,-2] |
|  -1--2     |[-1,-2]       |
|  -1..2,-2  |[-1,0,1,2,-2] |
|  -1...3,-2 |[-1,0,1,2,-2] |
|   1⋯3      |[1,2]         |
|  1…3       |[1,2]         |
|  1‥3       |[1,2,3]       |


What's this useful for? Well, letting users input these sorts of things and then
making them programmatically useful.


## Usage

First, `npm install parse-numeric-range`.

```javascript
const rangeParser = require("parse-numeric-range");

const numbers = rangeParser("4,6,8-10,12,14..16,18,20...23");

console.log(
  `The first ${numbers.length} composite numbers are: ${numbers.join(", ")}`,
);
```

### ES6
```jsx
import rangeParser from "parse-numeric-range";

const numbers = rangeParser("4,6,8-10,12,14..16,18,20...23");

console.log(
  `The first ${numbers.length} composite numbers are: ${numbers.join(", ")}`,
);
```

---

<p align="center">
    <a href="https://github.com/inikulin/parse5">
        <img src="https://raw.github.com/inikulin/parse5/master/media/logo.png" alt="parse5" />
    </a>
</p>

<div align="center">
<h1>parse5</h1>
<i><b>HTML parser and serializer.</b></i>
</div>
<br>

<div align="center">
<code>npm install --save parse5</code>
</div>
<br>

<p align="center">
  📖 <a href="https://parse5.js.org/modules/parse5.html"><b>Documentation</b></a> 📖
</p>

---

<p align="center">
  <a href="https://github.com/inikulin/parse5/tree/master/docs/list-of-packages.md">List of parse5 toolset packages</a>
</p>

<p align="center">
    <a href="https://github.com/inikulin/parse5">GitHub</a>
</p>

<p align="center">
  <a href="http://astexplorer.net/#/1CHlCXc4n4">Online playground</a>
</p>

<p align="center">
    <a href="https://github.com/inikulin/parse5/releases">Changelog</a>
</p>


---

<p align="center">
    <a href="https://github.com/inikulin/parse5">
        <img src="https://raw.github.com/inikulin/parse5/master/media/logo.png" alt="parse5" />
    </a>
</p>

<div align="center">
<h1>parse5-htmlparser2-tree-adapter</h1>
<i><b><a href="https://github.com/fb55/htmlparser2">htmlparser2</a> tree adapter for <a href="https://github.com/inikulin/parse5">parse5</a>.</b></i>
</div>
<br>

<div align="center">
<code>npm install --save parse5-htmlparser2-tree-adapter</code>
</div>
<br>

<p align="center">
  📖 <a href="https://parse5.js.org/modules/parse5_htmlparser2_tree_adapter.html"><b>Documentation</b></a> 📖
</p>

---

<p align="center">
  <a href="https://github.com/inikulin/parse5/tree/master/docs/list-of-packages.md">List of parse5 toolset packages</a>
</p>

<p align="center">
    <a href="https://github.com/inikulin/parse5">GitHub</a>
</p>

<p align="center">
    <a href="https://github.com/inikulin/parse5/releases">Changelog</a>
</p>


---

1.3.3 / 2019-04-15
==================

  * Fix Node.js 0.8 return value inconsistencies

1.3.2 / 2017-09-09
==================

  * perf: reduce overhead for full URLs
  * perf: unroll the "fast-path" `RegExp`

1.3.1 / 2016-01-17
==================

  * perf: enable strict mode

1.3.0 / 2014-08-09
==================

  * Add `parseurl.original` for parsing `req.originalUrl` with fallback
  * Return `undefined` if `req.url` is `undefined`

1.2.0 / 2014-07-21
==================

  * Cache URLs based on original value
  * Remove no-longer-needed URL mis-parse work-around
  * Simplify the "fast-path" `RegExp`

1.1.3 / 2014-07-08
==================

  * Fix typo

1.1.2 / 2014-07-08
==================

  * Seriously fix Node.js 0.8 compatibility

1.1.1 / 2014-07-08
==================

  * Fix Node.js 0.8 compatibility

1.1.0 / 2014-07-08
==================

  * Incorporate URL href-only parse fast-path

1.0.1 / 2014-03-08
==================

  * Add missing `require`

1.0.0 / 2014-03-08
==================

  * Genesis from `connect`


---

# parseurl

[![NPM Version][npm-version-image]][npm-url]
[![NPM Downloads][npm-downloads-image]][npm-url]
[![Node.js Version][node-image]][node-url]
[![Build Status][travis-image]][travis-url]
[![Test Coverage][coveralls-image]][coveralls-url]

Parse a URL with memoization.

## Install

This is a [Node.js](https://nodejs.org/en/) module available through the
[npm registry](https://www.npmjs.com/). Installation is done using the
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):

```sh
$ npm install parseurl
```

## API

```js
var parseurl = require('parseurl')
```

### parseurl(req)

Parse the URL of the given request object (looks at the `req.url` property)
and return the result. The result is the same as `url.parse` in Node.js core.
Calling this function multiple times on the same `req` where `req.url` does
not change will return a cached parsed object, rather than parsing again.

### parseurl.original(req)

Parse the original URL of the given request object and return the result.
This works by trying to parse `req.originalUrl` if it is a string, otherwise
parses `req.url`. The result is the same as `url.parse` in Node.js core.
Calling this function multiple times on the same `req` where `req.originalUrl`
does not change will return a cached parsed object, rather than parsing again.

## Benchmark

```bash
$ npm run-script bench

> parseurl@1.3.3 bench nodejs-parseurl
> node benchmark/index.js

  http_parser@2.8.0
  node@10.6.0
  v8@6.7.288.46-node.13
  uv@1.21.0
  zlib@1.2.11
  ares@1.14.0
  modules@64
  nghttp2@1.32.0
  napi@3
  openssl@1.1.0h
  icu@61.1
  unicode@10.0
  cldr@33.0
  tz@2018c

> node benchmark/fullurl.js

  Parsing URL "http://localhost:8888/foo/bar?user=tj&pet=fluffy"

  4 tests completed.

  fasturl            x 2,207,842 ops/sec ±3.76% (184 runs sampled)
  nativeurl - legacy x   507,180 ops/sec ±0.82% (191 runs sampled)
  nativeurl - whatwg x   290,044 ops/sec ±1.96% (189 runs sampled)
  parseurl           x   488,907 ops/sec ±2.13% (192 runs sampled)

> node benchmark/pathquery.js

  Parsing URL "/foo/bar?user=tj&pet=fluffy"

  4 tests completed.

  fasturl            x 3,812,564 ops/sec ±3.15% (188 runs sampled)
  nativeurl - legacy x 2,651,631 ops/sec ±1.68% (189 runs sampled)
  nativeurl - whatwg x   161,837 ops/sec ±2.26% (189 runs sampled)
  parseurl           x 4,166,338 ops/sec ±2.23% (184 runs sampled)

> node benchmark/samerequest.js

  Parsing URL "/foo/bar?user=tj&pet=fluffy" on same request object

  4 tests completed.

  fasturl            x  3,821,651 ops/sec ±2.42% (185 runs sampled)
  nativeurl - legacy x  2,651,162 ops/sec ±1.90% (187 runs sampled)
  nativeurl - whatwg x    175,166 ops/sec ±1.44% (188 runs sampled)
  parseurl           x 14,912,606 ops/sec ±3.59% (183 runs sampled)

> node benchmark/simplepath.js

  Parsing URL "/foo/bar"

  4 tests completed.

  fasturl            x 12,421,765 ops/sec ±2.04% (191 runs sampled)
  nativeurl - legacy x  7,546,036 ops/sec ±1.41% (188 runs sampled)
  nativeurl - whatwg x    198,843 ops/sec ±1.83% (189 runs sampled)
  parseurl           x 24,244,006 ops/sec ±0.51% (194 runs sampled)

> node benchmark/slash.js

  Parsing URL "/"

  4 tests completed.

  fasturl            x 17,159,456 ops/sec ±3.25% (188 runs sampled)
  nativeurl - legacy x 11,635,097 ops/sec ±3.79% (184 runs sampled)
  nativeurl - whatwg x    240,693 ops/sec ±0.83% (189 runs sampled)
  parseurl           x 42,279,067 ops/sec ±0.55% (190 runs sampled)
```

## License

  [MIT](LICENSE)

[coveralls-image]: https://badgen.net/coveralls/c/github/pillarjs/parseurl/master
[coveralls-url]: https://coveralls.io/r/pillarjs/parseurl?branch=master
[node-image]: https://badgen.net/npm/node/parseurl
[node-url]: https://nodejs.org/en/download
[npm-downloads-image]: https://badgen.net/npm/dm/parseurl
[npm-url]: https://npmjs.org/package/parseurl
[npm-version-image]: https://badgen.net/npm/v/parseurl
[travis-image]: https://badgen.net/travis/pillarjs/parseurl/master
[travis-url]: https://travis-ci.org/pillarjs/parseurl


---

# Pascal Case

[![NPM version][npm-image]][npm-url]
[![NPM downloads][downloads-image]][downloads-url]
[![Bundle size][bundlephobia-image]][bundlephobia-url]

> Transform into a string of capitalized words without separators.

## Installation

```
npm install pascal-case --save
```

## Usage

```js
import { pascalCase } from "pascal-case";

pascalCase("string"); //=> "String"
pascalCase("dot.case"); //=> "DotCase"
pascalCase("PascalCase"); //=> "PascalCase"
pascalCase("version 1.2.10"); //=> "Version_1_2_10"
```

The function also accepts [`options`](https://github.com/blakeembrey/change-case#options).

### Merge Numbers

If you'd like to remove the behavior prefixing `_` before numbers, you can use `pascalCaseTransformMerge`:

```js
import { pascalCaseTransformMerge } from "pascal-case";

pascalCase("version 12", { transform: pascalCaseTransformMerge }); //=> "Version12"
```

## License

MIT

[npm-image]: https://img.shields.io/npm/v/pascal-case.svg?style=flat
[npm-url]: https://npmjs.org/package/pascal-case
[downloads-image]: https://img.shields.io/npm/dm/pascal-case.svg?style=flat
[downloads-url]: https://npmjs.org/package/pascal-case
[bundlephobia-image]: https://img.shields.io/bundlephobia/minzip/pascal-case.svg
[bundlephobia-url]: https://bundlephobia.com/result?p=pascal-case


---

# path-exists

> Check if a path exists

NOTE: `fs.existsSync` has been un-deprecated in Node.js since 6.8.0. If you only need to check synchronously, this module is not needed.

Never use this before handling a file though:

> In particular, checking if a file exists before opening it is an anti-pattern that leaves you vulnerable to race conditions: another process may remove the file between the calls to `fs.exists()` and `fs.open()`. Just open the file and handle the error when it's not there.

## Install

```
$ npm install path-exists
```

## Usage

```js
// foo.js
import {pathExists} from 'path-exists';

console.log(await pathExists('foo.js'));
//=> true
```

## API

### pathExists(path)

Returns a `Promise<boolean>` of whether the path exists.

### pathExistsSync(path)

Returns a `boolean` of whether the path exists.

## Related

- [path-exists-cli](https://github.com/sindresorhus/path-exists-cli) - CLI for this module
- [path-type](https://github.com/sindresorhus/path-type) - Check if a path exists and whether it's a file, directory, or symlink

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-path-exists?utm_source=npm-path-exists&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

# path-is-absolute [![Build Status](https://travis-ci.org/sindresorhus/path-is-absolute.svg?branch=master)](https://travis-ci.org/sindresorhus/path-is-absolute)

> Node.js 0.12 [`path.isAbsolute()`](http://nodejs.org/api/path.html#path_path_isabsolute_path) [ponyfill](https://ponyfill.com)


## Install

```
$ npm install --save path-is-absolute
```


## Usage

```js
const pathIsAbsolute = require('path-is-absolute');

// Running on Linux
pathIsAbsolute('/home/foo');
//=> true
pathIsAbsolute('C:/Users/foo');
//=> false

// Running on Windows
pathIsAbsolute('C:/Users/foo');
//=> true
pathIsAbsolute('/home/foo');
//=> false

// Running on any OS
pathIsAbsolute.posix('/home/foo');
//=> true
pathIsAbsolute.posix('C:/Users/foo');
//=> false
pathIsAbsolute.win32('C:/Users/foo');
//=> true
pathIsAbsolute.win32('/home/foo');
//=> false
```


## API

See the [`path.isAbsolute()` docs](http://nodejs.org/api/path.html#path_path_isabsolute_path).

### pathIsAbsolute(path)

### pathIsAbsolute.posix(path)

POSIX specific version.

### pathIsAbsolute.win32(path)

Windows specific version.


## License

MIT © [Sindre Sorhus](https://sindresorhus.com)


---

# path-key [![Build Status](https://travis-ci.org/sindresorhus/path-key.svg?branch=master)](https://travis-ci.org/sindresorhus/path-key)

> Get the [PATH](https://en.wikipedia.org/wiki/PATH_(variable)) environment variable key cross-platform

It's usually `PATH`, but on Windows it can be any casing like `Path`...


## Install

```
$ npm install path-key
```


## Usage

```js
const pathKey = require('path-key');

const key = pathKey();
//=> 'PATH'

const PATH = process.env[key];
//=> '/usr/local/bin:/usr/bin:/bin'
```


## API

### pathKey(options?)

#### options

Type: `object`

##### env

Type: `object`<br>
Default: [`process.env`](https://nodejs.org/api/process.html#process_process_env)

Use a custom environment variables object.

#### platform

Type: `string`<br>
Default: [`process.platform`](https://nodejs.org/api/process.html#process_process_platform)

Get the PATH key for a specific platform.


---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-path-key?utm_source=npm-path-key&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

# path-parse [![Build Status](https://travis-ci.org/jbgutierrez/path-parse.svg?branch=master)](https://travis-ci.org/jbgutierrez/path-parse)

> Node.js [`path.parse(pathString)`](https://nodejs.org/api/path.html#path_path_parse_pathstring) [ponyfill](https://ponyfill.com).

## Install

```
$ npm install --save path-parse
```

## Usage

```js
var pathParse = require('path-parse');

pathParse('/home/user/dir/file.txt');
//=> {
//       root : "/",
//       dir : "/home/user/dir",
//       base : "file.txt",
//       ext : ".txt",
//       name : "file"
//   }
```

## API

See [`path.parse(pathString)`](https://nodejs.org/api/path.html#path_path_parse_pathstring) docs.

### pathParse(path)

### pathParse.posix(path)

The Posix specific version.

### pathParse.win32(path)

The Windows specific version.

## License

MIT © [Javier Blanco](http://jbgutierrez.info)


---

# Path-to-RegExp

> Turn an Express-style path string such as `/user/:name` into a regular expression.

[![NPM version][npm-image]][npm-url]
[![Build status][travis-image]][travis-url]
[![Test coverage][coveralls-image]][coveralls-url]
[![Dependency Status][david-image]][david-url]
[![License][license-image]][license-url]
[![Downloads][downloads-image]][downloads-url]

## Installation

```
npm install path-to-regexp --save
```

## Usage

```javascript
var pathToRegexp = require('path-to-regexp')

// pathToRegexp(path, keys, options)
// pathToRegexp.parse(path)
// pathToRegexp.compile(path)
```

- **path** An Express-style string, an array of strings, or a regular expression.
- **keys** An array to be populated with the keys found in the path.
- **options**
  - **sensitive** When `true` the route will be case sensitive. (default: `false`)
  - **strict** When `false` the trailing slash is optional. (default: `false`)
  - **end** When `false` the path will match at the beginning. (default: `true`)
  - **delimiter** Set the default delimiter for repeat parameters. (default: `'/'`)

```javascript
var keys = []
var re = pathToRegexp('/foo/:bar', keys)
// re = /^\/foo\/([^\/]+?)\/?$/i
// keys = [{ name: 'bar', prefix: '/', delimiter: '/', optional: false, repeat: false, pattern: '[^\\/]+?' }]
```

**Please note:** The `RegExp` returned by `path-to-regexp` is intended for use with pathnames or hostnames. It can not handle the query strings or fragments of a URL.

### Parameters

The path string can be used to define parameters and populate the keys.

#### Named Parameters

Named parameters are defined by prefixing a colon to the parameter name (`:foo`). By default, the parameter will match until the following path segment.

```js
var re = pathToRegexp('/:foo/:bar', keys)
// keys = [{ name: 'foo', prefix: '/', ... }, { name: 'bar', prefix: '/', ... }]

re.exec('/test/route')
//=> ['/test/route', 'test', 'route']
```

**Please note:** Named parameters must be made up of "word characters" (`[A-Za-z0-9_]`).

```js
var re = pathToRegexp('/(apple-)?icon-:res(\\d+).png', keys)
// keys = [{ name: 0, prefix: '/', ... }, { name: 'res', prefix: '', ... }]

re.exec('/icon-76.png')
//=> ['/icon-76.png', undefined, '76']
```

#### Modified Parameters

##### Optional

Parameters can be suffixed with a question mark (`?`) to make the parameter optional. This will also make the prefix optional.

```js
var re = pathToRegexp('/:foo/:bar?', keys)
// keys = [{ name: 'foo', ... }, { name: 'bar', delimiter: '/', optional: true, repeat: false }]

re.exec('/test')
//=> ['/test', 'test', undefined]

re.exec('/test/route')
//=> ['/test/route', 'test', 'route']
```

##### Zero or more

Parameters can be suffixed with an asterisk (`*`) to denote a zero or more parameter matches. The prefix is taken into account for each match.

```js
var re = pathToRegexp('/:foo*', keys)
// keys = [{ name: 'foo', delimiter: '/', optional: true, repeat: true }]

re.exec('/')
//=> ['/', undefined]

re.exec('/bar/baz')
//=> ['/bar/baz', 'bar/baz']
```

##### One or more

Parameters can be suffixed with a plus sign (`+`) to denote a one or more parameter matches. The prefix is taken into account for each match.

```js
var re = pathToRegexp('/:foo+', keys)
// keys = [{ name: 'foo', delimiter: '/', optional: false, repeat: true }]

re.exec('/')
//=> null

re.exec('/bar/baz')
//=> ['/bar/baz', 'bar/baz']
```

#### Custom Match Parameters

All parameters can be provided a custom regexp, which overrides the default (`[^\/]+`).

```js
var re = pathToRegexp('/:foo(\\d+)', keys)
// keys = [{ name: 'foo', ... }]

re.exec('/123')
//=> ['/123', '123']

re.exec('/abc')
//=> null
```

**Please note:** Backslashes need to be escaped with another backslash in strings.

#### Unnamed Parameters

It is possible to write an unnamed parameter that only consists of a matching group. It works the same as a named parameter, except it will be numerically indexed.

```js
var re = pathToRegexp('/:foo/(.*)', keys)
// keys = [{ name: 'foo', ... }, { name: 0, ... }]

re.exec('/test/route')
//=> ['/test/route', 'test', 'route']
```

#### Asterisk

An asterisk can be used for matching everything. It is equivalent to an unnamed matching group of `(.*)`.

```js
var re = pathToRegexp('/foo/*', keys)
// keys = [{ name: '0', ... }]

re.exec('/foo/bar/baz')
//=> ['/foo/bar/baz', 'bar/baz']
```

### Parse

The parse function is exposed via `pathToRegexp.parse`. This will return an array of strings and keys.

```js
var tokens = pathToRegexp.parse('/route/:foo/(.*)')

console.log(tokens[0])
//=> "/route"

console.log(tokens[1])
//=> { name: 'foo', prefix: '/', delimiter: '/', optional: false, repeat: false, pattern: '[^\\/]+?' }

console.log(tokens[2])
//=> { name: 0, prefix: '/', delimiter: '/', optional: false, repeat: false, pattern: '.*' }
```

**Note:** This method only works with Express-style strings.

### Compile ("Reverse" Path-To-RegExp)

Path-To-RegExp exposes a compile function for transforming an Express-style path into a valid path.

```js
var toPath = pathToRegexp.compile('/user/:id')

toPath({ id: 123 }) //=> "/user/123"
toPath({ id: 'café' }) //=> "/user/caf%C3%A9"
toPath({ id: '/' }) //=> "/user/%2F"

toPath({ id: ':' }) //=> "/user/%3A"
toPath({ id: ':' }, { pretty: true }) //=> "/user/:"

var toPathRepeated = pathToRegexp.compile('/:segment+')

toPathRepeated({ segment: 'foo' }) //=> "/foo"
toPathRepeated({ segment: ['a', 'b', 'c'] }) //=> "/a/b/c"

var toPathRegexp = pathToRegexp.compile('/user/:id(\\d+)')

toPathRegexp({ id: 123 }) //=> "/user/123"
toPathRegexp({ id: '123' }) //=> "/user/123"
toPathRegexp({ id: 'abc' }) //=> Throws `TypeError`.
```

**Note:** The generated function will throw on invalid input. It will do all necessary checks to ensure the generated path is valid. This method only works with strings.

### Working with Tokens

Path-To-RegExp exposes the two functions used internally that accept an array of tokens.

* `pathToRegexp.tokensToRegExp(tokens, options)` Transform an array of tokens into a matching regular expression.
* `pathToRegexp.tokensToFunction(tokens)` Transform an array of tokens into a path generator function.

#### Token Information

* `name` The name of the token (`string` for named or `number` for index)
* `prefix` The prefix character for the segment (`/` or `.`)
* `delimiter` The delimiter for the segment (same as prefix or `/`)
* `optional` Indicates the token is optional (`boolean`)
* `repeat` Indicates the token is repeated (`boolean`)
* `partial` Indicates this token is a partial path segment (`boolean`)
* `pattern` The RegExp used to match this token (`string`)
* `asterisk` Indicates the token is an `*` match (`boolean`)

## Compatibility with Express <= 4.x

Path-To-RegExp breaks compatibility with Express <= `4.x`:

* No longer a direct conversion to a RegExp with sugar on top - it's a path matcher with named and unnamed matching groups
  * It's unlikely you previously abused this feature, it's rare and you could always use a RegExp instead
* All matching RegExp special characters can be used in a matching group. E.g. `/:user(.*)`
  * Other RegExp features are not support - no nested matching groups, non-capturing groups or look aheads
* Parameters have suffixes that augment meaning - `*`, `+` and `?`. E.g. `/:user*`

## TypeScript

Includes a [`.d.ts`](index.d.ts) file for TypeScript users.

## Live Demo

You can see a live demo of this library in use at [express-route-tester](http://forbeslindesay.github.com/express-route-tester/).

## License

MIT

[npm-image]: https://img.shields.io/npm/v/path-to-regexp.svg?style=flat
[npm-url]: https://npmjs.org/package/path-to-regexp
[travis-image]: https://img.shields.io/travis/pillarjs/path-to-regexp.svg?style=flat
[travis-url]: https://travis-ci.org/pillarjs/path-to-regexp
[coveralls-image]: https://img.shields.io/coveralls/pillarjs/path-to-regexp.svg?style=flat
[coveralls-url]: https://coveralls.io/r/pillarjs/path-to-regexp?branch=master
[david-image]: http://img.shields.io/david/pillarjs/path-to-regexp.svg?style=flat
[david-url]: https://david-dm.org/pillarjs/path-to-regexp
[license-image]: http://img.shields.io/npm/l/path-to-regexp.svg?style=flat
[license-url]: LICENSE.md
[downloads-image]: http://img.shields.io/npm/dm/path-to-regexp.svg?style=flat
[downloads-url]: https://npmjs.org/package/path-to-regexp


---

# path-type [![Build Status](https://travis-ci.org/sindresorhus/path-type.svg?branch=master)](https://travis-ci.org/sindresorhus/path-type)

> Check if a path is a file, directory, or symlink


## Install

```
$ npm install path-type
```


## Usage

```js
const {isFile} = require('path-type');

(async () => {
	console.log(await isFile('package.json'));
	//=> true
})();
```


## API

### isFile(path)

Check whether the passed `path` is a file.

Returns a `Promise<boolean>`.

#### path

Type: `string`

The path to check.

### isDirectory(path)

Check whether the passed `path` is a directory.

Returns a `Promise<boolean>`.

### isSymlink(path)

Check whether the passed `path` is a symlink.

Returns a `Promise<boolean>`.

### isFileSync(path)

Synchronously check whether the passed `path` is a file.

Returns a `boolean`.

### isDirectorySync(path)

Synchronously check whether the passed `path` is a directory.

Returns a `boolean`.

### isSymlinkSync(path)

Synchronously check whether the passed `path` is a symlink.

Returns a `boolean`.


## License

MIT © [Sindre Sorhus](https://sindresorhus.com)


---

# picocolors

The tiniest and the fastest library for terminal output formatting with ANSI colors.

```javascript
import pc from "picocolors"

console.log(
  pc.green(`How are ${pc.italic(`you`)} doing?`)
)
```

- **No dependencies.**
- **14 times** smaller and **2 times** faster than chalk.
- Used by popular tools like PostCSS, SVGO, Stylelint, and Browserslist.
- Node.js v6+ & browsers support. Support for both CJS and ESM projects.
- TypeScript type declarations included.
- [`NO_COLOR`](https://no-color.org/) friendly.

## Docs
Read **[full docs](https://github.com/alexeyraspopov/picocolors#readme)** on GitHub.


---

# Release history

**All notable changes to this project will be documented in this file.**

The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).

<details>
  <summary><strong>Guiding Principles</strong></summary>

- Changelogs are for humans, not machines.
- There should be an entry for every single version.
- The same types of changes should be grouped.
- Versions and sections should be linkable.
- The latest version comes first.
- The release date of each versions is displayed.
- Mention whether you follow Semantic Versioning.

</details>

<details>
  <summary><strong>Types of changes</strong></summary>

Changelog entries are classified using the following labels _(from [keep-a-changelog](http://keepachangelog.com/)_):

- `Added` for new features.
- `Changed` for changes in existing functionality.
- `Deprecated` for soon-to-be removed features.
- `Removed` for now removed features.
- `Fixed` for any bug fixes.
- `Security` in case of vulnerabilities.

</details>

## 2.3.1 (2022-01-02)

### Fixed

* Fixes bug when a pattern containing an expression after the closing parenthesis (`/!(*.d).{ts,tsx}`) was incorrectly converted to regexp ([9f241ef](https://github.com/micromatch/picomatch/commit/9f241ef)).

### Changed

* Some documentation improvements ([f81d236](https://github.com/micromatch/picomatch/commit/f81d236), [421e0e7](https://github.com/micromatch/picomatch/commit/421e0e7)).

## 2.3.0 (2021-05-21)

### Fixed

* Fixes bug where file names with two dots were not being matched consistently with negation extglobs containing a star ([56083ef](https://github.com/micromatch/picomatch/commit/56083ef))

## 2.2.3 (2021-04-10)

### Fixed

* Do not skip pattern seperator for square brackets ([fb08a30](https://github.com/micromatch/picomatch/commit/fb08a30)).
* Set negatedExtGlob also if it does not span the whole pattern ([032e3f5](https://github.com/micromatch/picomatch/commit/032e3f5)).

## 2.2.2 (2020-03-21)

### Fixed

* Correctly handle parts of the pattern after parentheses in the `scan` method ([e15b920](https://github.com/micromatch/picomatch/commit/e15b920)).

## 2.2.1 (2020-01-04)

* Fixes [#49](https://github.com/micromatch/picomatch/issues/49), so that braces with no sets or ranges are now propertly treated as literals.

## 2.2.0 (2020-01-04)

* Disable fastpaths mode for the parse method ([5b8d33f](https://github.com/micromatch/picomatch/commit/5b8d33f))
* Add `tokens`, `slashes`, and `parts` to the object returned by `picomatch.scan()`.

## 2.1.0 (2019-10-31)

* add benchmarks for scan ([4793b92](https://github.com/micromatch/picomatch/commit/4793b92))
* Add eslint object-curly-spacing rule ([707c650](https://github.com/micromatch/picomatch/commit/707c650))
* Add prefer-const eslint rule ([5c7501c](https://github.com/micromatch/picomatch/commit/5c7501c))
* Add support for nonegate in scan API ([275c9b9](https://github.com/micromatch/picomatch/commit/275c9b9))
* Change lets to consts. Move root import up. ([4840625](https://github.com/micromatch/picomatch/commit/4840625))
* closes https://github.com/micromatch/picomatch/issues/21 ([766bcb0](https://github.com/micromatch/picomatch/commit/766bcb0))
* Fix "Extglobs" table in readme ([eb19da8](https://github.com/micromatch/picomatch/commit/eb19da8))
* fixes https://github.com/micromatch/picomatch/issues/20 ([9caca07](https://github.com/micromatch/picomatch/commit/9caca07))
* fixes https://github.com/micromatch/picomatch/issues/26 ([fa58f45](https://github.com/micromatch/picomatch/commit/fa58f45))
* Lint test ([d433a34](https://github.com/micromatch/picomatch/commit/d433a34))
* lint unit tests ([0159b55](https://github.com/micromatch/picomatch/commit/0159b55))
* Make scan work with noext ([6c02e03](https://github.com/micromatch/picomatch/commit/6c02e03))
* minor linting ([c2a2b87](https://github.com/micromatch/picomatch/commit/c2a2b87))
* minor parser improvements ([197671d](https://github.com/micromatch/picomatch/commit/197671d))
* remove eslint since it... ([07876fa](https://github.com/micromatch/picomatch/commit/07876fa))
* remove funding file ([8ebe96d](https://github.com/micromatch/picomatch/commit/8ebe96d))
* Remove unused funks ([cbc6d54](https://github.com/micromatch/picomatch/commit/cbc6d54))
* Run eslint during pretest, fix existing eslint findings ([0682367](https://github.com/micromatch/picomatch/commit/0682367))
* support `noparen` in scan ([3d37569](https://github.com/micromatch/picomatch/commit/3d37569))
* update changelog ([7b34e77](https://github.com/micromatch/picomatch/commit/7b34e77))
* update travis ([777f038](https://github.com/micromatch/picomatch/commit/777f038))
* Use eslint-disable-next-line instead of eslint-disable ([4e7c1fd](https://github.com/micromatch/picomatch/commit/4e7c1fd))

## 2.0.7 (2019-05-14)

* 2.0.7 ([9eb9a71](https://github.com/micromatch/picomatch/commit/9eb9a71))
* supports lookbehinds ([1f63f7e](https://github.com/micromatch/picomatch/commit/1f63f7e))
* update .verb.md file with typo change ([2741279](https://github.com/micromatch/picomatch/commit/2741279))
* fix: typo in README ([0753e44](https://github.com/micromatch/picomatch/commit/0753e44))

## 2.0.4 (2019-04-10)

### Fixed

- Readme link [fixed](https://github.com/micromatch/picomatch/pull/13/commits/a96ab3aa2b11b6861c23289964613d85563b05df) by @danez.
- `options.capture` now works as expected when fastpaths are enabled. See https://github.com/micromatch/picomatch/pull/12/commits/26aefd71f1cfaf95c37f1c1fcab68a693b037304. Thanks to @DrPizza.

## 2.0.0 (2019-04-10)

### Added

- Adds support for `options.onIgnore`. See the readme for details
- Adds support for `options.onResult`. See the readme for details

### Breaking changes

- The unixify option was renamed to `windows`
- caching and all related options and methods have been removed

## 1.0.0 (2018-11-05)

- adds `.onMatch` option
- improvements to `.scan` method
- numerous improvements and optimizations for matching and parsing
- better windows path handling

## 0.1.0 - 2017-04-13

First release.


[keep-a-changelog]: https://github.com/olivierlacan/keep-a-changelog


---

<h1 align="center">Picomatch</h1>

<p align="center">
<a href="https://npmjs.org/package/picomatch">
<img src="https://img.shields.io/npm/v/picomatch.svg" alt="version">
</a>
<a href="https://github.com/micromatch/picomatch/actions?workflow=Tests">
<img src="https://github.com/micromatch/picomatch/workflows/Tests/badge.svg" alt="test status">
</a>
<a href="https://coveralls.io/github/micromatch/picomatch">
<img src="https://img.shields.io/coveralls/github/micromatch/picomatch/master.svg" alt="coverage status">
</a>
<a href="https://npmjs.org/package/picomatch">
<img src="https://img.shields.io/npm/dm/picomatch.svg" alt="downloads">
</a>
</p>

<br>
<br>

<p align="center">
<strong>Blazing fast and accurate glob matcher written in JavaScript.</strong></br>
<em>No dependencies and full support for standard and extended Bash glob features, including braces, extglobs, POSIX brackets, and regular expressions.</em>
</p>

<br>
<br>

## Why picomatch?

* **Lightweight** - No dependencies
* **Minimal** - Tiny API surface. Main export is a function that takes a glob pattern and returns a matcher function.
* **Fast** - Loads in about 2ms (that's several times faster than a [single frame of a HD movie](http://www.endmemo.com/sconvert/framespersecondframespermillisecond.php) at 60fps)
* **Performant** - Use the returned matcher function to speed up repeat matching (like when watching files)
* **Accurate matching** - Using wildcards (`*` and `?`), globstars (`**`) for nested directories, [advanced globbing](#advanced-globbing) with extglobs, braces, and POSIX brackets, and support for escaping special characters with `\` or quotes.
* **Well tested** - Thousands of unit tests

See the [library comparison](#library-comparisons) to other libraries.

<br>
<br>

## Table of Contents

<details><summary> Click to expand </summary>

- [Install](#install)
- [Usage](#usage)
- [API](#api)
  * [picomatch](#picomatch)
  * [.test](#test)
  * [.matchBase](#matchbase)
  * [.isMatch](#ismatch)
  * [.parse](#parse)
  * [.scan](#scan)
  * [.compileRe](#compilere)
  * [.makeRe](#makere)
  * [.toRegex](#toregex)
- [Options](#options)
  * [Picomatch options](#picomatch-options)
  * [Scan Options](#scan-options)
  * [Options Examples](#options-examples)
- [Globbing features](#globbing-features)
  * [Basic globbing](#basic-globbing)
  * [Advanced globbing](#advanced-globbing)
  * [Braces](#braces)
  * [Matching special characters as literals](#matching-special-characters-as-literals)
- [Library Comparisons](#library-comparisons)
- [Benchmarks](#benchmarks)
- [Philosophies](#philosophies)
- [About](#about)
  * [Author](#author)
  * [License](#license)

_(TOC generated by [verb](https://github.com/verbose/verb) using [markdown-toc](https://github.com/jonschlinkert/markdown-toc))_

</details>

<br>
<br>

## Install

Install with [npm](https://www.npmjs.com/):

```sh
npm install --save picomatch
```

<br>

## Usage

The main export is a function that takes a glob pattern and an options object and returns a function for matching strings.

```js
const pm = require('picomatch');
const isMatch = pm('*.js');

console.log(isMatch('abcd')); //=> false
console.log(isMatch('a.js')); //=> true
console.log(isMatch('a.md')); //=> false
console.log(isMatch('a/b.js')); //=> false
```

<br>

## API

### [picomatch](lib/picomatch.js#L32)

Creates a matcher function from one or more glob patterns. The returned function takes a string to match as its first argument, and returns true if the string is a match. The returned matcher function also takes a boolean as the second argument that, when true, returns an object with additional information.

**Params**

* `globs` **{String|Array}**: One or more glob patterns.
* `options` **{Object=}**
* `returns` **{Function=}**: Returns a matcher function.

**Example**

```js
const picomatch = require('picomatch');
// picomatch(glob[, options]);

const isMatch = picomatch('*.!(*a)');
console.log(isMatch('a.a')); //=> false
console.log(isMatch('a.b')); //=> true
```

### [.test](lib/picomatch.js#L117)

Test `input` with the given `regex`. This is used by the main `picomatch()` function to test the input string.

**Params**

* `input` **{String}**: String to test.
* `regex` **{RegExp}**
* `returns` **{Object}**: Returns an object with matching info.

**Example**

```js
const picomatch = require('picomatch');
// picomatch.test(input, regex[, options]);

console.log(picomatch.test('foo/bar', /^(?:([^/]*?)\/([^/]*?))$/));
// { isMatch: true, match: [ 'foo/', 'foo', 'bar' ], output: 'foo/bar' }
```

### [.matchBase](lib/picomatch.js#L161)

Match the basename of a filepath.

**Params**

* `input` **{String}**: String to test.
* `glob` **{RegExp|String}**: Glob pattern or regex created by [.makeRe](#makeRe).
* `returns` **{Boolean}**

**Example**

```js
const picomatch = require('picomatch');
// picomatch.matchBase(input, glob[, options]);
console.log(picomatch.matchBase('foo/bar.js', '*.js'); // true
```

### [.isMatch](lib/picomatch.js#L183)

Returns true if **any** of the given glob `patterns` match the specified `string`.

**Params**

* **{String|Array}**: str The string to test.
* **{String|Array}**: patterns One or more glob patterns to use for matching.
* **{Object}**: See available [options](#options).
* `returns` **{Boolean}**: Returns true if any patterns match `str`

**Example**

```js
const picomatch = require('picomatch');
// picomatch.isMatch(string, patterns[, options]);

console.log(picomatch.isMatch('a.a', ['b.*', '*.a'])); //=> true
console.log(picomatch.isMatch('a.a', 'b.*')); //=> false
```

### [.parse](lib/picomatch.js#L199)

Parse a glob pattern to create the source string for a regular expression.

**Params**

* `pattern` **{String}**
* `options` **{Object}**
* `returns` **{Object}**: Returns an object with useful properties and output to be used as a regex source string.

**Example**

```js
const picomatch = require('picomatch');
const result = picomatch.parse(pattern[, options]);
```

### [.scan](lib/picomatch.js#L231)

Scan a glob pattern to separate the pattern into segments.

**Params**

* `input` **{String}**: Glob pattern to scan.
* `options` **{Object}**
* `returns` **{Object}**: Returns an object with

**Example**

```js
const picomatch = require('picomatch');
// picomatch.scan(input[, options]);

const result = picomatch.scan('!./foo/*.js');
console.log(result);
{ prefix: '!./',
  input: '!./foo/*.js',
  start: 3,
  base: 'foo',
  glob: '*.js',
  isBrace: false,
  isBracket: false,
  isGlob: true,
  isExtglob: false,
  isGlobstar: false,
  negated: true }
```

### [.compileRe](lib/picomatch.js#L245)

Compile a regular expression from the `state` object returned by the
[parse()](#parse) method.

**Params**

* `state` **{Object}**
* `options` **{Object}**
* `returnOutput` **{Boolean}**: Intended for implementors, this argument allows you to return the raw output from the parser.
* `returnState` **{Boolean}**: Adds the state to a `state` property on the returned regex. Useful for implementors and debugging.
* `returns` **{RegExp}**

### [.makeRe](lib/picomatch.js#L286)

Create a regular expression from a parsed glob pattern.

**Params**

* `state` **{String}**: The object returned from the `.parse` method.
* `options` **{Object}**
* `returnOutput` **{Boolean}**: Implementors may use this argument to return the compiled output, instead of a regular expression. This is not exposed on the options to prevent end-users from mutating the result.
* `returnState` **{Boolean}**: Implementors may use this argument to return the state from the parsed glob with the returned regular expression.
* `returns` **{RegExp}**: Returns a regex created from the given pattern.

**Example**

```js
const picomatch = require('picomatch');
const state = picomatch.parse('*.js');
// picomatch.compileRe(state[, options]);

console.log(picomatch.compileRe(state));
//=> /^(?:(?!\.)(?=.)[^/]*?\.js)$/
```

### [.toRegex](lib/picomatch.js#L321)

Create a regular expression from the given regex source string.

**Params**

* `source` **{String}**: Regular expression source string.
* `options` **{Object}**
* `returns` **{RegExp}**

**Example**

```js
const picomatch = require('picomatch');
// picomatch.toRegex(source[, options]);

const { output } = picomatch.parse('*.js');
console.log(picomatch.toRegex(output));
//=> /^(?:(?!\.)(?=.)[^/]*?\.js)$/
```

<br>

## Options

### Picomatch options

The following options may be used with the main `picomatch()` function or any of the methods on the picomatch API.

| **Option** | **Type** | **Default value** | **Description** |
| --- | --- | --- | --- |
| `basename`            | `boolean`      | `false`     | If set, then patterns without slashes will be matched against the basename of the path if it contains slashes.  For example, `a?b` would match the path `/xyz/123/acb`, but not `/xyz/acb/123`. |
| `bash`                | `boolean`      | `false`     | Follow bash matching rules more strictly - disallows backslashes as escape characters, and treats single stars as globstars (`**`). |
| `capture`             | `boolean`      | `undefined` | Return regex matches in supporting methods. |
| `contains`            | `boolean`      | `undefined` | Allows glob to match any part of the given string(s). |
| `cwd`                 | `string`       | `process.cwd()` | Current working directory. Used by `picomatch.split()` |
| `debug`               | `boolean`      | `undefined` | Debug regular expressions when an error is thrown. |
| `dot`                 | `boolean`      | `false`     | Enable dotfile matching. By default, dotfiles are ignored unless a `.` is explicitly defined in the pattern, or `options.dot` is true |
| `expandRange`         | `function`     | `undefined` | Custom function for expanding ranges in brace patterns, such as `{a..z}`. The function receives the range values as two arguments, and it must return a string to be used in the generated regex. It's recommended that returned strings be wrapped in parentheses. |
| `failglob`            | `boolean`      | `false`     | Throws an error if no matches are found. Based on the bash option of the same name. |
| `fastpaths`           | `boolean`      | `true`      | To speed up processing, full parsing is skipped for a handful common glob patterns. Disable this behavior by setting this option to `false`. |
| `flags`               | `string`      | `undefined` | Regex flags to use in the generated regex. If defined, the `nocase` option will be overridden. |
| [format](#optionsformat) | `function` | `undefined` | Custom function for formatting the returned string. This is useful for removing leading slashes, converting Windows paths to Posix paths, etc. |
| `ignore`              | `array\|string` | `undefined` | One or more glob patterns for excluding strings that should not be matched from the result. |
| `keepQuotes`          | `boolean`      | `false`     | Retain quotes in the generated regex, since quotes may also be used as an alternative to backslashes.  |
| `literalBrackets`     | `boolean`      | `undefined` | When `true`, brackets in the glob pattern will be escaped so that only literal brackets will be matched. |
| `matchBase`           | `boolean`      | `false`     | Alias for `basename` |
| `maxLength`           | `boolean`      | `65536`     | Limit the max length of the input string. An error is thrown if the input string is longer than this value. |
| `nobrace`             | `boolean`      | `false`     | Disable brace matching, so that `{a,b}` and `{1..3}` would be treated as literal characters. |
| `nobracket`           | `boolean`      | `undefined` | Disable matching with regex brackets. |
| `nocase`              | `boolean`      | `false`     | Make matching case-insensitive. Equivalent to the regex `i` flag. Note that this option is overridden by the `flags` option. |
| `nodupes`             | `boolean`      | `true`      | Deprecated, use `nounique` instead. This option will be removed in a future major release. By default duplicates are removed. Disable uniquification by setting this option to false. |
| `noext`               | `boolean`      | `false`     | Alias for `noextglob` |
| `noextglob`           | `boolean`      | `false`     | Disable support for matching with extglobs (like `+(a\|b)`) |
| `noglobstar`          | `boolean`      | `false`     | Disable support for matching nested directories with globstars (`**`) |
| `nonegate`            | `boolean`      | `false`     | Disable support for negating with leading `!` |
| `noquantifiers`       | `boolean`      | `false`     | Disable support for regex quantifiers (like `a{1,2}`) and treat them as brace patterns to be expanded. |
| [onIgnore](#optionsonIgnore) | `function` | `undefined` | Function to be called on ignored items. |
| [onMatch](#optionsonMatch) | `function` | `undefined` | Function to be called on matched items. |
| [onResult](#optionsonResult) | `function` | `undefined` | Function to be called on all items, regardless of whether or not they are matched or ignored. |
| `posix`               | `boolean`      | `false`     | Support POSIX character classes ("posix brackets"). |
| `posixSlashes`        | `boolean`      | `undefined` | Convert all slashes in file paths to forward slashes. This does not convert slashes in the glob pattern itself |
| `prepend`             | `boolean`      | `undefined` | String to prepend to the generated regex used for matching. |
| `regex`               | `boolean`      | `false`     | Use regular expression rules for `+` (instead of matching literal `+`), and for stars that follow closing parentheses or brackets (as in `)*` and `]*`). |
| `strictBrackets`      | `boolean`      | `undefined` | Throw an error if brackets, braces, or parens are imbalanced. |
| `strictSlashes`       | `boolean`      | `undefined` | When true, picomatch won't match trailing slashes with single stars. |
| `unescape`            | `boolean`      | `undefined` | Remove backslashes preceding escaped characters in the glob pattern. By default, backslashes are retained. |
| `unixify`             | `boolean`      | `undefined` | Alias for `posixSlashes`, for backwards compatibility. |

picomatch has automatic detection for regex positive and negative lookbehinds. If the pattern contains a negative lookbehind, you must be using Node.js >= 8.10 or else picomatch will throw an error.

### Scan Options

In addition to the main [picomatch options](#picomatch-options), the following options may also be used with the [.scan](#scan) method.

| **Option** | **Type** | **Default value** | **Description** |
| --- | --- | --- | --- |
| `tokens` | `boolean` | `false` | When `true`, the returned object will include an array of tokens (objects), representing each path "segment" in the scanned glob pattern |
| `parts` | `boolean` | `false` | When `true`, the returned object will include an array of strings representing each path "segment" in the scanned glob pattern. This is automatically enabled when `options.tokens` is true |

**Example**

```js
const picomatch = require('picomatch');
const result = picomatch.scan('!./foo/*.js', { tokens: true });
console.log(result);
// {
//   prefix: '!./',
//   input: '!./foo/*.js',
//   start: 3,
//   base: 'foo',
//   glob: '*.js',
//   isBrace: false,
//   isBracket: false,
//   isGlob: true,
//   isExtglob: false,
//   isGlobstar: false,
//   negated: true,
//   maxDepth: 2,
//   tokens: [
//     { value: '!./', depth: 0, isGlob: false, negated: true, isPrefix: true },
//     { value: 'foo', depth: 1, isGlob: false },
//     { value: '*.js', depth: 1, isGlob: true }
//   ],
//   slashes: [ 2, 6 ],
//   parts: [ 'foo', '*.js' ]
// }
```

<br>

### Options Examples

#### options.expandRange

**Type**: `function`

**Default**: `undefined`

Custom function for expanding ranges in brace patterns. The [fill-range](https://github.com/jonschlinkert/fill-range) library is ideal for this purpose, or you can use custom code to do whatever you need.

**Example**

The following example shows how to create a glob that matches a folder

```js
const fill = require('fill-range');
const regex = pm.makeRe('foo/{01..25}/bar', {
  expandRange(a, b) {
    return `(${fill(a, b, { toRegex: true })})`;
  }
});

console.log(regex);
//=> /^(?:foo\/((?:0[1-9]|1[0-9]|2[0-5]))\/bar)$/

console.log(regex.test('foo/00/bar'))  // false
console.log(regex.test('foo/01/bar'))  // true
console.log(regex.test('foo/10/bar')) // true
console.log(regex.test('foo/22/bar')) // true
console.log(regex.test('foo/25/bar')) // true
console.log(regex.test('foo/26/bar')) // false
```

#### options.format

**Type**: `function`

**Default**: `undefined`

Custom function for formatting strings before they're matched.

**Example**

```js
// strip leading './' from strings
const format = str => str.replace(/^\.\//, '');
const isMatch = picomatch('foo/*.js', { format });
console.log(isMatch('./foo/bar.js')); //=> true
```

#### options.onMatch

```js
const onMatch = ({ glob, regex, input, output }) => {
  console.log({ glob, regex, input, output });
};

const isMatch = picomatch('*', { onMatch });
isMatch('foo');
isMatch('bar');
isMatch('baz');
```

#### options.onIgnore

```js
const onIgnore = ({ glob, regex, input, output }) => {
  console.log({ glob, regex, input, output });
};

const isMatch = picomatch('*', { onIgnore, ignore: 'f*' });
isMatch('foo');
isMatch('bar');
isMatch('baz');
```

#### options.onResult

```js
const onResult = ({ glob, regex, input, output }) => {
  console.log({ glob, regex, input, output });
};

const isMatch = picomatch('*', { onResult, ignore: 'f*' });
isMatch('foo');
isMatch('bar');
isMatch('baz');
```

<br>
<br>

## Globbing features

* [Basic globbing](#basic-globbing) (Wildcard matching)
* [Advanced globbing](#advanced-globbing) (extglobs, posix brackets, brace matching)

### Basic globbing

| **Character** | **Description** |
| --- | --- |
| `*` | Matches any character zero or more times, excluding path separators. Does _not match_ path separators or hidden files or directories ("dotfiles"), unless explicitly enabled by setting the `dot` option to `true`. |
| `**` | Matches any character zero or more times, including path separators. Note that `**` will only match path separators (`/`, and `\\` on Windows) when they are the only characters in a path segment. Thus, `foo**/bar` is equivalent to `foo*/bar`, and `foo/a**b/bar` is equivalent to `foo/a*b/bar`, and _more than two_ consecutive stars in a glob path segment are regarded as _a single star_. Thus, `foo/***/bar` is equivalent to `foo/*/bar`. |
| `?` | Matches any character excluding path separators one time. Does _not match_ path separators or leading dots.  |
| `[abc]` | Matches any characters inside the brackets. For example, `[abc]` would match the characters `a`, `b` or `c`, and nothing else. |

#### Matching behavior vs. Bash

Picomatch's matching features and expected results in unit tests are based on Bash's unit tests and the Bash 4.3 specification, with the following exceptions:

* Bash will match `foo/bar/baz` with `*`. Picomatch only matches nested directories with `**`.
* Bash greedily matches with negated extglobs. For example, Bash 4.3 says that `!(foo)*` should match `foo` and `foobar`, since the trailing `*` bracktracks to match the preceding pattern. This is very memory-inefficient, and IMHO, also incorrect. Picomatch would return `false` for both `foo` and `foobar`.

<br>

### Advanced globbing

* [extglobs](#extglobs)
* [POSIX brackets](#posix-brackets)
* [Braces](#brace-expansion)

#### Extglobs

| **Pattern** | **Description** |
| --- | --- |
| `@(pattern)` | Match _only one_ consecutive occurrence of `pattern` |
| `*(pattern)` | Match _zero or more_ consecutive occurrences of `pattern` |
| `+(pattern)` | Match _one or more_ consecutive occurrences of `pattern` |
| `?(pattern)` | Match _zero or **one**_ consecutive occurrences of `pattern` |
| `!(pattern)` | Match _anything but_ `pattern` |

**Examples**

```js
const pm = require('picomatch');

// *(pattern) matches ZERO or more of "pattern"
console.log(pm.isMatch('a', 'a*(z)')); // true
console.log(pm.isMatch('az', 'a*(z)')); // true
console.log(pm.isMatch('azzz', 'a*(z)')); // true

// +(pattern) matches ONE or more of "pattern"
console.log(pm.isMatch('a', 'a*(z)')); // true
console.log(pm.isMatch('az', 'a*(z)')); // true
console.log(pm.isMatch('azzz', 'a*(z)')); // true

// supports multiple extglobs
console.log(pm.isMatch('foo.bar', '!(foo).!(bar)')); // false

// supports nested extglobs
console.log(pm.isMatch('foo.bar', '!(!(foo)).!(!(bar))')); // true
```

#### POSIX brackets

POSIX classes are disabled by default. Enable this feature by setting the `posix` option to true.

**Enable POSIX bracket support**

```js
console.log(pm.makeRe('[[:word:]]+', { posix: true }));
//=> /^(?:(?=.)[A-Za-z0-9_]+\/?)$/
```

**Supported POSIX classes**

The following named POSIX bracket expressions are supported:

* `[:alnum:]` - Alphanumeric characters, equ `[a-zA-Z0-9]`
* `[:alpha:]` - Alphabetical characters, equivalent to `[a-zA-Z]`.
* `[:ascii:]` - ASCII characters, equivalent to `[\\x00-\\x7F]`.
* `[:blank:]` - Space and tab characters, equivalent to `[ \\t]`.
* `[:cntrl:]` - Control characters, equivalent to `[\\x00-\\x1F\\x7F]`.
* `[:digit:]` - Numerical digits, equivalent to `[0-9]`.
* `[:graph:]` - Graph characters, equivalent to `[\\x21-\\x7E]`.
* `[:lower:]` - Lowercase letters, equivalent to `[a-z]`.
* `[:print:]` - Print characters, equivalent to `[\\x20-\\x7E ]`.
* `[:punct:]` - Punctuation and symbols, equivalent to `[\\-!"#$%&\'()\\*+,./:;<=>?@[\\]^_`{|}~]`.
* `[:space:]` - Extended space characters, equivalent to `[ \\t\\r\\n\\v\\f]`.
* `[:upper:]` - Uppercase letters, equivalent to `[A-Z]`.
* `[:word:]` -  Word characters (letters, numbers and underscores), equivalent to `[A-Za-z0-9_]`.
* `[:xdigit:]` - Hexadecimal digits, equivalent to `[A-Fa-f0-9]`.

See the [Bash Reference Manual](https://www.gnu.org/software/bash/manual/html_node/Pattern-Matching.html) for more information.

### Braces

Picomatch does not do brace expansion. For [brace expansion](https://www.gnu.org/software/bash/manual/html_node/Brace-Expansion.html) and advanced matching with braces, use [micromatch](https://github.com/micromatch/micromatch) instead. Picomatch has very basic support for braces.

### Matching special characters as literals

If you wish to match the following special characters in a filepath, and you want to use these characters in your glob pattern, they must be escaped with backslashes or quotes:

**Special Characters**

Some characters that are used for matching in regular expressions are also regarded as valid file path characters on some platforms.

To match any of the following characters as literals: `$^*+?()[]

Examples:

```js
console.log(pm.makeRe('foo/bar \\(1\\)'));
console.log(pm.makeRe('foo/bar \\(1\\)'));
```

<br>
<br>

## Library Comparisons

The following table shows which features are supported by [minimatch](https://github.com/isaacs/minimatch), [micromatch](https://github.com/micromatch/micromatch), [picomatch](https://github.com/micromatch/picomatch), [nanomatch](https://github.com/micromatch/nanomatch), [extglob](https://github.com/micromatch/extglob), [braces](https://github.com/micromatch/braces), and [expand-brackets](https://github.com/micromatch/expand-brackets).

| **Feature** | `minimatch` | `micromatch` | `picomatch` | `nanomatch` | `extglob` | `braces` | `expand-brackets` |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Wildcard matching (`*?+`) | ✔ | ✔ | ✔ | ✔ | - | - | - |
| Advancing globbing        | ✔ | ✔ | ✔ | - | - | - | - |
| Brace _matching_          | ✔ | ✔ | ✔ | - | - | ✔ | - |
| Brace _expansion_         | ✔ | ✔ | - | - | - | ✔ | - |
| Extglobs                  | partial | ✔ | ✔ | - | ✔ | - | - |
| Posix brackets            | - | ✔ | ✔ | - | - | - | ✔ |
| Regular expression syntax | - | ✔ | ✔ | ✔ | ✔ | - | ✔ |
| File system operations    | - | - | - | - | - | - | - |

<br>
<br>

## Benchmarks

Performance comparison of picomatch and minimatch.

```
# .makeRe star
  picomatch x 1,993,050 ops/sec ±0.51% (91 runs sampled)
  minimatch x 627,206 ops/sec ±1.96% (87 runs sampled))

# .makeRe star; dot=true
  picomatch x 1,436,640 ops/sec ±0.62% (91 runs sampled)
  minimatch x 525,876 ops/sec ±0.60% (88 runs sampled)

# .makeRe globstar
  picomatch x 1,592,742 ops/sec ±0.42% (90 runs sampled)
  minimatch x 962,043 ops/sec ±1.76% (91 runs sampled)d)

# .makeRe globstars
  picomatch x 1,615,199 ops/sec ±0.35% (94 runs sampled)
  minimatch x 477,179 ops/sec ±1.33% (91 runs sampled)

# .makeRe with leading star
  picomatch x 1,220,856 ops/sec ±0.40% (92 runs sampled)
  minimatch x 453,564 ops/sec ±1.43% (94 runs sampled)

# .makeRe - basic braces
  picomatch x 392,067 ops/sec ±0.70% (90 runs sampled)
  minimatch x 99,532 ops/sec ±2.03% (87 runs sampled))
```

<br>
<br>

## Philosophies

The goal of this library is to be blazing fast, without compromising on accuracy.

**Accuracy**

The number one of goal of this library is accuracy. However, it's not unusual for different glob implementations to have different rules for matching behavior, even with simple wildcard matching. It gets increasingly more complicated when combinations of different features are combined, like when extglobs are combined with globstars, braces, slashes, and so on: `!(**/{a,b,*/c})`.

Thus, given that there is no canonical glob specification to use as a single source of truth when differences of opinion arise regarding behavior, sometimes we have to implement our best judgement and rely on feedback from users to make improvements.

**Performance**

Although this library performs well in benchmarks, and in most cases it's faster than other popular libraries we benchmarked against, we will always choose accuracy over performance. It's not helpful to anyone if our library is faster at returning the wrong answer.

<br>
<br>

## About

<details>
<summary><strong>Contributing</strong></summary>

Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).

Please read the [contributing guide](.github/contributing.md) for advice on opening issues, pull requests, and coding standards.

</details>

<details>
<summary><strong>Running Tests</strong></summary>

Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

```sh
npm install && npm test
```

</details>

<details>
<summary><strong>Building docs</strong></summary>

_(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_

To generate the readme, run the following command:

```sh
npm install -g verbose/verb#dev verb-generate-readme && verb
```

</details>

### Author

**Jon Schlinkert**

* [GitHub Profile](https://github.com/jonschlinkert)
* [Twitter Profile](https://twitter.com/jonschlinkert)
* [LinkedIn Profile](https://linkedin.com/in/jonschlinkert)

### License

Copyright © 2017-present, [Jon Schlinkert](https://github.com/jonschlinkert).
Released under the [MIT License](LICENSE).


---

# pkg-dir

> Find the root directory of a Node.js project or npm package

## Install

```sh
npm install pkg-dir
```

## Usage

```
/
└── Users
    └── sindresorhus
        └── foo
            ├── package.json
            └── bar
                ├── baz
                └── example.js
```

```js
// example.js
import {packageDirectory} from 'pkg-dir';

console.log(await packageDirectory());
//=> '/Users/sindresorhus/foo'
```

## API

### packageDirectory(option?)

Returns a `Promise` for either the project root path or `undefined` if it could not be found.

### packageDirectorySync(options?)

Returns the project root path or `undefined` if it could not be found.

#### options

Type: `object`

##### cwd

Type: `string`\
Default: `process.cwd()`

The directory to start searching from.

## Related

- [pkg-dir-cli](https://github.com/sindresorhus/pkg-dir-cli) - CLI for this module
- [pkg-up](https://github.com/sindresorhus/pkg-up) - Find the closest package.json file
- [find-up](https://github.com/sindresorhus/find-up) - Find a file by walking up parent directories

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-pkg-dir?utm_source=npm-pkg-dir&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

# find-up [![Build Status: Linux and macOS](https://travis-ci.org/sindresorhus/find-up.svg?branch=master)](https://travis-ci.org/sindresorhus/find-up) [![Build Status: Windows](https://ci.appveyor.com/api/projects/status/l0cyjmvh5lq72vq2/branch/master?svg=true)](https://ci.appveyor.com/project/sindresorhus/find-up/branch/master)

> Find a file or directory by walking up parent directories


## Install

```
$ npm install find-up
```


## Usage

```
/
└── Users
		└── sindresorhus
				├── unicorn.png
				└── foo
						└── bar
								├── baz
								└── example.js
```

`example.js`

```js
const findUp = require('find-up');

(async () => {
	console.log(await findUp('unicorn.png'));
	//=> '/Users/sindresorhus/unicorn.png'

	console.log(await findUp(['rainbow.png', 'unicorn.png']));
	//=> '/Users/sindresorhus/unicorn.png'
})();
```


## API

### findUp(filename, [options])

Returns a `Promise` for either the filepath or `null` if it couldn't be found.

### findUp([filenameA, filenameB], [options])

Returns a `Promise` for either the first filepath found (by respecting the order) or `null` if none could be found.

### findUp.sync(filename, [options])

Returns a filepath or `null`.

### findUp.sync([filenameA, filenameB], [options])

Returns the first filepath found (by respecting the order) or `null`.

#### filename

Type: `string`

Filename of the file to find.

#### options

Type: `Object`

##### cwd

Type: `string`<br>
Default: `process.cwd()`

Directory to start from.


## Related

- [find-up-cli](https://github.com/sindresorhus/find-up-cli) - CLI for this module
- [pkg-up](https://github.com/sindresorhus/pkg-up) - Find the closest package.json file
- [pkg-dir](https://github.com/sindresorhus/pkg-dir) - Find the root directory of an npm package
- [resolve-from](https://github.com/sindresorhus/resolve-from) - Resolve the path of a module like `require.resolve()` but from a given path


## License

MIT © [Sindre Sorhus](https://sindresorhus.com)


---

# locate-path [![Build Status](https://travis-ci.org/sindresorhus/locate-path.svg?branch=master)](https://travis-ci.org/sindresorhus/locate-path)

> Get the first path that exists on disk of multiple paths


## Install

```
$ npm install locate-path
```


## Usage

Here we find the first file that exists on disk, in array order.

```js
const locatePath = require('locate-path');

const files = [
	'unicorn.png',
	'rainbow.png', // Only this one actually exists on disk
	'pony.png'
];

(async () => {
	console(await locatePath(files));
	//=> 'rainbow'
})();
```


## API

### locatePath(input, [options])

Returns a `Promise` for the first path that exists or `undefined` if none exists.

#### input

Type: `Iterable<string>`

Paths to check.

#### options

Type: `Object`

##### concurrency

Type: `number`<br>
Default: `Infinity`<br>
Minimum: `1`

Number of concurrently pending promises.

##### preserveOrder

Type: `boolean`<br>
Default: `true`

Preserve `input` order when searching.

Disable this to improve performance if you don't care about the order.

##### cwd

Type: `string`<br>
Default: `process.cwd()`

Current working directory.

### locatePath.sync(input, [options])

Returns the first path that exists or `undefined` if none exists.

#### input

Type: `Iterable<string>`

Paths to check.

#### options

Type: `Object`

##### cwd

Same as above.


## Related

- [path-exists](https://github.com/sindresorhus/path-exists) - Check if a path exists


## License

MIT © [Sindre Sorhus](https://sindresorhus.com)


---

# p-limit [![Build Status](https://travis-ci.org/sindresorhus/p-limit.svg?branch=master)](https://travis-ci.org/sindresorhus/p-limit)

> Run multiple promise-returning & async functions with limited concurrency

## Install

```
$ npm install p-limit
```

## Usage

```js
const pLimit = require('p-limit');

const limit = pLimit(1);

const input = [
	limit(() => fetchSomething('foo')),
	limit(() => fetchSomething('bar')),
	limit(() => doSomething())
];

(async () => {
	// Only one promise is run at once
	const result = await Promise.all(input);
	console.log(result);
})();
```

## API

### pLimit(concurrency)

Returns a `limit` function.

#### concurrency

Type: `number`\
Minimum: `1`\
Default: `Infinity`

Concurrency limit.

### limit(fn, ...args)

Returns the promise returned by calling `fn(...args)`.

#### fn

Type: `Function`

Promise-returning/async function.

#### args

Any arguments to pass through to `fn`.

Support for passing arguments on to the `fn` is provided in order to be able to avoid creating unnecessary closures. You probably don't need this optimization unless you're pushing a *lot* of functions.

### limit.activeCount

The number of promises that are currently running.

### limit.pendingCount

The number of promises that are waiting to run (i.e. their internal `fn` was not called yet).

### limit.clearQueue()

Discard pending promises that are waiting to run.

This might be useful if you want to teardown the queue at the end of your program's lifecycle or discard any function calls referencing an intermediary state of your app.

Note: This does not cancel promises that are already running.

## FAQ

### How is this different from the [`p-queue`](https://github.com/sindresorhus/p-queue) package?

This package is only about limiting the number of concurrent executions, while `p-queue` is a fully featured queue implementation with lots of different options, introspection, and ability to pause the queue.

## Related

- [p-queue](https://github.com/sindresorhus/p-queue) - Promise queue with concurrency control
- [p-throttle](https://github.com/sindresorhus/p-throttle) - Throttle promise-returning & async functions
- [p-debounce](https://github.com/sindresorhus/p-debounce) - Debounce promise-returning & async functions
- [p-all](https://github.com/sindresorhus/p-all) - Run promise-returning & async functions concurrently with optional limited concurrency
- [More…](https://github.com/sindresorhus/promise-fun)

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-p-limit?utm_source=npm-p-limit&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

# p-locate [![Build Status](https://travis-ci.org/sindresorhus/p-locate.svg?branch=master)](https://travis-ci.org/sindresorhus/p-locate)

> Get the first fulfilled promise that satisfies the provided testing function

Think of it like an async version of [`Array#find`](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Array/find).


## Install

```
$ npm install p-locate
```


## Usage

Here we find the first file that exists on disk, in array order.

```js
const pathExists = require('path-exists');
const pLocate = require('p-locate');

const files = [
	'unicorn.png',
	'rainbow.png', // Only this one actually exists on disk
	'pony.png'
];

(async () => {
	const foundPath = await pLocate(files, file => pathExists(file));

	console.log(foundPath);
	//=> 'rainbow'
})();
```

*The above is just an example. Use [`locate-path`](https://github.com/sindresorhus/locate-path) if you need this.*


## API

### pLocate(input, tester, [options])

Returns a `Promise` that is fulfilled when `tester` resolves to `true` or the iterable is done, or rejects if any of the promises reject. The fulfilled value is the current iterable value or `undefined` if `tester` never resolved to `true`.

#### input

Type: `Iterable<Promise|any>`

#### tester(element)

Type: `Function`

Expected to return a `Promise<boolean>` or boolean.

#### options

Type: `Object`

##### concurrency

Type: `number`<br>
Default: `Infinity`<br>
Minimum: `1`

Number of concurrently pending promises returned by `tester`.

##### preserveOrder

Type: `boolean`<br>
Default: `true`

Preserve `input` order when searching.

Disable this to improve performance if you don't care about the order.


## Related

- [p-map](https://github.com/sindresorhus/p-map) - Map over promises concurrently
- [p-filter](https://github.com/sindresorhus/p-filter) - Filter promises concurrently
- [p-any](https://github.com/sindresorhus/p-any) - Wait for any promise to be fulfilled
- [More…](https://github.com/sindresorhus/promise-fun)


## License

MIT © [Sindre Sorhus](https://sindresorhus.com)


---

# path-exists [![Build Status](https://travis-ci.org/sindresorhus/path-exists.svg?branch=master)](https://travis-ci.org/sindresorhus/path-exists)

> Check if a path exists

Because [`fs.exists()`](https://nodejs.org/api/fs.html#fs_fs_exists_path_callback) is being [deprecated](https://github.com/iojs/io.js/issues/103), but there's still a genuine use-case of being able to check if a path exists for other purposes than doing IO with it.

Never use this before handling a file though:

> In particular, checking if a file exists before opening it is an anti-pattern that leaves you vulnerable to race conditions: another process may remove the file between the calls to `fs.exists()` and `fs.open()`. Just open the file and handle the error when it's not there.


## Install

```
$ npm install --save path-exists
```


## Usage

```js
// foo.js
const pathExists = require('path-exists');

pathExists('foo.js').then(exists => {
	console.log(exists);
	//=> true
});
```


## API

### pathExists(path)

Returns a promise for a boolean of whether the path exists.

### pathExists.sync(path)

Returns a boolean of whether the path exists.


## Related

- [path-exists-cli](https://github.com/sindresorhus/path-exists-cli) - CLI for this module


## License

MIT © [Sindre Sorhus](https://sindresorhus.com)


---

# pkg-up [![Build Status](https://travis-ci.org/sindresorhus/pkg-up.svg?branch=master)](https://travis-ci.org/sindresorhus/pkg-up)

> Find the closest package.json file


## Install

```
$ npm install pkg-up
```


## Usage

```
/
└── Users
    └── sindresorhus
        └── foo
            ├── package.json
            └── bar
                ├── baz
                └── example.js
```

```js
// example.js
const pkgUp = require('pkg-up');

(async () => {
	console.log(await pkgUp());
	//=> '/Users/sindresorhus/foo/package.json'
})();
```


## API

### pkgUp([options])

Returns a `Promise<string>` for the filepath, or `Promise<null>` if it couldn't be found.

### pkgUp.sync([options])

Returns the filepath, or `null` if it couldn't be found.

#### options

Type: `Object`

#### cwd

Type: `string`<br>
Default: `process.cwd()`

Directory to start from.


## Related

- [read-pkg-up](https://github.com/sindresorhus/read-pkg-up) - Read the closest package.json file
- [pkg-dir](https://github.com/sindresorhus/pkg-dir) - Find the root directory of an npm package
- [find-up](https://github.com/sindresorhus/find-up) - Find a file by walking up parent directories


## License

MIT © [Sindre Sorhus](https://sindresorhus.com)


---

# PostCSS

<img align="right" width="95" height="95"
     alt="Philosopher’s stone, logo of PostCSS"
     src="https://postcss.org/logo.svg">

PostCSS is a tool for transforming styles with JS plugins.
These plugins can lint your CSS, support variables and mixins,
transpile future CSS syntax, inline images, and more.

PostCSS is used by industry leaders including Wikipedia, Twitter, Alibaba,
and JetBrains. The [Autoprefixer] and [Stylelint] PostCSS plugins is one of the most popular CSS tools.

---

<img src="https://cdn.evilmartians.com/badges/logo-no-label.svg" alt="" width="22" height="16" />  Made at <b><a href="https://evilmartians.com/devtools?utm_source=postcss&utm_campaign=devtools-button&utm_medium=github">Evil Martians</a></b>, product consulting for <b>developer tools</b>.

---

[Abstract Syntax Tree]: https://en.wikipedia.org/wiki/Abstract_syntax_tree
[Evil Martians]:        https://evilmartians.com/?utm_source=postcss
[Autoprefixer]:         https://github.com/postcss/autoprefixer
[Stylelint]:            https://stylelint.io/
[plugins]:              https://github.com/postcss/postcss#plugins


## Docs
Read full docs **[here](https://postcss.org/)**.


---

# Changes to PostCSS Attribute Case Insensitive

### 7.0.1

_October 23, 2024_

- Updated: `postcss-selector-parser`

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-attribute-case-insensitive/CHANGELOG.md)


---

The MIT License (MIT)

Copyright 2020 Dmitry Semigradsky <semigradskyd@gmail.com>

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


---

# PostCSS Attribute Case Insensitive [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install postcss-attribute-case-insensitive --save-dev`

[PostCSS Attribute Case Insensitive] enables support for [Case Insensitive Attribute] matching in selectors.

```pcss
[frame=hsides i] {
	border-style: solid none;
}

/* becomes */

[frame=hsides],[frame=Hsides],[frame=hSides],[frame=HSides],[frame=hsIdes],[frame=HsIdes],[frame=hSIdes],[frame=HSIdes],[frame=hsiDes],[frame=HsiDes],[frame=hSiDes],[frame=HSiDes],[frame=hsIDes],[frame=HsIDes],[frame=hSIDes],[frame=HSIDes],[frame=hsidEs],[frame=HsidEs],[frame=hSidEs],[frame=HSidEs],[frame=hsIdEs],[frame=HsIdEs],[frame=hSIdEs],[frame=HSIdEs],[frame=hsiDEs],[frame=HsiDEs],[frame=hSiDEs],[frame=HSiDEs],[frame=hsIDEs],[frame=HsIDEs],[frame=hSIDEs],[frame=HSIDEs],[frame=hsideS],[frame=HsideS],[frame=hSideS],[frame=HSideS],[frame=hsIdeS],[frame=HsIdeS],[frame=hSIdeS],[frame=HSIdeS],[frame=hsiDeS],[frame=HsiDeS],[frame=hSiDeS],[frame=HSiDeS],[frame=hsIDeS],[frame=HsIDeS],[frame=hSIDeS],[frame=HSIDeS],[frame=hsidES],[frame=HsidES],[frame=hSidES],[frame=HSidES],[frame=hsIdES],[frame=HsIdES],[frame=hSIdES],[frame=HSIdES],[frame=hsiDES],[frame=HsiDES],[frame=hSiDES],[frame=HSiDES],[frame=hsIDES],[frame=HsIDES],[frame=hSIDES],[frame=HSIDES] {
	border-style: solid none;
}
```

## Usage

Add [PostCSS Attribute Case Insensitive] to your project:

```bash
npm install postcss postcss-attribute-case-insensitive --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssAttributeCaseInsensitive = require('postcss-attribute-case-insensitive');

postcss([
	postcssAttributeCaseInsensitive(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## Options

### preserve

The `preserve` option determines whether the original notation
is preserved. By default, it is not preserved.

```js
postcssAttributeCaseInsensitive({ preserve: true })
```

```pcss
[frame=hsides i] {
	border-style: solid none;
}

/* becomes */

[frame=hsides],[frame=Hsides],[frame=hSides],[frame=HSides],[frame=hsIdes],[frame=HsIdes],[frame=hSIdes],[frame=HSIdes],[frame=hsiDes],[frame=HsiDes],[frame=hSiDes],[frame=HSiDes],[frame=hsIDes],[frame=HsIDes],[frame=hSIDes],[frame=HSIDes],[frame=hsidEs],[frame=HsidEs],[frame=hSidEs],[frame=HSidEs],[frame=hsIdEs],[frame=HsIdEs],[frame=hSIdEs],[frame=HSIdEs],[frame=hsiDEs],[frame=HsiDEs],[frame=hSiDEs],[frame=HSiDEs],[frame=hsIDEs],[frame=HsIDEs],[frame=hSIDEs],[frame=HSIDEs],[frame=hsideS],[frame=HsideS],[frame=hSideS],[frame=HSideS],[frame=hsIdeS],[frame=HsIdeS],[frame=hSIdeS],[frame=HSIdeS],[frame=hsiDeS],[frame=HsiDeS],[frame=hSiDeS],[frame=HSiDeS],[frame=hsIDeS],[frame=HsIDeS],[frame=hSIDeS],[frame=HSIDeS],[frame=hsidES],[frame=HsidES],[frame=hSidES],[frame=HSidES],[frame=hsIdES],[frame=HsIdES],[frame=hSIdES],[frame=HSIdES],[frame=hsiDES],[frame=HsiDES],[frame=hSiDES],[frame=HSiDES],[frame=hsIDES],[frame=HsIDES],[frame=hSIDES],[frame=HSIDES] {
	border-style: solid none;
}
[frame=hsides i] {
	border-style: solid none;
}
```

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#case-insensitive-attributes
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/postcss-attribute-case-insensitive

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Attribute Case Insensitive]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-attribute-case-insensitive
[Case Insensitive Attribute]: https://www.w3.org/TR/selectors4/#attribute-case


---

# API Documentation

*Please use only this documented API when working with the parser. Methods
not documented here are subject to change at any point.*

## `parser` function

This is the module's main entry point.

```js
const parser = require('postcss-selector-parser');
```

### `parser([transform], [options])`

Creates a new `processor` instance

```js
const processor = parser();
```

Or, with optional transform function

```js
const transform = selectors => {
    selectors.walkUniversals(selector => {
        selector.remove();
    });
};

const processor = parser(transform)

// Example
const result = processor.processSync('*.class');
// => .class
```

[See processor documentation](#processor)

Arguments:

* `transform (function)`: Provide a function to work with the parsed AST.
* `options (object)`: Provide default options for all calls on the returned `Processor`.

### `parser.attribute([props])`

Creates a new attribute selector.

```js
parser.attribute({attribute: 'href'});
// => [href]
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.className([props])`

Creates a new class selector.

```js
parser.className({value: 'button'});
// => .button
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.combinator([props])`

Creates a new selector combinator.

```js
parser.combinator({value: '+'});
// => +
```

Arguments:

* `props (object)`: The new node's properties.

Notes:
* **Descendant Combinators** The value of descendant combinators created by the
  parser always just a single space (`" "`). For descendant selectors with no
  comments, additional space is now stored in `node.spaces.before`. Depending
  on the location of comments, additional spaces may be stored in
  `node.raws.spaces.before`, `node.raws.spaces.after`, or `node.raws.value`.
* **Named Combinators** Although, nonstandard and unlikely to ever become a standard,
  named combinators like `/deep/` and `/for/` are parsed as combinators. The
  `node.value` is name after being unescaped and normalized as lowercase. The
  original value for the combinator name is stored in `node.raws.value`.


### `parser.comment([props])`

Creates a new comment.

```js
parser.comment({value: '/* Affirmative, Dave. I read you. */'});
// => /* Affirmative, Dave. I read you. */
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.id([props])`

Creates a new id selector.

```js
parser.id({value: 'search'});
// => #search
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.nesting([props])`

Creates a new nesting selector.

```js
parser.nesting();
// => &
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.pseudo([props])`

Creates a new pseudo selector.

```js
parser.pseudo({value: '::before'});
// => ::before
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.root([props])`

Creates a new root node.

```js
parser.root();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.selector([props])`

Creates a new selector node.

```js
parser.selector();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.string([props])`

Creates a new string node.

```js
parser.string();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.tag([props])`

Creates a new tag selector.

```js
parser.tag({value: 'button'});
// => button
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.universal([props])`

Creates a new universal selector.

```js
parser.universal();
// => *
```

Arguments:

* `props (object)`: The new node's properties.

## Node types

### `node.type`

A string representation of the selector type. It can be one of the following;
`attribute`, `class`, `combinator`, `comment`, `id`, `nesting`, `pseudo`,
`root`, `selector`, `string`, `tag`, or `universal`. Note that for convenience,
these constants are exposed on the main `parser` as uppercased keys. So for
example you can get `id` by querying `parser.ID`.

```js
parser.attribute({attribute: 'href'}).type;
// => 'attribute'
```

### `node.parent`

Returns the parent node.

```js
root.nodes[0].parent === root;
```

### `node.toString()`, `String(node)`, or `'' + node`

Returns a string representation of the node.

```js
const id = parser.id({value: 'search'});
console.log(String(id));
// => #search
```

### `node.next()` & `node.prev()`

Returns the next/previous child of the parent node.

```js
const next = id.next();
if (next && next.type !== 'combinator') {
    throw new Error('Qualified IDs are not allowed!');
}
```

### `node.replaceWith(node[,...nodeN])`

Replace a node with another.

```js
const attr = selectors.first.first;
const className = parser.className({value: 'test'});
attr.replaceWith(className);
```

Arguments:

* `node`: The node to substitute the original with.
...
* `nodeN`: The node to substitute the original with.

### `node.remove()`

Removes the node from its parent node.

```js
if (node.type === 'id') {
    node.remove();
}
```

### `node.clone([opts])`

Returns a copy of a node, detached from any parent containers that the
original might have had.

```js
const cloned = node.clone();
```

### `node.isAtPosition(line, column)`

Return a `boolean` indicating whether this node includes the character at the
position of the given line and column. Returns `undefined` if the nodes lack
sufficient source metadata to determine the position.

Arguments:

* `line`: 1-index based line number relative to the start of the selector.
* `column`: 1-index based column number relative to the start of the selector.

### `node.spaces`

Extra whitespaces around the node will be moved into `node.spaces.before` and
`node.spaces.after`. So for example, these spaces will be moved as they have
no semantic meaning:

```css
      h1     ,     h2   {}
```

For descendent selectors, the value is always a single space.

```css
h1        h2 {}
```

Additional whitespace is found in either the `node.spaces.before` and `node.spaces.after` depending on the presence of comments or other whitespace characters. If the actual whitespace does not start or end with a single space, the node's raw value is set to the actual space(s) found in the source.

### `node.source`

An object describing the node's start/end, line/column source position.

Within the following CSS, the `.bar` class node ...

```css
.foo,
  .bar {}
```

... will contain the following `source` object.

```js
source: {
    start: {
        line: 2,
        column: 3
    },
    end: {
        line: 2,
        column: 6
    }
}
```

### `node.sourceIndex`

The zero-based index of the node within the original source string.

Within the following CSS, the `.baz` class node will have a `sourceIndex` of `12`.

```css
.foo, .bar, .baz {}
```

## Container types

The `root`, `selector`, and `pseudo` nodes have some helper methods for working
with their children.

### `container.nodes`

An array of the container's children.

```js
// Input: h1 h2
selectors.at(0).nodes.length   // => 3
selectors.at(0).nodes[0].value // => 'h1'
selectors.at(0).nodes[1].value // => ' '
```

### `container.first` & `container.last`

The first/last child of the container.

```js
selector.first === selector.nodes[0];
selector.last === selector.nodes[selector.nodes.length - 1];
```

### `container.at(index)`

Returns the node at position `index`.

```js
selector.at(0) === selector.first;
selector.at(0) === selector.nodes[0];
```

Arguments:

* `index`: The index of the node to return.

### `container.atPosition(line, column)`

Returns the node at the source position `line` and `column`.

```js
// Input: :not(.foo),\n#foo > :matches(ol, ul)
selector.atPosition(1, 1); // => :not(.foo)
selector.atPosition(2, 1); // => \n#foo
```

Arguments:

* `line`: The line number of the node to return.
* `column`: The column number of the node to return.

### `container.index(node)`

Return the index of the node within its container.

```js
selector.index(selector.nodes[2]) // => 2
```

Arguments:

* `node`: A node within the current container.

### `container.length`

Proxy to the length of the container's nodes.

```js
container.length === container.nodes.length
```

### `container` Array iterators

The container class provides proxies to certain Array methods; these are:

* `container.map === container.nodes.map`
* `container.reduce === container.nodes.reduce`
* `container.every === container.nodes.every`
* `container.some === container.nodes.some`
* `container.filter === container.nodes.filter`
* `container.sort === container.nodes.sort`

Note that these methods only work on a container's immediate children; recursive
iteration is provided by `container.walk`.

### `container.each(callback)`

Iterate the container's immediate children, calling `callback` for each child.
You may return `false` within the callback to break the iteration.

```js
let className;
selectors.each((selector, index) => {
    if (selector.type === 'class') {
        className = selector.value;
        return false;
    }
});
```

Note that unlike `Array#forEach()`, this iterator is safe to use whilst adding
or removing nodes from the container.

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  and `index` arguments.

### `container.walk(callback)`

Like `container#each`, but will also iterate child nodes as long as they are
`container` types.

```js
selectors.walk((selector, index) => {
    // all nodes
});
```

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  and `index` arguments.

This iterator is safe to use whilst mutating `container.nodes`,
like `container#each`.

### `container.walk` proxies

The container class provides proxy methods for iterating over types of nodes,
so that it is easier to write modules that target specific selectors. Those
methods are:

* `container.walkAttributes`
* `container.walkClasses`
* `container.walkCombinators`
* `container.walkComments`
* `container.walkIds`
* `container.walkNesting`
* `container.walkPseudos`
* `container.walkTags`
* `container.walkUniversals`

### `container.split(callback)`

This method allows you to split a group of nodes by returning `true` from
a callback. It returns an array of arrays, where each inner array corresponds
to the groups that you created via the callback.

```js
// (input) => h1 h2>>h3
const list = selectors.first.split(selector => {
    return selector.type === 'combinator';
});

// (node values) => [['h1', ' '], ['h2', '>>'], ['h3']]
```

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  as an argument.

### `container.prepend(node)` & `container.append(node)`

Add a node to the start/end of the container. Note that doing so will set
the parent property of the node to this container.

```js
const id = parser.id({value: 'search'});
selector.append(id);
```

Arguments:

* `node`: The node to add.

### `container.insertBefore(old, new[, ...newNodes])` & `container.insertAfter(old, new[, ...newNodes])`

Add a node before or after an existing node in a container:

```js
selectors.walk(selector => {
    if (selector.type !== 'class') {
        const className = parser.className({value: 'theme-name'});
        selector.parent.insertAfter(selector, className);
    }
});
```

Arguments:

* `old`: The existing node in the container.
* `new`: The new node to add before/after the existing node.

### `container.removeChild(node)`

Remove the node from the container. Note that you can also use
`node.remove()` if you would like to remove just a single node.

```js
selector.length // => 2
selector.remove(id)
selector.length // => 1;
id.parent       // undefined
```

Arguments:

* `node`: The node to remove.

### `container.removeAll()` or `container.empty()`

Remove all children from the container.

```js
selector.removeAll();
selector.length // => 0
```

## Root nodes

A root node represents a comma separated list of selectors. Indeed, all
a root's `toString()` method does is join its selector children with a ','.
Other than this, it has no special functionality and acts like a container.

### `root.trailingComma`

This will be set to `true` if the input has a trailing comma, in order to
support parsing of legacy CSS hacks.

## Selector nodes

A selector node represents a single complex selector. For example, this
selector string `h1 h2 h3, [href] > p`, is represented as two selector nodes.
It has no special functionality of its own.

## Pseudo nodes

A pseudo selector extends a container node; if it has any parameters of its
own (such as `h1:not(h2, h3)`), they will be its children. Note that the pseudo
`value` will always contain the colons preceding the pseudo identifier. This
is so that both `:before` and `::before` are properly represented in the AST.

## Attribute nodes

### `attribute.quoted`

Returns `true` if the attribute's value is wrapped in quotation marks, false if it is not.
Remains `undefined` if there is no attribute value.

```css
[href=foo] /* false */
[href='foo'] /* true */
[href="foo"] /* true */
[href] /* undefined */
```

### `attribute.qualifiedAttribute`

Returns the attribute name qualified with the namespace if one is given.

### `attribute.offsetOf(part)`

 Returns the offset of the attribute part specified relative to the
 start of the node of the output string. This is useful in raising
 error messages about a specific part of the attribute, especially
 in combination with `attribute.sourceIndex`.

 Returns `-1` if the name is invalid or the value doesn't exist in this
 attribute.

 The legal values for `part` are:

 * `"ns"` - alias for "namespace"
 * `"namespace"` - the namespace if it exists.
 * `"attribute"` - the attribute name
 * `"attributeNS"` - the start of the attribute or its namespace
 * `"operator"` - the match operator of the attribute
 * `"value"` - The value (string or identifier)
 * `"insensitive"` - the case insensitivity flag

### `attribute.raws.unquoted`

Returns the unquoted content of the attribute's value.
Remains `undefined` if there is no attribute value.

```css
[href=foo] /* foo */
[href='foo'] /* foo */
[href="foo"] /* foo */
[href] /* undefined */
```

### `attribute.spaces`

Like `node.spaces` with the `before` and `after` values containing the spaces
around the element, the parts of the attribute can also have spaces before
and after them. The for each of `attribute`, `operator`, `value` and
`insensitive` there is corresponding property of the same nam in
`node.spaces` that has an optional `before` or `after` string containing only
whitespace.

Note that corresponding values in `attributes.raws.spaces` contain values
including any comments. If set, these values will override the
`attribute.spaces` value. Take care to remove them if changing
`attribute.spaces`.

### `attribute.raws`

The raws object stores comments and other information necessary to re-render
the node exactly as it was in the source.

If a comment is embedded within the identifiers for the `namespace`, `attribute`
or `value` then a property is placed in the raws for that value containing the full source of the propery including comments.

If a comment is embedded within the space between parts of the attribute
then the raw for that space is set accordingly.

Setting an attribute's property `raws` value to be deleted.

For now, changing the spaces required also updating or removing any of the
raws values that override them.

Example: `[ /*before*/ href /* after-attr */ = /* after-operator */ te/*inside-value*/st/* wow */ /*omg*/i/*bbq*/ /*whodoesthis*/]` would parse as:

```js
{
  attribute: "href",
  operator: "=",
  value: "test",
  spaces: {
    before: '',
    after: '',
    attribute: { before: '  ', after: '  ' },
    operator: { after: '  ' },
    value: { after: ' ' },
    insensitive: { after: ' ' }
  },
  raws: {
    spaces: {
      attribute: { before: ' /*before*/ ', after: ' /* after-attr */ ' },
      operator: { after: ' /* after-operator */ ' },
      value: { after: '/* wow */ /*omg*/' },
      insensitive: { after: '/*bbq*/ /*whodoesthis*/' }
    },
    unquoted: 'test',
    value: 'te/*inside-value*/st'
  }
}
```

## `Processor`

### `ProcessorOptions`

* `lossless` - When `true`, whitespace is preserved. Defaults to `true`.
* `updateSelector` - When `true`, if any processor methods are passed a postcss
  `Rule` node instead of a string, then that Rule's selector is updated
  with the results of the processing. Defaults to `true`.

### `process|processSync(selectors, [options])`

Processes the `selectors`, returning a string from the result of processing.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

**Example:**

```js
const parser = require("postcss-selector-parser");
const processor = parser();

let result = processor.processSync(' .class');
console.log(result);
// =>  .class

// Asynchronous operation
let promise = processor.process(' .class').then(result => {
    console.log(result)
    // => .class
});

// To have the parser normalize whitespace values, utilize the options
result = processor.processSync('  .class  ', {lossless: false});
console.log(result);
// => .class

// For better syntax errors, pass a PostCSS Rule node.
const postcss = require('postcss');
rule = postcss.rule({selector: ' #foo    > a,  .class  '});
processor.process(rule, {lossless: false, updateSelector: true}).then(result => {
    console.log(result);
    // => #foo>a,.class
    console.log("rule:", rule.selector);
    // => rule: #foo>a,.class
})
```

Arguments:

* `selectors (string|postcss.Rule)`: Either a selector string or a PostCSS Rule
  node.
* `[options] (object)`: Process options


### `ast|astSync(selectors, [options])`

Like `process()` and `processSync()` but after
processing the `selectors` these methods return the `Root` node of the result
instead of a string.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

### `transform|transformSync(selectors, [options])`

Like `process()` and `processSync()` but after
processing the `selectors` these methods return the value returned by the
processor callback.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

### Error Handling Within Selector Processors

The root node passed to the selector processor callback
has a method `error(message, options)` that returns an
error object. This method should always be used to raise
errors relating to the syntax of selectors. The options
to this method are passed to postcss's error constructor
([documentation](http://postcss.org/api/#container-error)).

#### Async Error Example

```js
let processor = (root) => {
    return new Promise((resolve, reject) => {
        root.walkClasses((classNode) => {
            if (/^(.*)[-_]/.test(classNode.value)) {
                let msg = "classes may not have underscores or dashes in them";
                reject(root.error(msg, {
                    index: classNode.sourceIndex + RegExp.$1.length + 1,
                    word: classNode.value
                }));
            }
        });
        resolve();
    });
};

const postcss = require("postcss");
const parser = require("postcss-selector-parser");
const selectorProcessor = parser(processor);
const plugin = postcss.plugin('classValidator', (options) => {
    return (root) => {
        let promises = [];
        root.walkRules(rule => {
            promises.push(selectorProcessor.process(rule));
        });
        return Promise.all(promises);
    };
});
postcss(plugin()).process(`
.foo-bar {
  color: red;
}
`.trim(), {from: 'test.css'}).catch((e) => console.error(e.toString()));

// CssSyntaxError: classValidator: ./test.css:1:5: classes may not have underscores or dashes in them
//
// > 1 | .foo-bar {
//     |     ^
//   2 |   color: red;
//   3 | }
```

#### Synchronous Error Example

```js
let processor = (root) => {
    root.walkClasses((classNode) => {
        if (/.*[-_]/.test(classNode.value)) {
            let msg = "classes may not have underscores or dashes in them";
            throw root.error(msg, {
                index: classNode.sourceIndex,
                word: classNode.value
            });
        }
    });
};

const postcss = require("postcss");
const parser = require("postcss-selector-parser");
const selectorProcessor = parser(processor);
const plugin = postcss.plugin('classValidator', (options) => {
    return (root) => {
        root.walkRules(rule => {
            selectorProcessor.processSync(rule);
        });
    };
});
postcss(plugin()).process(`
.foo-bar {
  color: red;
}
`.trim(), {from: 'test.css'}).catch((e) => console.error(e.toString()));

// CssSyntaxError: classValidator: ./test.css:1:5: classes may not have underscores or dashes in them
//
// > 1 | .foo-bar {
//     |     ^
//   2 |   color: red;
//   3 | }
```


---

# 7.1.0

- feat: insert(Before|After) support multiple new node

# 7.0.0

- Feat: make insertions during iteration safe (major)

# 6.1.2

- Fixed: erroneous trailing combinators in pseudos

# 6.1.1

- Fixed: improve typings of constructor helpers (#292)

# 6.1.0

- Feature: add `sourceIndex` to `Selector` nodes (#290)

# 6.0.16

- Fixed: add missing `index` argument to `each`/`walk` callback types (#289)

# 6.0.15

- Fixed: Node#prev and Node#next type for the first/last node

# 6.0.14

- Fixed: type definitions

# 6.0.13

- Fixed: throw on unexpected pipe symbols

# 6.0.12

- Fixed: `clone` arguments should be optional

# 6.0.11

- Fixed: parse attribute case insensitivity flag

# 6.0.10

- Fixed: `isPseudoElement()` supports `:first-letter` and `:first-line`

# 6.0.9

- Fixed: `Combinator.raws` property type

# 6.0.8

- Fixed: reduced size

# 6.0.7

- Fixed: parse animation percents

# 6.0.6

- Fixed: parse quoted attributes containing a newline correctly

# 6.0.5

- Perf: rework unesc for a 63+% performance boost

# 6.0.4

- Fixed: ts errors

# 6.0.3

- Fixed: replace node built-in "util" module with "util-deprecate"
- Fixed: handle uppercase pseudo elements
- Fixed: do not create invalid combinator before comment

# 6.0.2

- Fixed an issue with parsing and stringifying an empty attribute value

# 6.0.1

- Fixed an issue with unicode surrogate pair parsing

# 6.0.0

- Updated: `cssesc` to 3.0.0 (major)
- Fixed: Issues with escaped `id` and `class` selectors

# 5.0.0

- Allow escaped dot within class name.
- Update PostCSS to 7.0.7 (patch)

# 5.0.0-rc.4

- Fixed an issue where comments immediately after an insensitive (in attribute)
  were not parsed correctly.
- Updated `cssesc` to 2.0.0 (major).
- Removed outdated integration tests.
- Added tests for custom selectors, tags with attributes, the universal
  selector with pseudos, and tokens after combinators.

# 5.0.0-rc.1

To ease adoption of the v5.0 release, we have relaxed the node version
check performed by npm at installation time to allow for node 4, which
remains officially unsupported, but likely to continue working for the
time being.

# 5.0.0-rc.0

This release has **BREAKING CHANGES** that were required to fix regressions
in 4.0.0 and to make the Combinator Node API consistent for all combinator
types. Please read carefully.

## Summary of Changes

* The way a descendent combinator that isn't a single space character (E.g. `.a  .b`) is stored in the AST has changed.
* Named Combinators (E.g. `.a /for/ .b`) are now properly parsed as a combinator.
* It is now possible to look up a node based on the source location of a character in that node and to query nodes if they contain some character.
* Several bug fixes that caused the parser to hang and run out of memory when a `/` was encountered have been fixed.
* The minimum supported version of Node is now `v6.0.0`.

### Changes to the Descendent Combinator

In prior releases, the value of a descendant combinator with multiple spaces included all the spaces.

* `.a   .b`: Extra spaces are now stored as space before.
  - Old & Busted:
    - `combinator.value === "   "`
  - New hotness:
    - `combinator.value === " " && combinator.spaces.before === "  "`
* `.a   /*comment*/.b`: A comment at the end of the combinator causes extra space to become after space.
  - Old & Busted:
    - `combinator.value === "   "`
    - `combinator.raws.value === "   /*comment/"`
  - New hotness:
    - `combinator.value === " "`
    - `combinator.spaces.after === "  "`
    - `combinator.raws.spaces.after === "  /*comment*/"`
* `.a<newline>.b`: whitespace that doesn't start or end with a single space character is stored as a raw value.
  - Old & Busted:
    - `combinator.value === "\n"`
    - `combinator.raws.value === undefined`
  - New hotness:
    - `combinator.value === " "`
    - `combinator.raws.value === "\n"`

### Support for "Named Combinators"

Although, nonstandard and unlikely to ever become a standard, combinators like `/deep/` and `/for/` are now properly supported.

Because they've been taken off the standardization track, there is no spec-official name for combinators of the form `/<ident>/`. However, I talked to [Tab Atkins](https://twitter.com/tabatkins) and we agreed to call them "named combinators" so now they are called that.

Before this release such named combinators were parsed without intention and generated three nodes of type `"tag"` where the first and last nodes had a value of `"/"`.

* `.a /for/ .b` is parsed as a combinator.
  - Old & Busted:
    - `root.nodes[0].nodes[1].type === "tag"`
    - `root.nodes[0].nodes[1].value === "/"`
  - New hotness:
    - `root.nodes[0].nodes[1].type === "combinator"`
    - `root.nodes[0].nodes[1].value === "/for/"`
* `.a /F\6fR/ .b` escapes are handled and uppercase is normalized.
  - Old & Busted:
    - `root.nodes[0].nodes[2].type === "tag"`
    - `root.nodes[0].nodes[2].value === "F\\6fR"`
  - New hotness:
    - `root.nodes[0].nodes[1].type === "combinator"`
    - `root.nodes[0].nodes[1].value === "/for/"`
    - `root.nodes[0].nodes[1].raws.value === "/F\\6fR/"`

### Source position checks and lookups

A new API was added to look up a node based on the source location.

```js
const selectorParser = require("postcss-selector-parser");
// You can find the most specific node for any given character
let combinator = selectorParser.astSync(".a > .b").atPosition(1,4);
combinator.toString() === " > ";
// You can check if a node includes a specific character
// Whitespace surrounding the node that is owned by that node
// is included in the check.
[2,3,4,5,6].map(column => combinator.isAtPosition(1, column));
// => [false, true, true, true, false]
```

# 4.0.0

This release has **BREAKING CHANGES** that were required to fix bugs regarding values with escape sequences. Please read carefully.

* **Identifiers with escapes** - CSS escape sequences are now hidden from the public API by default.
  The normal value of a node like a class name or ID, or an aspect of a node such as attribute
  selector's value, is unescaped. Escapes representing Non-ascii characters are unescaped into
  unicode characters. For example: `bu\tton, .\31 00, #i\2764\FE0Fu, [attr="value is \"quoted\""]`
  will parse respectively to the values `button`, `100`, `i❤️u`, `value is "quoted"`.
  The original escape sequences for these values can be found in the corresponding property name
  in `node.raws`. Where possible, deprecation warnings were added, but the nature
  of escape handling makes it impossible to detect what is escaped or not. Our expectation is
  that most users are neither expecting nor handling escape sequences in their use of this library,
  and so for them, this is a bug fix. Users who are taking care to handle escapes correctly can
  now update their code to remove the escape handling and let us do it for them.

* **Mutating values with escapes** - When you make an update to a node property that has escape handling
  The value is assumed to be unescaped, and any special characters are escaped automatically and
  the corresponding `raws` value is immediately updated. This can result in changes to the original
  escape format. Where the exact value of the escape sequence is important there are methods that
  allow both values to be set in conjunction. There are a number of new convenience methods for
  manipulating values that involve escapes, especially for attributes values where the quote mark
  is involved. See https://github.com/postcss/postcss-selector-parser/pull/133 for an extensive
  write-up on these changes.


**Upgrade/API Example**

In `3.x` there was no unescape handling and internal consistency of several properties was the caller's job to maintain. It was very easy for the developer
to create a CSS file that did not parse correctly when some types of values
were in use.

```js
const selectorParser = require("postcss-selector-parser");
let attr = selectorParser.attribute({attribute: "id", operator: "=", value: "a-value"});
attr.value; // => "a-value"
attr.toString(); // => [id=a-value]
// Add quotes to an attribute's value.
// All these values have to be set by the caller to be consistent:
// no internal consistency is maintained.
attr.raws.unquoted = attr.value
attr.value = "'" + attr.value + "'";
attr.value; // => "'a-value'"
attr.quoted = true;
attr.toString();  // => "[id='a-value']"
```

In `4.0` there is a convenient API for setting and mutating values
that may need escaping. Especially for attributes.

```js
const selectorParser = require("postcss-selector-parser");

// The constructor requires you specify the exact escape sequence
let className = selectorParser.className({value: "illegal class name", raws: {value: "illegal\\ class\\ name"}});
className.toString(); // => '.illegal\\ class\\ name'

// So it's better to set the value as a property
className = selectorParser.className();
// Most properties that deal with identifiers work like this
className.value = "escape for me";
className.value; // => 'escape for me'
className.toString(); // => '.escape\\ for\\ me'

// emoji and all non-ascii are escaped to ensure it works in every css file.
className.value = "😱🦄😍";
className.value; // => '😱🦄😍'
className.toString(); // => '.\\1F631\\1F984\\1F60D'

// you can control the escape sequence if you want, or do bad bad things
className.setPropertyAndEscape('value', 'xxxx', 'yyyy');
className.value; // => "xxxx"
className.toString(); // => ".yyyy"

// Pass a value directly through to the css output without escaping it. 
className.setPropertyWithoutEscape('value', '$REPLACE_ME$');
className.value; // => "$REPLACE_ME$"
className.toString(); // => ".$REPLACE_ME$"

// The biggest changes are to the Attribute class
// passing quoteMark explicitly is required to avoid a deprecation warning.
let attr = selectorParser.attribute({attribute: "id", operator: "=", value: "a-value", quoteMark: null});
attr.toString(); // => "[id=a-value]"
// Get the value with quotes on it and any necessary escapes.
// This is the same as reading attr.value in 3.x.
attr.getQuotedValue(); // => "a-value";
attr.quoteMark; // => null

// Add quotes to an attribute's value.
attr.quoteMark = "'"; // This is all that's required.
attr.toString(); // => "[id='a-value']"
attr.quoted; // => true
// The value is still the same, only the quotes have changed.
attr.value; // => a-value
attr.getQuotedValue(); // => "'a-value'";

// deprecated assignment, no warning because there's no escapes
attr.value = "new-value";
// no quote mark is needed so it is removed
attr.getQuotedValue(); // => "new-value";

// deprecated assignment, 
attr.value = "\"a 'single quoted' value\"";
// > (node:27859) DeprecationWarning: Assigning an attribute a value containing characters that might need to be escaped is deprecated. Call attribute.setValue() instead.
attr.getQuotedValue(); // => '"a \'single quoted\' value"';
// quote mark inferred from first and last characters.
attr.quoteMark; // => '"'

// setValue takes options to make manipulating the value simple.
attr.setValue('foo', {smart: true});
// foo doesn't require any escapes or quotes.
attr.toString(); // => '[id=foo]'
attr.quoteMark; // => null 

// An explicit quote mark can be specified
attr.setValue('foo', {quoteMark: '"'});
attr.toString(); // => '[id="foo"]'

// preserves quote mark by default
attr.setValue('bar');
attr.toString(); // => '[id="bar"]'
attr.quoteMark = null;
attr.toString(); // => '[id=bar]'

// with no arguments, it preserves quote mark even when it's not a great idea
attr.setValue('a value \n that should be quoted');
attr.toString(); // => '[id=a\\ value\\ \\A\\ that\\ should\\ be\\ quoted]'

// smart preservation with a specified default
attr.setValue('a value \n that should be quoted', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => "[id='a value \\A  that should be quoted']"
attr.quoteMark = '"';
// => '[id="a value \\A  that should be quoted"]'

// this keeps double quotes because it wants to quote the value and the existing value has double quotes.
attr.setValue('this should be quoted', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => '[id="this should be quoted"]'

// picks single quotes because the value has double quotes
attr.setValue('a "double quoted" value', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => "[id='a "double quoted" value']"

// setPropertyAndEscape lets you do anything you want. Even things that are a bad idea and illegal.
attr.setPropertyAndEscape('value', 'xxxx', 'the password is 42');
attr.value; // => "xxxx"
attr.toString(); // => "[id=the password is 42]"

// Pass a value directly through to the css output without escaping it. 
attr.setPropertyWithoutEscape('value', '$REPLACEMENT$');
attr.value; // => "$REPLACEMENT$"
attr.toString(); // => "[id=$REPLACEMENT$]"
```

# 3.1.2

* Fix: Removed dot-prop dependency since it's no longer written in es5.

# 3.1.1

* Fix: typescript definitions weren't in the published package.

# 3.1.0

* Fixed numerous bugs in attribute nodes relating to the handling of comments
  and whitespace. There's significant changes to `attrNode.spaces` and `attrNode.raws` since the `3.0.0` release.
* Added `Attribute#offsetOf(part)` to get the offset location of
  attribute parts like `"operator"` and `"value"`. This is most
  often added to `Attribute#sourceIndex` for error reporting.

# 3.0.0

## Breaking changes

* Some tweaks to the tokenizer/attribute selector parsing mean that whitespace
  locations might be slightly different to the 2.x code.
* Better attribute selector parsing with more validation; postcss-selector-parser
  no longer uses regular expressions to parse attribute selectors.
* Added an async API (thanks to @jacobp100); the default `process` API is now
  async, and the sync API is now accessed through `processSync` instead.
* `process()` and `processSync()` now return a string instead of the Processor
  instance.
* Tweaks handling of Less interpolation (thanks to @jwilsson).
* Removes support for Node 0.12.

## Other changes

* `ast()` and `astSync()` methods have been added to the `Processor`. These
  return the `Root` node of the selectors after processing them.
* `transform()` and `transformSync()` methods have been added to the
  `Processor`. These return the value returned by the processor callback
  after processing the selectors.
* Set the parent when inserting a node (thanks to @chriseppstein).
* Correctly adjust indices when using insertBefore/insertAfter (thanks to @tivac).
* Fixes handling of namespaces with qualified tag selectors.
* `process`, `ast` and `transform` (and their sync variants) now accept a
  `postcss` rule node. When provided, better errors are generated and selector
  processing is automatically set back to the rule selector (unless the `updateSelector` option is set to `false`.)
* Now more memory efficient when tokenizing selectors.

### Upgrade hints

The pattern of:

`rule.selector = processor.process(rule.selector).result.toString();`

is now:

`processor.processSync(rule)`

# 2.2.3

* Resolves an issue where the parser would not reduce multiple spaces between an
  ampersand and another simple selector in lossy mode (thanks to @adam-26).

# 2.2.2

* No longer hangs on an unescaped semicolon; instead the parser will throw
  an exception for these cases.

# 2.2.1

* Allows a consumer to specify whitespace tokens when creating a new Node
  (thanks to @Semigradsky).

# 2.2.0

* Added a new option to normalize whitespace when parsing the selector string
  (thanks to @adam-26).

# 2.1.1

* Better unquoted value handling within attribute selectors
  (thanks to @evilebottnawi).

# 2.1.0

* Added: Use string constants for all node types & expose them on the main
  parser instance (thanks to @Aweary).

# 2.0.0

This release contains the following breaking changes:

* Renamed all `eachInside` iterators to `walk`. For example, `eachTag` is now
  `walkTags`, and `eachInside` is now `walk`.
* Renamed `Node#removeSelf()` to `Node#remove()`.
* Renamed `Container#remove()` to `Container#removeChild()`.
* Renamed `Node#raw` to `Node#raws` (thanks to @davidtheclark).
* Now parses `&` as the *nesting* selector, rather than a *tag* selector.
* Fixes misinterpretation of Sass interpolation (e.g. `#{foo}`) as an
  id selector (thanks to @davidtheclark).

and;

* Fixes parsing of attribute selectors with equals signs in them
  (e.g. `[data-attr="foo=bar"]`) (thanks to @montmanu).
* Adds `quoted` and `raw.unquoted` properties to attribute nodes
  (thanks to @davidtheclark).

# 1.3.3

* Fixes an infinite loop on `)` and `]` tokens when they had no opening pairs.
  Now postcss-selector-parser will throw when it encounters these lone tokens.

# 1.3.2

* Now uses plain integers rather than `str.charCodeAt(0)` for compiled builds.

# 1.3.1

* Update flatten to v1.x (thanks to @shinnn).

# 1.3.0

* Adds a new node type, `String`, to fix a crash on selectors such as
  `foo:bar("test")`.

# 1.2.1

* Fixes a crash when the parser encountered a trailing combinator.

# 1.2.0

* A more descriptive error is thrown when the parser expects to find a
  pseudo-class/pseudo-element (thanks to @ashelley).
* Adds support for line/column locations for selector nodes, as well as a
  `Node#sourceIndex` method (thanks to @davidtheclark).

# 1.1.4

* Fixes a crash when a selector started with a `>` combinator. The module will
  now no longer throw if a selector has a leading/trailing combinator node.

# 1.1.3

* Fixes a crash on `@` tokens.

# 1.1.2

* Fixes an infinite loop caused by using parentheses in a non-pseudo element
  context.

# 1.1.1

* Fixes a crash when a backslash ended a selector string.

# 1.1.0

* Adds support for replacing multiple nodes at once with `replaceWith`
  (thanks to @jonathantneal).
* Parser no longer throws on sequential IDs and trailing commas, to support
  parsing of selector hacks.

# 1.0.1

* Fixes using `insertAfter` and `insertBefore` during iteration.

# 1.0.0

* Adds `clone` and `replaceWith` methods to nodes.
* Adds `insertBefore` and `insertAfter` to containers.
* Stabilises API.

# 0.0.5

* Fixes crash on extra whitespace inside a pseudo selector's parentheses.
* Adds sort function to the container class.
* Enables the parser to pass its input through without transforming.
* Iteration-safe `each` and `eachInside`.

# 0.0.4

* Tidy up redundant duplication.
* Fixes a bug where the parser would loop infinitely on universal selectors
  inside pseudo selectors.
* Adds `length` getter and `eachInside`, `map`, `reduce` to the container class.
* When a selector has been removed from the tree, the root node will no longer
  cast it to a string.
* Adds node type iterators to the container class (e.g. `eachComment`).
* Adds filter function to the container class.
* Adds split function to the container class.
* Create new node types by doing `parser.id(opts)` etc.
* Adds support for pseudo classes anywhere in the selector.

# 0.0.3

* Adds `next` and `prev` to the node class.
* Adds `first` and `last` getters to the container class.
* Adds `every` and `some` iterators to the container class.
* Add `empty` alias for `removeAll`.
* Combinators are now types of node.
* Fixes the at method so that it is not an alias for `index`.
* Tidy up creation of new nodes in the parser.
* Refactors how namespaces are handled for consistency & less redundant code.
* Refactors AST to use `nodes` exclusively, and eliminates excessive nesting.
* Fixes nested pseudo parsing.
* Fixes whitespace parsing.

# 0.0.2

* Adds support for namespace selectors.
* Adds support for selectors joined by escaped spaces - such as `.\31\ 0`.

# 0.0.1

* Initial release.


---

# postcss-selector-parser [![test](https://github.com/postcss/postcss-selector-parser/actions/workflows/test.yml/badge.svg)](https://github.com/postcss/postcss-selector-parser/actions/workflows/test.yml)

> Selector parser with built in methods for working with selector strings.

## Install

With [npm](https://npmjs.com/package/postcss-selector-parser) do:

```
npm install postcss-selector-parser
```

## Quick Start

```js
const parser = require('postcss-selector-parser');
const transform = selectors => {
    selectors.walk(selector => {
        // do something with the selector
        console.log(String(selector))
    });
};

const transformed = parser(transform).processSync('h1, h2, h3');
```

To normalize selector whitespace:

```js
const parser = require('postcss-selector-parser');
const normalized = parser().processSync('h1, h2, h3', {lossless: false});
// -> h1,h2,h3
```

Async support is provided through `parser.process` and will resolve a Promise
with the resulting selector string.

## API

Please see [API.md](API.md).

## Credits

* Huge thanks to Andrey Sitnik (@ai) for work on PostCSS which helped
  accelerate this module's development.

## License

MIT


---

# PostCSS Calc [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS" width="90" height="90" align="right">][PostCSS]

[![NPM Version][npm-img]][npm-url]
[![Support Chat][git-img]][git-url]

[PostCSS Calc] lets you reduce `calc()` references whenever it's possible.
When multiple units are mixed together in the same expression, the `calc()`
statement is left as is, to fallback to the [W3C calc() implementation].

## Installation

```bash
npm install postcss-calc
```

## Usage

```js
// dependencies
var fs = require("fs")
var postcss = require("postcss")
var calc = require("postcss-calc")

// css to be processed
var css = fs.readFileSync("input.css", "utf8")

// process css
var output = postcss()
  .use(calc())
  .process(css)
  .css
```

Using this `input.css`:

```css
h1 {
  font-size: calc(16px * 2);
  height: calc(100px - 2em);
  width: calc(2*var(--base-width));
  margin-bottom: calc(16px * 1.5);
}
```

you will get:

```css
h1 {
  font-size: 32px;
  height: calc(100px - 2em);
  width: calc(2*var(--base-width));
  margin-bottom: 24px
}
```
Checkout [tests] for more examples.

### Options

#### `precision` (default: `5`)

Allow you to define the precision for decimal numbers.

```js
var out = postcss()
  .use(calc({precision: 10}))
  .process(css)
  .css
```

#### `preserve` (default: `false`)

Allow you to preserve calc() usage in output so browsers will handle decimal
precision themselves.

```js
var out = postcss()
  .use(calc({preserve: true}))
  .process(css)
  .css
```

#### `warnWhenCannotResolve` (default: `false`)

Adds warnings when calc() are not reduced to a single value.

```js
var out = postcss()
  .use(calc({warnWhenCannotResolve: true}))
  .process(css)
  .css
```

#### `mediaQueries` (default: `false`)

Allows calc() usage as part of media query declarations.

```js
var out = postcss()
  .use(calc({mediaQueries: true}))
  .process(css)
  .css
```

#### `selectors` (default: `false`)

Allows calc() usage as part of selectors.

```js
var out = postcss()
  .use(calc({selectors: true}))
  .process(css)
  .css
```

Example:

```css
div[data-size="calc(3*3)"] {
  width: 100px;
}
```

---

## Related PostCSS plugins
To replace the value of CSS custom properties at build time, try [PostCSS Custom Properties].

## Contributing

Work on a branch, install dev-dependencies, respect coding style & run tests
before submitting a bug fix or a feature.

```bash
git clone git@github.com:postcss/postcss-calc.git
git checkout -b patch-1
npm install
npm test
```

## [Changelog](CHANGELOG.md)

## [License](LICENSE)

[git-img]: https://img.shields.io/badge/support-chat-blue.svg
[git-url]: https://gitter.im/postcss/postcss
[npm-img]: https://img.shields.io/npm/v/postcss-calc.svg
[npm-url]: https://www.npmjs.com/package/postcss-calc

[PostCSS]: https://github.com/postcss
[PostCSS Calc]: https://github.com/postcss/postcss-calc
[PostCSS Custom Properties]: https://github.com/postcss/postcss-custom-properties
[tests]: src/__tests__/index.js
[W3C calc() implementation]: https://www.w3.org/TR/css3-values/#calc-notation


---

# Installing PostCSS Clamp

[PostCSS Clamp] runs in all Node environments, with special instructions for:

| [Node](#node) | [PostCSS CLI](#postcss-cli) | [Webpack](#webpack) | [Create React App](#create-react-app) | [Gulp](#gulp) | [Grunt](#grunt) |
| --- | --- | --- | --- | --- | --- |

## Node

Add [PostCSS Clamp] to your project:

```bash
$ npm install postcss-clamp --save-dev
```

Use [PostCSS Clamp] as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssClamp = require('postcss-clamp');

postcss([
  postcssClamp(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```

## PostCSS CLI

Add [PostCSS CLI] to your project:

```bash
npm install postcss-cli --save-dev
```

Use **PostCSS Clamp** in your `postcss.config.js` configuration file:

```js
const postcssClamp = require('postcss-clamp');

module.exports = {
  plugins: [
    postcssClamp(/* pluginOptions */)
  ]
}
```

## Webpack

Add [PostCSS Loader] to your project:

```bash
npm install postcss-loader --save-dev
```

Use **PostCSS Clamp** in your Webpack configuration:

```js
const postcssClamp = require('postcss-clamp');

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          'style-loader',
          { loader: 'css-loader', options: { importLoaders: 1 } },
          { loader: 'postcss-loader', options: {
            ident: 'postcss',
            plugins: () => [
              postcssClamp(/* pluginOptions */)
            ]
          } }
        ]
      }
    ]
  }
}
```

## Create React App

Add [React App Rewired] and [React App Rewire PostCSS] to your project:

```bash
npm install react-app-rewired react-app-rewire-postcss --save-dev
```

Use **React App Rewire PostCSS** and **PostCSS Clamp** in your
`config-overrides.js` file:

```js
const reactAppRewirePostcss = require('react-app-rewire-postcss');
const postcssClamp = require('postcss-clamp');

module.exports = config => reactAppRewirePostcss(config, {
  plugins: () => [
    postcssClamp(/* pluginOptions */)
  ]
});
```

## Gulp

Add [Gulp PostCSS] to your project:

```bash
npm install gulp-postcss --save-dev
```

Use **PostCSS Clamp** in your Gulpfile:

```js
const postcss = require('gulp-postcss');
const postcssClamp = require('postcss-clamp');

gulp.task('css', () => gulp.src('./src/*.css').pipe(
  postcss([
    postcssClamp(/* pluginOptions */)
  ])
).pipe(
  gulp.dest('.')
));
```

## Grunt

Add [Grunt PostCSS] to your project:

```bash
npm install grunt-postcss --save-dev
```

Use **PostCSS Clamp** in your Gruntfile:

```js
const postcssClamp = require('postcss-clamp');

grunt.loadNpmTasks('grunt-postcss');

grunt.initConfig({
  postcss: {
    options: {
      use: [
       postcssClamp(/* pluginOptions */)
      ]
    },
    dist: {
      src: '*.css'
    }
  }
});
```

[Gulp PostCSS]: https://github.com/postcss/gulp-postcss
[Grunt PostCSS]: https://github.com/nDmitry/grunt-postcss
[PostCSS]: https://github.com/postcss/postcss
[PostCSS CLI]: https://github.com/postcss/postcss-cli
[PostCSS Loader]: https://github.com/postcss/postcss-loader
[PostCSS Clamp]: https://github.com/polemius/postcss-clamp
[React App Rewire PostCSS]: https://github.com/csstools/react-app-rewire-postcss
[React App Rewired]: https://github.com/timarney/react-app-rewired


---

# PostCSS Clamp
[![Build Status][ci-img]][ci] [![codecov.io][cov-img]][cov]

[PostCSS] plugin to transform `clamp()` to combination of `min/max`.

[PostCSS]:    https://github.com/postcss/postcss
[ci-img]:     https://travis-ci.com/polemius/postcss-clamp.svg?branch=master
[ci]:         https://travis-ci.com/polemius/postcss-clamp
[cov-img]: https://codecov.io/github/polemius/postcss-clamp/coverage.svg?branch=master
[cov]:        https://codecov.io/github/polemius/postcss-clamp?branch=master

This plugin transform this css:

```css
.foo {
  width: clamp(10px, 4em, 80px);
}
```

into this:

```css
.foo {
  width: max(10px, min(4em, 80px));
}
```

Or with enabled options `precalculate`:

```css
.foo {
  width: clamp(10em, 4px, 10px);
}

/* becomes */

.foo {
  width: max(10em, 14px);
}
```

[!['Can I use' table](https://caniuse.bitsofco.de/image/css-math-functions.png)](https://caniuse.com/#feat=css-math-functions)

## Instalation

```bash
$ npm install postcss postcss-clamp --save-dev
or
$ yarn add --dev postcss postcss-clamp
```

## Usage

Use [PostCSS Clamp] as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssClamp = require('postcss-clamp');

postcss([
  postcssClamp(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```

[PostCSS Clamp] runs in all Node environments, with special instructions for:

| [Node](INSTALL.md#node) | [PostCSS CLI](INSTALL.md#postcss-cli) | [Webpack](INSTALL.md#webpack) | [Create React App](INSTALL.md#create-react-app) | [Gulp](INSTALL.md#gulp) | [Grunt](INSTALL.md#grunt) |
| --- | --- | --- | --- | --- | --- |

See [PostCSS] docs for examples for your environment.

## Options

### precalculate

The `precalculate` option determines whether values with the same unit
should be precalculated. By default, these are not precalculation.

```js
postcssColorHexAlpha({
  precalculate: true
});
```

The second and third value has the same unit (`px`):

```css
.foo {
  width: clamp(10em, 4px, 10px);
}

/* becomes */

.foo {
  width: max(10em, 14px);
}
```

Here all values have the same unit:

```css
.foo {
  width: clamp(10px, 4px, 10px);
}

/* becomes */

.foo {
  width: 24px;
}
```

## LICENSE

See [LICENSE](LICENSE)

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Clamp]: https://github.com/polemius/postcss-clamp


---

# Changes to PostCSS Color Functional Notation

### 7.0.8

_February 23, 2025_

- Updated [`@csstools/css-color-parser`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-color-parser) to [`3.0.8`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-color-parser/CHANGELOG.md#308) (patch)

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-color-functional-notation/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Color Functional Notation [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install postcss-color-functional-notation --save-dev`

[PostCSS Color Functional Notation] lets you use space and slash separated
color notation in CSS, following the [CSS Color] specification.

```css
:root {
	--firebrick: rgb(178 34 34);
	--firebrick-a50: rgb(70% 13.5% 13.5% / 50%);
	--firebrick-hsl: hsla(0 68% 42%);
	--firebrick-hsl-a50: hsl(0 68% 42% / 50%);
}

/* becomes */

:root {
	--firebrick: rgb(178, 34, 34);
	--firebrick-a50: rgba(179, 34, 34, 0.5);
	--firebrick-hsl: hsl(0, 68%, 42%);
	--firebrick-hsl-a50: hsla(0, 68%, 42%, 0.5);
}
```

## Usage

Add [PostCSS Color Functional Notation] to your project:

```bash
npm install postcss postcss-color-functional-notation --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssColorFunctionalNotation = require('postcss-color-functional-notation');

postcss([
	postcssColorFunctionalNotation(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## Options

### preserve

The `preserve` option determines whether the original notation
is preserved. By default, it is not preserved.

```js
postcssColorFunctionalNotation({ preserve: true })
```

```css
:root {
	--firebrick: rgb(178 34 34);
	--firebrick-a50: rgb(70% 13.5% 13.5% / 50%);
	--firebrick-hsl: hsla(0 68% 42%);
	--firebrick-hsl-a50: hsl(0 68% 42% / 50%);
}

/* becomes */

:root {
	--firebrick: rgb(178, 34, 34);
	--firebrick-a50: rgba(179, 34, 34, 0.5);
	--firebrick-hsl: hsl(0, 68%, 42%);
	--firebrick-hsl: hsla(0 68% 42%);
	--firebrick-hsl-a50: hsla(0, 68%, 42%, 0.5);
}

@supports (color: rgb(0 0 0 / 0)) {
:root {
	--firebrick: rgb(178 34 34);
	--firebrick-a50: rgb(70% 13.5% 13.5% / 50%);
}
}

@supports (color: hsl(0 0% 0% / 0)) {
:root {
	--firebrick-hsl-a50: hsl(0 68% 42% / 50%);
}
}
```

### enableProgressiveCustomProperties

The `enableProgressiveCustomProperties` option determines whether the original notation
is wrapped with `@supports` when used in Custom Properties. By default, it is enabled.

> [!NOTE]
> We only recommend disabling this when you set `preserve` to `false` or if you bring your own fix for Custom Properties.  
> See what the plugin does in its [README](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-progressive-custom-properties#readme).

```js
postcssColorFunctionalNotation({ enableProgressiveCustomProperties: false })
```

```css
:root {
	--firebrick: rgb(178 34 34);
	--firebrick-a50: rgb(70% 13.5% 13.5% / 50%);
	--firebrick-hsl: hsla(0 68% 42%);
	--firebrick-hsl-a50: hsl(0 68% 42% / 50%);
}

/* becomes */

:root {
	--firebrick: rgb(178, 34, 34);
	--firebrick: rgb(178 34 34);
	--firebrick-a50: rgba(179, 34, 34, 0.5);
	--firebrick-a50: rgb(70% 13.5% 13.5% / 50%);
	--firebrick-hsl: hsl(0, 68%, 42%);
	--firebrick-hsl: hsla(0 68% 42%);
	--firebrick-hsl-a50: hsla(0, 68%, 42%, 0.5);
	--firebrick-hsl-a50: hsl(0 68% 42% / 50%);
}
```

_Custom properties do not fallback to the previous declaration_

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#color-functional-notation
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/postcss-color-functional-notation

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Color Functional Notation]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-color-functional-notation
[CSS Color]: https://www.w3.org/TR/css-color-4/#funcdef-rgb


---

# Changes to PostCSS Color Hex Alpha

### 10.0.0

_August 3, 2024_

- Updated: Support for Node v18+ (major).
- Updated [`@csstools/utilities`](https://github.com/csstools/postcss-plugins/tree/main/packages/utilities) to [`2.0.0`](https://github.com/csstools/postcss-plugins/tree/main/packages/utilities/CHANGELOG.md#200) (major)

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-color-hex-alpha/CHANGELOG.md)


---

# The MIT License (MIT)

Copyright © PostCSS

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Color Hex Alpha [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install postcss-color-hex-alpha --save-dev`

[PostCSS Color Hex Alpha] lets you use 4 & 8 character hex color notation in
CSS, following the [CSS Color Module] specification.

```pcss
body {
	background: #9d9c;
}

/* becomes */

body {
	background: rgba(153,221,153,0.8);
}
```

## Usage

Add [PostCSS Color Hex Alpha] to your project:

```bash
npm install postcss postcss-color-hex-alpha --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssColorHexAlpha = require('postcss-color-hex-alpha');

postcss([
	postcssColorHexAlpha(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## Options

### preserve

The `preserve` option determines whether the original notation
is preserved. By default, it is not preserved.

```js
postcssColorHexAlpha({ preserve: true })
```

```pcss
body {
	background: #9d9c;
}

/* becomes */

body {
	background: rgba(153,221,153,0.8);
	background: #9d9c;
}
```

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#hexadecimal-alpha-notation
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/postcss-color-hex-alpha

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Color Hex Alpha]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-color-hex-alpha
[CSS Color Module]: https://www.w3.org/TR/css-color-4/#hex-notation


---

# Changes to PostCSS RebeccaPurple

### 10.0.0

_August 3, 2024_

- Updated: Support for Node v18+ (major).
- Updated [`@csstools/utilities`](https://github.com/csstools/postcss-plugins/tree/main/packages/utilities) to [`2.0.0`](https://github.com/csstools/postcss-plugins/tree/main/packages/utilities/CHANGELOG.md#200) (major)

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-color-rebeccapurple/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS RebeccaPurple [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install postcss-color-rebeccapurple --save-dev`

[PostCSS RebeccaPurple] lets you use the `rebeccapurple` color keyword in CSS.

```pcss
.heading {
	color: rebeccapurple;
}

/* becomes */

.heading {
	color: #639;
}
```

## About the `rebeccapurple` keyword

In 2014, Rebecca Alison Meyer, the daughter of [Eric A. Meyer](https://en.wikipedia.org/wiki/Eric_A._Meyer), an American web design consultant best known for his advocacy work on behalf of CSS, passed away of a brain tumor at six years of age.

In her memory, the hex color `#663399` is named `rebeccapurple` and [added to the CSS Colors list](https://lists.w3.org/Archives/Public/www-style/2014Jun/0312.html).

## Usage

Add [PostCSS RebeccaPurple] to your project:

```bash
npm install postcss postcss-color-rebeccapurple --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssRebeccaPurple = require('postcss-color-rebeccapurple');

postcss([
	postcssRebeccaPurple(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## Options

### preserve

The `preserve` option determines whether the original notation
is preserved. By default, it is not preserved.

```js
postcssRebeccaPurple({ preserve: true })
```

```pcss
.heading {
	color: rebeccapurple;
}

/* becomes */

.heading {
	color: #639;
	color: rebeccapurple;
}
```

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#rebeccapurple-color
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/postcss-color-rebeccapurple

[PostCSS]: https://github.com/postcss/postcss
[PostCSS RebeccaPurple]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-color-rebeccapurple


---

# [postcss][postcss]-colormin

> Minify colors in your CSS files with PostCSS.

## Install

With [npm](https://npmjs.org/package/postcss-colormin) do:

```
npm install postcss-colormin --save
```


## Example

```js
var postcss = require('postcss')
var colormin = require('postcss-colormin');

var css = 'h1 {color: rgba(255, 0, 0, 1)}';
console.log(postcss(colormin()).process(css).css);

// => 'h1 {color:red}'
```

For more examples see the [tests](src/__tests__/index.js).


## Usage

See the [PostCSS documentation](https://github.com/postcss/postcss#usage) for
examples for your environment.


## Contributors

See [CONTRIBUTORS.md](https://github.com/cssnano/cssnano/blob/master/CONTRIBUTORS.md).


## License

MIT © [Ben Briggs](http://beneb.info)


[postcss]:  https://github.com/postcss/postcss


---

# [postcss][postcss]-convert-values

> Convert values with PostCSS (e.g. ms -> s)

## Install

With [npm](https://npmjs.org/package/postcss-convert-values) do:

```
npm install postcss-convert-values --save
```

## Example

This plugin reduces CSS size by converting values to use different units
where possible; for example, `500ms` can be represented as `.5s`. You can
read more about these units in [this article][csstricks].

### Input

```css
h1 {
    font-size: 16px;
    width: 0em
}
```

### Output

```css
h1 {
    font-size: 1pc;
    width: 0
}
```

Note that this plugin only covers conversions for duration and absolute length
values. For color conversions, use [postcss-colormin][colormin].

## API

### convertValues([options])

#### options

##### length

Type: `boolean`
Default: `true`

Pass `false` to disable conversion from `px` to other absolute length units,
such as `pc` & `pt` & vice versa.

##### time

Type: `boolean`
Default: `true`

Pass `false` to disable conversion from `ms` to `s` & vice versa.

##### angle

Type: `boolean`
Default: `true`

Pass `false` to disable conversion from `deg` to `turn` & vice versa.

##### precision

Type: `boolean|number`
Default: `false`

Specify any numeric value here to round `px` values to that many decimal places;
for example, using `{precision: 2}` will round `6.66667px` to `6.67px`, and
`{precision: 0}` will round it to `7px`. Passing `false` (the default) will
leave these values as is.

It is recommended for most use cases to set this option to `2`.


## Usage

See the [PostCSS documentation](https://github.com/postcss/postcss#usage) for
examples for your environment.


## Contributors

See [CONTRIBUTORS.md](https://github.com/cssnano/cssnano/blob/master/CONTRIBUTORS.md).


## License

MIT © [Ben Briggs](http://beneb.info)


[postcss]: https://github.com/postcss/postcss
[csstricks]: https://css-tricks.com/the-lengths-of-css/


---

# Changes to PostCSS Custom Media

### 11.0.5

_November 1, 2024_

- Updated [`@csstools/css-tokenizer`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-tokenizer) to [`3.0.3`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-tokenizer/CHANGELOG.md#303) (patch)
- Updated [`@csstools/css-parser-algorithms`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-parser-algorithms) to [`3.0.4`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-parser-algorithms/CHANGELOG.md#304) (patch)
- Updated [`@csstools/cascade-layer-name-parser`](https://github.com/csstools/postcss-plugins/tree/main/packages/cascade-layer-name-parser) to [`2.0.4`](https://github.com/csstools/postcss-plugins/tree/main/packages/cascade-layer-name-parser/CHANGELOG.md#204) (patch)
- Updated [`@csstools/media-query-list-parser`](https://github.com/csstools/postcss-plugins/tree/main/packages/media-query-list-parser) to [`4.0.2`](https://github.com/csstools/postcss-plugins/tree/main/packages/media-query-list-parser/CHANGELOG.md#402) (patch)

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-custom-media/CHANGELOG.md)


---

# The MIT License (MIT)

Copyright © PostCSS

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Custom Media [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install postcss-custom-media --save-dev`

[PostCSS Custom Media] lets you define `@custom-media` in CSS following the [Custom Media Specification].

```pcss
@custom-media --small-viewport (max-width: 30em);

@media (--small-viewport) {
	/* styles for small viewport */
}

/* becomes */

@media (max-width: 30em) {
	/* styles for small viewport */
}
```

## `true` and `false`

With `@custom-media` you can use the constants `true` and `false`.
These are especially handy when debugging.

If you are unsure how your page is affected when a certain media query matches or not you can use these, to quickly toggle the results.
This plugin downgrades these queries to something that works in all browsers.

Quickly check the result as if the query matches:

```pcss
@custom-media --small-viewport true;

@media (--small-viewport) {
	/* styles for small viewport */
}

/* becomes */

@media (max-color:2147477350) {
	/* styles for small viewport */
}
```

Quickly check the result as if the query does not match:

```pcss
@custom-media --small-viewport false;

@media (--small-viewport) {
	/* styles for small viewport */
}

/* becomes */

@media (color:2147477350) {
	/* styles for small viewport */
}
```

## logical evaluation of complex media queries

It is impossible to accurately and correctly resolve complex `@custom-media` queries
as these depend on the browser the queries will eventually run in.

_Some of these queries will have only one possible outcome but we have to account for all possible queries in this plugin._

> [!NOTE]
> When handling complex media queries you will see that your CSS is doubled for each level of complexity.<br>
> GZIP works great to de-dupe this but having a lot of complex media queries will have a performance impact.

An example of a very complex (and artificial) use-case :

```pcss

@custom-media --a-complex-query tty and (min-width: 300px);

@media not screen and ((not (--a-complex-query)) or (color)) {
	/* Your CSS */
}

/* becomes */


@media tty and (min-width: 300px) {
@media not screen and ((not (max-color:2147477350)) or (color)) {
	/* Your CSS */
}
}
@media not tty,not all and (min-width: 300px) {
@media not screen and ((not (color:2147477350)) or (color)) {
	/* Your CSS */
}
}
```

## Usage

Add [PostCSS Custom Media] to your project:

```bash
npm install postcss postcss-custom-media --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssCustomMedia = require('postcss-custom-media');

postcss([
	postcssCustomMedia(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## Options

### preserve

The `preserve` option determines whether the original notation
is preserved. By default, it is not preserved.

```js
postcssCustomMedia({ preserve: true })
```

```pcss
@custom-media --small-viewport (max-width: 30em);

@media (--small-viewport) {
	/* styles for small viewport */
}

/* becomes */

@custom-media --small-viewport (max-width: 30em);

@media (max-width: 30em) {
	/* styles for small viewport */
}

@media (--small-viewport) {
	/* styles for small viewport */
}
```

## Modular CSS Processing

If you're using Modular CSS such as, CSS Modules, `postcss-loader` or `vanilla-extract` to name a few, you'll probably 
notice that custom media queries are not being resolved. This happens because each file is processed separately so 
unless you import the custom media query definitions in each file, they won't be resolved.

To overcome this, we recommend using the [PostCSS Global Data](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-global-data#readme)
plugin which allows you to pass a list of files that will be globally available. The plugin won't inject any extra code
in the output but will provide the context needed to resolve custom media queries.

For it to run it needs to be placed before the [PostCSS Custom Media] plugin.

```js
const postcss = require('postcss');
const postcssCustomMedia = require('postcss-custom-media');
const postcssGlobalData = require('@csstools/postcss-global-data');

postcss([
	postcssGlobalData({
		files: [
			'path/to/your/custom-media-queries.css'
		]
	}),
	postcssCustomMedia(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#custom-media-queries
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/postcss-custom-media

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Custom Media]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-custom-media
[Custom Media Specification]: https://www.w3.org/TR/mediaqueries-5/#at-ruledef-custom-media


---

# Changes to PostCSS Custom Properties

### 14.0.4

_November 1, 2024_

- Updated [`@csstools/css-tokenizer`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-tokenizer) to [`3.0.3`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-tokenizer/CHANGELOG.md#303) (patch)
- Updated [`@csstools/css-parser-algorithms`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-parser-algorithms) to [`3.0.4`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-parser-algorithms/CHANGELOG.md#304) (patch)
- Updated [`@csstools/cascade-layer-name-parser`](https://github.com/csstools/postcss-plugins/tree/main/packages/cascade-layer-name-parser) to [`2.0.4`](https://github.com/csstools/postcss-plugins/tree/main/packages/cascade-layer-name-parser/CHANGELOG.md#204) (patch)

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-custom-properties/CHANGELOG.md)


---

# The MIT License (MIT)

Copyright © PostCSS

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Custom Properties [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install postcss-custom-properties --save-dev`

[PostCSS Custom Properties] lets you use Custom Properties in CSS, following
the [CSS Custom Properties] specification.

[!['Can I use' table](https://caniuse.bitsofco.de/image/css-variables.png)](https://caniuse.com/#feat=css-variables)

```pcss
:root {
	--color-blue-dark: rgb(0, 61, 184);
	--color-blue-light: rgb(0, 217, 255);
	--color-pink: rgb(255, 192, 211);
	--text-color: var(--color-pink);
}

.element {
	/* custom props */
	--border-color: var(--color-blue-light);

	/* props */
	border: 1px solid var(--border-color);
	color: var(--text-color);
}

.element--dark {
	--border-color: var(--color-blue-dark);
}

/* becomes */

:root {
	--color-blue-dark: rgb(0, 61, 184);
	--color-blue-light: rgb(0, 217, 255);
	--color-pink: rgb(255, 192, 211);
	--text-color: var(--color-pink);
}

.element {
	/* custom props */
	--border-color: var(--color-blue-light);

	/* props */
	border: 1px solid rgb(0, 217, 255);
	border: 1px solid var(--border-color);
	color: rgb(255, 192, 211);
	color: var(--text-color);
}

.element--dark {
	--border-color: var(--color-blue-dark);
}
```

**Note:** 
- Only processes variables that were defined in the `:root` or `html` selector.
- Locally defined variables will be used as fallbacks only within the same rule, but not elsewhere.
- Fallback values in `var()` will be used if the variable was not defined in the `:root` or `html` selector.

## Usage

Add [PostCSS Custom Properties] to your project:

```bash
npm install postcss postcss-custom-properties --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssCustomProperties = require('postcss-custom-properties');

postcss([
	postcssCustomProperties(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## Options

### preserve

The `preserve` option determines whether properties using
custom properties should be preserved in their original form. By default these are preserved.

Custom property declarations are always preserved only `var()` functions can be omitted.

```js
postcssCustomProperties({ preserve: false })
```

```pcss
:root {
	--color-blue-dark: rgb(0, 61, 184);
	--color-blue-light: rgb(0, 217, 255);
	--color-pink: rgb(255, 192, 211);
	--text-color: var(--color-pink);
}

.element {
	/* custom props */
	--border-color: var(--color-blue-light);

	/* props */
	border: 1px solid var(--border-color);
	color: var(--text-color);
}

.element--dark {
	--border-color: var(--color-blue-dark);
}

/* becomes */

:root {
	--color-blue-dark: rgb(0, 61, 184);
	--color-blue-light: rgb(0, 217, 255);
	--color-pink: rgb(255, 192, 211);
	--text-color: var(--color-pink);
}

.element {
	/* custom props */
	--border-color: var(--color-blue-light);

	/* props */
	border: 1px solid var(--border-color);
	color: rgb(255, 192, 211);
}

.element--dark {
	--border-color: var(--color-blue-dark);
}
```

## Modular CSS Processing

If you're using Modular CSS such as, CSS Modules, `postcss-loader` or `vanilla-extract` to name a few, you'll probably
notice that custom properties are not being resolved. This happens because each file is processed separately so
unless you import the custom properties definitions in each file, they won't be resolved.

To overcome this, we recommend using the [PostCSS Global Data](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-global-data#readme)
plugin which allows you to pass a list of files that will be globally available. The plugin won't inject any extra code
in the output but will provide the context needed to resolve custom properties.

For it to run it needs to be placed before the [PostCSS Custom Properties] plugin.

```js
const postcss = require('postcss');
const postcssCustomProperties = require('postcss-custom-properties');
const postcssGlobalData = require('@csstools/postcss-global-data');

postcss([
	postcssGlobalData({
		files: [
			'path/to/your/custom-selectors.css'
		]
	}),
	postcssCustomProperties(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#custom-properties
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/postcss-custom-properties

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Custom Properties]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-custom-properties
[CSS Custom Properties]: https://www.w3.org/TR/css-variables-1/


---

# Changes to PostCSS Custom Selectors

### 8.0.4

_November 1, 2024_

- Updated [`@csstools/css-tokenizer`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-tokenizer) to [`3.0.3`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-tokenizer/CHANGELOG.md#303) (patch)
- Updated [`@csstools/css-parser-algorithms`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-parser-algorithms) to [`3.0.4`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-parser-algorithms/CHANGELOG.md#304) (patch)
- Updated [`@csstools/cascade-layer-name-parser`](https://github.com/csstools/postcss-plugins/tree/main/packages/cascade-layer-name-parser) to [`2.0.4`](https://github.com/csstools/postcss-plugins/tree/main/packages/cascade-layer-name-parser/CHANGELOG.md#204) (patch)

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-custom-selectors/CHANGELOG.md)


---

# The MIT License (MIT)

Copyright © PostCSS

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Custom Selectors [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install postcss-custom-selectors --save-dev`

[PostCSS Custom Selectors] lets you define `@custom-selector` in CSS following the [Custom Selectors Specification].

```pcss
@custom-selector :--heading h1, h2, h3;

article :--heading + p {
	margin-top: 0;
}

/* becomes */

article :is(h1, h2, h3) + p {
	margin-top: 0;
}
```

## Usage

Add [PostCSS Custom Selectors] to your project:

```bash
npm install postcss postcss-custom-selectors --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssCustomSelectors = require('postcss-custom-selectors');

postcss([
	postcssCustomSelectors(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## Options

### preserve

The `preserve` option determines whether the original notation
is preserved. By default, it is not preserved.

```js
postcssCustomSelectors({ preserve: true })
```

```pcss
@custom-selector :--heading h1, h2, h3;

article :--heading + p {
	margin-top: 0;
}

/* becomes */

@custom-selector :--heading h1, h2, h3;

article :is(h1, h2, h3) + p {
	margin-top: 0;
}

article :--heading + p {
	margin-top: 0;
}
```

## Modular CSS Processing

If you're using Modular CSS such as, CSS Modules, `postcss-loader` or `vanilla-extract` to name a few, you'll probably
notice that custom selectors are not being resolved. This happens because each file is processed separately so
unless you import the custom selector definitions in each file, they won't be resolved.

To overcome this, we recommend using the [PostCSS Global Data](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-global-data#readme)
plugin which allows you to pass a list of files that will be globally available. The plugin won't inject any extra code
in the output but will provide the context needed to resolve custom selectors.

For it to run it needs to be placed before the [PostCSS Custom Selectors] plugin.

```js
const postcss = require('postcss');
const postcssCustomSelectors = require('postcss-custom-selectors');
const postcssGlobalData = require('@csstools/postcss-global-data');

postcss([
	postcssGlobalData({
		files: [
			'path/to/your/custom-selectors.css'
		]
	}),
	postcssCustomSelectors(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#custom-selectors
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/postcss-custom-selectors

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Custom Selectors]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-custom-selectors
[Custom Selectors Specification]: https://drafts.csswg.org/css-extensions/#custom-selectors


---

# API Documentation

*Please use only this documented API when working with the parser. Methods
not documented here are subject to change at any point.*

## `parser` function

This is the module's main entry point.

```js
const parser = require('postcss-selector-parser');
```

### `parser([transform], [options])`

Creates a new `processor` instance

```js
const processor = parser();
```

Or, with optional transform function

```js
const transform = selectors => {
    selectors.walkUniversals(selector => {
        selector.remove();
    });
};

const processor = parser(transform)

// Example
const result = processor.processSync('*.class');
// => .class
```

[See processor documentation](#processor)

Arguments:

* `transform (function)`: Provide a function to work with the parsed AST.
* `options (object)`: Provide default options for all calls on the returned `Processor`.

### `parser.attribute([props])`

Creates a new attribute selector.

```js
parser.attribute({attribute: 'href'});
// => [href]
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.className([props])`

Creates a new class selector.

```js
parser.className({value: 'button'});
// => .button
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.combinator([props])`

Creates a new selector combinator.

```js
parser.combinator({value: '+'});
// => +
```

Arguments:

* `props (object)`: The new node's properties.

Notes:
* **Descendant Combinators** The value of descendant combinators created by the
  parser always just a single space (`" "`). For descendant selectors with no
  comments, additional space is now stored in `node.spaces.before`. Depending
  on the location of comments, additional spaces may be stored in
  `node.raws.spaces.before`, `node.raws.spaces.after`, or `node.raws.value`.
* **Named Combinators** Although, nonstandard and unlikely to ever become a standard,
  named combinators like `/deep/` and `/for/` are parsed as combinators. The
  `node.value` is name after being unescaped and normalized as lowercase. The
  original value for the combinator name is stored in `node.raws.value`.


### `parser.comment([props])`

Creates a new comment.

```js
parser.comment({value: '/* Affirmative, Dave. I read you. */'});
// => /* Affirmative, Dave. I read you. */
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.id([props])`

Creates a new id selector.

```js
parser.id({value: 'search'});
// => #search
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.nesting([props])`

Creates a new nesting selector.

```js
parser.nesting();
// => &
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.pseudo([props])`

Creates a new pseudo selector.

```js
parser.pseudo({value: '::before'});
// => ::before
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.root([props])`

Creates a new root node.

```js
parser.root();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.selector([props])`

Creates a new selector node.

```js
parser.selector();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.string([props])`

Creates a new string node.

```js
parser.string();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.tag([props])`

Creates a new tag selector.

```js
parser.tag({value: 'button'});
// => button
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.universal([props])`

Creates a new universal selector.

```js
parser.universal();
// => *
```

Arguments:

* `props (object)`: The new node's properties.

## Node types

### `node.type`

A string representation of the selector type. It can be one of the following;
`attribute`, `class`, `combinator`, `comment`, `id`, `nesting`, `pseudo`,
`root`, `selector`, `string`, `tag`, or `universal`. Note that for convenience,
these constants are exposed on the main `parser` as uppercased keys. So for
example you can get `id` by querying `parser.ID`.

```js
parser.attribute({attribute: 'href'}).type;
// => 'attribute'
```

### `node.parent`

Returns the parent node.

```js
root.nodes[0].parent === root;
```

### `node.toString()`, `String(node)`, or `'' + node`

Returns a string representation of the node.

```js
const id = parser.id({value: 'search'});
console.log(String(id));
// => #search
```

### `node.next()` & `node.prev()`

Returns the next/previous child of the parent node.

```js
const next = id.next();
if (next && next.type !== 'combinator') {
    throw new Error('Qualified IDs are not allowed!');
}
```

### `node.replaceWith(node[,...nodeN])`

Replace a node with another.

```js
const attr = selectors.first.first;
const className = parser.className({value: 'test'});
attr.replaceWith(className);
```

Arguments:

* `node`: The node to substitute the original with.
...
* `nodeN`: The node to substitute the original with.

### `node.remove()`

Removes the node from its parent node.

```js
if (node.type === 'id') {
    node.remove();
}
```

### `node.clone([opts])`

Returns a copy of a node, detached from any parent containers that the
original might have had.

```js
const cloned = node.clone();
```

### `node.isAtPosition(line, column)`

Return a `boolean` indicating whether this node includes the character at the
position of the given line and column. Returns `undefined` if the nodes lack
sufficient source metadata to determine the position.

Arguments:

* `line`: 1-index based line number relative to the start of the selector.
* `column`: 1-index based column number relative to the start of the selector.

### `node.spaces`

Extra whitespaces around the node will be moved into `node.spaces.before` and
`node.spaces.after`. So for example, these spaces will be moved as they have
no semantic meaning:

```css
      h1     ,     h2   {}
```

For descendent selectors, the value is always a single space.

```css
h1        h2 {}
```

Additional whitespace is found in either the `node.spaces.before` and `node.spaces.after` depending on the presence of comments or other whitespace characters. If the actual whitespace does not start or end with a single space, the node's raw value is set to the actual space(s) found in the source.

### `node.source`

An object describing the node's start/end, line/column source position.

Within the following CSS, the `.bar` class node ...

```css
.foo,
  .bar {}
```

... will contain the following `source` object.

```js
source: {
    start: {
        line: 2,
        column: 3
    },
    end: {
        line: 2,
        column: 6
    }
}
```

### `node.sourceIndex`

The zero-based index of the node within the original source string.

Within the following CSS, the `.baz` class node will have a `sourceIndex` of `12`.

```css
.foo, .bar, .baz {}
```

## Container types

The `root`, `selector`, and `pseudo` nodes have some helper methods for working
with their children.

### `container.nodes`

An array of the container's children.

```js
// Input: h1 h2
selectors.at(0).nodes.length   // => 3
selectors.at(0).nodes[0].value // => 'h1'
selectors.at(0).nodes[1].value // => ' '
```

### `container.first` & `container.last`

The first/last child of the container.

```js
selector.first === selector.nodes[0];
selector.last === selector.nodes[selector.nodes.length - 1];
```

### `container.at(index)`

Returns the node at position `index`.

```js
selector.at(0) === selector.first;
selector.at(0) === selector.nodes[0];
```

Arguments:

* `index`: The index of the node to return.

### `container.atPosition(line, column)`

Returns the node at the source position `line` and `column`.

```js
// Input: :not(.foo),\n#foo > :matches(ol, ul)
selector.atPosition(1, 1); // => :not(.foo)
selector.atPosition(2, 1); // => \n#foo
```

Arguments:

* `line`: The line number of the node to return.
* `column`: The column number of the node to return.

### `container.index(node)`

Return the index of the node within its container.

```js
selector.index(selector.nodes[2]) // => 2
```

Arguments:

* `node`: A node within the current container.

### `container.length`

Proxy to the length of the container's nodes.

```js
container.length === container.nodes.length
```

### `container` Array iterators

The container class provides proxies to certain Array methods; these are:

* `container.map === container.nodes.map`
* `container.reduce === container.nodes.reduce`
* `container.every === container.nodes.every`
* `container.some === container.nodes.some`
* `container.filter === container.nodes.filter`
* `container.sort === container.nodes.sort`

Note that these methods only work on a container's immediate children; recursive
iteration is provided by `container.walk`.

### `container.each(callback)`

Iterate the container's immediate children, calling `callback` for each child.
You may return `false` within the callback to break the iteration.

```js
let className;
selectors.each((selector, index) => {
    if (selector.type === 'class') {
        className = selector.value;
        return false;
    }
});
```

Note that unlike `Array#forEach()`, this iterator is safe to use whilst adding
or removing nodes from the container.

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  and `index` arguments.

### `container.walk(callback)`

Like `container#each`, but will also iterate child nodes as long as they are
`container` types.

```js
selectors.walk((selector, index) => {
    // all nodes
});
```

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  and `index` arguments.

This iterator is safe to use whilst mutating `container.nodes`,
like `container#each`.

### `container.walk` proxies

The container class provides proxy methods for iterating over types of nodes,
so that it is easier to write modules that target specific selectors. Those
methods are:

* `container.walkAttributes`
* `container.walkClasses`
* `container.walkCombinators`
* `container.walkComments`
* `container.walkIds`
* `container.walkNesting`
* `container.walkPseudos`
* `container.walkTags`
* `container.walkUniversals`

### `container.split(callback)`

This method allows you to split a group of nodes by returning `true` from
a callback. It returns an array of arrays, where each inner array corresponds
to the groups that you created via the callback.

```js
// (input) => h1 h2>>h3
const list = selectors.first.split(selector => {
    return selector.type === 'combinator';
});

// (node values) => [['h1', ' '], ['h2', '>>'], ['h3']]
```

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  as an argument.

### `container.prepend(node)` & `container.append(node)`

Add a node to the start/end of the container. Note that doing so will set
the parent property of the node to this container.

```js
const id = parser.id({value: 'search'});
selector.append(id);
```

Arguments:

* `node`: The node to add.

### `container.insertBefore(old, new[, ...newNodes])` & `container.insertAfter(old, new[, ...newNodes])`

Add a node before or after an existing node in a container:

```js
selectors.walk(selector => {
    if (selector.type !== 'class') {
        const className = parser.className({value: 'theme-name'});
        selector.parent.insertAfter(selector, className);
    }
});
```

Arguments:

* `old`: The existing node in the container.
* `new`: The new node to add before/after the existing node.

### `container.removeChild(node)`

Remove the node from the container. Note that you can also use
`node.remove()` if you would like to remove just a single node.

```js
selector.length // => 2
selector.remove(id)
selector.length // => 1;
id.parent       // undefined
```

Arguments:

* `node`: The node to remove.

### `container.removeAll()` or `container.empty()`

Remove all children from the container.

```js
selector.removeAll();
selector.length // => 0
```

## Root nodes

A root node represents a comma separated list of selectors. Indeed, all
a root's `toString()` method does is join its selector children with a ','.
Other than this, it has no special functionality and acts like a container.

### `root.trailingComma`

This will be set to `true` if the input has a trailing comma, in order to
support parsing of legacy CSS hacks.

## Selector nodes

A selector node represents a single complex selector. For example, this
selector string `h1 h2 h3, [href] > p`, is represented as two selector nodes.
It has no special functionality of its own.

## Pseudo nodes

A pseudo selector extends a container node; if it has any parameters of its
own (such as `h1:not(h2, h3)`), they will be its children. Note that the pseudo
`value` will always contain the colons preceding the pseudo identifier. This
is so that both `:before` and `::before` are properly represented in the AST.

## Attribute nodes

### `attribute.quoted`

Returns `true` if the attribute's value is wrapped in quotation marks, false if it is not.
Remains `undefined` if there is no attribute value.

```css
[href=foo] /* false */
[href='foo'] /* true */
[href="foo"] /* true */
[href] /* undefined */
```

### `attribute.qualifiedAttribute`

Returns the attribute name qualified with the namespace if one is given.

### `attribute.offsetOf(part)`

 Returns the offset of the attribute part specified relative to the
 start of the node of the output string. This is useful in raising
 error messages about a specific part of the attribute, especially
 in combination with `attribute.sourceIndex`.

 Returns `-1` if the name is invalid or the value doesn't exist in this
 attribute.

 The legal values for `part` are:

 * `"ns"` - alias for "namespace"
 * `"namespace"` - the namespace if it exists.
 * `"attribute"` - the attribute name
 * `"attributeNS"` - the start of the attribute or its namespace
 * `"operator"` - the match operator of the attribute
 * `"value"` - The value (string or identifier)
 * `"insensitive"` - the case insensitivity flag

### `attribute.raws.unquoted`

Returns the unquoted content of the attribute's value.
Remains `undefined` if there is no attribute value.

```css
[href=foo] /* foo */
[href='foo'] /* foo */
[href="foo"] /* foo */
[href] /* undefined */
```

### `attribute.spaces`

Like `node.spaces` with the `before` and `after` values containing the spaces
around the element, the parts of the attribute can also have spaces before
and after them. The for each of `attribute`, `operator`, `value` and
`insensitive` there is corresponding property of the same nam in
`node.spaces` that has an optional `before` or `after` string containing only
whitespace.

Note that corresponding values in `attributes.raws.spaces` contain values
including any comments. If set, these values will override the
`attribute.spaces` value. Take care to remove them if changing
`attribute.spaces`.

### `attribute.raws`

The raws object stores comments and other information necessary to re-render
the node exactly as it was in the source.

If a comment is embedded within the identifiers for the `namespace`, `attribute`
or `value` then a property is placed in the raws for that value containing the full source of the propery including comments.

If a comment is embedded within the space between parts of the attribute
then the raw for that space is set accordingly.

Setting an attribute's property `raws` value to be deleted.

For now, changing the spaces required also updating or removing any of the
raws values that override them.

Example: `[ /*before*/ href /* after-attr */ = /* after-operator */ te/*inside-value*/st/* wow */ /*omg*/i/*bbq*/ /*whodoesthis*/]` would parse as:

```js
{
  attribute: "href",
  operator: "=",
  value: "test",
  spaces: {
    before: '',
    after: '',
    attribute: { before: '  ', after: '  ' },
    operator: { after: '  ' },
    value: { after: ' ' },
    insensitive: { after: ' ' }
  },
  raws: {
    spaces: {
      attribute: { before: ' /*before*/ ', after: ' /* after-attr */ ' },
      operator: { after: ' /* after-operator */ ' },
      value: { after: '/* wow */ /*omg*/' },
      insensitive: { after: '/*bbq*/ /*whodoesthis*/' }
    },
    unquoted: 'test',
    value: 'te/*inside-value*/st'
  }
}
```

## `Processor`

### `ProcessorOptions`

* `lossless` - When `true`, whitespace is preserved. Defaults to `true`.
* `updateSelector` - When `true`, if any processor methods are passed a postcss
  `Rule` node instead of a string, then that Rule's selector is updated
  with the results of the processing. Defaults to `true`.

### `process|processSync(selectors, [options])`

Processes the `selectors`, returning a string from the result of processing.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

**Example:**

```js
const parser = require("postcss-selector-parser");
const processor = parser();

let result = processor.processSync(' .class');
console.log(result);
// =>  .class

// Asynchronous operation
let promise = processor.process(' .class').then(result => {
    console.log(result)
    // => .class
});

// To have the parser normalize whitespace values, utilize the options
result = processor.processSync('  .class  ', {lossless: false});
console.log(result);
// => .class

// For better syntax errors, pass a PostCSS Rule node.
const postcss = require('postcss');
rule = postcss.rule({selector: ' #foo    > a,  .class  '});
processor.process(rule, {lossless: false, updateSelector: true}).then(result => {
    console.log(result);
    // => #foo>a,.class
    console.log("rule:", rule.selector);
    // => rule: #foo>a,.class
})
```

Arguments:

* `selectors (string|postcss.Rule)`: Either a selector string or a PostCSS Rule
  node.
* `[options] (object)`: Process options


### `ast|astSync(selectors, [options])`

Like `process()` and `processSync()` but after
processing the `selectors` these methods return the `Root` node of the result
instead of a string.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

### `transform|transformSync(selectors, [options])`

Like `process()` and `processSync()` but after
processing the `selectors` these methods return the value returned by the
processor callback.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

### Error Handling Within Selector Processors

The root node passed to the selector processor callback
has a method `error(message, options)` that returns an
error object. This method should always be used to raise
errors relating to the syntax of selectors. The options
to this method are passed to postcss's error constructor
([documentation](http://postcss.org/api/#container-error)).

#### Async Error Example

```js
let processor = (root) => {
    return new Promise((resolve, reject) => {
        root.walkClasses((classNode) => {
            if (/^(.*)[-_]/.test(classNode.value)) {
                let msg = "classes may not have underscores or dashes in them";
                reject(root.error(msg, {
                    index: classNode.sourceIndex + RegExp.$1.length + 1,
                    word: classNode.value
                }));
            }
        });
        resolve();
    });
};

const postcss = require("postcss");
const parser = require("postcss-selector-parser");
const selectorProcessor = parser(processor);
const plugin = postcss.plugin('classValidator', (options) => {
    return (root) => {
        let promises = [];
        root.walkRules(rule => {
            promises.push(selectorProcessor.process(rule));
        });
        return Promise.all(promises);
    };
});
postcss(plugin()).process(`
.foo-bar {
  color: red;
}
`.trim(), {from: 'test.css'}).catch((e) => console.error(e.toString()));

// CssSyntaxError: classValidator: ./test.css:1:5: classes may not have underscores or dashes in them
//
// > 1 | .foo-bar {
//     |     ^
//   2 |   color: red;
//   3 | }
```

#### Synchronous Error Example

```js
let processor = (root) => {
    root.walkClasses((classNode) => {
        if (/.*[-_]/.test(classNode.value)) {
            let msg = "classes may not have underscores or dashes in them";
            throw root.error(msg, {
                index: classNode.sourceIndex,
                word: classNode.value
            });
        }
    });
};

const postcss = require("postcss");
const parser = require("postcss-selector-parser");
const selectorProcessor = parser(processor);
const plugin = postcss.plugin('classValidator', (options) => {
    return (root) => {
        root.walkRules(rule => {
            selectorProcessor.processSync(rule);
        });
    };
});
postcss(plugin()).process(`
.foo-bar {
  color: red;
}
`.trim(), {from: 'test.css'}).catch((e) => console.error(e.toString()));

// CssSyntaxError: classValidator: ./test.css:1:5: classes may not have underscores or dashes in them
//
// > 1 | .foo-bar {
//     |     ^
//   2 |   color: red;
//   3 | }
```


---

# 7.1.0

- feat: insert(Before|After) support multiple new node

# 7.0.0

- Feat: make insertions during iteration safe (major)

# 6.1.2

- Fixed: erroneous trailing combinators in pseudos

# 6.1.1

- Fixed: improve typings of constructor helpers (#292)

# 6.1.0

- Feature: add `sourceIndex` to `Selector` nodes (#290)

# 6.0.16

- Fixed: add missing `index` argument to `each`/`walk` callback types (#289)

# 6.0.15

- Fixed: Node#prev and Node#next type for the first/last node

# 6.0.14

- Fixed: type definitions

# 6.0.13

- Fixed: throw on unexpected pipe symbols

# 6.0.12

- Fixed: `clone` arguments should be optional

# 6.0.11

- Fixed: parse attribute case insensitivity flag

# 6.0.10

- Fixed: `isPseudoElement()` supports `:first-letter` and `:first-line`

# 6.0.9

- Fixed: `Combinator.raws` property type

# 6.0.8

- Fixed: reduced size

# 6.0.7

- Fixed: parse animation percents

# 6.0.6

- Fixed: parse quoted attributes containing a newline correctly

# 6.0.5

- Perf: rework unesc for a 63+% performance boost

# 6.0.4

- Fixed: ts errors

# 6.0.3

- Fixed: replace node built-in "util" module with "util-deprecate"
- Fixed: handle uppercase pseudo elements
- Fixed: do not create invalid combinator before comment

# 6.0.2

- Fixed an issue with parsing and stringifying an empty attribute value

# 6.0.1

- Fixed an issue with unicode surrogate pair parsing

# 6.0.0

- Updated: `cssesc` to 3.0.0 (major)
- Fixed: Issues with escaped `id` and `class` selectors

# 5.0.0

- Allow escaped dot within class name.
- Update PostCSS to 7.0.7 (patch)

# 5.0.0-rc.4

- Fixed an issue where comments immediately after an insensitive (in attribute)
  were not parsed correctly.
- Updated `cssesc` to 2.0.0 (major).
- Removed outdated integration tests.
- Added tests for custom selectors, tags with attributes, the universal
  selector with pseudos, and tokens after combinators.

# 5.0.0-rc.1

To ease adoption of the v5.0 release, we have relaxed the node version
check performed by npm at installation time to allow for node 4, which
remains officially unsupported, but likely to continue working for the
time being.

# 5.0.0-rc.0

This release has **BREAKING CHANGES** that were required to fix regressions
in 4.0.0 and to make the Combinator Node API consistent for all combinator
types. Please read carefully.

## Summary of Changes

* The way a descendent combinator that isn't a single space character (E.g. `.a  .b`) is stored in the AST has changed.
* Named Combinators (E.g. `.a /for/ .b`) are now properly parsed as a combinator.
* It is now possible to look up a node based on the source location of a character in that node and to query nodes if they contain some character.
* Several bug fixes that caused the parser to hang and run out of memory when a `/` was encountered have been fixed.
* The minimum supported version of Node is now `v6.0.0`.

### Changes to the Descendent Combinator

In prior releases, the value of a descendant combinator with multiple spaces included all the spaces.

* `.a   .b`: Extra spaces are now stored as space before.
  - Old & Busted:
    - `combinator.value === "   "`
  - New hotness:
    - `combinator.value === " " && combinator.spaces.before === "  "`
* `.a   /*comment*/.b`: A comment at the end of the combinator causes extra space to become after space.
  - Old & Busted:
    - `combinator.value === "   "`
    - `combinator.raws.value === "   /*comment/"`
  - New hotness:
    - `combinator.value === " "`
    - `combinator.spaces.after === "  "`
    - `combinator.raws.spaces.after === "  /*comment*/"`
* `.a<newline>.b`: whitespace that doesn't start or end with a single space character is stored as a raw value.
  - Old & Busted:
    - `combinator.value === "\n"`
    - `combinator.raws.value === undefined`
  - New hotness:
    - `combinator.value === " "`
    - `combinator.raws.value === "\n"`

### Support for "Named Combinators"

Although, nonstandard and unlikely to ever become a standard, combinators like `/deep/` and `/for/` are now properly supported.

Because they've been taken off the standardization track, there is no spec-official name for combinators of the form `/<ident>/`. However, I talked to [Tab Atkins](https://twitter.com/tabatkins) and we agreed to call them "named combinators" so now they are called that.

Before this release such named combinators were parsed without intention and generated three nodes of type `"tag"` where the first and last nodes had a value of `"/"`.

* `.a /for/ .b` is parsed as a combinator.
  - Old & Busted:
    - `root.nodes[0].nodes[1].type === "tag"`
    - `root.nodes[0].nodes[1].value === "/"`
  - New hotness:
    - `root.nodes[0].nodes[1].type === "combinator"`
    - `root.nodes[0].nodes[1].value === "/for/"`
* `.a /F\6fR/ .b` escapes are handled and uppercase is normalized.
  - Old & Busted:
    - `root.nodes[0].nodes[2].type === "tag"`
    - `root.nodes[0].nodes[2].value === "F\\6fR"`
  - New hotness:
    - `root.nodes[0].nodes[1].type === "combinator"`
    - `root.nodes[0].nodes[1].value === "/for/"`
    - `root.nodes[0].nodes[1].raws.value === "/F\\6fR/"`

### Source position checks and lookups

A new API was added to look up a node based on the source location.

```js
const selectorParser = require("postcss-selector-parser");
// You can find the most specific node for any given character
let combinator = selectorParser.astSync(".a > .b").atPosition(1,4);
combinator.toString() === " > ";
// You can check if a node includes a specific character
// Whitespace surrounding the node that is owned by that node
// is included in the check.
[2,3,4,5,6].map(column => combinator.isAtPosition(1, column));
// => [false, true, true, true, false]
```

# 4.0.0

This release has **BREAKING CHANGES** that were required to fix bugs regarding values with escape sequences. Please read carefully.

* **Identifiers with escapes** - CSS escape sequences are now hidden from the public API by default.
  The normal value of a node like a class name or ID, or an aspect of a node such as attribute
  selector's value, is unescaped. Escapes representing Non-ascii characters are unescaped into
  unicode characters. For example: `bu\tton, .\31 00, #i\2764\FE0Fu, [attr="value is \"quoted\""]`
  will parse respectively to the values `button`, `100`, `i❤️u`, `value is "quoted"`.
  The original escape sequences for these values can be found in the corresponding property name
  in `node.raws`. Where possible, deprecation warnings were added, but the nature
  of escape handling makes it impossible to detect what is escaped or not. Our expectation is
  that most users are neither expecting nor handling escape sequences in their use of this library,
  and so for them, this is a bug fix. Users who are taking care to handle escapes correctly can
  now update their code to remove the escape handling and let us do it for them.

* **Mutating values with escapes** - When you make an update to a node property that has escape handling
  The value is assumed to be unescaped, and any special characters are escaped automatically and
  the corresponding `raws` value is immediately updated. This can result in changes to the original
  escape format. Where the exact value of the escape sequence is important there are methods that
  allow both values to be set in conjunction. There are a number of new convenience methods for
  manipulating values that involve escapes, especially for attributes values where the quote mark
  is involved. See https://github.com/postcss/postcss-selector-parser/pull/133 for an extensive
  write-up on these changes.


**Upgrade/API Example**

In `3.x` there was no unescape handling and internal consistency of several properties was the caller's job to maintain. It was very easy for the developer
to create a CSS file that did not parse correctly when some types of values
were in use.

```js
const selectorParser = require("postcss-selector-parser");
let attr = selectorParser.attribute({attribute: "id", operator: "=", value: "a-value"});
attr.value; // => "a-value"
attr.toString(); // => [id=a-value]
// Add quotes to an attribute's value.
// All these values have to be set by the caller to be consistent:
// no internal consistency is maintained.
attr.raws.unquoted = attr.value
attr.value = "'" + attr.value + "'";
attr.value; // => "'a-value'"
attr.quoted = true;
attr.toString();  // => "[id='a-value']"
```

In `4.0` there is a convenient API for setting and mutating values
that may need escaping. Especially for attributes.

```js
const selectorParser = require("postcss-selector-parser");

// The constructor requires you specify the exact escape sequence
let className = selectorParser.className({value: "illegal class name", raws: {value: "illegal\\ class\\ name"}});
className.toString(); // => '.illegal\\ class\\ name'

// So it's better to set the value as a property
className = selectorParser.className();
// Most properties that deal with identifiers work like this
className.value = "escape for me";
className.value; // => 'escape for me'
className.toString(); // => '.escape\\ for\\ me'

// emoji and all non-ascii are escaped to ensure it works in every css file.
className.value = "😱🦄😍";
className.value; // => '😱🦄😍'
className.toString(); // => '.\\1F631\\1F984\\1F60D'

// you can control the escape sequence if you want, or do bad bad things
className.setPropertyAndEscape('value', 'xxxx', 'yyyy');
className.value; // => "xxxx"
className.toString(); // => ".yyyy"

// Pass a value directly through to the css output without escaping it. 
className.setPropertyWithoutEscape('value', '$REPLACE_ME$');
className.value; // => "$REPLACE_ME$"
className.toString(); // => ".$REPLACE_ME$"

// The biggest changes are to the Attribute class
// passing quoteMark explicitly is required to avoid a deprecation warning.
let attr = selectorParser.attribute({attribute: "id", operator: "=", value: "a-value", quoteMark: null});
attr.toString(); // => "[id=a-value]"
// Get the value with quotes on it and any necessary escapes.
// This is the same as reading attr.value in 3.x.
attr.getQuotedValue(); // => "a-value";
attr.quoteMark; // => null

// Add quotes to an attribute's value.
attr.quoteMark = "'"; // This is all that's required.
attr.toString(); // => "[id='a-value']"
attr.quoted; // => true
// The value is still the same, only the quotes have changed.
attr.value; // => a-value
attr.getQuotedValue(); // => "'a-value'";

// deprecated assignment, no warning because there's no escapes
attr.value = "new-value";
// no quote mark is needed so it is removed
attr.getQuotedValue(); // => "new-value";

// deprecated assignment, 
attr.value = "\"a 'single quoted' value\"";
// > (node:27859) DeprecationWarning: Assigning an attribute a value containing characters that might need to be escaped is deprecated. Call attribute.setValue() instead.
attr.getQuotedValue(); // => '"a \'single quoted\' value"';
// quote mark inferred from first and last characters.
attr.quoteMark; // => '"'

// setValue takes options to make manipulating the value simple.
attr.setValue('foo', {smart: true});
// foo doesn't require any escapes or quotes.
attr.toString(); // => '[id=foo]'
attr.quoteMark; // => null 

// An explicit quote mark can be specified
attr.setValue('foo', {quoteMark: '"'});
attr.toString(); // => '[id="foo"]'

// preserves quote mark by default
attr.setValue('bar');
attr.toString(); // => '[id="bar"]'
attr.quoteMark = null;
attr.toString(); // => '[id=bar]'

// with no arguments, it preserves quote mark even when it's not a great idea
attr.setValue('a value \n that should be quoted');
attr.toString(); // => '[id=a\\ value\\ \\A\\ that\\ should\\ be\\ quoted]'

// smart preservation with a specified default
attr.setValue('a value \n that should be quoted', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => "[id='a value \\A  that should be quoted']"
attr.quoteMark = '"';
// => '[id="a value \\A  that should be quoted"]'

// this keeps double quotes because it wants to quote the value and the existing value has double quotes.
attr.setValue('this should be quoted', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => '[id="this should be quoted"]'

// picks single quotes because the value has double quotes
attr.setValue('a "double quoted" value', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => "[id='a "double quoted" value']"

// setPropertyAndEscape lets you do anything you want. Even things that are a bad idea and illegal.
attr.setPropertyAndEscape('value', 'xxxx', 'the password is 42');
attr.value; // => "xxxx"
attr.toString(); // => "[id=the password is 42]"

// Pass a value directly through to the css output without escaping it. 
attr.setPropertyWithoutEscape('value', '$REPLACEMENT$');
attr.value; // => "$REPLACEMENT$"
attr.toString(); // => "[id=$REPLACEMENT$]"
```

# 3.1.2

* Fix: Removed dot-prop dependency since it's no longer written in es5.

# 3.1.1

* Fix: typescript definitions weren't in the published package.

# 3.1.0

* Fixed numerous bugs in attribute nodes relating to the handling of comments
  and whitespace. There's significant changes to `attrNode.spaces` and `attrNode.raws` since the `3.0.0` release.
* Added `Attribute#offsetOf(part)` to get the offset location of
  attribute parts like `"operator"` and `"value"`. This is most
  often added to `Attribute#sourceIndex` for error reporting.

# 3.0.0

## Breaking changes

* Some tweaks to the tokenizer/attribute selector parsing mean that whitespace
  locations might be slightly different to the 2.x code.
* Better attribute selector parsing with more validation; postcss-selector-parser
  no longer uses regular expressions to parse attribute selectors.
* Added an async API (thanks to @jacobp100); the default `process` API is now
  async, and the sync API is now accessed through `processSync` instead.
* `process()` and `processSync()` now return a string instead of the Processor
  instance.
* Tweaks handling of Less interpolation (thanks to @jwilsson).
* Removes support for Node 0.12.

## Other changes

* `ast()` and `astSync()` methods have been added to the `Processor`. These
  return the `Root` node of the selectors after processing them.
* `transform()` and `transformSync()` methods have been added to the
  `Processor`. These return the value returned by the processor callback
  after processing the selectors.
* Set the parent when inserting a node (thanks to @chriseppstein).
* Correctly adjust indices when using insertBefore/insertAfter (thanks to @tivac).
* Fixes handling of namespaces with qualified tag selectors.
* `process`, `ast` and `transform` (and their sync variants) now accept a
  `postcss` rule node. When provided, better errors are generated and selector
  processing is automatically set back to the rule selector (unless the `updateSelector` option is set to `false`.)
* Now more memory efficient when tokenizing selectors.

### Upgrade hints

The pattern of:

`rule.selector = processor.process(rule.selector).result.toString();`

is now:

`processor.processSync(rule)`

# 2.2.3

* Resolves an issue where the parser would not reduce multiple spaces between an
  ampersand and another simple selector in lossy mode (thanks to @adam-26).

# 2.2.2

* No longer hangs on an unescaped semicolon; instead the parser will throw
  an exception for these cases.

# 2.2.1

* Allows a consumer to specify whitespace tokens when creating a new Node
  (thanks to @Semigradsky).

# 2.2.0

* Added a new option to normalize whitespace when parsing the selector string
  (thanks to @adam-26).

# 2.1.1

* Better unquoted value handling within attribute selectors
  (thanks to @evilebottnawi).

# 2.1.0

* Added: Use string constants for all node types & expose them on the main
  parser instance (thanks to @Aweary).

# 2.0.0

This release contains the following breaking changes:

* Renamed all `eachInside` iterators to `walk`. For example, `eachTag` is now
  `walkTags`, and `eachInside` is now `walk`.
* Renamed `Node#removeSelf()` to `Node#remove()`.
* Renamed `Container#remove()` to `Container#removeChild()`.
* Renamed `Node#raw` to `Node#raws` (thanks to @davidtheclark).
* Now parses `&` as the *nesting* selector, rather than a *tag* selector.
* Fixes misinterpretation of Sass interpolation (e.g. `#{foo}`) as an
  id selector (thanks to @davidtheclark).

and;

* Fixes parsing of attribute selectors with equals signs in them
  (e.g. `[data-attr="foo=bar"]`) (thanks to @montmanu).
* Adds `quoted` and `raw.unquoted` properties to attribute nodes
  (thanks to @davidtheclark).

# 1.3.3

* Fixes an infinite loop on `)` and `]` tokens when they had no opening pairs.
  Now postcss-selector-parser will throw when it encounters these lone tokens.

# 1.3.2

* Now uses plain integers rather than `str.charCodeAt(0)` for compiled builds.

# 1.3.1

* Update flatten to v1.x (thanks to @shinnn).

# 1.3.0

* Adds a new node type, `String`, to fix a crash on selectors such as
  `foo:bar("test")`.

# 1.2.1

* Fixes a crash when the parser encountered a trailing combinator.

# 1.2.0

* A more descriptive error is thrown when the parser expects to find a
  pseudo-class/pseudo-element (thanks to @ashelley).
* Adds support for line/column locations for selector nodes, as well as a
  `Node#sourceIndex` method (thanks to @davidtheclark).

# 1.1.4

* Fixes a crash when a selector started with a `>` combinator. The module will
  now no longer throw if a selector has a leading/trailing combinator node.

# 1.1.3

* Fixes a crash on `@` tokens.

# 1.1.2

* Fixes an infinite loop caused by using parentheses in a non-pseudo element
  context.

# 1.1.1

* Fixes a crash when a backslash ended a selector string.

# 1.1.0

* Adds support for replacing multiple nodes at once with `replaceWith`
  (thanks to @jonathantneal).
* Parser no longer throws on sequential IDs and trailing commas, to support
  parsing of selector hacks.

# 1.0.1

* Fixes using `insertAfter` and `insertBefore` during iteration.

# 1.0.0

* Adds `clone` and `replaceWith` methods to nodes.
* Adds `insertBefore` and `insertAfter` to containers.
* Stabilises API.

# 0.0.5

* Fixes crash on extra whitespace inside a pseudo selector's parentheses.
* Adds sort function to the container class.
* Enables the parser to pass its input through without transforming.
* Iteration-safe `each` and `eachInside`.

# 0.0.4

* Tidy up redundant duplication.
* Fixes a bug where the parser would loop infinitely on universal selectors
  inside pseudo selectors.
* Adds `length` getter and `eachInside`, `map`, `reduce` to the container class.
* When a selector has been removed from the tree, the root node will no longer
  cast it to a string.
* Adds node type iterators to the container class (e.g. `eachComment`).
* Adds filter function to the container class.
* Adds split function to the container class.
* Create new node types by doing `parser.id(opts)` etc.
* Adds support for pseudo classes anywhere in the selector.

# 0.0.3

* Adds `next` and `prev` to the node class.
* Adds `first` and `last` getters to the container class.
* Adds `every` and `some` iterators to the container class.
* Add `empty` alias for `removeAll`.
* Combinators are now types of node.
* Fixes the at method so that it is not an alias for `index`.
* Tidy up creation of new nodes in the parser.
* Refactors how namespaces are handled for consistency & less redundant code.
* Refactors AST to use `nodes` exclusively, and eliminates excessive nesting.
* Fixes nested pseudo parsing.
* Fixes whitespace parsing.

# 0.0.2

* Adds support for namespace selectors.
* Adds support for selectors joined by escaped spaces - such as `.\31\ 0`.

# 0.0.1

* Initial release.


---

# postcss-selector-parser [![test](https://github.com/postcss/postcss-selector-parser/actions/workflows/test.yml/badge.svg)](https://github.com/postcss/postcss-selector-parser/actions/workflows/test.yml)

> Selector parser with built in methods for working with selector strings.

## Install

With [npm](https://npmjs.com/package/postcss-selector-parser) do:

```
npm install postcss-selector-parser
```

## Quick Start

```js
const parser = require('postcss-selector-parser');
const transform = selectors => {
    selectors.walk(selector => {
        // do something with the selector
        console.log(String(selector))
    });
};

const transformed = parser(transform).processSync('h1, h2, h3');
```

To normalize selector whitespace:

```js
const parser = require('postcss-selector-parser');
const normalized = parser().processSync('h1, h2, h3', {lossless: false});
// -> h1,h2,h3
```

Async support is provided through `parser.process` and will resolve a Promise
with the resulting selector string.

## API

Please see [API.md](API.md).

## Credits

* Huge thanks to Andrey Sitnik (@ai) for work on PostCSS which helped
  accelerate this module's development.

## License

MIT


---

# Changes to PostCSS Dir Pseudo Class

### 9.0.1

_October 23, 2024_

- Updated: `postcss-selector-parser`

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-dir-pseudo-class/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Dir Pseudo Class [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install postcss-dir-pseudo-class --save-dev`

[PostCSS Dir Pseudo Class] lets you style by directionality using the `:dir()`
pseudo-class in CSS, following the [Selectors] specification.

```pcss
article h3:dir(rtl) {
	margin-right: 10px;
}

article h3:dir(ltr) {
	margin-left: 10px;
}

/* becomes */

[dir="rtl"] article h3 {
	margin-right: 10px;
}

[dir="ltr"] article h3 {
	margin-left: 10px;
}
```

### Maintaining Specificity

Using [PostCSS Dir Pseudo Class] will not impact selector weight, but it will
require having at least one `[dir]` attribute in your HTML. If you don’t have
_any_ `[dir]` attributes, consider using the following JavaScript:

```js
// force at least one dir attribute (this can run at any time)
document.documentElement.dir=document.documentElement.dir||'ltr';
```

If you absolutely cannot add a `[dir]` attribute in your HTML or even force one
via JavaScript, you can still work around this by presuming a direction in your
CSS using the [`dir` option](#dir), but understand that this will
sometimes increase selector weight by one element (`html`).

## Usage

Add [PostCSS Dir Pseudo Class] to your project:

```bash
npm install postcss postcss-dir-pseudo-class --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssDirPseudoClass = require('postcss-dir-pseudo-class');

postcss([
	postcssDirPseudoClass(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## Options

### preserve

The `preserve` option determines whether the original notation
is preserved. By default, it is not preserved.

```js
postcssDirPseudoClass({ preserve: true })
```

```pcss
article h3:dir(rtl) {
	margin-right: 10px;
}

article h3:dir(ltr) {
	margin-left: 10px;
}

/* becomes */

[dir="rtl"] article h3 {
	margin-right: 10px;
}

article h3:dir(rtl) {
	margin-right: 10px;
}

[dir="ltr"] article h3 {
	margin-left: 10px;
}

article h3:dir(ltr) {
	margin-left: 10px;
}
```

### dir

The `dir` option allows you presume a direction in your CSS. By default, this
is not specified and you are required to include a direction `[dir]` attribute
somewhere in your HTML, preferably on the `html` element.

```js
postcssDirPseudoClass({ dir: 'ltr' });
```

```pcss
article h3:dir(rtl) {
	margin-right: 10px;
}

article h3:dir(ltr) {
	margin-left: 10px;
}

/* becomes */

[dir="rtl"] article h3 {
	margin-right: 10px;
}

html:not([dir="rtl"]) article h3 {
	margin-left: 10px;
}
```

```js
postcssDirPseudoClass({ dir: 'rtl' });
```

```pcss
article h3:dir(rtl) {
	margin-right: 10px;
}

article h3:dir(ltr) {
	margin-left: 10px;
}

/* becomes */

html:not([dir="ltr"]) article h3 {
	margin-right: 10px;
}

[dir="ltr"] article h3 {
	margin-left: 10px;
}
```

### shadow

The `shadow` option determines whether the CSS is assumed to be used in Shadow DOM with Custom Elements.

```js
postcssDirPseudoClass({ shadow: true })
```

```pcss
article h3:dir(rtl) {
	margin-right: 10px;
}

article h3:dir(ltr) {
	margin-left: 10px;
}

/* becomes */

:host-context([dir="rtl"]) article h3 {
	margin-right: 10px;
}

:host-context([dir="ltr"]) article h3 {
	margin-left: 10px;
}
```

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#dir-pseudo-class
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/postcss-dir-pseudo-class

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Dir Pseudo Class]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-dir-pseudo-class
[Selectors]: https://www.w3.org/TR/selectors-4/#the-dir-pseudo


---

# API Documentation

*Please use only this documented API when working with the parser. Methods
not documented here are subject to change at any point.*

## `parser` function

This is the module's main entry point.

```js
const parser = require('postcss-selector-parser');
```

### `parser([transform], [options])`

Creates a new `processor` instance

```js
const processor = parser();
```

Or, with optional transform function

```js
const transform = selectors => {
    selectors.walkUniversals(selector => {
        selector.remove();
    });
};

const processor = parser(transform)

// Example
const result = processor.processSync('*.class');
// => .class
```

[See processor documentation](#processor)

Arguments:

* `transform (function)`: Provide a function to work with the parsed AST.
* `options (object)`: Provide default options for all calls on the returned `Processor`.

### `parser.attribute([props])`

Creates a new attribute selector.

```js
parser.attribute({attribute: 'href'});
// => [href]
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.className([props])`

Creates a new class selector.

```js
parser.className({value: 'button'});
// => .button
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.combinator([props])`

Creates a new selector combinator.

```js
parser.combinator({value: '+'});
// => +
```

Arguments:

* `props (object)`: The new node's properties.

Notes:
* **Descendant Combinators** The value of descendant combinators created by the
  parser always just a single space (`" "`). For descendant selectors with no
  comments, additional space is now stored in `node.spaces.before`. Depending
  on the location of comments, additional spaces may be stored in
  `node.raws.spaces.before`, `node.raws.spaces.after`, or `node.raws.value`.
* **Named Combinators** Although, nonstandard and unlikely to ever become a standard,
  named combinators like `/deep/` and `/for/` are parsed as combinators. The
  `node.value` is name after being unescaped and normalized as lowercase. The
  original value for the combinator name is stored in `node.raws.value`.


### `parser.comment([props])`

Creates a new comment.

```js
parser.comment({value: '/* Affirmative, Dave. I read you. */'});
// => /* Affirmative, Dave. I read you. */
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.id([props])`

Creates a new id selector.

```js
parser.id({value: 'search'});
// => #search
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.nesting([props])`

Creates a new nesting selector.

```js
parser.nesting();
// => &
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.pseudo([props])`

Creates a new pseudo selector.

```js
parser.pseudo({value: '::before'});
// => ::before
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.root([props])`

Creates a new root node.

```js
parser.root();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.selector([props])`

Creates a new selector node.

```js
parser.selector();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.string([props])`

Creates a new string node.

```js
parser.string();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.tag([props])`

Creates a new tag selector.

```js
parser.tag({value: 'button'});
// => button
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.universal([props])`

Creates a new universal selector.

```js
parser.universal();
// => *
```

Arguments:

* `props (object)`: The new node's properties.

## Node types

### `node.type`

A string representation of the selector type. It can be one of the following;
`attribute`, `class`, `combinator`, `comment`, `id`, `nesting`, `pseudo`,
`root`, `selector`, `string`, `tag`, or `universal`. Note that for convenience,
these constants are exposed on the main `parser` as uppercased keys. So for
example you can get `id` by querying `parser.ID`.

```js
parser.attribute({attribute: 'href'}).type;
// => 'attribute'
```

### `node.parent`

Returns the parent node.

```js
root.nodes[0].parent === root;
```

### `node.toString()`, `String(node)`, or `'' + node`

Returns a string representation of the node.

```js
const id = parser.id({value: 'search'});
console.log(String(id));
// => #search
```

### `node.next()` & `node.prev()`

Returns the next/previous child of the parent node.

```js
const next = id.next();
if (next && next.type !== 'combinator') {
    throw new Error('Qualified IDs are not allowed!');
}
```

### `node.replaceWith(node[,...nodeN])`

Replace a node with another.

```js
const attr = selectors.first.first;
const className = parser.className({value: 'test'});
attr.replaceWith(className);
```

Arguments:

* `node`: The node to substitute the original with.
...
* `nodeN`: The node to substitute the original with.

### `node.remove()`

Removes the node from its parent node.

```js
if (node.type === 'id') {
    node.remove();
}
```

### `node.clone([opts])`

Returns a copy of a node, detached from any parent containers that the
original might have had.

```js
const cloned = node.clone();
```

### `node.isAtPosition(line, column)`

Return a `boolean` indicating whether this node includes the character at the
position of the given line and column. Returns `undefined` if the nodes lack
sufficient source metadata to determine the position.

Arguments:

* `line`: 1-index based line number relative to the start of the selector.
* `column`: 1-index based column number relative to the start of the selector.

### `node.spaces`

Extra whitespaces around the node will be moved into `node.spaces.before` and
`node.spaces.after`. So for example, these spaces will be moved as they have
no semantic meaning:

```css
      h1     ,     h2   {}
```

For descendent selectors, the value is always a single space.

```css
h1        h2 {}
```

Additional whitespace is found in either the `node.spaces.before` and `node.spaces.after` depending on the presence of comments or other whitespace characters. If the actual whitespace does not start or end with a single space, the node's raw value is set to the actual space(s) found in the source.

### `node.source`

An object describing the node's start/end, line/column source position.

Within the following CSS, the `.bar` class node ...

```css
.foo,
  .bar {}
```

... will contain the following `source` object.

```js
source: {
    start: {
        line: 2,
        column: 3
    },
    end: {
        line: 2,
        column: 6
    }
}
```

### `node.sourceIndex`

The zero-based index of the node within the original source string.

Within the following CSS, the `.baz` class node will have a `sourceIndex` of `12`.

```css
.foo, .bar, .baz {}
```

## Container types

The `root`, `selector`, and `pseudo` nodes have some helper methods for working
with their children.

### `container.nodes`

An array of the container's children.

```js
// Input: h1 h2
selectors.at(0).nodes.length   // => 3
selectors.at(0).nodes[0].value // => 'h1'
selectors.at(0).nodes[1].value // => ' '
```

### `container.first` & `container.last`

The first/last child of the container.

```js
selector.first === selector.nodes[0];
selector.last === selector.nodes[selector.nodes.length - 1];
```

### `container.at(index)`

Returns the node at position `index`.

```js
selector.at(0) === selector.first;
selector.at(0) === selector.nodes[0];
```

Arguments:

* `index`: The index of the node to return.

### `container.atPosition(line, column)`

Returns the node at the source position `line` and `column`.

```js
// Input: :not(.foo),\n#foo > :matches(ol, ul)
selector.atPosition(1, 1); // => :not(.foo)
selector.atPosition(2, 1); // => \n#foo
```

Arguments:

* `line`: The line number of the node to return.
* `column`: The column number of the node to return.

### `container.index(node)`

Return the index of the node within its container.

```js
selector.index(selector.nodes[2]) // => 2
```

Arguments:

* `node`: A node within the current container.

### `container.length`

Proxy to the length of the container's nodes.

```js
container.length === container.nodes.length
```

### `container` Array iterators

The container class provides proxies to certain Array methods; these are:

* `container.map === container.nodes.map`
* `container.reduce === container.nodes.reduce`
* `container.every === container.nodes.every`
* `container.some === container.nodes.some`
* `container.filter === container.nodes.filter`
* `container.sort === container.nodes.sort`

Note that these methods only work on a container's immediate children; recursive
iteration is provided by `container.walk`.

### `container.each(callback)`

Iterate the container's immediate children, calling `callback` for each child.
You may return `false` within the callback to break the iteration.

```js
let className;
selectors.each((selector, index) => {
    if (selector.type === 'class') {
        className = selector.value;
        return false;
    }
});
```

Note that unlike `Array#forEach()`, this iterator is safe to use whilst adding
or removing nodes from the container.

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  and `index` arguments.

### `container.walk(callback)`

Like `container#each`, but will also iterate child nodes as long as they are
`container` types.

```js
selectors.walk((selector, index) => {
    // all nodes
});
```

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  and `index` arguments.

This iterator is safe to use whilst mutating `container.nodes`,
like `container#each`.

### `container.walk` proxies

The container class provides proxy methods for iterating over types of nodes,
so that it is easier to write modules that target specific selectors. Those
methods are:

* `container.walkAttributes`
* `container.walkClasses`
* `container.walkCombinators`
* `container.walkComments`
* `container.walkIds`
* `container.walkNesting`
* `container.walkPseudos`
* `container.walkTags`
* `container.walkUniversals`

### `container.split(callback)`

This method allows you to split a group of nodes by returning `true` from
a callback. It returns an array of arrays, where each inner array corresponds
to the groups that you created via the callback.

```js
// (input) => h1 h2>>h3
const list = selectors.first.split(selector => {
    return selector.type === 'combinator';
});

// (node values) => [['h1', ' '], ['h2', '>>'], ['h3']]
```

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  as an argument.

### `container.prepend(node)` & `container.append(node)`

Add a node to the start/end of the container. Note that doing so will set
the parent property of the node to this container.

```js
const id = parser.id({value: 'search'});
selector.append(id);
```

Arguments:

* `node`: The node to add.

### `container.insertBefore(old, new[, ...newNodes])` & `container.insertAfter(old, new[, ...newNodes])`

Add a node before or after an existing node in a container:

```js
selectors.walk(selector => {
    if (selector.type !== 'class') {
        const className = parser.className({value: 'theme-name'});
        selector.parent.insertAfter(selector, className);
    }
});
```

Arguments:

* `old`: The existing node in the container.
* `new`: The new node to add before/after the existing node.

### `container.removeChild(node)`

Remove the node from the container. Note that you can also use
`node.remove()` if you would like to remove just a single node.

```js
selector.length // => 2
selector.remove(id)
selector.length // => 1;
id.parent       // undefined
```

Arguments:

* `node`: The node to remove.

### `container.removeAll()` or `container.empty()`

Remove all children from the container.

```js
selector.removeAll();
selector.length // => 0
```

## Root nodes

A root node represents a comma separated list of selectors. Indeed, all
a root's `toString()` method does is join its selector children with a ','.
Other than this, it has no special functionality and acts like a container.

### `root.trailingComma`

This will be set to `true` if the input has a trailing comma, in order to
support parsing of legacy CSS hacks.

## Selector nodes

A selector node represents a single complex selector. For example, this
selector string `h1 h2 h3, [href] > p`, is represented as two selector nodes.
It has no special functionality of its own.

## Pseudo nodes

A pseudo selector extends a container node; if it has any parameters of its
own (such as `h1:not(h2, h3)`), they will be its children. Note that the pseudo
`value` will always contain the colons preceding the pseudo identifier. This
is so that both `:before` and `::before` are properly represented in the AST.

## Attribute nodes

### `attribute.quoted`

Returns `true` if the attribute's value is wrapped in quotation marks, false if it is not.
Remains `undefined` if there is no attribute value.

```css
[href=foo] /* false */
[href='foo'] /* true */
[href="foo"] /* true */
[href] /* undefined */
```

### `attribute.qualifiedAttribute`

Returns the attribute name qualified with the namespace if one is given.

### `attribute.offsetOf(part)`

 Returns the offset of the attribute part specified relative to the
 start of the node of the output string. This is useful in raising
 error messages about a specific part of the attribute, especially
 in combination with `attribute.sourceIndex`.

 Returns `-1` if the name is invalid or the value doesn't exist in this
 attribute.

 The legal values for `part` are:

 * `"ns"` - alias for "namespace"
 * `"namespace"` - the namespace if it exists.
 * `"attribute"` - the attribute name
 * `"attributeNS"` - the start of the attribute or its namespace
 * `"operator"` - the match operator of the attribute
 * `"value"` - The value (string or identifier)
 * `"insensitive"` - the case insensitivity flag

### `attribute.raws.unquoted`

Returns the unquoted content of the attribute's value.
Remains `undefined` if there is no attribute value.

```css
[href=foo] /* foo */
[href='foo'] /* foo */
[href="foo"] /* foo */
[href] /* undefined */
```

### `attribute.spaces`

Like `node.spaces` with the `before` and `after` values containing the spaces
around the element, the parts of the attribute can also have spaces before
and after them. The for each of `attribute`, `operator`, `value` and
`insensitive` there is corresponding property of the same nam in
`node.spaces` that has an optional `before` or `after` string containing only
whitespace.

Note that corresponding values in `attributes.raws.spaces` contain values
including any comments. If set, these values will override the
`attribute.spaces` value. Take care to remove them if changing
`attribute.spaces`.

### `attribute.raws`

The raws object stores comments and other information necessary to re-render
the node exactly as it was in the source.

If a comment is embedded within the identifiers for the `namespace`, `attribute`
or `value` then a property is placed in the raws for that value containing the full source of the propery including comments.

If a comment is embedded within the space between parts of the attribute
then the raw for that space is set accordingly.

Setting an attribute's property `raws` value to be deleted.

For now, changing the spaces required also updating or removing any of the
raws values that override them.

Example: `[ /*before*/ href /* after-attr */ = /* after-operator */ te/*inside-value*/st/* wow */ /*omg*/i/*bbq*/ /*whodoesthis*/]` would parse as:

```js
{
  attribute: "href",
  operator: "=",
  value: "test",
  spaces: {
    before: '',
    after: '',
    attribute: { before: '  ', after: '  ' },
    operator: { after: '  ' },
    value: { after: ' ' },
    insensitive: { after: ' ' }
  },
  raws: {
    spaces: {
      attribute: { before: ' /*before*/ ', after: ' /* after-attr */ ' },
      operator: { after: ' /* after-operator */ ' },
      value: { after: '/* wow */ /*omg*/' },
      insensitive: { after: '/*bbq*/ /*whodoesthis*/' }
    },
    unquoted: 'test',
    value: 'te/*inside-value*/st'
  }
}
```

## `Processor`

### `ProcessorOptions`

* `lossless` - When `true`, whitespace is preserved. Defaults to `true`.
* `updateSelector` - When `true`, if any processor methods are passed a postcss
  `Rule` node instead of a string, then that Rule's selector is updated
  with the results of the processing. Defaults to `true`.

### `process|processSync(selectors, [options])`

Processes the `selectors`, returning a string from the result of processing.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

**Example:**

```js
const parser = require("postcss-selector-parser");
const processor = parser();

let result = processor.processSync(' .class');
console.log(result);
// =>  .class

// Asynchronous operation
let promise = processor.process(' .class').then(result => {
    console.log(result)
    // => .class
});

// To have the parser normalize whitespace values, utilize the options
result = processor.processSync('  .class  ', {lossless: false});
console.log(result);
// => .class

// For better syntax errors, pass a PostCSS Rule node.
const postcss = require('postcss');
rule = postcss.rule({selector: ' #foo    > a,  .class  '});
processor.process(rule, {lossless: false, updateSelector: true}).then(result => {
    console.log(result);
    // => #foo>a,.class
    console.log("rule:", rule.selector);
    // => rule: #foo>a,.class
})
```

Arguments:

* `selectors (string|postcss.Rule)`: Either a selector string or a PostCSS Rule
  node.
* `[options] (object)`: Process options


### `ast|astSync(selectors, [options])`

Like `process()` and `processSync()` but after
processing the `selectors` these methods return the `Root` node of the result
instead of a string.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

### `transform|transformSync(selectors, [options])`

Like `process()` and `processSync()` but after
processing the `selectors` these methods return the value returned by the
processor callback.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

### Error Handling Within Selector Processors

The root node passed to the selector processor callback
has a method `error(message, options)` that returns an
error object. This method should always be used to raise
errors relating to the syntax of selectors. The options
to this method are passed to postcss's error constructor
([documentation](http://postcss.org/api/#container-error)).

#### Async Error Example

```js
let processor = (root) => {
    return new Promise((resolve, reject) => {
        root.walkClasses((classNode) => {
            if (/^(.*)[-_]/.test(classNode.value)) {
                let msg = "classes may not have underscores or dashes in them";
                reject(root.error(msg, {
                    index: classNode.sourceIndex + RegExp.$1.length + 1,
                    word: classNode.value
                }));
            }
        });
        resolve();
    });
};

const postcss = require("postcss");
const parser = require("postcss-selector-parser");
const selectorProcessor = parser(processor);
const plugin = postcss.plugin('classValidator', (options) => {
    return (root) => {
        let promises = [];
        root.walkRules(rule => {
            promises.push(selectorProcessor.process(rule));
        });
        return Promise.all(promises);
    };
});
postcss(plugin()).process(`
.foo-bar {
  color: red;
}
`.trim(), {from: 'test.css'}).catch((e) => console.error(e.toString()));

// CssSyntaxError: classValidator: ./test.css:1:5: classes may not have underscores or dashes in them
//
// > 1 | .foo-bar {
//     |     ^
//   2 |   color: red;
//   3 | }
```

#### Synchronous Error Example

```js
let processor = (root) => {
    root.walkClasses((classNode) => {
        if (/.*[-_]/.test(classNode.value)) {
            let msg = "classes may not have underscores or dashes in them";
            throw root.error(msg, {
                index: classNode.sourceIndex,
                word: classNode.value
            });
        }
    });
};

const postcss = require("postcss");
const parser = require("postcss-selector-parser");
const selectorProcessor = parser(processor);
const plugin = postcss.plugin('classValidator', (options) => {
    return (root) => {
        root.walkRules(rule => {
            selectorProcessor.processSync(rule);
        });
    };
});
postcss(plugin()).process(`
.foo-bar {
  color: red;
}
`.trim(), {from: 'test.css'}).catch((e) => console.error(e.toString()));

// CssSyntaxError: classValidator: ./test.css:1:5: classes may not have underscores or dashes in them
//
// > 1 | .foo-bar {
//     |     ^
//   2 |   color: red;
//   3 | }
```


---

# 7.1.0

- feat: insert(Before|After) support multiple new node

# 7.0.0

- Feat: make insertions during iteration safe (major)

# 6.1.2

- Fixed: erroneous trailing combinators in pseudos

# 6.1.1

- Fixed: improve typings of constructor helpers (#292)

# 6.1.0

- Feature: add `sourceIndex` to `Selector` nodes (#290)

# 6.0.16

- Fixed: add missing `index` argument to `each`/`walk` callback types (#289)

# 6.0.15

- Fixed: Node#prev and Node#next type for the first/last node

# 6.0.14

- Fixed: type definitions

# 6.0.13

- Fixed: throw on unexpected pipe symbols

# 6.0.12

- Fixed: `clone` arguments should be optional

# 6.0.11

- Fixed: parse attribute case insensitivity flag

# 6.0.10

- Fixed: `isPseudoElement()` supports `:first-letter` and `:first-line`

# 6.0.9

- Fixed: `Combinator.raws` property type

# 6.0.8

- Fixed: reduced size

# 6.0.7

- Fixed: parse animation percents

# 6.0.6

- Fixed: parse quoted attributes containing a newline correctly

# 6.0.5

- Perf: rework unesc for a 63+% performance boost

# 6.0.4

- Fixed: ts errors

# 6.0.3

- Fixed: replace node built-in "util" module with "util-deprecate"
- Fixed: handle uppercase pseudo elements
- Fixed: do not create invalid combinator before comment

# 6.0.2

- Fixed an issue with parsing and stringifying an empty attribute value

# 6.0.1

- Fixed an issue with unicode surrogate pair parsing

# 6.0.0

- Updated: `cssesc` to 3.0.0 (major)
- Fixed: Issues with escaped `id` and `class` selectors

# 5.0.0

- Allow escaped dot within class name.
- Update PostCSS to 7.0.7 (patch)

# 5.0.0-rc.4

- Fixed an issue where comments immediately after an insensitive (in attribute)
  were not parsed correctly.
- Updated `cssesc` to 2.0.0 (major).
- Removed outdated integration tests.
- Added tests for custom selectors, tags with attributes, the universal
  selector with pseudos, and tokens after combinators.

# 5.0.0-rc.1

To ease adoption of the v5.0 release, we have relaxed the node version
check performed by npm at installation time to allow for node 4, which
remains officially unsupported, but likely to continue working for the
time being.

# 5.0.0-rc.0

This release has **BREAKING CHANGES** that were required to fix regressions
in 4.0.0 and to make the Combinator Node API consistent for all combinator
types. Please read carefully.

## Summary of Changes

* The way a descendent combinator that isn't a single space character (E.g. `.a  .b`) is stored in the AST has changed.
* Named Combinators (E.g. `.a /for/ .b`) are now properly parsed as a combinator.
* It is now possible to look up a node based on the source location of a character in that node and to query nodes if they contain some character.
* Several bug fixes that caused the parser to hang and run out of memory when a `/` was encountered have been fixed.
* The minimum supported version of Node is now `v6.0.0`.

### Changes to the Descendent Combinator

In prior releases, the value of a descendant combinator with multiple spaces included all the spaces.

* `.a   .b`: Extra spaces are now stored as space before.
  - Old & Busted:
    - `combinator.value === "   "`
  - New hotness:
    - `combinator.value === " " && combinator.spaces.before === "  "`
* `.a   /*comment*/.b`: A comment at the end of the combinator causes extra space to become after space.
  - Old & Busted:
    - `combinator.value === "   "`
    - `combinator.raws.value === "   /*comment/"`
  - New hotness:
    - `combinator.value === " "`
    - `combinator.spaces.after === "  "`
    - `combinator.raws.spaces.after === "  /*comment*/"`
* `.a<newline>.b`: whitespace that doesn't start or end with a single space character is stored as a raw value.
  - Old & Busted:
    - `combinator.value === "\n"`
    - `combinator.raws.value === undefined`
  - New hotness:
    - `combinator.value === " "`
    - `combinator.raws.value === "\n"`

### Support for "Named Combinators"

Although, nonstandard and unlikely to ever become a standard, combinators like `/deep/` and `/for/` are now properly supported.

Because they've been taken off the standardization track, there is no spec-official name for combinators of the form `/<ident>/`. However, I talked to [Tab Atkins](https://twitter.com/tabatkins) and we agreed to call them "named combinators" so now they are called that.

Before this release such named combinators were parsed without intention and generated three nodes of type `"tag"` where the first and last nodes had a value of `"/"`.

* `.a /for/ .b` is parsed as a combinator.
  - Old & Busted:
    - `root.nodes[0].nodes[1].type === "tag"`
    - `root.nodes[0].nodes[1].value === "/"`
  - New hotness:
    - `root.nodes[0].nodes[1].type === "combinator"`
    - `root.nodes[0].nodes[1].value === "/for/"`
* `.a /F\6fR/ .b` escapes are handled and uppercase is normalized.
  - Old & Busted:
    - `root.nodes[0].nodes[2].type === "tag"`
    - `root.nodes[0].nodes[2].value === "F\\6fR"`
  - New hotness:
    - `root.nodes[0].nodes[1].type === "combinator"`
    - `root.nodes[0].nodes[1].value === "/for/"`
    - `root.nodes[0].nodes[1].raws.value === "/F\\6fR/"`

### Source position checks and lookups

A new API was added to look up a node based on the source location.

```js
const selectorParser = require("postcss-selector-parser");
// You can find the most specific node for any given character
let combinator = selectorParser.astSync(".a > .b").atPosition(1,4);
combinator.toString() === " > ";
// You can check if a node includes a specific character
// Whitespace surrounding the node that is owned by that node
// is included in the check.
[2,3,4,5,6].map(column => combinator.isAtPosition(1, column));
// => [false, true, true, true, false]
```

# 4.0.0

This release has **BREAKING CHANGES** that were required to fix bugs regarding values with escape sequences. Please read carefully.

* **Identifiers with escapes** - CSS escape sequences are now hidden from the public API by default.
  The normal value of a node like a class name or ID, or an aspect of a node such as attribute
  selector's value, is unescaped. Escapes representing Non-ascii characters are unescaped into
  unicode characters. For example: `bu\tton, .\31 00, #i\2764\FE0Fu, [attr="value is \"quoted\""]`
  will parse respectively to the values `button`, `100`, `i❤️u`, `value is "quoted"`.
  The original escape sequences for these values can be found in the corresponding property name
  in `node.raws`. Where possible, deprecation warnings were added, but the nature
  of escape handling makes it impossible to detect what is escaped or not. Our expectation is
  that most users are neither expecting nor handling escape sequences in their use of this library,
  and so for them, this is a bug fix. Users who are taking care to handle escapes correctly can
  now update their code to remove the escape handling and let us do it for them.

* **Mutating values with escapes** - When you make an update to a node property that has escape handling
  The value is assumed to be unescaped, and any special characters are escaped automatically and
  the corresponding `raws` value is immediately updated. This can result in changes to the original
  escape format. Where the exact value of the escape sequence is important there are methods that
  allow both values to be set in conjunction. There are a number of new convenience methods for
  manipulating values that involve escapes, especially for attributes values where the quote mark
  is involved. See https://github.com/postcss/postcss-selector-parser/pull/133 for an extensive
  write-up on these changes.


**Upgrade/API Example**

In `3.x` there was no unescape handling and internal consistency of several properties was the caller's job to maintain. It was very easy for the developer
to create a CSS file that did not parse correctly when some types of values
were in use.

```js
const selectorParser = require("postcss-selector-parser");
let attr = selectorParser.attribute({attribute: "id", operator: "=", value: "a-value"});
attr.value; // => "a-value"
attr.toString(); // => [id=a-value]
// Add quotes to an attribute's value.
// All these values have to be set by the caller to be consistent:
// no internal consistency is maintained.
attr.raws.unquoted = attr.value
attr.value = "'" + attr.value + "'";
attr.value; // => "'a-value'"
attr.quoted = true;
attr.toString();  // => "[id='a-value']"
```

In `4.0` there is a convenient API for setting and mutating values
that may need escaping. Especially for attributes.

```js
const selectorParser = require("postcss-selector-parser");

// The constructor requires you specify the exact escape sequence
let className = selectorParser.className({value: "illegal class name", raws: {value: "illegal\\ class\\ name"}});
className.toString(); // => '.illegal\\ class\\ name'

// So it's better to set the value as a property
className = selectorParser.className();
// Most properties that deal with identifiers work like this
className.value = "escape for me";
className.value; // => 'escape for me'
className.toString(); // => '.escape\\ for\\ me'

// emoji and all non-ascii are escaped to ensure it works in every css file.
className.value = "😱🦄😍";
className.value; // => '😱🦄😍'
className.toString(); // => '.\\1F631\\1F984\\1F60D'

// you can control the escape sequence if you want, or do bad bad things
className.setPropertyAndEscape('value', 'xxxx', 'yyyy');
className.value; // => "xxxx"
className.toString(); // => ".yyyy"

// Pass a value directly through to the css output without escaping it. 
className.setPropertyWithoutEscape('value', '$REPLACE_ME$');
className.value; // => "$REPLACE_ME$"
className.toString(); // => ".$REPLACE_ME$"

// The biggest changes are to the Attribute class
// passing quoteMark explicitly is required to avoid a deprecation warning.
let attr = selectorParser.attribute({attribute: "id", operator: "=", value: "a-value", quoteMark: null});
attr.toString(); // => "[id=a-value]"
// Get the value with quotes on it and any necessary escapes.
// This is the same as reading attr.value in 3.x.
attr.getQuotedValue(); // => "a-value";
attr.quoteMark; // => null

// Add quotes to an attribute's value.
attr.quoteMark = "'"; // This is all that's required.
attr.toString(); // => "[id='a-value']"
attr.quoted; // => true
// The value is still the same, only the quotes have changed.
attr.value; // => a-value
attr.getQuotedValue(); // => "'a-value'";

// deprecated assignment, no warning because there's no escapes
attr.value = "new-value";
// no quote mark is needed so it is removed
attr.getQuotedValue(); // => "new-value";

// deprecated assignment, 
attr.value = "\"a 'single quoted' value\"";
// > (node:27859) DeprecationWarning: Assigning an attribute a value containing characters that might need to be escaped is deprecated. Call attribute.setValue() instead.
attr.getQuotedValue(); // => '"a \'single quoted\' value"';
// quote mark inferred from first and last characters.
attr.quoteMark; // => '"'

// setValue takes options to make manipulating the value simple.
attr.setValue('foo', {smart: true});
// foo doesn't require any escapes or quotes.
attr.toString(); // => '[id=foo]'
attr.quoteMark; // => null 

// An explicit quote mark can be specified
attr.setValue('foo', {quoteMark: '"'});
attr.toString(); // => '[id="foo"]'

// preserves quote mark by default
attr.setValue('bar');
attr.toString(); // => '[id="bar"]'
attr.quoteMark = null;
attr.toString(); // => '[id=bar]'

// with no arguments, it preserves quote mark even when it's not a great idea
attr.setValue('a value \n that should be quoted');
attr.toString(); // => '[id=a\\ value\\ \\A\\ that\\ should\\ be\\ quoted]'

// smart preservation with a specified default
attr.setValue('a value \n that should be quoted', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => "[id='a value \\A  that should be quoted']"
attr.quoteMark = '"';
// => '[id="a value \\A  that should be quoted"]'

// this keeps double quotes because it wants to quote the value and the existing value has double quotes.
attr.setValue('this should be quoted', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => '[id="this should be quoted"]'

// picks single quotes because the value has double quotes
attr.setValue('a "double quoted" value', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => "[id='a "double quoted" value']"

// setPropertyAndEscape lets you do anything you want. Even things that are a bad idea and illegal.
attr.setPropertyAndEscape('value', 'xxxx', 'the password is 42');
attr.value; // => "xxxx"
attr.toString(); // => "[id=the password is 42]"

// Pass a value directly through to the css output without escaping it. 
attr.setPropertyWithoutEscape('value', '$REPLACEMENT$');
attr.value; // => "$REPLACEMENT$"
attr.toString(); // => "[id=$REPLACEMENT$]"
```

# 3.1.2

* Fix: Removed dot-prop dependency since it's no longer written in es5.

# 3.1.1

* Fix: typescript definitions weren't in the published package.

# 3.1.0

* Fixed numerous bugs in attribute nodes relating to the handling of comments
  and whitespace. There's significant changes to `attrNode.spaces` and `attrNode.raws` since the `3.0.0` release.
* Added `Attribute#offsetOf(part)` to get the offset location of
  attribute parts like `"operator"` and `"value"`. This is most
  often added to `Attribute#sourceIndex` for error reporting.

# 3.0.0

## Breaking changes

* Some tweaks to the tokenizer/attribute selector parsing mean that whitespace
  locations might be slightly different to the 2.x code.
* Better attribute selector parsing with more validation; postcss-selector-parser
  no longer uses regular expressions to parse attribute selectors.
* Added an async API (thanks to @jacobp100); the default `process` API is now
  async, and the sync API is now accessed through `processSync` instead.
* `process()` and `processSync()` now return a string instead of the Processor
  instance.
* Tweaks handling of Less interpolation (thanks to @jwilsson).
* Removes support for Node 0.12.

## Other changes

* `ast()` and `astSync()` methods have been added to the `Processor`. These
  return the `Root` node of the selectors after processing them.
* `transform()` and `transformSync()` methods have been added to the
  `Processor`. These return the value returned by the processor callback
  after processing the selectors.
* Set the parent when inserting a node (thanks to @chriseppstein).
* Correctly adjust indices when using insertBefore/insertAfter (thanks to @tivac).
* Fixes handling of namespaces with qualified tag selectors.
* `process`, `ast` and `transform` (and their sync variants) now accept a
  `postcss` rule node. When provided, better errors are generated and selector
  processing is automatically set back to the rule selector (unless the `updateSelector` option is set to `false`.)
* Now more memory efficient when tokenizing selectors.

### Upgrade hints

The pattern of:

`rule.selector = processor.process(rule.selector).result.toString();`

is now:

`processor.processSync(rule)`

# 2.2.3

* Resolves an issue where the parser would not reduce multiple spaces between an
  ampersand and another simple selector in lossy mode (thanks to @adam-26).

# 2.2.2

* No longer hangs on an unescaped semicolon; instead the parser will throw
  an exception for these cases.

# 2.2.1

* Allows a consumer to specify whitespace tokens when creating a new Node
  (thanks to @Semigradsky).

# 2.2.0

* Added a new option to normalize whitespace when parsing the selector string
  (thanks to @adam-26).

# 2.1.1

* Better unquoted value handling within attribute selectors
  (thanks to @evilebottnawi).

# 2.1.0

* Added: Use string constants for all node types & expose them on the main
  parser instance (thanks to @Aweary).

# 2.0.0

This release contains the following breaking changes:

* Renamed all `eachInside` iterators to `walk`. For example, `eachTag` is now
  `walkTags`, and `eachInside` is now `walk`.
* Renamed `Node#removeSelf()` to `Node#remove()`.
* Renamed `Container#remove()` to `Container#removeChild()`.
* Renamed `Node#raw` to `Node#raws` (thanks to @davidtheclark).
* Now parses `&` as the *nesting* selector, rather than a *tag* selector.
* Fixes misinterpretation of Sass interpolation (e.g. `#{foo}`) as an
  id selector (thanks to @davidtheclark).

and;

* Fixes parsing of attribute selectors with equals signs in them
  (e.g. `[data-attr="foo=bar"]`) (thanks to @montmanu).
* Adds `quoted` and `raw.unquoted` properties to attribute nodes
  (thanks to @davidtheclark).

# 1.3.3

* Fixes an infinite loop on `)` and `]` tokens when they had no opening pairs.
  Now postcss-selector-parser will throw when it encounters these lone tokens.

# 1.3.2

* Now uses plain integers rather than `str.charCodeAt(0)` for compiled builds.

# 1.3.1

* Update flatten to v1.x (thanks to @shinnn).

# 1.3.0

* Adds a new node type, `String`, to fix a crash on selectors such as
  `foo:bar("test")`.

# 1.2.1

* Fixes a crash when the parser encountered a trailing combinator.

# 1.2.0

* A more descriptive error is thrown when the parser expects to find a
  pseudo-class/pseudo-element (thanks to @ashelley).
* Adds support for line/column locations for selector nodes, as well as a
  `Node#sourceIndex` method (thanks to @davidtheclark).

# 1.1.4

* Fixes a crash when a selector started with a `>` combinator. The module will
  now no longer throw if a selector has a leading/trailing combinator node.

# 1.1.3

* Fixes a crash on `@` tokens.

# 1.1.2

* Fixes an infinite loop caused by using parentheses in a non-pseudo element
  context.

# 1.1.1

* Fixes a crash when a backslash ended a selector string.

# 1.1.0

* Adds support for replacing multiple nodes at once with `replaceWith`
  (thanks to @jonathantneal).
* Parser no longer throws on sequential IDs and trailing commas, to support
  parsing of selector hacks.

# 1.0.1

* Fixes using `insertAfter` and `insertBefore` during iteration.

# 1.0.0

* Adds `clone` and `replaceWith` methods to nodes.
* Adds `insertBefore` and `insertAfter` to containers.
* Stabilises API.

# 0.0.5

* Fixes crash on extra whitespace inside a pseudo selector's parentheses.
* Adds sort function to the container class.
* Enables the parser to pass its input through without transforming.
* Iteration-safe `each` and `eachInside`.

# 0.0.4

* Tidy up redundant duplication.
* Fixes a bug where the parser would loop infinitely on universal selectors
  inside pseudo selectors.
* Adds `length` getter and `eachInside`, `map`, `reduce` to the container class.
* When a selector has been removed from the tree, the root node will no longer
  cast it to a string.
* Adds node type iterators to the container class (e.g. `eachComment`).
* Adds filter function to the container class.
* Adds split function to the container class.
* Create new node types by doing `parser.id(opts)` etc.
* Adds support for pseudo classes anywhere in the selector.

# 0.0.3

* Adds `next` and `prev` to the node class.
* Adds `first` and `last` getters to the container class.
* Adds `every` and `some` iterators to the container class.
* Add `empty` alias for `removeAll`.
* Combinators are now types of node.
* Fixes the at method so that it is not an alias for `index`.
* Tidy up creation of new nodes in the parser.
* Refactors how namespaces are handled for consistency & less redundant code.
* Refactors AST to use `nodes` exclusively, and eliminates excessive nesting.
* Fixes nested pseudo parsing.
* Fixes whitespace parsing.

# 0.0.2

* Adds support for namespace selectors.
* Adds support for selectors joined by escaped spaces - such as `.\31\ 0`.

# 0.0.1

* Initial release.


---

# postcss-selector-parser [![test](https://github.com/postcss/postcss-selector-parser/actions/workflows/test.yml/badge.svg)](https://github.com/postcss/postcss-selector-parser/actions/workflows/test.yml)

> Selector parser with built in methods for working with selector strings.

## Install

With [npm](https://npmjs.com/package/postcss-selector-parser) do:

```
npm install postcss-selector-parser
```

## Quick Start

```js
const parser = require('postcss-selector-parser');
const transform = selectors => {
    selectors.walk(selector => {
        // do something with the selector
        console.log(String(selector))
    });
};

const transformed = parser(transform).processSync('h1, h2, h3');
```

To normalize selector whitespace:

```js
const parser = require('postcss-selector-parser');
const normalized = parser().processSync('h1, h2, h3', {lossless: false});
// -> h1,h2,h3
```

Async support is provided through `parser.process` and will resolve a Promise
with the resulting selector string.

## API

Please see [API.md](API.md).

## Credits

* Huge thanks to Andrey Sitnik (@ai) for work on PostCSS which helped
  accelerate this module's development.

## License

MIT


---

# [postcss][postcss]-discard-comments

> Discard comments in your CSS files with PostCSS.


## Install

With [npm](https://npmjs.org/package/postcss-discard-comments) do:

```
npm install postcss-discard-comments --save
```


## Example

### Input

```css
h1/* heading */{
    margin: 0 auto
}
```

### Output

```css
h1 {
    margin: 0 auto
}
```

This module discards comments from your CSS files; by default, it will remove
all regular comments (`/* comment */`) and preserve comments marked as important
(`/*! important */`).

Note that this module does not handle source map comments because they are not
available to it; PostCSS handles this internally, so if they are removed then
you will have to [configure source maps in PostCSS][maps].

[maps]: https://github.com/postcss/postcss/blob/master/docs/source-maps.md


## API

### comments([options])

#### options

##### remove(function)

Type: `function`
Return: `boolean`
Variable: `comment` contains a comment without `/**/`

For each comment, return true to remove, or false to keep the comment.

```js
function(comment) {}
```

```js
var css = '/* headings *//*@ h1 */h1{margin:0 auto}/*@ h2 */h2{color:red}';
console.log(postcss(comments({
    remove: function(comment) { return comment[0] == "@"; }
})).process(css).css);
//=> /* headings */h1{margin:0 auto}h2{color:red}
```
**NOTE:** If you use the `remove` function other options will not be available.

##### removeAll

Type: `boolean`
Default: `false`

Remove all comments marked as important.

```js
var css = '/*! heading */h1{margin:0 auto}/*! heading 2 */h2{color:red}';
console.log(postcss(comments({removeAll: true})).process(css).css);
//=> h1{margin:0 auto}h2{color:red}
```

##### removeAllButFirst

Type: `boolean`
Default: `false`

Remove all comments marked as important, but the first one.

```js
var css = '/*! heading */h1{margin:0 auto}/*! heading 2 */h2{color:red}';
console.log(postcss(comments({removeAllButFirst: true})).process(css).css);
//=> /*! heading */h1{margin:0 auto}h2{color:red}
```


## Usage

See the [PostCSS documentation](https://github.com/postcss/postcss#usage) for
examples for your environment.


## Contributors

See [CONTRIBUTORS.md](https://github.com/cssnano/cssnano/blob/master/CONTRIBUTORS.md).


## License

MIT © [Ben Briggs](http://beneb.info)


[postcss]: https://github.com/postcss/postcss


---

# [postcss][postcss]-discard-duplicates

> Discard duplicate rules in your CSS files with PostCSS.

## Install

With [npm](https://npmjs.org/package/postcss-discard-duplicates) do:

```
npm install postcss-discard-duplicates --save
```

## Example

This module will remove all duplicate rules from your stylesheets. It works on
at rules, normal rules and declarations. Note that this module does not have any
responsibility for normalising declarations, selectors or whitespace, so that it
considers these two rules to be different:

```css
h1, h2 {
    color: blue;
}

h2, h1 {
    color: blue;
}
```

It has to assume that your rules have already been transformed by another
processor, otherwise it would be responsible for too many things.

### Input

```css
h1 {
    margin: 0 auto;
    margin: 0 auto
}

h1 {
    margin: 0 auto
}
```

### Output

```css
h1 {
    margin: 0 auto
}
```

## Usage

See the [PostCSS documentation](https://github.com/postcss/postcss#usage) for
examples for your environment.


## Contributors

See [CONTRIBUTORS.md](https://github.com/cssnano/cssnano/blob/master/CONTRIBUTORS.md).


## License

MIT © [Ben Briggs](http://beneb.info)


[postcss]: https://github.com/postcss/postcss


---

# [postcss][postcss]-discard-empty

> Discard empty rules and values with PostCSS.

## Install

With [npm](https://npmjs.org/package/postcss-discard-empty) do:

```
npm install postcss-discard-empty --save
```

## Example

For more examples see the [tests](src/__tests__/index.js).

### Input

```css
@font-face;
h1 {}
{color:blue}
h2 {color:}
h3 {color:red}
```

### Output

```css
h3 {color:red}
```

## Usage

See the [PostCSS documentation](https://github.com/postcss/postcss#usage) for
examples for your environment.


## Contributors

See [CONTRIBUTORS.md](https://github.com/cssnano/cssnano/blob/master/CONTRIBUTORS.md).


## License

MIT © [Ben Briggs](http://beneb.info)


[postcss]: https://github.com/postcss/postcss


---

# PostCSS Discard Overridden

[PostCSS] plugin to discard overridden `@keyframes` or `@counter-style`.

`@keyframes` or `@counter-style` will be overridden by those who share the same identifiers and appear later in stylesheets. So we can discard all of them except the last one. When defined inside a `@media` or `@supports` rule, `@keyframes` and `@counter-style` rules only override global rules in some of the client browsers so they need handled separately. This plugin has taken care of this and transforms the PostCss AST **safely**.

[PostCSS]: https://github.com/postcss/postcss

```css
@-webkit-keyframes fade-in {
  0% {
    opacity: 0;
  }
  100% {
    opacity: 0.8;
  }
}
@keyframes fade-in {
  0% {
    opacity: 0;
  }
  100% {
    opacity: 0.8;
  }
}
@media (max-width: 500px) {
  @-webkit-keyframes fade-in {
    0% {
      opacity: 0;
    }
    100% {
      opacity: 1;
    }
  }
  @keyframes fade-in {
    0% {
      opacity: 0;
    }
    100% {
      opacity: 1;
    }
  }
  @-webkit-keyframes fade-in {
    0% {
      opacity: 0;
    }
    100% {
      opacity: 0.8;
    }
  }
  @keyframes fade-in {
    0% {
      opacity: 0;
    }
    100% {
      opacity: 0.8;
    }
  }
  @supports (display: flex) {
    @-webkit-keyframes fade-in {
      0% {
        opacity: 0;
      }
      100% {
        opacity: 1;
      }
    }
    @keyframes fade-in {
      0% {
        opacity: 0;
      }
      100% {
        opacity: 1;
      }
    }
  }
}
@-webkit-keyframes fade-in {
  0% {
    opacity: 0;
  }
  100% {
    opacity: 1;
  }
}
@keyframes fade-in {
  0% {
    opacity: 0;
  }
  100% {
    opacity: 1;
  }
}
```

```css
@media (max-width: 500px) {
  @-webkit-keyframes fade-in {
    0% {
      opacity: 0;
    }
    100% {
      opacity: 0.8;
    }
  }
  @keyframes fade-in {
    0% {
      opacity: 0;
    }
    100% {
      opacity: 0.8;
    }
  }
  @supports (display: flex) {
    @-webkit-keyframes fade-in {
      0% {
        opacity: 0;
      }
      100% {
        opacity: 1;
      }
    }
    @keyframes fade-in {
      0% {
        opacity: 0;
      }
      100% {
        opacity: 1;
      }
    }
  }
}
@-webkit-keyframes fade-in {
  0% {
    opacity: 0;
  }
  100% {
    opacity: 1;
  }
}
@keyframes fade-in {
  0% {
    opacity: 0;
  }
  100% {
    opacity: 1;
  }
}
```

## Usage

See the [PostCSS documentation](https://github.com/postcss/postcss#usage) for
examples for your environment.

## Contributors

See [CONTRIBUTORS.md](https://github.com/cssnano/cssnano/blob/master/CONTRIBUTORS.md).


---

# [postcss][postcss]-discard-unused

> Discard unused counter styles, keyframes and fonts.


## Install

With [npm](https://npmjs.org/package/postcss-discard-unused) do:

```
npm install postcss-discard-unused --save
```


## Example

This module will discard unused at rules in your CSS file, if it cannot find
any selectors that make use of them. It works on `@counter-style`, `@keyframes`
and `@font-face`.

### Input

```css
@counter-style custom {
    system: extends decimal;
    suffix: "> "
}

@counter-style custom2 {
    system: extends decimal;
    suffix: "| "
}

a {
    list-style: custom
}
```

### Output

```css
@counter-style custom {
    system: extends decimal;
    suffix: "> "
}

a {
    list-style: custom
}
```

Note that this plugin is not responsible for normalising font families, as it
makes the assumption that you will write your font names consistently, such that
it considers these two declarations differently:

```css
h1 {
    font-family: "Helvetica Neue"
}

h2 {
    font-family: Helvetica Neue
}
```

However, you can mitigate this by including [postcss-minify-font-values][mfv]
*before* this plugin, which will take care of normalising quotes, and
deduplicating. For more examples, see the [tests](src/__tests__/index.js).


## Usage

See the [PostCSS documentation](https://github.com/postcss/postcss#usage) for
examples for your environment.


## API

### discardUnused([options])

#### options

##### fontFace

Type: `boolean`  
Default: `true`

Pass `false` to disable discarding unused font face rules.

##### counterStyle

Type: `boolean`  
Default: `true`

Pass `false` to disable discarding unused counter style rules.

##### keyframes

Type: `boolean`  
Default: `true`

Pass `false` to disable discarding unused keyframe rules.

##### namespace

Type: `boolean`  
Default: `true`

Pass `false` to disable discarding unused namespace rules.


## Usage

See the [PostCSS documentation](https://github.com/postcss/postcss#usage) for
examples for your environment.

## Contributors

See [CONTRIBUTORS.md](https://github.com/cssnano/cssnano/blob/master/CONTRIBUTORS.md).

## License

MIT © [Ben Briggs](http://beneb.info)


[postcss]: https://github.com/postcss/postcss
[mfv]:     https://github.com/trysound/postcss-minify-font-values


---

# Changes to PostCSS Double Position Gradients

### 6.0.0

_August 3, 2024_

- Updated: Support for Node v18+ (major).
- Updated [`@csstools/utilities`](https://github.com/csstools/postcss-plugins/tree/main/packages/utilities) to [`2.0.0`](https://github.com/csstools/postcss-plugins/tree/main/packages/utilities/CHANGELOG.md#200) (major)
- Updated [`@csstools/postcss-progressive-custom-properties`](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-progressive-custom-properties) to [`4.0.0`](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-progressive-custom-properties/CHANGELOG.md#400) (major)

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-double-position-gradients/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Double Position Gradients [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS" width="90" height="90" align="right">][postcss]

[<img alt="NPM Version" src="https://img.shields.io/npm/v/postcss-double-position-gradients.svg" height="20">][npm-url]
[<img alt="Discord" src="https://shields.io/badge/Discord-5865F2?logo=discord&logoColor=white">][discord]
<br><br>
[<img alt="Baseline Status" src="https://cssdb.org/images/badges-baseline/double-position-gradients.svg" height="20">][css-url]
[<img alt="CSS Standard Status" src="https://cssdb.org/images/badges/double-position-gradients.svg" height="20">][css-url]

[PostCSS Double Position Gradients] lets you use double-position gradients in
CSS, following the [CSS Image Values and Replaced Content] specification.

```pcss
.linear-gradient {
  background-image: linear-gradient(90deg, black 25% 50%, blue 50% 75%);
}

.conic-gradient {
  background-image: conic-gradient(yellowgreen 40%, gold 0deg 75%, #f06 0deg);
}

/* becomes */

.linear-gradient {
  background-image: linear-gradient(90deg, black 25%, black 50%, blue 50%, blue 75%);
  background-image: linear-gradient(90deg, black 25% 50%, blue 50% 75%);
}

.conic-gradient {
  background-image: conic-gradient(yellowgreen 40%, gold 0deg, gold 75%, #f06 0deg);
  background-image: conic-gradient(yellowgreen 40%, gold 0deg 75%, #f06 0deg);
}
```

## Usage

Add [PostCSS Double Position Gradients] to your project:

```bash
npm install postcss-double-position-gradients --save-dev
```

Use [PostCSS Double Position Gradients] to process your CSS:

```js
const postcssDoublePositionGradients = require('postcss-double-position-gradients');

postcssDoublePositionGradients.process(YOUR_CSS /*, processOptions, pluginOptions */);
```

Or use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssDoublePositionGradients = require('postcss-double-position-gradients');

postcss([
  postcssDoublePositionGradients(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```

[PostCSS Double Position Gradients] runs in all Node environments, with special instructions for:

| [Node](INSTALL.md#node) | [PostCSS CLI](INSTALL.md#postcss-cli) | [Webpack](INSTALL.md#webpack) | [Gulp](INSTALL.md#gulp) | [Grunt](INSTALL.md#grunt) |
| --- | --- | --- | --- | --- |

## Options

### preserve

The `preserve` option determines whether the original double-position gradients
should be preserved. By default, double-position gradients are preserved.

```js
postcssDoublePositionGradients({ preserve: false })
```

```css
.linear-gradient {
  background-image: linear-gradient(90deg, black 25% 50%, blue 50% 75%);
}

.conic-gradient {
  background-image: conic-gradient(yellowgreen 40%, gold 0deg 75%, #f06 0deg);
}

/* becomes */

.linear-gradient {
  background-image: linear-gradient(90deg, black 25%, black 50%, blue 50%, blue 75%);
}

.conic-gradient {
  background-image: conic-gradient(yellowgreen 40%, gold 0deg, gold 75%, #f06 0deg);
}
```

### enableProgressiveCustomProperties

The `enableProgressiveCustomProperties` option determines whether the original notation
is wrapped with `@supports` when used in Custom Properties. By default, it is enabled.

> [!NOTE]
> We only recommend disabling this when you set `preserve` to `false` or if you bring your own fix for Custom Properties.  
> See what the plugin does in its [README](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-progressive-custom-properties#readme).

```js
postcssDoublePositionGradients({ enableProgressiveCustomProperties: false })
```

```pcss
:root {
	--a-gradient: linear-gradient(90deg, black 25% 50%, blue 50% 75%);
}

/* becomes */

:root {
	--a-gradient: linear-gradient(90deg, black 25%, black 50%, blue 50%, blue 75%); /* will never be used, not even in older browser */
	--a-gradient: linear-gradient(90deg, black 25% 50%, blue 50% 75%);
}
```

[css-url]: https://cssdb.org/#double-position-gradients
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/postcss-double-position-gradients

[CSS Image Values and Replaced Content]: https://www.w3.org/TR/css-images-4/#color-stop-syntax
[PostCSS]: https://github.com/postcss/postcss
[PostCSS Double Position Gradients]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-double-position-gradients


---

# Changes to PostCSS Focus Visible

### 10.0.1

_October 23, 2024_

- Updated: `postcss-selector-parser`

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-focus-visible/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Focus Visible [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install postcss-focus-visible --save-dev`

[PostCSS Focus Visible] lets you use the `:focus-visible` pseudo-class in CSS, 
following the [Selectors Level 4 specification].

To use this feature you need to do two things :
- add the [PostCSS plugin](#usage) that transforms the selector into a class or attribute
- add the [focus-visible polyfill] that sets the attribute or class on elements in a browser

[!['Can I use' table](https://caniuse.bitsofco.de/image/css-focus-visible.png)](https://caniuse.com/#feat=css-focus-visible)

```css

```pcss
:focus:not(:focus-visible) {
	outline: none;
}

/* becomes */

:focus:not(.focus-visible).js-focus-visible, .js-focus-visible :focus:not(.focus-visible) {
	outline: none;
}
:focus:not(:focus-visible) {
	outline: none;
}
```

[PostCSS Focus Visible] duplicates rules using the `:focus-visible` pseudo-class
with a `.focus-visible` class selector, the same selector used by the
[focus-visible polyfill].

## Usage

Add [PostCSS Focus Visible] to your project:

```bash
npm install postcss postcss-focus-visible --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssFocusVisible = require('postcss-focus-visible');

postcss([
	postcssFocusVisible(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## Options

### preserve

The `preserve` option determines whether the original notation
is preserved. By default, it is preserved.

```js
postcssFocusVisible({ preserve: false })
```

```pcss
:focus:not(:focus-visible) {
	outline: none;
}

/* becomes */

:focus:not(.focus-visible).js-focus-visible, .js-focus-visible :focus:not(.focus-visible) {
	outline: none;
}
```

### replaceWith

The `replaceWith` option defines the selector to replace `:focus-visible`. By
default, the replacement selector is `.focus-visible`.

```js
postcssFocusVisible({ replaceWith: '[data-focus-visible-added]' })
```

```pcss
:focus:not(:focus-visible) {
	outline: none;
}

/* becomes */

<example.preserve-true.expect.css>
```

Note that if you want to keep using [focus-visible polyfill], the only 
acceptable value would be `[data-focus-visible-added]`,
given that the polyfill does not support arbitrary values.

### disablePolyfillReadyClass

The `disablePolyfillReadyClass` option determines if selectors are prefixed with an indicator class.
This class is only set on your document if the polyfill loads and is needed.

By default this option is `false`.
Set this to `true` to prevent the class from being added.

```js
postcssFocusVisible({ disablePolyfillReadyClass: true })
```

```pcss
:focus:not(:focus-visible) {
	outline: none;
}

/* becomes */

:focus:not(.focus-visible) {
	outline: none;
}
:focus:not(:focus-visible) {
	outline: none;
}
```

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#focus-visible-pseudo-class
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/postcss-focus-visible

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Focus Visible]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-focus-visible
[Selectors Level 4 specification]: https://www.w3.org/TR/selectors-4/#the-focus-visible-pseudo
[focus-visible polyfill]: https://github.com/WICG/focus-visible


---

# API Documentation

*Please use only this documented API when working with the parser. Methods
not documented here are subject to change at any point.*

## `parser` function

This is the module's main entry point.

```js
const parser = require('postcss-selector-parser');
```

### `parser([transform], [options])`

Creates a new `processor` instance

```js
const processor = parser();
```

Or, with optional transform function

```js
const transform = selectors => {
    selectors.walkUniversals(selector => {
        selector.remove();
    });
};

const processor = parser(transform)

// Example
const result = processor.processSync('*.class');
// => .class
```

[See processor documentation](#processor)

Arguments:

* `transform (function)`: Provide a function to work with the parsed AST.
* `options (object)`: Provide default options for all calls on the returned `Processor`.

### `parser.attribute([props])`

Creates a new attribute selector.

```js
parser.attribute({attribute: 'href'});
// => [href]
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.className([props])`

Creates a new class selector.

```js
parser.className({value: 'button'});
// => .button
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.combinator([props])`

Creates a new selector combinator.

```js
parser.combinator({value: '+'});
// => +
```

Arguments:

* `props (object)`: The new node's properties.

Notes:
* **Descendant Combinators** The value of descendant combinators created by the
  parser always just a single space (`" "`). For descendant selectors with no
  comments, additional space is now stored in `node.spaces.before`. Depending
  on the location of comments, additional spaces may be stored in
  `node.raws.spaces.before`, `node.raws.spaces.after`, or `node.raws.value`.
* **Named Combinators** Although, nonstandard and unlikely to ever become a standard,
  named combinators like `/deep/` and `/for/` are parsed as combinators. The
  `node.value` is name after being unescaped and normalized as lowercase. The
  original value for the combinator name is stored in `node.raws.value`.


### `parser.comment([props])`

Creates a new comment.

```js
parser.comment({value: '/* Affirmative, Dave. I read you. */'});
// => /* Affirmative, Dave. I read you. */
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.id([props])`

Creates a new id selector.

```js
parser.id({value: 'search'});
// => #search
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.nesting([props])`

Creates a new nesting selector.

```js
parser.nesting();
// => &
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.pseudo([props])`

Creates a new pseudo selector.

```js
parser.pseudo({value: '::before'});
// => ::before
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.root([props])`

Creates a new root node.

```js
parser.root();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.selector([props])`

Creates a new selector node.

```js
parser.selector();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.string([props])`

Creates a new string node.

```js
parser.string();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.tag([props])`

Creates a new tag selector.

```js
parser.tag({value: 'button'});
// => button
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.universal([props])`

Creates a new universal selector.

```js
parser.universal();
// => *
```

Arguments:

* `props (object)`: The new node's properties.

## Node types

### `node.type`

A string representation of the selector type. It can be one of the following;
`attribute`, `class`, `combinator`, `comment`, `id`, `nesting`, `pseudo`,
`root`, `selector`, `string`, `tag`, or `universal`. Note that for convenience,
these constants are exposed on the main `parser` as uppercased keys. So for
example you can get `id` by querying `parser.ID`.

```js
parser.attribute({attribute: 'href'}).type;
// => 'attribute'
```

### `node.parent`

Returns the parent node.

```js
root.nodes[0].parent === root;
```

### `node.toString()`, `String(node)`, or `'' + node`

Returns a string representation of the node.

```js
const id = parser.id({value: 'search'});
console.log(String(id));
// => #search
```

### `node.next()` & `node.prev()`

Returns the next/previous child of the parent node.

```js
const next = id.next();
if (next && next.type !== 'combinator') {
    throw new Error('Qualified IDs are not allowed!');
}
```

### `node.replaceWith(node[,...nodeN])`

Replace a node with another.

```js
const attr = selectors.first.first;
const className = parser.className({value: 'test'});
attr.replaceWith(className);
```

Arguments:

* `node`: The node to substitute the original with.
...
* `nodeN`: The node to substitute the original with.

### `node.remove()`

Removes the node from its parent node.

```js
if (node.type === 'id') {
    node.remove();
}
```

### `node.clone([opts])`

Returns a copy of a node, detached from any parent containers that the
original might have had.

```js
const cloned = node.clone();
```

### `node.isAtPosition(line, column)`

Return a `boolean` indicating whether this node includes the character at the
position of the given line and column. Returns `undefined` if the nodes lack
sufficient source metadata to determine the position.

Arguments:

* `line`: 1-index based line number relative to the start of the selector.
* `column`: 1-index based column number relative to the start of the selector.

### `node.spaces`

Extra whitespaces around the node will be moved into `node.spaces.before` and
`node.spaces.after`. So for example, these spaces will be moved as they have
no semantic meaning:

```css
      h1     ,     h2   {}
```

For descendent selectors, the value is always a single space.

```css
h1        h2 {}
```

Additional whitespace is found in either the `node.spaces.before` and `node.spaces.after` depending on the presence of comments or other whitespace characters. If the actual whitespace does not start or end with a single space, the node's raw value is set to the actual space(s) found in the source.

### `node.source`

An object describing the node's start/end, line/column source position.

Within the following CSS, the `.bar` class node ...

```css
.foo,
  .bar {}
```

... will contain the following `source` object.

```js
source: {
    start: {
        line: 2,
        column: 3
    },
    end: {
        line: 2,
        column: 6
    }
}
```

### `node.sourceIndex`

The zero-based index of the node within the original source string.

Within the following CSS, the `.baz` class node will have a `sourceIndex` of `12`.

```css
.foo, .bar, .baz {}
```

## Container types

The `root`, `selector`, and `pseudo` nodes have some helper methods for working
with their children.

### `container.nodes`

An array of the container's children.

```js
// Input: h1 h2
selectors.at(0).nodes.length   // => 3
selectors.at(0).nodes[0].value // => 'h1'
selectors.at(0).nodes[1].value // => ' '
```

### `container.first` & `container.last`

The first/last child of the container.

```js
selector.first === selector.nodes[0];
selector.last === selector.nodes[selector.nodes.length - 1];
```

### `container.at(index)`

Returns the node at position `index`.

```js
selector.at(0) === selector.first;
selector.at(0) === selector.nodes[0];
```

Arguments:

* `index`: The index of the node to return.

### `container.atPosition(line, column)`

Returns the node at the source position `line` and `column`.

```js
// Input: :not(.foo),\n#foo > :matches(ol, ul)
selector.atPosition(1, 1); // => :not(.foo)
selector.atPosition(2, 1); // => \n#foo
```

Arguments:

* `line`: The line number of the node to return.
* `column`: The column number of the node to return.

### `container.index(node)`

Return the index of the node within its container.

```js
selector.index(selector.nodes[2]) // => 2
```

Arguments:

* `node`: A node within the current container.

### `container.length`

Proxy to the length of the container's nodes.

```js
container.length === container.nodes.length
```

### `container` Array iterators

The container class provides proxies to certain Array methods; these are:

* `container.map === container.nodes.map`
* `container.reduce === container.nodes.reduce`
* `container.every === container.nodes.every`
* `container.some === container.nodes.some`
* `container.filter === container.nodes.filter`
* `container.sort === container.nodes.sort`

Note that these methods only work on a container's immediate children; recursive
iteration is provided by `container.walk`.

### `container.each(callback)`

Iterate the container's immediate children, calling `callback` for each child.
You may return `false` within the callback to break the iteration.

```js
let className;
selectors.each((selector, index) => {
    if (selector.type === 'class') {
        className = selector.value;
        return false;
    }
});
```

Note that unlike `Array#forEach()`, this iterator is safe to use whilst adding
or removing nodes from the container.

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  and `index` arguments.

### `container.walk(callback)`

Like `container#each`, but will also iterate child nodes as long as they are
`container` types.

```js
selectors.walk((selector, index) => {
    // all nodes
});
```

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  and `index` arguments.

This iterator is safe to use whilst mutating `container.nodes`,
like `container#each`.

### `container.walk` proxies

The container class provides proxy methods for iterating over types of nodes,
so that it is easier to write modules that target specific selectors. Those
methods are:

* `container.walkAttributes`
* `container.walkClasses`
* `container.walkCombinators`
* `container.walkComments`
* `container.walkIds`
* `container.walkNesting`
* `container.walkPseudos`
* `container.walkTags`
* `container.walkUniversals`

### `container.split(callback)`

This method allows you to split a group of nodes by returning `true` from
a callback. It returns an array of arrays, where each inner array corresponds
to the groups that you created via the callback.

```js
// (input) => h1 h2>>h3
const list = selectors.first.split(selector => {
    return selector.type === 'combinator';
});

// (node values) => [['h1', ' '], ['h2', '>>'], ['h3']]
```

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  as an argument.

### `container.prepend(node)` & `container.append(node)`

Add a node to the start/end of the container. Note that doing so will set
the parent property of the node to this container.

```js
const id = parser.id({value: 'search'});
selector.append(id);
```

Arguments:

* `node`: The node to add.

### `container.insertBefore(old, new[, ...newNodes])` & `container.insertAfter(old, new[, ...newNodes])`

Add a node before or after an existing node in a container:

```js
selectors.walk(selector => {
    if (selector.type !== 'class') {
        const className = parser.className({value: 'theme-name'});
        selector.parent.insertAfter(selector, className);
    }
});
```

Arguments:

* `old`: The existing node in the container.
* `new`: The new node to add before/after the existing node.

### `container.removeChild(node)`

Remove the node from the container. Note that you can also use
`node.remove()` if you would like to remove just a single node.

```js
selector.length // => 2
selector.remove(id)
selector.length // => 1;
id.parent       // undefined
```

Arguments:

* `node`: The node to remove.

### `container.removeAll()` or `container.empty()`

Remove all children from the container.

```js
selector.removeAll();
selector.length // => 0
```

## Root nodes

A root node represents a comma separated list of selectors. Indeed, all
a root's `toString()` method does is join its selector children with a ','.
Other than this, it has no special functionality and acts like a container.

### `root.trailingComma`

This will be set to `true` if the input has a trailing comma, in order to
support parsing of legacy CSS hacks.

## Selector nodes

A selector node represents a single complex selector. For example, this
selector string `h1 h2 h3, [href] > p`, is represented as two selector nodes.
It has no special functionality of its own.

## Pseudo nodes

A pseudo selector extends a container node; if it has any parameters of its
own (such as `h1:not(h2, h3)`), they will be its children. Note that the pseudo
`value` will always contain the colons preceding the pseudo identifier. This
is so that both `:before` and `::before` are properly represented in the AST.

## Attribute nodes

### `attribute.quoted`

Returns `true` if the attribute's value is wrapped in quotation marks, false if it is not.
Remains `undefined` if there is no attribute value.

```css
[href=foo] /* false */
[href='foo'] /* true */
[href="foo"] /* true */
[href] /* undefined */
```

### `attribute.qualifiedAttribute`

Returns the attribute name qualified with the namespace if one is given.

### `attribute.offsetOf(part)`

 Returns the offset of the attribute part specified relative to the
 start of the node of the output string. This is useful in raising
 error messages about a specific part of the attribute, especially
 in combination with `attribute.sourceIndex`.

 Returns `-1` if the name is invalid or the value doesn't exist in this
 attribute.

 The legal values for `part` are:

 * `"ns"` - alias for "namespace"
 * `"namespace"` - the namespace if it exists.
 * `"attribute"` - the attribute name
 * `"attributeNS"` - the start of the attribute or its namespace
 * `"operator"` - the match operator of the attribute
 * `"value"` - The value (string or identifier)
 * `"insensitive"` - the case insensitivity flag

### `attribute.raws.unquoted`

Returns the unquoted content of the attribute's value.
Remains `undefined` if there is no attribute value.

```css
[href=foo] /* foo */
[href='foo'] /* foo */
[href="foo"] /* foo */
[href] /* undefined */
```

### `attribute.spaces`

Like `node.spaces` with the `before` and `after` values containing the spaces
around the element, the parts of the attribute can also have spaces before
and after them. The for each of `attribute`, `operator`, `value` and
`insensitive` there is corresponding property of the same nam in
`node.spaces` that has an optional `before` or `after` string containing only
whitespace.

Note that corresponding values in `attributes.raws.spaces` contain values
including any comments. If set, these values will override the
`attribute.spaces` value. Take care to remove them if changing
`attribute.spaces`.

### `attribute.raws`

The raws object stores comments and other information necessary to re-render
the node exactly as it was in the source.

If a comment is embedded within the identifiers for the `namespace`, `attribute`
or `value` then a property is placed in the raws for that value containing the full source of the propery including comments.

If a comment is embedded within the space between parts of the attribute
then the raw for that space is set accordingly.

Setting an attribute's property `raws` value to be deleted.

For now, changing the spaces required also updating or removing any of the
raws values that override them.

Example: `[ /*before*/ href /* after-attr */ = /* after-operator */ te/*inside-value*/st/* wow */ /*omg*/i/*bbq*/ /*whodoesthis*/]` would parse as:

```js
{
  attribute: "href",
  operator: "=",
  value: "test",
  spaces: {
    before: '',
    after: '',
    attribute: { before: '  ', after: '  ' },
    operator: { after: '  ' },
    value: { after: ' ' },
    insensitive: { after: ' ' }
  },
  raws: {
    spaces: {
      attribute: { before: ' /*before*/ ', after: ' /* after-attr */ ' },
      operator: { after: ' /* after-operator */ ' },
      value: { after: '/* wow */ /*omg*/' },
      insensitive: { after: '/*bbq*/ /*whodoesthis*/' }
    },
    unquoted: 'test',
    value: 'te/*inside-value*/st'
  }
}
```

## `Processor`

### `ProcessorOptions`

* `lossless` - When `true`, whitespace is preserved. Defaults to `true`.
* `updateSelector` - When `true`, if any processor methods are passed a postcss
  `Rule` node instead of a string, then that Rule's selector is updated
  with the results of the processing. Defaults to `true`.

### `process|processSync(selectors, [options])`

Processes the `selectors`, returning a string from the result of processing.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

**Example:**

```js
const parser = require("postcss-selector-parser");
const processor = parser();

let result = processor.processSync(' .class');
console.log(result);
// =>  .class

// Asynchronous operation
let promise = processor.process(' .class').then(result => {
    console.log(result)
    // => .class
});

// To have the parser normalize whitespace values, utilize the options
result = processor.processSync('  .class  ', {lossless: false});
console.log(result);
// => .class

// For better syntax errors, pass a PostCSS Rule node.
const postcss = require('postcss');
rule = postcss.rule({selector: ' #foo    > a,  .class  '});
processor.process(rule, {lossless: false, updateSelector: true}).then(result => {
    console.log(result);
    // => #foo>a,.class
    console.log("rule:", rule.selector);
    // => rule: #foo>a,.class
})
```

Arguments:

* `selectors (string|postcss.Rule)`: Either a selector string or a PostCSS Rule
  node.
* `[options] (object)`: Process options


### `ast|astSync(selectors, [options])`

Like `process()` and `processSync()` but after
processing the `selectors` these methods return the `Root` node of the result
instead of a string.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

### `transform|transformSync(selectors, [options])`

Like `process()` and `processSync()` but after
processing the `selectors` these methods return the value returned by the
processor callback.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

### Error Handling Within Selector Processors

The root node passed to the selector processor callback
has a method `error(message, options)` that returns an
error object. This method should always be used to raise
errors relating to the syntax of selectors. The options
to this method are passed to postcss's error constructor
([documentation](http://postcss.org/api/#container-error)).

#### Async Error Example

```js
let processor = (root) => {
    return new Promise((resolve, reject) => {
        root.walkClasses((classNode) => {
            if (/^(.*)[-_]/.test(classNode.value)) {
                let msg = "classes may not have underscores or dashes in them";
                reject(root.error(msg, {
                    index: classNode.sourceIndex + RegExp.$1.length + 1,
                    word: classNode.value
                }));
            }
        });
        resolve();
    });
};

const postcss = require("postcss");
const parser = require("postcss-selector-parser");
const selectorProcessor = parser(processor);
const plugin = postcss.plugin('classValidator', (options) => {
    return (root) => {
        let promises = [];
        root.walkRules(rule => {
            promises.push(selectorProcessor.process(rule));
        });
        return Promise.all(promises);
    };
});
postcss(plugin()).process(`
.foo-bar {
  color: red;
}
`.trim(), {from: 'test.css'}).catch((e) => console.error(e.toString()));

// CssSyntaxError: classValidator: ./test.css:1:5: classes may not have underscores or dashes in them
//
// > 1 | .foo-bar {
//     |     ^
//   2 |   color: red;
//   3 | }
```

#### Synchronous Error Example

```js
let processor = (root) => {
    root.walkClasses((classNode) => {
        if (/.*[-_]/.test(classNode.value)) {
            let msg = "classes may not have underscores or dashes in them";
            throw root.error(msg, {
                index: classNode.sourceIndex,
                word: classNode.value
            });
        }
    });
};

const postcss = require("postcss");
const parser = require("postcss-selector-parser");
const selectorProcessor = parser(processor);
const plugin = postcss.plugin('classValidator', (options) => {
    return (root) => {
        root.walkRules(rule => {
            selectorProcessor.processSync(rule);
        });
    };
});
postcss(plugin()).process(`
.foo-bar {
  color: red;
}
`.trim(), {from: 'test.css'}).catch((e) => console.error(e.toString()));

// CssSyntaxError: classValidator: ./test.css:1:5: classes may not have underscores or dashes in them
//
// > 1 | .foo-bar {
//     |     ^
//   2 |   color: red;
//   3 | }
```


---

# 7.1.0

- feat: insert(Before|After) support multiple new node

# 7.0.0

- Feat: make insertions during iteration safe (major)

# 6.1.2

- Fixed: erroneous trailing combinators in pseudos

# 6.1.1

- Fixed: improve typings of constructor helpers (#292)

# 6.1.0

- Feature: add `sourceIndex` to `Selector` nodes (#290)

# 6.0.16

- Fixed: add missing `index` argument to `each`/`walk` callback types (#289)

# 6.0.15

- Fixed: Node#prev and Node#next type for the first/last node

# 6.0.14

- Fixed: type definitions

# 6.0.13

- Fixed: throw on unexpected pipe symbols

# 6.0.12

- Fixed: `clone` arguments should be optional

# 6.0.11

- Fixed: parse attribute case insensitivity flag

# 6.0.10

- Fixed: `isPseudoElement()` supports `:first-letter` and `:first-line`

# 6.0.9

- Fixed: `Combinator.raws` property type

# 6.0.8

- Fixed: reduced size

# 6.0.7

- Fixed: parse animation percents

# 6.0.6

- Fixed: parse quoted attributes containing a newline correctly

# 6.0.5

- Perf: rework unesc for a 63+% performance boost

# 6.0.4

- Fixed: ts errors

# 6.0.3

- Fixed: replace node built-in "util" module with "util-deprecate"
- Fixed: handle uppercase pseudo elements
- Fixed: do not create invalid combinator before comment

# 6.0.2

- Fixed an issue with parsing and stringifying an empty attribute value

# 6.0.1

- Fixed an issue with unicode surrogate pair parsing

# 6.0.0

- Updated: `cssesc` to 3.0.0 (major)
- Fixed: Issues with escaped `id` and `class` selectors

# 5.0.0

- Allow escaped dot within class name.
- Update PostCSS to 7.0.7 (patch)

# 5.0.0-rc.4

- Fixed an issue where comments immediately after an insensitive (in attribute)
  were not parsed correctly.
- Updated `cssesc` to 2.0.0 (major).
- Removed outdated integration tests.
- Added tests for custom selectors, tags with attributes, the universal
  selector with pseudos, and tokens after combinators.

# 5.0.0-rc.1

To ease adoption of the v5.0 release, we have relaxed the node version
check performed by npm at installation time to allow for node 4, which
remains officially unsupported, but likely to continue working for the
time being.

# 5.0.0-rc.0

This release has **BREAKING CHANGES** that were required to fix regressions
in 4.0.0 and to make the Combinator Node API consistent for all combinator
types. Please read carefully.

## Summary of Changes

* The way a descendent combinator that isn't a single space character (E.g. `.a  .b`) is stored in the AST has changed.
* Named Combinators (E.g. `.a /for/ .b`) are now properly parsed as a combinator.
* It is now possible to look up a node based on the source location of a character in that node and to query nodes if they contain some character.
* Several bug fixes that caused the parser to hang and run out of memory when a `/` was encountered have been fixed.
* The minimum supported version of Node is now `v6.0.0`.

### Changes to the Descendent Combinator

In prior releases, the value of a descendant combinator with multiple spaces included all the spaces.

* `.a   .b`: Extra spaces are now stored as space before.
  - Old & Busted:
    - `combinator.value === "   "`
  - New hotness:
    - `combinator.value === " " && combinator.spaces.before === "  "`
* `.a   /*comment*/.b`: A comment at the end of the combinator causes extra space to become after space.
  - Old & Busted:
    - `combinator.value === "   "`
    - `combinator.raws.value === "   /*comment/"`
  - New hotness:
    - `combinator.value === " "`
    - `combinator.spaces.after === "  "`
    - `combinator.raws.spaces.after === "  /*comment*/"`
* `.a<newline>.b`: whitespace that doesn't start or end with a single space character is stored as a raw value.
  - Old & Busted:
    - `combinator.value === "\n"`
    - `combinator.raws.value === undefined`
  - New hotness:
    - `combinator.value === " "`
    - `combinator.raws.value === "\n"`

### Support for "Named Combinators"

Although, nonstandard and unlikely to ever become a standard, combinators like `/deep/` and `/for/` are now properly supported.

Because they've been taken off the standardization track, there is no spec-official name for combinators of the form `/<ident>/`. However, I talked to [Tab Atkins](https://twitter.com/tabatkins) and we agreed to call them "named combinators" so now they are called that.

Before this release such named combinators were parsed without intention and generated three nodes of type `"tag"` where the first and last nodes had a value of `"/"`.

* `.a /for/ .b` is parsed as a combinator.
  - Old & Busted:
    - `root.nodes[0].nodes[1].type === "tag"`
    - `root.nodes[0].nodes[1].value === "/"`
  - New hotness:
    - `root.nodes[0].nodes[1].type === "combinator"`
    - `root.nodes[0].nodes[1].value === "/for/"`
* `.a /F\6fR/ .b` escapes are handled and uppercase is normalized.
  - Old & Busted:
    - `root.nodes[0].nodes[2].type === "tag"`
    - `root.nodes[0].nodes[2].value === "F\\6fR"`
  - New hotness:
    - `root.nodes[0].nodes[1].type === "combinator"`
    - `root.nodes[0].nodes[1].value === "/for/"`
    - `root.nodes[0].nodes[1].raws.value === "/F\\6fR/"`

### Source position checks and lookups

A new API was added to look up a node based on the source location.

```js
const selectorParser = require("postcss-selector-parser");
// You can find the most specific node for any given character
let combinator = selectorParser.astSync(".a > .b").atPosition(1,4);
combinator.toString() === " > ";
// You can check if a node includes a specific character
// Whitespace surrounding the node that is owned by that node
// is included in the check.
[2,3,4,5,6].map(column => combinator.isAtPosition(1, column));
// => [false, true, true, true, false]
```

# 4.0.0

This release has **BREAKING CHANGES** that were required to fix bugs regarding values with escape sequences. Please read carefully.

* **Identifiers with escapes** - CSS escape sequences are now hidden from the public API by default.
  The normal value of a node like a class name or ID, or an aspect of a node such as attribute
  selector's value, is unescaped. Escapes representing Non-ascii characters are unescaped into
  unicode characters. For example: `bu\tton, .\31 00, #i\2764\FE0Fu, [attr="value is \"quoted\""]`
  will parse respectively to the values `button`, `100`, `i❤️u`, `value is "quoted"`.
  The original escape sequences for these values can be found in the corresponding property name
  in `node.raws`. Where possible, deprecation warnings were added, but the nature
  of escape handling makes it impossible to detect what is escaped or not. Our expectation is
  that most users are neither expecting nor handling escape sequences in their use of this library,
  and so for them, this is a bug fix. Users who are taking care to handle escapes correctly can
  now update their code to remove the escape handling and let us do it for them.

* **Mutating values with escapes** - When you make an update to a node property that has escape handling
  The value is assumed to be unescaped, and any special characters are escaped automatically and
  the corresponding `raws` value is immediately updated. This can result in changes to the original
  escape format. Where the exact value of the escape sequence is important there are methods that
  allow both values to be set in conjunction. There are a number of new convenience methods for
  manipulating values that involve escapes, especially for attributes values where the quote mark
  is involved. See https://github.com/postcss/postcss-selector-parser/pull/133 for an extensive
  write-up on these changes.


**Upgrade/API Example**

In `3.x` there was no unescape handling and internal consistency of several properties was the caller's job to maintain. It was very easy for the developer
to create a CSS file that did not parse correctly when some types of values
were in use.

```js
const selectorParser = require("postcss-selector-parser");
let attr = selectorParser.attribute({attribute: "id", operator: "=", value: "a-value"});
attr.value; // => "a-value"
attr.toString(); // => [id=a-value]
// Add quotes to an attribute's value.
// All these values have to be set by the caller to be consistent:
// no internal consistency is maintained.
attr.raws.unquoted = attr.value
attr.value = "'" + attr.value + "'";
attr.value; // => "'a-value'"
attr.quoted = true;
attr.toString();  // => "[id='a-value']"
```

In `4.0` there is a convenient API for setting and mutating values
that may need escaping. Especially for attributes.

```js
const selectorParser = require("postcss-selector-parser");

// The constructor requires you specify the exact escape sequence
let className = selectorParser.className({value: "illegal class name", raws: {value: "illegal\\ class\\ name"}});
className.toString(); // => '.illegal\\ class\\ name'

// So it's better to set the value as a property
className = selectorParser.className();
// Most properties that deal with identifiers work like this
className.value = "escape for me";
className.value; // => 'escape for me'
className.toString(); // => '.escape\\ for\\ me'

// emoji and all non-ascii are escaped to ensure it works in every css file.
className.value = "😱🦄😍";
className.value; // => '😱🦄😍'
className.toString(); // => '.\\1F631\\1F984\\1F60D'

// you can control the escape sequence if you want, or do bad bad things
className.setPropertyAndEscape('value', 'xxxx', 'yyyy');
className.value; // => "xxxx"
className.toString(); // => ".yyyy"

// Pass a value directly through to the css output without escaping it. 
className.setPropertyWithoutEscape('value', '$REPLACE_ME$');
className.value; // => "$REPLACE_ME$"
className.toString(); // => ".$REPLACE_ME$"

// The biggest changes are to the Attribute class
// passing quoteMark explicitly is required to avoid a deprecation warning.
let attr = selectorParser.attribute({attribute: "id", operator: "=", value: "a-value", quoteMark: null});
attr.toString(); // => "[id=a-value]"
// Get the value with quotes on it and any necessary escapes.
// This is the same as reading attr.value in 3.x.
attr.getQuotedValue(); // => "a-value";
attr.quoteMark; // => null

// Add quotes to an attribute's value.
attr.quoteMark = "'"; // This is all that's required.
attr.toString(); // => "[id='a-value']"
attr.quoted; // => true
// The value is still the same, only the quotes have changed.
attr.value; // => a-value
attr.getQuotedValue(); // => "'a-value'";

// deprecated assignment, no warning because there's no escapes
attr.value = "new-value";
// no quote mark is needed so it is removed
attr.getQuotedValue(); // => "new-value";

// deprecated assignment, 
attr.value = "\"a 'single quoted' value\"";
// > (node:27859) DeprecationWarning: Assigning an attribute a value containing characters that might need to be escaped is deprecated. Call attribute.setValue() instead.
attr.getQuotedValue(); // => '"a \'single quoted\' value"';
// quote mark inferred from first and last characters.
attr.quoteMark; // => '"'

// setValue takes options to make manipulating the value simple.
attr.setValue('foo', {smart: true});
// foo doesn't require any escapes or quotes.
attr.toString(); // => '[id=foo]'
attr.quoteMark; // => null 

// An explicit quote mark can be specified
attr.setValue('foo', {quoteMark: '"'});
attr.toString(); // => '[id="foo"]'

// preserves quote mark by default
attr.setValue('bar');
attr.toString(); // => '[id="bar"]'
attr.quoteMark = null;
attr.toString(); // => '[id=bar]'

// with no arguments, it preserves quote mark even when it's not a great idea
attr.setValue('a value \n that should be quoted');
attr.toString(); // => '[id=a\\ value\\ \\A\\ that\\ should\\ be\\ quoted]'

// smart preservation with a specified default
attr.setValue('a value \n that should be quoted', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => "[id='a value \\A  that should be quoted']"
attr.quoteMark = '"';
// => '[id="a value \\A  that should be quoted"]'

// this keeps double quotes because it wants to quote the value and the existing value has double quotes.
attr.setValue('this should be quoted', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => '[id="this should be quoted"]'

// picks single quotes because the value has double quotes
attr.setValue('a "double quoted" value', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => "[id='a "double quoted" value']"

// setPropertyAndEscape lets you do anything you want. Even things that are a bad idea and illegal.
attr.setPropertyAndEscape('value', 'xxxx', 'the password is 42');
attr.value; // => "xxxx"
attr.toString(); // => "[id=the password is 42]"

// Pass a value directly through to the css output without escaping it. 
attr.setPropertyWithoutEscape('value', '$REPLACEMENT$');
attr.value; // => "$REPLACEMENT$"
attr.toString(); // => "[id=$REPLACEMENT$]"
```

# 3.1.2

* Fix: Removed dot-prop dependency since it's no longer written in es5.

# 3.1.1

* Fix: typescript definitions weren't in the published package.

# 3.1.0

* Fixed numerous bugs in attribute nodes relating to the handling of comments
  and whitespace. There's significant changes to `attrNode.spaces` and `attrNode.raws` since the `3.0.0` release.
* Added `Attribute#offsetOf(part)` to get the offset location of
  attribute parts like `"operator"` and `"value"`. This is most
  often added to `Attribute#sourceIndex` for error reporting.

# 3.0.0

## Breaking changes

* Some tweaks to the tokenizer/attribute selector parsing mean that whitespace
  locations might be slightly different to the 2.x code.
* Better attribute selector parsing with more validation; postcss-selector-parser
  no longer uses regular expressions to parse attribute selectors.
* Added an async API (thanks to @jacobp100); the default `process` API is now
  async, and the sync API is now accessed through `processSync` instead.
* `process()` and `processSync()` now return a string instead of the Processor
  instance.
* Tweaks handling of Less interpolation (thanks to @jwilsson).
* Removes support for Node 0.12.

## Other changes

* `ast()` and `astSync()` methods have been added to the `Processor`. These
  return the `Root` node of the selectors after processing them.
* `transform()` and `transformSync()` methods have been added to the
  `Processor`. These return the value returned by the processor callback
  after processing the selectors.
* Set the parent when inserting a node (thanks to @chriseppstein).
* Correctly adjust indices when using insertBefore/insertAfter (thanks to @tivac).
* Fixes handling of namespaces with qualified tag selectors.
* `process`, `ast` and `transform` (and their sync variants) now accept a
  `postcss` rule node. When provided, better errors are generated and selector
  processing is automatically set back to the rule selector (unless the `updateSelector` option is set to `false`.)
* Now more memory efficient when tokenizing selectors.

### Upgrade hints

The pattern of:

`rule.selector = processor.process(rule.selector).result.toString();`

is now:

`processor.processSync(rule)`

# 2.2.3

* Resolves an issue where the parser would not reduce multiple spaces between an
  ampersand and another simple selector in lossy mode (thanks to @adam-26).

# 2.2.2

* No longer hangs on an unescaped semicolon; instead the parser will throw
  an exception for these cases.

# 2.2.1

* Allows a consumer to specify whitespace tokens when creating a new Node
  (thanks to @Semigradsky).

# 2.2.0

* Added a new option to normalize whitespace when parsing the selector string
  (thanks to @adam-26).

# 2.1.1

* Better unquoted value handling within attribute selectors
  (thanks to @evilebottnawi).

# 2.1.0

* Added: Use string constants for all node types & expose them on the main
  parser instance (thanks to @Aweary).

# 2.0.0

This release contains the following breaking changes:

* Renamed all `eachInside` iterators to `walk`. For example, `eachTag` is now
  `walkTags`, and `eachInside` is now `walk`.
* Renamed `Node#removeSelf()` to `Node#remove()`.
* Renamed `Container#remove()` to `Container#removeChild()`.
* Renamed `Node#raw` to `Node#raws` (thanks to @davidtheclark).
* Now parses `&` as the *nesting* selector, rather than a *tag* selector.
* Fixes misinterpretation of Sass interpolation (e.g. `#{foo}`) as an
  id selector (thanks to @davidtheclark).

and;

* Fixes parsing of attribute selectors with equals signs in them
  (e.g. `[data-attr="foo=bar"]`) (thanks to @montmanu).
* Adds `quoted` and `raw.unquoted` properties to attribute nodes
  (thanks to @davidtheclark).

# 1.3.3

* Fixes an infinite loop on `)` and `]` tokens when they had no opening pairs.
  Now postcss-selector-parser will throw when it encounters these lone tokens.

# 1.3.2

* Now uses plain integers rather than `str.charCodeAt(0)` for compiled builds.

# 1.3.1

* Update flatten to v1.x (thanks to @shinnn).

# 1.3.0

* Adds a new node type, `String`, to fix a crash on selectors such as
  `foo:bar("test")`.

# 1.2.1

* Fixes a crash when the parser encountered a trailing combinator.

# 1.2.0

* A more descriptive error is thrown when the parser expects to find a
  pseudo-class/pseudo-element (thanks to @ashelley).
* Adds support for line/column locations for selector nodes, as well as a
  `Node#sourceIndex` method (thanks to @davidtheclark).

# 1.1.4

* Fixes a crash when a selector started with a `>` combinator. The module will
  now no longer throw if a selector has a leading/trailing combinator node.

# 1.1.3

* Fixes a crash on `@` tokens.

# 1.1.2

* Fixes an infinite loop caused by using parentheses in a non-pseudo element
  context.

# 1.1.1

* Fixes a crash when a backslash ended a selector string.

# 1.1.0

* Adds support for replacing multiple nodes at once with `replaceWith`
  (thanks to @jonathantneal).
* Parser no longer throws on sequential IDs and trailing commas, to support
  parsing of selector hacks.

# 1.0.1

* Fixes using `insertAfter` and `insertBefore` during iteration.

# 1.0.0

* Adds `clone` and `replaceWith` methods to nodes.
* Adds `insertBefore` and `insertAfter` to containers.
* Stabilises API.

# 0.0.5

* Fixes crash on extra whitespace inside a pseudo selector's parentheses.
* Adds sort function to the container class.
* Enables the parser to pass its input through without transforming.
* Iteration-safe `each` and `eachInside`.

# 0.0.4

* Tidy up redundant duplication.
* Fixes a bug where the parser would loop infinitely on universal selectors
  inside pseudo selectors.
* Adds `length` getter and `eachInside`, `map`, `reduce` to the container class.
* When a selector has been removed from the tree, the root node will no longer
  cast it to a string.
* Adds node type iterators to the container class (e.g. `eachComment`).
* Adds filter function to the container class.
* Adds split function to the container class.
* Create new node types by doing `parser.id(opts)` etc.
* Adds support for pseudo classes anywhere in the selector.

# 0.0.3

* Adds `next` and `prev` to the node class.
* Adds `first` and `last` getters to the container class.
* Adds `every` and `some` iterators to the container class.
* Add `empty` alias for `removeAll`.
* Combinators are now types of node.
* Fixes the at method so that it is not an alias for `index`.
* Tidy up creation of new nodes in the parser.
* Refactors how namespaces are handled for consistency & less redundant code.
* Refactors AST to use `nodes` exclusively, and eliminates excessive nesting.
* Fixes nested pseudo parsing.
* Fixes whitespace parsing.

# 0.0.2

* Adds support for namespace selectors.
* Adds support for selectors joined by escaped spaces - such as `.\31\ 0`.

# 0.0.1

* Initial release.


---

# postcss-selector-parser [![test](https://github.com/postcss/postcss-selector-parser/actions/workflows/test.yml/badge.svg)](https://github.com/postcss/postcss-selector-parser/actions/workflows/test.yml)

> Selector parser with built in methods for working with selector strings.

## Install

With [npm](https://npmjs.com/package/postcss-selector-parser) do:

```
npm install postcss-selector-parser
```

## Quick Start

```js
const parser = require('postcss-selector-parser');
const transform = selectors => {
    selectors.walk(selector => {
        // do something with the selector
        console.log(String(selector))
    });
};

const transformed = parser(transform).processSync('h1, h2, h3');
```

To normalize selector whitespace:

```js
const parser = require('postcss-selector-parser');
const normalized = parser().processSync('h1, h2, h3', {lossless: false});
// -> h1,h2,h3
```

Async support is provided through `parser.process` and will resolve a Promise
with the resulting selector string.

## API

Please see [API.md](API.md).

## Credits

* Huge thanks to Andrey Sitnik (@ai) for work on PostCSS which helped
  accelerate this module's development.

## License

MIT


---

# Changes to PostCSS Focus Within

### 9.0.1

_October 23, 2024_

- Updated: `postcss-selector-parser`

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-focus-within/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Focus Within [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install postcss-focus-within --save-dev`

[PostCSS Focus Within] lets you use the `:focus-within` pseudo-class in CSS, 
following the [Selectors Level 4 specification].

To use this feature you need to do two things :
- add the [PostCSS plugin](#usage) that transforms the selector into a class or attribute
- add the [browser polyfill](#browser) that sets the attribute or class on elements in a browser

```pcss
.my-form-field:focus-within label {
	background-color: yellow;
}

/* becomes */

.my-form-field[focus-within].js-focus-within label, .js-focus-within .my-form-field[focus-within] label {
	background-color: yellow;
}
.my-form-field:focus-within label {
	background-color: yellow;
}
```

[PostCSS Focus Within] duplicates rules using the `:focus-within` pseudo-class
with a `[focus-within]` attribute selector, the same selector used by the
focus-within polyfill. This replacement selector can be changed using the
`replaceWith` option. Also, the preservation of the original `:focus-within`
rule can be disabled using the `preserve` option.

## Usage

Add [PostCSS Focus Within] to your project:

```bash
npm install postcss postcss-focus-within --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssFocusWithin = require('postcss-focus-within');

postcss([
	postcssFocusWithin(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## Options

### preserve

The `preserve` option determines whether the original notation
is preserved. By default, it is preserved.

```js
postcssFocusWithin({ preserve: false })
```

```pcss
.my-form-field:focus-within label {
	background-color: yellow;
}

/* becomes */

.my-form-field[focus-within].js-focus-within label, .js-focus-within .my-form-field[focus-within] label {
	background-color: yellow;
}
```

### replaceWith

The `replaceWith` option defines the selector to replace `:focus-within`. By
default, the replacement selector is `[focus-within]`.
Please note that using a class, leverages `classList` under the hood which
might  not be supported on some old browsers such as IE9, so you may need
to polyfill `classList` in those cases.

```js
postcssFocusWithin({ replaceWith: '.focus-within' });
```

```pcss
.my-form-field:focus-within label {
	background-color: yellow;
}

/* becomes */

.my-form-field.focus-within.js-focus-within label, .js-focus-within .my-form-field.focus-within label {
	background-color: yellow;
}
.my-form-field:focus-within label {
	background-color: yellow;
}
```

Note that changing this option implies that it needs to be passed to the
browser polyfill as well.

### disablePolyfillReadyClass

The `disablePolyfillReadyClass` option determines if selectors are prefixed with an indicator class.
This class is only set on your document if the polyfill loads and is needed.

By default this option is `false`.
Set this to `true` to prevent the class from being added.

```js
postcssFocusWithin({ disablePolyfillReadyClass: true })
```

```pcss
.my-form-field:focus-within label {
	background-color: yellow;
}

/* becomes */

.my-form-field[focus-within] label {
	background-color: yellow;
}
.my-form-field:focus-within label {
	background-color: yellow;
}
```

## Browser

```js
import focusWithinInit from 'postcss-focus-within/browser';

focusWithinInit();
```

or

```html
<!-- When using a CDN url you will have to manually update the version number -->
<script src="https://unpkg.com/postcss-focus-within@9.0.1/dist/browser-global.js"></script>
<script>focusWithinInit()</script>
```

[PostCSS Focus Within] works in all major browsers, including Safari 6+ and
Internet Explorer 9+ without any additional polyfills.

### Browser Usage

#### force

The `force` option determines whether the library runs even if the browser
supports the selector or not. By default, it won't run if the browser does
support the selector.

```js
focusWithinInit({ force: true });
```

#### replaceWith

Similar to the option for the PostCSS Plugin, `replaceWith` determines the
attribute or class to apply to an element when it's considered to be `:focus-within`.

```js
focusWithinInit({ replaceWith: '.focus-within });
```

This option should be used if it was changed at PostCSS configuration level.

### Using with Next.js

Given that Next.js imports packages both on the browser and on the server, you need to make sure that the package is only imported on the browser.

As outlined in the [Next.js documentation](https://nextjs.org/docs/advanced-features/dynamic-import#with-external-libraries), you need to load the package with a dynamic import:

```jsx
useEffect(async () => {
	const focusWithinInit = (await import('postcss-focus-within/browser')).default;
	focusWithinInit();
}, []);
```

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#focus-within-pseudo-class
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/postcss-focus-within

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Focus Within]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-focus-within
[Selectors Level 4 specification]: https://www.w3.org/TR/selectors-4/#the-focus-within-pseudo


---

# API Documentation

*Please use only this documented API when working with the parser. Methods
not documented here are subject to change at any point.*

## `parser` function

This is the module's main entry point.

```js
const parser = require('postcss-selector-parser');
```

### `parser([transform], [options])`

Creates a new `processor` instance

```js
const processor = parser();
```

Or, with optional transform function

```js
const transform = selectors => {
    selectors.walkUniversals(selector => {
        selector.remove();
    });
};

const processor = parser(transform)

// Example
const result = processor.processSync('*.class');
// => .class
```

[See processor documentation](#processor)

Arguments:

* `transform (function)`: Provide a function to work with the parsed AST.
* `options (object)`: Provide default options for all calls on the returned `Processor`.

### `parser.attribute([props])`

Creates a new attribute selector.

```js
parser.attribute({attribute: 'href'});
// => [href]
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.className([props])`

Creates a new class selector.

```js
parser.className({value: 'button'});
// => .button
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.combinator([props])`

Creates a new selector combinator.

```js
parser.combinator({value: '+'});
// => +
```

Arguments:

* `props (object)`: The new node's properties.

Notes:
* **Descendant Combinators** The value of descendant combinators created by the
  parser always just a single space (`" "`). For descendant selectors with no
  comments, additional space is now stored in `node.spaces.before`. Depending
  on the location of comments, additional spaces may be stored in
  `node.raws.spaces.before`, `node.raws.spaces.after`, or `node.raws.value`.
* **Named Combinators** Although, nonstandard and unlikely to ever become a standard,
  named combinators like `/deep/` and `/for/` are parsed as combinators. The
  `node.value` is name after being unescaped and normalized as lowercase. The
  original value for the combinator name is stored in `node.raws.value`.


### `parser.comment([props])`

Creates a new comment.

```js
parser.comment({value: '/* Affirmative, Dave. I read you. */'});
// => /* Affirmative, Dave. I read you. */
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.id([props])`

Creates a new id selector.

```js
parser.id({value: 'search'});
// => #search
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.nesting([props])`

Creates a new nesting selector.

```js
parser.nesting();
// => &
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.pseudo([props])`

Creates a new pseudo selector.

```js
parser.pseudo({value: '::before'});
// => ::before
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.root([props])`

Creates a new root node.

```js
parser.root();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.selector([props])`

Creates a new selector node.

```js
parser.selector();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.string([props])`

Creates a new string node.

```js
parser.string();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.tag([props])`

Creates a new tag selector.

```js
parser.tag({value: 'button'});
// => button
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.universal([props])`

Creates a new universal selector.

```js
parser.universal();
// => *
```

Arguments:

* `props (object)`: The new node's properties.

## Node types

### `node.type`

A string representation of the selector type. It can be one of the following;
`attribute`, `class`, `combinator`, `comment`, `id`, `nesting`, `pseudo`,
`root`, `selector`, `string`, `tag`, or `universal`. Note that for convenience,
these constants are exposed on the main `parser` as uppercased keys. So for
example you can get `id` by querying `parser.ID`.

```js
parser.attribute({attribute: 'href'}).type;
// => 'attribute'
```

### `node.parent`

Returns the parent node.

```js
root.nodes[0].parent === root;
```

### `node.toString()`, `String(node)`, or `'' + node`

Returns a string representation of the node.

```js
const id = parser.id({value: 'search'});
console.log(String(id));
// => #search
```

### `node.next()` & `node.prev()`

Returns the next/previous child of the parent node.

```js
const next = id.next();
if (next && next.type !== 'combinator') {
    throw new Error('Qualified IDs are not allowed!');
}
```

### `node.replaceWith(node[,...nodeN])`

Replace a node with another.

```js
const attr = selectors.first.first;
const className = parser.className({value: 'test'});
attr.replaceWith(className);
```

Arguments:

* `node`: The node to substitute the original with.
...
* `nodeN`: The node to substitute the original with.

### `node.remove()`

Removes the node from its parent node.

```js
if (node.type === 'id') {
    node.remove();
}
```

### `node.clone([opts])`

Returns a copy of a node, detached from any parent containers that the
original might have had.

```js
const cloned = node.clone();
```

### `node.isAtPosition(line, column)`

Return a `boolean` indicating whether this node includes the character at the
position of the given line and column. Returns `undefined` if the nodes lack
sufficient source metadata to determine the position.

Arguments:

* `line`: 1-index based line number relative to the start of the selector.
* `column`: 1-index based column number relative to the start of the selector.

### `node.spaces`

Extra whitespaces around the node will be moved into `node.spaces.before` and
`node.spaces.after`. So for example, these spaces will be moved as they have
no semantic meaning:

```css
      h1     ,     h2   {}
```

For descendent selectors, the value is always a single space.

```css
h1        h2 {}
```

Additional whitespace is found in either the `node.spaces.before` and `node.spaces.after` depending on the presence of comments or other whitespace characters. If the actual whitespace does not start or end with a single space, the node's raw value is set to the actual space(s) found in the source.

### `node.source`

An object describing the node's start/end, line/column source position.

Within the following CSS, the `.bar` class node ...

```css
.foo,
  .bar {}
```

... will contain the following `source` object.

```js
source: {
    start: {
        line: 2,
        column: 3
    },
    end: {
        line: 2,
        column: 6
    }
}
```

### `node.sourceIndex`

The zero-based index of the node within the original source string.

Within the following CSS, the `.baz` class node will have a `sourceIndex` of `12`.

```css
.foo, .bar, .baz {}
```

## Container types

The `root`, `selector`, and `pseudo` nodes have some helper methods for working
with their children.

### `container.nodes`

An array of the container's children.

```js
// Input: h1 h2
selectors.at(0).nodes.length   // => 3
selectors.at(0).nodes[0].value // => 'h1'
selectors.at(0).nodes[1].value // => ' '
```

### `container.first` & `container.last`

The first/last child of the container.

```js
selector.first === selector.nodes[0];
selector.last === selector.nodes[selector.nodes.length - 1];
```

### `container.at(index)`

Returns the node at position `index`.

```js
selector.at(0) === selector.first;
selector.at(0) === selector.nodes[0];
```

Arguments:

* `index`: The index of the node to return.

### `container.atPosition(line, column)`

Returns the node at the source position `line` and `column`.

```js
// Input: :not(.foo),\n#foo > :matches(ol, ul)
selector.atPosition(1, 1); // => :not(.foo)
selector.atPosition(2, 1); // => \n#foo
```

Arguments:

* `line`: The line number of the node to return.
* `column`: The column number of the node to return.

### `container.index(node)`

Return the index of the node within its container.

```js
selector.index(selector.nodes[2]) // => 2
```

Arguments:

* `node`: A node within the current container.

### `container.length`

Proxy to the length of the container's nodes.

```js
container.length === container.nodes.length
```

### `container` Array iterators

The container class provides proxies to certain Array methods; these are:

* `container.map === container.nodes.map`
* `container.reduce === container.nodes.reduce`
* `container.every === container.nodes.every`
* `container.some === container.nodes.some`
* `container.filter === container.nodes.filter`
* `container.sort === container.nodes.sort`

Note that these methods only work on a container's immediate children; recursive
iteration is provided by `container.walk`.

### `container.each(callback)`

Iterate the container's immediate children, calling `callback` for each child.
You may return `false` within the callback to break the iteration.

```js
let className;
selectors.each((selector, index) => {
    if (selector.type === 'class') {
        className = selector.value;
        return false;
    }
});
```

Note that unlike `Array#forEach()`, this iterator is safe to use whilst adding
or removing nodes from the container.

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  and `index` arguments.

### `container.walk(callback)`

Like `container#each`, but will also iterate child nodes as long as they are
`container` types.

```js
selectors.walk((selector, index) => {
    // all nodes
});
```

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  and `index` arguments.

This iterator is safe to use whilst mutating `container.nodes`,
like `container#each`.

### `container.walk` proxies

The container class provides proxy methods for iterating over types of nodes,
so that it is easier to write modules that target specific selectors. Those
methods are:

* `container.walkAttributes`
* `container.walkClasses`
* `container.walkCombinators`
* `container.walkComments`
* `container.walkIds`
* `container.walkNesting`
* `container.walkPseudos`
* `container.walkTags`
* `container.walkUniversals`

### `container.split(callback)`

This method allows you to split a group of nodes by returning `true` from
a callback. It returns an array of arrays, where each inner array corresponds
to the groups that you created via the callback.

```js
// (input) => h1 h2>>h3
const list = selectors.first.split(selector => {
    return selector.type === 'combinator';
});

// (node values) => [['h1', ' '], ['h2', '>>'], ['h3']]
```

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  as an argument.

### `container.prepend(node)` & `container.append(node)`

Add a node to the start/end of the container. Note that doing so will set
the parent property of the node to this container.

```js
const id = parser.id({value: 'search'});
selector.append(id);
```

Arguments:

* `node`: The node to add.

### `container.insertBefore(old, new[, ...newNodes])` & `container.insertAfter(old, new[, ...newNodes])`

Add a node before or after an existing node in a container:

```js
selectors.walk(selector => {
    if (selector.type !== 'class') {
        const className = parser.className({value: 'theme-name'});
        selector.parent.insertAfter(selector, className);
    }
});
```

Arguments:

* `old`: The existing node in the container.
* `new`: The new node to add before/after the existing node.

### `container.removeChild(node)`

Remove the node from the container. Note that you can also use
`node.remove()` if you would like to remove just a single node.

```js
selector.length // => 2
selector.remove(id)
selector.length // => 1;
id.parent       // undefined
```

Arguments:

* `node`: The node to remove.

### `container.removeAll()` or `container.empty()`

Remove all children from the container.

```js
selector.removeAll();
selector.length // => 0
```

## Root nodes

A root node represents a comma separated list of selectors. Indeed, all
a root's `toString()` method does is join its selector children with a ','.
Other than this, it has no special functionality and acts like a container.

### `root.trailingComma`

This will be set to `true` if the input has a trailing comma, in order to
support parsing of legacy CSS hacks.

## Selector nodes

A selector node represents a single complex selector. For example, this
selector string `h1 h2 h3, [href] > p`, is represented as two selector nodes.
It has no special functionality of its own.

## Pseudo nodes

A pseudo selector extends a container node; if it has any parameters of its
own (such as `h1:not(h2, h3)`), they will be its children. Note that the pseudo
`value` will always contain the colons preceding the pseudo identifier. This
is so that both `:before` and `::before` are properly represented in the AST.

## Attribute nodes

### `attribute.quoted`

Returns `true` if the attribute's value is wrapped in quotation marks, false if it is not.
Remains `undefined` if there is no attribute value.

```css
[href=foo] /* false */
[href='foo'] /* true */
[href="foo"] /* true */
[href] /* undefined */
```

### `attribute.qualifiedAttribute`

Returns the attribute name qualified with the namespace if one is given.

### `attribute.offsetOf(part)`

 Returns the offset of the attribute part specified relative to the
 start of the node of the output string. This is useful in raising
 error messages about a specific part of the attribute, especially
 in combination with `attribute.sourceIndex`.

 Returns `-1` if the name is invalid or the value doesn't exist in this
 attribute.

 The legal values for `part` are:

 * `"ns"` - alias for "namespace"
 * `"namespace"` - the namespace if it exists.
 * `"attribute"` - the attribute name
 * `"attributeNS"` - the start of the attribute or its namespace
 * `"operator"` - the match operator of the attribute
 * `"value"` - The value (string or identifier)
 * `"insensitive"` - the case insensitivity flag

### `attribute.raws.unquoted`

Returns the unquoted content of the attribute's value.
Remains `undefined` if there is no attribute value.

```css
[href=foo] /* foo */
[href='foo'] /* foo */
[href="foo"] /* foo */
[href] /* undefined */
```

### `attribute.spaces`

Like `node.spaces` with the `before` and `after` values containing the spaces
around the element, the parts of the attribute can also have spaces before
and after them. The for each of `attribute`, `operator`, `value` and
`insensitive` there is corresponding property of the same nam in
`node.spaces` that has an optional `before` or `after` string containing only
whitespace.

Note that corresponding values in `attributes.raws.spaces` contain values
including any comments. If set, these values will override the
`attribute.spaces` value. Take care to remove them if changing
`attribute.spaces`.

### `attribute.raws`

The raws object stores comments and other information necessary to re-render
the node exactly as it was in the source.

If a comment is embedded within the identifiers for the `namespace`, `attribute`
or `value` then a property is placed in the raws for that value containing the full source of the propery including comments.

If a comment is embedded within the space between parts of the attribute
then the raw for that space is set accordingly.

Setting an attribute's property `raws` value to be deleted.

For now, changing the spaces required also updating or removing any of the
raws values that override them.

Example: `[ /*before*/ href /* after-attr */ = /* after-operator */ te/*inside-value*/st/* wow */ /*omg*/i/*bbq*/ /*whodoesthis*/]` would parse as:

```js
{
  attribute: "href",
  operator: "=",
  value: "test",
  spaces: {
    before: '',
    after: '',
    attribute: { before: '  ', after: '  ' },
    operator: { after: '  ' },
    value: { after: ' ' },
    insensitive: { after: ' ' }
  },
  raws: {
    spaces: {
      attribute: { before: ' /*before*/ ', after: ' /* after-attr */ ' },
      operator: { after: ' /* after-operator */ ' },
      value: { after: '/* wow */ /*omg*/' },
      insensitive: { after: '/*bbq*/ /*whodoesthis*/' }
    },
    unquoted: 'test',
    value: 'te/*inside-value*/st'
  }
}
```

## `Processor`

### `ProcessorOptions`

* `lossless` - When `true`, whitespace is preserved. Defaults to `true`.
* `updateSelector` - When `true`, if any processor methods are passed a postcss
  `Rule` node instead of a string, then that Rule's selector is updated
  with the results of the processing. Defaults to `true`.

### `process|processSync(selectors, [options])`

Processes the `selectors`, returning a string from the result of processing.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

**Example:**

```js
const parser = require("postcss-selector-parser");
const processor = parser();

let result = processor.processSync(' .class');
console.log(result);
// =>  .class

// Asynchronous operation
let promise = processor.process(' .class').then(result => {
    console.log(result)
    // => .class
});

// To have the parser normalize whitespace values, utilize the options
result = processor.processSync('  .class  ', {lossless: false});
console.log(result);
// => .class

// For better syntax errors, pass a PostCSS Rule node.
const postcss = require('postcss');
rule = postcss.rule({selector: ' #foo    > a,  .class  '});
processor.process(rule, {lossless: false, updateSelector: true}).then(result => {
    console.log(result);
    // => #foo>a,.class
    console.log("rule:", rule.selector);
    // => rule: #foo>a,.class
})
```

Arguments:

* `selectors (string|postcss.Rule)`: Either a selector string or a PostCSS Rule
  node.
* `[options] (object)`: Process options


### `ast|astSync(selectors, [options])`

Like `process()` and `processSync()` but after
processing the `selectors` these methods return the `Root` node of the result
instead of a string.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

### `transform|transformSync(selectors, [options])`

Like `process()` and `processSync()` but after
processing the `selectors` these methods return the value returned by the
processor callback.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

### Error Handling Within Selector Processors

The root node passed to the selector processor callback
has a method `error(message, options)` that returns an
error object. This method should always be used to raise
errors relating to the syntax of selectors. The options
to this method are passed to postcss's error constructor
([documentation](http://postcss.org/api/#container-error)).

#### Async Error Example

```js
let processor = (root) => {
    return new Promise((resolve, reject) => {
        root.walkClasses((classNode) => {
            if (/^(.*)[-_]/.test(classNode.value)) {
                let msg = "classes may not have underscores or dashes in them";
                reject(root.error(msg, {
                    index: classNode.sourceIndex + RegExp.$1.length + 1,
                    word: classNode.value
                }));
            }
        });
        resolve();
    });
};

const postcss = require("postcss");
const parser = require("postcss-selector-parser");
const selectorProcessor = parser(processor);
const plugin = postcss.plugin('classValidator', (options) => {
    return (root) => {
        let promises = [];
        root.walkRules(rule => {
            promises.push(selectorProcessor.process(rule));
        });
        return Promise.all(promises);
    };
});
postcss(plugin()).process(`
.foo-bar {
  color: red;
}
`.trim(), {from: 'test.css'}).catch((e) => console.error(e.toString()));

// CssSyntaxError: classValidator: ./test.css:1:5: classes may not have underscores or dashes in them
//
// > 1 | .foo-bar {
//     |     ^
//   2 |   color: red;
//   3 | }
```

#### Synchronous Error Example

```js
let processor = (root) => {
    root.walkClasses((classNode) => {
        if (/.*[-_]/.test(classNode.value)) {
            let msg = "classes may not have underscores or dashes in them";
            throw root.error(msg, {
                index: classNode.sourceIndex,
                word: classNode.value
            });
        }
    });
};

const postcss = require("postcss");
const parser = require("postcss-selector-parser");
const selectorProcessor = parser(processor);
const plugin = postcss.plugin('classValidator', (options) => {
    return (root) => {
        root.walkRules(rule => {
            selectorProcessor.processSync(rule);
        });
    };
});
postcss(plugin()).process(`
.foo-bar {
  color: red;
}
`.trim(), {from: 'test.css'}).catch((e) => console.error(e.toString()));

// CssSyntaxError: classValidator: ./test.css:1:5: classes may not have underscores or dashes in them
//
// > 1 | .foo-bar {
//     |     ^
//   2 |   color: red;
//   3 | }
```


---

# 7.1.0

- feat: insert(Before|After) support multiple new node

# 7.0.0

- Feat: make insertions during iteration safe (major)

# 6.1.2

- Fixed: erroneous trailing combinators in pseudos

# 6.1.1

- Fixed: improve typings of constructor helpers (#292)

# 6.1.0

- Feature: add `sourceIndex` to `Selector` nodes (#290)

# 6.0.16

- Fixed: add missing `index` argument to `each`/`walk` callback types (#289)

# 6.0.15

- Fixed: Node#prev and Node#next type for the first/last node

# 6.0.14

- Fixed: type definitions

# 6.0.13

- Fixed: throw on unexpected pipe symbols

# 6.0.12

- Fixed: `clone` arguments should be optional

# 6.0.11

- Fixed: parse attribute case insensitivity flag

# 6.0.10

- Fixed: `isPseudoElement()` supports `:first-letter` and `:first-line`

# 6.0.9

- Fixed: `Combinator.raws` property type

# 6.0.8

- Fixed: reduced size

# 6.0.7

- Fixed: parse animation percents

# 6.0.6

- Fixed: parse quoted attributes containing a newline correctly

# 6.0.5

- Perf: rework unesc for a 63+% performance boost

# 6.0.4

- Fixed: ts errors

# 6.0.3

- Fixed: replace node built-in "util" module with "util-deprecate"
- Fixed: handle uppercase pseudo elements
- Fixed: do not create invalid combinator before comment

# 6.0.2

- Fixed an issue with parsing and stringifying an empty attribute value

# 6.0.1

- Fixed an issue with unicode surrogate pair parsing

# 6.0.0

- Updated: `cssesc` to 3.0.0 (major)
- Fixed: Issues with escaped `id` and `class` selectors

# 5.0.0

- Allow escaped dot within class name.
- Update PostCSS to 7.0.7 (patch)

# 5.0.0-rc.4

- Fixed an issue where comments immediately after an insensitive (in attribute)
  were not parsed correctly.
- Updated `cssesc` to 2.0.0 (major).
- Removed outdated integration tests.
- Added tests for custom selectors, tags with attributes, the universal
  selector with pseudos, and tokens after combinators.

# 5.0.0-rc.1

To ease adoption of the v5.0 release, we have relaxed the node version
check performed by npm at installation time to allow for node 4, which
remains officially unsupported, but likely to continue working for the
time being.

# 5.0.0-rc.0

This release has **BREAKING CHANGES** that were required to fix regressions
in 4.0.0 and to make the Combinator Node API consistent for all combinator
types. Please read carefully.

## Summary of Changes

* The way a descendent combinator that isn't a single space character (E.g. `.a  .b`) is stored in the AST has changed.
* Named Combinators (E.g. `.a /for/ .b`) are now properly parsed as a combinator.
* It is now possible to look up a node based on the source location of a character in that node and to query nodes if they contain some character.
* Several bug fixes that caused the parser to hang and run out of memory when a `/` was encountered have been fixed.
* The minimum supported version of Node is now `v6.0.0`.

### Changes to the Descendent Combinator

In prior releases, the value of a descendant combinator with multiple spaces included all the spaces.

* `.a   .b`: Extra spaces are now stored as space before.
  - Old & Busted:
    - `combinator.value === "   "`
  - New hotness:
    - `combinator.value === " " && combinator.spaces.before === "  "`
* `.a   /*comment*/.b`: A comment at the end of the combinator causes extra space to become after space.
  - Old & Busted:
    - `combinator.value === "   "`
    - `combinator.raws.value === "   /*comment/"`
  - New hotness:
    - `combinator.value === " "`
    - `combinator.spaces.after === "  "`
    - `combinator.raws.spaces.after === "  /*comment*/"`
* `.a<newline>.b`: whitespace that doesn't start or end with a single space character is stored as a raw value.
  - Old & Busted:
    - `combinator.value === "\n"`
    - `combinator.raws.value === undefined`
  - New hotness:
    - `combinator.value === " "`
    - `combinator.raws.value === "\n"`

### Support for "Named Combinators"

Although, nonstandard and unlikely to ever become a standard, combinators like `/deep/` and `/for/` are now properly supported.

Because they've been taken off the standardization track, there is no spec-official name for combinators of the form `/<ident>/`. However, I talked to [Tab Atkins](https://twitter.com/tabatkins) and we agreed to call them "named combinators" so now they are called that.

Before this release such named combinators were parsed without intention and generated three nodes of type `"tag"` where the first and last nodes had a value of `"/"`.

* `.a /for/ .b` is parsed as a combinator.
  - Old & Busted:
    - `root.nodes[0].nodes[1].type === "tag"`
    - `root.nodes[0].nodes[1].value === "/"`
  - New hotness:
    - `root.nodes[0].nodes[1].type === "combinator"`
    - `root.nodes[0].nodes[1].value === "/for/"`
* `.a /F\6fR/ .b` escapes are handled and uppercase is normalized.
  - Old & Busted:
    - `root.nodes[0].nodes[2].type === "tag"`
    - `root.nodes[0].nodes[2].value === "F\\6fR"`
  - New hotness:
    - `root.nodes[0].nodes[1].type === "combinator"`
    - `root.nodes[0].nodes[1].value === "/for/"`
    - `root.nodes[0].nodes[1].raws.value === "/F\\6fR/"`

### Source position checks and lookups

A new API was added to look up a node based on the source location.

```js
const selectorParser = require("postcss-selector-parser");
// You can find the most specific node for any given character
let combinator = selectorParser.astSync(".a > .b").atPosition(1,4);
combinator.toString() === " > ";
// You can check if a node includes a specific character
// Whitespace surrounding the node that is owned by that node
// is included in the check.
[2,3,4,5,6].map(column => combinator.isAtPosition(1, column));
// => [false, true, true, true, false]
```

# 4.0.0

This release has **BREAKING CHANGES** that were required to fix bugs regarding values with escape sequences. Please read carefully.

* **Identifiers with escapes** - CSS escape sequences are now hidden from the public API by default.
  The normal value of a node like a class name or ID, or an aspect of a node such as attribute
  selector's value, is unescaped. Escapes representing Non-ascii characters are unescaped into
  unicode characters. For example: `bu\tton, .\31 00, #i\2764\FE0Fu, [attr="value is \"quoted\""]`
  will parse respectively to the values `button`, `100`, `i❤️u`, `value is "quoted"`.
  The original escape sequences for these values can be found in the corresponding property name
  in `node.raws`. Where possible, deprecation warnings were added, but the nature
  of escape handling makes it impossible to detect what is escaped or not. Our expectation is
  that most users are neither expecting nor handling escape sequences in their use of this library,
  and so for them, this is a bug fix. Users who are taking care to handle escapes correctly can
  now update their code to remove the escape handling and let us do it for them.

* **Mutating values with escapes** - When you make an update to a node property that has escape handling
  The value is assumed to be unescaped, and any special characters are escaped automatically and
  the corresponding `raws` value is immediately updated. This can result in changes to the original
  escape format. Where the exact value of the escape sequence is important there are methods that
  allow both values to be set in conjunction. There are a number of new convenience methods for
  manipulating values that involve escapes, especially for attributes values where the quote mark
  is involved. See https://github.com/postcss/postcss-selector-parser/pull/133 for an extensive
  write-up on these changes.


**Upgrade/API Example**

In `3.x` there was no unescape handling and internal consistency of several properties was the caller's job to maintain. It was very easy for the developer
to create a CSS file that did not parse correctly when some types of values
were in use.

```js
const selectorParser = require("postcss-selector-parser");
let attr = selectorParser.attribute({attribute: "id", operator: "=", value: "a-value"});
attr.value; // => "a-value"
attr.toString(); // => [id=a-value]
// Add quotes to an attribute's value.
// All these values have to be set by the caller to be consistent:
// no internal consistency is maintained.
attr.raws.unquoted = attr.value
attr.value = "'" + attr.value + "'";
attr.value; // => "'a-value'"
attr.quoted = true;
attr.toString();  // => "[id='a-value']"
```

In `4.0` there is a convenient API for setting and mutating values
that may need escaping. Especially for attributes.

```js
const selectorParser = require("postcss-selector-parser");

// The constructor requires you specify the exact escape sequence
let className = selectorParser.className({value: "illegal class name", raws: {value: "illegal\\ class\\ name"}});
className.toString(); // => '.illegal\\ class\\ name'

// So it's better to set the value as a property
className = selectorParser.className();
// Most properties that deal with identifiers work like this
className.value = "escape for me";
className.value; // => 'escape for me'
className.toString(); // => '.escape\\ for\\ me'

// emoji and all non-ascii are escaped to ensure it works in every css file.
className.value = "😱🦄😍";
className.value; // => '😱🦄😍'
className.toString(); // => '.\\1F631\\1F984\\1F60D'

// you can control the escape sequence if you want, or do bad bad things
className.setPropertyAndEscape('value', 'xxxx', 'yyyy');
className.value; // => "xxxx"
className.toString(); // => ".yyyy"

// Pass a value directly through to the css output without escaping it. 
className.setPropertyWithoutEscape('value', '$REPLACE_ME$');
className.value; // => "$REPLACE_ME$"
className.toString(); // => ".$REPLACE_ME$"

// The biggest changes are to the Attribute class
// passing quoteMark explicitly is required to avoid a deprecation warning.
let attr = selectorParser.attribute({attribute: "id", operator: "=", value: "a-value", quoteMark: null});
attr.toString(); // => "[id=a-value]"
// Get the value with quotes on it and any necessary escapes.
// This is the same as reading attr.value in 3.x.
attr.getQuotedValue(); // => "a-value";
attr.quoteMark; // => null

// Add quotes to an attribute's value.
attr.quoteMark = "'"; // This is all that's required.
attr.toString(); // => "[id='a-value']"
attr.quoted; // => true
// The value is still the same, only the quotes have changed.
attr.value; // => a-value
attr.getQuotedValue(); // => "'a-value'";

// deprecated assignment, no warning because there's no escapes
attr.value = "new-value";
// no quote mark is needed so it is removed
attr.getQuotedValue(); // => "new-value";

// deprecated assignment, 
attr.value = "\"a 'single quoted' value\"";
// > (node:27859) DeprecationWarning: Assigning an attribute a value containing characters that might need to be escaped is deprecated. Call attribute.setValue() instead.
attr.getQuotedValue(); // => '"a \'single quoted\' value"';
// quote mark inferred from first and last characters.
attr.quoteMark; // => '"'

// setValue takes options to make manipulating the value simple.
attr.setValue('foo', {smart: true});
// foo doesn't require any escapes or quotes.
attr.toString(); // => '[id=foo]'
attr.quoteMark; // => null 

// An explicit quote mark can be specified
attr.setValue('foo', {quoteMark: '"'});
attr.toString(); // => '[id="foo"]'

// preserves quote mark by default
attr.setValue('bar');
attr.toString(); // => '[id="bar"]'
attr.quoteMark = null;
attr.toString(); // => '[id=bar]'

// with no arguments, it preserves quote mark even when it's not a great idea
attr.setValue('a value \n that should be quoted');
attr.toString(); // => '[id=a\\ value\\ \\A\\ that\\ should\\ be\\ quoted]'

// smart preservation with a specified default
attr.setValue('a value \n that should be quoted', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => "[id='a value \\A  that should be quoted']"
attr.quoteMark = '"';
// => '[id="a value \\A  that should be quoted"]'

// this keeps double quotes because it wants to quote the value and the existing value has double quotes.
attr.setValue('this should be quoted', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => '[id="this should be quoted"]'

// picks single quotes because the value has double quotes
attr.setValue('a "double quoted" value', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => "[id='a "double quoted" value']"

// setPropertyAndEscape lets you do anything you want. Even things that are a bad idea and illegal.
attr.setPropertyAndEscape('value', 'xxxx', 'the password is 42');
attr.value; // => "xxxx"
attr.toString(); // => "[id=the password is 42]"

// Pass a value directly through to the css output without escaping it. 
attr.setPropertyWithoutEscape('value', '$REPLACEMENT$');
attr.value; // => "$REPLACEMENT$"
attr.toString(); // => "[id=$REPLACEMENT$]"
```

# 3.1.2

* Fix: Removed dot-prop dependency since it's no longer written in es5.

# 3.1.1

* Fix: typescript definitions weren't in the published package.

# 3.1.0

* Fixed numerous bugs in attribute nodes relating to the handling of comments
  and whitespace. There's significant changes to `attrNode.spaces` and `attrNode.raws` since the `3.0.0` release.
* Added `Attribute#offsetOf(part)` to get the offset location of
  attribute parts like `"operator"` and `"value"`. This is most
  often added to `Attribute#sourceIndex` for error reporting.

# 3.0.0

## Breaking changes

* Some tweaks to the tokenizer/attribute selector parsing mean that whitespace
  locations might be slightly different to the 2.x code.
* Better attribute selector parsing with more validation; postcss-selector-parser
  no longer uses regular expressions to parse attribute selectors.
* Added an async API (thanks to @jacobp100); the default `process` API is now
  async, and the sync API is now accessed through `processSync` instead.
* `process()` and `processSync()` now return a string instead of the Processor
  instance.
* Tweaks handling of Less interpolation (thanks to @jwilsson).
* Removes support for Node 0.12.

## Other changes

* `ast()` and `astSync()` methods have been added to the `Processor`. These
  return the `Root` node of the selectors after processing them.
* `transform()` and `transformSync()` methods have been added to the
  `Processor`. These return the value returned by the processor callback
  after processing the selectors.
* Set the parent when inserting a node (thanks to @chriseppstein).
* Correctly adjust indices when using insertBefore/insertAfter (thanks to @tivac).
* Fixes handling of namespaces with qualified tag selectors.
* `process`, `ast` and `transform` (and their sync variants) now accept a
  `postcss` rule node. When provided, better errors are generated and selector
  processing is automatically set back to the rule selector (unless the `updateSelector` option is set to `false`.)
* Now more memory efficient when tokenizing selectors.

### Upgrade hints

The pattern of:

`rule.selector = processor.process(rule.selector).result.toString();`

is now:

`processor.processSync(rule)`

# 2.2.3

* Resolves an issue where the parser would not reduce multiple spaces between an
  ampersand and another simple selector in lossy mode (thanks to @adam-26).

# 2.2.2

* No longer hangs on an unescaped semicolon; instead the parser will throw
  an exception for these cases.

# 2.2.1

* Allows a consumer to specify whitespace tokens when creating a new Node
  (thanks to @Semigradsky).

# 2.2.0

* Added a new option to normalize whitespace when parsing the selector string
  (thanks to @adam-26).

# 2.1.1

* Better unquoted value handling within attribute selectors
  (thanks to @evilebottnawi).

# 2.1.0

* Added: Use string constants for all node types & expose them on the main
  parser instance (thanks to @Aweary).

# 2.0.0

This release contains the following breaking changes:

* Renamed all `eachInside` iterators to `walk`. For example, `eachTag` is now
  `walkTags`, and `eachInside` is now `walk`.
* Renamed `Node#removeSelf()` to `Node#remove()`.
* Renamed `Container#remove()` to `Container#removeChild()`.
* Renamed `Node#raw` to `Node#raws` (thanks to @davidtheclark).
* Now parses `&` as the *nesting* selector, rather than a *tag* selector.
* Fixes misinterpretation of Sass interpolation (e.g. `#{foo}`) as an
  id selector (thanks to @davidtheclark).

and;

* Fixes parsing of attribute selectors with equals signs in them
  (e.g. `[data-attr="foo=bar"]`) (thanks to @montmanu).
* Adds `quoted` and `raw.unquoted` properties to attribute nodes
  (thanks to @davidtheclark).

# 1.3.3

* Fixes an infinite loop on `)` and `]` tokens when they had no opening pairs.
  Now postcss-selector-parser will throw when it encounters these lone tokens.

# 1.3.2

* Now uses plain integers rather than `str.charCodeAt(0)` for compiled builds.

# 1.3.1

* Update flatten to v1.x (thanks to @shinnn).

# 1.3.0

* Adds a new node type, `String`, to fix a crash on selectors such as
  `foo:bar("test")`.

# 1.2.1

* Fixes a crash when the parser encountered a trailing combinator.

# 1.2.0

* A more descriptive error is thrown when the parser expects to find a
  pseudo-class/pseudo-element (thanks to @ashelley).
* Adds support for line/column locations for selector nodes, as well as a
  `Node#sourceIndex` method (thanks to @davidtheclark).

# 1.1.4

* Fixes a crash when a selector started with a `>` combinator. The module will
  now no longer throw if a selector has a leading/trailing combinator node.

# 1.1.3

* Fixes a crash on `@` tokens.

# 1.1.2

* Fixes an infinite loop caused by using parentheses in a non-pseudo element
  context.

# 1.1.1

* Fixes a crash when a backslash ended a selector string.

# 1.1.0

* Adds support for replacing multiple nodes at once with `replaceWith`
  (thanks to @jonathantneal).
* Parser no longer throws on sequential IDs and trailing commas, to support
  parsing of selector hacks.

# 1.0.1

* Fixes using `insertAfter` and `insertBefore` during iteration.

# 1.0.0

* Adds `clone` and `replaceWith` methods to nodes.
* Adds `insertBefore` and `insertAfter` to containers.
* Stabilises API.

# 0.0.5

* Fixes crash on extra whitespace inside a pseudo selector's parentheses.
* Adds sort function to the container class.
* Enables the parser to pass its input through without transforming.
* Iteration-safe `each` and `eachInside`.

# 0.0.4

* Tidy up redundant duplication.
* Fixes a bug where the parser would loop infinitely on universal selectors
  inside pseudo selectors.
* Adds `length` getter and `eachInside`, `map`, `reduce` to the container class.
* When a selector has been removed from the tree, the root node will no longer
  cast it to a string.
* Adds node type iterators to the container class (e.g. `eachComment`).
* Adds filter function to the container class.
* Adds split function to the container class.
* Create new node types by doing `parser.id(opts)` etc.
* Adds support for pseudo classes anywhere in the selector.

# 0.0.3

* Adds `next` and `prev` to the node class.
* Adds `first` and `last` getters to the container class.
* Adds `every` and `some` iterators to the container class.
* Add `empty` alias for `removeAll`.
* Combinators are now types of node.
* Fixes the at method so that it is not an alias for `index`.
* Tidy up creation of new nodes in the parser.
* Refactors how namespaces are handled for consistency & less redundant code.
* Refactors AST to use `nodes` exclusively, and eliminates excessive nesting.
* Fixes nested pseudo parsing.
* Fixes whitespace parsing.

# 0.0.2

* Adds support for namespace selectors.
* Adds support for selectors joined by escaped spaces - such as `.\31\ 0`.

# 0.0.1

* Initial release.


---

# postcss-selector-parser [![test](https://github.com/postcss/postcss-selector-parser/actions/workflows/test.yml/badge.svg)](https://github.com/postcss/postcss-selector-parser/actions/workflows/test.yml)

> Selector parser with built in methods for working with selector strings.

## Install

With [npm](https://npmjs.com/package/postcss-selector-parser) do:

```
npm install postcss-selector-parser
```

## Quick Start

```js
const parser = require('postcss-selector-parser');
const transform = selectors => {
    selectors.walk(selector => {
        // do something with the selector
        console.log(String(selector))
    });
};

const transformed = parser(transform).processSync('h1, h2, h3');
```

To normalize selector whitespace:

```js
const parser = require('postcss-selector-parser');
const normalized = parser().processSync('h1, h2, h3', {lossless: false});
// -> h1,h2,h3
```

Async support is provided through `parser.process` and will resolve a Promise
with the resulting selector string.

## API

Please see [API.md](API.md).

## Credits

* Huge thanks to Andrey Sitnik (@ai) for work on PostCSS which helped
  accelerate this module's development.

## License

MIT


---

# 5.0.0 - 2021-01-12

- Changed: use PostCSS 7 API
- Updated: Node support to 10.0.0 (major)

# 4.0.1 - 2020-10-28

- Fixed: Incorrect conversion of small-caps ([#15](https://github.com/postcss/postcss-font-variant/pull/15))

# 4.0.0 - 2018-09-17

- Changed: use PostCSS 7 API

# 3.0.0 - 2017-05-11

- Changed: use PostCSS 6 API

# 2.0.1 - 2016-07-08

- Fixed: existing font-feature-settings being duplicated.
  ([#8](https://github.com/postcss/postcss-font-variant/pull/8) - @ChaosExAnima)

# 2.0.0 - 2015-09-08

- Added: compatibility with postcss v5.x
- Removed: compatiblity with postcss v4.x

# 1.2.0 - 2015-08-13

- Added: compatibility with postcss v4.1.x
  ([#5](https://github.com/postcss/postcss-font-variant/pull/5))

# 1.1.0 - 2015-01-29

  - Fixed: Properly handle font-variant-position:normal ([#3](https://github.com/postcss/postcss-font-variant/pull/3))
  - Added: support font-kerning ([#2](https://github.com/postcss/postcss-font-variant/pull/2))

# 1.0.2 - 2015-01-27

- Fixed: Re–use existing font-feature-settings declarations to avoid creating multiples that override themselves ([#1](https://github.com/postcss/postcss-font-variant/pull/1))

# 1.0.1 - 2014-11-11

- Fixed: wrong space char that breaks on some environnements

# 1.0.0 - 2014-10-09

✨ First release based on [rework-font-variant](https://github.com/ianstormtaylor/rework-font-variant) v1.0.1


---

# PostCSS Font-Variant [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">](https://github.com/postcss/postcss/)

[![CSS Status](https://cssdb.org/badge/font-variant-property.svg)](https://cssdb.org/#font-variant-property)
[![Build Status](https://travis-ci.org/postcss/postcss-font-variant.svg)](https://travis-ci.org/postcss/postcss-font-variant)

PostCSS Font-Variant lets you use `font-variant` in CSS, following the
[CSS Fonts](https://www.w3.org/TR/css-fonts-3/#font-variant-prop) specification.

## Installation

```console
$ npm install postcss-font-variant
```

## Usage

```js
// dependencies
var postcss = require("postcss")
var fontVariant = require("postcss-font-variant")

// css to be processed
var css = fs.readFileSync("input.css", "utf8")

// process css using postcss-font-variant
var out = postcss()
  .use(fontVariant())
  .process(css)
  .css
```

Using this `input.css`:

```css
h2 {
  font-variant-caps: small-caps;
}

table {
  font-variant-numeric: lining-nums;
}
```

you will get:

```css
h2 {
  font-feature-settings: "smcp";
  font-variant-caps: small-caps;
}

table {
  font-feature-settings: "lnum";
  font-variant-numeric: lining-nums;
}

```

Checkout [tests](test) for more examples.

---

## Contributing

Work on a branch, install dev-dependencies, respect coding style & run tests before submitting a bug fix or a feature.

    $ git clone https://github.com/postcss/postcss-font-variant.git
    $ git checkout -b patch-1
    $ npm install
    $ npm test

## [Changelog](CHANGELOG.md)

## [License](LICENSE)


---

# Changes to PostCSS Gap Properties

### 6.0.0

_August 3, 2024_

- Updated: Support for Node v18+ (major).

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-gap-properties/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Gap Properties [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install postcss-gap-properties --save-dev`

[PostCSS Gap Properties] lets you use the `gap`, `column-gap`, and `row-gap`
shorthand properties in CSS, following the [CSS Grid Layout] specification.

```pcss
.standard-grid {
	display: grid;
	gap: 20px;
}

.spaced-grid {
	display: grid;
	column-gap: 40px;
	row-gap: 20px;
}

/* becomes */

.standard-grid {
	display: grid;
	grid-gap: 20px;
	gap: 20px;
}

.spaced-grid {
	display: grid;
	grid-column-gap: 40px;
	column-gap: 40px;
	grid-row-gap: 20px;
	row-gap: 20px;
}
```

## Usage

Add [PostCSS Gap Properties] to your project:

```bash
npm install postcss postcss-gap-properties --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssGapProperties = require('postcss-gap-properties');

postcss([
	postcssGapProperties(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## Options

### preserve

The `preserve` option determines whether the original notation
is preserved. By default, it is preserved.

```js
postcssGapProperties({ preserve: false })
```

```pcss
.standard-grid {
	display: grid;
	gap: 20px;
}

.spaced-grid {
	display: grid;
	column-gap: 40px;
	row-gap: 20px;
}

/* becomes */

.standard-grid {
	display: grid;
	grid-gap: 20px;
}

.spaced-grid {
	display: grid;
	grid-column-gap: 40px;
	grid-row-gap: 20px;
}
```

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#gap-properties
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/postcss-gap-properties

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Gap Properties]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-gap-properties
[CSS Grid Layout]: https://www.w3.org/TR/css-grid-1/#gutters


---

# Changes to PostCSS image-set() Function

### 7.0.0

_August 3, 2024_

- Updated: Support for Node v18+ (major).
- Updated [`@csstools/utilities`](https://github.com/csstools/postcss-plugins/tree/main/packages/utilities) to [`2.0.0`](https://github.com/csstools/postcss-plugins/tree/main/packages/utilities/CHANGELOG.md#200) (major)

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-image-set-function/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS image-set() Function [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][postcss]

[![NPM Version][npm-img]][npm-url]
[![Build Status][cli-img]][cli-url]
[<img alt="Discord" src="https://shields.io/badge/Discord-5865F2?logo=discord&logoColor=white">][discord]
<br><br>
[<img alt="Baseline Status" src="https://cssdb.org/images/badges-baseline/image-set-function.svg" height="20">][css-url]
[![CSS Standard Status][css-img]][css-url]

[PostCSS image-set() Function] lets you display resolution-dependent images
using the `image-set()` function in CSS, following the [CSS Images]
specification.

[!['Can I use' table](https://caniuse.bitsofco.de/image/css-image-set.png)](https://caniuse.com/#feat=css-image-set)

```pcss
.example {
  background-image: image-set(
    url(img.png) 1x,
    url(img@2x.png) 2x,
    url(img@print.png) 600dpi
  );
}

/* becomes */

.example {
  background-image: url(img.png);
}

@media (-webkit-min-device-pixel-ratio: 2), (min-resolution: 192dpi) {
  .example {
    background-image: url(img@2x.png);
  }
}


@media (-webkit-min-device-pixel-ratio: 6.25), (min-resolution: 600dpi) {
  .example {
    background-image: url(my@print.png);
  }
}

.example {
  background-image: image-set(
    url(img.png) 1x,
    url(img@2x.png) 2x,
    url(img@print.png) 600dpi
  );
}
```

## Usage

Add [PostCSS image-set() Function] to your project:

```bash
npm install postcss-image-set-function --save-dev
```

Use [PostCSS image-set() Function] as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssImageSetFunction = require('postcss-image-set-function');

postcss([
  postcssImageSetFunction(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```

[PostCSS image-set() Function] runs in all Node environments, with special
instructions for:

| [Node](INSTALL.md#node) | [PostCSS CLI](INSTALL.md#postcss-cli) | [Webpack](INSTALL.md#webpack) | [Gulp](INSTALL.md#gulp) | [Grunt](INSTALL.md#grunt) |
| --- | --- | --- | --- | --- |

## Options

### preserve

The `preserve` option determines whether the original declaration using
`image-set()` is preserved. By default, it is preserved.

```js
postcssImageSetFunction({ preserve: false })
```

```pcss
.example {
  background-image: image-set(
    url(img.png) 1x,
    url(img@2x.png) 2x,
    url(img@print.png) 600dpi
  );
}

/* becomes */

@media (-webkit-min-device-pixel-ratio: 1), (min-resolution: 96dpi) {
  .example {
    background-image: url(img.png);
  }
}

@media (-webkit-min-device-pixel-ratio: 2), (min-resolution: 192dpi) {
  .example {
    background-image: url(img@2x.png);
  }
}


@media (-webkit-min-device-pixel-ratio: 6.25), (min-resolution: 600dpi) {
  .example {
    background-image: url(my@print.png);
  }
}
```

### onInvalid

The `onInvalid` option determines how invalid usage of `image-set()` should be
handled. By default, invalid usages of `image-set()` are ignored.
They can be configured to emit a warning with `warn` or throw an exception with `throw`.

```js
postcssImageSetFunction({ onInvalid: 'warn' }) // warn on invalid usages
```

```js
postcssImageSetFunction({ onInvalid: 'throw' }) // throw on invalid usages
```

## Image Resolution

The `image-set()` function allows an author to provide multiple resolutions of
an image and let the browser decide which is most appropriate in a given
situation. The `image-set()` also never fails to choose an image; the
`<resolution>` just helps determine which of the images is chosen.

Since this plugin is not a browser, the image options are sorted by device
pixel ratio and the lowest ratio is used as the default, while the remaining
images are pushed behind media queries.

Therefore, this plugin can only approximate native browser behavior. While
images should typically match the resolution as the device they’re being viewed
in, other factors can affect the chosen image. For example, if the user is on a
slow mobile connection, the browser may prefer to select a lower-res image
rather than wait for a larger, resolution-matching image to load.

[cli-img]: https://github.com/csstools/postcss-plugins/workflows/test/badge.svg
[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-img]: https://cssdb.org/images/badges/image-set-function.svg
[css-url]: https://cssdb.org/#image-set-function
[discord]: https://discord.gg/bUadyRwkJS
[npm-img]: https://img.shields.io/npm/v/postcss-image-set-function.svg
[npm-url]: https://www.npmjs.com/package/postcss-image-set-function

[CSS Images]: https://drafts.csswg.org/css-images-4/#image-set-notation
[Gulp PostCSS]: https://github.com/postcss/gulp-postcss
[Grunt PostCSS]: https://github.com/nDmitry/grunt-postcss
[PostCSS]: https://github.com/postcss/postcss
[PostCSS Loader]: https://github.com/postcss/postcss-loader
[PostCSS image-set() Function]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-image-set-function


---

# Changes to PostCSS Lab Function

### 7.0.8

_February 23, 2025_

- Updated [`@csstools/css-color-parser`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-color-parser) to [`3.0.8`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-color-parser/CHANGELOG.md#308) (patch)

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-lab-function/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Lab Function [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][postcss]

[<img alt="npm version" src="https://img.shields.io/npm/v/postcss-lab-function.svg" height="20">][npm-url]
[<img alt="Build Status" src="https://github.com/csstools/postcss-plugins/workflows/test/badge.svg" height="20">][cli-url]
[<img alt="Discord" src="https://shields.io/badge/Discord-5865F2?logo=discord&logoColor=white">][discord]
<br><br>
[<img alt="Baseline Status" src="https://cssdb.org/images/badges-baseline/lab-function.svg" height="20">][css-url]
[<img alt="CSS Standard Status" src="https://cssdb.org/images/badges/lab-function.svg" height="20">][css-url]

[PostCSS Lab Function] lets you use `lab` and `lch` color functions in
CSS, following the [CSS Color] specification.

```css
.color-lab {
	color: lab(40% 56.6 39);
}

.color-lch {
	color: lch(40% 68.735435 34.568626);
}

/* becomes */

.color {
	color: rgb(179, 35, 35);
	color: color(display-p3 0.64331 0.19245 0.16771);
}

.color-lch {
	color: rgb(179, 35, 35);
	color: color(display-p3 0.64331 0.19245 0.16771);
}
```

## Usage

Add [PostCSS Lab Function] to your project:

```bash
npm install postcss postcss-lab-function --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssLabFunction = require('postcss-lab-function');

postcss([
  postcssLabFunction(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```

[PostCSS Lab Function] runs in all Node environments, with special
instructions for:

| [Node](INSTALL.md#node) | [PostCSS CLI](INSTALL.md#postcss-cli) | [Webpack](INSTALL.md#webpack) | [Gulp](INSTALL.md#gulp) | [Grunt](INSTALL.md#grunt) |
| --- | --- | --- | --- | --- |

## Options

### preserve

The `preserve` option determines whether the original functional color notation
is preserved. By default, it is not preserved.

```js
postcssLabFunction({ preserve: true })
```

```css
.color {
	color: lab(40% 56.6 39);
}

/* becomes */

.color {
	color: rgb(179, 35, 35);
	color: color(display-p3 0.64331 0.19245 0.16771);
	color: lab(40% 56.6 39);
}
```

### enableProgressiveCustomProperties

The `enableProgressiveCustomProperties` option determines whether the original notation
is wrapped with `@supports` when used in Custom Properties. By default, it is enabled.

> [!NOTE]
> We only recommend disabling this when you set `preserve` to `false` or if you bring your own fix for Custom Properties.  
> See what the plugin does in its [README](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-progressive-custom-properties#readme).

```js
postcssLabFunction({ enableProgressiveCustomProperties: false })
```

```css
:root {
	--firebrick: lab(40% 56.6 39);
}

/* becomes */

:root {
	--firebrick: rgb(178, 34, 34); /* will never be used, not even in older browser */
	--firebrick: color(display-p3 0.64331 0.19245 0.16771); /* will never be used, not even in older browser */
	--firebrick: lab(40% 56.6 39);
}
```

### subFeatures

#### displayP3

The `subFeatures.displayP3` option determines if `color(display-p3 ...)` is used as a fallback.<br>
By default, it is enabled.

`display-p3` can display wider gamut colors than `rgb` on some devices.

```js
postcssOKLabFunction({
	subFeatures: {
		displayP3: false
	}
})
```

```css
.color {
	color: lab(40% 56.6 39);
}

/* becomes */

.color {
	color: rgb(179, 35, 35);
	color: lab(40% 56.6 39);
}
```

## Copyright : color conversions

This software or document includes material copied from or derived from https://github.com/w3c/csswg-drafts/tree/main/css-color-4. Copyright © 2022 W3C® (MIT, ERCIM, Keio, Beihang).

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#lab-function
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/postcss-lab-function

[CSS Color]: https://drafts.csswg.org/css-color/#specifying-lab-lch
[Gulp PostCSS]: https://github.com/postcss/gulp-postcss
[Grunt PostCSS]: https://github.com/nDmitry/grunt-postcss
[PostCSS]: https://github.com/postcss/postcss
[PostCSS Loader]: https://github.com/postcss/postcss-loader
[PostCSS Lab Function]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-lab-function


---

<div align="center">
  <img 
    width="180" 
    height="180" 
    hspace="10"
    alt="PostCSS Logo"
    src="https://api.postcss.org/logo.svg">
  <a href="https://github.com/webpack/webpack">
    <img 
      width="200" 
      height="200" 
      hspace="10"
      src="https://cdn.rawgit.com/webpack/media/e7485eb2/logo/icon.svg">
  </a>
  <div align="center">
    <a href="https://evilmartians.com/?utm_source=postcss">
      <img 
        src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg"
        alt="Sponsored by Evil Martians" 
        width="236" 
        height="54" 
        vspace="10">
    </a>
  </div>
</div>

[![npm][npm]][npm-url]
[![node][node]][node-url]
[![tests][tests]][tests-url]
[![coverage][cover]][cover-url]
[![size][size]][size-url]

Webpack discussion: [![discussion][discussion]][discussion-url]

PostCSS chat: [![chat-postcss][chat-postcss]][chat-postcss-url]

# postcss-loader

Loader to process CSS with [`PostCSS`](https://github.com/postcss/postcss).

## Getting Started

You need webpack v5 to use the latest version. For Webpack v4, you have to install postcss-loader v4.

To begin, you'll need to install `postcss-loader` and `postcss`:

```console
npm install --save-dev postcss-loader postcss
```

or

```console
yarn add -D postcss-loader postcss
```

or

```console
pnpm add -D postcss-loader postcss
```

Then add the plugin to your `webpack` config. For example:

> In the following configuration the plugin [`postcss-preset-env`](https://github.com/csstools/postcss-preset-env) is used, which is not installed by default.

**file.js**

```js
import css from "file.css";
```

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          "style-loader",
          "css-loader",
          {
            loader: "postcss-loader",
            options: {
              postcssOptions: {
                plugins: [
                  [
                    "postcss-preset-env",
                    {
                      // Options
                    },
                  ],
                ],
              },
            },
          },
        ],
      },
    ],
  },
};
```

Alternative use with [config files](#config):

**postcss.config.js**

```js
module.exports = {
  plugins: [
    [
      "postcss-preset-env",
      {
        // Options
      },
    ],
  ],
};
```

The loader **automatically** searches for configuration files.

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: ["style-loader", "css-loader", "postcss-loader"],
      },
    ],
  },
};
```

And run `webpack` via your preferred method.

## Options

- [`execute`](#execute)
- [`postcssOptions`](#postcssOptions)
- [`sourceMap`](#sourcemap)
- [`implementation`](#implementation)

### `execute`

Type:

```ts
type execute = boolean;
```

Default: `undefined`

Enable PostCSS Parser support in `CSS-in-JS`.
If you use JS styles the [`postcss-js`](https://github.com/postcss/postcss-js) parser, add the `execute` option.

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.style.js$/,
        use: [
          "style-loader",
          {
            loader: "css-loader",
          },
          {
            loader: "postcss-loader",
            options: {
              postcssOptions: {
                parser: "postcss-js",
              },
              execute: true,
            },
          },
        ],
      },
    ],
  },
};
```

### `postcssOptions`

See the file [`./src/config.d.ts`](./src/config.d.ts).

Type:

```ts
import type { Config as PostCSSConfig } from "postcss-load-config";
import type { LoaderContext } from "webpack";

type PostCSSLoaderContext = LoaderContext<PostCSSConfig>;

interface PostCSSLoaderAPI {
  mode: PostCSSLoaderContext["mode"];
  file: PostCSSLoaderContext["resourcePath"];
  webpackLoaderContext: PostCSSLoaderContext;
  env: PostCSSLoaderContext["mode"];
  options: PostCSSConfig;
}

export type PostCSSLoaderOptions =
  | PostCSSConfig
  | ((api: PostCSSLoaderAPI) => PostCSSConfig);
```

Default: `undefined`

Allows to set [`PostCSS options`](https://postcss.org/api/#processoptions) and plugins.

All `PostCSS` options are supported.
There is the special `config` option for config files. How it works and how it can be configured is described below.

We recommend do not specify `from`, `to` and `map` options, because this can lead to wrong path in source maps.
If you need source maps please use the [`sourcemap`](#sourcemap) option.

For large projects, to optimize performance of the loader, it is better to provide `postcssOptions` in loader
config and specify `config: false`. This approach removes the need to lookup and load external config files multiple
times during compilation.

#### `object`

Setup `plugins`:

**webpack.config.js** (**recommended**)

```js
const myOtherPostcssPlugin = require("postcss-my-plugin");

module.exports = {
  module: {
    rules: [
      {
        test: /\.sss$/i,
        loader: "postcss-loader",
        options: {
          postcssOptions: {
            plugins: [
              "postcss-import",
              ["postcss-short", { prefix: "x" }],
              require.resolve("my-postcss-plugin"),
              myOtherPostcssPlugin({ myOption: true }),
              // Deprecated and will be removed in the next major release
              { "postcss-nested": { preserveEmpty: true } },
            ],
          },
        },
      },
    ],
  },
};
```

**webpack.config.js** (**deprecated**, will be removed in the next major release)

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.sss$/i,
        loader: "postcss-loader",
        options: {
          postcssOptions: {
            plugins: {
              "postcss-import": {},
              "postcss-short": { prefix: "x" },
            },
          },
        },
      },
    ],
  },
};
```

Setup `syntax`:

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.sss$/i,
        loader: "postcss-loader",
        options: {
          postcssOptions: {
            // Can be `string`
            syntax: "sugarss",
            // Can be `object`
            syntax: require("sugarss"),
          },
        },
      },
    ],
  },
};
```

Setup `parser`:

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.sss$/i,
        loader: "postcss-loader",
        options: {
          postcssOptions: {
            // Can be `string`
            parser: "sugarss",
            // Can be `object`
            parser: require("sugarss"),
            // Can be `function`
            parser: require("sugarss").parse,
          },
        },
      },
    ],
  },
};
```

Setup `stringifier`:

**webpack.config.js**

```js
const Midas = require("midas");
const midas = new Midas();

module.exports = {
  module: {
    rules: [
      {
        test: /\.sss$/i,
        loader: "postcss-loader",
        options: {
          postcssOptions: {
            // Can be `string`
            stringifier: "sugarss",
            // Can be `object`
            stringifier: require("sugarss"),
            // Can be `function`
            stringifier: midas.stringifier,
          },
        },
      },
    ],
  },
};
```

#### `function`

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.(css|sss)$/i,
        loader: "postcss-loader",
        options: {
          postcssOptions: (loaderContext) => {
            if (/\.sss$/.test(loaderContext.resourcePath)) {
              return {
                parser: "sugarss",
                plugins: [
                  ["postcss-short", { prefix: "x" }],
                  "postcss-preset-env",
                ],
              };
            }

            return {
              plugins: [
                ["postcss-short", { prefix: "x" }],
                "postcss-preset-env",
              ],
            };
          },
        },
      },
    ],
  },
};
```

#### `config`

Type:

```ts
type config = boolean | string;
```

Default: `true`

Allows to set options using config files.
Options specified in the config file are combined with options passed to the loader, the loader options overwrite options from config.

##### Config Files

The loader will search up the directory tree for configuration in the following places:

- a `postcss` property in `package.json`
- a `.postcssrc` file in JSON or YAML format
- a `.postcssrc.json`, `.postcssrc.yaml`, `.postcssrc.yml`, `.postcssrc.js`, or `.postcssrc.cjs` file
- a `postcss.config.js` or `postcss.config.cjs` CommonJS module exporting an object (**recommended**)

##### Examples of Config Files

Using `object` notation:

**postcss.config.js** (**recommend**)

```js
module.exports = {
  // You can specify any options from https://postcss.org/api/#processoptions here
  // parser: 'sugarss',
  plugins: [
    // Plugins for PostCSS
    ["postcss-short", { prefix: "x" }],
    "postcss-preset-env",
  ],
};
```

Using `function` notation:

**postcss.config.js** (**recommend**)

```js
module.exports = (api) => {
  // `api.file` - path to the file
  // `api.mode` - `mode` value of webpack, please read https://webpack.js.org/configuration/mode/
  // `api.webpackLoaderContext` - loader context for complex use cases
  // `api.env` - alias `api.mode` for compatibility with `postcss-cli`
  // `api.options` - the `postcssOptions` options

  if (/\.sss$/.test(api.file)) {
    return {
      // You can specify any options from https://postcss.org/api/#processoptions here
      parser: "sugarss",
      plugins: [
        // Plugins for PostCSS
        ["postcss-short", { prefix: "x" }],
        "postcss-preset-env",
      ],
    };
  }

  return {
    // You can specify any options from https://postcss.org/api/#processoptions here
    plugins: [
      // Plugins for PostCSS
      ["postcss-short", { prefix: "x" }],
      "postcss-preset-env",
    ],
  };
};
```

**postcss.config.js** (**deprecated**, will be removed in the next major release)

```js
module.exports = {
  // You can specify any options from https://postcss.org/api/#processoptions here
  // parser: 'sugarss',
  plugins: {
    // Plugins for PostCSS
    "postcss-short": { prefix: "x" },
    "postcss-preset-env": {},
  },
};
```

##### Config Cascade

You can use different `postcss.config.js` files in different directories.
Config lookup starts from `path.dirname(file)` and walks the file tree upwards until a config file is found.

```
|– components
| |– component
| | |– index.js
| | |– index.png
| | |– style.css (1)
| | |– postcss.config.js (1)
| |– component
| | |– index.js
| | |– image.png
| | |– style.css (2)
|
|– postcss.config.js (1 && 2 (recommended))
|– webpack.config.js
|
|– package.json
```

After setting up your `postcss.config.js`, add `postcss-loader` to your `webpack.config.js`.
You can use it standalone or in conjunction with `css-loader` (recommended).

Use it **before** `css-loader` and `style-loader`, but **after** other preprocessor loaders like e.g `sass|less|stylus-loader`, if you use any (since [webpack loaders evaluate right to left/bottom to top](https://webpack.js.org/concepts/loaders/#configuration)).

**webpack.config.js** (**recommended**)

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          "style-loader",
          {
            loader: "css-loader",
            options: {
              importLoaders: 1,
            },
          },
          "postcss-loader",
        ],
      },
    ],
  },
};
```

#### `boolean`

Enables/Disables autoloading config.

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "postcss-loader",
        options: {
          postcssOptions: {
            config: false,
          },
        },
      },
    ],
  },
};
```

#### String

Allows to specify the path to the config file.

**webpack.config.js**

```js
const path = require("path");

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "postcss-loader",
        options: {
          postcssOptions: {
            config: path.resolve(__dirname, "custom.config.js"),
          },
        },
      },
    ],
  },
};
```

### `sourceMap`

Type:

```ts
type sourceMap = boolean;
```

Default: depends on the `compiler.devtool` value

By default generation of source maps depends on the [`devtool`](https://webpack.js.org/configuration/devtool/) option.
All values enable source map generation except `eval` and `false` value.

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          { loader: "style-loader" },
          { loader: "css-loader", options: { sourceMap: true } },
          { loader: "postcss-loader", options: { sourceMap: true } },
          { loader: "sass-loader", options: { sourceMap: true } },
        ],
      },
    ],
  },
};
```

Alternative setup:

**webpack.config.js**

```js
module.exports = {
  devtool: "source-map",
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          { loader: "style-loader" },
          { loader: "css-loader" },
          { loader: "postcss-loader" },
          { loader: "sass-loader" },
        ],
      },
    ],
  },
};
```

### `implementation`

Type:

```ts
type implementation = object;
```

type of `implementation` should be the same as [postcss.d.ts](https://github.com/postcss/postcss/blob/main/lib/postcss.d.ts)

Default: `postcss`

The special `implementation` option determines which implementation of PostCSS to use. Overrides the locally installed `peerDependency` version of `postcss`.

**This option is only really useful for downstream tooling authors to ease the PostCSS 7-to-8 transition.**

#### `function`

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          { loader: "style-loader" },
          { loader: "css-loader" },
          {
            loader: "postcss-loader",
            options: { implementation: require("postcss") },
          },
          { loader: "sass-loader" },
        ],
      },
    ],
  },
};
```

#### String

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          { loader: "style-loader" },
          { loader: "css-loader" },
          {
            loader: "postcss-loader",
            options: { implementation: require.resolve("postcss") },
          },
          { loader: "sass-loader" },
        ],
      },
    ],
  },
};
```

## Examples

### SugarSS

You'll need to install `sugarss`:

```console
npm install --save-dev sugarss
```

Using [`SugarSS`](https://github.com/postcss/sugarss) syntax.

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.sss$/i,
        use: [
          "style-loader",
          {
            loader: "css-loader",
            options: { importLoaders: 1 },
          },
          {
            loader: "postcss-loader",
            options: {
              postcssOptions: {
                parser: "sugarss",
              },
            },
          },
        ],
      },
    ],
  },
};
```

### Autoprefixer

You'll need to install `autoprefixer`:

```console
npm install --save-dev autoprefixer
```

Add vendor prefixes to CSS rules using [`autoprefixer`](https://github.com/postcss/autoprefixer).

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          "style-loader",
          {
            loader: "css-loader",
            options: { importLoaders: 1 },
          },
          {
            loader: "postcss-loader",
            options: {
              postcssOptions: {
                plugins: [
                  [
                    "autoprefixer",
                    {
                      // Options
                    },
                  ],
                ],
              },
            },
          },
        ],
      },
    ],
  },
};
```

> **Warning**
>
> [`postcss-preset-env`](https://github.com/csstools/postcss-preset-env) includes [`autoprefixer`](https://github.com/postcss/autoprefixer), so adding it separately is not necessary if you already use the preset. More [information](https://github.com/csstools/postcss-preset-env#autoprefixer)

### PostCSS Preset Env

You'll need to install `postcss-preset-env`:

```console
npm install --save-dev postcss-preset-env
```

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          "style-loader",
          {
            loader: "css-loader",
            options: { importLoaders: 1 },
          },
          {
            loader: "postcss-loader",
            options: {
              postcssOptions: {
                plugins: [
                  [
                    "postcss-preset-env",
                    {
                      // Options
                    },
                  ],
                ],
              },
            },
          },
        ],
      },
    ],
  },
};
```

### CSS Modules

What is `CSS Modules`? Please [read](https://github.com/webpack-contrib/css-loader#modules).

No additional options required on the `postcss-loader` side.
To make them work properly, either add the `css-loader`’s `importLoaders` option.

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          "style-loader",
          {
            loader: "css-loader",
            options: {
              modules: true,
              importLoaders: 1,
            },
          },
          "postcss-loader",
        ],
      },
    ],
  },
};
```

### CSS-in-JS and [`postcss-js`](https://github.com/postcss/postcss-js)

You'll need to install `postcss-js`:

```console
npm install --save-dev postcss-js
```

If you want to process styles written in JavaScript, use the [`postcss-js`](https://github.com/postcss/postcss-js) parser.

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.style.js$/,
        use: [
          "style-loader",
          {
            loader: "css-loader",
            options: {
              importLoaders: 2,
            },
          },
          {
            loader: "postcss-loader",
            options: {
              postcssOptions: {
                parser: "postcss-js",
              },
              execute: true,
            },
          },
          "babel-loader",
        ],
      },
    ],
  },
};
```

As result you will be able to write styles in the following way

```js
import colors from "./styles/colors";

export default {
  ".menu": {
    color: colors.main,
    height: 25,
    "&_link": {
      color: "white",
    },
  },
};
```

> **Warning**
>
> If you are using Babel you need to do the following in order for the setup to work

> 1. Add [`babel-plugin-add-module-exports`](https://github.com/59naga/babel-plugin-add-module-exports) to your configuration.
> 2. You need to have only one **default** export per style module.

### Extract CSS

Using [`mini-css-extract-plugin`](https://github.com/webpack-contrib/mini-css-extract-plugin).

**webpack.config.js**

```js
const isProductionMode = process.env.NODE_ENV === "production";

const MiniCssExtractPlugin = require("mini-css-extract-plugin");

module.exports = {
  mode: isProductionMode ? "production" : "development",
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          isProductionMode ? MiniCssExtractPlugin.loader : "style-loader",
          "css-loader",
          "postcss-loader",
        ],
      },
    ],
  },
  plugins: [
    new MiniCssExtractPlugin({
      filename: isProductionMode ? "[name].[contenthash].css" : "[name].css",
    }),
  ],
};
```

### Emit assets

To write a asset from PostCSS plugin to the webpack, need to add a message in `result.messages`.

The message should contain the following fields:

- `type` = `asset` - Message type (require, should be equal `asset`)
- `file` - file name (require)
- `content` - file content (require)
- `sourceMap` - sourceMap
- `info` - asset info

**webpack.config.js**

```js
const postcssCustomPlugin = (opts = {}) => {
  return {
    postcssPlugin: "postcss-custom-plugin",
    Once: (root, { result }) => {
      result.messages.push({
        type: "asset",
        file: "sprite.svg",
        content: "<svg>...</svg>",
      });
    },
  };
};

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          "style-loader",
          "css-loader",
          {
            loader: "postcss-loader",
            options: {
              postcssOptions: {
                plugins: [postcssCustomPlugin()],
              },
            },
          },
        ],
      },
    ],
  },
};
```

### Add dependencies, contextDependencies, buildDependencies, missingDependencies

The dependencies are necessary for webpack to understand when it needs to run recompilation on the changed files.

There are two way to add dependencies:

1. (Recommended). The plugin may emit messages in `result.messages`.

The message should contain the following fields:

- `type` = `dependency` - Message type (require, should be equal `dependency`, `context-dependency`, `build-dependency` or `missing-dependency`)
- `file` - absolute file path (require)

**webpack.config.js**

```js
const path = require("path");

const postcssCustomPlugin = (opts = {}) => {
  return {
    postcssPlugin: "postcss-custom-plugin",
    Once: (root, { result }) => {
      result.messages.push({
        type: "dependency",
        file: path.resolve(__dirname, "path", "to", "file"),
      });
    },
  };
};

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          "style-loader",
          "css-loader",
          {
            loader: "postcss-loader",
            options: {
              postcssOptions: {
                plugins: [postcssCustomPlugin()],
              },
            },
          },
        ],
      },
    ],
  },
};
```

Or you can use ready-made plugin [postcss-add-dependencies](https://www.npmjs.com/package/postcss-add-dependencies).

2. Pass `loaderContext` in plugin.

**webpack.config.js**

```js
const path = require("path");

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          "style-loader",
          "css-loader",
          {
            loader: "postcss-loader",
            options: {
              postcssOptions: {
                config: path.resolve(__dirname, "path/to/postcss.config.js"),
              },
            },
          },
        ],
      },
    ],
  },
};
```

**postcss.config.js**

```js
module.exports = (api) => ({
  plugins: [
    require("path/to/postcssCustomPlugin.js")({
      loaderContext: api.webpackLoaderContext,
    }),
  ],
});
```

**postcssCustomPlugin.js**

```js
const path = require("path");

const postcssCustomPlugin = (opts = {}) => {
  return {
    postcssPlugin: "postcss-custom-plugin",
    Once: (root, { result }) => {
      opts.loaderContext.addDependency(
        path.resolve(__dirname, "path", "to", "file")
      );
    },
  };
};

postcssCustomPlugin.postcss = true;
module.exports = postcssCustomPlugin;
```

## Contributing

Please take a moment to read our contributing guidelines if you haven't yet done so.

[CONTRIBUTING](./.github/CONTRIBUTING.md)

## License

[MIT](./LICENSE)

[npm]: https://img.shields.io/npm/v/postcss-loader.svg
[npm-url]: https://npmjs.com/package/postcss-loader
[node]: https://img.shields.io/node/v/postcss-loader.svg
[node-url]: https://nodejs.org
[tests]: https://github.com/webpack-contrib/postcss-loader/workflows/postcss-loader/badge.svg
[tests-url]: https://github.com/webpack-contrib/postcss-loader/actions
[cover]: https://codecov.io/gh/webpack-contrib/postcss-loader/branch/master/graph/badge.svg
[cover-url]: https://codecov.io/gh/webpack-contrib/postcss-loader
[discussion]: https://img.shields.io/github/discussions/webpack/webpack
[discussion-url]: https://github.com/webpack/webpack/discussions
[chat-postcss]: https://badges.gitter.im/postcss/postcss.svg
[chat-postcss-url]: https://gitter.im/postcss/postcss
[size]: https://packagephobia.now.sh/badge?p=postcss-loader
[size-url]: https://packagephobia.now.sh/result?p=postcss-loader


---

# Changes to PostCSS Logical Properties

### 8.1.0

_February 23, 2025_

- Add: `ignoreCustomProperties` plugin option.

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-logical/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Logical Properties and Values [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install postcss-logical --save-dev`

[PostCSS Logical Properties and Values]  lets you use logical, rather than physical, direction and dimension mappings in CSS, following the [CSS Logical Properties and Values] specification.

```css
.element {
	block-size: 100px;
	max-inline-size: 400px;
	inline-size: 200px;
	padding-block: 10px 20px;
	margin-inline: auto;
	border-block-width: 2px;
	border-block-style: solid;
}

/* becomes */

.element {
	height: 100px;
	max-width: 400px;
	width: 200px;
	padding-top: 10px;
	padding-bottom: 20px;
	margin-left: auto;
	margin-right: auto;
	border-top-width: 2px;
	border-bottom-width: 2px;
	border-top-style: solid;
	border-bottom-style: solid;
}
```

## Usage

Add [PostCSS Logical Properties and Values] to your project:

```bash
npm install postcss postcss-logical --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssLogical = require('postcss-logical');

postcss([
	postcssLogical(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## Options

### `blockDirection` and `inlineDirection`

The `blockDirection` and `inlineDirection` options allow you to specify the direction of the block and inline axes. The default values are `top-to-bottom` and `left-to-right` respectively, which would match any latin language.

**You should tweak these values so that they are specific to your language and writing mode.**

```js
postcssLogical({
	blockDirection: 'right-to-left',
	inlineDirection: 'top-to-bottom'
})
```

```css
.element {
	block-size: 100px;
	max-inline-size: 400px;
	inline-size: 200px;
	padding-block: 10px 20px;
	margin-inline: auto;
	border-block-width: 2px;
	border-block-style: solid;
}

/* becomes */

.element {
	width: 100px;
	max-height: 400px;
	height: 200px;
	padding-right: 10px;
	padding-left: 20px;
	margin-top: auto;
	margin-bottom: auto;
	border-right-width: 2px;
	border-left-width: 2px;
	border-right-style: solid;
	border-left-style: solid;
}
```

Each direction must be one of the following:

- `top-to-bottom`
- `bottom-to-top`
- `left-to-right`
- `right-to-left`

You can't mix two vertical directions or two horizontal directions so for example `top-to-bottom` and `right-to-left` are valid, but `top-to-bottom` and `bottom-to-top` are not.

Please do note that `text-align` won't be transformed if `inlineDirection` becomes vertical.

### `ignoreCustomProperties`

The `ignoreCustomProperties` option allows you to ignore any properties containing `var()`.  
`postcss-logical` assumes that all custom properties are single value (e.g. `--foo: 10px;`) and will assign these to physical properties as fallbacks for logical properties.  

This will produce broken declarations when your custom properties contain multiple values instead (e.g. `--foo: 1px 2px;`).

```css
:root {
	--inset-a: 10px;
}

.foo {
	inset: var(--inset-a);
}

:root {
	--inset-b: 1px 2px 3px 4px;
}

.bar {
	inset: var(--inset-b);
}

/* becomes */

:root {
	--inset-a: 10px;
}

.foo {
	top: var(--inset-a);
	right: var(--inset-a);
	bottom: var(--inset-a);
	left: var(--inset-a);
}

:root {
	--inset-b: 1px 2px 3px 4px;
}

.bar {
	top: var(--inset-b);
	right: var(--inset-b);
	bottom: var(--inset-b);
	left: var(--inset-b);
}
```

With `ignoreCustomProperties` set to `true`:

```css
:root {
	--inset-a: 10px;
}

.foo {
	inset: var(--inset-a);
}

:root {
	--inset-b: 1px 2px 3px 4px;
}

.bar {
	inset: var(--inset-b);
}

/* becomes */

:root {
	--inset-a: 10px;
}

.foo {
	inset: var(--inset-a);
}

:root {
	--inset-b: 1px 2px 3px 4px;
}

.bar {
	inset: var(--inset-b);
}
```

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#logical-properties-and-values
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/postcss-logical

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Logical Properties and Values]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-logical
[CSS Logical Properties and Values]: https://www.w3.org/TR/css-logical-1/


---

# [postcss][postcss]-merge-idents

> Merge keyframe and counter style identifiers.


## Install

With [npm](https://npmjs.org/package/postcss-merge-idents) do:

```
npm install postcss-merge-idents --save
```


## Example

This module will merge identifiers such as `@keyframes` and `@counter-style`,
if their properties are identical. Then, it will update those declarations that
depend on the duplicated property.

### Input

```css
@keyframes rotate {
    from { transform: rotate(0) }
    to { transform: rotate(360deg) }
}

@keyframes flip {
    from { transform: rotate(0) }
    to { transform: rotate(360deg) }
}

.rotate {
    animation-name: rotate
}

.flip {
    animation-name: flip
}
```

### Output

```css
@keyframes flip {
    from { transform: rotate(0) }
    to { transform: rotate(360deg) }
}

.rotate {
    animation-name: flip
}

.flip {
    animation-name: flip
}
```


## Usage

See the [PostCSS documentation](https://github.com/postcss/postcss#usage) for
examples for your environment.


## Contributors

See [CONTRIBUTORS.md](https://github.com/cssnano/cssnano/blob/master/CONTRIBUTORS.md).


## License

MIT © [Ben Briggs](http://beneb.info)


[postcss]: https://github.com/postcss/postcss


---

# [postcss][postcss]-merge-longhand

> Merge longhand properties into shorthand with PostCSS.

## Install

With [npm](https://npmjs.org/package/postcss-merge-longhand) do:

```
npm install postcss-merge-longhand --save
```

## Example

Merge longhand properties into shorthand; works with `margin`, `padding` &
`border`. For more examples see the [tests](src/__tests__/index.js).

### Input

```css
h1 {
    margin-top: 10px;
    margin-right: 20px;
    margin-bottom: 10px;
    margin-left: 20px;
}
```

### Output

```css
h1 {
    margin: 10px 20px;
}
```

## Usage

See the [PostCSS documentation](https://github.com/postcss/postcss#usage) for
examples for your environment.

## Contributors

See [CONTRIBUTORS.md](https://github.com/cssnano/cssnano/blob/master/CONTRIBUTORS.md).

## License

MIT © [Ben Briggs](http://beneb.info)

[postcss]: https://github.com/postcss/postcss


---

# [postcss][postcss]-merge-rules

> Merge CSS rules with PostCSS.

## Install

With [npm](https://npmjs.org/package/postcss-merge-rules) do:

```
npm install postcss-merge-rules --save
```

## Examples

This module will attempt to merge *adjacent* CSS rules:

### By declarations

#### Input

```css
a {
    color: blue;
    font-weight: bold
}

p {
    color: blue;
    font-weight: bold
}
```

#### Output

```css
a,p {
    color: blue;
    font-weight: bold
}
```

### By selectors

#### Input

```css
a {
    color: blue
}

a {
    font-weight: bold
}
```

#### Output

```css
a {
    color: blue;
    font-weight: bold
}
```

### By partial declarations

#### Input

```css
a {
    font-weight: bold
}

p {
    color: blue;
    font-weight: bold
}
```

#### Output

```css
a,p {
    font-weight: bold
}

p {
    color: blue
}
```

## Usage

See the [PostCSS documentation](https://github.com/postcss/postcss#usage) for
examples for your environment.

## Contributors

See [CONTRIBUTORS.md](https://github.com/cssnano/cssnano/blob/master/CONTRIBUTORS.md).

## License

MIT © [Ben Briggs](http://beneb.info)

[postcss]: https://github.com/postcss/postcss


---

# postcss-minify-font-values [![Build Status][ci-img]][ci]

> Minify font declarations with PostCSS.

This module will try to minimise the `font-family`, `font-weight` and `font` shorthand
properties; it can unquote font families where necessary, detect & remove
duplicates, and cut short a declaration after it finds a keyword. For more
examples, see the [tests](test).

```css
h1 {
  font:bold 2.2rem/.9 "Open Sans Condensed", sans-serif;
}

p {
  font-family: "Helvetica Neue", Arial, sans-serif, Helvetica;
  font-weight: normal;
}
```

```css
h1 {
  font:700 2.2rem/.9 Open Sans Condensed,sans-serif
}

p {
  font-family: Helvetica Neue,Arial,sans-serif;
  font-weight: 400;
}
```

## API

### minifyFontValues([options])

#### options

##### removeAfterKeyword

Type: `boolean`
Default: `false`

Pass `true` to remove font families after the module encounters a font keyword,
for example `sans-serif`.

##### removeDuplicates

Type: `boolean`
Default: `true`

Pass `false` to disable the module from removing duplicated font families.

##### removeQuotes

Type: `boolean` | `(prop: string) => '' | 'font' | 'font-family' | 'font-weight'`
Default: `true`

Pass `false` to disable the module from removing quotes from font families.
Note that oftentimes, this is a *safe optimisation* & is done safely. For more
details, see [Mathias Bynens' article][mathias].

Pass a function to determine whether a css variable is one of `font`, `font-family`, and `font-weight` to determine whether the variable needs to remove quotes.

## Usage

```js
postcss([ require('postcss-minify-font-values') ])
```

See [PostCSS] docs for examples for your environment.

## Contributors

See [CONTRIBUTORS.md](https://github.com/cssnano/cssnano/blob/master/CONTRIBUTORS.md).

# License

MIT © [Bogdan Chadkin](mailto:trysound@yandex.ru)

[mathias]: https://mathiasbynens.be/notes/unquoted-font-family
[PostCSS]: https://github.com/postcss/postcss
[ci-img]:  https://travis-ci.org/cssnano/postcss-minify-font-values.svg
[ci]:      https://travis-ci.org/cssnano/postcss-minify-font-values


---

# [postcss][postcss]-minify-gradients

> Minify gradient parameters with PostCSS.

## Install

With [npm](https://npmjs.org/package/postcss-minify-gradients) do:

```
npm install postcss-minify-gradients
```


## Example

Where possible, this module will minify gradient parameters. It can convert
linear gradient directional syntax to angles, remove the unnecessary `0%` and
`100%` start and end values, and minimise color stops that use the same length
values (the browser will adjust the value automatically).

### Input

```css
h1 {
    background: linear-gradient(to bottom, #ffe500 0%, #ffe500 50%, #121 50%, #121 100%)
}
```

### Output

```css
h1 {
    background: linear-gradient(180deg, #ffe500, #ffe500 50%, #121 0, #121)
}
```


## Usage

See the [PostCSS documentation](https://github.com/postcss/postcss#usage) for
examples for your environment.


## Contributors

See [CONTRIBUTORS.md](https://github.com/cssnano/cssnano/blob/master/CONTRIBUTORS.md).


## License

MIT © [Ben Briggs](http://beneb.info)

[postcss]: https://github.com/postcss/postcss


---

# postcss-minify-params [![Build Status][ci-img]][ci]

> Minify at-rule params with PostCSS.

```css
@media only screen   and ( min-width: 400px, min-height: 500px ) {
    h2{
        color:blue
    }
}
```

```css
@media only screen and (min-width:400px,min-height:500px) {
    h2{
        color:blue
    }
}
```

## Usage

```js
postcss([ require('postcss-minify-params') ])
```

See [PostCSS] docs for examples for your environment.

## Contributors

See [CONTRIBUTORS.md](https://github.com/cssnano/cssnano/blob/master/CONTRIBUTORS.md).

## License

MIT © [Bogdan Chadkin](mailto:trysound@yandex.ru)

[PostCSS]: https://github.com/postcss/postcss
[ci-img]:  https://travis-ci.org/cssnano/postcss-minify-params.svg
[ci]:      https://travis-ci.org/cssnano/postcss-minify-params


---

# [postcss][postcss]-minify-selectors

> Minify selectors with PostCSS.

## Install

With [npm](https://www.npmjs.com/package/postcss-minify-selectors) do:

```
npm install postcss-minify-selectors --save
```

## Example

### Input

```css
h1 + p, h2, h3, h2{color:blue}
```

### Output

```css
h1+p,h2,h3{color:blue}
```

For more examples see the [tests](test/index.js).

## Usage

See the [PostCSS documentation](https://github.com/postcss/postcss#usage) for
examples for your environment.

## Contributors

See [CONTRIBUTORS.md](https://github.com/cssnano/cssnano/blob/master/CONTRIBUTORS.md).

## License

MIT © [Ben Briggs](http://beneb.info)

[postcss]: https://github.com/postcss/postcss


---

# CSS Modules: Extract Imports

[![Build Status](https://travis-ci.org/css-modules/postcss-modules-extract-imports.svg?branch=master)](https://travis-ci.org/css-modules/postcss-modules-extract-imports)

Transforms:

```css
:local(.continueButton) {
  composes: button from "library/button.css";
  color: green;
}
```

into:

```css
:import("library/button.css") {
  button: __tmp_487387465fczSDGHSABb;
}
:local(.continueButton) {
  composes: __tmp_487387465fczSDGHSABb;
  color: green;
}
```

## Specification

- Only a certain whitelist of properties are inspected. Currently, that whitelist is `['composes']` alone.
- An extend-import has the following format:

```
composes: className [... className] from "path/to/file.css",  className [... className], className [... className] from global;
```

## Options

- `failOnWrongOrder` `bool` generates exception for unpredictable imports order.

```css
.aa {
  composes: b from "./b.css";
  composes: c from "./c.css";
}

.bb {
  /* "b.css" should be before "c.css" in this case */
  composes: c from "./c.css";
  composes: b from "./b.css";
}
```

## Building

```
npm install
npm test
```

[![Build Status](https://travis-ci.org/css-modules/postcss-modules-extract-imports.svg?branch=master)](https://travis-ci.org/css-modules/postcss-modules-extract-imports)

- Lines: [![Coverage Status](https://coveralls.io/repos/css-modules/postcss-modules-extract-imports/badge.svg?branch=master)](https://coveralls.io/r/css-modules/postcss-modules-extract-imports?branch=master)
- Statements: [![codecov.io](http://codecov.io/github/css-modules/postcss-modules-extract-imports/coverage.svg?branch=master)](http://codecov.io/github/css-modules/postcss-modules-extract-imports?branch=master)

## License

ISC

## With thanks

- Mark Dalgleish
- Tobias Koppers
- Guy Bedford

---

Glen Maddern, 2015.


---

[![Build Status][ci-img]][ci] [![codecov][codecov-img]][codecov] [![npm][npm-img]][npm]

# CSS Modules: Local by Default

Transformation examples:

Selectors (mode `local`, by default)::

<!-- prettier-ignore-start -->
```css
.foo { ... } /* => */ :local(.foo) { ... }

.foo .bar { ... } /* => */ :local(.foo) :local(.bar) { ... }

/* Shorthand global selector */

:global .foo .bar { ... } /* => */ .foo .bar { ... }

.foo :global .bar { ... } /* => */ :local(.foo) .bar { ... }

/* Targeted global selector */

:global(.foo) .bar { ... } /* => */ .foo :local(.bar) { ... }

.foo:global(.bar) { ... } /* => */ :local(.foo).bar { ... }

.foo :global(.bar) .baz { ... } /* => */ :local(.foo) .bar :local(.baz) { ... }

.foo:global(.bar) .baz { ... } /* => */ :local(.foo).bar :local(.baz) { ... }
```
<!-- prettier-ignore-end -->

Declarations (mode `local`, by default):

<!-- prettier-ignore-start -->
```css
.foo {
  animation-name: fadeInOut, global(moveLeft300px), local(bounce);
}

.bar {
  animation: rotate 1s, global(spin) 3s, local(fly) 6s;
}

/* => */ 

:local(.foo) {
  animation-name: :local(fadeInOut), moveLeft300px, :local(bounce);
}

:local(.bar) {
  animation: :local(rotate) 1s, spin 3s, :local(fly) 6s;
}
```
<!-- prettier-ignore-end -->

## Pure Mode

In pure mode, all selectors must contain at least one local class or id
selector

To ignore this rule for a specific selector, add the a `/* cssmodules-pure-ignore */` comment in front
of the selector:

```css
/* cssmodules-pure-ignore */
:global(#modal-backdrop) {
  ...;
}
```

or by adding a `/* cssmodules-pure-no-check */` comment at the top of a file to disable this check for the whole file:

```css
/* cssmodules-pure-no-check */

:global(#modal-backdrop) {
  ...;
}

:global(#my-id) {
  ...;
}
```

## Building

```bash
$ npm install
$ npm test
```

- Build: [![Build Status][ci-img]][ci]
- Lines: [![coveralls][coveralls-img]][coveralls]
- Statements: [![codecov][codecov-img]][codecov]

## Development

```bash
$ yarn test:watch
```

## License

MIT

## With thanks

- [Tobias Koppers](https://github.com/sokra)
- [Glen Maddern](https://github.com/geelen)

---

Mark Dalgleish, 2015.

[ci-img]: https://github.com/css-modules/postcss-modules-local-by-default/actions/workflows/nodejs.yml/badge.svg
[ci]: https://github.com/css-modules/postcss-modules-local-by-default/actions/workflows/nodejs.yml
[npm-img]: https://img.shields.io/npm/v/postcss-modules-local-by-default.svg?style=flat-square
[npm]: https://www.npmjs.com/package/postcss-modules-local-by-default
[coveralls-img]: https://img.shields.io/coveralls/css-modules/postcss-modules-local-by-default/master.svg?style=flat-square
[coveralls]: https://coveralls.io/r/css-modules/postcss-modules-local-by-default?branch=master
[codecov-img]: https://img.shields.io/codecov/c/github/css-modules/postcss-modules-local-by-default/master.svg?style=flat-square
[codecov]: https://codecov.io/github/css-modules/postcss-modules-local-by-default?branch=master


---

# API Documentation

*Please use only this documented API when working with the parser. Methods
not documented here are subject to change at any point.*

## `parser` function

This is the module's main entry point.

```js
const parser = require('postcss-selector-parser');
```

### `parser([transform], [options])`

Creates a new `processor` instance

```js
const processor = parser();
```

Or, with optional transform function

```js
const transform = selectors => {
    selectors.walkUniversals(selector => {
        selector.remove();
    });
};

const processor = parser(transform)

// Example
const result = processor.processSync('*.class');
// => .class
```

[See processor documentation](#processor)

Arguments:

* `transform (function)`: Provide a function to work with the parsed AST.
* `options (object)`: Provide default options for all calls on the returned `Processor`.

### `parser.attribute([props])`

Creates a new attribute selector.

```js
parser.attribute({attribute: 'href'});
// => [href]
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.className([props])`

Creates a new class selector.

```js
parser.className({value: 'button'});
// => .button
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.combinator([props])`

Creates a new selector combinator.

```js
parser.combinator({value: '+'});
// => +
```

Arguments:

* `props (object)`: The new node's properties.

Notes:
* **Descendant Combinators** The value of descendant combinators created by the
  parser always just a single space (`" "`). For descendant selectors with no
  comments, additional space is now stored in `node.spaces.before`. Depending
  on the location of comments, additional spaces may be stored in
  `node.raws.spaces.before`, `node.raws.spaces.after`, or `node.raws.value`.
* **Named Combinators** Although, nonstandard and unlikely to ever become a standard,
  named combinators like `/deep/` and `/for/` are parsed as combinators. The
  `node.value` is name after being unescaped and normalized as lowercase. The
  original value for the combinator name is stored in `node.raws.value`.


### `parser.comment([props])`

Creates a new comment.

```js
parser.comment({value: '/* Affirmative, Dave. I read you. */'});
// => /* Affirmative, Dave. I read you. */
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.id([props])`

Creates a new id selector.

```js
parser.id({value: 'search'});
// => #search
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.nesting([props])`

Creates a new nesting selector.

```js
parser.nesting();
// => &
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.pseudo([props])`

Creates a new pseudo selector.

```js
parser.pseudo({value: '::before'});
// => ::before
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.root([props])`

Creates a new root node.

```js
parser.root();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.selector([props])`

Creates a new selector node.

```js
parser.selector();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.string([props])`

Creates a new string node.

```js
parser.string();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.tag([props])`

Creates a new tag selector.

```js
parser.tag({value: 'button'});
// => button
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.universal([props])`

Creates a new universal selector.

```js
parser.universal();
// => *
```

Arguments:

* `props (object)`: The new node's properties.

## Node types

### `node.type`

A string representation of the selector type. It can be one of the following;
`attribute`, `class`, `combinator`, `comment`, `id`, `nesting`, `pseudo`,
`root`, `selector`, `string`, `tag`, or `universal`. Note that for convenience,
these constants are exposed on the main `parser` as uppercased keys. So for
example you can get `id` by querying `parser.ID`.

```js
parser.attribute({attribute: 'href'}).type;
// => 'attribute'
```

### `node.parent`

Returns the parent node.

```js
root.nodes[0].parent === root;
```

### `node.toString()`, `String(node)`, or `'' + node`

Returns a string representation of the node.

```js
const id = parser.id({value: 'search'});
console.log(String(id));
// => #search
```

### `node.next()` & `node.prev()`

Returns the next/previous child of the parent node.

```js
const next = id.next();
if (next && next.type !== 'combinator') {
    throw new Error('Qualified IDs are not allowed!');
}
```

### `node.replaceWith(node[,...nodeN])`

Replace a node with another.

```js
const attr = selectors.first.first;
const className = parser.className({value: 'test'});
attr.replaceWith(className);
```

Arguments:

* `node`: The node to substitute the original with.
...
* `nodeN`: The node to substitute the original with.

### `node.remove()`

Removes the node from its parent node.

```js
if (node.type === 'id') {
    node.remove();
}
```

### `node.clone([opts])`

Returns a copy of a node, detached from any parent containers that the
original might have had.

```js
const cloned = node.clone();
```

### `node.isAtPosition(line, column)`

Return a `boolean` indicating whether this node includes the character at the
position of the given line and column. Returns `undefined` if the nodes lack
sufficient source metadata to determine the position.

Arguments:

* `line`: 1-index based line number relative to the start of the selector.
* `column`: 1-index based column number relative to the start of the selector.

### `node.spaces`

Extra whitespaces around the node will be moved into `node.spaces.before` and
`node.spaces.after`. So for example, these spaces will be moved as they have
no semantic meaning:

```css
      h1     ,     h2   {}
```

For descendent selectors, the value is always a single space.

```css
h1        h2 {}
```

Additional whitespace is found in either the `node.spaces.before` and `node.spaces.after` depending on the presence of comments or other whitespace characters. If the actual whitespace does not start or end with a single space, the node's raw value is set to the actual space(s) found in the source.

### `node.source`

An object describing the node's start/end, line/column source position.

Within the following CSS, the `.bar` class node ...

```css
.foo,
  .bar {}
```

... will contain the following `source` object.

```js
source: {
    start: {
        line: 2,
        column: 3
    },
    end: {
        line: 2,
        column: 6
    }
}
```

### `node.sourceIndex`

The zero-based index of the node within the original source string.

Within the following CSS, the `.baz` class node will have a `sourceIndex` of `12`.

```css
.foo, .bar, .baz {}
```

## Container types

The `root`, `selector`, and `pseudo` nodes have some helper methods for working
with their children.

### `container.nodes`

An array of the container's children.

```js
// Input: h1 h2
selectors.at(0).nodes.length   // => 3
selectors.at(0).nodes[0].value // => 'h1'
selectors.at(0).nodes[1].value // => ' '
```

### `container.first` & `container.last`

The first/last child of the container.

```js
selector.first === selector.nodes[0];
selector.last === selector.nodes[selector.nodes.length - 1];
```

### `container.at(index)`

Returns the node at position `index`.

```js
selector.at(0) === selector.first;
selector.at(0) === selector.nodes[0];
```

Arguments:

* `index`: The index of the node to return.

### `container.atPosition(line, column)`

Returns the node at the source position `line` and `column`.

```js
// Input: :not(.foo),\n#foo > :matches(ol, ul)
selector.atPosition(1, 1); // => :not(.foo)
selector.atPosition(2, 1); // => \n#foo
```

Arguments:

* `line`: The line number of the node to return.
* `column`: The column number of the node to return.

### `container.index(node)`

Return the index of the node within its container.

```js
selector.index(selector.nodes[2]) // => 2
```

Arguments:

* `node`: A node within the current container.

### `container.length`

Proxy to the length of the container's nodes.

```js
container.length === container.nodes.length
```

### `container` Array iterators

The container class provides proxies to certain Array methods; these are:

* `container.map === container.nodes.map`
* `container.reduce === container.nodes.reduce`
* `container.every === container.nodes.every`
* `container.some === container.nodes.some`
* `container.filter === container.nodes.filter`
* `container.sort === container.nodes.sort`

Note that these methods only work on a container's immediate children; recursive
iteration is provided by `container.walk`.

### `container.each(callback)`

Iterate the container's immediate children, calling `callback` for each child.
You may return `false` within the callback to break the iteration.

```js
let className;
selectors.each((selector, index) => {
    if (selector.type === 'class') {
        className = selector.value;
        return false;
    }
});
```

Note that unlike `Array#forEach()`, this iterator is safe to use whilst adding
or removing nodes from the container.

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  and `index` arguments.

### `container.walk(callback)`

Like `container#each`, but will also iterate child nodes as long as they are
`container` types.

```js
selectors.walk((selector, index) => {
    // all nodes
});
```

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  and `index` arguments.

This iterator is safe to use whilst mutating `container.nodes`,
like `container#each`.

### `container.walk` proxies

The container class provides proxy methods for iterating over types of nodes,
so that it is easier to write modules that target specific selectors. Those
methods are:

* `container.walkAttributes`
* `container.walkClasses`
* `container.walkCombinators`
* `container.walkComments`
* `container.walkIds`
* `container.walkNesting`
* `container.walkPseudos`
* `container.walkTags`
* `container.walkUniversals`

### `container.split(callback)`

This method allows you to split a group of nodes by returning `true` from
a callback. It returns an array of arrays, where each inner array corresponds
to the groups that you created via the callback.

```js
// (input) => h1 h2>>h3
const list = selectors.first.split(selector => {
    return selector.type === 'combinator';
});

// (node values) => [['h1', ' '], ['h2', '>>'], ['h3']]
```

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  as an argument.

### `container.prepend(node)` & `container.append(node)`

Add a node to the start/end of the container. Note that doing so will set
the parent property of the node to this container.

```js
const id = parser.id({value: 'search'});
selector.append(id);
```

Arguments:

* `node`: The node to add.

### `container.insertBefore(old, new[, ...newNodes])` & `container.insertAfter(old, new[, ...newNodes])`

Add a node before or after an existing node in a container:

```js
selectors.walk(selector => {
    if (selector.type !== 'class') {
        const className = parser.className({value: 'theme-name'});
        selector.parent.insertAfter(selector, className);
    }
});
```

Arguments:

* `old`: The existing node in the container.
* `new`: The new node to add before/after the existing node.

### `container.removeChild(node)`

Remove the node from the container. Note that you can also use
`node.remove()` if you would like to remove just a single node.

```js
selector.length // => 2
selector.remove(id)
selector.length // => 1;
id.parent       // undefined
```

Arguments:

* `node`: The node to remove.

### `container.removeAll()` or `container.empty()`

Remove all children from the container.

```js
selector.removeAll();
selector.length // => 0
```

## Root nodes

A root node represents a comma separated list of selectors. Indeed, all
a root's `toString()` method does is join its selector children with a ','.
Other than this, it has no special functionality and acts like a container.

### `root.trailingComma`

This will be set to `true` if the input has a trailing comma, in order to
support parsing of legacy CSS hacks.

## Selector nodes

A selector node represents a single complex selector. For example, this
selector string `h1 h2 h3, [href] > p`, is represented as two selector nodes.
It has no special functionality of its own.

## Pseudo nodes

A pseudo selector extends a container node; if it has any parameters of its
own (such as `h1:not(h2, h3)`), they will be its children. Note that the pseudo
`value` will always contain the colons preceding the pseudo identifier. This
is so that both `:before` and `::before` are properly represented in the AST.

## Attribute nodes

### `attribute.quoted`

Returns `true` if the attribute's value is wrapped in quotation marks, false if it is not.
Remains `undefined` if there is no attribute value.

```css
[href=foo] /* false */
[href='foo'] /* true */
[href="foo"] /* true */
[href] /* undefined */
```

### `attribute.qualifiedAttribute`

Returns the attribute name qualified with the namespace if one is given.

### `attribute.offsetOf(part)`

 Returns the offset of the attribute part specified relative to the
 start of the node of the output string. This is useful in raising
 error messages about a specific part of the attribute, especially
 in combination with `attribute.sourceIndex`.

 Returns `-1` if the name is invalid or the value doesn't exist in this
 attribute.

 The legal values for `part` are:

 * `"ns"` - alias for "namespace"
 * `"namespace"` - the namespace if it exists.
 * `"attribute"` - the attribute name
 * `"attributeNS"` - the start of the attribute or its namespace
 * `"operator"` - the match operator of the attribute
 * `"value"` - The value (string or identifier)
 * `"insensitive"` - the case insensitivity flag

### `attribute.raws.unquoted`

Returns the unquoted content of the attribute's value.
Remains `undefined` if there is no attribute value.

```css
[href=foo] /* foo */
[href='foo'] /* foo */
[href="foo"] /* foo */
[href] /* undefined */
```

### `attribute.spaces`

Like `node.spaces` with the `before` and `after` values containing the spaces
around the element, the parts of the attribute can also have spaces before
and after them. The for each of `attribute`, `operator`, `value` and
`insensitive` there is corresponding property of the same nam in
`node.spaces` that has an optional `before` or `after` string containing only
whitespace.

Note that corresponding values in `attributes.raws.spaces` contain values
including any comments. If set, these values will override the
`attribute.spaces` value. Take care to remove them if changing
`attribute.spaces`.

### `attribute.raws`

The raws object stores comments and other information necessary to re-render
the node exactly as it was in the source.

If a comment is embedded within the identifiers for the `namespace`, `attribute`
or `value` then a property is placed in the raws for that value containing the full source of the propery including comments.

If a comment is embedded within the space between parts of the attribute
then the raw for that space is set accordingly.

Setting an attribute's property `raws` value to be deleted.

For now, changing the spaces required also updating or removing any of the
raws values that override them.

Example: `[ /*before*/ href /* after-attr */ = /* after-operator */ te/*inside-value*/st/* wow */ /*omg*/i/*bbq*/ /*whodoesthis*/]` would parse as:

```js
{
  attribute: "href",
  operator: "=",
  value: "test",
  spaces: {
    before: '',
    after: '',
    attribute: { before: '  ', after: '  ' },
    operator: { after: '  ' },
    value: { after: ' ' },
    insensitive: { after: ' ' }
  },
  raws: {
    spaces: {
      attribute: { before: ' /*before*/ ', after: ' /* after-attr */ ' },
      operator: { after: ' /* after-operator */ ' },
      value: { after: '/* wow */ /*omg*/' },
      insensitive: { after: '/*bbq*/ /*whodoesthis*/' }
    },
    unquoted: 'test',
    value: 'te/*inside-value*/st'
  }
}
```

## `Processor`

### `ProcessorOptions`

* `lossless` - When `true`, whitespace is preserved. Defaults to `true`.
* `updateSelector` - When `true`, if any processor methods are passed a postcss
  `Rule` node instead of a string, then that Rule's selector is updated
  with the results of the processing. Defaults to `true`.

### `process|processSync(selectors, [options])`

Processes the `selectors`, returning a string from the result of processing.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

**Example:**

```js
const parser = require("postcss-selector-parser");
const processor = parser();

let result = processor.processSync(' .class');
console.log(result);
// =>  .class

// Asynchronous operation
let promise = processor.process(' .class').then(result => {
    console.log(result)
    // => .class
});

// To have the parser normalize whitespace values, utilize the options
result = processor.processSync('  .class  ', {lossless: false});
console.log(result);
// => .class

// For better syntax errors, pass a PostCSS Rule node.
const postcss = require('postcss');
rule = postcss.rule({selector: ' #foo    > a,  .class  '});
processor.process(rule, {lossless: false, updateSelector: true}).then(result => {
    console.log(result);
    // => #foo>a,.class
    console.log("rule:", rule.selector);
    // => rule: #foo>a,.class
})
```

Arguments:

* `selectors (string|postcss.Rule)`: Either a selector string or a PostCSS Rule
  node.
* `[options] (object)`: Process options


### `ast|astSync(selectors, [options])`

Like `process()` and `processSync()` but after
processing the `selectors` these methods return the `Root` node of the result
instead of a string.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

### `transform|transformSync(selectors, [options])`

Like `process()` and `processSync()` but after
processing the `selectors` these methods return the value returned by the
processor callback.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

### Error Handling Within Selector Processors

The root node passed to the selector processor callback
has a method `error(message, options)` that returns an
error object. This method should always be used to raise
errors relating to the syntax of selectors. The options
to this method are passed to postcss's error constructor
([documentation](http://postcss.org/api/#container-error)).

#### Async Error Example

```js
let processor = (root) => {
    return new Promise((resolve, reject) => {
        root.walkClasses((classNode) => {
            if (/^(.*)[-_]/.test(classNode.value)) {
                let msg = "classes may not have underscores or dashes in them";
                reject(root.error(msg, {
                    index: classNode.sourceIndex + RegExp.$1.length + 1,
                    word: classNode.value
                }));
            }
        });
        resolve();
    });
};

const postcss = require("postcss");
const parser = require("postcss-selector-parser");
const selectorProcessor = parser(processor);
const plugin = postcss.plugin('classValidator', (options) => {
    return (root) => {
        let promises = [];
        root.walkRules(rule => {
            promises.push(selectorProcessor.process(rule));
        });
        return Promise.all(promises);
    };
});
postcss(plugin()).process(`
.foo-bar {
  color: red;
}
`.trim(), {from: 'test.css'}).catch((e) => console.error(e.toString()));

// CssSyntaxError: classValidator: ./test.css:1:5: classes may not have underscores or dashes in them
//
// > 1 | .foo-bar {
//     |     ^
//   2 |   color: red;
//   3 | }
```

#### Synchronous Error Example

```js
let processor = (root) => {
    root.walkClasses((classNode) => {
        if (/.*[-_]/.test(classNode.value)) {
            let msg = "classes may not have underscores or dashes in them";
            throw root.error(msg, {
                index: classNode.sourceIndex,
                word: classNode.value
            });
        }
    });
};

const postcss = require("postcss");
const parser = require("postcss-selector-parser");
const selectorProcessor = parser(processor);
const plugin = postcss.plugin('classValidator', (options) => {
    return (root) => {
        root.walkRules(rule => {
            selectorProcessor.processSync(rule);
        });
    };
});
postcss(plugin()).process(`
.foo-bar {
  color: red;
}
`.trim(), {from: 'test.css'}).catch((e) => console.error(e.toString()));

// CssSyntaxError: classValidator: ./test.css:1:5: classes may not have underscores or dashes in them
//
// > 1 | .foo-bar {
//     |     ^
//   2 |   color: red;
//   3 | }
```


---

# 7.1.0

- feat: insert(Before|After) support multiple new node

# 7.0.0

- Feat: make insertions during iteration safe (major)

# 6.1.2

- Fixed: erroneous trailing combinators in pseudos

# 6.1.1

- Fixed: improve typings of constructor helpers (#292)

# 6.1.0

- Feature: add `sourceIndex` to `Selector` nodes (#290)

# 6.0.16

- Fixed: add missing `index` argument to `each`/`walk` callback types (#289)

# 6.0.15

- Fixed: Node#prev and Node#next type for the first/last node

# 6.0.14

- Fixed: type definitions

# 6.0.13

- Fixed: throw on unexpected pipe symbols

# 6.0.12

- Fixed: `clone` arguments should be optional

# 6.0.11

- Fixed: parse attribute case insensitivity flag

# 6.0.10

- Fixed: `isPseudoElement()` supports `:first-letter` and `:first-line`

# 6.0.9

- Fixed: `Combinator.raws` property type

# 6.0.8

- Fixed: reduced size

# 6.0.7

- Fixed: parse animation percents

# 6.0.6

- Fixed: parse quoted attributes containing a newline correctly

# 6.0.5

- Perf: rework unesc for a 63+% performance boost

# 6.0.4

- Fixed: ts errors

# 6.0.3

- Fixed: replace node built-in "util" module with "util-deprecate"
- Fixed: handle uppercase pseudo elements
- Fixed: do not create invalid combinator before comment

# 6.0.2

- Fixed an issue with parsing and stringifying an empty attribute value

# 6.0.1

- Fixed an issue with unicode surrogate pair parsing

# 6.0.0

- Updated: `cssesc` to 3.0.0 (major)
- Fixed: Issues with escaped `id` and `class` selectors

# 5.0.0

- Allow escaped dot within class name.
- Update PostCSS to 7.0.7 (patch)

# 5.0.0-rc.4

- Fixed an issue where comments immediately after an insensitive (in attribute)
  were not parsed correctly.
- Updated `cssesc` to 2.0.0 (major).
- Removed outdated integration tests.
- Added tests for custom selectors, tags with attributes, the universal
  selector with pseudos, and tokens after combinators.

# 5.0.0-rc.1

To ease adoption of the v5.0 release, we have relaxed the node version
check performed by npm at installation time to allow for node 4, which
remains officially unsupported, but likely to continue working for the
time being.

# 5.0.0-rc.0

This release has **BREAKING CHANGES** that were required to fix regressions
in 4.0.0 and to make the Combinator Node API consistent for all combinator
types. Please read carefully.

## Summary of Changes

* The way a descendent combinator that isn't a single space character (E.g. `.a  .b`) is stored in the AST has changed.
* Named Combinators (E.g. `.a /for/ .b`) are now properly parsed as a combinator.
* It is now possible to look up a node based on the source location of a character in that node and to query nodes if they contain some character.
* Several bug fixes that caused the parser to hang and run out of memory when a `/` was encountered have been fixed.
* The minimum supported version of Node is now `v6.0.0`.

### Changes to the Descendent Combinator

In prior releases, the value of a descendant combinator with multiple spaces included all the spaces.

* `.a   .b`: Extra spaces are now stored as space before.
  - Old & Busted:
    - `combinator.value === "   "`
  - New hotness:
    - `combinator.value === " " && combinator.spaces.before === "  "`
* `.a   /*comment*/.b`: A comment at the end of the combinator causes extra space to become after space.
  - Old & Busted:
    - `combinator.value === "   "`
    - `combinator.raws.value === "   /*comment/"`
  - New hotness:
    - `combinator.value === " "`
    - `combinator.spaces.after === "  "`
    - `combinator.raws.spaces.after === "  /*comment*/"`
* `.a<newline>.b`: whitespace that doesn't start or end with a single space character is stored as a raw value.
  - Old & Busted:
    - `combinator.value === "\n"`
    - `combinator.raws.value === undefined`
  - New hotness:
    - `combinator.value === " "`
    - `combinator.raws.value === "\n"`

### Support for "Named Combinators"

Although, nonstandard and unlikely to ever become a standard, combinators like `/deep/` and `/for/` are now properly supported.

Because they've been taken off the standardization track, there is no spec-official name for combinators of the form `/<ident>/`. However, I talked to [Tab Atkins](https://twitter.com/tabatkins) and we agreed to call them "named combinators" so now they are called that.

Before this release such named combinators were parsed without intention and generated three nodes of type `"tag"` where the first and last nodes had a value of `"/"`.

* `.a /for/ .b` is parsed as a combinator.
  - Old & Busted:
    - `root.nodes[0].nodes[1].type === "tag"`
    - `root.nodes[0].nodes[1].value === "/"`
  - New hotness:
    - `root.nodes[0].nodes[1].type === "combinator"`
    - `root.nodes[0].nodes[1].value === "/for/"`
* `.a /F\6fR/ .b` escapes are handled and uppercase is normalized.
  - Old & Busted:
    - `root.nodes[0].nodes[2].type === "tag"`
    - `root.nodes[0].nodes[2].value === "F\\6fR"`
  - New hotness:
    - `root.nodes[0].nodes[1].type === "combinator"`
    - `root.nodes[0].nodes[1].value === "/for/"`
    - `root.nodes[0].nodes[1].raws.value === "/F\\6fR/"`

### Source position checks and lookups

A new API was added to look up a node based on the source location.

```js
const selectorParser = require("postcss-selector-parser");
// You can find the most specific node for any given character
let combinator = selectorParser.astSync(".a > .b").atPosition(1,4);
combinator.toString() === " > ";
// You can check if a node includes a specific character
// Whitespace surrounding the node that is owned by that node
// is included in the check.
[2,3,4,5,6].map(column => combinator.isAtPosition(1, column));
// => [false, true, true, true, false]
```

# 4.0.0

This release has **BREAKING CHANGES** that were required to fix bugs regarding values with escape sequences. Please read carefully.

* **Identifiers with escapes** - CSS escape sequences are now hidden from the public API by default.
  The normal value of a node like a class name or ID, or an aspect of a node such as attribute
  selector's value, is unescaped. Escapes representing Non-ascii characters are unescaped into
  unicode characters. For example: `bu\tton, .\31 00, #i\2764\FE0Fu, [attr="value is \"quoted\""]`
  will parse respectively to the values `button`, `100`, `i❤️u`, `value is "quoted"`.
  The original escape sequences for these values can be found in the corresponding property name
  in `node.raws`. Where possible, deprecation warnings were added, but the nature
  of escape handling makes it impossible to detect what is escaped or not. Our expectation is
  that most users are neither expecting nor handling escape sequences in their use of this library,
  and so for them, this is a bug fix. Users who are taking care to handle escapes correctly can
  now update their code to remove the escape handling and let us do it for them.

* **Mutating values with escapes** - When you make an update to a node property that has escape handling
  The value is assumed to be unescaped, and any special characters are escaped automatically and
  the corresponding `raws` value is immediately updated. This can result in changes to the original
  escape format. Where the exact value of the escape sequence is important there are methods that
  allow both values to be set in conjunction. There are a number of new convenience methods for
  manipulating values that involve escapes, especially for attributes values where the quote mark
  is involved. See https://github.com/postcss/postcss-selector-parser/pull/133 for an extensive
  write-up on these changes.


**Upgrade/API Example**

In `3.x` there was no unescape handling and internal consistency of several properties was the caller's job to maintain. It was very easy for the developer
to create a CSS file that did not parse correctly when some types of values
were in use.

```js
const selectorParser = require("postcss-selector-parser");
let attr = selectorParser.attribute({attribute: "id", operator: "=", value: "a-value"});
attr.value; // => "a-value"
attr.toString(); // => [id=a-value]
// Add quotes to an attribute's value.
// All these values have to be set by the caller to be consistent:
// no internal consistency is maintained.
attr.raws.unquoted = attr.value
attr.value = "'" + attr.value + "'";
attr.value; // => "'a-value'"
attr.quoted = true;
attr.toString();  // => "[id='a-value']"
```

In `4.0` there is a convenient API for setting and mutating values
that may need escaping. Especially for attributes.

```js
const selectorParser = require("postcss-selector-parser");

// The constructor requires you specify the exact escape sequence
let className = selectorParser.className({value: "illegal class name", raws: {value: "illegal\\ class\\ name"}});
className.toString(); // => '.illegal\\ class\\ name'

// So it's better to set the value as a property
className = selectorParser.className();
// Most properties that deal with identifiers work like this
className.value = "escape for me";
className.value; // => 'escape for me'
className.toString(); // => '.escape\\ for\\ me'

// emoji and all non-ascii are escaped to ensure it works in every css file.
className.value = "😱🦄😍";
className.value; // => '😱🦄😍'
className.toString(); // => '.\\1F631\\1F984\\1F60D'

// you can control the escape sequence if you want, or do bad bad things
className.setPropertyAndEscape('value', 'xxxx', 'yyyy');
className.value; // => "xxxx"
className.toString(); // => ".yyyy"

// Pass a value directly through to the css output without escaping it. 
className.setPropertyWithoutEscape('value', '$REPLACE_ME$');
className.value; // => "$REPLACE_ME$"
className.toString(); // => ".$REPLACE_ME$"

// The biggest changes are to the Attribute class
// passing quoteMark explicitly is required to avoid a deprecation warning.
let attr = selectorParser.attribute({attribute: "id", operator: "=", value: "a-value", quoteMark: null});
attr.toString(); // => "[id=a-value]"
// Get the value with quotes on it and any necessary escapes.
// This is the same as reading attr.value in 3.x.
attr.getQuotedValue(); // => "a-value";
attr.quoteMark; // => null

// Add quotes to an attribute's value.
attr.quoteMark = "'"; // This is all that's required.
attr.toString(); // => "[id='a-value']"
attr.quoted; // => true
// The value is still the same, only the quotes have changed.
attr.value; // => a-value
attr.getQuotedValue(); // => "'a-value'";

// deprecated assignment, no warning because there's no escapes
attr.value = "new-value";
// no quote mark is needed so it is removed
attr.getQuotedValue(); // => "new-value";

// deprecated assignment, 
attr.value = "\"a 'single quoted' value\"";
// > (node:27859) DeprecationWarning: Assigning an attribute a value containing characters that might need to be escaped is deprecated. Call attribute.setValue() instead.
attr.getQuotedValue(); // => '"a \'single quoted\' value"';
// quote mark inferred from first and last characters.
attr.quoteMark; // => '"'

// setValue takes options to make manipulating the value simple.
attr.setValue('foo', {smart: true});
// foo doesn't require any escapes or quotes.
attr.toString(); // => '[id=foo]'
attr.quoteMark; // => null 

// An explicit quote mark can be specified
attr.setValue('foo', {quoteMark: '"'});
attr.toString(); // => '[id="foo"]'

// preserves quote mark by default
attr.setValue('bar');
attr.toString(); // => '[id="bar"]'
attr.quoteMark = null;
attr.toString(); // => '[id=bar]'

// with no arguments, it preserves quote mark even when it's not a great idea
attr.setValue('a value \n that should be quoted');
attr.toString(); // => '[id=a\\ value\\ \\A\\ that\\ should\\ be\\ quoted]'

// smart preservation with a specified default
attr.setValue('a value \n that should be quoted', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => "[id='a value \\A  that should be quoted']"
attr.quoteMark = '"';
// => '[id="a value \\A  that should be quoted"]'

// this keeps double quotes because it wants to quote the value and the existing value has double quotes.
attr.setValue('this should be quoted', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => '[id="this should be quoted"]'

// picks single quotes because the value has double quotes
attr.setValue('a "double quoted" value', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => "[id='a "double quoted" value']"

// setPropertyAndEscape lets you do anything you want. Even things that are a bad idea and illegal.
attr.setPropertyAndEscape('value', 'xxxx', 'the password is 42');
attr.value; // => "xxxx"
attr.toString(); // => "[id=the password is 42]"

// Pass a value directly through to the css output without escaping it. 
attr.setPropertyWithoutEscape('value', '$REPLACEMENT$');
attr.value; // => "$REPLACEMENT$"
attr.toString(); // => "[id=$REPLACEMENT$]"
```

# 3.1.2

* Fix: Removed dot-prop dependency since it's no longer written in es5.

# 3.1.1

* Fix: typescript definitions weren't in the published package.

# 3.1.0

* Fixed numerous bugs in attribute nodes relating to the handling of comments
  and whitespace. There's significant changes to `attrNode.spaces` and `attrNode.raws` since the `3.0.0` release.
* Added `Attribute#offsetOf(part)` to get the offset location of
  attribute parts like `"operator"` and `"value"`. This is most
  often added to `Attribute#sourceIndex` for error reporting.

# 3.0.0

## Breaking changes

* Some tweaks to the tokenizer/attribute selector parsing mean that whitespace
  locations might be slightly different to the 2.x code.
* Better attribute selector parsing with more validation; postcss-selector-parser
  no longer uses regular expressions to parse attribute selectors.
* Added an async API (thanks to @jacobp100); the default `process` API is now
  async, and the sync API is now accessed through `processSync` instead.
* `process()` and `processSync()` now return a string instead of the Processor
  instance.
* Tweaks handling of Less interpolation (thanks to @jwilsson).
* Removes support for Node 0.12.

## Other changes

* `ast()` and `astSync()` methods have been added to the `Processor`. These
  return the `Root` node of the selectors after processing them.
* `transform()` and `transformSync()` methods have been added to the
  `Processor`. These return the value returned by the processor callback
  after processing the selectors.
* Set the parent when inserting a node (thanks to @chriseppstein).
* Correctly adjust indices when using insertBefore/insertAfter (thanks to @tivac).
* Fixes handling of namespaces with qualified tag selectors.
* `process`, `ast` and `transform` (and their sync variants) now accept a
  `postcss` rule node. When provided, better errors are generated and selector
  processing is automatically set back to the rule selector (unless the `updateSelector` option is set to `false`.)
* Now more memory efficient when tokenizing selectors.

### Upgrade hints

The pattern of:

`rule.selector = processor.process(rule.selector).result.toString();`

is now:

`processor.processSync(rule)`

# 2.2.3

* Resolves an issue where the parser would not reduce multiple spaces between an
  ampersand and another simple selector in lossy mode (thanks to @adam-26).

# 2.2.2

* No longer hangs on an unescaped semicolon; instead the parser will throw
  an exception for these cases.

# 2.2.1

* Allows a consumer to specify whitespace tokens when creating a new Node
  (thanks to @Semigradsky).

# 2.2.0

* Added a new option to normalize whitespace when parsing the selector string
  (thanks to @adam-26).

# 2.1.1

* Better unquoted value handling within attribute selectors
  (thanks to @evilebottnawi).

# 2.1.0

* Added: Use string constants for all node types & expose them on the main
  parser instance (thanks to @Aweary).

# 2.0.0

This release contains the following breaking changes:

* Renamed all `eachInside` iterators to `walk`. For example, `eachTag` is now
  `walkTags`, and `eachInside` is now `walk`.
* Renamed `Node#removeSelf()` to `Node#remove()`.
* Renamed `Container#remove()` to `Container#removeChild()`.
* Renamed `Node#raw` to `Node#raws` (thanks to @davidtheclark).
* Now parses `&` as the *nesting* selector, rather than a *tag* selector.
* Fixes misinterpretation of Sass interpolation (e.g. `#{foo}`) as an
  id selector (thanks to @davidtheclark).

and;

* Fixes parsing of attribute selectors with equals signs in them
  (e.g. `[data-attr="foo=bar"]`) (thanks to @montmanu).
* Adds `quoted` and `raw.unquoted` properties to attribute nodes
  (thanks to @davidtheclark).

# 1.3.3

* Fixes an infinite loop on `)` and `]` tokens when they had no opening pairs.
  Now postcss-selector-parser will throw when it encounters these lone tokens.

# 1.3.2

* Now uses plain integers rather than `str.charCodeAt(0)` for compiled builds.

# 1.3.1

* Update flatten to v1.x (thanks to @shinnn).

# 1.3.0

* Adds a new node type, `String`, to fix a crash on selectors such as
  `foo:bar("test")`.

# 1.2.1

* Fixes a crash when the parser encountered a trailing combinator.

# 1.2.0

* A more descriptive error is thrown when the parser expects to find a
  pseudo-class/pseudo-element (thanks to @ashelley).
* Adds support for line/column locations for selector nodes, as well as a
  `Node#sourceIndex` method (thanks to @davidtheclark).

# 1.1.4

* Fixes a crash when a selector started with a `>` combinator. The module will
  now no longer throw if a selector has a leading/trailing combinator node.

# 1.1.3

* Fixes a crash on `@` tokens.

# 1.1.2

* Fixes an infinite loop caused by using parentheses in a non-pseudo element
  context.

# 1.1.1

* Fixes a crash when a backslash ended a selector string.

# 1.1.0

* Adds support for replacing multiple nodes at once with `replaceWith`
  (thanks to @jonathantneal).
* Parser no longer throws on sequential IDs and trailing commas, to support
  parsing of selector hacks.

# 1.0.1

* Fixes using `insertAfter` and `insertBefore` during iteration.

# 1.0.0

* Adds `clone` and `replaceWith` methods to nodes.
* Adds `insertBefore` and `insertAfter` to containers.
* Stabilises API.

# 0.0.5

* Fixes crash on extra whitespace inside a pseudo selector's parentheses.
* Adds sort function to the container class.
* Enables the parser to pass its input through without transforming.
* Iteration-safe `each` and `eachInside`.

# 0.0.4

* Tidy up redundant duplication.
* Fixes a bug where the parser would loop infinitely on universal selectors
  inside pseudo selectors.
* Adds `length` getter and `eachInside`, `map`, `reduce` to the container class.
* When a selector has been removed from the tree, the root node will no longer
  cast it to a string.
* Adds node type iterators to the container class (e.g. `eachComment`).
* Adds filter function to the container class.
* Adds split function to the container class.
* Create new node types by doing `parser.id(opts)` etc.
* Adds support for pseudo classes anywhere in the selector.

# 0.0.3

* Adds `next` and `prev` to the node class.
* Adds `first` and `last` getters to the container class.
* Adds `every` and `some` iterators to the container class.
* Add `empty` alias for `removeAll`.
* Combinators are now types of node.
* Fixes the at method so that it is not an alias for `index`.
* Tidy up creation of new nodes in the parser.
* Refactors how namespaces are handled for consistency & less redundant code.
* Refactors AST to use `nodes` exclusively, and eliminates excessive nesting.
* Fixes nested pseudo parsing.
* Fixes whitespace parsing.

# 0.0.2

* Adds support for namespace selectors.
* Adds support for selectors joined by escaped spaces - such as `.\31\ 0`.

# 0.0.1

* Initial release.


---

# postcss-selector-parser [![test](https://github.com/postcss/postcss-selector-parser/actions/workflows/test.yml/badge.svg)](https://github.com/postcss/postcss-selector-parser/actions/workflows/test.yml)

> Selector parser with built in methods for working with selector strings.

## Install

With [npm](https://npmjs.com/package/postcss-selector-parser) do:

```
npm install postcss-selector-parser
```

## Quick Start

```js
const parser = require('postcss-selector-parser');
const transform = selectors => {
    selectors.walk(selector => {
        // do something with the selector
        console.log(String(selector))
    });
};

const transformed = parser(transform).processSync('h1, h2, h3');
```

To normalize selector whitespace:

```js
const parser = require('postcss-selector-parser');
const normalized = parser().processSync('h1, h2, h3', {lossless: false});
// -> h1,h2,h3
```

Async support is provided through `parser.process` and will resolve a Promise
with the resulting selector string.

## API

Please see [API.md](API.md).

## Credits

* Huge thanks to Andrey Sitnik (@ai) for work on PostCSS which helped
  accelerate this module's development.

## License

MIT


---

# Change Log

All notable changes to this project will be documented in this file.
This project adheres to [Semantic Versioning](http://semver.org/).

## [3.2.1](https://github.com/postcss-modules-local-by-default/compare/v3.2.0...v3.2.1)

### Chore

- update `postcss-selector-parser`

## [3.2.0](https://github.com/postcss-modules-local-by-default/compare/v3.1.2...v3.2.0) - 2024-04-03

### Features

- supports multiple composes, i.e. `.class { composes: a b, global(c), d e from "./path/file.css" }`

## [3.1.2](https://github.com/postcss-modules-local-by-default/compare/v3.1.1...v3.1.2) - 2024-04-03

### Fixes

- export a root and limit from the `@scope` at-rule

## [3.1.1](https://github.com/postcss-modules-local-by-default/compare/v3.1.0...v3.1.1) - 2024-01-18

### Fixes

- handle `@scope` at-rule
- fix CSS nesting logic

## [3.1.0](https://github.com/postcss-modules-local-by-default/compare/v3.0.0...v3.1.0) - 2023-12-21

### Fixes

- scoped class attribute

### Features

- pass a node to the `generateExportEntry` option

## [3.0.0](https://github.com/postcss-modules-local-by-default/compare/v3.0.0-rc.2...v3.0.0) - 2020-10-13

### Fixes

- compatibility with plugins other plugins
- handle animation short name
- perf

## [3.0.0-rc.2](https://github.com/postcss-modules-local-by-default/compare/v3.0.0-rc.1...v3.0.0-rc.2) - 2020-10-11

### BREAKING CHANGE

- minimum supported `postcss` version is `^8.1.0`

### Fixes

- minimum supported `Node.js` version is `^10 || ^12 || >= 14`
- compatibility with PostCSS 8

## [3.0.0-rc.1](https://github.com/postcss-modules-local-by-default/compare/v3.0.0-rc.0...v3.0.0-rc.1) - 2020-09-22

### BREAKING CHANGE

- do not handle invalid syntax

## [3.0.0-rc.0](https://github.com/postcss-modules-local-by-default/compare/v2.2.0...v3.0.0-rc.0) - 2020-09-21

### BREAKING CHANGE

- minimum supported `Node.js` version is `>= 10.13.0 || >= 12.13.0 || >= 14`
- minimum supported `postcss` version is `^8.0.3`
- `postcss` was moved to `peerDependencies`, you need to install `postcss` in your project before use the plugin

## 2.2.0 - 2020-03-19

- added the `exportGlobals` option to export global classes and ids

## 2.1.1 - 2019-03-05

### Fixed

- add additional space after the escape sequence (#17)

## [2.1.0] - 2019-03-05

### Fixed

- handles properly selector with escaping characters (like: `.\31 a2b3c { color: red }`)

### Feature

- `generateExportEntry` option (allow to setup key and value for `:export {}` rule)


---

# CSS Modules: Scope Locals & Extend

[![Build Status](https://travis-ci.org/css-modules/postcss-modules-scope.svg?branch=master)](https://travis-ci.org/css-modules/postcss-modules-scope)

Transforms:

```css
:local(.continueButton) {
  color: green;
}
```

into:

```css
:export {
  continueButton: __buttons_continueButton_djd347adcxz9;
}
.__buttons_continueButton_djd347adcxz9 {
  color: green;
}
```

so it doesn't pollute CSS global scope and can be simply used in JS like so:

```js
import styles from "./buttons.css";
elem.innerHTML = `<button class="${styles.continueButton}">Continue</button>`;
```

## Composition

Since we're exporting class names, there's no reason to export only one. This can give us some really useful reuse of styles:

```css
.globalButtonStyle {
  background: white;
  border: 1px solid;
  border-radius: 0.25rem;
}
.globalButtonStyle:hover {
  box-shadow: 0 0 4px -2px;
}
:local(.continueButton) {
  compose-with: globalButtonStyle;
  color: green;
}
```

becomes:

```
.globalButtonStyle {
  background: white;
  border: 1px solid;
  border-radius: 0.25rem;
}
.globalButtonStyle:hover {
  box-shadow: 0 0 4px -2px;
}
:local(.continueButton) {
  compose-with: globalButtonStyle;
  color: green;
}
```

**Note:** you can also use `composes` as a shorthand for `compose-with`

## Local-by-default & reuse across files

You're looking for [CSS Modules](https://github.com/css-modules/css-modules). It uses this plugin as well as a few others, and it's amazing.

## Building

```
npm install
npm test
```

- Status: [![Build Status](https://travis-ci.org/css-modules/postcss-modules-scope.svg?branch=master)](https://travis-ci.org/css-modules/postcss-modules-scope)
- Lines: [![Coverage Status](https://coveralls.io/repos/css-modules/postcss-modules-scope/badge.svg?branch=master)](https://coveralls.io/r/css-modules/postcss-modules-scope?branch=master)
- Statements: [![codecov.io](http://codecov.io/github/css-modules/postcss-modules-scope/coverage.svg?branch=master)](http://codecov.io/github/css-modules/postcss-modules-scope?branch=master)

## Development

- `npm test:watch` will watch `src` and `test` for changes and run the tests

## License

ISC

## With thanks

- Mark Dalgleish
- Tobias Koppers
- Guy Bedford

---

Glen Maddern, 2015.


---

# API Documentation

*Please use only this documented API when working with the parser. Methods
not documented here are subject to change at any point.*

## `parser` function

This is the module's main entry point.

```js
const parser = require('postcss-selector-parser');
```

### `parser([transform], [options])`

Creates a new `processor` instance

```js
const processor = parser();
```

Or, with optional transform function

```js
const transform = selectors => {
    selectors.walkUniversals(selector => {
        selector.remove();
    });
};

const processor = parser(transform)

// Example
const result = processor.processSync('*.class');
// => .class
```

[See processor documentation](#processor)

Arguments:

* `transform (function)`: Provide a function to work with the parsed AST.
* `options (object)`: Provide default options for all calls on the returned `Processor`.

### `parser.attribute([props])`

Creates a new attribute selector.

```js
parser.attribute({attribute: 'href'});
// => [href]
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.className([props])`

Creates a new class selector.

```js
parser.className({value: 'button'});
// => .button
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.combinator([props])`

Creates a new selector combinator.

```js
parser.combinator({value: '+'});
// => +
```

Arguments:

* `props (object)`: The new node's properties.

Notes:
* **Descendant Combinators** The value of descendant combinators created by the
  parser always just a single space (`" "`). For descendant selectors with no
  comments, additional space is now stored in `node.spaces.before`. Depending
  on the location of comments, additional spaces may be stored in
  `node.raws.spaces.before`, `node.raws.spaces.after`, or `node.raws.value`.
* **Named Combinators** Although, nonstandard and unlikely to ever become a standard,
  named combinators like `/deep/` and `/for/` are parsed as combinators. The
  `node.value` is name after being unescaped and normalized as lowercase. The
  original value for the combinator name is stored in `node.raws.value`.


### `parser.comment([props])`

Creates a new comment.

```js
parser.comment({value: '/* Affirmative, Dave. I read you. */'});
// => /* Affirmative, Dave. I read you. */
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.id([props])`

Creates a new id selector.

```js
parser.id({value: 'search'});
// => #search
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.nesting([props])`

Creates a new nesting selector.

```js
parser.nesting();
// => &
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.pseudo([props])`

Creates a new pseudo selector.

```js
parser.pseudo({value: '::before'});
// => ::before
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.root([props])`

Creates a new root node.

```js
parser.root();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.selector([props])`

Creates a new selector node.

```js
parser.selector();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.string([props])`

Creates a new string node.

```js
parser.string();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.tag([props])`

Creates a new tag selector.

```js
parser.tag({value: 'button'});
// => button
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.universal([props])`

Creates a new universal selector.

```js
parser.universal();
// => *
```

Arguments:

* `props (object)`: The new node's properties.

## Node types

### `node.type`

A string representation of the selector type. It can be one of the following;
`attribute`, `class`, `combinator`, `comment`, `id`, `nesting`, `pseudo`,
`root`, `selector`, `string`, `tag`, or `universal`. Note that for convenience,
these constants are exposed on the main `parser` as uppercased keys. So for
example you can get `id` by querying `parser.ID`.

```js
parser.attribute({attribute: 'href'}).type;
// => 'attribute'
```

### `node.parent`

Returns the parent node.

```js
root.nodes[0].parent === root;
```

### `node.toString()`, `String(node)`, or `'' + node`

Returns a string representation of the node.

```js
const id = parser.id({value: 'search'});
console.log(String(id));
// => #search
```

### `node.next()` & `node.prev()`

Returns the next/previous child of the parent node.

```js
const next = id.next();
if (next && next.type !== 'combinator') {
    throw new Error('Qualified IDs are not allowed!');
}
```

### `node.replaceWith(node[,...nodeN])`

Replace a node with another.

```js
const attr = selectors.first.first;
const className = parser.className({value: 'test'});
attr.replaceWith(className);
```

Arguments:

* `node`: The node to substitute the original with.
...
* `nodeN`: The node to substitute the original with.

### `node.remove()`

Removes the node from its parent node.

```js
if (node.type === 'id') {
    node.remove();
}
```

### `node.clone([opts])`

Returns a copy of a node, detached from any parent containers that the
original might have had.

```js
const cloned = node.clone();
```

### `node.isAtPosition(line, column)`

Return a `boolean` indicating whether this node includes the character at the
position of the given line and column. Returns `undefined` if the nodes lack
sufficient source metadata to determine the position.

Arguments:

* `line`: 1-index based line number relative to the start of the selector.
* `column`: 1-index based column number relative to the start of the selector.

### `node.spaces`

Extra whitespaces around the node will be moved into `node.spaces.before` and
`node.spaces.after`. So for example, these spaces will be moved as they have
no semantic meaning:

```css
      h1     ,     h2   {}
```

For descendent selectors, the value is always a single space.

```css
h1        h2 {}
```

Additional whitespace is found in either the `node.spaces.before` and `node.spaces.after` depending on the presence of comments or other whitespace characters. If the actual whitespace does not start or end with a single space, the node's raw value is set to the actual space(s) found in the source.

### `node.source`

An object describing the node's start/end, line/column source position.

Within the following CSS, the `.bar` class node ...

```css
.foo,
  .bar {}
```

... will contain the following `source` object.

```js
source: {
    start: {
        line: 2,
        column: 3
    },
    end: {
        line: 2,
        column: 6
    }
}
```

### `node.sourceIndex`

The zero-based index of the node within the original source string.

Within the following CSS, the `.baz` class node will have a `sourceIndex` of `12`.

```css
.foo, .bar, .baz {}
```

## Container types

The `root`, `selector`, and `pseudo` nodes have some helper methods for working
with their children.

### `container.nodes`

An array of the container's children.

```js
// Input: h1 h2
selectors.at(0).nodes.length   // => 3
selectors.at(0).nodes[0].value // => 'h1'
selectors.at(0).nodes[1].value // => ' '
```

### `container.first` & `container.last`

The first/last child of the container.

```js
selector.first === selector.nodes[0];
selector.last === selector.nodes[selector.nodes.length - 1];
```

### `container.at(index)`

Returns the node at position `index`.

```js
selector.at(0) === selector.first;
selector.at(0) === selector.nodes[0];
```

Arguments:

* `index`: The index of the node to return.

### `container.atPosition(line, column)`

Returns the node at the source position `line` and `column`.

```js
// Input: :not(.foo),\n#foo > :matches(ol, ul)
selector.atPosition(1, 1); // => :not(.foo)
selector.atPosition(2, 1); // => \n#foo
```

Arguments:

* `line`: The line number of the node to return.
* `column`: The column number of the node to return.

### `container.index(node)`

Return the index of the node within its container.

```js
selector.index(selector.nodes[2]) // => 2
```

Arguments:

* `node`: A node within the current container.

### `container.length`

Proxy to the length of the container's nodes.

```js
container.length === container.nodes.length
```

### `container` Array iterators

The container class provides proxies to certain Array methods; these are:

* `container.map === container.nodes.map`
* `container.reduce === container.nodes.reduce`
* `container.every === container.nodes.every`
* `container.some === container.nodes.some`
* `container.filter === container.nodes.filter`
* `container.sort === container.nodes.sort`

Note that these methods only work on a container's immediate children; recursive
iteration is provided by `container.walk`.

### `container.each(callback)`

Iterate the container's immediate children, calling `callback` for each child.
You may return `false` within the callback to break the iteration.

```js
let className;
selectors.each((selector, index) => {
    if (selector.type === 'class') {
        className = selector.value;
        return false;
    }
});
```

Note that unlike `Array#forEach()`, this iterator is safe to use whilst adding
or removing nodes from the container.

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  and `index` arguments.

### `container.walk(callback)`

Like `container#each`, but will also iterate child nodes as long as they are
`container` types.

```js
selectors.walk((selector, index) => {
    // all nodes
});
```

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  and `index` arguments.

This iterator is safe to use whilst mutating `container.nodes`,
like `container#each`.

### `container.walk` proxies

The container class provides proxy methods for iterating over types of nodes,
so that it is easier to write modules that target specific selectors. Those
methods are:

* `container.walkAttributes`
* `container.walkClasses`
* `container.walkCombinators`
* `container.walkComments`
* `container.walkIds`
* `container.walkNesting`
* `container.walkPseudos`
* `container.walkTags`
* `container.walkUniversals`

### `container.split(callback)`

This method allows you to split a group of nodes by returning `true` from
a callback. It returns an array of arrays, where each inner array corresponds
to the groups that you created via the callback.

```js
// (input) => h1 h2>>h3
const list = selectors.first.split(selector => {
    return selector.type === 'combinator';
});

// (node values) => [['h1', ' '], ['h2', '>>'], ['h3']]
```

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  as an argument.

### `container.prepend(node)` & `container.append(node)`

Add a node to the start/end of the container. Note that doing so will set
the parent property of the node to this container.

```js
const id = parser.id({value: 'search'});
selector.append(id);
```

Arguments:

* `node`: The node to add.

### `container.insertBefore(old, new[, ...newNodes])` & `container.insertAfter(old, new[, ...newNodes])`

Add a node before or after an existing node in a container:

```js
selectors.walk(selector => {
    if (selector.type !== 'class') {
        const className = parser.className({value: 'theme-name'});
        selector.parent.insertAfter(selector, className);
    }
});
```

Arguments:

* `old`: The existing node in the container.
* `new`: The new node to add before/after the existing node.

### `container.removeChild(node)`

Remove the node from the container. Note that you can also use
`node.remove()` if you would like to remove just a single node.

```js
selector.length // => 2
selector.remove(id)
selector.length // => 1;
id.parent       // undefined
```

Arguments:

* `node`: The node to remove.

### `container.removeAll()` or `container.empty()`

Remove all children from the container.

```js
selector.removeAll();
selector.length // => 0
```

## Root nodes

A root node represents a comma separated list of selectors. Indeed, all
a root's `toString()` method does is join its selector children with a ','.
Other than this, it has no special functionality and acts like a container.

### `root.trailingComma`

This will be set to `true` if the input has a trailing comma, in order to
support parsing of legacy CSS hacks.

## Selector nodes

A selector node represents a single complex selector. For example, this
selector string `h1 h2 h3, [href] > p`, is represented as two selector nodes.
It has no special functionality of its own.

## Pseudo nodes

A pseudo selector extends a container node; if it has any parameters of its
own (such as `h1:not(h2, h3)`), they will be its children. Note that the pseudo
`value` will always contain the colons preceding the pseudo identifier. This
is so that both `:before` and `::before` are properly represented in the AST.

## Attribute nodes

### `attribute.quoted`

Returns `true` if the attribute's value is wrapped in quotation marks, false if it is not.
Remains `undefined` if there is no attribute value.

```css
[href=foo] /* false */
[href='foo'] /* true */
[href="foo"] /* true */
[href] /* undefined */
```

### `attribute.qualifiedAttribute`

Returns the attribute name qualified with the namespace if one is given.

### `attribute.offsetOf(part)`

 Returns the offset of the attribute part specified relative to the
 start of the node of the output string. This is useful in raising
 error messages about a specific part of the attribute, especially
 in combination with `attribute.sourceIndex`.

 Returns `-1` if the name is invalid or the value doesn't exist in this
 attribute.

 The legal values for `part` are:

 * `"ns"` - alias for "namespace"
 * `"namespace"` - the namespace if it exists.
 * `"attribute"` - the attribute name
 * `"attributeNS"` - the start of the attribute or its namespace
 * `"operator"` - the match operator of the attribute
 * `"value"` - The value (string or identifier)
 * `"insensitive"` - the case insensitivity flag

### `attribute.raws.unquoted`

Returns the unquoted content of the attribute's value.
Remains `undefined` if there is no attribute value.

```css
[href=foo] /* foo */
[href='foo'] /* foo */
[href="foo"] /* foo */
[href] /* undefined */
```

### `attribute.spaces`

Like `node.spaces` with the `before` and `after` values containing the spaces
around the element, the parts of the attribute can also have spaces before
and after them. The for each of `attribute`, `operator`, `value` and
`insensitive` there is corresponding property of the same nam in
`node.spaces` that has an optional `before` or `after` string containing only
whitespace.

Note that corresponding values in `attributes.raws.spaces` contain values
including any comments. If set, these values will override the
`attribute.spaces` value. Take care to remove them if changing
`attribute.spaces`.

### `attribute.raws`

The raws object stores comments and other information necessary to re-render
the node exactly as it was in the source.

If a comment is embedded within the identifiers for the `namespace`, `attribute`
or `value` then a property is placed in the raws for that value containing the full source of the propery including comments.

If a comment is embedded within the space between parts of the attribute
then the raw for that space is set accordingly.

Setting an attribute's property `raws` value to be deleted.

For now, changing the spaces required also updating or removing any of the
raws values that override them.

Example: `[ /*before*/ href /* after-attr */ = /* after-operator */ te/*inside-value*/st/* wow */ /*omg*/i/*bbq*/ /*whodoesthis*/]` would parse as:

```js
{
  attribute: "href",
  operator: "=",
  value: "test",
  spaces: {
    before: '',
    after: '',
    attribute: { before: '  ', after: '  ' },
    operator: { after: '  ' },
    value: { after: ' ' },
    insensitive: { after: ' ' }
  },
  raws: {
    spaces: {
      attribute: { before: ' /*before*/ ', after: ' /* after-attr */ ' },
      operator: { after: ' /* after-operator */ ' },
      value: { after: '/* wow */ /*omg*/' },
      insensitive: { after: '/*bbq*/ /*whodoesthis*/' }
    },
    unquoted: 'test',
    value: 'te/*inside-value*/st'
  }
}
```

## `Processor`

### `ProcessorOptions`

* `lossless` - When `true`, whitespace is preserved. Defaults to `true`.
* `updateSelector` - When `true`, if any processor methods are passed a postcss
  `Rule` node instead of a string, then that Rule's selector is updated
  with the results of the processing. Defaults to `true`.

### `process|processSync(selectors, [options])`

Processes the `selectors`, returning a string from the result of processing.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

**Example:**

```js
const parser = require("postcss-selector-parser");
const processor = parser();

let result = processor.processSync(' .class');
console.log(result);
// =>  .class

// Asynchronous operation
let promise = processor.process(' .class').then(result => {
    console.log(result)
    // => .class
});

// To have the parser normalize whitespace values, utilize the options
result = processor.processSync('  .class  ', {lossless: false});
console.log(result);
// => .class

// For better syntax errors, pass a PostCSS Rule node.
const postcss = require('postcss');
rule = postcss.rule({selector: ' #foo    > a,  .class  '});
processor.process(rule, {lossless: false, updateSelector: true}).then(result => {
    console.log(result);
    // => #foo>a,.class
    console.log("rule:", rule.selector);
    // => rule: #foo>a,.class
})
```

Arguments:

* `selectors (string|postcss.Rule)`: Either a selector string or a PostCSS Rule
  node.
* `[options] (object)`: Process options


### `ast|astSync(selectors, [options])`

Like `process()` and `processSync()` but after
processing the `selectors` these methods return the `Root` node of the result
instead of a string.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

### `transform|transformSync(selectors, [options])`

Like `process()` and `processSync()` but after
processing the `selectors` these methods return the value returned by the
processor callback.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

### Error Handling Within Selector Processors

The root node passed to the selector processor callback
has a method `error(message, options)` that returns an
error object. This method should always be used to raise
errors relating to the syntax of selectors. The options
to this method are passed to postcss's error constructor
([documentation](http://postcss.org/api/#container-error)).

#### Async Error Example

```js
let processor = (root) => {
    return new Promise((resolve, reject) => {
        root.walkClasses((classNode) => {
            if (/^(.*)[-_]/.test(classNode.value)) {
                let msg = "classes may not have underscores or dashes in them";
                reject(root.error(msg, {
                    index: classNode.sourceIndex + RegExp.$1.length + 1,
                    word: classNode.value
                }));
            }
        });
        resolve();
    });
};

const postcss = require("postcss");
const parser = require("postcss-selector-parser");
const selectorProcessor = parser(processor);
const plugin = postcss.plugin('classValidator', (options) => {
    return (root) => {
        let promises = [];
        root.walkRules(rule => {
            promises.push(selectorProcessor.process(rule));
        });
        return Promise.all(promises);
    };
});
postcss(plugin()).process(`
.foo-bar {
  color: red;
}
`.trim(), {from: 'test.css'}).catch((e) => console.error(e.toString()));

// CssSyntaxError: classValidator: ./test.css:1:5: classes may not have underscores or dashes in them
//
// > 1 | .foo-bar {
//     |     ^
//   2 |   color: red;
//   3 | }
```

#### Synchronous Error Example

```js
let processor = (root) => {
    root.walkClasses((classNode) => {
        if (/.*[-_]/.test(classNode.value)) {
            let msg = "classes may not have underscores or dashes in them";
            throw root.error(msg, {
                index: classNode.sourceIndex,
                word: classNode.value
            });
        }
    });
};

const postcss = require("postcss");
const parser = require("postcss-selector-parser");
const selectorProcessor = parser(processor);
const plugin = postcss.plugin('classValidator', (options) => {
    return (root) => {
        root.walkRules(rule => {
            selectorProcessor.processSync(rule);
        });
    };
});
postcss(plugin()).process(`
.foo-bar {
  color: red;
}
`.trim(), {from: 'test.css'}).catch((e) => console.error(e.toString()));

// CssSyntaxError: classValidator: ./test.css:1:5: classes may not have underscores or dashes in them
//
// > 1 | .foo-bar {
//     |     ^
//   2 |   color: red;
//   3 | }
```


---

# 7.1.0

- feat: insert(Before|After) support multiple new node

# 7.0.0

- Feat: make insertions during iteration safe (major)

# 6.1.2

- Fixed: erroneous trailing combinators in pseudos

# 6.1.1

- Fixed: improve typings of constructor helpers (#292)

# 6.1.0

- Feature: add `sourceIndex` to `Selector` nodes (#290)

# 6.0.16

- Fixed: add missing `index` argument to `each`/`walk` callback types (#289)

# 6.0.15

- Fixed: Node#prev and Node#next type for the first/last node

# 6.0.14

- Fixed: type definitions

# 6.0.13

- Fixed: throw on unexpected pipe symbols

# 6.0.12

- Fixed: `clone` arguments should be optional

# 6.0.11

- Fixed: parse attribute case insensitivity flag

# 6.0.10

- Fixed: `isPseudoElement()` supports `:first-letter` and `:first-line`

# 6.0.9

- Fixed: `Combinator.raws` property type

# 6.0.8

- Fixed: reduced size

# 6.0.7

- Fixed: parse animation percents

# 6.0.6

- Fixed: parse quoted attributes containing a newline correctly

# 6.0.5

- Perf: rework unesc for a 63+% performance boost

# 6.0.4

- Fixed: ts errors

# 6.0.3

- Fixed: replace node built-in "util" module with "util-deprecate"
- Fixed: handle uppercase pseudo elements
- Fixed: do not create invalid combinator before comment

# 6.0.2

- Fixed an issue with parsing and stringifying an empty attribute value

# 6.0.1

- Fixed an issue with unicode surrogate pair parsing

# 6.0.0

- Updated: `cssesc` to 3.0.0 (major)
- Fixed: Issues with escaped `id` and `class` selectors

# 5.0.0

- Allow escaped dot within class name.
- Update PostCSS to 7.0.7 (patch)

# 5.0.0-rc.4

- Fixed an issue where comments immediately after an insensitive (in attribute)
  were not parsed correctly.
- Updated `cssesc` to 2.0.0 (major).
- Removed outdated integration tests.
- Added tests for custom selectors, tags with attributes, the universal
  selector with pseudos, and tokens after combinators.

# 5.0.0-rc.1

To ease adoption of the v5.0 release, we have relaxed the node version
check performed by npm at installation time to allow for node 4, which
remains officially unsupported, but likely to continue working for the
time being.

# 5.0.0-rc.0

This release has **BREAKING CHANGES** that were required to fix regressions
in 4.0.0 and to make the Combinator Node API consistent for all combinator
types. Please read carefully.

## Summary of Changes

* The way a descendent combinator that isn't a single space character (E.g. `.a  .b`) is stored in the AST has changed.
* Named Combinators (E.g. `.a /for/ .b`) are now properly parsed as a combinator.
* It is now possible to look up a node based on the source location of a character in that node and to query nodes if they contain some character.
* Several bug fixes that caused the parser to hang and run out of memory when a `/` was encountered have been fixed.
* The minimum supported version of Node is now `v6.0.0`.

### Changes to the Descendent Combinator

In prior releases, the value of a descendant combinator with multiple spaces included all the spaces.

* `.a   .b`: Extra spaces are now stored as space before.
  - Old & Busted:
    - `combinator.value === "   "`
  - New hotness:
    - `combinator.value === " " && combinator.spaces.before === "  "`
* `.a   /*comment*/.b`: A comment at the end of the combinator causes extra space to become after space.
  - Old & Busted:
    - `combinator.value === "   "`
    - `combinator.raws.value === "   /*comment/"`
  - New hotness:
    - `combinator.value === " "`
    - `combinator.spaces.after === "  "`
    - `combinator.raws.spaces.after === "  /*comment*/"`
* `.a<newline>.b`: whitespace that doesn't start or end with a single space character is stored as a raw value.
  - Old & Busted:
    - `combinator.value === "\n"`
    - `combinator.raws.value === undefined`
  - New hotness:
    - `combinator.value === " "`
    - `combinator.raws.value === "\n"`

### Support for "Named Combinators"

Although, nonstandard and unlikely to ever become a standard, combinators like `/deep/` and `/for/` are now properly supported.

Because they've been taken off the standardization track, there is no spec-official name for combinators of the form `/<ident>/`. However, I talked to [Tab Atkins](https://twitter.com/tabatkins) and we agreed to call them "named combinators" so now they are called that.

Before this release such named combinators were parsed without intention and generated three nodes of type `"tag"` where the first and last nodes had a value of `"/"`.

* `.a /for/ .b` is parsed as a combinator.
  - Old & Busted:
    - `root.nodes[0].nodes[1].type === "tag"`
    - `root.nodes[0].nodes[1].value === "/"`
  - New hotness:
    - `root.nodes[0].nodes[1].type === "combinator"`
    - `root.nodes[0].nodes[1].value === "/for/"`
* `.a /F\6fR/ .b` escapes are handled and uppercase is normalized.
  - Old & Busted:
    - `root.nodes[0].nodes[2].type === "tag"`
    - `root.nodes[0].nodes[2].value === "F\\6fR"`
  - New hotness:
    - `root.nodes[0].nodes[1].type === "combinator"`
    - `root.nodes[0].nodes[1].value === "/for/"`
    - `root.nodes[0].nodes[1].raws.value === "/F\\6fR/"`

### Source position checks and lookups

A new API was added to look up a node based on the source location.

```js
const selectorParser = require("postcss-selector-parser");
// You can find the most specific node for any given character
let combinator = selectorParser.astSync(".a > .b").atPosition(1,4);
combinator.toString() === " > ";
// You can check if a node includes a specific character
// Whitespace surrounding the node that is owned by that node
// is included in the check.
[2,3,4,5,6].map(column => combinator.isAtPosition(1, column));
// => [false, true, true, true, false]
```

# 4.0.0

This release has **BREAKING CHANGES** that were required to fix bugs regarding values with escape sequences. Please read carefully.

* **Identifiers with escapes** - CSS escape sequences are now hidden from the public API by default.
  The normal value of a node like a class name or ID, or an aspect of a node such as attribute
  selector's value, is unescaped. Escapes representing Non-ascii characters are unescaped into
  unicode characters. For example: `bu\tton, .\31 00, #i\2764\FE0Fu, [attr="value is \"quoted\""]`
  will parse respectively to the values `button`, `100`, `i❤️u`, `value is "quoted"`.
  The original escape sequences for these values can be found in the corresponding property name
  in `node.raws`. Where possible, deprecation warnings were added, but the nature
  of escape handling makes it impossible to detect what is escaped or not. Our expectation is
  that most users are neither expecting nor handling escape sequences in their use of this library,
  and so for them, this is a bug fix. Users who are taking care to handle escapes correctly can
  now update their code to remove the escape handling and let us do it for them.

* **Mutating values with escapes** - When you make an update to a node property that has escape handling
  The value is assumed to be unescaped, and any special characters are escaped automatically and
  the corresponding `raws` value is immediately updated. This can result in changes to the original
  escape format. Where the exact value of the escape sequence is important there are methods that
  allow both values to be set in conjunction. There are a number of new convenience methods for
  manipulating values that involve escapes, especially for attributes values where the quote mark
  is involved. See https://github.com/postcss/postcss-selector-parser/pull/133 for an extensive
  write-up on these changes.


**Upgrade/API Example**

In `3.x` there was no unescape handling and internal consistency of several properties was the caller's job to maintain. It was very easy for the developer
to create a CSS file that did not parse correctly when some types of values
were in use.

```js
const selectorParser = require("postcss-selector-parser");
let attr = selectorParser.attribute({attribute: "id", operator: "=", value: "a-value"});
attr.value; // => "a-value"
attr.toString(); // => [id=a-value]
// Add quotes to an attribute's value.
// All these values have to be set by the caller to be consistent:
// no internal consistency is maintained.
attr.raws.unquoted = attr.value
attr.value = "'" + attr.value + "'";
attr.value; // => "'a-value'"
attr.quoted = true;
attr.toString();  // => "[id='a-value']"
```

In `4.0` there is a convenient API for setting and mutating values
that may need escaping. Especially for attributes.

```js
const selectorParser = require("postcss-selector-parser");

// The constructor requires you specify the exact escape sequence
let className = selectorParser.className({value: "illegal class name", raws: {value: "illegal\\ class\\ name"}});
className.toString(); // => '.illegal\\ class\\ name'

// So it's better to set the value as a property
className = selectorParser.className();
// Most properties that deal with identifiers work like this
className.value = "escape for me";
className.value; // => 'escape for me'
className.toString(); // => '.escape\\ for\\ me'

// emoji and all non-ascii are escaped to ensure it works in every css file.
className.value = "😱🦄😍";
className.value; // => '😱🦄😍'
className.toString(); // => '.\\1F631\\1F984\\1F60D'

// you can control the escape sequence if you want, or do bad bad things
className.setPropertyAndEscape('value', 'xxxx', 'yyyy');
className.value; // => "xxxx"
className.toString(); // => ".yyyy"

// Pass a value directly through to the css output without escaping it. 
className.setPropertyWithoutEscape('value', '$REPLACE_ME$');
className.value; // => "$REPLACE_ME$"
className.toString(); // => ".$REPLACE_ME$"

// The biggest changes are to the Attribute class
// passing quoteMark explicitly is required to avoid a deprecation warning.
let attr = selectorParser.attribute({attribute: "id", operator: "=", value: "a-value", quoteMark: null});
attr.toString(); // => "[id=a-value]"
// Get the value with quotes on it and any necessary escapes.
// This is the same as reading attr.value in 3.x.
attr.getQuotedValue(); // => "a-value";
attr.quoteMark; // => null

// Add quotes to an attribute's value.
attr.quoteMark = "'"; // This is all that's required.
attr.toString(); // => "[id='a-value']"
attr.quoted; // => true
// The value is still the same, only the quotes have changed.
attr.value; // => a-value
attr.getQuotedValue(); // => "'a-value'";

// deprecated assignment, no warning because there's no escapes
attr.value = "new-value";
// no quote mark is needed so it is removed
attr.getQuotedValue(); // => "new-value";

// deprecated assignment, 
attr.value = "\"a 'single quoted' value\"";
// > (node:27859) DeprecationWarning: Assigning an attribute a value containing characters that might need to be escaped is deprecated. Call attribute.setValue() instead.
attr.getQuotedValue(); // => '"a \'single quoted\' value"';
// quote mark inferred from first and last characters.
attr.quoteMark; // => '"'

// setValue takes options to make manipulating the value simple.
attr.setValue('foo', {smart: true});
// foo doesn't require any escapes or quotes.
attr.toString(); // => '[id=foo]'
attr.quoteMark; // => null 

// An explicit quote mark can be specified
attr.setValue('foo', {quoteMark: '"'});
attr.toString(); // => '[id="foo"]'

// preserves quote mark by default
attr.setValue('bar');
attr.toString(); // => '[id="bar"]'
attr.quoteMark = null;
attr.toString(); // => '[id=bar]'

// with no arguments, it preserves quote mark even when it's not a great idea
attr.setValue('a value \n that should be quoted');
attr.toString(); // => '[id=a\\ value\\ \\A\\ that\\ should\\ be\\ quoted]'

// smart preservation with a specified default
attr.setValue('a value \n that should be quoted', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => "[id='a value \\A  that should be quoted']"
attr.quoteMark = '"';
// => '[id="a value \\A  that should be quoted"]'

// this keeps double quotes because it wants to quote the value and the existing value has double quotes.
attr.setValue('this should be quoted', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => '[id="this should be quoted"]'

// picks single quotes because the value has double quotes
attr.setValue('a "double quoted" value', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => "[id='a "double quoted" value']"

// setPropertyAndEscape lets you do anything you want. Even things that are a bad idea and illegal.
attr.setPropertyAndEscape('value', 'xxxx', 'the password is 42');
attr.value; // => "xxxx"
attr.toString(); // => "[id=the password is 42]"

// Pass a value directly through to the css output without escaping it. 
attr.setPropertyWithoutEscape('value', '$REPLACEMENT$');
attr.value; // => "$REPLACEMENT$"
attr.toString(); // => "[id=$REPLACEMENT$]"
```

# 3.1.2

* Fix: Removed dot-prop dependency since it's no longer written in es5.

# 3.1.1

* Fix: typescript definitions weren't in the published package.

# 3.1.0

* Fixed numerous bugs in attribute nodes relating to the handling of comments
  and whitespace. There's significant changes to `attrNode.spaces` and `attrNode.raws` since the `3.0.0` release.
* Added `Attribute#offsetOf(part)` to get the offset location of
  attribute parts like `"operator"` and `"value"`. This is most
  often added to `Attribute#sourceIndex` for error reporting.

# 3.0.0

## Breaking changes

* Some tweaks to the tokenizer/attribute selector parsing mean that whitespace
  locations might be slightly different to the 2.x code.
* Better attribute selector parsing with more validation; postcss-selector-parser
  no longer uses regular expressions to parse attribute selectors.
* Added an async API (thanks to @jacobp100); the default `process` API is now
  async, and the sync API is now accessed through `processSync` instead.
* `process()` and `processSync()` now return a string instead of the Processor
  instance.
* Tweaks handling of Less interpolation (thanks to @jwilsson).
* Removes support for Node 0.12.

## Other changes

* `ast()` and `astSync()` methods have been added to the `Processor`. These
  return the `Root` node of the selectors after processing them.
* `transform()` and `transformSync()` methods have been added to the
  `Processor`. These return the value returned by the processor callback
  after processing the selectors.
* Set the parent when inserting a node (thanks to @chriseppstein).
* Correctly adjust indices when using insertBefore/insertAfter (thanks to @tivac).
* Fixes handling of namespaces with qualified tag selectors.
* `process`, `ast` and `transform` (and their sync variants) now accept a
  `postcss` rule node. When provided, better errors are generated and selector
  processing is automatically set back to the rule selector (unless the `updateSelector` option is set to `false`.)
* Now more memory efficient when tokenizing selectors.

### Upgrade hints

The pattern of:

`rule.selector = processor.process(rule.selector).result.toString();`

is now:

`processor.processSync(rule)`

# 2.2.3

* Resolves an issue where the parser would not reduce multiple spaces between an
  ampersand and another simple selector in lossy mode (thanks to @adam-26).

# 2.2.2

* No longer hangs on an unescaped semicolon; instead the parser will throw
  an exception for these cases.

# 2.2.1

* Allows a consumer to specify whitespace tokens when creating a new Node
  (thanks to @Semigradsky).

# 2.2.0

* Added a new option to normalize whitespace when parsing the selector string
  (thanks to @adam-26).

# 2.1.1

* Better unquoted value handling within attribute selectors
  (thanks to @evilebottnawi).

# 2.1.0

* Added: Use string constants for all node types & expose them on the main
  parser instance (thanks to @Aweary).

# 2.0.0

This release contains the following breaking changes:

* Renamed all `eachInside` iterators to `walk`. For example, `eachTag` is now
  `walkTags`, and `eachInside` is now `walk`.
* Renamed `Node#removeSelf()` to `Node#remove()`.
* Renamed `Container#remove()` to `Container#removeChild()`.
* Renamed `Node#raw` to `Node#raws` (thanks to @davidtheclark).
* Now parses `&` as the *nesting* selector, rather than a *tag* selector.
* Fixes misinterpretation of Sass interpolation (e.g. `#{foo}`) as an
  id selector (thanks to @davidtheclark).

and;

* Fixes parsing of attribute selectors with equals signs in them
  (e.g. `[data-attr="foo=bar"]`) (thanks to @montmanu).
* Adds `quoted` and `raw.unquoted` properties to attribute nodes
  (thanks to @davidtheclark).

# 1.3.3

* Fixes an infinite loop on `)` and `]` tokens when they had no opening pairs.
  Now postcss-selector-parser will throw when it encounters these lone tokens.

# 1.3.2

* Now uses plain integers rather than `str.charCodeAt(0)` for compiled builds.

# 1.3.1

* Update flatten to v1.x (thanks to @shinnn).

# 1.3.0

* Adds a new node type, `String`, to fix a crash on selectors such as
  `foo:bar("test")`.

# 1.2.1

* Fixes a crash when the parser encountered a trailing combinator.

# 1.2.0

* A more descriptive error is thrown when the parser expects to find a
  pseudo-class/pseudo-element (thanks to @ashelley).
* Adds support for line/column locations for selector nodes, as well as a
  `Node#sourceIndex` method (thanks to @davidtheclark).

# 1.1.4

* Fixes a crash when a selector started with a `>` combinator. The module will
  now no longer throw if a selector has a leading/trailing combinator node.

# 1.1.3

* Fixes a crash on `@` tokens.

# 1.1.2

* Fixes an infinite loop caused by using parentheses in a non-pseudo element
  context.

# 1.1.1

* Fixes a crash when a backslash ended a selector string.

# 1.1.0

* Adds support for replacing multiple nodes at once with `replaceWith`
  (thanks to @jonathantneal).
* Parser no longer throws on sequential IDs and trailing commas, to support
  parsing of selector hacks.

# 1.0.1

* Fixes using `insertAfter` and `insertBefore` during iteration.

# 1.0.0

* Adds `clone` and `replaceWith` methods to nodes.
* Adds `insertBefore` and `insertAfter` to containers.
* Stabilises API.

# 0.0.5

* Fixes crash on extra whitespace inside a pseudo selector's parentheses.
* Adds sort function to the container class.
* Enables the parser to pass its input through without transforming.
* Iteration-safe `each` and `eachInside`.

# 0.0.4

* Tidy up redundant duplication.
* Fixes a bug where the parser would loop infinitely on universal selectors
  inside pseudo selectors.
* Adds `length` getter and `eachInside`, `map`, `reduce` to the container class.
* When a selector has been removed from the tree, the root node will no longer
  cast it to a string.
* Adds node type iterators to the container class (e.g. `eachComment`).
* Adds filter function to the container class.
* Adds split function to the container class.
* Create new node types by doing `parser.id(opts)` etc.
* Adds support for pseudo classes anywhere in the selector.

# 0.0.3

* Adds `next` and `prev` to the node class.
* Adds `first` and `last` getters to the container class.
* Adds `every` and `some` iterators to the container class.
* Add `empty` alias for `removeAll`.
* Combinators are now types of node.
* Fixes the at method so that it is not an alias for `index`.
* Tidy up creation of new nodes in the parser.
* Refactors how namespaces are handled for consistency & less redundant code.
* Refactors AST to use `nodes` exclusively, and eliminates excessive nesting.
* Fixes nested pseudo parsing.
* Fixes whitespace parsing.

# 0.0.2

* Adds support for namespace selectors.
* Adds support for selectors joined by escaped spaces - such as `.\31\ 0`.

# 0.0.1

* Initial release.


---

# postcss-selector-parser [![test](https://github.com/postcss/postcss-selector-parser/actions/workflows/test.yml/badge.svg)](https://github.com/postcss/postcss-selector-parser/actions/workflows/test.yml)

> Selector parser with built in methods for working with selector strings.

## Install

With [npm](https://npmjs.com/package/postcss-selector-parser) do:

```
npm install postcss-selector-parser
```

## Quick Start

```js
const parser = require('postcss-selector-parser');
const transform = selectors => {
    selectors.walk(selector => {
        // do something with the selector
        console.log(String(selector))
    });
};

const transformed = parser(transform).processSync('h1, h2, h3');
```

To normalize selector whitespace:

```js
const parser = require('postcss-selector-parser');
const normalized = parser().processSync('h1, h2, h3', {lossless: false});
// -> h1,h2,h3
```

Async support is provided through `parser.process` and will resolve a Promise
with the resulting selector string.

## API

Please see [API.md](API.md).

## Credits

* Huge thanks to Andrey Sitnik (@ai) for work on PostCSS which helped
  accelerate this module's development.

## License

MIT


---

# Change Log

All notable changes to this project will be documented in this file.
This project adheres to [Semantic Versioning](http://semver.org/).

## [4.0.0](https://github.com/postcss-modules-local-by-default/compare/v4.0.0-rc.5...v4.0.0) - 2020-13-08

### Fixes

- compatibility with other plugins

## [4.0.0-rc.5](https://github.com/postcss-modules-local-by-default/compare/v4.0.0-rc.4...v4.0.0-rc.5) - 2020-11-08

### Fixes

- compatibility with other plugins

## [4.0.0-rc.4](https://github.com/postcss-modules-local-by-default/compare/v4.0.0-rc.3...v4.0.0-rc.4) - 2020-10-08

### Fixes

- perf
- compatibility with empty custom properties
- works with `options.createImportedName`

## [4.0.0-rc.3](https://github.com/postcss-modules-local-by-default/compare/v4.0.0-rc.2...v4.0.0-rc.3) - 2020-10-08

### BREAKING CHANGE

- minimum supported `postcss` version is `^8.1.0`

### Fixes

- minimum supported `Node.js` version is `^10 || ^12 || >= 14`
- compatibility with PostCSS 8

## [4.0.0-rc.2](https://github.com/postcss-modules-local-by-default/compare/v4.0.0-rc.1...v4.0.0-rc.2) - 2020-09-22

### Fixes

- avoid using `postcss` directly to create decls and rules

## [4.0.0-rc.1](https://github.com/postcss-modules-local-by-default/compare/v4.0.0-rc.0...v4.0.0-rc.1) - 2020-09-22

### BREAKING CHANGE

- update `icss-utils` for PostCSS 8 compatibility

## [4.0.0-rc.0](https://github.com/postcss-modules-local-by-default/compare/v3.0.0...v4.0.0-rc.1) - 2020-09-18

### BREAKING CHANGE

- minimum supported `Node.js` version is `>= 10.13.0 || >= 12.13.0 || >= 14`
- minimum supported `postcss` version is `^8.0.3`
- `postcss` was moved to `peerDependencies`, you need to install `postcss` in your project before use the plugin


---

# CSS Modules: Values

Pass arbitrary values between your module files

### Usage

```css
/* colors.css */
@value primary: #BF4040;
@value secondary: #1F4F7F;

.text-primary {
  color: primary;
}

.text-secondary {
  color: secondary;
}
```

```css
/* breakpoints.css */
@value small: (max-width: 599px);
@value medium: (min-width: 600px) and (max-width: 959px);
@value large: (min-width: 960px);
```

```css
/* my-component.css */
/* alias paths for other values or composition */
@value colors: "./colors.css";
/* import multiple from a single file */
@value primary, secondary from colors;
/* make local aliases to imported values */
@value small as bp-small, large as bp-large from "./breakpoints.css";
/* value as selector name */
@value selectorValue: secondary-color;

.selectorValue {
  color: secondary;
}

.header {
  composes: text-primary from colors;
  box-shadow: 0 0 10px secondary;
}

@media bp-small {
  .header {
    box-shadow: 0 0 4px secondary;
  }
}
@media bp-large {
  .header {
    box-shadow: 0 0 20px secondary;
  }
}
```

**If you are using Sass** along with this PostCSS plugin, do not use the colon `:` in your `@value` definitions. It will cause Sass to crash.

Note also you can _import_ multiple values at once but can only _define_ one value per line.

```css
@value a: b, c: d; /* defines a as "b, c: d" */
```

## License

ISC

## With thanks

- Mark Dalgleish
- Tobias Koppers
- Josh Johnston

---

Glen Maddern, 2015.


---

# Changes to PostCSS Nesting

### 13.0.1

_October 23, 2024_

- Make sorting compound selectors forwards compatible with potential future changes in `postcss-selector-parser`
- Updated: `postcss-selector-parser`
- Updated [`@csstools/selector-resolve-nested`](https://github.com/csstools/postcss-plugins/tree/main/packages/selector-resolve-nested) to [`3.0.0`](https://github.com/csstools/postcss-plugins/tree/main/packages/selector-resolve-nested/CHANGELOG.md#300) (major)
- Updated [`@csstools/selector-specificity`](https://github.com/csstools/postcss-plugins/tree/main/packages/selector-specificity) to [`5.0.0`](https://github.com/csstools/postcss-plugins/tree/main/packages/selector-specificity/CHANGELOG.md#500) (major)

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-nesting/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Nesting [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install postcss-nesting --save-dev`

[PostCSS Nesting] lets you nest style rules inside each other, following the [CSS Nesting specification].

If you want nested rules the same way [Sass] works
you might want to use [PostCSS Nested] instead.

```pcss
.foo {
	color: red;

	&:hover {
		color: green;
	}

	> .bar {
		color: blue;
	}

	@media (prefers-color-scheme: dark) {
		color: cyan;
	}

	color: pink;
}

/* becomes */

.foo {
	color: red;
}
.foo:hover {
		color: green;
	}
.foo  > .bar {
		color: blue;
	}
@media (prefers-color-scheme: dark) {
	.foo {
		color: cyan;
}
	}
.foo {

	color: pink;
}
```

## Usage

Add [PostCSS Nesting] to your project:

```bash
npm install postcss postcss-nesting --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssNesting = require('postcss-nesting');

postcss([
	postcssNesting(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## Options

### edition

The CSS nesting feature has gone through several iterations and what is currently implemented in browsers is not the same as what was originally proposed. This plugin dates back to the original proposal and you might have written your CSS expecting this older behavior.

You can pick the older behavior by setting the `edition` option.  
The `edition` values correspond with rough dates when of a particular version of the specification:
- `2024-02` (default)
- `2021`

> [!TIP]
> If you wrote nested rules with `@nest` you definitely want to set the `edition` to `2021`.  
> If you are unsure than you should try to omit the `edition` option and use the default.

Eventually we will remove support for the older edition, and this plugin option, so it is strongly advised to update your CSS to the latest edition.


```js
postcssNesting({
	edition: '2024-02'
})
```

#### `2024-02` (default)

- usage of `:is()` pseudo-class is no longer optional
- at rules are not combined with the `and` keyword
- `@nest` is removed from the specification
- declarations and nested rules/at-rules are no longer re-ordered

#### `2021`

This version is a continuation of what existed before CSS nesting was implemented in browsers.  
It made a few non-invasive changes to keep up with implementations but it is falling behind.

```pcss
.foo {
	color: red;

	&:hover {
		color: green;
	}

	> .bar {
		color: blue;
	}

	@media (prefers-color-scheme: dark) {
		color: cyan;
	}

	color: pink;
}

/* becomes */

.foo {
	color: red;

	color: pink;
}
.foo:hover {
		color: green;
	}
.foo > .bar {
		color: blue;
	}
@media (prefers-color-scheme: dark) {
	.foo {
		color: cyan;
}
	}
```

### noIsPseudoSelector (edition: `2021`)

#### Specificity

Before :

```css
#alpha,
.beta {
	&:hover {
		order: 1;
	}
}
```

After **without** the option :

```js
postcssNesting()
```

```css
:is(#alpha,.beta):hover {
	order: 1;
}
```

_`.beta:hover` has specificity as if `.beta` where an id selector, matching the specification._

[specificity: 1, 1, 0](https://polypane.app/css-specificity-calculator/#selector=%3Ais(%23alpha%2C.beta)%3Ahover)

After **with** the option :

```js
postcssNesting({
	noIsPseudoSelector: true
})
```

```css
#alpha:hover, .beta:hover {
	order: 1;
}
```

_`.beta:hover` has specificity as if `.beta` where a class selector, conflicting with the specification._

[specificity: 0, 2, 0](https://polypane.app/css-specificity-calculator/#selector=.beta%3Ahover)


#### Complex selectors

Before :

```css
.alpha > .beta {
	& + & {
		order: 2;
	}
}
```

After **without** the option :

```js
postcssNesting()
```

```css
:is(.alpha > .beta) + :is(.alpha > .beta) {
	order: 2;
}
```

After **with** the option :

```js
postcssNesting({
	noIsPseudoSelector: true
})
```

```css
.alpha > .beta + .alpha > .beta {
	order: 2;
}
```

_this is a different selector than expected as `.beta + .alpha` matches `.beta` followed by `.alpha`._<br>
_avoid these cases when you disable `:is()`_<br>
_writing the selector without nesting is advised here_

```css
/* without nesting */
.alpha > .beta + .beta {
	order: 2;
}
```

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#nesting-rules
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/postcss-nesting

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Nesting]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-nesting
[PostCSS Nested]: https://github.com/postcss/postcss-nested
[Sass]: https://sass-lang.com/
[CSS Nesting specification]: https://www.w3.org/TR/css-nesting-1/


---

# Changes to Selector Resolve Nested

### 3.0.0

_October 23, 2024_

- Make sorting compound selectors forwards compatible with potential future changes in `postcss-selector-parser`
- Updated: `postcss-selector-parser`

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/packages/selector-resolve-nested/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# Selector Resolve Nested

[<img alt="npm version" src="https://img.shields.io/npm/v/@csstools/selector-resolve-nested.svg" height="20">][npm-url]
[<img alt="Build Status" src="https://github.com/csstools/postcss-plugins/workflows/test/badge.svg" height="20">][cli-url]
[<img alt="Discord" src="https://shields.io/badge/Discord-5865F2?logo=discord&logoColor=white">][discord]

## API

[Read the API docs](./docs/selector-resolve-nested.md)

## Usage

Add [Selector Resolve Nested] to your project:

```bash
npm install @csstools/selector-resolve-nested --save-dev
```

```js
import { resolveNestedSelector } from '@csstools/selector-resolve-nested';
import parser from 'postcss-selector-parser';

const a = parser().astSync('.foo &');
const b = parser().astSync('.bar');

resolveNestedSelector(a, b); // '.foo .bar'
```

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/selector-resolve-nested

[Selector Resolve Nested]: https://github.com/csstools/postcss-plugins/tree/main/packages/selector-resolve-nested


---

# Changes to Selector Specificity

### 5.0.0

_October 23, 2024_

- Updated: `postcss-selector-parser`

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/packages/selector-specificity/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# Selector Specificity

[<img alt="npm version" src="https://img.shields.io/npm/v/@csstools/selector-specificity.svg" height="20">][npm-url]
[<img alt="Build Status" src="https://github.com/csstools/postcss-plugins/workflows/test/badge.svg" height="20">][cli-url]
[<img alt="Discord" src="https://shields.io/badge/Discord-5865F2?logo=discord&logoColor=white">][discord]

## Usage

Add [Selector Specificity] to your project:

```bash
npm install @csstools/selector-specificity --save-dev
```

```js
import parser from 'postcss-selector-parser';
import { selectorSpecificity } from '@csstools/selector-specificity';

const selectorAST = parser().astSync('#foo:has(> .foo)');
const specificity = selectorSpecificity(selectorAST);

console.log(specificity.a); // 1
console.log(specificity.b); // 1
console.log(specificity.c); // 0
```

_`selectorSpecificity` takes a single selector, not a list of selectors (not : `a, b, c`).
To compare or otherwise manipulate lists of selectors you need to call `selectorSpecificity` on each part._

### Comparing

The package exports a utility function to compare two specificities.

```js
import { selectorSpecificity, compare } from '@csstools/selector-specificity';

const s1 = selectorSpecificity(ast1);
const s2 = selectorSpecificity(ast2);
compare(s1, s2); // -1 | 0 | 1
```

- if `s1 < s2` then `compare(s1, s2)` returns a negative number (`< 0`)
- if `s1 > s2` then `compare(s1, s2)` returns a positive number (`> 0`)
- if `s1 === s2` then `compare(s1, s2)` returns zero (`=== 0`)

## Prior Art

- [keeganstreet/specificity](https://github.com/keeganstreet/specificity)
- [bramus/specificity](https://github.com/bramus/specificity)

For CSSTools we always use `postcss-selector-parser` and want to calculate specificity from this AST.

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/selector-specificity

[Selector Specificity]: https://github.com/csstools/postcss-plugins/tree/main/packages/selector-specificity


---

# API Documentation

*Please use only this documented API when working with the parser. Methods
not documented here are subject to change at any point.*

## `parser` function

This is the module's main entry point.

```js
const parser = require('postcss-selector-parser');
```

### `parser([transform], [options])`

Creates a new `processor` instance

```js
const processor = parser();
```

Or, with optional transform function

```js
const transform = selectors => {
    selectors.walkUniversals(selector => {
        selector.remove();
    });
};

const processor = parser(transform)

// Example
const result = processor.processSync('*.class');
// => .class
```

[See processor documentation](#processor)

Arguments:

* `transform (function)`: Provide a function to work with the parsed AST.
* `options (object)`: Provide default options for all calls on the returned `Processor`.

### `parser.attribute([props])`

Creates a new attribute selector.

```js
parser.attribute({attribute: 'href'});
// => [href]
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.className([props])`

Creates a new class selector.

```js
parser.className({value: 'button'});
// => .button
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.combinator([props])`

Creates a new selector combinator.

```js
parser.combinator({value: '+'});
// => +
```

Arguments:

* `props (object)`: The new node's properties.

Notes:
* **Descendant Combinators** The value of descendant combinators created by the
  parser always just a single space (`" "`). For descendant selectors with no
  comments, additional space is now stored in `node.spaces.before`. Depending
  on the location of comments, additional spaces may be stored in
  `node.raws.spaces.before`, `node.raws.spaces.after`, or `node.raws.value`.
* **Named Combinators** Although, nonstandard and unlikely to ever become a standard,
  named combinators like `/deep/` and `/for/` are parsed as combinators. The
  `node.value` is name after being unescaped and normalized as lowercase. The
  original value for the combinator name is stored in `node.raws.value`.


### `parser.comment([props])`

Creates a new comment.

```js
parser.comment({value: '/* Affirmative, Dave. I read you. */'});
// => /* Affirmative, Dave. I read you. */
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.id([props])`

Creates a new id selector.

```js
parser.id({value: 'search'});
// => #search
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.nesting([props])`

Creates a new nesting selector.

```js
parser.nesting();
// => &
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.pseudo([props])`

Creates a new pseudo selector.

```js
parser.pseudo({value: '::before'});
// => ::before
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.root([props])`

Creates a new root node.

```js
parser.root();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.selector([props])`

Creates a new selector node.

```js
parser.selector();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.string([props])`

Creates a new string node.

```js
parser.string();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.tag([props])`

Creates a new tag selector.

```js
parser.tag({value: 'button'});
// => button
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.universal([props])`

Creates a new universal selector.

```js
parser.universal();
// => *
```

Arguments:

* `props (object)`: The new node's properties.

## Node types

### `node.type`

A string representation of the selector type. It can be one of the following;
`attribute`, `class`, `combinator`, `comment`, `id`, `nesting`, `pseudo`,
`root`, `selector`, `string`, `tag`, or `universal`. Note that for convenience,
these constants are exposed on the main `parser` as uppercased keys. So for
example you can get `id` by querying `parser.ID`.

```js
parser.attribute({attribute: 'href'}).type;
// => 'attribute'
```

### `node.parent`

Returns the parent node.

```js
root.nodes[0].parent === root;
```

### `node.toString()`, `String(node)`, or `'' + node`

Returns a string representation of the node.

```js
const id = parser.id({value: 'search'});
console.log(String(id));
// => #search
```

### `node.next()` & `node.prev()`

Returns the next/previous child of the parent node.

```js
const next = id.next();
if (next && next.type !== 'combinator') {
    throw new Error('Qualified IDs are not allowed!');
}
```

### `node.replaceWith(node[,...nodeN])`

Replace a node with another.

```js
const attr = selectors.first.first;
const className = parser.className({value: 'test'});
attr.replaceWith(className);
```

Arguments:

* `node`: The node to substitute the original with.
...
* `nodeN`: The node to substitute the original with.

### `node.remove()`

Removes the node from its parent node.

```js
if (node.type === 'id') {
    node.remove();
}
```

### `node.clone([opts])`

Returns a copy of a node, detached from any parent containers that the
original might have had.

```js
const cloned = node.clone();
```

### `node.isAtPosition(line, column)`

Return a `boolean` indicating whether this node includes the character at the
position of the given line and column. Returns `undefined` if the nodes lack
sufficient source metadata to determine the position.

Arguments:

* `line`: 1-index based line number relative to the start of the selector.
* `column`: 1-index based column number relative to the start of the selector.

### `node.spaces`

Extra whitespaces around the node will be moved into `node.spaces.before` and
`node.spaces.after`. So for example, these spaces will be moved as they have
no semantic meaning:

```css
      h1     ,     h2   {}
```

For descendent selectors, the value is always a single space.

```css
h1        h2 {}
```

Additional whitespace is found in either the `node.spaces.before` and `node.spaces.after` depending on the presence of comments or other whitespace characters. If the actual whitespace does not start or end with a single space, the node's raw value is set to the actual space(s) found in the source.

### `node.source`

An object describing the node's start/end, line/column source position.

Within the following CSS, the `.bar` class node ...

```css
.foo,
  .bar {}
```

... will contain the following `source` object.

```js
source: {
    start: {
        line: 2,
        column: 3
    },
    end: {
        line: 2,
        column: 6
    }
}
```

### `node.sourceIndex`

The zero-based index of the node within the original source string.

Within the following CSS, the `.baz` class node will have a `sourceIndex` of `12`.

```css
.foo, .bar, .baz {}
```

## Container types

The `root`, `selector`, and `pseudo` nodes have some helper methods for working
with their children.

### `container.nodes`

An array of the container's children.

```js
// Input: h1 h2
selectors.at(0).nodes.length   // => 3
selectors.at(0).nodes[0].value // => 'h1'
selectors.at(0).nodes[1].value // => ' '
```

### `container.first` & `container.last`

The first/last child of the container.

```js
selector.first === selector.nodes[0];
selector.last === selector.nodes[selector.nodes.length - 1];
```

### `container.at(index)`

Returns the node at position `index`.

```js
selector.at(0) === selector.first;
selector.at(0) === selector.nodes[0];
```

Arguments:

* `index`: The index of the node to return.

### `container.atPosition(line, column)`

Returns the node at the source position `line` and `column`.

```js
// Input: :not(.foo),\n#foo > :matches(ol, ul)
selector.atPosition(1, 1); // => :not(.foo)
selector.atPosition(2, 1); // => \n#foo
```

Arguments:

* `line`: The line number of the node to return.
* `column`: The column number of the node to return.

### `container.index(node)`

Return the index of the node within its container.

```js
selector.index(selector.nodes[2]) // => 2
```

Arguments:

* `node`: A node within the current container.

### `container.length`

Proxy to the length of the container's nodes.

```js
container.length === container.nodes.length
```

### `container` Array iterators

The container class provides proxies to certain Array methods; these are:

* `container.map === container.nodes.map`
* `container.reduce === container.nodes.reduce`
* `container.every === container.nodes.every`
* `container.some === container.nodes.some`
* `container.filter === container.nodes.filter`
* `container.sort === container.nodes.sort`

Note that these methods only work on a container's immediate children; recursive
iteration is provided by `container.walk`.

### `container.each(callback)`

Iterate the container's immediate children, calling `callback` for each child.
You may return `false` within the callback to break the iteration.

```js
let className;
selectors.each((selector, index) => {
    if (selector.type === 'class') {
        className = selector.value;
        return false;
    }
});
```

Note that unlike `Array#forEach()`, this iterator is safe to use whilst adding
or removing nodes from the container.

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  and `index` arguments.

### `container.walk(callback)`

Like `container#each`, but will also iterate child nodes as long as they are
`container` types.

```js
selectors.walk((selector, index) => {
    // all nodes
});
```

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  and `index` arguments.

This iterator is safe to use whilst mutating `container.nodes`,
like `container#each`.

### `container.walk` proxies

The container class provides proxy methods for iterating over types of nodes,
so that it is easier to write modules that target specific selectors. Those
methods are:

* `container.walkAttributes`
* `container.walkClasses`
* `container.walkCombinators`
* `container.walkComments`
* `container.walkIds`
* `container.walkNesting`
* `container.walkPseudos`
* `container.walkTags`
* `container.walkUniversals`

### `container.split(callback)`

This method allows you to split a group of nodes by returning `true` from
a callback. It returns an array of arrays, where each inner array corresponds
to the groups that you created via the callback.

```js
// (input) => h1 h2>>h3
const list = selectors.first.split(selector => {
    return selector.type === 'combinator';
});

// (node values) => [['h1', ' '], ['h2', '>>'], ['h3']]
```

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  as an argument.

### `container.prepend(node)` & `container.append(node)`

Add a node to the start/end of the container. Note that doing so will set
the parent property of the node to this container.

```js
const id = parser.id({value: 'search'});
selector.append(id);
```

Arguments:

* `node`: The node to add.

### `container.insertBefore(old, new[, ...newNodes])` & `container.insertAfter(old, new[, ...newNodes])`

Add a node before or after an existing node in a container:

```js
selectors.walk(selector => {
    if (selector.type !== 'class') {
        const className = parser.className({value: 'theme-name'});
        selector.parent.insertAfter(selector, className);
    }
});
```

Arguments:

* `old`: The existing node in the container.
* `new`: The new node to add before/after the existing node.

### `container.removeChild(node)`

Remove the node from the container. Note that you can also use
`node.remove()` if you would like to remove just a single node.

```js
selector.length // => 2
selector.remove(id)
selector.length // => 1;
id.parent       // undefined
```

Arguments:

* `node`: The node to remove.

### `container.removeAll()` or `container.empty()`

Remove all children from the container.

```js
selector.removeAll();
selector.length // => 0
```

## Root nodes

A root node represents a comma separated list of selectors. Indeed, all
a root's `toString()` method does is join its selector children with a ','.
Other than this, it has no special functionality and acts like a container.

### `root.trailingComma`

This will be set to `true` if the input has a trailing comma, in order to
support parsing of legacy CSS hacks.

## Selector nodes

A selector node represents a single complex selector. For example, this
selector string `h1 h2 h3, [href] > p`, is represented as two selector nodes.
It has no special functionality of its own.

## Pseudo nodes

A pseudo selector extends a container node; if it has any parameters of its
own (such as `h1:not(h2, h3)`), they will be its children. Note that the pseudo
`value` will always contain the colons preceding the pseudo identifier. This
is so that both `:before` and `::before` are properly represented in the AST.

## Attribute nodes

### `attribute.quoted`

Returns `true` if the attribute's value is wrapped in quotation marks, false if it is not.
Remains `undefined` if there is no attribute value.

```css
[href=foo] /* false */
[href='foo'] /* true */
[href="foo"] /* true */
[href] /* undefined */
```

### `attribute.qualifiedAttribute`

Returns the attribute name qualified with the namespace if one is given.

### `attribute.offsetOf(part)`

 Returns the offset of the attribute part specified relative to the
 start of the node of the output string. This is useful in raising
 error messages about a specific part of the attribute, especially
 in combination with `attribute.sourceIndex`.

 Returns `-1` if the name is invalid or the value doesn't exist in this
 attribute.

 The legal values for `part` are:

 * `"ns"` - alias for "namespace"
 * `"namespace"` - the namespace if it exists.
 * `"attribute"` - the attribute name
 * `"attributeNS"` - the start of the attribute or its namespace
 * `"operator"` - the match operator of the attribute
 * `"value"` - The value (string or identifier)
 * `"insensitive"` - the case insensitivity flag

### `attribute.raws.unquoted`

Returns the unquoted content of the attribute's value.
Remains `undefined` if there is no attribute value.

```css
[href=foo] /* foo */
[href='foo'] /* foo */
[href="foo"] /* foo */
[href] /* undefined */
```

### `attribute.spaces`

Like `node.spaces` with the `before` and `after` values containing the spaces
around the element, the parts of the attribute can also have spaces before
and after them. The for each of `attribute`, `operator`, `value` and
`insensitive` there is corresponding property of the same nam in
`node.spaces` that has an optional `before` or `after` string containing only
whitespace.

Note that corresponding values in `attributes.raws.spaces` contain values
including any comments. If set, these values will override the
`attribute.spaces` value. Take care to remove them if changing
`attribute.spaces`.

### `attribute.raws`

The raws object stores comments and other information necessary to re-render
the node exactly as it was in the source.

If a comment is embedded within the identifiers for the `namespace`, `attribute`
or `value` then a property is placed in the raws for that value containing the full source of the propery including comments.

If a comment is embedded within the space between parts of the attribute
then the raw for that space is set accordingly.

Setting an attribute's property `raws` value to be deleted.

For now, changing the spaces required also updating or removing any of the
raws values that override them.

Example: `[ /*before*/ href /* after-attr */ = /* after-operator */ te/*inside-value*/st/* wow */ /*omg*/i/*bbq*/ /*whodoesthis*/]` would parse as:

```js
{
  attribute: "href",
  operator: "=",
  value: "test",
  spaces: {
    before: '',
    after: '',
    attribute: { before: '  ', after: '  ' },
    operator: { after: '  ' },
    value: { after: ' ' },
    insensitive: { after: ' ' }
  },
  raws: {
    spaces: {
      attribute: { before: ' /*before*/ ', after: ' /* after-attr */ ' },
      operator: { after: ' /* after-operator */ ' },
      value: { after: '/* wow */ /*omg*/' },
      insensitive: { after: '/*bbq*/ /*whodoesthis*/' }
    },
    unquoted: 'test',
    value: 'te/*inside-value*/st'
  }
}
```

## `Processor`

### `ProcessorOptions`

* `lossless` - When `true`, whitespace is preserved. Defaults to `true`.
* `updateSelector` - When `true`, if any processor methods are passed a postcss
  `Rule` node instead of a string, then that Rule's selector is updated
  with the results of the processing. Defaults to `true`.

### `process|processSync(selectors, [options])`

Processes the `selectors`, returning a string from the result of processing.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

**Example:**

```js
const parser = require("postcss-selector-parser");
const processor = parser();

let result = processor.processSync(' .class');
console.log(result);
// =>  .class

// Asynchronous operation
let promise = processor.process(' .class').then(result => {
    console.log(result)
    // => .class
});

// To have the parser normalize whitespace values, utilize the options
result = processor.processSync('  .class  ', {lossless: false});
console.log(result);
// => .class

// For better syntax errors, pass a PostCSS Rule node.
const postcss = require('postcss');
rule = postcss.rule({selector: ' #foo    > a,  .class  '});
processor.process(rule, {lossless: false, updateSelector: true}).then(result => {
    console.log(result);
    // => #foo>a,.class
    console.log("rule:", rule.selector);
    // => rule: #foo>a,.class
})
```

Arguments:

* `selectors (string|postcss.Rule)`: Either a selector string or a PostCSS Rule
  node.
* `[options] (object)`: Process options


### `ast|astSync(selectors, [options])`

Like `process()` and `processSync()` but after
processing the `selectors` these methods return the `Root` node of the result
instead of a string.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

### `transform|transformSync(selectors, [options])`

Like `process()` and `processSync()` but after
processing the `selectors` these methods return the value returned by the
processor callback.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

### Error Handling Within Selector Processors

The root node passed to the selector processor callback
has a method `error(message, options)` that returns an
error object. This method should always be used to raise
errors relating to the syntax of selectors. The options
to this method are passed to postcss's error constructor
([documentation](http://postcss.org/api/#container-error)).

#### Async Error Example

```js
let processor = (root) => {
    return new Promise((resolve, reject) => {
        root.walkClasses((classNode) => {
            if (/^(.*)[-_]/.test(classNode.value)) {
                let msg = "classes may not have underscores or dashes in them";
                reject(root.error(msg, {
                    index: classNode.sourceIndex + RegExp.$1.length + 1,
                    word: classNode.value
                }));
            }
        });
        resolve();
    });
};

const postcss = require("postcss");
const parser = require("postcss-selector-parser");
const selectorProcessor = parser(processor);
const plugin = postcss.plugin('classValidator', (options) => {
    return (root) => {
        let promises = [];
        root.walkRules(rule => {
            promises.push(selectorProcessor.process(rule));
        });
        return Promise.all(promises);
    };
});
postcss(plugin()).process(`
.foo-bar {
  color: red;
}
`.trim(), {from: 'test.css'}).catch((e) => console.error(e.toString()));

// CssSyntaxError: classValidator: ./test.css:1:5: classes may not have underscores or dashes in them
//
// > 1 | .foo-bar {
//     |     ^
//   2 |   color: red;
//   3 | }
```

#### Synchronous Error Example

```js
let processor = (root) => {
    root.walkClasses((classNode) => {
        if (/.*[-_]/.test(classNode.value)) {
            let msg = "classes may not have underscores or dashes in them";
            throw root.error(msg, {
                index: classNode.sourceIndex,
                word: classNode.value
            });
        }
    });
};

const postcss = require("postcss");
const parser = require("postcss-selector-parser");
const selectorProcessor = parser(processor);
const plugin = postcss.plugin('classValidator', (options) => {
    return (root) => {
        root.walkRules(rule => {
            selectorProcessor.processSync(rule);
        });
    };
});
postcss(plugin()).process(`
.foo-bar {
  color: red;
}
`.trim(), {from: 'test.css'}).catch((e) => console.error(e.toString()));

// CssSyntaxError: classValidator: ./test.css:1:5: classes may not have underscores or dashes in them
//
// > 1 | .foo-bar {
//     |     ^
//   2 |   color: red;
//   3 | }
```


---

# 7.1.0

- feat: insert(Before|After) support multiple new node

# 7.0.0

- Feat: make insertions during iteration safe (major)

# 6.1.2

- Fixed: erroneous trailing combinators in pseudos

# 6.1.1

- Fixed: improve typings of constructor helpers (#292)

# 6.1.0

- Feature: add `sourceIndex` to `Selector` nodes (#290)

# 6.0.16

- Fixed: add missing `index` argument to `each`/`walk` callback types (#289)

# 6.0.15

- Fixed: Node#prev and Node#next type for the first/last node

# 6.0.14

- Fixed: type definitions

# 6.0.13

- Fixed: throw on unexpected pipe symbols

# 6.0.12

- Fixed: `clone` arguments should be optional

# 6.0.11

- Fixed: parse attribute case insensitivity flag

# 6.0.10

- Fixed: `isPseudoElement()` supports `:first-letter` and `:first-line`

# 6.0.9

- Fixed: `Combinator.raws` property type

# 6.0.8

- Fixed: reduced size

# 6.0.7

- Fixed: parse animation percents

# 6.0.6

- Fixed: parse quoted attributes containing a newline correctly

# 6.0.5

- Perf: rework unesc for a 63+% performance boost

# 6.0.4

- Fixed: ts errors

# 6.0.3

- Fixed: replace node built-in "util" module with "util-deprecate"
- Fixed: handle uppercase pseudo elements
- Fixed: do not create invalid combinator before comment

# 6.0.2

- Fixed an issue with parsing and stringifying an empty attribute value

# 6.0.1

- Fixed an issue with unicode surrogate pair parsing

# 6.0.0

- Updated: `cssesc` to 3.0.0 (major)
- Fixed: Issues with escaped `id` and `class` selectors

# 5.0.0

- Allow escaped dot within class name.
- Update PostCSS to 7.0.7 (patch)

# 5.0.0-rc.4

- Fixed an issue where comments immediately after an insensitive (in attribute)
  were not parsed correctly.
- Updated `cssesc` to 2.0.0 (major).
- Removed outdated integration tests.
- Added tests for custom selectors, tags with attributes, the universal
  selector with pseudos, and tokens after combinators.

# 5.0.0-rc.1

To ease adoption of the v5.0 release, we have relaxed the node version
check performed by npm at installation time to allow for node 4, which
remains officially unsupported, but likely to continue working for the
time being.

# 5.0.0-rc.0

This release has **BREAKING CHANGES** that were required to fix regressions
in 4.0.0 and to make the Combinator Node API consistent for all combinator
types. Please read carefully.

## Summary of Changes

* The way a descendent combinator that isn't a single space character (E.g. `.a  .b`) is stored in the AST has changed.
* Named Combinators (E.g. `.a /for/ .b`) are now properly parsed as a combinator.
* It is now possible to look up a node based on the source location of a character in that node and to query nodes if they contain some character.
* Several bug fixes that caused the parser to hang and run out of memory when a `/` was encountered have been fixed.
* The minimum supported version of Node is now `v6.0.0`.

### Changes to the Descendent Combinator

In prior releases, the value of a descendant combinator with multiple spaces included all the spaces.

* `.a   .b`: Extra spaces are now stored as space before.
  - Old & Busted:
    - `combinator.value === "   "`
  - New hotness:
    - `combinator.value === " " && combinator.spaces.before === "  "`
* `.a   /*comment*/.b`: A comment at the end of the combinator causes extra space to become after space.
  - Old & Busted:
    - `combinator.value === "   "`
    - `combinator.raws.value === "   /*comment/"`
  - New hotness:
    - `combinator.value === " "`
    - `combinator.spaces.after === "  "`
    - `combinator.raws.spaces.after === "  /*comment*/"`
* `.a<newline>.b`: whitespace that doesn't start or end with a single space character is stored as a raw value.
  - Old & Busted:
    - `combinator.value === "\n"`
    - `combinator.raws.value === undefined`
  - New hotness:
    - `combinator.value === " "`
    - `combinator.raws.value === "\n"`

### Support for "Named Combinators"

Although, nonstandard and unlikely to ever become a standard, combinators like `/deep/` and `/for/` are now properly supported.

Because they've been taken off the standardization track, there is no spec-official name for combinators of the form `/<ident>/`. However, I talked to [Tab Atkins](https://twitter.com/tabatkins) and we agreed to call them "named combinators" so now they are called that.

Before this release such named combinators were parsed without intention and generated three nodes of type `"tag"` where the first and last nodes had a value of `"/"`.

* `.a /for/ .b` is parsed as a combinator.
  - Old & Busted:
    - `root.nodes[0].nodes[1].type === "tag"`
    - `root.nodes[0].nodes[1].value === "/"`
  - New hotness:
    - `root.nodes[0].nodes[1].type === "combinator"`
    - `root.nodes[0].nodes[1].value === "/for/"`
* `.a /F\6fR/ .b` escapes are handled and uppercase is normalized.
  - Old & Busted:
    - `root.nodes[0].nodes[2].type === "tag"`
    - `root.nodes[0].nodes[2].value === "F\\6fR"`
  - New hotness:
    - `root.nodes[0].nodes[1].type === "combinator"`
    - `root.nodes[0].nodes[1].value === "/for/"`
    - `root.nodes[0].nodes[1].raws.value === "/F\\6fR/"`

### Source position checks and lookups

A new API was added to look up a node based on the source location.

```js
const selectorParser = require("postcss-selector-parser");
// You can find the most specific node for any given character
let combinator = selectorParser.astSync(".a > .b").atPosition(1,4);
combinator.toString() === " > ";
// You can check if a node includes a specific character
// Whitespace surrounding the node that is owned by that node
// is included in the check.
[2,3,4,5,6].map(column => combinator.isAtPosition(1, column));
// => [false, true, true, true, false]
```

# 4.0.0

This release has **BREAKING CHANGES** that were required to fix bugs regarding values with escape sequences. Please read carefully.

* **Identifiers with escapes** - CSS escape sequences are now hidden from the public API by default.
  The normal value of a node like a class name or ID, or an aspect of a node such as attribute
  selector's value, is unescaped. Escapes representing Non-ascii characters are unescaped into
  unicode characters. For example: `bu\tton, .\31 00, #i\2764\FE0Fu, [attr="value is \"quoted\""]`
  will parse respectively to the values `button`, `100`, `i❤️u`, `value is "quoted"`.
  The original escape sequences for these values can be found in the corresponding property name
  in `node.raws`. Where possible, deprecation warnings were added, but the nature
  of escape handling makes it impossible to detect what is escaped or not. Our expectation is
  that most users are neither expecting nor handling escape sequences in their use of this library,
  and so for them, this is a bug fix. Users who are taking care to handle escapes correctly can
  now update their code to remove the escape handling and let us do it for them.

* **Mutating values with escapes** - When you make an update to a node property that has escape handling
  The value is assumed to be unescaped, and any special characters are escaped automatically and
  the corresponding `raws` value is immediately updated. This can result in changes to the original
  escape format. Where the exact value of the escape sequence is important there are methods that
  allow both values to be set in conjunction. There are a number of new convenience methods for
  manipulating values that involve escapes, especially for attributes values where the quote mark
  is involved. See https://github.com/postcss/postcss-selector-parser/pull/133 for an extensive
  write-up on these changes.


**Upgrade/API Example**

In `3.x` there was no unescape handling and internal consistency of several properties was the caller's job to maintain. It was very easy for the developer
to create a CSS file that did not parse correctly when some types of values
were in use.

```js
const selectorParser = require("postcss-selector-parser");
let attr = selectorParser.attribute({attribute: "id", operator: "=", value: "a-value"});
attr.value; // => "a-value"
attr.toString(); // => [id=a-value]
// Add quotes to an attribute's value.
// All these values have to be set by the caller to be consistent:
// no internal consistency is maintained.
attr.raws.unquoted = attr.value
attr.value = "'" + attr.value + "'";
attr.value; // => "'a-value'"
attr.quoted = true;
attr.toString();  // => "[id='a-value']"
```

In `4.0` there is a convenient API for setting and mutating values
that may need escaping. Especially for attributes.

```js
const selectorParser = require("postcss-selector-parser");

// The constructor requires you specify the exact escape sequence
let className = selectorParser.className({value: "illegal class name", raws: {value: "illegal\\ class\\ name"}});
className.toString(); // => '.illegal\\ class\\ name'

// So it's better to set the value as a property
className = selectorParser.className();
// Most properties that deal with identifiers work like this
className.value = "escape for me";
className.value; // => 'escape for me'
className.toString(); // => '.escape\\ for\\ me'

// emoji and all non-ascii are escaped to ensure it works in every css file.
className.value = "😱🦄😍";
className.value; // => '😱🦄😍'
className.toString(); // => '.\\1F631\\1F984\\1F60D'

// you can control the escape sequence if you want, or do bad bad things
className.setPropertyAndEscape('value', 'xxxx', 'yyyy');
className.value; // => "xxxx"
className.toString(); // => ".yyyy"

// Pass a value directly through to the css output without escaping it. 
className.setPropertyWithoutEscape('value', '$REPLACE_ME$');
className.value; // => "$REPLACE_ME$"
className.toString(); // => ".$REPLACE_ME$"

// The biggest changes are to the Attribute class
// passing quoteMark explicitly is required to avoid a deprecation warning.
let attr = selectorParser.attribute({attribute: "id", operator: "=", value: "a-value", quoteMark: null});
attr.toString(); // => "[id=a-value]"
// Get the value with quotes on it and any necessary escapes.
// This is the same as reading attr.value in 3.x.
attr.getQuotedValue(); // => "a-value";
attr.quoteMark; // => null

// Add quotes to an attribute's value.
attr.quoteMark = "'"; // This is all that's required.
attr.toString(); // => "[id='a-value']"
attr.quoted; // => true
// The value is still the same, only the quotes have changed.
attr.value; // => a-value
attr.getQuotedValue(); // => "'a-value'";

// deprecated assignment, no warning because there's no escapes
attr.value = "new-value";
// no quote mark is needed so it is removed
attr.getQuotedValue(); // => "new-value";

// deprecated assignment, 
attr.value = "\"a 'single quoted' value\"";
// > (node:27859) DeprecationWarning: Assigning an attribute a value containing characters that might need to be escaped is deprecated. Call attribute.setValue() instead.
attr.getQuotedValue(); // => '"a \'single quoted\' value"';
// quote mark inferred from first and last characters.
attr.quoteMark; // => '"'

// setValue takes options to make manipulating the value simple.
attr.setValue('foo', {smart: true});
// foo doesn't require any escapes or quotes.
attr.toString(); // => '[id=foo]'
attr.quoteMark; // => null 

// An explicit quote mark can be specified
attr.setValue('foo', {quoteMark: '"'});
attr.toString(); // => '[id="foo"]'

// preserves quote mark by default
attr.setValue('bar');
attr.toString(); // => '[id="bar"]'
attr.quoteMark = null;
attr.toString(); // => '[id=bar]'

// with no arguments, it preserves quote mark even when it's not a great idea
attr.setValue('a value \n that should be quoted');
attr.toString(); // => '[id=a\\ value\\ \\A\\ that\\ should\\ be\\ quoted]'

// smart preservation with a specified default
attr.setValue('a value \n that should be quoted', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => "[id='a value \\A  that should be quoted']"
attr.quoteMark = '"';
// => '[id="a value \\A  that should be quoted"]'

// this keeps double quotes because it wants to quote the value and the existing value has double quotes.
attr.setValue('this should be quoted', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => '[id="this should be quoted"]'

// picks single quotes because the value has double quotes
attr.setValue('a "double quoted" value', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => "[id='a "double quoted" value']"

// setPropertyAndEscape lets you do anything you want. Even things that are a bad idea and illegal.
attr.setPropertyAndEscape('value', 'xxxx', 'the password is 42');
attr.value; // => "xxxx"
attr.toString(); // => "[id=the password is 42]"

// Pass a value directly through to the css output without escaping it. 
attr.setPropertyWithoutEscape('value', '$REPLACEMENT$');
attr.value; // => "$REPLACEMENT$"
attr.toString(); // => "[id=$REPLACEMENT$]"
```

# 3.1.2

* Fix: Removed dot-prop dependency since it's no longer written in es5.

# 3.1.1

* Fix: typescript definitions weren't in the published package.

# 3.1.0

* Fixed numerous bugs in attribute nodes relating to the handling of comments
  and whitespace. There's significant changes to `attrNode.spaces` and `attrNode.raws` since the `3.0.0` release.
* Added `Attribute#offsetOf(part)` to get the offset location of
  attribute parts like `"operator"` and `"value"`. This is most
  often added to `Attribute#sourceIndex` for error reporting.

# 3.0.0

## Breaking changes

* Some tweaks to the tokenizer/attribute selector parsing mean that whitespace
  locations might be slightly different to the 2.x code.
* Better attribute selector parsing with more validation; postcss-selector-parser
  no longer uses regular expressions to parse attribute selectors.
* Added an async API (thanks to @jacobp100); the default `process` API is now
  async, and the sync API is now accessed through `processSync` instead.
* `process()` and `processSync()` now return a string instead of the Processor
  instance.
* Tweaks handling of Less interpolation (thanks to @jwilsson).
* Removes support for Node 0.12.

## Other changes

* `ast()` and `astSync()` methods have been added to the `Processor`. These
  return the `Root` node of the selectors after processing them.
* `transform()` and `transformSync()` methods have been added to the
  `Processor`. These return the value returned by the processor callback
  after processing the selectors.
* Set the parent when inserting a node (thanks to @chriseppstein).
* Correctly adjust indices when using insertBefore/insertAfter (thanks to @tivac).
* Fixes handling of namespaces with qualified tag selectors.
* `process`, `ast` and `transform` (and their sync variants) now accept a
  `postcss` rule node. When provided, better errors are generated and selector
  processing is automatically set back to the rule selector (unless the `updateSelector` option is set to `false`.)
* Now more memory efficient when tokenizing selectors.

### Upgrade hints

The pattern of:

`rule.selector = processor.process(rule.selector).result.toString();`

is now:

`processor.processSync(rule)`

# 2.2.3

* Resolves an issue where the parser would not reduce multiple spaces between an
  ampersand and another simple selector in lossy mode (thanks to @adam-26).

# 2.2.2

* No longer hangs on an unescaped semicolon; instead the parser will throw
  an exception for these cases.

# 2.2.1

* Allows a consumer to specify whitespace tokens when creating a new Node
  (thanks to @Semigradsky).

# 2.2.0

* Added a new option to normalize whitespace when parsing the selector string
  (thanks to @adam-26).

# 2.1.1

* Better unquoted value handling within attribute selectors
  (thanks to @evilebottnawi).

# 2.1.0

* Added: Use string constants for all node types & expose them on the main
  parser instance (thanks to @Aweary).

# 2.0.0

This release contains the following breaking changes:

* Renamed all `eachInside` iterators to `walk`. For example, `eachTag` is now
  `walkTags`, and `eachInside` is now `walk`.
* Renamed `Node#removeSelf()` to `Node#remove()`.
* Renamed `Container#remove()` to `Container#removeChild()`.
* Renamed `Node#raw` to `Node#raws` (thanks to @davidtheclark).
* Now parses `&` as the *nesting* selector, rather than a *tag* selector.
* Fixes misinterpretation of Sass interpolation (e.g. `#{foo}`) as an
  id selector (thanks to @davidtheclark).

and;

* Fixes parsing of attribute selectors with equals signs in them
  (e.g. `[data-attr="foo=bar"]`) (thanks to @montmanu).
* Adds `quoted` and `raw.unquoted` properties to attribute nodes
  (thanks to @davidtheclark).

# 1.3.3

* Fixes an infinite loop on `)` and `]` tokens when they had no opening pairs.
  Now postcss-selector-parser will throw when it encounters these lone tokens.

# 1.3.2

* Now uses plain integers rather than `str.charCodeAt(0)` for compiled builds.

# 1.3.1

* Update flatten to v1.x (thanks to @shinnn).

# 1.3.0

* Adds a new node type, `String`, to fix a crash on selectors such as
  `foo:bar("test")`.

# 1.2.1

* Fixes a crash when the parser encountered a trailing combinator.

# 1.2.0

* A more descriptive error is thrown when the parser expects to find a
  pseudo-class/pseudo-element (thanks to @ashelley).
* Adds support for line/column locations for selector nodes, as well as a
  `Node#sourceIndex` method (thanks to @davidtheclark).

# 1.1.4

* Fixes a crash when a selector started with a `>` combinator. The module will
  now no longer throw if a selector has a leading/trailing combinator node.

# 1.1.3

* Fixes a crash on `@` tokens.

# 1.1.2

* Fixes an infinite loop caused by using parentheses in a non-pseudo element
  context.

# 1.1.1

* Fixes a crash when a backslash ended a selector string.

# 1.1.0

* Adds support for replacing multiple nodes at once with `replaceWith`
  (thanks to @jonathantneal).
* Parser no longer throws on sequential IDs and trailing commas, to support
  parsing of selector hacks.

# 1.0.1

* Fixes using `insertAfter` and `insertBefore` during iteration.

# 1.0.0

* Adds `clone` and `replaceWith` methods to nodes.
* Adds `insertBefore` and `insertAfter` to containers.
* Stabilises API.

# 0.0.5

* Fixes crash on extra whitespace inside a pseudo selector's parentheses.
* Adds sort function to the container class.
* Enables the parser to pass its input through without transforming.
* Iteration-safe `each` and `eachInside`.

# 0.0.4

* Tidy up redundant duplication.
* Fixes a bug where the parser would loop infinitely on universal selectors
  inside pseudo selectors.
* Adds `length` getter and `eachInside`, `map`, `reduce` to the container class.
* When a selector has been removed from the tree, the root node will no longer
  cast it to a string.
* Adds node type iterators to the container class (e.g. `eachComment`).
* Adds filter function to the container class.
* Adds split function to the container class.
* Create new node types by doing `parser.id(opts)` etc.
* Adds support for pseudo classes anywhere in the selector.

# 0.0.3

* Adds `next` and `prev` to the node class.
* Adds `first` and `last` getters to the container class.
* Adds `every` and `some` iterators to the container class.
* Add `empty` alias for `removeAll`.
* Combinators are now types of node.
* Fixes the at method so that it is not an alias for `index`.
* Tidy up creation of new nodes in the parser.
* Refactors how namespaces are handled for consistency & less redundant code.
* Refactors AST to use `nodes` exclusively, and eliminates excessive nesting.
* Fixes nested pseudo parsing.
* Fixes whitespace parsing.

# 0.0.2

* Adds support for namespace selectors.
* Adds support for selectors joined by escaped spaces - such as `.\31\ 0`.

# 0.0.1

* Initial release.


---

# postcss-selector-parser [![test](https://github.com/postcss/postcss-selector-parser/actions/workflows/test.yml/badge.svg)](https://github.com/postcss/postcss-selector-parser/actions/workflows/test.yml)

> Selector parser with built in methods for working with selector strings.

## Install

With [npm](https://npmjs.com/package/postcss-selector-parser) do:

```
npm install postcss-selector-parser
```

## Quick Start

```js
const parser = require('postcss-selector-parser');
const transform = selectors => {
    selectors.walk(selector => {
        // do something with the selector
        console.log(String(selector))
    });
};

const transformed = parser(transform).processSync('h1, h2, h3');
```

To normalize selector whitespace:

```js
const parser = require('postcss-selector-parser');
const normalized = parser().processSync('h1, h2, h3', {lossless: false});
// -> h1,h2,h3
```

Async support is provided through `parser.process` and will resolve a Promise
with the resulting selector string.

## API

Please see [API.md](API.md).

## Credits

* Huge thanks to Andrey Sitnik (@ai) for work on PostCSS which helped
  accelerate this module's development.

## License

MIT


---

# postcss-normalize-charset

Add necessary or remove extra charset with PostCSS

```css
a{
  content: "©";
}
```

```css
@charset "utf-8";
a{
  content: "©";
}
```

## API

### normalizeCharset([options])

#### options

##### add

Type: `boolean`  
Default: `true`

Pass `false` to stop the module from adding a `@charset` declaration if it was
missing from the file (and the file contained non-ascii characters).

## Usage

See the [PostCSS documentation](https://github.com/postcss/postcss#usage) for
examples for your environment.

## Contributors

See [CONTRIBUTORS.md](https://github.com/cssnano/cssnano/blob/master/CONTRIBUTORS.md).

## License

MIT © [Bogdan Chadkin](mailto:trysound@yandex.ru)


---

# [postcss][postcss]-normalize-display-values

> Normalize display property values with PostCSS.

## Install

With [npm](https://npmjs.org/package/postcss-normalize-display-values) do:

```
npm install postcss-normalize-display-values --save
```

## Example

### Input

```css
div {
    display: inline flow-root
}
```

### Output

```css
div {
    display: inline-block
}
``` 

## Usage

See the [PostCSS documentation](https://github.com/postcss/postcss#usage) for
examples for your environment.

## Contributors

See [CONTRIBUTORS.md](https://github.com/cssnano/cssnano/blob/master/CONTRIBUTORS.md).

## License

MIT © [Ben Briggs](http://beneb.info)

[postcss]: https://github.com/postcss/postcss


---

# [postcss][postcss]-normalize-positions

> Normalize positions with PostCSS.

## Install

With [npm](https://npmjs.org/package/postcss-normalize-positions) do:

```
npm install postcss-normalize-positions --save
```

## Example

### Input

```css
div {
    background-position: bottom left;
}
```

### Output

```css
div {
    background-position:0 100%;
}
``` 

## Usage

See the [PostCSS documentation](https://github.com/postcss/postcss#usage) for
examples for your environment.

## Contributors

See [CONTRIBUTORS.md](https://github.com/cssnano/cssnano/blob/master/CONTRIBUTORS.md).

## License

MIT © [Ben Briggs](http://beneb.info)

[postcss]: https://github.com/postcss/postcss


---

# [postcss][postcss]-normalize-repeat-style

> Normalize repeat styles with PostCSS.

## Install

With [npm](https://npmjs.org/package/postcss-normalize-repeat-style) do:

```
npm install postcss-normalize-repeat-style --save
```

## Example

### Input

```css
h1 {
    background: url(image.jpg) repeat no-repeat
}
```

### Output

```css
h1 {
    background: url(image.jpg) repeat-x
}
```

## Usage

See the [PostCSS documentation](https://github.com/postcss/postcss#usage) for
examples for your environment.

## Contributors

See [CONTRIBUTORS.md](https://github.com/cssnano/cssnano/blob/master/CONTRIBUTORS.md).

## License

MIT © [Ben Briggs](http://beneb.info)

[postcss]: https://github.com/postcss/postcss


---

# [postcss][postcss]-normalize-string

> Normalize strings with PostCSS.

## Install

With [npm](https://npmjs.org/package/postcss-normalize-string) do:

```
npm install postcss-normalize-string --save
```

## Example

### Input

```css
p:after{ content: '\\'string\\' is intact' }
```

### Output

```css
p:after{ content:"'string' is intact" }
```

## Usage

See the [PostCSS documentation](https://github.com/postcss/postcss#usage) for
examples for your environment.

## API

### normalize([options])

#### options

##### preferredQuote

Type: `string`
Default: `double`

Sets what type of quote to prefer. Possible values are `single` and `double`.

```js
var css = 'p:after{content:""}';
console.log(postcss(normalize({preferredQuote: 'single'})).process(css).css);
//=> p:after{content:''}
```

## Contributors

See [CONTRIBUTORS.md](https://github.com/cssnano/cssnano/blob/master/CONTRIBUTORS.md).

## License

MIT © [Ben Briggs](http://beneb.info)

[postcss]: https://github.com/postcss/postcss


---

# [postcss][postcss]-normalize-timing-functions

> Normalize timing functions with PostCSS.

## Install

With [npm](https://npmjs.org/package/postcss-normalize-timing-functions) do:

```
npm install postcss-normalize-timing-functions --save
```

## Example

### Input

```css
div {
    animate: fade 3s cubic-bezier(0.42, 0, 1, 1)
}
```

### Output

```css
div {
    animate: fade 3s ease-in
}
``` 

## Usage

See the [PostCSS documentation](https://github.com/postcss/postcss#usage) for
examples for your environment.

## Contributors

See [CONTRIBUTORS.md](https://github.com/cssnano/cssnano/blob/master/CONTRIBUTORS.md).

## License

MIT © [Ben Briggs](http://beneb.info)

[postcss]: https://github.com/postcss/postcss


---

# [postcss][postcss]-normalize-unicode

> Normalize unicode with PostCSS.

## Install

With [npm](https://npmjs.org/package/postcss-normalize-unicode) do:

```
npm install postcss-normalize-unicode --save
```

## Example

### Input

```css
@font-face{
    font-family: test;
    unicode-range: u+2b00-2bff
}
```

### Output

```css
@font-face{
    font-family: test;
    unicode-range: u+2b??
}
``` 

## Usage

See the [PostCSS documentation](https://github.com/postcss/postcss#usage) for
examples for your environment.

## Contributors

See [CONTRIBUTORS.md](https://github.com/cssnano/cssnano/blob/master/CONTRIBUTORS.md).

## License

MIT © [Ben Briggs](http://beneb.info)

[postcss]: https://github.com/postcss/postcss


---

# [postcss][postcss]-normalize-url

> [Normalize URLs](https://github.com/sindresorhus/normalize-url) with PostCSS.

## Install

With [npm](https://npmjs.org/package/postcss-normalize-url) do:

```
npm install postcss-normalize-url --save
```

## Example

### Input

```css
h1 {
    background: url("http://site.com:80/image.jpg")
}
```

### Output

```css
h1 {
    background: url(http://site.com/image.jpg)
}
```

Note that this module will also try to normalize relative URLs, and is capable
of stripping unnecessary quotes. For more examples, see the [tests](test/index.js).

## Usage

See the [PostCSS documentation](https://github.com/postcss/postcss#usage) for
examples for your environment.

## Contributors

See [CONTRIBUTORS.md](https://github.com/cssnano/cssnano/blob/master/CONTRIBUTORS.md).

## License

MIT © [Ben Briggs](http://beneb.info)

[docs]: https://github.com/sindresorhus/normalize-url#options
[postcss]: https://github.com/postcss/postcss


---

# [postcss][postcss]-normalize-whitespace

> Normalize whitespace with PostCSS.

## Install

With [npm](https://npmjs.org/package/postcss-normalize-whitespace) do:

```
npm install postcss-normalize-whitespace --save
```

## Example

### Input

```css
h1{
    width: calc(10px - ( 100px / var(--test) )) 
}
```

### Output

```css
h1{
    width: calc(10px - 100px / var(--test))
}
``` 

## Usage

See the [PostCSS documentation](https://github.com/postcss/postcss#usage) for
examples for your environment.

## Contributors

See [CONTRIBUTORS.md](https://github.com/cssnano/cssnano/blob/master/CONTRIBUTORS.md).

## License

MIT © [Ben Briggs](http://beneb.info)

[postcss]: https://github.com/postcss/postcss


---

# MIT License

Copyright (c) 2021 Marc Görtz <https://marcgoertz.de/>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


---

# PostCSS Opacity Percentage

[![Test](https://github.com/mrcgrtz/postcss-opacity-percentage/actions/workflows/test.yml/badge.svg)](https://github.com/mrcgrtz/postcss-opacity-percentage/actions/workflows/test.yml)
[![Coverage Status](https://coveralls.io/repos/github/mrcgrtz/postcss-opacity-percentage/badge.svg?branch=main)](https://coveralls.io/github/mrcgrtz/postcss-opacity-percentage?branch=main)
[![Install size](https://packagephobia.now.sh/badge?p=postcss-opacity-percentage)](https://packagephobia.now.sh/result?p=postcss-opacity-percentage)
[![XO code style](https://img.shields.io/badge/code_style-XO-5ed9c7.svg)](https://github.com/sindresorhus/xo)
[![MIT license](https://img.shields.io/github/license/mrcgrtz/postcss-opacity-percentage.svg)](https://github.com/mrcgrtz/postcss-opacity-percentage/blob/main/LICENSE.md)

[PostCSS](https://github.com/postcss/postcss) plugin to transform [percentage-based opacity values](https://www.w3.org/TR/css-color-4/#transparency) to more compatible floating-point values.

## Install

Using [npm](https://www.npmjs.com/get-npm):

```bash
npm install --save-dev postcss postcss-opacity-percentage
```

Using [yarn](https://yarnpkg.com/):

```bash
yarn add --dev postcss postcss-opacity-percentage
```

## Example

```css
/* Input */
.foo {
  opacity: 45%;
}
```

```css
/* Output */
.foo {
  opacity: 0.45;
}
```

## Usage

```js
postcss([
  require('postcss-opacity-percentage'),
]);
```

See [PostCSS](https://github.com/postcss/postcss) documentation for examples for your environment.

### `postcss-preset-env`

If you are using [`postcss-preset-env@>=7.3.0`](https://github.com/csstools/postcss-plugins/blob/main/plugin-packs/postcss-preset-env/CHANGELOG.md#730-january-31-2022), you already have this plugin installed via this package.

## Options

### `preserve`

The `preserve` option determines whether the original percentage value is preserved. By default, it is not preserved.

```js
// Keep the original notation
postcss([
  require('postcss-opacity-percentage')({preserve: true}),
]);
```

```css
/* Input */
.foo {
  opacity: 45%;
}
```

```css
/* Output */
.foo {
  opacity: 0.45;
  opacity: 45%;
}
```

## License

MIT © [Marc Görtz](https://marcgoertz.de/)


---

# [postcss][postcss]-ordered-values

> Ensure values are ordered consistently in your CSS.


## Install

With [npm](https://npmjs.org/package/postcss-ordered-values) do:

```
npm install postcss-ordered-values --save
```


## Example

Some CSS properties accept their values in an arbitrary order; for this reason,
it is entirely possible that different developers will write their values in
different orders. This module normalizes the order, making it easier for other
modules to understand which declarations are duplicates.

### Input

```css
h1 {
    border: solid 1px red;
    border: red solid .5em;
    border: rgba(0, 30, 105, 0.8) solid 1px;
    border: 1px solid red;
}
```

### Output

```css
h1 {
    border: 1px solid red;
    border: .5em solid red;
    border: 1px solid rgba(0, 30, 105, 0.8);
    border: 1px solid red;
}
```


## Support List

For more examples, see the [tests](src/__tests__/index.js).

* `animation`, `-webkit-animation`
* `border(border-left|right|top|bottom)`
* `box-shadow`
* `outline`
* `flex-flow`
* `transition`, `-webkit-transition`


## Usage

See the [PostCSS documentation](https://github.com/postcss/postcss#usage) for
examples for your environment.


## Contributors

See [CONTRIBUTORS.md](https://github.com/cssnano/cssnano/blob/master/CONTRIBUTORS.md).


## License

MIT © [Ben Briggs](http://beneb.info)

[postcss]: https://github.com/postcss/postcss


---

# Changes to PostCSS Overflow Shorthand

### 6.0.0

_August 3, 2024_

- Updated: Support for Node v18+ (major).

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-overflow-shorthand/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Overflow Shorthand [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install postcss-overflow-shorthand --save-dev`

[PostCSS Overflow Shorthand] lets you use the `overflow` shorthand in CSS,
following the [CSS Overflow] specification.

```pcss
html {
	overflow: hidden auto;
}

/* becomes */

html {
	overflow-x: hidden;
	overflow-y: auto;
	overflow: hidden auto;
}
```

## Usage

Add [PostCSS Overflow Shorthand] to your project:

```bash
npm install postcss postcss-overflow-shorthand --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssOverflowShorthand = require('postcss-overflow-shorthand');

postcss([
	postcssOverflowShorthand(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## Options

### preserve

The `preserve` option determines whether the original notation
is preserved. By default, it is preserved.

```js
postcssOverflowShorthand({ preserve: false })
```

```pcss
html {
	overflow: hidden auto;
}

/* becomes */

html {
	overflow-x: hidden;
	overflow-y: auto;
}
```

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#overflow-property
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/postcss-overflow-shorthand

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Overflow Shorthand]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-overflow-shorthand
[CSS Overflow]: https://drafts.csswg.org/css-overflow/#propdef-overflow


---

# Change Log
This project adheres to [Semantic Versioning](http://semver.org/).

## 3.0.3 - 2020-09-27
- Use `Declaration` event to work faster
- Fast check with `startsWith` before running slow regexp
- Avoid adding duplicate
Thanks to @ai

## 3.0.0  - 2020-09-20
* Updated: Support for PostCSS v8

## 2.0 - 2018-09-18
* Updated: Support for PostCSS v7

## 1.0
* Initial release


---

# postcss-page-break 

[![NPM Package][npm-img]][npm]
[![Build Status][ci-img]][ci]
[![License: MIT][mit-img]][mit]

[PostCSS] plugin to fallback `break-` properties with `page-break-` alias.

[!['Can I use' table](https://caniuse.bitsofco.de/image/multicolumn.png)](https://caniuse.com/#feat=multicolumn)

[PostCSS]: https://github.com/postcss/postcss
[npm-img]: https://img.shields.io/npm/v/postcss-page-break.svg
[npm]:     https://www.npmjs.org/package/postcss-page-break
[ci-img]:  https://travis-ci.org/shrpne/postcss-page-break.svg
[ci]:      https://travis-ci.org/shrpne/postcss-page-break
[mit-img]: https://img.shields.io/badge/License-MIT-yellow.svg
[mit]:     https://github.com/shrpne/postcss-page-break/blob/master/LICENSE

```css
/* before */
.foo {
  break-inside: avoid;
  break-after: page;
}

/* after */
.foo {
  page-break-inside: avoid;
  break-inside: avoid;
  page-break-after: always;
  break-after: page;
}
```

Available fallbacks:
```
break-inside: auto        =>  page-break-inside: auto
break-inside: avoid       =>  page-break-inside: avoid
break-inside: avoid-page  =>  page-break-inside: avoid
break-inside: inherit     =>  page-break-inside: inherit
break-inside: initial     =>  page-break-inside: initial
break-inside: unset       =>  page-break-inside: unset

break-before: auto        =>  page-break-before: auto;
break-before: avoid       =>  page-break-before: avoid;
break-before: avoid-page  =>  page-break-before: avoid;
break-before: page        =>  page-break-before: always;
break-before: always      =>  page-break-before: always;
break-before: left        =>  page-break-before: left;
break-before: right       =>  page-break-before: right;
break-before: recto       =>  page-break-before: recto;
break-before: verso       =>  page-break-before: verso;
break-before: inherit     =>  page-break-before: inherit;
break-before: initial     =>  page-break-before: initial;
break-before: unset       =>  page-break-before: unset;

break-after: auto         =>  page-break-after: auto;
break-after: avoid        =>  page-break-after: avoid;
break-after: avoid-page   =>  page-break-after: avoid;
break-after: page         =>  page-break-after: always;
break-after: always       =>  page-break-after: always;
break-after: left         =>  page-break-after: left;
break-after: right        =>  page-break-after: right;
break-after: recto        =>  page-break-after: recto;
break-after: verso        =>  page-break-after: verso;
break-after: inherit      =>  page-break-after: inherit;
break-after: initial      =>  page-break-after: initial;
break-after: unset        =>  page-break-after: unset;
```

## Installation
```bash
npm install --save-dev postcss postcss-page-break
```


## Usage

```js
postcss([ require('postcss-page-break') ])
```

See [PostCSS] docs for examples for your environment (webpack, gulp, grunt).


---

# Changes to PostCSS Place Properties

### 10.0.0

_August 3, 2024_

- Updated: Support for Node v18+ (major).

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-place/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Place Properties [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install postcss-place --save-dev`

[PostCSS Place Properties] lets you use `place-*` properties as shorthands for `align-*`
and `justify-*`, following the [CSS Box Alignment] specification.

```pcss
.example {
	place-self: center;
	place-content: space-between center;
}

/* becomes */

.example {
	align-self: center;
	justify-self: center;
	place-self: center;
	align-content: space-between;
	justify-content: center;
	place-content: space-between center;
}
```

## Usage

Add [PostCSS Place Properties] to your project:

```bash
npm install postcss postcss-place --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssPlace = require('postcss-place');

postcss([
	postcssPlace(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## Options

### preserve

The `preserve` option determines whether the original notation
is preserved. By default, it is preserved.

```js
postcssPlace({ preserve: false })
```

```pcss
.example {
	place-self: center;
	place-content: space-between center;
}

/* becomes */

.example {
	align-self: center;
	justify-self: center;
	align-content: space-between;
	justify-content: center;
}
```

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#place-properties
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/postcss-place

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Place Properties]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-place
[CSS Box Alignment]: https://www.w3.org/TR/css-align-3/#place-content


---

# Changes to PostCSS Preset Env

### 10.1.5

_February 23, 2025_

- Updated [`postcss-logical`](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-logical) to [`8.1.0`](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-logical/CHANGELOG.md#810) (minor)
- Updated [`@csstools/color-helpers`](https://github.com/csstools/postcss-plugins/tree/main/packages/color-helpers) to [`5.0.2`](https://github.com/csstools/postcss-plugins/tree/main/packages/color-helpers/CHANGELOG.md#502) (patch)
- Updated [`@csstools/css-calc`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-calc) to [`2.1.2`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-calc/CHANGELOG.md#212) (patch)
- Updated [`@csstools/css-color-parser`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-color-parser) to [`3.0.8`](https://github.com/csstools/postcss-plugins/tree/main/packages/css-color-parser/CHANGELOG.md#308) (patch)

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugin-packs/postcss-preset-env/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Preset Env [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS" width="90" height="90" align="right">][postcss]

[<img alt="npm version" src="https://img.shields.io/npm/v/postcss-preset-env.svg" height="20">][npm-url]
[<img alt="build status" src="https://github.com/csstools/postcss-plugins/workflows/test/badge.svg" height="20">][cli-url]
[![install size][package-phobia-badge]][package-phobia]
[<img alt="Discord" src="https://shields.io/badge/Discord-5865F2?logo=discord&logoColor=white">][discord]

[PostCSS Preset Env] lets you convert modern CSS into something most browsers
can understand, determining the polyfills you need based on your targeted
browsers or runtime environments.

## Quick start

[PostCSS Preset Env] is a [PostCSS] plugin.<br>
If you are already using [PostCSS] to build your CSS, you can simply add [PostCSS Preset Env] to your configuration.

- Install `postcss-preset-env` from npm.
- Add `postcss-preset-env` to your configuration.
- Explore the [features list](https://github.com/csstools/postcss-plugins/blob/main/plugin-packs/postcss-preset-env/FEATURES.md).

```js
const postcssPresetEnv = require('postcss-preset-env');

const yourConfig = {
	plugins: [
		/* other plugins */
		/* remove autoprefixer if you had it here, it's part of postcss-preset-env */
		postcssPresetEnv({
			/* pluginOptions */
			features: {},
		})
	]
}
```

_[Read more on how to use and install PostCSS Preset Env.](#usage)_

## How does it work?

[PostCSS Preset Env] is a Plugin Pack for [PostCSS]. It leverages the list of the features we keep an eye from [CSSDB][cssdb] and applies plugins, so you can use those new features without having to worry about browser support.

CSSDB exposes the browser support that each feature has which can come from [Can I Use](https://caniuse.com/css-all) or from [MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/all) (through [mdn/browser-compat-data](https://github.com/mdn/browser-compat-data)).

By providing a list of browser targets for your project, plugins that aren't needed will be skipped. Over time your targets might change and by updating the settings your CSS bundle will only ever contain the needed fallbacks.

What [PostCSS Preset Env] does is to take the support data that comes from MDN and Can I Use and determine from a [browserslist](https://github.com/browserslist/browserslist) whether those transformations are needed. It also packs [Autoprefixer](https://github.com/postcss/autoprefixer) within and shares the list with it, so prefixes are only applied when you're going to need them given your browser support list.

### Glossary:

* **Browser list option**: [Browserslist](https://github.com/browserslist/browserslist) is a package that gives you a list of browsers for a given query. For example, `chrome < 42` will give you a list of every Chrome version that has been released up to, but not including, 42.
* **Browser support stats**: Features get introduced on browsers at certain versions. They're often visible on [MDN](https://developer.mozilla.org/en-US/) and [Can I Use](https://caniuse.com/). Comparing these stats with the needed _support_ for your project tells you if it's safe to use a feature or not.
* **CSS Feature**: A CSS feature is often part of some spec that enables a specific feature. For example, `hwb` functional notation lets you express a given color according to its hue, whiteness, and blackness. This is part of the CSS Color 4 Spec.
* **CSS Spec**: A Spec is a document that collects new features, what problems are they trying to solve and how it's intended to be solved (generally). This is usually an evolving document that goes over lengthy discussions between several people from different companies.
* **Plugin**: A plugin is package that's intended (usually) to enable a new CSS Feature by leveraging PostCSS. This doesn't need to be part of any spec. An example of the latter is [PostCSS Mixins](https://github.com/postcss/postcss-mixins), a concept that existed on Less or Sass, but it's not part of any spec. This plugin pack **only** packs plugins that enable features acknowledged by the World Wide Web Consortium (W3C) which will then be implemented by browsers later.
* **Polyfill**: A polyfill is a piece of code (usually JavaScript on the Web) used to provide modern functionality on older browsers that do not natively support it. A polyfill _should_ be indistinguishable from the native behaviour.

Here's a quick example of the syntax you can leverage by using [PostCSS Preset Env].

```css
@custom-media --viewport-medium (width <= 50rem);
@custom-selector :--heading h1, h2, h3, h4, h5, h6;

:root {
  --mainColor: #12345678;
}

body {
  color: var(--mainColor);
  font-family: system-ui;
  overflow-wrap: break-word;
}

:--heading {
  background-image: image-set(url(img/heading.png) 1x, url(img/heading@2x.png) 2x);

  @media (--viewport-medium) {
    margin-block: 0;
  }
}

a {
  color: rgb(0 0 100% / 90%);

  &:hover {
    color: rebeccapurple;
  }
}

/* becomes */

:root {
  --mainColor: rgba(18, 52, 86, 0.47059);
}

body {
  color: rgba(18, 52, 86, 0.47059);
  color: var(--mainColor);
  font-family: system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Oxygen, Ubuntu, Cantarell, Droid Sans, Helvetica Neue;
  word-wrap: break-word;
}

h1, h2, h3, h4, h5, h6 {
  background-image: url(img/heading.png);
}

@media (-webkit-min-device-pixel-ratio: 2), (min-resolution: 192dpi) {
  h1, h2, h3, h4, h5, h6 {
    background-image: url(img/heading@2x.png)
  }
}

@media (max-width: 50rem) {
  h1, h2, h3, h4, h5, h6 {
    margin-top: 0;
    margin-bottom: 0;
  }
}

a {
  color: rgba(0, 0, 255, 0.9)
}

a:hover {
  color: #639;
}
```

Without any configuration options, [PostCSS Preset Env] enables **Stage 2**
features and supports **all** browsers.

[**Try it out in the Playground!**](https://preset-env.cssdb.org/playground/)

> [!NOTE]
> Please note that some features need a companion library that makes the feature work. While we try to avoid this requirement, there are instances in which this isn't possible to polyfill a new behaviour with _just_ CSS.

[See the list below](#plugins-that-need-client-library).

## Usage

Add [PostCSS Preset Env] to your project:

```bash
npm install postcss-preset-env --save-dev
```

Use [PostCSS Preset Env] as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssPresetEnv = require('postcss-preset-env');

postcss([
  postcssPresetEnv(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```

[PostCSS Preset Env] runs in all Node environments, with special instructions for:

- [Node](INSTALL.md#node)
- [PostCSS CLI](INSTALL.md#postcss-cli)
- [PostCSS Load Config](INSTALL.md#postcss-load-config)
- [Webpack](INSTALL.md#webpack)
- [Next.js](INSTALL.md#nextjs)
- [Gulp](INSTALL.md#gulp)
- [Grunt](INSTALL.md#grunt)

### Position in your PostCSS plugins list

[PostCSS Preset Env] only contains polyfills and fallbacks for standard CSS features and is unable to handle non-standard features and syntactic sugar.

If you also have PostCSS plugins for non-standard features and syntactic sugar,  
you should place these first in the PostCSS plugins list.

```js
module.exports = {
	plugins: [
		"postcss-syntactic-sugar",
		"postcss-non-standard",
		// ...
		[
			"postcss-preset-env",
			{
				// plugin options
			},
		],
		// ...
		// maybe a minifier?
	],
};
```

You can also use the [`insertBefore` / `insertAfter`](#insertbefore--insertafter) plugin options for more fine grained control.

## Options

### stage

The `stage` option determines which CSS features to polyfill, based upon their
stability in the process of becoming implemented web standards.

```js
postcssPresetEnv({ stage: 0 })
```

The `stage` can be `0` (experimental) through `4` (stable), or `false`. Setting
`stage` to `false` will disable every polyfill. Doing this would only be useful
if you intended to exclusively use the [`features`](#features) option.

Default: `2`

**It is very rare for features to progress beyond stage `2`.**  
**Use `minimumVendorImplementations` if you prefer to keep up with modern features.**

### minimumVendorImplementations

The `minimumVendorImplementations` option determines which CSS features to polyfill, based their implementation status.
This can be used to enable plugins that are available in browsers regardless of the [spec status](#stage).

```js
postcssPresetEnv({ minimumVendorImplementations: 2 })
```

`minimumVendorImplementations` can be `0` (no vendor has implemented it) through `3` (all major vendors).<br>

Default: `0`

**Note:**

When a feature has not yet been implemented by any vendor it can be considered experimental.<br>
Even with a single implementation it might still change in the future.<br>
Sometimes issues with a feature/specification are only discovered after it becomes available.

A value of `2` is recommended when you want to use only those features that should be [stable](#stability-and-portability).

Having 2 independent implementations is [a critical step in proposals becoming standards](https://www.w3.org/2021/Process-20211102/#implementation-experience) and a good indicator of a feature's stability.

### features

The `features` option enables or disables specific polyfills by ID. Passing
`true` to a specific feature ID will enable its polyfill, while passing `false`
will disable it. [List of Features](https://github.com/csstools/postcss-plugins/blob/main/plugin-packs/postcss-preset-env/FEATURES.md)

```js
postcssPresetEnv({
  /* use stage 3 features + css nesting rules */
  stage: 3,
  features: {
    'nesting-rules': true
  }
})
```

Passing an object to a specific feature ID will both enable and configure it.

```js
postcssPresetEnv({
  /* use stage 3 features + custom-selectors (preserving the original CSS) */
  stage: 3,
  features: {
    'custom-selectors': { preserve: true }
  }
})
```

If you want to preserve automatic enabling of features  
based on the stage, implementations and or browserslist,  
you can pass an array: `['auto', { /* plugin options */ }]`.

```js
postcssPresetEnv({
  /* use stage 3 features + custom-selectors (preserving the original CSS) */
  stage: 3,
  features: {
    'custom-selectors': ['auto', { preserve: true }]
  }
})
```

Any polyfills not explicitly enabled or disabled through `features` are
determined by the [`stage`](#stage) option.

### env

[PostCSS Preset Env] supports standard [browserslist] configuration, which can
be a `.browserslistrc` file, a `browserslist` key in `package.json`, or
`browserslist` environment variables.

The `env` option is used by [browserslist] to determine the named environment
that should be used when you have [multiple browserslist environments](https://github.com/browserslist/browserslist#configuring-for-different-environments)
configured. If not set, Browserslist will use the `production` environment.

```js
/* use the environment named `development`, instead of the default environment of `production` */
postcssPresetEnv({ env: 'development' })
```

### browsers

The `browsers` option overrides any existing [browserslist] configuration.

The `browsers` option should only be used when a standard browserslist
configuration is not available.  
When the `browsers` option is used the `env` option will be ignored.

```js
postcssPresetEnv({ browsers: 'last 2 versions' })
```

If no valid browserslist configuration is specified, the
[default browserslist query](https://github.com/browserslist/browserslist#queries)
will be used.

### insertBefore / insertAfter

The `insertBefore` and `insertAfter` keys allow you to insert other PostCSS
plugins into the chain. This is only useful if you are also using sugary
PostCSS plugins that must execute before or after certain polyfills.
Both `insertBefore` and `insertAfter` support chaining one or multiple plugins.

```js
import postcssSimpleVars from 'postcss-simple-vars';

postcssPresetEnv({
  insertBefore: {
    'all-property': postcssSimpleVars
  }
})
```

### autoprefixer

[PostCSS Preset Env] includes [autoprefixer]; the [`env`](#env) and [`browsers`](#browsers) options will be passed to it automatically.

Specifying the `autoprefixer` option enables passing
[additional options](https://github.com/postcss/autoprefixer#options)
into [autoprefixer].

```js
postcssPresetEnv({
  autoprefixer: { grid: true }
})
```

Passing `autoprefixer: false` disables autoprefixer.

⚠️ [autoprefixer] has [complex logic to fix CSS Grid in IE and older Edge](https://github.com/postcss/autoprefixer#grid-autoplacement-support-in-ie).

This can have unexpected results with certain features and when [`preserve: true`](#preserve) is used. (defaults to `true`)

```css
:root {
  --grid-gap: 15px;
}

.test-grid {
	grid-gap: var(--grid-gap);
	grid-template-columns: repeat(2, 1fr);
}
```

Becomes :

```
.test-grid {
	grid-gap: 15px;
	grid-gap: var(--grid-gap);
	-ms-grid-columns: 1fr var(--grid-gap) 1fr;
	grid-template-columns: repeat(2, 1fr);
}
```

The prefixed `-ms-grid-columns` still has a custom property: `1fr var(--grid-gap) 1fr;` which won't work.<br />
This example shows issues with custom properties but other transforms might have similar issues.

If you target IE or older Edge it is best to avoid using other modern features in grid property values.<br />
As a last resort you can set [`preserve: false`](#preserve), we do not advice this as doing so purely to fix issues with CSS grid.

_older Edge is any version before chromium (<79)_

### preserve

The `preserve` option determines whether all plugins should receive a
`preserve` option, which may preserve or remove otherwise-polyfilled CSS. By
default, this option is not configured.

```js
postcssPresetEnv({
  preserve: false // instruct all plugins to omit pre-polyfilled CSS
});
```

### debug

The `debug` option enables debugging messages to stdout which should be useful to help you debug which features have been enabled/disabled and why.

### enableClientSidePolyfills

The `enableClientSidePolyfills` enables all features that also need an extra browser library to be loaded into the page for it to work. Defaults to `false`.

- Note that manually enabling/disabling features via the "feature" option overrides this flag.
- This only controls if the PostCSS plugins are enabled. It does not cause the browsers libraries to be included in your bundle.

### logical

The `logical` option can hold an object which lets you specify direction of the inline and block axes and will affect the
following features:

- `logical-properties-and-values`: [PostCSS Logical](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-logical#readme)
- `float-clear-logical-values`: [PostCSS Logical Float And Clear](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-logical#readme)
- `logical-resize`: [PostCSS Logical Resize](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-logical-resize#readme)
- `logical-viewport-units`: [PostCSS Logical Viewport Units](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-logical-viewport-units#readme)

It should have `blockDirection` and/or `inlineDirection` which can be any of the following:

- `top-to-bottom`
- `bottom-to-top`
- `left-to-right`
- `right-to-left`

```js
postcssPresetEnv({
  logical: { // instruct all logical plugins to set inline axis to right to left
		inlineDirection: 'right-to-left',
	},
});
```

```css
.element {
	float: inline-start;
	padding-inline-end: 10px;
}
```

Becomes :

```
.element {
	float: right;
	padding-left: 10px;
}
```

You can't mix two vertical directions or two horizontal directions so for example `top-to-bottom` and `right-to-left` are valid, but `top-to-bottom` and `bottom-to-top` are not.

You might want to tweak these values if you are using a different writing system, such as Arabic, Hebrew or Chinese for example.

## Stability and Portability

[PostCSS Preset Env] will often include very modern CSS features that are not fully ready yet.
This gives users the chance to play around with these features and provide feedback.

If the specification changes or is abandoned a new major version of the plugin will be released.
This will require you to update your source code so that everything works as expected.

To have more stability between updates of [PostCSS Preset Env] you may set `stage: 3` and/or `minimumVendorImplementations: 2`.

A side effect of staying close to the standard is that you can more easily migrate your project to other tooling all together.

## Plugins list

### Plugins that need client library

This is the current list of features that need a client library with a link
to the polyfill's library.

* `blank-pseudo-class`: [Plugin](https://github.com/csstools/postcss-plugins/blob/main/plugins/css-blank-pseudo) / [Polyfill](https://github.com/csstools/postcss-plugins/blob/main/plugins/css-blank-pseudo#browser)
* `focus-visible-pseudo-class`: [Plugin](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-focus-visible) / [Polyfill](https://github.com/WICG/focus-visible)
* `focus-within-pseudo-class`: [Plugin](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-focus-within) / [Polyfill](https://github.com/csstools/postcss-plugins/blob/main/plugins/postcss-focus-within#browser)
* `has-pseudo-class`: [Plugin](https://github.com/csstools/postcss-plugins/blob/main/plugins/css-has-pseudo) / [Polyfill](https://github.com/csstools/postcss-plugins/blob/main/plugins/css-has-pseudo#browser)
* `prefers-color-scheme-query`: [Plugin](https://github.com/csstools/postcss-plugins/blob/main/plugins/css-prefers-color-scheme) / [Polyfill](https://github.com/csstools/postcss-plugins/blob/main/plugins/css-prefers-color-scheme#browser)

If you want to enable all these types of features, please check the [`enableClientSidePolyfills` option](#enableclientsidepolyfills).

### Plugins not affected by Browser Support

Given they have no support they will always be enabled if they match by Stage:

* `blank-pseudo-class`: [Plugin](https://github.com/csstools/postcss-plugins/blob/main/plugins/css-blank-pseudo) / [Polyfill](https://github.com/csstools/postcss-plugins/blob/main/plugins/css-blank-pseudo#browser)
* `custom-media-queries`: [Plugin](https://github.com/postcss/postcss-custom-media)
* `nesting-rules`: [Plugin](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-nesting)

[cli-img]: https://github.com/csstools/postcss-plugins/workflows/test/badge.svg
[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[discord]: https://discord.gg/bUadyRwkJS
[npm-img]: https://img.shields.io/npm/v/postcss-preset-env.svg
[npm-url]: https://www.npmjs.com/package/postcss-preset-env
[package-phobia-badge]: https://packagephobia.com/badge?p=postcss-preset-env
[package-phobia]: https://packagephobia.com/result?p=postcss-preset-env

[autoprefixer]: https://github.com/postcss/autoprefixer
[browserslist]: https://github.com/browserslist/browserslist#readme
[caniuse]: https://caniuse.com/
[cssdb]: https://cssdb.org/
[PostCSS]: https://github.com/postcss/postcss
[PostCSS Preset Env]: https://github.com/csstools/postcss-plugins/tree/main/plugin-packs/postcss-preset-env


---

# Changes to PostCSS Pseudo Class Any Link

### 10.0.1

_October 23, 2024_

- Updated: `postcss-selector-parser`

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-pseudo-class-any-link/CHANGELOG.md)


---

MIT No Attribution (MIT-0)

Copyright © CSSTools Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# PostCSS Pseudo Class Any Link [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install postcss-pseudo-class-any-link --save-dev`

[PostCSS Pseudo Class Any Link] lets you `:any-link` pseudo-class in CSS,
following the [Selectors] specification.

```pcss
nav :any-link > span {
	background-color: yellow;
}

/* becomes */

nav :link > span, nav :visited > span {
	background-color: yellow;
}
nav :any-link > span {
	background-color: yellow;
}
```

## Usage

Add [PostCSS Pseudo Class Any Link] to your project:

```bash
npm install postcss postcss-pseudo-class-any-link --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssPseudoClassAnyLink = require('postcss-pseudo-class-any-link');

postcss([
	postcssPseudoClassAnyLink(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## Options

### preserve

The `preserve` option determines whether the original notation
is preserved. By default, it is preserved.

```js
postcssPseudoClassAnyLink({ preserve: false })
```

```pcss
nav :any-link > span {
	background-color: yellow;
}

/* becomes */

nav :link > span, nav :visited > span {
	background-color: yellow;
}
```

### subFeatures

#### areaHrefNeedsFixing

The `subFeatures.areaHrefNeedsFixing` option determines if `<area href>` elements should match `:any-link` pseudo-class.<br>
In IE and Edge these do not match `:link` or `:visited`.

_This increased CSS bundle size and is disabled by default._

```js
postcssPseudoClassAnyLink({
	subFeatures: {
		areaHrefNeedsFixing: true
	}
})
```

```pcss
nav :any-link > span {
	background-color: yellow;
}

/* becomes */

nav :link > span, nav :visited > span, nav area[href] > span {
	background-color: yellow;
}
nav :any-link > span {
	background-color: yellow;
}
```

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#any-link-pseudo-class
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/postcss-pseudo-class-any-link

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Pseudo Class Any Link]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-pseudo-class-any-link
[Selectors]: https://www.w3.org/TR/selectors-4/#the-any-link-pseudo


---

# API Documentation

*Please use only this documented API when working with the parser. Methods
not documented here are subject to change at any point.*

## `parser` function

This is the module's main entry point.

```js
const parser = require('postcss-selector-parser');
```

### `parser([transform], [options])`

Creates a new `processor` instance

```js
const processor = parser();
```

Or, with optional transform function

```js
const transform = selectors => {
    selectors.walkUniversals(selector => {
        selector.remove();
    });
};

const processor = parser(transform)

// Example
const result = processor.processSync('*.class');
// => .class
```

[See processor documentation](#processor)

Arguments:

* `transform (function)`: Provide a function to work with the parsed AST.
* `options (object)`: Provide default options for all calls on the returned `Processor`.

### `parser.attribute([props])`

Creates a new attribute selector.

```js
parser.attribute({attribute: 'href'});
// => [href]
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.className([props])`

Creates a new class selector.

```js
parser.className({value: 'button'});
// => .button
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.combinator([props])`

Creates a new selector combinator.

```js
parser.combinator({value: '+'});
// => +
```

Arguments:

* `props (object)`: The new node's properties.

Notes:
* **Descendant Combinators** The value of descendant combinators created by the
  parser always just a single space (`" "`). For descendant selectors with no
  comments, additional space is now stored in `node.spaces.before`. Depending
  on the location of comments, additional spaces may be stored in
  `node.raws.spaces.before`, `node.raws.spaces.after`, or `node.raws.value`.
* **Named Combinators** Although, nonstandard and unlikely to ever become a standard,
  named combinators like `/deep/` and `/for/` are parsed as combinators. The
  `node.value` is name after being unescaped and normalized as lowercase. The
  original value for the combinator name is stored in `node.raws.value`.


### `parser.comment([props])`

Creates a new comment.

```js
parser.comment({value: '/* Affirmative, Dave. I read you. */'});
// => /* Affirmative, Dave. I read you. */
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.id([props])`

Creates a new id selector.

```js
parser.id({value: 'search'});
// => #search
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.nesting([props])`

Creates a new nesting selector.

```js
parser.nesting();
// => &
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.pseudo([props])`

Creates a new pseudo selector.

```js
parser.pseudo({value: '::before'});
// => ::before
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.root([props])`

Creates a new root node.

```js
parser.root();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.selector([props])`

Creates a new selector node.

```js
parser.selector();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.string([props])`

Creates a new string node.

```js
parser.string();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.tag([props])`

Creates a new tag selector.

```js
parser.tag({value: 'button'});
// => button
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.universal([props])`

Creates a new universal selector.

```js
parser.universal();
// => *
```

Arguments:

* `props (object)`: The new node's properties.

## Node types

### `node.type`

A string representation of the selector type. It can be one of the following;
`attribute`, `class`, `combinator`, `comment`, `id`, `nesting`, `pseudo`,
`root`, `selector`, `string`, `tag`, or `universal`. Note that for convenience,
these constants are exposed on the main `parser` as uppercased keys. So for
example you can get `id` by querying `parser.ID`.

```js
parser.attribute({attribute: 'href'}).type;
// => 'attribute'
```

### `node.parent`

Returns the parent node.

```js
root.nodes[0].parent === root;
```

### `node.toString()`, `String(node)`, or `'' + node`

Returns a string representation of the node.

```js
const id = parser.id({value: 'search'});
console.log(String(id));
// => #search
```

### `node.next()` & `node.prev()`

Returns the next/previous child of the parent node.

```js
const next = id.next();
if (next && next.type !== 'combinator') {
    throw new Error('Qualified IDs are not allowed!');
}
```

### `node.replaceWith(node[,...nodeN])`

Replace a node with another.

```js
const attr = selectors.first.first;
const className = parser.className({value: 'test'});
attr.replaceWith(className);
```

Arguments:

* `node`: The node to substitute the original with.
...
* `nodeN`: The node to substitute the original with.

### `node.remove()`

Removes the node from its parent node.

```js
if (node.type === 'id') {
    node.remove();
}
```

### `node.clone([opts])`

Returns a copy of a node, detached from any parent containers that the
original might have had.

```js
const cloned = node.clone();
```

### `node.isAtPosition(line, column)`

Return a `boolean` indicating whether this node includes the character at the
position of the given line and column. Returns `undefined` if the nodes lack
sufficient source metadata to determine the position.

Arguments:

* `line`: 1-index based line number relative to the start of the selector.
* `column`: 1-index based column number relative to the start of the selector.

### `node.spaces`

Extra whitespaces around the node will be moved into `node.spaces.before` and
`node.spaces.after`. So for example, these spaces will be moved as they have
no semantic meaning:

```css
      h1     ,     h2   {}
```

For descendent selectors, the value is always a single space.

```css
h1        h2 {}
```

Additional whitespace is found in either the `node.spaces.before` and `node.spaces.after` depending on the presence of comments or other whitespace characters. If the actual whitespace does not start or end with a single space, the node's raw value is set to the actual space(s) found in the source.

### `node.source`

An object describing the node's start/end, line/column source position.

Within the following CSS, the `.bar` class node ...

```css
.foo,
  .bar {}
```

... will contain the following `source` object.

```js
source: {
    start: {
        line: 2,
        column: 3
    },
    end: {
        line: 2,
        column: 6
    }
}
```

### `node.sourceIndex`

The zero-based index of the node within the original source string.

Within the following CSS, the `.baz` class node will have a `sourceIndex` of `12`.

```css
.foo, .bar, .baz {}
```

## Container types

The `root`, `selector`, and `pseudo` nodes have some helper methods for working
with their children.

### `container.nodes`

An array of the container's children.

```js
// Input: h1 h2
selectors.at(0).nodes.length   // => 3
selectors.at(0).nodes[0].value // => 'h1'
selectors.at(0).nodes[1].value // => ' '
```

### `container.first` & `container.last`

The first/last child of the container.

```js
selector.first === selector.nodes[0];
selector.last === selector.nodes[selector.nodes.length - 1];
```

### `container.at(index)`

Returns the node at position `index`.

```js
selector.at(0) === selector.first;
selector.at(0) === selector.nodes[0];
```

Arguments:

* `index`: The index of the node to return.

### `container.atPosition(line, column)`

Returns the node at the source position `line` and `column`.

```js
// Input: :not(.foo),\n#foo > :matches(ol, ul)
selector.atPosition(1, 1); // => :not(.foo)
selector.atPosition(2, 1); // => \n#foo
```

Arguments:

* `line`: The line number of the node to return.
* `column`: The column number of the node to return.

### `container.index(node)`

Return the index of the node within its container.

```js
selector.index(selector.nodes[2]) // => 2
```

Arguments:

* `node`: A node within the current container.

### `container.length`

Proxy to the length of the container's nodes.

```js
container.length === container.nodes.length
```

### `container` Array iterators

The container class provides proxies to certain Array methods; these are:

* `container.map === container.nodes.map`
* `container.reduce === container.nodes.reduce`
* `container.every === container.nodes.every`
* `container.some === container.nodes.some`
* `container.filter === container.nodes.filter`
* `container.sort === container.nodes.sort`

Note that these methods only work on a container's immediate children; recursive
iteration is provided by `container.walk`.

### `container.each(callback)`

Iterate the container's immediate children, calling `callback` for each child.
You may return `false` within the callback to break the iteration.

```js
let className;
selectors.each((selector, index) => {
    if (selector.type === 'class') {
        className = selector.value;
        return false;
    }
});
```

Note that unlike `Array#forEach()`, this iterator is safe to use whilst adding
or removing nodes from the container.

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  and `index` arguments.

### `container.walk(callback)`

Like `container#each`, but will also iterate child nodes as long as they are
`container` types.

```js
selectors.walk((selector, index) => {
    // all nodes
});
```

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  and `index` arguments.

This iterator is safe to use whilst mutating `container.nodes`,
like `container#each`.

### `container.walk` proxies

The container class provides proxy methods for iterating over types of nodes,
so that it is easier to write modules that target specific selectors. Those
methods are:

* `container.walkAttributes`
* `container.walkClasses`
* `container.walkCombinators`
* `container.walkComments`
* `container.walkIds`
* `container.walkNesting`
* `container.walkPseudos`
* `container.walkTags`
* `container.walkUniversals`

### `container.split(callback)`

This method allows you to split a group of nodes by returning `true` from
a callback. It returns an array of arrays, where each inner array corresponds
to the groups that you created via the callback.

```js
// (input) => h1 h2>>h3
const list = selectors.first.split(selector => {
    return selector.type === 'combinator';
});

// (node values) => [['h1', ' '], ['h2', '>>'], ['h3']]
```

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  as an argument.

### `container.prepend(node)` & `container.append(node)`

Add a node to the start/end of the container. Note that doing so will set
the parent property of the node to this container.

```js
const id = parser.id({value: 'search'});
selector.append(id);
```

Arguments:

* `node`: The node to add.

### `container.insertBefore(old, new[, ...newNodes])` & `container.insertAfter(old, new[, ...newNodes])`

Add a node before or after an existing node in a container:

```js
selectors.walk(selector => {
    if (selector.type !== 'class') {
        const className = parser.className({value: 'theme-name'});
        selector.parent.insertAfter(selector, className);
    }
});
```

Arguments:

* `old`: The existing node in the container.
* `new`: The new node to add before/after the existing node.

### `container.removeChild(node)`

Remove the node from the container. Note that you can also use
`node.remove()` if you would like to remove just a single node.

```js
selector.length // => 2
selector.remove(id)
selector.length // => 1;
id.parent       // undefined
```

Arguments:

* `node`: The node to remove.

### `container.removeAll()` or `container.empty()`

Remove all children from the container.

```js
selector.removeAll();
selector.length // => 0
```

## Root nodes

A root node represents a comma separated list of selectors. Indeed, all
a root's `toString()` method does is join its selector children with a ','.
Other than this, it has no special functionality and acts like a container.

### `root.trailingComma`

This will be set to `true` if the input has a trailing comma, in order to
support parsing of legacy CSS hacks.

## Selector nodes

A selector node represents a single complex selector. For example, this
selector string `h1 h2 h3, [href] > p`, is represented as two selector nodes.
It has no special functionality of its own.

## Pseudo nodes

A pseudo selector extends a container node; if it has any parameters of its
own (such as `h1:not(h2, h3)`), they will be its children. Note that the pseudo
`value` will always contain the colons preceding the pseudo identifier. This
is so that both `:before` and `::before` are properly represented in the AST.

## Attribute nodes

### `attribute.quoted`

Returns `true` if the attribute's value is wrapped in quotation marks, false if it is not.
Remains `undefined` if there is no attribute value.

```css
[href=foo] /* false */
[href='foo'] /* true */
[href="foo"] /* true */
[href] /* undefined */
```

### `attribute.qualifiedAttribute`

Returns the attribute name qualified with the namespace if one is given.

### `attribute.offsetOf(part)`

 Returns the offset of the attribute part specified relative to the
 start of the node of the output string. This is useful in raising
 error messages about a specific part of the attribute, especially
 in combination with `attribute.sourceIndex`.

 Returns `-1` if the name is invalid or the value doesn't exist in this
 attribute.

 The legal values for `part` are:

 * `"ns"` - alias for "namespace"
 * `"namespace"` - the namespace if it exists.
 * `"attribute"` - the attribute name
 * `"attributeNS"` - the start of the attribute or its namespace
 * `"operator"` - the match operator of the attribute
 * `"value"` - The value (string or identifier)
 * `"insensitive"` - the case insensitivity flag

### `attribute.raws.unquoted`

Returns the unquoted content of the attribute's value.
Remains `undefined` if there is no attribute value.

```css
[href=foo] /* foo */
[href='foo'] /* foo */
[href="foo"] /* foo */
[href] /* undefined */
```

### `attribute.spaces`

Like `node.spaces` with the `before` and `after` values containing the spaces
around the element, the parts of the attribute can also have spaces before
and after them. The for each of `attribute`, `operator`, `value` and
`insensitive` there is corresponding property of the same nam in
`node.spaces` that has an optional `before` or `after` string containing only
whitespace.

Note that corresponding values in `attributes.raws.spaces` contain values
including any comments. If set, these values will override the
`attribute.spaces` value. Take care to remove them if changing
`attribute.spaces`.

### `attribute.raws`

The raws object stores comments and other information necessary to re-render
the node exactly as it was in the source.

If a comment is embedded within the identifiers for the `namespace`, `attribute`
or `value` then a property is placed in the raws for that value containing the full source of the propery including comments.

If a comment is embedded within the space between parts of the attribute
then the raw for that space is set accordingly.

Setting an attribute's property `raws` value to be deleted.

For now, changing the spaces required also updating or removing any of the
raws values that override them.

Example: `[ /*before*/ href /* after-attr */ = /* after-operator */ te/*inside-value*/st/* wow */ /*omg*/i/*bbq*/ /*whodoesthis*/]` would parse as:

```js
{
  attribute: "href",
  operator: "=",
  value: "test",
  spaces: {
    before: '',
    after: '',
    attribute: { before: '  ', after: '  ' },
    operator: { after: '  ' },
    value: { after: ' ' },
    insensitive: { after: ' ' }
  },
  raws: {
    spaces: {
      attribute: { before: ' /*before*/ ', after: ' /* after-attr */ ' },
      operator: { after: ' /* after-operator */ ' },
      value: { after: '/* wow */ /*omg*/' },
      insensitive: { after: '/*bbq*/ /*whodoesthis*/' }
    },
    unquoted: 'test',
    value: 'te/*inside-value*/st'
  }
}
```

## `Processor`

### `ProcessorOptions`

* `lossless` - When `true`, whitespace is preserved. Defaults to `true`.
* `updateSelector` - When `true`, if any processor methods are passed a postcss
  `Rule` node instead of a string, then that Rule's selector is updated
  with the results of the processing. Defaults to `true`.

### `process|processSync(selectors, [options])`

Processes the `selectors`, returning a string from the result of processing.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

**Example:**

```js
const parser = require("postcss-selector-parser");
const processor = parser();

let result = processor.processSync(' .class');
console.log(result);
// =>  .class

// Asynchronous operation
let promise = processor.process(' .class').then(result => {
    console.log(result)
    // => .class
});

// To have the parser normalize whitespace values, utilize the options
result = processor.processSync('  .class  ', {lossless: false});
console.log(result);
// => .class

// For better syntax errors, pass a PostCSS Rule node.
const postcss = require('postcss');
rule = postcss.rule({selector: ' #foo    > a,  .class  '});
processor.process(rule, {lossless: false, updateSelector: true}).then(result => {
    console.log(result);
    // => #foo>a,.class
    console.log("rule:", rule.selector);
    // => rule: #foo>a,.class
})
```

Arguments:

* `selectors (string|postcss.Rule)`: Either a selector string or a PostCSS Rule
  node.
* `[options] (object)`: Process options


### `ast|astSync(selectors, [options])`

Like `process()` and `processSync()` but after
processing the `selectors` these methods return the `Root` node of the result
instead of a string.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

### `transform|transformSync(selectors, [options])`

Like `process()` and `processSync()` but after
processing the `selectors` these methods return the value returned by the
processor callback.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

### Error Handling Within Selector Processors

The root node passed to the selector processor callback
has a method `error(message, options)` that returns an
error object. This method should always be used to raise
errors relating to the syntax of selectors. The options
to this method are passed to postcss's error constructor
([documentation](http://postcss.org/api/#container-error)).

#### Async Error Example

```js
let processor = (root) => {
    return new Promise((resolve, reject) => {
        root.walkClasses((classNode) => {
            if (/^(.*)[-_]/.test(classNode.value)) {
                let msg = "classes may not have underscores or dashes in them";
                reject(root.error(msg, {
                    index: classNode.sourceIndex + RegExp.$1.length + 1,
                    word: classNode.value
                }));
            }
        });
        resolve();
    });
};

const postcss = require("postcss");
const parser = require("postcss-selector-parser");
const selectorProcessor = parser(processor);
const plugin = postcss.plugin('classValidator', (options) => {
    return (root) => {
        let promises = [];
        root.walkRules(rule => {
            promises.push(selectorProcessor.process(rule));
        });
        return Promise.all(promises);
    };
});
postcss(plugin()).process(`
.foo-bar {
  color: red;
}
`.trim(), {from: 'test.css'}).catch((e) => console.error(e.toString()));

// CssSyntaxError: classValidator: ./test.css:1:5: classes may not have underscores or dashes in them
//
// > 1 | .foo-bar {
//     |     ^
//   2 |   color: red;
//   3 | }
```

#### Synchronous Error Example

```js
let processor = (root) => {
    root.walkClasses((classNode) => {
        if (/.*[-_]/.test(classNode.value)) {
            let msg = "classes may not have underscores or dashes in them";
            throw root.error(msg, {
                index: classNode.sourceIndex,
                word: classNode.value
            });
        }
    });
};

const postcss = require("postcss");
const parser = require("postcss-selector-parser");
const selectorProcessor = parser(processor);
const plugin = postcss.plugin('classValidator', (options) => {
    return (root) => {
        root.walkRules(rule => {
            selectorProcessor.processSync(rule);
        });
    };
});
postcss(plugin()).process(`
.foo-bar {
  color: red;
}
`.trim(), {from: 'test.css'}).catch((e) => console.error(e.toString()));

// CssSyntaxError: classValidator: ./test.css:1:5: classes may not have underscores or dashes in them
//
// > 1 | .foo-bar {
//     |     ^
//   2 |   color: red;
//   3 | }
```


---

# 7.1.0

- feat: insert(Before|After) support multiple new node

# 7.0.0

- Feat: make insertions during iteration safe (major)

# 6.1.2

- Fixed: erroneous trailing combinators in pseudos

# 6.1.1

- Fixed: improve typings of constructor helpers (#292)

# 6.1.0

- Feature: add `sourceIndex` to `Selector` nodes (#290)

# 6.0.16

- Fixed: add missing `index` argument to `each`/`walk` callback types (#289)

# 6.0.15

- Fixed: Node#prev and Node#next type for the first/last node

# 6.0.14

- Fixed: type definitions

# 6.0.13

- Fixed: throw on unexpected pipe symbols

# 6.0.12

- Fixed: `clone` arguments should be optional

# 6.0.11

- Fixed: parse attribute case insensitivity flag

# 6.0.10

- Fixed: `isPseudoElement()` supports `:first-letter` and `:first-line`

# 6.0.9

- Fixed: `Combinator.raws` property type

# 6.0.8

- Fixed: reduced size

# 6.0.7

- Fixed: parse animation percents

# 6.0.6

- Fixed: parse quoted attributes containing a newline correctly

# 6.0.5

- Perf: rework unesc for a 63+% performance boost

# 6.0.4

- Fixed: ts errors

# 6.0.3

- Fixed: replace node built-in "util" module with "util-deprecate"
- Fixed: handle uppercase pseudo elements
- Fixed: do not create invalid combinator before comment

# 6.0.2

- Fixed an issue with parsing and stringifying an empty attribute value

# 6.0.1

- Fixed an issue with unicode surrogate pair parsing

# 6.0.0

- Updated: `cssesc` to 3.0.0 (major)
- Fixed: Issues with escaped `id` and `class` selectors

# 5.0.0

- Allow escaped dot within class name.
- Update PostCSS to 7.0.7 (patch)

# 5.0.0-rc.4

- Fixed an issue where comments immediately after an insensitive (in attribute)
  were not parsed correctly.
- Updated `cssesc` to 2.0.0 (major).
- Removed outdated integration tests.
- Added tests for custom selectors, tags with attributes, the universal
  selector with pseudos, and tokens after combinators.

# 5.0.0-rc.1

To ease adoption of the v5.0 release, we have relaxed the node version
check performed by npm at installation time to allow for node 4, which
remains officially unsupported, but likely to continue working for the
time being.

# 5.0.0-rc.0

This release has **BREAKING CHANGES** that were required to fix regressions
in 4.0.0 and to make the Combinator Node API consistent for all combinator
types. Please read carefully.

## Summary of Changes

* The way a descendent combinator that isn't a single space character (E.g. `.a  .b`) is stored in the AST has changed.
* Named Combinators (E.g. `.a /for/ .b`) are now properly parsed as a combinator.
* It is now possible to look up a node based on the source location of a character in that node and to query nodes if they contain some character.
* Several bug fixes that caused the parser to hang and run out of memory when a `/` was encountered have been fixed.
* The minimum supported version of Node is now `v6.0.0`.

### Changes to the Descendent Combinator

In prior releases, the value of a descendant combinator with multiple spaces included all the spaces.

* `.a   .b`: Extra spaces are now stored as space before.
  - Old & Busted:
    - `combinator.value === "   "`
  - New hotness:
    - `combinator.value === " " && combinator.spaces.before === "  "`
* `.a   /*comment*/.b`: A comment at the end of the combinator causes extra space to become after space.
  - Old & Busted:
    - `combinator.value === "   "`
    - `combinator.raws.value === "   /*comment/"`
  - New hotness:
    - `combinator.value === " "`
    - `combinator.spaces.after === "  "`
    - `combinator.raws.spaces.after === "  /*comment*/"`
* `.a<newline>.b`: whitespace that doesn't start or end with a single space character is stored as a raw value.
  - Old & Busted:
    - `combinator.value === "\n"`
    - `combinator.raws.value === undefined`
  - New hotness:
    - `combinator.value === " "`
    - `combinator.raws.value === "\n"`

### Support for "Named Combinators"

Although, nonstandard and unlikely to ever become a standard, combinators like `/deep/` and `/for/` are now properly supported.

Because they've been taken off the standardization track, there is no spec-official name for combinators of the form `/<ident>/`. However, I talked to [Tab Atkins](https://twitter.com/tabatkins) and we agreed to call them "named combinators" so now they are called that.

Before this release such named combinators were parsed without intention and generated three nodes of type `"tag"` where the first and last nodes had a value of `"/"`.

* `.a /for/ .b` is parsed as a combinator.
  - Old & Busted:
    - `root.nodes[0].nodes[1].type === "tag"`
    - `root.nodes[0].nodes[1].value === "/"`
  - New hotness:
    - `root.nodes[0].nodes[1].type === "combinator"`
    - `root.nodes[0].nodes[1].value === "/for/"`
* `.a /F\6fR/ .b` escapes are handled and uppercase is normalized.
  - Old & Busted:
    - `root.nodes[0].nodes[2].type === "tag"`
    - `root.nodes[0].nodes[2].value === "F\\6fR"`
  - New hotness:
    - `root.nodes[0].nodes[1].type === "combinator"`
    - `root.nodes[0].nodes[1].value === "/for/"`
    - `root.nodes[0].nodes[1].raws.value === "/F\\6fR/"`

### Source position checks and lookups

A new API was added to look up a node based on the source location.

```js
const selectorParser = require("postcss-selector-parser");
// You can find the most specific node for any given character
let combinator = selectorParser.astSync(".a > .b").atPosition(1,4);
combinator.toString() === " > ";
// You can check if a node includes a specific character
// Whitespace surrounding the node that is owned by that node
// is included in the check.
[2,3,4,5,6].map(column => combinator.isAtPosition(1, column));
// => [false, true, true, true, false]
```

# 4.0.0

This release has **BREAKING CHANGES** that were required to fix bugs regarding values with escape sequences. Please read carefully.

* **Identifiers with escapes** - CSS escape sequences are now hidden from the public API by default.
  The normal value of a node like a class name or ID, or an aspect of a node such as attribute
  selector's value, is unescaped. Escapes representing Non-ascii characters are unescaped into
  unicode characters. For example: `bu\tton, .\31 00, #i\2764\FE0Fu, [attr="value is \"quoted\""]`
  will parse respectively to the values `button`, `100`, `i❤️u`, `value is "quoted"`.
  The original escape sequences for these values can be found in the corresponding property name
  in `node.raws`. Where possible, deprecation warnings were added, but the nature
  of escape handling makes it impossible to detect what is escaped or not. Our expectation is
  that most users are neither expecting nor handling escape sequences in their use of this library,
  and so for them, this is a bug fix. Users who are taking care to handle escapes correctly can
  now update their code to remove the escape handling and let us do it for them.

* **Mutating values with escapes** - When you make an update to a node property that has escape handling
  The value is assumed to be unescaped, and any special characters are escaped automatically and
  the corresponding `raws` value is immediately updated. This can result in changes to the original
  escape format. Where the exact value of the escape sequence is important there are methods that
  allow both values to be set in conjunction. There are a number of new convenience methods for
  manipulating values that involve escapes, especially for attributes values where the quote mark
  is involved. See https://github.com/postcss/postcss-selector-parser/pull/133 for an extensive
  write-up on these changes.


**Upgrade/API Example**

In `3.x` there was no unescape handling and internal consistency of several properties was the caller's job to maintain. It was very easy for the developer
to create a CSS file that did not parse correctly when some types of values
were in use.

```js
const selectorParser = require("postcss-selector-parser");
let attr = selectorParser.attribute({attribute: "id", operator: "=", value: "a-value"});
attr.value; // => "a-value"
attr.toString(); // => [id=a-value]
// Add quotes to an attribute's value.
// All these values have to be set by the caller to be consistent:
// no internal consistency is maintained.
attr.raws.unquoted = attr.value
attr.value = "'" + attr.value + "'";
attr.value; // => "'a-value'"
attr.quoted = true;
attr.toString();  // => "[id='a-value']"
```

In `4.0` there is a convenient API for setting and mutating values
that may need escaping. Especially for attributes.

```js
const selectorParser = require("postcss-selector-parser");

// The constructor requires you specify the exact escape sequence
let className = selectorParser.className({value: "illegal class name", raws: {value: "illegal\\ class\\ name"}});
className.toString(); // => '.illegal\\ class\\ name'

// So it's better to set the value as a property
className = selectorParser.className();
// Most properties that deal with identifiers work like this
className.value = "escape for me";
className.value; // => 'escape for me'
className.toString(); // => '.escape\\ for\\ me'

// emoji and all non-ascii are escaped to ensure it works in every css file.
className.value = "😱🦄😍";
className.value; // => '😱🦄😍'
className.toString(); // => '.\\1F631\\1F984\\1F60D'

// you can control the escape sequence if you want, or do bad bad things
className.setPropertyAndEscape('value', 'xxxx', 'yyyy');
className.value; // => "xxxx"
className.toString(); // => ".yyyy"

// Pass a value directly through to the css output without escaping it. 
className.setPropertyWithoutEscape('value', '$REPLACE_ME$');
className.value; // => "$REPLACE_ME$"
className.toString(); // => ".$REPLACE_ME$"

// The biggest changes are to the Attribute class
// passing quoteMark explicitly is required to avoid a deprecation warning.
let attr = selectorParser.attribute({attribute: "id", operator: "=", value: "a-value", quoteMark: null});
attr.toString(); // => "[id=a-value]"
// Get the value with quotes on it and any necessary escapes.
// This is the same as reading attr.value in 3.x.
attr.getQuotedValue(); // => "a-value";
attr.quoteMark; // => null

// Add quotes to an attribute's value.
attr.quoteMark = "'"; // This is all that's required.
attr.toString(); // => "[id='a-value']"
attr.quoted; // => true
// The value is still the same, only the quotes have changed.
attr.value; // => a-value
attr.getQuotedValue(); // => "'a-value'";

// deprecated assignment, no warning because there's no escapes
attr.value = "new-value";
// no quote mark is needed so it is removed
attr.getQuotedValue(); // => "new-value";

// deprecated assignment, 
attr.value = "\"a 'single quoted' value\"";
// > (node:27859) DeprecationWarning: Assigning an attribute a value containing characters that might need to be escaped is deprecated. Call attribute.setValue() instead.
attr.getQuotedValue(); // => '"a \'single quoted\' value"';
// quote mark inferred from first and last characters.
attr.quoteMark; // => '"'

// setValue takes options to make manipulating the value simple.
attr.setValue('foo', {smart: true});
// foo doesn't require any escapes or quotes.
attr.toString(); // => '[id=foo]'
attr.quoteMark; // => null 

// An explicit quote mark can be specified
attr.setValue('foo', {quoteMark: '"'});
attr.toString(); // => '[id="foo"]'

// preserves quote mark by default
attr.setValue('bar');
attr.toString(); // => '[id="bar"]'
attr.quoteMark = null;
attr.toString(); // => '[id=bar]'

// with no arguments, it preserves quote mark even when it's not a great idea
attr.setValue('a value \n that should be quoted');
attr.toString(); // => '[id=a\\ value\\ \\A\\ that\\ should\\ be\\ quoted]'

// smart preservation with a specified default
attr.setValue('a value \n that should be quoted', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => "[id='a value \\A  that should be quoted']"
attr.quoteMark = '"';
// => '[id="a value \\A  that should be quoted"]'

// this keeps double quotes because it wants to quote the value and the existing value has double quotes.
attr.setValue('this should be quoted', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => '[id="this should be quoted"]'

// picks single quotes because the value has double quotes
attr.setValue('a "double quoted" value', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => "[id='a "double quoted" value']"

// setPropertyAndEscape lets you do anything you want. Even things that are a bad idea and illegal.
attr.setPropertyAndEscape('value', 'xxxx', 'the password is 42');
attr.value; // => "xxxx"
attr.toString(); // => "[id=the password is 42]"

// Pass a value directly through to the css output without escaping it. 
attr.setPropertyWithoutEscape('value', '$REPLACEMENT$');
attr.value; // => "$REPLACEMENT$"
attr.toString(); // => "[id=$REPLACEMENT$]"
```

# 3.1.2

* Fix: Removed dot-prop dependency since it's no longer written in es5.

# 3.1.1

* Fix: typescript definitions weren't in the published package.

# 3.1.0

* Fixed numerous bugs in attribute nodes relating to the handling of comments
  and whitespace. There's significant changes to `attrNode.spaces` and `attrNode.raws` since the `3.0.0` release.
* Added `Attribute#offsetOf(part)` to get the offset location of
  attribute parts like `"operator"` and `"value"`. This is most
  often added to `Attribute#sourceIndex` for error reporting.

# 3.0.0

## Breaking changes

* Some tweaks to the tokenizer/attribute selector parsing mean that whitespace
  locations might be slightly different to the 2.x code.
* Better attribute selector parsing with more validation; postcss-selector-parser
  no longer uses regular expressions to parse attribute selectors.
* Added an async API (thanks to @jacobp100); the default `process` API is now
  async, and the sync API is now accessed through `processSync` instead.
* `process()` and `processSync()` now return a string instead of the Processor
  instance.
* Tweaks handling of Less interpolation (thanks to @jwilsson).
* Removes support for Node 0.12.

## Other changes

* `ast()` and `astSync()` methods have been added to the `Processor`. These
  return the `Root` node of the selectors after processing them.
* `transform()` and `transformSync()` methods have been added to the
  `Processor`. These return the value returned by the processor callback
  after processing the selectors.
* Set the parent when inserting a node (thanks to @chriseppstein).
* Correctly adjust indices when using insertBefore/insertAfter (thanks to @tivac).
* Fixes handling of namespaces with qualified tag selectors.
* `process`, `ast` and `transform` (and their sync variants) now accept a
  `postcss` rule node. When provided, better errors are generated and selector
  processing is automatically set back to the rule selector (unless the `updateSelector` option is set to `false`.)
* Now more memory efficient when tokenizing selectors.

### Upgrade hints

The pattern of:

`rule.selector = processor.process(rule.selector).result.toString();`

is now:

`processor.processSync(rule)`

# 2.2.3

* Resolves an issue where the parser would not reduce multiple spaces between an
  ampersand and another simple selector in lossy mode (thanks to @adam-26).

# 2.2.2

* No longer hangs on an unescaped semicolon; instead the parser will throw
  an exception for these cases.

# 2.2.1

* Allows a consumer to specify whitespace tokens when creating a new Node
  (thanks to @Semigradsky).

# 2.2.0

* Added a new option to normalize whitespace when parsing the selector string
  (thanks to @adam-26).

# 2.1.1

* Better unquoted value handling within attribute selectors
  (thanks to @evilebottnawi).

# 2.1.0

* Added: Use string constants for all node types & expose them on the main
  parser instance (thanks to @Aweary).

# 2.0.0

This release contains the following breaking changes:

* Renamed all `eachInside` iterators to `walk`. For example, `eachTag` is now
  `walkTags`, and `eachInside` is now `walk`.
* Renamed `Node#removeSelf()` to `Node#remove()`.
* Renamed `Container#remove()` to `Container#removeChild()`.
* Renamed `Node#raw` to `Node#raws` (thanks to @davidtheclark).
* Now parses `&` as the *nesting* selector, rather than a *tag* selector.
* Fixes misinterpretation of Sass interpolation (e.g. `#{foo}`) as an
  id selector (thanks to @davidtheclark).

and;

* Fixes parsing of attribute selectors with equals signs in them
  (e.g. `[data-attr="foo=bar"]`) (thanks to @montmanu).
* Adds `quoted` and `raw.unquoted` properties to attribute nodes
  (thanks to @davidtheclark).

# 1.3.3

* Fixes an infinite loop on `)` and `]` tokens when they had no opening pairs.
  Now postcss-selector-parser will throw when it encounters these lone tokens.

# 1.3.2

* Now uses plain integers rather than `str.charCodeAt(0)` for compiled builds.

# 1.3.1

* Update flatten to v1.x (thanks to @shinnn).

# 1.3.0

* Adds a new node type, `String`, to fix a crash on selectors such as
  `foo:bar("test")`.

# 1.2.1

* Fixes a crash when the parser encountered a trailing combinator.

# 1.2.0

* A more descriptive error is thrown when the parser expects to find a
  pseudo-class/pseudo-element (thanks to @ashelley).
* Adds support for line/column locations for selector nodes, as well as a
  `Node#sourceIndex` method (thanks to @davidtheclark).

# 1.1.4

* Fixes a crash when a selector started with a `>` combinator. The module will
  now no longer throw if a selector has a leading/trailing combinator node.

# 1.1.3

* Fixes a crash on `@` tokens.

# 1.1.2

* Fixes an infinite loop caused by using parentheses in a non-pseudo element
  context.

# 1.1.1

* Fixes a crash when a backslash ended a selector string.

# 1.1.0

* Adds support for replacing multiple nodes at once with `replaceWith`
  (thanks to @jonathantneal).
* Parser no longer throws on sequential IDs and trailing commas, to support
  parsing of selector hacks.

# 1.0.1

* Fixes using `insertAfter` and `insertBefore` during iteration.

# 1.0.0

* Adds `clone` and `replaceWith` methods to nodes.
* Adds `insertBefore` and `insertAfter` to containers.
* Stabilises API.

# 0.0.5

* Fixes crash on extra whitespace inside a pseudo selector's parentheses.
* Adds sort function to the container class.
* Enables the parser to pass its input through without transforming.
* Iteration-safe `each` and `eachInside`.

# 0.0.4

* Tidy up redundant duplication.
* Fixes a bug where the parser would loop infinitely on universal selectors
  inside pseudo selectors.
* Adds `length` getter and `eachInside`, `map`, `reduce` to the container class.
* When a selector has been removed from the tree, the root node will no longer
  cast it to a string.
* Adds node type iterators to the container class (e.g. `eachComment`).
* Adds filter function to the container class.
* Adds split function to the container class.
* Create new node types by doing `parser.id(opts)` etc.
* Adds support for pseudo classes anywhere in the selector.

# 0.0.3

* Adds `next` and `prev` to the node class.
* Adds `first` and `last` getters to the container class.
* Adds `every` and `some` iterators to the container class.
* Add `empty` alias for `removeAll`.
* Combinators are now types of node.
* Fixes the at method so that it is not an alias for `index`.
* Tidy up creation of new nodes in the parser.
* Refactors how namespaces are handled for consistency & less redundant code.
* Refactors AST to use `nodes` exclusively, and eliminates excessive nesting.
* Fixes nested pseudo parsing.
* Fixes whitespace parsing.

# 0.0.2

* Adds support for namespace selectors.
* Adds support for selectors joined by escaped spaces - such as `.\31\ 0`.

# 0.0.1

* Initial release.


---

# postcss-selector-parser [![test](https://github.com/postcss/postcss-selector-parser/actions/workflows/test.yml/badge.svg)](https://github.com/postcss/postcss-selector-parser/actions/workflows/test.yml)

> Selector parser with built in methods for working with selector strings.

## Install

With [npm](https://npmjs.com/package/postcss-selector-parser) do:

```
npm install postcss-selector-parser
```

## Quick Start

```js
const parser = require('postcss-selector-parser');
const transform = selectors => {
    selectors.walk(selector => {
        // do something with the selector
        console.log(String(selector))
    });
};

const transformed = parser(transform).processSync('h1, h2, h3');
```

To normalize selector whitespace:

```js
const parser = require('postcss-selector-parser');
const normalized = parser().processSync('h1, h2, h3', {lossless: false});
// -> h1,h2,h3
```

Async support is provided through `parser.process` and will resolve a Promise
with the resulting selector string.

## API

Please see [API.md](API.md).

## Credits

* Huge thanks to Andrey Sitnik (@ai) for work on PostCSS which helped
  accelerate this module's development.

## License

MIT


---

# [postcss][postcss]-reduce-idents

> Reduce [custom identifiers][idents] with PostCSS.


## Install

With [npm](https://npmjs.org/package/postcss-reduce-idents) do:

```
npm install postcss-reduce-idents --save
```


## Example

### Input

This module will rename custom identifiers in your CSS files; it does so by
converting each name to a index, which is then encoded into a legal identifier.
A legal custom identifier in CSS is case sensitive and must start with a
letter, but can contain digits, hyphens and underscores. There are over 3,000
possible two character identifiers, and 51 possible single character identifiers
that will be generated.

```css
@keyframes whiteToBlack {
    0% {
        color: #fff
    }
    to {
        color: #000
    }
}

.one {
    animation-name: whiteToBlack
}
```

### Output

```css
@keyframes a {
    0% {
        color: #fff
    }
    to {
        color: #000
    }
}

.one {
    animation-name: a
}
```

Note that this module does not handle identifiers that are not linked together.
The following example will not be transformed in any way:

```css
@keyframes fadeOut {
    0% { opacity: 1 }
    to { opacity: 0 }
}

.fadeIn {
    animation-name: fadeIn;
}
```

It works for `@keyframes`, `@counter-style`, custom `counter` values and grid area definitions. See the
[documentation][idents] for more information, or the [tests](src/__tests__) for more
examples.


## Usage

See the [PostCSS documentation](https://github.com/postcss/postcss#usage) for
examples for your environment.


## API

### reduceIdents([options])

#### options

##### counter

Type: `boolean`  
Default: `true`

Pass `false` to disable reducing `content`, `counter-reset` and `counter-increment` declarations.

##### keyframes

Type: `boolean`  
Default: `true`

Pass `false` to disable reducing `keyframes` rules and `animation` declarations.

##### counterStyle

Type: `boolean`  
Default: `true`

Pass `false` to disable reducing `counter-style` rules and `list-style` and `system` declarations.

##### gridTemplate

Type: `boolean`  
Default: `true`

Pass `false` to disable reducing `grid-template`, `grid-area`, `grid-column`, `grid-row` and `grid-template-areas` declarations.

##### encoder

Type: `function`  
Default: [`lib/encode.js`](https://github.com/cssnano/postcss-reduce-idents/blob/master/src/lib/encode.js)

Pass a custom function to encode the identifier with (e.g.: as a way of prefixing them automatically).

It receives two parameters:
  - A `String` with the node value.
  - A `Number` identifying the index of the occurrence.

## Contributors

See [CONTRIBUTORS.md](https://github.com/cssnano/cssnano/blob/master/CONTRIBUTORS.md).


## License

MIT © [Ben Briggs](http://beneb.info)

[idents]:  https://developer.mozilla.org/en-US/docs/Web/CSS/custom-ident

[postcss]: https://github.com/postcss/postcss


---

# [postcss][postcss]-reduce-initial

> Reduce `initial` definitions to the _actual_ initial value, where possible.

## Install

With [npm](https://npmjs.org/package/postcss-reduce-initial) do:

```
npm install postcss-reduce-initial --save
```

## Examples

See the [data](data) for more conversions. This data is courtesy
of Mozilla.

### Convert `initial` values

When the `initial` keyword is longer than the property value, it will
be converted:

#### Input

```css
h1 {
  min-width: initial;
}
```

#### Output

```css
h1 {
  min-width: auto;
}
```

### Convert values back to `initial`

When the `initial` value is smaller than the property value, it will
be converted:

#### Input

```css
h1 {
  transform-box: border-box;
}
```

#### Output

```css
h1 {
  transform-box: initial;
}
```

This conversion is only applied when you supply a browsers list that all support
the `initial` keyword; it's worth noting that Internet Explorer has no support.

## API

### reduceInitial([options])

#### options

##### ignore

Type: `Array<String>`
Default: `undefined`

It contains the Array of properties that will be ignored while reducing its value to initial.
Example : `{ ignore : ["min-height"] }`

## Usage

See the [PostCSS documentation](https://github.com/postcss/postcss#usage) for
examples for your environment.

## Contributors

See [CONTRIBUTORS.md](https://github.com/cssnano/cssnano/blob/master/CONTRIBUTORS.md).

## License

This program uses a list of CSS properties derived from data maintained my the MDN team at Mozilla and licensed under the [CC0 1.0 Universal Public Domain Dedication](https://creativecommons.org/publicdomain/zero/1.0/).

MIT © [Ben Briggs](http://beneb.info)

[postcss]: https://github.com/postcss/postcss


---

# [postcss][postcss]-reduce-transforms

> Reduce transform functions with PostCSS.

## Install

With [npm](https://npmjs.org/package/postcss-reduce-transforms) do:

```
npm install postcss-reduce-transforms --save
```

## Example

This module will reduce transform functions where possible. For more examples,
see the [tests](src/__tests__/index.js).

### Input

```css
h1 {
  transform: rotate3d(0, 0, 1, 20deg);
}
```

### Output

```css
h1 {
  transform: rotate(20deg);
}
```

## Usage

See the [PostCSS documentation](https://github.com/postcss/postcss#usage) for
examples for your environment.

## Contributors

See [CONTRIBUTORS.md](https://github.com/cssnano/cssnano/blob/master/CONTRIBUTORS.md).

## License

MIT © [Ben Briggs](http://beneb.info)

[postcss]: https://github.com/postcss/postcss


---

## 3.0
* Use PostCSS 7.x
* Bump various dependencies

## 2.0
* Use PostCSS 6.x
* Use Node 4.x syntax

## 1.0
* Initial release


---

# PostCSS Replace Overflow Wrap [![CSS Standard Status][css-img]][css] [![Build Status][ci-img]][ci]

[PostCSS] plugin to replace overflow-wrap with word-wrap. May optionally retain both declarations.

[PostCSS]: https://github.com/postcss/postcss
[css-img]: https://jonathantneal.github.io/css-db/badge/css-text-overflow-wrap-property.svg
[css]:     https://jonathantneal.github.io/css-db/#css-text-overflow-wrap-property
[ci-img]:  https://travis-ci.org/MattDiMu/postcss-replace-overflow-wrap.svg
[ci]:      https://travis-ci.org/MattDiMu/postcss-replace-overflow-wrap


```css
/* before */
.foo {
    overflow-wrap: break-word;
}

/* after */
.foo {
    word-wrap: break-word;
}
```

```css
/* before, when the option { method: 'copy' } is passed */
.foo {
    overflow-wrap: break-word;
}

/* after */
.foo {
    word-wrap: break-word;
    overflow-wrap: break-word;
}
```

### Installation
`npm install --save-dev postcss postcss-replace-overflow-wrap`

For Postcss 7 or earlier use Version 3 or earlier:

`npm install --save-dev postcss-replace-overflow-wrap@3`


## Usage

```js
/* default usage, with no options (method = replace) */
postcss([ require('postcss-replace-overflow-wrap') ])
```

```js
/* add word-wrap, but keep overflow-wrap */
postcss([ require('postcss-replace-overflow-wrap') ])({ method: 'copy' })
```
See [PostCSS] docs for examples for your environment.


---

# Changes to PostCSS Selector Not

### 8.0.1

_October 23, 2024_

- Updated: `postcss-selector-parser`

[Full CHANGELOG](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-selector-not/CHANGELOG.md)


---

The MIT License (MIT)

Copyright (c) 2017 Maxime Thirouin

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


---

# PostCSS Selector Not [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install postcss-selector-not --save-dev`

[PostCSS Selector Not] transforms :not() W3C CSS level 4 pseudo classes to :not() CSS level 3 selectors following the [Selectors 4 Specification].

```pcss
p:not(:first-child, .special) {
	color: red;
}

/* becomes */

p:not(:first-child):not(.special) {
	color: red;
}
```

> [!CAUTION]
> Only lists of simple selectors (`:not(.a, .b)`) will work as expected.
> Complex selectors (`:not(.a > .b, .c ~ .d)`) can not be downgraded.

## Usage

Add [PostCSS Selector Not] to your project:

```bash
npm install postcss postcss-selector-not --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssSelectorNot = require('postcss-selector-not');

postcss([
	postcssSelectorNot(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#not-pseudo-class
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/postcss-selector-not

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Selector Not]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-selector-not
[Selectors 4 Specification]: https://www.w3.org/TR/selectors-4/#negation-pseudo


---

# API Documentation

*Please use only this documented API when working with the parser. Methods
not documented here are subject to change at any point.*

## `parser` function

This is the module's main entry point.

```js
const parser = require('postcss-selector-parser');
```

### `parser([transform], [options])`

Creates a new `processor` instance

```js
const processor = parser();
```

Or, with optional transform function

```js
const transform = selectors => {
    selectors.walkUniversals(selector => {
        selector.remove();
    });
};

const processor = parser(transform)

// Example
const result = processor.processSync('*.class');
// => .class
```

[See processor documentation](#processor)

Arguments:

* `transform (function)`: Provide a function to work with the parsed AST.
* `options (object)`: Provide default options for all calls on the returned `Processor`.

### `parser.attribute([props])`

Creates a new attribute selector.

```js
parser.attribute({attribute: 'href'});
// => [href]
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.className([props])`

Creates a new class selector.

```js
parser.className({value: 'button'});
// => .button
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.combinator([props])`

Creates a new selector combinator.

```js
parser.combinator({value: '+'});
// => +
```

Arguments:

* `props (object)`: The new node's properties.

Notes:
* **Descendant Combinators** The value of descendant combinators created by the
  parser always just a single space (`" "`). For descendant selectors with no
  comments, additional space is now stored in `node.spaces.before`. Depending
  on the location of comments, additional spaces may be stored in
  `node.raws.spaces.before`, `node.raws.spaces.after`, or `node.raws.value`.
* **Named Combinators** Although, nonstandard and unlikely to ever become a standard,
  named combinators like `/deep/` and `/for/` are parsed as combinators. The
  `node.value` is name after being unescaped and normalized as lowercase. The
  original value for the combinator name is stored in `node.raws.value`.


### `parser.comment([props])`

Creates a new comment.

```js
parser.comment({value: '/* Affirmative, Dave. I read you. */'});
// => /* Affirmative, Dave. I read you. */
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.id([props])`

Creates a new id selector.

```js
parser.id({value: 'search'});
// => #search
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.nesting([props])`

Creates a new nesting selector.

```js
parser.nesting();
// => &
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.pseudo([props])`

Creates a new pseudo selector.

```js
parser.pseudo({value: '::before'});
// => ::before
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.root([props])`

Creates a new root node.

```js
parser.root();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.selector([props])`

Creates a new selector node.

```js
parser.selector();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.string([props])`

Creates a new string node.

```js
parser.string();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.tag([props])`

Creates a new tag selector.

```js
parser.tag({value: 'button'});
// => button
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.universal([props])`

Creates a new universal selector.

```js
parser.universal();
// => *
```

Arguments:

* `props (object)`: The new node's properties.

## Node types

### `node.type`

A string representation of the selector type. It can be one of the following;
`attribute`, `class`, `combinator`, `comment`, `id`, `nesting`, `pseudo`,
`root`, `selector`, `string`, `tag`, or `universal`. Note that for convenience,
these constants are exposed on the main `parser` as uppercased keys. So for
example you can get `id` by querying `parser.ID`.

```js
parser.attribute({attribute: 'href'}).type;
// => 'attribute'
```

### `node.parent`

Returns the parent node.

```js
root.nodes[0].parent === root;
```

### `node.toString()`, `String(node)`, or `'' + node`

Returns a string representation of the node.

```js
const id = parser.id({value: 'search'});
console.log(String(id));
// => #search
```

### `node.next()` & `node.prev()`

Returns the next/previous child of the parent node.

```js
const next = id.next();
if (next && next.type !== 'combinator') {
    throw new Error('Qualified IDs are not allowed!');
}
```

### `node.replaceWith(node[,...nodeN])`

Replace a node with another.

```js
const attr = selectors.first.first;
const className = parser.className({value: 'test'});
attr.replaceWith(className);
```

Arguments:

* `node`: The node to substitute the original with.
...
* `nodeN`: The node to substitute the original with.

### `node.remove()`

Removes the node from its parent node.

```js
if (node.type === 'id') {
    node.remove();
}
```

### `node.clone([opts])`

Returns a copy of a node, detached from any parent containers that the
original might have had.

```js
const cloned = node.clone();
```

### `node.isAtPosition(line, column)`

Return a `boolean` indicating whether this node includes the character at the
position of the given line and column. Returns `undefined` if the nodes lack
sufficient source metadata to determine the position.

Arguments:

* `line`: 1-index based line number relative to the start of the selector.
* `column`: 1-index based column number relative to the start of the selector.

### `node.spaces`

Extra whitespaces around the node will be moved into `node.spaces.before` and
`node.spaces.after`. So for example, these spaces will be moved as they have
no semantic meaning:

```css
      h1     ,     h2   {}
```

For descendent selectors, the value is always a single space.

```css
h1        h2 {}
```

Additional whitespace is found in either the `node.spaces.before` and `node.spaces.after` depending on the presence of comments or other whitespace characters. If the actual whitespace does not start or end with a single space, the node's raw value is set to the actual space(s) found in the source.

### `node.source`

An object describing the node's start/end, line/column source position.

Within the following CSS, the `.bar` class node ...

```css
.foo,
  .bar {}
```

... will contain the following `source` object.

```js
source: {
    start: {
        line: 2,
        column: 3
    },
    end: {
        line: 2,
        column: 6
    }
}
```

### `node.sourceIndex`

The zero-based index of the node within the original source string.

Within the following CSS, the `.baz` class node will have a `sourceIndex` of `12`.

```css
.foo, .bar, .baz {}
```

## Container types

The `root`, `selector`, and `pseudo` nodes have some helper methods for working
with their children.

### `container.nodes`

An array of the container's children.

```js
// Input: h1 h2
selectors.at(0).nodes.length   // => 3
selectors.at(0).nodes[0].value // => 'h1'
selectors.at(0).nodes[1].value // => ' '
```

### `container.first` & `container.last`

The first/last child of the container.

```js
selector.first === selector.nodes[0];
selector.last === selector.nodes[selector.nodes.length - 1];
```

### `container.at(index)`

Returns the node at position `index`.

```js
selector.at(0) === selector.first;
selector.at(0) === selector.nodes[0];
```

Arguments:

* `index`: The index of the node to return.

### `container.atPosition(line, column)`

Returns the node at the source position `line` and `column`.

```js
// Input: :not(.foo),\n#foo > :matches(ol, ul)
selector.atPosition(1, 1); // => :not(.foo)
selector.atPosition(2, 1); // => \n#foo
```

Arguments:

* `line`: The line number of the node to return.
* `column`: The column number of the node to return.

### `container.index(node)`

Return the index of the node within its container.

```js
selector.index(selector.nodes[2]) // => 2
```

Arguments:

* `node`: A node within the current container.

### `container.length`

Proxy to the length of the container's nodes.

```js
container.length === container.nodes.length
```

### `container` Array iterators

The container class provides proxies to certain Array methods; these are:

* `container.map === container.nodes.map`
* `container.reduce === container.nodes.reduce`
* `container.every === container.nodes.every`
* `container.some === container.nodes.some`
* `container.filter === container.nodes.filter`
* `container.sort === container.nodes.sort`

Note that these methods only work on a container's immediate children; recursive
iteration is provided by `container.walk`.

### `container.each(callback)`

Iterate the container's immediate children, calling `callback` for each child.
You may return `false` within the callback to break the iteration.

```js
let className;
selectors.each((selector, index) => {
    if (selector.type === 'class') {
        className = selector.value;
        return false;
    }
});
```

Note that unlike `Array#forEach()`, this iterator is safe to use whilst adding
or removing nodes from the container.

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  and `index` arguments.

### `container.walk(callback)`

Like `container#each`, but will also iterate child nodes as long as they are
`container` types.

```js
selectors.walk((selector, index) => {
    // all nodes
});
```

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  and `index` arguments.

This iterator is safe to use whilst mutating `container.nodes`,
like `container#each`.

### `container.walk` proxies

The container class provides proxy methods for iterating over types of nodes,
so that it is easier to write modules that target specific selectors. Those
methods are:

* `container.walkAttributes`
* `container.walkClasses`
* `container.walkCombinators`
* `container.walkComments`
* `container.walkIds`
* `container.walkNesting`
* `container.walkPseudos`
* `container.walkTags`
* `container.walkUniversals`

### `container.split(callback)`

This method allows you to split a group of nodes by returning `true` from
a callback. It returns an array of arrays, where each inner array corresponds
to the groups that you created via the callback.

```js
// (input) => h1 h2>>h3
const list = selectors.first.split(selector => {
    return selector.type === 'combinator';
});

// (node values) => [['h1', ' '], ['h2', '>>'], ['h3']]
```

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  as an argument.

### `container.prepend(node)` & `container.append(node)`

Add a node to the start/end of the container. Note that doing so will set
the parent property of the node to this container.

```js
const id = parser.id({value: 'search'});
selector.append(id);
```

Arguments:

* `node`: The node to add.

### `container.insertBefore(old, new[, ...newNodes])` & `container.insertAfter(old, new[, ...newNodes])`

Add a node before or after an existing node in a container:

```js
selectors.walk(selector => {
    if (selector.type !== 'class') {
        const className = parser.className({value: 'theme-name'});
        selector.parent.insertAfter(selector, className);
    }
});
```

Arguments:

* `old`: The existing node in the container.
* `new`: The new node to add before/after the existing node.

### `container.removeChild(node)`

Remove the node from the container. Note that you can also use
`node.remove()` if you would like to remove just a single node.

```js
selector.length // => 2
selector.remove(id)
selector.length // => 1;
id.parent       // undefined
```

Arguments:

* `node`: The node to remove.

### `container.removeAll()` or `container.empty()`

Remove all children from the container.

```js
selector.removeAll();
selector.length // => 0
```

## Root nodes

A root node represents a comma separated list of selectors. Indeed, all
a root's `toString()` method does is join its selector children with a ','.
Other than this, it has no special functionality and acts like a container.

### `root.trailingComma`

This will be set to `true` if the input has a trailing comma, in order to
support parsing of legacy CSS hacks.

## Selector nodes

A selector node represents a single complex selector. For example, this
selector string `h1 h2 h3, [href] > p`, is represented as two selector nodes.
It has no special functionality of its own.

## Pseudo nodes

A pseudo selector extends a container node; if it has any parameters of its
own (such as `h1:not(h2, h3)`), they will be its children. Note that the pseudo
`value` will always contain the colons preceding the pseudo identifier. This
is so that both `:before` and `::before` are properly represented in the AST.

## Attribute nodes

### `attribute.quoted`

Returns `true` if the attribute's value is wrapped in quotation marks, false if it is not.
Remains `undefined` if there is no attribute value.

```css
[href=foo] /* false */
[href='foo'] /* true */
[href="foo"] /* true */
[href] /* undefined */
```

### `attribute.qualifiedAttribute`

Returns the attribute name qualified with the namespace if one is given.

### `attribute.offsetOf(part)`

 Returns the offset of the attribute part specified relative to the
 start of the node of the output string. This is useful in raising
 error messages about a specific part of the attribute, especially
 in combination with `attribute.sourceIndex`.

 Returns `-1` if the name is invalid or the value doesn't exist in this
 attribute.

 The legal values for `part` are:

 * `"ns"` - alias for "namespace"
 * `"namespace"` - the namespace if it exists.
 * `"attribute"` - the attribute name
 * `"attributeNS"` - the start of the attribute or its namespace
 * `"operator"` - the match operator of the attribute
 * `"value"` - The value (string or identifier)
 * `"insensitive"` - the case insensitivity flag

### `attribute.raws.unquoted`

Returns the unquoted content of the attribute's value.
Remains `undefined` if there is no attribute value.

```css
[href=foo] /* foo */
[href='foo'] /* foo */
[href="foo"] /* foo */
[href] /* undefined */
```

### `attribute.spaces`

Like `node.spaces` with the `before` and `after` values containing the spaces
around the element, the parts of the attribute can also have spaces before
and after them. The for each of `attribute`, `operator`, `value` and
`insensitive` there is corresponding property of the same nam in
`node.spaces` that has an optional `before` or `after` string containing only
whitespace.

Note that corresponding values in `attributes.raws.spaces` contain values
including any comments. If set, these values will override the
`attribute.spaces` value. Take care to remove them if changing
`attribute.spaces`.

### `attribute.raws`

The raws object stores comments and other information necessary to re-render
the node exactly as it was in the source.

If a comment is embedded within the identifiers for the `namespace`, `attribute`
or `value` then a property is placed in the raws for that value containing the full source of the propery including comments.

If a comment is embedded within the space between parts of the attribute
then the raw for that space is set accordingly.

Setting an attribute's property `raws` value to be deleted.

For now, changing the spaces required also updating or removing any of the
raws values that override them.

Example: `[ /*before*/ href /* after-attr */ = /* after-operator */ te/*inside-value*/st/* wow */ /*omg*/i/*bbq*/ /*whodoesthis*/]` would parse as:

```js
{
  attribute: "href",
  operator: "=",
  value: "test",
  spaces: {
    before: '',
    after: '',
    attribute: { before: '  ', after: '  ' },
    operator: { after: '  ' },
    value: { after: ' ' },
    insensitive: { after: ' ' }
  },
  raws: {
    spaces: {
      attribute: { before: ' /*before*/ ', after: ' /* after-attr */ ' },
      operator: { after: ' /* after-operator */ ' },
      value: { after: '/* wow */ /*omg*/' },
      insensitive: { after: '/*bbq*/ /*whodoesthis*/' }
    },
    unquoted: 'test',
    value: 'te/*inside-value*/st'
  }
}
```

## `Processor`

### `ProcessorOptions`

* `lossless` - When `true`, whitespace is preserved. Defaults to `true`.
* `updateSelector` - When `true`, if any processor methods are passed a postcss
  `Rule` node instead of a string, then that Rule's selector is updated
  with the results of the processing. Defaults to `true`.

### `process|processSync(selectors, [options])`

Processes the `selectors`, returning a string from the result of processing.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

**Example:**

```js
const parser = require("postcss-selector-parser");
const processor = parser();

let result = processor.processSync(' .class');
console.log(result);
// =>  .class

// Asynchronous operation
let promise = processor.process(' .class').then(result => {
    console.log(result)
    // => .class
});

// To have the parser normalize whitespace values, utilize the options
result = processor.processSync('  .class  ', {lossless: false});
console.log(result);
// => .class

// For better syntax errors, pass a PostCSS Rule node.
const postcss = require('postcss');
rule = postcss.rule({selector: ' #foo    > a,  .class  '});
processor.process(rule, {lossless: false, updateSelector: true}).then(result => {
    console.log(result);
    // => #foo>a,.class
    console.log("rule:", rule.selector);
    // => rule: #foo>a,.class
})
```

Arguments:

* `selectors (string|postcss.Rule)`: Either a selector string or a PostCSS Rule
  node.
* `[options] (object)`: Process options


### `ast|astSync(selectors, [options])`

Like `process()` and `processSync()` but after
processing the `selectors` these methods return the `Root` node of the result
instead of a string.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

### `transform|transformSync(selectors, [options])`

Like `process()` and `processSync()` but after
processing the `selectors` these methods return the value returned by the
processor callback.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

### Error Handling Within Selector Processors

The root node passed to the selector processor callback
has a method `error(message, options)` that returns an
error object. This method should always be used to raise
errors relating to the syntax of selectors. The options
to this method are passed to postcss's error constructor
([documentation](http://postcss.org/api/#container-error)).

#### Async Error Example

```js
let processor = (root) => {
    return new Promise((resolve, reject) => {
        root.walkClasses((classNode) => {
            if (/^(.*)[-_]/.test(classNode.value)) {
                let msg = "classes may not have underscores or dashes in them";
                reject(root.error(msg, {
                    index: classNode.sourceIndex + RegExp.$1.length + 1,
                    word: classNode.value
                }));
            }
        });
        resolve();
    });
};

const postcss = require("postcss");
const parser = require("postcss-selector-parser");
const selectorProcessor = parser(processor);
const plugin = postcss.plugin('classValidator', (options) => {
    return (root) => {
        let promises = [];
        root.walkRules(rule => {
            promises.push(selectorProcessor.process(rule));
        });
        return Promise.all(promises);
    };
});
postcss(plugin()).process(`
.foo-bar {
  color: red;
}
`.trim(), {from: 'test.css'}).catch((e) => console.error(e.toString()));

// CssSyntaxError: classValidator: ./test.css:1:5: classes may not have underscores or dashes in them
//
// > 1 | .foo-bar {
//     |     ^
//   2 |   color: red;
//   3 | }
```

#### Synchronous Error Example

```js
let processor = (root) => {
    root.walkClasses((classNode) => {
        if (/.*[-_]/.test(classNode.value)) {
            let msg = "classes may not have underscores or dashes in them";
            throw root.error(msg, {
                index: classNode.sourceIndex,
                word: classNode.value
            });
        }
    });
};

const postcss = require("postcss");
const parser = require("postcss-selector-parser");
const selectorProcessor = parser(processor);
const plugin = postcss.plugin('classValidator', (options) => {
    return (root) => {
        root.walkRules(rule => {
            selectorProcessor.processSync(rule);
        });
    };
});
postcss(plugin()).process(`
.foo-bar {
  color: red;
}
`.trim(), {from: 'test.css'}).catch((e) => console.error(e.toString()));

// CssSyntaxError: classValidator: ./test.css:1:5: classes may not have underscores or dashes in them
//
// > 1 | .foo-bar {
//     |     ^
//   2 |   color: red;
//   3 | }
```


---

# 7.1.0

- feat: insert(Before|After) support multiple new node

# 7.0.0

- Feat: make insertions during iteration safe (major)

# 6.1.2

- Fixed: erroneous trailing combinators in pseudos

# 6.1.1

- Fixed: improve typings of constructor helpers (#292)

# 6.1.0

- Feature: add `sourceIndex` to `Selector` nodes (#290)

# 6.0.16

- Fixed: add missing `index` argument to `each`/`walk` callback types (#289)

# 6.0.15

- Fixed: Node#prev and Node#next type for the first/last node

# 6.0.14

- Fixed: type definitions

# 6.0.13

- Fixed: throw on unexpected pipe symbols

# 6.0.12

- Fixed: `clone` arguments should be optional

# 6.0.11

- Fixed: parse attribute case insensitivity flag

# 6.0.10

- Fixed: `isPseudoElement()` supports `:first-letter` and `:first-line`

# 6.0.9

- Fixed: `Combinator.raws` property type

# 6.0.8

- Fixed: reduced size

# 6.0.7

- Fixed: parse animation percents

# 6.0.6

- Fixed: parse quoted attributes containing a newline correctly

# 6.0.5

- Perf: rework unesc for a 63+% performance boost

# 6.0.4

- Fixed: ts errors

# 6.0.3

- Fixed: replace node built-in "util" module with "util-deprecate"
- Fixed: handle uppercase pseudo elements
- Fixed: do not create invalid combinator before comment

# 6.0.2

- Fixed an issue with parsing and stringifying an empty attribute value

# 6.0.1

- Fixed an issue with unicode surrogate pair parsing

# 6.0.0

- Updated: `cssesc` to 3.0.0 (major)
- Fixed: Issues with escaped `id` and `class` selectors

# 5.0.0

- Allow escaped dot within class name.
- Update PostCSS to 7.0.7 (patch)

# 5.0.0-rc.4

- Fixed an issue where comments immediately after an insensitive (in attribute)
  were not parsed correctly.
- Updated `cssesc` to 2.0.0 (major).
- Removed outdated integration tests.
- Added tests for custom selectors, tags with attributes, the universal
  selector with pseudos, and tokens after combinators.

# 5.0.0-rc.1

To ease adoption of the v5.0 release, we have relaxed the node version
check performed by npm at installation time to allow for node 4, which
remains officially unsupported, but likely to continue working for the
time being.

# 5.0.0-rc.0

This release has **BREAKING CHANGES** that were required to fix regressions
in 4.0.0 and to make the Combinator Node API consistent for all combinator
types. Please read carefully.

## Summary of Changes

* The way a descendent combinator that isn't a single space character (E.g. `.a  .b`) is stored in the AST has changed.
* Named Combinators (E.g. `.a /for/ .b`) are now properly parsed as a combinator.
* It is now possible to look up a node based on the source location of a character in that node and to query nodes if they contain some character.
* Several bug fixes that caused the parser to hang and run out of memory when a `/` was encountered have been fixed.
* The minimum supported version of Node is now `v6.0.0`.

### Changes to the Descendent Combinator

In prior releases, the value of a descendant combinator with multiple spaces included all the spaces.

* `.a   .b`: Extra spaces are now stored as space before.
  - Old & Busted:
    - `combinator.value === "   "`
  - New hotness:
    - `combinator.value === " " && combinator.spaces.before === "  "`
* `.a   /*comment*/.b`: A comment at the end of the combinator causes extra space to become after space.
  - Old & Busted:
    - `combinator.value === "   "`
    - `combinator.raws.value === "   /*comment/"`
  - New hotness:
    - `combinator.value === " "`
    - `combinator.spaces.after === "  "`
    - `combinator.raws.spaces.after === "  /*comment*/"`
* `.a<newline>.b`: whitespace that doesn't start or end with a single space character is stored as a raw value.
  - Old & Busted:
    - `combinator.value === "\n"`
    - `combinator.raws.value === undefined`
  - New hotness:
    - `combinator.value === " "`
    - `combinator.raws.value === "\n"`

### Support for "Named Combinators"

Although, nonstandard and unlikely to ever become a standard, combinators like `/deep/` and `/for/` are now properly supported.

Because they've been taken off the standardization track, there is no spec-official name for combinators of the form `/<ident>/`. However, I talked to [Tab Atkins](https://twitter.com/tabatkins) and we agreed to call them "named combinators" so now they are called that.

Before this release such named combinators were parsed without intention and generated three nodes of type `"tag"` where the first and last nodes had a value of `"/"`.

* `.a /for/ .b` is parsed as a combinator.
  - Old & Busted:
    - `root.nodes[0].nodes[1].type === "tag"`
    - `root.nodes[0].nodes[1].value === "/"`
  - New hotness:
    - `root.nodes[0].nodes[1].type === "combinator"`
    - `root.nodes[0].nodes[1].value === "/for/"`
* `.a /F\6fR/ .b` escapes are handled and uppercase is normalized.
  - Old & Busted:
    - `root.nodes[0].nodes[2].type === "tag"`
    - `root.nodes[0].nodes[2].value === "F\\6fR"`
  - New hotness:
    - `root.nodes[0].nodes[1].type === "combinator"`
    - `root.nodes[0].nodes[1].value === "/for/"`
    - `root.nodes[0].nodes[1].raws.value === "/F\\6fR/"`

### Source position checks and lookups

A new API was added to look up a node based on the source location.

```js
const selectorParser = require("postcss-selector-parser");
// You can find the most specific node for any given character
let combinator = selectorParser.astSync(".a > .b").atPosition(1,4);
combinator.toString() === " > ";
// You can check if a node includes a specific character
// Whitespace surrounding the node that is owned by that node
// is included in the check.
[2,3,4,5,6].map(column => combinator.isAtPosition(1, column));
// => [false, true, true, true, false]
```

# 4.0.0

This release has **BREAKING CHANGES** that were required to fix bugs regarding values with escape sequences. Please read carefully.

* **Identifiers with escapes** - CSS escape sequences are now hidden from the public API by default.
  The normal value of a node like a class name or ID, or an aspect of a node such as attribute
  selector's value, is unescaped. Escapes representing Non-ascii characters are unescaped into
  unicode characters. For example: `bu\tton, .\31 00, #i\2764\FE0Fu, [attr="value is \"quoted\""]`
  will parse respectively to the values `button`, `100`, `i❤️u`, `value is "quoted"`.
  The original escape sequences for these values can be found in the corresponding property name
  in `node.raws`. Where possible, deprecation warnings were added, but the nature
  of escape handling makes it impossible to detect what is escaped or not. Our expectation is
  that most users are neither expecting nor handling escape sequences in their use of this library,
  and so for them, this is a bug fix. Users who are taking care to handle escapes correctly can
  now update their code to remove the escape handling and let us do it for them.

* **Mutating values with escapes** - When you make an update to a node property that has escape handling
  The value is assumed to be unescaped, and any special characters are escaped automatically and
  the corresponding `raws` value is immediately updated. This can result in changes to the original
  escape format. Where the exact value of the escape sequence is important there are methods that
  allow both values to be set in conjunction. There are a number of new convenience methods for
  manipulating values that involve escapes, especially for attributes values where the quote mark
  is involved. See https://github.com/postcss/postcss-selector-parser/pull/133 for an extensive
  write-up on these changes.


**Upgrade/API Example**

In `3.x` there was no unescape handling and internal consistency of several properties was the caller's job to maintain. It was very easy for the developer
to create a CSS file that did not parse correctly when some types of values
were in use.

```js
const selectorParser = require("postcss-selector-parser");
let attr = selectorParser.attribute({attribute: "id", operator: "=", value: "a-value"});
attr.value; // => "a-value"
attr.toString(); // => [id=a-value]
// Add quotes to an attribute's value.
// All these values have to be set by the caller to be consistent:
// no internal consistency is maintained.
attr.raws.unquoted = attr.value
attr.value = "'" + attr.value + "'";
attr.value; // => "'a-value'"
attr.quoted = true;
attr.toString();  // => "[id='a-value']"
```

In `4.0` there is a convenient API for setting and mutating values
that may need escaping. Especially for attributes.

```js
const selectorParser = require("postcss-selector-parser");

// The constructor requires you specify the exact escape sequence
let className = selectorParser.className({value: "illegal class name", raws: {value: "illegal\\ class\\ name"}});
className.toString(); // => '.illegal\\ class\\ name'

// So it's better to set the value as a property
className = selectorParser.className();
// Most properties that deal with identifiers work like this
className.value = "escape for me";
className.value; // => 'escape for me'
className.toString(); // => '.escape\\ for\\ me'

// emoji and all non-ascii are escaped to ensure it works in every css file.
className.value = "😱🦄😍";
className.value; // => '😱🦄😍'
className.toString(); // => '.\\1F631\\1F984\\1F60D'

// you can control the escape sequence if you want, or do bad bad things
className.setPropertyAndEscape('value', 'xxxx', 'yyyy');
className.value; // => "xxxx"
className.toString(); // => ".yyyy"

// Pass a value directly through to the css output without escaping it. 
className.setPropertyWithoutEscape('value', '$REPLACE_ME$');
className.value; // => "$REPLACE_ME$"
className.toString(); // => ".$REPLACE_ME$"

// The biggest changes are to the Attribute class
// passing quoteMark explicitly is required to avoid a deprecation warning.
let attr = selectorParser.attribute({attribute: "id", operator: "=", value: "a-value", quoteMark: null});
attr.toString(); // => "[id=a-value]"
// Get the value with quotes on it and any necessary escapes.
// This is the same as reading attr.value in 3.x.
attr.getQuotedValue(); // => "a-value";
attr.quoteMark; // => null

// Add quotes to an attribute's value.
attr.quoteMark = "'"; // This is all that's required.
attr.toString(); // => "[id='a-value']"
attr.quoted; // => true
// The value is still the same, only the quotes have changed.
attr.value; // => a-value
attr.getQuotedValue(); // => "'a-value'";

// deprecated assignment, no warning because there's no escapes
attr.value = "new-value";
// no quote mark is needed so it is removed
attr.getQuotedValue(); // => "new-value";

// deprecated assignment, 
attr.value = "\"a 'single quoted' value\"";
// > (node:27859) DeprecationWarning: Assigning an attribute a value containing characters that might need to be escaped is deprecated. Call attribute.setValue() instead.
attr.getQuotedValue(); // => '"a \'single quoted\' value"';
// quote mark inferred from first and last characters.
attr.quoteMark; // => '"'

// setValue takes options to make manipulating the value simple.
attr.setValue('foo', {smart: true});
// foo doesn't require any escapes or quotes.
attr.toString(); // => '[id=foo]'
attr.quoteMark; // => null 

// An explicit quote mark can be specified
attr.setValue('foo', {quoteMark: '"'});
attr.toString(); // => '[id="foo"]'

// preserves quote mark by default
attr.setValue('bar');
attr.toString(); // => '[id="bar"]'
attr.quoteMark = null;
attr.toString(); // => '[id=bar]'

// with no arguments, it preserves quote mark even when it's not a great idea
attr.setValue('a value \n that should be quoted');
attr.toString(); // => '[id=a\\ value\\ \\A\\ that\\ should\\ be\\ quoted]'

// smart preservation with a specified default
attr.setValue('a value \n that should be quoted', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => "[id='a value \\A  that should be quoted']"
attr.quoteMark = '"';
// => '[id="a value \\A  that should be quoted"]'

// this keeps double quotes because it wants to quote the value and the existing value has double quotes.
attr.setValue('this should be quoted', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => '[id="this should be quoted"]'

// picks single quotes because the value has double quotes
attr.setValue('a "double quoted" value', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => "[id='a "double quoted" value']"

// setPropertyAndEscape lets you do anything you want. Even things that are a bad idea and illegal.
attr.setPropertyAndEscape('value', 'xxxx', 'the password is 42');
attr.value; // => "xxxx"
attr.toString(); // => "[id=the password is 42]"

// Pass a value directly through to the css output without escaping it. 
attr.setPropertyWithoutEscape('value', '$REPLACEMENT$');
attr.value; // => "$REPLACEMENT$"
attr.toString(); // => "[id=$REPLACEMENT$]"
```

# 3.1.2

* Fix: Removed dot-prop dependency since it's no longer written in es5.

# 3.1.1

* Fix: typescript definitions weren't in the published package.

# 3.1.0

* Fixed numerous bugs in attribute nodes relating to the handling of comments
  and whitespace. There's significant changes to `attrNode.spaces` and `attrNode.raws` since the `3.0.0` release.
* Added `Attribute#offsetOf(part)` to get the offset location of
  attribute parts like `"operator"` and `"value"`. This is most
  often added to `Attribute#sourceIndex` for error reporting.

# 3.0.0

## Breaking changes

* Some tweaks to the tokenizer/attribute selector parsing mean that whitespace
  locations might be slightly different to the 2.x code.
* Better attribute selector parsing with more validation; postcss-selector-parser
  no longer uses regular expressions to parse attribute selectors.
* Added an async API (thanks to @jacobp100); the default `process` API is now
  async, and the sync API is now accessed through `processSync` instead.
* `process()` and `processSync()` now return a string instead of the Processor
  instance.
* Tweaks handling of Less interpolation (thanks to @jwilsson).
* Removes support for Node 0.12.

## Other changes

* `ast()` and `astSync()` methods have been added to the `Processor`. These
  return the `Root` node of the selectors after processing them.
* `transform()` and `transformSync()` methods have been added to the
  `Processor`. These return the value returned by the processor callback
  after processing the selectors.
* Set the parent when inserting a node (thanks to @chriseppstein).
* Correctly adjust indices when using insertBefore/insertAfter (thanks to @tivac).
* Fixes handling of namespaces with qualified tag selectors.
* `process`, `ast` and `transform` (and their sync variants) now accept a
  `postcss` rule node. When provided, better errors are generated and selector
  processing is automatically set back to the rule selector (unless the `updateSelector` option is set to `false`.)
* Now more memory efficient when tokenizing selectors.

### Upgrade hints

The pattern of:

`rule.selector = processor.process(rule.selector).result.toString();`

is now:

`processor.processSync(rule)`

# 2.2.3

* Resolves an issue where the parser would not reduce multiple spaces between an
  ampersand and another simple selector in lossy mode (thanks to @adam-26).

# 2.2.2

* No longer hangs on an unescaped semicolon; instead the parser will throw
  an exception for these cases.

# 2.2.1

* Allows a consumer to specify whitespace tokens when creating a new Node
  (thanks to @Semigradsky).

# 2.2.0

* Added a new option to normalize whitespace when parsing the selector string
  (thanks to @adam-26).

# 2.1.1

* Better unquoted value handling within attribute selectors
  (thanks to @evilebottnawi).

# 2.1.0

* Added: Use string constants for all node types & expose them on the main
  parser instance (thanks to @Aweary).

# 2.0.0

This release contains the following breaking changes:

* Renamed all `eachInside` iterators to `walk`. For example, `eachTag` is now
  `walkTags`, and `eachInside` is now `walk`.
* Renamed `Node#removeSelf()` to `Node#remove()`.
* Renamed `Container#remove()` to `Container#removeChild()`.
* Renamed `Node#raw` to `Node#raws` (thanks to @davidtheclark).
* Now parses `&` as the *nesting* selector, rather than a *tag* selector.
* Fixes misinterpretation of Sass interpolation (e.g. `#{foo}`) as an
  id selector (thanks to @davidtheclark).

and;

* Fixes parsing of attribute selectors with equals signs in them
  (e.g. `[data-attr="foo=bar"]`) (thanks to @montmanu).
* Adds `quoted` and `raw.unquoted` properties to attribute nodes
  (thanks to @davidtheclark).

# 1.3.3

* Fixes an infinite loop on `)` and `]` tokens when they had no opening pairs.
  Now postcss-selector-parser will throw when it encounters these lone tokens.

# 1.3.2

* Now uses plain integers rather than `str.charCodeAt(0)` for compiled builds.

# 1.3.1

* Update flatten to v1.x (thanks to @shinnn).

# 1.3.0

* Adds a new node type, `String`, to fix a crash on selectors such as
  `foo:bar("test")`.

# 1.2.1

* Fixes a crash when the parser encountered a trailing combinator.

# 1.2.0

* A more descriptive error is thrown when the parser expects to find a
  pseudo-class/pseudo-element (thanks to @ashelley).
* Adds support for line/column locations for selector nodes, as well as a
  `Node#sourceIndex` method (thanks to @davidtheclark).

# 1.1.4

* Fixes a crash when a selector started with a `>` combinator. The module will
  now no longer throw if a selector has a leading/trailing combinator node.

# 1.1.3

* Fixes a crash on `@` tokens.

# 1.1.2

* Fixes an infinite loop caused by using parentheses in a non-pseudo element
  context.

# 1.1.1

* Fixes a crash when a backslash ended a selector string.

# 1.1.0

* Adds support for replacing multiple nodes at once with `replaceWith`
  (thanks to @jonathantneal).
* Parser no longer throws on sequential IDs and trailing commas, to support
  parsing of selector hacks.

# 1.0.1

* Fixes using `insertAfter` and `insertBefore` during iteration.

# 1.0.0

* Adds `clone` and `replaceWith` methods to nodes.
* Adds `insertBefore` and `insertAfter` to containers.
* Stabilises API.

# 0.0.5

* Fixes crash on extra whitespace inside a pseudo selector's parentheses.
* Adds sort function to the container class.
* Enables the parser to pass its input through without transforming.
* Iteration-safe `each` and `eachInside`.

# 0.0.4

* Tidy up redundant duplication.
* Fixes a bug where the parser would loop infinitely on universal selectors
  inside pseudo selectors.
* Adds `length` getter and `eachInside`, `map`, `reduce` to the container class.
* When a selector has been removed from the tree, the root node will no longer
  cast it to a string.
* Adds node type iterators to the container class (e.g. `eachComment`).
* Adds filter function to the container class.
* Adds split function to the container class.
* Create new node types by doing `parser.id(opts)` etc.
* Adds support for pseudo classes anywhere in the selector.

# 0.0.3

* Adds `next` and `prev` to the node class.
* Adds `first` and `last` getters to the container class.
* Adds `every` and `some` iterators to the container class.
* Add `empty` alias for `removeAll`.
* Combinators are now types of node.
* Fixes the at method so that it is not an alias for `index`.
* Tidy up creation of new nodes in the parser.
* Refactors how namespaces are handled for consistency & less redundant code.
* Refactors AST to use `nodes` exclusively, and eliminates excessive nesting.
* Fixes nested pseudo parsing.
* Fixes whitespace parsing.

# 0.0.2

* Adds support for namespace selectors.
* Adds support for selectors joined by escaped spaces - such as `.\31\ 0`.

# 0.0.1

* Initial release.


---

# postcss-selector-parser [![test](https://github.com/postcss/postcss-selector-parser/actions/workflows/test.yml/badge.svg)](https://github.com/postcss/postcss-selector-parser/actions/workflows/test.yml)

> Selector parser with built in methods for working with selector strings.

## Install

With [npm](https://npmjs.com/package/postcss-selector-parser) do:

```
npm install postcss-selector-parser
```

## Quick Start

```js
const parser = require('postcss-selector-parser');
const transform = selectors => {
    selectors.walk(selector => {
        // do something with the selector
        console.log(String(selector))
    });
};

const transformed = parser(transform).processSync('h1, h2, h3');
```

To normalize selector whitespace:

```js
const parser = require('postcss-selector-parser');
const normalized = parser().processSync('h1, h2, h3', {lossless: false});
// -> h1,h2,h3
```

Async support is provided through `parser.process` and will resolve a Promise
with the resulting selector string.

## API

Please see [API.md](API.md).

## Credits

* Huge thanks to Andrey Sitnik (@ai) for work on PostCSS which helped
  accelerate this module's development.

## License

MIT


---

# API Documentation

*Please use only this documented API when working with the parser. Methods
not documented here are subject to change at any point.*

## `parser` function

This is the module's main entry point.

```js
const parser = require('postcss-selector-parser');
```

### `parser([transform], [options])`

Creates a new `processor` instance

```js
const processor = parser();
```

Or, with optional transform function

```js
const transform = selectors => {
    selectors.walkUniversals(selector => {
        selector.remove();
    });
};

const processor = parser(transform)

// Example
const result = processor.processSync('*.class');
// => .class
```

[See processor documentation](#processor)

Arguments:

* `transform (function)`: Provide a function to work with the parsed AST.
* `options (object)`: Provide default options for all calls on the returned `Processor`.

### `parser.attribute([props])`

Creates a new attribute selector.

```js
parser.attribute({attribute: 'href'});
// => [href]
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.className([props])`

Creates a new class selector.

```js
parser.className({value: 'button'});
// => .button
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.combinator([props])`

Creates a new selector combinator.

```js
parser.combinator({value: '+'});
// => +
```

Arguments:

* `props (object)`: The new node's properties.

Notes:
* **Descendant Combinators** The value of descendant combinators created by the
  parser always just a single space (`" "`). For descendant selectors with no
  comments, additional space is now stored in `node.spaces.before`. Depending
  on the location of comments, additional spaces may be stored in
  `node.raws.spaces.before`, `node.raws.spaces.after`, or `node.raws.value`.
* **Named Combinators** Although, nonstandard and unlikely to ever become a standard,
  named combinators like `/deep/` and `/for/` are parsed as combinators. The
  `node.value` is name after being unescaped and normalized as lowercase. The
  original value for the combinator name is stored in `node.raws.value`.


### `parser.comment([props])`

Creates a new comment.

```js
parser.comment({value: '/* Affirmative, Dave. I read you. */'});
// => /* Affirmative, Dave. I read you. */
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.id([props])`

Creates a new id selector.

```js
parser.id({value: 'search'});
// => #search
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.nesting([props])`

Creates a new nesting selector.

```js
parser.nesting();
// => &
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.pseudo([props])`

Creates a new pseudo selector.

```js
parser.pseudo({value: '::before'});
// => ::before
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.root([props])`

Creates a new root node.

```js
parser.root();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.selector([props])`

Creates a new selector node.

```js
parser.selector();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.string([props])`

Creates a new string node.

```js
parser.string();
// => (empty)
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.tag([props])`

Creates a new tag selector.

```js
parser.tag({value: 'button'});
// => button
```

Arguments:

* `props (object)`: The new node's properties.

### `parser.universal([props])`

Creates a new universal selector.

```js
parser.universal();
// => *
```

Arguments:

* `props (object)`: The new node's properties.

## Node types

### `node.type`

A string representation of the selector type. It can be one of the following;
`attribute`, `class`, `combinator`, `comment`, `id`, `nesting`, `pseudo`,
`root`, `selector`, `string`, `tag`, or `universal`. Note that for convenience,
these constants are exposed on the main `parser` as uppercased keys. So for
example you can get `id` by querying `parser.ID`.

```js
parser.attribute({attribute: 'href'}).type;
// => 'attribute'
```

### `node.parent`

Returns the parent node.

```js
root.nodes[0].parent === root;
```

### `node.toString()`, `String(node)`, or `'' + node`

Returns a string representation of the node.

```js
const id = parser.id({value: 'search'});
console.log(String(id));
// => #search
```

### `node.next()` & `node.prev()`

Returns the next/previous child of the parent node.

```js
const next = id.next();
if (next && next.type !== 'combinator') {
    throw new Error('Qualified IDs are not allowed!');
}
```

### `node.replaceWith(node)`

Replace a node with another.

```js
const attr = selectors.first.first;
const className = parser.className({value: 'test'});
attr.replaceWith(className);
```

Arguments:

* `node`: The node to substitute the original with.

### `node.remove()`

Removes the node from its parent node.

```js
if (node.type === 'id') {
    node.remove();
}
```

### `node.clone([opts])`

Returns a copy of a node, detached from any parent containers that the
original might have had.

```js
const cloned = node.clone();
```

### `node.isAtPosition(line, column)`

Return a `boolean` indicating whether this node includes the character at the
position of the given line and column. Returns `undefined` if the nodes lack
sufficient source metadata to determine the position.

Arguments:

* `line`: 1-index based line number relative to the start of the selector.
* `column`: 1-index based column number relative to the start of the selector.

### `node.spaces`

Extra whitespaces around the node will be moved into `node.spaces.before` and
`node.spaces.after`. So for example, these spaces will be moved as they have
no semantic meaning:

```css
      h1     ,     h2   {}
```

For descendent selectors, the value is always a single space.

```css
h1        h2 {}
```

Additional whitespace is found in either the `node.spaces.before` and `node.spaces.after` depending on the presence of comments or other whitespace characters. If the actual whitespace does not start or end with a single space, the node's raw value is set to the actual space(s) found in the source.

### `node.source`

An object describing the node's start/end, line/column source position.

Within the following CSS, the `.bar` class node ...

```css
.foo,
  .bar {}
```

... will contain the following `source` object.

```js
source: {
    start: {
        line: 2,
        column: 3
    },
    end: {
        line: 2,
        column: 6
    }
}
```

### `node.sourceIndex`

The zero-based index of the node within the original source string.

Within the following CSS, the `.baz` class node will have a `sourceIndex` of `12`.

```css
.foo, .bar, .baz {}
```

## Container types

The `root`, `selector`, and `pseudo` nodes have some helper methods for working
with their children.

### `container.nodes`

An array of the container's children.

```js
// Input: h1 h2
selectors.at(0).nodes.length   // => 3
selectors.at(0).nodes[0].value // => 'h1'
selectors.at(0).nodes[1].value // => ' '
```

### `container.first` & `container.last`

The first/last child of the container.

```js
selector.first === selector.nodes[0];
selector.last === selector.nodes[selector.nodes.length - 1];
```

### `container.at(index)`

Returns the node at position `index`.

```js
selector.at(0) === selector.first;
selector.at(0) === selector.nodes[0];
```

Arguments:

* `index`: The index of the node to return.

### `container.atPosition(line, column)`

Returns the node at the source position `line` and `column`.

```js
// Input: :not(.foo),\n#foo > :matches(ol, ul)
selector.atPosition(1, 1); // => :not(.foo)
selector.atPosition(2, 1); // => \n#foo
```

Arguments:

* `line`: The line number of the node to return.
* `column`: The column number of the node to return.

### `container.index(node)`

Return the index of the node within its container.

```js
selector.index(selector.nodes[2]) // => 2
```

Arguments:

* `node`: A node within the current container.

### `container.length`

Proxy to the length of the container's nodes.

```js
container.length === container.nodes.length
```

### `container` Array iterators

The container class provides proxies to certain Array methods; these are:

* `container.map === container.nodes.map`
* `container.reduce === container.nodes.reduce`
* `container.every === container.nodes.every`
* `container.some === container.nodes.some`
* `container.filter === container.nodes.filter`
* `container.sort === container.nodes.sort`

Note that these methods only work on a container's immediate children; recursive
iteration is provided by `container.walk`.

### `container.each(callback)`

Iterate the container's immediate children, calling `callback` for each child.
You may return `false` within the callback to break the iteration.

```js
let className;
selectors.each((selector, index) => {
    if (selector.type === 'class') {
        className = selector.value;
        return false;
    }
});
```

Note that unlike `Array#forEach()`, this iterator is safe to use whilst adding
or removing nodes from the container.

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  and `index` arguments.

### `container.walk(callback)`

Like `container#each`, but will also iterate child nodes as long as they are
`container` types.

```js
selectors.walk((selector, index) => {
    // all nodes
});
```

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  and `index` arguments.

This iterator is safe to use whilst mutating `container.nodes`,
like `container#each`.

### `container.walk` proxies

The container class provides proxy methods for iterating over types of nodes,
so that it is easier to write modules that target specific selectors. Those
methods are:

* `container.walkAttributes`
* `container.walkClasses`
* `container.walkCombinators`
* `container.walkComments`
* `container.walkIds`
* `container.walkNesting`
* `container.walkPseudos`
* `container.walkTags`
* `container.walkUniversals`

### `container.split(callback)`

This method allows you to split a group of nodes by returning `true` from
a callback. It returns an array of arrays, where each inner array corresponds
to the groups that you created via the callback.

```js
// (input) => h1 h2>>h3
const list = selectors.first.split(selector => {
    return selector.type === 'combinator';
});

// (node values) => [['h1', ' '], ['h2', '>>'], ['h3']]
```

Arguments:

* `callback (function)`: A function to call for each node, which receives `node`
  as an argument.

### `container.prepend(node)` & `container.append(node)`

Add a node to the start/end of the container. Note that doing so will set
the parent property of the node to this container.

```js
const id = parser.id({value: 'search'});
selector.append(id);
```

Arguments:

* `node`: The node to add.

### `container.insertBefore(old, new)` & `container.insertAfter(old, new)`

Add a node before or after an existing node in a container:

```js
selectors.walk(selector => {
    if (selector.type !== 'class') {
        const className = parser.className({value: 'theme-name'});
        selector.parent.insertAfter(selector, className);
    }
});
```

Arguments:

* `old`: The existing node in the container.
* `new`: The new node to add before/after the existing node.

### `container.removeChild(node)`

Remove the node from the container. Note that you can also use
`node.remove()` if you would like to remove just a single node.

```js
selector.length // => 2
selector.remove(id)
selector.length // => 1;
id.parent       // undefined
```

Arguments:

* `node`: The node to remove.

### `container.removeAll()` or `container.empty()`

Remove all children from the container.

```js
selector.removeAll();
selector.length // => 0
```

## Root nodes

A root node represents a comma separated list of selectors. Indeed, all
a root's `toString()` method does is join its selector children with a ','.
Other than this, it has no special functionality and acts like a container.

### `root.trailingComma`

This will be set to `true` if the input has a trailing comma, in order to
support parsing of legacy CSS hacks.

## Selector nodes

A selector node represents a single complex selector. For example, this
selector string `h1 h2 h3, [href] > p`, is represented as two selector nodes.
It has no special functionality of its own.

## Pseudo nodes

A pseudo selector extends a container node; if it has any parameters of its
own (such as `h1:not(h2, h3)`), they will be its children. Note that the pseudo
`value` will always contain the colons preceding the pseudo identifier. This
is so that both `:before` and `::before` are properly represented in the AST.

## Attribute nodes

### `attribute.quoted`

Returns `true` if the attribute's value is wrapped in quotation marks, false if it is not.
Remains `undefined` if there is no attribute value.

```css
[href=foo] /* false */
[href='foo'] /* true */
[href="foo"] /* true */
[href] /* undefined */
```

### `attribute.qualifiedAttribute`

Returns the attribute name qualified with the namespace if one is given.

### `attribute.offsetOf(part)`

 Returns the offset of the attribute part specified relative to the
 start of the node of the output string. This is useful in raising
 error messages about a specific part of the attribute, especially
 in combination with `attribute.sourceIndex`.

 Returns `-1` if the name is invalid or the value doesn't exist in this
 attribute.

 The legal values for `part` are:

 * `"ns"` - alias for "namespace"
 * `"namespace"` - the namespace if it exists.
 * `"attribute"` - the attribute name
 * `"attributeNS"` - the start of the attribute or its namespace
 * `"operator"` - the match operator of the attribute
 * `"value"` - The value (string or identifier)
 * `"insensitive"` - the case insensitivity flag

### `attribute.raws.unquoted`

Returns the unquoted content of the attribute's value.
Remains `undefined` if there is no attribute value.

```css
[href=foo] /* foo */
[href='foo'] /* foo */
[href="foo"] /* foo */
[href] /* undefined */
```

### `attribute.spaces`

Like `node.spaces` with the `before` and `after` values containing the spaces
around the element, the parts of the attribute can also have spaces before
and after them. The for each of `attribute`, `operator`, `value` and
`insensitive` there is corresponding property of the same nam in
`node.spaces` that has an optional `before` or `after` string containing only
whitespace.

Note that corresponding values in `attributes.raws.spaces` contain values
including any comments. If set, these values will override the
`attribute.spaces` value. Take care to remove them if changing
`attribute.spaces`.

### `attribute.raws`

The raws object stores comments and other information necessary to re-render
the node exactly as it was in the source.

If a comment is embedded within the identifiers for the `namespace`, `attribute`
or `value` then a property is placed in the raws for that value containing the full source of the propery including comments.

If a comment is embedded within the space between parts of the attribute
then the raw for that space is set accordingly.

Setting an attribute's property `raws` value to be deleted.

For now, changing the spaces required also updating or removing any of the
raws values that override them.

Example: `[ /*before*/ href /* after-attr */ = /* after-operator */ te/*inside-value*/st/* wow */ /*omg*/i/*bbq*/ /*whodoesthis*/]` would parse as:

```js
{
  attribute: "href",
  operator: "=",
  value: "test",
  spaces: {
    before: '',
    after: '',
    attribute: { before: '  ', after: '  ' },
    operator: { after: '  ' },
    value: { after: ' ' },
    insensitive: { after: ' ' }
  },
  raws: {
    spaces: {
      attribute: { before: ' /*before*/ ', after: ' /* after-attr */ ' },
      operator: { after: ' /* after-operator */ ' },
      value: { after: '/* wow */ /*omg*/' },
      insensitive: { after: '/*bbq*/ /*whodoesthis*/' }
    },
    unquoted: 'test',
    value: 'te/*inside-value*/st'
  }
}
```

## `Processor`

### `ProcessorOptions`

* `lossless` - When `true`, whitespace is preserved. Defaults to `true`.
* `updateSelector` - When `true`, if any processor methods are passed a postcss
  `Rule` node instead of a string, then that Rule's selector is updated
  with the results of the processing. Defaults to `true`.

### `process|processSync(selectors, [options])`

Processes the `selectors`, returning a string from the result of processing.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

**Example:**

```js
const parser = require("postcss-selector-parser");
const processor = parser();

let result = processor.processSync(' .class');
console.log(result);
// =>  .class

// Asynchronous operation
let promise = processor.process(' .class').then(result => {
    console.log(result)
    // => .class
});

// To have the parser normalize whitespace values, utilize the options
result = processor.processSync('  .class  ', {lossless: false});
console.log(result);
// => .class

// For better syntax errors, pass a PostCSS Rule node.
const postcss = require('postcss');
rule = postcss.rule({selector: ' #foo    > a,  .class  '});
processor.process(rule, {lossless: false, updateSelector: true}).then(result => {
    console.log(result);
    // => #foo>a,.class
    console.log("rule:", rule.selector);
    // => rule: #foo>a,.class
})
```

Arguments:

* `selectors (string|postcss.Rule)`: Either a selector string or a PostCSS Rule
  node.
* `[options] (object)`: Process options


### `ast|astSync(selectors, [options])`

Like `process()` and `processSync()` but after
processing the `selectors` these methods return the `Root` node of the result
instead of a string.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

### `transform|transformSync(selectors, [options])`

Like `process()` and `processSync()` but after
processing the `selectors` these methods return the value returned by the
processor callback.

Note: when the `updateSelector` option is set, the rule's selector
will be updated with the resulting string.

### Error Handling Within Selector Processors

The root node passed to the selector processor callback
has a method `error(message, options)` that returns an
error object. This method should always be used to raise
errors relating to the syntax of selectors. The options
to this method are passed to postcss's error constructor
([documentation](http://postcss.org/api/#container-error)).

#### Async Error Example

```js
let processor = (root) => {
    return new Promise((resolve, reject) => {
        root.walkClasses((classNode) => {
            if (/^(.*)[-_]/.test(classNode.value)) {
                let msg = "classes may not have underscores or dashes in them";
                reject(root.error(msg, {
                    index: classNode.sourceIndex + RegExp.$1.length + 1,
                    word: classNode.value
                }));
            }
        });
        resolve();
    });
};

const postcss = require("postcss");
const parser = require("postcss-selector-parser");
const selectorProcessor = parser(processor);
const plugin = postcss.plugin('classValidator', (options) => {
    return (root) => {
        let promises = [];
        root.walkRules(rule => {
            promises.push(selectorProcessor.process(rule));
        });
        return Promise.all(promises);
    };
});
postcss(plugin()).process(`
.foo-bar {
  color: red;
}
`.trim(), {from: 'test.css'}).catch((e) => console.error(e.toString()));

// CssSyntaxError: classValidator: ./test.css:1:5: classes may not have underscores or dashes in them
//
// > 1 | .foo-bar {
//     |     ^
//   2 |   color: red;
//   3 | }
```

#### Synchronous Error Example

```js
let processor = (root) => {
    root.walkClasses((classNode) => {
        if (/.*[-_]/.test(classNode.value)) {
            let msg = "classes may not have underscores or dashes in them";
            throw root.error(msg, {
                index: classNode.sourceIndex,
                word: classNode.value
            });
        }
    });
};

const postcss = require("postcss");
const parser = require("postcss-selector-parser");
const selectorProcessor = parser(processor);
const plugin = postcss.plugin('classValidator', (options) => {
    return (root) => {
        root.walkRules(rule => {
            selectorProcessor.processSync(rule);
        });
    };
});
postcss(plugin()).process(`
.foo-bar {
  color: red;
}
`.trim(), {from: 'test.css'}).catch((e) => console.error(e.toString()));

// CssSyntaxError: classValidator: ./test.css:1:5: classes may not have underscores or dashes in them
//
// > 1 | .foo-bar {
//     |     ^
//   2 |   color: red;
//   3 | }
```


---

# 6.1.2

- Fixed: erroneous trailing combinators in pseudos

# 6.1.1

- Fixed: improve typings of constructor helpers (#292)

# 6.1.0

- Feature: add `sourceIndex` to `Selector` nodes (#290)

# 6.0.16

- Fixed: add missing `index` argument to `each`/`walk` callback types (#289)

# 6.0.15

- Fixed: Node#prev and Node#next type for the first/last node

# 6.0.14

- Fixed: type definitions

# 6.0.13

- Fixed: throw on unexpected pipe symbols

# 6.0.12

- Fixed: `clone` arguments should be optional

# 6.0.11

- Fixed: parse attribute case insensitivity flag

# 6.0.10

- Fixed: `isPseudoElement()` supports `:first-letter` and `:first-line`

# 6.0.9

- Fixed: `Combinator.raws` property type

# 6.0.8

- Fixed: reduced size

# 6.0.7

- Fixed: parse animation percents

# 6.0.6

- Fixed: parse quoted attributes containing a newline correctly

# 6.0.5

- Perf: rework unesc for a 63+% performance boost

# 6.0.4

- Fixed: ts errors

# 6.0.3

- Fixed: replace node built-in "util" module with "util-deprecate"
- Fixed: handle uppercase pseudo elements
- Fixed: do not create invalid combinator before comment

# 6.0.2

- Fixed an issue with parsing and stringifying an empty attribute value

# 6.0.1

- Fixed an issue with unicode surrogate pair parsing

# 6.0.0

- Updated: `cssesc` to 3.0.0 (major)
- Fixed: Issues with escaped `id` and `class` selectors

# 5.0.0

- Allow escaped dot within class name.
- Update PostCSS to 7.0.7 (patch)

# 5.0.0-rc.4

- Fixed an issue where comments immediately after an insensitive (in attribute)
  were not parsed correctly.
- Updated `cssesc` to 2.0.0 (major).
- Removed outdated integration tests.
- Added tests for custom selectors, tags with attributes, the universal
  selector with pseudos, and tokens after combinators.

# 5.0.0-rc.1

To ease adoption of the v5.0 release, we have relaxed the node version
check performed by npm at installation time to allow for node 4, which
remains officially unsupported, but likely to continue working for the
time being.

# 5.0.0-rc.0

This release has **BREAKING CHANGES** that were required to fix regressions
in 4.0.0 and to make the Combinator Node API consistent for all combinator
types. Please read carefully.

## Summary of Changes

* The way a descendent combinator that isn't a single space character (E.g. `.a  .b`) is stored in the AST has changed.
* Named Combinators (E.g. `.a /for/ .b`) are now properly parsed as a combinator.
* It is now possible to look up a node based on the source location of a character in that node and to query nodes if they contain some character.
* Several bug fixes that caused the parser to hang and run out of memory when a `/` was encountered have been fixed.
* The minimum supported version of Node is now `v6.0.0`.

### Changes to the Descendent Combinator

In prior releases, the value of a descendant combinator with multiple spaces included all the spaces.

* `.a   .b`: Extra spaces are now stored as space before.
  - Old & Busted:
    - `combinator.value === "   "`
  - New hotness:
    - `combinator.value === " " && combinator.spaces.before === "  "`
* `.a   /*comment*/.b`: A comment at the end of the combinator causes extra space to become after space.
  - Old & Busted:
    - `combinator.value === "   "`
    - `combinator.raws.value === "   /*comment/"`
  - New hotness:
    - `combinator.value === " "`
    - `combinator.spaces.after === "  "`
    - `combinator.raws.spaces.after === "  /*comment*/"`
* `.a<newline>.b`: whitespace that doesn't start or end with a single space character is stored as a raw value.
  - Old & Busted:
    - `combinator.value === "\n"`
    - `combinator.raws.value === undefined`
  - New hotness:
    - `combinator.value === " "`
    - `combinator.raws.value === "\n"`

### Support for "Named Combinators"

Although, nonstandard and unlikely to ever become a standard, combinators like `/deep/` and `/for/` are now properly supported.

Because they've been taken off the standardization track, there is no spec-official name for combinators of the form `/<ident>/`. However, I talked to [Tab Atkins](https://twitter.com/tabatkins) and we agreed to call them "named combinators" so now they are called that.

Before this release such named combinators were parsed without intention and generated three nodes of type `"tag"` where the first and last nodes had a value of `"/"`.

* `.a /for/ .b` is parsed as a combinator.
  - Old & Busted:
    - `root.nodes[0].nodes[1].type === "tag"`
    - `root.nodes[0].nodes[1].value === "/"`
  - New hotness:
    - `root.nodes[0].nodes[1].type === "combinator"`
    - `root.nodes[0].nodes[1].value === "/for/"`
* `.a /F\6fR/ .b` escapes are handled and uppercase is normalized.
  - Old & Busted:
    - `root.nodes[0].nodes[2].type === "tag"`
    - `root.nodes[0].nodes[2].value === "F\\6fR"`
  - New hotness:
    - `root.nodes[0].nodes[1].type === "combinator"`
    - `root.nodes[0].nodes[1].value === "/for/"`
    - `root.nodes[0].nodes[1].raws.value === "/F\\6fR/"`

### Source position checks and lookups

A new API was added to look up a node based on the source location.

```js
const selectorParser = require("postcss-selector-parser");
// You can find the most specific node for any given character
let combinator = selectorParser.astSync(".a > .b").atPosition(1,4);
combinator.toString() === " > ";
// You can check if a node includes a specific character
// Whitespace surrounding the node that is owned by that node
// is included in the check.
[2,3,4,5,6].map(column => combinator.isAtPosition(1, column));
// => [false, true, true, true, false]
```

# 4.0.0

This release has **BREAKING CHANGES** that were required to fix bugs regarding values with escape sequences. Please read carefully.

* **Identifiers with escapes** - CSS escape sequences are now hidden from the public API by default.
  The normal value of a node like a class name or ID, or an aspect of a node such as attribute
  selector's value, is unescaped. Escapes representing Non-ascii characters are unescaped into
  unicode characters. For example: `bu\tton, .\31 00, #i\2764\FE0Fu, [attr="value is \"quoted\""]`
  will parse respectively to the values `button`, `100`, `i❤️u`, `value is "quoted"`.
  The original escape sequences for these values can be found in the corresponding property name
  in `node.raws`. Where possible, deprecation warnings were added, but the nature
  of escape handling makes it impossible to detect what is escaped or not. Our expectation is
  that most users are neither expecting nor handling escape sequences in their use of this library,
  and so for them, this is a bug fix. Users who are taking care to handle escapes correctly can
  now update their code to remove the escape handling and let us do it for them.

* **Mutating values with escapes** - When you make an update to a node property that has escape handling
  The value is assumed to be unescaped, and any special characters are escaped automatically and
  the corresponding `raws` value is immediately updated. This can result in changes to the original
  escape format. Where the exact value of the escape sequence is important there are methods that
  allow both values to be set in conjunction. There are a number of new convenience methods for
  manipulating values that involve escapes, especially for attributes values where the quote mark
  is involved. See https://github.com/postcss/postcss-selector-parser/pull/133 for an extensive
  write-up on these changes.


**Upgrade/API Example**

In `3.x` there was no unescape handling and internal consistency of several properties was the caller's job to maintain. It was very easy for the developer
to create a CSS file that did not parse correctly when some types of values
were in use.

```js
const selectorParser = require("postcss-selector-parser");
let attr = selectorParser.attribute({attribute: "id", operator: "=", value: "a-value"});
attr.value; // => "a-value"
attr.toString(); // => [id=a-value]
// Add quotes to an attribute's value.
// All these values have to be set by the caller to be consistent:
// no internal consistency is maintained.
attr.raws.unquoted = attr.value
attr.value = "'" + attr.value + "'";
attr.value; // => "'a-value'"
attr.quoted = true;
attr.toString();  // => "[id='a-value']"
```

In `4.0` there is a convenient API for setting and mutating values
that may need escaping. Especially for attributes.

```js
const selectorParser = require("postcss-selector-parser");

// The constructor requires you specify the exact escape sequence
let className = selectorParser.className({value: "illegal class name", raws: {value: "illegal\\ class\\ name"}});
className.toString(); // => '.illegal\\ class\\ name'

// So it's better to set the value as a property
className = selectorParser.className();
// Most properties that deal with identifiers work like this
className.value = "escape for me";
className.value; // => 'escape for me'
className.toString(); // => '.escape\\ for\\ me'

// emoji and all non-ascii are escaped to ensure it works in every css file.
className.value = "😱🦄😍";
className.value; // => '😱🦄😍'
className.toString(); // => '.\\1F631\\1F984\\1F60D'

// you can control the escape sequence if you want, or do bad bad things
className.setPropertyAndEscape('value', 'xxxx', 'yyyy');
className.value; // => "xxxx"
className.toString(); // => ".yyyy"

// Pass a value directly through to the css output without escaping it. 
className.setPropertyWithoutEscape('value', '$REPLACE_ME$');
className.value; // => "$REPLACE_ME$"
className.toString(); // => ".$REPLACE_ME$"

// The biggest changes are to the Attribute class
// passing quoteMark explicitly is required to avoid a deprecation warning.
let attr = selectorParser.attribute({attribute: "id", operator: "=", value: "a-value", quoteMark: null});
attr.toString(); // => "[id=a-value]"
// Get the value with quotes on it and any necessary escapes.
// This is the same as reading attr.value in 3.x.
attr.getQuotedValue(); // => "a-value";
attr.quoteMark; // => null

// Add quotes to an attribute's value.
attr.quoteMark = "'"; // This is all that's required.
attr.toString(); // => "[id='a-value']"
attr.quoted; // => true
// The value is still the same, only the quotes have changed.
attr.value; // => a-value
attr.getQuotedValue(); // => "'a-value'";

// deprecated assignment, no warning because there's no escapes
attr.value = "new-value";
// no quote mark is needed so it is removed
attr.getQuotedValue(); // => "new-value";

// deprecated assignment, 
attr.value = "\"a 'single quoted' value\"";
// > (node:27859) DeprecationWarning: Assigning an attribute a value containing characters that might need to be escaped is deprecated. Call attribute.setValue() instead.
attr.getQuotedValue(); // => '"a \'single quoted\' value"';
// quote mark inferred from first and last characters.
attr.quoteMark; // => '"'

// setValue takes options to make manipulating the value simple.
attr.setValue('foo', {smart: true});
// foo doesn't require any escapes or quotes.
attr.toString(); // => '[id=foo]'
attr.quoteMark; // => null 

// An explicit quote mark can be specified
attr.setValue('foo', {quoteMark: '"'});
attr.toString(); // => '[id="foo"]'

// preserves quote mark by default
attr.setValue('bar');
attr.toString(); // => '[id="bar"]'
attr.quoteMark = null;
attr.toString(); // => '[id=bar]'

// with no arguments, it preserves quote mark even when it's not a great idea
attr.setValue('a value \n that should be quoted');
attr.toString(); // => '[id=a\\ value\\ \\A\\ that\\ should\\ be\\ quoted]'

// smart preservation with a specified default
attr.setValue('a value \n that should be quoted', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => "[id='a value \\A  that should be quoted']"
attr.quoteMark = '"';
// => '[id="a value \\A  that should be quoted"]'

// this keeps double quotes because it wants to quote the value and the existing value has double quotes.
attr.setValue('this should be quoted', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => '[id="this should be quoted"]'

// picks single quotes because the value has double quotes
attr.setValue('a "double quoted" value', {smart: true, preferCurrentQuoteMark: true, quoteMark: "'"});
// => "[id='a "double quoted" value']"

// setPropertyAndEscape lets you do anything you want. Even things that are a bad idea and illegal.
attr.setPropertyAndEscape('value', 'xxxx', 'the password is 42');
attr.value; // => "xxxx"
attr.toString(); // => "[id=the password is 42]"

// Pass a value directly through to the css output without escaping it. 
attr.setPropertyWithoutEscape('value', '$REPLACEMENT$');
attr.value; // => "$REPLACEMENT$"
attr.toString(); // => "[id=$REPLACEMENT$]"
```

# 3.1.2

* Fix: Removed dot-prop dependency since it's no longer written in es5.

# 3.1.1

* Fix: typescript definitions weren't in the published package.

# 3.1.0

* Fixed numerous bugs in attribute nodes relating to the handling of comments
  and whitespace. There's significant changes to `attrNode.spaces` and `attrNode.raws` since the `3.0.0` release.
* Added `Attribute#offsetOf(part)` to get the offset location of
  attribute parts like `"operator"` and `"value"`. This is most
  often added to `Attribute#sourceIndex` for error reporting.

# 3.0.0

## Breaking changes

* Some tweaks to the tokenizer/attribute selector parsing mean that whitespace
  locations might be slightly different to the 2.x code.
* Better attribute selector parsing with more validation; postcss-selector-parser
  no longer uses regular expressions to parse attribute selectors.
* Added an async API (thanks to @jacobp100); the default `process` API is now
  async, and the sync API is now accessed through `processSync` instead.
* `process()` and `processSync()` now return a string instead of the Processor
  instance.
* Tweaks handling of Less interpolation (thanks to @jwilsson).
* Removes support for Node 0.12.

## Other changes

* `ast()` and `astSync()` methods have been added to the `Processor`. These
  return the `Root` node of the selectors after processing them.
* `transform()` and `transformSync()` methods have been added to the
  `Processor`. These return the value returned by the processor callback
  after processing the selectors.
* Set the parent when inserting a node (thanks to @chriseppstein).
* Correctly adjust indices when using insertBefore/insertAfter (thanks to @tivac).
* Fixes handling of namespaces with qualified tag selectors.
* `process`, `ast` and `transform` (and their sync variants) now accept a
  `postcss` rule node. When provided, better errors are generated and selector
  processing is automatically set back to the rule selector (unless the `updateSelector` option is set to `false`.)
* Now more memory efficient when tokenizing selectors.

### Upgrade hints

The pattern of:

`rule.selector = processor.process(rule.selector).result.toString();`

is now:

`processor.processSync(rule)`

# 2.2.3

* Resolves an issue where the parser would not reduce multiple spaces between an
  ampersand and another simple selector in lossy mode (thanks to @adam-26).

# 2.2.2

* No longer hangs on an unescaped semicolon; instead the parser will throw
  an exception for these cases.

# 2.2.1

* Allows a consumer to specify whitespace tokens when creating a new Node
  (thanks to @Semigradsky).

# 2.2.0

* Added a new option to normalize whitespace when parsing the selector string
  (thanks to @adam-26).

# 2.1.1

* Better unquoted value handling within attribute selectors
  (thanks to @evilebottnawi).

# 2.1.0

* Added: Use string constants for all node types & expose them on the main
  parser instance (thanks to @Aweary).

# 2.0.0

This release contains the following breaking changes:

* Renamed all `eachInside` iterators to `walk`. For example, `eachTag` is now
  `walkTags`, and `eachInside` is now `walk`.
* Renamed `Node#removeSelf()` to `Node#remove()`.
* Renamed `Container#remove()` to `Container#removeChild()`.
* Renamed `Node#raw` to `Node#raws` (thanks to @davidtheclark).
* Now parses `&` as the *nesting* selector, rather than a *tag* selector.
* Fixes misinterpretation of Sass interpolation (e.g. `#{foo}`) as an
  id selector (thanks to @davidtheclark).

and;

* Fixes parsing of attribute selectors with equals signs in them
  (e.g. `[data-attr="foo=bar"]`) (thanks to @montmanu).
* Adds `quoted` and `raw.unquoted` properties to attribute nodes
  (thanks to @davidtheclark).

# 1.3.3

* Fixes an infinite loop on `)` and `]` tokens when they had no opening pairs.
  Now postcss-selector-parser will throw when it encounters these lone tokens.

# 1.3.2

* Now uses plain integers rather than `str.charCodeAt(0)` for compiled builds.

# 1.3.1

* Update flatten to v1.x (thanks to @shinnn).

# 1.3.0

* Adds a new node type, `String`, to fix a crash on selectors such as
  `foo:bar("test")`.

# 1.2.1

* Fixes a crash when the parser encountered a trailing combinator.

# 1.2.0

* A more descriptive error is thrown when the parser expects to find a
  pseudo-class/pseudo-element (thanks to @ashelley).
* Adds support for line/column locations for selector nodes, as well as a
  `Node#sourceIndex` method (thanks to @davidtheclark).

# 1.1.4

* Fixes a crash when a selector started with a `>` combinator. The module will
  now no longer throw if a selector has a leading/trailing combinator node.

# 1.1.3

* Fixes a crash on `@` tokens.

# 1.1.2

* Fixes an infinite loop caused by using parentheses in a non-pseudo element
  context.

# 1.1.1

* Fixes a crash when a backslash ended a selector string.

# 1.1.0

* Adds support for replacing multiple nodes at once with `replaceWith`
  (thanks to @jonathantneal).
* Parser no longer throws on sequential IDs and trailing commas, to support
  parsing of selector hacks.

# 1.0.1

* Fixes using `insertAfter` and `insertBefore` during iteration.

# 1.0.0

* Adds `clone` and `replaceWith` methods to nodes.
* Adds `insertBefore` and `insertAfter` to containers.
* Stabilises API.

# 0.0.5

* Fixes crash on extra whitespace inside a pseudo selector's parentheses.
* Adds sort function to the container class.
* Enables the parser to pass its input through without transforming.
* Iteration-safe `each` and `eachInside`.

# 0.0.4

* Tidy up redundant duplication.
* Fixes a bug where the parser would loop infinitely on universal selectors
  inside pseudo selectors.
* Adds `length` getter and `eachInside`, `map`, `reduce` to the container class.
* When a selector has been removed from the tree, the root node will no longer
  cast it to a string.
* Adds node type iterators to the container class (e.g. `eachComment`).
* Adds filter function to the container class.
* Adds split function to the container class.
* Create new node types by doing `parser.id(opts)` etc.
* Adds support for pseudo classes anywhere in the selector.

# 0.0.3

* Adds `next` and `prev` to the node class.
* Adds `first` and `last` getters to the container class.
* Adds `every` and `some` iterators to the container class.
* Add `empty` alias for `removeAll`.
* Combinators are now types of node.
* Fixes the at method so that it is not an alias for `index`.
* Tidy up creation of new nodes in the parser.
* Refactors how namespaces are handled for consistency & less redundant code.
* Refactors AST to use `nodes` exclusively, and eliminates excessive nesting.
* Fixes nested pseudo parsing.
* Fixes whitespace parsing.

# 0.0.2

* Adds support for namespace selectors.
* Adds support for selectors joined by escaped spaces - such as `.\31\ 0`.

# 0.0.1

* Initial release.


---

# postcss-selector-parser [![test](https://github.com/postcss/postcss-selector-parser/actions/workflows/test.yml/badge.svg)](https://github.com/postcss/postcss-selector-parser/actions/workflows/test.yml)

> Selector parser with built in methods for working with selector strings.

## Install

With [npm](https://npmjs.com/package/postcss-selector-parser) do:

```
npm install postcss-selector-parser
```

## Quick Start

```js
const parser = require('postcss-selector-parser');
const transform = selectors => {
    selectors.walk(selector => {
        // do something with the selector
        console.log(String(selector))
    });
};

const transformed = parser(transform).processSync('h1, h2, h3');
```

To normalize selector whitespace:

```js
const parser = require('postcss-selector-parser');
const normalized = parser().processSync('h1, h2, h3', {lossless: false});
// -> h1,h2,h3
```

Async support is provided through `parser.process` and will resolve a Promise
with the resulting selector string.

## API

Please see [API.md](API.md).

## Credits

* Huge thanks to Andrey Sitnik (@ai) for work on PostCSS which helped
  accelerate this module's development.

## License

MIT


---

# PostCSS Sort Media Queries

[PostCSS]:          https://github.com/postcss/postcss
[MIT]:              https://github.com/yunusga/postcss-sort-media-queries/blob/master/LICENSE
[official docs]:    https://github.com/postcss/postcss#usage
[Releases history]: https://github.com/yunusga/postcss-sort-media-queries/blob/master/CHANGELOG.md

[![npm](https://img.shields.io/npm/v/postcss-sort-media-queries.svg)](https://www.npmjs.com/package/postcss-sort-media-queries) [![Node.js CI](https://github.com/yunusga/postcss-sort-media-queries/actions/workflows/test.yml/badge.svg?branch=main&event=status)](https://github.com/yunusga/postcss-sort-media-queries/actions/workflows/test.yml)
![license](https://img.shields.io/badge/License-MIT-orange.svg)
[![npm](https://img.shields.io/npm/dt/postcss-sort-media-queries.svg)](https://www.npmjs.com/package/postcss-sort-media-queries)

<img src="logo.svg?sanitize=true" align="right" title="PostCSS sort media queries logotype" width="100" height="100">

🌏 **English** ▫ [**O'zbek**](README-UZ.md)

[PostCSS] plugin for sorting and combining CSS media queries with **mobile first** / **desktop first** methodologies.

> From 5.0.0 plugin support [Media Feature Types: “range”](https://www.w3.org/TR/mediaqueries-4/#mq-ranges)

## Table of Contents

 - [Online demo](#online-demo)
 - [Examples](#examples)
   - [Mobile first sorting](#mobile-first-sorting)
   - [Desktop first sorting](#desktop-first-sorting)
 - [Install](#install)
 - [Usage](#usage)
 - [Options](#options)
   - [sort](#sort)
   - [Custom sort function](#custom-sort-function)
   - [Sort configuration](#sort-configuration)
   - [Only Top Level](#only-top-level)
 - [Changelog](#changelog)
 - [License](#license)
 - [Other PostCSS plugins](#other-postcss-plugins)
 - [Thanks 💪](#thanks)

## Online demo

And here is the [online demo](https://postcss-sort-media-queries.github.io)

## Examples

### Mobile first sorting

**before**

```css
@media screen and (max-width: 640px) {
  .head { color: #cfcfcf }
}
@media screen and (max-width: 768px) {
  .footer { color: #cfcfcf }
}
@media screen and (max-width: 640px) {
  .main { color: #cfcfcf }
}
@media screen and (min-width: 1280px) {
  .mobile-first { color: #cfcfcf }
}
@media screen and (width > 640px) {
  .mobile-first { color: #cfcfcf }
}
@media screen and (max-width: 640px) {
  .footer { color: #cfcfcf }
}
```

**after**

```css
@media screen and (width > 640px) {
  .mobile-first { color: #cfcfcf }
}
@media screen and (min-width: 1280px) {
  .mobile-first { color: #cfcfcf }
}
@media screen and (max-width: 768px) {
  .footer { color: #cfcfcf }
}
@media screen and (max-width: 640px) {
  /* combined */
  .head { color: #cfcfcf }
  .main { color: #cfcfcf }
  .footer { color: #cfcfcf }
}
```

### Desktop first sorting

**before**
```css
@media screen and (width < 640px) {
  .header { color: #cdcdcd }
}
@media screen and (min-width: 760px) {
  .desktop-first { color: #cdcdcd }
}
@media screen and (width < 640px) {
  .main { color: #cdcdcd }
}
@media screen and (min-width: 1280px) {
  .desktop-first { color: #cdcdcd }
}
@media screen and (max-width: 760px) {
  .footer { color: #cdcdcd }
}
@media screen and (max-width: 640px) {
  .footer { color: #cdcdcd }
}
```

**after**

```css
@media screen and (max-width: 760px) {
  .footer { color: #cdcdcd }
}
@media screen and (width < 640px) {
  /* combined */
  .header { color: #cdcdcd }
  .main { color: #cdcdcd }
  .footer { color: #cdcdcd }
}
@media screen and (min-width: 760px) {
  .desktop-first { color: #cdcdcd }
}
@media screen and (min-width: 1280px) {
  .desktop-first { color: #cdcdcd }
}
```

## Install

First thing's, install the module:

```
npm install postcss postcss-sort-media-queries --save-dev
```

## Usage

Check you project for existed PostCSS config: `postcss.config.js`
in the project root, `"postcss"` section in `package.json`
or `postcss` in bundle config.

If you already use PostCSS, add the plugin to plugins list:

```diff
module.exports = {
  plugins: [
+   require('postcss-sort-media-queries')({
+     sort: 'mobile-first', // default value
+   }),
    require('autoprefixer')
  ]
}
```

or with custom sort function
```diff
module.exports = {
  plugins: [
+   require('postcss-sort-media-queries')({
+     sort: function(a, b) {
+        // custom sorting function
+     }
+   }),
    require('autoprefixer')
  ]
}
```

If you do not use PostCSS, add it according to [official docs]
and set this plugin in settings.

## Options

> Sorting works based on [dutchenkoOleg/sort-css-media-queries](https://github.com/dutchenkoOleg/sort-css-media-queries) function.

### sort

This option support **string** or **function** values.

- `{string}` `'mobile-first'` - (default) mobile first sorting
- `{string}` `'desktop-first'` - desktop first sorting
- `{function}` your own sorting function

#### `'mobile-first'`

```js
postcss([
  sortMediaQueries({
    sort: 'mobile-first' // default
  })
]).process(css);
```

#### `'desktop-first'`

```js
postcss([
  sortMediaQueries({
    sort: 'desktop-first'
  })
]).process(css);
```

### Custom sort function
```js
postcss([
  sortMediaQueries({
    function(a, b) {
      return a.localeCompare(b);
    }
  })
]).process(css);
```

In this example, all your media queries will sort by A-Z order.

This sorting function is directly passed to Array#sort() method of an array of all your media queries.

### Sort configuration

By this configuration you can control sorting behaviour.

```js
postcss([
  sortMediaQueries({
    configuration: {
      unitlessMqAlwaysFirst: true, // or false
    }
  })
]).process(css);
```

Or alternatively create a `sort-css-mq.config.json` file in the root of your project. Or add property `sortCssMQ: {}` in your `package.json`.

### Only Top Level

Sort only top level media queries to prevent eject nested media queries from parent node

```js
postcss([
  sortMediaQueries({
    onlyTopLevel: true,
  })
]).process(css);
```

---

## Changelog

See [Releases history]

## License

[MIT]

## Other PostCSS plugins

- [`postcss-momentum-scrolling`](https://github.com/solversgroup/postcss-momentum-scrolling) - plugin for adding **momentum** style scrolling behavior (`-webkit-overflow-scrolling:touch`) for elements with overflow (scroll, auto) on iOS

## Thanks

- Andrey Sitnik [@ai](https://github.com/ai)
- Oleh Dutchenko [@dutchenkoOleg](https://github.com/dutchenkoOleg)
- Jakub Caban [@Lustmored](https://github.com/Lustmored)
- Dmytro Symonov [@Kassaila](https://github.com/Kassaila)
- Kai Falkowski [@SassNinja](https://github.com/SassNinja)
- Khayot Razzakov [@Khayotbek1](https://github.com/Khayotbek1)


---

# [postcss][postcss]-svgo

> Optimise inline SVG with PostCSS.


## Install

With [npm](https://npmjs.org/package/postcss-svgo) do:

```
npm install postcss-svgo --save
```


## Example

### Input

```css
h1 {
    background: url('data:image/svg+xml;charset=utf-8,<?xml version="1.0" encoding="utf-8"?><!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"><svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve"><circle cx="50" cy="50" r="40" fill="yellow" /></svg>');
}

h2 {
    background: url('data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz48IURPQ1RZUEUgc3ZnIFBVQkxJQyAiLS8vVzNDLy9EVEQgU1ZHIDEuMS8vRU4iICJodHRwOi8vd3d3LnczLm9yZy9HcmFwaGljcy9TVkcvMS4xL0RURC9zdmcxMS5kdGQiPjxzdmcgdmVyc2lvbj0iMS4xIiBpZD0iTGF5ZXJfMSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB4bWxuczp4bGluaz0iaHR0cDovL3d3dy53My5vcmcvMTk5OS94bGluayIgeG1sOnNwYWNlPSJwcmVzZXJ2ZSI+PGNpcmNsZSBjeD0iNTAiIGN5PSI1MCIgcj0iNDAiIGZpbGw9InllbGxvdyIgLz48IS0tdGVzdCBjb21tZW50LS0+PC9zdmc+');
}
```

### Output

```css
h1 {
    background: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg"><circle cx="50" cy="50" r="40" fill="%23ff0"/></svg>');
}

h2 {
    background: url('data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPjxjaXJjbGUgY3g9IjUwIiBjeT0iNTAiIHI9IjQwIiBmaWxsPSIjZmYwIi8+PC9zdmc+');
}
```


## API

### `svgo([options])`

#### options

##### encode

Type: `boolean`
Default: `undefined`

If `true`, it will encode URL-unsafe characters such as `<`, `>` and `&`;
`false` will decode these characters, and `undefined` will neither encode nor
decode the original input. Note that regardless of this setting, `#` will
always be URL-encoded.

##### plugins

Optionally, you can customise the output by specifying the `plugins` option. You
will need to provide the config in comma separated objects, like the example
below. Note that you can either disable the plugin by setting it to `false`,
or pass different options to change the default behaviour.

```js
const postcss = require('postcss');
const svgo = require('postcss-svgo');

const opts = {
    plugins: [{
        name: 'preset-default',
        params: {
            overrides: {
                removeViewBox: false,
                removeComments: false,
                cleanupNumericValues: {
                    floatPrecision: 2
                }
            }
        }
    }]
};


postcss([ svgo(opts) ]).process(css).then((result) => {
    console.log(result.css)
});
```

You can view the [full list of plugins here][plugins].


## Usage

See the [PostCSS documentation](https://github.com/postcss/postcss#usage) for
examples for your environment.


## Contributors

See [CONTRIBUTORS.md](https://github.com/cssnano/cssnano/blob/master/CONTRIBUTORS.md).


## License

MIT © [Ben Briggs](http://beneb.info)

[postcss]: https://github.com/postcss/postcss
[plugins]: https://svgo.dev/docs/plugins/


---

# [postcss][postcss]-unique-selectors

> Ensure CSS selectors are unique.

## Install

With [npm](https://npmjs.org/package/postcss-unique-selectors) do:

```
npm install postcss-unique-selectors --save
```

## Example

Selectors are sorted naturally, and deduplicated:

### Input

```css
h1,h3,h2,h1 {
    color: red
}
```

### Output

```css
h1,h2,h3 {
    color: red
}
```

## Usage

See the [PostCSS documentation](https://github.com/postcss/postcss#usage) for
examples for your environment.

## Contributors

See [CONTRIBUTORS.md](https://github.com/cssnano/cssnano/blob/master/CONTRIBUTORS.md).

## License

MIT © [Ben Briggs](http://beneb.info)

[postcss]: https://github.com/postcss/postcss


---

# postcss-value-parser

[![Travis CI](https://travis-ci.org/TrySound/postcss-value-parser.svg)](https://travis-ci.org/TrySound/postcss-value-parser)

Transforms CSS declaration values and at-rule parameters into a tree of nodes, and provides a simple traversal API.

## Usage

```js
var valueParser = require('postcss-value-parser');
var cssBackgroundValue = 'url(foo.png) no-repeat 40px 73%';
var parsedValue = valueParser(cssBackgroundValue);
// parsedValue exposes an API described below,
// e.g. parsedValue.walk(..), parsedValue.toString(), etc.
```

For example, parsing the value `rgba(233, 45, 66, .5)` will return the following:

```js
{
  nodes: [
    {
      type: 'function',
      value: 'rgba',
      before: '',
      after: '',
      nodes: [
        { type: 'word', value: '233' },
        { type: 'div', value: ',', before: '', after: ' ' },
        { type: 'word', value: '45' },
        { type: 'div', value: ',', before: '', after: ' ' },
        { type: 'word', value: '66' },
        { type: 'div', value: ',', before: ' ', after: '' },
        { type: 'word', value: '.5' }
      ]
    }
  ]
}
```

If you wanted to convert each `rgba()` value in `sourceCSS` to a hex value, you could do so like this:

```js
var valueParser = require('postcss-value-parser');

var parsed = valueParser(sourceCSS);

// walk() will visit all the of the nodes in the tree,
// invoking the callback for each.
parsed.walk(function (node) {

  // Since we only want to transform rgba() values,
  // we can ignore anything else.
  if (node.type !== 'function' && node.value !== 'rgba') return;

  // We can make an array of the rgba() arguments to feed to a
  // convertToHex() function
  var color = node.nodes.filter(function (node) {
    return node.type === 'word';
  }).map(function (node) {
    return Number(node.value);
  }); // [233, 45, 66, .5]

  // Now we will transform the existing rgba() function node
  // into a word node with the hex value
  node.type = 'word';
  node.value = convertToHex(color);
})

parsed.toString(); // #E92D42
```

## Nodes

Each node is an object with these common properties:

- **type**: The type of node (`word`, `string`, `div`, `space`, `comment`, or `function`).
  Each type is documented below.
- **value**: Each node has a `value` property; but what exactly `value` means
  is specific to the node type. Details are documented for each type below.
- **sourceIndex**: The starting index of the node within the original source
  string. For example, given the source string `10px 20px`, the `word` node
  whose value is `20px` will have a `sourceIndex` of `5`.

### word

The catch-all node type that includes keywords (e.g. `no-repeat`),
quantities (e.g. `20px`, `75%`, `1.5`), and hex colors (e.g. `#e6e6e6`).

Node-specific properties:

- **value**: The "word" itself.

### string

A quoted string value, e.g. `"something"` in `content: "something";`.

Node-specific properties:

- **value**: The text content of the string.
- **quote**: The quotation mark surrounding the string, either `"` or `'`.
- **unclosed**: `true` if the string was not closed properly. e.g. `"unclosed string  `.

### div

A divider, for example

- `,` in `animation-duration: 1s, 2s, 3s`
- `/` in `border-radius: 10px / 23px`
- `:` in `(min-width: 700px)`

Node-specific properties:

- **value**: The divider character. Either `,`, `/`, or `:` (see examples above).
- **before**: Whitespace before the divider.
- **after**: Whitespace after the divider.

### space

Whitespace used as a separator, e.g. ` ` occurring twice in `border: 1px solid black;`.

Node-specific properties:

- **value**: The whitespace itself.

### comment

A CSS comment starts with `/*` and ends with `*/`

Node-specific properties:

- **value**: The comment value without `/*` and `*/`
- **unclosed**: `true` if the comment was not closed properly. e.g. `/* comment without an end  `.

### function

A CSS function, e.g. `rgb(0,0,0)` or `url(foo.bar)`.

Function nodes have nodes nested within them: the function arguments.

Additional properties:

- **value**: The name of the function, e.g. `rgb` in `rgb(0,0,0)`.
- **before**: Whitespace after the opening parenthesis and before the first argument,
  e.g. `  ` in `rgb(  0,0,0)`.
- **after**: Whitespace before the closing parenthesis and after the last argument,
  e.g. `  ` in `rgb(0,0,0  )`.
- **nodes**: More nodes representing the arguments to the function.
- **unclosed**: `true` if the parentheses was not closed properly. e.g. `( unclosed-function  `.

Media features surrounded by parentheses are considered functions with an
empty value. For example, `(min-width: 700px)` parses to these nodes:

```js
[
  {
    type: 'function', value: '', before: '', after: '',
    nodes: [
      { type: 'word', value: 'min-width' },
      { type: 'div', value: ':', before: '', after: ' ' },
      { type: 'word', value: '700px' }
    ]
  }
]
```

`url()` functions can be parsed a little bit differently depending on
whether the first character in the argument is a quotation mark.

`url( /gfx/img/bg.jpg )` parses to:

```js
{ type: 'function', sourceIndex: 0, value: 'url', before: ' ', after: ' ', nodes: [
    { type: 'word', sourceIndex: 5, value: '/gfx/img/bg.jpg' }
] }
```

`url( "/gfx/img/bg.jpg" )`, on the other hand, parses to:

```js
{ type: 'function', sourceIndex: 0, value: 'url', before: ' ', after: ' ', nodes: [
     type: 'string', sourceIndex: 5, quote: '"', value: '/gfx/img/bg.jpg' },
] }
```

### unicode-range

The unicode-range CSS descriptor sets the specific range of characters to be 
used from a font defined by @font-face and made available 
for use on the current page (`unicode-range: U+0025-00FF`).

Node-specific properties:

- **value**: The "unicode-range" itself.

## API

```
var valueParser = require('postcss-value-parser');
```

### valueParser.unit(quantity)

Parses `quantity`, distinguishing the number from the unit. Returns an object like the following:

```js
// Given 2rem
{
  number: '2',
  unit: 'rem'
}
```

If the `quantity` argument cannot be parsed as a number, returns `false`.

*This function does not parse complete values*: you cannot pass it `1px solid black` and expect `px` as
the unit. Instead, you should pass it single quantities only. Parse `1px solid black`, then pass it
the stringified `1px` node (a `word` node) to parse the number and unit.

### valueParser.stringify(nodes[, custom])

Stringifies a node or array of nodes.

The `custom` function is called for each `node`; return a string to override the default behaviour.

### valueParser.walk(nodes, callback[, bubble])

Walks each provided node, recursively walking all descendent nodes within functions.

Returning `false` in the `callback` will prevent traversal of descendent nodes (within functions).
You can use this feature to for shallow iteration, walking over only the *immediate* children.
*Note: This only applies if `bubble` is `false` (which is the default).*

By default, the tree is walked from the outermost node inwards.
To reverse the direction, pass `true` for the `bubble` argument.

The `callback` is invoked with three arguments: `callback(node, index, nodes)`.

- `node`: The current node.
- `index`: The index of the current node.
- `nodes`: The complete nodes array passed to `walk()`.

Returns the `valueParser` instance.

### var parsed = valueParser(value)

Returns the parsed node tree.

### parsed.nodes

The array of nodes.

### parsed.toString()

Stringifies the node tree.

### parsed.walk(callback[, bubble])

Walks each node inside `parsed.nodes`. See the documentation for `valueParser.walk()` above.

# License

MIT © [Bogdan Chadkin](mailto:trysound@yandex.ru)


---

# [postcss][postcss]-zindex

> Reduce z-index values with PostCSS.

## Install

With [npm](https://npmjs.org/package/postcss-zindex) do:

```
npm install postcss-zindex --save
```

## Example

Sometimes, you may introduce z-index values into your CSS that are larger than
necessary, in order to improve your understanding of how each stack relates to
the others. For example, you might have a modal overlay at `5000` and the dialog
for it at `5500` - so that modal classes occupy the `5xxx` space.

But in production, it is unnecessary to use such large values for z-index where
smaller values would suffice. This module will reduce all z-index declarations
whilst respecting your original intent; such that the overlay becomes `1` and
the dialog becomes `2`. For more examples, see the [tests](test/index.js).

### Input

```css
.modal {
    z-index: 5000
}

.modal-overlay {
    z-index: 5500
}
```

### Output

```css
.modal {
    z-index: 1
}

.modal-overlay {
    z-index: 2
}
```

Note that this module does not attempt to normalize relative z-index values,
such as `-1`; indeed, it will abort immediately when encountering these values
as it cannot be sure that rebasing mixed positive & negative values will keep
the stacking context intact. Be careful with using this module alongside
JavaScript injected CSS; ideally you should have already extracted all of your
stacking context into CSS.

## API

### zindex([options])

#### options

##### startIndex

Type: `number`
Default: `1`

Set this to any other positive integer if you want to override z-indices from
other sources outside your control. For example if a third party widget has a
maximum z-index of `99`, you can set this to `100` and not have to worry about
stacking conflicts.

## Usage

See the [PostCSS documentation](https://github.com/postcss/postcss#usage) for
examples for your environment.

## Contributors

See [CONTRIBUTORS.md](https://github.com/cssnano/cssnano/blob/master/CONTRIBUTORS.md).

## License

MIT © [Ben Briggs](http://beneb.info)

[postcss]: https://github.com/postcss/postcss


---

# Changelog

## `4.0.0`

* **Breaking Change**: Removed support for Node `<12.x`

---

# pretty-error

[![Dependency status](https://david-dm.org/AriaMinaei/pretty-error.svg)](https://david-dm.org/AriaMinaei/pretty-error)
[![Build Status](https://secure.travis-ci.org/AriaMinaei/pretty-error.svg?branch=master)](https://travis-ci.org/AriaMinaei/pretty-error) [![npm](https://img.shields.io/npm/dm/pretty-error.svg)](https://npmjs.org/package/pretty-error)

A small tool to see node.js errors with less clutter:

![screenshot of pretty-error](https://github.com/AriaMinaei/pretty-error/raw/master/docs/images/pretty-error-screenshot.png)

... which is more readable compared to node's unformatted errors:

![screenshot of normal errors](https://github.com/AriaMinaei/pretty-error/raw/master/docs/images/normal-error-screenshot.png)

## Installation

Install with npm:

	$ npm install pretty-error

## Usage and Examples

To see an error rendered with colors, you can do this:

```javascript
var PrettyError = require('pretty-error');
var pe = new PrettyError();

var renderedError = pe.render(new Error('Some error message'));
console.log(renderedError);
```

Of course, you can render caught exceptions too:

```javascript
try {
   doSomethingThatThrowsAnError();
} catch (error) {
   console.log(pe.render(error));
}
```

But if you want pretty-error to render all errors, there is a shortcut for it:

```javascript
require('pretty-error').start();
```

... which is essentially equal to:

```javascript
var PrettyError = require('pretty-error');

// instantiate PrettyError, which can then be used to render error objects
var pe = new PrettyError();
pe.start();
```

You can also preload pretty-error into your code using node's [`--require`](https://nodejs.org/api/cli.html#cli_r_require_module) argument:

```
$ node --require pretty-error/start your-module.js
```

## How it Works

PrettyError turns error objects into something similar to an html document, and then uses [RenderKid](https://github.com/AriaMinaei/renderkid) to render the document using simple html/css-like commands. This allows PrettyError to be themed using simple css-like declarations.

## Theming

PrettyError's default theme is a bunch of simple css-like rules. [Here](https://github.com/AriaMinaei/pretty-error/blob/master/src/defaultStyle.coffee) is the source of the default theme.

Since the default theme is all css, you can customize it to fit your taste. Let's do a minimal one:

```javascript
// the start() shortcut returns an instance of PrettyError ...
pe = require('pretty-error').start();

// ... which we can then use to customize like this:
pe.appendStyle({
   // this is a simple selector to the element that says 'Error'
   'pretty-error > header > title > kind': {
      // which we can hide:
      display: 'none'
   },

   // the 'colon' after 'Error':
   'pretty-error > header > colon': {
      // we hide that too:
      display: 'none'
   },

   // our error message
   'pretty-error > header > message': {
      // let's change its color:
      color: 'bright-white',

      // we can use black, red, green, yellow, blue, magenta, cyan, white,
      // grey, bright-red, bright-green, bright-yellow, bright-blue,
      // bright-magenta, bright-cyan, and bright-white

      // we can also change the background color:
      background: 'cyan',

      // it understands paddings too!
      padding: '0 1' // top/bottom left/right
   },

   // each trace item ...
   'pretty-error > trace > item': {
      // ... can have a margin ...
      marginLeft: 2,

      // ... and a bullet character!
      bullet: '"<grey>o</grey>"'

      // Notes on bullets:
      //
      // The string inside the quotation mark gets used as the character
      // to show for the bullet point.
      //
      // You can set its color/background color using tags.
      //
      // This example sets the background color to white, and the text color
      // to cyan, the character will be a hyphen with a space character
      // on each side:
      // example: '"<bg-white><cyan> - </cyan></bg-white>"'
      //
      // Note that we should use a margin of 3, since the bullet will be
      // 3 characters long.
   },

   'pretty-error > trace > item > header > pointer > file': {
      color: 'bright-cyan'
   },

   'pretty-error > trace > item > header > pointer > colon': {
      color: 'cyan'
   },

   'pretty-error > trace > item > header > pointer > line': {
      color: 'bright-cyan'
   },

   'pretty-error > trace > item > header > what': {
      color: 'bright-white'
   },

   'pretty-error > trace > item > footer > addr': {
      display: 'none'
   }
});
```

This is how our minimal theme will look like: ![screenshot of our custom theme](https://github.com/AriaMinaei/pretty-error/raw/master/docs/images/custom-theme-screenshot.png)

Read [RenderKid](https://github.com/AriaMinaei/renderkid)'s docs to learn about all the css rules that are supported.

## Customization

There are a few methods to help you customize the contents of your error logs.

Let's instantiate first:

```javascript
PrettyError = require('pretty-error');
pe = new PrettyError();

// or:
pe = require('pretty-error').start();
```

#### Shortening paths

You might want to substitute long paths with shorter, more readable aliases:

```javascript
pe.alias('E:/open-source/theatrejs/lib', '(Theatre.js)');
```

#### Skipping packages

You might want to skip trace lines that belong to specific packages (chai, when, socket.io):

```javascript
pe.skipPackage('chai', 'when', 'socket.io');
```

#### Skipping node files

```javascript
// this will skip node.js, path.js, event.js, etc.
pe.skipNodeFiles();
```

#### Skipping paths

```javascript
pe.skipPath('/home/dir/someFile.js');
```

#### Skipping by callback

You can customize which trace lines get logged and which won't:
```javascript
pe.skip(function(traceLine, lineNumber){
   // if we know which package this trace line comes from, and it isn't
   // our 'demo' package ...
   if (typeof traceLine.packageName !== 'undefined' && traceLine.packageName !== 'demo') {
      // then skip this line
      return true;
   }

   // You can console.log(traceLine) to see all of it's properties.
   // Don't expect all these properties to be present, and don't assume
   // that our traceLine is always an object.
});
```

#### Modifying each trace line's contents

```javascript
pe.filter(function(traceLine, lineNumber){
   // the 'what' clause is something like:
   // 'DynamicTimeline.module.exports.DynamicTimeline._verifyProp'
   if (typeof traceLine.what !== 'undefined'){

      // we can shorten it with a regex:
      traceLine.what = traceLine.what.replace(
         /(.*\.module\.exports\.)(.*)/, '$2'
      );
   }
});
```

## Disabling colors
```javascript
pe.withoutColors(); // Errors will be rendered without coloring
```

## Integrating with frameworks

PrettyError is very simple to set up, so it should be easy to use within other frameworks.

### Integrating with [express](https://github.com/visionmedia/express)

Most frameworks such as express, catch errors automatically and provide a mechanism to handle those errors. Here is an example of how you can use PrettyError to log unhandled errors in express:

```javascript
// this is app.js

var express = require('express');
var PrettyError = require('pretty-error');

var app = express();

app.get('/', function(req, res) {
   // this will throw an error:
   var a = b;
});

var server = app.listen(3000, function(){
   console.log('Server started \n');
});


// we can now instantiaite Prettyerror:
pe = new PrettyError();

// and use it for our app's error handler:
app.use(function(err, req, res, next){
   console.log(pe.render(err));
   next();
});

// we can optionally configure prettyError to simplify the stack trace:

pe.skipNodeFiles(); // this will skip events.js and http.js and similar core node files
pe.skipPackage('express'); // this will skip all the trace lines about express` core and sub-modules
```

## Troubleshooting

`PrettyError.start()` modifies the stack traces of all errors thrown anywhere in your code, so it could potentially break packages that rely on node's original stack traces. I've only encountered this problem once, and it was with BlueBird when `Promise.longStackTraces()` was on.

In order to avoid this problem, it's better to not use `PrettyError.start()` and instead, manually catch errors and render them with PrettyError:

```javascript
var PrettyError = require('pretty-error');
var pe = new PrettyError();

// To render exceptions thrown in non-promies code:
process.on('uncaughtException', function(error){
   console.log(pe.render(error));
});

// To render unhandled rejections created in BlueBird:
process.on('unhandledRejection', function(reason){
   console.log("Unhandled rejection");
   console.log(pe.render(reason));
});

// While PrettyError.start() works out of the box with when.js` unhandled rejections,
// now that wer'e manually rendering errors, we have to instead use npmjs.org/packages/pretty-monitor
// to handle when.js rejections.

```

The only drawback with this approach is that exceptions thrown in the first tick are not prettified. To fix that, you can delay your application's startup for one tick:

```javascript
// (continued form above)

throw new Error(); // not prettified
process.nextTick(function(){
   throw new Error(); // prettified
});

```

## License

MIT


---

# pretty-time [![NPM version](https://img.shields.io/npm/v/pretty-time.svg?style=flat)](https://www.npmjs.com/package/pretty-time) [![NPM monthly downloads](https://img.shields.io/npm/dm/pretty-time.svg?style=flat)](https://npmjs.org/package/pretty-time) [![NPM total downloads](https://img.shields.io/npm/dt/pretty-time.svg?style=flat)](https://npmjs.org/package/pretty-time) [![Linux Build Status](https://img.shields.io/travis/jonschlinkert/pretty-time.svg?style=flat&label=Travis)](https://travis-ci.org/jonschlinkert/pretty-time)

> Easily format the time from node.js `process.hrtime`. Works with timescales ranging from weeks to nanoseconds.

Please consider following this project's author, [Jon Schlinkert](https://github.com/jonschlinkert), and consider starring the project to show your :heart: and support.

## Install

Install with [npm](https://www.npmjs.com/):

```sh
$ npm install --save pretty-time
```

## Usage

```js
var pretty = require('pretty-time');

var start = process.hrtime();
var time = process.hrtime(start);
console.log(pretty(time));
//=> 3μs
```

## API

By default, when no time increment is given as the second argument, the closest timescale is used (e.g. _most granular without being less than zero_).

**Examples:**

```js
pretty([1200708, 795428088]);
//=> '2w'

pretty([800708, 795428088]);
//=> '1w'

pretty([400708, 795428088]);
//=> '5d'

pretty([70708, 795428088]);
//=> '20h'

pretty([12708, 795428088]);
//=> '4h'

pretty([3708, 795428088]);
//=> '1h'

pretty([208, 795428088]);
//=> '3m'

pretty([20, 795428088]);
//=> '21s'

pretty([0, 795428088]);
//=> '795ms'

pretty([0, 000428088]);
//=> '428μs'

pretty([0, 000000088]);
//=> '88ns'

pretty([0, 000000018]);
//=> '18ns'
```

### Minimum time increment

_(All of the following examples use `[6740, 795428088]` as the hrtime array.)_

This value is passed as the second argument and determines how granular to make the time.

**Examples**

```js
pretty(time, 'h');
//=> '2h'

pretty(time, 'm');
//=> '1h 52m'

pretty(time, 's');
//=> '1h 52m 21s'
```

**Valid time increments**

Any of the following may be used:

* `ns` | `nano` | `nanosecond` | `nanoseconds`
* `μs` | `micro` | `microsecond` | `microseconds`
* `ms` | `milli` | `millisecond` | `milliseconds`
* `s` | `sec` | `second` | `seconds`
* `m` | `min` | `minute` | `minutes`
* `h` | `hr` | `hour` | `hours`
* `d` | `day` | `days`
* `w` | `wk` | `week` | `weeks`

## About

<details>
<summary><strong>Contributing</strong></summary>

Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).

</details>

<details>
<summary><strong>Running Tests</strong></summary>

Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

```sh
$ npm install && npm test
```

</details>

<details>
<summary><strong>Building docs</strong></summary>

_(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_

To generate the readme, run the following command:

```sh
$ npm install -g verbose/verb#dev verb-generate-readme && verb
```

</details>

### Related projects

You might also be interested in these projects:

* [o-clock](https://www.npmjs.com/package/o-clock): Simple javascript utility for displaying the time in 12-hour clock format. | [homepage](https://github.com/jonschlinkert/o-clock "Simple javascript utility for displaying the time in 12-hour clock format.")
* [seconds](https://www.npmjs.com/package/seconds): Get the number of seconds for a minute, hour, day and week. | [homepage](https://github.com/jonschlinkert/seconds "Get the number of seconds for a minute, hour, day and week.")
* [time-stamp](https://www.npmjs.com/package/time-stamp): Get a formatted timestamp. | [homepage](https://github.com/jonschlinkert/time-stamp "Get a formatted timestamp.")
* [timescale](https://www.npmjs.com/package/timescale): Convert from one time scale to another. Nanosecond is the most atomic unit, week is… [more](https://github.com/jonschlinkert/timescale) | [homepage](https://github.com/jonschlinkert/timescale "Convert from one time scale to another. Nanosecond is the most atomic unit, week is the largest unit.")
* [week](https://www.npmjs.com/package/week): Get the current week number. | [homepage](https://github.com/datetime/week "Get the current week number.")
* [weekday](https://www.npmjs.com/package/weekday): Get the name and number of the current weekday. Or get the name of the… [more](https://github.com/datetime/weekday) | [homepage](https://github.com/datetime/weekday "Get the name and number of the current weekday. Or get the name of the weekday for a given number.")
* [year](https://www.npmjs.com/package/year): Simple utility to get the current year with 2 or 4 digits. | [homepage](https://github.com/jonschlinkert/year "Simple utility to get the current year with 2 or 4 digits.")

### Contributors

| **Commits** | **Contributor** | 
| --- | --- |
| 14 | [jonschlinkert](https://github.com/jonschlinkert) |
| 5 | [doowb](https://github.com/doowb) |

### Author

**Jon Schlinkert**

* [LinkedIn Profile](https://linkedin.com/in/jonschlinkert)
* [GitHub Profile](https://github.com/jonschlinkert)
* [Twitter Profile](https://twitter.com/jonschlinkert)

### License

Copyright © 2018, [Jon Schlinkert](https://github.com/jonschlinkert).
Released under the [MIT License](LICENSE).

***

_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.6.0, on July 12, 2018._

---

[![Maintenance Status][maintenance-image]](#maintenance-status)


<h1 align="center">
  prism-react-renderer 🖌️
  <br>
</h1>
<p align="center" style="font-size: 1.2rem;">
  A lean <a href="https://github.com/PrismJS/prism">Prism</a> highlighter component for React<br>
  Comes with everything to render Prismjs highlighted code directly to React (Native) elements, global-pollution-free!
</p>

## Why?

Maybe you need to render some extra UI with your Prismjs-highlighted code,
or maybe you'd like to manipulate what Prism renders completely,
or maybe you're just using Prism with React and are searching for an easier,
global-pollution-free way?

Then you're right where you want to be!

## How?

This library tokenises code using Prism and provides a small render-props-driven
component to quickly render it out into React. This is why it even works with
React Native! It's bundled with a modified version of Prism that won't pollute
the global namespace and comes with
[a couple of common language syntaxes](./src/vendor/prism/includeLangs.js).

_(There's also an [escape-hatch](https://github.com/FormidableLabs/prism-react-renderer#prism) to use your own Prism setup, just in case)_

It also comes with its own [VSCode-like theming format](#theming), which means by default
you can easily drop in different themes, use the ones this library ships with, or
create new ones programmatically on the fly.

_(If you just want to use your Prism CSS-file themes, that's also no problem)_

## Table of Contents

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

- [Installation](#installation)
- [Usage](#usage)
- [Basic Props](#basic-props)
  - [children](#children)
  - [language](#language)
  - [code](#code)
- [Advanced Props](#advanced-props)
  - [theme](#theme)
  - [Prism](#prism)
- [Children Function](#children-function)
  - [state](#state)
  - [prop getters](#prop-getters)
    - [`getLineProps`](#getlineprops)
    - [`getTokenProps`](#gettokenprops)
- [Theming](#theming)
- [FAQ](#faq)
- [LICENSE](#license)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## Installation

This module is distributed via npm which is bundled with node and
should be installed as one of your project's `dependencies`:

```sh
# npm
npm install --save prism-react-renderer
# yarn
yarn add prism-react-renderer
```

> This package also depends on `react`. Please make sure you
> have those installed as well.

## Usage

> [Try it out in the browser](https://codesandbox.io/s/prism-react-renderer-example-u6vhk)

<img src="./.readme/basic.png" width="237" alt="Screenshot showing highlighted code block" />

```jsx
import React from "react";
import { render } from "react-dom";
import Highlight, { defaultProps } from "prism-react-renderer";

const exampleCode = `
(function someDemo() {
  var test = "Hello World!";
  console.log(test);
})();

return () => <App />;
`;

render(
  <Highlight {...defaultProps} code={exampleCode} language="jsx">
    {({ className, style, tokens, getLineProps, getTokenProps }) => (
      <pre className={className} style={style}>
        {tokens.map((line, i) => (
          <div {...getLineProps({ line, key: i })}>
            {line.map((token, key) => (
              <span {...getTokenProps({ token, key })} />
            ))}
          </div>
        ))}
      </pre>
    )}
  </Highlight>,
  document.getElementById('root')
);
```

`<Highlight />` is the only component exposed by this package, as inspired by
[downshift](https://github.com/paypal/downshift).

It also exports a `defaultProps` object which for basic usage can simply be spread
onto the `<Highlight />` component. It also provides some default theming.

It doesn't render anything itself, it just calls the render function and renders that.
["Use a render prop!"](https://cdb.reacttraining.com/use-a-render-prop-50de598f11ce)!
`<Highlight>{highlight => <pre>/* your JSX here! */</pre>}</Highlight>`

### Line Numbers

Add line numbers to your highlighted code blocks using the `index` parameter in your `line.map` function:

<img src="./.readme/line-numbers.png" width="453" alt="Screenshot showing line numbers in highlighted code block" />

For example, if you were using `styled-components`, it could look like the following demo.

> [Demo with `styled-components`](https://codesandbox.io/s/prism-react-renderer-example-u6vhk?file=/src/WithLineNumbers.js)

```js
import React from "react";
import styled from "styled-components";
import Highlight, { defaultProps } from "prism-react-renderer";
import theme from "prism-react-renderer/themes/nightOwl";

const exampleCode = `
import React, { useState } from "react";

function Example() {
  const [count, setCount] = useState(0);

  return (
    <div>
      <p>You clicked {count} times</p>
      <button onClick={() => setCount(count + 1)}>
        Click me
      </button>
    </div>
  );
}
`.trim();

const Pre = styled.pre`
  text-align: left;
  margin: 1em 0;
  padding: 0.5em;
  overflow: scroll;
`;

const Line = styled.div`
  display: table-row;
`;

const LineNo = styled.span`
  display: table-cell;
  text-align: right;
  padding-right: 1em;
  user-select: none;
  opacity: 0.5;
`;

const LineContent = styled.span`
  display: table-cell;
`;

const WithLineNumbers = () => (
  <Highlight {...defaultProps} theme={theme} code={exampleCode} language="jsx">
    {({ className, style, tokens, getLineProps, getTokenProps }) => (
      <Pre className={className} style={style}>
        {tokens.map((line, i) => (
          <Line key={i} {...getLineProps({ line, key: i })}>
            <LineNo>{i + 1}</LineNo>
            <LineContent>
              {line.map((token, key) => (
                <span key={key} {...getTokenProps({ token, key })} />
              ))}
            </LineContent>
          </Line>
        ))}
      </Pre>
    )}
  </Highlight>
);

export default WithLineNumbers;
```

## Basic Props

This is the list of props that you should probably know about. There are some
[advanced props](#advanced-props) below as well.

Most of these [advanced props](#advanced-props) are included in the `defaultProps`.

### children

> `function({})` | _required_

This is called with an object. Read more about the properties of this object in
the section "[Children Function](#children-function)".

### language

> `string` | _required_

This is the language that your code will be highlighted as. You can see a list
of all languages that are supported out of the box [here](./src/vendor/prism/includeLangs.js). Not all languages are included and the list of languages that are currently is a little arbitrary. You can use the [escape-hatch](https://github.com/FormidableLabs/prism-react-renderer#prism) to use your own Prism setup, just in case, or [add more languages to the bundled Prism.](https://github.com/FormidableLabs/prism-react-renderer#faq)

### code

> `string` | _required_

This is the code that will be highlighted.

## Advanced Props

### theme

> `PrismTheme` | _required; default is provided in `defaultProps` export_

If a theme is passed, it is used to generate style props which can be retrieved
via the prop-getters which are described in "[Children Function](#children-function)".

A default theme is provided by the `defaultProps` object.

Read more about how to theme `prism-react-renderer` in
the section "[Theming](#theming)".

### Prism

> `PrismLib` | _required; default is provided in `defaultProps` export_

This is the [Prismjs](https://github.com/PrismJS/prism) library itself.
A vendored version of Prism is provided (and also exported) as part of this library.
This vendored version doesn't pollute the global namespace, is slimmed down,
and doesn't conflict with any installation of `prismjs` you might have.

If you're only using `Prism.highlight` you can choose to use `prism-react-renderer`'s
exported, vendored version of Prism instead.

But if you choose to use your own Prism setup, simply pass Prism as a prop:

```jsx
// Whichever way you're retrieving Prism here:
import Prism from 'prismjs/components/prism-core';

<Highlight Prism={Prism} {/* ... */} />
```

## Children Function

This is where you render whatever you want to based on the output of `<Highlight />`.
You use it like so:

```js
const ui = (
  <Highlight>
    {highlight => (
      // use utilities and prop getters here, like highlight.className, highlight.getTokenProps, etc.
      <pre>{/* more jsx here */}</pre>
    )}
  </Highlight>
);
```

The properties of this `highlight` object can be split into two categories as indicated below:

### state

These properties are the flat output of `<Highlight />`. They're generally "state" and are what
you'd usually expect from a render-props-based API.

| property    | type        | description                                                                                                                  |
| ----------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `tokens`    | `Token[][]` | This is a doubly nested array of tokens. The outer array is for separate lines, the inner for tokens, so the actual content. |
| `className` | `string`    | This is the class you should apply to your wrapping element, typically a `<pre>`                                             |

A "Token" is an object that represents a piece of content for Prism. It has a `types` property, which is an array
of types that indicate the purpose and styling of a piece of text, and a `content` property, which is the actual
text.

You'd typically iterate over `tokens`, rendering each line, and iterate over its items, rendering out each token, which is a piece of
this line.

### prop getters

> See
> [Kent C. Dodds' blog post about prop getters](https://blog.kentcdodds.com/how-to-give-rendering-control-to-users-with-prop-getters-549eaef76acf)

These functions are used to apply props to the elements that you render. This
gives you maximum flexibility to render what, when, and wherever you like.

You'd typically call these functions with some dictated input and add on all other
props that it should pass through. It'll correctly override and modify the props
that it returns to you, so passing props to it instead of adding them directly is
advisable.

| property        | type           | description                                                                                           |
| --------------- | -------------- | ----------------------------------------------------------------------------------------------------- |
| `getLineProps`  | `function({})` | returns the props you should apply to any list of tokens, i.e. the element that contains your tokens. |
| `getTokenProps` | `function({})` | returns the props you should apply to the elements displaying tokens that you render.                 |

#### `getLineProps`

You need to add a `line` property (type: `Token[]`) to the object you're passing to
`getLineProps`; It's also advisable to add a `key`.

This getter will return you props to spread onto your line elements (typically `<div>s`).

It will typically return a `className` (if you pass one it'll be appended), `children`,
`style` (if you pass one it'll be merged). It also passes on all other props you pass
to the input.

The `className` will always contain `.token-line`.

#### `getTokenProps`

You need to add a `token` property (type: `Token`) to the object you're passing to
`getTokenProps`; It's also advisable to add a `key`.

This getter will return you props to spread onto your token elements (typically `<span>s`).

It will typically return a `className` (if you pass one it'll be appended), `children`,
`style` (if you pass one it'll be merged). It also passes on all other props you pass
to the input.

The `className` will always contain `.token`. This also provides full compatibility with
your old Prism CSS-file themes.

## Theming

The `defaultProps` you'd typically apply in a basic use-case, contain a default theme.
This theme is [duotoneDark](./src/themes/duotoneDark.js).

While all `className`s are provided with `<Highlight />`, so that you could use your good
old Prism CSS-file themes, you can also choose to use `prism-react-renderer`'s themes like so:

```jsx
import dracula from 'prism-react-renderer/themes/dracula';

<Highlight theme={dracula} {/* ... */} />
```

These themes are JSON-based and are heavily inspired by VSCode's theme format.

Their syntax, expressed in Flow looks like the following:

```js
{
  plain: StyleObj,
  styles: Array<{
    types: string[],
    languages?: string[],
    style: StyleObj
  }>
}
```

The `plain` property provides a base style-object. This style object is directly used
in the `style` props that you'll receive from the prop getters, if a `theme` prop has
been passed to `<Highlight />`.

The `styles` property contains an array of definitions. Each definition contains a `style`
property, that is also just a style object. These styles are limited by the `types`
and `languages` properties.

The `types` properties is an array of token types that Prism outputs. The `languages`
property limits styles to highlighted languages.

When converting a Prism CSS theme it's mostly just necessary to use classes as
`types` and convert the declarations to object-style-syntax and put them on `style`.

## FAQ

<details>

<summary>How do I add more language highlighting support?</summary>

By default `prism-react-renderer` only includes an [arbitrary subset of the languages](https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/vendor/prism/includeLangs.js) that Prism supports. You can add support for more by including their definitions from the main `prismjs` package:

```js
import Prism from "prism-react-renderer/prism";

(typeof global !== "undefined" ? global : window).Prism = Prism;

require("prismjs/components/prism-kotlin");
require("prismjs/components/prism-csharp");
```
</details>

<details>

<summary>How do I use my old Prism css themes?</summary>

`prism-react-renderer` still returns you all proper `className`s via the prop getters,
when you use it. By default however it uses its new theming system, which output a
couple of `style` props as well.

If you don't pass `theme` to the `<Highlight />` component it will default to not
outputting any `style` props, while still returning you the `className` props, like
so:

```js
<Highlight
  {...defaultProps}
  code={exampleCode}
  language="jsx"
  theme={undefined}
>
  {highlight => null /* ... */}
</Highlight>
```

</details>

<details>

<summary>How do I prevent a theme and the vendored Prism to be bundled?</summary>

Since the default theme and the vendored Prism library in `prism-react-renderer`
come from `defaultProps`, if you wish to pass your own Prism library in, and not
use the built-in theming, you simply need to leave it out to allow your bundler
to tree-shake those:

```js
import Highlight from "prism-react-renderer";
import Prism from "prismjs"; // Different source

<Highlight Prism={Prism} code={exampleCode} language="jsx">
  {highlight => null /* ... */}
</Highlight>;
```

You can also import the vendored Prism library on its own:

```js
import { Prism } from "prism-react-renderer";
// or
import Prism from "prism-react-renderer/prism";
```

</details>

## LICENSE

MIT

## Maintenance Status

**Active:** Formidable is actively working on this project, and we expect to continue for work for the foreseeable future. Bug reports, feature requests and pull requests are welcome.

[maintenance-image]: https://img.shields.io/badge/maintenance-active-green.svg



---

# Prism Changelog

## 1.29.0 (2022-08-23)

### New components

* __BBj__ ([#3511](https://github.com/PrismJS/prism/issues/3511)) [`1134bdfc`](https://github.com/PrismJS/prism/commit/1134bdfc)
* __BQN__ ([#3515](https://github.com/PrismJS/prism/issues/3515)) [`859f99a0`](https://github.com/PrismJS/prism/commit/859f99a0)
* __Cilk/C__ & __Cilk/C++__ ([#3522](https://github.com/PrismJS/prism/issues/3522)) [`c8462a29`](https://github.com/PrismJS/prism/commit/c8462a29)
* __Gradle__ ([#3443](https://github.com/PrismJS/prism/issues/3443)) [`32119823`](https://github.com/PrismJS/prism/commit/32119823)
* __METAFONT__ ([#3465](https://github.com/PrismJS/prism/issues/3465)) [`2815f699`](https://github.com/PrismJS/prism/commit/2815f699)
* __WGSL__ ([#3455](https://github.com/PrismJS/prism/issues/3455)) [`4c87d418`](https://github.com/PrismJS/prism/commit/4c87d418)

### Updated components

* __AsciiDoc__
    * Some regexes are too greedy ([#3481](https://github.com/PrismJS/prism/issues/3481)) [`c4cbeeaa`](https://github.com/PrismJS/prism/commit/c4cbeeaa)
* __Bash__
    * Added "sh" alias ([#3509](https://github.com/PrismJS/prism/issues/3509)) [`6b824d47`](https://github.com/PrismJS/prism/commit/6b824d47)
    * Added support for parameters and the `java` and `sysctl` commands. ([#3505](https://github.com/PrismJS/prism/issues/3505)) [`b9512b22`](https://github.com/PrismJS/prism/commit/b9512b22)
    * Added `cargo` command ([#3488](https://github.com/PrismJS/prism/issues/3488)) [`3e937137`](https://github.com/PrismJS/prism/commit/3e937137)
* __BBj__
    * Improve regexes ([#3512](https://github.com/PrismJS/prism/issues/3512)) [`0cad9ae5`](https://github.com/PrismJS/prism/commit/0cad9ae5)
* __CSS__
    * Fixed @-rules not accounting for strings ([#3438](https://github.com/PrismJS/prism/issues/3438)) [`0d4b6cb6`](https://github.com/PrismJS/prism/commit/0d4b6cb6)
* __CSS Extras__
    * Added support for `RebeccaPurple` color ([#3448](https://github.com/PrismJS/prism/issues/3448)) [`646b2e0a`](https://github.com/PrismJS/prism/commit/646b2e0a)
* __Hoon__
    * Fixed escaped strings ([#3473](https://github.com/PrismJS/prism/issues/3473)) [`64642716`](https://github.com/PrismJS/prism/commit/64642716)
* __Java__
    * Added support for constants ([#3507](https://github.com/PrismJS/prism/issues/3507)) [`342a0039`](https://github.com/PrismJS/prism/commit/342a0039)
* __Markup__
    * Fixed quotes in HTML attribute values ([#3442](https://github.com/PrismJS/prism/issues/3442)) [`ca8eaeee`](https://github.com/PrismJS/prism/commit/ca8eaeee)
* __NSIS__
    * Added missing commands ([#3504](https://github.com/PrismJS/prism/issues/3504)) [`b0c2a9b4`](https://github.com/PrismJS/prism/commit/b0c2a9b4)
* __Scala__
    * Updated keywords to support Scala 3 ([#3506](https://github.com/PrismJS/prism/issues/3506)) [`a090d063`](https://github.com/PrismJS/prism/commit/a090d063)
* __SCSS__
    * Fix casing in title of the `scss` lang ([#3501](https://github.com/PrismJS/prism/issues/3501)) [`2aed9ce7`](https://github.com/PrismJS/prism/commit/2aed9ce7)

### Updated plugins

* __Line Highlight__
    * Account for offset when clamping ranges ([#3518](https://github.com/PrismJS/prism/issues/3518)) [`098e3000`](https://github.com/PrismJS/prism/commit/098e3000)
    * Ignore ranges outside of actual lines ([#3475](https://github.com/PrismJS/prism/issues/3475)) [`9a4e725b`](https://github.com/PrismJS/prism/commit/9a4e725b)
* __Normalize Whitespace__
    * Add configuration via attributes ([#3467](https://github.com/PrismJS/prism/issues/3467)) [`91dea0c8`](https://github.com/PrismJS/prism/commit/91dea0c8)

### Other

* Added security policy ([#3070](https://github.com/PrismJS/prism/issues/3070)) [`05ee042a`](https://github.com/PrismJS/prism/commit/05ee042a)
* Added list of maintainers ([#3410](https://github.com/PrismJS/prism/issues/3410)) [`866b302e`](https://github.com/PrismJS/prism/commit/866b302e)
* Included githubactions in the dependabot config ([#3470](https://github.com/PrismJS/prism/issues/3470)) [`9561a9ab`](https://github.com/PrismJS/prism/commit/9561a9ab)
* Set permissions for GitHub actions ([#3468](https://github.com/PrismJS/prism/issues/3468)) [`b85e1ada`](https://github.com/PrismJS/prism/commit/b85e1ada)
* __Website__
    * Website: Added third-party tutorial for Pug template ([#3459](https://github.com/PrismJS/prism/issues/3459)) [`15272f76`](https://github.com/PrismJS/prism/commit/15272f76)
    * Docs: Add missing word ([#3489](https://github.com/PrismJS/prism/issues/3489)) [`9d603ef4`](https://github.com/PrismJS/prism/commit/9d603ef4)

## 1.28.0 (2022-04-17)

### New components

* __Ado__ & __Mata__ (Stata) ([#3383](https://github.com/PrismJS/prism/issues/3383)) [`63806d57`](https://github.com/PrismJS/prism/commit/63806d57)
* __ARM Assembly__ ([#3376](https://github.com/PrismJS/prism/issues/3376)) [`554ff324`](https://github.com/PrismJS/prism/commit/554ff324)
* __Arturo__ ([#3403](https://github.com/PrismJS/prism/issues/3403)) [`e2fe1f79`](https://github.com/PrismJS/prism/commit/e2fe1f79)
* __AWK__ & __GAWK__ ([#3374](https://github.com/PrismJS/prism/issues/3374)) [`ea8a0f40`](https://github.com/PrismJS/prism/commit/ea8a0f40)
* __Cooklang__ ([#3337](https://github.com/PrismJS/prism/issues/3337)) [`4eb928c3`](https://github.com/PrismJS/prism/commit/4eb928c3)
* __CUE__ ([#3375](https://github.com/PrismJS/prism/issues/3375)) [`a1340666`](https://github.com/PrismJS/prism/commit/a1340666)
* __gettext__ ([#3369](https://github.com/PrismJS/prism/issues/3369)) [`dfef9b61`](https://github.com/PrismJS/prism/commit/dfef9b61)
* __GNU Linker Script__ ([#3373](https://github.com/PrismJS/prism/issues/3373)) [`33f2cf95`](https://github.com/PrismJS/prism/commit/33f2cf95)
* __Odin__ ([#3424](https://github.com/PrismJS/prism/issues/3424)) [`8a3fef6d`](https://github.com/PrismJS/prism/commit/8a3fef6d)
* __PlantUML__ ([#3372](https://github.com/PrismJS/prism/issues/3372)) [`0d49553c`](https://github.com/PrismJS/prism/commit/0d49553c)
* __ReScript__ ([#3435](https://github.com/PrismJS/prism/issues/3435)) [`cbef9af7`](https://github.com/PrismJS/prism/commit/cbef9af7)
* __SuperCollider__ ([#3371](https://github.com/PrismJS/prism/issues/3371)) [`1b1d6731`](https://github.com/PrismJS/prism/commit/1b1d6731)

### Updated components

* __.properties__
    * Use `key`, `value` for token names; `attr-name`, `attr-value` as aliases ([#3377](https://github.com/PrismJS/prism/issues/3377)) [`b94a664d`](https://github.com/PrismJS/prism/commit/b94a664d)
* __ABAP__
    * Sorted keyword list ([#3368](https://github.com/PrismJS/prism/issues/3368)) [`7bda2bf1`](https://github.com/PrismJS/prism/commit/7bda2bf1)
* __Ada__
    * Changed `attr-name` to `attribute`; Use `attr-name` as alias ([#3381](https://github.com/PrismJS/prism/issues/3381)) [`cde0b5b2`](https://github.com/PrismJS/prism/commit/cde0b5b2)
    * Added `or` keyword ([#3380](https://github.com/PrismJS/prism/issues/3380)) [`c30b736f`](https://github.com/PrismJS/prism/commit/c30b736f)
* __Atmel AVR Assembly__
    * Fixed `&=` and `|=` operators ([#3395](https://github.com/PrismJS/prism/issues/3395)) [`8c4ae5a5`](https://github.com/PrismJS/prism/commit/8c4ae5a5)
* __AutoHotkey__
    * Use standard tokens ([#3385](https://github.com/PrismJS/prism/issues/3385)) [`61c460e8`](https://github.com/PrismJS/prism/commit/61c460e8)
    * Use general pattern instead of name list for directives ([#3384](https://github.com/PrismJS/prism/issues/3384)) [`7ac84dda`](https://github.com/PrismJS/prism/commit/7ac84dda)
* __CFScript__
    * Simplified operator regex ([#3396](https://github.com/PrismJS/prism/issues/3396)) [`6a215fe0`](https://github.com/PrismJS/prism/commit/6a215fe0)
* __CMake__
    * Simplified `variable` and `operator` regexes ([#3398](https://github.com/PrismJS/prism/issues/3398)) [`8e59744b`](https://github.com/PrismJS/prism/commit/8e59744b)
* __Erlang__
    * Added `begin` keyword ([#3387](https://github.com/PrismJS/prism/issues/3387)) [`cf38d059`](https://github.com/PrismJS/prism/commit/cf38d059)
* __Excel Formula__
    * Use more fitting aliases for `function-name`, `range`, and `cell` ([#3391](https://github.com/PrismJS/prism/issues/3391)) [`ef0ec02a`](https://github.com/PrismJS/prism/commit/ef0ec02a)
* __Flow__
    * Changed alias of `type` to `class-name` ([#3390](https://github.com/PrismJS/prism/issues/3390)) [`ce41434d`](https://github.com/PrismJS/prism/commit/ce41434d)
    * Recognise `[Ss]ymbol` as a type ([#3388](https://github.com/PrismJS/prism/issues/3388)) [`3916883a`](https://github.com/PrismJS/prism/commit/3916883a)
* __GEDCOM__
    * Update `tag` to `record` ([#3386](https://github.com/PrismJS/prism/issues/3386)) [`f8f95340`](https://github.com/PrismJS/prism/commit/f8f95340)
* __Groovy__
    * Added string interpolation without hook ([#3366](https://github.com/PrismJS/prism/issues/3366)) [`5617765f`](https://github.com/PrismJS/prism/commit/5617765f)
* __Handlebars__
    * Added Mustache alias ([#3422](https://github.com/PrismJS/prism/issues/3422)) [`cb5229af`](https://github.com/PrismJS/prism/commit/cb5229af)
* __Java__
    * Improved class name detection ([#3351](https://github.com/PrismJS/prism/issues/3351)) [`4cb3d038`](https://github.com/PrismJS/prism/commit/4cb3d038)
    * Fixed `record` false positives ([#3348](https://github.com/PrismJS/prism/issues/3348)) [`3bd8fdb1`](https://github.com/PrismJS/prism/commit/3bd8fdb1)
* __JavaScript__
    * Added support for new regex syntax ([#3399](https://github.com/PrismJS/prism/issues/3399)) [`ca78cde6`](https://github.com/PrismJS/prism/commit/ca78cde6)
* __Keyman__
    * Added new keywords ([#3401](https://github.com/PrismJS/prism/issues/3401)) [`bac36827`](https://github.com/PrismJS/prism/commit/bac36827)
* __MEL__
    * Improved functions, code, and comments ([#3393](https://github.com/PrismJS/prism/issues/3393)) [`8e648dab`](https://github.com/PrismJS/prism/commit/8e648dab)
* __NEON__
    * Change alias of `key` to `property` ([#3394](https://github.com/PrismJS/prism/issues/3394)) [`1c533f4a`](https://github.com/PrismJS/prism/commit/1c533f4a)
* __PHP__
    * Added `never` return type + minor fix of named arguments ([#3421](https://github.com/PrismJS/prism/issues/3421)) [`4ffab525`](https://github.com/PrismJS/prism/commit/4ffab525)
    * Added `readonly` keyword ([#3349](https://github.com/PrismJS/prism/issues/3349)) [`4c3f1969`](https://github.com/PrismJS/prism/commit/4c3f1969)
* __PureBasic__
    * Added support for pointer to string operator ([#3362](https://github.com/PrismJS/prism/issues/3362)) [`499b1fa0`](https://github.com/PrismJS/prism/commit/499b1fa0)
* __Razor C#__
    * Added support for `@helper` and inline C# inside attribute values ([#3355](https://github.com/PrismJS/prism/issues/3355)) [`31a38d0c`](https://github.com/PrismJS/prism/commit/31a38d0c)
* __VHDL__
    * Add `private`, `view` keywords; Distinguish `attribute` from `keyword` ([#3389](https://github.com/PrismJS/prism/issues/3389)) [`d1a5ce30`](https://github.com/PrismJS/prism/commit/d1a5ce30)
* __Wolfram language__
    * Simplified `operator` regex ([#3397](https://github.com/PrismJS/prism/issues/3397)) [`10ae6da3`](https://github.com/PrismJS/prism/commit/10ae6da3)

### Updated plugins

* __Autolinker__
    * Fixed URL regex to match more valid URLs ([#3358](https://github.com/PrismJS/prism/issues/3358)) [`17ed9160`](https://github.com/PrismJS/prism/commit/17ed9160)
* __Command Line__
    * Add support for command continuation prefix ([#3344](https://github.com/PrismJS/prism/issues/3344)) [`b53832cd`](https://github.com/PrismJS/prism/commit/b53832cd)
    * Increased prompt opacity ([#3352](https://github.com/PrismJS/prism/issues/3352)) [`f95dd190`](https://github.com/PrismJS/prism/commit/f95dd190)
* __Keep Markup__
    * Use original nodes instead of clones ([#3365](https://github.com/PrismJS/prism/issues/3365)) [`8a843a17`](https://github.com/PrismJS/prism/commit/8a843a17)

### Other

* __Infrastructure__
    * Use terser ([#3407](https://github.com/PrismJS/prism/issues/3407)) [`11c54624`](https://github.com/PrismJS/prism/commit/11c54624)
    * Tests: Cache results for exp backtracking check ([#3356](https://github.com/PrismJS/prism/issues/3356)) [`ead22e1e`](https://github.com/PrismJS/prism/commit/ead22e1e)
* __Website__
    * More documentation for language definitons ([#3427](https://github.com/PrismJS/prism/issues/3427)) [`333bd590`](https://github.com/PrismJS/prism/commit/333bd590)

## 1.27.0 (2022-02-17)

### New components

* __UO Razor Script__ ([#3309](https://github.com/PrismJS/prism/issues/3309)) [`3f8cc5a0`](https://github.com/PrismJS/prism/commit/3f8cc5a0)

### Updated components

* __AutoIt__
    * Allow hyphen in directive ([#3308](https://github.com/PrismJS/prism/issues/3308)) [`bcb2e2c8`](https://github.com/PrismJS/prism/commit/bcb2e2c8)
* __EditorConfig__
    * Change alias of `section` from `keyword` to `selector` ([#3305](https://github.com/PrismJS/prism/issues/3305)) [`e46501b9`](https://github.com/PrismJS/prism/commit/e46501b9)
* __Ini__
    * Swap out `header` for `section` ([#3304](https://github.com/PrismJS/prism/issues/3304)) [`deb3a97f`](https://github.com/PrismJS/prism/commit/deb3a97f)
* __MongoDB__
    * Added v5 support ([#3297](https://github.com/PrismJS/prism/issues/3297)) [`8458c41f`](https://github.com/PrismJS/prism/commit/8458c41f)
* __PureBasic__
    * Added missing keyword and fixed constants ending with `$` ([#3320](https://github.com/PrismJS/prism/issues/3320)) [`d6c53726`](https://github.com/PrismJS/prism/commit/d6c53726)
* __Scala__
    * Added support for interpolated strings ([#3293](https://github.com/PrismJS/prism/issues/3293)) [`441a1422`](https://github.com/PrismJS/prism/commit/441a1422)
* __Systemd configuration file__
    * Swap out `operator` for `punctuation` ([#3306](https://github.com/PrismJS/prism/issues/3306)) [`2eb89e15`](https://github.com/PrismJS/prism/commit/2eb89e15)

### Updated plugins

* __Command Line__
    * Escape markup in command line output ([#3341](https://github.com/PrismJS/prism/issues/3341)) [`e002e78c`](https://github.com/PrismJS/prism/commit/e002e78c)
    * Add support for line continuation and improved colors ([#3326](https://github.com/PrismJS/prism/issues/3326)) [`1784b175`](https://github.com/PrismJS/prism/commit/1784b175)
    * Added span around command and output ([#3312](https://github.com/PrismJS/prism/issues/3312)) [`82d0ca15`](https://github.com/PrismJS/prism/commit/82d0ca15)

### Other

* __Core__
    * Added better error message for missing grammars ([#3311](https://github.com/PrismJS/prism/issues/3311)) [`2cc4660b`](https://github.com/PrismJS/prism/commit/2cc4660b)

## 1.26.0 (2022-01-06)

### New components

* __Atmel AVR Assembly__ ([#2078](https://github.com/PrismJS/prism/issues/2078)) [`b5a70e4c`](https://github.com/PrismJS/prism/commit/b5a70e4c)
* __Go module__ ([#3209](https://github.com/PrismJS/prism/issues/3209)) [`8476a9ab`](https://github.com/PrismJS/prism/commit/8476a9ab)
* __Keepalived Configure__ ([#2417](https://github.com/PrismJS/prism/issues/2417)) [`d908e457`](https://github.com/PrismJS/prism/commit/d908e457)
* __Tremor__ & __Trickle__ & __Troy__ ([#3087](https://github.com/PrismJS/prism/issues/3087)) [`ec25ba65`](https://github.com/PrismJS/prism/commit/ec25ba65)
* __Web IDL__ ([#3107](https://github.com/PrismJS/prism/issues/3107)) [`ef53f021`](https://github.com/PrismJS/prism/commit/ef53f021)

### Updated components

* Use `\d` for `[0-9]` ([#3097](https://github.com/PrismJS/prism/issues/3097)) [`9fe2f93e`](https://github.com/PrismJS/prism/commit/9fe2f93e)
* __6502 Assembly__
    * Use standard tokens and minor improvements ([#3184](https://github.com/PrismJS/prism/issues/3184)) [`929c33e0`](https://github.com/PrismJS/prism/commit/929c33e0)
* __AppleScript__
    * Use `class-name` standard token ([#3182](https://github.com/PrismJS/prism/issues/3182)) [`9f5e511d`](https://github.com/PrismJS/prism/commit/9f5e511d)
* __AQL__
    * Differentiate between strings and identifiers ([#3183](https://github.com/PrismJS/prism/issues/3183)) [`fa540ab7`](https://github.com/PrismJS/prism/commit/fa540ab7)
* __Arduino__
    * Added `ino` alias ([#2990](https://github.com/PrismJS/prism/issues/2990)) [`5b7ce5e4`](https://github.com/PrismJS/prism/commit/5b7ce5e4)
* __Avro IDL__
    * Removed char syntax ([#3185](https://github.com/PrismJS/prism/issues/3185)) [`c7809285`](https://github.com/PrismJS/prism/commit/c7809285)
* __Bash__
    * Added `node` to known commands ([#3291](https://github.com/PrismJS/prism/issues/3291)) [`4b19b502`](https://github.com/PrismJS/prism/commit/4b19b502)
    * Added `vcpkg` command ([#3282](https://github.com/PrismJS/prism/issues/3282)) [`b351bc69`](https://github.com/PrismJS/prism/commit/b351bc69)
    * Added `docker` and `podman` commands ([#3237](https://github.com/PrismJS/prism/issues/3237)) [`8c5ed251`](https://github.com/PrismJS/prism/commit/8c5ed251)
* __Birb__
    * Fixed class name false positives ([#3111](https://github.com/PrismJS/prism/issues/3111)) [`d7017beb`](https://github.com/PrismJS/prism/commit/d7017beb)
* __Bro__
    * Removed `variable` and minor improvements ([#3186](https://github.com/PrismJS/prism/issues/3186)) [`4cebf34c`](https://github.com/PrismJS/prism/commit/4cebf34c)
* __BSL (1C:Enterprise)__
    * Made `directive` greedy ([#3112](https://github.com/PrismJS/prism/issues/3112)) [`5c412cbb`](https://github.com/PrismJS/prism/commit/5c412cbb)
* __C__
    * Added `char` token ([#3207](https://github.com/PrismJS/prism/issues/3207)) [`d85a64ae`](https://github.com/PrismJS/prism/commit/d85a64ae)
* __C#__
    * Added `char` token ([#3270](https://github.com/PrismJS/prism/issues/3270)) [`220bc40f`](https://github.com/PrismJS/prism/commit/220bc40f)
    * Move everything into the IIFE ([#3077](https://github.com/PrismJS/prism/issues/3077)) [`9ed4cf6e`](https://github.com/PrismJS/prism/commit/9ed4cf6e)
* __Clojure__
    * Added `char` token ([#3188](https://github.com/PrismJS/prism/issues/3188)) [`1c88c7da`](https://github.com/PrismJS/prism/commit/1c88c7da)
* __Concurnas__
    * Improved tokenization ([#3189](https://github.com/PrismJS/prism/issues/3189)) [`7b34e65d`](https://github.com/PrismJS/prism/commit/7b34e65d)
* __Content-Security-Policy__
    * Improved tokenization ([#3276](https://github.com/PrismJS/prism/issues/3276)) [`a943f2bb`](https://github.com/PrismJS/prism/commit/a943f2bb)
* __Coq__
    * Improved attribute pattern performance ([#3085](https://github.com/PrismJS/prism/issues/3085)) [`2f9672aa`](https://github.com/PrismJS/prism/commit/2f9672aa)
* __Crystal__
    * Improved tokenization ([#3194](https://github.com/PrismJS/prism/issues/3194)) [`51e3ecc0`](https://github.com/PrismJS/prism/commit/51e3ecc0)
* __Cypher__
    * Removed non-standard use of `symbol` token name ([#3195](https://github.com/PrismJS/prism/issues/3195)) [`6af8a644`](https://github.com/PrismJS/prism/commit/6af8a644)
* __D__
    * Added standard char token ([#3196](https://github.com/PrismJS/prism/issues/3196)) [`dafdbdec`](https://github.com/PrismJS/prism/commit/dafdbdec)
* __Dart__
    * Added string interpolation and improved metadata ([#3197](https://github.com/PrismJS/prism/issues/3197)) [`e1370357`](https://github.com/PrismJS/prism/commit/e1370357)
* __DataWeave__
    * Fixed keywords being highlighted as functions ([#3113](https://github.com/PrismJS/prism/issues/3113)) [`532212b2`](https://github.com/PrismJS/prism/commit/532212b2)
* __EditorConfig__
    * Swap out `property` for `key`; alias with `attr-name` ([#3272](https://github.com/PrismJS/prism/issues/3272)) [`bee6ad56`](https://github.com/PrismJS/prism/commit/bee6ad56)
* __Eiffel__
    * Removed non-standard use of `builtin` name ([#3198](https://github.com/PrismJS/prism/issues/3198)) [`6add768b`](https://github.com/PrismJS/prism/commit/6add768b)
* __Elm__
    * Recognize unicode escapes as valid Char ([#3105](https://github.com/PrismJS/prism/issues/3105)) [`736c581d`](https://github.com/PrismJS/prism/commit/736c581d)
* __ERB__
    * Better embedding of Ruby ([#3192](https://github.com/PrismJS/prism/issues/3192)) [`336edeea`](https://github.com/PrismJS/prism/commit/336edeea)
* __F#__
    * Added `char` token ([#3271](https://github.com/PrismJS/prism/issues/3271)) [`b58cd722`](https://github.com/PrismJS/prism/commit/b58cd722)
* __G-code__
    * Use standard-conforming alias for checksum ([#3205](https://github.com/PrismJS/prism/issues/3205)) [`ee7ab563`](https://github.com/PrismJS/prism/commit/ee7ab563)
* __GameMaker Language__
    * Fixed `operator` token and added tests ([#3114](https://github.com/PrismJS/prism/issues/3114)) [`d359eeae`](https://github.com/PrismJS/prism/commit/d359eeae)
* __Go__
    * Added `char` token and improved `string` and `number` tokens ([#3208](https://github.com/PrismJS/prism/issues/3208)) [`f11b86e2`](https://github.com/PrismJS/prism/commit/f11b86e2)
* __GraphQL__
    * Optimized regexes ([#3136](https://github.com/PrismJS/prism/issues/3136)) [`8494519e`](https://github.com/PrismJS/prism/commit/8494519e)
* __Haml__
    * Use `symbol` alias for filter names ([#3210](https://github.com/PrismJS/prism/issues/3210)) [`3d410670`](https://github.com/PrismJS/prism/commit/3d410670)
    * Improved filter and interpolation tokenization ([#3191](https://github.com/PrismJS/prism/issues/3191)) [`005ba469`](https://github.com/PrismJS/prism/commit/005ba469)
* __Haxe__
    * Improved tokenization ([#3211](https://github.com/PrismJS/prism/issues/3211)) [`f41bcf23`](https://github.com/PrismJS/prism/commit/f41bcf23)
* __Hoon__
    * Simplified the language definition a little ([#3212](https://github.com/PrismJS/prism/issues/3212)) [`81920b62`](https://github.com/PrismJS/prism/commit/81920b62)
* __HTTP__
    * Added support for special header value tokenization ([#3275](https://github.com/PrismJS/prism/issues/3275)) [`3362fc79`](https://github.com/PrismJS/prism/commit/3362fc79)
    * Relax pattern for body ([#3169](https://github.com/PrismJS/prism/issues/3169)) [`22d0c6ba`](https://github.com/PrismJS/prism/commit/22d0c6ba)
* __HTTP Public-Key-Pins__
    * Improved tokenization ([#3278](https://github.com/PrismJS/prism/issues/3278)) [`0f1b5810`](https://github.com/PrismJS/prism/commit/0f1b5810)
* __HTTP Strict-Transport-Security__
    * Improved tokenization ([#3277](https://github.com/PrismJS/prism/issues/3277)) [`3d708b97`](https://github.com/PrismJS/prism/commit/3d708b97)
* __Idris__
    * Fixed import statements ([#3115](https://github.com/PrismJS/prism/issues/3115)) [`15cb3b78`](https://github.com/PrismJS/prism/commit/15cb3b78)
* __Io__
    * Simplified comment token ([#3214](https://github.com/PrismJS/prism/issues/3214)) [`c2afa59b`](https://github.com/PrismJS/prism/commit/c2afa59b)
* __J__
    * Made comments greedy ([#3215](https://github.com/PrismJS/prism/issues/3215)) [`5af16014`](https://github.com/PrismJS/prism/commit/5af16014)
* __Java__
    * Added `char` token ([#3217](https://github.com/PrismJS/prism/issues/3217)) [`0a9f909c`](https://github.com/PrismJS/prism/commit/0a9f909c)
* __Java stack trace__
    * Removed unreachable parts of regexes ([#3219](https://github.com/PrismJS/prism/issues/3219)) [`fa55492b`](https://github.com/PrismJS/prism/commit/fa55492b)
    * Added missing lookbehinds ([#3116](https://github.com/PrismJS/prism/issues/3116)) [`cfb2e782`](https://github.com/PrismJS/prism/commit/cfb2e782)
* __JavaScript__
    * Improved `number` pattern ([#3149](https://github.com/PrismJS/prism/issues/3149)) [`5a24cbff`](https://github.com/PrismJS/prism/commit/5a24cbff)
    * Added properties ([#3099](https://github.com/PrismJS/prism/issues/3099)) [`3b2238fa`](https://github.com/PrismJS/prism/commit/3b2238fa)
* __Jolie__
    * Improved tokenization ([#3221](https://github.com/PrismJS/prism/issues/3221)) [`dfbb2020`](https://github.com/PrismJS/prism/commit/dfbb2020)
* __JQ__
    * Improved performance of strings ([#3084](https://github.com/PrismJS/prism/issues/3084)) [`233415b8`](https://github.com/PrismJS/prism/commit/233415b8)
* __JS stack trace__
    * Added missing boundary assertion ([#3117](https://github.com/PrismJS/prism/issues/3117)) [`23d9aec1`](https://github.com/PrismJS/prism/commit/23d9aec1)
* __Julia__
    * Added `char` token ([#3223](https://github.com/PrismJS/prism/issues/3223)) [`3a876df0`](https://github.com/PrismJS/prism/commit/3a876df0)
* __Keyman__
    * Improved tokenization ([#3224](https://github.com/PrismJS/prism/issues/3224)) [`baa95cab`](https://github.com/PrismJS/prism/commit/baa95cab)
* __Kotlin__
    * Added `char` token and improved string interpolation ([#3225](https://github.com/PrismJS/prism/issues/3225)) [`563cd73e`](https://github.com/PrismJS/prism/commit/563cd73e)
* __Latte__
    * Use standard token names and combined delimiter tokens ([#3226](https://github.com/PrismJS/prism/issues/3226)) [`6b168a3b`](https://github.com/PrismJS/prism/commit/6b168a3b)
* __Liquid__
    * Removed unmatchable object variants ([#3135](https://github.com/PrismJS/prism/issues/3135)) [`05e7ab04`](https://github.com/PrismJS/prism/commit/05e7ab04)
* __Lisp__
    * Improved `defun` ([#3130](https://github.com/PrismJS/prism/issues/3130)) [`e8f84a6c`](https://github.com/PrismJS/prism/commit/e8f84a6c)
* __Makefile__
    * Use standard token names correctly ([#3227](https://github.com/PrismJS/prism/issues/3227)) [`21a3c2d7`](https://github.com/PrismJS/prism/commit/21a3c2d7)
* __Markdown__
    * Fixed typo in token name ([#3101](https://github.com/PrismJS/prism/issues/3101)) [`00f77a2c`](https://github.com/PrismJS/prism/commit/00f77a2c)
* __MAXScript__
    * Various improvements ([#3181](https://github.com/PrismJS/prism/issues/3181)) [`e9b856c8`](https://github.com/PrismJS/prism/commit/e9b856c8)
    * Fixed booleans not being highlighted ([#3134](https://github.com/PrismJS/prism/issues/3134)) [`c6574e6b`](https://github.com/PrismJS/prism/commit/c6574e6b)
* __Monkey__
    * Use standard tokens correctly ([#3228](https://github.com/PrismJS/prism/issues/3228)) [`c1025aa6`](https://github.com/PrismJS/prism/commit/c1025aa6)
* __N1QL__
    * Updated keywords + minor improvements ([#3229](https://github.com/PrismJS/prism/issues/3229)) [`642d93ec`](https://github.com/PrismJS/prism/commit/642d93ec)
* __nginx__
    * Made some patterns greedy ([#3230](https://github.com/PrismJS/prism/issues/3230)) [`7b72e0ad`](https://github.com/PrismJS/prism/commit/7b72e0ad)
* __Nim__
    * Added `char` token and made some tokens greedy ([#3231](https://github.com/PrismJS/prism/issues/3231)) [`2334b4b6`](https://github.com/PrismJS/prism/commit/2334b4b6)
    * Fixed backtick identifier ([#3118](https://github.com/PrismJS/prism/issues/3118)) [`75331bea`](https://github.com/PrismJS/prism/commit/75331bea)
* __Nix__
    * Use standard token name correctly ([#3232](https://github.com/PrismJS/prism/issues/3232)) [`5bf6e35f`](https://github.com/PrismJS/prism/commit/5bf6e35f)
    * Removed unmatchable token ([#3119](https://github.com/PrismJS/prism/issues/3119)) [`dc1e808f`](https://github.com/PrismJS/prism/commit/dc1e808f)
* __NSIS__
    * Made `comment` greedy ([#3234](https://github.com/PrismJS/prism/issues/3234)) [`969f152a`](https://github.com/PrismJS/prism/commit/969f152a)
    * Update regex pattern for variables ([#3266](https://github.com/PrismJS/prism/issues/3266)) [`adcc8784`](https://github.com/PrismJS/prism/commit/adcc8784)
    * Update regex for constants pattern ([#3267](https://github.com/PrismJS/prism/issues/3267)) [`55583fb2`](https://github.com/PrismJS/prism/commit/55583fb2)
* __Objective-C__
    * Improved `string` token ([#3235](https://github.com/PrismJS/prism/issues/3235)) [`8e0e95f3`](https://github.com/PrismJS/prism/commit/8e0e95f3)
* __OCaml__
    * Improved tokenization ([#3269](https://github.com/PrismJS/prism/issues/3269)) [`7bcc5da0`](https://github.com/PrismJS/prism/commit/7bcc5da0)
    * Removed unmatchable punctuation variant ([#3120](https://github.com/PrismJS/prism/issues/3120)) [`314d6994`](https://github.com/PrismJS/prism/commit/314d6994)
* __Oz__
    * Improved tokenization ([#3240](https://github.com/PrismJS/prism/issues/3240)) [`a3905c04`](https://github.com/PrismJS/prism/commit/a3905c04)
* __Pascal__
    * Added support for asm and directives ([#2653](https://github.com/PrismJS/prism/issues/2653)) [`f053af13`](https://github.com/PrismJS/prism/commit/f053af13)
* __PATROL Scripting Language__
    * Added `boolean` token ([#3248](https://github.com/PrismJS/prism/issues/3248)) [`a5b6c5eb`](https://github.com/PrismJS/prism/commit/a5b6c5eb)
* __Perl__
    * Improved tokenization ([#3241](https://github.com/PrismJS/prism/issues/3241)) [`f22ea9f9`](https://github.com/PrismJS/prism/commit/f22ea9f9)
* __PHP__
    * Removed useless keyword tokens ([#3121](https://github.com/PrismJS/prism/issues/3121)) [`ee62a080`](https://github.com/PrismJS/prism/commit/ee62a080)
* __PHP Extras__
    * Improved `scope` and `this` ([#3243](https://github.com/PrismJS/prism/issues/3243)) [`59ef51db`](https://github.com/PrismJS/prism/commit/59ef51db)
* __PL/SQL__
    * Updated keywords + other improvements ([#3109](https://github.com/PrismJS/prism/issues/3109)) [`e7ba877b`](https://github.com/PrismJS/prism/commit/e7ba877b)
* __PowerQuery__
    * Improved tokenization and use standard tokens correctly ([#3244](https://github.com/PrismJS/prism/issues/3244)) [`5688f487`](https://github.com/PrismJS/prism/commit/5688f487)
    * Removed useless `data-type` alternative ([#3122](https://github.com/PrismJS/prism/issues/3122)) [`eeb13996`](https://github.com/PrismJS/prism/commit/eeb13996)
* __PowerShell__
    * Fixed lookbehind + refactoring ([#3245](https://github.com/PrismJS/prism/issues/3245)) [`d30a2da6`](https://github.com/PrismJS/prism/commit/d30a2da6)
* __Processing__
    * Use standard tokens correctly ([#3246](https://github.com/PrismJS/prism/issues/3246)) [`5ee8c557`](https://github.com/PrismJS/prism/commit/5ee8c557)
* __Prolog__
    * Removed variable token + minor improvements ([#3247](https://github.com/PrismJS/prism/issues/3247)) [`bacf9ae3`](https://github.com/PrismJS/prism/commit/bacf9ae3)
* __Pug__
    * Improved filter tokenization ([#3258](https://github.com/PrismJS/prism/issues/3258)) [`0390e644`](https://github.com/PrismJS/prism/commit/0390e644)
* __PureBasic__
    * Fixed token order inside `asm` token ([#3123](https://github.com/PrismJS/prism/issues/3123)) [`f3b25786`](https://github.com/PrismJS/prism/commit/f3b25786)
* __Python__
    * Made `comment` greedy ([#3249](https://github.com/PrismJS/prism/issues/3249)) [`8ecef306`](https://github.com/PrismJS/prism/commit/8ecef306)
    * Add `match` and `case` (soft) keywords ([#3142](https://github.com/PrismJS/prism/issues/3142)) [`3f24dc72`](https://github.com/PrismJS/prism/commit/3f24dc72)
    * Recognize walrus operator ([#3126](https://github.com/PrismJS/prism/issues/3126)) [`18bd101c`](https://github.com/PrismJS/prism/commit/18bd101c)
    * Fixed numbers ending with a dot ([#3106](https://github.com/PrismJS/prism/issues/3106)) [`2c63efa6`](https://github.com/PrismJS/prism/commit/2c63efa6)
* __QML__
    * Made `string` greedy ([#3250](https://github.com/PrismJS/prism/issues/3250)) [`1e6dcb51`](https://github.com/PrismJS/prism/commit/1e6dcb51)
* __React JSX__
    * Move alias property ([#3222](https://github.com/PrismJS/prism/issues/3222)) [`18c92048`](https://github.com/PrismJS/prism/commit/18c92048)
* __React TSX__
    * Removed `parameter` token ([#3090](https://github.com/PrismJS/prism/issues/3090)) [`0a313f4f`](https://github.com/PrismJS/prism/commit/0a313f4f)
* __Reason__
    * Use standard tokens correctly ([#3251](https://github.com/PrismJS/prism/issues/3251)) [`809af0d9`](https://github.com/PrismJS/prism/commit/809af0d9)
* __Regex__
    * Fixed char-class/char-set confusion ([#3124](https://github.com/PrismJS/prism/issues/3124)) [`4dde2e20`](https://github.com/PrismJS/prism/commit/4dde2e20)
* __Ren'py__
    * Improved language + added tests ([#3125](https://github.com/PrismJS/prism/issues/3125)) [`ede55b2c`](https://github.com/PrismJS/prism/commit/ede55b2c)
* __Rip__
    * Use standard `char` token ([#3252](https://github.com/PrismJS/prism/issues/3252)) [`2069ab0c`](https://github.com/PrismJS/prism/commit/2069ab0c)
* __Ruby__
    * Improved tokenization ([#3193](https://github.com/PrismJS/prism/issues/3193)) [`86028adb`](https://github.com/PrismJS/prism/commit/86028adb)
* __Rust__
    * Improved `type-definition` and use standard tokens correctly ([#3253](https://github.com/PrismJS/prism/issues/3253)) [`4049e5c6`](https://github.com/PrismJS/prism/commit/4049e5c6)
* __Scheme__
    * Use standard `char` token ([#3254](https://github.com/PrismJS/prism/issues/3254)) [`7d740c45`](https://github.com/PrismJS/prism/commit/7d740c45)
    * Updates syntax for reals ([#3159](https://github.com/PrismJS/prism/issues/3159)) [`4eb81fa1`](https://github.com/PrismJS/prism/commit/4eb81fa1)
* __Smalltalk__
    * Use standard `char` token ([#3255](https://github.com/PrismJS/prism/issues/3255)) [`a7bb3001`](https://github.com/PrismJS/prism/commit/a7bb3001)
    * Added `boolean` token ([#3100](https://github.com/PrismJS/prism/issues/3100)) [`51382524`](https://github.com/PrismJS/prism/commit/51382524)
* __Smarty__
    * Improved tokenization ([#3268](https://github.com/PrismJS/prism/issues/3268)) [`acc0bc09`](https://github.com/PrismJS/prism/commit/acc0bc09)
* __SQL__
    * Added identifier token ([#3141](https://github.com/PrismJS/prism/issues/3141)) [`4e00cddd`](https://github.com/PrismJS/prism/commit/4e00cddd)
* __Squirrel__
    * Use standard `char` token ([#3256](https://github.com/PrismJS/prism/issues/3256)) [`58a65bfd`](https://github.com/PrismJS/prism/commit/58a65bfd)
* __Stan__
    * Added missing keywords and HOFs ([#3238](https://github.com/PrismJS/prism/issues/3238)) [`afd77ed1`](https://github.com/PrismJS/prism/commit/afd77ed1)
* __Structured Text (IEC 61131-3)__
    * Structured text: Improved tokenization ([#3213](https://github.com/PrismJS/prism/issues/3213)) [`d04d166d`](https://github.com/PrismJS/prism/commit/d04d166d)
* __Swift__
    * Added support for `isolated` keyword ([#3174](https://github.com/PrismJS/prism/issues/3174)) [`18c828a6`](https://github.com/PrismJS/prism/commit/18c828a6)
* __TAP__
    * Conform to quoted-properties style ([#3127](https://github.com/PrismJS/prism/issues/3127)) [`3ef71533`](https://github.com/PrismJS/prism/commit/3ef71533)
* __Tremor__
    * Use standard `regex` token ([#3257](https://github.com/PrismJS/prism/issues/3257)) [`c56e4bf5`](https://github.com/PrismJS/prism/commit/c56e4bf5)
* __Twig__
    * Improved tokenization ([#3259](https://github.com/PrismJS/prism/issues/3259)) [`e03a7c24`](https://github.com/PrismJS/prism/commit/e03a7c24)
* __TypeScript__
    * Removed duplicate keywords ([#3132](https://github.com/PrismJS/prism/issues/3132)) [`91060fd6`](https://github.com/PrismJS/prism/commit/91060fd6)
* __URI__
    * Fixed IPv4 regex ([#3128](https://github.com/PrismJS/prism/issues/3128)) [`599e30ee`](https://github.com/PrismJS/prism/commit/599e30ee)
* __V__
    * Use standard `char` token ([#3260](https://github.com/PrismJS/prism/issues/3260)) [`e4373256`](https://github.com/PrismJS/prism/commit/e4373256)
* __Verilog__
    * Use standard tokens correctly ([#3261](https://github.com/PrismJS/prism/issues/3261)) [`43124129`](https://github.com/PrismJS/prism/commit/43124129)
* __Visual Basic__
    * Simplify regexes and use more common aliases ([#3262](https://github.com/PrismJS/prism/issues/3262)) [`aa73d448`](https://github.com/PrismJS/prism/commit/aa73d448)
* __Wolfram language__
    * Removed unmatchable punctuation variant ([#3133](https://github.com/PrismJS/prism/issues/3133)) [`a28a86ad`](https://github.com/PrismJS/prism/commit/a28a86ad)
* __Xojo (REALbasic)__
    * Proper token name for directives ([#3263](https://github.com/PrismJS/prism/issues/3263)) [`ffd8343f`](https://github.com/PrismJS/prism/commit/ffd8343f)
* __Zig__
    * Added missing keywords ([#3279](https://github.com/PrismJS/prism/issues/3279)) [`deed35e3`](https://github.com/PrismJS/prism/commit/deed35e3)
    * Use standard `char` token ([#3264](https://github.com/PrismJS/prism/issues/3264)) [`c3f9fb70`](https://github.com/PrismJS/prism/commit/c3f9fb70)
    * Fixed module comments and astral chars ([#3129](https://github.com/PrismJS/prism/issues/3129)) [`09a0e2ba`](https://github.com/PrismJS/prism/commit/09a0e2ba)

### Updated plugins

* __File Highlight__
    * File highlight+data range ([#1813](https://github.com/PrismJS/prism/issues/1813)) [`d38592c5`](https://github.com/PrismJS/prism/commit/d38592c5)
* __Keep Markup__
    * Added `drop-tokens` option class ([#3166](https://github.com/PrismJS/prism/issues/3166)) [`b679cfe6`](https://github.com/PrismJS/prism/commit/b679cfe6)
* __Line Highlight__
    * Expose `highlightLines` function as `Prism.plugins.highlightLines` ([#3086](https://github.com/PrismJS/prism/issues/3086)) [`9f4c0e74`](https://github.com/PrismJS/prism/commit/9f4c0e74)
* __Toolbar__
    * Set `z-index` of `.toolbar` to 10 ([#3163](https://github.com/PrismJS/prism/issues/3163)) [`1cac3559`](https://github.com/PrismJS/prism/commit/1cac3559)

### Updated themes

* Coy: Set `z-index` to make shadows visible in colored table cells ([#3161](https://github.com/PrismJS/prism/issues/3161)) [`79f250f3`](https://github.com/PrismJS/prism/commit/79f250f3)
* Coy: Added padding to account for box shadow ([#3143](https://github.com/PrismJS/prism/issues/3143)) [`a6a4ce7e`](https://github.com/PrismJS/prism/commit/a6a4ce7e)

### Other

* __Core__
    * Added `setLanguage` util function ([#3167](https://github.com/PrismJS/prism/issues/3167)) [`b631949a`](https://github.com/PrismJS/prism/commit/b631949a)
    * Fixed type error on null ([#3057](https://github.com/PrismJS/prism/issues/3057)) [`a80a68ba`](https://github.com/PrismJS/prism/commit/a80a68ba)
    * Document `disableWorkerMessageHandler` ([#3088](https://github.com/PrismJS/prism/issues/3088)) [`213cf7be`](https://github.com/PrismJS/prism/commit/213cf7be)
* __Infrastructure__
    * Tests: Added `.html.test` files for replace `.js` language tests ([#3148](https://github.com/PrismJS/prism/issues/3148)) [`2e834c8c`](https://github.com/PrismJS/prism/commit/2e834c8c)
    * Added regex coverage ([#3138](https://github.com/PrismJS/prism/issues/3138)) [`5333e281`](https://github.com/PrismJS/prism/commit/5333e281)
    * Tests: Added `TestCaseFile` class and generalized `runTestCase` ([#3147](https://github.com/PrismJS/prism/issues/3147)) [`ae8888a0`](https://github.com/PrismJS/prism/commit/ae8888a0)
    * Added even more language tests ([#3137](https://github.com/PrismJS/prism/issues/3137)) [`344d0b27`](https://github.com/PrismJS/prism/commit/344d0b27)
    * Added more plugin tests ([#1969](https://github.com/PrismJS/prism/issues/1969)) [`a394a14d`](https://github.com/PrismJS/prism/commit/a394a14d)
    * Added more language tests ([#3131](https://github.com/PrismJS/prism/issues/3131)) [`2f7f7364`](https://github.com/PrismJS/prism/commit/2f7f7364)
    * `package.json`: Added `engines.node` field ([#3108](https://github.com/PrismJS/prism/issues/3108)) [`798ee4f6`](https://github.com/PrismJS/prism/commit/798ee4f6)
    * Use tabs in `package(-lock).json` ([#3098](https://github.com/PrismJS/prism/issues/3098)) [`8daebb4a`](https://github.com/PrismJS/prism/commit/8daebb4a)
    * Update `eslint-plugin-regexp@1.2.0` ([#3091](https://github.com/PrismJS/prism/issues/3091)) [`e6e1d5ae`](https://github.com/PrismJS/prism/commit/e6e1d5ae)
    * Added minified CSS ([#3073](https://github.com/PrismJS/prism/issues/3073)) [`d63d6c0e`](https://github.com/PrismJS/prism/commit/d63d6c0e)
* __Website__
    * Readme: Clarify usage of our build system ([#3239](https://github.com/PrismJS/prism/issues/3239)) [`6f1d904a`](https://github.com/PrismJS/prism/commit/6f1d904a)
    * Improved CDN usage URLs ([#3285](https://github.com/PrismJS/prism/issues/3285)) [`6c21b2f7`](https://github.com/PrismJS/prism/commit/6c21b2f7)
    * Update download.html [`9d5424b6`](https://github.com/PrismJS/prism/commit/9d5424b6)
    * Autoloader: Mention how to load grammars from URLs ([#3218](https://github.com/PrismJS/prism/issues/3218)) [`cefccdd1`](https://github.com/PrismJS/prism/commit/cefccdd1)
    * Added PrismJS React and HTML tutorial link ([#3190](https://github.com/PrismJS/prism/issues/3190)) [`0ecdbdce`](https://github.com/PrismJS/prism/commit/0ecdbdce)
    * Improved readability ([#3177](https://github.com/PrismJS/prism/issues/3177)) [`4433d7fe`](https://github.com/PrismJS/prism/commit/4433d7fe)
    * Fixed red highlighting in Firefox ([#3178](https://github.com/PrismJS/prism/issues/3178)) [`746da79b`](https://github.com/PrismJS/prism/commit/746da79b)
    * Use Keep markup to highlight code section ([#3164](https://github.com/PrismJS/prism/issues/3164)) [`ebd59e32`](https://github.com/PrismJS/prism/commit/ebd59e32)
    * Document standard tokens and provide examples ([#3104](https://github.com/PrismJS/prism/issues/3104)) [`37551200`](https://github.com/PrismJS/prism/commit/37551200)
    * Fixed dead link to third-party tutorial [#3155](https://github.com/PrismJS/prism/issues/3155) ([#3156](https://github.com/PrismJS/prism/issues/3156)) [`31b4c1b8`](https://github.com/PrismJS/prism/commit/31b4c1b8)
    * Repositioned theme selector ([#3146](https://github.com/PrismJS/prism/issues/3146)) [`ea361e5a`](https://github.com/PrismJS/prism/commit/ea361e5a)
    * Adjusted TOC's line height for better readability ([#3145](https://github.com/PrismJS/prism/issues/3145)) [`c5629706`](https://github.com/PrismJS/prism/commit/c5629706)
    * Updated plugin header template ([#3144](https://github.com/PrismJS/prism/issues/3144)) [`faedfe85`](https://github.com/PrismJS/prism/commit/faedfe85)
    * Update test and example pages to use Autoloader ([#1936](https://github.com/PrismJS/prism/issues/1936)) [`3d96eedc`](https://github.com/PrismJS/prism/commit/3d96eedc)

## 1.25.0 (2021-09-16)

### New components

* __AviSynth__ ([#3071](https://github.com/PrismJS/prism/issues/3071)) [`746a4b1a`](https://github.com/PrismJS/prism/commit/746a4b1a)
* __Avro IDL__ ([#3051](https://github.com/PrismJS/prism/issues/3051)) [`87e5a376`](https://github.com/PrismJS/prism/commit/87e5a376)
* __Bicep__ ([#3027](https://github.com/PrismJS/prism/issues/3027)) [`c1dce998`](https://github.com/PrismJS/prism/commit/c1dce998)
* __GAP (CAS)__ ([#3054](https://github.com/PrismJS/prism/issues/3054)) [`23cd9b65`](https://github.com/PrismJS/prism/commit/23cd9b65)
* __GN__ ([#3062](https://github.com/PrismJS/prism/issues/3062)) [`4f97b82b`](https://github.com/PrismJS/prism/commit/4f97b82b)
* __Hoon__ ([#2978](https://github.com/PrismJS/prism/issues/2978)) [`ea776756`](https://github.com/PrismJS/prism/commit/ea776756)
* __Kusto__ ([#3068](https://github.com/PrismJS/prism/issues/3068)) [`e008ea05`](https://github.com/PrismJS/prism/commit/e008ea05)
* __Magma (CAS)__ ([#3055](https://github.com/PrismJS/prism/issues/3055)) [`a1b67ce3`](https://github.com/PrismJS/prism/commit/a1b67ce3)
* __MAXScript__ ([#3060](https://github.com/PrismJS/prism/issues/3060)) [`4fbdd2f8`](https://github.com/PrismJS/prism/commit/4fbdd2f8)
* __Mermaid__ ([#3050](https://github.com/PrismJS/prism/issues/3050)) [`148c1eca`](https://github.com/PrismJS/prism/commit/148c1eca)
* __Razor C#__ ([#3064](https://github.com/PrismJS/prism/issues/3064)) [`4433ccfc`](https://github.com/PrismJS/prism/commit/4433ccfc)
* __Systemd configuration file__ ([#3053](https://github.com/PrismJS/prism/issues/3053)) [`8df825e0`](https://github.com/PrismJS/prism/commit/8df825e0)
* __Wren__ ([#3063](https://github.com/PrismJS/prism/issues/3063)) [`6a356d25`](https://github.com/PrismJS/prism/commit/6a356d25)

### Updated components

* __Bicep__
    * Added support for multiline and interpolated strings and other improvements ([#3028](https://github.com/PrismJS/prism/issues/3028)) [`748bb9ac`](https://github.com/PrismJS/prism/commit/748bb9ac)
* __C#__
    * Added `with` keyword & improved record support ([#2993](https://github.com/PrismJS/prism/issues/2993)) [`fdd291c0`](https://github.com/PrismJS/prism/commit/fdd291c0)
    * Added `record`, `init`, and `nullable` keyword ([#2991](https://github.com/PrismJS/prism/issues/2991)) [`9b561565`](https://github.com/PrismJS/prism/commit/9b561565)
    * Added context check for `from` keyword ([#2970](https://github.com/PrismJS/prism/issues/2970)) [`158f25d4`](https://github.com/PrismJS/prism/commit/158f25d4)
* __C++__
    * Fixed generic function false positive ([#3043](https://github.com/PrismJS/prism/issues/3043)) [`5de8947f`](https://github.com/PrismJS/prism/commit/5de8947f)
* __Clojure__
    * Improved tokenization ([#3056](https://github.com/PrismJS/prism/issues/3056)) [`8d0b74b5`](https://github.com/PrismJS/prism/commit/8d0b74b5)
* __Hoon__
    * Fixed mixed-case aura tokenization ([#3002](https://github.com/PrismJS/prism/issues/3002)) [`9c8911bd`](https://github.com/PrismJS/prism/commit/9c8911bd)
* __Liquid__
    * Added all objects from Shopify reference ([#2998](https://github.com/PrismJS/prism/issues/2998)) [`693b7433`](https://github.com/PrismJS/prism/commit/693b7433)
    * Added `empty` keyword ([#2997](https://github.com/PrismJS/prism/issues/2997)) [`fe3bc526`](https://github.com/PrismJS/prism/commit/fe3bc526)
* __Log file__
    * Added support for Java stack traces ([#3003](https://github.com/PrismJS/prism/issues/3003)) [`b0365e70`](https://github.com/PrismJS/prism/commit/b0365e70)
* __Markup__
    * Made most patterns greedy ([#3065](https://github.com/PrismJS/prism/issues/3065)) [`52e8cee9`](https://github.com/PrismJS/prism/commit/52e8cee9)
    * Fixed ReDoS ([#3078](https://github.com/PrismJS/prism/issues/3078)) [`0ff371bb`](https://github.com/PrismJS/prism/commit/0ff371bb)
* __PureScript__
    * Made `∀` a keyword (alias for `forall`) ([#3005](https://github.com/PrismJS/prism/issues/3005)) [`b38fc89a`](https://github.com/PrismJS/prism/commit/b38fc89a)
    * Improved Haskell and PureScript ([#3020](https://github.com/PrismJS/prism/issues/3020)) [`679539ec`](https://github.com/PrismJS/prism/commit/679539ec)
* __Python__
    * Support for underscores in numbers ([#3039](https://github.com/PrismJS/prism/issues/3039)) [`6f5d68f7`](https://github.com/PrismJS/prism/commit/6f5d68f7)
* __Sass__
    * Fixed issues with CSS Extras ([#2994](https://github.com/PrismJS/prism/issues/2994)) [`14fdfe32`](https://github.com/PrismJS/prism/commit/14fdfe32)
* __Shell session__
    * Fixed command false positives ([#3048](https://github.com/PrismJS/prism/issues/3048)) [`35b88fcf`](https://github.com/PrismJS/prism/commit/35b88fcf)
    * Added support for the percent sign as shell symbol ([#3010](https://github.com/PrismJS/prism/issues/3010)) [`4492b62b`](https://github.com/PrismJS/prism/commit/4492b62b)
* __Swift__
    * Major improvements ([#3022](https://github.com/PrismJS/prism/issues/3022)) [`8541db2e`](https://github.com/PrismJS/prism/commit/8541db2e)
    * Added support for `@propertyWrapper`, `@MainActor`, and `@globalActor` ([#3009](https://github.com/PrismJS/prism/issues/3009)) [`ce5e0f01`](https://github.com/PrismJS/prism/commit/ce5e0f01)
    * Added support for new Swift 5.5 keywords ([#2988](https://github.com/PrismJS/prism/issues/2988)) [`bb93fac0`](https://github.com/PrismJS/prism/commit/bb93fac0)
* __TypeScript__
    * Fixed keyword false positives ([#3001](https://github.com/PrismJS/prism/issues/3001)) [`212e0ef2`](https://github.com/PrismJS/prism/commit/212e0ef2)

### Updated plugins

* __JSONP Highlight__
    * Refactored JSONP logic ([#3018](https://github.com/PrismJS/prism/issues/3018)) [`5126d1e1`](https://github.com/PrismJS/prism/commit/5126d1e1)
* __Line Highlight__
    * Extend highlight to full line width inside scroll container ([#3011](https://github.com/PrismJS/prism/issues/3011)) [`e289ec60`](https://github.com/PrismJS/prism/commit/e289ec60)
* __Normalize Whitespace__
    * Removed unnecessary checks ([#3017](https://github.com/PrismJS/prism/issues/3017)) [`63edf14c`](https://github.com/PrismJS/prism/commit/63edf14c)
* __Previewers__
    * Ensure popup is visible across themes ([#3080](https://github.com/PrismJS/prism/issues/3080)) [`c7b6a7f6`](https://github.com/PrismJS/prism/commit/c7b6a7f6)

### Updated themes

* __Twilight__
    * Increase selector specificities of plugin overrides ([#3081](https://github.com/PrismJS/prism/issues/3081)) [`ffb20439`](https://github.com/PrismJS/prism/commit/ffb20439)

### Other

* __Infrastructure__
    * Added benchmark suite ([#2153](https://github.com/PrismJS/prism/issues/2153)) [`44456b21`](https://github.com/PrismJS/prism/commit/44456b21)
    * Tests: Insert expected JSON by Default ([#2960](https://github.com/PrismJS/prism/issues/2960)) [`e997dd35`](https://github.com/PrismJS/prism/commit/e997dd35)
    * Tests: Improved dection of empty patterns ([#3058](https://github.com/PrismJS/prism/issues/3058)) [`d216e602`](https://github.com/PrismJS/prism/commit/d216e602)
* __Website__
    * Highlight Keywords: More documentation ([#3049](https://github.com/PrismJS/prism/issues/3049)) [`247fd9a3`](https://github.com/PrismJS/prism/commit/247fd9a3)


## 1.24.1 (2021-07-03)

### Updated components

* __Markdown__
    * Fixed Markdown not working in NodeJS ([#2977](https://github.com/PrismJS/prism/issues/2977)) [`151121cd`](https://github.com/PrismJS/prism/commit/151121cd)

### Updated plugins

* __Toolbar__
    * Fixed styles being applies to nested elements ([#2980](https://github.com/PrismJS/prism/issues/2980)) [`748ecddc`](https://github.com/PrismJS/prism/commit/748ecddc)


## 1.24.0 (2021-06-27)

### New components

* __CFScript__ ([#2771](https://github.com/PrismJS/prism/issues/2771)) [`b0a6ec85`](https://github.com/PrismJS/prism/commit/b0a6ec85)
* __ChaiScript__ ([#2706](https://github.com/PrismJS/prism/issues/2706)) [`3f7d7453`](https://github.com/PrismJS/prism/commit/3f7d7453)
* __COBOL__ ([#2800](https://github.com/PrismJS/prism/issues/2800)) [`7e5f78ff`](https://github.com/PrismJS/prism/commit/7e5f78ff)
* __Coq__ ([#2803](https://github.com/PrismJS/prism/issues/2803)) [`41e25d3c`](https://github.com/PrismJS/prism/commit/41e25d3c)
* __CSV__ ([#2794](https://github.com/PrismJS/prism/issues/2794)) [`f9b69528`](https://github.com/PrismJS/prism/commit/f9b69528)
* __DOT (Graphviz)__ ([#2690](https://github.com/PrismJS/prism/issues/2690)) [`1f91868e`](https://github.com/PrismJS/prism/commit/1f91868e)
* __False__ ([#2802](https://github.com/PrismJS/prism/issues/2802)) [`99a21dc5`](https://github.com/PrismJS/prism/commit/99a21dc5)
* __ICU Message Format__ ([#2745](https://github.com/PrismJS/prism/issues/2745)) [`bf4e7ba9`](https://github.com/PrismJS/prism/commit/bf4e7ba9)
* __Idris__ ([#2755](https://github.com/PrismJS/prism/issues/2755)) [`e9314415`](https://github.com/PrismJS/prism/commit/e9314415)
* __Jexl__ ([#2764](https://github.com/PrismJS/prism/issues/2764)) [`7e51b99c`](https://github.com/PrismJS/prism/commit/7e51b99c)
* __KuMir (КуМир)__ ([#2760](https://github.com/PrismJS/prism/issues/2760)) [`3419fb77`](https://github.com/PrismJS/prism/commit/3419fb77)
* __Log file__ ([#2796](https://github.com/PrismJS/prism/issues/2796)) [`2bc6475b`](https://github.com/PrismJS/prism/commit/2bc6475b)
* __Nevod__ ([#2798](https://github.com/PrismJS/prism/issues/2798)) [`f84c49c5`](https://github.com/PrismJS/prism/commit/f84c49c5)
* __OpenQasm__ ([#2797](https://github.com/PrismJS/prism/issues/2797)) [`1a2347a3`](https://github.com/PrismJS/prism/commit/1a2347a3)
* __PATROL Scripting Language__ ([#2739](https://github.com/PrismJS/prism/issues/2739)) [`18c67b49`](https://github.com/PrismJS/prism/commit/18c67b49)
* __Q#__ ([#2804](https://github.com/PrismJS/prism/issues/2804)) [`1b63cd01`](https://github.com/PrismJS/prism/commit/1b63cd01)
* __Rego__ ([#2624](https://github.com/PrismJS/prism/issues/2624)) [`e38986f9`](https://github.com/PrismJS/prism/commit/e38986f9)
* __Squirrel__ ([#2721](https://github.com/PrismJS/prism/issues/2721)) [`fd1081d2`](https://github.com/PrismJS/prism/commit/fd1081d2)
* __URI__ ([#2708](https://github.com/PrismJS/prism/issues/2708)) [`bbc77d19`](https://github.com/PrismJS/prism/commit/bbc77d19)
* __V__ ([#2687](https://github.com/PrismJS/prism/issues/2687)) [`72962701`](https://github.com/PrismJS/prism/commit/72962701)
* __Wolfram language__ & __Mathematica__ & __Mathematica Notebook__ ([#2921](https://github.com/PrismJS/prism/issues/2921)) [`c4f6b2cc`](https://github.com/PrismJS/prism/commit/c4f6b2cc)

### Updated components

* Fixed problems reported by `regexp/no-dupe-disjunctions` ([#2952](https://github.com/PrismJS/prism/issues/2952)) [`f471d2d7`](https://github.com/PrismJS/prism/commit/f471d2d7)
* Fixed some cases of quadratic worst-case runtime ([#2922](https://github.com/PrismJS/prism/issues/2922)) [`79d22182`](https://github.com/PrismJS/prism/commit/79d22182)
* Fixed 2 cases of exponential backtracking ([#2774](https://github.com/PrismJS/prism/issues/2774)) [`d85e30da`](https://github.com/PrismJS/prism/commit/d85e30da)
* __AQL__
    * Update for ArangoDB 3.8 ([#2842](https://github.com/PrismJS/prism/issues/2842)) [`ea82478d`](https://github.com/PrismJS/prism/commit/ea82478d)
* __AutoHotkey__
    * Improved tag pattern ([#2920](https://github.com/PrismJS/prism/issues/2920)) [`fc2a3334`](https://github.com/PrismJS/prism/commit/fc2a3334)
* __Bash__
    * Accept hyphens in function names ([#2832](https://github.com/PrismJS/prism/issues/2832)) [`e4ad22ad`](https://github.com/PrismJS/prism/commit/e4ad22ad)
    * Fixed single-quoted strings ([#2792](https://github.com/PrismJS/prism/issues/2792)) [`e5cfdb4a`](https://github.com/PrismJS/prism/commit/e5cfdb4a)
* __C++__
    * Added support for generic functions and made `::` punctuation ([#2814](https://github.com/PrismJS/prism/issues/2814)) [`3df62fd0`](https://github.com/PrismJS/prism/commit/3df62fd0)
    * Added missing keywords and modules ([#2763](https://github.com/PrismJS/prism/issues/2763)) [`88fa72cf`](https://github.com/PrismJS/prism/commit/88fa72cf)
* __Dart__
    * Improved support for classes & generics ([#2810](https://github.com/PrismJS/prism/issues/2810)) [`d0bcd074`](https://github.com/PrismJS/prism/commit/d0bcd074)
* __Docker__
    * Improvements ([#2720](https://github.com/PrismJS/prism/issues/2720)) [`93dd83c2`](https://github.com/PrismJS/prism/commit/93dd83c2)
* __Elixir__
    * Added missing keywords ([#2958](https://github.com/PrismJS/prism/issues/2958)) [`114e4626`](https://github.com/PrismJS/prism/commit/114e4626)
    * Added missing keyword and other improvements ([#2773](https://github.com/PrismJS/prism/issues/2773)) [`e6c0d298`](https://github.com/PrismJS/prism/commit/e6c0d298)
    * Added `defdelagate` keyword and highlighting for function/module names ([#2709](https://github.com/PrismJS/prism/issues/2709)) [`59f725d7`](https://github.com/PrismJS/prism/commit/59f725d7)
* __F#__
    * Fixed comment false positive ([#2703](https://github.com/PrismJS/prism/issues/2703)) [`a5d7178c`](https://github.com/PrismJS/prism/commit/a5d7178c)
* __GraphQL__
    * Fixed `definition-query` and `definition-mutation` tokens ([#2964](https://github.com/PrismJS/prism/issues/2964)) [`bfd7fded`](https://github.com/PrismJS/prism/commit/bfd7fded)
    * Added more detailed tokens ([#2939](https://github.com/PrismJS/prism/issues/2939)) [`34f24ac9`](https://github.com/PrismJS/prism/commit/34f24ac9)
* __Handlebars__
    * Added `hbs` alias ([#2874](https://github.com/PrismJS/prism/issues/2874)) [`43976351`](https://github.com/PrismJS/prism/commit/43976351)
* __HTTP__
    * Fixed body not being highlighted ([#2734](https://github.com/PrismJS/prism/issues/2734)) [`1dfc8271`](https://github.com/PrismJS/prism/commit/1dfc8271)
    * More granular tokenization ([#2722](https://github.com/PrismJS/prism/issues/2722)) [`6183fd9b`](https://github.com/PrismJS/prism/commit/6183fd9b)
    * Allow root path in request line ([#2711](https://github.com/PrismJS/prism/issues/2711)) [`4e7b2a82`](https://github.com/PrismJS/prism/commit/4e7b2a82)
* __Ini__
    * Consistently mimic Win32 INI parsing ([#2779](https://github.com/PrismJS/prism/issues/2779)) [`42d24fa2`](https://github.com/PrismJS/prism/commit/42d24fa2)
* __Java__
    * Improved generics ([#2812](https://github.com/PrismJS/prism/issues/2812)) [`4ec7535c`](https://github.com/PrismJS/prism/commit/4ec7535c)
* __JavaScript__
    * Added support for import assertions ([#2953](https://github.com/PrismJS/prism/issues/2953)) [`ab7c9953`](https://github.com/PrismJS/prism/commit/ab7c9953)
    * Added support for RegExp Match Indices ([#2900](https://github.com/PrismJS/prism/issues/2900)) [`415651a0`](https://github.com/PrismJS/prism/commit/415651a0)
    * Added hashbang and private getters/setters ([#2815](https://github.com/PrismJS/prism/issues/2815)) [`9c610ae6`](https://github.com/PrismJS/prism/commit/9c610ae6)
    * Improved contextual keywords ([#2713](https://github.com/PrismJS/prism/issues/2713)) [`022f90a0`](https://github.com/PrismJS/prism/commit/022f90a0)
* __JS Templates__
    * Added SQL templates ([#2945](https://github.com/PrismJS/prism/issues/2945)) [`abab9104`](https://github.com/PrismJS/prism/commit/abab9104)
* __JSON__
    * Fixed backtracking issue in Safari ([#2691](https://github.com/PrismJS/prism/issues/2691)) [`cf28d1b2`](https://github.com/PrismJS/prism/commit/cf28d1b2)
* __Liquid__
    * Added Markup support, missing tokens, and other improvements ([#2950](https://github.com/PrismJS/prism/issues/2950)) [`ac1d12f9`](https://github.com/PrismJS/prism/commit/ac1d12f9)
* __Log file__
    * Minor improvements ([#2851](https://github.com/PrismJS/prism/issues/2851)) [`45ec4a88`](https://github.com/PrismJS/prism/commit/45ec4a88)
* __Markdown__
    * Improved code snippets ([#2967](https://github.com/PrismJS/prism/issues/2967)) [`e9477d83`](https://github.com/PrismJS/prism/commit/e9477d83)
    * Workaround for incorrect highlighting due to double `wrap` hook ([#2719](https://github.com/PrismJS/prism/issues/2719)) [`2b355c98`](https://github.com/PrismJS/prism/commit/2b355c98)
* __Markup__
    * Added support for DOM event attributes ([#2702](https://github.com/PrismJS/prism/issues/2702)) [`8dbbbb35`](https://github.com/PrismJS/prism/commit/8dbbbb35)
* __nginx__
    * Complete rewrite ([#2793](https://github.com/PrismJS/prism/issues/2793)) [`5943f4cb`](https://github.com/PrismJS/prism/commit/5943f4cb)
* __PHP__
    * Fixed functions with namespaces ([#2889](https://github.com/PrismJS/prism/issues/2889)) [`87d79390`](https://github.com/PrismJS/prism/commit/87d79390)
    * Fixed string interpolation ([#2864](https://github.com/PrismJS/prism/issues/2864)) [`cf3755cb`](https://github.com/PrismJS/prism/commit/cf3755cb)
    * Added missing PHP 7.4 `fn` keyword ([#2858](https://github.com/PrismJS/prism/issues/2858)) [`e0ee93f1`](https://github.com/PrismJS/prism/commit/e0ee93f1)
    * Fixed methods with keyword names + minor improvements ([#2818](https://github.com/PrismJS/prism/issues/2818)) [`7e8cd40d`](https://github.com/PrismJS/prism/commit/7e8cd40d)
    * Improved constant support for PHP 8.1 enums ([#2770](https://github.com/PrismJS/prism/issues/2770)) [`8019e2f6`](https://github.com/PrismJS/prism/commit/8019e2f6)
    * Added support for PHP 8.1 enums ([#2752](https://github.com/PrismJS/prism/issues/2752)) [`f79b0eef`](https://github.com/PrismJS/prism/commit/f79b0eef)
    * Class names at the start of a string are now highlighted correctly ([#2731](https://github.com/PrismJS/prism/issues/2731)) [`04ef309c`](https://github.com/PrismJS/prism/commit/04ef309c)
    * Numeral syntax improvements ([#2701](https://github.com/PrismJS/prism/issues/2701)) [`01af04ed`](https://github.com/PrismJS/prism/commit/01af04ed)
* __React JSX__
    * Added support for general spread expressions ([#2754](https://github.com/PrismJS/prism/issues/2754)) [`9f59f52d`](https://github.com/PrismJS/prism/commit/9f59f52d)
    * Added support for comments inside tags ([#2728](https://github.com/PrismJS/prism/issues/2728)) [`30b0444f`](https://github.com/PrismJS/prism/commit/30b0444f)
* __reST (reStructuredText)__
    * Fixed `inline` pattern ([#2946](https://github.com/PrismJS/prism/issues/2946)) [`a7656de6`](https://github.com/PrismJS/prism/commit/a7656de6)
* __Ruby__
    * Added heredoc literals ([#2885](https://github.com/PrismJS/prism/issues/2885)) [`20b77bff`](https://github.com/PrismJS/prism/commit/20b77bff)
    * Added missing regex flags ([#2845](https://github.com/PrismJS/prism/issues/2845)) [`3786f396`](https://github.com/PrismJS/prism/commit/3786f396)
    * Added missing regex interpolation ([#2841](https://github.com/PrismJS/prism/issues/2841)) [`f08c2f7f`](https://github.com/PrismJS/prism/commit/f08c2f7f)
* __Scheme__
    * Added support for high Unicode characters ([#2693](https://github.com/PrismJS/prism/issues/2693)) [`0e61a7e1`](https://github.com/PrismJS/prism/commit/0e61a7e1)
    * Added bracket support ([#2813](https://github.com/PrismJS/prism/issues/2813)) [`1c6c0bf3`](https://github.com/PrismJS/prism/commit/1c6c0bf3)
* __Shell session__
    * Fixed multi-line commands ([#2872](https://github.com/PrismJS/prism/issues/2872)) [`cda976b1`](https://github.com/PrismJS/prism/commit/cda976b1)
    * Commands prefixed with a path are now detected ([#2686](https://github.com/PrismJS/prism/issues/2686)) [`c83fd0b8`](https://github.com/PrismJS/prism/commit/c83fd0b8)
* __SQL__
    * Added `ILIKE` operator ([#2704](https://github.com/PrismJS/prism/issues/2704)) [`6e34771f`](https://github.com/PrismJS/prism/commit/6e34771f)
* __Swift__
    * Added `some` keyword ([#2756](https://github.com/PrismJS/prism/issues/2756)) [`cf354ef5`](https://github.com/PrismJS/prism/commit/cf354ef5)
* __TypeScript__
    * Updated keywords ([#2861](https://github.com/PrismJS/prism/issues/2861)) [`fe98d536`](https://github.com/PrismJS/prism/commit/fe98d536)
    * Added support for decorators ([#2820](https://github.com/PrismJS/prism/issues/2820)) [`31cc2142`](https://github.com/PrismJS/prism/commit/31cc2142)
* __VB.Net__
    * Improved strings, comments, and punctuation ([#2782](https://github.com/PrismJS/prism/issues/2782)) [`a68f1fb6`](https://github.com/PrismJS/prism/commit/a68f1fb6)
* __Xojo (REALbasic)__
    * `REM` is no longer highlighted as a keyword in comments ([#2823](https://github.com/PrismJS/prism/issues/2823)) [`ebbbfd47`](https://github.com/PrismJS/prism/commit/ebbbfd47)
    * Added last missing Keyword "Selector" ([#2807](https://github.com/PrismJS/prism/issues/2807)) [`e32e043b`](https://github.com/PrismJS/prism/commit/e32e043b)
    * Added missing keywords ([#2805](https://github.com/PrismJS/prism/issues/2805)) [`459365ec`](https://github.com/PrismJS/prism/commit/459365ec)

### Updated plugins

* Made Match Braces and Custom Class compatible ([#2947](https://github.com/PrismJS/prism/issues/2947)) [`4b55bd6a`](https://github.com/PrismJS/prism/commit/4b55bd6a)
* Consistent Prism check ([#2788](https://github.com/PrismJS/prism/issues/2788)) [`96335642`](https://github.com/PrismJS/prism/commit/96335642)
* __Command Line__
    * Don't modify empty code blocks ([#2896](https://github.com/PrismJS/prism/issues/2896)) [`c81c3319`](https://github.com/PrismJS/prism/commit/c81c3319)
* __Copy to Clipboard__
    * Removed ClipboardJS dependency ([#2784](https://github.com/PrismJS/prism/issues/2784)) [`d5e14e1a`](https://github.com/PrismJS/prism/commit/d5e14e1a)
    * Fixed `clipboard.writeText` not working inside iFrames ([#2826](https://github.com/PrismJS/prism/issues/2826)) [`01b7b6f7`](https://github.com/PrismJS/prism/commit/01b7b6f7)
    * Added support for custom styles ([#2789](https://github.com/PrismJS/prism/issues/2789)) [`4d7f75b0`](https://github.com/PrismJS/prism/commit/4d7f75b0)
    * Make copy-to-clipboard configurable with multiple attributes ([#2723](https://github.com/PrismJS/prism/issues/2723)) [`2cb909e1`](https://github.com/PrismJS/prism/commit/2cb909e1)
* __File Highlight__
    * Fixed Prism check ([#2827](https://github.com/PrismJS/prism/issues/2827)) [`53d34b22`](https://github.com/PrismJS/prism/commit/53d34b22)
* __Line Highlight__
    * Fixed linkable line numbers not being initialized ([#2732](https://github.com/PrismJS/prism/issues/2732)) [`ccc73ab7`](https://github.com/PrismJS/prism/commit/ccc73ab7)
* __Previewers__
    * Use `classList` instead of `className` ([#2787](https://github.com/PrismJS/prism/issues/2787)) [`d298d46e`](https://github.com/PrismJS/prism/commit/d298d46e)

### Other

* __Core__
    * Add `tabindex` to code blocks to enable keyboard navigation ([#2799](https://github.com/PrismJS/prism/issues/2799)) [`dbf70515`](https://github.com/PrismJS/prism/commit/dbf70515)
    * Fixed greedy rematching reach bug ([#2705](https://github.com/PrismJS/prism/issues/2705)) [`b37987d3`](https://github.com/PrismJS/prism/commit/b37987d3)
    * Added support for plaintext ([#2738](https://github.com/PrismJS/prism/issues/2738)) [`970674cf`](https://github.com/PrismJS/prism/commit/970674cf)
* __Infrastructure__
    * Added ESLint
    * Added `npm-run-all` to clean up test command ([#2938](https://github.com/PrismJS/prism/issues/2938)) [`5d3d8088`](https://github.com/PrismJS/prism/commit/5d3d8088)
    * Added link to Q&A to issue templates ([#2834](https://github.com/PrismJS/prism/issues/2834)) [`7cd9e794`](https://github.com/PrismJS/prism/commit/7cd9e794)
    * CI: Run tests with NodeJS 16.x ([#2888](https://github.com/PrismJS/prism/issues/2888)) [`b77317c5`](https://github.com/PrismJS/prism/commit/b77317c5)
    * Dangerfile: Trim merge base ([#2761](https://github.com/PrismJS/prism/issues/2761)) [`45b0e82a`](https://github.com/PrismJS/prism/commit/45b0e82a)
    * Dangerfile: Fixed how changed files are determined ([#2757](https://github.com/PrismJS/prism/issues/2757)) [`0feb266f`](https://github.com/PrismJS/prism/commit/0feb266f)
    * Deps: Updated regex tooling ([#2923](https://github.com/PrismJS/prism/issues/2923)) [`ad9878ad`](https://github.com/PrismJS/prism/commit/ad9878ad)
    * Tests: Added `--language` for patterns tests ([#2929](https://github.com/PrismJS/prism/issues/2929)) [`a62ef796`](https://github.com/PrismJS/prism/commit/a62ef796)
    * Tests: Fixed polynomial backtracking test ([#2891](https://github.com/PrismJS/prism/issues/2891)) [`8dbf1217`](https://github.com/PrismJS/prism/commit/8dbf1217)
    * Tests: Fixed languages test discovery [`a9a199b6`](https://github.com/PrismJS/prism/commit/a9a199b6)
    * Tests: Test discovery should ignore unsupported file extensions ([#2886](https://github.com/PrismJS/prism/issues/2886)) [`4492c5ce`](https://github.com/PrismJS/prism/commit/4492c5ce)
    * Tests: Exhaustive pattern tests ([#2688](https://github.com/PrismJS/prism/issues/2688)) [`53151404`](https://github.com/PrismJS/prism/commit/53151404)
    * Tests: Fixed pretty print incorrectly calculating print width ([#2821](https://github.com/PrismJS/prism/issues/2821)) [`5bc405e7`](https://github.com/PrismJS/prism/commit/5bc405e7)
    * Tests: Automatically normalize line ends ([#2934](https://github.com/PrismJS/prism/issues/2934)) [`99f3ddcd`](https://github.com/PrismJS/prism/commit/99f3ddcd)
    * Tests: Added `--insert` and `--update` parameters to language test ([#2809](https://github.com/PrismJS/prism/issues/2809)) [`4c8b855d`](https://github.com/PrismJS/prism/commit/4c8b855d)
    * Tests: Stricter `components.json` tests ([#2758](https://github.com/PrismJS/prism/issues/2758)) [`933af805`](https://github.com/PrismJS/prism/commit/933af805)
* __Website__
    * Copy to clipboard: Fixed highlighting ([#2725](https://github.com/PrismJS/prism/issues/2725)) [`7a790bf9`](https://github.com/PrismJS/prism/commit/7a790bf9)
    * Readme: Mention `npm ci` ([#2899](https://github.com/PrismJS/prism/issues/2899)) [`91f3aaed`](https://github.com/PrismJS/prism/commit/91f3aaed)
    * Readme: Added Node and npm version requirements ([#2790](https://github.com/PrismJS/prism/issues/2790)) [`cb220168`](https://github.com/PrismJS/prism/commit/cb220168)
    * Readme: Update link to Chinese translation ([#2749](https://github.com/PrismJS/prism/issues/2749)) [`266cc700`](https://github.com/PrismJS/prism/commit/266cc700)
    * Replace `my.cdn` in code sample with Handlebars-like placeholder ([#2906](https://github.com/PrismJS/prism/issues/2906)) [`80471181`](https://github.com/PrismJS/prism/commit/80471181)
    * Set dummy domain for CDN ([#2905](https://github.com/PrismJS/prism/issues/2905)) [`38f1d289`](https://github.com/PrismJS/prism/commit/38f1d289)
    * Added MySQL to "Used by" section ([#2785](https://github.com/PrismJS/prism/issues/2785)) [`9b784ebf`](https://github.com/PrismJS/prism/commit/9b784ebf)
    * Improved basic usage section ([#2777](https://github.com/PrismJS/prism/issues/2777)) [`a1209930`](https://github.com/PrismJS/prism/commit/a1209930)
    * Updated URL in Autolinker example ([#2751](https://github.com/PrismJS/prism/issues/2751)) [`ec9767d6`](https://github.com/PrismJS/prism/commit/ec9767d6)
    * Added React native tutorial ([#2683](https://github.com/PrismJS/prism/issues/2683)) [`1506f345`](https://github.com/PrismJS/prism/commit/1506f345)


## 1.23.0 (2020-12-31)

### New components

* __Apex__ ([#2622](https://github.com/PrismJS/prism/issues/2622)) [`f0e2b70e`](https://github.com/PrismJS/prism/commit/f0e2b70e)
* __DataWeave__ ([#2659](https://github.com/PrismJS/prism/issues/2659)) [`0803525b`](https://github.com/PrismJS/prism/commit/0803525b)
* __PromQL__ ([#2628](https://github.com/PrismJS/prism/issues/2628)) [`8831c706`](https://github.com/PrismJS/prism/commit/8831c706)

### Updated components

* Fixed multiple vulnerable regexes ([#2584](https://github.com/PrismJS/prism/issues/2584)) [`c2f6a644`](https://github.com/PrismJS/prism/commit/c2f6a644)
* __Apache Configuration__
    * Update directive-flag to match `=` ([#2612](https://github.com/PrismJS/prism/issues/2612)) [`00bf00e3`](https://github.com/PrismJS/prism/commit/00bf00e3)
* __C-like__
    * Made all comments greedy ([#2680](https://github.com/PrismJS/prism/issues/2680)) [`0a3932fe`](https://github.com/PrismJS/prism/commit/0a3932fe)
* __C__
    * Better class name and macro name detection ([#2585](https://github.com/PrismJS/prism/issues/2585)) [`129faf5c`](https://github.com/PrismJS/prism/commit/129faf5c)
* __Content-Security-Policy__
    * Added missing directives and keywords ([#2664](https://github.com/PrismJS/prism/issues/2664)) [`f1541342`](https://github.com/PrismJS/prism/commit/f1541342)
    * Do not highlight directive names with adjacent hyphens ([#2662](https://github.com/PrismJS/prism/issues/2662)) [`a7ccc16d`](https://github.com/PrismJS/prism/commit/a7ccc16d)
* __CSS__
    * Better HTML `style` attribute tokenization ([#2569](https://github.com/PrismJS/prism/issues/2569)) [`b04cbafe`](https://github.com/PrismJS/prism/commit/b04cbafe)
* __Java__
    * Improved package and class name detection ([#2599](https://github.com/PrismJS/prism/issues/2599)) [`0889bc7c`](https://github.com/PrismJS/prism/commit/0889bc7c)
    * Added Java 15 keywords ([#2567](https://github.com/PrismJS/prism/issues/2567)) [`73f81c89`](https://github.com/PrismJS/prism/commit/73f81c89)
* __Java stack trace__
    * Added support stack frame element class loaders and modules ([#2658](https://github.com/PrismJS/prism/issues/2658)) [`0bb4f096`](https://github.com/PrismJS/prism/commit/0bb4f096)
* __Julia__
    * Removed constants that are not exported by default ([#2601](https://github.com/PrismJS/prism/issues/2601)) [`093c8175`](https://github.com/PrismJS/prism/commit/093c8175)
* __Kotlin__
    * Added support for backticks in function names ([#2489](https://github.com/PrismJS/prism/issues/2489)) [`a5107d5c`](https://github.com/PrismJS/prism/commit/a5107d5c)
* __Latte__
    * Fixed exponential backtracking ([#2682](https://github.com/PrismJS/prism/issues/2682)) [`89f1e182`](https://github.com/PrismJS/prism/commit/89f1e182)
* __Markdown__
    * Improved URL tokenization ([#2678](https://github.com/PrismJS/prism/issues/2678)) [`2af3e2c2`](https://github.com/PrismJS/prism/commit/2af3e2c2)
    * Added support for YAML front matter ([#2634](https://github.com/PrismJS/prism/issues/2634)) [`5cf9cfbc`](https://github.com/PrismJS/prism/commit/5cf9cfbc)
* __PHP__
    * Added support for PHP 7.4 + other major improvements ([#2566](https://github.com/PrismJS/prism/issues/2566)) [`38808e64`](https://github.com/PrismJS/prism/commit/38808e64)
    * Added support for PHP 8.0 features ([#2591](https://github.com/PrismJS/prism/issues/2591)) [`df922d90`](https://github.com/PrismJS/prism/commit/df922d90)
    * Removed C-like dependency ([#2619](https://github.com/PrismJS/prism/issues/2619)) [`89ebb0b7`](https://github.com/PrismJS/prism/commit/89ebb0b7)
    * Fixed exponential backtracking ([#2684](https://github.com/PrismJS/prism/issues/2684)) [`37b9c9a1`](https://github.com/PrismJS/prism/commit/37b9c9a1)
* __Sass (Scss)__
    * Added support for Sass modules ([#2643](https://github.com/PrismJS/prism/issues/2643)) [`deb238a6`](https://github.com/PrismJS/prism/commit/deb238a6)
* __Scheme__
    * Fixed number pattern ([#2648](https://github.com/PrismJS/prism/issues/2648)) [`e01ecd00`](https://github.com/PrismJS/prism/commit/e01ecd00)
    * Fixed function and function-like false positives ([#2611](https://github.com/PrismJS/prism/issues/2611)) [`7951ca24`](https://github.com/PrismJS/prism/commit/7951ca24)
* __Shell session__
    * Fixed false positives because of links in command output ([#2649](https://github.com/PrismJS/prism/issues/2649)) [`8e76a978`](https://github.com/PrismJS/prism/commit/8e76a978)
* __TSX__
    * Temporary fix for the collisions of JSX tags and TS generics ([#2596](https://github.com/PrismJS/prism/issues/2596)) [`25bdb494`](https://github.com/PrismJS/prism/commit/25bdb494)

### Updated plugins

* Made Autoloader and Diff Highlight compatible ([#2580](https://github.com/PrismJS/prism/issues/2580)) [`7a74497a`](https://github.com/PrismJS/prism/commit/7a74497a)
* __Copy to Clipboard Button__
    * Set `type="button"` attribute for copy to clipboard plugin ([#2593](https://github.com/PrismJS/prism/issues/2593)) [`f59a85f1`](https://github.com/PrismJS/prism/commit/f59a85f1)
* __File Highlight__
    * Fixed IE compatibility problem ([#2656](https://github.com/PrismJS/prism/issues/2656)) [`3f4ae00d`](https://github.com/PrismJS/prism/commit/3f4ae00d)
* __Line Highlight__
    * Fixed top offset in combination with Line numbers ([#2237](https://github.com/PrismJS/prism/issues/2237)) [`b40f8f4b`](https://github.com/PrismJS/prism/commit/b40f8f4b)
    * Fixed print background color ([#2668](https://github.com/PrismJS/prism/issues/2668)) [`cdb24abe`](https://github.com/PrismJS/prism/commit/cdb24abe)
* __Line Numbers__
    * Fixed null reference ([#2605](https://github.com/PrismJS/prism/issues/2605)) [`7cdfe556`](https://github.com/PrismJS/prism/commit/7cdfe556)
* __Treeview__
    * Fixed icons on dark themes ([#2631](https://github.com/PrismJS/prism/issues/2631)) [`7266e32f`](https://github.com/PrismJS/prism/commit/7266e32f)
* __Unescaped Markup__
    * Refactoring ([#2445](https://github.com/PrismJS/prism/issues/2445)) [`fc602822`](https://github.com/PrismJS/prism/commit/fc602822)

### Other

* Readme: Added alternative link for Chinese translation [`071232b4`](https://github.com/PrismJS/prism/commit/071232b4)
* Readme: Removed broken icon for Chinese translation ([#2670](https://github.com/PrismJS/prism/issues/2670)) [`2ea202b9`](https://github.com/PrismJS/prism/commit/2ea202b9)
* Readme: Grammar adjustments ([#2629](https://github.com/PrismJS/prism/issues/2629)) [`f217ab75`](https://github.com/PrismJS/prism/commit/f217ab75)
* __Core__
    * Moved pattern matching + lookbehind logic into function ([#2633](https://github.com/PrismJS/prism/issues/2633)) [`24574406`](https://github.com/PrismJS/prism/commit/24574406)
    * Fixed bug with greedy matching ([#2632](https://github.com/PrismJS/prism/issues/2632)) [`8fa8dd24`](https://github.com/PrismJS/prism/commit/8fa8dd24)
* __Infrastructure__
    * Migrate from TravisCI -> GitHub Actions ([#2606](https://github.com/PrismJS/prism/issues/2606)) [`69132045`](https://github.com/PrismJS/prism/commit/69132045)
    * Added Dangerfile and provide bundle size info ([#2608](https://github.com/PrismJS/prism/issues/2608)) [`9df20c5e`](https://github.com/PrismJS/prism/commit/9df20c5e)
    * New `start` script to start local server ([#2491](https://github.com/PrismJS/prism/issues/2491)) [`0604793c`](https://github.com/PrismJS/prism/commit/0604793c)
    * Added test for exponential backtracking ([#2590](https://github.com/PrismJS/prism/issues/2590)) [`05afbb10`](https://github.com/PrismJS/prism/commit/05afbb10)
    * Added test for polynomial backtracking ([#2597](https://github.com/PrismJS/prism/issues/2597)) [`e644178b`](https://github.com/PrismJS/prism/commit/e644178b)
    * Tests: Better pretty print ([#2600](https://github.com/PrismJS/prism/issues/2600)) [`8bfcc819`](https://github.com/PrismJS/prism/commit/8bfcc819)
    * Tests: Fixed sorted language list test ([#2623](https://github.com/PrismJS/prism/issues/2623)) [`2d3a1267`](https://github.com/PrismJS/prism/commit/2d3a1267)
    * Tests: Stricter pattern for nice-token-names test ([#2588](https://github.com/PrismJS/prism/issues/2588)) [`0df60be1`](https://github.com/PrismJS/prism/commit/0df60be1)
    * Tests: Added strict checks for `Prism.languages.extend` ([#2572](https://github.com/PrismJS/prism/issues/2572)) [`8828500e`](https://github.com/PrismJS/prism/commit/8828500e)
* __Website__
    * Test page: Added "Share" option ([#2575](https://github.com/PrismJS/prism/issues/2575)) [`b5f4f10e`](https://github.com/PrismJS/prism/commit/b5f4f10e)
    * Test page: Don't trigger ad-blockers with class ([#2677](https://github.com/PrismJS/prism/issues/2677)) [`df0738e9`](https://github.com/PrismJS/prism/commit/df0738e9)
    * Thousands -> millions [`9f82de50`](https://github.com/PrismJS/prism/commit/9f82de50)
    * Unescaped Markup: More doc regarding comments ([#2652](https://github.com/PrismJS/prism/issues/2652)) [`add3736a`](https://github.com/PrismJS/prism/commit/add3736a)
    * Website: Added and updated documentation ([#2654](https://github.com/PrismJS/prism/issues/2654)) [`8e660495`](https://github.com/PrismJS/prism/commit/8e660495)
    * Website: Updated and improved guide on "Extending Prism" page ([#2586](https://github.com/PrismJS/prism/issues/2586)) [`8e1f38ff`](https://github.com/PrismJS/prism/commit/8e1f38ff)

## 1.22.0 (2020-10-10)

### New components

* __Birb__ ([#2542](https://github.com/PrismJS/prism/issues/2542)) [`4d31e22a`](https://github.com/PrismJS/prism/commit/4d31e22a)
* __BSL (1C:Enterprise)__ & __OneScript__ ([#2520](https://github.com/PrismJS/prism/issues/2520)) [`5c33f0bb`](https://github.com/PrismJS/prism/commit/5c33f0bb)
* __MongoDB__ ([#2518](https://github.com/PrismJS/prism/issues/2518)) [`004eaa74`](https://github.com/PrismJS/prism/commit/004eaa74)
* __Naninovel Script__ ([#2494](https://github.com/PrismJS/prism/issues/2494)) [`388ad996`](https://github.com/PrismJS/prism/commit/388ad996)
* __PureScript__ ([#2526](https://github.com/PrismJS/prism/issues/2526)) [`ad748a00`](https://github.com/PrismJS/prism/commit/ad748a00)
* __SML__ & __SML/NJ__ ([#2537](https://github.com/PrismJS/prism/issues/2537)) [`cb75d9e2`](https://github.com/PrismJS/prism/commit/cb75d9e2)
* __Stan__ ([#2490](https://github.com/PrismJS/prism/issues/2490)) [`2da2beba`](https://github.com/PrismJS/prism/commit/2da2beba)
* __TypoScript__ & __TSConfig__ ([#2505](https://github.com/PrismJS/prism/issues/2505)) [`bf115f47`](https://github.com/PrismJS/prism/commit/bf115f47)

### Updated components

* Removed duplicate alternatives in various languages ([#2524](https://github.com/PrismJS/prism/issues/2524)) [`fa2225ff`](https://github.com/PrismJS/prism/commit/fa2225ff)
* __Haskell__
    * Improvements ([#2535](https://github.com/PrismJS/prism/issues/2535)) [`e023044c`](https://github.com/PrismJS/prism/commit/e023044c)
* __JS Extras__
    * Highlight import and export bindings ([#2533](https://github.com/PrismJS/prism/issues/2533)) [`c51ababb`](https://github.com/PrismJS/prism/commit/c51ababb)
    * Added control-flow keywords ([#2529](https://github.com/PrismJS/prism/issues/2529)) [`bcef22af`](https://github.com/PrismJS/prism/commit/bcef22af)
* __PHP__
    * Added `match` keyword (PHP 8.0) ([#2574](https://github.com/PrismJS/prism/issues/2574)) [`1761513e`](https://github.com/PrismJS/prism/commit/1761513e)
* __Processing__
    * Fixed function pattern ([#2564](https://github.com/PrismJS/prism/issues/2564)) [`35cbc02f`](https://github.com/PrismJS/prism/commit/35cbc02f)
* __Regex__
    * Changed how languages embed regexes ([#2532](https://github.com/PrismJS/prism/issues/2532)) [`f62ca787`](https://github.com/PrismJS/prism/commit/f62ca787)
* __Rust__
    * Fixed Unicode char literals ([#2550](https://github.com/PrismJS/prism/issues/2550)) [`3b4f14ca`](https://github.com/PrismJS/prism/commit/3b4f14ca)
* __Scheme__
    * Added support for R7RS syntax ([#2525](https://github.com/PrismJS/prism/issues/2525)) [`e4f6ccac`](https://github.com/PrismJS/prism/commit/e4f6ccac)
* __Shell session__
    * Added aliases ([#2548](https://github.com/PrismJS/prism/issues/2548)) [`bfb36748`](https://github.com/PrismJS/prism/commit/bfb36748)
    * Highlight all commands after the start of any Heredoc string ([#2509](https://github.com/PrismJS/prism/issues/2509)) [`6c921801`](https://github.com/PrismJS/prism/commit/6c921801)
* __YAML__
    * Improved key pattern ([#2561](https://github.com/PrismJS/prism/issues/2561)) [`59853a52`](https://github.com/PrismJS/prism/commit/59853a52)

### Updated plugins

* __Autoloader__
    * Fixed file detection regexes ([#2549](https://github.com/PrismJS/prism/issues/2549)) [`d36ea993`](https://github.com/PrismJS/prism/commit/d36ea993)
* __Match braces__
    * Fixed JS interpolation punctuation ([#2541](https://github.com/PrismJS/prism/issues/2541)) [`6b47133d`](https://github.com/PrismJS/prism/commit/6b47133d)
* __Show Language__
    * Added title for plain text ([#2555](https://github.com/PrismJS/prism/issues/2555)) [`a409245e`](https://github.com/PrismJS/prism/commit/a409245e)

### Other

* Tests: Added an option to accept the actual token stream ([#2515](https://github.com/PrismJS/prism/issues/2515)) [`bafab634`](https://github.com/PrismJS/prism/commit/bafab634)
* __Core__
    * Docs: Minor improvement ([#2513](https://github.com/PrismJS/prism/issues/2513)) [`206dc80f`](https://github.com/PrismJS/prism/commit/206dc80f)
* __Infrastructure__
    * JSDoc: Fixed line ends ([#2523](https://github.com/PrismJS/prism/issues/2523)) [`bf169e5f`](https://github.com/PrismJS/prism/commit/bf169e5f)
* __Website__
    * Website: Added new SB101 tutorial replacing the Crambler one ([#2576](https://github.com/PrismJS/prism/issues/2576)) [`655f985c`](https://github.com/PrismJS/prism/commit/655f985c)
    * Website: Fix typo on homepage by adding missing word add ([#2570](https://github.com/PrismJS/prism/issues/2570)) [`8ae6a4ba`](https://github.com/PrismJS/prism/commit/8ae6a4ba)
    * Custom class: Improved doc ([#2512](https://github.com/PrismJS/prism/issues/2512)) [`5ad6cb23`](https://github.com/PrismJS/prism/commit/5ad6cb23)

## 1.21.0 (2020-08-06)

### New components

* __.ignore__ & __.gitignore__ & __.hgignore__ & __.npmignore__ ([#2481](https://github.com/PrismJS/prism/issues/2481)) [`3fcce6fe`](https://github.com/PrismJS/prism/commit/3fcce6fe)
* __Agda__ ([#2430](https://github.com/PrismJS/prism/issues/2430)) [`3a127c7d`](https://github.com/PrismJS/prism/commit/3a127c7d)
* __AL__ ([#2300](https://github.com/PrismJS/prism/issues/2300)) [`de21eb64`](https://github.com/PrismJS/prism/commit/de21eb64)
* __Cypher__ ([#2459](https://github.com/PrismJS/prism/issues/2459)) [`398e2943`](https://github.com/PrismJS/prism/commit/398e2943)
* __Dhall__ ([#2473](https://github.com/PrismJS/prism/issues/2473)) [`649e51e5`](https://github.com/PrismJS/prism/commit/649e51e5)
* __EditorConfig__ ([#2471](https://github.com/PrismJS/prism/issues/2471)) [`ed8fff91`](https://github.com/PrismJS/prism/commit/ed8fff91)
* __HLSL__ ([#2318](https://github.com/PrismJS/prism/issues/2318)) [`87a5c7ae`](https://github.com/PrismJS/prism/commit/87a5c7ae)
* __JS stack trace__ ([#2418](https://github.com/PrismJS/prism/issues/2418)) [`ae0327b3`](https://github.com/PrismJS/prism/commit/ae0327b3)
* __PeopleCode__ ([#2302](https://github.com/PrismJS/prism/issues/2302)) [`bd4d8165`](https://github.com/PrismJS/prism/commit/bd4d8165)
* __PureBasic__ ([#2369](https://github.com/PrismJS/prism/issues/2369)) [`d0c1c70d`](https://github.com/PrismJS/prism/commit/d0c1c70d)
* __Racket__ ([#2315](https://github.com/PrismJS/prism/issues/2315)) [`053016ef`](https://github.com/PrismJS/prism/commit/053016ef)
* __Smali__ ([#2419](https://github.com/PrismJS/prism/issues/2419)) [`22eb5cad`](https://github.com/PrismJS/prism/commit/22eb5cad)
* __Structured Text (IEC 61131-3)__ ([#2311](https://github.com/PrismJS/prism/issues/2311)) [`8704cdfb`](https://github.com/PrismJS/prism/commit/8704cdfb)
* __UnrealScript__ ([#2305](https://github.com/PrismJS/prism/issues/2305)) [`1093ceb3`](https://github.com/PrismJS/prism/commit/1093ceb3)
* __WarpScript__ ([#2307](https://github.com/PrismJS/prism/issues/2307)) [`cde5b0fa`](https://github.com/PrismJS/prism/commit/cde5b0fa)
* __XML doc (.net)__ ([#2340](https://github.com/PrismJS/prism/issues/2340)) [`caec5e30`](https://github.com/PrismJS/prism/commit/caec5e30)
* __YANG__ ([#2467](https://github.com/PrismJS/prism/issues/2467)) [`ed1df1e1`](https://github.com/PrismJS/prism/commit/ed1df1e1)

### Updated components

* Markup & JSON: Added new aliases ([#2390](https://github.com/PrismJS/prism/issues/2390)) [`9782cfe6`](https://github.com/PrismJS/prism/commit/9782cfe6)
* Fixed several cases of exponential backtracking ([#2268](https://github.com/PrismJS/prism/issues/2268)) [`7a554b5f`](https://github.com/PrismJS/prism/commit/7a554b5f)
* __APL__
    * Added `⍥` ([#2409](https://github.com/PrismJS/prism/issues/2409)) [`0255cb6a`](https://github.com/PrismJS/prism/commit/0255cb6a)
* __AutoHotkey__
    * Added missing `format` built-in ([#2450](https://github.com/PrismJS/prism/issues/2450)) [`7c66cfc4`](https://github.com/PrismJS/prism/commit/7c66cfc4)
    * Improved comments and other improvements ([#2412](https://github.com/PrismJS/prism/issues/2412)) [`ddf3cc62`](https://github.com/PrismJS/prism/commit/ddf3cc62)
    * Added missing definitions ([#2400](https://github.com/PrismJS/prism/issues/2400)) [`4fe03676`](https://github.com/PrismJS/prism/commit/4fe03676)
* __Bash__
    * Added `composer` command ([#2298](https://github.com/PrismJS/prism/issues/2298)) [`044dd271`](https://github.com/PrismJS/prism/commit/044dd271)
* __Batch__
    * Fix escaped double quote ([#2485](https://github.com/PrismJS/prism/issues/2485)) [`f0f8210c`](https://github.com/PrismJS/prism/commit/f0f8210c)
* __C__
    * Improved macros and expressions ([#2440](https://github.com/PrismJS/prism/issues/2440)) [`8a72fa6f`](https://github.com/PrismJS/prism/commit/8a72fa6f)
    * Improved macros ([#2320](https://github.com/PrismJS/prism/issues/2320)) [`fdcf7ed2`](https://github.com/PrismJS/prism/commit/fdcf7ed2)
* __C#__
    * Improved pattern matching ([#2411](https://github.com/PrismJS/prism/issues/2411)) [`7f341fc1`](https://github.com/PrismJS/prism/commit/7f341fc1)
    * Fixed adjacent string interpolations ([#2402](https://github.com/PrismJS/prism/issues/2402)) [`2a2e79ed`](https://github.com/PrismJS/prism/commit/2a2e79ed)
* __C++__
    * Added support for default comparison operator ([#2426](https://github.com/PrismJS/prism/issues/2426)) [`8e9d161c`](https://github.com/PrismJS/prism/commit/8e9d161c)
    * Improved class name detection ([#2348](https://github.com/PrismJS/prism/issues/2348)) [`e3fe9040`](https://github.com/PrismJS/prism/commit/e3fe9040)
    * Fixed `enum class` class names ([#2342](https://github.com/PrismJS/prism/issues/2342)) [`30b4e254`](https://github.com/PrismJS/prism/commit/30b4e254)
* __Content-Security-Policy__
    * Fixed directives ([#2461](https://github.com/PrismJS/prism/issues/2461)) [`537a9e80`](https://github.com/PrismJS/prism/commit/537a9e80)
* __CSS__
    * Improved url and added keywords ([#2432](https://github.com/PrismJS/prism/issues/2432)) [`964de5a1`](https://github.com/PrismJS/prism/commit/964de5a1)
* __CSS Extras__
    * Optimized `class` and `id` patterns ([#2359](https://github.com/PrismJS/prism/issues/2359)) [`fdbc4473`](https://github.com/PrismJS/prism/commit/fdbc4473)
    * Renamed `attr-{name,value}` tokens and added tokens for combinators and selector lists ([#2373](https://github.com/PrismJS/prism/issues/2373)) [`e523f5d0`](https://github.com/PrismJS/prism/commit/e523f5d0)
* __Dart__
    * Added missing keywords ([#2355](https://github.com/PrismJS/prism/issues/2355)) [`4172ab6f`](https://github.com/PrismJS/prism/commit/4172ab6f)
* __Diff__
    * Added `prefix` token ([#2281](https://github.com/PrismJS/prism/issues/2281)) [`fd432a5b`](https://github.com/PrismJS/prism/commit/fd432a5b)
* __Docker__
    * Fixed strings inside comments ([#2428](https://github.com/PrismJS/prism/issues/2428)) [`37273a6f`](https://github.com/PrismJS/prism/commit/37273a6f)
* __EditorConfig__
    * Trim spaces before key and section title ([#2482](https://github.com/PrismJS/prism/issues/2482)) [`0c30c582`](https://github.com/PrismJS/prism/commit/0c30c582)
* __EJS__
    * Added `eta` alias ([#2282](https://github.com/PrismJS/prism/issues/2282)) [`0cfb6c5f`](https://github.com/PrismJS/prism/commit/0cfb6c5f)
* __GLSL__
    * Improvements ([#2321](https://github.com/PrismJS/prism/issues/2321)) [`33e49956`](https://github.com/PrismJS/prism/commit/33e49956)
* __GraphQL__
    * Added missing keywords ([#2407](https://github.com/PrismJS/prism/issues/2407)) [`de8ed16d`](https://github.com/PrismJS/prism/commit/de8ed16d)
    * Added support for multi-line strings and descriptions ([#2406](https://github.com/PrismJS/prism/issues/2406)) [`9e64c62e`](https://github.com/PrismJS/prism/commit/9e64c62e)
* __Io__
    * Fixed operator pattern ([#2365](https://github.com/PrismJS/prism/issues/2365)) [`d6055771`](https://github.com/PrismJS/prism/commit/d6055771)
* __Java__
    * Fixed `namespace` token ([#2295](https://github.com/PrismJS/prism/issues/2295)) [`62e184bb`](https://github.com/PrismJS/prism/commit/62e184bb)
* __JavaDoc__
    * Improvements ([#2324](https://github.com/PrismJS/prism/issues/2324)) [`032910ba`](https://github.com/PrismJS/prism/commit/032910ba)
* __JavaScript__
    * Improved regex detection ([#2465](https://github.com/PrismJS/prism/issues/2465)) [`4f55052f`](https://github.com/PrismJS/prism/commit/4f55052f)
    * Improved `get`/`set` and parameter detection ([#2387](https://github.com/PrismJS/prism/issues/2387)) [`ed715158`](https://github.com/PrismJS/prism/commit/ed715158)
    * Added support for logical assignment operators ([#2378](https://github.com/PrismJS/prism/issues/2378)) [`b28f21b7`](https://github.com/PrismJS/prism/commit/b28f21b7)
* __JSDoc__
    * Improvements ([#2466](https://github.com/PrismJS/prism/issues/2466)) [`2805ae35`](https://github.com/PrismJS/prism/commit/2805ae35)
* __JSON__
    * Greedy comments ([#2479](https://github.com/PrismJS/prism/issues/2479)) [`158caf52`](https://github.com/PrismJS/prism/commit/158caf52)
* __Julia__
    * Improved strings, comments, and other patterns ([#2363](https://github.com/PrismJS/prism/issues/2363)) [`81cf2344`](https://github.com/PrismJS/prism/commit/81cf2344)
* __Kotlin__
    * Added `kt` and `kts` aliases ([#2474](https://github.com/PrismJS/prism/issues/2474)) [`67f97e2e`](https://github.com/PrismJS/prism/commit/67f97e2e)
* __Markup__
    * Added tokens inside DOCTYPE ([#2349](https://github.com/PrismJS/prism/issues/2349)) [`9c7bc820`](https://github.com/PrismJS/prism/commit/9c7bc820)
    * Added `attr-equals` alias for the attribute `=` sign ([#2350](https://github.com/PrismJS/prism/issues/2350)) [`96a0116e`](https://github.com/PrismJS/prism/commit/96a0116e)
    * Added alias for named entities ([#2351](https://github.com/PrismJS/prism/issues/2351)) [`ab1e34ae`](https://github.com/PrismJS/prism/commit/ab1e34ae)
    * Added support for SSML ([#2306](https://github.com/PrismJS/prism/issues/2306)) [`eb70070d`](https://github.com/PrismJS/prism/commit/eb70070d)
* __Objective-C__
    * Added `objc` alias ([#2331](https://github.com/PrismJS/prism/issues/2331)) [`67c6b7af`](https://github.com/PrismJS/prism/commit/67c6b7af)
* __PowerShell__
    * New functions pattern bases on naming conventions ([#2301](https://github.com/PrismJS/prism/issues/2301)) [`fec39bcf`](https://github.com/PrismJS/prism/commit/fec39bcf)
* __Protocol Buffers__
    * Added support for RPC syntax ([#2414](https://github.com/PrismJS/prism/issues/2414)) [`939a17c4`](https://github.com/PrismJS/prism/commit/939a17c4)
* __Pug__
    * Improved class and id detection in tags ([#2358](https://github.com/PrismJS/prism/issues/2358)) [`7f948ecb`](https://github.com/PrismJS/prism/commit/7f948ecb)
* __Python__
    * Fixed empty multiline strings ([#2344](https://github.com/PrismJS/prism/issues/2344)) [`c9324476`](https://github.com/PrismJS/prism/commit/c9324476)
* __Regex__
    * Added aliases and minor improvements ([#2325](https://github.com/PrismJS/prism/issues/2325)) [`8a72830a`](https://github.com/PrismJS/prism/commit/8a72830a)
* __Ren'py__
    * Added `rpy` alias ([#2385](https://github.com/PrismJS/prism/issues/2385)) [`4935b5ca`](https://github.com/PrismJS/prism/commit/4935b5ca)
* __Ruby__
    * Optimized `regex` and `string` patterns ([#2354](https://github.com/PrismJS/prism/issues/2354)) [`b526e8c0`](https://github.com/PrismJS/prism/commit/b526e8c0)
* __Rust__
    * Improvements ([#2464](https://github.com/PrismJS/prism/issues/2464)) [`2ff40fe0`](https://github.com/PrismJS/prism/commit/2ff40fe0)
    * Improvements ([#2332](https://github.com/PrismJS/prism/issues/2332)) [`194c5429`](https://github.com/PrismJS/prism/commit/194c5429)
* __SAS__
    * Improved macro string functions ([#2463](https://github.com/PrismJS/prism/issues/2463)) [`278316ca`](https://github.com/PrismJS/prism/commit/278316ca)
    * Handle edge case of string macro functions ([#2451](https://github.com/PrismJS/prism/issues/2451)) [`a0a9f1ef`](https://github.com/PrismJS/prism/commit/a0a9f1ef)
    * Improved comments in `proc groovy` and `proc lua` ([#2392](https://github.com/PrismJS/prism/issues/2392)) [`475a5903`](https://github.com/PrismJS/prism/commit/475a5903)
* __Scheme__
    * Adjusted lookbehind for literals ([#2396](https://github.com/PrismJS/prism/issues/2396)) [`1e3f542b`](https://github.com/PrismJS/prism/commit/1e3f542b)
    * Improved lambda parameter ([#2346](https://github.com/PrismJS/prism/issues/2346)) [`1946918a`](https://github.com/PrismJS/prism/commit/1946918a)
    * Consistent lookaheads ([#2322](https://github.com/PrismJS/prism/issues/2322)) [`d2541d54`](https://github.com/PrismJS/prism/commit/d2541d54)
    * Improved boolean ([#2316](https://github.com/PrismJS/prism/issues/2316)) [`e27e65af`](https://github.com/PrismJS/prism/commit/e27e65af)
    * Added missing special keywords ([#2304](https://github.com/PrismJS/prism/issues/2304)) [`ac297ba5`](https://github.com/PrismJS/prism/commit/ac297ba5)
    * Improvements ([#2263](https://github.com/PrismJS/prism/issues/2263)) [`9a49f78f`](https://github.com/PrismJS/prism/commit/9a49f78f)
* __Solidity (Ethereum)__
    * Added `sol` alias ([#2382](https://github.com/PrismJS/prism/issues/2382)) [`6352213a`](https://github.com/PrismJS/prism/commit/6352213a)
* __SQL__
    * Added PostgreSQL `RETURNING` keyword ([#2476](https://github.com/PrismJS/prism/issues/2476)) [`bea7a585`](https://github.com/PrismJS/prism/commit/bea7a585)
* __Stylus__
    * Fixed comments breaking declarations + minor improvements ([#2372](https://github.com/PrismJS/prism/issues/2372)) [`6d663b6e`](https://github.com/PrismJS/prism/commit/6d663b6e)
    * New tokens and other improvements ([#2368](https://github.com/PrismJS/prism/issues/2368)) [`2c10ef8a`](https://github.com/PrismJS/prism/commit/2c10ef8a)
    * Fixed comments breaking strings and URLs ([#2361](https://github.com/PrismJS/prism/issues/2361)) [`0d65d6c9`](https://github.com/PrismJS/prism/commit/0d65d6c9)
* __T4 Text Templates (VB)__
    * Use the correct VB variant ([#2341](https://github.com/PrismJS/prism/issues/2341)) [`b6093339`](https://github.com/PrismJS/prism/commit/b6093339)
* __TypeScript__
    * Added `asserts` keyword and other improvements ([#2280](https://github.com/PrismJS/prism/issues/2280)) [`a197cfcd`](https://github.com/PrismJS/prism/commit/a197cfcd)
* __Visual Basic__
    * Added VBA alias ([#2469](https://github.com/PrismJS/prism/issues/2469)) [`78161d60`](https://github.com/PrismJS/prism/commit/78161d60)
    * Added `until` keyword ([#2423](https://github.com/PrismJS/prism/issues/2423)) [`a13ee8d9`](https://github.com/PrismJS/prism/commit/a13ee8d9)
    * Added missing keywords ([#2376](https://github.com/PrismJS/prism/issues/2376)) [`ba5ac1da`](https://github.com/PrismJS/prism/commit/ba5ac1da)

### Updated plugins

* File Highlight & JSONP Highlight update ([#1974](https://github.com/PrismJS/prism/issues/1974)) [`afea17d9`](https://github.com/PrismJS/prism/commit/afea17d9)
* Added general de/activation mechanism for plugins ([#2434](https://github.com/PrismJS/prism/issues/2434)) [`a36e96ab`](https://github.com/PrismJS/prism/commit/a36e96ab)
* __Autoloader__
    * Fixed bug breaking Autoloader ([#2449](https://github.com/PrismJS/prism/issues/2449)) [`a3416bf3`](https://github.com/PrismJS/prism/commit/a3416bf3)
    * Fixed `data-dependencies` and extensions ([#2326](https://github.com/PrismJS/prism/issues/2326)) [`1654b25f`](https://github.com/PrismJS/prism/commit/1654b25f)
    * Improved path detection and other minor improvements ([#2245](https://github.com/PrismJS/prism/issues/2245)) [`5cdc3251`](https://github.com/PrismJS/prism/commit/5cdc3251)
* __Command Line__
    * Some refactoring ([#2290](https://github.com/PrismJS/prism/issues/2290)) [`8c9c2896`](https://github.com/PrismJS/prism/commit/8c9c2896)
    * Correctly rehighlight elements ([#2291](https://github.com/PrismJS/prism/issues/2291)) [`e6b2c6fc`](https://github.com/PrismJS/prism/commit/e6b2c6fc)
* __Line Highlight__
    * Added linkable line numbers ([#2328](https://github.com/PrismJS/prism/issues/2328)) [`eb82e804`](https://github.com/PrismJS/prism/commit/eb82e804)
* __Line Numbers__
    * Improved resize performance ([#2125](https://github.com/PrismJS/prism/issues/2125)) [`b96ed225`](https://github.com/PrismJS/prism/commit/b96ed225)
    * Fixed TypeError when `lineNumberWrapper` is null ([#2337](https://github.com/PrismJS/prism/issues/2337)) [`4b61661d`](https://github.com/PrismJS/prism/commit/4b61661d)
    * Exposed `_resizeElement` function ([#2288](https://github.com/PrismJS/prism/issues/2288)) [`893f2a79`](https://github.com/PrismJS/prism/commit/893f2a79)
* __Previewers__
    * Fixed XSS ([#2506](https://github.com/PrismJS/prism/issues/2506)) [`8bba4880`](https://github.com/PrismJS/prism/commit/8bba4880)
* __Unescaped Markup__
    * No longer requires `Prism.languages.markup` ([#2444](https://github.com/PrismJS/prism/issues/2444)) [`af132dd3`](https://github.com/PrismJS/prism/commit/af132dd3)

### Updated themes

* __Coy__
    * Minor improvements ([#2176](https://github.com/PrismJS/prism/issues/2176)) [`7109c18c`](https://github.com/PrismJS/prism/commit/7109c18c)
* __Default__
    * Added a comment that declares the background color of `operator` tokens as intentional ([#2309](https://github.com/PrismJS/prism/issues/2309)) [`937e2691`](https://github.com/PrismJS/prism/commit/937e2691)
* __Okaidia__
    * Update comment text color to meet WCAG contrast recommendations to AA level ([#2292](https://github.com/PrismJS/prism/issues/2292)) [`06495f90`](https://github.com/PrismJS/prism/commit/06495f90)

### Other

* Changelog: Fixed v1.20.0 release date [`cb6349e2`](https://github.com/PrismJS/prism/commit/cb6349e2)
* __Core__
    * Fixed greedy matching bug ([#2032](https://github.com/PrismJS/prism/issues/2032)) [`40285203`](https://github.com/PrismJS/prism/commit/40285203)
    * Added JSDoc ([#1782](https://github.com/PrismJS/prism/issues/1782)) [`4ff555be`](https://github.com/PrismJS/prism/commit/4ff555be)
* __Infrastructure__
    * Update Git repo URL in package.json ([#2334](https://github.com/PrismJS/prism/issues/2334)) [`10f43275`](https://github.com/PrismJS/prism/commit/10f43275)
    * Added docs to ignore files ([#2437](https://github.com/PrismJS/prism/issues/2437)) [`05c9f20b`](https://github.com/PrismJS/prism/commit/05c9f20b)
    * Added `npm run build` command ([#2356](https://github.com/PrismJS/prism/issues/2356)) [`ff74a610`](https://github.com/PrismJS/prism/commit/ff74a610)
    * gulp: Improved `inlineRegexSource` ([#2296](https://github.com/PrismJS/prism/issues/2296)) [`abb800dd`](https://github.com/PrismJS/prism/commit/abb800dd)
    * gulp: Fixed language map ([#2283](https://github.com/PrismJS/prism/issues/2283)) [`11053193`](https://github.com/PrismJS/prism/commit/11053193)
    * gulp: Removed `premerge` task ([#2357](https://github.com/PrismJS/prism/issues/2357)) [`5ff7932b`](https://github.com/PrismJS/prism/commit/5ff7932b)
    * Tests are now faster ([#2165](https://github.com/PrismJS/prism/issues/2165)) [`e756be3f`](https://github.com/PrismJS/prism/commit/e756be3f)
    * Tests: Added extra newlines in pretty token streams ([#2070](https://github.com/PrismJS/prism/issues/2070)) [`681adeef`](https://github.com/PrismJS/prism/commit/681adeef)
    * Tests: Added test for identifier support across all languages ([#2371](https://github.com/PrismJS/prism/issues/2371)) [`48fac3b2`](https://github.com/PrismJS/prism/commit/48fac3b2)
    * Tests: Added test to sort the language list ([#2222](https://github.com/PrismJS/prism/issues/2222)) [`a3758728`](https://github.com/PrismJS/prism/commit/a3758728)
    * Tests: Always pretty-print token streams ([#2421](https://github.com/PrismJS/prism/issues/2421)) [`583e7eb5`](https://github.com/PrismJS/prism/commit/583e7eb5)
    * Tests: Always use `components.json` ([#2370](https://github.com/PrismJS/prism/issues/2370)) [`e416341f`](https://github.com/PrismJS/prism/commit/e416341f)
    * Tests: Better error messages for pattern tests ([#2364](https://github.com/PrismJS/prism/issues/2364)) [`10ca6433`](https://github.com/PrismJS/prism/commit/10ca6433)
    * Tests: Included `console` in VM context ([#2353](https://github.com/PrismJS/prism/issues/2353)) [`b4ed5ded`](https://github.com/PrismJS/prism/commit/b4ed5ded)
* __Website__
    * Fixed typos "Prims" ([#2455](https://github.com/PrismJS/prism/issues/2455)) [`dfa5498a`](https://github.com/PrismJS/prism/commit/dfa5498a)
    * New assets directory for all web-only files ([#2180](https://github.com/PrismJS/prism/issues/2180)) [`91fdd0b1`](https://github.com/PrismJS/prism/commit/91fdd0b1)
    * Improvements ([#2053](https://github.com/PrismJS/prism/issues/2053)) [`ce0fa227`](https://github.com/PrismJS/prism/commit/ce0fa227)
    * Fixed Treeview page ([#2484](https://github.com/PrismJS/prism/issues/2484)) [`a0efa40b`](https://github.com/PrismJS/prism/commit/a0efa40b)
    * Line Numbers: Fixed class name on website [`453079bf`](https://github.com/PrismJS/prism/commit/453079bf)
    * Line Numbers: Improved documentation ([#2456](https://github.com/PrismJS/prism/issues/2456)) [`447429f0`](https://github.com/PrismJS/prism/commit/447429f0)
    * Line Numbers: Style inline code on website ([#2435](https://github.com/PrismJS/prism/issues/2435)) [`ad9c13e2`](https://github.com/PrismJS/prism/commit/ad9c13e2)
    * Filter highlightAll: Fixed typo ([#2391](https://github.com/PrismJS/prism/issues/2391)) [`55bf7ec1`](https://github.com/PrismJS/prism/commit/55bf7ec1)

## 1.20.0 (2020-04-04)

### New components

* __Concurnas__ ([#2206](https://github.com/PrismJS/prism/issues/2206)) [`b24f7348`](https://github.com/PrismJS/prism/commit/b24f7348)
* __DAX__ ([#2248](https://github.com/PrismJS/prism/issues/2248)) [`9227853f`](https://github.com/PrismJS/prism/commit/9227853f)
* __Excel Formula__ ([#2219](https://github.com/PrismJS/prism/issues/2219)) [`bf4f7bfa`](https://github.com/PrismJS/prism/commit/bf4f7bfa)
* __Factor__ ([#2203](https://github.com/PrismJS/prism/issues/2203)) [`f941102e`](https://github.com/PrismJS/prism/commit/f941102e)
* __LLVM IR__ ([#2221](https://github.com/PrismJS/prism/issues/2221)) [`43efde2e`](https://github.com/PrismJS/prism/commit/43efde2e)
* __PowerQuery__ ([#2250](https://github.com/PrismJS/prism/issues/2250)) [`8119e57b`](https://github.com/PrismJS/prism/commit/8119e57b)
* __Solution file__ ([#2213](https://github.com/PrismJS/prism/issues/2213)) [`15983d52`](https://github.com/PrismJS/prism/commit/15983d52)

### Updated components

* __Bash__
    * Added support for escaped quotes ([#2256](https://github.com/PrismJS/prism/issues/2256)) [`328d0e0e`](https://github.com/PrismJS/prism/commit/328d0e0e)
* __BBcode__
    * Added "shortcode" alias ([#2273](https://github.com/PrismJS/prism/issues/2273)) [`57eebced`](https://github.com/PrismJS/prism/commit/57eebced)
* __C/C++/OpenCL C__
    * Improvements ([#2196](https://github.com/PrismJS/prism/issues/2196)) [`674f4b35`](https://github.com/PrismJS/prism/commit/674f4b35)
* __C__
    * Improvemed `comment` pattern ([#2229](https://github.com/PrismJS/prism/issues/2229)) [`fa630726`](https://github.com/PrismJS/prism/commit/fa630726)
* __C#__
    * Fixed keywords in type lists blocking type names ([#2277](https://github.com/PrismJS/prism/issues/2277)) [`947a55bd`](https://github.com/PrismJS/prism/commit/947a55bd)
    * C# improvements ([#1444](https://github.com/PrismJS/prism/issues/1444)) [`42b15463`](https://github.com/PrismJS/prism/commit/42b15463)
* __C++__
    * Added C++20 keywords ([#2236](https://github.com/PrismJS/prism/issues/2236)) [`462ad57e`](https://github.com/PrismJS/prism/commit/462ad57e)
* __CSS__
    * Fixed `url()` containing "@" ([#2272](https://github.com/PrismJS/prism/issues/2272)) [`504a63ba`](https://github.com/PrismJS/prism/commit/504a63ba)
* __CSS Extras__
    * Added support for the selector function ([#2201](https://github.com/PrismJS/prism/issues/2201)) [`2e0eff76`](https://github.com/PrismJS/prism/commit/2e0eff76)
* __Elixir__
    * Added support for attributes names ending with `?` ([#2182](https://github.com/PrismJS/prism/issues/2182)) [`5450e24c`](https://github.com/PrismJS/prism/commit/5450e24c)
* __Java__
    * Added `record` keyword ([#2185](https://github.com/PrismJS/prism/issues/2185)) [`47910b5c`](https://github.com/PrismJS/prism/commit/47910b5c)
* __Markdown__
    * Added support for nested lists ([#2228](https://github.com/PrismJS/prism/issues/2228)) [`73c8a376`](https://github.com/PrismJS/prism/commit/73c8a376)
* __OpenCL__
    * Require C ([#2231](https://github.com/PrismJS/prism/issues/2231)) [`26626ded`](https://github.com/PrismJS/prism/commit/26626ded)
* __PHPDoc__
    * Fixed exponential backtracking ([#2198](https://github.com/PrismJS/prism/issues/2198)) [`3b42536e`](https://github.com/PrismJS/prism/commit/3b42536e)
* __Ruby__
    * Fixed exponential backtracking ([#2225](https://github.com/PrismJS/prism/issues/2225)) [`c5de5aa8`](https://github.com/PrismJS/prism/commit/c5de5aa8)
* __SAS__
    * Fixed SAS' "peerDependencies" ([#2230](https://github.com/PrismJS/prism/issues/2230)) [`7d8ff7ea`](https://github.com/PrismJS/prism/commit/7d8ff7ea)
* __Shell session__
    * Improvements ([#2208](https://github.com/PrismJS/prism/issues/2208)) [`bd16bd57`](https://github.com/PrismJS/prism/commit/bd16bd57)
* __Visual Basic__
    * Added support for comments with line continuations ([#2195](https://github.com/PrismJS/prism/issues/2195)) [`a7d67ca3`](https://github.com/PrismJS/prism/commit/a7d67ca3)
* __YAML__
    * Improvements ([#2226](https://github.com/PrismJS/prism/issues/2226)) [`5362ba16`](https://github.com/PrismJS/prism/commit/5362ba16)
    * Fixed highlighting of anchors and aliases ([#2217](https://github.com/PrismJS/prism/issues/2217)) [`6124c974`](https://github.com/PrismJS/prism/commit/6124c974)

### New plugins

* __Treeview__ ([#2265](https://github.com/PrismJS/prism/issues/2265)) [`be909b18`](https://github.com/PrismJS/prism/commit/be909b18)

### Updated plugins

* __Inline Color__
    * Support for (semi-)transparent colors and minor improvements ([#2223](https://github.com/PrismJS/prism/issues/2223)) [`8d2c5a3e`](https://github.com/PrismJS/prism/commit/8d2c5a3e)
* __Keep Markup__
    * Remove self & document from IIFE arguments ([#2258](https://github.com/PrismJS/prism/issues/2258)) [`3c043338`](https://github.com/PrismJS/prism/commit/3c043338)
* __Toolbar__
    * `data-toolbar-order` is now inherited ([#2205](https://github.com/PrismJS/prism/issues/2205)) [`238f1163`](https://github.com/PrismJS/prism/commit/238f1163)

### Other

* Updated all `String.propotype.replace` calls for literal strings [`5d7aab56`](https://github.com/PrismJS/prism/commit/5d7aab56)
* __Core__
    * Linked list implementation for `matchGrammar` ([#1909](https://github.com/PrismJS/prism/issues/1909)) [`2d4c94cd`](https://github.com/PrismJS/prism/commit/2d4c94cd)
    * Faster `Token.stringify` ([#2171](https://github.com/PrismJS/prism/issues/2171)) [`f683972e`](https://github.com/PrismJS/prism/commit/f683972e)
    * Fixed scope problem in script mode ([#2184](https://github.com/PrismJS/prism/issues/2184)) [`984e5d2e`](https://github.com/PrismJS/prism/commit/984e5d2e)
* __Infrastructure__
    * Travis: Updated NodeJS versions ([#2246](https://github.com/PrismJS/prism/issues/2246)) [`e635260b`](https://github.com/PrismJS/prism/commit/e635260b)
    * gulp: Inline regex source improvement ([#2227](https://github.com/PrismJS/prism/issues/2227)) [`67afc5ad`](https://github.com/PrismJS/prism/commit/67afc5ad)
    * Tests: Added new pattern check for octal escapes ([#2189](https://github.com/PrismJS/prism/issues/2189)) [`81e1c3dd`](https://github.com/PrismJS/prism/commit/81e1c3dd)
    * Tests: Fixed optional dependencies in pattern tests ([#2242](https://github.com/PrismJS/prism/issues/2242)) [`1e3070a2`](https://github.com/PrismJS/prism/commit/1e3070a2)
    * Tests: Added test for zero-width lookbehinds ([#2220](https://github.com/PrismJS/prism/issues/2220)) [`7d03ece4`](https://github.com/PrismJS/prism/commit/7d03ece4)
    * Added tests for examples ([#2216](https://github.com/PrismJS/prism/issues/2216)) [`1f7a245c`](https://github.com/PrismJS/prism/commit/1f7a245c)
* __Website__
    * Removed invalid strings from C# example ([#2266](https://github.com/PrismJS/prism/issues/2266)) [`c917a8ca`](https://github.com/PrismJS/prism/commit/c917a8ca)
    * Fixed Diff highlight plugin page title ([#2233](https://github.com/PrismJS/prism/issues/2233)) [`a82770f8`](https://github.com/PrismJS/prism/commit/a82770f8)
    * Added link to `prism-liquibase` Bash language extension. ([#2191](https://github.com/PrismJS/prism/issues/2191)) [`0bf73dc7`](https://github.com/PrismJS/prism/commit/0bf73dc7)
    * Examples: Updated content header ([#2232](https://github.com/PrismJS/prism/issues/2232)) [`6232878b`](https://github.com/PrismJS/prism/commit/6232878b)
    * Website: Added Coy bug to the known failures page. ([#2170](https://github.com/PrismJS/prism/issues/2170)) [`e9dab85e`](https://github.com/PrismJS/prism/commit/e9dab85e)

## 1.19.0 (2020-01-13)

### New components

* __Latte__ ([#2140](https://github.com/PrismJS/prism/issues/2140)) [`694a81b8`](https://github.com/PrismJS/prism/commit/694a81b8)
* __Neon__ ([#2140](https://github.com/PrismJS/prism/issues/2140)) [`694a81b8`](https://github.com/PrismJS/prism/commit/694a81b8)
* __QML__ ([#2139](https://github.com/PrismJS/prism/issues/2139)) [`c40d96c6`](https://github.com/PrismJS/prism/commit/c40d96c6)

### Updated components

* __Handlebars__
    * Added support for `:` and improved the `variable` pattern ([#2172](https://github.com/PrismJS/prism/issues/2172)) [`ef4d29d9`](https://github.com/PrismJS/prism/commit/ef4d29d9)
* __JavaScript__
    * Added support for keywords after a spread operator ([#2148](https://github.com/PrismJS/prism/issues/2148)) [`1f3f8929`](https://github.com/PrismJS/prism/commit/1f3f8929)
    * Better regex detection ([#2158](https://github.com/PrismJS/prism/issues/2158)) [`a23d8f84`](https://github.com/PrismJS/prism/commit/a23d8f84)
* __Markdown__
    * Better language detection for code blocks ([#2114](https://github.com/PrismJS/prism/issues/2114)) [`d7ad48f9`](https://github.com/PrismJS/prism/commit/d7ad48f9)
* __OCaml__
    * Improvements ([#2179](https://github.com/PrismJS/prism/issues/2179)) [`2a570fd4`](https://github.com/PrismJS/prism/commit/2a570fd4)
* __PHP__
    * Fixed exponential runtime of a pattern ([#2157](https://github.com/PrismJS/prism/issues/2157)) [`24c8f833`](https://github.com/PrismJS/prism/commit/24c8f833)
* __React JSX__
    * Improved spread operator in tag attributes ([#2159](https://github.com/PrismJS/prism/issues/2159)) [`fd857e7b`](https://github.com/PrismJS/prism/commit/fd857e7b)
    * Made `$` a valid character for attribute names ([#2144](https://github.com/PrismJS/prism/issues/2144)) [`f018cf04`](https://github.com/PrismJS/prism/commit/f018cf04)
* __Reason__
    * Added support for single line comments ([#2150](https://github.com/PrismJS/prism/issues/2150)) [`7f1c55b7`](https://github.com/PrismJS/prism/commit/7f1c55b7)
* __Ruby__
    * Override 'class-name' definition ([#2135](https://github.com/PrismJS/prism/issues/2135)) [`401d4b02`](https://github.com/PrismJS/prism/commit/401d4b02)
* __SAS__
    * Added CASL support ([#2112](https://github.com/PrismJS/prism/issues/2112)) [`99d979a0`](https://github.com/PrismJS/prism/commit/99d979a0)

### Updated plugins

* __Custom Class__
    * Fixed TypeError when mapper is undefined ([#2167](https://github.com/PrismJS/prism/issues/2167)) [`543f04d7`](https://github.com/PrismJS/prism/commit/543f04d7)

### Updated themes

* Added missing `.token` selector ([#2161](https://github.com/PrismJS/prism/issues/2161)) [`86780457`](https://github.com/PrismJS/prism/commit/86780457)

### Other

* Added a check for redundant dependency declarations ([#2142](https://github.com/PrismJS/prism/issues/2142)) [`a06aca06`](https://github.com/PrismJS/prism/commit/a06aca06)
* Added a check for examples ([#2128](https://github.com/PrismJS/prism/issues/2128)) [`0b539136`](https://github.com/PrismJS/prism/commit/0b539136)
* Added silent option to `loadLanguages` ([#2147](https://github.com/PrismJS/prism/issues/2147)) [`191b4116`](https://github.com/PrismJS/prism/commit/191b4116)
* __Infrastructure__
    * Dependencies: Improved `getLoader` ([#2151](https://github.com/PrismJS/prism/issues/2151)) [`199bdcae`](https://github.com/PrismJS/prism/commit/199bdcae)
    * Updated gulp to v4.0.2 ([#2178](https://github.com/PrismJS/prism/issues/2178)) [`e5678a00`](https://github.com/PrismJS/prism/commit/e5678a00)
* __Website__
    * Custom Class: Fixed examples ([#2160](https://github.com/PrismJS/prism/issues/2160)) [`0c2fe405`](https://github.com/PrismJS/prism/commit/0c2fe405)
    * Added documentation for new dependency API ([#2141](https://github.com/PrismJS/prism/issues/2141)) [`59068d67`](https://github.com/PrismJS/prism/commit/59068d67)

## 1.18.0 (2020-01-04)

### New components

* __ANTLR4__ ([#2063](https://github.com/PrismJS/prism/issues/2063)) [`aaaa29a8`](https://github.com/PrismJS/prism/commit/aaaa29a8)
* __AQL__ ([#2025](https://github.com/PrismJS/prism/issues/2025)) [`3fdb7d55`](https://github.com/PrismJS/prism/commit/3fdb7d55)
* __BBcode__ ([#2095](https://github.com/PrismJS/prism/issues/2095)) [`aaf13aa6`](https://github.com/PrismJS/prism/commit/aaf13aa6)
* __BrightScript__ ([#2096](https://github.com/PrismJS/prism/issues/2096)) [`631f1e34`](https://github.com/PrismJS/prism/commit/631f1e34)
* __Embedded Lua templating__ ([#2050](https://github.com/PrismJS/prism/issues/2050)) [`0b771c90`](https://github.com/PrismJS/prism/commit/0b771c90)
* __Firestore security rules__ ([#2010](https://github.com/PrismJS/prism/issues/2010)) [`9f722586`](https://github.com/PrismJS/prism/commit/9f722586)
* __FreeMarker Template Language__ ([#2080](https://github.com/PrismJS/prism/issues/2080)) [`2f3da7e8`](https://github.com/PrismJS/prism/commit/2f3da7e8)
* __GDScript__ ([#2006](https://github.com/PrismJS/prism/issues/2006)) [`e2b99f40`](https://github.com/PrismJS/prism/commit/e2b99f40)
* __MoonScript__ ([#2100](https://github.com/PrismJS/prism/issues/2100)) [`f31946b3`](https://github.com/PrismJS/prism/commit/f31946b3)
* __Robot Framework__ (only the plain text format) ([#2034](https://github.com/PrismJS/prism/issues/2034)) [`f7eaa618`](https://github.com/PrismJS/prism/commit/f7eaa618)
* __Solidity (Ethereum)__ ([#2031](https://github.com/PrismJS/prism/issues/2031)) [`cc2cf3f7`](https://github.com/PrismJS/prism/commit/cc2cf3f7)
* __SPARQL__ ([#2033](https://github.com/PrismJS/prism/issues/2033)) [`c42f877d`](https://github.com/PrismJS/prism/commit/c42f877d)
* __SQF: Status Quo Function (Arma 3)__ ([#2079](https://github.com/PrismJS/prism/issues/2079)) [`cfac94ec`](https://github.com/PrismJS/prism/commit/cfac94ec)
* __Turtle__ & __TriG__ ([#2012](https://github.com/PrismJS/prism/issues/2012)) [`508d57ac`](https://github.com/PrismJS/prism/commit/508d57ac)
* __Zig__ ([#2019](https://github.com/PrismJS/prism/issues/2019)) [`a7cf56b7`](https://github.com/PrismJS/prism/commit/a7cf56b7)

### Updated components

* Minor improvements for C-like and Clojure ([#2064](https://github.com/PrismJS/prism/issues/2064)) [`7db0cab3`](https://github.com/PrismJS/prism/commit/7db0cab3)
* Inlined some unnecessary rest properties ([#2082](https://github.com/PrismJS/prism/issues/2082)) [`ad3fa443`](https://github.com/PrismJS/prism/commit/ad3fa443)
* __AQL__
    * Disallow unclosed multiline comments again ([#2089](https://github.com/PrismJS/prism/issues/2089)) [`717ace02`](https://github.com/PrismJS/prism/commit/717ace02)
    * Allow unclosed multi-line comments ([#2058](https://github.com/PrismJS/prism/issues/2058)) [`f3c6ba59`](https://github.com/PrismJS/prism/commit/f3c6ba59)
    * More pseudo keywords ([#2055](https://github.com/PrismJS/prism/issues/2055)) [`899574eb`](https://github.com/PrismJS/prism/commit/899574eb)
    * Added missing keyword + minor improvements ([#2047](https://github.com/PrismJS/prism/issues/2047)) [`32a4c422`](https://github.com/PrismJS/prism/commit/32a4c422)
* __Clojure__
    * Added multiline strings (lisp style) ([#2061](https://github.com/PrismJS/prism/issues/2061)) [`8ea685b8`](https://github.com/PrismJS/prism/commit/8ea685b8)
* __CSS Extras__
    * CSS Extras & PHP: Fixed too greedy number token ([#2009](https://github.com/PrismJS/prism/issues/2009)) [`ebe363f4`](https://github.com/PrismJS/prism/commit/ebe363f4)
* __D__
    * Fixed strings ([#2029](https://github.com/PrismJS/prism/issues/2029)) [`010a0157`](https://github.com/PrismJS/prism/commit/010a0157)
* __Groovy__
    * Minor improvements ([#2036](https://github.com/PrismJS/prism/issues/2036)) [`fb618331`](https://github.com/PrismJS/prism/commit/fb618331)
* __Java__
    * Added missing `::` operator ([#2101](https://github.com/PrismJS/prism/issues/2101)) [`ee7fdbee`](https://github.com/PrismJS/prism/commit/ee7fdbee)
    * Added support for new Java 13 syntax ([#2060](https://github.com/PrismJS/prism/issues/2060)) [`a7b95dd3`](https://github.com/PrismJS/prism/commit/a7b95dd3)
* __JavaScript__
    * Added Optional Chaining and Nullish Coalescing ([#2084](https://github.com/PrismJS/prism/issues/2084)) [`fdb7de0d`](https://github.com/PrismJS/prism/commit/fdb7de0d)
    * Tokenize `:` as an operator ([#2073](https://github.com/PrismJS/prism/issues/2073)) [`0e5c48d1`](https://github.com/PrismJS/prism/commit/0e5c48d1)
* __Less__
    * Fixed exponential backtracking ([#2016](https://github.com/PrismJS/prism/issues/2016)) [`d03d19b4`](https://github.com/PrismJS/prism/commit/d03d19b4)
* __Markup__
    * Improved doctype pattern ([#2094](https://github.com/PrismJS/prism/issues/2094)) [`99994c58`](https://github.com/PrismJS/prism/commit/99994c58)
* __Python__
    * Fixed decorators ([#2018](https://github.com/PrismJS/prism/issues/2018)) [`5b8a16d9`](https://github.com/PrismJS/prism/commit/5b8a16d9)
* __Robot Framework__
    * Rename "robot-framework" to "robotframework" ([#2113](https://github.com/PrismJS/prism/issues/2113)) [`baa78774`](https://github.com/PrismJS/prism/commit/baa78774)
* __Ruby__
    * Made `true` and `false` booleans ([#2098](https://github.com/PrismJS/prism/issues/2098)) [`68d1c472`](https://github.com/PrismJS/prism/commit/68d1c472)
    * Added missing keywords ([#2097](https://github.com/PrismJS/prism/issues/2097)) [`f460eafc`](https://github.com/PrismJS/prism/commit/f460eafc)
* __SAS__
    * Added support for embedded Groovy and Lua code ([#2091](https://github.com/PrismJS/prism/issues/2091)) [`3640b3f2`](https://github.com/PrismJS/prism/commit/3640b3f2)
    * Minor improvements ([#2085](https://github.com/PrismJS/prism/issues/2085)) [`07020c7a`](https://github.com/PrismJS/prism/commit/07020c7a)
    * Fixed `proc-args` token by removing backreferences from string pattern ([#2013](https://github.com/PrismJS/prism/issues/2013)) [`af5a36ae`](https://github.com/PrismJS/prism/commit/af5a36ae)
    * Major improvements ([#1981](https://github.com/PrismJS/prism/issues/1981)) [`076f6155`](https://github.com/PrismJS/prism/commit/076f6155)
* __Smalltalk__
    * Fixed single quote character literal ([#2041](https://github.com/PrismJS/prism/issues/2041)) [`1aabcd17`](https://github.com/PrismJS/prism/commit/1aabcd17)
* __Turtle__
    * Minor improvements ([#2038](https://github.com/PrismJS/prism/issues/2038)) [`8ccd258b`](https://github.com/PrismJS/prism/commit/8ccd258b)
* __TypeScript__
    * Added missing keyword `undefined` ([#2088](https://github.com/PrismJS/prism/issues/2088)) [`c8b48b9f`](https://github.com/PrismJS/prism/commit/c8b48b9f)

### Updated plugins

* New Match Braces plugin ([#1944](https://github.com/PrismJS/prism/issues/1944)) [`365faade`](https://github.com/PrismJS/prism/commit/365faade)
* New Inline color plugin ([#2007](https://github.com/PrismJS/prism/issues/2007)) [`8403e453`](https://github.com/PrismJS/prism/commit/8403e453)
* New Filter highlightAll plugin ([#2074](https://github.com/PrismJS/prism/issues/2074)) [`a7f70090`](https://github.com/PrismJS/prism/commit/a7f70090)
* __Custom Class__
    * New class adder feature ([#2075](https://github.com/PrismJS/prism/issues/2075)) [`dab7998e`](https://github.com/PrismJS/prism/commit/dab7998e)
* __File Highlight__
    * Made the download button its own plugin ([#1840](https://github.com/PrismJS/prism/issues/1840)) [`c6c62a69`](https://github.com/PrismJS/prism/commit/c6c62a69)

### Other

* Issue template improvements ([#2069](https://github.com/PrismJS/prism/issues/2069)) [`53f07b1b`](https://github.com/PrismJS/prism/commit/53f07b1b)
* Readme: Links now use HTTPS if available ([#2045](https://github.com/PrismJS/prism/issues/2045)) [`6cd0738a`](https://github.com/PrismJS/prism/commit/6cd0738a)
* __Core__
    * Fixed null reference ([#2106](https://github.com/PrismJS/prism/issues/2106)) [`0fd062d5`](https://github.com/PrismJS/prism/commit/0fd062d5)
    * Fixed race condition caused by deferring the script ([#2103](https://github.com/PrismJS/prism/issues/2103)) [`a3785ec9`](https://github.com/PrismJS/prism/commit/a3785ec9)
    * Minor improvements ([#1973](https://github.com/PrismJS/prism/issues/1973)) [`2d858e0a`](https://github.com/PrismJS/prism/commit/2d858e0a)
    * Fixed greedy partial lookbehinds not working ([#2030](https://github.com/PrismJS/prism/issues/2030)) [`174ed103`](https://github.com/PrismJS/prism/commit/174ed103)
    * Fixed greedy targeting bug ([#1932](https://github.com/PrismJS/prism/issues/1932)) [`e864d518`](https://github.com/PrismJS/prism/commit/e864d518)
    * Doubly check the `manual` flag ([#1957](https://github.com/PrismJS/prism/issues/1957)) [`d49f0f26`](https://github.com/PrismJS/prism/commit/d49f0f26)
    * IE11 workaround for `currentScript` ([#2104](https://github.com/PrismJS/prism/issues/2104)) [`2108c60f`](https://github.com/PrismJS/prism/commit/2108c60f)
* __Infrastructure__
    * gulp: Fixed changes task [`2f495905`](https://github.com/PrismJS/prism/commit/2f495905)
    * npm: Added `.github` folder to npm ignore ([#2052](https://github.com/PrismJS/prism/issues/2052)) [`1af89e06`](https://github.com/PrismJS/prism/commit/1af89e06)
    * npm: Updated dependencies to fix 122 vulnerabilities ([#1997](https://github.com/PrismJS/prism/issues/1997)) [`3af5d744`](https://github.com/PrismJS/prism/commit/3af5d744)
    * Tests: New test for unused capturing groups ([#1996](https://github.com/PrismJS/prism/issues/1996)) [`c187e229`](https://github.com/PrismJS/prism/commit/c187e229)
    * Tests: Simplified error message format ([#2056](https://github.com/PrismJS/prism/issues/2056)) [`007c9af4`](https://github.com/PrismJS/prism/commit/007c9af4)
    * Tests: New test for nice names ([#1911](https://github.com/PrismJS/prism/issues/1911)) [`3fda5c95`](https://github.com/PrismJS/prism/commit/3fda5c95)
    * Standardized dependency logic implementation ([#1998](https://github.com/PrismJS/prism/issues/1998)) [`7a4a0c7c`](https://github.com/PrismJS/prism/commit/7a4a0c7c)
* __Website__
    * Added @mAAdhaTTah and @RunDevelopment to credits and footer [`5d07aa7c`](https://github.com/PrismJS/prism/commit/5d07aa7c)
    * Added plugin descriptions to plugin list ([#2076](https://github.com/PrismJS/prism/issues/2076)) [`cdfa60ac`](https://github.com/PrismJS/prism/commit/cdfa60ac)
    * Use HTTPS link to alistapart.com ([#2044](https://github.com/PrismJS/prism/issues/2044)) [`8bcc1b85`](https://github.com/PrismJS/prism/commit/8bcc1b85)
    * Fixed the Toolbar plugin's overflow issue ([#1966](https://github.com/PrismJS/prism/issues/1966)) [`56a8711c`](https://github.com/PrismJS/prism/commit/56a8711c)
    * FAQ update ([#1977](https://github.com/PrismJS/prism/issues/1977)) [`8a572af5`](https://github.com/PrismJS/prism/commit/8a572af5)
    * Use modern JavaScript in the NodeJS usage section ([#1942](https://github.com/PrismJS/prism/issues/1942)) [`5c68a556`](https://github.com/PrismJS/prism/commit/5c68a556)
    * Improved test page performance for Chromium ([#2020](https://github.com/PrismJS/prism/issues/2020)) [`3509f3e5`](https://github.com/PrismJS/prism/commit/3509f3e5)
    * Fixed alias example in extending page ([#2011](https://github.com/PrismJS/prism/issues/2011)) [`7cb65eec`](https://github.com/PrismJS/prism/commit/7cb65eec)
    * Robot Framework: Renamed example file ([#2126](https://github.com/PrismJS/prism/issues/2126)) [`9908ca69`](https://github.com/PrismJS/prism/commit/9908ca69)

## 1.17.1 (2019-07-21)

### Other

* __Infrastructure__
    * Add .DS_Store to npmignore [`c2229ec2`](https://github.com/PrismJS/prism/commit/c2229ec2)

## 1.17.0 (2019-07-21)

### New components

* __DNS zone file__ ([#1961](https://github.com/PrismJS/prism/issues/1961)) [`bb84f98c`](https://github.com/PrismJS/prism/commit/bb84f98c)
* __JQ__ ([#1896](https://github.com/PrismJS/prism/issues/1896)) [`73d964be`](https://github.com/PrismJS/prism/commit/73d964be)
* __JS Templates__: Syntax highlighting inside tagged template literals ([#1931](https://github.com/PrismJS/prism/issues/1931)) [`c8844286`](https://github.com/PrismJS/prism/commit/c8844286)
* __LilyPond__ ([#1967](https://github.com/PrismJS/prism/issues/1967)) [`5d992fc5`](https://github.com/PrismJS/prism/commit/5d992fc5)
* __PascaLIGO__ ([#1947](https://github.com/PrismJS/prism/issues/1947)) [`858201c7`](https://github.com/PrismJS/prism/commit/858201c7)
* __PC-Axis__ ([#1940](https://github.com/PrismJS/prism/issues/1940)) [`473f7fbd`](https://github.com/PrismJS/prism/commit/473f7fbd)
* __Shell session__ ([#1892](https://github.com/PrismJS/prism/issues/1892)) [`96044979`](https://github.com/PrismJS/prism/commit/96044979)
* __Splunk SPL__ ([#1962](https://github.com/PrismJS/prism/issues/1962)) [`c93c066b`](https://github.com/PrismJS/prism/commit/c93c066b)

### New plugins

* __Diff Highlight__: Syntax highlighting inside diff blocks ([#1889](https://github.com/PrismJS/prism/issues/1889)) [`e7702ae1`](https://github.com/PrismJS/prism/commit/e7702ae1)

### Updated components

* __Bash__
    * Major improvements ([#1443](https://github.com/PrismJS/prism/issues/1443)) [`363281b3`](https://github.com/PrismJS/prism/commit/363281b3)
* __C#__
    * Added `cs` alias ([#1899](https://github.com/PrismJS/prism/issues/1899)) [`a8164559`](https://github.com/PrismJS/prism/commit/a8164559)
* __C++__
    * Fixed number pattern ([#1887](https://github.com/PrismJS/prism/issues/1887)) [`3de29e72`](https://github.com/PrismJS/prism/commit/3de29e72)
* __CSS__
    * Extended `url` inside ([#1874](https://github.com/PrismJS/prism/issues/1874)) [`f0a10669`](https://github.com/PrismJS/prism/commit/f0a10669)
    * Removed unnecessary flag and modifier ([#1875](https://github.com/PrismJS/prism/issues/1875)) [`74050c68`](https://github.com/PrismJS/prism/commit/74050c68)
* __CSS Extras__
    * Added `even` & `odd` keywords to `n-th` pattern ([#1872](https://github.com/PrismJS/prism/issues/1872)) [`5e5a3e00`](https://github.com/PrismJS/prism/commit/5e5a3e00)
* __F#__
    * Improved character literals ([#1956](https://github.com/PrismJS/prism/issues/1956)) [`d58d2aeb`](https://github.com/PrismJS/prism/commit/d58d2aeb)
* __JavaScript__
    * Fixed escaped template interpolation ([#1931](https://github.com/PrismJS/prism/issues/1931)) [`c8844286`](https://github.com/PrismJS/prism/commit/c8844286)
    * Added support for private fields ([#1950](https://github.com/PrismJS/prism/issues/1950)) [`7bd08327`](https://github.com/PrismJS/prism/commit/7bd08327)
    * Added support for numeric separators ([#1895](https://github.com/PrismJS/prism/issues/1895)) [`6068bf18`](https://github.com/PrismJS/prism/commit/6068bf18)
    * Increased bracket count of interpolation expressions in template strings ([#1845](https://github.com/PrismJS/prism/issues/1845)) [`c13d6e7d`](https://github.com/PrismJS/prism/commit/c13d6e7d)
    * Added support for the `s` regex flag ([#1846](https://github.com/PrismJS/prism/issues/1846)) [`9e164935`](https://github.com/PrismJS/prism/commit/9e164935)
    * Formatting: Added missing semicolon ([#1856](https://github.com/PrismJS/prism/issues/1856)) [`e2683959`](https://github.com/PrismJS/prism/commit/e2683959)
* __JSON__
    * Kinda fixed comment issue ([#1853](https://github.com/PrismJS/prism/issues/1853)) [`cbe05ec3`](https://github.com/PrismJS/prism/commit/cbe05ec3)
* __Julia__
    * Added `struct` keyword ([#1941](https://github.com/PrismJS/prism/issues/1941)) [`feb1b6f5`](https://github.com/PrismJS/prism/commit/feb1b6f5)
    * Highlight `Inf` and `NaN` as constants ([#1921](https://github.com/PrismJS/prism/issues/1921)) [`2141129f`](https://github.com/PrismJS/prism/commit/2141129f)
    * Added `in` keyword ([#1918](https://github.com/PrismJS/prism/issues/1918)) [`feb3187f`](https://github.com/PrismJS/prism/commit/feb3187f)
* __LaTeX__
    * Added TeX and ConTeXt alias ([#1915](https://github.com/PrismJS/prism/issues/1915)) [`5ad58a75`](https://github.com/PrismJS/prism/commit/5ad58a75)
    * Added support for $$ equations [`6f53f749`](https://github.com/PrismJS/prism/commit/6f53f749)
* __Markdown__
    * Markdown: Added support for auto-loading code block languages ([#1898](https://github.com/PrismJS/prism/issues/1898)) [`05823e88`](https://github.com/PrismJS/prism/commit/05823e88)
    * Improved URLs ([#1955](https://github.com/PrismJS/prism/issues/1955)) [`b9ec6fd8`](https://github.com/PrismJS/prism/commit/b9ec6fd8)
    * Added support for nested bold and italic expressions ([#1897](https://github.com/PrismJS/prism/issues/1897)) [`11903721`](https://github.com/PrismJS/prism/commit/11903721)
    * Added support for tables ([#1848](https://github.com/PrismJS/prism/issues/1848)) [`cedb8e84`](https://github.com/PrismJS/prism/commit/cedb8e84)
* __Perl__
    * Added `return` keyword ([#1943](https://github.com/PrismJS/prism/issues/1943)) [`2f39de97`](https://github.com/PrismJS/prism/commit/2f39de97)
* __Protocol Buffers__
    * Full support for PB2 and PB3 syntax + numerous other improvements ([#1948](https://github.com/PrismJS/prism/issues/1948)) [`de10bd1d`](https://github.com/PrismJS/prism/commit/de10bd1d)
* __reST (reStructuredText)__
    * Fixed exponentially backtracking pattern ([#1986](https://github.com/PrismJS/prism/issues/1986)) [`8b5d67a3`](https://github.com/PrismJS/prism/commit/8b5d67a3)
* __Rust__
    * Added `async` and `await` keywords. ([#1882](https://github.com/PrismJS/prism/issues/1882)) [`4faa3314`](https://github.com/PrismJS/prism/commit/4faa3314)
    * Improved punctuation and operators ([#1839](https://github.com/PrismJS/prism/issues/1839)) [`a42b1557`](https://github.com/PrismJS/prism/commit/a42b1557)
* __Sass (Scss)__
    * Fixed exponential url pattern ([#1938](https://github.com/PrismJS/prism/issues/1938)) [`4b6b6e8b`](https://github.com/PrismJS/prism/commit/4b6b6e8b)
* __Scheme__
    * Added support for rational number literals ([#1964](https://github.com/PrismJS/prism/issues/1964)) [`e8811d22`](https://github.com/PrismJS/prism/commit/e8811d22)
* __TOML__
    * Minor improvements ([#1917](https://github.com/PrismJS/prism/issues/1917)) [`3e181241`](https://github.com/PrismJS/prism/commit/3e181241)
* __Visual Basic__
    * Added support for interpolation strings ([#1971](https://github.com/PrismJS/prism/issues/1971)) [`4a2c90c1`](https://github.com/PrismJS/prism/commit/4a2c90c1)

### Updated plugins

* __Autolinker__
    * Improved component path guessing ([#1928](https://github.com/PrismJS/prism/issues/1928)) [`452d5c7d`](https://github.com/PrismJS/prism/commit/452d5c7d)
    * Improved URL regex ([#1842](https://github.com/PrismJS/prism/issues/1842)) [`eb28b62b`](https://github.com/PrismJS/prism/commit/eb28b62b)
* __Autoloader__
    * Fixed and improved callbacks ([#1935](https://github.com/PrismJS/prism/issues/1935)) [`b19f512f`](https://github.com/PrismJS/prism/commit/b19f512f)
* __Command Line__
    * Fix for uncaught errors for empty 'commandLine' object. ([#1862](https://github.com/PrismJS/prism/issues/1862)) [`c24831b5`](https://github.com/PrismJS/prism/commit/c24831b5)
* __Copy to Clipboard Button__
    * Switch anchor to button ([#1926](https://github.com/PrismJS/prism/issues/1926)) [`79880197`](https://github.com/PrismJS/prism/commit/79880197)
* __Custom Class__
    * Added mapper functions for language specific transformations ([#1873](https://github.com/PrismJS/prism/issues/1873)) [`acceb3b5`](https://github.com/PrismJS/prism/commit/acceb3b5)
* __Line Highlight__
    * Batching DOM read/writes to avoid reflows ([#1865](https://github.com/PrismJS/prism/issues/1865)) [`632ce00c`](https://github.com/PrismJS/prism/commit/632ce00c)
* __Toolbar__
    * Added `className` option for toolbar items ([#1951](https://github.com/PrismJS/prism/issues/1951)) [`5ab28bbe`](https://github.com/PrismJS/prism/commit/5ab28bbe)
    * Set opacity to 1 when focus is within ([#1927](https://github.com/PrismJS/prism/issues/1927)) [`0b1662dd`](https://github.com/PrismJS/prism/commit/0b1662dd)

### Updated themes

* __Funky__
    * Fixed typo ([#1960](https://github.com/PrismJS/prism/issues/1960)) [`7d056591`](https://github.com/PrismJS/prism/commit/7d056591)

### Other

* README: Added npm downloads badge ([#1934](https://github.com/PrismJS/prism/issues/1934)) [`d673d701`](https://github.com/PrismJS/prism/commit/d673d701)
* README: Minor changes ([#1857](https://github.com/PrismJS/prism/issues/1857)) [`77e403cb`](https://github.com/PrismJS/prism/commit/77e403cb)
* Clearer description for the highlighting bug report template ([#1850](https://github.com/PrismJS/prism/issues/1850)) [`2f9c9261`](https://github.com/PrismJS/prism/commit/2f9c9261)
* More language examples ([#1917](https://github.com/PrismJS/prism/issues/1917)) [`3e181241`](https://github.com/PrismJS/prism/commit/3e181241)
* __Core__
    * Removed `env.elements` from `before-highlightall` hook ([#1968](https://github.com/PrismJS/prism/issues/1968)) [`9d9e2ca4`](https://github.com/PrismJS/prism/commit/9d9e2ca4)
    * Made `language-none` the default language ([#1858](https://github.com/PrismJS/prism/issues/1858)) [`fd691c52`](https://github.com/PrismJS/prism/commit/fd691c52)
    * Removed `parent` from the `wrap` hook's environment ([#1837](https://github.com/PrismJS/prism/issues/1837)) [`65a4e894`](https://github.com/PrismJS/prism/commit/65a4e894)
* __Infrastructure__
    * gulp: Split `gulpfile.js` and expanded `changes` task ([#1835](https://github.com/PrismJS/prism/issues/1835)) [`033c5ad8`](https://github.com/PrismJS/prism/commit/033c5ad8)
    * gulp: JSON formatting for partly generated files ([#1933](https://github.com/PrismJS/prism/issues/1933)) [`d4373f3a`](https://github.com/PrismJS/prism/commit/d4373f3a)
    * gulp: Use `async` functions & drop testing on Node v6 ([#1783](https://github.com/PrismJS/prism/issues/1783)) [`0dd44d53`](https://github.com/PrismJS/prism/commit/0dd44d53)
    * Tests: `lookbehind` test for patterns ([#1890](https://github.com/PrismJS/prism/issues/1890)) [`3ba786cd`](https://github.com/PrismJS/prism/commit/3ba786cd)
    * Tests: Added test for empty regexes ([#1847](https://github.com/PrismJS/prism/issues/1847)) [`c1e6a7fd`](https://github.com/PrismJS/prism/commit/c1e6a7fd)
* __Website__
    * Added tutorial for using PrismJS with React ([#1979](https://github.com/PrismJS/prism/issues/1979)) [`f1e16c7b`](https://github.com/PrismJS/prism/commit/f1e16c7b)
    * Update footer's GitHub repository URL and capitalisation of "GitHub" ([#1983](https://github.com/PrismJS/prism/issues/1983)) [`bab744a6`](https://github.com/PrismJS/prism/commit/bab744a6)
    * Added known failures page ([#1876](https://github.com/PrismJS/prism/issues/1876)) [`36a5fa0e`](https://github.com/PrismJS/prism/commit/36a5fa0e)
    * Added basic usage for CDNs ([#1924](https://github.com/PrismJS/prism/issues/1924)) [`922ec555`](https://github.com/PrismJS/prism/commit/922ec555)
    * New tutorial for Drupal ([#1859](https://github.com/PrismJS/prism/issues/1859)) [`d2089d83`](https://github.com/PrismJS/prism/commit/d2089d83)
    * Updated website page styles to not interfere with themes ([#1952](https://github.com/PrismJS/prism/issues/1952)) [`b6543853`](https://github.com/PrismJS/prism/commit/b6543853)
    * Download page: Improved performance for Chromium-based browsers ([#1907](https://github.com/PrismJS/prism/issues/1907)) [`11f18e36`](https://github.com/PrismJS/prism/commit/11f18e36)
    * Download page: Fixed Edge's word wrap ([#1920](https://github.com/PrismJS/prism/issues/1920)) [`5d191b92`](https://github.com/PrismJS/prism/commit/5d191b92)
    * Examples page: Minor improvements ([#1919](https://github.com/PrismJS/prism/issues/1919)) [`a16d4a25`](https://github.com/PrismJS/prism/commit/a16d4a25)
    * Extending page: Fixed typo + new alias section ([#1949](https://github.com/PrismJS/prism/issues/1949)) [`24c8e717`](https://github.com/PrismJS/prism/commit/24c8e717)
    * Extending page: Added "Creating a new language definition" section ([#1925](https://github.com/PrismJS/prism/issues/1925)) [`ddf81233`](https://github.com/PrismJS/prism/commit/ddf81233)
    * Test page: Use `prism-core.js` instead of `prism.js` ([#1908](https://github.com/PrismJS/prism/issues/1908)) [`0853e694`](https://github.com/PrismJS/prism/commit/0853e694)
    * Copy to clipboard: Fixed typo ([#1869](https://github.com/PrismJS/prism/issues/1869)) [`59d4323f`](https://github.com/PrismJS/prism/commit/59d4323f)
    * JSONP Highlight: Fixed examples ([#1877](https://github.com/PrismJS/prism/issues/1877)) [`f8ae465d`](https://github.com/PrismJS/prism/commit/f8ae465d)
    * Line numbers: Fixed typo on webpage ([#1838](https://github.com/PrismJS/prism/issues/1838)) [`0f16eb87`](https://github.com/PrismJS/prism/commit/0f16eb87)

## 1.16.0 (2019-03-24)

### New components

* __ANBF__ ([#1753](https://github.com/PrismJS/prism/issues/1753)) [`6d98f0e7`](https://github.com/PrismJS/prism/commit/6d98f0e7)
* __BNF__ & __RBNF__ ([#1754](https://github.com/PrismJS/prism/issues/1754)) [`1df96c55`](https://github.com/PrismJS/prism/commit/1df96c55)
* __CIL__ ([#1593](https://github.com/PrismJS/prism/issues/1593)) [`38def334`](https://github.com/PrismJS/prism/commit/38def334)
* __CMake__ ([#1820](https://github.com/PrismJS/prism/issues/1820)) [`30779976`](https://github.com/PrismJS/prism/commit/30779976)
* __Doc comment__ ([#1541](https://github.com/PrismJS/prism/issues/1541)) [`493d19ef`](https://github.com/PrismJS/prism/commit/493d19ef)
* __EBNF__ ([#1756](https://github.com/PrismJS/prism/issues/1756)) [`13e1c97d`](https://github.com/PrismJS/prism/commit/13e1c97d)
* __EJS__ ([#1769](https://github.com/PrismJS/prism/issues/1769)) [`c37c90df`](https://github.com/PrismJS/prism/commit/c37c90df)
* __G-code__ ([#1572](https://github.com/PrismJS/prism/issues/1572)) [`2288c25e`](https://github.com/PrismJS/prism/commit/2288c25e)
* __GameMaker Language__ ([#1551](https://github.com/PrismJS/prism/issues/1551)) [`e529edd8`](https://github.com/PrismJS/prism/commit/e529edd8)
* __HCL__ ([#1594](https://github.com/PrismJS/prism/issues/1594)) [`c939df8e`](https://github.com/PrismJS/prism/commit/c939df8e)
* __Java stack trace__ ([#1520](https://github.com/PrismJS/prism/issues/1520)) [`4a8219a4`](https://github.com/PrismJS/prism/commit/4a8219a4)
* __JavaScript Extras__ ([#1743](https://github.com/PrismJS/prism/issues/1743)) [`bb628606`](https://github.com/PrismJS/prism/commit/bb628606)
* __JSON5__ ([#1744](https://github.com/PrismJS/prism/issues/1744)) [`64dc049d`](https://github.com/PrismJS/prism/commit/64dc049d)
* __N1QL__ ([#1620](https://github.com/PrismJS/prism/issues/1620)) [`7def8f5c`](https://github.com/PrismJS/prism/commit/7def8f5c)
* __Nand To Tetris HDL__ ([#1710](https://github.com/PrismJS/prism/issues/1710)) [`b94b56c1`](https://github.com/PrismJS/prism/commit/b94b56c1)
* __Regex__ ([#1682](https://github.com/PrismJS/prism/issues/1682)) [`571704cb`](https://github.com/PrismJS/prism/commit/571704cb)
* __T4__ ([#1699](https://github.com/PrismJS/prism/issues/1699)) [`16f2ad06`](https://github.com/PrismJS/prism/commit/16f2ad06)
* __TOML__ ([#1488](https://github.com/PrismJS/prism/issues/1488)) [`5b6ad70d`](https://github.com/PrismJS/prism/commit/5b6ad70d)
* __Vala__ ([#1658](https://github.com/PrismJS/prism/issues/1658)) [`b48c012c`](https://github.com/PrismJS/prism/commit/b48c012c)

### Updated components

* Fixed dependencies of Pug and Pure ([#1759](https://github.com/PrismJS/prism/issues/1759)) [`c9a32674`](https://github.com/PrismJS/prism/commit/c9a32674)
* Add file extensions support for major languages ([#1478](https://github.com/PrismJS/prism/issues/1478)) [`0c8f6504`](https://github.com/PrismJS/prism/commit/0c8f6504)
* Fixed patterns which can match the empty string ([#1775](https://github.com/PrismJS/prism/issues/1775)) [`86dd3e42`](https://github.com/PrismJS/prism/commit/86dd3e42)
* More variables for better code compression ([#1489](https://github.com/PrismJS/prism/issues/1489)) [`bc53e093`](https://github.com/PrismJS/prism/commit/bc53e093)
* Added missing aliases ([#1830](https://github.com/PrismJS/prism/issues/1830)) [`8d28c74c`](https://github.com/PrismJS/prism/commit/8d28c74c)
* Replaced all occurrences of `new RegExp` with `RegExp` ([#1493](https://github.com/PrismJS/prism/issues/1493)) [`44fed4d3`](https://github.com/PrismJS/prism/commit/44fed4d3)
* Added missing aliases to components.json ([#1503](https://github.com/PrismJS/prism/issues/1503)) [`2fb66e04`](https://github.com/PrismJS/prism/commit/2fb66e04)
* __Apacheconf__
	* Apache config: Minor improvements + new keyword ([#1823](https://github.com/PrismJS/prism/issues/1823)) [`a91be7b2`](https://github.com/PrismJS/prism/commit/a91be7b2)
* __AsciiDoc__
	* Added `adoc` alias for AsciiDoc ([#1685](https://github.com/PrismJS/prism/issues/1685)) [`88434f7a`](https://github.com/PrismJS/prism/commit/88434f7a)
* __Bash__
	* Add additional commands to bash ([#1577](https://github.com/PrismJS/prism/issues/1577)) [`a2230c38`](https://github.com/PrismJS/prism/commit/a2230c38)
	* Added `yarn add` to bash functions ([#1731](https://github.com/PrismJS/prism/issues/1731)) [`3a32cb75`](https://github.com/PrismJS/prism/commit/3a32cb75)
	* Added `pnpm` function to Bash ([#1734](https://github.com/PrismJS/prism/issues/1734)) [`fccfb98d`](https://github.com/PrismJS/prism/commit/fccfb98d)
* __Batch__
	* Remove batch's shell alias ([#1543](https://github.com/PrismJS/prism/issues/1543)) [`7155e60f`](https://github.com/PrismJS/prism/commit/7155e60f)
* __C__
	* Improve C language ([#1697](https://github.com/PrismJS/prism/issues/1697)) [`7eccea5c`](https://github.com/PrismJS/prism/commit/7eccea5c)
* __C-like__
	* Simplify function pattern of C-like language ([#1552](https://github.com/PrismJS/prism/issues/1552)) [`b520e1b6`](https://github.com/PrismJS/prism/commit/b520e1b6)
* __C/C++/Java__
	* Operator fixes ([#1528](https://github.com/PrismJS/prism/issues/1528)) [`7af8f8be`](https://github.com/PrismJS/prism/commit/7af8f8be)
* __C#__
	* Improvements to C# operator and punctuation ([#1532](https://github.com/PrismJS/prism/issues/1532)) [`3b1e0916`](https://github.com/PrismJS/prism/commit/3b1e0916)
* __CSS__
	* Fix tokenizing !important ([#1585](https://github.com/PrismJS/prism/issues/1585)) [`c1d6cb85`](https://github.com/PrismJS/prism/commit/c1d6cb85)
	* Added the comma to the list of CSS punctuation [`7ea2ff28`](https://github.com/PrismJS/prism/commit/7ea2ff28)
	* CSS: Comma punctuation ([#1632](https://github.com/PrismJS/prism/issues/1632)) [`1b812386`](https://github.com/PrismJS/prism/commit/1b812386)
	* Reuse CSS selector pattern in CSS Extras ([#1637](https://github.com/PrismJS/prism/issues/1637)) [`e2f2fd19`](https://github.com/PrismJS/prism/commit/e2f2fd19)
	* Fixed CSS extra variable ([#1649](https://github.com/PrismJS/prism/issues/1649)) [`9de47d3a`](https://github.com/PrismJS/prism/commit/9de47d3a)
	* Identify CSS units and variables ([#1450](https://github.com/PrismJS/prism/issues/1450)) [`5fcee966`](https://github.com/PrismJS/prism/commit/5fcee966)
	* Allow multiline CSS at-rules ([#1676](https://github.com/PrismJS/prism/issues/1676)) [`4f6f3c7d`](https://github.com/PrismJS/prism/commit/4f6f3c7d)
	* CSS: Highlight attribute selector ([#1671](https://github.com/PrismJS/prism/issues/1671)) [`245b59d4`](https://github.com/PrismJS/prism/commit/245b59d4)
	* CSS: Selectors can contain any string ([#1638](https://github.com/PrismJS/prism/issues/1638)) [`a2d445d0`](https://github.com/PrismJS/prism/commit/a2d445d0)
	* CSS extras: Highlighting for pseudo class arguments ([#1650](https://github.com/PrismJS/prism/issues/1650)) [`70a40414`](https://github.com/PrismJS/prism/commit/70a40414)
* __Django__
	* Django/Jinja2 improvements ([#1800](https://github.com/PrismJS/prism/issues/1800)) [`f2467488`](https://github.com/PrismJS/prism/commit/f2467488)
* __F#__
	* Chars can only contain one character ([#1570](https://github.com/PrismJS/prism/issues/1570)) [`f96b083a`](https://github.com/PrismJS/prism/commit/f96b083a)
	* Improve F# ([#1573](https://github.com/PrismJS/prism/issues/1573)) [`00bfc969`](https://github.com/PrismJS/prism/commit/00bfc969)
* __GraphQL__
	* Improved field highlighting for GraphQL ([#1711](https://github.com/PrismJS/prism/issues/1711)) [`44aeffb9`](https://github.com/PrismJS/prism/commit/44aeffb9)
	* Added GraphQL improvements and tests ([#1788](https://github.com/PrismJS/prism/issues/1788)) [`b2298b12`](https://github.com/PrismJS/prism/commit/b2298b12)
* __Haskell__
	* Added `hs` alias for Haskell ([#1831](https://github.com/PrismJS/prism/issues/1831)) [`64baec3c`](https://github.com/PrismJS/prism/commit/64baec3c)
* __HTTP__
	* Improved HTTP content highlighting ([#1598](https://github.com/PrismJS/prism/issues/1598)) [`1b75da90`](https://github.com/PrismJS/prism/commit/1b75da90)
* __Ini__
	* Add support for # comments to INI language ([#1730](https://github.com/PrismJS/prism/issues/1730)) [`baf6bb0c`](https://github.com/PrismJS/prism/commit/baf6bb0c)
* __Java__
	* Add Java 10 support ([#1549](https://github.com/PrismJS/prism/issues/1549)) [`8c981a22`](https://github.com/PrismJS/prism/commit/8c981a22)
	* Added module keywords to Java. ([#1655](https://github.com/PrismJS/prism/issues/1655)) [`6e250a5f`](https://github.com/PrismJS/prism/commit/6e250a5f)
	* Improve Java ([#1474](https://github.com/PrismJS/prism/issues/1474)) [`81bd8f0b`](https://github.com/PrismJS/prism/commit/81bd8f0b)
* __JavaScript__
	* Fix regex for `catch` and `finally` ([#1527](https://github.com/PrismJS/prism/issues/1527)) [`ebd1b9a6`](https://github.com/PrismJS/prism/commit/ebd1b9a6)
	* Highlighting of supposed classes and functions ([#1482](https://github.com/PrismJS/prism/issues/1482)) [`c40f6047`](https://github.com/PrismJS/prism/commit/c40f6047)
	* Added support for JS BigInt literals ([#1542](https://github.com/PrismJS/prism/issues/1542)) [`2b62e57b`](https://github.com/PrismJS/prism/commit/2b62e57b)
	* Fixed lowercase supposed class names ([#1544](https://github.com/PrismJS/prism/issues/1544)) [`a47c05ad`](https://github.com/PrismJS/prism/commit/a47c05ad)
	* Fixes regex for JS examples ([#1591](https://github.com/PrismJS/prism/issues/1591)) [`b41fb8f1`](https://github.com/PrismJS/prism/commit/b41fb8f1)
	* Improve regex detection in JS ([#1473](https://github.com/PrismJS/prism/issues/1473)) [`2a4758ab`](https://github.com/PrismJS/prism/commit/2a4758ab)
	* Identify JavaScript function parameters ([#1446](https://github.com/PrismJS/prism/issues/1446)) [`0cc8c56a`](https://github.com/PrismJS/prism/commit/0cc8c56a)
	* Improved JavaScript parameter recognization ([#1722](https://github.com/PrismJS/prism/issues/1722)) [`57a92035`](https://github.com/PrismJS/prism/commit/57a92035)
	* Make `undefined` a keyword in JS ([#1740](https://github.com/PrismJS/prism/issues/1740)) [`d9fa29a8`](https://github.com/PrismJS/prism/commit/d9fa29a8)
	* Fix `function-variable` in JS ([#1739](https://github.com/PrismJS/prism/issues/1739)) [`bfbea4d6`](https://github.com/PrismJS/prism/commit/bfbea4d6)
	* Improved JS constant pattern ([#1737](https://github.com/PrismJS/prism/issues/1737)) [`7bcec584`](https://github.com/PrismJS/prism/commit/7bcec584)
	* Improved JS function pattern ([#1736](https://github.com/PrismJS/prism/issues/1736)) [`8378ac83`](https://github.com/PrismJS/prism/commit/8378ac83)
	* JS: Fixed variables named "async" ([#1738](https://github.com/PrismJS/prism/issues/1738)) [`3560c643`](https://github.com/PrismJS/prism/commit/3560c643)
	* JS: Keyword fix ([#1808](https://github.com/PrismJS/prism/issues/1808)) [`f2d8e1c7`](https://github.com/PrismJS/prism/commit/f2d8e1c7)
* __JSON__ / __JSONP__
	* Fix bugs in JSON language ([#1479](https://github.com/PrismJS/prism/issues/1479)) [`74fe81c6`](https://github.com/PrismJS/prism/commit/74fe81c6)
	* Adds support for comments in JSON ([#1595](https://github.com/PrismJS/prism/issues/1595)) [`8720b3e6`](https://github.com/PrismJS/prism/commit/8720b3e6)
	* Cleaned up JSON ([#1596](https://github.com/PrismJS/prism/issues/1596)) [`da474c77`](https://github.com/PrismJS/prism/commit/da474c77)
	* Added `keyword` alias to JSON's `null` ([#1733](https://github.com/PrismJS/prism/issues/1733)) [`eee06649`](https://github.com/PrismJS/prism/commit/eee06649)
	* Fix JSONP support ([#1745](https://github.com/PrismJS/prism/issues/1745)) [`b5041cf9`](https://github.com/PrismJS/prism/commit/b5041cf9)
	* Fixed JSON/JSONP examples ([#1765](https://github.com/PrismJS/prism/issues/1765)) [`ae4842db`](https://github.com/PrismJS/prism/commit/ae4842db)
* __JSX__
	* React component tags are styled as classes in JSX ([#1519](https://github.com/PrismJS/prism/issues/1519)) [`3e1a9a3d`](https://github.com/PrismJS/prism/commit/3e1a9a3d)
	* Support JSX/TSX class-name with dot ([#1725](https://github.com/PrismJS/prism/issues/1725)) [`4362e42c`](https://github.com/PrismJS/prism/commit/4362e42c)
* __Less__
	* Remove useless insertBefore in LESS ([#1629](https://github.com/PrismJS/prism/issues/1629)) [`86d31793`](https://github.com/PrismJS/prism/commit/86d31793)
* __Lisp__
	* Fix Lisp exponential string pattern ([#1763](https://github.com/PrismJS/prism/issues/1763)) [`5bd182c0`](https://github.com/PrismJS/prism/commit/5bd182c0))
* __Markdown__
	* Added strike support to markdown ([#1563](https://github.com/PrismJS/prism/issues/1563)) [`9d2fddc2`](https://github.com/PrismJS/prism/commit/9d2fddc2)
	* Fixed Markdown headers ([#1557](https://github.com/PrismJS/prism/issues/1557)) [`c6584290`](https://github.com/PrismJS/prism/commit/c6584290)
	* Add support for code blocks in Markdown ([#1562](https://github.com/PrismJS/prism/issues/1562)) [`b0717e70`](https://github.com/PrismJS/prism/commit/b0717e70)
	* Markdown: The 'md' alias is now recognized by hooks ([#1771](https://github.com/PrismJS/prism/issues/1771)) [`8ca3d65b`](https://github.com/PrismJS/prism/commit/8ca3d65b)
* __Markup__
	* Decouple XML from Markup ([#1603](https://github.com/PrismJS/prism/issues/1603)) [`0030a4ef`](https://github.com/PrismJS/prism/commit/0030a4ef)
	* Fix for markup attributes ([#1752](https://github.com/PrismJS/prism/issues/1752)) [`c3862a24`](https://github.com/PrismJS/prism/commit/c3862a24)
	* Markup: Added support for CSS and JS inside of CDATAs ([#1660](https://github.com/PrismJS/prism/issues/1660)) [`57127701`](https://github.com/PrismJS/prism/commit/57127701)
	* Markup `addInline` improvements ([#1798](https://github.com/PrismJS/prism/issues/1798)) [`af67c32e`](https://github.com/PrismJS/prism/commit/af67c32e)
* __Markup Templating__
	* Markup-templating improvements ([#1653](https://github.com/PrismJS/prism/issues/1653)) [`b62e282b`](https://github.com/PrismJS/prism/commit/b62e282b)
* __nginx__
	* Add new keywords to nginx ([#1587](https://github.com/PrismJS/prism/issues/1587)) [`0d73f7f5`](https://github.com/PrismJS/prism/commit/0d73f7f5)
* __PHP__
	* Update PHP keywords ([#1690](https://github.com/PrismJS/prism/issues/1690)) [`55fb0f8e`](https://github.com/PrismJS/prism/commit/55fb0f8e)
	* Improve recognition of constants in PHP ([#1688](https://github.com/PrismJS/prism/issues/1688)) [`f1026b4b`](https://github.com/PrismJS/prism/commit/f1026b4b)
	* Made false, true, and null constants in PHP ([#1694](https://github.com/PrismJS/prism/issues/1694)) [`439e3bd7`](https://github.com/PrismJS/prism/commit/439e3bd7)
	* PHP: Fixed closing tag issue ([#1652](https://github.com/PrismJS/prism/issues/1652)) [`289ddd9b`](https://github.com/PrismJS/prism/commit/289ddd9b)
* __Python__
	* Operator keywords are now keywords ([#1617](https://github.com/PrismJS/prism/issues/1617)) [`1d1fb800`](https://github.com/PrismJS/prism/commit/1d1fb800)
	* Add decorator support to Python ([#1639](https://github.com/PrismJS/prism/issues/1639)) [`2577b6e6`](https://github.com/PrismJS/prism/commit/2577b6e6)
	* Improvements to Python F-strings and string prefixes ([#1642](https://github.com/PrismJS/prism/issues/1642)) [`a69c2b62`](https://github.com/PrismJS/prism/commit/a69c2b62)
* __Reason__
	* Added additional operators to Reason ([#1648](https://github.com/PrismJS/prism/issues/1648)) [`8b1bb469`](https://github.com/PrismJS/prism/commit/8b1bb469)
* __Ruby__
	* Consistent Ruby method highlighting ([#1523](https://github.com/PrismJS/prism/issues/1523)) [`72775919`](https://github.com/PrismJS/prism/commit/72775919)
	* Ruby/ERB: Fixed block comments ([#1768](https://github.com/PrismJS/prism/issues/1768)) [`c805f859`](https://github.com/PrismJS/prism/commit/c805f859)
* __Rust__
	* Add missing keywords ([#1634](https://github.com/PrismJS/prism/issues/1634)) [`3590edde`](https://github.com/PrismJS/prism/commit/3590edde)
* __SAS__
	* Added new SAS keywords ([#1784](https://github.com/PrismJS/prism/issues/1784)) [`3b396ef5`](https://github.com/PrismJS/prism/commit/3b396ef5)
* __Scheme__
	* Fix function without arguments in scheme language ([#1463](https://github.com/PrismJS/prism/issues/1463)) [`12a827e7`](https://github.com/PrismJS/prism/commit/12a827e7)
	* Scheme improvements ([#1556](https://github.com/PrismJS/prism/issues/1556)) [`225dd3f7`](https://github.com/PrismJS/prism/commit/225dd3f7)
	* Fixed operator-like functions in Scheme ([#1467](https://github.com/PrismJS/prism/issues/1467)) [`f8c8add2`](https://github.com/PrismJS/prism/commit/f8c8add2)
	* Scheme: Minor improvements ([#1814](https://github.com/PrismJS/prism/issues/1814)) [`191830f2`](https://github.com/PrismJS/prism/commit/191830f2)
* __SCSS__
	* Fixed that selector pattern can take exponential time ([#1499](https://github.com/PrismJS/prism/issues/1499)) [`0f75d9d4`](https://github.com/PrismJS/prism/commit/0f75d9d4)
	* Move SCSS `property` definition ([#1633](https://github.com/PrismJS/prism/issues/1633)) [`0536fb14`](https://github.com/PrismJS/prism/commit/0536fb14)
	* Add `keyword` alias for SCSS' `null` ([#1735](https://github.com/PrismJS/prism/issues/1735)) [`bd0378f0`](https://github.com/PrismJS/prism/commit/bd0378f0)
* __Smalltalk__
	* Allowed empty strings and comments ([#1747](https://github.com/PrismJS/prism/issues/1747)) [`5fd7577a`](https://github.com/PrismJS/prism/commit/5fd7577a)
* __Smarty__
	* Removed useless `insertBefore` call in Smarty ([#1677](https://github.com/PrismJS/prism/issues/1677)) [`bc49c361`](https://github.com/PrismJS/prism/commit/bc49c361)
* __SQL__
	* Added support for quote escapes to SQL strings ([#1500](https://github.com/PrismJS/prism/issues/1500)) [`a59a7926`](https://github.com/PrismJS/prism/commit/a59a7926)
	* SQL Quoted variables are now greedy ([#1510](https://github.com/PrismJS/prism/issues/1510)) [`42d119a2`](https://github.com/PrismJS/prism/commit/42d119a2)
* __TypeScript__
	* Enhance definitions in TypeScript component ([#1522](https://github.com/PrismJS/prism/issues/1522)) [`11695629`](https://github.com/PrismJS/prism/commit/11695629)
* __YAML__
	* Allow YAML strings to have trailing comments ([#1602](https://github.com/PrismJS/prism/issues/1602)) [`1c5f28a9`](https://github.com/PrismJS/prism/commit/1c5f28a9)

### Updated plugins

* Better class name detection for plugins ([#1772](https://github.com/PrismJS/prism/issues/1772)) [`c9762c6f`](https://github.com/PrismJS/prism/commit/c9762c6f)
* __Autolinker__
	* Fix Autolinker url-decoding all tokens ([#1723](https://github.com/PrismJS/prism/issues/1723)) [`8cf20d49`](https://github.com/PrismJS/prism/commit/8cf20d49)
* __Autoloader__
	* Resolved variable name clash ([#1568](https://github.com/PrismJS/prism/issues/1568)) [`bfa5a8d9`](https://github.com/PrismJS/prism/commit/bfa5a8d9)
	* Autoloader: Fixed the directory of scripts ([#1828](https://github.com/PrismJS/prism/issues/1828)) [`fd4c764f`](https://github.com/PrismJS/prism/commit/fd4c764f)
	* Autoloader: Added support for aliases ([#1829](https://github.com/PrismJS/prism/issues/1829)) [`52889b5b`](https://github.com/PrismJS/prism/commit/52889b5b)
* __Command Line__
	* Fixed class regex for Command Line plugin ([#1566](https://github.com/PrismJS/prism/issues/1566)) [`9f6e5026`](https://github.com/PrismJS/prism/commit/9f6e5026)
* __File Highlight__
	* Prevent double-loading & add scope to File Highlight ([#1586](https://github.com/PrismJS/prism/issues/1586)) [`10239c14`](https://github.com/PrismJS/prism/commit/10239c14)
* __JSONP Highlight__
	* Cleanup JSONP highlight code ([#1674](https://github.com/PrismJS/prism/issues/1674)) [`28489698`](https://github.com/PrismJS/prism/commit/28489698)
	* Fix typos & other issues in JSONP docs ([#1672](https://github.com/PrismJS/prism/issues/1672)) [`cd058a91`](https://github.com/PrismJS/prism/commit/cd058a91)
	* JSONP highlight: Fixed minified adapter names ([#1793](https://github.com/PrismJS/prism/issues/1793)) [`5dd8f916`](https://github.com/PrismJS/prism/commit/5dd8f916)
* __Keep Markup__
	* Add unit tests to the Keep Markup plugin ([#1646](https://github.com/PrismJS/prism/issues/1646)) [`a944c418`](https://github.com/PrismJS/prism/commit/a944c418)
* __Line Numbers__
	* Added inheritance for the `line-numbers` class ([#1799](https://github.com/PrismJS/prism/issues/1799)) [`14be7489`](https://github.com/PrismJS/prism/commit/14be7489)
* __Previewers__
	* Fixed Previewers bug [#1496](https://github.com/PrismJS/prism/issues/1496) ([#1497](https://github.com/PrismJS/prism/issues/1497)) [`4b56f3c1`](https://github.com/PrismJS/prism/commit/4b56f3c1)
* __Show Invisibles__
	* Updated styles of show invisibles ([#1607](https://github.com/PrismJS/prism/issues/1607)) [`2ba62268`](https://github.com/PrismJS/prism/commit/2ba62268)
	* Corrected load order of Show Invisibles ([#1612](https://github.com/PrismJS/prism/issues/1612)) [`6e0c6e86`](https://github.com/PrismJS/prism/commit/6e0c6e86)
	* Show invisibles inside tokens ([#1610](https://github.com/PrismJS/prism/issues/1610)) [`1090b253`](https://github.com/PrismJS/prism/commit/1090b253)
* __Show Language__
	* Show Language plugin alias support and improvements ([#1683](https://github.com/PrismJS/prism/issues/1683)) [`4c66d72c`](https://github.com/PrismJS/prism/commit/4c66d72c)
* __Toolbar__
	* Toolbar: Minor improvements ([#1818](https://github.com/PrismJS/prism/issues/1818)) [`3ad47047`](https://github.com/PrismJS/prism/commit/3ad47047)

### Updated themes

* Normalized the font-size of pre and code ([#1791](https://github.com/PrismJS/prism/issues/1791)) [`878ef295`](https://github.com/PrismJS/prism/commit/878ef295)
* __Coy__
	* Correct typo ([#1508](https://github.com/PrismJS/prism/issues/1508)) [`c322fc80`](https://github.com/PrismJS/prism/commit/c322fc80)

### Other changes

* __Core__
	* `insertBefore` now correctly updates references ([#1531](https://github.com/PrismJS/prism/issues/1531)) [`9dfec340`](https://github.com/PrismJS/prism/commit/9dfec340)
	* Invoke `callback` after `after-highlight` hook ([#1588](https://github.com/PrismJS/prism/issues/1588)) [`bfbe4464`](https://github.com/PrismJS/prism/commit/bfbe4464)
	* Improve `Prism.util.type` performance ([#1545](https://github.com/PrismJS/prism/issues/1545)) [`2864fe24`](https://github.com/PrismJS/prism/commit/2864fe24)
	* Remove unused `insertBefore` overload ([#1631](https://github.com/PrismJS/prism/issues/1631)) [`39686e12`](https://github.com/PrismJS/prism/commit/39686e12)
	* Ignore duplicates in insertBefore ([#1628](https://github.com/PrismJS/prism/issues/1628)) [`d33d259c`](https://github.com/PrismJS/prism/commit/d33d259c)
	* Remove the Prism.tokenize language parameter ([#1654](https://github.com/PrismJS/prism/issues/1654)) [`fbf0b094`](https://github.com/PrismJS/prism/commit/fbf0b094)
	* Call `insert-before` hook properly ([#1709](https://github.com/PrismJS/prism/issues/1709)) [`393ab164`](https://github.com/PrismJS/prism/commit/393ab164)
	* Improved languages.DFS and util.clone ([#1506](https://github.com/PrismJS/prism/issues/1506)) [`152a68ef`](https://github.com/PrismJS/prism/commit/152a68ef)
	* Core: Avoid redeclaring variables in util.clone ([#1778](https://github.com/PrismJS/prism/issues/1778)) [`b06f532f`](https://github.com/PrismJS/prism/commit/b06f532f)
	* Made prism-core a little more editor friendly ([#1776](https://github.com/PrismJS/prism/issues/1776)) [`bac09f0a`](https://github.com/PrismJS/prism/commit/bac09f0a)
	* Applied Array.isArray ([#1804](https://github.com/PrismJS/prism/issues/1804)) [`11d0f75e`](https://github.com/PrismJS/prism/commit/11d0f75e)
* __Infrastructure__
	* Linkify changelog more + add missing PR references [`2a100db7`](https://github.com/PrismJS/prism/commit/2a100db7)
	* Set default indentation size ([#1516](https://github.com/PrismJS/prism/issues/1516)) [`e63d1597`](https://github.com/PrismJS/prism/commit/e63d1597)
	* Add travis repo badge to readme ([#1561](https://github.com/PrismJS/prism/issues/1561)) [`716923f4`](https://github.com/PrismJS/prism/commit/716923f4)
	* Update README.md ([#1553](https://github.com/PrismJS/prism/issues/1553)) [`6d1a2c61`](https://github.com/PrismJS/prism/commit/6d1a2c61)
	* Mention Prism Themes in README ([#1625](https://github.com/PrismJS/prism/issues/1625)) [`5db04656`](https://github.com/PrismJS/prism/commit/5db04656)
	* Fixed CHANGELOG.md ([#1707](https://github.com/PrismJS/prism/issues/1707)) [`b1f8a65d`](https://github.com/PrismJS/prism/commit/b1f8a65d) ([#1704](https://github.com/PrismJS/prism/issues/1704)) [`66d2104a`](https://github.com/PrismJS/prism/commit/66d2104a)
	* Change tested NodeJS versions ([#1651](https://github.com/PrismJS/prism/issues/1651)) [`6ec71e0b`](https://github.com/PrismJS/prism/commit/6ec71e0b)
	* Inline regex source with gulp ([#1537](https://github.com/PrismJS/prism/issues/1537)) [`e894fc89`](https://github.com/PrismJS/prism/commit/e894fc89) ([#1716](https://github.com/PrismJS/prism/issues/1716)) [`217a6ea4`](https://github.com/PrismJS/prism/commit/217a6ea4)
	* Improve gulp error messages with pump ([#1741](https://github.com/PrismJS/prism/issues/1741)) [`671f4ca0`](https://github.com/PrismJS/prism/commit/671f4ca0)
	* Update gulp to version 4.0.0 ([#1779](https://github.com/PrismJS/prism/issues/1779)) [`06627f6a`](https://github.com/PrismJS/prism/commit/06627f6a)
	* gulp: Refactoring ([#1780](https://github.com/PrismJS/prism/issues/1780)) [`6c9fe257`](https://github.com/PrismJS/prism/commit/6c9fe257)
	* npm: Updated all dependencies ([#1742](https://github.com/PrismJS/prism/issues/1742)) [`9d908d5a`](https://github.com/PrismJS/prism/commit/9d908d5a)
	* Tests: Pretty-printed token stream ([#1801](https://github.com/PrismJS/prism/issues/1801)) [`9ea6d600`](https://github.com/PrismJS/prism/commit/9ea6d600)
	* Refactored tests ([#1795](https://github.com/PrismJS/prism/issues/1795)) [`832a9643`](https://github.com/PrismJS/prism/commit/832a9643)
	* Added issue templates ([#1805](https://github.com/PrismJS/prism/issues/1805)) [`dedb475f`](https://github.com/PrismJS/prism/commit/dedb475f)
	* npm: Fixed `test` script ([#1809](https://github.com/PrismJS/prism/issues/1809)) [`bc649dfa`](https://github.com/PrismJS/prism/commit/bc649dfa)
	* Add command to generate CHANGELOG [`212666d3`](https://github.com/PrismJS/prism/commit/212666d3)
	* Name in composer.json set to lowercase ([#1824](https://github.com/PrismJS/prism/issues/1824)) [`4f78f1d6`](https://github.com/PrismJS/prism/commit/4f78f1d6)
	* Added alias tests ([#1832](https://github.com/PrismJS/prism/issues/1832)) [`5c1a6fb2`](https://github.com/PrismJS/prism/commit/5c1a6fb2)
	* Travis: Fail when changed files are detected ([#1819](https://github.com/PrismJS/prism/issues/1819)) [`66b44e3b`](https://github.com/PrismJS/prism/commit/66b44e3b)
	* Tests: Additional checks for Prism functions ([#1803](https://github.com/PrismJS/prism/issues/1803)) [`c3e74ea3`](https://github.com/PrismJS/prism/commit/c3e74ea3)
	* Adjusted .npmignore ([#1834](https://github.com/PrismJS/prism/issues/1834)) [`29a30c62`](https://github.com/PrismJS/prism/commit/29a30c62)
* __Website__
	* Add Python triple-quoted strings "known failure" ([#1449](https://github.com/PrismJS/prism/issues/1449)) [`334c7bca`](https://github.com/PrismJS/prism/commit/334c7bca)
	* Updated index.html to fix broken instructions ([#1462](https://github.com/PrismJS/prism/issues/1462)) [`7418dfdd`](https://github.com/PrismJS/prism/commit/7418dfdd)
	* Improve download page typography ([#1484](https://github.com/PrismJS/prism/issues/1484)) [`b1c2f4df`](https://github.com/PrismJS/prism/commit/b1c2f4df)
	* Fixed peer dependencies in download page ([#1491](https://github.com/PrismJS/prism/issues/1491)) [`9d15ff6e`](https://github.com/PrismJS/prism/commit/9d15ff6e)
	* Fixed empty link in extending ([#1507](https://github.com/PrismJS/prism/issues/1507)) [`74916d48`](https://github.com/PrismJS/prism/commit/74916d48)
	* Display language aliases ([#1626](https://github.com/PrismJS/prism/issues/1626)) [`654b527b`](https://github.com/PrismJS/prism/commit/654b527b)
	* Clean up Previewers' page ([#1630](https://github.com/PrismJS/prism/issues/1630)) [`b0d1823c`](https://github.com/PrismJS/prism/commit/b0d1823c)
	* Updated website table of contents styles ([#1681](https://github.com/PrismJS/prism/issues/1681)) [`efdd96c3`](https://github.com/PrismJS/prism/commit/efdd96c3)
	* Added new third-party tutorial for using Prism in Gutenberg ([#1701](https://github.com/PrismJS/prism/issues/1701)) [`ff9ccbe5`](https://github.com/PrismJS/prism/commit/ff9ccbe5)
	* Remove dead tutorial ([#1702](https://github.com/PrismJS/prism/issues/1702)) [`e2d3bc7e`](https://github.com/PrismJS/prism/commit/e2d3bc7e)
	* Fix downloads page fetching from GitHub([#1684](https://github.com/PrismJS/prism/issues/1684)) [`dbd3555e`](https://github.com/PrismJS/prism/commit/dbd3555e)
	* Remove parentheses from download page ([#1627](https://github.com/PrismJS/prism/issues/1627)) [`2ce0666d`](https://github.com/PrismJS/prism/commit/2ce0666d)
	* Line Numbers plugin instructions clarifications ([#1719](https://github.com/PrismJS/prism/issues/1719)) [`00f4f04f`](https://github.com/PrismJS/prism/commit/00f4f04f)
	* Fixed Toolbar plugin example ([#1726](https://github.com/PrismJS/prism/issues/1726)) [`5311ca32`](https://github.com/PrismJS/prism/commit/5311ca32)
	* Test page: Show tokens option ([#1757](https://github.com/PrismJS/prism/issues/1757)) [`729cb28b`](https://github.com/PrismJS/prism/commit/729cb28b)
	* Some encouragement for visitors of PrismJS.com to request new languages ([#1760](https://github.com/PrismJS/prism/issues/1760)) [`ea769e0b`](https://github.com/PrismJS/prism/commit/ea769e0b)
	* Docs: Added missing parameter ([#1774](https://github.com/PrismJS/prism/issues/1774)) [`18f2921d`](https://github.com/PrismJS/prism/commit/18f2921d)
	* More persistent test page ([#1529](https://github.com/PrismJS/prism/issues/1529)) [`3100fa31`](https://github.com/PrismJS/prism/commit/3100fa31)
	* Added scripts directory ([#1781](https://github.com/PrismJS/prism/issues/1781)) [`439ea1ee`](https://github.com/PrismJS/prism/commit/439ea1ee)
	* Fixed download page ([#1811](https://github.com/PrismJS/prism/issues/1811)) [`77c57446`](https://github.com/PrismJS/prism/commit/77c57446)

## 1.15.0 (2018-06-16)

### New components

* __Template Tookit 2__ ([#1418](https://github.com/PrismJS/prism/issues/1418)) [[`e063992`](https://github.com/PrismJS/prism/commit/e063992)]
* __XQuery__ ([#1411](https://github.com/PrismJS/prism/issues/1411)) [[`e326cb0`](https://github.com/PrismJS/prism/commit/e326cb0)]
* __TAP__ ([#1430](https://github.com/PrismJS/prism/issues/1430)) [[`8c2b71f`](https://github.com/PrismJS/prism/commit/8c2b71f)]

### Updated components

* __HTTP__
	* Absolute path is a valid request uri ([#1388](https://github.com/PrismJS/prism/issues/1388)) [[`f6e81cb`](https://github.com/PrismJS/prism/commit/f6e81cb)]
* __Kotlin__
	* Add keywords of Kotlin and modify it's number pattern. ([#1389](https://github.com/PrismJS/prism/issues/1389)) [[`1bf73b0`](https://github.com/PrismJS/prism/commit/1bf73b0)]
	* Add `typealias` keyword ([#1437](https://github.com/PrismJS/prism/issues/1437)) [[`a21fdee`](https://github.com/PrismJS/prism/commit/a21fdee)]
* __JavaScript__
	* Improve Regexp pattern [[`5b043cf`](https://github.com/PrismJS/prism/commit/5b043cf)]
	* Add support for one level of nesting inside template strings. Fix [#1397](https://github.com/PrismJS/prism/issues/1397) [[`db2d0eb`](https://github.com/PrismJS/prism/commit/db2d0eb)]
* __Elixir__
	* Elixir: Fix attributes consuming punctuation. Fix [#1392](https://github.com/PrismJS/prism/issues/1392) [[`dac0485`](https://github.com/PrismJS/prism/commit/dac0485)]
* __Bash__
	* Change reserved keyword reference ([#1396](https://github.com/PrismJS/prism/issues/1396)) [[`b94f01f`](https://github.com/PrismJS/prism/commit/b94f01f)]
* __PowerShell__
	* Allow for one level of nesting in expressions inside strings. Fix [#1407](https://github.com/PrismJS/prism/issues/1407) [[`9272d6f`](https://github.com/PrismJS/prism/commit/9272d6f)]
* __JSX__
	* Allow for two levels of nesting inside JSX tags. Fix [#1408](https://github.com/PrismJS/prism/issues/1408) [[`f1cd7c5`](https://github.com/PrismJS/prism/commit/f1cd7c5)]
	* Add support for fragments short syntax. Fix [#1421](https://github.com/PrismJS/prism/issues/1421) [[`38ce121`](https://github.com/PrismJS/prism/commit/38ce121)]
* __Pascal__
	* Add `objectpascal` as an alias to `pascal` ([#1426](https://github.com/PrismJS/prism/issues/1426)) [[`a0bfc84`](https://github.com/PrismJS/prism/commit/a0bfc84)]
* __Swift__
	* Fix Swift 'protocol' keyword ([#1440](https://github.com/PrismJS/prism/issues/1440)) [[`081e318`](https://github.com/PrismJS/prism/commit/081e318)]

### Updated plugins

* __File Highlight__
	* Fix issue causing the Download button to show up on every code blocks. [[`cd22499`](https://github.com/PrismJS/prism/commit/cd22499)]
	* Simplify lang regex on File Highlight plugin ([#1399](https://github.com/PrismJS/prism/issues/1399)) [[`7bc9a4a`](https://github.com/PrismJS/prism/commit/7bc9a4a)]
* __Show Language__
	* Don't process language if block language not set ([#1410](https://github.com/PrismJS/prism/issues/1410)) [[`c111869`](https://github.com/PrismJS/prism/commit/c111869)]
* __Autoloader__
	* ASP.NET should require C# [[`fa328bb`](https://github.com/PrismJS/prism/commit/fa328bb)]
* __Line Numbers__
	* Make line-numbers styles more specific ([#1434](https://github.com/PrismJS/prism/issues/1434), [#1435](https://github.com/PrismJS/prism/issues/1435)) [[`9ee4f54`](https://github.com/PrismJS/prism/commit/9ee4f54)]

### Updated themes

* Add .token.class-name to rest of themes ([#1360](https://github.com/PrismJS/prism/issues/1360)) [[`f356dfe`](https://github.com/PrismJS/prism/commit/f356dfe)]

### Other changes

* __Website__
	* Site now loads over HTTPS!
	* Use HTTPS / canonical URLs ([#1390](https://github.com/PrismJS/prism/issues/1390)) [[`95146c8`](https://github.com/PrismJS/prism/commit/95146c8)]
	* Added Angular tutorial link [[`c436a7c`](https://github.com/PrismJS/prism/commit/c436a7c)]
	* Use rel="icon" instead of rel="shortcut icon" ([#1398](https://github.com/PrismJS/prism/issues/1398)) [[`d95f8fb`](https://github.com/PrismJS/prism/commit/d95f8fb)]
	* Fix Download page not handling multiple dependencies when from Redownload URL [[`c2ff248`](https://github.com/PrismJS/prism/commit/c2ff248)]
	* Update documentation for node & webpack usage [[`1e99e96`](https://github.com/PrismJS/prism/commit/1e99e96)]
* Handle optional dependencies in `loadLanguages()` ([#1417](https://github.com/PrismJS/prism/issues/1417)) [[`84935ac`](https://github.com/PrismJS/prism/commit/84935ac)]
* Add Chinese translation [[`f2b1964`](https://github.com/PrismJS/prism/commit/f2b1964)]

## 1.14.0 (2018-04-11)

### New components
* __GEDCOM__ ([#1385](https://github.com/PrismJS/prism/issues/1385)) [[`6e0b20a`](https://github.com/PrismJS/prism/commit/6e0b20a)]
* __Lisp__ ([#1297](https://github.com/PrismJS/prism/issues/1297)) [[`46468f8`](https://github.com/PrismJS/prism/commit/46468f8)]
* __Markup Templating__ ([#1367](https://github.com/PrismJS/prism/issues/1367)) [[`5f9c078`](https://github.com/PrismJS/prism/commit/5f9c078)]
* __Soy__ ([#1387](https://github.com/PrismJS/prism/issues/1387)) [[`b4509bf`](https://github.com/PrismJS/prism/commit/b4509bf)]
* __Velocity__ ([#1378](https://github.com/PrismJS/prism/issues/1378)) [[`5a524f7`](https://github.com/PrismJS/prism/commit/5a524f7)]
* __Visual Basic__ ([#1382](https://github.com/PrismJS/prism/issues/1382)) [[`c673ec2`](https://github.com/PrismJS/prism/commit/c673ec2)]
* __WebAssembly__ ([#1386](https://github.com/PrismJS/prism/issues/1386)) [[`c28d8c5`](https://github.com/PrismJS/prism/commit/c28d8c5)]

### Updated components
* __Bash__:
	* Add curl to the list of common functions. Close [#1160](https://github.com/PrismJS/prism/issues/1160) [[`1bfc084`](https://github.com/PrismJS/prism/commit/1bfc084)]
* __C-like__:
	* Make single-line comments greedy. Fix [#1337](https://github.com/PrismJS/prism/issues/1337). Make sure [#1340](https://github.com/PrismJS/prism/issues/1340) stays fixed. [[`571f2c5`](https://github.com/PrismJS/prism/commit/571f2c5)]
* __C#__:
	* More generic class-name highlighting. Fix [#1365](https://github.com/PrismJS/prism/issues/1365) [[`a6837d2`](https://github.com/PrismJS/prism/commit/a6837d2)]
	* More specific class-name highlighting. Fix [#1371](https://github.com/PrismJS/prism/issues/1371) [[`0a95f69`](https://github.com/PrismJS/prism/commit/0a95f69)]
* __Eiffel__:
	* Fix verbatim strings. Fix [#1379](https://github.com/PrismJS/prism/issues/1379) [[`04df41b`](https://github.com/PrismJS/prism/commit/04df41b)]
* __Elixir__
	* Make regexps greedy, remove comment hacks. Update known failures and tests. [[`e93d61f`](https://github.com/PrismJS/prism/commit/e93d61f)]
* __ERB__:
	* Make highlighting work properly in NodeJS ([#1367](https://github.com/PrismJS/prism/issues/1367)) [[`5f9c078`](https://github.com/PrismJS/prism/commit/5f9c078)]
* __Fortran__:
	* Make single-line comments greedy. Update known failures and tests. [[`c083b78`](https://github.com/PrismJS/prism/commit/c083b78)]
* __Handlebars__:
	* Make highlighting work properly in NodeJS ([#1367](https://github.com/PrismJS/prism/issues/1367)) [[`5f9c078`](https://github.com/PrismJS/prism/commit/5f9c078)]
* __Java__:
	* Add support for generics. Fix [#1351](https://github.com/PrismJS/prism/issues/1351) [[`a5cf302`](https://github.com/PrismJS/prism/commit/a5cf302)]
* __JavaScript__:
	* Add support for constants. Fix [#1348](https://github.com/PrismJS/prism/issues/1348) [[`9084481`](https://github.com/PrismJS/prism/commit/9084481)]
	* Improve Regex matching [[`172d351`](https://github.com/PrismJS/prism/commit/172d351)]
* __JSX__:
	* Fix highlighting of empty objects. Fix [#1364](https://github.com/PrismJS/prism/issues/1364) [[`b26bbb8`](https://github.com/PrismJS/prism/commit/b26bbb8)]
* __Monkey__:
	* Make comments greedy. Update known failures and tests. [[`d7b2b43`](https://github.com/PrismJS/prism/commit/d7b2b43)]
* __PHP__:
	* Make highlighting work properly in NodeJS ([#1367](https://github.com/PrismJS/prism/issues/1367)) [[`5f9c078`](https://github.com/PrismJS/prism/commit/5f9c078)]
* __Puppet__:
	* Make heredoc, comments, regexps and strings greedy. Update known failures and tests. [[`0c139d1`](https://github.com/PrismJS/prism/commit/0c139d1)]
* __Q__:
	* Make comments greedy. Update known failures and tests. [[`a0f5081`](https://github.com/PrismJS/prism/commit/a0f5081)]
* __Ruby__:
	* Make multi-line comments greedy, remove single-line comment hack. Update known failures and tests. [[`b0e34fb`](https://github.com/PrismJS/prism/commit/b0e34fb)]
* __SQL__:
	* Add missing keywords. Fix [#1374](https://github.com/PrismJS/prism/issues/1374) [[`238b195`](https://github.com/PrismJS/prism/commit/238b195)]

### Updated plugins
* __Command Line__:
	* Command Line: Allow specifying output prefix using data-filter-output attribute. ([#856](https://github.com/PrismJS/prism/issues/856)) [[`094d546`](https://github.com/PrismJS/prism/commit/094d546)]
* __File Highlight__:
	* Add option to provide a download button, when used with the Toolbar plugin. Fix [#1030](https://github.com/PrismJS/prism/issues/1030) [[`9f22952`](https://github.com/PrismJS/prism/commit/9f22952)]

### Updated themes
* __Default__:
	* Reach AA contrast ratio level ([#1296](https://github.com/PrismJS/prism/issues/1296)) [[`8aea939`](https://github.com/PrismJS/prism/commit/8aea939)]

### Other changes
* Website: Remove broken third-party tutorials from homepage [[`0efd6e1`](https://github.com/PrismJS/prism/commit/0efd6e1)]
* Docs: Mention `loadLanguages()` function on homepage in the nodeJS section. Close [#972](https://github.com/PrismJS/prism/issues/972), close [#593](https://github.com/PrismJS/prism/issues/593) [[`4a14d20`](https://github.com/PrismJS/prism/commit/4a14d20)]
* Core: Greedy patterns should always be matched against the full string. Fix [#1355](https://github.com/PrismJS/prism/issues/1355) [[`294efaa`](https://github.com/PrismJS/prism/commit/294efaa)]
* Crystal: Update known failures. [[`e1d2d42`](https://github.com/PrismJS/prism/commit/e1d2d42)]
* D: Update known failures and tests. [[`13d9991`](https://github.com/PrismJS/prism/commit/13d9991)]
* Markdown: Update known failures. [[`5b6c76d`](https://github.com/PrismJS/prism/commit/5b6c76d)]
* Matlab: Update known failures. [[`259b6fc`](https://github.com/PrismJS/prism/commit/259b6fc)]
* Website: Remove non-existent anchor to failures. Reword on homepage to make is less misleading. [[`8c0911a`](https://github.com/PrismJS/prism/commit/8c0911a)]
* Website: Add link to Keep Markup plugin in FAQ [[`e8cb6d4`](https://github.com/PrismJS/prism/commit/e8cb6d4)]
* Test suite: Memory leak in vm.runInNewContext() seems fixed. Revert [[`9a4b6fa`](https://github.com/PrismJS/prism/commit/9a4b6fa)] to drastically improve tests execution time. [[`9bceece`](https://github.com/PrismJS/prism/commit/9bceece), [`7c7602b`](https://github.com/PrismJS/prism/commit/7c7602b)]
* Gulp: Don't minify `components/index.js` [[`689227b`](https://github.com/PrismJS/prism/commit/689227b)]
* Website: Fix theme selection on Download page, when theme is in query string or hash. [[`b4d3063`](https://github.com/PrismJS/prism/commit/b4d3063)]
* Update JSPM config to also include unminified components. Close [#995](https://github.com/PrismJS/prism/issues/995) [[`218f160`](https://github.com/PrismJS/prism/commit/218f160)]
* Core: Fix support for language alias containing dash `-` [[`659ea31`](https://github.com/PrismJS/prism/commit/659ea31)]

## 1.13.0 (2018-03-21)

### New components
* __ERB__ [[`e6213ac`](https://github.com/PrismJS/prism/commit/e6213ac)]
* __PL/SQL__ ([#1338](https://github.com/PrismJS/prism/issues/1338)) [[`3599e6a`](https://github.com/PrismJS/prism/commit/3599e6a)]

### Updated components
* __JSX__:
	* Add support for plain text inside tags ([#1357](https://github.com/PrismJS/prism/issues/1357)) [[`2b8321d`](https://github.com/PrismJS/prism/commit/2b8321d)]
* __Markup__:
	* Make tags greedy. Fix [#1356](https://github.com/PrismJS/prism/issues/1356) [[`af834be`](https://github.com/PrismJS/prism/commit/af834be)]
* __Powershell__:
	* Add lookbehind to fix function interpolation inside strings. Fix [#1361](https://github.com/PrismJS/prism/issues/1361) [[`d2c026e`](https://github.com/PrismJS/prism/commit/d2c026e)]
* __Rust__:
	* Improve char pattern so that lifetime annotations are matched better. Fix [#1353](https://github.com/PrismJS/prism/issues/1353) [[`efdccbf`](https://github.com/PrismJS/prism/commit/efdccbf)]

### Updated themes
* __Default__:
	* Add color for class names [[`8572474`](https://github.com/PrismJS/prism/commit/8572474)]
* __Coy__:
	* Inherit pre's height on code, so it does not break on Download page. [[`c6c7fd1`](https://github.com/PrismJS/prism/commit/c6c7fd1)]

### Other changes
* Website: Auto-generate example headers [[`c3ed5b5`](https://github.com/PrismJS/prism/commit/c3ed5b5)]
* Core: Allow cloning of circular structures. ([#1345](https://github.com/PrismJS/prism/issues/1345)) [[`f90d555`](https://github.com/PrismJS/prism/commit/f90d555)]
* Core: Generate components.js from components.json and make it exportable to nodeJS. ([#1354](https://github.com/PrismJS/prism/issues/1354)) [[`ba60df0`](https://github.com/PrismJS/prism/commit/ba60df0)]
* Website: Improve appearance of theme selector [[`0460cad`](https://github.com/PrismJS/prism/commit/0460cad)]
* Website: Check stored theme by default + link both theme selectors together. Close [#1038](https://github.com/PrismJS/prism/issues/1038) [[`212dd4e`](https://github.com/PrismJS/prism/commit/212dd4e)]
* Tests: Use the new components.js file directly [[`0e1a8b7`](https://github.com/PrismJS/prism/commit/0e1a8b7)]
* Update .npmignore Close [#1274](https://github.com/PrismJS/prism/issues/1274) [[`a52319a`](https://github.com/PrismJS/prism/commit/a52319a)]
* Add a loadLanguages() function for easy component loading on NodeJS ([#1359](https://github.com/PrismJS/prism/issues/1359)) [[`a5331a6`](https://github.com/PrismJS/prism/commit/a5331a6)]

## 1.12.2 (2018-03-08)

### Other changes
* Test against NodeJS 4, 6, 8 and 9 ([#1329](https://github.com/PrismJS/prism/issues/1329)) [[`97b7d0a`](https://github.com/PrismJS/prism/commit/97b7d0a)]
* Stop testing against NodeJS 0.10 and 0.12 [[`df01b1b`](https://github.com/PrismJS/prism/commit/df01b1b)]

## 1.12.1 (2018-03-08)

### Updated components
* __C-like__:
	* Revert [[`b98e5b9`](https://github.com/PrismJS/prism/commit/b98e5b9)] to fix [#1340](https://github.com/PrismJS/prism/issues/1340). Reopened [#1337](https://github.com/PrismJS/prism/issues/1337). [[`cebacdf`](https://github.com/PrismJS/prism/commit/cebacdf)]
* __JSX__:
	* Allow for one level of nested curly braces inside tag attribute value. Fix [#1335](https://github.com/PrismJS/prism/issues/1335) [[`05bf67d`](https://github.com/PrismJS/prism/commit/05bf67d)]
* __Ruby__:
	*  Ensure module syntax is not confused with symbols. Fix [#1336](https://github.com/PrismJS/prism/issues/1336) [[`31a2a69`](https://github.com/PrismJS/prism/commit/31a2a69)]

## 1.12.0 (2018-03-07)

### New components
* __ARFF__ ([#1327](https://github.com/PrismJS/prism/issues/1327)) [[`0bc98ac`](https://github.com/PrismJS/prism/commit/0bc98ac)]
* __Clojure__ ([#1311](https://github.com/PrismJS/prism/issues/1311)) [[`8b4d3bd`](https://github.com/PrismJS/prism/commit/8b4d3bd)]
* __Liquid__ ([#1326](https://github.com/PrismJS/prism/issues/1326)) [[`f0b2c9e`](https://github.com/PrismJS/prism/commit/f0b2c9e)]

### Updated components
* __Bash__:
	* Add shell as an alias ([#1321](https://github.com/PrismJS/prism/issues/1321)) [[`67e16a2`](https://github.com/PrismJS/prism/commit/67e16a2)]
	* Add support for quoted command substitution. Fix [#1287](https://github.com/PrismJS/prism/issues/1287) [[`63fc215`](https://github.com/PrismJS/prism/commit/63fc215)]
* __C#__:
	* Add "dotnet" alias. [[`405867c`](https://github.com/PrismJS/prism/commit/405867c)]
* __C-like__:
	* Change order of comment patterns and make multi-line one greedy. Fix [#1337](https://github.com/PrismJS/prism/issues/1337) [[`b98e5b9`](https://github.com/PrismJS/prism/commit/b98e5b9)]
* __NSIS__:
	* Add support for NSIS 3.03 ([#1288](https://github.com/PrismJS/prism/issues/1288)) [[`bd1e98b`](https://github.com/PrismJS/prism/commit/bd1e98b)]
	* Add missing NSIS commands ([#1289](https://github.com/PrismJS/prism/issues/1289)) [[`ad2948f`](https://github.com/PrismJS/prism/commit/ad2948f)]
* __PHP__:
	* Add support for string interpolation inside double-quoted strings. Fix [#1146](https://github.com/PrismJS/prism/issues/1146) [[`9f1f8d6`](https://github.com/PrismJS/prism/commit/9f1f8d6)]
	* Add support for Heredoc and Nowdoc strings [[`5d7223c`](https://github.com/PrismJS/prism/commit/5d7223c)]
	* Fix shell-comment failure now that strings are greedy [[`ad25d22`](https://github.com/PrismJS/prism/commit/ad25d22)]
* __PowerShell__:
	* Add support for two levels of nested brackets inside namespace pattern. Fixes [#1317](https://github.com/PrismJS/prism/issues/1317) [[`3bc3e9c`](https://github.com/PrismJS/prism/commit/3bc3e9c)]
* __Ruby__:
	* Add keywords "protected", "private" and "public" [[`4593837`](https://github.com/PrismJS/prism/commit/4593837)]
* __Rust__:
	* Add support for lifetime-annotation and => operator. Fix [#1339](https://github.com/PrismJS/prism/issues/1339) [[`926f6f8`](https://github.com/PrismJS/prism/commit/926f6f8)]
* __Scheme__:
	* Don't highlight first number of a list as a function. Fix [#1331](https://github.com/PrismJS/prism/issues/1331) [[`51bff80`](https://github.com/PrismJS/prism/commit/51bff80)]
* __SQL__:
	* Add missing keywords and functions, fix numbers [[`de29d4a`](https://github.com/PrismJS/prism/commit/de29d4a)]

### Updated plugins
* __Autolinker__:
	* Allow more chars in query string and hash to match more URLs. Fix [#1142](https://github.com/PrismJS/prism/issues/1142) [[`109bd6f`](https://github.com/PrismJS/prism/commit/109bd6f)]
* __Copy to Clipboard__:
	* Bump ClipboardJS to 2.0.0 and remove hack ([#1314](https://github.com/PrismJS/prism/issues/1314)) [[`e9f410e`](https://github.com/PrismJS/prism/commit/e9f410e)]
* __Toolbar__:
	* Prevent scrolling toolbar with content ([#1305](https://github.com/PrismJS/prism/issues/1305), [#1314](https://github.com/PrismJS/prism/issues/1314)) [[`84eeb89`](https://github.com/PrismJS/prism/commit/84eeb89)]
* __Unescaped Markup__:
	* Use msMatchesSelector for IE11 and below. Fix [#1302](https://github.com/PrismJS/prism/issues/1302) [[`c246c1a`](https://github.com/PrismJS/prism/commit/c246c1a)]
* __WebPlatform Docs__:
	* WebPlatform Docs plugin: Fix links. Fixes [#1290](https://github.com/PrismJS/prism/issues/1290) [[`7a9dbe0`](https://github.com/PrismJS/prism/commit/7a9dbe0)]

### Other changes
* Fix Autoloader's demo page [[`3dddac9`](https://github.com/PrismJS/prism/commit/3dddac9)]
* Download page: Use hash instead of query-string for redownload URL. Fix [#1263](https://github.com/PrismJS/prism/issues/1263) [[`b03c02a`](https://github.com/PrismJS/prism/commit/b03c02a)]
* Core: Don't thow an error if lookbehing is used without anything matching. [[`e0cd47f`](https://github.com/PrismJS/prism/commit/e0cd47f)]
* Docs: Fix link to the `<code>` element specification in HTML5 [[`a84263f`](https://github.com/PrismJS/prism/commit/a84263f)]
* Docs: Mention support for `lang-xxxx` class. Close [#1312](https://github.com/PrismJS/prism/issues/1312) [[`a9e76db`](https://github.com/PrismJS/prism/commit/a9e76db)]
* Docs: Add note on `async` parameter to clarify the requirement of using a single bundled file. Closes [#1249](https://github.com/PrismJS/prism/issues/1249) [[`eba0235`](https://github.com/PrismJS/prism/commit/eba0235)]

## 1.11.0 (2018-02-05)

### New components
* __Content-Security-Policy (CSP)__ ([#1275](https://github.com/PrismJS/prism/issues/1275)) [[`b08cae5`](https://github.com/PrismJS/prism/commit/b08cae5)]
* __HTTP Public-Key-Pins (HPKP)__ ([#1275](https://github.com/PrismJS/prism/issues/1275)) [[`b08cae5`](https://github.com/PrismJS/prism/commit/b08cae5)]
* __HTTP String-Transport-Security (HSTS)__ ([#1275](https://github.com/PrismJS/prism/issues/1275)) [[`b08cae5`](https://github.com/PrismJS/prism/commit/b08cae5)]
* __React TSX__ ([#1280](https://github.com/PrismJS/prism/issues/1280)) [[`fbe82b8`](https://github.com/PrismJS/prism/commit/fbe82b8)]

### Updated components
* __C++__:
	* Add C++ platform-independent types ([#1271](https://github.com/PrismJS/prism/issues/1271)) [[`3da238f`](https://github.com/PrismJS/prism/commit/3da238f)]
* __TypeScript__:
	* Improve typescript with builtins ([#1277](https://github.com/PrismJS/prism/issues/1277)) [[`5de1b1f`](https://github.com/PrismJS/prism/commit/5de1b1f)]

### Other changes
* Fix passing of non-enumerable Error properties from the child test runner ([#1276](https://github.com/PrismJS/prism/issues/1276)) [[`38df653`](https://github.com/PrismJS/prism/commit/38df653)]

## 1.10.0 (2018-01-17)

### New components
* __6502 Assembly__ ([#1245](https://github.com/PrismJS/prism/issues/1245)) [[`2ece18b`](https://github.com/PrismJS/prism/commit/2ece18b)]
* __Elm__ ([#1174](https://github.com/PrismJS/prism/issues/1174)) [[`d6da70e`](https://github.com/PrismJS/prism/commit/d6da70e)]
* __IchigoJam BASIC__ ([#1246](https://github.com/PrismJS/prism/issues/1246)) [[`cf840be`](https://github.com/PrismJS/prism/commit/cf840be)]
* __Io__ ([#1251](https://github.com/PrismJS/prism/issues/1251)) [[`84ed3ed`](https://github.com/PrismJS/prism/commit/84ed3ed)]

### Updated components
* __BASIC__:
	* Make strings greedy [[`60114d0`](https://github.com/PrismJS/prism/commit/60114d0)]
* __C++__:
	* Add C++11 raw string feature ([#1254](https://github.com/PrismJS/prism/issues/1254)) [[`71595be`](https://github.com/PrismJS/prism/commit/71595be)]

### Updated plugins
* __Autoloader__:
	* Add support for `data-autoloader-path` ([#1242](https://github.com/PrismJS/prism/issues/1242)) [[`39360d6`](https://github.com/PrismJS/prism/commit/39360d6)]
* __Previewers__:
	* New plugin combining previous plugins Previewer: Base, Previewer: Angle, Previewer: Color, Previewer: Easing, Previewer: Gradient and Previewer: Time. ([#1244](https://github.com/PrismJS/prism/issues/1244)) [[`28e4b4c`](https://github.com/PrismJS/prism/commit/28e4b4c)]
* __Unescaped Markup__:
	* Make it work with any language ([#1265](https://github.com/PrismJS/prism/issues/1265)) [[`7bcdae7`](https://github.com/PrismJS/prism/commit/7bcdae7)]

### Other changes
* Add attribute `style` in `package.json` ([#1256](https://github.com/PrismJS/prism/issues/1256)) [[`a9b6785`](https://github.com/PrismJS/prism/commit/a9b6785)]

## 1.9.0 (2017-12-06)

### New components
* __Flow__ [[`d27b70d`](https://github.com/PrismJS/prism/commit/d27b70d)]

### Updated components
* __CSS__:
	* Unicode characters in CSS properties ([#1227](https://github.com/PrismJS/prism/issues/1227)) [[`f234ea4`](https://github.com/PrismJS/prism/commit/f234ea4)]
* __JSX__:
	* JSX: Improve highlighting support. Fix [#1235](https://github.com/PrismJS/prism/issues/1235) and [#1236](https://github.com/PrismJS/prism/issues/1236) [[`f41c5cd`](https://github.com/PrismJS/prism/commit/f41c5cd)]
* __Markup__:
	* Make CSS and JS inclusions in Markup greedy. Fix [#1240](https://github.com/PrismJS/prism/issues/1240) [[`7dc1e45`](https://github.com/PrismJS/prism/commit/7dc1e45)]
* __PHP__:
	* Add support for multi-line strings. Fix [#1233](https://github.com/PrismJS/prism/issues/1233) [[`9a542a0`](https://github.com/PrismJS/prism/commit/9a542a0)]

### Updated plugins
* __Copy to clipboard__:
	* Fix test for native Clipboard. Fix [#1241](https://github.com/PrismJS/prism/issues/1241) [[`e7b5e82`](https://github.com/PrismJS/prism/commit/e7b5e82)]
	* Copy to clipboard: Update to v1.7.1. Fix [#1220](https://github.com/PrismJS/prism/issues/1220) [[`a1b85e3`](https://github.com/PrismJS/prism/commit/a1b85e3), [`af50e44`](https://github.com/PrismJS/prism/commit/af50e44)]
* __Line highlight__:
	* Fixes to compatibility of line number and line higlight plugins ([#1194](https://github.com/PrismJS/prism/issues/1194)) [[`e63058f`](https://github.com/PrismJS/prism/commit/e63058f), [`3842a91`](https://github.com/PrismJS/prism/commit/3842a91)]
* __Unescaped Markup__:
	* Fix ambiguity in documentation by improving examples. Fix [#1197](https://github.com/PrismJS/prism/issues/1197) [[`924784a`](https://github.com/PrismJS/prism/commit/924784a)]

### Other changes
* Allow any element being root instead of document. ([#1230](https://github.com/PrismJS/prism/issues/1230)) [[`69f2e2c`](https://github.com/PrismJS/prism/commit/69f2e2c), [`6e50d44`](https://github.com/PrismJS/prism/commit/6e50d44)]
* Coy Theme: The 'height' element makes code blocks the height of the browser canvas. ([#1224](https://github.com/PrismJS/prism/issues/1224)) [[`ac219d7`](https://github.com/PrismJS/prism/commit/ac219d7)]
* Download page: Fix implicitly declared variable [[`f986551`](https://github.com/PrismJS/prism/commit/f986551)]
* Download page: Add version number at the beginning of the generated files. Fix [#788](https://github.com/PrismJS/prism/issues/788) [[`928790d`](https://github.com/PrismJS/prism/commit/928790d)]

## 1.8.4 (2017-11-05)

### Updated components

* __ABAP__:
	* Regexp optimisation [[`e7b411e`](https://github.com/PrismJS/prism/commit/e7b411e)]
* __ActionScript__:
	* Fix XML regex + optimise [[`75d00d7`](https://github.com/PrismJS/prism/commit/75d00d7)]
* __Ada__:
	* Regexp simplification [[`e881fe3`](https://github.com/PrismJS/prism/commit/e881fe3)]
* __Apacheconf__:
	* Regexp optimisation [[`a065e61`](https://github.com/PrismJS/prism/commit/a065e61)]
* __APL__:
	* Regexp simplification [[`33297c4`](https://github.com/PrismJS/prism/commit/33297c4)]
* __AppleScript__:
	* Regexp optimisation [[`d879f36`](https://github.com/PrismJS/prism/commit/d879f36)]
* __Arduino__:
	* Don't use captures if not needed [[`16b338f`](https://github.com/PrismJS/prism/commit/16b338f)]
* __ASP.NET__:
	* Regexp optimisation [[`438926c`](https://github.com/PrismJS/prism/commit/438926c)]
* __AutoHotkey__:
	* Regexp simplification + don't use captures if not needed [[`5edfd2f`](https://github.com/PrismJS/prism/commit/5edfd2f)]
* __Bash__:
	* Regexp optimisation and simplification [[`75b9b29`](https://github.com/PrismJS/prism/commit/75b9b29)]
* __Bro__:
	* Regexp simplification + don't use captures if not needed [[`d4b9003`](https://github.com/PrismJS/prism/commit/d4b9003)]
* __C__:
	* Regexp optimisation + don't use captures if not needed [[`f61d487`](https://github.com/PrismJS/prism/commit/f61d487)]
* __C++__:
	* Fix operator regexp + regexp simplification + don't use captures if not needed [[`ffeb26e`](https://github.com/PrismJS/prism/commit/ffeb26e)]
* __C#__:
	* Remove duplicates in keywords + regexp optimisation + don't use captures if not needed [[`d28d178`](https://github.com/PrismJS/prism/commit/d28d178)]
* __C-like__:
	* Regexp simplification + don't use captures if not needed [[`918e0ff`](https://github.com/PrismJS/prism/commit/918e0ff)]
* __CoffeeScript__:
	* Regexp optimisation + don't use captures if not needed [[`5895978`](https://github.com/PrismJS/prism/commit/5895978)]
* __Crystal__:
	* Remove trailing comma [[`16979a3`](https://github.com/PrismJS/prism/commit/16979a3)]
* __CSS__:
	* Regexp simplification + don't use captures if not needed + handle multi-line style attributes [[`43d9f36`](https://github.com/PrismJS/prism/commit/43d9f36)]
* __CSS Extras__:
	* Regexp simplification [[`134ed70`](https://github.com/PrismJS/prism/commit/134ed70)]
* __D__:
	* Regexp optimisation [[`fbe39c9`](https://github.com/PrismJS/prism/commit/fbe39c9)]
* __Dart__:
	* Regexp optimisation [[`f24e919`](https://github.com/PrismJS/prism/commit/f24e919)]
* __Django__:
	* Regexp optimisation [[`a95c51d`](https://github.com/PrismJS/prism/commit/a95c51d)]
* __Docker__:
	* Regexp optimisation [[`27f99ff`](https://github.com/PrismJS/prism/commit/27f99ff)]
* __Eiffel__:
	* Regexp optimisation [[`b7cdea2`](https://github.com/PrismJS/prism/commit/b7cdea2)]
* __Elixir__:
	* Regexp optimisation + uniform behavior between ~r and ~s [[`5d12e80`](https://github.com/PrismJS/prism/commit/5d12e80)]
* __Erlang__:
	* Regexp optimisation [[`7547f83`](https://github.com/PrismJS/prism/commit/7547f83)]
* __F#__:
	* Regexp optimisation + don't use captures if not needed [[`7753fc4`](https://github.com/PrismJS/prism/commit/7753fc4)]
* __Gherkin__:
	* Regexp optimisation + don't use captures if not needed + added explanation comment on table-body regexp [[`f26197a`](https://github.com/PrismJS/prism/commit/f26197a)]
* __Git__:
	* Regexp optimisation [[`b9483b9`](https://github.com/PrismJS/prism/commit/b9483b9)]
* __GLSL__:
	* Regexp optimisation [[`e66d21b`](https://github.com/PrismJS/prism/commit/e66d21b)]
* __Go__:
	* Regexp optimisation + don't use captures if not needed [[`88caabb`](https://github.com/PrismJS/prism/commit/88caabb)]
* __GraphQL__:
	* Regexp optimisation and simplification [[`2474f06`](https://github.com/PrismJS/prism/commit/2474f06)]
* __Groovy__:
	* Regexp optimisation + don't use captures if not needed [[`e74e00c`](https://github.com/PrismJS/prism/commit/e74e00c)]
* __Haml__:
	* Regexp optimisation + don't use captures if not needed + fix typo in comment [[`23e3b43`](https://github.com/PrismJS/prism/commit/23e3b43)]
* __Handlebars__:
	* Regexp optimisation + don't use captures if not needed [[`09dbfce`](https://github.com/PrismJS/prism/commit/09dbfce)]
* __Haskell__:
	* Regexp simplification + don't use captures if not needed [[`f11390a`](https://github.com/PrismJS/prism/commit/f11390a)]
* __HTTP__:
	* Regexp simplification + don't use captures if not needed [[`37ef24e`](https://github.com/PrismJS/prism/commit/37ef24e)]
* __Icon__:
	* Regexp optimisation [[`9cf64a0`](https://github.com/PrismJS/prism/commit/9cf64a0)]
* __J__:
	* Regexp simplification [[`de15150`](https://github.com/PrismJS/prism/commit/de15150)]
* __Java__:
	* Don't use captures if not needed [[`96b35c8`](https://github.com/PrismJS/prism/commit/96b35c8)]
* __JavaScript__:
	* Regexp optimisation + don't use captures if not needed [[`93d4002`](https://github.com/PrismJS/prism/commit/93d4002)]
* __Jolie__:
	* Regexp optimisation + don't use captures if not needed + remove duplicates in keywords [[`a491f9e`](https://github.com/PrismJS/prism/commit/a491f9e)]
* __JSON__:
	* Make strings greedy, remove negative look-ahead for ":". Fix [#1204](https://github.com/PrismJS/prism/issues/1204) [[`98acd2d`](https://github.com/PrismJS/prism/commit/98acd2d)]
	* Regexp optimisation + don't use captures if not needed [[`8fc1b03`](https://github.com/PrismJS/prism/commit/8fc1b03)]
* __JSX__:
	* Regexp optimisation + handle spread operator as a whole [[`28de4e2`](https://github.com/PrismJS/prism/commit/28de4e2)]
* __Julia__:
	* Regexp optimisation and simplification [[`12684c0`](https://github.com/PrismJS/prism/commit/12684c0)]
* __Keyman__:
	* Regexp optimisation + don't use captures if not needed [[`9726087`](https://github.com/PrismJS/prism/commit/9726087)]
* __Kotlin__:
	* Regexp simplification [[`12ff8dc`](https://github.com/PrismJS/prism/commit/12ff8dc)]
* __LaTeX__:
	* Regexp optimisation and simplification [[`aa426b0`](https://github.com/PrismJS/prism/commit/aa426b0)]
* __LiveScript__:
	* Make interpolated strings greedy + fix variable and identifier regexps [[`c581049`](https://github.com/PrismJS/prism/commit/c581049)]
* __LOLCODE__:
	* Don't use captures if not needed [[`52903af`](https://github.com/PrismJS/prism/commit/52903af)]
* __Makefile__:
	* Regexp optimisation [[`20ae2e5`](https://github.com/PrismJS/prism/commit/20ae2e5)]
* __Markdown__:
	* Don't use captures if not needed [[`f489a1e`](https://github.com/PrismJS/prism/commit/f489a1e)]
* __Markup__:
	* Regexp optimisation + fix punctuation inside attr-value [[`ea380c6`](https://github.com/PrismJS/prism/commit/ea380c6)]
* __MATLAB__:
	* Make strings greedy + handle line feeds better [[`4cd4f01`](https://github.com/PrismJS/prism/commit/4cd4f01)]
* __Monkey__:
	* Don't use captures if not needed [[`7f47140`](https://github.com/PrismJS/prism/commit/7f47140)]
* __N4JS__:
	* Don't use captures if not needed [[`2d3f9df`](https://github.com/PrismJS/prism/commit/2d3f9df)]
* __NASM__:
	* Regexp optimisation and simplification + don't use captures if not needed [[`9937428`](https://github.com/PrismJS/prism/commit/9937428)]
* __nginx__:
	* Remove trailing comma + remove duplicates in keywords [[`c6e7195`](https://github.com/PrismJS/prism/commit/c6e7195)]
* __NSIS__:
	* Regexp optimisation + don't use captures if not needed [[`beeb107`](https://github.com/PrismJS/prism/commit/beeb107)]
* __Objective-C__:
	* Don't use captures if not needed [[`9be0f88`](https://github.com/PrismJS/prism/commit/9be0f88)]
* __OCaml__:
	* Regexp simplification [[`5f5f38c`](https://github.com/PrismJS/prism/commit/5f5f38c)]
* __OpenCL__:
	* Don't use captures if not needed [[`5e70f1d`](https://github.com/PrismJS/prism/commit/5e70f1d)]
* __Oz__:
	* Fix atom regexp [[`9320e92`](https://github.com/PrismJS/prism/commit/9320e92)]
* __PARI/GP__:
	* Regexp optimisation [[`2c7b59b`](https://github.com/PrismJS/prism/commit/2c7b59b)]
* __Parser__:
	* Regexp simplification [[`569d511`](https://github.com/PrismJS/prism/commit/569d511)]
* __Perl__:
	* Regexp optimisation and simplification + don't use captures if not needed [[`0fe4cf6`](https://github.com/PrismJS/prism/commit/0fe4cf6)]
* __PHP__:
	* Don't use captures if not needed Golmote [[`5235f18`](https://github.com/PrismJS/prism/commit/5235f18)]
* __PHP Extras__:
	* Add word boundary after global keywords + don't use captures if not needed [[`9049a2a`](https://github.com/PrismJS/prism/commit/9049a2a)]
* __PowerShell__:
	* Regexp optimisation + don't use captures if not needed [[`0d05957`](https://github.com/PrismJS/prism/commit/0d05957)]
* __Processing__:
	* Regexp simplification [[`8110d38`](https://github.com/PrismJS/prism/commit/8110d38)]
* __.properties__:
	* Regexp optimisation [[`678b621`](https://github.com/PrismJS/prism/commit/678b621)]
* __Protocol Buffers__:
	* Don't use captures if not needed [[`3e256d8`](https://github.com/PrismJS/prism/commit/3e256d8)]
* __Pug__:
	* Don't use captures if not needed [[`76dc925`](https://github.com/PrismJS/prism/commit/76dc925)]
* __Pure__:
	* Make inline-lang greedy [[`92318b0`](https://github.com/PrismJS/prism/commit/92318b0)]
* __Python__:
	* Add Python builtin function highlighting ([#1205](https://github.com/PrismJS/prism/issues/1205)) [[`2169c99`](https://github.com/PrismJS/prism/commit/2169c99)]
	* Python: Add highlighting to functions with space between name and parentheses ([#1207](https://github.com/PrismJS/prism/issues/1207)) [[`3badd8a`](https://github.com/PrismJS/prism/commit/3badd8a)]
	* Make triple-quoted strings greedy + regexp optimisation and simplification [[`f09f9f5`](https://github.com/PrismJS/prism/commit/f09f9f5)]
* __Qore__:
	* Regexp simplification [[`69459f0`](https://github.com/PrismJS/prism/commit/69459f0)]
* __R__:
	* Regexp optimisation [[`06a9da4`](https://github.com/PrismJS/prism/commit/06a9da4)]
* __Reason__:
	* Regexp optimisation + don't use capture if not needed [[`19d79b4`](https://github.com/PrismJS/prism/commit/19d79b4)]
* __Ren'py__:
	* Make strings greedy + don't use captures if not needed [[`91d84d9`](https://github.com/PrismJS/prism/commit/91d84d9)]
* __reST__:
	* Regexp simplification + don't use captures if not needed [[`1a8b3e9`](https://github.com/PrismJS/prism/commit/1a8b3e9)]
* __Rip__:
	* Regexp optimisation [[`d7f0ee8`](https://github.com/PrismJS/prism/commit/d7f0ee8)]
* __Ruby__:
	* Regexp optimisation and simplification + don't use captures if not needed [[`4902ed4`](https://github.com/PrismJS/prism/commit/4902ed4)]
* __Rust__:
	* Regexp optimisation and simplification + don't use captures if not needed [[`cc9d874`](https://github.com/PrismJS/prism/commit/cc9d874)]
* __Sass__:
	* Regexp simplification Golmote [[`165d957`](https://github.com/PrismJS/prism/commit/165d957)]
* __Scala__:
	* Regexp optimisation Golmote [[`5f50c12`](https://github.com/PrismJS/prism/commit/5f50c12)]
* __Scheme__:
	* Regexp optimisation [[`bd19b04`](https://github.com/PrismJS/prism/commit/bd19b04)]
* __SCSS__:
	* Regexp simplification [[`c60b7d4`](https://github.com/PrismJS/prism/commit/c60b7d4)]
* __Smalltalk__:
	* Regexp simplification [[`41a2c76`](https://github.com/PrismJS/prism/commit/41a2c76)]
* __Smarty__:
	* Regexp optimisation and simplification [[`e169be9`](https://github.com/PrismJS/prism/commit/e169be9)]
* __SQL__:
	* Regexp optimisation [[`a6244a4`](https://github.com/PrismJS/prism/commit/a6244a4)]
* __Stylus__:
	* Regexp optimisation [[`df9506c`](https://github.com/PrismJS/prism/commit/df9506c)]
* __Swift__:
	* Don't use captures if not needed [[`a2d737a`](https://github.com/PrismJS/prism/commit/a2d737a)]
* __Tcl__:
	* Regexp simplification + don't use captures if not needed [[`f0b8a33`](https://github.com/PrismJS/prism/commit/f0b8a33)]
* __Textile__:
	* Regexp optimisation + don't use captures if not needed [[`08139ad`](https://github.com/PrismJS/prism/commit/08139ad)]
* __Twig__:
	* Regexp optimisation and simplification + don't use captures if not needed [[`0b10fd0`](https://github.com/PrismJS/prism/commit/0b10fd0)]
* __TypeScript__:
	* Don't use captures if not needed [[`e296caf`](https://github.com/PrismJS/prism/commit/e296caf)]
* __Verilog__:
	* Regexp simplification [[`1b24b34`](https://github.com/PrismJS/prism/commit/1b24b34)]
* __VHDL__:
	* Regexp optimisation and simplification [[`7af36df`](https://github.com/PrismJS/prism/commit/7af36df)]
* __vim__:
	* Remove duplicates in keywords [[`700505e`](https://github.com/PrismJS/prism/commit/700505e)]
* __Wiki markup__:
	* Fix escaping consistency [[`1fd690d`](https://github.com/PrismJS/prism/commit/1fd690d)]
* __YAML__:
	* Regexp optimisation + don't use captures if not needed [[`1fd690d`](https://github.com/PrismJS/prism/commit/1fd690d)]

### Other changes
* Remove comments spellcheck for AMP validation ([#1106](https://github.com/PrismJS/prism/issues/1106)) [[`de996d7`](https://github.com/PrismJS/prism/commit/de996d7)]
* Prevent error from throwing when element does not have a parentNode in highlightElement. [[`c33be19`](https://github.com/PrismJS/prism/commit/c33be19)]
* Provide a way to load Prism from inside a Worker without listening to messages. ([#1188](https://github.com/PrismJS/prism/issues/1188)) [[`d09982d`](https://github.com/PrismJS/prism/commit/d09982d)]

## 1.8.3 (2017-10-19)

### Other changes

* Fix inclusion tests for Pug [[`955c2ab`](https://github.com/PrismJS/prism/commit/955c2ab)]

## 1.8.2 (2017-10-19)

### Updated components
* __Jade__:
	* Jade has been renamed to __Pug__ ([#1201](https://github.com/PrismJS/prism/issues/1201)) [[`bcfef7c`](https://github.com/PrismJS/prism/commit/bcfef7c)]
* __JavaScript__:
	* Better highlighting of functions ([#1190](https://github.com/PrismJS/prism/issues/1190)) [[`8ee2cd3`](https://github.com/PrismJS/prism/commit/8ee2cd3)]

### Update plugins
* __Copy to clipboard__:
	* Fix error occurring when using in Chrome 61+ ([#1206](https://github.com/PrismJS/prism/issues/1206)) [[`b41d571`](https://github.com/PrismJS/prism/commit/b41d571)]
* __Show invisibles__:
	* Prevent error when using with Autoloader plugin ([#1195](https://github.com/PrismJS/prism/issues/1195)) [[`ed8bdb5`](https://github.com/PrismJS/prism/commit/ed8bdb5)]

## 1.8.1 (2017-09-16)

### Other changes

* Add Arduino to components.js [[`290a3c6`](https://github.com/PrismJS/prism/commit/290a3c6)]

## 1.8.0 (2017-09-16)

### New components

* __Arduino__ ([#1184](https://github.com/PrismJS/prism/issues/1184)) [[`edf2454`](https://github.com/PrismJS/prism/commit/edf2454)]
* __OpenCL__ ([#1175](https://github.com/PrismJS/prism/issues/1175)) [[`131e8fa`](https://github.com/PrismJS/prism/commit/131e8fa)]

### Updated plugins

* __Autolinker__:
	* Silently catch any error thrown by decodeURIComponent. Fixes [#1186](https://github.com/PrismJS/prism/issues/1186) [[`2e43fcf`](https://github.com/PrismJS/prism/commit/2e43fcf)]

## 1.7.0 (2017-09-09)

### New components

* __Django/Jinja2__ ([#1085](https://github.com/PrismJS/prism/issues/1085)) [[`345b1b2`](https://github.com/PrismJS/prism/commit/345b1b2)]
* __N4JS__ ([#1141](https://github.com/PrismJS/prism/issues/1141)) [[`eaa8ebb`](https://github.com/PrismJS/prism/commit/eaa8ebb)]
* __Ren'py__ ([#658](https://github.com/PrismJS/prism/issues/658)) [[`7ab4013`](https://github.com/PrismJS/prism/commit/7ab4013)]
* __VB.Net__ ([#1122](https://github.com/PrismJS/prism/issues/1122)) [[`5400651`](https://github.com/PrismJS/prism/commit/5400651)]

### Updated components

* __APL__:
	* Add left shoe underbar and right shoe underbar ([#1072](https://github.com/PrismJS/prism/issues/1072)) [[`12238c5`](https://github.com/PrismJS/prism/commit/12238c5)]
	* Update prism-apl.js ([#1126](https://github.com/PrismJS/prism/issues/1126)) [[`a5f3cdb`](https://github.com/PrismJS/prism/commit/a5f3cdb)]
* __C__:
	* Add more keywords and constants for C. ([#1029](https://github.com/PrismJS/prism/issues/1029)) [[`43a388e`](https://github.com/PrismJS/prism/commit/43a388e)]
* __C#__:
	* Fix wrong highlighting when three slashes appear inside string. Fix [#1091](https://github.com/PrismJS/prism/issues/1091) [[`dfb6f17`](https://github.com/PrismJS/prism/commit/dfb6f17)]
* __C-like__:
	* Add support for unclosed block comments. Close [#828](https://github.com/PrismJS/prism/issues/828) [[`3426ed1`](https://github.com/PrismJS/prism/commit/3426ed1)]
* __Crystal__:
	* Update Crystal keywords ([#1092](https://github.com/PrismJS/prism/issues/1092)) [[`125bff1`](https://github.com/PrismJS/prism/commit/125bff1)]
* __CSS Extras__:
	* Support CSS #RRGGBBAA ([#1139](https://github.com/PrismJS/prism/issues/1139)) [[`07a6806`](https://github.com/PrismJS/prism/commit/07a6806)]
* __Docker__:
	* Add dockerfile alias for docker language ([#1164](https://github.com/PrismJS/prism/issues/1164)) [[`601c47f`](https://github.com/PrismJS/prism/commit/601c47f)]
	* Update the list of keywords for dockerfiles ([#1180](https://github.com/PrismJS/prism/issues/1180)) [[`f0d73e0`](https://github.com/PrismJS/prism/commit/f0d73e0)]
* __Eiffel__:
	* Add class-name highlighting for Eiffel ([#471](https://github.com/PrismJS/prism/issues/471)) [[`cd03587`](https://github.com/PrismJS/prism/commit/cd03587)]
* __Handlebars__:
	* Check for possible pre-existing marker strings in Handlebars [[`7a1a404`](https://github.com/PrismJS/prism/commit/7a1a404)]
* __JavaScript__:
	* Properly match every operator as a whole token. Fix [#1133](https://github.com/PrismJS/prism/issues/1133) [[`9f649fb`](https://github.com/PrismJS/prism/commit/9f649fb)]
	* Allows uppercase prefixes in JS number literals ([#1151](https://github.com/PrismJS/prism/issues/1151)) [[`d4ee904`](https://github.com/PrismJS/prism/commit/d4ee904)]
	* Reduced backtracking in regex pattern. Fix [#1159](https://github.com/PrismJS/prism/issues/1159) [[`ac09e97`](https://github.com/PrismJS/prism/commit/ac09e97)]
* __JSON__:
	* Fix property and string patterns performance. Fix [#1080](https://github.com/PrismJS/prism/issues/1080) [[`0ca1353`](https://github.com/PrismJS/prism/commit/0ca1353)]
* __JSX__:
	* JSX spread operator break. Fixes [#1061](https://github.com/PrismJS/prism/issues/1061) ([#1094](https://github.com/PrismJS/prism/issues/1094)) [[`561bceb`](https://github.com/PrismJS/prism/commit/561bceb)]
	* Fix highlighting of attributes containing spaces [[`867ea42`](https://github.com/PrismJS/prism/commit/867ea42)]
	* Improved performance for tags (when not matching) Fix [#1152](https://github.com/PrismJS/prism/issues/1152) [[`b0fe103`](https://github.com/PrismJS/prism/commit/b0fe103)]
* __LOLCODE__:
	* Make strings greedy Golmote [[`1a5e7a4`](https://github.com/PrismJS/prism/commit/1a5e7a4)]
* __Markup__:
	* Support HTML entities in attribute values ([#1143](https://github.com/PrismJS/prism/issues/1143)) [[`1d5047d`](https://github.com/PrismJS/prism/commit/1d5047d)]
* __NSIS__:
	* Update patterns ([#1033](https://github.com/PrismJS/prism/issues/1033)) [[`01a59d8`](https://github.com/PrismJS/prism/commit/01a59d8)]
	* Add support for NSIS 3.02 ([#1169](https://github.com/PrismJS/prism/issues/1169)) [[`393b5f7`](https://github.com/PrismJS/prism/commit/393b5f7)]
* __PHP__:
	* Fix the PHP language ([#1100](https://github.com/PrismJS/prism/issues/1100)) [[`1453fa7`](https://github.com/PrismJS/prism/commit/1453fa7)]
	* Check for possible pre-existing marker strings in PHP [[`36bc560`](https://github.com/PrismJS/prism/commit/36bc560)]
* __Ruby__:
	* Fix slash regex performance. Fix [#1083](https://github.com/PrismJS/prism/issues/1083) [[`a708730`](https://github.com/PrismJS/prism/commit/a708730)]
	* Add support for =begin =end comments. Manual merge of [#1121](https://github.com/PrismJS/prism/issues/1121). [[`62cdaf8`](https://github.com/PrismJS/prism/commit/62cdaf8)]
* __Smarty__:
	* Check for possible pre-existing marker strings in Smarty [[`5df26e2`](https://github.com/PrismJS/prism/commit/5df26e2)]
* __TypeScript__:
	* Update typescript keywords ([#1064](https://github.com/PrismJS/prism/issues/1064)) [[`52020a0`](https://github.com/PrismJS/prism/commit/52020a0)]
	* Chmod -x prism-typescript component ([#1145](https://github.com/PrismJS/prism/issues/1145)) [[`afe0542`](https://github.com/PrismJS/prism/commit/afe0542)]
* __YAML__:
	* Make strings greedy (partial fix for [#1075](https://github.com/PrismJS/prism/issues/1075)) [[`565a2cc`](https://github.com/PrismJS/prism/commit/565a2cc)]

### Updated plugins

* __Autolinker__:
	* Fixed an rendering issue for encoded urls ([#1173](https://github.com/PrismJS/prism/issues/1173)) [[`abc007f`](https://github.com/PrismJS/prism/commit/abc007f)]
* __Custom Class__:
	* Add missing noCSS property for the Custom Class plugin [[`ba64f8d`](https://github.com/PrismJS/prism/commit/ba64f8d)]
	* Added a default for classMap. Fixes [#1137](https://github.com/PrismJS/prism/issues/1137). ([#1157](https://github.com/PrismJS/prism/issues/1157)) [[`5400af9`](https://github.com/PrismJS/prism/commit/5400af9)]
* __Keep Markup__:
	* Store highlightedCode after reinserting markup. Fix [#1127](https://github.com/PrismJS/prism/issues/1127) [[`6df2ceb`](https://github.com/PrismJS/prism/commit/6df2ceb)]
* __Line Highlight__:
	* Cleanup left-over line-highlight tags before other plugins run [[`79b723d`](https://github.com/PrismJS/prism/commit/79b723d)]
	* Avoid conflict between line-highlight and other plugins [[`224fdb8`](https://github.com/PrismJS/prism/commit/224fdb8)]
* __Line Numbers__:
	* Support soft wrap for line numbers plugin ([#584](https://github.com/PrismJS/prism/issues/584)) [[`849f1d6`](https://github.com/PrismJS/prism/commit/849f1d6)]
	* Plugins fixes (unescaped-markup, line-numbers) ([#1012](https://github.com/PrismJS/prism/issues/1012)) [[`3fb7cf8`](https://github.com/PrismJS/prism/commit/3fb7cf8)]
* __Normalize Whitespace__:
	* Add Node.js support for the normalize-whitespace plugin [[`6c7dae2`](https://github.com/PrismJS/prism/commit/6c7dae2)]
* __Unescaped Markup__:
	* Plugins fixes (unescaped-markup, line-numbers) ([#1012](https://github.com/PrismJS/prism/issues/1012)) [[`3fb7cf8`](https://github.com/PrismJS/prism/commit/3fb7cf8)]

### Updated themes
* __Coy__:
	* Scroll 'Coy' background with contents ([#1163](https://github.com/PrismJS/prism/issues/1163)) [[`310990b`](https://github.com/PrismJS/prism/commit/310990b)]

### Other changes

* Initial implementation of manual highlighting ([#1087](https://github.com/PrismJS/prism/issues/1087)) [[`bafc4cb`](https://github.com/PrismJS/prism/commit/bafc4cb)]
* Remove dead link in Third-party tutorials section. Fixes [#1028](https://github.com/PrismJS/prism/issues/1028) [[`dffadc6`](https://github.com/PrismJS/prism/commit/dffadc6)]
* Most languages now use the greedy flag for better highlighting [[`7549ecc`](https://github.com/PrismJS/prism/commit/7549ecc)]
* .npmignore: Unignore components.js ([#1108](https://github.com/PrismJS/prism/issues/1108)) [[`1f699e7`](https://github.com/PrismJS/prism/commit/1f699e7)]
* Run before-highlight and after-highlight hooks even when no grammar is found. Fix [#1134](https://github.com/PrismJS/prism/issues/1134) [[`70cb472`](https://github.com/PrismJS/prism/commit/70cb472)]
* Replace [\w\W] with [\s\S] and [0-9] with \d in regexes ([#1107](https://github.com/PrismJS/prism/issues/1107)) [[`8aa2cc4`](https://github.com/PrismJS/prism/commit/8aa2cc4)]
* Fix corner cases for the greedy flag ([#1095](https://github.com/PrismJS/prism/issues/1095)) [[`6530709`](https://github.com/PrismJS/prism/commit/6530709)]
* Add Third Party Tutorial ([#1156](https://github.com/PrismJS/prism/issues/1156)) [[`c34e57b`](https://github.com/PrismJS/prism/commit/c34e57b)]
* Add Composer support ([#648](https://github.com/PrismJS/prism/issues/648)) [[`2989633`](https://github.com/PrismJS/prism/commit/2989633)]
* Remove IE8 plugin ([#992](https://github.com/PrismJS/prism/issues/992)) [[`25788eb`](https://github.com/PrismJS/prism/commit/25788eb)]
* Website: remove width and height on logo.svg, so it becomes scalable. Close [#1005](https://github.com/PrismJS/prism/issues/1005) [[`0621ff7`](https://github.com/PrismJS/prism/commit/0621ff7)]
* Remove yarn.lock ([#1098](https://github.com/PrismJS/prism/issues/1098)) [[`11eed25`](https://github.com/PrismJS/prism/commit/11eed25)]

## 1.6.0 (2016-12-03)

### New components

* __.properties__ ([#980](https://github.com/PrismJS/prism/issues/980)) [[`be6219a`](https://github.com/PrismJS/prism/commit/be6219a)]
* __Ada__ ([#949](https://github.com/PrismJS/prism/issues/949)) [[`65619f7`](https://github.com/PrismJS/prism/commit/65619f7)]
* __GraphQL__ ([#971](https://github.com/PrismJS/prism/issues/971)) [[`e018087`](https://github.com/PrismJS/prism/commit/e018087)]
* __Jolie__ ([#1014](https://github.com/PrismJS/prism/issues/1014)) [[`dfc1941`](https://github.com/PrismJS/prism/commit/dfc1941)]
* __LiveScript__ ([#982](https://github.com/PrismJS/prism/issues/982)) [[`62e258c`](https://github.com/PrismJS/prism/commit/62e258c)]
* __Reason__ (Fixes [#1046](https://github.com/PrismJS/prism/issues/1046)) [[`3cae6ce`](https://github.com/PrismJS/prism/commit/3cae6ce)]
* __Xojo__ ([#994](https://github.com/PrismJS/prism/issues/994)) [[`0224b7c`](https://github.com/PrismJS/prism/commit/0224b7c)]

### Updated components

* __APL__:
	* Add iota underbar ([#1024](https://github.com/PrismJS/prism/issues/1024)) [[`3c5c89a`](https://github.com/PrismJS/prism/commit/3c5c89a), [`ac21d33`](https://github.com/PrismJS/prism/commit/ac21d33)]
* __AsciiDoc__:
	* Optimized block regexps to prevent struggling on large files. Fixes [#1001](https://github.com/PrismJS/prism/issues/1001). [[`1a86d34`](https://github.com/PrismJS/prism/commit/1a86d34)]
* __Bash__:
	* Add `npm` to function list ([#969](https://github.com/PrismJS/prism/issues/969)) [[`912bdfe`](https://github.com/PrismJS/prism/commit/912bdfe)]
* __CSS__:
	* Make CSS strings greedy. Fix [#1013](https://github.com/PrismJS/prism/issues/1013). [[`e57e26d`](https://github.com/PrismJS/prism/commit/e57e26d)]
* __CSS Extras__:
	* Match attribute inside selectors [[`13fed76`](https://github.com/PrismJS/prism/commit/13fed76)]
* __Groovy__:
	* Fix order of decoding entities in groovy. Fixes [#1049](https://github.com/PrismJS/prism/issues/1049) ([#1050](https://github.com/PrismJS/prism/issues/1050)) [[`d75da8e`](https://github.com/PrismJS/prism/commit/d75da8e)]
* __Ini__:
	* Remove important token in ini definition ([#1047](https://github.com/PrismJS/prism/issues/1047)) [[`fe8ad8b`](https://github.com/PrismJS/prism/commit/fe8ad8b)]
* __JavaScript__:
	* Add exponentiation & spread/rest operator ([#991](https://github.com/PrismJS/prism/issues/991)) [[`b2de65a`](https://github.com/PrismJS/prism/commit/b2de65a), [`268d01e`](https://github.com/PrismJS/prism/commit/268d01e)]
* __JSON__:
	* JSON: Fixed issues with properties and strings + added tests. Fix [#1025](https://github.com/PrismJS/prism/issues/1025) [[`25a541d`](https://github.com/PrismJS/prism/commit/25a541d)]
* __Markup__:
	* Allow for dots in Markup tag names, but not in HTML tags included in Textile. Fixes [#888](https://github.com/PrismJS/prism/issues/888). [[`31ea66b`](https://github.com/PrismJS/prism/commit/31ea66b)]
	* Make doctype case-insensitive ([#1009](https://github.com/PrismJS/prism/issues/1009)) [[`3dd7219`](https://github.com/PrismJS/prism/commit/3dd7219)]
* __NSIS__:
	* Updated patterns ([#1032](https://github.com/PrismJS/prism/issues/1032)) [[`76ba1b8`](https://github.com/PrismJS/prism/commit/76ba1b8)]
* __PHP__:
	* Make comments greedy. Fix [#197](https://github.com/PrismJS/prism/issues/197) [[`318aab3`](https://github.com/PrismJS/prism/commit/318aab3)]
* __PowerShell__:
	* Fix highlighting of empty comments ([#977](https://github.com/PrismJS/prism/issues/977)) [[`4fda477`](https://github.com/PrismJS/prism/commit/4fda477)]
* __Puppet__:
	* Fix over-greedy regexp detection ([#978](https://github.com/PrismJS/prism/issues/978)) [[`105be25`](https://github.com/PrismJS/prism/commit/105be25)]
* __Ruby__:
	* Fix typo `Fload` to `Float` in prism-ruby.js ([#1023](https://github.com/PrismJS/prism/issues/1023)) [[`22cb018`](https://github.com/PrismJS/prism/commit/22cb018)]
	* Make strings greedy. Fixes [#1048](https://github.com/PrismJS/prism/issues/1048) [[`8b0520a`](https://github.com/PrismJS/prism/commit/8b0520a)]
* __SCSS__:
	* Alias statement as keyword. Fix [#246](https://github.com/PrismJS/prism/issues/246) [[`fd09391`](https://github.com/PrismJS/prism/commit/fd09391)]
	* Highlight variables inside selectors and properties. [[`d6b5c2f`](https://github.com/PrismJS/prism/commit/d6b5c2f)]
	* Highlight parent selector [[`8f5f1fa`](https://github.com/PrismJS/prism/commit/8f5f1fa)]
* __TypeScript__:
	* Add missing `from` keyword to typescript & set `ts` as alias. ([#1042](https://github.com/PrismJS/prism/issues/1042)) [[`cba78f3`](https://github.com/PrismJS/prism/commit/cba78f3)]

### New plugins

* __Copy to Clipboard__ ([#891](https://github.com/PrismJS/prism/issues/891)) [[`07b81ac`](https://github.com/PrismJS/prism/commit/07b81ac)]
* __Custom Class__ ([#950](https://github.com/PrismJS/prism/issues/950)) [[`a0bd686`](https://github.com/PrismJS/prism/commit/a0bd686)]
* __Data-URI Highlight__ ([#996](https://github.com/PrismJS/prism/issues/996)) [[`bdca61b`](https://github.com/PrismJS/prism/commit/bdca61b)]
* __Toolbar__ ([#891](https://github.com/PrismJS/prism/issues/891)) [[`07b81ac`](https://github.com/PrismJS/prism/commit/07b81ac)]

### Updated plugins

* __Autoloader__:
	* Updated documentation for Autoloader plugin [[`b4f3423`](https://github.com/PrismJS/prism/commit/b4f3423)]
    * Download all grammars as a zip from Autoloader plugin page ([#981](https://github.com/PrismJS/prism/issues/981)) [[`0d0a007`](https://github.com/PrismJS/prism/commit/0d0a007), [`5c815d3`](https://github.com/PrismJS/prism/commit/5c815d3)]
    * Removed duplicated script on Autoloader plugin page [[`9671996`](https://github.com/PrismJS/prism/commit/9671996)]
    * Don't try to load "none" component. Fix [#1000](https://github.com/PrismJS/prism/issues/1000) [[`f89b0b9`](https://github.com/PrismJS/prism/commit/f89b0b9)]
* __WPD__:
	* Fix at-rule detection + don't process if language is not handled [[`2626728`](https://github.com/PrismJS/prism/commit/2626728)]

### Other changes

* Improvement to greedy-flag ([#967](https://github.com/PrismJS/prism/issues/967)) [[`500121b`](https://github.com/PrismJS/prism/commit/500121b), [`9893489`](https://github.com/PrismJS/prism/commit/9893489)]
* Add setTimeout fallback for requestAnimationFrame. Fixes [#987](https://github.com/PrismJS/prism/issues/987). ([#988](https://github.com/PrismJS/prism/issues/988)) [[`c9bdcd3`](https://github.com/PrismJS/prism/commit/c9bdcd3)]
* Added aria-hidden attributes on elements created by the Line Highlight and Line Numbers plugins. Fixes [#574](https://github.com/PrismJS/prism/issues/574). [[`e5587a7`](https://github.com/PrismJS/prism/commit/e5587a7)]
* Don't insert space before ">" when there is no attributes [[`3dc8c9e`](https://github.com/PrismJS/prism/commit/3dc8c9e)]
* Added missing hooks-related tests for AsciiDoc, Groovy, Handlebars, Markup, PHP and Smarty [[`c1a0c1b`](https://github.com/PrismJS/prism/commit/c1a0c1b)]
* Fix issue when using Line numbers plugin and Normalise whitespace plugin together with Handlebars, PHP or Smarty. Fix [#1018](https://github.com/PrismJS/prism/issues/1018), [#997](https://github.com/PrismJS/prism/issues/997), [#935](https://github.com/PrismJS/prism/issues/935). Revert [#998](https://github.com/PrismJS/prism/issues/998). [[`86aa3d2`](https://github.com/PrismJS/prism/commit/86aa3d2)]
* Optimized logo ([#990](https://github.com/PrismJS/prism/issues/990)) ([#1002](https://github.com/PrismJS/prism/issues/1002)) [[`f69e570`](https://github.com/PrismJS/prism/commit/f69e570), [`218fd25`](https://github.com/PrismJS/prism/commit/218fd25)]
* Remove unneeded prefixed CSS ([#989](https://github.com/PrismJS/prism/issues/989)) [[`5e56833`](https://github.com/PrismJS/prism/commit/5e56833)]
* Optimize images ([#1007](https://github.com/PrismJS/prism/issues/1007)) [[`b2fa6d5`](https://github.com/PrismJS/prism/commit/b2fa6d5)]
* Add yarn.lock to .gitignore ([#1035](https://github.com/PrismJS/prism/issues/1035)) [[`03ecf74`](https://github.com/PrismJS/prism/commit/03ecf74)]
* Fix greedy flag bug. Fixes [#1039](https://github.com/PrismJS/prism/issues/1039) [[`32cd99f`](https://github.com/PrismJS/prism/commit/32cd99f)]
* Ruby: Fix test after [#1023](https://github.com/PrismJS/prism/issues/1023) [[`b15d43b`](https://github.com/PrismJS/prism/commit/b15d43b)]
* Ini: Fix test after [#1047](https://github.com/PrismJS/prism/issues/1047) [[`25cdd3f`](https://github.com/PrismJS/prism/commit/25cdd3f)]
* Reduce risk of XSS ([#1051](https://github.com/PrismJS/prism/issues/1051)) [[`17e33bc`](https://github.com/PrismJS/prism/commit/17e33bc)]
* env.code can be modified by before-sanity-check hook even when using language-none. Fix [#1066](https://github.com/PrismJS/prism/issues/1066) [[`83bafbd`](https://github.com/PrismJS/prism/commit/83bafbd)]


## 1.5.1 (2016-06-05)

### Updated components

* __Normalize Whitespace__:
	* Add class that disables the normalize whitespace plugin [[`9385c54`](https://github.com/PrismJS/prism/commit/9385c54)]
* __JavaScript Language__:
	* Rearrange the `string` and `template-string` token in JavaScript [[`1158e46`](https://github.com/PrismJS/prism/commit/1158e46)]
* __SQL Language__:
	* add delimeter and delimeters keywords to sql ([#958](https://github.com/PrismJS/prism/pull/958)) [[`a9ef24e`](https://github.com/PrismJS/prism/commit/a9ef24e)]
	* add AUTO_INCREMENT and DATE keywords to sql ([#954](https://github.com/PrismJS/prism/pull/954)) [[`caea2af`](https://github.com/PrismJS/prism/commit/caea2af)]
* __Diff Language__:
	* Highlight diff lines with only + or - ([#952](https://github.com/PrismJS/prism/pull/952)) [[`4d0526f`](https://github.com/PrismJS/prism/commit/4d0526f)]

### Other changes

* Allow for asynchronous loading of prism.js ([#959](https://github.com/PrismJS/prism/pull/959))
* Use toLowerCase on language names ([#957](https://github.com/PrismJS/prism/pull/957)) [[`acd9508`](https://github.com/PrismJS/prism/commit/acd9508)]
* link to index for basic usage - fixes [#945](https://github.com/PrismJS/prism/issues/945) ([#946](https://github.com/PrismJS/prism/pull/946)) [[`6c772d8`](https://github.com/PrismJS/prism/commit/6c772d8)]
* Fixed monospace typo ([#953](https://github.com/PrismJS/prism/pull/953)) [[`e6c3498`](https://github.com/PrismJS/prism/commit/e6c3498)]

## 1.5.0 (2016-05-01)

### New components

* __Bro Language__ ([#925](https://github.com/PrismJS/prism/pull/925))
* __Protocol Buffers Language__ ([#938](https://github.com/PrismJS/prism/pull/938)) [[`ae4a4f2`](https://github.com/PrismJS/prism/commit/ae4a4f2)]

### Updated components

* __Keep Markup__:
	* Fix Keep Markup plugin incorrect highlighting ([#880](https://github.com/PrismJS/prism/pull/880)) [[`24841ef`](https://github.com/PrismJS/prism/commit/24841ef)]
* __Groovy Language__:
	* Fix double HTML-encoding bug in Groovy language [[`24a0936`](https://github.com/PrismJS/prism/commit/24a0936)]
* __Java Language__:
	* Adding annotation token for Java ([#905](https://github.com/PrismJS/prism/pull/905)) [[`367ace6`](https://github.com/PrismJS/prism/commit/367ace6)]
* __SAS Language__:
	* Add missing keywords for SAS ([#922](https://github.com/PrismJS/prism/pull/922))
* __YAML Language__:
	* fix hilighting of YAML keys on first line of code block ([#943](https://github.com/PrismJS/prism/pull/943)) [[`f19db81`](https://github.com/PrismJS/prism/commit/f19db81)]
* __C# Language__:
	* Support for generic methods in csharp [[`6f75735`](https://github.com/PrismJS/prism/commit/6f75735)]

### New plugins

* __Unescaped Markup__ [[`07d77e5`](https://github.com/PrismJS/prism/commit/07d77e5)]
* __Normalize Whitespace__ ([#847](https://github.com/PrismJS/prism/pull/847)) [[`e86ec01`](https://github.com/PrismJS/prism/commit/e86ec01)]

### Other changes

* Add JSPM support [[`ad048ab`](https://github.com/PrismJS/prism/commit/ad048ab)]
* update linear-gradient syntax from `left` to `to right` [[`cd234dc`](https://github.com/PrismJS/prism/commit/cd234dc)]
* Add after-property to allow ordering of plugins [[`224b7a1`](https://github.com/PrismJS/prism/commit/224b7a1)]
* Partial solution for the "Comment-like substrings"-problem [[`2705c50`](https://github.com/PrismJS/prism/commit/2705c50)]
* Add property 'aliasTitles' to components.js [[`54400fb`](https://github.com/PrismJS/prism/commit/54400fb)]
* Add before-highlightall hook [[`70a8602`](https://github.com/PrismJS/prism/commit/70a8602)]
* Fix catastrophic backtracking regex issues in JavaScript [[`ab65be2`](https://github.com/PrismJS/prism/commit/ab65be2)]

## 1.4.1 (2016-02-03)

### Other changes

* Fix DFS bug in Prism core [[`b86c727`](https://github.com/PrismJS/prism/commit/b86c727)]

## 1.4.0 (2016-02-03)

### New components

* __Solarized Light__ ([#855](https://github.com/PrismJS/prism/pull/855)) [[`70846ba`](https://github.com/PrismJS/prism/commit/70846ba)]
* __JSON__ ([#370](https://github.com/PrismJS/prism/pull/370)) [[`ad2fcd0`](https://github.com/PrismJS/prism/commit/ad2fcd0)]

### Updated components

* __Show Language__:
	* Remove data-language attribute ([#840](https://github.com/PrismJS/prism/pull/840)) [[`eb9a83c`](https://github.com/PrismJS/prism/commit/eb9a83c)]
	* Allow custom label without a language mapping ([#837](https://github.com/PrismJS/prism/pull/837)) [[`7e74aef`](https://github.com/PrismJS/prism/commit/7e74aef)]
* __JSX__:
	* Better Nesting in JSX attributes ([#842](https://github.com/PrismJS/prism/pull/842)) [[`971dda7`](https://github.com/PrismJS/prism/commit/971dda7)]
* __File Highlight__:
	* Defer File Highlight until the full DOM has loaded. ([#844](https://github.com/PrismJS/prism/pull/844)) [[`6f995ef`](https://github.com/PrismJS/prism/commit/6f995ef)]
* __Coy Theme__:
	* Fix coy theme shadows ([#865](https://github.com/PrismJS/prism/pull/865)) [[`58d2337`](https://github.com/PrismJS/prism/commit/58d2337)]
* __Show Invisibles__:
	* Ensure show-invisibles compat with autoloader ([#874](https://github.com/PrismJS/prism/pull/874)) [[`c3cfb1f`](https://github.com/PrismJS/prism/commit/c3cfb1f)]
	* Add support for the space character for the show-invisibles plugin ([#876](https://github.com/PrismJS/prism/pull/876)) [[`05442d3`](https://github.com/PrismJS/prism/commit/05442d3)]

### New plugins

* __Command Line__ ([#831](https://github.com/PrismJS/prism/pull/831)) [[`8378906`](https://github.com/PrismJS/prism/commit/8378906)]

### Other changes

* Use document.currentScript instead of document.getElementsByTagName() [[`fa98743`](https://github.com/PrismJS/prism/commit/fa98743)]
* Add prefix for Firefox selection and move prefixed rule first [[`6d54717`](https://github.com/PrismJS/prism/commit/6d54717)]
* No background for `<code>` in `<pre>` [[`8c310bc`](https://github.com/PrismJS/prism/commit/8c310bc)]
* Fixing to initial copyright year [[`69cbf7a`](https://github.com/PrismJS/prism/commit/69cbf7a)]
* Simplify the “lang” regex [[`417f54a`](https://github.com/PrismJS/prism/commit/417f54a)]
* Fix broken heading links [[`a7f9e62`](https://github.com/PrismJS/prism/commit/a7f9e62)]
* Prevent infinite recursion in DFS [[`02894e1`](https://github.com/PrismJS/prism/commit/02894e1)]
* Fix incorrect page title [[`544b56f`](https://github.com/PrismJS/prism/commit/544b56f)]
* Link scss to webplatform wiki [[`08d979a`](https://github.com/PrismJS/prism/commit/08d979a)]
* Revert white-space to normal when code is inline instead of in a pre [[`1a971b5`](https://github.com/PrismJS/prism/commit/1a971b5)]

## 1.3.0 (2015-10-26)

### New components

* __AsciiDoc__ ([#800](https://github.com/PrismJS/prism/issues/800)) [[`6803ca0`](https://github.com/PrismJS/prism/commit/6803ca0)]
* __Haxe__ ([#811](https://github.com/PrismJS/prism/issues/811)) [[`bd44341`](https://github.com/PrismJS/prism/commit/bd44341)]
* __Icon__ ([#803](https://github.com/PrismJS/prism/issues/803)) [[`b43c5f3`](https://github.com/PrismJS/prism/commit/b43c5f3)]
* __Kotlin__ ([#814](https://github.com/PrismJS/prism/issues/814)) [[`e8a31a5`](https://github.com/PrismJS/prism/commit/e8a31a5)]
* __Lua__ ([#804](https://github.com/PrismJS/prism/issues/804)) [[`a36bc4a`](https://github.com/PrismJS/prism/commit/a36bc4a)]
* __Nix__ ([#795](https://github.com/PrismJS/prism/issues/795)) [[`9b275c8`](https://github.com/PrismJS/prism/commit/9b275c8)]
* __Oz__ ([#805](https://github.com/PrismJS/prism/issues/805)) [[`388c53f`](https://github.com/PrismJS/prism/commit/388c53f)]
* __PARI/GP__ ([#802](https://github.com/PrismJS/prism/issues/802)) [[`253c035`](https://github.com/PrismJS/prism/commit/253c035)]
* __Parser__ ([#808](https://github.com/PrismJS/prism/issues/808)) [[`a953b3a`](https://github.com/PrismJS/prism/commit/a953b3a)]
* __Puppet__ ([#813](https://github.com/PrismJS/prism/issues/813)) [[`81933ee`](https://github.com/PrismJS/prism/commit/81933ee)]
* __Roboconf__ ([#812](https://github.com/PrismJS/prism/issues/812)) [[`f5db346`](https://github.com/PrismJS/prism/commit/f5db346)]

### Updated components

* __C__:
	* Highlight directives in preprocessor lines ([#801](https://github.com/PrismJS/prism/issues/801)) [[`ad316a3`](https://github.com/PrismJS/prism/commit/ad316a3)]
* __C#__:
	* Highlight directives in preprocessor lines ([#801](https://github.com/PrismJS/prism/issues/801)) [[`ad316a3`](https://github.com/PrismJS/prism/commit/ad316a3)]
	* Fix detection of float numbers ([#806](https://github.com/PrismJS/prism/issues/806)) [[`1dae72b`](https://github.com/PrismJS/prism/commit/1dae72b)]
* __F#__:
	* Highlight directives in preprocessor lines ([#801](https://github.com/PrismJS/prism/issues/801)) [[`ad316a3`](https://github.com/PrismJS/prism/commit/ad316a3)]
* __JavaScript__:
	* Highlight true and false as booleans ([#801](https://github.com/PrismJS/prism/issues/801)) [[`ad316a3`](https://github.com/PrismJS/prism/commit/ad316a3)]
* __Python__:
	* Highlight triple-quoted strings before comments. Fix [#815](https://github.com/PrismJS/prism/issues/815) [[`90fbf0b`](https://github.com/PrismJS/prism/commit/90fbf0b)]

### New plugins

* __Previewer: Time__ ([#790](https://github.com/PrismJS/prism/issues/790)) [[`88173de`](https://github.com/PrismJS/prism/commit/88173de)]
* __Previewer: Angle__ ([#791](https://github.com/PrismJS/prism/issues/791)) [[`a434c86`](https://github.com/PrismJS/prism/commit/a434c86)]

### Other changes

* Increase mocha's timeout [[`f1c41db`](https://github.com/PrismJS/prism/commit/f1c41db)]
* Prevent most errors in IE8. Fix [#9](https://github.com/PrismJS/prism/issues/9) [[`9652d75`](https://github.com/PrismJS/prism/commit/9652d75)]
* Add U.S. Web Design Standards on homepage. Fix [#785](https://github.com/PrismJS/prism/issues/785) [[`e10d48b`](https://github.com/PrismJS/prism/commit/e10d48b), [`79ebbf8`](https://github.com/PrismJS/prism/commit/79ebbf8), [`2f7088d`](https://github.com/PrismJS/prism/commit/2f7088d)]
* Added gulp task to autolink PRs and commits in changelog [[`5ec4e4d`](https://github.com/PrismJS/prism/commit/5ec4e4d)]
* Use child processes to run each set of tests, in order to deal with the memory leak in vm.runInNewContext() [[`9a4b6fa`](https://github.com/PrismJS/prism/commit/9a4b6fa)]

## 1.2.0 (2015-10-07)

### New components

* __Batch__ ([#781](https://github.com/PrismJS/prism/issues/781)) [[`eab5b06`](https://github.com/PrismJS/prism/commit/eab5b06)]

### Updated components

* __ASP.NET__:
	* Simplified pattern for `<script>` [[`29643f4`](https://github.com/PrismJS/prism/issues/29643f4)]
* __Bash__:
	* Fix regression in strings ([#792](https://github.com/PrismJS/prism/issues/792)) [[`bd275c2`](https://github.com/PrismJS/prism/commit/bd275c2)]
	* Substantially reduce wrongly highlighted stuff ([#793](https://github.com/PrismJS/prism/issues/793)) [[`ac6fe2e`](https://github.com/PrismJS/prism/commit/ac6fe2e)]
* __CSS__:
	* Simplified pattern for `<style>` [[`29643f4`](https://github.com/PrismJS/prism/issues/29643f4)]
* __JavaScript__:
	* Simplified pattern for `<script>` [[`29643f4`](https://github.com/PrismJS/prism/issues/29643f4)]

### New plugins

* __Previewer: Gradient__ ([#783](https://github.com/PrismJS/prism/issues/783)) [[`9a63483`](https://github.com/PrismJS/prism/commit/9a63483)]

### Updated plugins

* __Previewer: Color__
	* Add support for Sass variables [[`3a1fb04`](https://github.com/PrismJS/prism/commit/3a1fb04)]

* __Previewer: Easing__
	* Add support for Sass variables [[`7c7ab4e`](https://github.com/PrismJS/prism/commit/7c7ab4e)]

### Other changes

* Test runner: Allow to run tests for only some languages [[`5ade8a5`](https://github.com/PrismJS/prism/issues/5ade8a5)]
* Download page: Fixed wrong components order raising error in generated file ([#797](https://github.com/PrismJS/prism/issues/787)) [[`7a6aed8`](https://github.com/PrismJS/prism/commit/7a6aed8)]

## 1.1.0 (2015-10-04)

### New components

* __ABAP__ ([#636](https://github.com/PrismJS/prism/issues/636)) [[`75b0328`](https://github.com/PrismJS/prism/commit/75b0328), [`0749129`](https://github.com/PrismJS/prism/commit/0749129)]
* __APL__ ([#308](https://github.com/PrismJS/prism/issues/308)) [[`1f45942`](https://github.com/PrismJS/prism/commit/1f45942), [`33a295f`](https://github.com/PrismJS/prism/commit/33a295f)]
* __AutoIt__ ([#771](https://github.com/PrismJS/prism/issues/771)) [[`211a41c`](https://github.com/PrismJS/prism/commit/211a41c)]
* __BASIC__ ([#620](https://github.com/PrismJS/prism/issues/620)) [[`805a0ce`](https://github.com/PrismJS/prism/commit/805a0ce)]
* __Bison__ ([#764](https://github.com/PrismJS/prism/issues/764)) [[`7feb135`](https://github.com/PrismJS/prism/commit/7feb135)]
* __Crystal__ ([#780](https://github.com/PrismJS/prism/issues/780)) [[`5b473de`](https://github.com/PrismJS/prism/commit/5b473de), [`414848d`](https://github.com/PrismJS/prism/commit/414848d)]
* __D__ ([#613](https://github.com/PrismJS/prism/issues/613)) [[`b5e741c`](https://github.com/PrismJS/prism/commit/b5e741c)]
* __Diff__ ([#450](https://github.com/PrismJS/prism/issues/450)) [[`ef41c74`](https://github.com/PrismJS/prism/commit/ef41c74)]
* __Docker__ ([#576](https://github.com/PrismJS/prism/issues/576)) [[`e808352`](https://github.com/PrismJS/prism/commit/e808352)]
* __Elixir__ ([#614](https://github.com/PrismJS/prism/issues/614)) [[`a1c028c`](https://github.com/PrismJS/prism/commit/a1c028c), [`c451611`](https://github.com/PrismJS/prism/commit/c451611), [`2e637f0`](https://github.com/PrismJS/prism/commit/2e637f0), [`ccb6566`](https://github.com/PrismJS/prism/commit/ccb6566)]
* __GLSL__ ([#615](https://github.com/PrismJS/prism/issues/615)) [[`247da05`](https://github.com/PrismJS/prism/commit/247da05)]
* __Inform 7__ ([#616](https://github.com/PrismJS/prism/issues/616)) [[`d2595b4`](https://github.com/PrismJS/prism/commit/d2595b4)]
* __J__ ([#623](https://github.com/PrismJS/prism/issues/623)) [[`0cc50b2`](https://github.com/PrismJS/prism/commit/0cc50b2)]
* __MEL__ ([#618](https://github.com/PrismJS/prism/issues/618)) [[`8496c14`](https://github.com/PrismJS/prism/commit/8496c14)]
* __Mizar__ ([#619](https://github.com/PrismJS/prism/issues/619)) [[`efde61d`](https://github.com/PrismJS/prism/commit/efde61d)]
* __Monkey__ ([#621](https://github.com/PrismJS/prism/issues/621)) [[`fdd4a3c`](https://github.com/PrismJS/prism/commit/fdd4a3c)]
* __nginx__ ([#776](https://github.com/PrismJS/prism/issues/776)) [[`dc4fc19`](https://github.com/PrismJS/prism/commit/dc4fc19), [`e62c88e`](https://github.com/PrismJS/prism/commit/e62c88e)]
* __Nim__ ([#622](https://github.com/PrismJS/prism/issues/622)) [[`af9c49a`](https://github.com/PrismJS/prism/commit/af9c49a)]
* __OCaml__ ([#628](https://github.com/PrismJS/prism/issues/628)) [[`556c04d`](https://github.com/PrismJS/prism/commit/556c04d)]
* __Processing__ ([#629](https://github.com/PrismJS/prism/issues/629)) [[`e47087b`](https://github.com/PrismJS/prism/commit/e47087b)]
* __Prolog__ ([#630](https://github.com/PrismJS/prism/issues/630)) [[`dd04c32`](https://github.com/PrismJS/prism/commit/dd04c32)]
* __Pure__ ([#626](https://github.com/PrismJS/prism/issues/626)) [[`9c276ab`](https://github.com/PrismJS/prism/commit/9c276ab)]
* __Q__ ([#624](https://github.com/PrismJS/prism/issues/624)) [[`c053c9e`](https://github.com/PrismJS/prism/commit/c053c9e)]
* __Qore__ [[`125e91f`](https://github.com/PrismJS/prism/commit/125e91f)]
* __Tcl__ [[`a3e751a`](https://github.com/PrismJS/prism/commit/a3e751a), [`11ff829`](https://github.com/PrismJS/prism/commit/11ff829)]
* __Textile__ ([#544](https://github.com/PrismJS/prism/issues/544)) [[`d0c6764`](https://github.com/PrismJS/prism/commit/d0c6764)]
* __Verilog__ ([#640](https://github.com/PrismJS/prism/issues/640)) [[`44a11c2`](https://github.com/PrismJS/prism/commit/44a11c2), [`795eb99`](https://github.com/PrismJS/prism/commit/795eb99)]
* __Vim__ [[`69ea994`](https://github.com/PrismJS/prism/commit/69ea994)]

### Updated components

* __Bash__:
	* Add support for Here-Documents ([#787](https://github.com/PrismJS/prism/issues/787)) [[`b57a096`](https://github.com/PrismJS/prism/commit/b57a096)]
	* Remove C-like dependency ([#789](https://github.com/PrismJS/prism/issues/789)) [[`1ab4619`](https://github.com/PrismJS/prism/commit/1ab4619)]
* __C__:
	* Fixed numbers [[`4d64d07`](https://github.com/PrismJS/prism/commit/4d64d07), [`071c3dd`](https://github.com/PrismJS/prism/commit/071c3dd)]
* __C-like__:
	* Add word boundary before class-name prefixes [[`aa757f6`](https://github.com/PrismJS/prism/commit/aa757f6)]
	* Improved operator regex + add != and !== [[`135ee9d`](https://github.com/PrismJS/prism/commit/135ee9d)]
	* Optimized string regexp [[`792e35c`](https://github.com/PrismJS/prism/commit/792e35c)]
* __F#__:
	* Fixed keywords containing exclamation mark [[`09f2005`](https://github.com/PrismJS/prism/commit/09f2005)]
	* Improved string pattern [[`0101c89`](https://github.com/PrismJS/prism/commit/0101c89)]
	* Insert preprocessor before keyword + don't allow line feeds before # [[`fdc9477`](https://github.com/PrismJS/prism/commit/fdc9477)]
	* Fixed numbers [[`0aa0791`](https://github.com/PrismJS/prism/commit/0aa0791)]
* __Gherkin__:
	* Don't allow spaces in tags [[`48ff8b7`](https://github.com/PrismJS/prism/commit/48ff8b7)]
	* Handle \r\n and \r + allow feature alone + don't match blank td/th [[`ce1ec3b`](https://github.com/PrismJS/prism/commit/ce1ec3b)]
* __Git__:
	* Added more examples ([#652](https://github.com/PrismJS/prism/issues/652)) [[`95dc102`](https://github.com/PrismJS/prism/commit/95dc102)]
	* Add support for unified diff. Fixes [#769](https://github.com/PrismJS/prism/issues/769), fixes [#357](https://github.com/PrismJS/prism/issues/357), closes [#401](https://github.com/PrismJS/prism/issues/401) [[`3aadd5d`](https://github.com/PrismJS/prism/commit/3aadd5d)]
* __Go__:
	* Improved operator regexp + removed punctuation from it [[`776ab90`](https://github.com/PrismJS/prism/commit/776ab90)]
* __Haml__:
	* Combine both multiline-comment regexps + handle \r\n and \r [[`f77b40b`](https://github.com/PrismJS/prism/commit/f77b40b)]
	* Handle \r\n and \r in filter regex [[`bbe68ac`](https://github.com/PrismJS/prism/commit/bbe68ac)]
* __Handlebars__:
	* Fix empty strings, add plus sign in exponential notation, improve block pattern and variable pattern [[`c477f9a`](https://github.com/PrismJS/prism/commit/c477f9a)]
	* Properly escape special replacement patterns ($) in Handlebars, PHP and Smarty. Fix [#772](https://github.com/PrismJS/prism/issues/772) [[`895bf46`](https://github.com/PrismJS/prism/commit/895bf46)]
* __Haskell__:
	* Removed useless backslashes and parentheses + handle \r\n and \r + simplify number regexp + fix operator regexp [[`1cc8d8e`](https://github.com/PrismJS/prism/commit/1cc8d8e)]
* __HTTP__:
	* Fix indentation + Add multiline flag for more flexibility + Fix response status + Handle \r\n and \r [[`aaa90f1`](https://github.com/PrismJS/prism/commit/aaa90f1)]
* __Ini__:
	* Fix some regexps + remove unused flags [[`53d5839`](https://github.com/PrismJS/prism/commit/53d5839)]
* __Jade__:
	* Add todo list + remove single-line comment pattern + simplified most patterns with m flag + handle \r\n and \r [[`a79e838`](https://github.com/PrismJS/prism/commit/a79e838)]
* __Java__:
	* Fix number regexp + simplified number regexp and optimized operator regexp [[`21e20b9`](https://github.com/PrismJS/prism/commit/21e20b9)]
* __JavaScript__:
	* JavaScript: Allow for all non-ASCII characters in function names. Fix [#400](https://github.com/PrismJS/prism/issues/400) [[`29e26dc`](https://github.com/PrismJS/prism/commit/29e26dc)]
* __JSX__:
	* Allow for one level of nesting in scripts (Fix [#717](https://github.com/PrismJS/prism/issues/717)) [[`90c75d5`](https://github.com/PrismJS/prism/commit/90c75d5)]
* __Julia__:
	* Simplify comment regexp + improved number regexp + improved operator regexp [[`bcac7d4`](https://github.com/PrismJS/prism/commit/bcac7d4)]
* __Keyman__:
	* Move header statements above keywords [[`23a444c`](https://github.com/PrismJS/prism/commit/23a444c)]
* __LaTeX__:
	* Simplify comment regexp [[`132b41a`](https://github.com/PrismJS/prism/commit/132b41a)]
	* Extend support [[`942a6ec`](https://github.com/PrismJS/prism/commit/942a6ec)]
* __Less__:
	* Remove useless part in property regexp [[`80d8260`](https://github.com/PrismJS/prism/commit/80d8260)]
* __LOLCODE__:
	* Removed useless parentheses [[`8147c9b`](https://github.com/PrismJS/prism/commit/8147c9b)]
* __Makefile__:
	* Add known failures in example [[`e0f8984`](https://github.com/PrismJS/prism/commit/e0f8984)]
	* Handle \r\n in comments and strings + fix "-include" keyword
* __Markup__:
	* Simplify patterns + handle \r\n and \r [[`4c551e8`](https://github.com/PrismJS/prism/commit/4c551e8)]
	* Don't allow = to appear in tag name [[`85d8a55`](https://github.com/PrismJS/prism/commit/85d8a55)]
	* Don't allow dot inside tag name [[`283691e`](https://github.com/PrismJS/prism/commit/283691e)]
* __MATLAB__:
	* Simplify string pattern to remove lookbehind [[`a3cbecc`](https://github.com/PrismJS/prism/commit/a3cbecc)]
* __NASM__:
	* Converted indents to tabs, removed uneeded escapes, added lookbehinds [[`a92e4bd`](https://github.com/PrismJS/prism/commit/a92e4bd)]
* __NSIS__:
	* Simplified patterns [[`bbd83d4`](https://github.com/PrismJS/prism/commit/bbd83d4)]
	* Fix operator regexp [[`44ad8dc`](https://github.com/PrismJS/prism/commit/44ad8dc)]
* __Objective-C__:
	* Simplified regexps + fix strings + handle \r [[`1d33147`](https://github.com/PrismJS/prism/commit/1d33147)]
	* Fix operator regexp [[`e9d382e`](https://github.com/PrismJS/prism/commit/e9d382e)]
* __Pascal__:
	* Simplified regexps [[`c03c8a4`](https://github.com/PrismJS/prism/commit/c03c8a4)]
* __Perl__:
	* Simplified regexps + Made most string and regexp patterns multi-line + Added support for regexp's n flag + Added missing operators [[`71b00cc`](https://github.com/PrismJS/prism/commit/71b00cc)]
* __PHP__:
	* Simplified patterns [[`f9d9452`](https://github.com/PrismJS/prism/commit/f9d9452)]
	* Properly escape special replacement patterns ($) in Handlebars, PHP and Smarty. Fix [#772](https://github.com/PrismJS/prism/issues/772) [[`895bf46`](https://github.com/PrismJS/prism/commit/895bf46)]
* __PHP Extras__:
	* Fix $this regexp + improve global regexp [[`781fdad`](https://github.com/PrismJS/prism/commit/781fdad)]
* __PowerShell__:
	* Update definitions for command/alias/operators [[`14da55c`](https://github.com/PrismJS/prism/commit/14da55c)]
* __Python__:
	* Added async/await and @ operator ([#656](https://github.com/PrismJS/prism/issues/656)) [[`7f1ae75`](https://github.com/PrismJS/prism/commit/7f1ae75)]
	* Added 'self' keyword and support for class names ([#677](https://github.com/PrismJS/prism/issues/677)) [[`d9d4ab2`](https://github.com/PrismJS/prism/commit/d9d4ab2)]
	* Simplified regexps + don't capture where unneeded + fixed operators [[`530f5f0`](https://github.com/PrismJS/prism/commit/530f5f0)]
* __R__:
	* Fixed and simplified patterns [[`c20c3ec`](https://github.com/PrismJS/prism/commit/c20c3ec)]
* __reST__:
	* Simplified some patterns, fixed others, prevented blank comments to match, moved list-bullet down to prevent breaking quotes [[`e6c6b85`](https://github.com/PrismJS/prism/commit/e6c6b85)]
* __Rip__:
	* Fixed some regexp + moved down numbers [[`1093f7d`](https://github.com/PrismJS/prism/commit/1093f7d)]
* __Ruby__:
	* Code cleaning, handle \r\n and \r, fix some regexps [[`dd4989f`](https://github.com/PrismJS/prism/commit/dd4989f)]
	* Add % notations for strings and regexps. Fix [#590](https://github.com/PrismJS/prism/issues/590) [[`2d37800`](https://github.com/PrismJS/prism/commit/2d37800)]
* __Rust__:
	* Simplified patterns and fixed operators [[`6c8494f`](https://github.com/PrismJS/prism/commit/6c8494f)]
* __SAS__:
	* Simplified datalines and optimized operator patterns [[`6ebb96f`](https://github.com/PrismJS/prism/commit/6ebb96f)]
* __Sass__:
	* Add missing require in components [[`35b8c50`](https://github.com/PrismJS/prism/commit/35b8c50)]
	* Fix comments, operators and selectors and simplified patterns [[`28759d0`](https://github.com/PrismJS/prism/commit/28759d0)]
	* Highlight "-" as operator only if surrounded by spaces, in order to not break hyphenated values (e.g. "ease-in-out") [[`b2763e7`](https://github.com/PrismJS/prism/commit/b2763e7)]
* __Scala__:
	* Simplified patterns [[`daf2597`](https://github.com/PrismJS/prism/commit/daf2597)]
* __Scheme__:
	* Add missing lookbehind on number pattern. Fix [#702](https://github.com/PrismJS/prism/issues/702) [[`3120ff7`](https://github.com/PrismJS/prism/commit/3120ff7)]
	* Fixes and simplifications [[`068704a`](https://github.com/PrismJS/prism/commit/068704a)]
	* Don't match content of symbols starting with a parenthesis [[`fa7df08`](https://github.com/PrismJS/prism/commit/fa7df08)]
* __Scss__:
	* Simplified patterns + fixed operators + don't match empty selectors [[`672c167`](https://github.com/PrismJS/prism/commit/672c167)]
* __Smalltalk__:
	* Simplified patterns [[`d896622`](https://github.com/PrismJS/prism/commit/d896622)]
* __Smarty__:
	* Optimized regexps + fixed punctuation and operators [[`1446700`](https://github.com/PrismJS/prism/commit/1446700)]
	* Properly escape special replacement patterns ($) in Handlebars, PHP and Smarty. Fix [#772](https://github.com/PrismJS/prism/issues/772) [[`895bf46`](https://github.com/PrismJS/prism/commit/895bf46)]
* __SQL__:
	* Simplified regexp + fixed keywords and operators + add CHARSET keyword [[`d49fec0`](https://github.com/PrismJS/prism/commit/d49fec0)]
* __Stylus__:
	* Rewrote the component entirely [[`7729728`](https://github.com/PrismJS/prism/commit/7729728)]
* __Swift__:
	* Optimized keywords lists and removed duplicates [[`936e429`](https://github.com/PrismJS/prism/commit/936e429)]
	* Add support for string interpolation. Fix [#448](https://github.com/PrismJS/prism/issues/448) [[`89cd5d0`](https://github.com/PrismJS/prism/commit/89cd5d0)]
* __Twig__:
	* Prevent "other" pattern from matching blank strings [[`cae2cef`](https://github.com/PrismJS/prism/commit/cae2cef)]
	* Optimized regexps + fixed operators + added missing operators/keywords [[`2d8271f`](https://github.com/PrismJS/prism/commit/2d8271f)]
* __VHDL__:
	* Move operator overloading before strings, don't capture if not needed, handle \r\n and \r, fix numbers [[`4533f17`](https://github.com/PrismJS/prism/commit/4533f17)]
* __Wiki markup__:
	* Fixed emphasis + merged some url patterns + added TODOs [[`8cf9e6a`](https://github.com/PrismJS/prism/commit/8cf9e6a)]
* __YAML__:
	* Handled \r\n and \r, simplified some patterns, fixed "---" [[`9e33e0a`](https://github.com/PrismJS/prism/commit/9e33e0a)]

### New plugins

* __Autoloader__ ([#766](https://github.com/PrismJS/prism/issues/766)) [[`ed4ccfe`](https://github.com/PrismJS/prism/commit/ed4ccfe)]
* __JSONP Highlight__ [[`b2f14d9`](https://github.com/PrismJS/prism/commit/b2f14d9)]
* __Keep Markup__ ([#770](https://github.com/PrismJS/prism/issues/770)) [[`bd3e9ea`](https://github.com/PrismJS/prism/commit/bd3e9ea)]
* __Previewer: Base__ ([#767](https://github.com/PrismJS/prism/issues/767)) [[`cf764c0`](https://github.com/PrismJS/prism/commit/cf764c0)]
* __Previewer: Color__ ([#767](https://github.com/PrismJS/prism/issues/767)) [[`cf764c0`](https://github.com/PrismJS/prism/commit/cf764c0)]
* __Previewer: Easing__ ([#773](https://github.com/PrismJS/prism/issues/773)) [[`513137c`](https://github.com/PrismJS/prism/commit/513137c), [`9207258`](https://github.com/PrismJS/prism/commit/9207258), [`4303c94`](https://github.com/PrismJS/prism/commit/4303c94)]
* __Remove initial line feed__ [[`ed9f2b2`](https://github.com/PrismJS/prism/commit/ed9f2b2), [`b8d098e`](https://github.com/PrismJS/prism/commit/b8d098e)]

### Updated plugins

* __Autolinker__:
	* Don't process all grammars on load, process each one in before-highlight. Should fix [#760](https://github.com/PrismJS/prism/issues/760) [[`a572495`](https://github.com/PrismJS/prism/commit/a572495)]
* __Line Highlight__:
	* Run in `complete` hook [[`f237e67`](https://github.com/PrismJS/prism/commit/f237e67)]
	* Fixed position when font-size is odd ([#668](https://github.com/PrismJS/prism/issues/668)) [[`86bbd4c`](https://github.com/PrismJS/prism/commit/86bbd4c), [`8ed7ce3`](https://github.com/PrismJS/prism/commit/8ed7ce3)]
* __Line Numbers__:
	* Run in `complete` hook [[`3f4d918`](https://github.com/PrismJS/prism/commit/3f4d918)]
	* Don't run if already exists [[`c89bbdb`](https://github.com/PrismJS/prism/commit/c89bbdb)]
	* Don't run if block is empty. Fix [#669](https://github.com/PrismJS/prism/issues/669) [[`ee463e8`](https://github.com/PrismJS/prism/commit/ee463e8)]
	* Correct calculation for number of lines (fix [#385](https://github.com/PrismJS/prism/issues/385)) [[`14f3f80`](https://github.com/PrismJS/prism/commit/14f3f80)]
	* Fix computation of line numbers for single-line code blocks. Fix [#721](https://github.com/PrismJS/prism/issues/721) [[`02b220e`](https://github.com/PrismJS/prism/commit/02b220e)]
	* Fixing word wrap on long code lines [[`56b3d29`](https://github.com/PrismJS/prism/commit/56b3d29)]
	* Fixing coy theme + line numbers plugin overflowing on long blocks of text ([#762](https://github.com/PrismJS/prism/issues/762)) [[`a0127eb`](https://github.com/PrismJS/prism/commit/a0127eb)]
* __Show Language__:
	* Add gulp task to build languages map in Show language plugin (Fix [#671](https://github.com/PrismJS/prism/issues/671)) [[`39bd827`](https://github.com/PrismJS/prism/commit/39bd827)]
	* Add reset styles to prevent bug in Coy theme ([#703](https://github.com/PrismJS/prism/issues/703)) [[`08dd500`](https://github.com/PrismJS/prism/commit/08dd500)]

### Other changes

* Fixed link to David Peach article ([#647](https://github.com/PrismJS/prism/issues/647)) [[`3f679f8`](https://github.com/PrismJS/prism/commit/3f679f8)]
* Added `complete` hook, which runs even when no grammar is found [[`e58b6c0`](https://github.com/PrismJS/prism/commit/e58b6c0), [`fd54995`](https://github.com/PrismJS/prism/commit/fd54995)]
* Added test suite runner ([#588](https://github.com/PrismJS/prism/issues/588)) [[`956cd85`](https://github.com/PrismJS/prism/commit/956cd85)]
* Added tests for every components
* Added `.gitattributes` to prevent line ending changes in test files [[`45ca8c8`](https://github.com/PrismJS/prism/commit/45ca8c8)]
* Split plugins into 3 columns on Download page [[`a88936a`](https://github.com/PrismJS/prism/commit/a88936a)]
* Removed comment in components.js to make it easier to parse as JSON ([#679](https://github.com/PrismJS/prism/issues/679)) [[`2cb1326`](https://github.com/PrismJS/prism/commit/2cb1326)]
* Updated README.md [[`1388256`](https://github.com/PrismJS/prism/commit/1388256)]
* Updated documentation since the example was not relevant any more [[`80aedb2`](https://github.com/PrismJS/prism/commit/80aedb2)]
* Fixed inline style for Coy theme [[`52829b3`](https://github.com/PrismJS/prism/commit/52829b3)]
* Prevent errors in nodeJS ([#754](https://github.com/PrismJS/prism/issues/754)) [[`9f5c93c`](https://github.com/PrismJS/prism/commit/9f5c93c), [`0356c58`](https://github.com/PrismJS/prism/commit/0356c58)]
* Explicitly make the Worker close itself after highlighting, so that users have control on this behaviour when directly using Prism inside a Worker. Fix [#492](https://github.com/PrismJS/prism/issues/492) [[`e42a228`](https://github.com/PrismJS/prism/commit/e42a228)]
* Added some language aliases: js for javascript, xml, html, mathml and svg for markup [[`2f9fe1e`](https://github.com/PrismJS/prism/commit/2f9fe1e)]
* Download page: Add a "Select all" checkbox ([#561](https://github.com/PrismJS/prism/issues/561)) [[`9a9020b`](https://github.com/PrismJS/prism/commit/9a9020b)]
* Download page: Don't add semicolon unless needed in generated code. Fix [#273](https://github.com/PrismJS/prism/issues/273) [[`5a5eec5`](https://github.com/PrismJS/prism/commit/5a5eec5)]
* Add language counter on homepage [[`889cda5`](https://github.com/PrismJS/prism/commit/889cda5)]
* Improve performance by doing more work in the worker [[`1316abc`](https://github.com/PrismJS/prism/commit/1316abc)]
* Replace Typeplate with SitePoint on homepage. Fix [#774](https://github.com/PrismJS/prism/issues/774) [[`0c54308`](https://github.com/PrismJS/prism/commit/0c54308)]
* Added basic `.editorconfig` [[`c48f55d`](https://github.com/PrismJS/prism/commit/c48f55d)]

---

## 1.0.1 (2015-07-26)

### New components

* __Brainfuck__ ([#611](https://github.com/PrismJS/prism/issues/611)) [[`3ede718`](https://github.com/PrismJS/prism/commit/3ede718)]
* __Keyman__ ([#609](https://github.com/PrismJS/prism/issues/609)) [[`2698f82`](https://github.com/PrismJS/prism/commit/2698f82), [`e9936c6`](https://github.com/PrismJS/prism/commit/e9936c6)]
* __Makefile__ ([#610](https://github.com/PrismJS/prism/issues/610)) [[`3baa61c`](https://github.com/PrismJS/prism/commit/3baa61c)]
* __Sass (Sass)__ (fix [#199](https://github.com/PrismJS/prism/issues/199)) [[`b081804`](https://github.com/PrismJS/prism/commit/b081804)]
* __VHDL__ ([#595](https://github.com/PrismJS/prism/issues/595)) [[`43e6157`](https://github.com/PrismJS/prism/commit/43e6157)]

### Updated components

* __ActionScript__:
	* Fix ! operator and add ++ and -- as whole operators [[`6bf0794`](https://github.com/PrismJS/prism/commit/6bf0794)]
	* Fix XML highlighting [[`90257b0`](https://github.com/PrismJS/prism/commit/90257b0)]
	* Update examples to add inline XML [[`2c1626a`](https://github.com/PrismJS/prism/commit/2c1626a), [`3987711`](https://github.com/PrismJS/prism/commit/3987711)]
* __Apache Configuration__:
	* Don't include the spaces in directive-inline [[`e87efd8`](https://github.com/PrismJS/prism/commit/e87efd8)]
* __AppleScript__:
	* Allow one level of nesting in block comments [[`65894c5`](https://github.com/PrismJS/prism/commit/65894c5)]
	* Removed duplicates between operators and keywords [[`1ec5a81`](https://github.com/PrismJS/prism/commit/1ec5a81)]
	* Removed duplicates between keywords and classes [[`e8d09f6`](https://github.com/PrismJS/prism/commit/e8d09f6)]
	* Move numbers up so they are not broken by operator pattern [[`66dac31`](https://github.com/PrismJS/prism/commit/66dac31)]
* __ASP.NET__:
	* Prevent Markup tags from breaking ASP tags + fix MasterType directive [[`1f0a336`](https://github.com/PrismJS/prism/commit/1f0a336)]
* __AutoHotkey__:
	* Allow tags (labels) to be highlighted at the end of the code [[`0a1fc4b`](https://github.com/PrismJS/prism/commit/0a1fc4b)]
	* Match all operators + add comma to punctuation [[`f0ccb1b`](https://github.com/PrismJS/prism/commit/f0ccb1b)]
	* Removed duplicates in keywords lists [[`fe0a068`](https://github.com/PrismJS/prism/commit/fe0a068)]
* __Bash__:
	* Simplify comment regex [[`2700981`](https://github.com/PrismJS/prism/commit/2700981)]
	* Removed duplicates in keywords + removed unneeded parentheses [[`903b8a4`](https://github.com/PrismJS/prism/commit/903b8a4)]
* __C__:
	* Removed string pattern (inherited from C-like) [[`dcce1a7`](https://github.com/PrismJS/prism/commit/dcce1a7)]
	* Better support for macro statements [[`4868635`](https://github.com/PrismJS/prism/commit/4868635)]
* __C#__:
	* Fix preprocessor pattern [[`86311f5`](https://github.com/PrismJS/prism/commit/86311f5)]
* __C++__:
	* Removed delete[] and new[] broken keywords [[`42fbeef`](https://github.com/PrismJS/prism/commit/42fbeef)]
* __C-like__:
	* Removed unused 'ignore' pattern [[`b6535dd`](https://github.com/PrismJS/prism/commit/b6535dd)]
	* Use look-ahead instead of inside to match functions [[`d4194c9`](https://github.com/PrismJS/prism/commit/d4194c9)]
* __CoffeeScript__:
	* Prevent strings from ending with a backslash [[`cb6b824`](https://github.com/PrismJS/prism/commit/cb6b824)]
* __CSS__:
	* Highlight parentheses as punctuation [[`cd0273e`](https://github.com/PrismJS/prism/commit/cd0273e)]
	* Improved highlighting of at-rules [[`e254088`](https://github.com/PrismJS/prism/commit/e254088)]
	* Improved URL and strings [[`901812c`](https://github.com/PrismJS/prism/commit/901812c)]
	* Selector regexp should not include last spaces before brace [[`f2e2718`](https://github.com/PrismJS/prism/commit/f2e2718)]
	* Handle \r\n [[`15760e1`](https://github.com/PrismJS/prism/commit/15760e1)]
* __Eiffel__:
	* Fix string patterns order + fix /= operator [[`7d1b8d7`](https://github.com/PrismJS/prism/commit/7d1b8d7)]
* __Erlang__:
	* Fixed quoted functions, quoted atoms, variables and <= operator [[`fa286aa`](https://github.com/PrismJS/prism/commit/fa286aa)]
* __Fortran__:
	* Improved pattern for comments inside strings [[`40ae215`](https://github.com/PrismJS/prism/commit/40ae215)]
	* Fixed order in keyword pattern [[`8a6d32d`](https://github.com/PrismJS/prism/commit/8a6d32d)]
* __Handlebars__:
	* Support blocks with dashes ([#587](https://github.com/PrismJS/prism/issues/587)) [[`f409b13`](https://github.com/PrismJS/prism/commit/f409b13)]
* __JavaScript__:
	* Added support for 'y' and 'u' ES6 JavaScript regex flags ([#596](https://github.com/PrismJS/prism/issues/596)) [[`5d99957`](https://github.com/PrismJS/prism/commit/5d99957)]
	* Added support for missing ES6 keywords in JavaScript ([#596](https://github.com/PrismJS/prism/issues/596)) [[`ca68b87`](https://github.com/PrismJS/prism/commit/ca68b87)]
	* Added `async` and `await` keywords ([#575](https://github.com/PrismJS/prism/issues/575)) [[`5458cec`](https://github.com/PrismJS/prism/commit/5458cec)]
	* Added support for Template strings + interpolation [[`04f72b1`](https://github.com/PrismJS/prism/commit/04f72b1)]
	* Added support for octal and binary numbers ([#597](https://github.com/PrismJS/prism/issues/597)) [[`a8aa058`](https://github.com/PrismJS/prism/commit/a8aa058)]
	* Improve regex performance of C-like strings and JS regexps [[`476cbf4`](https://github.com/PrismJS/prism/commit/476cbf4)]
* __Markup__:
	* Allow non-ASCII chars in tag names and attributes (fix [#585](https://github.com/PrismJS/prism/issues/585)) [[`52fd55e`](https://github.com/PrismJS/prism/commit/52fd55e)]
	* Optimized tag's regexp so that it stops crashing on large unclosed tags [[`75452ba`](https://github.com/PrismJS/prism/commit/75452ba)]
	* Highlight single quotes in attr-value as punctuation [[`1ebcb8e`](https://github.com/PrismJS/prism/commit/1ebcb8e)]
	* Doctype and prolog can be multi-line [[`c19a238`](https://github.com/PrismJS/prism/commit/c19a238)]
* __Python__:
	* Added highlighting for function declaration ([#601](https://github.com/PrismJS/prism/issues/601)) [[`a88aae8`](https://github.com/PrismJS/prism/commit/a88aae8)]
	* Fixed wrong highlighting of variables named a, b, c... f ([#601](https://github.com/PrismJS/prism/issues/601)) [[`a88aae8`](https://github.com/PrismJS/prism/commit/a88aae8)]
* __Ruby__:
	* Added support for string interpolation [[`c36b123`](https://github.com/PrismJS/prism/commit/c36b123)]
* __Scss__:
	* Fixed media queries highlighting [[`bf8e032`](https://github.com/PrismJS/prism/commit/bf8e032)]
	* Improved highlighting inside at-rules [[`eef4248`](https://github.com/PrismJS/prism/commit/eef4248)]
	* Match placeholders inside selectors (fix [#238](https://github.com/PrismJS/prism/issues/238)) [[`4e42e26`](https://github.com/PrismJS/prism/commit/4e42e26)]
* __Swift__:
	* Update keywords list (fix [#625](https://github.com/PrismJS/prism/issues/625)) [[`88f44a7`](https://github.com/PrismJS/prism/commit/88f44a7)]

### Updated plugins

* __File Highlight__:
	* Allow to specify the highlighting language. Fix [#607](https://github.com/PrismJS/prism/issues/607) [[`8030db9`](https://github.com/PrismJS/prism/commit/8030db9)]
* __Line Highlight__:
	* Fixed incorrect height in IE9 ([#604](https://github.com/PrismJS/prism/issues/604)) [[`f1705eb`](https://github.com/PrismJS/prism/commit/f1705eb)]
	* Prevent errors in IE8 [[`5f133c8`](https://github.com/PrismJS/prism/commit/5f133c8)]

### Other changes

* Removed moot `version` property from `bower.json` ([#594](https://github.com/PrismJS/prism/issues/594)) [[`4693499`](https://github.com/PrismJS/prism/commit/4693499)]
* Added repository to `bower.json` ([#600](https://github.com/PrismJS/prism/issues/600)) [[`8e5ebcc`](https://github.com/PrismJS/prism/commit/8e5ebcc)]
* Added `.DS_Store` to `.gitignore` [[`1707e4e`](https://github.com/PrismJS/prism/commit/1707e4e)]
* Improve test drive page usability. Fix [#591](https://github.com/PrismJS/prism/issues/591) [[`fe60858`](https://github.com/PrismJS/prism/commit/fe60858)]
* Fixed prism-core and prism-file-highlight to prevent errors in IE8 [[`5f133c8`](https://github.com/PrismJS/prism/commit/5f133c8)]
* Add Ubuntu Mono font to font stack [[`ed9d7e3`](https://github.com/PrismJS/prism/commit/ed9d7e3)]

---

## 1.0.0 (2015-05-23)

* First release
* Supported languages:
	* ActionScript
	* Apache Configuration
	* AppleScript
	* ASP.NET (C#)
	* AutoHotkey
	* Bash
	* C
	* C#
	* C++
	* C-like
	* CoffeeScript
	* CSS
	* CSS Extras
	* Dart
	* Eiffel
	* Erlang
	* F#
	* Fortran
	* Gherkin
	* Git
	* Go
	* Groovy
	* Haml
	* Handlebars
	* Haskell
	* HTTP
	* Ini
	* Jade
	* Java
	* JavaScript
	* Julia
	* LaTeX
	* Less
	* LOLCODE
	* Markdown
	* Markup
	* MATLAB
	* NASM
	* NSIS
	* Objective-C
	* Pascal
	* Perl
	* PHP
	* PHP Extras
	* PowerShell
	* Python
	* R
	* React JSX
	* reST
	* Rip
	* Ruby
	* Rust
	* SAS
	* Sass (Scss)
	* Scala
	* Scheme
	* Smalltalk
	* Smarty
	* SQL
	* Stylus
	* Swift
	* Twig
	* TypeScript
	* Wiki markup
	* YAML
* Plugins:
	* Autolinker
	* File Highlight
	* Highlight Keywords
	* Line Highlight
	* Line Numbers
	* Show Invisibles
	* Show Language
	* WebPlatform Docs


---

# [Prism](https://prismjs.com/)

[![Build Status](https://github.com/PrismJS/prism/workflows/CI/badge.svg)](https://github.com/PrismJS/prism/actions)
[![npm](https://img.shields.io/npm/dw/prismjs.svg)](https://www.npmjs.com/package/prismjs)

Prism is a lightweight, robust, and elegant syntax highlighting library. It's a spin-off project from [Dabblet](https://dabblet.com/).

You can learn more on [prismjs.com](https://prismjs.com/).

[Why another syntax highlighter?](https://lea.verou.me/2012/07/introducing-prism-an-awesome-new-syntax-highlighter/#more-1841)

[More themes for Prism!](https://github.com/PrismJS/prism-themes)

## Contribute to Prism!

### **Important Notice**

We are currently working on [Prism v2](https://github.com/PrismJS/prism/discussions/3531) and will only accept security-relevant PRs for the time being.

Once work on Prism v2 is sufficiently advanced, we will accept PRs again. This will be announced on our [Discussion](https://github.com/PrismJS/prism/discussions) page and mentioned in the [roadmap discussion](https://github.com/PrismJS/prism/discussions/3531).

<details>
<summary>Prism v1 contributing notes</summary>

Prism depends on community contributions to expand and cover a wider array of use cases. If you like it, consider giving back by sending a pull request. Here are a few tips:

- Read the [documentation](https://prismjs.com/extending.html). Prism was designed to be extensible.
- Do not edit `prism.js`, it’s just the version of Prism used by the Prism website and is built automatically. Limit your changes to the unminified files in the `components/` folder. `prism.js` and all minified files are generated by our build system (see below).
- Use `npm ci` to install Prism's dependencies. Do not use `npm install` because it will cause non-deterministic builds.
- The build system uses [gulp](https://github.com/gulpjs/gulp) to minify the files and build `prism.js`. With all of Prism's dependencies installed, you just need to run the command `npm run build`.
- Please follow the code conventions used in the files already. For example, I use [tabs for indentation and spaces for alignment](http://lea.verou.me/2012/01/why-tabs-are-clearly-superior/). Opening braces are on the same line, closing braces on their own line regardless of construct. There is a space before the opening brace. etc etc.
- Please try to err towards more smaller PRs rather than a few huge PRs. If a PR includes changes that I want to merge and also changes that I don't, handling it becomes difficult.
- My time is very limited these days, so it might take a long time to review bigger PRs (small ones are usually merged very quickly), especially those modifying the Prism Core. This doesn't mean your PR is rejected.
- If you contribute a new language definition, you will be responsible for handling bug reports about that language definition.
- If you [add a new language definition](https://prismjs.com/extending.html#creating-a-new-language-definition) or plugin, you need to add it to `components.json` as well and rebuild Prism by running `npm run build`, so that it becomes available to the download build page. For new languages, please also add a few [tests](https://prismjs.com/test-suite.html) and an example in the `examples/` folder.
- Go to [prism-themes](https://github.com/PrismJS/prism-themes) if you want to add a new theme.

Thank you so much for contributing!!

### Software requirements

Prism will run on [almost any browser](https://prismjs.com/#features-full) and Node.js version but you need the following software to contribute:

- Node.js >= 10.x
- npm >= 6.x

</details>

## Translations

* [简体中文](https://www.awesomes.cn/repo/PrismJS/prism) (if unavailable, see [here](https://deepmind.t-salon.cc/article/113))


---

# Copyright (c) 2015 Calvin Metcalf

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

**THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.**


---

process-nextick-args
=====

[![Build Status](https://travis-ci.org/calvinmetcalf/process-nextick-args.svg?branch=master)](https://travis-ci.org/calvinmetcalf/process-nextick-args)

```bash
npm install --save process-nextick-args
```

Always be able to pass arguments to process.nextTick, no matter the platform

```js
var pna = require('process-nextick-args');

pna.nextTick(function (a, b, c) {
  console.log(a, b, c);
}, 'step', 3,  'profit');
```


---

<p align="center">
  <img src="https://github.com/terkelg/prompts/raw/master/prompts.png" alt="Prompts" width="500" />
</p>

<h1 align="center">❯ Prompts</h1>

<p align="center">
  <a href="https://npmjs.org/package/prompts">
    <img src="https://img.shields.io/npm/v/prompts.svg" alt="version" />
  </a>
  <a href="https://travis-ci.org/terkelg/prompts">
    <img src="https://img.shields.io/travis/terkelg/prompts.svg" alt="travis" />
  </a>
  <a href="https://npmjs.org/package/prompts">
    <img src="https://img.shields.io/npm/dm/prompts.svg" alt="downloads" />
  </a>
  <!---
   <a href="https://packagephobia.now.sh/result?p=prompts">
    <img src="https://packagephobia.now.sh/badge?p=prompts" alt="install size" />
  </a>
  --->
</p>

<p align="center">
  <b>Lightweight, beautiful and user-friendly interactive prompts</b><br />
  <sub>>_ Easy to use CLI prompts to enquire users for information▌</sub>
</p>

<br />

* **Simple**: prompts has [no big dependencies](http://npm.anvaka.com/#/view/2d/prompts) nor is it broken into a [dozen](http://npm.anvaka.com/#/view/2d/inquirer) tiny modules that only work well together.
* **User friendly**: prompt uses layout and colors to create beautiful cli interfaces.
* **Promised**: uses promises and `async`/`await`. No callback hell.
* **Flexible**: all prompts are independent and can be used on their own.
* **Testable**: provides a way to submit answers programmatically.
* **Unified**: consistent experience across all [prompts](#-types).


![split](https://github.com/terkelg/prompts/raw/master/media/split.png)


## ❯ Install

```
$ npm install --save prompts
```

> This package supports Node 6 and above

![split](https://github.com/terkelg/prompts/raw/master/media/split.png)

## ❯ Usage

<img src="https://github.com/terkelg/prompts/raw/master/media/example.gif" alt="example prompt" width="499" height="103" />

```js
const prompts = require('prompts');

(async () => {
  const response = await prompts({
    type: 'number',
    name: 'value',
    message: 'How old are you?',
    validate: value => value < 18 ? `Nightclub is 18+ only` : true
  });

  console.log(response); // => { value: 24 }
})();
```

> See [`example.js`](https://github.com/terkelg/prompts/blob/master/example.js) for more options.


![split](https://github.com/terkelg/prompts/raw/master/media/split.png)


## ❯ Examples

### Single Prompt

Prompt with a single prompt object. Returns an object with the response.

```js
const prompts = require('prompts');

(async () => {
  const response = await prompts({
    type: 'text',
    name: 'meaning',
    message: 'What is the meaning of life?'
  });

  console.log(response.meaning);
})();
```

### Prompt Chain

Prompt with a list of prompt objects. Returns an object with the responses.
Make sure to give each prompt a unique `name` property to prevent overwriting values.

```js
const prompts = require('prompts');

const questions = [
  {
    type: 'text',
    name: 'username',
    message: 'What is your GitHub username?'
  },
  {
    type: 'number',
    name: 'age',
    message: 'How old are you?'
  },
  {
    type: 'text',
    name: 'about',
    message: 'Tell something about yourself',
    initial: 'Why should I?'
  }
];

(async () => {
  const response = await prompts(questions);

  // => response => { username, age, about }
})();
```

### Dynamic Prompts

Prompt properties can be functions too.
Prompt Objects with `type` set to `falsy` values are skipped.

```js
const prompts = require('prompts');

const questions = [
  {
    type: 'text',
    name: 'dish',
    message: 'Do you like pizza?'
  },
  {
    type: prev => prev == 'pizza' ? 'text' : null,
    name: 'topping',
    message: 'Name a topping'
  }
];

(async () => {
  const response = await prompts(questions);
})();
```


![split](https://github.com/terkelg/prompts/raw/master/media/split.png)


## ❯ API

### prompts(prompts, options)

Type: `Function`<br>
Returns: `Object`

Prompter function which takes your [prompt objects](#-prompt-objects) and returns an object with responses.


#### prompts

Type: `Array|Object`<br>

Array of [prompt objects](#-prompt-objects).
 These are the questions the user will be prompted. You can see the list of supported [prompt types here](#-types).

Prompts can be submitted (<kbd>return</kbd>, <kbd>enter</kbd>) or canceled (<kbd>esc</kbd>, <kbd>abort</kbd>, <kbd>ctrl</kbd>+<kbd>c</kbd>, <kbd>ctrl</kbd>+<kbd>d</kbd>). No property is being defined on the returned response object when a prompt is canceled.

#### options.onSubmit

Type: `Function`<br>
Default: `() => {}`

Callback that's invoked after each prompt submission.
Its signature is `(prompt, answer, answers)` where `prompt` is the current prompt object, `answer` the user answer to the current question and `answers` the user answers so far. Async functions are supported.

Return `true` to quit the prompt chain and return all collected responses so far, otherwise continue to iterate prompt objects.

**Example:**
```js
(async () => {
  const questions = [{ ... }];
  const onSubmit = (prompt, answer) => console.log(`Thanks I got ${answer} from ${prompt.name}`);
  const response = await prompts(questions, { onSubmit });
})();
```

#### options.onCancel

Type: `Function`<br>
Default: `() => {}`

Callback that's invoked when the user cancels/exits the prompt.
Its signature is `(prompt, answers)` where `prompt` is the current prompt object and `answers` the user answers so far. Async functions are supported.

Return `true` to continue and prevent the prompt loop from aborting.
On cancel responses collected so far are returned.

**Example:**
```js
(async () => {
  const questions = [{ ... }];
  const onCancel = prompt => {
    console.log('Never stop prompting!');
    return true;
  }
  const response = await prompts(questions, { onCancel });
})();
```

### override

Type: `Function`

Preanswer questions by passing an object with answers to `prompts.override`.
Powerful when combined with arguments of process.

**Example**
```js
const prompts = require('prompts');
prompts.override(require('yargs').argv);

(async () => {
  const response = await prompts([
    {
      type: 'text',
      name: 'twitter',
      message: `What's your twitter handle?`
    },
    {
      type: 'multiselect',
      name: 'color',
      message: 'Pick colors',
      choices: [
        { title: 'Red', value: '#ff0000' },
        { title: 'Green', value: '#00ff00' },
        { title: 'Blue', value: '#0000ff' }
      ],
    }
  ]);

  console.log(response);
})();
```

### inject(values)

Type: `Function`<br>

Programmatically inject responses. This enables you to prepare the responses ahead of time.
If any injected value is found the prompt is immediately resolved with the injected value.
This feature is intended for testing only.

#### values

Type: `Array`

Array with values to inject. Resolved values are removed from the internal inject array.
Each value can be an array of values in order to provide answers for a question asked multiple times.
If a value is an instance of `Error` it will simulate the user cancelling/exiting the prompt.

**Example:**
```js
const prompts = require('prompts');

prompts.inject([ '@terkelg', ['#ff0000', '#0000ff'] ]);

(async () => {
  const response = await prompts([
    {
      type: 'text',
      name: 'twitter',
      message: `What's your twitter handle?`
    },
    {
      type: 'multiselect',
      name: 'color',
      message: 'Pick colors',
      choices: [
        { title: 'Red', value: '#ff0000' },
        { title: 'Green', value: '#00ff00' },
        { title: 'Blue', value: '#0000ff' }
      ],
    }
  ]);

  // => { twitter: 'terkelg', color: [ '#ff0000', '#0000ff' ] }
})();
```

![split](https://github.com/terkelg/prompts/raw/master/media/split.png)


## ❯ Prompt Objects

Prompts Objects are JavaScript objects that define the "questions" and the [type of prompt](#-types).
Almost all prompt objects have the following properties:

```js
{
  type: String | Function,
  name: String | Function,
  message: String | Function,
  initial: String | Function | Async Function
  format: Function | Async Function,
  onRender: Function
  onState: Function
  stdin: Readable
  stdout: Writeable
}
```

Each property be of type `function` and will be invoked right before prompting the user.

The function signature is `(prev, values, prompt)`, where `prev` is the value from the previous prompt,
`values` is the response object with all values collected so far and `prompt` is the previous prompt object.

**Function example:**
```js
{
  type: prev => prev > 3 ? 'confirm' : null,
  name: 'confirm',
  message: (prev, values) => `Please confirm that you eat ${values.dish} times ${prev} a day?`
}
```

The above prompt will be skipped if the value of the previous prompt is less than 3.

### type

Type: `String|Function`

Defines the type of prompt to display. See the list of [prompt types](#-types) for valid values.

If `type` is a falsy value the prompter will skip that question.
```js
{
  type: null,
  name: 'forgetme',
  message: `I'll never be shown anyway`,
}
```

### name

Type: `String|Function`

The response will be saved under this key/property in the returned response object.
In case you have multiple prompts with the same name only the latest response will be stored.

> Make sure to give prompts unique names if you don't want to overwrite previous values.

### message

Type: `String|Function`

The message to be displayed to the user.

### initial

Type: `String|Function`

Optional default prompt value. Async functions are supported too.

### format

Type: `Function`

Receive the user input and return the formatted value to be used inside the program.
The value returned will be added to the response object.

The function signature is `(val, values)`, where `val` is the value from the current prompt and
`values` is the current response object in case you need to format based on previous responses.

**Example:**
```js
{
  type: 'number',
  name: 'price',
  message: 'Enter price',
  format: val => Intl.NumberFormat(undefined, { style: 'currency', currency: 'USD' }).format(val);
}
```

### onRender

Type: `Function`

Callback for when the prompt is rendered.
The function receives [kleur](https://github.com/lukeed/kleur) as its first argument and `this` refers to the current prompt.

**Example:**
```js
{
  type: 'number',
  message: 'This message will be overridden',
  onRender(kleur) {
    this.msg = kleur.cyan('Enter a number');
  }
}
```

### onState

Type: `Function`

Callback for when the state of the current prompt changes.
The function signature is `(state)` where `state` is an object with a snapshot of the current state.
The state object has two properties `value` and `aborted`. E.g `{ value: 'This is ', aborted: false }`

### stdin and stdout

Type: `Stream`

By default, prompts uses `process.stdin` for receiving input and `process.stdout` for writing output.
If you need to use different streams, for instance `process.stderr`, you can set these with the `stdin` and `stdout` properties.


![split](https://github.com/terkelg/prompts/raw/master/media/split.png)


## ❯ Types

* [text](#textmessage-initial-style)
* [password](#passwordmessage-initial)
* [invisible](#invisiblemessage-initial)
* [number](#numbermessage-initial-max-min-style)
* [confirm](#confirmmessage-initial)
* [list](#listmessage-initial)
* [toggle](#togglemessage-initial-active-inactive)
* [select](#selectmessage-choices-initial-hint-warn)
* [multiselect](#multiselectmessage-choices-initial-max-hint-warn)
* [autocompleteMultiselect](#multiselectmessage-choices-initial-max-hint-warn)
* [autocomplete](#autocompletemessage-choices-initial-suggest-limit-style)
* [date](#datemessage-initial-warn)

***

### text(message, [initial], [style])
> Text prompt for free text input.

Hit <kbd>tab</kbd> to autocomplete to `initial` value when provided.

#### Example
<img src="https://github.com/terkelg/prompts/raw/master/media/text.gif" alt="text prompt" width="499" height="103" />

```js
{
  type: 'text',
  name: 'value',
  message: `What's your twitter handle?`
}
```

#### Options
| Param | Type | Description |
| ----- | :--: | ----------- |
| message | `string` | Prompt message to display |
| initial | `string` | Default string value |
| style | `string` | Render style (`default`, `password`, `invisible`, `emoji`). Defaults to `default` |
| format | `function` | Receive user input. The returned value will be added to the response object |
| validate | `function` | Receive user input. Should return `true` if the value is valid, and an error message `String` otherwise. If `false` is returned, a default error message is shown |
| onRender | `function` | On render callback. Keyword `this` refers to the current prompt |
| onState | `function` | On state change callback. Function signature is an `object` with two properties: `value` and `aborted` |

**↑ back to:** [Prompt types](#-types)

***

### password(message, [initial])
> Password prompt with masked input.

This prompt is a similar to a prompt of type `'text'` with `style` set to `'password'`.

#### Example
<img src="https://github.com/terkelg/prompts/raw/master/media/password.gif" alt="password prompt" width="499" height="103" />

```js
{
  type: 'password',
  name: 'value',
  message: 'Tell me a secret'
}
```

#### Options
| Param | Type | Description |
| ----- | :--: | ----------- |
| message | `string` | Prompt message to display |
| initial | `string` | Default string value |
| format | `function` | Receive user input. The returned value will be added to the response object |
| validate | `function` | Receive user input. Should return `true` if the value is valid, and an error message `String` otherwise. If `false` is returned, a default error message is shown |
| onRender | `function` | On render callback. Keyword `this` refers to the current prompt |
| onState | `function` | On state change callback. Function signature is an `object` with two properties: `value` and `aborted` |

**↑ back to:** [Prompt types](#-types)

***

### invisible(message, [initial])
> Prompts user for invisible text input.

This prompt is working like `sudo` where the input is invisible.
This prompt is a similar to a prompt of type `'text'` with style set to `'invisible'`.

#### Example
<img src="https://github.com/terkelg/prompts/raw/master/media/invisible.gif" alt="invisible prompt" width="499" height="103" />

```js
{
  type: 'invisible',
  name: 'value',
  message: 'Enter password'
}
```

#### Options
| Param | Type | Description |
| ----- | :--: | ----------- |
| message | `string` | Prompt message to display |
| initial | `string` | Default string value |
| format | `function` | Receive user input. The returned value will be added to the response object |
| validate | `function` | Receive user input. Should return `true` if the value is valid, and an error message `String` otherwise. If `false` is returned, a default error message is shown |
| onRender | `function` | On render callback. Keyword `this` refers to the current prompt |
| onState | `function` | On state change callback. Function signature is an `object` with two properties: `value` and `aborted` |

**↑ back to:** [Prompt types](#-types)

***

### number(message, initial, [max], [min], [style])
> Prompts user for number input.

You can type in numbers and use <kbd>up</kbd>/<kbd>down</kbd> to increase/decrease the value. Only numbers are allowed as input. Hit <kbd>tab</kbd> to autocomplete to `initial` value when provided.

#### Example
<img src="https://github.com/terkelg/prompts/raw/master/media/number.gif" alt="number prompt" width="499" height="103" />

```js
{
  type: 'number',
  name: 'value',
  message: 'How old are you?',
  initial: 0,
  style: 'default',
  min: 2,
  max: 10
}
```

#### Options
| Param | Type | Description |
| ----- | :--: | ----------- |
| message | `string` | Prompt message to display |
| initial | `number` | Default number value |
| format | `function` | Receive user input. The returned value will be added to the response object |
| validate | `function` | Receive user input. Should return `true` if the value is valid, and an error message `String` otherwise. If `false` is returned, a default error message is shown |
| max | `number` | Max value. Defaults to `Infinity` |
| min | `number` | Min value. Defaults to `-infinity` |
| float | `boolean` | Allow floating point inputs. Defaults to `false` |
| round | `number` | Round `float` values to x decimals. Defaults to `2` |
| increment | `number` | Increment step when using <kbd>arrow</kbd> keys. Defaults to `1` |
| style | `string` | Render style (`default`, `password`, `invisible`, `emoji`). Defaults to `default` |
| onRender | `function` | On render callback. Keyword `this` refers to the current prompt |
| onState | `function` | On state change callback. Function signature is an `object` with two properties: `value` and `aborted` |

**↑ back to:** [Prompt types](#-types)

***

### confirm(message, [initial])
> Classic yes/no prompt.

Hit <kbd>y</kbd> or <kbd>n</kbd> to confirm/reject.

#### Example
<img src="https://github.com/terkelg/prompts/raw/master/media/confirm.gif" alt="confirm prompt" width="499" height="103" />

```js
{
  type: 'confirm',
  name: 'value',
  message: 'Can you confirm?',
  initial: true
}
```


#### Options
| Param | Type | Description |
| ----- | :--: | ----------- |
| message | `string` | Prompt message to display |
| initial | `boolean` | Default value. Default is `false` |
| format | `function` | Receive user input. The returned value will be added to the response object |
| onRender | `function` | On render callback. Keyword `this` refers to the current prompt |
| onState | `function` | On state change callback. Function signature is an `object` with two properties: `value` and `aborted` |

**↑ back to:** [Prompt types](#-types)

***

### list(message, [initial])
> List prompt that return an array.

Similar to the `text` prompt, but the output is an `Array` containing the
string separated by `separator`.

```js
{
  type: 'list',
  name: 'value',
  message: 'Enter keywords',
  initial: '',
  separator: ','
}
```

<img src="https://github.com/terkelg/prompts/raw/master/media/list.gif" alt="list prompt" width="499" height="103" />


| Param | Type | Description |
| ----- | :--: | ----------- |
| message | `string` | Prompt message to display |
| initial | `boolean` | Default value |
| format | `function` | Receive user input. The returned value will be added to the response object |
| separator | `string` | String separator. Will trim all white-spaces from start and end of string. Defaults to `','`  |
| onRender | `function` | On render callback. Keyword `this` refers to the current prompt |
| onState | `function` | On state change callback. Function signature is an `object` with two properties: `value` and `aborted` |

**↑ back to:** [Prompt types](#-types)

***

### toggle(message, [initial], [active], [inactive])
> Interactive toggle/switch prompt.

Use tab or <kbd>arrow keys</kbd>/<kbd>tab</kbd>/<kbd>space</kbd> to switch between options.

#### Example
<img src="https://github.com/terkelg/prompts/raw/master/media/toggle.gif" alt="toggle prompt" width="499" height="103" />

```js
{
  type: 'toggle',
  name: 'value',
  message: 'Can you confirm?',
  initial: true,
  active: 'yes',
  inactive: 'no'
}
```

#### Options
| Param | Type | Description |
| ----- | :--: | ----------- |
| message | `string` | Prompt message to display |
| initial | `boolean` | Default value. Defaults to `false` |
| format | `function` | Receive user input. The returned value will be added to the response object |
| active | `string` | Text for `active` state. Defaults to `'on'` |
| inactive | `string` | Text for `inactive` state. Defaults to `'off'` |
| onRender | `function` | On render callback. Keyword `this` refers to the current prompt |
| onState | `function` | On state change callback. Function signature is an `object` with two properties: `value` and `aborted` |

**↑ back to:** [Prompt types](#-types)

***

### select(message, choices, [initial], [hint], [warn])
> Interactive select prompt.

Use <kbd>up</kbd>/<kbd>down</kbd> to navigate. Use <kbd>tab</kbd> to cycle the list.

#### Example
<img src="https://github.com/terkelg/prompts/raw/master/media/select.gif" alt="select prompt" width="499" height="130" />

```js
{
  type: 'select',
  name: 'value',
  message: 'Pick a color',
  choices: [
    { title: 'Red', description: 'This option has a description', value: '#ff0000' },
    { title: 'Green', value: '#00ff00', disabled: true },
    { title: 'Blue', value: '#0000ff' }
  ],
  initial: 1
}
```

#### Options
| Param | Type | Description |
| ----- | :--: | ----------- |
| message | `string` | Prompt message to display |
| initial | `number` | Index of default value |
| format | `function` | Receive user input. The returned value will be added to the response object |
| hint | `string` | Hint to display to the user |
| warn | `string` | Message to display when selecting a disabled option |
| choices | `Array` | Array of strings or choices objects `[{ title, description, value, disabled }, ...]`. The choice's index in the array will be used as its value if it is not specified. |
| onRender | `function` | On render callback. Keyword `this` refers to the current prompt |
| onState | `function` | On state change callback. Function signature is an `object` with two properties: `value` and `aborted` |

**↑ back to:** [Prompt types](#-types)

***

### multiselect(message, choices, [initial], [max], [hint], [warn])
### autocompleteMultiselect(same)
> Interactive multi-select prompt.  
> Autocomplete is a searchable multiselect prompt with the same options. Useful for long lists.

Use <kbd>space</kbd> to toggle select/unselect and <kbd>up</kbd>/<kbd>down</kbd> to navigate. Use <kbd>tab</kbd> to cycle the list. You can also use <kbd>right</kbd> to select and <kbd>left</kbd> to deselect.
By default this prompt returns an `array` containing the **values** of the selected items - not their display title.

#### Example
<img src="https://github.com/terkelg/prompts/raw/master/media/multiselect.gif" alt="multiselect prompt" width="499" height="130" />

```js
{
  type: 'multiselect',
  name: 'value',
  message: 'Pick colors',
  choices: [
    { title: 'Red', value: '#ff0000' },
    { title: 'Green', value: '#00ff00', disabled: true },
    { title: 'Blue', value: '#0000ff', selected: true }
  ],
  max: 2,
  hint: '- Space to select. Return to submit'
}
```

#### Options
| Param | Type | Description |
| ----- | :--: | ----------- |
| message | `string` | Prompt message to display |
| format | `function` | Receive user input. The returned value will be added to the response object |
| instructions | `string` or `boolean` | Prompt instructions to display |
| choices | `Array` | Array of strings or choices objects `[{ title, value, disabled }, ...]`. The choice's index in the array will be used as its value if it is not specified. |
| optionsPerPage | `number` | Number of options displayed per page (default: 10) |
| min | `number` | Min select - will display error |
| max | `number` | Max select |
| hint | `string` | Hint to display to the user |
| warn | `string` | Message to display when selecting a disabled option |
| onRender | `function` | On render callback. Keyword `this` refers to the current prompt |
| onState | `function` | On state change callback. Function signature is an `object` with two properties: `value` and `aborted` |

This is one of the few prompts that don't take a initial value.
If you want to predefine selected values, give the choice object an `selected` property of `true`.

**↑ back to:** [Prompt types](#-types)

***

### autocomplete(message, choices, [initial], [suggest], [limit], [style])
> Interactive auto complete prompt.

The prompt will list options based on user input. Type to filter the list.
Use <kbd>⇧</kbd>/<kbd>⇩</kbd> to navigate. Use <kbd>tab</kbd> to cycle the result. Use <kbd>Page Up</kbd>/<kbd>Page Down</kbd> (on Mac: <kbd>fn</kbd> + <kbd>⇧</kbd> / <kbd>⇩</kbd>) to change page. Hit <kbd>enter</kbd> to select the highlighted item below the prompt.

The default suggests function is sorting based on the `title` property of the choices.
You can overwrite how choices are being filtered by passing your own suggest function.

#### Example
<img src="https://github.com/terkelg/prompts/raw/master/media/autocomplete.gif" alt="auto complete prompt" width="499" height="163" />

```js
{
  type: 'autocomplete',
  name: 'value',
  message: 'Pick your favorite actor',
  choices: [
    { title: 'Cage' },
    { title: 'Clooney', value: 'silver-fox' },
    { title: 'Gyllenhaal' },
    { title: 'Gibson' },
    { title: 'Grant' }
  ]
}
```

#### Options
| Param | Type | Description |
| ----- | :--: | ----------- |
| message | `string` | Prompt message to display |
| format | `function` | Receive user input. The returned value will be added to the response object |
| choices | `Array` | Array of auto-complete choices objects `[{ title, value }, ...]` |
| suggest | `function` | Filter function. Defaults to sort by `title` property. `suggest` should always return a promise. Filters using `title` by default  |
| limit | `number` | Max number of results to show. Defaults to `10` |
| style | `string` | Render style (`default`, `password`, `invisible`, `emoji`). Defaults to `'default'` |
| initial | `string \| number` | Default initial value |
| clearFirst | `boolean` | The first ESCAPE keypress will clear the input |
| fallback | `string` | Fallback message when no match is found. Defaults to `initial` value if provided |
| onRender | `function` | On render callback. Keyword `this` refers to the current prompt |
| onState | `function` | On state change callback. Function signature is an `object` with three properties: `value`, `aborted` and `exited` |

Example on what a `suggest` function might look like:
```js
const suggestByTitle = (input, choices) =>
    Promise.resolve(choices.filter(i => i.title.slice(0, input.length) === input))
```

**↑ back to:** [Prompt types](#-types)

***

### date(message, [initial], [warn])
> Interactive date prompt.

Use <kbd>left</kbd>/<kbd>right</kbd>/<kbd>tab</kbd> to navigate. Use <kbd>up</kbd>/<kbd>down</kbd> to change date.

#### Example
<img src="https://github.com/terkelg/prompts/raw/master/media/date.gif" alt="date prompt" width="499" height="103" />

```js
{
  type: 'date',
  name: 'value',
  message: 'Pick a date',
  initial: new Date(1997, 09, 12),
  validate: date => date > Date.now() ? 'Not in the future' : true
}
```

#### Options
| Param | Type | Description |
| ----- | :--: | ----------- |
| message | `string` | Prompt message to display |
| initial | `date` | Default date |
| locales | `object` | Use to define custom locales. See below for an example. |
| mask | `string` | The format mask of the date. See below for more information.<br />Default: `YYYY-MM-DD HH:mm:ss` |
| validate | `function` | Receive user input. Should return `true` if the value is valid, and an error message `String` otherwise. If `false` is returned, a default error message is shown |
| onRender | `function` | On render callback. Keyword `this` refers to the current prompt |
| onState | `function` | On state change callback. Function signature is an `object` with two properties: `value` and `aborted` |

Default locales:

```javascript
{
  months: [
    'January', 'February', 'March', 'April',
    'May', 'June', 'July', 'August',
    'September', 'October', 'November', 'December'
  ],
  monthsShort: [
    'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
    'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
  ],
  weekdays: [
    'Sunday', 'Monday', 'Tuesday', 'Wednesday',
    'Thursday', 'Friday', 'Saturday'
  ],
  weekdaysShort: [
    'Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'
  ]
}
```
>**Formatting**: See full list of formatting options in the [wiki](https://github.com/terkelg/prompts/wiki/Date-Time-Formatting)

![split](https://github.com/terkelg/prompts/raw/master/media/split.png)

**↑ back to:** [Prompt types](#-types)

***

## ❯ Credit
Many of the prompts are based on the work of [derhuerst](https://github.com/derhuerst).


## ❯ License

MIT © [Terkel Gjervig](https://terkel.com)


---

# prop-types [![Build Status](https://travis-ci.com/facebook/prop-types.svg?branch=main)](https://travis-ci.org/facebook/prop-types)

Runtime type checking for React props and similar objects.

You can use prop-types to document the intended types of properties passed to
components. React (and potentially other libraries—see the `checkPropTypes()`
reference below) will check props passed to your components against those
definitions, and warn in development if they don’t match.

## Installation

```shell
npm install --save prop-types
```

## Importing

```js
import PropTypes from 'prop-types'; // ES6
var PropTypes = require('prop-types'); // ES5 with npm
```

### CDN

If you prefer to exclude `prop-types` from your application and use it
globally via `window.PropTypes`, the `prop-types` package provides
single-file distributions, which are hosted on the following CDNs:

* [**unpkg**](https://unpkg.com/prop-types/)
```html
<!-- development version -->
<script src="https://unpkg.com/prop-types@15.6/prop-types.js"></script>

<!-- production version -->
<script src="https://unpkg.com/prop-types@15.6/prop-types.min.js"></script>
```

* [**cdnjs**](https://cdnjs.com/libraries/prop-types)
```html
<!-- development version -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/prop-types/15.6.0/prop-types.js"></script>

<!-- production version -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/prop-types/15.6.0/prop-types.min.js"></script>
```

To load a specific version of `prop-types` replace `15.6.0` with the version number.

## Usage

PropTypes was originally exposed as part of the React core module, and is
commonly used with React components.
Here is an example of using PropTypes with a React component, which also
documents the different validators provided:

```js
import React from 'react';
import PropTypes from 'prop-types';

class MyComponent extends React.Component {
  render() {
    // ... do things with the props
  }
}

MyComponent.propTypes = {
  // You can declare that a prop is a specific JS primitive. By default, these
  // are all optional.
  optionalArray: PropTypes.array,
  optionalBigInt: PropTypes.bigint,
  optionalBool: PropTypes.bool,
  optionalFunc: PropTypes.func,
  optionalNumber: PropTypes.number,
  optionalObject: PropTypes.object,
  optionalString: PropTypes.string,
  optionalSymbol: PropTypes.symbol,

  // Anything that can be rendered: numbers, strings, elements or an array
  // (or fragment) containing these types.
  // see https://reactjs.org/docs/rendering-elements.html for more info
  optionalNode: PropTypes.node,

  // A React element (ie. <MyComponent />).
  optionalElement: PropTypes.element,

  // A React element type (eg. MyComponent).
  // a function, string, or "element-like" object (eg. React.Fragment, Suspense, etc.)
  // see https://github.com/facebook/react/blob/HEAD/packages/shared/isValidElementType.js
  optionalElementType: PropTypes.elementType,

  // You can also declare that a prop is an instance of a class. This uses
  // JS's instanceof operator.
  optionalMessage: PropTypes.instanceOf(Message),

  // You can ensure that your prop is limited to specific values by treating
  // it as an enum.
  optionalEnum: PropTypes.oneOf(['News', 'Photos']),

  // An object that could be one of many types
  optionalUnion: PropTypes.oneOfType([
    PropTypes.string,
    PropTypes.number,
    PropTypes.instanceOf(Message)
  ]),

  // An array of a certain type
  optionalArrayOf: PropTypes.arrayOf(PropTypes.number),

  // An object with property values of a certain type
  optionalObjectOf: PropTypes.objectOf(PropTypes.number),

  // You can chain any of the above with `isRequired` to make sure a warning
  // is shown if the prop isn't provided.

  // An object taking on a particular shape
  optionalObjectWithShape: PropTypes.shape({
    optionalProperty: PropTypes.string,
    requiredProperty: PropTypes.number.isRequired
  }),

  // An object with warnings on extra properties
  optionalObjectWithStrictShape: PropTypes.exact({
    optionalProperty: PropTypes.string,
    requiredProperty: PropTypes.number.isRequired
  }),

  requiredFunc: PropTypes.func.isRequired,

  // A value of any data type
  requiredAny: PropTypes.any.isRequired,

  // You can also specify a custom validator. It should return an Error
  // object if the validation fails. Don't `console.warn` or throw, as this
  // won't work inside `oneOfType`.
  customProp: function(props, propName, componentName) {
    if (!/matchme/.test(props[propName])) {
      return new Error(
        'Invalid prop `' + propName + '` supplied to' +
        ' `' + componentName + '`. Validation failed.'
      );
    }
  },

  // You can also supply a custom validator to `arrayOf` and `objectOf`.
  // It should return an Error object if the validation fails. The validator
  // will be called for each key in the array or object. The first two
  // arguments of the validator are the array or object itself, and the
  // current item's key.
  customArrayProp: PropTypes.arrayOf(function(propValue, key, componentName, location, propFullName) {
    if (!/matchme/.test(propValue[key])) {
      return new Error(
        'Invalid prop `' + propFullName + '` supplied to' +
        ' `' + componentName + '`. Validation failed.'
      );
    }
  })
};
```

Refer to the [React documentation](https://facebook.github.io/react/docs/typechecking-with-proptypes.html) for more information.

## Migrating from React.PropTypes

Check out [Migrating from React.PropTypes](https://facebook.github.io/react/blog/2017/04/07/react-v15.5.0.html#migrating-from-react.proptypes) for details on how to migrate to `prop-types` from `React.PropTypes`.

Note that this blog posts **mentions a codemod script that performs the conversion automatically**.

There are also important notes below.

## How to Depend on This Package?

For apps, we recommend putting it in `dependencies` with a caret range.
For example:

```js
  "dependencies": {
    "prop-types": "^15.5.7"
  }
```

For libraries, we *also* recommend leaving it in `dependencies`:

```js
  "dependencies": {
    "prop-types": "^15.5.7"
  },
  "peerDependencies": {
    "react": "^15.5.0"
  }
```

**Note:** there are known issues in versions before 15.5.7 so we recommend using it as the minimal version.

Make sure that the version range uses a caret (`^`) and thus is broad enough for npm to efficiently deduplicate packages.

For UMD bundles of your components, make sure you **don’t** include `PropTypes` in the build. Usually this is done by marking it as an external (the specifics depend on your bundler), just like you do with React.

## Compatibility

### React 0.14

This package is compatible with **React 0.14.9**. Compared to 0.14.8 (which was released in March of 2016), there are no other changes in 0.14.9, so it should be a painless upgrade.

```shell
# ATTENTION: Only run this if you still use React 0.14!
npm install --save react@^0.14.9 react-dom@^0.14.9
```

### React 15+

This package is compatible with **React 15.3.0** and higher.

```
npm install --save react@^15.3.0 react-dom@^15.3.0
```

### What happens on other React versions?

It outputs warnings with the message below even though the developer doesn’t do anything wrong. Unfortunately there is no solution for this other than updating React to either 15.3.0 or higher, or 0.14.9 if you’re using React 0.14.

## Difference from `React.PropTypes`: Don’t Call Validator Functions

First of all, **which version of React are you using**? You might be seeing this message because a component library has updated to use `prop-types` package, but your version of React is incompatible with it. See the [above section](#compatibility) for more details.

Are you using either React 0.14.9 or a version higher than React 15.3.0? Read on.

When you migrate components to use the standalone `prop-types`, **all validator functions will start throwing an error if you call them directly**. This makes sure that nobody relies on them in production code, and it is safe to strip their implementations to optimize the bundle size.

Code like this is still fine:

```js
MyComponent.propTypes = {
  myProp: PropTypes.bool
};
```

However, code like this will not work with the `prop-types` package:

```js
// Will not work with `prop-types` package!
var errorOrNull = PropTypes.bool(42, 'myProp', 'MyComponent', 'prop');
```

It will throw an error:

```
Calling PropTypes validators directly is not supported by the `prop-types` package.
Use PropTypes.checkPropTypes() to call them.
```

(If you see **a warning** rather than an error with this message, please check the [above section about compatibility](#compatibility).)

This is new behavior, and you will only encounter it when you migrate from `React.PropTypes` to the `prop-types` package. For the vast majority of components, this doesn’t matter, and if you didn’t see [this warning](https://facebook.github.io/react/warnings/dont-call-proptypes.html) in your components, your code is safe to migrate. This is not a breaking change in React because you are only opting into this change for a component by explicitly changing your imports to use `prop-types`. If you temporarily need the old behavior, you can keep using `React.PropTypes` until React 16.

**If you absolutely need to trigger the validation manually**, call `PropTypes.checkPropTypes()`. Unlike the validators themselves, this function is safe to call in production, as it will be replaced by an empty function:

```js
// Works with standalone PropTypes
PropTypes.checkPropTypes(MyComponent.propTypes, props, 'prop', 'MyComponent');
```
See below for more info.

**If you DO want to use validation in production**, you can choose to use the **development version** by importing/requiring `prop-types/prop-types` instead of `prop-types`.

**You might also see this error** if you’re calling a `PropTypes` validator from your own custom `PropTypes` validator. In this case, the fix is to make sure that you are passing *all* of the arguments to the inner function. There is a more in-depth explanation of how to fix it [on this page](https://facebook.github.io/react/warnings/dont-call-proptypes.html#fixing-the-false-positive-in-third-party-proptypes). Alternatively, you can temporarily keep using `React.PropTypes` until React 16, as it would still only warn in this case.

If you use a bundler like Browserify or Webpack, don’t forget to [follow these instructions](https://reactjs.org/docs/optimizing-performance.html#use-the-production-build) to correctly bundle your application in development or production mode. Otherwise you’ll ship unnecessary code to your users.

## PropTypes.checkPropTypes

React will automatically check the propTypes you set on the component, but if
you are using PropTypes without React then you may want to manually call
`PropTypes.checkPropTypes`, like so:

```js
const myPropTypes = {
  name: PropTypes.string,
  age: PropTypes.number,
  // ... define your prop validations
};

const props = {
  name: 'hello', // is valid
  age: 'world', // not valid
};

// Let's say your component is called 'MyComponent'

// Works with standalone PropTypes
PropTypes.checkPropTypes(myPropTypes, props, 'prop', 'MyComponent');
// This will warn as follows:
// Warning: Failed prop type: Invalid prop `age` of type `string` supplied to
// `MyComponent`, expected `number`.
```

## PropTypes.resetWarningCache()

`PropTypes.checkPropTypes(...)` only `console.error`s a given message once. To reset the error warning cache in tests, call `PropTypes.resetWarningCache()`

### License

prop-types is [MIT licensed](./LICENSE).


---

# property-information

[![Build][badge-build-image]][badge-build-url]
[![Coverage][badge-coverage-image]][badge-coverage-url]
[![Downloads][badge-downloads-image]][badge-downloads-url]
[![Size][badge-size-image]][badge-size-url]

Info on the properties and attributes of the web platform
(HTML, SVG, ARIA, XML, XMLNS, XLink).

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`Info`](#info)
  * [`Schema`](#schema)
  * [`Space`](#space)
  * [`find(schema, name)`](#findschema-name)
  * [`hastToReact`](#hasttoreact)
  * [`html`](#html)
  * [`normalize(name)`](#normalizename)
  * [`svg`](#svg)
* [Compatibility](#compatibility)
* [Support](#support)
* [Security](#security)
* [Related](#related)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package contains lots of info on all the properties and attributes found
on the web platform.
It includes data on
HTML, SVG, ARIA, XML, XMLNS, and XLink.
The names of the properties follow [hast][github-hast-property-name]’s
sensible naming scheme.
It includes info on what data types attributes hold,
such as whether they’re booleans or contain lists of space separated numbers.

## When should I use this?

You can use this package if you’re working with hast,
which is an AST for HTML,
or have goals related to ASTs,
such as figuring out which properties or attributes are valid,
or what data types they hold.

## Install

This package is [ESM only][github-gist-esm].
In Node.js (version 16+),
install with [npm][npmjs-install]:

```sh
npm install property-information
```

In Deno with [`esm.sh`][esmsh]:

```js
import * as propertyInformation from 'https://esm.sh/property-information@7'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import * as propertyInformation from 'https://esm.sh/property-information@7?bundle'
</script>
```

## Use

```js
import {find, html, svg} from 'property-information'

console.log(find(html, 'className'))
// Or: find(html, 'class')
console.log(find(svg, 'horiz-adv-x'))
// Or: find(svg, 'horizAdvX')
console.log(find(svg, 'xlink:arcrole'))
// Or: find(svg, 'xLinkArcRole')
console.log(find(html, 'xmlLang'))
// Or: find(html, 'xml:lang')
console.log(find(html, 'ariaValueNow'))
// Or: find(html, 'aria-valuenow')
```

Yields:

```js
{attribute: 'class', property: 'className', spaceSeparated: true, space: 'html'}
{attribute: 'horiz-adv-x', number: true, property: 'horizAdvX', space: 'svg'}
{attribute: 'xlink:arcrole', property: 'xLinkArcRole', space: 'xlink'}
{attribute: 'xml:lang', property: 'xmlLang', space: 'xml'}
{attribute: 'aria-valuenow', number: true, property: 'ariaValueNow'}
```

## API

This package exports the identifiers
[`find`][api-find],
[`hastToReact`][api-hast-to-react],
[`html`][api-html],
[`normalize`][api-normalize],
and
[`svg`][api-svg].
There is no default export.
It exports the [TypeScript][] types
[`Info`][api-info],
[`Schema`][api-schema],
and
[`Space`][api-space].

### `Info`

Info on a property (TypeScript type).

###### Fields

* `attribute` (`string`)
  — attribute name for the property that could be used in markup
  (such as `'aria-describedby'`, `'allowfullscreen'`, `'xml:lang'`, `'for'`,
  or `'charoff'`)
* `booleanish` (`boolean`)
  — the property is *like* a `boolean`
  (such as `draggable`);
  these properties have both an on and off state when defined,
  *and* another state when not defined
* `boolean` (`boolean`)
  — the property is a `boolean`
  (such as `hidden`);
  these properties have an on state when defined and an off state when not
  defined
* `commaOrSpaceSeparated` (`boolean`)
  — the property is a list separated by spaces or commas
  (such as `strokeDashArray`)
* `commaSeparated` (`boolean`)
  — the property is a list separated by commas
  (such as `coords`)
* `defined` (`boolean`)
  — the property is [defined by a space][section-support];
  this is the case for values in HTML
  (including [data][mozilla-dataset] and ARIA),
  SVG, XML, XMLNS, and XLink;
  not defined properties can only be found through `find`
* `mustUseProperty` (`boolean`)
  — when working with the DOM,
  this property has to be changed as a field on the element,
  instead of through `setAttribute`
  (this is true only for `'checked'`, `'multiple'`, `'muted'`, and
  `'selected'`)
* `number` (`boolean`)
  — the property is a `number` (such as `height`)
* `overloadedBoolean` (`boolean`)
  — the property is *like* a `boolean` (such as `download`);
  these properties have an on state *and* more states when defined and an off
  state when not defined
* `property` (`string`)
  — JavaScript-style camel-cased name;
  based on the DOM but sometimes different
  (such as `'ariaDescribedBy'`, `'allowFullScreen'`, `'xmlLang'`, `'htmlFor'`,
  `'charOff'`)
* `spaceSeparated` (`boolean`)
  — the property is a list separated by spaces
  (such as `className`)
* `space` ([`Space`][api-space] or `undefined`)
  — [space][github-web-namespaces] of the property

### `Schema`

Schema for a primary space (TypeScript type).

###### Fields

* `normal` (`Record<string, string>`)
  — object mapping normalized attributes and properties to properly cased
  properties
* `property` ([`Record<string, Info>`][api-info])
  — object mapping properties to info
* `space` (`'html'` or `'svg'`)
  — primary space of the schema

### `Space`

Space of a property (TypeScript type).

###### Type

```ts
type Space = 'html' | 'svg' | 'xlink' | 'xmlns' | 'xml'
```

### `find(schema, name)`

Look up info on a property.

In most cases the given `schema` contains info on the property.
All standard,
most legacy,
and some non-standard properties are supported.
For these cases,
the returned [`Info`][api-info] has hints about the value of the property.

`name` can also be a [valid data attribute or property][mozilla-dataset],
in which case an [`Info`][api-info] object with the correctly cased `attribute`
and `property` is returned.

`name` can be an unknown attribute,
in which case an [`Info`][api-info] object with `attribute` and `property` set
to the given name is returned.
It is not recommended to provide unsupported legacy or recently specced
properties.

###### Parameters

* `schema` ([`Schema`][api-schema])
  — schema;
  either the `html` or `svg` export
* `name` (`string`)
  — an attribute-like or property-like name;
  it will be passed through
  [`normalize`][api-normalize] to hopefully find the correct info

###### Returns

[`Info`][api-info].

###### Example

Aside from the aforementioned example,
which shows known HTML, SVG, XML, XLink, and ARIA support,
data properties and attributes are also supported:

```js
console.log(find(html, 'data-date-of-birth'))
// Or: find(html, 'dataDateOfBirth')
// => {attribute: 'data-date-of-birth', property: 'dataDateOfBirth'}
```

Unknown values are passed through untouched:

```js
console.log(find(html, 'un-Known'))
// => {attribute: 'un-Known', property: 'un-Known'}
```

### `hastToReact`

Special cases for React (`Record<string, string>`).

[`hast`][github-hast] is close to [`React`][github-react]
but differs in a couple of cases.
To get a React property from a hast property,
check if it is in `hastToReact`.
If it is,
use the corresponding value.

### `html`

[`Schema`][api-schema] for HTML,
with info on properties from HTML itself and related embedded spaces
(ARIA, XML, XMLNS, XLink).

###### Example

```js
console.log(html.property.htmlFor)
// => {attribute: 'for', property: 'htmlFor', spaceSeparated: true, space: 'html'}
console.log(html.property.unknown)
// => undefined
```

### `normalize(name)`

Get the cleaned case insensitive form of an attribute or property.

###### Parameters

* `name` (`string`)
  — an attribute-like or property-like name

###### Returns

Value (`string`) that can be used to look up the properly cased property on a
[`Schema`][api-schema].

###### Example

```js
html.normal[normalize('for')] // => 'htmlFor'
svg.normal[normalize('VIEWBOX')] // => 'viewBox'
html.normal[normalize('unknown')] // => undefined
html.normal[normalize('accept-charset')] // => 'acceptCharset'
```

### `svg`

[`Schema`][api-schema] for SVG,
with info on properties from SVG itself and related embedded spaces
(ARIA, XML, XMLNS, XLink).

###### Example

```js
console.log(svg.property.viewBox)
// => {attribute: 'viewBox', property: 'viewBox', space: 'svg'}
console.log(svg.property.unknown)
// => undefined
```

## Compatibility

This package is at least compatible with all maintained versions of Node.js.
As of now,
that is Node.js 16+.
It also works in Deno and modern browsers.

## Support

<!--list start-->

| Property                     | Attribute                      | Space         |
| ---------------------------- | ------------------------------ | ------------- |
| `aLink`                      | `alink`                        | `html`        |
| `abbr`                       | `abbr`                         | `html`        |
| `about`                      | `about`                        | `svg`         |
| `accentHeight`               | `accent-height`                | `svg`         |
| `accept`                     | `accept`                       | `html`        |
| `acceptCharset`              | `accept-charset`               | `html`        |
| `accessKey`                  | `accesskey`                    | `html`        |
| `accumulate`                 | `accumulate`                   | `svg`         |
| `action`                     | `action`                       | `html`        |
| `additive`                   | `additive`                     | `svg`         |
| `align`                      | `align`                        | `html`        |
| `alignmentBaseline`          | `alignment-baseline`           | `svg`         |
| `allow`                      | `allow`                        | `html`        |
| `allowFullScreen`            | `allowfullscreen`              | `html`        |
| `allowPaymentRequest`        | `allowpaymentrequest`          | `html`        |
| `allowTransparency`          | `allowtransparency`            | `html`        |
| `allowUserMedia`             | `allowusermedia`               | `html`        |
| `alphabetic`                 | `alphabetic`                   | `svg`         |
| `alt`                        | `alt`                          | `html`        |
| `amplitude`                  | `amplitude`                    | `svg`         |
| `arabicForm`                 | `arabic-form`                  | `svg`         |
| `archive`                    | `archive`                      | `html`        |
| `ariaActiveDescendant`       | `aria-activedescendant`        |               |
| `ariaAtomic`                 | `aria-atomic`                  |               |
| `ariaAutoComplete`           | `aria-autocomplete`            |               |
| `ariaBusy`                   | `aria-busy`                    |               |
| `ariaChecked`                | `aria-checked`                 |               |
| `ariaColCount`               | `aria-colcount`                |               |
| `ariaColIndex`               | `aria-colindex`                |               |
| `ariaColSpan`                | `aria-colspan`                 |               |
| `ariaControls`               | `aria-controls`                |               |
| `ariaCurrent`                | `aria-current`                 |               |
| `ariaDescribedBy`            | `aria-describedby`             |               |
| `ariaDetails`                | `aria-details`                 |               |
| `ariaDisabled`               | `aria-disabled`                |               |
| `ariaDropEffect`             | `aria-dropeffect`              |               |
| `ariaErrorMessage`           | `aria-errormessage`            |               |
| `ariaExpanded`               | `aria-expanded`                |               |
| `ariaFlowTo`                 | `aria-flowto`                  |               |
| `ariaGrabbed`                | `aria-grabbed`                 |               |
| `ariaHasPopup`               | `aria-haspopup`                |               |
| `ariaHidden`                 | `aria-hidden`                  |               |
| `ariaInvalid`                | `aria-invalid`                 |               |
| `ariaKeyShortcuts`           | `aria-keyshortcuts`            |               |
| `ariaLabel`                  | `aria-label`                   |               |
| `ariaLabelledBy`             | `aria-labelledby`              |               |
| `ariaLevel`                  | `aria-level`                   |               |
| `ariaLive`                   | `aria-live`                    |               |
| `ariaModal`                  | `aria-modal`                   |               |
| `ariaMultiLine`              | `aria-multiline`               |               |
| `ariaMultiSelectable`        | `aria-multiselectable`         |               |
| `ariaOrientation`            | `aria-orientation`             |               |
| `ariaOwns`                   | `aria-owns`                    |               |
| `ariaPlaceholder`            | `aria-placeholder`             |               |
| `ariaPosInSet`               | `aria-posinset`                |               |
| `ariaPressed`                | `aria-pressed`                 |               |
| `ariaReadOnly`               | `aria-readonly`                |               |
| `ariaRelevant`               | `aria-relevant`                |               |
| `ariaRequired`               | `aria-required`                |               |
| `ariaRoleDescription`        | `aria-roledescription`         |               |
| `ariaRowCount`               | `aria-rowcount`                |               |
| `ariaRowIndex`               | `aria-rowindex`                |               |
| `ariaRowSpan`                | `aria-rowspan`                 |               |
| `ariaSelected`               | `aria-selected`                |               |
| `ariaSetSize`                | `aria-setsize`                 |               |
| `ariaSort`                   | `aria-sort`                    |               |
| `ariaValueMax`               | `aria-valuemax`                |               |
| `ariaValueMin`               | `aria-valuemin`                |               |
| `ariaValueNow`               | `aria-valuenow`                |               |
| `ariaValueText`              | `aria-valuetext`               |               |
| `as`                         | `as`                           | `html`        |
| `ascent`                     | `ascent`                       | `svg`         |
| `async`                      | `async`                        | `html`        |
| `attributeName`              | `attributeName`                | `svg`         |
| `attributeType`              | `attributeType`                | `svg`         |
| `autoCapitalize`             | `autocapitalize`               | `html`        |
| `autoComplete`               | `autocomplete`                 | `html`        |
| `autoCorrect`                | `autocorrect`                  | `html`        |
| `autoFocus`                  | `autofocus`                    | `html`        |
| `autoPlay`                   | `autoplay`                     | `html`        |
| `autoSave`                   | `autosave`                     | `html`        |
| `axis`                       | `axis`                         | `html`        |
| `azimuth`                    | `azimuth`                      | `svg`         |
| `background`                 | `background`                   | `html`        |
| `bandwidth`                  | `bandwidth`                    | `svg`         |
| `baseFrequency`              | `baseFrequency`                | `svg`         |
| `baseProfile`                | `baseProfile`                  | `svg`         |
| `baselineShift`              | `baseline-shift`               | `svg`         |
| `bbox`                       | `bbox`                         | `svg`         |
| `begin`                      | `begin`                        | `svg`         |
| `bgColor`                    | `bgcolor`                      | `html`        |
| `bias`                       | `bias`                         | `svg`         |
| `blocking`                   | `blocking`                     | `html`        |
| `border`                     | `border`                       | `html`        |
| `borderColor`                | `bordercolor`                  | `html`        |
| `bottomMargin`               | `bottommargin`                 | `html`        |
| `by`                         | `by`                           | `svg`         |
| `calcMode`                   | `calcMode`                     | `svg`         |
| `capHeight`                  | `cap-height`                   | `svg`         |
| `capture`                    | `capture`                      | `html`        |
| `cellPadding`                | `cellpadding`                  | `html`        |
| `cellSpacing`                | `cellspacing`                  | `html`        |
| `char`                       | `char`                         | `html`        |
| `charOff`                    | `charoff`                      | `html`        |
| `charSet`                    | `charset`                      | `html`        |
| `checked`                    | `checked`                      | `html`        |
| `cite`                       | `cite`                         | `html`        |
| `classId`                    | `classid`                      | `html`        |
| `className`                  | `class`                        | `svg`, `html` |
| `clear`                      | `clear`                        | `html`        |
| `clip`                       | `clip`                         | `svg`         |
| `clipPath`                   | `clip-path`                    | `svg`         |
| `clipPathUnits`              | `clipPathUnits`                | `svg`         |
| `clipRule`                   | `clip-rule`                    | `svg`         |
| `code`                       | `code`                         | `html`        |
| `codeBase`                   | `codebase`                     | `html`        |
| `codeType`                   | `codetype`                     | `html`        |
| `colSpan`                    | `colspan`                      | `html`        |
| `color`                      | `color`                        | `svg`, `html` |
| `colorInterpolation`         | `color-interpolation`          | `svg`         |
| `colorInterpolationFilters`  | `color-interpolation-filters`  | `svg`         |
| `colorProfile`               | `color-profile`                | `svg`         |
| `colorRendering`             | `color-rendering`              | `svg`         |
| `cols`                       | `cols`                         | `html`        |
| `compact`                    | `compact`                      | `html`        |
| `content`                    | `content`                      | `svg`, `html` |
| `contentEditable`            | `contenteditable`              | `html`        |
| `contentScriptType`          | `contentScriptType`            | `svg`         |
| `contentStyleType`           | `contentStyleType`             | `svg`         |
| `controls`                   | `controls`                     | `html`        |
| `controlsList`               | `controlslist`                 | `html`        |
| `coords`                     | `coords`                       | `html`        |
| `crossOrigin`                | `crossorigin`                  | `svg`, `html` |
| `cursor`                     | `cursor`                       | `svg`         |
| `cx`                         | `cx`                           | `svg`         |
| `cy`                         | `cy`                           | `svg`         |
| `d`                          | `d`                            | `svg`         |
| `data`                       | `data`                         | `html`        |
| `dataType`                   | `datatype`                     | `svg`         |
| `dateTime`                   | `datetime`                     | `html`        |
| `declare`                    | `declare`                      | `html`        |
| `decoding`                   | `decoding`                     | `html`        |
| `default`                    | `default`                      | `html`        |
| `defaultAction`              | `defaultAction`                | `svg`         |
| `defer`                      | `defer`                        | `html`        |
| `descent`                    | `descent`                      | `svg`         |
| `diffuseConstant`            | `diffuseConstant`              | `svg`         |
| `dir`                        | `dir`                          | `html`        |
| `dirName`                    | `dirname`                      | `html`        |
| `direction`                  | `direction`                    | `svg`         |
| `disablePictureInPicture`    | `disablepictureinpicture`      | `html`        |
| `disableRemotePlayback`      | `disableremoteplayback`        | `html`        |
| `disabled`                   | `disabled`                     | `html`        |
| `display`                    | `display`                      | `svg`         |
| `divisor`                    | `divisor`                      | `svg`         |
| `dominantBaseline`           | `dominant-baseline`            | `svg`         |
| `download`                   | `download`                     | `svg`, `html` |
| `draggable`                  | `draggable`                    | `html`        |
| `dur`                        | `dur`                          | `svg`         |
| `dx`                         | `dx`                           | `svg`         |
| `dy`                         | `dy`                           | `svg`         |
| `edgeMode`                   | `edgeMode`                     | `svg`         |
| `editable`                   | `editable`                     | `svg`         |
| `elevation`                  | `elevation`                    | `svg`         |
| `enableBackground`           | `enable-background`            | `svg`         |
| `encType`                    | `enctype`                      | `html`        |
| `end`                        | `end`                          | `svg`         |
| `enterKeyHint`               | `enterkeyhint`                 | `html`        |
| `event`                      | `event`                        | `svg`, `html` |
| `exponent`                   | `exponent`                     | `svg`         |
| `externalResourcesRequired`  | `externalResourcesRequired`    | `svg`         |
| `face`                       | `face`                         | `html`        |
| `fetchPriority`              | `fetchpriority`                | `html`        |
| `fill`                       | `fill`                         | `svg`         |
| `fillOpacity`                | `fill-opacity`                 | `svg`         |
| `fillRule`                   | `fill-rule`                    | `svg`         |
| `filter`                     | `filter`                       | `svg`         |
| `filterRes`                  | `filterRes`                    | `svg`         |
| `filterUnits`                | `filterUnits`                  | `svg`         |
| `floodColor`                 | `flood-color`                  | `svg`         |
| `floodOpacity`               | `flood-opacity`                | `svg`         |
| `focusHighlight`             | `focusHighlight`               | `svg`         |
| `focusable`                  | `focusable`                    | `svg`         |
| `fontFamily`                 | `font-family`                  | `svg`         |
| `fontSize`                   | `font-size`                    | `svg`         |
| `fontSizeAdjust`             | `font-size-adjust`             | `svg`         |
| `fontStretch`                | `font-stretch`                 | `svg`         |
| `fontStyle`                  | `font-style`                   | `svg`         |
| `fontVariant`                | `font-variant`                 | `svg`         |
| `fontWeight`                 | `font-weight`                  | `svg`         |
| `form`                       | `form`                         | `html`        |
| `formAction`                 | `formaction`                   | `html`        |
| `formEncType`                | `formenctype`                  | `html`        |
| `formMethod`                 | `formmethod`                   | `html`        |
| `formNoValidate`             | `formnovalidate`               | `html`        |
| `formTarget`                 | `formtarget`                   | `html`        |
| `format`                     | `format`                       | `svg`         |
| `fr`                         | `fr`                           | `svg`         |
| `frame`                      | `frame`                        | `html`        |
| `frameBorder`                | `frameborder`                  | `html`        |
| `from`                       | `from`                         | `svg`         |
| `fx`                         | `fx`                           | `svg`         |
| `fy`                         | `fy`                           | `svg`         |
| `g1`                         | `g1`                           | `svg`         |
| `g2`                         | `g2`                           | `svg`         |
| `glyphName`                  | `glyph-name`                   | `svg`         |
| `glyphOrientationHorizontal` | `glyph-orientation-horizontal` | `svg`         |
| `glyphOrientationVertical`   | `glyph-orientation-vertical`   | `svg`         |
| `glyphRef`                   | `glyphRef`                     | `svg`         |
| `gradientTransform`          | `gradientTransform`            | `svg`         |
| `gradientUnits`              | `gradientUnits`                | `svg`         |
| `hSpace`                     | `hspace`                       | `html`        |
| `handler`                    | `handler`                      | `svg`         |
| `hanging`                    | `hanging`                      | `svg`         |
| `hatchContentUnits`          | `hatchContentUnits`            | `svg`         |
| `hatchUnits`                 | `hatchUnits`                   | `svg`         |
| `headers`                    | `headers`                      | `html`        |
| `height`                     | `height`                       | `svg`, `html` |
| `hidden`                     | `hidden`                       | `html`        |
| `high`                       | `high`                         | `html`        |
| `horizAdvX`                  | `horiz-adv-x`                  | `svg`         |
| `horizOriginX`               | `horiz-origin-x`               | `svg`         |
| `horizOriginY`               | `horiz-origin-y`               | `svg`         |
| `href`                       | `href`                         | `svg`, `html` |
| `hrefLang`                   | `hreflang`                     | `svg`, `html` |
| `htmlFor`                    | `for`                          | `html`        |
| `httpEquiv`                  | `http-equiv`                   | `html`        |
| `id`                         | `id`                           | `svg`, `html` |
| `ideographic`                | `ideographic`                  | `svg`         |
| `imageRendering`             | `image-rendering`              | `svg`         |
| `imageSizes`                 | `imagesizes`                   | `html`        |
| `imageSrcSet`                | `imagesrcset`                  | `html`        |
| `in`                         | `in`                           | `svg`         |
| `in2`                        | `in2`                          | `svg`         |
| `inert`                      | `inert`                        | `html`        |
| `initialVisibility`          | `initialVisibility`            | `svg`         |
| `inputMode`                  | `inputmode`                    | `html`        |
| `integrity`                  | `integrity`                    | `html`        |
| `intercept`                  | `intercept`                    | `svg`         |
| `is`                         | `is`                           | `html`        |
| `isMap`                      | `ismap`                        | `html`        |
| `itemId`                     | `itemid`                       | `html`        |
| `itemProp`                   | `itemprop`                     | `html`        |
| `itemRef`                    | `itemref`                      | `html`        |
| `itemScope`                  | `itemscope`                    | `html`        |
| `itemType`                   | `itemtype`                     | `html`        |
| `k`                          | `k`                            | `svg`         |
| `k1`                         | `k1`                           | `svg`         |
| `k2`                         | `k2`                           | `svg`         |
| `k3`                         | `k3`                           | `svg`         |
| `k4`                         | `k4`                           | `svg`         |
| `kernelMatrix`               | `kernelMatrix`                 | `svg`         |
| `kernelUnitLength`           | `kernelUnitLength`             | `svg`         |
| `kerning`                    | `kerning`                      | `svg`         |
| `keyPoints`                  | `keyPoints`                    | `svg`         |
| `keySplines`                 | `keySplines`                   | `svg`         |
| `keyTimes`                   | `keyTimes`                     | `svg`         |
| `kind`                       | `kind`                         | `html`        |
| `label`                      | `label`                        | `html`        |
| `lang`                       | `lang`                         | `svg`, `html` |
| `language`                   | `language`                     | `html`        |
| `leftMargin`                 | `leftmargin`                   | `html`        |
| `lengthAdjust`               | `lengthAdjust`                 | `svg`         |
| `letterSpacing`              | `letter-spacing`               | `svg`         |
| `lightingColor`              | `lighting-color`               | `svg`         |
| `limitingConeAngle`          | `limitingConeAngle`            | `svg`         |
| `link`                       | `link`                         | `html`        |
| `list`                       | `list`                         | `html`        |
| `loading`                    | `loading`                      | `html`        |
| `local`                      | `local`                        | `svg`         |
| `longDesc`                   | `longdesc`                     | `html`        |
| `loop`                       | `loop`                         | `html`        |
| `low`                        | `low`                          | `html`        |
| `lowSrc`                     | `lowsrc`                       | `html`        |
| `manifest`                   | `manifest`                     | `html`        |
| `marginHeight`               | `marginheight`                 | `html`        |
| `marginWidth`                | `marginwidth`                  | `html`        |
| `markerEnd`                  | `marker-end`                   | `svg`         |
| `markerHeight`               | `markerHeight`                 | `svg`         |
| `markerMid`                  | `marker-mid`                   | `svg`         |
| `markerStart`                | `marker-start`                 | `svg`         |
| `markerUnits`                | `markerUnits`                  | `svg`         |
| `markerWidth`                | `markerWidth`                  | `svg`         |
| `mask`                       | `mask`                         | `svg`         |
| `maskContentUnits`           | `maskContentUnits`             | `svg`         |
| `maskUnits`                  | `maskUnits`                    | `svg`         |
| `mathematical`               | `mathematical`                 | `svg`         |
| `max`                        | `max`                          | `svg`, `html` |
| `maxLength`                  | `maxlength`                    | `html`        |
| `media`                      | `media`                        | `svg`, `html` |
| `mediaCharacterEncoding`     | `mediaCharacterEncoding`       | `svg`         |
| `mediaContentEncodings`      | `mediaContentEncodings`        | `svg`         |
| `mediaSize`                  | `mediaSize`                    | `svg`         |
| `mediaTime`                  | `mediaTime`                    | `svg`         |
| `method`                     | `method`                       | `svg`, `html` |
| `min`                        | `min`                          | `svg`, `html` |
| `minLength`                  | `minlength`                    | `html`        |
| `mode`                       | `mode`                         | `svg`         |
| `multiple`                   | `multiple`                     | `html`        |
| `muted`                      | `muted`                        | `html`        |
| `name`                       | `name`                         | `svg`, `html` |
| `navDown`                    | `nav-down`                     | `svg`         |
| `navDownLeft`                | `nav-down-left`                | `svg`         |
| `navDownRight`               | `nav-down-right`               | `svg`         |
| `navLeft`                    | `nav-left`                     | `svg`         |
| `navNext`                    | `nav-next`                     | `svg`         |
| `navPrev`                    | `nav-prev`                     | `svg`         |
| `navRight`                   | `nav-right`                    | `svg`         |
| `navUp`                      | `nav-up`                       | `svg`         |
| `navUpLeft`                  | `nav-up-left`                  | `svg`         |
| `navUpRight`                 | `nav-up-right`                 | `svg`         |
| `noHref`                     | `nohref`                       | `html`        |
| `noModule`                   | `nomodule`                     | `html`        |
| `noResize`                   | `noresize`                     | `html`        |
| `noShade`                    | `noshade`                      | `html`        |
| `noValidate`                 | `novalidate`                   | `html`        |
| `noWrap`                     | `nowrap`                       | `html`        |
| `nonce`                      | `nonce`                        | `html`        |
| `numOctaves`                 | `numOctaves`                   | `svg`         |
| `object`                     | `object`                       | `html`        |
| `observer`                   | `observer`                     | `svg`         |
| `offset`                     | `offset`                       | `svg`         |
| `onAbort`                    | `onabort`                      | `svg`, `html` |
| `onActivate`                 | `onactivate`                   | `svg`         |
| `onAfterPrint`               | `onafterprint`                 | `svg`, `html` |
| `onAuxClick`                 | `onauxclick`                   | `html`        |
| `onBeforeMatch`              | `onbeforematch`                | `html`        |
| `onBeforePrint`              | `onbeforeprint`                | `svg`, `html` |
| `onBeforeToggle`             | `onbeforetoggle`               | `html`        |
| `onBeforeUnload`             | `onbeforeunload`               | `html`        |
| `onBegin`                    | `onbegin`                      | `svg`         |
| `onBlur`                     | `onblur`                       | `html`        |
| `onCanPlay`                  | `oncanplay`                    | `svg`, `html` |
| `onCanPlayThrough`           | `oncanplaythrough`             | `svg`, `html` |
| `onCancel`                   | `oncancel`                     | `svg`, `html` |
| `onChange`                   | `onchange`                     | `svg`, `html` |
| `onClick`                    | `onclick`                      | `svg`, `html` |
| `onClose`                    | `onclose`                      | `svg`, `html` |
| `onContextLost`              | `oncontextlost`                | `html`        |
| `onContextMenu`              | `oncontextmenu`                | `html`        |
| `onContextRestored`          | `oncontextrestored`            | `html`        |
| `onCopy`                     | `oncopy`                       | `svg`, `html` |
| `onCueChange`                | `oncuechange`                  | `svg`, `html` |
| `onCut`                      | `oncut`                        | `svg`, `html` |
| `onDblClick`                 | `ondblclick`                   | `svg`, `html` |
| `onDrag`                     | `ondrag`                       | `svg`, `html` |
| `onDragEnd`                  | `ondragend`                    | `svg`, `html` |
| `onDragEnter`                | `ondragenter`                  | `svg`, `html` |
| `onDragExit`                 | `ondragexit`                   | `svg`, `html` |
| `onDragLeave`                | `ondragleave`                  | `svg`, `html` |
| `onDragOver`                 | `ondragover`                   | `svg`, `html` |
| `onDragStart`                | `ondragstart`                  | `svg`, `html` |
| `onDrop`                     | `ondrop`                       | `svg`, `html` |
| `onDurationChange`           | `ondurationchange`             | `svg`, `html` |
| `onEmptied`                  | `onemptied`                    | `svg`, `html` |
| `onEnd`                      | `onend`                        | `svg`         |
| `onEnded`                    | `onended`                      | `svg`, `html` |
| `onError`                    | `onerror`                      | `svg`, `html` |
| `onFocus`                    | `onfocus`                      | `svg`, `html` |
| `onFocusIn`                  | `onfocusin`                    | `svg`         |
| `onFocusOut`                 | `onfocusout`                   | `svg`         |
| `onFormData`                 | `onformdata`                   | `html`        |
| `onHashChange`               | `onhashchange`                 | `svg`, `html` |
| `onInput`                    | `oninput`                      | `svg`, `html` |
| `onInvalid`                  | `oninvalid`                    | `svg`, `html` |
| `onKeyDown`                  | `onkeydown`                    | `svg`, `html` |
| `onKeyPress`                 | `onkeypress`                   | `svg`, `html` |
| `onKeyUp`                    | `onkeyup`                      | `svg`, `html` |
| `onLanguageChange`           | `onlanguagechange`             | `html`        |
| `onLoad`                     | `onload`                       | `svg`, `html` |
| `onLoadEnd`                  | `onloadend`                    | `html`        |
| `onLoadStart`                | `onloadstart`                  | `svg`, `html` |
| `onLoadedData`               | `onloadeddata`                 | `svg`, `html` |
| `onLoadedMetadata`           | `onloadedmetadata`             | `svg`, `html` |
| `onMessage`                  | `onmessage`                    | `svg`, `html` |
| `onMessageError`             | `onmessageerror`               | `html`        |
| `onMouseDown`                | `onmousedown`                  | `svg`, `html` |
| `onMouseEnter`               | `onmouseenter`                 | `svg`, `html` |
| `onMouseLeave`               | `onmouseleave`                 | `svg`, `html` |
| `onMouseMove`                | `onmousemove`                  | `svg`, `html` |
| `onMouseOut`                 | `onmouseout`                   | `svg`, `html` |
| `onMouseOver`                | `onmouseover`                  | `svg`, `html` |
| `onMouseUp`                  | `onmouseup`                    | `svg`, `html` |
| `onMouseWheel`               | `onmousewheel`                 | `svg`         |
| `onOffline`                  | `onoffline`                    | `svg`, `html` |
| `onOnline`                   | `ononline`                     | `svg`, `html` |
| `onPageHide`                 | `onpagehide`                   | `svg`, `html` |
| `onPageShow`                 | `onpageshow`                   | `svg`, `html` |
| `onPaste`                    | `onpaste`                      | `svg`, `html` |
| `onPause`                    | `onpause`                      | `svg`, `html` |
| `onPlay`                     | `onplay`                       | `svg`, `html` |
| `onPlaying`                  | `onplaying`                    | `svg`, `html` |
| `onPopState`                 | `onpopstate`                   | `svg`, `html` |
| `onProgress`                 | `onprogress`                   | `svg`, `html` |
| `onRateChange`               | `onratechange`                 | `svg`, `html` |
| `onRejectionHandled`         | `onrejectionhandled`           | `html`        |
| `onRepeat`                   | `onrepeat`                     | `svg`         |
| `onReset`                    | `onreset`                      | `svg`, `html` |
| `onResize`                   | `onresize`                     | `svg`, `html` |
| `onScroll`                   | `onscroll`                     | `svg`, `html` |
| `onScrollEnd`                | `onscrollend`                  | `html`        |
| `onSecurityPolicyViolation`  | `onsecuritypolicyviolation`    | `html`        |
| `onSeeked`                   | `onseeked`                     | `svg`, `html` |
| `onSeeking`                  | `onseeking`                    | `svg`, `html` |
| `onSelect`                   | `onselect`                     | `svg`, `html` |
| `onShow`                     | `onshow`                       | `svg`         |
| `onSlotChange`               | `onslotchange`                 | `html`        |
| `onStalled`                  | `onstalled`                    | `svg`, `html` |
| `onStorage`                  | `onstorage`                    | `svg`, `html` |
| `onSubmit`                   | `onsubmit`                     | `svg`, `html` |
| `onSuspend`                  | `onsuspend`                    | `svg`, `html` |
| `onTimeUpdate`               | `ontimeupdate`                 | `svg`, `html` |
| `onToggle`                   | `ontoggle`                     | `svg`, `html` |
| `onUnhandledRejection`       | `onunhandledrejection`         | `html`        |
| `onUnload`                   | `onunload`                     | `svg`, `html` |
| `onVolumeChange`             | `onvolumechange`               | `svg`, `html` |
| `onWaiting`                  | `onwaiting`                    | `svg`, `html` |
| `onWheel`                    | `onwheel`                      | `html`        |
| `onZoom`                     | `onzoom`                       | `svg`         |
| `opacity`                    | `opacity`                      | `svg`         |
| `open`                       | `open`                         | `html`        |
| `operator`                   | `operator`                     | `svg`         |
| `optimum`                    | `optimum`                      | `html`        |
| `order`                      | `order`                        | `svg`         |
| `orient`                     | `orient`                       | `svg`         |
| `orientation`                | `orientation`                  | `svg`         |
| `origin`                     | `origin`                       | `svg`         |
| `overflow`                   | `overflow`                     | `svg`         |
| `overlay`                    | `overlay`                      | `svg`         |
| `overlinePosition`           | `overline-position`            | `svg`         |
| `overlineThickness`          | `overline-thickness`           | `svg`         |
| `paintOrder`                 | `paint-order`                  | `svg`         |
| `panose1`                    | `panose-1`                     | `svg`         |
| `path`                       | `path`                         | `svg`         |
| `pathLength`                 | `pathLength`                   | `svg`         |
| `pattern`                    | `pattern`                      | `html`        |
| `patternContentUnits`        | `patternContentUnits`          | `svg`         |
| `patternTransform`           | `patternTransform`             | `svg`         |
| `patternUnits`               | `patternUnits`                 | `svg`         |
| `phase`                      | `phase`                        | `svg`         |
| `ping`                       | `ping`                         | `svg`, `html` |
| `pitch`                      | `pitch`                        | `svg`         |
| `placeholder`                | `placeholder`                  | `html`        |
| `playbackOrder`              | `playbackorder`                | `svg`         |
| `playsInline`                | `playsinline`                  | `html`        |
| `pointerEvents`              | `pointer-events`               | `svg`         |
| `points`                     | `points`                       | `svg`         |
| `pointsAtX`                  | `pointsAtX`                    | `svg`         |
| `pointsAtY`                  | `pointsAtY`                    | `svg`         |
| `pointsAtZ`                  | `pointsAtZ`                    | `svg`         |
| `popover`                    | `popover`                      | `html`        |
| `popoverTarget`              | `popovertarget`                | `html`        |
| `popoverTargetAction`        | `popovertargetaction`          | `html`        |
| `poster`                     | `poster`                       | `html`        |
| `prefix`                     | `prefix`                       | `html`        |
| `preload`                    | `preload`                      | `html`        |
| `preserveAlpha`              | `preserveAlpha`                | `svg`         |
| `preserveAspectRatio`        | `preserveAspectRatio`          | `svg`         |
| `primitiveUnits`             | `primitiveUnits`               | `svg`         |
| `profile`                    | `profile`                      | `html`        |
| `prompt`                     | `prompt`                       | `html`        |
| `propagate`                  | `propagate`                    | `svg`         |
| `property`                   | `property`                     | `svg`, `html` |
| `r`                          | `r`                            | `svg`         |
| `radius`                     | `radius`                       | `svg`         |
| `readOnly`                   | `readonly`                     | `html`        |
| `refX`                       | `refX`                         | `svg`         |
| `refY`                       | `refY`                         | `svg`         |
| `referrerPolicy`             | `referrerpolicy`               | `svg`, `html` |
| `rel`                        | `rel`                          | `svg`, `html` |
| `renderingIntent`            | `rendering-intent`             | `svg`         |
| `repeatCount`                | `repeatCount`                  | `svg`         |
| `repeatDur`                  | `repeatDur`                    | `svg`         |
| `required`                   | `required`                     | `html`        |
| `requiredExtensions`         | `requiredExtensions`           | `svg`         |
| `requiredFeatures`           | `requiredFeatures`             | `svg`         |
| `requiredFonts`              | `requiredFonts`                | `svg`         |
| `requiredFormats`            | `requiredFormats`              | `svg`         |
| `resource`                   | `resource`                     | `svg`         |
| `restart`                    | `restart`                      | `svg`         |
| `result`                     | `result`                       | `svg`         |
| `results`                    | `results`                      | `html`        |
| `rev`                        | `rev`                          | `svg`, `html` |
| `reversed`                   | `reversed`                     | `html`        |
| `rightMargin`                | `rightmargin`                  | `html`        |
| `role`                       | `role`                         |               |
| `rotate`                     | `rotate`                       | `svg`         |
| `rowSpan`                    | `rowspan`                      | `html`        |
| `rows`                       | `rows`                         | `html`        |
| `rules`                      | `rules`                        | `html`        |
| `rx`                         | `rx`                           | `svg`         |
| `ry`                         | `ry`                           | `svg`         |
| `sandbox`                    | `sandbox`                      | `html`        |
| `scale`                      | `scale`                        | `svg`         |
| `scheme`                     | `scheme`                       | `html`        |
| `scope`                      | `scope`                        | `html`        |
| `scoped`                     | `scoped`                       | `html`        |
| `scrolling`                  | `scrolling`                    | `html`        |
| `seamless`                   | `seamless`                     | `html`        |
| `security`                   | `security`                     | `html`        |
| `seed`                       | `seed`                         | `svg`         |
| `selected`                   | `selected`                     | `html`        |
| `shadowRootClonable`         | `shadowrootclonable`           | `html`        |
| `shadowRootDelegatesFocus`   | `shadowrootdelegatesfocus`     | `html`        |
| `shadowRootMode`             | `shadowrootmode`               | `html`        |
| `shape`                      | `shape`                        | `html`        |
| `shapeRendering`             | `shape-rendering`              | `svg`         |
| `side`                       | `side`                         | `svg`         |
| `size`                       | `size`                         | `html`        |
| `sizes`                      | `sizes`                        | `html`        |
| `slope`                      | `slope`                        | `svg`         |
| `slot`                       | `slot`                         | `html`        |
| `snapshotTime`               | `snapshotTime`                 | `svg`         |
| `spacing`                    | `spacing`                      | `svg`         |
| `span`                       | `span`                         | `html`        |
| `specularConstant`           | `specularConstant`             | `svg`         |
| `specularExponent`           | `specularExponent`             | `svg`         |
| `spellCheck`                 | `spellcheck`                   | `html`        |
| `spreadMethod`               | `spreadMethod`                 | `svg`         |
| `src`                        | `src`                          | `html`        |
| `srcDoc`                     | `srcdoc`                       | `html`        |
| `srcLang`                    | `srclang`                      | `html`        |
| `srcSet`                     | `srcset`                       | `html`        |
| `standby`                    | `standby`                      | `html`        |
| `start`                      | `start`                        | `html`        |
| `startOffset`                | `startOffset`                  | `svg`         |
| `stdDeviation`               | `stdDeviation`                 | `svg`         |
| `stemh`                      | `stemh`                        | `svg`         |
| `stemv`                      | `stemv`                        | `svg`         |
| `step`                       | `step`                         | `html`        |
| `stitchTiles`                | `stitchTiles`                  | `svg`         |
| `stopColor`                  | `stop-color`                   | `svg`         |
| `stopOpacity`                | `stop-opacity`                 | `svg`         |
| `strikethroughPosition`      | `strikethrough-position`       | `svg`         |
| `strikethroughThickness`     | `strikethrough-thickness`      | `svg`         |
| `string`                     | `string`                       | `svg`         |
| `stroke`                     | `stroke`                       | `svg`         |
| `strokeDashArray`            | `stroke-dasharray`             | `svg`         |
| `strokeDashOffset`           | `stroke-dashoffset`            | `svg`         |
| `strokeLineCap`              | `stroke-linecap`               | `svg`         |
| `strokeLineJoin`             | `stroke-linejoin`              | `svg`         |
| `strokeMiterLimit`           | `stroke-miterlimit`            | `svg`         |
| `strokeOpacity`              | `stroke-opacity`               | `svg`         |
| `strokeWidth`                | `stroke-width`                 | `svg`         |
| `style`                      | `style`                        | `svg`, `html` |
| `summary`                    | `summary`                      | `html`        |
| `surfaceScale`               | `surfaceScale`                 | `svg`         |
| `syncBehavior`               | `syncBehavior`                 | `svg`         |
| `syncBehaviorDefault`        | `syncBehaviorDefault`          | `svg`         |
| `syncMaster`                 | `syncMaster`                   | `svg`         |
| `syncTolerance`              | `syncTolerance`                | `svg`         |
| `syncToleranceDefault`       | `syncToleranceDefault`         | `svg`         |
| `systemLanguage`             | `systemLanguage`               | `svg`         |
| `tabIndex`                   | `tabindex`                     | `svg`, `html` |
| `tableValues`                | `tableValues`                  | `svg`         |
| `target`                     | `target`                       | `svg`, `html` |
| `targetX`                    | `targetX`                      | `svg`         |
| `targetY`                    | `targetY`                      | `svg`         |
| `text`                       | `text`                         | `html`        |
| `textAnchor`                 | `text-anchor`                  | `svg`         |
| `textDecoration`             | `text-decoration`              | `svg`         |
| `textLength`                 | `textLength`                   | `svg`         |
| `textRendering`              | `text-rendering`               | `svg`         |
| `timelineBegin`              | `timelinebegin`                | `svg`         |
| `title`                      | `title`                        | `svg`, `html` |
| `to`                         | `to`                           | `svg`         |
| `topMargin`                  | `topmargin`                    | `html`        |
| `transform`                  | `transform`                    | `svg`         |
| `transformBehavior`          | `transformBehavior`            | `svg`         |
| `transformOrigin`            | `transform-origin`             | `svg`         |
| `translate`                  | `translate`                    | `html`        |
| `type`                       | `type`                         | `svg`, `html` |
| `typeMustMatch`              | `typemustmatch`                | `html`        |
| `typeOf`                     | `typeof`                       | `svg`         |
| `u1`                         | `u1`                           | `svg`         |
| `u2`                         | `u2`                           | `svg`         |
| `underlinePosition`          | `underline-position`           | `svg`         |
| `underlineThickness`         | `underline-thickness`          | `svg`         |
| `unicode`                    | `unicode`                      | `svg`         |
| `unicodeBidi`                | `unicode-bidi`                 | `svg`         |
| `unicodeRange`               | `unicode-range`                | `svg`         |
| `unitsPerEm`                 | `units-per-em`                 | `svg`         |
| `unselectable`               | `unselectable`                 | `html`        |
| `useMap`                     | `usemap`                       | `html`        |
| `vAlign`                     | `valign`                       | `html`        |
| `vAlphabetic`                | `v-alphabetic`                 | `svg`         |
| `vHanging`                   | `v-hanging`                    | `svg`         |
| `vIdeographic`               | `v-ideographic`                | `svg`         |
| `vLink`                      | `vlink`                        | `html`        |
| `vMathematical`              | `v-mathematical`               | `svg`         |
| `vSpace`                     | `vspace`                       | `html`        |
| `value`                      | `value`                        | `html`        |
| `valueType`                  | `valuetype`                    | `html`        |
| `values`                     | `values`                       | `svg`         |
| `vectorEffect`               | `vector-effect`                | `svg`         |
| `version`                    | `version`                      | `svg`, `html` |
| `vertAdvY`                   | `vert-adv-y`                   | `svg`         |
| `vertOriginX`                | `vert-origin-x`                | `svg`         |
| `vertOriginY`                | `vert-origin-y`                | `svg`         |
| `viewBox`                    | `viewBox`                      | `svg`         |
| `viewTarget`                 | `viewTarget`                   | `svg`         |
| `visibility`                 | `visibility`                   | `svg`         |
| `width`                      | `width`                        | `svg`, `html` |
| `widths`                     | `widths`                       | `svg`         |
| `wordSpacing`                | `word-spacing`                 | `svg`         |
| `wrap`                       | `wrap`                         | `html`        |
| `writingMode`                | `writing-mode`                 | `svg`         |
| `writingSuggestions`         | `writingsuggestions`           | `html`        |
| `x`                          | `x`                            | `svg`         |
| `x1`                         | `x1`                           | `svg`         |
| `x2`                         | `x2`                           | `svg`         |
| `xChannelSelector`           | `xChannelSelector`             | `svg`         |
| `xHeight`                    | `x-height`                     | `svg`         |
| `xLinkActuate`               | `xlink:actuate`                | `xlink`       |
| `xLinkArcRole`               | `xlink:arcrole`                | `xlink`       |
| `xLinkHref`                  | `xlink:href`                   | `xlink`       |
| `xLinkRole`                  | `xlink:role`                   | `xlink`       |
| `xLinkShow`                  | `xlink:show`                   | `xlink`       |
| `xLinkTitle`                 | `xlink:title`                  | `xlink`       |
| `xLinkType`                  | `xlink:type`                   | `xlink`       |
| `xmlBase`                    | `xml:base`                     | `xml`         |
| `xmlLang`                    | `xml:lang`                     | `xml`         |
| `xmlSpace`                   | `xml:space`                    | `xml`         |
| `xmlns`                      | `xmlns`                        | `xmlns`       |
| `xmlnsXLink`                 | `xmlns:xlink`                  | `xmlns`       |
| `y`                          | `y`                            | `svg`         |
| `y1`                         | `y1`                           | `svg`         |
| `y2`                         | `y2`                           | `svg`         |
| `yChannelSelector`           | `yChannelSelector`             | `svg`         |
| `z`                          | `z`                            | `svg`         |
| `zoomAndPan`                 | `zoomAndPan`                   | `svg`         |

<!--list end-->

## Security

This package is safe.

## Related

* [`wooorm/web-namespaces`][github-web-namespaces]
  — list of web namespaces
* [`wooorm/space-separated-tokens`](https://github.com/wooorm/space-separated-tokens)
  — parse/stringify space separated tokens
* [`wooorm/comma-separated-tokens`](https://github.com/wooorm/comma-separated-tokens)
  — parse/stringify comma separated tokens
* [`wooorm/html-tag-names`](https://github.com/wooorm/html-tag-names)
  — list of HTML tag names
* [`wooorm/mathml-tag-names`](https://github.com/wooorm/mathml-tag-names)
  — list of MathML tag names
* [`wooorm/svg-tag-names`](https://github.com/wooorm/svg-tag-names)
  — list of SVG tag names
* [`wooorm/html-void-elements`](https://github.com/wooorm/html-void-elements)
  — list of void HTML tag names
* [`wooorm/svg-element-attributes`](https://github.com/wooorm/svg-element-attributes)
  — map of SVG elements to allowed attributes
* [`wooorm/html-element-attributes`](https://github.com/wooorm/html-element-attributes)
  — map of HTML elements to allowed attributes
* [`wooorm/aria-attributes`](https://github.com/wooorm/aria-attributes)
  — list of ARIA attributes

## Contribute

Yes please!
See [*How to Contribute to Open Source*][opensource-guide].

## License

[MIT][file-license] © [Titus Wormer][wooorm]

Derivative work based on [React][github-react-source] licensed under
[MIT][github-react-source-license] © Facebook, Inc.

[api-find]: #findschema-name

[api-hast-to-react]: #hasttoreact

[api-html]: #html

[api-info]: #info

[api-normalize]: #normalizename

[api-schema]: #schema

[api-space]: #space

[api-svg]: #svg

[badge-build-image]: https://github.com/wooorm/property-information/workflows/main/badge.svg

[badge-build-url]: https://github.com/wooorm/property-information/actions

[badge-coverage-image]: https://img.shields.io/codecov/c/github/wooorm/property-information.svg

[badge-coverage-url]: https://codecov.io/github/wooorm/property-information

[badge-downloads-image]: https://img.shields.io/npm/dm/property-information.svg

[badge-downloads-url]: https://www.npmjs.com/package/property-information

[badge-size-image]: https://img.shields.io/bundlejs/size/property-information

[badge-size-url]: https://bundlejs.com/?q=property-information

[esmsh]: https://esm.sh

[file-license]: license

[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[github-hast]: https://github.com/syntax-tree/hast

[github-hast-property-name]: https://github.com/syntax-tree/hast#propertyname

[github-react]: https://github.com/facebook/react

[github-react-source]: https://github.com/facebook/react/blob/4632e36/packages/react-dom-bindings/src/shared/possibleStandardNames.js

[github-react-source-license]: https://github.com/facebook/react/blob/4632e36/LICENSE

[github-web-namespaces]: https://github.com/wooorm/web-namespaces

[mozilla-dataset]: https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dataset

[npmjs-install]: https://docs.npmjs.com/cli/install

[opensource-guide]: https://opensource.guide/how-to-contribute/

[section-support]: #support

[typescript]: https://www.typescriptlang.org

[wooorm]: https://wooorm.com


---

A list of objects, bound by their prototype chain.

Used in npm's config stuff.


---

2.0.7 / 2021-05-31
==================

  * deps: forwarded@0.2.0
    - Use `req.socket` over deprecated `req.connection`

2.0.6 / 2020-02-24
==================

  * deps: ipaddr.js@1.9.1

2.0.5 / 2019-04-16
==================

  * deps: ipaddr.js@1.9.0

2.0.4 / 2018-07-26
==================

  * deps: ipaddr.js@1.8.0

2.0.3 / 2018-02-19
==================

  * deps: ipaddr.js@1.6.0

2.0.2 / 2017-09-24
==================

  * deps: forwarded@~0.1.2
    - perf: improve header parsing
    - perf: reduce overhead when no `X-Forwarded-For` header

2.0.1 / 2017-09-10
==================

  * deps: forwarded@~0.1.1
    - Fix trimming leading / trailing OWS
    - perf: hoist regular expression
  * deps: ipaddr.js@1.5.2

2.0.0 / 2017-08-08
==================

  * Drop support for Node.js below 0.10

1.1.5 / 2017-07-25
==================

  * Fix array argument being altered
  * deps: ipaddr.js@1.4.0

1.1.4 / 2017-03-24
==================

  * deps: ipaddr.js@1.3.0

1.1.3 / 2017-01-14
==================

  * deps: ipaddr.js@1.2.0

1.1.2 / 2016-05-29
==================

  * deps: ipaddr.js@1.1.1
    - Fix IPv6-mapped IPv4 validation edge cases

1.1.1 / 2016-05-03
==================

  * Fix regression matching mixed versions against multiple subnets

1.1.0 / 2016-05-01
==================

  * Fix accepting various invalid netmasks
    - IPv4 netmasks must be contingous
    - IPv6 addresses cannot be used as a netmask
  * deps: ipaddr.js@1.1.0

1.0.10 / 2015-12-09
===================

  * deps: ipaddr.js@1.0.5
    - Fix regression in `isValid` with non-string arguments

1.0.9 / 2015-12-01
==================

  * deps: ipaddr.js@1.0.4
    - Fix accepting some invalid IPv6 addresses
    - Reject CIDRs with negative or overlong masks
  * perf: enable strict mode

1.0.8 / 2015-05-10
==================

  * deps: ipaddr.js@1.0.1

1.0.7 / 2015-03-16
==================

  * deps: ipaddr.js@0.1.9
    - Fix OOM on certain inputs to `isValid`

1.0.6 / 2015-02-01
==================

  * deps: ipaddr.js@0.1.8

1.0.5 / 2015-01-08
==================

  * deps: ipaddr.js@0.1.6

1.0.4 / 2014-11-23
==================

  * deps: ipaddr.js@0.1.5
    - Fix edge cases with `isValid`

1.0.3 / 2014-09-21
==================

  * Use `forwarded` npm module

1.0.2 / 2014-09-18
==================

  * Fix a global leak when multiple subnets are trusted
  * Support Node.js 0.6
  * deps: ipaddr.js@0.1.3

1.0.1 / 2014-06-03
==================

  * Fix links in npm package

1.0.0 / 2014-05-08
==================

  * Add `trust` argument to determine proxy trust on
    * Accepts custom function
    * Accepts IPv4/IPv6 address(es)
    * Accepts subnets
    * Accepts pre-defined names
  * Add optional `trust` argument to `proxyaddr.all` to
    stop at first untrusted
  * Add `proxyaddr.compile` to pre-compile `trust` function
    to make subsequent calls faster

0.0.1 / 2014-05-04
==================

  * Fix bad npm publish

0.0.0 / 2014-05-04
==================

  * Initial release


---

# proxy-addr

[![NPM Version][npm-version-image]][npm-url]
[![NPM Downloads][npm-downloads-image]][npm-url]
[![Node.js Version][node-image]][node-url]
[![Build Status][ci-image]][ci-url]
[![Test Coverage][coveralls-image]][coveralls-url]

Determine address of proxied request

## Install

This is a [Node.js](https://nodejs.org/en/) module available through the
[npm registry](https://www.npmjs.com/). Installation is done using the
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):

```sh
$ npm install proxy-addr
```

## API

```js
var proxyaddr = require('proxy-addr')
```

### proxyaddr(req, trust)

Return the address of the request, using the given `trust` parameter.

The `trust` argument is a function that returns `true` if you trust
the address, `false` if you don't. The closest untrusted address is
returned.

```js
proxyaddr(req, function (addr) { return addr === '127.0.0.1' })
proxyaddr(req, function (addr, i) { return i < 1 })
```

The `trust` arugment may also be a single IP address string or an
array of trusted addresses, as plain IP addresses, CIDR-formatted
strings, or IP/netmask strings.

```js
proxyaddr(req, '127.0.0.1')
proxyaddr(req, ['127.0.0.0/8', '10.0.0.0/8'])
proxyaddr(req, ['127.0.0.0/255.0.0.0', '192.168.0.0/255.255.0.0'])
```

This module also supports IPv6. Your IPv6 addresses will be normalized
automatically (i.e. `fe80::00ed:1` equals `fe80:0:0:0:0:0:ed:1`).

```js
proxyaddr(req, '::1')
proxyaddr(req, ['::1/128', 'fe80::/10'])
```

This module will automatically work with IPv4-mapped IPv6 addresses
as well to support node.js in IPv6-only mode. This means that you do
not have to specify both `::ffff:a00:1` and `10.0.0.1`.

As a convenience, this module also takes certain pre-defined names
in addition to IP addresses, which expand into IP addresses:

```js
proxyaddr(req, 'loopback')
proxyaddr(req, ['loopback', 'fc00:ac:1ab5:fff::1/64'])
```

  * `loopback`: IPv4 and IPv6 loopback addresses (like `::1` and
    `127.0.0.1`).
  * `linklocal`: IPv4 and IPv6 link-local addresses (like
    `fe80::1:1:1:1` and `169.254.0.1`).
  * `uniquelocal`: IPv4 private addresses and IPv6 unique-local
    addresses (like `fc00:ac:1ab5:fff::1` and `192.168.0.1`).

When `trust` is specified as a function, it will be called for each
address to determine if it is a trusted address. The function is
given two arguments: `addr` and `i`, where `addr` is a string of
the address to check and `i` is a number that represents the distance
from the socket address.

### proxyaddr.all(req, [trust])

Return all the addresses of the request, optionally stopping at the
first untrusted. This array is ordered from closest to furthest
(i.e. `arr[0] === req.connection.remoteAddress`).

```js
proxyaddr.all(req)
```

The optional `trust` argument takes the same arguments as `trust`
does in `proxyaddr(req, trust)`.

```js
proxyaddr.all(req, 'loopback')
```

### proxyaddr.compile(val)

Compiles argument `val` into a `trust` function. This function takes
the same arguments as `trust` does in `proxyaddr(req, trust)` and
returns a function suitable for `proxyaddr(req, trust)`.

```js
var trust = proxyaddr.compile('loopback')
var addr = proxyaddr(req, trust)
```

This function is meant to be optimized for use against every request.
It is recommend to compile a trust function up-front for the trusted
configuration and pass that to `proxyaddr(req, trust)` for each request.

## Testing

```sh
$ npm test
```

## Benchmarks

```sh
$ npm run-script bench
```

## License

[MIT](LICENSE)

[ci-image]: https://badgen.net/github/checks/jshttp/proxy-addr/master?label=ci
[ci-url]: https://github.com/jshttp/proxy-addr/actions?query=workflow%3Aci
[coveralls-image]: https://badgen.net/coveralls/c/github/jshttp/proxy-addr/master
[coveralls-url]: https://coveralls.io/r/jshttp/proxy-addr?branch=master
[node-image]: https://badgen.net/npm/node/proxy-addr
[node-url]: https://nodejs.org/en/download
[npm-downloads-image]: https://badgen.net/npm/dm/proxy-addr
[npm-url]: https://npmjs.org/package/proxy-addr
[npm-version-image]: https://badgen.net/npm/v/proxy-addr


---

# ipaddr.js — an IPv6 and IPv4 address manipulation library [![Build Status](https://travis-ci.org/whitequark/ipaddr.js.svg)](https://travis-ci.org/whitequark/ipaddr.js)

ipaddr.js is a small (1.9K minified and gzipped) library for manipulating
IP addresses in JavaScript environments. It runs on both CommonJS runtimes
(e.g. [nodejs]) and in a web browser.

ipaddr.js allows you to verify and parse string representation of an IP
address, match it against a CIDR range or range list, determine if it falls
into some reserved ranges (examples include loopback and private ranges),
and convert between IPv4 and IPv4-mapped IPv6 addresses.

[nodejs]: http://nodejs.org

## Installation

`npm install ipaddr.js`

or

`bower install ipaddr.js`

## API

ipaddr.js defines one object in the global scope: `ipaddr`. In CommonJS,
it is exported from the module:

```js
var ipaddr = require('ipaddr.js');
```

The API consists of several global methods and two classes: ipaddr.IPv6 and ipaddr.IPv4.

### Global methods

There are three global methods defined: `ipaddr.isValid`, `ipaddr.parse` and
`ipaddr.process`. All of them receive a string as a single parameter.

The `ipaddr.isValid` method returns `true` if the address is a valid IPv4 or
IPv6 address, and `false` otherwise. It does not throw any exceptions.

The `ipaddr.parse` method returns an object representing the IP address,
or throws an `Error` if the passed string is not a valid representation of an
IP address.

The `ipaddr.process` method works just like the `ipaddr.parse` one, but it
automatically converts IPv4-mapped IPv6 addresses to their IPv4 counterparts
before returning. It is useful when you have a Node.js instance listening
on an IPv6 socket, and the `net.ivp6.bindv6only` sysctl parameter (or its
equivalent on non-Linux OS) is set to 0. In this case, you can accept IPv4
connections on your IPv6-only socket, but the remote address will be mangled.
Use `ipaddr.process` method to automatically demangle it.

### Object representation

Parsing methods return an object which descends from `ipaddr.IPv6` or
`ipaddr.IPv4`. These objects share some properties, but most of them differ.

#### Shared properties

One can determine the type of address by calling `addr.kind()`. It will return
either `"ipv6"` or `"ipv4"`.

An address can be converted back to its string representation with `addr.toString()`.
Note that this method:
 * does not return the original string used to create the object (in fact, there is
   no way of getting that string)
 * returns a compact representation (when it is applicable)

A `match(range, bits)` method can be used to check if the address falls into a
certain CIDR range.
Note that an address can be (obviously) matched only against an address of the same type.

For example:

```js
var addr = ipaddr.parse("2001:db8:1234::1");
var range = ipaddr.parse("2001:db8::");

addr.match(range, 32); // => true
```

Alternatively, `match` can also be called as `match([range, bits])`. In this way,
it can be used together with the `parseCIDR(string)` method, which parses an IP
address together with a CIDR range.

For example:

```js
var addr = ipaddr.parse("2001:db8:1234::1");

addr.match(ipaddr.parseCIDR("2001:db8::/32")); // => true
```

A `range()` method returns one of predefined names for several special ranges defined
by IP protocols. The exact names (and their respective CIDR ranges) can be looked up
in the source: [IPv6 ranges] and [IPv4 ranges]. Some common ones include `"unicast"`
(the default one) and `"reserved"`.

You can match against your own range list by using
`ipaddr.subnetMatch(address, rangeList, defaultName)` method. It can work with a mix of IPv6 or IPv4 addresses, and accepts a name-to-subnet map as the range list. For example:

```js
var rangeList = {
  documentationOnly: [ ipaddr.parse('2001:db8::'), 32 ],
  tunnelProviders: [
    [ ipaddr.parse('2001:470::'), 32 ], // he.net
    [ ipaddr.parse('2001:5c0::'), 32 ]  // freenet6
  ]
};
ipaddr.subnetMatch(ipaddr.parse('2001:470:8:66::1'), rangeList, 'unknown'); // => "tunnelProviders"
```

The addresses can be converted to their byte representation with `toByteArray()`.
(Actually, JavaScript mostly does not know about byte buffers. They are emulated with
arrays of numbers, each in range of 0..255.)

```js
var bytes = ipaddr.parse('2a00:1450:8007::68').toByteArray(); // ipv6.google.com
bytes // => [42, 0x00, 0x14, 0x50, 0x80, 0x07, 0x00, <zeroes...>, 0x00, 0x68 ]
```

The `ipaddr.IPv4` and `ipaddr.IPv6` objects have some methods defined, too. All of them
have the same interface for both protocols, and are similar to global methods.

`ipaddr.IPvX.isValid(string)` can be used to check if the string is a valid address
for particular protocol, and `ipaddr.IPvX.parse(string)` is the error-throwing parser.

`ipaddr.IPvX.isValid(string)` uses the same format for parsing as the POSIX `inet_ntoa` function, which accepts unusual formats like `0xc0.168.1.1` or `0x10000000`. The function `ipaddr.IPv4.isValidFourPartDecimal(string)` validates the IPv4 address and also ensures that it is written in four-part decimal format.

[IPv6 ranges]: https://github.com/whitequark/ipaddr.js/blob/master/src/ipaddr.coffee#L186
[IPv4 ranges]: https://github.com/whitequark/ipaddr.js/blob/master/src/ipaddr.coffee#L71

#### IPv6 properties

Sometimes you will want to convert IPv6 not to a compact string representation (with
the `::` substitution); the `toNormalizedString()` method will return an address where
all zeroes are explicit.

For example:

```js
var addr = ipaddr.parse("2001:0db8::0001");
addr.toString(); // => "2001:db8::1"
addr.toNormalizedString(); // => "2001:db8:0:0:0:0:0:1"
```

The `isIPv4MappedAddress()` method will return `true` if this address is an IPv4-mapped
one, and `toIPv4Address()` will return an IPv4 object address.

To access the underlying binary representation of the address, use `addr.parts`.

```js
var addr = ipaddr.parse("2001:db8:10::1234:DEAD");
addr.parts // => [0x2001, 0xdb8, 0x10, 0, 0, 0, 0x1234, 0xdead]
```

A IPv6 zone index can be accessed via `addr.zoneId`:

```js
var addr = ipaddr.parse("2001:db8::%eth0");
addr.zoneId // => 'eth0'
```

#### IPv4 properties

`toIPv4MappedAddress()` will return a corresponding IPv4-mapped IPv6 address.

To access the underlying representation of the address, use `addr.octets`.

```js
var addr = ipaddr.parse("192.168.1.1");
addr.octets // => [192, 168, 1, 1]
```

`prefixLengthFromSubnetMask()` will return a CIDR prefix length for a valid IPv4 netmask or
null if the netmask is not valid.

```js
ipaddr.IPv4.parse('255.255.255.240').prefixLengthFromSubnetMask() == 28
ipaddr.IPv4.parse('255.192.164.0').prefixLengthFromSubnetMask()  == null
```

`subnetMaskFromPrefixLength()` will return an IPv4 netmask for a valid CIDR prefix length.

```js
ipaddr.IPv4.subnetMaskFromPrefixLength(24) == "255.255.255.0"
ipaddr.IPv4.subnetMaskFromPrefixLength(29) == "255.255.255.248"
```

`broadcastAddressFromCIDR()` will return the broadcast address for a given IPv4 interface and netmask in CIDR notation.
```js
ipaddr.IPv4.broadcastAddressFromCIDR("172.0.0.1/24") == "172.0.0.255"
```
`networkAddressFromCIDR()` will return the network address for a given IPv4 interface and netmask in CIDR notation.
```js
ipaddr.IPv4.networkAddressFromCIDR("172.0.0.1/24") == "172.0.0.0"
```

#### Conversion

IPv4 and IPv6 can be converted bidirectionally to and from network byte order (MSB) byte arrays.

The `fromByteArray()` method will take an array and create an appropriate IPv4 or IPv6 object
if the input satisfies the requirements. For IPv4 it has to be an array of four 8-bit values,
while for IPv6 it has to be an array of sixteen 8-bit values.

For example:
```js
var addr = ipaddr.fromByteArray([0x7f, 0, 0, 1]);
addr.toString(); // => "127.0.0.1"
```

or

```js
var addr = ipaddr.fromByteArray([0x20, 1, 0xd, 0xb8, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1])
addr.toString(); // => "2001:db8::1"
```

Both objects also offer a `toByteArray()` method, which returns an array in network byte order (MSB).

For example:
```js
var addr = ipaddr.parse("127.0.0.1");
addr.toByteArray(); // => [0x7f, 0, 0, 1]
```

or

```js
var addr = ipaddr.parse("2001:db8::1");
addr.toByteArray(); // => [0x20, 1, 0xd, 0xb8, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1]
```


---

# proxy-from-env

[![Build Status](https://travis-ci.org/Rob--W/proxy-from-env.svg?branch=master)](https://travis-ci.org/Rob--W/proxy-from-env)
[![Coverage Status](https://coveralls.io/repos/github/Rob--W/proxy-from-env/badge.svg?branch=master)](https://coveralls.io/github/Rob--W/proxy-from-env?branch=master)

`proxy-from-env` is a Node.js package that exports a function (`getProxyForUrl`)
that takes an input URL (a string or
[`url.parse`](https://nodejs.org/docs/latest/api/url.html#url_url_parsing)'s
return value) and returns the desired proxy URL (also a string) based on
standard proxy environment variables. If no proxy is set, an empty string is
returned.

It is your responsibility to actually proxy the request using the given URL.

Installation:

```sh
npm install proxy-from-env
```

## Example
This example shows how the data for a URL can be fetched via the
[`http` module](https://nodejs.org/api/http.html), in a proxy-aware way.

```javascript
var http = require('http');
var parseUrl = require('url').parse;
var getProxyForUrl = require('proxy-from-env').getProxyForUrl;

var some_url = 'http://example.com/something';

// // Example, if there is a proxy server at 10.0.0.1:1234, then setting the
// // http_proxy environment variable causes the request to go through a proxy.
// process.env.http_proxy = 'http://10.0.0.1:1234';
// 
// // But if the host to be proxied is listed in NO_PROXY, then the request is
// // not proxied (but a direct request is made).
// process.env.no_proxy = 'example.com';

var proxy_url = getProxyForUrl(some_url);  // <-- Our magic.
if (proxy_url) {
  // Should be proxied through proxy_url.
  var parsed_some_url = parseUrl(some_url);
  var parsed_proxy_url = parseUrl(proxy_url);
  // A HTTP proxy is quite simple. It is similar to a normal request, except the
  // path is an absolute URL, and the proxied URL's host is put in the header
  // instead of the server's actual host.
  httpOptions = {
    protocol: parsed_proxy_url.protocol,
    hostname: parsed_proxy_url.hostname,
    port: parsed_proxy_url.port,
    path: parsed_some_url.href,
    headers: {
      Host: parsed_some_url.host,  // = host name + optional port.
    },
  };
} else {
  // Direct request.
  httpOptions = some_url;
}
http.get(httpOptions, function(res) {
  var responses = [];
  res.on('data', function(chunk) { responses.push(chunk); });
  res.on('end', function() { console.log(responses.join(''));  });
});

```

## Environment variables
The environment variables can be specified in lowercase or uppercase, with the
lowercase name having precedence over the uppercase variant. A variable that is
not set has the same meaning as a variable that is set but has no value.

### NO\_PROXY

`NO_PROXY` is a list of host names (optionally with a port). If the input URL
matches any of the entries in `NO_PROXY`, then the input URL should be fetched
by a direct request (i.e. without a proxy).

Matching follows the following rules:

- `NO_PROXY=*` disables all proxies.
- Space and commas may be used to separate the entries in the `NO_PROXY` list.
- If `NO_PROXY` does not contain any entries, then proxies are never disabled.
- If a port is added after the host name, then the ports must match. If the URL
  does not have an explicit port name, the protocol's default port is used.
- Generally, the proxy is only disabled if the host name is an exact match for
  an entry in the `NO_PROXY` list. The only exceptions are entries that start
  with a dot or with a wildcard; then the proxy is disabled if the host name
  ends with the entry.

See `test.js` for examples of what should match and what does not.

### \*\_PROXY

The environment variable used for the proxy depends on the protocol of the URL.
For example, `https://example.com` uses the "https" protocol, and therefore the
proxy to be used is `HTTPS_PROXY` (_NOT_ `HTTP_PROXY`, which is _only_ used for
http:-URLs).

The library is not limited to http(s), other schemes such as
`FTP_PROXY` (ftp:),
`WSS_PROXY` (wss:),
`WS_PROXY` (ws:)
are also supported.

If present, `ALL_PROXY` is used as fallback if there is no other match.


## External resources
The exact way of parsing the environment variables is not codified in any
standard. This library is designed to be compatible with formats as expected by
existing software.
The following resources were used to determine the desired behavior:

- cURL:
  https://curl.haxx.se/docs/manpage.html#ENVIRONMENT  
  https://github.com/curl/curl/blob/4af40b3646d3b09f68e419f7ca866ff395d1f897/lib/url.c#L4446-L4514  
  https://github.com/curl/curl/blob/4af40b3646d3b09f68e419f7ca866ff395d1f897/lib/url.c#L4608-L4638  

- wget: 
  https://www.gnu.org/software/wget/manual/wget.html#Proxies  
  http://git.savannah.gnu.org/cgit/wget.git/tree/src/init.c?id=636a5f9a1c508aa39e35a3a8e9e54520a284d93d#n383  
  http://git.savannah.gnu.org/cgit/wget.git/tree/src/retr.c?id=93c1517c4071c4288ba5a4b038e7634e4c6b5482#n1278  

- W3:
  https://www.w3.org/Daemon/User/Proxies/ProxyClients.html  

- Python's urllib:
  https://github.com/python/cpython/blob/936135bb97fe04223aa30ca6e98eac8f3ed6b349/Lib/urllib/request.py#L755-L782  
  https://github.com/python/cpython/blob/936135bb97fe04223aa30ca6e98eac8f3ed6b349/Lib/urllib/request.py#L2444-L2479


---

# pupa

> Simple micro templating

Useful when all you need is to fill in some placeholders.

## Install

```
$ npm install pupa
```

## Usage

```js
import pupa from 'pupa';

pupa('The mobile number of {name} is {phone.mobile}', {
	name: 'Sindre',
	phone: {
		mobile: '609 24 363'
	}
});
//=> 'The mobile number of Sindre is 609 24 363'

pupa('I like {0} and {1}', ['🦄', '🐮']);
//=> 'I like 🦄 and 🐮'

// Double braces encodes the HTML entities to avoid code injection.
pupa('I like {{0}} and {{1}}', ['<br>🦄</br>', '<i>🐮</i>']);
//=> 'I like &lt;br&gt;🦄&lt;/br&gt; and &lt;i&gt;🐮&lt;/i&gt;'
```

## API

### pupa(template, data, options?)

#### template

Type: `string`

Text with placeholders for `data` properties.

#### data

Type: `object | unknown[]`

Data to interpolate into `template`.

#### options

Type: `object`

##### ignoreMissing

Type: `boolean`\
Default: `false`

By default, Pupa throws a `MissingValueError` when a placeholder resolves to `undefined`. With this option set to `true`, it simply ignores it and leaves the placeholder as is.

##### transform

Type: `((data: {value: unknown; key: string}) => unknown) | undefined` (default: `({value}) => value`)

Performs arbitrary operation for each interpolation. If the returned value was `undefined`, it behaves differently depending on the `ignoreMissing` option. Otherwise, the returned value will be interpolated into a string (and escaped when double-braced) and embedded into the template.

### MissingValueError

Exposed for instance checking.

## FAQ

### What about template literals?

Template literals expand on creation. This module expands the template on execution, which can be useful if either or both template and data are lazily created or user-supplied.

## Related

- [pupa-cli](https://github.com/sindresorhus/pupa-cli) - CLI for this module


---

## **6.13.0**
- [New] `parse`: add `strictDepth` option (#511)
- [Tests] use `npm audit` instead of `aud`

## **6.12.3**
- [Fix] `parse`: properly account for `strictNullHandling` when `allowEmptyArrays`
- [meta] fix changelog indentation

## **6.12.2**
- [Fix] `parse`: parse encoded square brackets (#506)
- [readme] add CII best practices badge

## **6.12.1**
- [Fix] `parse`: Disable `decodeDotInKeys` by default to restore previous behavior (#501)
- [Performance] `utils`: Optimize performance under large data volumes, reduce memory usage, and speed up processing (#502)
- [Refactor] `utils`: use `+=`
- [Tests] increase coverage

## **6.12.0**

- [New] `parse`/`stringify`: add `decodeDotInKeys`/`encodeDotKeys` options (#488)
- [New] `parse`: add `duplicates` option
- [New] `parse`/`stringify`: add `allowEmptyArrays` option to allow [] in object values (#487)
- [Refactor] `parse`/`stringify`: move allowDots config logic to its own variable
- [Refactor] `stringify`: move option-handling code into `normalizeStringifyOptions`
- [readme] update readme, add logos (#484)
- [readme] `stringify`: clarify default `arrayFormat` behavior
- [readme] fix line wrapping
- [readme] remove dead badges
- [Deps] update `side-channel`
- [meta] make the dist build 50% smaller
- [meta] add `sideEffects` flag
- [meta] run build in prepack, not prepublish
- [Tests] `parse`: remove useless tests; add coverage
- [Tests] `stringify`: increase coverage
- [Tests] use `mock-property`
- [Tests] `stringify`: improve coverage
- [Dev Deps] update `@ljharb/eslint-config `, `aud`, `has-override-mistake`, `has-property-descriptors`, `mock-property`, `npmignore`, `object-inspect`, `tape`
- [Dev Deps] pin `glob`, since v10.3.8+ requires a broken `jackspeak`
- [Dev Deps] pin `jackspeak` since 2.1.2+ depends on npm aliases, which kill the install process in npm < 6

## **6.11.2**
- [Fix] `parse`: Fix parsing when the global Object prototype is frozen (#473)
- [Tests] add passing test cases with empty keys (#473)

## **6.11.1**
- [Fix] `stringify`: encode comma values more consistently (#463)
- [readme] add usage of `filter` option for injecting custom serialization, i.e. of custom types (#447)
- [meta] remove extraneous code backticks (#457)
- [meta] fix changelog markdown
- [actions] update checkout action
- [actions] restrict action permissions
- [Dev Deps] update `@ljharb/eslint-config`, `aud`, `object-inspect`, `tape`

## **6.11.0**
- [New] [Fix] `stringify`: revert 0e903c0; add `commaRoundTrip` option (#442)
- [readme] fix version badge

## **6.10.5**
- [Fix] `stringify`: with `arrayFormat: comma`, properly include an explicit `[]` on a single-item array (#434)

## **6.10.4**
- [Fix] `stringify`: with `arrayFormat: comma`, include an explicit `[]` on a single-item array (#441)
- [meta] use `npmignore` to autogenerate an npmignore file
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `aud`, `has-symbol`, `object-inspect`, `tape`

## **6.10.3**
- [Fix] `parse`: ignore `__proto__` keys (#428)
- [Robustness] `stringify`: avoid relying on a global `undefined` (#427)
- [actions] reuse common workflows
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `object-inspect`, `tape`

## **6.10.2**
- [Fix] `stringify`: actually fix cyclic references (#426)
- [Fix] `stringify`: avoid encoding arrayformat comma when `encodeValuesOnly = true` (#424)
- [readme] remove travis badge; add github actions/codecov badges; update URLs
- [Docs] add note and links for coercing primitive values (#408)
- [actions] update codecov uploader
- [actions] update workflows
- [Tests] clean up stringify tests slightly
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `aud`, `object-inspect`, `safe-publish-latest`, `tape`

## **6.10.1**
- [Fix] `stringify`: avoid exception on repeated object values (#402)

## **6.10.0**
- [New] `stringify`: throw on cycles, instead of an infinite loop (#395, #394, #393)
- [New] `parse`: add `allowSparse` option for collapsing arrays with missing indices (#312)
- [meta] fix README.md (#399)
- [meta] only run `npm run dist` in publish, not install
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `aud`, `has-symbols`, `tape`
- [Tests] fix tests on node v0.6
- [Tests] use `ljharb/actions/node/install` instead of `ljharb/actions/node/run`
- [Tests] Revert "[meta] ignore eclint transitive audit warning"

## **6.9.7**
- [Fix] `parse`: ignore `__proto__` keys (#428)
- [Fix] `stringify`: avoid encoding arrayformat comma when `encodeValuesOnly = true` (#424)
- [Robustness] `stringify`: avoid relying on a global `undefined` (#427)
- [readme] remove travis badge; add github actions/codecov badges; update URLs
- [Docs] add note and links for coercing primitive values (#408)
- [Tests] clean up stringify tests slightly
- [meta] fix README.md (#399)
- Revert "[meta] ignore eclint transitive audit warning"
- [actions] backport actions from main
- [Dev Deps] backport updates from main

## **6.9.6**
- [Fix] restore `dist` dir; mistakenly removed in d4f6c32

## **6.9.5**
- [Fix] `stringify`: do not encode parens for RFC1738
- [Fix] `stringify`: fix arrayFormat comma with empty array/objects (#350)
- [Refactor] `format`: remove `util.assign` call
- [meta] add "Allow Edits" workflow; update rebase workflow
- [actions] switch Automatic Rebase workflow to `pull_request_target` event
- [Tests] `stringify`: add tests for #378
- [Tests] migrate tests to Github Actions
- [Tests] run `nyc` on all tests; use `tape` runner
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `browserify`, `mkdirp`, `object-inspect`, `tape`; add `aud`

## **6.9.4**
- [Fix] `stringify`: when `arrayFormat` is `comma`, respect `serializeDate` (#364)
- [Refactor] `stringify`: reduce branching (part of #350)
- [Refactor] move `maybeMap` to `utils`
- [Dev Deps] update `browserify`, `tape`

## **6.9.3**
- [Fix] proper comma parsing of URL-encoded commas (#361)
- [Fix] parses comma delimited array while having percent-encoded comma treated as normal text (#336)

## **6.9.2**
- [Fix] `parse`: Fix parsing array from object with `comma` true (#359)
- [Fix] `parse`: throw a TypeError instead of an Error for bad charset (#349)
- [meta] ignore eclint transitive audit warning
- [meta] fix indentation in package.json
- [meta] add tidelift marketing copy
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `object-inspect`, `has-symbols`, `tape`, `mkdirp`, `iconv-lite`
- [actions] add automatic rebasing / merge commit blocking

## **6.9.1**
- [Fix] `parse`: with comma true, handle field that holds an array of arrays (#335)
- [Fix] `parse`: with comma true, do not split non-string values (#334)
- [meta] add `funding` field
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`
- [Tests] use shared travis-ci config

## **6.9.0**
- [New] `parse`/`stringify`: Pass extra key/value argument to `decoder` (#333)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `evalmd`
- [Tests] `parse`: add passing `arrayFormat` tests
- [Tests] add `posttest` using `npx aud` to run `npm audit` without a lockfile
- [Tests] up to `node` `v12.10`, `v11.15`, `v10.16`, `v8.16`
- [Tests] `Buffer.from` in node v5.0-v5.9 and v4.0-v4.4 requires a TypedArray

## **6.8.3**
- [Fix] `parse`: ignore `__proto__` keys (#428)
- [Robustness] `stringify`: avoid relying on a global `undefined` (#427)
- [Fix] `stringify`: avoid encoding arrayformat comma when `encodeValuesOnly = true` (#424)
- [readme] remove travis badge; add github actions/codecov badges; update URLs
- [Tests] clean up stringify tests slightly
- [Docs] add note and links for coercing primitive values (#408)
- [meta] fix README.md (#399)
- [actions] backport actions from main
- [Dev Deps] backport updates from main
- [Refactor] `stringify`: reduce branching
- [meta] do not publish workflow files

## **6.8.2**
- [Fix] proper comma parsing of URL-encoded commas (#361)
- [Fix] parses comma delimited array while having percent-encoded comma treated as normal text (#336)

## **6.8.1**
- [Fix] `parse`: Fix parsing array from object with `comma` true (#359)
- [Fix] `parse`: throw a TypeError instead of an Error for bad charset (#349)
- [Fix] `parse`: with comma true, handle field that holds an array of arrays (#335)
- [fix] `parse`: with comma true, do not split non-string values (#334)
- [meta] add tidelift marketing copy
- [meta] add `funding` field
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `tape`, `safe-publish-latest`, `evalmd`, `has-symbols`, `iconv-lite`, `mkdirp`, `object-inspect`
- [Tests] `parse`: add passing `arrayFormat` tests
- [Tests] use shared travis-ci configs
- [Tests] `Buffer.from` in node v5.0-v5.9 and v4.0-v4.4 requires a TypedArray
- [actions] add automatic rebasing / merge commit blocking

## **6.8.0**
- [New] add `depth=false` to preserve the original key; [Fix] `depth=0` should preserve the original key (#326)
- [New] [Fix] stringify symbols and bigints
- [Fix] ensure node 0.12 can stringify Symbols
- [Fix] fix for an impossible situation: when the formatter is called with a non-string value
- [Refactor] `formats`: tiny bit of cleanup.
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `browserify`, `safe-publish-latest`, `iconv-lite`, `tape`
- [Tests] add tests for `depth=0` and `depth=false` behavior, both current and intuitive/intended (#326)
- [Tests] use `eclint` instead of `editorconfig-tools`
- [docs] readme: add security note
- [meta] add github sponsorship
- [meta] add FUNDING.yml
- [meta] Clean up license text so it’s properly detected as BSD-3-Clause

## **6.7.3**
- [Fix] `parse`: ignore `__proto__` keys (#428)
- [Fix] `stringify`: avoid encoding arrayformat comma when `encodeValuesOnly = true` (#424)
- [Robustness] `stringify`: avoid relying on a global `undefined` (#427)
- [readme] remove travis badge; add github actions/codecov badges; update URLs
- [Docs] add note and links for coercing primitive values (#408)
- [meta] fix README.md (#399)
- [meta] do not publish workflow files
- [actions] backport actions from main
- [Dev Deps] backport updates from main
- [Tests] use `nyc` for coverage
- [Tests] clean up stringify tests slightly

## **6.7.2**
- [Fix] proper comma parsing of URL-encoded commas (#361)
- [Fix] parses comma delimited array while having percent-encoded comma treated as normal text (#336)

## **6.7.1**
- [Fix] `parse`: Fix parsing array from object with `comma` true (#359)
- [Fix] `parse`: with comma true, handle field that holds an array of arrays (#335)
- [fix] `parse`: with comma true, do not split non-string values (#334)
- [Fix] `parse`: throw a TypeError instead of an Error for bad charset (#349)
- [Fix] fix for an impossible situation: when the formatter is called with a non-string value
- [Refactor] `formats`: tiny bit of cleanup.
- readme: add security note
- [meta] add tidelift marketing copy
- [meta] add `funding` field
- [meta] add FUNDING.yml
- [meta] Clean up license text so it’s properly detected as BSD-3-Clause
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `tape`, `safe-publish-latest`, `evalmd`, `iconv-lite`, `mkdirp`, `object-inspect`, `browserify`
- [Tests] `parse`: add passing `arrayFormat` tests
- [Tests] use shared travis-ci configs
- [Tests] `Buffer.from` in node v5.0-v5.9 and v4.0-v4.4 requires a TypedArray
- [Tests] add tests for `depth=0` and `depth=false` behavior, both current and intuitive/intended
- [Tests] use `eclint` instead of `editorconfig-tools`
- [actions] add automatic rebasing / merge commit blocking

## **6.7.0**
- [New] `stringify`/`parse`: add `comma` as an `arrayFormat` option (#276, #219)
- [Fix] correctly parse nested arrays (#212)
- [Fix] `utils.merge`: avoid a crash with a null target and a truthy non-array source, also with an array source
- [Robustness] `stringify`: cache `Object.prototype.hasOwnProperty`
- [Refactor] `utils`: `isBuffer`: small tweak; add tests
- [Refactor] use cached `Array.isArray`
- [Refactor] `parse`/`stringify`: make a function to normalize the options
- [Refactor] `utils`: reduce observable [[Get]]s
- [Refactor] `stringify`/`utils`: cache `Array.isArray`
- [Tests] always use `String(x)` over `x.toString()`
- [Tests] fix Buffer tests to work in node < 4.5 and node < 5.10
- [Tests] temporarily allow coverage to fail

## **6.6.1**
- [Fix] `parse`: ignore `__proto__` keys (#428)
- [Fix] fix for an impossible situation: when the formatter is called with a non-string value
- [Fix] `utils.merge`: avoid a crash with a null target and an array source
- [Fix] `utils.merge`: avoid a crash with a null target and a truthy non-array source
- [Fix] correctly parse nested arrays
- [Robustness] `stringify`: avoid relying on a global `undefined` (#427)
- [Robustness] `stringify`: cache `Object.prototype.hasOwnProperty`
- [Refactor] `formats`: tiny bit of cleanup.
- [Refactor] `utils`: `isBuffer`: small tweak; add tests
- [Refactor]: `stringify`/`utils`: cache `Array.isArray`
- [Refactor] `utils`: reduce observable [[Get]]s
- [Refactor] use cached `Array.isArray`
- [Refactor] `parse`/`stringify`: make a function to normalize the options
- [readme] remove travis badge; add github actions/codecov badges; update URLs
- [Docs] Clarify the need for "arrayLimit" option
- [meta] fix README.md (#399)
- [meta] do not publish workflow files
- [meta] Clean up license text so it’s properly detected as BSD-3-Clause
- [meta] add FUNDING.yml
- [meta] Fixes typo in CHANGELOG.md
- [actions] backport actions from main
- [Tests] fix Buffer tests to work in node < 4.5 and node < 5.10
- [Tests] always use `String(x)` over `x.toString()`
- [Dev Deps] backport from main

## **6.6.0**
- [New] Add support for iso-8859-1, utf8 "sentinel" and numeric entities (#268)
- [New] move two-value combine to a `utils` function (#189)
- [Fix] `stringify`: fix a crash with `strictNullHandling` and a custom `filter`/`serializeDate` (#279)
- [Fix] when `parseArrays` is false, properly handle keys ending in `[]` (#260)
- [Fix] `stringify`: do not crash in an obscure combo of `interpretNumericEntities`, a bad custom `decoder`, & `iso-8859-1`
- [Fix] `utils`: `merge`: fix crash when `source` is a truthy primitive & no options are provided
- [refactor] `stringify`: Avoid arr = arr.concat(...), push to the existing instance (#269)
- [Refactor] `parse`: only need to reassign the var once
- [Refactor] `parse`/`stringify`: clean up `charset` options checking; fix defaults
- [Refactor] add missing defaults
- [Refactor] `parse`: one less `concat` call
- [Refactor] `utils`: `compactQueue`: make it explicitly side-effecting
- [Dev Deps] update `browserify`, `eslint`, `@ljharb/eslint-config`, `iconv-lite`, `safe-publish-latest`, `tape`
- [Tests] up to `node` `v10.10`, `v9.11`, `v8.12`, `v6.14`, `v4.9`; pin included builds to LTS

## **6.5.3**
- [Fix] `parse`: ignore `__proto__` keys (#428)
- [Fix] `utils.merge`: avoid a crash with a null target and a truthy non-array source
- [Fix] correctly parse nested arrays
- [Fix] `stringify`: fix a crash with `strictNullHandling` and a custom `filter`/`serializeDate` (#279)
- [Fix] `utils`: `merge`: fix crash when `source` is a truthy primitive & no options are provided
- [Fix] when `parseArrays` is false, properly handle keys ending in `[]`
- [Fix] fix for an impossible situation: when the formatter is called with a non-string value
- [Fix] `utils.merge`: avoid a crash with a null target and an array source
- [Refactor] `utils`: reduce observable [[Get]]s
- [Refactor] use cached `Array.isArray`
- [Refactor] `stringify`: Avoid arr = arr.concat(...), push to the existing instance (#269)
- [Refactor] `parse`: only need to reassign the var once
- [Robustness] `stringify`: avoid relying on a global `undefined` (#427)
- [readme] remove travis badge; add github actions/codecov badges; update URLs
- [Docs] Clean up license text so it’s properly detected as BSD-3-Clause
- [Docs] Clarify the need for "arrayLimit" option
- [meta] fix README.md (#399)
- [meta] add FUNDING.yml
- [actions] backport actions from main
- [Tests] always use `String(x)` over `x.toString()`
- [Tests] remove nonexistent tape option
- [Dev Deps] backport from main

## **6.5.2**
- [Fix] use `safer-buffer` instead of `Buffer` constructor
- [Refactor] utils: `module.exports` one thing, instead of mutating `exports` (#230)
- [Dev Deps] update `browserify`, `eslint`, `iconv-lite`, `safer-buffer`, `tape`, `browserify`

## **6.5.1**
- [Fix] Fix parsing & compacting very deep objects (#224)
- [Refactor] name utils functions
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `tape`
- [Tests] up to `node` `v8.4`; use `nvm install-latest-npm` so newer npm doesn’t break older node
- [Tests] Use precise dist for Node.js 0.6 runtime (#225)
- [Tests] make 0.6 required, now that it’s passing
- [Tests] on `node` `v8.2`; fix npm on node 0.6

## **6.5.0**
- [New] add `utils.assign`
- [New] pass default encoder/decoder to custom encoder/decoder functions (#206)
- [New] `parse`/`stringify`: add `ignoreQueryPrefix`/`addQueryPrefix` options, respectively (#213)
- [Fix] Handle stringifying empty objects with addQueryPrefix (#217)
- [Fix] do not mutate `options` argument (#207)
- [Refactor] `parse`: cache index to reuse in else statement (#182)
- [Docs] add various badges to readme (#208)
- [Dev Deps] update `eslint`, `browserify`, `iconv-lite`, `tape`
- [Tests] up to `node` `v8.1`, `v7.10`, `v6.11`; npm v4.6 breaks on node < v1; npm v5+ breaks on node < v4
- [Tests] add `editorconfig-tools`

## **6.4.1**
- [Fix] `parse`: ignore `__proto__` keys (#428)
- [Fix] fix for an impossible situation: when the formatter is called with a non-string value
- [Fix] use `safer-buffer` instead of `Buffer` constructor
- [Fix] `utils.merge`: avoid a crash with a null target and an array source
- [Fix] `utils.merge`: avoid a crash with a null target and a truthy non-array source
- [Fix] `stringify`: fix a crash with `strictNullHandling` and a custom `filter`/`serializeDate` (#279)
- [Fix] `utils`: `merge`: fix crash when `source` is a truthy primitive & no options are provided
- [Fix] when `parseArrays` is false, properly handle keys ending in `[]`
- [Robustness] `stringify`: avoid relying on a global `undefined` (#427)
- [Refactor] use cached `Array.isArray`
- [Refactor] `stringify`: Avoid arr = arr.concat(...), push to the existing instance (#269)
- [readme] remove travis badge; add github actions/codecov badges; update URLs
- [Docs] Clarify the need for "arrayLimit" option
- [meta] fix README.md (#399)
- [meta] Clean up license text so it’s properly detected as BSD-3-Clause
- [meta] add FUNDING.yml
- [actions] backport actions from main
- [Tests] remove nonexistent tape option
- [Dev Deps] backport from main

## **6.4.0**
- [New] `qs.stringify`: add `encodeValuesOnly` option
- [Fix] follow `allowPrototypes` option during merge (#201, #201)
- [Fix] support keys starting with brackets (#202, #200)
- [Fix] chmod a-x
- [Dev Deps] update `eslint`
- [Tests] up to `node` `v7.7`, `v6.10`,` v4.8`; disable osx builds since they block linux builds
- [eslint] reduce warnings

## **6.3.3**
- [Fix] `parse`: ignore `__proto__` keys (#428)
- [Fix] fix for an impossible situation: when the formatter is called with a non-string value
- [Fix] `utils.merge`: avoid a crash with a null target and an array source
- [Fix] `utils.merge`: avoid a crash with a null target and a truthy non-array source
- [Fix] `stringify`: fix a crash with `strictNullHandling` and a custom `filter`/`serializeDate` (#279)
- [Fix] `utils`: `merge`: fix crash when `source` is a truthy primitive & no options are provided
- [Fix] when `parseArrays` is false, properly handle keys ending in `[]`
- [Robustness] `stringify`: avoid relying on a global `undefined` (#427)
- [Refactor] use cached `Array.isArray`
- [Refactor] `stringify`: Avoid arr = arr.concat(...), push to the existing instance (#269)
- [Docs] Clarify the need for "arrayLimit" option
- [meta] fix README.md (#399)
- [meta] Clean up license text so it’s properly detected as BSD-3-Clause
- [meta] add FUNDING.yml
- [actions] backport actions from main
- [Tests] use `safer-buffer` instead of `Buffer` constructor
- [Tests] remove nonexistent tape option
- [Dev Deps] backport from main

## **6.3.2**
- [Fix] follow `allowPrototypes` option during merge (#201, #200)
- [Dev Deps] update `eslint`
- [Fix] chmod a-x
- [Fix] support keys starting with brackets (#202, #200)
- [Tests] up to `node` `v7.7`, `v6.10`,` v4.8`; disable osx builds since they block linux builds

## **6.3.1**
- [Fix] ensure that `allowPrototypes: false` does not ever shadow Object.prototype properties (thanks, @snyk!)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `browserify`, `iconv-lite`, `qs-iconv`, `tape`
- [Tests] on all node minors; improve test matrix
- [Docs] document stringify option `allowDots` (#195)
- [Docs] add empty object and array values example (#195)
- [Docs] Fix minor inconsistency/typo (#192)
- [Docs] document stringify option `sort` (#191)
- [Refactor] `stringify`: throw faster with an invalid encoder
- [Refactor] remove unnecessary escapes (#184)
- Remove contributing.md, since `qs` is no longer part of `hapi` (#183)

## **6.3.0**
- [New] Add support for RFC 1738 (#174, #173)
- [New] `stringify`: Add `serializeDate` option to customize Date serialization (#159)
- [Fix] ensure `utils.merge` handles merging two arrays
- [Refactor] only constructors should be capitalized
- [Refactor] capitalized var names are for constructors only
- [Refactor] avoid using a sparse array
- [Robustness] `formats`: cache `String#replace`
- [Dev Deps] update `browserify`, `eslint`, `@ljharb/eslint-config`; add `safe-publish-latest`
- [Tests] up to `node` `v6.8`, `v4.6`; improve test matrix
- [Tests] flesh out arrayLimit/arrayFormat tests (#107)
- [Tests] skip Object.create tests when null objects are not available
- [Tests] Turn on eslint for test files (#175)

## **6.2.4**
- [Fix] `parse`: ignore `__proto__` keys (#428)
- [Fix] `utils.merge`: avoid a crash with a null target and an array source
- [Fix] `utils.merge`: avoid a crash with a null target and a truthy non-array source
- [Fix] `utils`: `merge`: fix crash when `source` is a truthy primitive & no options are provided
- [Fix] when `parseArrays` is false, properly handle keys ending in `[]`
- [Robustness] `stringify`: avoid relying on a global `undefined` (#427)
- [Refactor] use cached `Array.isArray`
- [Docs] Clarify the need for "arrayLimit" option
- [meta] fix README.md (#399)
- [meta] Clean up license text so it’s properly detected as BSD-3-Clause
- [meta] add FUNDING.yml
- [actions] backport actions from main
- [Tests] use `safer-buffer` instead of `Buffer` constructor
- [Tests] remove nonexistent tape option
- [Dev Deps] backport from main

## **6.2.3**
- [Fix] follow `allowPrototypes` option during merge (#201, #200)
- [Fix] chmod a-x
- [Fix] support keys starting with brackets (#202, #200)
- [Tests] up to `node` `v7.7`, `v6.10`,` v4.8`; disable osx builds since they block linux builds

## **6.2.2**
- [Fix] ensure that `allowPrototypes: false` does not ever shadow Object.prototype properties

## **6.2.1**
- [Fix] ensure `key[]=x&key[]&key[]=y` results in 3, not 2, values
- [Refactor] Be explicit and use `Object.prototype.hasOwnProperty.call`
- [Tests] remove `parallelshell` since it does not reliably report failures
- [Tests] up to `node` `v6.3`, `v5.12`
- [Dev Deps] update `tape`, `eslint`, `@ljharb/eslint-config`, `qs-iconv`

## [**6.2.0**](https://github.com/ljharb/qs/issues?milestone=36&state=closed)
- [New] pass Buffers to the encoder/decoder directly (#161)
- [New] add "encoder" and "decoder" options, for custom param encoding/decoding (#160)
- [Fix] fix compacting of nested sparse arrays (#150)

## **6.1.2**
- [Fix] follow `allowPrototypes` option during merge (#201, #200)
- [Fix] chmod a-x
- [Fix] support keys starting with brackets (#202, #200)
- [Tests] up to `node` `v7.7`, `v6.10`,` v4.8`; disable osx builds since they block linux builds

## **6.1.1**
- [Fix] ensure that `allowPrototypes: false` does not ever shadow Object.prototype properties

## [**6.1.0**](https://github.com/ljharb/qs/issues?milestone=35&state=closed)
- [New] allowDots option for `stringify` (#151)
- [Fix] "sort" option should work at a depth of 3 or more (#151)
- [Fix] Restore `dist` directory; will be removed in v7 (#148)

## **6.0.4**
- [Fix] follow `allowPrototypes` option during merge (#201, #200)
- [Fix] chmod a-x
- [Fix] support keys starting with brackets (#202, #200)
- [Tests] up to `node` `v7.7`, `v6.10`,` v4.8`; disable osx builds since they block linux builds

## **6.0.3**
- [Fix] ensure that `allowPrototypes: false` does not ever shadow Object.prototype properties
- [Fix] Restore `dist` directory; will be removed in v7 (#148)

## [**6.0.2**](https://github.com/ljharb/qs/issues?milestone=33&state=closed)
- Revert ES6 requirement and restore support for node down to v0.8.

## [**6.0.1**](https://github.com/ljharb/qs/issues?milestone=32&state=closed)
- [**#127**](https://github.com/ljharb/qs/pull/127) Fix engines definition in package.json

## [**6.0.0**](https://github.com/ljharb/qs/issues?milestone=31&state=closed)
- [**#124**](https://github.com/ljharb/qs/issues/124) Use ES6 and drop support for node < v4

## **5.2.1**
- [Fix] ensure `key[]=x&key[]&key[]=y` results in 3, not 2, values

## [**5.2.0**](https://github.com/ljharb/qs/issues?milestone=30&state=closed)
- [**#64**](https://github.com/ljharb/qs/issues/64) Add option to sort object keys in the query string

## [**5.1.0**](https://github.com/ljharb/qs/issues?milestone=29&state=closed)
- [**#117**](https://github.com/ljharb/qs/issues/117) make URI encoding stringified results optional
- [**#106**](https://github.com/ljharb/qs/issues/106) Add flag `skipNulls` to optionally skip null values in stringify

## [**5.0.0**](https://github.com/ljharb/qs/issues?milestone=28&state=closed)
- [**#114**](https://github.com/ljharb/qs/issues/114) default allowDots to false
- [**#100**](https://github.com/ljharb/qs/issues/100) include dist to npm

## [**4.0.0**](https://github.com/ljharb/qs/issues?milestone=26&state=closed)
- [**#98**](https://github.com/ljharb/qs/issues/98) make returning plain objects and allowing prototype overwriting properties optional

## [**3.1.0**](https://github.com/ljharb/qs/issues?milestone=24&state=closed)
- [**#89**](https://github.com/ljharb/qs/issues/89) Add option to disable "Transform dot notation to bracket notation"

## [**3.0.0**](https://github.com/ljharb/qs/issues?milestone=23&state=closed)
- [**#80**](https://github.com/ljharb/qs/issues/80) qs.parse silently drops properties
- [**#77**](https://github.com/ljharb/qs/issues/77) Perf boost
- [**#60**](https://github.com/ljharb/qs/issues/60) Add explicit option to disable array parsing
- [**#74**](https://github.com/ljharb/qs/issues/74) Bad parse when turning array into object
- [**#81**](https://github.com/ljharb/qs/issues/81) Add a `filter` option
- [**#68**](https://github.com/ljharb/qs/issues/68) Fixed issue with recursion and passing strings into objects.
- [**#66**](https://github.com/ljharb/qs/issues/66) Add mixed array and object dot notation support Closes: #47
- [**#76**](https://github.com/ljharb/qs/issues/76) RFC 3986
- [**#85**](https://github.com/ljharb/qs/issues/85) No equal sign
- [**#84**](https://github.com/ljharb/qs/issues/84) update license attribute

## [**2.4.1**](https://github.com/ljharb/qs/issues?milestone=20&state=closed)
- [**#73**](https://github.com/ljharb/qs/issues/73) Property 'hasOwnProperty' of object #<Object> is not a function

## [**2.4.0**](https://github.com/ljharb/qs/issues?milestone=19&state=closed)
- [**#70**](https://github.com/ljharb/qs/issues/70) Add arrayFormat option

## [**2.3.3**](https://github.com/ljharb/qs/issues?milestone=18&state=closed)
- [**#59**](https://github.com/ljharb/qs/issues/59) make sure array indexes are >= 0, closes #57
- [**#58**](https://github.com/ljharb/qs/issues/58) make qs usable for browser loader

## [**2.3.2**](https://github.com/ljharb/qs/issues?milestone=17&state=closed)
- [**#55**](https://github.com/ljharb/qs/issues/55) allow merging a string into an object

## [**2.3.1**](https://github.com/ljharb/qs/issues?milestone=16&state=closed)
- [**#52**](https://github.com/ljharb/qs/issues/52) Return "undefined" and "false" instead of throwing "TypeError".

## [**2.3.0**](https://github.com/ljharb/qs/issues?milestone=15&state=closed)
- [**#50**](https://github.com/ljharb/qs/issues/50) add option to omit array indices, closes #46

## [**2.2.5**](https://github.com/ljharb/qs/issues?milestone=14&state=closed)
- [**#39**](https://github.com/ljharb/qs/issues/39) Is there an alternative to Buffer.isBuffer?
- [**#49**](https://github.com/ljharb/qs/issues/49) refactor utils.merge, fixes #45
- [**#41**](https://github.com/ljharb/qs/issues/41) avoid browserifying Buffer, for #39

## [**2.2.4**](https://github.com/ljharb/qs/issues?milestone=13&state=closed)
- [**#38**](https://github.com/ljharb/qs/issues/38) how to handle object keys beginning with a number

## [**2.2.3**](https://github.com/ljharb/qs/issues?milestone=12&state=closed)
- [**#37**](https://github.com/ljharb/qs/issues/37) parser discards first empty value in array
- [**#36**](https://github.com/ljharb/qs/issues/36) Update to lab 4.x

## [**2.2.2**](https://github.com/ljharb/qs/issues?milestone=11&state=closed)
- [**#33**](https://github.com/ljharb/qs/issues/33) Error when plain object in a value
- [**#34**](https://github.com/ljharb/qs/issues/34) use Object.prototype.hasOwnProperty.call instead of obj.hasOwnProperty
- [**#24**](https://github.com/ljharb/qs/issues/24) Changelog? Semver?

## [**2.2.1**](https://github.com/ljharb/qs/issues?milestone=10&state=closed)
- [**#32**](https://github.com/ljharb/qs/issues/32) account for circular references properly, closes #31
- [**#31**](https://github.com/ljharb/qs/issues/31) qs.parse stackoverflow on circular objects

## [**2.2.0**](https://github.com/ljharb/qs/issues?milestone=9&state=closed)
- [**#26**](https://github.com/ljharb/qs/issues/26) Don't use Buffer global if it's not present
- [**#30**](https://github.com/ljharb/qs/issues/30) Bug when merging non-object values into arrays
- [**#29**](https://github.com/ljharb/qs/issues/29) Don't call Utils.clone at the top of Utils.merge
- [**#23**](https://github.com/ljharb/qs/issues/23) Ability to not limit parameters?

## [**2.1.0**](https://github.com/ljharb/qs/issues?milestone=8&state=closed)
- [**#22**](https://github.com/ljharb/qs/issues/22) Enable using a RegExp as delimiter

## [**2.0.0**](https://github.com/ljharb/qs/issues?milestone=7&state=closed)
- [**#18**](https://github.com/ljharb/qs/issues/18) Why is there arrayLimit?
- [**#20**](https://github.com/ljharb/qs/issues/20) Configurable parametersLimit
- [**#21**](https://github.com/ljharb/qs/issues/21) make all limits optional, for #18, for #20

## [**1.2.2**](https://github.com/ljharb/qs/issues?milestone=6&state=closed)
- [**#19**](https://github.com/ljharb/qs/issues/19) Don't overwrite null values

## [**1.2.1**](https://github.com/ljharb/qs/issues?milestone=5&state=closed)
- [**#16**](https://github.com/ljharb/qs/issues/16) ignore non-string delimiters
- [**#15**](https://github.com/ljharb/qs/issues/15) Close code block

## [**1.2.0**](https://github.com/ljharb/qs/issues?milestone=4&state=closed)
- [**#12**](https://github.com/ljharb/qs/issues/12) Add optional delim argument
- [**#13**](https://github.com/ljharb/qs/issues/13) fix #11: flattened keys in array are now correctly parsed

## [**1.1.0**](https://github.com/ljharb/qs/issues?milestone=3&state=closed)
- [**#7**](https://github.com/ljharb/qs/issues/7) Empty values of a POST array disappear after being submitted
- [**#9**](https://github.com/ljharb/qs/issues/9) Should not omit equals signs (=) when value is null
- [**#6**](https://github.com/ljharb/qs/issues/6) Minor grammar fix in README

## [**1.0.2**](https://github.com/ljharb/qs/issues?milestone=2&state=closed)
- [**#5**](https://github.com/ljharb/qs/issues/5) array holes incorrectly copied into object on large index


---

BSD 3-Clause License

Copyright (c) 2014, Nathan LaFreniere and other [contributors](https://github.com/ljharb/qs/graphs/contributors)
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this
   list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice,
   this list of conditions and the following disclaimer in the documentation
   and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its
   contributors may be used to endorse or promote products derived from
   this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


---

<p align="center">
    <img alt="qs" src="./logos/banner_default.png" width="800" />
</p>

# qs <sup>[![Version Badge][npm-version-svg]][package-url]</sup>

[![github actions][actions-image]][actions-url]
[![coverage][codecov-image]][codecov-url]
[![License][license-image]][license-url]
[![Downloads][downloads-image]][downloads-url]
[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/9058/badge)](https://bestpractices.coreinfrastructure.org/projects/9058)

[![npm badge][npm-badge-png]][package-url]

A querystring parsing and stringifying library with some added security.

Lead Maintainer: [Jordan Harband](https://github.com/ljharb)

The **qs** module was originally created and maintained by [TJ Holowaychuk](https://github.com/visionmedia/node-querystring).

## Usage

```javascript
var qs = require('qs');
var assert = require('assert');

var obj = qs.parse('a=c');
assert.deepEqual(obj, { a: 'c' });

var str = qs.stringify(obj);
assert.equal(str, 'a=c');
```

### Parsing Objects

[](#preventEval)
```javascript
qs.parse(string, [options]);
```

**qs** allows you to create nested objects within your query strings, by surrounding the name of sub-keys with square brackets `[]`.
For example, the string `'foo[bar]=baz'` converts to:

```javascript
assert.deepEqual(qs.parse('foo[bar]=baz'), {
    foo: {
        bar: 'baz'
    }
});
```

When using the `plainObjects` option the parsed value is returned as a null object, created via `Object.create(null)` and as such you should be aware that prototype methods will not exist on it and a user may set those names to whatever value they like:

```javascript
var nullObject = qs.parse('a[hasOwnProperty]=b', { plainObjects: true });
assert.deepEqual(nullObject, { a: { hasOwnProperty: 'b' } });
```

By default parameters that would overwrite properties on the object prototype are ignored, if you wish to keep the data from those fields either use `plainObjects` as mentioned above, or set `allowPrototypes` to `true` which will allow user input to overwrite those properties.
*WARNING* It is generally a bad idea to enable this option as it can cause problems when attempting to use the properties that have been overwritten.
Always be careful with this option.

```javascript
var protoObject = qs.parse('a[hasOwnProperty]=b', { allowPrototypes: true });
assert.deepEqual(protoObject, { a: { hasOwnProperty: 'b' } });
```

URI encoded strings work too:

```javascript
assert.deepEqual(qs.parse('a%5Bb%5D=c'), {
    a: { b: 'c' }
});
```

You can also nest your objects, like `'foo[bar][baz]=foobarbaz'`:

```javascript
assert.deepEqual(qs.parse('foo[bar][baz]=foobarbaz'), {
    foo: {
        bar: {
            baz: 'foobarbaz'
        }
    }
});
```

By default, when nesting objects **qs** will only parse up to 5 children deep.
This means if you attempt to parse a string like `'a[b][c][d][e][f][g][h][i]=j'` your resulting object will be:

```javascript
var expected = {
    a: {
        b: {
            c: {
                d: {
                    e: {
                        f: {
                            '[g][h][i]': 'j'
                        }
                    }
                }
            }
        }
    }
};
var string = 'a[b][c][d][e][f][g][h][i]=j';
assert.deepEqual(qs.parse(string), expected);
```

This depth can be overridden by passing a `depth` option to `qs.parse(string, [options])`:

```javascript
var deep = qs.parse('a[b][c][d][e][f][g][h][i]=j', { depth: 1 });
assert.deepEqual(deep, { a: { b: { '[c][d][e][f][g][h][i]': 'j' } } });
```

You can configure **qs** to throw an error when parsing nested input beyond this depth using the `strictDepth` option (defaulted to false):

```javascript
try {
    qs.parse('a[b][c][d][e][f][g][h][i]=j', { depth: 1, strictDepth: true });
} catch (err) {
    assert(err instanceof RangeError);
    assert.strictEqual(err.message, 'Input depth exceeded depth option of 1 and strictDepth is true');
}
```

The depth limit helps mitigate abuse when **qs** is used to parse user input, and it is recommended to keep it a reasonably small number. The strictDepth option adds a layer of protection by throwing an error when the limit is exceeded, allowing you to catch and handle such cases.

For similar reasons, by default **qs** will only parse up to 1000 parameters. This can be overridden by passing a `parameterLimit` option:

```javascript
var limited = qs.parse('a=b&c=d', { parameterLimit: 1 });
assert.deepEqual(limited, { a: 'b' });
```

To bypass the leading question mark, use `ignoreQueryPrefix`:

```javascript
var prefixed = qs.parse('?a=b&c=d', { ignoreQueryPrefix: true });
assert.deepEqual(prefixed, { a: 'b', c: 'd' });
```

An optional delimiter can also be passed:

```javascript
var delimited = qs.parse('a=b;c=d', { delimiter: ';' });
assert.deepEqual(delimited, { a: 'b', c: 'd' });
```

Delimiters can be a regular expression too:

```javascript
var regexed = qs.parse('a=b;c=d,e=f', { delimiter: /[;,]/ });
assert.deepEqual(regexed, { a: 'b', c: 'd', e: 'f' });
```

Option `allowDots` can be used to enable dot notation:

```javascript
var withDots = qs.parse('a.b=c', { allowDots: true });
assert.deepEqual(withDots, { a: { b: 'c' } });
```

Option `decodeDotInKeys` can be used to decode dots in keys
Note: it implies `allowDots`, so `parse` will error if you set `decodeDotInKeys` to `true`, and `allowDots` to `false`.

```javascript
var withDots = qs.parse('name%252Eobj.first=John&name%252Eobj.last=Doe', { decodeDotInKeys: true });
assert.deepEqual(withDots, { 'name.obj': { first: 'John', last: 'Doe' }});
```

Option `allowEmptyArrays` can be used to allowing empty array values in object
```javascript
var withEmptyArrays = qs.parse('foo[]&bar=baz', { allowEmptyArrays: true });
assert.deepEqual(withEmptyArrays, { foo: [], bar: 'baz' });
```

Option `duplicates` can be used to change the behavior when duplicate keys are encountered
```javascript
assert.deepEqual(qs.parse('foo=bar&foo=baz'), { foo: ['bar', 'baz'] });
assert.deepEqual(qs.parse('foo=bar&foo=baz', { duplicates: 'combine' }), { foo: ['bar', 'baz'] });
assert.deepEqual(qs.parse('foo=bar&foo=baz', { duplicates: 'first' }), { foo: 'bar' });
assert.deepEqual(qs.parse('foo=bar&foo=baz', { duplicates: 'last' }), { foo: 'baz' });
```

If you have to deal with legacy browsers or services, there's also support for decoding percent-encoded octets as iso-8859-1:

```javascript
var oldCharset = qs.parse('a=%A7', { charset: 'iso-8859-1' });
assert.deepEqual(oldCharset, { a: '§' });
```

Some services add an initial `utf8=✓` value to forms so that old Internet Explorer versions are more likely to submit the form as utf-8.
Additionally, the server can check the value against wrong encodings of the checkmark character and detect that a query string or `application/x-www-form-urlencoded` body was *not* sent as utf-8, eg. if the form had an `accept-charset` parameter or the containing page had a different character set.

**qs** supports this mechanism via the `charsetSentinel` option.
If specified, the `utf8` parameter will be omitted from the returned object.
It will be used to switch to `iso-8859-1`/`utf-8` mode depending on how the checkmark is encoded.

**Important**: When you specify both the `charset` option and the `charsetSentinel` option, the `charset` will be overridden when the request contains a `utf8` parameter from which the actual charset can be deduced.
In that sense the `charset` will behave as the default charset rather than the authoritative charset.

```javascript
var detectedAsUtf8 = qs.parse('utf8=%E2%9C%93&a=%C3%B8', {
    charset: 'iso-8859-1',
    charsetSentinel: true
});
assert.deepEqual(detectedAsUtf8, { a: 'ø' });

// Browsers encode the checkmark as &#10003; when submitting as iso-8859-1:
var detectedAsIso8859_1 = qs.parse('utf8=%26%2310003%3B&a=%F8', {
    charset: 'utf-8',
    charsetSentinel: true
});
assert.deepEqual(detectedAsIso8859_1, { a: 'ø' });
```

If you want to decode the `&#...;` syntax to the actual character, you can specify the `interpretNumericEntities` option as well:

```javascript
var detectedAsIso8859_1 = qs.parse('a=%26%239786%3B', {
    charset: 'iso-8859-1',
    interpretNumericEntities: true
});
assert.deepEqual(detectedAsIso8859_1, { a: '☺' });
```

It also works when the charset has been detected in `charsetSentinel` mode.

### Parsing Arrays

**qs** can also parse arrays using a similar `[]` notation:

```javascript
var withArray = qs.parse('a[]=b&a[]=c');
assert.deepEqual(withArray, { a: ['b', 'c'] });
```

You may specify an index as well:

```javascript
var withIndexes = qs.parse('a[1]=c&a[0]=b');
assert.deepEqual(withIndexes, { a: ['b', 'c'] });
```

Note that the only difference between an index in an array and a key in an object is that the value between the brackets must be a number to create an array.
When creating arrays with specific indices, **qs** will compact a sparse array to only the existing values preserving their order:

```javascript
var noSparse = qs.parse('a[1]=b&a[15]=c');
assert.deepEqual(noSparse, { a: ['b', 'c'] });
```

You may also use `allowSparse` option to parse sparse arrays:

```javascript
var sparseArray = qs.parse('a[1]=2&a[3]=5', { allowSparse: true });
assert.deepEqual(sparseArray, { a: [, '2', , '5'] });
```

Note that an empty string is also a value, and will be preserved:

```javascript
var withEmptyString = qs.parse('a[]=&a[]=b');
assert.deepEqual(withEmptyString, { a: ['', 'b'] });

var withIndexedEmptyString = qs.parse('a[0]=b&a[1]=&a[2]=c');
assert.deepEqual(withIndexedEmptyString, { a: ['b', '', 'c'] });
```

**qs** will also limit specifying indices in an array to a maximum index of `20`.
Any array members with an index of greater than `20` will instead be converted to an object with the index as the key.
This is needed to handle cases when someone sent, for example, `a[999999999]` and it will take significant time to iterate over this huge array.

```javascript
var withMaxIndex = qs.parse('a[100]=b');
assert.deepEqual(withMaxIndex, { a: { '100': 'b' } });
```

This limit can be overridden by passing an `arrayLimit` option:

```javascript
var withArrayLimit = qs.parse('a[1]=b', { arrayLimit: 0 });
assert.deepEqual(withArrayLimit, { a: { '1': 'b' } });
```

To disable array parsing entirely, set `parseArrays` to `false`.

```javascript
var noParsingArrays = qs.parse('a[]=b', { parseArrays: false });
assert.deepEqual(noParsingArrays, { a: { '0': 'b' } });
```

If you mix notations, **qs** will merge the two items into an object:

```javascript
var mixedNotation = qs.parse('a[0]=b&a[b]=c');
assert.deepEqual(mixedNotation, { a: { '0': 'b', b: 'c' } });
```

You can also create arrays of objects:

```javascript
var arraysOfObjects = qs.parse('a[][b]=c');
assert.deepEqual(arraysOfObjects, { a: [{ b: 'c' }] });
```

Some people use comma to join array, **qs** can parse it:
```javascript
var arraysOfObjects = qs.parse('a=b,c', { comma: true })
assert.deepEqual(arraysOfObjects, { a: ['b', 'c'] })
```
(_this cannot convert nested objects, such as `a={b:1},{c:d}`_)

### Parsing primitive/scalar values (numbers, booleans, null, etc)

By default, all values are parsed as strings.
This behavior will not change and is explained in [issue #91](https://github.com/ljharb/qs/issues/91).

```javascript
var primitiveValues = qs.parse('a=15&b=true&c=null');
assert.deepEqual(primitiveValues, { a: '15', b: 'true', c: 'null' });
```

If you wish to auto-convert values which look like numbers, booleans, and other values into their primitive counterparts, you can use the [query-types Express JS middleware](https://github.com/xpepermint/query-types) which will auto-convert all request query parameters.

### Stringifying

[](#preventEval)
```javascript
qs.stringify(object, [options]);
```

When stringifying, **qs** by default URI encodes output. Objects are stringified as you would expect:

```javascript
assert.equal(qs.stringify({ a: 'b' }), 'a=b');
assert.equal(qs.stringify({ a: { b: 'c' } }), 'a%5Bb%5D=c');
```

This encoding can be disabled by setting the `encode` option to `false`:

```javascript
var unencoded = qs.stringify({ a: { b: 'c' } }, { encode: false });
assert.equal(unencoded, 'a[b]=c');
```

Encoding can be disabled for keys by setting the `encodeValuesOnly` option to `true`:
```javascript
var encodedValues = qs.stringify(
    { a: 'b', c: ['d', 'e=f'], f: [['g'], ['h']] },
    { encodeValuesOnly: true }
);
assert.equal(encodedValues,'a=b&c[0]=d&c[1]=e%3Df&f[0][0]=g&f[1][0]=h');
```

This encoding can also be replaced by a custom encoding method set as `encoder` option:

```javascript
var encoded = qs.stringify({ a: { b: 'c' } }, { encoder: function (str) {
    // Passed in values `a`, `b`, `c`
    return // Return encoded string
}})
```

_(Note: the `encoder` option does not apply if `encode` is `false`)_

Analogue to the `encoder` there is a `decoder` option for `parse` to override decoding of properties and values:

```javascript
var decoded = qs.parse('x=z', { decoder: function (str) {
    // Passed in values `x`, `z`
    return // Return decoded string
}})
```

You can encode keys and values using different logic by using the type argument provided to the encoder:

```javascript
var encoded = qs.stringify({ a: { b: 'c' } }, { encoder: function (str, defaultEncoder, charset, type) {
    if (type === 'key') {
        return // Encoded key
    } else if (type === 'value') {
        return // Encoded value
    }
}})
```

The type argument is also provided to the decoder:

```javascript
var decoded = qs.parse('x=z', { decoder: function (str, defaultDecoder, charset, type) {
    if (type === 'key') {
        return // Decoded key
    } else if (type === 'value') {
        return // Decoded value
    }
}})
```

Examples beyond this point will be shown as though the output is not URI encoded for clarity.
Please note that the return values in these cases *will* be URI encoded during real usage.

When arrays are stringified, they follow the `arrayFormat` option, which defaults to `indices`:

```javascript
qs.stringify({ a: ['b', 'c', 'd'] });
// 'a[0]=b&a[1]=c&a[2]=d'
```

You may override this by setting the `indices` option to `false`, or to be more explicit, the `arrayFormat` option to `repeat`:

```javascript
qs.stringify({ a: ['b', 'c', 'd'] }, { indices: false });
// 'a=b&a=c&a=d'
```

You may use the `arrayFormat` option to specify the format of the output array:

```javascript
qs.stringify({ a: ['b', 'c'] }, { arrayFormat: 'indices' })
// 'a[0]=b&a[1]=c'
qs.stringify({ a: ['b', 'c'] }, { arrayFormat: 'brackets' })
// 'a[]=b&a[]=c'
qs.stringify({ a: ['b', 'c'] }, { arrayFormat: 'repeat' })
// 'a=b&a=c'
qs.stringify({ a: ['b', 'c'] }, { arrayFormat: 'comma' })
// 'a=b,c'
```

Note: when using `arrayFormat` set to `'comma'`, you can also pass the `commaRoundTrip` option set to `true` or `false`, to append `[]` on single-item arrays, so that they can round trip through a parse.

When objects are stringified, by default they use bracket notation:

```javascript
qs.stringify({ a: { b: { c: 'd', e: 'f' } } });
// 'a[b][c]=d&a[b][e]=f'
```

You may override this to use dot notation by setting the `allowDots` option to `true`:

```javascript
qs.stringify({ a: { b: { c: 'd', e: 'f' } } }, { allowDots: true });
// 'a.b.c=d&a.b.e=f'
```

You may encode the dot notation in the keys of object with option `encodeDotInKeys` by setting it to `true`:
Note: it implies `allowDots`, so `stringify` will error if you set `decodeDotInKeys` to `true`, and `allowDots` to `false`.
Caveat: when `encodeValuesOnly` is `true` as well as `encodeDotInKeys`, only dots in keys and nothing else will be encoded.
```javascript
qs.stringify({ "name.obj": { "first": "John", "last": "Doe" } }, { allowDots: true, encodeDotInKeys: true })
// 'name%252Eobj.first=John&name%252Eobj.last=Doe'
```

You may allow empty array values by setting the `allowEmptyArrays` option to `true`:
```javascript
qs.stringify({ foo: [], bar: 'baz' }, { allowEmptyArrays: true });
// 'foo[]&bar=baz'
```

Empty strings and null values will omit the value, but the equals sign (=) remains in place:

```javascript
assert.equal(qs.stringify({ a: '' }), 'a=');
```

Key with no values (such as an empty object or array) will return nothing:

```javascript
assert.equal(qs.stringify({ a: [] }), '');
assert.equal(qs.stringify({ a: {} }), '');
assert.equal(qs.stringify({ a: [{}] }), '');
assert.equal(qs.stringify({ a: { b: []} }), '');
assert.equal(qs.stringify({ a: { b: {}} }), '');
```

Properties that are set to `undefined` will be omitted entirely:

```javascript
assert.equal(qs.stringify({ a: null, b: undefined }), 'a=');
```

The query string may optionally be prepended with a question mark:

```javascript
assert.equal(qs.stringify({ a: 'b', c: 'd' }, { addQueryPrefix: true }), '?a=b&c=d');
```

The delimiter may be overridden with stringify as well:

```javascript
assert.equal(qs.stringify({ a: 'b', c: 'd' }, { delimiter: ';' }), 'a=b;c=d');
```

If you only want to override the serialization of `Date` objects, you can provide a `serializeDate` option:

```javascript
var date = new Date(7);
assert.equal(qs.stringify({ a: date }), 'a=1970-01-01T00:00:00.007Z'.replace(/:/g, '%3A'));
assert.equal(
    qs.stringify({ a: date }, { serializeDate: function (d) { return d.getTime(); } }),
    'a=7'
);
```

You may use the `sort` option to affect the order of parameter keys:

```javascript
function alphabeticalSort(a, b) {
    return a.localeCompare(b);
}
assert.equal(qs.stringify({ a: 'c', z: 'y', b : 'f' }, { sort: alphabeticalSort }), 'a=c&b=f&z=y');
```

Finally, you can use the `filter` option to restrict which keys will be included in the stringified output.
If you pass a function, it will be called for each key to obtain the replacement value.
Otherwise, if you pass an array, it will be used to select properties and array indices for stringification:

```javascript
function filterFunc(prefix, value) {
    if (prefix == 'b') {
        // Return an `undefined` value to omit a property.
        return;
    }
    if (prefix == 'e[f]') {
        return value.getTime();
    }
    if (prefix == 'e[g][0]') {
        return value * 2;
    }
    return value;
}
qs.stringify({ a: 'b', c: 'd', e: { f: new Date(123), g: [2] } }, { filter: filterFunc });
// 'a=b&c=d&e[f]=123&e[g][0]=4'
qs.stringify({ a: 'b', c: 'd', e: 'f' }, { filter: ['a', 'e'] });
// 'a=b&e=f'
qs.stringify({ a: ['b', 'c', 'd'], e: 'f' }, { filter: ['a', 0, 2] });
// 'a[0]=b&a[2]=d'
```

You could also use `filter` to inject custom serialization for user defined types.
Consider you're working with some api that expects query strings of the format for ranges:

```
https://domain.com/endpoint?range=30...70
```

For which you model as:

```javascript
class Range {
    constructor(from, to) {
        this.from = from;
        this.to = to;
    }
}
```

You could _inject_ a custom serializer to handle values of this type:

```javascript
qs.stringify(
    {
        range: new Range(30, 70),
    },
    {
        filter: (prefix, value) => {
            if (value instanceof Range) {
                return `${value.from}...${value.to}`;
            }
            // serialize the usual way
            return value;
        },
    }
);
// range=30...70
```

### Handling of `null` values

By default, `null` values are treated like empty strings:

```javascript
var withNull = qs.stringify({ a: null, b: '' });
assert.equal(withNull, 'a=&b=');
```

Parsing does not distinguish between parameters with and without equal signs.
Both are converted to empty strings.

```javascript
var equalsInsensitive = qs.parse('a&b=');
assert.deepEqual(equalsInsensitive, { a: '', b: '' });
```

To distinguish between `null` values and empty strings use the `strictNullHandling` flag. In the result string the `null`
values have no `=` sign:

```javascript
var strictNull = qs.stringify({ a: null, b: '' }, { strictNullHandling: true });
assert.equal(strictNull, 'a&b=');
```

To parse values without `=` back to `null` use the `strictNullHandling` flag:

```javascript
var parsedStrictNull = qs.parse('a&b=', { strictNullHandling: true });
assert.deepEqual(parsedStrictNull, { a: null, b: '' });
```

To completely skip rendering keys with `null` values, use the `skipNulls` flag:

```javascript
var nullsSkipped = qs.stringify({ a: 'b', c: null}, { skipNulls: true });
assert.equal(nullsSkipped, 'a=b');
```

If you're communicating with legacy systems, you can switch to `iso-8859-1` using the `charset` option:

```javascript
var iso = qs.stringify({ æ: 'æ' }, { charset: 'iso-8859-1' });
assert.equal(iso, '%E6=%E6');
```

Characters that don't exist in `iso-8859-1` will be converted to numeric entities, similar to what browsers do:

```javascript
var numeric = qs.stringify({ a: '☺' }, { charset: 'iso-8859-1' });
assert.equal(numeric, 'a=%26%239786%3B');
```

You can use the `charsetSentinel` option to announce the character by including an `utf8=✓` parameter with the proper encoding if the checkmark, similar to what Ruby on Rails and others do when submitting forms.

```javascript
var sentinel = qs.stringify({ a: '☺' }, { charsetSentinel: true });
assert.equal(sentinel, 'utf8=%E2%9C%93&a=%E2%98%BA');

var isoSentinel = qs.stringify({ a: 'æ' }, { charsetSentinel: true, charset: 'iso-8859-1' });
assert.equal(isoSentinel, 'utf8=%26%2310003%3B&a=%E6');
```

### Dealing with special character sets

By default the encoding and decoding of characters is done in `utf-8`, and `iso-8859-1` support is also built in via the `charset` parameter.

If you wish to encode querystrings to a different character set (i.e.
[Shift JIS](https://en.wikipedia.org/wiki/Shift_JIS)) you can use the
[`qs-iconv`](https://github.com/martinheidegger/qs-iconv) library:

```javascript
var encoder = require('qs-iconv/encoder')('shift_jis');
var shiftJISEncoded = qs.stringify({ a: 'こんにちは！' }, { encoder: encoder });
assert.equal(shiftJISEncoded, 'a=%82%B1%82%F1%82%C9%82%BF%82%CD%81I');
```

This also works for decoding of query strings:

```javascript
var decoder = require('qs-iconv/decoder')('shift_jis');
var obj = qs.parse('a=%82%B1%82%F1%82%C9%82%BF%82%CD%81I', { decoder: decoder });
assert.deepEqual(obj, { a: 'こんにちは！' });
```

### RFC 3986 and RFC 1738 space encoding

RFC3986 used as default option and encodes ' ' to *%20* which is backward compatible.
In the same time, output can be stringified as per RFC1738 with ' ' equal to '+'.

```
assert.equal(qs.stringify({ a: 'b c' }), 'a=b%20c');
assert.equal(qs.stringify({ a: 'b c' }, { format : 'RFC3986' }), 'a=b%20c');
assert.equal(qs.stringify({ a: 'b c' }, { format : 'RFC1738' }), 'a=b+c');
```

## Security

Please email [@ljharb](https://github.com/ljharb) or see https://tidelift.com/security if you have a potential security vulnerability to report.

## qs for enterprise

Available as part of the Tidelift Subscription

The maintainers of qs and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications.
Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use.
[Learn more.](https://tidelift.com/subscription/pkg/npm-qs?utm_source=npm-qs&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)

[package-url]: https://npmjs.org/package/qs
[npm-version-svg]: https://versionbadg.es/ljharb/qs.svg
[deps-svg]: https://david-dm.org/ljharb/qs.svg
[deps-url]: https://david-dm.org/ljharb/qs
[dev-deps-svg]: https://david-dm.org/ljharb/qs/dev-status.svg
[dev-deps-url]: https://david-dm.org/ljharb/qs#info=devDependencies
[npm-badge-png]: https://nodei.co/npm/qs.png?downloads=true&stars=true
[license-image]: https://img.shields.io/npm/l/qs.svg
[license-url]: LICENSE
[downloads-image]: https://img.shields.io/npm/dm/qs.svg
[downloads-url]: https://npm-stat.com/charts.html?package=qs
[codecov-image]: https://codecov.io/gh/ljharb/qs/branch/main/graphs/badge.svg
[codecov-url]: https://app.codecov.io/gh/ljharb/qs/
[actions-image]: https://img.shields.io/endpoint?url=https://github-actions-badge-u3jn4tfpocch.runkit.sh/ljharb/qs
[actions-url]: https://github.com/ljharb/qs/actions

## Acknowledgements

qs logo by [NUMI](https://github.com/numi-hq/open-design):

[<img src="https://raw.githubusercontent.com/numi-hq/open-design/main/assets/numi-lockup.png" alt="NUMI Logo" style="width: 200px;"/>](https://numi.tech/?ref=qs)


---

```
   ____  __  _____  __  _____
  / __ `/ / / / _ \/ / / / _ \
 / /_/ / /_/ /  __/ /_/ /  __/
 \__, /\__,_/\___/\__,_/\___/
   /_/
```
Asynchronous function queue with adjustable concurrency.

[![npm](http://img.shields.io/npm/v/queue.svg?style=flat-square)](http://www.npmjs.org/queue)
[![tests](https://img.shields.io/travis/jessetane/queue.svg?style=flat-square&branch=master)](https://travis-ci.org/jessetane/queue)
[![coverage](https://img.shields.io/coveralls/jessetane/queue.svg?style=flat-square&branch=master)](https://coveralls.io/r/jessetane/queue)

This module exports a class `Queue` that implements most of the `Array` API. Pass async functions (ones that accept a callback or return a promise) to an instance's additive array methods. Processing begins when you call `q.start()`.

## Example
`npm run example`
``` javascript
var queue = require('../')

var q = queue({ results: [] })

// add jobs using the familiar Array API
q.push(function (cb) {
  const result = 'two'
  cb(null, result)
})

q.push(
  function (cb) {
    const result = 'four'
    cb(null, result)
  },
  function (cb) {
    const result = 'five'
    cb(null, result)
  }
)

// jobs can accept a callback or return a promise
q.push(function () {
  return new Promise(function (resolve, reject) {
    const result = 'one'
    resolve(result)
  })
})

q.unshift(function (cb) {
  const result = 'one'
  cb(null, result)
})

q.splice(2, 0, function (cb) {
  const result = 'three'
  cb(null, result)
})

// use the timeout feature to deal with jobs that
// take too long or forget to execute a callback
q.timeout = 100

q.on('timeout', function (next, job) {
  console.log('job timed out:', job.toString().replace(/\n/g, ''))
  next()
})

q.push(function (cb) {
  setTimeout(function () {
    console.log('slow job finished')
    cb()
  }, 200)
})

q.push(function (cb) {
  console.log('forgot to execute callback')
})

// jobs can also override the queue's timeout
// on a per-job basis
function extraSlowJob (cb) {
  setTimeout(function () {
    console.log('extra slow job finished')
    cb()
  }, 400)
}

extraSlowJob.timeout = 500
q.push(extraSlowJob)

// jobs can also opt-out of the timeout altogether
function superSlowJob (cb) {
  setTimeout(function () {
    console.log('super slow job finished')
    cb()
  }, 1000)
}

superSlowJob.timeout = null
q.push(superSlowJob)

// get notified when jobs complete
q.on('success', function (result, job) {
  console.log('job finished processing:', job.toString().replace(/\n/g, ''))
  console.log('The result is:', result)
})

// begin processing, get notified on end / failure
q.start(function (err) {
  if (err) throw err
  console.log('all done:', q.results)
})

```

## Install
`npm install queue`

_Note_: You may need to install the [`events`](https://github.com/Gozala/events) dependency if 
your environment does not have it by default (eg. browser, react-native). 

## Test
`npm test`
`npm run test-browser`

## API

### `var q = queue([opts])`
Constructor. `opts` may contain inital values for:
* `q.concurrency`
* `q.timeout`
* `q.autostart`
* `q.results`

## Instance methods
### `q.start([cb])`
cb, if passed, will be called when the queue empties or when an error occurs.

### `q.stop()`
Stops the queue. can be resumed with `q.start()`.

### `q.end([err])`
Stop and empty the queue immediately.

## Instance methods mixed in from `Array`
Mozilla has docs on how these methods work [here](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array). Note that `slice` does not copy the queue.
### `q.push(element1, ..., elementN)`
### `q.unshift(element1, ..., elementN)`
### `q.splice(index , howMany[, element1[, ...[, elementN]]])`
### `q.pop()`
### `q.shift()`
### `q.slice(begin[, end])`
### `q.reverse()`
### `q.indexOf(searchElement[, fromIndex])`
### `q.lastIndexOf(searchElement[, fromIndex])`

## Properties
### `q.concurrency`
Max number of jobs the queue should process concurrently, defaults to `Infinity`.

### `q.timeout`
Milliseconds to wait for a job to execute its callback. This can be overridden by specifying a `timeout` property on a per-job basis.

### `q.autostart`
Ensures the queue is always running if jobs are available. Useful in situations where you are using a queue only for concurrency control.

### `q.results`
An array to set job callback arguments on.

### `q.length`
Jobs pending + jobs to process (readonly).

## Events

### `q.emit('start', job)`
Immediately before a job begins to execute.

### `q.emit('success', result, job)`
After a job executes its callback.

### `q.emit('error', err, job)`
After a job passes an error to its callback.

### `q.emit('timeout', continue, job)`
After `q.timeout` milliseconds have elapsed and a job has not executed its callback.

### `q.emit('end'[, err])`
After all jobs have been processed

## Releases
The latest stable release is published to [npm](http://npmjs.org/queue). Abbreviated changelog below:
* [6.0](https://github.com/jessetane/queue/archive/6.0.1.tar.gz)
  * Add `start` event before job begins (@joelgriffith)
  * Add `timeout` property on a job to override the queue's timeout (@joelgriffith)
* [5.0](https://github.com/jessetane/queue/archive/5.0.0.tar.gz)
  * Updated TypeScript bindings (@Codex-)
* [4.4](https://github.com/jessetane/queue/archive/4.4.0.tar.gz)
  * Add results feature
* [4.3](https://github.com/jessetane/queue/archive/4.3.0.tar.gz)
  * Add promise support (@kwolfy)
* [4.2](https://github.com/jessetane/queue/archive/4.2.0.tar.gz)
  * Unref timers on end
* [4.1](https://github.com/jessetane/queue/archive/4.1.0.tar.gz)
  * Add autostart feature
* [4.0](https://github.com/jessetane/queue/archive/4.0.0.tar.gz)
  * Change license to MIT
* [3.1.x](https://github.com/jessetane/queue/archive/3.0.6.tar.gz)
  * Add .npmignore
* [3.0.x](https://github.com/jessetane/queue/archive/3.0.6.tar.gz)
  * Change the default concurrency to `Infinity`
  * Allow `q.start()` to accept an optional callback executed on `q.emit('end')`
* [2.x](https://github.com/jessetane/queue/archive/2.2.0.tar.gz)
  * Major api changes / not backwards compatible with 1.x
* [1.x](https://github.com/jessetane/queue/archive/1.0.2.tar.gz)
  * Early prototype

## License
Copyright © 2014 Jesse Tane <jesse.tane@gmail.com>

This work is free. You can redistribute it and/or modify it under the
terms of the [MIT License](https://opensource.org/licenses/MIT).
See LICENSE for full details.


---

# queue-microtask [![ci][ci-image]][ci-url] [![npm][npm-image]][npm-url] [![downloads][downloads-image]][downloads-url] [![javascript style guide][standard-image]][standard-url]

[ci-image]: https://img.shields.io/github/workflow/status/feross/queue-microtask/ci/master
[ci-url]: https://github.com/feross/queue-microtask/actions
[npm-image]: https://img.shields.io/npm/v/queue-microtask.svg
[npm-url]: https://npmjs.org/package/queue-microtask
[downloads-image]: https://img.shields.io/npm/dm/queue-microtask.svg
[downloads-url]: https://npmjs.org/package/queue-microtask
[standard-image]: https://img.shields.io/badge/code_style-standard-brightgreen.svg
[standard-url]: https://standardjs.com

### fast, tiny [`queueMicrotask`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/queueMicrotask) shim for modern engines

- Use [`queueMicrotask`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/queueMicrotask) in all modern JS engines.
- No dependencies. Less than 10 lines. No shims or complicated fallbacks.
- Optimal performance in all modern environments
  - Uses `queueMicrotask` in modern environments
  - Fallback to `Promise.resolve().then(fn)` in Node.js 10 and earlier, and old browsers (same performance as `queueMicrotask`)

## install

```
npm install queue-microtask
```

## usage

```js
const queueMicrotask = require('queue-microtask')

queueMicrotask(() => { /* this will run soon */ })
```

## What is `queueMicrotask` and why would one use it?

The `queueMicrotask` function is a WHATWG standard. It queues a microtask to be executed prior to control returning to the event loop.

A microtask is a short function which will run after the current task has completed its work and when there is no other code waiting to be run before control of the execution context is returned to the event loop.

The code `queueMicrotask(fn)` is equivalent to the code `Promise.resolve().then(fn)`. It is also very similar to [`process.nextTick(fn)`](https://nodejs.org/api/process.html#process_process_nexttick_callback_args) in Node.

Using microtasks lets code run without interfering with any other, potentially higher priority, code that is pending, but before the JS engine regains control over the execution context.

See the [spec](https://html.spec.whatwg.org/multipage/timers-and-user-prompts.html#microtask-queuing) or [Node documentation](https://nodejs.org/api/globals.html#globals_queuemicrotask_callback) for more information.

## Who is this package for?

This package allows you to use `queueMicrotask` safely in all modern JS engines. Use it if you prioritize small JS bundle size over support for old browsers.

If you just need to support Node 12 and later, use `queueMicrotask` directly. If you need to support all versions of Node, use this package.

## Why not use `process.nextTick`?

In Node, `queueMicrotask` and `process.nextTick` are [essentially equivalent](https://nodejs.org/api/globals.html#globals_queuemicrotask_callback), though there are [subtle differences](https://github.com/YuzuJS/setImmediate#macrotasks-and-microtasks) that don't matter in most situations.

You can think of `queueMicrotask` as a standardized version of `process.nextTick` that works in the browser. No need to rely on your browser bundler to shim `process` for the browser environment.

## Why not use `setTimeout(fn, 0)`?

This approach is the most compatible, but it has problems. Modern browsers throttle timers severely, so `setTimeout(…, 0)` usually takes at least 4ms to run. Furthermore, the throttling gets even worse if the page is backgrounded. If you have many `setTimeout` calls, then this can severely limit the performance of your program.

## Why not use a microtask library like [`immediate`](https://www.npmjs.com/package/immediate) or [`asap`](https://www.npmjs.com/package/asap)?

These packages are great! However, if you prioritize small JS bundle size over optimal performance in old browsers then you may want to consider this package.

This package (`queue-microtask`) is four times smaller than `immediate`, twice as small as `asap`, and twice as small as using `process.nextTick` and letting the browser bundler shim it automatically.

Note: This package throws an exception in JS environments which lack `Promise` support -- which are usually very old browsers and Node.js versions.

Since the `queueMicrotask` API is supported in Node.js, Chrome, Firefox, Safari, Opera, and Edge, **the vast majority of users will get optimal performance**. Any JS environment with `Promise`, which is almost all of them, also get optimal performance. If you need support for JS environments which lack `Promise` support, use one of the alternative packages.

## What is a shim?

> In computer programming, a shim is a library that transparently intercepts API calls and changes the arguments passed, handles the operation itself or redirects the operation elsewhere. – [Wikipedia](https://en.wikipedia.org/wiki/Shim_(computing))

This package could also be described as a "ponyfill".

> A ponyfill is almost the same as a polyfill, but not quite. Instead of patching functionality for older browsers, a ponyfill provides that functionality as a standalone module you can use. – [PonyFoo](https://ponyfoo.com/articles/polyfills-or-ponyfills)

## API

### `queueMicrotask(fn)`

The `queueMicrotask()` method queues a microtask.

The `fn` argument is a function to be executed after all pending tasks have completed but before yielding control to the browser's event loop.

## license

MIT. Copyright (c) [Feross Aboukhadijeh](https://feross.org).


---

# quick-lru [![Build Status](https://travis-ci.org/sindresorhus/quick-lru.svg?branch=master)](https://travis-ci.org/sindresorhus/quick-lru) [![Coverage Status](https://coveralls.io/repos/github/sindresorhus/quick-lru/badge.svg?branch=master)](https://coveralls.io/github/sindresorhus/quick-lru?branch=master)

> Simple [“Least Recently Used” (LRU) cache](https://en.m.wikipedia.org/wiki/Cache_replacement_policies#Least_Recently_Used_.28LRU.29)

Useful when you need to cache something and limit memory usage.

Inspired by the [`hashlru` algorithm](https://github.com/dominictarr/hashlru#algorithm), but instead uses [`Map`](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Map) to support keys of any type, not just strings, and values can be `undefined`.

## Install

```
$ npm install quick-lru
```

## Usage

```js
const QuickLRU = require('quick-lru');

const lru = new QuickLRU({maxSize: 1000});

lru.set('🦄', '🌈');

lru.has('🦄');
//=> true

lru.get('🦄');
//=> '🌈'
```

## API

### new QuickLRU(options?)

Returns a new instance.

### options

Type: `object`

#### maxSize

*Required*\
Type: `number`

The maximum number of items before evicting the least recently used items.

#### onEviction

*Optional*\
Type: `(key, value) => void`

Called right before an item is evicted from the cache.

Useful for side effects or for items like object URLs that need explicit cleanup (`revokeObjectURL`).

### Instance

The instance is [`iterable`](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Iteration_protocols) so you can use it directly in a [`for…of`](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Statements/for...of) loop.

Both `key` and `value` can be of any type.

#### .set(key, value)

Set an item. Returns the instance.

#### .get(key)

Get an item.

#### .has(key)

Check if an item exists.

#### .peek(key)

Get an item without marking it as recently used.

#### .delete(key)

Delete an item.

Returns `true` if the item is removed or `false` if the item doesn't exist.

#### .clear()

Delete all items.

#### .keys()

Iterable for all the keys.

#### .values()

Iterable for all the values.

#### .size

The stored item count.

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-quick-lru?utm_source=npm-quick-lru&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

randombytes
===

[![Version](http://img.shields.io/npm/v/randombytes.svg)](https://www.npmjs.org/package/randombytes) [![Build Status](https://travis-ci.org/crypto-browserify/randombytes.svg?branch=master)](https://travis-ci.org/crypto-browserify/randombytes)

randombytes from node that works in the browser.  In node you just get crypto.randomBytes, but in the browser it uses .crypto/msCrypto.getRandomValues

```js
var randomBytes = require('randombytes');
randomBytes(16);//get 16 random bytes
randomBytes(16, function (err, resp) {
  // resp is 16 random bytes
});
```


---

1.2.0 / 2016-06-01
==================

  * Add `combine` option to combine overlapping ranges

1.1.0 / 2016-05-13
==================

  * Fix incorrectly returning -1 when there is at least one valid range
  * perf: remove internal function

1.0.3 / 2015-10-29
==================

  * perf: enable strict mode

1.0.2 / 2014-09-08
==================

  * Support Node.js 0.6

1.0.1 / 2014-09-07
==================

  * Move repository to jshttp

1.0.0 / 2013-12-11
==================

  * Add repository to package.json
  * Add MIT license

0.0.4 / 2012-06-17
==================

  * Change ret -1 for unsatisfiable and -2 when invalid

0.0.3 / 2012-06-17
==================

  * Fix last-byte-pos default to len - 1

0.0.2 / 2012-06-14
==================

  * Add `.type`

0.0.1 / 2012-06-11
==================

  * Initial release


---

# range-parser

[![NPM Version][npm-image]][npm-url]
[![NPM Downloads][downloads-image]][downloads-url]
[![Node.js Version][node-version-image]][node-version-url]
[![Build Status][travis-image]][travis-url]
[![Test Coverage][coveralls-image]][coveralls-url]

Range header field parser.

## Installation

```
$ npm install range-parser
```

## API

```js
var parseRange = require('range-parser')
```

### parseRange(size, header, options)

Parse the given `header` string where `size` is the maximum size of the resource.
An array of ranges will be returned or negative numbers indicating an error parsing.

  * `-2` signals a malformed header string
  * `-1` signals an unsatisfiable range

```js
// parse header from request
var range = parseRange(size, req.headers.range)

// the type of the range
if (range.type === 'bytes') {
  // the ranges
  range.forEach(function (r) {
    // do something with r.start and r.end
  })
}
```

#### Options

These properties are accepted in the options object.

##### combine

Specifies if overlapping & adjacent ranges should be combined, defaults to `false`.
When `true`, ranges will be combined and returned as if they were specified that
way in the header.

```js
parseRange(100, 'bytes=50-55,0-10,5-10,56-60', { combine: true })
// => [
//      { start: 0,  end: 10 },
//      { start: 50, end: 60 }
//    ]
```

## License

[MIT](LICENSE)

[npm-image]: https://img.shields.io/npm/v/range-parser.svg
[npm-url]: https://npmjs.org/package/range-parser
[node-version-image]: https://img.shields.io/node/v/range-parser.svg
[node-version-url]: https://nodejs.org/endownload
[travis-image]: https://img.shields.io/travis/jshttp/range-parser.svg
[travis-url]: https://travis-ci.org/jshttp/range-parser
[coveralls-image]: https://img.shields.io/coveralls/jshttp/range-parser.svg
[coveralls-url]: https://coveralls.io/r/jshttp/range-parser
[downloads-image]: https://img.shields.io/npm/dm/range-parser.svg
[downloads-url]: https://npmjs.org/package/range-parser


---

2.5.2 / 2023-02-21
==================

  * Fix error message for non-stream argument

2.5.1 / 2022-02-28
==================

  * Fix error on early async hooks implementations

2.5.0 / 2022-02-21
==================

  * Prevent loss of async hooks context
  * Prevent hanging when stream is not readable
  * deps: http-errors@2.0.0
    - deps: depd@2.0.0
    - deps: statuses@2.0.1

2.4.3 / 2022-02-14
==================

  * deps: bytes@3.1.2

2.4.2 / 2021-11-16
==================

  * deps: bytes@3.1.1
  * deps: http-errors@1.8.1
    - deps: setprototypeof@1.2.0
    - deps: toidentifier@1.0.1

2.4.1 / 2019-06-25
==================

  * deps: http-errors@1.7.3
    - deps: inherits@2.0.4

2.4.0 / 2019-04-17
==================

  * deps: bytes@3.1.0
    - Add petabyte (`pb`) support
  * deps: http-errors@1.7.2
    - Set constructor name when possible
    - deps: setprototypeof@1.1.1
    - deps: statuses@'>= 1.5.0 < 2'
  * deps: iconv-lite@0.4.24
    - Added encoding MIK

2.3.3 / 2018-05-08
==================

  * deps: http-errors@1.6.3
    - deps: depd@~1.1.2
    - deps: setprototypeof@1.1.0
    - deps: statuses@'>= 1.3.1 < 2'
  * deps: iconv-lite@0.4.23
    - Fix loading encoding with year appended
    - Fix deprecation warnings on Node.js 10+

2.3.2 / 2017-09-09
==================

  * deps: iconv-lite@0.4.19
    - Fix ISO-8859-1 regression
    - Update Windows-1255

2.3.1 / 2017-09-07
==================

  * deps: bytes@3.0.0
  * deps: http-errors@1.6.2
    - deps: depd@1.1.1
  * perf: skip buffer decoding on overage chunk

2.3.0 / 2017-08-04
==================

  * Add TypeScript definitions
  * Use `http-errors` for standard emitted errors
  * deps: bytes@2.5.0
  * deps: iconv-lite@0.4.18
    - Add support for React Native
    - Add a warning if not loaded as utf-8
    - Fix CESU-8 decoding in Node.js 8
    - Improve speed of ISO-8859-1 encoding

2.2.0 / 2017-01-02
==================

  * deps: iconv-lite@0.4.15
    - Added encoding MS-31J
    - Added encoding MS-932
    - Added encoding MS-936
    - Added encoding MS-949
    - Added encoding MS-950
    - Fix GBK/GB18030 handling of Euro character

2.1.7 / 2016-06-19
==================

  * deps: bytes@2.4.0
  * perf: remove double-cleanup on happy path

2.1.6 / 2016-03-07
==================

  * deps: bytes@2.3.0
    - Drop partial bytes on all parsed units
    - Fix parsing byte string that looks like hex

2.1.5 / 2015-11-30
==================

  * deps: bytes@2.2.0
  * deps: iconv-lite@0.4.13

2.1.4 / 2015-09-27
==================

  * Fix masking critical errors from `iconv-lite`
  * deps: iconv-lite@0.4.12
    - Fix CESU-8 decoding in Node.js 4.x

2.1.3 / 2015-09-12
==================

  * Fix sync callback when attaching data listener causes sync read
    - Node.js 0.10 compatibility issue

2.1.2 / 2015-07-05
==================

  * Fix error stack traces to skip `makeError`
  * deps: iconv-lite@0.4.11
    - Add encoding CESU-8

2.1.1 / 2015-06-14
==================

  * Use `unpipe` module for unpiping requests

2.1.0 / 2015-05-28
==================

  * deps: iconv-lite@0.4.10
    - Improved UTF-16 endianness detection
    - Leading BOM is now removed when decoding
    - The encoding UTF-16 without BOM now defaults to UTF-16LE when detection fails

2.0.2 / 2015-05-21
==================

  * deps: bytes@2.1.0
    - Slight optimizations

2.0.1 / 2015-05-10
==================

  * Fix a false-positive when unpiping in Node.js 0.8

2.0.0 / 2015-05-08
==================

  * Return a promise without callback instead of thunk
  * deps: bytes@2.0.1
    - units no longer case sensitive when parsing

1.3.4 / 2015-04-15
==================

  * Fix hanging callback if request aborts during read
  * deps: iconv-lite@0.4.8
    - Add encoding alias UNICODE-1-1-UTF-7

1.3.3 / 2015-02-08
==================

  * deps: iconv-lite@0.4.7
    - Gracefully support enumerables on `Object.prototype`

1.3.2 / 2015-01-20
==================

  * deps: iconv-lite@0.4.6
    - Fix rare aliases of single-byte encodings

1.3.1 / 2014-11-21
==================

  * deps: iconv-lite@0.4.5
    - Fix Windows-31J and X-SJIS encoding support

1.3.0 / 2014-07-20
==================

  * Fully unpipe the stream on error
    - Fixes `Cannot switch to old mode now` error on Node.js 0.10+

1.2.3 / 2014-07-20
==================

  * deps: iconv-lite@0.4.4
    - Added encoding UTF-7

1.2.2 / 2014-06-19
==================

  * Send invalid encoding error to callback

1.2.1 / 2014-06-15
==================

  * deps: iconv-lite@0.4.3
    - Added encodings UTF-16BE and UTF-16 with BOM

1.2.0 / 2014-06-13
==================

  * Passing string as `options` interpreted as encoding
  * Support all encodings from `iconv-lite`

1.1.7 / 2014-06-12
==================

  * use `string_decoder` module from npm

1.1.6 / 2014-05-27
==================

  * check encoding for old streams1
  * support node.js < 0.10.6

1.1.5 / 2014-05-14
==================

  * bump bytes

1.1.4 / 2014-04-19
==================

  * allow true as an option
  * bump bytes

1.1.3 / 2014-03-02
==================

  * fix case when length=null

1.1.2 / 2013-12-01
==================

  * be less strict on state.encoding check

1.1.1 / 2013-11-27
==================

  * add engines

1.1.0 / 2013-11-27
==================

  * add err.statusCode and err.type
  * allow for encoding option to be true
  * pause the stream instead of dumping on error
  * throw if the stream's encoding is set

1.0.1 / 2013-11-19
==================

  * dont support streams1, throw if dev set encoding

1.0.0 / 2013-11-17
==================

  * rename `expected` option to `length`

0.2.0 / 2013-11-15
==================

  * republish

0.1.1 / 2013-11-15
==================

  * use bytes

0.1.0 / 2013-11-11
==================

  * generator support

0.0.3 / 2013-10-10
==================

  * update repo

0.0.2 / 2013-09-14
==================

  * dump stream on bad headers
  * listen to events after defining received and buffers

0.0.1 / 2013-09-14
==================

  * Initial release


---

# raw-body

[![NPM Version][npm-image]][npm-url]
[![NPM Downloads][downloads-image]][downloads-url]
[![Node.js Version][node-version-image]][node-version-url]
[![Build status][github-actions-ci-image]][github-actions-ci-url]
[![Test coverage][coveralls-image]][coveralls-url]

Gets the entire buffer of a stream either as a `Buffer` or a string.
Validates the stream's length against an expected length and maximum limit.
Ideal for parsing request bodies.

## Install

This is a [Node.js](https://nodejs.org/en/) module available through the
[npm registry](https://www.npmjs.com/). Installation is done using the
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):

```sh
$ npm install raw-body
```

### TypeScript

This module includes a [TypeScript](https://www.typescriptlang.org/)
declaration file to enable auto complete in compatible editors and type
information for TypeScript projects. This module depends on the Node.js
types, so install `@types/node`:

```sh
$ npm install @types/node
```

## API

```js
var getRawBody = require('raw-body')
```

### getRawBody(stream, [options], [callback])

**Returns a promise if no callback specified and global `Promise` exists.**

Options:

- `length` - The length of the stream.
  If the contents of the stream do not add up to this length,
  an `400` error code is returned.
- `limit` - The byte limit of the body.
  This is the number of bytes or any string format supported by
  [bytes](https://www.npmjs.com/package/bytes),
  for example `1000`, `'500kb'` or `'3mb'`.
  If the body ends up being larger than this limit,
  a `413` error code is returned.
- `encoding` - The encoding to use to decode the body into a string.
  By default, a `Buffer` instance will be returned when no encoding is specified.
  Most likely, you want `utf-8`, so setting `encoding` to `true` will decode as `utf-8`.
  You can use any type of encoding supported by [iconv-lite](https://www.npmjs.org/package/iconv-lite#readme).

You can also pass a string in place of options to just specify the encoding.

If an error occurs, the stream will be paused, everything unpiped,
and you are responsible for correctly disposing the stream.
For HTTP requests, you may need to finish consuming the stream if
you want to keep the socket open for future requests. For streams
that use file descriptors, you should `stream.destroy()` or
`stream.close()` to prevent leaks.

## Errors

This module creates errors depending on the error condition during reading.
The error may be an error from the underlying Node.js implementation, but is
otherwise an error created by this module, which has the following attributes:

  * `limit` - the limit in bytes
  * `length` and `expected` - the expected length of the stream
  * `received` - the received bytes
  * `encoding` - the invalid encoding
  * `status` and `statusCode` - the corresponding status code for the error
  * `type` - the error type

### Types

The errors from this module have a `type` property which allows for the programmatic
determination of the type of error returned.

#### encoding.unsupported

This error will occur when the `encoding` option is specified, but the value does
not map to an encoding supported by the [iconv-lite](https://www.npmjs.org/package/iconv-lite#readme)
module.

#### entity.too.large

This error will occur when the `limit` option is specified, but the stream has
an entity that is larger.

#### request.aborted

This error will occur when the request stream is aborted by the client before
reading the body has finished.

#### request.size.invalid

This error will occur when the `length` option is specified, but the stream has
emitted more bytes.

#### stream.encoding.set

This error will occur when the given stream has an encoding set on it, making it
a decoded stream. The stream should not have an encoding set and is expected to
emit `Buffer` objects.

#### stream.not.readable

This error will occur when the given stream is not readable.

## Examples

### Simple Express example

```js
var contentType = require('content-type')
var express = require('express')
var getRawBody = require('raw-body')

var app = express()

app.use(function (req, res, next) {
  getRawBody(req, {
    length: req.headers['content-length'],
    limit: '1mb',
    encoding: contentType.parse(req).parameters.charset
  }, function (err, string) {
    if (err) return next(err)
    req.text = string
    next()
  })
})

// now access req.text
```

### Simple Koa example

```js
var contentType = require('content-type')
var getRawBody = require('raw-body')
var koa = require('koa')

var app = koa()

app.use(function * (next) {
  this.text = yield getRawBody(this.req, {
    length: this.req.headers['content-length'],
    limit: '1mb',
    encoding: contentType.parse(this.req).parameters.charset
  })
  yield next
})

// now access this.text
```

### Using as a promise

To use this library as a promise, simply omit the `callback` and a promise is
returned, provided that a global `Promise` is defined.

```js
var getRawBody = require('raw-body')
var http = require('http')

var server = http.createServer(function (req, res) {
  getRawBody(req)
    .then(function (buf) {
      res.statusCode = 200
      res.end(buf.length + ' bytes submitted')
    })
    .catch(function (err) {
      res.statusCode = 500
      res.end(err.message)
    })
})

server.listen(3000)
```

### Using with TypeScript

```ts
import * as getRawBody from 'raw-body';
import * as http from 'http';

const server = http.createServer((req, res) => {
  getRawBody(req)
  .then((buf) => {
    res.statusCode = 200;
    res.end(buf.length + ' bytes submitted');
  })
  .catch((err) => {
    res.statusCode = err.statusCode;
    res.end(err.message);
  });
});

server.listen(3000);
```

## License

[MIT](LICENSE)

[npm-image]: https://img.shields.io/npm/v/raw-body.svg
[npm-url]: https://npmjs.org/package/raw-body
[node-version-image]: https://img.shields.io/node/v/raw-body.svg
[node-version-url]: https://nodejs.org/en/download/
[coveralls-image]: https://img.shields.io/coveralls/stream-utils/raw-body/master.svg
[coveralls-url]: https://coveralls.io/r/stream-utils/raw-body?branch=master
[downloads-image]: https://img.shields.io/npm/dm/raw-body.svg
[downloads-url]: https://npmjs.org/package/raw-body
[github-actions-ci-image]: https://img.shields.io/github/actions/workflow/status/stream-utils/raw-body/ci.yml?branch=master&label=ci
[github-actions-ci-url]: https://github.com/jshttp/stream-utils/raw-body?query=workflow%3Aci


---

# Security Policies and Procedures

## Reporting a Bug

The `raw-body` team and community take all security bugs seriously. Thank you
for improving the security of Express. We appreciate your efforts and
responsible disclosure and will make every effort to acknowledge your
contributions.

Report security bugs by emailing the current owners of `raw-body`. This information
can be found in the npm registry using the command `npm owner ls raw-body`.
If unsure or unable to get the information from the above, open an issue
in the [project issue tracker](https://github.com/stream-utils/raw-body/issues)
asking for the current contact information.

To ensure the timely response to your report, please ensure that the entirety
of the report is contained within the email body and not solely behind a web
link or an attachment.

At least one owner will acknowledge your email within 48 hours, and will send a
more detailed response within 48 hours indicating the next steps in handling
your report. After the initial reply to your report, the owners will
endeavor to keep you informed of the progress towards a fix and full
announcement, and may ask for additional information or guidance.


---

3.1.2 / 2022-01-27
==================

  * Fix return value for un-parsable strings

3.1.1 / 2021-11-15
==================

  * Fix "thousandsSeparator" incorrecting formatting fractional part

3.1.0 / 2019-01-22
==================

  * Add petabyte (`pb`) support

3.0.0 / 2017-08-31
==================

  * Change "kB" to "KB" in format output
  * Remove support for Node.js 0.6
  * Remove support for ComponentJS

2.5.0 / 2017-03-24
==================

  * Add option "unit"

2.4.0 / 2016-06-01
==================

  * Add option "unitSeparator"

2.3.0 / 2016-02-15
==================

  * Drop partial bytes on all parsed units
  * Fix non-finite numbers to `.format` to return `null`
  * Fix parsing byte string that looks like hex
  * perf: hoist regular expressions

2.2.0 / 2015-11-13
==================

  * add option "decimalPlaces"
  * add option "fixedDecimals"

2.1.0 / 2015-05-21
==================

  * add `.format` export
  * add `.parse` export

2.0.2 / 2015-05-20
==================

  * remove map recreation
  * remove unnecessary object construction

2.0.1 / 2015-05-07
==================

  * fix browserify require
  * remove node.extend dependency

2.0.0 / 2015-04-12
==================

  * add option "case"
  * add option "thousandsSeparator"
  * return "null" on invalid parse input
  * support proper round-trip: bytes(bytes(num)) === num
  * units no longer case sensitive when parsing

1.0.0 / 2014-05-05
==================

 * add negative support. fixes #6

0.3.0 / 2014-03-19
==================

 * added terabyte support

0.2.1 / 2013-04-01
==================

  * add .component

0.2.0 / 2012-10-28
==================

  * bytes(200).should.eql('200b')

0.1.0 / 2012-07-04
==================

  * add bytes to string conversion [yields]


---

# Bytes utility

[![NPM Version][npm-image]][npm-url]
[![NPM Downloads][downloads-image]][downloads-url]
[![Build Status][ci-image]][ci-url]
[![Test Coverage][coveralls-image]][coveralls-url]

Utility to parse a string bytes (ex: `1TB`) to bytes (`1099511627776`) and vice-versa.

## Installation

This is a [Node.js](https://nodejs.org/en/) module available through the
[npm registry](https://www.npmjs.com/). Installation is done using the
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):

```bash
$ npm install bytes
```

## Usage

```js
var bytes = require('bytes');
```

#### bytes(number｜string value, [options]): number｜string｜null

Default export function. Delegates to either `bytes.format` or `bytes.parse` based on the type of `value`.

**Arguments**

| Name    | Type     | Description        |
|---------|----------|--------------------|
| value   | `number`｜`string` | Number value to format or string value to parse |
| options | `Object` | Conversion options for `format` |

**Returns**

| Name    | Type             | Description                                     |
|---------|------------------|-------------------------------------------------|
| results | `string`｜`number`｜`null` | Return null upon error. Numeric value in bytes, or string value otherwise. |

**Example**

```js
bytes(1024);
// output: '1KB'

bytes('1KB');
// output: 1024
```

#### bytes.format(number value, [options]): string｜null

Format the given value in bytes into a string. If the value is negative, it is kept as such. If it is a float, it is
 rounded.

**Arguments**

| Name    | Type     | Description        |
|---------|----------|--------------------|
| value   | `number` | Value in bytes     |
| options | `Object` | Conversion options |

**Options**

| Property          | Type   | Description                                                                             |
|-------------------|--------|-----------------------------------------------------------------------------------------|
| decimalPlaces | `number`｜`null` | Maximum number of decimal places to include in output. Default value to `2`. |
| fixedDecimals | `boolean`｜`null` | Whether to always display the maximum number of decimal places. Default value to `false` |
| thousandsSeparator | `string`｜`null` | Example of values: `' '`, `','` and `'.'`... Default value to `''`. |
| unit | `string`｜`null` | The unit in which the result will be returned (B/KB/MB/GB/TB). Default value to `''` (which means auto detect). |
| unitSeparator | `string`｜`null` | Separator to use between number and unit. Default value to `''`. |

**Returns**

| Name    | Type             | Description                                     |
|---------|------------------|-------------------------------------------------|
| results | `string`｜`null` | Return null upon error. String value otherwise. |

**Example**

```js
bytes.format(1024);
// output: '1KB'

bytes.format(1000);
// output: '1000B'

bytes.format(1000, {thousandsSeparator: ' '});
// output: '1 000B'

bytes.format(1024 * 1.7, {decimalPlaces: 0});
// output: '2KB'

bytes.format(1024, {unitSeparator: ' '});
// output: '1 KB'
```

#### bytes.parse(string｜number value): number｜null

Parse the string value into an integer in bytes. If no unit is given, or `value`
is a number, it is assumed the value is in bytes.

Supported units and abbreviations are as follows and are case-insensitive:

  * `b` for bytes
  * `kb` for kilobytes
  * `mb` for megabytes
  * `gb` for gigabytes
  * `tb` for terabytes
  * `pb` for petabytes

The units are in powers of two, not ten. This means 1kb = 1024b according to this parser.

**Arguments**

| Name          | Type   | Description        |
|---------------|--------|--------------------|
| value   | `string`｜`number` | String to parse, or number in bytes.   |

**Returns**

| Name    | Type        | Description             |
|---------|-------------|-------------------------|
| results | `number`｜`null` | Return null upon error. Value in bytes otherwise. |

**Example**

```js
bytes.parse('1KB');
// output: 1024

bytes.parse('1024');
// output: 1024

bytes.parse(1024);
// output: 1024
```

## License

[MIT](LICENSE)

[ci-image]: https://badgen.net/github/checks/visionmedia/bytes.js/master?label=ci
[ci-url]: https://github.com/visionmedia/bytes.js/actions?query=workflow%3Aci
[coveralls-image]: https://badgen.net/coveralls/c/github/visionmedia/bytes.js/master
[coveralls-url]: https://coveralls.io/r/visionmedia/bytes.js?branch=master
[downloads-image]: https://badgen.net/npm/dm/bytes
[downloads-url]: https://npmjs.org/package/bytes
[npm-image]: https://badgen.net/npm/v/bytes
[npm-url]: https://npmjs.org/package/bytes


---

# rc

The non-configurable configuration loader for lazy people.

## Usage

The only option is to pass rc the name of your app, and your default configuration.

```javascript
var conf = require('rc')(appname, {
  //defaults go here.
  port: 2468,

  //defaults which are objects will be merged, not replaced
  views: {
    engine: 'jade'
  }
});
```

`rc` will return your configuration options merged with the defaults you specify.
If you pass in a predefined defaults object, it will be mutated:

```javascript
var conf = {};
require('rc')(appname, conf);
```

If `rc` finds any config files for your app, the returned config object will have
a `configs` array containing their paths:

```javascript
var appCfg = require('rc')(appname, conf);
appCfg.configs[0] // /etc/appnamerc
appCfg.configs[1] // /home/dominictarr/.config/appname
appCfg.config // same as appCfg.configs[appCfg.configs.length - 1]
```

## Standards

Given your application name (`appname`), rc will look in all the obvious places for configuration.

  * command line arguments, parsed by minimist _(e.g. `--foo baz`, also nested: `--foo.bar=baz`)_
  * environment variables prefixed with `${appname}_`
    * or use "\_\_" to indicate nested properties <br/> _(e.g. `appname_foo__bar__baz` => `foo.bar.baz`)_
  * if you passed an option `--config file` then from that file
  * a local `.${appname}rc` or the first found looking in `./ ../ ../../ ../../../` etc.
  * `$HOME/.${appname}rc`
  * `$HOME/.${appname}/config`
  * `$HOME/.config/${appname}`
  * `$HOME/.config/${appname}/config`
  * `/etc/${appname}rc`
  * `/etc/${appname}/config`
  * the defaults object you passed in.

All configuration sources that were found will be flattened into one object,
so that sources **earlier** in this list override later ones.


## Configuration File Formats

Configuration files (e.g. `.appnamerc`) may be in either [json](http://json.org/example) or [ini](http://en.wikipedia.org/wiki/INI_file) format. **No** file extension (`.json` or `.ini`) should be used. The example configurations below are equivalent:


#### Formatted as `ini`

```
; You can include comments in `ini` format if you want.

dependsOn=0.10.0


; `rc` has built-in support for ini sections, see?

[commands]
  www     = ./commands/www
  console = ./commands/repl


; You can even do nested sections

[generators.options]
  engine  = ejs

[generators.modules]
  new     = generate-new
  engine  = generate-backend

```

#### Formatted as `json`

```javascript
{
  // You can even comment your JSON, if you want
  "dependsOn": "0.10.0",
  "commands": {
    "www": "./commands/www",
    "console": "./commands/repl"
  },
  "generators": {
    "options": {
      "engine": "ejs"
    },
    "modules": {
      "new": "generate-new",
      "backend": "generate-backend"
    }
  }
}
```

Comments are stripped from JSON config via [strip-json-comments](https://github.com/sindresorhus/strip-json-comments).

> Since ini, and env variables do not have a standard for types, your application needs be prepared for strings.

To ensure that string representations of booleans and numbers are always converted into their proper types (especially useful if you intend to do strict `===` comparisons), consider using a module such as [parse-strings-in-object](https://github.com/anselanza/parse-strings-in-object) to wrap the config object returned from rc.


## Simple example demonstrating precedence
Assume you have an application like this (notice the hard-coded defaults passed to rc):
```
const conf = require('rc')('myapp', {
    port: 12345,
    mode: 'test'
});

console.log(JSON.stringify(conf, null, 2));
```
You also have a file `config.json`, with these contents:
```
{
  "port": 9000,
  "foo": "from config json",
  "something": "else"
}
```
And a file `.myapprc` in the same folder, with these contents:
```
{
  "port": "3001",
  "foo": "bar"
}
```
Here is the expected output from various commands:

`node .`
```
{
  "port": "3001",
  "mode": "test",
  "foo": "bar",
  "_": [],
  "configs": [
    "/Users/stephen/repos/conftest/.myapprc"
  ],
  "config": "/Users/stephen/repos/conftest/.myapprc"
}
```
*Default `mode` from hard-coded object is retained, but port is overridden by `.myapprc` file (automatically found based on appname match), and `foo` is added.*


`node . --foo baz`
```
{
  "port": "3001",
  "mode": "test",
  "foo": "baz",
  "_": [],
  "configs": [
    "/Users/stephen/repos/conftest/.myapprc"
  ],
  "config": "/Users/stephen/repos/conftest/.myapprc"
}
```
*Same result as above but `foo` is overridden because command-line arguments take precedence over `.myapprc` file.*

`node . --foo barbar --config config.json`
```
{
  "port": 9000,
  "mode": "test",
  "foo": "barbar",
  "something": "else",
  "_": [],
  "config": "config.json",
  "configs": [
    "/Users/stephen/repos/conftest/.myapprc",
    "config.json"
  ]
}
```
*Now the `port` comes from the `config.json` file specified (overriding the value from `.myapprc`), and `foo` value is overriden by command-line despite also being specified in the `config.json` file.*
 


## Advanced Usage

#### Pass in your own `argv`

You may pass in your own `argv` as the third argument to `rc`.  This is in case you want to [use your own command-line opts parser](https://github.com/dominictarr/rc/pull/12).

```javascript
require('rc')(appname, defaults, customArgvParser);
```

## Pass in your own parser

If you have a special need to use a non-standard parser,
you can do so by passing in the parser as the 4th argument.
(leave the 3rd as null to get the default args parser)

```javascript
require('rc')(appname, defaults, null, parser);
```

This may also be used to force a more strict format,
such as strict, valid JSON only.

## Note on Performance

`rc` is running `fs.statSync`-- so make sure you don't use it in a hot code path (e.g. a request handler) 


## License

Multi-licensed under the two-clause BSD License, MIT License, or Apache License, version 2.0


---

# strip-json-comments [![Build Status](https://travis-ci.org/sindresorhus/strip-json-comments.svg?branch=master)](https://travis-ci.org/sindresorhus/strip-json-comments)

> Strip comments from JSON. Lets you use comments in your JSON files!

This is now possible:

```js
{
	// rainbows
	"unicorn": /* ❤ */ "cake"
}
```

It will replace single-line comments `//` and multi-line comments `/**/` with whitespace. This allows JSON error positions to remain as close as possible to the original source.

Also available as a [gulp](https://github.com/sindresorhus/gulp-strip-json-comments)/[grunt](https://github.com/sindresorhus/grunt-strip-json-comments)/[broccoli](https://github.com/sindresorhus/broccoli-strip-json-comments) plugin.


## Install

```
$ npm install --save strip-json-comments
```


## Usage

```js
const json = '{/*rainbows*/"unicorn":"cake"}';

JSON.parse(stripJsonComments(json));
//=> {unicorn: 'cake'}
```


## API

### stripJsonComments(input, [options])

#### input

Type: `string`

Accepts a string with JSON and returns a string without comments.

#### options

##### whitespace

Type: `boolean`  
Default: `true`

Replace comments with whitespace instead of stripping them entirely.


## Related

- [strip-json-comments-cli](https://github.com/sindresorhus/strip-json-comments-cli) - CLI for this module
- [strip-css-comments](https://github.com/sindresorhus/strip-css-comments) - Strip comments from CSS


## License

MIT © [Sindre Sorhus](http://sindresorhus.com)


---

# `react`

React is a JavaScript library for creating user interfaces.

The `react` package contains only the functionality necessary to define React components. It is typically used together with a React renderer like `react-dom` for the web, or `react-native` for the native environments.

**Note:** by default, React will be in development mode. The development version includes extra warnings about common mistakes, whereas the production version includes extra performance optimizations and strips all error messages. Don't forget to use the [production build](https://reactjs.org/docs/optimizing-performance.html#use-the-production-build) when deploying your application.

## Usage

```js
import { useState } from 'react';
import { createRoot } from 'react-dom/client';

function Counter() {
  const [count, setCount] = useState(0);
  return (
    <>
      <h1>{count}</h1>
      <button onClick={() => setCount(count + 1)}>
        Increment
      </button>
    </>
  );
}

const root = createRoot(document.getElementById('root'));
root.render(<Counter />);
```

## Documentation

See https://react.dev/

## API

See https://react.dev/reference/react


---

# react-dev-utils

This package includes some utilities used by [Create React App](https://github.com/facebook/create-react-app).<br>
Please refer to its documentation:

- [Getting Started](https://facebook.github.io/create-react-app/docs/getting-started) – How to create a new app.
- [User Guide](https://facebook.github.io/create-react-app/) – How to develop apps bootstrapped with Create React App.

## Usage in Create React App Projects

These utilities come by default with [Create React App](https://github.com/facebook/create-react-app). **You don’t need to install it separately in Create React App projects.**

## Usage Outside of Create React App

If you don’t use Create React App, or if you [ejected](https://facebook.github.io/create-react-app/docs/available-scripts#npm-run-eject), you may keep using these utilities. Their development will be aligned with Create React App, so major versions of these utilities may come out relatively often. Feel free to fork or copy and paste them into your projects if you’d like to have more control over them, or feel free to use the old versions. Not all of them are React-specific, but we might make some of them more React-specific in the future.

### Entry Points

There is no single entry point. You can only import individual top-level modules.

#### `new InterpolateHtmlPlugin(htmlWebpackPlugin: HtmlWebpackPlugin, replacements: {[key:string]: string})`

This webpack plugin lets us interpolate custom variables into `index.html`.<br>
It works in tandem with [HtmlWebpackPlugin](https://github.com/ampedandwired/html-webpack-plugin) 2.x via its [events](https://github.com/ampedandwired/html-webpack-plugin#events).

```js
var path = require('path');
var HtmlWebpackPlugin = require('html-webpack-plugin');
var InterpolateHtmlPlugin = require('react-dev-utils/InterpolateHtmlPlugin');

// webpack config
var publicUrl = '/my-custom-url';

module.exports = {
  output: {
    // ...
    publicPath: publicUrl + '/',
  },
  // ...
  plugins: [
    // Generates an `index.html` file with the <script> injected.
    new HtmlWebpackPlugin({
      inject: true,
      template: path.resolve('public/index.html'),
    }),
    // Makes the public URL available as %PUBLIC_URL% in index.html, e.g.:
    // <link rel="icon" href="%PUBLIC_URL%/favicon.ico">
    new InterpolateHtmlPlugin(HtmlWebpackPlugin, {
      PUBLIC_URL: publicUrl,
      // You can pass any key-value pairs, this was just an example.
      // WHATEVER: 42 will replace %WHATEVER% with 42 in index.html.
    }),
    // ...
  ],
  // ...
};
```

#### `new InlineChunkHtmlPlugin(htmlWebpackPlugin: HtmlWebpackPlugin, tests: Regex[])`

This webpack plugin inlines script chunks into `index.html`.<br>
It works in tandem with [HtmlWebpackPlugin](https://github.com/ampedandwired/html-webpack-plugin) 4.x.

```js
var path = require('path');
var HtmlWebpackPlugin = require('html-webpack-plugin');
var InlineChunkHtmlPlugin = require('react-dev-utils/InlineChunkHtmlPlugin');

// webpack config
var publicUrl = '/my-custom-url';

module.exports = {
  output: {
    // ...
    publicPath: publicUrl + '/',
  },
  // ...
  plugins: [
    // Generates an `index.html` file with the <script> injected.
    new HtmlWebpackPlugin({
      inject: true,
      template: path.resolve('public/index.html'),
    }),
    // Inlines chunks with `runtime` in the name
    new InlineChunkHtmlPlugin(HtmlWebpackPlugin, [/runtime/]),
    // ...
  ],
  // ...
};
```

#### `new ModuleScopePlugin(appSrc: string | string[], allowedFiles?: string[])`

This webpack plugin ensures that relative imports from app's source directories don't reach outside of it.

```js
var path = require('path');
var ModuleScopePlugin = require('react-dev-utils/ModuleScopePlugin');

module.exports = {
  // ...
  resolve: {
    // ...
    plugins: [
      new ModuleScopePlugin(paths.appSrc, [paths.appPackageJson]),
      // ...
    ],
    // ...
  },
  // ...
};
```

#### `checkRequiredFiles(files: Array<string>): boolean`

Makes sure that all passed files exist.<br>
Filenames are expected to be absolute.<br>
If a file is not found, prints a warning message and returns `false`.

```js
var path = require('path');
var checkRequiredFiles = require('react-dev-utils/checkRequiredFiles');

if (
  !checkRequiredFiles([
    path.resolve('public/index.html'),
    path.resolve('src/index.js'),
  ])
) {
  process.exit(1);
}
```

#### `clearConsole(): void`

Clears the console, hopefully in a cross-platform way.

```js
var clearConsole = require('react-dev-utils/clearConsole');

clearConsole();
console.log('Just cleared the screen!');
```

#### `eslintFormatter(results: Object): string`

This is our custom ESLint formatter that integrates well with Create React App console output.<br>
You can use the default one instead if you prefer so.

```js
const eslintFormatter = require('react-dev-utils/eslintFormatter');

// In your webpack config:
// ...
module: {
  rules: [
    {
      test: /\.(js|jsx)$/,
      include: paths.appSrc,
      enforce: 'pre',
      use: [
        {
          loader: 'eslint-loader',
          options: {
            // Pass the formatter:
            formatter: eslintFormatter,
          },
        },
      ],
    },
  ];
}
```

#### `FileSizeReporter`

##### `measureFileSizesBeforeBuild(buildFolder: string): Promise<OpaqueFileSizes>`

Captures JS and CSS asset sizes inside the passed `buildFolder`. Save the result value to compare it after the build.

##### `printFileSizesAfterBuild(webpackStats: WebpackStats, previousFileSizes: OpaqueFileSizes, buildFolder: string, maxBundleGzipSize?: number, maxChunkGzipSize?: number)`

Prints the JS and CSS asset sizes after the build, and includes a size comparison with `previousFileSizes` that were captured earlier using `measureFileSizesBeforeBuild()`. `maxBundleGzipSize` and `maxChunkGzipSizemay` may optionally be specified to display a warning when the main bundle or a chunk exceeds the specified size (in bytes).

```js
var {
  measureFileSizesBeforeBuild,
  printFileSizesAfterBuild,
} = require('react-dev-utils/FileSizeReporter');

measureFileSizesBeforeBuild(buildFolder).then(previousFileSizes => {
  return cleanAndRebuild().then(webpackStats => {
    printFileSizesAfterBuild(webpackStats, previousFileSizes, buildFolder);
  });
});
```

#### `formatWebpackMessages({errors: Array<string>, warnings: Array<string>}): {errors: Array<string>, warnings: Array<string>}`

Extracts and prettifies warning and error messages from webpack [stats](https://github.com/webpack/docs/wiki/node.js-api#stats) object.

```js
var webpack = require('webpack');
var config = require('../config/webpack.config.dev');
var formatWebpackMessages = require('react-dev-utils/formatWebpackMessages');

var compiler = webpack(config);

compiler.hooks.invalid.tap('invalid', function () {
  console.log('Compiling...');
});

compiler.hooks.done.tap('done', function (stats) {
  var rawMessages = stats.toJson({}, true);
  var messages = formatWebpackMessages(rawMessages);
  if (!messages.errors.length && !messages.warnings.length) {
    console.log('Compiled successfully!');
  }
  if (messages.errors.length) {
    console.log('Failed to compile.');
    messages.errors.forEach(e => console.log(e));
    return;
  }
  if (messages.warnings.length) {
    console.log('Compiled with warnings.');
    messages.warnings.forEach(w => console.log(w));
  }
});
```

#### `printBuildError(error: Object): void`

Prettify some known build errors.
Pass an Error object to log a prettified error message in the console.

```
  const printBuildError = require('react-dev-utils/printBuildError')
  try {
    build()
  } catch(e) {
    printBuildError(e) // logs prettified message
  }
```

#### `getProcessForPort(port: number): string`

Finds the currently running process on `port`.
Returns a string containing the name and directory, e.g.,

```
create-react-app
in /Users/developer/create-react-app
```

```js
var getProcessForPort = require('react-dev-utils/getProcessForPort');

getProcessForPort(3000);
```

#### `launchEditor(fileName: string, lineNumber: number): void`

On macOS, tries to find a known running editor process and opens the file in it. It can also be explicitly configured by `REACT_EDITOR`, `VISUAL`, or `EDITOR` environment variables. For example, you can put `REACT_EDITOR=atom` in your `.env.local` file, and Create React App will respect that.

#### `noopServiceWorkerMiddleware(servedPath: string): ExpressMiddleware`

Returns Express middleware that serves a `${servedPath}/service-worker.js` that resets any previously set service worker configuration. Useful for development.

#### `redirectServedPathMiddleware(servedPath: string): ExpressMiddleware`

Returns Express middleware that redirects to `${servedPath}/${req.path}`, if `req.url`
does not start with `servedPath`. Useful for development.

#### `openBrowser(url: string): boolean`

Attempts to open the browser with a given URL.<br>
On Mac OS X, attempts to reuse an existing Chrome tab via AppleScript.<br>
Otherwise, falls back to [opn](https://github.com/sindresorhus/opn) behavior.

```js
var path = require('path');
var openBrowser = require('react-dev-utils/openBrowser');

if (openBrowser('http://localhost:3000')) {
  console.log('The browser tab has been opened!');
}
```

#### `printHostingInstructions(appPackage: Object, publicUrl: string, publicPath: string, buildFolder: string, useYarn: boolean): void`

Prints hosting instructions after the project is built.

Pass your parsed `package.json` object as `appPackage`, your URL where you plan to host the app as `publicUrl`, `output.publicPath` from your webpack configuration as `publicPath`, the `buildFolder` name, and whether to `useYarn` in instructions.

```js
const appPackage = require(paths.appPackageJson);
const publicUrl = paths.publicUrlOrPath;
const publicPath = config.output.publicPath;
printHostingInstructions(appPackage, publicUrl, publicPath, 'build', true);
```

#### `WebpackDevServerUtils`

##### `choosePort(host: string, defaultPort: number): Promise<number | null>`

Returns a Promise resolving to either `defaultPort` or next available port if the user confirms it is okay to do. If the port is taken and the user has refused to use another port, or if the terminal is not interactive and can’t present user with the choice, resolves to `null`.

##### `createCompiler(args: Object): WebpackCompiler`

Creates a webpack compiler instance for WebpackDevServer with built-in helpful messages.

The `args` object accepts a number of properties:

- **appName** `string`: The name that will be printed to the terminal.
- **config** `Object`: The webpack configuration options to be provided to the webpack constructor.
- **urls** `Object`: To provide the `urls` argument, use `prepareUrls()` described below.
- **useYarn** `boolean`: If `true`, yarn instructions will be emitted in the terminal instead of npm.
- **useTypeScript** `boolean`: If `true`, TypeScript type checking will be enabled. Be sure to provide the `devSocket` argument above if this is set to `true`.
- **webpack** `function`: A reference to the webpack constructor.

##### `prepareProxy(proxySetting: string, appPublicFolder: string, servedPathname: string): Object`

Creates a WebpackDevServer `proxy` configuration object from the `proxy` setting in `package.json`.

##### `prepareUrls(protocol: string, host: string, port: number, pathname: string = '/'): Object`

Returns an object with local and remote URLs for the development server. Pass this object to `createCompiler()` described above.

#### `webpackHotDevClient`

This is an alternative client for [WebpackDevServer](https://github.com/webpack/webpack-dev-server) that shows a syntax error overlay.

It currently supports only webpack 3.x.

```js
// webpack development config
module.exports = {
  // ...
  entry: [
    // You can replace the line below with these two lines if you prefer the
    // stock client:
    // require.resolve('webpack-dev-server/client') + '?/',
    // require.resolve('webpack/hot/dev-server'),
    'react-dev-utils/webpackHotDevClient',
    'src/index',
  ],
  // ...
};
```

#### `getCSSModuleLocalIdent(context: Object, localIdentName: String, localName: String, options: Object): string`

Creates a class name for CSS Modules that uses either the filename or folder name if named `index.module.css`.

For `MyFolder/MyComponent.module.css` and class `MyClass` the output will be `MyComponent.module_MyClass__[hash]`
For `MyFolder/index.module.css` and class `MyClass` the output will be `MyFolder_MyClass__[hash]`

```js
const getCSSModuleLocalIdent = require('react-dev-utils/getCSSModuleLocalIdent');

// In your webpack config:
// ...
module: {
  rules: [
    {
      test: /\.module\.css$/,
      use: [
        require.resolve('style-loader'),
        {
          loader: require.resolve('css-loader'),
          options: {
            importLoaders: 1,
            modules: {
              getLocalIdent: getCSSModuleLocalIdent,
            },
          },
        },
        {
          loader: require.resolve('postcss-loader'),
          options: postCSSLoaderOptions,
        },
      ],
    },
  ];
}
```

#### `getCacheIdentifier(environment: string, packages: string[]): string`

Returns a cache identifier (string) consisting of the specified environment and related package versions, e.g.,

```js
var getCacheIdentifier = require('react-dev-utils/getCacheIdentifier');

getCacheIdentifier('prod', ['react-dev-utils', 'chalk']); // # => 'prod:react-dev-utils@5.0.0:chalk@3.0.0'
```


---

# find-up [![Build Status](https://travis-ci.com/sindresorhus/find-up.svg?branch=master)](https://travis-ci.com/github/sindresorhus/find-up)

> Find a file or directory by walking up parent directories

## Install

```
$ npm install find-up
```

## Usage

```
/
└── Users
    └── sindresorhus
        ├── unicorn.png
        └── foo
            └── bar
                ├── baz
                └── example.js
```

`example.js`

```js
const path = require('path');
const findUp = require('find-up');

(async () => {
	console.log(await findUp('unicorn.png'));
	//=> '/Users/sindresorhus/unicorn.png'

	console.log(await findUp(['rainbow.png', 'unicorn.png']));
	//=> '/Users/sindresorhus/unicorn.png'

	console.log(await findUp(async directory => {
		const hasUnicorns = await findUp.exists(path.join(directory, 'unicorn.png'));
		return hasUnicorns && directory;
	}, {type: 'directory'}));
	//=> '/Users/sindresorhus'
})();
```

## API

### findUp(name, options?)
### findUp(matcher, options?)

Returns a `Promise` for either the path or `undefined` if it couldn't be found.

### findUp([...name], options?)

Returns a `Promise` for either the first path found (by respecting the order of the array) or `undefined` if none could be found.

### findUp.sync(name, options?)
### findUp.sync(matcher, options?)

Returns a path or `undefined` if it couldn't be found.

### findUp.sync([...name], options?)

Returns the first path found (by respecting the order of the array) or `undefined` if none could be found.

#### name

Type: `string`

Name of the file or directory to find.

#### matcher

Type: `Function`

A function that will be called with each directory until it returns a `string` with the path, which stops the search, or the root directory has been reached and nothing was found. Useful if you want to match files with certain patterns, set of permissions, or other advanced use-cases.

When using async mode, the `matcher` may optionally be an async or promise-returning function that returns the path.

#### options

Type: `object`

##### cwd

Type: `string`\
Default: `process.cwd()`

Directory to start from.

##### type

Type: `string`\
Default: `'file'`\
Values: `'file'` `'directory'`

The type of paths that can match.

##### allowSymlinks

Type: `boolean`\
Default: `true`

Allow symbolic links to match if they point to the chosen path type.

### findUp.exists(path)

Returns a `Promise<boolean>` of whether the path exists.

### findUp.sync.exists(path)

Returns a `boolean` of whether the path exists.

#### path

Type: `string`

Path to a file or directory.

### findUp.stop

A [`Symbol`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol) that can be returned by a `matcher` function to stop the search and cause `findUp` to immediately return `undefined`. Useful as a performance optimization in case the current working directory is deeply nested in the filesystem.

```js
const path = require('path');
const findUp = require('find-up');

(async () => {
	await findUp(directory => {
		return path.basename(directory) === 'work' ? findUp.stop : 'logo.png';
	});
})();
```

## Related

- [find-up-cli](https://github.com/sindresorhus/find-up-cli) - CLI for this module
- [pkg-up](https://github.com/sindresorhus/pkg-up) - Find the closest package.json file
- [pkg-dir](https://github.com/sindresorhus/pkg-dir) - Find the root directory of an npm package
- [resolve-from](https://github.com/sindresorhus/resolve-from) - Resolve the path of a module like `require.resolve()` but from a given path

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-find-up?utm_source=npm-find-up&utm_medium=referral&utm_campaign=readme">Get professional support for 'find-up' with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

# loader-utils

## Methods

### `urlToRequest`

Converts some resource URL to a webpack module request.

> i Before call `urlToRequest` you need call `isUrlRequest` to ensure it is requestable url

```javascript
const url = "path/to/module.js";

if (loaderUtils.isUrlRequest(url)) {
  // Logic for requestable url
  const request = loaderUtils.urlToRequest(url);
} else {
  // Logic for not requestable url
}
```

Simple example:

```javascript
const url = "path/to/module.js";
const request = loaderUtils.urlToRequest(url); // "./path/to/module.js"
```

#### Module URLs

Any URL containing a `~` will be interpreted as a module request. Anything after the `~` will be considered the request path.

```javascript
const url = "~path/to/module.js";
const request = loaderUtils.urlToRequest(url); // "path/to/module.js"
```

#### Root-relative URLs

URLs that are root-relative (start with `/`) can be resolved relative to some arbitrary path by using the `root` parameter:

```javascript
const url = "/path/to/module.js";
const root = "./root";
const request = loaderUtils.urlToRequest(url, root); // "./root/path/to/module.js"
```

To convert a root-relative URL into a module URL, specify a `root` value that starts with `~`:

```javascript
const url = "/path/to/module.js";
const root = "~";
const request = loaderUtils.urlToRequest(url, root); // "path/to/module.js"
```

### `interpolateName`

Interpolates a filename template using multiple placeholders and/or a regular expression.
The template and regular expression are set as query params called `name` and `regExp` on the current loader's context.

```javascript
const interpolatedName = loaderUtils.interpolateName(
  loaderContext,
  name,
  options
);
```

The following tokens are replaced in the `name` parameter:

- `[ext]` the extension of the resource
- `[name]` the basename of the resource
- `[path]` the path of the resource relative to the `context` query parameter or option.
- `[folder]` the folder the resource is in
- `[query]` the queryof the resource, i.e. `?foo=bar`
- `[contenthash]` the hash of `options.content` (Buffer) (by default it's the hex digest of the `xxhash64` hash)
- `[<hashType>:contenthash:<digestType>:<length>]` optionally one can configure
  - other `hashType`s, i. e. `xxhash64`, `sha1`, `md4` (wasm version), `native-md4` (`crypto` module version), `md5`, `sha256`, `sha512`
  - other `digestType`s, i. e. `hex`, `base26`, `base32`, `base36`, `base49`, `base52`, `base58`, `base62`, `base64`, `base64safe`
  - and `length` the length in chars
- `[hash]` the hash of `options.content` (Buffer) (by default it's the hex digest of the `xxhash64` hash)
- `[<hashType>:hash:<digestType>:<length>]` optionally one can configure
  - other `hashType`s, i. e. `xxhash64`, `sha1`, `md4` (wasm version), `native-md4` (`crypto` module version), `md5`, `sha256`, `sha512`
  - other `digestType`s, i. e. `hex`, `base26`, `base32`, `base36`, `base49`, `base52`, `base58`, `base62`, `base64`, `base64safe`
  - and `length` the length in chars
- `[N]` the N-th match obtained from matching the current file name against `options.regExp`

In loader context `[hash]` and `[contenthash]` are the same, but we recommend using `[contenthash]` for avoid misleading.

`digestType` with `base64safe` don't contain `/`, `+` and `=` symbols.

Examples

```javascript
// loaderContext.resourcePath = "/absolute/path/to/app/js/javascript.js"
loaderUtils.interpolateName(loaderContext, "js/[hash].script.[ext]", { content: ... });
// => js/9473fdd0d880a43c21b7778d34872157.script.js

// loaderContext.resourcePath = "/absolute/path/to/app/js/javascript.js"
// loaderContext.resourceQuery = "?foo=bar"
loaderUtils.interpolateName(loaderContext, "js/[hash].script.[ext][query]", { content: ... });
// => js/9473fdd0d880a43c21b7778d34872157.script.js?foo=bar

// loaderContext.resourcePath = "/absolute/path/to/app/js/javascript.js"
loaderUtils.interpolateName(loaderContext, "js/[contenthash].script.[ext]", { content: ... });
// => js/9473fdd0d880a43c21b7778d34872157.script.js

// loaderContext.resourcePath = "/absolute/path/to/app/page.html"
loaderUtils.interpolateName(loaderContext, "html-[hash:6].html", { content: ... });
// => html-9473fd.html

// loaderContext.resourcePath = "/absolute/path/to/app/flash.txt"
loaderUtils.interpolateName(loaderContext, "[hash]", { content: ... });
// => c31e9820c001c9c4a86bce33ce43b679

// loaderContext.resourcePath = "/absolute/path/to/app/img/image.png"
loaderUtils.interpolateName(loaderContext, "[sha512:hash:base64:7].[ext]", { content: ... });
// => 2BKDTjl.png
// use sha512 hash instead of xxhash64 and with only 7 chars of base64

// loaderContext.resourcePath = "/absolute/path/to/app/img/myself.png"
// loaderContext.query.name =
loaderUtils.interpolateName(loaderContext, "picture.png");
// => picture.png

// loaderContext.resourcePath = "/absolute/path/to/app/dir/file.png"
loaderUtils.interpolateName(loaderContext, "[path][name].[ext]?[hash]", { content: ... });
// => /app/dir/file.png?9473fdd0d880a43c21b7778d34872157

// loaderContext.resourcePath = "/absolute/path/to/app/js/page-home.js"
loaderUtils.interpolateName(loaderContext, "script-[1].[ext]", { regExp: "page-(.*)\\.js", content: ... });
// => script-home.js

// loaderContext.resourcePath = "/absolute/path/to/app/js/javascript.js"
// loaderContext.resourceQuery = "?foo=bar"
loaderUtils.interpolateName(
  loaderContext,
  (resourcePath, resourceQuery) => {
    // resourcePath - `/app/js/javascript.js`
    // resourceQuery - `?foo=bar`

    return "js/[hash].script.[ext]";
  },
  { content: ... }
);
// => js/9473fdd0d880a43c21b7778d34872157.script.js
```

### `getHashDigest`

```javascript
const digestString = loaderUtils.getHashDigest(
  buffer,
  hashType,
  digestType,
  maxLength
);
```

- `buffer` the content that should be hashed
- `hashType` one of `xxhash64`, `sha1`, `md4`, `md5`, `sha256`, `sha512` or any other node.js supported hash type
- `digestType` one of `hex`, `base26`, `base32`, `base36`, `base49`, `base52`, `base58`, `base62`, `base64`, `base64safe`
- `maxLength` the maximum length in chars

## License

MIT (http://www.opensource.org/licenses/mit-license.php)


---

# locate-path [![Build Status](https://travis-ci.com/sindresorhus/locate-path.svg?branch=master)](https://travis-ci.com/github/sindresorhus/locate-path)

> Get the first path that exists on disk of multiple paths

## Install

```
$ npm install locate-path
```

## Usage

Here we find the first file that exists on disk, in array order.

```js
const locatePath = require('locate-path');

const files = [
	'unicorn.png',
	'rainbow.png', // Only this one actually exists on disk
	'pony.png'
];

(async () => {
	console(await locatePath(files));
	//=> 'rainbow'
})();
```

## API

### locatePath(paths, options?)

Returns a `Promise<string>` for the first path that exists or `undefined` if none exists.

#### paths

Type: `Iterable<string>`

Paths to check.

#### options

Type: `object`

##### concurrency

Type: `number`\
Default: `Infinity`\
Minimum: `1`

Number of concurrently pending promises.

##### preserveOrder

Type: `boolean`\
Default: `true`

Preserve `paths` order when searching.

Disable this to improve performance if you don't care about the order.

##### cwd

Type: `string`\
Default: `process.cwd()`

Current working directory.

##### type

Type: `string`\
Default: `'file'`\
Values: `'file' | 'directory'`

The type of paths that can match.

##### allowSymlinks

Type: `boolean`\
Default: `true`

Allow symbolic links to match if they point to the chosen path type.

### locatePath.sync(paths, options?)

Returns the first path that exists or `undefined` if none exists.

#### paths

Type: `Iterable<string>`

Paths to check.

#### options

Type: `object`

##### cwd

Same as above.

##### type

Same as above.

##### allowSymlinks

Same as above.

## Related

- [path-exists](https://github.com/sindresorhus/path-exists) - Check if a path exists

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-locate-path?utm_source=npm-locate-path&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

# p-limit

> Run multiple promise-returning & async functions with limited concurrency

## Install

```
$ npm install p-limit
```

## Usage

```js
const pLimit = require('p-limit');

const limit = pLimit(1);

const input = [
	limit(() => fetchSomething('foo')),
	limit(() => fetchSomething('bar')),
	limit(() => doSomething())
];

(async () => {
	// Only one promise is run at once
	const result = await Promise.all(input);
	console.log(result);
})();
```

## API

### pLimit(concurrency)

Returns a `limit` function.

#### concurrency

Type: `number`\
Minimum: `1`\
Default: `Infinity`

Concurrency limit.

### limit(fn, ...args)

Returns the promise returned by calling `fn(...args)`.

#### fn

Type: `Function`

Promise-returning/async function.

#### args

Any arguments to pass through to `fn`.

Support for passing arguments on to the `fn` is provided in order to be able to avoid creating unnecessary closures. You probably don't need this optimization unless you're pushing a *lot* of functions.

### limit.activeCount

The number of promises that are currently running.

### limit.pendingCount

The number of promises that are waiting to run (i.e. their internal `fn` was not called yet).

### limit.clearQueue()

Discard pending promises that are waiting to run.

This might be useful if you want to teardown the queue at the end of your program's lifecycle or discard any function calls referencing an intermediary state of your app.

Note: This does not cancel promises that are already running.

## FAQ

### How is this different from the [`p-queue`](https://github.com/sindresorhus/p-queue) package?

This package is only about limiting the number of concurrent executions, while `p-queue` is a fully featured queue implementation with lots of different options, introspection, and ability to pause the queue.

## Related

- [p-queue](https://github.com/sindresorhus/p-queue) - Promise queue with concurrency control
- [p-throttle](https://github.com/sindresorhus/p-throttle) - Throttle promise-returning & async functions
- [p-debounce](https://github.com/sindresorhus/p-debounce) - Debounce promise-returning & async functions
- [p-all](https://github.com/sindresorhus/p-all) - Run promise-returning & async functions concurrently with optional limited concurrency
- [More…](https://github.com/sindresorhus/promise-fun)

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-p-limit?utm_source=npm-p-limit&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

# p-locate [![Build Status](https://travis-ci.com/sindresorhus/p-locate.svg?branch=master)](https://travis-ci.com/github/sindresorhus/p-locate)

> Get the first fulfilled promise that satisfies the provided testing function

Think of it like an async version of [`Array#find`](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Array/find).

## Install

```
$ npm install p-locate
```

## Usage

Here we find the first file that exists on disk, in array order.

```js
const pathExists = require('path-exists');
const pLocate = require('p-locate');

const files = [
	'unicorn.png',
	'rainbow.png', // Only this one actually exists on disk
	'pony.png'
];

(async () => {
	const foundPath = await pLocate(files, file => pathExists(file));

	console.log(foundPath);
	//=> 'rainbow'
})();
```

*The above is just an example. Use [`locate-path`](https://github.com/sindresorhus/locate-path) if you need this.*

## API

### pLocate(input, tester, options?)

Returns a `Promise` that is fulfilled when `tester` resolves to `true` or the iterable is done, or rejects if any of the promises reject. The fulfilled value is the current iterable value or `undefined` if `tester` never resolved to `true`.

#### input

Type: `Iterable<Promise | unknown>`

An iterable of promises/values to test.

#### tester(element)

Type: `Function`

This function will receive resolved values from `input` and is expected to return a `Promise<boolean>` or `boolean`.

#### options

Type: `object`

##### concurrency

Type: `number`\
Default: `Infinity`\
Minimum: `1`

Number of concurrently pending promises returned by `tester`.

##### preserveOrder

Type: `boolean`\
Default: `true`

Preserve `input` order when searching.

Disable this to improve performance if you don't care about the order.

## Related

- [p-map](https://github.com/sindresorhus/p-map) - Map over promises concurrently
- [p-filter](https://github.com/sindresorhus/p-filter) - Filter promises concurrently
- [p-any](https://github.com/sindresorhus/p-any) - Wait for any promise to be fulfilled
- [More…](https://github.com/sindresorhus/promise-fun)

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-p-locate?utm_source=npm-p-locate&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

# path-exists [![Build Status](https://travis-ci.org/sindresorhus/path-exists.svg?branch=master)](https://travis-ci.org/sindresorhus/path-exists)

> Check if a path exists

NOTE: `fs.existsSync` has been un-deprecated in Node.js since 6.8.0. If you only need to check synchronously, this module is not needed.

While [`fs.exists()`](https://nodejs.org/api/fs.html#fs_fs_exists_path_callback) is being [deprecated](https://github.com/iojs/io.js/issues/103), there's still a genuine use-case of being able to check if a path exists for other purposes than doing IO with it.

Never use this before handling a file though:

> In particular, checking if a file exists before opening it is an anti-pattern that leaves you vulnerable to race conditions: another process may remove the file between the calls to `fs.exists()` and `fs.open()`. Just open the file and handle the error when it's not there.


## Install

```
$ npm install path-exists
```


## Usage

```js
// foo.js
const pathExists = require('path-exists');

(async () => {
	console.log(await pathExists('foo.js'));
	//=> true
})();
```


## API

### pathExists(path)

Returns a `Promise<boolean>` of whether the path exists.

### pathExists.sync(path)

Returns a `boolean` of whether the path exists.


## Related

- [path-exists-cli](https://github.com/sindresorhus/path-exists-cli) - CLI for this module


## License

MIT © [Sindre Sorhus](https://sindresorhus.com)


---

# yocto-queue [![](https://badgen.net/bundlephobia/minzip/yocto-queue)](https://bundlephobia.com/result?p=yocto-queue)

> Tiny queue data structure

You should use this package instead of an array if you do a lot of `Array#push()` and `Array#shift()` on large arrays, since `Array#shift()` has [linear time complexity](https://medium.com/@ariel.salem1989/an-easy-to-use-guide-to-big-o-time-complexity-5dcf4be8a444#:~:text=O(N)%E2%80%94Linear%20Time) *O(n)* while `Queue#dequeue()` has [constant time complexity](https://medium.com/@ariel.salem1989/an-easy-to-use-guide-to-big-o-time-complexity-5dcf4be8a444#:~:text=O(1)%20%E2%80%94%20Constant%20Time) *O(1)*. That makes a huge difference for large arrays.

> A [queue](https://en.wikipedia.org/wiki/Queue_(abstract_data_type)) is an ordered list of elements where an element is inserted at the end of the queue and is removed from the front of the queue. A queue works based on the first-in, first-out ([FIFO](https://en.wikipedia.org/wiki/FIFO_(computing_and_electronics))) principle.

## Install

```
$ npm install yocto-queue
```

## Usage

```js
const Queue = require('yocto-queue');

const queue = new Queue();

queue.enqueue('🦄');
queue.enqueue('🌈');

console.log(queue.size);
//=> 2

console.log(...queue);
//=> '🦄 🌈'

console.log(queue.dequeue());
//=> '🦄'

console.log(queue.dequeue());
//=> '🌈'
```

## API

### `queue = new Queue()`

The instance is an [`Iterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols), which means you can iterate over the queue front to back with a “for…of” loop, or use spreading to convert the queue to an array. Don't do this unless you really need to though, since it's slow.

#### `.enqueue(value)`

Add a value to the queue.

#### `.dequeue()`

Remove the next value in the queue.

Returns the removed value or `undefined` if the queue is empty.

#### `.clear()`

Clear the queue.

#### `.size`

The size of the queue.

## Related

- [quick-lru](https://github.com/sindresorhus/quick-lru) - Simple “Least Recently Used” (LRU) cache


---

# `react-dom`

This package serves as the entry point to the DOM and server renderers for React. It is intended to be paired with the generic React package, which is shipped as `react` to npm.

## Installation

```sh
npm install react react-dom
```

## Usage

### In the browser

```js
import { createRoot } from 'react-dom/client';

function App() {
  return <div>Hello World</div>;
}

const root = createRoot(document.getElementById('root'));
root.render(<App />);
```

### On the server

```js
import { renderToPipeableStream } from 'react-dom/server';

function App() {
  return <div>Hello World</div>;
}

function handleRequest(res) {
  // ... in your server handler ...
  const stream = renderToPipeableStream(<App />, {
    onShellReady() {
      res.statusCode = 200;
      res.setHeader('Content-type', 'text/html');
      stream.pipe(res);
    },
    // ...
  });
}
```

## API

### `react-dom`

See https://react.dev/reference/react-dom

### `react-dom/client`

See https://react.dev/reference/react-dom/client

### `react-dom/server`

See https://react.dev/reference/react-dom/server


---

# `react-error-overlay`

`react-error-overlay` is an overlay which displays when there is a runtime error.

## Development

When developing within this package, make sure you run `npm start` (or `yarn start`) so that the files are compiled as you work.
This is run in watch mode by default.

If you would like to build this for production, run `npm run build:prod` (or `yarn build:prod`).<br>
If you would like to build this one-off for development, you can run `NODE_ENV=development npm run build` (or `NODE_ENV=development yarn build`).


---

[![React Fast Compare — Formidable, We build the modern web](https://raw.githubusercontent.com/FormidableLabs/react-fast-compare/master/react-fast-compare-Hero.png)](https://formidable.com/open-source/)

[![Downloads][downloads_img]][npm_site]
[![Bundle Size][bundle_img]](#bundle-size)
[![GH Actions Status][actions_img]][actions_site]
[![Coverage Status][cov_img]][cov_site]
[![npm version][npm_img]][npm_site]
[![Maintenance Status][maintenance_img]](#maintenance-status)

The fastest deep equal comparison for React. Very quick general-purpose deep
comparison, too. Great for `React.memo` and `shouldComponentUpdate`.

This is a fork of the brilliant
[fast-deep-equal](https://github.com/epoberezkin/fast-deep-equal) with some
extra handling for React.

![benchmark chart](https://raw.githubusercontent.com/FormidableLabs/react-fast-compare/master/assets/benchmarking.png "benchmarking chart")

(Check out the [benchmarking details](#benchmarking-this-library).)

## Install

```sh
$ yarn add react-fast-compare
# or
$ npm install react-fast-compare
```

## Highlights

- ES5 compatible; works in node.js (0.10+) and browsers (IE9+)
- deeply compares any value (besides objects with circular references)
- handles React-specific circular references, like elements
- checks equality Date and RegExp objects
- should as fast as [fast-deep-equal](https://github.com/epoberezkin/fast-deep-equal) via a single unified library, and with added guardrails for circular references.
- small: under 660 bytes minified+gzipped

## Usage

```jsx
const isEqual = require("react-fast-compare");

// general usage
console.log(isEqual({ foo: "bar" }, { foo: "bar" })); // true

// React.memo
// only re-render ExpensiveComponent when the props have deeply changed
const DeepMemoComponent = React.memo(ExpensiveComponent, isEqual);

// React.Component shouldComponentUpdate
// only re-render AnotherExpensiveComponent when the props have deeply changed
class AnotherExpensiveComponent extends React.Component {
  shouldComponentUpdate(nextProps) {
    return !isEqual(this.props, nextProps);
  }
  render() {
    // ...
  }
}
```

## Do I Need `React.memo` (or `shouldComponentUpdate`)?

> What's faster than a really fast deep comparison? No deep comparison at all.

—This Readme

Deep checks in `React.memo` or a `shouldComponentUpdate` should not be used blindly.
First, see if the default
[React.memo](https://reactjs.org/docs/react-api.html#reactmemo) or
[PureComponent](https://reactjs.org/docs/react-api.html#reactpurecomponent)
will work for you. If it won't (if you need deep checks), it's wise to make
sure you've correctly indentified the bottleneck in your application by
[profiling the performance](https://reactjs.org/docs/optimizing-performance.html#profiling-components-with-the-chrome-performance-tab).
After you've determined that you _do_ need deep equality checks and you've
identified the minimum number of places to apply them, then this library may
be for you!

## Benchmarking this Library

The absolute values are much less important than the relative differences
between packages.

Benchmarking source can be found
[here](https://github.com/FormidableLabs/react-fast-compare/blob/master/benchmark/index.js).
Each "operation" consists of running all relevant tests. The React benchmark
uses both the generic tests and the react tests; these runs will be slower
simply because there are more tests in each operation.

The results below are from a local test on a laptop _(stats last updated 6/2/2020)_:

### Generic Data

```
react-fast-compare x 177,600 ops/sec ±1.73% (92 runs sampled)
fast-deep-equal x 184,211 ops/sec ±0.65% (87 runs sampled)
lodash.isEqual x 39,826 ops/sec ±1.32% (86 runs sampled)
nano-equal x 176,023 ops/sec ±0.89% (92 runs sampled)
shallow-equal-fuzzy x 146,355 ops/sec ±0.64% (89 runs sampled)
  fastest: fast-deep-equal
```

`react-fast-compare` and `fast-deep-equal` should be the same speed for these
tests; any difference is just noise. `react-fast-compare` won't be faster than
`fast-deep-equal`, because it's based on it.

### React and Generic Data

```
react-fast-compare x 86,392 ops/sec ±0.70% (93 runs sampled)
fast-deep-equal x 85,567 ops/sec ±0.95% (92 runs sampled)
lodash.isEqual x 7,369 ops/sec ±1.78% (84 runs sampled)
  fastest: react-fast-compare,fast-deep-equal
```

Two of these packages cannot handle comparing React elements, because they
contain circular reference: `nano-equal` and `shallow-equal-fuzzy`.

### Running Benchmarks

```sh
$ yarn install
$ yarn run benchmark
```

## Differences between this library and `fast-deep-equal`

`react-fast-compare` is based on `fast-deep-equal`, with some additions:

- `react-fast-compare` has `try`/`catch` guardrails for stack overflows from undetected (non-React) circular references.
- `react-fast-compare` has a _single_ unified entry point for all uses. No matter what your target application is, `import equal from 'react-fast-compare'` just works. `fast-deep-equal` has multiple entry points for different use cases.

This version of `react-fast-compare` tracks `fast-deep-equal@3.1.1`.

## Bundle Size

There are a variety of ways to calculate bundle size for JavaScript code.
You can see our size test code in the `compress` script in
[`package.json`](https://github.com/FormidableLabs/react-fast-compare/blob/master/package.json).
[Bundlephobia's calculation](https://bundlephobia.com/result?p=react-fast-compare) is slightly higher,
as they [do not mangle during minification](https://github.com/pastelsky/package-build-stats/blob/v6.1.1/src/getDependencySizeTree.js#L139).

## License

[MIT](https://github.com/FormidableLabs/react-fast-compare/blob/readme/LICENSE)

## Contributing

Please see our [contributions guide](./CONTRIBUTING.md).

## Maintenance Status

**Active:** Formidable is actively working on this project, and we expect to continue for work for the foreseeable future. Bug reports, feature requests and pull requests are welcome.

[actions_img]: https://github.com/FormidableLabs/react-fast-compare/actions/workflows/ci.yml/badge.svg
[actions_site]: https://github.com/formidablelabs/react-fast-compare/actions/workflows/ci.yml
[cov_img]: https://codecov.io/gh/FormidableLabs/react-fast-compare/branch/master/graph/badge.svg
[cov_site]: https://codecov.io/gh/FormidableLabs/react-fast-compare
[npm_img]: https://badge.fury.io/js/react-fast-compare.svg
[npm_site]: http://badge.fury.io/js/react-fast-compare
[appveyor_img]: https://ci.appveyor.com/api/projects/status/github/formidablelabs/react-fast-compare?branch=master&svg=true
[appveyor_site]: https://ci.appveyor.com/project/FormidableLabs/react-fast-compare
[bundle_img]: https://img.shields.io/badge/minzipped%20size-656%20B-flatgreen.svg
[downloads_img]: https://img.shields.io/npm/dm/react-fast-compare.svg
[maintenance_img]: https://img.shields.io/badge/maintenance-active-flatgreen.svg


---

# react-helmet-async

[![CircleCI](https://circleci.com/gh/staylor/react-helmet-async.svg?style=svg)](https://circleci.com/gh/staylor/react-helmet-async)

[Announcement post on Times Open blog](https://open.nytimes.com/the-future-of-meta-tag-management-for-modern-react-development-ec26a7dc9183)

This package is a fork of [React Helmet](https://github.com/nfl/react-helmet).
`<Helmet>` usage is synonymous, but server and client now requires `<HelmetProvider>` to encapsulate state per request.

`react-helmet` relies on `react-side-effect`, which is not thread-safe. If you are doing anything asynchronous on the server, you need Helmet to encapsulate data on a per-request basis, this package does just that.

## Usage

**New is 1.0.0:** No more default export! `import { Helmet } from 'react-helmet-async'`

The main way that this package differs from `react-helmet` is that it requires using a Provider to encapsulate Helmet state for your React tree. If you use libraries like Redux or Apollo, you are already familiar with this paradigm:

```javascript
import React from 'react';
import ReactDOM from 'react-dom';
import { Helmet, HelmetProvider } from 'react-helmet-async';

const app = (
  <HelmetProvider>
    <App>
      <Helmet>
        <title>Hello World</title>
        <link rel="canonical" href="https://www.tacobell.com/" />
      </Helmet>
      <h1>Hello World</h1>
    </App>
  </HelmetProvider>
);

ReactDOM.hydrate(
  app,
  document.getElementById(‘app’)
);
```

On the server, we will no longer use static methods to extract state. `react-side-effect`
exposed a `.rewind()` method, which Helmet used when calling `Helmet.renderStatic()`. Instead, we are going
to pass a `context` prop to `HelmetProvider`, which will hold our state specific to each request.

```javascript
import React from 'react';
import { renderToString } from 'react-dom/server';
import { Helmet, HelmetProvider } from 'react-helmet-async';

const helmetContext = {};

const app = (
  <HelmetProvider context={helmetContext}>
    <App>
      <Helmet>
        <title>Hello World</title>
        <link rel="canonical" href="https://www.tacobell.com/" />
      </Helmet>
      <h1>Hello World</h1>
    </App>
  </HelmetProvider>
);

const html = renderToString(app);

const { helmet } = helmetContext;

// helmet.title.toString() etc…
```

## Streams

This package only works with streaming if your `<head>` data is output outside of `renderToNodeStream()`.
This is possible if your data hydration method already parses your React tree. Example:

```javascript
import through from 'through';
import { renderToNodeStream } from 'react-dom/server';
import { getDataFromTree } from 'react-apollo';
import { Helmet, HelmetProvider } from 'react-helmet-async';
import template from 'server/template';

const helmetContext = {};

const app = (
  <HelmetProvider context={helmetContext}>
    <App>
      <Helmet>
        <title>Hello World</title>
        <link rel="canonical" href="https://www.tacobell.com/" />
      </Helmet>
      <h1>Hello World</h1>
    </App>
  </HelmetProvider>
);

await getDataFromTree(app);

const [header, footer] = template({
  helmet: helmetContext.helmet,
});

res.status(200);
res.write(header);
renderToNodeStream(app)
  .pipe(
    through(
      function write(data) {
        this.queue(data);
      },
      function end() {
        this.queue(footer);
        this.queue(null);
      }
    )
  )
  .pipe(res);
```

## Usage in Jest
While testing in using jest, if there is a need to emulate SSR, the following string is required to have the test behave the way they are expected to.

```javascript
import { HelmetProvider } from 'react-helmet-async';

HelmetProvider.canUseDOM = false;
```

## Prioritizing tags for SEO

It is understood that in some cases for SEO, certain tags should appear earlier in the HEAD. Using the `prioritizeSeoTags` flag on any `<Helmet>` component allows the server render of react-helmet-async to expose a method for prioritizing relevant SEO tags.

In the component:
```javascript
<Helmet prioritizeSeoTags>
  <title>A fancy webpage</title>
  <link rel="notImportant" href="https://www.chipotle.com" />
  <meta name="whatever" value="notImportant" />
  <link rel="canonical" href="https://www.tacobell.com" />
  <meta property="og:title" content="A very important title"/>
</Helmet>
```

In your server template:

```javascript
<html>
  <head>
    ${helmet.title.toString()}
    ${helmet.priority.toString()}
    ${helmet.meta.toString()}
    ${helmet.link.toString()}
    ${helmet.script.toString()}
  </head>
  ...
</html>
```

Will result in:

```html
<html>
  <head>
    <title>A fancy webpage</title>
    <meta property="og:title" content="A very important title"/>
    <link rel="canonical" href="https://www.tacobell.com" />
    <meta name="whatever" value="notImportant" />
    <link rel="notImportant" href="https://www.chipotle.com" />
  </head>
  ...
</html>
```

A list of prioritized tags and attributes can be found in [constants.js](./src/constants.js).

## Usage without Context
You can optionally use `<Helmet>` outside a context by manually creating a stateful `HelmetData` instance, and passing that stateful object to each `<Helmet>` instance:


```js
import React from 'react';
import { renderToString } from 'react-dom/server';
import { Helmet, HelmetProvider, HelmetData } from 'react-helmet-async';

const helmetData = new HelmetData({});

const app = (
    <App>
      <Helmet helmetData={helmetData}>
        <title>Hello World</title>
        <link rel="canonical" href="https://www.tacobell.com/" />
      </Helmet>
      <h1>Hello World</h1>
    </App>
);

const html = renderToString(app);

const { helmet } = helmetData.context;
```

## License

Licensed under the Apache 2.0 License, Copyright © 2018 Scott Taylor


---

# `react-is`

This package allows you to test arbitrary values and see if they're a particular React element type.

## Installation

```sh
# Yarn
yarn add react-is

# NPM
npm install react-is
```

## Usage

### Determining if a Component is Valid

```js
import React from "react";
import * as ReactIs from "react-is";

class ClassComponent extends React.Component {
  render() {
    return React.createElement("div");
  }
}

const FunctionComponent = () => React.createElement("div");

const ForwardRefComponent = React.forwardRef((props, ref) =>
  React.createElement(Component, { forwardedRef: ref, ...props })
);

const Context = React.createContext(false);

ReactIs.isValidElementType("div"); // true
ReactIs.isValidElementType(ClassComponent); // true
ReactIs.isValidElementType(FunctionComponent); // true
ReactIs.isValidElementType(ForwardRefComponent); // true
ReactIs.isValidElementType(Context.Provider); // true
ReactIs.isValidElementType(Context.Consumer); // true
ReactIs.isValidElementType(React.createFactory("div")); // true
```

### Determining an Element's Type

#### Context

```js
import React from "react";
import * as ReactIs from 'react-is';

const ThemeContext = React.createContext("blue");

ReactIs.isContextConsumer(<ThemeContext.Consumer />); // true
ReactIs.isContextProvider(<ThemeContext.Provider />); // true
ReactIs.typeOf(<ThemeContext.Provider />) === ReactIs.ContextProvider; // true
ReactIs.typeOf(<ThemeContext.Consumer />) === ReactIs.ContextConsumer; // true
```

#### Element

```js
import React from "react";
import * as ReactIs from 'react-is';

ReactIs.isElement(<div />); // true
ReactIs.typeOf(<div />) === ReactIs.Element; // true
```

#### Fragment

```js
import React from "react";
import * as ReactIs from 'react-is';

ReactIs.isFragment(<></>); // true
ReactIs.typeOf(<></>) === ReactIs.Fragment; // true
```

#### Portal

```js
import React from "react";
import ReactDOM from "react-dom";
import * as ReactIs from 'react-is';

const div = document.createElement("div");
const portal = ReactDOM.createPortal(<div />, div);

ReactIs.isPortal(portal); // true
ReactIs.typeOf(portal) === ReactIs.Portal; // true
```

#### StrictMode

```js
import React from "react";
import * as ReactIs from 'react-is';

ReactIs.isStrictMode(<React.StrictMode />); // true
ReactIs.typeOf(<React.StrictMode />) === ReactIs.StrictMode; // true
```


---


**IMPORTANT**: this is a minimalistic fork to solve the `componentWillMount` warning for the [facebook/docusaurus](https://github.com/facebook/docusaurus) project. 

v6.0 also adds support for React 18.3 / React 19, and removes the useless prop-type dependency.

We don't plan to support/maintain this project, just get rid of the deprecation warnings for our own needs. It is provided as-is, and we won't accept PRs.

----

![React Loadable](http://thejameskyle.com/img/react-loadable-header.png)


> A higher order component for loading components with dynamic imports.

## Install

```sh
yarn add react-loadable
```

## Example

```js
import Loadable from 'react-loadable';
import Loading from './my-loading-component';

const LoadableComponent = Loadable({
  loader: () => import('./my-component'),
  loading: Loading,
});

export default class App extends React.Component {
  render() {
    return <LoadableComponent/>;
  }
}
```

## Happy Customers:

- ["I'm obsessed with this right now: CRA with React Router v4 and react-loadable. Free code splitting, this is so easy."](https://twitter.com/matzatorski/status/872059865350406144)
- ["Oh hey - using loadable component I knocked 13K off my initial load. Easy win!"](https://twitter.com/AdamRackis/status/846593080992153600)
- ["Had a look and its awesome. shaved like 50kb off our main bundle."](https://github.com/quran/quran.com-frontend/pull/701#issuecomment-287908551)
- ["I've got that server-side rendering + code splitting + PWA ServiceWorker caching setup done 😎 (thanks to react-loadable). Now our frontend is super fast."](https://twitter.com/mxstbr/status/922375575217627136)
- ["Using react-loadable went from 221.28 KB → 115.76 KB @ main bundle. Fucking awesome and very simple API."](https://twitter.com/evgenyrodionov/status/958821614644269057)
- ["We've reduced our entry chunk by a lot & reduced initial load time by ~50%!"](https://github.com/jamiebuilds/react-loadable/pull/181)
- ["React-loadable is killer! We've decreased our load size by over 50kb with only 2 files! Can't wait to see how much lower it will go."](https://github.com/jamiebuilds/react-loadable/pull/180/)

## Users

- [AdHawk / Flooring Stores](https://www.flooringstores.com)
- [Akutbolig.dk](https://www.akutbolig.dk)
- [Analog.Cafe](https://www.analog.cafe)
- [Ambrosus](https://ambrosus.com)
- [Appbase.io](https://github.com/appbaseio/reactivesearch)
- [Atlassian](https://www.atlassian.com/)
- [BBC News](https://github.com/BBC-News/simorgh)
- [Blytzpay](https://www.blytzpay.com)
- [ClearTax](https://cleartax.in)
- [Cloudflare](https://www.cloudflare.com)
- [Chibaki](https://chibaki.co)
- [Compass](https://compass.com)
- [Curio](https://www.curio.org)
- [Delivery.com](https://www.delivery.com)
- [Doctor.com](https://www.doctor.com/)
- [Dollar Shave Club](https://github.com/dollarshaveclub)
- [Dresez](https://dresez.pk/)
- [Edcast](https://www.edcast.com/)
- [Evidation Health](https://evidation.com/)
- [Flexport](https://flexport.com/)
- [Flyhomes](https://flyhomes.com)
- [Gogo](https://gogoair.com)
- [Gofore](https://gofore.com/en/home/)
- [Graana](https://www.graana.com/)
- [Localie](https://localie.co/en)
- [MediaTek MCS-Lite](https://github.com/MCS-Lite)
- [NiYO Solutions Inc.](https://www.goniyo.com/)
- [Officepulse](https://www.officepulse.in/)
- [PageSpeed Green](https://pagespeed.green/)
- [Perx](https://www.perxtech.com/)
- [Plottu](https://public.plottu.com)
- [reformma](https://reformma.com.br)
- [Render](https://render.com)
- [Shift](https://shift.com)
- [Snipit](https://snipit.io)
- [Spectrum.chat](https://spectrum.chat)
- [Superblocks](https://superblocks.com)
- [Sprint Boards](https://sprintboards.io)
- [Talentpair](https://talentpair.com)
- [Tinder](https://tinder.com/)
- [Unsplash](https://unsplash.com/)
- [Wave](https://waveapps.com/)
- [WUZZUF](https://wuzzuf.net/)
- [Wxb](https://wxb.com/wxpush)

> _If your company or project is using React Loadable, please open a PR and add
> yourself to this list (in alphabetical order please)_

## Also See:

- [`react-loadable-visibility`](https://github.com/stratiformltd/react-loadable-visibility) - Building on top of and keeping the same API as `react-loadable`, this library enables you to load content that is visible on the screen.

- [`react-loadable-ssr-addon`](https://github.com/themgoncalves/react-loadable-ssr-addon) - Server Side Render add-on for `react-loadable`. Discover & load automatically dynamically all files dependencies, e.g. splitted chunks, css, etc.

<h2>
  <hr>
  <hr>
  <img src="http://thejameskyle.com/img/react-loadable-guide.png" alt="GUIDE">
  <hr>
  <hr>
  <small>Guide</small>
</h2>

So you've got your React app, you're bundling it with Webpack, and things are
going smooth. But then one day you notice your app's bundle is getting so big
that it's slowing things down.

It's time to start code-splitting your app!

![A single giant bundle vs multiple smaller bundles](http://thejameskyle.com/img/react-loadable-split-bundles.png)

Code-splitting is the process of taking one large bundle containing your entire
app, and splitting them up into multiple smaller bundles which contain separate
parts of your app.

This might seem difficult to do, but tools like Webpack have this built in, and
React Loadable is designed to make it super simple.

### Route-based splitting vs. Component-based splitting

A common piece of advice you will see is to break your app into separate routes
and load each one asynchronously. This seems to work well enough for many apps–
as a user, clicking a link and waiting for a page to load is a familiar
experience on the web.

But we can do better than that.

Using most routing tools for React, a route is simply a component. There's
nothing particularly special about them (Sorry Ryan and Michael– you're what's
special). So what if we optimized for splitting around components instead of
routes? What would that get us?

![Route vs. component centric code splitting](http://thejameskyle.com/img/react-loadable-component-splitting.png)

As it turns out: Quite a lot. There are many more places than just routes where
you can pretty easily split apart your app. Modals, tabs, and many more UI
components hide content until the user has done something to reveal it.

> **Example:** Maybe your app has a map buried inside of a tab component. Why
> would you load a massive mapping library for the parent route every time when
> the user may never go to that tab?

Not to mention all the places where you can defer loading content until higher
priority content is finished loading. That component at the bottom of your page
which loads a bunch of libraries: Why should that be loaded at the same time as
the content at the top?

And because routes are just components, we can still easily code-split at the
route level.

Introducing new code-splitting points in your app should be so easy that you
don't think twice about it. It should be a matter of changing a few lines of
code and everything else should be automated.

### Introducing React Loadable

React Loadable is a small library that makes component-centric code splitting
incredibly easy in React.

`Loadable` is a higher-order component (a function that creates a component)
which lets you dynamically load any module before rendering it into your app.

Let's imagine two components, one that imports and renders another.

```js
import Bar from './components/Bar';

class Foo extends React.Component {
  render() {
    return <Bar/>;
  }
}
```

Right now we're depending on `Bar` being imported synchronously via `import`,
but we don't need it until we go to render it. So why don't we just defer that?

Using a **dynamic import** ([a tc39 proposal currently at Stage 3](https://github.com/tc39/proposal-dynamic-import))
we can modify our component to load `Bar` asynchronously.

```js
class MyComponent extends React.Component {
  state = {
    Bar: null
  };

  componentWillMount() {
    import('./components/Bar').then(Bar => {
      this.setState({ Bar: Bar.default });
    });
  }

  render() {
    let {Bar} = this.state;
    if (!Bar) {
      return <div>Loading...</div>;
    } else {
      return <Bar/>;
    };
  }
}
```

But that's a whole bunch of work, and it doesn't even handle a bunch of cases.
What about when `import()` fails? What about server-side rendering?

Instead you can use `Loadable` to abstract away the problem.

```js
import Loadable from 'react-loadable';

const LoadableBar = Loadable({
  loader: () => import('./components/Bar'),
  loading() {
    return <div>Loading...</div>
  }
});

class MyComponent extends React.Component {
  render() {
    return <LoadableBar/>;
  }
}
```

### Automatic code-splitting on `import()`

When you use `import()` with Webpack 2+, it will
[automatically code-split](https://webpack.js.org/guides/code-splitting/) for
you with no additional configuration.

This means that you can easily experiment with new code splitting points just
by switching to `import()` and using React Loadable. Figure out what performs
best for your app.

### Creating a great "Loading..." Component

Rendering a static "Loading..." doesn't communicate enough to the user. You
also need to think about error states, timeouts, and making it a nice
experience.

```js
function Loading() {
  return <div>Loading...</div>;
}

Loadable({
  loader: () => import('./WillFailToLoad'), // oh no!
  loading: Loading,
});
```

To make this all nice, your [loading component](#loadingcomponent) receives a
couple different props.

#### Loading error states

When your [`loader`](optsloader) fails, your [loading component](#loadingcomponent)
will receive an [`error`](propserror) prop which will be an `Error` object (otherwise it
will be `null`).

```js
function Loading(props) {
  if (props.error) {
    return <div>Error! <button onClick={ props.retry }>Retry</button></div>;
  } else {
    return <div>Loading...</div>;
  }
}
```

#### Avoiding _Flash Of Loading Component_

Sometimes components load really quickly (<200ms) and the loading screen only
quickly flashes on the screen.

A number of user studies have proven that this causes users to perceive things
taking longer than they really have. If you don't show anything, users perceive
it as being faster.

So your loading component will also get a [`pastDelay` prop](#propspastdelay)
which will only be true once the component has taken longer to load than a set
[delay](#optsdelay).

```js
function Loading(props) {
  if (props.error) {
    return <div>Error! <button onClick={ props.retry }>Retry</button></div>;
  } else if (props.pastDelay) {
    return <div>Loading...</div>;
  } else {
    return null;
  }
}
```

This delay defaults to `200ms` but you can also customize the
[delay](#optsdelay) in `Loadable`.

```js
Loadable({
  loader: () => import('./components/Bar'),
  loading: Loading,
  delay: 300, // 0.3 seconds
});
```

#### Timing out when the `loader` is taking too long

Sometimes network connections suck and never resolve or fail, they just hang
there forever. This sucks for the user because they won't know if it should
always take this long, or if they should try refreshing.

The [loading component](#loadingcomponent) will receive a
[`timedOut` prop](#propstimedout) which will be set to `true` when the
[`loader`](#optsloader) has timed out.

```js
function Loading(props) {
  if (props.error) {
    return <div>Error! <button onClick={ props.retry }>Retry</button></div>;
  } else if (props.timedOut) {
    return <div>Taking a long time... <button onClick={ props.retry }>Retry</button></div>;
  } else if (props.pastDelay) {
    return <div>Loading...</div>;
  } else {
    return null;
  }
}
```

However, this feature is disabled by default. To turn it on, you can pass a
[`timeout` option](#optstimeout) to `Loadable`.

```js
Loadable({
  loader: () => import('./components/Bar'),
  loading: Loading,
  timeout: 10000, // 10 seconds
});
```

### Customizing rendering

By default `Loadable` will render the `default` export of the returned module.
If you want to customize this behavior you can use the
[`render` option](#optsrender).

```js
Loadable({
  loader: () => import('./my-component'),
  render(loaded, props) {
    let Component = loaded.namedExport;
    return <Component {...props}/>;
  }
});
```

### Loading multiple resources

Technically you can do whatever you want within `loader()` as long as it
returns a promise and [you're able to render something](#customizing-rendering).
But writing it out can be a bit annoying.

To make it easier to load multiple resources in parallel, you can use
[`Loadable.Map`](#loadablemap).

```js
Loadable.Map({
  loader: {
    Bar: () => import('./Bar'),
    i18n: () => fetch('./i18n/bar.json').then(res => res.json()),
  },
  render(loaded, props) {
    let Bar = loaded.Bar.default;
    let i18n = loaded.i18n;
    return <Bar {...props} i18n={i18n}/>;
  },
});
```

When using `Loadable.Map` the [`render()` method](#optsrender) is required. It
will be passed a `loaded` param which will be an object matching the shape of
your `loader`.

### Preloading

As an optimization, you can also decide to preload a component before it gets
rendered.

For example, if you need to load a new component when a button gets pressed,
you could start preloading the component when the user hovers over the button.

The component created by `Loadable` exposes a
[static `preload` method](#loadablecomponentpreload) which does exactly this.

```js
const LoadableBar = Loadable({
  loader: () => import('./Bar'),
  loading: Loading,
});

class MyComponent extends React.Component {
  state = { showBar: false };

  onClick = () => {
    this.setState({ showBar: true });
  };

  onMouseOver = () => {
    LoadableBar.preload();
  };

  render() {
    return (
      <div>
        <button
          onClick={this.onClick}
          onMouseOver={this.onMouseOver}>
          Show Bar
        </button>
        {this.state.showBar && <LoadableBar/>}
      </div>
    )
  }
}
```

<h2>
  <hr>
  <hr>
  <img src="http://thejameskyle.com/img/react-loadable-ssr.png" alt="SERVER SIDE RENDERING">
  <hr>
  <hr>
  <small>Server-Side Rendering</small>
</h2>

When you go to render all these dynamically loaded components, what you'll get
is a whole bunch of loading screens.

This really sucks, but the good news is that React Loadable is designed to
make server-side rendering work as if nothing is being loaded dynamically.

Here's our starting server using [Express](https://expressjs.com/).

```js
import express from 'express';
import React from 'react';
import ReactDOMServer from 'react-dom/server';
import App from './components/App';

const app = express();

app.get('/', (req, res) => {
  res.send(`
    <!doctype html>
    <html lang="en">
      <head>...</head>
      <body>
        <div id="app">${ReactDOMServer.renderToString(<App/>)}</div>
        <script src="/dist/main.js"></script>
      </body>
    </html>
  `);
});

app.listen(3000, () => {
  console.log('Running on http://localhost:3000/');
});
```

### Preloading all your loadable components on the server

The first step to rendering the correct content from the server is to make sure
that all of your loadable components are already loaded when you go to render
them.

To do this, you can use the [`Loadable.preloadAll`](#loadablepreloadall)
method. It returns a promise that will resolve when all your loadable
components are ready.

```js
Loadable.preloadAll().then(() => {
  app.listen(3000, () => {
    console.log('Running on http://localhost:3000/');
  });
});
```

### Picking up a server-side rendered app on the client

This is where things get a little bit tricky. So let's prepare ourselves
little bit.

In order for us to pick up what was rendered from the server we need to have
all the same code that was used to render on the server.

To do this, we first need our loadable components telling us which modules they
are rendering.

#### Declaring which modules are being loaded

There are two options in [`Loadable`](#loadable) and
[`Loadable.Map`](#loadablemap) which are used to tell us which modules our
component is trying to load: [`opts.modules`](#optsmodules) and
[`opts.webpack`](#optswebpack).

```js
Loadable({
  loader: () => import('./Bar'),
  modules: ['./Bar'],
  webpack: () => [require.resolveWeak('./Bar')],
});
```

But don't worry too much about these options. React Loadable includes a
[Babel plugin](#babel-plugin) to add them for you.

Just add the `react-loadable/babel` plugin to your Babel config:

```json
{
  "plugins": [
    "react-loadable/babel"
  ]
}
```

Now these options will automatically be provided.

For typescript you can use [react-loadable-ts-transformer](https://github.com/stushurik/react-loadable-ts-transformer) which is a ts analog of react-loadable/babel plugin.

#### Finding out which dynamic modules were rendered

Next we need to find out which modules were actually rendered when a request
comes in.

For this, there is [`Loadable.Capture`](#loadablecapture) component which can
be used to collect all the modules that were rendered.

```js
import Loadable from 'react-loadable';

app.get('/', (req, res) => {
  let modules = [];

  let html = ReactDOMServer.renderToString(
    <Loadable.Capture report={moduleName => modules.push(moduleName)}>
      <App/>
    </Loadable.Capture>
  );

  console.log(modules);

  res.send(`...${html}...`);
});
```

#### Mapping loaded modules to bundles

In order to make sure that the client loads all the modules that were rendered
server-side, we'll need to map them to the bundles that Webpack created.

This comes in two parts.

First we need Webpack to tell us which bundles each module lives inside. For
this there is the [React Loadable Webpack plugin](#webpack-plugin).

Import the `ReactLoadablePlugin` from `react-loadable/webpack` and include it
in your webpack config. Pass it a `filename` for where to store the JSON data
about our bundles.

```js
// webpack.config.js
import { ReactLoadablePlugin } from 'react-loadable/webpack';

export default {
  plugins: [
    new ReactLoadablePlugin({
      filename: './dist/react-loadable.json',
    }),
  ],
};
```

Then we'll go back to our server and use this data to convert our modules to
bundles.

To convert from modules to bundles, import the [`getBundles`](#getbundles)
method from `react-loadable/webpack` and the data from Webpack.

```js
import Loadable from 'react-loadable';
import { getBundles } from 'react-loadable/webpack'
import stats from './dist/react-loadable.json';

app.get('/', (req, res) => {
  let modules = [];

  let html = ReactDOMServer.renderToString(
    <Loadable.Capture report={moduleName => modules.push(moduleName)}>
      <App/>
    </Loadable.Capture>
  );

  let bundles = getBundles(stats, modules);

  // ...
});
```

We can then render these bundles into `<script>` tags in our HTML.

It is important that the bundles are included _before_ the main bundle, so that
they can be loaded by the browser prior to the app rendering.

However, as the Webpack manifest (including the logic for parsing bundles) lives in
the main bundle, it will need to be extracted into its own chunk.

This is easy to do with the [CommonsChunkPlugin](https://webpack.js.org/plugins/commons-chunk-plugin/)

```js
// webpack.config.js
export default {
  plugins: [
    new webpack.optimize.CommonsChunkPlugin({
      name: 'manifest',
      minChunks: Infinity
    })
  ]
}
```

_Notice: As of Webpack 4 the CommonsChunkPlugin has been removed and the manifest doesn't need to be extracted anymore._

```js
let bundles = getBundles(stats, modules);

res.send(`
  <!doctype html>
  <html lang="en">
    <head>...</head>
    <body>
      <div id="app">${html}</div>
      <script src="/dist/manifest.js"></script>
      <script src="/dist/main.js"></script>
      ${bundles.map(bundle => {
        return `<script src="/dist/${bundle.file}"></script>`
        // alternatively if you are using publicPath option in webpack config
        // you can use the publicPath value from bundle, e.g:
        // return `<script src="${bundle.publicPath}"></script>`
      }).join('\n')}
      <script>window.main();</script>
    </body>
  </html>
`);
```

#### Preloading ready loadable components on the client

We can use the [`Loadable.preloadReady()`](#loadablepreloadready) method on the
client to preload the loadable components that were included on the page.

Like [`Loadable.preloadAll()`](#loadablepreloadall), it returns a promise,
which on resolution means that we can hydrate our app.

```js
// src/entry.js
import React from 'react';
import ReactDOM from 'react-dom';
import Loadable from 'react-loadable';
import App from './components/App';

window.main = () => {
  Loadable.preloadReady().then(() => {
    ReactDOM.hydrate(<App/>, document.getElementById('app'));
  });
};

```

<h4 align="center">
  Now server-side rendering should work perfectly!
</h4>

<h2>
  <hr>
  <hr>
  <img src="http://thejameskyle.com/img/react-loadable-api-docs.png" alt="API DOCS">
  <hr>
  <hr>
  <small>API Docs</small>
</h2>

### `Loadable`

A higher-order component for dynamically [loading](#optsloader) a module before
[rendering](#optsrender) it, a [loading](#opts.loading) component is rendered
while the module is unavailable.

```js
const LoadableComponent = Loadable({
  loader: () => import('./Bar'),
  loading: Loading,
  delay: 200,
  timeout: 10000,
});
```

This returns a [LoadableComponent](#loadablecomponent).

### `Loadable.Map`

A higher-order component that allows you to load multiple resources in parallel.

Loadable.Map's [`opts.loader`](#optsloader) accepts an object of functions, and
needs a [`opts.render`](#optsrender) method.

```js
Loadable.Map({
  loader: {
    Bar: () => import('./Bar'),
    i18n: () => fetch('./i18n/bar.json').then(res => res.json()),
  },
  render(loaded, props) {
    let Bar = loaded.Bar.default;
    let i18n = loaded.i18n;
    return <Bar {...props} i18n={i18n}/>;
  }
});
```

When using `Loadable.Map` the `render()` method's `loaded` param will be an
object with the same shape as your `loader`.

### `Loadable` and `Loadable.Map` Options

#### `opts.loader`

A function returning a promise that loads your module.

```js
Loadable({
  loader: () => import('./Bar'),
});
```

When using with [`Loadable.Map`](#loadablemap) this accepts an object of these
types of functions.

```js
Loadable.Map({
  loader: {
    Bar: () => import('./Bar'),
    i18n: () => fetch('./i18n/bar.json').then(res => res.json()),
  },
});
```

When using with `Loadable.Map` you'll also need to pass a
[`opts.render`](#optsrender) function.

#### `opts.loading`

A [`LoadingComponent`](#loadingcomponent) that renders while a module is
loading or when it errors.

```js
Loadable({
  loading: LoadingComponent,
});
```

This option is required, if you don't want to render anything, return `null`.

```js
Loadable({
  loading: () => null,
});
```

#### `opts.delay`

Time to wait (in milliseconds) before passing
[`props.pastDelay`](#propspastdelay) to your [`loading`](#optsloading)
component. This defaults to `200`.

```js
Loadable({
  delay: 200
});
```

[Read more about delays](#avoiding-flash-of-loading-component).

#### `opts.timeout`

Time to wait (in milliseconds) before passing
[`props.timedOut`](#propstimedout) to your [`loading`](#optsloading) component.
This is turned off by default.

```js
Loadable({
  timeout: 10000
});
```

[Read more about timeouts](#timing-out-when-the-loader-is-taking-too-long).

#### `opts.render`

A function to customize the rendering of loaded modules.

Receives `loaded` which is the resolved value of [`opts.loader`](#optsloader)
and `props` which are the props passed to the
[`LoadableComponent`](#loadablecomponent).

```js
Loadable({
  render(loaded, props) {
    let Component = loaded.default;
    return <Component {...props}/>;
  }
});
```

#### `opts.webpack`

An optional function which returns an array of Webpack module ids which you can
get with `require.resolveWeak`.

```js
Loadable({
  loader: () => import('./Foo'),
  webpack: () => [require.resolveWeak('./Foo')],
});
```

This option can be automated with the [Babel Plugin](#babel-plugin).

#### `opts.modules`

An optional array with module paths for your imports.

```js
Loadable({
  loader: () => import('./my-component'),
  modules: ['./my-component'],
});
```

This option can be automated with the [Babel Plugin](#babel-plugin).

### `LoadableComponent`

This is the component returned by `Loadable` and `Loadable.Map`.

```js
const LoadableComponent = Loadable({
  // ...
});
```

Props passed to this component will be passed straight through to the
dynamically loaded component via [`opts.render`](#optsrender).

#### `LoadableComponent.preload()`

This is a static method on [`LoadableComponent`](#loadablecomponent) which can
be used to load the component ahead of time.

```js
const LoadableComponent = Loadable({...});

LoadableComponent.preload();
```

This returns a promise, but you should avoid waiting for that promise to
resolve to update your UI. In most cases it creates a bad user experience.

[Read more about preloading](#preloading).

### `LoadingComponent`

This is the component you pass to [`opts.loading`](#optsloading).

```js
function LoadingComponent(props) {
  if (props.error) {
    // When the loader has errored
    return <div>Error! <button onClick={ props.retry }>Retry</button></div>;
  } else if (props.timedOut) {
    // When the loader has taken longer than the timeout
    return <div>Taking a long time... <button onClick={ props.retry }>Retry</button></div>;
  } else if (props.pastDelay) {
    // When the loader has taken longer than the delay
    return <div>Loading...</div>;
  } else {
    // When the loader has just started
    return null;
  }
}

Loadable({
  loading: LoadingComponent,
});
```

[Read more about loading components](#creating-a-great-loading-component)

#### `props.error`

An `Error` object passed to [`LoadingComponent`](#loadingcomponent) when the
[`loader`](#optsloader) has failed. When there is no error, `null` is
passed.

```js
function LoadingComponent(props) {
  if (props.error) {
    return <div>Error!</div>;
  } else {
    return <div>Loading...</div>;
  }
}
```

[Read more about errors](#loading-error-states).

#### `props.retry`

A function prop passed to [`LoadingComponent`](#loadingcomponent) when the
[`loader`](#optsloader) has failed, used to retry loading the component.

```js
function LoadingComponent(props) {
  if (props.error) {
    return <div>Error! <button onClick={ props.retry }>Retry</button></div>;
  } else {
    return <div>Loading...</div>;
  }
}
```

[Read more about errors](#loading-error-states).

#### `props.timedOut`

A boolean prop passed to [`LoadingComponent`](#loadingcomponent) after a set
[`timeout`](#optstimeout).

```js
function LoadingComponent(props) {
  if (props.timedOut) {
    return <div>Taking a long time...</div>;
  } else {
    return <div>Loading...</div>;
  }
}
```

[Read more about timeouts](#timing-out-when-the-loader-is-taking-too-long).

#### `props.pastDelay`

A boolean prop passed to [`LoadingComponent`](#loadingcomponent) after a set
[`delay`](#optsdelay).

```js
function LoadingComponent(props) {
  if (props.pastDelay) {
    return <div>Loading...</div>;
  } else {
    return null;
  }
}
```

[Read more about delays](#avoiding-flash-of-loading-component).

### `Loadable.preloadAll()`

This will call all of the
[`LoadableComponent.preload`](#loadablecomponentpreload) methods recursively
until they are all resolved. Allowing you to preload all of your dynamic
modules in environments like the server.

```js
Loadable.preloadAll().then(() => {
  app.listen(3000, () => {
    console.log('Running on http://localhost:3000/');
  });
});
```

It's important to note that this requires that you declare all of your loadable
components when modules are initialized rather than when your app is being
rendered.

**Good:**

```js
// During module initialization...
const LoadableComponent = Loadable({...});

class MyComponent extends React.Component {
  componentDidMount() {
    // ...
  }
}
```

**Bad:**

```js
// ...

class MyComponent extends React.Component {
  componentDidMount() {
    // During app render...
    const LoadableComponent = Loadable({...});
  }
}
```

> **Note:** `Loadable.preloadAll()` will not work if you have more than one
> copy of `react-loadable` in your app.

[Read more about preloading on the server](#preloading-all-your-loadable-components-on-the-server).

### `Loadable.preloadReady()`

Check for modules that are already loaded in the browser and call the matching
[`LoadableComponent.preload`](#loadablecomponentpreload) methods.

```js
Loadable.preloadReady().then(() => {
  ReactDOM.hydrate(<App/>, document.getElementById('app'));
});
```

[Read more about preloading on the client](#waiting-to-render-on-the-client-until-all-the-bundles-are-loaded).

### `Loadable.Capture`

A component for reporting which modules were rendered.

Accepts a `report` prop which is called for every `moduleName` that is
rendered via React Loadable.

```js
let modules = [];

let html = ReactDOMServer.renderToString(
  <Loadable.Capture report={moduleName => modules.push(moduleName)}>
    <App/>
  </Loadable.Capture>
);

console.log(modules);
```

[Read more about capturing rendered modules](#finding-out-which-dynamic-modules-were-rendered).

## Babel Plugin

Providing [`opts.webpack`](#optswebpack) and [`opts.modules`](#optsmodules) for
every loadable component is a lot of manual work to remember to do.

Instead you can add the Babel plugin to your config and it will automate it for
you:

```json
{
  "plugins": ["react-loadable/babel"]
}
```

**Input**

```js
import Loadable from 'react-loadable';

const LoadableMyComponent = Loadable({
  loader: () => import('./MyComponent'),
});

const LoadableComponents = Loadable.Map({
  loader: {
    One: () => import('./One'),
    Two: () => import('./Two'),
  },
});
```

**Output**

```js
import Loadable from 'react-loadable';
import path from 'path';

const LoadableMyComponent = Loadable({
  loader: () => import('./MyComponent'),
  webpack: () => [require.resolveWeak('./MyComponent')],
  modules: [path.join(__dirname, './MyComponent')],
});

const LoadableComponents = Loadable.Map({
  loader: {
    One: () => import('./One'),
    Two: () => import('./Two'),
  },
  webpack: () => [require.resolveWeak('./One'), require.resolveWeak('./Two')],
  modules: [path.join(__dirname, './One'), path.join(__dirname, './Two')],
});
```

[Read more about declaring modules](#declaring-which-modules-are-being-loaded).

## Webpack Plugin

In order to [send the right bundles down](#mapping-loaded-modules-to-bundles)
when rendering server-side, you'll need the React Loadable Webpack plugin 
to provide you with a mapping of modules to bundles.

```js
// webpack.config.js
import { ReactLoadablePlugin } from 'react-loadable/webpack';

export default {
  plugins: [
    new ReactLoadablePlugin({
      filename: './dist/react-loadable.json',
    }),
  ],
};
```

This will create a file (`opts.filename`) which you can import to map modules
to bundles.

[Read more about mapping modules to bundles](#mapping-loaded-modules-to-bundles).

### `getBundles`

A method exported by `react-loadable/webpack` for converting modules to
bundles.

```js
import { getBundles } from 'react-loadable/webpack';

let bundles = getBundles(stats, modules);
```

[Read more about mapping modules to bundles](#mapping-loaded-modules-to-bundles).

<h2>
  <hr>
  <hr>
  <img src="http://thejameskyle.com/img/react-loadable-faq.png" alt="FAQ">
  <hr>
  <hr>
  <small>FAQ</small>
</h2>

### How do I avoid repetition?

Specifying the same `loading` component or `delay` every time you use
`Loadable()` gets repetitive fast. Instead you can wrap `Loadable` with your
own Higher-Order Component (HOC) to set default options.

```js
import Loadable from 'react-loadable';
import Loading from './my-loading-component';

export default function MyLoadable(opts) {
  return Loadable(Object.assign({
    loading: Loading,
    delay: 200,
    timeout: 10000,
  }, opts));
};
```

Then you can just specify a `loader` when you go to use it.

```js
import MyLoadable from './MyLoadable';

const LoadableMyComponent = MyLoadable({
  loader: () => import('./MyComponent'),
});

export default class App extends React.Component {
  render() {
    return <LoadableMyComponent/>;
  }
}
```

Unfortunately at the moment using wrapped Loadable breaks [react-loadable/babel](#babel-plugin) so in such case you have to add required properties (`modules`, `webpack`) manually.

```js
import MyLoadable from './MyLoadable';

const LoadableMyComponent = MyLoadable({
  loader: () => import('./MyComponent'),
  modules: ['./MyComponent'],
  webpack: () => [require.resolveWeak('./MyComponent')],
});

export default class App extends React.Component {
  render() {
    return <LoadableMyComponent/>;
  }
}
```

### How do I handle other styles `.css` or sourcemaps `.map` with server-side rendering?

When you call [`getBundles`](#getbundles), it may return file types other than
JavaScript depending on your Webpack configuration.

To handle this, you should manually filter down to the file extensions that
you care about:

```js
let bundles = getBundles(stats, modules);

let styles = bundles.filter(bundle => bundle.file.endsWith('.css'));
let scripts = bundles.filter(bundle => bundle.file.endsWith('.js'));

res.send(`
  <!doctype html>
  <html lang="en">
    <head>
      ...
      ${styles.map(style => {
        return `<link href="/dist/${style.file}" rel="stylesheet"/>`
      }).join('\n')}
    </head>
    <body>
      <div id="app">${html}</div>
      <script src="/dist/main.js"></script>
      ${scripts.map(script => {
        return `<script src="/dist/${script.file}"></script>`
      }).join('\n')}
    </body>
  </html>
`);
```


---

# Contributor Covenant Code of Conduct

## Our Pledge

In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.

## Our Standards

Examples of behavior that contributes to creating a positive environment include:

* Using welcoming and inclusive language
* Being respectful of differing viewpoints and experiences
* Gracefully accepting constructive criticism
* Focusing on what is best for the community
* Showing empathy towards other community members

Examples of unacceptable behavior by participants include:

* The use of sexualized language or imagery and unwelcome sexual attention or advances
* Trolling, insulting/derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or electronic address, without explicit permission
* Other conduct which could reasonably be considered inappropriate in a professional setting

## Our Responsibilities

Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.

Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.

## Scope

This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.

## Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at contact@themgoncalves.com. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.

Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.

## Attribution

This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version]

[homepage]: http://contributor-covenant.org
[version]: http://contributor-covenant.org/version/1/4/


---

# Issue Title
<!--- Provide a general summary of the issue in the Title above -->

## Expected Behavior
<!--- Tell us what should happen -->

## Current Behavior
<!--- Tell us what happens instead of the expected behavior -->

## Possible Solution
<!--- Not obligatory, but suggest a fix/reason for the bug, -->

## Steps to Reproduce
<!--- Provide a link to a live example, or an unambiguous set of steps to -->
<!--- reproduce this bug. Include code to reproduce, if relevant -->
1.
2.
3.
4.

## Context (Environment)
<!--- How has this issue affected you? What are you trying to accomplish? -->
<!--- Providing context helps us come up with a solution that is most useful in the real world -->

<!--- Provide a general summary of the issue in the Title above -->

### Environment

1. OS running: <!--- macOS mojave/Windows 10/Linux Ubunto...  -->
2. Node version:
3. Webpack version:

## Detailed Description
<!--- Provide a detailed description of the change or addition you are proposing -->

## Possible Implementation
<!--- Not obligatory, but suggest an idea for implementing addition or change -->

## Other Comments


---

## Summary
A few sentences describing the overall goals of the pull request's commits.

## Why
A few sentences describing the reasons behind this pull request.

## Checklist

- [ ] Your code builds clean without any `errors` or `warnings`
- [ ] You are using `approved terminology`
- [ ] You have added `unit tests`, if apply.

## Emojis for categorizing pull requests:

⚡️ New feature (`:zap:`)
🐛 Bug fix (`:bug:`)  
🔥 P0 fix (`:fire:`)  
✅ Tests (`:white_check_mark:`)  
🚀 Performance improvements (`:rocket:`)  
🖍 CSS / Styling (`:crayon:`)  
♿ Accessibility (`:wheelchair:`)  
🌐 Internationalization (`:globe_with_meridians:`)  
📖 Documentation (`:book:`)  
🏗 Infrastructure / Tooling / Builds / CI (`:building_construction:`)  
⏪ Reverting a previous change (`:rewind:`)  
♻️ Refactoring (like moving around code w/o any changes) (`:recycle:`)  
🚮 Deleting code (`:put_litter_in_its_place:`)


---

react-loadable-ssr-addon is authored by: 

* Alexey Pyltsyn <lex61rus@gmail.com>
* Endi <endiliey@gmail.com>
* Jérémie Parker <gitkraken@jeremie-parker.com>
* Marcos <contact@themgoncalves.com>
* Marcos Gonçalves <contact@themgoncalves.com>
* Ngoc Phuong <nguyenngocphuongnb@gmail.com>
* Phuong Nguyen <nguyenngocphuongnb@gmail.com>
* Reece Dunham <me@rdil.rocks>
* Sébastien Lorber <slorber@users.noreply.github.com>
* dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
* endiliey <endiliey@gmail.com>
* slorber <lorber.sebastien@gmail.com>


---

# React Loadable SSR Add-on
> Server Side Render add-on for React Loadable. Load splitted chunks was never that easy.

[![NPM][npm-image]][npm-url]
[![CircleCI][circleci-image]][circleci-url]
[![GitHub All Releases][releases-image]][releases-url]
[![GitHub stars][stars-image]][stars-url]
[![Known Vulnerabilities][vulnerabilities-image]][vulnerabilities-url]
[![GitHub issues][issues-image]][issues-url]
[![Awesome][awesome-image]][awesome-url]

## Description

`React Loadable SSR Add-on` is a `server side render` add-on for [React Loadable](https://github.com/jamiebuilds/react-loadable)
that helps you to load dynamically all files dependencies, e.g. `splitted chunks`, `css`, etc.

Oh yeah, and we also **provide support for [SRI (Subresource Integrity)](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity)**.

<br />

## Installation

**Download our NPM Package**

```sh
npm install react-loadable-ssr-addon
# or
yarn add react-loadable-ssr-addon
```

**Note**: `react-loadable-ssr-addon` **should not** be listed in the `devDependencies`.

<br />

## How to use

### 1 - Webpack Plugin

First we need to import the package into our component;

```javascript
const ReactLoadableSSRAddon = require('react-loadable-ssr-addon');

module.exports = {
  entry: {
    // ...
  },
  output: {
    // ...
  },
  module: {
    // ...
  },
  plugins: [
    new ReactLoadableSSRAddon({
      filename: 'assets-manifest.json',
    }),
  ],
};
```

<br />

### 2 - On the Server


```js
// import `getBundles` to map required modules and its dependencies
import { getBundles } from 'react-loadable-ssr-addon';
// then import the assets manifest file generated by the Webpack Plugin
import manifest from './your-output-folder/assets-manifest.json';

...

// react-loadable ssr implementation
const modules = new Set();

const html = ReactDOMServer.renderToString(
<Loadable.Capture report={moduleName => modules.add(moduleName)}>
  <App />
</Loadable.Capture>
);

...

// now we concatenate the loaded `modules` from react-loadable `Loadable.Capture` method
// with our application entry point
const modulesToBeLoaded = [...manifest.entrypoints, ...Array.from(modules)];
// also if you find your project still fetching the files after the placement
// maybe a good idea to switch the order from the implementation above to
// const modulesToBeLoaded = [...Array.from(modules), ...manifest.entrypoints];
// see the issue #6 regarding this thread
// https://github.com/themgoncalves/react-loadable-ssr-addon/issues/6

// after that, we pass the required modules to `getBundles` map it.
// `getBundles` will return all the required assets, group by `file type`.
const bundles = getBundles(manifest, modulesToBeLoaded);

// so it's easy to implement it
const styles = bundles.css || [];
const scripts = bundles.js || [];

res.send(`
  <!doctype html>
  <html lang="en">
    <head>...</head>
    ${styles.map(style => {
      return `<link href="/dist/${style.file}" rel="stylesheet" />`;
    }).join('\n')}
    <body>
      <div id="app">${html}</div>
      ${scripts.map(script => {
        return `<script src="/dist/${script.file}"></script>`
      }).join('\n')}
  </html>
`);
```

See how easy to implement it is?

<br />

## API Documentation

### Webpack Plugin options

#### `filename`

Type: `string`
Default: `react-loadable.json`

Assets manifest file name. May contain relative or absolute path.


#### `integrity`

Type: `boolean`
Default: `false`

Enable or disable generation of [Subresource Integrity (SRI).](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) hash.

#### `integrityAlgorithms`

Type: `array`
Default: `[ 'sha256', 'sha384', 'sha512' ]`

Algorithms to generate hash.


#### `integrityPropertyName`

Type: `string`
Default: `integrity`

Custom property name to be output in the assets manifest file.


**Full configuration example**

```js
new ReactLoadableSSRAddon({
  filename: 'assets-manifest.json',
  integrity: false,
  integrityAlgorithms: [ 'sha256', 'sha384', 'sha512' ],
  integrityPropertyName: 'integrity',
})
```

<br />

### Server Side

### `getBundles`

```js
import { getBundles } from 'react-loadable-ssr-addon';

/**
 * getBundles
 * @param {object} manifest - The assets manifest content generate by ReactLoadableSSRAddon
 * @param {array} chunks - Chunks list to be loaded
 * @returns {array} - Assets list group by file type
 */
const bundles = getBundles(manifest, modules);


const styles = bundles.css || [];
const scripts = bundles.js || [];
const xml = bundles.xml || [];
const json = bundles.json || [];
...
```

<br />

### Assets Manifest

#### `Basic Structure`

```json
{
  "entrypoints": [ ],
  "origins": {
    "app": [ ]
  },
  "assets": {
    "app": {
      "js": [
        {
          "file": "",
          "hash": "",
          "publicPath": "",
          "integrity": ""
        }
      ]
    }
  }
}
```

#### `entrypoints`

Type: `array`

List of all application entry points defined in Webpack `entry`.


#### `origins`

Type: `array`

Origin name requested. List all assets required for the requested origin.


#### `assets`

Type: `array` of objects

Lists all application assets generate by Webpack, group by file type,
containing an `array of objects` with the following format:

```js
[file-type]: [
    {
      "file": "",       // assets file
      "hash": "",       // file hash generated by Webpack
      "publicPath": "", // assets file + webpack public path
      "integrity": ""   // integrity base64 hash, if enabled
    }
]
```

<br />

### Assets Manifest Example

```json
{
  "entrypoints": [
    "app"
  ],
  "origins": {
    "./home": [
      "home"
    ],
    "./about": [
      "about"
    ],
    "app": [
      "vendors",
      "app"
    ],
     "vendors": [
       "app",
       "vendors"
     ]
  },
  "assets": {
    "home": {
      "js": [
        {
          "file": "home.chunk.js",
          "hash": "fdb00ffa16dfaf9cef0a",
          "publicPath": "/dist/home.chunk.js",
          "integrity": "sha256-Xxf7WVjPbdkJjgiZt7mvZvYv05+uErTC9RC2yCHF1RM= sha384-9OgouqlzN9KrqXVAcBzVMnlYOPxOYv/zLBOCuYtUAMoFxvmfxffbNIgendV4KXSJ sha512-oUxk3Swi0xIqvIxdWzXQIDRYlXo/V/aBqSYc+iWfsLcBftuIx12arohv852DruxKmlqtJhMv7NZp+5daSaIlnw=="
        }
      ]
    },
    "about": {
      "js": [
        {
          "file": "about.chunk.js",
          "hash": "7e88ef606abbb82d7e82",
          "publicPath": "/dist/about.chunk.js",
          "integrity": "sha256-ZPrPWVJRjdS4af9F1FzkqTqqSGo1jYyXNyctwTOLk9o= sha384-J1wiEV8N1foqRF7W9SEvg2s/FhQbhpKFHBTNBJR8g1yEMNRMi38y+8XmjDV/Iu7w sha512-b16+PXStO68CP52R+0ZktccMiaI1v0jOy34l/DqyGN7kEae3DpV3xPNoC8vt1WfE1kCAH7dlnHDdp1XRVhZX+g=="
        }
      ]
    },
    "app": {
      "css": [
        {
          "file": "app.css",
          "hash": "5888714915d8e89a8580",
          "publicPath": "/dist/app.css",
          "integrity": "sha256-3y4DyCC2cLII5sc2kaElHWhBIVMHdan/tA0akReI9qg= sha384-vCMVPKjSrrNpfnhmCD9E8SyHdfPdnM3DO/EkrbNI2vd0m2wH6BnfPja6gt43nDIF"
        }
      ],
      "js": [
        {
          "file": "app.bundle.js",
          "hash": "0cbd05b10204597c781d",
          "publicPath": "/dist/app.bundle.js",
          "integrity": "sha256-sGdw+WVvXK1ZVQnYHI4FpecOcZtWZ99576OHCdrGil8= sha384-DZZzkPtPCTCR5UOWuGCyXQvsjyvZPoreCzqQGyrNV8+HyV9MdoYZawHX7NdGGLyi sha512-y29BlwBuwKB+BeXrrQYEBrK+mfWuOb4ok6F57kGbtrwa/Xq553Zb7lgss8RNvFjBSaMUdvXiJuhmP3HZA0jNeg=="
        }
      ]
    },
    "vendors": {
      "css": [
        {
          "file": "vendors.css",
          "hash": "5a9586c29103a034feb5",
          "publicPath": "/dist/vendors.css"
        }
      ],
      "js": [
        {
          "file": "vendors.chunk.js",
          "hash": "5a9586c29103a034feb5",
          "publicPath": "/dist/vendors.chunk.js"
        }
      ]
    }
  }
}
```

<br />

## Release History
* 1.0.1
    * FIX: [Webpack v5 deprecation warning](https://github.com/themgoncalves/react-loadable-ssr-addon/pull/27)
* 1.0.0
    * BREAKING CHANGE: drop support for Webpack v3.
    * NEW: add [support for Webpack v5](https://github.com/themgoncalves/react-loadable-ssr-addon/pull/26)
<details>
  <summary>See older release note</summary>
* 0.3.0
    * NEW: [`@babel/runtime` become an explicit dependency](https://github.com/themgoncalves/react-loadable-ssr-addon/pull/22) by [@RDIL](https://github.com/RDIL)
        > Requirement for `yarn v2`.
* 0.2.3
    * FIX: [Parsing `null` or `undefined` to object on `getBundles()`](https://github.com/themgoncalves/react-loadable-ssr-addon/pull/21) reported by [@slorber](https://github.com/slorber)
* 0.2.2
    * FIX: As precaution measure, downgrade few dependencies due to node SemVer incompatibility.
* 0.2.1
    * FIX: [Possible missing chunk](https://github.com/themgoncalves/react-loadable-ssr-addon/pull/20) reported by [@lex111](https://github.com/lex111)
* 0.2.0
    * Improvement: Reduce memory consumption ([Issue #17](https://github.com/themgoncalves/react-loadable-ssr-addon/issues/17)) reported by [@endiliey](https://github.com/endiliey)
* 0.1.9
    * FIX: [Missing entry in origins](https://github.com/themgoncalves/react-loadable-ssr-addon/pull/13) reported by [@p-j](https://github.com/p-j);
* 0.1.8
    * Includes all features from deprecated v0.1.7;
    * FIX: [Issue #11](https://github.com/themgoncalves/react-loadable-ssr-addon/issues/11) reported by [@endiliey](https://github.com/endiliey)
* ~~0.1.7 (_deprecated_)~~
    * FIX: [`Cannot read property 'integrity' of undefined`](https://github.com/themgoncalves/react-loadable-ssr-addon/pull/10) reported by [@nguyenngocphuongnb](https://github.com/nguyenngocphuongnb);
    * Minor improvements.
* 0.1.6
    * FIX: `getManifestOutputPath` method when requested from `Webpack Dev Middleware`;
* 0.1.5
    * FIX: [Issue #7](https://github.com/themgoncalves/react-loadable-ssr-addon/issues/7) reported by [@themgoncalves](https://github.com/themgoncalves) and [@tomkelsey](https://github.com/tomkelsey)
* 0.1.4
    * FIX: [Issue #5](https://github.com/themgoncalves/react-loadable-ssr-addon/issues/5) reported by [@tomkelsey](https://github.com/tomkelsey)
* 0.1.3
    * FIX: [Issue #4](https://github.com/themgoncalves/react-loadable-ssr-addon/issues/4) reported by [@tomkelsey](https://github.com/tomkelsey)
* 0.1.2
    * FIX: [Issue #2](https://github.com/themgoncalves/react-loadable-ssr-addon/issues/2) reported by [@tatchi](https://github.com/tatchi)
* 0.1.1
    * FIX: [Issue #1](https://github.com/themgoncalves/react-loadable-ssr-addon/issues/1) reported by [@tatchi](https://github.com/tatchi)
* 0.1.0
    * First release
    * NEW: Created `getBundles()` to retrieve required assets
    * NEW: Created `ReactLoadableSSRAddon` Plugin for Webpack 3+
* 0.0.1
    * Work in progress
</details>

<br />

## Meta

### Author
**Marcos Gonçalves** – [LinkedIn](http://linkedin.com/in/themgoncalves/) – [Website](http://www.themgoncalves.com)

### License
Distributed under the MIT license. [Click here](/LICENSE) for more information.

[https://github.com/themgoncalves/react-loadable-ssr-addon](https://github.com/themgoncalves/react-loadable-ssr-addon)

## Contributing

1. Fork it (<https://github.com/themgoncalves/react-loadable-ssr-addon/fork>)
2. Create your feature branch (`git checkout -b feature/fooBar`)
3. Commit your changes (`git commit -m ':zap: Add some fooBar'`)
4. Push to the branch (`git push origin feature/fooBar`)
5. Create a new Pull Request

### Emojis for categorizing commits:

⚡️ New feature (`:zap:`)
🐛 Bug fix (`:bug:`)
🔥 P0 fix (`:fire:`)
✅ Tests (`:white_check_mark:`)
🚀 Performance improvements (`:rocket:`)
🖍 CSS / Styling (`:crayon:`)
♿ Accessibility (`:wheelchair:`)
🌐 Internationalization (`:globe_with_meridians:`)
📖 Documentation (`:book:`)
🏗 Infrastructure / Tooling / Builds / CI (`:building_construction:`)
⏪ Reverting a previous change (`:rewind:`)
♻️ Refactoring (like moving around code w/o any changes) (`:recycle:`)
🚮 Deleting code (`:put_litter_in_its_place:`)

<!-- Markdown link & img dfn's -->

[circleci-image]:https://circleci.com/gh/themgoncalves/react-loadable-ssr-addon.svg?style=svg
[circleci-url]: https://circleci.com/gh/themgoncalves/react-loadable-ssr-addon
[vulnerabilities-image]: https://snyk.io/test/github/themgoncalves/react-loadable-ssr-addon/badge.svg
[vulnerabilities-url]: https://snyk.io/test/github/themgoncalves/react-loadable-ssr-addon
[issues-image]: https://img.shields.io/github/issues/themgoncalves/react-loadable-ssr-addon.svg
[issues-url]: https://github.com/themgoncalves/react-loadable-ssr-addon/issues
[stars-image]: https://img.shields.io/github/stars/themgoncalves/react-loadable-ssr-addon.svg
[stars-url]: https://github.com/themgoncalves/react-loadable-ssr-addon/stargazers
[forks-image]: https://img.shields.io/github/forks/themgoncalves/react-loadable-ssr-addon.svg
[forks-url]: https://github.com/themgoncalves/react-loadable-ssr-addon/network
[releases-image]: https://img.shields.io/npm/dm/react-loadable-ssr-addon.svg
[releases-url]: https://github.com/themgoncalves/react-loadable-ssr-addon
[awesome-image]: https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg
[awesome-url]: https://github.com/themgoncalves/react-loadable-ssr-addon
[npm-image]: https://img.shields.io/npm/v/react-loadable-ssr-addon.svg
[npm-url]: https://www.npmjs.com/package/react-loadable-ssr-addon


---

# react-router

Declarative routing for [React](https://facebook.github.io/react).

## Installation

Using [npm](https://www.npmjs.com/):

    $ npm install --save react-router

**Note:** This package provides the core routing functionality for React Router, but you might not want to install it directly. If you are writing an application that will run in the browser, you should instead install `react-router-dom`. Similarly, if you are writing a React Native application, you should instead install `react-router-native`. Both of those will install `react-router` as a dependency.

Then with a module bundler like [webpack](https://webpack.github.io/), use as you would anything else:

```js
// using ES6 modules
import { Router, Route, Switch } from "react-router";

// using CommonJS modules
var Router = require("react-router").Router;
var Route = require("react-router").Route;
var Switch = require("react-router").Switch;
```

The UMD build is also available on [unpkg](https://unpkg.com):

```html
<script src="https://unpkg.com/react-router/umd/react-router.min.js"></script>
```

You can find the library on `window.ReactRouter`.

## Issues

If you find a bug, please file an issue on [our issue tracker on GitHub](https://github.com/remix-run/react-router/issues).

## Credits

React Router is built and maintained by [Remix Software](https://remix.run).


---

# React Router Config

Static route configuration helpers for React Router.

This is alpha software, it needs:

1. Realistic server rendering example with data preloading
2. Pending navigation example

## Installation

Using [npm](https://www.npmjs.com/):

    $ npm install --save react-router-config

Then with a module bundler like [webpack](https://webpack.github.io/), use as you would anything else:

```js
// using an ES6 transpiler, like babel
import { matchRoutes, renderRoutes } from "react-router-config";

// not using an ES6 transpiler
var matchRoutes = require("react-router-config").matchRoutes;
```

The UMD build is also available on [unpkg](https://unpkg.com):

```html
<script src="https://unpkg.com/react-router-config/umd/react-router-config.min.js"></script>
```

You can find the library on `window.ReactRouterConfig`

## Motivation

With the introduction of React Router v4, there is no longer a centralized route configuration. There are some use-cases where it is valuable to know about all the app's potential routes such as:

- Loading data on the server or in the lifecycle before rendering the next screen
- Linking to routes by name
- Static analysis

This project seeks to define a shared format for others to build patterns on top of.

## Route Configuration Shape

Routes are objects with the same properties as a `<Route>` with a couple differences:

- the only render prop it accepts is `component` (no `render` or `children`)
- introduces the `routes` key for sub routes
- Consumers are free to add any additional props they'd like to a route, you can access `props.route` inside the `component`, this object is a reference to the object used to render and match.
- accepts `key` prop to prevent remounting component when transition was made from route with the same component and same `key` prop

```js
const routes = [
  {
    component: Root,
    routes: [
      {
        path: "/",
        exact: true,
        component: Home
      },
      {
        path: "/child/:id",
        component: Child,
        routes: [
          {
            path: "/child/:id/grand-child",
            component: GrandChild
          }
        ]
      }
    ]
  }
];
```

**Note**: Just like `<Route>`, relative paths are not (yet) supported. When it is supported there, it will be supported here.

## API

### `matchRoutes(routes, pathname)`

Returns an array of matched routes.

#### Parameters

- routes - the route configuration
- pathname - the [pathname](https://developer.mozilla.org/en-US/docs/Web/API/HTMLHyperlinkElementUtils/pathname) component of the url. This must be a decoded string representing the path.

```js
import { matchRoutes } from "react-router-config";
const branch = matchRoutes(routes, "/child/23");
// using the routes shown earlier, this returns
// [
//   routes[0],
//   routes[0].routes[1]
// ]
```

Each item in the array contains two properties: `routes` and `match`.

- `routes`: A reference to the routes array used to match
- `match`: The match object that also gets passed to `<Route>` render methods.

```js
branch[0].match.url;
branch[0].match.isExact;
// etc.
```

You can use this branch of routes to figure out what is going to be rendered before it actually is rendered. You could do something like this on the server before rendering, or in a lifecycle hook of a component that wraps your entire app

```js
const loadBranchData = (location) => {
  const branch = matchRoutes(routes, location.pathname)

  const promises = branch.map(({ route, match }) => {
    return route.loadData
      ? route.loadData(match)
      : Promise.resolve(null)
  })

  return Promise.all(promises)
}

// useful on the server for preloading data
loadBranchData(req.url).then(data => {
  putTheDataSomewhereTheClientCanFindIt(data)
})

// also useful on the client for "pending navigation" where you
// load up all the data before rendering the next page when
// the url changes

// THIS IS JUST SOME THEORETICAL PSEUDO CODE :)
class PendingNavDataLoader extends Component {
  state = {
    previousLocation: null,
    currentLocation: this.props.location
  }

  static getDerivedStateFromProps(props, state) {
    const currentLocation = props.location
    const previousLocation = state.currentLocation

    const navigated = currentLocation !== previousLocation
    if (navigated) {
      // save the location so we can render the old screen
      return {
        previousLocation,
        currentLocation
      }
    }

    return null
  }

  componentDidUpdate(prevProps) {
    const navigated = prevProps.location !== this.props.location

    if (navigated) {
      // load data while the old screen remains
      loadNextData(routes, this.props.location).then(data => {
        putTheDataSomewhereRoutesCanFindIt(data)
        // clear previousLocation so the next screen renders
        this.setState({
          previousLocation: null
        })
      })
    }
  }

  render() {
    const { children, location } = this.props
    const { previousLocation } = this.state

    // use a controlled <Route> to trick all descendants into
    // rendering the old location
    return (
      <Route
        location={previousLocation || location}
        render={() => children}
      />
    )
  }
}

// wrap in withRouter
export default withRouter(PendingNavDataLoader)

/////////////
// somewhere at the top of your app
import routes from './routes'

<BrowserRouter>
  <PendingNavDataLoader routes={routes}>
    {renderRoutes(routes)}
  </PendingNavDataLoader>
</BrowserRouter>
```

Again, that's all pseudo-code. There are a lot of ways to do server rendering with data and pending navigation and we haven't settled on one. The point here is that `matchRoutes` gives you a chance to match statically outside of the render lifecycle. We'd like to make a demo app of this approach eventually.

### `renderRoutes(routes, extraProps = {}, switchProps = {})`

In order to ensure that matching outside of render with `matchRoutes` and inside of render result in the same branch, you must use `renderRoutes` instead of `<Route>` inside your components. You can render a `<Route>` still, but know that it will not be accounted for in `matchRoutes` outside of render.

```js
import { renderRoutes } from "react-router-config";

const routes = [
  {
    component: Root,
    routes: [
      {
        path: "/",
        exact: true,
        component: Home
      },
      {
        path: "/child/:id",
        component: Child,
        routes: [
          {
            path: "/child/:id/grand-child",
            component: GrandChild
          }
        ]
      }
    ]
  }
];

const Root = ({ route }) => (
  <div>
    <h1>Root</h1>
    {/* child routes won't render without this */}
    {renderRoutes(route.routes)}
  </div>
);

const Home = ({ route }) => (
  <div>
    <h2>Home</h2>
  </div>
);

const Child = ({ route }) => (
  <div>
    <h2>Child</h2>
    {/* child routes won't render without this */}
    {renderRoutes(route.routes, { someProp: "these extra props are optional" })}
  </div>
);

const GrandChild = ({ someProp }) => (
  <div>
    <h3>Grand Child</h3>
    <div>{someProp}</div>
  </div>
);

ReactDOM.render(
  <BrowserRouter>
    {/* kick it all off with the root route */}
    {renderRoutes(routes)}
  </BrowserRouter>,
  document.getElementById("root")
);
```


---

# react-router-dom

DOM bindings for [React Router](https://reactrouter.com).

## Installation

Using [npm](https://www.npmjs.com/):

    $ npm install --save react-router-dom

Then with a module bundler like [webpack](https://webpack.github.io/), use as you would anything else:

```js
// using ES6 modules
import { BrowserRouter, Route, Link } from "react-router-dom";

// using CommonJS modules
const BrowserRouter = require("react-router-dom").BrowserRouter;
const Route = require("react-router-dom").Route;
const Link = require("react-router-dom").Link;
```

The UMD build is also available on [unpkg](https://unpkg.com):

```html
<script src="https://unpkg.com/react-router-dom/umd/react-router-dom.min.js"></script>
```

You can find the library on `window.ReactRouterDOM`.

## Issues

If you find a bug, please file an issue on [our issue tracker on GitHub](https://github.com/remix-run/react-router/issues).

## Credits

React Router is built and maintained by [Remix Software](https://remix.run).


---

# Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

* (a) The contribution was created in whole or in part by me and I
  have the right to submit it under the open source license
  indicated in the file; or

* (b) The contribution is based upon previous work that, to the best
  of my knowledge, is covered under an appropriate open source
  license and I have the right under that license to submit that
  work with modifications, whether created in whole or in part
  by me, under the same open source license (unless I am
  permitted to submit under a different license), as indicated
  in the file; or

* (c) The contribution was provided directly to me by some other
  person who certified (a), (b) or (c) and I have not modified
  it.

* (d) I understand and agree that this project and the contribution
  are public and that a record of the contribution (including all
  personal information I submit with it, including my sign-off) is
  maintained indefinitely and may be redistributed consistent with
  this project or the open source license(s) involved.

## Moderation Policy

The [Node.js Moderation Policy] applies to this WG.

## Code of Conduct

The [Node.js Code of Conduct][] applies to this WG.

[Node.js Code of Conduct]:
https://github.com/nodejs/node/blob/master/CODE_OF_CONDUCT.md
[Node.js Moderation Policy]:
https://github.com/nodejs/TSC/blob/master/Moderation-Policy.md


---

### Streams Working Group

The Node.js Streams is jointly governed by a Working Group
(WG)
that is responsible for high-level guidance of the project.

The WG has final authority over this project including:

* Technical direction
* Project governance and process (including this policy)
* Contribution policy
* GitHub repository hosting
* Conduct guidelines
* Maintaining the list of additional Collaborators

For the current list of WG members, see the project
[README.md](./README.md#current-project-team-members).

### Collaborators

The readable-stream GitHub repository is
maintained by the WG and additional Collaborators who are added by the
WG on an ongoing basis.

Individuals making significant and valuable contributions are made
Collaborators and given commit-access to the project. These
individuals are identified by the WG and their addition as
Collaborators is discussed during the WG meeting.

_Note:_ If you make a significant contribution and are not considered
for commit-access log an issue or contact a WG member directly and it
will be brought up in the next WG meeting.

Modifications of the contents of the readable-stream repository are
made on
a collaborative basis. Anybody with a GitHub account may propose a
modification via pull request and it will be considered by the project
Collaborators. All pull requests must be reviewed and accepted by a
Collaborator with sufficient expertise who is able to take full
responsibility for the change. In the case of pull requests proposed
by an existing Collaborator, an additional Collaborator is required
for sign-off. Consensus should be sought if additional Collaborators
participate and there is disagreement around a particular
modification. See _Consensus Seeking Process_ below for further detail
on the consensus model used for governance.

Collaborators may opt to elevate significant or controversial
modifications, or modifications that have not found consensus to the
WG for discussion by assigning the ***WG-agenda*** tag to a pull
request or issue. The WG should serve as the final arbiter where
required.

For the current list of Collaborators, see the project
[README.md](./README.md#members).

### WG Membership

WG seats are not time-limited.  There is no fixed size of the WG.
However, the expected target is between 6 and 12, to ensure adequate
coverage of important areas of expertise, balanced with the ability to
make decisions efficiently.

There is no specific set of requirements or qualifications for WG
membership beyond these rules.

The WG may add additional members to the WG by unanimous consensus.

A WG member may be removed from the WG by voluntary resignation, or by
unanimous consensus of all other WG members.

Changes to WG membership should be posted in the agenda, and may be
suggested as any other agenda item (see "WG Meetings" below).

If an addition or removal is proposed during a meeting, and the full
WG is not in attendance to participate, then the addition or removal
is added to the agenda for the subsequent meeting.  This is to ensure
that all members are given the opportunity to participate in all
membership decisions.  If a WG member is unable to attend a meeting
where a planned membership decision is being made, then their consent
is assumed.

No more than 1/3 of the WG members may be affiliated with the same
employer.  If removal or resignation of a WG member, or a change of
employment by a WG member, creates a situation where more than 1/3 of
the WG membership shares an employer, then the situation must be
immediately remedied by the resignation or removal of one or more WG
members affiliated with the over-represented employer(s).

### WG Meetings

The WG meets occasionally on a Google Hangout On Air. A designated moderator
approved by the WG runs the meeting. Each meeting should be
published to YouTube.

Items are added to the WG agenda that are considered contentious or
are modifications of governance, contribution policy, WG membership,
or release process.

The intention of the agenda is not to approve or review all patches;
that should happen continuously on GitHub and be handled by the larger
group of Collaborators.

Any community member or contributor can ask that something be added to
the next meeting's agenda by logging a GitHub Issue. Any Collaborator,
WG member or the moderator can add the item to the agenda by adding
the ***WG-agenda*** tag to the issue.

Prior to each WG meeting the moderator will share the Agenda with
members of the WG. WG members can add any items they like to the
agenda at the beginning of each meeting. The moderator and the WG
cannot veto or remove items.

The WG may invite persons or representatives from certain projects to
participate in a non-voting capacity.

The moderator is responsible for summarizing the discussion of each
agenda item and sends it as a pull request after the meeting.

### Consensus Seeking Process

The WG follows a
[Consensus
Seeking](http://en.wikipedia.org/wiki/Consensus-seeking_decision-making)
decision-making model.

When an agenda item has appeared to reach a consensus the moderator
will ask "Does anyone object?" as a final call for dissent from the
consensus.

If an agenda item cannot reach a consensus a WG member can call for
either a closing vote or a vote to table the issue to the next
meeting. The call for a vote must be seconded by a majority of the WG
or else the discussion will continue. Simple majority wins.

Note that changes to WG membership require a majority consensus.  See
"WG Membership" above.


---

# readable-stream

***Node.js core streams for userland*** [![Build Status](https://travis-ci.com/nodejs/readable-stream.svg?branch=master)](https://travis-ci.com/nodejs/readable-stream)


[![NPM](https://nodei.co/npm/readable-stream.png?downloads=true&downloadRank=true)](https://nodei.co/npm/readable-stream/)
[![NPM](https://nodei.co/npm-dl/readable-stream.png?&months=6&height=3)](https://nodei.co/npm/readable-stream/)


[![Sauce Test Status](https://saucelabs.com/browser-matrix/readabe-stream.svg)](https://saucelabs.com/u/readabe-stream)

```bash
npm install --save readable-stream
```

This package is a mirror of the streams implementations in Node.js.

Full documentation may be found on the [Node.js website](https://nodejs.org/dist/v10.18.1/docs/api/stream.html).

If you want to guarantee a stable streams base, regardless of what version of
Node you, or the users of your libraries are using, use **readable-stream** *only* and avoid the *"stream"* module in Node-core, for background see [this blogpost](http://r.va.gg/2014/06/why-i-dont-use-nodes-core-stream-module.html).

As of version 2.0.0 **readable-stream** uses semantic versioning.

## Version 3.x.x

v3.x.x of `readable-stream` is a cut from Node 10. This version supports Node 6, 8, and 10, as well as evergreen browsers, IE 11 and latest Safari. The breaking changes introduced by v3 are composed by the combined breaking changes in [Node v9](https://nodejs.org/en/blog/release/v9.0.0/) and [Node v10](https://nodejs.org/en/blog/release/v10.0.0/), as follows:

1. Error codes: https://github.com/nodejs/node/pull/13310,
   https://github.com/nodejs/node/pull/13291,
   https://github.com/nodejs/node/pull/16589,
   https://github.com/nodejs/node/pull/15042,
   https://github.com/nodejs/node/pull/15665,
   https://github.com/nodejs/readable-stream/pull/344
2. 'readable' have precedence over flowing
   https://github.com/nodejs/node/pull/18994
3. make virtual methods errors consistent
   https://github.com/nodejs/node/pull/18813
4. updated streams error handling
   https://github.com/nodejs/node/pull/18438
5. writable.end should return this.
   https://github.com/nodejs/node/pull/18780
6. readable continues to read when push('')
   https://github.com/nodejs/node/pull/18211
7. add custom inspect to BufferList
   https://github.com/nodejs/node/pull/17907
8. always defer 'readable' with nextTick
   https://github.com/nodejs/node/pull/17979

## Version 2.x.x
v2.x.x of `readable-stream` is a cut of the stream module from Node 8 (there have been no semver-major changes from Node 4 to 8). This version supports all Node.js versions from 0.8, as well as evergreen browsers and IE 10 & 11.

### Big Thanks

Cross-browser Testing Platform and Open Source <3 Provided by [Sauce Labs][sauce]

# Usage

You can swap your `require('stream')` with `require('readable-stream')`
without any changes, if you are just using one of the main classes and
functions.

```js
const {
  Readable,
  Writable,
  Transform,
  Duplex,
  pipeline,
  finished
} = require('readable-stream')
````

Note that `require('stream')` will return `Stream`, while
`require('readable-stream')` will return `Readable`. We discourage using
whatever is exported directly, but rather use one of the properties as
shown in the example above.

# Streams Working Group

`readable-stream` is maintained by the Streams Working Group, which
oversees the development and maintenance of the Streams API within
Node.js. The responsibilities of the Streams Working Group include:

* Addressing stream issues on the Node.js issue tracker.
* Authoring and editing stream documentation within the Node.js project.
* Reviewing changes to stream subclasses within the Node.js project.
* Redirecting changes to streams from the Node.js project to this
  project.
* Assisting in the implementation of stream providers within Node.js.
* Recommending versions of `readable-stream` to be included in Node.js.
* Messaging about the future of streams to give the community advance
  notice of changes.

<a name="members"></a>
## Team Members

* **Calvin Metcalf** ([@calvinmetcalf](https://github.com/calvinmetcalf)) &lt;calvin.metcalf@gmail.com&gt;
  - Release GPG key: F3EF5F62A87FC27A22E643F714CE4FF5015AA242
* **Mathias Buus** ([@mafintosh](https://github.com/mafintosh)) &lt;mathiasbuus@gmail.com&gt;
* **Matteo Collina** ([@mcollina](https://github.com/mcollina)) &lt;matteo.collina@gmail.com&gt;
  - Release GPG key: 3ABC01543F22DD2239285CDD818674489FBC127E
* **Irina Shestak** ([@lrlna](https://github.com/lrlna)) &lt;shestak.irina@gmail.com&gt;
* **Yoshua Wyuts** ([@yoshuawuyts](https://github.com/yoshuawuyts)) &lt;yoshuawuyts@gmail.com&gt;

[sauce]: https://saucelabs.com


---

# readdirp [![Weekly downloads](https://img.shields.io/npm/dw/readdirp.svg)](https://github.com/paulmillr/readdirp)

Recursive version of [fs.readdir](https://nodejs.org/api/fs.html#fs_fs_readdir_path_options_callback). Exposes a **stream API** and a **promise API**.


```sh
npm install readdirp
```

```javascript
const readdirp = require('readdirp');

// Use streams to achieve small RAM & CPU footprint.
// 1) Streams example with for-await.
for await (const entry of readdirp('.')) {
  const {path} = entry;
  console.log(`${JSON.stringify({path})}`);
}

// 2) Streams example, non for-await.
// Print out all JS files along with their size within the current folder & subfolders.
readdirp('.', {fileFilter: '*.js', alwaysStat: true})
  .on('data', (entry) => {
    const {path, stats: {size}} = entry;
    console.log(`${JSON.stringify({path, size})}`);
  })
  // Optionally call stream.destroy() in `warn()` in order to abort and cause 'close' to be emitted
  .on('warn', error => console.error('non-fatal error', error))
  .on('error', error => console.error('fatal error', error))
  .on('end', () => console.log('done'));

// 3) Promise example. More RAM and CPU than streams / for-await.
const files = await readdirp.promise('.');
console.log(files.map(file => file.path));

// Other options.
readdirp('test', {
  fileFilter: '*.js',
  directoryFilter: ['!.git', '!*modules']
  // directoryFilter: (di) => di.basename.length === 9
  type: 'files_directories',
  depth: 1
});
```

For more examples, check out `examples` directory.

## API

`const stream = readdirp(root[, options])` — **Stream API**

- Reads given root recursively and returns a `stream` of [entry infos](#entryinfo)
- Optionally can be used like `for await (const entry of stream)` with node.js 10+ (`asyncIterator`).
- `on('data', (entry) => {})` [entry info](#entryinfo) for every file / dir.
- `on('warn', (error) => {})` non-fatal `Error` that prevents a file / dir from being processed. Example: inaccessible to the user.
- `on('error', (error) => {})` fatal `Error` which also ends the stream. Example: illegal options where passed.
- `on('end')` — we are done. Called when all entries were found and no more will be emitted.
- `on('close')` — stream is destroyed via `stream.destroy()`.
  Could be useful if you want to manually abort even on a non fatal error.
  At that point the stream is no longer `readable` and no more entries, warning or errors are emitted
- To learn more about streams, consult the very detailed [nodejs streams documentation](https://nodejs.org/api/stream.html)
  or the [stream-handbook](https://github.com/substack/stream-handbook)

`const entries = await readdirp.promise(root[, options])` — **Promise API**. Returns a list of [entry infos](#entryinfo).

First argument is awalys `root`, path in which to start reading and recursing into subdirectories.

### options

- `fileFilter: ["*.js"]`: filter to include or exclude files. A `Function`, Glob string or Array of glob strings.
    - **Function**: a function that takes an entry info as a parameter and returns true to include or false to exclude the entry
    - **Glob string**: a string (e.g., `*.js`) which is matched using [picomatch](https://github.com/micromatch/picomatch), so go there for more
        information. Globstars (`**`) are not supported since specifying a recursive pattern for an already recursive function doesn't make sense. Negated globs (as explained in the minimatch documentation) are allowed, e.g., `!*.txt` matches everything but text files.
    - **Array of glob strings**: either need to be all inclusive or all exclusive (negated) patterns otherwise an error is thrown.
        `['*.json', '*.js']` includes all JavaScript and Json files.
        `['!.git', '!node_modules']` includes all directories except the '.git' and 'node_modules'.
    - Directories that do not pass a filter will not be recursed into.
- `directoryFilter: ['!.git']`: filter to include/exclude directories found and to recurse into. Directories that do not pass a filter will not be recursed into.
- `depth: 5`: depth at which to stop recursing even if more subdirectories are found
- `type: 'files'`: determines if data events on the stream should be emitted for `'files'` (default), `'directories'`, `'files_directories'`, or `'all'`. Setting to `'all'` will also include entries for other types of file descriptors like character devices, unix sockets and named pipes.
- `alwaysStat: false`: always return `stats` property for every file. Default is `false`, readdirp will return `Dirent` entries. Setting it to `true` can double readdir execution time - use it only when you need file `size`, `mtime` etc. Cannot be enabled on node <10.10.0.
- `lstat: false`: include symlink entries in the stream along with files. When `true`, `fs.lstat` would be used instead of `fs.stat`

### `EntryInfo`

Has the following properties:

- `path: 'assets/javascripts/react.js'`: path to the file/directory (relative to given root)
- `fullPath: '/Users/dev/projects/app/assets/javascripts/react.js'`: full path to the file/directory found
- `basename: 'react.js'`: name of the file/directory
- `dirent: fs.Dirent`: built-in [dir entry object](https://nodejs.org/api/fs.html#fs_class_fs_dirent) - only with `alwaysStat: false`
- `stats: fs.Stats`: built in [stat object](https://nodejs.org/api/fs.html#fs_class_fs_stats) - only with `alwaysStat: true`

## Changelog

- 3.5 (Oct 13, 2020) disallows recursive directory-based symlinks.
  Before, it could have entered infinite loop.
- 3.4 (Mar 19, 2020) adds support for directory-based symlinks.
- 3.3 (Dec 6, 2019) stabilizes RAM consumption and enables perf management with `highWaterMark` option. Fixes race conditions related to `for-await` looping.
- 3.2 (Oct 14, 2019) improves performance by 250% and makes streams implementation more idiomatic.
- 3.1 (Jul 7, 2019) brings `bigint` support to `stat` output on Windows. This is backwards-incompatible for some cases. Be careful. It you use it incorrectly, you'll see "TypeError: Cannot mix BigInt and other types, use explicit conversions".
- 3.0 brings huge performance improvements and stream backpressure support.
- Upgrading 2.x to 3.x:
    - Signature changed from `readdirp(options)` to `readdirp(root, options)`
    - Replaced callback API with promise API.
    - Renamed `entryType` option to `type`
    - Renamed `entryType: 'both'` to `'files_directories'`
    - `EntryInfo`
        - Renamed `stat` to `stats`
            - Emitted only when `alwaysStat: true`
            - `dirent` is emitted instead of `stats` by default with `alwaysStat: false`
        - Renamed `name` to `basename`
        - Removed `parentDir` and `fullParentDir` properties
- Supported node.js versions:
    - 3.x: node 8+
    - 2.x: node 0.6+

## License

Copyright (c) 2012-2019 Thorsten Lorenz, Paul Miller (<https://paulmillr.com>)

MIT License, see [LICENSE](LICENSE) file.


---

# reading-time

[![NPM](http://img.shields.io/npm/v/reading-time.svg)](https://www.npmjs.org/package/reading-time) [![Build Status](http://img.shields.io/travis/ngryman/reading-time.svg)](https://travis-ci.org/ngryman/reading-time)

<br>

[Medium]'s like reading time estimation.

`reading-time` helps you estimate how long an article will take to read.
It works perfectly with plain text, but also with `markdown` or `html`.

Note that it's focused on performance and simplicity, so the number of words it will extract from other formats than plain text can vary a little. But this is an estimation right?

[medium]: https://medium.com

## Installation

```sh
npm install reading-time --production
```

## Usage

### Classic

```javascript
const readingTime = require('reading-time');

const stats = readingTime(text);
// ->
// stats: {
//   text: '1 min read',
//   minutes: 1,
//   time: 60000,
//   words: 200
// }
```

### Stream

```javascript
const {readingTimeStream} = require('reading-time');

fs.createReadStream('foo')
  .pipe(readingTimeStream)
  .on('data', stats => {
    // ...
  });
```

## API

`readingTime(text, options?)`

- `text`: the text to analyze
- options (optional)
  - `options.wordsPerMinute`: (optional) the words per minute an average reader can read (default: 200)
  - `options.wordBound`: (optional) a function that returns a boolean value depending on if a character is considered as a word bound (default: spaces, new lines and tabulations)

## Help wanted!

This library has been optimized for alphabetical languages and CJK languages, but may not behave correctly for other languages that don't use spaces for work bounds. If you find the behavior of this library to deviate significantly from your expectation, issues or contributions are welcomed!

## Other projects

- [Fauda](https://github.com/ngryman/fauda): configuration made simple.
- [Badge Size](https://github.com/ngryman/badge-size): Displays the size of a given file in your repository.
- [Commitizen Emoji](https://github.com/ngryman/cz-emoji): Commitizen adapter formatting commit messages using emojis.


---

# rechoir [![Build Status](https://secure.travis-ci.org/tkellen/js-rechoir.png)](http://travis-ci.org/tkellen/js-rechoir)
> Require any supported file as a node module.

[![NPM](https://nodei.co/npm/rechoir.png)](https://nodei.co/npm/rechoir/)

## What is it?
This module, in conjunction with [interpret]-like objects can register any file type the npm ecosystem has a module loader for. This library is a dependency of [Liftoff].

## API

### prepare(config, filepath, requireFrom)
Look for a module loader associated with the provided file and attempt require it.  If necessary, run any setup required to inject it into [require.extensions](http://nodejs.org/api/globals.html#globals_require_extensions).

`config` An [interpret]-like configuration object.  

`filepath` A file whose type you'd like to register a module loader for.

`requireFrom` An optional path to start searching for the module required to load the requested file.  Defaults to the directory of `filepath`.

If calling this method is successful (aka: it doesn't throw), you can now require files of the type you requested natively.

An error with a `failures` property will be thrown if the module loader(s) configured for a given extension cannot be registered.

If a loader is already registered, this will simply return `true`.

**Note:** While rechoir will automatically load and register transpilers like `coffee-script`, you must provide a local installation. The transpilers are **not** bundled with this module.

#### Usage
```js
const config = require('interpret').extensions;
const rechoir = require('rechoir');
rechoir.prepare(config, './test/fixtures/test.coffee');
rechoir.prepare(config, './test/fixtures/test.csv');
rechoir.prepare(config, './test/fixtures/test.toml');

console.log(require('./test/fixtures/test.coffee'));
console.log(require('./test/fixtures/test.csv'));
console.log(require('./test/fixtures/test.toml'));
```

[interpret]: http://github.com/tkellen/js-interpret
[Liftoff]: http://github.com/tkellen/js-liftoff


---

# recma-build-jsx

[![Build][badge-build-image]][badge-build-url]
[![Coverage][badge-coverage-image]][badge-coverage-url]
[![Downloads][badge-downloads-image]][badge-downloads-url]
[![Size][badge-size-image]][badge-size-url]
[![Sponsors][badge-sponsors-image]][badge-collective-url]
[![Backers][badge-backers-image]][badge-collective-url]
[![Chat][badge-chat-image]][badge-chat-url]

**[recma][github-recma]** plugin to add support for turning JSX (`<x />`)
into JavaScript (`React.createElement('x', {})` or `_jsx('x', {})`).

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`unified().use(recmaBuildJsx[, options])`](#unifieduserecmabuildjsx-options)
  * [`Options`](#options)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package is a [unified][github-unified]
([recma][github-recma])
that can turn JSX into JavaScript.

## When should I use this?

Use this when preparing JSX for evaluation.
JSX cannot be evaluated without being transformed first.

If you don’t use plugins and access syntax trees manually,
you can directly use [`estree-util-build-jsx`][github-estree-util-build-jsx],
which is used inside this plugin.
recma focusses on making it easier to transform code by abstracting such
internals away.

## Install

This package is [ESM only][github-gist-esm].
In Node.js (version 16+),
install with [npm][npm-install]:

```sh
npm install recma-build-jsx
```

In Deno with [`esm.sh`][esmsh]:

```js
import recmaBuildJsx from 'https://esm.sh/recma-build-jsx@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import recmaBuildJsx from 'https://esm.sh/recma-build-jsx@1?bundle'
</script>
```

## Use

Say we have the following module `example.js`:

```js
import recmaBuildJsx from 'recma-build-jsx'
import recmaJsx from 'recma-jsx'
import recmaParse from 'recma-parse'
import recmaStringify from 'recma-stringify'
import {unified} from 'unified'

const file = await unified()
  .use(recmaParse)
  .use(recmaJsx)
  .use(recmaBuildJsx)
  .use(recmaStringify)
  .process('console.log(<em>Hi!</em>)')

console.log(String(file))
```

…running that with `node example.js` yields:

```js
console.log(React.createElement("em", null, "Hi!"));
```

## API

This package exports no identifiers.
The default export is [`recmaBuildJsx`][api-recma-build-jsx].

### `unified().use(recmaBuildJsx[, options])`

Plugin to build JSX.

###### Parameters

* `options` ([`Options`][api-options], optional)
  — configuration

###### Returns

Transform ([`Transformer`][github-unified-transformer]).

### `Options`

Configuration (TypeScript type).

Same as [`Options`][github-estree-util-build-jsx-options]
from `estree-util-build-jsx`.
Passing `filePath` is not supported as it is handled for you.

## Types

This package is fully typed with [TypeScript][].
It exports the additional type [`Options`][api-options].

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release,
we drop support for unmaintained versions of Node.
This means we try to keep the current release line,
`recma-build-jsx@1`,
compatible with Node.js 16.

## Security

As **recma** works on JS and evaluating JS is unsafe,
use of recma can also be unsafe.
Do not evaluate unsafe code.

## Contribute

See [§ Contribute][mdxjs-contribute] on our site for ways to get started.
See [§ Support][mdxjs-support] for ways to get help.

This project has a [code of conduct][health-coc].
By interacting with this repository,
organization,
or community you agree to abide by its terms.

## License

[MIT][file-license] © [Titus Wormer][wooorm]

<!-- Definitions -->

[api-options]: #options

[api-recma-build-jsx]: #unifieduserecmabuildjsx-options

[badge-backers-image]: https://opencollective.com/unified/backers/badge.svg

[badge-build-image]: https://github.com/mdx-js/recma/actions/workflows/main.yml/badge.svg

[badge-build-url]: https://github.com/mdx-js/recma/actions

[badge-collective-url]: https://opencollective.com/unified

[badge-coverage-image]: https://img.shields.io/codecov/c/github/mdx-js/recma.svg

[badge-coverage-url]: https://codecov.io/github/mdx-js/recma

[badge-downloads-image]: https://img.shields.io/npm/dm/recma-build-jsx.svg

[badge-downloads-url]: https://www.npmjs.com/package/recma-build-jsx

[badge-size-image]: https://img.shields.io/bundlejs/size/recma-build-jsx

[badge-size-url]: https://bundlejs.com/?q=recma-build-jsx

[badge-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg

[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg

[badge-chat-url]: https://github.com/mdx-js/mdx/discussions

[esmsh]: https://esm.sh

[file-license]: license

[github-estree-util-build-jsx-options]: https://github.com/syntax-tree/estree-util-build-jsx#options

[github-estree-util-build-jsx]: https://github.com/syntax-tree/estree-util-build-jsx

[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[github-recma]: https://github.com/mdx-js/recma

[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer

[github-unified]: https://github.com/unifiedjs/unified

[health-coc]: https://github.com/mdx-js/.github/blob/main/code-of-conduct.md

[mdxjs-contribute]: https://mdxjs.com/community/contribute/

[mdxjs-support]: https://mdxjs.com/community/support/

[npm-install]: https://docs.npmjs.com/cli/install

[typescript]: https://www.typescriptlang.org

[wooorm]: https://wooorm.com


---

# recma-jsx

[![Build][badge-build-image]][badge-build-url]
[![Coverage][badge-coverage-image]][badge-coverage-url]
[![Downloads][badge-downloads-image]][badge-downloads-url]
[![Size][badge-size-image]][badge-size-url]
[![Sponsors][badge-sponsors-image]][badge-collective-url]
[![Backers][badge-backers-image]][badge-collective-url]
[![Chat][badge-chat-image]][badge-chat-url]

**[recma][github-recma]** plugin to add support for parsing and serializing
[JSX][github-io-jsx].

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`unified().use(recmaJsx)`](#unifieduserecmajsx)
* [Syntax](#syntax)
* [Syntax tree](#syntax-tree)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package is a [unified][github-unified]
([recma][github-recma])
that enables JSX.
You can use this plugin to add support for parsing and serializing it.

## When should I use this?

You can use this if you want to use `recma` and JSX.
You can also use [`acorn-jsx`][github-acorn-jsx] manually with
[`acorn`][github-acorn] for parsing.
And use the [`jsx`][github-estree-util-to-js-jsx] handlers from
[`estree-util-to-js`][github-estree-util-to-js] manually.

## Install

This package is [ESM only][github-gist-esm].
In Node.js (version 16+),
install with [npm][npm-install]:

```sh
npm install recma-jsx
```

In Deno with [`esm.sh`][esmsh]:

```js
import recmaJsx from 'https://esm.sh/recma-jsx@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import recmaJsx from 'https://esm.sh/recma-jsx@1?bundle'
</script>
```

## Use

Say we have the following module `example.js`:

```js
import recmaJsx from 'recma-jsx'
import recmaParse from 'recma-parse'
import recmaStringify from 'recma-stringify'
import {unified} from 'unified'

const file = await unified()
  .use(recmaParse)
  .use(recmaJsx)
  .use(recmaStringify)
  .process('console.log(<em>Hi!</em>)')

console.log(String(file))
```

…running that with `node example.js` yields:

```jsx
console.log(<em>Hi!</em>);
```

## API

This package exports no identifiers.
The default export is [`recmaJsx`][api-recma-jsx].

### `unified().use(recmaJsx)`

Plugin to add support for parsing and serializing JSX.

###### Parameters

There are no parameters.

###### Returns

Nothing (`undefined`).

## Syntax

JSX is parsed and serialized according to [`facebook/jsx`][github-io-jsx].

## Syntax tree

The syntax tree format used in recma is [esast][github-esast] and
[estree][github-estree].

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release,
we drop support for unmaintained versions of Node.
This means we try to keep the current release line,
`recma-jsx@1`,
compatible with Node.js 16.

## Security

As **recma** works on JS and evaluating JS is unsafe,
use of recma can also be unsafe.
Do not evaluate unsafe code.

## Contribute

See [§ Contribute][mdxjs-contribute] on our site for ways to get started.
See [§ Support][mdxjs-support] for ways to get help.

This project has a [code of conduct][health-coc].
By interacting with this repository,
organization,
or community you agree to abide by its terms.

## License

[MIT][file-license] © [Titus Wormer][wooorm]

<!-- Definitions -->

[api-recma-jsx]: #unifieduserecmajsx

[badge-backers-image]: https://opencollective.com/unified/backers/badge.svg

[badge-build-image]: https://github.com/mdx-js/recma/actions/workflows/main.yml/badge.svg

[badge-build-url]: https://github.com/mdx-js/recma/actions

[badge-collective-url]: https://opencollective.com/unified

[badge-coverage-image]: https://img.shields.io/codecov/c/github/mdx-js/recma.svg

[badge-coverage-url]: https://codecov.io/github/mdx-js/recma

[badge-downloads-image]: https://img.shields.io/npm/dm/recma-jsx.svg

[badge-downloads-url]: https://www.npmjs.com/package/recma-jsx

[badge-size-image]: https://img.shields.io/bundlejs/size/recma-jsx

[badge-size-url]: https://bundlejs.com/?q=recma-jsx

[badge-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg

[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg

[badge-chat-url]: https://github.com/mdx-js/mdx/discussions

[esmsh]: https://esm.sh

[file-license]: license

[github-acorn-jsx]: https://github.com/acornjs/acorn-jsx

[github-acorn]: https://github.com/acornjs/acorn

[github-esast]: https://github.com/syntax-tree/esast

[github-estree-util-to-js]: https://github.com/syntax-tree/estree-util-to-js

[github-estree-util-to-js-jsx]: https://github.com/syntax-tree/estree-util-to-js#jsx

[github-estree]: https://github.com/estree/estree

[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[github-io-jsx]: http://facebook.github.io/jsx/

[github-recma]: https://github.com/mdx-js/recma

[github-unified]: https://github.com/unifiedjs/unified

[health-coc]: https://github.com/mdx-js/.github/blob/main/code-of-conduct.md

[mdxjs-contribute]: https://mdxjs.com/community/contribute/

[mdxjs-support]: https://mdxjs.com/community/support/

[npm-install]: https://docs.npmjs.com/cli/install

[typescript]: https://www.typescriptlang.org

[wooorm]: https://wooorm.com


---

# recma-parse

[![Build][badge-build-image]][badge-build-url]
[![Coverage][badge-coverage-image]][badge-coverage-url]
[![Downloads][badge-downloads-image]][badge-downloads-url]
[![Size][badge-size-image]][badge-size-url]
[![Sponsors][badge-sponsors-image]][badge-collective-url]
[![Backers][badge-backers-image]][badge-collective-url]
[![Chat][badge-chat-image]][badge-chat-url]

**[recma][github-recma]** plugin to add support for parsing JavaScript.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`unified().use(recmaParse[, options])`](#unifieduserecmaparse-options)
  * [`Options`](#options)
* [Syntax](#syntax)
* [Syntax tree](#syntax-tree)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package is a [unified][github-unified] ([recma][github-recma]) plugin that
defines how to take JavaScript as input and turn it into a syntax tree.
When it’s used,
JavaScript can be parsed and other recma plugins can be used.

See [the monorepo readme][github-recma] for info on what the recma ecosystem is.

## When should I use this?

This plugin adds support to unified for parsing JavaScript.
If you also need to serialize JavaScript,
you can alternatively use [`recma`][github-recma-core],
which combines unified,
this plugin,
and [`recma-stringify`][github-recma-stringify].

If you don’t use plugins and want to access the syntax tree,
you can directly use [`esast-util-from-js`][github-esast-util-from-js],
which is used inside this plugin.
recma focusses on making it easier to transform code by abstracting such
internals away.

## Install

This package is [ESM only][github-gist-esm].
In Node.js (version 16+),
install with [npm][npm-install]:

```sh
npm install recma-parse
```

In Deno with [`esm.sh`][esmsh]:

```js
import recmaParse from 'https://esm.sh/recma-parse@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import recmaParse from 'https://esm.sh/recma-parse@1?bundle'
</script>
```

## Use

Say we have the following module `example.js`:

```js
import recmaBuildJsx from 'recma-build-jsx'
import recmaJsx from 'recma-jsx'
import recmaParse from 'recma-parse'
import recmaStringify from 'recma-stringify'
import {unified} from 'unified'

const file = await unified()
  .use(recmaParse)
  .use(recmaJsx)
  .use(recmaBuildJsx)
  .use(recmaStringify)
  .process('console.log(<em>Hi!</em>)')

console.log(String(file))
```

…running that with `node example.js` yields:

```js
console.log(React.createElement("em", null, "Hi!"));
```

## API

This package exports no identifiers.
The default export is [`recmaParse`][api-recma-parse].

### `unified().use(recmaParse[, options])`

Plugin to add support for parsing from JavaScript.

###### Parameters

* `options` ([`Options`][api-options], optional)
  — configuration

###### Returns

Nothing (`undefined`).

### `Options`

Configuration (TypeScript type).

Same as [`Options`][github-esast-util-from-js-options]
from [`esast-util-from-js`][github-esast-util-from-js].

## Syntax

JS is parsed according to [ECMA-262][tc39-ecma-262],
which is also followed by all browsers and engines such as Node.js.

## Syntax tree

The syntax tree format used in recma is [esast][github-esast] and
[estree][github-estree].

## Types

This package is fully typed with [TypeScript][].
It exports the additional type
[`Options`][api-options].

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release,
we drop support for unmaintained versions of Node.
This means we try to keep the current release line,
`recma-parse@1`,
compatible with Node.js 16.

## Security

As **recma** works on JS and evaluating JS is unsafe,
use of recma can also be unsafe.
Do not evaluate unsafe code.

Use of recma plugins could also open you up to other attacks.
Carefully assess each plugin and the risks involved in using them.

For info on how to submit a report, see our [security policy][health-security].

## Contribute

See [§ Contribute][mdxjs-contribute] on our site for ways to get started.
See [§ Support][mdxjs-support] for ways to get help.

This project has a [code of conduct][health-coc].
By interacting with this repository,
organization,
or community you agree to abide by its terms.

## License

[MIT][file-license] © [Titus Wormer][wooorm]

<!-- Definitions -->

[api-options]: #options

[api-recma-parse]: #unifieduserecmaparse-options

[badge-backers-image]: https://opencollective.com/unified/backers/badge.svg

[badge-build-image]: https://github.com/mdx-js/recma/actions/workflows/main.yml/badge.svg

[badge-build-url]: https://github.com/mdx-js/recma/actions

[badge-collective-url]: https://opencollective.com/unified

[badge-coverage-image]: https://img.shields.io/codecov/c/github/mdx-js/recma.svg

[badge-coverage-url]: https://codecov.io/github/mdx-js/recma

[badge-downloads-image]: https://img.shields.io/npm/dm/recma-parse.svg

[badge-downloads-url]: https://www.npmjs.com/package/recma-parse

[badge-size-image]: https://img.shields.io/bundlejs/size/recma-parse

[badge-size-url]: https://bundlejs.com/?q=recma-parse

[badge-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg

[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg

[badge-chat-url]: https://github.com/mdx-js/mdx/discussions

[esmsh]: https://esm.sh

[file-license]: license

[github-esast]: https://github.com/syntax-tree/esast

[github-esast-util-from-js]: https://github.com/syntax-tree/esast-util-from-js

[github-esast-util-from-js-options]: https://github.com/syntax-tree/esast-util-from-js#options

[github-estree]: https://github.com/estree/estree

[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[github-recma-core]: https://github.com/mdx-js/recma/tree/main/packages/recma

[github-recma-stringify]: https://github.com/mdx-js/recma/tree/main/packages/recma-stringify

[github-recma]: https://github.com/mdx-js/recma

[github-unified]: https://github.com/unifiedjs/unified

[health-coc]: https://github.com/mdx-js/.github/blob/main/code-of-conduct.md

[health-security]: https://github.com/mdx-js/.github/blob/main/security.md

[mdxjs-contribute]: https://mdxjs.com/community/contribute/

[mdxjs-support]: https://mdxjs.com/community/support/

[npm-install]: https://docs.npmjs.com/cli/install

[tc39-ecma-262]: https://tc39.es/ecma262/multipage/

[typescript]: https://www.typescriptlang.org

[wooorm]: https://wooorm.com


---

# recma-stringify

[![Build][badge-build-image]][badge-build-url]
[![Coverage][badge-coverage-image]][badge-coverage-url]
[![Downloads][badge-downloads-image]][badge-downloads-url]
[![Size][badge-size-image]][badge-size-url]
[![Sponsors][badge-sponsors-image]][badge-collective-url]
[![Backers][badge-backers-image]][badge-collective-url]
[![Chat][badge-chat-image]][badge-chat-url]

**[recma][github-recma]** plugin to add support for serializing JavaScript.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`unified().use(recmaStringify[, options])`](#unifieduserecmastringify-options)
  * [`Options`](#options)
* [Syntax](#syntax)
* [Syntax tree](#syntax-tree)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package is a [unified][github-unified] ([recma][github-recma]) plugin that
defines how to take a syntax tree as input and turn it into JavaScript.
When it’s used,
JavaScript is serialized as the final result.

See [the monorepo readme][github-recma] for info on what the recma ecosystem is.

## When should I use this?

This plugin adds support to unified for serializing JavaScript.
If you also need to parse JavaScript,
you can alternatively use [`recma`][github-recma-core],
which combines unified,
this plugin,
and [`recma-parse`][github-recma-parse].

If you don’t use plugins and have access to the syntax tree,
you can directly use [`estree-util-to-js`][github-estree-util-to-js],
which is used inside this plugin.
recma focusses on making it easier to transform code by abstracting such
internals away.

## Install

This package is [ESM only][github-gist-esm].
In Node.js (version 16+),
install with [npm][npm-install]:

```sh
npm install recma-stringify
```

In Deno with [`esm.sh`][esmsh]:

```js
import recmaStringify from 'https://esm.sh/recma-stringify@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import recmaStringify from 'https://esm.sh/recma-stringify@1?bundle'
</script>
```

## Use

Say we have the following module `example.js`:

```js
import recmaJsx from 'recma-jsx'
import recmaStringify from 'recma-stringify'
import rehypeParse from 'rehype-parse'
import rehypeRecma from 'rehype-recma'
import {unified} from 'unified'

const file = await unified()
  .use(rehypeParse, {fragment: true})
  .use(rehypeRecma)
  .use(recmaJsx)
  .use(recmaStringify)
  .process('<p>Hi!<h1>Hello!')

console.log(String(file))
```

…running that with `node example.js` yields:

```jsx
<><p>{"Hi!"}</p><h1>{"Hello!"}</h1></>;
```

## API

This package exports no identifiers.
The default export is [`recmaStringify`][api-recma-stringify].

### `unified().use(recmaStringify[, options])`

Plugin to add support for serializing to JavaScript.

###### Parameters

* `options` ([`Options`][api-options], optional)
  — configuration

###### Returns

Nothing (`undefined`).

### `Options`

Configuration (TypeScript type).

Same as [`Options`][github-estree-util-to-js-options]
from [`estree-util-to-js`][github-estree-util-to-js].
Passing `filePath` is not supported as it is handled for you.

## Syntax

JS is serialized according to [ECMA-262][tc39-ecma-262],
which is also followed by all browsers and engines such as Node.js.

## Syntax tree

The syntax tree format used in recma is [esast][github-esast] and
[estree][github-estree].

## Types

This package is fully typed with [TypeScript][].
It exports the additional type
[`Options`][api-options].

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release,
we drop support for unmaintained versions of Node.
This means we try to keep the current release line,
`recma-strignify@1`,
compatible with Node.js 16.

## Security

As **recma** works on JS and evaluating JS is unsafe,
use of recma can also be unsafe.
Do not evaluate unsafe code.

Use of recma plugins could also open you up to other attacks.
Carefully assess each plugin and the risks involved in using them.

For info on how to submit a report, see our [security policy][health-security].

## Contribute

See [§ Contribute][mdxjs-contribute] on our site for ways to get started.
See [§ Support][mdxjs-support] for ways to get help.

This project has a [code of conduct][health-coc].
By interacting with this repository,
organization,
or community you agree to abide by its terms.

## License

[MIT][file-license] © [Titus Wormer][wooorm]

<!-- Definitions -->

[api-options]: #options

[api-recma-stringify]: #unifieduserecmastringify-options

[badge-backers-image]: https://opencollective.com/unified/backers/badge.svg

[badge-build-image]: https://github.com/mdx-js/recma/actions/workflows/main.yml/badge.svg

[badge-build-url]: https://github.com/mdx-js/recma/actions

[badge-collective-url]: https://opencollective.com/unified

[badge-coverage-image]: https://img.shields.io/codecov/c/github/mdx-js/recma.svg

[badge-coverage-url]: https://codecov.io/github/mdx-js/recma

[badge-downloads-image]: https://img.shields.io/npm/dm/recma-stringify.svg

[badge-downloads-url]: https://www.npmjs.com/package/recma-stringify

[badge-size-image]: https://img.shields.io/bundlejs/size/recma-stringify

[badge-size-url]: https://bundlejs.com/?q=recma-stringify

[badge-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg

[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg

[badge-chat-url]: https://github.com/mdx-js/mdx/discussions

[esmsh]: https://esm.sh

[file-license]: license

[github-esast]: https://github.com/syntax-tree/esast

[github-estree-util-to-js]: https://github.com/syntax-tree/estree-util-to-js

[github-estree-util-to-js-options]: https://github.com/syntax-tree/estree-util-to-js#options

[github-estree]: https://github.com/estree/estree

[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[github-recma-core]: https://github.com/mdx-js/recma/tree/main/packages/recma

[github-recma-parse]: https://github.com/mdx-js/recma/tree/main/packages/recma-parse

[github-recma]: https://github.com/mdx-js/recma

[github-unified]: https://github.com/unifiedjs/unified

[health-coc]: https://github.com/mdx-js/.github/blob/main/code-of-conduct.md

[health-security]: https://github.com/mdx-js/.github/blob/main/security.md

[mdxjs-contribute]: https://mdxjs.com/community/contribute/

[mdxjs-support]: https://mdxjs.com/community/support/

[npm-install]: https://docs.npmjs.com/cli/install

[tc39-ecma-262]: https://tc39.es/ecma262/multipage/

[typescript]: https://www.typescriptlang.org

[wooorm]: https://wooorm.com


---

# recursive-readdir

[![Build Status](https://travis-ci.org/jergason/recursive-readdir.svg?branch=master)](https://travis-ci.org/jergason/recursive-readdir)

Recursively list all files in a directory and its subdirectories. It does not list the directories themselves.

Because it uses fs.readdir, which calls [readdir](http://linux.die.net/man/3/readdir) under the hood
on OS X and Linux, the order of files inside directories is [not guaranteed](http://stackoverflow.com/questions/8977441/does-readdir-guarantee-an-order).

## Installation

    npm install recursive-readdir

## Usage

```javascript
var recursive = require("recursive-readdir");

recursive("some/path", function (err, files) {
  // `files` is an array of file paths
  console.log(files);
});
```

It can also take a list of files to ignore.

```javascript
var recursive = require("recursive-readdir");

// ignore files named "foo.cs" or files that end in ".html".
recursive("some/path", ["foo.cs", "*.html"], function (err, files) {
  console.log(files);
});
```

You can also pass functions which are called to determine whether or not to
ignore a file:

```javascript
var recursive = require("recursive-readdir");

function ignoreFunc(file, stats) {
  // `file` is the path to the file, and `stats` is an `fs.Stats`
  // object returned from `fs.lstat()`.
  return stats.isDirectory() && path.basename(file) == "test";
}

// Ignore files named "foo.cs" and descendants of directories named test
recursive("some/path", ["foo.cs", ignoreFunc], function (err, files) {
  console.log(files);
});
```

## Promises
You can omit the callback and return a promise instead.

```javascript
var recursive = require("recursive-readdir");

recursive("some/path").then(
  function(files) {
    console.log("files are", files);
  },
  function(error) {
    console.error("something exploded", error);
  }
);
```

The ignore strings support Glob syntax via
[minimatch](https://github.com/isaacs/minimatch).


---

# Regenerate [![Build status](https://travis-ci.org/mathiasbynens/regenerate.svg?branch=master)](https://travis-ci.org/mathiasbynens/regenerate) [![Code coverage status](https://img.shields.io/codecov/c/github/mathiasbynens/regenerate.svg)](https://codecov.io/gh/mathiasbynens/regenerate)

_Regenerate_ is a Unicode-aware regex generator for JavaScript. It allows you to easily generate ES5-compatible regular expressions based on a given set of Unicode symbols or code points. (This is trickier than you might think, because of [how JavaScript deals with astral symbols](https://mathiasbynens.be/notes/javascript-unicode).)

## Installation

Via [npm](https://npmjs.org/):

```bash
npm install regenerate
```

Via [Bower](http://bower.io/):

```bash
bower install regenerate
```

In a browser:

```html
<script src="regenerate.js"></script>
```

In [Node.js](https://nodejs.org/), [io.js](https://iojs.org/), and [RingoJS ≥ v0.8.0](http://ringojs.org/):

```js
var regenerate = require('regenerate');
```

In [Narwhal](http://narwhaljs.org/) and [RingoJS ≤ v0.7.0](http://ringojs.org/):

```js
var regenerate = require('regenerate').regenerate;
```

In [Rhino](http://www.mozilla.org/rhino/):

```js
load('regenerate.js');
```

Using an AMD loader like [RequireJS](http://requirejs.org/):

```js
require(
  {
    'paths': {
      'regenerate': 'path/to/regenerate'
    }
  },
  ['regenerate'],
  function(regenerate) {
    console.log(regenerate);
  }
);
```

## API

### `regenerate(value1, value2, value3, ...)`

The main Regenerate function. Calling this function creates a new set that gets a chainable API.

```js
var set = regenerate()
  .addRange(0x60, 0x69) // add U+0060 to U+0069
  .remove(0x62, 0x64) // remove U+0062 and U+0064
  .add(0x1D306); // add U+1D306
set.valueOf();
// → [0x60, 0x61, 0x63, 0x65, 0x66, 0x67, 0x68, 0x69, 0x1D306]
set.toString();
// → '[`ace-i]|\\uD834\\uDF06'
set.toRegExp();
// → /[`ace-i]|\uD834\uDF06/
```

Any arguments passed to `regenerate()` will be added to the set right away. Both code points (numbers) and symbols (strings consisting of a single Unicode symbol) are accepted, as well as arrays containing values of these types.

```js
regenerate(0x1D306, 'A', '©', 0x2603).toString();
// → '[A\\xA9\\u2603]|\\uD834\\uDF06'

var items = [0x1D306, 'A', '©', 0x2603];
regenerate(items).toString();
// → '[A\\xA9\\u2603]|\\uD834\\uDF06'
```

### `regenerate.prototype.add(value1, value2, value3, ...)`

Any arguments passed to `add()` are added to the set. Both code points (numbers) and symbols (strings consisting of a single Unicode symbol) are accepted, as well as arrays containing values of these types.

```js
regenerate().add(0x1D306, 'A', '©', 0x2603).toString();
// → '[A\\xA9\\u2603]|\\uD834\\uDF06'

var items = [0x1D306, 'A', '©', 0x2603];
regenerate().add(items).toString();
// → '[A\\xA9\\u2603]|\\uD834\\uDF06'
```

It’s also possible to pass in a Regenerate instance. Doing so adds all code points in that instance to the current set.

```js
var set = regenerate(0x1D306, 'A');
regenerate().add('©', 0x2603).add(set).toString();
// → '[A\\xA9\\u2603]|\\uD834\\uDF06'
```

Note that the initial call to `regenerate()` acts like `add()`. This allows you to create a new Regenerate instance and add some code points to it in one go:

```js
regenerate(0x1D306, 'A', '©', 0x2603).toString();
// → '[A\\xA9\\u2603]|\\uD834\\uDF06'
```

### `regenerate.prototype.remove(value1, value2, value3, ...)`

Any arguments passed to `remove()` are removed from the set. Both code points (numbers) and symbols (strings consisting of a single Unicode symbol) are accepted, as well as arrays containing values of these types.

```js
regenerate(0x1D306, 'A', '©', 0x2603).remove('☃').toString();
// → '[A\\xA9]|\\uD834\\uDF06'
```

It’s also possible to pass in a Regenerate instance. Doing so removes all code points in that instance from the current set.

```js
var set = regenerate('☃');
regenerate(0x1D306, 'A', '©', 0x2603).remove(set).toString();
// → '[A\\xA9]|\\uD834\\uDF06'
```

### `regenerate.prototype.addRange(start, end)`

Adds a range of code points from `start` to `end` (inclusive) to the set. Both code points (numbers) and symbols (strings consisting of a single Unicode symbol) are accepted.

```js
regenerate(0x1D306).addRange(0x00, 0xFF).toString(16);
// → '[\\0-\\xFF]|\\uD834\\uDF06'

regenerate().addRange('A', 'z').toString();
// → '[A-z]'
```

### `regenerate.prototype.removeRange(start, end)`

Removes a range of code points from `start` to `end` (inclusive) from the set. Both code points (numbers) and symbols (strings consisting of a single Unicode symbol) are accepted.

```js
regenerate()
  .addRange(0x000000, 0x10FFFF) // add all Unicode code points
  .removeRange('A', 'z') // remove all symbols from `A` to `z`
  .toString();
// → '[\\0-@\\{-\\uD7FF\\uE000-\\uFFFF]|[\\uD800-\\uDBFF][\\uDC00-\\uDFFF]|[\\uD800-\\uDBFF](?![\\uDC00-\\uDFFF])|(?:[^\\uD800-\\uDBFF]|^)[\\uDC00-\\uDFFF]'

regenerate()
  .addRange(0x000000, 0x10FFFF) // add all Unicode code points
  .removeRange(0x0041, 0x007A) // remove all code points from U+0041 to U+007A
  .toString();
// → '[\\0-@\\{-\\uD7FF\\uE000-\\uFFFF]|[\\uD800-\\uDBFF][\\uDC00-\\uDFFF]|[\\uD800-\\uDBFF](?![\\uDC00-\\uDFFF])|(?:[^\\uD800-\\uDBFF]|^)[\\uDC00-\\uDFFF]'
```

### `regenerate.prototype.intersection(codePoints)`

Removes any code points from the set that are not present in both the set and the given `codePoints` array. `codePoints` must be an array of numeric code point values, i.e. numbers.

```js
regenerate()
  .addRange(0x00, 0xFF) // add extended ASCII code points
  .intersection([0x61, 0x69]) // remove all code points from the set except for these
  .toString();
// → '[ai]'
```

Instead of the `codePoints` array, it’s also possible to pass in a Regenerate instance.

```js
var whitelist = regenerate(0x61, 0x69);

regenerate()
  .addRange(0x00, 0xFF) // add extended ASCII code points
  .intersection(whitelist) // remove all code points from the set except for those in the `whitelist` set
  .toString();
// → '[ai]'
```

### `regenerate.prototype.contains(value)`

Returns `true` if the given value is part of the set, and `false` otherwise. Both code points (numbers) and symbols (strings consisting of a single Unicode symbol) are accepted.

```js
var set = regenerate().addRange(0x00, 0xFF);
set.contains('A');
// → true
set.contains(0x1D306);
// → false
```

### `regenerate.prototype.clone()`

Returns a clone of the current code point set. Any actions performed on the clone won’t mutate the original set.

```js
var setA = regenerate(0x1D306);
var setB = setA.clone().add(0x1F4A9);
setA.toArray();
// → [0x1D306]
setB.toArray();
// → [0x1D306, 0x1F4A9]
```

### `regenerate.prototype.toString(options)`

Returns a string representing (part of) a regular expression that matches all the symbols mapped to the code points within the set.

```js
regenerate(0x1D306, 0x1F4A9).toString();
// → '\\uD834\\uDF06|\\uD83D\\uDCA9'
```

If the `bmpOnly` property of the optional `options` object is set to `true`, the output matches surrogates individually, regardless of whether they’re lone surrogates or just part of a surrogate pair. This simplifies the output, but it can only be used in case you’re certain the strings it will be used on don’t contain any astral symbols.

```js
var highSurrogates = regenerate().addRange(0xD800, 0xDBFF);
highSurrogates.toString();
// → '[\\uD800-\\uDBFF](?![\\uDC00-\\uDFFF])'
highSurrogates.toString({ 'bmpOnly': true });
// → '[\\uD800-\\uDBFF]'

var lowSurrogates = regenerate().addRange(0xDC00, 0xDFFF);
lowSurrogates.toString();
// → '(?:[^\\uD800-\\uDBFF]|^)[\\uDC00-\\uDFFF]'
lowSurrogates.toString({ 'bmpOnly': true });
// → '[\\uDC00-\\uDFFF]'
```

Note that lone low surrogates cannot be matched accurately using regular expressions in JavaScript without the use of [lookbehind assertions](https://mathiasbynens.be/notes/es-regexp-proposals#lookbehinds), which aren't yet widely supported. Regenerate’s output makes a best-effort approach but [there can be false negatives in this regard](https://github.com/mathiasbynens/regenerate/issues/28#issuecomment-72224808).

If the `hasUnicodeFlag` property of the optional `options` object is set to `true`, the output makes use of Unicode code point escapes (`\u{…}`) where applicable. This simplifies the output at the cost of compatibility and portability, since it means the output can only be used as a pattern in a regular expression with [the ES6 `u` flag](https://mathiasbynens.be/notes/es6-unicode-regex) enabled.

```js
var set = regenerate().addRange(0x0, 0x10FFFF);

set.toString();
// → '[\\0-\\uD7FF\\uE000-\\uFFFF]|[\\uD800-\\uDBFF][\\uDC00-\\uDFFF]|[\\uD800-\\uDBFF](?![\\uDC00-\\uDFFF])|(?:[^\\uD800-\\uDBFF]|^)[\\uDC00-\\uDFFF]''

set.toString({ 'hasUnicodeFlag': true });
// → '[\\0-\\u{10FFFF}]'
```

### `regenerate.prototype.toRegExp(flags = '')`

Returns a regular expression that matches all the symbols mapped to the code points within the set. Optionally, you can pass [flags](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp#Parameters) to be added to the regular expression.

```js
var regex = regenerate(0x1D306, 0x1F4A9).toRegExp();
// → /\uD834\uDF06|\uD83D\uDCA9/
regex.test('𝌆');
// → true
regex.test('A');
// → false

// With flags:
var regex = regenerate(0x1D306, 0x1F4A9).toRegExp('g');
// → /\uD834\uDF06|\uD83D\uDCA9/g
```

**Note:** This probably shouldn’t be used. Regenerate is intended as a tool that is used as part of a build process, not at runtime.

### `regenerate.prototype.valueOf()` or `regenerate.prototype.toArray()`

Returns a sorted array of unique code points in the set.

```js
regenerate(0x1D306)
  .addRange(0x60, 0x65)
  .add(0x59, 0x60) // note: 0x59 is added after 0x65, and 0x60 is a duplicate
  .valueOf();
// → [0x59, 0x60, 0x61, 0x62, 0x63, 0x64, 0x65, 0x1D306]
```

### `regenerate.version`

A string representing the semantic version number.

## Combine Regenerate with other libraries

Regenerate gets even better when combined with other libraries such as [Punycode.js](https://mths.be/punycode). Here’s an example where [Punycode.js](https://mths.be/punycode) is used to convert a string into an array of code points, that is then passed on to Regenerate:

```js
var regenerate = require('regenerate');
var punycode = require('punycode');

var string = 'Lorem ipsum dolor sit amet.';
// Get an array of all code points used in the string:
var codePoints = punycode.ucs2.decode(string);

// Generate a regular expression that matches any of the symbols used in the string:
regenerate(codePoints).toString();
// → '[ \\.Ladeilmopr-u]'
```

In ES6 you can do something similar with [`Array.from`](https://mths.be/array-from) which uses [the string’s iterator](https://mathiasbynens.be/notes/javascript-unicode#iterating-over-symbols) to split the given string into an array of strings that each contain a single symbol. [`regenerate()`](#regenerateprototypeaddvalue1-value2-value3-) accepts both strings and code points, remember?

```js
var regenerate = require('regenerate');

var string = 'Lorem ipsum dolor sit amet.';
// Get an array of all symbols used in the string:
var symbols = Array.from(string);

// Generate a regular expression that matches any of the symbols used in the string:
regenerate(symbols).toString();
// → '[ \\.Ladeilmopr-u]'
```

## Support

Regenerate supports at least Chrome 27+, Firefox 3+, Safari 4+, Opera 10+, IE 6+, Node.js v0.10.0+, io.js v1.0.0+, Narwhal 0.3.2+, RingoJS 0.8+, PhantomJS 1.9.0+, and Rhino 1.7RC4+.

## Unit tests & code coverage

After cloning this repository, run `npm install` to install the dependencies needed for Regenerate development and testing. You may want to install Istanbul _globally_ using `npm install istanbul -g`.

Once that’s done, you can run the unit tests in Node using `npm test` or `node tests/tests.js`. To run the tests in Rhino, Ringo, Narwhal, and web browsers as well, use `grunt test`.

To generate the code coverage report, use `grunt cover`.

## Author

| [![twitter/mathias](https://gravatar.com/avatar/24e08a9ea84deb17ae121074d0f17125?s=70)](https://twitter.com/mathias "Follow @mathias on Twitter") |
|---|
| [Mathias Bynens](https://mathiasbynens.be/) |

## License

Regenerate is available under the [MIT](https://mths.be/mit) license.


---

# regenerate-unicode-properties [![regenerate-unicode-properties on npm](https://img.shields.io/npm/v/regenerate-unicode-properties)](https://www.npmjs.com/package/regenerate-unicode-properties)

_regenerate-unicode-properties_ is a collection of [Regenerate](https://github.com/mathiasbynens/regenerate) sets for [various Unicode properties](https://github.com/tc39/proposal-regexp-unicode-property-escapes).

## Installation

To use _regenerate-unicode-properties_ programmatically, install it as a dependency via [npm](https://www.npmjs.com/):

```bash
$ npm install regenerate-unicode-properties
```

## Usage

To get a map of supported properties and their values:

```js
const properties = require('regenerate-unicode-properties');
```

To get a specific Regenerate set:

```js
// Examples:
const Lu = require('regenerate-unicode-properties/General_Category/Uppercase_Letter.js').characters;
const Greek = require('regenerate-unicode-properties/Script_Extensions/Greek.js').characters;
```

Some properties can also refer to strings rather than single characters:
```js
const { characters, strings } = require('regenerate-unicode-properties/Property_of_Strings/Basic_Emoji.js');
```

To get the Unicode version the data was based on:

```js
const unicodeVersion = require('regenerate-unicode-properties/unicode-version.js');
```

## For maintainers

### How to publish a new release

1. On the `main` branch, bump the version number in `package.json`:

    ```sh
    npm version patch -m 'Release v%s'
    ```

    Instead of `patch`, use `minor` or `major` [as needed](https://semver.org/).

    Note that this produces a Git commit + tag.

1. Push the release commit and tag:

    ```sh
    git push && git push --tags
    ```

    Our CI then automatically publishes the new release to npm.

## Author

| [![twitter/mathias](https://gravatar.com/avatar/24e08a9ea84deb17ae121074d0f17125?s=70)](https://twitter.com/mathias "Follow @mathias on Twitter") |
|---|
| [Mathias Bynens](https://mathiasbynens.be/) |

## License

_regenerate-unicode-properties_ is available under the [MIT](https://mths.be/mit) license.


---

# regenerator-runtime

Standalone runtime for
[Regenerator](https://github.com/facebook/regenerator)-compiled generator
and `async` functions.

To import the runtime as a module (recommended), either of the following
import styles will work:
```js
// CommonJS
const regeneratorRuntime = require("regenerator-runtime");

// ECMAScript 2015
import regeneratorRuntime from "regenerator-runtime";
```

To ensure that `regeneratorRuntime` is defined globally, either of the
following styles will work:
```js
// CommonJS
require("regenerator-runtime/runtime");

// ECMAScript 2015
import "regenerator-runtime/runtime.js";
```

To get the absolute file system path of `runtime.js`, evaluate the
following expression:
```js
require("regenerator-runtime/path").path
```


---

# regenerator-transform

Transform async/generator functions with [regenerator](https://github.com/facebook/regenerator)

## Installation

```sh
$ npm install regenerator-transform
```

## Usage

### Via `.babelrc` (Recommended)

**.babelrc**

```js
// without options
{
  "plugins": ["regenerator-transform"]
}
// with options
{
  "plugins": [
    ["regenerator-transform", {
      asyncGenerators: false, // true by default
      generators: false, // true by default
      async: false // true by default
    }]
  ]
}
```

### Via CLI

```sh
$ babel --plugins regenerator-transform script.js
```

### Via Node API

```javascript
require("@babel/core").transformSync("code", {
  plugins: ["regenerator-transform"]
});
```


---

# regexpu-core [![Build status](https://github.com/mathiasbynens/regexpu-core/workflows/run-checks/badge.svg)](https://github.com/mathiasbynens/regexpu-core/actions?query=workflow%3Arun-checks) [![regexpu-core on npm](https://img.shields.io/npm/v/regexpu-core)](https://www.npmjs.com/package/regexpu-core)

_regexpu_ is a source code transpiler that enables the use of ES2015 Unicode regular expressions in JavaScript-of-today (ES5).

_regexpu-core_ contains _regexpu_’s core functionality, i.e. `rewritePattern(pattern, flag)`, which enables rewriting regular expressions that make use of [the ES2015 `u` flag](https://mathiasbynens.be/notes/es6-unicode-regex) into equivalent ES5-compatible regular expression patterns.

## Installation

To use _regexpu-core_ programmatically, install it as a dependency via [npm](https://www.npmjs.com/):

```bash
npm install regexpu-core --save
```

Then, `require` it:

```js
const rewritePattern = require('regexpu-core');
```

## API

This module exports a single function named `rewritePattern`.

### `rewritePattern(pattern, flags, options)`

This function takes a string that represents a regular expression pattern as well as a string representing its flags, and returns an ES5-compatible version of the pattern.

```js
rewritePattern('foo.bar', 'u', { unicodeFlag: "transform" });
// → 'foo(?:[\\0-\\t\\x0B\\f\\x0E-\\u2027\\u202A-\\uD7FF\\uDC00-\\uFFFF]|[\\uD800-\\uDBFF][\\uDC00-\\uDFFF]|[\\uD800-\\uDBFF])bar'

rewritePattern('[\\u{1D306}-\\u{1D308}a-z]', 'u', { unicodeFlag: "transform" });
// → '(?:[a-z]|\\uD834[\\uDF06-\\uDF08])'

rewritePattern('[\\u{1D306}-\\u{1D308}a-z]', 'ui', { unicodeFlag: "transform" });
// → '(?:[a-z\\u017F\\u212A]|\\uD834[\\uDF06-\\uDF08])'
```

_regexpu-core_ can rewrite non-ES6 regular expressions too, which is useful to demonstrate how their behavior changes once the `u` and `i` flags are added:

```js
// In ES5, the dot operator only matches BMP symbols:
rewritePattern('foo.bar', '', { unicodeFlag: "transform" });
// → 'foo(?:[\\0-\\t\\x0B\\f\\x0E-\\u2027\\u202A-\\uFFFF])bar'

// But with the ES2015 `u` flag, it matches astral symbols too:
rewritePattern('foo.bar', 'u', { unicodeFlag: "transform" });
// → 'foo(?:[\\0-\\t\\x0B\\f\\x0E-\\u2027\\u202A-\\uD7FF\\uDC00-\\uFFFF]|[\\uD800-\\uDBFF][\\uDC00-\\uDFFF]|[\\uD800-\\uDBFF])bar'
```

The optional `options` argument recognizes the following properties:

#### Stable regular expression features

These options can be set to `false` or `'transform'`. When using `'transform'`, the corresponding features are compiled to older syntax that can run in older browsers. When using `false` (the default), they are not compiled and they can be relied upon to compile more modern features.

- `unicodeFlag` - The `u` flag, enabling support for Unicode code point escapes in the form `\u{...}`.

  ```js
  rewritePattern('\\u{ab}', '', {
    unicodeFlag: 'transform'
  });
  // → '\\u{ab}'

  rewritePattern('\\u{ab}', 'u', {
    unicodeFlag: 'transform'
  });
  // → '\\xAB'
  ```

- `dotAllFlag` - The [`s` (`dotAll`) flag](https://github.com/mathiasbynens/es-regexp-dotall-flag).

  ```js
  rewritePattern('.', '', {
    dotAllFlag: 'transform'
  });
  // → '[\\0-\\t\\x0B\\f\\x0E-\\u2027\\u202A-\\uFFFF]'

  rewritePattern('.', 's', {
    dotAllFlag: 'transform'
  });
  // → '[\\0-\\uFFFF]'

  rewritePattern('.', 'su', {
    dotAllFlag: 'transform'
  });
  // → '(?:[\\0-\\uD7FF\\uE000-\\uFFFF]|[\\uD800-\\uDBFF][\\uDC00-\\uDFFF]|[\\uD800-\\uDBFF](?![\\uDC00-\\uDFFF])|(?:[^\\uD800-\\uDBFF]|^)[\\uDC00-\\uDFFF])'
  ```

- `unicodePropertyEscapes` - [Unicode property escapes](property-escapes.md).

  By default they are compiled to Unicode code point escapes of the form `\u{...}`. If the `unicodeFlag` option is set to `'transform'` they often result in larger output, although there are cases (such as `\p{Lu}`) where it actually _decreases_ the output size.

  ```js
  rewritePattern('\\p{Script_Extensions=Anatolian_Hieroglyphs}', 'u', {
    unicodePropertyEscapes: 'transform'
  });
  // → '[\\u{14400}-\\u{14646}]'

  rewritePattern('\\p{Script_Extensions=Anatolian_Hieroglyphs}', 'u', {
    unicodeFlag: 'transform',
    unicodePropertyEscapes: 'transform'
  });
  // → '(?:\\uD811[\\uDC00-\\uDE46])'
  ```

- `namedGroups` - [Named capture groups](https://github.com/tc39/proposal-regexp-named-groups).

  ```js
  rewritePattern('(?<name>.)\\k<name>', '', {
    namedGroups: 'transform'
  });
  // → '(.)\1'
  ```

- `unicodeSetsFlag` - [The `v` (`unicodeSets`) flag](https://github.com/tc39/proposal-regexp-set-notation)

  ```js
  rewritePattern('[\\p{Emoji}&&\\p{ASCII}]', 'v', {
    unicodeSetsFlag: 'transform'
  });
  // → '[#\\*0-9]'
  ```

  By default, patterns with the `v` flag are transformed to patterns with the `u` flag. If you want to downlevel them more you can set the `unicodeFlag: 'transform'` option.

  ```js
  rewritePattern('[^[a-h]&&[f-z]]', 'v', {
    unicodeSetsFlag: 'transform'
  });
  // → '[^f-h]' (to be used with /u)
  ```

  ```js
  rewritePattern('[^[a-h]&&[f-z]]', 'v', {
    unicodeSetsFlag: 'transform',
    unicodeFlag: 'transform'
  });
  // → '(?:(?![f-h])[\s\S])' (to be used without /u)
  ```

- `modifiers` - [Inline `i`/`m`/`s` modifiers](https://github.com/tc39/proposal-regexp-modifiers)

  ```js
  rewritePattern('(?i:[a-z])[a-z]', '', {
    modifiers: 'transform'
  });
  // → '(?:[a-zA-Z])([a-z])'
  ```

#### Experimental regular expression features

These options can be set to `false`, `'parse'` and `'transform'`. When using `'transform'`, the corresponding features are compiled to older syntax that can run in older browsers. When using `'parse'`, they are parsed and left as-is in the output pattern. When using `false` (the default), they result in a syntax error if used.

Once these features become stable (when the proposals are accepted as part of ECMAScript), they will be parsed by default and thus `'parse'` will behave like `false`.

#### Miscellaneous options

- `onNamedGroup`

  This option is a function that gets called when a named capture group is found. It receives two parameters:
  the name of the group, and its index.

  ```js
  rewritePattern('(?<name>.)\\k<name>', '', {
    onNamedGroup(name, index) {
      console.log(name, index);
      // → 'name', 1
    }
  });
  ```

- `onNewFlags`

  This option is a function that gets called to pass the flags that the resulting pattern must be interpreted with.

  ```js
  rewritePattern('abc', 'um', '', {
    unicodeFlag: 'transform',
    onNewFlags(flags) {
      console.log(flags);
      // → 'm'
    }
  })
  ```

### Caveats

- [Lookbehind assertions](https://github.com/tc39/proposal-regexp-lookbehind) cannot be transformed to older syntax.
- When using `namedGroups: 'transform'`, _regexpu-core_ only takes care of the _syntax_: you will still need a runtime wrapper around the regular expression to populate the `.groups` property of `RegExp.prototype.match()`'s result. If you are using _regexpu-core_ via Babel, it's handled automatically.

## For maintainers

### How to publish a new release

1. On the `main` branch, bump the version number in `package.json`:

    ```sh
    npm version patch -m 'Release v%s'
    ```

    Instead of `patch`, use `minor` or `major` [as needed](https://semver.org/).

    Note that this produces a Git commit + tag.

1. Push the release commit and tag:

    ```sh
    git push --follow-tags
    ```

    Our CI then automatically publishes the new release to npm.

1. Once the release has been published to npm, update [`regexpu`](https://github.com/mathiasbynens/regexpu) to make use of it, and [cut a new release of `regexpu` as well](https://github.com/mathiasbynens/regexpu#how-to-publish-a-new-release).


## Author

| [![twitter/mathias](https://gravatar.com/avatar/24e08a9ea84deb17ae121074d0f17125?s=70)](https://twitter.com/mathias "Follow @mathias on Twitter") |
|---|
| [Mathias Bynens](https://mathiasbynens.be/) |

## License

_regexpu-core_ is available under the [MIT](https://mths.be/mit) license.


---

# Change Log

All notable changes will be documented in this file.

## [5.1.0] - 2025-02-07

### Changes

- Use WHATWG URL instead of legacy APIs, silencing errors in Bun etc (fisker Cheung)

## [5.0.3] - 2024-11-27

### Changes

- Make all arguments optional in type definitions (Mattias Leino)

## [5.0.2] - 2023-03-05

### Changes

- Prevent crashing on invalid npmrc files (Espen Hovlandsdal)

## [5.0.0] - 2022-06-16

### BREAKING

- Require node version 14 or above (Espen Hovlandsdal)

### Added

- Add typescript definitions (Espen Hovlandsdal)

### Changes

- Replace outdated `rc` dependency with `@pnpm/npm-conf` (Kyler Nelson)
- Fix incorrect usage information in readme (Kyler Nelson)

## [4.2.2] - 2022-06-16

### Changes

- Pin version of `rc` module to `1.2.8` to avoid malware in [compromised versions](https://github.com/advisories/GHSA-g2q5-5433-rhrf) (Espen Hovlandsdal)

## [4.2.1] - 2020-11-10

### Changes

- Exclude tests from published npm files (Garrit Franke)

## [4.2.0] - 2020-07-13

### Changes

- Add support for `NPM_CONFIG_USERCONFIG` environment variable (Ben Sorohan)

## [4.1.0] - 2020-01-17

### Changes

- Add support for legacy auth token on the registry url (Gustav Blomér)

## [4.0.0] - 2019-06-17

### BREAKING

- Minimum node.js version requirement is now v6

### Changes

- Upgraded dependencies (Espen Hovlandsdal)

## [3.4.0] - 2019-03-20

### Changes

- Enabled legacy auth token to be read from environment variable (Martin Flodin)

## [3.3.2] - 2018-01-26

### Changes

- Support password with ENV variable tokens (Nowell Strite)

## [3.3.1] - 2017-05-02

### Fixes

- Auth legacy token is basic auth (Hutson Betts)

## [3.3.0] - 2017-04-24

### Changes

- Support legacy auth token config key (Zoltan Kochan)
- Use safe-buffer module for backwards-compatible base64 encoding/decoding (Espen Hovlandsdal)
- Change to standard.js coding style (Espen Hovlandsdal)

## [3.2.0] - 2017-04-20

### Changes

- Allow passing parsed npmrc from outside (Zoltan Kochan)

## [3.1.2] - 2017-04-07

### Changes

- Avoid infinite loop on invalid URL (Zoltan Kochan)

## [3.1.1] - 2017-04-06

### Changes

- Nerf-dart URLs even if recursive is set to false (Espen Hovlandsdal)

## [3.1.0] - 2016-10-19

### Changes

- Return the password and username for Basic authorization (Zoltan Kochan)

## [3.0.1] - 2016-08-07

### Changes

- Fix recursion bug (Lukas Eipert)
- Implement alternative base64 encoding/decoding implementation for Node 6 (Lukas Eipert)

## [3.0.0] - 2016-08-04

### Added

- Support for Basic Authentication (username/password) (Lukas Eipert)

### Changes

- The result format of the output changed from a simple string to an object which contains the token type

```js
// before: returns 'tokenString'
// after: returns {token: 'tokenString', type: 'Bearer'}
getAuthToken();
```

## [2.1.1] - 2016-07-10

### Changes

- Fix infinite loop when recursively resolving registry URLs on Windows (Espen Hovlandsdal)

## [2.1.0] - 2016-07-07

### Added

- Add feature to find configured registry URL for a scope (Espen Hovlandsdal)

## [2.0.0] - 2016-06-17

### Changes

- Fix tokens defined by reference to environment variables (Dan MacTough)

## [1.1.1] - 2016-04-26

### Changes

- Fix for registries with port number in URL (Ryan Day)

[1.1.1]: https://github.com/rexxars/registry-auth-token/compare/a5b4fe2f5ff982110eb8a813ba1b3b3c5d851af1...v1.1.1
[2.0.0]: https://github.com/rexxars/registry-auth-token/compare/v1.1.1...v2.0.0
[2.1.0]: https://github.com/rexxars/registry-auth-token/compare/v2.0.0...v2.1.0
[2.1.1]: https://github.com/rexxars/registry-auth-token/compare/v2.1.0...v2.1.1
[3.0.0]: https://github.com/rexxars/registry-auth-token/compare/v2.1.1...v3.0.0
[3.0.1]: https://github.com/rexxars/registry-auth-token/compare/v3.0.0...v3.0.1
[3.1.0]: https://github.com/rexxars/registry-auth-token/compare/v3.0.1...v3.1.0
[3.1.1]: https://github.com/rexxars/registry-auth-token/compare/v3.1.0...v3.1.1
[3.1.2]: https://github.com/rexxars/registry-auth-token/compare/v3.1.1...v3.1.2
[3.2.0]: https://github.com/rexxars/registry-auth-token/compare/v3.1.2...v3.2.0
[3.3.0]: https://github.com/rexxars/registry-auth-token/compare/v3.2.0...v3.3.0


---

# registry-auth-token

[![npm version](http://img.shields.io/npm/v/registry-auth-token.svg?style=flat-square)](https://www.npmjs.com/package/registry-auth-token)[![npm](https://img.shields.io/npm/dm/registry-auth-token?style=flat-square)](https://www.npmjs.com/package/registry-auth-token)

Get the auth token set for an npm registry from `.npmrc`. Also allows fetching the configured registry URL for a given npm scope.

## Installing

```
npm install --save registry-auth-token
```

## Usage

Returns an object containing `token` and `type`, or `undefined` if no token can be found. `type` can be either `Bearer` or `Basic`.

```js
const getAuthToken = require('registry-auth-token')
const getRegistryUrl = require('registry-auth-token/registry-url')

// Get auth token and type for default `registry` set in `.npmrc`
console.log(getAuthToken()) // {token: 'someToken', type: 'Bearer'}

// Get auth token for a specific registry URL
console.log(getAuthToken('//registry.foo.bar'))

// Find the registry auth token for a given URL (with deep path):
// If registry is at `//some.host/registry`
// URL passed is `//some.host/registry/deep/path`
// Will find token the closest matching path; `//some.host/registry`
console.log(getAuthToken('//some.host/registry/deep/path', {recursive: true}))

// Use the npm config that is passed in
console.log(getAuthToken('//registry.foo.bar', {
  npmrc: {
    'registry': 'http://registry.foo.bar',
    '//registry.foo.bar/:_authToken': 'qar'
  }
}))

// Find the configured registry url for scope `@foobar`.
// Falls back to the global registry if not defined.
console.log(getRegistryUrl('@foobar'))

// Use the npm config that is passed in
console.log(getRegistryUrl('http://registry.foobar.eu/', {
  'registry': 'http://registry.foobar.eu/',
  '//registry.foobar.eu/:_authToken': 'qar'
}))
```

## Return value

```js
// If auth info can be found:
{token: 'someToken', type: 'Bearer'}

// Or:
{token: 'someOtherToken', type: 'Basic'}

// Or, if nothing is found:
undefined
```

## Security

Please be careful when using this. Leaking your auth token is dangerous.

## License

MIT © [Espen Hovlandsdal](https://espen.codes/)


---

# registry-url

> Get the set npm registry URL

It's usually `https://registry.npmjs.org/`, but it's [configurable](https://docs.npmjs.com/misc/registry).

Use this if you do anything with the npm registry as users will expect it to use their configured registry.

## Install

```
$ npm install registry-url
```

## Usage

```ini
# .npmrc
registry = 'https://custom-registry.com/'
```

```js
import registryUrl from 'registry-url';

console.log(registryUrl());
//=> 'https://custom-registry.com/'
```

It can also retrieve the registry URL associated with an [npm scope](https://docs.npmjs.com/misc/scope).

```ini
# .npmrc
@myco:registry = 'https://custom-registry.com/'
```

```js
import registryUrl from 'registry-url';

console.log(registryUrl('@myco'));
//=> 'https://custom-registry.com/'
```

If the provided scope is not in the user's `.npmrc` file, then `registry-url` will check for the existence of `registry`, or if that's not set, fallback to the default npm registry.

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-registry-url?utm_source=npm-registry-url&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

# regjsgen [![Build status][ci-img]][ci] [![Code coverage status][codecov-img]][codecov]

Generate regular expressions from [regjsparser][regjsparser]’s AST.

## Installation

```sh
npm i regjsgen
```

## API

### `regjsgen.generate(ast)`

This function accepts an abstract syntax tree representing a regular expression (see [regjsparser][regjsparser]), and returns the generated regular expression string.

```js
const regjsparser = require('regjsparser');
const regjsgen = require('regjsgen');

// Generate an AST with `regjsparser`.
let ast = regjsparser.parse(regex);

// Modify AST
// …

// Generate `RegExp` string with `regjsgen`.
let regex = regjsgen.generate(ast);
```

## Support

Tested on Node.js 16 and 18.<br>
Compatible with regjsparser v0.10.0’s AST.


[ci]: https://github.com/bnjmnt4n/regjsgen/actions
[ci-img]: https://github.com/bnjmnt4n/regjsgen/workflows/Node.js%20CI/badge.svg
[codecov]: https://codecov.io/gh/bnjmnt4n/regjsgen
[codecov-img]: https://codecov.io/gh/bnjmnt4n/regjsgen/branch/main/graph/badge.svg
[regjsparser]: https://github.com/jviereck/regjsparser


---

# RegJSParser

Parsing the JavaScript's RegExp in JavaScript.

## Installation

```bash
npm install regjsparser
```

## Usage

```js
var parse = require('regjsparser').parse;

var parseTree = parse('^a'); // /^a/
console.log(parseTree);

// Toggle on/off additional features:
var parseTree = parse('^a', '', {
  // SEE: https://github.com/jviereck/regjsparser/pull/78
  unicodePropertyEscape: true,

  // SEE: https://github.com/jviereck/regjsparser/pull/83
  namedGroups: true,

  // SEE: https://github.com/jviereck/regjsparser/pull/89
  lookbehind: true
});
console.log(parseTree);
```

## Testing

To run the tests, run the following command:

```bash
npm test
```

To create a new reference file, execute…

```bash
node test/update-fixtures.js
```

…from the repo top directory.


---

# jsesc [![Build status](https://travis-ci.org/mathiasbynens/jsesc.svg?branch=master)](https://travis-ci.org/mathiasbynens/jsesc) [![Code coverage status](https://coveralls.io/repos/mathiasbynens/jsesc/badge.svg)](https://coveralls.io/r/mathiasbynens/jsesc)

Given some data, _jsesc_ returns a stringified representation of that data. jsesc is similar to `JSON.stringify()` except:

1. it outputs JavaScript instead of JSON [by default](#json), enabling support for data structures like ES6 maps and sets;
2. it offers [many options](#api) to customize the output;
3. its output is ASCII-safe [by default](#minimal), thanks to its use of [escape sequences](https://mathiasbynens.be/notes/javascript-escapes) where needed.

For any input, jsesc generates the shortest possible valid printable-ASCII-only output. [Here’s an online demo.](https://mothereff.in/js-escapes)

jsesc’s output can be used instead of `JSON.stringify`’s to avoid [mojibake](https://en.wikipedia.org/wiki/Mojibake) and other encoding issues, or even to [avoid errors](https://twitter.com/annevk/status/380000829643571200) when passing JSON-formatted data (which may contain U+2028 LINE SEPARATOR, U+2029 PARAGRAPH SEPARATOR, or [lone surrogates](https://esdiscuss.org/topic/code-points-vs-unicode-scalar-values#content-14)) to a JavaScript parser or an UTF-8 encoder.

## Installation

Via [npm](https://www.npmjs.com/):

```bash
npm install jsesc
```

In [Node.js](https://nodejs.org/):

```js
const jsesc = require('jsesc');
```

## API

### `jsesc(value, options)`

This function takes a value and returns an escaped version of the value where any characters that are not printable ASCII symbols are escaped using the shortest possible (but valid) [escape sequences for use in JavaScript strings](https://mathiasbynens.be/notes/javascript-escapes). The first supported value type is strings:

```js
jsesc('Ich ♥ Bücher');
// → 'Ich \\u2665 B\\xFCcher'

jsesc('foo 𝌆 bar');
// → 'foo \\uD834\\uDF06 bar'
```

Instead of a string, the `value` can also be an array, an object, a map, a set, or a buffer. In such cases, `jsesc` returns a stringified version of the value where any characters that are not printable ASCII symbols are escaped in the same way.

```js
// Escaping an array
jsesc([
  'Ich ♥ Bücher', 'foo 𝌆 bar'
]);
// → '[\'Ich \\u2665 B\\xFCcher\',\'foo \\uD834\\uDF06 bar\']'

// Escaping an object
jsesc({
  'Ich ♥ Bücher': 'foo 𝌆 bar'
});
// → '{\'Ich \\u2665 B\\xFCcher\':\'foo \\uD834\\uDF06 bar\'}'
```

The optional `options` argument accepts an object with the following options:

#### `quotes`

The default value for the `quotes` option is `'single'`. This means that any occurrences of `'` in the input string are escaped as `\'`, so that the output can be used in a string literal wrapped in single quotes.

```js
jsesc('`Lorem` ipsum "dolor" sit \'amet\' etc.');
// → 'Lorem ipsum "dolor" sit \\\'amet\\\' etc.'

jsesc('`Lorem` ipsum "dolor" sit \'amet\' etc.', {
  'quotes': 'single'
});
// → '`Lorem` ipsum "dolor" sit \\\'amet\\\' etc.'
// → "`Lorem` ipsum \"dolor\" sit \\'amet\\' etc."
```

If you want to use the output as part of a string literal wrapped in double quotes, set the `quotes` option to `'double'`.

```js
jsesc('`Lorem` ipsum "dolor" sit \'amet\' etc.', {
  'quotes': 'double'
});
// → '`Lorem` ipsum \\"dolor\\" sit \'amet\' etc.'
// → "`Lorem` ipsum \\\"dolor\\\" sit 'amet' etc."
```

If you want to use the output as part of a template literal (i.e. wrapped in backticks), set the `quotes` option to `'backtick'`.

```js
jsesc('`Lorem` ipsum "dolor" sit \'amet\' etc.', {
  'quotes': 'backtick'
});
// → '\\`Lorem\\` ipsum "dolor" sit \'amet\' etc.'
// → "\\`Lorem\\` ipsum \"dolor\" sit 'amet' etc."
// → `\\\`Lorem\\\` ipsum "dolor" sit 'amet' etc.`
```

This setting also affects the output for arrays and objects:

```js
jsesc({ 'Ich ♥ Bücher': 'foo 𝌆 bar' }, {
  'quotes': 'double'
});
// → '{"Ich \\u2665 B\\xFCcher":"foo \\uD834\\uDF06 bar"}'

jsesc([ 'Ich ♥ Bücher', 'foo 𝌆 bar' ], {
  'quotes': 'double'
});
// → '["Ich \\u2665 B\\xFCcher","foo \\uD834\\uDF06 bar"]'
```

#### `numbers`

The default value for the `numbers` option is `'decimal'`. This means that any numeric values are represented using decimal integer literals. Other valid options are `binary`, `octal`, and `hexadecimal`, which result in binary integer literals, octal integer literals, and hexadecimal integer literals, respectively.

```js
jsesc(42, {
  'numbers': 'binary'
});
// → '0b101010'

jsesc(42, {
  'numbers': 'octal'
});
// → '0o52'

jsesc(42, {
  'numbers': 'decimal'
});
// → '42'

jsesc(42, {
  'numbers': 'hexadecimal'
});
// → '0x2A'
```

#### `wrap`

The `wrap` option takes a boolean value (`true` or `false`), and defaults to `false` (disabled). When enabled, the output is a valid JavaScript string literal wrapped in quotes. The type of quotes can be specified through the `quotes` setting.

```js
jsesc('Lorem ipsum "dolor" sit \'amet\' etc.', {
  'quotes': 'single',
  'wrap': true
});
// → '\'Lorem ipsum "dolor" sit \\\'amet\\\' etc.\''
// → "\'Lorem ipsum \"dolor\" sit \\\'amet\\\' etc.\'"

jsesc('Lorem ipsum "dolor" sit \'amet\' etc.', {
  'quotes': 'double',
  'wrap': true
});
// → '"Lorem ipsum \\"dolor\\" sit \'amet\' etc."'
// → "\"Lorem ipsum \\\"dolor\\\" sit \'amet\' etc.\""
```

#### `es6`

The `es6` option takes a boolean value (`true` or `false`), and defaults to `false` (disabled). When enabled, any astral Unicode symbols in the input are escaped using [ECMAScript 6 Unicode code point escape sequences](https://mathiasbynens.be/notes/javascript-escapes#unicode-code-point) instead of using separate escape sequences for each surrogate half. If backwards compatibility with ES5 environments is a concern, don’t enable this setting. If the `json` setting is enabled, the value for the `es6` setting is ignored (as if it was `false`).

```js
// By default, the `es6` option is disabled:
jsesc('foo 𝌆 bar 💩 baz');
// → 'foo \\uD834\\uDF06 bar \\uD83D\\uDCA9 baz'

// To explicitly disable it:
jsesc('foo 𝌆 bar 💩 baz', {
  'es6': false
});
// → 'foo \\uD834\\uDF06 bar \\uD83D\\uDCA9 baz'

// To enable it:
jsesc('foo 𝌆 bar 💩 baz', {
  'es6': true
});
// → 'foo \\u{1D306} bar \\u{1F4A9} baz'
```

#### `escapeEverything`

The `escapeEverything` option takes a boolean value (`true` or `false`), and defaults to `false` (disabled). When enabled, all the symbols in the output are escaped — even printable ASCII symbols.

```js
jsesc('lolwat"foo\'bar', {
  'escapeEverything': true
});
// → '\\x6C\\x6F\\x6C\\x77\\x61\\x74\\"\\x66\\x6F\\x6F\\\'\\x62\\x61\\x72'
// → "\\x6C\\x6F\\x6C\\x77\\x61\\x74\\\"\\x66\\x6F\\x6F\\'\\x62\\x61\\x72"
```

This setting also affects the output for string literals within arrays and objects.

#### `minimal`

The `minimal` option takes a boolean value (`true` or `false`), and defaults to `false` (disabled). When enabled, only a limited set of symbols in the output are escaped:

* U+0000 `\0`
* U+0008 `\b`
* U+0009 `\t`
* U+000A `\n`
* U+000C `\f`
* U+000D `\r`
* U+005C `\\`
* U+2028 `\u2028`
* U+2029 `\u2029`
* whatever symbol is being used for wrapping string literals (based on [the `quotes` option](#quotes))
* [lone surrogates](https://esdiscuss.org/topic/code-points-vs-unicode-scalar-values#content-14)

Note: with this option enabled, jsesc output is no longer guaranteed to be ASCII-safe.

```js
jsesc('foo\u2029bar\nbaz©qux𝌆flops', {
  'minimal': false
});
// → 'foo\\u2029bar\\nbaz©qux𝌆flops'
```

#### `isScriptContext`

The `isScriptContext` option takes a boolean value (`true` or `false`), and defaults to `false` (disabled). When enabled, occurrences of [`</script` and `</style`](https://mathiasbynens.be/notes/etago) in the output are escaped as `<\/script` and `<\/style`, and [`<!--`](https://mathiasbynens.be/notes/etago#comment-8) is escaped as `\x3C!--` (or `\u003C!--` when the `json` option is enabled). This setting is useful when jsesc’s output ends up as part of a `<script>` or `<style>` element in an HTML document.

```js
jsesc('foo</script>bar', {
  'isScriptContext': true
});
// → 'foo<\\/script>bar'
```

#### `compact`

The `compact` option takes a boolean value (`true` or `false`), and defaults to `true` (enabled). When enabled, the output for arrays and objects is as compact as possible; it’s not formatted nicely.

```js
jsesc({ 'Ich ♥ Bücher': 'foo 𝌆 bar' }, {
  'compact': true // this is the default
});
// → '{\'Ich \u2665 B\xFCcher\':\'foo \uD834\uDF06 bar\'}'

jsesc({ 'Ich ♥ Bücher': 'foo 𝌆 bar' }, {
  'compact': false
});
// → '{\n\t\'Ich \u2665 B\xFCcher\': \'foo \uD834\uDF06 bar\'\n}'

jsesc([ 'Ich ♥ Bücher', 'foo 𝌆 bar' ], {
  'compact': false
});
// → '[\n\t\'Ich \u2665 B\xFCcher\',\n\t\'foo \uD834\uDF06 bar\'\n]'
```

This setting has no effect on the output for strings.

#### `indent`

The `indent` option takes a string value, and defaults to `'\t'`. When the `compact` setting is disabled (`false`), the value of the `indent` option is used to format the output for arrays and objects.

```js
jsesc({ 'Ich ♥ Bücher': 'foo 𝌆 bar' }, {
  'compact': false,
  'indent': '\t' // this is the default
});
// → '{\n\t\'Ich \u2665 B\xFCcher\': \'foo \uD834\uDF06 bar\'\n}'

jsesc({ 'Ich ♥ Bücher': 'foo 𝌆 bar' }, {
  'compact': false,
  'indent': '  '
});
// → '{\n  \'Ich \u2665 B\xFCcher\': \'foo \uD834\uDF06 bar\'\n}'

jsesc([ 'Ich ♥ Bücher', 'foo 𝌆 bar' ], {
  'compact': false,
  'indent': '  '
});
// → '[\n  \'Ich \u2665 B\xFCcher\',\n\  t\'foo \uD834\uDF06 bar\'\n]'
```

This setting has no effect on the output for strings.

#### `indentLevel`

The `indentLevel` option takes a numeric value, and defaults to `0`. It represents the current indentation level, i.e. the number of times the value of [the `indent` option](#indent) is repeated.

```js
jsesc(['a', 'b', 'c'], {
  'compact': false,
  'indentLevel': 1
});
// → '[\n\t\t\'a\',\n\t\t\'b\',\n\t\t\'c\'\n\t]'

jsesc(['a', 'b', 'c'], {
  'compact': false,
  'indentLevel': 2
});
// → '[\n\t\t\t\'a\',\n\t\t\t\'b\',\n\t\t\t\'c\'\n\t\t]'
```

#### `json`

The `json` option takes a boolean value (`true` or `false`), and defaults to `false` (disabled). When enabled, the output is valid JSON. [Hexadecimal character escape sequences](https://mathiasbynens.be/notes/javascript-escapes#hexadecimal) and [the `\v` or `\0` escape sequences](https://mathiasbynens.be/notes/javascript-escapes#single) are not used. Setting `json: true` implies `quotes: 'double', wrap: true, es6: false`, although these values can still be overridden if needed — but in such cases, the output won’t be valid JSON anymore.

```js
jsesc('foo\x00bar\xFF\uFFFDbaz', {
  'json': true
});
// → '"foo\\u0000bar\\u00FF\\uFFFDbaz"'

jsesc({ 'foo\x00bar\xFF\uFFFDbaz': 'foo\x00bar\xFF\uFFFDbaz' }, {
  'json': true
});
// → '{"foo\\u0000bar\\u00FF\\uFFFDbaz":"foo\\u0000bar\\u00FF\\uFFFDbaz"}'

jsesc([ 'foo\x00bar\xFF\uFFFDbaz', 'foo\x00bar\xFF\uFFFDbaz' ], {
  'json': true
});
// → '["foo\\u0000bar\\u00FF\\uFFFDbaz","foo\\u0000bar\\u00FF\\uFFFDbaz"]'

// Values that are acceptable in JSON but aren’t strings, arrays, or object
// literals can’t be escaped, so they’ll just be preserved:
jsesc([ 'foo\x00bar', [1, '©', { 'foo': true, 'qux': null }], 42 ], {
  'json': true
});
// → '["foo\\u0000bar",[1,"\\u00A9",{"foo":true,"qux":null}],42]'
// Values that aren’t allowed in JSON are run through `JSON.stringify()`:
jsesc([ undefined, -Infinity ], {
  'json': true
});
// → '[null,null]'
```

**Note:** Using this option on objects or arrays that contain non-string values relies on `JSON.stringify()`. For legacy environments like IE ≤ 7, use [a `JSON` polyfill](http://bestiejs.github.io/json3/).

#### `lowercaseHex`

The `lowercaseHex` option takes a boolean value (`true` or `false`), and defaults to `false` (disabled). When enabled, any alphabetical hexadecimal digits in escape sequences as well as any hexadecimal integer literals (see [the `numbers` option](#numbers)) in the output are in lowercase.

```js
jsesc('Ich ♥ Bücher', {
  'lowercaseHex': true
});
// → 'Ich \\u2665 B\\xfccher'
//                    ^^

jsesc(42, {
  'numbers': 'hexadecimal',
  'lowercaseHex': true
});
// → '0x2a'
//      ^^
```

### `jsesc.version`

A string representing the semantic version number.

### Using the `jsesc` binary

To use the `jsesc` binary in your shell, simply install jsesc globally using npm:

```bash
npm install -g jsesc
```

After that you’re able to escape strings from the command line:

```bash
$ jsesc 'föo ♥ bår 𝌆 baz'
f\xF6o \u2665 b\xE5r \uD834\uDF06 baz
```

To escape arrays or objects containing string values, use the `-o`/`--object` option:

```bash
$ jsesc --object '{ "föo": "♥", "bår": "𝌆 baz" }'
{'f\xF6o':'\u2665','b\xE5r':'\uD834\uDF06 baz'}
```

To prettify the output in such cases, use the `-p`/`--pretty` option:

```bash
$ jsesc --pretty '{ "föo": "♥", "bår": "𝌆 baz" }'
{
  'f\xF6o': '\u2665',
  'b\xE5r': '\uD834\uDF06 baz'
}
```

For valid JSON output, use the `-j`/`--json` option:

```bash
$ jsesc --json --pretty '{ "föo": "♥", "bår": "𝌆 baz" }'
{
  "f\u00F6o": "\u2665",
  "b\u00E5r": "\uD834\uDF06 baz"
}
```

Read a local JSON file, escape any non-ASCII symbols, and save the result to a new file:

```bash
$ jsesc --json --object < data-raw.json > data-escaped.json
```

Or do the same with an online JSON file:

```bash
$ curl -sL "http://git.io/aorKgQ" | jsesc --json --object > data-escaped.json
```

See `jsesc --help` for the full list of options.

## Support

As of v3.0.0, jsesc supports Node.js v6+ only.

Older versions (up to jsesc v1.3.0) support Chrome 27, Firefox 3, Safari 4, Opera 10, IE 6, Node.js v6.0.0, Narwhal 0.3.2, RingoJS 0.8-0.11, PhantomJS 1.9.0, and Rhino 1.7RC4. **Note:** Using the `json` option on objects or arrays that contain non-string values relies on `JSON.parse()`. For legacy environments like IE ≤ 7, use [a `JSON` polyfill](https://bestiejs.github.io/json3/).

## Author

| [![twitter/mathias](https://gravatar.com/avatar/24e08a9ea84deb17ae121074d0f17125?s=70)](https://twitter.com/mathias "Follow @mathias on Twitter") |
|---|
| [Mathias Bynens](https://mathiasbynens.be/) |

## License

This library is available under the [MIT](https://mths.be/mit) license.


---

# rehype-raw

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

**[rehype][]** plugin to parse the tree (and raw nodes) again, keeping
positional info okay.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`unified().use(rehypeRaw[, options])`](#unifieduserehyperaw-options)
    *   [`Options`](#options)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Security](#security)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package is a [unified][] ([rehype][]) plugin to parse a document again.
To understand how it works, requires knowledge of ASTs (specifically, [hast][]).
This plugin passes each node and embedded raw HTML through an HTML parser
([`parse5`][parse5]), to recreate a tree exactly as how a browser would parse
it, while keeping the original data and positional info intact.

**unified** is a project that transforms content with abstract syntax trees
(ASTs).
**rehype** adds support for HTML to unified.
**hast** is the HTML AST that rehype uses.
This is a rehype plugin that parses the tree again.

## When should I use this?

This plugin is particularly useful when coming from markdown and wanting to
support HTML embedded inside that markdown (which requires passing
`allowDangerousHtml: true` to `remark-rehype`).
Markdown dictates how, say, a list item or emphasis can be parsed.
We can use that to turn the markdown syntax tree into an HTML syntax tree.
But markdown also dictates that things that look like HTML, are passed through
untouched, even when it just looks like XML but doesn’t really make sense, so we
can’t normally use these strings of “HTML” to create an HTML syntax tree.
This plugin can.
It can be used to take those strings of HTML and include them into the syntax
tree as actual nodes.

If your final result is HTML and you trust content, then “strings” are fine
(you can pass `allowDangerousHtml: true` to `rehype-stringify`, which passes
HTML through untouched).
But there are two main cases where a proper syntax tree is preferred:

*   rehype plugins need a proper syntax tree as they operate on actual nodes to
    inspect or transform things, they can’t operate on strings of HTML
*   other output formats (React, MDX, etc) need actual nodes and can’t handle
    strings of HTML

This plugin is built on [`hast-util-raw`][hast-util-raw], which does the work on
syntax trees.
rehype focusses on making it easier to transform content by abstracting such
internals away.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install rehype-raw
```

In Deno with [`esm.sh`][esmsh]:

```js
import rehypeRaw from 'https://esm.sh/rehype-raw@7'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import rehypeRaw from 'https://esm.sh/rehype-raw@7?bundle'
</script>
```

## Use

Say we have the following markdown file `example.md`:

```markdown
<div class="note">

A mix of *markdown* and <em>HTML</em>.

</div>
```

…and our module `example.js` looks as follows:

```js
import rehypeDocument from 'rehype-document'
import rehypeFormat from 'rehype-format'
import rehypeRaw from 'rehype-raw'
import rehypeStringify from 'rehype-stringify'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import {read} from 'to-vfile'
import {unified} from 'unified'

const file = await unified()
  .use(remarkParse)
  .use(remarkRehype, {allowDangerousHtml: true})
  .use(rehypeRaw)
  .use(rehypeDocument, {title: '🙌'})
  .use(rehypeFormat)
  .use(rehypeStringify)
  .process(await read('example.md'))

console.log(String(file))
```

…now running `node example.js` yields:

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>🙌</title>
    <meta name="viewport" content="width=device-width, initial-scale=1">
  </head>
  <body>
    <div class="note">
      <p>A mix of <em>markdown</em> and <em>HTML</em>.</p>
    </div>
  </body>
</html>
```

## API

This package exports no identifiers.
The default export is [`rehypeRaw`][api-rehype-raw].

### `unified().use(rehypeRaw[, options])`

Parse the tree (and raw nodes) again, keeping positional info okay.

###### Parameters

*   `options` ([`Options`][api-options], optional)
    — configuration

###### Returns

Transform ([`Transformer`][transformer]).

### `Options`

Configuration (TypeScript type).

###### Fields

*   `passThrough` (`Array<string>`, default: `[]`)
    — list of custom hast node types to pass through (as in, keep); this option
    is a bit advanced as it requires knowledge of ASTs, so we defer to the docs
    in [`hast-util-raw`][hast-util-raw]

## Types

This package is fully typed with [TypeScript][].
It exports the additional type [`Options`][api-options].

The `Raw` node type is registered by and exposed from
[`remark-rehype`][remark-rehype].

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, `rehype-raw@^7`, compatible
with Node.js 16.

## Security

The `allowDangerousHtml` option in [`remark-rehype`][remark-rehype] is
dangerous, so see that plugin on how to make it safe.
Otherwise, this plugin is safe.

## Contribute

See [`contributing.md`][contributing] in [`rehypejs/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/rehypejs/rehype-raw/workflows/main/badge.svg

[build]: https://github.com/rehypejs/rehype-raw/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/rehypejs/rehype-raw.svg

[coverage]: https://codecov.io/github/rehypejs/rehype-raw

[downloads-badge]: https://img.shields.io/npm/dm/rehype-raw.svg

[downloads]: https://www.npmjs.com/package/rehype-raw

[size-badge]: https://img.shields.io/bundlejs/size/rehype-raw

[size]: https://bundlejs.com/?q=rehype-raw

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/rehypejs/rehype/discussions

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[health]: https://github.com/rehypejs/.github

[contributing]: https://github.com/rehypejs/.github/blob/HEAD/contributing.md

[support]: https://github.com/rehypejs/.github/blob/HEAD/support.md

[coc]: https://github.com/rehypejs/.github/blob/HEAD/code-of-conduct.md

[license]: license

[author]: https://wooorm.com

[typescript]: https://www.typescriptlang.org

[parse5]: https://github.com/inikulin/parse5

[unified]: https://github.com/unifiedjs/unified

[transformer]: https://github.com/unifiedjs/unified?tab=readme-ov-file#transformer

[hast]: https://github.com/syntax-tree/hast

[hast-util-raw]: https://github.com/syntax-tree/hast-util-raw

[rehype]: https://github.com/rehypejs/rehype

[remark-rehype]: https://github.com/remarkjs/remark-rehype

[api-options]: #options

[api-rehype-raw]: #unifieduserehyperaw-options


---

# rehype-recma

[![Build][badge-build-image]][badge-build-url]
[![Coverage][badge-coverage-image]][badge-coverage-url]
[![Downloads][badge-downloads-image]][badge-downloads-url]
[![Size][badge-size-image]][badge-size-url]
[![Sponsors][badge-sponsors-image]][badge-collective-url]
[![Backers][badge-backers-image]][badge-collective-url]
[![Chat][badge-chat-image]][badge-chat-url]

**[rehype][github-rehype]** plugin to transform HTML to JS.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`unified().use(rehypeRecma[, options])`](#unifieduserehyperecma-options)
  * [`Options`](#options)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package is a [unified][github-unified] ([rehype][github-rehype]) plugin
that can turn HTML into JavaScript.

## When should I use this?

Use this when you want to integrate static HTML into some JavaScript
application.

If you don’t use plugins and access syntax trees manually,
you can directly use [`hast-util-to-estree`][github-hast-util-to-estree],
which is used inside this plugin.

## Install

This package is [ESM only][github-gist-esm].
In Node.js (version 16+),
install with [npm][npm-install]:

```sh
npm install rehype-recma
```

In Deno with [`esm.sh`][esmsh]:

```js
import rehypeRecma from 'https://esm.sh/rehype-recma@1'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import rehypeRecma from 'https://esm.sh/rehype-recma@1?bundle'
</script>
```

## Use

Say we have the following module `example.js`:

```js
import recmaJsx from 'recma-jsx'
import recmaStringify from 'recma-stringify'
import rehypeParse from 'rehype-parse'
import rehypeRecma from 'rehype-recma'
import {unified} from 'unified'

const file = await unified()
  .use(rehypeParse, {fragment: true})
  .use(rehypeRecma)
  .use(recmaJsx)
  .use(recmaStringify)
  .process('<p>Hi!<h1>Hello!')

console.log(String(file))
```

…running that with `node example.js` yields:

```jsx
<><p>{"Hi!"}</p><h1>{"Hello!"}</h1></>;
```

## API

This package exports no identifiers.
The default export is [`rehypeRecma`][api-rehype-recma].

### `unified().use(rehypeRecma[, options])`

Plugin to transform HTML (hast) to JS (estree).

###### Parameters

* `options` ([`Options`][api-options], optional)
  — configuration

###### Returns

Transform ([`Transformer`][github-unified-transformer]).

### `Options`

Configuration (TypeScript type).

Same as [`Options`][github-hast-util-to-estree-options]
from `hast-util-to-estree`.

## Types

This package is fully typed with [TypeScript][].
It exports the additional type [`Options`][api-options].

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release,
we drop support for unmaintained versions of Node.
This means we try to keep the current release line,
`rehype-recma@1`,
compatible with Node.js 16.

## Security

As **recma** works on JS and evaluating JS is unsafe,
use of recma can also be unsafe.
Do not evaluate unsafe code.

## Contribute

See [§ Contribute][mdxjs-contribute] on our site for ways to get started.
See [§ Support][mdxjs-support] for ways to get help.

This project has a [code of conduct][health-coc].
By interacting with this repository,
organization,
or community you agree to abide by its terms.

## License

[MIT][file-license] © [Titus Wormer][wooorm]

<!-- Definitions -->

[api-options]: #options

[api-rehype-recma]: #unifieduserehyperecma-options

[badge-backers-image]: https://opencollective.com/unified/backers/badge.svg

[badge-build-image]: https://github.com/mdx-js/recma/actions/workflows/main.yml/badge.svg

[badge-build-url]: https://github.com/mdx-js/recma/actions

[badge-collective-url]: https://opencollective.com/unified

[badge-coverage-image]: https://img.shields.io/codecov/c/github/mdx-js/recma.svg

[badge-coverage-url]: https://codecov.io/github/mdx-js/recma

[badge-downloads-image]: https://img.shields.io/npm/dm/rehype-recma.svg

[badge-downloads-url]: https://www.npmjs.com/package/rehype-recma

[badge-size-image]: https://img.shields.io/bundlejs/size/rehype-recma

[badge-size-url]: https://bundlejs.com/?q=rehype-recma

[badge-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg

[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg

[badge-chat-url]: https://github.com/mdx-js/mdx/discussions

[esmsh]: https://esm.sh

[file-license]: license

[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[github-hast-util-to-estree-options]: https://github.com/syntax-tree/hast-util-to-estree#options

[github-hast-util-to-estree]: https://github.com/syntax-tree/hast-util-to-estree

[github-rehype]: https://github.com/rehypejs/rehype

[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer

[github-unified]: https://github.com/unifiedjs/unified

[health-coc]: https://github.com/mdx-js/.github/blob/main/code-of-conduct.md

[mdxjs-contribute]: https://mdxjs.com/community/contribute/

[mdxjs-support]: https://mdxjs.com/community/support/

[npm-install]: https://docs.npmjs.com/cli/install

[typescript]: https://www.typescriptlang.org

[wooorm]: https://wooorm.com


---

# relateurl [![NPM Version][npm-image]][npm-url] [![Build Status][travis-image]][travis-url] [![Dependency Status][david-image]][david-url]

> Minify URLs by converting them from absolute to relative.

If you were to use this library on a website like `http://example.com/dir1/dir1-1/`, you would get results such as:

| Before                                      | After                                |
| :------------------------------------------ | :----------------------------------- |
| `http://example.com/dir1/dir1-2/index.html` | `../dir1-2/`                         |
| `http://example.com/dir2/dir2-1/`           | `/dir2/dir2-1/`                      |
| `http://example.com/dir1/dir1-1/`           | ` `                                  |
| `https://example.com/dir1/dir1-1/`          | `https://example.com/dir1/dir1-1/`   |
| `http://google.com:80/dir/`                 | `//google.com/dir/`                  |
| `../../../../../../../../#anchor`           | `/#anchor`                           |

**All string parsing.** *No* directory browsing. It is thoroughly tested, very fast and lightweight with zero external dependencies.

## Getting Started

This utility requires [Node.js](http://nodejs.org/) `>= 0.10`. To install, type this at the command line:
```
npm install relateurl --save-dev
```

### Options

#### options.defaultPorts
Type: `Object`   
Default value: `{ftp:21, http:80, https:443}`  

Extend the list with any ports you need. Any URLs containing these default ports will have them removed. Example: `http://example.com:80/` will become `http://example.com/`.

#### options.directoryIndexes
Type: `Array`   
Default value: `["index.html"]`  

Extend the list with any resources you need. Works with [`options.removeDirectoryIndexes`](#options.removeDirectoryIndexes).

#### options.ignore_www
Type: `Boolean`  
Default value: `false`  

This will, for example, consider any domains containing `http://www.example.com/` to be related to any that contain `http://example.com/`.

#### options.output
Type: constant or `String`  
Choices: `RelateUrl.ABSOLUTE`,`RelateUrl.PATH_RELATIVE`,`RelateUrl.ROOT_RELATIVE`,`RelateUrl.SHORTEST`  
Choices: `"absolute"`,`"pathRelative"`,`"rootRelative"`,`"shortest"`  
Default value: `RelateUrl.SHORTEST`  

`RelateUrl.ABSOLUTE` will produce an absolute URL. Overrides [`options.schemeRelative`](#options.schemeRelative) with a value of `false`.  
`RelateUrl.PATH_RELATIVE` will produce something like `../child-of-parent/etc/`.  
`RelateUrl.ROOT_RELATIVE` will produce something like `/child-of-root/etc/`.  
`RelateUrl.SHORTEST` will choose whichever is shortest between root- and path-relative.  

#### options.rejectedSchemes
Type: `Array`   
Default value: `["data","javascript","mailto"]`  

Extend the list with any additional schemes. Example: `javascript:something` will not be modified.

#### options.removeAuth
Type: `Boolean`   
Default value: `false`  

Remove user authentication information from the output URL.

#### options.removeDirectoryIndexes
Type: `Boolean`   
Default value: `true`  

Remove any resources that match any found in [`options.directoryIndexes`](#options.directoryIndexes).

#### options.removeEmptyQueries
Type: `Boolean`   
Default value: `false`  

Remove empty query variables. Example: `http://domain.com/?var1&var2=&var3=asdf` will become `http://domain.com/?var3=adsf`. This does not apply to unrelated URLs (with other protocols, auths, hosts and/or ports).

#### options.removeRootTrailingSlash
Type: `Boolean`   
Default value: `true`  

Remove trailing slashes from root paths. Example: `http://domain.com/?var` will become `http://domain.com?var` while `http://domain.com/dir/?var` will not be modified.

#### options.schemeRelative
Type: `Boolean`   
Default value: `true`  

Output URLs relative to the scheme. Example: `http://example.com/` will become `//example.com/`.

#### options.site
Type: `String`   
Default value: `undefined`  

An options-based version of the [`from`](#examples) argument. If both are specified, `from` takes priority.

#### options.slashesDenoteHost
Type: `Boolean`   
Default value: `true`  

Passed to Node's [`url.parse`](http://nodejs.org/api/url.html#url_url_parse_urlstr_parsequerystring_slashesdenotehost).

### Examples
This library can be used as a [function for single-use](#single-instance) or as a [class for multiple conversions](#reusable-instances).

Upon successful conversion, a `String` will be returned. If an issue is encountered while parsing `from`, an error will be thrown.

#### Single Instance
```js
var RelateUrl = require("relateurl");

var result = RelateUrl.relate(from, to, options);
```

#### Reusable Instances
```js
var RelateUrl = require("relateurl");

var instance = new RelateUrl(from, options);

var result1 = instance.relate(to1);
var result2 = instance.relate(to2, customOptions);
var result3 = instance.relate(to3);
```

## FAQ
1. **Why bother writing/using this?**  
To aid in further minifying HTML, mainly for the purpose of faster page loads and SEO. It's been integrated into [HTMLMinifier](https://github.com/kangax/html-minifier).

2. **Why not just use Node's `url.parse`, `url.resolve` and `path.relative`?**  
`url.parse` *is* used, but `url.resolve` and `path.relative` are both slower and less powerful than this library.


## Release History
* 0.2.7 Node v6 support
* 0.2.6 minor enhancements
* 0.2.5 added `options.removeRootTrailingSlash`
* 0.2.4 added `options.site`
* 0.2.3 added browserify npm-script
* 0.2.2 removed task runner
* 0.2.1 shorten resource- and query-relative URLs, test variations list with other site URLs
* 0.2.0 code cleanup, `options.removeEmptyQueries=true` only applied to unrelated URLs
* 0.1.0 initial release


## Roadmap
* 0.2.8 check if queries are the same, regardless of param order
* 0.2.8 possible [scheme exclusions](http://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml) such as `tel:`
* 0.2.8 decipher and return invalid input (special cases) to complete test suite
* 0.3.0 test `options.slashesDenoteHost=false`, add something like `options.externalDirectoryIndexes=[]` for external sites


[npm-image]: https://img.shields.io/npm/v/relateurl.svg
[npm-url]: https://npmjs.org/package/relateurl
[travis-image]: https://img.shields.io/travis/stevenvachon/relateurl.svg
[travis-url]: https://travis-ci.org/stevenvachon/relateurl
[david-image]: https://img.shields.io/david/stevenvachon/relateurl.svg
[david-url]: https://david-dm.org/stevenvachon/relateurl


---

# remark-directive

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

**[remark][]** plugin to support the [generic directives
proposal][commonmark-prop] (`:cite[smith04]`,
`::youtube[Video of a cat in a box]{v=01ab2cd3efg}`, and such).

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`unified().use(remarkDirective[, options])`](#unifieduseremarkdirective-options)
  * [`Options`](#options)
* [Examples](#examples)
  * [Example: YouTube](#example-youtube)
  * [Example: Styled blocks](#example-styled-blocks)
* [Authoring](#authoring)
* [HTML](#html)
* [CSS](#css)
* [Syntax](#syntax)
* [Syntax tree](#syntax-tree)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Related](#related)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package is a [unified][] ([remark][]) plugin to add support for directives:
one syntax for arbitrary extensions in markdown.

## When should I use this?

Directives are one of the four ways to extend markdown: an arbitrary extension
syntax (see [Extending markdown][micromark-extending-markdown] in micromark’s
docs for the alternatives and more info).
This mechanism works well when you control the content: who authors it, what
tools handle it, and where it’s displayed.
When authors can read a guide on how to embed a tweet but are not expected to
know the ins and outs of HTML or JavaScript.
Directives don’t work well if you don’t know who authors content, what tools
handle it, and where it ends up.
Example use cases are a docs website for a project or product, or blogging
tools and static site generators.

If you *just* want to turn markdown into HTML (with maybe a few extensions such
as this one), we recommend [`micromark`][micromark] with
[`micromark-extension-directive`][micromark-extension-directive] instead.
If you don’t use plugins and want to access the syntax tree, you can use
[`mdast-util-from-markdown`][mdast-util-from-markdown] with
[`mdast-util-directive`][mdast-util-directive].

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install remark-directive
```

In Deno with [`esm.sh`][esmsh]:

```js
import remarkDirective from 'https://esm.sh/remark-directive@3'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import remarkDirective from 'https://esm.sh/remark-directive@3?bundle'
</script>
```

## Use

Say our document `example.md` contains:

```markdown
:::main{#readme}

Lorem:br
ipsum.

::hr{.red}

A :i[lovely] language know as :abbr[HTML]{title="HyperText Markup Language"}.

:::
```

…and our module `example.js` contains:

```js
/**
 * @import {} from 'mdast-util-directive'
 * @import {} from 'mdast-util-to-hast'
 * @import {Root} from 'mdast'
 */

import {h} from 'hastscript'
import rehypeFormat from 'rehype-format'
import rehypeStringify from 'rehype-stringify'
import remarkDirective from 'remark-directive'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import {read} from 'to-vfile'
import {unified} from 'unified'
import {visit} from 'unist-util-visit'

const file = await unified()
  .use(remarkParse)
  .use(remarkDirective)
  .use(myRemarkPlugin)
  .use(remarkRehype)
  .use(rehypeFormat)
  .use(rehypeStringify)
  .process(await read('example.md'))

console.log(String(file))

// This plugin is an example to let users write HTML with directives.
// It’s informative but rather useless.
// See below for others examples.
function myRemarkPlugin() {
  /**
   * @param {Root} tree
   *   Tree.
   * @returns {undefined}
   *   Nothing.
   */
  return function (tree) {
    visit(tree, function (node) {
      if (
        node.type === 'containerDirective' ||
        node.type === 'leafDirective' ||
        node.type === 'textDirective'
      ) {
        const data = node.data || (node.data = {})
        const hast = h(node.name, node.attributes || {})

        data.hName = hast.tagName
        data.hProperties = hast.properties
      }
    })
  }
}
```

…then running `node example.js` yields:

```html
<main id="readme">
  <p>Lorem<br>ipsum.</p>
  <hr class="red">
  <p>A <i>lovely</i> language know as <abbr title="HyperText Markup Language">HTML</abbr>.</p>
</main>
```

## API

This package exports no identifiers.
The default export is [`remarkDirective`][api-remark-directive].

### `unified().use(remarkDirective[, options])`

Add support for generic directives.

###### Parameters

* `options` ([`Options`][api-options], optional)
  — configuration

###### Returns

Nothing (`undefined`).

###### Notes

Doesn’t handle the directives:
[create your own plugin][unified-create-plugin] to do that.

### `Options`

Configuration (TypeScript type).

###### Fields

* `collapseEmptyAttributes`
  (`boolean`, default: `true`)
  — collapse empty attributes: get `title` instead of `title=""`
* `preferShortcut`
  (`boolean`, default: `true`)
  — prefer `#` and `.` shortcuts for `id` and `class`
* `preferUnquoted`
  (`boolean`, default: `false`)
  — leave attributes unquoted if that results in less bytes
* `quoteSmart`
  (`boolean`, default: `false`)
  — use the other quote if that results in less bytes
* `quote`
  (`'"'` or `"'"`,
  default: the [`quote`][quote] used by `remark-stringify` for titles)
  — preferred quote to use around attribute values

## Examples

### Example: YouTube

This example shows how directives can be used for YouTube embeds.
It’s based on the example in Use above.
If `myRemarkPlugin` was replaced with this function:

```js
/**
 * @import {} from 'mdast-util-directive'
 * @import {} from 'mdast-util-to-hast'
 * @import {Root} from 'mdast'
 * @import {VFile} from 'vfile'
 */

import {visit} from 'unist-util-visit'

// This plugin is an example to turn `::youtube` into iframes.
function myRemarkPlugin() {
  /**
   * @param {Root} tree
   *   Tree.
   * @param {VFile} file
   *   File.
   * @returns {undefined}
   *   Nothing.
   */
  return (tree, file) => {
    visit(tree, function (node) {
      if (
        node.type === 'containerDirective' ||
        node.type === 'leafDirective' ||
        node.type === 'textDirective'
      ) {
        if (node.name !== 'youtube') return

        const data = node.data || (node.data = {})
        const attributes = node.attributes || {}
        const id = attributes.id

        if (node.type === 'textDirective') {
          file.fail(
            'Unexpected `:youtube` text directive, use two colons for a leaf directive',
            node
          )
        }

        if (!id) {
          file.fail('Unexpected missing `id` on `youtube` directive', node)
        }

        data.hName = 'iframe'
        data.hProperties = {
          src: 'https://www.youtube.com/embed/' + id,
          width: 200,
          height: 200,
          frameBorder: 0,
          allow: 'picture-in-picture',
          allowFullScreen: true
        }
      }
    })
  }
}
```

…and `example.md` contains:

```markdown
# Cat videos

::youtube[Video of a cat in a box]{#01ab2cd3efg}
```

…then running `node example.js` yields:

```html
<h1>Cat videos</h1>
<iframe src="https://www.youtube.com/embed/01ab2cd3efg" width="200" height="200" frameborder="0" allow="picture-in-picture" allowfullscreen>Video of a cat in a box</iframe>
```

### Example: Styled blocks

> 👉 **Note**: This is sometimes called admonitions, callouts, etc.

This example shows how directives can be used to style blocks.
It’s based on the example in Use above.
If `myRemarkPlugin` was replaced with this function:

```js
/**
 * @import {} from 'mdast-util-directive'
 * @import {} from 'mdast-util-to-hast'
 * @import {Root} from 'mdast'
 */

import {h} from 'hastscript'
import {visit} from 'unist-util-visit'

// This plugin is an example to turn `::note` into divs, passing arbitrary
// attributes.
function myRemarkPlugin() {
  /**
   * @param {Root} tree
   *   Tree.
   * @returns {undefined}
   *   Nothing.
   */
  return (tree) => {
    visit(tree, (node) => {
      if (
        node.type === 'containerDirective' ||
        node.type === 'leafDirective' ||
        node.type === 'textDirective'
      ) {
        if (node.name !== 'note') return

        const data = node.data || (node.data = {})
        const tagName = node.type === 'textDirective' ? 'span' : 'div'

        data.hName = tagName
        data.hProperties = h(tagName, node.attributes || {}).properties
      }
    })
  }
}
```

…and `example.md` contains:

```markdown
# How to use xxx

You can use xxx.

:::note{.warning}
if you chose xxx, you should also use yyy somewhere…
:::
```

…then running `node example` yields:

```html
<h1>How to use xxx</h1>
<p>You can use xxx.</p>
<div class="warning">
  <p>if you chose xxx, you should also use yyy somewhere…</p>
</div>
```

## Authoring

When authoring markdown with directives, keep in mind that they don’t work in
most places.
On your own site it can be great!

## HTML

You can define how directives are turned into HTML.
If directives are not handled, they do not emit anything.

## CSS

How to display directives is left as an exercise for the reader.

## Syntax

See [*Syntax* in
`micromark-extension-directive`](https://github.com/micromark/micromark-extension-directive#syntax).

## Syntax tree

See [*Syntax tree* in
`mdast-util-directive`](https://github.com/syntax-tree/mdast-util-directive#syntax-tree).

## Types

This package is fully typed with [TypeScript][].
It exports no additional options.

If you’re working with the syntax tree, you can register the new node types
with `@types/mdast` by adding a reference:

```js
/**
 * @import {} from 'mdast-util-directive'
 * @import {Root} from 'mdast'
 */

import {visit} from 'unist-util-visit'

function myRemarkPlugin() {
  /**
   * @param {Root} tree
   *   Tree.
   * @returns {undefined}
   *   Nothing.
   */
  return (tree) => {
    visit(tree, function (node) {
      console.log(node) // `node` can now be one of the nodes for directives.
    })
  }
}
```

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, `remark-directive@^3`,
compatible with Node.js 16.

## Security

Use of `remark-directive` does not involve **[rehype][]** ([hast][]) or user
content so there are no openings for [cross-site scripting (XSS)][wiki-xss]
attacks.

## Related

* [`remark-gfm`](https://github.com/remarkjs/remark-gfm)
  — support GFM (autolink literals, footnotes, strikethrough, tables,
  tasklists)
* [`remark-frontmatter`](https://github.com/remarkjs/remark-frontmatter)
  — support frontmatter (YAML, TOML, and more)
* [`remark-math`](https://github.com/remarkjs/remark-math)
  — support math
* [`remark-mdx`](https://github.com/mdx-js/mdx/tree/main/packages/remark-mdx)
  — support MDX (ESM, JSX, expressions)

## Contribute

See [`contributing.md`][contributing] in [`remarkjs/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/remarkjs/remark-directive/workflows/main/badge.svg

[build]: https://github.com/remarkjs/remark-directive/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/remarkjs/remark-directive.svg

[coverage]: https://codecov.io/github/remarkjs/remark-directive

[downloads-badge]: https://img.shields.io/npm/dm/remark-directive.svg

[downloads]: https://www.npmjs.com/package/remark-directive

[size-badge]: https://img.shields.io/bundlejs/size/remark-directive

[size]: https://bundlejs.com/?q=remark-directive

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/remarkjs/remark/discussions

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[health]: https://github.com/remarkjs/.github

[contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md

[support]: https://github.com/remarkjs/.github/blob/main/support.md

[coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md

[license]: license

[author]: https://wooorm.com

[commonmark-prop]: https://talk.commonmark.org/t/generic-directives-plugins-syntax/444

[hast]: https://github.com/syntax-tree/hast

[mdast-util-directive]: https://github.com/syntax-tree/mdast-util-directive

[mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown

[micromark]: https://github.com/micromark/micromark

[micromark-extension-directive]: https://github.com/micromark/micromark-extension-directive

[micromark-extending-markdown]: https://github.com/micromark/micromark#extending-markdown

[quote]: https://github.com/remarkjs/remark/tree/main/packages/remark-stringify#options

[rehype]: https://github.com/rehypejs/rehype

[remark]: https://github.com/remarkjs/remark

[typescript]: https://www.typescriptlang.org

[unified]: https://github.com/unifiedjs/unified

[unified-create-plugin]: https://unifiedjs.com/learn/guide/create-a-plugin/

[wiki-xss]: https://en.wikipedia.org/wiki/Cross-site_scripting

[api-remark-directive]: #unifieduseremarkdirective-options

[api-options]: #options


---

remark-emoji
============
[![CI][ci-badge]][ci]
[![npm][npm-badge]][npm]

[remark-emoji][npm] is a [remark](https://github.com/remarkjs/remark) plugin to replace `:emoji:` to real UTF-8
emojis in text. Accessibility support and Emoticon support are optionally available.

## Demo

You can find a demo in the following [Codesandbox](https://codesandbox.io/s/remark-emoji-example-osvyi).

## Usage

```
remark().use(emoji [, options]);
```

```javascript
import {remark} from 'remark';
import emoji from 'remark-emoji';

const doc = 'Emojis in this text will be replaced: :dog: :+1:';
const processor = remark().use(emoji);
const file = await processor.process(doc);

console.log(String(file));
// => Emojis in this text will be replaced: 🐶 👍
```

Note that this package is [ESM only][esm-only] from v3.0.0 since remark packages migrated to ESM.

## Options

### `options.accessible`

Setting to `true` makes the converted emoji text accessible with `role` and `aria-label` attributes. Each emoji
text is wrapped with `<span>` element. Note that `role` attribute is not allowed by default. Please add it to
the sanitization schema used by remark's HTML transformer.

For example,

```javascript
import {remark} from 'remark';
import toHtml from 'remark-html';
import {defaultSchema} from 'hast-util-sanitize'
import emoji from 'remark-emoji';

// Allow using `role` attribute in transformed HTML document
const schema = structuredClone(defaultSchema);
if ('span' in schema.attributes) {
    schema.attributes.span.push('role');
} else {
    schema.attributes.span = ['role'];
}

const processor = remark()
    .use(emoji, { accessible: true })
    .use(toHtml, { sanitize: schema });
const file = await processor.process('Hello :dog:!');
console.log(String(file));
```

yields

```html
Hello <span role="img" aria-label="dog emoji">🐶</span>!
```

Default value is `false`.

### `options.padSpaceAfter`

Setting to `true` means that an extra whitespace is added after emoji.
This is useful when browser handle emojis with half character length and following character is hidden.
Default value is `false`.

### `options.emoticon`

Setting to `true` means that [emoticon](https://www.npmjs.com/package/emoticon) shortcodes are supported (e.g. :-)
will be replaced by 😃). Default value is `false`.

## TypeScript support

remark-emoji package contains [TypeScript](https://www.typescriptlang.org/) type definitions. The package is ready
for use with TypeScript.

Note that the legacy `node` (or `node10`) resolution at [`moduleResolution`](https://www.typescriptlang.org/tsconfig#moduleResolution)
is not available since it enforces CommonJS module resolution and this package is ESM only. Please use `node16`,
`bundler`, or `nodenext` to enable ESM module resolution.

## License

Distributed under [the MIT License](LICENSE).



[ci-badge]: https://github.com/rhysd/remark-emoji/workflows/CI/badge.svg?branch=master&event=push
[ci]: https://github.com/rhysd/remark-emoji/actions?query=workflow%3ACI
[npm-badge]: https://badge.fury.io/js/remark-emoji.svg
[npm]: https://www.npmjs.com/package/remark-emoji
[esm-only]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c


---

# remark-frontmatter

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

**[remark][]** plugin to support frontmatter (YAML, TOML, and more).

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`unified().use(remarkFrontmatter[, options])`](#unifieduseremarkfrontmatter-options)
    *   [`Options`](#options)
*   [Examples](#examples)
    *   [Example: different markers and fences](#example-different-markers-and-fences)
    *   [Example: frontmatter as metadata](#example-frontmatter-as-metadata)
    *   [Example: frontmatter in MDX](#example-frontmatter-in-mdx)
*   [Authoring](#authoring)
*   [HTML](#html)
*   [CSS](#css)
*   [Syntax](#syntax)
*   [Syntax tree](#syntax-tree)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Security](#security)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package is a [unified][] ([remark][]) plugin to add support for YAML, TOML,
and other frontmatter.

Frontmatter is a metadata format in front of the content.
It’s typically written in YAML and is often used with markdown.

This plugin follow how GitHub handles frontmatter.
GitHub only supports YAML frontmatter, but this plugin also supports different
flavors (such as TOML).

## When should I use this?

You can use frontmatter when you want authors, that have some markup
experience, to configure where or how the content is displayed or supply
metadata about content, and know that the markdown is only used in places
that support frontmatter.
A good example use case is markdown being rendered by (static) site generators.

If you *just* want to turn markdown into HTML (with maybe a few extensions such
as frontmatter), we recommend [`micromark`][micromark] with
[`micromark-extension-frontmatter`][micromark-extension-frontmatter] instead.
If you don’t use plugins and want to access the syntax tree, you can use
[`mdast-util-from-markdown`][mdast-util-from-markdown] with
[`mdast-util-frontmatter`][mdast-util-frontmatter].

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install remark-frontmatter
```

In Deno with [`esm.sh`][esmsh]:

```js
import remarkFrontmatter from 'https://esm.sh/remark-frontmatter@5'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import remarkFrontmatter from 'https://esm.sh/remark-frontmatter@5?bundle'
</script>
```

## Use

Say our document `example.md` contains:

```markdown
+++
layout = "solar-system"
+++

# Jupiter
```

…and our module `example.js` contains:

```js
import remarkFrontmatter from 'remark-frontmatter'
import remarkParse from 'remark-parse'
import remarkStringify from 'remark-stringify'
import {unified} from 'unified'
import {read} from 'to-vfile'

const file = await unified()
  .use(remarkParse)
  .use(remarkStringify)
  .use(remarkFrontmatter, ['yaml', 'toml'])
  .use(function () {
    return function (tree) {
      console.dir(tree)
    }
  })
  .process(await read('example.md'))

console.log(String(file))
```

…then running `node example.js` yields:

```js
{
  type: 'root',
  children: [
    {type: 'toml', value: 'layout = "solar-system"', position: [Object]},
    {type: 'heading', depth: 1, children: [Array], position: [Object]}
  ],
  position: {
    start: {line: 1, column: 1, offset: 0},
    end: {line: 6, column: 1, offset: 43}
  }
}
```

```markdown
+++
layout = "solar-system"
+++

# Jupiter
```

## API

This package exports no identifiers.
The default export is [`remarkFrontmatter`][api-remark-frontmatter].

### `unified().use(remarkFrontmatter[, options])`

Add support for frontmatter.

###### Parameters

*   `options` ([`Options`][api-options], default: `'yaml'`)
    — configuration

###### Returns

Nothing (`undefined`).

###### Notes

Doesn’t parse the data inside them:
[create your own plugin][unified-create-plugin] to do that.

### `Options`

Configuration (TypeScript type).

###### Type

```ts
type Options = Array<Matter | Preset> | Matter | Preset

/**
 * Sequence.
 *
 * Depending on how this structure is used, it reflects a marker or a fence.
 */
export type Info = {
  /**
   * Closing.
   */
  close: string
  /**
   * Opening.
   */
  open: string
}

/**
 * Fence configuration.
 */
type FenceProps = {
  /**
   * Complete fences.
   *
   * This can be used when fences contain different characters or lengths
   * other than 3.
   * Pass `open` and `close` to interface to specify different characters for opening and
   * closing fences.
   */
  fence: Info | string
  /**
   * If `fence` is set, `marker` must not be set.
   */
  marker?: never
}

/**
 * Marker configuration.
 */
type MarkerProps = {
  /**
   * Character repeated 3 times, used as complete fences.
   *
   * For example the character `'-'` will result in `'---'` being used as the
   * fence
   * Pass `open` and `close` to specify different characters for opening and
   * closing fences.
   */
  marker: Info | string
  /**
   * If `marker` is set, `fence` must not be set.
   */
  fence?: never
}

/**
 * Fields describing a kind of matter.
 *
 * > 👉 **Note**: using `anywhere` is a terrible idea.
 * > It’s called frontmatter, not matter-in-the-middle or so.
 * > This makes your markdown less portable.
 *
 * > 👉 **Note**: `marker` and `fence` are mutually exclusive.
 * > If `marker` is set, `fence` must not be set, and vice versa.
 */
type Matter = (MatterProps & FenceProps) | (MatterProps & MarkerProps)

/**
 * Fields describing a kind of matter.
 */
type MatterProps = {
  /**
   * Node type to tokenize as.
   */
  type: string
  /**
   * Whether matter can be found anywhere in the document, normally, only matter
   * at the start of the document is recognized.
   *
   * > 👉 **Note**: using this is a terrible idea.
   * > It’s called frontmatter, not matter-in-the-middle or so.
   * > This makes your markdown less portable.
   */
  anywhere?: boolean | null | undefined
}

/**
 * Known name of a frontmatter style.
 */
type Preset = 'toml' | 'yaml'
```

## Examples

### Example: different markers and fences

Here are a couple of example of different matter objects and what frontmatter
they match.

To match frontmatter with the same opening and closing fence, namely three of
the same markers, use for example `{type: 'yaml', marker: '-'}`, which matches:

```yaml
---
key: value
---
```

To match frontmatter with different opening and closing fences, which each use
three different markers, use for example
`{type: 'custom', marker: {open: '<', close: '>'}}`, which matches:

```text
<<<
data
>>>
```

To match frontmatter with the same opening and closing fences, which both use
the same custom string, use for example `{type: 'custom', fence: '+=+=+=+'}`,
which matches:

```text
+=+=+=+
data
+=+=+=+
```

To match frontmatter with different opening and closing fences, which each use
different custom strings, use for example
`{type: 'json', fence: {open: '{', close: '}'}}`, which matches:

```json
{
  "key": "value"
}
```

### Example: frontmatter as metadata

This plugin handles the syntax of frontmatter in markdown.
It does not *parse* that frontmatter as say YAML or TOML and expose it
somewhere.

In unified, there is a place for metadata about files:
[`file.data`][vfile-file-data].
For frontmatter specifically, it’s customary to expose parsed data at `file.data.matter`.

We can make a plugin that does this.
This example uses the utility [`vfile-matter`][vfile-matter], which is specific
to YAML.
To support other data languages, look at this utility for inspiration.

`my-unified-plugin-handling-yaml-matter.js`:

```js
/**
 * @typedef {import('unist').Node} Node
 * @typedef {import('vfile').VFile} VFile
 */

import {matter} from 'vfile-matter'

/**
 * Parse YAML frontmatter and expose it at `file.data.matter`.
 *
 * @returns
 *   Transform.
 */
export default function myUnifiedPluginHandlingYamlMatter() {
  /**
   * Transform.
   *
   * @param {Node} tree
   *   Tree.
   * @param {VFile} file
   *   File.
   * @returns {undefined}
   *   Nothing.
   */
  return function (tree, file) {
    matter(file)
  }
}
```

…with an example markdown file `example.md`:

```markdown
---
key: value
---

# Venus
```

…and using the plugin with an `example.js` containing:

```js
import remarkParse from 'remark-parse'
import remarkFrontmatter from 'remark-frontmatter'
import remarkStringify from 'remark-stringify'
import {read} from 'to-vfile'
import {unified} from 'unified'
import myUnifiedPluginHandlingYamlMatter from './my-unified-plugin-handling-yaml-matter.js'

const file = await unified()
  .use(remarkParse)
  .use(remarkStringify)
  .use(remarkFrontmatter)
  .use(myUnifiedPluginHandlingYamlMatter)
  .process(await read('example.md'))

console.log(file.data.matter) // => {key: 'value'}
```

### Example: frontmatter in MDX

MDX has the ability to export data from it, where markdown does not.
When authoring MDX, you can write `export` statements and expose arbitrary data
through them.
It is also possible to write frontmatter, and let a plugin turn those into
export statements.

To automatically turn frontmatter into export statements, use
[`remark-mdx-frontmatter`][remark-mdx-frontmatter].

With an `example.mdx` as follows:

```mdx
---
key: value
---

# Mars
```

This plugin can be used as follows:

```js
import {compile} from '@mdx-js/mdx'
import remarkFrontmatter from 'remark-frontmatter'
import remarkMdxFrontmatter from 'remark-mdx-frontmatter'
import {read, write} from 'to-vfile'

const file = await compile(await read('example.mdx'), {
  remarkPlugins: [remarkFrontmatter, [remarkMdxFrontmatter, {name: 'matter'}]]
})
file.path = 'output.js'
await write(file)

const mod = await import('./output.js')
console.log(mod.matter) // => {key: 'value'}
```

## Authoring

When authoring markdown with frontmatter, it’s recommended to use YAML
frontmatter if possible.
While YAML has some warts, it works in the most places, so using it guarantees
the highest chance of portability.

In certain ecosystems, other flavors are widely used.
For example, in the Rust ecosystem, TOML is often used.
In such cases, using TOML is an okay choice.

When possible, do not use other types of frontmatter, and do not allow
frontmatter anywhere.

## HTML

Frontmatter does not relate to HTML elements.
It is typically stripped, which is what [`remark-rehype`][remark-rehype] does.

## CSS

This package does not relate to CSS.

## Syntax

See [*Syntax* in
`micromark-extension-frontmatter`](https://github.com/micromark/micromark-extension-frontmatter#syntax).

## Syntax tree

See [*Syntax tree* in
`mdast-util-frontmatter`](https://github.com/syntax-tree/mdast-util-frontmatter#syntax-tree).

## Types

This package is fully typed with [TypeScript][].
It exports the additional type [`Options`][api-options].

The YAML node type is supported in `@types/mdast` by default.
To add other node types, register them by adding them to
`FrontmatterContentMap`:

```ts
import type {Data, Literal} from 'mdast'

interface Toml extends Literal {
  type: 'toml'
  data?: TomlData
}

declare module 'mdast' {
  interface FrontmatterContentMap {
    // Allow using TOML nodes defined by `remark-frontmatter`.
    toml: Toml
  }
}
```

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, `remark-frontmatter@^5`,
compatible with Node.js 16.

This plugin works with unified 6+ and remark 13+.

## Security

Use of `remark-frontmatter` does not involve **[rehype][]** ([hast][]) or user
content so there are no openings for [cross-site scripting (XSS)][wiki-xss]
attacks.

## Related

*   [`remark-yaml-config`](https://github.com/remarkjs/remark-yaml-config)
    — configure remark from YAML configuration
*   [`remark-gfm`](https://github.com/remarkjs/remark-gfm)
    — support GFM (autolink literals, footnotes, strikethrough, tables,
    tasklists)
*   [`remark-mdx`](https://github.com/mdx-js/mdx/tree/main/packages/remark-mdx)
    — support MDX (ESM, JSX, expressions)
*   [`remark-directive`](https://github.com/remarkjs/remark-directive)
    — support directives
*   [`remark-math`](https://github.com/remarkjs/remark-math)
    — support math

## Contribute

See [`contributing.md`][contributing] in [`remarkjs/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/remarkjs/remark-frontmatter/workflows/main/badge.svg

[build]: https://github.com/remarkjs/remark-frontmatter/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/remarkjs/remark-frontmatter.svg

[coverage]: https://codecov.io/github/remarkjs/remark-frontmatter

[downloads-badge]: https://img.shields.io/npm/dm/remark-frontmatter.svg

[downloads]: https://www.npmjs.com/package/remark-frontmatter

[size-badge]: https://img.shields.io/bundlejs/size/remark-frontmatter

[size]: https://bundlejs.com/?q=remark-frontmatter

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/remarkjs/remark/discussions

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[health]: https://github.com/remarkjs/.github

[contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md

[support]: https://github.com/remarkjs/.github/blob/main/support.md

[coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md

[license]: license

[author]: https://wooorm.com

[mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown

[mdast-util-frontmatter]: https://github.com/syntax-tree/mdast-util-frontmatter

[micromark]: https://github.com/micromark/micromark

[micromark-extension-frontmatter]: https://github.com/micromark/micromark-extension-frontmatter

[hast]: https://github.com/syntax-tree/hast

[rehype]: https://github.com/rehypejs/rehype

[remark]: https://github.com/remarkjs/remark

[remark-rehype]: https://github.com/remarkjs/remark-rehype

[remark-mdx-frontmatter]: https://github.com/remcohaszing/remark-mdx-frontmatter

[typescript]: https://www.typescriptlang.org

[unified]: https://github.com/unifiedjs/unified

[unified-create-plugin]: https://unifiedjs.com/learn/guide/create-a-plugin/

[vfile-file-data]: https://github.com/vfile/vfile#filedata

[vfile-matter]: https://github.com/vfile/vfile-matter

[wiki-xss]: https://en.wikipedia.org/wiki/Cross-site_scripting

[api-options]: #options

[api-remark-frontmatter]: #unifieduseremarkfrontmatter-options


---

# remark-gfm

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

**[remark][]** plugin to support [GFM][] (autolink literals, footnotes,
strikethrough, tables, tasklists).

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`unified().use(remarkGfm[, options])`](#unifieduseremarkgfm-options)
  * [`Options`](#options)
* [Examples](#examples)
  * [Example: `singleTilde`](#example-singletilde)
  * [Example: `stringLength`](#example-stringlength)
* [Bugs](#bugs)
* [Authoring](#authoring)
* [HTML](#html)
* [CSS](#css)
* [Syntax](#syntax)
* [Syntax tree](#syntax-tree)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Related](#related)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package is a [unified][] ([remark][]) plugin to enable the extensions to
markdown that GitHub adds with GFM: autolink literals (`www.x.com`), footnotes
(`[^1]`), strikethrough (`~~stuff~~`), tables (`| cell |…`), and tasklists
(`* [x]`).
You can use this plugin to add support for parsing and serializing them.
These extensions by GitHub to CommonMark are called [GFM][] (GitHub Flavored
Markdown).

This plugin does not handle how markdown is turned to HTML.
That’s done by [`remark-rehype`][remark-rehype].
If your content is not in English and uses footnotes, you should configure that
plugin.
When generating HTML, you might also want to enable [`rehype-slug`][rehype-slug]
to add `id`s on headings.

A different plugin, [`remark-frontmatter`][remark-frontmatter], adds support for
frontmatter.
GitHub supports YAML frontmatter for files in repos and Gists but they don’t
treat it as part of GFM.

Another plugin, [`remark-github`][remark-github], adds support for how markdown
works in relation to a certain GitHub repo in comments, issues, PRs, and
releases, by linking references to commits, issues, and users.

Yet another plugin, [`remark-breaks`][remark-breaks], turns soft line endings
(enters) into hard breaks (`<br>`s).
GitHub does this in a few places (comments, issues, PRs, and releases).

## When should I use this?

This project is useful when you want to support the same features that GitHub
does in files in a repo, Gists, and several other places.
Users frequently believe that some of these extensions, specifically autolink
literals and tables, are part of normal markdown, so using `remark-gfm` will
help match your implementation to their understanding of markdown.
There are several edge cases where GitHub’s implementation works in unexpected
ways or even different than described in their spec, so *writing* in GFM is not
always the best choice.

If you *just* want to turn markdown into HTML (with maybe a few extensions such
as GFM), we recommend [`micromark`][micromark] with
[`micromark-extension-gfm`][micromark-extension-gfm] instead.
If you don’t use plugins and want to access the syntax tree, you can use
[`mdast-util-from-markdown`][mdast-util-from-markdown] with
[`mdast-util-gfm`][mdast-util-gfm].

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install remark-gfm
```

In Deno with [`esm.sh`][esmsh]:

```js
import remarkGfm from 'https://esm.sh/remark-gfm@4'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import remarkGfm from 'https://esm.sh/remark-gfm@4?bundle'
</script>
```

## Use

Say our document `example.md` contains:

```markdown
# GFM

## Autolink literals

www.example.com, https://example.com, and contact@example.com.

## Footnote

A note[^1]

[^1]: Big note.

## Strikethrough

~one~ or ~~two~~ tildes.

## Table

| a | b  |  c |  d  |
| - | :- | -: | :-: |

## Tasklist

* [ ] to do
* [x] done
```

…and our module `example.js` contains:

```js
import rehypeStringify from 'rehype-stringify'
import remarkGfm from 'remark-gfm'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import {read} from 'to-vfile'
import {unified} from 'unified'

const file = await unified()
  .use(remarkParse)
  .use(remarkGfm)
  .use(remarkRehype)
  .use(rehypeStringify)
  .process(await read('example.md'))

console.log(String(file))
```

…then running `node example.js` yields:

```html
<h1>GFM</h1>
<h2>Autolink literals</h2>
<p><a href="http://www.example.com">www.example.com</a>, <a href="https://example.com">https://example.com</a>, and <a href="mailto:contact@example.com">contact@example.com</a>.</p>
<h2>Footnote</h2>
<p>A note<sup><a href="#user-content-fn-1" id="user-content-fnref-1" data-footnote-ref aria-describedby="footnote-label">1</a></sup></p>
<h2>Strikethrough</h2>
<p><del>one</del> or <del>two</del> tildes.</p>
<h2>Table</h2>
<table>
<thead>
<tr>
<th>a</th>
<th align="left">b</th>
<th align="right">c</th>
<th align="center">d</th>
</tr>
</thead>
</table>
<h2>Tasklist</h2>
<ul class="contains-task-list">
<li class="task-list-item"><input type="checkbox" disabled> to do</li>
<li class="task-list-item"><input type="checkbox" checked disabled> done</li>
</ul>
<section data-footnotes class="footnotes"><h2 class="sr-only" id="footnote-label">Footnotes</h2>
<ol>
<li id="user-content-fn-1">
<p>Big note. <a href="#user-content-fnref-1" data-footnote-backref class="data-footnote-backref" aria-label="Back to content">↩</a></p>
</li>
</ol>
</section>
```

## API

This package exports no identifiers.
The default export is [`remarkGfm`][api-remark-gfm].

### `unified().use(remarkGfm[, options])`

Add support GFM (autolink literals, footnotes, strikethrough, tables,
tasklists).

###### Parameters

* `options` ([`Options`][api-options], optional)
  — configuration

###### Returns

Nothing (`undefined`).

### `Options`

Configuration (TypeScript type).

###### Fields

* `firstLineBlank` (`boolean`, default: `false`)
  — serialize with a blank line for the first line of footnote definitions
* `stringLength` (`((value: string) => number)`, default: `d => d.length`)
  — detect the size of table cells, used when aligning cells
* `singleTilde` (`boolean`, default: `true`)
  — whether to support strikethrough with a single tilde;
  single tildes work on github.com, but are technically prohibited by GFM;
  you can always use 2 or more tildes for strikethrough
* `tablePipeAlign` (`boolean`, default: `true`)
  — whether to align table pipes
* `tableCellPadding` (`boolean`, default: `true`)
  — whether to add a space of padding between table pipes and cells

## Examples

### Example: `singleTilde`

To turn off support for parsing strikethrough with single tildes, pass
`singleTilde: false`:

```js
// …

const file = await unified()
  .use(remarkParse)
  .use(remarkGfm, {singleTilde: false})
  .use(remarkRehype)
  .use(rehypeStringify)
  .process('~one~ and ~~two~~')

console.log(String(file))
```

Yields:

```html
<p>~one~ and <del>two</del></p>
```

### Example: `stringLength`

It’s possible to align tables based on the visual width of cells.
First, let’s show the problem:

```js
import {remark} from 'remark'
import remarkGfm from 'remark-gfm'

const input = `| Alpha | Bravo |
| - | - |
| 中文 | Charlie |
| 👩‍❤️‍👩 | Delta |`

const file = await remark().use(remarkGfm).process(input)

console.log(String(file))
```

The above code shows how remark can be used to format markdown.
The output is as follows:

```markdown
| Alpha    | Bravo   |
| -------- | ------- |
| 中文       | Charlie |
| 👩‍❤️‍👩 | Delta   |
```

To improve the alignment of these full-width characters and emoji, pass a
`stringLength` function that calculates the visual width of cells.
One such algorithm is [`string-width`][string-width].
It can be used like so:

```diff
@@ -1,5 +1,6 @@
 import {remark} from 'remark'
 import remarkGfm from 'remark-gfm'
+import stringWidth from 'string-width'

@@ -10,7 +11,7 @@ async function main() {
 | 👩‍❤️‍👩 | Delta |`

-const file = await remark().use(remarkGfm).process(input)
+const file = await remark()
+  .use(remarkGfm, {stringLength: stringWidth})
+  .process(input)

   console.log(String(file))
```

The output of our code with these changes is as follows:

```markdown
| Alpha | Bravo   |
| ----- | ------- |
| 中文  | Charlie |
| 👩‍❤️‍👩    | Delta   |
```

## Bugs

For bugs present in GFM but not here, or other peculiarities that are
supported, see each corresponding readme:

* [autolink literal](https://github.com/micromark/micromark-extension-gfm-autolink-literal#bugs)
* [footnote](https://github.com/micromark/micromark-extension-gfm-footnote#bugs)
* strikethrough: n/a
* [table](https://github.com/micromark/micromark-extension-gfm-table#bugs)
* tasklists: n/a

## Authoring

For recommendations on how to author GFM, see each corresponding readme:

* [autolink literal](https://github.com/micromark/micromark-extension-gfm-autolink-literal#authoring)
* [footnote](https://github.com/micromark/micromark-extension-gfm-footnote#authoring)
* [strikethrough](https://github.com/micromark/micromark-extension-gfm-strikethrough#authoring)
* [table](https://github.com/micromark/micromark-extension-gfm-table#authoring)
* [tasklists](https://github.com/micromark/micromark-extension-gfm-task-list-item#authoring)

## HTML

This plugin does not handle how markdown is turned to HTML.
See [`remark-rehype`][remark-rehype] for how that happens and how to change it.

## CSS

For info on how GitHub styles these features, see each corresponding readme:

* [autolink literal](https://github.com/micromark/micromark-extension-gfm-autolink-literal#css)
* [footnote](https://github.com/micromark/micromark-extension-gfm-footnote#css)
* [strikethrough](https://github.com/micromark/micromark-extension-gfm-strikethrough#css)
* [table](https://github.com/micromark/micromark-extension-gfm-table#css)
* [tasklists](https://github.com/micromark/micromark-extension-gfm-task-list-item#css)

## Syntax

For info on the syntax of these features, see each corresponding readme:

* [autolink literal](https://github.com/micromark/micromark-extension-gfm-autolink-literal#syntax)
* [footnote](https://github.com/micromark/micromark-extension-gfm-footnote#syntax)
* [strikethrough](https://github.com/micromark/micromark-extension-gfm-strikethrough#syntax)
* [table](https://github.com/micromark/micromark-extension-gfm-table#syntax)
* [tasklists](https://github.com/micromark/micromark-extension-gfm-task-list-item#syntax)

## Syntax tree

For info on the syntax tree of these features, see each corresponding readme:

* [autolink literal](https://github.com/syntax-tree/mdast-util-gfm-autolink-literal#syntax-tree)
* [footnote](https://github.com/syntax-tree/mdast-util-gfm-footnote#syntax-tree)
* [strikethrough](https://github.com/syntax-tree/mdast-util-gfm-strikethrough#syntax-tree)
* [table](https://github.com/syntax-tree/mdast-util-gfm-table#syntax-tree)
* [tasklists](https://github.com/syntax-tree/mdast-util-gfm-task-list-item#syntax-tree)

## Types

This package is fully typed with [TypeScript][].
It exports the additional type [`Options`][api-options].

The node types are supported in `@types/mdast` by default.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, `remark-gfm@^4`, compatible
with Node.js 16.

This plugin works with `remark-parse` version 11+ (`remark` version 15+).
The previous version (v3) worked with `remark-parse` version 10 (`remark`
version 14).
Before that, v2 worked with `remark-parse` version 9 (`remark` version 13).
Earlier versions of `remark-parse` and `remark` had a `gfm` option that enabled
this functionality, which defaulted to true.

## Security

Use of `remark-gfm` does not involve **[rehype][]** ([hast][]) or user
content so there are no openings for [cross-site scripting (XSS)][wiki-xss]
attacks.

## Related

* [`remark-github`][remark-github]
  — link references to commits, issues, PRs, and users
* [`remark-breaks`][remark-breaks]
  — support breaks without needing spaces or escapes (enters to `<br>`)
* [`remark-frontmatter`][remark-frontmatter]
  — support frontmatter (YAML, TOML, and more)
* [`remark-directive`](https://github.com/remarkjs/remark-directive)
  — support directives
* [`remark-math`](https://github.com/remarkjs/remark-math)
  — support math
* [`remark-mdx`](https://github.com/mdx-js/mdx/tree/main/packages/remark-mdx)
  — support MDX (ESM, JSX, expressions)

## Contribute

See [`contributing.md`][contributing] in [`remarkjs/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[api-options]: #options

[api-remark-gfm]: #unifieduseremarkgfm-options

[author]: https://wooorm.com

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[build]: https://github.com/remarkjs/remark-gfm/actions

[build-badge]: https://github.com/remarkjs/remark-gfm/workflows/main/badge.svg

[chat]: https://github.com/remarkjs/remark/discussions

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[coc]: https://github.com/remarkjs/.github/blob/HEAD/code-of-conduct.md

[collective]: https://opencollective.com/unified

[contributing]: https://github.com/remarkjs/.github/blob/HEAD/contributing.md

[coverage]: https://codecov.io/github/remarkjs/remark-gfm

[coverage-badge]: https://img.shields.io/codecov/c/github/remarkjs/remark-gfm.svg

[downloads]: https://www.npmjs.com/package/remark-gfm

[downloads-badge]: https://img.shields.io/npm/dm/remark-gfm.svg

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[gfm]: https://github.github.com/gfm/

[hast]: https://github.com/syntax-tree/hast

[health]: https://github.com/remarkjs/.github

[license]: license

[mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown

[mdast-util-gfm]: https://github.com/syntax-tree/mdast-util-gfm

[micromark]: https://github.com/micromark/micromark

[micromark-extension-gfm]: https://github.com/micromark/micromark-extension-gfm

[npm]: https://docs.npmjs.com/cli/install

[rehype]: https://github.com/rehypejs/rehype

[rehype-slug]: https://github.com/rehypejs/rehype-slug

[remark]: https://github.com/remarkjs/remark

[remark-breaks]: https://github.com/remarkjs/remark-breaks

[remark-frontmatter]: https://github.com/remarkjs/remark-frontmatter

[remark-github]: https://github.com/remarkjs/remark-github

[remark-rehype]: https://github.com/remarkjs/remark-rehype

[size]: https://bundlejs.com/?q=remark-gfm

[size-badge]: https://img.shields.io/bundlejs/size/remark-gfm

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[string-width]: https://github.com/sindresorhus/string-width

[support]: https://github.com/remarkjs/.github/blob/HEAD/support.md

[typescript]: https://www.typescriptlang.org

[unified]: https://github.com/unifiedjs/unified

[wiki-xss]: https://en.wikipedia.org/wiki/Cross-site_scripting


---

# remark-mdx

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

remark plugin to support the MDX syntax (JSX, export/import, expressions).

<!-- more -->

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`unified().use(remarkMdx[, options])`](#unifieduseremarkmdx-options)
  * [`Options`](#options)
* [Authoring](#authoring)
* [HTML](#html)
* [Syntax](#syntax)
* [Syntax tree](#syntax-tree)
* [Errors](#errors)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package is a [unified][] ([remark][]) plugin to enable the extensions to
markdown that MDX adds: JSX (`<x/>`), export/import (`export x from 'y'`), and
expression {`{1 + 1}`}.
You can use this plugin to add support for parsing and serializing them.

This plugin does not handle how MDX is compiled to JavaScript or evaluated and
rendered to HTML.
That’s done by [`@mdx-js/mdx`][mdx].

## When should I use this?

This plugin is useful if you’re dealing with the MDX syntax and integrating
with remark, rehype, and the rest of unified.
Some example use cases are when you want to lint the syntax or compile it to
something other that JavaScript.

If you don’t use plugins and want to access the syntax tree, you can use
[`mdast-util-from-markdown`][mdast-util-from-markdown] with
[`mdast-util-mdx`][mdast-util-mdx].

Typically though, you’d want to move a layer up: `@mdx-js/mdx`.
That package is the core compiler for turning MDX into JavaScript which
gives you the most control.
Or even higher: if you’re using a bundler (Rollup, esbuild, webpack), or a site
builder (Next.js) or build system (Vite) which comes with a bundler, you’re
better off using an integration: see [§ Integrations][integrations].

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install remark-mdx
```

In Deno with [`esm.sh`][esmsh]:

```tsx
import remarkMdx from 'https://esm.sh/remark-mdx@3'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import remarkMdx from 'https://esm.sh/remark-mdx@3?bundle'
</script>
```

## Use

```tsx
import {remark} from 'remark'
import remarkMdx from 'remark-mdx'

const file = await remark()
  .use(remarkMdx)
  .process('import a from "b"\n\na <b /> c {1 + 1} d')

console.log(String(file))
```

Yields:

```mdx
import a from "b"

a <b/> c {1 + 1} d
```

## API

This package exports no identifiers.
The default export is [`remarkMdx`][api-remark-mdx].

### `unified().use(remarkMdx[, options])`

Add support for MDX (JSX: `<Video id={123} />`, export/imports: `export {x}
from 'y'`; and expressions: `{1 + 1}`).

###### Parameters

* `options` ([`Options`][api-options], optional)
  — configuration

###### Returns

Nothing (`undefined`).

### `Options`

Configuration (TypeScript type).

###### Fields

* `acornOptions` ([`AcornOptions`][acorn-options], default:
  `{ecmaVersion: 2024, locations: true, sourceType: 'module'}`)
  — configuration for acorn; all fields except `locations` can be set
* `printWidth` (`number`, default: `Infinity`)
  — try and wrap syntax at this width;
  when set to a finite number (say, `80`), the formatter will print
  attributes on separate lines when a tag doesn’t fit on one line;
  the normal behavior is to print attributes with spaces between them instead
  of line endings
* `quote` (`'"'` or `"'"`, default: `'"'`)
  — preferred quote to use around attribute values
* `quoteSmart` (`boolean`, default: `false`)
  — use the other quote if that results in less bytes
* `tightSelfClosing` (`boolean`, default: `false`)
  — do not use an extra space when closing self-closing elements: `<img/>`
  instead of `<img />`

<!-- Note: `acorn`, `addResult`, `allowEmpty`, and `spread` are intentionally not documented. -->

## Authoring

For recommendations on how to author MDX, see each corresponding readme:

* [ESM](https://github.com/micromark/micromark-extension-mdxjs-esm#authoring)
* [JSX](https://github.com/micromark/micromark-extension-mdx-jsx#authoring)
* [expressions](https://github.com/micromark/micromark-extension-mdx-expression/tree/main/packages/micromark-extension-mdx-expression#authoring)
* [CommonMark features not in MDX](https://github.com/micromark/micromark-extension-mdx-md#authoring)

## HTML

MDX has no representation in HTML.
Though, when you are dealing with MDX, you will likely go *through* hast.
You can enable passing MDX through to hast by configuring
[`remark-rehype`][remark-rehype] with `passThrough: ['mdxjsEsm',
'mdxFlowExpression', 'mdxJsxFlowElement', 'mdxJsxTextElement', 'mdxTextExpression']`.

## Syntax

For info on the syntax of these features, see each corresponding readme:

* [ESM](https://github.com/micromark/micromark-extension-mdxjs-esm#syntax)
* [JSX](https://github.com/micromark/micromark-extension-mdx-jsx#syntax)
* [expressions](https://github.com/micromark/micromark-extension-mdx-expression/tree/main/packages/micromark-extension-mdx-expression#syntax)
* CommonMark features not in MDX: n/a

## Syntax tree

For info on the syntax tree of these features, see each corresponding readme:

* [ESM](https://github.com/syntax-tree/mdast-util-mdxjs-esm#syntax-tree)
* [JSX](https://github.com/syntax-tree/mdast-util-mdx-jsx#syntax-tree)
* [expressions](https://github.com/syntax-tree/mdast-util-mdx-expression#syntax-tree)
* CommonMark features not in MDX: n/a

## Errors

For info on what errors are thrown, see each corresponding readme:

* [ESM](https://github.com/micromark/micromark-extension-mdxjs-esm#errors)
* [JSX](https://github.com/micromark/micromark-extension-mdx-jsx#errors)
* [expressions](https://github.com/micromark/micromark-extension-mdx-expression/tree/main/packages/micromark-extension-mdx-expression#errors)
* CommonMark features not in MDX: n/a

## Types

This package is fully typed with [TypeScript][].
It exports the additional type [`Options`][api-options].

If you’re working with the syntax tree, you can register the new node types
with `@types/mdast` by adding a reference:

```tsx
// Register MDX nodes in mdast:
/// <reference types="remark-mdx" />

/**
 * @import {Root} from 'mdast'
 */

import {visit} from 'unist-util-visit'

function myRemarkPlugin() {
  /**
   * @param {Root} tree
   *   Tree.
   * @returns {undefined}
   *   Nothing.
   */
  return function (tree) {
    visit(tree, function (node) {
      console.log(node) // `node` can now be one of the MDX nodes.
    })
  }
}
```

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, `remark-mdx@^3`, compatible
with Node.js 16.

## Security

See [§ Security][security] on our website for information.

## Contribute

See [§ Contribute][contribute] on our website for ways to get started.
See [§ Support][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][] © [Titus Wormer][author]

[build-badge]: https://github.com/mdx-js/mdx/workflows/main/badge.svg

[build]: https://github.com/mdx-js/mdx/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/mdx-js/mdx/main.svg

[coverage]: https://codecov.io/github/mdx-js/mdx

[downloads-badge]: https://img.shields.io/npm/dm/remark-mdx.svg

[downloads]: https://www.npmjs.com/package/remark-mdx

[size-badge]: https://img.shields.io/bundlephobia/minzip/remark-mdx.svg

[size]: https://bundlephobia.com/result?p=remark-mdx

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/mdx-js/mdx/discussions

[npm]: https://docs.npmjs.com/cli/install

[contribute]: https://mdxjs.com/community/contribute/

[support]: https://mdxjs.com/community/support/

[coc]: https://github.com/mdx-js/.github/blob/main/code-of-conduct.md

[mit]: https://github.com/mdx-js/mdx/blob/main/packages/remark-mdx/license

[author]: https://wooorm.com

[integrations]: https://mdxjs.com/getting-started/#integrations

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[security]: https://mdxjs.com/getting-started/#security

[typescript]: https://www.typescriptlang.org

[unified]: https://github.com/unifiedjs/unified

[remark]: https://github.com/remarkjs/remark

[remark-rehype]: https://github.com/remarkjs/remark-rehype

[mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown

[mdast-util-mdx]: https://github.com/syntax-tree/mdast-util-mdx

[mdx]: https://mdxjs.com/packages/mdx/

[acorn-options]: https://github.com/acornjs/acorn/blob/520547b/acorn/src/acorn.d.ts#L578

[api-options]: #options

[api-remark-mdx]: #unifieduseremarkmdx-options


---

# remark-parse

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

**[remark][]** plugin to add support for parsing from markdown.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`unified().use(remarkParse)`](#unifieduseremarkparse)
*   [Examples](#examples)
    *   [Example: support GFM and frontmatter](#example-support-gfm-and-frontmatter)
    *   [Example: turning markdown into a man page](#example-turning-markdown-into-a-man-page)
*   [Syntax](#syntax)
*   [Syntax tree](#syntax-tree)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Security](#security)
*   [Contribute](#contribute)
*   [Sponsor](#sponsor)
*   [License](#license)

## What is this?

This package is a [unified][] ([remark][]) plugin that defines how to take
markdown as input and turn it into a syntax tree.

See [the monorepo readme][remark] for info on what the remark ecosystem is.

## When should I use this?

This plugin adds support to unified for parsing markdown.
If you also need to serialize markdown, you can alternatively use
[`remark`][remark-core], which combines unified, this plugin, and
[`remark-stringify`][remark-stringify].

If you *just* want to turn markdown into HTML (with maybe a few extensions),
we recommend [`micromark`][micromark] instead.
If you don’t use plugins and want to access the syntax tree, you can directly
use [`mdast-util-from-markdown`][mdast-util-from-markdown].
remark focusses on making it easier to transform content by abstracting these
internals away.

You can combine this plugin with other plugins to add syntax extensions.
Notable examples that deeply integrate with it are
[`remark-gfm`][remark-gfm],
[`remark-mdx`][remark-mdx],
[`remark-frontmatter`][remark-frontmatter],
[`remark-math`][remark-math], and
[`remark-directive`][remark-directive].
You can also use any other [remark plugin][remark-plugin] after `remark-parse`.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install remark-parse
```

In Deno with [`esm.sh`][esmsh]:

```js
import remarkParse from 'https://esm.sh/remark-parse@11'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import remarkParse from 'https://esm.sh/remark-parse@11?bundle'
</script>
```

## Use

Say we have the following module `example.js`:

```js
import rehypeStringify from 'rehype-stringify'
import remarkGfm from 'remark-gfm'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import {unified} from 'unified'

const doc = `
# Mercury

**Mercury** is the first planet from the [Sun](https://en.wikipedia.org/wiki/Sun)
and the smallest planet in the Solar System.
`

const file = await unified()
  .use(remarkParse)
  .use(remarkGfm)
  .use(remarkRehype)
  .use(rehypeStringify)
  .process(doc)

console.log(String(file))
```

…then running `node example.js` yields:

```html
<h1>Mercury</h1>
<p><strong>Mercury</strong> is the first planet from the <a href="https://en.wikipedia.org/wiki/Sun">Sun</a>
and the smallest planet in the Solar System.</p>
```

## API

This package exports no identifiers.
The default export is [`remarkParse`][api-remark-parse].

### `unified().use(remarkParse)`

Add support for parsing from markdown.

###### Parameters

There are no parameters.

###### Returns

Nothing (`undefined`).

## Examples

### Example: support GFM and frontmatter

We support CommonMark by default.
Non-standard markdown extensions can be enabled with plugins.

This example shows how to support GFM features (autolink literals,
footnotes, strikethrough, tables, tasklists) and frontmatter (YAML):

```js
import rehypeStringify from 'rehype-stringify'
import remarkFrontmatter from 'remark-frontmatter'
import remarkGfm from 'remark-gfm'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import {unified} from 'unified'

const doc = `---
layout: solar-system
---

# Hi ~~Mars~~Venus!
`

const file = await unified()
  .use(remarkParse)
  .use(remarkFrontmatter)
  .use(remarkGfm)
  .use(remarkRehype)
  .use(rehypeStringify)
  .process(doc)

console.log(String(file))
```

Yields:

```html
<h1>Hi <del>Mars</del>Venus!</h1>
```

### Example: turning markdown into a man page

Man pages (short for manual pages) are a way to document CLIs (example: type
`man git-log` in your terminal).
They use an old markup format called roff.
There’s a remark plugin, [`remark-man`][remark-man], that can serialize as
roff.

This example shows how to turn markdown into man pages by using unified with
`remark-parse` and `remark-man`:

```js
import remarkMan from 'remark-man'
import remarkParse from 'remark-parse'
import {unified} from 'unified'

const doc = `
# titan(7) -- largest moon of saturn

Titan is the largest moon…
`

const file = await unified().use(remarkParse).use(remarkMan).process(doc)

console.log(String(file))
```

Yields:

```roff
.TH "TITAN" "7" "September 2023" "" ""
.SH "NAME"
\fBtitan\fR - largest moon of saturn
.P
Titan is the largest moon…
```

## Syntax

Markdown is parsed according to CommonMark.
Other plugins can add support for syntax extensions.
If you’re interested in extending markdown,
[more information is available in micromark’s readme][micromark-extend].

## Syntax tree

The syntax tree used in remark is [mdast][].

## Types

This package is fully typed with [TypeScript][].
It exports the additional type `Options` (which is currently empty).

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, `remark-parse@^11`,
compatible with Node.js 16.

## Security

As markdown can be turned into HTML and improper use of HTML can open you up to
[cross-site scripting (XSS)][xss] attacks, use of remark can be unsafe.
When going to HTML, you will combine remark with **[rehype][]**, in which case
you should use [`rehype-sanitize`][rehype-sanitize].

Use of remark plugins could also open you up to other attacks.
Carefully assess each plugin and the risks involved in using them.

For info on how to submit a report, see our [security policy][security].

## Contribute

See [`contributing.md`][contributing] in [`remarkjs/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.
Join us in [Discussions][chat] to chat with the community and contributors.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## Sponsor

Support this effort and give back by sponsoring on [OpenCollective][collective]!

<table>
<tr valign="middle">
<td width="20%" align="center" rowspan="2" colspan="2">
  <a href="https://vercel.com">Vercel</a><br><br>
  <a href="https://vercel.com"><img src="https://avatars1.githubusercontent.com/u/14985020?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
  <a href="https://motif.land">Motif</a><br><br>
  <a href="https://motif.land"><img src="https://avatars1.githubusercontent.com/u/74457950?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
  <a href="https://www.hashicorp.com">HashiCorp</a><br><br>
  <a href="https://www.hashicorp.com"><img src="https://avatars1.githubusercontent.com/u/761456?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
  <a href="https://www.gitbook.com">GitBook</a><br><br>
  <a href="https://www.gitbook.com"><img src="https://avatars1.githubusercontent.com/u/7111340?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
  <a href="https://www.gatsbyjs.org">Gatsby</a><br><br>
  <a href="https://www.gatsbyjs.org"><img src="https://avatars1.githubusercontent.com/u/12551863?s=256&v=4" width="128"></a>
</td>
</tr>
<tr valign="middle">
</tr>
<tr valign="middle">
<td width="20%" align="center" rowspan="2" colspan="2">
  <a href="https://www.netlify.com">Netlify</a><br><br>
  <!--OC has a sharper image-->
  <a href="https://www.netlify.com"><img src="https://images.opencollective.com/netlify/4087de2/logo/256.png" width="128"></a>
</td>
<td width="10%" align="center">
  <a href="https://www.coinbase.com">Coinbase</a><br><br>
  <a href="https://www.coinbase.com"><img src="https://avatars1.githubusercontent.com/u/1885080?s=256&v=4" width="64"></a>
</td>
<td width="10%" align="center">
  <a href="https://themeisle.com">ThemeIsle</a><br><br>
  <a href="https://themeisle.com"><img src="https://avatars1.githubusercontent.com/u/58979018?s=128&v=4" width="64"></a>
</td>
<td width="10%" align="center">
  <a href="https://expo.io">Expo</a><br><br>
  <a href="https://expo.io"><img src="https://avatars1.githubusercontent.com/u/12504344?s=128&v=4" width="64"></a>
</td>
<td width="10%" align="center">
  <a href="https://boostnote.io">Boost Note</a><br><br>
  <a href="https://boostnote.io"><img src="https://images.opencollective.com/boosthub/6318083/logo/128.png" width="64"></a>
</td>
<td width="10%" align="center">
  <a href="https://markdown.space">Markdown Space</a><br><br>
  <a href="https://markdown.space"><img src="https://images.opencollective.com/markdown-space/e1038ed/logo/128.png" width="64"></a>
</td>
<td width="10%" align="center">
  <a href="https://www.holloway.com">Holloway</a><br><br>
  <a href="https://www.holloway.com"><img src="https://avatars1.githubusercontent.com/u/35904294?s=128&v=4" width="64"></a>
</td>
<td width="10%"></td>
<td width="10%"></td>
</tr>
<tr valign="middle">
<td width="100%" align="center" colspan="8">
  <br>
  <a href="https://opencollective.com/unified"><strong>You?</strong></a>
  <br><br>
</td>
</tr>
</table>

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/remarkjs/remark/workflows/main/badge.svg

[build]: https://github.com/remarkjs/remark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/remarkjs/remark.svg

[coverage]: https://codecov.io/github/remarkjs/remark

[downloads-badge]: https://img.shields.io/npm/dm/remark-parse.svg

[downloads]: https://www.npmjs.com/package/remark-parse

[size-badge]: https://img.shields.io/bundlejs/size/remark-parse

[size]: https://bundlejs.com/?q=remark-parse

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/remarkjs/remark/discussions

[security]: https://github.com/remarkjs/.github/blob/main/security.md

[health]: https://github.com/remarkjs/.github

[contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md

[support]: https://github.com/remarkjs/.github/blob/main/support.md

[coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md

[license]: https://github.com/remarkjs/remark/blob/main/license

[author]: https://wooorm.com

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[mdast]: https://github.com/syntax-tree/mdast

[mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown

[micromark]: https://github.com/micromark/micromark

[micromark-extend]: https://github.com/micromark/micromark#extensions

[rehype]: https://github.com/rehypejs/rehype

[rehype-sanitize]: https://github.com/rehypejs/rehype-sanitize

[remark]: https://github.com/remarkjs/remark

[remark-core]: ../remark/

[remark-directive]: https://github.com/remarkjs/remark-directive

[remark-frontmatter]: https://github.com/remarkjs/remark-frontmatter

[remark-gfm]: https://github.com/remarkjs/remark-gfm

[remark-mdx]: https://github.com/mdx-js/mdx/tree/main/packages/remark-mdx

[remark-man]: https://github.com/remarkjs/remark-man

[remark-math]: https://github.com/remarkjs/remark-math

[remark-plugin]: https://github.com/remarkjs/remark#plugin

[remark-stringify]: ../remark-stringify/

[typescript]: https://www.typescriptlang.org

[unified]: https://github.com/unifiedjs/unified

[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting

[api-remark-parse]: #unifieduseremarkparse


---

# remark-rehype

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

**[remark][]** plugin that turns markdown into HTML to support **[rehype][]**.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`defaultFootnoteBackContent(referenceIndex, rereferenceIndex)`](#defaultfootnotebackcontentreferenceindex-rereferenceindex)
  * [`defaultFootnoteBackLabel(referenceIndex, rereferenceIndex)`](#defaultfootnotebacklabelreferenceindex-rereferenceindex)
  * [`defaultHandlers`](#defaulthandlers)
  * [`unified().use(remarkRehype[, destination][, options])`](#unifieduseremarkrehype-destination-options)
  * [`Options`](#options)
* [Examples](#examples)
  * [Example: supporting HTML in markdown naïvely](#example-supporting-html-in-markdown-naïvely)
  * [Example: supporting HTML in markdown properly](#example-supporting-html-in-markdown-properly)
  * [Example: footnotes in languages other than English](#example-footnotes-in-languages-other-than-english)
* [HTML](#html-1)
* [CSS](#css)
* [Syntax tree](#syntax-tree)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Related](#related)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package is a [unified][] ([remark][]) plugin that switches from remark (the
markdown ecosystem) to rehype (the HTML ecosystem).
It does this by transforming the current markdown (mdast) syntax tree into an
HTML (hast) syntax tree.
remark plugins deal with mdast and rehype plugins deal with hast, so plugins
used after `remark-rehype` have to be rehype plugins.

The reason that there are different ecosystems for markdown and HTML is that
turning markdown into HTML is, while frequently needed, not the only purpose of
markdown.
Checking (linting) and formatting markdown are also common use cases for
remark and markdown.
There are several aspects of markdown that do not translate 1-to-1 to HTML.
In some cases markdown contains more information than HTML: for example, there
are several ways to add a link in markdown (as in, autolinks: `<https://url>`,
resource links: `[label](url)`, and reference links with definitions:
`[label][id]` and `[id]: url`).
In other cases HTML contains more information than markdown: there are many
tags, which add new meaning (semantics), available in HTML that aren’t available
in markdown.
If there was just one AST, it would be quite hard to perform the tasks that
several remark and rehype plugins currently do.

## When should I use this?

This project is useful when you want to turn markdown to HTML.
It opens up a whole new ecosystem with tons of plugins to do all kinds of
things.
You can [minify HTML][rehype-minify], [format HTML][rehype-format],
[make sure it’s safe][rehype-sanitize], [highlight code][rehype-highlight],
[add metadata][rehype-meta], and a lot more.

A different plugin, [`rehype-raw`][rehype-raw], adds support for raw HTML
written inside markdown.
This is a separate plugin because supporting HTML inside markdown is a heavy
task (performance and bundle size) and not always needed.
To use both together, you also have to configure `remark-rehype` with
`allowDangerousHtml: true` and then use `rehype-raw`.

The rehype plugin [`rehype-remark`][rehype-remark] does the inverse of this
plugin.
It turns HTML into markdown.

If you don’t use plugins and want to access syntax trees, you can use
[`mdast-util-to-hast`][mdast-util-to-hast].

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install remark-rehype
```

In Deno with [`esm.sh`][esmsh]:

```js
import remarkRehype from 'https://esm.sh/remark-rehype@11'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import remarkRehype from 'https://esm.sh/remark-rehype@11?bundle'
</script>
```

## Use

Say our document `example.md` contains:

```markdown
# Pluto

**Pluto** (minor-planet designation: **134340 Pluto**) is a
[dwarf planet](https://en.wikipedia.org/wiki/Dwarf_planet) in the
[Kuiper belt](https://en.wikipedia.org/wiki/Kuiper_belt).
```

…and our module `example.js` contains:

```js
import rehypeDocument from 'rehype-document'
import rehypeFormat from 'rehype-format'
import rehypeStringify from 'rehype-stringify'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import {read} from 'to-vfile'
import {unified} from 'unified'
import {reporter} from 'vfile-reporter'

const file = await unified()
  .use(remarkParse)
  .use(remarkRehype)
  .use(rehypeDocument)
  .use(rehypeFormat)
  .use(rehypeStringify)
  .process(await read('example.md'))

console.error(reporter(file))
console.log(String(file))
```

…then running `node example.js` yields:

```txt
example.md: no issues found
```

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>example</title>
    <meta content="width=device-width, initial-scale=1" name="viewport">
  </head>
  <body>
    <h1>Pluto</h1>
    <p>
      <strong>Pluto</strong> (minor-planet designation: <strong>134340 Pluto</strong>) is a
      <a href="https://en.wikipedia.org/wiki/Dwarf_planet">dwarf planet</a> in the
      <a href="https://en.wikipedia.org/wiki/Kuiper_belt">Kuiper belt</a>.
    </p>
  </body>
</html>
```

## API

This package exports the identifiers
[`defaultFootnoteBackContent`][api-default-footnote-back-content],
[`defaultFootnoteBackLabel`][api-default-footnote-back-label], and
[`defaultHandlers`][api-default-handlers].
The default export is [`remarkRehype`][api-remark-rehype].

### `defaultFootnoteBackContent(referenceIndex, rereferenceIndex)`

See [`defaultFootnoteBackContent` from
`mdast-util-to-hast`][mdast-util-to-hast-default-footnote-back-content]

### `defaultFootnoteBackLabel(referenceIndex, rereferenceIndex)`

See [`defaultFootnoteBackLabel` from
`mdast-util-to-hast`][mdast-util-to-hast-default-footnote-back-label]

### `defaultHandlers`

See [`defaultHandlers` from
`mdast-util-to-hast`][mdast-util-to-hast-default-handlers]

### `unified().use(remarkRehype[, destination][, options])`

Turn markdown into HTML.

###### Parameters

* `destination` ([`Processor`][unified-processor], optional)
  — processor
* `options` ([`Options`][api-options], optional)
  — configuration

###### Returns

Transform ([`Transformer`][unified-transformer]).

##### Notes

###### Signature

* if a [processor][unified-processor] is given, runs the (rehype) plugins
  used on it with a hast tree, then discards the result
  ([*bridge mode*][unified-mode])
* otherwise, returns a hast tree, the plugins used after `remarkRehype`
  are rehype plugins ([*mutate mode*][unified-mode])

> 👉 **Note**: It’s highly unlikely that you want to pass a `processor`.

###### HTML

Raw HTML is available in mdast as [`html`][mdast-html] nodes and can be embedded
in hast as semistandard `raw` nodes.
Most plugins ignore `raw` nodes but two notable ones don’t:

* [`rehype-stringify`][rehype-stringify] also has an option
  `allowDangerousHtml` which will output the raw HTML.
  This is typically discouraged as noted by the option name but is useful if
  you completely trust authors
* [`rehype-raw`][rehype-raw] can handle the raw embedded HTML strings by
  parsing them into standard hast nodes (`element`, `text`, etc).
  This is a heavy task as it needs a full HTML parser, but it is the only way
  to support untrusted content

###### Footnotes

Many options supported here relate to footnotes.
Footnotes are not specified by CommonMark, which we follow by default.
They are supported by GitHub, so footnotes can be enabled in markdown with
[`remark-gfm`][remark-gfm].

The options `footnoteBackLabel` and `footnoteLabel` define natural language
that explains footnotes, which is hidden for sighted users but shown to
assistive technology.
When your page is not in English, you must define translated values.

Back references use ARIA attributes, but the section label itself uses a
heading that is hidden with an `sr-only` class.
To show it to sighted users, define different attributes in
`footnoteLabelProperties`.

###### Clobbering

Footnotes introduces a problem, as it links footnote calls to footnote
definitions on the page through `id` attributes generated from user content,
which results in DOM clobbering.

DOM clobbering is this:

```html
<p id=x></p>
<script>alert(x) // `x` now refers to the DOM `p#x` element</script>
```

Elements by their ID are made available by browsers on the `window` object,
which is a security risk.
Using a prefix solves this problem.

More information on how to handle clobbering and the prefix is explained in
[*Example: headings (DOM clobbering)* in
`rehype-sanitize`][rehype-sanitize-clobber].

###### Unknown nodes

Unknown nodes are nodes with a type that isn’t in `handlers` or `passThrough`.
The default behavior for unknown nodes is:

* when the node has a `value` (and doesn’t have `data.hName`,
  `data.hProperties`, or `data.hChildren`, see later), create a hast `text`
  node
* otherwise, create a `<div>` element (which could be changed with
  `data.hName`), with its children mapped from mdast to hast as well

This behavior can be changed by passing an `unknownHandler`.

### `Options`

Configuration (TypeScript type).

###### Fields

* `allowDangerousHtml` (`boolean`, default: `false`)
  — whether to persist raw HTML in markdown in the hast tree
* `clobberPrefix` (`string`, default: `'user-content-'`)
  — prefix to use before the `id` property on footnotes to prevent them from
  *clobbering*
* `footnoteBackContent`
  ([`FootnoteBackContentTemplate` from
  `mdast-util-to-hast`][mdast-util-to-hast-footnote-back-content-template]
  or `string`, default:
  [`defaultFootnoteBackContent` from
  `mdast-util-to-hast`][mdast-util-to-hast-default-footnote-back-content])
  — content of the backreference back to references
* `footnoteBackLabel`
  ([`FootnoteBackLabelTemplate` from
  `mdast-util-to-hast`][mdast-util-to-hast-footnote-back-label-template]
  or `string`, default:
  [`defaultFootnoteBackLabel` from
  `mdast-util-to-hast`][mdast-util-to-hast-default-footnote-back-label])
  — label to describe the backreference back to references
* `footnoteLabel` (`string`, default: `'Footnotes'`)
  — label to use for the footnotes section (affects screen readers)
* `footnoteLabelProperties`
  ([`Properties` from `@types/hast`][hast-properties], default:
  `{className: ['sr-only']}`)
  — properties to use on the footnote label
  (note that `id: 'footnote-label'` is always added as footnote calls use it
  with `aria-describedby` to provide an accessible label)
* `footnoteLabelTagName` (`string`, default: `h2`)
  — tag name to use for the footnote label
* `handlers` ([`Handlers` from
  `mdast-util-to-hast`][mdast-util-to-hast-handlers], optional)
  — extra handlers for nodes
* `passThrough` (`Array<Nodes['type']>`, optional)
  — list of custom mdast node types to pass through (keep) in hast (note that
  the node itself is passed, but eventual children are transformed)
* `unknownHandler` ([`Handler` from
  `mdast-util-to-hast`][mdast-util-to-hast-handler], optional)
  — handle all unknown nodes

## Examples

### Example: supporting HTML in markdown naïvely

If you completely trust the authors of the input markdown and want to allow them
to write HTML inside markdown, you can pass `allowDangerousHtml` to
`remark-rehype` and `rehype-stringify`:

```js
import rehypeStringify from 'rehype-stringify'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import {unified} from 'unified'

const file = await unified()
  .use(remarkParse)
  .use(remarkRehype, {allowDangerousHtml: true})
  .use(rehypeStringify, {allowDangerousHtml: true})
  .process('<a href="/wiki/Dysnomia_(moon)" onclick="alert(1)">Dysnomia</a>')

console.log(String(file))
```

Yields:

```html
<p><a href="/wiki/Dysnomia_(moon)" onclick="alert(1)">Dysnomia</a></p>
```

> ⚠️ **Danger**: observe that the XSS attack through `onclick` is present.

### Example: supporting HTML in markdown properly

If you do not trust the authors of the input markdown, or if you want to make
sure that rehype plugins can see HTML embedded in markdown, use
[`rehype-raw`][rehype-raw].
The following example passes `allowDangerousHtml` to `remark-rehype`, then
turns the raw embedded HTML into proper HTML nodes with `rehype-raw`, and
finally sanitizes the HTML by only allowing safe things with
`rehype-sanitize`:

```js
import rehypeSanitize from 'rehype-sanitize'
import rehypeStringify from 'rehype-stringify'
import rehypeRaw from 'rehype-raw'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import {unified} from 'unified'

const file = await unified()
  .use(remarkParse)
  .use(remarkRehype, {allowDangerousHtml: true})
  .use(rehypeRaw)
  .use(rehypeSanitize)
  .use(rehypeStringify)
  .process('<a href="/wiki/Dysnomia_(moon)" onclick="alert(1)">Dysnomia</a>')

console.log(String(file))
```

Running that code yields:

```html
<p><a href="/wiki/Dysnomia_(moon)">Dysnomia</a></p>
```

> ⚠️ **Danger**: observe that the XSS attack through `onclick` is **not**
> present.

### Example: footnotes in languages other than English

If you know that the markdown is authored in a language other than English,
and you’re using `remark-gfm` to match how GitHub renders markdown, and you know
that footnotes are (or can?) be used, you should translate the labels associated
with them.

Let’s first set the stage:

```js
import {unified} from 'unified'
import remarkParse from 'remark-parse'
import remarkGfm from 'remark-gfm'
import remarkRehype from 'remark-rehype'
import rehypeStringify from 'rehype-stringify'

const doc = `
Ceres ist nach der römischen Göttin des Ackerbaus benannt;
ihr astronomisches Symbol ist daher eine stilisierte Sichel: ⚳.[^nasa-2015]

[^nasa-2015]: JPL/NASA:
    [*What is a Dwarf Planet?*](https://www.jpl.nasa.gov/infographics/what-is-a-dwarf-planet)
    In: Jet Propulsion Laboratory.
    22. April 2015,
    abgerufen am 19. Januar 2022 (englisch).
`

const file = await unified()
  .use(remarkParse)
  .use(remarkGfm)
  .use(remarkRehype)
  .use(rehypeStringify)
  .process(doc)

console.log(String(file))
```

Yields:

```html
<p>Ceres ist nach der römischen Göttin des Ackerbaus benannt;
ihr astronomisches Symbol ist daher eine stilisierte Sichel: ⚳.<sup><a href="#user-content-fn-nasa-2015" id="user-content-fnref-nasa-2015" data-footnote-ref aria-describedby="footnote-label">1</a></sup></p>
<section data-footnotes class="footnotes"><h2 class="sr-only" id="footnote-label">Footnotes</h2>
<ol>
<li id="user-content-fn-nasa-2015">
<p>JPL/NASA:
<a href="https://www.jpl.nasa.gov/infographics/what-is-a-dwarf-planet"><em>What is a Dwarf Planet?</em></a>
In: Jet Propulsion Laboratory.
22. April 2015,
abgerufen am 19. Januar 2022 (englisch). <a href="#user-content-fnref-nasa-2015" data-footnote-backref="" aria-label="Back to reference 1" class="data-footnote-backref">↩</a></p>
</li>
</ol>
</section>
```

This is a mix of English and German that isn’t very accessible, such as that
screen readers can’t handle it nicely.
Let’s say our program *does* know that the markdown is in German.
In that case, it’s important to translate and define the labels relating to
footnotes so that screen reader users can properly pronounce the page:

```diff
@@ -18,7 +18,16 @@ ihr astronomisches Symbol ist daher eine stilisierte Sichel: ⚳.[^nasa-2015]
 const file = await unified()
   .use(remarkParse)
   .use(remarkGfm)
-  .use(remarkRehype)
+  .use(remarkRehype, {
+    footnoteBackLabel(referenceIndex, rereferenceIndex) {
+      return (
+        'Hochspringen nach: ' +
+        (referenceIndex + 1) +
+        (rereferenceIndex > 1 ? '-' + rereferenceIndex : '')
+      )
+    },
+    footnoteLabel: 'Fußnoten'
+  })
   .use(rehypeStringify)
   .process(doc)
```

Running the code with the above patch applied, yields:

```diff
@@ -1,13 +1,13 @@
 <p>Ceres ist nach der römischen Göttin des Ackerbaus benannt;
 ihr astronomisches Symbol ist daher eine stilisierte Sichel: ⚳.<sup><a href="#user-content-fn-nasa-2015" id="user-content-fnref-nasa-2015" data-footnote-ref aria-describedby="footnote-label">1</a></sup></p>
-<section data-footnotes class="footnotes"><h2 class="sr-only" id="footnote-label">Footnotes</h2>
+<section data-footnotes class="footnotes"><h2 class="sr-only" id="footnote-label">Fußnoten</h2>
 <ol>
 <li id="user-content-fn-nasa-2015">
 <p>JPL/NASA:
 <a href="https://www.jpl.nasa.gov/infographics/what-is-a-dwarf-planet"><em>What is a Dwarf Planet?</em></a>
 In: Jet Propulsion Laboratory.
 22. April 2015,
-abgerufen am 19. Januar 2022 (englisch). <a href="#user-content-fnref-nasa-2015" data-footnote-backref="" aria-label="Back to reference 1" class="data-footnote-backref">↩</a></p>
+abgerufen am 19. Januar 2022 (englisch). <a href="#user-content-fnref-nasa-2015" data-footnote-backref="" aria-label="Hochspringen nach: 1" class="data-footnote-backref">↩</a></p>
 </li>
 </ol>
 </section>
```

## HTML

See [*Algorithm* in
`mdast-util-to-hast`](https://github.com/syntax-tree/mdast-util-to-hast#algorithm)
for info on how mdast (markdown) nodes are transformed to hast (HTML).

## CSS

Assuming you know how to use (semantic) HTML and CSS, then it should generally
be straightforward to style the HTML produced by this plugin.
With CSS, you can get creative and style the results as you please.

Some semistandard features, notably GFMs tasklists and footnotes, generate HTML
that be unintuitive, as it matches exactly what GitHub produces for their
website.
There is a project, [`sindresorhus/github-markdown-css`][github-markdown-css],
that exposes the stylesheet that GitHub uses for rendered markdown, which might
either be inspirational for more complex features, or can be used as-is to
exactly match how GitHub styles rendered markdown.

The following CSS is needed to make footnotes look a bit like GitHub:

```css
/* Style the footnotes section. */
.footnotes {
  font-size: smaller;
  color: #8b949e;
  border-top: 1px solid #30363d;
}

/* Hide the section label for visual users. */
.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  word-wrap: normal;
  border: 0;
}

/* Place `[` and `]` around footnote calls. */
[data-footnote-ref]::before {
  content: '[';
}

[data-footnote-ref]::after {
  content: ']';
}
```

## Syntax tree

This projects turns [mdast][] (markdown) into [hast][] (HTML).

It extends mdast by supporting `data` fields on mdast nodes to specify how they
should be transformed.
See [*Fields on nodes* in
`mdast-util-to-hast`](https://github.com/syntax-tree/mdast-util-to-hast#fields-on-nodes)
for info on how these fields work.

It extends hast by using a semistandard raw nodes for raw HTML.
See the [*HTML* note above](#html) for more info.

## Types

This package is fully typed with [TypeScript][].
It exports the types
[`Options`][api-options].

The types of `mdast-util-to-hast` can be referenced to register data fields
with `@types/mdast` and `Raw` nodes with `@types/hast`.

```js
/**
 * @import {Root as HastRoot} from 'hast'
 * @import {Root as MdastRoot} from 'mdast'
 * @import {} from 'mdast-util-to-hast'
 */

import {visit} from 'unist-util-visit'

const mdastNode = /** @type {MdastRoot} */ ({/* … */})
console.log(mdastNode.data?.hName) // Typed as `string | undefined`.

const hastNode = /** @type {HastRoot} */ ({/* … */})

visit(hastNode, function (node) {
  // `node` can now be `raw`.
})
```

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, `remark-rehype@^11`,
compatible with Node.js 16.

This plugin works with `unified` version 6+, `remark-parse` version 3+ (used in
`remark` version 7), and `rehype-stringify` version 3+ (used in `rehype`
version 5).

## Security

Use of `remark-rehype` can open you up to a
[cross-site scripting (XSS)][wiki-xss] attack.
Embedded **[hast][]** properties (`hName`, `hProperties`, `hChildren`) in
[mdast][], custom handlers, and the `allowDangerousHtml` option all provide
openings.
Use [`rehype-sanitize`][rehype-sanitize] to make the tree safe.

## Related

* [`rehype-raw`][rehype-raw]
  — rehype plugin to parse the tree again and support `raw` nodes
* [`rehype-sanitize`][rehype-sanitize]
  — rehype plugin to sanitize HTML
* [`rehype-remark`](https://github.com/rehypejs/rehype-remark)
  — rehype plugin to turn HTML into markdown
* [`rehype-retext`](https://github.com/rehypejs/rehype-retext)
  — rehype plugin to support retext
* [`remark-retext`](https://github.com/remarkjs/remark-retext)
  — remark plugin to support retext

## Contribute

See [`contributing.md`][contributing] in [`remarkjs/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/remarkjs/remark-rehype/workflows/main/badge.svg

[build]: https://github.com/remarkjs/remark-rehype/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/remarkjs/remark-rehype.svg

[coverage]: https://codecov.io/github/remarkjs/remark-rehype

[downloads-badge]: https://img.shields.io/npm/dm/remark-rehype.svg

[downloads]: https://www.npmjs.com/package/remark-rehype

[size-badge]: https://img.shields.io/bundlejs/size/remark-rehype

[size]: https://bundlejs.com/?q=remark-rehype

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/remarkjs/remark/discussions

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[health]: https://github.com/remarkjs/.github

[contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md

[support]: https://github.com/remarkjs/.github/blob/main/support.md

[coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md

[license]: license

[author]: https://wooorm.com

[github-markdown-css]: https://github.com/sindresorhus/github-markdown-css

[hast]: https://github.com/syntax-tree/hast

[hast-properties]: https://github.com/syntax-tree/hast#properties

[mdast]: https://github.com/syntax-tree/mdast

[mdast-html]: https://github.com/syntax-tree/mdast#html

[mdast-util-to-hast]: https://github.com/syntax-tree/mdast-util-to-hast

[mdast-util-to-hast-default-footnote-back-content]: https://github.com/syntax-tree/mdast-util-to-hast#defaultfootnotebackcontentreferenceindex-rereferenceindex

[mdast-util-to-hast-default-footnote-back-label]: https://github.com/syntax-tree/mdast-util-to-hast#defaultfootnotebacklabelreferenceindex-rereferenceindex

[mdast-util-to-hast-footnote-back-content-template]: https://github.com/syntax-tree/mdast-util-to-hast#footnotebackcontenttemplate

[mdast-util-to-hast-footnote-back-label-template]: https://github.com/syntax-tree/mdast-util-to-hast#footnotebacklabeltemplate

[mdast-util-to-hast-default-handlers]: https://github.com/syntax-tree/mdast-util-to-hast#defaulthandlers

[mdast-util-to-hast-handlers]: https://github.com/syntax-tree/mdast-util-to-hast#handlers

[mdast-util-to-hast-handler]: https://github.com/syntax-tree/mdast-util-to-hast#handler

[rehype]: https://github.com/rehypejs/rehype

[rehype-format]: https://github.com/rehypejs/rehype-format

[rehype-highlight]: https://github.com/rehypejs/rehype-highlight

[rehype-meta]: https://github.com/rehypejs/rehype-meta

[rehype-minify]: https://github.com/rehypejs/rehype-minify

[rehype-raw]: https://github.com/rehypejs/rehype-raw

[rehype-sanitize]: https://github.com/rehypejs/rehype-sanitize

[rehype-sanitize-clobber]: https://github.com/rehypejs/rehype-sanitize#example-headings-dom-clobbering

[rehype-stringify]: https://github.com/rehypejs/rehype/tree/main/packages/rehype-stringify

[rehype-remark]: https://github.com/rehypejs/rehype-remark

[remark]: https://github.com/remarkjs/remark

[remark-gfm]: https://github.com/remarkjs/remark-gfm

[typescript]: https://www.typescriptlang.org

[unified]: https://github.com/unifiedjs/unified

[unified-mode]: https://github.com/unifiedjs/unified#transforming-between-ecosystems

[unified-processor]: https://github.com/unifiedjs/unified#processor

[unified-transformer]: https://github.com/unifiedjs/unified#transformer

[wiki-xss]: https://en.wikipedia.org/wiki/Cross-site_scripting

[api-default-footnote-back-content]: #defaultfootnotebackcontentreferenceindex-rereferenceindex

[api-default-footnote-back-label]: #defaultfootnotebacklabelreferenceindex-rereferenceindex

[api-default-handlers]: #defaulthandlers

[api-options]: #options

[api-remark-rehype]: #unifieduseremarkrehype-destination-options


---

# remark-stringify

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

**[remark][]** plugin to add support for serializing to markdown.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`unified().use(remarkStringify[, options])`](#unifieduseremarkstringify-options)
*   [Syntax](#syntax)
*   [Syntax tree](#syntax-tree)
*   [Types](#types)
*   [Security](#security)
*   [Contribute](#contribute)
*   [Sponsor](#sponsor)
*   [License](#license)

## What is this?

This package is a [unified][] ([remark][]) plugin that defines how to take a
syntax tree as input and turn it into serialized markdown.
When it’s used, markdown is serialized as the final result.

See [the monorepo readme][remark] for info on what the remark ecosystem is.

## When should I use this?

This plugin adds support to unified for serializing markdown.
If you also need to parse markdown, you can alternatively use
[`remark`][remark-core], which combines unified,
[`remark-parse`][remark-parse], and this plugin.

If you don’t use plugins and have access to a syntax tree, you can directly use
[`mdast-util-to-markdown`][mdast-util-to-markdown], which is used inside this
plugin.
remark focusses on making it easier to transform content by abstracting these
internals away.

You can combine this plugin with other plugins to add syntax extensions.
Notable examples that deeply integrate with it are
[`remark-gfm`][remark-gfm],
[`remark-mdx`][remark-mdx],
[`remark-frontmatter`][remark-frontmatter],
[`remark-math`][remark-math], and
[`remark-directive`][remark-directive].
You can also use any other [remark plugin][remark-plugin] before
`remark-stringify`.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install remark-stringify
```

In Deno with [`esm.sh`][esmsh]:

```js
import remarkStringify from 'https://esm.sh/remark-stringify@11'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import remarkStringify from 'https://esm.sh/remark-stringify@11?bundle'
</script>
```

## Use

Say we have the following module `example.js`:

```js
import rehypeParse from 'rehype-parse'
import rehypeRemark from 'rehype-remark'
import remarkStringify from 'remark-stringify'
import {unified} from 'unified'

const doc = `
<h1>Uranus</h1>
<p><b>Uranus</b> is the seventh
<a href="/wiki/Planet" title="Planet">planet</a> from the Sun and is a gaseous
cyan <a href="/wiki/Ice_giant" title="Ice giant">ice giant</a>.</p>
`

const file = await unified()
  .use(rehypeParse)
  .use(rehypeRemark)
  .use(remarkStringify)
  .process(doc)

console.log(String(file))
```

…then running `node example.js` yields:

```markdown
# Uranus

**Uranus** is the seventh [planet](/wiki/Planet "Planet") from the Sun and is a gaseous cyan [ice giant](/wiki/Ice_giant "Ice giant").
```

## API

This package exports no identifiers.
The default export is [`remarkStringify`][api-remark-stringify].

### `unified().use(remarkStringify[, options])`

Add support for serializing to markdown.

###### Parameters

*   `options` ([`Options`][api-options], optional)
    — configuration

###### Returns

Nothing (`undefined`).

### `Options`

Configuration (TypeScript type).

###### Fields

*   `bullet` (`'*'`, `'+'`, or `'-'`, default: `'*'`)
    — marker to use for bullets of items in unordered lists
*   `bulletOther` (`'*'`, `'+'`, or `'-'`, default: `'-'` when `bullet` is
    `'*'`, `'*'` otherwise)
    — marker to use in certain cases where the primary bullet doesn’t work;
    cannot be equal to `bullet`
*   `bulletOrdered` (`'.'` or `')'`, default: `'.'`)
    — marker to use for bullets of items in ordered lists
*   `closeAtx` (`boolean`, default: `false`)
    — add the same number of number signs (`#`) at the end of an ATX heading as
    the opening sequence
*   `emphasis` (`'*'` or `'_'`, default: `'*'`)
    — marker to use for emphasis
*   `fence` (``'`'`` or `'~'`, default: ``'`'``)
    — marker to use for fenced code
*   `fences` (`boolean`, default: `true`)
    — use fenced code always; when `false`, uses fenced code if there is a
    language defined, if the code is empty, or if it starts or ends in blank
    lines
*   `handlers` (`Handlers`, optional)
    — handle particular nodes;
    see [`mdast-util-to-markdown`][mdast-util-to-markdown] for more info
*   `incrementListMarker` (`boolean`, default: `true`)
    — increment the counter of ordered lists items
*   `join` (`Array<Join>`, optional)
    — how to join blocks;
    see [`mdast-util-to-markdown`][mdast-util-to-markdown] for more info
*   `listItemIndent` (`'mixed'`, `'one'`, or `'tab'`, default: `'one'`)
    — how to indent the content of list items;
    either with the size of the bullet plus one space (when `'one'`), a tab
    stop (`'tab'`), or depending on the item and its parent list: `'mixed'`
    uses `'one'` if the item and list are tight and `'tab'` otherwise
*   `quote` (`'"'` or `"'"`, default: `'"'`)
    — marker to use for titles
*   `resourceLink` (`boolean`, default: `false`)
    — always use resource links (`[text](url)`);
    when `false`, uses autolinks (`<https://example.com>`) when possible
*   `rule` (`'*'`, `'-'`, or `'_'`, default: `'*'`)
    — marker to use for thematic breaks
*   `ruleRepetition` (`number`, default: `3`, min: `3`)
    — number of markers to use for thematic breaks
*   `ruleSpaces` (`boolean`, default: `false`)
    — add spaces between markers in thematic breaks
*   `setext` (`boolean`, default: `false`)
    — use setext headings when possible;
    when `true`, uses setext headings (`heading\n=======`) for non-empty rank 1
    or 2 headings
*   `strong` (`'*'` or `'_'`, default: `'*'`)
    — marker to use for strong
*   `tightDefinitions` (`boolean`, default: `false`)
    — join definitions without a blank line
*   `unsafe` (`Array<Unsafe>`, optional)
    — schemas that define when characters cannot occur;
    see [`mdast-util-to-markdown`][mdast-util-to-markdown] for more info

<!-- Note: `extensions` intentionally not supported/documented. -->

## Syntax

Markdown is serialized according to CommonMark but care is taken to format in a
way that works with most markdown parsers.
Other plugins can add support for syntax extensions.

## Syntax tree

The syntax tree used in remark is [mdast][].

## Types

This package is fully typed with [TypeScript][].
It exports the additional type [`Options`][api-options].

It also registers `Settings` with `unified`.
If you’re passing options with `.data('settings', …)`, make sure to import this
package somewhere in your types, as that registers the fields.

```js
/// <reference types="remark-stringify" />

import {unified} from 'unified'

// @ts-expect-error: `thisDoesNotExist` is not a valid option.
unified().data('settings', {thisDoesNotExist: false})
```

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, `remark-stringify@^11`,
compatible with Node.js 16.

## Security

Use of `remark-stringify` is safe.

Use of remark plugins can open you up to attacks.
Carefully assess each plugin and the risks involved in using them.

For info on how to submit a report, see our [security policy][security].

## Contribute

See [`contributing.md`][contributing] in [`remarkjs/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.
Join us in [Discussions][chat] to chat with the community and contributors.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## Sponsor

Support this effort and give back by sponsoring on [OpenCollective][collective]!

<table>
<tr valign="middle">
<td width="20%" align="center" rowspan="2" colspan="2">
  <a href="https://vercel.com">Vercel</a><br><br>
  <a href="https://vercel.com"><img src="https://avatars1.githubusercontent.com/u/14985020?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
  <a href="https://motif.land">Motif</a><br><br>
  <a href="https://motif.land"><img src="https://avatars1.githubusercontent.com/u/74457950?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
  <a href="https://www.hashicorp.com">HashiCorp</a><br><br>
  <a href="https://www.hashicorp.com"><img src="https://avatars1.githubusercontent.com/u/761456?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
  <a href="https://www.gitbook.com">GitBook</a><br><br>
  <a href="https://www.gitbook.com"><img src="https://avatars1.githubusercontent.com/u/7111340?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
  <a href="https://www.gatsbyjs.org">Gatsby</a><br><br>
  <a href="https://www.gatsbyjs.org"><img src="https://avatars1.githubusercontent.com/u/12551863?s=256&v=4" width="128"></a>
</td>
</tr>
<tr valign="middle">
</tr>
<tr valign="middle">
<td width="20%" align="center" rowspan="2" colspan="2">
  <a href="https://www.netlify.com">Netlify</a><br><br>
  <!--OC has a sharper image-->
  <a href="https://www.netlify.com"><img src="https://images.opencollective.com/netlify/4087de2/logo/256.png" width="128"></a>
</td>
<td width="10%" align="center">
  <a href="https://www.coinbase.com">Coinbase</a><br><br>
  <a href="https://www.coinbase.com"><img src="https://avatars1.githubusercontent.com/u/1885080?s=256&v=4" width="64"></a>
</td>
<td width="10%" align="center">
  <a href="https://themeisle.com">ThemeIsle</a><br><br>
  <a href="https://themeisle.com"><img src="https://avatars1.githubusercontent.com/u/58979018?s=128&v=4" width="64"></a>
</td>
<td width="10%" align="center">
  <a href="https://expo.io">Expo</a><br><br>
  <a href="https://expo.io"><img src="https://avatars1.githubusercontent.com/u/12504344?s=128&v=4" width="64"></a>
</td>
<td width="10%" align="center">
  <a href="https://boostnote.io">Boost Note</a><br><br>
  <a href="https://boostnote.io"><img src="https://images.opencollective.com/boosthub/6318083/logo/128.png" width="64"></a>
</td>
<td width="10%" align="center">
  <a href="https://markdown.space">Markdown Space</a><br><br>
  <a href="https://markdown.space"><img src="https://images.opencollective.com/markdown-space/e1038ed/logo/128.png" width="64"></a>
</td>
<td width="10%" align="center">
  <a href="https://www.holloway.com">Holloway</a><br><br>
  <a href="https://www.holloway.com"><img src="https://avatars1.githubusercontent.com/u/35904294?s=128&v=4" width="64"></a>
</td>
<td width="10%"></td>
<td width="10%"></td>
</tr>
<tr valign="middle">
<td width="100%" align="center" colspan="8">
  <br>
  <a href="https://opencollective.com/unified"><strong>You?</strong></a>
  <br><br>
</td>
</tr>
</table>

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/remarkjs/remark/workflows/main/badge.svg

[build]: https://github.com/remarkjs/remark/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/remarkjs/remark.svg

[coverage]: https://codecov.io/github/remarkjs/remark

[downloads-badge]: https://img.shields.io/npm/dm/remark-stringify.svg

[downloads]: https://www.npmjs.com/package/remark-stringify

[size-badge]: https://img.shields.io/bundlejs/size/remark-stringify

[size]: https://bundlejs.com/?q=remark-stringify

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/remarkjs/remark/discussions

[security]: https://github.com/remarkjs/.github/blob/main/security.md

[health]: https://github.com/remarkjs/.github

[contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md

[support]: https://github.com/remarkjs/.github/blob/main/support.md

[coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md

[license]: https://github.com/remarkjs/remark/blob/main/license

[author]: https://wooorm.com

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[mdast]: https://github.com/syntax-tree/mdast

[mdast-util-to-markdown]: https://github.com/syntax-tree/mdast-util-to-markdown

[remark]: https://github.com/remarkjs/remark

[remark-core]: ../remark/

[remark-directive]: https://github.com/remarkjs/remark-directive

[remark-frontmatter]: https://github.com/remarkjs/remark-frontmatter

[remark-gfm]: https://github.com/remarkjs/remark-gfm

[remark-math]: https://github.com/remarkjs/remark-math

[remark-mdx]: https://github.com/mdx-js/mdx/tree/main/packages/remark-mdx

[remark-parse]: ../remark-parse/

[remark-plugin]: https://github.com/remarkjs/remark#plugin

[typescript]: https://www.typescriptlang.org

[unified]: https://github.com/unifiedjs/unified

[api-options]: #options

[api-remark-stringify]: #unifieduseremarkstringify-options


---

# Renderkid Changelog

## `3.0.0`

* **Breaking change**: Dropped support for Node `<12.x`

---

# RenderKid
[![Build Status](https://secure.travis-ci.org/AriaMinaei/RenderKid.png)](http://travis-ci.org/AriaMinaei/RenderKid)

RenderKid allows you to use HTML and CSS to style your CLI output, making it easy to create a beautiful, readable, and consistent look for your nodejs tool.

## Installation

Install with npm:
```
$ npm install renderkid
```

## Usage

```coffeescript
RenderKid = require('renderkid')

r = new RenderKid()

r.style({
  "ul": {
    display: "block"
    margin: "2 0 2"
  }

  "li": {
    display: "block"
    marginBottom: "1"
  }

  "key": {
    color: "grey"
    marginRight: "1"
  }

  "value": {
    color: "bright-white"
  }
})

output = r.render("
<ul>
  <li>
    <key>Name:</key>
    <value>RenderKid</value>
  </li>
  <li>
    <key>Version:</key>
    <value>0.2</value>
  </li>
  <li>
    <key>Last Update:</key>
    <value>Jan 2015</value>
  </li>
</ul>
")

console.log(output)
```

![screenshot of usage](https://github.com/AriaMinaei/RenderKid/raw/master/docs/images/usage.png)

## Stylesheet properties

### Display mode

Elements can have a `display` of either `inline`, `block`, or `none`:
```coffeescript
r.style({
  "div": {
    display: "block"
  }

  "span": {
    display: "inline" # default
  }

  "hidden": {
    display: "none"
  }
})

output = r.render("
<div>This will fill one or more rows.</div>
<span>These</span> <span>will</span> <span>be</span> in the same <span>line.</span>
<hidden>This won't be displayed.</hidden>
")

console.log(output)
```

![screenshot of usage](https://github.com/AriaMinaei/RenderKid/raw/master/docs/images/display.png)


### Margin

Margins work just like they do in browsers:
```coffeescript
r.style({
  "li": {
    display: "block"

    marginTop: "1"
    marginRight: "2"
    marginBottom: "3"
    marginLeft: "4"

    # or the shorthand version:
    "margin": "1 2 3 4"
  },

  "highlight": {
    display: "inline"
    marginLeft: "2"
    marginRight: "2"
  }
})

r.render("
<ul>
  <li>Item <highlgiht>1</highlight></li>
  <li>Item <highlgiht>2</highlight></li>
  <li>Item <highlgiht>3</highlight></li>
</ul>
")
```

### Padding

See margins above. Paddings work the same way, only inward.

### Width and Height

Block elements can have explicit width and height:
```coffeescript
r.style({
  "box": {
    display: "block"
    "width": "4"
    "height": "2"
  }
})

r.render("<box>This is a box and some of its text will be truncated.</box>")
```

### Colors

You can set a custom color and background color for each element:

```coffeescript
r.style({
  "error": {
    color: "black"
    background: "red"
  }
})
```

List of colors currently supported are `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`, `grey`, `bright-red`, `bright-green`, `bright-yellow`, `bright-blue`, `bright-magenta`, `bright-cyan`, `bright-white`.

### Bullet points

Block elements can have bullet points on their margins. Let's start with an example:
```coffeescript
r.style({
  "li": {
    # To add bullet points to an element, first you
    # should make some room for the bullet point by
    # giving your element some margin to the left:
    marginLeft: "4",

    # Now we can add a bullet point to our margin:
    bullet: '"-"'
  }
})

# The four hyphens are there for visual reference
r.render("
----
<li>Item 1</li>
<li>Item 2</li>
<li>Item 3</li>
----
")
```
And here is the result:

![screenshot of bullet points, 1](https://github.com/AriaMinaei/RenderKid/raw/master/docs/images/bullets-1.png)


---

# Security Policy

## Supported Versions

| Version | Supported          |
| ------- | ------------------ |
| 2.0.x   | :white_check_mark: |

## Reporting a Vulnerability

Send security alerts to aria@theatrejs.com


---

# css-select [![NPM version](http://img.shields.io/npm/v/css-select.svg)](https://npmjs.org/package/css-select) [![Build Status](https://travis-ci.com/fb55/css-select.svg?branch=master)](http://travis-ci.com/fb55/css-select) [![Downloads](https://img.shields.io/npm/dm/css-select.svg)](https://npmjs.org/package/css-select) [![Coverage](https://coveralls.io/repos/fb55/css-select/badge.svg?branch=master)](https://coveralls.io/r/fb55/css-select)

A CSS selector compiler and engine

## What?

As a **compiler**, css-select turns CSS selectors into functions that tests if
elements match them.

As an **engine**, css-select looks through a DOM tree, searching for elements.
Elements are tested "from the top", similar to how browsers execute CSS
selectors.

In its default configuration, css-select queries the DOM structure of the
[`domhandler`](https://github.com/fb55/domhandler) module (also known as
htmlparser2 DOM). To query alternative DOM structures, see [`Options`](#options)
below.

**Features:**

-   🔬 Full implementation of CSS3 selectors, as well as most CSS4 selectors
-   🧪 Partial implementation of jQuery/Sizzle extensions (see
    [cheerio-select](https://github.com/cheeriojs/cheerio-select) for the
    remaining selectors)
-   🧑‍🔬 High test coverage, including the full test suites from Sizzle, Qwery and
    NWMatcher.
-   🥼 Reliably great performance

## Why?

Most CSS engines written in JavaScript execute selectors left-to-right. That
means thet execute every component of the selector in order, from left to right
_(duh)_. As an example: For the selector `a b`, these engines will first query
for `a` elements, then search these for `b` elements. (That's the approach of
eg. [`Sizzle`](https://github.com/jquery/sizzle),
[`nwmatcher`](https://github.com/dperini/nwmatcher/) and
[`qwery`](https://github.com/ded/qwery).)

While this works, it has some downsides: Children of `a`s will be checked
multiple times; first, to check if they are also `a`s, then, for every superior
`a` once, if they are `b`s. Using
[Big O notation](http://en.wikipedia.org/wiki/Big_O_notation), that would be
`O(n^(k+1))`, where `k` is the number of descendant selectors (that's the space
in the example above).

The far more efficient approach is to first look for `b` elements, then check if
they have superior `a` elements: Using big O notation again, that would be
`O(n)`. That's called right-to-left execution.

And that's what css-select does – and why it's quite performant.

## How does it work?

By building a stack of functions.

_Wait, what?_

Okay, so let's suppose we want to compile the selector `a b`, for right-to-left
execution. We start by _parsing_ the selector. This turns the selector into an
array of the building blocks. That's what the
[`css-what`](https://github.com/fb55/css-what) module is for, if you want to
have a look.

Anyway, after parsing, we end up with an array like this one:

```js
[
    { type: "tag", name: "a" },
    { type: "descendant" },
    { type: "tag", name: "b" },
];
```

(Actually, this array is wrapped in another array, but that's another story,
involving commas in selectors.)

Now that we know the meaning of every part of the selector, we can compile it.
That is where things become interesting.

The basic idea is to turn every part of the selector into a function, which
takes an element as its only argument. The function checks whether a passed
element matches its part of the selector: If it does, the element is passed to
the next function representing the next part of the selector. That function does
the same. If an element is accepted by all parts of the selector, it _matches_
the selector and double rainbow ALL THE WAY.

As said before, we want to do right-to-left execution with all the big O
improvements. That means elements are passed from the rightmost part of the
selector (`b` in our example) to the leftmost (~~which would be `c`~~ of course
`a`).

For traversals, such as the _descendant_ operating the space between `a` and
`b`, we walk up the DOM tree, starting from the element passed as argument.

_//TODO: More in-depth description. Implementation details. Build a spaceship._

## API

```js
const CSSselect = require("css-select");
```

**Note:** css-select throws errors when invalid selectors are passed to it.This
is done to aid with writing css selectors, but can be unexpected when processing
arbitrary strings.

#### `CSSselect.selectAll(query, elems, options)`

Queries `elems`, returns an array containing all matches.

-   `query` can be either a CSS selector or a function.
-   `elems` can be either an array of elements, or a single element. If it is an
    element, its children will be queried.
-   `options` is described below.

Aliases: `default` export, `CSSselect.iterate(query, elems)`.

#### `CSSselect.compile(query, options)`

Compiles the query, returns a function.

#### `CSSselect.is(elem, query, options)`

Tests whether or not an element is matched by `query`. `query` can be either a
CSS selector or a function.

#### `CSSselect.selectOne(query, elems, options)`

Arguments are the same as for `CSSselect.selectAll(query, elems)`. Only returns
the first match, or `null` if there was no match.

### Options

All options are optional.

-   `xmlMode`: When enabled, tag names will be case-sensitive. Default: `false`.
-   `rootFunc`: The last function in the stack, will be called with the last
    element that's looked at.
-   `adapter`: The adapter to use when interacting with the backing DOM
    structure. By default it uses the `domutils` module.
-   `context`: The context of the current query. Used to limit the scope of
    searches. Can be matched directly using the `:scope` pseudo-selector.
-   `cacheResults`: Allow css-select to cache results for some selectors,
    sometimes greatly improving querying performance. Disable this if your
    document can change in between queries with the same compiled selector.
    Default: `true`.

#### Custom Adapters

A custom adapter must match the interface described
[here](https://github.com/fb55/css-select/blob/1aa44bdd64aaf2ebdfd7f338e2e76bed36521957/src/types.ts#L6-L96).

You may want to have a look at [`domutils`](https://github.com/fb55/domutils) to
see the default implementation, or at
[`css-select-browser-adapter`](https://github.com/nrkn/css-select-browser-adapter/blob/master/index.js)
for an implementation backed by the DOM.

## Supported selectors

_As defined by CSS 4 and / or jQuery._

-   [Selector lists](https://developer.mozilla.org/en-US/docs/Web/CSS/Selector_list)
    (`,`)
-   [Universal](https://developer.mozilla.org/en-US/docs/Web/CSS/Universal_selectors)
    (`*`)
-   [Type](https://developer.mozilla.org/en-US/docs/Web/CSS/Type_selectors)
    (`<tagname>`)
-   [Descendant](https://developer.mozilla.org/en-US/docs/Web/CSS/Descendant_combinator)
    (` `)
-   [Child](https://developer.mozilla.org/en-US/docs/Web/CSS/Child_combinator)
    (`>`)
-   Parent (`<`)
-   [Adjacent sibling](https://developer.mozilla.org/en-US/docs/Web/CSS/Adjacent_sibling_combinator)
    (`+`)
-   [General sibling](https://developer.mozilla.org/en-US/docs/Web/CSS/General_sibling_combinator)
    (`~`)
-   [Attribute](https://developer.mozilla.org/en-US/docs/Web/CSS/Attribute_selectors)
    (`[attr=foo]`), with supported comparisons:
    -   `[attr]` (existential)
    -   `=`
    -   `~=`
    -   `|=`
    -   `*=`
    -   `^=`
    -   `$=`
    -   `!=`
    -   `i` and `s` can be added after the comparison to make the comparison
        case-insensitive or case-sensitive (eg. `[attr=foo i]`). If neither is
        supplied, css-select will follow the HTML spec's
        [case-sensitivity rules](https://html.spec.whatwg.org/multipage/semantics-other.html#case-sensitivity-of-selectors).
-   Pseudos:
    -   [`:not`](https://developer.mozilla.org/en-US/docs/Web/CSS/:not)
    -   [`:contains`](https://api.jquery.com/contains-selector)
    -   `:icontains` (case-insensitive version of `:contains`)
    -   [`:has`](https://developer.mozilla.org/en-US/docs/Web/CSS/:has)
    -   [`:root`](https://developer.mozilla.org/en-US/docs/Web/CSS/:root)
    -   [`:empty`](https://developer.mozilla.org/en-US/docs/Web/CSS/:empty)
    -   [`:parent`](https://api.jquery.com/parent-selector)
    -   [`:first-child`](https://developer.mozilla.org/en-US/docs/Web/CSS/:first-child),
        [`:last-child`](https://developer.mozilla.org/en-US/docs/Web/CSS/:last-child),
        [`:first-of-type`](https://developer.mozilla.org/en-US/docs/Web/CSS/:first-of-type),
        [`:last-of-type`](https://developer.mozilla.org/en-US/docs/Web/CSS/:last-of-type)
    -   [`:only-of-type`](https://developer.mozilla.org/en-US/docs/Web/CSS/:only-of-type),
        [`:only-child`](https://developer.mozilla.org/en-US/docs/Web/CSS/:only-child)
    -   [`:nth-child`](https://developer.mozilla.org/en-US/docs/Web/CSS/:nth-child),
        [`:nth-last-child`](https://developer.mozilla.org/en-US/docs/Web/CSS/:nth-last-child),
        [`:nth-of-type`](https://developer.mozilla.org/en-US/docs/Web/CSS/:nth-of-type),
        [`:nth-last-of-type`](https://developer.mozilla.org/en-US/docs/Web/CSS/:nth-last-of-type),
    -   [`:link`](https://developer.mozilla.org/en-US/docs/Web/CSS/:link),
        [`:any-link`](https://developer.mozilla.org/en-US/docs/Web/CSS/:any-link)
    -   [`:visited`](https://developer.mozilla.org/en-US/docs/Web/CSS/:visited),
        [`:hover`](https://developer.mozilla.org/en-US/docs/Web/CSS/:hover),
        [`:active`](https://developer.mozilla.org/en-US/docs/Web/CSS/:active)
        (these depend on optional `Adapter` methods, so these will only match
        elements if implemented in `Adapter`)
    -   [`:selected`](https://api.jquery.com/selected-selector),
        [`:checked`](https://developer.mozilla.org/en-US/docs/Web/CSS/:checked)
    -   [`:enabled`](https://developer.mozilla.org/en-US/docs/Web/CSS/:enabled),
        [`:disabled`](https://developer.mozilla.org/en-US/docs/Web/CSS/:disabled)
    -   [`:required`](https://developer.mozilla.org/en-US/docs/Web/CSS/:required),
        [`:optional`](https://developer.mozilla.org/en-US/docs/Web/CSS/:optional)
    -   [`:header`](https://api.jquery.com/header-selector),
        [`:button`](https://api.jquery.com/button-selector),
        [`:input`](https://api.jquery.com/input-selector),
        [`:text`](https://api.jquery.com/text-selector),
        [`:checkbox`](https://api.jquery.com/checkbox-selector),
        [`:file`](https://api.jquery.com/file-selector),
        [`:password`](https://api.jquery.com/password-selector),
        [`:reset`](https://api.jquery.com/reset-selector),
        [`:radio`](https://api.jquery.com/radio-selector) etc.
    -   [`:is`](https://developer.mozilla.org/en-US/docs/Web/CSS/:is), plus its
        legacy alias `:matches`
    -   [`:scope`](https://developer.mozilla.org/en-US/docs/Web/CSS/:scope)
        (uses the context from the passed options)

---

License: BSD-2-Clause

## Security contact information

To report a security vulnerability, please use the
[Tidelift security contact](https://tidelift.com/security). Tidelift will
coordinate the fix and disclosure.

## `css-select` for enterprise

Available as part of the Tidelift Subscription

The maintainers of `css-select` and thousands of other packages are working with
Tidelift to deliver commercial support and maintenance for the open source
dependencies you use to build your applications. Save time, reduce risk, and
improve code health, while paying the maintainers of the exact dependencies you
use.
[Learn more.](https://tidelift.com/subscription/pkg/npm-css-select?utm_source=npm-css-select&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)


---

# dom-serializer [![Build Status](https://travis-ci.com/cheeriojs/dom-serializer.svg?branch=master)](https://travis-ci.com/cheeriojs/dom-serializer)

Renders a [domhandler](https://github.com/fb55/domhandler) DOM node or an array of domhandler DOM nodes to a string.

```js
import render from "dom-serializer";

// OR

const render = require("dom-serializer").default;
```

# API

## `render`

▸ **render**(`node`: Node \| Node[], `options?`: [_Options_](#Options)): _string_

Renders a DOM node or an array of DOM nodes to a string.

Can be thought of as the equivalent of the `outerHTML` of the passed node(s).

#### Parameters:

| Name      | Type                               | Default value | Description                    |
| :-------- | :--------------------------------- | :------------ | :----------------------------- |
| `node`    | Node \| Node[]                     | -             | Node to be rendered.           |
| `options` | [_DomSerializerOptions_](#Options) | {}            | Changes serialization behavior |

**Returns:** _string_

## Options

### `decodeEntities`

• `Optional` **decodeEntities**: _boolean_

Encode characters that are either reserved in HTML or XML, or are outside of the ASCII range.

**`default`** true

---

### `emptyAttrs`

• `Optional` **emptyAttrs**: _boolean_

Print an empty attribute's value.

**`default`** xmlMode

**`example`** With <code>emptyAttrs: false</code>: <code>&lt;input checked&gt;</code>

**`example`** With <code>emptyAttrs: true</code>: <code>&lt;input checked=""&gt;</code>

---

### `selfClosingTags`

• `Optional` **selfClosingTags**: _boolean_

Print self-closing tags for tags without contents.

**`default`** xmlMode

**`example`** With <code>selfClosingTags: false</code>: <code>&lt;foo&gt;&lt;/foo&gt;</code>

**`example`** With <code>selfClosingTags: true</code>: <code>&lt;foo /&gt;</code>

---

### `xmlMode`

• `Optional` **xmlMode**: _boolean_ \| _"foreign"_

Treat the input as an XML document; enables the `emptyAttrs` and `selfClosingTags` options.

If the value is `"foreign"`, it will try to correct mixed-case attribute names.

**`default`** false

---

## Ecosystem

| Name                                                          | Description                                             |
| ------------------------------------------------------------- | ------------------------------------------------------- |
| [htmlparser2](https://github.com/fb55/htmlparser2)            | Fast & forgiving HTML/XML parser                        |
| [domhandler](https://github.com/fb55/domhandler)              | Handler for htmlparser2 that turns documents into a DOM |
| [domutils](https://github.com/fb55/domutils)                  | Utilities for working with domhandler's DOM             |
| [css-select](https://github.com/fb55/css-select)              | CSS selector engine, compatible with domhandler's DOM   |
| [cheerio](https://github.com/cheeriojs/cheerio)               | The jQuery API for domhandler's DOM                     |
| [dom-serializer](https://github.com/cheeriojs/dom-serializer) | Serializer for domhandler's DOM                         |

---

LICENSE: MIT


---

# domhandler [![Build Status](https://travis-ci.com/fb55/domhandler.svg?branch=master)](https://travis-ci.com/fb55/domhandler)

The DOM handler creates a tree containing all nodes of a page.
The tree can be manipulated using the [domutils](https://github.com/fb55/domutils)
or [cheerio](https://github.com/cheeriojs/cheerio) libraries and
rendered using [dom-serializer](https://github.com/cheeriojs/dom-serializer) .

## Usage

```javascript
const handler = new DomHandler([ <func> callback(err, dom), ] [ <obj> options ]);
// const parser = new Parser(handler[, options]);
```

Available options are described below.

## Example

```javascript
const { Parser } = require("htmlparser2");
const { DomHandler } = require("domhandler");
const rawHtml =
    "Xyz <script language= javascript>var foo = '<<bar>>';</script><!--<!-- Waah! -- -->";
const handler = new DomHandler((error, dom) => {
    if (error) {
        // Handle error
    } else {
        // Parsing completed, do something
        console.log(dom);
    }
});
const parser = new Parser(handler);
parser.write(rawHtml);
parser.end();
```

Output:

```javascript
[
    {
        data: "Xyz ",
        type: "text",
    },
    {
        type: "script",
        name: "script",
        attribs: {
            language: "javascript",
        },
        children: [
            {
                data: "var foo = '<bar>';<",
                type: "text",
            },
        ],
    },
    {
        data: "<!-- Waah! -- ",
        type: "comment",
    },
];
```

## Option: `withStartIndices`

Add a `startIndex` property to nodes.
When the parser is used in a non-streaming fashion, `startIndex` is an integer
indicating the position of the start of the node in the document.
The default value is `false`.

## Option: `withEndIndices`

Add an `endIndex` property to nodes.
When the parser is used in a non-streaming fashion, `endIndex` is an integer
indicating the position of the end of the node in the document.
The default value is `false`.

## Option: `normalizeWhitespace` _(deprecated)_

Replace all whitespace with single spaces.
The default value is `false`.

**Note:** Enabling this might break your markup.

For the following examples, this HTML will be used:

```html
<font> <br />this is the text <font></font></font>
```

### Example: `normalizeWhitespace: true`

```javascript
[
    {
        type: "tag",
        name: "font",
        children: [
            {
                data: " ",
                type: "text",
            },
            {
                type: "tag",
                name: "br",
            },
            {
                data: "this is the text ",
                type: "text",
            },
            {
                type: "tag",
                name: "font",
            },
        ],
    },
];
```

### Example: `normalizeWhitespace: false`

```javascript
[
    {
        type: "tag",
        name: "font",
        children: [
            {
                data: "\n\t",
                type: "text",
            },
            {
                type: "tag",
                name: "br",
            },
            {
                data: "this is the text\n",
                type: "text",
            },
            {
                type: "tag",
                name: "font",
            },
        ],
    },
];
```

---

License: BSD-2-Clause

## Security contact information

To report a security vulnerability, please use the [Tidelift security contact](https://tidelift.com/security).
Tidelift will coordinate the fix and disclosure.

## `domhandler` for enterprise

Available as part of the Tidelift Subscription

The maintainers of `domhandler` and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-domhandler?utm_source=npm-domhandler&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)


---

# domutils [![Build Status](https://travis-ci.com/fb55/domutils.svg?branch=master)](https://travis-ci.com/fb55/domutils)

Utilities for working with [htmlparser2](https://github.com/fb55/htmlparser2)'s DOM.

All functions are exported as a single module. Look [through the docs](https://domutils.js.org/modules.html) to see what is available.

## Ecosystem

| Name                                                          | Description                                             |
| ------------------------------------------------------------- | ------------------------------------------------------- |
| [htmlparser2](https://github.com/fb55/htmlparser2)            | Fast & forgiving HTML/XML parser                        |
| [domhandler](https://github.com/fb55/domhandler)              | Handler for htmlparser2 that turns documents into a DOM |
| [domutils](https://github.com/fb55/domutils)                  | Utilities for working with domhandler's DOM             |
| [css-select](https://github.com/fb55/css-select)              | CSS selector engine, compatible with domhandler's DOM   |
| [cheerio](https://github.com/cheeriojs/cheerio)               | The jQuery API for domhandler's DOM                     |
| [dom-serializer](https://github.com/cheeriojs/dom-serializer) | Serializer for domhandler's DOM                         |

---

License: BSD-2-Clause

## Security contact information

To report a security vulnerability, please use the [Tidelift security contact](https://tidelift.com/security).
Tidelift will coordinate the fix and disclosure.

## `domutils` for enterprise

Available as part of the Tidelift Subscription

The maintainers of `domutils` and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-domutils?utm_source=npm-domutils&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)


---

# entities [![NPM version](http://img.shields.io/npm/v/entities.svg)](https://npmjs.org/package/entities) [![Downloads](https://img.shields.io/npm/dm/entities.svg)](https://npmjs.org/package/entities) [![Build Status](http://img.shields.io/travis/fb55/entities.svg)](http://travis-ci.org/fb55/entities) [![Coverage](http://img.shields.io/coveralls/fb55/entities.svg)](https://coveralls.io/r/fb55/entities)

Encode & decode HTML & XML entities with ease & speed.

## How to…

### …install `entities`

    npm install entities

### …use `entities`

```javascript
const entities = require("entities");

//encoding
entities.escape("&#38;"); // "&#x26;#38;"
entities.encodeXML("&#38;"); // "&amp;#38;"
entities.encodeHTML("&#38;"); // "&amp;&num;38&semi;"

//decoding
entities.decodeXML("asdf &amp; &#xFF; &#xFC; &apos;"); // "asdf & ÿ ü '"
entities.decodeHTML("asdf &amp; &yuml; &uuml; &apos;"); // "asdf & ÿ ü '"
```

## Performance

This is how `entities` compares to other libraries on a very basic benchmark
(see `scripts/benchmark.ts`, for 10,000,000 iterations):

| Library        | `decode` performance | `encode` performance | Bundle size                                                                |
| -------------- | -------------------- | -------------------- | -------------------------------------------------------------------------- |
| entities       | 10.809s              | 17.683s              | ![npm bundle size](https://img.shields.io/bundlephobia/min/entities)       |
| html-entities  | 14.029s              | 22.670s              | ![npm bundle size](https://img.shields.io/bundlephobia/min/html-entities)  |
| he             | 16.163s              | 44.010s              | ![npm bundle size](https://img.shields.io/bundlephobia/min/he)             |
| parse-entities | 28.507s              | N/A                  | ![npm bundle size](https://img.shields.io/bundlephobia/min/parse-entities) |

---

License: BSD-2-Clause

## Security contact information

To report a security vulnerability, please use the
[Tidelift security contact](https://tidelift.com/security). Tidelift will
coordinate the fix and disclosure.

## `entities` for enterprise

Available as part of the Tidelift Subscription

The maintainers of `entities` and thousands of other packages are working with
Tidelift to deliver commercial support and maintenance for the open source
dependencies you use to build your applications. Save time, reduce risk, and
improve code health, while paying the maintainers of the exact dependencies you
use.
[Learn more.](https://tidelift.com/subscription/pkg/npm-entities?utm_source=npm-entities&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)


---

# htmlparser2

[![NPM version](http://img.shields.io/npm/v/htmlparser2.svg?style=flat)](https://npmjs.org/package/htmlparser2)
[![Downloads](https://img.shields.io/npm/dm/htmlparser2.svg?style=flat)](https://npmjs.org/package/htmlparser2)
[![Build Status](https://img.shields.io/github/workflow/status/fb55/htmlparser2/Node.js%20Test?label=tests&style=flat)](https://github.com/fb55/htmlparser2/actions?query=workflow%3A%22Node.js+Test%22)
[![Coverage](http://img.shields.io/coveralls/fb55/htmlparser2.svg?style=flat)](https://coveralls.io/r/fb55/htmlparser2)

The fast & forgiving HTML/XML parser.

## Installation

    npm install htmlparser2

A live demo of `htmlparser2` is available [here](https://astexplorer.net/#/2AmVrGuGVJ).

## Ecosystem

| Name                                                          | Description                                             |
| ------------------------------------------------------------- | ------------------------------------------------------- |
| [htmlparser2](https://github.com/fb55/htmlparser2)            | Fast & forgiving HTML/XML parser                        |
| [domhandler](https://github.com/fb55/domhandler)              | Handler for htmlparser2 that turns documents into a DOM |
| [domutils](https://github.com/fb55/domutils)                  | Utilities for working with domhandler's DOM             |
| [css-select](https://github.com/fb55/css-select)              | CSS selector engine, compatible with domhandler's DOM   |
| [cheerio](https://github.com/cheeriojs/cheerio)               | The jQuery API for domhandler's DOM                     |
| [dom-serializer](https://github.com/cheeriojs/dom-serializer) | Serializer for domhandler's DOM                         |

## Usage

`htmlparser2` itself provides a callback interface that allows consumption of documents with minimal allocations.
For a more ergonomic experience, read [Getting a DOM](#getting-a-dom) below.

```javascript
const htmlparser2 = require("htmlparser2");
const parser = new htmlparser2.Parser({
    onopentag(name, attributes) {
        /*
         * This fires when a new tag is opened.
         *
         * If you don't need an aggregated `attributes` object,
         * have a look at the `onopentagname` and `onattribute` events.
         */
        if (name === "script" && attributes.type === "text/javascript") {
            console.log("JS! Hooray!");
        }
    },
    ontext(text) {
        /*
         * Fires whenever a section of text was processed.
         *
         * Note that this can fire at any point within text and you might
         * have to stich together multiple pieces.
         */
        console.log("-->", text);
    },
    onclosetag(tagname) {
        /*
         * Fires when a tag is closed.
         *
         * You can rely on this event only firing when you have received an
         * equivalent opening tag before. Closing tags without corresponding
         * opening tags will be ignored.
         */
        if (tagname === "script") {
            console.log("That's it?!");
        }
    },
});
parser.write(
    "Xyz <script type='text/javascript'>const foo = '<<bar>>';</ script>"
);
parser.end();
```

Output (with multiple text events combined):

```
--> Xyz
JS! Hooray!
--> const foo = '<<bar>>';
That's it?!
```

This example only shows three of the possible events.
Read more about the parser, its events and options in the [wiki](https://github.com/fb55/htmlparser2/wiki/Parser-options).

### Usage with streams

While the `Parser` interface closely resembles Node.js streams, it's not a 100% match.
Use the `WritableStream` interface to process a streaming input:

```javascript
const { WritableStream } = require("htmlparser2/lib/WritableStream");
const parserStream = new WritableStream({
    ontext(text) {
        console.log("Streaming:", text);
    },
});

const htmlStream = fs.createReadStream("./my-file.html");
htmlStream.pipe(parserStream).on("finish", () => console.log("done"));
```

## Getting a DOM

The `DomHandler` produces a DOM (document object model) that can be manipulated using the [`DomUtils`](https://github.com/fb55/DomUtils) helper.

```js
const htmlparser2 = require("htmlparser2");

const dom = htmlparser2.parseDocument();
```

The `DomHandler`, while still bundled with this module, was moved to its [own module](https://github.com/fb55/domhandler).
Have a look at that for further information.

## Parsing RSS/RDF/Atom Feeds

```javascript
const feed = htmlparser2.parseFeed(content, options);
```

Note: While the provided feed handler works for most feeds,
you might want to use [danmactough/node-feedparser](https://github.com/danmactough/node-feedparser), which is much better tested and actively maintained.

## Performance

After having some artificial benchmarks for some time, **@AndreasMadsen** published his [`htmlparser-benchmark`](https://github.com/AndreasMadsen/htmlparser-benchmark), which benchmarks HTML parses based on real-world websites.

At the time of writing, the latest versions of all supported parsers show the following performance characteristics on [Travis CI](https://travis-ci.org/AndreasMadsen/htmlparser-benchmark/builds/10805007) (please note that Travis doesn't guarantee equal conditions for all tests):

```
gumbo-parser   : 34.9208 ms/file ± 21.4238
html-parser    : 24.8224 ms/file ± 15.8703
html5          : 419.597 ms/file ± 264.265
htmlparser     : 60.0722 ms/file ± 384.844
htmlparser2-dom: 12.0749 ms/file ± 6.49474
htmlparser2    : 7.49130 ms/file ± 5.74368
hubbub         : 30.4980 ms/file ± 16.4682
libxmljs       : 14.1338 ms/file ± 18.6541
parse5         : 22.0439 ms/file ± 15.3743
sax            : 49.6513 ms/file ± 26.6032
```

## How does this module differ from [node-htmlparser](https://github.com/tautologistics/node-htmlparser)?

This module started as a fork of the `htmlparser` module.
The main difference is that `htmlparser2` is intended to be used only with node (it runs on other platforms using [browserify](https://github.com/substack/node-browserify)).
`htmlparser2` was rewritten multiple times and, while it maintains an API that's compatible with `htmlparser` in most cases, the projects don't share any code anymore.

The parser now provides a callback interface inspired by [sax.js](https://github.com/isaacs/sax-js) (originally targeted at [readabilitySAX](https://github.com/fb55/readabilitysax)).
As a result, old handlers won't work anymore.

The `DefaultHandler` and the `RssHandler` were renamed to clarify their purpose (to `DomHandler` and `FeedHandler`). The old names are still available when requiring `htmlparser2`, your code should work as expected.

## Security contact information

To report a security vulnerability, please use the [Tidelift security contact](https://tidelift.com/security).
Tidelift will coordinate the fix and disclosure.

## `htmlparser2` for enterprise

Available as part of the Tidelift Subscription

The maintainers of `htmlparser2` and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-htmlparser2?utm_source=npm-htmlparser2&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)


---

# repeat-string [![NPM version](https://img.shields.io/npm/v/repeat-string.svg?style=flat)](https://www.npmjs.com/package/repeat-string) [![NPM monthly downloads](https://img.shields.io/npm/dm/repeat-string.svg?style=flat)](https://npmjs.org/package/repeat-string)  [![NPM total downloads](https://img.shields.io/npm/dt/repeat-string.svg?style=flat)](https://npmjs.org/package/repeat-string) [![Linux Build Status](https://img.shields.io/travis/jonschlinkert/repeat-string.svg?style=flat&label=Travis)](https://travis-ci.org/jonschlinkert/repeat-string)

> Repeat the given string n times. Fastest implementation for repeating a string.

## Install

Install with [npm](https://www.npmjs.com/):

```sh
$ npm install --save repeat-string
```

## Usage

### [repeat](index.js#L41)

Repeat the given `string` the specified `number` of times.

**Example:**

**Example**

```js
var repeat = require('repeat-string');
repeat('A', 5);
//=> AAAAA
```

**Params**

* `string` **{String}**: The string to repeat
* `number` **{Number}**: The number of times to repeat the string
* `returns` **{String}**: Repeated string

## Benchmarks

Repeat string is significantly faster than the native method (which is itself faster than [repeating](https://github.com/sindresorhus/repeating)):

```sh
# 2x
repeat-string  █████████████████████████  (26,953,977 ops/sec)
repeating      █████████                  (9,855,695 ops/sec)
native         ██████████████████         (19,453,895 ops/sec)

# 3x
repeat-string  █████████████████████████  (19,445,252 ops/sec)
repeating      ███████████                (8,661,565 ops/sec)
native         ████████████████████       (16,020,598 ops/sec)

# 10x
repeat-string  █████████████████████████  (23,792,521 ops/sec)
repeating      █████████                  (8,571,332 ops/sec)
native         ███████████████            (14,582,955 ops/sec)

# 50x
repeat-string  █████████████████████████  (23,640,179 ops/sec)
repeating      █████                      (5,505,509 ops/sec)
native         ██████████                 (10,085,557 ops/sec)

# 250x
repeat-string  █████████████████████████  (23,489,618 ops/sec)
repeating      ████                       (3,962,937 ops/sec)
native         ████████                   (7,724,892 ops/sec)

# 2000x
repeat-string  █████████████████████████  (20,315,172 ops/sec)
repeating      ████                       (3,297,079 ops/sec)
native         ███████                    (6,203,331 ops/sec)

# 20000x
repeat-string  █████████████████████████  (23,382,915 ops/sec)
repeating      ███                        (2,980,058 ops/sec)
native         █████                      (5,578,808 ops/sec)
```

**Run the benchmarks**

Install dev dependencies:

```sh
npm i -d && node benchmark
```

## About

### Related projects

[repeat-element](https://www.npmjs.com/package/repeat-element): Create an array by repeating the given value n times. | [homepage](https://github.com/jonschlinkert/repeat-element "Create an array by repeating the given value n times.")

### Contributing

Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).

### Contributors

| **Commits** | **Contributor**<br/> | 
| --- | --- |
| 51 | [jonschlinkert](https://github.com/jonschlinkert) |
| 2 | [LinusU](https://github.com/LinusU) |
| 2 | [tbusser](https://github.com/tbusser) |
| 1 | [doowb](https://github.com/doowb) |
| 1 | [wooorm](https://github.com/wooorm) |

### Building docs

_(This document was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme) (a [verb](https://github.com/verbose/verb) generator), please don't edit the readme directly. Any changes to the readme must be made in [.verb.md](.verb.md).)_

To generate the readme and API documentation with [verb](https://github.com/verbose/verb):

```sh
$ npm install -g verb verb-generate-readme && verb
```

### Running tests

Install dev dependencies:

```sh
$ npm install -d && npm test
```

### Author

**Jon Schlinkert**

* [github/jonschlinkert](https://github.com/jonschlinkert)
* [twitter/jonschlinkert](http://twitter.com/jonschlinkert)

### License

Copyright © 2016, [Jon Schlinkert](http://github.com/jonschlinkert).
Released under the [MIT license](https://github.com/jonschlinkert/repeat-string/blob/master/LICENSE).

***

_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.2.0, on October 23, 2016._

---

# require-from-string [![Build Status](https://travis-ci.org/floatdrop/require-from-string.svg?branch=master)](https://travis-ci.org/floatdrop/require-from-string)

Load module from string in Node.

## Install

```
$ npm install --save require-from-string
```


## Usage

```js
var requireFromString = require('require-from-string');

requireFromString('module.exports = 1');
//=> 1
```


## API

### requireFromString(code, [filename], [options])

#### code

*Required*  
Type: `string`

Module code.

#### filename
Type: `string`  
Default: `''`

Optional filename.


#### options
Type: `object`

##### appendPaths
Type: `Array`

List of `paths`, that will be appended to module `paths`. Useful, when you want
to be able require modules from these paths.

##### prependPaths
Type: `Array`

Same as `appendPaths`, but paths will be prepended.

## License

MIT © [Vsevolod Strukchinsky](http://github.com/floatdrop)


---

# require-like

[![Build Status](https://secure.travis-ci.org/felixge/node-require-like.png)](http://travis-ci.org/felixge/node-require-like)

Generates require functions that act as if they were operating in a given path.

## Install

``` bash
npm install require-like
```

## Usage

A require function that acts as if it was executed in `'./lib/bar'`:

``` javascript
var requireLike = require('require-like');
var myRequire = requireLike(__dirname + '/lib/bar.js');

var myFoo = myRequire('./foo.js');
var foo = require('./lib/foo');

require('assert').strictEqual(myFoo, foo);
```

## API

### requireLike(path, [uncached])

Returns a require function that acts as if it was operating in the given
`path`.

Setting the `uncached` parameter to true returns a function that by-passes the
module cache.

## Implementation Details

This module works by accessing some private node APIs. You shouldn't worry about
that so, since I will make sure this module does not break in the future by
either patching it, or making a patch for node that makes the needed APIs
public.

## What to do with this

I use this library for dependency injection in unit tests. However, you could
also use it to create experimental require addons yourself.

## License

require-like is licensed under the MIT license.


---

# requires-port

[![Made by unshift](https://img.shields.io/badge/made%20by-unshift-00ffcc.svg?style=flat-square)](http://unshift.io)[![Version npm](http://img.shields.io/npm/v/requires-port.svg?style=flat-square)](http://browsenpm.org/package/requires-port)[![Build Status](http://img.shields.io/travis/unshiftio/requires-port/master.svg?style=flat-square)](https://travis-ci.org/unshiftio/requires-port)[![Dependencies](https://img.shields.io/david/unshiftio/requires-port.svg?style=flat-square)](https://david-dm.org/unshiftio/requires-port)[![Coverage Status](http://img.shields.io/coveralls/unshiftio/requires-port/master.svg?style=flat-square)](https://coveralls.io/r/unshiftio/requires-port?branch=master)[![IRC channel](http://img.shields.io/badge/IRC-irc.freenode.net%23unshift-00a8ff.svg?style=flat-square)](http://webchat.freenode.net/?channels=unshift)

The module name says it all, check if a protocol requires a given port.

## Installation

This module is intended to be used with browserify or Node.js and is distributed
in the public npm registry. To install it simply run the following command from
your CLI:

```j
npm install --save requires-port
```

## Usage

The module exports it self as function and requires 2 arguments:

1. The port number, can be a string or number.
2. Protocol, can be `http`, `http:` or even `https://yomoma.com`. We just split
   it at `:` and use the first result. We currently accept the following
   protocols:
   - `http`
   - `https`
   - `ws`
   - `wss`
   - `ftp`
   - `gopher`
   - `file`

It returns a boolean that indicates if protocol requires this port to be added
to your URL.

```js
'use strict';

var required = require('requires-port');

console.log(required('8080', 'http')) // true
console.log(required('80', 'http'))   // false
```

# License

MIT


---

# Security

Please email [@ljharb](https://github.com/ljharb) or see https://tidelift.com/security if you have a potential security vulnerability to report.


---

# `resolve-alpn`

[![Node CI](https://github.com/szmarczak/resolve-alpn/workflows/Node%20CI/badge.svg)](https://github.com/szmarczak/resolve-alpn/actions)
[![codecov](https://codecov.io/gh/szmarczak/resolve-alpn/branch/master/graph/badge.svg)](https://codecov.io/gh/szmarczak/resolve-alpn)

## API

### resolveALPN(options, connect = tls.connect)

Returns an object with an `alpnProtocol` property. The `socket` property may be also present.

```js
const result = await resolveALPN({
	host: 'nghttp2.org',
	port: 443,
	ALPNProtocols: ['h2', 'http/1.1'],
	servername: 'nghttp2.org'
});

console.log(result); // {alpnProtocol: 'h2'}
```

**Note:** While the `servername` option is not required in this case, many other servers do. It's best practice to set it anyway.

**Note:** If the socket times out, the promise will resolve and `result.timeout` will be set to `true`.

#### options

Same as [TLS options](https://nodejs.org/api/tls.html#tls_tls_connect_options_callback).

##### options.resolveSocket

By default, the socket gets destroyed and the promise resolves.<br>
If you set this to true, it will return the socket in a `socket` property.

```js
const result = await resolveALPN({
	host: 'nghttp2.org',
	port: 443,
	ALPNProtocols: ['h2', 'http/1.1'],
	servername: 'nghttp2.org',
	resolveSocket: true
});

console.log(result); // {alpnProtocol: 'h2', socket: tls.TLSSocket}

// Remember to destroy the socket if you don't use it!
result.socket.destroy();
```

#### connect

Type: `Function<TLSSocket> | AsyncFunction<TLSSocket>`\
Default: [`tls.connect`](https://nodejs.org/dist/latest-v16.x/docs/api/tls.html#tls_tls_connect_options_callback)

**Note:** No matter which function is used (synchronous or asynchronous), it **must** accept a `callback` function as a second argument. The `callback` function gets executed when the socket has successfully connected.

## License

MIT


---

# resolve-from [![Build Status](https://travis-ci.org/sindresorhus/resolve-from.svg?branch=master)](https://travis-ci.org/sindresorhus/resolve-from)

> Resolve the path of a module like [`require.resolve()`](https://nodejs.org/api/globals.html#globals_require_resolve) but from a given path


## Install

```
$ npm install resolve-from
```


## Usage

```js
const resolveFrom = require('resolve-from');

// There is a file at `./foo/bar.js`

resolveFrom('foo', './bar');
//=> '/Users/sindresorhus/dev/test/foo/bar.js'
```


## API

### resolveFrom(fromDir, moduleId)

Like `require()`, throws when the module can't be found.

### resolveFrom.silent(fromDir, moduleId)

Returns `null` instead of throwing when the module can't be found.

#### fromDir

Type: `string`

Directory to resolve from.

#### moduleId

Type: `string`

What you would use in `require()`.


## Tip

Create a partial using a bound function if you want to resolve from the same `fromDir` multiple times:

```js
const resolveFromFoo = resolveFrom.bind(null, 'foo');

resolveFromFoo('./bar');
resolveFromFoo('./baz');
```


## Related

- [resolve-cwd](https://github.com/sindresorhus/resolve-cwd) - Resolve the path of a module from the current working directory
- [import-from](https://github.com/sindresorhus/import-from) - Import a module from a given path
- [import-cwd](https://github.com/sindresorhus/import-cwd) - Import a module from the current working directory
- [resolve-pkg](https://github.com/sindresorhus/resolve-pkg) - Resolve the path of a package regardless of it having an entry point
- [import-lazy](https://github.com/sindresorhus/import-lazy) - Import a module lazily
- [resolve-global](https://github.com/sindresorhus/resolve-global) - Resolve the path of a globally installed module


## License

MIT © [Sindre Sorhus](https://sindresorhus.com)


---

# resolve-pathname [![Travis][build-badge]][build] [![npm package][npm-badge]][npm]

[build-badge]: https://img.shields.io/travis/mjackson/resolve-pathname/master.svg?style=flat-square
[build]: https://travis-ci.org/mjackson/resolve-pathname
[npm-badge]: https://img.shields.io/npm/v/resolve-pathname.svg?style=flat-square
[npm]: https://www.npmjs.org/package/resolve-pathname

[resolve-pathname](https://www.npmjs.com/package/resolve-pathname) resolves URL pathnames identical to the way browsers resolve the pathname of an `<a href>` value. The goals are:

- 100% compatibility with browser pathname resolution
- Pure JavaScript implementation (no DOM dependency)

## Installation

Using [npm](https://www.npmjs.com/):

    $ npm install --save resolve-pathname

Then, use as you would anything else:

```js
// using ES6 modules
import resolvePathname from 'resolve-pathname';

// using CommonJS modules
var resolvePathname = require('resolve-pathname');
```

The UMD build is also available on [unpkg](https://unpkg.com):

```html
<script src="https://unpkg.com/resolve-pathname"></script>
```

You can find the library on `window.resolvePathname`.

## Usage

```js
import resolvePathname from 'resolve-pathname';

// Simply pass the pathname you'd like to resolve. Second
// argument is the path we're coming from, or the current
// pathname. It defaults to "/".
resolvePathname('about', '/company/jobs'); // /company/about
resolvePathname('../jobs', '/company/team/ceo'); // /company/jobs
resolvePathname('about'); // /about
resolvePathname('/about'); // /about

// Index paths (with a trailing slash) are also supported and
// work the same way as browsers.
resolvePathname('about', '/company/info/'); // /company/info/about

// In browsers, it's easy to resolve a URL pathname relative to
// the current page. Just use window.location! e.g. if
// window.location.pathname == '/company/team/ceo' then
resolvePathname('cto', window.location.pathname); // /company/team/cto
resolvePathname('../jobs', window.location.pathname); // /company/jobs
```

## Prior Work

- [url.resolve](https://nodejs.org/api/url.html#url_url_resolve_from_to) - node's `url.resolve` implementation for full URLs
- [resolve-url](https://www.npmjs.com/package/resolve-url) - A DOM-dependent implementation of the same algorithm


---

# responselike

> A response-like object for mocking a Node.js HTTP response stream

Returns a streamable response object similar to a [Node.js HTTP response stream](https://nodejs.org/api/http.html#http_class_http_incomingmessage). Useful for formatting cached responses so they can be consumed by code expecting a real response.

## Install

```sh
npm install responselike
```

## Usage

```js
import Response from 'responselike';

const response = new Response({
	statusCode: 200,
	headers: {
		foo: 'bar'
	},
	body: Buffer.from('Hi!'),
	url: 'https://example.com'
});

response.statusCode;
// 200

response.headers;
// {foo: 'bar'}

response.body;
// <Buffer 48 69 21>

response.url;
// 'https://example.com'

response.pipe(process.stdout);
// 'Hi!'
```

## API

### new Response(options?)

Returns a streamable response object similar to a [Node.js HTTP response stream](https://nodejs.org/api/http.html#http_class_http_incomingmessage).

#### options

Type: `object`

##### statusCode

Type: `number`

The HTTP response status code.

##### headers

Type: `object`

The HTTP headers. Keys will be automatically lowercased.

##### body

Type: `Buffer`

The response body. The Buffer contents will be streamable but is also exposed directly as `response.body`.

##### url

Type: `string`

The request URL string.


---

<!-- badges/ -->
[![Build Status](https://secure.travis-ci.org/tim-kos/node-retry.svg?branch=master)](http://travis-ci.org/tim-kos/node-retry "Check this project's build status on TravisCI")
[![codecov](https://codecov.io/gh/tim-kos/node-retry/branch/master/graph/badge.svg)](https://codecov.io/gh/tim-kos/node-retry)
<!-- /badges -->

# retry

Abstraction for exponential and custom retry strategies for failed operations.

## Installation

    npm install retry

## Current Status

This module has been tested and is ready to be used.

## Tutorial

The example below will retry a potentially failing `dns.resolve` operation
`10` times using an exponential backoff strategy. With the default settings, this
means the last attempt is made after `17 minutes and 3 seconds`.

``` javascript
var dns = require('dns');
var retry = require('retry');

function faultTolerantResolve(address, cb) {
  var operation = retry.operation();

  operation.attempt(function(currentAttempt) {
    dns.resolve(address, function(err, addresses) {
      if (operation.retry(err)) {
        return;
      }

      cb(err ? operation.mainError() : null, addresses);
    });
  });
}

faultTolerantResolve('nodejs.org', function(err, addresses) {
  console.log(err, addresses);
});
```

Of course you can also configure the factors that go into the exponential
backoff. See the API documentation below for all available settings.
currentAttempt is an int representing the number of attempts so far.

``` javascript
var operation = retry.operation({
  retries: 5,
  factor: 3,
  minTimeout: 1 * 1000,
  maxTimeout: 60 * 1000,
  randomize: true,
});
```

## API

### retry.operation([options])

Creates a new `RetryOperation` object. `options` is the same as `retry.timeouts()`'s `options`, with three additions:

* `forever`: Whether to retry forever, defaults to `false`.
* `unref`: Whether to [unref](https://nodejs.org/api/timers.html#timers_unref) the setTimeout's, defaults to `false`.
* `maxRetryTime`: The maximum time (in milliseconds) that the retried operation is allowed to run. Default is `Infinity`.  

### retry.timeouts([options])

Returns an array of timeouts. All time `options` and return values are in
milliseconds. If `options` is an array, a copy of that array is returned.

`options` is a JS object that can contain any of the following keys:

* `retries`: The maximum amount of times to retry the operation. Default is `10`. Seting this to `1` means `do it once, then retry it once`.
* `factor`: The exponential factor to use. Default is `2`.
* `minTimeout`: The number of milliseconds before starting the first retry. Default is `1000`.
* `maxTimeout`: The maximum number of milliseconds between two retries. Default is `Infinity`.
* `randomize`: Randomizes the timeouts by multiplying with a factor between `1` to `2`. Default is `false`.

The formula used to calculate the individual timeouts is:

```
Math.min(random * minTimeout * Math.pow(factor, attempt), maxTimeout)
```

Have a look at [this article][article] for a better explanation of approach.

If you want to tune your `factor` / `times` settings to attempt the last retry
after a certain amount of time, you can use wolfram alpha. For example in order
to tune for `10` attempts in `5 minutes`, you can use this equation:

![screenshot](https://github.com/tim-kos/node-retry/raw/master/equation.gif)

Explaining the various values from left to right:

* `k = 0 ... 9`:  The `retries` value (10)
* `1000`: The `minTimeout` value in ms (1000)
* `x^k`: No need to change this, `x` will be your resulting factor
* `5 * 60 * 1000`: The desired total amount of time for retrying in ms (5 minutes)

To make this a little easier for you, use wolfram alpha to do the calculations:

<http://www.wolframalpha.com/input/?i=Sum%5B1000*x^k%2C+{k%2C+0%2C+9}%5D+%3D+5+*+60+*+1000>

[article]: http://dthain.blogspot.com/2009/02/exponential-backoff-in-distributed.html

### retry.createTimeout(attempt, opts)

Returns a new `timeout` (integer in milliseconds) based on the given parameters.

`attempt` is an integer representing for which retry the timeout should be calculated. If your retry operation was executed 4 times you had one attempt and 3 retries. If you then want to calculate a new timeout, you should set `attempt` to 4 (attempts are zero-indexed).

`opts` can include `factor`, `minTimeout`, `randomize` (boolean) and `maxTimeout`. They are documented above.

`retry.createTimeout()` is used internally by `retry.timeouts()` and is public for you to be able to create your own timeouts for reinserting an item, see [issue #13](https://github.com/tim-kos/node-retry/issues/13).

### retry.wrap(obj, [options], [methodNames])

Wrap all functions of the `obj` with retry. Optionally you can pass operation options and
an array of method names which need to be wrapped.

```
retry.wrap(obj)

retry.wrap(obj, ['method1', 'method2'])

retry.wrap(obj, {retries: 3})

retry.wrap(obj, {retries: 3}, ['method1', 'method2'])
```
The `options` object can take any options that the usual call to `retry.operation` can take.

### new RetryOperation(timeouts, [options])

Creates a new `RetryOperation` where `timeouts` is an array where each value is
a timeout given in milliseconds.

Available options:
* `forever`: Whether to retry forever, defaults to `false`.
* `unref`: Wether to [unref](https://nodejs.org/api/timers.html#timers_unref) the setTimeout's, defaults to `false`.

If `forever` is true, the following changes happen:
* `RetryOperation.errors()` will only output an array of one item: the last error.
* `RetryOperation` will repeatedly use the `timeouts` array. Once all of its timeouts have been used up, it restarts with the first timeout, then uses the second and so on.

#### retryOperation.errors()

Returns an array of all errors that have been passed to `retryOperation.retry()` so far. The
returning array has the errors ordered chronologically based on when they were passed to
`retryOperation.retry()`, which means the first passed error is at index zero and the last is
at the last index.

#### retryOperation.mainError()

A reference to the error object that occured most frequently. Errors are
compared using the `error.message` property.

If multiple error messages occured the same amount of time, the last error
object with that message is returned.

If no errors occured so far, the value is `null`.

#### retryOperation.attempt(fn, timeoutOps)

Defines the function `fn` that is to be retried and executes it for the first
time right away. The `fn` function can receive an optional `currentAttempt` callback that represents the number of attempts to execute `fn` so far.

Optionally defines `timeoutOps` which is an object having a property `timeout` in miliseconds and a property `cb` callback function.
Whenever your retry operation takes longer than `timeout` to execute, the timeout callback function `cb` is called.


#### retryOperation.try(fn)

This is an alias for `retryOperation.attempt(fn)`. This is deprecated. Please use `retryOperation.attempt(fn)` instead.

#### retryOperation.start(fn)

This is an alias for `retryOperation.attempt(fn)`. This is deprecated. Please use `retryOperation.attempt(fn)` instead.

#### retryOperation.retry(error)

Returns `false` when no `error` value is given, or the maximum amount of retries
has been reached.

Otherwise it returns `true`, and retries the operation after the timeout for
the current attempt number.

#### retryOperation.stop()

Allows you to stop the operation being retried. Useful for aborting the operation on a fatal error etc.

#### retryOperation.reset()

Resets the internal state of the operation object, so that you can call `attempt()` again as if this was a new operation object.

#### retryOperation.attempts()

Returns an int representing the number of attempts it took to call `fn` before it was successful.

## License

retry is licensed under the MIT license.


# Changelog

0.10.0 Adding `stop` functionality, thanks to @maxnachlinger.

0.9.0 Adding `unref` functionality, thanks to @satazor.

0.8.0 Implementing retry.wrap.

0.7.0 Some bug fixes and made retry.createTimeout() public. Fixed issues [#10](https://github.com/tim-kos/node-retry/issues/10), [#12](https://github.com/tim-kos/node-retry/issues/12), and [#13](https://github.com/tim-kos/node-retry/issues/13).

0.6.0 Introduced optional timeOps parameter for the attempt() function which is an object having a property timeout in milliseconds and a property cb callback function. Whenever your retry operation takes longer than timeout to execute, the timeout callback function cb is called.

0.5.0 Some minor refactoring.

0.4.0 Changed retryOperation.try() to retryOperation.attempt(). Deprecated the aliases start() and try() for it.

0.3.0 Added retryOperation.start() which is an alias for retryOperation.try().

0.2.0 Added attempts() function and parameter to retryOperation.try() representing the number of attempts it took to call fn().


---

# reusify

[![npm version][npm-badge]][npm-url]

Reuse your objects and functions for maximum speed. This technique will
make any function run ~10% faster. You call your functions a
lot, and it adds up quickly in hot code paths.

```
$ node benchmarks/createNoCodeFunction.js
Total time 53133
Total iterations 100000000
Iteration/s 1882069.5236482036

$ node benchmarks/reuseNoCodeFunction.js
Total time 50617
Total iterations 100000000
Iteration/s 1975620.838848608
```

The above benchmark uses fibonacci to simulate a real high-cpu load.
The actual numbers might differ for your use case, but the difference
should not.

The benchmark was taken using Node v6.10.0.

This library was extracted from
[fastparallel](http://npm.im/fastparallel).

## Example

```js
var reusify = require('reusify')
var fib = require('reusify/benchmarks/fib')
var instance = reusify(MyObject)

// get an object from the cache,
// or creates a new one when cache is empty
var obj = instance.get()

// set the state
obj.num = 100
obj.func()

// reset the state.
// if the state contains any external object
// do not use delete operator (it is slow)
// prefer set them to null
obj.num = 0

// store an object in the cache
instance.release(obj)

function MyObject () {
  // you need to define this property
  // so V8 can compile MyObject into an
  // hidden class
  this.next = null
  this.num = 0

  var that = this

  // this function is never reallocated,
  // so it can be optimized by V8
  this.func = function () {
    if (null) {
      // do nothing
    } else {
      // calculates fibonacci
      fib(that.num)
    }
  }
}
```

The above example was intended for synchronous code, let's see async:
```js
var reusify = require('reusify')
var instance = reusify(MyObject)

for (var i = 0; i < 100; i++) {
  getData(i, console.log)
}

function getData (value, cb) {
  var obj = instance.get()

  obj.value = value
  obj.cb = cb
  obj.run()
}

function MyObject () {
  this.next = null
  this.value = null

  var that = this

  this.run = function () {
    asyncOperation(that.value, that.handle)
  }

  this.handle = function (err, result) {
    that.cb(err, result)
    that.value = null
    that.cb = null
    instance.release(that)
  }
}
```

Also note how in the above examples, the code, that consumes an instance of `MyObject`,
reset the state to initial condition, just before storing it in the cache.
That's needed so that every subsequent request for an instance from the cache,
could get a clean instance.

## Why

It is faster because V8 doesn't have to collect all the functions you
create. On a short-lived benchmark, it is as fast as creating the
nested function, but on a longer time frame it creates less
pressure on the garbage collector.

## Other examples
If you want to see some complex example, checkout [middie](https://github.com/fastify/middie) and [steed](https://github.com/mcollina/steed).

## Acknowledgements

Thanks to [Trevor Norris](https://github.com/trevnorris) for
getting me down the rabbit hole of performance, and thanks to [Mathias
Buss](http://github.com/mafintosh) for suggesting me to share this
trick.

## License

MIT

[npm-badge]: https://badge.fury.io/js/reusify.svg
[npm-url]: https://badge.fury.io/js/reusify


---

# Security Policy

## Supported Versions

Use this section to tell people about which versions of your project are
currently being supported with security updates.

| Version | Supported          |
| ------- | ------------------ |
| 1.x     | :white_check_mark: |
| < 1.0   | :x:                |

## Reporting a Vulnerability

Please report all vulnerabilities at [https://github.com/mcollina/fastq/security](https://github.com/mcollina/fastq/security).


---

# v3.0

- Add `--preserve-root` option to executable (default true)
- Drop support for Node.js below version 6

# v2.7

- Make `glob` an optional dependency

# 2.6

- Retry on EBUSY on non-windows platforms as well
- Make `rimraf.sync` 10000% more reliable on Windows

# 2.5

- Handle Windows EPERM when lstat-ing read-only dirs
- Add glob option to pass options to glob

# 2.4

- Add EPERM to delay/retry loop
- Add `disableGlob` option

# 2.3

- Make maxBusyTries and emfileWait configurable
- Handle weird SunOS unlink-dir issue
- Glob the CLI arg for better Windows support

# 2.2

- Handle ENOENT properly on Windows
- Allow overriding fs methods
- Treat EPERM as indicative of non-empty dir
- Remove optional graceful-fs dep
- Consistently return null error instead of undefined on success
- win32: Treat ENOTEMPTY the same as EBUSY
- Add `rimraf` binary

# 2.1

- Fix SunOS error code for a non-empty directory
- Try rmdir before readdir
- Treat EISDIR like EPERM
- Remove chmod
- Remove lstat polyfill, node 0.7 is not supported

# 2.0

- Fix myGid call to check process.getgid
- Simplify the EBUSY backoff logic.
- Use fs.lstat in node >= 0.7.9
- Remove gently option
- remove fiber implementation
- Delete files that are marked read-only

# 1.0

- Allow ENOENT in sync method
- Throw when no callback is provided
- Make opts.gently an absolute path
- use 'stat' if 'lstat' is not available
- Consistent error naming, and rethrow non-ENOENT stat errors
- add fiber implementation


---

[![Build Status](https://travis-ci.org/isaacs/rimraf.svg?branch=master)](https://travis-ci.org/isaacs/rimraf) [![Dependency Status](https://david-dm.org/isaacs/rimraf.svg)](https://david-dm.org/isaacs/rimraf) [![devDependency Status](https://david-dm.org/isaacs/rimraf/dev-status.svg)](https://david-dm.org/isaacs/rimraf#info=devDependencies)

The [UNIX command](http://en.wikipedia.org/wiki/Rm_(Unix)) `rm -rf` for node.

Install with `npm install rimraf`, or just drop rimraf.js somewhere.

## API

`rimraf(f, [opts], callback)`

The first parameter will be interpreted as a globbing pattern for files. If you
want to disable globbing you can do so with `opts.disableGlob` (defaults to
`false`). This might be handy, for instance, if you have filenames that contain
globbing wildcard characters.

The callback will be called with an error if there is one.  Certain
errors are handled for you:

* Windows: `EBUSY` and `ENOTEMPTY` - rimraf will back off a maximum of
  `opts.maxBusyTries` times before giving up, adding 100ms of wait
  between each attempt.  The default `maxBusyTries` is 3.
* `ENOENT` - If the file doesn't exist, rimraf will return
  successfully, since your desired outcome is already the case.
* `EMFILE` - Since `readdir` requires opening a file descriptor, it's
  possible to hit `EMFILE` if too many file descriptors are in use.
  In the sync case, there's nothing to be done for this.  But in the
  async case, rimraf will gradually back off with timeouts up to
  `opts.emfileWait` ms, which defaults to 1000.

## options

* unlink, chmod, stat, lstat, rmdir, readdir,
  unlinkSync, chmodSync, statSync, lstatSync, rmdirSync, readdirSync

    In order to use a custom file system library, you can override
    specific fs functions on the options object.

    If any of these functions are present on the options object, then
    the supplied function will be used instead of the default fs
    method.

    Sync methods are only relevant for `rimraf.sync()`, of course.

    For example:

    ```javascript
    var myCustomFS = require('some-custom-fs')

    rimraf('some-thing', myCustomFS, callback)
    ```

* maxBusyTries

    If an `EBUSY`, `ENOTEMPTY`, or `EPERM` error code is encountered
    on Windows systems, then rimraf will retry with a linear backoff
    wait of 100ms longer on each try.  The default maxBusyTries is 3.

    Only relevant for async usage.

* emfileWait

    If an `EMFILE` error is encountered, then rimraf will retry
    repeatedly with a linear backoff of 1ms longer on each try, until
    the timeout counter hits this max.  The default limit is 1000.

    If you repeatedly encounter `EMFILE` errors, then consider using
    [graceful-fs](http://npm.im/graceful-fs) in your program.

    Only relevant for async usage.

* glob

    Set to `false` to disable [glob](http://npm.im/glob) pattern
    matching.

    Set to an object to pass options to the glob module.  The default
    glob options are `{ nosort: true, silent: true }`.

    Glob version 6 is used in this module.

    Relevant for both sync and async usage.

* disableGlob

    Set to any non-falsey value to disable globbing entirely.
    (Equivalent to setting `glob: false`.)

## rimraf.sync

It can remove stuff synchronously, too.  But that's not so good.  Use
the async API.  It's better.

## CLI

If installed with `npm install rimraf -g` it can be used as a global
command `rimraf <path> [<path> ...]` which is useful for cross platform support.

## mkdirp

If you need to create a directory recursively, check out
[mkdirp](https://github.com/substack/node-mkdirp).


---

# RTLCSS Changelog

## 4.3.0 - 27 Aug. 2024

- Return an error code when the parsed CSS `stdin` is invalid. **Thanks @lade-odoo**


## 4.2.0 - 24 Jul. 2024

- Add support for eight-value hex colors.

## 4.1.1 - 18 Sep. 2023

- Update mirroring `transform` to safeguard functions inside values.
- Internal code refactoring. **Thanks @XhmikosR**

## 4.1.0 - 11 Apr. 2023

- Update dependencies. **Thanks @XhmikosR**
- Update mirroring `transform-origin` to not flip `y-offset` when `x-offset` is `center`. **Thanks @skmanohar**
- Return an error code when the parssed CSS file is invalid. **Thanks @HANNICHE-Walid**

## 4.0.0 - 09 Aug. 2022

- Update dependencies, Internal code refactoring, cleanup and optimizations. **Thanks @XhmikosR**
- Support flipping `justify-content`, `justify-items` and `justify-self`. **Thanks @mbehzad**
- Support flipping length position without using `calc`.

## 3.5.0 - 02 Nov. 2021

- Update dependencies. **Thanks @XhmikosR**
- Internal code cleanup/formatting. **Thanks @XhmikosR**

## 3.4.0 - 18 Oct. 2021

- Support flipping `object-position`.
- Update devDependencies.

## 3.3.0 - 08 Jul. 2021

- Add `processEnv` option to support flipping agent-defined environment variables (`safe-area-inset-left`, `safe-area-inset-right`).

## 3.2.1 - 22 Jun. 2021

- Bump [glob-parent](https://github.com/gulpjs/glob-parent) from 5.1.1 to 5.1.2.

## 3.2.0 - 23 May. 2021

- Add `aliases` option to support processing Custom Properties (CSS Variables). **Thanks @elchininet**

## 3.1.2 - 04 Feb. 2021

- Update `README.md`.

## 3.1.1 - 02 Feb. 2021

- Fixes `TypeError` when placing value directive before `!important`. [#218](https://github.com/MohammadYounes/rtlcss/issues/218)

## 3.1.0 - 30 Jan. 2021

- Use `strict` mode across all files. **Thanks @XhmikosR**
- Decrease package size by around 6%. **Thanks @XhmikosR**
- Add guards against prototype pollution. **Thanks @XhmikosR**
- Allow value directives to be placed any where inside the declaration value.
- Handle value directives placed after `!important`.
- Fix reading config file sources ([#209](https://github.com/MohammadYounes/rtlcss/issues/209)).

## 3.0.0 - 10 Dec. 2020

- Upgrade to [postcss] 8.
- Dropped **Node.js 6.x, 8.x, 11.x, and 13.x** versions.

## 2.6.2 - 01 Dec. 2020

- Set input source to same file in raw directive ([#180](https://github.com/MohammadYounes/rtlcss/issues/180)).

## 2.6.1 - 15 Oct. 2020

- Remove colors dependency from findup ([#177](https://github.com/MohammadYounes/rtlcss/pull/177)).

## 2.6.0 - 15 Aug. 2020

- Support flipping `perspective-origin` ([#167](https://github.com/MohammadYounes/rtlcss/pull/167)).
- CLI: Fix empty output when `--silent` and `--stdin` flags are used together (Fixes [#169](https://github.com/MohammadYounes/rtlcss/issues/169)).
- Enable flipping `rotateY`.
- Fix flipping `rotate3d`.

## 2.5.0 - 08 Feb. 2020

- `useCalc` to flip unit based `transform-origin`.
- CLI: use `console.log` instead of the [deprecated](https://nodejs.org/docs/latest-v10.x/api/util.html#util_util_print_strings) `util.print`(issue #156).

## 2.4.1 - 28 Nov. 2019

- Ignore white spaces before directives prefix.

## 2.4.0 - 20 Jun. 2018

- New Option:
  - `useCalc` (default: `false`) to flip unit based `background-position` using `calc`. **Thanks @zoreet**

## 2.3.0 - 9 Jun. 2018

- Skip processing CSS variables. **Thanks @danfooo**

## 2.2.1 - 9 Nov. 2017

- Fixes a bug in flipping `background-position` having keywords only (Fixes [#107](https://github.com/MohammadYounes/rtlcss/issues/107)).

## 2.2.0 - 7 Jun. 2017

- Support for pre/post hooks.
- Upgrade to [postcss] v6.x

## 2.1.2 - 31 Dec. 2016

- Internal code update.

## 2.1.1 - 28 Dec. 2016

- Fixes a bug in self-closing ignore directive (Fixes [#88](https://github.com/MohammadYounes/rtlcss/issues/88)).

## 2.1.0 - 30 Nov. 2016

- Support CSS `background-position` edge offsets.

## 2.0.7 - 16 Nov. 2016

- Fixes a bug in flipping backgrounds having URL placed first (Fixes [#84](https://github.com/MohammadYounes/rtlcss/issues/84)).
- Update `node.value` so changes will be picked up by other processors (Closes [#85](https://github.com/MohammadYounes/rtlcss/issues/85)).

## 2.0.6 - 12 Jul. 2016

- README updates.

## 2.0.5 - 17 May. 2016

- Fixes a bug in complementing `calc` values (Fixes [#71](https://github.com/MohammadYounes/rtlcss/issues/71)).

## 2.0.4 - 25 Apr. 2016

- Fixes a bug in flipping cursor value (Fixes [#68](https://github.com/MohammadYounes/rtlcss/issues/68)).

## 2.0.3 - 23 Mar. 2016

- Guard against flipping tokens, e.g: [shadows starting with a color function](https://github.com/MohammadYounes/rtlcss/blob/master/test/data/special.js#L2-L7).

## 2.0.2 - 05 Mar. 2016

- Fixes a bug in flipping background with a hex color value (Fixes [#60](https://github.com/MohammadYounes/rtlcss/issues/60)).

## 2.0.1 - 23 Feb. 2016

- Fixes a bug when having `decl` nodes inside `atrule`s and `autoRename` enabled.
- Fixes a bug in flipping multi-valued transforms.

## 2.0.0 - 18 Feb. 2016

- Support for control directive blocks, e.g. `/*rtl:begin:ignore*/ ... /*rtl:end:ignore*/`.
- Support for strict auto renaming, which ensures `autoRename` is applied only when a pair exists.
- New directives:
  - `config`
  - `options`
  - `raw`
  - `remove`
- Support for [Plugins](docs/writing-a-plugin.md).

### Upgrading from version 1.0

Options and config settings have changed. However, you need not to worry about your CSS files as all directives are backward-compatible. This is a summary of what's changed:

- New Options:

  - `autoRenameStrict` (default: `false`) to apply auto rename only when a pair exists.
  - `blacklist` to prevent execution of certain directives.
  - `clean` (default: `true`), to remove directives from output CSS.
  - `processUrls` (default: `false`) to control URL updates. You can also target specific node types using an object literal. e.g. `{'atrule': true, 'decl': false}`.

- Updated Options:

  - `autoRename` new default is `false`.
  - `stringMap`:
    - added `priority` attribute to control maps execution order.
    - added `exclusive` attribute, which determines if a map execution should stop iterating over other maps.
    - dropped `'west-east'` map from the default map collection.

- Removed Options:

  - `enableLogging`, still warnings and errors are reported directly to postcss.
  - `minify`, it wasn't actual minification after all!
  - `swapLeftRightInUrl`, `swapLtrRtlInUrl` and `swapWestEastInUrl` in favor of `processUrls` option.
  - `preserveComments`, comments inside declaration values will always be preserved.
  - `preserveDirectives`, in favor of `clean` option.

- Constructor arguments `rules`, `declarations` and `properties` are now replaced with `plugins`.

## v1.7.4 - 23 Feb. 2016

- Fixes a bug in flipping multiple transforms.

## v1.7.3 - 30 Jan. 2016

- Fixes a bug in flipping N-Values containing comments.

## 1.7.2 - 30 Jan. 2016

- Fixes a bug in flipping N-Values containing comments.

## 1.7.2 - 04 Dec. 2015

- Fixes a compatibility issue with postcss-js (Fixes [#48](https://github.com/MohammadYounes/rtlcss/issues/48)).

## 1.7.1 - 10 Nov. 2015

- Fixed a bug in flipping backgrounds having functions (Issue [#45](https://github.com/MohammadYounes/rtlcss/issues/45)).

## 1.7.0 - 19 Sep. 2015

- Add `calc` support.
- Mark rule as flipped when values are updated by decl. directives.
- Allow further processing for rules that uses `rename` directive.

## 1.6.3 - 28 Aug. 2015

- CLI: fix source map option (issue #40).
- Upgrade to [postcss] v5.0.x

## 1.6.2 - 21 Jul. 2015

- CLI: fix loading custom configuration file manually via the --config flag. **Thanks @KeyKaKiTO**

## 1.6.1 - 17 Mar. 2015

- Fixed flipping units having more than 1 digit before the decimal point.

## 1.6.0 - 15 Mar. 2015

- Support flipping `matrix3d` transform.

## 1.5.2 - 28 Feb. 2015

- Fix flipping string maps containing regular expressions special characters (Fixes [#24](https://github.com/MohammadYounes/rtlcss/issues/24)).

## 1.5.1 - 14 Feb. 2015

- Fix flipping multiple shadows when a hex color was used. **Thanks @ocean90**

## 1.5.0 - 30 Jan. 2015

- CLI: New option `-e,--ext` to set output files extension when processing a directory.

## 1.4.3 - 24 Jan. 2015

- Upgrade to [postcss] v4.0.x **Thanks @necolas**

## 1.4.2 - 24 Oct. 2014

- CLI: Switch to Unix line endings (Fixes [#14](https://github.com/MohammadYounes/rtlcss/issues/14))

## 1.4.1 - 24 Oct. 2014

- CLI: Print processing errors.

## 1.4.0 - 10 Oct. 2014

- CLI: Support processing a directory. See [CLI documentation](https://github.com/MohammadYounes/rtlcss/blob/master/docs/CLI.md).

## 1.3.1 - 29 Sep. 2014

- Update README.md (typos).

## 1.3.0 - 28 Sep. 2014

- New feature - String Maps. Add your own set of swappable strings, for example (prev/next).
- Preserves lowercase, UPPERCASE and Capitalization when swapping **_left_**, **_right_**, **_ltr_**, **_rtl_**, **_west_** and **_east_**.

## 1.2.0 - 26 Sep. 2014

- Support !important comments for directives (enables flipping minified stylesheets).

## 1.1.0 - 26 Sep. 2014

- Upgrade to [postcss] v2.2.5
- Support flipping `border-color`, `border-style` and `background-position-x`

## 1.0.0 - 24 Aug. 2014

- Upgrade to [postcss] v2.2.1
- Support flipping urls in `@import` rule.
- Fix JSON parse error when configuration file is UTF-8 encoded.
- Better minification.

## 0.9.0 - 10 Aug. 2014

- New configuration loader.
- CLI configuration can be set using one of the following methods:
  - Specify the configuration file manually via the --config flag.
  - Put your config into your projects package.json file under the `rtlcssConfig` property
  - Use a special file `.rtlcssrc` or `.rtlcssrc.json`

## 0.8.0 - 8 Aug. 2014

- Fix source map generation.

## 0.7.0 - 4 Jul. 2014

- Fix flipping linear-gradient.

## 0.6.0 - 4 Jul. 2014

- Allow additional comments inside `ignore`/`rename` rule level directives.

## 0.5.0 - 11 Jun. 2014

- Add CLI support.

## 0.4.0 - 5 Apr. 2014

- Fix flipping transform-origin.
- Update `autoRename` to search for all swappable words.

## 0.3.0 - 5 Apr. 2014

- Support flipping `rotateZ`.
- Fix flipping `rotate3d`.
- Fix flipping `skew`, `skewX` and `skewY`.
- Fix flipping `cursor` value.
- Fix flipping `translate3d`.
- Update flipping background horizontal position to treat `0` as `0%`

## 0.2.1 - 20 Mar. 2014

- Upgrade to [postcss] v0.3.4

## 0.2.0 - 20 Mar. 2014

- Support combining with other processors.
- Support rad, grad & turn angle units when flipping linear-gradient
- Fix typo in config.js

## 0.1.3 - 7 Mar. 2014

- Fix missing include in rules.js

## 0.1.2 - 5 Mar. 2014

- New option: minify output CSS.
- Updated README.md

## 0.1.1 - 4 Mar. 2014

- Initial commit.

[postcss]: https://postcss.org/


---

# RTLCSS

[![Join the chat at https://gitter.im/MohammadYounes/rtlcss](https://img.shields.io/gitter/room/MohammadYounes/rtlcss?color=%2340aa8b)](https://gitter.im/MohammadYounes/rtlcss)

<img src="https://github.com/MohammadYounes/rtlcss/blob/master/.github/logo.svg" alt="" align="right" width="100" height="100" title="RTLCSS">

[![GitHub version](https://img.shields.io/github/v/tag/MohammadYounes/rtlcss)](https://github.com/MohammadYounes/rtlcss/releases)
[![npm version](https://img.shields.io/npm/v/rtlcss)](https://www.npmjs.com/package/rtlcss)
[![CI Status](https://img.shields.io/github/actions/workflow/status/MohammadYounes/rtlcss/ci.yml?branch=master&label=CI)](https://github.com/MohammadYounes/rtlcss/actions/workflows/ci.yml?query=branch%3Amaster)

[![js-standard-style](https://img.shields.io/badge/code%20style-standard-blue)](https://standardjs.com/)
[![editor](https://img.shields.io/badge/editor-vscode-blue)](https://code.visualstudio.com/)
[![Twitter](https://img.shields.io/badge/follow-%40rtlcss-blue)](https://twitter.com/rtlcss)

RTLCSS is a framework for converting Left-To-Right (LTR) Cascading Style Sheets(CSS) to Right-To-Left (RTL).

## Documentation

Visit <https://rtlcss.com/learn/>

## Playground

Visit <https://rtlcss.com/playground/>

## Bugs and Issues

Have a bug or a feature request? please feel free to [open a new issue](https://github.com/MohammadYounes/rtlcss/issues/new).

## Release Notes

To view changes in recent versions, see the [CHANGELOG](CHANGELOG.md).

## Support

RTLCSS is saving you and your team a tremendous amount of time and effort? [Buy Me a Coffee ☕](https://www.paypal.me/MohammadYounes)


---

# run-parallel [![travis][travis-image]][travis-url] [![npm][npm-image]][npm-url] [![downloads][downloads-image]][downloads-url] [![javascript style guide][standard-image]][standard-url]

[travis-image]: https://img.shields.io/travis/feross/run-parallel/master.svg
[travis-url]: https://travis-ci.org/feross/run-parallel
[npm-image]: https://img.shields.io/npm/v/run-parallel.svg
[npm-url]: https://npmjs.org/package/run-parallel
[downloads-image]: https://img.shields.io/npm/dm/run-parallel.svg
[downloads-url]: https://npmjs.org/package/run-parallel
[standard-image]: https://img.shields.io/badge/code_style-standard-brightgreen.svg
[standard-url]: https://standardjs.com

### Run an array of functions in parallel

![parallel](https://raw.githubusercontent.com/feross/run-parallel/master/img.png) [![Sauce Test Status](https://saucelabs.com/browser-matrix/run-parallel.svg)](https://saucelabs.com/u/run-parallel)

### install

```
npm install run-parallel
```

### usage

#### parallel(tasks, [callback])

Run the `tasks` array of functions in parallel, without waiting until the previous
function has completed. If any of the functions pass an error to its callback, the main
`callback` is immediately called with the value of the error. Once the `tasks` have
completed, the results are passed to the final `callback` as an array.

It is also possible to use an object instead of an array. Each property will be run as a
function and the results will be passed to the final `callback` as an object instead of
an array. This can be a more readable way of handling the results.

##### arguments

- `tasks` - An array or object containing functions to run. Each function is passed a
`callback(err, result)` which it must call on completion with an error `err` (which can
be `null`) and an optional `result` value.
- `callback(err, results)` - An optional callback to run once all the functions have
completed. This function gets a results array (or object) containing all the result
arguments passed to the task callbacks.

##### example

```js
var parallel = require('run-parallel')

parallel([
  function (callback) {
    setTimeout(function () {
      callback(null, 'one')
    }, 200)
  },
  function (callback) {
    setTimeout(function () {
      callback(null, 'two')
    }, 100)
  }
],
// optional callback
function (err, results) {
  // the results array will equal ['one','two'] even though
  // the second function had a shorter timeout.
})
```

This module is basically equavalent to
[`async.parallel`](https://github.com/caolan/async#paralleltasks-callback), but it's
handy to just have the one function you need instead of the kitchen sink. Modularity!
Especially handy if you're serving to the browser and need to reduce your javascript
bundle size.

Works great in the browser with [browserify](http://browserify.org/)!

### see also

- [run-auto](https://github.com/feross/run-auto)
- [run-parallel-limit](https://github.com/feross/run-parallel-limit)
- [run-series](https://github.com/feross/run-series)
- [run-waterfall](https://github.com/feross/run-waterfall)

### license

MIT. Copyright (c) [Feross Aboukhadijeh](http://feross.org).


---

# safe-buffer [![travis][travis-image]][travis-url] [![npm][npm-image]][npm-url] [![downloads][downloads-image]][downloads-url] [![javascript style guide][standard-image]][standard-url]

[travis-image]: https://img.shields.io/travis/feross/safe-buffer/master.svg
[travis-url]: https://travis-ci.org/feross/safe-buffer
[npm-image]: https://img.shields.io/npm/v/safe-buffer.svg
[npm-url]: https://npmjs.org/package/safe-buffer
[downloads-image]: https://img.shields.io/npm/dm/safe-buffer.svg
[downloads-url]: https://npmjs.org/package/safe-buffer
[standard-image]: https://img.shields.io/badge/code_style-standard-brightgreen.svg
[standard-url]: https://standardjs.com

#### Safer Node.js Buffer API

**Use the new Node.js Buffer APIs (`Buffer.from`, `Buffer.alloc`,
`Buffer.allocUnsafe`, `Buffer.allocUnsafeSlow`) in all versions of Node.js.**

**Uses the built-in implementation when available.**

## install

```
npm install safe-buffer
```

## usage

The goal of this package is to provide a safe replacement for the node.js `Buffer`.

It's a drop-in replacement for `Buffer`. You can use it by adding one `require` line to
the top of your node.js modules:

```js
var Buffer = require('safe-buffer').Buffer

// Existing buffer code will continue to work without issues:

new Buffer('hey', 'utf8')
new Buffer([1, 2, 3], 'utf8')
new Buffer(obj)
new Buffer(16) // create an uninitialized buffer (potentially unsafe)

// But you can use these new explicit APIs to make clear what you want:

Buffer.from('hey', 'utf8') // convert from many types to a Buffer
Buffer.alloc(16) // create a zero-filled buffer (safe)
Buffer.allocUnsafe(16) // create an uninitialized buffer (potentially unsafe)
```

## api

### Class Method: Buffer.from(array)
<!-- YAML
added: v3.0.0
-->

* `array` {Array}

Allocates a new `Buffer` using an `array` of octets.

```js
const buf = Buffer.from([0x62,0x75,0x66,0x66,0x65,0x72]);
  // creates a new Buffer containing ASCII bytes
  // ['b','u','f','f','e','r']
```

A `TypeError` will be thrown if `array` is not an `Array`.

### Class Method: Buffer.from(arrayBuffer[, byteOffset[, length]])
<!-- YAML
added: v5.10.0
-->

* `arrayBuffer` {ArrayBuffer} The `.buffer` property of a `TypedArray` or
  a `new ArrayBuffer()`
* `byteOffset` {Number} Default: `0`
* `length` {Number} Default: `arrayBuffer.length - byteOffset`

When passed a reference to the `.buffer` property of a `TypedArray` instance,
the newly created `Buffer` will share the same allocated memory as the
TypedArray.

```js
const arr = new Uint16Array(2);
arr[0] = 5000;
arr[1] = 4000;

const buf = Buffer.from(arr.buffer); // shares the memory with arr;

console.log(buf);
  // Prints: <Buffer 88 13 a0 0f>

// changing the TypedArray changes the Buffer also
arr[1] = 6000;

console.log(buf);
  // Prints: <Buffer 88 13 70 17>
```

The optional `byteOffset` and `length` arguments specify a memory range within
the `arrayBuffer` that will be shared by the `Buffer`.

```js
const ab = new ArrayBuffer(10);
const buf = Buffer.from(ab, 0, 2);
console.log(buf.length);
  // Prints: 2
```

A `TypeError` will be thrown if `arrayBuffer` is not an `ArrayBuffer`.

### Class Method: Buffer.from(buffer)
<!-- YAML
added: v3.0.0
-->

* `buffer` {Buffer}

Copies the passed `buffer` data onto a new `Buffer` instance.

```js
const buf1 = Buffer.from('buffer');
const buf2 = Buffer.from(buf1);

buf1[0] = 0x61;
console.log(buf1.toString());
  // 'auffer'
console.log(buf2.toString());
  // 'buffer' (copy is not changed)
```

A `TypeError` will be thrown if `buffer` is not a `Buffer`.

### Class Method: Buffer.from(str[, encoding])
<!-- YAML
added: v5.10.0
-->

* `str` {String} String to encode.
* `encoding` {String} Encoding to use, Default: `'utf8'`

Creates a new `Buffer` containing the given JavaScript string `str`. If
provided, the `encoding` parameter identifies the character encoding.
If not provided, `encoding` defaults to `'utf8'`.

```js
const buf1 = Buffer.from('this is a tést');
console.log(buf1.toString());
  // prints: this is a tést
console.log(buf1.toString('ascii'));
  // prints: this is a tC)st

const buf2 = Buffer.from('7468697320697320612074c3a97374', 'hex');
console.log(buf2.toString());
  // prints: this is a tést
```

A `TypeError` will be thrown if `str` is not a string.

### Class Method: Buffer.alloc(size[, fill[, encoding]])
<!-- YAML
added: v5.10.0
-->

* `size` {Number}
* `fill` {Value} Default: `undefined`
* `encoding` {String} Default: `utf8`

Allocates a new `Buffer` of `size` bytes. If `fill` is `undefined`, the
`Buffer` will be *zero-filled*.

```js
const buf = Buffer.alloc(5);
console.log(buf);
  // <Buffer 00 00 00 00 00>
```

The `size` must be less than or equal to the value of
`require('buffer').kMaxLength` (on 64-bit architectures, `kMaxLength` is
`(2^31)-1`). Otherwise, a [`RangeError`][] is thrown. A zero-length Buffer will
be created if a `size` less than or equal to 0 is specified.

If `fill` is specified, the allocated `Buffer` will be initialized by calling
`buf.fill(fill)`. See [`buf.fill()`][] for more information.

```js
const buf = Buffer.alloc(5, 'a');
console.log(buf);
  // <Buffer 61 61 61 61 61>
```

If both `fill` and `encoding` are specified, the allocated `Buffer` will be
initialized by calling `buf.fill(fill, encoding)`. For example:

```js
const buf = Buffer.alloc(11, 'aGVsbG8gd29ybGQ=', 'base64');
console.log(buf);
  // <Buffer 68 65 6c 6c 6f 20 77 6f 72 6c 64>
```

Calling `Buffer.alloc(size)` can be significantly slower than the alternative
`Buffer.allocUnsafe(size)` but ensures that the newly created `Buffer` instance
contents will *never contain sensitive data*.

A `TypeError` will be thrown if `size` is not a number.

### Class Method: Buffer.allocUnsafe(size)
<!-- YAML
added: v5.10.0
-->

* `size` {Number}

Allocates a new *non-zero-filled* `Buffer` of `size` bytes.  The `size` must
be less than or equal to the value of `require('buffer').kMaxLength` (on 64-bit
architectures, `kMaxLength` is `(2^31)-1`). Otherwise, a [`RangeError`][] is
thrown. A zero-length Buffer will be created if a `size` less than or equal to
0 is specified.

The underlying memory for `Buffer` instances created in this way is *not
initialized*. The contents of the newly created `Buffer` are unknown and
*may contain sensitive data*. Use [`buf.fill(0)`][] to initialize such
`Buffer` instances to zeroes.

```js
const buf = Buffer.allocUnsafe(5);
console.log(buf);
  // <Buffer 78 e0 82 02 01>
  // (octets will be different, every time)
buf.fill(0);
console.log(buf);
  // <Buffer 00 00 00 00 00>
```

A `TypeError` will be thrown if `size` is not a number.

Note that the `Buffer` module pre-allocates an internal `Buffer` instance of
size `Buffer.poolSize` that is used as a pool for the fast allocation of new
`Buffer` instances created using `Buffer.allocUnsafe(size)` (and the deprecated
`new Buffer(size)` constructor) only when `size` is less than or equal to
`Buffer.poolSize >> 1` (floor of `Buffer.poolSize` divided by two). The default
value of `Buffer.poolSize` is `8192` but can be modified.

Use of this pre-allocated internal memory pool is a key difference between
calling `Buffer.alloc(size, fill)` vs. `Buffer.allocUnsafe(size).fill(fill)`.
Specifically, `Buffer.alloc(size, fill)` will *never* use the internal Buffer
pool, while `Buffer.allocUnsafe(size).fill(fill)` *will* use the internal
Buffer pool if `size` is less than or equal to half `Buffer.poolSize`. The
difference is subtle but can be important when an application requires the
additional performance that `Buffer.allocUnsafe(size)` provides.

### Class Method: Buffer.allocUnsafeSlow(size)
<!-- YAML
added: v5.10.0
-->

* `size` {Number}

Allocates a new *non-zero-filled* and non-pooled `Buffer` of `size` bytes.  The
`size` must be less than or equal to the value of
`require('buffer').kMaxLength` (on 64-bit architectures, `kMaxLength` is
`(2^31)-1`). Otherwise, a [`RangeError`][] is thrown. A zero-length Buffer will
be created if a `size` less than or equal to 0 is specified.

The underlying memory for `Buffer` instances created in this way is *not
initialized*. The contents of the newly created `Buffer` are unknown and
*may contain sensitive data*. Use [`buf.fill(0)`][] to initialize such
`Buffer` instances to zeroes.

When using `Buffer.allocUnsafe()` to allocate new `Buffer` instances,
allocations under 4KB are, by default, sliced from a single pre-allocated
`Buffer`. This allows applications to avoid the garbage collection overhead of
creating many individually allocated Buffers. This approach improves both
performance and memory usage by eliminating the need to track and cleanup as
many `Persistent` objects.

However, in the case where a developer may need to retain a small chunk of
memory from a pool for an indeterminate amount of time, it may be appropriate
to create an un-pooled Buffer instance using `Buffer.allocUnsafeSlow()` then
copy out the relevant bits.

```js
// need to keep around a few small chunks of memory
const store = [];

socket.on('readable', () => {
  const data = socket.read();
  // allocate for retained data
  const sb = Buffer.allocUnsafeSlow(10);
  // copy the data into the new allocation
  data.copy(sb, 0, 0, 10);
  store.push(sb);
});
```

Use of `Buffer.allocUnsafeSlow()` should be used only as a last resort *after*
a developer has observed undue memory retention in their applications.

A `TypeError` will be thrown if `size` is not a number.

### All the Rest

The rest of the `Buffer` API is exactly the same as in node.js.
[See the docs](https://nodejs.org/api/buffer.html).


## Related links

- [Node.js issue: Buffer(number) is unsafe](https://github.com/nodejs/node/issues/4660)
- [Node.js Enhancement Proposal: Buffer.from/Buffer.alloc/Buffer.zalloc/Buffer() soft-deprecate](https://github.com/nodejs/node-eps/pull/4)

## Why is `Buffer` unsafe?

Today, the node.js `Buffer` constructor is overloaded to handle many different argument
types like `String`, `Array`, `Object`, `TypedArrayView` (`Uint8Array`, etc.),
`ArrayBuffer`, and also `Number`.

The API is optimized for convenience: you can throw any type at it, and it will try to do
what you want.

Because the Buffer constructor is so powerful, you often see code like this:

```js
// Convert UTF-8 strings to hex
function toHex (str) {
  return new Buffer(str).toString('hex')
}
```

***But what happens if `toHex` is called with a `Number` argument?***

### Remote Memory Disclosure

If an attacker can make your program call the `Buffer` constructor with a `Number`
argument, then they can make it allocate uninitialized memory from the node.js process.
This could potentially disclose TLS private keys, user data, or database passwords.

When the `Buffer` constructor is passed a `Number` argument, it returns an
**UNINITIALIZED** block of memory of the specified `size`. When you create a `Buffer` like
this, you **MUST** overwrite the contents before returning it to the user.

From the [node.js docs](https://nodejs.org/api/buffer.html#buffer_new_buffer_size):

> `new Buffer(size)`
>
> - `size` Number
>
> The underlying memory for `Buffer` instances created in this way is not initialized.
> **The contents of a newly created `Buffer` are unknown and could contain sensitive
> data.** Use `buf.fill(0)` to initialize a Buffer to zeroes.

(Emphasis our own.)

Whenever the programmer intended to create an uninitialized `Buffer` you often see code
like this:

```js
var buf = new Buffer(16)

// Immediately overwrite the uninitialized buffer with data from another buffer
for (var i = 0; i < buf.length; i++) {
  buf[i] = otherBuf[i]
}
```


### Would this ever be a problem in real code?

Yes. It's surprisingly common to forget to check the type of your variables in a
dynamically-typed language like JavaScript.

Usually the consequences of assuming the wrong type is that your program crashes with an
uncaught exception. But the failure mode for forgetting to check the type of arguments to
the `Buffer` constructor is more catastrophic.

Here's an example of a vulnerable service that takes a JSON payload and converts it to
hex:

```js
// Take a JSON payload {str: "some string"} and convert it to hex
var server = http.createServer(function (req, res) {
  var data = ''
  req.setEncoding('utf8')
  req.on('data', function (chunk) {
    data += chunk
  })
  req.on('end', function () {
    var body = JSON.parse(data)
    res.end(new Buffer(body.str).toString('hex'))
  })
})

server.listen(8080)
```

In this example, an http client just has to send:

```json
{
  "str": 1000
}
```

and it will get back 1,000 bytes of uninitialized memory from the server.

This is a very serious bug. It's similar in severity to the
[the Heartbleed bug](http://heartbleed.com/) that allowed disclosure of OpenSSL process
memory by remote attackers.


### Which real-world packages were vulnerable?

#### [`bittorrent-dht`](https://www.npmjs.com/package/bittorrent-dht)

[Mathias Buus](https://github.com/mafintosh) and I
([Feross Aboukhadijeh](http://feross.org/)) found this issue in one of our own packages,
[`bittorrent-dht`](https://www.npmjs.com/package/bittorrent-dht). The bug would allow
anyone on the internet to send a series of messages to a user of `bittorrent-dht` and get
them to reveal 20 bytes at a time of uninitialized memory from the node.js process.

Here's
[the commit](https://github.com/feross/bittorrent-dht/commit/6c7da04025d5633699800a99ec3fbadf70ad35b8)
that fixed it. We released a new fixed version, created a
[Node Security Project disclosure](https://nodesecurity.io/advisories/68), and deprecated all
vulnerable versions on npm so users will get a warning to upgrade to a newer version.

#### [`ws`](https://www.npmjs.com/package/ws)

That got us wondering if there were other vulnerable packages. Sure enough, within a short
period of time, we found the same issue in [`ws`](https://www.npmjs.com/package/ws), the
most popular WebSocket implementation in node.js.

If certain APIs were called with `Number` parameters instead of `String` or `Buffer` as
expected, then uninitialized server memory would be disclosed to the remote peer.

These were the vulnerable methods:

```js
socket.send(number)
socket.ping(number)
socket.pong(number)
```

Here's a vulnerable socket server with some echo functionality:

```js
server.on('connection', function (socket) {
  socket.on('message', function (message) {
    message = JSON.parse(message)
    if (message.type === 'echo') {
      socket.send(message.data) // send back the user's message
    }
  })
})
```

`socket.send(number)` called on the server, will disclose server memory.

Here's [the release](https://github.com/websockets/ws/releases/tag/1.0.1) where the issue
was fixed, with a more detailed explanation. Props to
[Arnout Kazemier](https://github.com/3rd-Eden) for the quick fix. Here's the
[Node Security Project disclosure](https://nodesecurity.io/advisories/67).


### What's the solution?

It's important that node.js offers a fast way to get memory otherwise performance-critical
applications would needlessly get a lot slower.

But we need a better way to *signal our intent* as programmers. **When we want
uninitialized memory, we should request it explicitly.**

Sensitive functionality should not be packed into a developer-friendly API that loosely
accepts many different types. This type of API encourages the lazy practice of passing
variables in without checking the type very carefully.

#### A new API: `Buffer.allocUnsafe(number)`

The functionality of creating buffers with uninitialized memory should be part of another
API. We propose `Buffer.allocUnsafe(number)`. This way, it's not part of an API that
frequently gets user input of all sorts of different types passed into it.

```js
var buf = Buffer.allocUnsafe(16) // careful, uninitialized memory!

// Immediately overwrite the uninitialized buffer with data from another buffer
for (var i = 0; i < buf.length; i++) {
  buf[i] = otherBuf[i]
}
```


### How do we fix node.js core?

We sent [a PR to node.js core](https://github.com/nodejs/node/pull/4514) (merged as
`semver-major`) which defends against one case:

```js
var str = 16
new Buffer(str, 'utf8')
```

In this situation, it's implied that the programmer intended the first argument to be a
string, since they passed an encoding as a second argument. Today, node.js will allocate
uninitialized memory in the case of `new Buffer(number, encoding)`, which is probably not
what the programmer intended.

But this is only a partial solution, since if the programmer does `new Buffer(variable)`
(without an `encoding` parameter) there's no way to know what they intended. If `variable`
is sometimes a number, then uninitialized memory will sometimes be returned.

### What's the real long-term fix?

We could deprecate and remove `new Buffer(number)` and use `Buffer.allocUnsafe(number)` when
we need uninitialized memory. But that would break 1000s of packages.

~~We believe the best solution is to:~~

~~1. Change `new Buffer(number)` to return safe, zeroed-out memory~~

~~2. Create a new API for creating uninitialized Buffers. We propose: `Buffer.allocUnsafe(number)`~~

#### Update

We now support adding three new APIs:

- `Buffer.from(value)` - convert from any type to a buffer
- `Buffer.alloc(size)` - create a zero-filled buffer
- `Buffer.allocUnsafe(size)` - create an uninitialized buffer with given size

This solves the core problem that affected `ws` and `bittorrent-dht` which is
`Buffer(variable)` getting tricked into taking a number argument.

This way, existing code continues working and the impact on the npm ecosystem will be
minimal. Over time, npm maintainers can migrate performance-critical code to use
`Buffer.allocUnsafe(number)` instead of `new Buffer(number)`.


### Conclusion

We think there's a serious design issue with the `Buffer` API as it exists today. It
promotes insecure software by putting high-risk functionality into a convenient API
with friendly "developer ergonomics".

This wasn't merely a theoretical exercise because we found the issue in some of the
most popular npm packages.

Fortunately, there's an easy fix that can be applied today. Use `safe-buffer` in place of
`buffer`.

```js
var Buffer = require('safe-buffer').Buffer
```

Eventually, we hope that node.js core can switch to this new, safer behavior. We believe
the impact on the ecosystem would be minimal since it's not a breaking change.
Well-maintained, popular packages would be updated to use `Buffer.alloc` quickly, while
older, insecure packages would magically become safe from this attack vector.


## links

- [Node.js PR: buffer: throw if both length and enc are passed](https://github.com/nodejs/node/pull/4514)
- [Node Security Project disclosure for `ws`](https://nodesecurity.io/advisories/67)
- [Node Security Project disclosure for`bittorrent-dht`](https://nodesecurity.io/advisories/68)


## credit

The original issues in `bittorrent-dht`
([disclosure](https://nodesecurity.io/advisories/68)) and
`ws` ([disclosure](https://nodesecurity.io/advisories/67)) were discovered by
[Mathias Buus](https://github.com/mafintosh) and
[Feross Aboukhadijeh](http://feross.org/).

Thanks to [Adam Baldwin](https://github.com/evilpacket) for helping disclose these issues
and for his work running the [Node Security Project](https://nodesecurity.io/).

Thanks to [John Hiesey](https://github.com/jhiesey) for proofreading this README and
auditing the code.


## license

MIT. Copyright (C) [Feross Aboukhadijeh](http://feross.org)


---

# Porting to the Buffer.from/Buffer.alloc API

<a id="overview"></a>
## Overview

- [Variant 1: Drop support for Node.js ≤ 4.4.x and 5.0.0 — 5.9.x.](#variant-1) (*recommended*)
- [Variant 2: Use a polyfill](#variant-2)
- [Variant 3: manual detection, with safeguards](#variant-3)

### Finding problematic bits of code using grep

Just run `grep -nrE '[^a-zA-Z](Slow)?Buffer\s*\(' --exclude-dir node_modules`.

It will find all the potentially unsafe places in your own code (with some considerably unlikely
exceptions).

### Finding problematic bits of code using Node.js 8

If you’re using Node.js ≥ 8.0.0 (which is recommended), Node.js exposes multiple options that help with finding the relevant pieces of code:

- `--trace-warnings` will make Node.js show a stack trace for this warning and other warnings that are printed by Node.js.
- `--trace-deprecation` does the same thing, but only for deprecation warnings.
- `--pending-deprecation` will show more types of deprecation warnings. In particular, it will show the `Buffer()` deprecation warning, even on Node.js 8.

You can set these flags using an environment variable:

```console
$ export NODE_OPTIONS='--trace-warnings --pending-deprecation'
$ cat example.js
'use strict';
const foo = new Buffer('foo');
$ node example.js
(node:7147) [DEP0005] DeprecationWarning: The Buffer() and new Buffer() constructors are not recommended for use due to security and usability concerns. Please use the new Buffer.alloc(), Buffer.allocUnsafe(), or Buffer.from() construction methods instead.
    at showFlaggedDeprecation (buffer.js:127:13)
    at new Buffer (buffer.js:148:3)
    at Object.<anonymous> (/path/to/example.js:2:13)
    [... more stack trace lines ...]
```

### Finding problematic bits of code using linters

Eslint rules [no-buffer-constructor](https://eslint.org/docs/rules/no-buffer-constructor)
or
[node/no-deprecated-api](https://github.com/mysticatea/eslint-plugin-node/blob/master/docs/rules/no-deprecated-api.md)
also find calls to deprecated `Buffer()` API. Those rules are included in some pre-sets.

There is a drawback, though, that it doesn't always
[work correctly](https://github.com/chalker/safer-buffer#why-not-safe-buffer) when `Buffer` is
overriden e.g. with a polyfill, so recommended is a combination of this and some other method
described above.

<a id="variant-1"></a>
## Variant 1: Drop support for Node.js ≤ 4.4.x and 5.0.0 — 5.9.x.

This is the recommended solution nowadays that would imply only minimal overhead.

The Node.js 5.x release line has been unsupported since July 2016, and the Node.js 4.x release line reaches its End of Life in April 2018 (→ [Schedule](https://github.com/nodejs/Release#release-schedule)). This means that these versions of Node.js will *not* receive any updates, even in case of security issues, so using these release lines should be avoided, if at all possible.

What you would do in this case is to convert all `new Buffer()` or `Buffer()` calls to use `Buffer.alloc()` or `Buffer.from()`, in the following way:

- For `new Buffer(number)`, replace it with `Buffer.alloc(number)`.
- For `new Buffer(string)` (or `new Buffer(string, encoding)`), replace it with `Buffer.from(string)` (or `Buffer.from(string, encoding)`).
- For all other combinations of arguments (these are much rarer), also replace `new Buffer(...arguments)` with `Buffer.from(...arguments)`.

Note that `Buffer.alloc()` is also _faster_ on the current Node.js versions than
`new Buffer(size).fill(0)`, which is what you would otherwise need to ensure zero-filling.

Enabling eslint rule [no-buffer-constructor](https://eslint.org/docs/rules/no-buffer-constructor)
or
[node/no-deprecated-api](https://github.com/mysticatea/eslint-plugin-node/blob/master/docs/rules/no-deprecated-api.md)
is recommended to avoid accidential unsafe Buffer API usage.

There is also a [JSCodeshift codemod](https://github.com/joyeecheung/node-dep-codemod#dep005)
for automatically migrating Buffer constructors to `Buffer.alloc()` or `Buffer.from()`.
Note that it currently only works with cases where the arguments are literals or where the
constructor is invoked with two arguments.

_If you currently support those older Node.js versions and dropping them would be a semver-major change
for you, or if you support older branches of your packages, consider using [Variant 2](#variant-2)
or [Variant 3](#variant-3) on older branches, so people using those older branches will also receive
the fix. That way, you will eradicate potential issues caused by unguarded Buffer API usage and
your users will not observe a runtime deprecation warning when running your code on Node.js 10._

<a id="variant-2"></a>
## Variant 2: Use a polyfill

Utilize [safer-buffer](https://www.npmjs.com/package/safer-buffer) as a polyfill to support older
Node.js versions.

You would take exacly the same steps as in [Variant 1](#variant-1), but with a polyfill
`const Buffer = require('safer-buffer').Buffer` in all files where you use the new `Buffer` api.

Make sure that you do not use old `new Buffer` API — in any files where the line above is added,
using old `new Buffer()` API will _throw_. It will be easy to notice that in CI, though.

Alternatively, you could use [buffer-from](https://www.npmjs.com/package/buffer-from) and/or
[buffer-alloc](https://www.npmjs.com/package/buffer-alloc) [ponyfills](https://ponyfill.com/) —
those are great, the only downsides being 4 deps in the tree and slightly more code changes to
migrate off them (as you would be using e.g. `Buffer.from` under a different name). If you need only
`Buffer.from` polyfilled — `buffer-from` alone which comes with no extra dependencies.

_Alternatively, you could use [safe-buffer](https://www.npmjs.com/package/safe-buffer) — it also
provides a polyfill, but takes a different approach which has
[it's drawbacks](https://github.com/chalker/safer-buffer#why-not-safe-buffer). It will allow you
to also use the older `new Buffer()` API in your code, though — but that's arguably a benefit, as
it is problematic, can cause issues in your code, and will start emitting runtime deprecation
warnings starting with Node.js 10._

Note that in either case, it is important that you also remove all calls to the old Buffer
API manually — just throwing in `safe-buffer` doesn't fix the problem by itself, it just provides
a polyfill for the new API. I have seen people doing that mistake.

Enabling eslint rule [no-buffer-constructor](https://eslint.org/docs/rules/no-buffer-constructor)
or
[node/no-deprecated-api](https://github.com/mysticatea/eslint-plugin-node/blob/master/docs/rules/no-deprecated-api.md)
is recommended.

_Don't forget to drop the polyfill usage once you drop support for Node.js < 4.5.0._

<a id="variant-3"></a>
## Variant 3 — manual detection, with safeguards

This is useful if you create Buffer instances in only a few places (e.g. one), or you have your own
wrapper around them.

### Buffer(0)

This special case for creating empty buffers can be safely replaced with `Buffer.concat([])`, which
returns the same result all the way down to Node.js 0.8.x.

### Buffer(notNumber)

Before:

```js
var buf = new Buffer(notNumber, encoding);
```

After:

```js
var buf;
if (Buffer.from && Buffer.from !== Uint8Array.from) {
  buf = Buffer.from(notNumber, encoding);
} else {
  if (typeof notNumber === 'number')
    throw new Error('The "size" argument must be of type number.');
  buf = new Buffer(notNumber, encoding);
}
```

`encoding` is optional.

Note that the `typeof notNumber` before `new Buffer` is required (for cases when `notNumber` argument is not
hard-coded) and _is not caused by the deprecation of Buffer constructor_ — it's exactly _why_ the
Buffer constructor is deprecated. Ecosystem packages lacking this type-check caused numereous
security issues — situations when unsanitized user input could end up in the `Buffer(arg)` create
problems ranging from DoS to leaking sensitive information to the attacker from the process memory.

When `notNumber` argument is hardcoded (e.g. literal `"abc"` or `[0,1,2]`), the `typeof` check can
be omitted.

Also note that using TypeScript does not fix this problem for you — when libs written in
`TypeScript` are used from JS, or when user input ends up there — it behaves exactly as pure JS, as
all type checks are translation-time only and are not present in the actual JS code which TS
compiles to.

### Buffer(number)

For Node.js 0.10.x (and below) support:

```js
var buf;
if (Buffer.alloc) {
  buf = Buffer.alloc(number);
} else {
  buf = new Buffer(number);
  buf.fill(0);
}
```

Otherwise (Node.js ≥ 0.12.x):

```js
const buf = Buffer.alloc ? Buffer.alloc(number) : new Buffer(number).fill(0);
```

## Regarding Buffer.allocUnsafe

Be extra cautious when using `Buffer.allocUnsafe`:
 * Don't use it if you don't have a good reason to
   * e.g. you probably won't ever see a performance difference for small buffers, in fact, those
     might be even faster with `Buffer.alloc()`,
   * if your code is not in the hot code path — you also probably won't notice a difference,
   * keep in mind that zero-filling minimizes the potential risks.
 * If you use it, make sure that you never return the buffer in a partially-filled state,
   * if you are writing to it sequentially — always truncate it to the actuall written length

Errors in handling buffers allocated with `Buffer.allocUnsafe` could result in various issues,
ranged from undefined behaviour of your code to sensitive data (user input, passwords, certs)
leaking to the remote attacker.

_Note that the same applies to `new Buffer` usage without zero-filling, depending on the Node.js
version (and lacking type checks also adds DoS to the list of potential problems)._

<a id="faq"></a>
## FAQ

<a id="design-flaws"></a>
### What is wrong with the `Buffer` constructor?

The `Buffer` constructor could be used to create a buffer in many different ways:

- `new Buffer(42)` creates a `Buffer` of 42 bytes. Before Node.js 8, this buffer contained
  *arbitrary memory* for performance reasons, which could include anything ranging from
  program source code to passwords and encryption keys.
- `new Buffer('abc')` creates a `Buffer` that contains the UTF-8-encoded version of
  the string `'abc'`. A second argument could specify another encoding: For example,
  `new Buffer(string, 'base64')` could be used to convert a Base64 string into the original
  sequence of bytes that it represents.
- There are several other combinations of arguments.

This meant that, in code like `var buffer = new Buffer(foo);`, *it is not possible to tell
what exactly the contents of the generated buffer are* without knowing the type of `foo`.

Sometimes, the value of `foo` comes from an external source. For example, this function
could be exposed as a service on a web server, converting a UTF-8 string into its Base64 form:

```
function stringToBase64(req, res) {
  // The request body should have the format of `{ string: 'foobar' }`
  const rawBytes = new Buffer(req.body.string)
  const encoded = rawBytes.toString('base64')
  res.end({ encoded: encoded })
}
```

Note that this code does *not* validate the type of `req.body.string`:

- `req.body.string` is expected to be a string. If this is the case, all goes well.
- `req.body.string` is controlled by the client that sends the request.
- If `req.body.string` is the *number* `50`, the `rawBytes` would be 50 bytes:
  - Before Node.js 8, the content would be uninitialized
  - After Node.js 8, the content would be `50` bytes with the value `0`

Because of the missing type check, an attacker could intentionally send a number
as part of the request. Using this, they can either:

- Read uninitialized memory. This **will** leak passwords, encryption keys and other
  kinds of sensitive information. (Information leak)
- Force the program to allocate a large amount of memory. For example, when specifying
  `500000000` as the input value, each request will allocate 500MB of memory.
  This can be used to either exhaust the memory available of a program completely
  and make it crash, or slow it down significantly. (Denial of Service)

Both of these scenarios are considered serious security issues in a real-world
web server context.

when using `Buffer.from(req.body.string)` instead, passing a number will always
throw an exception instead, giving a controlled behaviour that can always be
handled by the program.

<a id="ecosystem-usage"></a>
### The `Buffer()` constructor has been deprecated for a while. Is this really an issue?

Surveys of code in the `npm` ecosystem have shown that the `Buffer()` constructor is still
widely used. This includes new code, and overall usage of such code has actually been
*increasing*.


---

# safer-buffer [![travis][travis-image]][travis-url] [![npm][npm-image]][npm-url] [![javascript style guide][standard-image]][standard-url] [![Security Responsible Disclosure][secuirty-image]][secuirty-url]

[travis-image]: https://travis-ci.org/ChALkeR/safer-buffer.svg?branch=master
[travis-url]: https://travis-ci.org/ChALkeR/safer-buffer
[npm-image]: https://img.shields.io/npm/v/safer-buffer.svg
[npm-url]: https://npmjs.org/package/safer-buffer
[standard-image]: https://img.shields.io/badge/code_style-standard-brightgreen.svg
[standard-url]: https://standardjs.com
[secuirty-image]: https://img.shields.io/badge/Security-Responsible%20Disclosure-green.svg
[secuirty-url]: https://github.com/nodejs/security-wg/blob/master/processes/responsible_disclosure_template.md

Modern Buffer API polyfill without footguns, working on Node.js from 0.8 to current.

## How to use?

First, port all `Buffer()` and `new Buffer()` calls to `Buffer.alloc()` and `Buffer.from()` API.

Then, to achieve compatibility with outdated Node.js versions (`<4.5.0` and 5.x `<5.9.0`), use
`const Buffer = require('safer-buffer').Buffer` in all files where you make calls to the new
Buffer API. _Use `var` instead of `const` if you need that for your Node.js version range support._

Also, see the
[porting Buffer](https://github.com/ChALkeR/safer-buffer/blob/master/Porting-Buffer.md) guide.

## Do I need it?

Hopefully, not — dropping support for outdated Node.js versions should be fine nowdays, and that
is the recommended path forward. You _do_ need to port to the `Buffer.alloc()` and `Buffer.from()`
though.

See the [porting guide](https://github.com/ChALkeR/safer-buffer/blob/master/Porting-Buffer.md)
for a better description.

## Why not [safe-buffer](https://npmjs.com/safe-buffer)?

_In short: while `safe-buffer` serves as a polyfill for the new API, it allows old API usage and
itself contains footguns._

`safe-buffer` could be used safely to get the new API while still keeping support for older
Node.js versions (like this module), but while analyzing ecosystem usage of the old Buffer API
I found out that `safe-buffer` is itself causing problems in some cases.

For example, consider the following snippet:

```console
$ cat example.unsafe.js
console.log(Buffer(20))
$ ./node-v6.13.0-linux-x64/bin/node example.unsafe.js
<Buffer 0a 00 00 00 00 00 00 00 28 13 de 02 00 00 00 00 05 00 00 00>
$ standard example.unsafe.js
standard: Use JavaScript Standard Style (https://standardjs.com)
  /home/chalker/repo/safer-buffer/example.unsafe.js:2:13: 'Buffer()' was deprecated since v6. Use 'Buffer.alloc()' or 'Buffer.from()' (use 'https://www.npmjs.com/package/safe-buffer' for '<4.5.0') instead.
```

This is allocates and writes to console an uninitialized chunk of memory.
[standard](https://www.npmjs.com/package/standard) linter (among others) catch that and warn people
to avoid using unsafe API.

Let's now throw in `safe-buffer`!

```console
$ cat example.safe-buffer.js
const Buffer = require('safe-buffer').Buffer
console.log(Buffer(20))
$ standard example.safe-buffer.js
$ ./node-v6.13.0-linux-x64/bin/node example.safe-buffer.js
<Buffer 08 00 00 00 00 00 00 00 28 58 01 82 fe 7f 00 00 00 00 00 00>
```

See the problem? Adding in `safe-buffer` _magically removes the lint warning_, but the behavior
remains identiсal to what we had before, and when launched on Node.js 6.x LTS — this dumps out
chunks of uninitialized memory.
_And this code will still emit runtime warnings on Node.js 10.x and above._

That was done by design. I first considered changing `safe-buffer`, prohibiting old API usage or
emitting warnings on it, but that significantly diverges from `safe-buffer` design. After some
discussion, it was decided to move my approach into a separate package, and _this is that separate
package_.

This footgun is not imaginary — I observed top-downloaded packages doing that kind of thing,
«fixing» the lint warning by blindly including `safe-buffer` without any actual changes.

Also in some cases, even if the API _was_ migrated to use of safe Buffer API — a random pull request
can bring unsafe Buffer API usage back to the codebase by adding new calls — and that could go
unnoticed even if you have a linter prohibiting that (becase of the reason stated above), and even
pass CI. _I also observed that being done in popular packages._

Some examples:
 * [webdriverio](https://github.com/webdriverio/webdriverio/commit/05cbd3167c12e4930f09ef7cf93b127ba4effae4#diff-124380949022817b90b622871837d56cR31)
   (a module with 548 759 downloads/month),
 * [websocket-stream](https://github.com/maxogden/websocket-stream/commit/c9312bd24d08271687d76da0fe3c83493871cf61)
   (218 288 d/m, fix in [maxogden/websocket-stream#142](https://github.com/maxogden/websocket-stream/pull/142)),
 * [node-serialport](https://github.com/node-serialport/node-serialport/commit/e8d9d2b16c664224920ce1c895199b1ce2def48c)
   (113 138 d/m, fix in [node-serialport/node-serialport#1510](https://github.com/node-serialport/node-serialport/pull/1510)),
 * [karma](https://github.com/karma-runner/karma/commit/3d94b8cf18c695104ca195334dc75ff054c74eec)
   (3 973 193 d/m, fix in [karma-runner/karma#2947](https://github.com/karma-runner/karma/pull/2947)),
 * [spdy-transport](https://github.com/spdy-http2/spdy-transport/commit/5375ac33f4a62a4f65bcfc2827447d42a5dbe8b1)
   (5 970 727 d/m, fix in [spdy-http2/spdy-transport#53](https://github.com/spdy-http2/spdy-transport/pull/53)).
 * And there are a lot more over the ecosystem.

I filed a PR at
[mysticatea/eslint-plugin-node#110](https://github.com/mysticatea/eslint-plugin-node/pull/110) to
partially fix that (for cases when that lint rule is used), but it is a semver-major change for
linter rules and presets, so it would take significant time for that to reach actual setups.
_It also hasn't been released yet (2018-03-20)._

Also, `safer-buffer` discourages the usage of `.allocUnsafe()`, which is often done by a mistake.
It still supports it with an explicit concern barier, by placing it under
`require('safer-buffer/dangereous')`.

## But isn't throwing bad?

Not really. It's an error that could be noticed and fixed early, instead of causing havoc later like
unguarded `new Buffer()` calls that end up receiving user input can do.

This package affects only the files where `var Buffer = require('safer-buffer').Buffer` was done, so
it is really simple to keep track of things and make sure that you don't mix old API usage with that.
Also, CI should hint anything that you might have missed.

New commits, if tested, won't land new usage of unsafe Buffer API this way.
_Node.js 10.x also deals with that by printing a runtime depecation warning._

### Would it affect third-party modules?

No, unless you explicitly do an awful thing like monkey-patching or overriding the built-in `Buffer`.
Don't do that.

### But I don't want throwing…

That is also fine!

Also, it could be better in some cases when you don't comprehensive enough test coverage.

In that case — just don't override `Buffer` and use
`var SaferBuffer = require('safer-buffer').Buffer` instead.

That way, everything using `Buffer` natively would still work, but there would be two drawbacks:

* `Buffer.from`/`Buffer.alloc` won't be polyfilled — use `SaferBuffer.from` and
  `SaferBuffer.alloc` instead.
* You are still open to accidentally using the insecure deprecated API — use a linter to catch that.

Note that using a linter to catch accidential `Buffer` constructor usage in this case is strongly
recommended. `Buffer` is not overriden in this usecase, so linters won't get confused.

## «Without footguns»?

Well, it is still possible to do _some_ things with `Buffer` API, e.g. accessing `.buffer` property
on older versions and duping things from there. You shouldn't do that in your code, probabably.

The intention is to remove the most significant footguns that affect lots of packages in the
ecosystem, and to do it in the proper way.

Also, this package doesn't protect against security issues affecting some Node.js versions, so for
usage in your own production code, it is still recommended to update to a Node.js version
[supported by upstream](https://github.com/nodejs/release#release-schedule).


---

# sax js

A sax-style parser for XML and HTML.

Designed with [node](http://nodejs.org/) in mind, but should work fine in
the browser or other CommonJS implementations.

## What This Is

* A very simple tool to parse through an XML string.
* A stepping stone to a streaming HTML parser.
* A handy way to deal with RSS and other mostly-ok-but-kinda-broken XML
  docs.

## What This Is (probably) Not

* An HTML Parser - That's a fine goal, but this isn't it.  It's just
  XML.
* A DOM Builder - You can use it to build an object model out of XML,
  but it doesn't do that out of the box.
* XSLT - No DOM = no querying.
* 100% Compliant with (some other SAX implementation) - Most SAX
  implementations are in Java and do a lot more than this does.
* An XML Validator - It does a little validation when in strict mode, but
  not much.
* A Schema-Aware XSD Thing - Schemas are an exercise in fetishistic
  masochism.
* A DTD-aware Thing - Fetching DTDs is a much bigger job.

## Regarding `<!DOCTYPE`s and `<!ENTITY`s

The parser will handle the basic XML entities in text nodes and attribute
values: `&amp; &lt; &gt; &apos; &quot;`. It's possible to define additional
entities in XML by putting them in the DTD. This parser doesn't do anything
with that. If you want to listen to the `ondoctype` event, and then fetch
the doctypes, and read the entities and add them to `parser.ENTITIES`, then
be my guest.

Unknown entities will fail in strict mode, and in loose mode, will pass
through unmolested.

## Usage

```javascript
var sax = require("./lib/sax"),
  strict = true, // set to false for html-mode
  parser = sax.parser(strict);

parser.onerror = function (e) {
  // an error happened.
};
parser.ontext = function (t) {
  // got some text.  t is the string of text.
};
parser.onopentag = function (node) {
  // opened a tag.  node has "name" and "attributes"
};
parser.onattribute = function (attr) {
  // an attribute.  attr has "name" and "value"
};
parser.onend = function () {
  // parser stream is done, and ready to have more stuff written to it.
};

parser.write('<xml>Hello, <who name="world">world</who>!</xml>').close();

// stream usage
// takes the same options as the parser
var saxStream = require("sax").createStream(strict, options)
saxStream.on("error", function (e) {
  // unhandled errors will throw, since this is a proper node
  // event emitter.
  console.error("error!", e)
  // clear the error
  this._parser.error = null
  this._parser.resume()
})
saxStream.on("opentag", function (node) {
  // same object as above
})
// pipe is supported, and it's readable/writable
// same chunks coming in also go out.
fs.createReadStream("file.xml")
  .pipe(saxStream)
  .pipe(fs.createWriteStream("file-copy.xml"))
```


## Arguments

Pass the following arguments to the parser function.  All are optional.

`strict` - Boolean. Whether or not to be a jerk. Default: `false`.

`opt` - Object bag of settings regarding string formatting.  All default to `false`.

Settings supported:

* `trim` - Boolean. Whether or not to trim text and comment nodes.
* `normalize` - Boolean. If true, then turn any whitespace into a single
  space.
* `lowercase` - Boolean. If true, then lowercase tag names and attribute names
  in loose mode, rather than uppercasing them.
* `xmlns` - Boolean. If true, then namespaces are supported.
* `position` - Boolean. If false, then don't track line/col/position.
* `strictEntities` - Boolean. If true, only parse [predefined XML
  entities](http://www.w3.org/TR/REC-xml/#sec-predefined-ent)
  (`&amp;`, `&apos;`, `&gt;`, `&lt;`, and `&quot;`)
* `unquotedAttributeValues` - Boolean. If true, then unquoted
  attribute values are allowed. Defaults to `false` when `strict`
  is true, `true` otherwise.

## Methods

`write` - Write bytes onto the stream. You don't have to do this all at
once. You can keep writing as much as you want.

`close` - Close the stream. Once closed, no more data may be written until
it is done processing the buffer, which is signaled by the `end` event.

`resume` - To gracefully handle errors, assign a listener to the `error`
event. Then, when the error is taken care of, you can call `resume` to
continue parsing. Otherwise, the parser will not continue while in an error
state.

## Members

At all times, the parser object will have the following members:

`line`, `column`, `position` - Indications of the position in the XML
document where the parser currently is looking.

`startTagPosition` - Indicates the position where the current tag starts.

`closed` - Boolean indicating whether or not the parser can be written to.
If it's `true`, then wait for the `ready` event to write again.

`strict` - Boolean indicating whether or not the parser is a jerk.

`opt` - Any options passed into the constructor.

`tag` - The current tag being dealt with.

And a bunch of other stuff that you probably shouldn't touch.

## Events

All events emit with a single argument. To listen to an event, assign a
function to `on<eventname>`. Functions get executed in the this-context of
the parser object. The list of supported events are also in the exported
`EVENTS` array.

When using the stream interface, assign handlers using the EventEmitter
`on` function in the normal fashion.

`error` - Indication that something bad happened. The error will be hanging
out on `parser.error`, and must be deleted before parsing can continue. By
listening to this event, you can keep an eye on that kind of stuff. Note:
this happens *much* more in strict mode. Argument: instance of `Error`.

`text` - Text node. Argument: string of text.

`doctype` - The `<!DOCTYPE` declaration. Argument: doctype string.

`processinginstruction` - Stuff like `<?xml foo="blerg" ?>`. Argument:
object with `name` and `body` members. Attributes are not parsed, as
processing instructions have implementation dependent semantics.

`sgmldeclaration` - Random SGML declarations. Stuff like `<!ENTITY p>`
would trigger this kind of event. This is a weird thing to support, so it
might go away at some point. SAX isn't intended to be used to parse SGML,
after all.

`opentagstart` - Emitted immediately when the tag name is available,
but before any attributes are encountered.  Argument: object with a
`name` field and an empty `attributes` set.  Note that this is the
same object that will later be emitted in the `opentag` event.

`opentag` - An opening tag. Argument: object with `name` and `attributes`.
In non-strict mode, tag names are uppercased, unless the `lowercase`
option is set.  If the `xmlns` option is set, then it will contain
namespace binding information on the `ns` member, and will have a
`local`, `prefix`, and `uri` member.

`closetag` - A closing tag. In loose mode, tags are auto-closed if their
parent closes. In strict mode, well-formedness is enforced. Note that
self-closing tags will have `closeTag` emitted immediately after `openTag`.
Argument: tag name.

`attribute` - An attribute node.  Argument: object with `name` and `value`.
In non-strict mode, attribute names are uppercased, unless the `lowercase`
option is set.  If the `xmlns` option is set, it will also contains namespace
information.

`comment` - A comment node.  Argument: the string of the comment.

`opencdata` - The opening tag of a `<![CDATA[` block.

`cdata` - The text of a `<![CDATA[` block. Since `<![CDATA[` blocks can get
quite large, this event may fire multiple times for a single block, if it
is broken up into multiple `write()`s. Argument: the string of random
character data.

`closecdata` - The closing tag (`]]>`) of a `<![CDATA[` block.

`opennamespace` - If the `xmlns` option is set, then this event will
signal the start of a new namespace binding.

`closenamespace` - If the `xmlns` option is set, then this event will
signal the end of a namespace binding.

`end` - Indication that the closed stream has ended.

`ready` - Indication that the stream has reset, and is ready to be written
to.

`noscript` - In non-strict mode, `<script>` tags trigger a `"script"`
event, and their contents are not checked for special xml characters.
If you pass `noscript: true`, then this behavior is suppressed.

## Reporting Problems

It's best to write a failing test if you find an issue.  I will always
accept pull requests with failing tests if they demonstrate intended
behavior, but it is very hard to figure out what issue you're describing
without a test.  Writing a test is also the best way for you yourself
to figure out if you really understand the issue you think you have with
sax-js.


---

# `scheduler`

This is a package for cooperative scheduling in a browser environment. It is currently used internally by React, but we plan to make it more generic.

The public API for this package is not yet finalized.

### Thanks

The React team thanks [Anton Podviaznikov](https://podviaznikov.com/) for donating the `scheduler` package name.


---

<div align="center">
  <a href="http://json-schema.org">
    <img width="160" height="160"
      src="https://raw.githubusercontent.com/webpack-contrib/schema-utils/master/.github/assets/logo.png">
  </a>
  <a href="https://github.com/webpack/webpack">
    <img width="200" height="200"
      src="https://webpack.js.org/assets/icon-square-big.svg">
  </a>
</div>

[![npm][npm]][npm-url]
[![node][node]][node-url]
[![tests][tests]][tests-url]
[![coverage][cover]][cover-url]
[![GitHub Discussions][discussion]][discussion-url]
[![size][size]][size-url]

# schema-utils

Package for validate options in loaders and plugins.

## Getting Started

To begin, you'll need to install `schema-utils`:

```console
npm install schema-utils
```

## API

**schema.json**

```json
{
  "type": "object",
  "properties": {
    "option": {
      "type": "boolean"
    }
  },
  "additionalProperties": false
}
```

```js
import schema from "./path/to/schema.json";
import { validate } from "schema-utils";

const options = { option: true };
const configuration = { name: "Loader Name/Plugin Name/Name" };

validate(schema, options, configuration);
```

### `schema`

Type: `String`

JSON schema.

Simple example of schema:

```json
{
  "type": "object",
  "properties": {
    "name": {
      "description": "This is description of option.",
      "type": "string"
    }
  },
  "additionalProperties": false
}
```

### `options`

Type: `Object`

Object with options.

```js
import schema from "./path/to/schema.json";
import { validate } from "schema-utils";

const options = { foo: "bar" };

validate(schema, { name: 123 }, { name: "MyPlugin" });
```

### `configuration`

Allow to configure validator.

There is an alternative method to configure the `name` and`baseDataPath` options via the `title` property in the schema.
For example:

```json
{
  "title": "My Loader options",
  "type": "object",
  "properties": {
    "name": {
      "description": "This is description of option.",
      "type": "string"
    }
  },
  "additionalProperties": false
}
```

The last word used for the `baseDataPath` option, other words used for the `name` option.
Based on the example above the `name` option equals `My Loader`, the `baseDataPath` option equals `options`.

#### `name`

Type: `Object`
Default: `"Object"`

Allow to setup name in validation errors.

```js
import schema from "./path/to/schema.json";
import { validate } from "schema-utils";

const options = { foo: "bar" };

validate(schema, options, { name: "MyPlugin" });
```

```shell
Invalid configuration object. MyPlugin has been initialised using a configuration object that does not match the API schema.
 - configuration.optionName should be a integer.
```

#### `baseDataPath`

Type: `String`
Default: `"configuration"`

Allow to setup base data path in validation errors.

```js
import schema from "./path/to/schema.json";
import { validate } from "schema-utils";

const options = { foo: "bar" };

validate(schema, options, { name: "MyPlugin", baseDataPath: "options" });
```

```shell
Invalid options object. MyPlugin has been initialised using an options object that does not match the API schema.
 - options.optionName should be a integer.
```

#### `postFormatter`

Type: `Function`
Default: `undefined`

Allow to reformat errors.

```js
import schema from "./path/to/schema.json";
import { validate } from "schema-utils";

const options = { foo: "bar" };

validate(schema, options, {
  name: "MyPlugin",
  postFormatter: (formattedError, error) => {
    if (error.keyword === "type") {
      return `${formattedError}\nAdditional Information.`;
    }

    return formattedError;
  },
});
```

```shell
Invalid options object. MyPlugin has been initialized using an options object that does not match the API schema.
 - options.optionName should be a integer.
   Additional Information.
```

## Examples

**schema.json**

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "test": {
      "anyOf": [
        { "type": "array" },
        { "type": "string" },
        { "instanceof": "RegExp" }
      ]
    },
    "transform": {
      "instanceof": "Function"
    },
    "sourceMap": {
      "type": "boolean"
    }
  },
  "additionalProperties": false
}
```

### `Loader`

```js
import { getOptions } from "loader-utils";
import { validate } from "schema-utils";

import schema from "path/to/schema.json";

function loader(src, map) {
  const options = getOptions(this);

  validate(schema, options, {
    name: "Loader Name",
    baseDataPath: "options",
  });

  // Code...
}

export default loader;
```

### `Plugin`

```js
import { validate } from "schema-utils";

import schema from "path/to/schema.json";

class Plugin {
  constructor(options) {
    validate(schema, options, {
      name: "Plugin Name",
      baseDataPath: "options",
    });

    this.options = options;
  }

  apply(compiler) {
    // Code...
  }
}

export default Plugin;
```

### Allow to disable and enable validation (the `validate` function do nothing)

This can be useful when you don't want to do validation for `production` builds.

```js
import { disableValidation, enableValidation, validate } from "schema-utils";

// Disable validation
disableValidation();
// Do nothing
validate(schema, options);

// Enable validation
enableValidation();
// Will throw an error if schema is not valid
validate(schema, options);

// Allow to undestand do you need validation or not
const need = needValidate();

console.log(need);
```

Also you can enable/disable validation using the `process.env.SKIP_VALIDATION` env variable.

Supported values (case insensitive):

- `yes`/`y`/`true`/`1`/`on`
- `no`/`n`/`false`/`0`/`off`

## Contributing

Please take a moment to read our contributing guidelines if you haven't yet done so.

[CONTRIBUTING](./.github/CONTRIBUTING.md)

## License

[MIT](./LICENSE)

[npm]: https://img.shields.io/npm/v/schema-utils.svg
[npm-url]: https://npmjs.com/package/schema-utils
[node]: https://img.shields.io/node/v/schema-utils.svg
[node-url]: https://nodejs.org
[tests]: https://github.com/webpack/schema-utils/workflows/schema-utils/badge.svg
[tests-url]: https://github.com/webpack/schema-utils/actions
[cover]: https://codecov.io/gh/webpack/schema-utils/branch/master/graph/badge.svg
[cover-url]: https://codecov.io/gh/webpack/schema-utils
[discussion]: https://img.shields.io/github/discussions/webpack/webpack
[discussion-url]: https://github.com/webpack/webpack/discussions
[size]: https://packagephobia.com/badge?p=schema-utils
[size-url]: https://packagephobia.com/result?p=schema-utils


---

<img align="right" alt="Ajv logo" width="160" src="https://ajv.js.org/img/ajv.svg">

&nbsp;

# Ajv JSON schema validator

The fastest JSON validator for Node.js and browser.

Supports JSON Schema draft-04/06/07/2019-09/2020-12 ([draft-04 support](https://ajv.js.org/json-schema.html#draft-04) requires ajv-draft-04 package) and JSON Type Definition [RFC8927](https://datatracker.ietf.org/doc/rfc8927/).

[![build](https://github.com/ajv-validator/ajv/actions/workflows/build.yml/badge.svg)](https://github.com/ajv-validator/ajv/actions?query=workflow%3Abuild)
[![npm](https://img.shields.io/npm/v/ajv.svg)](https://www.npmjs.com/package/ajv)
[![npm downloads](https://img.shields.io/npm/dm/ajv.svg)](https://www.npmjs.com/package/ajv)
[![Coverage Status](https://coveralls.io/repos/github/ajv-validator/ajv/badge.svg?branch=master)](https://coveralls.io/github/ajv-validator/ajv?branch=master)
[![SimpleX](https://img.shields.io/badge/chat-on%20SimpleX-70F0F9)](https://simplex.chat/contact#/?v=1-2&smp=smp%3A%2F%2Fu2dS9sG8nMNURyZwqASV4yROM28Er0luVTx5X1CsMrU%3D%40smp4.simplex.im%2F8KvvURM6J38Gdq9dCuPswMOkMny0xCOJ%23%2F%3Fv%3D1-2%26dh%3DMCowBQYDK2VuAyEAr8rPVRuMOXv6kwF2yUAap-eoVg-9ssOFCi1fIrxTUw0%253D%26srv%3Do5vmywmrnaxalvz6wi3zicyftgio6psuvyniis6gco6bp6ekl4cqj4id.onion&data=%7B%22type%22%3A%22group%22%2C%22groupLinkId%22%3A%224pwLRgWHU9tlroMWHz0uOg%3D%3D%22%7D)
[![Gitter](https://img.shields.io/gitter/room/ajv-validator/ajv.svg)](https://gitter.im/ajv-validator/ajv)
[![GitHub Sponsors](https://img.shields.io/badge/$-sponsors-brightgreen)](https://github.com/sponsors/epoberezkin)

## Ajv sponsors

[<img src="https://ajv.js.org/img/mozilla.svg" width="45%" alt="Mozilla">](https://www.mozilla.org)<img src="https://ajv.js.org/img/gap.svg" width="9%">[<img src="https://ajv.js.org/img/reserved.svg" width="45%">](https://opencollective.com/ajv)

[<img src="https://ajv.js.org/img/microsoft.png" width="31%" alt="Microsoft">](https://opensource.microsoft.com)<img src="https://ajv.js.org/img/gap.svg" width="3%">[<img src="https://ajv.js.org/img/reserved.svg" width="31%">](https://opencollective.com/ajv)<img src="https://ajv.js.org/img/gap.svg" width="3%">[<img src="https://ajv.js.org/img/reserved.svg" width="31%">](https://opencollective.com/ajv)

[<img src="https://ajv.js.org/img/retool.svg" width="22.5%" alt="Retool">](https://retool.com/?utm_source=sponsor&utm_campaign=ajv)<img src="https://ajv.js.org/img/gap.svg" width="3%">[<img src="https://ajv.js.org/img/tidelift.svg" width="22.5%" alt="Tidelift">](https://tidelift.com/subscription/pkg/npm-ajv?utm_source=npm-ajv&utm_medium=referral&utm_campaign=enterprise)<img src="https://ajv.js.org/img/gap.svg" width="3%">[<img src="https://ajv.js.org/img/simplex.svg" width="22.5%" alt="SimpleX">](https://github.com/simplex-chat/simplex-chat)<img src="https://ajv.js.org/img/gap.svg" width="3%">[<img src="https://ajv.js.org/img/reserved.svg" width="22.5%">](https://opencollective.com/ajv)

## Contributing

More than 100 people contributed to Ajv, and we would love to have you join the development. We welcome implementing new features that will benefit many users and ideas to improve our documentation.

Please review [Contributing guidelines](./CONTRIBUTING.md) and [Code components](https://ajv.js.org/components.html).

## Documentation

All documentation is available on the [Ajv website](https://ajv.js.org).

Some useful site links:

- [Getting started](https://ajv.js.org/guide/getting-started.html)
- [JSON Schema vs JSON Type Definition](https://ajv.js.org/guide/schema-language.html)
- [API reference](https://ajv.js.org/api.html)
- [Strict mode](https://ajv.js.org/strict-mode.html)
- [Standalone validation code](https://ajv.js.org/standalone.html)
- [Security considerations](https://ajv.js.org/security.html)
- [Command line interface](https://ajv.js.org/packages/ajv-cli.html)
- [Frequently Asked Questions](https://ajv.js.org/faq.html)

## <a name="sponsors"></a>Please [sponsor Ajv development](https://github.com/sponsors/epoberezkin)

Since I asked to support Ajv development 40 people and 6 organizations contributed via GitHub and OpenCollective - this support helped receiving the MOSS grant!

Your continuing support is very important - the funds will be used to develop and maintain Ajv once the next major version is released.

Please sponsor Ajv via:

- [GitHub sponsors page](https://github.com/sponsors/epoberezkin) (GitHub will match it)
- [Ajv Open Collective](https://opencollective.com/ajv)

Thank you.

#### Open Collective sponsors

<a href="https://opencollective.com/ajv"><img src="https://opencollective.com/ajv/individuals.svg?width=890"></a>

<a href="https://opencollective.com/ajv/organization/0/website"><img src="https://opencollective.com/ajv/organization/0/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/1/website"><img src="https://opencollective.com/ajv/organization/1/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/2/website"><img src="https://opencollective.com/ajv/organization/2/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/3/website"><img src="https://opencollective.com/ajv/organization/3/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/4/website"><img src="https://opencollective.com/ajv/organization/4/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/5/website"><img src="https://opencollective.com/ajv/organization/5/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/6/website"><img src="https://opencollective.com/ajv/organization/6/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/7/website"><img src="https://opencollective.com/ajv/organization/7/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/8/website"><img src="https://opencollective.com/ajv/organization/8/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/9/website"><img src="https://opencollective.com/ajv/organization/9/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/10/website"><img src="https://opencollective.com/ajv/organization/10/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/11/website"><img src="https://opencollective.com/ajv/organization/11/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/12/website"><img src="https://opencollective.com/ajv/organization/12/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/13/website"><img src="https://opencollective.com/ajv/organization/13/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/14/website"><img src="https://opencollective.com/ajv/organization/14/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/15/website"><img src="https://opencollective.com/ajv/organization/15/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/16/website"><img src="https://opencollective.com/ajv/organization/16/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/17/website"><img src="https://opencollective.com/ajv/organization/17/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/18/website"><img src="https://opencollective.com/ajv/organization/18/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/19/website"><img src="https://opencollective.com/ajv/organization/19/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/20/website"><img src="https://opencollective.com/ajv/organization/20/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/21/website"><img src="https://opencollective.com/ajv/organization/21/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/22/website"><img src="https://opencollective.com/ajv/organization/22/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/23/website"><img src="https://opencollective.com/ajv/organization/23/avatar.svg"></a>
<a href="https://opencollective.com/ajv/organization/24/website"><img src="https://opencollective.com/ajv/organization/24/avatar.svg"></a>

## Performance

Ajv generates code to turn JSON Schemas into super-fast validation functions that are efficient for v8 optimization.

Currently Ajv is the fastest and the most standard compliant validator according to these benchmarks:

- [json-schema-benchmark](https://github.com/ebdrup/json-schema-benchmark) - 50% faster than the second place
- [jsck benchmark](https://github.com/pandastrike/jsck#benchmarks) - 20-190% faster
- [z-schema benchmark](https://rawgit.com/zaggino/z-schema/master/benchmark/results.html)
- [themis benchmark](https://cdn.rawgit.com/playlyfe/themis/master/benchmark/results.html)

Performance of different validators by [json-schema-benchmark](https://github.com/ebdrup/json-schema-benchmark):

[![performance](https://chart.googleapis.com/chart?chxt=x,y&cht=bhs&chco=76A4FB&chls=2.0&chbh=62,4,1&chs=600x416&chxl=-1:|ajv|@exodus/schemasafe|is-my-json-valid|djv|@cfworker/json-schema|jsonschema/=t:100,69.2,51.5,13.1,5.1,1.2)](https://github.com/ebdrup/json-schema-benchmark/blob/master/README.md#performance)

## Features

- Ajv implements JSON Schema [draft-06/07/2019-09/2020-12](http://json-schema.org/) standards (draft-04 is supported in v6):
  - all validation keywords (see [JSON Schema validation keywords](https://ajv.js.org/json-schema.html))
  - [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md) extensions:
    - NEW: keyword [discriminator](https://ajv.js.org/json-schema.html#discriminator).
    - keyword [nullable](https://ajv.js.org/json-schema.html#nullable).
  - full support of remote references (remote schemas have to be added with `addSchema` or compiled to be available)
  - support of recursive references between schemas
  - correct string lengths for strings with unicode pairs
  - JSON Schema [formats](https://ajv.js.org/guide/formats.html) (with [ajv-formats](https://github.com/ajv-validator/ajv-formats) plugin).
  - [validates schemas against meta-schema](https://ajv.js.org/api.html#api-validateschema)
- NEW: supports [JSON Type Definition](https://datatracker.ietf.org/doc/rfc8927/):
  - all keywords (see [JSON Type Definition schema forms](https://ajv.js.org/json-type-definition.html))
  - meta-schema for JTD schemas
  - "union" keyword and user-defined keywords (can be used inside "metadata" member of the schema)
- supports [browsers](https://ajv.js.org/guide/environments.html#browsers) and Node.js 10.x - current
- [asynchronous loading](https://ajv.js.org/guide/managing-schemas.html#asynchronous-schema-loading) of referenced schemas during compilation
- "All errors" validation mode with [option allErrors](https://ajv.js.org/options.html#allerrors)
- [error messages with parameters](https://ajv.js.org/api.html#validation-errors) describing error reasons to allow error message generation
- i18n error messages support with [ajv-i18n](https://github.com/ajv-validator/ajv-i18n) package
- [removing-additional-properties](https://ajv.js.org/guide/modifying-data.html#removing-additional-properties)
- [assigning defaults](https://ajv.js.org/guide/modifying-data.html#assigning-defaults) to missing properties and items
- [coercing data](https://ajv.js.org/guide/modifying-data.html#coercing-data-types) to the types specified in `type` keywords
- [user-defined keywords](https://ajv.js.org/guide/user-keywords.html)
- additional extension keywords with [ajv-keywords](https://github.com/ajv-validator/ajv-keywords) package
- [\$data reference](https://ajv.js.org/guide/combining-schemas.html#data-reference) to use values from the validated data as values for the schema keywords
- [asynchronous validation](https://ajv.js.org/guide/async-validation.html) of user-defined formats and keywords

## Install

To install version 8:

```
npm install ajv
```

## <a name="usage"></a>Getting started

Try it in the Node.js REPL: https://runkit.com/npm/ajv

In JavaScript:

```javascript
// or ESM/TypeScript import
import Ajv from "ajv"
// Node.js require:
const Ajv = require("ajv")

const ajv = new Ajv() // options can be passed, e.g. {allErrors: true}

const schema = {
  type: "object",
  properties: {
    foo: {type: "integer"},
    bar: {type: "string"},
  },
  required: ["foo"],
  additionalProperties: false,
}

const data = {
  foo: 1,
  bar: "abc",
}

const validate = ajv.compile(schema)
const valid = validate(data)
if (!valid) console.log(validate.errors)
```

Learn how to use Ajv and see more examples in the [Guide: getting started](https://ajv.js.org/guide/getting-started.html)

## Changes history

See [https://github.com/ajv-validator/ajv/releases](https://github.com/ajv-validator/ajv/releases)

**Please note**: [Changes in version 8.0.0](https://github.com/ajv-validator/ajv/releases/tag/v8.0.0)

[Version 7.0.0](https://github.com/ajv-validator/ajv/releases/tag/v7.0.0)

[Version 6.0.0](https://github.com/ajv-validator/ajv/releases/tag/v6.0.0).

## Code of conduct

Please review and follow the [Code of conduct](./CODE_OF_CONDUCT.md).

Please report any unacceptable behaviour to ajv.validator@gmail.com - it will be reviewed by the project team.

## Security contact

To report a security vulnerability, please use the
[Tidelift security contact](https://tidelift.com/security).
Tidelift will coordinate the fix and disclosure. Please do NOT report security vulnerabilities via GitHub issues.

## Open-source software support

Ajv is a part of [Tidelift subscription](https://tidelift.com/subscription/pkg/npm-ajv?utm_source=npm-ajv&utm_medium=referral&utm_campaign=readme) - it provides a centralised support to open-source software users, in addition to the support provided by software maintainers.

## License

[MIT](./LICENSE)


---

# ajv-keywords

Custom JSON-Schema keywords for [Ajv](https://github.com/epoberezkin/ajv) validator

[![build](https://github.com/ajv-validator/ajv-keywords/workflows/build/badge.svg)](https://github.com/ajv-validator/ajv-keywords/actions?query=workflow%3Abuild)
[![npm](https://img.shields.io/npm/v/ajv-keywords.svg)](https://www.npmjs.com/package/ajv-keywords)
[![npm downloads](https://img.shields.io/npm/dm/ajv-keywords.svg)](https://www.npmjs.com/package/ajv-keywords)
[![coverage](https://coveralls.io/repos/github/ajv-validator/ajv-keywords/badge.svg?branch=master)](https://coveralls.io/github/ajv-validator/ajv-keywords?branch=master)
[![gitter](https://img.shields.io/gitter/room/ajv-validator/ajv.svg)](https://gitter.im/ajv-validator/ajv)

**Please note**: This readme file is for [ajv-keywords v5.0.0](https://github.com/ajv-validator/ajv-keywords/releases/tag/v5.0.0) that should be used with [ajv v8](https://github.com/ajv-validator/ajv).

[ajv-keywords v3](https://github.com/ajv-validator/ajv-keywords/tree/v3) should be used with [ajv v6](https://github.com/ajv-validator/ajv/tree/v6).

## Contents

- [Install](#install)
- [Usage](#usage)
- [Keywords](#keywords)
  - [Types](#types)
    - [typeof](#typeof)
    - [instanceof](#instanceof)<sup>\+</sup>
  - [Keywords for numbers](#keywords-for-numbers)
    - [range and exclusiveRange](#range-and-exclusiverange)
  - [Keywords for strings](#keywords-for-strings)
    - [regexp](#regexp)
    - [transform](#transform)<sup>\*</sup>
  - [Keywords for arrays](#keywords-for-arrays)
    - [uniqueItemProperties](#uniqueitemproperties)<sup>\+</sup>
  - [Keywords for objects](#keywords-for-objects)
    - [allRequired](#allrequired)
    - [anyRequired](#anyrequired)
    - [oneRequired](#onerequired)
    - [patternRequired](#patternrequired)
    - [prohibited](#prohibited)
    - [deepProperties](#deepproperties)
    - [deepRequired](#deeprequired)
    - [dynamicDefaults](#dynamicdefaults)<sup>\*</sup><sup>\+</sup>
  - [Keywords for all types](#keywords-for-all-types)
    - [select/selectCases/selectDefault](#selectselectcasesselectdefault)
- [Security contact](#security-contact)
- [Open-source software support](#open-source-software-support)
- [License](#license)

<sup>\*</sup> - keywords that modify data
<sup>\+</sup> - keywords that are not supported in [standalone validation code](https://github.com/ajv-validator/ajv/blob/master/docs/standalone.md)

## Install

To install version 4 to use with [Ajv v7](https://github.com/ajv-validator/ajv):

```
npm install ajv-keywords
```

## Usage

To add all available keywords:

```javascript
const Ajv = require("ajv")
const ajv = new Ajv()
require("ajv-keywords")(ajv)

ajv.validate({instanceof: "RegExp"}, /.*/) // true
ajv.validate({instanceof: "RegExp"}, ".*") // false
```

To add a single keyword:

```javascript
require("ajv-keywords")(ajv, "instanceof")
```

To add multiple keywords:

```javascript
require("ajv-keywords")(ajv, ["typeof", "instanceof"])
```

To add a single keyword directly (to avoid adding unused code):

```javascript
require("ajv-keywords/dist/keywords/select")(ajv, opts)
```

To add all keywords via Ajv options:

```javascript
const ajv = new Ajv({keywords: require("ajv-keywords/dist/definitions")(opts)})
```

To add one or several keywords via options:

```javascript
const ajv = new Ajv({
  keywords: [
    require("ajv-keywords/dist/definitions/typeof")(),
    require("ajv-keywords/dist/definitions/instanceof")(),
    // select exports an array of 3 definitions - see "select" in docs
    ...require("ajv-keywords/dist/definitions/select")(opts),
  ],
})
```

`opts` is an optional object with a property `defaultMeta` - URI of meta-schema to use for keywords that use subschemas (`select` and `deepProperties`). The default is `"http://json-schema.org/schema"`.

## Keywords

### Types

#### `typeof`

Based on JavaScript `typeof` operation.

The value of the keyword should be a string (`"undefined"`, `"string"`, `"number"`, `"object"`, `"function"`, `"boolean"` or `"symbol"`) or an array of strings.

To pass validation the result of `typeof` operation on the value should be equal to the string (or one of the strings in the array).

```javascript
ajv.validate({typeof: "undefined"}, undefined) // true
ajv.validate({typeof: "undefined"}, null) // false
ajv.validate({typeof: ["undefined", "object"]}, null) // true
```

#### `instanceof`

Based on JavaScript `instanceof` operation.

The value of the keyword should be a string (`"Object"`, `"Array"`, `"Function"`, `"Number"`, `"String"`, `"Date"`, `"RegExp"` or `"Promise"`) or an array of strings.

To pass validation the result of `data instanceof ...` operation on the value should be true:

```javascript
ajv.validate({instanceof: "Array"}, []) // true
ajv.validate({instanceof: "Array"}, {}) // false
ajv.validate({instanceof: ["Array", "Function"]}, function () {}) // true
```

You can add your own constructor function to be recognised by this keyword:

```javascript
class MyClass {}
const instanceofDef = require("ajv-keywords/dist/definitions/instanceof")
instanceofDef.CONSTRUCTORS.MyClass = MyClass
ajv.validate({instanceof: "MyClass"}, new MyClass()) // true
```

**Please note**: currently `instanceof` is not supported in [standalone validation code](https://github.com/ajv-validator/ajv/blob/master/docs/standalone.md) - it has to be implemented as [`code` keyword](https://github.com/ajv-validator/ajv/blob/master/docs/keywords.md#define-keyword-with-code-generation-function) to support it (PR is welcome).

### Keywords for numbers

#### `range` and `exclusiveRange`

Syntax sugar for the combination of minimum and maximum keywords (or exclusiveMinimum and exclusiveMaximum), also fails schema compilation if there are no numbers in the range.

The value of these keywords must be an array consisting of two numbers, the second must be greater or equal than the first one.

If the validated value is not a number the validation passes, otherwise to pass validation the value should be greater (or equal) than the first number and smaller (or equal) than the second number in the array.

```javascript
const schema = {type: "number", range: [1, 3]}
ajv.validate(schema, 1) // true
ajv.validate(schema, 2) // true
ajv.validate(schema, 3) // true
ajv.validate(schema, 0.99) // false
ajv.validate(schema, 3.01) // false

const schema = {type: "number", exclusiveRange: [1, 3]}
ajv.validate(schema, 1.01) // true
ajv.validate(schema, 2) // true
ajv.validate(schema, 2.99) // true
ajv.validate(schema, 1) // false
ajv.validate(schema, 3) // false
```

### Keywords for strings

#### `regexp`

This keyword allows to use regular expressions with flags in schemas, and also without `"u"` flag when needed (the standard `pattern` keyword does not support flags and implies the presence of `"u"` flag).

This keyword applies only to strings. If the data is not a string, the validation succeeds.

The value of this keyword can be either a string (the result of `regexp.toString()`) or an object with the properties `pattern` and `flags` (the same strings that should be passed to RegExp constructor).

```javascript
const schema = {
  type: "object",
  properties: {
    foo: {type: "string", regexp: "/foo/i"},
    bar: {type: "string", regexp: {pattern: "bar", flags: "i"}},
  },
}

const validData = {
  foo: "Food",
  bar: "Barmen",
}

const invalidData = {
  foo: "fog",
  bar: "bad",
}
```

#### `transform`

This keyword allows a string to be modified during validation.

This keyword applies only to strings. If the data is not a string, the `transform` keyword is ignored.

A standalone string cannot be modified, i.e. `data = 'a'; ajv.validate(schema, data);`, because strings are passed by value

**Supported transformations:**

- `trim`: remove whitespace from start and end
- `trimStart`/`trimLeft`: remove whitespace from start
- `trimEnd`/`trimRight`: remove whitespace from end
- `toLowerCase`: convert to lower case
- `toUpperCase`: convert to upper case
- `toEnumCase`: change string case to be equal to one of `enum` values in the schema

Transformations are applied in the order they are listed.

Note: `toEnumCase` requires that all allowed values are unique when case insensitive.

**Example: multiple transformations**

```javascript
require("ajv-keywords")(ajv, "transform")

const schema = {
  type: "array",
  items: {
    type: "string",
    transform: ["trim", "toLowerCase"],
  },
}

const data = ["  MixCase  "]
ajv.validate(schema, data)
console.log(data) // ['mixcase']
```

**Example: `enumcase`**

```javascript
require("ajv-keywords")(ajv, ["transform"])

const schema = {
  type: "array",
  items: {
    type: "string",
    transform: ["trim", "toEnumCase"],
    enum: ["pH"],
  },
}

const data = ["ph", " Ph", "PH", "pH "]
ajv.validate(schema, data)
console.log(data) // ['pH','pH','pH','pH']
```

### Keywords for arrays

#### `uniqueItemProperties`

The keyword allows to check that some properties in array items are unique.

This keyword applies only to arrays. If the data is not an array, the validation succeeds.

The value of this keyword must be an array of strings - property names that should have unique values across all items.

```javascript
const schema = {
  type: "array",
  uniqueItemProperties: ["id", "name"],
}

const validData = [{id: 1}, {id: 2}, {id: 3}]

const invalidData1 = [
  {id: 1},
  {id: 1}, // duplicate "id"
  {id: 3},
]

const invalidData2 = [
  {id: 1, name: "taco"},
  {id: 2, name: "taco"}, // duplicate "name"
  {id: 3, name: "salsa"},
]
```

This keyword is contributed by [@blainesch](https://github.com/blainesch).

**Please note**: currently `uniqueItemProperties` is not supported in [standalone validation code](https://github.com/ajv-validator/ajv/blob/master/docs/standalone.md) - it has to be implemented as [`code` keyword](https://github.com/ajv-validator/ajv/blob/master/docs/keywords.md#define-keyword-with-code-generation-function) to support it (PR is welcome).

### Keywords for objects

#### `allRequired`

This keyword allows to require the presence of all properties used in `properties` keyword in the same schema object.

This keyword applies only to objects. If the data is not an object, the validation succeeds.

The value of this keyword must be boolean.

If the value of the keyword is `false`, the validation succeeds.

If the value of the keyword is `true`, the validation succeeds if the data contains all properties defined in `properties` keyword (in the same schema object).

If the `properties` keyword is not present in the same schema object, schema compilation will throw exception.

```javascript
const schema = {
  type: "object",
  properties: {
    foo: {type: "number"},
    bar: {type: "number"},
  },
  allRequired: true,
}

const validData = {foo: 1, bar: 2}
const alsoValidData = {foo: 1, bar: 2, baz: 3}

const invalidDataList = [{}, {foo: 1}, {bar: 2}]
```

#### `anyRequired`

This keyword allows to require the presence of any (at least one) property from the list.

This keyword applies only to objects. If the data is not an object, the validation succeeds.

The value of this keyword must be an array of strings, each string being a property name. For data object to be valid at least one of the properties in this array should be present in the object.

```javascript
const schema = {
  type: "object",
  anyRequired: ["foo", "bar"],
}

const validData = {foo: 1}
const alsoValidData = {foo: 1, bar: 2}

const invalidDataList = [{}, {baz: 3}]
```

#### `oneRequired`

This keyword allows to require the presence of only one property from the list.

This keyword applies only to objects. If the data is not an object, the validation succeeds.

The value of this keyword must be an array of strings, each string being a property name. For data object to be valid exactly one of the properties in this array should be present in the object.

```javascript
const schema = {
  type: "object",
  oneRequired: ["foo", "bar"],
}

const validData = {foo: 1}
const alsoValidData = {bar: 2, baz: 3}

const invalidDataList = [{}, {baz: 3}, {foo: 1, bar: 2}]
```

#### `patternRequired`

This keyword allows to require the presence of properties that match some pattern(s).

This keyword applies only to objects. If the data is not an object, the validation succeeds.

The value of this keyword should be an array of strings, each string being a regular expression. For data object to be valid each regular expression in this array should match at least one property name in the data object.

If the array contains multiple regular expressions, more than one expression can match the same property name.

```javascript
const schema = {
  type: "object",
  patternRequired: ["f.*o", "b.*r"],
}

const validData = {foo: 1, bar: 2}
const alsoValidData = {foobar: 3}

const invalidDataList = [{}, {foo: 1}, {bar: 2}]
```

#### `prohibited`

This keyword allows to prohibit that any of the properties in the list is present in the object.

This keyword applies only to objects. If the data is not an object, the validation succeeds.

The value of this keyword should be an array of strings, each string being a property name. For data object to be valid none of the properties in this array should be present in the object.

```javascript
const schema = {
  type: "object",
  prohibited: ["foo", "bar"],
}

const validData = {baz: 1}
const alsoValidData = {}

const invalidDataList = [{foo: 1}, {bar: 2}, {foo: 1, bar: 2}]
```

**Please note**: `{prohibited: ['foo', 'bar']}` is equivalent to `{not: {anyRequired: ['foo', 'bar']}}` (i.e. it has the same validation result for any data).

#### `deepProperties`

This keyword allows to validate deep properties (identified by JSON pointers).

This keyword applies only to objects. If the data is not an object, the validation succeeds.

The value should be an object, where keys are JSON pointers to the data, starting from the current position in data, and the values are JSON schemas. For data object to be valid the value of each JSON pointer should be valid according to the corresponding schema.

```javascript
const schema = {
  type: "object",
  deepProperties: {
    "/users/1/role": {enum: ["admin"]},
  },
}

const validData = {
  users: [
    {},
    {
      id: 123,
      role: "admin",
    },
  ],
}

const alsoValidData = {
  users: {
    1: {
      id: 123,
      role: "admin",
    },
  },
}

const invalidData = {
  users: [
    {},
    {
      id: 123,
      role: "user",
    },
  ],
}

const alsoInvalidData = {
  users: {
    1: {
      id: 123,
      role: "user",
    },
  },
}
```

#### `deepRequired`

This keyword allows to check that some deep properties (identified by JSON pointers) are available.

This keyword applies only to objects. If the data is not an object, the validation succeeds.

The value should be an array of JSON pointers to the data, starting from the current position in data. For data object to be valid each JSON pointer should be some existing part of the data.

```javascript
const schema = {
  type: "object",
  deepRequired: ["/users/1/role"],
}

const validData = {
  users: [
    {},
    {
      id: 123,
      role: "admin",
    },
  ],
}

const invalidData = {
  users: [
    {},
    {
      id: 123,
    },
  ],
}
```

See [json-schema-org/json-schema-spec#203](https://github.com/json-schema-org/json-schema-spec/issues/203#issue-197211916) for an example of the equivalent schema without `deepRequired` keyword.

### Keywords for all types

#### `select`/`selectCases`/`selectDefault`

**Please note**: these keywords are deprecated. It is recommended to use OpenAPI [discriminator](https://ajv.js.org/json-schema.html#discriminator) keyword supported by Ajv v8 instead of `select`.

These keywords allow to choose the schema to validate the data based on the value of some property in the validated data.

These keywords must be present in the same schema object (`selectDefault` is optional).

The value of `select` keyword should be a [\$data reference](https://github.com/ajv-validator/ajv/blob/master/docs/validation.md#data-reference) that points to any primitive JSON type (string, number, boolean or null) in the data that is validated. You can also use a constant of primitive type as the value of this keyword (e.g., for debugging purposes).

The value of `selectCases` keyword must be an object where each property name is a possible string representation of the value of `select` keyword and each property value is a corresponding schema (from draft-06 it can be boolean) that must be used to validate the data.

The value of `selectDefault` keyword is a schema (also can be boolean) that must be used to validate the data in case `selectCases` has no key equal to the stringified value of `select` keyword.

The validation succeeds in one of the following cases:

- the validation of data using selected schema succeeds,
- none of the schemas is selected for validation,
- the value of select is undefined (no property in the data that the data reference points to).

If `select` value (in data) is not a primitive type the validation fails.

This keyword correctly tracks evaluated properties and items to work with `unevaluatedProperties` and `unevaluatedItems` keywords - only properties and items from the subschema that was used (one of `selectCases` subschemas or `selectDefault` subschema) are marked as evaluated.

**Please note**: these keywords require Ajv `$data` option to support [\$data reference](https://github.com/ajv-validator/ajv/blob/master/docs/validation.md#data-reference).

```javascript
require("ajv-keywords")(ajv, "select")

const schema = {
  type: "object",
  required: ["kind"],
  properties: {
    kind: {type: "string"},
  },
  select: {$data: "0/kind"},
  selectCases: {
    foo: {
      required: ["foo"],
      properties: {
        kind: {},
        foo: {type: "string"},
      },
      additionalProperties: false,
    },
    bar: {
      required: ["bar"],
      properties: {
        kind: {},
        bar: {type: "number"},
      },
      additionalProperties: false,
    },
  },
  selectDefault: {
    propertyNames: {
      not: {enum: ["foo", "bar"]},
    },
  },
}

const validDataList = [
  {kind: "foo", foo: "any"},
  {kind: "bar", bar: 1},
  {kind: "anything_else", not_bar_or_foo: "any value"},
]

const invalidDataList = [
  {kind: "foo"}, // no property foo
  {kind: "bar"}, // no property bar
  {kind: "foo", foo: "any", another: "any value"}, // additional property
  {kind: "bar", bar: 1, another: "any value"}, // additional property
  {kind: "anything_else", foo: "any"}, // property foo not allowed
  {kind: "anything_else", bar: 1}, // property bar not allowed
]
```

#### `dynamicDefaults`

This keyword allows to assign dynamic defaults to properties, such as timestamps, unique IDs etc.

This keyword only works if `useDefaults` options is used and not inside `anyOf` keywords etc., in the same way as [default keyword treated by Ajv](https://github.com/epoberezkin/ajv#assigning-defaults).

The keyword should be added on the object level. Its value should be an object with each property corresponding to a property name, in the same way as in standard `properties` keyword. The value of each property can be:

- an identifier of dynamic default function (a string)
- an object with properties `func` (an identifier) and `args` (an object with parameters that will be passed to this function during schema compilation - see examples).

The properties used in `dynamicDefaults` should not be added to `required` keyword in the same schema (or validation will fail), because unlike `default` this keyword is processed after validation.

There are several predefined dynamic default functions:

- `"timestamp"` - current timestamp in milliseconds
- `"datetime"` - current date and time as string (ISO, valid according to `date-time` format)
- `"date"` - current date as string (ISO, valid according to `date` format)
- `"time"` - current time as string (ISO, valid according to `time` format)
- `"random"` - pseudo-random number in [0, 1) interval
- `"randomint"` - pseudo-random integer number. If string is used as a property value, the function will randomly return 0 or 1. If object `{ func: 'randomint', args: { max: N } }` is used then the default will be an integer number in [0, N) interval.
- `"seq"` - sequential integer number starting from 0. If string is used as a property value, the default sequence will be used. If object `{ func: 'seq', args: { name: 'foo'} }` is used then the sequence with name `"foo"` will be used. Sequences are global, even if different ajv instances are used.

```javascript
const schema = {
  type: "object",
  dynamicDefaults: {
    ts: "datetime",
    r: {func: "randomint", args: {max: 100}},
    id: {func: "seq", args: {name: "id"}},
  },
  properties: {
    ts: {
      type: "string",
      format: "date-time",
    },
    r: {
      type: "integer",
      minimum: 0,
      exclusiveMaximum: 100,
    },
    id: {
      type: "integer",
      minimum: 0,
    },
  },
}

const data = {}
ajv.validate(data) // true
data // { ts: '2016-12-01T22:07:28.829Z', r: 25, id: 0 }

const data1 = {}
ajv.validate(data1) // true
data1 // { ts: '2016-12-01T22:07:29.832Z', r: 68, id: 1 }

ajv.validate(data1) // true
data1 // didn't change, as all properties were defined
```

When using the `useDefaults` option value `"empty"`, properties and items equal to `null` or `""` (empty string) will be considered missing and assigned defaults. Use `allOf` [compound keyword](https://github.com/epoberezkin/ajv/blob/master/KEYWORDS.md#compound-keywords) to execute `dynamicDefaults` before validation.

```javascript
const schema = {
  type: "object",
  allOf: [
    {
      dynamicDefaults: {
        ts: "datetime",
        r: {func: "randomint", args: {min: 5, max: 100}},
        id: {func: "seq", args: {name: "id"}},
      },
    },
    {
      properties: {
        ts: {
          type: "string",
        },
        r: {
          type: "number",
          minimum: 5,
          exclusiveMaximum: 100,
        },
        id: {
          type: "integer",
          minimum: 0,
        },
      },
    },
  ],
}

const data = {ts: "", r: null}
ajv.validate(data) // true
data // { ts: '2016-12-01T22:07:28.829Z', r: 25, id: 0 }
```

You can add your own dynamic default function to be recognised by this keyword:

```javascript
const uuid = require("uuid")

const def = require("ajv-keywords/dist/definitions/dynamicDefaults")
def.DEFAULTS.uuid = () => uuid.v4

const schema = {
  dynamicDefaults: {id: "uuid"},
  properties: {id: {type: "string", format: "uuid"}},
}

const data = {}
ajv.validate(schema, data) // true
data // { id: 'a1183fbe-697b-4030-9bcc-cfeb282a9150' };

const data1 = {}
ajv.validate(schema, data1) // true
data1 // { id: '5b008de7-1669-467a-a5c6-70fa244d7209' }
```

You also can define dynamic default that accept parameters, e.g. version of uuid:

```javascript
const uuid = require("uuid")

function getUuid(args) {
  const version = "v" + ((arvs && args.v) || "4")
  return uuid[version]
}

const def = require("ajv-keywords/dist/definitions/dynamicDefaults")
def.DEFAULTS.uuid = getUuid

const schema = {
  dynamicDefaults: {
    id1: "uuid", // v4
    id2: {func: "uuid", v: 4}, // v4
    id3: {func: "uuid", v: 1}, // v1
  },
}
```

**Please note**: dynamic default functions are differentiated by the number of parameters they have (`function.length`). Functions that do not expect default must have one non-optional argument so that `function.length` > 0.

`dynamicDefaults` is not supported in [standalone validation code](https://github.com/ajv-validator/ajv/blob/master/docs/standalone.md).

## Security contact

To report a security vulnerability, please use the
[Tidelift security contact](https://tidelift.com/security).
Tidelift will coordinate the fix and disclosure.

Please do NOT report security vulnerabilities via GitHub issues.

## Open-source software support

Ajv-keywords is a part of [Tidelift subscription](https://tidelift.com/subscription/pkg/npm-ajv-keywords?utm_source=npm-ajv-keywords&utm_medium=referral&utm_campaign=readme) - it provides a centralised support to open-source software users, in addition to the support provided by software maintainers.

## License

[MIT](https://github.com/epoberezkin/ajv-keywords/blob/master/LICENSE)


---

# json-schema-traverse
Traverse JSON Schema passing each schema object to callback

[![build](https://github.com/epoberezkin/json-schema-traverse/workflows/build/badge.svg)](https://github.com/epoberezkin/json-schema-traverse/actions?query=workflow%3Abuild)
[![npm](https://img.shields.io/npm/v/json-schema-traverse)](https://www.npmjs.com/package/json-schema-traverse)
[![coverage](https://coveralls.io/repos/github/epoberezkin/json-schema-traverse/badge.svg?branch=master)](https://coveralls.io/github/epoberezkin/json-schema-traverse?branch=master)


## Install

```
npm install json-schema-traverse
```


## Usage

```javascript
const traverse = require('json-schema-traverse');
const schema = {
  properties: {
    foo: {type: 'string'},
    bar: {type: 'integer'}
  }
};

traverse(schema, {cb});
// cb is called 3 times with:
// 1. root schema
// 2. {type: 'string'}
// 3. {type: 'integer'}

// Or:

traverse(schema, {cb: {pre, post}});
// pre is called 3 times with:
// 1. root schema
// 2. {type: 'string'}
// 3. {type: 'integer'}
//
// post is called 3 times with:
// 1. {type: 'string'}
// 2. {type: 'integer'}
// 3. root schema

```

Callback function `cb` is called for each schema object (not including draft-06 boolean schemas), including the root schema, in pre-order traversal. Schema references ($ref) are not resolved, they are passed as is.  Alternatively, you can pass a `{pre, post}` object as `cb`, and then `pre` will be called before traversing child elements, and `post` will be called after all child elements have been traversed.

Callback is passed these parameters:

- _schema_: the current schema object
- _JSON pointer_: from the root schema to the current schema object
- _root schema_: the schema passed to `traverse` object
- _parent JSON pointer_: from the root schema to the parent schema object (see below)
- _parent keyword_: the keyword inside which this schema appears (e.g. `properties`, `anyOf`, etc.)
- _parent schema_: not necessarily parent object/array; in the example above the parent schema for `{type: 'string'}` is the root schema
- _index/property_: index or property name in the array/object containing multiple schemas; in the example above for `{type: 'string'}` the property name is `'foo'`


## Traverse objects in all unknown keywords

```javascript
const traverse = require('json-schema-traverse');
const schema = {
  mySchema: {
    minimum: 1,
    maximum: 2
  }
};

traverse(schema, {allKeys: true, cb});
// cb is called 2 times with:
// 1. root schema
// 2. mySchema
```

Without option `allKeys: true` callback will be called only with root schema.


## Enterprise support

json-schema-traverse package is a part of [Tidelift enterprise subscription](https://tidelift.com/subscription/pkg/npm-json-schema-traverse?utm_source=npm-json-schema-traverse&utm_medium=referral&utm_campaign=enterprise&utm_term=repo) - it provides a centralised commercial support to open-source software users, in addition to the support provided by software maintainers.


## Security contact

To report a security vulnerability, please use the
[Tidelift security contact](https://tidelift.com/security).
Tidelift will coordinate the fix and disclosure. Please do NOT report security vulnerability via GitHub issues.


## License

[MIT](https://github.com/epoberezkin/json-schema-traverse/blob/master/LICENSE)


---

# section-matter [![NPM version](https://img.shields.io/npm/v/section-matter.svg?style=flat)](https://www.npmjs.com/package/section-matter) [![NPM monthly downloads](https://img.shields.io/npm/dm/section-matter.svg?style=flat)](https://npmjs.org/package/section-matter) [![NPM total downloads](https://img.shields.io/npm/dt/section-matter.svg?style=flat)](https://npmjs.org/package/section-matter) [![Linux Build Status](https://img.shields.io/travis/jonschlinkert/section-matter.svg?style=flat&label=Travis)](https://travis-ci.org/jonschlinkert/section-matter) 

> Like front-matter, but supports multiple sections in a document.

Please consider following this project's author, [Jon Schlinkert](https://github.com/jonschlinkert), and consider starring the project to show your :heart: and support.

## Install
Install with [npm](https://www.npmjs.com/):

```sh
$ npm install --save section-matter
```

## Usage

**Params**

* `input` **{String|Buffer|Object}**: If input is an object, it's `content` property must be a string or buffer.    
* **{Object}**: options    
* `returns` **{Object}**: Returns an object with a `content` string and an array of `sections` objects.  

**Example**

```js
var sections = require('{%= name %}');
var result = sections(input, options);
// { content: 'Content before sections', sections: [] }
```

See available [options](#options).

## Example

_With the exception of front-matter, **which must be the very first thing in the string**, the opening delimiter of all other sections must be followed by a string to be used as the `key` for the section._

Given the following string:

```
Content before the sections.

---

More content.

---one
title: One
---

This is the first section.
```

The following code:

```js
console.log(sections(input));
```

Results in:

```js
{ 
  content: 'Content before the sections.\n\n---\n\nMore content.\n',
  sections: [
    { 
      key: 'one',
      data: 'title: One',
      content: '\nThis is the first section.' 
    } 
  ] 
}
```

## Options

### options.section_parse

**Type**: `function`

**Default**: `undefined`

Function to be called on each section after it's parsed from the string.

**Example**

Given the following string (`foo.md`):

```
This is content before the sections.

---one
title: First section
---

This is section one.

---two
title: Second section
---

This is section two.
```

Using the following custom `section_parse` function:

```js
var fs = require('fs');
var path = require('path');
var yaml = require('js-yaml');
var sections = require('section-matter');

var str = fs.readFileSync('foo.md');
var options = {
  section_parse: function(section) {
    console.log(section)
    section.key = 'section-' + section.key;
    section.data = yaml.safeLoad(section.data);
  }
};

var result = sections(str, options);
console.log(result);
```

Results in:

```js
{
  content: 'This is content before the sections.\n',
  sections: [
    {
      key: 'section-one',
      data: { title: 'First section' },
      content: '\nThis is section one.\n'
    },
    {
      key: 'section-two',
      data: { title: 'Second section' },
      content: '\nThis is section two.\n'
    }
  ]
}
```

### options.section_delimiter

**Type**: `string`

**Default**: `---`

Delimiter to use as the separator for sections. _With the exception of front-matter, which must be the very first thing in the string, the opening delimiter of all other sections must be followed by a string to be used as the `key` for the section._

**Example**

```js
var input = '~~~\ntitle: bar\n~~~\n\nfoo\n~~~one\ntitle: One\n~~~\nThis is one';
console.log(sections(input, {section_delimiter: '~~~'}));
```

Results in:

```js
{
  content: '',
  sections: [
    {
      key: '',
      data: 'title: bar',
      content: '\nfoo'
    },
    {
      key: 'one',
      data: 'title: One',
      content: 'This is one'
    }
  ]
}
```

## About
<details>
  <summary><strong>Contributing</strong></summary>

Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).

Please read the [contributing guide](.github/contributing.md) for advice on opening issues, pull requests, and coding standards.

</details>

<details>
  <summary><strong>Running Tests</strong></summary>

Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

```sh
$ npm install && npm test
```

</details>

<details>
  <summary><strong>Building docs</strong></summary>

_(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_

To generate the readme, run the following command:

```sh
$ npm install -g verbose/verb#dev verb-generate-readme && verb
```

</details>

### Related projects

You might also be interested in these projects: 

- [assemble](https://www.npmjs.com/package/assemble): Get the rocks out of your socks! Assemble makes you fast at creating web projects… [more](https://github.com/assemble/assemble) | [homepage](https://github.com/assemble/assemble "Get the rocks out of your socks! Assemble makes you fast at creating web projects. Assemble is used by thousands of projects for rapid prototyping, creating themes, scaffolds, boilerplates, e-books, UI components, API documentation, blogs, building websit")
- [gray-matter](https://www.npmjs.com/package/gray-matter): Parse front-matter from a string or file. Fast, reliable and easy to use. Parses YAML… [more](https://github.com/jonschlinkert/gray-matter) | [homepage](https://github.com/jonschlinkert/gray-matter "Parse front-matter from a string or file. Fast, reliable and easy to use. Parses YAML front matter by default, but also has support for YAML, JSON, TOML or Coffee Front-Matter, with options to set custom delimiters. Used by metalsmith, assemble, verb and ")
- [verb](https://www.npmjs.com/package/verb): Documentation generator for GitHub projects. Verb is extremely powerful, easy to use, and is used… [more](https://github.com/verbose/verb) | [homepage](https://github.com/verbose/verb "Documentation generator for GitHub projects. Verb is extremely powerful, easy to use, and is used on hundreds of projects of all sizes to generate everything from API docs to readmes.")  

### Contributors

### Author
**Jon Schlinkert**

+ [github/jonschlinkert](https://github.com/jonschlinkert)
+ [twitter/jonschlinkert](https://twitter.com/jonschlinkert)

### License
Copyright © 2017, [Jon Schlinkert](https://github.com/jonschlinkert).
Released under the [MIT License](LICENSE).

***

_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.6.0, on October 23, 2017._



---

# Select Hose

[![Build Status](https://secure.travis-ci.org/indutny/select-hose.png)](http://travis-ci.org/indutny/select-hose)
[![NPM version](https://badge.fury.io/js/select-hose.svg)](http://badge.fury.io/js/select-hose)

Hose the data to the handler

## LICENSE

This software is licensed under the MIT License.

Copyright Fedor Indutny, 2015.

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to permit
persons to whom the Software is furnished to do so, subject to the
following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
USE OR OTHER DEALINGS IN THE SOFTWARE.


---

Generate a self signed x509 certificate from node.js.

## Install

```bash
  npm install selfsigned
```

## Usage

```js
var selfsigned = require('selfsigned');
var attrs = [{ name: 'commonName', value: 'contoso.com' }];
var pems = selfsigned.generate(attrs, { days: 365 });
console.log(pems)
```

#### Async

```js
selfsigned.generate(attrs, { days: 365 }, function (err, pems) {
  console.log(pems)
});
```

Will return the following like this:

```js
{
  private: '-----BEGIN RSA PRIVATE KEY-----\r\nMIICXAIBAAKBgQCBFMXMYS/+RZz6+qzv+xeqXPdjw4YKZC4y3dPhSwgEwkecrCTX\r\nsR6boue+1MjIqPqWggXZnotIGldfEN0kn0Jbh2vMTrTx6YwqQ8tceBPoyuuqcYBO\r\nOONAcKOB3MLnZbyOgVtbyT3j68JE5V/lx6LhpIKAgY0m5WIuaKrW6mvLXQIDAQAB\r\nAoGAU6ODGxAqSecPdayyG/ml9vSwNAuAMgGB0eHcpZG5i2PbhRAh+0TAIXaoFQXJ\r\naAPeA2ISqlTJyRmQXYAO2uj61FzeyDzYCf0z3+yZEVz3cO7jB5Pl6iBvzbxWuuuA\r\ncbJtWLhWtW5/jioc8F0EAzZ+lkC/XuVJdwKHDmwt2qvJO+ECQQD+dvo1g3Sz9xGw\r\n21n+fDG5i4128+Qh+JPgh5AeLuXSofc1HMHaOXcC6Wu/Cloh7QAD934b7W0A7VoD\r\ndLd/JLyFAkEAgdwjryyvdhy69e516IrPB3b+m4rggtntBlZREMrk9tOzeIucVO3W\r\ntKI3FHm6JebN2gVcG+rZ+FaDPo+ifJkW+QJBAPojrMwEACmUevB2f9246gxx0UsY\r\nbq6yM3No71OsWEEY8/Bi53CEQqg7Gq5+F6H33qcHmBEN8LQTngN9rY+vZh0CQBg0\r\nqJImii5B/LeK03+dICoMDDmCEYdSh9P+ku3GZBd+Lp3xqBpMmxDgi9PNPN2DwCs7\r\nhIfPpwGbXqtyqp7/CkECQB4OdY+2FbCciI473eQkTu310RMf8jElU63iwnx4R/XN\r\n/mgqN589OfF4SS0U/MoRzYk9jF9IAJN1Mi/571T+nw4=\r\n-----END RSA PRIVATE KEY-----\r\n',
  public: '-----BEGIN PUBLIC KEY-----\r\nMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCBFMXMYS/+RZz6+qzv+xeqXPdj\r\nw4YKZC4y3dPhSwgEwkecrCTXsR6boue+1MjIqPqWggXZnotIGldfEN0kn0Jbh2vM\r\nTrTx6YwqQ8tceBPoyuuqcYBOOONAcKOB3MLnZbyOgVtbyT3j68JE5V/lx6LhpIKA\r\ngY0m5WIuaKrW6mvLXQIDAQAB\r\n-----END PUBLIC KEY-----\r\n',
  cert: '-----BEGIN CERTIFICATE-----\r\nMIICjTCCAfagAwIBAgIBATANBgkqhkiG9w0BAQUFADBpMRQwEgYDVQQDEwtleGFt\r\ncGxlLm9yZzELMAkGA1UEBhMCVVMxETAPBgNVBAgTCFZpcmdpbmlhMRMwEQYDVQQH\r\nEwpCbGFja3NidXJnMQ0wCwYDVQQKEwRUZXN0MQ0wCwYDVQQLEwRUZXN0MB4XDTEz\r\nMDgxMzA1NDAyN1oXDTE0MDgxMzA1NDAyN1owaTEUMBIGA1UEAxMLZXhhbXBsZS5v\r\ncmcxCzAJBgNVBAYTAlVTMREwDwYDVQQIEwhWaXJnaW5pYTETMBEGA1UEBxMKQmxh\r\nY2tzYnVyZzENMAsGA1UEChMEVGVzdDENMAsGA1UECxMEVGVzdDCBnzANBgkqhkiG\r\n9w0BAQEFAAOBjQAwgYkCgYEAgRTFzGEv/kWc+vqs7/sXqlz3Y8OGCmQuMt3T4UsI\r\nBMJHnKwk17Eem6LnvtTIyKj6loIF2Z6LSBpXXxDdJJ9CW4drzE608emMKkPLXHgT\r\n6MrrqnGATjjjQHCjgdzC52W8joFbW8k94+vCROVf5cei4aSCgIGNJuViLmiq1upr\r\ny10CAwEAAaNFMEMwDAYDVR0TBAUwAwEB/zALBgNVHQ8EBAMCAvQwJgYDVR0RBB8w\r\nHYYbaHR0cDovL2V4YW1wbGUub3JnL3dlYmlkI21lMA0GCSqGSIb3DQEBBQUAA4GB\r\nAC9hGQlDh8anNo1YDJdG2mYqOQ5uybJV++kixblGaOkoDROPsWepUpL6kMDUtbAM\r\n4uXTyFkvlUQSaQkhNgOY5w/BRIAkCIu6u4D4XcjlCdwFq6vcKMEuWTHMAlBWFla3\r\nXJZAPO10PHuDen7JeMOUf1Re7lRFtwfRGAvVYmrvYFKv\r\n-----END CERTIFICATE-----\r\n'
}
```

## Attributes

for attributes, please refer to: https://github.com/digitalbazaar/forge/blob/master/lib/x509.js

## Options

```js
var pems = selfsigned.generate(null, {
  keySize: 2048, // the size for the private key in bits (default: 1024)
  days: 30, // how long till expiry of the signed certificate (default: 365)
  notBeforeDate: new Date(), // The date before which the certificate should not be valid (default: now)
  algorithm: 'sha256', // sign the certificate with specified algorithm (default: 'sha1')
  extensions: [{ name: 'basicConstraints', cA: true }], // certificate extensions array
  pkcs7: true, // include PKCS#7 as part of the output (default: false)
  clientCertificate: true, // generate client cert signed by the original key (default: false)
  clientCertificateCN: 'jdoe' // client certificate's common name (default: 'John Doe jdoe123')
});
```

> You can avoid key pair generation specifying your own keys (`{ keyPair: { publicKey: '-----BEGIN PUBLIC KEY-----...', privateKey: '-----BEGIN RSA PRIVATE KEY-----...' }`)

### Generate Client Certificates

If you are in an environment where servers require client certificates, you can generate client keys signed by the original (server) key.

```js
var pems = selfsigned.generate(null, { clientCertificate: true });
console.log(pems)
```
Will return the following like this:

```js
{ private: '-----BEGIN RSA PRIVATE KEY-----\r\nMIICXQIBAAKBgQDLg/kS4dCPVu96sbK6MQuUPmhqnF8SeBXVHH18h+0BTj7HqnrA\r\nA75hNVIiSLTChvpzQ0qi2Ju7O2ESUOdx7cvGiftGuZLiI8uL2HVlYuX+wQTIoRHx\r\n9nxv56TIiqnPg5d05vSTLXoiJg5uac3a6+4vnhhTo0XRRXVVboZsfNpuGQIDAQAB\r\nAoGAfhCd9QhUPLZJWeNBJvzCg221GHUMn1Arlfsz8DPyp+BkGyKLLu4iu+xfmEUZ\r\nU3ZxJX0FeqJatTwvAT2EYJpAovx+F37PWFTLAS6T57WI1O5Lj1pTIKVkLrasNQgF\r\nl6qFD3cvEtCZve4LiwDoJ52FO2OtcDcMJ0r2oqbCXSDIlAECQQDnkkxKcTejBZGH\r\nyYEXG9hAznnEZ63LLzlHHF2cIPfxT+9826Wm0IzBxn8Wr4hcAbNx3bVKgsU9p7xA\r\nfKnSqObhAkEA4PwCjPQqxFpiYUmNt7htb8nCEvUDD/QSDyxAH/uJzfr6gOJOD5nT\r\n5gZYblC+CCMDkgDUpro6oATNyeRNoU3GOQJBANdaW26DWZ1WqV9hCpcGAxdJrT30\r\nuVASq66w93Ehy9LzZqFz1tqKacwvH7NmLGZ8AngrGdSgRnOvEMfb50aMYqECQDcG\r\nzCTnbzJZHOjIkaXWsMV/pjz2ugoD2wrk+sYXwoujj/NH5mnAaOhAsw5AJ0pcLfpe\r\nw6QHtmD+68ouUaJbIFkCQQDeu0AXAp6Kbk6570i2DpGUSnkRdGCGS+3ekqqJUpE7\r\nfVUSx1nCF1sPD0p+pO8Rj3i87iI4MlblQRm/wVkrkjiR\r\n-----END RSA PRIVATE KEY-----\r\n',
  public: '-----BEGIN PUBLIC KEY-----\r\nMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDLg/kS4dCPVu96sbK6MQuUPmhq\r\nnF8SeBXVHH18h+0BTj7HqnrAA75hNVIiSLTChvpzQ0qi2Ju7O2ESUOdx7cvGiftG\r\nuZLiI8uL2HVlYuX+wQTIoRHx9nxv56TIiqnPg5d05vSTLXoiJg5uac3a6+4vnhhT\r\no0XRRXVVboZsfNpuGQIDAQAB\r\n-----END PUBLIC KEY-----\r\n',
  cert: '-----BEGIN CERTIFICATE-----\r\nMIIClTCCAf6gAwIBAgIJdMZqoEeGMVYKMA0GCSqGSIb3DQEBBQUAMGkxFDASBgNV\r\nBAMTC2V4YW1wbGUub3JnMQswCQYDVQQGEwJVUzERMA8GA1UECBMIVmlyZ2luaWEx\r\nEzARBgNVBAcTCkJsYWNrc2J1cmcxDTALBgNVBAoTBFRlc3QxDTALBgNVBAsTBFRl\r\nc3QwHhcNMTUxMDI5MTMwNjA1WhcNMTYxMDI4MTMwNjA1WjBpMRQwEgYDVQQDEwtl\r\neGFtcGxlLm9yZzELMAkGA1UEBhMCVVMxETAPBgNVBAgTCFZpcmdpbmlhMRMwEQYD\r\nVQQHEwpCbGFja3NidXJnMQ0wCwYDVQQKEwRUZXN0MQ0wCwYDVQQLEwRUZXN0MIGf\r\nMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDLg/kS4dCPVu96sbK6MQuUPmhqnF8S\r\neBXVHH18h+0BTj7HqnrAA75hNVIiSLTChvpzQ0qi2Ju7O2ESUOdx7cvGiftGuZLi\r\nI8uL2HVlYuX+wQTIoRHx9nxv56TIiqnPg5d05vSTLXoiJg5uac3a6+4vnhhTo0XR\r\nRXVVboZsfNpuGQIDAQABo0UwQzAMBgNVHRMEBTADAQH/MAsGA1UdDwQEAwIC9DAm\r\nBgNVHREEHzAdhhtodHRwOi8vZXhhbXBsZS5vcmcvd2ViaWQjbWUwDQYJKoZIhvcN\r\nAQEFBQADgYEAj1Yyyb0R9KRFjIWNFi6RErB/riWylW4CdOK1hOyJZ+VRBWeYLKfX\r\ni///V+tqRvLlYY5x5DnrjXbDjBy0CZuN/J772/Srgp7Nl5cn92zynMJK1q4MEEs3\r\nAE/FO85R0HbGEp+IrwUwDOLR6omBFVdh1EUOTcQU2jLZNbWvLDiWbDo=\r\n-----END CERTIFICATE-----\r\n',
  clientprivate: '-----BEGIN RSA PRIVATE KEY-----\r\nMIICWwIBAAKBgQDjR5FrrdZ1jirqkx3KMPnGjrcObj/vmztWTEZ1kX6gTskQugJU\r\noxktzwDZza4jYODC6Ud2jouFLWeAi5BDSAeLwAQb951qVD9zVsmQ+63V/mvSJUoj\r\nigwj7YjcxyReJ17F0YgjceqrkZaPM8YRo8h1fj1JdPc4ZOUgA5ASZ0h2ewIDAQAB\r\nAoGAfB5DbjibG8ut6Di7VgX1AdhCY+EVjXaKqxAwklgIfOdJqpbKWwpO39NiNY+7\r\nf5qSZB8dZcNmsi4fjfWprPSTGVkk1Qp2uibtFS4MhbLEeyy4cgZfMIBQY+HD0Asf\r\n1NU7WTY5QfzgH3HAKuWpUEWdar/jE+hDPA+wnsMg+TgGARECQQDzlc+5WA9JsG9f\r\nwNRzhMGRxDP4QLmL0iLWupF4BMP/k4OLMjDtzWl725WJ4FjCzML7mSmkWWe/P8f5\r\nwrbR+e8lAkEA7t0CEsiIw8BE55YMuGIz5xI0QDnuwNWmCEmq6+ZziW3L+EuAr1S4\r\nDORqBYm5DuRvBWkWE9Sld0a8vNqWh58tHwJAP1ZYEhicuQuAmkRYucTuVEnRPZ8O\r\n4BV+65jNlIigskcYMEyXvm3oHMWnJ5fHXLfDh4p28n4w5ODfzcjcotK7ZQJAE7bX\r\n8fbtGsLmrPp8aEdqozqkZ1ygsPexMWPrIHcvt/sA56hLoazrV90ORxC73lfKNfcb\r\nZF2bnoGPGEMuQ1lG3wJAPnHysm3DgbSHZQiXWMjF4YDRRV2AeOqX1fmlSeMErwdj\r\ncwIs+ikIBnOwUOh6liJ7yK1YnckDTZTOfUDyG+vdFQ==\r\n-----END RSA PRIVATE KEY-----\r\n',
  clientpublic: '-----BEGIN PUBLIC KEY-----\r\nMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDjR5FrrdZ1jirqkx3KMPnGjrcO\r\nbj/vmztWTEZ1kX6gTskQugJUoxktzwDZza4jYODC6Ud2jouFLWeAi5BDSAeLwAQb\r\n951qVD9zVsmQ+63V/mvSJUojigwj7YjcxyReJ17F0YgjceqrkZaPM8YRo8h1fj1J\r\ndPc4ZOUgA5ASZ0h2ewIDAQAB\r\n-----END PUBLIC KEY-----\r\n',
  clientcert: '-----BEGIN CERTIFICATE-----\r\nMIICSzCCAbSgAwIBAgIBAjANBgkqhkiG9w0BAQUFADBpMRQwEgYDVQQDEwtleGFt\r\ncGxlLm9yZzELMAkGA1UEBhMCVVMxETAPBgNVBAgTCFZpcmdpbmlhMRMwEQYDVQQH\r\nEwpCbGFja3NidXJnMQ0wCwYDVQQKEwRUZXN0MQ0wCwYDVQQLEwRUZXN0MB4XDTE1\r\nMTAyOTEzMDYwNVoXDTE2MTAyOTEzMDYwNVowbjEZMBcGA1UEAxMQSm9obiBEb2Ug\r\namRvZTEyMzELMAkGA1UEBhMCVVMxETAPBgNVBAgTCFZpcmdpbmlhMRMwEQYDVQQH\r\nEwpCbGFja3NidXJnMQ0wCwYDVQQKEwRUZXN0MQ0wCwYDVQQLEwRUZXN0MIGfMA0G\r\nCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDjR5FrrdZ1jirqkx3KMPnGjrcObj/vmztW\r\nTEZ1kX6gTskQugJUoxktzwDZza4jYODC6Ud2jouFLWeAi5BDSAeLwAQb951qVD9z\r\nVsmQ+63V/mvSJUojigwj7YjcxyReJ17F0YgjceqrkZaPM8YRo8h1fj1JdPc4ZOUg\r\nA5ASZ0h2ewIDAQABMA0GCSqGSIb3DQEBBQUAA4GBACOUglBxJ80jzR3DSSMrgRav\r\n7deKUPShEPC3tbVrc3LHPGpCEJUC309aK2mbMwz2jX78tr/ezePELKbyRggUvVgN\r\nB0XdIQkpR9X4mPdtFYkMiWKNVYKd79r0kolprgFPryhT3jsICIOnwE1Ur23Q+Fk2\r\nnizRS0HY4Q25JLCmsWWy\r\n-----END CERTIFICATE-----\r\n' }
```

To override the default client CN of `john doe jdoe123`, add another option for `clientCertificateCN`:

```js
var pems = selfsigned.generate(null, { clientCertificate: true, clientCertificateCN: 'FooBar' });
```

## License

MIT


---

semver(1) -- The semantic versioner for npm
===========================================

## Install

```bash
npm install semver
````

## Usage

As a node module:

```js
const semver = require('semver')

semver.valid('1.2.3') // '1.2.3'
semver.valid('a.b.c') // null
semver.clean('  =v1.2.3   ') // '1.2.3'
semver.satisfies('1.2.3', '1.x || >=2.5.0 || 5.0.0 - 7.2.3') // true
semver.gt('1.2.3', '9.8.7') // false
semver.lt('1.2.3', '9.8.7') // true
semver.minVersion('>=1.0.0') // '1.0.0'
semver.valid(semver.coerce('v2')) // '2.0.0'
semver.valid(semver.coerce('42.6.7.9.3-alpha')) // '42.6.7'
```

You can also just load the module for the function that you care about if
you'd like to minimize your footprint.

```js
// load the whole API at once in a single object
const semver = require('semver')

// or just load the bits you need
// all of them listed here, just pick and choose what you want

// classes
const SemVer = require('semver/classes/semver')
const Comparator = require('semver/classes/comparator')
const Range = require('semver/classes/range')

// functions for working with versions
const semverParse = require('semver/functions/parse')
const semverValid = require('semver/functions/valid')
const semverClean = require('semver/functions/clean')
const semverInc = require('semver/functions/inc')
const semverDiff = require('semver/functions/diff')
const semverMajor = require('semver/functions/major')
const semverMinor = require('semver/functions/minor')
const semverPatch = require('semver/functions/patch')
const semverPrerelease = require('semver/functions/prerelease')
const semverCompare = require('semver/functions/compare')
const semverRcompare = require('semver/functions/rcompare')
const semverCompareLoose = require('semver/functions/compare-loose')
const semverCompareBuild = require('semver/functions/compare-build')
const semverSort = require('semver/functions/sort')
const semverRsort = require('semver/functions/rsort')

// low-level comparators between versions
const semverGt = require('semver/functions/gt')
const semverLt = require('semver/functions/lt')
const semverEq = require('semver/functions/eq')
const semverNeq = require('semver/functions/neq')
const semverGte = require('semver/functions/gte')
const semverLte = require('semver/functions/lte')
const semverCmp = require('semver/functions/cmp')
const semverCoerce = require('semver/functions/coerce')

// working with ranges
const semverSatisfies = require('semver/functions/satisfies')
const semverMaxSatisfying = require('semver/ranges/max-satisfying')
const semverMinSatisfying = require('semver/ranges/min-satisfying')
const semverToComparators = require('semver/ranges/to-comparators')
const semverMinVersion = require('semver/ranges/min-version')
const semverValidRange = require('semver/ranges/valid')
const semverOutside = require('semver/ranges/outside')
const semverGtr = require('semver/ranges/gtr')
const semverLtr = require('semver/ranges/ltr')
const semverIntersects = require('semver/ranges/intersects')
const semverSimplifyRange = require('semver/ranges/simplify')
const semverRangeSubset = require('semver/ranges/subset')
```

As a command-line utility:

```
$ semver -h

A JavaScript implementation of the https://semver.org/ specification
Copyright Isaac Z. Schlueter

Usage: semver [options] <version> [<version> [...]]
Prints valid versions sorted by SemVer precedence

Options:
-r --range <range>
        Print versions that match the specified range.

-i --increment [<level>]
        Increment a version by the specified level.  Level can
        be one of: major, minor, patch, premajor, preminor,
        prepatch, prerelease, or release.  Default level is 'patch'.
        Only one version may be specified.

--preid <identifier>
        Identifier to be used to prefix premajor, preminor,
        prepatch or prerelease version increments.

-l --loose
        Interpret versions and ranges loosely

-n <0|1>
        This is the base to be used for the prerelease identifier.

-p --include-prerelease
        Always include prerelease versions in range matching

-c --coerce
        Coerce a string into SemVer if possible
        (does not imply --loose)

--rtl
        Coerce version strings right to left

--ltr
        Coerce version strings left to right (default)

Program exits successfully if any valid version satisfies
all supplied ranges, and prints all satisfying versions.

If no satisfying versions are found, then exits failure.

Versions are printed in ascending order, so supplying
multiple versions to the utility will just sort them.
```

## Versions

A "version" is described by the `v2.0.0` specification found at
<https://semver.org/>.

A leading `"="` or `"v"` character is stripped off and ignored.
Support for stripping a leading "v" is kept for compatibility with `v1.0.0` of the SemVer
specification but should not be used anymore.

## Ranges

A `version range` is a set of `comparators` that specify versions
that satisfy the range.

A `comparator` is composed of an `operator` and a `version`.  The set
of primitive `operators` is:

* `<` Less than
* `<=` Less than or equal to
* `>` Greater than
* `>=` Greater than or equal to
* `=` Equal.  If no operator is specified, then equality is assumed,
  so this operator is optional but MAY be included.

For example, the comparator `>=1.2.7` would match the versions
`1.2.7`, `1.2.8`, `2.5.3`, and `1.3.9`, but not the versions `1.2.6`
or `1.1.0`. The comparator `>1` is equivalent to `>=2.0.0` and
would match the versions `2.0.0` and `3.1.0`, but not the versions
`1.0.1` or `1.1.0`.

Comparators can be joined by whitespace to form a `comparator set`,
which is satisfied by the **intersection** of all of the comparators
it includes.

A range is composed of one or more comparator sets, joined by `||`.  A
version matches a range if and only if every comparator in at least
one of the `||`-separated comparator sets is satisfied by the version.

For example, the range `>=1.2.7 <1.3.0` would match the versions
`1.2.7`, `1.2.8`, and `1.2.99`, but not the versions `1.2.6`, `1.3.0`,
or `1.1.0`.

The range `1.2.7 || >=1.2.9 <2.0.0` would match the versions `1.2.7`,
`1.2.9`, and `1.4.6`, but not the versions `1.2.8` or `2.0.0`.

### Prerelease Tags

If a version has a prerelease tag (for example, `1.2.3-alpha.3`) then
it will only be allowed to satisfy comparator sets if at least one
comparator with the same `[major, minor, patch]` tuple also has a
prerelease tag.

For example, the range `>1.2.3-alpha.3` would be allowed to match the
version `1.2.3-alpha.7`, but it would *not* be satisfied by
`3.4.5-alpha.9`, even though `3.4.5-alpha.9` is technically "greater
than" `1.2.3-alpha.3` according to the SemVer sort rules.  The version
range only accepts prerelease tags on the `1.2.3` version.
Version `3.4.5` *would* satisfy the range because it does not have a
prerelease flag, and `3.4.5` is greater than `1.2.3-alpha.7`.

The purpose of this behavior is twofold.  First, prerelease versions
frequently are updated very quickly, and contain many breaking changes
that are (by the author's design) not yet fit for public consumption.
Therefore, by default, they are excluded from range-matching
semantics.

Second, a user who has opted into using a prerelease version has
indicated the intent to use *that specific* set of
alpha/beta/rc versions.  By including a prerelease tag in the range,
the user is indicating that they are aware of the risk.  However, it
is still not appropriate to assume that they have opted into taking a
similar risk on the *next* set of prerelease versions.

Note that this behavior can be suppressed (treating all prerelease
versions as if they were normal versions, for range-matching)
by setting the `includePrerelease` flag on the options
object to any
[functions](https://github.com/npm/node-semver#functions) that do
range matching.

#### Prerelease Identifiers

The method `.inc` takes an additional `identifier` string argument that
will append the value of the string as a prerelease identifier:

```javascript
semver.inc('1.2.3', 'prerelease', 'beta')
// '1.2.4-beta.0'
```

command-line example:

```bash
$ semver 1.2.3 -i prerelease --preid beta
1.2.4-beta.0
```

Which then can be used to increment further:

```bash
$ semver 1.2.4-beta.0 -i prerelease
1.2.4-beta.1
```

To get out of the prerelease phase, use the `release` option:

```bash
$ semver 1.2.4-beta.1 -i release
1.2.4
```

#### Prerelease Identifier Base

The method `.inc` takes an optional parameter 'identifierBase' string
that will let you let your prerelease number as zero-based or one-based.
Set to `false` to omit the prerelease number altogether.
If you do not specify this parameter, it will default to zero-based.

```javascript
semver.inc('1.2.3', 'prerelease', 'beta', '1')
// '1.2.4-beta.1'
```

```javascript
semver.inc('1.2.3', 'prerelease', 'beta', false)
// '1.2.4-beta'
```

command-line example:

```bash
$ semver 1.2.3 -i prerelease --preid beta -n 1
1.2.4-beta.1
```

```bash
$ semver 1.2.3 -i prerelease --preid beta -n false
1.2.4-beta
```

### Advanced Range Syntax

Advanced range syntax desugars to primitive comparators in
deterministic ways.

Advanced ranges may be combined in the same way as primitive
comparators using white space or `||`.

#### Hyphen Ranges `X.Y.Z - A.B.C`

Specifies an inclusive set.

* `1.2.3 - 2.3.4` := `>=1.2.3 <=2.3.4`

If a partial version is provided as the first version in the inclusive
range, then the missing pieces are replaced with zeroes.

* `1.2 - 2.3.4` := `>=1.2.0 <=2.3.4`

If a partial version is provided as the second version in the
inclusive range, then all versions that start with the supplied parts
of the tuple are accepted, but nothing that would be greater than the
provided tuple parts.

* `1.2.3 - 2.3` := `>=1.2.3 <2.4.0-0`
* `1.2.3 - 2` := `>=1.2.3 <3.0.0-0`

#### X-Ranges `1.2.x` `1.X` `1.2.*` `*`

Any of `X`, `x`, or `*` may be used to "stand in" for one of the
numeric values in the `[major, minor, patch]` tuple.

* `*` := `>=0.0.0` (Any non-prerelease version satisfies, unless
  `includePrerelease` is specified, in which case any version at all
  satisfies)
* `1.x` := `>=1.0.0 <2.0.0-0` (Matching major version)
* `1.2.x` := `>=1.2.0 <1.3.0-0` (Matching major and minor versions)

A partial version range is treated as an X-Range, so the special
character is in fact optional.

* `""` (empty string) := `*` := `>=0.0.0`
* `1` := `1.x.x` := `>=1.0.0 <2.0.0-0`
* `1.2` := `1.2.x` := `>=1.2.0 <1.3.0-0`

#### Tilde Ranges `~1.2.3` `~1.2` `~1`

Allows patch-level changes if a minor version is specified on the
comparator.  Allows minor-level changes if not.

* `~1.2.3` := `>=1.2.3 <1.(2+1).0` := `>=1.2.3 <1.3.0-0`
* `~1.2` := `>=1.2.0 <1.(2+1).0` := `>=1.2.0 <1.3.0-0` (Same as `1.2.x`)
* `~1` := `>=1.0.0 <(1+1).0.0` := `>=1.0.0 <2.0.0-0` (Same as `1.x`)
* `~0.2.3` := `>=0.2.3 <0.(2+1).0` := `>=0.2.3 <0.3.0-0`
* `~0.2` := `>=0.2.0 <0.(2+1).0` := `>=0.2.0 <0.3.0-0` (Same as `0.2.x`)
* `~0` := `>=0.0.0 <(0+1).0.0` := `>=0.0.0 <1.0.0-0` (Same as `0.x`)
* `~1.2.3-beta.2` := `>=1.2.3-beta.2 <1.3.0-0` Note that prereleases in
  the `1.2.3` version will be allowed, if they are greater than or
  equal to `beta.2`.  So, `1.2.3-beta.4` would be allowed, but
  `1.2.4-beta.2` would not, because it is a prerelease of a
  different `[major, minor, patch]` tuple.

#### Caret Ranges `^1.2.3` `^0.2.5` `^0.0.4`

Allows changes that do not modify the left-most non-zero element in the
`[major, minor, patch]` tuple.  In other words, this allows patch and
minor updates for versions `1.0.0` and above, patch updates for
versions `0.X >=0.1.0`, and *no* updates for versions `0.0.X`.

Many authors treat a `0.x` version as if the `x` were the major
"breaking-change" indicator.

Caret ranges are ideal when an author may make breaking changes
between `0.2.4` and `0.3.0` releases, which is a common practice.
However, it presumes that there will *not* be breaking changes between
`0.2.4` and `0.2.5`.  It allows for changes that are presumed to be
additive (but non-breaking), according to commonly observed practices.

* `^1.2.3` := `>=1.2.3 <2.0.0-0`
* `^0.2.3` := `>=0.2.3 <0.3.0-0`
* `^0.0.3` := `>=0.0.3 <0.0.4-0`
* `^1.2.3-beta.2` := `>=1.2.3-beta.2 <2.0.0-0` Note that prereleases in
  the `1.2.3` version will be allowed, if they are greater than or
  equal to `beta.2`.  So, `1.2.3-beta.4` would be allowed, but
  `1.2.4-beta.2` would not, because it is a prerelease of a
  different `[major, minor, patch]` tuple.
* `^0.0.3-beta` := `>=0.0.3-beta <0.0.4-0`  Note that prereleases in the
  `0.0.3` version *only* will be allowed, if they are greater than or
  equal to `beta`.  So, `0.0.3-pr.2` would be allowed.

When parsing caret ranges, a missing `patch` value desugars to the
number `0`, but will allow flexibility within that value, even if the
major and minor versions are both `0`.

* `^1.2.x` := `>=1.2.0 <2.0.0-0`
* `^0.0.x` := `>=0.0.0 <0.1.0-0`
* `^0.0` := `>=0.0.0 <0.1.0-0`

A missing `minor` and `patch` values will desugar to zero, but also
allow flexibility within those values, even if the major version is
zero.

* `^1.x` := `>=1.0.0 <2.0.0-0`
* `^0.x` := `>=0.0.0 <1.0.0-0`

### Range Grammar

Putting all this together, here is a Backus-Naur grammar for ranges,
for the benefit of parser authors:

```bnf
range-set  ::= range ( logical-or range ) *
logical-or ::= ( ' ' ) * '||' ( ' ' ) *
range      ::= hyphen | simple ( ' ' simple ) * | ''
hyphen     ::= partial ' - ' partial
simple     ::= primitive | partial | tilde | caret
primitive  ::= ( '<' | '>' | '>=' | '<=' | '=' ) partial
partial    ::= xr ( '.' xr ( '.' xr qualifier ? )? )?
xr         ::= 'x' | 'X' | '*' | nr
nr         ::= '0' | ['1'-'9'] ( ['0'-'9'] ) *
tilde      ::= '~' partial
caret      ::= '^' partial
qualifier  ::= ( '-' pre )? ( '+' build )?
pre        ::= parts
build      ::= parts
parts      ::= part ( '.' part ) *
part       ::= nr | [-0-9A-Za-z]+
```

## Functions

All methods and classes take a final `options` object argument.  All
options in this object are `false` by default.  The options supported
are:

- `loose`: Be more forgiving about not-quite-valid semver strings.
  (Any resulting output will always be 100% strict compliant, of
  course.)  For backwards compatibility reasons, if the `options`
  argument is a boolean value instead of an object, it is interpreted
  to be the `loose` param.
- `includePrerelease`: Set to suppress the [default
  behavior](https://github.com/npm/node-semver#prerelease-tags) of
  excluding prerelease tagged versions from ranges unless they are
  explicitly opted into.

Strict-mode Comparators and Ranges will be strict about the SemVer
strings that they parse.

* `valid(v)`: Return the parsed version, or null if it's not valid.
* `inc(v, releaseType, options, identifier, identifierBase)`: 
  Return the version incremented by the release
  type (`major`, `premajor`, `minor`, `preminor`, `patch`,
  `prepatch`, `prerelease`, or `release`), or null if it's not valid
  * `premajor` in one call will bump the version up to the next major
    version and down to a prerelease of that major version.
    `preminor`, and `prepatch` work the same way.
  * If called from a non-prerelease version, `prerelease` will work the
    same as `prepatch`. It increments the patch version and then makes a
    prerelease. If the input version is already a prerelease it simply
    increments it.
  * `release` will remove any prerelease part of the version.
  * `identifier` can be used to prefix `premajor`, `preminor`,
    `prepatch`, or `prerelease` version increments. `identifierBase`
    is the base to be used for the `prerelease` identifier.
* `prerelease(v)`: Returns an array of prerelease components, or null
  if none exist. Example: `prerelease('1.2.3-alpha.1') -> ['alpha', 1]`
* `major(v)`: Return the major version number.
* `minor(v)`: Return the minor version number.
* `patch(v)`: Return the patch version number.
* `intersects(r1, r2, loose)`: Return true if the two supplied ranges
  or comparators intersect.
* `parse(v)`: Attempt to parse a string as a semantic version, returning either
  a `SemVer` object or `null`.

### Comparison

* `gt(v1, v2)`: `v1 > v2`
* `gte(v1, v2)`: `v1 >= v2`
* `lt(v1, v2)`: `v1 < v2`
* `lte(v1, v2)`: `v1 <= v2`
* `eq(v1, v2)`: `v1 == v2` This is true if they're logically equivalent,
  even if they're not the same string.  You already know how to
  compare strings.
* `neq(v1, v2)`: `v1 != v2` The opposite of `eq`.
* `cmp(v1, comparator, v2)`: Pass in a comparison string, and it'll call
  the corresponding function above.  `"==="` and `"!=="` do simple
  string comparison, but are included for completeness.  Throws if an
  invalid comparison string is provided.
* `compare(v1, v2)`: Return `0` if `v1 == v2`, or `1` if `v1` is greater, or `-1` if
  `v2` is greater.  Sorts in ascending order if passed to `Array.sort()`.
* `rcompare(v1, v2)`: The reverse of `compare`.  Sorts an array of versions
  in descending order when passed to `Array.sort()`.
* `compareBuild(v1, v2)`: The same as `compare` but considers `build` when two versions
  are equal.  Sorts in ascending order if passed to `Array.sort()`.
* `compareLoose(v1, v2)`: Short for `compare(v1, v2, { loose: true })`.
* `diff(v1, v2)`: Returns the difference between two versions by the release type
  (`major`, `premajor`, `minor`, `preminor`, `patch`, `prepatch`, or `prerelease`),
  or null if the versions are the same.

### Sorting

* `sort(versions)`: Returns a sorted array of versions based on the `compareBuild` 
  function.
* `rsort(versions)`: The reverse of `sort`. Returns an array of versions based on
  the `compareBuild` function in descending order.

### Comparators

* `intersects(comparator)`: Return true if the comparators intersect

### Ranges

* `validRange(range)`: Return the valid range or null if it's not valid.
* `satisfies(version, range)`: Return true if the version satisfies the
  range.
* `maxSatisfying(versions, range)`: Return the highest version in the list
  that satisfies the range, or `null` if none of them do.
* `minSatisfying(versions, range)`: Return the lowest version in the list
  that satisfies the range, or `null` if none of them do.
* `minVersion(range)`: Return the lowest version that can match
  the given range.
* `gtr(version, range)`: Return `true` if the version is greater than all the
  versions possible in the range.
* `ltr(version, range)`: Return `true` if the version is less than all the
  versions possible in the range.
* `outside(version, range, hilo)`: Return true if the version is outside
  the bounds of the range in either the high or low direction.  The
  `hilo` argument must be either the string `'>'` or `'<'`.  (This is
  the function called by `gtr` and `ltr`.)
* `intersects(range)`: Return true if any of the range comparators intersect.
* `simplifyRange(versions, range)`: Return a "simplified" range that
  matches the same items in the `versions` list as the range specified.  Note
  that it does *not* guarantee that it would match the same versions in all
  cases, only for the set of versions provided.  This is useful when
  generating ranges by joining together multiple versions with `||`
  programmatically, to provide the user with something a bit more
  ergonomic.  If the provided range is shorter in string-length than the
  generated range, then that is returned.
* `subset(subRange, superRange)`: Return `true` if the `subRange` range is
  entirely contained by the `superRange` range.

Note that, since ranges may be non-contiguous, a version might not be
greater than a range, less than a range, *or* satisfy a range!  For
example, the range `1.2 <1.2.9 || >2.0.0` would have a hole from `1.2.9`
until `2.0.0`, so version `1.2.10` would not be greater than the
range (because `2.0.1` satisfies, which is higher), nor less than the
range (since `1.2.8` satisfies, which is lower), and it also does not
satisfy the range.

If you want to know if a version satisfies or does not satisfy a
range, use the `satisfies(version, range)` function.

### Coercion

* `coerce(version, options)`: Coerces a string to semver if possible

This aims to provide a very forgiving translation of a non-semver string to
semver. It looks for the first digit in a string and consumes all
remaining characters which satisfy at least a partial semver (e.g., `1`,
`1.2`, `1.2.3`) up to the max permitted length (256 characters).  Longer
versions are simply truncated (`4.6.3.9.2-alpha2` becomes `4.6.3`).  All
surrounding text is simply ignored (`v3.4 replaces v3.3.1` becomes
`3.4.0`).  Only text which lacks digits will fail coercion (`version one`
is not valid).  The maximum length for any semver component considered for
coercion is 16 characters; longer components will be ignored
(`10000000000000000.4.7.4` becomes `4.7.4`).  The maximum value for any
semver component is `Number.MAX_SAFE_INTEGER || (2**53 - 1)`; higher value
components are invalid (`9999999999999999.4.7.4` is likely invalid).

If the `options.rtl` flag is set, then `coerce` will return the right-most
coercible tuple that does not share an ending index with a longer coercible
tuple.  For example, `1.2.3.4` will return `2.3.4` in rtl mode, not
`4.0.0`.  `1.2.3/4` will return `4.0.0`, because the `4` is not a part of
any other overlapping SemVer tuple.

If the `options.includePrerelease` flag is set, then the `coerce` result will contain
prerelease and build parts of a version.  For example, `1.2.3.4-rc.1+rev.2`
will preserve prerelease `rc.1` and build `rev.2` in the result.

### Clean

* `clean(version)`: Clean a string to be a valid semver if possible

This will return a cleaned and trimmed semver version. If the provided
version is not valid a null will be returned. This does not work for
ranges.

ex.
* `s.clean(' = v 2.1.5foo')`: `null`
* `s.clean(' = v 2.1.5foo', { loose: true })`: `'2.1.5-foo'`
* `s.clean(' = v 2.1.5-foo')`: `null`
* `s.clean(' = v 2.1.5-foo', { loose: true })`: `'2.1.5-foo'`
* `s.clean('=v2.1.5')`: `'2.1.5'`
* `s.clean('  =v2.1.5')`: `'2.1.5'`
* `s.clean('      2.1.5   ')`: `'2.1.5'`
* `s.clean('~1.0.0')`: `null`

## Constants

As a convenience, helper constants are exported to provide information about what `node-semver` supports:

### `RELEASE_TYPES`

- major
- premajor
- minor
- preminor
- patch
- prepatch
- prerelease

```
const semver = require('semver');

if (semver.RELEASE_TYPES.includes(arbitraryUserInput)) {
  console.log('This is a valid release type!');
} else {
  console.warn('This is NOT a valid release type!');
}
```

### `SEMVER_SPEC_VERSION`

2.0.0

```
const semver = require('semver');

console.log('We are currently using the semver specification version:', semver.SEMVER_SPEC_VERSION);
```

## Exported Modules

<!--
TODO: Make sure that all of these items are documented (classes aren't,
eg), and then pull the module name into the documentation for that specific
thing.
-->

You may pull in just the part of this semver utility that you need if you
are sensitive to packing and tree-shaking concerns.  The main
`require('semver')` export uses getter functions to lazily load the parts
of the API that are used.

The following modules are available:

* `require('semver')`
* `require('semver/classes')`
* `require('semver/classes/comparator')`
* `require('semver/classes/range')`
* `require('semver/classes/semver')`
* `require('semver/functions/clean')`
* `require('semver/functions/cmp')`
* `require('semver/functions/coerce')`
* `require('semver/functions/compare')`
* `require('semver/functions/compare-build')`
* `require('semver/functions/compare-loose')`
* `require('semver/functions/diff')`
* `require('semver/functions/eq')`
* `require('semver/functions/gt')`
* `require('semver/functions/gte')`
* `require('semver/functions/inc')`
* `require('semver/functions/lt')`
* `require('semver/functions/lte')`
* `require('semver/functions/major')`
* `require('semver/functions/minor')`
* `require('semver/functions/neq')`
* `require('semver/functions/parse')`
* `require('semver/functions/patch')`
* `require('semver/functions/prerelease')`
* `require('semver/functions/rcompare')`
* `require('semver/functions/rsort')`
* `require('semver/functions/satisfies')`
* `require('semver/functions/sort')`
* `require('semver/functions/valid')`
* `require('semver/ranges/gtr')`
* `require('semver/ranges/intersects')`
* `require('semver/ranges/ltr')`
* `require('semver/ranges/max-satisfying')`
* `require('semver/ranges/min-satisfying')`
* `require('semver/ranges/min-version')`
* `require('semver/ranges/outside')`
* `require('semver/ranges/simplify')`
* `require('semver/ranges/subset')`
* `require('semver/ranges/to-comparators')`
* `require('semver/ranges/valid')`



---

# semver-diff

> Get the diff type of two [semver](https://github.com/npm/node-semver) versions: `0.0.1 0.0.2` → `patch`

## Install

```
$ npm install semver-diff
```

## Usage

```js
import semverDiff from 'semver-diff';

semverDiff('1.1.1', '1.1.2');
//=> 'patch'

semverDiff('1.1.1-foo', '1.1.2');
//=> 'prepatch'

semverDiff('0.0.1', '1.0.0');
//=> 'major'

semverDiff('0.0.1-foo', '1.0.0');
//=> 'premajor'

semverDiff('0.0.1', '0.1.0');
//=> 'minor'

semverDiff('0.0.1-foo', '0.1.0');
//=> 'preminor'

semverDiff('0.0.1-foo', '0.0.1-foo.bar');
//=> 'prerelease'

semverDiff('0.1.0', '0.1.0+foo');
//=> 'build'

semverDiff('0.0.1', '0.0.1');
//=> undefined

semverDiff('0.0.2', '0.0.1');
//=> undefined
```

## API

### semverDiff(versionA, versionB)

Returns the difference type between two semver versions, or `undefined` if they are identical or the second one is lower than the first.

Possible values:

- `'major'`,
- `'premajor'`,
- `'minor'`,
- `'preminor'`,
- `'patch'`,
- `'prepatch'`,
- `'prerelease'`,
- `'build'`,
- `undefined`

## Related

- [latest-semver](https://github.com/sindresorhus/latest-semver) - Get the latest stable semver version from an array of versions
- [to-semver](https://github.com/sindresorhus/to-semver) - Get an array of valid, sorted, and cleaned semver versions from an array of strings
- [semver-regex](https://github.com/sindresorhus/semver-regex) - Regular expression for matching semver versions
- [semver-truncate](https://github.com/sindresorhus/semver-truncate) - Truncate a semver version: `1.2.3` → `1.2.0`

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-semver-diff?utm_source=npm-semver-diff&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

0.19.0 / 2024-09-10
===================

* Remove link renderization in html while redirecting

0.18.0 / 2022-03-23
===================

  * Fix emitted 416 error missing headers property
  * Limit the headers removed for 304 response
  * deps: depd@2.0.0
    - Replace internal `eval` usage with `Function` constructor
    - Use instance methods on `process` to check for listeners
  * deps: destroy@1.2.0
  * deps: http-errors@2.0.0
    - deps: depd@2.0.0
    - deps: statuses@2.0.1
  * deps: on-finished@2.4.1
  * deps: statuses@2.0.1

0.17.2 / 2021-12-11
===================

  * pref: ignore empty http tokens
  * deps: http-errors@1.8.1
    - deps: inherits@2.0.4
    - deps: toidentifier@1.0.1
    - deps: setprototypeof@1.2.0
  * deps: ms@2.1.3

0.17.1 / 2019-05-10
===================

  * Set stricter CSP header in redirect & error responses
  * deps: range-parser@~1.2.1

0.17.0 / 2019-05-03
===================

  * deps: http-errors@~1.7.2
    - Set constructor name when possible
    - Use `toidentifier` module to make class names
    - deps: depd@~1.1.2
    - deps: setprototypeof@1.1.1
    - deps: statuses@'>= 1.5.0 < 2'
  * deps: mime@1.6.0
    - Add extensions for JPEG-2000 images
    - Add new `font/*` types from IANA
    - Add WASM mapping
    - Update `.bdoc` to `application/bdoc`
    - Update `.bmp` to `image/bmp`
    - Update `.m4a` to `audio/mp4`
    - Update `.rtf` to `application/rtf`
    - Update `.wav` to `audio/wav`
    - Update `.xml` to `application/xml`
    - Update generic extensions to `application/octet-stream`:
      `.deb`, `.dll`, `.dmg`, `.exe`, `.iso`, `.msi`
    - Use mime-score module to resolve extension conflicts
  * deps: ms@2.1.1
    - Add `week`/`w` support
    - Fix negative number handling
  * deps: statuses@~1.5.0
  * perf: remove redundant `path.normalize` call

0.16.2 / 2018-02-07
===================

  * Fix incorrect end tag in default error & redirects
  * deps: depd@~1.1.2
    - perf: remove argument reassignment
  * deps: encodeurl@~1.0.2
    - Fix encoding `%` as last character
  * deps: statuses@~1.4.0

0.16.1 / 2017-09-29
===================

  * Fix regression in edge-case behavior for empty `path`

0.16.0 / 2017-09-27
===================

  * Add `immutable` option
  * Fix missing `</html>` in default error & redirects
  * Use instance methods on steam to check for listeners
  * deps: mime@1.4.1
    - Add 70 new types for file extensions
    - Set charset as "UTF-8" for .js and .json
  * perf: improve path validation speed

0.15.6 / 2017-09-22
===================

  * deps: debug@2.6.9
  * perf: improve `If-Match` token parsing

0.15.5 / 2017-09-20
===================

  * deps: etag@~1.8.1
    - perf: replace regular expression with substring
  * deps: fresh@0.5.2
    - Fix handling of modified headers with invalid dates
    - perf: improve ETag match loop
    - perf: improve `If-None-Match` token parsing

0.15.4 / 2017-08-05
===================

  * deps: debug@2.6.8
  * deps: depd@~1.1.1
    - Remove unnecessary `Buffer` loading
  * deps: http-errors@~1.6.2
    - deps: depd@1.1.1

0.15.3 / 2017-05-16
===================

  * deps: debug@2.6.7
    - deps: ms@2.0.0
  * deps: ms@2.0.0

0.15.2 / 2017-04-26
===================

  * deps: debug@2.6.4
    - Fix `DEBUG_MAX_ARRAY_LENGTH`
    - deps: ms@0.7.3
  * deps: ms@1.0.0

0.15.1 / 2017-03-04
===================

  * Fix issue when `Date.parse` does not return `NaN` on invalid date
  * Fix strict violation in broken environments

0.15.0 / 2017-02-25
===================

  * Support `If-Match` and `If-Unmodified-Since` headers
  * Add `res` and `path` arguments to `directory` event
  * Remove usage of `res._headers` private field
    - Improves compatibility with Node.js 8 nightly
  * Send complete HTML document in redirect & error responses
  * Set default CSP header in redirect & error responses
  * Use `res.getHeaderNames()` when available
  * Use `res.headersSent` when available
  * deps: debug@2.6.1
    - Allow colors in workers
    - Deprecated `DEBUG_FD` environment variable set to `3` or higher
    - Fix error when running under React Native
    - Use same color for same namespace
    - deps: ms@0.7.2
  * deps: etag@~1.8.0
  * deps: fresh@0.5.0
    - Fix false detection of `no-cache` request directive
    - Fix incorrect result when `If-None-Match` has both `*` and ETags
    - Fix weak `ETag` matching to match spec
    - perf: delay reading header values until needed
    - perf: enable strict mode
    - perf: hoist regular expressions
    - perf: remove duplicate conditional
    - perf: remove unnecessary boolean coercions
    - perf: skip checking modified time if ETag check failed
    - perf: skip parsing `If-None-Match` when no `ETag` header
    - perf: use `Date.parse` instead of `new Date`
  * deps: http-errors@~1.6.1
    - Make `message` property enumerable for `HttpError`s
    - deps: setprototypeof@1.0.3

0.14.2 / 2017-01-23
===================

  * deps: http-errors@~1.5.1
    - deps: inherits@2.0.3
    - deps: setprototypeof@1.0.2
    - deps: statuses@'>= 1.3.1 < 2'
  * deps: ms@0.7.2
  * deps: statuses@~1.3.1

0.14.1 / 2016-06-09
===================

  * Fix redirect error when `path` contains raw non-URL characters
  * Fix redirect when `path` starts with multiple forward slashes

0.14.0 / 2016-06-06
===================

  * Add `acceptRanges` option
  * Add `cacheControl` option
  * Attempt to combine multiple ranges into single range
  * Correctly inherit from `Stream` class
  * Fix `Content-Range` header in 416 responses when using `start`/`end` options
  * Fix `Content-Range` header missing from default 416 responses
  * Ignore non-byte `Range` headers
  * deps: http-errors@~1.5.0
    - Add `HttpError` export, for `err instanceof createError.HttpError`
    - Support new code `421 Misdirected Request`
    - Use `setprototypeof` module to replace `__proto__` setting
    - deps: inherits@2.0.1
    - deps: statuses@'>= 1.3.0 < 2'
    - perf: enable strict mode
  * deps: range-parser@~1.2.0
    - Fix incorrectly returning -1 when there is at least one valid range
    - perf: remove internal function
  * deps: statuses@~1.3.0
    - Add `421 Misdirected Request`
    - perf: enable strict mode
  * perf: remove argument reassignment

0.13.2 / 2016-03-05
===================

  * Fix invalid `Content-Type` header when `send.mime.default_type` unset

0.13.1 / 2016-01-16
===================

  * deps: depd@~1.1.0
    - Support web browser loading
    - perf: enable strict mode
  * deps: destroy@~1.0.4
    - perf: enable strict mode
  * deps: escape-html@~1.0.3
    - perf: enable strict mode
    - perf: optimize string replacement
    - perf: use faster string coercion
  * deps: range-parser@~1.0.3
    - perf: enable strict mode

0.13.0 / 2015-06-16
===================

  * Allow Node.js HTTP server to set `Date` response header
  * Fix incorrectly removing `Content-Location` on 304 response
  * Improve the default redirect response headers
  * Send appropriate headers on default error response
  * Use `http-errors` for standard emitted errors
  * Use `statuses` instead of `http` module for status messages
  * deps: escape-html@1.0.2
  * deps: etag@~1.7.0
    - Improve stat performance by removing hashing
  * deps: fresh@0.3.0
    - Add weak `ETag` matching support
  * deps: on-finished@~2.3.0
    - Add defined behavior for HTTP `CONNECT` requests
    - Add defined behavior for HTTP `Upgrade` requests
    - deps: ee-first@1.1.1
  * perf: enable strict mode
  * perf: remove unnecessary array allocations

0.12.3 / 2015-05-13
===================

  * deps: debug@~2.2.0
    - deps: ms@0.7.1
  * deps: depd@~1.0.1
  * deps: etag@~1.6.0
   - Improve support for JXcore
   - Support "fake" stats objects in environments without `fs`
  * deps: ms@0.7.1
    - Prevent extraordinarily long inputs
  * deps: on-finished@~2.2.1

0.12.2 / 2015-03-13
===================

  * Throw errors early for invalid `extensions` or `index` options
  * deps: debug@~2.1.3
    - Fix high intensity foreground color for bold
    - deps: ms@0.7.0

0.12.1 / 2015-02-17
===================

  * Fix regression sending zero-length files

0.12.0 / 2015-02-16
===================

  * Always read the stat size from the file
  * Fix mutating passed-in `options`
  * deps: mime@1.3.4

0.11.1 / 2015-01-20
===================

  * Fix `root` path disclosure

0.11.0 / 2015-01-05
===================

  * deps: debug@~2.1.1
  * deps: etag@~1.5.1
    - deps: crc@3.2.1
  * deps: ms@0.7.0
    - Add `milliseconds`
    - Add `msecs`
    - Add `secs`
    - Add `mins`
    - Add `hrs`
    - Add `yrs`
  * deps: on-finished@~2.2.0

0.10.1 / 2014-10-22
===================

  * deps: on-finished@~2.1.1
    - Fix handling of pipelined requests

0.10.0 / 2014-10-15
===================

  * deps: debug@~2.1.0
    - Implement `DEBUG_FD` env variable support
  * deps: depd@~1.0.0
  * deps: etag@~1.5.0
    - Improve string performance
    - Slightly improve speed for weak ETags over 1KB

0.9.3 / 2014-09-24
==================

  * deps: etag@~1.4.0
    - Support "fake" stats objects

0.9.2 / 2014-09-15
==================

  * deps: depd@0.4.5
  * deps: etag@~1.3.1
  * deps: range-parser@~1.0.2

0.9.1 / 2014-09-07
==================

  * deps: fresh@0.2.4

0.9.0 / 2014-09-07
==================

  * Add `lastModified` option
  * Use `etag` to generate `ETag` header
  * deps: debug@~2.0.0

0.8.5 / 2014-09-04
==================

  * Fix malicious path detection for empty string path

0.8.4 / 2014-09-04
==================

  * Fix a path traversal issue when using `root`

0.8.3 / 2014-08-16
==================

  * deps: destroy@1.0.3
    - renamed from dethroy
  * deps: on-finished@2.1.0

0.8.2 / 2014-08-14
==================

  * Work around `fd` leak in Node.js 0.10 for `fs.ReadStream`
  * deps: dethroy@1.0.2

0.8.1 / 2014-08-05
==================

  * Fix `extensions` behavior when file already has extension

0.8.0 / 2014-08-05
==================

  * Add `extensions` option

0.7.4 / 2014-08-04
==================

  * Fix serving index files without root dir

0.7.3 / 2014-07-29
==================

  * Fix incorrect 403 on Windows and Node.js 0.11

0.7.2 / 2014-07-27
==================

  * deps: depd@0.4.4
    - Work-around v8 generating empty stack traces

0.7.1 / 2014-07-26
==================

 * deps: depd@0.4.3
   - Fix exception when global `Error.stackTraceLimit` is too low

0.7.0 / 2014-07-20
==================

 * Deprecate `hidden` option; use `dotfiles` option
 * Add `dotfiles` option
 * deps: debug@1.0.4
 * deps: depd@0.4.2
   - Add `TRACE_DEPRECATION` environment variable
   - Remove non-standard grey color from color output
   - Support `--no-deprecation` argument
   - Support `--trace-deprecation` argument

0.6.0 / 2014-07-11
==================

 * Deprecate `from` option; use `root` option
 * Deprecate `send.etag()` -- use `etag` in `options`
 * Deprecate `send.hidden()` -- use `hidden` in `options`
 * Deprecate `send.index()` -- use `index` in `options`
 * Deprecate `send.maxage()` -- use `maxAge` in `options`
 * Deprecate `send.root()` -- use `root` in `options`
 * Cap `maxAge` value to 1 year
 * deps: debug@1.0.3
   - Add support for multiple wildcards in namespaces

0.5.0 / 2014-06-28
==================

 * Accept string for `maxAge` (converted by `ms`)
 * Add `headers` event
 * Include link in default redirect response
 * Use `EventEmitter.listenerCount` to count listeners

0.4.3 / 2014-06-11
==================

 * Do not throw un-catchable error on file open race condition
 * Use `escape-html` for HTML escaping
 * deps: debug@1.0.2
   - fix some debugging output colors on node.js 0.8
 * deps: finished@1.2.2
 * deps: fresh@0.2.2

0.4.2 / 2014-06-09
==================

 * fix "event emitter leak" warnings
 * deps: debug@1.0.1
 * deps: finished@1.2.1

0.4.1 / 2014-06-02
==================

 * Send `max-age` in `Cache-Control` in correct format

0.4.0 / 2014-05-27
==================

 * Calculate ETag with md5 for reduced collisions
 * Fix wrong behavior when index file matches directory
 * Ignore stream errors after request ends
   - Goodbye `EBADF, read`
 * Skip directories in index file search
 * deps: debug@0.8.1

0.3.0 / 2014-04-24
==================

 * Fix sending files with dots without root set
 * Coerce option types
 * Accept API options in options object
 * Set etags to "weak"
 * Include file path in etag
 * Make "Can't set headers after they are sent." catchable
 * Send full entity-body for multi range requests
 * Default directory access to 403 when index disabled
 * Support multiple index paths
 * Support "If-Range" header
 * Control whether to generate etags
 * deps: mime@1.2.11

0.2.0 / 2014-01-29
==================

 * update range-parser and fresh

0.1.4 / 2013-08-11 
==================

 * update fresh

0.1.3 / 2013-07-08 
==================

 * Revert "Fix fd leak"

0.1.2 / 2013-07-03 
==================

 * Fix fd leak

0.1.0 / 2012-08-25 
==================

  * add options parameter to send() that is passed to fs.createReadStream() [kanongil]

0.0.4 / 2012-08-16 
==================

  * allow custom "Accept-Ranges" definition

0.0.3 / 2012-07-16 
==================

  * fix normalization of the root directory. Closes #3

0.0.2 / 2012-07-09 
==================

  * add passing of req explicitly for now (YUCK)

0.0.1 / 2010-01-03
==================

  * Initial release


---

# send

[![NPM Version][npm-version-image]][npm-url]
[![NPM Downloads][npm-downloads-image]][npm-url]
[![Linux Build][github-actions-ci-image]][github-actions-ci-url]
[![Windows Build][appveyor-image]][appveyor-url]
[![Test Coverage][coveralls-image]][coveralls-url]

Send is a library for streaming files from the file system as a http response
supporting partial responses (Ranges), conditional-GET negotiation (If-Match,
If-Unmodified-Since, If-None-Match, If-Modified-Since), high test coverage,
and granular events which may be leveraged to take appropriate actions in your
application or framework.

Looking to serve up entire folders mapped to URLs? Try [serve-static](https://www.npmjs.org/package/serve-static).

## Installation

This is a [Node.js](https://nodejs.org/en/) module available through the
[npm registry](https://www.npmjs.com/). Installation is done using the
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):

```bash
$ npm install send
```

## API

```js
var send = require('send')
```

### send(req, path, [options])

Create a new `SendStream` for the given path to send to a `res`. The `req` is
the Node.js HTTP request and the `path` is a urlencoded path to send (urlencoded,
not the actual file-system path).

#### Options

##### acceptRanges

Enable or disable accepting ranged requests, defaults to true.
Disabling this will not send `Accept-Ranges` and ignore the contents
of the `Range` request header.

##### cacheControl

Enable or disable setting `Cache-Control` response header, defaults to
true. Disabling this will ignore the `immutable` and `maxAge` options.

##### dotfiles

Set how "dotfiles" are treated when encountered. A dotfile is a file
or directory that begins with a dot ("."). Note this check is done on
the path itself without checking if the path actually exists on the
disk. If `root` is specified, only the dotfiles above the root are
checked (i.e. the root itself can be within a dotfile when when set
to "deny").

  - `'allow'` No special treatment for dotfiles.
  - `'deny'` Send a 403 for any request for a dotfile.
  - `'ignore'` Pretend like the dotfile does not exist and 404.

The default value is _similar_ to `'ignore'`, with the exception that
this default will not ignore the files within a directory that begins
with a dot, for backward-compatibility.

##### end

Byte offset at which the stream ends, defaults to the length of the file
minus 1. The end is inclusive in the stream, meaning `end: 3` will include
the 4th byte in the stream.

##### etag

Enable or disable etag generation, defaults to true.

##### extensions

If a given file doesn't exist, try appending one of the given extensions,
in the given order. By default, this is disabled (set to `false`). An
example value that will serve extension-less HTML files: `['html', 'htm']`.
This is skipped if the requested file already has an extension.

##### immutable

Enable or disable the `immutable` directive in the `Cache-Control` response
header, defaults to `false`. If set to `true`, the `maxAge` option should
also be specified to enable caching. The `immutable` directive will prevent
supported clients from making conditional requests during the life of the
`maxAge` option to check if the file has changed.

##### index

By default send supports "index.html" files, to disable this
set `false` or to supply a new index pass a string or an array
in preferred order.

##### lastModified

Enable or disable `Last-Modified` header, defaults to true. Uses the file
system's last modified value.

##### maxAge

Provide a max-age in milliseconds for http caching, defaults to 0.
This can also be a string accepted by the
[ms](https://www.npmjs.org/package/ms#readme) module.

##### root

Serve files relative to `path`.

##### start

Byte offset at which the stream starts, defaults to 0. The start is inclusive,
meaning `start: 2` will include the 3rd byte in the stream.

#### Events

The `SendStream` is an event emitter and will emit the following events:

  - `error` an error occurred `(err)`
  - `directory` a directory was requested `(res, path)`
  - `file` a file was requested `(path, stat)`
  - `headers` the headers are about to be set on a file `(res, path, stat)`
  - `stream` file streaming has started `(stream)`
  - `end` streaming has completed

#### .pipe

The `pipe` method is used to pipe the response into the Node.js HTTP response
object, typically `send(req, path, options).pipe(res)`.

### .mime

The `mime` export is the global instance of of the
[`mime` npm module](https://www.npmjs.com/package/mime).

This is used to configure the MIME types that are associated with file extensions
as well as other options for how to resolve the MIME type of a file (like the
default type to use for an unknown file extension).

## Error-handling

By default when no `error` listeners are present an automatic response will be
made, otherwise you have full control over the response, aka you may show a 5xx
page etc.

## Caching

It does _not_ perform internal caching, you should use a reverse proxy cache
such as Varnish for this, or those fancy things called CDNs. If your
application is small enough that it would benefit from single-node memory
caching, it's small enough that it does not need caching at all ;).

## Debugging

To enable `debug()` instrumentation output export __DEBUG__:

```
$ DEBUG=send node app
```

## Running tests

```
$ npm install
$ npm test
```

## Examples

### Serve a specific file

This simple example will send a specific file to all requests.

```js
var http = require('http')
var send = require('send')

var server = http.createServer(function onRequest (req, res) {
  send(req, '/path/to/index.html')
    .pipe(res)
})

server.listen(3000)
```

### Serve all files from a directory

This simple example will just serve up all the files in a
given directory as the top-level. For example, a request
`GET /foo.txt` will send back `/www/public/foo.txt`.

```js
var http = require('http')
var parseUrl = require('parseurl')
var send = require('send')

var server = http.createServer(function onRequest (req, res) {
  send(req, parseUrl(req).pathname, { root: '/www/public' })
    .pipe(res)
})

server.listen(3000)
```

### Custom file types

```js
var http = require('http')
var parseUrl = require('parseurl')
var send = require('send')

// Default unknown types to text/plain
send.mime.default_type = 'text/plain'

// Add a custom type
send.mime.define({
  'application/x-my-type': ['x-mt', 'x-mtt']
})

var server = http.createServer(function onRequest (req, res) {
  send(req, parseUrl(req).pathname, { root: '/www/public' })
    .pipe(res)
})

server.listen(3000)
```

### Custom directory index view

This is a example of serving up a structure of directories with a
custom function to render a listing of a directory.

```js
var http = require('http')
var fs = require('fs')
var parseUrl = require('parseurl')
var send = require('send')

// Transfer arbitrary files from within /www/example.com/public/*
// with a custom handler for directory listing
var server = http.createServer(function onRequest (req, res) {
  send(req, parseUrl(req).pathname, { index: false, root: '/www/public' })
    .once('directory', directory)
    .pipe(res)
})

server.listen(3000)

// Custom directory handler
function directory (res, path) {
  var stream = this

  // redirect to trailing slash for consistent url
  if (!stream.hasTrailingSlash()) {
    return stream.redirect(path)
  }

  // get directory list
  fs.readdir(path, function onReaddir (err, list) {
    if (err) return stream.error(err)

    // render an index for the directory
    res.setHeader('Content-Type', 'text/plain; charset=UTF-8')
    res.end(list.join('\n') + '\n')
  })
}
```

### Serving from a root directory with custom error-handling

```js
var http = require('http')
var parseUrl = require('parseurl')
var send = require('send')

var server = http.createServer(function onRequest (req, res) {
  // your custom error-handling logic:
  function error (err) {
    res.statusCode = err.status || 500
    res.end(err.message)
  }

  // your custom headers
  function headers (res, path, stat) {
    // serve all files for download
    res.setHeader('Content-Disposition', 'attachment')
  }

  // your custom directory handling logic:
  function redirect () {
    res.statusCode = 301
    res.setHeader('Location', req.url + '/')
    res.end('Redirecting to ' + req.url + '/')
  }

  // transfer arbitrary files from within
  // /www/example.com/public/*
  send(req, parseUrl(req).pathname, { root: '/www/public' })
    .on('error', error)
    .on('directory', redirect)
    .on('headers', headers)
    .pipe(res)
})

server.listen(3000)
```

## License

[MIT](LICENSE)

[appveyor-image]: https://badgen.net/appveyor/ci/dougwilson/send/master?label=windows
[appveyor-url]: https://ci.appveyor.com/project/dougwilson/send
[coveralls-image]: https://badgen.net/coveralls/c/github/pillarjs/send/master
[coveralls-url]: https://coveralls.io/r/pillarjs/send?branch=master
[github-actions-ci-image]: https://badgen.net/github/checks/pillarjs/send/master?label=linux
[github-actions-ci-url]: https://github.com/pillarjs/send/actions/workflows/ci.yml
[node-image]: https://badgen.net/npm/node/send
[node-url]: https://nodejs.org/en/download/
[npm-downloads-image]: https://badgen.net/npm/dm/send
[npm-url]: https://npmjs.org/package/send
[npm-version-image]: https://badgen.net/npm/v/send


---

# Security Policies and Procedures

## Reporting a Bug

The `send` team and community take all security bugs seriously. Thank you
for improving the security of Express. We appreciate your efforts and
responsible disclosure and will make every effort to acknowledge your
contributions.

Report security bugs by emailing the current owner(s) of `send`. This information
can be found in the npm registry using the command `npm owner ls send`.
If unsure or unable to get the information from the above, open an issue
in the [project issue tracker](https://github.com/pillarjs/send/issues)
asking for the current contact information.

To ensure the timely response to your report, please ensure that the entirety
of the report is contained within the email body and not solely behind a web
link or an attachment.

At least one owner will acknowledge your email within 48 hours, and will send a
more detailed response within 48 hours indicating the next steps in handling
your report. After the initial reply to your report, the owners will
endeavor to keep you informed of the progress towards a fix and full
announcement, and may ask for additional information or guidance.


---


2.6.9 / 2017-09-22
==================

  * remove ReDoS regexp in %o formatter (#504)

2.6.8 / 2017-05-18
==================

  * Fix: Check for undefined on browser globals (#462, @marbemac)

2.6.7 / 2017-05-16
==================

  * Fix: Update ms to 2.0.0 to fix regular expression denial of service vulnerability (#458, @hubdotcom)
  * Fix: Inline extend function in node implementation (#452, @dougwilson)
  * Docs: Fix typo (#455, @msasad)

2.6.5 / 2017-04-27
==================
  
  * Fix: null reference check on window.documentElement.style.WebkitAppearance (#447, @thebigredgeek)
  * Misc: clean up browser reference checks (#447, @thebigredgeek)
  * Misc: add npm-debug.log to .gitignore (@thebigredgeek)


2.6.4 / 2017-04-20
==================

  * Fix: bug that would occure if process.env.DEBUG is a non-string value. (#444, @LucianBuzzo)
  * Chore: ignore bower.json in npm installations. (#437, @joaovieira)
  * Misc: update "ms" to v0.7.3 (@tootallnate)

2.6.3 / 2017-03-13
==================

  * Fix: Electron reference to `process.env.DEBUG` (#431, @paulcbetts)
  * Docs: Changelog fix (@thebigredgeek)

2.6.2 / 2017-03-10
==================

  * Fix: DEBUG_MAX_ARRAY_LENGTH (#420, @slavaGanzin)
  * Docs: Add backers and sponsors from Open Collective (#422, @piamancini)
  * Docs: Add Slackin invite badge (@tootallnate)

2.6.1 / 2017-02-10
==================

  * Fix: Module's `export default` syntax fix for IE8 `Expected identifier` error
  * Fix: Whitelist DEBUG_FD for values 1 and 2 only (#415, @pi0)
  * Fix: IE8 "Expected identifier" error (#414, @vgoma)
  * Fix: Namespaces would not disable once enabled (#409, @musikov)

2.6.0 / 2016-12-28
==================

  * Fix: added better null pointer checks for browser useColors (@thebigredgeek)
  * Improvement: removed explicit `window.debug` export (#404, @tootallnate)
  * Improvement: deprecated `DEBUG_FD` environment variable (#405, @tootallnate)

2.5.2 / 2016-12-25
==================

  * Fix: reference error on window within webworkers (#393, @KlausTrainer)
  * Docs: fixed README typo (#391, @lurch)
  * Docs: added notice about v3 api discussion (@thebigredgeek)

2.5.1 / 2016-12-20
==================

  * Fix: babel-core compatibility

2.5.0 / 2016-12-20
==================

  * Fix: wrong reference in bower file (@thebigredgeek)
  * Fix: webworker compatibility (@thebigredgeek)
  * Fix: output formatting issue (#388, @kribblo)
  * Fix: babel-loader compatibility (#383, @escwald)
  * Misc: removed built asset from repo and publications (@thebigredgeek)
  * Misc: moved source files to /src (#378, @yamikuronue)
  * Test: added karma integration and replaced babel with browserify for browser tests (#378, @yamikuronue)
  * Test: coveralls integration (#378, @yamikuronue)
  * Docs: simplified language in the opening paragraph (#373, @yamikuronue)

2.4.5 / 2016-12-17
==================

  * Fix: `navigator` undefined in Rhino (#376, @jochenberger)
  * Fix: custom log function (#379, @hsiliev)
  * Improvement: bit of cleanup + linting fixes (@thebigredgeek)
  * Improvement: rm non-maintainted `dist/` dir (#375, @freewil)
  * Docs: simplified language in the opening paragraph. (#373, @yamikuronue)

2.4.4 / 2016-12-14
==================

  * Fix: work around debug being loaded in preload scripts for electron (#368, @paulcbetts)

2.4.3 / 2016-12-14
==================

  * Fix: navigation.userAgent error for react native (#364, @escwald)

2.4.2 / 2016-12-14
==================

  * Fix: browser colors (#367, @tootallnate)
  * Misc: travis ci integration (@thebigredgeek)
  * Misc: added linting and testing boilerplate with sanity check (@thebigredgeek)

2.4.1 / 2016-12-13
==================

  * Fix: typo that broke the package (#356)

2.4.0 / 2016-12-13
==================

  * Fix: bower.json references unbuilt src entry point (#342, @justmatt)
  * Fix: revert "handle regex special characters" (@tootallnate)
  * Feature: configurable util.inspect()`options for NodeJS (#327, @tootallnate)
  * Feature: %O`(big O) pretty-prints objects (#322, @tootallnate)
  * Improvement: allow colors in workers (#335, @botverse)
  * Improvement: use same color for same namespace. (#338, @lchenay)

2.3.3 / 2016-11-09
==================

  * Fix: Catch `JSON.stringify()` errors (#195, Jovan Alleyne)
  * Fix: Returning `localStorage` saved values (#331, Levi Thomason)
  * Improvement: Don't create an empty object when no `process` (Nathan Rajlich)

2.3.2 / 2016-11-09
==================

  * Fix: be super-safe in index.js as well (@TooTallNate)
  * Fix: should check whether process exists (Tom Newby)

2.3.1 / 2016-11-09
==================

  * Fix: Added electron compatibility (#324, @paulcbetts)
  * Improvement: Added performance optimizations (@tootallnate)
  * Readme: Corrected PowerShell environment variable example (#252, @gimre)
  * Misc: Removed yarn lock file from source control (#321, @fengmk2)

2.3.0 / 2016-11-07
==================

  * Fix: Consistent placement of ms diff at end of output (#215, @gorangajic)
  * Fix: Escaping of regex special characters in namespace strings (#250, @zacronos)
  * Fix: Fixed bug causing crash on react-native (#282, @vkarpov15)
  * Feature: Enabled ES6+ compatible import via default export (#212 @bucaran)
  * Feature: Added %O formatter to reflect Chrome's console.log capability (#279, @oncletom)
  * Package: Update "ms" to 0.7.2 (#315, @DevSide)
  * Package: removed superfluous version property from bower.json (#207 @kkirsche)
  * Readme: fix USE_COLORS to DEBUG_COLORS
  * Readme: Doc fixes for format string sugar (#269, @mlucool)
  * Readme: Updated docs for DEBUG_FD and DEBUG_COLORS environment variables (#232, @mattlyons0)
  * Readme: doc fixes for PowerShell (#271 #243, @exoticknight @unreadable)
  * Readme: better docs for browser support (#224, @matthewmueller)
  * Tooling: Added yarn integration for development (#317, @thebigredgeek)
  * Misc: Renamed History.md to CHANGELOG.md (@thebigredgeek)
  * Misc: Added license file (#226 #274, @CantemoInternal @sdaitzman)
  * Misc: Updated contributors (@thebigredgeek)

2.2.0 / 2015-05-09
==================

  * package: update "ms" to v0.7.1 (#202, @dougwilson)
  * README: add logging to file example (#193, @DanielOchoa)
  * README: fixed a typo (#191, @amir-s)
  * browser: expose `storage` (#190, @stephenmathieson)
  * Makefile: add a `distclean` target (#189, @stephenmathieson)

2.1.3 / 2015-03-13
==================

  * Updated stdout/stderr example (#186)
  * Updated example/stdout.js to match debug current behaviour
  * Renamed example/stderr.js to stdout.js
  * Update Readme.md (#184)
  * replace high intensity foreground color for bold (#182, #183)

2.1.2 / 2015-03-01
==================

  * dist: recompile
  * update "ms" to v0.7.0
  * package: update "browserify" to v9.0.3
  * component: fix "ms.js" repo location
  * changed bower package name
  * updated documentation about using debug in a browser
  * fix: security error on safari (#167, #168, @yields)

2.1.1 / 2014-12-29
==================

  * browser: use `typeof` to check for `console` existence
  * browser: check for `console.log` truthiness (fix IE 8/9)
  * browser: add support for Chrome apps
  * Readme: added Windows usage remarks
  * Add `bower.json` to properly support bower install

2.1.0 / 2014-10-15
==================

  * node: implement `DEBUG_FD` env variable support
  * package: update "browserify" to v6.1.0
  * package: add "license" field to package.json (#135, @panuhorsmalahti)

2.0.0 / 2014-09-01
==================

  * package: update "browserify" to v5.11.0
  * node: use stderr rather than stdout for logging (#29, @stephenmathieson)

1.0.4 / 2014-07-15
==================

  * dist: recompile
  * example: remove `console.info()` log usage
  * example: add "Content-Type" UTF-8 header to browser example
  * browser: place %c marker after the space character
  * browser: reset the "content" color via `color: inherit`
  * browser: add colors support for Firefox >= v31
  * debug: prefer an instance `log()` function over the global one (#119)
  * Readme: update documentation about styled console logs for FF v31 (#116, @wryk)

1.0.3 / 2014-07-09
==================

  * Add support for multiple wildcards in namespaces (#122, @seegno)
  * browser: fix lint

1.0.2 / 2014-06-10
==================

  * browser: update color palette (#113, @gscottolson)
  * common: make console logging function configurable (#108, @timoxley)
  * node: fix %o colors on old node <= 0.8.x
  * Makefile: find node path using shell/which (#109, @timoxley)

1.0.1 / 2014-06-06
==================

  * browser: use `removeItem()` to clear localStorage
  * browser, node: don't set DEBUG if namespaces is undefined (#107, @leedm777)
  * package: add "contributors" section
  * node: fix comment typo
  * README: list authors

1.0.0 / 2014-06-04
==================

  * make ms diff be global, not be scope
  * debug: ignore empty strings in enable()
  * node: make DEBUG_COLORS able to disable coloring
  * *: export the `colors` array
  * npmignore: don't publish the `dist` dir
  * Makefile: refactor to use browserify
  * package: add "browserify" as a dev dependency
  * Readme: add Web Inspector Colors section
  * node: reset terminal color for the debug content
  * node: map "%o" to `util.inspect()`
  * browser: map "%j" to `JSON.stringify()`
  * debug: add custom "formatters"
  * debug: use "ms" module for humanizing the diff
  * Readme: add "bash" syntax highlighting
  * browser: add Firebug color support
  * browser: add colors for WebKit browsers
  * node: apply log to `console`
  * rewrite: abstract common logic for Node & browsers
  * add .jshintrc file

0.8.1 / 2014-04-14
==================

  * package: re-add the "component" section

0.8.0 / 2014-03-30
==================

  * add `enable()` method for nodejs. Closes #27
  * change from stderr to stdout
  * remove unnecessary index.js file

0.7.4 / 2013-11-13
==================

  * remove "browserify" key from package.json (fixes something in browserify)

0.7.3 / 2013-10-30
==================

  * fix: catch localStorage security error when cookies are blocked (Chrome)
  * add debug(err) support. Closes #46
  * add .browser prop to package.json. Closes #42

0.7.2 / 2013-02-06
==================

  * fix package.json
  * fix: Mobile Safari (private mode) is broken with debug
  * fix: Use unicode to send escape character to shell instead of octal to work with strict mode javascript

0.7.1 / 2013-02-05
==================

  * add repository URL to package.json
  * add DEBUG_COLORED to force colored output
  * add browserify support
  * fix component. Closes #24

0.7.0 / 2012-05-04
==================

  * Added .component to package.json
  * Added debug.component.js build

0.6.0 / 2012-03-16
==================

  * Added support for "-" prefix in DEBUG [Vinay Pulim]
  * Added `.enabled` flag to the node version [TooTallNate]

0.5.0 / 2012-02-02
==================

  * Added: humanize diffs. Closes #8
  * Added `debug.disable()` to the CS variant
  * Removed padding. Closes #10
  * Fixed: persist client-side variant again. Closes #9

0.4.0 / 2012-02-01
==================

  * Added browser variant support for older browsers [TooTallNate]
  * Added `debug.enable('project:*')` to browser variant [TooTallNate]
  * Added padding to diff (moved it to the right)

0.3.0 / 2012-01-26
==================

  * Added millisecond diff when isatty, otherwise UTC string

0.2.0 / 2012-01-22
==================

  * Added wildcard support

0.1.0 / 2011-12-02
==================

  * Added: remove colors unless stderr isatty [TooTallNate]

0.0.1 / 2010-01-03
==================

  * Initial release


---

# debug
[![Build Status](https://travis-ci.org/visionmedia/debug.svg?branch=master)](https://travis-ci.org/visionmedia/debug)  [![Coverage Status](https://coveralls.io/repos/github/visionmedia/debug/badge.svg?branch=master)](https://coveralls.io/github/visionmedia/debug?branch=master)  [![Slack](https://visionmedia-community-slackin.now.sh/badge.svg)](https://visionmedia-community-slackin.now.sh/) [![OpenCollective](https://opencollective.com/debug/backers/badge.svg)](#backers) 
[![OpenCollective](https://opencollective.com/debug/sponsors/badge.svg)](#sponsors)



A tiny node.js debugging utility modelled after node core's debugging technique.

**Discussion around the V3 API is under way [here](https://github.com/visionmedia/debug/issues/370)**

## Installation

```bash
$ npm install debug
```

## Usage

`debug` exposes a function; simply pass this function the name of your module, and it will return a decorated version of `console.error` for you to pass debug statements to. This will allow you to toggle the debug output for different parts of your module as well as the module as a whole.

Example _app.js_:

```js
var debug = require('debug')('http')
  , http = require('http')
  , name = 'My App';

// fake app

debug('booting %s', name);

http.createServer(function(req, res){
  debug(req.method + ' ' + req.url);
  res.end('hello\n');
}).listen(3000, function(){
  debug('listening');
});

// fake worker of some kind

require('./worker');
```

Example _worker.js_:

```js
var debug = require('debug')('worker');

setInterval(function(){
  debug('doing some work');
}, 1000);
```

 The __DEBUG__ environment variable is then used to enable these based on space or comma-delimited names. Here are some examples:

  ![debug http and worker](http://f.cl.ly/items/18471z1H402O24072r1J/Screenshot.png)

  ![debug worker](http://f.cl.ly/items/1X413v1a3M0d3C2c1E0i/Screenshot.png)

#### Windows note

 On Windows the environment variable is set using the `set` command.

 ```cmd
 set DEBUG=*,-not_this
 ```

 Note that PowerShell uses different syntax to set environment variables.

 ```cmd
 $env:DEBUG = "*,-not_this"
  ```

Then, run the program to be debugged as usual.

## Millisecond diff

  When actively developing an application it can be useful to see when the time spent between one `debug()` call and the next. Suppose for example you invoke `debug()` before requesting a resource, and after as well, the "+NNNms" will show you how much time was spent between calls.

  ![](http://f.cl.ly/items/2i3h1d3t121M2Z1A3Q0N/Screenshot.png)

  When stdout is not a TTY, `Date#toUTCString()` is used, making it more useful for logging the debug information as shown below:

  ![](http://f.cl.ly/items/112H3i0e0o0P0a2Q2r11/Screenshot.png)

## Conventions

  If you're using this in one or more of your libraries, you _should_ use the name of your library so that developers may toggle debugging as desired without guessing names. If you have more than one debuggers you _should_ prefix them with your library name and use ":" to separate features. For example "bodyParser" from Connect would then be "connect:bodyParser".

## Wildcards

  The `*` character may be used as a wildcard. Suppose for example your library has debuggers named "connect:bodyParser", "connect:compress", "connect:session", instead of listing all three with `DEBUG=connect:bodyParser,connect:compress,connect:session`, you may simply do `DEBUG=connect:*`, or to run everything using this module simply use `DEBUG=*`.

  You can also exclude specific debuggers by prefixing them with a "-" character.  For example, `DEBUG=*,-connect:*` would include all debuggers except those starting with "connect:".

## Environment Variables

  When running through Node.js, you can set a few environment variables that will
  change the behavior of the debug logging:

| Name      | Purpose                                         |
|-----------|-------------------------------------------------|
| `DEBUG`   | Enables/disables specific debugging namespaces. |
| `DEBUG_COLORS`| Whether or not to use colors in the debug output. |
| `DEBUG_DEPTH` | Object inspection depth. |
| `DEBUG_SHOW_HIDDEN` | Shows hidden properties on inspected objects. |


  __Note:__ The environment variables beginning with `DEBUG_` end up being
  converted into an Options object that gets used with `%o`/`%O` formatters.
  See the Node.js documentation for
  [`util.inspect()`](https://nodejs.org/api/util.html#util_util_inspect_object_options)
  for the complete list.

## Formatters


  Debug uses [printf-style](https://wikipedia.org/wiki/Printf_format_string) formatting. Below are the officially supported formatters:

| Formatter | Representation |
|-----------|----------------|
| `%O`      | Pretty-print an Object on multiple lines. |
| `%o`      | Pretty-print an Object all on a single line. |
| `%s`      | String. |
| `%d`      | Number (both integer and float). |
| `%j`      | JSON. Replaced with the string '[Circular]' if the argument contains circular references. |
| `%%`      | Single percent sign ('%'). This does not consume an argument. |

### Custom formatters

  You can add custom formatters by extending the `debug.formatters` object. For example, if you wanted to add support for rendering a Buffer as hex with `%h`, you could do something like:

```js
const createDebug = require('debug')
createDebug.formatters.h = (v) => {
  return v.toString('hex')
}

// …elsewhere
const debug = createDebug('foo')
debug('this is hex: %h', new Buffer('hello world'))
//   foo this is hex: 68656c6c6f20776f726c6421 +0ms
```

## Browser support
  You can build a browser-ready script using [browserify](https://github.com/substack/node-browserify),
  or just use the [browserify-as-a-service](https://wzrd.in/) [build](https://wzrd.in/standalone/debug@latest),
  if you don't want to build it yourself.

  Debug's enable state is currently persisted by `localStorage`.
  Consider the situation shown below where you have `worker:a` and `worker:b`,
  and wish to debug both. You can enable this using `localStorage.debug`:

```js
localStorage.debug = 'worker:*'
```

And then refresh the page.

```js
a = debug('worker:a');
b = debug('worker:b');

setInterval(function(){
  a('doing some work');
}, 1000);

setInterval(function(){
  b('doing some work');
}, 1200);
```

#### Web Inspector Colors

  Colors are also enabled on "Web Inspectors" that understand the `%c` formatting
  option. These are WebKit web inspectors, Firefox ([since version
  31](https://hacks.mozilla.org/2014/05/editable-box-model-multiple-selection-sublime-text-keys-much-more-firefox-developer-tools-episode-31/))
  and the Firebug plugin for Firefox (any version).

  Colored output looks something like:

  ![](https://cloud.githubusercontent.com/assets/71256/3139768/b98c5fd8-e8ef-11e3-862a-f7253b6f47c6.png)


## Output streams

  By default `debug` will log to stderr, however this can be configured per-namespace by overriding the `log` method:

Example _stdout.js_:

```js
var debug = require('debug');
var error = debug('app:error');

// by default stderr is used
error('goes to stderr!');

var log = debug('app:log');
// set this namespace to log via console.log
log.log = console.log.bind(console); // don't forget to bind to console!
log('goes to stdout');
error('still goes to stderr!');

// set all output to go via console.info
// overrides all per-namespace log settings
debug.log = console.info.bind(console);
error('now goes to stdout via console.info');
log('still goes to stdout, but via console.info now');
```


## Authors

 - TJ Holowaychuk
 - Nathan Rajlich
 - Andrew Rhyne
 
## Backers

Support us with a monthly donation and help us continue our activities. [[Become a backer](https://opencollective.com/debug#backer)]

<a href="https://opencollective.com/debug/backer/0/website" target="_blank"><img src="https://opencollective.com/debug/backer/0/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/1/website" target="_blank"><img src="https://opencollective.com/debug/backer/1/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/2/website" target="_blank"><img src="https://opencollective.com/debug/backer/2/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/3/website" target="_blank"><img src="https://opencollective.com/debug/backer/3/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/4/website" target="_blank"><img src="https://opencollective.com/debug/backer/4/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/5/website" target="_blank"><img src="https://opencollective.com/debug/backer/5/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/6/website" target="_blank"><img src="https://opencollective.com/debug/backer/6/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/7/website" target="_blank"><img src="https://opencollective.com/debug/backer/7/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/8/website" target="_blank"><img src="https://opencollective.com/debug/backer/8/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/9/website" target="_blank"><img src="https://opencollective.com/debug/backer/9/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/10/website" target="_blank"><img src="https://opencollective.com/debug/backer/10/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/11/website" target="_blank"><img src="https://opencollective.com/debug/backer/11/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/12/website" target="_blank"><img src="https://opencollective.com/debug/backer/12/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/13/website" target="_blank"><img src="https://opencollective.com/debug/backer/13/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/14/website" target="_blank"><img src="https://opencollective.com/debug/backer/14/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/15/website" target="_blank"><img src="https://opencollective.com/debug/backer/15/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/16/website" target="_blank"><img src="https://opencollective.com/debug/backer/16/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/17/website" target="_blank"><img src="https://opencollective.com/debug/backer/17/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/18/website" target="_blank"><img src="https://opencollective.com/debug/backer/18/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/19/website" target="_blank"><img src="https://opencollective.com/debug/backer/19/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/20/website" target="_blank"><img src="https://opencollective.com/debug/backer/20/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/21/website" target="_blank"><img src="https://opencollective.com/debug/backer/21/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/22/website" target="_blank"><img src="https://opencollective.com/debug/backer/22/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/23/website" target="_blank"><img src="https://opencollective.com/debug/backer/23/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/24/website" target="_blank"><img src="https://opencollective.com/debug/backer/24/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/25/website" target="_blank"><img src="https://opencollective.com/debug/backer/25/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/26/website" target="_blank"><img src="https://opencollective.com/debug/backer/26/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/27/website" target="_blank"><img src="https://opencollective.com/debug/backer/27/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/28/website" target="_blank"><img src="https://opencollective.com/debug/backer/28/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/29/website" target="_blank"><img src="https://opencollective.com/debug/backer/29/avatar.svg"></a>


## Sponsors

Become a sponsor and get your logo on our README on Github with a link to your site. [[Become a sponsor](https://opencollective.com/debug#sponsor)]

<a href="https://opencollective.com/debug/sponsor/0/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/0/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/1/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/1/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/2/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/2/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/3/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/3/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/4/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/4/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/5/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/5/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/6/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/6/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/7/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/7/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/8/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/8/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/9/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/9/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/10/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/10/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/11/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/11/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/12/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/12/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/13/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/13/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/14/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/14/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/15/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/15/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/16/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/16/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/17/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/17/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/18/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/18/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/19/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/19/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/20/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/20/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/21/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/21/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/22/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/22/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/23/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/23/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/24/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/24/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/25/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/25/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/26/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/26/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/27/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/27/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/28/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/28/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/29/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/29/avatar.svg"></a>

## License

(The MIT License)

Copyright (c) 2014-2016 TJ Holowaychuk &lt;tj@vision-media.ca&gt;

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
'Software'), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


---

The MIT License (MIT)

Copyright (c) 2016 Zeit, Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# ms

[![Build Status](https://travis-ci.org/zeit/ms.svg?branch=master)](https://travis-ci.org/zeit/ms)
[![Slack Channel](http://zeit-slackin.now.sh/badge.svg)](https://zeit.chat/)

Use this package to easily convert various time formats to milliseconds.

## Examples

```js
ms('2 days')  // 172800000
ms('1d')      // 86400000
ms('10h')     // 36000000
ms('2.5 hrs') // 9000000
ms('2h')      // 7200000
ms('1m')      // 60000
ms('5s')      // 5000
ms('1y')      // 31557600000
ms('100')     // 100
```

### Convert from milliseconds

```js
ms(60000)             // "1m"
ms(2 * 60000)         // "2m"
ms(ms('10 hours'))    // "10h"
```

### Time format written-out

```js
ms(60000, { long: true })             // "1 minute"
ms(2 * 60000, { long: true })         // "2 minutes"
ms(ms('10 hours'), { long: true })    // "10 hours"
```

## Features

- Works both in [node](https://nodejs.org) and in the browser.
- If a number is supplied to `ms`, a string with a unit is returned.
- If a string that contains the number is supplied, it returns it as a number (e.g.: it returns `100` for `'100'`).
- If you pass a string with a number and a valid unit, the number of equivalent ms is returned.

## Caught a bug?

1. [Fork](https://help.github.com/articles/fork-a-repo/) this repository to your own GitHub account and then [clone](https://help.github.com/articles/cloning-a-repository/) it to your local device
2. Link the package to the global module directory: `npm link`
3. Within the module you want to test your local development instance of ms, just link it to the dependencies: `npm link ms`. Instead of the default one from npm, node will now use your clone of ms!

As always, you can run the tests using: `npm test`


---

1.0.2 / 2018-01-21
==================

  * Fix encoding `%` as last character

1.0.1 / 2016-06-09
==================

  * Fix encoding unpaired surrogates at start/end of string

1.0.0 / 2016-06-08
==================

  * Initial release


---

# encodeurl

[![NPM Version][npm-image]][npm-url]
[![NPM Downloads][downloads-image]][downloads-url]
[![Node.js Version][node-version-image]][node-version-url]
[![Build Status][travis-image]][travis-url]
[![Test Coverage][coveralls-image]][coveralls-url]

Encode a URL to a percent-encoded form, excluding already-encoded sequences

## Installation

This is a [Node.js](https://nodejs.org/en/) module available through the
[npm registry](https://www.npmjs.com/). Installation is done using the
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):

```sh
$ npm install encodeurl
```

## API

```js
var encodeUrl = require('encodeurl')
```

### encodeUrl(url)

Encode a URL to a percent-encoded form, excluding already-encoded sequences.

This function will take an already-encoded URL and encode all the non-URL
code points (as UTF-8 byte sequences). This function will not encode the
"%" character unless it is not part of a valid sequence (`%20` will be
left as-is, but `%foo` will be encoded as `%25foo`).

This encode is meant to be "safe" and does not throw errors. It will try as
hard as it can to properly encode the given URL, including replacing any raw,
unpaired surrogate pairs with the Unicode replacement character prior to
encoding.

This function is _similar_ to the intrinsic function `encodeURI`, except it
will not encode the `%` character if that is part of a valid sequence, will
not encode `[` and `]` (for IPv6 hostnames) and will replace raw, unpaired
surrogate pairs with the Unicode replacement character (instead of throwing).

## Examples

### Encode a URL containing user-controled data

```js
var encodeUrl = require('encodeurl')
var escapeHtml = require('escape-html')

http.createServer(function onRequest (req, res) {
  // get encoded form of inbound url
  var url = encodeUrl(req.url)

  // create html message
  var body = '<p>Location ' + escapeHtml(url) + ' not found</p>'

  // send a 404
  res.statusCode = 404
  res.setHeader('Content-Type', 'text/html; charset=UTF-8')
  res.setHeader('Content-Length', String(Buffer.byteLength(body, 'utf-8')))
  res.end(body, 'utf-8')
})
```

### Encode a URL for use in a header field

```js
var encodeUrl = require('encodeurl')
var escapeHtml = require('escape-html')
var url = require('url')

http.createServer(function onRequest (req, res) {
  // parse inbound url
  var href = url.parse(req)

  // set new host for redirect
  href.host = 'localhost'
  href.protocol = 'https:'
  href.slashes = true

  // create location header
  var location = encodeUrl(url.format(href))

  // create html message
  var body = '<p>Redirecting to new site: ' + escapeHtml(location) + '</p>'

  // send a 301
  res.statusCode = 301
  res.setHeader('Content-Type', 'text/html; charset=UTF-8')
  res.setHeader('Content-Length', String(Buffer.byteLength(body, 'utf-8')))
  res.setHeader('Location', location)
  res.end(body, 'utf-8')
})
```

## Testing

```sh
$ npm test
$ npm run lint
```

## References

- [RFC 3986: Uniform Resource Identifier (URI): Generic Syntax][rfc-3986]
- [WHATWG URL Living Standard][whatwg-url]

[rfc-3986]: https://tools.ietf.org/html/rfc3986
[whatwg-url]: https://url.spec.whatwg.org/

## License

[MIT](LICENSE)

[npm-image]: https://img.shields.io/npm/v/encodeurl.svg
[npm-url]: https://npmjs.org/package/encodeurl
[node-version-image]: https://img.shields.io/node/v/encodeurl.svg
[node-version-url]: https://nodejs.org/en/download
[travis-image]: https://img.shields.io/travis/pillarjs/encodeurl.svg
[travis-url]: https://travis-ci.org/pillarjs/encodeurl
[coveralls-image]: https://img.shields.io/coveralls/pillarjs/encodeurl.svg
[coveralls-url]: https://coveralls.io/r/pillarjs/encodeurl?branch=master
[downloads-image]: https://img.shields.io/npm/dm/encodeurl.svg
[downloads-url]: https://npmjs.org/package/encodeurl


---

The MIT License (MIT)

Copyright (c) 2020 Vercel, Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# ms

![CI](https://github.com/vercel/ms/workflows/CI/badge.svg)

Use this package to easily convert various time formats to milliseconds.

## Examples

```js
ms('2 days')  // 172800000
ms('1d')      // 86400000
ms('10h')     // 36000000
ms('2.5 hrs') // 9000000
ms('2h')      // 7200000
ms('1m')      // 60000
ms('5s')      // 5000
ms('1y')      // 31557600000
ms('100')     // 100
ms('-3 days') // -259200000
ms('-1h')     // -3600000
ms('-200')    // -200
```

### Convert from Milliseconds

```js
ms(60000)             // "1m"
ms(2 * 60000)         // "2m"
ms(-3 * 60000)        // "-3m"
ms(ms('10 hours'))    // "10h"
```

### Time Format Written-Out

```js
ms(60000, { long: true })             // "1 minute"
ms(2 * 60000, { long: true })         // "2 minutes"
ms(-3 * 60000, { long: true })        // "-3 minutes"
ms(ms('10 hours'), { long: true })    // "10 hours"
```

## Features

- Works both in [Node.js](https://nodejs.org) and in the browser
- If a number is supplied to `ms`, a string with a unit is returned
- If a string that contains the number is supplied, it returns it as a number (e.g.: it returns `100` for `'100'`)
- If you pass a string with a number and a valid unit, the number of equivalent milliseconds is returned

## Related Packages

- [ms.macro](https://github.com/knpwrs/ms.macro) - Run `ms` as a macro at build-time.

## Caught a Bug?

1. [Fork](https://help.github.com/articles/fork-a-repo/) this repository to your own GitHub account and then [clone](https://help.github.com/articles/cloning-a-repository/) it to your local device
2. Link the package to the global module directory: `npm link`
3. Within the module you want to test your local development instance of ms, just link it to the dependencies: `npm link ms`. Instead of the default one from npm, Node.js will now use your clone of ms!

As always, you can run the tests using: `npm test`


---

1.2.1 / 2019-05-10
==================

  * Improve error when `str` is not a string

1.2.0 / 2016-06-01
==================

  * Add `combine` option to combine overlapping ranges

1.1.0 / 2016-05-13
==================

  * Fix incorrectly returning -1 when there is at least one valid range
  * perf: remove internal function

1.0.3 / 2015-10-29
==================

  * perf: enable strict mode

1.0.2 / 2014-09-08
==================

  * Support Node.js 0.6

1.0.1 / 2014-09-07
==================

  * Move repository to jshttp

1.0.0 / 2013-12-11
==================

  * Add repository to package.json
  * Add MIT license

0.0.4 / 2012-06-17
==================

  * Change ret -1 for unsatisfiable and -2 when invalid

0.0.3 / 2012-06-17
==================

  * Fix last-byte-pos default to len - 1

0.0.2 / 2012-06-14
==================

  * Add `.type`

0.0.1 / 2012-06-11
==================

  * Initial release


---

# range-parser

[![NPM Version][npm-version-image]][npm-url]
[![NPM Downloads][npm-downloads-image]][npm-url]
[![Node.js Version][node-image]][node-url]
[![Build Status][travis-image]][travis-url]
[![Test Coverage][coveralls-image]][coveralls-url]

Range header field parser.

## Installation

This is a [Node.js](https://nodejs.org/en/) module available through the
[npm registry](https://www.npmjs.com/). Installation is done using the
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):

```sh
$ npm install range-parser
```

## API

<!-- eslint-disable no-unused-vars -->

```js
var parseRange = require('range-parser')
```

### parseRange(size, header, options)

Parse the given `header` string where `size` is the maximum size of the resource.
An array of ranges will be returned or negative numbers indicating an error parsing.

  * `-2` signals a malformed header string
  * `-1` signals an unsatisfiable range

<!-- eslint-disable no-undef -->

```js
// parse header from request
var range = parseRange(size, req.headers.range)

// the type of the range
if (range.type === 'bytes') {
  // the ranges
  range.forEach(function (r) {
    // do something with r.start and r.end
  })
}
```

#### Options

These properties are accepted in the options object.

##### combine

Specifies if overlapping & adjacent ranges should be combined, defaults to `false`.
When `true`, ranges will be combined and returned as if they were specified that
way in the header.

<!-- eslint-disable no-undef -->

```js
parseRange(100, 'bytes=50-55,0-10,5-10,56-60', { combine: true })
// => [
//      { start: 0,  end: 10 },
//      { start: 50, end: 60 }
//    ]
```

## License

[MIT](LICENSE)

[coveralls-image]: https://badgen.net/coveralls/c/github/jshttp/range-parser/master
[coveralls-url]: https://coveralls.io/r/jshttp/range-parser?branch=master
[node-image]: https://badgen.net/npm/node/range-parser
[node-url]: https://nodejs.org/en/download
[npm-downloads-image]: https://badgen.net/npm/dm/range-parser
[npm-url]: https://npmjs.org/package/range-parser
[npm-version-image]: https://badgen.net/npm/v/range-parser
[travis-image]: https://badgen.net/travis/jshttp/range-parser/master
[travis-url]: https://travis-ci.org/jshttp/range-parser


---

Serialize JavaScript
====================

Serialize JavaScript to a _superset_ of JSON that includes regular expressions, dates and functions.

[![npm Version][npm-badge]][npm]
[![Dependency Status][david-badge]][david]
![Test](https://github.com/yahoo/serialize-javascript/workflows/Test/badge.svg)

## Overview

The code in this package began its life as an internal module to [express-state][]. To expand its usefulness, it now lives as `serialize-javascript` — an independent package on npm.

You're probably wondering: **What about `JSON.stringify()`!?** We've found that sometimes we need to serialize JavaScript **functions**, **regexps**, **dates**, **sets** or **maps**. A great example is a web app that uses client-side URL routing where the route definitions are regexps that need to be shared from the server to the client. But this module is also great for communicating between node processes.

The string returned from this package's single export function is literal JavaScript which can be saved to a `.js` file, or be embedded into an HTML document by making the content of a `<script>` element.

> **HTML characters and JavaScript line terminators are escaped automatically.**

Please note that serialization for ES6 Sets & Maps requires support for `Array.from` (not available in IE or Node < 0.12), or an `Array.from` polyfill.

## Installation

Install using npm:

```shell
$ npm install serialize-javascript
```

## Usage

```js
var serialize = require('serialize-javascript');

serialize({
    str  : 'string',
    num  : 0,
    obj  : {foo: 'foo'},
    arr  : [1, 2, 3],
    bool : true,
    nil  : null,
    undef: undefined,
    inf  : Infinity,
    date : new Date("Thu, 28 Apr 2016 22:02:17 GMT"),
    map  : new Map([['hello', 'world']]),
    set  : new Set([123, 456]),
    fn   : function echo(arg) { return arg; },
    re   : /([^\s]+)/g,
    big  : BigInt(10),
    url  : new URL('https://example.com/'),
});
```

The above will produce the following string output:

```js
'{"str":"string","num":0,"obj":{"foo":"foo"},"arr":[1,2,3],"bool":true,"nil":null,"undef":undefined,"inf":Infinity,"date":new Date("2016-04-28T22:02:17.000Z"),"map":new Map([["hello","world"]]),"set":new Set([123,456]),"fn":function echo(arg) { return arg; },"re":new RegExp("([^\\\\s]+)", "g"),"big":BigInt("10"),"url":new URL("https://example.com/")}'
```

Note: to produce a beautified string, you can pass an optional second argument to `serialize()` to define the number of spaces to be used for the indentation.

### Automatic Escaping of HTML Characters

A primary feature of this package is to serialize code to a string of literal JavaScript which can be embedded in an HTML document by adding it as the contents of the `<script>` element. In order to make this safe, HTML characters and JavaScript line terminators are escaped automatically.

```js
serialize({
    haxorXSS: '</script>'
});
```

The above will produce the following string, HTML-escaped output which is safe to put into an HTML document as it will not cause the inline script element to terminate:

```js
'{"haxorXSS":"\\u003C\\u002Fscript\\u003E"}'
```

> You can pass an optional `unsafe` argument to `serialize()` for straight serialization.

### Options

The `serialize()` function accepts an `options` object as its second argument. All options are being defaulted to `undefined`:

#### `options.space`

This option is the same as the `space` argument that can be passed to [`JSON.stringify`][JSON.stringify]. It can be used to add whitespace and indentation to the serialized output to make it more readable.

```js
serialize(obj, {space: 2});
```

#### `options.isJSON`

This option is a signal to `serialize()` that the object being serialized does not contain any function or regexps values. This enables a hot-path that allows serialization to be over 3x faster. If you're serializing a lot of data, and know its pure JSON, then you can enable this option for a speed-up.

**Note:** That when using this option, the output will still be escaped to protect against XSS.

```js
serialize(obj, {isJSON: true});
```

#### `options.unsafe`

This option is to signal `serialize()` that we want to do a straight conversion, without the XSS protection. This options needs to be explicitly set to `true`. HTML characters and JavaScript line terminators will not be escaped. You will have to roll your own.

```js
serialize(obj, {unsafe: true});
```

#### `options.ignoreFunction`

This option is to signal `serialize()` that we do not want serialize JavaScript function. 
Just treat function like `JSON.stringify` do, but other features will work as expected.

```js
serialize(obj, {ignoreFunction: true});
```

## Deserializing

For some use cases you might also need to deserialize the string. This is explicitly not part of this module. However, you can easily write it yourself:

```js
function deserialize(serializedJavascript){
  return eval('(' + serializedJavascript + ')');
}
```

**Note:** Don't forget the parentheses around the serialized javascript, as the opening bracket `{` will be considered to be the start of a body.

## License

This software is free to use under the Yahoo! Inc. BSD license.
See the [LICENSE file][LICENSE] for license text and copyright information.


[npm]: https://www.npmjs.org/package/serialize-javascript
[npm-badge]: https://img.shields.io/npm/v/serialize-javascript.svg?style=flat-square
[david]: https://david-dm.org/yahoo/serialize-javascript
[david-badge]: https://img.shields.io/david/yahoo/serialize-javascript.svg?style=flat-square
[express-state]: https://github.com/yahoo/express-state
[JSON.stringify]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify
[LICENSE]: https://github.com/yahoo/serialize-javascript/blob/main/LICENSE


---

# serve-handler

[![Tests](https://github.com/vercel/serve-handler/actions/workflows/tests.yaml/badge.svg)](https://github.com/vercel/serve-handler/actions/workflows/tests.yaml)
[![codecov](https://codecov.io/gh/vercel/serve-handler/branch/main/graph/badge.svg)](https://codecov.io/gh/vercel/serve-handler)
[![install size](https://packagephobia.now.sh/badge?p=serve-handler)](https://packagephobia.now.sh/result?p=serve-handler)

This package represents the core of [serve](https://github.com/vercel/serve). It can be plugged into any HTTP server and is responsible for routing requests and handling responses.

In order to customize the default behaviour, you can also pass custom routing rules, provide your own methods for interacting with the file system and much more.

## Usage

Get started by installing the package using [yarn](https://yarnpkg.com/lang/en/):

```sh
yarn add serve-handler
```

You can also use [npm](https://www.npmjs.com/) instead, if you'd like:

```sh
npm install serve-handler
```

Next, add it to your HTTP server. Here's an example using [micro](https://github.com/vercel/micro):

```js
const handler = require('serve-handler');

module.exports = async (request, response) => {
  await handler(request, response);
};
```

That's it! :tada:

## Options

If you want to customize the package's default behaviour, you can use the third argument of the function call to pass any of the configuration options listed below. Here's an example:

```js
await handler(request, response, {
  cleanUrls: true
});
```

You can use any of the following options:

| Property                                             | Description                                                           |
|------------------------------------------------------|-----------------------------------------------------------------------|
| [`public`](#public-string)                           | Set a sub directory to be served                                      |
| [`cleanUrls`](#cleanurls-booleanarray)               | Have the `.html` extension stripped from paths                        |
| [`rewrites`](#rewrites-array)                        | Rewrite paths to different paths                                      |
| [`redirects`](#redirects-array)                      | Forward paths to different paths or external URLs                     |
| [`headers`](#headers-array)                          | Set custom headers for specific paths                                 |
| [`directoryListing`](#directorylisting-booleanarray) | Disable directory listing or restrict it to certain paths             |
| [`unlisted`](#unlisted-array)                        | Exclude paths from the directory listing                              |
| [`trailingSlash`](#trailingslash-boolean)            | Remove or add trailing slashes to all paths                           |
| [`renderSingle`](#rendersingle-boolean)              | If a directory only contains one file, render it                      |
| [`symlinks`](#symlinks-boolean)                      | Resolve symlinks instead of rendering a 404 error                     |
| [`etag`](#etag-boolean)                              | Calculate a strong `ETag` response header, instead of `Last-Modified` |

### public (String)

By default, the current working directory will be served. If you only want to serve a specific path, you can use this options to pass an absolute path or a custom directory to be served relative to the current working directory.

For example, if serving a [Jekyll](https://jekyllrb.com/) app, it would look like this:

```json
{
  "public": "_site"
}
```

Using absolute path:

```json
{
  "public": "/path/to/your/_site"
}
```

**NOTE:** The path cannot contain globs or regular expressions.

### cleanUrls (Boolean|Array)

By default, all `.html` files can be accessed without their extension.

If one of these extensions is used at the end of a filename, it will automatically perform a redirect with status code [301](https://en.wikipedia.org/wiki/HTTP_301) to the same path, but with the extension dropped.

You can disable the feature like follows:

```json
{
  "cleanUrls": false
}
```

However, you can also restrict it to certain paths:

```json
{
  "cleanUrls": [
    "/app/**",
    "/!components/**"
  ]
}
```

**NOTE:** The paths can only contain globs that are matched using [minimatch](https://github.com/isaacs/minimatch).

### rewrites (Array)

If you want your visitors to receive a response under a certain path, but actually serve a completely different one behind the curtains, this option is what you need.

It's perfect for [single page applications](https://en.wikipedia.org/wiki/Single-page_application) (SPAs), for example:

```json
{
  "rewrites": [
    { "source": "app/**", "destination": "/index.html" },
    { "source": "projects/*/edit", "destination": "/edit-project.html" }
  ]
}
```

You can also use so-called "routing segments" as follows:

```json
{
  "rewrites": [
    { "source": "/projects/:id/edit", "destination": "/edit-project-:id.html" },
  ]
}
```

Now, if a visitor accesses `/projects/123/edit`, it will respond with the file `/edit-project-123.html`.

**NOTE:** The paths can contain globs (matched using [minimatch](https://github.com/isaacs/minimatch)) or regular expressions (match using [path-to-regexp](https://github.com/pillarjs/path-to-regexp)).

### redirects (Array)

In order to redirect visits to a certain path to a different one (or even an external URL), you can use this option:

```json
{
  "redirects": [
    { "source": "/from", "destination": "/to" },
    { "source": "/old-pages/**", "destination": "/home" }
  ]
}
```

By default, all of them are performed with the status code [301](https://en.wikipedia.org/wiki/HTTP_301), but this behavior can be adjusted by setting the `type` property directly on the object (see below).

Just like with [rewrites](#rewrites-array), you can also use routing segments:

```json
{
  "redirects": [
    { "source": "/old-docs/:id", "destination": "/new-docs/:id" },
    { "source": "/old", "destination": "/new", "type": 302 }
  ]
}
```

In the example above, `/old-docs/12` would be forwarded to `/new-docs/12` with status code [301](https://en.wikipedia.org/wiki/HTTP_301). In addition `/old` would be forwarded to `/new` with status code [302](https://en.wikipedia.org/wiki/HTTP_302).

**NOTE:** The paths can contain globs (matched using [minimatch](https://github.com/isaacs/minimatch)) or regular expressions (match using [path-to-regexp](https://github.com/pillarjs/path-to-regexp)).

### headers (Array)

Allows you to set custom headers (and overwrite the default ones) for certain paths:

```json
{
  "headers": [
    {
      "source" : "**/*.@(jpg|jpeg|gif|png)",
      "headers" : [{
        "key" : "Cache-Control",
        "value" : "max-age=7200"
      }]
    }, {
      "source" : "404.html",
      "headers" : [{
        "key" : "Cache-Control",
        "value" : "max-age=300"
      }]
    }
  ]
}
```

If you define the `ETag` header for a path, the handler will automatically reply with status code `304` for that path if a request comes in with a matching `If-None-Match` header.

If you set a header `value` to `null` it removes any previous defined header with the same key.

**NOTE:** The paths can only contain globs that are matched using [minimatch](https://github.com/isaacs/minimatch).

### directoryListing (Boolean|Array)

For paths are not files, but directories, the package will automatically render a good-looking list of all the files and directories contained inside that directory.

If you'd like to disable this for all paths, set this option to `false`. Furthermore, you can also restrict it to certain directory paths if you want:

```json
{
  "directoryListing": [
    "/assets/**",
    "/!assets/private"
  ]
}
```

**NOTE:** The paths can only contain globs that are matched using [minimatch](https://github.com/isaacs/minimatch).

### unlisted (Array)

In certain cases, you might not want a file or directory to appear in the directory listing. In these situations, there are two ways of solving this problem.

Either you disable the directory listing entirely (like shown [here](#directorylisting-booleanarray)), or you exclude certain paths from those listings by adding them all to this config property.

```json
{
  "unlisted": [
    ".DS_Store",
    ".git"
  ]
}
```

The items shown above are excluded from the directory listing by default.

**NOTE:** The paths can only contain globs that are matched using [minimatch](https://github.com/isaacs/minimatch).

### trailingSlash (Boolean)

By default, the package will try to make assumptions for when to add trailing slashes to your URLs or not. If you want to remove them, set this property to `false` and `true` if you want to force them on all URLs:

```js
{
  "trailingSlash": true
}
```

With the above config, a request to `/test` would now result in a [301](https://en.wikipedia.org/wiki/HTTP_301) redirect to `/test/`.

### renderSingle (Boolean)

Sometimes you might want to have a directory path actually render a file, if the directory only contains one. This is only useful for any files that are not `.html` files (for those, [`cleanUrls`](#cleanurls-booleanarray) is faster).

This is disabled by default and can be enabled like this:

```js
{
  "renderSingle": true
}
```

After that, if you access your directory `/test` (for example), you will see an image being rendered if the directory contains a single image file.

### symlinks (Boolean)

For security purposes, symlinks are disabled by default. If `serve-handler` encounters a symlink, it will treat it as if it doesn't exist in the first place. In turn, a 404 error is rendered for that path.

However, this behavior can easily be adjusted:

```js
{
  "symlinks": true
}
```

Once this property is set as shown above, all symlinks will automatically be resolved to their targets.

### etag (Boolean)

HTTP response headers will contain a strong [`ETag`][etag] response header, instead of a [`Last-Modified`][last-modified] header. Opt-in because calculating the hash value may be computationally expensive for large files.

Sending an `ETag` header is disabled by default and can be enabled like this:

```js
{
  "etag": true
}
```

## Error templates

The handler will automatically determine the right error format if one occurs and then sends it to the client in that format.

Furthermore, this allows you to not just specifiy an error template for `404` errors, but also for all other errors that can occur (e.g. `400` or `500`).

Just add a `<status-code>.html` file to the root directory and you're good.

## Middleware

If you want to replace the methods the package is using for interacting with the file system and sending responses, you can pass them as the fourth argument to the function call.

These are the methods used by the package (they can all return a `Promise` or be asynchronous):

```js
await handler(request, response, undefined, {
  lstat(path) {},
  realpath(path) {},
  createReadStream(path, config) {}
  readdir(path) {},
  sendError(absolutePath, response, acceptsJSON, root, handlers, config, error) {}
});
```

**NOTE:** It's important that – for native methods like `createReadStream` – all arguments are passed on to the native call.

## Author

Leo Lamprecht ([@leo](https://x.com/leo)) - [Vercel](https://vercel.com)


[etag]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag
[last-modified]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Last-Modified


---

# Path-to-RegExp

> Turn a path string such as `/user/:name` into a regular expression.

[![NPM version][npm-image]][npm-url]
[![Build status][travis-image]][travis-url]
[![Test coverage][coveralls-image]][coveralls-url]
[![Dependency Status][david-image]][david-url]
[![License][license-image]][license-url]
[![Downloads][downloads-image]][downloads-url]

## Installation

```
npm install path-to-regexp --save
```

## Usage

```javascript
const pathToRegexp = require('path-to-regexp')

// pathToRegexp(path, keys?, options?)
// pathToRegexp.match(path)
// pathToRegexp.parse(path)
// pathToRegexp.compile(path)
```

- **path** A string, array of strings, or a regular expression.
- **keys** An array to populate with keys found in the path.
- **options**
  - **sensitive** When `true` the regexp will be case sensitive. (default: `false`)
  - **strict** When `true` the regexp allows an optional trailing delimiter to match. (default: `false`)
  - **end** When `true` the regexp will match to the end of the string. (default: `true`)
  - **start** When `true` the regexp will match from the beginning of the string. (default: `true`)
  - **delimiter** The default delimiter for segments. (default: `'/'`)
  - **endsWith** Optional character, or list of characters, to treat as "end" characters.
  - **whitelist** List of characters to consider delimiters when parsing. (default: `undefined`, any character)

```javascript
const keys = []
const regexp = pathToRegexp('/foo/:bar', keys)
// regexp = /^\/foo\/([^\/]+?)\/?$/i
// keys = [{ name: 'bar', prefix: '/', delimiter: '/', optional: false, repeat: false, pattern: '[^\\/]+?' }]
```

**Please note:** The `RegExp` returned by `path-to-regexp` is intended for ordered data (e.g. pathnames, hostnames). It can not handle arbitrarily ordered data (e.g. query strings, URL fragments, JSON, etc).

### Parameters

The path argument is used to define parameters and populate the list of keys.

#### Named Parameters

Named parameters are defined by prefixing a colon to the parameter name (`:foo`). By default, the parameter will match until the next prefix (e.g. `[^/]+`).

```js
const regexp = pathToRegexp('/:foo/:bar')
// keys = [{ name: 'foo', prefix: '/', ... }, { name: 'bar', prefix: '/', ... }]

regexp.exec('/test/route')
//=> [ '/test/route', 'test', 'route', index: 0, input: '/test/route', groups: undefined ]
```

**Please note:** Parameter names must use "word characters" (`[A-Za-z0-9_]`).

#### Parameter Modifiers

##### Optional

Parameters can be suffixed with a question mark (`?`) to make the parameter optional.

```js
const regexp = pathToRegexp('/:foo/:bar?')
// keys = [{ name: 'foo', ... }, { name: 'bar', delimiter: '/', optional: true, repeat: false }]

regexp.exec('/test')
//=> [ '/test', 'test', undefined, index: 0, input: '/test', groups: undefined ]

regexp.exec('/test/route')
//=> [ '/test/route', 'test', 'route', index: 0, input: '/test/route', groups: undefined ]
```

**Tip:** The prefix is also optional, escape the prefix `\/` to make it required.

##### Zero or more

Parameters can be suffixed with an asterisk (`*`) to denote a zero or more parameter matches. The prefix is used for each match.

```js
const regexp = pathToRegexp('/:foo*')
// keys = [{ name: 'foo', delimiter: '/', optional: true, repeat: true }]

regexp.exec('/')
//=> [ '/', undefined, index: 0, input: '/', groups: undefined ]

regexp.exec('/bar/baz')
//=> [ '/bar/baz', 'bar/baz', index: 0, input: '/bar/baz', groups: undefined ]
```

##### One or more

Parameters can be suffixed with a plus sign (`+`) to denote a one or more parameter matches. The prefix is used for each match.

```js
const regexp = pathToRegexp('/:foo+')
// keys = [{ name: 'foo', delimiter: '/', optional: false, repeat: true }]

regexp.exec('/')
//=> null

regexp.exec('/bar/baz')
//=> [ '/bar/baz','bar/baz', index: 0, input: '/bar/baz', groups: undefined ]
```

#### Unnamed Parameters

It is possible to write an unnamed parameter that only consists of a matching group. It works the same as a named parameter, except it will be numerically indexed.

```js
const regexp = pathToRegexp('/:foo/(.*)')
// keys = [{ name: 'foo', ... }, { name: 0, ... }]

regexp.exec('/test/route')
//=> [ '/test/route', 'test', 'route', index: 0, input: '/test/route', groups: undefined ]
```

#### Custom Matching Parameters

All parameters can have a custom regexp, which overrides the default match (`[^/]+`). For example, you can match digits or names in a path:

```js
const regexpNumbers = pathToRegexp('/icon-:foo(\\d+).png')
// keys = [{ name: 'foo', ... }]

regexpNumbers.exec('/icon-123.png')
//=> ['/icon-123.png', '123']

regexpNumbers.exec('/icon-abc.png')
//=> null

const regexpWord = pathToRegexp('/(user|u)')
// keys = [{ name: 0, ... }]

regexpWord.exec('/u')
//=> ['/u', 'u']

regexpWord.exec('/users')
//=> null
```

**Tip:** Backslashes need to be escaped with another backslash in JavaScript strings.

### Match

The `match` function will return a function for transforming paths into parameters:

```js
const match = pathToRegexp.match('/user/:id')

match('/user/123') //=> { path: '/user/123', index: 0, params: { id: '123' } }
match('/invalid') //=> false
```

### Parse

The `parse` function will return a list of strings and keys from a path string:

```js
const tokens = pathToRegexp.parse('/route/:foo/(.*)')

console.log(tokens[0])
//=> "/route"

console.log(tokens[1])
//=> { name: 'foo', prefix: '/', delimiter: '/', optional: false, repeat: false, pattern: '[^\\/]+?' }

console.log(tokens[2])
//=> { name: 0, prefix: '/', delimiter: '/', optional: false, repeat: false, pattern: '.*' }
```

**Note:** This method only works with strings.

### Compile ("Reverse" Path-To-RegExp)

The `compile` function will return a function for transforming parameters into a valid path:

```js
const toPath = pathToRegexp.compile('/user/:id')

toPath({ id: 123 }) //=> "/user/123"
toPath({ id: 'café' }) //=> "/user/caf%C3%A9"
toPath({ id: '/' }) //=> "/user/%2F"

toPath({ id: ':/' }) //=> "/user/%3A%2F"
toPath({ id: ':/' }, { encode: (value, token) => value, validate: false }) //=> "/user/:/"

const toPathRepeated = pathToRegexp.compile('/:segment+')

toPathRepeated({ segment: 'foo' }) //=> "/foo"
toPathRepeated({ segment: ['a', 'b', 'c'] }) //=> "/a/b/c"

const toPathRegexp = pathToRegexp.compile('/user/:id(\\d+)')

toPathRegexp({ id: 123 }) //=> "/user/123"
toPathRegexp({ id: '123' }) //=> "/user/123"
toPathRegexp({ id: 'abc' }) //=> Throws `TypeError`.
toPathRegexp({ id: 'abc' }, { validate: false }) //=> "/user/abc"
```

**Note:** The generated function will throw on invalid input. It will do all necessary checks to ensure the generated path is valid. This method only works with strings.

### Working with Tokens

Path-To-RegExp exposes the two functions used internally that accept an array of tokens.

* `pathToRegexp.tokensToRegExp(tokens, keys?, options?)` Transform an array of tokens into a matching regular expression.
* `pathToRegexp.tokensToFunction(tokens)` Transform an array of tokens into a path generator function.

#### Token Information

* `name` The name of the token (`string` for named or `number` for index)
* `prefix` The prefix character for the segment (e.g. `/`)
* `delimiter` The delimiter for the segment (same as prefix or default delimiter)
* `optional` Indicates the token is optional (`boolean`)
* `repeat` Indicates the token is repeated (`boolean`)
* `pattern` The RegExp used to match this token (`string`)

## Compatibility with Express <= 4.x

Path-To-RegExp breaks compatibility with Express <= `4.x`:

* RegExp special characters can only be used in a parameter
  * Express.js 4.x used all `RegExp` special characters regardless of position - this considered a bug
* Parameters have suffixes that augment meaning - `*`, `+` and `?`. E.g. `/:user*`
* No wildcard asterisk (`*`) - use parameters instead (`(.*)`)

## TypeScript

Includes a [`.d.ts`](index.d.ts) file for TypeScript users.

## Live Demo

You can see a live demo of this library in use at [express-route-tester](http://forbeslindesay.github.com/express-route-tester/).

## License

MIT

[npm-image]: https://img.shields.io/npm/v/path-to-regexp.svg?style=flat
[npm-url]: https://npmjs.org/package/path-to-regexp
[travis-image]: https://img.shields.io/travis/pillarjs/path-to-regexp.svg?style=flat
[travis-url]: https://travis-ci.org/pillarjs/path-to-regexp
[coveralls-image]: https://img.shields.io/coveralls/pillarjs/path-to-regexp.svg?style=flat
[coveralls-url]: https://coveralls.io/r/pillarjs/path-to-regexp?branch=master
[david-image]: http://img.shields.io/david/pillarjs/path-to-regexp.svg?style=flat
[david-url]: https://david-dm.org/pillarjs/path-to-regexp
[license-image]: http://img.shields.io/npm/l/path-to-regexp.svg?style=flat
[license-url]: LICENSE.md
[downloads-image]: http://img.shields.io/npm/dm/path-to-regexp.svg?style=flat
[downloads-url]: https://npmjs.org/package/path-to-regexp


---

1.9.1 / 2017-09-28
==================

  * deps: accepts@~1.3.4
    - deps: mime-types@~2.1.16
  * deps: debug@2.6.9
  * deps: http-errors@~1.6.2
    - deps: depd@1.1.1
  * deps: mime-types@~2.1.17
    - Add new mime types
    - deps: mime-db@~1.30.0
  * deps: parseurl@~1.3.2
    - perf: reduce overhead for full URLs
    - perf: unroll the "fast-path" `RegExp`

1.9.0 / 2017-05-25
==================

  * Set `X-Content-Type-Options: nosniff` header
  * deps: batch@0.6.1
  * deps: debug@2.6.8
    - Allow colors in workers
    - Deprecated `DEBUG_FD` environment variable set to `3` or higher
    - Fix `DEBUG_MAX_ARRAY_LENGTH`
    - Fix error when running under React Native
    - Use same color for same namespace
    - deps: ms@2.0.0
  * deps: http-errors@~1.6.1
    - Make `message` property enumerable for `HttpError`s
    - deps: inherits@2.0.3
    - deps: setprototypeof@1.0.3
    - deps: statuses@'>= 1.3.1 < 2'
  * deps: mime-types@~2.1.15
    - Add new mime types
    - Add `audio/mp3`

1.8.0 / 2016-06-17
==================

  * Make inline file search case-insensitive
  * deps: accepts@~1.3.3
    - deps: mime-types@~2.1.11
    - deps: negotiator@0.6.1
    - perf: improve header parsing speed
  * deps: http-errors@~1.5.0
    - Use `setprototypeof` module to replace `__proto__` setting
    - deps: inherits@2.0.1
    - deps: statuses@'>= 1.3.0 < 2'
    - perf: enable strict mode
  * deps: mime-types@~2.1.11
    - Add new mime types
    - Update primary extension for `audio/mp4`
    - deps: mime-db@~1.23.0

1.7.3 / 2016-01-24
==================

  * deps: accepts@~1.2.13
    - deps: mime-types@~2.1.6
  * deps: batch@0.5.3
    - Fix invalid dependency for browserify
  * deps: escape-html@~1.0.3
    - perf: enable strict mode
    - perf: optimize string replacement
    - perf: use faster string coercion
  * deps: mime-types@~2.1.9
    - Add new mime types
  * deps: parseurl@~1.3.1
    - perf: enable strict mode

1.7.2 / 2015-07-30
==================

  * deps: accepts@~1.2.12
    - deps: mime-types@~2.1.4
  * deps: mime-types@~2.1.4
    - Add new mime types

1.7.1 / 2015-07-05
==================

  * deps: accepts@~1.2.10
    - deps: mime-types@~2.1.2
  * deps: mime-types@~2.1.2
    - Add new mime types

1.7.0 / 2015-06-15
==================

  * Accept `function` value for `template` option
  * Send non-chunked response for `OPTIONS`
  * Stat parent directory when necessary
  * Use `Date.prototype.toLocaleDateString` to format date
  * deps: accepts@~1.2.9
    - deps: mime-types@~2.1.1
    - deps: negotiator@0.5.3
    - perf: avoid argument reassignment & argument slice
    - perf: avoid negotiator recursive construction
    - perf: enable strict mode
    - perf: remove unnecessary bitwise operator
  * deps: escape-html@1.0.2
  * deps: mime-types@~2.1.1
    - Add new mime types
  * perf: enable strict mode
  * perf: remove argument reassignment

1.6.4 / 2015-05-12
==================

  * deps: accepts@~1.2.7
    - deps: mime-types@~2.0.11
    - deps: negotiator@0.5.3
  * deps: debug@~2.2.0
    - deps: ms@0.7.1
  * deps: mime-types@~2.0.11
    - Add new mime types

1.6.3 / 2015-03-13
==================

  * Properly escape file names in HTML
  * deps: accepts@~1.2.5
    - deps: mime-types@~2.0.10
  * deps: debug@~2.1.3
    - Fix high intensity foreground color for bold
    - deps: ms@0.7.0
  * deps: escape-html@1.0.1
  * deps: mime-types@~2.0.10
    - Add new mime types

1.6.2 / 2015-02-16
==================

  * deps: accepts@~1.2.4
    - deps: mime-types@~2.0.9
    - deps: negotiator@0.5.1
  * deps: http-errors@~1.3.1
    - Construct errors using defined constructors from `createError`
    - Fix error names that are not identifiers
    - Set a meaningful `name` property on constructed errors
  * deps: mime-types@~2.0.9
    - Add new mime types
    - deps: mime-db@~1.7.0

1.6.1 / 2015-01-31
==================

  * deps: accepts@~1.2.3
    - deps: mime-types@~2.0.8
  * deps: mime-types@~2.0.8
    - Add new mime types
    - deps: mime-db@~1.6.0

1.6.0 / 2015-01-01
==================

  * Add link to root directory
  * deps: accepts@~1.2.2
    - deps: mime-types@~2.0.7
    - deps: negotiator@0.5.0
  * deps: batch@0.5.2
  * deps: debug@~2.1.1
  * deps: mime-types@~2.0.7
    - Add new mime types
    - Fix missing extensions
    - Fix various invalid MIME type entries
    - Remove example template MIME types
    - deps: mime-db@~1.5.0

1.5.3 / 2014-12-10
==================

  * deps: accepts@~1.1.4
    - deps: mime-types@~2.0.4
  * deps: http-errors@~1.2.8
    - Fix stack trace from exported function
  * deps: mime-types@~2.0.4
    - Add new mime types
    - deps: mime-db@~1.3.0

1.5.2 / 2014-12-03
==================

  * Fix icon name background alignment on mobile view

1.5.1 / 2014-11-22
==================

  * deps: accepts@~1.1.3
    - deps: mime-types@~2.0.3
  * deps: mime-types@~2.0.3
    - Add new mime types
    - deps: mime-db@~1.2.0

1.5.0 / 2014-10-16
==================

  * Create errors with `http-errors`
  * deps: debug@~2.1.0
    - Implement `DEBUG_FD` env variable support
  * deps: mime-types@~2.0.2
    - deps: mime-db@~1.1.0

1.4.1 / 2014-10-15
==================

  * deps: accepts@~1.1.2
    - Fix error when media type has invalid parameter
    - deps: negotiator@0.4.9

1.4.0 / 2014-10-03
==================

  * Add `dir` argument to `filter` function
  * Support using tokens multiple times

1.3.1 / 2014-10-01
==================

  * Fix incorrect 403 on Windows and Node.js 0.11
  * deps: accepts@~1.1.1
    - deps: mime-types@~2.0.2
    - deps: negotiator@0.4.8

1.3.0 / 2014-09-20
==================

  * Add icon for mkv files
  * Lookup icon by mime type for greater icon support

1.2.1 / 2014-09-05
==================

  * deps: accepts@~1.1.0
  * deps: debug@~2.0.0

1.2.0 / 2014-08-25
==================

  * Add `debug` messages
  * Resolve relative paths at middleware setup

1.1.6 / 2014-08-10
==================

  * Fix URL parsing
  * deps: parseurl@~1.3.0

1.1.5 / 2014-07-27
==================

  * Fix Content-Length calculation for multi-byte file names
  * deps: accepts@~1.0.7
    - deps: negotiator@0.4.7

1.1.4 / 2014-06-20
==================

  * deps: accepts@~1.0.5

1.1.3 / 2014-06-20
==================

  * deps: accepts@~1.0.4
    - use `mime-types`

1.1.2 / 2014-06-19
==================

  * deps: batch@0.5.1

1.1.1 / 2014-06-11
==================

  * deps: accepts@1.0.3

1.1.0 / 2014-05-29
==================

  * Fix content negotiation when no `Accept` header
  * Properly support all HTTP methods
  * Support vanilla node.js http servers
  * Treat `ENAMETOOLONG` as code 414
  * Use accepts for negotiation

1.0.3 / 2014-05-20
==================

  * Fix error from non-statable files in HTML view

1.0.2 / 2014-04-28
==================

  * Add `stylesheet` option
  * deps: negotiator@0.4.3

1.0.1 / 2014-03-05
==================

  * deps: negotiator@0.4.2

1.0.0 / 2014-03-05
==================

  * Genesis from connect


---

# serve-index

[![NPM Version][npm-image]][npm-url]
[![NPM Downloads][downloads-image]][downloads-url]
[![Linux Build][travis-image]][travis-url]
[![Windows Build][appveyor-image]][appveyor-url]
[![Test Coverage][coveralls-image]][coveralls-url]
[![Gratipay][gratipay-image]][gratipay-url]

  Serves pages that contain directory listings for a given path.

## Install

This is a [Node.js](https://nodejs.org/en/) module available through the
[npm registry](https://www.npmjs.com/). Installation is done using the
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):

```sh
$ npm install serve-index
```

## API

```js
var serveIndex = require('serve-index')
```

### serveIndex(path, options)

Returns middlware that serves an index of the directory in the given `path`.

The `path` is based off the `req.url` value, so a `req.url` of `'/some/dir`
with a `path` of `'public'` will look at `'public/some/dir'`. If you are using
something like `express`, you can change the URL "base" with `app.use` (see
the express example).

#### Options

Serve index accepts these properties in the options object.

##### filter

Apply this filter function to files. Defaults to `false`. The `filter` function
is called for each file, with the signature `filter(filename, index, files, dir)`
where `filename` is the name of the file, `index` is the array index, `files` is
the array of files and `dir` is the absolute path the file is located (and thus,
the directory the listing is for).

##### hidden

Display hidden (dot) files. Defaults to `false`.

##### icons

Display icons. Defaults to `false`.

##### stylesheet

Optional path to a CSS stylesheet. Defaults to a built-in stylesheet.

##### template

Optional path to an HTML template or a function that will render a HTML
string. Defaults to a built-in template.

When given a string, the string is used as a file path to load and then the
following tokens are replaced in templates:

  * `{directory}` with the name of the directory.
  * `{files}` with the HTML of an unordered list of file links.
  * `{linked-path}` with the HTML of a link to the directory.
  * `{style}` with the specified stylesheet and embedded images.

When given as a function, the function is called as `template(locals, callback)`
and it needs to invoke `callback(error, htmlString)`. The following are the
provided locals:

  * `directory` is the directory being displayed (where `/` is the root).
  * `displayIcons` is a Boolean for if icons should be rendered or not.
  * `fileList` is a sorted array of files in the directory. The array contains
    objects with the following properties:
    - `name` is the relative name for the file.
    - `stat` is a `fs.Stats` object for the file.
  * `path` is the full filesystem path to `directory`.
  * `style` is the default stylesheet or the contents of the `stylesheet` option.
  * `viewName` is the view name provided by the `view` option.

##### view

Display mode. `tiles` and `details` are available. Defaults to `tiles`.

## Examples

### Serve directory indexes with vanilla node.js http server

```js
var finalhandler = require('finalhandler')
var http = require('http')
var serveIndex = require('serve-index')
var serveStatic = require('serve-static')

// Serve directory indexes for public/ftp folder (with icons)
var index = serveIndex('public/ftp', {'icons': true})

// Serve up public/ftp folder files
var serve = serveStatic('public/ftp')

// Create server
var server = http.createServer(function onRequest(req, res){
  var done = finalhandler(req, res)
  serve(req, res, function onNext(err) {
    if (err) return done(err)
    index(req, res, done)
  })
})

// Listen
server.listen(3000)
```

### Serve directory indexes with express

```js
var express    = require('express')
var serveIndex = require('serve-index')

var app = express()

// Serve URLs like /ftp/thing as public/ftp/thing
// The express.static serves the file contents
// The serveIndex is this module serving the directory
app.use('/ftp', express.static('public/ftp'), serveIndex('public/ftp', {'icons': true}))

// Listen
app.listen(3000)
```

## License

[MIT](LICENSE). The [Silk](http://www.famfamfam.com/lab/icons/silk/) icons
are created by/copyright of [FAMFAMFAM](http://www.famfamfam.com/).

[npm-image]: https://img.shields.io/npm/v/serve-index.svg
[npm-url]: https://npmjs.org/package/serve-index
[travis-image]: https://img.shields.io/travis/expressjs/serve-index/master.svg?label=linux
[travis-url]: https://travis-ci.org/expressjs/serve-index
[appveyor-image]: https://img.shields.io/appveyor/ci/dougwilson/serve-index/master.svg?label=windows
[appveyor-url]: https://ci.appveyor.com/project/dougwilson/serve-index
[coveralls-image]: https://img.shields.io/coveralls/expressjs/serve-index/master.svg
[coveralls-url]: https://coveralls.io/r/expressjs/serve-index?branch=master
[downloads-image]: https://img.shields.io/npm/dm/serve-index.svg
[downloads-url]: https://npmjs.org/package/serve-index
[gratipay-image]: https://img.shields.io/gratipay/dougwilson.svg
[gratipay-url]: https://www.gratipay.com/dougwilson/


---


2.6.9 / 2017-09-22
==================

  * remove ReDoS regexp in %o formatter (#504)

2.6.8 / 2017-05-18
==================

  * Fix: Check for undefined on browser globals (#462, @marbemac)

2.6.7 / 2017-05-16
==================

  * Fix: Update ms to 2.0.0 to fix regular expression denial of service vulnerability (#458, @hubdotcom)
  * Fix: Inline extend function in node implementation (#452, @dougwilson)
  * Docs: Fix typo (#455, @msasad)

2.6.5 / 2017-04-27
==================
  
  * Fix: null reference check on window.documentElement.style.WebkitAppearance (#447, @thebigredgeek)
  * Misc: clean up browser reference checks (#447, @thebigredgeek)
  * Misc: add npm-debug.log to .gitignore (@thebigredgeek)


2.6.4 / 2017-04-20
==================

  * Fix: bug that would occure if process.env.DEBUG is a non-string value. (#444, @LucianBuzzo)
  * Chore: ignore bower.json in npm installations. (#437, @joaovieira)
  * Misc: update "ms" to v0.7.3 (@tootallnate)

2.6.3 / 2017-03-13
==================

  * Fix: Electron reference to `process.env.DEBUG` (#431, @paulcbetts)
  * Docs: Changelog fix (@thebigredgeek)

2.6.2 / 2017-03-10
==================

  * Fix: DEBUG_MAX_ARRAY_LENGTH (#420, @slavaGanzin)
  * Docs: Add backers and sponsors from Open Collective (#422, @piamancini)
  * Docs: Add Slackin invite badge (@tootallnate)

2.6.1 / 2017-02-10
==================

  * Fix: Module's `export default` syntax fix for IE8 `Expected identifier` error
  * Fix: Whitelist DEBUG_FD for values 1 and 2 only (#415, @pi0)
  * Fix: IE8 "Expected identifier" error (#414, @vgoma)
  * Fix: Namespaces would not disable once enabled (#409, @musikov)

2.6.0 / 2016-12-28
==================

  * Fix: added better null pointer checks for browser useColors (@thebigredgeek)
  * Improvement: removed explicit `window.debug` export (#404, @tootallnate)
  * Improvement: deprecated `DEBUG_FD` environment variable (#405, @tootallnate)

2.5.2 / 2016-12-25
==================

  * Fix: reference error on window within webworkers (#393, @KlausTrainer)
  * Docs: fixed README typo (#391, @lurch)
  * Docs: added notice about v3 api discussion (@thebigredgeek)

2.5.1 / 2016-12-20
==================

  * Fix: babel-core compatibility

2.5.0 / 2016-12-20
==================

  * Fix: wrong reference in bower file (@thebigredgeek)
  * Fix: webworker compatibility (@thebigredgeek)
  * Fix: output formatting issue (#388, @kribblo)
  * Fix: babel-loader compatibility (#383, @escwald)
  * Misc: removed built asset from repo and publications (@thebigredgeek)
  * Misc: moved source files to /src (#378, @yamikuronue)
  * Test: added karma integration and replaced babel with browserify for browser tests (#378, @yamikuronue)
  * Test: coveralls integration (#378, @yamikuronue)
  * Docs: simplified language in the opening paragraph (#373, @yamikuronue)

2.4.5 / 2016-12-17
==================

  * Fix: `navigator` undefined in Rhino (#376, @jochenberger)
  * Fix: custom log function (#379, @hsiliev)
  * Improvement: bit of cleanup + linting fixes (@thebigredgeek)
  * Improvement: rm non-maintainted `dist/` dir (#375, @freewil)
  * Docs: simplified language in the opening paragraph. (#373, @yamikuronue)

2.4.4 / 2016-12-14
==================

  * Fix: work around debug being loaded in preload scripts for electron (#368, @paulcbetts)

2.4.3 / 2016-12-14
==================

  * Fix: navigation.userAgent error for react native (#364, @escwald)

2.4.2 / 2016-12-14
==================

  * Fix: browser colors (#367, @tootallnate)
  * Misc: travis ci integration (@thebigredgeek)
  * Misc: added linting and testing boilerplate with sanity check (@thebigredgeek)

2.4.1 / 2016-12-13
==================

  * Fix: typo that broke the package (#356)

2.4.0 / 2016-12-13
==================

  * Fix: bower.json references unbuilt src entry point (#342, @justmatt)
  * Fix: revert "handle regex special characters" (@tootallnate)
  * Feature: configurable util.inspect()`options for NodeJS (#327, @tootallnate)
  * Feature: %O`(big O) pretty-prints objects (#322, @tootallnate)
  * Improvement: allow colors in workers (#335, @botverse)
  * Improvement: use same color for same namespace. (#338, @lchenay)

2.3.3 / 2016-11-09
==================

  * Fix: Catch `JSON.stringify()` errors (#195, Jovan Alleyne)
  * Fix: Returning `localStorage` saved values (#331, Levi Thomason)
  * Improvement: Don't create an empty object when no `process` (Nathan Rajlich)

2.3.2 / 2016-11-09
==================

  * Fix: be super-safe in index.js as well (@TooTallNate)
  * Fix: should check whether process exists (Tom Newby)

2.3.1 / 2016-11-09
==================

  * Fix: Added electron compatibility (#324, @paulcbetts)
  * Improvement: Added performance optimizations (@tootallnate)
  * Readme: Corrected PowerShell environment variable example (#252, @gimre)
  * Misc: Removed yarn lock file from source control (#321, @fengmk2)

2.3.0 / 2016-11-07
==================

  * Fix: Consistent placement of ms diff at end of output (#215, @gorangajic)
  * Fix: Escaping of regex special characters in namespace strings (#250, @zacronos)
  * Fix: Fixed bug causing crash on react-native (#282, @vkarpov15)
  * Feature: Enabled ES6+ compatible import via default export (#212 @bucaran)
  * Feature: Added %O formatter to reflect Chrome's console.log capability (#279, @oncletom)
  * Package: Update "ms" to 0.7.2 (#315, @DevSide)
  * Package: removed superfluous version property from bower.json (#207 @kkirsche)
  * Readme: fix USE_COLORS to DEBUG_COLORS
  * Readme: Doc fixes for format string sugar (#269, @mlucool)
  * Readme: Updated docs for DEBUG_FD and DEBUG_COLORS environment variables (#232, @mattlyons0)
  * Readme: doc fixes for PowerShell (#271 #243, @exoticknight @unreadable)
  * Readme: better docs for browser support (#224, @matthewmueller)
  * Tooling: Added yarn integration for development (#317, @thebigredgeek)
  * Misc: Renamed History.md to CHANGELOG.md (@thebigredgeek)
  * Misc: Added license file (#226 #274, @CantemoInternal @sdaitzman)
  * Misc: Updated contributors (@thebigredgeek)

2.2.0 / 2015-05-09
==================

  * package: update "ms" to v0.7.1 (#202, @dougwilson)
  * README: add logging to file example (#193, @DanielOchoa)
  * README: fixed a typo (#191, @amir-s)
  * browser: expose `storage` (#190, @stephenmathieson)
  * Makefile: add a `distclean` target (#189, @stephenmathieson)

2.1.3 / 2015-03-13
==================

  * Updated stdout/stderr example (#186)
  * Updated example/stdout.js to match debug current behaviour
  * Renamed example/stderr.js to stdout.js
  * Update Readme.md (#184)
  * replace high intensity foreground color for bold (#182, #183)

2.1.2 / 2015-03-01
==================

  * dist: recompile
  * update "ms" to v0.7.0
  * package: update "browserify" to v9.0.3
  * component: fix "ms.js" repo location
  * changed bower package name
  * updated documentation about using debug in a browser
  * fix: security error on safari (#167, #168, @yields)

2.1.1 / 2014-12-29
==================

  * browser: use `typeof` to check for `console` existence
  * browser: check for `console.log` truthiness (fix IE 8/9)
  * browser: add support for Chrome apps
  * Readme: added Windows usage remarks
  * Add `bower.json` to properly support bower install

2.1.0 / 2014-10-15
==================

  * node: implement `DEBUG_FD` env variable support
  * package: update "browserify" to v6.1.0
  * package: add "license" field to package.json (#135, @panuhorsmalahti)

2.0.0 / 2014-09-01
==================

  * package: update "browserify" to v5.11.0
  * node: use stderr rather than stdout for logging (#29, @stephenmathieson)

1.0.4 / 2014-07-15
==================

  * dist: recompile
  * example: remove `console.info()` log usage
  * example: add "Content-Type" UTF-8 header to browser example
  * browser: place %c marker after the space character
  * browser: reset the "content" color via `color: inherit`
  * browser: add colors support for Firefox >= v31
  * debug: prefer an instance `log()` function over the global one (#119)
  * Readme: update documentation about styled console logs for FF v31 (#116, @wryk)

1.0.3 / 2014-07-09
==================

  * Add support for multiple wildcards in namespaces (#122, @seegno)
  * browser: fix lint

1.0.2 / 2014-06-10
==================

  * browser: update color palette (#113, @gscottolson)
  * common: make console logging function configurable (#108, @timoxley)
  * node: fix %o colors on old node <= 0.8.x
  * Makefile: find node path using shell/which (#109, @timoxley)

1.0.1 / 2014-06-06
==================

  * browser: use `removeItem()` to clear localStorage
  * browser, node: don't set DEBUG if namespaces is undefined (#107, @leedm777)
  * package: add "contributors" section
  * node: fix comment typo
  * README: list authors

1.0.0 / 2014-06-04
==================

  * make ms diff be global, not be scope
  * debug: ignore empty strings in enable()
  * node: make DEBUG_COLORS able to disable coloring
  * *: export the `colors` array
  * npmignore: don't publish the `dist` dir
  * Makefile: refactor to use browserify
  * package: add "browserify" as a dev dependency
  * Readme: add Web Inspector Colors section
  * node: reset terminal color for the debug content
  * node: map "%o" to `util.inspect()`
  * browser: map "%j" to `JSON.stringify()`
  * debug: add custom "formatters"
  * debug: use "ms" module for humanizing the diff
  * Readme: add "bash" syntax highlighting
  * browser: add Firebug color support
  * browser: add colors for WebKit browsers
  * node: apply log to `console`
  * rewrite: abstract common logic for Node & browsers
  * add .jshintrc file

0.8.1 / 2014-04-14
==================

  * package: re-add the "component" section

0.8.0 / 2014-03-30
==================

  * add `enable()` method for nodejs. Closes #27
  * change from stderr to stdout
  * remove unnecessary index.js file

0.7.4 / 2013-11-13
==================

  * remove "browserify" key from package.json (fixes something in browserify)

0.7.3 / 2013-10-30
==================

  * fix: catch localStorage security error when cookies are blocked (Chrome)
  * add debug(err) support. Closes #46
  * add .browser prop to package.json. Closes #42

0.7.2 / 2013-02-06
==================

  * fix package.json
  * fix: Mobile Safari (private mode) is broken with debug
  * fix: Use unicode to send escape character to shell instead of octal to work with strict mode javascript

0.7.1 / 2013-02-05
==================

  * add repository URL to package.json
  * add DEBUG_COLORED to force colored output
  * add browserify support
  * fix component. Closes #24

0.7.0 / 2012-05-04
==================

  * Added .component to package.json
  * Added debug.component.js build

0.6.0 / 2012-03-16
==================

  * Added support for "-" prefix in DEBUG [Vinay Pulim]
  * Added `.enabled` flag to the node version [TooTallNate]

0.5.0 / 2012-02-02
==================

  * Added: humanize diffs. Closes #8
  * Added `debug.disable()` to the CS variant
  * Removed padding. Closes #10
  * Fixed: persist client-side variant again. Closes #9

0.4.0 / 2012-02-01
==================

  * Added browser variant support for older browsers [TooTallNate]
  * Added `debug.enable('project:*')` to browser variant [TooTallNate]
  * Added padding to diff (moved it to the right)

0.3.0 / 2012-01-26
==================

  * Added millisecond diff when isatty, otherwise UTC string

0.2.0 / 2012-01-22
==================

  * Added wildcard support

0.1.0 / 2011-12-02
==================

  * Added: remove colors unless stderr isatty [TooTallNate]

0.0.1 / 2010-01-03
==================

  * Initial release


---

# debug
[![Build Status](https://travis-ci.org/visionmedia/debug.svg?branch=master)](https://travis-ci.org/visionmedia/debug)  [![Coverage Status](https://coveralls.io/repos/github/visionmedia/debug/badge.svg?branch=master)](https://coveralls.io/github/visionmedia/debug?branch=master)  [![Slack](https://visionmedia-community-slackin.now.sh/badge.svg)](https://visionmedia-community-slackin.now.sh/) [![OpenCollective](https://opencollective.com/debug/backers/badge.svg)](#backers) 
[![OpenCollective](https://opencollective.com/debug/sponsors/badge.svg)](#sponsors)



A tiny node.js debugging utility modelled after node core's debugging technique.

**Discussion around the V3 API is under way [here](https://github.com/visionmedia/debug/issues/370)**

## Installation

```bash
$ npm install debug
```

## Usage

`debug` exposes a function; simply pass this function the name of your module, and it will return a decorated version of `console.error` for you to pass debug statements to. This will allow you to toggle the debug output for different parts of your module as well as the module as a whole.

Example _app.js_:

```js
var debug = require('debug')('http')
  , http = require('http')
  , name = 'My App';

// fake app

debug('booting %s', name);

http.createServer(function(req, res){
  debug(req.method + ' ' + req.url);
  res.end('hello\n');
}).listen(3000, function(){
  debug('listening');
});

// fake worker of some kind

require('./worker');
```

Example _worker.js_:

```js
var debug = require('debug')('worker');

setInterval(function(){
  debug('doing some work');
}, 1000);
```

 The __DEBUG__ environment variable is then used to enable these based on space or comma-delimited names. Here are some examples:

  ![debug http and worker](http://f.cl.ly/items/18471z1H402O24072r1J/Screenshot.png)

  ![debug worker](http://f.cl.ly/items/1X413v1a3M0d3C2c1E0i/Screenshot.png)

#### Windows note

 On Windows the environment variable is set using the `set` command.

 ```cmd
 set DEBUG=*,-not_this
 ```

 Note that PowerShell uses different syntax to set environment variables.

 ```cmd
 $env:DEBUG = "*,-not_this"
  ```

Then, run the program to be debugged as usual.

## Millisecond diff

  When actively developing an application it can be useful to see when the time spent between one `debug()` call and the next. Suppose for example you invoke `debug()` before requesting a resource, and after as well, the "+NNNms" will show you how much time was spent between calls.

  ![](http://f.cl.ly/items/2i3h1d3t121M2Z1A3Q0N/Screenshot.png)

  When stdout is not a TTY, `Date#toUTCString()` is used, making it more useful for logging the debug information as shown below:

  ![](http://f.cl.ly/items/112H3i0e0o0P0a2Q2r11/Screenshot.png)

## Conventions

  If you're using this in one or more of your libraries, you _should_ use the name of your library so that developers may toggle debugging as desired without guessing names. If you have more than one debuggers you _should_ prefix them with your library name and use ":" to separate features. For example "bodyParser" from Connect would then be "connect:bodyParser".

## Wildcards

  The `*` character may be used as a wildcard. Suppose for example your library has debuggers named "connect:bodyParser", "connect:compress", "connect:session", instead of listing all three with `DEBUG=connect:bodyParser,connect:compress,connect:session`, you may simply do `DEBUG=connect:*`, or to run everything using this module simply use `DEBUG=*`.

  You can also exclude specific debuggers by prefixing them with a "-" character.  For example, `DEBUG=*,-connect:*` would include all debuggers except those starting with "connect:".

## Environment Variables

  When running through Node.js, you can set a few environment variables that will
  change the behavior of the debug logging:

| Name      | Purpose                                         |
|-----------|-------------------------------------------------|
| `DEBUG`   | Enables/disables specific debugging namespaces. |
| `DEBUG_COLORS`| Whether or not to use colors in the debug output. |
| `DEBUG_DEPTH` | Object inspection depth. |
| `DEBUG_SHOW_HIDDEN` | Shows hidden properties on inspected objects. |


  __Note:__ The environment variables beginning with `DEBUG_` end up being
  converted into an Options object that gets used with `%o`/`%O` formatters.
  See the Node.js documentation for
  [`util.inspect()`](https://nodejs.org/api/util.html#util_util_inspect_object_options)
  for the complete list.

## Formatters


  Debug uses [printf-style](https://wikipedia.org/wiki/Printf_format_string) formatting. Below are the officially supported formatters:

| Formatter | Representation |
|-----------|----------------|
| `%O`      | Pretty-print an Object on multiple lines. |
| `%o`      | Pretty-print an Object all on a single line. |
| `%s`      | String. |
| `%d`      | Number (both integer and float). |
| `%j`      | JSON. Replaced with the string '[Circular]' if the argument contains circular references. |
| `%%`      | Single percent sign ('%'). This does not consume an argument. |

### Custom formatters

  You can add custom formatters by extending the `debug.formatters` object. For example, if you wanted to add support for rendering a Buffer as hex with `%h`, you could do something like:

```js
const createDebug = require('debug')
createDebug.formatters.h = (v) => {
  return v.toString('hex')
}

// …elsewhere
const debug = createDebug('foo')
debug('this is hex: %h', new Buffer('hello world'))
//   foo this is hex: 68656c6c6f20776f726c6421 +0ms
```

## Browser support
  You can build a browser-ready script using [browserify](https://github.com/substack/node-browserify),
  or just use the [browserify-as-a-service](https://wzrd.in/) [build](https://wzrd.in/standalone/debug@latest),
  if you don't want to build it yourself.

  Debug's enable state is currently persisted by `localStorage`.
  Consider the situation shown below where you have `worker:a` and `worker:b`,
  and wish to debug both. You can enable this using `localStorage.debug`:

```js
localStorage.debug = 'worker:*'
```

And then refresh the page.

```js
a = debug('worker:a');
b = debug('worker:b');

setInterval(function(){
  a('doing some work');
}, 1000);

setInterval(function(){
  b('doing some work');
}, 1200);
```

#### Web Inspector Colors

  Colors are also enabled on "Web Inspectors" that understand the `%c` formatting
  option. These are WebKit web inspectors, Firefox ([since version
  31](https://hacks.mozilla.org/2014/05/editable-box-model-multiple-selection-sublime-text-keys-much-more-firefox-developer-tools-episode-31/))
  and the Firebug plugin for Firefox (any version).

  Colored output looks something like:

  ![](https://cloud.githubusercontent.com/assets/71256/3139768/b98c5fd8-e8ef-11e3-862a-f7253b6f47c6.png)


## Output streams

  By default `debug` will log to stderr, however this can be configured per-namespace by overriding the `log` method:

Example _stdout.js_:

```js
var debug = require('debug');
var error = debug('app:error');

// by default stderr is used
error('goes to stderr!');

var log = debug('app:log');
// set this namespace to log via console.log
log.log = console.log.bind(console); // don't forget to bind to console!
log('goes to stdout');
error('still goes to stderr!');

// set all output to go via console.info
// overrides all per-namespace log settings
debug.log = console.info.bind(console);
error('now goes to stdout via console.info');
log('still goes to stdout, but via console.info now');
```


## Authors

 - TJ Holowaychuk
 - Nathan Rajlich
 - Andrew Rhyne
 
## Backers

Support us with a monthly donation and help us continue our activities. [[Become a backer](https://opencollective.com/debug#backer)]

<a href="https://opencollective.com/debug/backer/0/website" target="_blank"><img src="https://opencollective.com/debug/backer/0/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/1/website" target="_blank"><img src="https://opencollective.com/debug/backer/1/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/2/website" target="_blank"><img src="https://opencollective.com/debug/backer/2/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/3/website" target="_blank"><img src="https://opencollective.com/debug/backer/3/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/4/website" target="_blank"><img src="https://opencollective.com/debug/backer/4/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/5/website" target="_blank"><img src="https://opencollective.com/debug/backer/5/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/6/website" target="_blank"><img src="https://opencollective.com/debug/backer/6/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/7/website" target="_blank"><img src="https://opencollective.com/debug/backer/7/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/8/website" target="_blank"><img src="https://opencollective.com/debug/backer/8/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/9/website" target="_blank"><img src="https://opencollective.com/debug/backer/9/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/10/website" target="_blank"><img src="https://opencollective.com/debug/backer/10/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/11/website" target="_blank"><img src="https://opencollective.com/debug/backer/11/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/12/website" target="_blank"><img src="https://opencollective.com/debug/backer/12/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/13/website" target="_blank"><img src="https://opencollective.com/debug/backer/13/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/14/website" target="_blank"><img src="https://opencollective.com/debug/backer/14/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/15/website" target="_blank"><img src="https://opencollective.com/debug/backer/15/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/16/website" target="_blank"><img src="https://opencollective.com/debug/backer/16/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/17/website" target="_blank"><img src="https://opencollective.com/debug/backer/17/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/18/website" target="_blank"><img src="https://opencollective.com/debug/backer/18/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/19/website" target="_blank"><img src="https://opencollective.com/debug/backer/19/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/20/website" target="_blank"><img src="https://opencollective.com/debug/backer/20/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/21/website" target="_blank"><img src="https://opencollective.com/debug/backer/21/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/22/website" target="_blank"><img src="https://opencollective.com/debug/backer/22/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/23/website" target="_blank"><img src="https://opencollective.com/debug/backer/23/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/24/website" target="_blank"><img src="https://opencollective.com/debug/backer/24/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/25/website" target="_blank"><img src="https://opencollective.com/debug/backer/25/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/26/website" target="_blank"><img src="https://opencollective.com/debug/backer/26/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/27/website" target="_blank"><img src="https://opencollective.com/debug/backer/27/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/28/website" target="_blank"><img src="https://opencollective.com/debug/backer/28/avatar.svg"></a>
<a href="https://opencollective.com/debug/backer/29/website" target="_blank"><img src="https://opencollective.com/debug/backer/29/avatar.svg"></a>


## Sponsors

Become a sponsor and get your logo on our README on Github with a link to your site. [[Become a sponsor](https://opencollective.com/debug#sponsor)]

<a href="https://opencollective.com/debug/sponsor/0/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/0/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/1/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/1/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/2/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/2/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/3/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/3/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/4/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/4/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/5/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/5/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/6/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/6/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/7/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/7/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/8/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/8/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/9/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/9/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/10/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/10/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/11/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/11/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/12/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/12/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/13/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/13/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/14/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/14/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/15/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/15/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/16/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/16/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/17/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/17/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/18/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/18/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/19/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/19/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/20/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/20/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/21/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/21/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/22/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/22/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/23/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/23/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/24/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/24/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/25/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/25/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/26/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/26/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/27/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/27/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/28/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/28/avatar.svg"></a>
<a href="https://opencollective.com/debug/sponsor/29/website" target="_blank"><img src="https://opencollective.com/debug/sponsor/29/avatar.svg"></a>

## License

(The MIT License)

Copyright (c) 2014-2016 TJ Holowaychuk &lt;tj@vision-media.ca&gt;

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
'Software'), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


---

1.1.2 / 2018-01-11
==================

  * perf: remove argument reassignment
  * Support Node.js 0.6 to 9.x

1.1.1 / 2017-07-27
==================

  * Remove unnecessary `Buffer` loading
  * Support Node.js 0.6 to 8.x

1.1.0 / 2015-09-14
==================

  * Enable strict mode in more places
  * Support io.js 3.x
  * Support io.js 2.x
  * Support web browser loading
    - Requires bundler like Browserify or webpack

1.0.1 / 2015-04-07
==================

  * Fix `TypeError`s when under `'use strict'` code
  * Fix useless type name on auto-generated messages
  * Support io.js 1.x
  * Support Node.js 0.12

1.0.0 / 2014-09-17
==================

  * No changes

0.4.5 / 2014-09-09
==================

  * Improve call speed to functions using the function wrapper
  * Support Node.js 0.6

0.4.4 / 2014-07-27
==================

  * Work-around v8 generating empty stack traces

0.4.3 / 2014-07-26
==================

  * Fix exception when global `Error.stackTraceLimit` is too low

0.4.2 / 2014-07-19
==================

  * Correct call site for wrapped functions and properties

0.4.1 / 2014-07-19
==================

  * Improve automatic message generation for function properties

0.4.0 / 2014-07-19
==================

  * Add `TRACE_DEPRECATION` environment variable
  * Remove non-standard grey color from color output
  * Support `--no-deprecation` argument
  * Support `--trace-deprecation` argument
  * Support `deprecate.property(fn, prop, message)`

0.3.0 / 2014-06-16
==================

  * Add `NO_DEPRECATION` environment variable

0.2.0 / 2014-06-15
==================

  * Add `deprecate.property(obj, prop, message)`
  * Remove `supports-color` dependency for node.js 0.8

0.1.0 / 2014-06-15
==================

  * Add `deprecate.function(fn, message)`
  * Add `process.on('deprecation', fn)` emitter
  * Automatically generate message when omitted from `deprecate()`

0.0.1 / 2014-06-15
==================

  * Fix warning for dynamic calls at singe call site

0.0.0 / 2014-06-15
==================

  * Initial implementation


---

# depd

[![NPM Version][npm-version-image]][npm-url]
[![NPM Downloads][npm-downloads-image]][npm-url]
[![Node.js Version][node-image]][node-url]
[![Linux Build][travis-image]][travis-url]
[![Windows Build][appveyor-image]][appveyor-url]
[![Coverage Status][coveralls-image]][coveralls-url]

Deprecate all the things

> With great modules comes great responsibility; mark things deprecated!

## Install

This module is installed directly using `npm`:

```sh
$ npm install depd
```

This module can also be bundled with systems like
[Browserify](http://browserify.org/) or [webpack](https://webpack.github.io/),
though by default this module will alter it's API to no longer display or
track deprecations.

## API

<!-- eslint-disable no-unused-vars -->

```js
var deprecate = require('depd')('my-module')
```

This library allows you to display deprecation messages to your users.
This library goes above and beyond with deprecation warnings by
introspection of the call stack (but only the bits that it is interested
in).

Instead of just warning on the first invocation of a deprecated
function and never again, this module will warn on the first invocation
of a deprecated function per unique call site, making it ideal to alert
users of all deprecated uses across the code base, rather than just
whatever happens to execute first.

The deprecation warnings from this module also include the file and line
information for the call into the module that the deprecated function was
in.

**NOTE** this library has a similar interface to the `debug` module, and
this module uses the calling file to get the boundary for the call stacks,
so you should always create a new `deprecate` object in each file and not
within some central file.

### depd(namespace)

Create a new deprecate function that uses the given namespace name in the
messages and will display the call site prior to the stack entering the
file this function was called from. It is highly suggested you use the
name of your module as the namespace.

### deprecate(message)

Call this function from deprecated code to display a deprecation message.
This message will appear once per unique caller site. Caller site is the
first call site in the stack in a different file from the caller of this
function.

If the message is omitted, a message is generated for you based on the site
of the `deprecate()` call and will display the name of the function called,
similar to the name displayed in a stack trace.

### deprecate.function(fn, message)

Call this function to wrap a given function in a deprecation message on any
call to the function. An optional message can be supplied to provide a custom
message.

### deprecate.property(obj, prop, message)

Call this function to wrap a given property on object in a deprecation message
on any accessing or setting of the property. An optional message can be supplied
to provide a custom message.

The method must be called on the object where the property belongs (not
inherited from the prototype).

If the property is a data descriptor, it will be converted to an accessor
descriptor in order to display the deprecation message.

### process.on('deprecation', fn)

This module will allow easy capturing of deprecation errors by emitting the
errors as the type "deprecation" on the global `process`. If there are no
listeners for this type, the errors are written to STDERR as normal, but if
there are any listeners, nothing will be written to STDERR and instead only
emitted. From there, you can write the errors in a different format or to a
logging source.

The error represents the deprecation and is emitted only once with the same
rules as writing to STDERR. The error has the following properties:

  - `message` - This is the message given by the library
  - `name` - This is always `'DeprecationError'`
  - `namespace` - This is the namespace the deprecation came from
  - `stack` - This is the stack of the call to the deprecated thing

Example `error.stack` output:

```
DeprecationError: my-cool-module deprecated oldfunction
    at Object.<anonymous> ([eval]-wrapper:6:22)
    at Module._compile (module.js:456:26)
    at evalScript (node.js:532:25)
    at startup (node.js:80:7)
    at node.js:902:3
```

### process.env.NO_DEPRECATION

As a user of modules that are deprecated, the environment variable `NO_DEPRECATION`
is provided as a quick solution to silencing deprecation warnings from being
output. The format of this is similar to that of `DEBUG`:

```sh
$ NO_DEPRECATION=my-module,othermod node app.js
```

This will suppress deprecations from being output for "my-module" and "othermod".
The value is a list of comma-separated namespaces. To suppress every warning
across all namespaces, use the value `*` for a namespace.

Providing the argument `--no-deprecation` to the `node` executable will suppress
all deprecations (only available in Node.js 0.8 or higher).

**NOTE** This will not suppress the deperecations given to any "deprecation"
event listeners, just the output to STDERR.

### process.env.TRACE_DEPRECATION

As a user of modules that are deprecated, the environment variable `TRACE_DEPRECATION`
is provided as a solution to getting more detailed location information in deprecation
warnings by including the entire stack trace. The format of this is the same as
`NO_DEPRECATION`:

```sh
$ TRACE_DEPRECATION=my-module,othermod node app.js
```

This will include stack traces for deprecations being output for "my-module" and
"othermod". The value is a list of comma-separated namespaces. To trace every
warning across all namespaces, use the value `*` for a namespace.

Providing the argument `--trace-deprecation` to the `node` executable will trace
all deprecations (only available in Node.js 0.8 or higher).

**NOTE** This will not trace the deperecations silenced by `NO_DEPRECATION`.

## Display

![message](files/message.png)

When a user calls a function in your library that you mark deprecated, they
will see the following written to STDERR (in the given colors, similar colors
and layout to the `debug` module):

```
bright cyan    bright yellow
|              |          reset       cyan
|              |          |           |
▼              ▼          ▼           ▼
my-cool-module deprecated oldfunction [eval]-wrapper:6:22
▲              ▲          ▲           ▲
|              |          |           |
namespace      |          |           location of mycoolmod.oldfunction() call
               |          deprecation message
               the word "deprecated"
```

If the user redirects their STDERR to a file or somewhere that does not support
colors, they see (similar layout to the `debug` module):

```
Sun, 15 Jun 2014 05:21:37 GMT my-cool-module deprecated oldfunction at [eval]-wrapper:6:22
▲                             ▲              ▲          ▲              ▲
|                             |              |          |              |
timestamp of message          namespace      |          |             location of mycoolmod.oldfunction() call
                                             |          deprecation message
                                             the word "deprecated"
```

## Examples

### Deprecating all calls to a function

This will display a deprecated message about "oldfunction" being deprecated
from "my-module" on STDERR.

```js
var deprecate = require('depd')('my-cool-module')

// message automatically derived from function name
// Object.oldfunction
exports.oldfunction = deprecate.function(function oldfunction () {
  // all calls to function are deprecated
})

// specific message
exports.oldfunction = deprecate.function(function () {
  // all calls to function are deprecated
}, 'oldfunction')
```

### Conditionally deprecating a function call

This will display a deprecated message about "weirdfunction" being deprecated
from "my-module" on STDERR when called with less than 2 arguments.

```js
var deprecate = require('depd')('my-cool-module')

exports.weirdfunction = function () {
  if (arguments.length < 2) {
    // calls with 0 or 1 args are deprecated
    deprecate('weirdfunction args < 2')
  }
}
```

When calling `deprecate` as a function, the warning is counted per call site
within your own module, so you can display different deprecations depending
on different situations and the users will still get all the warnings:

```js
var deprecate = require('depd')('my-cool-module')

exports.weirdfunction = function () {
  if (arguments.length < 2) {
    // calls with 0 or 1 args are deprecated
    deprecate('weirdfunction args < 2')
  } else if (typeof arguments[0] !== 'string') {
    // calls with non-string first argument are deprecated
    deprecate('weirdfunction non-string first arg')
  }
}
```

### Deprecating property access

This will display a deprecated message about "oldprop" being deprecated
from "my-module" on STDERR when accessed. A deprecation will be displayed
when setting the value and when getting the value.

```js
var deprecate = require('depd')('my-cool-module')

exports.oldprop = 'something'

// message automatically derives from property name
deprecate.property(exports, 'oldprop')

// explicit message
deprecate.property(exports, 'oldprop', 'oldprop >= 0.10')
```

## License

[MIT](LICENSE)

[npm-version-image]: https://img.shields.io/npm/v/depd.svg
[npm-downloads-image]: https://img.shields.io/npm/dm/depd.svg
[npm-url]: https://npmjs.org/package/depd
[travis-image]: https://img.shields.io/travis/dougwilson/nodejs-depd/master.svg?label=linux
[travis-url]: https://travis-ci.org/dougwilson/nodejs-depd
[appveyor-image]: https://img.shields.io/appveyor/ci/dougwilson/nodejs-depd/master.svg?label=windows
[appveyor-url]: https://ci.appveyor.com/project/dougwilson/nodejs-depd
[coveralls-image]: https://img.shields.io/coveralls/dougwilson/nodejs-depd/master.svg
[coveralls-url]: https://coveralls.io/r/dougwilson/nodejs-depd?branch=master
[node-image]: https://img.shields.io/node/v/depd.svg
[node-url]: https://nodejs.org/en/download/


---

2018-03-29 / 1.6.3
==================

  * deps: depd@~1.1.2
    - perf: remove argument reassignment
  * deps: setprototypeof@1.1.0
  * deps: statuses@'>= 1.3.1 < 2'

2017-08-04 / 1.6.2
==================

  * deps: depd@1.1.1
    - Remove unnecessary `Buffer` loading

2017-02-20 / 1.6.1
==================

  * deps: setprototypeof@1.0.3
    - Fix shim for old browsers

2017-02-14 / 1.6.0
==================

  * Accept custom 4xx and 5xx status codes in factory
  * Add deprecation message to `"I'mateapot"` export
  * Deprecate passing status code as anything except first argument in factory
  * Deprecate using non-error status codes
  * Make `message` property enumerable for `HttpError`s

2016-11-16 / 1.5.1
==================

  * deps: inherits@2.0.3
    - Fix issue loading in browser
  * deps: setprototypeof@1.0.2
  * deps: statuses@'>= 1.3.1 < 2'

2016-05-18 / 1.5.0
==================

  * Support new code `421 Misdirected Request`
  * Use `setprototypeof` module to replace `__proto__` setting
  * deps: statuses@'>= 1.3.0 < 2'
    - Add `421 Misdirected Request`
    - perf: enable strict mode
  * perf: enable strict mode

2016-01-28 / 1.4.0
==================

  * Add `HttpError` export, for `err instanceof createError.HttpError`
  * deps: inherits@2.0.1
  * deps: statuses@'>= 1.2.1 < 2'
    - Fix message for status 451
    - Remove incorrect nginx status code

2015-02-02 / 1.3.1
==================

  * Fix regression where status can be overwritten in `createError` `props`

2015-02-01 / 1.3.0
==================

  * Construct errors using defined constructors from `createError`
  * Fix error names that are not identifiers
    - `createError["I'mateapot"]` is now `createError.ImATeapot`
  * Set a meaningful `name` property on constructed errors

2014-12-09 / 1.2.8
==================

  * Fix stack trace from exported function
  * Remove `arguments.callee` usage

2014-10-14 / 1.2.7
==================

  * Remove duplicate line

2014-10-02 / 1.2.6
==================

  * Fix `expose` to be `true` for `ClientError` constructor

2014-09-28 / 1.2.5
==================

  * deps: statuses@1

2014-09-21 / 1.2.4
==================

  * Fix dependency version to work with old `npm`s

2014-09-21 / 1.2.3
==================

  * deps: statuses@~1.1.0

2014-09-21 / 1.2.2
==================

  * Fix publish error

2014-09-21 / 1.2.1
==================

  * Support Node.js 0.6
  * Use `inherits` instead of `util`

2014-09-09 / 1.2.0
==================

  * Fix the way inheriting functions
  * Support `expose` being provided in properties argument

2014-09-08 / 1.1.0
==================

  * Default status to 500
  * Support provided `error` to extend

2014-09-08 / 1.0.1
==================

  * Fix accepting string message

2014-09-08 / 1.0.0
==================

  * Initial release


---

# http-errors

[![NPM Version][npm-image]][npm-url]
[![NPM Downloads][downloads-image]][downloads-url]
[![Node.js Version][node-version-image]][node-version-url]
[![Build Status][travis-image]][travis-url]
[![Test Coverage][coveralls-image]][coveralls-url]

Create HTTP errors for Express, Koa, Connect, etc. with ease.

## Install

This is a [Node.js](https://nodejs.org/en/) module available through the
[npm registry](https://www.npmjs.com/). Installation is done using the
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):

```bash
$ npm install http-errors
```

## Example

```js
var createError = require('http-errors')
var express = require('express')
var app = express()

app.use(function (req, res, next) {
  if (!req.user) return next(createError(401, 'Please login to view this page.'))
  next()
})
```

## API

This is the current API, currently extracted from Koa and subject to change.

All errors inherit from JavaScript `Error` and the exported `createError.HttpError`.

### Error Properties

- `expose` - can be used to signal if `message` should be sent to the client,
  defaulting to `false` when `status` >= 500
- `headers` - can be an object of header names to values to be sent to the
  client, defaulting to `undefined`. When defined, the key names should all
  be lower-cased
- `message` - the traditional error message, which should be kept short and all
  single line
- `status` - the status code of the error, mirroring `statusCode` for general
  compatibility
- `statusCode` - the status code of the error, defaulting to `500`

### createError([status], [message], [properties])

<!-- eslint-disable no-undef, no-unused-vars -->

```js
var err = createError(404, 'This video does not exist!')
```

- `status: 500` - the status code as a number
- `message` - the message of the error, defaulting to node's text for that status code.
- `properties` - custom properties to attach to the object

### new createError\[code || name\](\[msg]\))

<!-- eslint-disable no-undef, no-unused-vars -->

```js
var err = new createError.NotFound()
```

- `code` - the status code as a number
- `name` - the name of the error as a "bumpy case", i.e. `NotFound` or `InternalServerError`.

#### List of all constructors

|Status Code|Constructor Name             |
|-----------|-----------------------------|
|400        |BadRequest                   |
|401        |Unauthorized                 |
|402        |PaymentRequired              |
|403        |Forbidden                    |
|404        |NotFound                     |
|405        |MethodNotAllowed             |
|406        |NotAcceptable                |
|407        |ProxyAuthenticationRequired  |
|408        |RequestTimeout               |
|409        |Conflict                     |
|410        |Gone                         |
|411        |LengthRequired               |
|412        |PreconditionFailed           |
|413        |PayloadTooLarge              |
|414        |URITooLong                   |
|415        |UnsupportedMediaType         |
|416        |RangeNotSatisfiable          |
|417        |ExpectationFailed            |
|418        |ImATeapot                    |
|421        |MisdirectedRequest           |
|422        |UnprocessableEntity          |
|423        |Locked                       |
|424        |FailedDependency             |
|425        |UnorderedCollection          |
|426        |UpgradeRequired              |
|428        |PreconditionRequired         |
|429        |TooManyRequests              |
|431        |RequestHeaderFieldsTooLarge  |
|451        |UnavailableForLegalReasons   |
|500        |InternalServerError          |
|501        |NotImplemented               |
|502        |BadGateway                   |
|503        |ServiceUnavailable           |
|504        |GatewayTimeout               |
|505        |HTTPVersionNotSupported      |
|506        |VariantAlsoNegotiates        |
|507        |InsufficientStorage          |
|508        |LoopDetected                 |
|509        |BandwidthLimitExceeded       |
|510        |NotExtended                  |
|511        |NetworkAuthenticationRequired|

## License

[MIT](LICENSE)

[npm-image]: https://img.shields.io/npm/v/http-errors.svg
[npm-url]: https://npmjs.org/package/http-errors
[node-version-image]: https://img.shields.io/node/v/http-errors.svg
[node-version-url]: https://nodejs.org/en/download/
[travis-image]: https://img.shields.io/travis/jshttp/http-errors.svg
[travis-url]: https://travis-ci.org/jshttp/http-errors
[coveralls-image]: https://img.shields.io/coveralls/jshttp/http-errors.svg
[coveralls-url]: https://coveralls.io/r/jshttp/http-errors
[downloads-image]: https://img.shields.io/npm/dm/http-errors.svg
[downloads-url]: https://npmjs.org/package/http-errors


---

Browser-friendly inheritance fully compatible with standard node.js
[inherits](http://nodejs.org/api/util.html#util_util_inherits_constructor_superconstructor).

This package exports standard `inherits` from node.js `util` module in
node environment, but also provides alternative browser-friendly
implementation through [browser
field](https://gist.github.com/shtylman/4339901). Alternative
implementation is a literal copy of standard one located in standalone
module to avoid requiring of `util`. It also has a shim for old
browsers with no `Object.create` support.

While keeping you sure you are using standard `inherits`
implementation in node.js environment, it allows bundlers such as
[browserify](https://github.com/substack/node-browserify) to not
include full `util` package to your client code if all you need is
just `inherits` function. It worth, because browser shim for `util`
package is large and `inherits` is often the single function you need
from it.

It's recommended to use this package instead of
`require('util').inherits` for any code that has chances to be used
not only in node.js but in browser too.

## usage

```js
var inherits = require('inherits');
// then use exactly as the standard one
```

## note on version ~1.0

Version ~1.0 had completely different motivation and is not compatible
neither with 2.0 nor with standard node.js `inherits`.

If you are using version ~1.0 and planning to switch to ~2.0, be
careful:

* new version uses `super_` instead of `super` for referencing
  superclass
* new version overwrites current prototype while old one preserves any
  existing fields on it


---

The MIT License (MIT)

Copyright (c) 2016 Zeit, Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# ms

[![Build Status](https://travis-ci.org/zeit/ms.svg?branch=master)](https://travis-ci.org/zeit/ms)
[![Slack Channel](http://zeit-slackin.now.sh/badge.svg)](https://zeit.chat/)

Use this package to easily convert various time formats to milliseconds.

## Examples

```js
ms('2 days')  // 172800000
ms('1d')      // 86400000
ms('10h')     // 36000000
ms('2.5 hrs') // 9000000
ms('2h')      // 7200000
ms('1m')      // 60000
ms('5s')      // 5000
ms('1y')      // 31557600000
ms('100')     // 100
```

### Convert from milliseconds

```js
ms(60000)             // "1m"
ms(2 * 60000)         // "2m"
ms(ms('10 hours'))    // "10h"
```

### Time format written-out

```js
ms(60000, { long: true })             // "1 minute"
ms(2 * 60000, { long: true })         // "2 minutes"
ms(ms('10 hours'), { long: true })    // "10 hours"
```

## Features

- Works both in [node](https://nodejs.org) and in the browser.
- If a number is supplied to `ms`, a string with a unit is returned.
- If a string that contains the number is supplied, it returns it as a number (e.g.: it returns `100` for `'100'`).
- If you pass a string with a number and a valid unit, the number of equivalent ms is returned.

## Caught a bug?

1. [Fork](https://help.github.com/articles/fork-a-repo/) this repository to your own GitHub account and then [clone](https://help.github.com/articles/cloning-a-repository/) it to your local device
2. Link the package to the global module directory: `npm link`
3. Within the module you want to test your local development instance of ms, just link it to the dependencies: `npm link ms`. Instead of the default one from npm, node will now use your clone of ms!

As always, you can run the tests using: `npm test`


---

# Polyfill for `Object.setPrototypeOf`

A simple cross platform implementation to set the prototype of an instianted object.  Supports all modern browsers and at least back to IE8.

## Usage:

```
$ npm install --save setprototypeof
```

```javascript
var setPrototypeOf = require('setprototypeof');

var obj = {};
setPrototypeOf(obj, {
	foo: function() {
		return 'bar';
	}
});
obj.foo(); // bar
```

TypeScript is also supported:
```typescript
import setPrototypeOf = require('setprototypeof');
```

---

1.5.0 / 2018-03-27
==================

  * Add `103 Early Hints`

1.4.0 / 2017-10-20
==================

  * Add `STATUS_CODES` export

1.3.1 / 2016-11-11
==================

  * Fix return type in JSDoc

1.3.0 / 2016-05-17
==================

  * Add `421 Misdirected Request`
  * perf: enable strict mode

1.2.1 / 2015-02-01
==================

  * Fix message for status 451
    - `451 Unavailable For Legal Reasons`

1.2.0 / 2014-09-28
==================

  * Add `208 Already Repored`
  * Add `226 IM Used`
  * Add `306 (Unused)`
  * Add `415 Unable For Legal Reasons`
  * Add `508 Loop Detected`

1.1.1 / 2014-09-24
==================

  * Add missing 308 to `codes.json`

1.1.0 / 2014-09-21
==================

  * Add `codes.json` for universal support

1.0.4 / 2014-08-20
==================

  * Package cleanup

1.0.3 / 2014-06-08
==================

  * Add 308 to `.redirect` category

1.0.2 / 2014-03-13
==================

  * Add `.retry` category

1.0.1 / 2014-03-12
==================

  * Initial release


---

# Statuses

[![NPM Version][npm-image]][npm-url]
[![NPM Downloads][downloads-image]][downloads-url]
[![Node.js Version][node-version-image]][node-version-url]
[![Build Status][travis-image]][travis-url]
[![Test Coverage][coveralls-image]][coveralls-url]

HTTP status utility for node.

This module provides a list of status codes and messages sourced from
a few different projects:

  * The [IANA Status Code Registry](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml)
  * The [Node.js project](https://nodejs.org/)
  * The [NGINX project](https://www.nginx.com/)
  * The [Apache HTTP Server project](https://httpd.apache.org/)

## Installation

This is a [Node.js](https://nodejs.org/en/) module available through the
[npm registry](https://www.npmjs.com/). Installation is done using the
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):

```sh
$ npm install statuses
```

## API

<!-- eslint-disable no-unused-vars -->

```js
var status = require('statuses')
```

### var code = status(Integer || String)

If `Integer` or `String` is a valid HTTP code or status message, then the
appropriate `code` will be returned. Otherwise, an error will be thrown.

<!-- eslint-disable no-undef -->

```js
status(403) // => 403
status('403') // => 403
status('forbidden') // => 403
status('Forbidden') // => 403
status(306) // throws, as it's not supported by node.js
```

### status.STATUS_CODES

Returns an object which maps status codes to status messages, in
the same format as the
[Node.js http module](https://nodejs.org/dist/latest/docs/api/http.html#http_http_status_codes).

### status.codes

Returns an array of all the status codes as `Integer`s.

### var msg = status[code]

Map of `code` to `status message`. `undefined` for invalid `code`s.

<!-- eslint-disable no-undef, no-unused-expressions -->

```js
status[404] // => 'Not Found'
```

### var code = status[msg]

Map of `status message` to `code`. `msg` can either be title-cased or
lower-cased. `undefined` for invalid `status message`s.

<!-- eslint-disable no-undef, no-unused-expressions -->

```js
status['not found'] // => 404
status['Not Found'] // => 404
```

### status.redirect[code]

Returns `true` if a status code is a valid redirect status.

<!-- eslint-disable no-undef, no-unused-expressions -->

```js
status.redirect[200] // => undefined
status.redirect[301] // => true
```

### status.empty[code]

Returns `true` if a status code expects an empty body.

<!-- eslint-disable no-undef, no-unused-expressions -->

```js
status.empty[200] // => undefined
status.empty[204] // => true
status.empty[304] // => true
```

### status.retry[code]

Returns `true` if you should retry the rest.

<!-- eslint-disable no-undef, no-unused-expressions -->

```js
status.retry[501] // => undefined
status.retry[503] // => true
```

[npm-image]: https://img.shields.io/npm/v/statuses.svg
[npm-url]: https://npmjs.org/package/statuses
[node-version-image]: https://img.shields.io/node/v/statuses.svg
[node-version-url]: https://nodejs.org/en/download
[travis-image]: https://img.shields.io/travis/jshttp/statuses.svg
[travis-url]: https://travis-ci.org/jshttp/statuses
[coveralls-image]: https://img.shields.io/coveralls/jshttp/statuses.svg
[coveralls-url]: https://coveralls.io/r/jshttp/statuses?branch=master
[downloads-image]: https://img.shields.io/npm/dm/statuses.svg
[downloads-url]: https://npmjs.org/package/statuses


---

1.16.2 / 2024-09-11
===================

* deps: encodeurl@~2.0.0

1.16.1 / 2024-09-11
===================

* deps: send@0.19.0

1.16.0 / 2024-09-10
===================

* Remove link renderization in html while redirecting


1.15.0 / 2022-03-24
===================

  * deps: send@0.18.0
    - Fix emitted 416 error missing headers property
    - Limit the headers removed for 304 response
    - deps: depd@2.0.0
    - deps: destroy@1.2.0
    - deps: http-errors@2.0.0
    - deps: on-finished@2.4.1
    - deps: statuses@2.0.1

1.14.2 / 2021-12-15
===================

  * deps: send@0.17.2
    - deps: http-errors@1.8.1
    - deps: ms@2.1.3
    - pref: ignore empty http tokens

1.14.1 / 2019-05-10
===================

  * Set stricter CSP header in redirect response
  * deps: send@0.17.1
    - deps: range-parser@~1.2.1

1.14.0 / 2019-05-07
===================

  * deps: parseurl@~1.3.3
  * deps: send@0.17.0
    - deps: http-errors@~1.7.2
    - deps: mime@1.6.0
    - deps: ms@2.1.1
    - deps: statuses@~1.5.0
    - perf: remove redundant `path.normalize` call

1.13.2 / 2018-02-07
===================

  * Fix incorrect end tag in redirects
  * deps: encodeurl@~1.0.2
    - Fix encoding `%` as last character
  * deps: send@0.16.2
    - deps: depd@~1.1.2
    - deps: encodeurl@~1.0.2
    - deps: statuses@~1.4.0

1.13.1 / 2017-09-29
===================

  * Fix regression when `root` is incorrectly set to a file
  * deps: send@0.16.1

1.13.0 / 2017-09-27
===================

  * deps: send@0.16.0
    - Add 70 new types for file extensions
    - Add `immutable` option
    - Fix missing `</html>` in default error & redirects
    - Set charset as "UTF-8" for .js and .json
    - Use instance methods on steam to check for listeners
    - deps: mime@1.4.1
    - perf: improve path validation speed

1.12.6 / 2017-09-22
===================

  * deps: send@0.15.6
    - deps: debug@2.6.9
    - perf: improve `If-Match` token parsing
  * perf: improve slash collapsing

1.12.5 / 2017-09-21
===================

  * deps: parseurl@~1.3.2
    - perf: reduce overhead for full URLs
    - perf: unroll the "fast-path" `RegExp`
  * deps: send@0.15.5
    - Fix handling of modified headers with invalid dates
    - deps: etag@~1.8.1
    - deps: fresh@0.5.2

1.12.4 / 2017-08-05
===================

  * deps: send@0.15.4
    - deps: debug@2.6.8
    - deps: depd@~1.1.1
    - deps: http-errors@~1.6.2

1.12.3 / 2017-05-16
===================

  * deps: send@0.15.3
    - deps: debug@2.6.7

1.12.2 / 2017-04-26
===================

  * deps: send@0.15.2
    - deps: debug@2.6.4

1.12.1 / 2017-03-04
===================

  * deps: send@0.15.1
    - Fix issue when `Date.parse` does not return `NaN` on invalid date
    - Fix strict violation in broken environments

1.12.0 / 2017-02-25
===================

  * Send complete HTML document in redirect response
  * Set default CSP header in redirect response
  * deps: send@0.15.0
    - Fix false detection of `no-cache` request directive
    - Fix incorrect result when `If-None-Match` has both `*` and ETags
    - Fix weak `ETag` matching to match spec
    - Remove usage of `res._headers` private field
    - Support `If-Match` and `If-Unmodified-Since` headers
    - Use `res.getHeaderNames()` when available
    - Use `res.headersSent` when available
    - deps: debug@2.6.1
    - deps: etag@~1.8.0
    - deps: fresh@0.5.0
    - deps: http-errors@~1.6.1

1.11.2 / 2017-01-23
===================

  * deps: send@0.14.2
    - deps: http-errors@~1.5.1
    - deps: ms@0.7.2
    - deps: statuses@~1.3.1

1.11.1 / 2016-06-10
===================

  * Fix redirect error when `req.url` contains raw non-URL characters
  * deps: send@0.14.1

1.11.0 / 2016-06-07
===================

  * Use status code 301 for redirects
  * deps: send@0.14.0
    - Add `acceptRanges` option
    - Add `cacheControl` option
    - Attempt to combine multiple ranges into single range
    - Correctly inherit from `Stream` class
    - Fix `Content-Range` header in 416 responses when using `start`/`end` options
    - Fix `Content-Range` header missing from default 416 responses
    - Ignore non-byte `Range` headers
    - deps: http-errors@~1.5.0
    - deps: range-parser@~1.2.0
    - deps: statuses@~1.3.0
    - perf: remove argument reassignment

1.10.3 / 2016-05-30
===================

  * deps: send@0.13.2
    - Fix invalid `Content-Type` header when `send.mime.default_type` unset

1.10.2 / 2016-01-19
===================

  * deps: parseurl@~1.3.1
    - perf: enable strict mode

1.10.1 / 2016-01-16
===================

  * deps: escape-html@~1.0.3
    - perf: enable strict mode
    - perf: optimize string replacement
    - perf: use faster string coercion
  * deps: send@0.13.1
    - deps: depd@~1.1.0
    - deps: destroy@~1.0.4
    - deps: escape-html@~1.0.3
    - deps: range-parser@~1.0.3

1.10.0 / 2015-06-17
===================

  * Add `fallthrough` option
    - Allows declaring this middleware is the final destination
    - Provides better integration with Express patterns
  * Fix reading options from options prototype
  * Improve the default redirect response headers
  * deps: escape-html@1.0.2
  * deps: send@0.13.0
    - Allow Node.js HTTP server to set `Date` response header
    - Fix incorrectly removing `Content-Location` on 304 response
    - Improve the default redirect response headers
    - Send appropriate headers on default error response
    - Use `http-errors` for standard emitted errors
    - Use `statuses` instead of `http` module for status messages
    - deps: escape-html@1.0.2
    - deps: etag@~1.7.0
    - deps: fresh@0.3.0
    - deps: on-finished@~2.3.0
    - perf: enable strict mode
    - perf: remove unnecessary array allocations
  * perf: enable strict mode
  * perf: remove argument reassignment

1.9.3 / 2015-05-14
==================

  * deps: send@0.12.3
    - deps: debug@~2.2.0
    - deps: depd@~1.0.1
    - deps: etag@~1.6.0
    - deps: ms@0.7.1
    - deps: on-finished@~2.2.1

1.9.2 / 2015-03-14
==================

  * deps: send@0.12.2
    - Throw errors early for invalid `extensions` or `index` options
    - deps: debug@~2.1.3

1.9.1 / 2015-02-17
==================

  * deps: send@0.12.1
    - Fix regression sending zero-length files

1.9.0 / 2015-02-16
==================

  * deps: send@0.12.0
    - Always read the stat size from the file
    - Fix mutating passed-in `options`
    - deps: mime@1.3.4

1.8.1 / 2015-01-20
==================

  * Fix redirect loop in Node.js 0.11.14
  * deps: send@0.11.1
    - Fix root path disclosure

1.8.0 / 2015-01-05
==================

  * deps: send@0.11.0
    - deps: debug@~2.1.1
    - deps: etag@~1.5.1
    - deps: ms@0.7.0
    - deps: on-finished@~2.2.0

1.7.2 / 2015-01-02
==================

  * Fix potential open redirect when mounted at root

1.7.1 / 2014-10-22
==================

  * deps: send@0.10.1
    - deps: on-finished@~2.1.1

1.7.0 / 2014-10-15
==================

  * deps: send@0.10.0
    - deps: debug@~2.1.0
    - deps: depd@~1.0.0
    - deps: etag@~1.5.0

1.6.5 / 2015-02-04
==================

  * Fix potential open redirect when mounted at root
    - Back-ported from v1.7.2

1.6.4 / 2014-10-08
==================

  * Fix redirect loop when index file serving disabled

1.6.3 / 2014-09-24
==================

  * deps: send@0.9.3
    - deps: etag@~1.4.0

1.6.2 / 2014-09-15
==================

  * deps: send@0.9.2
    - deps: depd@0.4.5
    - deps: etag@~1.3.1
    - deps: range-parser@~1.0.2

1.6.1 / 2014-09-07
==================

  * deps: send@0.9.1
    - deps: fresh@0.2.4

1.6.0 / 2014-09-07
==================

  * deps: send@0.9.0
    - Add `lastModified` option
    - Use `etag` to generate `ETag` header
    - deps: debug@~2.0.0

1.5.4 / 2014-09-04
==================

  * deps: send@0.8.5
    - Fix a path traversal issue when using `root`
    - Fix malicious path detection for empty string path

1.5.3 / 2014-08-17
==================

  * deps: send@0.8.3

1.5.2 / 2014-08-14
==================

  * deps: send@0.8.2
    - Work around `fd` leak in Node.js 0.10 for `fs.ReadStream`

1.5.1 / 2014-08-09
==================

  * Fix parsing of weird `req.originalUrl` values
  * deps: parseurl@~1.3.0
  * deps: utils-merge@1.0.0

1.5.0 / 2014-08-05
==================

  * deps: send@0.8.1
    - Add `extensions` option

1.4.4 / 2014-08-04
==================

  * deps: send@0.7.4
    - Fix serving index files without root dir

1.4.3 / 2014-07-29
==================

  * deps: send@0.7.3
    - Fix incorrect 403 on Windows and Node.js 0.11

1.4.2 / 2014-07-27
==================

  * deps: send@0.7.2
    - deps: depd@0.4.4

1.4.1 / 2014-07-26
==================

  * deps: send@0.7.1
    - deps: depd@0.4.3

1.4.0 / 2014-07-21
==================

  * deps: parseurl@~1.2.0
    - Cache URLs based on original value
    - Remove no-longer-needed URL mis-parse work-around
    - Simplify the "fast-path" `RegExp`
  * deps: send@0.7.0
    - Add `dotfiles` option
    - deps: debug@1.0.4
    - deps: depd@0.4.2

1.3.2 / 2014-07-11
==================

  * deps: send@0.6.0
    - Cap `maxAge` value to 1 year
    - deps: debug@1.0.3

1.3.1 / 2014-07-09
==================

  * deps: parseurl@~1.1.3
    - faster parsing of href-only URLs

1.3.0 / 2014-06-28
==================

  * Add `setHeaders` option
  * Include HTML link in redirect response
  * deps: send@0.5.0
    - Accept string for `maxAge` (converted by `ms`)

1.2.3 / 2014-06-11
==================

  * deps: send@0.4.3
    - Do not throw un-catchable error on file open race condition
    - Use `escape-html` for HTML escaping
    - deps: debug@1.0.2
    - deps: finished@1.2.2
    - deps: fresh@0.2.2

1.2.2 / 2014-06-09
==================

  * deps: send@0.4.2
    - fix "event emitter leak" warnings
    - deps: debug@1.0.1
    - deps: finished@1.2.1

1.2.1 / 2014-06-02
==================

  * use `escape-html` for escaping
  * deps: send@0.4.1
    - Send `max-age` in `Cache-Control` in correct format

1.2.0 / 2014-05-29
==================

  * deps: send@0.4.0
    - Calculate ETag with md5 for reduced collisions
    - Fix wrong behavior when index file matches directory
    - Ignore stream errors after request ends
    - Skip directories in index file search
    - deps: debug@0.8.1

1.1.0 / 2014-04-24
==================

  * Accept options directly to `send` module
  * deps: send@0.3.0

1.0.4 / 2014-04-07
==================

  * Resolve relative paths at middleware setup
  * Use parseurl to parse the URL from request

1.0.3 / 2014-03-20
==================

  * Do not rely on connect-like environments

1.0.2 / 2014-03-06
==================

  * deps: send@0.2.0

1.0.1 / 2014-03-05
==================

  * Add mime export for back-compat

1.0.0 / 2014-03-05
==================

  * Genesis from `connect`


---

# serve-static

[![NPM Version][npm-version-image]][npm-url]
[![NPM Downloads][npm-downloads-image]][npm-url]
[![Linux Build][github-actions-ci-image]][github-actions-ci-url]
[![Windows Build][appveyor-image]][appveyor-url]
[![Test Coverage][coveralls-image]][coveralls-url]

## Install

This is a [Node.js](https://nodejs.org/en/) module available through the
[npm registry](https://www.npmjs.com/). Installation is done using the
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):

```sh
$ npm install serve-static
```

## API

```js
var serveStatic = require('serve-static')
```

### serveStatic(root, options)

Create a new middleware function to serve files from within a given root
directory. The file to serve will be determined by combining `req.url`
with the provided root directory. When a file is not found, instead of
sending a 404 response, this module will instead call `next()` to move on
to the next middleware, allowing for stacking and fall-backs.

#### Options

##### acceptRanges

Enable or disable accepting ranged requests, defaults to true.
Disabling this will not send `Accept-Ranges` and ignore the contents
of the `Range` request header.

##### cacheControl

Enable or disable setting `Cache-Control` response header, defaults to
true. Disabling this will ignore the `immutable` and `maxAge` options.

##### dotfiles

 Set how "dotfiles" are treated when encountered. A dotfile is a file
or directory that begins with a dot ("."). Note this check is done on
the path itself without checking if the path actually exists on the
disk. If `root` is specified, only the dotfiles above the root are
checked (i.e. the root itself can be within a dotfile when set
to "deny").

  - `'allow'` No special treatment for dotfiles.
  - `'deny'` Deny a request for a dotfile and 403/`next()`.
  - `'ignore'` Pretend like the dotfile does not exist and 404/`next()`.

The default value is similar to `'ignore'`, with the exception that this
default will not ignore the files within a directory that begins with a dot.

##### etag

Enable or disable etag generation, defaults to true.

##### extensions

Set file extension fallbacks. When set, if a file is not found, the given
extensions will be added to the file name and search for. The first that
exists will be served. Example: `['html', 'htm']`.

The default value is `false`.

##### fallthrough

Set the middleware to have client errors fall-through as just unhandled
requests, otherwise forward a client error. The difference is that client
errors like a bad request or a request to a non-existent file will cause
this middleware to simply `next()` to your next middleware when this value
is `true`. When this value is `false`, these errors (even 404s), will invoke
`next(err)`.

Typically `true` is desired such that multiple physical directories can be
mapped to the same web address or for routes to fill in non-existent files.

The value `false` can be used if this middleware is mounted at a path that
is designed to be strictly a single file system directory, which allows for
short-circuiting 404s for less overhead. This middleware will also reply to
all methods.

The default value is `true`.

##### immutable

Enable or disable the `immutable` directive in the `Cache-Control` response
header, defaults to `false`. If set to `true`, the `maxAge` option should
also be specified to enable caching. The `immutable` directive will prevent
supported clients from making conditional requests during the life of the
`maxAge` option to check if the file has changed.

##### index

By default this module will send "index.html" files in response to a request
on a directory. To disable this set `false` or to supply a new index pass a
string or an array in preferred order.

##### lastModified

Enable or disable `Last-Modified` header, defaults to true. Uses the file
system's last modified value.

##### maxAge

Provide a max-age in milliseconds for http caching, defaults to 0. This
can also be a string accepted by the [ms](https://www.npmjs.org/package/ms#readme)
module.

##### redirect

Redirect to trailing "/" when the pathname is a dir. Defaults to `true`.

##### setHeaders

Function to set custom headers on response. Alterations to the headers need to
occur synchronously. The function is called as `fn(res, path, stat)`, where
the arguments are:

  - `res` the response object
  - `path` the file path that is being sent
  - `stat` the stat object of the file that is being sent

## Examples

### Serve files with vanilla node.js http server

```js
var finalhandler = require('finalhandler')
var http = require('http')
var serveStatic = require('serve-static')

// Serve up public/ftp folder
var serve = serveStatic('public/ftp', { index: ['index.html', 'index.htm'] })

// Create server
var server = http.createServer(function onRequest (req, res) {
  serve(req, res, finalhandler(req, res))
})

// Listen
server.listen(3000)
```

### Serve all files as downloads

```js
var contentDisposition = require('content-disposition')
var finalhandler = require('finalhandler')
var http = require('http')
var serveStatic = require('serve-static')

// Serve up public/ftp folder
var serve = serveStatic('public/ftp', {
  index: false,
  setHeaders: setHeaders
})

// Set header to force download
function setHeaders (res, path) {
  res.setHeader('Content-Disposition', contentDisposition(path))
}

// Create server
var server = http.createServer(function onRequest (req, res) {
  serve(req, res, finalhandler(req, res))
})

// Listen
server.listen(3000)
```

### Serving using express

#### Simple

This is a simple example of using Express.

```js
var express = require('express')
var serveStatic = require('serve-static')

var app = express()

app.use(serveStatic('public/ftp', { index: ['default.html', 'default.htm'] }))
app.listen(3000)
```

#### Multiple roots

This example shows a simple way to search through multiple directories.
Files are searched for in `public-optimized/` first, then `public/` second
as a fallback.

```js
var express = require('express')
var path = require('path')
var serveStatic = require('serve-static')

var app = express()

app.use(serveStatic(path.join(__dirname, 'public-optimized')))
app.use(serveStatic(path.join(__dirname, 'public')))
app.listen(3000)
```

#### Different settings for paths

This example shows how to set a different max age depending on the served
file type. In this example, HTML files are not cached, while everything else
is for 1 day.

```js
var express = require('express')
var path = require('path')
var serveStatic = require('serve-static')

var app = express()

app.use(serveStatic(path.join(__dirname, 'public'), {
  maxAge: '1d',
  setHeaders: setCustomCacheControl
}))

app.listen(3000)

function setCustomCacheControl (res, path) {
  if (serveStatic.mime.lookup(path) === 'text/html') {
    // Custom Cache-Control for HTML files
    res.setHeader('Cache-Control', 'public, max-age=0')
  }
}
```

## License

[MIT](LICENSE)

[appveyor-image]: https://badgen.net/appveyor/ci/dougwilson/serve-static/master?label=windows
[appveyor-url]: https://ci.appveyor.com/project/dougwilson/serve-static
[coveralls-image]: https://badgen.net/coveralls/c/github/expressjs/serve-static/master
[coveralls-url]: https://coveralls.io/r/expressjs/serve-static?branch=master
[github-actions-ci-image]: https://badgen.net/github/checks/expressjs/serve-static/master?label=linux
[github-actions-ci-url]: https://github.com/expressjs/serve-static/actions/workflows/ci.yml
[node-image]: https://badgen.net/npm/node/serve-static
[node-url]: https://nodejs.org/en/download/
[npm-downloads-image]: https://badgen.net/npm/dm/serve-static
[npm-url]: https://npmjs.org/package/serve-static
[npm-version-image]: https://badgen.net/npm/v/serve-static


---

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [v1.2.2](https://github.com/ljharb/set-function-length/compare/v1.2.1...v1.2.2) - 2024-03-09

### Commits

- [types] use shared config [`027032f`](https://github.com/ljharb/set-function-length/commit/027032fe9cc439644a07248ea6a8d813fcc767cb)
- [actions] remove redundant finisher; use reusable workflow [`1fd4fb1`](https://github.com/ljharb/set-function-length/commit/1fd4fb1c58bd5170f0dcff7e320077c0aa2ffdeb)
- [types] use a handwritten d.ts file instead of emit [`01b9761`](https://github.com/ljharb/set-function-length/commit/01b9761742c95e1118e8c2d153ce2ae43d9731aa)
- [Deps] update `define-data-property`, `get-intrinsic`, `has-property-descriptors` [`bee8eaf`](https://github.com/ljharb/set-function-length/commit/bee8eaf7749f325357ade85cffeaeef679e513d4)
- [Dev Deps] update `call-bind`, `tape` [`5dae579`](https://github.com/ljharb/set-function-length/commit/5dae579fdc3aab91b14ebb58f9c19ee3f509d434)
- [Tests] use `@arethetypeswrong/cli` [`7e22425`](https://github.com/ljharb/set-function-length/commit/7e22425d15957fd3d6da0b6bca4afc0c8d255d2d)

## [v1.2.1](https://github.com/ljharb/set-function-length/compare/v1.2.0...v1.2.1) - 2024-02-06

### Commits

- [Dev Deps] update `call-bind`, `tape`, `typescript` [`d9a4601`](https://github.com/ljharb/set-function-length/commit/d9a460199c4c1fa37da9ebe055e2c884128f0738)
- [Deps] update `define-data-property`, `get-intrinsic` [`38d39ae`](https://github.com/ljharb/set-function-length/commit/38d39aed13a757ed36211d5b0437b88485090c6b)
- [Refactor] use `es-errors`, so things that only need those do not need `get-intrinsic` [`b4bfe5a`](https://github.com/ljharb/set-function-length/commit/b4bfe5ae0953b906d55b85f867eca5e7f673ebf4)

## [v1.2.0](https://github.com/ljharb/set-function-length/compare/v1.1.1...v1.2.0) - 2024-01-14

### Commits

- [New] add types [`f6d9088`](https://github.com/ljharb/set-function-length/commit/f6d9088b9283a3112b21c6776e8bef6d1f30558a)
- [Fix] ensure `env` properties are always booleans [`0c42f84`](https://github.com/ljharb/set-function-length/commit/0c42f84979086389b3229e1b4272697fd352275a)
- [Dev Deps] update `aud`, `call-bind`, `npmignore`, `tape` [`2b75f75`](https://github.com/ljharb/set-function-length/commit/2b75f75468093a4bb8ce8ca989b2edd2e80d95d1)
- [Deps] update `get-intrinsic`, `has-property-descriptors` [`19bf0fc`](https://github.com/ljharb/set-function-length/commit/19bf0fc4ffaa5ad425acbfa150516be9f3b6263a)
- [meta] add `sideEffects` flag [`8bb9b78`](https://github.com/ljharb/set-function-length/commit/8bb9b78c11c621123f725c9470222f43466c01d0)

## [v1.1.1](https://github.com/ljharb/set-function-length/compare/v1.1.0...v1.1.1) - 2023-10-19

### Fixed

- [Fix] move `define-data-property` to runtime deps [`#2`](https://github.com/ljharb/set-function-length/issues/2)

### Commits

- [Dev Deps] update `object-inspect`; add missing `call-bind` [`5aecf79`](https://github.com/ljharb/set-function-length/commit/5aecf79e7d6400957a5d9bd9ac20d4528908ca18)

## [v1.1.0](https://github.com/ljharb/set-function-length/compare/v1.0.1...v1.1.0) - 2023-10-13

### Commits

- [New] add `env` entry point [`475c87a`](https://github.com/ljharb/set-function-length/commit/475c87aa2f59b700aaed589d980624ec596acdcb)
- [Tests] add coverage with `nyc` [`14f0bf8`](https://github.com/ljharb/set-function-length/commit/14f0bf8c145ae60bf14a026420a06bb7be132c36)
- [eslint] fix linting failure [`fb516f9`](https://github.com/ljharb/set-function-length/commit/fb516f93c664057138c53559ef63c8622a093335)
- [Deps] update `define-data-property` [`d727e7c`](https://github.com/ljharb/set-function-length/commit/d727e7c6c9a40d7bf26797694e500ea68741feea)

## [v1.0.1](https://github.com/ljharb/set-function-length/compare/v1.0.0...v1.0.1) - 2023-10-12

### Commits

- [Refactor] use `get-intrinsic`, since it‘s in the dep graph anyways [`278a954`](https://github.com/ljharb/set-function-length/commit/278a954a06cd849051c569ff7aee56df6798933e)
- [meta] add `exports` [`72acfe5`](https://github.com/ljharb/set-function-length/commit/72acfe5a0310071fb205a72caba5ecbab24336a0)

## v1.0.0 - 2023-10-12

### Commits

- Initial implementation, tests, readme [`fce14e1`](https://github.com/ljharb/set-function-length/commit/fce14e17586460e4f294405173be72b6ffdf7e5f)
- Initial commit [`ca7ba85`](https://github.com/ljharb/set-function-length/commit/ca7ba857c7c283f9d26e21f14e71cd388f2cb722)
- npm init [`6a7e493`](https://github.com/ljharb/set-function-length/commit/6a7e493927736cebcaf5c1a84e69b8e6b7b744d8)
- Only apps should have lockfiles [`d2bf6c4`](https://github.com/ljharb/set-function-length/commit/d2bf6c43de8a51b02a0aa53e8d62cb50c4a2b0da)


---

# set-function-length <sup>[![Version Badge][npm-version-svg]][package-url]</sup>

[![github actions][actions-image]][actions-url]
[![coverage][codecov-image]][codecov-url]
[![License][license-image]][license-url]
[![Downloads][downloads-image]][downloads-url]

[![npm badge][npm-badge-png]][package-url]

Set a function’s length.

Arguments:
 - `fn`: the function
 - `length`: the new length. Must be an integer between 0 and 2**32.
 - `loose`: Optional. If true, and the length fails to be set, do not throw. Default false.

Returns `fn`.

## Usage

```javascript
var setFunctionLength = require('set-function-length');
var assert = require('assert');

function zero() {}
function one(_) {}
function two(_, __) {}

assert.equal(zero.length, 0);
assert.equal(one.length, 1);
assert.equal(two.length, 2);

assert.equal(setFunctionLength(zero, 10), zero);
assert.equal(setFunctionLength(one, 11), one);
assert.equal(setFunctionLength(two, 12), two);

assert.equal(zero.length, 10);
assert.equal(one.length, 11);
assert.equal(two.length, 12);
```

[package-url]: https://npmjs.org/package/set-function-length
[npm-version-svg]: https://versionbadg.es/ljharb/set-function-length.svg
[deps-svg]: https://david-dm.org/ljharb/set-function-length.svg
[deps-url]: https://david-dm.org/ljharb/set-function-length
[dev-deps-svg]: https://david-dm.org/ljharb/set-function-length/dev-status.svg
[dev-deps-url]: https://david-dm.org/ljharb/set-function-length#info=devDependencies
[npm-badge-png]: https://nodei.co/npm/set-function-length.png?downloads=true&stars=true
[license-image]: https://img.shields.io/npm/l/set-function-length.svg
[license-url]: LICENSE
[downloads-image]: https://img.shields.io/npm/dm/set-function-length.svg
[downloads-url]: https://npm-stat.com/charts.html?package=set-function-length
[codecov-image]: https://codecov.io/gh/ljharb/set-function-length/branch/main/graphs/badge.svg
[codecov-url]: https://app.codecov.io/gh/ljharb/set-function-length/
[actions-image]: https://img.shields.io/endpoint?url=https://github-actions-badge-u3jn4tfpocch.runkit.sh/ljharb/set-function-length
[actions-url]: https://github.com/ljharb/set-function-length/actions


---

# Polyfill for `Object.setPrototypeOf`

[![NPM Version](https://img.shields.io/npm/v/setprototypeof.svg)](https://npmjs.org/package/setprototypeof)
[![NPM Downloads](https://img.shields.io/npm/dm/setprototypeof.svg)](https://npmjs.org/package/setprototypeof)
[![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg)](https://github.com/standard/standard)

A simple cross platform implementation to set the prototype of an instianted object.  Supports all modern browsers and at least back to IE8.

## Usage:

```
$ npm install --save setprototypeof
```

```javascript
var setPrototypeOf = require('setprototypeof')

var obj = {}
setPrototypeOf(obj, {
  foo: function () {
    return 'bar'
  }
})
obj.foo() // bar
```

TypeScript is also supported:

```typescript
import setPrototypeOf from 'setprototypeof'
```


---

# shallow-clone [![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=W8YFZ425KND68) [![NPM version](https://img.shields.io/npm/v/shallow-clone.svg?style=flat)](https://www.npmjs.com/package/shallow-clone) [![NPM monthly downloads](https://img.shields.io/npm/dm/shallow-clone.svg?style=flat)](https://npmjs.org/package/shallow-clone) [![NPM total downloads](https://img.shields.io/npm/dt/shallow-clone.svg?style=flat)](https://npmjs.org/package/shallow-clone) [![Linux Build Status](https://img.shields.io/travis/jonschlinkert/shallow-clone.svg?style=flat&label=Travis)](https://travis-ci.org/jonschlinkert/shallow-clone)

> Creates a shallow clone of any JavaScript value.

Please consider following this project's author, [Jon Schlinkert](https://github.com/jonschlinkert), and consider starring the project to show your :heart: and support.

## Install

Install with [npm](https://www.npmjs.com/):

```sh
$ npm install --save shallow-clone
```

## Usage

```js
const clone = require('shallow-clone');
```

**Supports**

* array buffers
* arrays
* buffers
* dates
* errors
* float32 arrays
* float64 arrays
* int16 arrays
* int32 arrays
* int8 arrays
* maps
* objects
* primitives
* regular expressions
* sets
* symbols
* uint16 arrays
* uint32 arrays
* uint8 arrays
* uint8clamped arrays

## Arrays

By default, only the array itself is cloned (shallow), use [clone-deep](https://github.com/jonschlinkert/clone-deep) if you also need the elements in the array to be cloned.

```js
const arr = [{ a: 0 }, { b: 1 }];
const foo = clone(arr);
// foo =>  [{ 'a': 0 }, { 'b': 1 }]

// array is cloned
assert(actual === expected); // false

// array elements are not
assert.deepEqual(actual[0], expected[0]); // true
```

## Objects

Only the object is shallow cloned, use [clone-deep](https://github.com/jonschlinkert/clone-deep) if you also need the values in the object to be cloned.

```js
console.log(clone({ a: 1, b: 2, c: 3 }));
//=> {a: 1, b: 2, c: 3 }
```

## RegExp

Clones regular expressions and flags, and preserves the `.lastIndex`.

```js
const regex = clone(/foo/g); //=> /foo/g
// you can manually reset lastIndex if necessary
regex.lastIndex = 0;
```

## Primitives

Simply returns primitives unchanged.

```js
clone(0); //=> 0
clone('foo'); //=> 'foo'
```

## About

<details>
<summary><strong>Contributing</strong></summary>

Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).

</details>

<details>
<summary><strong>Running Tests</strong></summary>

Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

```sh
$ npm install && npm test
```

</details>

<details>
<summary><strong>Building docs</strong></summary>

_(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_

To generate the readme, run the following command:

```sh
$ npm install -g verbose/verb#dev verb-generate-readme && verb
```

</details>

### Related projects

You might also be interested in these projects:

* [assign-deep](https://www.npmjs.com/package/assign-deep): Deeply assign the values of all enumerable-own-properties and symbols from one or more source objects… [more](https://github.com/jonschlinkert/assign-deep) | [homepage](https://github.com/jonschlinkert/assign-deep "Deeply assign the values of all enumerable-own-properties and symbols from one or more source objects to a target object. Returns the target object.")
* [clone-deep](https://www.npmjs.com/package/clone-deep): Recursively (deep) clone JavaScript native types, like Object, Array, RegExp, Date as well as primitives. | [homepage](https://github.com/jonschlinkert/clone-deep "Recursively (deep) clone JavaScript native types, like Object, Array, RegExp, Date as well as primitives.")
* [is-plain-object](https://www.npmjs.com/package/is-plain-object): Returns true if an object was created by the `Object` constructor. | [homepage](https://github.com/jonschlinkert/is-plain-object "Returns true if an object was created by the `Object` constructor.")
* [kind-of](https://www.npmjs.com/package/kind-of): Get the native type of a value. | [homepage](https://github.com/jonschlinkert/kind-of "Get the native type of a value.")

### Contributors

| **Commits** | **Contributor** |  
| --- | --- |  
| 20 | [jonschlinkert](https://github.com/jonschlinkert) |  
| 2  | [doowb](https://github.com/doowb) |  
| 1  | [jakub-g](https://github.com/jakub-g) |  

### Author

**Jon Schlinkert**

* [GitHub Profile](https://github.com/jonschlinkert)
* [Twitter Profile](https://twitter.com/jonschlinkert)
* [LinkedIn Profile](https://linkedin.com/in/jonschlinkert)

### License

Copyright © 2019, [Jon Schlinkert](https://github.com/jonschlinkert).
Released under the [MIT License](LICENSE).

***

_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.8.0, on April 15, 2019._

---

# shallowequal [![Build Status](https://travis-ci.org/dashed/shallowequal.svg)](https://travis-ci.org/dashed/shallowequal) [![Downloads](https://img.shields.io/npm/dm/shallowequal.svg)](https://npmjs.com/shallowequal) [![npm version](https://img.shields.io/npm/v/shallowequal.svg?style=flat)](https://www.npmjs.com/package/shallowequal)

[![Greenkeeper badge](https://badges.greenkeeper.io/dashed/shallowequal.svg)](https://greenkeeper.io/)

> `shallowequal` is like lodash's [`isEqualWith`](https://lodash.com/docs/4.17.4#isEqualWith) but for shallow (strict) equal.

`shallowequal(value, other, [customizer], [thisArg])`

Performs a ***shallow equality*** comparison between two values (i.e. `value` and `other`) to determine if they are equivalent.

The equality is performed by iterating through keys on the given `value`, and returning `false` whenever any key has values which are not **strictly equal** between `value` and `other`. Otherwise, return `true` whenever the values of all keys are strictly equal.

If `customizer` (expected to be a function) is provided it is invoked to compare values. If `customizer` returns `undefined` (i.e. `void 0`), then comparisons are handled by the `shallowequal` function instead.

The `customizer` is bound to `thisArg` and invoked with three arguments: `(value, other, key)`.

**NOTE:** Docs are (shamelessly) adapted from [lodash's v3.x docs](https://lodash.com/docs/3.10.1#isEqualWith)

## Install

```sh
$ yarn add shallowequal
# npm v5+
$ npm install shallowequal
# before npm v5
$ npm install --save shallowequal
```

## Usage

```js
const shallowequal = require('shallowequal');

const object = { 'user': 'fred' };
const other = { 'user': 'fred' };

object == other;
// → false

shallowequal(object, other);
// → true
```

## Credit

Code for `shallowEqual` originated from https://github.com/gaearon/react-pure-render/ and has since been refactored to have the exact same API as `lodash.isEqualWith` (as of `v4.17.4`).

## Development

- `node.js` and `npm`. See: https://github.com/creationix/nvm#installation
- `yarn`. See: https://yarnpkg.com/en/docs/install
- `npm` dependencies. Run: `yarn install`

### Chores

- Lint: `yarn lint`
- Test: `yarn test`
- Pretty: `yarn pretty`
- Pre-publish: `yarn prepublish`

## License

MIT.


---

# shebang-command [![Build Status](https://travis-ci.org/kevva/shebang-command.svg?branch=master)](https://travis-ci.org/kevva/shebang-command)

> Get the command from a shebang


## Install

```
$ npm install shebang-command
```


## Usage

```js
const shebangCommand = require('shebang-command');

shebangCommand('#!/usr/bin/env node');
//=> 'node'

shebangCommand('#!/bin/bash');
//=> 'bash'
```


## API

### shebangCommand(string)

#### string

Type: `string`

String containing a shebang.


---

# shebang-regex [![Build Status](https://travis-ci.org/sindresorhus/shebang-regex.svg?branch=master)](https://travis-ci.org/sindresorhus/shebang-regex)

> Regular expression for matching a [shebang](https://en.wikipedia.org/wiki/Shebang_(Unix)) line


## Install

```
$ npm install shebang-regex
```


## Usage

```js
const shebangRegex = require('shebang-regex');

const string = '#!/usr/bin/env node\nconsole.log("unicorns");';

shebangRegex.test(string);
//=> true

shebangRegex.exec(string)[0];
//=> '#!/usr/bin/env node'

shebangRegex.exec(string)[1];
//=> '/usr/bin/env node'
```


## License

MIT © [Sindre Sorhus](https://sindresorhus.com)


---

# shell-quote <sup>[![Version Badge][npm-version-svg]][package-url]</sup>

[![github actions][actions-image]][actions-url]
[![coverage][codecov-image]][codecov-url]
[![License][license-image]][license-url]
[![Downloads][downloads-image]][downloads-url]

[![npm badge][npm-badge-png]][package-url]

Parse and quote shell commands.

# example

## quote

``` js
var quote = require('shell-quote/quote');
var s = quote([ 'a', 'b c d', '$f', '"g"' ]);
console.log(s);
```

output

```
a 'b c d' \$f '"g"'
```

## parse

``` js
var parse = require('shell-quote/parse');
var xs = parse('a "b c" \\$def \'it\\\'s great\'');
console.dir(xs);
```

output

```
[ 'a', 'b c', '\\$def', 'it\'s great' ]
```

## parse with an environment variable

``` js
var parse = require('shell-quote/parse');
var xs = parse('beep --boop="$PWD"', { PWD: '/home/robot' });
console.dir(xs);
```

output

```
[ 'beep', '--boop=/home/robot' ]
```

## parse with custom escape character

``` js
var parse = require('shell-quote/parse');
var xs = parse('beep ^--boop="$PWD"', { PWD: '/home/robot' }, { escape: '^' });
console.dir(xs);
```

output

```
[ 'beep --boop=/home/robot' ]
```

## parsing shell operators

``` js
var parse = require('shell-quote/parse');
var xs = parse('beep || boop > /byte');
console.dir(xs);
```

output:

```
[ 'beep', { op: '||' }, 'boop', { op: '>' }, '/byte' ]
```

## parsing shell comment

``` js
var parse = require('shell-quote/parse');
var xs = parse('beep > boop # > kaboom');
console.dir(xs);
```

output:

```
[ 'beep', { op: '>' }, 'boop', { comment: '> kaboom' } ]
```

# methods

``` js
var quote = require('shell-quote/quote');
var parse = require('shell-quote/parse');
```

## quote(args)

Return a quoted string for the array `args` suitable for using in shell
commands.

## parse(cmd, env={})

Return an array of arguments from the quoted string `cmd`.

Interpolate embedded bash-style `$VARNAME` and `${VARNAME}` variables with
the `env` object which like bash will replace undefined variables with `""`.

`env` is usually an object but it can also be a function to perform lookups.
When `env(key)` returns a string, its result will be output just like `env[key]`
would. When `env(key)` returns an object, it will be inserted into the result
array like the operator objects.

When a bash operator is encountered, the element in the array with be an object
with an `"op"` key set to the operator string. For example:

```
'beep || boop > /byte'
```

parses as:

```
[ 'beep', { op: '||' }, 'boop', { op: '>' }, '/byte' ]
```

# install

With [npm](http://npmjs.org) do:

```
npm install shell-quote
```

# license

MIT

[package-url]: https://npmjs.org/package/shell-quote
[npm-version-svg]: https://versionbadg.es/ljharb/shell-quote.svg
[deps-svg]: https://david-dm.org/ljharb/shell-quote.svg
[deps-url]: https://david-dm.org/ljharb/shell-quote
[dev-deps-svg]: https://david-dm.org/ljharb/shell-quote/dev-status.svg
[dev-deps-url]: https://david-dm.org/ljharb/shell-quote#info=devDependencies
[npm-badge-png]: https://nodei.co/npm/shell-quote.png?downloads=true&stars=true
[license-image]: https://img.shields.io/npm/l/shell-quote.svg
[license-url]: LICENSE
[downloads-image]: https://img.shields.io/npm/dm/shell-quote.svg
[downloads-url]: https://npm-stat.com/charts.html?package=shell-quote
[codecov-image]: https://codecov.io/gh/ljharb/shell-quote/branch/main/graphs/badge.svg
[codecov-url]: https://app.codecov.io/gh/ljharb/shell-quote/
[actions-image]: https://img.shields.io/endpoint?url=https://github-actions-badge-u3jn4tfpocch.runkit.sh/ljharb/shell-quote
[actions-url]: https://github.com/ljharb/shell-quote/actions


---

# Security Policy

## Supported Versions

Only the latest major version is supported at any given time.

## Reporting a Vulnerability

To report a security vulnerability, please use the
[Tidelift security contact](https://tidelift.com/security).
Tidelift will coordinate the fix and disclosure.


---

# Change Log

## [Unreleased](https://github.com/shelljs/shelljs/tree/HEAD)

[Full Changelog](https://github.com/shelljs/shelljs/compare/v0.8.2...HEAD)

**Closed issues:**

- Shelljs print stderr to console even if exec-only "silent" is true [\#905](https://github.com/shelljs/shelljs/issues/905)
- refactor: remove common.state.tempDir [\#902](https://github.com/shelljs/shelljs/issues/902)
- Can't suppress stdout for echo [\#899](https://github.com/shelljs/shelljs/issues/899)
- exec\(\) doesn't apply the arguments correctly [\#895](https://github.com/shelljs/shelljs/issues/895)
- Travis CI currently broken [\#893](https://github.com/shelljs/shelljs/issues/893)
- shell.exec\('npm pack'\) painfully slow [\#885](https://github.com/shelljs/shelljs/issues/885)
- shelljs.exec cannot find app.asar/node\_modules/shelljs/src/exec-child.js [\#881](https://github.com/shelljs/shelljs/issues/881)
- test infra: mocks and skipOnWin conflict [\#862](https://github.com/shelljs/shelljs/issues/862)
- Support for shell function completion on IDE [\#859](https://github.com/shelljs/shelljs/issues/859)
- echo command shows options in stdout [\#855](https://github.com/shelljs/shelljs/issues/855)
- silent does not always work [\#851](https://github.com/shelljs/shelljs/issues/851)
- Appveyor installs the latest npm, instead of the latest compatible npm [\#844](https://github.com/shelljs/shelljs/issues/844)
- Force symbolic link \(ln -sf\) does not overwrite/recreate existing destination [\#830](https://github.com/shelljs/shelljs/issues/830)
- inconsistent result when trying to echo to a file [\#798](https://github.com/shelljs/shelljs/issues/798)
- Prevent require\(\)ing executable-only files [\#789](https://github.com/shelljs/shelljs/issues/789)
- Cannot set property to of \[object String\] which has only a getter [\#752](https://github.com/shelljs/shelljs/issues/752)
- which\(\) should check executability before returning a value [\#657](https://github.com/shelljs/shelljs/issues/657)
- Bad encoding experience [\#456](https://github.com/shelljs/shelljs/issues/456)
- phpcs very slow [\#440](https://github.com/shelljs/shelljs/issues/440)
- Error shown when triggering a sigint during shelljs.exec if process.on sigint is defined [\#254](https://github.com/shelljs/shelljs/issues/254)
- `.to\(file\)` does not mute STDIO output [\#146](https://github.com/shelljs/shelljs/issues/146)
- Escaping shell arguments to exec\(\) [\#143](https://github.com/shelljs/shelljs/issues/143)
- Allow multiple string arguments for exec\(\) [\#103](https://github.com/shelljs/shelljs/issues/103)
- cp does not recursively copy from readonly location  [\#98](https://github.com/shelljs/shelljs/issues/98)
- Handling permissions errors on file I/O [\#64](https://github.com/shelljs/shelljs/issues/64)

**Merged pull requests:**

- refactor: don't expose tempdir in common.state [\#903](https://github.com/shelljs/shelljs/pull/903) ([nfischer](https://github.com/nfischer))
- chore\(ci\): fix codecov on travis [\#897](https://github.com/shelljs/shelljs/pull/897) ([nfischer](https://github.com/nfischer))
- chore\(npm\): add ci-or-install script [\#896](https://github.com/shelljs/shelljs/pull/896) ([nfischer](https://github.com/nfischer))
- Fix silent exec [\#892](https://github.com/shelljs/shelljs/pull/892) ([nfischer](https://github.com/nfischer))
- chore\(appveyor\): run entire test matrix [\#886](https://github.com/shelljs/shelljs/pull/886) ([nfischer](https://github.com/nfischer))
- docs: remove gitter badge [\#880](https://github.com/shelljs/shelljs/pull/880) ([nfischer](https://github.com/nfischer))
- grep includes the i flag [\#876](https://github.com/shelljs/shelljs/pull/876) ([ppsleep](https://github.com/ppsleep))
- Fix\(which\): match only executable files \(\#657\) [\#874](https://github.com/shelljs/shelljs/pull/874) ([termosa](https://github.com/termosa))
- chore: rename some tests [\#871](https://github.com/shelljs/shelljs/pull/871) ([nfischer](https://github.com/nfischer))
- Fix cp from readonly source [\#870](https://github.com/shelljs/shelljs/pull/870) ([nfischer](https://github.com/nfischer))
- chore: bump dev dependencies and add package-lock [\#864](https://github.com/shelljs/shelljs/pull/864) ([nfischer](https://github.com/nfischer))
- fix\(mocks\): fix conflict between mocks and skip [\#863](https://github.com/shelljs/shelljs/pull/863) ([nfischer](https://github.com/nfischer))
- chore: output npm version in travis [\#850](https://github.com/shelljs/shelljs/pull/850) ([nfischer](https://github.com/nfischer))
- Prevent require-ing bin/shjs [\#848](https://github.com/shelljs/shelljs/pull/848) ([freitagbr](https://github.com/freitagbr))
- chore\(appveyor\): do not use latest npm [\#847](https://github.com/shelljs/shelljs/pull/847) ([nfischer](https://github.com/nfischer))
- chore: update shelljs-release version [\#846](https://github.com/shelljs/shelljs/pull/846) ([nfischer](https://github.com/nfischer))

## [v0.8.2](https://github.com/shelljs/shelljs/tree/v0.8.2) (2018-05-08)
[Full Changelog](https://github.com/shelljs/shelljs/compare/v0.8.1...v0.8.2)

**Closed issues:**

- High severity vulnerability in shelljs 0.8.1 [\#842](https://github.com/shelljs/shelljs/issues/842)
- Add test for ls\(\) on a symlink to a directory [\#795](https://github.com/shelljs/shelljs/issues/795)
- Harden shell.exec by writing the child process in a source file [\#782](https://github.com/shelljs/shelljs/issues/782)
- shell.exec\(\) doesn't respond correctly to config.fatal = true [\#735](https://github.com/shelljs/shelljs/issues/735)
- Merge 'exec: internal error' with ShellJSInternalError [\#734](https://github.com/shelljs/shelljs/issues/734)
- exec returning null from command [\#724](https://github.com/shelljs/shelljs/issues/724)
- Only Get Stderr from Exec [\#371](https://github.com/shelljs/shelljs/issues/371)
- Execute child.stdout.on before child.on\("exit"\)  [\#224](https://github.com/shelljs/shelljs/issues/224)

**Merged pull requests:**

- Workaround codecov bug of miscalculation of coverage \(\#795\) [\#838](https://github.com/shelljs/shelljs/pull/838) ([dwi2](https://github.com/dwi2))
- Update doc comments and regenerate README.md. [\#825](https://github.com/shelljs/shelljs/pull/825) ([Zearin](https://github.com/Zearin))
- chore: update contributing guidelines [\#817](https://github.com/shelljs/shelljs/pull/817) ([nfischer](https://github.com/nfischer))
- chore\(lint\): don't allow excess trailing newlines [\#816](https://github.com/shelljs/shelljs/pull/816) ([nfischer](https://github.com/nfischer))
- Remove separate "internal error" from exec [\#802](https://github.com/shelljs/shelljs/pull/802) ([freitagbr](https://github.com/freitagbr))

## [v0.8.1](https://github.com/shelljs/shelljs/tree/v0.8.1) (2018-01-20)
[Full Changelog](https://github.com/shelljs/shelljs/compare/v0.8.0...v0.8.1)

**Closed issues:**

- Exec failing with internal error when piping large output [\#818](https://github.com/shelljs/shelljs/issues/818)

**Merged pull requests:**

- Revert "refactor\(exec\): remove paramsFile \(\#807\)" [\#819](https://github.com/shelljs/shelljs/pull/819) ([nfischer](https://github.com/nfischer))

## [v0.8.0](https://github.com/shelljs/shelljs/tree/v0.8.0) (2018-01-12)
[Full Changelog](https://github.com/shelljs/shelljs/compare/v0.7.8...v0.8.0)

**Closed issues:**

- Snyk vulnerability DB reporting command injection vulnerability in ShellJS [\#810](https://github.com/shelljs/shelljs/issues/810)
- chore: upgrade nyc [\#803](https://github.com/shelljs/shelljs/issues/803)
- Update CI to use Node v9 [\#799](https://github.com/shelljs/shelljs/issues/799)
- Link to FAQ wiki section in our issue template [\#787](https://github.com/shelljs/shelljs/issues/787)
- Is it possible to get a js library\(file\) for ShellJS [\#776](https://github.com/shelljs/shelljs/issues/776)
- 48, [\#774](https://github.com/shelljs/shelljs/issues/774)
- 47 [\#773](https://github.com/shelljs/shelljs/issues/773)
- Exec function calls JSON.stringify on command [\#772](https://github.com/shelljs/shelljs/issues/772)
- getting different result from terminal and with shelljs  [\#769](https://github.com/shelljs/shelljs/issues/769)
- test\(\) does not support -w and -x options [\#768](https://github.com/shelljs/shelljs/issues/768)
- Snyk "high severity" issue [\#766](https://github.com/shelljs/shelljs/issues/766)
- Snyk "high security [\#765](https://github.com/shelljs/shelljs/issues/765)
- ShellJS doesn't respect NPM Registry being set outside of it [\#761](https://github.com/shelljs/shelljs/issues/761)
- Run second shell script [\#756](https://github.com/shelljs/shelljs/issues/756)
- shelljs seems NOT compatible with nexe under CentOS 6.5 [\#754](https://github.com/shelljs/shelljs/issues/754)
- Feature request: pushd/popd -q option [\#753](https://github.com/shelljs/shelljs/issues/753)
- cat doesn't support '-n' option [\#750](https://github.com/shelljs/shelljs/issues/750)
- shelljs run xcodebuild error [\#749](https://github.com/shelljs/shelljs/issues/749)
- Add wrappers around fs.statSync and fs.lstatSync [\#745](https://github.com/shelljs/shelljs/issues/745)
- Improve coverage for exec\(\) [\#742](https://github.com/shelljs/shelljs/issues/742)
- Improve coverage for head\(\) [\#741](https://github.com/shelljs/shelljs/issues/741)
- shelljs is no longer used in PDF.js [\#737](https://github.com/shelljs/shelljs/issues/737)
- ls doesn't follow links to directories [\#733](https://github.com/shelljs/shelljs/issues/733)
- Add test for `ls regular-file.txt` [\#732](https://github.com/shelljs/shelljs/issues/732)
- Clean up common tests [\#714](https://github.com/shelljs/shelljs/issues/714)
- Cant get encoding buffer to work on exec [\#675](https://github.com/shelljs/shelljs/issues/675)
- Set up Codecov for the project [\#671](https://github.com/shelljs/shelljs/issues/671)
- ShellJS: internal error Error: EBUSY: resource busy or locked, lstat 'C:\pagefile.sys' [\#514](https://github.com/shelljs/shelljs/issues/514)
- Feature request: provide a way to skip option parsing [\#778](https://github.com/shelljs/shelljs/issues/778)
- Switch to os.homedir\(\) when we move to v4+ [\#683](https://github.com/shelljs/shelljs/issues/683)
- Drop support for v0.12 [\#647](https://github.com/shelljs/shelljs/issues/647)
- feature: echo -n [\#559](https://github.com/shelljs/shelljs/issues/559)
- Don't kill the node process upon unexpected error [\#483](https://github.com/shelljs/shelljs/issues/483)
- Echo doesn't return value ending in a trailing newline [\#476](https://github.com/shelljs/shelljs/issues/476)
- Synchronous exec stalls permenantly when there is an error/w the shell [\#7](https://github.com/shelljs/shelljs/issues/7)

**Merged pull requests:**

- docs: announce plugin API [\#812](https://github.com/shelljs/shelljs/pull/812) ([nfischer](https://github.com/nfischer))
- chore: update CI to Node v9 [\#811](https://github.com/shelljs/shelljs/pull/811) ([nfischer](https://github.com/nfischer))
- refactor\(exec\): remove paramsFile [\#807](https://github.com/shelljs/shelljs/pull/807) ([nfischer](https://github.com/nfischer))
- chore: update nyc dependency [\#805](https://github.com/shelljs/shelljs/pull/805) ([nfischer](https://github.com/nfischer))
- refactor: harden plugins against unknown options [\#804](https://github.com/shelljs/shelljs/pull/804) ([nfischer](https://github.com/nfischer))
- chore\(eslint\): use words instead of numbers [\#797](https://github.com/shelljs/shelljs/pull/797) ([nfischer](https://github.com/nfischer))
- Add note to issue template about FAQ [\#794](https://github.com/shelljs/shelljs/pull/794) ([freitagbr](https://github.com/freitagbr))
- Remove codeFile parameter [\#791](https://github.com/shelljs/shelljs/pull/791) ([nfischer](https://github.com/nfischer))
- Use execFileSync to launch child process [\#790](https://github.com/shelljs/shelljs/pull/790) ([nfischer](https://github.com/nfischer))
- refactor\(exec\): move child process to source file [\#786](https://github.com/shelljs/shelljs/pull/786) ([nfischer](https://github.com/nfischer))
- Remove unnecessary shell.error checks from common tests [\#785](https://github.com/shelljs/shelljs/pull/785) ([freitagbr](https://github.com/freitagbr))
- Add a test for ls for a single file [\#784](https://github.com/shelljs/shelljs/pull/784) ([freitagbr](https://github.com/freitagbr))
- Wrap fs.statSync and fs.lstatSync [\#783](https://github.com/shelljs/shelljs/pull/783) ([freitagbr](https://github.com/freitagbr))
- chore: set AVA options [\#780](https://github.com/shelljs/shelljs/pull/780) ([nfischer](https://github.com/nfischer))
- chore: clean up refs to unsupported node versions [\#779](https://github.com/shelljs/shelljs/pull/779) ([nfischer](https://github.com/nfischer))
- Added `-q` \(quiet\) option to `push`, `popd`, `dirs` functions. [\#777](https://github.com/shelljs/shelljs/pull/777) ([alexreg](https://github.com/alexreg))
- feat\(cat\): number output lines \(\#750\) [\#775](https://github.com/shelljs/shelljs/pull/775) ([gcca](https://github.com/gcca))
- refactor\(test\): update AVA and refactor tests [\#760](https://github.com/shelljs/shelljs/pull/760) ([nfischer](https://github.com/nfischer))
- chore: add skipOnWin and skipOnUnix test helpers [\#746](https://github.com/shelljs/shelljs/pull/746) ([nfischer](https://github.com/nfischer))
- test\(exec\): add tests for coverage [\#744](https://github.com/shelljs/shelljs/pull/744) ([nfischer](https://github.com/nfischer))
- test\(head\): improve coverage [\#743](https://github.com/shelljs/shelljs/pull/743) ([nfischer](https://github.com/nfischer))
- Remove PDF.js mention from README.md [\#738](https://github.com/shelljs/shelljs/pull/738) ([voy](https://github.com/voy))
- Provide an API to pass parameters which resemble options [\#792](https://github.com/shelljs/shelljs/pull/792) ([nfischer](https://github.com/nfischer))
- Fix ls not following links to directories by default [\#764](https://github.com/shelljs/shelljs/pull/764) ([freitagbr](https://github.com/freitagbr))
- Add "encoding" option to exec [\#763](https://github.com/shelljs/shelljs/pull/763) ([freitagbr](https://github.com/freitagbr))
- Merge dev into master [\#731](https://github.com/shelljs/shelljs/pull/731) ([freitagbr](https://github.com/freitagbr))
- Deprecate common.getUserHome, advise using os.homedir instead [\#725](https://github.com/shelljs/shelljs/pull/725) ([freitagbr](https://github.com/freitagbr))
- Echo test mocks [\#708](https://github.com/shelljs/shelljs/pull/708) ([freitagbr](https://github.com/freitagbr))
- Safely exit by throwing an error [\#546](https://github.com/shelljs/shelljs/pull/546) ([freitagbr](https://github.com/freitagbr))
- chore\(make\): depreciate shelljs/make [\#431](https://github.com/shelljs/shelljs/pull/431) ([ariporad](https://github.com/ariporad))

## [v0.7.8](https://github.com/shelljs/shelljs/tree/v0.7.8) (2017-06-07)
[Full Changelog](https://github.com/shelljs/shelljs/compare/v0.7.7...v0.7.8)

**Closed issues:**

- Add node v8 to CI [\#729](https://github.com/shelljs/shelljs/issues/729)
- Exec not working in Electron ! [\#726](https://github.com/shelljs/shelljs/issues/726)
- is rechoir used anywhere? [\#723](https://github.com/shelljs/shelljs/issues/723)
- ShellJS: internal error on shelljs.mkdir\('myFile/myDir'\) [\#720](https://github.com/shelljs/shelljs/issues/720)
- Can't make sed perform global replace [\#719](https://github.com/shelljs/shelljs/issues/719)
- grep: option not recognized: l [\#717](https://github.com/shelljs/shelljs/issues/717)
- Problems getting code, stdout, stderr [\#715](https://github.com/shelljs/shelljs/issues/715)
- Copying hidden files fails on Windows 10 [\#711](https://github.com/shelljs/shelljs/issues/711)
- How am I suppose to handle errors with ShellJS? [\#707](https://github.com/shelljs/shelljs/issues/707)
- use cp\('-r', './src', './dist'\) bug [\#705](https://github.com/shelljs/shelljs/issues/705)
- Way to ignore files in globs. [\#699](https://github.com/shelljs/shelljs/issues/699)
- Buffer constructor is deprecated [\#694](https://github.com/shelljs/shelljs/issues/694)
- source command not working via exec method. [\#693](https://github.com/shelljs/shelljs/issues/693)
- Would you be interested in a PR for `open`? [\#692](https://github.com/shelljs/shelljs/issues/692)
- Get rid of common.platform in favor of process.platform [\#670](https://github.com/shelljs/shelljs/issues/670)
- Passing empty string to cp throws internal error [\#664](https://github.com/shelljs/shelljs/issues/664)
- Why does sed split files into an array, call replace on each line and rejoin? [\#645](https://github.com/shelljs/shelljs/issues/645)
- feat: cp & mv should not overwrite recently created files [\#631](https://github.com/shelljs/shelljs/issues/631)
- Echo tests unnecessarily run tests in own process [\#622](https://github.com/shelljs/shelljs/issues/622)
- rm -rf on a symbolic link to a dir deletes its contents [\#587](https://github.com/shelljs/shelljs/issues/587)
- "Cannot extract package" with node-webkit [\#181](https://github.com/shelljs/shelljs/issues/181)
- EBADF, bad file descriptor [\#180](https://github.com/shelljs/shelljs/issues/180)

**Merged pull requests:**

- Add node 8 to CI [\#730](https://github.com/shelljs/shelljs/pull/730) ([freitagbr](https://github.com/freitagbr))
- fix\(mkdir\): improve error handling around files [\#721](https://github.com/shelljs/shelljs/pull/721) ([nfischer](https://github.com/nfischer))
- Properly handle directories as arguments [\#713](https://github.com/shelljs/shelljs/pull/713) ([nfischer](https://github.com/nfischer))
- Add common.buffer [\#710](https://github.com/shelljs/shelljs/pull/710) ([freitagbr](https://github.com/freitagbr))
- Fix common.expand error [\#709](https://github.com/shelljs/shelljs/pull/709) ([freitagbr](https://github.com/freitagbr))
- refactor: remove unnecessary common.js imports [\#703](https://github.com/shelljs/shelljs/pull/703) ([nfischer](https://github.com/nfischer))
- Fix \#631 throw error when overwriting recently created file [\#702](https://github.com/shelljs/shelljs/pull/702) ([uttpal](https://github.com/uttpal))
- Small clarification of verbose flag [\#691](https://github.com/shelljs/shelljs/pull/691) ([zommerfelds](https://github.com/zommerfelds))
- fix\(grep, sed, sort, uniq\): Split only on newline characters [\#690](https://github.com/shelljs/shelljs/pull/690) ([freitagbr](https://github.com/freitagbr))
- Refactor: Use process.platform across codebase [\#689](https://github.com/shelljs/shelljs/pull/689) ([freitagbr](https://github.com/freitagbr))
- Remove contents of symlink to dir with rm -rf [\#688](https://github.com/shelljs/shelljs/pull/688) ([freitagbr](https://github.com/freitagbr))
- Echo stdout [\#677](https://github.com/shelljs/shelljs/pull/677) ([nfischer](https://github.com/nfischer))

## [v0.7.7](https://github.com/shelljs/shelljs/tree/v0.7.7) (2017-03-09)
[Full Changelog](https://github.com/shelljs/shelljs/compare/v0.7.6...v0.7.7)

**Closed issues:**

- Error output should be consistent across all platforms. [\#681](https://github.com/shelljs/shelljs/issues/681)
- \*CRITICAL data loss\* shell.cp\(\) Content of file is erased when trying to copy it to the folder it already belongs to [\#678](https://github.com/shelljs/shelljs/issues/678)
- Use with webpack broken in 0.7.6 [\#667](https://github.com/shelljs/shelljs/issues/667)
- Difference between bash ls -R and ShellJS ls -R with symlinks [\#666](https://github.com/shelljs/shelljs/issues/666)
- Refactor which\(\) \(too many repeated code blocks\) [\#656](https://github.com/shelljs/shelljs/issues/656)
- find\(\) raises error when unable to find any files matching, expected to return empty array. [\#653](https://github.com/shelljs/shelljs/issues/653)
- Reformat the markdown in RELEASE.md [\#642](https://github.com/shelljs/shelljs/issues/642)
- rm -rf doesn't work if the directory contains an asar archive in Electron [\#618](https://github.com/shelljs/shelljs/issues/618)
- Add support for other file types in rm [\#617](https://github.com/shelljs/shelljs/issues/617)
- Feature request: ls -L option [\#563](https://github.com/shelljs/shelljs/issues/563)
- How to send SIGINT signal to child process launched with exec [\#518](https://github.com/shelljs/shelljs/issues/518)
- feature request: option to add node\_modules to the path for shelljs scripts [\#469](https://github.com/shelljs/shelljs/issues/469)
- high cpu usage during synchronous exec [\#167](https://github.com/shelljs/shelljs/issues/167)

**Merged pull requests:**

- Add support for removing fifos [\#687](https://github.com/shelljs/shelljs/pull/687) ([freitagbr](https://github.com/freitagbr))
- chore: add codecov script to appveyor CI [\#686](https://github.com/shelljs/shelljs/pull/686) ([nfischer](https://github.com/nfischer))
- Refactor tests to improve readability [\#685](https://github.com/shelljs/shelljs/pull/685) ([nfischer](https://github.com/nfischer))
- fix: convert error output to be consistent cross-platform [\#684](https://github.com/shelljs/shelljs/pull/684) ([nfischer](https://github.com/nfischer))
- chore: add codecov [\#682](https://github.com/shelljs/shelljs/pull/682) ([nfischer](https://github.com/nfischer))
- Fix cp overwriting identical files [\#679](https://github.com/shelljs/shelljs/pull/679) ([freitagbr](https://github.com/freitagbr))
- Modified glob pattern. Fixes \#666 [\#676](https://github.com/shelljs/shelljs/pull/676) ([frandiox](https://github.com/frandiox))
- refactor\(parseOptions\): better handle errors [\#674](https://github.com/shelljs/shelljs/pull/674) ([nfischer](https://github.com/nfischer))
- test: add misc. tests to improve coverage [\#673](https://github.com/shelljs/shelljs/pull/673) ([nfischer](https://github.com/nfischer))
- test: don't count hard-to-test lines for coverage [\#672](https://github.com/shelljs/shelljs/pull/672) ([nfischer](https://github.com/nfischer))
- fix: switch commands.json -\> commands.js [\#668](https://github.com/shelljs/shelljs/pull/668) ([nfischer](https://github.com/nfischer))
- ls -L \(follow symlinks\) [\#665](https://github.com/shelljs/shelljs/pull/665) ([frandiox](https://github.com/frandiox))
- docs\(chmod\): document `options` argument [\#663](https://github.com/shelljs/shelljs/pull/663) ([gkalpak](https://github.com/gkalpak))
- docs: clean up RELEASE.md [\#662](https://github.com/shelljs/shelljs/pull/662) ([nfischer](https://github.com/nfischer))
- docs: miscellaneous README changes [\#661](https://github.com/shelljs/shelljs/pull/661) ([nfischer](https://github.com/nfischer))
- Fix typo in README [\#660](https://github.com/shelljs/shelljs/pull/660) ([faheel](https://github.com/faheel))
- refactor: reduce repeated code in which\(\) [\#659](https://github.com/shelljs/shelljs/pull/659) ([nfischer](https://github.com/nfischer))
- feature: add -a option for which command [\#655](https://github.com/shelljs/shelljs/pull/655) ([termosa](https://github.com/termosa))
- Fix find ENOENT [\#654](https://github.com/shelljs/shelljs/pull/654) ([freitagbr](https://github.com/freitagbr))
- Safely exit by throwing an error [\#649](https://github.com/shelljs/shelljs/pull/649) ([freitagbr](https://github.com/freitagbr))
- Chore drop 0.12 [\#648](https://github.com/shelljs/shelljs/pull/648) ([nfischer](https://github.com/nfischer))
- chore\(lint\): Enforce a trailing comma for multi-line [\#646](https://github.com/shelljs/shelljs/pull/646) ([nfischer](https://github.com/nfischer))
- docs\(release\): use bulleted list [\#643](https://github.com/shelljs/shelljs/pull/643) ([freitagbr](https://github.com/freitagbr))

## [v0.7.6](https://github.com/shelljs/shelljs/tree/v0.7.6) (2017-01-08)
[Full Changelog](https://github.com/shelljs/shelljs/compare/v0.7.5...v0.7.6)

**Closed issues:**

- unable to execute ionic command with shell js  [\#640](https://github.com/shelljs/shelljs/issues/640)
- How to increase ShellJS buffer size? [\#639](https://github.com/shelljs/shelljs/issues/639)
- mkdir fails with non-normalized path [\#634](https://github.com/shelljs/shelljs/issues/634)
- Move execPath into common [\#633](https://github.com/shelljs/shelljs/issues/633)
- QUESTION: Feedback while an operation is running? [\#629](https://github.com/shelljs/shelljs/issues/629)
- Test setup/cleanup is broken [\#621](https://github.com/shelljs/shelljs/issues/621)
- Ignore temp directories when running lint [\#620](https://github.com/shelljs/shelljs/issues/620)
- parseOptions should throw an error if the option string doesn't start with '-' [\#614](https://github.com/shelljs/shelljs/issues/614)
- chore: LGTM.co is gone [\#595](https://github.com/shelljs/shelljs/issues/595)
- refactor: objectAssign should refer to Object.assign if it exists, or the internal polyfill otherwise [\#592](https://github.com/shelljs/shelljs/issues/592)
- parseOptions: allow a way to keep errors silent \(exception only\) [\#591](https://github.com/shelljs/shelljs/issues/591)
- \[Question\] commands with multiple options / arguments? [\#589](https://github.com/shelljs/shelljs/issues/589)
- feature: GNU Parallel  [\#585](https://github.com/shelljs/shelljs/issues/585)
- write to file [\#568](https://github.com/shelljs/shelljs/issues/568)
- Cannot figure out how to disable globbing for rm [\#567](https://github.com/shelljs/shelljs/issues/567)
- Switch to the ava test framework [\#560](https://github.com/shelljs/shelljs/issues/560)
- Option not recognized [\#556](https://github.com/shelljs/shelljs/issues/556)
- chore: add @freitagbr to LGTM maintainers [\#552](https://github.com/shelljs/shelljs/issues/552)
- chore: set up dev branch [\#548](https://github.com/shelljs/shelljs/issues/548)
- bug: cp\(\) doesn't always copy everything [\#547](https://github.com/shelljs/shelljs/issues/547)
- User-friendly lint command [\#544](https://github.com/shelljs/shelljs/issues/544)
- Lint warning [\#542](https://github.com/shelljs/shelljs/issues/542)
- chore: add nodejs v7 to CI [\#537](https://github.com/shelljs/shelljs/issues/537)
- error.code is not always available [\#536](https://github.com/shelljs/shelljs/issues/536)
- Add shx as a dependency for testing [\#525](https://github.com/shelljs/shelljs/issues/525)
- Feature request: allow `common.error\(\)` to optionally not insert a prefix and optionally not print to console [\#523](https://github.com/shelljs/shelljs/issues/523)
- Feature request: Add "shelljs.unlink" [\#519](https://github.com/shelljs/shelljs/issues/519)
- Sed should allow a replacement string to contain `\1` for match groups [\#507](https://github.com/shelljs/shelljs/issues/507)
- Usage with neodoc [\#445](https://github.com/shelljs/shelljs/issues/445)
- \[ Feature idea \] synchronous sleep command [\#441](https://github.com/shelljs/shelljs/issues/441)
- Improve test coverage [\#347](https://github.com/shelljs/shelljs/issues/347)
- Add a way to prevent shell-expansion on commands \(this issue is not for exec\) [\#345](https://github.com/shelljs/shelljs/issues/345)
- Chown [\#183](https://github.com/shelljs/shelljs/issues/183)
- spawn EMFILE [\#81](https://github.com/shelljs/shelljs/issues/81)
- Rewrite exec using execsync-ng \(which uses node-ffi\) [\#66](https://github.com/shelljs/shelljs/issues/66)
- `exec` gets stuck on my Debian box [\#51](https://github.com/shelljs/shelljs/issues/51)
- 100% cpu usage when a nodejs script goes side ways executing a command. [\#5](https://github.com/shelljs/shelljs/issues/5)

**Merged pull requests:**

- refactor: add config.reset\(\) and .resetForTesting\(\) [\#641](https://github.com/shelljs/shelljs/pull/641) ([nfischer](https://github.com/nfischer))
- chore: set up test coverage [\#638](https://github.com/shelljs/shelljs/pull/638) ([nfischer](https://github.com/nfischer))
- refactor: create common.execPath [\#636](https://github.com/shelljs/shelljs/pull/636) ([nfischer](https://github.com/nfischer))
- fix: allow non-normalized paths as input to mkdir [\#635](https://github.com/shelljs/shelljs/pull/635) ([nfischer](https://github.com/nfischer))
- Finalize moving to ava [\#630](https://github.com/shelljs/shelljs/pull/630) ([freitagbr](https://github.com/freitagbr))
- test: refactor pushd tests to AVA [\#627](https://github.com/shelljs/shelljs/pull/627) ([nfischer](https://github.com/nfischer))
- test: refactor popd tests to AVA [\#626](https://github.com/shelljs/shelljs/pull/626) ([nfischer](https://github.com/nfischer))
- test: refactor shjs tests to AVA [\#625](https://github.com/shelljs/shelljs/pull/625) ([nfischer](https://github.com/nfischer))
- test: remove tests for make \(deprecated\) [\#624](https://github.com/shelljs/shelljs/pull/624) ([nfischer](https://github.com/nfischer))
- Ignore test temp directories during linting [\#623](https://github.com/shelljs/shelljs/pull/623) ([freitagbr](https://github.com/freitagbr))
- refactor: list all commands in commands.json [\#616](https://github.com/shelljs/shelljs/pull/616) ([nfischer](https://github.com/nfischer))
- Throw an error if the options string does not start with '-' [\#615](https://github.com/shelljs/shelljs/pull/615) ([freitagbr](https://github.com/freitagbr))
- chore: switch to files attribute from npmignore [\#613](https://github.com/shelljs/shelljs/pull/613) ([nfischer](https://github.com/nfischer))
- test: refactor 'test' command tests to AVA [\#612](https://github.com/shelljs/shelljs/pull/612) ([nfischer](https://github.com/nfischer))
- test: refactor find tests to AVA [\#611](https://github.com/shelljs/shelljs/pull/611) ([nfischer](https://github.com/nfischer))
- test: refactor ln tests to AVA [\#610](https://github.com/shelljs/shelljs/pull/610) ([nfischer](https://github.com/nfischer))
- test: refactor ls to use AVA [\#609](https://github.com/shelljs/shelljs/pull/609) ([nfischer](https://github.com/nfischer))
- test: refactor pipe tests to AVA [\#608](https://github.com/shelljs/shelljs/pull/608) ([nfischer](https://github.com/nfischer))
- test: refactor sed tests to AVA [\#607](https://github.com/shelljs/shelljs/pull/607) ([nfischer](https://github.com/nfischer))
- test: refactor grep tests to AVA [\#606](https://github.com/shelljs/shelljs/pull/606) ([nfischer](https://github.com/nfischer))
- test: refactor global tests to AVA [\#605](https://github.com/shelljs/shelljs/pull/605) ([nfischer](https://github.com/nfischer))
- test: refactor touch tests to AVA [\#604](https://github.com/shelljs/shelljs/pull/604) ([nfischer](https://github.com/nfischer))
- test: refactor uniq tests to AVA [\#603](https://github.com/shelljs/shelljs/pull/603) ([nfischer](https://github.com/nfischer))
- test: refactor sort tests to AVA [\#602](https://github.com/shelljs/shelljs/pull/602) ([nfischer](https://github.com/nfischer))
- test: refactor tail tests to AVA [\#601](https://github.com/shelljs/shelljs/pull/601) ([nfischer](https://github.com/nfischer))
- test: refactor head tests to AVA [\#600](https://github.com/shelljs/shelljs/pull/600) ([nfischer](https://github.com/nfischer))
- test: refactor mkdir tests to AVA [\#599](https://github.com/shelljs/shelljs/pull/599) ([nfischer](https://github.com/nfischer))
- Fix: rm behavior regarding symlinks [\#598](https://github.com/shelljs/shelljs/pull/598) ([freitagbr](https://github.com/freitagbr))
- test: refactor mv tests to AVA [\#597](https://github.com/shelljs/shelljs/pull/597) ([nfischer](https://github.com/nfischer))
- Remove files related to lgtm.co [\#596](https://github.com/shelljs/shelljs/pull/596) ([freitagbr](https://github.com/freitagbr))
- Add ability to configure error from parseOptions [\#594](https://github.com/shelljs/shelljs/pull/594) ([freitagbr](https://github.com/freitagbr))
- Use Object.assign if possible [\#593](https://github.com/shelljs/shelljs/pull/593) ([freitagbr](https://github.com/freitagbr))
- Add "-n" option to echo [\#590](https://github.com/shelljs/shelljs/pull/590) ([freitagbr](https://github.com/freitagbr))
- test: refactor rm tests to AVA [\#586](https://github.com/shelljs/shelljs/pull/586) ([nfischer](https://github.com/nfischer))
- test: refactor pwd tests to AVA [\#582](https://github.com/shelljs/shelljs/pull/582) ([nfischer](https://github.com/nfischer))
- test: refactor tempdir tests to AVA [\#581](https://github.com/shelljs/shelljs/pull/581) ([nfischer](https://github.com/nfischer))
- test: refactor 'which' tests to AVA [\#580](https://github.com/shelljs/shelljs/pull/580) ([nfischer](https://github.com/nfischer))
- test: refactor plugin tests to AVA [\#579](https://github.com/shelljs/shelljs/pull/579) ([nfischer](https://github.com/nfischer))
- test: refactor toEnd tests to AVA [\#578](https://github.com/shelljs/shelljs/pull/578) ([nfischer](https://github.com/nfischer))
- test: refactor to tests to AVA [\#577](https://github.com/shelljs/shelljs/pull/577) ([nfischer](https://github.com/nfischer))
- test: refactor 'set' tests to AVA [\#576](https://github.com/shelljs/shelljs/pull/576) ([nfischer](https://github.com/nfischer))
- test: refactor echo tests to AVA [\#575](https://github.com/shelljs/shelljs/pull/575) ([nfischer](https://github.com/nfischer))
- test: refactor exec tests to AVA [\#574](https://github.com/shelljs/shelljs/pull/574) ([nfischer](https://github.com/nfischer))
- test: refactor env tests to AVA [\#573](https://github.com/shelljs/shelljs/pull/573) ([nfischer](https://github.com/nfischer))
- test: refactor dirs tests to AVA [\#572](https://github.com/shelljs/shelljs/pull/572) ([nfischer](https://github.com/nfischer))
- test: refactor config tests to AVA [\#571](https://github.com/shelljs/shelljs/pull/571) ([nfischer](https://github.com/nfischer))
- test: refactor common tests to AVA [\#570](https://github.com/shelljs/shelljs/pull/570) ([nfischer](https://github.com/nfischer))
- test: refactor chmod tests to AVA [\#569](https://github.com/shelljs/shelljs/pull/569) ([nfischer](https://github.com/nfischer))
- test: refactor cp tests to ava [\#565](https://github.com/shelljs/shelljs/pull/565) ([nfischer](https://github.com/nfischer))
- test: refactor cat tests to ava [\#564](https://github.com/shelljs/shelljs/pull/564) ([nfischer](https://github.com/nfischer))
- test: set up ava and move cd.js [\#561](https://github.com/shelljs/shelljs/pull/561) ([nfischer](https://github.com/nfischer))
- Update sed documentation regarding capture groups [\#558](https://github.com/shelljs/shelljs/pull/558) ([freitagbr](https://github.com/freitagbr))
- Add newline to output of echo [\#557](https://github.com/shelljs/shelljs/pull/557) ([freitagbr](https://github.com/freitagbr))
- fix: handle code-less errors more carefully in exec [\#554](https://github.com/shelljs/shelljs/pull/554) ([nfischer](https://github.com/nfischer))
- Add Brandon Freitag to maintainers/contributors [\#553](https://github.com/shelljs/shelljs/pull/553) ([freitagbr](https://github.com/freitagbr))
- Get pipe tests running on Windows. [\#550](https://github.com/shelljs/shelljs/pull/550) ([binki](https://github.com/binki))
- fix: maxdepth doesn't limit total number of copies [\#549](https://github.com/shelljs/shelljs/pull/549) ([nfischer](https://github.com/nfischer))
- Fix lint warning [\#543](https://github.com/shelljs/shelljs/pull/543) ([freitagbr](https://github.com/freitagbr))
- chore: remove v0.10 from Travis CI [\#540](https://github.com/shelljs/shelljs/pull/540) ([nfischer](https://github.com/nfischer))
- chore: add Node v7 for CI [\#539](https://github.com/shelljs/shelljs/pull/539) ([nfischer](https://github.com/nfischer))

## [v0.7.5](https://github.com/shelljs/shelljs/tree/v0.7.5) (2016-10-27)
[Full Changelog](https://github.com/shelljs/shelljs/compare/v0.7.4...v0.7.5)

**Closed issues:**

- Project objectives: there is some higher goal to achieve? [\#533](https://github.com/shelljs/shelljs/issues/533)
- fs.existsSync is un-deprecated [\#531](https://github.com/shelljs/shelljs/issues/531)
- Inadvertent breaking change to shell.test\(\) [\#529](https://github.com/shelljs/shelljs/issues/529)
- Add -u flag support for cp [\#526](https://github.com/shelljs/shelljs/issues/526)
- API request: allow `plugin.error\(\)` to take an options parameter [\#522](https://github.com/shelljs/shelljs/issues/522)
- FS Real Path error thrown when requiring shelljs [\#521](https://github.com/shelljs/shelljs/issues/521)
- Question: passing code via pipe? [\#520](https://github.com/shelljs/shelljs/issues/520)
- The performance in `cp` is different between `0.6.0` and `0.7.4` [\#517](https://github.com/shelljs/shelljs/issues/517)
- ShellJS in Electron package don't find ffmpeg anymore [\#516](https://github.com/shelljs/shelljs/issues/516)
- Exec issues with string option introduced in 0.7.4 [\#515](https://github.com/shelljs/shelljs/issues/515)
- \[ Feature \] SSH command [\#435](https://github.com/shelljs/shelljs/issues/435)

**Merged pull requests:**

- feat: plugin.error\(\) takes an options parameter [\#535](https://github.com/shelljs/shelljs/pull/535) ([nfischer](https://github.com/nfischer))
- Revert "refactor: replace fs.existsSync" fixes\(\#531\) [\#532](https://github.com/shelljs/shelljs/pull/532) ([gyandeeps](https://github.com/gyandeeps))
- Fix: Remove default glob from shell.test \(fixes \#529\) [\#530](https://github.com/shelljs/shelljs/pull/530) ([gyandeeps](https://github.com/gyandeeps))
- feat: cp -u option [\#527](https://github.com/shelljs/shelljs/pull/527) ([nfischer](https://github.com/nfischer))
- chore: add downloads per month on README [\#513](https://github.com/shelljs/shelljs/pull/513) ([nfischer](https://github.com/nfischer))

## [v0.7.4](https://github.com/shelljs/shelljs/tree/v0.7.4) (2016-08-26)
[Full Changelog](https://github.com/shelljs/shelljs/compare/v0.7.3...v0.7.4)

**Closed issues:**

- fix: echo -e should not print "-e" [\#510](https://github.com/shelljs/shelljs/issues/510)
- Wrong method signature in doc [\#498](https://github.com/shelljs/shelljs/issues/498)
- readFromPipe should be a function with no arguments [\#485](https://github.com/shelljs/shelljs/issues/485)
- TypeError: Cannot read property 'toString' of undefined [\#471](https://github.com/shelljs/shelljs/issues/471)

**Merged pull requests:**

- fix: echo supports -e option properly [\#511](https://github.com/shelljs/shelljs/pull/511) ([nfischer](https://github.com/nfischer))
- refactor: replace fs.existsSync [\#509](https://github.com/shelljs/shelljs/pull/509) ([nfischer](https://github.com/nfischer))
- refactor: readFromPipe\(\) requires no arguments [\#506](https://github.com/shelljs/shelljs/pull/506) ([nfischer](https://github.com/nfischer))
- chore: switch to eslint [\#504](https://github.com/shelljs/shelljs/pull/504) ([nfischer](https://github.com/nfischer))
- feat: add overWrite option for commands [\#503](https://github.com/shelljs/shelljs/pull/503) ([nfischer](https://github.com/nfischer))
- chore: update issue template [\#502](https://github.com/shelljs/shelljs/pull/502) ([nfischer](https://github.com/nfischer))
- fixed head/tail readme [\#499](https://github.com/shelljs/shelljs/pull/499) ([charlesread](https://github.com/charlesread))

## [v0.7.3](https://github.com/shelljs/shelljs/tree/v0.7.3) (2016-07-27)
[Full Changelog](https://github.com/shelljs/shelljs/compare/v0.7.2...v0.7.3)

**Closed issues:**

- expose execSync [\#494](https://github.com/shelljs/shelljs/issues/494)
- Add a way to create commands that can receive from a pipe without being standalone commands [\#487](https://github.com/shelljs/shelljs/issues/487)
- cp -r breaks when the directory contains a softlink [\#193](https://github.com/shelljs/shelljs/issues/193)
- Redirect output to file fails [\#60](https://github.com/shelljs/shelljs/issues/60)
- We need sed -n ? [\#38](https://github.com/shelljs/shelljs/issues/38)

**Merged pull requests:**

- refactor: allow pipeOnly commands \(methods on ShellStrings\) [\#493](https://github.com/shelljs/shelljs/pull/493) ([nfischer](https://github.com/nfischer))
- refactor: glob by default for commands [\#492](https://github.com/shelljs/shelljs/pull/492) ([nfischer](https://github.com/nfischer))
- refactor: switch from notUnix to unix in wrap\(\) [\#491](https://github.com/shelljs/shelljs/pull/491) ([nfischer](https://github.com/nfischer))
- refactor: switch common.extend\(\) to Object.assign ponyfill [\#490](https://github.com/shelljs/shelljs/pull/490) ([nfischer](https://github.com/nfischer))
- fix: conflicting options now properly override each other [\#489](https://github.com/shelljs/shelljs/pull/489) ([nfischer](https://github.com/nfischer))
- refactor: expose plugin utils & add initial tests [\#484](https://github.com/shelljs/shelljs/pull/484) ([nfischer](https://github.com/nfischer))

## [v0.7.2](https://github.com/shelljs/shelljs/tree/v0.7.2) (2016-07-25)
[Full Changelog](https://github.com/shelljs/shelljs/compare/v0.7.1...v0.7.2)

**Closed issues:**

- shelljs should not kill process if node call throws exception [\#473](https://github.com/shelljs/shelljs/issues/473)
- `cp` work incorrectly when folder name contains '@' [\#463](https://github.com/shelljs/shelljs/issues/463)
- Something went wrong [\#158](https://github.com/shelljs/shelljs/issues/158)

**Merged pull requests:**

- fix: resolve a cylcic-dependency problem [\#482](https://github.com/shelljs/shelljs/pull/482) ([nfischer](https://github.com/nfischer))
- refactor: add wrapOutput option to auto-ShellString-ify command output [\#481](https://github.com/shelljs/shelljs/pull/481) ([nfischer](https://github.com/nfischer))
- refactor: move option parsing into common.wrap\(\) [\#479](https://github.com/shelljs/shelljs/pull/479) ([nfischer](https://github.com/nfischer))
- refactor: hook new uniq\(\) command using new format [\#478](https://github.com/shelljs/shelljs/pull/478) ([nfischer](https://github.com/nfischer))
- Fix mkdir malformed path [\#477](https://github.com/shelljs/shelljs/pull/477) ([nfischer](https://github.com/nfischer))
- fix: mkdir for invalid perms does not kill process [\#474](https://github.com/shelljs/shelljs/pull/474) ([nfischer](https://github.com/nfischer))
- feat\(command\): new command: uniq\(\) [\#453](https://github.com/shelljs/shelljs/pull/453) ([joshi-sh](https://github.com/joshi-sh))

## [v0.7.1](https://github.com/shelljs/shelljs/tree/v0.7.1) (2016-07-22)
[Full Changelog](https://github.com/shelljs/shelljs/compare/v0.7.0...v0.7.1)

**Closed issues:**

- cp -n doesn't work correctly [\#465](https://github.com/shelljs/shelljs/issues/465)
- how can i run sudo apt-get install xtodotool by your plugin? [\#448](https://github.com/shelljs/shelljs/issues/448)
- shell.js grep: internal error,  Invalid regular expression [\#447](https://github.com/shelljs/shelljs/issues/447)
- Stdout is empty on Git log command [\#439](https://github.com/shelljs/shelljs/issues/439)
- Cannot read toString of null when using execSync [\#415](https://github.com/shelljs/shelljs/issues/415)
- cp -R dir/ target fails to copy hidden files in dir [\#140](https://github.com/shelljs/shelljs/issues/140)
- \#mv Won't Work Across Disks [\#1](https://github.com/shelljs/shelljs/issues/1)

**Merged pull requests:**

- refactor: commands now register themselves [\#475](https://github.com/shelljs/shelljs/pull/475) ([nfischer](https://github.com/nfischer))
- chore: switch to shields.io, and add npm badge [\#470](https://github.com/shelljs/shelljs/pull/470) ([nfischer](https://github.com/nfischer))
- fix\(cp\): -n option no longer raises error [\#466](https://github.com/shelljs/shelljs/pull/466) ([nfischer](https://github.com/nfischer))
- refactor: expose pipe-ability to command configuration [\#464](https://github.com/shelljs/shelljs/pull/464) ([nfischer](https://github.com/nfischer))
- fix\(mv\): works across partitions [\#461](https://github.com/shelljs/shelljs/pull/461) ([nfischer](https://github.com/nfischer))
- chore: switch to shelljs-changelog [\#460](https://github.com/shelljs/shelljs/pull/460) ([nfischer](https://github.com/nfischer))
- chore: update release process [\#459](https://github.com/shelljs/shelljs/pull/459) ([nfischer](https://github.com/nfischer))
- chore: revert depreciate shelljs/make \(\#431\) [\#458](https://github.com/shelljs/shelljs/pull/458) ([zephraph](https://github.com/zephraph))
- chore: clarify message for when docs are not generated [\#457](https://github.com/shelljs/shelljs/pull/457) ([nfischer](https://github.com/nfischer))
- chore\(gendocs\): add `npm run gendocs` command [\#455](https://github.com/shelljs/shelljs/pull/455) ([nfischer](https://github.com/nfischer))
- chore: update jshint and move it to an npm script [\#454](https://github.com/shelljs/shelljs/pull/454) ([nfischer](https://github.com/nfischer))
- test\(ls\): add case for trailing slash on dir name [\#450](https://github.com/shelljs/shelljs/pull/450) ([nfischer](https://github.com/nfischer))
- docs\(exec\): explicitly mention the `shell` option [\#449](https://github.com/shelljs/shelljs/pull/449) ([nfischer](https://github.com/nfischer))
- chore: setup changelog [\#443](https://github.com/shelljs/shelljs/pull/443) ([levithomason](https://github.com/levithomason))
- docs: comment code better to help contributors [\#437](https://github.com/shelljs/shelljs/pull/437) ([nfischer](https://github.com/nfischer))
- chore\(CI\): update appveyor [\#436](https://github.com/shelljs/shelljs/pull/436) ([nfischer](https://github.com/nfischer))
- chore: test against node v6 [\#433](https://github.com/shelljs/shelljs/pull/433) ([nfischer](https://github.com/nfischer))
- docs: warn that README contains newest features [\#410](https://github.com/shelljs/shelljs/pull/410) ([nfischer](https://github.com/nfischer))

## [v0.7.0](https://github.com/shelljs/shelljs/tree/v0.7.0) (2016-04-25)
[Full Changelog](https://github.com/shelljs/shelljs/compare/v0.6.0...v0.7.0)

**Closed issues:**

- exec\('nohup node some.js &'\) [\#426](https://github.com/shelljs/shelljs/issues/426)
- shelljs Breaks SemVer for Alpha and Pre-Release Versions [\#390](https://github.com/shelljs/shelljs/issues/390)
- Copy not accepting source end with wildcards \* when using -r on v0.6.0 [\#389](https://github.com/shelljs/shelljs/issues/389)
- Support globbing in `shjs` [\#388](https://github.com/shelljs/shelljs/issues/388)
- Refactor more commands to return ShellString [\#373](https://github.com/shelljs/shelljs/issues/373)
- ln\('-sf', './', '\<destination\>'\) is not linking the right folder [\#363](https://github.com/shelljs/shelljs/issues/363)
- v0.6.0 - shell.cp\('r', '/foo/\*, '/bar'\) fails with /foo/\* no such file or directory [\#342](https://github.com/shelljs/shelljs/issues/342)
- Add documentup as a webhook [\#327](https://github.com/shelljs/shelljs/issues/327)
- Dir glob breaks when in the middle of path [\#245](https://github.com/shelljs/shelljs/issues/245)
- could you switch off wiki page? [\#233](https://github.com/shelljs/shelljs/issues/233)
- ls globbing does not behave like shell, consider using glob.sync [\#225](https://github.com/shelljs/shelljs/issues/225)
- Cannot run shell.exec\('heroku config:push'\) -- just hangs  [\#218](https://github.com/shelljs/shelljs/issues/218)
- `cp` does not overwrite files by default [\#210](https://github.com/shelljs/shelljs/issues/210)
- exec failed to return [\#208](https://github.com/shelljs/shelljs/issues/208)
- CLI Version [\#202](https://github.com/shelljs/shelljs/issues/202)
- Bracket expansion not working [\#176](https://github.com/shelljs/shelljs/issues/176)
- "exec" causes LiveScript interpreter \(lsc\) to hang [\#160](https://github.com/shelljs/shelljs/issues/160)
- Don't modify string prototype [\#159](https://github.com/shelljs/shelljs/issues/159)
- `exec\(...\).to\(file\)` should work [\#154](https://github.com/shelljs/shelljs/issues/154)
- Can't install shelljs locally instead of globally [\#136](https://github.com/shelljs/shelljs/issues/136)
- shelljs and node 0.10.28 [\#125](https://github.com/shelljs/shelljs/issues/125)
- Use case for global installed shelljs [\#123](https://github.com/shelljs/shelljs/issues/123)
- Only get stdout from `exec` [\#92](https://github.com/shelljs/shelljs/issues/92)
- What about other commands? [\#90](https://github.com/shelljs/shelljs/issues/90)
- Flesh out example of exit\(\) [\#73](https://github.com/shelljs/shelljs/issues/73)
- exec doesn't work with qualified paths on windows [\#41](https://github.com/shelljs/shelljs/issues/41)
- exec does not working in mingw bash in windows [\#17](https://github.com/shelljs/shelljs/issues/17)
- Add support for cp -P option [\#413](https://github.com/shelljs/shelljs/issues/413)
- cp -L: Incorrect behavior for symlinks to regular files [\#407](https://github.com/shelljs/shelljs/issues/407)
- Edit the docs to emphasize ShellStrings and Pipes [\#398](https://github.com/shelljs/shelljs/issues/398)
- Error message isn't always printed [\#372](https://github.com/shelljs/shelljs/issues/372)
- Standardize command output [\#356](https://github.com/shelljs/shelljs/issues/356)
- exec\(\) doesn't clean up all temp files [\#353](https://github.com/shelljs/shelljs/issues/353)
- Document that exec\(\) options don't work on early versions of node [\#350](https://github.com/shelljs/shelljs/issues/350)
- Add -f option to set\(\) [\#344](https://github.com/shelljs/shelljs/issues/344)
- Glob commands by default [\#343](https://github.com/shelljs/shelljs/issues/343)
- rm -rf incorrect behaviour [\#332](https://github.com/shelljs/shelljs/issues/332)
- Switch `exec\(\)` to use bash by default [\#281](https://github.com/shelljs/shelljs/issues/281)
- pipe to proc [\#148](https://github.com/shelljs/shelljs/issues/148)
- shell builtin [\#138](https://github.com/shelljs/shelljs/issues/138)
- add timeout option for exec [\#132](https://github.com/shelljs/shelljs/issues/132)
- shelljs cp handling symlinks badly [\#69](https://github.com/shelljs/shelljs/issues/69)

**Merged pull requests:**

- chore: add "Team" section to README [\#423](https://github.com/shelljs/shelljs/pull/423) ([nfischer](https://github.com/nfischer))
- Contributing guidelines [\#422](https://github.com/shelljs/shelljs/pull/422) ([nfischer](https://github.com/nfischer))
- feat\(glob\): expose config.globOptions. [\#400](https://github.com/shelljs/shelljs/pull/400) ([nfischer](https://github.com/nfischer))
- Add shelljs as a keyword in package.json [\#393](https://github.com/shelljs/shelljs/pull/393) ([nfischer](https://github.com/nfischer))
- docs: add link to wiki page [\#392](https://github.com/shelljs/shelljs/pull/392) ([nfischer](https://github.com/nfischer))
- refactor\(cd\): use process.env.OLDPWD to store previous dir [\#383](https://github.com/shelljs/shelljs/pull/383) ([nfischer](https://github.com/nfischer))
- chore\(appveyor\): add in node 4 for appveyor [\#381](https://github.com/shelljs/shelljs/pull/381) ([nfischer](https://github.com/nfischer))
- Add Cash cross-reference [\#375](https://github.com/shelljs/shelljs/pull/375) ([dthree](https://github.com/dthree))
- Ignore gitattributes from npm package [\#361](https://github.com/shelljs/shelljs/pull/361) ([nfischer](https://github.com/nfischer))
- Consistently use LF line endings [\#355](https://github.com/shelljs/shelljs/pull/355) ([TimothyGu](https://github.com/TimothyGu))
- Release v0.7.0 [\#429](https://github.com/shelljs/shelljs/pull/429) ([nfischer](https://github.com/nfischer))
- fix: null is no longer confused for an object [\#428](https://github.com/shelljs/shelljs/pull/428) ([nfischer](https://github.com/nfischer))
- fix\(ls\): no trailing newline for empty directories [\#425](https://github.com/shelljs/shelljs/pull/425) ([nfischer](https://github.com/nfischer))
- feat\(cp\): -P option, plus better handling of symlinks [\#421](https://github.com/shelljs/shelljs/pull/421) ([nfischer](https://github.com/nfischer))
- docs\(exec\): fix docs about exec return type [\#419](https://github.com/shelljs/shelljs/pull/419) ([nfischer](https://github.com/nfischer))
- docs\(error\): deprecate relying on string value [\#418](https://github.com/shelljs/shelljs/pull/418) ([nfischer](https://github.com/nfischer))
- fix: error message now printed for fatal failures [\#417](https://github.com/shelljs/shelljs/pull/417) ([nfischer](https://github.com/nfischer))
- issue-407: Add regular files unit tests and fix symlink copy behavior [\#409](https://github.com/shelljs/shelljs/pull/409) ([charlesverge](https://github.com/charlesverge))
- refactor\(rm\): Remove duplicate code [\#408](https://github.com/shelljs/shelljs/pull/408) ([nfischer](https://github.com/nfischer))
- docs: wildcards for all commands, other docs cleanups [\#404](https://github.com/shelljs/shelljs/pull/404) ([nfischer](https://github.com/nfischer))
- test\(rm\): add tests to prevent a future regression [\#403](https://github.com/shelljs/shelljs/pull/403) ([nfischer](https://github.com/nfischer))
- refactor\(string\): modify string protoype, but only for shelljs/global [\#401](https://github.com/shelljs/shelljs/pull/401) ([nfischer](https://github.com/nfischer))
- feat: adding error codes to ShellJS [\#394](https://github.com/shelljs/shelljs/pull/394) ([nfischer](https://github.com/nfischer))
- feature: use rechoir [\#384](https://github.com/shelljs/shelljs/pull/384) ([nfischer](https://github.com/nfischer))
- refactor\(cp\): clean up code and fix \#376 [\#380](https://github.com/shelljs/shelljs/pull/380) ([nfischer](https://github.com/nfischer))
- New commands: sort\(\), head\(\), and tail\(\) [\#379](https://github.com/shelljs/shelljs/pull/379) ([nfischer](https://github.com/nfischer))
- Add unit tests to prevent regression \(see \#376\) [\#378](https://github.com/shelljs/shelljs/pull/378) ([nfischer](https://github.com/nfischer))
- feat\(pipe\): add support for pipes between commands [\#370](https://github.com/shelljs/shelljs/pull/370) ([nfischer](https://github.com/nfischer))
- refactor\(ls\): greatly simplify ls implimentation [\#369](https://github.com/shelljs/shelljs/pull/369) ([ariporad](https://github.com/ariporad))
- chore: drop node v0.10 support [\#368](https://github.com/shelljs/shelljs/pull/368) ([ariporad](https://github.com/ariporad))
- perf\(cd\): only run `stat` once [\#367](https://github.com/shelljs/shelljs/pull/367) ([ariporad](https://github.com/ariporad))
- fix\(exec\): properly handles paths with spaces and quotes [\#365](https://github.com/shelljs/shelljs/pull/365) ([nfischer](https://github.com/nfischer))
- test\(ln\): add tests for linking to cwd [\#364](https://github.com/shelljs/shelljs/pull/364) ([nfischer](https://github.com/nfischer))
- fix\(verbose\): verbose-style logging is consistent [\#362](https://github.com/shelljs/shelljs/pull/362) ([nfischer](https://github.com/nfischer))
- Refactor shellstring [\#360](https://github.com/shelljs/shelljs/pull/360) ([nfischer](https://github.com/nfischer))
- feat\(glob\): use glob module for globbing [\#359](https://github.com/shelljs/shelljs/pull/359) ([nfischer](https://github.com/nfischer))
- feat\(set\): add -f option to disable globbing [\#358](https://github.com/shelljs/shelljs/pull/358) ([nfischer](https://github.com/nfischer))
- config.fatal now throws an exception [\#357](https://github.com/shelljs/shelljs/pull/357) ([jrmclaurin](https://github.com/jrmclaurin))
- fix\(exec\): temp files are now cleaned up [\#354](https://github.com/shelljs/shelljs/pull/354) ([nfischer](https://github.com/nfischer))
- feat\(glob\): glob support for \(almost\) all commands [\#352](https://github.com/shelljs/shelljs/pull/352) ([nfischer](https://github.com/nfischer))
- feat\(grep\): add -l option [\#349](https://github.com/shelljs/shelljs/pull/349) ([nfischer](https://github.com/nfischer))
- fix\(exec\): now actually supports shell option [\#348](https://github.com/shelljs/shelljs/pull/348) ([nfischer](https://github.com/nfischer))
- feat\(touch\): supports multiple files [\#346](https://github.com/shelljs/shelljs/pull/346) ([nfischer](https://github.com/nfischer))

## [v0.6.0](https://github.com/shelljs/shelljs/tree/v0.6.0) (2016-02-05)
[Full Changelog](https://github.com/shelljs/shelljs/compare/v0.5.3...v0.6.0)

**Closed issues:**

- option not recognized [\#334](https://github.com/shelljs/shelljs/issues/334)
- Feature request: Metadata with `ls` [\#323](https://github.com/shelljs/shelljs/issues/323)
- Gen-docs is broken [\#309](https://github.com/shelljs/shelljs/issues/309)
- `link -s` is broken for files on Windows [\#301](https://github.com/shelljs/shelljs/issues/301)
- Shelljs quits unexpectedly: [\#300](https://github.com/shelljs/shelljs/issues/300)
- Failing tests on Windows [\#296](https://github.com/shelljs/shelljs/issues/296)
- run-tests.js is broken for cmd.exe [\#294](https://github.com/shelljs/shelljs/issues/294)
- Support echo-ing environment variables [\#291](https://github.com/shelljs/shelljs/issues/291)
- Add Windows CI [\#287](https://github.com/shelljs/shelljs/issues/287)
- Add tests for the shjs utility [\#280](https://github.com/shelljs/shelljs/issues/280)
- Allow shjs utility to infer the extension for "filename." [\#278](https://github.com/shelljs/shelljs/issues/278)
- Ability to read the stdout buffer line-by-line [\#277](https://github.com/shelljs/shelljs/issues/277)
- Poor output for commands with multiple errors [\#267](https://github.com/shelljs/shelljs/issues/267)
- Travis ci build status says "unknown" [\#266](https://github.com/shelljs/shelljs/issues/266)
- wild card characters in filename not working as expected [\#262](https://github.com/shelljs/shelljs/issues/262)
- shell.exec - read internal variable [\#260](https://github.com/shelljs/shelljs/issues/260)
- cp and rename directory with -r doesn't match unix behavior [\#256](https://github.com/shelljs/shelljs/issues/256)
- console.log.apply throwing TypeError: Illegal Invocation [\#255](https://github.com/shelljs/shelljs/issues/255)
- How to exit on first error [\#253](https://github.com/shelljs/shelljs/issues/253)
- why not support set 'cwd'  when invoke execAsync ? [\#250](https://github.com/shelljs/shelljs/issues/250)
- Not possible to check the failure of cd? [\#247](https://github.com/shelljs/shelljs/issues/247)
- By default shelljs runs command in root  [\#246](https://github.com/shelljs/shelljs/issues/246)
- /usr/bin/env: node: No such file or directory [\#243](https://github.com/shelljs/shelljs/issues/243)
- "Which" command not working properly on Windows Platform. [\#238](https://github.com/shelljs/shelljs/issues/238)
- Arguments [\#237](https://github.com/shelljs/shelljs/issues/237)
- sed\(\) should accept multiple file arguments [\#231](https://github.com/shelljs/shelljs/issues/231)
- shelljs.exec\('aaa && bbb'\) blocks [\#229](https://github.com/shelljs/shelljs/issues/229)
- Consider creating a GitHub Organization with more maintainers [\#223](https://github.com/shelljs/shelljs/issues/223)
- \[idea\] Add chmodr function. [\#219](https://github.com/shelljs/shelljs/issues/219)
- Execute a file [\#211](https://github.com/shelljs/shelljs/issues/211)
- Where is standard error going to? [\#209](https://github.com/shelljs/shelljs/issues/209)
- boolean return value for string.to\(\) [\#205](https://github.com/shelljs/shelljs/issues/205)
- `common.error` doesn't throw [\#199](https://github.com/shelljs/shelljs/issues/199)
- Problems with exec \(sync\) on 0.12/io.js [\#197](https://github.com/shelljs/shelljs/issues/197)
- cp --update flag [\#172](https://github.com/shelljs/shelljs/issues/172)
- Is there a way to suppress pushd/popd output? [\#171](https://github.com/shelljs/shelljs/issues/171)
- Cannot recursively list all \*.js files [\#162](https://github.com/shelljs/shelljs/issues/162)
- exec\(\) breaks if executed in a deleted directory [\#157](https://github.com/shelljs/shelljs/issues/157)
- shjs command always exits with zero code [\#133](https://github.com/shelljs/shelljs/issues/133)
- touch command [\#122](https://github.com/shelljs/shelljs/issues/122)
- Symbolic links are broken! [\#100](https://github.com/shelljs/shelljs/issues/100)
- interpret `--` as stdin [\#55](https://github.com/shelljs/shelljs/issues/55)
- Error ENOTEMPTY when deleting a directory recursively. [\#49](https://github.com/shelljs/shelljs/issues/49)
- Cross-platform way to add to PATH [\#32](https://github.com/shelljs/shelljs/issues/32)
- `mv` fails on block, character, fifo [\#25](https://github.com/shelljs/shelljs/issues/25)
- ls -l [\#22](https://github.com/shelljs/shelljs/issues/22)

**Merged pull requests:**

- feat\(set\): add new set\(\) command [\#329](https://github.com/shelljs/shelljs/pull/329) ([nfischer](https://github.com/nfischer))
- Fix symlinking on Windows [\#322](https://github.com/shelljs/shelljs/pull/322) ([BYK](https://github.com/BYK))
- Rewrite .gitignore to be more comprehensive [\#321](https://github.com/shelljs/shelljs/pull/321) ([BYK](https://github.com/BYK))
- chore\(gitter/travis\): add gitter webhook to travis [\#313](https://github.com/shelljs/shelljs/pull/313) ([ariporad](https://github.com/ariporad))
- chore\(LGTM\): add LGTM config files [\#312](https://github.com/shelljs/shelljs/pull/312) ([ariporad](https://github.com/ariporad))
- feat\(ls\): add -d flag to ls\(\) [\#311](https://github.com/shelljs/shelljs/pull/311) ([nfischer](https://github.com/nfischer))
- fix\(gen-docs\): fix issue where docs are generated wrong [\#310](https://github.com/shelljs/shelljs/pull/310) ([nfischer](https://github.com/nfischer))
- chore\(package\): remove v0.8 from engines list [\#308](https://github.com/shelljs/shelljs/pull/308) ([nfischer](https://github.com/nfischer))
- travis: Mark as not using `sudo` and do not test 0.11 [\#307](https://github.com/shelljs/shelljs/pull/307) ([TimothyGu](https://github.com/TimothyGu))
- fix: jshint works on Windows [\#295](https://github.com/shelljs/shelljs/pull/295) ([nfischer](https://github.com/nfischer))
- feat: add tilde expansion to expand\(\) [\#293](https://github.com/shelljs/shelljs/pull/293) ([nfischer](https://github.com/nfischer))
- style: make docs more consistent [\#292](https://github.com/shelljs/shelljs/pull/292) ([nfischer](https://github.com/nfischer))
- update `exec` docs to match implemented behaviour [\#289](https://github.com/shelljs/shelljs/pull/289) ([vise890](https://github.com/vise890))
- chore: update github URL in package.json [\#288](https://github.com/shelljs/shelljs/pull/288) ([nfischer](https://github.com/nfischer))
- docs\(spelling\): fix typo in source comment [\#285](https://github.com/shelljs/shelljs/pull/285) ([nfischer](https://github.com/nfischer))
- chore\(travis\): add OS X to Travis CI [\#283](https://github.com/shelljs/shelljs/pull/283) ([nfischer](https://github.com/nfischer))
- Don't do `console.log.apply\(this, ...\)`. [\#274](https://github.com/shelljs/shelljs/pull/274) ([ariporad](https://github.com/ariporad))
- Implementing cd\('-'\) to behave like Bash's "cd -" [\#273](https://github.com/shelljs/shelljs/pull/273) ([nfischer](https://github.com/nfischer))
- Fix cp to match unix behavior [\#271](https://github.com/shelljs/shelljs/pull/271) ([freitagbr](https://github.com/freitagbr))
- Commands that have multiple errors now produce cleaner log output [\#268](https://github.com/shelljs/shelljs/pull/268) ([nfischer](https://github.com/nfischer))
- Support exit code in shjs. [\#252](https://github.com/shelljs/shelljs/pull/252) ([bryce-gibson](https://github.com/bryce-gibson))
- add touch\(1\) [\#249](https://github.com/shelljs/shelljs/pull/249) ([blockloop](https://github.com/blockloop))
- Fix `os.tmpdir` bug [\#240](https://github.com/shelljs/shelljs/pull/240) ([BYK](https://github.com/BYK))
- Make sure Which\(\) on Windows platform always return the command with … [\#239](https://github.com/shelljs/shelljs/pull/239) ([TingluoHuang](https://github.com/TingluoHuang))
- Add target node.js \(iojs v1, v2, v3\) [\#230](https://github.com/shelljs/shelljs/pull/230) ([sanemat](https://github.com/sanemat))
- feat-multisymbolic + Support for directory entry \(capital X in chmod terms\) [\#228](https://github.com/shelljs/shelljs/pull/228) ([rezonant](https://github.com/rezonant))
- Fixes an issue with multi-symbolic mode specification \(ie a-rwx,u+rw\) [\#227](https://github.com/shelljs/shelljs/pull/227) ([rezonant](https://github.com/rezonant))
- Memoized the result of target invocation [\#216](https://github.com/shelljs/shelljs/pull/216) ([rizowski](https://github.com/rizowski))
- remove empty for loop and leaked i var [\#166](https://github.com/shelljs/shelljs/pull/166) ([ratbeard](https://github.com/ratbeard))
- Wrap script name in double quotes [\#135](https://github.com/shelljs/shelljs/pull/135) ([ndelitski](https://github.com/ndelitski))
- Fixed coffeescript syntax in top example [\#99](https://github.com/shelljs/shelljs/pull/99) ([maxnordlund](https://github.com/maxnordlund))
- fix\(touch\): enhance parseOptions and fix touch's -r flag [\#341](https://github.com/shelljs/shelljs/pull/341) ([nfischer](https://github.com/nfischer))
- chore\(.npmignore\): update npmignore [\#339](https://github.com/shelljs/shelljs/pull/339) ([ariporad](https://github.com/ariporad))
- Release v0.6.0 [\#338](https://github.com/shelljs/shelljs/pull/338) ([ariporad](https://github.com/ariporad))
- docs\(README\): remove coffeescript from README [\#337](https://github.com/shelljs/shelljs/pull/337) ([ariporad](https://github.com/ariporad))
- fix\(cp\): add -n option, make -f default behavior [\#336](https://github.com/shelljs/shelljs/pull/336) ([nfischer](https://github.com/nfischer))
- feat\(exec\): allow all exec options to pass through [\#335](https://github.com/shelljs/shelljs/pull/335) ([nfischer](https://github.com/nfischer))
- fix\(mv\): add -n option, make -f default behavior [\#328](https://github.com/shelljs/shelljs/pull/328) ([nfischer](https://github.com/nfischer))
- fix\(cat\): make behavior more like unix [\#326](https://github.com/shelljs/shelljs/pull/326) ([nfischer](https://github.com/nfischer))
- feat\(ls\): add -l  option [\#324](https://github.com/shelljs/shelljs/pull/324) ([nfischer](https://github.com/nfischer))
- style\(test/which\): make test/which.js conform to the style guidelines [\#320](https://github.com/shelljs/shelljs/pull/320) ([ariporad](https://github.com/ariporad))
- chore\(appveyor\): add badge [\#316](https://github.com/shelljs/shelljs/pull/316) ([nfischer](https://github.com/nfischer))
- fix\(windows\): fix shjs commands for windows [\#315](https://github.com/shelljs/shelljs/pull/315) ([nfischer](https://github.com/nfischer))
- feat\(sed\): support multiple file names [\#314](https://github.com/shelljs/shelljs/pull/314) ([nfischer](https://github.com/nfischer))
- feat\(cd\): cd\(\) \(no args\) changes to home directory [\#306](https://github.com/shelljs/shelljs/pull/306) ([nfischer](https://github.com/nfischer))
- test\(shjs\): add tests for shjs [\#304](https://github.com/shelljs/shelljs/pull/304) ([ariporad](https://github.com/ariporad))
- fix: regexes are more consistent with sed and grep [\#303](https://github.com/shelljs/shelljs/pull/303) ([nfischer](https://github.com/nfischer))
- Add appveyor.yml config file [\#299](https://github.com/shelljs/shelljs/pull/299) ([nfischer](https://github.com/nfischer))
- Fix tests on Windows [\#297](https://github.com/shelljs/shelljs/pull/297) ([BYK](https://github.com/BYK))
- Search PATHEXT instead of 3 hardcoded values [\#290](https://github.com/shelljs/shelljs/pull/290) ([isiahmeadows](https://github.com/isiahmeadows))
- Fix relative symlinks [\#282](https://github.com/shelljs/shelljs/pull/282) ([freitagbr](https://github.com/freitagbr))
- Make to and toEnd chainable [\#276](https://github.com/shelljs/shelljs/pull/276) ([TimothyGu](https://github.com/TimothyGu))

## [v0.5.3](https://github.com/shelljs/shelljs/tree/v0.5.3) (2015-08-11)
[Full Changelog](https://github.com/shelljs/shelljs/compare/v0.5.2...v0.5.3)

**Merged pull requests:**

- Manually closing streams [\#222](https://github.com/shelljs/shelljs/pull/222) ([JulianLaval](https://github.com/JulianLaval))

## [v0.5.2](https://github.com/shelljs/shelljs/tree/v0.5.2) (2015-08-10)
[Full Changelog](https://github.com/shelljs/shelljs/compare/v0.5.1...v0.5.2)

**Closed issues:**

- Cannot run shell.exec [\#217](https://github.com/shelljs/shelljs/issues/217)
- write after end: internal error [\#206](https://github.com/shelljs/shelljs/issues/206)

**Merged pull requests:**

- Update README.md [\#221](https://github.com/shelljs/shelljs/pull/221) ([giosh94mhz](https://github.com/giosh94mhz))
- prevent internal error: write after end [\#214](https://github.com/shelljs/shelljs/pull/214) ([charlierudolph](https://github.com/charlierudolph))

## [v0.5.1](https://github.com/shelljs/shelljs/tree/v0.5.1) (2015-06-05)
[Full Changelog](https://github.com/shelljs/shelljs/compare/v0.5.0...v0.5.1)

**Closed issues:**

- cd into home directory [\#9](https://github.com/shelljs/shelljs/issues/9)

**Merged pull requests:**

- Fix issue \#49: Retry rmdirSync on Windows for up to 1 second if files still exist. [\#179](https://github.com/shelljs/shelljs/pull/179) ([andreialecu](https://github.com/andreialecu))

## [v0.5.0](https://github.com/shelljs/shelljs/tree/v0.5.0) (2015-05-19)
[Full Changelog](https://github.com/shelljs/shelljs/compare/v0.3.0...v0.5.0)

**Closed issues:**

- Enter text to prompt [\#203](https://github.com/shelljs/shelljs/issues/203)
- Find which shell is being used [\#195](https://github.com/shelljs/shelljs/issues/195)
- Pass command line params to the make tool [\#188](https://github.com/shelljs/shelljs/issues/188)
- Is it possible to call exec with a command containing new lines ? [\#177](https://github.com/shelljs/shelljs/issues/177)
- The installation would break on Windows 7 [\#161](https://github.com/shelljs/shelljs/issues/161)
- Q.ninvoke\(\) returns undefined [\#153](https://github.com/shelljs/shelljs/issues/153)
- installed shelljs on osx but reported error: npm ERR! 404 '%5B-g%5D' is not in the npm registry. [\#124](https://github.com/shelljs/shelljs/issues/124)
- "ln" not found \(OS X\) [\#106](https://github.com/shelljs/shelljs/issues/106)
- Using shelljs in a CLI app. [\#91](https://github.com/shelljs/shelljs/issues/91)

**Merged pull requests:**

- Breaking: Allow -- as args separators \(fixes \#188\) [\#207](https://github.com/shelljs/shelljs/pull/207) ([nzakas](https://github.com/nzakas))
- Update .travis.yml [\#190](https://github.com/shelljs/shelljs/pull/190) ([arturadib](https://github.com/arturadib))
- Use new child\_process.execSync instead of busywaiting [\#189](https://github.com/shelljs/shelljs/pull/189) ([madd512](https://github.com/madd512))
- Update README.md: explains how to access "config" [\#145](https://github.com/shelljs/shelljs/pull/145) ([kerphi](https://github.com/kerphi))
- Fix to set state.error before throw the exception [\#120](https://github.com/shelljs/shelljs/pull/120) ([abdul-martinez](https://github.com/abdul-martinez))
- Add -l and -s support to grep. [\#116](https://github.com/shelljs/shelljs/pull/116) ([idearat](https://github.com/idearat))

## [v0.3.0](https://github.com/shelljs/shelljs/tree/v0.3.0) (2014-05-08)
[Full Changelog](https://github.com/shelljs/shelljs/compare/v0.2.6...v0.3.0)

**Closed issues:**

- grep\(\) should fully support globing [\#118](https://github.com/shelljs/shelljs/issues/118)
- sed\(\) could support replacement function [\#115](https://github.com/shelljs/shelljs/issues/115)
- How would you close an exec process that runs indefinitely? [\#113](https://github.com/shelljs/shelljs/issues/113)
- listen for intermittent output of a long-running child process [\#111](https://github.com/shelljs/shelljs/issues/111)
-  Cannot find module 'shelljs' after installing shelljs with npm [\#109](https://github.com/shelljs/shelljs/issues/109)
- Massive CPU usage on exec\(\) windows [\#108](https://github.com/shelljs/shelljs/issues/108)
- cp skipping dot files? [\#79](https://github.com/shelljs/shelljs/issues/79)
- $variables in exec\(\) aren't handled correctly [\#11](https://github.com/shelljs/shelljs/issues/11)
- debug flag that prints commands instead of executing [\#8](https://github.com/shelljs/shelljs/issues/8)

**Merged pull requests:**

- grep\(\) support for globing, fixes \#118 [\#119](https://github.com/shelljs/shelljs/pull/119) ([utensil](https://github.com/utensil))
- make sed\(\) support replacement function, fixes \#115 [\#117](https://github.com/shelljs/shelljs/pull/117) ([utensil](https://github.com/utensil))
- which\(\) should only find files, not directories [\#110](https://github.com/shelljs/shelljs/pull/110) ([panrafal](https://github.com/panrafal))
- Added the New BSD license to the package.json. [\#105](https://github.com/shelljs/shelljs/pull/105) ([keskival](https://github.com/keskival))
- Added win32 support to ln [\#104](https://github.com/shelljs/shelljs/pull/104) ([jamon](https://github.com/jamon))
- Fix ln using bad paths when given abspaths. [\#89](https://github.com/shelljs/shelljs/pull/89) ([Schoonology](https://github.com/Schoonology))
- Add ln support, including both -s and -f options. [\#88](https://github.com/shelljs/shelljs/pull/88) ([Schoonology](https://github.com/Schoonology))
- add support for symlinking \(junctions\) on win32 [\#87](https://github.com/shelljs/shelljs/pull/87) ([jamon](https://github.com/jamon))

## [v0.2.6](https://github.com/shelljs/shelljs/tree/v0.2.6) (2013-09-22)
[Full Changelog](https://github.com/shelljs/shelljs/compare/v0.2.5...v0.2.6)

**Closed issues:**

- Versions 0.2.4 and 0.2.3 keep throwing strange errors [\#82](https://github.com/shelljs/shelljs/issues/82)
- Add global pollution tests [\#33](https://github.com/shelljs/shelljs/issues/33)

## [v0.2.5](https://github.com/shelljs/shelljs/tree/v0.2.5) (2013-09-11)
[Full Changelog](https://github.com/shelljs/shelljs/compare/v0.2.4...v0.2.5)

**Closed issues:**

- shelljs.exec stalls on Red Hat when script is invoked with 'sudo -u username' [\#72](https://github.com/shelljs/shelljs/issues/72)

## [v0.2.4](https://github.com/shelljs/shelljs/tree/v0.2.4) (2013-09-11)
[Full Changelog](https://github.com/shelljs/shelljs/compare/v0.2.3...v0.2.4)

## [v0.2.3](https://github.com/shelljs/shelljs/tree/v0.2.3) (2013-09-09)
[Full Changelog](https://github.com/shelljs/shelljs/compare/v0.2.2...v0.2.3)

**Merged pull requests:**

- Make shell.exec\(\) treat process error return codes as shelljs errors [\#80](https://github.com/shelljs/shelljs/pull/80) ([nilsbunger](https://github.com/nilsbunger))

## [v0.2.2](https://github.com/shelljs/shelljs/tree/v0.2.2) (2013-09-02)
[Full Changelog](https://github.com/shelljs/shelljs/compare/v0.1.4...v0.2.2)

**Closed issues:**

- which and node\_modules [\#63](https://github.com/shelljs/shelljs/issues/63)
- cannot install with nodejs 0.10.2 [\#57](https://github.com/shelljs/shelljs/issues/57)

**Merged pull requests:**

- Addition of a toEnd\(\) function modeled after the Unix \>\> pipe. [\#78](https://github.com/shelljs/shelljs/pull/78) ([a10y](https://github.com/a10y))
- Added appendTo\(\) function to imitate '\>\>' redirect-and-append pipe. [\#75](https://github.com/shelljs/shelljs/pull/75) ([a10y](https://github.com/a10y))
- Fix a small typo in README.md [\#71](https://github.com/shelljs/shelljs/pull/71) ([asmblah](https://github.com/asmblah))
- adding an `.npmignore` file [\#70](https://github.com/shelljs/shelljs/pull/70) ([stephenmathieson](https://github.com/stephenmathieson))
- tempdir: use `os.tmpDir` when possible [\#67](https://github.com/shelljs/shelljs/pull/67) ([stephenmathieson](https://github.com/stephenmathieson))

## [v0.1.4](https://github.com/shelljs/shelljs/tree/v0.1.4) (2013-05-10)
[Full Changelog](https://github.com/shelljs/shelljs/compare/v0.1.3...v0.1.4)

**Merged pull requests:**

- removing extra fs calls [\#62](https://github.com/shelljs/shelljs/pull/62) ([stephenmathieson](https://github.com/stephenmathieson))
- moving \_jshint\_ to a development dependency [\#61](https://github.com/shelljs/shelljs/pull/61) ([stephenmathieson](https://github.com/stephenmathieson))
- Make the maximum buffersize 20 MB. [\#59](https://github.com/shelljs/shelljs/pull/59) ([waddlesplash](https://github.com/waddlesplash))

## [v0.1.3](https://github.com/shelljs/shelljs/tree/v0.1.3) (2013-04-21)
[Full Changelog](https://github.com/shelljs/shelljs/compare/v0.1.2...v0.1.3)

**Merged pull requests:**

- test\('-L', badlink\) should return true [\#56](https://github.com/shelljs/shelljs/pull/56) ([lge88](https://github.com/lge88))
- exec options now allows `silent:true` with callback. [\#54](https://github.com/shelljs/shelljs/pull/54) ([iapain](https://github.com/iapain))
- Add Zepto to README [\#53](https://github.com/shelljs/shelljs/pull/53) ([madrobby](https://github.com/madrobby))

## [v0.1.2](https://github.com/shelljs/shelljs/tree/v0.1.2) (2013-01-08)
[Full Changelog](https://github.com/shelljs/shelljs/compare/v0.1.1...v0.1.2)

**Closed issues:**

- pushd/popd [\#24](https://github.com/shelljs/shelljs/issues/24)

**Merged pull requests:**

- Implemented chmod command.  Github issue 35 [\#48](https://github.com/shelljs/shelljs/pull/48) ([brandonramirez](https://github.com/brandonramirez))

## [v0.1.1](https://github.com/shelljs/shelljs/tree/v0.1.1) (2013-01-01)
[Full Changelog](https://github.com/shelljs/shelljs/compare/v0.1.0...v0.1.1)

**Merged pull requests:**

- Work in progress: pushd/popd/dirs [\#47](https://github.com/shelljs/shelljs/pull/47) ([mstade](https://github.com/mstade))

## [v0.1.0](https://github.com/shelljs/shelljs/tree/v0.1.0) (2012-12-26)
[Full Changelog](https://github.com/shelljs/shelljs/compare/v0.0.9...v0.1.0)

**Closed issues:**

- test\(\) for binary file? [\#45](https://github.com/shelljs/shelljs/issues/45)
- Inconsistent behaviour of cp command with directories. [\#44](https://github.com/shelljs/shelljs/issues/44)
- Executing SSH with ShellJs [\#43](https://github.com/shelljs/shelljs/issues/43)

**Merged pull requests:**

- Fix for \#44 [\#46](https://github.com/shelljs/shelljs/pull/46) ([mstade](https://github.com/mstade))
- Fix single/double quotes in exec [\#42](https://github.com/shelljs/shelljs/pull/42) ([danielepolencic](https://github.com/danielepolencic))

## [v0.0.9](https://github.com/shelljs/shelljs/tree/v0.0.9) (2012-12-01)
[Full Changelog](https://github.com/shelljs/shelljs/compare/v0.0.8...v0.0.9)

**Closed issues:**

- silent output [\#40](https://github.com/shelljs/shelljs/issues/40)
- asynchronous exec [\#34](https://github.com/shelljs/shelljs/issues/34)

**Merged pull requests:**

- Passed process arguments to executable script [\#36](https://github.com/shelljs/shelljs/pull/36) ([Zanisimo](https://github.com/Zanisimo))

## [v0.0.8](https://github.com/shelljs/shelljs/tree/v0.0.8) (2012-10-11)
[Full Changelog](https://github.com/shelljs/shelljs/compare/v0.0.7...v0.0.8)

**Closed issues:**

- exec with callback should automatically be async [\#31](https://github.com/shelljs/shelljs/issues/31)
- Exporting variables. [\#30](https://github.com/shelljs/shelljs/issues/30)
- Detecting shelljs/node [\#27](https://github.com/shelljs/shelljs/issues/27)

**Merged pull requests:**

- fix: global leak 'stats' [\#29](https://github.com/shelljs/shelljs/pull/29) ([ando-takahiro](https://github.com/ando-takahiro))
- -a includes . and ..; -A does not [\#28](https://github.com/shelljs/shelljs/pull/28) ([aeosynth](https://github.com/aeosynth))

## [v0.0.7](https://github.com/shelljs/shelljs/tree/v0.0.7) (2012-09-23)
[Full Changelog](https://github.com/shelljs/shelljs/compare/v0.0.6...v0.0.7)

**Closed issues:**

- gh-pages: clicking 'fork me' just reloads the page [\#26](https://github.com/shelljs/shelljs/issues/26)
- Not declared local var implies possible memory leak [\#21](https://github.com/shelljs/shelljs/issues/21)
- Cannot echo a string that starts with - [\#20](https://github.com/shelljs/shelljs/issues/20)
- Unexpected cp behaviour with directories [\#15](https://github.com/shelljs/shelljs/issues/15)

**Merged pull requests:**

- add primaries to \_test [\#23](https://github.com/shelljs/shelljs/pull/23) ([aeosynth](https://github.com/aeosynth))

## [v0.0.6](https://github.com/shelljs/shelljs/tree/v0.0.6) (2012-08-07)
[Full Changelog](https://github.com/shelljs/shelljs/compare/v0.0.6pre2...v0.0.6)

**Merged pull requests:**

- Fixed a global variable leak [\#16](https://github.com/shelljs/shelljs/pull/16) ([dallonf](https://github.com/dallonf))

## [v0.0.6pre2](https://github.com/shelljs/shelljs/tree/v0.0.6pre2) (2012-05-25)
[Full Changelog](https://github.com/shelljs/shelljs/compare/v0.0.6pre1...v0.0.6pre2)

## [v0.0.6pre1](https://github.com/shelljs/shelljs/tree/v0.0.6pre1) (2012-05-25)
[Full Changelog](https://github.com/shelljs/shelljs/compare/v0.0.5...v0.0.6pre1)

## [v0.0.5](https://github.com/shelljs/shelljs/tree/v0.0.5) (2012-05-24)
[Full Changelog](https://github.com/shelljs/shelljs/compare/v0.0.5pre4...v0.0.5)

**Closed issues:**

- global.key assigned value 'async' as a result of shell.exec\(...\) [\#12](https://github.com/shelljs/shelljs/issues/12)

**Merged pull requests:**

- Add support for grep option -v. [\#13](https://github.com/shelljs/shelljs/pull/13) ([kkujala](https://github.com/kkujala))

## [v0.0.5pre4](https://github.com/shelljs/shelljs/tree/v0.0.5pre4) (2012-03-27)
[Full Changelog](https://github.com/shelljs/shelljs/compare/v0.0.5pre3...v0.0.5pre4)

## [v0.0.5pre3](https://github.com/shelljs/shelljs/tree/v0.0.5pre3) (2012-03-27)
[Full Changelog](https://github.com/shelljs/shelljs/compare/v0.0.5pre2...v0.0.5pre3)

## [v0.0.5pre2](https://github.com/shelljs/shelljs/tree/v0.0.5pre2) (2012-03-26)
[Full Changelog](https://github.com/shelljs/shelljs/compare/v0.0.5pre1...v0.0.5pre2)

## [v0.0.5pre1](https://github.com/shelljs/shelljs/tree/v0.0.5pre1) (2012-03-26)
[Full Changelog](https://github.com/shelljs/shelljs/compare/v0.0.4...v0.0.5pre1)

**Closed issues:**

- rm\(\) does not respect read/write modes [\#6](https://github.com/shelljs/shelljs/issues/6)

## [v0.0.4](https://github.com/shelljs/shelljs/tree/v0.0.4) (2012-03-22)
[Full Changelog](https://github.com/shelljs/shelljs/compare/v0.0.3...v0.0.4)

**Closed issues:**

- "For convenient iteration via `for in`, ..."? [\#4](https://github.com/shelljs/shelljs/issues/4)

## [v0.0.3](https://github.com/shelljs/shelljs/tree/v0.0.3) (2012-03-21)
[Full Changelog](https://github.com/shelljs/shelljs/compare/v0.0.2...v0.0.3)

## [v0.0.2](https://github.com/shelljs/shelljs/tree/v0.0.2) (2012-03-15)
[Full Changelog](https://github.com/shelljs/shelljs/compare/v0.0.2pre1...v0.0.2)

## [v0.0.2pre1](https://github.com/shelljs/shelljs/tree/v0.0.2pre1) (2012-03-03)


\* *This Change Log was automatically generated by [github_changelog_generator](https://github.com/skywinder/Github-Changelog-Generator)*

---

# ShellJS - Unix shell commands for Node.js

[![Travis](https://img.shields.io/travis/shelljs/shelljs/master.svg?style=flat-square&label=unix)](https://travis-ci.org/shelljs/shelljs)
[![AppVeyor](https://img.shields.io/appveyor/ci/shelljs/shelljs/master.svg?style=flat-square&label=windows)](https://ci.appveyor.com/project/shelljs/shelljs/branch/master)
[![Codecov](https://img.shields.io/codecov/c/github/shelljs/shelljs/master.svg?style=flat-square&label=coverage)](https://codecov.io/gh/shelljs/shelljs)
[![npm version](https://img.shields.io/npm/v/shelljs.svg?style=flat-square)](https://www.npmjs.com/package/shelljs)
[![npm downloads](https://img.shields.io/npm/dm/shelljs.svg?style=flat-square)](https://www.npmjs.com/package/shelljs)

ShellJS is a portable **(Windows/Linux/OS X)** implementation of Unix shell
commands on top of the Node.js API. You can use it to eliminate your shell
script's dependency on Unix while still keeping its familiar and powerful
commands. You can also install it globally so you can run it from outside Node
projects - say goodbye to those gnarly Bash scripts!

ShellJS is proudly tested on every node release since `v4`!

The project is [unit-tested](http://travis-ci.org/shelljs/shelljs) and battle-tested in projects like:

+ [Firebug](http://getfirebug.com/) - Firefox's infamous debugger
+ [JSHint](http://jshint.com) & [ESLint](http://eslint.org/) - popular JavaScript linters
+ [Zepto](http://zeptojs.com) - jQuery-compatible JavaScript library for modern browsers
+ [Yeoman](http://yeoman.io/) - Web application stack and development tool
+ [Deployd.com](http://deployd.com) - Open source PaaS for quick API backend generation
+ And [many more](https://npmjs.org/browse/depended/shelljs).

If you have feedback, suggestions, or need help, feel free to post in our [issue
tracker](https://github.com/shelljs/shelljs/issues).

Think ShellJS is cool? Check out some related projects in our [Wiki
page](https://github.com/shelljs/shelljs/wiki)!

Upgrading from an older version? Check out our [breaking
changes](https://github.com/shelljs/shelljs/wiki/Breaking-Changes) page to see
what changes to watch out for while upgrading.

## Command line use

If you just want cross platform UNIX commands, checkout our new project
[shelljs/shx](https://github.com/shelljs/shx), a utility to expose `shelljs` to
the command line.

For example:

```
$ shx mkdir -p foo
$ shx touch foo/bar.txt
$ shx rm -rf foo
```

## Plugin API

ShellJS now supports third-party plugins! You can learn more about using plugins
and writing your own ShellJS commands in [the
wiki](https://github.com/shelljs/shelljs/wiki/Using-ShellJS-Plugins).

## A quick note about the docs

For documentation on all the latest features, check out our
[README](https://github.com/shelljs/shelljs). To read docs that are consistent
with the latest release, check out [the npm
page](https://www.npmjs.com/package/shelljs) or
[shelljs.org](http://documentup.com/shelljs/shelljs).

## Installing

Via npm:

```bash
$ npm install [-g] shelljs
```

## Examples

```javascript
var shell = require('shelljs');

if (!shell.which('git')) {
  shell.echo('Sorry, this script requires git');
  shell.exit(1);
}

// Copy files to release dir
shell.rm('-rf', 'out/Release');
shell.cp('-R', 'stuff/', 'out/Release');

// Replace macros in each .js file
shell.cd('lib');
shell.ls('*.js').forEach(function (file) {
  shell.sed('-i', 'BUILD_VERSION', 'v0.1.2', file);
  shell.sed('-i', /^.*REMOVE_THIS_LINE.*$/, '', file);
  shell.sed('-i', /.*REPLACE_LINE_WITH_MACRO.*\n/, shell.cat('macro.js'), file);
});
shell.cd('..');

// Run external tool synchronously
if (shell.exec('git commit -am "Auto-commit"').code !== 0) {
  shell.echo('Error: Git commit failed');
  shell.exit(1);
}
```

## Exclude options

If you need to pass a parameter that looks like an option, you can do so like:

```js
shell.grep('--', '-v', 'path/to/file'); // Search for "-v", no grep options

shell.cp('-R', '-dir', 'outdir'); // If already using an option, you're done
```

## Global vs. Local

We no longer recommend using a global-import for ShellJS (i.e.
`require('shelljs/global')`). While still supported for convenience, this
pollutes the global namespace, and should therefore only be used with caution.

Instead, we recommend a local import (standard for npm packages):

```javascript
var shell = require('shelljs');
shell.echo('hello world');
```

<!-- DO NOT MODIFY BEYOND THIS POINT - IT'S AUTOMATICALLY GENERATED -->


## Command reference


All commands run synchronously, unless otherwise stated.
All commands accept standard bash globbing characters (`*`, `?`, etc.),
compatible with the [node `glob` module](https://github.com/isaacs/node-glob).

For less-commonly used commands and features, please check out our [wiki
page](https://github.com/shelljs/shelljs/wiki).


### cat([options,] file [, file ...])
### cat([options,] file_array)

Available options:

+ `-n`: number all output lines

Examples:

```javascript
var str = cat('file*.txt');
var str = cat('file1', 'file2');
var str = cat(['file1', 'file2']); // same as above
```

Returns a string containing the given file, or a concatenated string
containing the files if more than one file is given (a new line character is
introduced between each file).


### cd([dir])

Changes to directory `dir` for the duration of the script. Changes to home
directory if no argument is supplied.


### chmod([options,] octal_mode || octal_string, file)
### chmod([options,] symbolic_mode, file)

Available options:

+ `-v`: output a diagnostic for every file processed
+ `-c`: like verbose, but report only when a change is made
+ `-R`: change files and directories recursively

Examples:

```javascript
chmod(755, '/Users/brandon');
chmod('755', '/Users/brandon'); // same as above
chmod('u+x', '/Users/brandon');
chmod('-R', 'a-w', '/Users/brandon');
```

Alters the permissions of a file or directory by either specifying the
absolute permissions in octal form or expressing the changes in symbols.
This command tries to mimic the POSIX behavior as much as possible.
Notable exceptions:

+ In symbolic modes, `a-r` and `-r` are identical.  No consideration is
  given to the `umask`.
+ There is no "quiet" option, since default behavior is to run silent.


### cp([options,] source [, source ...], dest)
### cp([options,] source_array, dest)

Available options:

+ `-f`: force (default behavior)
+ `-n`: no-clobber
+ `-u`: only copy if `source` is newer than `dest`
+ `-r`, `-R`: recursive
+ `-L`: follow symlinks
+ `-P`: don't follow symlinks

Examples:

```javascript
cp('file1', 'dir1');
cp('-R', 'path/to/dir/', '~/newCopy/');
cp('-Rf', '/tmp/*', '/usr/local/*', '/home/tmp');
cp('-Rf', ['/tmp/*', '/usr/local/*'], '/home/tmp'); // same as above
```

Copies files.


### pushd([options,] [dir | '-N' | '+N'])

Available options:

+ `-n`: Suppresses the normal change of directory when adding directories to the stack, so that only the stack is manipulated.
+ `-q`: Supresses output to the console.

Arguments:

+ `dir`: Sets the current working directory to the top of the stack, then executes the equivalent of `cd dir`.
+ `+N`: Brings the Nth directory (counting from the left of the list printed by dirs, starting with zero) to the top of the list by rotating the stack.
+ `-N`: Brings the Nth directory (counting from the right of the list printed by dirs, starting with zero) to the top of the list by rotating the stack.

Examples:

```javascript
// process.cwd() === '/usr'
pushd('/etc'); // Returns /etc /usr
pushd('+1');   // Returns /usr /etc
```

Save the current directory on the top of the directory stack and then `cd` to `dir`. With no arguments, `pushd` exchanges the top two directories. Returns an array of paths in the stack.


### popd([options,] ['-N' | '+N'])

Available options:

+ `-n`: Suppress the normal directory change when removing directories from the stack, so that only the stack is manipulated.
+ `-q`: Supresses output to the console.

Arguments:

+ `+N`: Removes the Nth directory (counting from the left of the list printed by dirs), starting with zero.
+ `-N`: Removes the Nth directory (counting from the right of the list printed by dirs), starting with zero.

Examples:

```javascript
echo(process.cwd()); // '/usr'
pushd('/etc');       // '/etc /usr'
echo(process.cwd()); // '/etc'
popd();              // '/usr'
echo(process.cwd()); // '/usr'
```

When no arguments are given, `popd` removes the top directory from the stack and performs a `cd` to the new top directory. The elements are numbered from 0, starting at the first directory listed with dirs (i.e., `popd` is equivalent to `popd +0`). Returns an array of paths in the stack.


### dirs([options | '+N' | '-N'])

Available options:

+ `-c`: Clears the directory stack by deleting all of the elements.
+ `-q`: Supresses output to the console.

Arguments:

+ `+N`: Displays the Nth directory (counting from the left of the list printed by dirs when invoked without options), starting with zero.
+ `-N`: Displays the Nth directory (counting from the right of the list printed by dirs when invoked without options), starting with zero.

Display the list of currently remembered directories. Returns an array of paths in the stack, or a single path if `+N` or `-N` was specified.

See also: `pushd`, `popd`


### echo([options,] string [, string ...])

Available options:

+ `-e`: interpret backslash escapes (default)
+ `-n`: remove trailing newline from output

Examples:

```javascript
echo('hello world');
var str = echo('hello world');
echo('-n', 'no newline at end');
```

Prints `string` to stdout, and returns string with additional utility methods
like `.to()`.


### exec(command [, options] [, callback])

Available options:

+ `async`: Asynchronous execution. If a callback is provided, it will be set to
  `true`, regardless of the passed value (default: `false`).
+ `silent`: Do not echo program output to console (default: `false`).
+ `encoding`: Character encoding to use. Affects the values returned to stdout and stderr, and
  what is written to stdout and stderr when not in silent mode (default: `'utf8'`).
+ and any option available to Node.js's
  [`child_process.exec()`](https://nodejs.org/api/child_process.html#child_process_child_process_exec_command_options_callback)

Examples:

```javascript
var version = exec('node --version', {silent:true}).stdout;

var child = exec('some_long_running_process', {async:true});
child.stdout.on('data', function(data) {
  /* ... do something with data ... */
});

exec('some_long_running_process', function(code, stdout, stderr) {
  console.log('Exit code:', code);
  console.log('Program output:', stdout);
  console.log('Program stderr:', stderr);
});
```

Executes the given `command` _synchronously_, unless otherwise specified.  When in synchronous
mode, this returns a `ShellString` (compatible with ShellJS v0.6.x, which returns an object
of the form `{ code:..., stdout:... , stderr:... }`). Otherwise, this returns the child process
object, and the `callback` receives the arguments `(code, stdout, stderr)`.

Not seeing the behavior you want? `exec()` runs everything through `sh`
by default (or `cmd.exe` on Windows), which differs from `bash`. If you
need bash-specific behavior, try out the `{shell: 'path/to/bash'}` option.


### find(path [, path ...])
### find(path_array)

Examples:

```javascript
find('src', 'lib');
find(['src', 'lib']); // same as above
find('.').filter(function(file) { return file.match(/\.js$/); });
```

Returns array of all files (however deep) in the given paths.

The main difference from `ls('-R', path)` is that the resulting file names
include the base directories (e.g., `lib/resources/file1` instead of just `file1`).


### grep([options,] regex_filter, file [, file ...])
### grep([options,] regex_filter, file_array)

Available options:

+ `-v`: Invert `regex_filter` (only print non-matching lines).
+ `-l`: Print only filenames of matching files.
+ `-i`: Ignore case.

Examples:

```javascript
grep('-v', 'GLOBAL_VARIABLE', '*.js');
grep('GLOBAL_VARIABLE', '*.js');
```

Reads input string from given files and returns a string containing all lines of the
file that match the given `regex_filter`.


### head([{'-n': \<num\>},] file [, file ...])
### head([{'-n': \<num\>},] file_array)

Available options:

+ `-n <num>`: Show the first `<num>` lines of the files

Examples:

```javascript
var str = head({'-n': 1}, 'file*.txt');
var str = head('file1', 'file2');
var str = head(['file1', 'file2']); // same as above
```

Read the start of a file.


### ln([options,] source, dest)

Available options:

+ `-s`: symlink
+ `-f`: force

Examples:

```javascript
ln('file', 'newlink');
ln('-sf', 'file', 'existing');
```

Links `source` to `dest`. Use `-f` to force the link, should `dest` already exist.


### ls([options,] [path, ...])
### ls([options,] path_array)

Available options:

+ `-R`: recursive
+ `-A`: all files (include files beginning with `.`, except for `.` and `..`)
+ `-L`: follow symlinks
+ `-d`: list directories themselves, not their contents
+ `-l`: list objects representing each file, each with fields containing `ls
        -l` output fields. See
        [`fs.Stats`](https://nodejs.org/api/fs.html#fs_class_fs_stats)
        for more info

Examples:

```javascript
ls('projs/*.js');
ls('-R', '/users/me', '/tmp');
ls('-R', ['/users/me', '/tmp']); // same as above
ls('-l', 'file.txt'); // { name: 'file.txt', mode: 33188, nlink: 1, ...}
```

Returns array of files in the given `path`, or files in
the current directory if no `path` is  provided.


### mkdir([options,] dir [, dir ...])
### mkdir([options,] dir_array)

Available options:

+ `-p`: full path (and create intermediate directories, if necessary)

Examples:

```javascript
mkdir('-p', '/tmp/a/b/c/d', '/tmp/e/f/g');
mkdir('-p', ['/tmp/a/b/c/d', '/tmp/e/f/g']); // same as above
```

Creates directories.


### mv([options ,] source [, source ...], dest')
### mv([options ,] source_array, dest')

Available options:

+ `-f`: force (default behavior)
+ `-n`: no-clobber

Examples:

```javascript
mv('-n', 'file', 'dir/');
mv('file1', 'file2', 'dir/');
mv(['file1', 'file2'], 'dir/'); // same as above
```

Moves `source` file(s) to `dest`.


### pwd()

Returns the current directory.


### rm([options,] file [, file ...])
### rm([options,] file_array)

Available options:

+ `-f`: force
+ `-r, -R`: recursive

Examples:

```javascript
rm('-rf', '/tmp/*');
rm('some_file.txt', 'another_file.txt');
rm(['some_file.txt', 'another_file.txt']); // same as above
```

Removes files.


### sed([options,] search_regex, replacement, file [, file ...])
### sed([options,] search_regex, replacement, file_array)

Available options:

+ `-i`: Replace contents of `file` in-place. _Note that no backups will be created!_

Examples:

```javascript
sed('-i', 'PROGRAM_VERSION', 'v0.1.3', 'source.js');
sed(/.*DELETE_THIS_LINE.*\n/, '', 'source.js');
```

Reads an input string from `file`s, and performs a JavaScript `replace()` on the input
using the given `search_regex` and `replacement` string or function. Returns the new string after replacement.

Note:

Like unix `sed`, ShellJS `sed` supports capture groups. Capture groups are specified
using the `$n` syntax:

```javascript
sed(/(\w+)\s(\w+)/, '$2, $1', 'file.txt');
```


### set(options)

Available options:

+ `+/-e`: exit upon error (`config.fatal`)
+ `+/-v`: verbose: show all commands (`config.verbose`)
+ `+/-f`: disable filename expansion (globbing)

Examples:

```javascript
set('-e'); // exit upon first error
set('+e'); // this undoes a "set('-e')"
```

Sets global configuration variables.


### sort([options,] file [, file ...])
### sort([options,] file_array)

Available options:

+ `-r`: Reverse the results
+ `-n`: Compare according to numerical value

Examples:

```javascript
sort('foo.txt', 'bar.txt');
sort('-r', 'foo.txt');
```

Return the contents of the `file`s, sorted line-by-line. Sorting multiple
files mixes their content (just as unix `sort` does).


### tail([{'-n': \<num\>},] file [, file ...])
### tail([{'-n': \<num\>},] file_array)

Available options:

+ `-n <num>`: Show the last `<num>` lines of `file`s

Examples:

```javascript
var str = tail({'-n': 1}, 'file*.txt');
var str = tail('file1', 'file2');
var str = tail(['file1', 'file2']); // same as above
```

Read the end of a `file`.


### tempdir()

Examples:

```javascript
var tmp = tempdir(); // "/tmp" for most *nix platforms
```

Searches and returns string containing a writeable, platform-dependent temporary directory.
Follows Python's [tempfile algorithm](http://docs.python.org/library/tempfile.html#tempfile.tempdir).


### test(expression)

Available expression primaries:

+ `'-b', 'path'`: true if path is a block device
+ `'-c', 'path'`: true if path is a character device
+ `'-d', 'path'`: true if path is a directory
+ `'-e', 'path'`: true if path exists
+ `'-f', 'path'`: true if path is a regular file
+ `'-L', 'path'`: true if path is a symbolic link
+ `'-p', 'path'`: true if path is a pipe (FIFO)
+ `'-S', 'path'`: true if path is a socket

Examples:

```javascript
if (test('-d', path)) { /* do something with dir */ };
if (!test('-f', path)) continue; // skip if it's a regular file
```

Evaluates `expression` using the available primaries and returns corresponding value.


### ShellString.prototype.to(file)

Examples:

```javascript
cat('input.txt').to('output.txt');
```

Analogous to the redirection operator `>` in Unix, but works with
`ShellStrings` (such as those returned by `cat`, `grep`, etc.). _Like Unix
redirections, `to()` will overwrite any existing file!_


### ShellString.prototype.toEnd(file)

Examples:

```javascript
cat('input.txt').toEnd('output.txt');
```

Analogous to the redirect-and-append operator `>>` in Unix, but works with
`ShellStrings` (such as those returned by `cat`, `grep`, etc.).


### touch([options,] file [, file ...])
### touch([options,] file_array)

Available options:

+ `-a`: Change only the access time
+ `-c`: Do not create any files
+ `-m`: Change only the modification time
+ `-d DATE`: Parse `DATE` and use it instead of current time
+ `-r FILE`: Use `FILE`'s times instead of current time

Examples:

```javascript
touch('source.js');
touch('-c', '/path/to/some/dir/source.js');
touch({ '-r': FILE }, '/path/to/some/dir/source.js');
```

Update the access and modification times of each `FILE` to the current time.
A `FILE` argument that does not exist is created empty, unless `-c` is supplied.
This is a partial implementation of [`touch(1)`](http://linux.die.net/man/1/touch).


### uniq([options,] [input, [output]])

Available options:

+ `-i`: Ignore case while comparing
+ `-c`: Prefix lines by the number of occurrences
+ `-d`: Only print duplicate lines, one for each group of identical lines

Examples:

```javascript
uniq('foo.txt');
uniq('-i', 'foo.txt');
uniq('-cd', 'foo.txt', 'bar.txt');
```

Filter adjacent matching lines from `input`.


### which(command)

Examples:

```javascript
var nodeExec = which('node');
```

Searches for `command` in the system's `PATH`. On Windows, this uses the
`PATHEXT` variable to append the extension if it's not already executable.
Returns string containing the absolute path to `command`.


### exit(code)

Exits the current process with the given exit `code`.

### error()

Tests if error occurred in the last command. Returns a truthy value if an
error returned, or a falsy value otherwise.

**Note**: do not rely on the
return value to be an error message. If you need the last error message, use
the `.stderr` attribute from the last command's return value instead.


### ShellString(str)

Examples:

```javascript
var foo = ShellString('hello world');
```

Turns a regular string into a string-like object similar to what each
command returns. This has special methods, like `.to()` and `.toEnd()`.


### env['VAR_NAME']

Object containing environment variables (both getter and setter). Shortcut
to `process.env`.

### Pipes

Examples:

```javascript
grep('foo', 'file1.txt', 'file2.txt').sed(/o/g, 'a').to('output.txt');
echo('files with o\'s in the name:\n' + ls().grep('o'));
cat('test.js').exec('node'); // pipe to exec() call
```

Commands can send their output to another command in a pipe-like fashion.
`sed`, `grep`, `cat`, `exec`, `to`, and `toEnd` can appear on the right-hand
side of a pipe. Pipes can be chained.

## Configuration


### config.silent

Example:

```javascript
var sh = require('shelljs');
var silentState = sh.config.silent; // save old silent state
sh.config.silent = true;
/* ... */
sh.config.silent = silentState; // restore old silent state
```

Suppresses all command output if `true`, except for `echo()` calls.
Default is `false`.

### config.fatal

Example:

```javascript
require('shelljs/global');
config.fatal = true; // or set('-e');
cp('this_file_does_not_exist', '/dev/null'); // throws Error here
/* more commands... */
```

If `true`, the script will throw a Javascript error when any shell.js
command encounters an error. Default is `false`. This is analogous to
Bash's `set -e`.

### config.verbose

Example:

```javascript
config.verbose = true; // or set('-v');
cd('dir/');
rm('-rf', 'foo.txt', 'bar.txt');
exec('echo hello');
```

Will print each command as follows:

```
cd dir/
rm -rf foo.txt bar.txt
exec echo hello
```

### config.globOptions

Example:

```javascript
config.globOptions = {nodir: true};
```

Use this value for calls to `glob.sync()` instead of the default options.

### config.reset()

Example:

```javascript
var shell = require('shelljs');
// Make changes to shell.config, and do stuff...
/* ... */
shell.config.reset(); // reset to original state
// Do more stuff, but with original settings
/* ... */
```

Reset `shell.config` to the defaults:

```javascript
{
  fatal: false,
  globOptions: {},
  maxdepth: 255,
  noglob: false,
  silent: false,
  verbose: false,
}
```

## Team

| [![Nate Fischer](https://avatars.githubusercontent.com/u/5801521?s=130)](https://github.com/nfischer) | [![Brandon Freitag](https://avatars1.githubusercontent.com/u/5988055?v=3&s=130)](http://github.com/freitagbr) |
|:---:|:---:|
| [Nate Fischer](https://github.com/nfischer) | [Brandon Freitag](http://github.com/freitagbr) |


---

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [v1.1.0](https://github.com/ljharb/side-channel/compare/v1.0.6...v1.1.0) - 2024-12-11

### Commits

- [Refactor] extract implementations to `side-channel-weakmap`, `side-channel-map`, `side-channel-list` [`ada5955`](https://github.com/ljharb/side-channel/commit/ada595549a5c4c6c853756d598846b180941c6da)
- [New] add `channel.delete` [`c01d2d3`](https://github.com/ljharb/side-channel/commit/c01d2d3fd51dbb1ce6da72ad7916e61bd6172aad)
- [types] improve types [`0c54356`](https://github.com/ljharb/side-channel/commit/0c5435651417df41b8cc1a5f7cdce8bffae68cde)
- [readme] add content [`be24868`](https://github.com/ljharb/side-channel/commit/be248682ac294b0e22c883092c45985aa91c490a)
- [actions] split out node 10-20, and 20+ [`c4488e2`](https://github.com/ljharb/side-channel/commit/c4488e241ef3d49a19fe266ac830a2e644305911)
- [types] use shared tsconfig [`0e0d57c`](https://github.com/ljharb/side-channel/commit/0e0d57c2ff17c7b45c6cbd43ebcf553edc9e3adc)
- [Dev Deps] update `@ljharb/eslint-config`, `@ljharb/tsconfig`, `@types/get-intrinsic`, `@types/object-inspect`, `@types/tape`, `auto-changelog`, `tape` [`fb4f622`](https://github.com/ljharb/side-channel/commit/fb4f622e64a99a1e40b6e5cd7691674a9dc429e4)
- [Deps] update `call-bind`, `get-intrinsic`, `object-inspect` [`b78336b`](https://github.com/ljharb/side-channel/commit/b78336b886172d1b457d414ac9e28de8c5fecc78)
- [Tests] replace `aud` with `npm audit` [`ee3ab46`](https://github.com/ljharb/side-channel/commit/ee3ab4690d954311c35115651bcfd45edd205aa1)
- [Dev Deps] add missing peer dep [`c03e21a`](https://github.com/ljharb/side-channel/commit/c03e21a7def3b67cdc15ae22316884fefcb2f6a8)

## [v1.0.6](https://github.com/ljharb/side-channel/compare/v1.0.5...v1.0.6) - 2024-02-29

### Commits

- add types [`9beef66`](https://github.com/ljharb/side-channel/commit/9beef6643e6d717ea57bedabf86448123a7dd9e9)
- [meta] simplify `exports` [`4334cf9`](https://github.com/ljharb/side-channel/commit/4334cf9df654151504c383b62a2f9ebdc8d9d5ac)
- [Deps] update `call-bind` [`d6043c4`](https://github.com/ljharb/side-channel/commit/d6043c4d8f4d7be9037dd0f0419c7a2e0e39ec6a)
- [Dev Deps] update `tape` [`6aca376`](https://github.com/ljharb/side-channel/commit/6aca3761868dc8cd5ff7fd9799bf6b95e09a6eb0)

## [v1.0.5](https://github.com/ljharb/side-channel/compare/v1.0.4...v1.0.5) - 2024-02-06

### Commits

- [actions] reuse common workflows [`3d2e1ff`](https://github.com/ljharb/side-channel/commit/3d2e1ffd16dd6eaaf3e40ff57951f840d2d63c04)
- [meta] use `npmignore` to autogenerate an npmignore file [`04296ea`](https://github.com/ljharb/side-channel/commit/04296ea17d1544b0a5d20fd5bfb31aa4f6513eb9)
- [meta] add `.editorconfig`; add `eclint` [`130f0a6`](https://github.com/ljharb/side-channel/commit/130f0a6adbc04d385c7456a601d38344dce3d6a9)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `aud`, `auto-changelog`, `safe-publish-latest`, `tape` [`d480c2f`](https://github.com/ljharb/side-channel/commit/d480c2fbe757489ae9b4275491ffbcc3ac4725e9)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `aud`, `auto-changelog`, `tape` [`ecbe70e`](https://github.com/ljharb/side-channel/commit/ecbe70e53a418234081a77971fec1fdfae20c841)
- [actions] update rebase action [`75240b9`](https://github.com/ljharb/side-channel/commit/75240b9963b816e8846400d2287cb68f88c7fba7)
- [Dev Deps] update `@ljharb/eslint-config`, `aud`, `npmignore`, `tape` [`ae8d281`](https://github.com/ljharb/side-channel/commit/ae8d281572430099109870fd9430d2ca3f320b8d)
- [Dev Deps] update `@ljharb/eslint-config`, `aud`, `tape` [`7125b88`](https://github.com/ljharb/side-channel/commit/7125b885fd0eacad4fee9b073b72d14065ece278)
- [Deps] update `call-bind`, `get-intrinsic`, `object-inspect` [`82577c9`](https://github.com/ljharb/side-channel/commit/82577c9796304519139a570f82a317211b5f3b86)
- [Deps] update `call-bind`, `get-intrinsic`, `object-inspect` [`550aadf`](https://github.com/ljharb/side-channel/commit/550aadf20475a6081fd70304cc54f77259a5c8a8)
- [Tests] increase coverage [`5130877`](https://github.com/ljharb/side-channel/commit/5130877a7b27c862e64e6d1c12a178b28808859d)
- [Deps] update `get-intrinsic`, `object-inspect` [`ba0194c`](https://github.com/ljharb/side-channel/commit/ba0194c505b1a8a0427be14cadd5b8a46d4d01b8)
- [meta] add missing `engines.node` [`985fd24`](https://github.com/ljharb/side-channel/commit/985fd249663cb06617a693a94fe08cad12f5cb70)
- [Refactor] use `es-errors`, so things that only need those do not need `get-intrinsic` [`40227a8`](https://github.com/ljharb/side-channel/commit/40227a87b01709ad2c0eebf87eb4223a800099b9)
- [Deps] update `get-intrinsic` [`a989b40`](https://github.com/ljharb/side-channel/commit/a989b4024958737ae7be9fbffdeff2078f33a0fd)
- [Deps] update `object-inspect` [`aec42d2`](https://github.com/ljharb/side-channel/commit/aec42d2ec541a31aaa02475692c87d489237d9a3)

## [v1.0.4](https://github.com/ljharb/side-channel/compare/v1.0.3...v1.0.4) - 2020-12-29

### Commits

- [Tests] migrate tests to Github Actions [`10909cb`](https://github.com/ljharb/side-channel/commit/10909cbf8ce9c0bf96f604cf13d7ffd5a22c2d40)
- [Refactor] Use a linked list rather than an array, and move accessed nodes to the beginning [`195613f`](https://github.com/ljharb/side-channel/commit/195613f28b5c1e6072ef0b61b5beebaf2b6a304e)
- [meta] do not publish github action workflow files [`290ec29`](https://github.com/ljharb/side-channel/commit/290ec29cd21a60585145b4a7237ec55228c52c27)
- [Tests] run `nyc` on all tests; use `tape` runner [`ea6d030`](https://github.com/ljharb/side-channel/commit/ea6d030ff3fe6be2eca39e859d644c51ecd88869)
- [actions] add "Allow Edits" workflow [`d464d8f`](https://github.com/ljharb/side-channel/commit/d464d8fe52b5eddf1504a0ed97f0941a90f32c15)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `aud`, `auto-changelog` [`02daca8`](https://github.com/ljharb/side-channel/commit/02daca87c6809821c97be468d1afa2f5ef447383)
- [Refactor] use `call-bind` and `get-intrinsic` instead of `es-abstract` [`e09d481`](https://github.com/ljharb/side-channel/commit/e09d481528452ebafa5cdeae1af665c35aa2deee)
- [Deps] update `object.assign` [`ee83aa8`](https://github.com/ljharb/side-channel/commit/ee83aa81df313b5e46319a63adb05cf0c179079a)
- [actions] update rebase action to use checkout v2 [`7726b0b`](https://github.com/ljharb/side-channel/commit/7726b0b058b632fccea709f58960871defaaa9d7)

## [v1.0.3](https://github.com/ljharb/side-channel/compare/v1.0.2...v1.0.3) - 2020-08-23

### Commits

- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `aud`, `auto-changelog`, `tape` [`1f10561`](https://github.com/ljharb/side-channel/commit/1f105611ef3acf32dec8032ae5c0baa5e56bb868)
- [Deps] update `es-abstract`, `object-inspect` [`bc20159`](https://github.com/ljharb/side-channel/commit/bc201597949a505e37cef9eaf24c7010831e6f03)
- [Dev Deps] update `@ljharb/eslint-config`, `tape` [`b9b2b22`](https://github.com/ljharb/side-channel/commit/b9b2b225f9e0ea72a6ec2b89348f0bd690bc9ed1)
- [Dev Deps] update `eslint`, `@ljharb/eslint-config`, `tape` [`7055ab4`](https://github.com/ljharb/side-channel/commit/7055ab4de0860606efd2003674a74f1fe6ebc07e)
- [Dev Deps] update `auto-changelog`; add `aud` [`d278c37`](https://github.com/ljharb/side-channel/commit/d278c37d08227be4f84aa769fcd919e73feeba40)
- [actions] switch Automatic Rebase workflow to `pull_request_target` event [`3bcf982`](https://github.com/ljharb/side-channel/commit/3bcf982faa122745b39c33ce83d32fdf003741c6)
- [Tests] only audit prod deps [`18d01c4`](https://github.com/ljharb/side-channel/commit/18d01c4015b82a3d75044c4d5ba7917b2eac01ec)
- [Deps] update `es-abstract` [`6ab096d`](https://github.com/ljharb/side-channel/commit/6ab096d9de2b482cf5e0717e34e212f5b2b9bc9a)
- [Dev Deps] update `tape` [`9dc174c`](https://github.com/ljharb/side-channel/commit/9dc174cc651dfd300b4b72da936a0a7eda5f9452)
- [Deps] update `es-abstract` [`431d0f0`](https://github.com/ljharb/side-channel/commit/431d0f0ff11fbd2ae6f3115582a356d3a1cfce82)
- [Deps] update `es-abstract` [`49869fd`](https://github.com/ljharb/side-channel/commit/49869fd323bf4453f0ba515c0fb265cf5ab7b932)
- [meta] Add package.json to package's exports [`77d9cdc`](https://github.com/ljharb/side-channel/commit/77d9cdceb2a9e47700074f2ae0c0a202e7dac0d4)

## [v1.0.2](https://github.com/ljharb/side-channel/compare/v1.0.1...v1.0.2) - 2019-12-20

### Commits

- [Dev Deps] update `@ljharb/eslint-config`, `tape` [`4a526df`](https://github.com/ljharb/side-channel/commit/4a526df44e4701566ed001ec78546193f818b082)
- [Deps] update `es-abstract` [`d4f6e62`](https://github.com/ljharb/side-channel/commit/d4f6e629b6fb93a07415db7f30d3c90fd7f264fe)

## [v1.0.1](https://github.com/ljharb/side-channel/compare/v1.0.0...v1.0.1) - 2019-12-01

### Commits

- [Fix] add missing "exports" [`d212907`](https://github.com/ljharb/side-channel/commit/d2129073abf0701a5343bf28aa2145617604dc2e)

## v1.0.0 - 2019-12-01

### Commits

- Initial implementation [`dbebd3a`](https://github.com/ljharb/side-channel/commit/dbebd3a4b5ed64242f9a6810efe7c4214cd8cde4)
- Initial tests [`73bdefe`](https://github.com/ljharb/side-channel/commit/73bdefe568c9076cf8c0b8719bc2141aec0e19b8)
- Initial commit [`43c03e1`](https://github.com/ljharb/side-channel/commit/43c03e1c2849ec50a87b7a5cd76238a62b0b8770)
- npm init [`5c090a7`](https://github.com/ljharb/side-channel/commit/5c090a765d66a5527d9889b89aeff78dee91348c)
- [meta] add `auto-changelog` [`a5c4e56`](https://github.com/ljharb/side-channel/commit/a5c4e5675ec02d5eb4d84b4243aeea2a1d38fbec)
- [actions] add automatic rebasing / merge commit blocking [`bab1683`](https://github.com/ljharb/side-channel/commit/bab1683d8f9754b086e94397699fdc645e0d7077)
- [meta] add `funding` field; create FUNDING.yml [`63d7aea`](https://github.com/ljharb/side-channel/commit/63d7aeaf34f5650650ae97ca4b9fae685bd0937c)
- [Tests] add `npm run lint` [`46a5a81`](https://github.com/ljharb/side-channel/commit/46a5a81705cd2664f83df232c01dbbf2ee952885)
- Only apps should have lockfiles [`8b16b03`](https://github.com/ljharb/side-channel/commit/8b16b0305f00895d90c4e2e5773c854cfea0e448)
- [meta] add `safe-publish-latest` [`2f098ef`](https://github.com/ljharb/side-channel/commit/2f098ef092a39399cfe548b19a1fc03c2fd2f490)


---

# side-channel <sup>[![Version Badge][npm-version-svg]][package-url]</sup>

[![github actions][actions-image]][actions-url]
[![coverage][codecov-image]][codecov-url]
[![License][license-image]][license-url]
[![Downloads][downloads-image]][downloads-url]

[![npm badge][npm-badge-png]][package-url]

Store information about any JS value in a side channel. Uses WeakMap if available.

Warning: in an environment that lacks `WeakMap`, this implementation will leak memory until you `delete` the `key`.

## Getting started

```sh
npm install --save side-channel
```

## Usage/Examples

```js
const assert = require('assert');
const getSideChannel = require('side-channel');

const channel = getSideChannel();

const key = {};
assert.equal(channel.has(key), false);
assert.throws(() => channel.assert(key), TypeError);

channel.set(key, 42);

channel.assert(key); // does not throw
assert.equal(channel.has(key), true);
assert.equal(channel.get(key), 42);

channel.delete(key);
assert.equal(channel.has(key), false);
assert.throws(() => channel.assert(key), TypeError);
```

## Tests

Clone the repo, `npm install`, and run `npm test`

[package-url]: https://npmjs.org/package/side-channel
[npm-version-svg]: https://versionbadg.es/ljharb/side-channel.svg
[deps-svg]: https://david-dm.org/ljharb/side-channel.svg
[deps-url]: https://david-dm.org/ljharb/side-channel
[dev-deps-svg]: https://david-dm.org/ljharb/side-channel/dev-status.svg
[dev-deps-url]: https://david-dm.org/ljharb/side-channel#info=devDependencies
[npm-badge-png]: https://nodei.co/npm/side-channel.png?downloads=true&stars=true
[license-image]: https://img.shields.io/npm/l/side-channel.svg
[license-url]: LICENSE
[downloads-image]: https://img.shields.io/npm/dm/side-channel.svg
[downloads-url]: https://npm-stat.com/charts.html?package=side-channel
[codecov-image]: https://codecov.io/gh/ljharb/side-channel/branch/main/graphs/badge.svg
[codecov-url]: https://app.codecov.io/gh/ljharb/side-channel/
[actions-image]: https://img.shields.io/endpoint?url=https://github-actions-badge-u3jn4tfpocch.runkit.sh/ljharb/side-channel
[actions-url]: https://github.com/ljharb/side-channel/actions


---

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## v1.0.0 - 2024-12-10

### Commits

- Initial implementation, tests, readme, types [`5d6baee`](https://github.com/ljharb/side-channel-list/commit/5d6baee5c9054a1238007f5a1dfc109a7a816251)
- Initial commit [`3ae784c`](https://github.com/ljharb/side-channel-list/commit/3ae784c63a47895fbaeed2a91ab54a8029a7a100)
- npm init [`07055a4`](https://github.com/ljharb/side-channel-list/commit/07055a4d139895565b199dba5fe2479c1a1b9e28)
- Only apps should have lockfiles [`9573058`](https://github.com/ljharb/side-channel-list/commit/9573058a47494e2d68f8c6c77b5d7fbe441949c1)


---

# side-channel-list <sup>[![Version Badge][npm-version-svg]][package-url]</sup>

[![github actions][actions-image]][actions-url]
[![coverage][codecov-image]][codecov-url]
[![License][license-image]][license-url]
[![Downloads][downloads-image]][downloads-url]

[![npm badge][npm-badge-png]][package-url]

Store information about any JS value in a side channel, using a linked list.

Warning: this implementation will leak memory until you `delete` the `key`.
Use [`side-channel`](https://npmjs.com/side-channel) for the best available strategy.

## Getting started

```sh
npm install --save side-channel-list
```

## Usage/Examples

```js
const assert = require('assert');
const getSideChannelList = require('side-channel-list');

const channel = getSideChannelList();

const key = {};
assert.equal(channel.has(key), false);
assert.throws(() => channel.assert(key), TypeError);

channel.set(key, 42);

channel.assert(key); // does not throw
assert.equal(channel.has(key), true);
assert.equal(channel.get(key), 42);

channel.delete(key);
assert.equal(channel.has(key), false);
assert.throws(() => channel.assert(key), TypeError);
```

## Tests

Clone the repo, `npm install`, and run `npm test`

[package-url]: https://npmjs.org/package/side-channel-list
[npm-version-svg]: https://versionbadg.es/ljharb/side-channel-list.svg
[deps-svg]: https://david-dm.org/ljharb/side-channel-list.svg
[deps-url]: https://david-dm.org/ljharb/side-channel-list
[dev-deps-svg]: https://david-dm.org/ljharb/side-channel-list/dev-status.svg
[dev-deps-url]: https://david-dm.org/ljharb/side-channel-list#info=devDependencies
[npm-badge-png]: https://nodei.co/npm/side-channel-list.png?downloads=true&stars=true
[license-image]: https://img.shields.io/npm/l/side-channel-list.svg
[license-url]: LICENSE
[downloads-image]: https://img.shields.io/npm/dm/side-channel-list.svg
[downloads-url]: https://npm-stat.com/charts.html?package=side-channel-list
[codecov-image]: https://codecov.io/gh/ljharb/side-channel-list/branch/main/graphs/badge.svg
[codecov-url]: https://app.codecov.io/gh/ljharb/side-channel-list/
[actions-image]: https://img.shields.io/endpoint?url=https://github-actions-badge-u3jn4tfpocch.runkit.sh/ljharb/side-channel-list
[actions-url]: https://github.com/ljharb/side-channel-list/actions


---

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [v1.0.1](https://github.com/ljharb/side-channel-map/compare/v1.0.0...v1.0.1) - 2024-12-10

### Commits

- [Deps] update `call-bound` [`6d05aaa`](https://github.com/ljharb/side-channel-map/commit/6d05aaa4ce5f2be4e7825df433d650696f0ba40f)
- [types] fix generics ordering [`11c0184`](https://github.com/ljharb/side-channel-map/commit/11c0184132ac11fdc16857e12682e148e5e9ee74)

## v1.0.0 - 2024-12-10

### Commits

- Initial implementation, tests, readme, types [`ad877b4`](https://github.com/ljharb/side-channel-map/commit/ad877b42926d46d63fff76a2bd01d2b4a01959a9)
- Initial commit [`28f8879`](https://github.com/ljharb/side-channel-map/commit/28f8879c512abe8fcf9b6a4dc7754a0287e5eba4)
- npm init [`2c9604e`](https://github.com/ljharb/side-channel-map/commit/2c9604e5aa40223e425ea7cea78f8a07697504bd)
- Only apps should have lockfiles [`5e7ba9c`](https://github.com/ljharb/side-channel-map/commit/5e7ba9cffe3ef42095815adc8ac1255b49bbadf5)


---

# side-channel-map <sup>[![Version Badge][npm-version-svg]][package-url]</sup>

[![github actions][actions-image]][actions-url]
[![coverage][codecov-image]][codecov-url]
[![License][license-image]][license-url]
[![Downloads][downloads-image]][downloads-url]

[![npm badge][npm-badge-png]][package-url]

Store information about any JS value in a side channel, using a Map.

Warning: if the `key` is an object, this implementation will leak memory until you `delete` it.
Use [`side-channel`](https://npmjs.com/side-channel) for the best available strategy.

## Getting started

```sh
npm install --save side-channel-map
```

## Usage/Examples

```js
const assert = require('assert');
const getSideChannelMap = require('side-channel-map');

const channel = getSideChannelMap();

const key = {};
assert.equal(channel.has(key), false);
assert.throws(() => channel.assert(key), TypeError);

channel.set(key, 42);

channel.assert(key); // does not throw
assert.equal(channel.has(key), true);
assert.equal(channel.get(key), 42);

channel.delete(key);
assert.equal(channel.has(key), false);
assert.throws(() => channel.assert(key), TypeError);
```

## Tests

Clone the repo, `npm install`, and run `npm test`

[package-url]: https://npmjs.org/package/side-channel-map
[npm-version-svg]: https://versionbadg.es/ljharb/side-channel-map.svg
[deps-svg]: https://david-dm.org/ljharb/side-channel-map.svg
[deps-url]: https://david-dm.org/ljharb/side-channel-map
[dev-deps-svg]: https://david-dm.org/ljharb/side-channel-map/dev-status.svg
[dev-deps-url]: https://david-dm.org/ljharb/side-channel-map#info=devDependencies
[npm-badge-png]: https://nodei.co/npm/side-channel-map.png?downloads=true&stars=true
[license-image]: https://img.shields.io/npm/l/side-channel-map.svg
[license-url]: LICENSE
[downloads-image]: https://img.shields.io/npm/dm/side-channel-map.svg
[downloads-url]: https://npm-stat.com/charts.html?package=side-channel-map
[codecov-image]: https://codecov.io/gh/ljharb/side-channel-map/branch/main/graphs/badge.svg
[codecov-url]: https://app.codecov.io/gh/ljharb/side-channel-map/
[actions-image]: https://img.shields.io/endpoint?url=https://github-actions-badge-u3jn4tfpocch.runkit.sh/ljharb/side-channel-map
[actions-url]: https://github.com/ljharb/side-channel-map/actions


---

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [v1.0.2](https://github.com/ljharb/side-channel-weakmap/compare/v1.0.1...v1.0.2) - 2024-12-10

### Commits

- [types] fix generics ordering [`1b62e94`](https://github.com/ljharb/side-channel-weakmap/commit/1b62e94a2ad6ed30b640ba73c4a2535836c67289)

## [v1.0.1](https://github.com/ljharb/side-channel-weakmap/compare/v1.0.0...v1.0.1) - 2024-12-10

### Commits

- [types] fix generics ordering [`08a4a5d`](https://github.com/ljharb/side-channel-weakmap/commit/08a4a5dbffedc3ebc79f1aaaf5a3dd6d2196dc1b)
- [Deps] update `side-channel-map` [`b53fe44`](https://github.com/ljharb/side-channel-weakmap/commit/b53fe447dfdd3a9aebedfd015b384eac17fce916)

## v1.0.0 - 2024-12-10

### Commits

- Initial implementation, tests, readme, types [`53c0fa4`](https://github.com/ljharb/side-channel-weakmap/commit/53c0fa4788435a006f58b9d7b43cb65989ecee49)
- Initial commit [`a157947`](https://github.com/ljharb/side-channel-weakmap/commit/a157947f26fcaf2c4a941d3a044e76bf67343532)
- npm init [`54dfc55`](https://github.com/ljharb/side-channel-weakmap/commit/54dfc55bafb16265910d5aad4e743c43aee5bbbb)
- Only apps should have lockfiles [`0ddd6c7`](https://github.com/ljharb/side-channel-weakmap/commit/0ddd6c7b07fe8ee04d67b2e9f7255af7ce62c07d)


---

# side-channel-weakmap <sup>[![Version Badge][npm-version-svg]][package-url]</sup>

[![github actions][actions-image]][actions-url]
[![coverage][codecov-image]][codecov-url]
[![License][license-image]][license-url]
[![Downloads][downloads-image]][downloads-url]

[![npm badge][npm-badge-png]][package-url]

Store information about any JS value in a side channel. Uses WeakMap if available.

Warning: this implementation will leak memory until you `delete` the `key`.
Use [`side-channel`](https://npmjs.com/side-channel) for the best available strategy.

## Getting started

```sh
npm install --save side-channel-weakmap
```

## Usage/Examples

```js
const assert = require('assert');
const getSideChannelList = require('side-channel-weakmap');

const channel = getSideChannelList();

const key = {};
assert.equal(channel.has(key), false);
assert.throws(() => channel.assert(key), TypeError);

channel.set(key, 42);

channel.assert(key); // does not throw
assert.equal(channel.has(key), true);
assert.equal(channel.get(key), 42);

channel.delete(key);
assert.equal(channel.has(key), false);
assert.throws(() => channel.assert(key), TypeError);
```

## Tests

Clone the repo, `npm install`, and run `npm test`

[package-url]: https://npmjs.org/package/side-channel-weakmap
[npm-version-svg]: https://versionbadg.es/ljharb/side-channel-weakmap.svg
[deps-svg]: https://david-dm.org/ljharb/side-channel-weakmap.svg
[deps-url]: https://david-dm.org/ljharb/side-channel-weakmap
[dev-deps-svg]: https://david-dm.org/ljharb/side-channel-weakmap/dev-status.svg
[dev-deps-url]: https://david-dm.org/ljharb/side-channel-weakmap#info=devDependencies
[npm-badge-png]: https://nodei.co/npm/side-channel-weakmap.png?downloads=true&stars=true
[license-image]: https://img.shields.io/npm/l/side-channel-weakmap.svg
[license-url]: LICENSE
[downloads-image]: https://img.shields.io/npm/dm/side-channel-weakmap.svg
[downloads-url]: https://npm-stat.com/charts.html?package=side-channel-weakmap
[codecov-image]: https://codecov.io/gh/ljharb/side-channel-weakmap/branch/main/graphs/badge.svg
[codecov-url]: https://app.codecov.io/gh/ljharb/side-channel-weakmap/
[actions-image]: https://img.shields.io/endpoint?url=https://github-actions-badge-u3jn4tfpocch.runkit.sh/ljharb/side-channel-weakmap
[actions-url]: https://github.com/ljharb/side-channel-weakmap/actions


---

# signal-exit

[![Build Status](https://travis-ci.org/tapjs/signal-exit.png)](https://travis-ci.org/tapjs/signal-exit)
[![Coverage](https://coveralls.io/repos/tapjs/signal-exit/badge.svg?branch=master)](https://coveralls.io/r/tapjs/signal-exit?branch=master)
[![NPM version](https://img.shields.io/npm/v/signal-exit.svg)](https://www.npmjs.com/package/signal-exit)
[![Standard Version](https://img.shields.io/badge/release-standard%20version-brightgreen.svg)](https://github.com/conventional-changelog/standard-version)

When you want to fire an event no matter how a process exits:

* reaching the end of execution.
* explicitly having `process.exit(code)` called.
* having `process.kill(pid, sig)` called.
* receiving a fatal signal from outside the process

Use `signal-exit`.

```js
var onExit = require('signal-exit')

onExit(function (code, signal) {
  console.log('process exited!')
})
```

## API

`var remove = onExit(function (code, signal) {}, options)`

The return value of the function is a function that will remove the
handler.

Note that the function *only* fires for signals if the signal would
cause the process to exit.  That is, there are no other listeners, and
it is a fatal signal.

## Options

* `alwaysLast`: Run this handler after any other signal or exit
  handlers.  This causes `process.emit` to be monkeypatched.


---

# sirv ![CI](https://github.com/lukeed/sirv/workflows/CI/badge.svg)

> The optimized and lightweight middleware for serving requests to static assets

You may use `sirv` as a *very* fast and lightweight alternative to [`serve-static`](https://www.npmjs.com/package/serve-static).

The massive performance advantage over `serve-static` is explained by **not** relying on the file system for existence checks on every request. These are expensive interactions and must be avoided whenever possible! Instead, when not in "dev" mode, `sirv` performs all its file-system operations upfront and then relies on its cache for future operations.

This middleware will work out of the box for [Polka](https://github.com/lukeed/polka), Express, and other Express-like frameworks. It will also work with the native `http`, `https` and `http2` modules. It requires _very_ little effort to modify/wrap it for servers that don't accept the `(req, res, next)` signature.

:bulb: For a feature-complete CLI application, check out the sibling [`sirv-cli`](https://github.com/lukeed/sirv/tree/master/packages/sirv-cli) package as an alternative to [`zeit/serve`](https://github.com/zeit/serve)~!

## Install

```
$ npm install --save sirv
```


## Usage

```js
const sirv = require('sirv');
const polka = require('polka');
const compress = require('compression')();

// Init `sirv` handler
const assets = sirv('public', {
  maxAge: 31536000, // 1Y
  immutable: true
});

polka()
  .use(compress, assets)
  .use('/api', require('./api'))
  .listen(3000, err => {
    if (err) throw err;
    console.log('> Ready on localhost:3000~!');
  });
```


## API

### sirv(dir, opts={})

Returns: `Function`

The returned function is a middleware in the standard Express-like signature: `(req, res, next)`, where `req` is the [`http.IncomingMessage`](https://nodejs.org/api/http.html#http_class_http_incomingmessage), `res` is the [`http.ServerResponse`](https://nodejs.org/dist/latest-v9.x/docs/api/http.html#http_class_http_serverresponse), and `next` (in this case) is the function to call if no file was found for the given path.

When defined, a `next()` callback is always called _instead of_ the [`opts.onNoMatch`](#optsonnomatch) callback. However, unlike `onNoMatch`, your `next()` is given no arguments.

#### dir
Type: `String`<br>
Default: `.`

The directory from which to read and serve assets. It is resolved to an absolute path &mdash; you must provide an absolute path yourself if `process.cwd()` is not the correct assumption.

#### opts.dev
Type: `Boolean`<br>
Default: `false`

Enable "dev" mode, which disables/skips caching. Instead, `sirv` will traverse the file system ***on every request***.

Additionally, `dev` mode will ignore `maxAge` and `immutable` as these options generate a production-oriented `Cache-Control` header value.

> **Important:** Do not use `dev` mode in production!

#### opts.etag
Type: `Boolean`<br>
Default: `false`

Generate and attach an `ETag` header to responses.

> **Note:** If an incoming request's [`If-None-Match` header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-None-Match) matches the `ETag` value, a `304` response is given.

#### opts.dotfiles
Type: `Boolean`<br>
Default: `false`

Allow requests to dotfiles (files or directories beginning with a `.`).

> **Note:** Requests to [`/.well-known/*`](https://tools.ietf.org/html/rfc8615) are always allowed.

#### opts.extensions
Type: `Array<String>`<br>
Default: `['html', 'htm']`

The file extension fallbacks to check for if a pathame is not initially found. For example, if a `/login` request cannot find a `login` filename, it will then look for `login.html` and `login.htm` before giving up~!

> **Important:** Actually, `sirv` will **also** look for `login/index.html` and `login/index.htm` before giving up.

#### opts.gzip
Type: `Boolean`<br>
Default: `false`

Determine if `sirv` look for **precompiled** `*.gz` files.<br>
Must be enabled _and_ the incoming request's [`Accept Encoding`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding) must include "gzip" in order for `sirv` to search for the gzip'd alternative.

> **Note:** The `.gz` assumption also applies to the `opts.extensions` list.

```js
// NOTE: PSEUDO CODE
// Showing lookup logic

// Request: [Accept-Encoding: gzip] "/foobar.jpg"
lookup([
  '/foobar.jpg.gz', '/foobar.jpg',
  '/foobar.jpg.html.gz', '/foobar.jpg/index.html.gz',
  '/foobar.jpg.htm.gz', '/foobar.jpg/index.htm.gz',
  '/foobar.jpg.html', '/foobar.jpg/index.html',
  '/foobar.jpg.htm', '/foobar.jpg/index.htm',
]);

// Request: [Accept-Encoding: gzip] "/"
lookup([
  '/index.html.gz',
  '/index.htm.gz',
  '/index.html',
  '/index.htm',
]);
```


#### opts.brotli
Type: `Boolean`<br>
Default: `false`

Determine if `sirv` look for **precompiled** `*.br` files.<br>
Must be enabled _and_ the incoming request's [`Accept Encoding`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding) must include either "br" or "brotli" in order for `sirv` to search for the brotli-compressed alternative.

> **Note:** The `.br` assumption also applies to the `opts.extensions` list.

When both `opts.broli` and `opts.gzip` are enabled &mdash; and all conditions are equal &mdash; then the brotli variant always takes priority.

```js
// NOTE: PSEUDO CODE
// Showing lookup logic

// Request: [Accept-Encoding: br] "/foobar.jpg"
lookup([
  '/foobar.jpg.br', '/foobar.jpg',
  '/foobar.jpg.html.br', '/foobar.jpg/index.html.br',
  '/foobar.jpg.htm.br', '/foobar.jpg/index.htm.br',
  '/foobar.jpg.html', '/foobar.jpg/index.html',
  '/foobar.jpg.htm', '/foobar.jpg/index.htm',
]);

// Request: [Accept-Encoding: br,gz] "/"
lookup([
  '/index.html.br'
  '/index.htm.br'
  '/index.html.gz'
  '/index.htm.gz'
  '/index.html'
  '/index.htm'
]);
```

#### opts.maxAge
Type: `Number`<br>
Default: `undefined`

Enables the `Cache-Control` header on responses and sets the `max-age` value (in seconds).<br>
For example, `maxAge: 31536000` is equivalent to one year.

#### opts.immutable
Type: `Boolean`<br>
Default: `false`

Appends the [`immutable` directive](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#Revalidation_and_reloading) on your `Cache-Control` header, used for uniquely-named assets that will not change!

> **Important:** Will only work if `opts.maxAge` has a value defined!

#### opts.single
Type: `Boolean` or `String`<br>
Default: `false`

Treat the directory as a single-page application.

When `true`, the directory's index page (default `index.html`) will be sent if the request asset does not exist.<br>
You may pass a `string` value to use a file _instead of_ `index.html` as your fallback.

For example, if "/about" is requested but no variants of that file exist, then the response for "/" is sent instead:

```js
// Note: This is psuedo code to illustrate what's happening

// Request: "/about"
let file = find(['/about', '/about.html', '/about.htm', '/about/index.html', '/about.htm']);
if (file) {
  send(file);
} else if (opts.single === true) {
  file = find(['/', '/index.html', '/index.htm']);
  send(file);
} else if (typeof opts.single === 'string') {
  file = find([opts.single]);
  send(file);
} else {
  // next() or 404
}
```

#### opts.ignores
Type: `false` or `Array<String | RegExp>`

Specify paths/patterns that should ignore the fallback behavior that `opts.single` provides.

By default, any asset-like path (URLs that end with an extension) will be ignored. This means that, for example, if `/foobar.jpg` is not found, a `404` response is sent instead of the `index.html` fallback.

Additionally, any `/.well-known/*` pathname ignores the fallback – as do all other dotfile requests when `opts.dotfiles` is enabled.

Any string value(s) will be passed through `new RegExp(value, 'i')` directly.

Finally, you may set `ignores: false` to disable ***all*** ignores, including the defaults. Put differently, this will fallback ***all*** unknown pathnames to your `index.html` (or custom `opts.single` value).

> **Important:** Only has an effect if `opts.single` is enabled.

#### opts.onNoMatch
Type: `Function`

A custom function to run if a file cannot be found for a given request. <br>By default, `sirv` will send a basic `(404) Not found` response.

The function receives the current `req <IncomingMessage>, res <ServerResponse>` pair for as its two arguments.

> **Note:** This won't run if a `next` callback has been provided to the middleware; see [`sirv`](#sirvdir-opts) description.

#### opts.setHeaders
Type: `Function`

A custom function to append or change any headers on the outgoing response. There is no default.

Its signature is `(res, pathname, stats)`, where `res` is the `ServerResponse`, `pathname` is incoming request path (stripped of queries), and `stats` is the file's result from [`fs.statSync`](https://nodejs.org/api/fs.html#fs_fs_statsync_path).


## License

MIT © [Luke Edwards](https://lukeed.com)


---

# sister ANSI [![Version](https://img.shields.io/npm/v/sisteransi.svg)](https://www.npmjs.com/package/sisteransi) [![Build Status](https://travis-ci.org/terkelg/sisteransi.svg?branch=master)](https://travis-ci.org/terkelg/sisteransi) [![Downloads](https://img.shields.io/npm/dm/sisteransi.svg)](https://www.npmjs.com/package/sisteransi)

> Ansi escape codes faster than you can say "[Bam bam](https://www.youtube.com/watch?v=OcaPu9JPenU)".

## Installation

```
npm install sisteransi
```


## Usage

```js
const ansi = require('sisteransi');
// or const { cursor } = require('sisteransi');

const p = str => process.stdout.write(str);

// move cursor to 2, 1
p(ansi.cursor.to(2, 1));

// to up, one down
p(ansi.cursor.up(2)+ansi.cursor.down(1));
```

## API

### cursor

#### to(x, y)
Set the absolute position of the cursor. `x0` `y0` is the top left of the screen.

#### move(x, y)
Set the position of the cursor relative to its current position.

#### up(count = 1)
Move cursor up a specific amount of rows. Default is `1`.

#### down(count = 1)
Move cursor down a specific amount of rows. Default is `1`.

#### forward(count = 1)
Move cursor forward a specific amount of rows. Default is `1`.

#### backward(count = 1)
Move cursor backward a specific amount of rows. Default is `1`.

#### nextLine(count = 1)
Move cursor to the next line a specific amount of lines. Default is `1`.

#### prevLine(count = 1)
Move cursor to the previous a specific amount of lines. Default is `1`.

#### left
Move cursor to the left side.

#### hide
Hide cursor.

#### show
Show cursor.

#### save

Save cursor position.

#### restore

Restore cursor position.


### scroll

#### up(count = 1)
Scroll display up a specific amount of lines. Default to `1`.

#### down(count = 1)
Scroll display down a specific amount of lines. Default to `1`.


### erase

#### screen
Erase the screen and move the cursor the top left position.

#### up(count = 1)
Erase the screen from the current line up to the top of the screen. Default to `1`.

#### down(count = 2)
Erase the screen from the current line down to the bottom of the screen. Default to `1`.

#### line
Erase the entire current line.

#### lineEnd
Erase from the current cursor position to the end of the current line.

#### lineStart
Erase from the current cursor position to the start of the current line.

#### lines(count)
Erase from the current cursor position up the specified amount of rows.


## Credit

This is a fork of [ansi-escapes](https://github.com/sindresorhus/ansi-escapes).


## License

MIT © [Terkel Gjervig](https://terkel.com)


---

# Changelog

## 7.1.2

- fix #425 via #426 thanks to @huntharo update streamToPromise to bubble up errors + jsDoc
- fix #415 thanks to @mohd-akram Fix circular dependency breaking Node.js 20.6
- non-breaking updates of dependent packages

## 7.1.1

- fix #378 exit code not set on parse failure. A proper error will be set on the stream now.
- fix #384 thanks @tomcek112 parseSitemapIndex not included in 7.1.0 release
- fix #356 thanks @vandres - SitemapIndexStream now has lastmodDateOnly
- Fix #375 thanks @huntharo parseSitemap and parseSitemapIndex uncatchable errors 
- Filter out null as well when writing XML thanks @huntharo #376

## 7.1.0

- bumped types dependency for node
- bumped all dev dependencies - includes some prettier changes
- package-lock updated to version 2

## 7.0.0

### [BREAKING]

- dropped support for Node 10, added support for Node 16
- removed deprecated createSitemapsAndIndex. use SitemapAndIndexStream or simpleSitemapAndIndex
- dropped deprecated `getSitemapStream` option for SitemapAndIndexStream that does not return a write stream
- fixed invalid documentation for #357

### non-breaking

- Added option to simplesitemap `publicBasePath`: allows the user to set the location of sitemap files hosted on the site fixes [#359]
- bumped dependencies

## 6.4.0

- added support for content_loc parsing #347 and uploader info attr
- added error handler option to sitemapstream #349 Thanks @marcoreni

## 6.3.6

- bump dependencies

## 6.3.5

- Add option to silence or redirect logs from parse #337
  - `new XMLToSitemapItemStream({ logger: false })` or 
  - `new XMLToSitemapItemStream({ level: ErrorLevel.SILENT })` or 
  - `new XMLToSitemapItemStream({ logger: (level, ...message) => your.custom.logger(...message) })`

## 6.3.4

- bump dependencies
- correct return type of xmllint. Was `Promise<null>` but actually returned `Promise<void>`
- add alternate option for lang, hreflang as that is the actual name of the printed attribute

## 6.3.3

- bump ts to 4
- change file reference in sitemap-index to include .gz fixes #334

## 6.3.2

- fix unreported timing issue in SitemapAndIndexStream uncovered in latest unit tests

## 6.3.1

- fix #331 incorrect type on sourceData in simpleSitemapAndIndex.

## 6.3.0

- simpleSitemap will create the dest directory if it doesn't exist
- allow user to not gzip fixes #322

## 6.2.0

- Add simplified interface for creating sitemaps and index
- fix bug where sitemap and index stream would not properly wait to emit finish event until all sitemaps had been written
- bump deps

## 6.1.7

- Improve documentation and error messaging on ending a stream too early #317
- bump dependencies

## 6.1.6

- support allow_embed #314
- bump dependencies

## 6.1.5

- performance improvement for streamToPromise #307

## 6.1.4

- remove stale files from dist #298
- Correct documentation on renamed XMLToSitemapOptions, XMLToSitemapItemStream #297
- bump node typedef to 14.0.1

## 6.1.3

- bump node types resolves #293

## 6.1.2

- bump node types resolves #290

## 6.1.1

- Fix #286 sitemapindex tag not closing for deprecated createSitemapsAndIndex

## 6.1.0

- Added back xslUrl option removed in 5.0.0

## 6.0.0

- removed xmlbuilder as a dependency
- added stronger validity checking on values supplied to sitemap
- Added the ability to turn off or add custom xml namespaces
- CLI and library now can accept a stream which will automatically write both the index and the sitemaps. See README for usage.

### 6.0.0 breaking changes

- renamed XMLToISitemapOptions to XMLToSitemapOptions
- various error messages changed.
- removed deprecated Sitemap and SitemapIndex classes
- replaced buildSitemapIndex with SitemapIndexStream
- Typescript: various types renamed or made more specific, removed I prefix
- Typescript: view_count is now exclusively a number
- Typescript: `price:type` and `price:resolution` are now more restrictive types
- sitemap parser now returns a sitemapItem array rather than a config object that could be passed to the now removed Sitemap class
- CLI no longer accepts multiple file arguments or a mixture of file and streams except as a part of a parameter eg. prepend

## 5.1.0

Fix for #255. Baidu does not like timestamp in its sitemap.xml, this adds an option to truncate lastmod

```js
new SitemapStream({ lastmodDateOnly: true });
```

## 5.0.1

Fix for issue #254.

```sh
warning: failed to load external entity "./schema/all.xsd"
Schemas parser error : Failed to locate the main schema resource at './schema/all.xsd'.
WXS schema ./schema/all.xsd failed to compile
```

## 5.0.0

### Streams

This release is heavily focused on converting the core methods of this library to use streams. Why? Overall its made the API ~20% faster and uses only 10% or less of the memory. Some tradeoffs had to be made as in their nature streams are operate on individual segments of data as opposed to the whole. For instance, the streaming interface does not support removal of sitemap items as it does not hold on to a sitemap item after its converted to XML. It should however be possible to create your own transform that filters out entries should you desire it. The existing synchronous interfaces will remain for this release at least. Do not be surprised if they go away in a future breaking release.

### Sitemap Index

This library interface has been overhauled to use streams internally. Although it would have been preferable to convert this to a stream as well, I could not think of an interface that wouldn't actually end up more complex or confusing. It may be altered in the near future to accept a stream in addition to a simple list.

### Misc

- runnable examples, some pulled straight from README have been added to the examples directory.
- createSitemapsIndex was renamed createSitemapsAndIndex to more accurately reflect its function. It now returns a promise that resolves to true or throws with an error.
- You can now add to existing sitemap.xml files via the cli using `npx sitemap --prepend existingSitemap.xml < listOfNewURLs.json.txt`

### 5.0 Breaking Changes

- Dropped support for mobile sitemap - Google appears to have deleted their dtd and all references to it, strongly implying that they do not want you to use it. As its absence now breaks the validator, it has been dropped.
- normalizeURL(url, XMLRoot, hostname) -> normalizeURL(url, hostname)
  - The second argument was unused and has been eliminated
- Support for Node 8 dropped - Node 8 is reaching its EOL December 2019
- xslURL is being dropped from all apis - styling xml is out of scope of this library.
- createSitemapIndex has been converted to a promised based api rather than callback.
- createSitemapIndex now gzips by default - pass gzip: false to disable
- cacheTime is being dropped from createSitemapIndex - This didn't actually cache the way it was written so this should be a non-breaking change in effect.
- SitemapIndex as a class has been dropped. The class did all its work on construction and there was no reason to hold on to it once you created it.
- The options for the cli have been overhauled
  - `--json` is now inferred
  - `--line-separated` has been flipped to `--single-line-json` to by default output options immediately compatible with feeding back into sitemap

## 4.1.1

Add a pretty print option to `toString(false)`
pass true pretty print

Add an xmlparser that will output a config that would generate that same file

  cli:
    use --parser to output the complete config --line-separated to print out line
    separated config compatible with the --json input option for cli

  lib: import parseSitemap and pass it a stream

## 4.0.2

Fix npx script error - needs the shebang

## 4.0.1

Validation functions which depend on xmllint will now warn if you do not have xmllint installed.

## 4.0.0

This release is geared around overhauling the public api for this library. Many
options have been introduced over the years and this has lead to some inconsistencies
that make the library hard to use. Most have been cleaned up but a couple notable
items remain, including the confusing names of buildSitemapIndex and createSitemapIndex

- A new experimental CLI
  - stream in a list of urls stream out xml
  - validate your generated sitemap
- Sitemap video item now supports id element
- Several schema errors have been cleaned up.
- Docs have been updated and streamlined.

### breaking changes

- lastmod option parses all ISO8601 date-only strings as being in UTC rather than local time
  - lastmodISO is deprecated as it is equivalent to lastmod
  - lastmodfile now includes the file's time as well
  - lastmodrealtime is no longer necessary
- The default export of sitemap lib is now just createSitemap
- Sitemap constructor now uses a object for its constructor

```js
  const { Sitemap } = require('sitemap');
  const siteMap = new Sitemap({
    urls = [],
    hostname: 'https://example.com', // optional
    cacheTime = 0,
    xslUrl,
    xmlNs,
    level = 'warn'
  })
```

- Sitemap no longer accepts a single string for its url
- Drop support for node 6
- Remove callback on toXML - This had no performance benefit
- Direct modification of urls property on Sitemap has been dropped. Use add/remove/contains
- When a Sitemap item is generated with invalid options it no longer throws by default
  - instead it console warns.
  - if you'd like to pre-verify your data the `validateSMIOptions` function is
  now available
  - To get the previous behavior pass level `createSitemap({...otheropts, level: 'throw' }) // ErrorLevel.THROW for TS users`

## 3.2.2

- revert https everywhere added in 3.2.0. xmlns is not url.
- adds alias for lastmod in the form of lastmodiso
- fixes bug in lastmod option for buildSitemapIndex where option would be overwritten if a lastmod option was provided with a single url
- fixes #201, fixes #203

## 3.2.1

- no really fixes ts errors for real this time
- fixes #193 in PR #198

## 3.2.0

- fixes #192, fixes #193 typescript errors
- correct types on player:loc and restriction:relationship types
- use https urls in xmlns

## 3.1.0

- fixes #187, #188 typescript errors
- adds support for full precision priority #176

## 3.0.0

- Converted project to typescript
- properly encode URLs #179
- updated core dependency

### 3.0 breaking changes

This will likely not break anyone's code but we're bumping to be safe

- root domain URLs are now suffixed with / (eg. `https://www.ya.ru` -> `https://www.ya.ru/`) This is a side-effect of properly encoding passed in URLs


---

# Contributor Covenant Code of Conduct

## Our Pledge

In the interest of fostering an open and welcoming environment, we as
contributors and maintainers pledge to making participation in our project and
our community a harassment-free experience for everyone, regardless of age, body
size, disability, ethnicity, sex characteristics, gender identity and expression,
level of experience, education, socio-economic status, nationality, personal
appearance, race, religion, or sexual identity and orientation.

## Our Standards

Examples of behavior that contributes to creating a positive environment
include:

* Using welcoming and inclusive language
* Being respectful of differing viewpoints and experiences
* Gracefully accepting constructive criticism
* Focusing on what is best for the community
* Showing empathy towards other community members

Examples of unacceptable behavior by participants include:

* The use of sexualized language or imagery and unwelcome sexual attention or
 advances
* Trolling, insulting/derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or electronic
 address, without explicit permission
* Other conduct which could reasonably be considered inappropriate in a
 professional setting

## Our Responsibilities

Project maintainers are responsible for clarifying the standards of acceptable
behavior and are expected to take appropriate and fair corrective action in
response to any instances of unacceptable behavior.

Project maintainers have the right and responsibility to remove, edit, or
reject comments, commits, code, wiki edits, issues, and other contributions
that are not aligned to this Code of Conduct, or to ban temporarily or
permanently any contributor for other behaviors that they deem inappropriate,
threatening, offensive, or harmful.

## Scope

This Code of Conduct applies both within project spaces and in public spaces
when an individual is representing the project or its community. Examples of
representing a project or community include using an official project e-mail
address, posting via an official social media account, or acting as an appointed
representative at an online or offline event. Representation of a project may be
further defined and clarified by project maintainers.

## Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported by contacting the project team at sitemap-cc@nimblerendition.com. All
complaints will be reviewed and investigated and will result in a response that
is deemed necessary and appropriate to the circumstances. The project team is
obligated to maintain confidentiality with regard to the reporter of an incident.
Further details of specific enforcement policies may be posted separately.

Project maintainers who do not follow or enforce the Code of Conduct in good
faith may face temporary or permanent repercussions as determined by other
members of the project's leadership.

## Attribution

This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html

[homepage]: https://www.contributor-covenant.org

For answers to common questions about this code of conduct, see
https://www.contributor-covenant.org/faq


---

# sitemap ![MIT License](https://img.shields.io/npm/l/sitemap)[![Build Status](https://travis-ci.org/ekalinin/sitemap.js.svg?branch=master)](https://travis-ci.org/ekalinin/sitemap.js)![Monthly Downloads](https://img.shields.io/npm/dm/sitemap)

**sitemap** is a high-level streaming sitemap-generating library/CLI that
makes creating [sitemap XML](http://www.sitemaps.org/) files easy. [What is a sitemap?](https://support.google.com/webmasters/answer/156184?hl=en&ref_topic=4581190)

## Table of Contents

- [Installation](#installation)
- [Generate a one time sitemap from a list of urls](#generate-a-one-time-sitemap-from-a-list-of-urls)
- [Example of using sitemap.js with](#serve-a-sitemap-from-a-server-and-periodically-update-it) [express](https://expressjs.com/)
- [Generating more than one sitemap](#create-sitemap-and-index-files-from-one-large-list)
- [Options you can pass](#options-you-can-pass)
- [Examples](#examples)
- [API](#api)
- [Maintainers](#maintainers)
- [License](#license)

## Installation

```sh
npm install --save sitemap
```

## Generate a one time sitemap from a list of urls

If you are just looking to take a giant list of URLs and turn it into some sitemaps, try out our CLI. The cli can also parse, update and validate existing sitemaps.

```sh
npx sitemap < listofurls.txt # `npx sitemap -h` for more examples and a list of options.
```

For programmatic one time generation of a sitemap try:

```js
  const { SitemapStream, streamToPromise } = require( 'sitemap' )
  const { Readable } = require( 'stream' )

  // An array with your links
  const links = [{ url: '/page-1/',  changefreq: 'daily', priority: 0.3  }]

  // Create a stream to write to
  const stream = new SitemapStream( { hostname: 'https://...' } )

  // Return a promise that resolves with your XML string
  return streamToPromise(Readable.from(links).pipe(stream)).then((data) =>
    data.toString()
  )
```

## Serve a sitemap from a server and periodically update it

Use this if you have less than 50 thousand urls. See SitemapAndIndexStream for if you have more.

```js
const express = require('express')
const { SitemapStream, streamToPromise } = require('sitemap')
const { createGzip } = require('zlib')
const { Readable } = require('stream')

const app = express()
let sitemap

app.get('/sitemap.xml', function(req, res) {
  res.header('Content-Type', 'application/xml');
  res.header('Content-Encoding', 'gzip');
  // if we have a cached entry send it
  if (sitemap) {
    res.send(sitemap)
    return
  }

  try {
    const smStream = new SitemapStream({ hostname: 'https://example.com/' })
    const pipeline = smStream.pipe(createGzip())

    // pipe your entries or directly write them.
    smStream.write({ url: '/page-1/',  changefreq: 'daily', priority: 0.3 })
    smStream.write({ url: '/page-2/',  changefreq: 'monthly',  priority: 0.7 })
    smStream.write({ url: '/page-3/'})    // changefreq: 'weekly',  priority: 0.5
    smStream.write({ url: '/page-4/',   img: "http://urlTest.com" })
    /* or use
    Readable.from([{url: '/page-1'}...]).pipe(smStream)
    if you are looking to avoid writing your own loop.
    */

    // cache the response
    streamToPromise(pipeline).then(sm => sitemap = sm)
    // make sure to attach a write stream such as streamToPromise before ending
    smStream.end()
    // stream write the response
    pipeline.pipe(res).on('error', (e) => {throw e})
  } catch (e) {
    console.error(e)
    res.status(500).end()
  }
})

app.listen(3000, () => {
  console.log('listening')
});
```

## Create sitemap and index files from one large list

If you know you are definitely going to have more than 50,000 urls in your sitemap, you can use this slightly more complex interface to create a new sitemap every 45,000 entries and add that file to a sitemap index.

```js
const { createReadStream, createWriteStream } = require('fs');
const { resolve } = require('path');
const { createGzip } = require('zlib')
const {
  simpleSitemapAndIndex,
  lineSeparatedURLsToSitemapOptions
} = require('sitemap')

// writes sitemaps and index out to the destination you provide.
simpleSitemapAndIndex({
  hostname: 'https://example.com',
  destinationDir: './',
  sourceData: lineSeparatedURLsToSitemapOptions(
    createReadStream('./your-data.json.txt')
  ),
  // or (only works with node 10.17 and up)
  sourceData: [{ url: '/page-1/', changefreq: 'daily'}, ...],
  // or
  sourceData: './your-data.json.txt',
}).then(() => {
  // Do follow up actions
})
```

Want to customize that?

```js
const { createReadStream, createWriteStream } = require('fs');
const { resolve } = require('path');
const { createGzip } = require('zlib')
const { Readable } = require('stream')
const {
  SitemapAndIndexStream,
  SitemapStream,
  lineSeparatedURLsToSitemapOptions
} = require('sitemap')

const sms = new SitemapAndIndexStream({
  limit: 50000, // defaults to 45k
  lastmodDateOnly: false, // print date not time
  // SitemapAndIndexStream will call this user provided function every time
  // it needs to create a new sitemap file. You merely need to return a stream
  // for it to write the sitemap urls to and the expected url where that sitemap will be hosted
  getSitemapStream: (i) => {
    const sitemapStream = new SitemapStream({ hostname: 'https://example.com' });
    // if your server automatically serves sitemap.xml.gz when requesting sitemap.xml leave this line be
    // otherwise you will need to add .gz here and remove it a couple lines below so that both the index 
    // and the actual file have a .gz extension
    const path = `./sitemap-${i}.xml`; 

    const ws = sitemapStream
      .pipe(createGzip()) // compress the output of the sitemap
      .pipe(createWriteStream(resolve(path + '.gz'))); // write it to sitemap-NUMBER.xml

    return [new URL(path, 'https://example.com/subdir/').toString(), sitemapStream, ws];
  },
});

// when reading from a file
lineSeparatedURLsToSitemapOptions(
  createReadStream('./your-data.json.txt')
)
.pipe(sms)
.pipe(createGzip())
.pipe(createWriteStream(resolve('./sitemap-index.xml.gz')));

// or reading straight from an in-memory array
sms
.pipe(createGzip())
.pipe(createWriteStream(resolve('./sitemap-index.xml.gz')));

const arrayOfSitemapItems = [{ url: '/page-1/', changefreq: 'daily'}, ...]
Readable.from(arrayOfSitemapItems).pipe(sms) // available as of node 10.17.0
// or
arrayOfSitemapItems.forEach(item => sms.write(item))
sms.end() // necessary to let it know you've got nothing else to write
```

### Options you can pass

```js
const { SitemapStream, streamToPromise } = require('sitemap');
const smStream = new SitemapStream({
  hostname: 'http://www.mywebsite.com',
  xslUrl: "https://example.com/style.xsl",
  lastmodDateOnly: false, // print date not time
  xmlns: { // trim the xml namespace
    news: true, // flip to false to omit the xml namespace for news
    xhtml: true,
    image: true,
    video: true,
    custom: [
      'xsi:schemaLocation="http://www.sitemaps.org/schemas/sitemap/0.9 http://www.sitemaps.org/schemas/sitemap/0.9/sitemap.xsd"',
      'xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"',
    ],
  }
 })
// coalesce stream to value
// alternatively you can pipe to another stream
streamToPromise(smStream).then(console.log)

smStream.write({
  url: '/page1',
  changefreq: 'weekly',
  priority: 0.8, // A hint to the crawler that it should prioritize this over items less than 0.8
})

// each sitemap entry supports many options
// See [Sitemap Item Options](./api.md#sitemap-item-options) below for details
smStream.write({
  url: 'http://test.com/page-1/',
  img: [
    {
      url: 'http://test.com/img1.jpg',
      caption: 'An image',
      title: 'The Title of Image One',
      geoLocation: 'London, United Kingdom',
      license: 'https://creativecommons.org/licenses/by/4.0/'
    },
    {
      url: 'http://test.com/img2.jpg',
      caption: 'Another image',
      title: 'The Title of Image Two',
      geoLocation: 'London, United Kingdom',
      license: 'https://creativecommons.org/licenses/by/4.0/'
    }
  ],
  video: [
    {
      thumbnail_loc: 'http://test.com/tmbn1.jpg',
      title: 'A video title',
      description: 'This is a video'
    },
    {
      thumbnail_loc: 'http://test.com/tmbn2.jpg',
      title: 'A video with an attribute',
      description: 'This is another video',
      'player_loc': 'http://www.example.com/videoplayer.mp4?video=123',
      'player_loc:autoplay': 'ap=1',
      'player_loc:allow_embed': 'yes'
    }
  ],
  links: [
    { lang: 'en', url: 'http://test.com/page-1/' },
    { lang: 'ja', url: 'http://test.com/page-1/ja/' }
  ],
  androidLink: 'android-app://com.company.test/page-1/',
  news: {
    publication: {
      name: 'The Example Times',
      language: 'en'
    },
    genres: 'PressRelease, Blog',
    publication_date: '2008-12-23',
    title: 'Companies A, B in Merger Talks',
    keywords: 'business, merger, acquisition, A, B',
    stock_tickers: 'NASDAQ:A, NASDAQ:B'
  }
})
// indicate there is nothing left to write
smStream.end()
```

## Examples

For more examples see the [examples directory](./examples/)

## API

Full API docs can be found [here](./api.md)

## Maintainers

- [@ekalinin](https://github.com/ekalinin)
- [@derduher](https://github.com/derduher)

## License

See [LICENSE](https://github.com/ekalinin/sitemap.js/blob/master/LICENSE) file.


---

# API

- [API](#api)
  - [SitemapStream](#sitemapstream)
  - [XMLToSitemapItemStream](#xmltositemapitemstream)
  - [sitemapAndIndexStream](#sitemapandindexstream)
  - [createSitemapsAndIndex](#createsitemapsandindex)
  - [SitemapIndexStream](#sitemapindexstream)
  - [xmlLint](#xmllint)
  - [parseSitemap](#parsesitemap)
  - [lineSeparatedURLsToSitemapOptions](#lineseparatedurlstositemapoptions)
  - [streamToPromise](#streamtopromise)
  - [ObjectStreamToJSON](#objectstreamtojson)
  - [SitemapItemStream](#sitemapitemstream)
  - [Sitemap Item Options](#sitemap-item-options)
  - [SitemapImage](#sitemapimage)
  - [VideoItem](#videoitem)
  - [ILinkItem](#ilinkitem)
  - [NewsItem](#newsitem)

## SitemapStream

A [Transform](https://nodejs.org/api/stream.html#stream_implementing_a_transform_stream) for turning a [Readable stream](https://nodejs.org/api/stream.html#stream_readable_streams) of either [SitemapItemOptions](#sitemap-item-options) or url strings into a Sitemap. The readable stream it transforms **must** be in object mode.

```javascript
const { SitemapStream } = require('sitemap')
const sms = new SitemapStream({
  hostname: 'https://example.com', // optional only necessary if your paths are relative
  lastmodDateOnly: false // defaults to false, flip to true for baidu
  xmlns: { // XML namespaces to turn on - all by default
    news: true,
    xhtml: true,
    image: true,
    video: true,
    // custom: ['xmlns:custom="https://example.com"']
  },
  errorHandler: undefined // defaults to a standard errorLogger that logs to console or throws if the errorLevel is set to throw
})
const readable = // a readable stream of objects
readable.pipe(sms).pipe(process.stdout)
```

## XMLToSitemapItemStream

Takes a stream of xml and transforms it into a stream of SitemapOptions.
Use this to parse existing sitemaps into config options compatible with this library

```javascript
const { createReadStream, createWriteStream } = require('fs');
const { XMLToSitemapItemStream, ObjectStreamToJSON } = require('sitemap');

createReadStream('./some/sitemap.xml')
// turn the xml into sitemap option item options
.pipe(new XMLToSitemapItemStream({
  // optional
  level: ErrorLevel.Warn // default is WARN pass Silent to silence
  logger: false // default is console log, pass false as another way to silence or your own custom logger
}))
// convert the object stream to JSON
.pipe(new ObjectStreamToJSON())
// write the library compatible options to disk
.pipe(createWriteStream('./sitemapOptions.json'))
```

## sitemapAndIndexStream

Use this to take a stream which may go over the max of 50000 items and split it into an index and sitemaps.
SitemapAndIndexStream consumes a stream of urls and streams out index entries while writing individual urls to the streams you give it.
Provide it with a function which when provided with a index returns a url where the sitemap will ultimately be hosted and a stream to write the current sitemap to. This function will be called everytime the next item in the stream would exceed the provided limit.

```js
const { createReadStream, createWriteStream } = require('fs');
const { resolve } = require('path');
const { createGzip } = require('zlib')
const {
  SitemapAndIndexStream,
  SitemapStream,
  lineSeparatedURLsToSitemapOptions
} = require('sitemap')

const sms = new SitemapAndIndexStream({
  limit: 10000, // defaults to 45k
  // SitemapAndIndexStream will call this user provided function every time
  // it needs to create a new sitemap file. You merely need to return a stream
  // for it to write the sitemap urls to and the expected url where that sitemap will be hosted
  getSitemapStream: (i) => {
    const sitemapStream = new SitemapStream();
    const path = `./sitemap-${i}.xml`;

    const ws = sitemapStream
      .pipe(createGzip()) // compress the output of the sitemap
      .pipe(createWriteStream(resolve(path + '.gz'))); // write it to sitemap-NUMBER.xml

    return [new URL(path, 'https://example.com/subdir/').toString(), sitemapStream, ws];
  },
});

lineSeparatedURLsToSitemapOptions(
  createReadStream('./your-data.json.txt')
)
.pipe(sms)
.pipe(createGzip())
.pipe(createWriteStream(resolve('./sitemap-index.xml.gz')));
```

## SitemapIndexStream

Writes a sitemap index when given a stream urls.

```js
/**
 * writes the following
 * <?xml version="1.0" encoding="UTF-8"?>
   <sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
   <sitemap>
      <loc>https://example.com/</loc>
   </sitemap>
   <sitemap>
      <loc>https://example.com/2</loc>
   </sitemap>
 */
const smis = new SitemapIndexStream({level: 'warn'})
smis.write({url: 'https://example.com/'})
smis.write({url: 'https://example.com/2'})
smis.pipe(writestream)
smis.end()
```

## xmlLint

Resolve or reject depending on whether the passed in xml is a valid sitemap.
This is just a wrapper around the xmlLint command line tool and thus requires
xmlLint.

```js
const { createReadStream } = require('fs')
const { xmlLint } = require('sitemap')
xmlLint(createReadStream('./example.xml')).then(
  () => console.log('xml is valid'),
  ([err, stderr]) => console.error('xml is invalid', stderr)
)
```

## parseSitemap

Read xml and resolve with the configuration that would produce it or reject with
an error

```js
const { createReadStream } = require('fs')
const { parseSitemap, createSitemap } = require('sitemap')
parseSitemap(createReadStream('./example.xml')).then(
  // produces the same xml
  // you can, of course, more practically modify it or store it
  (xmlConfig) => console.log(createSitemap(xmlConfig).toString()),
  (err) => console.log(err)
)
```

## lineSeparatedURLsToSitemapOptions

Takes a stream of urls or sitemapoptions likely from fs.createReadStream('./path') and returns an object stream of sitemap items.

## streamToPromise

Takes a stream returns a promise that resolves when stream emits finish.

```javascript
const { streamToPromise, SitemapStream } = require('sitemap')
const sitemap = new SitemapStream({ hostname: 'http://example.com' });
sitemap.write({ url: '/page-1/', changefreq: 'daily', priority: 0.3 })
sitemap.end()
streamToPromise(sitemap).then(buffer => console.log(buffer.toString())) // emits the full sitemap
```

## ObjectStreamToJSON

A Transform that converts a stream of objects into a JSON Array or a line separated stringified JSON.

- @param [lineSeparated=false] whether to separate entries by a new line or comma

```javascript
const stream = Readable.from([{a: 'b'}])
  .pipe(new ObjectStreamToJSON())
  .pipe(process.stdout)
stream.end()
// prints {"a":"b"}
```

## SitemapItemStream

Takes a stream of SitemapItemOptions and spits out xml for each

```js
// writes <url><loc>https://example.com</loc><url><url><loc>https://example.com/2</loc><url>
const smis = new SitemapItemStream({level: 'warn'})
smis.pipe(writestream)
smis.write({url: 'https://example.com', img: [], video: [], links: []})
smis.write({url: 'https://example.com/2', img: [], video: [], links: []})
smis.end()
```

## Sitemap Item Options

|Option|Type|eg|Description|
|------|----|--|-----------|
|url|string|`http://example.com/some/path`|The only required property for every sitemap entry|
|lastmod|string|'2019-07-29' or '2019-07-22T05:58:37.037Z'|When the page we as last modified use the W3C Datetime ISO8601 subset <https://www.sitemaps.org/protocol.html#xmlTagDefinitions>|
|changefreq|string|'weekly'|How frequently the page is likely to change. This value provides general information to search engines and may not correlate exactly to how often they crawl the page. Please note that the value of this tag is considered a hint and not a command. See <https://www.sitemaps.org/protocol.html#xmlTagDefinitions> for the acceptable values|
|priority|number|0.6|The priority of this URL relative to other URLs on your site. Valid values range from 0.0 to 1.0. This value does not affect how your pages are compared to pages on other sites—it only lets the search engines know which pages you deem most important for the crawlers. The default priority of a page is 0.5. <https://www.sitemaps.org/protocol.html#xmlTagDefinitions>|
|img|object[]|see [#ISitemapImage](#ISitemapImage)|<https://support.google.com/webmasters/answer/178636?hl=en&ref_topic=4581190>|
|video|object[]|see [#IVideoItem](#IVideoItem)|<https://support.google.com/webmasters/answer/80471?hl=en&ref_topic=4581190>|
|links|object[]|see [#ILinkItem](#ILinkItem)|Tell search engines about localized versions <https://support.google.com/webmasters/answer/189077>|
|news|object|see [#INewsItem](#INewsItem)|<https://support.google.com/webmasters/answer/74288?hl=en&ref_topic=4581190>|
|ampLink|string|`http://ampproject.org/article.amp.html`||
|cdata|boolean|true|wrap url in cdata xml escape|

## SitemapImage

Sitemap image
<https://support.google.com/webmasters/answer/178636?hl=en&ref_topic=4581190>

|Option|Type|eg|Description|
|------|----|--|-----------|
|url|string|`http://example.com/image.jpg`|The URL of the image.|
|caption|string - optional|'Here we did the stuff'|The caption of the image.|
|title|string - optional|'Star Wars EP IV'|The title of the image.|
|geoLocation|string - optional|'Limerick, Ireland'|The geographic location of the image.|
|license|string - optional|`http://example.com/license.txt`|A URL to the license of the image.|

## VideoItem

Sitemap video. <https://support.google.com/webmasters/answer/80471?hl=en&ref_topic=4581190>

|Option|Type|eg|Description|
|------|----|--|-----------|
|thumbnail_loc|string|`"https://rtv3-img-roosterteeth.akamaized.net/store/0e841100-289b-4184-ae30-b6a16736960a.jpg/sm/thumb3.jpg"`|A URL pointing to the video thumbnail image file|
|title|string|'2018:E6 - GoldenEye: Source'|The title of the video. |
|description|string|'We play gun game in GoldenEye: Source with a good friend of ours. His name is Gruchy. Dan Gruchy.'|A description of the video. Maximum 2048 characters. |
|content_loc|string - optional|`"http://streamserver.example.com/video123.mp4"`|A URL pointing to the actual video media file. Should be one of the supported formats. HTML is not a supported format. Flash is allowed, but no longer supported on most mobile platforms, and so may be indexed less well. Must not be the same as the `<loc>` URL.|
|player_loc|string - optional|`"https://roosterteeth.com/embed/rouletsplay-2018-goldeneye-source"`|A URL pointing to a player for a specific video. Usually this is the information in the src element of an `<embed>` tag. Must not be the same as the `<loc>` URL|
|'player_loc:autoplay'|string - optional|'ap=1'|a string the search engine can append as a query param to enable automatic playback|
|'player_loc:allow_embed'|boolean - optional|'yes'|Whether the search engine can embed the video in search results. Allowed values are yes or no.|
|duration|number - optional| 600| duration of video in seconds|
|expiration_date| string - optional|"2012-07-16T19:20:30+08:00"|The date after which the video will no longer be available|
|view_count|number - optional|'21000000000'|The number of times the video has been viewed.|
|publication_date| string - optional|"2018-04-27T17:00:00.000Z"|The date the video was first published, in W3C format.|
|category|string - optional|"Baking"|A short description of the broad category that the video belongs to. This is a string no longer than 256 characters.|
|restriction|string - optional|"IE GB US CA"|Whether to show or hide your video in search results from specific countries.|
|restriction:relationship| string - optional|"deny"||
|gallery_loc| string - optional|`"https://roosterteeth.com/series/awhu"`|Currently not used.|
|gallery_loc:title|string - optional|"awhu series page"|Currently not used.|
|price|string - optional|"1.99"|The price to download or view the video. Omit this tag for free videos.|
|price:resolution|string - optional|"HD"|Specifies the resolution of the purchased version. Supported values are hd and sd.|
|price:currency| string - optional|"USD"|currency [Required] Specifies the currency in ISO 4217 format.|
|price:type|string - optional|"rent"|type [Optional] Specifies the purchase option. Supported values are rent and own. |
|uploader|string - optional|"GrillyMcGrillerson"|The video uploader's name. Only one <video:uploader> is allowed per video. String value, max 255 characters.|
|platform|string - optional|"tv"|Whether to show or hide your video in search results on specified platform types. This is a list of space-delimited platform types. See <https://support.google.com/webmasters/answer/80471?hl=en&ref_topic=4581190> for more detail|
|platform:relationship|string 'Allow'\|'Deny' - optional|'Allow'||
|id|string - optional|||
|tag|string[] - optional|['Baking']|An arbitrary string tag describing the video. Tags are generally very short descriptions of key concepts associated with a video or piece of content.|
|rating|number - optional|2.5|The rating of the video. Supported values are float numbers|
|family_friendly|string 'YES'\|'NO' - optional|'YES'||
|requires_subscription|string 'YES'\|'NO' - optional|'YES'|Indicates whether a subscription (either paid or free) is required to view the video. Allowed values are yes or no.|
|live|string 'YES'\|'NO' - optional|'NO'|Indicates whether the video is a live stream. Supported values are yes or no.|

## ILinkItem

<https://support.google.com/webmasters/answer/189077>

|Option|Type|eg|Description|
|------|----|--|-----------|
|lang|string|'en'||
|url|string|`'http://example.com/en/'`||

## NewsItem

<https://support.google.com/webmasters/answer/74288?hl=en&ref_topic=4581190>

|Option|Type|eg|Description|
|------|----|--|-----------|
|access|string - 'Registration' \| 'Subscription'| 'Registration' - optional||
|publication| object|see following options||
|publication['name']| string|'The Example Times'|The `<name>` is the name of the news publication. It must exactly match the name as it appears on your articles on news.google.com, except for anything in parentheses.|
|publication['language']|string|'en'|The `<language>` is the language of your publication. Use an ISO 639 language code (2 or 3 letters).|
|genres|string - optional|'PressRelease, Blog'||
|publication_date|string|'2008-12-23'|Article publication date in W3C format, using either the "complete date" (YYYY-MM-DD) format or the "complete date plus hours, minutes, and seconds"|
|title|string|'Companies A, B in Merger Talks'|The title of the news article.|
|keywords|string - optional|"business, merger, acquisition, A, B"||
|stock_tickers|string - optional|"NASDAQ:A, NASDAQ:B"||


---

# Installation
> `npm install --save @types/node`

# Summary
This package contains type definitions for Node.js (https://nodejs.org/).

# Details
Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/node/v17.

### Additional Details
 * Last updated: Wed, 15 Jun 2022 23:01:35 GMT
 * Dependencies: none
 * Global values: `AbortController`, `AbortSignal`, `__dirname`, `__filename`, `console`, `exports`, `gc`, `global`, `module`, `process`, `require`, `structuredClone`

# Credits
These definitions were written by [Microsoft TypeScript](https://github.com/Microsoft), [DefinitelyTyped](https://github.com/DefinitelyTyped), [Alberto Schiabel](https://github.com/jkomyno), [Alvis HT Tang](https://github.com/alvis), [Andrew Makarov](https://github.com/r3nya), [Benjamin Toueg](https://github.com/btoueg), [Chigozirim C.](https://github.com/smac89), [David Junger](https://github.com/touffy), [Deividas Bakanas](https://github.com/DeividasBakanas), [Eugene Y. Q. Shen](https://github.com/eyqs), [Hannes Magnusson](https://github.com/Hannes-Magnusson-CK), [Huw](https://github.com/hoo29), [Kelvin Jin](https://github.com/kjin), [Klaus Meinhardt](https://github.com/ajafff), [Lishude](https://github.com/islishude), [Mariusz Wiktorczyk](https://github.com/mwiktorczyk), [Mohsen Azimi](https://github.com/mohsen1), [Nicolas Even](https://github.com/n-e), [Nikita Galkin](https://github.com/galkin), [Parambir Singh](https://github.com/parambirs), [Sebastian Silbermann](https://github.com/eps1lon), [Simon Schick](https://github.com/SimonSchick), [Thomas den Hollander](https://github.com/ThomasdenH), [Wilco Bakker](https://github.com/WilcoBakker), [wwwy3y3](https://github.com/wwwy3y3), [Samuel Ainsworth](https://github.com/samuela), [Kyle Uehlein](https://github.com/kuehlein), [Thanik Bhongbhibhat](https://github.com/bhongy), [Marcin Kopacz](https://github.com/chyzwar), [Trivikram Kamat](https://github.com/trivikr), [Junxiao Shi](https://github.com/yoursunny), [Ilia Baryshnikov](https://github.com/qwelias), [ExE Boss](https://github.com/ExE-Boss), [Piotr Błażejewicz](https://github.com/peterblazejewicz), [Anna Henningsen](https://github.com/addaleax), [Victor Perin](https://github.com/victorperin), [Yongsheng Zhang](https://github.com/ZYSzys), [NodeJS Contributors](https://github.com/NodeJS), [Linus Unnebäck](https://github.com/LinusU), and [wafuwafu13](https://github.com/wafuwafu13).


---

# skin-tone [![Build Status](https://travis-ci.org/sindresorhus/skin-tone.svg?branch=master)](https://travis-ci.org/sindresorhus/skin-tone)

> Change the skin tone of an emoji 👌👌🏻👌🏼👌🏽👌🏾👌🏿

The [Fitzpatrick scale](https://en.wikipedia.org/wiki/Fitzpatrick_scale#Unicode) is used to specify skin tones for emoji characters which represent humans.


## Install

```
$ npm install skin-tone
```


## Usage

```js
const skinTone = require('skin-tone');

skinTone('👍', 'brown');
//=> '👍🏾'

skinTone('👍', 'white');
//=> '👍🏻'

// can also remove skin tone
skinTone('👍🏾', 'none');
//=> '👍'

// just passes it through when not supported
skinTone('🦄', 'darkBrown');
//=> '🦄'
```


## API

### skinTone(emoji, tone)

#### emoji

Type: `string`

Emoji to modify.

#### tone

Type: `'none' | 'white' | 'creamWhite' | 'lightBrown' | 'brown' | 'darkBrown'`

Skin tone to use for `emoji`.

- `'none'`       :      *(Removes skin tone)*
- `'white'`      : 🏻   *(Fitzpatrick Type-1–2)*
- `'creamWhite'` : 🏼   *(Fitzpatrick Type-3)*
- `'lightBrown'` : 🏽   *(Fitzpatrick Type-4)*
- `'brown'`      : 🏾   *(Fitzpatrick Type-5)*
- `'darkBrown'`  : 🏿   *(Fitzpatrick Type-6)*

Skin tone to use for `emoji`.


## License

MIT © [Sindre Sorhus](https://sindresorhus.com)


---

# slash [![Build Status](https://travis-ci.org/sindresorhus/slash.svg?branch=master)](https://travis-ci.org/sindresorhus/slash)

> Convert Windows backslash paths to slash paths: `foo\\bar` ➔ `foo/bar`

[Forward-slash paths can be used in Windows](http://superuser.com/a/176395/6877) as long as they're not extended-length paths and don't contain any non-ascii characters.

This was created since the `path` methods in Node.js outputs `\\` paths on Windows.


## Install

```
$ npm install slash
```


## Usage

```js
const path = require('path');
const slash = require('slash');

const string = path.join('foo', 'bar');
// Unix    => foo/bar
// Windows => foo\\bar

slash(string);
// Unix    => foo/bar
// Windows => foo/bar
```


## API

### slash(path)

Type: `string`

Accepts a Windows backslash path and returns a path with forward slashes.


## License

MIT © [Sindre Sorhus](https://sindresorhus.com)


---

# Snake Case

[![NPM version][npm-image]][npm-url]
[![NPM downloads][downloads-image]][downloads-url]
[![Bundle size][bundlephobia-image]][bundlephobia-url]

> Transform into a lower case string with underscores between words.

## Installation

```
npm install snake-case --save
```

## Usage

```js
import { snakeCase } from "snake-case";

snakeCase("string"); //=> "string"
snakeCase("dot.case"); //=> "dot_case"
snakeCase("PascalCase"); //=> "pascal_case"
snakeCase("version 1.2.10"); //=> "version_1_2_10"
```

The function also accepts [`options`](https://github.com/blakeembrey/change-case#options).

## License

MIT

[npm-image]: https://img.shields.io/npm/v/snake-case.svg?style=flat
[npm-url]: https://npmjs.org/package/snake-case
[downloads-image]: https://img.shields.io/npm/dm/snake-case.svg?style=flat
[downloads-url]: https://npmjs.org/package/snake-case
[bundlephobia-image]: https://img.shields.io/bundlephobia/minzip/snake-case.svg
[bundlephobia-url]: https://bundlephobia.com/result?p=snake-case


---

[![NPM version](https://badge.fury.io/js/sockjs.svg)](http://badge.fury.io/js/sockjs)

SockJS family:

  * [SockJS-client](https://github.com/sockjs/sockjs-client) JavaScript client library
  * [SockJS-node](https://github.com/sockjs/sockjs-node) Node.js server
  * [SockJS-erlang](https://github.com/sockjs/sockjs-erlang) Erlang server
  * [SockJS-tornado](https://github.com/MrJoes/sockjs-tornado) Python/Tornado server
  * [vert.x](https://github.com/eclipse/vert.x) Java/vert.x server

Work in progress:

  * [SockJS-ruby](https://github.com/nyarly/sockjs-ruby)
  * [SockJS-netty](https://github.com/cgbystrom/sockjs-netty)
  * [SockJS-gevent](https://github.com/sdiehl/sockjs-gevent) ([and a fork](https://github.com/njoyce/sockjs-gevent))
  * [pyramid-SockJS](https://github.com/fafhrd91/pyramid_sockjs)
  * [wildcloud-websockets](https://github.com/wildcloud/wildcloud-websockets)
  * [SockJS-cyclone](https://github.com/flaviogrossi/sockjs-cyclone)
  * [SockJS-twisted](https://github.com/Fugiman/sockjs-twisted/)
  * [wai-SockJS](https://github.com/Palmik/wai-sockjs)
  * [SockJS-perl](https://github.com/vti/sockjs-perl)
  * [SockJS-go](https://github.com/igm/sockjs-go/)

What is SockJS?
===============

SockJS is a JavaScript library (for browsers) that provides a WebSocket-like
object. SockJS gives you a coherent, cross-browser, Javascript API
which creates a low latency, full duplex, cross-domain communication
channel between the browser and the web server, with WebSockets or without.
This necessitates the use of a server, which this is one version of, for Node.js.


SockJS-node server
==================

SockJS-node is a Node.js server side counterpart of
[SockJS-client browser library](https://github.com/sockjs/sockjs-client)
written in CoffeeScript.

To install `sockjs-node` run:

    npm install sockjs

A simplified echo SockJS server could look more or less like:

```javascript
var http = require('http');
var sockjs = require('sockjs');

var echo = sockjs.createServer();
echo.on('connection', function(conn) {
    conn.on('data', function(message) {
        conn.write(message);
    });
    conn.on('close', function() {});
});

var server = http.createServer();
echo.installHandlers(server, {prefix:'/echo'});
server.listen(9999, '0.0.0.0');
```

(Take look at
[examples](https://github.com/sockjs/sockjs-node/tree/master/examples/echo)
directory for a complete version.)

Subscribe to
[SockJS mailing list](https://groups.google.com/forum/#!forum/sockjs) for
discussions and support.


SockJS-node API
---------------

The API design is based on common Node APIs like the
[Streams API](http://nodejs.org/docs/v0.5.8/api/streams.html) or the
[Http.Server API](http://nodejs.org/docs/v0.5.8/api/http.html#http.Server).

### Server class

SockJS module is generating a `Server` class, similar to
[Node.js http.createServer](http://nodejs.org/docs/v0.5.8/api/http.html#http.createServer)
module.

```javascript
var sockjs_server = sockjs.createServer(options);
```

Where `options` is a hash which can contain:

<dl>
<dt>sockjs_url (string)</dt>
<dd>Transports which don't support cross-domain communication natively
   ('eventsource' to name one) use an iframe trick. A simple page is
   served from the SockJS server (using its foreign domain) and is
   placed in an invisible iframe. Code run from this iframe doesn't
   need to worry about cross-domain issues, as it's being run from
   domain local to the SockJS server. This iframe also does need to
   load SockJS javascript client library, and this option lets you specify
   its url (if you're unsure, point it to
   <a href="https://cdn.jsdelivr.net/npm/sockjs-client@1/dist/sockjs.min.js">
   the latest minified SockJS client release</a>, this is the default).
   You must explicitly specify this url on the server side for security
   reasons - we don't want the possibility of running any foreign
   javascript within the SockJS domain (aka cross site scripting attack).
   Also, sockjs javascript library is probably already cached by the
   browser - it makes sense to reuse the sockjs url you're using in
   normally.</dd>

<dt>prefix (string regex)</dt>
<dd>A url prefix for the server. All http requests which paths begins
   with selected prefix will be handled by SockJS. All other requests
   will be passed through, to previously registered handlers.</dd>

<dt>response_limit (integer)</dt>
<dd>Most streaming transports save responses on the client side and
   don't free memory used by delivered messages. Such transports need
   to be garbage-collected once in a while. `response_limit` sets
   a minimum number of bytes that can be send over a single http streaming
   request before it will be closed. After that client needs to open
   new request. Setting this value to one effectively disables
   streaming and will make streaming transports to behave like polling
   transports. The default value is 128K.</dd>

<dt>websocket (boolean)</dt>
<dd>Some load balancers don't support websockets. This option can be used
   to disable websockets support by the server. By default websockets are
   enabled.</dd>

<dt>jsessionid (boolean or function)</dt>
<dd>Some hosting providers enable sticky sessions only to requests that
  have JSESSIONID cookie set. This setting controls if the server should
  set this cookie to a dummy value. By default setting JSESSIONID cookie
  is disabled. More sophisticated behaviour can be achieved by supplying
  a function.</dd>

<dt>log (function(severity, message))</dt>
<dd>It's quite useful, especially for debugging, to see some messages
  printed by a SockJS-node library. This is done using this `log`
  function, which is by default set to `console.log`. If this
  behaviour annoys you for some reason, override `log` setting with a
  custom handler.  The following `severities` are used: `debug`
  (miscellaneous logs), `info` (requests logs), `error` (serious
  errors, consider filing an issue).</dd>

<dt>heartbeat_delay (milliseconds)</dt>
<dd>In order to keep proxies and load balancers from closing long
  running http requests we need to pretend that the connection is
  active and send a heartbeat packet once in a while. This setting
  controls how often this is done. By default a heartbeat packet is
  sent every 25 seconds.  </dd>

<dt>disconnect_delay (milliseconds)</dt>
<dd>The server sends a `close` event when a client receiving
  connection have not been seen for a while. This delay is configured
  by this setting. By default the `close` event will be emitted when a
  receiving connection wasn't seen for 5 seconds.  </dd>

<dt>disable_cors (boolean)</dt>
<dd>Enabling this option will prevent
  <a href="https://en.wikipedia.org/wiki/Cross-origin_resource_sharing">CORS</a>
  headers from being included in the HTTP response. Can be used when the
  sockjs client is known to be connecting from the same origin as the 
  sockjs server.</dd>
</dl>


### Server instance

Once you have create `Server` instance you can hook it to the
[http.Server instance](http://nodejs.org/docs/v0.5.8/api/http.html#http.createServer).

```javascript
var http_server = http.createServer();
sockjs_server.installHandlers(http_server, options);
http_server.listen(...);
```

Where `options` can overshadow options given when creating `Server`
instance.

`Server` instance is an
[EventEmitter](http://nodejs.org/docs/v0.4.10/api/events.html#events.EventEmitter),
and emits following event:

<dl>
<dt>Event: connection (connection)</dt>
<dd>A new connection has been successfully opened.</dd>
</dl>

All http requests that don't go under the path selected by `prefix`
will remain unanswered and will be passed to previously registered
handlers. You must install your custom http handlers before calling
`installHandlers`.

### Connection instance

A `Connection` instance supports
[Node Stream API](http://nodejs.org/docs/v0.5.8/api/streams.html) and
has following methods and properties:

<dl>
<dt>Property: readable (boolean)</dt>
<dd>Is the stream readable?</dd>

<dt>Property: writable (boolean)</dt>
<dd>Is the stream writable?</dd>

<dt>Property: remoteAddress (string)</dt>
<dd>Last known IP address of the client.</dd>

<dt>Property: remotePort (number)</dt>
<dd>Last known port number of the client.</dd>

<dt>Property: address (object)</dt>
<dd>Hash with 'address' and 'port' fields.</dd>

<dt>Property: headers (object)</dt>
<dd>Hash containing various headers copied from last receiving request
    on that connection. Exposed headers include: `origin`, `referer`
    and `x-forwarded-for` (and friends). We explicitly do not grant
    access to `cookie` header, as using it may easily lead to security
    issues (for details read the section "Authorisation").</dd>

<dt>Property: url (string)</dt>
<dd><a href="http://nodejs.org/docs/v0.4.10/api/http.html#request.url">Url</a>
    property copied from last request.</dd>

<dt>Property: pathname (string)</dt>
<dd>`pathname` from parsed url, for convenience.</dd>

<dt>Property: prefix (string)</dt>
<dd>Prefix of the url on which the request was handled.</dd>

<dt>Property: protocol (string)</dt>
<dd>Protocol used by the connection. Keep in mind that some protocols
   are indistinguishable - for example "xhr-polling" and "xdr-polling".</dd>

<dt>Property: readyState (integer)</dt>
<dd>Current state of the connection:
   0-connecting, 1-open, 2-closing, 3-closed.</dd>

<dt>write(message)</dt>
<dd>Sends a message over opened connection. A message must be a
  non-empty string. It's illegal to send a message after the connection was
  closed (either after 'close' or 'end' method or 'close' event).</dd>

<dt>close([code], [reason])</dt>
<dd>Asks the remote client to disconnect. 'code' and 'reason'
   parameters are optional and can be used to share the reason of
   disconnection.</dd>

<dt>end()</dt>
<dd>Asks the remote client to disconnect with default 'code' and
   'reason' values.</dd>

</dl>

A `Connection` instance emits the following events:

<dl>
<dt>Event: data (message)</dt>
<dd>A message arrived on the connection. Message is a unicode
  string.</dd>

<dt>Event: close ()</dt>
<dd>Connection was closed. This event is triggered exactly once for
   every connection.</dd>
</dl>

For example:

```javascript
sockjs_server.on('connection', function(conn) {
    console.log('connection' + conn);
    conn.on('close', function() {
        console.log('close ' + conn);
    });
    conn.on('data', function(message) {
        console.log('message ' + conn,
                    message);
    });
});
```

### Footnote

A fully working echo server does need a bit more boilerplate (to
handle requests unanswered by SockJS), see the
[`echo` example](https://github.com/sockjs/sockjs-node/tree/master/examples/echo)
for a complete code.

### Examples

If you want to see samples of running code, take a look at:

 * [./examples/echo](https://github.com/sockjs/sockjs-node/tree/master/examples/echo)
   directory, which contains a full example of a echo server.
 * [./examples/test_server](https://github.com/sockjs/sockjs-node/tree/master/examples/test_server) a standard SockJS test server.


Connecting to SockJS-node without the client
--------------------------------------------

Although the main point of SockJS it to enable browser-to-server
connectivity, it is possible to connect to SockJS from an external
application. Any SockJS server complying with 0.3 protocol does
support a raw WebSocket url. The raw WebSocket url for the test server
looks like:

 * ws://localhost:8081/echo/websocket

You can connect any WebSocket RFC 6455 compliant WebSocket client to
this url. This can be a command line client, external application,
third party code or even a browser (though I don't know why you would
want to do so).

Note: This endpoint will *not send any heartbeat packets*.


Deployment and load balancing
-----------------------------

There are two issues that need to be considered when planning a
non-trivial SockJS-node deployment: WebSocket-compatible load balancer
and sticky sessions (aka session affinity).

### WebSocket compatible load balancer

Often WebSockets don't play nicely with proxies and load balancers.
Deploying a SockJS server behind Nginx or Apache could be painful.

Fortunately recent versions of an excellent load balancer
[HAProxy](http://haproxy.1wt.eu/) are able to proxy WebSocket
connections. We propose to put HAProxy as a front line load balancer
and use it to split SockJS traffic from normal HTTP data. Take a look
at the sample
[SockJS HAProxy configuration](https://github.com/sockjs/sockjs-node/blob/master/examples/haproxy.cfg).

The config also shows how to use HAproxy balancing to split traffic
between multiple Node.js servers. You can also do balancing using dns
names.

### Sticky sessions

If you plan deploying more than one SockJS server, you must make sure
that all HTTP requests for a single session will hit the same server.
SockJS has two mechanisms that can be useful to achieve that:

 * Urls are prefixed with server and session id numbers, like:
   `/resource/<server_number>/<session_id>/transport`.  This is
   useful for load balancers that support prefix-based affinity
   (HAProxy does).
 * `JSESSIONID` cookie is being set by SockJS-node. Many load
   balancers turn on sticky sessions if that cookie is set. This
   technique is derived from Java applications, where sticky sessions
   are often necessary. HAProxy does support this method, as well as
   some hosting providers, for example CloudFoundry.  In order to
   enable this method on the client side, please supply a
   `cookie:true` option to SockJS constructor.


Development and testing
-----------------------

If you want to work on SockJS-node source code, you need to clone the
git repo and follow these steps. First you need to install
dependencies:

    cd sockjs-node
    npm install
    npm install --dev
    ln -s .. node_modules/sockjs

You're ready to compile CoffeeScript:

    make build

If compilation succeeds you may want to test if your changes pass all
the tests. Currently, there are two separate test suites. For both of
them you need to start a SockJS-node test server (by default listening
on port 8081):

    make test_server

### SockJS-protocol Python tests

To run it run something like:

    cd sockjs-protocol
    make test_deps
    ./venv/bin/python sockjs-protocol.py

For details see
[SockJS-protocol README](https://github.com/sockjs/sockjs-protocol#readme).

### SockJS-client QUnit tests

You need to start a second web server (by default listening on 8080)
that is serving various static html and javascript files:

    cd sockjs-client
    make test

At that point you should have two web servers running: sockjs-node on
8081 and sockjs-client on 8080. When you open the browser on
[http://localhost:8080/](http://localhost:8080/) you should be able
run the QUnit tests against your sockjs-node server.

For details see
[SockJS-client README](https://github.com/sockjs/sockjs-client#readme).

Additionally, if you're doing more serious development consider using
`make serve`, which will automatically the server when you modify the
source code.


Various issues and design considerations
----------------------------------------

### Authorisation

SockJS-node does not expose cookies to the application. This is done
deliberately as using cookie-based authorisation with SockJS simply
doesn't make sense and will lead to security issues.

Cookies are a contract between a browser and an http server, and are
identified by a domain name. If a browser has a cookie set for
particular domain, it will pass it as a part of all http requests to
the host. But to get various transports working, SockJS uses a middleman
- an iframe hosted from target SockJS domain. That means the server
will receive requests from the iframe, and not from the real
domain. The domain of an iframe is the same as the SockJS domain. The
problem is that any website can embed the iframe and communicate with
it - and request establishing SockJS connection. Using cookies for
authorisation in this scenario will result in granting full access to
SockJS communication with your website from any website. This is a
classic CSRF attack.

Basically - cookies are not suited for SockJS model. If you want to
authorise a session - provide a unique token on a page, send it as a
first thing over SockJS connection and validate it on the server
side. In essence, this is how cookies work.


### Deploying SockJS on Heroku

Long polling is known to cause problems on Heroku, but
[workaround for SockJS is available](https://github.com/sockjs/sockjs-node/issues/57#issuecomment-5242187).


---

# sort-css-media-queries

![types](https://img.shields.io/badge/types-TypeScript-blue)
![npm](https://img.shields.io/badge/node-6.3.0-yellow.svg)
![license](https://img.shields.io/badge/License-MIT-orange.svg)
![Test](https://github.com/dutchenkoOleg/sort-css-media-queries/workflows/Test/badge.svg)
[![Build Status](https://travis-ci.org/dutchenkoOleg/sort-css-media-queries.svg?branch=master)](https://travis-ci.org/dutchenkoOleg/sort-css-media-queries)

> The custom `sort` method (mobile-first / desktop-first) for [`css-mqpacker`](https://www.npmjs.com/package/css-mqpacker) or [`pleeease`](https://www.npmjs.com/package/pleeease) (which uses css-mqpacker) or, perhaps, something else ))

[![image](https://raw.githubusercontent.com/WezomCompany/code-style/main/assets/code-style-badge-white.svg)](https://github.com/WezomCompany/code-style)


| Statements                                                            | Branches                                                                    | Functions                                                            | Lines                                                            |
| --------------------------------------------------------------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------- |
| ![Statements](https://img.shields.io/badge/statements-95.68%25-brightgreen.svg) | ![Branches](https://img.shields.io/badge/branches-96.48%25-brightgreen.svg) | ![Functions](https://img.shields.io/badge/functions-100%25-brightgreen.svg) | ![Lines](https://img.shields.io/badge/lines-95.68%25-brightgreen.svg) |

---

##  Table of Contents

🇬🇧 English
|
[🇺🇦 Українська](https://github.com/dutchenkoOleg/sort-css-media-queries/blob/master/README-UK.md)

- [Alternative to `mqpacker`](#alternative-to-mqpacker)
- [Available in CSS-in-JS](#available-in-css-in-js-)
- [Installing](#installing)
- [Usage](#usage)
	- [mobile-first](#mobile-first)
	- [desktop-first](#desktop-first)
- [Sort configuration](#sort-configuration)
	- [Configuration options](#configuration-options)
- [Project info](#project-info)

## Alternative to `mqpacker`

https://github.com/hail2u/node-css-mqpacker is deprecated.  
One of the alternative plugins may be - [postcss-sort-media-queries](https://github.com/solversgroup/postcss-sort-media-queries)

## Available in CSS-in-JS 🚀

This package now is a part of the [jss-plugin-sort-css-media-queries](https://www.npmjs.com/package/jss-plugin-sort-css-media-queries)

## Installing

```shell
npm install --save sort-css-media-queries
# or using yarn cli
yarn add sort-css-media-queries
```

## Usage

See the original docs at first https://www.npmjs.com/package/css-mqpacker#sort;

```js

const sortCSSmq = require('sort-css-media-queries');

// your cool code
// ...

postcss([
  mqpacker({
    sort: sortCSSmq
  })
]).process(css);

```

### mobile-first

The plugin will sort your media-queries according to the mobile-first methodology. The sequence of media requests:

1. `min-width` and `min-height`  from smallest to largest,
1. `max-width` and `max-height` from largest to smallest,
1. `min-device-width` and `min-device-height`  from smallest to largest,
1. `max-device-width` and `max-device-height` from largest to smallest
1. media queries without dimension values, for example `print, tv, ...`,
1. at the end:
	- `print`
	- `print and (orientation: landscape)`
	- `print and (orientation: portrait)`

Example

Media-queries list:

```js
// min-width/-height -> from smallest to largest
'screen and (min-width: 320px) and (max-width: 767px)',
'screen and (min-height: 480px)',
'screen and (min-height: 480px) and (min-width: 320px)',
'screen and (min-width: 640px)',
'screen and (min-width: 1024px)',
'screen and (min-width: 1280px)',

// device
'screen and (min-device-width: 320px) and (max-device-width: 767px)',

// max-width/-height <- from largest to smallest
'screen and (max-width: 1023px)',
'screen and (max-height: 767px) and (min-height: 320px)',
'screen and (max-width: 767px) and (min-width: 320px)',
'screen and (max-width: 639px)',

// no units
'screen and (orientation: landscape)',
'screen and (orientation: portrait)',
'print',
'tv'
```

Sort result:

```js
'screen and (min-width: 320px) and (max-width: 767px)',
'screen and (min-height: 480px)',
'screen and (min-height: 480px) and (min-width: 320px)',
'screen and (min-width: 640px)',
'screen and (min-width: 1024px)',
'screen and (min-width: 1280px)',
'screen and (min-device-width: 320px) and (max-device-width: 767px)',
'screen and (max-width: 1023px)',
'screen and (max-height: 767px) and (min-height: 320px)',
'screen and (max-width: 767px) and (min-width: 320px)',
'screen and (max-width: 639px)',
'print',
'screen and (orientation: landscape)',
'screen and (orientation: portrait)',
'tv'
```

### desktop-first

```js
const sortCSSmq = require('sort-css-media-queries');

// your cool code
// ...

postcss([
  mqpacker({
    sort: sortCSSmq.desktopFirst
  })
]).process(css);

```

The plugin will sort your media-queries according to the desktop-first methodology. The sequence of media requests:

1. `max-width` and `max-height` from largest to smallest,
1. `max-device-width` and `max-device-height` from largest to smallest
1. `min-width` and `min-height`  from smallest to largest,
1. `min-device-width` and `min-device-height`  from smallest to largest,
1. media queries without dimension values, `tv, ...`,
1. at the end:
	- `print`
	- `print and (orientation: landscape)`
	- `print and (orientation: portrait)`

---

## Sort configuration

You can import a separate sorting helper from a package
and create your own sorting method with config as needed:

```js
const createSort = require("sort-css-media-queries/lib/create-sort");
const sortCSSmq = createSort({ ...configuration });
```

Or alternatively create a `sort-css-mq.config.json` file in the root of your project.
Or add property `sortCssMQ: {}` in your `package.json`.

By this configuration you can control sorting behaviour.

### Configuration options

#### `unitlessMqAlwaysFirst`

- type: `boolean | undefined`
- default value: `undefined`

---

## Project Info

* [Release notes](https://github.com/dutchenkoOleg/sort-css-media-queries/releases)
* [Contributor Covenant Code of Conduct](https://github.com/dutchenkoOleg/sort-css-media-queries/blob/master/CODE_OF_CONDUCT.md)
* [License MIT](https://github.com/dutchenkoOleg/sort-css-media-queries/blob/master/LICENSE)



---

# Change Log

## 0.5.6

* Fix for regression when people were using numbers as names in source maps. See
  #236.

## 0.5.5

* Fix "regression" of unsupported, implementation behavior that half the world
  happens to have come to depend on. See #235.

* Fix regression involving function hoisting in SpiderMonkey. See #233.

## 0.5.4

* Large performance improvements to source-map serialization. See #228 and #229.

## 0.5.3

* Do not include unnecessary distribution files. See
  commit ef7006f8d1647e0a83fdc60f04f5a7ca54886f86.

## 0.5.2

* Include browser distributions of the library in package.json's `files`. See
  issue #212.

## 0.5.1

* Fix latent bugs in IndexedSourceMapConsumer.prototype._parseMappings. See
  ff05274becc9e6e1295ed60f3ea090d31d843379.

## 0.5.0

* Node 0.8 is no longer supported.

* Use webpack instead of dryice for bundling.

* Big speedups serializing source maps. See pull request #203.

* Fix a bug with `SourceMapConsumer.prototype.sourceContentFor` and sources that
  explicitly start with the source root. See issue #199.

## 0.4.4

* Fix an issue where using a `SourceMapGenerator` after having created a
  `SourceMapConsumer` from it via `SourceMapConsumer.fromSourceMap` failed. See
  issue #191.

* Fix an issue with where `SourceMapGenerator` would mistakenly consider
  different mappings as duplicates of each other and avoid generating them. See
  issue #192.

## 0.4.3

* A very large number of performance improvements, particularly when parsing
  source maps. Collectively about 75% of time shaved off of the source map
  parsing benchmark!

* Fix a bug in `SourceMapConsumer.prototype.allGeneratedPositionsFor` and fuzzy
  searching in the presence of a column option. See issue #177.

* Fix a bug with joining a source and its source root when the source is above
  the root. See issue #182.

* Add the `SourceMapConsumer.prototype.hasContentsOfAllSources` method to
  determine when all sources' contents are inlined into the source map. See
  issue #190.

## 0.4.2

* Add an `.npmignore` file so that the benchmarks aren't pulled down by
  dependent projects. Issue #169.

* Add an optional `column` argument to
  `SourceMapConsumer.prototype.allGeneratedPositionsFor` and better handle lines
  with no mappings. Issues #172 and #173.

## 0.4.1

* Fix accidentally defining a global variable. #170.

## 0.4.0

* The default direction for fuzzy searching was changed back to its original
  direction. See #164.

* There is now a `bias` option you can supply to `SourceMapConsumer` to control
  the fuzzy searching direction. See #167.

* About an 8% speed up in parsing source maps. See #159.

* Added a benchmark for parsing and generating source maps.

## 0.3.0

* Change the default direction that searching for positions fuzzes when there is
  not an exact match. See #154.

* Support for environments using json2.js for JSON serialization. See #156.

## 0.2.0

* Support for consuming "indexed" source maps which do not have any remote
  sections. See pull request #127. This introduces a minor backwards
  incompatibility if you are monkey patching `SourceMapConsumer.prototype`
  methods.

## 0.1.43

* Performance improvements for `SourceMapGenerator` and `SourceNode`. See issue
  #148 for some discussion and issues #150, #151, and #152 for implementations.

## 0.1.42

* Fix an issue where `SourceNode`s from different versions of the source-map
  library couldn't be used in conjunction with each other. See issue #142.

## 0.1.41

* Fix a bug with getting the source content of relative sources with a "./"
  prefix. See issue #145 and [Bug 1090768](bugzil.la/1090768).

* Add the `SourceMapConsumer.prototype.computeColumnSpans` method to compute the
  column span of each mapping.

* Add the `SourceMapConsumer.prototype.allGeneratedPositionsFor` method to find
  all generated positions associated with a given original source and line.

## 0.1.40

* Performance improvements for parsing source maps in SourceMapConsumer.

## 0.1.39

* Fix a bug where setting a source's contents to null before any source content
  had been set before threw a TypeError. See issue #131.

## 0.1.38

* Fix a bug where finding relative paths from an empty path were creating
  absolute paths. See issue #129.

## 0.1.37

* Fix a bug where if the source root was an empty string, relative source paths
  would turn into absolute source paths. Issue #124.

## 0.1.36

* Allow the `names` mapping property to be an empty string. Issue #121.

## 0.1.35

* A third optional parameter was added to `SourceNode.fromStringWithSourceMap`
  to specify a path that relative sources in the second parameter should be
  relative to. Issue #105.

* If no file property is given to a `SourceMapGenerator`, then the resulting
  source map will no longer have a `null` file property. The property will
  simply not exist. Issue #104.

* Fixed a bug where consecutive newlines were ignored in `SourceNode`s.
  Issue #116.

## 0.1.34

* Make `SourceNode` work with windows style ("\r\n") newlines. Issue #103.

* Fix bug involving source contents and the
  `SourceMapGenerator.prototype.applySourceMap`. Issue #100.

## 0.1.33

* Fix some edge cases surrounding path joining and URL resolution.

* Add a third parameter for relative path to
  `SourceMapGenerator.prototype.applySourceMap`.

* Fix issues with mappings and EOLs.

## 0.1.32

* Fixed a bug where SourceMapConsumer couldn't handle negative relative columns
  (issue 92).

* Fixed test runner to actually report number of failed tests as its process
  exit code.

* Fixed a typo when reporting bad mappings (issue 87).

## 0.1.31

* Delay parsing the mappings in SourceMapConsumer until queried for a source
  location.

* Support Sass source maps (which at the time of writing deviate from the spec
  in small ways) in SourceMapConsumer.

## 0.1.30

* Do not join source root with a source, when the source is a data URI.

* Extend the test runner to allow running single specific test files at a time.

* Performance improvements in `SourceNode.prototype.walk` and
  `SourceMapConsumer.prototype.eachMapping`.

* Source map browser builds will now work inside Workers.

* Better error messages when attempting to add an invalid mapping to a
  `SourceMapGenerator`.

## 0.1.29

* Allow duplicate entries in the `names` and `sources` arrays of source maps
  (usually from TypeScript) we are parsing. Fixes github issue 72.

## 0.1.28

* Skip duplicate mappings when creating source maps from SourceNode; github
  issue 75.

## 0.1.27

* Don't throw an error when the `file` property is missing in SourceMapConsumer,
  we don't use it anyway.

## 0.1.26

* Fix SourceNode.fromStringWithSourceMap for empty maps. Fixes github issue 70.

## 0.1.25

* Make compatible with browserify

## 0.1.24

* Fix issue with absolute paths and `file://` URIs. See
  https://bugzilla.mozilla.org/show_bug.cgi?id=885597

## 0.1.23

* Fix issue with absolute paths and sourcesContent, github issue 64.

## 0.1.22

* Ignore duplicate mappings in SourceMapGenerator. Fixes github issue 21.

## 0.1.21

* Fixed handling of sources that start with a slash so that they are relative to
  the source root's host.

## 0.1.20

* Fixed github issue #43: absolute URLs aren't joined with the source root
  anymore.

## 0.1.19

* Using Travis CI to run tests.

## 0.1.18

* Fixed a bug in the handling of sourceRoot.

## 0.1.17

* Added SourceNode.fromStringWithSourceMap.

## 0.1.16

* Added missing documentation.

* Fixed the generating of empty mappings in SourceNode.

## 0.1.15

* Added SourceMapGenerator.applySourceMap.

## 0.1.14

* The sourceRoot is now handled consistently.

## 0.1.13

* Added SourceMapGenerator.fromSourceMap.

## 0.1.12

* SourceNode now generates empty mappings too.

## 0.1.11

* Added name support to SourceNode.

## 0.1.10

* Added sourcesContent support to the customer and generator.


---

# Source Map

[![Build Status](https://travis-ci.org/mozilla/source-map.png?branch=master)](https://travis-ci.org/mozilla/source-map)

[![NPM](https://nodei.co/npm/source-map.png?downloads=true&downloadRank=true)](https://www.npmjs.com/package/source-map)

This is a library to generate and consume the source map format
[described here][format].

[format]: https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k/edit

## Use with Node

    $ npm install source-map

## Use on the Web

    <script src="https://raw.githubusercontent.com/mozilla/source-map/master/dist/source-map.min.js" defer></script>

--------------------------------------------------------------------------------

<!-- `npm run toc` to regenerate the Table of Contents -->

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
## Table of Contents

- [Examples](#examples)
  - [Consuming a source map](#consuming-a-source-map)
  - [Generating a source map](#generating-a-source-map)
    - [With SourceNode (high level API)](#with-sourcenode-high-level-api)
    - [With SourceMapGenerator (low level API)](#with-sourcemapgenerator-low-level-api)
- [API](#api)
  - [SourceMapConsumer](#sourcemapconsumer)
    - [new SourceMapConsumer(rawSourceMap)](#new-sourcemapconsumerrawsourcemap)
    - [SourceMapConsumer.prototype.computeColumnSpans()](#sourcemapconsumerprototypecomputecolumnspans)
    - [SourceMapConsumer.prototype.originalPositionFor(generatedPosition)](#sourcemapconsumerprototypeoriginalpositionforgeneratedposition)
    - [SourceMapConsumer.prototype.generatedPositionFor(originalPosition)](#sourcemapconsumerprototypegeneratedpositionfororiginalposition)
    - [SourceMapConsumer.prototype.allGeneratedPositionsFor(originalPosition)](#sourcemapconsumerprototypeallgeneratedpositionsfororiginalposition)
    - [SourceMapConsumer.prototype.hasContentsOfAllSources()](#sourcemapconsumerprototypehascontentsofallsources)
    - [SourceMapConsumer.prototype.sourceContentFor(source[, returnNullOnMissing])](#sourcemapconsumerprototypesourcecontentforsource-returnnullonmissing)
    - [SourceMapConsumer.prototype.eachMapping(callback, context, order)](#sourcemapconsumerprototypeeachmappingcallback-context-order)
  - [SourceMapGenerator](#sourcemapgenerator)
    - [new SourceMapGenerator([startOfSourceMap])](#new-sourcemapgeneratorstartofsourcemap)
    - [SourceMapGenerator.fromSourceMap(sourceMapConsumer)](#sourcemapgeneratorfromsourcemapsourcemapconsumer)
    - [SourceMapGenerator.prototype.addMapping(mapping)](#sourcemapgeneratorprototypeaddmappingmapping)
    - [SourceMapGenerator.prototype.setSourceContent(sourceFile, sourceContent)](#sourcemapgeneratorprototypesetsourcecontentsourcefile-sourcecontent)
    - [SourceMapGenerator.prototype.applySourceMap(sourceMapConsumer[, sourceFile[, sourceMapPath]])](#sourcemapgeneratorprototypeapplysourcemapsourcemapconsumer-sourcefile-sourcemappath)
    - [SourceMapGenerator.prototype.toString()](#sourcemapgeneratorprototypetostring)
  - [SourceNode](#sourcenode)
    - [new SourceNode([line, column, source[, chunk[, name]]])](#new-sourcenodeline-column-source-chunk-name)
    - [SourceNode.fromStringWithSourceMap(code, sourceMapConsumer[, relativePath])](#sourcenodefromstringwithsourcemapcode-sourcemapconsumer-relativepath)
    - [SourceNode.prototype.add(chunk)](#sourcenodeprototypeaddchunk)
    - [SourceNode.prototype.prepend(chunk)](#sourcenodeprototypeprependchunk)
    - [SourceNode.prototype.setSourceContent(sourceFile, sourceContent)](#sourcenodeprototypesetsourcecontentsourcefile-sourcecontent)
    - [SourceNode.prototype.walk(fn)](#sourcenodeprototypewalkfn)
    - [SourceNode.prototype.walkSourceContents(fn)](#sourcenodeprototypewalksourcecontentsfn)
    - [SourceNode.prototype.join(sep)](#sourcenodeprototypejoinsep)
    - [SourceNode.prototype.replaceRight(pattern, replacement)](#sourcenodeprototypereplacerightpattern-replacement)
    - [SourceNode.prototype.toString()](#sourcenodeprototypetostring)
    - [SourceNode.prototype.toStringWithSourceMap([startOfSourceMap])](#sourcenodeprototypetostringwithsourcemapstartofsourcemap)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## Examples

### Consuming a source map

```js
var rawSourceMap = {
  version: 3,
  file: 'min.js',
  names: ['bar', 'baz', 'n'],
  sources: ['one.js', 'two.js'],
  sourceRoot: 'http://example.com/www/js/',
  mappings: 'CAAC,IAAI,IAAM,SAAUA,GAClB,OAAOC,IAAID;CCDb,IAAI,IAAM,SAAUE,GAClB,OAAOA'
};

var smc = new SourceMapConsumer(rawSourceMap);

console.log(smc.sources);
// [ 'http://example.com/www/js/one.js',
//   'http://example.com/www/js/two.js' ]

console.log(smc.originalPositionFor({
  line: 2,
  column: 28
}));
// { source: 'http://example.com/www/js/two.js',
//   line: 2,
//   column: 10,
//   name: 'n' }

console.log(smc.generatedPositionFor({
  source: 'http://example.com/www/js/two.js',
  line: 2,
  column: 10
}));
// { line: 2, column: 28 }

smc.eachMapping(function (m) {
  // ...
});
```

### Generating a source map

In depth guide:
[**Compiling to JavaScript, and Debugging with Source Maps**](https://hacks.mozilla.org/2013/05/compiling-to-javascript-and-debugging-with-source-maps/)

#### With SourceNode (high level API)

```js
function compile(ast) {
  switch (ast.type) {
  case 'BinaryExpression':
    return new SourceNode(
      ast.location.line,
      ast.location.column,
      ast.location.source,
      [compile(ast.left), " + ", compile(ast.right)]
    );
  case 'Literal':
    return new SourceNode(
      ast.location.line,
      ast.location.column,
      ast.location.source,
      String(ast.value)
    );
  // ...
  default:
    throw new Error("Bad AST");
  }
}

var ast = parse("40 + 2", "add.js");
console.log(compile(ast).toStringWithSourceMap({
  file: 'add.js'
}));
// { code: '40 + 2',
//   map: [object SourceMapGenerator] }
```

#### With SourceMapGenerator (low level API)

```js
var map = new SourceMapGenerator({
  file: "source-mapped.js"
});

map.addMapping({
  generated: {
    line: 10,
    column: 35
  },
  source: "foo.js",
  original: {
    line: 33,
    column: 2
  },
  name: "christopher"
});

console.log(map.toString());
// '{"version":3,"file":"source-mapped.js","sources":["foo.js"],"names":["christopher"],"mappings":";;;;;;;;;mCAgCEA"}'
```

## API

Get a reference to the module:

```js
// Node.js
var sourceMap = require('source-map');

// Browser builds
var sourceMap = window.sourceMap;

// Inside Firefox
const sourceMap = require("devtools/toolkit/sourcemap/source-map.js");
```

### SourceMapConsumer

A SourceMapConsumer instance represents a parsed source map which we can query
for information about the original file positions by giving it a file position
in the generated source.

#### new SourceMapConsumer(rawSourceMap)

The only parameter is the raw source map (either as a string which can be
`JSON.parse`'d, or an object). According to the spec, source maps have the
following attributes:

* `version`: Which version of the source map spec this map is following.

* `sources`: An array of URLs to the original source files.

* `names`: An array of identifiers which can be referenced by individual
  mappings.

* `sourceRoot`: Optional. The URL root from which all sources are relative.

* `sourcesContent`: Optional. An array of contents of the original source files.

* `mappings`: A string of base64 VLQs which contain the actual mappings.

* `file`: Optional. The generated filename this source map is associated with.

```js
var consumer = new sourceMap.SourceMapConsumer(rawSourceMapJsonData);
```

#### SourceMapConsumer.prototype.computeColumnSpans()

Compute the last column for each generated mapping. The last column is
inclusive.

```js
// Before:
consumer.allGeneratedPositionsFor({ line: 2, source: "foo.coffee" })
// [ { line: 2,
//     column: 1 },
//   { line: 2,
//     column: 10 },
//   { line: 2,
//     column: 20 } ]

consumer.computeColumnSpans();

// After:
consumer.allGeneratedPositionsFor({ line: 2, source: "foo.coffee" })
// [ { line: 2,
//     column: 1,
//     lastColumn: 9 },
//   { line: 2,
//     column: 10,
//     lastColumn: 19 },
//   { line: 2,
//     column: 20,
//     lastColumn: Infinity } ]

```

#### SourceMapConsumer.prototype.originalPositionFor(generatedPosition)

Returns the original source, line, and column information for the generated
source's line and column positions provided. The only argument is an object with
the following properties:

* `line`: The line number in the generated source.  Line numbers in
  this library are 1-based (note that the underlying source map
  specification uses 0-based line numbers -- this library handles the
  translation).

* `column`: The column number in the generated source.  Column numbers
  in this library are 0-based.

* `bias`: Either `SourceMapConsumer.GREATEST_LOWER_BOUND` or
  `SourceMapConsumer.LEAST_UPPER_BOUND`. Specifies whether to return the closest
  element that is smaller than or greater than the one we are searching for,
  respectively, if the exact element cannot be found.  Defaults to
  `SourceMapConsumer.GREATEST_LOWER_BOUND`.

and an object is returned with the following properties:

* `source`: The original source file, or null if this information is not
  available.

* `line`: The line number in the original source, or null if this information is
  not available.  The line number is 1-based.

* `column`: The column number in the original source, or null if this
  information is not available.  The column number is 0-based.

* `name`: The original identifier, or null if this information is not available.

```js
consumer.originalPositionFor({ line: 2, column: 10 })
// { source: 'foo.coffee',
//   line: 2,
//   column: 2,
//   name: null }

consumer.originalPositionFor({ line: 99999999999999999, column: 999999999999999 })
// { source: null,
//   line: null,
//   column: null,
//   name: null }
```

#### SourceMapConsumer.prototype.generatedPositionFor(originalPosition)

Returns the generated line and column information for the original source,
line, and column positions provided. The only argument is an object with
the following properties:

* `source`: The filename of the original source.

* `line`: The line number in the original source.  The line number is
  1-based.

* `column`: The column number in the original source.  The column
  number is 0-based.

and an object is returned with the following properties:

* `line`: The line number in the generated source, or null.  The line
  number is 1-based.

* `column`: The column number in the generated source, or null.  The
  column number is 0-based.

```js
consumer.generatedPositionFor({ source: "example.js", line: 2, column: 10 })
// { line: 1,
//   column: 56 }
```

#### SourceMapConsumer.prototype.allGeneratedPositionsFor(originalPosition)

Returns all generated line and column information for the original source, line,
and column provided. If no column is provided, returns all mappings
corresponding to a either the line we are searching for or the next closest line
that has any mappings. Otherwise, returns all mappings corresponding to the
given line and either the column we are searching for or the next closest column
that has any offsets.

The only argument is an object with the following properties:

* `source`: The filename of the original source.

* `line`: The line number in the original source.  The line number is
  1-based.

* `column`: Optional. The column number in the original source.  The
  column number is 0-based.

and an array of objects is returned, each with the following properties:

* `line`: The line number in the generated source, or null.  The line
  number is 1-based.

* `column`: The column number in the generated source, or null.  The
  column number is 0-based.

```js
consumer.allGeneratedpositionsfor({ line: 2, source: "foo.coffee" })
// [ { line: 2,
//     column: 1 },
//   { line: 2,
//     column: 10 },
//   { line: 2,
//     column: 20 } ]
```

#### SourceMapConsumer.prototype.hasContentsOfAllSources()

Return true if we have the embedded source content for every source listed in
the source map, false otherwise.

In other words, if this method returns `true`, then
`consumer.sourceContentFor(s)` will succeed for every source `s` in
`consumer.sources`.

```js
// ...
if (consumer.hasContentsOfAllSources()) {
  consumerReadyCallback(consumer);
} else {
  fetchSources(consumer, consumerReadyCallback);
}
// ...
```

#### SourceMapConsumer.prototype.sourceContentFor(source[, returnNullOnMissing])

Returns the original source content for the source provided. The only
argument is the URL of the original source file.

If the source content for the given source is not found, then an error is
thrown. Optionally, pass `true` as the second param to have `null` returned
instead.

```js
consumer.sources
// [ "my-cool-lib.clj" ]

consumer.sourceContentFor("my-cool-lib.clj")
// "..."

consumer.sourceContentFor("this is not in the source map");
// Error: "this is not in the source map" is not in the source map

consumer.sourceContentFor("this is not in the source map", true);
// null
```

#### SourceMapConsumer.prototype.eachMapping(callback, context, order)

Iterate over each mapping between an original source/line/column and a
generated line/column in this source map.

* `callback`: The function that is called with each mapping. Mappings have the
  form `{ source, generatedLine, generatedColumn, originalLine, originalColumn,
  name }`

* `context`: Optional. If specified, this object will be the value of `this`
  every time that `callback` is called.

* `order`: Either `SourceMapConsumer.GENERATED_ORDER` or
  `SourceMapConsumer.ORIGINAL_ORDER`. Specifies whether you want to iterate over
  the mappings sorted by the generated file's line/column order or the
  original's source/line/column order, respectively. Defaults to
  `SourceMapConsumer.GENERATED_ORDER`.

```js
consumer.eachMapping(function (m) { console.log(m); })
// ...
// { source: 'illmatic.js',
//   generatedLine: 1,
//   generatedColumn: 0,
//   originalLine: 1,
//   originalColumn: 0,
//   name: null }
// { source: 'illmatic.js',
//   generatedLine: 2,
//   generatedColumn: 0,
//   originalLine: 2,
//   originalColumn: 0,
//   name: null }
// ...
```
### SourceMapGenerator

An instance of the SourceMapGenerator represents a source map which is being
built incrementally.

#### new SourceMapGenerator([startOfSourceMap])

You may pass an object with the following properties:

* `file`: The filename of the generated source that this source map is
  associated with.

* `sourceRoot`: A root for all relative URLs in this source map.

* `skipValidation`: Optional. When `true`, disables validation of mappings as
  they are added. This can improve performance but should be used with
  discretion, as a last resort. Even then, one should avoid using this flag when
  running tests, if possible.

```js
var generator = new sourceMap.SourceMapGenerator({
  file: "my-generated-javascript-file.js",
  sourceRoot: "http://example.com/app/js/"
});
```

#### SourceMapGenerator.fromSourceMap(sourceMapConsumer)

Creates a new `SourceMapGenerator` from an existing `SourceMapConsumer` instance.

* `sourceMapConsumer` The SourceMap.

```js
var generator = sourceMap.SourceMapGenerator.fromSourceMap(consumer);
```

#### SourceMapGenerator.prototype.addMapping(mapping)

Add a single mapping from original source line and column to the generated
source's line and column for this source map being created. The mapping object
should have the following properties:

* `generated`: An object with the generated line and column positions.

* `original`: An object with the original line and column positions.

* `source`: The original source file (relative to the sourceRoot).

* `name`: An optional original token name for this mapping.

```js
generator.addMapping({
  source: "module-one.scm",
  original: { line: 128, column: 0 },
  generated: { line: 3, column: 456 }
})
```

#### SourceMapGenerator.prototype.setSourceContent(sourceFile, sourceContent)

Set the source content for an original source file.

* `sourceFile` the URL of the original source file.

* `sourceContent` the content of the source file.

```js
generator.setSourceContent("module-one.scm",
                           fs.readFileSync("path/to/module-one.scm"))
```

#### SourceMapGenerator.prototype.applySourceMap(sourceMapConsumer[, sourceFile[, sourceMapPath]])

Applies a SourceMap for a source file to the SourceMap.
Each mapping to the supplied source file is rewritten using the
supplied SourceMap. Note: The resolution for the resulting mappings
is the minimum of this map and the supplied map.

* `sourceMapConsumer`: The SourceMap to be applied.

* `sourceFile`: Optional. The filename of the source file.
  If omitted, sourceMapConsumer.file will be used, if it exists.
  Otherwise an error will be thrown.

* `sourceMapPath`: Optional. The dirname of the path to the SourceMap
  to be applied. If relative, it is relative to the SourceMap.

  This parameter is needed when the two SourceMaps aren't in the same
  directory, and the SourceMap to be applied contains relative source
  paths. If so, those relative source paths need to be rewritten
  relative to the SourceMap.

  If omitted, it is assumed that both SourceMaps are in the same directory,
  thus not needing any rewriting. (Supplying `'.'` has the same effect.)

#### SourceMapGenerator.prototype.toString()

Renders the source map being generated to a string.

```js
generator.toString()
// '{"version":3,"sources":["module-one.scm"],"names":[],"mappings":"...snip...","file":"my-generated-javascript-file.js","sourceRoot":"http://example.com/app/js/"}'
```

### SourceNode

SourceNodes provide a way to abstract over interpolating and/or concatenating
snippets of generated JavaScript source code, while maintaining the line and
column information associated between those snippets and the original source
code. This is useful as the final intermediate representation a compiler might
use before outputting the generated JS and source map.

#### new SourceNode([line, column, source[, chunk[, name]]])

* `line`: The original line number associated with this source node, or null if
  it isn't associated with an original line.  The line number is 1-based.

* `column`: The original column number associated with this source node, or null
  if it isn't associated with an original column.  The column number
  is 0-based.

* `source`: The original source's filename; null if no filename is provided.

* `chunk`: Optional. Is immediately passed to `SourceNode.prototype.add`, see
  below.

* `name`: Optional. The original identifier.

```js
var node = new SourceNode(1, 2, "a.cpp", [
  new SourceNode(3, 4, "b.cpp", "extern int status;\n"),
  new SourceNode(5, 6, "c.cpp", "std::string* make_string(size_t n);\n"),
  new SourceNode(7, 8, "d.cpp", "int main(int argc, char** argv) {}\n"),
]);
```

#### SourceNode.fromStringWithSourceMap(code, sourceMapConsumer[, relativePath])

Creates a SourceNode from generated code and a SourceMapConsumer.

* `code`: The generated code

* `sourceMapConsumer` The SourceMap for the generated code

* `relativePath` The optional path that relative sources in `sourceMapConsumer`
  should be relative to.

```js
var consumer = new SourceMapConsumer(fs.readFileSync("path/to/my-file.js.map", "utf8"));
var node = SourceNode.fromStringWithSourceMap(fs.readFileSync("path/to/my-file.js"),
                                              consumer);
```

#### SourceNode.prototype.add(chunk)

Add a chunk of generated JS to this source node.

* `chunk`: A string snippet of generated JS code, another instance of
   `SourceNode`, or an array where each member is one of those things.

```js
node.add(" + ");
node.add(otherNode);
node.add([leftHandOperandNode, " + ", rightHandOperandNode]);
```

#### SourceNode.prototype.prepend(chunk)

Prepend a chunk of generated JS to this source node.

* `chunk`: A string snippet of generated JS code, another instance of
   `SourceNode`, or an array where each member is one of those things.

```js
node.prepend("/** Build Id: f783haef86324gf **/\n\n");
```

#### SourceNode.prototype.setSourceContent(sourceFile, sourceContent)

Set the source content for a source file. This will be added to the
`SourceMap` in the `sourcesContent` field.

* `sourceFile`: The filename of the source file

* `sourceContent`: The content of the source file

```js
node.setSourceContent("module-one.scm",
                      fs.readFileSync("path/to/module-one.scm"))
```

#### SourceNode.prototype.walk(fn)

Walk over the tree of JS snippets in this node and its children. The walking
function is called once for each snippet of JS and is passed that snippet and
the its original associated source's line/column location.

* `fn`: The traversal function.

```js
var node = new SourceNode(1, 2, "a.js", [
  new SourceNode(3, 4, "b.js", "uno"),
  "dos",
  [
    "tres",
    new SourceNode(5, 6, "c.js", "quatro")
  ]
]);

node.walk(function (code, loc) { console.log("WALK:", code, loc); })
// WALK: uno { source: 'b.js', line: 3, column: 4, name: null }
// WALK: dos { source: 'a.js', line: 1, column: 2, name: null }
// WALK: tres { source: 'a.js', line: 1, column: 2, name: null }
// WALK: quatro { source: 'c.js', line: 5, column: 6, name: null }
```

#### SourceNode.prototype.walkSourceContents(fn)

Walk over the tree of SourceNodes. The walking function is called for each
source file content and is passed the filename and source content.

* `fn`: The traversal function.

```js
var a = new SourceNode(1, 2, "a.js", "generated from a");
a.setSourceContent("a.js", "original a");
var b = new SourceNode(1, 2, "b.js", "generated from b");
b.setSourceContent("b.js", "original b");
var c = new SourceNode(1, 2, "c.js", "generated from c");
c.setSourceContent("c.js", "original c");

var node = new SourceNode(null, null, null, [a, b, c]);
node.walkSourceContents(function (source, contents) { console.log("WALK:", source, ":", contents); })
// WALK: a.js : original a
// WALK: b.js : original b
// WALK: c.js : original c
```

#### SourceNode.prototype.join(sep)

Like `Array.prototype.join` except for SourceNodes. Inserts the separator
between each of this source node's children.

* `sep`: The separator.

```js
var lhs = new SourceNode(1, 2, "a.rs", "my_copy");
var operand = new SourceNode(3, 4, "a.rs", "=");
var rhs = new SourceNode(5, 6, "a.rs", "orig.clone()");

var node = new SourceNode(null, null, null, [ lhs, operand, rhs ]);
var joinedNode = node.join(" ");
```

#### SourceNode.prototype.replaceRight(pattern, replacement)

Call `String.prototype.replace` on the very right-most source snippet. Useful
for trimming white space from the end of a source node, etc.

* `pattern`: The pattern to replace.

* `replacement`: The thing to replace the pattern with.

```js
// Trim trailing white space.
node.replaceRight(/\s*$/, "");
```

#### SourceNode.prototype.toString()

Return the string representation of this source node. Walks over the tree and
concatenates all the various snippets together to one string.

```js
var node = new SourceNode(1, 2, "a.js", [
  new SourceNode(3, 4, "b.js", "uno"),
  "dos",
  [
    "tres",
    new SourceNode(5, 6, "c.js", "quatro")
  ]
]);

node.toString()
// 'unodostresquatro'
```

#### SourceNode.prototype.toStringWithSourceMap([startOfSourceMap])

Returns the string representation of this tree of source nodes, plus a
SourceMapGenerator which contains all the mappings between the generated and
original sources.

The arguments are the same as those to `new SourceMapGenerator`.

```js
var node = new SourceNode(1, 2, "a.js", [
  new SourceNode(3, 4, "b.js", "uno"),
  "dos",
  [
    "tres",
    new SourceNode(5, 6, "c.js", "quatro")
  ]
]);

node.toStringWithSourceMap({ file: "my-output-file.js" })
// { code: 'unodostresquatro',
//   map: [object SourceMapGenerator] }
```


---

# Source Map JS

[![NPM](https://nodei.co/npm/source-map-js.png?downloads=true&downloadRank=true)](https://www.npmjs.com/package/source-map-js)

Difference between original [source-map](https://github.com/mozilla/source-map):

> TL,DR: it's fork of original source-map@0.6, but with perfomance optimizations.

This journey starts from [source-map@0.7.0](https://github.com/mozilla/source-map/blob/master/CHANGELOG.md#070). Some part of it was rewritten to Rust and WASM and API became async.

It's still a major block for many libraries like PostCSS or Sass for example because they need to migrate the whole API to the async way. This is the reason why 0.6.1 has 2x more downloads than 0.7.3 while it's faster several times.

![Downloads count](media/downloads.png)

More important that WASM version has some optimizations in JS code too. This is why [community asked to create branch for 0.6 version](https://github.com/mozilla/source-map/issues/324) and port these optimizations but, sadly, the answer was «no». A bit later I discovered [the issue](https://github.com/mozilla/source-map/issues/370) created by [Ben Rothman (@benthemonkey)](https://github.com/benthemonkey) with no response at all.

[Roman Dvornov (@lahmatiy)](https://github.com/lahmatiy) wrote a [serveral posts](https://t.me/gorshochekvarit/76) (russian, only, sorry) about source-map library in his own Telegram channel. He mentioned the article [«Maybe you don't need Rust and WASM to speed up your JS»](https://mrale.ph/blog/2018/02/03/maybe-you-dont-need-rust-to-speed-up-your-js.html) written by [Vyacheslav Egorov (@mraleph)](https://github.com/mraleph). This article contains optimizations and hacks that lead to almost the same performance compare to WASM implementation.

I decided to fork the original source-map and port these optimizations from the article and several others PR from the original source-map.

---------

This is a library to generate and consume the source map format
[described here][format].

[format]: https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k/edit

## Use with Node

    $ npm install source-map-js

<!-- ## Use on the Web

    <script src="https://raw.githubusercontent.com/mozilla/source-map/master/dist/source-map.min.js" defer></script> -->

--------------------------------------------------------------------------------

<!-- `npm run toc` to regenerate the Table of Contents -->

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
## Table of Contents

- [Examples](#examples)
  - [Consuming a source map](#consuming-a-source-map)
  - [Generating a source map](#generating-a-source-map)
    - [With SourceNode (high level API)](#with-sourcenode-high-level-api)
    - [With SourceMapGenerator (low level API)](#with-sourcemapgenerator-low-level-api)
- [API](#api)
  - [SourceMapConsumer](#sourcemapconsumer)
    - [new SourceMapConsumer(rawSourceMap)](#new-sourcemapconsumerrawsourcemap)
    - [SourceMapConsumer.prototype.computeColumnSpans()](#sourcemapconsumerprototypecomputecolumnspans)
    - [SourceMapConsumer.prototype.originalPositionFor(generatedPosition)](#sourcemapconsumerprototypeoriginalpositionforgeneratedposition)
    - [SourceMapConsumer.prototype.generatedPositionFor(originalPosition)](#sourcemapconsumerprototypegeneratedpositionfororiginalposition)
    - [SourceMapConsumer.prototype.allGeneratedPositionsFor(originalPosition)](#sourcemapconsumerprototypeallgeneratedpositionsfororiginalposition)
    - [SourceMapConsumer.prototype.hasContentsOfAllSources()](#sourcemapconsumerprototypehascontentsofallsources)
    - [SourceMapConsumer.prototype.sourceContentFor(source[, returnNullOnMissing])](#sourcemapconsumerprototypesourcecontentforsource-returnnullonmissing)
    - [SourceMapConsumer.prototype.eachMapping(callback, context, order)](#sourcemapconsumerprototypeeachmappingcallback-context-order)
  - [SourceMapGenerator](#sourcemapgenerator)
    - [new SourceMapGenerator([startOfSourceMap])](#new-sourcemapgeneratorstartofsourcemap)
    - [SourceMapGenerator.fromSourceMap(sourceMapConsumer)](#sourcemapgeneratorfromsourcemapsourcemapconsumer)
    - [SourceMapGenerator.prototype.addMapping(mapping)](#sourcemapgeneratorprototypeaddmappingmapping)
    - [SourceMapGenerator.prototype.setSourceContent(sourceFile, sourceContent)](#sourcemapgeneratorprototypesetsourcecontentsourcefile-sourcecontent)
    - [SourceMapGenerator.prototype.applySourceMap(sourceMapConsumer[, sourceFile[, sourceMapPath]])](#sourcemapgeneratorprototypeapplysourcemapsourcemapconsumer-sourcefile-sourcemappath)
    - [SourceMapGenerator.prototype.toString()](#sourcemapgeneratorprototypetostring)
  - [SourceNode](#sourcenode)
    - [new SourceNode([line, column, source[, chunk[, name]]])](#new-sourcenodeline-column-source-chunk-name)
    - [SourceNode.fromStringWithSourceMap(code, sourceMapConsumer[, relativePath])](#sourcenodefromstringwithsourcemapcode-sourcemapconsumer-relativepath)
    - [SourceNode.prototype.add(chunk)](#sourcenodeprototypeaddchunk)
    - [SourceNode.prototype.prepend(chunk)](#sourcenodeprototypeprependchunk)
    - [SourceNode.prototype.setSourceContent(sourceFile, sourceContent)](#sourcenodeprototypesetsourcecontentsourcefile-sourcecontent)
    - [SourceNode.prototype.walk(fn)](#sourcenodeprototypewalkfn)
    - [SourceNode.prototype.walkSourceContents(fn)](#sourcenodeprototypewalksourcecontentsfn)
    - [SourceNode.prototype.join(sep)](#sourcenodeprototypejoinsep)
    - [SourceNode.prototype.replaceRight(pattern, replacement)](#sourcenodeprototypereplacerightpattern-replacement)
    - [SourceNode.prototype.toString()](#sourcenodeprototypetostring)
    - [SourceNode.prototype.toStringWithSourceMap([startOfSourceMap])](#sourcenodeprototypetostringwithsourcemapstartofsourcemap)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## Examples

### Consuming a source map

```js
var rawSourceMap = {
  version: 3,
  file: 'min.js',
  names: ['bar', 'baz', 'n'],
  sources: ['one.js', 'two.js'],
  sourceRoot: 'http://example.com/www/js/',
  mappings: 'CAAC,IAAI,IAAM,SAAUA,GAClB,OAAOC,IAAID;CCDb,IAAI,IAAM,SAAUE,GAClB,OAAOA'
};

var smc = new SourceMapConsumer(rawSourceMap);

console.log(smc.sources);
// [ 'http://example.com/www/js/one.js',
//   'http://example.com/www/js/two.js' ]

console.log(smc.originalPositionFor({
  line: 2,
  column: 28
}));
// { source: 'http://example.com/www/js/two.js',
//   line: 2,
//   column: 10,
//   name: 'n' }

console.log(smc.generatedPositionFor({
  source: 'http://example.com/www/js/two.js',
  line: 2,
  column: 10
}));
// { line: 2, column: 28 }

smc.eachMapping(function (m) {
  // ...
});
```

### Generating a source map

In depth guide:
[**Compiling to JavaScript, and Debugging with Source Maps**](https://hacks.mozilla.org/2013/05/compiling-to-javascript-and-debugging-with-source-maps/)

#### With SourceNode (high level API)

```js
function compile(ast) {
  switch (ast.type) {
  case 'BinaryExpression':
    return new SourceNode(
      ast.location.line,
      ast.location.column,
      ast.location.source,
      [compile(ast.left), " + ", compile(ast.right)]
    );
  case 'Literal':
    return new SourceNode(
      ast.location.line,
      ast.location.column,
      ast.location.source,
      String(ast.value)
    );
  // ...
  default:
    throw new Error("Bad AST");
  }
}

var ast = parse("40 + 2", "add.js");
console.log(compile(ast).toStringWithSourceMap({
  file: 'add.js'
}));
// { code: '40 + 2',
//   map: [object SourceMapGenerator] }
```

#### With SourceMapGenerator (low level API)

```js
var map = new SourceMapGenerator({
  file: "source-mapped.js"
});

map.addMapping({
  generated: {
    line: 10,
    column: 35
  },
  source: "foo.js",
  original: {
    line: 33,
    column: 2
  },
  name: "christopher"
});

console.log(map.toString());
// '{"version":3,"file":"source-mapped.js","sources":["foo.js"],"names":["christopher"],"mappings":";;;;;;;;;mCAgCEA"}'
```

## API

Get a reference to the module:

```js
// Node.js
var sourceMap = require('source-map');

// Browser builds
var sourceMap = window.sourceMap;

// Inside Firefox
const sourceMap = require("devtools/toolkit/sourcemap/source-map.js");
```

### SourceMapConsumer

A SourceMapConsumer instance represents a parsed source map which we can query
for information about the original file positions by giving it a file position
in the generated source.

#### new SourceMapConsumer(rawSourceMap)

The only parameter is the raw source map (either as a string which can be
`JSON.parse`'d, or an object). According to the spec, source maps have the
following attributes:

* `version`: Which version of the source map spec this map is following.

* `sources`: An array of URLs to the original source files.

* `names`: An array of identifiers which can be referenced by individual
  mappings.

* `sourceRoot`: Optional. The URL root from which all sources are relative.

* `sourcesContent`: Optional. An array of contents of the original source files.

* `mappings`: A string of base64 VLQs which contain the actual mappings.

* `file`: Optional. The generated filename this source map is associated with.

```js
var consumer = new sourceMap.SourceMapConsumer(rawSourceMapJsonData);
```

#### SourceMapConsumer.prototype.computeColumnSpans()

Compute the last column for each generated mapping. The last column is
inclusive.

```js
// Before:
consumer.allGeneratedPositionsFor({ line: 2, source: "foo.coffee" })
// [ { line: 2,
//     column: 1 },
//   { line: 2,
//     column: 10 },
//   { line: 2,
//     column: 20 } ]

consumer.computeColumnSpans();

// After:
consumer.allGeneratedPositionsFor({ line: 2, source: "foo.coffee" })
// [ { line: 2,
//     column: 1,
//     lastColumn: 9 },
//   { line: 2,
//     column: 10,
//     lastColumn: 19 },
//   { line: 2,
//     column: 20,
//     lastColumn: Infinity } ]

```

#### SourceMapConsumer.prototype.originalPositionFor(generatedPosition)

Returns the original source, line, and column information for the generated
source's line and column positions provided. The only argument is an object with
the following properties:

* `line`: The line number in the generated source.  Line numbers in
  this library are 1-based (note that the underlying source map
  specification uses 0-based line numbers -- this library handles the
  translation).

* `column`: The column number in the generated source.  Column numbers
  in this library are 0-based.

* `bias`: Either `SourceMapConsumer.GREATEST_LOWER_BOUND` or
  `SourceMapConsumer.LEAST_UPPER_BOUND`. Specifies whether to return the closest
  element that is smaller than or greater than the one we are searching for,
  respectively, if the exact element cannot be found.  Defaults to
  `SourceMapConsumer.GREATEST_LOWER_BOUND`.

and an object is returned with the following properties:

* `source`: The original source file, or null if this information is not
  available.

* `line`: The line number in the original source, or null if this information is
  not available.  The line number is 1-based.

* `column`: The column number in the original source, or null if this
  information is not available.  The column number is 0-based.

* `name`: The original identifier, or null if this information is not available.

```js
consumer.originalPositionFor({ line: 2, column: 10 })
// { source: 'foo.coffee',
//   line: 2,
//   column: 2,
//   name: null }

consumer.originalPositionFor({ line: 99999999999999999, column: 999999999999999 })
// { source: null,
//   line: null,
//   column: null,
//   name: null }
```

#### SourceMapConsumer.prototype.generatedPositionFor(originalPosition)

Returns the generated line and column information for the original source,
line, and column positions provided. The only argument is an object with
the following properties:

* `source`: The filename of the original source.

* `line`: The line number in the original source.  The line number is
  1-based.

* `column`: The column number in the original source.  The column
  number is 0-based.

and an object is returned with the following properties:

* `line`: The line number in the generated source, or null.  The line
  number is 1-based.

* `column`: The column number in the generated source, or null.  The
  column number is 0-based.

```js
consumer.generatedPositionFor({ source: "example.js", line: 2, column: 10 })
// { line: 1,
//   column: 56 }
```

#### SourceMapConsumer.prototype.allGeneratedPositionsFor(originalPosition)

Returns all generated line and column information for the original source, line,
and column provided. If no column is provided, returns all mappings
corresponding to a either the line we are searching for or the next closest line
that has any mappings. Otherwise, returns all mappings corresponding to the
given line and either the column we are searching for or the next closest column
that has any offsets.

The only argument is an object with the following properties:

* `source`: The filename of the original source.

* `line`: The line number in the original source.  The line number is
  1-based.

* `column`: Optional. The column number in the original source.  The
  column number is 0-based.

and an array of objects is returned, each with the following properties:

* `line`: The line number in the generated source, or null.  The line
  number is 1-based.

* `column`: The column number in the generated source, or null.  The
  column number is 0-based.

```js
consumer.allGeneratedpositionsfor({ line: 2, source: "foo.coffee" })
// [ { line: 2,
//     column: 1 },
//   { line: 2,
//     column: 10 },
//   { line: 2,
//     column: 20 } ]
```

#### SourceMapConsumer.prototype.hasContentsOfAllSources()

Return true if we have the embedded source content for every source listed in
the source map, false otherwise.

In other words, if this method returns `true`, then
`consumer.sourceContentFor(s)` will succeed for every source `s` in
`consumer.sources`.

```js
// ...
if (consumer.hasContentsOfAllSources()) {
  consumerReadyCallback(consumer);
} else {
  fetchSources(consumer, consumerReadyCallback);
}
// ...
```

#### SourceMapConsumer.prototype.sourceContentFor(source[, returnNullOnMissing])

Returns the original source content for the source provided. The only
argument is the URL of the original source file.

If the source content for the given source is not found, then an error is
thrown. Optionally, pass `true` as the second param to have `null` returned
instead.

```js
consumer.sources
// [ "my-cool-lib.clj" ]

consumer.sourceContentFor("my-cool-lib.clj")
// "..."

consumer.sourceContentFor("this is not in the source map");
// Error: "this is not in the source map" is not in the source map

consumer.sourceContentFor("this is not in the source map", true);
// null
```

#### SourceMapConsumer.prototype.eachMapping(callback, context, order)

Iterate over each mapping between an original source/line/column and a
generated line/column in this source map.

* `callback`: The function that is called with each mapping. Mappings have the
  form `{ source, generatedLine, generatedColumn, originalLine, originalColumn,
  name }`

* `context`: Optional. If specified, this object will be the value of `this`
  every time that `callback` is called.

* `order`: Either `SourceMapConsumer.GENERATED_ORDER` or
  `SourceMapConsumer.ORIGINAL_ORDER`. Specifies whether you want to iterate over
  the mappings sorted by the generated file's line/column order or the
  original's source/line/column order, respectively. Defaults to
  `SourceMapConsumer.GENERATED_ORDER`.

```js
consumer.eachMapping(function (m) { console.log(m); })
// ...
// { source: 'illmatic.js',
//   generatedLine: 1,
//   generatedColumn: 0,
//   originalLine: 1,
//   originalColumn: 0,
//   name: null }
// { source: 'illmatic.js',
//   generatedLine: 2,
//   generatedColumn: 0,
//   originalLine: 2,
//   originalColumn: 0,
//   name: null }
// ...
```
### SourceMapGenerator

An instance of the SourceMapGenerator represents a source map which is being
built incrementally.

#### new SourceMapGenerator([startOfSourceMap])

You may pass an object with the following properties:

* `file`: The filename of the generated source that this source map is
  associated with.

* `sourceRoot`: A root for all relative URLs in this source map.

* `skipValidation`: Optional. When `true`, disables validation of mappings as
  they are added. This can improve performance but should be used with
  discretion, as a last resort. Even then, one should avoid using this flag when
  running tests, if possible.

* `ignoreInvalidMapping`: Optional. When `true`, instead of throwing error on
  invalid mapping, it will be ignored.

```js
var generator = new sourceMap.SourceMapGenerator({
  file: "my-generated-javascript-file.js",
  sourceRoot: "http://example.com/app/js/"
});
```

#### SourceMapGenerator.fromSourceMap(sourceMapConsumer, sourceMapGeneratorOptions)

Creates a new `SourceMapGenerator` from an existing `SourceMapConsumer` instance.

* `sourceMapConsumer` The SourceMap.

* `sourceMapGeneratorOptions` options that will be passed to the SourceMapGenerator constructor which used under the hood.

```js
var generator = sourceMap.SourceMapGenerator.fromSourceMap(consumer, {
  ignoreInvalidMapping: true,
});
```

#### SourceMapGenerator.prototype.addMapping(mapping)

Add a single mapping from original source line and column to the generated
source's line and column for this source map being created. The mapping object
should have the following properties:

* `generated`: An object with the generated line and column positions.

* `original`: An object with the original line and column positions.

* `source`: The original source file (relative to the sourceRoot).

* `name`: An optional original token name for this mapping.

```js
generator.addMapping({
  source: "module-one.scm",
  original: { line: 128, column: 0 },
  generated: { line: 3, column: 456 }
})
```

#### SourceMapGenerator.prototype.setSourceContent(sourceFile, sourceContent)

Set the source content for an original source file.

* `sourceFile` the URL of the original source file.

* `sourceContent` the content of the source file.

```js
generator.setSourceContent("module-one.scm",
                           fs.readFileSync("path/to/module-one.scm"))
```

#### SourceMapGenerator.prototype.applySourceMap(sourceMapConsumer[, sourceFile[, sourceMapPath]])

Applies a SourceMap for a source file to the SourceMap.
Each mapping to the supplied source file is rewritten using the
supplied SourceMap. Note: The resolution for the resulting mappings
is the minimum of this map and the supplied map.

* `sourceMapConsumer`: The SourceMap to be applied.

* `sourceFile`: Optional. The filename of the source file.
  If omitted, sourceMapConsumer.file will be used, if it exists.
  Otherwise an error will be thrown.

* `sourceMapPath`: Optional. The dirname of the path to the SourceMap
  to be applied. If relative, it is relative to the SourceMap.

  This parameter is needed when the two SourceMaps aren't in the same
  directory, and the SourceMap to be applied contains relative source
  paths. If so, those relative source paths need to be rewritten
  relative to the SourceMap.

  If omitted, it is assumed that both SourceMaps are in the same directory,
  thus not needing any rewriting. (Supplying `'.'` has the same effect.)

#### SourceMapGenerator.prototype.toString()

Renders the source map being generated to a string.

```js
generator.toString()
// '{"version":3,"sources":["module-one.scm"],"names":[],"mappings":"...snip...","file":"my-generated-javascript-file.js","sourceRoot":"http://example.com/app/js/"}'
```

### SourceNode

SourceNodes provide a way to abstract over interpolating and/or concatenating
snippets of generated JavaScript source code, while maintaining the line and
column information associated between those snippets and the original source
code. This is useful as the final intermediate representation a compiler might
use before outputting the generated JS and source map.

#### new SourceNode([line, column, source[, chunk[, name]]])

* `line`: The original line number associated with this source node, or null if
  it isn't associated with an original line.  The line number is 1-based.

* `column`: The original column number associated with this source node, or null
  if it isn't associated with an original column.  The column number
  is 0-based.

* `source`: The original source's filename; null if no filename is provided.

* `chunk`: Optional. Is immediately passed to `SourceNode.prototype.add`, see
  below.

* `name`: Optional. The original identifier.

```js
var node = new SourceNode(1, 2, "a.cpp", [
  new SourceNode(3, 4, "b.cpp", "extern int status;\n"),
  new SourceNode(5, 6, "c.cpp", "std::string* make_string(size_t n);\n"),
  new SourceNode(7, 8, "d.cpp", "int main(int argc, char** argv) {}\n"),
]);
```

#### SourceNode.fromStringWithSourceMap(code, sourceMapConsumer[, relativePath])

Creates a SourceNode from generated code and a SourceMapConsumer.

* `code`: The generated code

* `sourceMapConsumer` The SourceMap for the generated code

* `relativePath` The optional path that relative sources in `sourceMapConsumer`
  should be relative to.

```js
var consumer = new SourceMapConsumer(fs.readFileSync("path/to/my-file.js.map", "utf8"));
var node = SourceNode.fromStringWithSourceMap(fs.readFileSync("path/to/my-file.js"),
                                              consumer);
```

#### SourceNode.prototype.add(chunk)

Add a chunk of generated JS to this source node.

* `chunk`: A string snippet of generated JS code, another instance of
   `SourceNode`, or an array where each member is one of those things.

```js
node.add(" + ");
node.add(otherNode);
node.add([leftHandOperandNode, " + ", rightHandOperandNode]);
```

#### SourceNode.prototype.prepend(chunk)

Prepend a chunk of generated JS to this source node.

* `chunk`: A string snippet of generated JS code, another instance of
   `SourceNode`, or an array where each member is one of those things.

```js
node.prepend("/** Build Id: f783haef86324gf **/\n\n");
```

#### SourceNode.prototype.setSourceContent(sourceFile, sourceContent)

Set the source content for a source file. This will be added to the
`SourceMap` in the `sourcesContent` field.

* `sourceFile`: The filename of the source file

* `sourceContent`: The content of the source file

```js
node.setSourceContent("module-one.scm",
                      fs.readFileSync("path/to/module-one.scm"))
```

#### SourceNode.prototype.walk(fn)

Walk over the tree of JS snippets in this node and its children. The walking
function is called once for each snippet of JS and is passed that snippet and
the its original associated source's line/column location.

* `fn`: The traversal function.

```js
var node = new SourceNode(1, 2, "a.js", [
  new SourceNode(3, 4, "b.js", "uno"),
  "dos",
  [
    "tres",
    new SourceNode(5, 6, "c.js", "quatro")
  ]
]);

node.walk(function (code, loc) { console.log("WALK:", code, loc); })
// WALK: uno { source: 'b.js', line: 3, column: 4, name: null }
// WALK: dos { source: 'a.js', line: 1, column: 2, name: null }
// WALK: tres { source: 'a.js', line: 1, column: 2, name: null }
// WALK: quatro { source: 'c.js', line: 5, column: 6, name: null }
```

#### SourceNode.prototype.walkSourceContents(fn)

Walk over the tree of SourceNodes. The walking function is called for each
source file content and is passed the filename and source content.

* `fn`: The traversal function.

```js
var a = new SourceNode(1, 2, "a.js", "generated from a");
a.setSourceContent("a.js", "original a");
var b = new SourceNode(1, 2, "b.js", "generated from b");
b.setSourceContent("b.js", "original b");
var c = new SourceNode(1, 2, "c.js", "generated from c");
c.setSourceContent("c.js", "original c");

var node = new SourceNode(null, null, null, [a, b, c]);
node.walkSourceContents(function (source, contents) { console.log("WALK:", source, ":", contents); })
// WALK: a.js : original a
// WALK: b.js : original b
// WALK: c.js : original c
```

#### SourceNode.prototype.join(sep)

Like `Array.prototype.join` except for SourceNodes. Inserts the separator
between each of this source node's children.

* `sep`: The separator.

```js
var lhs = new SourceNode(1, 2, "a.rs", "my_copy");
var operand = new SourceNode(3, 4, "a.rs", "=");
var rhs = new SourceNode(5, 6, "a.rs", "orig.clone()");

var node = new SourceNode(null, null, null, [ lhs, operand, rhs ]);
var joinedNode = node.join(" ");
```

#### SourceNode.prototype.replaceRight(pattern, replacement)

Call `String.prototype.replace` on the very right-most source snippet. Useful
for trimming white space from the end of a source node, etc.

* `pattern`: The pattern to replace.

* `replacement`: The thing to replace the pattern with.

```js
// Trim trailing white space.
node.replaceRight(/\s*$/, "");
```

#### SourceNode.prototype.toString()

Return the string representation of this source node. Walks over the tree and
concatenates all the various snippets together to one string.

```js
var node = new SourceNode(1, 2, "a.js", [
  new SourceNode(3, 4, "b.js", "uno"),
  "dos",
  [
    "tres",
    new SourceNode(5, 6, "c.js", "quatro")
  ]
]);

node.toString()
// 'unodostresquatro'
```

#### SourceNode.prototype.toStringWithSourceMap([startOfSourceMap])

Returns the string representation of this tree of source nodes, plus a
SourceMapGenerator which contains all the mappings between the generated and
original sources.

The arguments are the same as those to `new SourceMapGenerator`.

```js
var node = new SourceNode(1, 2, "a.js", [
  new SourceNode(3, 4, "b.js", "uno"),
  "dos",
  [
    "tres",
    new SourceNode(5, 6, "c.js", "quatro")
  ]
]);

node.toStringWithSourceMap({ file: "my-output-file.js" })
// { code: 'unodostresquatro',
//   map: [object SourceMapGenerator] }
```


---

The MIT License (MIT)

Copyright (c) 2014 Evan Wallace

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

# Source Map Support
[![Build Status](https://travis-ci.org/evanw/node-source-map-support.svg?branch=master)](https://travis-ci.org/evanw/node-source-map-support)

This module provides source map support for stack traces in node via the [V8 stack trace API](https://github.com/v8/v8/wiki/Stack-Trace-API). It uses the [source-map](https://github.com/mozilla/source-map) module to replace the paths and line numbers of source-mapped files with their original paths and line numbers. The output mimics node's stack trace format with the goal of making every compile-to-JS language more of a first-class citizen. Source maps are completely general (not specific to any one language) so you can use source maps with multiple compile-to-JS languages in the same node process.

## Installation and Usage

#### Node support

```
$ npm install source-map-support
```

Source maps can be generated using libraries such as [source-map-index-generator](https://github.com/twolfson/source-map-index-generator). Once you have a valid source map, place a source mapping comment somewhere in the file (usually done automatically or with an option by your transpiler):

```
//# sourceMappingURL=path/to/source.map
```

If multiple sourceMappingURL comments exist in one file, the last sourceMappingURL comment will be
respected (e.g. if a file mentions the comment in code, or went through multiple transpilers).
The path should either be absolute or relative to the compiled file.

From here you have two options.

##### CLI Usage

```bash
node -r source-map-support/register compiled.js
```

##### Programmatic Usage

Put the following line at the top of the compiled file.

```js
require('source-map-support').install();
```

It is also possible to install the source map support directly by
requiring the `register` module which can be handy with ES6:

```js
import 'source-map-support/register'

// Instead of:
import sourceMapSupport from 'source-map-support'
sourceMapSupport.install()
```
Note: if you're using babel-register, it includes source-map-support already.

It is also very useful with Mocha:

```
$ mocha --require source-map-support/register tests/
```

#### Browser support

This library also works in Chrome. While the DevTools console already supports source maps, the V8 engine doesn't and `Error.prototype.stack` will be incorrect without this library. Everything will just work if you deploy your source files using [browserify](http://browserify.org/). Just make sure to pass the `--debug` flag to the browserify command so your source maps are included in the bundled code.

This library also works if you use another build process or just include the source files directly. In this case, include the file `browser-source-map-support.js` in your page and call `sourceMapSupport.install()`. It contains the whole library already bundled for the browser using browserify.

```html
<script src="browser-source-map-support.js"></script>
<script>sourceMapSupport.install();</script>
```

This library also works if you use AMD (Asynchronous Module Definition), which is used in tools like [RequireJS](http://requirejs.org/). Just list `browser-source-map-support` as a dependency:

```html
<script>
  define(['browser-source-map-support'], function(sourceMapSupport) {
    sourceMapSupport.install();
  });
</script>
```

## Options

This module installs two things: a change to the `stack` property on `Error` objects and a handler for uncaught exceptions that mimics node's default exception handler (the handler can be seen in the demos below). You may want to disable the handler if you have your own uncaught exception handler. This can be done by passing an argument to the installer:

```js
require('source-map-support').install({
  handleUncaughtExceptions: false
});
```

This module loads source maps from the filesystem by default. You can provide alternate loading behavior through a callback as shown below. For example, [Meteor](https://github.com/meteor) keeps all source maps cached in memory to avoid disk access.

```js
require('source-map-support').install({
  retrieveSourceMap: function(source) {
    if (source === 'compiled.js') {
      return {
        url: 'original.js',
        map: fs.readFileSync('compiled.js.map', 'utf8')
      };
    }
    return null;
  }
});
```

The module will by default assume a browser environment if XMLHttpRequest and window are defined. If either of these do not exist it will instead assume a node environment.
In some rare cases, e.g. when running a browser emulation and where both variables are also set, you can explictly specify the environment to be either 'browser' or 'node'.

```js
require('source-map-support').install({
  environment: 'node'
});
```

To support files with inline source maps, the `hookRequire` options can be specified, which will monitor all source files for inline source maps.


```js
require('source-map-support').install({
  hookRequire: true
});
```

This monkey patches the `require` module loading chain, so is not enabled by default and is not recommended for any sort of production usage.

## Demos

#### Basic Demo

original.js:

```js
throw new Error('test'); // This is the original code
```

compiled.js:

```js
require('source-map-support').install();

throw new Error('test'); // This is the compiled code
// The next line defines the sourceMapping.
//# sourceMappingURL=compiled.js.map
```

compiled.js.map:

```json
{
  "version": 3,
  "file": "compiled.js",
  "sources": ["original.js"],
  "names": [],
  "mappings": ";;AAAA,MAAM,IAAI"
}
```

Run compiled.js using node (notice how the stack trace uses original.js instead of compiled.js):

```
$ node compiled.js

original.js:1
throw new Error('test'); // This is the original code
      ^
Error: test
    at Object.<anonymous> (original.js:1:7)
    at Module._compile (module.js:456:26)
    at Object.Module._extensions..js (module.js:474:10)
    at Module.load (module.js:356:32)
    at Function.Module._load (module.js:312:12)
    at Function.Module.runMain (module.js:497:10)
    at startup (node.js:119:16)
    at node.js:901:3
```

#### TypeScript Demo

demo.ts:

```typescript
declare function require(name: string);
require('source-map-support').install();
class Foo {
  constructor() { this.bar(); }
  bar() { throw new Error('this is a demo'); }
}
new Foo();
```

Compile and run the file using the TypeScript compiler from the terminal:

```
$ npm install source-map-support typescript
$ node_modules/typescript/bin/tsc -sourcemap demo.ts
$ node demo.js

demo.ts:5
  bar() { throw new Error('this is a demo'); }
                ^
Error: this is a demo
    at Foo.bar (demo.ts:5:17)
    at new Foo (demo.ts:4:24)
    at Object.<anonymous> (demo.ts:7:1)
    at Module._compile (module.js:456:26)
    at Object.Module._extensions..js (module.js:474:10)
    at Module.load (module.js:356:32)
    at Function.Module._load (module.js:312:12)
    at Function.Module.runMain (module.js:497:10)
    at startup (node.js:119:16)
    at node.js:901:3
```

There is also the option to use `-r source-map-support/register` with typescript, without the need add the `require('source-map-support').install()` in the code base:

```
$ npm install source-map-support typescript
$ node_modules/typescript/bin/tsc  -sourcemap demo.ts
$ node -r source-map-support/register demo.js

demo.ts:5
  bar() { throw new Error('this is a demo'); }
                ^
Error: this is a demo
    at Foo.bar (demo.ts:5:17)
    at new Foo (demo.ts:4:24)
    at Object.<anonymous> (demo.ts:7:1)
    at Module._compile (module.js:456:26)
    at Object.Module._extensions..js (module.js:474:10)
    at Module.load (module.js:356:32)
    at Function.Module._load (module.js:312:12)
    at Function.Module.runMain (module.js:497:10)
    at startup (node.js:119:16)
    at node.js:901:3
```

#### CoffeeScript Demo

demo.coffee:

```coffee
require('source-map-support').install()
foo = ->
  bar = -> throw new Error 'this is a demo'
  bar()
foo()
```

Compile and run the file using the CoffeeScript compiler from the terminal:

```sh
$ npm install source-map-support coffeescript
$ node_modules/.bin/coffee --map --compile demo.coffee
$ node demo.js

demo.coffee:3
  bar = -> throw new Error 'this is a demo'
                     ^
Error: this is a demo
    at bar (demo.coffee:3:22)
    at foo (demo.coffee:4:3)
    at Object.<anonymous> (demo.coffee:5:1)
    at Object.<anonymous> (demo.coffee:1:1)
    at Module._compile (module.js:456:26)
    at Object.Module._extensions..js (module.js:474:10)
    at Module.load (module.js:356:32)
    at Function.Module._load (module.js:312:12)
    at Function.Module.runMain (module.js:497:10)
    at startup (node.js:119:16)
```

## Tests

This repo contains both automated tests for node and manual tests for the browser. The automated tests can be run using mocha (type `mocha` in the root directory). To run the manual tests:

* Build the tests using `build.js`
* Launch the HTTP server (`npm run serve-tests`) and visit
  * http://127.0.0.1:1336/amd-test
  * http://127.0.0.1:1336/browser-test
  * http://127.0.0.1:1336/browserify-test - **Currently not working** due to a bug with browserify (see [pull request #66](https://github.com/evanw/node-source-map-support/pull/66) for details).
* For `header-test`, run `server.js` inside that directory and visit http://127.0.0.1:1337/

## License

This code is available under the [MIT license](http://opensource.org/licenses/MIT).


---

# space-separated-tokens

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]

Parse and stringify space-separated tokens.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`parse(value)`](#parsevalue)
    *   [`stringify(values)`](#stringifyvalues)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Related](#related)
*   [Contribute](#contribute)
*   [Security](#security)
*   [License](#license)

## What is this?

This is a tiny package that can parse and stringify space-separated tokens, as
used for example in the HTML `class` attribute, according to the
[WHATWG spec][spec].

## When should I use this?

This package is rather niche, it’s low-level and particularly useful when
working with [hast][].

## Install

This package is [ESM only][esm].
In Node.js (version 14.14+, 16.0+), install with [npm][]:

```sh
npm install space-separated-tokens
```

In Deno with [`esm.sh`][esmsh]:

```js
import {parse, stringify} from 'https://esm.sh/space-separated-tokens@2'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {parse, stringify} from 'https://esm.sh/space-separated-tokens@2?bundle'
</script>
```

## Use

```js
import {parse, stringify} from 'space-separated-tokens'

parse(' foo\tbar\nbaz  ')
//=> ['foo', 'bar', 'baz']

stringify(['foo', 'bar', 'baz'])
//=> 'foo bar baz'
```

## API

This package exports the identifiers `parse` and `stringify`.
There is no default export.

### `parse(value)`

Parse space-separated tokens (`string`) to an array of strings
(`Array<string>`), according to the [WHATWG spec][spec].

### `stringify(values)`

Serialize an array of strings or numbers (`Array<string|number>`) to
space-separated tokens (`string`).

> 👉 **Note**: it’s not possible to specify empty or whitespace only values.

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

This package is at least compatible with all maintained versions of Node.js.
As of now, that is Node.js 14.14+ and 16.0+.
It also works in Deno and modern browsers.

## Related

*   [`comma-separated-tokens`](https://github.com/wooorm/comma-separated-tokens)
    — parse/stringify comma-separated tokens
*   [`collapse-white-space`](https://github.com/wooorm/collapse-white-space)
    — replace multiple white-space characters with a single space
*   [`property-information`](https://github.com/wooorm/property-information)
    — info on HTML properties

## Contribute

Yes please!
See [How to Contribute to Open Source][contribute].

## Security

This package is safe.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definition -->

[build-badge]: https://github.com/wooorm/space-separated-tokens/workflows/main/badge.svg

[build]: https://github.com/wooorm/space-separated-tokens/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/space-separated-tokens.svg

[coverage]: https://codecov.io/github/wooorm/space-separated-tokens

[downloads-badge]: https://img.shields.io/npm/dm/space-separated-tokens.svg

[downloads]: https://www.npmjs.com/package/space-separated-tokens

[size-badge]: https://img.shields.io/bundlephobia/minzip/space-separated-tokens.svg

[size]: https://bundlephobia.com/result?p=space-separated-tokens

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[typescript]: https://www.typescriptlang.org

[contribute]: https://opensource.guide/how-to-contribute/

[license]: license

[author]: https://wooorm.com

[spec]: https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#space-separated-tokens

[hast]: https://github.com/syntax-tree/hast


---

# SPDY Server for node.js

[![Build Status](https://travis-ci.org/spdy-http2/node-spdy.svg?branch=master)](http://travis-ci.org/spdy-http2/node-spdy)
[![NPM version](https://badge.fury.io/js/spdy.svg)](http://badge.fury.io/js/spdy)
[![dependencies Status](https://david-dm.org/spdy-http2/node-spdy/status.svg?style=flat-square)](https://david-dm.org/spdy-http2/node-spdy)
[![Standard - JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg?style=flat-square)](http://standardjs.com/)
[![Waffle](https://img.shields.io/badge/track-waffle-blue.svg?style=flat-square)](https://waffle.io/spdy-http2/node-spdy)

With this module you can create [HTTP2][0] / [SPDY][1] servers
in node.js with natural http module interface and fallback to regular https
(for browsers that don't support neither HTTP2, nor SPDY yet).

This module named `spdy` but it [provides](https://github.com/indutny/node-spdy/issues/269#issuecomment-239014184) support for both http/2 (h2) and spdy (2,3,3.1). Also, `spdy` is compatible with Express.

## Usage

### Examples

Server:
```javascript
var spdy = require('spdy'),
    fs = require('fs');

var options = {
  // Private key
  key: fs.readFileSync(__dirname + '/keys/spdy-key.pem'),

  // Fullchain file or cert file (prefer the former)
  cert: fs.readFileSync(__dirname + '/keys/spdy-fullchain.pem'),

  // **optional** SPDY-specific options
  spdy: {
    protocols: [ 'h2', 'spdy/3.1', ..., 'http/1.1' ],
    plain: false,

    // **optional**
    // Parse first incoming X_FORWARDED_FOR frame and put it to the
    // headers of every request.
    // NOTE: Use with care! This should not be used without some proxy that
    // will *always* send X_FORWARDED_FOR
    'x-forwarded-for': true,

    connection: {
      windowSize: 1024 * 1024, // Server's window size

      // **optional** if true - server will send 3.1 frames on 3.0 *plain* spdy
      autoSpdy31: false
    }
  }
};

var server = spdy.createServer(options, function(req, res) {
  res.writeHead(200);
  res.end('hello world!');
});

server.listen(3000);
```

Client:
```javascript
var spdy = require('spdy');
var https = require('https');

var agent = spdy.createAgent({
  host: 'www.google.com',
  port: 443,

  // Optional SPDY options
  spdy: {
    plain: false,
    ssl: true,

    // **optional** send X_FORWARDED_FOR
    'x-forwarded-for': '127.0.0.1'
  }
});

https.get({
  host: 'www.google.com',
  agent: agent
}, function(response) {
  console.log('yikes');
  // Here it goes like with any other node.js HTTP request
  // ...
  // And once we're done - we may close TCP connection to server
  // NOTE: All non-closed requests will die!
  agent.close();
}).end();
```

Please note that if you use a custom agent, by default all connection-level
errors will result in an uncaught exception. To handle these errors subscribe
to the `error` event and re-emit the captured error:

```javascript
var agent = spdy.createAgent({
  host: 'www.google.com',
  port: 443
}).once('error', function (err) {
  this.emit(err);
});
```

#### Push streams

It is possible to initiate [PUSH_PROMISE][5] to send content to clients _before_
the client requests it.

```javascript
spdy.createServer(options, function(req, res) {
  var stream = res.push('/main.js', {
    status: 200, // optional
    method: 'GET', // optional
    request: {
      accept: '*/*'
    },
    response: {
      'content-type': 'application/javascript'
    }
  });
  stream.on('error', function() {
  });
  stream.end('alert("hello from push stream!");');

  res.end('<script src="/main.js"></script>');
}).listen(3000);
```

[PUSH_PROMISE][5] may be sent using the `push()` method on the current response
object.  The signature of the `push()` method is:

`.push('/some/relative/url', { request: {...}, response: {...} }, callback)`

Second argument contains headers for both PUSH_PROMISE and emulated response.
`callback` will receive two arguments: `err` (if any error is happened) and a
[Duplex][4] stream as the second argument.

Client usage:
```javascript
var agent = spdy.createAgent({ /* ... */ });
var req = http.get({
  host: 'www.google.com',
  agent: agent
}, function(response) {
});
req.on('push', function(stream) {
  stream.on('error', function(err) {
    // Handle error
  });
  // Read data from stream
});
```

NOTE: You're responsible for the `stream` object once given it in `.push()`
callback or `push` event. Hence ignoring `error` event on it will result in
uncaught exception and crash your program.

#### Trailing headers

Server usage:
```javascript
function (req, res) {
  // Send trailing headers to client
  res.addTrailers({ header1: 'value1', header2: 'value2' });

  // On client's trailing headers
  req.on('trailers', function(headers) {
    // ...
  });
}
```

Client usage:
```javascript
var req = http.request({ agent: spdyAgent, /* ... */ }).function (res) {
  // On server's trailing headers
  res.on('trailers', function(headers) {
    // ...
  });
});
req.write('stuff');
req.addTrailers({ /* ... */ });
req.end();
```

#### Options

All options supported by [tls][2] work with node-spdy.

Additional options may be passed via `spdy` sub-object:

* `plain` - if defined, server will ignore NPN and ALPN data and choose whether
  to use spdy or plain http by looking at first data packet.
* `ssl` - if `false` and `options.plain` is `true`, `http.Server` will be used
  as a `base` class for created server.
* `maxChunk` - if set and non-falsy, limits number of bytes sent in one DATA
  chunk. Setting it to non-zero value is recommended if you care about
  interleaving of outgoing data from multiple different streams.
  (defaults to 8192)
* `protocols` - list of NPN/ALPN protocols to use (default is:
  `['h2','spdy/3.1', 'spdy/3', 'spdy/2','http/1.1', 'http/1.0']`)
* `protocol` - use specific protocol if no NPN/ALPN ex In addition,
* `maxStreams` - set "[maximum concurrent streams][3]" protocol option

### API

API is compatible with `http` and `https` module, but you can use another
function as base class for SPDYServer.

```javascript
spdy.createServer(
  [base class constructor, i.e. https.Server],
  { /* keys and options */ }, // <- the only one required argument
  [request listener]
).listen([port], [host], [callback]);
```

Request listener will receive two arguments: `request` and `response`. They're
both instances of `http`'s `IncomingMessage` and `OutgoingMessage`. But three
custom properties are added to both of them: `isSpdy`, `spdyVersion`. `isSpdy`
is `true` when the request was processed using HTTP2/SPDY protocols, it is
`false` in case of HTTP/1.1 fallback. `spdyVersion` is either of: `2`, `3`,
`3.1`, or `4` (for HTTP2).


#### Contributors

* [Fedor Indutny](https://github.com/indutny)
* [Chris Strom](https://github.com/eee-c)
* [François de Metz](https://github.com/francois2metz)
* [Ilya Grigorik](https://github.com/igrigorik)
* [Roberto Peon](https://github.com/grmocg)
* [Tatsuhiro Tsujikawa](https://github.com/tatsuhiro-t)
* [Jesse Cravens](https://github.com/jessecravens)

#### LICENSE

This software is licensed under the MIT License.

Copyright Fedor Indutny, 2015.

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to permit
persons to whom the Software is furnished to do so, subject to the
following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
USE OR OTHER DEALINGS IN THE SOFTWARE.

[0]: https://http2.github.io/
[1]: http://www.chromium.org/spdy
[2]: http://nodejs.org/docs/latest/api/tls.html#tls.createServer
[3]: https://httpwg.github.io/specs/rfc7540.html#SETTINGS_MAX_CONCURRENT_STREAMS
[4]: https://iojs.org/api/stream.html#stream_class_stream_duplex
[5]: https://httpwg.github.io/specs/rfc7540.html#PUSH_PROMISE


---

# spdy-transport

[![Build Status](https://travis-ci.org/spdy-http2/spdy-transport.svg?branch=master)](http://travis-ci.org/spdy-http2/spdy-transport)
[![NPM version](https://badge.fury.io/js/spdy-transport.svg)](http://badge.fury.io/js/spdy-transport)
[![dependencies Status](https://david-dm.org/spdy-http2/spdy-transport/status.svg?style=flat-square)](https://david-dm.org/spdy-http2/spdy-transport)
[![Standard - JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg?style=flat-square)](http://standardjs.com/)
[![Waffle](https://img.shields.io/badge/track-waffle-blue.svg?style=flat-square)](https://waffle.io/spdy-http2/node-spdy)

> SPDY/HTTP2 generic transport implementation.

## Usage

```javascript
var transport = require('spdy-transport');

// NOTE: socket is some stream or net.Socket instance, may be an argument
// of `net.createServer`'s connection handler.

var server = transport.connection.create(socket, {
  protocol: 'http2',
  isServer: true
});

server.on('stream', function(stream) {
  console.log(stream.method, stream.path, stream.headers);
  stream.respond(200, {
    header: 'value'
  });

  stream.on('readable', function() {
    var chunk = stream.read();
    if (!chunk)
      return;

    console.log(chunk);
  });

  stream.on('end', function() {
    console.log('end');
  });

  // And other node.js Stream APIs
  // ...
});
```

## LICENSE

This software is licensed under the MIT License.

Copyright Fedor Indutny, 2015.

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to permit
persons to whom the Software is furnished to do so, subject to the
following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
USE OR OTHER DEALINGS IN THE SOFTWARE.

[0]: http://json.org/
[1]: http://github.com/indutny/bud-backend
[2]: https://github.com/nodejs/io.js
[3]: https://github.com/libuv/libuv
[4]: http://openssl.org/


---

# sprintf.js
**sprintf.js** is a complete open source JavaScript sprintf implementation for the *browser* and *node.js*.

Its prototype is simple:

    string sprintf(string format , [mixed arg1 [, mixed arg2 [ ,...]]])

The placeholders in the format string are marked by `%` and are followed by one or more of these elements, in this order:

* An optional number followed by a `$` sign that selects which argument index to use for the value. If not specified, arguments will be placed in the same order as the placeholders in the input string.
* An optional `+` sign that forces to preceed the result with a plus or minus sign on numeric values. By default, only the `-` sign is used on negative numbers.
* An optional padding specifier that says what character to use for padding (if specified). Possible values are `0` or any other character precedeed by a `'` (single quote). The default is to pad with *spaces*.
* An optional `-` sign, that causes sprintf to left-align the result of this placeholder. The default is to right-align the result.
* An optional number, that says how many characters the result should have. If the value to be returned is shorter than this number, the result will be padded. When used with the `j` (JSON) type specifier, the padding length specifies the tab size used for indentation.
* An optional precision modifier, consisting of a `.` (dot) followed by a number, that says how many digits should be displayed for floating point numbers. When used with the `g` type specifier, it specifies the number of significant digits. When used on a string, it causes the result to be truncated.
* A type specifier that can be any of:
    * `%` — yields a literal `%` character
    * `b` — yields an integer as a binary number
    * `c` — yields an integer as the character with that ASCII value
    * `d` or `i` — yields an integer as a signed decimal number
    * `e` — yields a float using scientific notation
    * `u` — yields an integer as an unsigned decimal number
    * `f` — yields a float as is; see notes on precision above
    * `g` — yields a float as is; see notes on precision above
    * `o` — yields an integer as an octal number
    * `s` — yields a string as is
    * `x` — yields an integer as a hexadecimal number (lower-case)
    * `X` — yields an integer as a hexadecimal number (upper-case)
    * `j` — yields a JavaScript object or array as a JSON encoded string

## JavaScript `vsprintf`
`vsprintf` is the same as `sprintf` except that it accepts an array of arguments, rather than a variable number of arguments:

    vsprintf("The first 4 letters of the english alphabet are: %s, %s, %s and %s", ["a", "b", "c", "d"])

## Argument swapping
You can also swap the arguments. That is, the order of the placeholders doesn't have to match the order of the arguments. You can do that by simply indicating in the format string which arguments the placeholders refer to:

    sprintf("%2$s %3$s a %1$s", "cracker", "Polly", "wants")
And, of course, you can repeat the placeholders without having to increase the number of arguments.

## Named arguments
Format strings may contain replacement fields rather than positional placeholders. Instead of referring to a certain argument, you can now refer to a certain key within an object. Replacement fields are surrounded by rounded parentheses - `(` and `)` - and begin with a keyword that refers to a key:

    var user = {
        name: "Dolly"
    }
    sprintf("Hello %(name)s", user) // Hello Dolly
Keywords in replacement fields can be optionally followed by any number of keywords or indexes:

    var users = [
        {name: "Dolly"},
        {name: "Molly"},
        {name: "Polly"}
    ]
    sprintf("Hello %(users[0].name)s, %(users[1].name)s and %(users[2].name)s", {users: users}) // Hello Dolly, Molly and Polly
Note: mixing positional and named placeholders is not (yet) supported

## Computed values
You can pass in a function as a dynamic value and it will be invoked (with no arguments) in order to compute the value on-the-fly.

    sprintf("Current timestamp: %d", Date.now) // Current timestamp: 1398005382890
    sprintf("Current date and time: %s", function() { return new Date().toString() })

# AngularJS
You can now use `sprintf` and `vsprintf` (also aliased as `fmt` and `vfmt` respectively) in your AngularJS projects. See `demo/`.

# Installation

## Via Bower

    bower install sprintf

## Or as a node.js module

    npm install sprintf-js

### Usage

    var sprintf = require("sprintf-js").sprintf,
        vsprintf = require("sprintf-js").vsprintf

    sprintf("%2$s %3$s a %1$s", "cracker", "Polly", "wants")
    vsprintf("The first 4 letters of the english alphabet are: %s, %s, %s and %s", ["a", "b", "c", "d"])

# License

**sprintf.js** is licensed under the terms of the 3-clause BSD license.


---

# srcset

> Parse and stringify the HTML `<img>` [srcset](https://www.smashingmagazine.com/2013/08/webkit-implements-srcset-and-why-its-a-good-thing/) attribute.

Can be useful if you're creating a build-tool.

## Install

```
$ npm install srcset
```

## Usage

How an image with `srcset` might look like:

```html
<img
	alt="The Breakfast Combo"
	src="banner.jpg"
	srcset="banner-HD.jpg 2x, banner-phone.jpg 100w"
>
```

Then have some fun with it:

```js
const srcset = require('srcset');

const parsed = srcset.parse('banner-HD.jpg 2x, banner-phone.jpg 100w');
console.log(parsed);
/*
[
	{
		url: 'banner-HD.jpg',
		density: 2
	},
	{
		url: 'banner-phone.jpg',
		width: 100
	}
]
*/

parsed.push({
	url: 'banner-super-HD.jpg',
	density: 3
});

const stringified = srcset.stringify(parsed);
console.log(stringified);
/*
banner-HD.jpg 2x, banner-phone.jpg 100w, banner-super-HD.jpg 3x
*/
```

## API

### .parse(string, options?)

Parse the HTML `<img>` [srcset](http://mobile.smashingmagazine.com/2013/08/21/webkit-implements-srcset-and-why-its-a-good-thing/) attribute.

Accepts a “srcset” string and returns an array of objects with the possible properties: `url` (always), `width`, `height`, and `density`.

#### string

Type: `string`

A “srcset” string.

#### options

Type: `object`

##### strict

Type: `boolean`\
Default: `false`

When enabled, an invalid “srcset” string will cause an error to be thrown. When disabled, a best effort will be made to parse the string, potentially resulting in invalid or nonsensical output.

### .stringify(SrcSetDefinitions, options?)

Stringify `SrcSetDefinition`s. Accepts an array of `SrcSetDefinition` objects and returns a “srcset” string.

#### srcsetDescriptors

Type: `array`

An array of `SrcSetDefinition` objects. Each object should have a `url` field and may have `width`, `height` or `density` fields. When the `strict` option is `true`, only `width` or `density` is accepted.

#### options

Type: `object`

##### strict

Type: `boolean`

Default: `false`

Enable or disable validation of the SrcSetDefinitions. When true, invalid input will cause an error to be thrown. When false, a best effort will be made to stringify invalid input, likely resulting in invalid srcset value.

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-srcset?utm_source=npm-srcset&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

2.0.1 / 2021-01-03
==================

  * Fix returning values from `Object.prototype`

2.0.0 / 2020-04-19
==================

  * Drop support for Node.js 0.6
  * Fix messaging casing of `418 I'm a Teapot`
  * Remove code 306
  * Remove `status[code]` exports; use `status.message[code]`
  * Remove `status[msg]` exports; use `status.code[msg]`
  * Rename `425 Unordered Collection` to standard `425 Too Early`
  * Rename `STATUS_CODES` export to `message`
  * Return status message for `statuses(code)` when given code

1.5.0 / 2018-03-27
==================

  * Add `103 Early Hints`

1.4.0 / 2017-10-20
==================

  * Add `STATUS_CODES` export

1.3.1 / 2016-11-11
==================

  * Fix return type in JSDoc

1.3.0 / 2016-05-17
==================

  * Add `421 Misdirected Request`
  * perf: enable strict mode

1.2.1 / 2015-02-01
==================

  * Fix message for status 451
    - `451 Unavailable For Legal Reasons`

1.2.0 / 2014-09-28
==================

  * Add `208 Already Repored`
  * Add `226 IM Used`
  * Add `306 (Unused)`
  * Add `415 Unable For Legal Reasons`
  * Add `508 Loop Detected`

1.1.1 / 2014-09-24
==================

  * Add missing 308 to `codes.json`

1.1.0 / 2014-09-21
==================

  * Add `codes.json` for universal support

1.0.4 / 2014-08-20
==================

  * Package cleanup

1.0.3 / 2014-06-08
==================

  * Add 308 to `.redirect` category

1.0.2 / 2014-03-13
==================

  * Add `.retry` category

1.0.1 / 2014-03-12
==================

  * Initial release


---

# statuses

[![NPM Version][npm-version-image]][npm-url]
[![NPM Downloads][npm-downloads-image]][npm-url]
[![Node.js Version][node-version-image]][node-version-url]
[![Build Status][ci-image]][ci-url]
[![Test Coverage][coveralls-image]][coveralls-url]

HTTP status utility for node.

This module provides a list of status codes and messages sourced from
a few different projects:

  * The [IANA Status Code Registry](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml)
  * The [Node.js project](https://nodejs.org/)
  * The [NGINX project](https://www.nginx.com/)
  * The [Apache HTTP Server project](https://httpd.apache.org/)

## Installation

This is a [Node.js](https://nodejs.org/en/) module available through the
[npm registry](https://www.npmjs.com/). Installation is done using the
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):

```sh
$ npm install statuses
```

## API

<!-- eslint-disable no-unused-vars -->

```js
var status = require('statuses')
```

### status(code)

Returns the status message string for a known HTTP status code. The code
may be a number or a string. An error is thrown for an unknown status code.

<!-- eslint-disable no-undef -->

```js
status(403) // => 'Forbidden'
status('403') // => 'Forbidden'
status(306) // throws
```

### status(msg)

Returns the numeric status code for a known HTTP status message. The message
is case-insensitive. An error is thrown for an unknown status message.

<!-- eslint-disable no-undef -->

```js
status('forbidden') // => 403
status('Forbidden') // => 403
status('foo') // throws
```

### status.codes

Returns an array of all the status codes as `Integer`s.

### status.code[msg]

Returns the numeric status code for a known status message (in lower-case),
otherwise `undefined`.

<!-- eslint-disable no-undef, no-unused-expressions -->

```js
status['not found'] // => 404
```

### status.empty[code]

Returns `true` if a status code expects an empty body.

<!-- eslint-disable no-undef, no-unused-expressions -->

```js
status.empty[200] // => undefined
status.empty[204] // => true
status.empty[304] // => true
```

### status.message[code]

Returns the string message for a known numeric status code, otherwise
`undefined`. This object is the same format as the
[Node.js http module `http.STATUS_CODES`](https://nodejs.org/dist/latest/docs/api/http.html#http_http_status_codes).

<!-- eslint-disable no-undef, no-unused-expressions -->

```js
status.message[404] // => 'Not Found'
```

### status.redirect[code]

Returns `true` if a status code is a valid redirect status.

<!-- eslint-disable no-undef, no-unused-expressions -->

```js
status.redirect[200] // => undefined
status.redirect[301] // => true
```

### status.retry[code]

Returns `true` if you should retry the rest.

<!-- eslint-disable no-undef, no-unused-expressions -->

```js
status.retry[501] // => undefined
status.retry[503] // => true
```

## License

[MIT](LICENSE)

[ci-image]: https://badgen.net/github/checks/jshttp/statuses/master?label=ci
[ci-url]: https://github.com/jshttp/statuses/actions?query=workflow%3Aci
[coveralls-image]: https://badgen.net/coveralls/c/github/jshttp/statuses/master
[coveralls-url]: https://coveralls.io/r/jshttp/statuses?branch=master
[node-version-image]: https://badgen.net/npm/node/statuses
[node-version-url]: https://nodejs.org/en/download
[npm-downloads-image]: https://badgen.net/npm/dm/statuses
[npm-url]: https://npmjs.org/package/statuses
[npm-version-image]: https://badgen.net/npm/v/statuses


---

# std-env

[![npm](https://img.shields.io/npm/dm/std-env.svg?style=flat-square)](http://npmjs.com/package/std-env)
[![npm](https://img.shields.io/npm/v/std-env.svg?style=flat-square)](http://npmjs.com/package/std-env)
[![bundlephobia](https://img.shields.io/bundlephobia/min/std-env/latest.svg?style=flat-square)](https://bundlephobia.com/result?p=std-env)

> Runtime agnostic JS utils

## Installation

```sh
# Using npm
npm i std-env

# Using pnpm
pnpm i std-env

# Using yarn
yarn add std-env
```

## Usage

```js
// ESM
import { env, isDevelopment, isProduction } from "std-env";

// CommonJS
const { env, isDevelopment, isProduction } = require("std-env");
```

## Flags

- `hasTTY`
- `hasWindow`
- `isDebug`
- `isDevelopment`
- `isLinux`
- `isMacOS`
- `isMinimal`
- `isProduction`
- `isTest`
- `isWindows`
- `platform`
- `isColorSupported`
- `nodeVersion`
- `nodeMajorVersion`

You can read more about how each flag works from [./src/flags.ts](./src/flags.ts).

## Provider Detection

`std-env` can automatically detect the current runtime provider based on environment variables.

You can use `isCI` and `platform` exports to detect it:

```ts
import { isCI, provider, providerInfo } from "std-env";

console.log({
  isCI, // true
  provider, // "github_actions"
  providerInfo, // { name: "github_actions", isCI: true }
});
```

List of well known providers can be found from [./src/providers.ts](./src/providers.ts).

## Runtime Detection

`std-env` can automatically detect the current JavaScript runtime based on global variables, following the [WinterCG Runtime Keys proposal](https://runtime-keys.proposal.wintercg.org/):

```ts
import { runtime, runtimeInfo } from "std-env";

// "" | "node" | "deno" | "bun" | "workerd" ...
console.log(runtime);

// { name: "node" }
console.log(runtimeInfo);
```

You can also use individual named exports for each runtime detection:

> [!NOTE]
> When running code in Bun and Deno with Node.js compatibility mode, `isNode` flag will be also `true`, indicating running in a Node.js compatible runtime.
>
> Use `runtime === "node"` if you need strict check for Node.js runtime.

- `isNode`
- `isBun`
- `isDeno`
- `isNetlify`
- `isEdgeLight`
- `isWorkerd`
- `isFastly`

List of well known providers can be found from [./src/runtimes.ts](./src/runtimes.ts).

## Platform-Agnostic `env`

`std-env` provides a lightweight proxy to access environment variables in a platform agnostic way.

```ts
import { env } from "std-env";
```

## Platform-Agnostic `process`

`std-env` provides a lightweight proxy to access [`process`](https://nodejs.org/api/process.html) object in a platform agnostic way.

```ts
import { process } from "std-env";
```

## License

MIT


---

# ansi-regex

> Regular expression for matching [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code)

## Install

```sh
npm install ansi-regex
```

## Usage

```js
import ansiRegex from 'ansi-regex';

ansiRegex().test('\u001B[4mcake\u001B[0m');
//=> true

ansiRegex().test('cake');
//=> false

'\u001B[4mcake\u001B[0m'.match(ansiRegex());
//=> ['\u001B[4m', '\u001B[0m']

'\u001B[4mcake\u001B[0m'.match(ansiRegex({onlyFirst: true}));
//=> ['\u001B[4m']

'\u001B]8;;https://github.com\u0007click\u001B]8;;\u0007'.match(ansiRegex());
//=> ['\u001B]8;;https://github.com\u0007', '\u001B]8;;\u0007']
```

## API

### ansiRegex(options?)

Returns a regex for matching ANSI escape codes.

#### options

Type: `object`

##### onlyFirst

Type: `boolean`\
Default: `false` *(Matches any ANSI escape codes in a string)*

Match only the first ANSI escape.

## FAQ

### Why do you test for codes not in the ECMA 48 standard?

Some of the codes we run as a test are codes that we acquired finding various lists of non-standard or manufacturer specific codes. We test for both standard and non-standard codes, as most of them follow the same or similar format and can be safely matched in strings without the risk of removing actual string content. There are a few non-standard control codes that do not follow the traditional format (i.e. they end in numbers) thus forcing us to exclude them from the test because we cannot reliably match them.

On the historical side, those ECMA standards were established in the early 90's whereas the VT100, for example, was designed in the mid/late 70's. At that point in time, control codes were still pretty ungoverned and engineers used them for a multitude of things, namely to activate hardware ports that may have been proprietary. Somewhere else you see a similar 'anarchy' of codes is in the x86 architecture for processors; there are a ton of "interrupts" that can mean different things on certain brands of processors, most of which have been phased out.

## Maintainers

- [Sindre Sorhus](https://github.com/sindresorhus)
- [Josh Junon](https://github.com/qix-)


---

# strip-ansi

> Strip [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code) from a string

## Install

```
$ npm install strip-ansi
```

## Usage

```js
import stripAnsi from 'strip-ansi';

stripAnsi('\u001B[4mUnicorn\u001B[0m');
//=> 'Unicorn'

stripAnsi('\u001B]8;;https://github.com\u0007Click\u001B]8;;\u0007');
//=> 'Click'
```

## strip-ansi for enterprise

Available as part of the Tidelift Subscription.

The maintainers of strip-ansi and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-strip-ansi?utm_source=npm-strip-ansi&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)

## Related

- [strip-ansi-cli](https://github.com/chalk/strip-ansi-cli) - CLI for this module
- [strip-ansi-stream](https://github.com/chalk/strip-ansi-stream) - Streaming version of this module
- [has-ansi](https://github.com/chalk/has-ansi) - Check if a string has ANSI escape codes
- [ansi-regex](https://github.com/chalk/ansi-regex) - Regular expression for matching ANSI escape codes
- [chalk](https://github.com/chalk/chalk) - Terminal string styling done right

## Maintainers

- [Sindre Sorhus](https://github.com/sindresorhus)
- [Josh Junon](https://github.com/qix-)



---

# string-width

> Get the visual width of a string - the number of columns required to display it

Some Unicode characters are [fullwidth](https://en.wikipedia.org/wiki/Halfwidth_and_fullwidth_forms) and use double the normal width. [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code) are stripped and doesn't affect the width.

Useful to be able to measure the actual width of command-line output.

## Install

```
$ npm install string-width
```

## Usage

```js
import stringWidth from 'string-width';

stringWidth('a');
//=> 1

stringWidth('古');
//=> 2

stringWidth('\u001B[1m古\u001B[22m');
//=> 2
```

## API

### stringWidth(string, options?)

#### string

Type: `string`

The string to be counted.

#### options

Type: `object`

##### ambiguousIsNarrow

Type: `boolean`\
Default: `false`

Count [ambiguous width characters](https://www.unicode.org/reports/tr11/#Ambiguous) as having narrow width (count of 1) instead of wide width (count of 2).

## Related

- [string-width-cli](https://github.com/sindresorhus/string-width-cli) - CLI for this module
- [string-length](https://github.com/sindresorhus/string-length) - Get the real length of a string
- [widest-line](https://github.com/sindresorhus/widest-line) - Get the visual width of the widest line in a string

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-string-width?utm_source=npm-string-width&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

# string_decoder

***Node-core v8.9.4 string_decoder for userland***


[![NPM](https://nodei.co/npm/string_decoder.png?downloads=true&downloadRank=true)](https://nodei.co/npm/string_decoder/)
[![NPM](https://nodei.co/npm-dl/string_decoder.png?&months=6&height=3)](https://nodei.co/npm/string_decoder/)


```bash
npm install --save string_decoder
```

***Node-core string_decoder for userland***

This package is a mirror of the string_decoder implementation in Node-core.

Full documentation may be found on the [Node.js website](https://nodejs.org/dist/v8.9.4/docs/api/).

As of version 1.0.0 **string_decoder** uses semantic versioning.

## Previous versions

Previous version numbers match the versions found in Node core, e.g. 0.10.24 matches Node 0.10.24, likewise 0.11.10 matches Node 0.11.10.

## Update

The *build/* directory contains a build script that will scrape the source from the [nodejs/node](https://github.com/nodejs/node) repo given a specific Node version.

## Streams Working Group

`string_decoder` is maintained by the Streams Working Group, which
oversees the development and maintenance of the Streams API within
Node.js. The responsibilities of the Streams Working Group include:

* Addressing stream issues on the Node.js issue tracker.
* Authoring and editing stream documentation within the Node.js project.
* Reviewing changes to stream subclasses within the Node.js project.
* Redirecting changes to streams from the Node.js project to this
  project.
* Assisting in the implementation of stream providers within Node.js.
* Recommending versions of `readable-stream` to be included in Node.js.
* Messaging about the future of streams to give the community advance
  notice of changes.

See [readable-stream](https://github.com/nodejs/readable-stream) for
more details.


---

# stringify-entities

[![Build Status][build-badge]][build]
[![Coverage Status][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]

Serialize (encode) HTML character references.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`stringifyEntities(value[, options])`](#stringifyentitiesvalue-options)
*   [Algorithm](#algorithm)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Security](#security)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This is a small and powerful encoder of HTML character references (often called
entities).
This one has either all the options you need for a minifier/formatter, or a
tiny size when using `stringifyEntitiesLight`.

## When should I use this?

You can use this for spec-compliant encoding of character references.
It’s small and fast enough to do that well.
You can also use this when making an HTML formatter or minifier, because there
are different ways to produce pretty or tiny output.
This package is reliable: ``'`'`` characters are encoded to ensure no scripts
run in Internet Explorer 6 to 8.
Additionally, only named references recognized by HTML 4 are encoded, meaning
the infamous `&apos;` (which people think is a [virus][]) won’t show up.

## Install

This package is [ESM only][esm].
In Node.js (version 14.14+, 16.0+), install with [npm][]:

```sh
npm install stringify-entities
```

In Deno with [`esm.sh`][esmsh]:

```js
import {stringifyEntities} from 'https://esm.sh/stringify-entities@4'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {stringifyEntities} from 'https://esm.sh/stringify-entities@4?bundle'
</script>
```

## Use

```js
import {stringifyEntities} from 'stringify-entities'

stringifyEntities('alpha © bravo ≠ charlie 𝌆 delta')
// => 'alpha &#xA9; bravo &#x2260; charlie &#x1D306; delta'

stringifyEntities('alpha © bravo ≠ charlie 𝌆 delta', {useNamedReferences: true})
// => 'alpha &copy; bravo &ne; charlie &#x1D306; delta'
```

## API

This package exports the identifiers `stringifyEntities` and
`stringifyEntitiesLight`.
There is no default export.

### `stringifyEntities(value[, options])`

Encode special characters in `value`.

##### Core options

###### `options.escapeOnly`

Whether to only escape possibly dangerous characters (`boolean`, default:
`false`).
Those characters are `"`, `&`, `'`, `<`, `>`, and `` ` ``.

###### `options.subset`

Whether to only escape the given subset of characters (`Array<string>`).
Note that only BMP characters are supported here (so no emoji).

##### Formatting options

If you do not care about the following options, use `stringifyEntitiesLight`,
which always outputs hexadecimal character references.

###### `options.useNamedReferences`

Prefer named character references (`&amp;`) where possible (`boolean?`, default:
`false`).

###### `options.useShortestReferences`

Prefer the shortest possible reference, if that results in less bytes
(`boolean?`, default: `false`).

> ⚠️ **Note**: `useNamedReferences` can be omitted when using
> `useShortestReferences`.

###### `options.omitOptionalSemicolons`

Whether to omit semicolons when possible (`boolean?`, default: `false`).

> ⚠️ **Note**: This creates what HTML calls “parse errors” but is otherwise
> still valid HTML — don’t use this except when building a minifier.
> Omitting semicolons is possible for certain named and numeric references in
> some cases.

###### `options.attribute`

Create character references which don’t fail in attributes (`boolean?`, default:
`false`).

> ⚠️ **Note**: `attribute` only applies when operating dangerously with
> `omitOptionalSemicolons: true`.

#### Returns

Encoded value (`string`).

## Algorithm

By default, all dangerous, non-ASCII, and non-printable ASCII characters are
encoded.
A [subset][] of characters can be given to encode just those characters.
Alternatively, pass [`escapeOnly`][escapeonly] to escape just the dangerous
characters (`"`, `'`, `<`, `>`, `&`, `` ` ``).
By default, hexadecimal character references are used.
Pass [`useNamedReferences`][named] to use named character references when
possible, or [`useShortestReferences`][short] to use whichever is shortest:
decimal, hexadecimal, or named.
There is also a `stringifyEntitiesLight` export, which works just like
`stringifyEntities` but without the formatting options: it’s much smaller but
always outputs hexadecimal character references.

## Types

This package is fully typed with [TypeScript][].
It exports the additional types `Options` and `LightOptions` types.

## Compatibility

This package is at least compatible with all maintained versions of Node.js.
As of now, that is Node.js 14.14+ and 16.0+.
It also works in Deno and modern browsers.

## Security

This package is safe.

## Related

*   [`parse-entities`](https://github.com/wooorm/parse-entities)
    — parse (decode) HTML character references
*   [`wooorm/character-entities`](https://github.com/wooorm/character-entities)
    — info on character references
*   [`wooorm/character-entities-html4`](https://github.com/wooorm/character-entities-html4)
    — info on HTML 4 character references
*   [`wooorm/character-entities-legacy`](https://github.com/wooorm/character-entities-legacy)
    — info on legacy character references
*   [`wooorm/character-reference-invalid`](https://github.com/wooorm/character-reference-invalid)
    — info on invalid numeric character references

## Contribute

Yes please!
See [How to Contribute to Open Source][contribute].

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/wooorm/stringify-entities/workflows/main/badge.svg

[build]: https://github.com/wooorm/stringify-entities/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/stringify-entities.svg

[coverage]: https://codecov.io/github/wooorm/stringify-entities

[downloads-badge]: https://img.shields.io/npm/dm/stringify-entities.svg

[downloads]: https://www.npmjs.com/package/stringify-entities

[size-badge]: https://img.shields.io/bundlephobia/minzip/stringify-entities.svg

[size]: https://bundlephobia.com/result?p=stringify-entities

[npm]: https://docs.npmjs.com/cli/install

[esmsh]: https://esm.sh

[license]: license

[author]: https://wooorm.com

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[typescript]: https://www.typescriptlang.org

[contribute]: https://opensource.guide/how-to-contribute/

[virus]: https://www.telegraph.co.uk/technology/advice/10516839/Why-do-some-apostrophes-get-replaced-with-andapos.html

[subset]: #optionssubset

[escapeonly]: #optionsescapeonly

[named]: #optionsusenamedreferences

[short]: #optionsuseshortestreferences


---

# stringify-object [![Build Status](https://secure.travis-ci.org/yeoman/stringify-object.svg?branch=master)](http://travis-ci.org/yeoman/stringify-object)

> Stringify an object/array like JSON.stringify just without all the double-quotes

Useful for when you want to get the string representation of an object in a formatted way.

It also handles circular references and lets you specify quote type.


## Install

```
$ npm install stringify-object
```


## Usage

```js
const stringifyObject = require('stringify-object');

const obj = {
	foo: 'bar',
	'arr': [1, 2, 3],
	nested: { hello: "world" }
};

const pretty = stringifyObject(obj, {
	indent: '  ',
	singleQuotes: false
});

console.log(pretty);
/*
{
	foo: "bar",
	arr: [
		1,
		2,
		3
	],
	nested: {
		hello: "world"
	}
}
*/
```


## API

### stringifyObject(input, [options])

Circular references will be replaced with `"[Circular]"`.

#### input

Type: `Object` `Array`

#### options

##### indent

Type: `string`<br>
Default: `\t`

Preferred indentation.

##### singleQuotes

Type: `boolean`<br>
Default: `true`

Set to false to get double-quoted strings.

##### filter(obj, prop)

Type: `Function`

Expected to return a `boolean` of whether to include the property `prop` of the object `obj` in the output.

##### transform(obj, prop, originalResult)

Type: `Function`<br>
Default: `undefined`

Expected to return a `string` that transforms the string that resulted from stringifying `obj[prop]`. This can be used to detect special types of objects that need to be stringified in a particular way. The `transform` function might return an alternate string in this case, otherwise returning the `originalResult`.

Here's an example that uses the `transform` option to mask fields named "password":

```js
const obj = {
	user: 'becky',
	password: 'secret'
}

const pretty = stringifyObject(obj, {
	transform: (obj, prop, originalResult) => {
		if (prop === 'password') {
			return originalResult.replace(/\w/g, '*');
		} else {
			return originalResult;
		}
	}
});

console.log(pretty);
/*
{
	user: 'becky',
	password: '******'
}
*/
```


##### inlineCharacterLimit

Type: `number`

When set, will inline values up to `inlineCharacterLimit` length for the sake of more terse output.

For example, given the example at the top of the README:

```js
const obj = {
	foo: 'bar',
	'arr': [1, 2, 3],
	nested: { hello: "world" }
};

const pretty = stringifyObject(obj, {
	indent: '  ',
	singleQuotes: false,
	inlineCharacterLimit: 12
});

console.log(pretty);
/*
{
	foo: "bar",
	arr: [1, 2, 3],
	nested: {
		hello: "world"
	}
}
*/
```

As you can see, `arr` was printed as a one-liner because its string was shorter than 12 characters.


## License

BSD-2-Clause © Yeoman team


---

# strip-ansi [![Build Status](https://travis-ci.org/chalk/strip-ansi.svg?branch=master)](https://travis-ci.org/chalk/strip-ansi)

> Strip [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code) from a string


## Install

```
$ npm install strip-ansi
```


## Usage

```js
const stripAnsi = require('strip-ansi');

stripAnsi('\u001B[4mUnicorn\u001B[0m');
//=> 'Unicorn'

stripAnsi('\u001B]8;;https://github.com\u0007Click\u001B]8;;\u0007');
//=> 'Click'
```


## strip-ansi for enterprise

Available as part of the Tidelift Subscription.

The maintainers of strip-ansi and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-strip-ansi?utm_source=npm-strip-ansi&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)


## Related

- [strip-ansi-cli](https://github.com/chalk/strip-ansi-cli) - CLI for this module
- [strip-ansi-stream](https://github.com/chalk/strip-ansi-stream) - Streaming version of this module
- [has-ansi](https://github.com/chalk/has-ansi) - Check if a string has ANSI escape codes
- [ansi-regex](https://github.com/chalk/ansi-regex) - Regular expression for matching ANSI escape codes
- [chalk](https://github.com/chalk/chalk) - Terminal string styling done right


## Maintainers

- [Sindre Sorhus](https://github.com/sindresorhus)
- [Josh Junon](https://github.com/qix-)



---

# strip-bom-string [![NPM version](https://img.shields.io/npm/v/strip-bom-string.svg?style=flat)](https://www.npmjs.com/package/strip-bom-string) [![NPM monthly downloads](https://img.shields.io/npm/dm/strip-bom-string.svg?style=flat)](https://npmjs.org/package/strip-bom-string)  [![NPM total downloads](https://img.shields.io/npm/dt/strip-bom-string.svg?style=flat)](https://npmjs.org/package/strip-bom-string) [![Linux Build Status](https://img.shields.io/travis/jonschlinkert/strip-bom-string.svg?style=flat&label=Travis)](https://travis-ci.org/jonschlinkert/strip-bom-string)

> Strip a byte order mark (BOM) from a string.

## Install

Install with [npm](https://www.npmjs.com/):

```sh
$ npm install --save strip-bom-string
```

## Usage

```js
var strip = require('strip-bom-string');
strip('\ufefffoo');
//=> 'foo'
```

## About

### Related projects

* [cr](https://www.npmjs.com/package/cr): Strip windows carriage returns, or convert carriage returns to newlines. | [homepage](https://github.com/jonschlinkert/cr "Strip windows carriage returns, or convert carriage returns to newlines.")
* [has-bom](https://www.npmjs.com/package/has-bom): Returns true if a buffer or string has a byte order mark (BOM) | [homepage](https://github.com/jonschlinkert/has-bom "Returns true if a buffer or string has a byte order mark (BOM)")
* [read-file](https://www.npmjs.com/package/read-file): Thin wrapper around fs.readFile and fs.readFileSync that also strips byte order marks when `utf8` encoding… [more](https://github.com/jonschlinkert/read-file) | [homepage](https://github.com/jonschlinkert/read-file "Thin wrapper around fs.readFile and fs.readFileSync that also strips byte order marks when `utf8` encoding is chosen. Also optionally replaces windows newlines with unix newlines.")
* [strip-bom-buffer](https://www.npmjs.com/package/strip-bom-buffer): Strip a byte order mark (BOM) from a buffer. | [homepage](https://github.com/jonschlinkert/strip-bom-buffer "Strip a byte order mark (BOM) from a buffer.")

### Contributing

Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).

### Building docs

_(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_

To generate the readme, run the following command:

```sh
$ npm install -g verbose/verb#dev verb-generate-readme && verb
```

### Running tests

Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

```sh
$ npm install && npm test
```

### Author

**Jon Schlinkert**

* [github/jonschlinkert](https://github.com/jonschlinkert)
* [twitter/jonschlinkert](https://twitter.com/jonschlinkert)

### License

Copyright © 2017, [Jon Schlinkert](https://github.com/jonschlinkert).
Released under the [MIT License](LICENSE).

***

_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.4.3, on March 29, 2017._

---

# strip-final-newline [![Build Status](https://travis-ci.com/sindresorhus/strip-final-newline.svg?branch=master)](https://travis-ci.com/sindresorhus/strip-final-newline)

> Strip the final [newline character](https://en.wikipedia.org/wiki/Newline) from a string/buffer

Can be useful when parsing the output of, for example, `ChildProcess#execFile`, as [binaries usually output a newline at the end](https://stackoverflow.com/questions/729692/why-should-text-files-end-with-a-newline). Normally, you would use `stdout.trim()`, but that would also remove newlines at the start and whitespace.


## Install

```
$ npm install strip-final-newline
```


## Usage

```js
const stripFinalNewline = require('strip-final-newline');

stripFinalNewline('foo\nbar\n\n');
//=> 'foo\nbar\n'

stripFinalNewline(Buffer.from('foo\nbar\n\n')).toString();
//=> 'foo\nbar\n'
```


## License

MIT © [Sindre Sorhus](https://sindresorhus.com)


---

# strip-json-comments [![Build Status](https://travis-ci.com/sindresorhus/strip-json-comments.svg?branch=master)](https://travis-ci.com/github/sindresorhus/strip-json-comments)

> Strip comments from JSON. Lets you use comments in your JSON files!

This is now possible:

```js
{
	// Rainbows
	"unicorn": /* ❤ */ "cake"
}
```

It will replace single-line comments `//` and multi-line comments `/**/` with whitespace. This allows JSON error positions to remain as close as possible to the original source.

Also available as a [Gulp](https://github.com/sindresorhus/gulp-strip-json-comments)/[Grunt](https://github.com/sindresorhus/grunt-strip-json-comments)/[Broccoli](https://github.com/sindresorhus/broccoli-strip-json-comments) plugin.

## Install

```
$ npm install strip-json-comments
```

## Usage

```js
const json = `{
	// Rainbows
	"unicorn": /* ❤ */ "cake"
}`;

JSON.parse(stripJsonComments(json));
//=> {unicorn: 'cake'}
```

## API

### stripJsonComments(jsonString, options?)

#### jsonString

Type: `string`

Accepts a string with JSON and returns a string without comments.

#### options

Type: `object`

##### whitespace

Type: `boolean`\
Default: `true`

Replace comments with whitespace instead of stripping them entirely.

## Benchmark

```
$ npm run bench
```

## Related

- [strip-json-comments-cli](https://github.com/sindresorhus/strip-json-comments-cli) - CLI for this module
- [strip-css-comments](https://github.com/sindresorhus/strip-css-comments) - Strip comments from CSS

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-strip-json-comments?utm_source=npm-strip-json-comments&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

# style-to-js

[![NPM](https://nodei.co/npm/style-to-js.png)](https://nodei.co/npm/style-to-js/)

[![NPM version](https://badgen.net/npm/v/style-to-js)](https://www.npmjs.com/package/style-to-js)
[![Bundlephobia minified + gzip](https://badgen.net/bundlephobia/minzip/style-to-js)](https://bundlephobia.com/package/style-to-js)
[![build](https://github.com/remarkablemark/style-to-js/actions/workflows/build.yml/badge.svg)](https://github.com/remarkablemark/style-to-js/actions/workflows/build.yml)
[![codecov](https://codecov.io/gh/remarkablemark/style-to-js/branch/master/graph/badge.svg?token=JWKUKTFT3E)](https://codecov.io/gh/remarkablemark/style-to-js)
[![NPM downloads](https://badgen.net/npm/dm/style-to-js)](https://www.npmjs.com/package/style-to-js)

Parses CSS inline style to JavaScript object (camelCased):

```
StyleToJS(string)
```

## Example

```js
import parse from 'style-to-js';

parse('background-color: #BADA55;');
```

Output:

```json
{ "backgroundColor": "#BADA55" }
```

[Replit](https://replit.com/@remarkablemark/style-to-js) | [JSFiddle](https://jsfiddle.net/remarkablemark/04nob1y7/) | [Examples](https://github.com/remarkablemark/style-to-js/tree/master/examples)

## Install

[NPM](https://www.npmjs.com/package/style-to-js):

```sh
npm install style-to-js --save
```

[Yarn](https://yarnpkg.com/package/style-to-js):

```sh
yarn add style-to-js
```

[CDN](https://unpkg.com/style-to-js/):

```html
<script src="https://unpkg.com/style-to-js@latest/umd/style-to-js.min.js"></script>
<script>
  window.StyleToJS(/* string */);
</script>
```

## Usage

### Import

Import with ES Modules:

```js
import parse from 'style-to-js';
```

Require with CommonJS:

```js
const parse = require('style-to-js');
```

### Parse style

Parse single declaration:

```js
parse('line-height: 42');
```

Output:

```json
{ "lineHeight": "42" }
```

> Notice that the CSS property is camelCased.

Parse multiple declarations:

```js
parse(`
  border-color: #ACE;
  z-index: 1337;
`);
```

Output:

```json
{
  "borderColor": "#ACE",
  "zIndex": "1337"
}
```

### Vendor prefix

Parse [vendor prefix](https://developer.mozilla.org/en-US/docs/Glossary/Vendor_Prefix):

```js
parse(`
  -webkit-transition: all 4s ease;
  -moz-transition: all 4s ease;
  -ms-transition: all 4s ease;
  -o-transition: all 4s ease;
  -khtml-transition: all 4s ease;
`);
```

Output:

```json
{
  "webkitTransition": "all 4s ease",
  "mozTransition": "all 4s ease",
  "msTransition": "all 4s ease",
  "oTransition": "all 4s ease",
  "khtmlTransition": "all 4s ease"
}
```

### Custom property

Parse [custom property](https://developer.mozilla.org/en-US/docs/Web/CSS/--*):

```js
parse('--custom-property: #f00');
```

Output:

```json
{ "--custom-property": "#f00" }
```

### Unknown declaration

This library does not validate declarations, so unknown declarations can be parsed:

```js
parse('the-answer: 42;');
```

Output:

```json
{ "theAnswer": "42" }
```

### Invalid declaration

Declarations with missing value are removed:

```js
parse(`
  margin-top: ;
  margin-right: 1em;
`);
```

Output:

```json
{ "marginRight": "1em" }
```

Other invalid declarations or arguments:

```js
parse(); // {}
parse(null); // {}
parse(1); // {}
parse(true); // {}
parse('top:'); // {}
parse(':12px'); // {}
parse(':'); // {}
parse(';'); // {}
```

The following values will throw an error:

```js
parse('top'); // Uncaught Error: property missing ':'
parse('/*'); // Uncaught Error: End of comment missing
```

### Options

#### reactCompat

When option `reactCompat` is true, the [vendor prefix](https://developer.mozilla.org/en-US/docs/Glossary/Vendor_Prefix) will be capitalized:

```js
parse(
  `
    -webkit-transition: all 4s ease;
    -moz-transition: all 4s ease;
    -ms-transition: all 4s ease;
    -o-transition: all 4s ease;
    -khtml-transition: all 4s ease;
  `,
  { reactCompat: true },
);
```

Output:

```json
{
  "WebkitTransition": "all 4s ease",
  "MozTransition": "all 4s ease",
  "msTransition": "all 4s ease",
  "OTransition": "all 4s ease",
  "KhtmlTransition": "all 4s ease"
}
```

This removes the React warning:

```
Warning: Unsupported vendor-prefixed style property %s. Did you mean %s?%s", "oTransition", "OTransition"
```

## Testing

Run tests with coverage:

```sh
npm test
```

Run tests in watch mode:

```sh
npm run test:watch
```

Lint files:

```sh
npm run lint
```

Fix lint errors:

```sh
npm run lint:fix
```

## Release

Release and publish are automated by [Release Please](https://github.com/googleapis/release-please).

## Special Thanks

- [style-to-object](https://github.com/remarkablemark/style-to-object)

## License

[MIT](https://github.com/remarkablemark/style-to-js/blob/master/LICENSE)


---

# style-to-object

[![NPM](https://nodei.co/npm/style-to-object.png)](https://nodei.co/npm/style-to-object/)

[![NPM version](https://badgen.net/npm/v/style-to-object)](https://www.npmjs.com/package/style-to-object)
[![Bundlephobia minified + gzip](https://badgen.net/bundlephobia/minzip/style-to-object)](https://bundlephobia.com/package/style-to-object)
[![build](https://github.com/remarkablemark/style-to-object/actions/workflows/build.yml/badge.svg)](https://github.com/remarkablemark/style-to-object/actions/workflows/build.yml)
[![codecov](https://codecov.io/gh/remarkablemark/style-to-object/branch/master/graph/badge.svg?token=XWxph9dpa4)](https://codecov.io/gh/remarkablemark/style-to-object)
[![NPM downloads](https://badgen.net/npm/dm/style-to-object)](https://www.npmjs.com/package/style-to-object)

Parse CSS inline style to JavaScript object:

```js
import parse from 'style-to-object';

parse('color: #C0FFEE; background: #BADA55;');
```

Output:

```js
{ color: '#C0FFEE', background: '#BADA55' }
```

[JSFiddle](https://jsfiddle.net/remarkablemark/ykz2meot/) | [Replit](https://replit.com/@remarkablemark/style-to-object) | [Examples](https://github.com/remarkablemark/style-to-object/tree/master/examples)

## Installation

[NPM](https://www.npmjs.com/package/style-to-object):

```sh
npm install style-to-object --save
```

[Yarn](https://yarn.fyi/style-to-object):

```sh
yarn add style-to-object
```

[CDN](https://unpkg.com/style-to-object/):

```html
<script src="https://unpkg.com/style-to-object@latest/dist/style-to-object.min.js"></script>
<script>
  window.StyleToObject(/* string */);
</script>
```

## Usage

Import with ES Modules:

```js
import parse from 'style-to-object';
```

Require with CommonJS:

```js
const parse = require('style-to-object').default;
```

Parse single declaration:

```js
parse('line-height: 42');
```

Output:

```js
{ 'line-height': '42' }
```

Parse multiple declarations:

```js
parse(`
  border-color: #ACE;
  z-index: 1337;
`);
```

Output:

```js
{ 'border-color': '#ACE', 'z-index': '1337' }
```

Parse unknown declarations:

```js
parse('answer: 42;');
```

Output:

```js
{ 'answer': '42' }
```

Invalid declarations/arguments:

<!-- prettier-ignore-start -->

```js
parse(`
  top: ;
  right: 1em;
`); // { right: '1em' }

parse();        // null
parse(null);    // null
parse(1);       // null
parse(true);    // null
parse('top:');  // null
parse(':12px'); // null
parse(':');     // null
parse(';');     // null

parse('top'); // throws Error
parse('/*');  // throws Error
```

<!-- prettier-ignore-end -->

### Iterator

If the 2nd argument is a function, then the parser will return `null`:

```js
parse('color: #f00', () => {}); // null
```

But the function will iterate through each declaration:

<!-- prettier-ignore-start -->

```js
parse('color: #f00', (name, value, declaration) => {
  console.log(name);        // 'color'
  console.log(value);       // '#f00'
  console.log(declaration); // { type: 'declaration', property: 'color', value: '#f00' }
});
```

<!-- prettier-ignore-end -->

This makes it easy to customize the output:

```js
const style = `
  color: red;
  background: blue;
`;
const output = [];

function iterator(name, value) {
  output.push([name, value]);
}

parse(style, iterator);
console.log(output); // [['color', 'red'], ['background', 'blue']]
```

## Migration

### v1

Migrated to TypeScript. Iterator excludes `Comment`. CommonJS requires the `.default` key:

```js
const parse = require('style-to-object').default;
```

## Release

Release and publish are automated by [Release Please](https://github.com/googleapis/release-please).

## Special Thanks

- [inline-style-parser](https://github.com/remarkablemark/inline-style-parser)
- [Contributors](https://github.com/remarkablemark/style-to-object/graphs/contributors)

## License

[MIT](https://github.com/remarkablemark/style-to-object/blob/master/LICENSE)


---

# stylehacks

> Detect/remove browser hacks from CSS files.


## Install

With [npm](https://npmjs.org/package/stylehacks) do:

```
npm install stylehacks --save
```


## Example

In its default mode, stylehacks will remove hacks from your CSS file, based on
the browsers that you wish to support.

### Input

```css
h1 {
    _color: white;
    color: rgba(255, 255, 255, 0.5);
}
```

### Output

```css
h1 {
    color: rgba(255, 255, 255, 0.5);
}
```


## API

### `stylehacks.detect(node)`

Type: `function`  
Returns: `boolean`

This method will take any PostCSS *node*, run applicable plugins depending on
its type, then will return a boolean depending on whether it found any of
the supported hacks. For example, if the `decl` node found below is passed to
the `detect` function, it will return `true`. But if the `rule` node is passed,
it will return `false` instead.

```css
h1 { _color: red }
```

### `postcss([ stylehacks(opts) ])`

stylehacks can also be consumed as a PostCSS plugin. See the
[documentation](https://github.com/postcss/postcss#usage) for examples for
your environment.

#### options

##### lint

Type: `boolean`  
Default: `false`

If lint mode is enabled, stylehacks will not remove hacks from the CSS; instead,
it will add warnings to `Result#messages`.


## Related

stylehacks works well with your existing PostCSS setup:

* [stylelint] - Comprehensive & modern CSS linter, to ensure that your code
  style rules are respected.


## Contributing

Pull requests are welcome. If you add functionality, then please add unit tests
to cover it.


## License

MIT © [Ben Briggs](http://beneb.info)


[stylelint]: https://github.com/stylelint/stylelint


---

# supports-color [![Build Status](https://travis-ci.org/chalk/supports-color.svg?branch=master)](https://travis-ci.org/chalk/supports-color)

> Detect whether a terminal supports color


## Install

```
$ npm install supports-color
```


## Usage

```js
const supportsColor = require('supports-color');

if (supportsColor.stdout) {
	console.log('Terminal stdout supports color');
}

if (supportsColor.stdout.has256) {
	console.log('Terminal stdout supports 256 colors');
}

if (supportsColor.stderr.has16m) {
	console.log('Terminal stderr supports 16 million colors (truecolor)');
}
```


## API

Returns an `Object` with a `stdout` and `stderr` property for testing either streams. Each property is an `Object`, or `false` if color is not supported.

The `stdout`/`stderr` objects specifies a level of support for color through a `.level` property and a corresponding flag:

- `.level = 1` and `.hasBasic = true`: Basic color support (16 colors)
- `.level = 2` and `.has256 = true`: 256 color support
- `.level = 3` and `.has16m = true`: Truecolor support (16 million colors)


## Info

It obeys the `--color` and `--no-color` CLI flags.

For situations where using `--color` is not possible, use the environment variable `FORCE_COLOR=1` (level 1), `FORCE_COLOR=2` (level 2), or `FORCE_COLOR=3` (level 3) to forcefully enable color, or `FORCE_COLOR=0` to forcefully disable. The use of `FORCE_COLOR` overrides all other color support checks.

Explicit 256/Truecolor mode can be enabled using the `--color=256` and `--color=16m` flags, respectively.


## Related

- [supports-color-cli](https://github.com/chalk/supports-color-cli) - CLI for this module
- [chalk](https://github.com/chalk/chalk) - Terminal string styling done right


## Maintainers

- [Sindre Sorhus](https://github.com/sindresorhus)
- [Josh Junon](https://github.com/qix-)


---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-supports-color?utm_source=npm-supports-color&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>

---


---

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## v1.0.0 - 2022-01-02

### Commits

- Tests [`e2f59ad`](https://github.com/inspect-js/node-supports-preserve-symlinks-flag/commit/e2f59ad74e2ae0f5f4899fcde6a6f693ab7cc074)
- Initial commit [`dc222aa`](https://github.com/inspect-js/node-supports-preserve-symlinks-flag/commit/dc222aad3c0b940d8d3af1ca9937d108bd2dc4b9)
- [meta] do not publish workflow files [`5ef77f7`](https://github.com/inspect-js/node-supports-preserve-symlinks-flag/commit/5ef77f7cb6946d16ee38672be9ec0f1bbdf63262)
- npm init [`992b068`](https://github.com/inspect-js/node-supports-preserve-symlinks-flag/commit/992b068503a461f7e8676f40ca2aab255fd8d6ff)
- read me [`6c9afa9`](https://github.com/inspect-js/node-supports-preserve-symlinks-flag/commit/6c9afa9fabc8eaf0814aaed6dd01e6df0931b76d)
- Initial implementation [`2f98925`](https://github.com/inspect-js/node-supports-preserve-symlinks-flag/commit/2f9892546396d4ab0ad9f1ff83e76c3f01234ae8)
- [meta] add `auto-changelog` [`6c476ae`](https://github.com/inspect-js/node-supports-preserve-symlinks-flag/commit/6c476ae1ed7ce68b0480344f090ac2844f35509d)
- [Dev Deps] add `eslint`, `@ljharb/eslint-config` [`d0fffc8`](https://github.com/inspect-js/node-supports-preserve-symlinks-flag/commit/d0fffc886d25fba119355520750a909d64da0087)
- Only apps should have lockfiles [`ab318ed`](https://github.com/inspect-js/node-supports-preserve-symlinks-flag/commit/ab318ed7ae62f6c2c0e80a50398d40912afd8f69)
- [meta] add `safe-publish-latest` [`2bb23b3`](https://github.com/inspect-js/node-supports-preserve-symlinks-flag/commit/2bb23b3ebab02dc4135c4cdf0217db82835b9fca)
- [meta] add `sideEffects` flag [`600223b`](https://github.com/inspect-js/node-supports-preserve-symlinks-flag/commit/600223ba24f30779f209d9097721eff35ed62741)


---

# node-supports-preserve-symlinks-flag <sup>[![Version Badge][npm-version-svg]][package-url]</sup>

[![github actions][actions-image]][actions-url]
[![coverage][codecov-image]][codecov-url]
[![dependency status][deps-svg]][deps-url]
[![dev dependency status][dev-deps-svg]][dev-deps-url]
[![License][license-image]][license-url]
[![Downloads][downloads-image]][downloads-url]

[![npm badge][npm-badge-png]][package-url]

Determine if the current node version supports the `--preserve-symlinks` flag.

## Example

```js
var supportsPreserveSymlinks = require('node-supports-preserve-symlinks-flag');
var assert = require('assert');

assert.equal(supportsPreserveSymlinks, null); // in a browser
assert.equal(supportsPreserveSymlinks, false); // in node < v6.2
assert.equal(supportsPreserveSymlinks, true); // in node v6.2+
```

## Tests
Simply clone the repo, `npm install`, and run `npm test`

[package-url]: https://npmjs.org/package/node-supports-preserve-symlinks-flag
[npm-version-svg]: https://versionbadg.es/inspect-js/node-supports-preserve-symlinks-flag.svg
[deps-svg]: https://david-dm.org/inspect-js/node-supports-preserve-symlinks-flag.svg
[deps-url]: https://david-dm.org/inspect-js/node-supports-preserve-symlinks-flag
[dev-deps-svg]: https://david-dm.org/inspect-js/node-supports-preserve-symlinks-flag/dev-status.svg
[dev-deps-url]: https://david-dm.org/inspect-js/node-supports-preserve-symlinks-flag#info=devDependencies
[npm-badge-png]: https://nodei.co/npm/node-supports-preserve-symlinks-flag.png?downloads=true&stars=true
[license-image]: https://img.shields.io/npm/l/node-supports-preserve-symlinks-flag.svg
[license-url]: LICENSE
[downloads-image]: https://img.shields.io/npm/dm/node-supports-preserve-symlinks-flag.svg
[downloads-url]: https://npm-stat.com/charts.html?package=node-supports-preserve-symlinks-flag
[codecov-image]: https://codecov.io/gh/inspect-js/node-supports-preserve-symlinks-flag/branch/main/graphs/badge.svg
[codecov-url]: https://app.codecov.io/gh/inspect-js/node-supports-preserve-symlinks-flag/
[actions-image]: https://img.shields.io/endpoint?url=https://github-actions-badge-u3jn4tfpocch.runkit.sh/inspect-js/node-supports-preserve-symlinks-flag
[actions-url]: https://github.com/inspect-js/node-supports-preserve-symlinks-flag/actions


---

# svg-parser changelog

## 2.0.3

* Fix reported error location ([#9](https://github.com/Rich-Harris/svg-parser/issues/9))

## 2.0.2

* Allow underscores in attribute names ([#4](https://github.com/Rich-Harris/svg-parser/issues/4))

## 2.0.1

* Fix empty/space attributes

## 2.0.0

* Migrate to HAST

## 1.0.6

* Remove unused dependency

## 1.0.5

* Handle doctype and CDATA

## 1.0.4

* Handle unexpected end of input

## 1.0.3

* Prevent infinite loops on bad final closing tag

## 1.0.2

* Prevent `""=true` attributes

## 1.0.1

* Allow attributes with numbers (e.g. `x1`)
* Fix error messages

## 1.0.0

* First release


---

# svg-parser

Take a string representing an SVG document or fragment, turn it into [HAST](https://github.com/syntax-tree/hast) JavaScript object.


## Installation

`npm install svg-parser`, or grab it from [npmcdn.com/svg-parser](https://npmcdn.com/svg-parser).


## Usage

```js
import { parse } from 'svg-parser';

const parsed = parse( `
	<svg viewBox='0 0 100 100'>
		<!-- stuff goes here... -->
	</svg>
` );
/*
{
  type: 'root',
  children: [
    {
      type: 'element',
      tagName: 'svg',
      properties: {
        viewBox: '0 0 100 100'
      },
      children: [...]
    }
  ]
}
*/
```


## License

MIT


---

<div align="center">
  <img src="./logo/logo-web.svg" width="348.61" height="100" alt=""/>
</div>

# SVGO [![npm](https://img.shields.io/npm/v/svgo)](https://npmjs.org/package/svgo) [![chat](https://img.shields.io/discord/815166721315831868)](https://discord.gg/z8jX8NYxrE) [![docs](https://img.shields.io/badge/docs-svgo.dev-blue)](https://svgo.dev/)

SVGO, short for **SVG O**ptimizer, is a Node.js library and command-line application for optimizing SVG files.

## Why?

SVG files, especially those exported from vector editors, usually contain a lot of redundant information. This includes editor metadata, comments, hidden elements, default or suboptimal values, and other stuff that can be safely removed or converted without impacting rendering.

## Installation

You can install SVGO globally through npm, yarn, or pnpm. Alternatively, drop the global flag (`global`/`-g`) to use it in your Node.js project.

```sh
# npm
npm install -g svgo

# yarn
yarn global add svgo

# pnpm
pnpm add -g svgo
```

## Command-line usage

Process single files:

```sh
svgo one.svg two.svg -o one.min.svg two.min.svg
```

Process a directory of files recursively with `-f`/`--folder`:

```sh
svgo -f path/to/directory_with_svgs -o path/to/output_directory
```

Help for advanced usage:

```sh
svgo --help
```

## Configuration

SVGO has a plugin architecture. You can read more about all plugins in [Plugins | SVGO Documentation](https://svgo.dev/docs/plugins/), and the default plugins in [Preset Default | SVGO Documentation](https://svgo.dev/docs/preset-default/).

SVGO reads the configuration from `svgo.config.js` or the `--config path/to/config.js` command-line option. Some other parameters can be configured though command-line options too.

**`svgo.config.js`**

```js
module.exports = {
  multipass: false, // boolean
  datauri: 'base64', // 'base64'|'enc'|'unenc'
  js2svg: {
    indent: 4, // number
    pretty: false, // boolean
  },
  plugins: [
    'preset-default', // built-in plugins enabled by default
    'prefixIds', // enable built-in plugins by name

    // enable built-in plugins with an object to configure plugins
    {
      name: 'prefixIds',
      params: {
        prefix: 'uwu',
      },
    },
  ],
};
```

### Default preset

Instead of configuring SVGO from scratch, you can tweak the default preset to suit your needs by configuring or disabling the respective plugin.

**`svgo.config.js`**

```js
module.exports = {
  plugins: [
    {
      name: 'preset-default',
      params: {
        overrides: {
          // disable a default plugin
          removeViewBox: false,

          // customize the params of a default plugin
          inlineStyles: {
            onlyMatchedOnce: false,
          },
        },
      },
    },
  ],
};
```

You can find a list of the default plugins in the order they run in [Preset Default | SVGO Documentation](https://svgo.dev/docs/preset-default/#plugins-list).

### Custom plugins

You can also specify custom plugins:

**`svgo.config.js`**

```js
const importedPlugin = require('./imported-plugin');

module.exports = {
  plugins: [
    // plugin imported from another JavaScript file
    importedPlugin,

    // plugin defined inline
    {
      name: 'customPlugin',
      params: {
        paramName: 'paramValue',
      },
      fn: (ast, params, info) => {},
    },
  ],
};
```

## API usage

SVGO provides a few low level utilities.

### optimize

The core of SVGO is `optimize` function.

```js
const { optimize } = require('svgo');

const result = optimize(svgString, {
  path: 'path-to.svg', // recommended
  multipass: true, // all other config fields are available here
});

const optimizedSvgString = result.data;
```

### loadConfig

If you write a tool on top of SVGO you may want to resolve the `svgo.config.js` file.

```js
const { loadConfig } = require('svgo');

const config = await loadConfig();
```

You can also specify a path and customize the current working directory.

```js
const config = await loadConfig(configFile, cwd);
```

## Other ways to use SVGO

| Method                    | Reference                                                                                                               |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Web app                   | [SVGOMG](https://jakearchibald.github.io/svgomg/)                                                                       |
| Grunt task                | [grunt-svgmin](https://github.com/sindresorhus/grunt-svgmin)                                                            |
| Gulp task                 | [gulp-svgmin](https://github.com/ben-eb/gulp-svgmin)                                                                    |
| Webpack loader            | [image-minimizer-webpack-plugin](https://github.com/webpack-contrib/image-minimizer-webpack-plugin/#optimize-with-svgo) |
| PostCSS plugin            | [postcss-svgo](https://github.com/cssnano/cssnano/tree/master/packages/postcss-svgo)                                    |
| Inkscape plugin           | [inkscape-svgo](https://github.com/konsumer/inkscape-svgo)                                                              |
| Sketch plugin             | [svgo-compressor](https://github.com/BohemianCoding/svgo-compressor)                                                    |
| Rollup plugin             | [rollup-plugin-svgo](https://github.com/porsager/rollup-plugin-svgo)                                                    |
| Visual Studio Code plugin | [vscode-svgo](https://github.com/1000ch/vscode-svgo)                                                                    |
| Atom plugin               | [atom-svgo](https://github.com/1000ch/atom-svgo)                                                                        |
| Sublime plugin            | [Sublime-svgo](https://github.com/1000ch/Sublime-svgo)                                                                  |
| Figma plugin              | [Advanced SVG Export](https://www.figma.com/c/plugin/782713260363070260/Advanced-SVG-Export)                            |
| Linux app                 | [Oh My SVG](https://github.com/sonnyp/OhMySVG)                                                                          |
| Browser extension         | [SVG Gobbler](https://github.com/rossmoody/svg-gobbler)                                                                 |
| API                       | [Vector Express](https://github.com/smidyo/vectorexpress-api#convertor-svgo)                                            |

## Donors

| [<img src="https://sheetjs.com/sketch128.png" width="80">](https://sheetjs.com/) | [<img src="https://raw.githubusercontent.com/fontello/fontello/8.0.0/fontello-image.svg" width="80">](https://fontello.com/) |
| :------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------------------: |
|                       [SheetJS LLC](https://sheetjs.com/)                        |                                              [Fontello](https://fontello.com/)                                               |

## License and Copyright

This software is released under the terms of the [MIT license](https://github.com/svg/svgo/blob/main/LICENSE).

Logo by [André Castillo](https://github.com/DerianAndre).


---

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html). (Format adopted after v3.0.0.)

<!-- markdownlint-disable MD024 -->
<!-- markdownlint-disable MD004 -->

## [7.2.0] (2021-03-26)

### Added

- TypeScript typing for `parent` property on `Command` ([#1475])
- TypeScript typing for `.attributeName()` on `Option` ([#1483])
- support information in package ([#1477])

### Changed

- improvements to error messages, README, and tests
- update dependencies

## [7.1.0] (2021-02-15)

### Added

- support for named imports from ECMAScript modules ([#1440])
- add `.cjs` to list of expected script file extensions ([#1449])
- allow using option choices and variadic together ([#1454])

### Fixed

- replace use of deprecated `process.mainModule` ([#1448])
- regression for legacy `command('*')` and call when command line includes options ([#1464])
- regression for `on('command:*', ...)` and call when command line includes unknown options ([#1464])
- display best error for combination of unknown command and unknown option (i.e. unknown command) ([#1464])

### Changed

- make TypeScript typings tests stricter ([#1453])
- improvements to README and tests

## [7.0.0] (2021-01-15)

### Added

- `.enablePositionalOptions()` to let program and subcommand reuse same option ([#1427])
- `.passThroughOptions()` to pass options through to other programs without needing `--` ([#1427])
- `.allowExcessArguments(false)` to show an error message if there are too many command-arguments on command line for the action handler ([#1409])
- `.configureOutput()` to modify use of stdout and stderr or customise display of errors ([#1387])
- use `.addHelpText()` to add text before or after the built-in help, for just current command or also for all subcommands ([#1296])
- enhance Option class ([#1331])
  - allow hiding options from help
  - allow restricting option arguments to a list of choices
  - allow setting how default value is shown in help
- `.createOption()` to support subclassing of automatically created options (like `.createCommand()`) ([#1380])
- refactor the code generating the help into a separate public Help class ([#1365])
  - support sorting subcommands and options in help
  - support specifying wrap width (columns)
  - allow subclassing Help class
  - allow configuring Help class without subclassing

### Changed

- *Breaking:* options are stored safely by default, not as properties on the command ([#1409])
    - this especially affects accessing options on program, use `program.opts()`
    - revert behaviour with `.storeOptionsAsProperties()`
- *Breaking:* action handlers are passed options and command separately ([#1409])
- deprecated callback parameter to `.help()` and `.outputHelp()` (removed from README) ([#1296])
- *Breaking:* errors now displayed using `process.stderr.write()` instead of `console.error()`
- deprecate `.on('--help')` (removed from README) ([#1296])
- initialise the command description to empty string (previously undefined) ([#1365])
- document and annotate deprecated routines ([#1349])

### Fixed

- wrapping bugs in help ([#1365])
  - first line of command description was wrapping two characters early
  - pad width calculation was not including help option and help command
  - pad width calculation was including hidden options and commands
- improve backwards compatibility for custom command event listeners ([#1403])
  
### Deleted

- *Breaking:* `.passCommandToAction()` ([#1409])
    - no longer needed as action handler is passed options and command
- *Breaking:* "extra arguments" parameter to action handler ([#1409])
    - if being used to detect excess arguments, there is now an error available by setting `.allowExcessArguments(false)`

### Migration Tips

The biggest change is the parsed option values. Previously the options were stored by default as properties on the command object, and now the options are stored separately.

If you wish to restore the old behaviour and get running quickly you can call `.storeOptionsAsProperties()`. 
To allow you to move to the new code patterns incrementally, the action handler will be passed the command _twice_,
to match the new "options" and "command" parameters (see below).

**program options**

Use the `.opts()` method to access the options. This is available on any command but is used most with the program.

```js
program.option('-d, --debug');
program.parse();
// Old code before Commander 7
if (program.debug) console.log(`Program name is ${program.name()}`);
```

```js
// New code
const options = program.opts();
if (options.debug) console.log(`Program name is ${program.name()}`);
```

**action handler**

The action handler gets passed a parameter for each command-argument you declared. Previously by default the next parameter was the command object with the options as properties. Now the next two parameters are instead the options and the command. If you
only accessed the options there may be no code changes required.

```js
program
  .command('compress <filename>')
  .option('-t, --trace')
  // Old code before Commander 7
  .action((filename, cmd)) => {
    if (cmd.trace) console.log(`Command name is ${cmd.name()}`);
  });
```

```js
  // New code
  .action((filename, options, command)) => {
    if (options.trace) console.log(`Command name is ${command.name()}`);
  });
```

If you already set `.storeOptionsAsProperties(false)` you may still need to adjust your code.

```js
program
  .command('compress <filename>')
  .storeOptionsAsProperties(false)
  .option('-t, --trace')
  // Old code before Commander 7
  .action((filename, command)) => {
    if (command.opts().trace) console.log(`Command name is ${command.name()}`);
  });
```

```js
   // New code
   .action((filename, options, command)) => {
      if (command.opts().trace) console.log(`Command name is ${command.name()}`);
   });
```

## [7.0.0-2] (2020-12-14)

(Released in 7.0.0)

## [7.0.0-1] (2020-11-21)

(Released in 7.0.0)

## [7.0.0-0] (2020-10-25)

(Released in 7.0.0)

## [6.2.1] (2020-12-13)

### Fixed

- some tests failed if directory path included a space ([1390])

## [6.2.0] (2020-10-25)

### Added

- added 'tsx' file extension for stand-alone executable subcommands ([#1368])
- documented second parameter to `.description()` to describe command arguments ([#1353])
- documentation of special cases with options taking varying numbers of option-arguments ([#1332])
- documentation for terminology ([#1361])
  
### Fixed

- add missing TypeScript definition for `.addHelpCommand()' ([#1375])
- removed blank line after "Arguments:" in help, to match "Options:" and "Commands:" ([#1360])

### Changed

- update dependencies

## [6.1.0] (2020-08-28)

### Added

- include URL to relevant section of README for error for potential conflict between Command properties and option values ([#1306])
- `.combineFlagAndOptionalValue(false)` to ease upgrade path from older versions of Commander ([#1326])
- allow disabling the built-in help option using `.helpOption(false)` ([#1325])
- allow just some arguments in `argumentDescription` to `.description()` ([#1323])

### Changed

- tidy async test and remove lint override ([#1312])

### Fixed

- executable subcommand launching when script path not known ([#1322])

## [6.0.0] (2020-07-21)

### Added

- add support for variadic options ([#1250])
- allow options to be added with just a short flag ([#1256])
  - *Breaking* the option property has same case as flag. e.g. flag `-n` accessed as `opts().n` (previously uppercase)
- *Breaking* throw an error if there might be a clash between option name and a Command property, with advice on how to resolve ([#1275])

### Fixed

- Options which contain -no- in the middle of the option flag should not be treated as negatable. ([#1301])

## [6.0.0-0] (2020-06-20)

(Released in 6.0.0)

## [5.1.0] (2020-04-25)

### Added

- support for multiple command aliases, the first of which is shown in the auto-generated help ([#531], [#1236])
- configuration support in `addCommand()` for `hidden` and `isDefault` ([#1232])

### Fixed

- omit masked help flags from the displayed help ([#645], [#1247])
- remove old short help flag when change help flags using `helpOption` ([#1248])

### Changed

- remove use of `arguments` to improve auto-generated help in editors ([#1235])
- rename `.command()` configuration `noHelp` to `hidden` (but not remove old support) ([#1232])
- improvements to documentation
- update dependencies
- update tested versions of node
- eliminate lint errors in TypeScript ([#1208])

## [5.0.0] (2020-03-14)

### Added

* support for nested commands with action-handlers ([#1] [#764] [#1149])
* `.addCommand()` for adding a separately configured command ([#764] [#1149])
* allow a non-executable to be set as the default command ([#742] [#1149])
* implicit help command when there are subcommands (previously only if executables) ([#1149])
* customise implicit help command with `.addHelpCommand()` ([#1149])
* display error message for unknown subcommand, by default ([#432] [#1088] [#1149])
* display help for missing subcommand, by default ([#1088] [#1149])
* combined short options as single argument may include boolean flags and value flag and value (e.g. `-a -b -p 80` can be written as `-abp80`) ([#1145])
* `.parseOption()` includes short flag and long flag expansions ([#1145])
* `.helpInformation()` returns help text as a string, previously a private routine ([#1169])
* `.parse()` implicitly uses `process.argv` if arguments not specified ([#1172])
* optionally specify where `.parse()` arguments "from", if not following node conventions ([#512] [#1172])
* suggest help option along with unknown command error ([#1179])
* TypeScript definition for `commands` property of `Command` ([#1184])
* export `program` property ([#1195])
* `createCommand` factory method to simplify subclassing ([#1191])

### Fixed

* preserve argument order in subcommands ([#508] [#962] [#1138])
* do not emit `command:*` for executable subcommands ([#809] [#1149])
* action handler called whether or not there are non-option arguments ([#1062] [#1149])
* combining option short flag and value in single argument now works for subcommands ([#1145])
* only add implicit help command when it will not conflict with other uses of argument ([#1153] [#1149])
* implicit help command works with command aliases ([#948] [#1149])
* options are validated whether or not there is an action handler ([#1149])

### Changed

* *Breaking* `.args` contains command arguments with just recognised options removed ([#1032] [#1138])
* *Breaking* display error if required argument for command is missing ([#995] [#1149])
* tighten TypeScript definition of custom option processing function passed to `.option()` ([#1119])
* *Breaking* `.allowUnknownOption()` ([#802] [#1138])
  * unknown options included in arguments passed to command action handler
  * unknown options included in `.args`
* only recognised option short flags and long flags are expanded (e.g. `-ab` or `--foo=bar`) ([#1145])
* *Breaking* `.parseOptions()` ([#1138])
  * `args` in returned result renamed `operands` and does not include anything after first unknown option
  * `unknown` in returned result has arguments after first unknown option including operands, not just options and values
* *Breaking* `.on('command:*', callback)` and other command events passed (changed) results from `.parseOptions`, i.e. operands and unknown  ([#1138])
* refactor Option from prototype to class ([#1133])
* refactor Command from prototype to class ([#1159])
* changes to error handling ([#1165])
  * throw for author error, not just display message
  * preflight for variadic error
  * add tips to missing subcommand executable
* TypeScript fluent return types changed to be more subclass friendly, return `this` rather than `Command` ([#1180])
* `.parseAsync` returns `Promise<this>` to be consistent with `.parse()` ([#1180])
* update dependencies

### Removed

* removed EventEmitter from TypeScript definition for Command, eliminating implicit peer dependency on `@types/node` ([#1146])
* removed private function `normalize` (the functionality has been integrated into `parseOptions`) ([#1145])
* `parseExpectedArgs` is now private ([#1149])

### Migration Tips

If you use `.on('command:*')` or more complicated tests to detect an unrecognised subcommand, you may be able to delete the code and rely on the default behaviour.

If you use `program.args` or more complicated tests to detect a missing subcommand, you may be able to delete the code and rely on the default behaviour.

If you use `.command('*')` to add a default command, you may be be able to switch to `isDefault:true` with a named command.

If you want to continue combining short options with optional values as though they were boolean flags, set `combineFlagAndOptionalValue(false)`
to expand `-fb` to `-f -b` rather than `-f b`.

## [5.0.0-4] (2020-03-03)

(Released in 5.0.0)

## [5.0.0-3] (2020-02-20)

(Released in 5.0.0)

## [5.0.0-2] (2020-02-10)

(Released in 5.0.0)

## [5.0.0-1] (2020-02-08)

(Released in 5.0.0)

## [5.0.0-0] (2020-02-02)

(Released in 5.0.0)

## Older versions

* [4.x](./changelogs/CHANGELOG-4.md)
* [3.x](./changelogs/CHANGELOG-3.md)
* [2.x](./changelogs/CHANGELOG-2.md)
* [1.x](./changelogs/CHANGELOG-1.md)
* [0.x](./changelogs/CHANGELOG-0.md)

[#1]: https://github.com/tj/commander.js/issues/1
[#432]: https://github.com/tj/commander.js/issues/432
[#508]: https://github.com/tj/commander.js/issues/508
[#512]: https://github.com/tj/commander.js/issues/512
[#531]: https://github.com/tj/commander.js/issues/531
[#645]: https://github.com/tj/commander.js/issues/645
[#742]: https://github.com/tj/commander.js/issues/742
[#764]: https://github.com/tj/commander.js/issues/764
[#802]: https://github.com/tj/commander.js/issues/802
[#809]: https://github.com/tj/commander.js/issues/809
[#948]: https://github.com/tj/commander.js/issues/948
[#962]: https://github.com/tj/commander.js/issues/962
[#995]: https://github.com/tj/commander.js/issues/995
[#1032]: https://github.com/tj/commander.js/issues/1032
[#1062]: https://github.com/tj/commander.js/pull/1062
[#1088]: https://github.com/tj/commander.js/issues/1088
[#1119]: https://github.com/tj/commander.js/pull/1119
[#1133]: https://github.com/tj/commander.js/pull/1133
[#1138]: https://github.com/tj/commander.js/pull/1138
[#1145]: https://github.com/tj/commander.js/pull/1145
[#1146]: https://github.com/tj/commander.js/pull/1146
[#1149]: https://github.com/tj/commander.js/pull/1149
[#1153]: https://github.com/tj/commander.js/issues/1153
[#1159]: https://github.com/tj/commander.js/pull/1159
[#1165]: https://github.com/tj/commander.js/pull/1165
[#1169]: https://github.com/tj/commander.js/pull/1169
[#1172]: https://github.com/tj/commander.js/pull/1172
[#1179]: https://github.com/tj/commander.js/pull/1179
[#1180]: https://github.com/tj/commander.js/pull/1180
[#1184]: https://github.com/tj/commander.js/pull/1184
[#1191]: https://github.com/tj/commander.js/pull/1191
[#1195]: https://github.com/tj/commander.js/pull/1195
[#1208]: https://github.com/tj/commander.js/pull/1208
[#1232]: https://github.com/tj/commander.js/pull/1232
[#1235]: https://github.com/tj/commander.js/pull/1235
[#1236]: https://github.com/tj/commander.js/pull/1236
[#1247]: https://github.com/tj/commander.js/pull/1247
[#1248]: https://github.com/tj/commander.js/pull/1248
[#1250]: https://github.com/tj/commander.js/pull/1250
[#1256]: https://github.com/tj/commander.js/pull/1256
[#1275]: https://github.com/tj/commander.js/pull/1275
[#1296]: https://github.com/tj/commander.js/pull/1296
[#1301]: https://github.com/tj/commander.js/issues/1301
[#1306]: https://github.com/tj/commander.js/pull/1306
[#1312]: https://github.com/tj/commander.js/pull/1312
[#1322]: https://github.com/tj/commander.js/pull/1322
[#1323]: https://github.com/tj/commander.js/pull/1323
[#1325]: https://github.com/tj/commander.js/pull/1325
[#1326]: https://github.com/tj/commander.js/pull/1326
[#1331]: https://github.com/tj/commander.js/pull/1331
[#1332]: https://github.com/tj/commander.js/pull/1332
[#1349]: https://github.com/tj/commander.js/pull/1349
[#1353]: https://github.com/tj/commander.js/pull/1353
[#1360]: https://github.com/tj/commander.js/pull/1360
[#1361]: https://github.com/tj/commander.js/pull/1361
[#1365]: https://github.com/tj/commander.js/pull/1365
[#1368]: https://github.com/tj/commander.js/pull/1368
[#1375]: https://github.com/tj/commander.js/pull/1375
[#1380]: https://github.com/tj/commander.js/pull/1380
[#1387]: https://github.com/tj/commander.js/pull/1387
[#1390]: https://github.com/tj/commander.js/pull/1390
[#1403]: https://github.com/tj/commander.js/pull/1403
[#1409]: https://github.com/tj/commander.js/pull/1409
[#1427]: https://github.com/tj/commander.js/pull/1427
[#1440]: https://github.com/tj/commander.js/pull/1440
[#1448]: https://github.com/tj/commander.js/pull/1448
[#1449]: https://github.com/tj/commander.js/pull/1449
[#1453]: https://github.com/tj/commander.js/pull/1453
[#1454]: https://github.com/tj/commander.js/pull/1454
[#1464]: https://github.com/tj/commander.js/pull/1464
[#1475]: https://github.com/tj/commander.js/pull/1475
[#1477]: https://github.com/tj/commander.js/pull/1477
[#1483]: https://github.com/tj/commander.js/pull/1483

[Unreleased]: https://github.com/tj/commander.js/compare/master...develop
[7.2.0]: https://github.com/tj/commander.js/compare/v7.1.0...v7.2.0
[7.1.0]: https://github.com/tj/commander.js/compare/v7.0.0...v7.1.0
[7.0.0]: https://github.com/tj/commander.js/compare/v6.2.1...v7.0.0
[7.0.0-2]: https://github.com/tj/commander.js/compare/v7.0.0-1...v7.0.0-2
[7.0.0-1]: https://github.com/tj/commander.js/compare/v7.0.0-0...v7.0.0-1
[7.0.0-0]: https://github.com/tj/commander.js/compare/v6.2.0...v7.0.0-0
[6.2.1]: https://github.com/tj/commander.js/compare/v6.2.0..v6.2.1
[6.2.0]: https://github.com/tj/commander.js/compare/v6.1.0..v6.2.0
[6.1.0]: https://github.com/tj/commander.js/compare/v6.0.0..v6.1.0
[6.0.0]: https://github.com/tj/commander.js/compare/v5.1.0..v6.0.0
[6.0.0-0]: https://github.com/tj/commander.js/compare/v5.1.0..v6.0.0-0
[5.1.0]: https://github.com/tj/commander.js/compare/v5.0.0..v5.1.0
[5.0.0]: https://github.com/tj/commander.js/compare/v4.1.1..v5.0.0
[5.0.0-4]: https://github.com/tj/commander.js/compare/v5.0.0-3..v5.0.0-4
[5.0.0-3]: https://github.com/tj/commander.js/compare/v5.0.0-2..v5.0.0-3
[5.0.0-2]: https://github.com/tj/commander.js/compare/v5.0.0-1..v5.0.0-2
[5.0.0-1]: https://github.com/tj/commander.js/compare/v5.0.0-0..v5.0.0-1
[5.0.0-0]: https://github.com/tj/commander.js/compare/v4.1.1..v5.0.0-0


---

# Commander.js

[![Build Status](https://github.com/tj/commander.js/workflows/build/badge.svg)](https://github.com/tj/commander.js/actions?query=workflow%3A%22build%22)
[![NPM Version](http://img.shields.io/npm/v/commander.svg?style=flat)](https://www.npmjs.org/package/commander)
[![NPM Downloads](https://img.shields.io/npm/dm/commander.svg?style=flat)](https://npmcharts.com/compare/commander?minimal=true)
[![Install Size](https://packagephobia.now.sh/badge?p=commander)](https://packagephobia.now.sh/result?p=commander)

The complete solution for [node.js](http://nodejs.org) command-line interfaces.

Read this in other languages: English | [简体中文](./Readme_zh-CN.md)

- [Commander.js](#commanderjs)
  - [Installation](#installation)
  - [Declaring _program_ variable](#declaring-program-variable)
  - [Options](#options)
    - [Common option types, boolean and value](#common-option-types-boolean-and-value)
    - [Default option value](#default-option-value)
    - [Other option types, negatable boolean and boolean|value](#other-option-types-negatable-boolean-and-booleanvalue)
    - [Required option](#required-option)
    - [Variadic option](#variadic-option)
    - [Version option](#version-option)
    - [More configuration](#more-configuration)
    - [Custom option processing](#custom-option-processing)
  - [Commands](#commands)
    - [Specify the argument syntax](#specify-the-argument-syntax)
    - [Action handler](#action-handler)
    - [Stand-alone executable (sub)commands](#stand-alone-executable-subcommands)
  - [Automated help](#automated-help)
    - [Custom help](#custom-help)
    - [Display help from code](#display-help-from-code)
    - [.usage and .name](#usage-and-name)
    - [.helpOption(flags, description)](#helpoptionflags-description)
    - [.addHelpCommand()](#addhelpcommand)
    - [More configuration](#more-configuration-1)
  - [Custom event listeners](#custom-event-listeners)
  - [Bits and pieces](#bits-and-pieces)
    - [.parse() and .parseAsync()](#parse-and-parseasync)
    - [Parsing Configuration](#parsing-configuration)
    - [Legacy options as properties](#legacy-options-as-properties)
    - [TypeScript](#typescript)
    - [createCommand()](#createcommand)
    - [Node options such as `--harmony`](#node-options-such-as---harmony)
    - [Debugging stand-alone executable subcommands](#debugging-stand-alone-executable-subcommands)
    - [Override exit and output handling](#override-exit-and-output-handling)
    - [Additional documentation](#additional-documentation)
  - [Examples](#examples)
  - [Support](#support)
    - [Commander for enterprise](#commander-for-enterprise)

For information about terms used in this document see: [terminology](./docs/terminology.md)

## Installation

```bash
npm install commander
```

## Declaring _program_ variable

Commander exports a global object which is convenient for quick programs.
This is used in the examples in this README for brevity.

```js
const { program } = require('commander');
program.version('0.0.1');
```

For larger programs which may use commander in multiple ways, including unit testing, it is better to create a local Command object to use.

```js
const { Command } = require('commander');
const program = new Command();
program.version('0.0.1');
```

For named imports in ECMAScript modules, import from `commander/esm.mjs`.

```js
// index.mjs
import { Command } from 'commander/esm.mjs';
const program = new Command();
```

And in TypeScript:

```ts
// index.ts
import { Command } from 'commander';
const program = new Command();
```


## Options

Options are defined with the `.option()` method, also serving as documentation for the options. Each option can have a short flag (single character) and a long name, separated by a comma or space or vertical bar ('|').

The parsed options can be accessed by calling `.opts()` on a `Command` object, and are passed to the action handler. Multi-word options such as "--template-engine" are camel-cased, becoming `program.opts().templateEngine` etc.

Multiple short flags may optionally be combined in a single argument following the dash: boolean flags, followed by a single option taking a value (possibly followed by the value).
For example `-a -b -p 80` may be written as `-ab -p80` or even `-abp80`.

You can use `--` to indicate the end of the options, and any remaining arguments will be used without being interpreted.

By default options on the command line are not positional, and can be specified before or after other arguments.

### Common option types, boolean and value

The two most used option types are a boolean option, and an option which takes its value
from the following argument (declared with angle brackets like `--expect <value>`). Both are `undefined` unless specified on command line.  

Example file: [options-common.js](./examples/options-common.js)

```js
program
  .option('-d, --debug', 'output extra debugging')
  .option('-s, --small', 'small pizza size')
  .option('-p, --pizza-type <type>', 'flavour of pizza');

program.parse(process.argv);

const options = program.opts();
if (options.debug) console.log(options);
console.log('pizza details:');
if (options.small) console.log('- small pizza size');
if (options.pizzaType) console.log(`- ${options.pizzaType}`);
```

```bash
$ pizza-options -d
{ debug: true, small: undefined, pizzaType: undefined }
pizza details:
$ pizza-options -p
error: option '-p, --pizza-type <type>' argument missing
$ pizza-options -ds -p vegetarian
{ debug: true, small: true, pizzaType: 'vegetarian' }
pizza details:
- small pizza size
- vegetarian
$ pizza-options --pizza-type=cheese
pizza details:
- cheese
```

`program.parse(arguments)` processes the arguments, leaving any args not consumed by the program options in the `program.args` array. The parameter is optional and defaults to `process.argv`.

### Default option value

You can specify a default value for an option which takes a value.

Example file: [options-defaults.js](./examples/options-defaults.js)

```js
program
  .option('-c, --cheese <type>', 'add the specified type of cheese', 'blue');

program.parse();

console.log(`cheese: ${program.opts().cheese}`);
```

```bash
$ pizza-options
cheese: blue
$ pizza-options --cheese stilton
cheese: stilton
```

### Other option types, negatable boolean and boolean|value

You can define a boolean option long name with a leading `no-` to set the option value to false when used.
Defined alone this also makes the option true by default.

If you define `--foo` first, adding `--no-foo` does not change the default value from what it would
otherwise be. You can specify a default boolean value for a boolean option and it can be overridden on command line.

Example file: [options-negatable.js](./examples/options-negatable.js)

```js
program
  .option('--no-sauce', 'Remove sauce')
  .option('--cheese <flavour>', 'cheese flavour', 'mozzarella')
  .option('--no-cheese', 'plain with no cheese')
  .parse();

const options = program.opts();
const sauceStr = options.sauce ? 'sauce' : 'no sauce';
const cheeseStr = (options.cheese === false) ? 'no cheese' : `${options.cheese} cheese`;
console.log(`You ordered a pizza with ${sauceStr} and ${cheeseStr}`);
```

```bash
$ pizza-options
You ordered a pizza with sauce and mozzarella cheese
$ pizza-options --sauce
error: unknown option '--sauce'
$ pizza-options --cheese=blue
You ordered a pizza with sauce and blue cheese
$ pizza-options --no-sauce --no-cheese
You ordered a pizza with no sauce and no cheese
```

You can specify an option which may be used as a boolean option but may optionally take an option-argument
(declared with square brackets like `--optional [value]`).

Example file: [options-boolean-or-value.js](./examples/options-boolean-or-value.js)

```js
program
  .option('-c, --cheese [type]', 'Add cheese with optional type');

program.parse(process.argv);

const options = program.opts();
if (options.cheese === undefined) console.log('no cheese');
else if (options.cheese === true) console.log('add cheese');
else console.log(`add cheese type ${options.cheese}`);
```

```bash
$ pizza-options
no cheese
$ pizza-options --cheese
add cheese
$ pizza-options --cheese mozzarella
add cheese type mozzarella
```

For information about possible ambiguous cases, see [options taking varying arguments](./docs/options-taking-varying-arguments.md).

### Required option

You may specify a required (mandatory) option using `.requiredOption`. The option must have a value after parsing, usually specified on the command line, or perhaps from a default value (say from environment). The method is otherwise the same as `.option` in format, taking flags and description, and optional default value or custom processing.

Example file: [options-required.js](./examples/options-required.js)

```js
program
  .requiredOption('-c, --cheese <type>', 'pizza must have cheese');

program.parse();
```

```bash
$ pizza
error: required option '-c, --cheese <type>' not specified
```

### Variadic option

You may make an option variadic by appending `...` to the value placeholder when declaring the option. On the command line you
can then specify multiple option-arguments, and the parsed option value will be an array. The extra arguments
are read until the first argument starting with a dash. The special argument `--` stops option processing entirely. If a value
is specified in the same argument as the option then no further values are read.

Example file: [options-variadic.js](./examples/options-variadic.js)

```js
program
  .option('-n, --number <numbers...>', 'specify numbers')
  .option('-l, --letter [letters...]', 'specify letters');

program.parse();

console.log('Options: ', program.opts());
console.log('Remaining arguments: ', program.args);
```

```bash
$ collect -n 1 2 3 --letter a b c
Options:  { number: [ '1', '2', '3' ], letter: [ 'a', 'b', 'c' ] }
Remaining arguments:  []
$ collect --letter=A -n80 operand
Options:  { number: [ '80' ], letter: [ 'A' ] }
Remaining arguments:  [ 'operand' ]
$ collect --letter -n 1 -n 2 3 -- operand
Options:  { number: [ '1', '2', '3' ], letter: true }
Remaining arguments:  [ 'operand' ]
```

For information about possible ambiguous cases, see [options taking varying arguments](./docs/options-taking-varying-arguments.md).

### Version option

The optional `version` method adds handling for displaying the command version. The default option flags are `-V` and `--version`, and when present the command prints the version number and exits.

```js
program.version('0.0.1');
```

```bash
$ ./examples/pizza -V
0.0.1
```

You may change the flags and description by passing additional parameters to the `version` method, using
the same syntax for flags as the `option` method.

```js
program.version('0.0.1', '-v, --vers', 'output the current version');
```

### More configuration

You can add most options using the `.option()` method, but there are some additional features available
by constructing an `Option` explicitly for less common cases.

Example file: [options-extra.js](./examples/options-extra.js)

```js
program
  .addOption(new Option('-s, --secret').hideHelp())
  .addOption(new Option('-t, --timeout <delay>', 'timeout in seconds').default(60, 'one minute'))
  .addOption(new Option('-d, --drink <size>', 'drink size').choices(['small', 'medium', 'large']));
```

```bash
$ extra --help
Usage: help [options]

Options:
  -t, --timeout <delay>  timeout in seconds (default: one minute)
  -d, --drink <size>     drink cup size (choices: "small", "medium", "large")
  -h, --help             display help for command

$ extra --drink huge
error: option '-d, --drink <size>' argument 'huge' is invalid. Allowed choices are small, medium, large.
```

### Custom option processing

You may specify a function to do custom processing of option-arguments. The callback function receives two parameters,
the user specified option-argument and the previous value for the option. It returns the new value for the option.

This allows you to coerce the option-argument to the desired type, or accumulate values, or do entirely custom processing.

You can optionally specify the default/starting value for the option after the function parameter.

Example file: [options-custom-processing.js](./examples/options-custom-processing.js)

```js
function myParseInt(value, dummyPrevious) {
  // parseInt takes a string and a radix
  const parsedValue = parseInt(value, 10);
  if (isNaN(parsedValue)) {
    throw new commander.InvalidOptionArgumentError('Not a number.');
  }
  return parsedValue;
}

function increaseVerbosity(dummyValue, previous) {
  return previous + 1;
}

function collect(value, previous) {
  return previous.concat([value]);
}

function commaSeparatedList(value, dummyPrevious) {
  return value.split(',');
}

program
  .option('-f, --float <number>', 'float argument', parseFloat)
  .option('-i, --integer <number>', 'integer argument', myParseInt)
  .option('-v, --verbose', 'verbosity that can be increased', increaseVerbosity, 0)
  .option('-c, --collect <value>', 'repeatable value', collect, [])
  .option('-l, --list <items>', 'comma separated list', commaSeparatedList)
;

program.parse();

const options = program.opts();
if (options.float !== undefined) console.log(`float: ${options.float}`);
if (options.integer !== undefined) console.log(`integer: ${options.integer}`);
if (options.verbose > 0) console.log(`verbosity: ${options.verbose}`);
if (options.collect.length > 0) console.log(options.collect);
if (options.list !== undefined) console.log(options.list);
```

```bash
$ custom -f 1e2
float: 100
$ custom --integer 2
integer: 2
$ custom -v -v -v
verbose: 3
$ custom -c a -c b -c c
[ 'a', 'b', 'c' ]
$ custom --list x,y,z
[ 'x', 'y', 'z' ]
```

## Commands

You can specify (sub)commands using `.command()` or `.addCommand()`. There are two ways these can be implemented: using an action handler attached to the command, or as a stand-alone executable file (described in more detail later). The subcommands may be nested ([example](./examples/nestedCommands.js)).

In the first parameter to `.command()` you specify the command name and any command-arguments. The arguments may be `<required>` or `[optional]`, and the last argument may also be `variadic...`.

You can use `.addCommand()` to add an already configured subcommand to the program.

For example:

```js
// Command implemented using action handler (description is supplied separately to `.command`)
// Returns new command for configuring.
program
  .command('clone <source> [destination]')
  .description('clone a repository into a newly created directory')
  .action((source, destination) => {
    console.log('clone command called');
  });

// Command implemented using stand-alone executable file (description is second parameter to `.command`)
// Returns `this` for adding more commands.
program
  .command('start <service>', 'start named service')
  .command('stop [service]', 'stop named service, or all if no name supplied');

// Command prepared separately.
// Returns `this` for adding more commands.
program
  .addCommand(build.makeBuildCommand());
```

Configuration options can be passed with the call to `.command()` and `.addCommand()`. Specifying `hidden: true` will 
remove the command from the generated help output. Specifying `isDefault: true` will run the subcommand if no other
subcommand is specified ([example](./examples/defaultCommand.js)).

### Specify the argument syntax

You use `.arguments` to specify the expected command-arguments for the top-level command, and for subcommands they are usually
included in the `.command` call. Angled brackets (e.g. `<required>`) indicate required command-arguments.
Square brackets (e.g. `[optional]`) indicate optional command-arguments.
You can optionally describe the arguments in the help by supplying a hash as second parameter to `.description()`.

Example file: [arguments.js](./examples/arguments.js)

```js
program
  .version('0.1.0')
  .arguments('<username> [password]')
  .description('test command', {
    username: 'user to login',
    password: 'password for user, if required'
  })
  .action((username, password) => {
    console.log('username:', username);
    console.log('environment:', password || 'no password given');
  });
```

 The last argument of a command can be variadic, and only the last argument.  To make an argument variadic you
 append `...` to the argument name. For example:

```js
program
  .version('0.1.0')
  .command('rmdir <dirs...>')
  .action(function (dirs) {
    dirs.forEach((dir) => {
      console.log('rmdir %s', dir);
    });
  });
```

The variadic argument is passed to the action handler as an array.

### Action handler

The action handler gets passed a parameter for each command-argument you declared, and two additional parameters
which are the parsed options and the command object itself. 

Example file: [thank.js](./examples/thank.js)

```js
program
  .arguments('<name>')
  .option('-t, --title <honorific>', 'title to use before name')
  .option('-d, --debug', 'display some debugging')
  .action((name, options, command) => {
    if (options.debug) {
      console.error('Called %s with options %o', command.name(), options);
    }
    const title = options.title ? `${options.title} ` : '';
    console.log(`Thank-you ${title}${name}`);
  });
```

You may supply an `async` action handler, in which case you call `.parseAsync` rather than `.parse`.

```js
async function run() { /* code goes here */ }

async function main() {
  program
    .command('run')
    .action(run);
  await program.parseAsync(process.argv);
}
```

A command's options and arguments on the command line are validated when the command is used. Any unknown options or missing arguments will be reported as an error. You can suppress the unknown option checks with `.allowUnknownOption()`. By default it is not an error to
pass more arguments than declared, but you can make this an error with `.allowExcessArguments(false)`.

### Stand-alone executable (sub)commands

When `.command()` is invoked with a description argument, this tells Commander that you're going to use stand-alone executables for subcommands.
Commander will search the executables in the directory of the entry script (like `./examples/pm`) with the name `program-subcommand`, like `pm-install`, `pm-search`.
You can specify a custom name with the `executableFile` configuration option.

You handle the options for an executable (sub)command in the executable, and don't declare them at the top-level.

Example file: [pm](./examples/pm)

```js
program
  .version('0.1.0')
  .command('install [name]', 'install one or more packages')
  .command('search [query]', 'search with optional query')
  .command('update', 'update installed packages', { executableFile: 'myUpdateSubCommand' })
  .command('list', 'list packages installed', { isDefault: true });

program.parse(process.argv);
```

If the program is designed to be installed globally, make sure the executables have proper modes, like `755`.

## Automated help

The help information is auto-generated based on the information commander already knows about your program. The default
help option is `-h,--help`.

Example file: [pizza](./examples/pizza)

```bash
$ node ./examples/pizza --help
Usage: pizza [options]

An application for pizza ordering

Options:
  -p, --peppers        Add peppers
  -c, --cheese <type>  Add the specified type of cheese (default: "marble")
  -C, --no-cheese      You do not want any cheese
  -h, --help           display help for command
```

A `help` command is added by default if your command has subcommands. It can be used alone, or with a subcommand name to show
further help for the subcommand. These are effectively the same if the `shell` program has implicit help:

```bash
shell help
shell --help

shell help spawn
shell spawn --help
```

### Custom help

You can add extra text to be displayed along with the built-in help. 

Example file: [custom-help](./examples/custom-help)

```js
program
  .option('-f, --foo', 'enable some foo');

program.addHelpText('after', `

Example call:
  $ custom-help --help`);
```

Yields the following help output:

```Text
Usage: custom-help [options]

Options:
  -f, --foo   enable some foo
  -h, --help  display help for command

Example call:
  $ custom-help --help
```

The positions in order displayed are:

- `beforeAll`: add to the program for a global banner or header
- `before`: display extra information before built-in help
- `after`: display extra information after built-in help
- `afterAll`: add to the program for a global footer (epilog)

The positions "beforeAll" and "afterAll" apply to the command and all its subcommands. 

The second parameter can be a string, or a function returning a string. The function is passed a context object for your convenience. The properties are:

- error: a boolean for whether the help is being displayed due to a usage error
- command: the Command which is displaying the help

### Display help from code

`.help()`: display help information and exit immediately. You can optionally pass `{ error: true }` to display on stderr and exit with an error status.

`.outputHelp()`: output help information without exiting. You can optionally pass `{ error: true }` to display on stderr.

`.helpInformation()`: get the built-in command help information as a string for processing or displaying yourself.

### .usage and .name

These allow you to customise the usage description in the first line of the help. The name is otherwise
deduced from the (full) program arguments. Given:

```js
program
  .name("my-command")
  .usage("[global options] command")
```

The help will start with:

```Text
Usage: my-command [global options] command
```

### .helpOption(flags, description)

By default every command has a help option. Override the default help flags and description. Pass false to disable the built-in help option.

```js
program
  .helpOption('-e, --HELP', 'read more information');
```

### .addHelpCommand()

A help command is added by default if your command has subcommands. You can explicitly turn on or off the implicit help command with `.addHelpCommand()` and `.addHelpCommand(false)`.

You can both turn on and customise the help command by supplying the name and description:

```js
program.addHelpCommand('assist [command]', 'show assistance');
```

### More configuration

The built-in help is formatted using the Help class.
You can configure the Help behaviour by modifying data properties and methods using `.configureHelp()`, or by subclassing using `.createHelp()` if you prefer.

The data properties are:

- `helpWidth`: specify the wrap width, useful for unit tests
- `sortSubcommands`: sort the subcommands alphabetically
- `sortOptions`: sort the options alphabetically

There are methods getting the visible lists of arguments, options, and subcommands. There are methods for formatting the items in the lists, with each item having a _term_ and _description_. Take a look at `.formatHelp()` to see how they are used.

Example file: [configure-help.js](./examples/configure-help.js)

```
program.configureHelp({
  sortSubcommands: true,
  subcommandTerm: (cmd) => cmd.name() // Just show the name, instead of short usage.
});
```

## Custom event listeners

You can execute custom actions by listening to command and option events.

```js
program.on('option:verbose', function () {
  process.env.VERBOSE = this.opts().verbose;
});

program.on('command:*', function (operands) {
  console.error(`error: unknown command '${operands[0]}'`);
  const availableCommands = program.commands.map(cmd => cmd.name());
  mySuggestBestMatch(operands[0], availableCommands);
  process.exitCode = 1;
});
```

## Bits and pieces

### .parse() and .parseAsync()

The first argument to `.parse` is the array of strings to parse. You may omit the parameter to implicitly use `process.argv`.

If the arguments follow different conventions than node you can pass a `from` option in the second parameter:

- 'node': default, `argv[0]` is the application and `argv[1]` is the script being run, with user parameters after that
- 'electron': `argv[1]` varies depending on whether the electron application is packaged
- 'user': all of the arguments from the user

For example:

```js
program.parse(process.argv); // Explicit, node conventions
program.parse(); // Implicit, and auto-detect electron
program.parse(['-f', 'filename'], { from: 'user' });
```

### Parsing Configuration

If the default parsing does not suit your needs, there are some behaviours to support other usage patterns.

By default program options are recognised before and after subcommands. To only look for program options before subcommands, use `.enablePositionalOptions()`. This lets you use
an option for a different purpose in subcommands.

Example file: [positional-options.js](./examples/positional-options.js)

With positional options, the `-b` is a program option in the first line and a subcommand option in the second line:

```sh
program -b subcommand
program subcommand -b
```

By default options are recognised before and after command-arguments. To only process options that come
before the command-arguments, use `.passThroughOptions()`. This lets you pass the  arguments and following options through to another program
without needing to use `--` to end the option processing. 
To use pass through options in a subcommand, the program needs to enable positional options.

Example file: [pass-through-options.js](./examples/pass-through-options.js)

With pass through options, the `--port=80` is a program option in the first line and passed through as a command-argument in the second line:

```sh
program --port=80 arg
program arg --port=80
```

By default the option processing shows an error for an unknown option. To have an unknown option treated as an ordinary command-argument and continue looking for options, use `.allowUnknownOption()`. This lets you mix known and unknown options.

By default the argument processing does not display an error for more command-arguments than expected.
To display an error for excess arguments, use`.allowExcessArguments(false)`.

### Legacy options as properties 

Before Commander 7, the option values were stored as properties on the command.
This was convenient to code but the downside was possible clashes with
existing properties of `Command`. You can revert to the old behaviour to run unmodified legacy code by using `.storeOptionsAsProperties()`.

```js
program
  .storeOptionsAsProperties()
  .option('-d, --debug')
  .action((commandAndOptions) => {
    if (commandAndOptions.debug) {
      console.error(`Called ${commandAndOptions.name()}`);
    }
  });
```

### TypeScript

If you use `ts-node` and  stand-alone executable subcommands written as `.ts` files, you need to call your program through node to get the subcommands called correctly. e.g.

```bash
node -r ts-node/register pm.ts
```

### createCommand()

This factory function creates a new command. It is exported and may be used instead of using `new`, like:

```js
const { createCommand } = require('commander');
const program = createCommand();
```

`createCommand` is also a method of the Command object, and creates a new command rather than a subcommand. This gets used internally
when creating subcommands using `.command()`, and you may override it to
customise the new subcommand (example file [custom-command-class.js](./examples/custom-command-class.js)).

### Node options such as `--harmony`

You can enable `--harmony` option in two ways:

- Use `#! /usr/bin/env node --harmony` in the subcommands scripts. (Note Windows does not support this pattern.)
- Use the `--harmony` option when call the command, like `node --harmony examples/pm publish`. The `--harmony` option will be preserved when spawning subcommand process.

### Debugging stand-alone executable subcommands

An executable subcommand is launched as a separate child process.

If you are using the node inspector for [debugging](https://nodejs.org/en/docs/guides/debugging-getting-started/) executable subcommands using `node --inspect` et al,
the inspector port is incremented by 1 for the spawned subcommand.

If you are using VSCode to debug executable subcommands you need to set the `"autoAttachChildProcesses": true` flag in your launch.json configuration.

### Override exit and output handling

By default Commander calls `process.exit` when it detects errors, or after displaying the help or version. You can override
this behaviour and optionally supply a callback. The default override throws a `CommanderError`.

The override callback is passed a `CommanderError` with properties `exitCode` number, `code` string, and `message`. The default override behaviour is to throw the error, except for async handling of executable subcommand completion which carries on. The normal display of error messages or version or help
is not affected by the override which is called after the display.

```js
program.exitOverride();

try {
  program.parse(process.argv);
} catch (err) {
  // custom processing...
}
```

By default Commander is configured for a command-line application and writes to stdout and stderr.
You can modify this behaviour for custom applications. In addition, you can modify the display of error messages.

Example file: [configure-output.js](./examples/configure-output.js)


```js
function errorColor(str) {
  // Add ANSI escape codes to display text in red.
  return `\x1b[31m${str}\x1b[0m`;
}

program
  .configureOutput({
    // Visibly override write routines as example!
    writeOut: (str) => process.stdout.write(`[OUT] ${str}`),
    writeErr: (str) => process.stdout.write(`[ERR] ${str}`),
    // Highlight errors in color.
    outputError: (str, write) => write(errorColor(str))
  });
```

### Additional documentation

There is more information available about:

- [deprecated](./docs/deprecated.md) features still supported for backwards compatibility
- [options taking varying arguments](./docs/options-taking-varying-arguments.md)

## Examples

In a single command program, you might not need an action handler.

Example file: [pizza](./examples/pizza)

```js
const { program } = require('commander');

program
  .description('An application for pizza ordering')
  .option('-p, --peppers', 'Add peppers')
  .option('-c, --cheese <type>', 'Add the specified type of cheese', 'marble')
  .option('-C, --no-cheese', 'You do not want any cheese');

program.parse();

const options = program.opts();
console.log('you ordered a pizza with:');
if (options.peppers) console.log('  - peppers');
const cheese = !options.cheese ? 'no' : options.cheese;
console.log('  - %s cheese', cheese);
```

In a multi-command program, you will have action handlers for each command (or stand-alone executables for the commands).

Example file: [deploy](./examples/deploy)

```js
const { Command } = require('commander');
const program = new Command();

program
  .version('0.0.1')
  .option('-c, --config <path>', 'set config path', './deploy.conf');

program
  .command('setup [env]')
  .description('run setup commands for all envs')
  .option('-s, --setup_mode <mode>', 'Which setup mode to use', 'normal')
  .action((env, options) => {
    env = env || 'all';
    console.log('read config from %s', program.opts().config);
    console.log('setup for %s env(s) with %s mode', env, options.setup_mode);
  });

program
  .command('exec <script>')
  .alias('ex')
  .description('execute the given remote cmd')
  .option('-e, --exec_mode <mode>', 'Which exec mode to use', 'fast')
  .action((script, options) => {
    console.log('read config from %s', program.opts().config);
    console.log('exec "%s" using %s mode and config %s', script, options.exec_mode, program.opts().config);
  }).addHelpText('after', `
Examples:
  $ deploy exec sequential
  $ deploy exec async`
  );
  
program.parse(process.argv);
```

More samples can be found in the [examples](https://github.com/tj/commander.js/tree/master/examples) directory.

## Support

The current version of Commander is fully supported on Long Term Support versions of node, and requires at least node v10.
(For older versions of node, use an older version of Commander. Commander version 2.x has the widest support.)

The main forum for free and community support is the project [Issues](https://github.com/tj/commander.js/issues) on GitHub.

### Commander for enterprise

Available as part of the Tidelift Subscription

The maintainers of Commander and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-commander?utm_source=npm-commander&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)


---

# Tapable

The tapable package expose many Hook classes, which can be used to create hooks for plugins.

``` javascript
const {
	SyncHook,
	SyncBailHook,
	SyncWaterfallHook,
	SyncLoopHook,
	AsyncParallelHook,
	AsyncParallelBailHook,
	AsyncSeriesHook,
	AsyncSeriesBailHook,
	AsyncSeriesWaterfallHook
 } = require("tapable");
```

## Installation

``` shell
npm install --save tapable
```

## Usage

All Hook constructors take one optional argument, which is a list of argument names as strings.

``` js
const hook = new SyncHook(["arg1", "arg2", "arg3"]);
```

The best practice is to expose all hooks of a class in a `hooks` property:

``` js
class Car {
	constructor() {
		this.hooks = {
			accelerate: new SyncHook(["newSpeed"]),
			brake: new SyncHook(),
			calculateRoutes: new AsyncParallelHook(["source", "target", "routesList"])
		};
	}

	/* ... */
}
```

Other people can now use these hooks:

``` js
const myCar = new Car();

// Use the tap method to add a consument
myCar.hooks.brake.tap("WarningLampPlugin", () => warningLamp.on());
```

It's required to pass a name to identify the plugin/reason.

You may receive arguments:

``` js
myCar.hooks.accelerate.tap("LoggerPlugin", newSpeed => console.log(`Accelerating to ${newSpeed}`));
```

For sync hooks, `tap` is the only valid method to add a plugin. Async hooks also support async plugins:

``` js
myCar.hooks.calculateRoutes.tapPromise("GoogleMapsPlugin", (source, target, routesList) => {
	// return a promise
	return google.maps.findRoute(source, target).then(route => {
		routesList.add(route);
	});
});
myCar.hooks.calculateRoutes.tapAsync("BingMapsPlugin", (source, target, routesList, callback) => {
	bing.findRoute(source, target, (err, route) => {
		if(err) return callback(err);
		routesList.add(route);
		// call the callback
		callback();
	});
});

// You can still use sync plugins
myCar.hooks.calculateRoutes.tap("CachedRoutesPlugin", (source, target, routesList) => {
	const cachedRoute = cache.get(source, target);
	if(cachedRoute)
		routesList.add(cachedRoute);
})
```
The class declaring these hooks need to call them:

``` js
class Car {
	/**
	  * You won't get returned value from SyncHook or AsyncParallelHook,
	  * to do that, use SyncWaterfallHook and AsyncSeriesWaterfallHook respectively
	 **/

	setSpeed(newSpeed) {
		// following call returns undefined even when you returned values
		this.hooks.accelerate.call(newSpeed);
	}

	useNavigationSystemPromise(source, target) {
		const routesList = new List();
		return this.hooks.calculateRoutes.promise(source, target, routesList).then((res) => {
			// res is undefined for AsyncParallelHook
			return routesList.getRoutes();
		});
	}

	useNavigationSystemAsync(source, target, callback) {
		const routesList = new List();
		this.hooks.calculateRoutes.callAsync(source, target, routesList, err => {
			if(err) return callback(err);
			callback(null, routesList.getRoutes());
		});
	}
}
```

The Hook will compile a method with the most efficient way of running your plugins. It generates code depending on:
* The number of registered plugins (none, one, many)
* The kind of registered plugins (sync, async, promise)
* The used call method (sync, async, promise)
* The number of arguments
* Whether interception is used

This ensures fastest possible execution.

## Hook types

Each hook can be tapped with one or several functions. How they are executed depends on the hook type:

* Basic hook (without “Waterfall”, “Bail” or “Loop” in its name). This hook simply calls every function it tapped in a row.

* __Waterfall__. A waterfall hook also calls each tapped function in a row. Unlike the basic hook, it passes a return value from each function to the next function.

* __Bail__. A bail hook allows exiting early. When any of the tapped function returns anything, the bail hook will stop executing the remaining ones.

* __Loop__. When a plugin in a loop hook returns a non-undefined value the hook will restart from the first plugin. It will loop until all plugins return undefined.

Additionally, hooks can be synchronous or asynchronous. To reflect this, there’re “Sync”, “AsyncSeries”, and “AsyncParallel” hook classes:

* __Sync__. A sync hook can only be tapped with synchronous functions (using `myHook.tap()`).

* __AsyncSeries__. An async-series hook can be tapped with synchronous, callback-based and promise-based functions (using `myHook.tap()`, `myHook.tapAsync()` and `myHook.tapPromise()`). They call each async method in a row.

* __AsyncParallel__. An async-parallel hook can also be tapped with synchronous, callback-based and promise-based functions (using `myHook.tap()`, `myHook.tapAsync()` and `myHook.tapPromise()`). However, they run each async method in parallel.

The hook type is reflected in its class name. E.g., `AsyncSeriesWaterfallHook` allows asynchronous functions and runs them in series, passing each function’s return value into the next function.


## Interception

All Hooks offer an additional interception API:

``` js
myCar.hooks.calculateRoutes.intercept({
	call: (source, target, routesList) => {
		console.log("Starting to calculate routes");
	},
	register: (tapInfo) => {
		// tapInfo = { type: "promise", name: "GoogleMapsPlugin", fn: ... }
		console.log(`${tapInfo.name} is doing its job`);
		return tapInfo; // may return a new tapInfo object
	}
})
```

**call**: `(...args) => void` Adding `call` to your interceptor will trigger when hooks are triggered. You have access to the hooks arguments.

**tap**: `(tap: Tap) => void` Adding `tap` to your interceptor will trigger when a plugin taps into a hook. Provided is the `Tap` object. `Tap` object can't be changed.

**loop**: `(...args) => void` Adding `loop` to your interceptor will trigger for each loop of a looping hook.

**register**: `(tap: Tap) => Tap | undefined` Adding `register` to your interceptor will trigger for each added `Tap` and allows to modify it.

## Context

Plugins and interceptors can opt-in to access an optional `context` object, which can be used to pass arbitrary values to subsequent plugins and interceptors.

``` js
myCar.hooks.accelerate.intercept({
	context: true,
	tap: (context, tapInfo) => {
		// tapInfo = { type: "sync", name: "NoisePlugin", fn: ... }
		console.log(`${tapInfo.name} is doing it's job`);

		// `context` starts as an empty object if at least one plugin uses `context: true`.
		// If no plugins use `context: true`, then `context` is undefined.
		if (context) {
			// Arbitrary properties can be added to `context`, which plugins can then access.
			context.hasMuffler = true;
		}
	}
});

myCar.hooks.accelerate.tap({
	name: "NoisePlugin",
	context: true
}, (context, newSpeed) => {
	if (context && context.hasMuffler) {
		console.log("Silence...");
	} else {
		console.log("Vroom!");
	}
});
```

## HookMap

A HookMap is a helper class for a Map with Hooks

``` js
const keyedHook = new HookMap(key => new SyncHook(["arg"]))
```

``` js
keyedHook.for("some-key").tap("MyPlugin", (arg) => { /* ... */ });
keyedHook.for("some-key").tapAsync("MyPlugin", (arg, callback) => { /* ... */ });
keyedHook.for("some-key").tapPromise("MyPlugin", (arg) => { /* ... */ });
```

``` js
const hook = keyedHook.get("some-key");
if(hook !== undefined) {
	hook.callAsync("arg", err => { /* ... */ });
}
```

## Hook/HookMap interface

Public:

``` ts
interface Hook {
	tap: (name: string | Tap, fn: (context?, ...args) => Result) => void,
	tapAsync: (name: string | Tap, fn: (context?, ...args, callback: (err, result: Result) => void) => void) => void,
	tapPromise: (name: string | Tap, fn: (context?, ...args) => Promise<Result>) => void,
	intercept: (interceptor: HookInterceptor) => void
}

interface HookInterceptor {
	call: (context?, ...args) => void,
	loop: (context?, ...args) => void,
	tap: (context?, tap: Tap) => void,
	register: (tap: Tap) => Tap,
	context: boolean
}

interface HookMap {
	for: (key: any) => Hook,
	intercept: (interceptor: HookMapInterceptor) => void
}

interface HookMapInterceptor {
	factory: (key: any, hook: Hook) => Hook
}

interface Tap {
	name: string,
	type: string
	fn: Function,
	stage: number,
	context: boolean,
	before?: string | Array
}
```

Protected (only for the class containing the hook):

``` ts
interface Hook {
	isUsed: () => boolean,
	call: (...args) => Result,
	promise: (...args) => Promise<Result>,
	callAsync: (...args, callback: (err, result: Result) => void) => void,
}

interface HookMap {
	get: (key: any) => Hook | undefined,
	for: (key: any) => Hook
}
```

## MultiHook

A helper Hook-like class to redirect taps to multiple other hooks:

``` js
const { MultiHook } = require("tapable");

this.hooks.allHooks = new MultiHook([this.hooks.hookA, this.hooks.hookB]);
```


---

# Changelog

## v5.39.0

 - Remove unnecessary `console.assert` calls (#1590)

## v5.38.2

 - internal: Flatten inheritance tree for object/class members

## v5.38.1

 - Fix inlining non-call expressions into an `optional_call?.()`

## v5.38.0

 - Remove `console` method-of-method calls (eg `console.log.apply()`) when `drop_console` option is used (#1585)
 - Remove more object spreads, such as `{ ...void !0 }` (#1142)

## v5.37.0

 - Reserved object properties from chrome extensions (domprops)
 - Fix semicolon insertion between a class property without a semicolon `a` and a computed class property `["prop"]`

## v5.36.0

 - Support import attributes `with` syntax

## v5.35.0

 - Ensure parent directory exists when using --output on CLI (#1530)

## v5.34.1

 - bump the rollup devDependency to disable CVE warnings (Terser was not affected)

## v5.34.0

 - internal: stop assigning properties to objects they don't belong in
 - internal: run compress tests in parallel
 - `drop_console`: emit an empty function if the return value of `console.METHOD(...)` may be called.

## v5.33.0

 - `reduce_vars` improved when dealing with hoisted function definitions (#1544)

## v5.32.0

 - `import("module")` can now be input and output from ESTree AST (#1557)
 - `BigInt` literals can now be input and output from ESTree AST (#1555)
 - `typeof` an object or array (`typeof {}` and `typeof []`) can now be statically evaluated. (#1546)

## v5.31.6
 - Retain side effects in a `case` when the expression is a sequence (comma) expression

## v5.31.5
 - Revert v5.31.4, which created mysterious issues #1548, #1549

## v5.31.4 (reverted)
 - drop_unused: drop classes which only have side effects in the `extends` part

## v5.31.3
 - drop_unused: drop unused parameters from IIFEs in some more situations.

## v5.31.2
 - drop_unused: scan variables in self-referential class declarations that contain side effects.
 - Don't add parens to arrow function when it's the default for an argument (#1540)
 - Update domprops (#1538)

## v5.31.1
 - Allow drop-unused to drop the whole assignment (not just the assigned name) in more situations, in order to avoid duplication of long strings.

## v5.31.0
 - Sync up property mangler exceptions with current contents of Firefox and Chrome environments
 - Add more webcomponent properties to property mangler exceptions (#1525)
 - Drop non-nullish constants in `...spreads` in objects (#1141)

## v5.30.4
 - Fix parsing `#private in ...` when next to other operators

## v5.30.3
 - Fix precedence of `#private in ...` operator

## v5.30.2
 - Avoid optimizations inside computed keys, because they can cause js-engine-specific bugs.

## v5.30.1
 - Removed useless `\` escapes for non-ascii characters
 - Make modern identifier characters quoted for older environments (#1512)

## v5.30.0
 - Improve removal of classes referring to themselves

## v5.29.2
 - Make sure 'computed_props' creates string keys
 - Take into account the evaluated size when inlining

## v5.29.1
 - fix optimisation of all-bits mask check

## v5.29.0
 - Re-releases previously reverted 5.28.0
 - Fix crash while optimizing some bitwise ops
 - (internal) Remove needless wrapper for from_moz (#1499)

## v5.28.1
(hotfix release)
 - Reverts v5.28.0

## v5.28.0
 - Optimise redundant or shrinkable bitwise operations (`|`, `^`, `&`, `>>`, `<<`)
 - Evaluate some `BigInt` math operations

## v5.27.2
 - Recognise `this` as a reference to the surrounding class in `drop_unused`. Closes #1472

## v5.27.1
 - Fixed case where `collapse_vars` inlines `await` expressions into non-async functions.

## v5.27.0
 - Created `minify_sync()` alternative to `minify()` since there's no async code left.

## v5.26.0
 - Do not take the `/*#__PURE__*/` annotation into account when the `side_effects` compress option is off.
 - The `preserve_annotations` option now automatically opts annotation comments in, instead of requiring the `comments` option to be configured for this.
 - Refuse to parse empty parenthesized expressions (`()`)

## v5.25.0
 - Regex properties added to reserved property mangler (#1471)
 - `pure_new` option added to drop unused `new` expressions.

## v5.24.0
 - Improve formatting performance in V8 by keeping a small work string and a large output string

## v5.23.0
 - When top_retain will keep a variable assignment around, inline the assignee when it's shorter than the name (#1434)
 - Remove empty class `static {}` blocks.

## v5.22.0
 - Do not `unsafe`ly shorten expressions like a?.toString() when they're conditional.
 - Avoid running drop_unused in nodes that aren't scopes. Fixes a rare crash.
 - When 'module' is enabled, assume strict mode when figuring out scopes.

## v5.21.0
 - Do not inline functions that would be retained in the toplevel (as this would cause code duplication).
 - Fix precedence of arrow function and ternary operator when formatting output.

## v5.20.0
 - Passing `minify()` zero files will now throw a clean exception (#1450)
 - `drop_console` supports passing in an array of `console.*` method names (#1445)
 - New DOM properties from the WebGPU API have been added for use in the property mangler (#1436)
 - Internal code simplification (#1437)

## v5.19.4
 - Prevent creating very deeply nested ternaries from a long list of `if..return`
 - Prevent inlining classes into other functions, to avoid constructors being compared.

## v5.19.3
 - Fix side effect detection of `optional?.chains`.
 - Add roundRect to domprops.js (#1426)

## v5.19.2
 - fix performance hit from avoiding HTML comments in the output

## v5.19.1
 - Better avoid outputting `</script>` and HTML comments.
 - Fix unused variables in class static blocks not being dropped correctly.
 - Fix sourcemap names of methods that are `async` or `static`

## v5.19.0
 - Allow `/*@__MANGLE_PROP__*/` annotation in `object.property`, in addition to property declarations.

## v5.18.2
 - Stop using recursion in hoisted defuns fix.

## v5.18.1
 - Fix major performance issue caused by hoisted defuns' scopes bugfix.

## v5.18.0
 - Add new `/*@__MANGLE_PROP__*/` annotation, to mark properties that should be mangled.

## v5.17.7
 - Update some dependencies
 - Add consistent sorting for `v` RegExp flag
 - Add `inert` DOM attribute to domprops

## v5.17.6
 - Fixes to mozilla AST input and output, for class properties, private properties and static blocks
 - Fix outputting a shorthand property in quotes when safari10 and ecma=2015 options are enabled
 - `configurable` and `enumerable`, used in Object.defineProperty, added to domprops (#1393)

## v5.17.5
 - Take into account the non-deferred bits of a class, such as static properties, while dropping unused code.

## v5.17.4

 - Fix crash when trying to negate a class (`!class{}`)
 - Avoid outputting comments between `yield`/`await` and its argument
 - Fix detection of left-hand-side of assignment, to avoid optimizing it like any other expression in some edge cases

## v5.17.3

 - Fix issue with trimming a static class property's contents accessing the class as `this`.

## v5.17.2
 - Be less conservative when detecting use-before-definition of `var` in hoisted functions.
 - Support unusual (but perfectly valid) initializers of for-in and for-of loops.
 - Fix issue where hoisted function would be dropped if it was after a `continue` statement

## v5.17.1
 - Fix evaluating `.length` when the source array might've been mutated

## v5.17.0
 - Drop vestigial `= undefined` default argument in IIFE calls (#1366)
 - Evaluate known arrays' `.length` property when statically determinable
 - Add `@__KEY__` annotation to mangle string literals (#1365)

## v5.16.9
 - Fix parentheses in output of optional chains (`a?.b`) (#1374)
 - More documentation on source maps (#1368)
 - New `lhs_constants` option, allowing to stop Terser from swapping comparison operands (#1361)

## v5.16.8

 - Become even less conservative around function definitions for `reduce_vars`
 - Fix parsing context of `import.meta` expressions such that method calls are allowed

## v5.16.6

 - Become less conservative with analyzing function definitions for `reduce_vars`
 - Parse `import.meta` as a real AST node and not an `object.property`

## v5.16.5

 - Correctly handle AST transform functions that mutate children arrays
 - Don't mutate the options object passed to Terser (#1342)
 - Do not treat BigInt like a number

## v5.16.4

 - Keep `(defaultArg = undefined) => ...`, because default args don't count for function length
 - Prevent inlining variables into `?.` optional chains
 - Avoid removing unused arguments while transforming
 - Optimize iterating AST node lists
 - Make sure `catch` and `finally` aren't children of `try` in the AST
 - Use modern unicode property escapes (`\p{...}`) to parse identifiers when available

## v5.16.3

 - Ensure function definitions, don't assume the values of variables defined after them.

## v5.16.2

 - Fix sourcemaps with non-ascii characters (#1318)
 - Support string module name and export * as (#1336)
 - Do not move `let` out of `for` initializers, as it can change scoping
 - Fix a corner case that would generate the invalid syntax `if (something) let x` ("let" in braceless if body)
 - Knowledge of more native object properties (#1330)
 - Got rid of Travis (#1323)
 - Added semi-secret `asObject` sourcemap option to typescript defs (#1321)

## v5.16.1

 - Properly handle references in destructurings (`const { [reference]: val } = ...`)
 - Allow parsing of `.#privatefield` in nested classes
 - Do not evaluate operations that return large strings if that would make the output code larger
 - Make `collapse_vars` handle block scope correctly
 - Internal improvements: Typos (#1311), more tests, small-scale refactoring

## v5.16.0

 - Disallow private fields in object bodies (#1011)
 - Parse `#privatefield in object` (#1279)
 - Compress `#privatefield in object`

## v5.15.1

 - Fixed missing parentheses around optional chains
 - Avoid bare `let` or `const` as the bodies of `if` statements (#1253)
 - Small internal fixes (#1271)
 - Avoid inlining a class twice and creating two equivalent but `!==` classes.

## v5.15.0
 - Basic support for ES2022 class static initializer blocks.
 - Add `AudioWorkletNode` constructor options to domprops list (#1230)
 - Make identity function inliner not inline `id(...expandedArgs)`

## v5.14.2

 - Security fix for RegExps that should not be evaluated (regexp DDOS)
 - Source maps improvements (#1211)
 - Performance improvements in long property access evaluation (#1213)

## v5.14.1
 - keep_numbers option added to TypeScript defs (#1208)
 - Fixed parsing of nested template strings (#1204)

## v5.14.0
 - Switched to @jridgewell/source-map for sourcemap generation (#1190, #1181)
 - Fixed source maps with non-terminated segments (#1106)
 - Enabled typescript types to be imported from the package (#1194)
 - Extra DOM props have been added (#1191)
 - Delete the AST while generating code, as a means to save RAM

## v5.13.1
 - Removed self-assignments (`varname=varname`) (closes #1081)
 - Separated inlining code (for inlining things into references, or removing IIFEs)
 - Allow multiple identifiers with the same name in `var` destructuring (eg `var { a, a } = x`) (#1176)

## v5.13.0

 - All calls to eval() were removed (#1171, #1184)
 - `source-map` was updated to 0.8.0-beta.0 (#1164)
 - NavigatorUAData was added to domprops to avoid property mangling (#1166)

## v5.12.1

 - Fixed an issue with function definitions inside blocks (#1155)
 - Fixed parens of `new` in some situations (closes #1159)

## v5.12.0

 - `TERSER_DEBUG_DIR` environment variable
 - @copyright comments are now preserved with the comments="some" option (#1153)

## v5.11.0

 - Unicode code point escapes (`\u{abcde}`) are not emitted inside RegExp literals anymore (#1147)
 - acorn is now a regular dependency

## v5.10.0

 - Massive optimization to max_line_len (#1109)
 - Basic support for import assertions
 - Marked ES2022 Object.hasOwn as a pure function
 - Fix `delete optional?.property`
 - New CI/CD pipeline with github actions (#1057)
 - Fix reordering of switch branches (#1092), (#1084)
 - Fix error when creating a class property called `get`
 - Acorn dependency is now an optional peerDependency
 - Fix mangling collision with exported variables (#1072)
 - Fix an issue with `return someVariable = (async () => { ... })()` (#1073)

## v5.9.0

 - Collapsing switch cases with the same bodies (even if they're not next to each other) (#1070).
 - Fix evaluation of optional chain expressions (#1062)
 - Fix mangling collision in ESM exports (#1063)
 - Fix issue with mutating function objects after a second pass (#1047)
 - Fix for inlining object spread `{ ...obj }` (#1071)
 - Typescript typings fix (#1069)

## v5.8.0

 - Fixed shadowing variables while moving code in some cases (#1065)
 - Stop mangling computed & quoted properties when keep_quoted is enabled.
 - Fix for mangling private getter/setter and .#private access (#1060, #1068)
 - Array.from has a new optimization when the unsafe option is set (#737)
 - Mangle/propmangle let you generate your own identifiers through the nth_identifier option (#1061)
 - More optimizations to switch statements (#1044)

## v5.7.2

 - Fixed issues with compressing functions defined in `global_defs` option (#1036)
 - New recipe for using Terser in gulp was added to RECIPES.md (#1035)
 - Fixed issues with `??` and `?.` (#1045)
 - Future reserved words such as `package` no longer require you to disable strict mode to be used as names.
 - Refactored huge compressor file into multiple more focused files.
 - Avoided unparenthesized `in` operator in some for loops (it breaks parsing because of for..in loops)
 - Improved documentation (#1021, #1025)
 - More type definitions (#1021)

## v5.7.1

 - Avoided collapsing assignments together if it would place a chain assignment on the left hand side, which is invalid syntax (`a?.b = c`)
 - Removed undefined from object expansions (`{ ...void 0 }` -> `{}`)
 - Fix crash when checking if something is nullish or undefined (#1009)
 - Fixed comparison of private class properties (#1015)
 - Minor performance improvements (#993)
 - Fixed scope of function defs in strict mode (they are block scoped)

## v5.7.0

 - Several compile-time evaluation and inlining fixes
 - Allow `reduce_funcs` to be disabled again.
 - Add `spidermonkey` options to parse and format (#974)
 - Accept `{get = "default val"}` and `{set = "default val"}` in destructuring arguments.
 - Change package.json export map to help require.resolve (#971)
 - Improve docs
 - Fix `export default` of an anonymous class with `extends`

## v5.6.1

 - Mark assignments to the `.prototype` of a class as pure
 - Parenthesize `await` on the left of `**` (while accepting legacy non-parenthesised input)
 - Avoided outputting NUL bytes in optimized RegExps, to stop the output from breaking other tools
 - Added `exports` to domprops (#939)
 - Fixed a crash when spreading `...this`
 - Fixed the computed size of arrow functions, which improves their inlining

## v5.6.0

 - Added top-level await
 - Beautify option has been removed in #895
 - Private properties, getters and setters have been added in #913 and some more commits
 - Docs improvements: #896, #903, #916

## v5.5.1

 - Fixed object properties with unicode surrogates on safari.

## v5.5.0

 - Fixed crash when inlining uninitialized variable into template string.
 - The sourcemap for dist was removed for being too large.

## v5.4.0

 - Logical assignment
 - Change `let x = undefined` to just `let x`
 - Removed some optimizations for template strings, placing them behind `unsafe` options. Reason: adding strings is not equivalent to template strings, due to valueOf differences.
 - The AST_Token class was slimmed down in order to use less memory.

## v5.3.8

 - Restore node 13 support

## v5.3.7

Hotfix release, fixes package.json "engines" syntax

## v5.3.6

 - Fixed parentheses when outputting `??` mixed with `||` and `&&`
 - Improved hygiene of the symbol generator

## v5.3.5

 - Avoid moving named functions into default exports.
 - Enabled transform() for chain expressions. This allows AST transformers to reach inside chain expressions.

## v5.3.4

 - Fixed a crash when hoisting (with `hoist_vars`) a destructuring variable declaration

## v5.3.3

 - `source-map` library has been updated, bringing memory usage and CPU time improvements when reading input source maps (the SourceMapConsumer is now WASM based).
 - The `wrap_func_args` option now also wraps arrow functions, as opposed to only function expressions.

## v5.3.2

 - Prevented spread operations from being expanded when the expanded array/object contains getters, setters, or array holes.
 - Fixed _very_ slow self-recursion in some cases of removing extraneous parentheses from `+` operations.

## v5.3.1

 - An issue with destructuring declarations when `pure_getters` is enabled has been fixed
 - Fixed a crash when chain expressions need to be shallowly compared
 - Made inlining functions more conservative to make sure a function that contains a reference to itself isn't moved into a place that can create multiple instances of itself.

## v5.3.0

 - Fixed a crash when compressing object spreads in some cases
 - Fixed compiletime evaluation of optional chains (caused typeof a?.b to always return "object")
 - domprops has been updated to contain every single possible prop

## v5.2.1

 - The parse step now doesn't accept an `ecma` option, so that all ES code is accepted.
 - Optional dotted chains now accept keywords, just like dotted expressions (`foo?.default`)

## v5.2.0

 - Optional chaining syntax is now supported.
 - Consecutive await expressions don't have unnecessary parens
 - Taking the variable name's length (after mangling) into consideration when deciding to inline

## v5.1.0

 - `import.meta` is now supported
 - Typescript typings have been improved

## v5.0.0

 - `in` operator now taken into account during property mangle.
 - Fixed infinite loop in face of a reference loop in some situations.
 - Kept exports and imports around even if there's something which will throw before them.
 - The main exported bundle for commonjs, dist/bundle.min.js is no longer minified.

## v5.0.0-beta.0

 - BREAKING: `minify()` is now async and rejects a promise instead of returning an error.
 - BREAKING: Internal AST is no longer exposed, so that it can be improved without releasing breaking changes.
 - BREAKING: Lowest supported node version is 10
 - BREAKING: There are no more warnings being emitted
 - Module is now distributed as a dual package - You can `import` and `require()` too.
 - Inline improvements were made


-----

## v4.8.1 (backport)

 - Security fix for RegExps that should not be evaluated (regexp DDOS)

## v4.8.0

 - Support for numeric separators (`million = 1_000_000`) was added.
 - Assigning properties to a class is now assumed to be pure.
 - Fixed bug where `yield` wasn't considered a valid property key in generators.

## v4.7.0

 - A bug was fixed where an arrow function would have the wrong size
 - `arguments` object is now considered safe to retrieve properties from (useful for `length`, or `0`) even when `pure_getters` is not set.
 - Fixed erroneous `const` declarations without value (which is invalid) in some corner cases when using `collapse_vars`.

## v4.6.13

 - Fixed issue where ES5 object properties were being turned into ES6 object properties due to more lax unicode rules.
 - Fixed parsing of BigInt with lowercase `e` in them.

## v4.6.12

 - Fixed subtree comparison code, making it see that `[1,[2, 3]]` is different from `[1, 2, [3]]`
 - Printing of unicode identifiers has been improved

## v4.6.11

 - Read unused classes' properties and method keys, to figure out if they use other variables.
 - Prevent inlining into block scopes when there are name collisions
 - Functions are no longer inlined into parameter defaults, because they live in their own special scope.
 - When inlining identity functions, take into account the fact they may be used to drop `this` in function calls.
 - Nullish coalescing operator (`x ?? y`), plus basic optimization for it.
 - Template literals in binary expressions such as `+` have been further optimized

## v4.6.10

 - Do not use reduce_vars when classes are present

## v4.6.9

 - Check if block scopes actually exist in blocks

## v4.6.8

 - Take into account "executed bits" of classes like static properties or computed keys, when checking if a class evaluation might throw or have side effects.

## v4.6.7

 - Some new performance gains through a `AST_Node.size()` method which measures a node's source code length without printing it to a string first.
 - An issue with setting `--comments` to `false` in the CLI has been fixed.
 - Fixed some issues with inlining
 - `unsafe_symbols` compress option was added, which turns `Symbol("name")` into just `Symbol()`
 - Brought back compress performance improvement through the `AST_Node.equivalent_to(other)` method (which was reverted in v4.6.6).

## v4.6.6

(hotfix release)

 - Reverted code to 4.6.4 to allow for more time to investigate an issue.

## v4.6.5 (REVERTED)

 - Improved compress performance through using a new method to see if two nodes are equivalent, instead of printing them to a string.

## v4.6.4

 - The `"some"` value in the `comments` output option now preserves `@lic` and other important comments when using `//`
 - `</script>` is now better escaped in regex, and in comments, when using the `inline_script` output option
 - Fixed an issue when transforming `new RegExp` into `/.../` when slashes are included in the source
 - `AST_Node.prototype.constructor` now exists, allowing for easier debugging of crashes
 - Multiple if statements with the same consequents are now collapsed
 - Typescript typings improvements
 - Optimizations while looking for surrogate pairs in strings

## v4.6.3

 - Annotations such as `/*#__NOINLINE__*/` and `/*#__PURE__*/` may now be preserved using the `preserve_annotations` output option
 - A TypeScript definition update for the `keep_quoted` output option.

## v4.6.2

 - A bug where functions were inlined into other functions with scope conflicts has been fixed.
 - `/*#__NOINLINE__*/` annotation fixed for more use cases where inlining happens.

## v4.6.1

 - Fixed an issue where a class is duplicated by reduce_vars when there's a recursive reference to the class.

## v4.6.0

 - Fixed issues with recursive class references.
 - BigInt evaluation has been prevented, stopping Terser from evaluating BigInts like it would do regular numbers.
 - Class property support has been added

## v4.5.1

(hotfix release)

 - Fixed issue where `() => ({})[something]` was not parenthesised correctly.

## v4.5.0

 - Inlining has been improved
 - An issue where keep_fnames combined with functions declared through variables was causing name shadowing has been fixed
 - You can now set the ES version through their year
 - The output option `keep_numbers` has been added, which prevents Terser from turning `1000` into `1e3` and such
 - Internal small optimisations and refactors

## v4.4.3

 - Number and BigInt parsing has been fixed
 - `/*#__INLINE__*/` annotation fixed for arrow functions with non-block bodies.
 - Functional tests have been added, using [this repository](https://github.com/terser/terser-functional-tests).
 - A memory leak, where the entire AST lives on after compression, has been plugged.

## v4.4.2

 - Fixed a problem with inlining identity functions

## v4.4.1

*note:* This introduced a feature, therefore it should have been a minor release.

 - Fixed a crash when `unsafe` was enabled.
 - An issue has been fixed where `let` statements might be collapsed out of their scope.
 - Some error messages have been improved by adding quotes around variable names.

## v4.4.0

 - Added `/*#__INLINE__*/` and `/*#__NOINLINE__*/` annotations for calls. If a call has one of these, it either forces or forbids inlining.

## v4.3.11

 - Fixed a problem where `window` was considered safe to access, even though there are situations where it isn't (Node.js, workers...)
 - Fixed an error where `++` and `--` were considered side-effect free
 - `Number(x)` now needs both `unsafe` and and `unsafe_math` to be compressed into `+x` because `x` might be a `BigInt`
 - `keep_fnames` now correctly supports regexes when the function is in a variable declaration

## v4.3.10

 - Fixed syntax error when repeated semicolons were encountered in classes
 - Fixed invalid output caused by the creation of empty sequences internally
 - Scopes are now updated when scopes are inlined into them

## v4.3.9
 - Fixed issue with mangle's `keep_fnames` option, introduced when adding code to keep variable names of anonymous functions

## v4.3.8

 - Typescript typings fix

## v4.3.7

 - Parsing of regex options in the CLI (which broke in v4.3.5) was fixed.
 - typescript definition updates

## v4.3.6

(crash hotfix)

## v4.3.5

 - Fixed an issue with DOS line endings strings separated by `\` and a new line.
 - Improved fix for the output size regression related to unused references within the extends section of a class.
 - Variable names of anonymous functions (eg: `const x = () => { ... }` or `var func = function () {...}`) are now preserved when keep_fnames is true.
 - Fixed performance degradation introduced for large payloads in v4.2.0

## v4.3.4

 - Fixed a regression where the output size was increased when unused classes were referred to in the extends clause of a class.
 - Small typescript typings fixes.
 - Comments with `@preserve`, `@license`, `@cc_on` as well as comments starting with `/*!` and `/**!` are now preserved by default.

## v4.3.3

 - Fixed a problem where parsing template strings would mix up octal notation and a slash followed by a zero representing a null character.
 - Started accepting the name `async` in destructuring arguments with default value.
 - Now Terser takes into account side effects inside class `extends` clauses.
 - Added parens whenever there's a comment between a return statement and the returned value, to prevent issues with ASI.
 - Stopped using raw RegExp objects, since the spec is going to continue to evolve. This ensures Terser is able to process new, unknown RegExp flags and features. This is a breaking change in the AST node AST_RegExp.

## v4.3.2

 - Typescript typing fix
 - Ensure that functions can't be inlined, by reduce_vars, into places where they're accessing variables with the same name, but from somewhere else.

## v4.3.1

 - Fixed an issue from 4.3.0 where any block scope within a for loop erroneously had its parent set to the function scopee
 - Fixed an issue where compressing IIFEs with argument expansions would result in some parameters becoming undefined
 - addEventListener options argument's properties are now part of the DOM properties list.

## v4.3.0

 - Do not drop computed object keys with side effects
 - Functions passed to other functions in calls are now wrapped in parentheses by default, which speeds up loading most modules
 - Objects with computed properties are now less likely to be hoisted
 - Speed and memory efficiency optimizations
 - Fixed scoping issues with `try` and `switch`

## v4.2.1

 - Minor refactors
 - Fixed a bug similar to #369 in collapse_vars
 - Functions can no longer be inlined into a place where they're going to be compared with themselves.
 - reduce_funcs option is now legacy, as using reduce_vars without reduce_funcs caused some weird corner cases. As a result, it is now implied in reduce_vars and can't be turned off without turning off reduce_vars.
 - Bug which would cause a random stack overflow has now been fixed.

## v4.2.0

 - When the source map URL is `inline`, don't write it to a file.
 - Fixed output parens when a lambda literal is the tag on a tagged template string.
 - The `mangle.properties.undeclared` option was added. This enables the property mangler to mangle properties of variables which can be found in the name cache, but whose properties are not known to this Terser run.
 - The v8 bug where the toString and source representations of regexes like `RegExp("\\\n")` includes an actual newline is now fixed.
 - Now we're guaranteed to not have duplicate comments in the output
 - Domprops updates

## v4.1.4

 - Fixed a crash when inlining a function into somewhere else when it has interdependent, non-removable variables.

## v4.1.3

 - Several issues with the `reduce_vars` option were fixed.
 - Starting this version, we only have a dist/bundle.min.js

## v4.1.2

 - The hotfix was hotfixed

## v4.1.1

 - Fixed a bug where toplevel scopes were being mixed up with lambda scopes

## v4.1.0

 - Internal functions were replaced by `Object.assign`, `Array.prototype.some`, `Array.prototype.find` and `Array.prototype.every`.
 - A serious issue where some ESM-native code was broken was fixed.
 - Performance improvements were made.
 - Support for BigInt was added.
 - Inline efficiency was improved. Functions are now being inlined more proactively instead of being inlined only after another Compressor pass.

## v4.0.2

(Hotfix release. Reverts unmapped segments PR [#342](https://github.com/terser/terser/pull/342), which will be put back on Terser when the upstream issue is resolved)

## v4.0.1

 - Collisions between the arguments of inlined functions and names in the outer scope are now being avoided while inlining
 - Unmapped segments are now preserved when compressing a file which has source maps
 - Default values of functions are now correctly converted from Mozilla AST to Terser AST
 - JSON ⊂ ECMAScript spec (if you don't know what this is you don't need to)
 - Export AST_* classes to library users
 - Fixed issue with `collapse_vars` when functions are created with the same name as a variable which already exists
 - Added `MutationObserverInit` (Object with options for initialising a mutation observer) properties to the DOM property list
 - Custom `Error` subclasses are now internally used instead of old-school Error inheritance hacks.
 - Documentation fixes
 - Performance optimizations

## v4.0.0

 - **breaking change**: The `variables` property of all scopes has become a standard JavaScript `Map` as opposed to the old bespoke `Dictionary` object.
 - Typescript definitions were fixed
 - `terser --help` was fixed
 - The public interface was cleaned up
 - Fixed optimisation of `Array` and `new Array`
 - Added the `keep_quoted=strict` mode to mangle_props, which behaves more like Google Closure Compiler by mangling all unquoted property names, instead of reserving quoted property names automatically.
 - Fixed parent functions' parameters being shadowed in some cases
 - Allowed Terser to run in a situation where there are custom functions attached to Object.prototype
 - And more bug fixes, optimisations and internal changes

## v3.17.0

 - More DOM properties added to --mangle-properties's DOM property list
 - Closed issue where if 2 functions had the same argument name, Terser would not inline them together properly
 - Fixed issue with `hasOwnProperty.call`
 - You can now list files to minify in a Terser config file
 - Started replacing `new Array(<number>)` with an array literal
 - Started using ES6 capabilities like `Set` and the `includes` method for strings and arrays

## v3.16.1

 - Fixed issue where Terser being imported with `import` would cause it not to work due to the `__esModule` property. (PR #254 was submitted, which was nice, but since it wasn't a pure commonJS approach I decided to go with my own solution)

## v3.16.0

 - No longer leaves names like Array or Object or window as a SimpleStatement (statement which is just a single expression).
 - Add support for sections sourcemaps (IndexedSourceMapConsumer)
 - Drops node.js v4 and starts using commonJS
 - Is now built with rollup

## v3.15.0

 - Inlined spread syntax (`[...[1, 2, 3], 4, 5] => [1, 2, 3, 4, 5]`) in arrays and objects.
 - Fixed typo in compressor warning
 - Fixed inline source map input bug
 - Fixed parsing of template literals with unnecessary escapes (Like `\\a`)


---

# Our patrons

These are the first-tier patrons from Patreon (notice: **The Terser Patreon is shutting down in favor of opencollective**). My appreciation goes to everyone on this list for supporting the project!

 * 38elements
 * Alan Orozco
 * Aria Buckles
 * CKEditor
 * Mariusz Nowak
 * Nakshatra Mukhopadhyay
 * Philippe Léger
 * Piotrek Koszuliński
 * Serhiy Shyyko
 * Viktor Hubert
 * 龙腾道


---

<h1><img src="https://terser.org/img/terser-banner-logo.png" alt="Terser" width="400"></h1>

  [![NPM Version][npm-image]][npm-url]
  [![NPM Downloads][downloads-image]][downloads-url]
  [![CI pipeline][ci-image]][ci-url]
  [![Opencollective financial contributors][opencollective-contributors]][opencollective-url]

A JavaScript mangler/compressor toolkit for ES6+.

*note*: <s>You can support this project on patreon: [link]</s> **The Terser Patreon is shutting down in favor of opencollective**. Check out [PATRONS.md](https://github.com/terser/terser/blob/master/PATRONS.md) for our first-tier patrons.

Terser recommends you use RollupJS to bundle your modules, as that produces smaller code overall.

*Beautification* has been undocumented and is *being removed* from terser, we recommend you use [prettier](https://npmjs.com/package/prettier).

Find the changelog in [CHANGELOG.md](https://github.com/terser/terser/blob/master/CHANGELOG.md)



[npm-image]: https://img.shields.io/npm/v/terser.svg
[npm-url]: https://npmjs.org/package/terser
[downloads-image]: https://img.shields.io/npm/dm/terser.svg
[downloads-url]: https://npmjs.org/package/terser
[ci-image]: https://github.com/terser/terser/actions/workflows/ci.yml/badge.svg
[ci-url]: https://github.com/terser/terser/actions/workflows/ci.yml
[opencollective-contributors]: https://opencollective.com/terser/tiers/badge.svg
[opencollective-url]: https://opencollective.com/terser

Why choose terser?
------------------

`uglify-es` is [no longer maintained](https://github.com/mishoo/UglifyJS2/issues/3156#issuecomment-392943058) and `uglify-js` does not support ES6+.

**`terser`** is a fork of `uglify-es` that mostly retains API and CLI compatibility
with `uglify-es` and `uglify-js@3`.

Install
-------

First make sure you have installed the latest version of [node.js](http://nodejs.org/)
(You may need to restart your computer after this step).

From NPM for use as a command line app:

    npm install terser -g

From NPM for programmatic use:

    npm install terser

# Command line usage

<!-- CLI_USAGE:START -->

```
terser [input files] [options]
```

Terser can take multiple input files.  It's recommended that you pass the
input files first, then pass the options.  Terser will parse input files
in sequence and apply any compression options.  The files are parsed in the
same global scope, that is, a reference from a file to some
variable/function declared in another file will be matched properly.

Command line arguments that take options (like --parse, --compress, --mangle and
--format) can take in a comma-separated list of default option overrides. For
instance:

    terser input.js --compress ecma=2015,computed_props=false

If no input file is specified, Terser will read from STDIN.

If you wish to pass your options before the input files, separate the two with
a double dash to prevent input files being used as option arguments:

    terser --compress --mangle -- input.js

### Command line options

```
    -h, --help                  Print usage information.
                                `--help options` for details on available options.
    -V, --version               Print version number.
    -p, --parse <options>       Specify parser options:
                                `acorn`  Use Acorn for parsing.
                                `bare_returns`  Allow return outside of functions.
                                                Useful when minifying CommonJS
                                                modules and Userscripts that may
                                                be anonymous function wrapped (IIFE)
                                                by the .user.js engine `caller`.
                                `expression`  Parse a single expression, rather than
                                              a program (for parsing JSON).
                                `spidermonkey`  Assume input files are SpiderMonkey
                                                AST format (as JSON).
    -c, --compress [options]    Enable compressor/specify compressor options:
                                `pure_funcs`  List of functions that can be safely
                                              removed when their return values are
                                              not used.
    -m, --mangle [options]      Mangle names/specify mangler options:
                                `reserved`  List of names that should not be mangled.
    --mangle-props [options]    Mangle properties/specify mangler options:
                                `builtins`  Mangle property names that overlaps
                                            with standard JavaScript globals and DOM
                                            API props.
                                `debug`  Add debug prefix and suffix.
                                `keep_quoted`  Only mangle unquoted properties, quoted
                                               properties are automatically reserved.
                                               `strict` disables quoted properties
                                               being automatically reserved.
                                `regex`  Only mangle matched property names.
                                `only_annotated` Only mangle properties defined with /*@__MANGLE_PROP__*/.
                                `reserved`  List of names that should not be mangled.
    -f, --format [options]      Specify format options.
                                `preamble`  Preamble to prepend to the output. You
                                            can use this to insert a comment, for
                                            example for licensing information.
                                            This will not be parsed, but the source
                                            map will adjust for its presence.
                                `quote_style`  Quote style:
                                               0 - auto
                                               1 - single
                                               2 - double
                                               3 - original
                                `wrap_iife`  Wrap IIFEs in parenthesis. Note: you may
                                             want to disable `negate_iife` under
                                             compressor options.
                                `wrap_func_args`  Wrap function arguments in parenthesis.
    -o, --output <file>         Output file path (default STDOUT). Specify `ast` or
                                `spidermonkey` to write Terser or SpiderMonkey AST
                                as JSON to STDOUT respectively.
    --comments [filter]         Preserve copyright comments in the output. By
                                default this works like Google Closure, keeping
                                JSDoc-style comments that contain e.g. "@license",
                                or start with "!". You can optionally pass one of the
                                following arguments to this flag:
                                - "all" to keep all comments
                                - `false` to omit comments in the output
                                - a valid JS RegExp like `/foo/` or `/^!/` to
                                keep only matching comments.
                                Note that currently not *all* comments can be
                                kept when compression is on, because of dead
                                code removal or cascading statements into
                                sequences.
    --config-file <file>        Read `minify()` options from JSON file.
    -d, --define <expr>[=value] Global definitions.
    --ecma <version>            Specify ECMAScript release: 5, 2015, 2016, etc.
    -e, --enclose [arg[:value]] Embed output in a big function with configurable
                                arguments and values.
    --ie8                       Support non-standard Internet Explorer 8.
                                Equivalent to setting `ie8: true` in `minify()`
                                for `compress`, `mangle` and `format` options.
                                By default Terser will not try to be IE-proof.
    --keep-classnames           Do not mangle/drop class names.
    --keep-fnames               Do not mangle/drop function names.  Useful for
                                code relying on Function.prototype.name.
    --module                    Input is an ES6 module. If `compress` or `mangle` is
                                enabled then the `toplevel` option, as well as strict mode,
                                will be enabled.
    --name-cache <file>         File to hold mangled name mappings.
    --safari10                  Support non-standard Safari 10/11.
                                Equivalent to setting `safari10: true` in `minify()`
                                for `mangle` and `format` options.
                                By default `terser` will not work around
                                Safari 10/11 bugs.
    --source-map [options]      Enable source map/specify source map options:
                                `base`  Path to compute relative paths from input files.
                                `content`  Input source map, useful if you're compressing
                                           JS that was generated from some other original
                                           code. Specify "inline" if the source map is
                                           included within the sources.
                                `filename`  Name and/or location of the output source.
                                `includeSources`  Pass this flag if you want to include
                                                  the content of source files in the
                                                  source map as sourcesContent property.
                                `root`  Path to the original source to be included in
                                        the source map.
                                `url`  If specified, path to the source map to append in
                                       `//# sourceMappingURL`.
    --timings                   Display operations run time on STDERR.
    --toplevel                  Compress and/or mangle variables in top level scope.
    --wrap <name>               Embed everything in a big function, making the
                                “exports” and “global” variables available. You
                                need to pass an argument to this option to
                                specify the name that your module will take
                                when included in, say, a browser.
```

Specify `--output` (`-o`) to declare the output file.  Otherwise the output
goes to STDOUT.

## CLI source map options

Terser can generate a source map file, which is highly useful for
debugging your compressed JavaScript.  To get a source map, pass
`--source-map --output output.js` (source map will be written out to
`output.js.map`).

Additional options:

- `--source-map "filename='<NAME>'"` to specify the name of the source map.

- `--source-map "root='<URL>'"` to pass the URL where the original files can be found.

- `--source-map "url='<URL>'"` to specify the URL where the source map can be found.
  Otherwise Terser assumes HTTP `X-SourceMap` is being used and will omit the
  `//# sourceMappingURL=` directive.

For example:

    terser js/file1.js js/file2.js \
             -o foo.min.js -c -m \
             --source-map "root='http://foo.com/src',url='foo.min.js.map'"

The above will compress and mangle `file1.js` and `file2.js`, will drop the
output in `foo.min.js` and the source map in `foo.min.js.map`.  The source
mapping will refer to `http://foo.com/src/js/file1.js` and
`http://foo.com/src/js/file2.js` (in fact it will list `http://foo.com/src`
as the source map root, and the original files as `js/file1.js` and
`js/file2.js`).

### Composed source map

When you're compressing JS code that was output by a compiler such as
CoffeeScript, mapping to the JS code won't be too helpful.  Instead, you'd
like to map back to the original code (i.e. CoffeeScript).  Terser has an
option to take an input source map.  Assuming you have a mapping from
CoffeeScript → compiled JS, Terser can generate a map from CoffeeScript →
compressed JS by mapping every token in the compiled JS to its original
location.

To use this feature pass `--source-map "content='/path/to/input/source.map'"`
or `--source-map "content=inline"` if the source map is included inline with
the sources.

## CLI compress options

You need to pass `--compress` (`-c`) to enable the compressor.  Optionally
you can pass a comma-separated list of [compress options](#compress-options).

Options are in the form `foo=bar`, or just `foo` (the latter implies
a boolean option that you want to set `true`; it's effectively a
shortcut for `foo=true`).

Example:

    terser file.js -c toplevel,sequences=false

## CLI mangle options

To enable the mangler you need to pass `--mangle` (`-m`).  The following
(comma-separated) options are supported:

- `toplevel` (default `false`) -- mangle names declared in the top level scope.

- `eval` (default `false`) -- mangle names visible in scopes where `eval` or `with` are used.

When mangling is enabled but you want to prevent certain names from being
mangled, you can declare those names with `--mangle reserved` — pass a
comma-separated list of names.  For example:

    terser ... -m reserved=['$','require','exports']

to prevent the `require`, `exports` and `$` names from being changed.

### CLI mangling property names (`--mangle-props`)

**Note:** THIS **WILL** BREAK YOUR CODE. A good rule of thumb is not to use this unless you know exactly what you're doing and how this works and read this section until the end.

Mangling property names is a separate step, different from variable name mangling.  Pass
`--mangle-props` to enable it. The least dangerous
way to use this is to use the `regex` option like so:

```
terser example.js -c -m --mangle-props regex=/_$/
```

This will mangle all properties that end with an
underscore. So you can use it to mangle internal methods.

By default, it will mangle all properties in the
input code with the exception of built in DOM properties and properties
in core JavaScript classes, which is what will break your code if you don't:

1. Control all the code you're mangling
2. Avoid using a module bundler, as they usually will call Terser on each file individually, making it impossible to pass mangled objects between modules.
3. Avoid calling functions like `defineProperty` or `hasOwnProperty`, because they refer to object properties using strings and will break your code if you don't know what you are doing.

An example:

```javascript
// example.js
var x = {
    baz_: 0,
    foo_: 1,
    calc: function() {
        return this.foo_ + this.baz_;
    }
};
x.bar_ = 2;
x["baz_"] = 3;
console.log(x.calc());
```
Mangle all properties (except for JavaScript `builtins`) (**very** unsafe):
```bash
$ terser example.js -c passes=2 -m --mangle-props
```
```javascript
var x={o:3,t:1,i:function(){return this.t+this.o},s:2};console.log(x.i());
```
Mangle all properties except for `reserved` properties (still very unsafe):
```bash
$ terser example.js -c passes=2 -m --mangle-props reserved=[foo_,bar_]
```
```javascript
var x={o:3,foo_:1,t:function(){return this.foo_+this.o},bar_:2};console.log(x.t());
```
Mangle all properties matching a `regex` (not as unsafe but still unsafe):
```bash
$ terser example.js -c passes=2 -m --mangle-props regex=/_$/
```
```javascript
var x={o:3,t:1,calc:function(){return this.t+this.o},i:2};console.log(x.calc());
```

Combining mangle properties options:
```bash
$ terser example.js -c passes=2 -m --mangle-props regex=/_$/,reserved=[bar_]
```
```javascript
var x={o:3,t:1,calc:function(){return this.t+this.o},bar_:2};console.log(x.calc());
```

In order for this to be of any use, we avoid mangling standard JS names and DOM
API properties by default (`--mangle-props builtins` to override).

A regular expression can be used to define which property names should be
mangled.  For example, `--mangle-props regex=/^_/` will only mangle property
names that start with an underscore.

When you compress multiple files using this option, in order for them to
work together in the end we need to ensure somehow that one property gets
mangled to the same name in all of them.  For this, pass `--name-cache filename.json`
and Terser will maintain these mappings in a file which can then be reused.
It should be initially empty.  Example:

```bash
$ rm -f /tmp/cache.json  # start fresh
$ terser file1.js file2.js --mangle-props --name-cache /tmp/cache.json -o part1.js
$ terser file3.js file4.js --mangle-props --name-cache /tmp/cache.json -o part2.js
```

Now, `part1.js` and `part2.js` will be consistent with each other in terms
of mangled property names.

Using the name cache is not necessary if you compress all your files in a
single call to Terser.

### Mangling unquoted names (`--mangle-props keep_quoted`)

Using quoted property name (`o["foo"]`) reserves the property name (`foo`)
so that it is not mangled throughout the entire script even when used in an
unquoted style (`o.foo`). Example:

```javascript
// stuff.js
var o = {
    "foo": 1,
    bar: 3
};
o.foo += o.bar;
console.log(o.foo);
```
```bash
$ terser stuff.js --mangle-props keep_quoted -c -m
```
```javascript
var o={foo:1,o:3};o.foo+=o.o,console.log(o.foo);
```

### Debugging property name mangling

You can also pass `--mangle-props debug` in order to mangle property names
without completely obscuring them. For example the property `o.foo`
would mangle to `o._$foo$_` with this option. This allows property mangling
of a large codebase while still being able to debug the code and identify
where mangling is breaking things.

```bash
$ terser stuff.js --mangle-props debug -c -m
```
```javascript
var o={_$foo$_:1,_$bar$_:3};o._$foo$_+=o._$bar$_,console.log(o._$foo$_);
```

You can also pass a custom suffix using `--mangle-props debug=XYZ`. This would then
mangle `o.foo` to `o._$foo$XYZ_`. You can change this each time you compile a
script to identify how a property got mangled. One technique is to pass a
random number on every compile to simulate mangling changing with different
inputs (e.g. as you update the input script with new properties), and to help
identify mistakes like writing mangled keys to storage.

<!-- CLI_USAGE:END -->

# API Reference

<!-- API_REFERENCE:START -->

Assuming installation via NPM, you can load Terser in your application
like this:

```javascript
const { minify } = require("terser");
```

Or,

```javascript
import { minify } from "terser";
```

Browser loading is also supported. It exposes a global variable `Terser` containing a `.minify` property:
```html
<script src="https://cdn.jsdelivr.net/npm/source-map@0.7.3/dist/source-map.js"></script>
<script src="https://cdn.jsdelivr.net/npm/terser/dist/bundle.min.js"></script>
```

There is an async high level function, **`async minify(code, options)`**,
which will perform all minification [phases](#minify-options) in a configurable
manner. By default `minify()` will enable [`compress`](#compress-options)
and [`mangle`](#mangle-options). Example:
```javascript
var code = "function add(first, second) { return first + second; }";
var result = await minify(code, { sourceMap: true });
console.log(result.code);  // minified output: function add(n,d){return n+d}
console.log(result.map);  // source map
```

There is also a `minify_sync()` alternative version of it, which returns instantly.

You can `minify` more than one JavaScript file at a time by using an object
for the first argument where the keys are file names and the values are source
code:
```javascript
var code = {
    "file1.js": "function add(first, second) { return first + second; }",
    "file2.js": "console.log(add(1 + 2, 3 + 4));"
};
var result = await minify(code);
console.log(result.code);
// function add(d,n){return d+n}console.log(add(3,7));
```

The `toplevel` option:
```javascript
var code = {
    "file1.js": "function add(first, second) { return first + second; }",
    "file2.js": "console.log(add(1 + 2, 3 + 4));"
};
var options = { toplevel: true };
var result = await minify(code, options);
console.log(result.code);
// console.log(3+7);
```

The `nameCache` option:
```javascript
var options = {
    mangle: {
        toplevel: true,
    },
    nameCache: {}
};
var result1 = await minify({
    "file1.js": "function add(first, second) { return first + second; }"
}, options);
var result2 = await minify({
    "file2.js": "console.log(add(1 + 2, 3 + 4));"
}, options);
console.log(result1.code);
// function n(n,r){return n+r}
console.log(result2.code);
// console.log(n(3,7));
```

You may persist the name cache to the file system in the following way:
```javascript
var cacheFileName = "/tmp/cache.json";
var options = {
    mangle: {
        properties: true,
    },
    nameCache: JSON.parse(fs.readFileSync(cacheFileName, "utf8"))
};
fs.writeFileSync("part1.js", await minify({
    "file1.js": fs.readFileSync("file1.js", "utf8"),
    "file2.js": fs.readFileSync("file2.js", "utf8")
}, options).code, "utf8");
fs.writeFileSync("part2.js", await minify({
    "file3.js": fs.readFileSync("file3.js", "utf8"),
    "file4.js": fs.readFileSync("file4.js", "utf8")
}, options).code, "utf8");
fs.writeFileSync(cacheFileName, JSON.stringify(options.nameCache), "utf8");
```

An example of a combination of `minify()` options:
```javascript
var code = {
    "file1.js": "function add(first, second) { return first + second; }",
    "file2.js": "console.log(add(1 + 2, 3 + 4));"
};
var options = {
    toplevel: true,
    compress: {
        global_defs: {
            "@console.log": "alert"
        },
        passes: 2
    },
    format: {
        preamble: "/* minified */"
    }
};
var result = await minify(code, options);
console.log(result.code);
// /* minified */
// alert(10);"
```

An error example:
```javascript
try {
    const result = await minify({"foo.js" : "if (0) else console.log(1);"});
    // Do something with result
} catch (error) {
    const { message, filename, line, col, pos } = error;
    // Do something with error
}
```

## Minify options

- `ecma` (default `undefined`) - pass `5`, `2015`, `2016`, etc to override
  `compress` and `format`'s `ecma` options.

- `enclose` (default `false`) - pass `true`, or a string in the format
  of `"args[:values]"`, where `args` and `values` are comma-separated
  argument names and values, respectively, to embed the output in a big
  function with the configurable arguments and values.

- `parse` (default `{}`) — pass an object if you wish to specify some
  additional [parse options](#parse-options).

- `compress` (default `{}`) — pass `false` to skip compressing entirely.
  Pass an object to specify custom [compress options](#compress-options).

- `mangle` (default `true`) — pass `false` to skip mangling names, or pass
  an object to specify [mangle options](#mangle-options) (see below).

  - `mangle.properties` (default `false`) — a subcategory of the mangle option.
    Pass an object to specify custom [mangle property options](#mangle-properties-options).

- `module` (default `false`) — Use when minifying an ES6 module. "use strict"
  is implied and names can be mangled on the top scope. If `compress` or
  `mangle` is enabled then the `toplevel` option will be enabled.

- `format` or `output` (default `null`) — pass an object if you wish to specify
  additional [format options](#format-options).  The defaults are optimized
  for best compression.

- `sourceMap` (default `false`) - pass an object if you wish to specify
  [source map options](#source-map-options).

- `toplevel` (default `false`) - set to `true` if you wish to enable top level
  variable and function name mangling and to drop unused variables and functions.

- `nameCache` (default `null`) - pass an empty object `{}` or a previously
  used `nameCache` object if you wish to cache mangled variable and
  property names across multiple invocations of `minify()`. Note: this is
  a read/write property. `minify()` will read the name cache state of this
  object and update it during minification so that it may be
  reused or externally persisted by the user.

- `ie8` (default `false`) - set to `true` to support IE8.

- `keep_classnames` (default: `undefined`) - pass `true` to prevent discarding or mangling
  of class names. Pass a regular expression to only keep class names matching that regex.

- `keep_fnames` (default: `false`) - pass `true` to prevent discarding or mangling
  of function names. Pass a regular expression to only keep function names matching that regex.
  Useful for code relying on `Function.prototype.name`. If the top level minify option
  `keep_classnames` is `undefined` it will be overridden with the value of the top level
  minify option `keep_fnames`.

- `safari10` (default: `false`) - pass `true` to work around Safari 10/11 bugs in
  loop scoping and `await`. See `safari10` options in [`mangle`](#mangle-options)
  and [`format`](#format-options) for details.

## Minify options structure

```javascript
{
    parse: {
        // parse options
    },
    compress: {
        // compress options
    },
    mangle: {
        // mangle options

        properties: {
            // mangle property options
        }
    },
    format: {
        // format options (can also use `output` for backwards compatibility)
    },
    sourceMap: {
        // source map options
    },
    ecma: 5, // specify one of: 5, 2015, 2016, etc.
    enclose: false, // or specify true, or "args:values"
    keep_classnames: false,
    keep_fnames: false,
    ie8: false,
    module: false,
    nameCache: null, // or specify a name cache object
    safari10: false,
    toplevel: false
}
```

### Source map options

To generate a source map:
```javascript
var result = await minify({"file1.js": "var a = function() {};"}, {
    sourceMap: {
        filename: "out.js",
        url: "out.js.map"
    }
});
console.log(result.code); // minified output
console.log(result.map);  // source map
```

Note that the source map is not saved in a file, it's just returned in
`result.map`.  The value passed for `sourceMap.url` is only used to set
`//# sourceMappingURL=out.js.map` in `result.code`. The value of
`filename` is only used to set `file` attribute (see [the spec](https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k))
in source map file.

You can set option `sourceMap.url` to be `"inline"` and source map will
be appended to code.

You can also specify sourceRoot property to be included in source map:
```javascript
var result = await minify({"file1.js": "var a = function() {};"}, {
    sourceMap: {
        root: "http://example.com/src",
        url: "out.js.map"
    }
});
```

If you're compressing compiled JavaScript and have a source map for it, you
can use `sourceMap.content`:
```javascript
var result = await minify({"compiled.js": "compiled code"}, {
    sourceMap: {
        content: "content from compiled.js.map",
        url: "minified.js.map"
    }
});
// same as before, it returns `code` and `map`
```

If you're using the `X-SourceMap` header instead, you can just omit `sourceMap.url`.

If you happen to need the source map as a raw object, set `sourceMap.asObject` to `true`.

<!-- API_REFERENCE:END -->

<!-- OPTIONS:START -->

## Parse options

- `bare_returns` (default `false`) -- support top level `return` statements

- `html5_comments` (default `true`)

- `shebang` (default `true`) -- support `#!command` as the first line

- `spidermonkey` (default `false`) -- accept a Spidermonkey (Mozilla) AST

## Compress options

- `defaults` (default: `true`) -- Pass `false` to disable most default
  enabled `compress` transforms. Useful when you only want to enable a few
  `compress` options while disabling the rest.

- `arrows` (default: `true`) -- Class and object literal methods are converted
  will also be converted to arrow expressions if the resultant code is shorter:
  `m(){return x}` becomes `m:()=>x`. To do this to regular ES5 functions which
  don't use `this` or `arguments`, see `unsafe_arrows`.

- `arguments` (default: `false`) -- replace `arguments[index]` with function
  parameter name whenever possible.

- `booleans` (default: `true`) -- various optimizations for boolean context,
  for example `!!a ? b : c → a ? b : c`

- `booleans_as_integers` (default: `false`) -- Turn booleans into 0 and 1, also
  makes comparisons with booleans use `==` and `!=` instead of `===` and `!==`.

- `collapse_vars` (default: `true`) -- Collapse single-use non-constant variables,
  side effects permitting.

- `comparisons` (default: `true`) -- apply certain optimizations to binary nodes,
  e.g. `!(a <= b) → a > b` (only when `unsafe_comps`), attempts to negate binary
  nodes, e.g. `a = !b && !c && !d && !e → a=!(b||c||d||e)` etc. Note: `comparisons`
  works best with `lhs_constants` enabled.

- `computed_props` (default: `true`) -- Transforms constant computed properties
  into regular ones: `{["computed"]: 1}` is converted to `{computed: 1}`.

- `conditionals` (default: `true`) -- apply optimizations for `if`-s and conditional
  expressions

- `dead_code` (default: `true`) -- remove unreachable code

- `directives` (default: `true`) -- remove redundant or non-standard directives

- `drop_console` (default: `false`) -- Pass `true` to discard calls to
  `console.*` functions. If you only want to discard a portion of console, 
   you can pass an array like this `['log', 'info']`, which will only discard `console.log`、 `console.info`.

- `drop_debugger` (default: `true`) -- remove `debugger;` statements

- `ecma` (default: `5`) -- Pass `2015` or greater to enable `compress` options that
  will transform ES5 code into smaller ES6+ equivalent forms.

- `evaluate` (default: `true`) -- attempt to evaluate constant expressions

- `expression` (default: `false`) -- Pass `true` to preserve completion values
  from terminal statements without `return`, e.g. in bookmarklets.

- `global_defs` (default: `{}`) -- see [conditional compilation](#conditional-compilation)

- `hoist_funs` (default: `false`) -- hoist function declarations

- `hoist_props` (default: `true`) -- hoist properties from constant object and
  array literals into regular variables subject to a set of constraints. For example:
  `var o={p:1, q:2}; f(o.p, o.q);` is converted to `f(1, 2);`. Note: `hoist_props`
  works best with `mangle` enabled, the `compress` option `passes` set to `2` or higher,
  and the `compress` option `toplevel` enabled.

- `hoist_vars` (default: `false`) -- hoist `var` declarations (this is `false`
  by default because it seems to increase the size of the output in general)

- `if_return` (default: `true`) -- optimizations for if/return and if/continue

- `inline` (default: `true`) -- inline calls to function with simple/`return` statement:
  - `false` -- same as `0`
  - `0` -- disabled inlining
  - `1` -- inline simple functions
  - `2` -- inline functions with arguments
  - `3` -- inline functions with arguments and variables
  - `true` -- same as `3`

- `join_vars` (default: `true`) -- join consecutive `var`, `let` and `const` statements

- `keep_classnames` (default: `false`) -- Pass `true` to prevent the compressor from
  discarding class names. Pass a regular expression to only keep class names matching
  that regex. See also: the `keep_classnames` [mangle option](#mangle-options).

- `keep_fargs` (default: `true`) -- Prevents the compressor from discarding unused
  function arguments.  You need this for code which relies on `Function.length`.

- `keep_fnames` (default: `false`) -- Pass `true` to prevent the
  compressor from discarding function names. Pass a regular expression to only keep
  function names matching that regex. Useful for code relying on `Function.prototype.name`.
  See also: the `keep_fnames` [mangle option](#mangle-options).

- `keep_infinity` (default: `false`) -- Pass `true` to prevent `Infinity` from
  being compressed into `1/0`, which may cause performance issues on Chrome.

- `lhs_constants` (default: `true`) -- Moves constant values to the left-hand side
  of binary nodes. `foo == 42 → 42 == foo`

- `loops` (default: `true`) -- optimizations for `do`, `while` and `for` loops
  when we can statically determine the condition.

- `module` (default `false`) -- Pass `true` when compressing an ES6 module. Strict
  mode is implied and the `toplevel` option as well.

- `negate_iife` (default: `true`) -- negate "Immediately-Called Function Expressions"
  where the return value is discarded, to avoid the parens that the
  code generator would insert.

- `passes` (default: `1`) -- The maximum number of times to run compress.
  In some cases more than one pass leads to further compressed code.  Keep in
  mind more passes will take more time.

- `properties` (default: `true`) -- rewrite property access using the dot notation, for
  example `foo["bar"] → foo.bar`

- `pure_funcs` (default: `null`) -- You can pass an array of names and
  Terser will assume that those functions do not produce side
  effects.  DANGER: will not check if the name is redefined in scope.
  An example case here, for instance `var q = Math.floor(a/b)`.  If
  variable `q` is not used elsewhere, Terser will drop it, but will
  still keep the `Math.floor(a/b)`, not knowing what it does.  You can
  pass `pure_funcs: [ 'Math.floor' ]` to let it know that this
  function won't produce any side effect, in which case the whole
  statement would get discarded.  The current implementation adds some
  overhead (compression will be slower).

- `pure_getters` (default: `"strict"`) -- If you pass `true` for
  this, Terser will assume that object property access
  (e.g. `foo.bar` or `foo["bar"]`) doesn't have any side effects.
  Specify `"strict"` to treat `foo.bar` as side-effect-free only when
  `foo` is certain to not throw, i.e. not `null` or `undefined`.

- `pure_new` (default: `false`) -- Set to `true` to assume `new X()` never has
  side effects.

- `reduce_vars` (default: `true`) -- Improve optimization on variables assigned with and
  used as constant values.

- `reduce_funcs` (default: `true`) -- Inline single-use functions when
  possible. Depends on `reduce_vars` being enabled.  Disabling this option
  sometimes improves performance of the output code.

- `sequences` (default: `true`) -- join consecutive simple statements using the
  comma operator.  May be set to a positive integer to specify the maximum number
  of consecutive comma sequences that will be generated. If this option is set to
  `true` then the default `sequences` limit is `200`. Set option to `false` or `0`
  to disable. The smallest `sequences` length is `2`. A `sequences` value of `1`
  is grandfathered to be equivalent to `true` and as such means `200`. On rare
  occasions the default sequences limit leads to very slow compress times in which
  case a value of `20` or less is recommended.

- `side_effects` (default: `true`) -- Remove expressions which have no side effects
  and whose results aren't used.

- `switches` (default: `true`) -- de-duplicate and remove unreachable `switch` branches

- `toplevel` (default: `false`) -- drop unreferenced functions (`"funcs"`) and/or
  variables (`"vars"`) in the top level scope (`false` by default, `true` to drop
  both unreferenced functions and variables)

- `top_retain` (default: `null`) -- prevent specific toplevel functions and
  variables from `unused` removal (can be array, comma-separated, RegExp or
  function. Implies `toplevel`)

- `typeofs` (default: `true`) -- Transforms `typeof foo == "undefined"` into
  `foo === void 0`.  Note: recommend to set this value to `false` for IE10 and
  earlier versions due to known issues.

- `unsafe` (default: `false`) -- apply "unsafe" transformations
  ([details](#the-unsafe-compress-option)).

- `unsafe_arrows` (default: `false`) -- Convert ES5 style anonymous function
  expressions to arrow functions if the function body does not reference `this`.
  Note: it is not always safe to perform this conversion if code relies on the
  the function having a `prototype`, which arrow functions lack.
  This transform requires that the `ecma` compress option is set to `2015` or greater.

- `unsafe_comps` (default: `false`) -- Reverse `<` and `<=` to `>` and `>=` to
  allow improved compression. This might be unsafe when an at least one of two
  operands is an object with computed values due the use of methods like `get`,
  or `valueOf`. This could cause change in execution order after operands in the
  comparison are switching. Compression only works if both `comparisons` and
  `unsafe_comps` are both set to true.

- `unsafe_Function` (default: `false`) -- compress and mangle `Function(args, code)`
  when both `args` and `code` are string literals.

- `unsafe_math` (default: `false`) -- optimize numerical expressions like
  `2 * x * 3` into `6 * x`, which may give imprecise floating point results.

- `unsafe_symbols` (default: `false`) -- removes keys from native Symbol
  declarations, e.g `Symbol("kDog")` becomes `Symbol()`.

- `unsafe_methods` (default: false) -- Converts `{ m: function(){} }` to
  `{ m(){} }`. `ecma` must be set to `6` or greater to enable this transform.
  If `unsafe_methods` is a RegExp then key/value pairs with keys matching the
  RegExp will be converted to concise methods.
  Note: if enabled there is a risk of getting a "`<method name>` is not a
  constructor" TypeError should any code try to `new` the former function.

- `unsafe_proto` (default: `false`) -- optimize expressions like
  `Array.prototype.slice.call(a)` into `[].slice.call(a)`

- `unsafe_regexp` (default: `false`) -- enable substitutions of variables with
  `RegExp` values the same way as if they are constants.

- `unsafe_undefined` (default: `false`) -- substitute `void 0` if there is a
  variable named `undefined` in scope (variable name will be mangled, typically
  reduced to a single character)

- `unused` (default: `true`) -- drop unreferenced functions and variables (simple
  direct variable assignments do not count as references unless set to `"keep_assign"`)

## Mangle options

- `eval` (default `false`) -- Pass `true` to mangle names visible in scopes
  where `eval` or `with` are used.

- `keep_classnames` (default `false`) -- Pass `true` to not mangle class names.
  Pass a regular expression to only keep class names matching that regex.
  See also: the `keep_classnames` [compress option](#compress-options).

- `keep_fnames` (default `false`) -- Pass `true` to not mangle function names.
  Pass a regular expression to only keep function names matching that regex.
  Useful for code relying on `Function.prototype.name`. See also: the `keep_fnames`
  [compress option](#compress-options).

- `module` (default `false`) -- Pass `true` an ES6 modules, where the toplevel
  scope is not the global scope. Implies `toplevel` and assumes input code is strict mode JS.

- `nth_identifier` (default: an internal mangler that weights based on character
  frequency analysis) -- Pass an object with a `get(n)` function that converts an
  ordinal into the nth most favored (usually shortest) identifier.
  Optionally also provide `reset()`, `sort()`, and `consider(chars, delta)` to
  use character frequency analysis of the source code.

- `reserved` (default `[]`) -- Pass an array of identifiers that should be
  excluded from mangling. Example: `["foo", "bar"]`.

- `toplevel` (default `false`) -- Pass `true` to mangle names declared in the
  top level scope.

- `safari10` (default `false`) -- Pass `true` to work around the Safari 10 loop
  iterator [bug](https://bugs.webkit.org/show_bug.cgi?id=171041)
  "Cannot declare a let variable twice".
  See also: the `safari10` [format option](#format-options).

Examples:

```javascript
// test.js
var globalVar;
function funcName(firstLongName, anotherLongName) {
    var myVariable = firstLongName +  anotherLongName;
}
```
```javascript
var code = fs.readFileSync("test.js", "utf8");

await minify(code).code;
// 'function funcName(a,n){}var globalVar;'

await minify(code, { mangle: { reserved: ['firstLongName'] } }).code;
// 'function funcName(firstLongName,a){}var globalVar;'

await minify(code, { mangle: { toplevel: true } }).code;
// 'function n(n,a){}var a;'
```

### Mangle properties options

- `builtins` (default: `false`) — Use `true` to allow the mangling of builtin
  DOM properties. Not recommended to override this setting.

- `debug` (default: `false`) — Mangle names with the original name still present.
  Pass an empty string `""` to enable, or a non-empty string to set the debug suffix.

- `keep_quoted` (default: `false`) — How quoting properties (`{"prop": ...}` and `obj["prop"]`) controls what gets mangled.
  - `"strict"` (recommended) -- `obj.prop` is mangled.
  - `false` -- `obj["prop"]` is mangled.
  - `true` -- `obj.prop` is mangled unless there is `obj["prop"]` elsewhere in the code.

- `nth_identifier` (default: an internal mangler that weights based on character
  frequency analysis) -- Pass an object with a `get(n)` function that converts an
  ordinal into the nth most favored (usually shortest) identifier.
  Optionally also provide `reset()`, `sort()`, and `consider(chars, delta)` to
  use character frequency analysis of the source code.

- `regex` (default: `null`) — Pass a [RegExp literal or pattern string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp) to only mangle property matching the regular expression.

- `reserved` (default: `[]`) — Do not mangle property names listed in the
  `reserved` array.

- `undeclared` (default: `false`) - Mangle those names when they are accessed
  as properties of known top level variables but their declarations are never
  found in input code. May be useful when only minifying parts of a project.
  See [#397](https://github.com/terser/terser/issues/397) for more details.


## Format options

These options control the format of Terser's output code. Previously known
as "output options".

- `ascii_only` (default `false`) -- escape Unicode characters in strings and
  regexps (affects directives with non-ascii characters becoming invalid)

- `beautify` (default `false`) -- (DEPRECATED) whether to beautify the output.
  When using the legacy `-b` CLI flag, this is set to true by default.

- `braces` (default `false`) -- always insert braces in `if`, `for`,
  `do`, `while` or `with` statements, even if their body is a single
  statement.

- `comments` (default `"some"`) -- by default it keeps JSDoc-style comments
  that contain "@license", "@copyright", "@preserve" or start with `!`, pass `true`
  or `"all"` to preserve all comments, `false` to omit comments in the output,
  a regular expression string (e.g. `/^!/`) or a function.

- `ecma` (default `5`) -- set desired EcmaScript standard version for output.
  Set `ecma` to `2015` or greater to emit shorthand object properties - i.e.:
  `{a}` instead of `{a: a}`.  The `ecma` option will only change the output in
  direct control of the beautifier. Non-compatible features in your input will
  still be output as is. For example: an `ecma` setting of `5` will **not**
  convert modern code to ES5.

- `indent_level` (default `4`)

- `indent_start` (default `0`) -- prefix all lines by that many spaces

- `inline_script` (default `true`) -- escape HTML comments and the slash in
  occurrences of `</script>` in strings

- `keep_numbers` (default `false`) -- keep number literals as it was in original code
 (disables optimizations like converting `1000000` into `1e6`)

- `keep_quoted_props` (default `false`) -- when turned on, prevents stripping
  quotes from property names in object literals.

- `max_line_len` (default `false`) -- maximum line length (for minified code)

- `preamble` (default `null`) -- when passed it must be a string and
  it will be prepended to the output literally.  The source map will
  adjust for this text.  Can be used to insert a comment containing
  licensing information, for example.

- `quote_keys` (default `false`) -- pass `true` to quote all keys in literal
  objects

- `quote_style` (default `0`) -- preferred quote style for strings (affects
  quoted property names and directives as well):
  - `0` -- prefers double quotes, switches to single quotes when there are
    more double quotes in the string itself. `0` is best for gzip size.
  - `1` -- always use single quotes
  - `2` -- always use double quotes
  - `3` -- always use the original quotes

- `preserve_annotations` -- (default `false`) -- Preserve [Terser annotations](#annotations) in the output.

- `safari10` (default `false`) -- set this option to `true` to work around
  the [Safari 10/11 await bug](https://bugs.webkit.org/show_bug.cgi?id=176685).
  See also: the `safari10` [mangle option](#mangle-options).

- `semicolons` (default `true`) -- separate statements with semicolons.  If
  you pass `false` then whenever possible we will use a newline instead of a
  semicolon, leading to more readable output of minified code (size before
  gzip could be smaller; size after gzip insignificantly larger).

- `shebang` (default `true`) -- preserve shebang `#!` in preamble (bash scripts)

- `spidermonkey` (default `false`) -- produce a Spidermonkey (Mozilla) AST

- `webkit` (default `false`) -- enable workarounds for WebKit bugs.
  PhantomJS users should set this option to `true`.

- `wrap_iife` (default `false`) -- pass `true` to wrap immediately invoked
  function expressions. See
  [#640](https://github.com/mishoo/UglifyJS2/issues/640) for more details.

- `wrap_func_args` (default `true`) -- pass `false` if you do not want to wrap
  function expressions that are passed as arguments, in parenthesis. See
  [OptimizeJS](https://github.com/nolanlawson/optimize-js) for more details.


<!-- OPTIONS:END -->


# Miscellaneous

<!-- MISCELLANEOUS:START -->

### Keeping copyright notices or other comments

You can pass `--comments` to retain certain comments in the output.  By
default it will keep comments starting with "!" and JSDoc-style comments that
contain "@preserve", "@copyright", "@license" or "@cc_on" (conditional compilation for IE).
You can pass `--comments all` to keep all the comments, or a valid JavaScript regexp to
keep only comments that match this regexp.  For example `--comments /^!/`
will keep comments like `/*! Copyright Notice */`.

Note, however, that there might be situations where comments are lost.  For
example:
```javascript
function f() {
    /** @preserve Foo Bar */
    function g() {
        // this function is never called
    }
    return something();
}
```

Even though it has "@preserve", the comment will be lost because the inner
function `g` (which is the AST node to which the comment is attached to) is
discarded by the compressor as not referenced.

The safest comments where to place copyright information (or other info that
needs to be kept in the output) are comments attached to toplevel nodes.

### The `unsafe` `compress` option

It enables some transformations that *might* break code logic in certain
contrived cases, but should be fine for most code.  It assumes that standard
built-in ECMAScript functions and classes have not been altered or replaced.
You might want to try it on your own code; it should reduce the minified size.
Some examples of the optimizations made when this option is enabled:

- `new Array(1, 2, 3)` or `Array(1, 2, 3)` → `[ 1, 2, 3 ]`
- `Array.from([1, 2, 3])` → `[1, 2, 3]`
- `new Object()` → `{}`
- `String(exp)` or `exp.toString()` → `"" + exp`
- `new Object/RegExp/Function/Error/Array (...)` → we discard the `new`
- `"foo bar".substr(4)` → `"bar"`

### Conditional compilation

You can use the `--define` (`-d`) switch in order to declare global
variables that Terser will assume to be constants (unless defined in
scope).  For example if you pass `--define DEBUG=false` then, coupled with
dead code removal Terser will discard the following from the output:
```javascript
if (DEBUG) {
    console.log("debug stuff");
}
```

You can specify nested constants in the form of `--define env.DEBUG=false`.

Another way of doing that is to declare your globals as constants in a
separate file and include it into the build.  For example you can have a
`build/defines.js` file with the following:
```javascript
var DEBUG = false;
var PRODUCTION = true;
// etc.
```

and build your code like this:

    terser build/defines.js js/foo.js js/bar.js... -c

Terser will notice the constants and, since they cannot be altered, it
will evaluate references to them to the value itself and drop unreachable
code as usual.  The build will contain the `const` declarations if you use
them. If you are targeting < ES6 environments which does not support `const`,
using `var` with `reduce_vars` (enabled by default) should suffice.

### Conditional compilation API

You can also use conditional compilation via the programmatic API. With the difference that the
property name is `global_defs` and is a compressor property:

```javascript
var result = await minify(fs.readFileSync("input.js", "utf8"), {
    compress: {
        dead_code: true,
        global_defs: {
            DEBUG: false
        }
    }
});
```

To replace an identifier with an arbitrary non-constant expression it is
necessary to prefix the `global_defs` key with `"@"` to instruct Terser
to parse the value as an expression:
```javascript
await minify("alert('hello');", {
    compress: {
        global_defs: {
            "@alert": "console.log"
        }
    }
}).code;
// returns: 'console.log("hello");'
```

Otherwise it would be replaced as string literal:
```javascript
await minify("alert('hello');", {
    compress: {
        global_defs: {
            "alert": "console.log"
        }
    }
}).code;
// returns: '"console.log"("hello");'
```

### Annotations

Annotations in Terser are a way to tell it to treat a certain function call differently. The following annotations are available:

 * `/*@__INLINE__*/` - forces a function to be inlined somewhere.
 * `/*@__NOINLINE__*/` - Makes sure the called function is not inlined into the call site.
 * `/*@__PURE__*/` - Marks a function call as pure. That means, it can safely be dropped.
 * `/*@__KEY__*/` - Marks a string literal as a property to also mangle it when mangling properties.
 * `/*@__MANGLE_PROP__*/` - Opts-in an object property (or class field) for mangling, when the property mangler is enabled.

You can use either a `@` sign at the start, or a `#`.

Here are some examples on how to use them:

```javascript
/*@__INLINE__*/
function_always_inlined_here()

/*#__NOINLINE__*/
function_cant_be_inlined_into_here()

const x = /*#__PURE__*/i_am_dropped_if_x_is_not_used()

function lookup(object, key) { return object[key]; }
lookup({ i_will_be_mangled_too: "bar" }, /*@__KEY__*/ "i_will_be_mangled_too");
```

### ESTree / SpiderMonkey AST

Terser has its own abstract syntax tree format; for
[practical reasons](http://lisperator.net/blog/uglifyjs-why-not-switching-to-spidermonkey-ast/)
we can't easily change to using the SpiderMonkey AST internally.  However,
Terser now has a converter which can import a SpiderMonkey AST.

For example [Acorn](https://github.com/acornjs/acorn) is a super-fast parser that produces a
SpiderMonkey AST.  It has a small CLI utility that parses one file and dumps
the AST in JSON on the standard output.  To use Terser to mangle and
compress that:

    acorn file.js | terser -p spidermonkey -m -c

The `-p spidermonkey` option tells Terser that all input files are not
JavaScript, but JS code described in SpiderMonkey AST in JSON.  Therefore we
don't use our own parser in this case, but just transform that AST into our
internal AST.

`spidermonkey` is also available in `minify` as `parse` and `format` options to
accept and/or produce a spidermonkey AST.

### Use Acorn for parsing

More for fun, I added the `-p acorn` option which will use Acorn to do all
the parsing.  If you pass this option, Terser will `require("acorn")`.

Acorn is really fast (e.g. 250ms instead of 380ms on some 650K code), but
converting the SpiderMonkey tree that Acorn produces takes another 150ms so
in total it's a bit more than just using Terser's own parser.

### Terser Fast Minify Mode

It's not well known, but whitespace removal and symbol mangling accounts
for 95% of the size reduction in minified code for most JavaScript - not
elaborate code transforms. One can simply disable `compress` to speed up
Terser builds by 3 to 4 times.

| d3.js | size | gzip size | time (s) |
|   --- | ---: |      ---: |     ---: |
| original                                    | 451,131 | 108,733 |     - |
| terser@3.7.5 mangle=false, compress=false   | 316,600 |  85,245 |  0.82 |
| terser@3.7.5 mangle=true, compress=false    | 220,216 |  72,730 |  1.45 |
| terser@3.7.5 mangle=true, compress=true     | 212,046 |  70,954 |  5.87 |
| babili@0.1.4                                | 210,713 |  72,140 | 12.64 |
| babel-minify@0.4.3                          | 210,321 |  72,242 | 48.67 |
| babel-minify@0.5.0-alpha.01eac1c3           | 210,421 |  72,238 | 14.17 |

To enable fast minify mode from the CLI use:
```
terser file.js -m
```
To enable fast minify mode with the API use:
```js
await minify(code, { compress: false, mangle: true });
```

#### Source maps and debugging

Various `compress` transforms that simplify, rearrange, inline and remove code
are known to have an adverse effect on debugging with source maps. This is
expected as code is optimized and mappings are often simply not possible as
some code no longer exists. For highest fidelity in source map debugging
disable the `compress` option and just use `mangle`.

When debugging, make sure you enable the **"map scopes"** feature to map mangled variable names back to their original names.  
Without this, all variable values will be `undefined`. See https://github.com/terser/terser/issues/1367 for more details.
<br/><br/>

![image](https://user-images.githubusercontent.com/27283110/230441652-ac5cf6b0-5dc5-4ffc-9d8b-bd02875484f4.png)

### Compiler assumptions

To allow for better optimizations, the compiler makes various assumptions:

- `.toString()` and `.valueOf()` don't have side effects, and for built-in
  objects they have not been overridden.
- `undefined`, `NaN` and `Infinity` have not been externally redefined.
- `arguments.callee`, `arguments.caller` and `Function.prototype.caller` are not used.
- The code doesn't expect the contents of `Function.prototype.toString()` or
  `Error.prototype.stack` to be anything in particular.
- Getting and setting properties on a plain object does not cause other side effects
  (using `.watch()` or `Proxy`).
- Object properties can be added, removed and modified (not prevented with
  `Object.defineProperty()`, `Object.defineProperties()`, `Object.freeze()`,
  `Object.preventExtensions()` or `Object.seal()`).
- `document.all` is not `== null`
- Assigning properties to a class doesn't have side effects and does not throw.

### Build Tools and Adaptors using Terser

https://www.npmjs.com/browse/depended/terser

### Replacing `uglify-es` with `terser` in a project using `yarn`

A number of JS bundlers and uglify wrappers are still using buggy versions
of `uglify-es` and have not yet upgraded to `terser`. If you are using `yarn`
you can add the following alias to your project's `package.json` file:

```js
  "resolutions": {
    "uglify-es": "npm:terser"
  }
```

to use `terser` instead of `uglify-es` in all deeply nested dependencies
without changing any code.

Note: for this change to take effect you must run the following commands
to remove the existing `yarn` lock file and reinstall all packages:

```
$ rm -rf node_modules yarn.lock
$ yarn
```

<!-- MISCELLANEOUS:END -->

# Reporting issues

<!-- REPORTING_ISSUES:START -->

## A minimal, reproducible example

You're expected to provide a [minimal reproducible example] of input code that will demonstrate your issue.

To get to this example, you can remove bits of your code and stop if your issue ceases to reproduce.

## Obtaining the source code given to Terser

Because users often don't control the call to `await minify()` or its arguments, Terser provides a `TERSER_DEBUG_DIR` environment variable to make terser output some debug logs.

These logs will contain the input code and options of each `minify()` call.

```bash
TERSER_DEBUG_DIR=/tmp/terser-log-dir command-that-uses-terser
ls /tmp/terser-log-dir
terser-debug-123456.log
```

If you're not sure how to set an environment variable on your shell (the above example works in bash), you can try using cross-env:

```
> npx cross-env TERSER_DEBUG_DIR=/path/to/logs command-that-uses-terser
```

## Stack traces

In the terser CLI we use [source-map-support](https://npmjs.com/source-map-support) to produce good error stacks. In your own app, you're expected to enable source-map-support (read their docs) to have nice stack traces that will help you write good issues.

<!-- REPORTING_ISSUES:END -->

# README.md Patrons:

*note*: <s>You can support this project on patreon: [link]</s> **The Terser Patreon is shutting down in favor of opencollective**. Check out [PATRONS.md](https://github.com/terser/terser/blob/master/PATRONS.md) for our first-tier patrons.

These are the second-tier patrons. Great thanks for your support!

 * CKEditor ![](https://c10.patreonusercontent.com/3/eyJoIjoxMDAsInciOjEwMH0%3D/patreon-media/p/user/15452278/f8548dcf48d740619071e8d614459280/1?token-time=2145916800&token-hash=SIQ54PhIPHv3M7CVz9LxS8_8v4sOw4H304HaXsXj8MM%3D)
 * 38elements ![](https://c10.patreonusercontent.com/3/eyJ3IjoyMDB9/patreon-media/p/user/12501844/88e7fc5dd62d45c6a5626533bbd48cfb/1?token-time=2145916800&token-hash=c3AsQ5T0IQWic0zKxFHu-bGGQJkXQFvafvJ4bPerFR4%3D)

## Contributors

### Code Contributors

This project exists thanks to all the people who contribute. [[Contribute](CONTRIBUTING.md)].
<a href="https://github.com/terser/terser/graphs/contributors"><img src="https://opencollective.com/terser/contributors.svg?width=890&button=false" /></a>

### Financial Contributors

Become a financial contributor and help us sustain our community. [[Contribute](https://opencollective.com/terser/contribute)]

#### Individuals

<a href="https://opencollective.com/terser"><img src="https://opencollective.com/terser/individuals.svg?width=890"></a>

#### Organizations

Support this project with your organization. Your logo will show up here with a link to your website. [[Contribute](https://opencollective.com/terser/contribute)]

<a href="https://opencollective.com/terser/organization/0/website"><img src="https://opencollective.com/terser/organization/0/avatar.svg"></a>
<a href="https://opencollective.com/terser/organization/1/website"><img src="https://opencollective.com/terser/organization/1/avatar.svg"></a>
<a href="https://opencollective.com/terser/organization/2/website"><img src="https://opencollective.com/terser/organization/2/avatar.svg"></a>
<a href="https://opencollective.com/terser/organization/3/website"><img src="https://opencollective.com/terser/organization/3/avatar.svg"></a>
<a href="https://opencollective.com/terser/organization/4/website"><img src="https://opencollective.com/terser/organization/4/avatar.svg"></a>
<a href="https://opencollective.com/terser/organization/5/website"><img src="https://opencollective.com/terser/organization/5/avatar.svg"></a>
<a href="https://opencollective.com/terser/organization/6/website"><img src="https://opencollective.com/terser/organization/6/avatar.svg"></a>
<a href="https://opencollective.com/terser/organization/7/website"><img src="https://opencollective.com/terser/organization/7/avatar.svg"></a>
<a href="https://opencollective.com/terser/organization/8/website"><img src="https://opencollective.com/terser/organization/8/avatar.svg"></a>
<a href="https://opencollective.com/terser/organization/9/website"><img src="https://opencollective.com/terser/organization/9/avatar.svg"></a>


---

2.20.3 / 2019-10-11
==================

  * Support Node.js 0.10 (Revert #1059)
  * Ran "npm unpublish commander@2.20.2". There is no 2.20.2.

2.20.1 / 2019-09-29
==================

  * Improve executable subcommand tracking
  * Update dev dependencies

2.20.0 / 2019-04-02
==================

  * fix: resolve symbolic links completely when hunting for subcommands (#935)
  * Update index.d.ts (#930)
  * Update Readme.md (#924)
  * Remove --save option as it isn't required anymore (#918)
  * Add link to the license file (#900)
  * Added example of receiving args from options (#858)
  * Added missing semicolon (#882)
  * Add extension to .eslintrc (#876)

2.19.0 / 2018-10-02
==================

  * Removed newline after Options and Commands headers (#864)
  * Bugfix - Error output (#862)
  * Fix to change default value to string (#856)

2.18.0 / 2018-09-07
==================

  * Standardize help output (#853)
  * chmod 644 travis.yml (#851)
  * add support for execute typescript subcommand via ts-node (#849)

2.17.1 / 2018-08-07
==================

  * Fix bug in command emit (#844)

2.17.0 / 2018-08-03
==================

  * fixed newline output after help information (#833)
  * Fix to emit the action even without command (#778)
  * npm update (#823)

2.16.0 / 2018-06-29
==================

  * Remove Makefile and `test/run` (#821)
  * Make 'npm test' run on Windows (#820)
  * Add badge to display install size (#807)
  * chore: cache node_modules (#814)
  * chore: remove Node.js 4 (EOL), add Node.js 10 (#813)
  * fixed typo in readme (#812)
  * Fix types (#804)
  * Update eslint to resolve vulnerabilities in lodash (#799)
  * updated readme with custom event listeners. (#791)
  * fix tests (#794)

2.15.0 / 2018-03-07
==================

  * Update downloads badge to point to graph of downloads over time instead of duplicating link to npm
  * Arguments description

2.14.1 / 2018-02-07
==================

  * Fix typing of help function

2.14.0 / 2018-02-05
==================

  * only register the option:version event once
  * Fixes issue #727: Passing empty string for option on command is set to undefined
  * enable eqeqeq rule
  * resolves #754 add linter configuration to project
  * resolves #560 respect custom name for version option
  * document how to override the version flag
  * document using options per command

2.13.0 / 2018-01-09
==================

  * Do not print default for --no-
  * remove trailing spaces in command help
  * Update CI's Node.js to LTS and latest version
  * typedefs: Command and Option types added to commander namespace

2.12.2 / 2017-11-28
==================

  * fix: typings are not shipped

2.12.1 / 2017-11-23
==================

  * Move @types/node to dev dependency

2.12.0 / 2017-11-22
==================

  * add attributeName() method to Option objects
  * Documentation updated for options with --no prefix
  * typings: `outputHelp` takes a string as the first parameter
  * typings: use overloads
  * feat(typings): update to match js api
  * Print default value in option help
  * Fix translation error
  * Fail when using same command and alias (#491)
  * feat(typings): add help callback
  * fix bug when description is add after command with options (#662)
  * Format js code
  * Rename History.md to CHANGELOG.md (#668)
  * feat(typings): add typings to support TypeScript (#646)
  * use current node

2.11.0 / 2017-07-03
==================

  * Fix help section order and padding (#652)
  * feature: support for signals to subcommands (#632)
  * Fixed #37, --help should not display first (#447)
  * Fix translation errors. (#570)
  * Add package-lock.json
  * Remove engines
  * Upgrade package version
  * Prefix events to prevent conflicts between commands and options (#494)
  * Removing dependency on graceful-readlink
  * Support setting name in #name function and make it chainable
  * Add .vscode directory to .gitignore (Visual Studio Code metadata)
  * Updated link to ruby commander in readme files

2.10.0 / 2017-06-19
==================

  * Update .travis.yml. drop support for older node.js versions.
  * Fix require arguments in README.md
  * On SemVer you do not start from 0.0.1
  * Add missing semi colon in readme
  * Add save param to npm install
  * node v6 travis test
  * Update Readme_zh-CN.md
  * Allow literal '--' to be passed-through as an argument
  * Test subcommand alias help
  * link build badge to master branch
  * Support the alias of Git style sub-command
  * added keyword commander for better search result on npm
  * Fix Sub-Subcommands
  * test node.js stable
  * Fixes TypeError when a command has an option called `--description`
  * Update README.md to make it beginner friendly and elaborate on the difference between angled and square brackets.
  * Add chinese Readme file

2.9.0 / 2015-10-13
==================

  * Add option `isDefault` to set default subcommand #415 @Qix-
  * Add callback to allow filtering or post-processing of help text #434 @djulien
  * Fix `undefined` text in help information close #414 #416 @zhiyelee

2.8.1 / 2015-04-22
==================

 * Back out `support multiline description` Close #396 #397

2.8.0 / 2015-04-07
==================

  * Add `process.execArg` support, execution args like `--harmony` will be passed to sub-commands #387 @DigitalIO @zhiyelee
  * Fix bug in Git-style sub-commands #372 @zhiyelee
  * Allow commands to be hidden from help #383 @tonylukasavage
  * When git-style sub-commands are in use, yet none are called, display help #382 @claylo
  * Add ability to specify arguments syntax for top-level command #258 @rrthomas
  * Support multiline descriptions #208 @zxqfox

2.7.1 / 2015-03-11
==================

 * Revert #347 (fix collisions when option and first arg have same name) which causes a bug in #367.

2.7.0 / 2015-03-09
==================

 * Fix git-style bug when installed globally. Close #335 #349 @zhiyelee
 * Fix collisions when option and first arg have same name. Close #346 #347 @tonylukasavage
 * Add support for camelCase on `opts()`. Close #353  @nkzawa
 * Add node.js 0.12 and io.js to travis.yml
 * Allow RegEx options. #337 @palanik
 * Fixes exit code when sub-command failing.  Close #260 #332 @pirelenito
 * git-style `bin` files in $PATH make sense. Close #196 #327  @zhiyelee

2.6.0 / 2014-12-30
==================

  * added `Command#allowUnknownOption` method. Close #138 #318 @doozr @zhiyelee
  * Add application description to the help msg. Close #112 @dalssoft

2.5.1 / 2014-12-15
==================

  * fixed two bugs incurred by variadic arguments. Close #291 @Quentin01 #302 @zhiyelee

2.5.0 / 2014-10-24
==================

 * add support for variadic arguments. Closes #277 @whitlockjc

2.4.0 / 2014-10-17
==================

 * fixed a bug on executing the coercion function of subcommands option. Closes #270
 * added `Command.prototype.name` to retrieve command name. Closes #264 #266 @tonylukasavage
 * added `Command.prototype.opts` to retrieve all the options as a simple object of key-value pairs. Closes #262 @tonylukasavage
 * fixed a bug on subcommand name. Closes #248 @jonathandelgado
 * fixed function normalize doesn’t honor option terminator. Closes #216 @abbr

2.3.0 / 2014-07-16
==================

 * add command alias'. Closes PR #210
 * fix: Typos. Closes #99
 * fix: Unused fs module. Closes #217

2.2.0 / 2014-03-29
==================

 * add passing of previous option value
 * fix: support subcommands on windows. Closes #142
 * Now the defaultValue passed as the second argument of the coercion function.

2.1.0 / 2013-11-21
==================

 * add: allow cflag style option params, unit test, fixes #174

2.0.0 / 2013-07-18
==================

 * remove input methods (.prompt, .confirm, etc)

1.3.2 / 2013-07-18
==================

 * add support for sub-commands to co-exist with the original command

1.3.1 / 2013-07-18
==================

 * add quick .runningCommand hack so you can opt-out of other logic when running a sub command

1.3.0 / 2013-07-09
==================

 * add EACCES error handling
 * fix sub-command --help

1.2.0 / 2013-06-13
==================

 * allow "-" hyphen as an option argument
 * support for RegExp coercion

1.1.1 / 2012-11-20
==================

  * add more sub-command padding
  * fix .usage() when args are present. Closes #106

1.1.0 / 2012-11-16
==================

  * add git-style executable subcommand support. Closes #94

1.0.5 / 2012-10-09
==================

  * fix `--name` clobbering. Closes #92
  * fix examples/help. Closes #89

1.0.4 / 2012-09-03
==================

  * add `outputHelp()` method.

1.0.3 / 2012-08-30
==================

  * remove invalid .version() defaulting

1.0.2 / 2012-08-24
==================

  * add `--foo=bar` support [arv]
  * fix password on node 0.8.8. Make backward compatible with 0.6 [focusaurus]

1.0.1 / 2012-08-03
==================

  * fix issue #56
  * fix tty.setRawMode(mode) was moved to tty.ReadStream#setRawMode() (i.e. process.stdin.setRawMode())

1.0.0 / 2012-07-05
==================

  * add support for optional option descriptions
  * add defaulting of `.version()` to package.json's version

0.6.1 / 2012-06-01
==================

  * Added: append (yes or no) on confirmation
  * Added: allow node.js v0.7.x

0.6.0 / 2012-04-10
==================

  * Added `.prompt(obj, callback)` support. Closes #49
  * Added default support to .choose(). Closes #41
  * Fixed the choice example

0.5.1 / 2011-12-20
==================

  * Fixed `password()` for recent nodes. Closes #36

0.5.0 / 2011-12-04
==================

  * Added sub-command option support [itay]

0.4.3 / 2011-12-04
==================

  * Fixed custom help ordering. Closes #32

0.4.2 / 2011-11-24
==================

  * Added travis support
  * Fixed: line-buffered input automatically trimmed. Closes #31

0.4.1 / 2011-11-18
==================

  * Removed listening for "close" on --help

0.4.0 / 2011-11-15
==================

  * Added support for `--`. Closes #24

0.3.3 / 2011-11-14
==================

  * Fixed: wait for close event when writing help info [Jerry Hamlet]

0.3.2 / 2011-11-01
==================

  * Fixed long flag definitions with values [felixge]

0.3.1 / 2011-10-31
==================

  * Changed `--version` short flag to `-V` from `-v`
  * Changed `.version()` so it's configurable [felixge]

0.3.0 / 2011-10-31
==================

  * Added support for long flags only. Closes #18

0.2.1 / 2011-10-24
==================

  * "node": ">= 0.4.x < 0.7.0". Closes #20

0.2.0 / 2011-09-26
==================

  * Allow for defaults that are not just boolean. Default peassignment only occurs for --no-*, optional, and required arguments. [Jim Isaacs]

0.1.0 / 2011-08-24
==================

  * Added support for custom `--help` output

0.0.5 / 2011-08-18
==================

  * Changed: when the user enters nothing prompt for password again
  * Fixed issue with passwords beginning with numbers [NuckChorris]

0.0.4 / 2011-08-15
==================

  * Fixed `Commander#args`

0.0.3 / 2011-08-15
==================

  * Added default option value support

0.0.2 / 2011-08-15
==================

  * Added mask support to `Command#password(str[, mask], fn)`
  * Added `Command#password(str, fn)`

0.0.1 / 2010-01-03
==================

  * Initial release


---

# Commander.js


[![Build Status](https://api.travis-ci.org/tj/commander.js.svg?branch=master)](http://travis-ci.org/tj/commander.js)
[![NPM Version](http://img.shields.io/npm/v/commander.svg?style=flat)](https://www.npmjs.org/package/commander)
[![NPM Downloads](https://img.shields.io/npm/dm/commander.svg?style=flat)](https://npmcharts.com/compare/commander?minimal=true)
[![Install Size](https://packagephobia.now.sh/badge?p=commander)](https://packagephobia.now.sh/result?p=commander)
[![Join the chat at https://gitter.im/tj/commander.js](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/tj/commander.js?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)

  The complete solution for [node.js](http://nodejs.org) command-line interfaces, inspired by Ruby's [commander](https://github.com/commander-rb/commander).  
  [API documentation](http://tj.github.com/commander.js/)


## Installation

    $ npm install commander

## Option parsing

Options with commander are defined with the `.option()` method, also serving as documentation for the options. The example below parses args and options from `process.argv`, leaving remaining args as the `program.args` array which were not consumed by options.

```js
#!/usr/bin/env node

/**
 * Module dependencies.
 */

var program = require('commander');

program
  .version('0.1.0')
  .option('-p, --peppers', 'Add peppers')
  .option('-P, --pineapple', 'Add pineapple')
  .option('-b, --bbq-sauce', 'Add bbq sauce')
  .option('-c, --cheese [type]', 'Add the specified type of cheese [marble]', 'marble')
  .parse(process.argv);

console.log('you ordered a pizza with:');
if (program.peppers) console.log('  - peppers');
if (program.pineapple) console.log('  - pineapple');
if (program.bbqSauce) console.log('  - bbq');
console.log('  - %s cheese', program.cheese);
```

Short flags may be passed as a single arg, for example `-abc` is equivalent to `-a -b -c`. Multi-word options such as "--template-engine" are camel-cased, becoming `program.templateEngine` etc.

Note that multi-word options starting with `--no` prefix negate the boolean value of the following word. For example, `--no-sauce` sets the value of `program.sauce` to false.

```js
#!/usr/bin/env node

/**
 * Module dependencies.
 */

var program = require('commander');

program
  .option('--no-sauce', 'Remove sauce')
  .parse(process.argv);

console.log('you ordered a pizza');
if (program.sauce) console.log('  with sauce');
else console.log(' without sauce');
```

To get string arguments from options you will need to use angle brackets <> for required inputs or square brackets [] for optional inputs. 

e.g. ```.option('-m --myarg [myVar]', 'my super cool description')```

Then to access the input if it was passed in.

e.g. ```var myInput = program.myarg```

**NOTE**: If you pass a argument without using brackets the example above will return true and not the value passed in.


## Version option

Calling the `version` implicitly adds the `-V` and `--version` options to the command.
When either of these options is present, the command prints the version number and exits.

    $ ./examples/pizza -V
    0.0.1

If you want your program to respond to the `-v` option instead of the `-V` option, simply pass custom flags to the `version` method using the same syntax as the `option` method.

```js
program
  .version('0.0.1', '-v, --version')
```

The version flags can be named anything, but the long option is required.

## Command-specific options

You can attach options to a command.

```js
#!/usr/bin/env node

var program = require('commander');

program
  .command('rm <dir>')
  .option('-r, --recursive', 'Remove recursively')
  .action(function (dir, cmd) {
    console.log('remove ' + dir + (cmd.recursive ? ' recursively' : ''))
  })

program.parse(process.argv)
```

A command's options are validated when the command is used. Any unknown options will be reported as an error. However, if an action-based command does not define an action, then the options are not validated.

## Coercion

```js
function range(val) {
  return val.split('..').map(Number);
}

function list(val) {
  return val.split(',');
}

function collect(val, memo) {
  memo.push(val);
  return memo;
}

function increaseVerbosity(v, total) {
  return total + 1;
}

program
  .version('0.1.0')
  .usage('[options] <file ...>')
  .option('-i, --integer <n>', 'An integer argument', parseInt)
  .option('-f, --float <n>', 'A float argument', parseFloat)
  .option('-r, --range <a>..<b>', 'A range', range)
  .option('-l, --list <items>', 'A list', list)
  .option('-o, --optional [value]', 'An optional value')
  .option('-c, --collect [value]', 'A repeatable value', collect, [])
  .option('-v, --verbose', 'A value that can be increased', increaseVerbosity, 0)
  .parse(process.argv);

console.log(' int: %j', program.integer);
console.log(' float: %j', program.float);
console.log(' optional: %j', program.optional);
program.range = program.range || [];
console.log(' range: %j..%j', program.range[0], program.range[1]);
console.log(' list: %j', program.list);
console.log(' collect: %j', program.collect);
console.log(' verbosity: %j', program.verbose);
console.log(' args: %j', program.args);
```

## Regular Expression
```js
program
  .version('0.1.0')
  .option('-s --size <size>', 'Pizza size', /^(large|medium|small)$/i, 'medium')
  .option('-d --drink [drink]', 'Drink', /^(coke|pepsi|izze)$/i)
  .parse(process.argv);

console.log(' size: %j', program.size);
console.log(' drink: %j', program.drink);
```

## Variadic arguments

 The last argument of a command can be variadic, and only the last argument.  To make an argument variadic you have to
 append `...` to the argument name.  Here is an example:

```js
#!/usr/bin/env node

/**
 * Module dependencies.
 */

var program = require('commander');

program
  .version('0.1.0')
  .command('rmdir <dir> [otherDirs...]')
  .action(function (dir, otherDirs) {
    console.log('rmdir %s', dir);
    if (otherDirs) {
      otherDirs.forEach(function (oDir) {
        console.log('rmdir %s', oDir);
      });
    }
  });

program.parse(process.argv);
```

 An `Array` is used for the value of a variadic argument.  This applies to `program.args` as well as the argument passed
 to your action as demonstrated above.

## Specify the argument syntax

```js
#!/usr/bin/env node

var program = require('commander');

program
  .version('0.1.0')
  .arguments('<cmd> [env]')
  .action(function (cmd, env) {
     cmdValue = cmd;
     envValue = env;
  });

program.parse(process.argv);

if (typeof cmdValue === 'undefined') {
   console.error('no command given!');
   process.exit(1);
}
console.log('command:', cmdValue);
console.log('environment:', envValue || "no environment given");
```
Angled brackets (e.g. `<cmd>`) indicate required input. Square brackets (e.g. `[env]`) indicate optional input.

## Git-style sub-commands

```js
// file: ./examples/pm
var program = require('commander');

program
  .version('0.1.0')
  .command('install [name]', 'install one or more packages')
  .command('search [query]', 'search with optional query')
  .command('list', 'list packages installed', {isDefault: true})
  .parse(process.argv);
```

When `.command()` is invoked with a description argument, no `.action(callback)` should be called to handle sub-commands, otherwise there will be an error. This tells commander that you're going to use separate executables for sub-commands, much like `git(1)` and other popular tools.  
The commander will try to search the executables in the directory of the entry script (like `./examples/pm`) with the name `program-command`, like `pm-install`, `pm-search`.

Options can be passed with the call to `.command()`. Specifying `true` for `opts.noHelp` will remove the subcommand from the generated help output. Specifying `true` for `opts.isDefault` will run the subcommand if no other subcommand is specified.

If the program is designed to be installed globally, make sure the executables have proper modes, like `755`.

### `--harmony`

You can enable `--harmony` option in two ways:
* Use `#! /usr/bin/env node --harmony` in the sub-commands scripts. Note some os version don’t support this pattern.
* Use the `--harmony` option when call the command, like `node --harmony examples/pm publish`. The `--harmony` option will be preserved when spawning sub-command process.

## Automated --help

 The help information is auto-generated based on the information commander already knows about your program, so the following `--help` info is for free:

```  
$ ./examples/pizza --help
Usage: pizza [options]

An application for pizzas ordering

Options:
  -h, --help           output usage information
  -V, --version        output the version number
  -p, --peppers        Add peppers
  -P, --pineapple      Add pineapple
  -b, --bbq            Add bbq sauce
  -c, --cheese <type>  Add the specified type of cheese [marble]
  -C, --no-cheese      You do not want any cheese
```

## Custom help

 You can display arbitrary `-h, --help` information
 by listening for "--help". Commander will automatically
 exit once you are done so that the remainder of your program
 does not execute causing undesired behaviors, for example
 in the following executable "stuff" will not output when
 `--help` is used.

```js
#!/usr/bin/env node

/**
 * Module dependencies.
 */

var program = require('commander');

program
  .version('0.1.0')
  .option('-f, --foo', 'enable some foo')
  .option('-b, --bar', 'enable some bar')
  .option('-B, --baz', 'enable some baz');

// must be before .parse() since
// node's emit() is immediate

program.on('--help', function(){
  console.log('')
  console.log('Examples:');
  console.log('  $ custom-help --help');
  console.log('  $ custom-help -h');
});

program.parse(process.argv);

console.log('stuff');
```

Yields the following help output when `node script-name.js -h` or `node script-name.js --help` are run:

```
Usage: custom-help [options]

Options:
  -h, --help     output usage information
  -V, --version  output the version number
  -f, --foo      enable some foo
  -b, --bar      enable some bar
  -B, --baz      enable some baz

Examples:
  $ custom-help --help
  $ custom-help -h
```

## .outputHelp(cb)

Output help information without exiting.
Optional callback cb allows post-processing of help text before it is displayed.

If you want to display help by default (e.g. if no command was provided), you can use something like:

```js
var program = require('commander');
var colors = require('colors');

program
  .version('0.1.0')
  .command('getstream [url]', 'get stream URL')
  .parse(process.argv);

if (!process.argv.slice(2).length) {
  program.outputHelp(make_red);
}

function make_red(txt) {
  return colors.red(txt); //display the help text in red on the console
}
```

## .help(cb)

  Output help information and exit immediately.
  Optional callback cb allows post-processing of help text before it is displayed.


## Custom event listeners
 You can execute custom actions by listening to command and option events.

```js
program.on('option:verbose', function () {
  process.env.VERBOSE = this.verbose;
});

// error on unknown commands
program.on('command:*', function () {
  console.error('Invalid command: %s\nSee --help for a list of available commands.', program.args.join(' '));
  process.exit(1);
});
```

## Examples

```js
var program = require('commander');

program
  .version('0.1.0')
  .option('-C, --chdir <path>', 'change the working directory')
  .option('-c, --config <path>', 'set config path. defaults to ./deploy.conf')
  .option('-T, --no-tests', 'ignore test hook');

program
  .command('setup [env]')
  .description('run setup commands for all envs')
  .option("-s, --setup_mode [mode]", "Which setup mode to use")
  .action(function(env, options){
    var mode = options.setup_mode || "normal";
    env = env || 'all';
    console.log('setup for %s env(s) with %s mode', env, mode);
  });

program
  .command('exec <cmd>')
  .alias('ex')
  .description('execute the given remote cmd')
  .option("-e, --exec_mode <mode>", "Which exec mode to use")
  .action(function(cmd, options){
    console.log('exec "%s" using %s mode', cmd, options.exec_mode);
  }).on('--help', function() {
    console.log('');
    console.log('Examples:');
    console.log('');
    console.log('  $ deploy exec sequential');
    console.log('  $ deploy exec async');
  });

program
  .command('*')
  .action(function(env){
    console.log('deploying "%s"', env);
  });

program.parse(process.argv);
```

More Demos can be found in the [examples](https://github.com/tj/commander.js/tree/master/examples) directory.

## License

[MIT](https://github.com/tj/commander.js/blob/master/LICENSE)


---

<div align="center">
  <a href="https://github.com/webpack/webpack">
    <img width="200" height="200" src="https://webpack.js.org/assets/icon-square-big.svg">
  </a>
</div>

[![npm][npm]][npm-url]
[![node][node]][node-url]
[![tests][tests]][tests-url]
[![cover][cover]][cover-url]
[![discussion][discussion]][discussion-url]
[![size][size]][size-url]

# terser-webpack-plugin

This plugin uses [terser](https://github.com/terser/terser) to minify/minimize your JavaScript.

## Getting Started

Webpack v5 comes with the latest `terser-webpack-plugin` out of the box. If you are using Webpack v5 or above and wish to customize the options, you will still need to install `terser-webpack-plugin`. Using Webpack v4, you have to install `terser-webpack-plugin` v4.

To begin, you'll need to install `terser-webpack-plugin`:

```console
npm install terser-webpack-plugin --save-dev
```

or

```console
yarn add -D terser-webpack-plugin
```

or

```console
pnpm add -D terser-webpack-plugin
```

Then add the plugin to your `webpack` config. For example:

**webpack.config.js**

```js
const TerserPlugin = require("terser-webpack-plugin");

module.exports = {
  optimization: {
    minimize: true,
    minimizer: [new TerserPlugin()],
  },
};
```

And run `webpack` via your preferred method.

## Note about source maps

**Works only with `source-map`, `inline-source-map`, `hidden-source-map` and `nosources-source-map` values for the [`devtool`](https://webpack.js.org/configuration/devtool/) option.**

Why?

- `eval` wraps modules in `eval("string")` and the minimizer does not handle strings.
- `cheap` has not column information and minimizer generate only a single line, which leave only a single mapping.

Using supported `devtool` values enable source map generation.

## Options

- **[`test`](#test)**
- **[`include`](#include)**
- **[`exclude`](#exclude)**
- **[`parallel`](#parallel)**
- **[`minify`](#minify)**
- **[`terserOptions`](#terseroptions)**
- **[`extractComments`](#extractcomments)**

### `test`

Type:

```ts
type test = string | RegExp | Array<string | RegExp>;
```

Default: `/\.m?js(\?.*)?$/i`

Test to match files against.

**webpack.config.js**

```js
module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new TerserPlugin({
        test: /\.js(\?.*)?$/i,
      }),
    ],
  },
};
```

### `include`

Type:

```ts
type include = string | RegExp | Array<string | RegExp>;
```

Default: `undefined`

Files to include.

**webpack.config.js**

```js
module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new TerserPlugin({
        include: /\/includes/,
      }),
    ],
  },
};
```

### `exclude`

Type:

```ts
type exclude = string | RegExp | Array<string | RegExp>;
```

Default: `undefined`

Files to exclude.

**webpack.config.js**

```js
module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new TerserPlugin({
        exclude: /\/excludes/,
      }),
    ],
  },
};
```

### `parallel`

Type:

```ts
type parallel = boolean | number;
```

Default: `true`

Use multi-process parallel running to improve the build speed.
Default number of concurrent runs: `os.cpus().length - 1` or `os.availableParallelism() - 1` (if this function is supported).

> **Note**
>
> Parallelization can speedup your build significantly and is therefore **highly recommended**.

> **Warning**
>
> If you use **Circle CI** or any other environment that doesn't provide real available count of CPUs then you need to setup explicitly number of CPUs to avoid `Error: Call retries were exceeded` (see [#143](https://github.com/webpack-contrib/terser-webpack-plugin/issues/143), [#202](https://github.com/webpack-contrib/terser-webpack-plugin/issues/202)).

#### `boolean`

Enable/disable multi-process parallel running.

**webpack.config.js**

```js
module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new TerserPlugin({
        parallel: true,
      }),
    ],
  },
};
```

#### `number`

Enable multi-process parallel running and set number of concurrent runs.

**webpack.config.js**

```js
module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new TerserPlugin({
        parallel: 4,
      }),
    ],
  },
};
```

### `minify`

Type:

```ts
type minify = (
  input: {
    [file: string]: string;
  },
  sourceMap: import("@jridgewell/trace-mapping").SourceMapInput | undefined,
  minifyOptions: {
    module?: boolean | undefined;
    ecma?: import("terser").ECMA | undefined;
  },
  extractComments:
    | boolean
    | "all"
    | "some"
    | RegExp
    | ((
        astNode: any,
        comment: {
          value: string;
          type: "comment1" | "comment2" | "comment3" | "comment4";
          pos: number;
          line: number;
          col: number;
        }
      ) => boolean)
    | {
        condition?:
          | boolean
          | "all"
          | "some"
          | RegExp
          | ((
              astNode: any,
              comment: {
                value: string;
                type: "comment1" | "comment2" | "comment3" | "comment4";
                pos: number;
                line: number;
                col: number;
              }
            ) => boolean)
          | undefined;
        filename?: string | ((fileData: any) => string) | undefined;
        banner?:
          | string
          | boolean
          | ((commentsFile: string) => string)
          | undefined;
      }
    | undefined
) => Promise<{
  code: string;
  map?: import("@jridgewell/trace-mapping").SourceMapInput | undefined;
  errors?: (string | Error)[] | undefined;
  warnings?: (string | Error)[] | undefined;
  extractedComments?: string[] | undefined;
}>;
```

Default: `TerserPlugin.terserMinify`

Allows you to override default minify function.
By default plugin uses [terser](https://github.com/terser/terser) package.
Useful for using and testing unpublished versions or forks.

> **Warning**
>
> **Always use `require` inside `minify` function when `parallel` option enabled**.

**webpack.config.js**

```js
// Can be async
const minify = (input, sourceMap, minimizerOptions, extractsComments) => {
  // The `minimizerOptions` option contains option from the `terserOptions` option
  // You can use `minimizerOptions.myCustomOption`

  // Custom logic for extract comments
  const { map, code } = require("uglify-module") // Or require('./path/to/uglify-module')
    .minify(input, {
      /* Your options for minification */
    });

  return { map, code, warnings: [], errors: [], extractedComments: [] };
};

// Used to regenerate `fullhash`/`chunkhash` between different implementation
// Example: you fix a bug in custom minimizer/custom function, but unfortunately webpack doesn't know about it, so you will get the same fullhash/chunkhash
// to avoid this you can provide version of your custom minimizer
// You don't need if you use only `contenthash`
minify.getMinimizerVersion = () => {
  let packageJson;

  try {
    // eslint-disable-next-line global-require, import/no-extraneous-dependencies
    packageJson = require("uglify-module/package.json");
  } catch (error) {
    // Ignore
  }

  return packageJson && packageJson.version;
};

module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new TerserPlugin({
        terserOptions: {
          myCustomOption: true,
        },
        minify,
      }),
    ],
  },
};
```

### `terserOptions`

Type:

```ts
type terserOptions = {
  compress?: boolean | CompressOptions;
  ecma?: ECMA;
  enclose?: boolean | string;
  ie8?: boolean;
  keep_classnames?: boolean | RegExp;
  keep_fnames?: boolean | RegExp;
  mangle?: boolean | MangleOptions;
  module?: boolean;
  nameCache?: object;
  format?: FormatOptions;
  /** @deprecated */
  output?: FormatOptions;
  parse?: ParseOptions;
  safari10?: boolean;
  sourceMap?: boolean | SourceMapOptions;
  toplevel?: boolean;
};
```

Default: [default](https://github.com/terser/terser#minify-options)

Terser [options](https://github.com/terser/terser#minify-options).

**webpack.config.js**

```js
module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new TerserPlugin({
        terserOptions: {
          ecma: undefined,
          parse: {},
          compress: {},
          mangle: true, // Note `mangle.properties` is `false` by default.
          module: false,
          // Deprecated
          output: null,
          format: null,
          toplevel: false,
          nameCache: null,
          ie8: false,
          keep_classnames: undefined,
          keep_fnames: false,
          safari10: false,
        },
      }),
    ],
  },
};
```

### `extractComments`

Type:

```ts
type extractComments =
  | boolean
  | string
  | RegExp
  | ((
      astNode: any,
      comment: {
        value: string;
        type: "comment1" | "comment2" | "comment3" | "comment4";
        pos: number;
        line: number;
        col: number;
      }
    ) => boolean)
  | {
      condition?:
        | boolean
        | "all"
        | "some"
        | RegExp
        | ((
            astNode: any,
            comment: {
              value: string;
              type: "comment1" | "comment2" | "comment3" | "comment4";
              pos: number;
              line: number;
              col: number;
            }
          ) => boolean)
        | undefined;
      filename?: string | ((fileData: any) => string) | undefined;
      banner?:
        | string
        | boolean
        | ((commentsFile: string) => string)
        | undefined;
    };
```

Default: `true`

Whether comments shall be extracted to a separate file, (see [details](https://github.com/webpack/webpack/commit/71933e979e51c533b432658d5e37917f9e71595a)).
By default extract only comments using `/^\**!|@preserve|@license|@cc_on/i` regexp condition and remove remaining comments.
If the original file is named `foo.js`, then the comments will be stored to `foo.js.LICENSE.txt`.
The `terserOptions.format.comments` option specifies whether the comment will be preserved, i.e. it is possible to preserve some comments (e.g. annotations) while extracting others or even preserving comments that have been extracted.

#### `boolean`

Enable/disable extracting comments.

**webpack.config.js**

```js
module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new TerserPlugin({
        extractComments: true,
      }),
    ],
  },
};
```

#### `string`

Extract `all` or `some` (use `/^\**!|@preserve|@license|@cc_on/i` RegExp) comments.

**webpack.config.js**

```js
module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new TerserPlugin({
        extractComments: "all",
      }),
    ],
  },
};
```

#### `RegExp`

All comments that match the given expression will be extracted to the separate file.

**webpack.config.js**

```js
module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new TerserPlugin({
        extractComments: /@extract/i,
      }),
    ],
  },
};
```

#### `function`

All comments that match the given expression will be extracted to the separate file.

**webpack.config.js**

```js
module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new TerserPlugin({
        extractComments: (astNode, comment) => {
          if (/@extract/i.test(comment.value)) {
            return true;
          }

          return false;
        },
      }),
    ],
  },
};
```

#### `object`

Allow to customize condition for extract comments, specify extracted file name and banner.

**webpack.config.js**

```js
module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new TerserPlugin({
        extractComments: {
          condition: /^\**!|@preserve|@license|@cc_on/i,
          filename: (fileData) => {
            // The "fileData" argument contains object with "filename", "basename", "query" and "hash"
            return `${fileData.filename}.LICENSE.txt${fileData.query}`;
          },
          banner: (licenseFile) => {
            return `License information can be found in ${licenseFile}`;
          },
        },
      }),
    ],
  },
};
```

##### `condition`

Type:

```ts
type condition =
  | boolean
  | "all"
  | "some"
  | RegExp
  | ((
      astNode: any,
      comment: {
        value: string;
        type: "comment1" | "comment2" | "comment3" | "comment4";
        pos: number;
        line: number;
        col: number;
      }
    ) => boolean)
  | undefined;
```

Condition what comments you need extract.

**webpack.config.js**

```js
module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new TerserPlugin({
        extractComments: {
          condition: "some",
          filename: (fileData) => {
            // The "fileData" argument contains object with "filename", "basename", "query" and "hash"
            return `${fileData.filename}.LICENSE.txt${fileData.query}`;
          },
          banner: (licenseFile) => {
            return `License information can be found in ${licenseFile}`;
          },
        },
      }),
    ],
  },
};
```

##### `filename`

Type:

```ts
type filename = string | ((fileData: any) => string) | undefined;
```

Default: `[file].LICENSE.txt[query]`

Available placeholders: `[file]`, `[query]` and `[filebase]` (`[base]` for webpack 5).

The file where the extracted comments will be stored.
Default is to append the suffix `.LICENSE.txt` to the original filename.

> **Warning**
>
> We highly recommend using the `txt` extension. Using `js`/`cjs`/`mjs` extensions may conflict with existing assets which leads to broken code.

**webpack.config.js**

```js
module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new TerserPlugin({
        extractComments: {
          condition: /^\**!|@preserve|@license|@cc_on/i,
          filename: "extracted-comments.js",
          banner: (licenseFile) => {
            return `License information can be found in ${licenseFile}`;
          },
        },
      }),
    ],
  },
};
```

##### `banner`

Type:

```ts
type banner = string | boolean | ((commentsFile: string) => string) | undefined;
```

Default: `/*! For license information please see ${commentsFile} */`

The banner text that points to the extracted file and will be added on top of the original file.
Can be `false` (no banner), a `String`, or a `Function<(string) -> String>` that will be called with the filename where extracted comments have been stored.
Will be wrapped into comment.

**webpack.config.js**

```js
module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new TerserPlugin({
        extractComments: {
          condition: true,
          filename: (fileData) => {
            // The "fileData" argument contains object with "filename", "basename", "query" and "hash"
            return `${fileData.filename}.LICENSE.txt${fileData.query}`;
          },
          banner: (commentsFile) => {
            return `My custom banner about license information ${commentsFile}`;
          },
        },
      }),
    ],
  },
};
```

## Examples

### Preserve Comments

Extract all legal comments (i.e. `/^\**!|@preserve|@license|@cc_on/i`) and preserve `/@license/i` comments.

**webpack.config.js**

```js
module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new TerserPlugin({
        terserOptions: {
          format: {
            comments: /@license/i,
          },
        },
        extractComments: true,
      }),
    ],
  },
};
```

### Remove Comments

If you avoid building with comments, use this config:

**webpack.config.js**

```js
module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new TerserPlugin({
        terserOptions: {
          format: {
            comments: false,
          },
        },
        extractComments: false,
      }),
    ],
  },
};
```

### [`uglify-js`](https://github.com/mishoo/UglifyJS)

[`UglifyJS`](https://github.com/mishoo/UglifyJS) is a JavaScript parser, minifier, compressor and beautifier toolkit.

**webpack.config.js**

```js
module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new TerserPlugin({
        minify: TerserPlugin.uglifyJsMinify,
        // `terserOptions` options will be passed to `uglify-js`
        // Link to options - https://github.com/mishoo/UglifyJS#minify-options
        terserOptions: {},
      }),
    ],
  },
};
```

### [`swc`](https://github.com/swc-project/swc)

[`swc`](https://github.com/swc-project/swc) is a super-fast compiler written in rust; producing widely-supported javascript from modern standards and typescript.

> **Warning**
>
> the `extractComments` option is not supported and all comments will be removed by default, it will be fixed in future

**webpack.config.js**

```js
module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new TerserPlugin({
        minify: TerserPlugin.swcMinify,
        // `terserOptions` options will be passed to `swc` (`@swc/core`)
        // Link to options - https://swc.rs/docs/config-js-minify
        terserOptions: {},
      }),
    ],
  },
};
```

### [`esbuild`](https://github.com/evanw/esbuild)

[`esbuild`](https://github.com/evanw/esbuild) is an extremely fast JavaScript bundler and minifier.

> **Warning**
>
> the `extractComments` option is not supported and all legal comments (i.e. copyright, licenses and etc) will be preserved

**webpack.config.js**

```js
module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new TerserPlugin({
        minify: TerserPlugin.esbuildMinify,
        // `terserOptions` options will be passed to `esbuild`
        // Link to options - https://esbuild.github.io/api/#minify
        // Note: the `minify` options is true by default (and override other `minify*` options), so if you want to disable the `minifyIdentifiers` option (or other `minify*` options) please use:
        // terserOptions: {
        //   minify: false,
        //   minifyWhitespace: true,
        //   minifyIdentifiers: false,
        //   minifySyntax: true,
        // },
        terserOptions: {},
      }),
    ],
  },
};
```

### Custom Minify Function

Override default minify function - use `uglify-js` for minification.

**webpack.config.js**

```js
module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new TerserPlugin({
        minify: (file, sourceMap) => {
          // https://github.com/mishoo/UglifyJS2#minify-options
          const uglifyJsOptions = {
            /* your `uglify-js` package options */
          };

          if (sourceMap) {
            uglifyJsOptions.sourceMap = {
              content: sourceMap,
            };
          }

          return require("uglify-js").minify(file, uglifyJsOptions);
        },
      }),
    ],
  },
};
```

### Typescript

With default terser minify function:

```ts
module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new TerserPlugin({
        terserOptions: {
          compress: true,
        },
      }),
    ],
  },
};
```

With built-in minify functions:

```ts
import type { JsMinifyOptions as SwcOptions } from "@swc/core";
import type { MinifyOptions as UglifyJSOptions } from "uglify-js";
import type { TransformOptions as EsbuildOptions } from "esbuild";
import type { MinifyOptions as TerserOptions } from "terser";

module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new TerserPlugin<SwcOptions>({
        minify: TerserPlugin.swcMinify,
        terserOptions: {
          // `swc` options
        },
      }),
      new TerserPlugin<UglifyJSOptions>({
        minify: TerserPlugin.uglifyJsMinify,
        terserOptions: {
          // `uglif-js` options
        },
      }),
      new TerserPlugin<EsbuildOptions>({
        minify: TerserPlugin.esbuildMinify,
        terserOptions: {
          // `esbuild` options
        },
      }),

      // Alternative usage:
      new TerserPlugin<TerserOptions>({
        minify: TerserPlugin.terserMinify,
        terserOptions: {
          // `terser` options
        },
      }),
    ],
  },
};
```

## Contributing

Please take a moment to read our contributing guidelines if you haven't yet done so.

[CONTRIBUTING](./.github/CONTRIBUTING.md)

## License

[MIT](./LICENSE)

[npm]: https://img.shields.io/npm/v/terser-webpack-plugin.svg
[npm-url]: https://npmjs.com/package/terser-webpack-plugin
[node]: https://img.shields.io/node/v/terser-webpack-plugin.svg
[node-url]: https://nodejs.org
[tests]: https://github.com/webpack-contrib/terser-webpack-plugin/workflows/terser-webpack-plugin/badge.svg
[tests-url]: https://github.com/webpack-contrib/terser-webpack-plugin/actions
[cover]: https://codecov.io/gh/webpack-contrib/terser-webpack-plugin/branch/master/graph/badge.svg
[cover-url]: https://codecov.io/gh/webpack-contrib/terser-webpack-plugin
[discussion]: https://img.shields.io/github/discussions/webpack/webpack
[discussion-url]: https://github.com/webpack/webpack/discussions
[size]: https://packagephobia.now.sh/badge?p=terser-webpack-plugin
[size-url]: https://packagephobia.now.sh/result?p=terser-webpack-plugin


---

# jest-worker

Module for executing heavy tasks under forked processes in parallel, by providing a `Promise` based interface, minimum overhead, and bound workers.

The module works by providing an absolute path of the module to be loaded in all forked processes. Files relative to a node module are also accepted. All methods are exposed on the parent process as promises, so they can be `await`'ed. Child (worker) methods can either be synchronous or asynchronous.

The module also implements support for bound workers. Binding a worker means that, based on certain parameters, the same task will always be executed by the same worker. The way bound workers work is by using the returned string of the `computeWorkerKey` method. If the string was used before for a task, the call will be queued to the related worker that processed the task earlier; if not, it will be executed by the first available worker, then sticked to the worker that executed it; so the next time it will be processed by the same worker. If you have no preference on the worker executing the task, but you have defined a `computeWorkerKey` method because you want _some_ of the tasks to be sticked, you can return `null` from it.

The list of exposed methods can be explicitly provided via the `exposedMethods` option. If it is not provided, it will be obtained by requiring the child module into the main process, and analyzed via reflection. Check the "minimal example" section for a valid one.

## Install

```sh
$ yarn add jest-worker
```

## Example

This example covers the minimal usage:

### File `parent.js`

```javascript
import {Worker as JestWorker} from 'jest-worker';

async function main() {
  const worker = new JestWorker(require.resolve('./Worker'));
  const result = await worker.hello('Alice'); // "Hello, Alice"
}

main();
```

### File `worker.js`

```javascript
export function hello(param) {
  return 'Hello, ' + param;
}
```

## Experimental worker

Node 10 shipped with [worker-threads](https://nodejs.org/api/worker_threads.html), a "threading API" that uses SharedArrayBuffers to communicate between the main process and its child threads. This experimental Node feature can significantly improve the communication time between parent and child processes in `jest-worker`.

Since `worker_threads` are considered experimental in Node, you have to opt-in to this behavior by passing `enableWorkerThreads: true` when instantiating the worker. While the feature was unflagged in Node 11.7.0, you'll need to run the Node process with the `--experimental-worker` flag for Node 10.

## API

The `Worker` export is a constructor that is initialized by passing the worker path, plus an options object.

### `workerPath: string` (required)

Node module name or absolute path of the file to be loaded in the child processes. Use `require.resolve` to transform a relative path into an absolute one.

### `options: Object` (optional)

#### `exposedMethods: $ReadOnlyArray<string>` (optional)

List of method names that can be called on the child processes from the parent process. You cannot expose any method named like a public `Worker` method, or starting with `_`. If you use method auto-discovery, then these methods will not be exposed, even if they exist.

#### `numWorkers: number` (optional)

Amount of workers to spawn. Defaults to the number of CPUs minus 1.

#### `maxRetries: number` (optional)

Maximum amount of times that a dead child can be re-spawned, per call. Defaults to `3`, pass `Infinity` to allow endless retries.

#### `forkOptions: Object` (optional)

Allow customizing all options passed to `childProcess.fork`. By default, some values are set (`cwd`, `env` and `execArgv`), but you can override them and customize the rest. For a list of valid values, check [the Node documentation](https://nodejs.org/api/child_process.html#child_process_child_process_fork_modulepath_args_options).

#### `computeWorkerKey: (method: string, ...args: Array<any>) => ?string` (optional)

Every time a method exposed via the API is called, `computeWorkerKey` is also called in order to bound the call to a worker. This is useful for workers that are able to cache the result or part of it. You bound calls to a worker by making `computeWorkerKey` return the same identifier for all different calls. If you do not want to bind the call to any worker, return `null`.

The callback you provide is called with the method name, plus all the rest of the arguments of the call. Thus, you have full control to decide what to return. Check a practical example on bound workers under the "bound worker usage" section.

By default, no process is bound to any worker.

#### `setupArgs: Array<mixed>` (optional)

The arguments that will be passed to the `setup` method during initialization.

#### `WorkerPool: (workerPath: string, options?: WorkerPoolOptions) => WorkerPoolInterface` (optional)

Provide a custom worker pool to be used for spawning child processes. By default, Jest will use a node thread pool if available and fall back to child process threads.

#### `enableWorkerThreads: boolean` (optional)

`jest-worker` will automatically detect if `worker_threads` are available, but will not use them unless passed `enableWorkerThreads: true`.

### `workerSchedulingPolicy: 'round-robin' | 'in-order'` (optional)

Specifies the policy how tasks are assigned to workers if multiple workers are _idle_:

- `round-robin` (default): The task will be sequentially distributed onto the workers. The first task is assigned to the worker 1, the second to the worker 2, to ensure that the work is distributed across workers.
- `in-order`: The task will be assigned to the first free worker starting with worker 1 and only assign the work to worker 2 if the worker 1 is busy.

Tasks are always assigned to the first free worker as soon as tasks start to queue up. The scheduling policy does not define the task scheduling which is always first-in, first-out.

### `taskQueue`: TaskQueue` (optional)

The task queue defines in which order tasks (method calls) are processed by the workers. `jest-worker` ships with a `FifoQueue` and `PriorityQueue`:

- `FifoQueue` (default): Processes the method calls (tasks) in the call order.
- `PriorityQueue`: Processes the method calls by a computed priority in natural ordering (lower priorities first). Tasks with the same priority are processed in any order (FIFO not guaranteed). The constructor accepts a single argument, the function that is passed the name of the called function and the arguments and returns a numerical value for the priority: `new require('jest-worker').PriorityQueue((method, filename) => filename.length)`.

## JestWorker

### Methods

The returned `JestWorker` instance has all the exposed methods, plus some additional ones to interact with the workers itself:

#### `getStdout(): Readable`

Returns a `ReadableStream` where the standard output of all workers is piped. Note that the `silent` option of the child workers must be set to `true` to make it work. This is the default set by `jest-worker`, but keep it in mind when overriding options through `forkOptions`.

#### `getStderr(): Readable`

Returns a `ReadableStream` where the standard error of all workers is piped. Note that the `silent` option of the child workers must be set to `true` to make it work. This is the default set by `jest-worker`, but keep it in mind when overriding options through `forkOptions`.

#### `end()`

Finishes the workers by killing all workers. No further calls can be done to the `Worker` instance.

Returns a Promise that resolves with `{ forceExited: boolean }` once all workers are dead. If `forceExited` is `true`, at least one of the workers did not exit gracefully, which likely happened because it executed a leaky task that left handles open. This should be avoided, force exiting workers is a last resort to prevent creating lots of orphans.

**Note:**

`await`ing the `end()` Promise immediately after the workers are no longer needed before proceeding to do other useful things in your program may not be a good idea. If workers have to be force exited, `jest-worker` may go through multiple stages of force exiting (e.g. SIGTERM, later SIGKILL) and give the worker overall around 1 second time to exit on its own. During this time, your program will wait, even though it may not be necessary that all workers are dead before continuing execution.

Consider deliberately leaving this Promise floating (unhandled resolution). After your program has done the rest of its work and is about to exit, the Node process will wait for the Promise to resolve after all workers are dead as the last event loop task. That way you parallelized computation time of your program and waiting time and you didn't delay the outputs of your program unnecessarily.

### Worker IDs

Each worker has a unique id (index that starts with `1`), which is available inside the worker as `process.env.JEST_WORKER_ID`.

## Setting up and tearing down the child process

The child process can define two special methods (both of them can be asynchronous):

- `setup()`: If defined, it's executed before the first call to any method in the child.
- `teardown()`: If defined, it's executed when the farm ends.

# More examples

## Standard usage

This example covers the standard usage:

### File `parent.js`

```javascript
import {Worker as JestWorker} from 'jest-worker';

async function main() {
  const myWorker = new JestWorker(require.resolve('./Worker'), {
    exposedMethods: ['foo', 'bar', 'getWorkerId'],
    numWorkers: 4,
  });

  console.log(await myWorker.foo('Alice')); // "Hello from foo: Alice"
  console.log(await myWorker.bar('Bob')); // "Hello from bar: Bob"
  console.log(await myWorker.getWorkerId()); // "3" -> this message has sent from the 3rd worker

  const {forceExited} = await myWorker.end();
  if (forceExited) {
    console.error('Workers failed to exit gracefully');
  }
}

main();
```

### File `worker.js`

```javascript
export function foo(param) {
  return 'Hello from foo: ' + param;
}

export function bar(param) {
  return 'Hello from bar: ' + param;
}

export function getWorkerId() {
  return process.env.JEST_WORKER_ID;
}
```

## Bound worker usage:

This example covers the usage with a `computeWorkerKey` method:

### File `parent.js`

```javascript
import {Worker as JestWorker} from 'jest-worker';

async function main() {
  const myWorker = new JestWorker(require.resolve('./Worker'), {
    computeWorkerKey: (method, filename) => filename,
  });

  // Transform the given file, within the first available worker.
  console.log(await myWorker.transform('/tmp/foo.js'));

  // Wait a bit.
  await sleep(10000);

  // Transform the same file again. Will immediately return because the
  // transformed file is cached in the worker, and `computeWorkerKey` ensures
  // the same worker that processed the file the first time will process it now.
  console.log(await myWorker.transform('/tmp/foo.js'));

  const {forceExited} = await myWorker.end();
  if (forceExited) {
    console.error('Workers failed to exit gracefully');
  }
}

main();
```

### File `worker.js`

```javascript
import babel from '@babel/core';

const cache = Object.create(null);

export function transform(filename) {
  if (cache[filename]) {
    return cache[filename];
  }

  // jest-worker can handle both immediate results and thenables. If a
  // thenable is returned, it will be await'ed until it resolves.
  return babel.transformFileAsync(filename).then(result => {
    cache[filename] = result;

    return result;
  });
}
```


---

# supports-color

> Detect whether a terminal supports color

## Install

```
$ npm install supports-color
```

## Usage

```js
const supportsColor = require('supports-color');

if (supportsColor.stdout) {
	console.log('Terminal stdout supports color');
}

if (supportsColor.stdout.has256) {
	console.log('Terminal stdout supports 256 colors');
}

if (supportsColor.stderr.has16m) {
	console.log('Terminal stderr supports 16 million colors (truecolor)');
}
```

## API

Returns an `Object` with a `stdout` and `stderr` property for testing either streams. Each property is an `Object`, or `false` if color is not supported.

The `stdout`/`stderr` objects specifies a level of support for color through a `.level` property and a corresponding flag:

- `.level = 1` and `.hasBasic = true`: Basic color support (16 colors)
- `.level = 2` and `.has256 = true`: 256 color support
- `.level = 3` and `.has16m = true`: Truecolor support (16 million colors)

### `require('supports-color').supportsColor(stream, options?)`

Additionally, `supports-color` exposes the `.supportsColor()` function that takes an arbitrary write stream (e.g. `process.stdout`) and an optional options object to (re-)evaluate color support for an arbitrary stream.

For example, `require('supports-color').stdout` is the equivalent of `require('supports-color').supportsColor(process.stdout)`.

The options object supports a single boolean property `sniffFlags`. By default it is `true`, which instructs `supportsColor()` to sniff `process.argv` for the multitude of `--color` flags (see _Info_ below). If `false`, then `process.argv` is not considered when determining color support.

## Info

It obeys the `--color` and `--no-color` CLI flags.

For situations where using `--color` is not possible, use the environment variable `FORCE_COLOR=1` (level 1), `FORCE_COLOR=2` (level 2), or `FORCE_COLOR=3` (level 3) to forcefully enable color, or `FORCE_COLOR=0` to forcefully disable. The use of `FORCE_COLOR` overrides all other color support checks.

Explicit 256/Truecolor mode can be enabled using the `--color=256` and `--color=16m` flags, respectively.

## Related

- [supports-color-cli](https://github.com/chalk/supports-color-cli) - CLI for this module
- [chalk](https://github.com/chalk/chalk) - Terminal string styling done right

## Maintainers

- [Sindre Sorhus](https://github.com/sindresorhus)
- [Josh Junon](https://github.com/qix-)

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-supports-color?utm_source=npm-supports-color&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>

---


---

# thunky

Delay the evaluation of a paramless async function and cache the result (see [thunk](http://en.wikipedia.org/wiki/Thunk_%28functional_programming%29)).

```
npm install thunky
```

[![build status](http://img.shields.io/travis/mafintosh/thunky.svg?style=flat)](http://travis-ci.org/mafintosh/thunky)

## Example

Let's make a simple function that returns a random number 1 second after it is called for the first time

``` js
var thunky = require('thunky')

var test = thunky(function (callback) { // the inner function should only accept a callback
  console.log('waiting 1s and returning random number')
  setTimeout(function () {
    callback(Math.random())
  }, 1000)
})

test(function (num) {  // inner function is called the first time we call test
  console.log(num) // prints random number
})

test(function (num) {  // subsequent calls waits for the first call to finish and return the same value
  console.log(num) // prints the same random number as above
})
```

## Lazy evaluation

Thunky makes it easy to implement a lazy evaluation pattern.

``` js
var getDb = thunky(function (callback) {
  db.open(myConnectionString, callback)
})

var queryDb = function (query, callback) {
  getDb(function (err, db) {
    if (err) return callback(err)
    db.query(query, callback)
  })
}

queryDb('some query', function (err, result) { ... } )

queryDb('some other query', function (err, result) { ... } )
```

The first time `getDb` is called it will try do open a connection to the database.
Any subsequent calls will just wait for the first call to complete and then call your callback.

A nice property of this pattern is that it *easily* allows us to pass any error caused by `getDb` to the `queryDb` callback.

## Error → No caching

If the thunk callback is called with an `Error` object as the first argument it will not cache the result

``` js
var fails = thunky(function (callback) {
  console.log('returning an error')
  callback(new Error('bad stuff'))
})

fails(function (err) { // inner function is called
  console.log(err)
});

fails(function (err) { // inner function is called again as it returned an error before
  console.log(err)
})
```

## Promise version

A promise version is available as well

``` js
var thunkyp = require('thunky/promise')

var ready = thunkyp(async function () {
  // ... do async stuff
  return 42
})

// same semantics as the callback version
await ready()
```

## License

MIT


---

# tiny-invariant 🔬💥

[![Build Status](https://travis-ci.org/alexreardon/tiny-invariant.svg?branch=master)](https://travis-ci.org/alexreardon/tiny-invariant)
[![npm](https://img.shields.io/npm/v/tiny-invariant.svg)](https://www.npmjs.com/package/tiny-invariant) [![dependencies](https://david-dm.org/alexreardon/tiny-invariant.svg)](https://david-dm.org/alexreardon/tiny-invariant)
![types](https://img.shields.io/badge/types-typescript%20%7C%20flow-blueviolet)
[![minzip](https://img.shields.io/bundlephobia/minzip/tiny-invariant.svg)](https://www.npmjs.com/package/tiny-invariant)
[![Downloads per month](https://img.shields.io/npm/dm/tiny-invariant.svg)](https://www.npmjs.com/package/tiny-invariant)

A tiny [`invariant`](https://www.npmjs.com/package/invariant) alternative.

## What is `invariant`?

An `invariant` function takes a value, and if the value is [falsy](https://github.com/getify/You-Dont-Know-JS/blob/bdbe570600d4e1107d0b131787903ca1c9ec8140/up%20%26%20going/ch2.md#truthy--falsy) then the `invariant` function will throw. If the value is [truthy](https://github.com/getify/You-Dont-Know-JS/blob/bdbe570600d4e1107d0b131787903ca1c9ec8140/up%20%26%20going/ch2.md#truthy--falsy), then the function will not throw.

```js
import invariant from 'tiny-invariant';

invariant(truthyValue, 'This should not throw!');

invariant(falsyValue, 'This will throw!');
// Error('Invariant violation: This will throw!');
```

You can also provide a function to generate your message, for when your message is expensive to create

```js
import invariant from 'tiny-invariant';

invariant(value, () => getExpensiveMessage());
```

## Why `tiny-invariant`?

The [`library: invariant`](https://www.npmjs.com/package/invariant) supports passing in arguments to the `invariant` function in a sprintf style `(condition, format, a, b, c, d, e, f)`. It has internal logic to execute the sprintf substitutions. The sprintf logic is not removed in production builds. `tiny-invariant` has dropped all of the sprintf logic. `tiny-invariant` allows you to pass a single string message. With [template literals](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) there is really no need for a custom message formatter to be built into the library. If you need a multi part message you can just do this:

```js
invariant(condition, `Hello, ${name} - how are you today?`);
```

## Type narrowing

`tiny-invariant` is useful for correctly narrowing types for `flow` and `typescript`

```ts
const value: Person | null = { name: 'Alex' }; // type of value == 'Person | null'
invariant(value, 'Expected value to be a person');
// type of value has been narrowed to 'Person'
```

## API: `(condition: any, message?: string | (() => string)) => void`

- `condition` is required and can be anything
- `message` optional `string` or a function that returns a `string` (`() => string`)

## Installation

```bash
# yarn
yarn add tiny-invariant

# npm
npm install tiny-invariant --save
```

## Dropping your `message` for kb savings!

Big idea: you will want your compiler to convert this code:

```js
invariant(condition, 'My cool message that takes up a lot of kbs');
```

Into this:

```js
if (!condition) {
  if ('production' !== process.env.NODE_ENV) {
    invariant(false, 'My cool message that takes up a lot of kbs');
  } else {
    invariant(false);
  }
}
```

- **Babel**: recommend [`babel-plugin-dev-expression`](https://www.npmjs.com/package/babel-plugin-dev-expression)
- **TypeScript**: recommend [`tsdx`](https://github.com/jaredpalmer/tsdx#invariant) (or you can run `babel-plugin-dev-expression` after TypeScript compiling)

Your bundler can then drop the code in the `"production" !== process.env.NODE_ENV` block for your production builds to end up with this:

```js
if (!condition) {
  invariant(false);
}
```

- rollup: use [rollup-plugin-replace](https://github.com/rollup/rollup-plugin-replace) and set `NODE_ENV` to `production` and then `rollup` will treeshake out the unused code
- Webpack: [instructions](https://webpack.js.org/guides/production/#specify-the-mode)

## Builds

- We have a `es` (EcmaScript module) build
- We have a `cjs` (CommonJS) build
- We have a `umd` (Universal module definition) build in case you needed it

We expect `process.env.NODE_ENV` to be available at module compilation. We cache this value

## That's it!

🤘


---

# tiny-warning 🔬⚠️

[![Build Status](https://travis-ci.org/alexreardon/tiny-warning.svg?branch=master)](https://travis-ci.org/alexreardon/tiny-warning)
[![npm](https://img.shields.io/npm/v/tiny-warning.svg)](https://www.npmjs.com/package/tiny-warning) [![Downloads per month](https://img.shields.io/npm/dm/tiny-warning.svg)](https://www.npmjs.com/package/tiny-warning) [![dependencies](https://david-dm.org/alexreardon/tiny-warning.svg)](https://david-dm.org/alexreardon/tiny-warning)
[![min](https://img.shields.io/bundlephobia/min/tiny-warning.svg)](https://www.npmjs.com/package/tiny-warning)
[![minzip](https://img.shields.io/bundlephobia/minzip/tiny-warning.svg)](https://www.npmjs.com/package/tiny-warning)

A tiny [`warning`](https://www.npmjs.com/package/warning) alternative.

```js
import warning from 'tiny-warning';

warning(truthyValue, 'This should not log a warning');

warning(falsyValue, 'This should log a warning');
// console.warn('Warning: This should log a warning');
```

## API: `(condition: mixed, message: string) => void`

- `condition` is required and can be anything
- `message` is an required string that will be passed onto `console.warn`

## Why `tiny-warning`?

The [`library: warning`](https://www.npmjs.com/package/warning) supports passing in arguments to the `warning` function in a sprintf style `(condition, format, a, b, c, d, e, f)`. It has internal logic to execute the sprintf substitutions. `tiny-warning` has dropped all of the sprintf logic. `tiny-warning` allows you to pass a single string message. With [template literals](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) there is really no need for a custom message formatter to be built into the library. If you need a multi part message you can just do this: `warning(condition, 'Hello, ${name} - how are you today?')`

## Dropping your `warning` for kb savings!

We recommend using [`babel-plugin-dev-expression`](https://www.npmjs.com/package/babel-plugin-dev-expression) to remove `warning` calls from your production build. This saves you kb's as well as avoids logging warnings to the console for production.

What it does it turn your code that looks like this:

```js
warning(condition, 'My cool message that takes up a lot of kbs');
```

Into this

```js
if ('production' !== process.env.NODE_ENV) {
  warning(condition, 'My cool message that takes up a lot of kbs');
}
```

Your bundler can then drop the code in the `"production" !== process.env.NODE_ENV` block for your production builds

Final result:

```js
// nothing to see here! 👍
```

> For `rollup` use [rollup-plugin-replace](https://github.com/rollup/rollup-plugin-replace) and set `NODE_ENV` to `production` and then `rollup` will treeshake out the unused code
>
> [`Webpack` instructions](https://webpack.js.org/guides/production/#specify-the-mode)

## Builds

- We have a `es` (EcmaScript module) build (because you _know_ you want to deduplicate this super heavy library)
- We have a `cjs` (CommonJS) build
- We have a `umd` (Universal module definition) build in case you needed it

We expect `process.env.NODE_ENV` to be available at module compilation. We cache this value

## That's it!

🤘


---

# to-regex-range [![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=W8YFZ425KND68) [![NPM version](https://img.shields.io/npm/v/to-regex-range.svg?style=flat)](https://www.npmjs.com/package/to-regex-range) [![NPM monthly downloads](https://img.shields.io/npm/dm/to-regex-range.svg?style=flat)](https://npmjs.org/package/to-regex-range) [![NPM total downloads](https://img.shields.io/npm/dt/to-regex-range.svg?style=flat)](https://npmjs.org/package/to-regex-range) [![Linux Build Status](https://img.shields.io/travis/micromatch/to-regex-range.svg?style=flat&label=Travis)](https://travis-ci.org/micromatch/to-regex-range)

> Pass two numbers, get a regex-compatible source string for matching ranges. Validated against more than 2.78 million test assertions.

Please consider following this project's author, [Jon Schlinkert](https://github.com/jonschlinkert), and consider starring the project to show your :heart: and support.

## Install

Install with [npm](https://www.npmjs.com/):

```sh
$ npm install --save to-regex-range
```

<details>
<summary><strong>What does this do?</strong></summary>

<br>

This libary generates the `source` string to be passed to `new RegExp()` for matching a range of numbers.

**Example**

```js
const toRegexRange = require('to-regex-range');
const regex = new RegExp(toRegexRange('15', '95'));
```

A string is returned so that you can do whatever you need with it before passing it to `new RegExp()` (like adding `^` or `$` boundaries, defining flags, or combining it another string).

<br>

</details>

<details>
<summary><strong>Why use this library?</strong></summary>

<br>

### Convenience

Creating regular expressions for matching numbers gets deceptively complicated pretty fast.

For example, let's say you need a validation regex for matching part of a user-id, postal code, social security number, tax id, etc:

* regex for matching `1` => `/1/` (easy enough)
* regex for matching `1` through `5` => `/[1-5]/` (not bad...)
* regex for matching `1` or `5` => `/(1|5)/` (still easy...)
* regex for matching `1` through `50` => `/([1-9]|[1-4][0-9]|50)/` (uh-oh...)
* regex for matching `1` through `55` => `/([1-9]|[1-4][0-9]|5[0-5])/` (no prob, I can do this...)
* regex for matching `1` through `555` => `/([1-9]|[1-9][0-9]|[1-4][0-9]{2}|5[0-4][0-9]|55[0-5])/` (maybe not...)
* regex for matching `0001` through `5555` => `/(0{3}[1-9]|0{2}[1-9][0-9]|0[1-9][0-9]{2}|[1-4][0-9]{3}|5[0-4][0-9]{2}|55[0-4][0-9]|555[0-5])/` (okay, I get the point!)

The numbers are contrived, but they're also really basic. In the real world you might need to generate a regex on-the-fly for validation.

**Learn more**

If you're interested in learning more about [character classes](http://www.regular-expressions.info/charclass.html) and other regex features, I personally have always found [regular-expressions.info](http://www.regular-expressions.info/charclass.html) to be pretty useful.

### Heavily tested

As of April 07, 2019, this library runs [>1m test assertions](./test/test.js) against generated regex-ranges to provide brute-force verification that results are correct.

Tests run in ~280ms on my MacBook Pro, 2.5 GHz Intel Core i7.

### Optimized

Generated regular expressions are optimized:

* duplicate sequences and character classes are reduced using quantifiers
* smart enough to use `?` conditionals when number(s) or range(s) can be positive or negative
* uses fragment caching to avoid processing the same exact string more than once

<br>

</details>

## Usage

Add this library to your javascript application with the following line of code

```js
const toRegexRange = require('to-regex-range');
```

The main export is a function that takes two integers: the `min` value and `max` value (formatted as strings or numbers).

```js
const source = toRegexRange('15', '95');
//=> 1[5-9]|[2-8][0-9]|9[0-5]

const regex = new RegExp(`^${source}$`);
console.log(regex.test('14')); //=> false
console.log(regex.test('50')); //=> true
console.log(regex.test('94')); //=> true
console.log(regex.test('96')); //=> false
```

## Options

### options.capture

**Type**: `boolean`

**Deafault**: `undefined`

Wrap the returned value in parentheses when there is more than one regex condition. Useful when you're dynamically generating ranges.

```js
console.log(toRegexRange('-10', '10'));
//=> -[1-9]|-?10|[0-9]

console.log(toRegexRange('-10', '10', { capture: true }));
//=> (-[1-9]|-?10|[0-9])
```

### options.shorthand

**Type**: `boolean`

**Deafault**: `undefined`

Use the regex shorthand for `[0-9]`:

```js
console.log(toRegexRange('0', '999999'));
//=> [0-9]|[1-9][0-9]{1,5}

console.log(toRegexRange('0', '999999', { shorthand: true }));
//=> \d|[1-9]\d{1,5}
```

### options.relaxZeros

**Type**: `boolean`

**Default**: `true`

This option relaxes matching for leading zeros when when ranges are zero-padded.

```js
const source = toRegexRange('-0010', '0010');
const regex = new RegExp(`^${source}$`);
console.log(regex.test('-10')); //=> true
console.log(regex.test('-010')); //=> true
console.log(regex.test('-0010')); //=> true
console.log(regex.test('10')); //=> true
console.log(regex.test('010')); //=> true
console.log(regex.test('0010')); //=> true
```

When `relaxZeros` is false, matching is strict:

```js
const source = toRegexRange('-0010', '0010', { relaxZeros: false });
const regex = new RegExp(`^${source}$`);
console.log(regex.test('-10')); //=> false
console.log(regex.test('-010')); //=> false
console.log(regex.test('-0010')); //=> true
console.log(regex.test('10')); //=> false
console.log(regex.test('010')); //=> false
console.log(regex.test('0010')); //=> true
```

## Examples

| **Range**                   | **Result**                                                                      | **Compile time** |
| ---                         | ---                                                                             | ---              |
| `toRegexRange(-10, 10)`     | `-[1-9]\|-?10\|[0-9]`                                                           | _132μs_          |
| `toRegexRange(-100, -10)`   | `-1[0-9]\|-[2-9][0-9]\|-100`                                                    | _50μs_           |
| `toRegexRange(-100, 100)`   | `-[1-9]\|-?[1-9][0-9]\|-?100\|[0-9]`                                            | _42μs_           |
| `toRegexRange(001, 100)`    | `0{0,2}[1-9]\|0?[1-9][0-9]\|100`                                                | _109μs_          |
| `toRegexRange(001, 555)`    | `0{0,2}[1-9]\|0?[1-9][0-9]\|[1-4][0-9]{2}\|5[0-4][0-9]\|55[0-5]`                | _51μs_           |
| `toRegexRange(0010, 1000)`  | `0{0,2}1[0-9]\|0{0,2}[2-9][0-9]\|0?[1-9][0-9]{2}\|1000`                         | _31μs_           |
| `toRegexRange(1, 50)`       | `[1-9]\|[1-4][0-9]\|50`                                                         | _24μs_           |
| `toRegexRange(1, 55)`       | `[1-9]\|[1-4][0-9]\|5[0-5]`                                                     | _23μs_           |
| `toRegexRange(1, 555)`      | `[1-9]\|[1-9][0-9]\|[1-4][0-9]{2}\|5[0-4][0-9]\|55[0-5]`                        | _30μs_           |
| `toRegexRange(1, 5555)`     | `[1-9]\|[1-9][0-9]{1,2}\|[1-4][0-9]{3}\|5[0-4][0-9]{2}\|55[0-4][0-9]\|555[0-5]` | _43μs_           |
| `toRegexRange(111, 555)`    | `11[1-9]\|1[2-9][0-9]\|[2-4][0-9]{2}\|5[0-4][0-9]\|55[0-5]`                     | _38μs_           |
| `toRegexRange(29, 51)`      | `29\|[34][0-9]\|5[01]`                                                          | _24μs_           |
| `toRegexRange(31, 877)`     | `3[1-9]\|[4-9][0-9]\|[1-7][0-9]{2}\|8[0-6][0-9]\|87[0-7]`                       | _32μs_           |
| `toRegexRange(5, 5)`        | `5`                                                                             | _8μs_            |
| `toRegexRange(5, 6)`        | `5\|6`                                                                          | _11μs_           |
| `toRegexRange(1, 2)`        | `1\|2`                                                                          | _6μs_            |
| `toRegexRange(1, 5)`        | `[1-5]`                                                                         | _15μs_           |
| `toRegexRange(1, 10)`       | `[1-9]\|10`                                                                     | _22μs_           |
| `toRegexRange(1, 100)`      | `[1-9]\|[1-9][0-9]\|100`                                                        | _25μs_           |
| `toRegexRange(1, 1000)`     | `[1-9]\|[1-9][0-9]{1,2}\|1000`                                                  | _31μs_           |
| `toRegexRange(1, 10000)`    | `[1-9]\|[1-9][0-9]{1,3}\|10000`                                                 | _34μs_           |
| `toRegexRange(1, 100000)`   | `[1-9]\|[1-9][0-9]{1,4}\|100000`                                                | _36μs_           |
| `toRegexRange(1, 1000000)`  | `[1-9]\|[1-9][0-9]{1,5}\|1000000`                                               | _42μs_           |
| `toRegexRange(1, 10000000)` | `[1-9]\|[1-9][0-9]{1,6}\|10000000`                                              | _42μs_           |

## Heads up!

**Order of arguments**

When the `min` is larger than the `max`, values will be flipped to create a valid range:

```js
toRegexRange('51', '29');
```

Is effectively flipped to:

```js
toRegexRange('29', '51');
//=> 29|[3-4][0-9]|5[0-1]
```

**Steps / increments**

This library does not support steps (increments). A pr to add support would be welcome.

## History

### v2.0.0 - 2017-04-21

**New features**

Adds support for zero-padding!

### v1.0.0

**Optimizations**

Repeating ranges are now grouped using quantifiers. rocessing time is roughly the same, but the generated regex is much smaller, which should result in faster matching.

## Attribution

Inspired by the python library [range-regex](https://github.com/dimka665/range-regex).

## About

<details>
<summary><strong>Contributing</strong></summary>

Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).

</details>

<details>
<summary><strong>Running Tests</strong></summary>

Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

```sh
$ npm install && npm test
```

</details>

<details>
<summary><strong>Building docs</strong></summary>

_(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_

To generate the readme, run the following command:

```sh
$ npm install -g verbose/verb#dev verb-generate-readme && verb
```

</details>

### Related projects

You might also be interested in these projects:

* [expand-range](https://www.npmjs.com/package/expand-range): Fast, bash-like range expansion. Expand a range of numbers or letters, uppercase or lowercase. Used… [more](https://github.com/jonschlinkert/expand-range) | [homepage](https://github.com/jonschlinkert/expand-range "Fast, bash-like range expansion. Expand a range of numbers or letters, uppercase or lowercase. Used by micromatch.")
* [fill-range](https://www.npmjs.com/package/fill-range): Fill in a range of numbers or letters, optionally passing an increment or `step` to… [more](https://github.com/jonschlinkert/fill-range) | [homepage](https://github.com/jonschlinkert/fill-range "Fill in a range of numbers or letters, optionally passing an increment or `step` to use, or create a regex-compatible range with `options.toRegex`")
* [micromatch](https://www.npmjs.com/package/micromatch): Glob matching for javascript/node.js. A drop-in replacement and faster alternative to minimatch and multimatch. | [homepage](https://github.com/micromatch/micromatch "Glob matching for javascript/node.js. A drop-in replacement and faster alternative to minimatch and multimatch.")
* [repeat-element](https://www.npmjs.com/package/repeat-element): Create an array by repeating the given value n times. | [homepage](https://github.com/jonschlinkert/repeat-element "Create an array by repeating the given value n times.")
* [repeat-string](https://www.npmjs.com/package/repeat-string): Repeat the given string n times. Fastest implementation for repeating a string. | [homepage](https://github.com/jonschlinkert/repeat-string "Repeat the given string n times. Fastest implementation for repeating a string.")

### Contributors

| **Commits** | **Contributor** |  
| --- | --- |  
| 63 | [jonschlinkert](https://github.com/jonschlinkert) |  
| 3  | [doowb](https://github.com/doowb) |  
| 2  | [realityking](https://github.com/realityking) |  

### Author

**Jon Schlinkert**

* [GitHub Profile](https://github.com/jonschlinkert)
* [Twitter Profile](https://twitter.com/jonschlinkert)
* [LinkedIn Profile](https://linkedin.com/in/jonschlinkert)

Please consider supporting me on Patreon, or [start your own Patreon page](https://patreon.com/invite/bxpbvm)!

<a href="https://www.patreon.com/jonschlinkert">
<img src="https://c5.patreon.com/external/logo/become_a_patron_button@2x.png" height="50">
</a>

### License

Copyright © 2019, [Jon Schlinkert](https://github.com/jonschlinkert).
Released under the [MIT License](LICENSE).

***

_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.8.0, on April 07, 2019._

---

1.0.1 / 2021-11-14
==================

  * pref: enable strict mode

1.0.0 / 2018-07-09
==================

  * Initial release


---

# toidentifier

[![NPM Version][npm-image]][npm-url]
[![NPM Downloads][downloads-image]][downloads-url]
[![Build Status][github-actions-ci-image]][github-actions-ci-url]
[![Test Coverage][codecov-image]][codecov-url]

> Convert a string of words to a JavaScript identifier

## Install

This is a [Node.js](https://nodejs.org/en/) module available through the
[npm registry](https://www.npmjs.com/). Installation is done using the
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):

```bash
$ npm install toidentifier
```

## Example

```js
var toIdentifier = require('toidentifier')

console.log(toIdentifier('Bad Request'))
// => "BadRequest"
```

## API

This CommonJS module exports a single default function: `toIdentifier`.

### toIdentifier(string)

Given a string as the argument, it will be transformed according to
the following rules and the new string will be returned:

1. Split into words separated by space characters (`0x20`).
2. Upper case the first character of each word.
3. Join the words together with no separator.
4. Remove all non-word (`[0-9a-z_]`) characters.

## License

[MIT](LICENSE)

[codecov-image]: https://img.shields.io/codecov/c/github/component/toidentifier.svg
[codecov-url]: https://codecov.io/gh/component/toidentifier
[downloads-image]: https://img.shields.io/npm/dm/toidentifier.svg
[downloads-url]: https://npmjs.org/package/toidentifier
[github-actions-ci-image]: https://img.shields.io/github/workflow/status/component/toidentifier/ci/master?label=ci
[github-actions-ci-url]: https://github.com/component/toidentifier?query=workflow%3Aci
[npm-image]: https://img.shields.io/npm/v/toidentifier.svg
[npm-url]: https://npmjs.org/package/toidentifier


##

[npm]: https://www.npmjs.com/

[yarn]: https://yarnpkg.com/


---

# totalist [![build status](https://badgen.now.sh/github/status/lukeed/totalist)](https://github.com/lukeed/totalist/actions) [![codecov](https://badgen.now.sh/codecov/c/github/lukeed/totalist)](https://codecov.io/gh/lukeed/totalist)

> A tiny (195B to 224B) utility to recursively list all (total) files in a directory

Traverse a directory recursively, running a function for **every file** found.

With this module, you easily apply custom logic to decide which file(s) to process without worrying about accidentally accessing a directory or making repeat `fs.Stats` requests.

## Install

```
$ npm install --save totalist
```


## Modes

There are two "versions" of `totalist` available:

#### "async"
> **Node.js:** >= 8.x<br>
> **Size (gzip):** 220 bytes<br>
> **Availability:** [CommonJS](https://unpkg.com/totalist/dist/index.js), [ES Module](https://unpkg.com/totalist/dist/index.mjs)

This is the primary/default mode. It makes use of `async`/`await` and [`util.promisify`](https://nodejs.org/api/util.html#util_util_promisify_original).

#### "sync"
> **Node.js:** >= 6.x<br>
> **Size (gzip):** 195 bytes<br>
> **Availability:** [CommonJS](https://unpkg.com/totalist/sync/index.js), [ES Module](https://unpkg.com/totalist/sync/index.mjs)

This is the opt-in mode, ideal for scenarios where `async` usage cannot be supported.


## Usage

***Selecting a Mode***

```js
// import via npm module
import { totalist } from 'totalist';
import { totalist } from 'totalist/sync';
```

***Example Usage***

```js
import { totalist } from 'totalist/sync';

const styles = new Set();
const scripts = new Set();

totalist('src', (name, abs, stats) => {
  if (/\.js$/.test(name)) {
    scripts.add(abs);
    if (stats.size >= 100e3) {
      console.warn(`[WARN] "${name}" might cause performance issues (${stats.size})`);
    }
  } else if (/\.css$/.test(name)) {
    styles.add(abs);
  }
});

console.log([...scripts]);
//=> [..., '/Users/lukeed/.../src/path/to/example.css', ...]
```


## API

### totalist(dir, callback)
Returns: `void`

> **Important:** The "async" usage must be `await`ed or included within a Promise chain.

#### dir
Type: `string`<br>
Required: `true`

The directory to traverse.

This may be a relative _or_ an absolute path.

> **Note**: Node.js will assume a relative path is meant to be resolved from the current location (`process.cwd()`).

#### callback
Type: `Function`<br>
Required: `true`

The callback function to run for _every_ file.

The function receives three parameters:

##### relPath
Type: `String`<br>
The path _relative to_ the initial `dir` value you provided.

##### absPath
Type: `String`<br>
The absolute path of the file.

##### stats
Type: `fs.Stats`<br>
The [`fs.Stats`](https://nodejs.org/api/fs.html#fs_class_fs_stats) object for the file.


## License

MIT © [Luke Edwards](https://lukeed.com)


---

# trim-lines

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]

Remove spaces and tabs around line breaks.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`trimLines(value)`](#trimlinesvalue)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package is a tiny utility that removes spaces and tabs around line endings,
keeping the line endings, and not removing whitespace at the start or end of the
string.
It might look trivial, but it’s actually pretty complex to get performant.

## When should I use this?

When you need to trim markdown-like whitespace around line endings and don’t
want to run into performance problems.

## Install

This package is [ESM only][esm].
In Node.js (version 14.14+, 16.0+, or 18.0+), install with [npm][]:

```sh
npm install trim-lines
```

In Deno with [`esm.sh`][esmsh]:

```js
import trimLines from 'https://esm.sh/trim-lines@3'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import trimLines from 'https://esm.sh/trim-lines@3?bundle'
</script>
```

## Use

```js
import {trimLines} from 'trim-lines'

console.log(trimLines(' foo\t\n\n bar \n\tbaz ')) // => ' foo\n\nbar\nbaz '
```

## API

This package exports the identifier `trimLines`.
There is no default export.

### `trimLines(value)`

Remove spaces and tabs around line breaks in `value` (`string`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

This package is at least compatible with all maintained versions of Node.js.
As of now, that is Node.js 14.14+, 16.0+, and 18.0+.
It also works in Deno and modern browsers.

## Contribute

Yes please!
See [How to Contribute to Open Source][contribute].

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/wooorm/trim-lines/workflows/main/badge.svg

[build]: https://github.com/wooorm/trim-lines/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/trim-lines.svg

[coverage]: https://codecov.io/github/wooorm/trim-lines

[downloads-badge]: https://img.shields.io/npm/dm/trim-lines.svg

[downloads]: https://www.npmjs.com/package/trim-lines

[size-badge]: https://img.shields.io/bundlephobia/minzip/trim-lines.svg

[size]: https://bundlephobia.com/result?p=trim-lines

[npm]: https://docs.npmjs.com/cli/install

[license]: license

[author]: https://wooorm.com

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[typescript]: https://www.typescriptlang.org

[contribute]: https://opensource.guide/how-to-contribute/


---

# trough

[![Build][badge-build-image]][badge-build-url]
[![Coverage][badge-coverage-image]][badge-coverage-url]
[![Downloads][badge-downloads-image]][badge-downloads-url]
[![Size][badge-size-image]][badge-size-url]

`trough` is middleware.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`trough()`](#trough-1)
    *   [`wrap(middleware, callback)`](#wrapmiddleware-callback)
    *   [`Callback`](#callback)
    *   [`Middleware`](#middleware)
    *   [`Pipeline`](#pipeline)
    *   [`Run`](#run)
    *   [`Use`](#use-1)
*   [Compatibility](#compatibility)
*   [Security](#security)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

`trough` is like [`ware`][github-segmentio-ware] with less sugar.
Middleware functions can also change the input of the next.

The word **trough** (`/trôf/`) means a channel used to convey a liquid.

## When should I use this?

You can use this package when you’re building something that accepts “plugins”,
which are functions, that can be sync or async, promises or callbacks.

## Install

This package is [ESM only][github-gist-esm].
In Node.js (version 16+),
install with [npm][npm-install]:

```sh
npm install trough
```

In Deno with [`esm.sh`][esm-sh]:

```js
import {trough, wrap} from 'https://esm.sh/trough@2'
```

In browsers with [`esm.sh`][esm-sh]:

```html
<script type="module">
  import {trough, wrap} from 'https://esm.sh/trough@2?bundle'
</script>
```

## Use

```js
import fs from 'node:fs'
import path from 'node:path'
import process from 'node:process'
import {trough} from 'trough'

const pipeline = trough()
  .use(function (fileName) {
    console.log('Checking… ' + fileName)
  })
  .use(function (fileName) {
    return path.join(process.cwd(), fileName)
  })
  .use(function (filePath, next) {
    fs.stat(filePath, function (error, stats) {
      next(error, {filePath, stats})
    })
  })
  .use(function (ctx, next) {
    if (ctx.stats.isFile()) {
      fs.readFile(ctx.filePath, next)
    } else {
      next(new Error('Expected file'))
    }
  })

pipeline.run('readme.md', console.log)
pipeline.run('node_modules', console.log)
```

Yields:

```txt
Checking… readme.md
Checking… node_modules
Error: Expected file
    at ~/example.js:22:12
    at wrapped (~/node_modules/trough/index.js:111:16)
    at next (~/node_modules/trough/index.js:62:23)
    at done (~/node_modules/trough/index.js:145:7)
    at ~/example.js:15:7
    at FSReqCallback.oncomplete (node:fs:199:5)
null <Buffer 23 20 74 72 6f 75 67 68 0a 0a 5b 21 5b 42 75 69 6c 64 5d 5b 62 75 69 6c 64 2d 62 61 64 67 65 5d 5d 5b 62 75 69 6c 64 5d 0a 5b 21 5b 43 6f 76 65 72 61 ... 7994 more bytes>
```

## API

This package exports the identifiers
[`trough`][api-trough] and
[`wrap`][api-wrap].
There is no default export.

It exports the [TypeScript][] types
[`Callback`][api-callback],
[`Middleware`][api-middleware],
[`Pipeline`][api-pipeline],
[`Run`][api-run],
and [`Use`][api-use].

### `trough()`

Create new middleware.

###### Parameters

There are no parameters.

###### Returns

[`Pipeline`][api-pipeline].

### `wrap(middleware, callback)`

Wrap `middleware` into a uniform interface.

You can pass all input to the resulting function.
`callback` is then called with the output of `middleware`.

If `middleware` accepts more arguments than the later given in input,
an extra `done` function is passed to it after that input,
which must be called by `middleware`.

The first value in `input` is the main input value.
All other input values are the rest input values.
The values given to `callback` are the input values,
merged with every non-nullish output value.

*   if `middleware` throws an error,
    returns a promise that is rejected,
    or calls the given `done` function with an error,
    `callback` is called with that error
*   if `middleware` returns a value or returns a promise that is resolved,
    that value is the main output value
*   if `middleware` calls `done`,
    all non-nullish values except for the first one (the error) overwrite the
    output values

###### Parameters

*   `middleware` ([`Middleware`][api-middleware])
    — function to wrap
*   `callback` ([`Callback`][api-callback])
    — callback called with the output of `middleware`

###### Returns

Wrapped middleware ([`Run`][api-run]).

### `Callback`

Callback function (TypeScript type).

###### Parameters

*   `error` (`Error`, optional)
    — error, if any
*   `...output` (`Array<unknown>`, optional)
    — output values

###### Returns

Nothing (`undefined`).

### `Middleware`

A middleware function called with the output of its predecessor (TypeScript
type).

###### Synchronous

If `fn` returns or throws an error,
the pipeline fails and `done` is called with that error.

If `fn` returns a value (neither `null` nor `undefined`),
the first `input` of the next function is set to that value
(all other `input` is passed through).

The following example shows how returning an error stops the pipeline:

```js
import {trough} from 'trough'

trough()
  .use(function (thing) {
    return new Error('Got: ' + thing)
  })
  .run('some value', console.log)
```

Yields:

```txt
Error: Got: some value
    at ~/example.js:5:12
    …
```

The following example shows how throwing an error stops the pipeline:

```js
import {trough} from 'trough'

trough()
  .use(function (thing) {
    throw new Error('Got: ' + thing)
  })
  .run('more value', console.log)
```

Yields:

```txt
Error: Got: more value
    at ~/example.js:5:11
    …
```

The following example shows how the first output can be modified:

```js
import {trough} from 'trough'

trough()
  .use(function (thing) {
    return 'even ' + thing
  })
  .run('more value', 'untouched', console.log)
```

Yields:

```txt
null 'even more value' 'untouched'
```

###### Promise

If `fn` returns a promise,
and that promise rejects,
the pipeline fails and `done` is called with the rejected value.

If `fn` returns a promise,
and that promise resolves with a value (neither `null` nor `undefined`),
the first `input` of the next function is set to that value (all other `input`
is passed through).

The following example shows how rejecting a promise stops the pipeline:

```js
import {trough} from 'trough'

trough()
  .use(function (thing) {
    return new Promise(function (resolve, reject) {
      reject('Got: ' + thing)
    })
  })
  .run('thing', console.log)
```

Yields:

```txt
Got: thing
```

The following example shows how the input isn’t touched by resolving to `null`.

```js
import {trough} from 'trough'

trough()
  .use(function () {
    return new Promise(function (resolve) {
      setTimeout(function () {
        resolve(null)
      }, 100)
    })
  })
  .run('Input', console.log)
```

Yields:

```txt
null 'Input'
```

###### Asynchronous

If `fn` accepts one more argument than the given `input`,
a `next` function is given (after the input).
`next` must be called, but doesn’t have to be called async.

If `next` is given a value (neither `null` nor `undefined`) as its first
argument,
the pipeline fails and `done` is called with that value.

If `next` is given no value (either `null` or `undefined`) as the first
argument,
all following non-nullish values change the input of the following
function,
and all nullish values default to the `input`.

The following example shows how passing a first argument stops the pipeline:

```js
import {trough} from 'trough'

trough()
  .use(function (thing, next) {
    next(new Error('Got: ' + thing))
  })
  .run('thing', console.log)
```

Yields:

```txt
Error: Got: thing
    at ~/example.js:5:10
```

The following example shows how more values than the input are passed.

```js
import {trough} from 'trough'

trough()
  .use(function (thing, next) {
    setTimeout(function () {
      next(null, null, 'values')
    }, 100)
  })
  .run('some', console.log)
```

Yields:

```txt
null 'some' 'values'
```

###### Parameters

*   `...input` (`Array<any>`, optional)
    — input values

###### Returns

Output, promise, etc (`any`).

### `Pipeline`

Pipeline (TypeScript type).

###### Properties

*   `run` ([`Run`][api-run])
    — run the pipeline
*   `use` ([`Use`][api-use])
    — add middleware

### `Run`

Call all middleware (TypeScript type).

Calls `done` on completion with either an error or the output of the
last middleware.

> 👉 **Note**: as the length of input defines whether async functions get a
> `next` function,
> it’s recommended to keep `input` at one value normally.

###### Parameters

*   `...input` (`Array<any>`, optional)
    — input values
*   `done` ([`Callback`][api-callback])
    — callback called when done

###### Returns

Nothing (`undefined`).

### `Use`

Add middleware (TypeScript type).

###### Parameters

*   `middleware` ([`Middleware`][api-middleware])
    — middleware function

###### Returns

Current pipeline ([`Pipeline`][api-pipeline]).

## Compatibility

This projects is compatible with maintained versions of Node.js.

When we cut a new major release,
we drop support for unmaintained versions of Node.
This means we try to keep the current release line,
`trough@2`,
compatible with Node.js 12.

## Security

This package is safe.

## Contribute

Yes please!
See [How to Contribute to Open Source][open-source-guide-contribute].

## License

[MIT][file-license] © [Titus Wormer][wooorm]

<!-- Definitions -->

[api-callback]: #callback

[api-middleware]: #middleware

[api-pipeline]: #pipeline

[api-run]: #run

[api-trough]: #trough

[api-use]: #use

[api-wrap]: #wrapmiddleware-callback

[badge-build-image]: https://github.com/wooorm/trough/workflows/main/badge.svg

[badge-build-url]: https://github.com/wooorm/trough/actions

[badge-coverage-image]: https://img.shields.io/codecov/c/github/wooorm/trough.svg

[badge-coverage-url]: https://codecov.io/github/wooorm/trough

[badge-downloads-image]: https://img.shields.io/npm/dm/trough.svg

[badge-downloads-url]: https://www.npmjs.com/package/trough

[badge-size-image]: https://img.shields.io/bundlejs/size/trough

[badge-size-url]: https://bundlejs.com/?q=trough

[npm-install]: https://docs.npmjs.com/cli/install

[esm-sh]: https://esm.sh

[file-license]: license

[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[github-segmentio-ware]: https://github.com/segmentio/ware

[open-source-guide-contribute]: https://opensource.guide/how-to-contribute/

[typescript]: https://www.typescriptlang.org

[wooorm]: https://wooorm.com


---

# tslib

This is a runtime library for [TypeScript](https://www.typescriptlang.org/) that contains all of the TypeScript helper functions.

This library is primarily used by the `--importHelpers` flag in TypeScript.
When using `--importHelpers`, a module that uses helper functions like `__extends` and `__assign` in the following emitted file:

```ts
var __assign = (this && this.__assign) || Object.assign || function(t) {
    for (var s, i = 1, n = arguments.length; i < n; i++) {
        s = arguments[i];
        for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
            t[p] = s[p];
    }
    return t;
};
exports.x = {};
exports.y = __assign({}, exports.x);

```

will instead be emitted as something like the following:

```ts
var tslib_1 = require("tslib");
exports.x = {};
exports.y = tslib_1.__assign({}, exports.x);
```

Because this can avoid duplicate declarations of things like `__extends`, `__assign`, etc., this means delivering users smaller files on average, as well as less runtime overhead.
For optimized bundles with TypeScript, you should absolutely consider using `tslib` and `--importHelpers`.

# Installing

For the latest stable version, run:

## npm

```sh
# TypeScript 3.9.2 or later
npm install tslib

# TypeScript 3.8.4 or earlier
npm install tslib@^1

# TypeScript 2.3.2 or earlier
npm install tslib@1.6.1
```

## yarn

```sh
# TypeScript 3.9.2 or later
yarn add tslib

# TypeScript 3.8.4 or earlier
yarn add tslib@^1

# TypeScript 2.3.2 or earlier
yarn add tslib@1.6.1
```

## bower

```sh
# TypeScript 3.9.2 or later
bower install tslib

# TypeScript 3.8.4 or earlier
bower install tslib@^1

# TypeScript 2.3.2 or earlier
bower install tslib@1.6.1
```

## JSPM

```sh
# TypeScript 3.9.2 or later
jspm install tslib

# TypeScript 3.8.4 or earlier
jspm install tslib@^1

# TypeScript 2.3.2 or earlier
jspm install tslib@1.6.1
```

# Usage

Set the `importHelpers` compiler option on the command line:

```
tsc --importHelpers file.ts
```

or in your tsconfig.json:

```json
{
    "compilerOptions": {
        "importHelpers": true
    }
}
```

#### For bower and JSPM users

You will need to add a `paths` mapping for `tslib`, e.g. For Bower users:

```json
{
    "compilerOptions": {
        "module": "amd",
        "importHelpers": true,
        "baseUrl": "./",
        "paths": {
            "tslib" : ["bower_components/tslib/tslib.d.ts"]
        }
    }
}
```

For JSPM users:

```json
{
    "compilerOptions": {
        "module": "system",
        "importHelpers": true,
        "baseUrl": "./",
        "paths": {
            "tslib" : ["jspm_packages/npm/tslib@2.x.y/tslib.d.ts"]
        }
    }
}
```

## Deployment

- Choose your new version number
- Set it in `package.json` and `bower.json`
- Create a tag: `git tag [version]`
- Push the tag: `git push --tags`
- Create a [release in GitHub](https://github.com/microsoft/tslib/releases)
- Run the [publish to npm](https://github.com/microsoft/tslib/actions?query=workflow%3A%22Publish+to+NPM%22) workflow

Done.

# Contribute

There are many ways to [contribute](https://github.com/Microsoft/TypeScript/blob/master/CONTRIBUTING.md) to TypeScript.

* [Submit bugs](https://github.com/Microsoft/TypeScript/issues) and help us verify fixes as they are checked in.
* Review the [source code changes](https://github.com/Microsoft/TypeScript/pulls).
* Engage with other TypeScript users and developers on [StackOverflow](http://stackoverflow.com/questions/tagged/typescript).
* Join the [#typescript](http://twitter.com/#!/search/realtime/%23typescript) discussion on Twitter.
* [Contribute bug fixes](https://github.com/Microsoft/TypeScript/blob/master/CONTRIBUTING.md).

# Documentation

* [Quick tutorial](http://www.typescriptlang.org/Tutorial)
* [Programming handbook](http://www.typescriptlang.org/Handbook)
* [Homepage](http://www.typescriptlang.org/)


---

<!-- BEGIN MICROSOFT SECURITY.MD V0.0.7 BLOCK -->

## Security

Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include [Microsoft](https://github.com/Microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet), [Xamarin](https://github.com/xamarin), and [our GitHub organizations](https://opensource.microsoft.com/).

If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](https://aka.ms/opensource/security/definition), please report it to us as described below.

## Reporting Security Issues

**Please do not report security vulnerabilities through public GitHub issues.**

Instead, please report them to the Microsoft Security Response Center (MSRC) at [https://msrc.microsoft.com/create-report](https://aka.ms/opensource/security/create-report).

If you prefer to submit without logging in, send email to [secure@microsoft.com](mailto:secure@microsoft.com).  If possible, encrypt your message with our PGP key; please download it from the [Microsoft Security Response Center PGP Key page](https://aka.ms/opensource/security/pgpkey).

You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at [microsoft.com/msrc](https://aka.ms/opensource/security/msrc). 

Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue:

  * Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.)
  * Full paths of source file(s) related to the manifestation of the issue
  * The location of the affected source code (tag/branch/commit or direct URL)
  * Any special configuration required to reproduce the issue
  * Step-by-step instructions to reproduce the issue
  * Proof-of-concept or exploit code (if possible)
  * Impact of the issue, including how an attacker might exploit the issue

This information will help us triage your report more quickly.

If you are reporting for a bug bounty, more complete reports can contribute to a higher bounty award. Please visit our [Microsoft Bug Bounty Program](https://aka.ms/opensource/security/bounty) page for more details about our active programs.

## Preferred Languages

We prefer all communications to be in English.

## Policy

Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://aka.ms/opensource/security/cvd).

<!-- END MICROSOFT SECURITY.MD BLOCK -->


---

<div align="center">
	<br>
	<br>
	<img src="media/logo.svg" alt="type-fest" height="300">
	<br>
	<br>
	<b>A collection of essential TypeScript types</b>
	<br>
	<br>
	<br>
	<br>
	<hr>
	<div align="center">
		<p>
			<p>
				<sup>
					<a href="https://github.com/sponsors/sindresorhus">Sindre Sorhus' open source work is supported by the community</a>
				</sup>
			</p>
			<sup>Special thanks to:</sup>
			<br>
			<br>
			<a href="https://standardresume.co/tech">
				<img src="https://sindresorhus.com/assets/thanks/standard-resume-logo.svg" width="180"/>
			</a>
			<br>
			<br>
			<br>
			<a href="https://workos.com/?utm_campaign=github_repo&utm_medium=referral&utm_content=type-fest&utm_source=github">
				<div>
					<img src="https://sindresorhus.com/assets/thanks/workos-logo-white-bg.svg" width="220" alt="WorkOS">
				</div>
				<b>Your app, enterprise-ready.</b>
				<div>
					<sub>Start selling to enterprise customers with just a few lines of code.</sub>
					<br>
					<sup>Add Single Sign-On (and more) in minutes instead of months.</sup>
				</div>
			</a>
			<br>
			<br>
			<br>
			<a href="https://www.useanvil.com/?utm_source=sindresorhus#gh-light-mode-only">
				<div>
					<img src="https://sindresorhus.com/assets/thanks/anvil-logo-light.svg" width="200" alt="Anvil">
				</div>
				<br>
				<b>Paperwork that makes the data work.</b>
				<div>
					<sub>
					Easy APIs for paperwork. PDF generation, e-signature and embeddable no-code webforms.
					<br>
					The easiest way to build paperwork automation into your product.
					</sub>
				</div>
			</a>
			<a href="https://www.useanvil.com/?utm_source=sindresorhus#gh-dark-mode-only">
				<div>
					<img src="https://sindresorhus.com/assets/thanks/anvil-logo-dark.svg" width="200" alt="Anvil">
				</div>
				<br>
				<b>Paperwork that makes the data work.</b>
				<div>
					<sub>
					Easy APIs for paperwork. PDF generation, e-signature and embeddable no-code webforms.
					<br>
					The easiest way to build paperwork automation into your product.
					</sub>
				</div>
			</a>
		</p>
	</div>
	<br>
	<hr>
</div>
<br>
<br>

[![](https://img.shields.io/badge/unicorn-approved-ff69b4.svg)](https://giphy.com/gifs/illustration-rainbow-unicorn-26AHG5KGFxSkUWw1i)
[![npm dependents](https://badgen.net/npm/dependents/type-fest)](https://www.npmjs.com/package/type-fest?activeTab=dependents)
[![npm downloads](https://badgen.net/npm/dt/type-fest)](https://www.npmjs.com/package/type-fest)
[![Docs](https://paka.dev/badges/v0/cute.svg)](https://paka.dev/npm/type-fest)

Many of the types here should have been built-in. You can help by suggesting some of them to the [TypeScript project](https://github.com/Microsoft/TypeScript/blob/main/CONTRIBUTING.md).

Either add this package as a dependency or copy-paste the needed types. No credit required. 👌

PR welcome for additional commonly needed types and docs improvements. Read the [contributing guidelines](.github/contributing.md) first.

**Help wanted with reviewing [proposals](https://github.com/sindresorhus/type-fest/issues) and [pull requests](https://github.com/sindresorhus/type-fest/pulls).**

## Install

```sh
npm install type-fest
```

*Requires TypeScript >=4.2*

## Usage

```ts
import type {Except} from 'type-fest';

type Foo = {
	unicorn: string;
	rainbow: boolean;
};

type FooWithoutRainbow = Except<Foo, 'rainbow'>;
//=> {unicorn: string}
```

## API

Click the type names for complete docs.

### Basic

- [`Primitive`](source/primitive.d.ts) - Matches any [primitive value](https://developer.mozilla.org/en-US/docs/Glossary/Primitive).
- [`Class`](source/basic.d.ts) - Matches a [`class`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes).
- [`Constructor`](source/basic.d.ts) - Matches a [`class` constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes).
- [`TypedArray`](source/typed-array.d.ts) - Matches any [typed array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray), like `Uint8Array` or `Float64Array`.
- [`ObservableLike`](source/observable-like.d.ts) - Matches a value that is like an [Observable](https://github.com/tc39/proposal-observable).

### Utilities

- [`Except`](source/except.d.ts) - Create a type from an object type without certain keys. This is a stricter version of [`Omit`](https://www.typescriptlang.org/docs/handbook/utility-types.html#omittype-keys).
- [`Writable`](source/writable.d.ts) - Create a type that strips `readonly` from all or some of an object's keys. The inverse of `Readonly<T>`. Formerly named `Mutable`.
- [`Merge`](source/merge.d.ts) - Merge two types into a new type. Keys of the second type overrides keys of the first type.
- [`MergeExclusive`](source/merge-exclusive.d.ts) - Create a type that has mutually exclusive keys.
- [`RequireAtLeastOne`](source/require-at-least-one.d.ts) - Create a type that requires at least one of the given keys.
- [`RequireExactlyOne`](source/require-exactly-one.d.ts) - Create a type that requires exactly a single key of the given keys and disallows more.
- [`RequireAllOrNone`](source/require-all-or-none.d.ts) - Create a type that requires all of the given keys or none of the given keys.
- [`RemoveIndexSignature`](source/remove-index-signature.d.ts) - Create a type that only has explicitly defined properties, absent of any index signatures.
- [`PartialDeep`](source/partial-deep.d.ts) - Create a deeply optional version of another type. Use [`Partial<T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#partialtype) if you only need one level deep.
- [`PartialOnUndefinedDeep`](source/partial-on-undefined-deep.d.ts) - Create a deep version of another type where all keys accepting `undefined` type are set to optional.
- [`ReadonlyDeep`](source/readonly-deep.d.ts) - Create a deeply immutable version of an `object`/`Map`/`Set`/`Array` type. Use [`Readonly<T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#readonlytype) if you only need one level deep.
- [`LiteralUnion`](source/literal-union.d.ts) - Create a union type by combining primitive types and literal types without sacrificing auto-completion in IDEs for the literal type part of the union. Workaround for [Microsoft/TypeScript#29729](https://github.com/Microsoft/TypeScript/issues/29729).
- [`Opaque`](source/opaque.d.ts) - Create an [opaque type](https://codemix.com/opaque-types-in-javascript/).
- [`UnwrapOpaque`](source/opaque.d.ts) - Revert an [opaque type](https://codemix.com/opaque-types-in-javascript/) back to its original type.
- [`InvariantOf`](source/invariant-of.d.ts) - Create an [invariant type](https://basarat.gitbook.io/typescript/type-system/type-compatibility#footnote-invariance), which is a type that does not accept supertypes and subtypes.
- [`SetOptional`](source/set-optional.d.ts) - Create a type that makes the given keys optional.
- [`SetRequired`](source/set-required.d.ts) - Create a type that makes the given keys required.
- [`SetNonNullable`](source/set-non-nullable.d.ts) - Create a type that makes the given keys non-nullable.
- [`ValueOf`](source/value-of.d.ts) - Create a union of the given object's values, and optionally specify which keys to get the values from.
- [`ConditionalKeys`](source/conditional-keys.d.ts) - Extract keys from a shape where values extend the given `Condition` type.
- [`ConditionalPick`](source/conditional-pick.d.ts) - Like `Pick` except it selects properties from a shape where the values extend the given `Condition` type.
- [`ConditionalExcept`](source/conditional-except.d.ts) - Like `Omit` except it removes properties from a shape where the values extend the given `Condition` type.
- [`UnionToIntersection`](source/union-to-intersection.d.ts) - Convert a union type to an intersection type.
- [`LiteralToPrimitive`](source/literal-to-primitive.d.ts) - Convert a [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types) to the [primitive type](source/primitive.d.ts) it belongs to.
- [`Stringified`](source/stringified.d.ts) - Create a type with the keys of the given type changed to `string` type.
- [`IterableElement`](source/iterable-element.d.ts) - Get the element type of an `Iterable`/`AsyncIterable`. For example, an array or a generator.
- [`Entry`](source/entry.d.ts) - Create a type that represents the type of an entry of a collection.
- [`Entries`](source/entries.d.ts) - Create a type that represents the type of the entries of a collection.
- [`SetReturnType`](source/set-return-type.d.ts) - Create a function type with a return type of your choice and the same parameters as the given function type.
- [`Simplify`](source/simplify.d.ts) - Useful to flatten the type output to improve type hints shown in editors. And also to transform an interface into a type to aide with assignability.
- [`Get`](source/get.d.ts) - Get a deeply-nested property from an object using a key path, like [Lodash's `.get()`](https://lodash.com/docs/latest#get) function.
- [`StringKeyOf`](source/string-key-of.d.ts) - Get keys of the given type as strings.
- [`Schema`](source/schema.d.ts) - Create a deep version of another object type where property values are recursively replaced into a given value type.
- [`Exact`](source/exact.d.ts) - Create a type that does not allow extra properties.
- [`OptionalKeysOf`](source/optional-keys-of.d.ts) - Extract all optional keys from the given type.
- [`HasOptionalKeys`](source/has-optional-keys.d.ts) - Create a `true`/`false` type depending on whether the given type has any optional fields.
- [`RequiredKeysOf`](source/required-keys-of.d.ts) - Extract all required keys from the given type.
- [`HasRequiredKeys`](source/has-required-keys.d.ts) - Create a `true`/`false` type depending on whether the given type has any required fields.
- [`Spread`](source/spread.d.ts) - Mimic the type inferred by TypeScript when merging two objects or two arrays/tuples using the spread syntax.

### JSON

- [`Jsonify`](source/jsonify.d.ts) - Transform a type to one that is assignable to the `JsonValue` type.
- [`JsonPrimitive`](source/basic.d.ts) - Matches a JSON primitive.
- [`JsonObject`](source/basic.d.ts) - Matches a JSON object.
- [`JsonArray`](source/basic.d.ts) - Matches a JSON array.
- [`JsonValue`](source/basic.d.ts) - Matches any valid JSON value.

### Async

- [`Promisable`](source/promisable.d.ts) - Create a type that represents either the value or the value wrapped in `PromiseLike`.
- [`AsyncReturnType`](source/async-return-type.d.ts) - Unwrap the return type of a function that returns a `Promise`.
- [`Asyncify`](source/asyncify.d.ts) - Create an async version of the given function type.

### String

- [`Trim`](source/trim.d.ts) - Remove leading and trailing spaces from a string.
- [`Split`](source/split.d.ts) - Represents an array of strings split using a given character or character set.
- [`Replace`](source/replace.d.ts) - Represents a string with some or all matches replaced by a replacement.

### Array

- [`Includes`](source/includes.d.ts) - Returns a boolean for whether the given array includes the given item.
- [`Join`](source/join.d.ts) - Join an array of strings and/or numbers using the given string as a delimiter.
- [`LastArrayElement`](source/last-array-element.d.ts) - Extracts the type of the last element of an array.
- [`FixedLengthArray`](source/fixed-length-array.d.ts) - Create a type that represents an array of the given type and length.
- [`MultidimensionalArray`](source/multidimensional-array.d.ts) - Create a type that represents a multidimensional array of the given type and dimensions.
- [`MultidimensionalReadonlyArray`](source/multidimensional-readonly-array.d.ts) - Create a type that represents a multidimensional readonly array of the given type and dimensions.
- [`ReadonlyTuple`](source/readonly-tuple.d.ts) - Create a type that represents a read-only tuple of the given type and length.

### Numeric

- [`PositiveInfinity`](source/numeric.d.ts) - Matches the hidden `Infinity` type.
- [`NegativeInfinity`](source/numeric.d.ts) - Matches the hidden `-Infinity` type.
- [`Finite`](source/numeric.d.ts) - A finite `number`.
- [`Integer`](source/numeric.d.ts) - A `number` that is an integer.
- [`Float`](source/numeric.d.ts) - A `number` that is not an integer.
- [`NegativeFloat`](source/numeric.d.ts) - A negative (`-∞ < x < 0`) `number` that is not an integer.
- [`Negative`](source/numeric.d.ts) - A negative `number`/`bigint` (`-∞ < x < 0`)
- [`NonNegative`](source/numeric.d.ts) - A non-negative `number`/`bigint` (`0 <= x < ∞`).
- [`NegativeInteger`](source/numeric.d.ts) - A negative (`-∞ < x < 0`) `number` that is an integer.
- [`NonNegativeInteger`](source/numeric.d.ts) - A non-negative (`0 <= x < ∞`) `number` that is an integer.

### Change case

- [`CamelCase`](source/camel-case.d.ts) - Convert a string literal to camel-case (`fooBar`).
- [`CamelCasedProperties`](source/camel-cased-properties.d.ts) - Convert object properties to camel-case (`fooBar`).
- [`CamelCasedPropertiesDeep`](source/camel-cased-properties-deep.d.ts) - Convert object properties to camel-case recursively (`fooBar`).
- [`KebabCase`](source/kebab-case.d.ts) - Convert a string literal to kebab-case (`foo-bar`).
- [`KebabCasedProperties`](source/kebab-cased-properties.d.ts) - Convert a object properties to kebab-case recursively (`foo-bar`).
- [`KebabCasedPropertiesDeep`](source/kebab-cased-properties-deep.d.ts) - Convert object properties to kebab-case (`foo-bar`).
- [`PascalCase`](source/pascal-case.d.ts) - Converts a string literal to pascal-case (`FooBar`)
- [`PascalCasedProperties`](source/pascal-cased-properties.d.ts) - Converts object properties to pascal-case (`FooBar`)
- [`PascalCasedPropertiesDeep`](source/pascal-cased-properties-deep.d.ts) - Converts object properties to pascal-case (`FooBar`)
- [`SnakeCase`](source/snake-case.d.ts) - Convert a string literal to snake-case (`foo_bar`).
- [`SnakeCasedProperties`](source/snake-cased-properties-deep.d.ts) - Convert object properties to snake-case (`foo_bar`).
- [`SnakeCasedPropertiesDeep`](source/snake-cased-properties-deep.d.ts) - Convert object properties to snake-case recursively (`foo_bar`).
- [`ScreamingSnakeCase`](source/screaming-snake-case.d.ts) - Convert a string literal to screaming-snake-case (`FOO_BAR`).
- [`DelimiterCase`](source/delimiter-case.d.ts) - Convert a string literal to a custom string delimiter casing.
- [`DelimiterCasedProperties`](source/delimiter-cased-properties.d.ts) - Convert object properties to a custom string delimiter casing.
- [`DelimiterCasedPropertiesDeep`](source/delimiter-cased-properties-deep.d.ts) - Convert object properties to a custom string delimiter casing recursively.

### Miscellaneous

- [`PackageJson`](source/package-json.d.ts) - Type for [npm's `package.json` file](https://docs.npmjs.com/creating-a-package-json-file). It also includes support for [TypeScript Declaration Files](https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html) and [Yarn Workspaces](https://classic.yarnpkg.com/lang/en/docs/workspaces/).
- [`TsConfigJson`](source/tsconfig-json.d.ts) - Type for [TypeScript's `tsconfig.json` file](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) (TypeScript 4.4).

## Declined types

*If we decline a type addition, we will make sure to document the better solution here.*

- [`Diff` and `Spread`](https://github.com/sindresorhus/type-fest/pull/7) - The pull request author didn't provide any real-world use-cases and the PR went stale. If you think this type is useful, provide some real-world use-cases and we might reconsider.
- [`Dictionary`](https://github.com/sindresorhus/type-fest/issues/33) - You only save a few characters (`Dictionary<number>` vs `Record<string, number>`) from [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type), which is more flexible and well-known. Also, you shouldn't use an object as a dictionary. We have `Map` in JavaScript now.
- [`ExtractProperties` and `ExtractMethods`](https://github.com/sindresorhus/type-fest/pull/4) - The types violate the single responsibility principle. Instead, refine your types into more granular type hierarchies.
- [`Url2Json`](https://github.com/sindresorhus/type-fest/pull/262) - Inferring search parameters from a URL string is a cute idea, but not very useful in practice, since search parameters are usually dynamic and defined separately.
- [`Nullish`](https://github.com/sindresorhus/type-fest/pull/318) - The type only saves a couple of characters, not everyone knows what "nullish" means, and I'm also trying to [get away from `null`](https://github.com/sindresorhus/meta/discussions/7).
- [`TitleCase`](https://github.com/sindresorhus/type-fest/pull/303) - It's not solving a common need and is a better fit for a separate package.
- [`ExtendOr` and `ExtendAnd`](https://github.com/sindresorhus/type-fest/pull/247) - The benefits don't outweigh having to learn what they mean.
- [`PackageJsonExtras`](https://github.com/sindresorhus/type-fest/issues/371) - There are too many possible configurations that can be put into `package.json`. If you would like to extend `PackageJson` to support an additional configuration in your project, please see the *Extending existing types* section below.

## Alternative type names

*If you know one of our types by a different name, add it here for discovery.*

- `PartialBy` - See [`SetOptional`](https://github.com/sindresorhus/type-fest/blob/main/source/set-optional.d.ts)
- `RecordDeep`- See [`Schema`](https://github.com/sindresorhus/type-fest/blob/main/source/schema.d.ts)

## Tips

### Extending existing types

- [`PackageJson`](source/package-json.d.ts) - There are a lot of tools that place extra configurations inside the `package.json` file. You can extend `PackageJson` to support these additional configurations.
	<details>
	<summary>
			Example
	</summary>

	[Playground](https://www.typescriptlang.org/play?#code/JYWwDg9gTgLgBDAnmApnA3gBQIYGMDW2A5igFIDOEAdnNuXAEJ0o4HFmVUC+cAZlBBBwA5ElQBaXinIxhAbgCwAKFCRYCZGnQAZYFRgooPfoJHSANntmKlysWlaESFanAC8jZo-YuaAMgwLKwBhal5gIgB+AC44XX1DADpQqnCiLhsgA)

	```ts
	import type {PackageJson as BasePackageJson} from 'type-fest';
	import type {Linter} from 'eslint';

	type PackageJson = BasePackageJson & {eslintConfig?: Linter.Config};
	```
	</details>

### Related

- [typed-query-selector](https://github.com/g-plane/typed-query-selector) - Enhances `document.querySelector` and `document.querySelectorAll` with a template literal type that matches element types returned from an HTML element query selector.
- [`Linter.Config`](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/eslint/index.d.ts) - Definitions for the [ESLint configuration schema](https://eslint.org/docs/user-guide/configuring/language-options).

### Built-in types

There are many advanced types most users don't know about.

- [`Partial<T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#partialtype) - Make all properties in `T` optional.
	<details>
	<summary>
			Example
	</summary>

	[Playground](https://www.typescriptlang.org/play/#code/JYOwLgpgTgZghgYwgAgHIHsAmEDC6QzADmyA3gLABQyycADnanALYQBcyAzmFKEQNxUaddFDAcQAV2YAjaIMoBfKlQQAbOJ05osEAIIMAQpOBrsUMkOR1eANziRkCfISKSoD4Pg4ZseAsTIALyW1DS0DEysHADkvvoMMQA0VsKi4sgAzAAMuVaKClY2wPaOknSYDrguADwA0sgQAB6QIJjaANYQAJ7oMDp+LsQAfAAUXd0cdUnI9mo+uv6uANp1ALoAlKHhyGAAFsCcAHTOAW4eYF4gyxNrwbNwago0ypRWp66jH8QcAApwYmAjxq8SWIy2FDCNDA3ToKFBQyIdR69wmfQG1TOhShyBgomQX3w3GQE2Q6IA8jIAFYQBBgI4TTiEs5bTQYsFInrLTbbHZOIlgZDlSqQABqj0kKBC3yINx6a2xfOQwH6o2FVXFaklwSCIUkbQghBAEEwENSfNOlykEGefNe5uhB2O6sgS3GPRmLogmslG1tLxUOKgEDA7hAuydtteryAA)

	```ts
	interface NodeConfig {
			appName: string;
			port: number;
	}

	class NodeAppBuilder {
			private configuration: NodeConfig = {
					appName: 'NodeApp',
					port: 3000
			};

			private updateConfig<Key extends keyof NodeConfig>(key: Key, value: NodeConfig[Key]) {
					this.configuration[key] = value;
			}

			config(config: Partial<NodeConfig>) {
					type NodeConfigKey = keyof NodeConfig;

					for (const key of Object.keys(config) as NodeConfigKey[]) {
							const updateValue = config[key];

							if (updateValue === undefined) {
									continue;
							}

							this.updateConfig(key, updateValue);
					}

					return this;
			}
	}

	// `Partial<NodeConfig>`` allows us to provide only a part of the
	// NodeConfig interface.
	new NodeAppBuilder().config({appName: 'ToDoApp'});
	```
	</details>

- [`Required<T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#requiredtype) - Make all properties in `T` required.
	<details>
	<summary>
			Example
	</summary>

	[Playground](https://typescript-play.js.org/?target=6#code/AQ4SwOwFwUwJwGYEMDGNgGED21VQGJZwC2wA3gFCjXAzFJgA2A-AFzADOUckA5gNxUaIYjA4ckvGG07c+g6gF8KQkAgCuEFFDA5O6gEbEwUbLm2ESwABQIixACJIoSdgCUYAR3Vg4MACYAPGYuFvYAfACU5Ko0APRxwADKMBD+wFAAFuh2Vv7OSBlYGdmc8ABu8LHKsRyGxqY4oQT21pTCIHQMjOwA5DAAHgACxAAOjDAAdChYxL0ANLHUouKSMH0AEmAAhJhY6ozpAJ77GTCMjMCiV0ToSAb7UJPPC9WRgrEJwAAqR6MwSRQPFGUFocDgRHYxnEfGAowh-zgUCOwF6KwkUl6tXqJhCeEsxDaS1AXSYfUGI3GUxmc0WSneQA)

	```ts
	interface ContactForm {
			email?: string;
			message?: string;
	}

	function submitContactForm(formData: Required<ContactForm>) {
			// Send the form data to the server.
	}

	submitContactForm({
			email: 'ex@mple.com',
			message: 'Hi! Could you tell me more about…',
	});

	// TypeScript error: missing property 'message'
	submitContactForm({
			email: 'ex@mple.com',
	});
	```
	</details>

- [`Readonly<T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#readonlytype) - Make all properties in `T` readonly.
	<details>
	<summary>
			Example
	</summary>

	[Playground](https://typescript-play.js.org/?target=6#code/AQ4UwOwVwW2AZA9gc3mAbmANsA3gKFCOAHkAzMgGkOJABEwAjKZa2kAUQCcvEu32AMQCGAF2FYBIAL4BufDRABLCKLBcywgMZgEKZOoDCiCGSXI8i4hGEwwALmABnUVxXJ57YFgzZHSVF8sT1BpBSItLGEnJz1kAy5LLy0TM2RHACUwYQATEywATwAeAITjU3MAPnkrCJMXLigtUT4AClxgGztKbyDgaX99I1TzAEokr1BRAAslJwA6FIqLAF48TtswHp9MHDla9hJGACswZvmyLjAwAC8wVpm5xZHkUZDaMKIwqyWXYCW0oN4sNlsA1h0ug5gAByACyBQAggAHJHQ7ZBIFoXbzBjMCz7OoQP5YIaJNYQMAAdziCVaALGNSIAHomcAACoFJFgADKWjcSNEwG4vC4ji0wggEEQguiTnMEGALWAV1yAFp8gVgEjeFyuKICvMrCTgVxnst5jtsGC4ljsPNhXxGaAWcAAOq6YRXYDCRg+RWIcA5JSC+kWdCepQ+v3RYCU3RInzRMCGwlpC19NYBW1Ye08R1AA)

	```ts
	enum LogLevel {
			Off,
			Debug,
			Error,
			Fatal
	};

	interface LoggerConfig {
			name: string;
			level: LogLevel;
	}

	class Logger {
			config: Readonly<LoggerConfig>;

			constructor({name, level}: LoggerConfig) {
					this.config = {name, level};
					Object.freeze(this.config);
			}
	}

	const config: LoggerConfig = {
		name: 'MyApp',
		level: LogLevel.Debug
	};

	const logger = new Logger(config);

	// TypeScript Error: cannot assign to read-only property.
	logger.config.level = LogLevel.Error;

	// We are able to edit config variable as we please.
	config.level = LogLevel.Error;
	```
	</details>

- [`Pick<T, K>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#picktype-keys) - From `T`, pick a set of properties whose keys are in the union `K`.
	<details>
	<summary>
			Example
	</summary>

	[Playground](https://typescript-play.js.org/?target=6#code/AQ4SwOwFwUwJwGYEMDGNgEE5TCgNugN4BQoZwOUBAXMAM5RyQDmA3KeSFABYCuAtgCMISMHloMmENh04oA9tBjQJjFuzIBfYrOAB6PcADCcGElh1gEGAHcKATwAO6ebyjB5CTNlwFwSxFR0BX5HeToYABNgBDh5fm8cfBg6AHIKG3ldA2BHOOcfFNpUygJ0pAhokr4hETFUgDpswywkggAFUwA3MFtgAF5gQgowKhhVKTYKGuFRcXo1aVZgbTIoJ3RW3xhOmB6+wfbcAGsAHi3kgBpgEtGy4AAfG54BWfqAPnZm4AAlZUj4MAkMA8GAGB4vEgfMlLLw6CwPBA8PYRmMgZVgAC6CgmI4cIommQELwICh8RBgKZKvALh1ur0bHQABR5PYMui0Wk7em2ADaAF0AJS0AASABUALIAGQAogR+Mp3CROCAFBBwVC2ikBpj5CgBIqGjizLA5TAFdAmalImAuqlBRoVQh5HBgEy1eDWfs7J5cjzGYKhroVfpDEhHM4MV6GRR5NN0JrtnRg6BVirTFBeHAKYmYY6QNpdB73LmCJZBlSAXAubtvczeSmQMNSuMbmKNgBlHFgPEUNwusBIPAAQlS1xetTmxT0SDoESgdD0C4aACtHMwxytLrohawgA)

	```ts
	interface Article {
			title: string;
			thumbnail: string;
			content: string;
	}

	// Creates new type out of the `Article` interface composed
	// from the Articles' two properties: `title` and `thumbnail`.
	// `ArticlePreview = {title: string; thumbnail: string}`
	type ArticlePreview = Pick<Article, 'title' | 'thumbnail'>;

	// Render a list of articles using only title and description.
	function renderArticlePreviews(previews: ArticlePreview[]): HTMLElement {
			const articles = document.createElement('div');

			for (const preview of previews) {
					// Append preview to the articles.
			}

			return articles;
	}

	const articles = renderArticlePreviews([
			{
				title: 'TypeScript tutorial!',
				thumbnail: '/assets/ts.jpg'
			}
	]);
	```
	</details>

- [`Record<K, T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type) - Construct a type with a set of properties `K` of type `T`.
	<details>
	<summary>
			Example
	</summary>

	[Playground](https://typescript-play.js.org/?target=6#code/AQ4ejYAUHsGcCWAXBMB2dgwGbAKYC2ADgDYwCeeemCaWArgE7ADGMxAhmuQHQBQoYEnJE8wALKEARnkaxEKdMAC8wAOS0kstGuAAfdQBM8ANzxlRjXQbVaWACwC0JPB0NqA3HwGgIwAJJoWozYHCxixnAsjAhStADmwESMMJYo1Fi4HMCIaPEu+MRklHj8gpqyoeHAAKJFFFTAAN4+giDYCIxwSAByHAR4AFw5SDF5Xm2gJBzdfQPD3WPxE5PAlBxdAPLYNQAelgh4aOHDaPQEMowrIAC+3oJ+AMKMrlrAXFhSAFZ4LEhC9g4-0BmA4JBISXgiCkBQABpILrJ5MhUGhYcATGD6Bk4Hh-jNgABrPDkOBlXyQAAq9ngYmJpOAAHcEOCRjAXqwYODfoo6DhakUSph+Uh7GI4P0xER4Cj0OSQGwMP8tP1hgAlX7swwAHgRl2RvIANALSA08ABtAC6AD4VM1Wm0Kow0MMrYaHYJjGYLLJXZb3at1HYnC43Go-QHQDcvA6-JsmEJXARgCDgMYWAhjIYhDAU+YiMAAFIwex0ZmilMITCGF79TLAGRsAgJYAAZRwSEZGzEABFTOZUrJ5Yn+jwnWgeER6HB7AAKJrADpdXqS4ZqYultTG6azVfqHswPBbtauLY7fayQ7HIbAAAMwBuAEoYw9IBq2Ixs9h2eFMOQYPQObALQKJgggABeYhghCIpikkKRpOQRIknAsZUiIeCttECBEP8NSMCkjDDAARMGziuIYxHwYOjDCMBmDNnAuTxA6irdCOBB1Lh5Dqpqn66tISIykawBnOCtqqC0gbjqc9DgpGkxegOliyfJDrRkAA)

	```ts
	// Positions of employees in our company.
	type MemberPosition = 'intern' | 'developer' | 'tech-lead';

	// Interface describing properties of a single employee.
	interface Employee {
			firstName: string;
			lastName: string;
			yearsOfExperience: number;
	}

	// Create an object that has all possible `MemberPosition` values set as keys.
	// Those keys will store a collection of Employees of the same position.
	const team: Record<MemberPosition, Employee[]> = {
			intern: [],
			developer: [],
			'tech-lead': [],
	};

	// Our team has decided to help John with his dream of becoming Software Developer.
	team.intern.push({
		firstName: 'John',
		lastName: 'Doe',
		yearsOfExperience: 0
	});

	// `Record` forces you to initialize all of the property keys.
	// TypeScript Error: "tech-lead" property is missing
	const teamEmpty: Record<MemberPosition, null> = {
			intern: null,
			developer: null,
	};
	```
	</details>

- [`Exclude<T, U>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#excludetype-excludedunion) - Exclude from `T` those types that are assignable to `U`.
	<details>
	<summary>
			Example
	</summary>

	[Playground](https://typescript-play.js.org/?target=6#code/JYOwLgpgTgZghgYwgAgMrQG7QMIHsQzADmyA3gFDLIAOuUYAXMiAK4A2byAPsgM5hRQJHqwC2AI2gBucgF9y5MAE9qKAEoQAjiwj8AEnBAATNtGQBeZAAooWphu26wAGmS3e93bRC8IASgsAPmRDJRlyAHoI5ABRAA8ENhYjFFYOZGVVZBgoXFFkAAM0zh5+QRBhZhYJaAKAOkjogEkQZAQ4X2QAdwALCFbaemRgXmQtFjhOMFwq9K6ULuB0lk6U+HYwZAxJnQaYFhAEMGB8ZCIIMAAFOjAANR2IK0HGWISklIAedCgsKDwCYgAbQA5M9gQBdVzFQJ+JhiSRQMiUYYwayZCC4VHPCzmSzAspCYEBWxgFhQAZwKC+FpgJ43VwARgADH4ZFQSWSBjcZPJyPtDsdTvxKWBvr8rD1DCZoJ5HPopaYoK4EPhCEQmGKcKriLCtrhgEYkVQVT5Nr4fmZLLZtMBbFZgT0wGBqES6ghbHBIJqoBKFdBWQpjfh+DQbhY2tqiHVsbjLMVkAB+ZAAZiZaeQTHOVxu9ySjxNaujNwDVHNvzqbBGkBAdPoAfkQA)

	```ts
	interface ServerConfig {
		port: null | string | number;
	}

	type RequestHandler = (request: Request, response: Response) => void;

	// Exclude `null` type from `null | string | number`.
	// In case the port is equal to `null`, we will use default value.
	function getPortValue(port: Exclude<ServerConfig['port'], null>): number {
		if (typeof port === 'string') {
			return parseInt(port, 10);
		}

		return port;
	}

	function startServer(handler: RequestHandler, config: ServerConfig): void {
		const server = require('http').createServer(handler);

		const port = config.port === null ? 3000 : getPortValue(config.port);
		server.listen(port);
	}
	```
	</details>

- [`Extract<T, U>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#extracttype-union) - Extract from `T` those types that are assignable to `U`.
	<details>
	<summary>
			Example
	</summary>

	[Playground](https://typescript-play.js.org/?target=6#code/CYUwxgNghgTiAEAzArgOzAFwJYHtXzSwEdkQBJYACgEoAueVZAWwCMQYBuAKDDwGcM8MgBF4AXngBlAJ6scESgHIRi6ty5ZUGdoihgEABXZ888AN5d48ANoiAuvUat23K6ihMQ9ATE0BzV3goPy8GZjZOLgBfLi4Aejj4AEEICBwAdz54MAALKFQQ+BxEeAAHY1NgKAwoIKy0grr4DByEUpgccpgMaXgAaxBerCzi+B9-ZulygDouFHRsU1z8kKMYE1RhaqgAHkt4AHkWACt4EAAPbVRgLLWNgBp9gGlBs8uQa6yAUUuYPQwdgNpKM7nh7mMML4CgA+R5WABqUAgpDeVxuhxO1he0jsXGh8EoOBO9COx3BQPo2PBADckaR6IjkSA6PBqTgsMBzPsicdrEC7OJWXSQNwYvFEgAVTS9JLXODpeDpKBZFg4GCoWa8VACIJykAKiQWKy2YQOAioYikCg0OEMDyhRSy4DyxS24KhAAMjyi6gS8AAwjh5OD0iBFHAkJoEOksC1mnkMJq8gUQKDNttKPlnfrwYp3J5XfBHXqoKpfYkAOI4ansTxaeDADmoRSCCBYAbxhC6TDx6rwYHIRX5bScjA4bLJwoDmDwDkfbA9JMrVMVdM1TN69LgkTgwgkchUahqIA)

	```ts
	declare function uniqueId(): number;

	const ID = Symbol('ID');

	interface Person {
		[ID]: number;
		name: string;
		age: number;
	}

	// Allows changing the person data as long as the property key is of string type.
	function changePersonData<
		Obj extends Person,
		Key extends Extract<keyof Person, string>,
		Value extends Obj[Key]
	> (obj: Obj, key: Key, value: Value): void {
		obj[key] = value;
	}

	// Tiny Andrew was born.
	const andrew = {
		[ID]: uniqueId(),
		name: 'Andrew',
		age: 0,
	};

	// Cool, we're fine with that.
	changePersonData(andrew, 'name', 'Pony');

	// Goverment didn't like the fact that you wanted to change your identity.
	changePersonData(andrew, ID, uniqueId());
	```
	</details>

- [`NonNullable<T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#nonnullabletype) - Exclude `null` and `undefined` from `T`.
	<details>
	<summary>
			Example
	</summary>
	Works with <a href="https://www.typescriptlang.org/tsconfig#strictNullChecks"><code>strictNullChecks</code></a> set to <code>true</code>.

	[Playground](https://typescript-play.js.org/?target=6#code/C4TwDgpgBACg9gJ2AOQK4FsBGEFQLxQDOwCAlgHYDmUAPlORtrnQwDasDcAUFwPQBU-WAEMkUOADMowqAGNWwwoSgATCBIqlgpOOSjAAFsOBRSy1IQgr9cKJlSlW1mZYQA3HFH68u8xcoBlHA8EACEHJ08Aby4oKDBUTFZSWXjEFEYcAEIALihkXTR2YSSIAB54JDQsHAA+blj4xOTUsHSACkMzPKD3HHDHNQQAGjSkPMqMmoQASh7g-oihqBi4uNIpdraxPAI2VhmVxrX9AzMAOm2ppnwoAA4ABifuE4BfKAhWSyOTuK7CS7pao3AhXF5rV48E4ICDAVAIPT-cGQyG+XTEIgLMJLTx7CAAdygvRCA0iCHaMwarhJOIQjUBSHaACJHk8mYdeLwxtdcVAAOSsh58+lXdr7Dlcq7A3n3J4PEUdADMcspUE53OluAIUGVTx46oAKuAIAFZGQwCYAKIIBCILjUxaDHAMnla+iodjcIA)

	```ts
	type PortNumber = string | number | null;

	/** Part of a class definition that is used to build a server */
	class ServerBuilder {
			portNumber!: NonNullable<PortNumber>;

			port(this: ServerBuilder, port: PortNumber): ServerBuilder {
					if (port == null) {
							this.portNumber = 8000;
					} else {
							this.portNumber = port;
					}

					return this;
			}
	}

	const serverBuilder = new ServerBuilder();

	serverBuilder
			.port('8000')   // portNumber = '8000'
			.port(null)     // portNumber =  8000
			.port(3000);    // portNumber =  3000

	// TypeScript error
	serverBuilder.portNumber = null;
	```
	</details>

- [`Parameters<T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#parameterstype) - Obtain the parameters of a function type in a tuple.
	<details>
	<summary>
			Example
	</summary>

	[Playground](https://typescript-play.js.org/?target=6#code/GYVwdgxgLglg9mABAZwBYmMANgUwBQxgAOIUAXIgIZgCeA2gLoCUFAbnDACaIDeAUIkQB6IYgCypSlBxUATrMo1ECsJzgBbLEoipqAc0J7EMKMgDkiHLnU4wp46pwAPHMgB0fAL58+oSLARECEosLAA5ABUYG2QAHgAxJGdpVWREPDdMylk9ZApqemZEAF4APipacrw-CApEgBogkKwAYThwckQwEHUAIxxZJl4BYVEImiIZKF0oZRwiWVdbeygJmThgOYgcGFYcbhqApCJsyhtpWXcR1cnEePBoeDAABVPzgbTixFeFd8uEsClADcIxGiygIFkSEOT3SmTc2VydQeRx+ZxwF2QQ34gkEwDgsnSuFmMBKiAADEDjIhYk1Qm0OlSYABqZnYka4xA1DJZHJYkGc7yCbyeRA+CAIZCzNAYbA4CIAdxg2zJwVCkWirjwMswuEaACYmCCgA)

	```ts
	function shuffle(input: any[]): void {
		// Mutate array randomly changing its' elements indexes.
	}

	function callNTimes<Fn extends (...args: any[]) => any> (func: Fn, callCount: number) {
		// Type that represents the type of the received function parameters.
		type FunctionParameters = Parameters<Fn>;

		return function (...args: FunctionParameters) {
			for (let i = 0; i < callCount; i++) {
				func(...args);
			}
		}
	}

	const shuffleTwice = callNTimes(shuffle, 2);
	```
	</details>

- [`ConstructorParameters<T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#constructorparameterstype) - Obtain the parameters of a constructor function type in a tuple.
	<details>
	<summary>
			Example
	</summary>

	[Playground](https://typescript-play.js.org/?target=6#code/MYGwhgzhAECCBOAXAlqApgWQPYBM0mgG8AoaaFRENALmgkXmQDsBzAblOmCycTV4D8teo1YdO3JiICuwRFngAKClWENmLAJRFOZRAAtkEAHQq00ALzlklNBzIBfYk+KhIMAJJTEYJsDQAwmDA+mgAPAAq0GgAHnxMODCKTGgA7tCKxllg8CwQtL4AngDaALraFgB80EWa1SRkAA6MAG5gfNAB4FABPDJyCrQR9tDNyG0dwMGhtBhgjWEiGgA00F70vv4RhY3hEZXVVinpc42KmuJkkv3y8Bly8EPaDWTkhiZd7r3e8LK3llwGCMXGQWGhEOsfH5zJlsrl8p0+gw-goAAo5MAAW3BaHgEEilU0tEhmzQ212BJ0ry4SOg+kg+gBBiMximIGA0nAfAQLGk2N4EAAEgzYcYcnkLsRdDTvNEYkYUKwSdCme9WdM0MYwYhFPSIPpJdTkAAzDKxBUaZX+aAAQgsVmkCTQxuYaBw2ng4Ok8CYcotSu8pMur09iG9vuObxZnx6SN+AyUWTF8MN0CcZE4Ywm5jZHK5aB5fP4iCFIqT4oRRTKRLo6lYVNeAHpG50wOzOe1zHr9NLQ+HoABybsD4HOKXXRA1JCoKhBELmI5pNaB6Fz0KKBAodDYPAgSUTmqYsAALx4m5nC6nW9nGq14KtaEUA9gR9PvuNCjQ9BgACNvcwNBtAcLiAA)

	```ts
	class ArticleModel {
		title: string;
		content?: string;

		constructor(title: string) {
			this.title = title;
		}
	}

	class InstanceCache<T extends (new (...args: any[]) => any)> {
		private ClassConstructor: T;
		private cache: Map<string, InstanceType<T>> = new Map();

		constructor (ctr: T) {
			this.ClassConstructor = ctr;
		}

		getInstance (...args: ConstructorParameters<T>): InstanceType<T> {
			const hash = this.calculateArgumentsHash(...args);

			const existingInstance = this.cache.get(hash);
			if (existingInstance !== undefined) {
				return existingInstance;
			}

			return new this.ClassConstructor(...args);
		}

		private calculateArgumentsHash(...args: any[]): string {
			// Calculate hash.
			return 'hash';
		}
	}

	const articleCache = new InstanceCache(ArticleModel);
	const amazonArticle = articleCache.getInstance('Amazon forests burining!');
	```
	</details>

- [`ReturnType<T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#returntypetype) - Obtain the return type of a function type.
	<details>
	<summary>
			Example
	</summary>

	[Playground](https://typescript-play.js.org/?target=6#code/MYGwhgzhAECSAmICmBlJAnAbgS2E6A3gFDTTwD2AcuQC4AW2AdgOYAUAlAFzSbnbyEAvkWFFQkGJSQB3GMVI1sNZNwg10TZgG4S0YOUY0kh1es07d+xmvQBXYDXLpWi5UlMaWAGj0GjJ6BtNdkJdBQYIADpXZGgAXmgYpB1ScOwoq38aeN9DYxoU6GFRKzVoJjUwRjwAYXJbPPRuAFkwAAcAHgAxBodsAx9GWwBbACMMAD4cxhloVraOCyYjdAAzMDxoOut1e0d0UNIZ6WhWSPOwdGYIbiqATwBtAF0uaHudUQB6ACpv6ABpJBINqJdAbADW0Do5BOw3u5R2VTwMHIq2gAANtjZ0bkbHsnFCwJh8ONjHp0EgwEZ4JFoN9PkRVr1FAZoMwkDRYIjqkgOrosepoEgAB7+eAwAV2BxOLy6ACCVxgIrFEoMeOl6AACpcwMMORgIB1JRMiBNWKVdhruJKfOdIpdrtwFddXlzKjyACp3Nq842HaDIbL6BrZBIVGhIpB1EMYSLsmjmtWW-YhAA+qegAAYLKQLQj3ZsEsdccmnGcLor2Dn8xGedHGpEIBzEzspfsfMHDNAANTQACMVaIljV5GQkRA5DYmIpVKQAgAJARO9le33BDXIyi0YuLW2nJFGLqkOvxFB0YPdBSaLZ0IwNzyPkO8-xkGgsLh8Al427a3hWAhXwwHA8EHT5PmgAB1bAQBAANJ24adKWpft72RaBUTgRBUCAj89HAM8xCTaBjggABRQx0DuHJv25P9dCkWRZVIAAiBjoFImpmjlFBgA0NpsjadByDacgIDAEAIAAQmYpjoGYgAZSBsmGPw6DtZiiFA8CoJguDmAQmoZ2QvtUKQLdoAYmBTwgdEiCAA)

	```ts
	/** Provides every element of the iterable `iter` into the `callback` function and stores the results in an array. */
	function mapIter<
			Elem,
			Func extends (elem: Elem) => any,
			Ret extends ReturnType<Func>
	>(iter: Iterable<Elem>, callback: Func): Ret[] {
			const mapped: Ret[] = [];

			for (const elem of iter) {
					mapped.push(callback(elem));
			}

			return mapped;
	}

	const setObject: Set<string> = new Set();
	const mapObject: Map<number, string> = new Map();

	mapIter(setObject, (value: string) => value.indexOf('Foo')); // number[]

	mapIter(mapObject, ([key, value]: [number, string]) => {
			return key % 2 === 0 ? value : 'Odd';
	}); // string[]
	```
	</details>

- [`InstanceType<T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#instancetypetype) - Obtain the instance type of a constructor function type.
	<details>
	<summary>
			Example
	</summary>

	[Playground](https://typescript-play.js.org/?target=6#code/MYGwhgzhAECSAmICmBlJAnAbgS2E6A3gFDTTwD2AcuQC4AW2AdgOYAUAlAFzSbnbyEAvkWFFQkGJSQB3GMVI1sNZNwg10TZgG4S0YOUY0kh1es07d+xmvQBXYDXLpWi5UlMaWAGj0GjJ6BtNdkJdBQYIADpXZGgAXmgYpB1ScOwoq38aeN9DYxoU6GFRKzVoJjUwRjwAYXJbPPRuAFkwAAcAHgAxBodsAx9GWwBbACMMAD4cxhloVraOCyYjdAAzMDxoOut1e0d0UNIZ6WhWSPOwdGYIbiqATwBtAF0uaHudUQB6ACpv6ABpJBINqJdAbADW0Do5BOw3u5R2VTwMHIq2gAANtjZ0bkbHsnFCwJh8ONjHp0EgwEZ4JFoN9PkRVr1FAZoMwkDRYIjqkgOrosepoEgAB7+eAwAV2BxOLy6ACCVxgIrFEoMeOl6AACpcwMMORgIB1JRMiBNWKVdhruJKfOdIpdrtwFddXlzKjyACp3Nq842HaDIbL6BrZBIVGhIpB1EMYSLsmjmtWW-YhAA+qegAAYLKQLQj3ZsEsdccmnGcLor2Dn8xGedHGpEIBzEzspfsfMHDNAANTQACMVaIljV5GQkRA5DYmIpVKQAgAJARO9le33BDXIyi0YuLW2nJFGLqkOvxFB0YPdBSaLZ0IwNzyPkO8-xkGgsLh8Al427a3hWAhXwwHA8EHT5PmgAB1bAQBAANJ24adKWpft72RaBUTgRBUCAj89HAM8xCTaBjggABRQx0DuHJv25P9dCkWRZVIAAiBjoFImpmjlFBgA0NpsjadByDacgIDAEAIAAQmYpjoGYgAZSBsmGPw6DtZiiFA8CoJguDmAQmoZ2QvtUKQLdoAYmBTwgdEiCAA)

	```ts
	class IdleService {
			doNothing (): void {}
	}

	class News {
			title: string;
			content: string;

			constructor(title: string, content: string) {
					this.title = title;
					this.content = content;
			}
	}

	const instanceCounter: Map<Function, number> = new Map();

	interface Constructor {
			new(...args: any[]): any;
	}

	// Keep track how many instances of `Constr` constructor have been created.
	function getInstance<
			Constr extends Constructor,
			Args extends ConstructorParameters<Constr>
	>(constructor: Constr, ...args: Args): InstanceType<Constr> {
			let count = instanceCounter.get(constructor) || 0;

			const instance = new constructor(...args);

			instanceCounter.set(constructor, count + 1);

			console.log(`Created ${count + 1} instances of ${Constr.name} class`);

			return instance;
	}


	const idleService = getInstance(IdleService);
	// Will log: `Created 1 instances of IdleService class`
	const newsEntry = getInstance(News, 'New ECMAScript proposals!', 'Last month...');
	// Will log: `Created 1 instances of News class`
	```
	</details>

- [`Omit<T, K>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#omittype-keys) - Constructs a type by picking all properties from T and then removing K.
	<details>
	<summary>
			Example
	</summary>

	[Playground](https://typescript-play.js.org/?target=6#code/JYOwLgpgTgZghgYwgAgIImAWzgG2QbwChlks4BzCAVShwC5kBnMKUcgbmKYAcIFgIjBs1YgOXMpSFMWbANoBdTiW5woFddwAW0kfKWEAvoUIB6U8gDCUCHEiNkICAHdkYAJ69kz4GC3JcPG4oAHteKDABBxCYNAxsPFBIWEQUCAAPJG4wZABySUFcgJAAEzMLXNV1ck0dIuCw6EjBADpy5AB1FAQ4EGQAV0YUP2AHDy8wEOQbUugmBLwtEIA3OcmQnEjuZBgQqE7gAGtgZAhwKHdkHFGwNvGUdDIcAGUliIBJEF3kAF5kAHlML4ADyPBIAGjyBUYRQAPnkqho4NoYQA+TiEGD9EAISIhPozErQMG4AASK2gn2+AApek9pCSXm8wFSQooAJQMUkAFQAsgAZACiOAgmDOOSIJAQ+OYyGl4DgoDmf2QJRCCH6YvALQQNjsEGFovF1NyJWAy1y7OUyHMyE+yRAuFImG4Iq1YDswHxbRINjA-SgfXlHqVUE4xiAA)

	```ts
	interface Animal {
			imageUrl: string;
			species: string;
			images: string[];
			paragraphs: string[];
	}

	// Creates new type with all properties of the `Animal` interface
	// except 'images' and 'paragraphs' properties. We can use this
	// type to render small hover tooltip for a wiki entry list.
	type AnimalShortInfo = Omit<Animal, 'images' | 'paragraphs'>;

	function renderAnimalHoverInfo (animals: AnimalShortInfo[]): HTMLElement {
			const container = document.createElement('div');
			// Internal implementation.
			return container;
	}
	```
	</details>

- [`Uppercase<S extends string>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#uppercasestringtype) - Transforms every character in a string into uppercase.
	<details>
	<summary>
		Example
	</summary>

	```ts
	type T = Uppercase<'hello'>;  // 'HELLO'

	type T2 = Uppercase<'foo' | 'bar'>;  // 'FOO' | 'BAR'

	type T3<S extends string> = Uppercase<`aB${S}`>;
	type T4 = T3<'xYz'>;  // 'ABXYZ'

	type T5 = Uppercase<string>;  // string
	type T6 = Uppercase<any>;  // any
	type T7 = Uppercase<never>;  // never
	type T8 = Uppercase<42>;  // Error, type 'number' does not satisfy the constraint 'string'
	```
	</details>

- [`Lowercase<S extends string>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#lowercasestringtype) - Transforms every character in a string into lowercase.
	<details>
	<summary>
		Example
	</summary>

	```ts
	type T = Lowercase<'HELLO'>;  // 'hello'

	type T2 = Lowercase<'FOO' | 'BAR'>;  // 'foo' | 'bar'

	type T3<S extends string> = Lowercase<`aB${S}`>;
	type T4 = T3<'xYz'>;  // 'abxyz'

	type T5 = Lowercase<string>;  // string
	type T6 = Lowercase<any>;  // any
	type T7 = Lowercase<never>;  // never
	type T8 = Lowercase<42>;  // Error, type 'number' does not satisfy the constraint 'string'
	```
	</details>

- [`Capitalize<S extends string>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#capitalizestringtype) - Transforms the first character in a string into uppercase.
	<details>
	<summary>
		Example
	</summary>

	```ts
	type T = Capitalize<'hello'>;  // 'Hello'

	type T2 = Capitalize<'foo' | 'bar'>;  // 'Foo' | 'Bar'

	type T3<S extends string> = Capitalize<`aB${S}`>;
	type T4 = T3<'xYz'>;  // 'ABxYz'

	type T5 = Capitalize<string>;  // string
	type T6 = Capitalize<any>;  // any
	type T7 = Capitalize<never>;  // never
	type T8 = Capitalize<42>;  // Error, type 'number' does not satisfy the constraint 'string'
	```
	</details>

- [`Uncapitalize<S extends string>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#uncapitalizestringtype) - Transforms the first character in a string into lowercase.
	<details>
	<summary>
		Example
	</summary>

	```ts
	type T = Uncapitalize<'Hello'>;  // 'hello'

	type T2 = Uncapitalize<'Foo' | 'Bar'>;  // 'foo' | 'bar'

	type T3<S extends string> = Uncapitalize<`AB${S}`>;
	type T4 = T3<'xYz'>;  // 'aBxYz'

	type T5 = Uncapitalize<string>;  // string
	type T6 = Uncapitalize<any>;  // any
	type T7 = Uncapitalize<never>;  // never
	type T8 = Uncapitalize<42>;  // Error, type 'number' does not satisfy the constraint 'string'
	```
	</details>

You can find some examples in the [TypeScript docs](https://www.typescriptlang.org/docs/handbook/utility-types.html).

## Maintainers

- [Sindre Sorhus](https://github.com/sindresorhus)
- [Jarek Radosz](https://github.com/CvX)
- [Dimitri Benin](https://github.com/BendingBender)
- [Pelle Wessman](https://github.com/voxpelli)

## License

SPDX-License-Identifier: (MIT OR CC0-1.0)

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-type-fest?utm_source=npm-type-fest&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

1.6.18 / 2019-04-26
===================

  * Fix regression passing request object to `typeis.is`

1.6.17 / 2019-04-25
===================

  * deps: mime-types@~2.1.24
    - Add Apple file extensions from IANA
    - Add extension `.csl` to `application/vnd.citationstyles.style+xml`
    - Add extension `.es` to `application/ecmascript`
    - Add extension `.nq` to `application/n-quads`
    - Add extension `.nt` to `application/n-triples`
    - Add extension `.owl` to `application/rdf+xml`
    - Add extensions `.siv` and `.sieve` to `application/sieve`
    - Add extensions from IANA for `image/*` types
    - Add extensions from IANA for `model/*` types
    - Add extensions to HEIC image types
    - Add new mime types
    - Add `text/mdx` with extension `.mdx`
  * perf: prevent internal `throw` on invalid type

1.6.16 / 2018-02-16
===================

  * deps: mime-types@~2.1.18
    - Add `application/raml+yaml` with extension `.raml`
    - Add `application/wasm` with extension `.wasm`
    - Add `text/shex` with extension `.shex`
    - Add extensions for JPEG-2000 images
    - Add extensions from IANA for `message/*` types
    - Add extension `.mjs` to `application/javascript`
    - Add extension `.wadl` to `application/vnd.sun.wadl+xml`
    - Add extension `.gz` to `application/gzip`
    - Add glTF types and extensions
    - Add new mime types
    - Update extensions `.md` and `.markdown` to be `text/markdown`
    - Update font MIME types
    - Update `text/hjson` to registered `application/hjson`

1.6.15 / 2017-03-31
===================

  * deps: mime-types@~2.1.15
    - Add new mime types

1.6.14 / 2016-11-18
===================

  * deps: mime-types@~2.1.13
    - Add new mime types

1.6.13 / 2016-05-18
===================

  * deps: mime-types@~2.1.11
    - Add new mime types

1.6.12 / 2016-02-28
===================

  * deps: mime-types@~2.1.10
    - Add new mime types
    - Fix extension of `application/dash+xml`
    - Update primary extension for `audio/mp4`

1.6.11 / 2016-01-29
===================

  * deps: mime-types@~2.1.9
    - Add new mime types

1.6.10 / 2015-12-01
===================

  * deps: mime-types@~2.1.8
    - Add new mime types

1.6.9 / 2015-09-27
==================

  * deps: mime-types@~2.1.7
    - Add new mime types

1.6.8 / 2015-09-04
==================

  * deps: mime-types@~2.1.6
    - Add new mime types

1.6.7 / 2015-08-20
==================

  * Fix type error when given invalid type to match against
  * deps: mime-types@~2.1.5
    - Add new mime types

1.6.6 / 2015-07-31
==================

  * deps: mime-types@~2.1.4
    - Add new mime types

1.6.5 / 2015-07-16
==================

  * deps: mime-types@~2.1.3
    - Add new mime types

1.6.4 / 2015-07-01
==================

  * deps: mime-types@~2.1.2
    - Add new mime types
  * perf: enable strict mode
  * perf: remove argument reassignment

1.6.3 / 2015-06-08
==================

  * deps: mime-types@~2.1.1
    - Add new mime types
  * perf: reduce try block size
  * perf: remove bitwise operations

1.6.2 / 2015-05-10
==================

  * deps: mime-types@~2.0.11
    - Add new mime types

1.6.1 / 2015-03-13
==================

  * deps: mime-types@~2.0.10
    - Add new mime types

1.6.0 / 2015-02-12
==================

  * fix false-positives in `hasBody` `Transfer-Encoding` check
  * support wildcard for both type and subtype (`*/*`)

1.5.7 / 2015-02-09
==================

  * fix argument reassignment
  * deps: mime-types@~2.0.9
    - Add new mime types

1.5.6 / 2015-01-29
==================

  * deps: mime-types@~2.0.8
    - Add new mime types

1.5.5 / 2014-12-30
==================

  * deps: mime-types@~2.0.7
    - Add new mime types
    - Fix missing extensions
    - Fix various invalid MIME type entries
    - Remove example template MIME types
    - deps: mime-db@~1.5.0

1.5.4 / 2014-12-10
==================

  * deps: mime-types@~2.0.4
    - Add new mime types
    - deps: mime-db@~1.3.0

1.5.3 / 2014-11-09
==================

  * deps: mime-types@~2.0.3
    - Add new mime types
    - deps: mime-db@~1.2.0

1.5.2 / 2014-09-28
==================

  * deps: mime-types@~2.0.2
    - Add new mime types
    - deps: mime-db@~1.1.0

1.5.1 / 2014-09-07
==================

  * Support Node.js 0.6
  * deps: media-typer@0.3.0
  * deps: mime-types@~2.0.1
    - Support Node.js 0.6

1.5.0 / 2014-09-05
==================

 * fix `hasbody` to be true for `content-length: 0`

1.4.0 / 2014-09-02
==================

 * update mime-types

1.3.2 / 2014-06-24
==================

 * use `~` range on mime-types

1.3.1 / 2014-06-19
==================

 * fix global variable leak

1.3.0 / 2014-06-19
==================

 * improve type parsing

   - invalid media type never matches
   - media type not case-sensitive
   - extra LWS does not affect results

1.2.2 / 2014-06-19
==================

 * fix behavior on unknown type argument

1.2.1 / 2014-06-03
==================

 * switch dependency from `mime` to `mime-types@1.0.0`

1.2.0 / 2014-05-11
==================

 * support suffix matching:

   - `+json` matches `application/vnd+json`
   - `*/vnd+json` matches `application/vnd+json`
   - `application/*+json` matches `application/vnd+json`

1.1.0 / 2014-04-12
==================

 * add non-array values support
 * expose internal utilities:

   - `.is()`
   - `.hasBody()`
   - `.normalize()`
   - `.match()`

1.0.1 / 2014-03-30
==================

 * add `multipart` as a shorthand


---

# type-is

[![NPM Version][npm-version-image]][npm-url]
[![NPM Downloads][npm-downloads-image]][npm-url]
[![Node.js Version][node-version-image]][node-version-url]
[![Build Status][travis-image]][travis-url]
[![Test Coverage][coveralls-image]][coveralls-url]

Infer the content-type of a request.

### Install

This is a [Node.js](https://nodejs.org/en/) module available through the
[npm registry](https://www.npmjs.com/). Installation is done using the
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):

```sh
$ npm install type-is
```

## API

```js
var http = require('http')
var typeis = require('type-is')

http.createServer(function (req, res) {
  var istext = typeis(req, ['text/*'])
  res.end('you ' + (istext ? 'sent' : 'did not send') + ' me text')
})
```

### typeis(request, types)

Checks if the `request` is one of the `types`. If the request has no body,
even if there is a `Content-Type` header, then `null` is returned. If the
`Content-Type` header is invalid or does not matches any of the `types`, then
`false` is returned. Otherwise, a string of the type that matched is returned.

The `request` argument is expected to be a Node.js HTTP request. The `types`
argument is an array of type strings.

Each type in the `types` array can be one of the following:

- A file extension name such as `json`. This name will be returned if matched.
- A mime type such as `application/json`.
- A mime type with a wildcard such as `*/*` or `*/json` or `application/*`.
  The full mime type will be returned if matched.
- A suffix such as `+json`. This can be combined with a wildcard such as
  `*/vnd+json` or `application/*+json`. The full mime type will be returned
  if matched.

Some examples to illustrate the inputs and returned value:

<!-- eslint-disable no-undef -->

```js
// req.headers.content-type = 'application/json'

typeis(req, ['json']) // => 'json'
typeis(req, ['html', 'json']) // => 'json'
typeis(req, ['application/*']) // => 'application/json'
typeis(req, ['application/json']) // => 'application/json'

typeis(req, ['html']) // => false
```

### typeis.hasBody(request)

Returns a Boolean if the given `request` has a body, regardless of the
`Content-Type` header.

Having a body has no relation to how large the body is (it may be 0 bytes).
This is similar to how file existence works. If a body does exist, then this
indicates that there is data to read from the Node.js request stream.

<!-- eslint-disable no-undef -->

```js
if (typeis.hasBody(req)) {
  // read the body, since there is one

  req.on('data', function (chunk) {
    // ...
  })
}
```

### typeis.is(mediaType, types)

Checks if the `mediaType` is one of the `types`. If the `mediaType` is invalid
or does not matches any of the `types`, then `false` is returned. Otherwise, a
string of the type that matched is returned.

The `mediaType` argument is expected to be a
[media type](https://tools.ietf.org/html/rfc6838) string. The `types` argument
is an array of type strings.

Each type in the `types` array can be one of the following:

- A file extension name such as `json`. This name will be returned if matched.
- A mime type such as `application/json`.
- A mime type with a wildcard such as `*/*` or `*/json` or `application/*`.
  The full mime type will be returned if matched.
- A suffix such as `+json`. This can be combined with a wildcard such as
  `*/vnd+json` or `application/*+json`. The full mime type will be returned
  if matched.

Some examples to illustrate the inputs and returned value:

<!-- eslint-disable no-undef -->

```js
var mediaType = 'application/json'

typeis.is(mediaType, ['json']) // => 'json'
typeis.is(mediaType, ['html', 'json']) // => 'json'
typeis.is(mediaType, ['application/*']) // => 'application/json'
typeis.is(mediaType, ['application/json']) // => 'application/json'

typeis.is(mediaType, ['html']) // => false
```

## Examples

### Example body parser

```js
var express = require('express')
var typeis = require('type-is')

var app = express()

app.use(function bodyParser (req, res, next) {
  if (!typeis.hasBody(req)) {
    return next()
  }

  switch (typeis(req, ['urlencoded', 'json', 'multipart'])) {
    case 'urlencoded':
      // parse urlencoded body
      throw new Error('implement urlencoded body parsing')
    case 'json':
      // parse json body
      throw new Error('implement json body parsing')
    case 'multipart':
      // parse multipart body
      throw new Error('implement multipart body parsing')
    default:
      // 415 error code
      res.statusCode = 415
      res.end()
      break
  }
})
```

## License

[MIT](LICENSE)

[coveralls-image]: https://badgen.net/coveralls/c/github/jshttp/type-is/master
[coveralls-url]: https://coveralls.io/r/jshttp/type-is?branch=master
[node-version-image]: https://badgen.net/npm/node/type-is
[node-version-url]: https://nodejs.org/en/download
[npm-downloads-image]: https://badgen.net/npm/dm/type-is
[npm-url]: https://npmjs.org/package/type-is
[npm-version-image]: https://badgen.net/npm/v/type-is
[travis-image]: https://badgen.net/travis/jshttp/type-is/master
[travis-url]: https://travis-ci.org/jshttp/type-is


---

1.52.0 / 2022-02-21
===================

  * Add extensions from IANA for more `image/*` types
  * Add extension `.asc` to `application/pgp-keys`
  * Add extensions to various XML types
  * Add new upstream MIME types

1.51.0 / 2021-11-08
===================

  * Add new upstream MIME types
  * Mark `image/vnd.microsoft.icon` as compressible
  * Mark `image/vnd.ms-dds` as compressible

1.50.0 / 2021-09-15
===================

  * Add deprecated iWorks mime types and extensions
  * Add new upstream MIME types

1.49.0 / 2021-07-26
===================

  * Add extension `.trig` to `application/trig`
  * Add new upstream MIME types

1.48.0 / 2021-05-30
===================

  * Add extension `.mvt` to `application/vnd.mapbox-vector-tile`
  * Add new upstream MIME types
  * Mark `text/yaml` as compressible

1.47.0 / 2021-04-01
===================

  * Add new upstream MIME types
  * Remove ambigious extensions from IANA for `application/*+xml` types
  * Update primary extension to `.es` for `application/ecmascript`

1.46.0 / 2021-02-13
===================

  * Add extension `.amr` to `audio/amr`
  * Add extension `.m4s` to `video/iso.segment`
  * Add extension `.opus` to `audio/ogg`
  * Add new upstream MIME types

1.45.0 / 2020-09-22
===================

  * Add `application/ubjson` with extension `.ubj`
  * Add `image/avif` with extension `.avif`
  * Add `image/ktx2` with extension `.ktx2`
  * Add extension `.dbf` to `application/vnd.dbf`
  * Add extension `.rar` to `application/vnd.rar`
  * Add extension `.td` to `application/urc-targetdesc+xml`
  * Add new upstream MIME types
  * Fix extension of `application/vnd.apple.keynote` to be `.key`

1.44.0 / 2020-04-22
===================

  * Add charsets from IANA
  * Add extension `.cjs` to `application/node`
  * Add new upstream MIME types

1.43.0 / 2020-01-05
===================

  * Add `application/x-keepass2` with extension `.kdbx`
  * Add extension `.mxmf` to `audio/mobile-xmf`
  * Add extensions from IANA for `application/*+xml` types
  * Add new upstream MIME types

1.42.0 / 2019-09-25
===================

  * Add `image/vnd.ms-dds` with extension `.dds`
  * Add new upstream MIME types
  * Remove compressible from `multipart/mixed`

1.41.0 / 2019-08-30
===================

  * Add new upstream MIME types
  * Add `application/toml` with extension `.toml`
  * Mark `font/ttf` as compressible

1.40.0 / 2019-04-20
===================

  * Add extensions from IANA for `model/*` types
  * Add `text/mdx` with extension `.mdx`

1.39.0 / 2019-04-04
===================

  * Add extensions `.siv` and `.sieve` to `application/sieve`
  * Add new upstream MIME types

1.38.0 / 2019-02-04
===================

  * Add extension `.nq` to `application/n-quads`
  * Add extension `.nt` to `application/n-triples`
  * Add new upstream MIME types
  * Mark `text/less` as compressible

1.37.0 / 2018-10-19
===================

  * Add extensions to HEIC image types
  * Add new upstream MIME types

1.36.0 / 2018-08-20
===================

  * Add Apple file extensions from IANA
  * Add extensions from IANA for `image/*` types
  * Add new upstream MIME types

1.35.0 / 2018-07-15
===================

  * Add extension `.owl` to `application/rdf+xml`
  * Add new upstream MIME types
    - Removes extension `.woff` from `application/font-woff`

1.34.0 / 2018-06-03
===================

  * Add extension `.csl` to `application/vnd.citationstyles.style+xml`
  * Add extension `.es` to `application/ecmascript`
  * Add new upstream MIME types
  * Add `UTF-8` as default charset for `text/turtle`
  * Mark all XML-derived types as compressible

1.33.0 / 2018-02-15
===================

  * Add extensions from IANA for `message/*` types
  * Add new upstream MIME types
  * Fix some incorrect OOXML types
  * Remove `application/font-woff2`

1.32.0 / 2017-11-29
===================

  * Add new upstream MIME types
  * Update `text/hjson` to registered `application/hjson`
  * Add `text/shex` with extension `.shex`

1.31.0 / 2017-10-25
===================

  * Add `application/raml+yaml` with extension `.raml`
  * Add `application/wasm` with extension `.wasm`
  * Add new `font` type from IANA
  * Add new upstream font extensions
  * Add new upstream MIME types
  * Add extensions for JPEG-2000 images

1.30.0 / 2017-08-27
===================

  * Add `application/vnd.ms-outlook`
  * Add `application/x-arj`
  * Add extension `.mjs` to `application/javascript`
  * Add glTF types and extensions
  * Add new upstream MIME types
  * Add `text/x-org`
  * Add VirtualBox MIME types
  * Fix `source` records for `video/*` types that are IANA
  * Update `font/opentype` to registered `font/otf`

1.29.0 / 2017-07-10
===================

  * Add `application/fido.trusted-apps+json`
  * Add extension `.wadl` to `application/vnd.sun.wadl+xml`
  * Add new upstream MIME types
  * Add `UTF-8` as default charset for `text/css`

1.28.0 / 2017-05-14
===================

  * Add new upstream MIME types
  * Add extension `.gz` to `application/gzip`
  * Update extensions `.md` and `.markdown` to be `text/markdown`

1.27.0 / 2017-03-16
===================

  * Add new upstream MIME types
  * Add `image/apng` with extension `.apng`

1.26.0 / 2017-01-14
===================

  * Add new upstream MIME types
  * Add extension `.geojson` to `application/geo+json`

1.25.0 / 2016-11-11
===================

  * Add new upstream MIME types

1.24.0 / 2016-09-18
===================

  * Add `audio/mp3`
  * Add new upstream MIME types

1.23.0 / 2016-05-01
===================

  * Add new upstream MIME types
  * Add extension `.3gpp` to `audio/3gpp`

1.22.0 / 2016-02-15
===================

  * Add `text/slim`
  * Add extension `.rng` to `application/xml`
  * Add new upstream MIME types
  * Fix extension of `application/dash+xml` to be `.mpd`
  * Update primary extension to `.m4a` for `audio/mp4`

1.21.0 / 2016-01-06
===================

  * Add Google document types
  * Add new upstream MIME types

1.20.0 / 2015-11-10
===================

  * Add `text/x-suse-ymp`
  * Add new upstream MIME types

1.19.0 / 2015-09-17
===================

  * Add `application/vnd.apple.pkpass`
  * Add new upstream MIME types

1.18.0 / 2015-09-03
===================

  * Add new upstream MIME types

1.17.0 / 2015-08-13
===================

  * Add `application/x-msdos-program`
  * Add `audio/g711-0`
  * Add `image/vnd.mozilla.apng`
  * Add extension `.exe` to `application/x-msdos-program`

1.16.0 / 2015-07-29
===================

  * Add `application/vnd.uri-map`

1.15.0 / 2015-07-13
===================

  * Add `application/x-httpd-php`

1.14.0 / 2015-06-25
===================

  * Add `application/scim+json`
  * Add `application/vnd.3gpp.ussd+xml`
  * Add `application/vnd.biopax.rdf+xml`
  * Add `text/x-processing`

1.13.0 / 2015-06-07
===================

  * Add nginx as a source
  * Add `application/x-cocoa`
  * Add `application/x-java-archive-diff`
  * Add `application/x-makeself`
  * Add `application/x-perl`
  * Add `application/x-pilot`
  * Add `application/x-redhat-package-manager`
  * Add `application/x-sea`
  * Add `audio/x-m4a`
  * Add `audio/x-realaudio`
  * Add `image/x-jng`
  * Add `text/mathml`

1.12.0 / 2015-06-05
===================

  * Add `application/bdoc`
  * Add `application/vnd.hyperdrive+json`
  * Add `application/x-bdoc`
  * Add extension `.rtf` to `text/rtf`

1.11.0 / 2015-05-31
===================

  * Add `audio/wav`
  * Add `audio/wave`
  * Add extension `.litcoffee` to `text/coffeescript`
  * Add extension `.sfd-hdstx` to `application/vnd.hydrostatix.sof-data`
  * Add extension `.n-gage` to `application/vnd.nokia.n-gage.symbian.install`

1.10.0 / 2015-05-19
===================

  * Add `application/vnd.balsamiq.bmpr`
  * Add `application/vnd.microsoft.portable-executable`
  * Add `application/x-ns-proxy-autoconfig`

1.9.1 / 2015-04-19
==================

  * Remove `.json` extension from `application/manifest+json`
    - This is causing bugs downstream

1.9.0 / 2015-04-19
==================

  * Add `application/manifest+json`
  * Add `application/vnd.micro+json`
  * Add `image/vnd.zbrush.pcx`
  * Add `image/x-ms-bmp`

1.8.0 / 2015-03-13
==================

  * Add `application/vnd.citationstyles.style+xml`
  * Add `application/vnd.fastcopy-disk-image`
  * Add `application/vnd.gov.sk.xmldatacontainer+xml`
  * Add extension `.jsonld` to `application/ld+json`

1.7.0 / 2015-02-08
==================

  * Add `application/vnd.gerber`
  * Add `application/vnd.msa-disk-image`

1.6.1 / 2015-02-05
==================

  * Community extensions ownership transferred from `node-mime`

1.6.0 / 2015-01-29
==================

  * Add `application/jose`
  * Add `application/jose+json`
  * Add `application/json-seq`
  * Add `application/jwk+json`
  * Add `application/jwk-set+json`
  * Add `application/jwt`
  * Add `application/rdap+json`
  * Add `application/vnd.gov.sk.e-form+xml`
  * Add `application/vnd.ims.imsccv1p3`

1.5.0 / 2014-12-30
==================

  * Add `application/vnd.oracle.resource+json`
  * Fix various invalid MIME type entries
    - `application/mbox+xml`
    - `application/oscp-response`
    - `application/vwg-multiplexed`
    - `audio/g721`

1.4.0 / 2014-12-21
==================

  * Add `application/vnd.ims.imsccv1p2`
  * Fix various invalid MIME type entries
    - `application/vnd-acucobol`
    - `application/vnd-curl`
    - `application/vnd-dart`
    - `application/vnd-dxr`
    - `application/vnd-fdf`
    - `application/vnd-mif`
    - `application/vnd-sema`
    - `application/vnd-wap-wmlc`
    - `application/vnd.adobe.flash-movie`
    - `application/vnd.dece-zip`
    - `application/vnd.dvb_service`
    - `application/vnd.micrografx-igx`
    - `application/vnd.sealed-doc`
    - `application/vnd.sealed-eml`
    - `application/vnd.sealed-mht`
    - `application/vnd.sealed-ppt`
    - `application/vnd.sealed-tiff`
    - `application/vnd.sealed-xls`
    - `application/vnd.sealedmedia.softseal-html`
    - `application/vnd.sealedmedia.softseal-pdf`
    - `application/vnd.wap-slc`
    - `application/vnd.wap-wbxml`
    - `audio/vnd.sealedmedia.softseal-mpeg`
    - `image/vnd-djvu`
    - `image/vnd-svf`
    - `image/vnd-wap-wbmp`
    - `image/vnd.sealed-png`
    - `image/vnd.sealedmedia.softseal-gif`
    - `image/vnd.sealedmedia.softseal-jpg`
    - `model/vnd-dwf`
    - `model/vnd.parasolid.transmit-binary`
    - `model/vnd.parasolid.transmit-text`
    - `text/vnd-a`
    - `text/vnd-curl`
    - `text/vnd.wap-wml`
  * Remove example template MIME types
    - `application/example`
    - `audio/example`
    - `image/example`
    - `message/example`
    - `model/example`
    - `multipart/example`
    - `text/example`
    - `video/example`

1.3.1 / 2014-12-16
==================

  * Fix missing extensions
    - `application/json5`
    - `text/hjson`

1.3.0 / 2014-12-07
==================

  * Add `application/a2l`
  * Add `application/aml`
  * Add `application/atfx`
  * Add `application/atxml`
  * Add `application/cdfx+xml`
  * Add `application/dii`
  * Add `application/json5`
  * Add `application/lxf`
  * Add `application/mf4`
  * Add `application/vnd.apache.thrift.compact`
  * Add `application/vnd.apache.thrift.json`
  * Add `application/vnd.coffeescript`
  * Add `application/vnd.enphase.envoy`
  * Add `application/vnd.ims.imsccv1p1`
  * Add `text/csv-schema`
  * Add `text/hjson`
  * Add `text/markdown`
  * Add `text/yaml`

1.2.0 / 2014-11-09
==================

  * Add `application/cea`
  * Add `application/dit`
  * Add `application/vnd.gov.sk.e-form+zip`
  * Add `application/vnd.tmd.mediaflex.api+xml`
  * Type `application/epub+zip` is now IANA-registered

1.1.2 / 2014-10-23
==================

  * Rebuild database for `application/x-www-form-urlencoded` change

1.1.1 / 2014-10-20
==================

  * Mark `application/x-www-form-urlencoded` as compressible.

1.1.0 / 2014-09-28
==================

  * Add `application/font-woff2`

1.0.3 / 2014-09-25
==================

  * Fix engine requirement in package

1.0.2 / 2014-09-25
==================

  * Add `application/coap-group+json`
  * Add `application/dcd`
  * Add `application/vnd.apache.thrift.binary`
  * Add `image/vnd.tencent.tap`
  * Mark all JSON-derived types as compressible
  * Update `text/vtt` data

1.0.1 / 2014-08-30
==================

  * Fix extension ordering

1.0.0 / 2014-08-30
==================

  * Add `application/atf`
  * Add `application/merge-patch+json`
  * Add `multipart/x-mixed-replace`
  * Add `source: 'apache'` metadata
  * Add `source: 'iana'` metadata
  * Remove badly-assumed charset data


---

# mime-db

[![NPM Version][npm-version-image]][npm-url]
[![NPM Downloads][npm-downloads-image]][npm-url]
[![Node.js Version][node-image]][node-url]
[![Build Status][ci-image]][ci-url]
[![Coverage Status][coveralls-image]][coveralls-url]

This is a large database of mime types and information about them.
It consists of a single, public JSON file and does not include any logic,
allowing it to remain as un-opinionated as possible with an API.
It aggregates data from the following sources:

- http://www.iana.org/assignments/media-types/media-types.xhtml
- http://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/conf/mime.types
- http://hg.nginx.org/nginx/raw-file/default/conf/mime.types

## Installation

```bash
npm install mime-db
```

### Database Download

If you're crazy enough to use this in the browser, you can just grab the
JSON file using [jsDelivr](https://www.jsdelivr.com/). It is recommended to
replace `master` with [a release tag](https://github.com/jshttp/mime-db/tags)
as the JSON format may change in the future.

```
https://cdn.jsdelivr.net/gh/jshttp/mime-db@master/db.json
```

## Usage

```js
var db = require('mime-db')

// grab data on .js files
var data = db['application/javascript']
```

## Data Structure

The JSON file is a map lookup for lowercased mime types.
Each mime type has the following properties:

- `.source` - where the mime type is defined.
    If not set, it's probably a custom media type.
    - `apache` - [Apache common media types](http://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/conf/mime.types)
    - `iana` - [IANA-defined media types](http://www.iana.org/assignments/media-types/media-types.xhtml)
    - `nginx` - [nginx media types](http://hg.nginx.org/nginx/raw-file/default/conf/mime.types)
- `.extensions[]` - known extensions associated with this mime type.
- `.compressible` - whether a file of this type can be gzipped.
- `.charset` - the default charset associated with this type, if any.

If unknown, every property could be `undefined`.

## Contributing

To edit the database, only make PRs against `src/custom-types.json` or
`src/custom-suffix.json`.

The `src/custom-types.json` file is a JSON object with the MIME type as the
keys and the values being an object with the following keys:

- `compressible` - leave out if you don't know, otherwise `true`/`false` to
  indicate whether the data represented by the type is typically compressible.
- `extensions` - include an array of file extensions that are associated with
  the type.
- `notes` - human-readable notes about the type, typically what the type is.
- `sources` - include an array of URLs of where the MIME type and the associated
  extensions are sourced from. This needs to be a [primary source](https://en.wikipedia.org/wiki/Primary_source);
  links to type aggregating sites and Wikipedia are _not acceptable_.

To update the build, run `npm run build`.

### Adding Custom Media Types

The best way to get new media types included in this library is to register
them with the IANA. The community registration procedure is outlined in
[RFC 6838 section 5](http://tools.ietf.org/html/rfc6838#section-5). Types
registered with the IANA are automatically pulled into this library.

If that is not possible / feasible, they can be added directly here as a
"custom" type. To do this, it is required to have a primary source that
definitively lists the media type. If an extension is going to be listed as
associateed with this media type, the source must definitively link the
media type and extension as well.

[ci-image]: https://badgen.net/github/checks/jshttp/mime-db/master?label=ci
[ci-url]: https://github.com/jshttp/mime-db/actions?query=workflow%3Aci
[coveralls-image]: https://badgen.net/coveralls/c/github/jshttp/mime-db/master
[coveralls-url]: https://coveralls.io/r/jshttp/mime-db?branch=master
[node-image]: https://badgen.net/npm/node/mime-db
[node-url]: https://nodejs.org/en/download
[npm-downloads-image]: https://badgen.net/npm/dm/mime-db
[npm-url]: https://npmjs.org/package/mime-db
[npm-version-image]: https://badgen.net/npm/v/mime-db


---

2.1.35 / 2022-03-12
===================

  * deps: mime-db@1.52.0
    - Add extensions from IANA for more `image/*` types
    - Add extension `.asc` to `application/pgp-keys`
    - Add extensions to various XML types
    - Add new upstream MIME types

2.1.34 / 2021-11-08
===================

  * deps: mime-db@1.51.0
    - Add new upstream MIME types

2.1.33 / 2021-10-01
===================

  * deps: mime-db@1.50.0
    - Add deprecated iWorks mime types and extensions
    - Add new upstream MIME types

2.1.32 / 2021-07-27
===================

  * deps: mime-db@1.49.0
    - Add extension `.trig` to `application/trig`
    - Add new upstream MIME types

2.1.31 / 2021-06-01
===================

  * deps: mime-db@1.48.0
    - Add extension `.mvt` to `application/vnd.mapbox-vector-tile`
    - Add new upstream MIME types

2.1.30 / 2021-04-02
===================

  * deps: mime-db@1.47.0
    - Add extension `.amr` to `audio/amr`
    - Remove ambigious extensions from IANA for `application/*+xml` types
    - Update primary extension to `.es` for `application/ecmascript`

2.1.29 / 2021-02-17
===================

  * deps: mime-db@1.46.0
    - Add extension `.amr` to `audio/amr`
    - Add extension `.m4s` to `video/iso.segment`
    - Add extension `.opus` to `audio/ogg`
    - Add new upstream MIME types

2.1.28 / 2021-01-01
===================

  * deps: mime-db@1.45.0
    - Add `application/ubjson` with extension `.ubj`
    - Add `image/avif` with extension `.avif`
    - Add `image/ktx2` with extension `.ktx2`
    - Add extension `.dbf` to `application/vnd.dbf`
    - Add extension `.rar` to `application/vnd.rar`
    - Add extension `.td` to `application/urc-targetdesc+xml`
    - Add new upstream MIME types
    - Fix extension of `application/vnd.apple.keynote` to be `.key`

2.1.27 / 2020-04-23
===================

  * deps: mime-db@1.44.0
    - Add charsets from IANA
    - Add extension `.cjs` to `application/node`
    - Add new upstream MIME types

2.1.26 / 2020-01-05
===================

  * deps: mime-db@1.43.0
    - Add `application/x-keepass2` with extension `.kdbx`
    - Add extension `.mxmf` to `audio/mobile-xmf`
    - Add extensions from IANA for `application/*+xml` types
    - Add new upstream MIME types

2.1.25 / 2019-11-12
===================

  * deps: mime-db@1.42.0
    - Add new upstream MIME types
    - Add `application/toml` with extension `.toml`
    - Add `image/vnd.ms-dds` with extension `.dds`

2.1.24 / 2019-04-20
===================

  * deps: mime-db@1.40.0
    - Add extensions from IANA for `model/*` types
    - Add `text/mdx` with extension `.mdx`

2.1.23 / 2019-04-17
===================

  * deps: mime-db@~1.39.0
    - Add extensions `.siv` and `.sieve` to `application/sieve`
    - Add new upstream MIME types

2.1.22 / 2019-02-14
===================

  * deps: mime-db@~1.38.0
    - Add extension `.nq` to `application/n-quads`
    - Add extension `.nt` to `application/n-triples`
    - Add new upstream MIME types

2.1.21 / 2018-10-19
===================

  * deps: mime-db@~1.37.0
    - Add extensions to HEIC image types
    - Add new upstream MIME types

2.1.20 / 2018-08-26
===================

  * deps: mime-db@~1.36.0
    - Add Apple file extensions from IANA
    - Add extensions from IANA for `image/*` types
    - Add new upstream MIME types

2.1.19 / 2018-07-17
===================

  * deps: mime-db@~1.35.0
    - Add extension `.csl` to `application/vnd.citationstyles.style+xml`
    - Add extension `.es` to `application/ecmascript`
    - Add extension `.owl` to `application/rdf+xml`
    - Add new upstream MIME types
    - Add UTF-8 as default charset for `text/turtle`

2.1.18 / 2018-02-16
===================

  * deps: mime-db@~1.33.0
    - Add `application/raml+yaml` with extension `.raml`
    - Add `application/wasm` with extension `.wasm`
    - Add `text/shex` with extension `.shex`
    - Add extensions for JPEG-2000 images
    - Add extensions from IANA for `message/*` types
    - Add new upstream MIME types
    - Update font MIME types
    - Update `text/hjson` to registered `application/hjson`

2.1.17 / 2017-09-01
===================

  * deps: mime-db@~1.30.0
    - Add `application/vnd.ms-outlook`
    - Add `application/x-arj`
    - Add extension `.mjs` to `application/javascript`
    - Add glTF types and extensions
    - Add new upstream MIME types
    - Add `text/x-org`
    - Add VirtualBox MIME types
    - Fix `source` records for `video/*` types that are IANA
    - Update `font/opentype` to registered `font/otf`

2.1.16 / 2017-07-24
===================

  * deps: mime-db@~1.29.0
    - Add `application/fido.trusted-apps+json`
    - Add extension `.wadl` to `application/vnd.sun.wadl+xml`
    - Add extension `.gz` to `application/gzip`
    - Add new upstream MIME types
    - Update extensions `.md` and `.markdown` to be `text/markdown`

2.1.15 / 2017-03-23
===================

  * deps: mime-db@~1.27.0
    - Add new mime types
    - Add `image/apng`

2.1.14 / 2017-01-14
===================

  * deps: mime-db@~1.26.0
    - Add new mime types

2.1.13 / 2016-11-18
===================

  * deps: mime-db@~1.25.0
    - Add new mime types

2.1.12 / 2016-09-18
===================

  * deps: mime-db@~1.24.0
    - Add new mime types
    - Add `audio/mp3`

2.1.11 / 2016-05-01
===================

  * deps: mime-db@~1.23.0
    - Add new mime types

2.1.10 / 2016-02-15
===================

  * deps: mime-db@~1.22.0
    - Add new mime types
    - Fix extension of `application/dash+xml`
    - Update primary extension for `audio/mp4`

2.1.9 / 2016-01-06
==================

  * deps: mime-db@~1.21.0
    - Add new mime types

2.1.8 / 2015-11-30
==================

  * deps: mime-db@~1.20.0
    - Add new mime types

2.1.7 / 2015-09-20
==================

  * deps: mime-db@~1.19.0
    - Add new mime types

2.1.6 / 2015-09-03
==================

  * deps: mime-db@~1.18.0
    - Add new mime types

2.1.5 / 2015-08-20
==================

  * deps: mime-db@~1.17.0
    - Add new mime types

2.1.4 / 2015-07-30
==================

  * deps: mime-db@~1.16.0
    - Add new mime types

2.1.3 / 2015-07-13
==================

  * deps: mime-db@~1.15.0
    - Add new mime types

2.1.2 / 2015-06-25
==================

  * deps: mime-db@~1.14.0
    - Add new mime types

2.1.1 / 2015-06-08
==================

  * perf: fix deopt during mapping

2.1.0 / 2015-06-07
==================

  * Fix incorrectly treating extension-less file name as extension
    - i.e. `'path/to/json'` will no longer return `application/json`
  * Fix `.charset(type)` to accept parameters
  * Fix `.charset(type)` to match case-insensitive
  * Improve generation of extension to MIME mapping
  * Refactor internals for readability and no argument reassignment
  * Prefer `application/*` MIME types from the same source
  * Prefer any type over `application/octet-stream`
  * deps: mime-db@~1.13.0
    - Add nginx as a source
    - Add new mime types

2.0.14 / 2015-06-06
===================

  * deps: mime-db@~1.12.0
    - Add new mime types

2.0.13 / 2015-05-31
===================

  * deps: mime-db@~1.11.0
    - Add new mime types

2.0.12 / 2015-05-19
===================

  * deps: mime-db@~1.10.0
    - Add new mime types

2.0.11 / 2015-05-05
===================

  * deps: mime-db@~1.9.1
    - Add new mime types

2.0.10 / 2015-03-13
===================

  * deps: mime-db@~1.8.0
    - Add new mime types

2.0.9 / 2015-02-09
==================

  * deps: mime-db@~1.7.0
    - Add new mime types
    - Community extensions ownership transferred from `node-mime`

2.0.8 / 2015-01-29
==================

  * deps: mime-db@~1.6.0
    - Add new mime types

2.0.7 / 2014-12-30
==================

  * deps: mime-db@~1.5.0
    - Add new mime types
    - Fix various invalid MIME type entries

2.0.6 / 2014-12-30
==================

  * deps: mime-db@~1.4.0
    - Add new mime types
    - Fix various invalid MIME type entries
    - Remove example template MIME types

2.0.5 / 2014-12-29
==================

  * deps: mime-db@~1.3.1
    - Fix missing extensions

2.0.4 / 2014-12-10
==================

  * deps: mime-db@~1.3.0
    - Add new mime types

2.0.3 / 2014-11-09
==================

  * deps: mime-db@~1.2.0
    - Add new mime types

2.0.2 / 2014-09-28
==================

  * deps: mime-db@~1.1.0
    - Add new mime types
    - Update charsets

2.0.1 / 2014-09-07
==================

  * Support Node.js 0.6

2.0.0 / 2014-09-02
==================

  * Use `mime-db`
  * Remove `.define()`

1.0.2 / 2014-08-04
==================

  * Set charset=utf-8 for `text/javascript`

1.0.1 / 2014-06-24
==================

  * Add `text/jsx` type

1.0.0 / 2014-05-12
==================

  * Return `false` for unknown types
  * Set charset=utf-8 for `application/json`

0.1.0 / 2014-05-02
==================

  * Initial release


---

# mime-types

[![NPM Version][npm-version-image]][npm-url]
[![NPM Downloads][npm-downloads-image]][npm-url]
[![Node.js Version][node-version-image]][node-version-url]
[![Build Status][ci-image]][ci-url]
[![Test Coverage][coveralls-image]][coveralls-url]

The ultimate javascript content-type utility.

Similar to [the `mime@1.x` module](https://www.npmjs.com/package/mime), except:

- __No fallbacks.__ Instead of naively returning the first available type,
  `mime-types` simply returns `false`, so do
  `var type = mime.lookup('unrecognized') || 'application/octet-stream'`.
- No `new Mime()` business, so you could do `var lookup = require('mime-types').lookup`.
- No `.define()` functionality
- Bug fixes for `.lookup(path)`

Otherwise, the API is compatible with `mime` 1.x.

## Install

This is a [Node.js](https://nodejs.org/en/) module available through the
[npm registry](https://www.npmjs.com/). Installation is done using the
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):

```sh
$ npm install mime-types
```

## Adding Types

All mime types are based on [mime-db](https://www.npmjs.com/package/mime-db),
so open a PR there if you'd like to add mime types.

## API

```js
var mime = require('mime-types')
```

All functions return `false` if input is invalid or not found.

### mime.lookup(path)

Lookup the content-type associated with a file.

```js
mime.lookup('json') // 'application/json'
mime.lookup('.md') // 'text/markdown'
mime.lookup('file.html') // 'text/html'
mime.lookup('folder/file.js') // 'application/javascript'
mime.lookup('folder/.htaccess') // false

mime.lookup('cats') // false
```

### mime.contentType(type)

Create a full content-type header given a content-type or extension.
When given an extension, `mime.lookup` is used to get the matching
content-type, otherwise the given content-type is used. Then if the
content-type does not already have a `charset` parameter, `mime.charset`
is used to get the default charset and add to the returned content-type.

```js
mime.contentType('markdown') // 'text/x-markdown; charset=utf-8'
mime.contentType('file.json') // 'application/json; charset=utf-8'
mime.contentType('text/html') // 'text/html; charset=utf-8'
mime.contentType('text/html; charset=iso-8859-1') // 'text/html; charset=iso-8859-1'

// from a full path
mime.contentType(path.extname('/path/to/file.json')) // 'application/json; charset=utf-8'
```

### mime.extension(type)

Get the default extension for a content-type.

```js
mime.extension('application/octet-stream') // 'bin'
```

### mime.charset(type)

Lookup the implied default charset of a content-type.

```js
mime.charset('text/markdown') // 'UTF-8'
```

### var type = mime.types[extension]

A map of content-types by extension.

### [extensions...] = mime.extensions[type]

A map of extensions by content-type.

## License

[MIT](LICENSE)

[ci-image]: https://badgen.net/github/checks/jshttp/mime-types/master?label=ci
[ci-url]: https://github.com/jshttp/mime-types/actions/workflows/ci.yml
[coveralls-image]: https://badgen.net/coveralls/c/github/jshttp/mime-types/master
[coveralls-url]: https://coveralls.io/r/jshttp/mime-types?branch=master
[node-version-image]: https://badgen.net/npm/node/mime-types
[node-version-url]: https://nodejs.org/en/download
[npm-downloads-image]: https://badgen.net/npm/dm/mime-types
[npm-url]: https://npmjs.org/package/mime-types
[npm-version-image]: https://badgen.net/npm/v/mime-types


---

# typedarray-to-buffer [![travis][travis-image]][travis-url] [![npm][npm-image]][npm-url] [![downloads][downloads-image]][downloads-url] [![javascript style guide][standard-image]][standard-url]

[travis-image]: https://img.shields.io/travis/feross/typedarray-to-buffer/master.svg
[travis-url]: https://travis-ci.org/feross/typedarray-to-buffer
[npm-image]: https://img.shields.io/npm/v/typedarray-to-buffer.svg
[npm-url]: https://npmjs.org/package/typedarray-to-buffer
[downloads-image]: https://img.shields.io/npm/dm/typedarray-to-buffer.svg
[downloads-url]: https://npmjs.org/package/typedarray-to-buffer
[standard-image]: https://img.shields.io/badge/code_style-standard-brightgreen.svg
[standard-url]: https://standardjs.com

#### Convert a typed array to a [Buffer](https://github.com/feross/buffer) without a copy.

[![saucelabs][saucelabs-image]][saucelabs-url]

[saucelabs-image]: https://saucelabs.com/browser-matrix/typedarray-to-buffer.svg
[saucelabs-url]: https://saucelabs.com/u/typedarray-to-buffer

Say you're using the ['buffer'](https://github.com/feross/buffer) module on npm, or
[browserify](http://browserify.org/) and you're working with lots of binary data.

Unfortunately, sometimes the browser or someone else's API gives you a typed array like
`Uint8Array` to work with and you need to convert it to a `Buffer`. What do you do?

Of course: `Buffer.from(uint8array)`

But, alas, every time you do `Buffer.from(uint8array)` **the entire array gets copied**.
The `Buffer` constructor does a copy; this is
defined by the [node docs](http://nodejs.org/api/buffer.html) and the 'buffer' module
matches the node API exactly.

So, how can we avoid this expensive copy in
[performance critical applications](https://github.com/feross/buffer/issues/22)?

***Simply use this module, of course!***

If you have an `ArrayBuffer`, you don't need this module, because
`Buffer.from(arrayBuffer)`
[is already efficient](https://nodejs.org/api/buffer.html#buffer_class_method_buffer_from_arraybuffer_byteoffset_length).

## install

```bash
npm install typedarray-to-buffer
```

## usage

To convert a typed array to a `Buffer` **without a copy**, do this:

```js
var toBuffer = require('typedarray-to-buffer')

var arr = new Uint8Array([1, 2, 3])
arr = toBuffer(arr)

// arr is a buffer now!

arr.toString()  // '\u0001\u0002\u0003'
arr.readUInt16BE(0)  // 258
```

## how it works

If the browser supports typed arrays, then `toBuffer` will **augment the typed array** you
pass in with the `Buffer` methods and return it. See [how does Buffer
work?](https://github.com/feross/buffer#how-does-it-work) for more about how augmentation
works.

This module uses the typed array's underlying `ArrayBuffer` to back the new `Buffer`. This
respects the "view" on the `ArrayBuffer`, i.e. `byteOffset` and `byteLength`. In other
words, if you do `toBuffer(new Uint32Array([1, 2, 3]))`, then the new `Buffer` will
contain `[1, 0, 0, 0, 2, 0, 0, 0, 3, 0, 0, 0]`, **not** `[1, 2, 3]`. And it still doesn't
require a copy.

If the browser doesn't support typed arrays, then `toBuffer` will create a new `Buffer`
object, copy the data into it, and return it. There's no simple performance optimization
we can do for old browsers. Oh well.

If this module is used in node, then it will just call `Buffer.from`. This is just for
the convenience of modules that work in both node and the browser.

## license

MIT. Copyright (C) [Feross Aboukhadijeh](http://feross.org).


---


# TypeScript

[![CI](https://github.com/microsoft/TypeScript/actions/workflows/ci.yml/badge.svg)](https://github.com/microsoft/TypeScript/actions/workflows/ci.yml)
[![npm version](https://badge.fury.io/js/typescript.svg)](https://www.npmjs.com/package/typescript)
[![Downloads](https://img.shields.io/npm/dm/typescript.svg)](https://www.npmjs.com/package/typescript)
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/microsoft/TypeScript/badge)](https://securityscorecards.dev/viewer/?uri=github.com/microsoft/TypeScript)


[TypeScript](https://www.typescriptlang.org/) is a language for application-scale JavaScript. TypeScript adds optional types to JavaScript that support tools for large-scale JavaScript applications for any browser, for any host, on any OS. TypeScript compiles to readable, standards-based JavaScript. Try it out at the [playground](https://www.typescriptlang.org/play/), and stay up to date via [our blog](https://blogs.msdn.microsoft.com/typescript) and [Twitter account](https://twitter.com/typescript).

Find others who are using TypeScript at [our community page](https://www.typescriptlang.org/community/).

## Installing

For the latest stable version:

```bash
npm install -D typescript
```

For our nightly builds:

```bash
npm install -D typescript@next
```

## Contribute

There are many ways to [contribute](https://github.com/microsoft/TypeScript/blob/main/CONTRIBUTING.md) to TypeScript.
* [Submit bugs](https://github.com/microsoft/TypeScript/issues) and help us verify fixes as they are checked in.
* Review the [source code changes](https://github.com/microsoft/TypeScript/pulls).
* Engage with other TypeScript users and developers on [StackOverflow](https://stackoverflow.com/questions/tagged/typescript).
* Help each other in the [TypeScript Community Discord](https://discord.gg/typescript).
* Join the [#typescript](https://twitter.com/search?q=%23TypeScript) discussion on Twitter.
* [Contribute bug fixes](https://github.com/microsoft/TypeScript/blob/main/CONTRIBUTING.md).

This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see
the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com)
with any additional questions or comments.

## Documentation

*  [TypeScript in 5 minutes](https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes.html)
*  [Programming handbook](https://www.typescriptlang.org/docs/handbook/intro.html)
*  [Homepage](https://www.typescriptlang.org/)

## Roadmap

For details on our planned features and future direction, please refer to our [roadmap](https://github.com/microsoft/TypeScript/wiki/Roadmap).


---

<!-- BEGIN MICROSOFT SECURITY.MD V0.0.9 BLOCK -->

## Security

Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include [Microsoft](https://github.com/Microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet) and [Xamarin](https://github.com/xamarin).

If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](https://aka.ms/security.md/definition), please report it to us as described below.

## Reporting Security Issues

**Please do not report security vulnerabilities through public GitHub issues.**

Instead, please report them to the Microsoft Security Response Center (MSRC) at [https://msrc.microsoft.com/create-report](https://aka.ms/security.md/msrc/create-report).

If you prefer to submit without logging in, send email to [secure@microsoft.com](mailto:secure@microsoft.com).  If possible, encrypt your message with our PGP key; please download it from the [Microsoft Security Response Center PGP Key page](https://aka.ms/security.md/msrc/pgp).

You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at [microsoft.com/msrc](https://www.microsoft.com/msrc). 

Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue:

  * Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.)
  * Full paths of source file(s) related to the manifestation of the issue
  * The location of the affected source code (tag/branch/commit or direct URL)
  * Any special configuration required to reproduce the issue
  * Step-by-step instructions to reproduce the issue
  * Proof-of-concept or exploit code (if possible)
  * Impact of the issue, including how an attacker might exploit the issue

This information will help us triage your report more quickly.

If you are reporting for a bug bounty, more complete reports can contribute to a higher bounty award. Please visit our [Microsoft Bug Bounty Program](https://aka.ms/security.md/msrc/bounty) page for more details about our active programs.

## Preferred Languages

We prefer all communications to be in English.

## Policy

Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://aka.ms/security.md/cvd).

<!-- END MICROSOFT SECURITY.MD BLOCK -->


---

# typesense-js [![NPM version][npm-image]][npm-url] ![downloads](https://img.shields.io/npm/dt/typesense?label=downloads)

Javascript client library for accessing the [Typesense HTTP API](https://github.com/typesense/typesense).

This library can be used both on the server-side and on the client-side. The library's [source](/src) is in ES6 and during build time, we transpile it to ES5 and generate two artifacts - [one](/lib) that can be used on the server-side and [another](/dist) that uses [Browserify](http://browserify.org/) and can be used on the client side.

## Installation

#### Option 1: Install via npm

```sh
npm install --save typesense
```

Install peer dependencies:
```sh
npm install --save @babel/runtime
```

Note: `@babel/runtime` is very a common dependency among many JS libraries. So instead of each library adding it as a dependency independently (which will cause multiple instances of `@babel/runtime` to be installed increasing bundle size), Babel's recommendation is that the libraries ask users to install it once as a direct dependency, so there's only one copy of `@babel/runtime` for the entire project. In some cases, your JS framework might already include `@babel/runtime` as a dependency.

#### Option 2: Include the minified JS file for use in the browser directly

```html
<script src="dist/typesense.min.js"></script>
```

or via jsDelivr

```html
<script src="https://cdn.jsdelivr.net/npm/typesense@1/dist/typesense.min.js"></script>
```

## Usage

Read the documentation here for detailed examples: [https://typesense.org/docs/api/](https://typesense.org/docs/api/)

Tests are also a good place to know how the library works internally: [test](test)

**Note: When using this library in a browser, please be sure to use an API Key that only allows search operations instead of the `master` API key.** See [doc/examples/server/keys.js](doc/examples/server/keys.js) for an example of how to generate a search only API key.

See [Configuration.ts](src/Typesense/Configuration.ts) for a list of all client configuration options.

### Examples

Here are some examples with inline comments that walk you through how to use the client: [doc/examples](doc/examples)

To run the examples, from the repo root:

```bash
npm run typesenseServer
node doc/examples/server/bulkImport.js
```

## GatsbyJS Integration

If you use [GatsbyJS](https://www.gatsbyjs.com/) for a framework, we have a plugin (that uses typesense-js behind the scenes) to automatically push your site data to Typesense when you build your site. Learn more [here](https://github.com/typesense/gatsby-plugin-typesense).

## Firebase Integration

If you use [Firebase](https://firebase.google.com/), we have a Firebase extension (that uses typesense-js behind the scenes) to automatically push your Firestore data to Typesense. Learn more [here](https://github.com/typesense/firestore-typesense-search).

## Building UI components

Checkout the [Typesense-InstantSearch.js](https://github.com/typesense/typesense-instantsearch-adapter) (which uses typesense-js) for UI components you can use to quickly build powerful instant search experiences.

## Compatibility

This table refers to server=>client compatibility. Newer versions of the client library maintain backwards compatibility with older versions of the server library.

| Typesense Server | typesense-js |
|------------------|--------------|
| \>= v0.26.0.rc38 | \>= v1.8.0   |
| \>= v0.25.0      | \>= v1.7.0   |
| \>= v0.24.0      | \>= v1.5.0   |
| \>= v0.23.0      | \>= v1.3.0   |
| \>= v0.21.0      | \>= v0.14.0  |
| \>= v0.20.0      | \>= v0.12.0  |
| \>= v0.19.0      | \>= v0.11.0  |
| \>= v0.18.0      | \>= v0.10.0  |
| \>= v0.17.0      | \>= v0.9.0   |
| \>= v0.16.0      | \>= v0.8.0   |
| \>= v0.15.0      | \>= v0.7.0   |
| \>= v0.12.1      | \>= v0.5.0   |
| \>= v0.12.0      | \>= v0.4.7   |
| <= v0.11         | <= v0.3.0    |

## Development

After checking out the repo, run `npm install` to install dependencies. Then run `npm test` to run the linter and tests.

To release a new version, we use the [np](https://github.com/sindresorhus/np) package:

```shell
$ npm install --global np
$ np

# Follow instructions that np shows you

```

## Contributing

Bug reports and pull requests are welcome on GitHub at [https://github.com/typesense/typesense-js](https://github.com/typesense/typesense-js).

[npm-image]: https://badge.fury.io/js/typesense.svg
[npm-url]: https://npmjs.org/package/typesense


---

# Typesense DocSearch Styles

This is a fork of Algolia's awesome [DocSearch.js](https://github.com/algolia/docsearch) library, customized to send queries to [Typesense](https://typesense.org).

This repo contains styles.

To be able to use this, you'd first need to setup and run the [Typesense DocSearch Scraper](https://github.com/typesense/typesense-docsearch-scraper).

#### What is Typesense?

If you're new to Typesense, it is an **open source** search engine that is simple to use, run and scale, with clean APIs and documentation.

Think of it as an open source alternative to Algolia and an easier-to-use, batteries-included alternative to ElasticSearch. Get a quick overview from [this guide](https://typesense.org/guide/).

## Usage

Read detailed step-by-step instructions on how to configure and setup this version of DocSearch.js on Typesense's dedicated documentation site: https://typesense.org/docs/latest/guide/docsearch.html.

## Help

If you have any questions or run into any problems, please create a Github issue and we'll try our best to help.


---

# Typesense Instantsearch Adapter

An adapter to use the awesome [Instantsearch.js](https://github.com/algolia/instantsearch.js) library with a [Typesense](https://typesense.org) Search Server, to build rich search interfaces.

[![NPM version][npm-image]][npm-url]
![downloads](https://img.shields.io/npm/dt/typesense-instantsearch-adapter?label=downloads)

Here is an example of UI you can build with this adapater: [songs-search.typesense.org](https://songs-search.typesense.org)

**Note:** If your search interface is built on a custom autocomplete component, or is based on [@algolia/autocomplete-js](https://www.algolia.com/doc/ui-libraries/autocomplete/introduction/what-is-autocomplete/), then you don't need this adapter to use it with Typesense, as [typesense-js](https://github.com/typesense/typesense-js) library already supports client-side fetching data from any async data sources. Read more [here](https://github.com/typesense/typesense-instantsearch-adapter/issues/88#issuecomment-1021597634).

## Quick Links

- [Background](#background)
- [Quick Start](#quick-start)
  - [Starter App](#starter-app)
- [Installation](#installation)
- [Usage](#usage)
  - [With instantsearch.js](#with-instantsearchjs)
  - [With react-instantsearch](#with-react-instantsearch) (also works with React Native)
  - [With vue-instantsearch](#with-vue-instantsearch)
  - [With angular-instantsearch](#with-angular-instantsearch)
- [Widget Specific Instructions](#widget-specific-instructions)
- [Caching](#caching)
- [Compatibility](#compatibility)
- [Development](#development)
- [Help](#help)

## Background

The good folks over at Algolia have built and open-sourced [Instantsearch.js](https://github.com/algolia/instantsearch.js) which is a collection of out-of-the-box components that you can use to build interactive search experiences swiftly.

With the adapter in this repository, you'll be able to use [Instantsearch](https://github.com/algolia/instantsearch.js) (and its [React](https://github.com/algolia/react-instantsearch), [Vue](https://github.com/algolia/vue-instantsearch) and [Angular](https://github.com/algolia/angular-instantsearch) cousins) with data indexed in a Typesense search server.

If you haven't used Instantsearch before, we recommend going through their Getting Started guide [here](https://www.algolia.com/doc/guides/building-search-ui/getting-started/js/#build-a-simple-ui).
Once you go through the guide, follow the instructions below to plug the Typesense adapter into Instantsearch.

## Quick Start

Here's a guide on building a quick search interface with Typesense and InstantSearch.js: [https://typesense.org/docs/0.20.0/guide/search-ui-components.html](https://typesense.org/docs/0.20.0/guide/search-ui-components.html)

### Starter App

Here's a demo starter app that shows you how to use the adapter: [https://github.com/typesense/typesense-instantsearch-demo](https://github.com/typesense/typesense-instantsearch-demo)

## Installation

```shell
$ npm install --save typesense-instantsearch-adapter @babel/runtime
```

or

```shell
$ yarn add typesense-instantsearch-adapter @babel/runtime
```

or, you can also directly include the adapter via a script tag in your HTML:

```html
<script src="https://cdn.jsdelivr.net/npm/typesense-instantsearch-adapter@2/dist/typesense-instantsearch-adapter.min.js"></script>

<!-- You might want to pin the version of the adapter used if you don't want to always receive the latest minor version -->
```

Since this is an adapter, it **will not install** the Instantsearch library automatically for you. You need to install one of the following in your application directly:

- [instantsearch.js](https://github.com/algolia/instantsearch.js)
- [react-instantsearch](https://github.com/algolia/react-instantsearch)
- [vue-instantsearch](https://github.com/algolia/vue-instantsearch)
- [angular-instantsearch](https://github.com/algolia/angular-instantsearch)

You'll find information on how to get started with each of the above libraries in their respective repos.

We'd also recommend checking out [create-instantsearch-app](https://github.com/algolia/create-instantsearch-app) to create your Search UI from a starter template.

## Usage

### With [instantsearch.js](https://github.com/algolia/instantsearch.js)

```javascript
import instantsearch from "instantsearch.js";
import { searchBox, hits } from "instantsearch.js/es/widgets";
import TypesenseInstantSearchAdapter from "typesense-instantsearch-adapter";

const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "abcd", // Be sure to use an API key that only allows search operations
    nodes: [
      {
        host: "localhost",
        path: "", // Optional. Example: If you have your typesense mounted in localhost:8108/typesense, path should be equal to '/typesense'
        port: "8108",
        protocol: "http",
      },
    ],
    cacheSearchResultsForSeconds: 2 * 60, // Cache search results from server. Defaults to 2 minutes. Set to 0 to disable caching.
  },
  // The following parameters are directly passed to Typesense's search API endpoint.
  //  So you can pass any parameters supported by the search endpoint below.
  //  query_by is required.
  additionalSearchParameters: {
    query_by: "name,description,categories",
  },
});
const searchClient = typesenseInstantsearchAdapter.searchClient;

const search = instantsearch({
  searchClient,
  indexName: "products",
});
search.addWidgets([
  searchBox({
    container: "#searchbox",
  }),
  hits({
    container: "#hits",
    templates: {
      item: `
        <div class="hit-name">
          {{#helpers.highlight}}{ "attribute": "name" }{{/helpers.highlight}}
        </div>
      `,
    },
  }),
]);

search.start();
```

You can add any of the Instantsearch widgets [here](https://www.algolia.com/doc/guides/building-search-ui/widgets/showcase/js/) that are [supported](#widget-compatibility) by the adapter.

You'll also find a working example in [test/support/testground](test/support/testground). To run it, run `npm run testground` from the project root folder.

### With [react-instantsearch](https://github.com/algolia/react-instantsearch)

```jsx harmony
import React from "react";
import ReactDOM from "react-dom";
import { SearchBox } from "react-instantsearch-dom";
import TypesenseInstantSearchAdapter from "typesense-instantsearch-adapter";

const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "abcd", // Be sure to use an API key that only allows search operations
    nodes: [
      {
        host: "localhost",
        port: "8108",
        path: "", // Optional. Example: If you have your typesense mounted in localhost:8108/typesense, path should be equal to '/typesense'
        protocol: "http",
      },
    ],
    cacheSearchResultsForSeconds: 2 * 60, // Cache search results from server. Defaults to 2 minutes. Set to 0 to disable caching.
  },
  // The following parameters are directly passed to Typesense's search API endpoint.
  //  So you can pass any parameters supported by the search endpoint below.
  //  query_by is required.
  additionalSearchParameters: {
    query_by: "name,description,categories",
  },
});
const searchClient = typesenseInstantsearchAdapter.searchClient;

const App = () => (
  <InstantSearch indexName="products" searchClient={searchClient}>
    <SearchBox />
    <Hits />
  </InstantSearch>
);
```

You can then add any of the Instantsearch-React widgets [here](https://www.algolia.com/doc/guides/building-search-ui/widgets/showcase/react/) that are [supported](#widget-compatibility) by the adapter.

The instructions above also apply to React Native.

### With [vue-instantsearch](https://github.com/algolia/vue-instantsearch)

App.vue:

```vue
<template>
  <ais-instant-search :search-client="searchClient" index-name="products">
    <ais-search-box />
    <ais-hits>
      <div slot="item" slot-scope="{ item }">
        <h2>{{ item.name }}</h2>
      </div>
    </ais-hits>
  </ais-instant-search>
</template>

<script>
import TypesenseInstantSearchAdapter from "typesense-instantsearch-adapter";

const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "abcd", // Be sure to use an API key that only allows search operations
    nodes: [
      {
        host: "localhost",
        path: "", // Optional. Example: If you have your typesense mounted in localhost:8108/typesense, path should be equal to '/typesense'
        port: "8108",
        protocol: "http",
      },
    ],
    cacheSearchResultsForSeconds: 2 * 60, // Cache search results from server. Defaults to 2 minutes. Set to 0 to disable caching.
  },
  // The following parameters are directly passed to Typesense's search API endpoint.
  //  So you can pass any parameters supported by the search endpoint below.
  //  query_by is required.
  additionalSearchParameters: {
    query_by: "name,description,categories",
  },
});
const searchClient = typesenseInstantsearchAdapter.searchClient;

export default {
  data() {
    return {
      searchClient,
    };
  },
};
</script>
```

You can then add any of the Instantsearch widgets [here](https://www.algolia.com/doc/guides/building-search-ui/widgets/showcase/vue/) that are [supported](#widget-compatibility) by the adapter.

### With [angular-instantsearch](https://github.com/algolia/angular-instantsearch)

```javascript
// app.component.ts
import { Component } from "@angular/core";
import TypesenseInstantSearchAdapter from "typesense-instantsearch-adapter";

const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "abcd", // Be sure to use an API key that only allows search operations
    nodes: [
      {
        host: "localhost",
        path: "", // Optional. Example: If you have your typesense mounted in localhost:8108/typesense, path should be equal to '/typesense'
        port: "8108",
        protocol: "http",
      },
    ],
    cacheSearchResultsForSeconds: 2 * 60, // Cache search results from server. Defaults to 2 minutes. Set to 0 to disable caching.
  },
  // The following parameters are directly passed to Typesense's search API endpoint.
  //  So you can pass any parameters supported by the search endpoint below.
  //  query_by is required.
  additionalSearchParameters: {
    query_by: "name,description,categories",
  },
});
const searchClient = typesenseInstantsearchAdapter.searchClient;

@Component({
  selector: "app-root",
  templateUrl: "./app.component.html",
  styleUrls: ["./app.component.css"],
})
export class AppComponent {
  config = {
    indexName: "products",
    searchClient,
  };
}
```

You can then add any of the Instantsearch widgets [here](https://www.algolia.com/doc/guides/building-search-ui/widgets/showcase/angular/) that are [supported](#widget-compatibility) by the adapter.

## Widget Specific Instructions

### `hierarchicalMenu`

For this widget, you want to create independent fields in the collection's schema with this specific naming convention:

- `field.lvl0`
- `field.lvl1`
- `field.lvl2`

for a nested hierarchy of `field.lvl0 > field.lvl1 > field.lvl2`

Each of these fields can also hold an array of values. This is useful for handling multiple hierarchies.

### `sortBy`

When instantiating this widget, you want to set the value of the index name to this particular format:

```javascript
search.addWidgets([
  sortBy({
    container: "#sort-by",
    items: [
      { label: "Default", value: "products" },
      { label: "Price (asc)", value: "products/sort/price:asc" },
      { label: "Price (desc)", value: "products/sort/price:desc" },
    ],
  }),
]);
```

The generalized pattern for the value attribute is: `<index_name>[/sort/<sort_by>]`. The adapter will use the value in `<sort_by>` as the value for the `sort_by` search parameter.

### `configure`

If you need to specify a `filter_by` search parameter for Typesense, you want to use the `configure` InstantSearch widget, along with `facetFilters`, `numericFilters` or `filters`.

The format for `facetFilters` and `numericFilters` is the same as Algolia's as described [here](https://www.algolia.com/doc/api-reference/api-parameters/facetFilters/).
But `filters` needs to be in Typesense's `filter_by` format as described in this table [here](https://typesense.org/docs/latest/api/documents.html#query-parameters).

Setting `filter_by` inside the `additionalQueryParameters` config only works when the widgets are loaded initially, because InstantSearch internally overrides the `filter_by` field subsequently.
Read more [here](https://github.com/typesense/typesense-instantsearch-adapter/issues/17#issuecomment-746912375).

### `index`

For Federated / Multi-Index Search, you'd need to use the `index` widget. To then be able to specify different search parameters for each index/collection, you can specify them using the `collectionSpecificSearchParameters` configuration:

```js
const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "abcd", // Be sure to use an API key that only allows search operations
    nodes: [{ host: "localhost", path: "/", port: "8108", protocol: "http" }],
  },
  // Search parameters that are common to all collections/indices go here:
  additionalSearchParameters: {
    numTypos: 3,
  },
  // Search parameters that need to be *overridden* on a per-collection-basis go here:
  collectionSpecificSearchParameters: {
    products: {
      query_by: "name,description,categories",
    },
    brands: {
      query_by: "name",
    },
  },
});
const searchClient = typesenseInstantsearchAdapter.searchClient;
```

Essentially, any parameters set in `collectionSpecificSearchParameters` will be merged with the values in `additionalSearchParameters` when querying Typesense, effectively overriding values in `additionalSearchParameters` on a per-collection-basis.

### `geoSearch`

Algolia uses `_geoloc` by default for the name of the field that stores the lat long values for a record.
In Typesense, you can name the geo location field anything. If you use a name other than `_geoloc`, you need to specify it when initializing the adapter like below, so InstantSearch can access it:

```js
const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "xyz",
    nodes: [
      {
        host: "localhost",
        port: "8108",
        path: "/",
        protocol: "http",
      },
    ],
  },
  geoLocationField: "lat_lng_field", // <<======
  additionalSearchParameters,
});
```

### `dynamicWidgets`

> Available as of Typesense Server `v0.25.0.rc12`

This [`dynamicWidgets`](https://www.algolia.com/doc/api-reference/widgets/dynamic-facets/js/) widget works out of the box with no additional changes,
but if you want to control the order in which these facets are displayed in the UI
Instantsearch expects a parameter called [`renderingContent`](https://www.algolia.com/doc/api-reference/api-parameters/renderingContent/) to be set.

```js
const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "xyz",
    nodes: [
      {
        host: "localhost",
        port: "8108",
        path: "/",
        protocol: "http",
      },
    ],
  },
  renderingContent: {
    // <<===== Add this, only if you want to control the order of the widgets displayed by dynamicWidgets
    facetOrdering: {
      facets: {
        order: ["size", "brand"], // <<===== Change this as needed
      },
    },
  },
  additionalSearchParameters,
});
```

Read more about all available options for `renderingContent` in [Algolia's documentation here](https://www.algolia.com/doc/api-reference/api-parameters/renderingContent/?client=javascript#examples).

### Special characters in field names / values

> Available as of typesense-instantsearch-adapter `2.7.0-2`

- If any string fields in your documents have a colon `:` in their values (for eg, let's say there's a field called `{ brand: "a:b" }`, then you would need to add a parameter like below when instantiating the adapter:

  ```js
  const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
    server: {
      apiKey: "xyz",
      nodes: [
        {
          host: "localhost",
          port: "8108",
          path: "/",
          protocol: "http",
        },
      ],
    },
    facetableFieldsWithSpecialCharacters: ["brand"], // <======= Add string fields that have colons in their values here, to aid in parsing
    additionalSearchParameters,
  });
  ```

- If any numeric field _names_ in your documents have special characters like `>`, `<`, `=` (for eg, let's say there's a field called `{ price>discount: 3.0 }`) then you would need to add a parameter like below when instantiating the adapter:

  ```js
  const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
    server: {
      apiKey: "xyz",
      nodes: [
        {
          host: "localhost",
          port: "8108",
          path: "/",
          protocol: "http",
        },
      ],
    },
    facetableFieldsWithSpecialCharacters: ["price>discount"], // // <======= Add numeric fields that have >, < or = in their names, to aid in parsing
    additionalSearchParameters,
  });
  ```

### Setting `facet_by` options

> Available as of typesense-instantsearch-adapter `2.8.0-1` and Typesense Server `v0.26.0.rc25`

The `facet_by` parameter is managed by InstantSearch internally when you use the various filter widgets.

But if you need to pass custom options to the `facet_by` parameter (eg: server-side sort options), then you can use the `facetByOptions` parameter as shown below:

```js
const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "xyz",
    nodes: [
      {
        host: "localhost",
        port: "8108",
        path: "/",
        protocol: "http",
      },
    ],
  },
  facetByOptions: {
    brand: "(sort_by: _alpha:asc)",
    category: "(sort_by: _alpha:desc)",
  }, // <======= Add any facet_by parameter as a key value pair. Don't forget the surrounding parantheses in the value.
  collectionSpecificFacetByOptions: {
    collection1: {
      brand: "(sort_by: _alpha:desc)",
    },
  }, // <======= Use this parameter if multiple collections share the same field names, and you want to use different options for each field. This will override facetByOptions for that particular collection.
  additionalSearchParameters,
});
```

Note that for sorting in refinementLists, in addition to sorting on the Typesense Server-side, you'd also need to pass the [`sortBy`](https://www.algolia.com/doc/api-reference/widgets/refinement-list/js/#widget-param-sortby) parameter to the refinementList widget to also sort the results appropriately on the client-side.

### Setting `filter_by` options

> Available as of typesense-instantsearch-adapter `2.8.0-5`

The `filter_by` parameter is managed by InstantSearch internally when you use the various filter widgets.

By default, the adapter uses exact filtering (`filter_by: field:=value`) when sending the queries to Typesense.
If you need to configure the adapter to use `:` (non-exact word-level filtering - `filter_by: field:value`), you want to instantiate the adapter using the `filterByOptions` configuration:

```js
const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "xyz",
    nodes: [
      {
        host: "localhost",
        port: "8108",
        path: "/",
        protocol: "http",
      },
    ],
  },
  filterByOptions: {
    brand: { exactMatch: false }, // <========== Add this to do non-exact word-level filtering
    category: { exactMatch: false },
  },
  collectionSpecificFilterByOptions: {
    collection1: {
      brand: { exactMatch: false },
    },
  }, // <======= Use this parameter if multiple collections share the same field names, and you want to use different options for each field. This will override filterByOptions for that particular collection.
  additionalSearchParameters,
});
```

### Disabling overrides for certain sorts

> Available as of typesense-instantsearch-adapter `2.9.0-0`

Here's a way to disable overrides / curation rules, when users select a particular sort order:

```js
const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "xyz",
    nodes: [
      {
        host: "localhost",
        port: "8108",
        path: "/",
        protocol: "http",
      },
    ],
  },
  sortByOptions: {
    "field1:desc,field2:desc": { enable_overrides: false }, // <========== Add this to disable sorting when this particular Typesense `sort_by` string is generated by the sortBy widget
  },
  collectionSpecificSortByOptions: {
    collection2: {
      "field1:desc,field2:desc": { enable_overrides: false },
    },
  }, // <======= Use this parameter if multiple collections share the same field names, and you want to use different options for each field. This will override sortByOptions for that particular collection.
  additionalSearchParameters,
});
```

If you have a sortBy widgets configured with an indexName value of `products/sort/price:asc` for eg, then the key inside `sortByOptions` should be `price:asc`.

### Grouped Hits

> Available as of typesense-instantsearch-adapter `2.7.1-4`

By default, when `group_by` is used as a search parameters, the adapter flattens the results across all groups into a single list of sequential hits.

If you'd like to preserve the groups, you want to set `flattenGroupedHits: false` when instantiating the adapter.

This will place the first hit in a group as the primary hit, and then add all hits in the group inside a `_grouped_hits` key inside each hit.

```js
const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "xyz",
    nodes: [
      {
        host: "localhost",
        port: "8108",
        path: "/",
        protocol: "http",
      },
    ],
  },
  flattenGroupedHits: false, // <=======
  additionalSearchParameters,
});
```

### Vector Search

> Available as of typesense-instantsearch-adapter `2.7.0-3`

The general idea is to first hook into the query life-cycle of Instantsearch, intercept the typed query and send it to an embedding API, fetch the embeddings and then send the vectors to Typesense to do a nearest neighbor vector search.

Here's a demo that you can run locally to see this in action: [https://github.com/typesense/showcase-hn-comments-semantic-search](https://github.com/typesense/showcase-hn-comments-semantic-search).

Here's how to do this in Instantsearch.js:

```javascript
const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "xyz",
    nodes: [
      {
        host: "localhost",
        port: "8108",
        path: "/",
        protocol: "http",
      },
    ],
  },
  additionalSearchParameters,
});
// from https://github.com/typesense/showcase-hn-comments-semantic-search/blob/8a33006cae58b425c53f56a64e1273e808cd9375/src/js/index.js#L101
const searchClient = typesenseInstantsearchAdapter.searchClient;
search = instantsearch({
  searchClient,
  indexName: INDEX_NAME,
  routing: true,
  async searchFunction(helper) {
    // This fetches 200 (nearest neighbor) results for semantic / hybrid search

    let query = helper.getQuery().query;
    const page = helper.getPage(); // Retrieve the current page

    if (query !== "" && ["semantic", "hybrid"].includes($("#search-type-select").val())) {
      console.log(helper.getQuery().query);
      helper
        .setQueryParameter(
          "typesenseVectorQuery", // <=== Special parameter that only works in typesense-instantsearch-adapter@2.7.0-3 and above
          `embedding:([], k:200)`,
        )
        .setPage(page)
        .search();
      console.log(helper.getQuery().query);
    } else {
      helper.setQueryParameter("typesenseVectorQuery", null).setPage(page).search();
    }
  },
});
```

## Caching

There are two modes of caching:

1. **Server-side caching:**

   To enable server-side caching, add a parameter called `useServerSideSearchCache: true` in the `server` configuration block of the typesense-instantsearch-adapter like this:

   ```javascript
   const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
     server: {
       apiKey: "...",
       nearestNode: {...},
       nodes: [...],
       useServerSideSearchCache: true // <<< Add this to send use_cache as a query parameter instead of post body parameter
     },
     additionalSearchParameters: {...}
   });
   ```

   This will cause the adapter to add `?use_cache=true` as a URL query parameter to all search requests initiated by the adapter, which will then cause Typesense Server to enable server-side caching for these requests.

2. **Client-side caching:**

   The adapter also has client-side caching enabled by default, to prevent unnecessary network calls to the server. The TTL for this client-side cache can be configured like this:

   ```javascript
   const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
    server: {
      apiKey: "...",
      nearestNode: {...},
      nodes: [...],
      cacheSearchResultsForSeconds: 2 * 60 // <<< Add this to configure the TTL for client-side cache in the browser
    },
    additionalSearchParameters: {...}
   });
   ```

## Compatibility

| Typesense Server | typesense-instantsearch-adapter | instantsearch.js | react-instantsearch | vue-instantsearch | angular-instantsearch |
| ---------------- | ------------------------------- | ---------------- | ------------------- | ----------------- | --------------------- |
| \>= v0.25.0      | \>= v2.7.1                      | \>= 4.51         | \>= 6.39            | \>= 4.8           | \>= 4.4               |
| \>= v0.25.0.rc14 | \>= v2.7.0-1                    | \>= 4.51         | \>= 6.39            | \>= 4.8           | \>= 4.4               |
| \>= v0.25.0.rc12 | \>= v2.6.0                      | \>= 4.51         | \>= 6.39            | \>= 4.8           | \>= 4.4               |
| \>= v0.24        | \>= v2.5.0                      | \>= 4.2.0        | \>= 6.0.0           | \>= 2.2.1         | \>= 3.0.0             |
| \>= v0.21        | \>= v2.0.0                      | \>= 4.2.0        | \>= 6.0.0           | \>= 2.2.1         | \>= 3.0.0             |
| \>= v0.19        | \>= v1.0.0                      | \>= 4.2.0        | \>= 6.0.0           | \>= 2.2.1         | \>= 3.0.0             |
| \>= v0.15        | \>= v0.3.0                      | \>= 4.2.0        | \>= 6.0.0           | \>= 2.2.1         | \>= 3.0.0             |
| \>= v0.14        | \>= v0.2.0                      | \>= 4.2.0        | \>= 6.0.0           | \>= 2.2.1         | \>= 3.0.0             |
| \>= v0.13        | \>= v0.1.0                      | \>= 4.2.0        | \>= 6.0.0           | \>= 2.2.1         | \>= 3.0.0             |
| \>= v0.12        | \>= v0.0.4                      | \>= 4.2.0        | \>= 6.0.0           | \>= 2.2.1         | \>= 3.0.0             |

If a particular version of the above libraries don't work with the adapter, please open a Github issue with details.

### Widget Compatibility

This adapter works with all widgets in [this list](https://www.algolia.com/doc/api-reference/widgets/js/)

## Development

```shell
$ npm install
$ npm run typesenseServer
$ FORCE_REINDEX=true npm run indexTestData

$ npm link typesense-instantsearch-adapter
$ npm run testground

$ npm test
```

To release a new version, we use the [np](https://github.com/sindresorhus/np) package:

```shell
$ npm install --global np
$ np

# Follow instructions that np shows you

```

## Help

If you have any questions or run into any problems, please create a Github issue and we'll try our best to help.

© 2020-present Typesense, Inc.

[npm-image]: https://badge.fury.io/js/typesense-instantsearch-adapter.svg
[npm-url]: https://npmjs.org/package/typesense-instantsearch-adapter


---

# unicode-canonical-property-names-ecmascript [![unicode-canonical-property-names-ecmascript on npm](https://img.shields.io/npm/v/unicode-canonical-property-names-ecmascript)](https://www.npmjs.com/package/unicode-canonical-property-names-ecmascript)

_unicode-canonical-property-names-ecmascript_ exports the set of canonical Unicode property names that are supported in [ECMAScript RegExp property escapes](https://github.com/tc39/proposal-regexp-unicode-property-escapes).

## Installation

To use _unicode-canonical-property-names-ecmascript_, install it as a dependency via [npm](https://www.npmjs.com/):

```bash
$ npm install unicode-canonical-property-names-ecmascript
```

Then, `require` it:

```js
const properties = require('unicode-canonical-property-names-ecmascript');
```

## Example

```js
properties.has('ID_Start');
// → true
properties.has('IDS');
// → false
```

## For maintainers

### How to publish a new release

1. On the `main` branch, bump the version number in `package.json`:

    ```sh
    npm version patch -m 'Release v%s'
    ```

    Instead of `patch`, use `minor` or `major` [as needed](https://semver.org/).

    Note that this produces a Git commit + tag.

1. Push the release commit and tag:

    ```sh
    git push && git push --tags
    ```

    Our CI then automatically publishes the new release to npm.

## Author

| [![twitter/mathias](https://gravatar.com/avatar/24e08a9ea84deb17ae121074d0f17125?s=70)](https://twitter.com/mathias "Follow @mathias on Twitter") |
|---|
| [Mathias Bynens](https://mathiasbynens.be/) |

## License

_unicode-canonical-property-names-ecmascript_ is available under the [MIT](https://mths.be/mit) license.


---

# unicode-match-property-ecmascript [![Build status](https://travis-ci.org/mathiasbynens/unicode-match-property-ecmascript.svg?branch=main)](https://travis-ci.org/mathiasbynens/unicode-match-property-ecmascript) [![unicode-match-property-ecmascript on npm](https://img.shields.io/npm/v/unicode-match-property-ecmascript)](https://www.npmjs.com/package/unicode-match-property-ecmascript)

_unicode-match-property-ecmascript_ matches a given Unicode property or [property alias](https://github.com/mathiasbynens/unicode-property-aliases-ecmascript) to its canonical property name without applying [loose matching](https://github.com/mathiasbynens/unicode-loose-match) per the algorithm used for [RegExp Unicode property escapes in ECMAScript](https://github.com/tc39/proposal-regexp-unicode-property-escapes). Consider it a strict alternative to loose matching.

## Installation

To use _unicode-match-property-ecmascript_ programmatically, install it as a dependency via [npm](https://www.npmjs.com/):

```bash
$ npm install unicode-match-property-ecmascript
```

Then, `require` it:

```js
const matchProperty = require('unicode-match-property-ecmascript');
```

## API

This module exports a single function named `matchProperty`.

### `matchProperty(value)`

This function takes a string `value` and attempts to match it to a canonical Unicode property name. If there’s a match, it returns the canonical property name. Otherwise, it throws an exception.

```js
// Find the canonical property name:
matchProperty('sc')
// → 'Script'

matchProperty('Script')
// → 'Script'

matchProperty('script') // Note: incorrect casing.
// → throws
```

## For maintainers

### How to publish a new release

1. On the `main` branch, bump the version number in `package.json`:

    ```sh
    npm version patch -m 'Release v%s'
    ```

    Instead of `patch`, use `minor` or `major` [as needed](https://semver.org/).

    Note that this produces a Git commit + tag.

1. Push the release commit and tag:

    ```sh
    git push && git push --tags
    ```

    Our CI then automatically publishes the new release to npm.

## Author

| [![twitter/mathias](https://gravatar.com/avatar/24e08a9ea84deb17ae121074d0f17125?s=70)](https://twitter.com/mathias "Follow @mathias on Twitter") |
|---|
| [Mathias Bynens](https://mathiasbynens.be/) |

## License

_unicode-match-property-ecmascript_ is available under the [MIT](https://mths.be/mit) license.


---

# unicode-match-property-value-ecmascript [![unicode-match-property-value-ecmascript on npm](https://img.shields.io/npm/v/unicode-match-property-value-ecmascript)](https://www.npmjs.com/package/unicode-match-property-value-ecmascript)

_unicode-match-property-value-ecmascript_ matches a given Unicode property value or [property value alias](https://github.com/mathiasbynens/unicode-property-value-aliases) to its canonical property value without applying [loose matching](https://github.com/mathiasbynens/unicode-loose-match), per the algorithm used for [RegExp Unicode property escapes in ECMAScript](https://github.com/tc39/proposal-regexp-unicode-property-escapes). Consider it a strict alternative to loose matching.

## Installation

To use _unicode-match-property-value-ecmascript_ programmatically, install it as a dependency via [npm](https://www.npmjs.com/):

```bash
$ npm install unicode-match-property-value-ecmascript
```

Then, `require` it:

```js
const matchPropertyValue = require('unicode-match-property-value-ecmascript');
```

## API

This module exports a single function named `matchPropertyValue`.

### `matchPropertyValue(property, value)`

This function takes a string `property` that is a canonical/unaliased Unicode property name, and a string `value`. It attemps to  match `value` to a canonical Unicode property value for the given property. If there’s a match, it returns the canonical property value. Otherwise, it throws an exception.

```js
// Find the canonical property value:
matchPropertyValue('Script_Extensions', 'Aghb')
// → 'Caucasian_Albanian'

matchPropertyValue('Script_Extensions', 'Caucasian_Albanian')
// → 'Caucasian_Albanian'

matchPropertyValue('script_extensions', 'Caucasian_Albanian') // Note: incorrect casing.
// → throws

matchPropertyValue('Script_Extensions', 'caucasian_albanian') // Note: incorrect casing.
// → throws
```

## For maintainers

### How to publish a new release

1. On the `main` branch, bump the version number in `package.json`:

    ```sh
    npm version patch -m 'Release v%s'
    ```

    Instead of `patch`, use `minor` or `major` [as needed](https://semver.org/).

    Note that this produces a Git commit + tag.

1. Push the release commit and tag:

    ```sh
    git push && git push --tags
    ```

    Our CI then automatically publishes the new release to npm.

## Author

| [![twitter/mathias](https://gravatar.com/avatar/24e08a9ea84deb17ae121074d0f17125?s=70)](https://twitter.com/mathias "Follow @mathias on Twitter") |
|---|
| [Mathias Bynens](https://mathiasbynens.be/) |

## License

_unicode-match-property-value-ecmascript_ is available under the [MIT](https://mths.be/mit) license.


---

# unicode-property-aliases-ecmascript [![Build status](https://travis-ci.org/mathiasbynens/unicode-property-aliases-ecmascript.svg?branch=main)](https://travis-ci.org/mathiasbynens/unicode-property-aliases-ecmascript) [![unicode-property-aliases-ecmascript on npm](https://img.shields.io/npm/v/unicode-property-aliases-ecmascript)](https://www.npmjs.com/package/unicode-property-aliases-ecmascript)

_unicode-property-aliases-ecmascript_ offers Unicode property alias mappings in an easy-to-consume JavaScript format. It only contains the Unicode property names that are supported in [ECMAScript RegExp property escapes](https://github.com/tc39/proposal-regexp-unicode-property-escapes).

It’s based on Unicode’s `PropertyAliases.txt`.

## Installation

To use _unicode-property-aliases-ecmascript_ programmatically, install it as a dependency via [npm](https://www.npmjs.com/):

```bash
$ npm install unicode-property-aliases-ecmascript
```

Then, `require` it:

```js
const propertyAliases = require('unicode-property-aliases-ecmascript');
```

## Usage

This module exports a `Map` object. The most common usage is to convert a property alias to its canonical form:

```js
propertyAliases.get('scx')
// → 'Script_Extensions'
```

## For maintainers

### How to publish a new release

1. On the `main` branch, bump the version number in `package.json`:

    ```sh
    npm version patch -m 'Release v%s'
    ```

    Instead of `patch`, use `minor` or `major` [as needed](https://semver.org/).

    Note that this produces a Git commit + tag.

1. Push the release commit and tag:

    ```sh
    git push && git push --tags
    ```

    Our CI then automatically publishes the new release to npm.

## Author

| [![twitter/mathias](https://gravatar.com/avatar/24e08a9ea84deb17ae121074d0f17125?s=70)](https://twitter.com/mathias "Follow @mathias on Twitter") |
|---|
| [Mathias Bynens](https://mathiasbynens.be/) |

## License

_unicode-property-aliases-ecmascript_ is available under the [MIT](https://mths.be/mit) license.


---

# [![unified][logo]][site]

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

**unified** lets you inspect and transform content with plugins.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [Overview](#overview)
* [API](#api)
  * [`processor()`](#processor)
  * [`processor.compiler`](#processorcompiler)
  * [`processor.data([key[, value]])`](#processordatakey-value)
  * [`processor.freeze()`](#processorfreeze)
  * [`processor.parse(file)`](#processorparsefile)
  * [`processor.parser`](#processorparser)
  * [`processor.process(file[, done])`](#processorprocessfile-done)
  * [`processor.processSync(file)`](#processorprocesssyncfile)
  * [`processor.run(tree[, file][, done])`](#processorruntree-file-done)
  * [`processor.runSync(tree[, file])`](#processorrunsynctree-file)
  * [`processor.stringify(tree[, file])`](#processorstringifytree-file)
  * [`processor.use(plugin[, options])`](#processoruseplugin-options)
  * [`CompileResultMap`](#compileresultmap)
  * [`CompileResults`](#compileresults)
  * [`Compiler`](#compiler)
  * [`Data`](#data)
  * [`Parser`](#parser)
  * [`Pluggable`](#pluggable)
  * [`PluggableList`](#pluggablelist)
  * [`Plugin`](#plugin)
  * [`PluginTuple`](#plugintuple)
  * [`Preset`](#preset)
  * [`ProcessCallback`](#processcallback)
  * [`Processor`](#processor-1)
  * [`RunCallback`](#runcallback)
  * [`Settings`](#settings)
  * [`TransformCallback`](#transformcallback)
  * [`Transformer`](#transformer)
* [Types](#types)
* [Compatibility](#compatibility)
* [Contribute](#contribute)
* [Sponsor](#sponsor)
* [Acknowledgments](#acknowledgments)
* [License](#license)

## What is this?

unified is two things:

* **unified** is a collective of 500+ free and open source packages that work
  with content as structured data (ASTs)
* `unified` (this project) is the core package, used in 1.3m+ projects on GH,
  to process content with plugins

Several ecosystems are built on unified around different kinds of content.
Notably, [remark][] (markdown), [rehype][] (HTML), and [retext][] (natural
language).
These ecosystems can be connected together.

* for more about us, see [`unifiedjs.com`][site]
* for updates, see [@unifiedjs][twitter] on Twitter
* for questions, see [support][]
* to help, see [contribute][] and [sponsor][] below

## When should I use this?

In some cases, you are already using unified.
For example, it’s used in MDX, Gatsby, Docusaurus, etc.
In those cases, you don’t need to add `unified` yourself but you can include
plugins into those projects.

But the real fun (for some) is to get your hands dirty and work with syntax
trees and build with it yourself.
You can create those projects, or things like Prettier, or your own site
generator.
You can connect utilities together and make your own plugins that check for
problems and transform from one thing to another.

When you are dealing with one type of content (such as markdown), you can use
the main package of that ecosystem instead (so `remark`).
When you are dealing with different kinds of content (such as markdown and
HTML), it’s recommended to use `unified` itself, and pick and choose the plugins
you need.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install unified
```

In Deno with [`esm.sh`][esmsh]:

```js
import {unified} from 'https://esm.sh/unified@11'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {unified} from 'https://esm.sh/unified@11?bundle'
</script>
```

## Use

```js
import rehypeDocument from 'rehype-document'
import rehypeFormat from 'rehype-format'
import rehypeStringify from 'rehype-stringify'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import {unified} from 'unified'
import {reporter} from 'vfile-reporter'

const file = await unified()
  .use(remarkParse)
  .use(remarkRehype)
  .use(rehypeDocument, {title: '👋🌍'})
  .use(rehypeFormat)
  .use(rehypeStringify)
  .process('# Hello world!')

console.error(reporter(file))
console.log(String(file))
```

Yields:

```txt
no issues found
```

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>👋🌍</title>
    <meta name="viewport" content="width=device-width, initial-scale=1">
  </head>
  <body>
    <h1>Hello world!</h1>
  </body>
</html>
```

<!-- Old name: -->

<a name="description"></a>

## Overview

`unified` is an interface for processing content with syntax trees.
Syntax trees are a representation of content understandable to programs.
Those programs, called *[plugins][api-plugin]*, take these trees and inspect and
modify them.
To get to the syntax tree from text, there is a *[parser][api-parser]*.
To get from that back to text, there is a *[compiler][api-compiler]*.
This is the *[process][api-process]* of a *processor*.

```ascii
| ........................ process ........................... |
| .......... parse ... | ... run ... | ... stringify ..........|

          +--------+                     +----------+
Input ->- | Parser | ->- Syntax Tree ->- | Compiler | ->- Output
          +--------+          |          +----------+
                              X
                              |
                       +--------------+
                       | Transformers |
                       +--------------+
```

###### Processors

Processors process content.
On its own, `unified` (the root processor) doesn’t work.
It needs to be configured with plugins to work.
For example:

```js
const processor = unified()
  .use(remarkParse)
  .use(remarkRehype)
  .use(rehypeDocument, {title: '👋🌍'})
  .use(rehypeFormat)
  .use(rehypeStringify)
```

That processor can do different things.
It can:

* …parse markdown (`parse`)
* …turn parsed markdown into HTML and format the HTML (`run`)
* …compile HTML (`stringify`)
* …do all of the above (`process`)

Every processor implements another processor.
To create a processor, call another processor.
The new processor is configured to work the same as its ancestor.
But when the descendant processor is configured in the future it does not affect
the ancestral processor.

When processors are exposed from a module (for example, `unified` itself) they
should not be configured directly, as that would change their behavior for all
module users.
Those processors are *[frozen][api-freeze]* and they should be called to create
a new processor before they are used.

###### File

When processing a document, metadata is gathered about that document.
[`vfile`][vfile] is the file format that stores data, metadata, and messages
about files for unified and plugins.

There are several [utilities][vfile-utilities] for working with these files.

###### Syntax tree

The syntax trees used in unified are [unist][] nodes.
A tree represents a whole document and each [node][] is a plain JavaScript
object with a `type` field.
The semantics of nodes and the format of syntax trees is defined by other
projects:

* [esast][] — JavaScript
* [hast][] — HTML
* [mdast][] — markdown
* [nlcst][] — natural language
* [xast][] — XML

There are many utilities for working with trees listed in each aforementioned
project and maintained in the [`syntax-tree`][syntax-tree] organization.
These utilities are a level lower than unified itself and are building blocks
that can be used to make plugins.

<!-- Old name: -->

<a name="list-of-processors"></a>

###### Ecosystems

Around each syntax tree is an ecosystem that focusses on that particular kind
of content.
At their core, they parse text to a tree and compile that tree back to text.
They also provide plugins that work with the syntax tree, without requiring
that the end user has knowledge about that tree.

* [rehype][] (hast) — HTML
* [remark][] (mdast) — markdown
* [retext][] (nlcst) — natural language

<a name="list-of-plugins"></a>

###### Plugins

Each aforementioned ecosystem comes with a large set of plugins that you can
pick and choose from to do all kinds of things.

* [List of remark plugins][remark-plugins] ·
  [`remarkjs/awesome-remark`][awesome-remark] ·
  [`remark-plugin` topic][topic-remark-plugin]
* [List of rehype plugins][rehype-plugins] ·
  [`rehypejs/awesome-rehype`][awesome-rehype] ·
  [`rehype-plugin` topic][topic-rehype-plugin]
* [List of retext plugins][retext-plugins] ·
  [`retextjs/awesome-retext`][awesome-retext] ·
  [`retext-plugin` topic][topic-retext-plugin]

There are also a few plugins that work in any ecosystem:

* [`unified-diff`](https://github.com/unifiedjs/unified-diff)
  — ignore unrelated messages in GitHub Actions and Travis
* [`unified-infer-git-meta`](https://github.com/unifiedjs/unified-infer-git-meta)
  — infer metadata of a document from Git
* [`unified-message-control`](https://github.com/unifiedjs/unified-message-control)
  — enable, disable, and ignore messages from content

###### Configuration

Processors are configured with [plugins][api-plugin] or with the
[`data`][api-data] method.
Most plugins also accept configuration through options.
See each plugin’s readme for more info.

###### Integrations

unified can integrate with the file system through
[`unified-engine`][unified-engine].
CLI apps can be created with [`unified-args`][unified-args], Gulp plugins with
[`unified-engine-gulp`][unified-engine-gulp], and language servers with
[`unified-language-server`][unified-language-server].
A streaming interface can be created with [`unified-stream`][unified-stream].

###### Programming interface

The [API][] provided by `unified` allows multiple files to be processed and
gives access to metadata (such as lint messages):

```js
import rehypeStringify from 'rehype-stringify'
import remarkParse from 'remark-parse'
import remarkPresetLintMarkdownStyleGuide from 'remark-preset-lint-markdown-style-guide'
import remarkRehype from 'remark-rehype'
import remarkRetext from 'remark-retext'
import retextEnglish from 'retext-english'
import retextEquality from 'retext-equality'
import {unified} from 'unified'
import {reporter} from 'vfile-reporter'

const file = await unified()
  .use(remarkParse)
  .use(remarkPresetLintMarkdownStyleGuide)
  .use(remarkRetext, unified().use(retextEnglish).use(retextEquality))
  .use(remarkRehype)
  .use(rehypeStringify)
  .process('*Emphasis* and _stress_, you guys!')

console.error(reporter(file))
console.log(String(file))
```

Yields:

```txt
1:16-1:24 warning Emphasis should use `*` as a marker                                 emphasis-marker remark-lint
1:30-1:34 warning `guys` may be insensitive, use `people`, `persons`, `folks` instead gals-man        retext-equality

⚠ 2 warnings
```

```html
<p><em>Emphasis</em> and <em>stress</em>, you guys!</p>
```

<!-- Old name: -->

<a name="processing-between-syntaxes"></a>

###### Transforming between ecosystems

Ecosystems can be combined in two modes.

**Bridge** mode transforms the tree from one format (*origin*) to another
(*destination*).
A different processor runs on the destination tree.
Afterwards, the original processor continues with the origin tree.

**Mutate** mode also transforms the syntax tree from one format to another.
But the original processor continues transforming the destination tree.

In the previous example (“Programming interface”), `remark-retext` is used in
bridge mode: the origin syntax tree is kept after retext is done; whereas
`remark-rehype` is used in mutate mode: it sets a new syntax tree and discards
the origin tree.

The following plugins lets you combine ecosystems:

* [`remark-retext`][remark-retext] — turn markdown into natural language
* [`remark-rehype`][remark-rehype] — turn markdown into HTML
* [`rehype-retext`][rehype-retext] — turn HTML into natural language
* [`rehype-remark`][rehype-remark] — turn HTML into markdown

## API

This package exports the identifier `unified` (the root `processor`).
There is no default export.

### `processor()`

Create a new processor.

###### Returns

New *[unfrozen][api-freeze]* processor ([`processor`][api-processor]).

This processor is configured to work the same as its ancestor.
When the descendant processor is configured in the future it does not affect
the ancestral processor.

###### Example

This example shows how a new processor can be created (from `remark`) and linked
to **stdin**(4) and **stdout**(4).

```js
import process from 'node:process'
import concatStream from 'concat-stream'
import {remark} from 'remark'

process.stdin.pipe(
  concatStream(function (buf) {
    process.stdout.write(String(remark().processSync(buf)))
  })
)
```

### `processor.compiler`

Compiler to use ([`Compiler`][api-compiler], optional).

### `processor.data([key[, value]])`

Configure the processor with info available to all plugins.
Information is stored in an object.

Typically, options can be given to a specific plugin, but sometimes it makes
sense to have information shared with several plugins.
For example, a list of HTML elements that are self-closing, which is needed
during all [phases][overview].

> 👉 **Note**: setting information cannot occur on *[frozen][api-freeze]*
> processors.
> Call the processor first to create a new unfrozen processor.

> 👉 **Note**: to register custom data in TypeScript, augment the
> [`Data`][api-data] interface.

###### Signatures

* `processor = processor.data(key, value)`
* `processor = processor.data(dataset)`
* `value = processor.data(key)`
* `dataset = processor.data()`

###### Parameters

* `key` ([`keyof Data`][api-data], optional) — field to get
* `value` ([`Data[key]`][api-data]) — value to set
* `values` ([`Data`][api-data]) — values to set

###### Returns

The current processor when setting ([`processor`][api-processor]), the value at
`key` when getting ([`Data[key]`][api-data]), or the entire dataset when
getting without key ([`Data`][api-data]).

###### Example

This example show how to get and set info:

```js
import {unified} from 'unified'

const processor = unified().data('alpha', 'bravo')

processor.data('alpha') // => 'bravo'

processor.data() // => {alpha: 'bravo'}

processor.data({charlie: 'delta'})

processor.data() // => {charlie: 'delta'}
```

### `processor.freeze()`

Freeze a processor.

Frozen processors are meant to be extended and not to be configured directly.

When a processor is frozen it cannot be unfrozen.
New processors working the same way can be created by calling the processor.

It’s possible to freeze processors explicitly by calling `.freeze()`.
Processors freeze automatically when `.parse()`, `.run()`, `.runSync()`,
`.stringify()`, `.process()`, or `.processSync()` are called.

###### Returns

The current processor ([`processor`][api-processor]).

###### Example

This example, `index.js`, shows how `rehype` prevents extensions to itself:

```js
import rehypeParse from 'rehype-parse'
import rehypeStringify from 'rehype-stringify'
import {unified} from 'unified'

export const rehype = unified().use(rehypeParse).use(rehypeStringify).freeze()
```

That processor can be used and configured like so:

```js
import {rehype} from 'rehype'
import rehypeFormat from 'rehype-format'
// …

rehype()
  .use(rehypeFormat)
  // …
```

A similar looking example is broken as operates on the frozen interface.
If this behavior was allowed it would result in unexpected behavior so an error
is thrown.
**This is not valid**:

```js
import {rehype} from 'rehype'
import rehypeFormat from 'rehype-format'
// …

rehype
  .use(rehypeFormat)
  // …
```

Yields:

```txt
~/node_modules/unified/index.js:426
    throw new Error(
    ^

Error: Cannot call `use` on a frozen processor.
Create a new processor first, by calling it: use `processor()` instead of `processor`.
    at assertUnfrozen (~/node_modules/unified/index.js:426:11)
    at Function.use (~/node_modules/unified/index.js:165:5)
    …
```

### `processor.parse(file)`

Parse text to a syntax tree.

> 👉 **Note**: `parse` freezes the processor if not already
> *[frozen][api-freeze]*.

> 👉 **Note**: `parse` performs the [parse phase][overview], not the run phase
> or other phases.

###### Parameters

* `file` ([`Compatible`][vfile-compatible]) — file to parse; typically
  `string` or [`VFile`][vfile]; any value accepted as `x` in `new VFile(x)`

###### Returns

Syntax tree representing `file` ([`Node`][node]).

###### Example

This example shows how `parse` can be used to create a tree from a file.

```js
import remarkParse from 'remark-parse'
import {unified} from 'unified'

const tree = unified().use(remarkParse).parse('# Hello world!')

console.log(tree)
```

Yields:

```js
{
  type: 'root',
  children: [
    {type: 'heading', depth: 1, children: [Array], position: [Object]}
  ],
  position: {
    start: {line: 1, column: 1, offset: 0},
    end: {line: 1, column: 15, offset: 14}
  }
}
```

### `processor.parser`

Parser to use ([`Parser`][api-parser], optional).

### `processor.process(file[, done])`

Process the given file as configured on the processor.

> 👉 **Note**: `process` freezes the processor if not already
> *[frozen][api-freeze]*.

> 👉 **Note**: `process` performs the [parse, run, and stringify
> phases][overview].

###### Signatures

* `processor.process(file, done)`
* `Promise<VFile> = processor.process(file?)`

###### Parameters

* `file` ([`Compatible`][vfile-compatible], optional) — file; typically
  `string` or [`VFile`][vfile]; any value accepted as `x` in `new VFile(x)`
* `done` ([`ProcessCallback`][api-process-callback], optional) — callback

###### Returns

Nothing if `done` is given (`undefined`).
Otherwise a promise, rejected with a fatal error or resolved with the
processed file ([`Promise<VFile>`][vfile]).

The parsed, transformed, and compiled value is available at `file.value` (see
note).

> 👉 **Note**: unified typically compiles by serializing: most
> compilers return `string` (or `Uint8Array`).
> Some compilers, such as the one configured with
> [`rehype-react`][rehype-react], return other values (in this case, a React
> tree).
> If you’re using a compiler that doesn’t serialize, expect different result
> values.
>
> To register custom results in TypeScript, add them to
> [`CompileResultMap`][api-compile-result-map].

###### Example

This example shows how `process` can be used to process a file:

```js
import rehypeDocument from 'rehype-document'
import rehypeFormat from 'rehype-format'
import rehypeStringify from 'rehype-stringify'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import {unified} from 'unified'

const file = await unified()
  .use(remarkParse)
  .use(remarkRehype)
  .use(rehypeDocument, {title: '👋🌍'})
  .use(rehypeFormat)
  .use(rehypeStringify)
  .process('# Hello world!')

console.log(String(file))
```

Yields:

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>👋🌍</title>
    <meta name="viewport" content="width=device-width, initial-scale=1">
  </head>
  <body>
    <h1>Hello world!</h1>
  </body>
</html>
```

### `processor.processSync(file)`

Process the given file as configured on the processor.

An error is thrown if asynchronous transforms are configured.

> 👉 **Note**: `processSync` freezes the processor if not already
> *[frozen][api-freeze]*.

> 👉 **Note**: `processSync` performs the [parse, run, and stringify
> phases][overview].

###### Parameters

* `file` ([`Compatible`][vfile-compatible], optional) — file; typically
  `string` or [`VFile`][vfile]; any value accepted as `x` in `new VFile(x)`

###### Returns

The processed file ([`VFile`][vfile]).

The parsed, transformed, and compiled value is available at `file.value` (see
note).

> 👉 **Note**: unified typically compiles by serializing: most
> compilers return `string` (or `Uint8Array`).
> Some compilers, such as the one configured with
> [`rehype-react`][rehype-react], return other values (in this case, a React
> tree).
> If you’re using a compiler that doesn’t serialize, expect different result
> values.
>
> To register custom results in TypeScript, add them to
> [`CompileResultMap`][api-compile-result-map].

###### Example

This example shows how `processSync` can be used to process a file, if all
transformers are synchronous.

```js
import rehypeDocument from 'rehype-document'
import rehypeFormat from 'rehype-format'
import rehypeStringify from 'rehype-stringify'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import {unified} from 'unified'

const processor = unified()
  .use(remarkParse)
  .use(remarkRehype)
  .use(rehypeDocument, {title: '👋🌍'})
  .use(rehypeFormat)
  .use(rehypeStringify)

console.log(String(processor.processSync('# Hello world!')))
```

Yields:

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>👋🌍</title>
    <meta name="viewport" content="width=device-width, initial-scale=1">
  </head>
  <body>
    <h1>Hello world!</h1>
  </body>
</html>
```

### `processor.run(tree[, file][, done])`

Run *[transformers][api-transformer]* on a syntax tree.

> 👉 **Note**: `run` freezes the processor if not already
> *[frozen][api-freeze]*.

> 👉 **Note**: `run` performs the [run phase][overview], not other phases.

###### Signatures

* `processor.run(tree, done)`
* `processor.run(tree, file, done)`
* `Promise<Node> = processor.run(tree, file?)`

###### Parameters

* `tree` ([`Node`][node]) — tree to transform and inspect
* `file` ([`Compatible`][vfile-compatible], optional) — file associated
  with `node`; any value accepted as `x` in `new VFile(x)`
* `done` ([`RunCallback`][api-run-callback], optional) — callback

###### Returns

Nothing if `done` is given (`undefined`).
Otherwise, a promise rejected with a fatal error or resolved with the
transformed tree ([`Promise<Node>`][node]).

###### Example

This example shows how `run` can be used to transform a tree:

```js
import remarkReferenceLinks from 'remark-reference-links'
import {unified} from 'unified'
import {u} from 'unist-builder'

const tree = u('root', [
  u('paragraph', [
    u('link', {href: 'https://example.com'}, [u('text', 'Example Domain')])
  ])
])

const changedTree = await unified().use(remarkReferenceLinks).run(tree)

console.log(changedTree)
```

Yields:

```js
{
  type: 'root',
  children: [
    {type: 'paragraph', children: [Array]},
    {type: 'definition', identifier: '1', title: '', url: undefined}
  ]
}
```

### `processor.runSync(tree[, file])`

Run *[transformers][api-transformer]* on a syntax tree.

An error is thrown if asynchronous transforms are configured.

> 👉 **Note**: `runSync` freezes the processor if not already
> *[frozen][api-freeze]*.

> 👉 **Note**: `runSync` performs the [run phase][overview], not other phases.

###### Parameters

* `tree` ([`Node`][node]) — tree to transform and inspect
* `file` ([`Compatible`][vfile-compatible], optional) — file associated
  with `node`; any value accepted as `x` in `new VFile(x)`

###### Returns

Transformed tree ([`Node`][node]).

### `processor.stringify(tree[, file])`

Compile a syntax tree.

> 👉 **Note**: `stringify` freezes the processor if not already
> *[frozen][api-freeze]*.

> 👉 **Note**: `stringify` performs the [stringify phase][overview], not the run
> phase or other phases.

###### Parameters

* `tree` ([`Node`][node]) — tree to compile
* `file` ([`Compatible`][vfile-compatible], optional) — file associated
  with `node`; any value accepted as `x` in `new VFile(x)`

###### Returns

Textual representation of the tree (`Uint8Array` or `string`, see note).

> 👉 **Note**: unified typically compiles by serializing: most compilers
> return `string` (or `Uint8Array`).
> Some compilers, such as the one configured with
> [`rehype-react`][rehype-react], return other values (in this case, a
> React tree).
> If you’re using a compiler that doesn’t serialize, expect different
> result values.
>
> To register custom results in TypeScript, add them to
> [`CompileResultMap`][api-compile-result-map].

###### Example

This example shows how `stringify` can be used to serialize a syntax tree:

```js
import {h} from 'hastscript'
import rehypeStringify from 'rehype-stringify'
import {unified} from 'unified'

const tree = h('h1', 'Hello world!')

const document = unified().use(rehypeStringify).stringify(tree)

console.log(document)
```

Yields:

```html
<h1>Hello world!</h1>
```

### `processor.use(plugin[, options])`

Configure the processor to use a plugin, a list of usable values, or a preset.

If the processor is already using a plugin, the previous plugin configuration
is changed based on the options that are passed in.
In other words, the plugin is not added a second time.

> 👉 **Note**: `use` cannot be called on [*frozen*][api-freeze] processors.
> Call the processor first to create a new unfrozen processor.

###### Signatures

* `processor.use(preset?)`
* `processor.use(list)`
* `processor.use(plugin[, ...parameters])`

###### Parameters

* `preset` ([`Preset`][api-preset]) — plugins and settings
* `list` ([`PluggableList`][api-pluggable-list]) — list of usable things
* `plugin` ([`Plugin`][api-plugin]) — plugin
* `parameters` (`Array<unknown>`) — configuration for `plugin`, typically a
  single options object

###### Returns

Current processor ([`processor`][api-processor]).

###### Example

There are many ways to pass plugins to `.use()`.
This example gives an overview:

```js
import {unified} from 'unified'

unified()
  // Plugin with options:
  .use(pluginA, {x: true, y: true})
  // Passing the same plugin again merges configuration (to `{x: true, y: false, z: true}`):
  .use(pluginA, {y: false, z: true})
  // Plugins:
  .use([pluginB, pluginC])
  // Two plugins, the second with options:
  .use([pluginD, [pluginE, {}]])
  // Preset with plugins and settings:
  .use({plugins: [pluginF, [pluginG, {}]], settings: {position: false}})
  // Settings only:
  .use({settings: {position: false}})
```

### `CompileResultMap`

Interface of known results from compilers (TypeScript type).

Normally, compilers result in text ([`Value`][vfile-value] of `vfile`).
When you compile to something else, such as a React node (as in,
`rehype-react`), you can augment this interface to include that type.

```ts
import type {ReactNode} from 'somewhere'

declare module 'unified' {
  interface CompileResultMap {
    // Register a new result (value is used, key should match it).
    ReactNode: ReactNode
  }
}

export {} // You may not need this, but it makes sure the file is a module.
```

Use [`CompileResults`][api-compile-results] to access the values.

###### Type

```ts
interface CompileResultMap {
  // Note: if `Value` from `VFile` is changed, this should too.
  Uint8Array: Uint8Array
  string: string
}
```

### `CompileResults`

Acceptable results from compilers (TypeScript type).

To register custom results, add them to
[`CompileResultMap`][api-compile-result-map].

###### Type

```ts
type CompileResults = CompileResultMap[keyof CompileResultMap]
```

### `Compiler`

A **compiler** handles the compiling of a syntax tree to something else
(in most cases, text) (TypeScript type).

It is used in the stringify phase and called with a [`Node`][node]
and [`VFile`][vfile] representation of the document to compile.
It should return the textual representation of the given tree (typically
`string`).

> 👉 **Note**: unified typically compiles by serializing: most compilers
> return `string` (or `Uint8Array`).
> Some compilers, such as the one configured with
> [`rehype-react`][rehype-react], return other values (in this case, a
> React tree).
> If you’re using a compiler that doesn’t serialize, expect different
> result values.
>
> To register custom results in TypeScript, add them to
> [`CompileResultMap`][api-compile-result-map].

###### Type

```ts
type Compiler<
  Tree extends Node = Node,
  Result extends CompileResults = CompileResults
> = (tree: Tree, file: VFile) => Result
```

### `Data`

Interface of known data that can be supported by all plugins (TypeScript type).

Typically, options can be given to a specific plugin, but sometimes it makes
sense to have information shared with several plugins.
For example, a list of HTML elements that are self-closing, which is needed
during all phases.

To type this, do something like:

```ts
declare module 'unified' {
  interface Data {
    htmlVoidElements?: Array<string> | undefined
  }
}

export {} // You may not need this, but it makes sure the file is a module.
```

###### Type

```ts
interface Data {
  settings?: Settings | undefined
}
```

See [`Settings`][api-settings] for more info.

### `Parser`

A **parser** handles the parsing of text to a syntax tree (TypeScript type).

It is used in the parse phase and is called with a `string` and
[`VFile`][vfile] of the document to parse.
It must return the syntax tree representation of the given file
([`Node`][node]).

###### Type

```ts
type Parser<Tree extends Node = Node> = (document: string, file: VFile) => Tree
```

### `Pluggable`

Union of the different ways to add plugins and settings (TypeScript type).

###### Type

```ts
type Pluggable =
  | Plugin<Array<any>, any, any>
  | PluginTuple<Array<any>, any, any>
  | Preset
```

See [`Plugin`][api-plugin], [`PluginTuple`][api-plugin-tuple],
and [`Preset`][api-preset] for more info.

### `PluggableList`

List of plugins and presets (TypeScript type).

###### Type

```ts
type PluggableList = Array<Pluggable>
```

See [`Pluggable`][api-pluggable] for more info.

### `Plugin`

Single plugin (TypeScript type).

Plugins configure the processors they are applied on in the following ways:

* they change the processor, such as the parser, the compiler, or by
  configuring data
* they specify how to handle trees and files

In practice, they are functions that can receive options and configure the
processor (`this`).

> 👉 **Note**: plugins are called when the processor is *frozen*, not when they
> are applied.

###### Type

```ts
type Plugin<
  PluginParameters extends unknown[] = [],
  Input extends Node | string | undefined = Node,
  Output = Input
> = (
  this: Processor,
  ...parameters: PluginParameters
) => Input extends string // Parser.
  ? Output extends Node | undefined
    ? undefined | void
    : never
  : Output extends CompileResults // Compiler.
  ? Input extends Node | undefined
    ? undefined | void
    : never
  : // Inspect/transform.
      | Transformer<
          Input extends Node ? Input : Node,
          Output extends Node ? Output : Node
        >
      | undefined
      | void
```

See [`Transformer`][api-transformer] for more info.

###### Example

`move.js`:

```js
/**
 * @typedef Options
 *   Configuration (required).
 * @property {string} extname
 *   File extension to use (must start with `.`).
 */

/** @type {import('unified').Plugin<[Options]>} */
export function move(options) {
  if (!options || !options.extname) {
    throw new Error('Missing `options.extname`')
  }

  return function (_, file) {
    if (file.extname && file.extname !== options.extname) {
      file.extname = options.extname
    }
  }
}
```

`example.md`:

```markdown
# Hello, world!
```

`example.js`:

```js
import rehypeStringify from 'rehype-stringify'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import {read, write} from 'to-vfile'
import {unified} from 'unified'
import {reporter} from 'vfile-reporter'
import {move} from './move.js'

const file = await unified()
  .use(remarkParse)
  .use(remarkRehype)
  .use(move, {extname: '.html'})
  .use(rehypeStringify)
  .process(await read('example.md'))

console.error(reporter(file))
await write(file) // Written to `example.html`.
```

Yields:

```txt
example.md: no issues found
```

…and in `example.html`:

```html
<h1>Hello, world!</h1>
```

### `PluginTuple`

Tuple of a plugin and its configuration (TypeScript type).

The first item is a plugin, the rest are its parameters.

###### Type

```ts
type PluginTuple<
  TupleParameters extends unknown[] = [],
  Input extends Node | string | undefined = undefined,
  Output = undefined
> = [
  plugin: Plugin<TupleParameters, Input, Output>,
  ...parameters: TupleParameters
]
```

See [`Plugin`][api-plugin] for more info.

### `Preset`

Sharable configuration (TypeScript type).

They can contain plugins and settings.

###### Fields

* `plugins` ([`PluggableList`][api-pluggable-list], optional)
  — list of plugins and presets
* `settings` ([`Data`][api-data], optional)
  — shared settings for parsers and compilers

###### Example

`preset.js`:

```js
import remarkCommentConfig from 'remark-comment-config'
import remarkLicense from 'remark-license'
import remarkPresetLintConsistent from 'remark-preset-lint-consistent'
import remarkPresetLintRecommended from 'remark-preset-lint-recommended'
import remarkToc from 'remark-toc'

/** @type {import('unified').Preset} */
const preset = {
  plugins: [
    remarkPresetLintRecommended,
    remarkPresetLintConsistent,
    remarkCommentConfig,
    [remarkToc, {maxDepth: 3, tight: true}],
    remarkLicense
  ]
  settings: {bullet: '*', emphasis: '*', fences: true},
}

export default preset
```

`example.md`:

```markdown
# Hello, world!

_Emphasis_ and **importance**.

## Table of contents

## API

## License
```

`example.js`:

```js
import {remark} from 'remark'
import {read, write} from 'to-vfile'
import {reporter} from 'vfile-reporter'
import preset from './preset.js'

const file = await remark()
  .use(preset)
  .process(await read('example.md'))

console.error(reporter(file))
await write(file)
```

Yields:

```txt
example.md: no issues found
```

`example.md` now contains:

```markdown
# Hello, world!

*Emphasis* and **importance**.

## Table of contents

*   [API](#api)
*   [License](#license)

## API

## License

[MIT](license) © [Titus Wormer](https://wooorm.com)
```

### `ProcessCallback`

Callback called when the process is done (TypeScript type).

Called with either an error or a result.

###### Parameters

* `error` (`Error`, optional)
  — fatal error
* `file` ([`VFile`][vfile], optional)
  — processed file

###### Returns

Nothing (`undefined`).

###### Example

This example shows how `process` can be used to process a file with a callback.

```js
import remarkGithub from 'remark-github'
import remarkParse from 'remark-parse'
import remarkStringify from 'remark-stringify'
import {unified} from 'unified'
import {reporter} from 'vfile-reporter'

unified()
  .use(remarkParse)
  .use(remarkGithub)
  .use(remarkStringify)
  .process('@unifiedjs', function (error, file) {
    if (error) throw error
    if (file) {
      console.error(reporter(file))
      console.log(String(file))
    }
  })
```

Yields:

```txt
no issues found
```

```markdown
[**@unifiedjs**](https://github.com/unifiedjs)
```

### `Processor`

Type of a [`processor`][api-processor] (TypeScript type).

### `RunCallback`

Callback called when transformers are done (TypeScript type).

Called with either an error or results.

###### Parameters

* `error` (`Error`, optional)
  — fatal error
* `tree` ([`Node`][node], optional)
  — transformed tree
* `file` ([`VFile`][vfile], optional)
  — file

###### Returns

Nothing (`undefined`).

### `Settings`

Interface of known extra options, that can be supported by parser and
compilers.

This exists so that users can use packages such as `remark`, which configure
both parsers and compilers (in this case `remark-parse` and
`remark-stringify`), and still provide options for them.

When you make parsers or compilers, that could be packaged up together, you
should support `this.data('settings')` as input and merge it with explicitly
passed `options`.
Then, to type it, using `remark-stringify` as an example, do something like:

```ts
declare module 'unified' {
  interface Settings {
    bullet: '*' | '+' | '-'
    // …
  }
}

export {} // You may not need this, but it makes sure the file is a module.
```

###### Type

```ts
interface Settings {}
```

### `TransformCallback`

Callback passed to transforms (TypeScript type).

If the signature of a `transformer` accepts a third argument, the transformer
may perform asynchronous operations, and must call it.

###### Parameters

* `error` (`Error`, optional)
  — fatal error to stop the process
* `tree` ([`Node`][node], optional)
  — new, changed, tree
* `file` ([`VFile`][vfile], optional)
  — new, changed, file

###### Returns

Nothing (`undefined`).

### `Transformer`

Transformers handle syntax trees and files (TypeScript type).

They are functions that are called each time a syntax tree and file are
passed through the run phase.
When an error occurs in them (either because it’s thrown, returned,
rejected, or passed to `next`), the process stops.

The run phase is handled by [`trough`][trough], see its documentation for
the exact semantics of these functions.

> 👉 **Note**: you should likely ignore `next`: don’t accept it.
> it supports callback-style async work.
> But promises are likely easier to reason about.

###### Type

```ts
type Transformer<
  Input extends Node = Node,
  Output extends Node = Input
> = (
  tree: Input,
  file: VFile,
  next: TransformCallback<Output>
) =>
  | Promise<Output | undefined>
  | Output
  | Error
  | undefined
```

## Types

This package is fully typed with [TypeScript][].
It exports the additional types
[`CompileResultMap`][api-compile-result-map],
[`CompileResults`][api-compile-results],
[`Compiler`][api-compiler],
[`Data`][api-data],
[`Parser`][api-parser],
[`Pluggable`][api-pluggable],
[`PluggableList`][api-pluggable-list],
[`Plugin`][api-plugin],
[`PluginTuple`][api-plugin-tuple],
[`Preset`][api-preset],
[`ProcessCallback`][api-process-callback],
[`Processor`][api-processor],
[`RunCallback`][api-run-callback],
[`Settings`][api-settings],
[`TransformCallback`][api-transform-callback],
and [`Transformer`][api-transformer]

For TypeScript to work, it is particularly important to type your plugins
correctly.
We strongly recommend using the `Plugin` type with its generics and to use the
node types for the syntax trees provided by our packages (as in,
[`@types/hast`][types-hast], [`@types/mdast`][types-mdast],
[`@types/nlcst`][types-nlcst]).

```js
/**
 * @typedef {import('hast').Root} HastRoot
 * @typedef {import('mdast').Root} MdastRoot
 */

/**
 * @typedef Options
 *   Configuration (optional).
 * @property {boolean | null | undefined} [someField]
 *   Some option (optional).
 */

// To type options:
/** @type {import('unified').Plugin<[(Options | null | undefined)?]>} */
export function myPluginAcceptingOptions(options) {
  const settings = options || {}
  // `settings` is now `Options`.
}

// To type a plugin that works on a certain tree, without options:
/** @type {import('unified').Plugin<[], MdastRoot>} */
export function myRemarkPlugin() {
  return function (tree, file) {
    // `tree` is `MdastRoot`.
  }
}

// To type a plugin that transforms one tree into another:
/** @type {import('unified').Plugin<[], MdastRoot, HastRoot>} */
export function remarkRehype() {
  return function (tree) {
    // `tree` is `MdastRoot`.
    // Result must be `HastRoot`.
  }
}

// To type a plugin that defines a parser:
/** @type {import('unified').Plugin<[], string, MdastRoot>} */
export function remarkParse(options) {}

// To type a plugin that defines a compiler:
/** @type {import('unified').Plugin<[], HastRoot, string>} */
export function rehypeStringify(options) {}
```

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, `unified@^11`, compatible
with Node.js 16.

## Contribute

See [`contributing.md`][contributing] in [`unifiedjs/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

For info on how to submit a security report, see our
[security policy][security].

## Sponsor

Support this effort and give back by sponsoring on [OpenCollective][collective]!

<table>
<tr valign="middle">
<td width="20%" align="center" rowspan="2" colspan="2">
  <a href="https://vercel.com">Vercel</a><br><br>
  <a href="https://vercel.com"><img src="https://avatars1.githubusercontent.com/u/14985020?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
  <a href="https://motif.land">Motif</a><br><br>
  <a href="https://motif.land"><img src="https://avatars1.githubusercontent.com/u/74457950?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
  <a href="https://www.hashicorp.com">HashiCorp</a><br><br>
  <a href="https://www.hashicorp.com"><img src="https://avatars1.githubusercontent.com/u/761456?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
  <a href="https://americanexpress.io">American Express</a><br><br>
  <a href="https://americanexpress.io"><img src="https://avatars1.githubusercontent.com/u/3853301?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
  <a href="https://www.gitbook.com">GitBook</a><br><br>
  <a href="https://www.gitbook.com"><img src="https://avatars1.githubusercontent.com/u/7111340?s=256&v=4" width="128"></a>
</td>
</tr>
<tr valign="middle">
</tr>
<tr valign="middle">
<td width="20%" align="center" rowspan="2" colspan="2">
  <a href="https://www.gatsbyjs.org">Gatsby</a><br><br>
  <a href="https://www.gatsbyjs.org"><img src="https://avatars1.githubusercontent.com/u/12551863?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
  <a href="https://www.netlify.com">Netlify</a><br><br>
  <!--OC has a sharper image-->
  <a href="https://www.netlify.com"><img src="https://images.opencollective.com/netlify/4087de2/logo/256.png" width="128"></a>
</td>
<td width="10%" align="center">
  <a href="https://www.coinbase.com">Coinbase</a><br><br>
  <a href="https://www.coinbase.com"><img src="https://avatars1.githubusercontent.com/u/1885080?s=256&v=4" width="64"></a>
</td>
<td width="10%" align="center">
  <a href="https://themeisle.com">ThemeIsle</a><br><br>
  <a href="https://themeisle.com"><img src="https://avatars1.githubusercontent.com/u/58979018?s=128&v=4" width="64"></a>
</td>
<td width="10%" align="center">
  <a href="https://expo.io">Expo</a><br><br>
  <a href="https://expo.io"><img src="https://avatars1.githubusercontent.com/u/12504344?s=128&v=4" width="64"></a>
</td>
<td width="10%" align="center">
  <a href="https://boostnote.io">Boost Note</a><br><br>
  <a href="https://boostnote.io"><img src="https://images.opencollective.com/boosthub/6318083/logo/128.png" width="64"></a>
</td>
<td width="10%" align="center">
  <a href="https://markdown.space">Markdown Space</a><br><br>
  <a href="https://markdown.space"><img src="https://images.opencollective.com/markdown-space/e1038ed/logo/128.png" width="64"></a>
</td>
<td width="10%" align="center">
  <a href="https://www.holloway.com">Holloway</a><br><br>
  <a href="https://www.holloway.com"><img src="https://avatars1.githubusercontent.com/u/35904294?s=128&v=4" width="64"></a>
</td>
</tr>
<tr valign="middle">
<td width="100%" align="center" colspan="6">
  <br>
  <a href="https://opencollective.com/unified"><strong>You?</strong></a>
  <br><br>
</td>
</tr>
</table>

## Acknowledgments

Preliminary work for unified was done [in 2014][preliminary] for
**[retext][]** and inspired by [`ware`][ware].
Further incubation happened in **[remark][]**.
The project was finally [externalised][] in 2015 and [published][] as `unified`.
The project was authored by **[@wooorm](https://github.com/wooorm)**.

Although `unified` since moved its plugin architecture to [`trough`][trough],
thanks to **[@calvinfo](https://github.com/calvinfo)**,
**[@ianstormtaylor](https://github.com/ianstormtaylor)**, and others for their
work on [`ware`][ware], as it was a huge initial inspiration.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[logo]: https://raw.githubusercontent.com/unifiedjs/unified/93862e5/logo.svg?sanitize=true

[build-badge]: https://github.com/unifiedjs/unified/workflows/main/badge.svg

[build]: https://github.com/unifiedjs/unified/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/unifiedjs/unified.svg

[coverage]: https://codecov.io/github/unifiedjs/unified

[downloads-badge]: https://img.shields.io/npm/dm/unified.svg

[downloads]: https://www.npmjs.com/package/unified

[size-badge]: https://img.shields.io/bundlejs/size/unified

[size]: https://bundlejs.com/?q=unified

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/unifiedjs/unified/discussions

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[typescript]: https://www.typescriptlang.org

[health]: https://github.com/unifiedjs/.github

[contributing]: https://github.com/unifiedjs/.github/blob/main/contributing.md

[support]: https://github.com/unifiedjs/.github/blob/main/support.md

[coc]: https://github.com/unifiedjs/.github/blob/main/code-of-conduct.md

[security]: https://github.com/unifiedjs/.github/blob/main/security.md

[license]: license

[author]: https://wooorm.com

[npm]: https://docs.npmjs.com/cli/install

[site]: https://unifiedjs.com

[twitter]: https://twitter.com/unifiedjs

[rehype]: https://github.com/rehypejs/rehype

[remark]: https://github.com/remarkjs/remark

[retext]: https://github.com/retextjs/retext

[syntax-tree]: https://github.com/syntax-tree

[esast]: https://github.com/syntax-tree/esast

[hast]: https://github.com/syntax-tree/hast

[mdast]: https://github.com/syntax-tree/mdast

[nlcst]: https://github.com/syntax-tree/nlcst

[unist]: https://github.com/syntax-tree/unist

[xast]: https://github.com/syntax-tree/xast

[unified-engine]: https://github.com/unifiedjs/unified-engine

[unified-args]: https://github.com/unifiedjs/unified-args

[unified-engine-gulp]: https://github.com/unifiedjs/unified-engine-gulp

[unified-language-server]: https://github.com/unifiedjs/unified-language-server

[unified-stream]: https://github.com/unifiedjs/unified-stream

[rehype-remark]: https://github.com/rehypejs/rehype-remark

[rehype-retext]: https://github.com/rehypejs/rehype-retext

[remark-rehype]: https://github.com/remarkjs/remark-rehype

[remark-retext]: https://github.com/remarkjs/remark-retext

[node]: https://github.com/syntax-tree/unist#node

[vfile]: https://github.com/vfile/vfile

[vfile-compatible]: https://github.com/vfile/vfile#compatible

[vfile-value]: https://github.com/vfile/vfile#value

[vfile-utilities]: https://github.com/vfile/vfile#list-of-utilities

[rehype-react]: https://github.com/rehypejs/rehype-react

[trough]: https://github.com/wooorm/trough#function-fninput-next

[rehype-plugins]: https://github.com/rehypejs/rehype/blob/main/doc/plugins.md#list-of-plugins

[remark-plugins]: https://github.com/remarkjs/remark/blob/main/doc/plugins.md#list-of-plugins

[retext-plugins]: https://github.com/retextjs/retext/blob/main/doc/plugins.md#list-of-plugins

[awesome-rehype]: https://github.com/rehypejs/awesome-rehype

[awesome-remark]: https://github.com/remarkjs/awesome-remark

[awesome-retext]: https://github.com/retextjs/awesome-retext

[topic-rehype-plugin]: https://github.com/topics/rehype-plugin

[topic-remark-plugin]: https://github.com/topics/remark-plugin

[topic-retext-plugin]: https://github.com/topics/retext-plugin

[types-hast]: https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/hast

[types-mdast]: https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/mdast

[types-nlcst]: https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/nlcst

[preliminary]: https://github.com/retextjs/retext/commit/8fcb1f

[externalised]: https://github.com/remarkjs/remark/commit/9892ec

[published]: https://github.com/unifiedjs/unified/commit/2ba1cf

[ware]: https://github.com/segmentio/ware

[api]: #api

[contribute]: #contribute

[overview]: #overview

[sponsor]: #sponsor

[api-compile-result-map]: #compileresultmap

[api-compile-results]: #compileresults

[api-compiler]: #compiler

[api-data]: #data

[api-freeze]: #processorfreeze

[api-parser]: #parser

[api-pluggable]: #pluggable

[api-pluggable-list]: #pluggablelist

[api-plugin]: #plugin

[api-plugin-tuple]: #plugintuple

[api-preset]: #preset

[api-process]: #processorprocessfile-done

[api-process-callback]: #processcallback

[api-processor]: #processor

[api-run-callback]: #runcallback

[api-settings]: #settings

[api-transform-callback]: #transformcallback

[api-transformer]: #transformer


---

# unique-string

> Generate a unique random string

## Install

```
$ npm install unique-string
```

## Usage

```js
import uniqueString from 'unique-string';

uniqueString();
//=> 'b4de2a49c8ffa3fbee04446f045483b2'
```

## API

### uniqueString()

Returns a 32 character unique string. Matches the length of MD5, which is [unique enough](https://stackoverflow.com/a/2444336/64949) for non-crypto purposes.


---

# unist-util-is

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[unist][] utility to check if nodes pass a test.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`is(node[, test[, index, parent[, context]]])`](#isnode-test-index-parent-context)
    *   [`convert(test)`](#converttest)
    *   [`Check`](#check)
    *   [`Test`](#test)
    *   [`TestFunction`](#testfunction)
*   [Examples](#examples)
    *   [Example of `convert`](#example-of-convert)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package is a small utility that checks that a node is a certain node.

## When should I use this?

Use this small utility if you find yourself repeating code for checking what
nodes are.

A similar package, [`hast-util-is-element`][hast-util-is-element], works on hast
elements.

For more advanced tests, [`unist-util-select`][unist-util-select] can be used
to match against CSS selectors.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install unist-util-is
```

In Deno with [`esm.sh`][esmsh]:

```js
import {is} from 'https://esm.sh/unist-util-is@6'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {is} from 'https://esm.sh/unist-util-is@6?bundle'
</script>
```

## Use

```js
import {is} from 'unist-util-is'

const node = {type: 'strong'}
const parent = {type: 'paragraph', children: [node]}

is() // => false
is({children: []}) // => false
is(node) // => true
is(node, 'strong') // => true
is(node, 'emphasis') // => false

is(node, node) // => true
is(parent, {type: 'paragraph'}) // => true
is(parent, {type: 'strong'}) // => false

is(node, test) // => false
is(node, test, 4, parent) // => false
is(node, test, 5, parent) // => true

function test(node, n) {
  return n === 5
}
```

## API

This package exports the identifiers [`convert`][api-convert] and
[`is`][api-is].
There is no default export.

### `is(node[, test[, index, parent[, context]]])`

Check if `node` is a `Node` and whether it passes the given test.

###### Parameters

*   `node` (`unknown`, optional)
    — thing to check, typically [`Node`][node]
*   `test` ([`Test`][api-test], optional)
    — a test for a specific element
*   `index` (`number`, optional)
    — the node’s position in its parent
*   `parent` ([`Node`][node], optional)
    — the node’s parent
*   `context` (`unknown`, optional)
    — context object (`this`) to call `test` with

###### Returns

Whether `node` is a [`Node`][node] and passes a test (`boolean`).

###### Throws

When an incorrect `test`, `index`, or `parent` is given.
There is no error thrown when `node` is not a node.

### `convert(test)`

Generate a check from a test.

Useful if you’re going to test many nodes, for example when creating a
utility where something else passes a compatible test.

The created function is a bit faster because it expects valid input only:
a `node`, `index`, and `parent`.

###### Parameters

*   `test` ([`Test`][api-test], optional)
    — a test for a specific node

###### Returns

A check ([`Check`][api-check]).

### `Check`

Check that an arbitrary value is a node (TypeScript type).

###### Parameters

*   `this` (`unknown`, optional)
    — context object (`this`) to call `test` with
*   `node` (`unknown`)
    — anything (typically a node)
*   `index` (`number`, optional)
    — the node’s position in its parent
*   `parent` ([`Node`][node], optional)
    — the node’s parent

###### Returns

Whether this is a node and passes a test (`boolean`).

### `Test`

Check for an arbitrary node (TypeScript type).

###### Type

```ts
type Test =
  | Array<Record<string, unknown> | TestFunction | string>
  | Record<string, unknown>
  | TestFunction
  | string
  | null
  | undefined
```

Checks that the given thing is a node, and then:

*   when `string`, checks that the node has that tag name
*   when `function`, see  [`TestFunction`][api-test-function]
*   when `object`, checks that all keys in test are in node, and that they have
    (strictly) equal values
*   when `Array`, checks if one of the subtests pass

### `TestFunction`

Check if a node passes a test (TypeScript type).

###### Parameters

*   `node` ([`Node`][node])
    — a node
*   `index` (`number` or `undefined`)
    — the node’s position in its parent
*   `parent` ([`Node`][node] or `undefined`)
    — the node’s parent

###### Returns

Whether this node passes the test (`boolean`, optional).

## Examples

### Example of `convert`

```js
import {u} from 'unist-builder'
import {convert} from 'unist-util-is'

const test = convert('leaf')

const tree = u('tree', [
  u('node', [u('leaf', '1')]),
  u('leaf', '2'),
  u('node', [u('leaf', '3'), u('leaf', '4')]),
  u('leaf', '5')
])

const leafs = tree.children.filter(function (child, index) {
  return test(child, index, tree)
})

console.log(leafs)
```

Yields:

```js
[{type: 'leaf', value: '2'}, {type: 'leaf', value: '5'}]
```

## Types

This package is fully typed with [TypeScript][].
It exports the additional types [`Check`][api-check],
[`Test`][api-test],
[`TestFunction`][api-test-function].

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, `unist-util-is@^6`,
compatible with Node.js 16.

## Related

*   [`unist-util-find-after`](https://github.com/syntax-tree/unist-util-find-after)
    — find a node after another node
*   [`unist-util-find-before`](https://github.com/syntax-tree/unist-util-find-before)
    — find a node before another node
*   [`unist-util-find-all-after`](https://github.com/syntax-tree/unist-util-find-all-after)
    — find all nodes after another node
*   [`unist-util-find-all-before`](https://github.com/syntax-tree/unist-util-find-all-before)
    — find all nodes before another node
*   [`unist-util-find-all-between`](https://github.com/mrzmmr/unist-util-find-all-between)
    — find all nodes between two nodes
*   [`unist-util-filter`](https://github.com/syntax-tree/unist-util-filter)
    — create a new tree with nodes that pass a check
*   [`unist-util-remove`](https://github.com/syntax-tree/unist-util-remove)
    — remove nodes from tree

## Contribute

See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
ways to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/syntax-tree/unist-util-is/workflows/main/badge.svg

[build]: https://github.com/syntax-tree/unist-util-is/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/unist-util-is.svg

[coverage]: https://codecov.io/github/syntax-tree/unist-util-is

[downloads-badge]: https://img.shields.io/npm/dm/unist-util-is.svg

[downloads]: https://www.npmjs.com/package/unist-util-is

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=unist-util-is

[size]: https://bundlejs.com/?q=unist-util-is

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/syntax-tree/unist/discussions

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[typescript]: https://www.typescriptlang.org

[license]: license

[author]: https://wooorm.com

[health]: https://github.com/syntax-tree/.github

[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md

[support]: https://github.com/syntax-tree/.github/blob/main/support.md

[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md

[unist]: https://github.com/syntax-tree/unist

[node]: https://github.com/syntax-tree/unist#node

[hast-util-is-element]: https://github.com/syntax-tree/hast-util-is-element

[unist-util-select]: https://github.com/syntax-tree/unist-util-select

[api-convert]: #converttest

[api-is]: #isnode-test-index-parent-context

[api-check]: #check

[api-test]: #test

[api-test-function]: #testfunction


---

# unist-util-position

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[unist][] utility to get positional info of nodes.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`position(node)`](#positionnode)
    *   [`pointEnd(node)`](#pointendnode)
    *   [`pointStart(node)`](#pointstartnode)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This utility helps with accessing positional info on a potentially dirty tree.

## When should I use this?

The positional info is typically consistent and proper in unist trees generated
by our ecosystem, but, user plugins could mess that up.
If you’re making a reusable plugin, and accessing the positional info often, you
might want to guard against that by using this utility.

You might also find the utility [`unist-util-generated`][unist-util-generated]
useful to check whether a node is considered to be generated (not in the
original input file).

You might also enjoy
[`unist-util-stringify-position`][unist-util-stringify-position] when you want
to display positional info to users.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install unist-util-position
```

In Deno with [`esm.sh`][esmsh]:

```js
import {pointEnd, pointStart, position} from 'https://esm.sh/unist-util-position@5'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {pointEnd, pointStart, position} from 'https://esm.sh/unist-util-position@5?bundle'
</script>
```

## Use

```js
import {fromMarkdown} from 'mdast-util-from-markdown'
import {pointEnd, pointStart, position} from 'unist-util-position'

const tree = fromMarkdown('# foo\n\n* bar\n')

console.log(position(tree))
console.log(pointStart(tree))
console.log(pointEnd(tree))
```

Yields:

```js
{start: {line: 1, column: 1, offset: 0}, end: {line: 4, column: 1, offset: 13}}
{line: 1, column: 1, offset: 0}
{line: 4, column: 1, offset: 13}
```

## API

This package exports the identifiers [`pointEnd`][pointend],
[`pointStart`][pointstart], and [`position`][position].
There is no default export.

### `position(node)`

Get the positional info of `node`.

###### Parameters

*   `node` ([`Node`][node])
    — node

###### Returns

Position, if valid ([`Position`][unist-position] or `undefined`).

### `pointEnd(node)`

Get the ending point of `node`.

###### Parameters

*   `node` ([`Node`][node])
    — node

###### Returns

Point, if valid ([`Point`][unist-point] or `undefined`).

### `pointStart(node)`

Get the starting point of `node`.

###### Parameters

*   `node` ([`Node`][node])
    — node

###### Returns

Point, if valid ([`Point`][unist-point] or `undefined`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, `unist-util-position@^5`,
compatible with Node.js 16.

## Related

*   [`unist-util-stringify-position`](https://github.com/syntax-tree/unist-util-stringify-position)
    — serialize a node, position, or point as a human readable location
*   [`unist-util-position-from-estree`](https://github.com/syntax-tree/unist-util-position-from-estree)
    — get a position from an estree node
*   [`unist-util-remove-position`](https://github.com/syntax-tree/unist-util-remove-position)
    — remove positions from tree
*   [`unist-util-generated`](https://github.com/syntax-tree/unist-util-generated)
    — check if a node is generated
*   [`unist-util-source`](https://github.com/syntax-tree/unist-util-source)
    — get the source of a node

## Contribute

See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
ways to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/syntax-tree/unist-util-position/workflows/main/badge.svg

[build]: https://github.com/syntax-tree/unist-util-position/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/unist-util-position.svg

[coverage]: https://codecov.io/github/syntax-tree/unist-util-position

[downloads-badge]: https://img.shields.io/npm/dm/unist-util-position.svg

[downloads]: https://www.npmjs.com/package/unist-util-position

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=unist-util-position

[size]: https://bundlejs.com/?q=unist-util-position

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/syntax-tree/unist/discussions

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[typescript]: https://www.typescriptlang.org

[license]: license

[author]: https://wooorm.com

[health]: https://github.com/syntax-tree/.github

[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md

[support]: https://github.com/syntax-tree/.github/blob/main/support.md

[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md

[unist]: https://github.com/syntax-tree/unist

[node]: https://github.com/syntax-tree/unist#node

[unist-position]: https://github.com/syntax-tree/unist#position

[unist-point]: https://github.com/syntax-tree/unist#point

[unist-util-generated]: https://github.com/syntax-tree/unist-util-generated

[unist-util-stringify-position]: https://github.com/syntax-tree/unist-util-stringify-position

[position]: #positionnode

[pointend]: #pointendnode

[pointstart]: #pointstartnode


---

# unist-util-position-from-estree

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[unist][] utility to get a position from an [estree][] node.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`positionFromEstree(node)`](#positionfromestreenode)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package is a tiny utility that can create a proper unist position from
an estree node

## When should I use this?

You can use this package when you want to use other unist utilities with estree
nodes.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install unist-util-position-from-estree
```

In Deno with [`esm.sh`][esmsh]:

```js
import {positionFromEstree} from 'https://esm.sh/unist-util-position-from-estree@2'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {positionFromEstree} from 'https://esm.sh/unist-util-position-from-estree@2?bundle'
</script>
```

## Use

```js
import {parse} from 'acorn'
import {positionFromEstree} from 'unist-util-position-from-estree'

// Make acorn support line/column.
const node = parse('function x() { console.log(1) }', {
  ecmaVersion: 2020,
  locations: true
})

console.log(positionFromEstree(node)) // `Program`
console.log(positionFromEstree(node.body[0].id)) // `x`
console.log(positionFromEstree(node.body[0].body.body[0].expression)) // Call
```

Yields:

```js
{
  start: {line: 1, column: 1, offset: 0},
  end: {line: 1, column: 32, offset: 31}
}
{
  start: {line: 1, column: 10, offset: 9},
  end: {line: 1, column: 11, offset: 10}
}
{
  start: {line: 1, column: 16, offset: 15},
  end: {line: 1, column: 30, offset: 29}
}
```

## API

This package exports the identifier [`positionFromEstree`][positionfromestree].
There is no default export.

### `positionFromEstree(node)`

Turn an estree `node` into a unist `position`.

###### Parameters

*   `node` ([`Node`][node])
    — estree node

###### Returns

unist position, if valid ([`Position`][position] or `undefined`).

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`unist-util-position-from-estree@^2`, compatible with Node.js 16.

## Contribute

See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
ways to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definition -->

[build-badge]: https://github.com/syntax-tree/unist-util-position-from-estree/workflows/main/badge.svg

[build]: https://github.com/syntax-tree/unist-util-position-from-estree/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/unist-util-position-from-estree.svg

[coverage]: https://codecov.io/github/syntax-tree/unist-util-position-from-estree

[downloads-badge]: https://img.shields.io/npm/dm/unist-util-position-from-estree.svg

[downloads]: https://www.npmjs.com/package/unist-util-position-from-estree

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=unist-util-position-from-estree

[size]: https://bundlejs.com/?q=unist-util-position-from-estree

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/syntax-tree/unist/discussions

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[typescript]: https://www.typescriptlang.org

[license]: license

[author]: https://wooorm.com

[health]: https://github.com/syntax-tree/.github

[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md

[support]: https://github.com/syntax-tree/.github/blob/main/support.md

[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md

[estree]: https://github.com/estree/estree

[node]: https://github.com/estree/estree/blob/master/es5.md#node-objects

[unist]: https://github.com/syntax-tree/unist

[position]: https://github.com/syntax-tree/unist#position

[positionfromestree]: #positionfromestreenode


---

# unist-util-stringify-position

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[unist][] utility to pretty print the positional info of a node.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`stringifyPosition(node|position|point)`](#stringifypositionnodepositionpoint)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Security](#security)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package is a utility that takes any [unist][] (whether mdast, hast, etc)
node, position, or point, and serializes its positional info.

## When should I use this?

This utility is useful to display where something occurred in the original
document, in one standard way, for humans.
For example, when throwing errors or warning messages about something.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install unist-util-stringify-position
```

In Deno with [`esm.sh`][esmsh]:

```js
import {stringifyPosition} from 'https://esm.sh/unist-util-stringify-position@4'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {stringifyPosition} from 'https://esm.sh/unist-util-stringify-position@4?bundle'
</script>
```

## Use

```js
import {stringifyPosition} from 'unist-util-stringify-position'

stringifyPosition({line: 2, column: 3}) // => '2:3' (point)
stringifyPosition({start: {line: 2}, end: {line: 3}}) // => '2:1-3:1' (position)
stringifyPosition({
  type: 'text',
  value: '!',
  position: {
    start: {line: 5, column: 11},
    end: {line: 5, column: 12}
  }
}) // => '5:11-5:12' (node)
```

## API

This package exports the identifier [`stringifyPosition`][stringifyposition].
There is no default export.

### `stringifyPosition(node|position|point)`

Serialize the positional info of a point, position (start and end points), or
node.

###### Parameters

*   `node` ([`Node`][node])
    — node whose `position` fields to serialize
*   `position` ([`Position`][position])
    — position whose `start` and `end` points to serialize
*   `point` ([`Point`][point])
    — point whose `line` and `column` fields to serialize

###### Returns

Pretty printed positional info of a node (`string`).

In the format of a range `ls:cs-le:ce` (when given `node` or `position`) or a
point `l:c` (when given `point`), where `l` stands for line, `c` for column, `s`
for `start`, and `e` for end.
An empty string (`''`) is returned if the given value is neither `node`,
`position`, nor `point`.

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`unist-util-stringify-position@^4`, compatible with Node.js 16.

## Security

This project is safe.

## Related

*   [`unist-util-generated`](https://github.com/syntax-tree/unist-util-generated)
    — check if a node is generated
*   [`unist-util-position`](https://github.com/syntax-tree/unist-util-position)
    — get positional info of nodes
*   [`unist-util-remove-position`](https://github.com/syntax-tree/unist-util-remove-position)
    — remove positional info from trees
*   [`unist-util-source`](https://github.com/syntax-tree/unist-util-source)
    — get the source of a value (node or position) in a file

## Contribute

See [`contributing.md` in `syntax-tree/.github`][contributing] for ways to get
started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definition -->

[build-badge]: https://github.com/syntax-tree/unist-util-stringify-position/workflows/main/badge.svg

[build]: https://github.com/syntax-tree/unist-util-stringify-position/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/unist-util-stringify-position.svg

[coverage]: https://codecov.io/github/syntax-tree/unist-util-stringify-position

[downloads-badge]: https://img.shields.io/npm/dm/unist-util-stringify-position.svg

[downloads]: https://www.npmjs.com/package/unist-util-stringify-position

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=unist-util-stringify-position

[size]: https://bundlejs.com/?q=unist-util-stringify-position

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/syntax-tree/unist/discussions

[npm]: https://docs.npmjs.com/cli/install

[license]: license

[author]: https://wooorm.com

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[typescript]: https://www.typescriptlang.org

[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md

[support]: https://github.com/syntax-tree/.github/blob/main/support.md

[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md

[unist]: https://github.com/syntax-tree/unist

[node]: https://github.com/syntax-tree/unist#node

[position]: https://github.com/syntax-tree/unist#position

[point]: https://github.com/syntax-tree/unist#point

[stringifyposition]: #stringifypositionnodepositionpoint


---

# unist-util-visit

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[unist][] utility to walk the tree.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`visit(tree[, test], visitor[, reverse])`](#visittree-test-visitor-reverse)
    *   [`CONTINUE`](#continue)
    *   [`EXIT`](#exit)
    *   [`SKIP`](#skip)
    *   [`Action`](#action)
    *   [`ActionTuple`](#actiontuple)
    *   [`BuildVisitor`](#buildvisitor)
    *   [`Index`](#index)
    *   [`Test`](#test)
    *   [`Visitor`](#visitor)
    *   [`VisitorResult`](#visitorresult)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This is a very important utility for working with unist as it lets you walk the
tree.

## When should I use this?

You can use this utility when you want to walk the tree.
You can use [`unist-util-visit-parents`][vp] if you care about the entire stack
of parents.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install unist-util-visit
```

In Deno with [`esm.sh`][esmsh]:

```js
import {CONTINUE, EXIT, SKIP, visit} from 'https://esm.sh/unist-util-visit@5'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {CONTINUE, EXIT, SKIP, visit} from 'https://esm.sh/unist-util-visit@5?bundle'
</script>
```

## Use

```js
import {fromMarkdown} from 'mdast-util-from-markdown'
import {visit} from 'unist-util-visit'

const tree = fromMarkdown('Some *emphasis*, **strong**, and `code`.')

visit(tree, 'text', function (node, index, parent) {
  console.log([node.value, parent ? parent.type : index])
})
```

Yields:

```js
[ 'Some ', 'paragraph' ]
[ 'emphasis', 'emphasis' ]
[ ', ', 'paragraph' ]
[ 'strong', 'strong' ]
[ ', and ', 'paragraph' ]
[ '.', 'paragraph' ]
```

## API

This package exports the identifiers [`CONTINUE`][api-continue],
[`EXIT`][api-exit], [`SKIP`][api-skip], and [`visit`][api-visit].
There is no default export.

### `visit(tree[, test], visitor[, reverse])`

This function works exactly the same as [`unist-util-visit-parents`][vp],
but [`Visitor`][api-visitor] has a different signature.

### `CONTINUE`

Continue traversing as normal (`true`).

### `EXIT`

Stop traversing immediately (`false`).

### `SKIP`

Do not traverse this node’s children (`'skip'`).

### `Action`

Union of the action types (TypeScript type).
See [`Action` in `unist-util-visit-parents`][vp-action].

### `ActionTuple`

List with an action and an index (TypeScript type).
See [`ActionTuple` in `unist-util-visit-parents`][vp-action-tuple].

### `BuildVisitor`

Build a typed `Visitor` function from a tree and a test (TypeScript type).
See [`BuildVisitor` in `unist-util-visit-parents`][vp-build-visitor].

### `Index`

Move to the sibling at `index` next (TypeScript type).
See [`Index` in `unist-util-visit-parents`][vp-index].

### `Test`

[`unist-util-is`][unist-util-is] compatible test (TypeScript type).

### `Visitor`

Handle a node (matching `test`, if given) (TypeScript type).

Visitors are free to transform `node`.
They can also transform `parent`.

Replacing `node` itself, if `SKIP` is not returned, still causes its
descendants to be walked (which is a bug).

When adding or removing previous siblings of `node` (or next siblings, in
case of reverse), the `Visitor` should return a new `Index` to specify the
sibling to traverse after `node` is traversed.
Adding or removing next siblings of `node` (or previous siblings, in case
of reverse) is handled as expected without needing to return a new `Index`.

Removing the children property of `parent` still results in them being
traversed.

###### Parameters

*   `node` ([`Node`][node])
    — found node
*   `index` (`number` or `undefined`)
    — index of `node` in `parent`
*   `parent` ([`Node`][node] or `undefined`)
    — parent of `node`

###### Returns

What to do next.

An `Index` is treated as a tuple of `[CONTINUE, Index]`.
An `Action` is treated as a tuple of `[Action]`.

Passing a tuple back only makes sense if the `Action` is `SKIP`.
When the `Action` is `EXIT`, that action can be returned.
When the `Action` is `CONTINUE`, `Index` can be returned.

### `VisitorResult`

Any value that can be returned from a visitor (TypeScript type).
See [`VisitorResult` in `unist-util-visit-parents`][vp-visitor-result].

## Types

This package is fully typed with [TypeScript][].
It exports the additional types [`Action`][api-action],
[`ActionTuple`][api-action-tuple], [`BuildVisitor`][api-build-visitor],
[`Index`][api-index], [`Test`][api-test], [`Visitor`][api-visitor], and
[`VisitorResult`][api-visitor-result].

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, `unist-util-visit@^5`,
compatible with Node.js 16.

## Related

*   [`unist-util-visit-parents`][vp]
    — walk the tree with a stack of parents
*   [`unist-util-filter`](https://github.com/syntax-tree/unist-util-filter)
    — create a new tree with all nodes that pass a test
*   [`unist-util-map`](https://github.com/syntax-tree/unist-util-map)
    — create a new tree with all nodes mapped by a given function
*   [`unist-util-flatmap`](https://gitlab.com/staltz/unist-util-flatmap)
    — create a new tree by mapping (to an array) with the given function
*   [`unist-util-remove`](https://github.com/syntax-tree/unist-util-remove)
    — remove nodes from a tree that pass a test
*   [`unist-util-select`](https://github.com/syntax-tree/unist-util-select)
    — select nodes with CSS-like selectors

## Contribute

See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
ways to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definition -->

[build-badge]: https://github.com/syntax-tree/unist-util-visit/workflows/main/badge.svg

[build]: https://github.com/syntax-tree/unist-util-visit/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/unist-util-visit.svg

[coverage]: https://codecov.io/github/syntax-tree/unist-util-visit

[downloads-badge]: https://img.shields.io/npm/dm/unist-util-visit.svg

[downloads]: https://www.npmjs.com/package/unist-util-visit

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=unist-util-visit

[size]: https://bundlejs.com/?q=unist-util-visit

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/syntax-tree/unist/discussions

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[typescript]: https://www.typescriptlang.org

[license]: license

[author]: https://wooorm.com

[health]: https://github.com/syntax-tree/.github

[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md

[support]: https://github.com/syntax-tree/.github/blob/main/support.md

[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md

[unist]: https://github.com/syntax-tree/unist

[node]: https://github.com/syntax-tree/unist#nodes

[unist-util-is]: https://github.com/syntax-tree/unist-util-is

[vp]: https://github.com/syntax-tree/unist-util-visit-parents

[vp-action]: https://github.com/syntax-tree/unist-util-visit-parents#action

[vp-action-tuple]: https://github.com/syntax-tree/unist-util-visit-parents#actiontuple

[vp-build-visitor]: https://github.com/syntax-tree/unist-util-visit-parents#buildvisitor

[vp-index]: https://github.com/syntax-tree/unist-util-visit-parents#index

[vp-visitor-result]: https://github.com/syntax-tree/unist-util-visit-parents#visitorresult

[api-visit]: #visittree-test-visitor-reverse

[api-continue]: #continue

[api-exit]: #exit

[api-skip]: #skip

[api-action]: #action

[api-action-tuple]: #actiontuple

[api-build-visitor]: #buildvisitor

[api-index]: #index

[api-test]: #test

[api-visitor]: #visitor

[api-visitor-result]: #visitorresult


---

# unist-util-visit-parents

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[unist][] utility to walk the tree with a stack of parents.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`visitParents(tree[, test], visitor[, reverse])`](#visitparentstree-test-visitor-reverse)
    *   [`CONTINUE`](#continue)
    *   [`EXIT`](#exit)
    *   [`SKIP`](#skip)
    *   [`Action`](#action)
    *   [`ActionTuple`](#actiontuple)
    *   [`BuildVisitor`](#buildvisitor)
    *   [`Index`](#index)
    *   [`Test`](#test)
    *   [`Visitor`](#visitor)
    *   [`VisitorResult`](#visitorresult)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This is a very important utility for working with unist as it lets you walk the
tree.

## When should I use this?

You can use this utility when you want to walk the tree and want to know about
every parent of each node.
You can use [`unist-util-visit`][unist-util-visit] if you don’t care about the
entire stack of parents.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install unist-util-visit-parents
```

In Deno with [`esm.sh`][esmsh]:

```js
import {visitParents} from 'https://esm.sh/unist-util-visit-parents@6'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {visitParents} from 'https://esm.sh/unist-util-visit-parents@6?bundle'
</script>
```

## Use

```js
import {visitParents} from 'unist-util-visit-parents'
import {fromMarkdown} from 'mdast-util-from-markdown'

const tree = fromMarkdown('Some *emphasis*, **strong**, and `code`.')

visitParents(tree, 'strong', function (node, ancestors) {
  console.log(node.type, ancestors.map(ancestor => ancestor.type))
})
```

Yields:

```js
strong ['root', 'paragraph']
```

## API

This package exports the identifiers [`CONTINUE`][api-continue],
[`EXIT`][api-exit], [`SKIP`][api-skip], and [`visitParents`][api-visitparents].
There is no default export.

### `visitParents(tree[, test], visitor[, reverse])`

Visit nodes, with ancestral information.

This algorithm performs *[depth-first][]* *[tree traversal][tree-traversal]*
in *[preorder][]* (**NLR**) or if `reverse` is given, in *reverse preorder*
(**NRL**).

You can choose for which nodes `visitor` is called by passing a `test`.
For complex tests, you should test yourself in `visitor`, as it will be
faster and will have improved type information.

Walking the tree is an intensive task.
Make use of the return values of the visitor when possible.
Instead of walking a tree multiple times, walk it once, use
[`unist-util-is`][unist-util-is] to check if a node matches, and then perform
different operations.

You can change the tree.
See [`Visitor`][api-visitor] for more info.

###### Parameters

*   `tree` ([`Node`][node])
    — tree to traverse
*   `test` ([`Test`][api-test], optional)
    — [`unist-util-is`][unist-util-is]-compatible test
*   `visitor` ([`Visitor`][api-visitor])
    — handle each node
*   `reverse` (`boolean`, default: `false`)
    — traverse in reverse preorder (NRL) instead of the default preorder (NLR)

###### Returns

Nothing (`undefined`).

### `CONTINUE`

Continue traversing as normal (`true`).

### `EXIT`

Stop traversing immediately (`false`).

### `SKIP`

Do not traverse this node’s children (`'skip'`).

### `Action`

Union of the action types (TypeScript type).

###### Type

```ts
type Action = typeof CONTINUE | typeof EXIT | typeof SKIP
```

### `ActionTuple`

List with one or two values, the first an action, the second an index
(TypeScript type).

###### Type

```ts
type ActionTuple = [
  (Action | null | undefined | void)?,
  (Index | null | undefined)?
]
```

### `BuildVisitor`

Build a typed `Visitor` function from a tree and a test (TypeScript type).

It will infer which values are passed as `node` and which as `parents`.

###### Type parameters

*   `Tree` ([`Node`][node], default: `Node`)
    — tree type
*   `Check` ([`Test`][api-test], default: `Test`)
    — test type

###### Returns

[`Visitor`][api-visitor].

### `Index`

Move to the sibling at `index` next (after node itself is completely
traversed) (TypeScript type).

Useful if mutating the tree, such as removing the node the visitor is currently
on, or any of its previous siblings.
Results less than `0` or greater than or equal to `children.length` stop
traversing the parent.

###### Type

```ts
type Index = number
```

### `Test`

[`unist-util-is`][unist-util-is] compatible test (TypeScript type).

### `Visitor`

Handle a node (matching `test`, if given) (TypeScript type).

Visitors are free to transform `node`.
They can also transform the parent of node (the last of `ancestors`).

Replacing `node` itself, if `SKIP` is not returned, still causes its
descendants to be walked (which is a bug).

When adding or removing previous siblings of `node` (or next siblings, in
case of reverse), the `Visitor` should return a new `Index` to specify the
sibling to traverse after `node` is traversed.
Adding or removing next siblings of `node` (or previous siblings, in case
of reverse) is handled as expected without needing to return a new `Index`.

Removing the children property of an ancestor still results in them being
traversed.

###### Parameters

*   `node` ([`Node`][node])
    — found node
*   `parents` ([`Array<Node>`][node])
    — ancestors of `node`

###### Returns

What to do next.

An `Index` is treated as a tuple of `[CONTINUE, Index]`.
An `Action` is treated as a tuple of `[Action]`.

Passing a tuple back only makes sense if the `Action` is `SKIP`.
When the `Action` is `EXIT`, that action can be returned.
When the `Action` is `CONTINUE`, `Index` can be returned.

### `VisitorResult`

Any value that can be returned from a visitor (TypeScript type).

###### Type

```ts
type VisitorResult =
  | Action
  | ActionTuple
  | Index
  | null
  | undefined
  | void
```

## Types

This package is fully typed with [TypeScript][].
It exports the additional types [`Action`][api-action],
[`ActionTuple`][api-actiontuple], [`BuildVisitor`][api-buildvisitor],
[`Index`][api-index], [`Test`][api-test], [`Visitor`][api-visitor], and
[`VisitorResult`][api-visitorresult].

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`unist-util-visit-parents@^6`, compatible with Node.js 16.

## Related

*   [`unist-util-visit`](https://github.com/syntax-tree/unist-util-visit)
    — walk the tree with one parent
*   [`unist-util-filter`](https://github.com/syntax-tree/unist-util-filter)
    — create a new tree with all nodes that pass a test
*   [`unist-util-map`](https://github.com/syntax-tree/unist-util-map)
    — create a new tree with all nodes mapped by a given function
*   [`unist-util-flatmap`](https://gitlab.com/staltz/unist-util-flatmap)
    — create a new tree by mapping (to an array) with the given function
*   [`unist-util-remove`](https://github.com/syntax-tree/unist-util-remove)
    — remove nodes from a tree that pass a test
*   [`unist-util-select`](https://github.com/syntax-tree/unist-util-select)
    — select nodes with CSS-like selectors

## Contribute

See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
ways to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definition -->

[build-badge]: https://github.com/syntax-tree/unist-util-visit-parents/workflows/main/badge.svg

[build]: https://github.com/syntax-tree/unist-util-visit-parents/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/unist-util-visit-parents.svg

[coverage]: https://codecov.io/github/syntax-tree/unist-util-visit-parents

[downloads-badge]: https://img.shields.io/npm/dm/unist-util-visit-parents.svg

[downloads]: https://www.npmjs.com/package/unist-util-visit-parents

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=unist-util-visit-parents

[size]: https://bundlejs.com/?q=unist-util-visit-parents

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/syntax-tree/unist/discussions

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[typescript]: https://www.typescriptlang.org

[license]: license

[author]: https://wooorm.com

[health]: https://github.com/syntax-tree/.github

[contributing]: https://github.com/syntax-tree/.github/blob/HEAD/contributing.md

[support]: https://github.com/syntax-tree/.github/blob/HEAD/support.md

[coc]: https://github.com/syntax-tree/.github/blob/HEAD/code-of-conduct.md

[unist]: https://github.com/syntax-tree/unist

[node]: https://github.com/syntax-tree/unist#node

[depth-first]: https://github.com/syntax-tree/unist#depth-first-traversal

[tree-traversal]: https://github.com/syntax-tree/unist#tree-traversal

[preorder]: https://github.com/syntax-tree/unist#preorder

[unist-util-visit]: https://github.com/syntax-tree/unist-util-visit

[unist-util-is]: https://github.com/syntax-tree/unist-util-is

[api-visitparents]: #visitparentstree-test-visitor-reverse

[api-continue]: #continue

[api-exit]: #exit

[api-skip]: #skip

[api-action]: #action

[api-actiontuple]: #actiontuple

[api-buildvisitor]: #buildvisitor

[api-index]: #index

[api-test]: #test

[api-visitor]: #visitor

[api-visitorresult]: #visitorresult


---

# universalify

![GitHub Workflow Status (branch)](https://img.shields.io/github/actions/workflow/status/RyanZim/universalify/ci.yml?branch=master)
![Coveralls github branch](https://img.shields.io/coveralls/github/RyanZim/universalify/master.svg)
![npm](https://img.shields.io/npm/dm/universalify.svg)
![npm](https://img.shields.io/npm/l/universalify.svg)

Make a callback- or promise-based function support both promises and callbacks.

Uses the native promise implementation.

## Installation

```bash
npm install universalify
```

## API

### `universalify.fromCallback(fn)`

Takes a callback-based function to universalify, and returns the universalified  function.

Function must take a callback as the last parameter that will be called with the signature `(error, result)`. `universalify` does not support calling the callback with three or more arguments, and does not ensure that the callback is only called once.

```js
function callbackFn (n, cb) {
  setTimeout(() => cb(null, n), 15)
}

const fn = universalify.fromCallback(callbackFn)

// Works with Promises:
fn('Hello World!')
.then(result => console.log(result)) // -> Hello World!
.catch(error => console.error(error))

// Works with Callbacks:
fn('Hi!', (error, result) => {
  if (error) return console.error(error)
  console.log(result)
  // -> Hi!
})
```

### `universalify.fromPromise(fn)`

Takes a promise-based function to universalify, and returns the universalified  function.

Function must return a valid JS promise. `universalify` does not ensure that a valid promise is returned.

```js
function promiseFn (n) {
  return new Promise(resolve => {
    setTimeout(() => resolve(n), 15)
  })
}

const fn = universalify.fromPromise(promiseFn)

// Works with Promises:
fn('Hello World!')
.then(result => console.log(result)) // -> Hello World!
.catch(error => console.error(error))

// Works with Callbacks:
fn('Hi!', (error, result) => {
  if (error) return console.error(error)
  console.log(result)
  // -> Hi!
})
```

## License

MIT


---

1.0.0 / 2015-06-14
==================

  * Initial release


---

# unpipe

[![NPM Version][npm-image]][npm-url]
[![NPM Downloads][downloads-image]][downloads-url]
[![Node.js Version][node-image]][node-url]
[![Build Status][travis-image]][travis-url]
[![Test Coverage][coveralls-image]][coveralls-url]

Unpipe a stream from all destinations.

## Installation

```sh
$ npm install unpipe
```

## API

```js
var unpipe = require('unpipe')
```

### unpipe(stream)

Unpipes all destinations from a given stream. With stream 2+, this is
equivalent to `stream.unpipe()`. When used with streams 1 style streams
(typically Node.js 0.8 and below), this module attempts to undo the
actions done in `stream.pipe(dest)`.

## License

[MIT](LICENSE)

[npm-image]: https://img.shields.io/npm/v/unpipe.svg
[npm-url]: https://npmjs.org/package/unpipe
[node-image]: https://img.shields.io/node/v/unpipe.svg
[node-url]: http://nodejs.org/download/
[travis-image]: https://img.shields.io/travis/stream-utils/unpipe.svg
[travis-url]: https://travis-ci.org/stream-utils/unpipe
[coveralls-image]: https://img.shields.io/coveralls/stream-utils/unpipe.svg
[coveralls-url]: https://coveralls.io/r/stream-utils/unpipe?branch=master
[downloads-image]: https://img.shields.io/npm/dm/unpipe.svg
[downloads-url]: https://npmjs.org/package/unpipe


---

# Update Browserslist DB

<img width="120" height="120" alt="Browserslist logo by Anton Popov"
     src="https://browsersl.ist/logo.svg" align="right">

CLI tool to update `caniuse-lite` with browsers DB
from [Browserslist](https://github.com/browserslist/browserslist/) config.

Some queries like `last 2 versions` or `>1%` depend on actual data
from `caniuse-lite`.

```sh
npx update-browserslist-db@latest
```

<a href="https://evilmartians.com/?utm_source=update-browserslist-db">
  <img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg"
       alt="Sponsored by Evil Martians" width="236" height="54">
</a>

## Docs
Read full docs **[here](https://github.com/browserslist/update-db#readme)**.


---

# boxen

> Create boxes in the terminal

![](screenshot.png)

## Install

```sh
npm install boxen
```

## Usage

```js
import boxen from 'boxen';

console.log(boxen('unicorn', {padding: 1}));
/*
┌─────────────┐
│             │
│   unicorn   │
│             │
└─────────────┘
*/

console.log(boxen('unicorn', {padding: 1, margin: 1, borderStyle: 'double'}));
/*

   ╔═════════════╗
   ║             ║
   ║   unicorn   ║
   ║             ║
   ╚═════════════╝

*/

console.log(boxen('unicorns love rainbows', {title: 'magical', titleAlignment: 'center'}));
/*
┌────── magical ───────┐
│unicorns love rainbows│
└──────────────────────┘
*/
```

## API

### boxen(text, options?)

#### text

Type: `string`

Text inside the box.

#### options

Type: `object`

##### borderColor

Type: `string`\
Values: `'black'` `'red'` `'green'` `'yellow'` `'blue'` `'magenta'` `'cyan'` `'white'` `'gray'` or a hex value like `'#ff0000'`

Color of the box border.

##### borderStyle

Type: `string | object`\
Default: `'single'`\
Values:
- `'single'`
```
┌───┐
│foo│
└───┘
```
- `'double'`
```
╔═══╗
║foo║
╚═══╝
```
- `'round'` (`'single'` sides with round corners)
```
╭───╮
│foo│
╰───╯
```
- `'bold'`
```
┏━━━┓
┃foo┃
┗━━━┛
```
- `'singleDouble'` (`'single'` on top and bottom, `'double'` on right and left)
```
╓───╖
║foo║
╙───╜
```
- `'doubleSingle'` (`'double'` on top and bottom, `'single'` on right and left)
```
╒═══╕
│foo│
╘═══╛
```
- `'classic'`
```
+---+
|foo|
+---+
```
- `'arrow'`
```
↘↓↓↓↙
→foo←
↗↑↑↑↖
```
- `'none'`
```
foo
```

Style of the box border.

Can be any of the above predefined styles or an object with the following keys:

```js
{
	topLeft: '+',
	topRight: '+',
	bottomLeft: '+',
	bottomRight: '+',
	top: '-',
	bottom: '-',
	left: '|',
	right: '|'
}
```

##### dimBorder

Type: `boolean`\
Default: `false`

Reduce opacity of the border.

##### title

Type: `string`

Display a title at the top of the box.
If needed, the box will horizontally expand to fit the title.

Example:
```js
console.log(boxen('foo bar', {title: 'example'}));
/*
┌ example ┐
│foo bar  │
└─────────┘
*/
```

##### titleAlignment

Type: `string`\
Default: `'left'`

Align the title in the top bar.

Values:
- `'left'`
```js
/*
┌ example ──────┐
│foo bar foo bar│
└───────────────┘
*/
```
- `'center'`
```js
/*
┌─── example ───┐
│foo bar foo bar│
└───────────────┘
*/
```
- `'right'`
```js
/*
┌────── example ┐
│foo bar foo bar│
└───────────────┘
*/
```

##### width

Type: `number`

Set a fixed width for the box.

*Note:* This disables terminal overflow handling and may cause the box to look broken if the user's terminal is not wide enough.

```js
import boxen from 'boxen';

console.log(boxen('foo bar', {width: 15}));
// ┌─────────────┐
// │foo bar      │
// └─────────────┘
```

##### height

Type: `number`

Set a fixed height for the box.

*Note:* This option will crop overflowing content.

```js
import boxen from 'boxen';

console.log(boxen('foo bar', {height: 5}));
// ┌───────┐
// │foo bar│
// │       │
// │       │
// └───────┘
```

##### fullscreen

Type: `boolean | (width: number, height: number) => [width: number, height: number]`

Whether or not to fit all available space within the terminal.

Pass a callback function to control box dimensions:

```js
import boxen from 'boxen';

console.log(boxen('foo bar', {
	fullscreen: (width, height) => [width, height - 1],
}));
```

##### padding

Type: `number | object`\
Default: `0`

Space between the text and box border.

Accepts a number or an object with any of the `top`, `right`, `bottom`, `left` properties. When a number is specified, the left/right padding is 3 times the top/bottom to make it look nice.

##### margin

Type: `number | object`\
Default: `0`

Space around the box.

Accepts a number or an object with any of the `top`, `right`, `bottom`, `left` properties. When a number is specified, the left/right margin is 3 times the top/bottom to make it look nice.

##### float

Type: `string`\
Default: `'left'`\
Values: `'right'` `'center'` `'left'`

Float the box on the available terminal screen space.

##### backgroundColor

Type: `string`\
Values: `'black'` `'red'` `'green'` `'yellow'` `'blue'` `'magenta'` `'cyan'` `'white'` `'gray'` or a hex value like `'#ff0000'`

Color of the background.

##### textAlignment

Type: `string`\
Default: `'left'`\
Values: `'left'` `'center'` `'right'`

Align the text in the box based on the widest line.

## Maintainer

- [Sindre Sorhus](https://github.com/sindresorhus)
- [Caesarovich](https://github.com/Caesarovich)

## Related

- [boxen-cli](https://github.com/sindresorhus/boxen-cli) - CLI for this module
- [cli-boxes](https://github.com/sindresorhus/cli-boxes) - Boxes for use in the terminal


---

# camelcase

> Convert a dash/dot/underscore/space separated string to camelCase or PascalCase: `foo-bar` → `fooBar`

Correctly handles Unicode strings.

If you use this on untrusted user input, don't forget to limit the length to something reasonable.

## Install

```sh
npm install camelcase
```

## Usage

```js
import camelCase from 'camelcase';

camelCase('foo-bar');
//=> 'fooBar'

camelCase('foo_bar');
//=> 'fooBar'

camelCase('Foo-Bar');
//=> 'fooBar'

camelCase('розовый_пушистый_единорог');
//=> 'розовыйПушистыйЕдинорог'

camelCase('Foo-Bar', {pascalCase: true});
//=> 'FooBar'

camelCase('--foo.bar', {pascalCase: false});
//=> 'fooBar'

camelCase('Foo-BAR', {preserveConsecutiveUppercase: true});
//=> 'fooBAR'

camelCase('fooBAR', {pascalCase: true, preserveConsecutiveUppercase: true}));
//=> 'FooBAR'

camelCase('foo bar');
//=> 'fooBar'

console.log(process.argv[3]);
//=> '--foo-bar'
camelCase(process.argv[3]);
//=> 'fooBar'

camelCase(['foo', 'bar']);
//=> 'fooBar'

camelCase(['__foo__', '--bar'], {pascalCase: true});
//=> 'FooBar'

camelCase(['foo', 'BAR'], {pascalCase: true, preserveConsecutiveUppercase: true})
//=> 'FooBAR'

camelCase('lorem-ipsum', {locale: 'en-US'});
//=> 'loremIpsum'
```

## API

### camelCase(input, options?)

#### input

Type: `string | string[]`

String to convert to camel case.

#### options

Type: `object`

##### pascalCase

Type: `boolean`\
Default: `false`

Uppercase the first character: `foo-bar` → `FooBar`

##### preserveConsecutiveUppercase

Type: `boolean`\
Default: `false`

Preserve consecutive uppercase characters: `foo-BAR` → `FooBAR`.

##### locale

Type: `false | string | string[]`\
Default: The host environment’s current locale.

The locale parameter indicates the locale to be used to convert to upper/lower case according to any locale-specific case mappings. If multiple locales are given in an array, the best available locale is used.

```js
import camelCase from 'camelcase';

camelCase('lorem-ipsum', {locale: 'en-US'});
//=> 'loremIpsum'

camelCase('lorem-ipsum', {locale: 'tr-TR'});
//=> 'loremİpsum'

camelCase('lorem-ipsum', {locale: ['en-US', 'en-GB']});
//=> 'loremIpsum'

camelCase('lorem-ipsum', {locale: ['tr', 'TR', 'tr-TR']});
//=> 'loremİpsum'
```

Setting `locale: false` ignores the platform locale and uses the [Unicode Default Case Conversion](https://unicode-org.github.io/icu/userguide/transforms/casemappings.html#simple-single-character-case-mapping) algorithm:

```js
import camelCase from 'camelcase';

// On a platform with 'tr-TR'

camelCase('lorem-ipsum');
//=> 'loremİpsum'

camelCase('lorem-ipsum', {locale: false});
//=> 'loremIpsum'
```

## camelcase for enterprise

Available as part of the Tidelift Subscription.

The maintainers of camelcase and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-camelcase?utm_source=npm-camelcase&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)

## Related

- [decamelize](https://github.com/sindresorhus/decamelize) - The inverse of this module
- [uppercamelcase](https://github.com/SamVerschueren/uppercamelcase) - Like this module, but to PascalCase instead of camelCase
- [titleize](https://github.com/sindresorhus/titleize) - Capitalize every word in string
- [humanize-string](https://github.com/sindresorhus/humanize-string) - Convert a camelized/dasherized/underscored string into a humanized one
- [camelcase-keys](https://github.com/sindresorhus/camelcase-keys) - Convert object keys to camel case


---

<h1 align="center">
	<br>
	<br>
	<img width="320" src="media/logo.svg" alt="Chalk">
	<br>
	<br>
	<br>
</h1>

> Terminal string styling done right

[![Coverage Status](https://codecov.io/gh/chalk/chalk/branch/main/graph/badge.svg)](https://codecov.io/gh/chalk/chalk)
[![npm dependents](https://badgen.net/npm/dependents/chalk)](https://www.npmjs.com/package/chalk?activeTab=dependents)
[![Downloads](https://badgen.net/npm/dt/chalk)](https://www.npmjs.com/package/chalk)

![](media/screenshot.png)

## Info

- [Why not switch to a smaller coloring package?](https://github.com/chalk/chalk?tab=readme-ov-file#why-not-switch-to-a-smaller-coloring-package)
- See [yoctocolors](https://github.com/sindresorhus/yoctocolors) for a smaller alternative

## Highlights

- Expressive API
- Highly performant
- No dependencies
- Ability to nest styles
- [256/Truecolor color support](#256-and-truecolor-color-support)
- Auto-detects color support
- Doesn't extend `String.prototype`
- Clean and focused
- Actively maintained
- [Used by ~115,000 packages](https://www.npmjs.com/browse/depended/chalk) as of July 4, 2024

## Install

```sh
npm install chalk
```

**IMPORTANT:** Chalk 5 is ESM. If you want to use Chalk with TypeScript or a build tool, you will probably want to use Chalk 4 for now. [Read more.](https://github.com/chalk/chalk/releases/tag/v5.0.0)

## Usage

```js
import chalk from 'chalk';

console.log(chalk.blue('Hello world!'));
```

Chalk comes with an easy to use composable API where you just chain and nest the styles you want.

```js
import chalk from 'chalk';

const log = console.log;

// Combine styled and normal strings
log(chalk.blue('Hello') + ' World' + chalk.red('!'));

// Compose multiple styles using the chainable API
log(chalk.blue.bgRed.bold('Hello world!'));

// Pass in multiple arguments
log(chalk.blue('Hello', 'World!', 'Foo', 'bar', 'biz', 'baz'));

// Nest styles
log(chalk.red('Hello', chalk.underline.bgBlue('world') + '!'));

// Nest styles of the same type even (color, underline, background)
log(chalk.green(
	'I am a green line ' +
	chalk.blue.underline.bold('with a blue substring') +
	' that becomes green again!'
));

// ES2015 template literal
log(`
CPU: ${chalk.red('90%')}
RAM: ${chalk.green('40%')}
DISK: ${chalk.yellow('70%')}
`);

// Use RGB colors in terminal emulators that support it.
log(chalk.rgb(123, 45, 67).underline('Underlined reddish color'));
log(chalk.hex('#DEADED').bold('Bold gray!'));
```

Easily define your own themes:

```js
import chalk from 'chalk';

const error = chalk.bold.red;
const warning = chalk.hex('#FFA500'); // Orange color

console.log(error('Error!'));
console.log(warning('Warning!'));
```

Take advantage of console.log [string substitution](https://nodejs.org/docs/latest/api/console.html#console_console_log_data_args):

```js
import chalk from 'chalk';

const name = 'Sindre';
console.log(chalk.green('Hello %s'), name);
//=> 'Hello Sindre'
```

## API

### chalk.`<style>[.<style>...](string, [string...])`

Example: `chalk.red.bold.underline('Hello', 'world');`

Chain [styles](#styles) and call the last one as a method with a string argument. Order doesn't matter, and later styles take precedent in case of a conflict. This simply means that `chalk.red.yellow.green` is equivalent to `chalk.green`.

Multiple arguments will be separated by space.

### chalk.level

Specifies the level of color support.

Color support is automatically detected, but you can override it by setting the `level` property. You should however only do this in your own code as it applies globally to all Chalk consumers.

If you need to change this in a reusable module, create a new instance:

```js
import {Chalk} from 'chalk';

const customChalk = new Chalk({level: 0});
```

| Level | Description |
| :---: | :--- |
| `0` | All colors disabled |
| `1` | Basic color support (16 colors) |
| `2` | 256 color support |
| `3` | Truecolor support (16 million colors) |

### supportsColor

Detect whether the terminal [supports color](https://github.com/chalk/supports-color). Used internally and handled for you, but exposed for convenience.

Can be overridden by the user with the flags `--color` and `--no-color`. For situations where using `--color` is not possible, use the environment variable `FORCE_COLOR=1` (level 1), `FORCE_COLOR=2` (level 2), or `FORCE_COLOR=3` (level 3) to forcefully enable color, or `FORCE_COLOR=0` to forcefully disable. The use of `FORCE_COLOR` overrides all other color support checks.

Explicit 256/Truecolor mode can be enabled using the `--color=256` and `--color=16m` flags, respectively.

### chalkStderr and supportsColorStderr

`chalkStderr` contains a separate instance configured with color support detected for `stderr` stream instead of `stdout`. Override rules from `supportsColor` apply to this too. `supportsColorStderr` is exposed for convenience.

### modifierNames, foregroundColorNames, backgroundColorNames, and colorNames

All supported style strings are exposed as an array of strings for convenience. `colorNames` is the combination of `foregroundColorNames` and `backgroundColorNames`.

This can be useful if you wrap Chalk and need to validate input:

```js
import {modifierNames, foregroundColorNames} from 'chalk';

console.log(modifierNames.includes('bold'));
//=> true

console.log(foregroundColorNames.includes('pink'));
//=> false
```

## Styles

### Modifiers

- `reset` - Reset the current style.
- `bold` - Make the text bold.
- `dim` - Make the text have lower opacity.
- `italic` - Make the text italic. *(Not widely supported)*
- `underline` - Put a horizontal line below the text. *(Not widely supported)*
- `overline` - Put a horizontal line above the text. *(Not widely supported)*
- `inverse`- Invert background and foreground colors.
- `hidden` - Print the text but make it invisible.
- `strikethrough` - Puts a horizontal line through the center of the text. *(Not widely supported)*
- `visible`- Print the text only when Chalk has a color level above zero. Can be useful for things that are purely cosmetic.

### Colors

- `black`
- `red`
- `green`
- `yellow`
- `blue`
- `magenta`
- `cyan`
- `white`
- `blackBright` (alias: `gray`, `grey`)
- `redBright`
- `greenBright`
- `yellowBright`
- `blueBright`
- `magentaBright`
- `cyanBright`
- `whiteBright`

### Background colors

- `bgBlack`
- `bgRed`
- `bgGreen`
- `bgYellow`
- `bgBlue`
- `bgMagenta`
- `bgCyan`
- `bgWhite`
- `bgBlackBright` (alias: `bgGray`, `bgGrey`)
- `bgRedBright`
- `bgGreenBright`
- `bgYellowBright`
- `bgBlueBright`
- `bgMagentaBright`
- `bgCyanBright`
- `bgWhiteBright`

## 256 and Truecolor color support

Chalk supports 256 colors and [Truecolor](https://github.com/termstandard/colors) (16 million colors) on supported terminal apps.

Colors are downsampled from 16 million RGB values to an ANSI color format that is supported by the terminal emulator (or by specifying `{level: n}` as a Chalk option). For example, Chalk configured to run at level 1 (basic color support) will downsample an RGB value of #FF0000 (red) to 31 (ANSI escape for red).

Examples:

- `chalk.hex('#DEADED').underline('Hello, world!')`
- `chalk.rgb(15, 100, 204).inverse('Hello!')`

Background versions of these models are prefixed with `bg` and the first level of the module capitalized (e.g. `hex` for foreground colors and `bgHex` for background colors).

- `chalk.bgHex('#DEADED').underline('Hello, world!')`
- `chalk.bgRgb(15, 100, 204).inverse('Hello!')`

The following color models can be used:

- [`rgb`](https://en.wikipedia.org/wiki/RGB_color_model) - Example: `chalk.rgb(255, 136, 0).bold('Orange!')`
- [`hex`](https://en.wikipedia.org/wiki/Web_colors#Hex_triplet) - Example: `chalk.hex('#FF8800').bold('Orange!')`
- [`ansi256`](https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit) - Example: `chalk.bgAnsi256(194)('Honeydew, more or less')`

## Browser support

Since Chrome 69, ANSI escape codes are natively supported in the developer console.

## Windows

If you're on Windows, do yourself a favor and use [Windows Terminal](https://github.com/microsoft/terminal) instead of `cmd.exe`.

## FAQ

### Why not switch to a smaller coloring package?

Chalk may be larger, but there is a reason for that. It offers a more user-friendly API, well-documented types, supports millions of colors, and covers edge cases that smaller alternatives miss. Chalk is mature, reliable, and built to last.

But beyond the technical aspects, there's something more critical: trust and long-term maintenance. I have been active in open source for over a decade, and I'm committed to keeping Chalk maintained. Smaller packages might seem appealing now, but there's no guarantee they will be around for the long term, or that they won't become malicious over time.

Chalk is also likely already in your dependency tree (since 100K+ packages depend on it), so switching won’t save space—in fact, it might increase it. npm deduplicates dependencies, so multiple Chalk instances turn into one, but adding another package alongside it will increase your overall size.

If the goal is to clean up the ecosystem, switching away from Chalk won’t even make a dent. The real problem lies with packages that have very deep dependency trees (for example, those including a lot of polyfills). Chalk has no dependencies. It's better to focus on impactful changes rather than minor optimizations.

If absolute package size is important to you, I also maintain [yoctocolors](https://github.com/sindresorhus/yoctocolors), one of the smallest color packages out there.

*\- [Sindre](https://github.com/sindresorhus)*

### But the smaller coloring package has benchmarks showing it is faster

[Micro-benchmarks are flawed](https://sindresorhus.com/blog/micro-benchmark-fallacy) because they measure performance in unrealistic, isolated scenarios, often giving a distorted view of real-world performance. Don't believe marketing fluff. All the coloring packages are more than fast enough.

## Related

- [chalk-template](https://github.com/chalk/chalk-template) - [Tagged template literals](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates) support for this module
- [chalk-cli](https://github.com/chalk/chalk-cli) - CLI for this module
- [ansi-styles](https://github.com/chalk/ansi-styles) - ANSI escape codes for styling strings in the terminal
- [supports-color](https://github.com/chalk/supports-color) - Detect whether a terminal supports color
- [strip-ansi](https://github.com/chalk/strip-ansi) - Strip ANSI escape codes
- [strip-ansi-stream](https://github.com/chalk/strip-ansi-stream) - Strip ANSI escape codes from a stream
- [has-ansi](https://github.com/chalk/has-ansi) - Check if a string has ANSI escape codes
- [ansi-regex](https://github.com/chalk/ansi-regex) - Regular expression for matching ANSI escape codes
- [wrap-ansi](https://github.com/chalk/wrap-ansi) - Wordwrap a string with ANSI escape codes
- [slice-ansi](https://github.com/chalk/slice-ansi) - Slice a string with ANSI escape codes
- [color-convert](https://github.com/qix-/color-convert) - Converts colors between different models
- [chalk-animation](https://github.com/bokub/chalk-animation) - Animate strings in the terminal
- [gradient-string](https://github.com/bokub/gradient-string) - Apply color gradients to strings
- [chalk-pipe](https://github.com/LitoMore/chalk-pipe) - Create chalk style schemes with simpler style strings
- [terminal-link](https://github.com/sindresorhus/terminal-link) - Create clickable links in the terminal

*(Not accepting additional entries)*

## Maintainers

- [Sindre Sorhus](https://github.com/sindresorhus)
- [Josh Junon](https://github.com/qix-)


---

# update-notifier

> Update notifications for your CLI app

![](screenshot.png)

Inform users of your package of updates in a non-intrusive way.

#### Contents

- [Install](#install)
- [Usage](#usage)
- [How](#how)
- [API](#api)
- [About](#about)
- [Users](#users)

## Install

```sh
npm install update-notifier
```

## Usage

### Simple

```js
import updateNotifier from 'update-notifier';
import packageJson from './package.json' assert {type: 'json'};

updateNotifier({pkg: packageJson}).notify();
```

### Comprehensive

```js
import updateNotifier from 'update-notifier';
import packageJson from './package.json' assert {type: 'json'};

// Checks for available update and returns an instance
const notifier = updateNotifier({pkg: packageJson});

// Notify using the built-in convenience method
notifier.notify();

// `notifier.update` contains some useful info about the update
console.log(notifier.update);
/*
{
	latest: '1.0.1',
	current: '1.0.0',
	type: 'patch', // Possible values: latest, major, minor, patch, prerelease, build
	name: 'pageres'
}
*/
```

### Options and custom message

```js
const notifier = updateNotifier({
	pkg,
	updateCheckInterval: 1000 * 60 * 60 * 24 * 7 // 1 week
});

if (notifier.update) {
	console.log(`Update available: ${notifier.update.latest}`);
}
```

## How

Whenever you initiate the update notifier and it's not within the interval threshold, it will asynchronously check with npm in the background for available updates, then persist the result. The next time the notifier is initiated, the result will be loaded into the `.update` property. This prevents any impact on your package startup performance.
The update check is done in a unref'ed [child process](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options). This means that if you call `process.exit`, the check will still be performed in its own process.

The first time the user runs your app, it will check for an update, and even if an update is available, it will wait the specified `updateCheckInterval` before notifying the user. This is done to not be annoying to the user, but might surprise you as an implementer if you're testing whether it works. Check out [`example.js`](example.js) to quickly test out `update-notifier` and see how you can test that it works in your app.

## API

### notifier = updateNotifier(options)

Checks if there is an available update. Accepts options defined below. Returns an instance with an `.update` property if there is an available update, otherwise `undefined`.

### options

Type: `object`

#### pkg

Type: `object`

##### name

*Required*\
Type: `string`

##### version

*Required*\
Type: `string`

#### updateCheckInterval

Type: `number`\
Default: `1000 * 60 * 60 * 24` *(1 day)*

How often to check for updates.

#### shouldNotifyInNpmScript

Type: `boolean`\
Default: `false`

Allows notification to be shown when running as an npm script.

#### distTag

Type: `string`\
Default: `'latest'`

Which [dist-tag](https://docs.npmjs.com/adding-dist-tags-to-packages) to use to find the latest version.

### notifier.fetchInfo()

Check update information.

Returns an `object` with:

- `latest` _(String)_ - Latest version.
- `current` _(String)_ - Current version.
- `type` _(String)_ - Type of current update. Possible values: `latest`, `major`, `minor`, `patch`, `prerelease`, `build`.
- `name` _(String)_ - Package name.

### notifier.notify(options?)

Convenience method to display a notification message. *(See screenshot)*

Only notifies if there is an update and the process is [TTY](https://nodejs.org/api/process.html#process_a_note_on_process_i_o).

#### options

Type: `object`

##### defer

Type: `boolean`\
Default: `true`

Defer showing the notification to after the process has exited.

##### message

Type: `string`\
Default: [See above screenshot](https://github.com/yeoman/update-notifier#update-notifier-)

Message that will be shown when an update is available.

Available placeholders:

- `{packageName}` - Package name.
- `{currentVersion}` - Current version.
- `{latestVersion}` - Latest version.
- `{updateCommand}` - Update command.

```js
notifier.notify({message: 'Run `{updateCommand}` to update.'});

// Output:
// Run `npm install update-notifier-tester@1.0.0` to update.
```

##### isGlobal

Type: `boolean`\
Default: Auto-detect

Include the `-g` argument in the default message's `npm i` recommendation. You may want to change this if your CLI package can be installed as a dependency of another project, and don't want to recommend a global installation. This option is ignored if you supply your own `message` (see above).

##### boxenOptions

Type: `object`\
Default: `{padding: 1, margin: 1, textAlignment: 'center', borderColor: 'yellow', borderStyle: 'round'}` *(See screenshot)*

Options object that will be passed to [`boxen`](https://github.com/sindresorhus/boxen).

### User settings

Users of your module have the ability to opt-out of the update notifier by changing the `optOut` property to `true` in `~/.config/configstore/update-notifier-[your-module-name].json`. The path is available in `notifier.config.path`.

Users can also opt-out by [setting the environment variable](https://github.com/sindresorhus/guides/blob/main/set-environment-variables.md) `NO_UPDATE_NOTIFIER` with any value or by using the `--no-update-notifier` flag on a per run basis.

The check is also skipped automatically:
  - on CI
  - in unit tests (when the `NODE_ENV` environment variable is `test`)

## About

The idea for this module came from the desire to apply the browser update strategy to CLI tools, where everyone is always on the latest version. We first tried automatic updating, which we discovered wasn't popular. This is the second iteration of that idea, but limited to just update notifications.

## Users

There are a bunch projects using it:

- [npm](https://github.com/npm/npm) - Package manager for JavaScript
- [Yeoman](https://yeoman.io) - Modern workflows for modern webapps
- [AVA](https://avajs.dev) - Simple concurrent test runner
- [XO](https://github.com/xojs/xo) - JavaScript happiness style linter
- [Node GH](https://github.com/node-gh/gh) - GitHub command line tool

[And 2700+ more…](https://www.npmjs.org/browse/depended/update-notifier)

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-update_notifier?utm_source=npm-update-notifier&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

# URI.js

URI.js is an [RFC 3986](http://www.ietf.org/rfc/rfc3986.txt) compliant, scheme extendable URI parsing/validating/resolving library for all JavaScript environments (browsers, Node.js, etc).
It is also compliant with the IRI ([RFC 3987](http://www.ietf.org/rfc/rfc3987.txt)), IDNA ([RFC 5890](http://www.ietf.org/rfc/rfc5890.txt)), IPv6 Address ([RFC 5952](http://www.ietf.org/rfc/rfc5952.txt)), IPv6 Zone Identifier ([RFC 6874](http://www.ietf.org/rfc/rfc6874.txt)) specifications.

URI.js has an extensive test suite, and works in all (Node.js, web) environments. It weighs in at 6.4kb (gzipped, 17kb deflated).

## API

### Parsing

	URI.parse("uri://user:pass@example.com:123/one/two.three?q1=a1&q2=a2#body");
	//returns:
	//{
	//  scheme : "uri",
	//  userinfo : "user:pass",
	//  host : "example.com",
	//  port : 123,
	//  path : "/one/two.three",
	//  query : "q1=a1&q2=a2",
	//  fragment : "body"
	//}

### Serializing

	URI.serialize({scheme : "http", host : "example.com", fragment : "footer"}) === "http://example.com/#footer"

### Resolving

	URI.resolve("uri://a/b/c/d?q", "../../g") === "uri://a/g"

### Normalizing

	URI.normalize("HTTP://ABC.com:80/%7Esmith/home.html") === "http://abc.com/~smith/home.html"

### Comparison

	URI.equal("example://a/b/c/%7Bfoo%7D", "eXAMPLE://a/./b/../b/%63/%7bfoo%7d") === true

### IP Support

	//IPv4 normalization
	URI.normalize("//192.068.001.000") === "//192.68.1.0"

	//IPv6 normalization
	URI.normalize("//[2001:0:0DB8::0:0001]") === "//[2001:0:db8::1]"

	//IPv6 zone identifier support
	URI.parse("//[2001:db8::7%25en1]");
	//returns:
	//{
	//  host : "2001:db8::7%en1"
	//}

### IRI Support

	//convert IRI to URI
	URI.serialize(URI.parse("http://examplé.org/rosé")) === "http://xn--exampl-gva.org/ros%C3%A9"
	//convert URI to IRI
	URI.serialize(URI.parse("http://xn--exampl-gva.org/ros%C3%A9"), {iri:true}) === "http://examplé.org/rosé"

### Options

All of the above functions can accept an additional options argument that is an object that can contain one or more of the following properties:

*	`scheme` (string)

	Indicates the scheme that the URI should be treated as, overriding the URI's normal scheme parsing behavior.

*	`reference` (string)

	If set to `"suffix"`, it indicates that the URI is in the suffix format, and the validator will use the option's `scheme` property to determine the URI's scheme.

*	`tolerant` (boolean, false)

	If set to `true`, the parser will relax URI resolving rules.

*	`absolutePath` (boolean, false)

	If set to `true`, the serializer will not resolve a relative `path` component.

*	`iri` (boolean, false)

	If set to `true`, the serializer will unescape non-ASCII characters as per [RFC 3987](http://www.ietf.org/rfc/rfc3987.txt).

*	`unicodeSupport` (boolean, false)

	If set to `true`, the parser will unescape non-ASCII characters in the parsed output as per [RFC 3987](http://www.ietf.org/rfc/rfc3987.txt).

*	`domainHost` (boolean, false)

	If set to `true`, the library will treat the `host` component as a domain name, and convert IDNs (International Domain Names) as per [RFC 5891](http://www.ietf.org/rfc/rfc5891.txt).

## Scheme Extendable

URI.js supports inserting custom [scheme](http://en.wikipedia.org/wiki/URI_scheme) dependent processing rules. Currently, URI.js has built in support for the following schemes:

*	http \[[RFC 2616](http://www.ietf.org/rfc/rfc2616.txt)\]
*	https \[[RFC 2818](http://www.ietf.org/rfc/rfc2818.txt)\]
*	ws \[[RFC 6455](http://www.ietf.org/rfc/rfc6455.txt)\]
*	wss \[[RFC 6455](http://www.ietf.org/rfc/rfc6455.txt)\]
*	mailto \[[RFC 6068](http://www.ietf.org/rfc/rfc6068.txt)\]
*	urn \[[RFC 2141](http://www.ietf.org/rfc/rfc2141.txt)\]
*	urn:uuid \[[RFC 4122](http://www.ietf.org/rfc/rfc4122.txt)\]

### HTTP/HTTPS Support

	URI.equal("HTTP://ABC.COM:80", "http://abc.com/") === true
	URI.equal("https://abc.com", "HTTPS://ABC.COM:443/") === true

### WS/WSS Support

	URI.parse("wss://example.com/foo?bar=baz");
	//returns:
	//{
	//	scheme : "wss",
	//	host: "example.com",
	//	resourceName: "/foo?bar=baz",
	//	secure: true,
	//}

	URI.equal("WS://ABC.COM:80/chat#one", "ws://abc.com/chat") === true

### Mailto Support

	URI.parse("mailto:alpha@example.com,bravo@example.com?subject=SUBSCRIBE&body=Sign%20me%20up!");
	//returns:
	//{
	//	scheme : "mailto",
	//	to : ["alpha@example.com", "bravo@example.com"],
	//	subject : "SUBSCRIBE",
	//	body : "Sign me up!"
	//}

	URI.serialize({
		scheme : "mailto",
		to : ["alpha@example.com"],
		subject : "REMOVE",
		body : "Please remove me",
		headers : {
			cc : "charlie@example.com"
		}
	}) === "mailto:alpha@example.com?cc=charlie@example.com&subject=REMOVE&body=Please%20remove%20me"

### URN Support

	URI.parse("urn:example:foo");
	//returns:
	//{
	//	scheme : "urn",
	//	nid : "example",
	//	nss : "foo",
	//}

#### URN UUID Support

	URI.parse("urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6");
	//returns:
	//{
	//	scheme : "urn",
	//	nid : "uuid",
	//	uuid : "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
	//}

## Usage

To load in a browser, use the following tag:

	<script type="text/javascript" src="uri-js/dist/es5/uri.all.min.js"></script>

To load in a CommonJS/Module environment, first install with npm/yarn by running on the command line:

	npm install uri-js
	# OR
	yarn add uri-js

Then, in your code, load it using:

	const URI = require("uri-js");

If you are writing your code in ES6+ (ESNEXT) or TypeScript, you would load it using:

	import * as URI from "uri-js";

Or you can load just what you need using named exports:

	import { parse, serialize, resolve, resolveComponents, normalize, equal, removeDotSegments, pctEncChar, pctDecChars, escapeComponent, unescapeComponent } from "uri-js";

## Breaking changes

### Breaking changes from 3.x

URN parsing has been completely changed to better align with the specification. Scheme is now always `urn`, but has two new properties: `nid` which contains the Namspace Identifier, and `nss` which contains the Namespace Specific String. The `nss` property will be removed by higher order scheme handlers, such as the UUID URN scheme handler.

The UUID of a URN can now be found in the `uuid` property.

### Breaking changes from 2.x

URI validation has been removed as it was slow, exposed a vulnerabilty, and was generally not useful.

### Breaking changes from 1.x

The `errors` array on parsed components is now an `error` string.


---

# Punycode.js [![punycode on npm](https://img.shields.io/npm/v/punycode)](https://www.npmjs.com/package/emoji-test-regex-pattern) [![](https://data.jsdelivr.com/v1/package/npm/punycode/badge)](https://www.jsdelivr.com/package/npm/punycode)

Punycode.js is a robust Punycode converter that fully complies to [RFC 3492](https://tools.ietf.org/html/rfc3492) and [RFC 5891](https://tools.ietf.org/html/rfc5891).

This JavaScript library is the result of comparing, optimizing and documenting different open-source implementations of the Punycode algorithm:

* [The C example code from RFC 3492](https://tools.ietf.org/html/rfc3492#appendix-C)
* [`punycode.c` by _Markus W. Scherer_ (IBM)](http://opensource.apple.com/source/ICU/ICU-400.42/icuSources/common/punycode.c)
* [`punycode.c` by _Ben Noordhuis_](https://github.com/bnoordhuis/punycode/blob/master/punycode.c)
* [JavaScript implementation by _some_](http://stackoverflow.com/questions/183485/can-anyone-recommend-a-good-free-javascript-for-punycode-to-unicode-conversion/301287#301287)
* [`punycode.js` by _Ben Noordhuis_](https://github.com/joyent/node/blob/426298c8c1c0d5b5224ac3658c41e7c2a3fe9377/lib/punycode.js) (note: [not fully compliant](https://github.com/joyent/node/issues/2072))

This project was [bundled](https://github.com/joyent/node/blob/master/lib/punycode.js) with Node.js from [v0.6.2+](https://github.com/joyent/node/compare/975f1930b1...61e796decc) until [v7](https://github.com/nodejs/node/pull/7941) (soft-deprecated).

This project provides a CommonJS module that uses ES2015+ features and JavaScript module, which work in modern Node.js versions and browsers. For the old Punycode.js version that offers the same functionality in a UMD build with support for older pre-ES2015 runtimes, including Rhino, Ringo, and Narwhal, see [v1.4.1](https://github.com/mathiasbynens/punycode.js/releases/tag/v1.4.1).

## Installation

Via [npm](https://www.npmjs.com/):

```bash
npm install punycode --save
```

In [Node.js](https://nodejs.org/):

> ⚠️ Note that userland modules don't hide core modules.
> For example, `require('punycode')` still imports the deprecated core module even if you executed `npm install punycode`.
> Use `require('punycode/')` to import userland modules rather than core modules.

```js
const punycode = require('punycode/');
```

## API

### `punycode.decode(string)`

Converts a Punycode string of ASCII symbols to a string of Unicode symbols.

```js
// decode domain name parts
punycode.decode('maana-pta'); // 'mañana'
punycode.decode('--dqo34k'); // '☃-⌘'
```

### `punycode.encode(string)`

Converts a string of Unicode symbols to a Punycode string of ASCII symbols.

```js
// encode domain name parts
punycode.encode('mañana'); // 'maana-pta'
punycode.encode('☃-⌘'); // '--dqo34k'
```

### `punycode.toUnicode(input)`

Converts a Punycode string representing a domain name or an email address to Unicode. Only the Punycoded parts of the input will be converted, i.e. it doesn’t matter if you call it on a string that has already been converted to Unicode.

```js
// decode domain names
punycode.toUnicode('xn--maana-pta.com');
// → 'mañana.com'
punycode.toUnicode('xn----dqo34k.com');
// → '☃-⌘.com'

// decode email addresses
punycode.toUnicode('джумла@xn--p-8sbkgc5ag7bhce.xn--ba-lmcq');
// → 'джумла@джpумлатест.bрфa'
```

### `punycode.toASCII(input)`

Converts a lowercased Unicode string representing a domain name or an email address to Punycode. Only the non-ASCII parts of the input will be converted, i.e. it doesn’t matter if you call it with a domain that’s already in ASCII.

```js
// encode domain names
punycode.toASCII('mañana.com');
// → 'xn--maana-pta.com'
punycode.toASCII('☃-⌘.com');
// → 'xn----dqo34k.com'

// encode email addresses
punycode.toASCII('джумла@джpумлатест.bрфa');
// → 'джумла@xn--p-8sbkgc5ag7bhce.xn--ba-lmcq'
```

### `punycode.ucs2`

#### `punycode.ucs2.decode(string)`

Creates an array containing the numeric code point values of each Unicode symbol in the string. While [JavaScript uses UCS-2 internally](https://mathiasbynens.be/notes/javascript-encoding), this function will convert a pair of surrogate halves (each of which UCS-2 exposes as separate characters) into a single code point, matching UTF-16.

```js
punycode.ucs2.decode('abc');
// → [0x61, 0x62, 0x63]
// surrogate pair for U+1D306 TETRAGRAM FOR CENTRE:
punycode.ucs2.decode('\uD834\uDF06');
// → [0x1D306]
```

#### `punycode.ucs2.encode(codePoints)`

Creates a string based on an array of numeric code point values.

```js
punycode.ucs2.encode([0x61, 0x62, 0x63]);
// → 'abc'
punycode.ucs2.encode([0x1D306]);
// → '\uD834\uDF06'
```

### `punycode.version`

A string representing the current Punycode.js version number.

## Author

| [![twitter/mathias](https://gravatar.com/avatar/24e08a9ea84deb17ae121074d0f17125?s=70)](https://twitter.com/mathias "Follow @mathias on Twitter") |
|---|
| [Mathias Bynens](https://mathiasbynens.be/) |

## License

Punycode.js is available under the [MIT](https://mths.be/mit) license.


---

# Changelog

All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.

### [4.1.1](https://github.com/webpack-contrib/url-loader/compare/v4.1.0...v4.1.1) (2020-10-09)

### Chore

* update `schema-utils`

## [4.1.0](https://github.com/webpack-contrib/url-loader/compare/v4.0.0...v4.1.0) (2020-04-08)


### Features

* the `mimetype` option can be `Boolean`
* added the `encoding` option
* added the `generator` option 

## [4.0.0](https://github.com/webpack-contrib/url-loader/compare/v3.0.0...v4.0.0) (2020-03-17)


### ⚠ BREAKING CHANGES

* **deps:** migrate on `mime-types` package, some rare types may have other mimetype

### Bug Fixes

*  description on the `esModule` option ([#204](https://github.com/webpack-contrib/url-loader/issues/204)) ([a2f127d](https://github.com/webpack-contrib/url-loader/commit/a2f127d16b88cda3c38509821a51487a89827c28))


* **deps:** migrate on `mime-types` package ([#209](https://github.com/webpack-contrib/url-loader/issues/209)) ([fc8721f](https://github.com/webpack-contrib/url-loader/commit/fc8721f49626360dd81300085a747b3afa5acd38))

## [3.0.0](https://github.com/webpack-contrib/url-loader/compare/v2.0.0...v3.0.0) (2019-11-26)


### BREAKING CHANGES

* minimum required nodejs version is `10.13.0`
* rename the `esModules` option to `esModule`
* switch to ES modules by default (the option `esModule` is `true` by default)


## [2.3.0](https://github.com/webpack-contrib/url-loader/compare/v2.2.0...v2.3.0) (2019-11-21)


### Features

* new `esModules` option to output ES modules ([0ee2b99](https://github.com/webpack-contrib/url-loader/commit/0ee2b9964f37f4d7c5dd6ea09f8526525e0fab91))

### [2.2.0](https://github.com/webpack-contrib/url-loader/compare/v2.1.0...v2.2.0) (2019-10-04)


### Features

* limit allow using `Infinity` and `Number` ([#192](https://github.com/webpack-contrib/url-loader/issues/192)) ([2bffcfd](https://github.com/webpack-contrib/url-loader/commit/2bffcfd))
* pnp support ([#195](https://github.com/webpack-contrib/url-loader/issues/195)) ([196110e](https://github.com/webpack-contrib/url-loader/commit/196110e))

## [2.1.0](https://github.com/webpack-contrib/url-loader/compare/v2.0.1...v2.1.0) (2019-07-18)


### Features

* improved validation error messages ([#187](https://github.com/webpack-contrib/url-loader/issues/187)) ([f3d4dd2](https://github.com/webpack-contrib/url-loader/commit/f3d4dd2))



### [2.0.1](https://github.com/webpack-contrib/url-loader/compare/v2.0.0...v2.0.1) (2019-06-25)


### Bug Fixes

* allow using limit as string when you use loader with query string ([#185](https://github.com/webpack-contrib/url-loader/issues/185)) ([4842f93](https://github.com/webpack-contrib/url-loader/commit/4842f93))



## [2.0.0](https://github.com/webpack-contrib/url-loader/compare/v1.1.2...v2.0.0) (2019-06-05)


### Bug Fixes

* rm unnecessary `bin` field ([#163](https://github.com/webpack-contrib/url-loader/issues/163)) ([b603665](https://github.com/webpack-contrib/url-loader/commit/b603665))
* `limit` should always be a number and 0 value handles as number ([#180](https://github.com/webpack-contrib/url-loader/issues/180)) ([d82e453](https://github.com/webpack-contrib/url-loader/commit/d82e453))
* fallback loader will be used than limit is equal or greater ([#179](https://github.com/webpack-contrib/url-loader/issues/179)) ([3c24545](https://github.com/webpack-contrib/url-loader/commit/3c24545))


### Features

* limit option can be boolean ([#181](https://github.com/webpack-contrib/url-loader/issues/181)) ([60d2cb3](https://github.com/webpack-contrib/url-loader/commit/60d2cb3))


### BREAKING CHANGES

* minimum required nodejs version is `8.9.0`
* `limit` should always be a number and 0 value handles as number
* fallback loader will be used than limit is equal or greater (before only when greater)



<a name="1.1.2"></a>
## [1.1.2](https://github.com/webpack-contrib/url-loader/compare/v1.1.0...v1.1.2) (2018-10-10)


### Bug Fixes

* fallback options behaviour ([#145](https://github.com/webpack-contrib/url-loader/issues/145)) ([03e631f](https://github.com/webpack-contrib/url-loader/commit/03e631f))
* **package:** add support for `webpack =< v3.0.0` (`peerDependencies`) ([#150](https://github.com/webpack-contrib/url-loader/issues/150)) ([a6860fc](https://github.com/webpack-contrib/url-loader/commit/a6860fc))
* **package:** relax `node` version range (`engines`) ([#155](https://github.com/webpack-contrib/url-loader/issues/155)) ([d37b108](https://github.com/webpack-contrib/url-loader/commit/d37b108))
* **utils/normalizeFallback:** correctly pass all `options` to the default fallback (`file-loader`) ([#139](https://github.com/webpack-contrib/url-loader/issues/139)) ([401be63](https://github.com/webpack-contrib/url-loader/commit/401be63))



<a name="1.1.1"></a>
## [1.1.1](https://github.com/webpack-contrib/url-loader/compare/v1.1.0...v1.1.1) (2018-08-17)


### Bug Fixes

* correctly pass all `options` to the fallback ([#143](https://github.com/webpack-contrib/url-loader/issues/143)) ([03e631f](https://github.com/webpack-contrib/url-loader/commit/03e631f))


<a name="1.1.0"></a>
# [1.1.0](https://github.com/webpack-contrib/url-loader/compare/v1.0.1...v1.1.0) (2018-08-13)


### Features

* support fallback loader in options.fallback ([#123](https://github.com/webpack-contrib/url-loader/issues/123)) ([017adc7](https://github.com/webpack-contrib/url-loader/commit/017adc7)), closes [#118](https://github.com/webpack-contrib/url-loader/issues/118)



<a name="1.0.1"></a>
## [1.0.1](https://github.com/webpack-contrib/url-loader/compare/v1.0.0...v1.0.1) (2018-03-03)


### Bug Fixes

* **index:** revert to CJS exports (`module.exports`) ([#116](https://github.com/webpack-contrib/url-loader/issues/116)) ([7b60cc2](https://github.com/webpack-contrib/url-loader/commit/7b60cc2))



<a name="1.0.0"></a>
# [1.0.0](https://github.com/webpack-contrib/url-loader/compare/v1.0.0-beta.0...v1.0.0) (2018-03-03)


### Bug Fixes

* **index:** use `Buffer.from` instead of deprecated `new Buffer` ([#113](https://github.com/webpack-contrib/url-loader/issues/113)) ([457618b](https://github.com/webpack-contrib/url-loader/commit/457618b))



<a name="1.0.0-beta.0"></a>
# [1.0.0-beta.0](https://github.com/webpack-contrib/url-loader/compare/v0.6.2...v1.0.0-beta.0) (2017-12-17)


### Code Refactoring

* apply `webpack-defaults` ([#102](https://github.com/webpack-contrib/url-loader/issues/102)) ([073b588](https://github.com/webpack-contrib/url-loader/commit/073b588))


### BREAKING CHANGES

* Sets `engines` to `"node": ">= 6.9.0 || >= 8.9.0"`
* Drops support for `webpack =< v2.0.0`



<a name="0.6.2"></a>
## [0.6.2](https://github.com/webpack-contrib/url-loader/compare/v0.6.1...v0.6.2) (2017-10-04)


### Bug Fixes

* allow use `limit` as string ([#96](https://github.com/webpack-contrib/url-loader/issues/96)) ([b31684d](https://github.com/webpack-contrib/url-loader/commit/b31684d))



<a name="0.6.1"></a>
## [0.6.1](https://github.com/webpack-contrib/url-loader/compare/v0.6.0...v0.6.1) (2017-10-04)


### Bug Fixes

* **schema:** allow `additionalProperties` ([#94](https://github.com/webpack-contrib/url-loader/issues/94)) ([2b01ea2](https://github.com/webpack-contrib/url-loader/commit/2b01ea2))



<a name="0.6.0"></a>
# [0.6.0](https://github.com/webpack-contrib/url-loader/compare/v0.5.9...v0.6.0) (2017-10-03)


### Features

* **index:** add options validation (`schema-utils`) ([#78](https://github.com/webpack-contrib/url-loader/issues/78)) ([ced5990](https://github.com/webpack-contrib/url-loader/commit/ced5990))
* add `fallback` option ([#88](https://github.com/webpack-contrib/url-loader/issues/88)) ([636ebed](https://github.com/webpack-contrib/url-loader/commit/636ebed))

### Security

* Updates Mime pacakge due to Regex DOS security vulnerability ([#87](https://github.com/webpack-contrib/url-loader/issues/87)) ([d19ee2d](https://github.com/webpack-contrib/url-loader/commit/d19ee2d))

 - Reference issue https://nodesecurity.io/advisories/535


<a name="0.5.9"></a>
## [0.5.9](https://github.com/webpack/url-loader/compare/v0.5.8...v0.5.9) (2017-06-12)


### Bug Fixes

* `String` not being `base64` encoded ([#67](https://github.com/webpack/url-loader/issues/67)) ([e9496b9](https://github.com/webpack/url-loader/commit/e9496b9))
* don't default to `0` (`options.limit`) ([#74](https://github.com/webpack/url-loader/issues/74)) ([020c2a8](https://github.com/webpack/url-loader/commit/020c2a8))



# Change Log

All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.


---

<div align="center">
  <a href="https://github.com/webpack/webpack">
    <img width="200" height="200" src="https://webpack.js.org/assets/icon-square-big.svg">
  </a>
</div>

[![npm][npm]][npm-url]
[![node][node]][node-url]
[![deps][deps]][deps-url]
[![tests][tests]][tests-url]
[![chat][chat]][chat-url]
[![size][size]][size-url]

# url-loader

A loader for webpack which transforms files into base64 URIs.

## Getting Started

To begin, you'll need to install `url-loader`:

```console
$ npm install url-loader --save-dev
```

`url-loader` works like
[`file-loader`](https://github.com/webpack-contrib/file-loader), but can return
a DataURL if the file is smaller than a byte limit.

**index.js**

```js
import img from './image.png';
```

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpg|gif)$/i,
        use: [
          {
            loader: 'url-loader',
            options: {
              limit: 8192,
            },
          },
        ],
      },
    ],
  },
};
```

And run `webpack` via your preferred method.

## Options

|             Name              |            Type             |                            Default                            | Description                                                                         |
| :---------------------------: | :-------------------------: | :-----------------------------------------------------------: | :---------------------------------------------------------------------------------- |
|     **[`limit`](#limit)**     | `{Boolean\|Number\|String}` |                            `true`                             | Specifying the maximum size of a file in bytes.                                     |
|  **[`mimetype`](#mimetype)**  |     `{Boolean\|String}`     | based from [mime-types](https://github.com/jshttp/mime-types) | Sets the MIME type for the file to be transformed.                                  |
|  **[`encoding`](#encoding)**  |     `{Boolean\|String}`     |                           `base64`                            | Specify the encoding which the file will be inlined with.                           |
| **[`generator`](#generator)** |        `{Function}`         |           `() => type/subtype;encoding,base64_data`           | You can create you own custom implementation for encoding data.                     |
|  **[`fallback`](#fallback)**  |         `{String}`          |                         `file-loader`                         | Specifies an alternative loader to use when a target file's size exceeds the limit. |
|  **[`esModule`](#esmodule)**  |         `{Boolean}`         |                            `true`                             | Use ES modules syntax.                                                              |

### `limit`

Type: `Boolean|Number|String`
Default: `undefined`

The limit can be specified via loader options and defaults to no limit.

#### `Boolean`

Enable or disable transform files into base64.

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpg|gif)$/i,
        use: [
          {
            loader: 'url-loader',
            options: {
              limit: false,
            },
          },
        ],
      },
    ],
  },
};
```

#### `Number|String`

A `Number` or `String` specifying the maximum size of a file in bytes.
If the file size is **equal** or **greater** than the limit [`file-loader`](https://github.com/webpack-contrib/file-loader) will be used (by default) and all query parameters are passed to it.

Using an alternative to `file-loader` is enabled via the `fallback` option.

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpg|gif)$/i,
        use: [
          {
            loader: 'url-loader',
            options: {
              limit: 8192,
            },
          },
        ],
      },
    ],
  },
};
```

### `mimetype`

Type: `Boolean|String`
Default: based from [mime-types](https://github.com/jshttp/mime-types)

Specify the `mimetype` which the file will be inlined with.
If unspecified the `mimetype` value will be used from [mime-types](https://github.com/jshttp/mime-types).

#### `Boolean`

The `true` value allows to generation the `mimetype` part from [mime-types](https://github.com/jshttp/mime-types).
The `false` value removes the `mediatype` part from a Data URL (if omitted, defaults to `text/plain;charset=US-ASCII`).

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpg|gif)$/i,
        use: [
          {
            loader: 'url-loader',
            options: {
              mimetype: false,
            },
          },
        ],
      },
    ],
  },
};
```

#### `String`

Sets the MIME type for the file to be transformed.

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpg|gif)$/i,
        use: [
          {
            loader: 'url-loader',
            options: {
              mimetype: 'image/png',
            },
          },
        ],
      },
    ],
  },
};
```

### `encoding`

Type: `Boolean|String`
Default: `base64`

Specify the `encoding` which the file will be inlined with.
If unspecified the `encoding` will be `base64`.

#### `Boolean`

If you don't want to use any encoding you can set `encoding` to `false` however if you set it to `true` it will use the default encoding `base64`.

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.svg$/i,
        use: [
          {
            loader: 'url-loader',
            options: {
              encoding: false,
            },
          },
        ],
      },
    ],
  },
};
```

#### `String`

It supports [Node.js Buffers and Character Encodings](https://nodejs.org/api/buffer.html#buffer_buffers_and_character_encodings) which are `["utf8","utf16le","latin1","base64","hex","ascii","binary","ucs2"]`.

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.svg$/i,
        use: [
          {
            loader: 'url-loader',
            options: {
              encoding: 'utf8',
            },
          },
        ],
      },
    ],
  },
};
```

### `generator`

Type: `Function`
Default: `(mimetype, encoding, content, resourcePath) => mimetype;encoding,base64_content`

You can create you own custom implementation for encoding data.

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|html)$/i,
        use: [
          {
            loader: 'url-loader',
            options: {
              // The `mimetype` and `encoding` arguments will be obtained from your options
              // The `resourcePath` argument is path to file.
              generator: (content, mimetype, encoding, resourcePath) => {
                if (/\.html$/i.test(resourcePath)) {
                  return `data:${mimetype},${content.toString()}`;
                }

                return `data:${mimetype}${
                  encoding ? `;${encoding}` : ''
                },${content.toString(encoding)}`;
              },
            },
          },
        ],
      },
    ],
  },
};
```

### `fallback`

Type: `String`
Default: `'file-loader'`

Specifies an alternative loader to use when a target file's size exceeds the limit set in the `limit` option.

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpg|gif)$/i,
        use: [
          {
            loader: 'url-loader',
            options: {
              fallback: require.resolve('responsive-loader'),
            },
          },
        ],
      },
    ],
  },
};
```

The fallback loader will receive the same configuration options as url-loader.

For example, to set the quality option of a responsive-loader above use:

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpg|gif)$/i,
        use: [
          {
            loader: 'url-loader',
            options: {
              fallback: require.resolve('responsive-loader'),
              quality: 85,
            },
          },
        ],
      },
    ],
  },
};
```

### `esModule`

Type: `Boolean`
Default: `true`

By default, `file-loader` generates JS modules that use the ES modules syntax.
There are some cases in which using ES modules is beneficial, like in the case of [module concatenation](https://webpack.js.org/plugins/module-concatenation-plugin/) and [tree shaking](https://webpack.js.org/guides/tree-shaking/).

You can enable a CommonJS module syntax using:

**webpack.config.js**

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          {
            loader: 'url-loader',
            options: {
              esModule: false,
            },
          },
        ],
      },
    ],
  },
};
```

## Examples

### SVG

SVG can be compressed into a more compact output, avoiding `base64`.
You can read about it more [here](https://css-tricks.com/probably-dont-base64-svg/).
You can do it using [mini-svg-data-uri](https://github.com/tigt/mini-svg-data-uri) package.

**webpack.config.js**

```js
const svgToMiniDataURI = require('mini-svg-data-uri');

module.exports = {
  module: {
    rules: [
      {
        test: /\.svg$/i,
        use: [
          {
            loader: 'url-loader',
            options: {
              generator: (content) => svgToMiniDataURI(content.toString()),
            },
          },
        ],
      },
    ],
  },
};
```

## Contributing

Please take a moment to read our contributing guidelines if you haven't yet done so.

[CONTRIBUTING](./.github/CONTRIBUTING.md)

## License

[MIT](./LICENSE)

[npm]: https://img.shields.io/npm/v/url-loader.svg
[npm-url]: https://npmjs.com/package/url-loader
[node]: https://img.shields.io/node/v/url-loader.svg
[node-url]: https://nodejs.org
[deps]: https://david-dm.org/webpack-contrib/url-loader.svg
[deps-url]: https://david-dm.org/webpack-contrib/url-loader
[tests]: https://github.com/webpack-contrib/url-loader/workflows/url-loader/badge.svg
[tests-url]: https://github.com/webpack-contrib/url-loader/actions
[cover]: https://codecov.io/gh/webpack-contrib/url-loader/branch/master/graph/badge.svg
[cover-url]: https://codecov.io/gh/webpack-contrib/url-loader
[chat]: https://img.shields.io/badge/gitter-webpack%2Fwebpack-brightgreen.svg
[chat-url]: https://gitter.im/webpack/webpack
[size]: https://packagephobia.now.sh/badge?p=url-loader
[size-url]: https://packagephobia.now.sh/result?p=url-loader

```

```


---

1.52.0 / 2022-02-21
===================

  * Add extensions from IANA for more `image/*` types
  * Add extension `.asc` to `application/pgp-keys`
  * Add extensions to various XML types
  * Add new upstream MIME types

1.51.0 / 2021-11-08
===================

  * Add new upstream MIME types
  * Mark `image/vnd.microsoft.icon` as compressible
  * Mark `image/vnd.ms-dds` as compressible

1.50.0 / 2021-09-15
===================

  * Add deprecated iWorks mime types and extensions
  * Add new upstream MIME types

1.49.0 / 2021-07-26
===================

  * Add extension `.trig` to `application/trig`
  * Add new upstream MIME types

1.48.0 / 2021-05-30
===================

  * Add extension `.mvt` to `application/vnd.mapbox-vector-tile`
  * Add new upstream MIME types
  * Mark `text/yaml` as compressible

1.47.0 / 2021-04-01
===================

  * Add new upstream MIME types
  * Remove ambigious extensions from IANA for `application/*+xml` types
  * Update primary extension to `.es` for `application/ecmascript`

1.46.0 / 2021-02-13
===================

  * Add extension `.amr` to `audio/amr`
  * Add extension `.m4s` to `video/iso.segment`
  * Add extension `.opus` to `audio/ogg`
  * Add new upstream MIME types

1.45.0 / 2020-09-22
===================

  * Add `application/ubjson` with extension `.ubj`
  * Add `image/avif` with extension `.avif`
  * Add `image/ktx2` with extension `.ktx2`
  * Add extension `.dbf` to `application/vnd.dbf`
  * Add extension `.rar` to `application/vnd.rar`
  * Add extension `.td` to `application/urc-targetdesc+xml`
  * Add new upstream MIME types
  * Fix extension of `application/vnd.apple.keynote` to be `.key`

1.44.0 / 2020-04-22
===================

  * Add charsets from IANA
  * Add extension `.cjs` to `application/node`
  * Add new upstream MIME types

1.43.0 / 2020-01-05
===================

  * Add `application/x-keepass2` with extension `.kdbx`
  * Add extension `.mxmf` to `audio/mobile-xmf`
  * Add extensions from IANA for `application/*+xml` types
  * Add new upstream MIME types

1.42.0 / 2019-09-25
===================

  * Add `image/vnd.ms-dds` with extension `.dds`
  * Add new upstream MIME types
  * Remove compressible from `multipart/mixed`

1.41.0 / 2019-08-30
===================

  * Add new upstream MIME types
  * Add `application/toml` with extension `.toml`
  * Mark `font/ttf` as compressible

1.40.0 / 2019-04-20
===================

  * Add extensions from IANA for `model/*` types
  * Add `text/mdx` with extension `.mdx`

1.39.0 / 2019-04-04
===================

  * Add extensions `.siv` and `.sieve` to `application/sieve`
  * Add new upstream MIME types

1.38.0 / 2019-02-04
===================

  * Add extension `.nq` to `application/n-quads`
  * Add extension `.nt` to `application/n-triples`
  * Add new upstream MIME types
  * Mark `text/less` as compressible

1.37.0 / 2018-10-19
===================

  * Add extensions to HEIC image types
  * Add new upstream MIME types

1.36.0 / 2018-08-20
===================

  * Add Apple file extensions from IANA
  * Add extensions from IANA for `image/*` types
  * Add new upstream MIME types

1.35.0 / 2018-07-15
===================

  * Add extension `.owl` to `application/rdf+xml`
  * Add new upstream MIME types
    - Removes extension `.woff` from `application/font-woff`

1.34.0 / 2018-06-03
===================

  * Add extension `.csl` to `application/vnd.citationstyles.style+xml`
  * Add extension `.es` to `application/ecmascript`
  * Add new upstream MIME types
  * Add `UTF-8` as default charset for `text/turtle`
  * Mark all XML-derived types as compressible

1.33.0 / 2018-02-15
===================

  * Add extensions from IANA for `message/*` types
  * Add new upstream MIME types
  * Fix some incorrect OOXML types
  * Remove `application/font-woff2`

1.32.0 / 2017-11-29
===================

  * Add new upstream MIME types
  * Update `text/hjson` to registered `application/hjson`
  * Add `text/shex` with extension `.shex`

1.31.0 / 2017-10-25
===================

  * Add `application/raml+yaml` with extension `.raml`
  * Add `application/wasm` with extension `.wasm`
  * Add new `font` type from IANA
  * Add new upstream font extensions
  * Add new upstream MIME types
  * Add extensions for JPEG-2000 images

1.30.0 / 2017-08-27
===================

  * Add `application/vnd.ms-outlook`
  * Add `application/x-arj`
  * Add extension `.mjs` to `application/javascript`
  * Add glTF types and extensions
  * Add new upstream MIME types
  * Add `text/x-org`
  * Add VirtualBox MIME types
  * Fix `source` records for `video/*` types that are IANA
  * Update `font/opentype` to registered `font/otf`

1.29.0 / 2017-07-10
===================

  * Add `application/fido.trusted-apps+json`
  * Add extension `.wadl` to `application/vnd.sun.wadl+xml`
  * Add new upstream MIME types
  * Add `UTF-8` as default charset for `text/css`

1.28.0 / 2017-05-14
===================

  * Add new upstream MIME types
  * Add extension `.gz` to `application/gzip`
  * Update extensions `.md` and `.markdown` to be `text/markdown`

1.27.0 / 2017-03-16
===================

  * Add new upstream MIME types
  * Add `image/apng` with extension `.apng`

1.26.0 / 2017-01-14
===================

  * Add new upstream MIME types
  * Add extension `.geojson` to `application/geo+json`

1.25.0 / 2016-11-11
===================

  * Add new upstream MIME types

1.24.0 / 2016-09-18
===================

  * Add `audio/mp3`
  * Add new upstream MIME types

1.23.0 / 2016-05-01
===================

  * Add new upstream MIME types
  * Add extension `.3gpp` to `audio/3gpp`

1.22.0 / 2016-02-15
===================

  * Add `text/slim`
  * Add extension `.rng` to `application/xml`
  * Add new upstream MIME types
  * Fix extension of `application/dash+xml` to be `.mpd`
  * Update primary extension to `.m4a` for `audio/mp4`

1.21.0 / 2016-01-06
===================

  * Add Google document types
  * Add new upstream MIME types

1.20.0 / 2015-11-10
===================

  * Add `text/x-suse-ymp`
  * Add new upstream MIME types

1.19.0 / 2015-09-17
===================

  * Add `application/vnd.apple.pkpass`
  * Add new upstream MIME types

1.18.0 / 2015-09-03
===================

  * Add new upstream MIME types

1.17.0 / 2015-08-13
===================

  * Add `application/x-msdos-program`
  * Add `audio/g711-0`
  * Add `image/vnd.mozilla.apng`
  * Add extension `.exe` to `application/x-msdos-program`

1.16.0 / 2015-07-29
===================

  * Add `application/vnd.uri-map`

1.15.0 / 2015-07-13
===================

  * Add `application/x-httpd-php`

1.14.0 / 2015-06-25
===================

  * Add `application/scim+json`
  * Add `application/vnd.3gpp.ussd+xml`
  * Add `application/vnd.biopax.rdf+xml`
  * Add `text/x-processing`

1.13.0 / 2015-06-07
===================

  * Add nginx as a source
  * Add `application/x-cocoa`
  * Add `application/x-java-archive-diff`
  * Add `application/x-makeself`
  * Add `application/x-perl`
  * Add `application/x-pilot`
  * Add `application/x-redhat-package-manager`
  * Add `application/x-sea`
  * Add `audio/x-m4a`
  * Add `audio/x-realaudio`
  * Add `image/x-jng`
  * Add `text/mathml`

1.12.0 / 2015-06-05
===================

  * Add `application/bdoc`
  * Add `application/vnd.hyperdrive+json`
  * Add `application/x-bdoc`
  * Add extension `.rtf` to `text/rtf`

1.11.0 / 2015-05-31
===================

  * Add `audio/wav`
  * Add `audio/wave`
  * Add extension `.litcoffee` to `text/coffeescript`
  * Add extension `.sfd-hdstx` to `application/vnd.hydrostatix.sof-data`
  * Add extension `.n-gage` to `application/vnd.nokia.n-gage.symbian.install`

1.10.0 / 2015-05-19
===================

  * Add `application/vnd.balsamiq.bmpr`
  * Add `application/vnd.microsoft.portable-executable`
  * Add `application/x-ns-proxy-autoconfig`

1.9.1 / 2015-04-19
==================

  * Remove `.json` extension from `application/manifest+json`
    - This is causing bugs downstream

1.9.0 / 2015-04-19
==================

  * Add `application/manifest+json`
  * Add `application/vnd.micro+json`
  * Add `image/vnd.zbrush.pcx`
  * Add `image/x-ms-bmp`

1.8.0 / 2015-03-13
==================

  * Add `application/vnd.citationstyles.style+xml`
  * Add `application/vnd.fastcopy-disk-image`
  * Add `application/vnd.gov.sk.xmldatacontainer+xml`
  * Add extension `.jsonld` to `application/ld+json`

1.7.0 / 2015-02-08
==================

  * Add `application/vnd.gerber`
  * Add `application/vnd.msa-disk-image`

1.6.1 / 2015-02-05
==================

  * Community extensions ownership transferred from `node-mime`

1.6.0 / 2015-01-29
==================

  * Add `application/jose`
  * Add `application/jose+json`
  * Add `application/json-seq`
  * Add `application/jwk+json`
  * Add `application/jwk-set+json`
  * Add `application/jwt`
  * Add `application/rdap+json`
  * Add `application/vnd.gov.sk.e-form+xml`
  * Add `application/vnd.ims.imsccv1p3`

1.5.0 / 2014-12-30
==================

  * Add `application/vnd.oracle.resource+json`
  * Fix various invalid MIME type entries
    - `application/mbox+xml`
    - `application/oscp-response`
    - `application/vwg-multiplexed`
    - `audio/g721`

1.4.0 / 2014-12-21
==================

  * Add `application/vnd.ims.imsccv1p2`
  * Fix various invalid MIME type entries
    - `application/vnd-acucobol`
    - `application/vnd-curl`
    - `application/vnd-dart`
    - `application/vnd-dxr`
    - `application/vnd-fdf`
    - `application/vnd-mif`
    - `application/vnd-sema`
    - `application/vnd-wap-wmlc`
    - `application/vnd.adobe.flash-movie`
    - `application/vnd.dece-zip`
    - `application/vnd.dvb_service`
    - `application/vnd.micrografx-igx`
    - `application/vnd.sealed-doc`
    - `application/vnd.sealed-eml`
    - `application/vnd.sealed-mht`
    - `application/vnd.sealed-ppt`
    - `application/vnd.sealed-tiff`
    - `application/vnd.sealed-xls`
    - `application/vnd.sealedmedia.softseal-html`
    - `application/vnd.sealedmedia.softseal-pdf`
    - `application/vnd.wap-slc`
    - `application/vnd.wap-wbxml`
    - `audio/vnd.sealedmedia.softseal-mpeg`
    - `image/vnd-djvu`
    - `image/vnd-svf`
    - `image/vnd-wap-wbmp`
    - `image/vnd.sealed-png`
    - `image/vnd.sealedmedia.softseal-gif`
    - `image/vnd.sealedmedia.softseal-jpg`
    - `model/vnd-dwf`
    - `model/vnd.parasolid.transmit-binary`
    - `model/vnd.parasolid.transmit-text`
    - `text/vnd-a`
    - `text/vnd-curl`
    - `text/vnd.wap-wml`
  * Remove example template MIME types
    - `application/example`
    - `audio/example`
    - `image/example`
    - `message/example`
    - `model/example`
    - `multipart/example`
    - `text/example`
    - `video/example`

1.3.1 / 2014-12-16
==================

  * Fix missing extensions
    - `application/json5`
    - `text/hjson`

1.3.0 / 2014-12-07
==================

  * Add `application/a2l`
  * Add `application/aml`
  * Add `application/atfx`
  * Add `application/atxml`
  * Add `application/cdfx+xml`
  * Add `application/dii`
  * Add `application/json5`
  * Add `application/lxf`
  * Add `application/mf4`
  * Add `application/vnd.apache.thrift.compact`
  * Add `application/vnd.apache.thrift.json`
  * Add `application/vnd.coffeescript`
  * Add `application/vnd.enphase.envoy`
  * Add `application/vnd.ims.imsccv1p1`
  * Add `text/csv-schema`
  * Add `text/hjson`
  * Add `text/markdown`
  * Add `text/yaml`

1.2.0 / 2014-11-09
==================

  * Add `application/cea`
  * Add `application/dit`
  * Add `application/vnd.gov.sk.e-form+zip`
  * Add `application/vnd.tmd.mediaflex.api+xml`
  * Type `application/epub+zip` is now IANA-registered

1.1.2 / 2014-10-23
==================

  * Rebuild database for `application/x-www-form-urlencoded` change

1.1.1 / 2014-10-20
==================

  * Mark `application/x-www-form-urlencoded` as compressible.

1.1.0 / 2014-09-28
==================

  * Add `application/font-woff2`

1.0.3 / 2014-09-25
==================

  * Fix engine requirement in package

1.0.2 / 2014-09-25
==================

  * Add `application/coap-group+json`
  * Add `application/dcd`
  * Add `application/vnd.apache.thrift.binary`
  * Add `image/vnd.tencent.tap`
  * Mark all JSON-derived types as compressible
  * Update `text/vtt` data

1.0.1 / 2014-08-30
==================

  * Fix extension ordering

1.0.0 / 2014-08-30
==================

  * Add `application/atf`
  * Add `application/merge-patch+json`
  * Add `multipart/x-mixed-replace`
  * Add `source: 'apache'` metadata
  * Add `source: 'iana'` metadata
  * Remove badly-assumed charset data


---

# mime-db

[![NPM Version][npm-version-image]][npm-url]
[![NPM Downloads][npm-downloads-image]][npm-url]
[![Node.js Version][node-image]][node-url]
[![Build Status][ci-image]][ci-url]
[![Coverage Status][coveralls-image]][coveralls-url]

This is a large database of mime types and information about them.
It consists of a single, public JSON file and does not include any logic,
allowing it to remain as un-opinionated as possible with an API.
It aggregates data from the following sources:

- http://www.iana.org/assignments/media-types/media-types.xhtml
- http://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/conf/mime.types
- http://hg.nginx.org/nginx/raw-file/default/conf/mime.types

## Installation

```bash
npm install mime-db
```

### Database Download

If you're crazy enough to use this in the browser, you can just grab the
JSON file using [jsDelivr](https://www.jsdelivr.com/). It is recommended to
replace `master` with [a release tag](https://github.com/jshttp/mime-db/tags)
as the JSON format may change in the future.

```
https://cdn.jsdelivr.net/gh/jshttp/mime-db@master/db.json
```

## Usage

```js
var db = require('mime-db')

// grab data on .js files
var data = db['application/javascript']
```

## Data Structure

The JSON file is a map lookup for lowercased mime types.
Each mime type has the following properties:

- `.source` - where the mime type is defined.
    If not set, it's probably a custom media type.
    - `apache` - [Apache common media types](http://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/conf/mime.types)
    - `iana` - [IANA-defined media types](http://www.iana.org/assignments/media-types/media-types.xhtml)
    - `nginx` - [nginx media types](http://hg.nginx.org/nginx/raw-file/default/conf/mime.types)
- `.extensions[]` - known extensions associated with this mime type.
- `.compressible` - whether a file of this type can be gzipped.
- `.charset` - the default charset associated with this type, if any.

If unknown, every property could be `undefined`.

## Contributing

To edit the database, only make PRs against `src/custom-types.json` or
`src/custom-suffix.json`.

The `src/custom-types.json` file is a JSON object with the MIME type as the
keys and the values being an object with the following keys:

- `compressible` - leave out if you don't know, otherwise `true`/`false` to
  indicate whether the data represented by the type is typically compressible.
- `extensions` - include an array of file extensions that are associated with
  the type.
- `notes` - human-readable notes about the type, typically what the type is.
- `sources` - include an array of URLs of where the MIME type and the associated
  extensions are sourced from. This needs to be a [primary source](https://en.wikipedia.org/wiki/Primary_source);
  links to type aggregating sites and Wikipedia are _not acceptable_.

To update the build, run `npm run build`.

### Adding Custom Media Types

The best way to get new media types included in this library is to register
them with the IANA. The community registration procedure is outlined in
[RFC 6838 section 5](http://tools.ietf.org/html/rfc6838#section-5). Types
registered with the IANA are automatically pulled into this library.

If that is not possible / feasible, they can be added directly here as a
"custom" type. To do this, it is required to have a primary source that
definitively lists the media type. If an extension is going to be listed as
associateed with this media type, the source must definitively link the
media type and extension as well.

[ci-image]: https://badgen.net/github/checks/jshttp/mime-db/master?label=ci
[ci-url]: https://github.com/jshttp/mime-db/actions?query=workflow%3Aci
[coveralls-image]: https://badgen.net/coveralls/c/github/jshttp/mime-db/master
[coveralls-url]: https://coveralls.io/r/jshttp/mime-db?branch=master
[node-image]: https://badgen.net/npm/node/mime-db
[node-url]: https://nodejs.org/en/download
[npm-downloads-image]: https://badgen.net/npm/dm/mime-db
[npm-url]: https://npmjs.org/package/mime-db
[npm-version-image]: https://badgen.net/npm/v/mime-db


---

2.1.35 / 2022-03-12
===================

  * deps: mime-db@1.52.0
    - Add extensions from IANA for more `image/*` types
    - Add extension `.asc` to `application/pgp-keys`
    - Add extensions to various XML types
    - Add new upstream MIME types

2.1.34 / 2021-11-08
===================

  * deps: mime-db@1.51.0
    - Add new upstream MIME types

2.1.33 / 2021-10-01
===================

  * deps: mime-db@1.50.0
    - Add deprecated iWorks mime types and extensions
    - Add new upstream MIME types

2.1.32 / 2021-07-27
===================

  * deps: mime-db@1.49.0
    - Add extension `.trig` to `application/trig`
    - Add new upstream MIME types

2.1.31 / 2021-06-01
===================

  * deps: mime-db@1.48.0
    - Add extension `.mvt` to `application/vnd.mapbox-vector-tile`
    - Add new upstream MIME types

2.1.30 / 2021-04-02
===================

  * deps: mime-db@1.47.0
    - Add extension `.amr` to `audio/amr`
    - Remove ambigious extensions from IANA for `application/*+xml` types
    - Update primary extension to `.es` for `application/ecmascript`

2.1.29 / 2021-02-17
===================

  * deps: mime-db@1.46.0
    - Add extension `.amr` to `audio/amr`
    - Add extension `.m4s` to `video/iso.segment`
    - Add extension `.opus` to `audio/ogg`
    - Add new upstream MIME types

2.1.28 / 2021-01-01
===================

  * deps: mime-db@1.45.0
    - Add `application/ubjson` with extension `.ubj`
    - Add `image/avif` with extension `.avif`
    - Add `image/ktx2` with extension `.ktx2`
    - Add extension `.dbf` to `application/vnd.dbf`
    - Add extension `.rar` to `application/vnd.rar`
    - Add extension `.td` to `application/urc-targetdesc+xml`
    - Add new upstream MIME types
    - Fix extension of `application/vnd.apple.keynote` to be `.key`

2.1.27 / 2020-04-23
===================

  * deps: mime-db@1.44.0
    - Add charsets from IANA
    - Add extension `.cjs` to `application/node`
    - Add new upstream MIME types

2.1.26 / 2020-01-05
===================

  * deps: mime-db@1.43.0
    - Add `application/x-keepass2` with extension `.kdbx`
    - Add extension `.mxmf` to `audio/mobile-xmf`
    - Add extensions from IANA for `application/*+xml` types
    - Add new upstream MIME types

2.1.25 / 2019-11-12
===================

  * deps: mime-db@1.42.0
    - Add new upstream MIME types
    - Add `application/toml` with extension `.toml`
    - Add `image/vnd.ms-dds` with extension `.dds`

2.1.24 / 2019-04-20
===================

  * deps: mime-db@1.40.0
    - Add extensions from IANA for `model/*` types
    - Add `text/mdx` with extension `.mdx`

2.1.23 / 2019-04-17
===================

  * deps: mime-db@~1.39.0
    - Add extensions `.siv` and `.sieve` to `application/sieve`
    - Add new upstream MIME types

2.1.22 / 2019-02-14
===================

  * deps: mime-db@~1.38.0
    - Add extension `.nq` to `application/n-quads`
    - Add extension `.nt` to `application/n-triples`
    - Add new upstream MIME types

2.1.21 / 2018-10-19
===================

  * deps: mime-db@~1.37.0
    - Add extensions to HEIC image types
    - Add new upstream MIME types

2.1.20 / 2018-08-26
===================

  * deps: mime-db@~1.36.0
    - Add Apple file extensions from IANA
    - Add extensions from IANA for `image/*` types
    - Add new upstream MIME types

2.1.19 / 2018-07-17
===================

  * deps: mime-db@~1.35.0
    - Add extension `.csl` to `application/vnd.citationstyles.style+xml`
    - Add extension `.es` to `application/ecmascript`
    - Add extension `.owl` to `application/rdf+xml`
    - Add new upstream MIME types
    - Add UTF-8 as default charset for `text/turtle`

2.1.18 / 2018-02-16
===================

  * deps: mime-db@~1.33.0
    - Add `application/raml+yaml` with extension `.raml`
    - Add `application/wasm` with extension `.wasm`
    - Add `text/shex` with extension `.shex`
    - Add extensions for JPEG-2000 images
    - Add extensions from IANA for `message/*` types
    - Add new upstream MIME types
    - Update font MIME types
    - Update `text/hjson` to registered `application/hjson`

2.1.17 / 2017-09-01
===================

  * deps: mime-db@~1.30.0
    - Add `application/vnd.ms-outlook`
    - Add `application/x-arj`
    - Add extension `.mjs` to `application/javascript`
    - Add glTF types and extensions
    - Add new upstream MIME types
    - Add `text/x-org`
    - Add VirtualBox MIME types
    - Fix `source` records for `video/*` types that are IANA
    - Update `font/opentype` to registered `font/otf`

2.1.16 / 2017-07-24
===================

  * deps: mime-db@~1.29.0
    - Add `application/fido.trusted-apps+json`
    - Add extension `.wadl` to `application/vnd.sun.wadl+xml`
    - Add extension `.gz` to `application/gzip`
    - Add new upstream MIME types
    - Update extensions `.md` and `.markdown` to be `text/markdown`

2.1.15 / 2017-03-23
===================

  * deps: mime-db@~1.27.0
    - Add new mime types
    - Add `image/apng`

2.1.14 / 2017-01-14
===================

  * deps: mime-db@~1.26.0
    - Add new mime types

2.1.13 / 2016-11-18
===================

  * deps: mime-db@~1.25.0
    - Add new mime types

2.1.12 / 2016-09-18
===================

  * deps: mime-db@~1.24.0
    - Add new mime types
    - Add `audio/mp3`

2.1.11 / 2016-05-01
===================

  * deps: mime-db@~1.23.0
    - Add new mime types

2.1.10 / 2016-02-15
===================

  * deps: mime-db@~1.22.0
    - Add new mime types
    - Fix extension of `application/dash+xml`
    - Update primary extension for `audio/mp4`

2.1.9 / 2016-01-06
==================

  * deps: mime-db@~1.21.0
    - Add new mime types

2.1.8 / 2015-11-30
==================

  * deps: mime-db@~1.20.0
    - Add new mime types

2.1.7 / 2015-09-20
==================

  * deps: mime-db@~1.19.0
    - Add new mime types

2.1.6 / 2015-09-03
==================

  * deps: mime-db@~1.18.0
    - Add new mime types

2.1.5 / 2015-08-20
==================

  * deps: mime-db@~1.17.0
    - Add new mime types

2.1.4 / 2015-07-30
==================

  * deps: mime-db@~1.16.0
    - Add new mime types

2.1.3 / 2015-07-13
==================

  * deps: mime-db@~1.15.0
    - Add new mime types

2.1.2 / 2015-06-25
==================

  * deps: mime-db@~1.14.0
    - Add new mime types

2.1.1 / 2015-06-08
==================

  * perf: fix deopt during mapping

2.1.0 / 2015-06-07
==================

  * Fix incorrectly treating extension-less file name as extension
    - i.e. `'path/to/json'` will no longer return `application/json`
  * Fix `.charset(type)` to accept parameters
  * Fix `.charset(type)` to match case-insensitive
  * Improve generation of extension to MIME mapping
  * Refactor internals for readability and no argument reassignment
  * Prefer `application/*` MIME types from the same source
  * Prefer any type over `application/octet-stream`
  * deps: mime-db@~1.13.0
    - Add nginx as a source
    - Add new mime types

2.0.14 / 2015-06-06
===================

  * deps: mime-db@~1.12.0
    - Add new mime types

2.0.13 / 2015-05-31
===================

  * deps: mime-db@~1.11.0
    - Add new mime types

2.0.12 / 2015-05-19
===================

  * deps: mime-db@~1.10.0
    - Add new mime types

2.0.11 / 2015-05-05
===================

  * deps: mime-db@~1.9.1
    - Add new mime types

2.0.10 / 2015-03-13
===================

  * deps: mime-db@~1.8.0
    - Add new mime types

2.0.9 / 2015-02-09
==================

  * deps: mime-db@~1.7.0
    - Add new mime types
    - Community extensions ownership transferred from `node-mime`

2.0.8 / 2015-01-29
==================

  * deps: mime-db@~1.6.0
    - Add new mime types

2.0.7 / 2014-12-30
==================

  * deps: mime-db@~1.5.0
    - Add new mime types
    - Fix various invalid MIME type entries

2.0.6 / 2014-12-30
==================

  * deps: mime-db@~1.4.0
    - Add new mime types
    - Fix various invalid MIME type entries
    - Remove example template MIME types

2.0.5 / 2014-12-29
==================

  * deps: mime-db@~1.3.1
    - Fix missing extensions

2.0.4 / 2014-12-10
==================

  * deps: mime-db@~1.3.0
    - Add new mime types

2.0.3 / 2014-11-09
==================

  * deps: mime-db@~1.2.0
    - Add new mime types

2.0.2 / 2014-09-28
==================

  * deps: mime-db@~1.1.0
    - Add new mime types
    - Update charsets

2.0.1 / 2014-09-07
==================

  * Support Node.js 0.6

2.0.0 / 2014-09-02
==================

  * Use `mime-db`
  * Remove `.define()`

1.0.2 / 2014-08-04
==================

  * Set charset=utf-8 for `text/javascript`

1.0.1 / 2014-06-24
==================

  * Add `text/jsx` type

1.0.0 / 2014-05-12
==================

  * Return `false` for unknown types
  * Set charset=utf-8 for `application/json`

0.1.0 / 2014-05-02
==================

  * Initial release


---

# mime-types

[![NPM Version][npm-version-image]][npm-url]
[![NPM Downloads][npm-downloads-image]][npm-url]
[![Node.js Version][node-version-image]][node-version-url]
[![Build Status][ci-image]][ci-url]
[![Test Coverage][coveralls-image]][coveralls-url]

The ultimate javascript content-type utility.

Similar to [the `mime@1.x` module](https://www.npmjs.com/package/mime), except:

- __No fallbacks.__ Instead of naively returning the first available type,
  `mime-types` simply returns `false`, so do
  `var type = mime.lookup('unrecognized') || 'application/octet-stream'`.
- No `new Mime()` business, so you could do `var lookup = require('mime-types').lookup`.
- No `.define()` functionality
- Bug fixes for `.lookup(path)`

Otherwise, the API is compatible with `mime` 1.x.

## Install

This is a [Node.js](https://nodejs.org/en/) module available through the
[npm registry](https://www.npmjs.com/). Installation is done using the
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):

```sh
$ npm install mime-types
```

## Adding Types

All mime types are based on [mime-db](https://www.npmjs.com/package/mime-db),
so open a PR there if you'd like to add mime types.

## API

```js
var mime = require('mime-types')
```

All functions return `false` if input is invalid or not found.

### mime.lookup(path)

Lookup the content-type associated with a file.

```js
mime.lookup('json') // 'application/json'
mime.lookup('.md') // 'text/markdown'
mime.lookup('file.html') // 'text/html'
mime.lookup('folder/file.js') // 'application/javascript'
mime.lookup('folder/.htaccess') // false

mime.lookup('cats') // false
```

### mime.contentType(type)

Create a full content-type header given a content-type or extension.
When given an extension, `mime.lookup` is used to get the matching
content-type, otherwise the given content-type is used. Then if the
content-type does not already have a `charset` parameter, `mime.charset`
is used to get the default charset and add to the returned content-type.

```js
mime.contentType('markdown') // 'text/x-markdown; charset=utf-8'
mime.contentType('file.json') // 'application/json; charset=utf-8'
mime.contentType('text/html') // 'text/html; charset=utf-8'
mime.contentType('text/html; charset=iso-8859-1') // 'text/html; charset=iso-8859-1'

// from a full path
mime.contentType(path.extname('/path/to/file.json')) // 'application/json; charset=utf-8'
```

### mime.extension(type)

Get the default extension for a content-type.

```js
mime.extension('application/octet-stream') // 'bin'
```

### mime.charset(type)

Lookup the implied default charset of a content-type.

```js
mime.charset('text/markdown') // 'UTF-8'
```

### var type = mime.types[extension]

A map of content-types by extension.

### [extensions...] = mime.extensions[type]

A map of extensions by content-type.

## License

[MIT](LICENSE)

[ci-image]: https://badgen.net/github/checks/jshttp/mime-types/master?label=ci
[ci-url]: https://github.com/jshttp/mime-types/actions/workflows/ci.yml
[coveralls-image]: https://badgen.net/coveralls/c/github/jshttp/mime-types/master
[coveralls-url]: https://coveralls.io/r/jshttp/mime-types?branch=master
[node-version-image]: https://badgen.net/npm/node/mime-types
[node-version-url]: https://nodejs.org/en/download
[npm-downloads-image]: https://badgen.net/npm/dm/mime-types
[npm-url]: https://npmjs.org/package/mime-types
[npm-version-image]: https://badgen.net/npm/v/mime-types


---

# Changelog

All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.

## [3.3.0](https://github.com/webpack/schema-utils/compare/v3.2.0...v3.3.0) (2023-06-14)


### Features

* added API to disable and enable validation ([#183](https://github.com/webpack/schema-utils/issues/183)) ([d4d334f](https://github.com/webpack/schema-utils/commit/d4d334f0ba22eb6b6564b1119e8f3ea439e1f2bb))


### Bug Fixes

* **perf:** cache compiled schema ([#182](https://github.com/webpack/schema-utils/issues/182)) ([02aa068](https://github.com/webpack/schema-utils/commit/02aa068df80d99cc576a5ed385f947eb5204c5db))

## [3.2.0](https://github.com/webpack/schema-utils/compare/v3.1.2...v3.2.0) (2023-06-07)


### Features

* implement `undefinedAsNull` keyword for `enum` type ([#176](https://github.com/webpack/schema-utils/issues/176)) ([95826eb](https://github.com/webpack/schema-utils/commit/95826eb9e14bc4b10ab95f962ac2bdca447880a3))

### [3.1.2](https://github.com/webpack/schema-utils/compare/v3.1.1...v3.1.2) (2023-04-15)


### Bug Fixes

* **perf:** reduced initial start time ([#170](https://github.com/webpack/schema-utils/issues/170)) ([8d052e6](https://github.com/webpack/schema-utils/commit/8d052e6764dc9247e7d5b7b1ae8f87ca5047b2b0))

### [3.1.1](https://github.com/webpack/schema-utils/compare/v3.1.0...v3.1.1) (2021-07-19)


### Bug Fixes

* update error message for `integer` ([#136](https://github.com/webpack/schema-utils/issues/136)) ([2daa97e](https://github.com/webpack/schema-utils/commit/2daa97eae87e6790b92711746a6a527b859ac13b))

## [3.1.0](https://github.com/webpack/schema-utils/compare/v3.0.0...v3.1.0) (2021-06-30)


### Features

* added the `link` property in validation error ([589aa59](https://github.com/webpack/schema-utils/commit/589aa5993424a8bc45ec22b67dff55be92c456a9))


### Bug Fixes

* non-empty validation error message ([#116](https://github.com/webpack/schema-utils/issues/116)) ([c51abef](https://github.com/webpack/schema-utils/commit/c51abefa4d4d62e1346b3a105182d36675595077))

## [3.0.0](https://github.com/webpack/schema-utils/compare/v2.7.1...v3.0.0) (2020-10-05)


### ⚠ BREAKING CHANGES

* minimum supported `Node.js` version is `10.13.0`, 
* the packages exports was changed, please use `const { validate } = require('schema-utils');`
* the `ValidateError` export was removed in favor the `ValidationError` export, please use `const { ValidationError } = require('schema-utils');`

### [2.7.1](https://github.com/webpack/schema-utils/compare/v2.7.0...v2.7.1) (2020-08-31)


### Bug Fixes

* remove esModuleInterop from tsconfig ([#110](https://github.com/webpack/schema-utils/issues/110)) ([#111](https://github.com/webpack/schema-utils/issues/111)) ([2f40154](https://github.com/webpack/schema-utils/commit/2f40154b91e45b393258ae9dd8f10cc3b8590b7d))

## [2.7.0](https://github.com/webpack/schema-utils/compare/v2.6.6...v2.7.0) (2020-05-29)


### Features

* improve hints ([a36e535](https://github.com/webpack/schema-utils/commit/a36e535faca1b01e27c3bfa3c8bee9227c3f836c))
* smart not case ([#101](https://github.com/webpack/schema-utils/issues/101)) ([698d8b0](https://github.com/webpack/schema-utils/commit/698d8b05462d86aadb217e25a45c7b953a79a52e))


### Bug Fixes

* move @types/json-schema from devDependencies to dependencies ([#97](https://github.com/webpack/schema-utils/issues/97)) ([#98](https://github.com/webpack/schema-utils/issues/98)) ([945e67d](https://github.com/webpack/schema-utils/commit/945e67db5e19baf7ec7df72813b0739dd56f950d))

### [2.6.6](https://github.com/webpack/schema-utils/compare/v2.6.5...v2.6.6) (2020-04-17)


### Bug Fixes

* improve perf

### [2.6.5](https://github.com/webpack/schema-utils/compare/v2.6.4...v2.6.5) (2020-03-11)


### Bug Fixes

* correct dots at end of sentence ([7284beb](https://github.com/webpack/schema-utils/commit/7284bebe00cd570f1bef2c15951a07b9794038e6))

### [2.6.4](https://github.com/webpack/schema-utils/compare/v2.6.3...v2.6.4) (2020-01-17)


### Bug Fixes

* change `initialised` to `initialized` ([#87](https://github.com/webpack/schema-utils/issues/87)) ([70f12d3](https://github.com/webpack/schema-utils/commit/70f12d33a8eaa27249bc9c1a27f886724cf91ea7))

### [2.6.3](https://github.com/webpack/schema-utils/compare/v2.6.2...v2.6.3) (2020-01-17)


### Bug Fixes

* prefer the `baseDataPath` option from arguments ([#86](https://github.com/webpack/schema-utils/issues/86)) ([e236859](https://github.com/webpack/schema-utils/commit/e236859e85b28e35e1294f86fc1ff596a5031cea))

### [2.6.2](https://github.com/webpack/schema-utils/compare/v2.6.1...v2.6.2) (2020-01-14)


### Bug Fixes

* better handle Windows absolute paths ([#85](https://github.com/webpack/schema-utils/issues/85)) ([1fa2930](https://github.com/webpack/schema-utils/commit/1fa2930a161e907b9fc53a7233d605910afdb883))

### [2.6.1](https://github.com/webpack/schema-utils/compare/v2.6.0...v2.6.1) (2019-11-28)


### Bug Fixes

* typescript declarations ([#84](https://github.com/webpack/schema-utils/issues/84)) ([89d55a9](https://github.com/webpack/schema-utils/commit/89d55a9a8edfa6a8ac8b112f226bb3154e260319))

## [2.6.0](https://github.com/webpack/schema-utils/compare/v2.5.0...v2.6.0) (2019-11-27)


### Features

* support configuration via title ([#81](https://github.com/webpack/schema-utils/issues/81)) ([afddc10](https://github.com/webpack/schema-utils/commit/afddc109f6891cd37a9f1835d50862d119a072bf))


### Bug Fixes

* typescript definitions ([#70](https://github.com/webpack/schema-utils/issues/70)) ([f38158d](https://github.com/webpack/schema-utils/commit/f38158d6d040e2c701622778ae8122fb26a4f990))

## [2.5.0](https://github.com/webpack/schema-utils/compare/v2.4.1...v2.5.0) (2019-10-15)


### Bug Fixes

* rework format for maxLength, minLength ([#67](https://github.com/webpack/schema-utils/issues/67)) ([0d12259](https://github.com/webpack/schema-utils/commit/0d12259))
* support all cases with one number in range ([#64](https://github.com/webpack/schema-utils/issues/64)) ([7fc8069](https://github.com/webpack/schema-utils/commit/7fc8069))
* typescript definition and export naming ([#69](https://github.com/webpack/schema-utils/issues/69)) ([a435b79](https://github.com/webpack/schema-utils/commit/a435b79))


### Features

* "smart" numbers range ([62fb107](https://github.com/webpack/schema-utils/commit/62fb107))

### [2.4.1](https://github.com/webpack/schema-utils/compare/v2.4.0...v2.4.1) (2019-09-27)


### Bug Fixes

* publish definitions ([#58](https://github.com/webpack/schema-utils/issues/58)) ([1885faa](https://github.com/webpack/schema-utils/commit/1885faa))

## [2.4.0](https://github.com/webpack/schema-utils/compare/v2.3.0...v2.4.0) (2019-09-26)


### Features

* better errors when the `type` keyword doesn't exist ([0988be2](https://github.com/webpack/schema-utils/commit/0988be2))
* support $data reference ([#56](https://github.com/webpack/schema-utils/issues/56)) ([d2f11d6](https://github.com/webpack/schema-utils/commit/d2f11d6))
* types definitions ([#52](https://github.com/webpack/schema-utils/issues/52)) ([facb431](https://github.com/webpack/schema-utils/commit/facb431))

## [2.3.0](https://github.com/webpack/schema-utils/compare/v2.2.0...v2.3.0) (2019-09-26)


### Features

* support `not` keyword ([#53](https://github.com/webpack/schema-utils/issues/53)) ([765f458](https://github.com/webpack/schema-utils/commit/765f458))

## [2.2.0](https://github.com/webpack/schema-utils/compare/v2.1.0...v2.2.0) (2019-09-02)


### Features

* better error output for `oneOf` and `anyOf` ([#48](https://github.com/webpack/schema-utils/issues/48)) ([#50](https://github.com/webpack/schema-utils/issues/50)) ([332242f](https://github.com/webpack/schema-utils/commit/332242f))

## [2.1.0](https://github.com/webpack-contrib/schema-utils/compare/v2.0.1...v2.1.0) (2019-08-07)


### Bug Fixes

* throw error on sparse arrays ([#47](https://github.com/webpack-contrib/schema-utils/issues/47)) ([b85ac38](https://github.com/webpack-contrib/schema-utils/commit/b85ac38))


### Features

* export `ValidateError` ([#46](https://github.com/webpack-contrib/schema-utils/issues/46)) ([ff781d7](https://github.com/webpack-contrib/schema-utils/commit/ff781d7))



### [2.0.1](https://github.com/webpack-contrib/schema-utils/compare/v2.0.0...v2.0.1) (2019-07-18)


### Bug Fixes

* error message for empty object ([#44](https://github.com/webpack-contrib/schema-utils/issues/44)) ([0b4b4a2](https://github.com/webpack-contrib/schema-utils/commit/0b4b4a2))



### [2.0.0](https://github.com/webpack-contrib/schema-utils/compare/v1.0.0...v2.0.0) (2019-07-17)


### BREAKING CHANGES

* drop support for Node.js < 8.9.0
* drop support `errorMessage`, please use `description` for links.
* api was changed, please look documentation.
* error messages was fully rewritten.


<a name="1.0.0"></a>
# [1.0.0](https://github.com/webpack-contrib/schema-utils/compare/v0.4.7...v1.0.0) (2018-08-07)


### Features

* **src:** add support for custom error messages ([#33](https://github.com/webpack-contrib/schema-utils/issues/33)) ([1cbe4ef](https://github.com/webpack-contrib/schema-utils/commit/1cbe4ef))



<a name="0.4.7"></a>
## [0.4.7](https://github.com/webpack-contrib/schema-utils/compare/v0.4.6...v0.4.7) (2018-08-07)


### Bug Fixes

* **src:** `node >= v4.0.0` support ([#32](https://github.com/webpack-contrib/schema-utils/issues/32)) ([cb13dd4](https://github.com/webpack-contrib/schema-utils/commit/cb13dd4))



<a name="0.4.6"></a>
## [0.4.6](https://github.com/webpack-contrib/schema-utils/compare/v0.4.5...v0.4.6) (2018-08-06)


### Bug Fixes

* **package:** remove lockfile ([#28](https://github.com/webpack-contrib/schema-utils/issues/28)) ([69f1a81](https://github.com/webpack-contrib/schema-utils/commit/69f1a81))
* **package:** remove unnecessary `webpack` dependency ([#26](https://github.com/webpack-contrib/schema-utils/issues/26)) ([532eaa5](https://github.com/webpack-contrib/schema-utils/commit/532eaa5))



<a name="0.4.5"></a>
## [0.4.5](https://github.com/webpack-contrib/schema-utils/compare/v0.4.4...v0.4.5) (2018-02-13)


### Bug Fixes

* **CHANGELOG:** update broken links ([4483b9f](https://github.com/webpack-contrib/schema-utils/commit/4483b9f))
* **package:** update broken links ([f2494ba](https://github.com/webpack-contrib/schema-utils/commit/f2494ba))



<a name="0.4.4"></a>
## [0.4.4](https://github.com/webpack-contrib/schema-utils/compare/v0.4.3...v0.4.4) (2018-02-13)


### Bug Fixes

* **package:** update `dependencies` ([#22](https://github.com/webpack-contrib/schema-utils/issues/22)) ([3aecac6](https://github.com/webpack-contrib/schema-utils/commit/3aecac6))



<a name="0.4.3"></a>
## [0.4.3](https://github.com/webpack-contrib/schema-utils/compare/v0.4.2...v0.4.3) (2017-12-14)


### Bug Fixes

* **validateOptions:** throw `err` instead of `process.exit(1)` ([#17](https://github.com/webpack-contrib/schema-utils/issues/17)) ([c595eda](https://github.com/webpack-contrib/schema-utils/commit/c595eda))
* **ValidationError:** never return `this` in the ctor ([#16](https://github.com/webpack-contrib/schema-utils/issues/16)) ([c723791](https://github.com/webpack-contrib/schema-utils/commit/c723791))



<a name="0.4.2"></a>
## [0.4.2](https://github.com/webpack-contrib/schema-utils/compare/v0.4.1...v0.4.2) (2017-11-09)


### Bug Fixes

* **validateOptions:** catch `ValidationError` and handle it internally ([#15](https://github.com/webpack-contrib/schema-utils/issues/15)) ([9c5ef5e](https://github.com/webpack-contrib/schema-utils/commit/9c5ef5e))



<a name="0.4.1"></a>
## [0.4.1](https://github.com/webpack-contrib/schema-utils/compare/v0.4.0...v0.4.1) (2017-11-03)


### Bug Fixes

* **ValidationError:** use `Error.captureStackTrace` for `err.stack` handling ([#14](https://github.com/webpack-contrib/schema-utils/issues/14)) ([a6fb974](https://github.com/webpack-contrib/schema-utils/commit/a6fb974))



<a name="0.4.0"></a>
# [0.4.0](https://github.com/webpack-contrib/schema-utils/compare/v0.3.0...v0.4.0) (2017-10-28)


### Features

* add support for `typeof`, `instanceof` (`{Function\|RegExp}`) ([#10](https://github.com/webpack-contrib/schema-utils/issues/10)) ([9f01816](https://github.com/webpack-contrib/schema-utils/commit/9f01816))



<a name="0.3.0"></a>
# [0.3.0](https://github.com/webpack-contrib/schema-utils/compare/v0.2.1...v0.3.0) (2017-04-29)


### Features

* add ValidationError ([#8](https://github.com/webpack-contrib/schema-utils/issues/8)) ([d48f0fb](https://github.com/webpack-contrib/schema-utils/commit/d48f0fb))



<a name="0.2.1"></a>
## [0.2.1](https://github.com/webpack-contrib/schema-utils/compare/v0.2.0...v0.2.1) (2017-03-13)


### Bug Fixes

* Include .babelrc to `files` ([28f0363](https://github.com/webpack-contrib/schema-utils/commit/28f0363))
* Include source to `files` ([43b0f2f](https://github.com/webpack-contrib/schema-utils/commit/43b0f2f))



<a name="0.2.0"></a>
# [0.2.0](https://github.com/webpack-contrib/schema-utils/compare/v0.1.0...v0.2.0) (2017-03-12)

<a name="0.1.0"></a>
# 0.1.0 (2017-03-07)


### Features

* **validations:** add validateOptions module ([ae9b47b](https://github.com/webpack-contrib/schema-utils/commit/ae9b47b))



# Change Log

All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.


---

<div align="center">
  <a href="http://json-schema.org">
    <img width="160" height="160"
      src="https://raw.githubusercontent.com/webpack-contrib/schema-utils/master/.github/assets/logo.png">
  </a>
  <a href="https://github.com/webpack/webpack">
    <img width="200" height="200"
      src="https://webpack.js.org/assets/icon-square-big.svg">
  </a>
</div>

[![npm][npm]][npm-url]
[![node][node]][node-url]
[![deps][deps]][deps-url]
[![tests][tests]][tests-url]
[![coverage][cover]][cover-url]
[![chat][chat]][chat-url]
[![size][size]][size-url]

# schema-utils

Package for validate options in loaders and plugins.

## Getting Started

To begin, you'll need to install `schema-utils`:

```console
npm install schema-utils
```

## API

**schema.json**

```json
{
  "type": "object",
  "properties": {
    "option": {
      "type": "boolean"
    }
  },
  "additionalProperties": false
}
```

```js
import schema from "./path/to/schema.json";
import { validate } from "schema-utils";

const options = { option: true };
const configuration = { name: "Loader Name/Plugin Name/Name" };

validate(schema, options, configuration);
```

### `schema`

Type: `String`

JSON schema.

Simple example of schema:

```json
{
  "type": "object",
  "properties": {
    "name": {
      "description": "This is description of option.",
      "type": "string"
    }
  },
  "additionalProperties": false
}
```

### `options`

Type: `Object`

Object with options.

```js
import schema from "./path/to/schema.json";
import { validate } from "schema-utils";

const options = { foo: "bar" };

validate(schema, { name: 123 }, { name: "MyPlugin" });
```

### `configuration`

Allow to configure validator.

There is an alternative method to configure the `name` and`baseDataPath` options via the `title` property in the schema.
For example:

```json
{
  "title": "My Loader options",
  "type": "object",
  "properties": {
    "name": {
      "description": "This is description of option.",
      "type": "string"
    }
  },
  "additionalProperties": false
}
```

The last word used for the `baseDataPath` option, other words used for the `name` option.
Based on the example above the `name` option equals `My Loader`, the `baseDataPath` option equals `options`.

#### `name`

Type: `Object`
Default: `"Object"`

Allow to setup name in validation errors.

```js
import schema from "./path/to/schema.json";
import { validate } from "schema-utils";

const options = { foo: "bar" };

validate(schema, options, { name: "MyPlugin" });
```

```shell
Invalid configuration object. MyPlugin has been initialised using a configuration object that does not match the API schema.
 - configuration.optionName should be a integer.
```

#### `baseDataPath`

Type: `String`
Default: `"configuration"`

Allow to setup base data path in validation errors.

```js
import schema from "./path/to/schema.json";
import { validate } from "schema-utils";

const options = { foo: "bar" };

validate(schema, options, { name: "MyPlugin", baseDataPath: "options" });
```

```shell
Invalid options object. MyPlugin has been initialised using an options object that does not match the API schema.
 - options.optionName should be a integer.
```

#### `postFormatter`

Type: `Function`
Default: `undefined`

Allow to reformat errors.

```js
import schema from "./path/to/schema.json";
import { validate } from "schema-utils";

const options = { foo: "bar" };

validate(schema, options, {
  name: "MyPlugin",
  postFormatter: (formattedError, error) => {
    if (error.keyword === "type") {
      return `${formattedError}\nAdditional Information.`;
    }

    return formattedError;
  },
});
```

```shell
Invalid options object. MyPlugin has been initialized using an options object that does not match the API schema.
 - options.optionName should be a integer.
   Additional Information.
```

## Examples

**schema.json**

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "test": {
      "anyOf": [
        { "type": "array" },
        { "type": "string" },
        { "instanceof": "RegExp" }
      ]
    },
    "transform": {
      "instanceof": "Function"
    },
    "sourceMap": {
      "type": "boolean"
    }
  },
  "additionalProperties": false
}
```

### `Loader`

```js
import { getOptions } from "loader-utils";
import { validate } from "schema-utils";

import schema from "path/to/schema.json";

function loader(src, map) {
  const options = getOptions(this);

  validate(schema, options, {
    name: "Loader Name",
    baseDataPath: "options",
  });

  // Code...
}

export default loader;
```

### `Plugin`

```js
import { validate } from "schema-utils";

import schema from "path/to/schema.json";

class Plugin {
  constructor(options) {
    validate(schema, options, {
      name: "Plugin Name",
      baseDataPath: "options",
    });

    this.options = options;
  }

  apply(compiler) {
    // Code...
  }
}

export default Plugin;
```

## Contributing

Please take a moment to read our contributing guidelines if you haven't yet done so.

[CONTRIBUTING](./.github/CONTRIBUTING.md)

## License

[MIT](./LICENSE)

[npm]: https://img.shields.io/npm/v/schema-utils.svg
[npm-url]: https://npmjs.com/package/schema-utils
[node]: https://img.shields.io/node/v/schema-utils.svg
[node-url]: https://nodejs.org
[deps]: https://david-dm.org/webpack/schema-utils.svg
[deps-url]: https://david-dm.org/webpack/schema-utils
[tests]: https://github.com/webpack/schema-utils/workflows/schema-utils/badge.svg
[tests-url]: https://github.com/webpack/schema-utils/actions
[cover]: https://codecov.io/gh/webpack/schema-utils/branch/master/graph/badge.svg
[cover-url]: https://codecov.io/gh/webpack/schema-utils
[chat]: https://badges.gitter.im/webpack/webpack.svg
[chat-url]: https://gitter.im/webpack/webpack
[size]: https://packagephobia.com/badge?p=schema-utils
[size-url]: https://packagephobia.com/result?p=schema-utils


---


1.0.2 / 2015-10-07
==================

  * use try/catch when checking `localStorage` (#3, @kumavis)

1.0.1 / 2014-11-25
==================

  * browser: use `console.warn()` for deprecation calls
  * browser: more jsdocs

1.0.0 / 2014-04-30
==================

  * initial commit


---

util-deprecate
==============
### The Node.js `util.deprecate()` function with browser support

In Node.js, this module simply re-exports the `util.deprecate()` function.

In the web browser (i.e. via browserify), a browser-specific implementation
of the `util.deprecate()` function is used.


## API

A `deprecate()` function is the only thing exposed by this module.

``` javascript
// setup:
exports.foo = deprecate(foo, 'foo() is deprecated, use bar() instead');


// users see:
foo();
// foo() is deprecated, use bar() instead
foo();
foo();
```


## License

(The MIT License)

Copyright (c) 2014 Nathan Rajlich <nathan@tootallnate.net>

Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following
conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.


---

notareplacementforunderscore

# Installation

**npm**: `npm install utila`

**bower**: available via bower as in `bower install utila`, but you should run `npm install` before you can use it.

---

All changelogs can be found in [Releases](https://github.com/piotrwitek/utility-types/releases)


---

<div align="center">

# utility-types

Collection of utility types, complementing TypeScript built-in mapped types and aliases (think "lodash" for static types).

[![Latest Stable Version](https://img.shields.io/npm/v/utility-types.svg)](https://www.npmjs.com/package/utility-types)
[![NPM Downloads](https://img.shields.io/npm/dm/utility-types.svg)](https://www.npmjs.com/package/utility-types)
[![NPM Downloads](https://img.shields.io/npm/dt/utility-types.svg)](https://www.npmjs.com/package/utility-types)
[![Bundlephobia Size](https://img.shields.io/bundlephobia/minzip/utility-types.svg)](https://www.npmjs.com/package/utility-types)

[![Build Status](https://semaphoreci.com/api/v1/piotrekwitek/utility-types/branches/master/shields_badge.svg)](https://semaphoreci.com/piotrekwitek/utility-types)
[![Dependency Status](https://img.shields.io/david/piotrwitek/utility-types.svg)](https://david-dm.org/piotrwitek/utility-types)
[![License](https://img.shields.io/npm/l/utility-types.svg?style=flat)](https://david-dm.org/piotrwitek/utility-types?type=peer)
[![Join the community on Spectrum](https://withspectrum.github.io/badge/badge.svg)](https://spectrum.chat/utility-types)

_Found it useful? Want more updates?_

[**Show your support by giving a :star:**](https://github.com/piotrwitek/utility-types/stargazers)

<a href="https://www.buymeacoffee.com/piotrekwitek">
  <img src="https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png" alt="Buy Me a Coffee">
</a>
<a href="https://www.patreon.com/piotrekwitek">
  <img src="https://c5.patreon.com/external/logo/become_a_patron_button@2x.png" alt="Become a Patron" width="160">
</a>

<br/><hr/>

### **What's new?**

:tada: _Now updated to support **TypeScript v3.7**_ :tada:

<hr/><br/>

</div>

## Features

* Providing a set of [Common Types](#table-of-contents) for TypeScript projects that are idiomatic and complementary to existing [TypeScript Mapped Types](https://www.typescriptlang.org/docs/handbook/advanced-types.html) so you don't need to copy them between the projects.
* Providing a set of [Additional Types](#) compatible with [Flow's Utility Types](https://flow.org/en/docs/types/utilities/) to allow much easier migration to `TypeScript`.

## Goals

* Quality - thoroughly tested for type correctness with type-testing library `dts-jest`
* Secure and minimal - no third-party dependencies
* No runtime cost - it's type-level only

## Installation

```bash
# NPM
npm install utility-types

# YARN
yarn add utility-types
```

## Compatibility Notes

**TypeScript support**
* `v3.x.x` - TypeScript v3.1+
* `v2.x.x` - TypeScript v2.8.1+
* `v1.x.x` - TypeScript v2.7.2+

## Funding Issues
**Utility-Types** is an open-source project created by people investing their time for the benefit of our community.

Issues like bug fixes or feature requests can be very quickly resolved when funded through the IssueHunt platform.

I highly recommend adding a bounty to the issue that you're waiting for to attract some contributors willing to work on it.

[![Let's fund issues in this repository](https://issuehunt.io/static/embed/issuehunt-button-v1.svg)](https://issuehunt.io/repos/76400842)

## Contributing

We are open for contributions. If you're planning to contribute please make sure to read the contributing guide as it can save you from wasting your time: [CONTRIBUTING.md](/CONTRIBUTING.md)

---

* _(built-in)_ - types built-in TypeScript, no need to import

# Table of Contents

## Aliases & Type Guards

* [`Primitive`](#primitive)
* [`isPrimitive`](#isprimitive)
* [`Falsy`](#falsy)
* [`isFalsy`](#isfalsy)

## Union operators

* [`SetIntersection<A, B>`](#setintersectiona-b-same-as-extract)
* [`SetDifference<A, B>`](#setdifferencea-b-same-as-exclude)
* [`SetComplement<A, A1>`](#setcomplementa-a1)
* [`SymmetricDifference<A, B>`](#symmetricdifferencea-b)
* [`Exclude<A, B>`](#excludea-b) _(built-in)_
* [`Extract<A, B>`](#extracta-b) _(built-in)_
* [`NonNullable<T>`](#nonnullablea) _(built-in)_
* [`NonUndefined<T>`](#nonundefineda)

## Object operators

* [`FunctionKeys<T>`](#functionkeyst)
* [`NonFunctionKeys<T>`](#nonfunctionkeyst)
* [`MutableKeys<T>`](#mutablekeyst)
* [`ReadonlyKeys<T>`](#readonlykeyst)
* [`RequiredKeys<T>`](#requiredkeyst)
* [`OptionalKeys<T>`](#optionalkeyst)
* [`Optional<T, K>`](#optionalt-k)
* [`Partial<T>`](#partialt) _(built-in)_
* [`DeepPartial<T>`](#deeppartialt)
* [`Required<T, K>`](#requiredt-k)
* [`DeepRequired<T>`](#deeprequiredt)
* [`Readonly<T>`](#readonlyt) _(built-in)_
* [`DeepReadonly<T>`](#deepreadonlyt)
* [`Mutable<T>`](#mutablet)
* [`Pick<T, K>` _(built-in)_](#pickt-k-built-in)
* [`Omit<T, K>`](#omitt-k) _(built-in)_
* [`PickByValue<T, ValueType>`](#pickbyvaluet-valuetype)
* [`PickByValueExact<T, ValueType>`](#pickbyvalueexactt-valuetype)
* [`OmitByValue<T, ValueType>`](#omitbyvaluet-valuetype)
* [`OmitByValueExact<T, ValueType>`](#omitbyvalueexactt-valuetype)
* [`Intersection<T, U>`](#intersectiont-u)
* [`Diff<T, U>`](#difft-u)
* [`Subtract<T, T1>`](#subtractt-t1)
* [`Overwrite<T, U>`](#overwritet-u)
* [`Assign<T, U>`](#assignt-u)
* [`ValuesType<T>`](#valuestypet)

## Special operators

* [`ReturnType<T>`](#returntypet) _(built-in)_
* [`InstanceType<T>`](#instancetypet) _(built-in)_
* [`PromiseType<T>`](#promisetypet)
* [`Unionize<T>`](#unionizet)
* [`Brand<T, U>`](#brandt-u)
* [`UnionToIntersection<U>`](#uniontointersectionu)

## Flow's Utility Types

* [`$Keys<T>`](#keyst)
* [`$Values<T>`](#valuest)
* [`$ReadOnly<T>`](#readonly2)
* [`$Diff<T, U>`](#diff2)
* [`$PropertyType<T, K>`](#propertytypet-k)
* [`$ElementType<T, K>`](#elementtypet-k)
* [`$Call<T>`](#callt)
* [`$Shape<T>`](#shapet)
* [`$NonMaybeType<T>`](#nonmaybetypet)
* [`Class<T>`](#classt)
* [`mixed`](#mixed)

## Deprecated API (use at own risk)
* `getReturnOfExpression()` - from TS v2.0 it's better to use type-level `ReturnType` instead

---

### `Primitive`

Type representing primitive types in JavaScript, and thus TypeScript: `string | number | bigint | boolean |  symbol | null | undefined`

You can test for singular of these types with [`typeof`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/typeof)

### `isPrimitive`

This is a [TypeScript Typeguard](https://www.typescriptlang.org/docs/handbook/advanced-types.html#type-guards-and-differentiating-types) for the [`Primitive`](#primitive) type.

This can be useful to control the type of a parameter as the program flows. Example:

```ts
const consumer = (param: Primitive[] | Primitive): string => {
    if (isPrimitive(param)) {
        // typeof param === Primitive
        return String(param) + ' was Primitive';
    }
    // typeof param === Primitive[]
    const resultArray = param
        .map(consumer)
        .map(rootString => '\n\t' + rootString);
    return resultArray.reduce((comm, newV) => comm + newV, 'this was nested:');
};
```

[⇧ back to top](#table-of-contents)

### `Falsy`

Type representing falsy values in TypeScript: `false | "" | 0 | null | undefined`
> Except `NaN` which cannot be represented as a type literal

### `isFalsy`

```ts
const consumer = (param: Falsy | string): string => {
    if (isFalsy(param)) {
        // typeof param === Falsy
        return String(param) + ' was Falsy';
    }
    // typeof param === string
    return param.toString();
};
```

[⇧ back to top](#table-of-contents)

### `SetIntersection<A, B>` (same as Extract)

Set intersection of given union types `A` and `B`

**Usage:**

```ts
import { SetIntersection } from 'utility-types';

// Expect: "2" | "3"
type ResultSet = SetIntersection<'1' | '2' | '3', '2' | '3' | '4'>;
// Expect: () => void
type ResultSetMixed = SetIntersection<string | number | (() => void), Function>;
```

[⇧ back to top](#table-of-contents)

### `SetDifference<A, B>` (same as Exclude)

Set difference of given union types `A` and `B`

**Usage:**

```ts
import { SetDifference } from 'utility-types';

// Expect: "1"
type ResultSet = SetDifference<'1' | '2' | '3', '2' | '3' | '4'>;
// Expect: string | number
type ResultSetMixed = SetDifference<string | number | (() => void), Function>;
```

[⇧ back to top](#table-of-contents)

### `SetComplement<A, A1>`

Set complement of given union types `A` and (it's subset) `A1`

**Usage:**

```ts
import { SetComplement } from 'utility-types';

// Expect: "1"
type ResultSet = SetComplement<'1' | '2' | '3', '2' | '3'>;
```

[⇧ back to top](#table-of-contents)

### `SymmetricDifference<A, B>`

Set difference of union and intersection of given union types `A` and `B`

**Usage:**

```ts
import { SymmetricDifference } from 'utility-types';

// Expect: "1" | "4"
type ResultSet = SymmetricDifference<'1' | '2' | '3', '2' | '3' | '4'>;
```

[⇧ back to top](#table-of-contents)

### `NonNullable<A>`

Exclude `null` and `undefined` from set `A`

[⇧ back to top](#table-of-contents)

### `NonUndefined<A>`

Exclude `undefined` from set `A`

[⇧ back to top](#table-of-contents)

### `Exclude<A, B>`

Exclude subset `B` from set `A`

[⇧ back to top](#table-of-contents)

### `Extract<A, B>`

Extract subset `B` from set `A`

[⇧ back to top](#table-of-contents)

## Operations on objects

### `FunctionKeys<T>`

Get union type of keys that are functions in object type `T`

**Usage:**

```ts
import { FunctionKeys } from 'utility-types';

type MixedProps = { name: string; setName: (name: string) => void };

// Expect: "setName"
type Keys = FunctionKeys<MixedProps>;
```

[⇧ back to top](#table-of-contents)

### `NonFunctionKeys<T>`

Get union type of keys that are non-functions in object type `T`

**Usage:**

```ts
import { NonFunctionKeys } from 'utility-types';

type MixedProps = { name: string; setName: (name: string) => void };

// Expect: "name"
type Keys = NonFunctionKeys<MixedProps>;
```

[⇧ back to top](#table-of-contents)

### `MutableKeys<T>`

Get union type of keys that are mutable (not readonly) in object type `T`

Alias: `WritableKeys<T>`

**Usage:**

```ts
import { MutableKeys } from 'utility-types';

type Props = { readonly foo: string; bar: number };

// Expect: "bar"
type Keys = MutableKeys<Props>;
```

[⇧ back to top](#table-of-contents)

### `ReadonlyKeys<T>`

Get union type of keys that are readonly in object type `T`

**Usage:**

```ts
import { ReadonlyKeys } from 'utility-types';

type Props = { readonly foo: string; bar: number };

// Expect: "foo"
type Keys = ReadonlyKeys<Props>;
```

[⇧ back to top](#table-of-contents)

### `RequiredKeys<T>`

Get union type of keys that are required in object type `T`

**Usage:**

```ts
import { RequiredKeys } from 'utility-types';

type Props = { req: number; reqUndef: number | undefined; opt?: string; optUndef?: number | undefined; };

// Expect: "req" | "reqUndef"
type Keys = RequiredKeys<Props>;
```

[⇧ back to top](#table-of-contents)

### `OptionalKeys<T>`

Get union type of keys that are optional in object type `T`

**Usage:**

```ts
import { OptionalKeys } from 'utility-types';

type Props = { req: number; reqUndef: number | undefined; opt?: string; optUndef?: number | undefined; };

// Expect: "opt" | "optUndef"
type Keys = OptionalKeys<Props>;
```

[⇧ back to top](#table-of-contents)

### `Optional<T, K>`

From `T` make a set of properties by key `K` become optional

**Usage:**

```ts
import { Optional } from 'utility-types';

type Props = { name: string; age: number; visible: boolean; };

// Expect: { name?: string; age?: number; visible?: boolean; }
type Props = Optional<Props>
// Expect: { name: string; age?: number; visible?: boolean; }
type Props = Optional<Props, 'age' | 'visible'>;
```

[⇧ back to top](#table-of-contents)


### `Pick<T, K>` _(built-in)_

From `T` pick a set of properties by key `K`

**Usage:**

```ts
type Props = { name: string; age: number; visible: boolean };

// Expect: { age: number; }
type Props = Pick<Props, 'age'>;
```

[⇧ back to top](#table-of-contents)

### `PickByValue<T, ValueType>`

From `T` pick a set of properties by value matching `ValueType`.
_(Credit: [Piotr Lewandowski](https://medium.com/dailyjs/typescript-create-a-condition-based-subset-types-9d902cea5b8c))_

**Usage:**

```ts
import { PickByValue } from 'utility-types';

type Props = { req: number; reqUndef: number | undefined; opt?: string; };

// Expect: { req: number }
type Props = PickByValue<Props, number>;
// Expect: { req: number; reqUndef: number | undefined; }
type Props = PickByValue<Props, number | undefined>;
```

[⇧ back to top](#table-of-contents)

### `PickByValueExact<T, ValueType>`

From `T` pick a set of properties by value matching exact `ValueType`.

**Usage:**

```ts
import { PickByValueExact } from 'utility-types';

type Props = { req: number; reqUndef: number | undefined; opt?: string; };

// Expect: { req: number }
type Props = PickByValueExact<Props, number>;
// Expect: { reqUndef: number | undefined; }
type Props = PickByValueExact<Props, number | undefined>;
```

[⇧ back to top](#table-of-contents)

### `Omit<T, K>`

From `T` remove a set of properties by key `K`

**Usage:**

```ts
import { Omit } from 'utility-types';

type Props = { name: string; age: number; visible: boolean };

// Expect: { name: string; visible: boolean; }
type Props = Omit<Props, 'age'>;
```

[⇧ back to top](#table-of-contents)

### `OmitByValue<T, ValueType>`

From `T` remove a set of properties by value matching `ValueType`.
_(Credit: [Piotr Lewandowski](https://medium.com/dailyjs/typescript-create-a-condition-based-subset-types-9d902cea5b8c))_

**Usage:**

```ts
import { OmitByValue } from 'utility-types';

type Props = { req: number; reqUndef: number | undefined; opt?: string; };

// Expect: { reqUndef: number | undefined; opt?: string; }
type Props = OmitByValue<Props, number>;
// Expect: { opt?: string; }
type Props = OmitByValue<Props, number | undefined>;
```

[⇧ back to top](#table-of-contents)

### `OmitByValueExact<T, ValueType>`

From `T` remove a set of properties by value matching exact `ValueType`.

**Usage:**

```ts
import { OmitByValueExact } from 'utility-types';

type Props = { req: number; reqUndef: number | undefined; opt?: string; };

// Expect: { reqUndef: number | undefined; opt?: string; }
type Props = OmitByValueExact<Props, number>;
// Expect: { req: number; opt?: string }
type Props = OmitByValueExact<Props, number | undefined>;
```

[⇧ back to top](#table-of-contents)

### `Intersection<T, U>`

From `T` pick properties that exist in `U`

**Usage:**

```ts
import { Intersection } from 'utility-types';

type Props = { name: string; age: number; visible: boolean };
type DefaultProps = { age: number };

// Expect: { age: number; }
type DuplicatedProps = Intersection<Props, DefaultProps>;
```

[⇧ back to top](#table-of-contents)

### `Diff<T, U>`

From `T` remove properties that exist in `U`

**Usage:**

```ts
import { Diff } from 'utility-types';

type Props = { name: string; age: number; visible: boolean };
type DefaultProps = { age: number };

// Expect: { name: string; visible: boolean; }
type RequiredProps = Diff<Props, DefaultProps>;
```

[⇧ back to top](#table-of-contents)

### `Subtract<T, T1>`

From `T` remove properties that exist in `T1` (`T1` has a subset of the properties of `T`)

**Usage:**

```ts
import { Subtract } from 'utility-types';

type Props = { name: string; age: number; visible: boolean };
type DefaultProps = { age: number };

// Expect: { name: string; visible: boolean; }
type RequiredProps = Subtract<Props, DefaultProps>;
```

[⇧ back to top](#table-of-contents)

### `Overwrite<T, U>`

From `U` overwrite properties to `T`

**Usage:**

```ts
import { Overwrite } from 'utility-types';

type Props = { name: string; age: number; visible: boolean };
type NewProps = { age: string; other: string };

// Expect: { name: string; age: string; visible: boolean; }
type ReplacedProps = Overwrite<Props, NewProps>;
```

[⇧ back to top](#table-of-contents)

### `Assign<T, U>`

From `U` assign properties to `T` (just like object assign)

**Usage:**

```ts
import { Assign } from 'utility-types';

type Props = { name: string; age: number; visible: boolean };
type NewProps = { age: string; other: string };

// Expect: { name: string; age: number; visible: boolean; other: string; }
type ExtendedProps = Assign<Props, NewProps>;
```

[⇧ back to top](#table-of-contents)

### `ValuesType<T>`

Get the union type of all the values in an object, tuple, array or array-like type `T`.

**Usage:**

```ts
import { ValuesType } from 'utility-types';

type Props = { name: string; age: number; visible: boolean };
// Expect: string | number | boolean
type PropsValues = ValuesType<Props>;

type NumberArray = number[];
// Expect: number
type NumberItems = ValuesType<NumberArray>;

type ReadonlyNumberTuple = readonly [1, 2];
// Expect: 1 | 2
type AnotherNumberUnion = ValuesType<NumberTuple>;

type BinaryArray = Uint8Array;
// Expect: number
type BinaryItems = ValuesType<BinaryArray>;
```

[⇧ back to top](#table-of-contents)

### `Partial<T>`

Make all properties of object type optional

[⇧ back to top](#table-of-contents)

### `Required<T, K>`

From `T` make a set of properties by key `K` become required

**Usage:**

```ts
import { Required } from 'utility-types';

type Props = { name?: string; age?: number; visible?: boolean; };

// Expect: { name: string; age: number; visible: boolean; }
type Props = Required<Props>
// Expect: { name?: string; age: number; visible: boolean; }
type Props = Required<Props, 'age' | 'visible'>;
```

[⇧ back to top](#table-of-contents)

### `Readonly<T>`

Make all properties of object type readonly

[⇧ back to top](#table-of-contents)

### `Mutable<T>`

From `T` make all properties become mutable

Alias: `Writable<T>`

```ts
import { Mutable } from 'utility-types';

type Props = {
  readonly name: string;
  readonly age: number;
  readonly visible: boolean;
};

// Expect: { name: string; age: number; visible: boolean; }
Mutable<Props>;
```

[⇧ back to top](#table-of-contents)

### `ReturnType<T>`

Obtain the return type of a function

[⇧ back to top](#table-of-contents)

### `InstanceType<T>`

Obtain the instance type of a class

[⇧ back to top](#table-of-contents)

### `Unionize<T>`

Disjoin object to form union of objects, each with single property

**Usage:**

```ts
import { Unionize } from 'utility-types';

type Props = { name: string; age: number; visible: boolean };

// Expect: { name: string; } | { age: number; } | { visible: boolean; }
type UnionizedType = Unionize<Props>;
```

[⇧ back to top](#table-of-contents)

### `PromiseType<T>`

Obtain Promise resolve type

**Usage:**

```ts
import { PromiseType } from 'utility-types';

// Expect: string
type Response = PromiseType<Promise<string>>;
```

[⇧ back to top](#table-of-contents)

### `DeepReadonly<T>`

Readonly that works for deeply nested structures

**Usage:**

```ts
import { DeepReadonly } from 'utility-types';

type NestedProps = {
  first: {
    second: {
      name: string;
    };
  };
};

// Expect: {
//   readonly first: {
//     readonly second: {
//       readonly name: string;
//     };
//   };
// }
type ReadonlyNestedProps = DeepReadonly<NestedProps>;
```

[⇧ back to top](#table-of-contents)

### `DeepRequired<T>`

Required that works for deeply nested structures

**Usage:**

```ts
import { DeepRequired } from 'utility-types';

type NestedProps = {
  first?: {
    second?: {
      name?: string;
    };
  };
};

// Expect: {
//   first: {
//     second: {
//       name: string;
//     };
//   };
// }
type RequiredNestedProps = DeepRequired<NestedProps>;
```

[⇧ back to top](#table-of-contents)

### `DeepNonNullable<T>`

NonNullable that works for deeply nested structure

**Usage:**

```ts
import { DeepNonNullable } from 'utility-types';

type NestedProps = {
  first?: null | {
    second?: null | {
      name?: string | null | undefined;
    };
  };
};

// Expect: {
//   first: {
//     second: {
//       name: string;
//     };
//   };
// }
type RequiredNestedProps = DeepNonNullable<NestedProps>;
```

[⇧ back to top](#table-of-contents)

### `DeepPartial<T>`

Partial that works for deeply nested structures

**Usage:**

```ts
import { DeepPartial } from 'utility-types';

type NestedProps = {
  first: {
    second: {
      name: string;
    };
  };
};

// Expect: {
//   first?: {
//     second?: {
//       name?: string;
//     };
//   };
// }
type PartialNestedProps = DeepPartial<NestedProps>;
```

[⇧ back to top](#table-of-contents)

### `Brand<T, U>`

Define nominal type of `U` based on type of `T`. Similar to Opaque types in Flow.

**Usage:**

```ts
import { Brand } from 'utility-types';

type USD = Brand<number, "USD">
type EUR = Brand<number, "EUR">

const tax = 5 as USD;
const usd = 10 as USD;
const eur = 10 as EUR;

function gross(net: USD): USD {
  return (net + tax) as USD;
}

gross(usd); // ok
gross(eur); // Type '"EUR"' is not assignable to type '"USD"'.
```

[⇧ back to top](#table-of-contents)

### `UnionToIntersection<U>`

Get intersection type given union type `U`

**Usage:**

```ts
import { UnionToIntersection } from 'utility-types';

// Expect: { name: string } & { age: number } & { visible: boolean }
UnionToIntersection<{ name: string } | { age: number } | { visible: boolean }>
```

[⇧ back to top](#table-of-contents)

---

## Flow's Utility Types

### `$Keys<T>`

get the union type of all the keys in an object type `T`<br>
https://flow.org/en/docs/types/utilities/#toc-keys

**Usage:**

```ts
import { $Keys } from 'utility-types';

type Props = { name: string; age: number; visible: boolean };

// Expect: "name" | "age" | "visible"
type PropsKeys = $Keys<Props>;
```

[⇧ back to top](#flows-utility-types)

### `$Values<T>`

get the union type of all the values in an object type `T`<br>
https://flow.org/en/docs/types/utilities/#toc-values

**Usage:**

```ts
import { $Values } from 'utility-types';

type Props = { name: string; age: number; visible: boolean };

// Expect: string | number | boolean
type PropsValues = $Values<Props>;
```

[⇧ back to top](#flows-utility-types)

### <a id="readonly2"></a> `$ReadOnly<T>`

get the read-only version of a given object type `T`<br>
https://flow.org/en/docs/types/utilities/#toc-readonly

**Usage:**

```ts
import { $ReadOnly } from 'utility-types';

type Props = { name: string; age: number; visible: boolean };

// Expect: Readonly<{ name: string; age?: number | undefined; visible: boolean; }>
type ReadOnlyProps = $ReadOnly<Props>;
```

[⇧ back to top](#flows-utility-types)

### <a id="diff2"></a> `$Diff<T, U>`

get the set difference of a given object types `T` and `U` (`T \ U`)<br>
https://flow.org/en/docs/types/utilities/#toc-diff

**Usage:**

```ts
import { $Diff } from 'utility-types';

type Props = { name: string; age: number; visible: boolean };
type DefaultProps = { age: number };

// Expect: { name: string; visible: boolean; }
type RequiredProps = $Diff<Props, DefaultProps>;
```

[⇧ back to top](#flows-utility-types)

### `$PropertyType<T, K>`

get the type of property of an object at a given key `K`<br>
https://flow.org/en/docs/types/utilities/#toc-propertytype

**Usage:**

```ts
import { $PropertyType } from 'utility-types';

type Props = { name: string; age: number; visible: boolean };
// Expect: string
type NameType = $PropertyType<Props, 'name'>;

type Tuple = [boolean, number];
// Expect: boolean
type A = $PropertyType<Tuple, '0'>;
// Expect: number
type B = $PropertyType<Tuple, '1'>;
```

[⇧ back to top](#flows-utility-types)

### `$ElementType<T, K>`

get the type of elements inside of array, tuple or object of type `T`, that matches the given index type `K`<br>
https://flow.org/en/docs/types/utilities/#toc-elementtype

**Usage:**

```ts
import { $ElementType } from 'utility-types';

type Props = { name: string; age: number; visible: boolean };
// Expect: string
type NameType = $ElementType<Props, 'name'>;

type Tuple = [boolean, number];
// Expect: boolean
type A = $ElementType<Tuple, 0>;
// Expect: number
type B = $ElementType<Tuple, 1>;

type Arr = boolean[];
// Expect: boolean
type ItemsType = $ElementType<Arr, number>;

type Obj = { [key: string]: number };
// Expect: number
type ValuesType = $ElementType<Obj, string>;
```

[⇧ back to top](#flows-utility-types)

### `$Call<T>`

get the return type of a given expression type<br>
https://flow.org/en/docs/types/utilities/#toc-call

**Usage:**

```ts
import { $Call } from 'utility-types';

// Common use-case
const add = (amount: number) => ({ type: 'ADD' as 'ADD', payload: amount });
type AddAction = $Call<typeof returnOfIncrement>; // { type: 'ADD'; payload: number }

// Examples migrated from Flow docs
type ExtractPropType<T extends { prop: any }> = (arg: T) => T['prop'];
type Obj = { prop: number };
type PropType = $Call<ExtractPropType<Obj>>; // number
// type Nope = $Call<ExtractPropType<{ nope: number }>>; // Error: argument doesn't match `Obj`.

type ExtractReturnType<T extends () => any> = (arg: T) => ReturnType<T>;
type Fn = () => number;
type FnReturnType = $Call<ExtractReturnType<Fn>>; // number
```

[⇧ back to top](#flows-utility-types)

### `$Shape<T>`

Copies the shape of the type supplied, but marks every field optional.<br>
https://flow.org/en/docs/types/utilities/#toc-shape

**Usage:**

```ts
import { $Shape } from 'utility-types';

type Props = { name: string; age: number; visible: boolean };

// Expect: Partial<Props>
type PartialProps = $Shape<Props>;
```

[⇧ back to top](#flows-utility-types)

### `$NonMaybeType<T>`

Converts a type `T` to a non-maybe type. In other words, the values of `$NonMaybeType<T>` are the values of `T` except for `null` and `undefined`.<br>
https://flow.org/en/docs/types/utilities/#toc-nonmaybe

**Usage:**

```ts
import { $NonMaybeType } from 'utility-types';

type MaybeName = string | null;

// Expect: string
type Name = $NonMaybeType<MaybeName>;
```

[⇧ back to top](#flows-utility-types)

### `Class<T>`

Given a type T representing instances of a class C, the type Class<T> is the type of the class C<br>
https://flow.org/en/docs/types/utilities/#toc-class
\* Differs from original Flow's util - implements only constructor part and won't include any static members. Additionally classes in Typescript are not treated as nominal

**Usage:**

```ts
import { Class } from 'utility-types';


function makeStore(storeClass: Class<Store>): Store {
  return new storeClass();
}
```

[⇧ back to top](#flows-utility-types)

### mixed

An arbitrary type that could be anything (same as `unknown`)<br>
https://flow.org/en/docs/types/mixed

[⇧ back to top](#table-of-contents)

---

## Related Projects

- [`ts-toolbelt`](https://github.com/pirix-gh/ts-toolbelt) - Higher type safety for TypeScript
- [`$mol_type`](https://github.com/eigenmethod/mol/tree/master/type) - Collection of TypeScript meta types for complex logic

---

## License

[MIT License](/LICENSE)

Copyright (c) 2016 Piotr Witek <mailto:piotrek.witek@gmail.com> (http://piotrwitek.github.io)


---

# Security Policy

## Supported Versions

Check below to find which versions are currently being supported with security updates.

| Version | Supported          |
| ------- | ------------------ |
| 3.x     | :white_check_mark: |
| < 3.0   | :x: |

## Reporting a Vulnerability

You can report a security vulnerability to this email: piotrek.witek@gmail.com

You'll get a response back to your email shortly after we read your report.
After analysis of vulnerability is completed we will send you the results and 
keep you updated about the next steps.


---

# Support

## Community

If you're looking for support the best place is to check our spectrum community chat:
- https://spectrum.chat/utility-types

## Project Updates

You can also subscribe to receive project updates on my Twitter and BuyMeACoffee profile:
- https://twitter.com/piotrekwitek
- https://www.buymeacoffee.com/piotrekwitek


---

# utils-merge

[![Version](https://img.shields.io/npm/v/utils-merge.svg?label=version)](https://www.npmjs.com/package/utils-merge)
[![Build](https://img.shields.io/travis/jaredhanson/utils-merge.svg)](https://travis-ci.org/jaredhanson/utils-merge)
[![Quality](https://img.shields.io/codeclimate/github/jaredhanson/utils-merge.svg?label=quality)](https://codeclimate.com/github/jaredhanson/utils-merge)
[![Coverage](https://img.shields.io/coveralls/jaredhanson/utils-merge.svg)](https://coveralls.io/r/jaredhanson/utils-merge)
[![Dependencies](https://img.shields.io/david/jaredhanson/utils-merge.svg)](https://david-dm.org/jaredhanson/utils-merge)


Merges the properties from a source object into a destination object.

## Install

```bash
$ npm install utils-merge
```

## Usage

```javascript
var a = { foo: 'bar' }
  , b = { bar: 'baz' };

merge(a, b);
// => { foo: 'bar', bar: 'baz' }
```

## License

[The MIT License](http://opensource.org/licenses/MIT)

Copyright (c) 2013-2017 Jared Hanson <[http://jaredhanson.net/](http://jaredhanson.net/)>

<a target='_blank' rel='nofollow' href='https://app.codesponsor.io/link/vK9dyjRnnWsMzzJTQ57fRJpH/jaredhanson/utils-merge'>  <img alt='Sponsor' width='888' height='68' src='https://app.codesponsor.io/embed/vK9dyjRnnWsMzzJTQ57fRJpH/jaredhanson/utils-merge.svg' /></a>


---

# Changelog

All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.

### [8.3.2](https://github.com/uuidjs/uuid/compare/v8.3.1...v8.3.2) (2020-12-08)

### Bug Fixes

- lazy load getRandomValues ([#537](https://github.com/uuidjs/uuid/issues/537)) ([16c8f6d](https://github.com/uuidjs/uuid/commit/16c8f6df2f6b09b4d6235602d6a591188320a82e)), closes [#536](https://github.com/uuidjs/uuid/issues/536)

### [8.3.1](https://github.com/uuidjs/uuid/compare/v8.3.0...v8.3.1) (2020-10-04)

### Bug Fixes

- support expo>=39.0.0 ([#515](https://github.com/uuidjs/uuid/issues/515)) ([c65a0f3](https://github.com/uuidjs/uuid/commit/c65a0f3fa73b901959d638d1e3591dfacdbed867)), closes [#375](https://github.com/uuidjs/uuid/issues/375)

## [8.3.0](https://github.com/uuidjs/uuid/compare/v8.2.0...v8.3.0) (2020-07-27)

### Features

- add parse/stringify/validate/version/NIL APIs ([#479](https://github.com/uuidjs/uuid/issues/479)) ([0e6c10b](https://github.com/uuidjs/uuid/commit/0e6c10ba1bf9517796ff23c052fc0468eedfd5f4)), closes [#475](https://github.com/uuidjs/uuid/issues/475) [#478](https://github.com/uuidjs/uuid/issues/478) [#480](https://github.com/uuidjs/uuid/issues/480) [#481](https://github.com/uuidjs/uuid/issues/481) [#180](https://github.com/uuidjs/uuid/issues/180)

## [8.2.0](https://github.com/uuidjs/uuid/compare/v8.1.0...v8.2.0) (2020-06-23)

### Features

- improve performance of v1 string representation ([#453](https://github.com/uuidjs/uuid/issues/453)) ([0ee0b67](https://github.com/uuidjs/uuid/commit/0ee0b67c37846529c66089880414d29f3ae132d5))
- remove deprecated v4 string parameter ([#454](https://github.com/uuidjs/uuid/issues/454)) ([88ce3ca](https://github.com/uuidjs/uuid/commit/88ce3ca0ba046f60856de62c7ce03f7ba98ba46c)), closes [#437](https://github.com/uuidjs/uuid/issues/437)
- support jspm ([#473](https://github.com/uuidjs/uuid/issues/473)) ([e9f2587](https://github.com/uuidjs/uuid/commit/e9f2587a92575cac31bc1d4ae944e17c09756659))

### Bug Fixes

- prepare package exports for webpack 5 ([#468](https://github.com/uuidjs/uuid/issues/468)) ([8d6e6a5](https://github.com/uuidjs/uuid/commit/8d6e6a5f8965ca9575eb4d92e99a43435f4a58a8))

## [8.1.0](https://github.com/uuidjs/uuid/compare/v8.0.0...v8.1.0) (2020-05-20)

### Features

- improve v4 performance by reusing random number array ([#435](https://github.com/uuidjs/uuid/issues/435)) ([bf4af0d](https://github.com/uuidjs/uuid/commit/bf4af0d711b4d2ed03d1f74fd12ad0baa87dc79d))
- optimize V8 performance of bytesToUuid ([#434](https://github.com/uuidjs/uuid/issues/434)) ([e156415](https://github.com/uuidjs/uuid/commit/e156415448ec1af2351fa0b6660cfb22581971f2))

### Bug Fixes

- export package.json required by react-native and bundlers ([#449](https://github.com/uuidjs/uuid/issues/449)) ([be1c8fe](https://github.com/uuidjs/uuid/commit/be1c8fe9a3206c358e0059b52fafd7213aa48a52)), closes [ai/nanoevents#44](https://github.com/ai/nanoevents/issues/44#issuecomment-602010343) [#444](https://github.com/uuidjs/uuid/issues/444)

## [8.0.0](https://github.com/uuidjs/uuid/compare/v7.0.3...v8.0.0) (2020-04-29)

### ⚠ BREAKING CHANGES

- For native ECMAScript Module (ESM) usage in Node.js only named exports are exposed, there is no more default export.

  ```diff
  -import uuid from 'uuid';
  -console.log(uuid.v4()); // -> 'cd6c3b08-0adc-4f4b-a6ef-36087a1c9869'
  +import { v4 as uuidv4 } from 'uuid';
  +uuidv4(); // ⇨ '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d'
  ```

- Deep requiring specific algorithms of this library like `require('uuid/v4')`, which has been deprecated in `uuid@7`, is no longer supported.

  Instead use the named exports that this module exports.

  For ECMAScript Modules (ESM):

  ```diff
  -import uuidv4 from 'uuid/v4';
  +import { v4 as uuidv4 } from 'uuid';
  uuidv4();
  ```

  For CommonJS:

  ```diff
  -const uuidv4 = require('uuid/v4');
  +const { v4: uuidv4 } = require('uuid');
  uuidv4();
  ```

### Features

- native Node.js ES Modules (wrapper approach) ([#423](https://github.com/uuidjs/uuid/issues/423)) ([2d9f590](https://github.com/uuidjs/uuid/commit/2d9f590ad9701d692625c07ed62f0a0f91227991)), closes [#245](https://github.com/uuidjs/uuid/issues/245) [#419](https://github.com/uuidjs/uuid/issues/419) [#342](https://github.com/uuidjs/uuid/issues/342)
- remove deep requires ([#426](https://github.com/uuidjs/uuid/issues/426)) ([daf72b8](https://github.com/uuidjs/uuid/commit/daf72b84ceb20272a81bb5fbddb05dd95922cbba))

### Bug Fixes

- add CommonJS syntax example to README quickstart section ([#417](https://github.com/uuidjs/uuid/issues/417)) ([e0ec840](https://github.com/uuidjs/uuid/commit/e0ec8402c7ad44b7ef0453036c612f5db513fda0))

### [7.0.3](https://github.com/uuidjs/uuid/compare/v7.0.2...v7.0.3) (2020-03-31)

### Bug Fixes

- make deep require deprecation warning work in browsers ([#409](https://github.com/uuidjs/uuid/issues/409)) ([4b71107](https://github.com/uuidjs/uuid/commit/4b71107d8c0d2ef56861ede6403fc9dc35a1e6bf)), closes [#408](https://github.com/uuidjs/uuid/issues/408)

### [7.0.2](https://github.com/uuidjs/uuid/compare/v7.0.1...v7.0.2) (2020-03-04)

### Bug Fixes

- make access to msCrypto consistent ([#393](https://github.com/uuidjs/uuid/issues/393)) ([8bf2a20](https://github.com/uuidjs/uuid/commit/8bf2a20f3565df743da7215eebdbada9d2df118c))
- simplify link in deprecation warning ([#391](https://github.com/uuidjs/uuid/issues/391)) ([bb2c8e4](https://github.com/uuidjs/uuid/commit/bb2c8e4e9f4c5f9c1eaaf3ea59710c633cd90cb7))
- update links to match content in readme ([#386](https://github.com/uuidjs/uuid/issues/386)) ([44f2f86](https://github.com/uuidjs/uuid/commit/44f2f86e9d2bbf14ee5f0f00f72a3db1292666d4))

### [7.0.1](https://github.com/uuidjs/uuid/compare/v7.0.0...v7.0.1) (2020-02-25)

### Bug Fixes

- clean up esm builds for node and browser ([#383](https://github.com/uuidjs/uuid/issues/383)) ([59e6a49](https://github.com/uuidjs/uuid/commit/59e6a49e7ce7b3e8fb0f3ee52b9daae72af467dc))
- provide browser versions independent from module system ([#380](https://github.com/uuidjs/uuid/issues/380)) ([4344a22](https://github.com/uuidjs/uuid/commit/4344a22e7aed33be8627eeaaf05360f256a21753)), closes [#378](https://github.com/uuidjs/uuid/issues/378)

## [7.0.0](https://github.com/uuidjs/uuid/compare/v3.4.0...v7.0.0) (2020-02-24)

### ⚠ BREAKING CHANGES

- The default export, which used to be the v4() method but which was already discouraged in v3.x of this library, has been removed.
- Explicitly note that deep imports of the different uuid version functions are deprecated and no longer encouraged and that ECMAScript module named imports should be used instead. Emit a deprecation warning for people who deep-require the different algorithm variants.
- Remove builtin support for insecure random number generators in the browser. Users who want that will have to supply their own random number generator function.
- Remove support for generating v3 and v5 UUIDs in Node.js<4.x
- Convert code base to ECMAScript Modules (ESM) and release CommonJS build for node and ESM build for browser bundlers.

### Features

- add UMD build to npm package ([#357](https://github.com/uuidjs/uuid/issues/357)) ([4e75adf](https://github.com/uuidjs/uuid/commit/4e75adf435196f28e3fbbe0185d654b5ded7ca2c)), closes [#345](https://github.com/uuidjs/uuid/issues/345)
- add various es module and CommonJS examples ([b238510](https://github.com/uuidjs/uuid/commit/b238510bf352463521f74bab175a3af9b7a42555))
- ensure that docs are up-to-date in CI ([ee5e77d](https://github.com/uuidjs/uuid/commit/ee5e77db547474f5a8f23d6c857a6d399209986b))
- hybrid CommonJS & ECMAScript modules build ([a3f078f](https://github.com/uuidjs/uuid/commit/a3f078faa0baff69ab41aed08e041f8f9c8993d0))
- remove insecure fallback random number generator ([3a5842b](https://github.com/uuidjs/uuid/commit/3a5842b141a6e5de0ae338f391661e6b84b167c9)), closes [#173](https://github.com/uuidjs/uuid/issues/173)
- remove support for pre Node.js v4 Buffer API ([#356](https://github.com/uuidjs/uuid/issues/356)) ([b59b5c5](https://github.com/uuidjs/uuid/commit/b59b5c5ecad271c5453f1a156f011671f6d35627))
- rename repository to github:uuidjs/uuid ([#351](https://github.com/uuidjs/uuid/issues/351)) ([c37a518](https://github.com/uuidjs/uuid/commit/c37a518e367ac4b6d0aa62dba1bc6ce9e85020f7)), closes [#338](https://github.com/uuidjs/uuid/issues/338)

### Bug Fixes

- add deep-require proxies for local testing and adjust tests ([#365](https://github.com/uuidjs/uuid/issues/365)) ([7fedc79](https://github.com/uuidjs/uuid/commit/7fedc79ac8fda4bfd1c566c7f05ef4ac13b2db48))
- add note about removal of default export ([#372](https://github.com/uuidjs/uuid/issues/372)) ([12749b7](https://github.com/uuidjs/uuid/commit/12749b700eb49db8a9759fd306d8be05dbfbd58c)), closes [#370](https://github.com/uuidjs/uuid/issues/370)
- deprecated deep requiring of the different algorithm versions ([#361](https://github.com/uuidjs/uuid/issues/361)) ([c0bdf15](https://github.com/uuidjs/uuid/commit/c0bdf15e417639b1aeb0b247b2fb11f7a0a26b23))

## [3.4.0](https://github.com/uuidjs/uuid/compare/v3.3.3...v3.4.0) (2020-01-16)

### Features

- rename repository to github:uuidjs/uuid ([#351](https://github.com/uuidjs/uuid/issues/351)) ([e2d7314](https://github.com/uuidjs/uuid/commit/e2d7314)), closes [#338](https://github.com/uuidjs/uuid/issues/338)

## [3.3.3](https://github.com/uuidjs/uuid/compare/v3.3.2...v3.3.3) (2019-08-19)

### Bug Fixes

- no longer run ci tests on node v4
- upgrade dependencies

## [3.3.2](https://github.com/uuidjs/uuid/compare/v3.3.1...v3.3.2) (2018-06-28)

### Bug Fixes

- typo ([305d877](https://github.com/uuidjs/uuid/commit/305d877))

## [3.3.1](https://github.com/uuidjs/uuid/compare/v3.3.0...v3.3.1) (2018-06-28)

### Bug Fixes

- fix [#284](https://github.com/uuidjs/uuid/issues/284) by setting function name in try-catch ([f2a60f2](https://github.com/uuidjs/uuid/commit/f2a60f2))

# [3.3.0](https://github.com/uuidjs/uuid/compare/v3.2.1...v3.3.0) (2018-06-22)

### Bug Fixes

- assignment to readonly property to allow running in strict mode ([#270](https://github.com/uuidjs/uuid/issues/270)) ([d062fdc](https://github.com/uuidjs/uuid/commit/d062fdc))
- fix [#229](https://github.com/uuidjs/uuid/issues/229) ([c9684d4](https://github.com/uuidjs/uuid/commit/c9684d4))
- Get correct version of IE11 crypto ([#274](https://github.com/uuidjs/uuid/issues/274)) ([153d331](https://github.com/uuidjs/uuid/commit/153d331))
- mem issue when generating uuid ([#267](https://github.com/uuidjs/uuid/issues/267)) ([c47702c](https://github.com/uuidjs/uuid/commit/c47702c))

### Features

- enforce Conventional Commit style commit messages ([#282](https://github.com/uuidjs/uuid/issues/282)) ([cc9a182](https://github.com/uuidjs/uuid/commit/cc9a182))

## [3.2.1](https://github.com/uuidjs/uuid/compare/v3.2.0...v3.2.1) (2018-01-16)

### Bug Fixes

- use msCrypto if available. Fixes [#241](https://github.com/uuidjs/uuid/issues/241) ([#247](https://github.com/uuidjs/uuid/issues/247)) ([1fef18b](https://github.com/uuidjs/uuid/commit/1fef18b))

# [3.2.0](https://github.com/uuidjs/uuid/compare/v3.1.0...v3.2.0) (2018-01-16)

### Bug Fixes

- remove mistakenly added typescript dependency, rollback version (standard-version will auto-increment) ([09fa824](https://github.com/uuidjs/uuid/commit/09fa824))
- use msCrypto if available. Fixes [#241](https://github.com/uuidjs/uuid/issues/241) ([#247](https://github.com/uuidjs/uuid/issues/247)) ([1fef18b](https://github.com/uuidjs/uuid/commit/1fef18b))

### Features

- Add v3 Support ([#217](https://github.com/uuidjs/uuid/issues/217)) ([d94f726](https://github.com/uuidjs/uuid/commit/d94f726))

# [3.1.0](https://github.com/uuidjs/uuid/compare/v3.1.0...v3.0.1) (2017-06-17)

### Bug Fixes

- (fix) Add .npmignore file to exclude test/ and other non-essential files from packing. (#183)
- Fix typo (#178)
- Simple typo fix (#165)

### Features

- v5 support in CLI (#197)
- V5 support (#188)

# 3.0.1 (2016-11-28)

- split uuid versions into separate files

# 3.0.0 (2016-11-17)

- remove .parse and .unparse

# 2.0.0

- Removed uuid.BufferClass

# 1.4.0

- Improved module context detection
- Removed public RNG functions

# 1.3.2

- Improve tests and handling of v1() options (Issue #24)
- Expose RNG option to allow for perf testing with different generators

# 1.3.0

- Support for version 1 ids, thanks to [@ctavan](https://github.com/ctavan)!
- Support for node.js crypto API
- De-emphasizing performance in favor of a) cryptographic quality PRNGs where available and b) more manageable code


---

# Contributing

Please feel free to file GitHub Issues or propose Pull Requests. We're always happy to discuss improvements to this library!

## Testing

```shell
npm test
```

## Releasing

Releases are supposed to be done from master, version bumping is automated through [`standard-version`](https://github.com/conventional-changelog/standard-version):

```shell
npm run release -- --dry-run  # verify output manually
npm run release               # follow the instructions from the output of this command
```


---

The MIT License (MIT)

Copyright (c) 2010-2020 Robert Kieffer and other contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


---

<!--
  -- This file is auto-generated from README_js.md. Changes should be made there.
  -->

# uuid [![CI](https://github.com/uuidjs/uuid/workflows/CI/badge.svg)](https://github.com/uuidjs/uuid/actions?query=workflow%3ACI) [![Browser](https://github.com/uuidjs/uuid/workflows/Browser/badge.svg)](https://github.com/uuidjs/uuid/actions?query=workflow%3ABrowser)

For the creation of [RFC4122](http://www.ietf.org/rfc/rfc4122.txt) UUIDs

- **Complete** - Support for RFC4122 version 1, 3, 4, and 5 UUIDs
- **Cross-platform** - Support for ...
  - CommonJS, [ECMAScript Modules](#ecmascript-modules) and [CDN builds](#cdn-builds)
  - Node 8, 10, 12, 14
  - Chrome, Safari, Firefox, Edge, IE 11 browsers
  - Webpack and rollup.js module bundlers
  - [React Native / Expo](#react-native--expo)
- **Secure** - Cryptographically-strong random values
- **Small** - Zero-dependency, small footprint, plays nice with "tree shaking" packagers
- **CLI** - Includes the [`uuid` command line](#command-line) utility

**Upgrading from `uuid@3.x`?** Your code is probably okay, but check out [Upgrading From `uuid@3.x`](#upgrading-from-uuid3x) for details.

## Quickstart

To create a random UUID...

**1. Install**

```shell
npm install uuid
```

**2. Create a UUID** (ES6 module syntax)

```javascript
import { v4 as uuidv4 } from 'uuid';
uuidv4(); // ⇨ '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d'
```

... or using CommonJS syntax:

```javascript
const { v4: uuidv4 } = require('uuid');
uuidv4(); // ⇨ '1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed'
```

For timestamp UUIDs, namespace UUIDs, and other options read on ...

## API Summary

|  |  |  |
| --- | --- | --- |
| [`uuid.NIL`](#uuidnil) | The nil UUID string (all zeros) | New in `uuid@8.3` |
| [`uuid.parse()`](#uuidparsestr) | Convert UUID string to array of bytes | New in `uuid@8.3` |
| [`uuid.stringify()`](#uuidstringifyarr-offset) | Convert array of bytes to UUID string | New in `uuid@8.3` |
| [`uuid.v1()`](#uuidv1options-buffer-offset) | Create a version 1 (timestamp) UUID |  |
| [`uuid.v3()`](#uuidv3name-namespace-buffer-offset) | Create a version 3 (namespace w/ MD5) UUID |  |
| [`uuid.v4()`](#uuidv4options-buffer-offset) | Create a version 4 (random) UUID |  |
| [`uuid.v5()`](#uuidv5name-namespace-buffer-offset) | Create a version 5 (namespace w/ SHA-1) UUID |  |
| [`uuid.validate()`](#uuidvalidatestr) | Test a string to see if it is a valid UUID | New in `uuid@8.3` |
| [`uuid.version()`](#uuidversionstr) | Detect RFC version of a UUID | New in `uuid@8.3` |

## API

### uuid.NIL

The nil UUID string (all zeros).

Example:

```javascript
import { NIL as NIL_UUID } from 'uuid';

NIL_UUID; // ⇨ '00000000-0000-0000-0000-000000000000'
```

### uuid.parse(str)

Convert UUID string to array of bytes

|           |                                          |
| --------- | ---------------------------------------- |
| `str`     | A valid UUID `String`                    |
| _returns_ | `Uint8Array[16]`                         |
| _throws_  | `TypeError` if `str` is not a valid UUID |

Note: Ordering of values in the byte arrays used by `parse()` and `stringify()` follows the left &Rarr; right order of hex-pairs in UUID strings. As shown in the example below.

Example:

```javascript
import { parse as uuidParse } from 'uuid';

// Parse a UUID
const bytes = uuidParse('6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b');

// Convert to hex strings to show byte order (for documentation purposes)
[...bytes].map((v) => v.toString(16).padStart(2, '0')); // ⇨ 
  // [
  //   '6e', 'c0', 'bd', '7f',
  //   '11', 'c0', '43', 'da',
  //   '97', '5e', '2a', '8a',
  //   'd9', 'eb', 'ae', '0b'
  // ]
```

### uuid.stringify(arr[, offset])

Convert array of bytes to UUID string

|                |                                                                              |
| -------------- | ---------------------------------------------------------------------------- |
| `arr`          | `Array`-like collection of 16 values (starting from `offset`) between 0-255. |
| [`offset` = 0] | `Number` Starting index in the Array                                         |
| _returns_      | `String`                                                                     |
| _throws_       | `TypeError` if a valid UUID string cannot be generated                       |

Note: Ordering of values in the byte arrays used by `parse()` and `stringify()` follows the left &Rarr; right order of hex-pairs in UUID strings. As shown in the example below.

Example:

```javascript
import { stringify as uuidStringify } from 'uuid';

const uuidBytes = [
  0x6e,
  0xc0,
  0xbd,
  0x7f,
  0x11,
  0xc0,
  0x43,
  0xda,
  0x97,
  0x5e,
  0x2a,
  0x8a,
  0xd9,
  0xeb,
  0xae,
  0x0b,
];

uuidStringify(uuidBytes); // ⇨ '6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b'
```

### uuid.v1([options[, buffer[, offset]]])

Create an RFC version 1 (timestamp) UUID

|  |  |
| --- | --- |
| [`options`] | `Object` with one or more of the following properties: |
| [`options.node` ] | RFC "node" field as an `Array[6]` of byte values (per 4.1.6) |
| [`options.clockseq`] | RFC "clock sequence" as a `Number` between 0 - 0x3fff |
| [`options.msecs`] | RFC "timestamp" field (`Number` of milliseconds, unix epoch) |
| [`options.nsecs`] | RFC "timestamp" field (`Number` of nanseconds to add to `msecs`, should be 0-10,000) |
| [`options.random`] | `Array` of 16 random bytes (0-255) |
| [`options.rng`] | Alternative to `options.random`, a `Function` that returns an `Array` of 16 random bytes (0-255) |
| [`buffer`] | `Array \| Buffer` If specified, uuid will be written here in byte-form, starting at `offset` |
| [`offset` = 0] | `Number` Index to start writing UUID bytes in `buffer` |
| _returns_ | UUID `String` if no `buffer` is specified, otherwise returns `buffer` |
| _throws_ | `Error` if more than 10M UUIDs/sec are requested |

Note: The default [node id](https://tools.ietf.org/html/rfc4122#section-4.1.6) (the last 12 digits in the UUID) is generated once, randomly, on process startup, and then remains unchanged for the duration of the process.

Note: `options.random` and `options.rng` are only meaningful on the very first call to `v1()`, where they may be passed to initialize the internal `node` and `clockseq` fields.

Example:

```javascript
import { v1 as uuidv1 } from 'uuid';

uuidv1(); // ⇨ '2c5ea4c0-4067-11e9-8bad-9b1deb4d3b7d'
```

Example using `options`:

```javascript
import { v1 as uuidv1 } from 'uuid';

const v1options = {
  node: [0x01, 0x23, 0x45, 0x67, 0x89, 0xab],
  clockseq: 0x1234,
  msecs: new Date('2011-11-01').getTime(),
  nsecs: 5678,
};
uuidv1(v1options); // ⇨ '710b962e-041c-11e1-9234-0123456789ab'
```

### uuid.v3(name, namespace[, buffer[, offset]])

Create an RFC version 3 (namespace w/ MD5) UUID

API is identical to `v5()`, but uses "v3" instead.

&#x26a0;&#xfe0f; Note: Per the RFC, "_If backward compatibility is not an issue, SHA-1 [Version 5] is preferred_."

### uuid.v4([options[, buffer[, offset]]])

Create an RFC version 4 (random) UUID

|  |  |
| --- | --- |
| [`options`] | `Object` with one or more of the following properties: |
| [`options.random`] | `Array` of 16 random bytes (0-255) |
| [`options.rng`] | Alternative to `options.random`, a `Function` that returns an `Array` of 16 random bytes (0-255) |
| [`buffer`] | `Array \| Buffer` If specified, uuid will be written here in byte-form, starting at `offset` |
| [`offset` = 0] | `Number` Index to start writing UUID bytes in `buffer` |
| _returns_ | UUID `String` if no `buffer` is specified, otherwise returns `buffer` |

Example:

```javascript
import { v4 as uuidv4 } from 'uuid';

uuidv4(); // ⇨ '1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed'
```

Example using predefined `random` values:

```javascript
import { v4 as uuidv4 } from 'uuid';

const v4options = {
  random: [
    0x10,
    0x91,
    0x56,
    0xbe,
    0xc4,
    0xfb,
    0xc1,
    0xea,
    0x71,
    0xb4,
    0xef,
    0xe1,
    0x67,
    0x1c,
    0x58,
    0x36,
  ],
};
uuidv4(v4options); // ⇨ '109156be-c4fb-41ea-b1b4-efe1671c5836'
```

### uuid.v5(name, namespace[, buffer[, offset]])

Create an RFC version 5 (namespace w/ SHA-1) UUID

|  |  |
| --- | --- |
| `name` | `String \| Array` |
| `namespace` | `String \| Array[16]` Namespace UUID |
| [`buffer`] | `Array \| Buffer` If specified, uuid will be written here in byte-form, starting at `offset` |
| [`offset` = 0] | `Number` Index to start writing UUID bytes in `buffer` |
| _returns_ | UUID `String` if no `buffer` is specified, otherwise returns `buffer` |

Note: The RFC `DNS` and `URL` namespaces are available as `v5.DNS` and `v5.URL`.

Example with custom namespace:

```javascript
import { v5 as uuidv5 } from 'uuid';

// Define a custom namespace.  Readers, create your own using something like
// https://www.uuidgenerator.net/
const MY_NAMESPACE = '1b671a64-40d5-491e-99b0-da01ff1f3341';

uuidv5('Hello, World!', MY_NAMESPACE); // ⇨ '630eb68f-e0fa-5ecc-887a-7c7a62614681'
```

Example with RFC `URL` namespace:

```javascript
import { v5 as uuidv5 } from 'uuid';

uuidv5('https://www.w3.org/', uuidv5.URL); // ⇨ 'c106a26a-21bb-5538-8bf2-57095d1976c1'
```

### uuid.validate(str)

Test a string to see if it is a valid UUID

|           |                                                     |
| --------- | --------------------------------------------------- |
| `str`     | `String` to validate                                |
| _returns_ | `true` if string is a valid UUID, `false` otherwise |

Example:

```javascript
import { validate as uuidValidate } from 'uuid';

uuidValidate('not a UUID'); // ⇨ false
uuidValidate('6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b'); // ⇨ true
```

Using `validate` and `version` together it is possible to do per-version validation, e.g. validate for only v4 UUIds.

```javascript
import { version as uuidVersion } from 'uuid';
import { validate as uuidValidate } from 'uuid';

function uuidValidateV4(uuid) {
  return uuidValidate(uuid) && uuidVersion(uuid) === 4;
}

const v1Uuid = 'd9428888-122b-11e1-b85c-61cd3cbb3210';
const v4Uuid = '109156be-c4fb-41ea-b1b4-efe1671c5836';

uuidValidateV4(v4Uuid); // ⇨ true
uuidValidateV4(v1Uuid); // ⇨ false
```

### uuid.version(str)

Detect RFC version of a UUID

|           |                                          |
| --------- | ---------------------------------------- |
| `str`     | A valid UUID `String`                    |
| _returns_ | `Number` The RFC version of the UUID     |
| _throws_  | `TypeError` if `str` is not a valid UUID |

Example:

```javascript
import { version as uuidVersion } from 'uuid';

uuidVersion('45637ec4-c85f-11ea-87d0-0242ac130003'); // ⇨ 1
uuidVersion('6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b'); // ⇨ 4
```

## Command Line

UUIDs can be generated from the command line using `uuid`.

```shell
$ uuid
ddeb27fb-d9a0-4624-be4d-4615062daed4
```

The default is to generate version 4 UUIDS, however the other versions are supported. Type `uuid --help` for details:

```shell
$ uuid --help

Usage:
  uuid
  uuid v1
  uuid v3 <name> <namespace uuid>
  uuid v4
  uuid v5 <name> <namespace uuid>
  uuid --help

Note: <namespace uuid> may be "URL" or "DNS" to use the corresponding UUIDs
defined by RFC4122
```

## ECMAScript Modules

This library comes with [ECMAScript Modules](https://www.ecma-international.org/ecma-262/6.0/#sec-modules) (ESM) support for Node.js versions that support it ([example](./examples/node-esmodules/)) as well as bundlers like [rollup.js](https://rollupjs.org/guide/en/#tree-shaking) ([example](./examples/browser-rollup/)) and [webpack](https://webpack.js.org/guides/tree-shaking/) ([example](./examples/browser-webpack/)) (targeting both, Node.js and browser environments).

```javascript
import { v4 as uuidv4 } from 'uuid';
uuidv4(); // ⇨ '1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed'
```

To run the examples you must first create a dist build of this library in the module root:

```shell
npm run build
```

## CDN Builds

### ECMAScript Modules

To load this module directly into modern browsers that [support loading ECMAScript Modules](https://caniuse.com/#feat=es6-module) you can make use of [jspm](https://jspm.org/):

```html
<script type="module">
  import { v4 as uuidv4 } from 'https://jspm.dev/uuid';
  console.log(uuidv4()); // ⇨ '1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed'
</script>
```

### UMD

To load this module directly into older browsers you can use the [UMD (Universal Module Definition)](https://github.com/umdjs/umd) builds from any of the following CDNs:

**Using [UNPKG](https://unpkg.com/uuid@latest/dist/umd/)**:

```html
<script src="https://unpkg.com/uuid@latest/dist/umd/uuidv4.min.js"></script>
```

**Using [jsDelivr](https://cdn.jsdelivr.net/npm/uuid@latest/dist/umd/)**:

```html
<script src="https://cdn.jsdelivr.net/npm/uuid@latest/dist/umd/uuidv4.min.js"></script>
```

**Using [cdnjs](https://cdnjs.com/libraries/uuid)**:

```html
<script src="https://cdnjs.cloudflare.com/ajax/libs/uuid/8.1.0/uuidv4.min.js"></script>
```

These CDNs all provide the same [`uuidv4()`](#uuidv4options-buffer-offset) method:

```html
<script>
  uuidv4(); // ⇨ '55af1e37-0734-46d8-b070-a1e42e4fc392'
</script>
```

Methods for the other algorithms ([`uuidv1()`](#uuidv1options-buffer-offset), [`uuidv3()`](#uuidv3name-namespace-buffer-offset) and [`uuidv5()`](#uuidv5name-namespace-buffer-offset)) are available from the files `uuidv1.min.js`, `uuidv3.min.js` and `uuidv5.min.js` respectively.

## "getRandomValues() not supported"

This error occurs in environments where the standard [`crypto.getRandomValues()`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues) API is not supported. This issue can be resolved by adding an appropriate polyfill:

### React Native / Expo

1. Install [`react-native-get-random-values`](https://github.com/LinusU/react-native-get-random-values#readme)
1. Import it _before_ `uuid`. Since `uuid` might also appear as a transitive dependency of some other imports it's safest to just import `react-native-get-random-values` as the very first thing in your entry point:

```javascript
import 'react-native-get-random-values';
import { v4 as uuidv4 } from 'uuid';
```

Note: If you are using Expo, you must be using at least `react-native-get-random-values@1.5.0` and `expo@39.0.0`.

### Web Workers / Service Workers (Edge <= 18)

[In Edge <= 18, Web Crypto is not supported in Web Workers or Service Workers](https://caniuse.com/#feat=cryptography) and we are not aware of a polyfill (let us know if you find one, please).

## Upgrading From `uuid@7.x`

### Only Named Exports Supported When Using with Node.js ESM

`uuid@7.x` did not come with native ECMAScript Module (ESM) support for Node.js. Importing it in Node.js ESM consequently imported the CommonJS source with a default export. This library now comes with true Node.js ESM support and only provides named exports.

Instead of doing:

```javascript
import uuid from 'uuid';
uuid.v4();
```

you will now have to use the named exports:

```javascript
import { v4 as uuidv4 } from 'uuid';
uuidv4();
```

### Deep Requires No Longer Supported

Deep requires like `require('uuid/v4')` [which have been deprecated in `uuid@7.x`](#deep-requires-now-deprecated) are no longer supported.

## Upgrading From `uuid@3.x`

"_Wait... what happened to `uuid@4.x` - `uuid@6.x`?!?_"

In order to avoid confusion with RFC [version 4](#uuidv4options-buffer-offset) and [version 5](#uuidv5name-namespace-buffer-offset) UUIDs, and a possible [version 6](http://gh.peabody.io/uuidv6/), releases 4 thru 6 of this module have been skipped.

### Deep Requires Now Deprecated

`uuid@3.x` encouraged the use of deep requires to minimize the bundle size of browser builds:

```javascript
const uuidv4 = require('uuid/v4'); // <== NOW DEPRECATED!
uuidv4();
```

As of `uuid@7.x` this library now provides ECMAScript modules builds, which allow packagers like Webpack and Rollup to do "tree-shaking" to remove dead code. Instead, use the `import` syntax:

```javascript
import { v4 as uuidv4 } from 'uuid';
uuidv4();
```

... or for CommonJS:

```javascript
const { v4: uuidv4 } = require('uuid');
uuidv4();
```

### Default Export Removed

`uuid@3.x` was exporting the Version 4 UUID method as a default export:

```javascript
const uuid = require('uuid'); // <== REMOVED!
```

This usage pattern was already discouraged in `uuid@3.x` and has been removed in `uuid@7.x`.

----
Markdown generated from [README_js.md](README_js.md) by [![RunMD Logo](http://i.imgur.com/h0FVyzU.png)](https://github.com/broofa/runmd)

---

# value-equal [![Travis][build-badge]][build] [![npm package][npm-badge]][npm]

[build-badge]: https://img.shields.io/travis/mjackson/value-equal/master.svg?style=flat-square
[build]: https://travis-ci.org/mjackson/value-equal
[npm-badge]: https://img.shields.io/npm/v/value-equal.svg?style=flat-square
[npm]: https://www.npmjs.org/package/value-equal

[`value-equal`](https://www.npmjs.com/package/value-equal) determines if two JavaScript values are equal using [`Object.prototype.valueOf`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/valueOf).

In many instances when I'm checking for object equality, what I really want to know is if their **values** are equal. This is good for:

- Stuff you keep in `localStorage`
- `window.history.state` values
- Query strings

## Installation

Using [npm](https://www.npmjs.com/):

    $ npm install --save value-equal

Then with a module bundler like [webpack](https://webpack.github.io/), use as you would anything else:

```js
// using ES6 modules
import valueEqual from 'value-equal';

// using CommonJS modules
var valueEqual = require('value-equal');
```

The UMD build is also available on [unpkg](https://unpkg.com):

```html
<script src="https://unpkg.com/value-equal"></script>
```

You can find the library on `window.valueEqual`.

## Usage

```js
valueEqual(1, 1); // true
valueEqual('asdf', 'asdf'); // true
valueEqual('asdf', new String('asdf')); // true
valueEqual(true, true); // true
valueEqual(true, false); // false
valueEqual({ a: 'a' }, { a: 'a' }); // true
valueEqual({ a: 'a' }, { a: 'b' }); // false
valueEqual([1, 2, 3], [1, 2, 3]); // true
valueEqual([1, 2, 3], [2, 3, 4]); // false
```

That's it. Enjoy!


---

1.1.2 / 2017-09-23
==================

  * perf: improve header token parsing speed

1.1.1 / 2017-03-20
==================

  * perf: hoist regular expression

1.1.0 / 2015-09-29
==================

  * Only accept valid field names in the `field` argument
    - Ensures the resulting string is a valid HTTP header value

1.0.1 / 2015-07-08
==================

  * Fix setting empty header from empty `field`
  * perf: enable strict mode
  * perf: remove argument reassignments

1.0.0 / 2014-08-10
==================

  * Accept valid `Vary` header string as `field`
  * Add `vary.append` for low-level string manipulation
  * Move to `jshttp` orgainzation

0.1.0 / 2014-06-05
==================

  * Support array of fields to set

0.0.0 / 2014-06-04
==================

  * Initial release


---

# vary

[![NPM Version][npm-image]][npm-url]
[![NPM Downloads][downloads-image]][downloads-url]
[![Node.js Version][node-version-image]][node-version-url]
[![Build Status][travis-image]][travis-url]
[![Test Coverage][coveralls-image]][coveralls-url]

Manipulate the HTTP Vary header

## Installation

This is a [Node.js](https://nodejs.org/en/) module available through the
[npm registry](https://www.npmjs.com/). Installation is done using the
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally): 

```sh
$ npm install vary
```

## API

<!-- eslint-disable no-unused-vars -->

```js
var vary = require('vary')
```

### vary(res, field)

Adds the given header `field` to the `Vary` response header of `res`.
This can be a string of a single field, a string of a valid `Vary`
header, or an array of multiple fields.

This will append the header if not already listed, otherwise leaves
it listed in the current location.

<!-- eslint-disable no-undef -->

```js
// Append "Origin" to the Vary header of the response
vary(res, 'Origin')
```

### vary.append(header, field)

Adds the given header `field` to the `Vary` response header string `header`.
This can be a string of a single field, a string of a valid `Vary` header,
or an array of multiple fields.

This will append the header if not already listed, otherwise leaves
it listed in the current location. The new header string is returned.

<!-- eslint-disable no-undef -->

```js
// Get header string appending "Origin" to "Accept, User-Agent"
vary.append('Accept, User-Agent', 'Origin')
```

## Examples

### Updating the Vary header when content is based on it

```js
var http = require('http')
var vary = require('vary')

http.createServer(function onRequest (req, res) {
  // about to user-agent sniff
  vary(res, 'User-Agent')

  var ua = req.headers['user-agent'] || ''
  var isMobile = /mobi|android|touch|mini/i.test(ua)

  // serve site, depending on isMobile
  res.setHeader('Content-Type', 'text/html')
  res.end('You are (probably) ' + (isMobile ? '' : 'not ') + 'a mobile user')
})
```

## Testing

```sh
$ npm test
```

## License

[MIT](LICENSE)

[npm-image]: https://img.shields.io/npm/v/vary.svg
[npm-url]: https://npmjs.org/package/vary
[node-version-image]: https://img.shields.io/node/v/vary.svg
[node-version-url]: https://nodejs.org/en/download
[travis-image]: https://img.shields.io/travis/jshttp/vary/master.svg
[travis-url]: https://travis-ci.org/jshttp/vary
[coveralls-image]: https://img.shields.io/coveralls/jshttp/vary/master.svg
[coveralls-url]: https://coveralls.io/r/jshttp/vary
[downloads-image]: https://img.shields.io/npm/dm/vary.svg
[downloads-url]: https://npmjs.org/package/vary


---

<h1>
  <img src="https://raw.githubusercontent.com/vfile/vfile/fc8164b/logo.svg?sanitize=true" alt="vfile" />
</h1>

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

**vfile** is a small and browser friendly virtual file format that tracks
metadata about files (such as its `path` and `value`) and lint
[messages][api-vfile-messages].

## Contents

* [unified](#unified)
* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`VFile(options?)`](#vfileoptions)
  * [`file.cwd`](#filecwd)
  * [`file.data`](#filedata)
  * [`file.history`](#filehistory)
  * [`file.messages`](#filemessages)
  * [`file.value`](#filevalue)
  * [`file.basename`](#filebasename)
  * [`file.dirname`](#filedirname)
  * [`file.extname`](#fileextname)
  * [`file.path`](#filepath)
  * [`file.stem`](#filestem)
  * [`VFile#fail(reason[, options])`](#vfilefailreason-options)
  * [`VFile#info(reason[, options])`](#vfileinforeason-options)
  * [`VFile#message(reason[, options])`](#vfilemessagereason-options)
  * [`VFile#toString(encoding?)`](#vfiletostringencoding)
  * [`Compatible`](#compatible)
  * [`Data`](#data)
  * [`DataMap`](#datamap)
  * [`Map`](#map)
  * [`MessageOptions`](#messageoptions)
  * [`Options`](#options)
  * [`Reporter`](#reporter)
  * [`ReporterSettings`](#reportersettings)
  * [`Value`](#value)
  * [Well-known](#well-known)
* [List of utilities](#list-of-utilities)
* [Reporters](#reporters)
* [Types](#types)
* [Compatibility](#compatibility)
* [Contribute](#contribute)
* [Sponsor](#sponsor)
* [Acknowledgments](#acknowledgments)
* [License](#license)

## unified

**vfile** is part of the unified collective.

* for more about us, see [`unifiedjs.com`][site]
* for how the collective is governed, see [`unifiedjs/collective`][governance]
* for updates, see [@unifiedjs][twitter] on Twitter

## What is this?

This package provides a virtual file format.
It exposes an API to access the file value, path, metadata about the file, and
specifically supports attaching lint messages and errors to certain places in
these files.

## When should I use this?

The virtual file format is useful when dealing with the concept of files in
places where you might not be able to access the file system.
The message API is particularly useful when making things that check files (as
in, linting).

vfile is made for [unified][], which amongst other things checks files.
However, vfile can be used in other projects that deal with parsing,
transforming, and serializing data, to build linters, compilers, static site
generators, and other build tools.

This is different from the excellent [`vinyl`][vinyl] in that vfile has a
smaller API, a smaller size, and focuses on messages.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install vfile
```

In Deno with [`esm.sh`][esmsh]:

```js
import {VFile} from 'https://esm.sh/vfile@6'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {VFile} from 'https://esm.sh/vfile@6?bundle'
</script>
```

## Use

```js
import {VFile} from 'vfile'

const file = new VFile({
  path: '~/example.txt',
  value: 'Alpha *braavo* charlie.'
})

console.log(file.path) // => '~/example.txt'
console.log(file.dirname) // => '~'

file.extname = '.md'

console.log(file.basename) // => 'example.md'

file.basename = 'index.text'

console.log(file.history) // => ['~/example.txt', '~/example.md', '~/index.text']

file.message('Unexpected unknown word `braavo`, did you mean `bravo`?', {
  place: {line: 1, column: 8},
  source: 'spell',
  ruleId: 'typo'
})

console.log(file.messages)
```

Yields:

```txt
[
  [~/index.text:1:8: Unexpected unknown word `braavo`, did you mean `bravo`?] {
    ancestors: undefined,
    cause: undefined,
    column: 8,
    fatal: false,
    line: 1,
    place: { line: 1, column: 8 },
    reason: 'Unexpected unknown word `braavo`, did you mean `bravo`?',
    ruleId: 'typo',
    source: 'spell',
    file: '~/index.text'
  }
]
```

## API

This package exports the identifier [`VFile`][api-vfile].
There is no default export.

### `VFile(options?)`

Create a new virtual file.

`options` is treated as:

* `string` or [`Uint8Array`][mdn-uint8-array] — `{value: options}`
* `URL` — `{path: options}`
* `VFile` — shallow copies its data over to the new file
* `object` — all fields are shallow copied over to the new file

Path related fields are set in the following order (least specific to
most specific): `history`, `path`, `basename`, `stem`, `extname`,
`dirname`.

You cannot set `dirname` or `extname` without setting either `history`,
`path`, `basename`, or `stem` too.

###### Parameters

* `options` ([`Compatible`][api-compatible], optional)
  — file value

###### Returns

New instance (`VFile`).

###### Example

```js
new VFile()
new VFile('console.log("alpha");')
new VFile(new Uint8Array([0x65, 0x78, 0x69, 0x74, 0x20, 0x31]))
new VFile({path: path.join('path', 'to', 'readme.md')})
new VFile({stem: 'readme', extname: '.md', dirname: path.join('path', 'to')})
new VFile({other: 'properties', are: 'copied', ov: {e: 'r'}})
```

### `file.cwd`

Base of `path` (`string`, default: `process.cwd()` or `'/'` in browsers).

### `file.data`

Place to store custom info (`Record<string, unknown>`, default: `{}`).

It’s OK to store custom data directly on the file but moving it to `data` is
recommended.

### `file.history`

List of file paths the file moved between (`Array<string>`).

The first is the original path and the last is the current path.

### `file.messages`

List of messages associated with the file
([`Array<VFileMessage>`][api-vfile-message]).

### `file.value`

Raw value ([`Uint8Array`][mdn-uint8-array], `string`, `undefined`).

### `file.basename`

Get or set the basename (including extname) (`string?`, example: `'index.min.js'`).

Cannot contain path separators (`'/'` on unix, macOS, and browsers, `'\'` on
windows).
Cannot be nullified (use `file.path = file.dirname` instead).

### `file.dirname`

Get or set the parent path (`string?`, example: `'~'`).

Cannot be set if there’s no `path` yet.

### `file.extname`

Get or set the extname (including dot) (`string?`, example: `'.js'`).

Cannot contain path separators (`'/'` on unix, macOS, and browsers, `'\'` on
windows).
Cannot be set if there’s no `path` yet.

### `file.path`

Get or set the full path (`string?`, example: `'~/index.min.js'`).

Cannot be nullified.
You can set a file URL (a `URL` object with a `file:` protocol) which will be
turned into a path with [`url.fileURLToPath`][file-url-to-path].

### `file.stem`

Get or set the stem (basename w/o extname) (`string?`, example: `'index.min'`).

Cannot contain path separators (`'/'` on unix, macOS, and browsers, `'\'` on
windows).
Cannot be nullified.

### `VFile#fail(reason[, options])`

Create a fatal message for `reason` associated with the file.

The `fatal` field of the message is set to `true` (error; file not usable) and
the `file` field is set to the current file path.
The message is added to the `messages` field on `file`.

> 🪦 **Note**: also has obsolete signatures.

###### Parameters

* `reason` (`string`)
  — reason for message, should use markdown
* `options` ([`MessageOptions`][api-message-options], optional)
  — configuration

###### Returns

Nothing (`never`).

###### Throws

Message ([`VFileMessage`][vmessage]).

### `VFile#info(reason[, options])`

Create an info message for `reason` associated with the file.

The `fatal` field of the message is set to `undefined` (info; change likely not
needed) and the `file` field is set to the current file path.
The message is added to the `messages` field on `file`.

> 🪦 **Note**: also has obsolete signatures.

###### Parameters

* `reason` (`string`)
  — reason for message, should use markdown
* `options` ([`MessageOptions`][api-message-options], optional)
  — configuration

###### Returns

Message ([`VFileMessage`][vmessage]).

### `VFile#message(reason[, options])`

Create a message for `reason` associated with the file.

The `fatal` field of the message is set to `false` (warning; change may be
needed) and the `file` field is set to the current file path.
The message is added to the `messages` field on `file`.

> 🪦 **Note**: also has obsolete signatures.

###### Parameters

* `reason` (`string`)
  — reason for message, should use markdown
* `options` ([`MessageOptions`][api-message-options], optional)
  — configuration

###### Returns

Message ([`VFileMessage`][vmessage]).

### `VFile#toString(encoding?)`

Serialize the file.

> **Note**: which encodings are supported depends on the engine.
> For info on Node.js, see:
> <https://nodejs.org/api/util.html#whatwg-supported-encodings>.

###### Parameters

* `encoding` (`string`, default: `'utf8'`)
  — character encoding to understand `value` as when it’s a
  [`Uint8Array`][mdn-uint8-array]

###### Returns

Serialized file (`string`).

### `Compatible`

Things that can be passed to the constructor (TypeScript type).

###### Type

```ts
type Compatible = Options | URL | VFile | Value
```

### `Data`

Custom info (TypeScript type).

Known attributes can be added to [`DataMap`][api-data-map].

###### Type

```ts
type Data = Record<string, unknown> & Partial<DataMap>
```

### `DataMap`

This map registers the type of the `data` key of a `VFile` (TypeScript type).

This type can be augmented to register custom `data` types.

###### Type

```ts
interface DataMap {}
```

###### Example

```ts
declare module 'vfile' {
  interface DataMap {
    // `file.data.name` is typed as `string`
    name: string
  }
}
```

### `Map`

Raw source map (TypeScript type).

See [`source-map`][source-map].

###### Fields

* `version` (`number`)
  — which version of the source map spec this map is following
* `sources` (`Array<string>`)
  — an array of URLs to the original source files
* `names` (`Array<string>`)
  — an array of identifiers which can be referenced by individual mappings
* `sourceRoot` (`string`, optional)
  — the URL root from which all sources are relative
* `sourcesContent` (`Array<string>`, optional)
  — an array of contents of the original source files
* `mappings` (`string`)
  — a string of base64 VLQs which contain the actual mappings
* `file` (`string`)
  — the generated file this source map is associated with

### `MessageOptions`

Options to create messages (TypeScript type).

See [`Options` in `vfile-message`][vfile-message-options].

### `Options`

An object with arbitrary fields and the following known fields (TypeScript
type).

###### Fields

* `basename` (`string`, optional)
  — set `basename` (name)
* `cwd` (`string`, optional)
  — set `cwd` (working directory)
* `data` ([`Data`][api-data], optional)
  — set `data` (associated info)
* `dirname` (`string`, optional)
  — set `dirname` (path w/o basename)
* `extname` (`string`, optional)
  — set `extname` (extension with dot)
* `history` (`Array<string>`, optional)
  — set `history` (paths the file moved between)
* `path` (`URL | string`, optional)
  — set `path` (current path)
* `stem` (`string`, optional)
  — set `stem` (name without extension)
* `value` ([`Value`][api-value], optional)
  — set `value` (the contents of the file)

### `Reporter`

Type for a reporter (TypeScript type).

###### Type

```ts
type Reporter<Settings = ReporterSettings> = (
  files: Array<VFile>,
  options: Settings
) => string
```

### `ReporterSettings`

Configuration for reporters (TypeScript type).

###### Type

```ts
type ReporterSettings = Record<string, unknown>
```

### `Value`

Contents of the file (TypeScript type).

Can either be text or a [`Uint8Array`][mdn-uint8-array] structure.

###### Type

```ts
type Value = Uint8Array | string
```

### Well-known

The following fields are considered “non-standard”, but they are allowed, and
some utilities use them:

* `map` ([`Map`][api-map])
  — source map; this type is equivalent to the `RawSourceMap` type from the
  `source-map` module
* `result` (`unknown`)
  — custom, non-string, compiled, representation; this is used by unified to
  store non-string results; one example is when turning markdown into React
  nodes
* `stored` (`boolean`)
  — whether a file was saved to disk; this is used by vfile reporters

There are also well-known fields on messages, see
[them in a similar section of
`vfile-message`](https://github.com/vfile/vfile-message#well-known).

<a name="utilities"></a>

## List of utilities

* [`convert-vinyl-to-vfile`](https://github.com/dustinspecker/convert-vinyl-to-vfile)
  — transform from [Vinyl][]
* [`to-vfile`](https://github.com/vfile/to-vfile)
  — create a file from a file path and read and write to the file system
* [`vfile-find-down`](https://github.com/vfile/vfile-find-down)
  — find files by searching the file system downwards
* [`vfile-find-up`](https://github.com/vfile/vfile-find-up)
  — find files by searching the file system upwards
* [`vfile-glob`](https://github.com/shinnn/vfile-glob)
  — find files by glob patterns
* [`vfile-is`](https://github.com/vfile/vfile-is)
  — check if a file passes a test
* [`vfile-location`](https://github.com/vfile/vfile-location)
  — convert between positional and offset locations
* [`vfile-matter`](https://github.com/vfile/vfile-matter)
  — parse the YAML front matter
* [`vfile-message`](https://github.com/vfile/vfile-message)
  — create a file message
* [`vfile-messages-to-vscode-diagnostics`](https://github.com/shinnn/vfile-messages-to-vscode-diagnostics)
  — transform file messages to VS Code diagnostics
* [`vfile-mkdirp`](https://github.com/vfile/vfile-mkdirp)
  — make sure the directory of a file exists on the file system
* [`vfile-rename`](https://github.com/vfile/vfile-rename)
  — rename the path parts of a file
* [`vfile-sort`](https://github.com/vfile/vfile-sort)
  — sort messages by line/column
* [`vfile-statistics`](https://github.com/vfile/vfile-statistics)
  — count messages per category: failures, warnings, etc
* [`vfile-to-eslint`](https://github.com/vfile/vfile-to-eslint)
  — convert to ESLint formatter compatible output

> 👉 **Note**: see [unist][] for projects that work with nodes.

## Reporters

* [`vfile-reporter`][reporter]
  — create a report
* [`vfile-reporter-json`](https://github.com/vfile/vfile-reporter-json)
  — create a JSON report
* [`vfile-reporter-folder-json`](https://github.com/vfile/vfile-reporter-folder-json)
  — create a JSON representation of vfiles
* [`vfile-reporter-pretty`](https://github.com/vfile/vfile-reporter-pretty)
  — create a pretty report
* [`vfile-reporter-junit`](https://github.com/kellyselden/vfile-reporter-junit)
  — create a jUnit report
* [`vfile-reporter-position`](https://github.com/Hocdoc/vfile-reporter-position)
  — create a report with content excerpts

> 👉 **Note**: want to make your own reporter?
> Reporters *must* accept `Array<VFile>` as their first argument, and return
> `string`.
> Reporters *may* accept other values too, in which case it’s suggested to stick
> to `vfile-reporter`s interface.

## Types

This package is fully typed with [TypeScript][].
It exports the additional types
[`Compatible`][api-compatible],
[`Data`][api-data],
[`DataMap`][api-data-map],
[`Map`][api-map],
[`MessageOptions`][api-message-options],
[`Options`][api-options],
[`Reporter`][api-reporter],
[`ReporterSettings`][api-reporter-settings], and
[`Value`][api-value].

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, `vfile@^6`,
compatible with Node.js 16.

## Contribute

See [`contributing.md`][contributing] in [`vfile/.github`][health] for ways to
get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## Sponsor

Support this effort and give back by sponsoring on [OpenCollective][collective]!

<table>
<tr valign="middle">
<td width="20%" align="center" rowspan="2" colspan="2">
  <a href="https://vercel.com">Vercel</a><br><br>
  <a href="https://vercel.com"><img src="https://avatars1.githubusercontent.com/u/14985020?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
  <a href="https://motif.land">Motif</a><br><br>
  <a href="https://motif.land"><img src="https://avatars1.githubusercontent.com/u/74457950?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
  <a href="https://www.hashicorp.com">HashiCorp</a><br><br>
  <a href="https://www.hashicorp.com"><img src="https://avatars1.githubusercontent.com/u/761456?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
  <a href="https://www.gitbook.com">GitBook</a><br><br>
  <a href="https://www.gitbook.com"><img src="https://avatars1.githubusercontent.com/u/7111340?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
  <a href="https://www.gatsbyjs.org">Gatsby</a><br><br>
  <a href="https://www.gatsbyjs.org"><img src="https://avatars1.githubusercontent.com/u/12551863?s=256&v=4" width="128"></a>
</td>
</tr>
<tr valign="middle">
</tr>
<tr valign="middle">
<td width="20%" align="center" rowspan="2" colspan="2">
  <a href="https://www.netlify.com">Netlify</a><br><br>
  <!--OC has a sharper image-->
  <a href="https://www.netlify.com"><img src="https://images.opencollective.com/netlify/4087de2/logo/256.png" width="128"></a>
</td>
<td width="10%" align="center">
  <a href="https://www.coinbase.com">Coinbase</a><br><br>
  <a href="https://www.coinbase.com"><img src="https://avatars1.githubusercontent.com/u/1885080?s=256&v=4" width="64"></a>
</td>
<td width="10%" align="center">
  <a href="https://themeisle.com">ThemeIsle</a><br><br>
  <a href="https://themeisle.com"><img src="https://avatars1.githubusercontent.com/u/58979018?s=128&v=4" width="64"></a>
</td>
<td width="10%" align="center">
  <a href="https://expo.io">Expo</a><br><br>
  <a href="https://expo.io"><img src="https://avatars1.githubusercontent.com/u/12504344?s=128&v=4" width="64"></a>
</td>
<td width="10%" align="center">
  <a href="https://boostnote.io">Boost Note</a><br><br>
  <a href="https://boostnote.io"><img src="https://images.opencollective.com/boosthub/6318083/logo/128.png" width="64"></a>
</td>
<td width="10%" align="center">
  <a href="https://markdown.space">Markdown Space</a><br><br>
  <a href="https://markdown.space"><img src="https://images.opencollective.com/markdown-space/e1038ed/logo/128.png" width="64"></a>
</td>
<td width="10%" align="center">
  <a href="https://www.holloway.com">Holloway</a><br><br>
  <a href="https://www.holloway.com"><img src="https://avatars1.githubusercontent.com/u/35904294?s=128&v=4" width="64"></a>
</td>
<td width="10%"></td>
<td width="10%"></td>
</tr>
<tr valign="middle">
<td width="100%" align="center" colspan="8">
  <br>
  <a href="https://opencollective.com/unified"><strong>You?</strong></a>
  <br><br>
</td>
</tr>
</table>

## Acknowledgments

The initial release of this project was authored by
[**@wooorm**](https://github.com/wooorm).

Thanks to [**@contra**](https://github.com/contra),
[**@phated**](https://github.com/phated), and others for their work on
[Vinyl][], which was a huge inspiration.

Thanks to
[**@brendo**](https://github.com/brendo),
[**@shinnn**](https://github.com/shinnn),
[**@KyleAMathews**](https://github.com/KyleAMathews),
[**@sindresorhus**](https://github.com/sindresorhus), and
[**@denysdovhan**](https://github.com/denysdovhan)
for contributing commits since!

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/vfile/vfile/workflows/main/badge.svg

[build]: https://github.com/vfile/vfile/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/vfile/vfile.svg

[coverage]: https://codecov.io/github/vfile/vfile

[downloads-badge]: https://img.shields.io/npm/dm/vfile.svg

[downloads]: https://www.npmjs.com/package/vfile

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=vfile

[size]: https://bundlejs.com/?q=vfile

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/vfile/vfile/discussions

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[typescript]: https://www.typescriptlang.org

[health]: https://github.com/vfile/.github

[contributing]: https://github.com/vfile/.github/blob/main/contributing.md

[support]: https://github.com/vfile/.github/blob/main/support.md

[coc]: https://github.com/vfile/.github/blob/main/code-of-conduct.md

[license]: license

[author]: https://wooorm.com

[unified]: https://github.com/unifiedjs/unified

[vinyl]: https://github.com/gulpjs/vinyl

[site]: https://unifiedjs.com

[twitter]: https://twitter.com/unifiedjs

[unist]: https://github.com/syntax-tree/unist#list-of-utilities

[reporter]: https://github.com/vfile/vfile-reporter

[vmessage]: https://github.com/vfile/vfile-message

[vfile-message-options]: https://github.com/vfile/vfile-message#options

[mdn-uint8-array]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array

[source-map]: https://github.com/mozilla/source-map/blob/58819f0/source-map.d.ts#L15-L23

[file-url-to-path]: https://nodejs.org/api/url.html#url_url_fileurltopath_url

[governance]: https://github.com/unifiedjs/collective

[api-vfile-messages]: #filemessages

[api-vfile-message]: #vfilemessagereason-options

[api-vfile]: #vfileoptions

[api-compatible]: #compatible

[api-data]: #data

[api-data-map]: #datamap

[api-map]: #map

[api-message-options]: #messageoptions

[api-options]: #options

[api-reporter]: #reporter

[api-reporter-settings]: #reportersettings

[api-value]: #value


---

# vfile-location

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[vfile][] utility to convert between positional (line and column-based) and
offsets (range-based) locations.

## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
  * [`Location`](#location)
  * [`location(file)`](#locationfile)
* [Types](#types)
* [Compatibility](#compatibility)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This is a tiny but useful package to convert between arbitrary places in a
file.

## When should I use this?

This utility is useful when ASTs nodes don’t cut it.
For example, when you are making a lint rule that looks for dangerous
characters in a file, which you accomplish by searching the raw file value,
and still want to report it to users.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install vfile-location
```

In Deno with [`esm.sh`][esmsh]:

```js
import {location} from 'https://esm.sh/vfile-location@5'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {location} from 'https://esm.sh/vfile-location@5?bundle'
</script>
```

## Use

```js
import {VFile} from 'vfile'
import {location} from 'vfile-location'

const place = location(new VFile('foo\nbar\nbaz'))

const offset = place.toOffset({line: 3, column: 3}) // => 10
place.toPoint(offset) // => {line: 3, column: 3, offset: 10}
```

## API

### `Location`

Accessors for index.

###### Fields

* `toOffset` (`(point?: PointLike | null | undefined) => number | undefined`)
  — get the `offset` from a line/column based `Point` in the bound indices;
  returns `undefined` when given out of bounds input
* `toPoint` (`(offset?: number | null | undefined) => UnistPoint | undefined`)
  — get the line/column based `Point` for `offset` in the bound indices;
  returns `undefined` when given out of bounds input

### `location(file)`

Create an index of the given document to translate between line/column and
offset based positional info.

Also implemented in Rust in [`wooorm/markdown-rs`][markdown-rs].

[markdown-rs]: https://github.com/wooorm/markdown-rs/blob/main/src/util/location.rs

###### Parameters

* `file` (`VFile | Value`)
  — file to index

###### Returns

Accessors for index (`Location`).

## Types

This package is fully typed with [TypeScript][].
It exports the additional type [`Location`][api-location-map].

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, `vfile-location@^5`,
compatible with Node.js 16.

## Contribute

See [`contributing.md`][contributing] in [`vfile/.github`][health] for ways to
get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/vfile/vfile-location/workflows/main/badge.svg

[build]: https://github.com/vfile/vfile-location/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/vfile/vfile-location.svg

[coverage]: https://codecov.io/github/vfile/vfile-location

[downloads-badge]: https://img.shields.io/npm/dm/vfile-location.svg

[downloads]: https://www.npmjs.com/package/vfile-location

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=vfile-location

[size]: https://bundlejs.com/?q=vfile-location

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/vfile/vfile/discussions

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[typescript]: https://www.typescriptlang.org

[contributing]: https://github.com/vfile/.github/blob/main/contributing.md

[support]: https://github.com/vfile/.github/blob/main/support.md

[health]: https://github.com/vfile/.github

[coc]: https://github.com/vfile/.github/blob/main/code-of-conduct.md

[license]: license

[author]: https://wooorm.com

[vfile]: https://github.com/vfile/vfile

[api-location-map]: #location


---

# vfile-message

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

Create [vfile][] messages.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`VFileMessage(reason[, options])`](#vfilemessagereason-options)
    *   [`Options`](#options)
    *   [Well-known](#well-known)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package provides a (lint) message format.

## When should I use this?

In most cases, you can use `file.message` from `VFile` itself, but in some
cases you might not have a file, and still want to emit warnings or errors,
in which case this can be used directly.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install vfile-message
```

In Deno with [`esm.sh`][esmsh]:

```js
import {VFileMessage} from 'https://esm.sh/vfile-message@4'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {VFileMessage} from 'https://esm.sh/vfile-message@4?bundle'
</script>
```

## Use

```js
import {VFileMessage} from 'vfile-message'

const message = new VFileMessage(
  'Unexpected unknown word `braavo`, did you mean `bravo`?',
  {source: 'spell', ruleId: 'typo', place: {line: 1, column: 8}}
)

console.log(message)
```

Yields:

```txt
[1:8: Unexpected unknown word `braavo`, did you mean `bravo`?] {
  reason: 'Unexpected unknown word `braavo`, did you mean `bravo`?',
  line: 1,
  column: 8,
  ancestors: undefined,
  cause: undefined,
  fatal: undefined,
  place: {line: 1, column: 8},
  ruleId: 'typo',
  source: 'spell'
}
```

## API

This package exports the identifier [`VFileMessage`][api-vfile-message].
There is no default export.

### `VFileMessage(reason[, options])`

Create a message for `reason`.

> 🪦 **Note**: also has obsolete signatures.

###### Parameters

*   `reason` (`string`)
    — reason for message (should use markdown)
*   `options` ([`Options`][api-options], optional)
    — configuration.

###### Extends

[`Error`][mdn-error].

###### Returns

Instance of `VFileMessage`.

###### Fields

*   `ancestors` ([`Array<Node>`][unist-node] or `undefined`)
    — stack of (inclusive) ancestor nodes surrounding the message
*   `cause` ([`Error`][mdn-error] or `undefined`)
    — original error cause of the message
*   `column` (`number` or `undefined`)
    — starting column of message
*   `fatal` (`boolean` or `undefined`)
    — state of problem; `true`: error, file not usable; `false`: warning,
    change may be needed; `undefined`: info, change likely not needed
*   `line` (`number` or `undefined`)
    — starting line of message
*   `place` ([`Point`][unist-point], [`Position`][unist-position] or `undefined`)
    — place of message
*   `reason` (`string`)
    — reason for message (should use markdown)
*   `ruleId` (`string` or `undefined`, example: `'my-rule'`)
    — category of message
*   `source` (`string` or `undefined`, example: `'my-package'`)
    — namespace of message

### `Options`

Configuration (TypeScript type).

###### Fields

*   `ancestors` ([`Array<Node>`][unist-node], optional)
    — stack of (inclusive) ancestor nodes surrounding the message
*   `cause` ([`Error`][mdn-error], optional)
    — original error cause of the message
*   `place` ([`Point`][unist-point] or [`Position`][unist-position], optional)
    — place of message
*   `ruleId` (`string`, optional, example: `'my-rule'`)
    — category of message
*   `source` (`string`, optional, , example: `'my-package'`)
    — namespace of who sent the message

### Well-known

It’s OK to store custom data directly on the `VFileMessage`, some of those are
handled by [utilities][util].
The following fields are documented and typed here.

###### Fields

*   `actual` (`string`, optional)
    — specify the source value that’s being reported, which is deemed incorrect
*   `expected` (`Array<string>`, optional)
    — suggest acceptable values that can be used instead of `actual`
*   `url` (`string`, optional)
    — link to docs for the message (this must be an absolute URL that can be
    passed as `x` to `new URL(x)`)
*   `note` (`string`, optional)
    — long form description of the message (you should use markdown)

## Types

This package is fully typed with [TypeScript][].
It exports the additional type [`Options`][api-options].

## Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, `vfile-message@^4`,
compatible with Node.js 16.

## Contribute

See [`contributing.md`][contributing] in [`vfile/.github`][health] for ways to
get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/vfile/vfile-message/workflows/main/badge.svg

[build]: https://github.com/vfile/vfile-message/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/vfile/vfile-message.svg

[coverage]: https://codecov.io/github/vfile/vfile-message

[downloads-badge]: https://img.shields.io/npm/dm/vfile-message.svg

[downloads]: https://www.npmjs.com/package/vfile-message

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=vfile-message

[size]: https://bundlejs.com/?q=vfile-message

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/vfile/vfile/discussions

[npm]: https://docs.npmjs.com/cli/install

[contributing]: https://github.com/vfile/.github/blob/main/contributing.md

[support]: https://github.com/vfile/.github/blob/main/support.md

[health]: https://github.com/vfile/.github

[coc]: https://github.com/vfile/.github/blob/main/code-of-conduct.md

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[typescript]: https://www.typescriptlang.org

[license]: license

[author]: https://wooorm.com

[mdn-error]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error

[unist-node]: https://github.com/syntax-tree/unist#node

[unist-point]: https://github.com/syntax-tree/unist#point

[unist-position]: https://github.com/syntax-tree/unist#position

[vfile]: https://github.com/vfile/vfile

[util]: https://github.com/vfile/vfile#utilities

[api-options]: #options

[api-vfile-message]: #vfilemessagereason-options


---

# watchpack

Wrapper library for directory and file watching.

[![Test](https://github.com/webpack/watchpack/actions/workflows/test.yml/badge.svg)](https://github.com/webpack/watchpack/actions/workflows/test.yml)
[![Codecov](https://codecov.io/gh/webpack/watchpack/graph/badge.svg?token=8xk2OrrxWm)](https://codecov.io/gh/webpack/watchpack)
[![Downloads](https://img.shields.io/npm/dm/watchpack.svg)](https://www.npmjs.com/package/watchpack)

## Concept

watchpack high level API doesn't map directly to watchers. Instead a three level architecture ensures that for each directory only a single watcher exists.

- The high level API requests `DirectoryWatchers` from a `WatcherManager`, which ensures that only a single `DirectoryWatcher` per directory is created.
- A user-faced `Watcher` can be obtained from a `DirectoryWatcher` and provides a filtered view on the `DirectoryWatcher`.
- Reference-counting is used on the `DirectoryWatcher` and `Watcher` to decide when to close them.
- The real watchers are created by the `DirectoryWatcher`.
- Files are never watched directly. This should keep the watcher count low.
- Watching can be started in the past. This way watching can start after file reading.
- Symlinks are not followed, instead the symlink is watched.

## API

```javascript
var Watchpack = require("watchpack");

var wp = new Watchpack({
	// options:
	aggregateTimeout: 1000,
	// fire "aggregated" event when after a change for 1000ms no additional change occurred
	// aggregated defaults to undefined, which doesn't fire an "aggregated" event

	poll: true,
	// poll: true - use polling with the default interval
	// poll: 10000 - use polling with an interval of 10s
	// poll defaults to undefined, which prefer native watching methods
	// Note: enable polling when watching on a network path
	// When WATCHPACK_POLLING environment variable is set it will override this option

	followSymlinks: true,
	// true: follows symlinks and watches symlinks and real files
	//   (This makes sense when symlinks has not been resolved yet, comes with a performance hit)
	// false (default): watches only specified item they may be real files or symlinks
	//   (This makes sense when symlinks has already been resolved)

	ignored: "**/.git"
	// ignored: "string" - a glob pattern for files or folders that should not be watched
	// ignored: ["string", "string"] - multiple glob patterns that should be ignored
	// ignored: /regexp/ - a regular expression for files or folders that should not be watched
	// ignored: (entry) => boolean - an arbitrary function which must return truthy to ignore an entry
	// For all cases expect the arbitrary function the path will have path separator normalized to '/'.
	// All subdirectories are ignored too
});

// Watchpack.prototype.watch({
//   files: Iterable<string>,
//   directories: Iterable<string>,
//   missing: Iterable<string>,
//   startTime?: number
// })
wp.watch({
	files: listOfFiles,
	directories: listOfDirectories,
	missing: listOfNotExistingItems,
	startTime: Date.now() - 10000
});
// starts watching these files and directories
// calling this again will override the files and directories
// files: can be files or directories, for files: content and existence changes are tracked
//        for directories: only existence and timestamp changes are tracked
// directories: only directories, directory content (and content of children, ...) and
//              existence changes are tracked.
//              assumed to exist, when directory is not found without further information a remove event is emitted
// missing: can be files or directorees,
//          only existence changes are tracked
//          expected to not exist, no remove event is emitted when not found initially
// files and directories are assumed to exist, when they are not found without further information a remove event is emitted
// missing is assumed to not exist and no remove event is emitted

wp.on("change", function(filePath, mtime, explanation) {
	// filePath: the changed file
	// mtime: last modified time for the changed file
	// explanation: textual information how this change was detected
});

wp.on("remove", function(filePath, explanation) {
	// filePath: the removed file or directory
	// explanation: textual information how this change was detected
});

wp.on("aggregated", function(changes, removals) {
	// changes: a Set of all changed files
	// removals: a Set of all removed files
	// watchpack gives up ownership on these Sets.
});

// Watchpack.prototype.pause()
wp.pause();
// stops emitting events, but keeps watchers open
// next "watch" call can reuse the watchers
// The watcher will keep aggregating events
// which can be received with getAggregated()

// Watchpack.prototype.close()
wp.close();
// stops emitting events and closes all watchers

// Watchpack.prototype.getAggregated(): { changes: Set<string>, removals: Set<string> }
const { changes, removals } = wp.getAggregated();
// returns the current aggregated info and removes that from the watcher
// The next aggregated event won't include that info and will only emitted
// when futher changes happen
// Can also be used when paused.

// Watchpack.prototype.collectTimeInfoEntries(fileInfoEntries: Map<string, Entry>, directoryInfoEntries: Map<string, Entry>)
wp.collectTimeInfoEntries(fileInfoEntries, directoryInfoEntries);
// collects time info objects for all known files and directories
// this include info from files not directly watched
// key: absolute path, value: object with { safeTime, timestamp }
// safeTime: a point in time at which it is safe to say all changes happened before that
// timestamp: only for files, the mtime timestamp of the file

// Watchpack.prototype.getTimeInfoEntries()
var fileTimes = wp.getTimeInfoEntries();
// returns a Map with all known time info objects for files and directories
// similar to collectTimeInfoEntries but returns a single map with all entries

// (deprecated)
// Watchpack.prototype.getTimes()
var fileTimes = wp.getTimes();
// returns an object with all known change times for files
// this include timestamps from files not directly watched
// key: absolute path, value: timestamp as number
```


---

# wbuf

#### LICENSE

This software is licensed under the MIT License.

Copyright Fedor Indutny, 2014.

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to permit
persons to whom the Software is furnished to do so, subject to the
following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
USE OR OTHER DEALINGS IN THE SOFTWARE.


---

# web-namespaces

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]

Map of web namespaces.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`webNamespaces`](#webnamespaces)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Security](#security)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This is a map of names to namespaces found on the web platforms.

## When should I use this?

You can use this package if you want to access the XML, HTML, SVG, etc.
namespace urls.

## Install

This package is [ESM only][esm].
In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]:

```sh
npm install web-namespaces
```

In Deno with [Skypack][]:

```js
import {webNamespaces} from 'https://cdn.skypack.dev/web-namespaces@2?dts'
```

In browsers with [Skypack][]:

```html
<script type="module">
  import {webNamespaces} from 'https://cdn.skypack.dev/web-namespaces@2?min'
</script>
```

## Use

```js
import {webNamespaces} from 'web-namespaces'

console.log(webNamespaces)
```

Yields:

```js
{
  html: 'http://www.w3.org/1999/xhtml',
  mathml: 'http://www.w3.org/1998/Math/MathML',
  svg: 'http://www.w3.org/2000/svg',
  xlink: 'http://www.w3.org/1999/xlink',
  xml: 'http://www.w3.org/XML/1998/namespace',
  xmlns: 'http://www.w3.org/2000/xmlns/'
}
```

## API

This package exports the following identifiers: `webNamespaces`.
There is no default export.

### `webNamespaces`

Map of names to namespaces (`Record<string, string>`).

## Types

This package is fully typed with [TypeScript][].
There are no extra exported types.

## Compatibility

This package is at least compatible with all maintained versions of Node.js.
As of now, that is Node.js 12.20+, 14.14+, and 16.0+.
It also works in Deno and modern browsers.

## Security

This package is safe.

## Related

*   [`wooorm/html-tag-names`](https://github.com/wooorm/html-tag-names)
    — list of HTML tag names
*   [`wooorm/mathml-tag-names`](https://github.com/wooorm/mathml-tag-names)
    — list of MathML tag names
*   [`wooorm/svg-tag-names`](https://github.com/wooorm/svg-tag-names)
    — list of SVG tag names
*   [`wooorm/svg-element-attributes`](https://github.com/wooorm/svg-element-attributes)
    — map of SVG elements to allowed attributes
*   [`wooorm/html-element-attributes`](https://github.com/wooorm/html-element-attributes)
    — map of HTML elements to allowed attributes
*   [`wooorm/aria-attributes`](https://github.com/wooorm/aria-attributes)
    — list of ARIA attributes

## Contribute

Yes please!
See [How to Contribute to Open Source][contribute].

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definition -->

[build-badge]: https://github.com/wooorm/web-namespaces/workflows/main/badge.svg

[build]: https://github.com/wooorm/web-namespaces/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/web-namespaces.svg

[coverage]: https://codecov.io/github/wooorm/web-namespaces

[downloads-badge]: https://img.shields.io/npm/dm/web-namespaces.svg

[downloads]: https://www.npmjs.com/package/web-namespaces

[size-badge]: https://img.shields.io/bundlephobia/minzip/web-namespaces.svg

[size]: https://bundlephobia.com/result?p=web-namespaces

[npm]: https://docs.npmjs.com/cli/install

[skypack]: https://www.skypack.dev

[license]: license

[author]: https://wooorm.com

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[typescript]: https://www.typescriptlang.org

[contribute]: https://opensource.guide/how-to-contribute/


---

<div align="center">
  <a href="https://github.com/webpack/webpack">
    <img width="200" height="200" src="https://webpack.js.org/assets/icon-square-big.svg">
  </a>
  <br>
  <br>

[![npm][npm]][npm-url]

[![node][node]][node-url]
[![builds1][builds1]][builds1-url]
[![builds2][builds2]][builds2-url]
[![dependency-review][dependency-review]][dependency-review-url]
[![coverage][cover]][cover-url]
[![PR's welcome][prs]][prs-url]
[![compatibility-score](https://api.dependabot.com/badges/compatibility_score?dependency-name=webpack&package-manager=npm_and_yarn&previous-version=5.72.1&new-version=5.73.0)](https://docs.github.com/en/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates#about-compatibility-scores)
[![downloads](https://img.shields.io/npm/dm/webpack.svg)](https://npmcharts.com/compare/webpack?minimal=true)
[![install-size](https://packagephobia.com/badge?p=webpack)](https://packagephobia.com/result?p=webpack)
[![backers](https://opencollective.com/webpack/backers/badge.svg)](https://opencollective.com/webpack#backer)
[![sponsors](https://opencollective.com/webpack/sponsors/badge.svg)](https://opencollective.com/webpack#sponsors)
[![contributors](https://img.shields.io/github/contributors/webpack/webpack.svg)](https://github.com/webpack/webpack/graphs/contributors)
[![discussions](https://img.shields.io/github/discussions/webpack/webpack)](https://github.com/webpack/webpack/discussions)
[![discord](https://img.shields.io/discord/1180618526436888586?label=discord&logo=discord&logoColor=white&style=flat)](https://discord.gg/5sxFZPdx2k)

  <h1>webpack</h1>
  <p>
    Webpack is a module bundler. Its main purpose is to bundle JavaScript files for usage in a browser, yet it is also capable of transforming, bundling, or packaging just about any resource or asset.
  </p>
</div>

## Table of Contents

- [Install](#install)
- [Introduction](#introduction)
- [Concepts](#concepts)
- [Contributing](#contributing)
- [Support](#support)
- [Current project members](#current-project-members)
  - [TSC (Technical Steering Committee)](#tsc-technical-steering-committee)
  - [Core Collaborators](#core-collaborators)
- [Sponsoring](#sponsoring)
  - [Premium Partners](#premium-partners)
  - [Gold Sponsors](#gold-sponsors)
  - [Silver Sponsors](#silver-sponsors)
  - [Bronze Sponsors](#bronze-sponsors)
  - [Backers](#backers)
- [Special Thanks](#special-thanks-to)

<h2>Install</h2>

Install with npm:

```bash
npm install --save-dev webpack
```

Install with yarn:

```bash
yarn add webpack --dev
```

<h2>Introduction</h2>

Webpack is a bundler for modules. The main purpose is to bundle JavaScript
files for usage in a browser, yet it is also capable of transforming, bundling,
or packaging just about any resource or asset.

**TL;DR**

- Bundles [ES Modules](https://www.2ality.com/2014/09/es6-modules-final.html), [CommonJS](http://wiki.commonjs.org/), and [AMD](https://github.com/amdjs/amdjs-api/wiki/AMD) modules (even combined).
- Can create a single bundle or multiple chunks that are asynchronously loaded at runtime (to reduce initial loading time).
- Dependencies are resolved during compilation, reducing the runtime size.
- Loaders can preprocess files while compiling, e.g. TypeScript to JavaScript, Handlebars strings to compiled functions, images to Base64, etc.
- Highly modular plugin system to do whatever else your application requires.

#### Learn about webpack through videos!

- [Understanding Webpack - Video 1](https://www.youtube.com/watch?v=xj93pvQIsRo)
- [Understanding Webpack - Video 2](https://www.youtube.com/watch?v=4tQiJaFzuJ8)

### Get Started

Check out webpack's quick [**Get Started**](https://webpack.js.org/guides/getting-started) guide and the [other guides](https://webpack.js.org/guides/).

### Browser Compatibility

Webpack supports all browsers that are [ES5-compliant](https://kangax.github.io/compat-table/es5/) (IE8 and below are not supported).
Webpack also needs `Promise` for `import()` and `require.ensure()`. If you want to support older browsers, you will need to [load a polyfill](https://webpack.js.org/guides/shimming/) before using these expressions.

<h2>Concepts</h2>

### [Plugins](https://webpack.js.org/plugins/)

Webpack has a [rich plugin
interface](https://webpack.js.org/plugins/). Most of the features
within webpack itself use this plugin interface. This makes webpack very
**flexible**.

|                   Name                    |       Status       |    Install Size     | Description                                                                             |
| :---------------------------------------: | :----------------: | :-----------------: | :-------------------------------------------------------------------------------------- |
|    [mini-css-extract-plugin][mini-css]    |  ![mini-css-npm]   |  ![mini-css-size]   | Extracts CSS into separate files. It creates a CSS file per JS file which contains CSS. |
| [compression-webpack-plugin][compression] | ![compression-npm] | ![compression-size] | Prepares compressed versions of assets to serve them with Content-Encoding              |
|    [html-webpack-plugin][html-plugin]     | ![html-plugin-npm] | ![html-plugin-size] | Simplifies creation of HTML files (`index.html`) to serve your bundles                  |
|         [pug-plugin][pug-plugin]          | ![pug-plugin-npm]  | ![pug-plugin-size]  | Renders Pug files to HTML, extracts JS and CSS from sources specified directly in Pug.  |

[common-npm]: https://img.shields.io/npm/v/webpack.svg
[mini-css]: https://github.com/webpack-contrib/mini-css-extract-plugin
[mini-css-npm]: https://img.shields.io/npm/v/mini-css-extract-plugin.svg
[mini-css-size]: https://packagephobia.com/badge?p=mini-css-extract-plugin
[component]: https://github.com/webpack-contrib/component-webpack-plugin
[component-npm]: https://img.shields.io/npm/v/component-webpack-plugin.svg
[component-size]: https://packagephobia.com/badge?p=component-webpack-plugin
[compression]: https://github.com/webpack-contrib/compression-webpack-plugin
[compression-npm]: https://img.shields.io/npm/v/compression-webpack-plugin.svg
[compression-size]: https://packagephobia.com/badge?p=compression-webpack-plugin
[html-plugin]: https://github.com/jantimon/html-webpack-plugin
[html-plugin-npm]: https://img.shields.io/npm/v/html-webpack-plugin.svg
[html-plugin-size]: https://packagephobia.com/badge?p=html-webpack-plugin
[pug-plugin]: https://github.com/webdiscus/pug-plugin
[pug-plugin-npm]: https://img.shields.io/npm/v/pug-plugin.svg
[pug-plugin-size]: https://packagephobia.com/badge?p=pug-plugin

### [Loaders](https://webpack.js.org/loaders/)

Webpack enables the use of loaders to preprocess files. This allows you to bundle
**any static resource** way beyond JavaScript. You can easily [write your own
loaders](https://webpack.js.org/api/loaders/) using Node.js.

Loaders are activated by using `loadername!` prefixes in `require()` statements,
or are automatically applied via regex from your webpack configuration.

#### Files

|       Name        |   Status   | Install Size | Description                                              |
| :---------------: | :--------: | :----------: | :------------------------------------------------------- |
| [val-loader][val] | ![val-npm] | ![val-size]  | Executes code as module and considers exports as JS code |

[val]: https://github.com/webpack-contrib/val-loader
[val-npm]: https://img.shields.io/npm/v/val-loader.svg
[val-size]: https://packagephobia.com/badge?p=val-loader

#### JSON

|                                                                   Name                                                                    |   Status    | Install Size |           Description            |
| :---------------------------------------------------------------------------------------------------------------------------------------: | :---------: | :----------: | :------------------------------: |
| <a href="https://github.com/awnist/cson-loader"><img width="48" height="48" src="https://worldvectorlogo.com/logos/coffeescript.svg"></a> | ![cson-npm] | ![cson-size] | Loads and transpiles a CSON file |

[cson-npm]: https://img.shields.io/npm/v/cson-loader.svg
[cson-size]: https://packagephobia.com/badge?p=cson-loader

#### Transpiling

|                                                                                                                             Name                                                                                                                             |    Status     |  Install Size  | Description                                                                                       |
| :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-----------: | :------------: | :------------------------------------------------------------------------------------------------ |
|                                                  <a href="https://github.com/babel/babel-loader"><img width="48" height="48" title="babel-loader" src="https://worldvectorlogo.com/logos/babel-10.svg"></a>                                                  | ![babel-npm]  | ![babel-size]  | Loads ES2015+ code and transpiles to ES5 using <a href="https://github.com/babel/babel">Babel</a> |
| <a href="https://github.com/TypeStrong/ts-loader"><img width="48" height="48" src="https://raw.githubusercontent.com/microsoft/TypeScript-Website/f407e1ae19e5e990d9901ac8064a32a8cc60edf0/packages/typescriptlang-org/static/branding/ts-logo-128.svg"></a> |  ![type-npm]  |  ![type-size]  | Loads TypeScript like JavaScript                                                                  |
|                                                     <a href="https://github.com/webpack-contrib/coffee-loader"><img width="48" height="48" src="https://worldvectorlogo.com/logos/coffeescript.svg"></a>                                                     | ![coffee-npm] | ![coffee-size] | Loads CoffeeScript like JavaScript                                                                |

[babel-npm]: https://img.shields.io/npm/v/babel-loader.svg
[babel-size]: https://packagephobia.com/badge?p=babel-loader
[coffee-npm]: https://img.shields.io/npm/v/coffee-loader.svg
[coffee-size]: https://packagephobia.com/badge?p=coffee-loader
[type-npm]: https://img.shields.io/npm/v/ts-loader.svg
[type-size]: https://packagephobia.com/badge?p=ts-loader

#### Templating

|                                                                                   Name                                                                                    |     Status      |   Install Size   | Description                                                                             |
| :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-------------: | :--------------: | :-------------------------------------------------------------------------------------- |
|               <a href="https://github.com/webpack-contrib/html-loader"><img width="48" height="48" src="https://worldvectorlogo.com/logos/html5-2.svg"></a>               |   ![html-npm]   |   ![html-size]   | Exports HTML as string, requires references to static resources                         |
|   <a href="https://github.com/pugjs/pug-loader"><img width="48" height="48" src="https://cdn.rawgit.com/pugjs/pug-logo/master/SVG/pug-final-logo-_-colour-128.svg"></a>   |   ![pug-npm]    |   ![pug-size]    | Loads Pug templates and returns a function                                              |
| <a href="https://github.com/webdiscus/pug-loader"><img width="48" height="48" src="https://cdn.rawgit.com/pugjs/pug-logo/master/SVG/pug-final-logo-_-colour-128.svg"></a> |   ![pug3-npm]   |   ![pug3-size]   | Compiles Pug to a function or HTML string, useful for use with Vue, React, Angular      |
|                <a href="https://github.com/peerigon/markdown-loader"><img width="48" height="48" src="https://worldvectorlogo.com/logos/markdown.svg"></a>                |    ![md-npm]    |    ![md-size]    | Compiles Markdown to HTML                                                               |
|                 <a href="https://github.com/posthtml/posthtml-loader"><img width="48" height="48" src="https://posthtml.github.io/posthtml/logo.svg"></a>                 | ![posthtml-npm] | ![posthtml-size] | Loads and transforms a HTML file using [PostHTML](https://github.com/posthtml/posthtml) |
|             <a href="https://github.com/pcardune/handlebars-loader"><img width="48" height="48" src="https://worldvectorlogo.com/logos/handlebars-1.svg"></a>             |   ![hbs-npm]    |   ![hbs-size]    | Compiles Handlebars to HTML                                                             |

[html-npm]: https://img.shields.io/npm/v/html-loader.svg
[html-size]: https://packagephobia.com/badge?p=html-loader
[pug-npm]: https://img.shields.io/npm/v/pug-loader.svg
[pug-size]: https://packagephobia.com/badge?p=pug-loader
[pug3-npm]: https://img.shields.io/npm/v/@webdiscus/pug-loader.svg
[pug3-size]: https://packagephobia.com/badge?p=@webdiscus/pug-loader
[jade-npm]: https://img.shields.io/npm/v/jade-loader.svg
[jade-size]: https://packagephobia.com/badge?p=jade-loader
[md-npm]: https://img.shields.io/npm/v/markdown-loader.svg
[md-size]: https://packagephobia.com/badge?p=markdown-loader
[posthtml-npm]: https://img.shields.io/npm/v/posthtml-loader.svg
[posthtml-size]: https://packagephobia.com/badge?p=posthtml-loader
[hbs-npm]: https://img.shields.io/npm/v/handlebars-loader.svg
[hbs-size]: https://packagephobia.com/badge?p=handlebars-loader

#### Styling

|                                                                     Name                                                                      |     Status     |  Install Size   | Description                                                              |
| :-------------------------------------------------------------------------------------------------------------------------------------------: | :------------: | :-------------: | :----------------------------------------------------------------------- |
|                                    <a href="https://github.com/webpack-contrib/style-loader">`<style>`</a>                                    |  ![style-npm]  |  ![style-size]  | Add exports of a module as style to DOM                                  |
|  <a href="https://github.com/webpack-contrib/css-loader"><img width="48" height="48" src="https://worldvectorlogo.com/logos/css-3.svg"></a>   |   ![css-npm]   |   ![css-size]   | Loads CSS file with resolved imports and returns CSS code                |
| <a href="https://github.com/webpack-contrib/less-loader"><img width="48" height="48" src="https://worldvectorlogo.com/logos/less-63.svg"></a> |  ![less-npm]   |  ![less-size]   | Loads and compiles a LESS file                                           |
| <a href="https://github.com/webpack-contrib/sass-loader"><img width="48" height="48" src="https://worldvectorlogo.com/logos/sass-1.svg"></a>  |  ![sass-npm]   |  ![sass-size]   | Loads and compiles a Sass/SCSS file                                      |
|     <a href="https://github.com/shama/stylus-loader"><img width="48" height="48" src="https://worldvectorlogo.com/logos/stylus.svg"></a>      | ![stylus-npm]  | ![stylus-size]  | Loads and compiles a Stylus file                                         |
|   <a href="https://github.com/postcss/postcss-loader"><img width="48" height="48" src="https://worldvectorlogo.com/logos/postcss.svg"></a>    | ![postcss-npm] | ![postcss-size] | Loads and transforms a CSS/SSS file using [PostCSS](https://postcss.org) |

[style-npm]: https://img.shields.io/npm/v/style-loader.svg
[style-size]: https://packagephobia.com/badge?p=style-loader
[css-npm]: https://img.shields.io/npm/v/css-loader.svg
[css-size]: https://packagephobia.com/badge?p=css-loader
[less-npm]: https://img.shields.io/npm/v/less-loader.svg
[less-size]: https://packagephobia.com/badge?p=less-loader
[sass-npm]: https://img.shields.io/npm/v/sass-loader.svg
[sass-size]: https://packagephobia.com/badge?p=sass-loader
[stylus-npm]: https://img.shields.io/npm/v/stylus-loader.svg
[stylus-size]: https://packagephobia.com/badge?p=stylus-loader
[postcss-npm]: https://img.shields.io/npm/v/postcss-loader.svg
[postcss-size]: https://packagephobia.com/badge?p=postcss-loader

#### Frameworks

|                                                                             Name                                                                             |     Status     |  Install Size   | Description                                                                                            |
| :----------------------------------------------------------------------------------------------------------------------------------------------------------: | :------------: | :-------------: | :----------------------------------------------------------------------------------------------------- |
|               <a href="https://github.com/vuejs/vue-loader"><img width="48" height="48" src="https://worldvectorlogo.com/logos/vue-9.svg"></a>               |   ![vue-npm]   |   ![vue-size]   | Loads and compiles Vue Components                                                                      |
|   <a href="https://github.com/webpack-contrib/polymer-webpack-loader"><img width="48" height="48" src="https://worldvectorlogo.com/logos/polymer.svg"></a>   | ![polymer-npm] | ![polymer-size] | Process HTML & CSS with preprocessor of choice and `require()` Web Components like first-class modules |
| <a href="https://github.com/TheLarkInn/angular2-template-loader"><img width="48" height="48" src="https://worldvectorlogo.com/logos/angular-icon-1.svg"></a> | ![angular-npm] | ![angular-size] | Loads and compiles Angular 2 Components                                                                |
|              <a href="https://github.com/riot/webpack-loader"><img width="48" height="48" src="https://worldvectorlogo.com/logos/riot.svg"></a>              |  ![riot-npm]   |  ![riot-size]   | Riot official webpack loader                                                                           |
|          <a href="https://github.com/sveltejs/svelte-loader"><img width="48" height="48" src="https://worldvectorlogo.com/logos/svelte-1.svg"></a>           | ![svelte-npm]  | ![svelte-size]  | Official Svelte loader                                                                                 |

[vue-npm]: https://img.shields.io/npm/v/vue-loader.svg
[vue-size]: https://packagephobia.com/badge?p=vue-loader
[polymer-npm]: https://img.shields.io/npm/v/polymer-webpack-loader.svg
[polymer-size]: https://packagephobia.com/badge?p=polymer-webpack-loader
[angular-npm]: https://img.shields.io/npm/v/angular2-template-loader.svg
[angular-size]: https://packagephobia.com/badge?p=angular2-template-loader
[riot-npm]: https://img.shields.io/npm/v/riot-tag-loader.svg
[riot-size]: https://packagephobia.com/badge?p=riot-tag-loader
[svelte-npm]: https://img.shields.io/npm/v/svelte-loader.svg
[svelte-size]: https://packagephobia.com/badge?p=svelte-loader

### Performance

Webpack uses async I/O and has multiple caching levels. This makes webpack fast
and incredibly **fast** on incremental compilations.

### Module Formats

Webpack supports ES2015+, CommonJS and AMD modules **out of the box**. It performs clever static
analysis on the AST of your code. It even has an evaluation engine to evaluate
simple expressions. This allows you to **support most existing libraries** out of the box.

### [Code Splitting](https://webpack.js.org/guides/code-splitting/)

Webpack allows you to split your codebase into multiple chunks. Chunks are
loaded asynchronously at runtime. This reduces the initial loading time.

### [Optimizations](https://webpack.js.org/guides/production-build/)

Webpack can do many optimizations to **reduce the output size of your
JavaScript** by deduplicating frequently used modules, minifying, and giving
you full control of what is loaded initially and what is loaded at runtime
through code splitting. It can also make your code chunks **cache
friendly** by using hashes.

<h2>Contributing</h2>

**We want contributing to webpack to be fun, enjoyable, and educational for anyone, and everyone.** We have a [vibrant ecosystem](https://medium.com/webpack/contributors-guide/home) that spans beyond this single repo. We welcome you to check out any of the repositories in [our organization](https://github.com/webpack) or [webpack-contrib organization](https://github.com/webpack-contrib) which houses all of our loaders and plugins.

Contributions go far beyond pull requests and commits. Although we love giving you the opportunity to put your stamp on webpack, we also are thrilled to receive a variety of other contributions including:

- [Documentation](https://github.com/webpack/webpack.js.org) updates, enhancements, designs, or bugfixes
- Spelling or grammar fixes
- README.md corrections or redesigns
- Adding unit, or functional tests
- Triaging GitHub issues -- especially determining whether an issue still persists or is reproducible.
- [Searching #webpack on twitter](https://twitter.com/search?q=webpack) and helping someone else who needs help
- Teaching others how to contribute to one of the many webpack's repos!
- [Blogging, speaking about, or creating tutorials](https://github.com/webpack-contrib/awesome-webpack) about one of webpack's many features.
- Helping others in our webpack [gitter channel](https://gitter.im/webpack/webpack).
- [The Contributor's Guide to webpack](https://medium.com/webpack/contributors-guide/home)

To get started have a look at our [documentation on contributing](https://github.com/webpack/webpack/blob/main/CONTRIBUTING.md).

<h3>Creating your own plugins and loaders</h3>

If you create a loader or plugin, we would <3 for you to open source it, and put it on npm. We follow the `x-loader`, `x-webpack-plugin` naming convention.

<h2>Support</h2>

We consider webpack to be a low-level tool used not only individually but also layered beneath other awesome tools. Because of its flexibility, webpack isn't always the _easiest_ entry-level solution, however we do believe it is the most powerful. That said, we're always looking for ways to improve and simplify the tool without compromising functionality. If you have any ideas on ways to accomplish this, we're all ears!

If you're just getting started, take a look at [our new docs and concepts page](https://webpack.js.org/concepts/). This has a high level overview that is great for beginners!!

If you have discovered a 🐜 or have a feature suggestion, feel free to create an issue on GitHub.

<h2>Current project members</h2>

For information about the governance of the Node.js project, see [GOVERNANCE.md](./GOVERNANCE.md).

<h3>TSC (Technical Steering Committee)</h3>

- [alexander-akait](https://github.com/alexander-akait) -
  **Alexander Akait** <<sheo13666q@gmail.com>> (he/him)
- [ematipico](https://github.com/ematipico) -
  **Emanuele Stoppa** <<my.burning@gmail.com>> (he/him)
- [evenstensberg](https://github.com/evenstensberg) -
  **Even Stensberg** <<evenstensberg@gmail.com>> (he/him)
- [ovflowd](https://github.com/ovflowd) -
  **Claudio Wunder** <<cwunder@gnome.org>> (he/they)
- [snitin315](https://github.com/snitin315) -
  **Nitin Kumarr** <<snitin315@gmail.com>> (he/him)

<h3>Core Collaborators</h3>

- [jhnns](https://github.com/jhnns) -
  **Johannes Ewald** <<mail@johannesewald.de>>
- [sokra](https://github.com/sokra) -
  **Tobias Koppers** <<jackworks@protonmail.co>>
- [spacek33z](https://github.com/spacek33z) -
  **Kees Kluskens** <<kees@webduck.nl>>
- [TheLarkInn](https://github.com/TheLarkInn) -
  **Sean T. Larkin** <<selarkin@microsoft.com>>

<h2>Sponsoring</h2>

Most of the core team members, webpack contributors and contributors in the ecosystem do this open source work in their free time. If you use webpack for a serious task, and you'd like us to invest more time on it, please donate. This project increases your income/productivity too. It makes development and applications faster and it reduces the required bandwidth.

This is how we use the donations:

- Allow the core team to work on webpack
- Thank contributors if they invested a large amount of time in contributing
- Support projects in the ecosystem that are of great value for users
- Support projects that are voted most (work in progress)
- Infrastructure cost
- Fees for money handling

<h3>Premium Partners</h3>

<div align="center">

<a href="https://www.ag-grid.com/?utm_source=webpack&utm_medium=banner&utm_campaign=sponsorship" target="_blank"><img align="center" src="https://raw.githubusercontent.com/webpack/media/2b399d58/horiz-banner-ad-ag-grid.png">
</a>

</div>

<h3>Other Backers and Sponsors</h3>

Before we started using OpenCollective, donations were made anonymously. Now that we have made the switch, we would like to acknowledge these sponsors (and the ones who continue to donate using OpenCollective). If we've missed someone, please send us a PR, and we'll add you to this list.

<div align="center">

<a href="https://angular.io/" target="_blank" title="JS framework">Angular</a>
<a href="https://moonmail.io" target="_blank" title="Email Marketing Software">MoonMail</a>
<a href="https://monei.net" target="_blank" title="Best payment gateway rates">MONEI</a>

</div>

<h3>Gold Sponsors</h3>

[Become a gold sponsor](https://opencollective.com/webpack#sponsor) and get your logo on our README on GitHub with a link to your site.

<div align="center">

<a href="https://opencollective.com/webpack/goldsponsor/0/website?requireActive=false" target="_blank"><img width="150" src="https://opencollective.com/webpack/goldsponsor/0/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/goldsponsor/1/website?requireActive=false" target="_blank"><img width="150" src="https://opencollective.com/webpack/goldsponsor/1/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/goldsponsor/2/website?requireActive=false" target="_blank"><img width="150" src="https://opencollective.com/webpack/goldsponsor/2/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/goldsponsor/3/website?requireActive=false" target="_blank"><img width="150" src="https://opencollective.com/webpack/goldsponsor/3/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/goldsponsor/4/website?requireActive=false" target="_blank"><img width="150" src="https://opencollective.com/webpack/goldsponsor/4/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/goldsponsor/5/website?requireActive=false" target="_blank"><img width="150" src="https://opencollective.com/webpack/goldsponsor/5/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/goldsponsor/6/website?requireActive=false" target="_blank"><img width="150" src="https://opencollective.com/webpack/goldsponsor/6/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/goldsponsor/7/website?requireActive=false" target="_blank"><img width="150" src="https://opencollective.com/webpack/goldsponsor/7/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/goldsponsor/8/website?requireActive=false" target="_blank"><img width="150" src="https://opencollective.com/webpack/goldsponsor/8/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/goldsponsor/9/website?requireActive=false" target="_blank"><img width="150" src="https://opencollective.com/webpack/goldsponsor/9/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/goldsponsor/10/website?requireActive=false" target="_blank"><img width="150" src="https://opencollective.com/webpack/goldsponsor/10/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/goldsponsor/11/website?requireActive=false" target="_blank"><img width="150" src="https://opencollective.com/webpack/goldsponsor/11/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/goldsponsor/12/website?requireActive=false" target="_blank"><img width="150" src="https://opencollective.com/webpack/goldsponsor/12/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/goldsponsor/13/website?requireActive=false" target="_blank"><img width="150" src="https://opencollective.com/webpack/goldsponsor/13/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/goldsponsor/14/website?requireActive=false" target="_blank"><img width="150" src="https://opencollective.com/webpack/goldsponsor/14/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/goldsponsor/15/website?requireActive=false" target="_blank"><img width="150" src="https://opencollective.com/webpack/goldsponsor/15/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/goldsponsor/16/website?requireActive=false" target="_blank"><img width="150" src="https://opencollective.com/webpack/goldsponsor/16/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/goldsponsor/17/website?requireActive=false" target="_blank"><img width="150" src="https://opencollective.com/webpack/goldsponsor/17/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/goldsponsor/18/website?requireActive=false" target="_blank"><img width="150" src="https://opencollective.com/webpack/goldsponsor/18/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/goldsponsor/19/website?requireActive=false" target="_blank"><img width="150" src="https://opencollective.com/webpack/goldsponsor/19/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/goldsponsor/20/website?requireActive=false" target="_blank"><img width="150" src="https://opencollective.com/webpack/goldsponsor/20/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/goldsponsor/21/website?requireActive=false" target="_blank"><img width="150" src="https://opencollective.com/webpack/goldsponsor/21/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/goldsponsor/22/website?requireActive=false" target="_blank"><img width="150" src="https://opencollective.com/webpack/goldsponsor/22/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/goldsponsor/23/website?requireActive=false" target="_blank"><img width="150" src="https://opencollective.com/webpack/goldsponsor/23/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/goldsponsor/24/website?requireActive=false" target="_blank"><img width="150" src="https://opencollective.com/webpack/goldsponsor/24/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/goldsponsor/25/website?requireActive=false" target="_blank"><img width="150" src="https://opencollective.com/webpack/goldsponsor/25/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/goldsponsor/26/website?requireActive=false" target="_blank"><img width="150" src="https://opencollective.com/webpack/goldsponsor/26/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/goldsponsor/27/website?requireActive=false" target="_blank"><img width="150" src="https://opencollective.com/webpack/goldsponsor/27/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/goldsponsor/28/website?requireActive=false" target="_blank"><img width="150" src="https://opencollective.com/webpack/goldsponsor/28/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/goldsponsor/29/website?requireActive=false" target="_blank"><img width="150" src="https://opencollective.com/webpack/goldsponsor/29/avatar.svg?requireActive=false"></a>

</div>

<h3>Silver Sponsors</h3>

[Become a silver sponsor](https://opencollective.com/webpack#sponsor) and get your logo on our README on GitHub with a link to your site.

<div align="center">

<a href="https://opencollective.com/webpack/silversponsor/0/website?requireActive=false" target="_blank"><img width="120" src="https://opencollective.com/webpack/silversponsor/0/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/silversponsor/1/website?requireActive=false" target="_blank"><img width="120" src="https://opencollective.com/webpack/silversponsor/1/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/silversponsor/2/website?requireActive=false" target="_blank"><img width="120" src="https://opencollective.com/webpack/silversponsor/2/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/silversponsor/3/website?requireActive=false" target="_blank"><img width="120" src="https://opencollective.com/webpack/silversponsor/3/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/silversponsor/4/website?requireActive=false" target="_blank"><img width="120" src="https://opencollective.com/webpack/silversponsor/4/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/silversponsor/5/website?requireActive=false" target="_blank"><img width="120" src="https://opencollective.com/webpack/silversponsor/5/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/silversponsor/6/website?requireActive=false" target="_blank"><img width="120" src="https://opencollective.com/webpack/silversponsor/6/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/silversponsor/7/website?requireActive=false" target="_blank"><img width="120" src="https://opencollective.com/webpack/silversponsor/7/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/silversponsor/8/website?requireActive=false" target="_blank"><img width="120" src="https://opencollective.com/webpack/silversponsor/8/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/silversponsor/9/website?requireActive=false" target="_blank"><img width="120" src="https://opencollective.com/webpack/silversponsor/9/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/silversponsor/10/website?requireActive=false" target="_blank"><img width="120" src="https://opencollective.com/webpack/silversponsor/10/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/silversponsor/11/website?requireActive=false" target="_blank"><img width="120" src="https://opencollective.com/webpack/silversponsor/11/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/silversponsor/12/website?requireActive=false" target="_blank"><img width="120" src="https://opencollective.com/webpack/silversponsor/12/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/silversponsor/13/website?requireActive=false" target="_blank"><img width="120" src="https://opencollective.com/webpack/silversponsor/13/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/silversponsor/14/website?requireActive=false" target="_blank"><img width="120" src="https://opencollective.com/webpack/silversponsor/14/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/silversponsor/15/website?requireActive=false" target="_blank"><img width="120" src="https://opencollective.com/webpack/silversponsor/15/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/silversponsor/16/website?requireActive=false" target="_blank"><img width="120" src="https://opencollective.com/webpack/silversponsor/16/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/silversponsor/17/website?requireActive=false" target="_blank"><img width="120" src="https://opencollective.com/webpack/silversponsor/17/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/silversponsor/18/website?requireActive=false" target="_blank"><img width="120" src="https://opencollective.com/webpack/silversponsor/18/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/silversponsor/19/website?requireActive=false" target="_blank"><img width="120" src="https://opencollective.com/webpack/silversponsor/19/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/silversponsor/20/website?requireActive=false" target="_blank"><img width="120" src="https://opencollective.com/webpack/silversponsor/20/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/silversponsor/21/website?requireActive=false" target="_blank"><img width="120" src="https://opencollective.com/webpack/silversponsor/21/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/silversponsor/22/website?requireActive=false" target="_blank"><img width="120" src="https://opencollective.com/webpack/silversponsor/22/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/silversponsor/23/website?requireActive=false" target="_blank"><img width="120" src="https://opencollective.com/webpack/silversponsor/23/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/silversponsor/24/website?requireActive=false" target="_blank"><img width="120" src="https://opencollective.com/webpack/silversponsor/24/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/silversponsor/25/website?requireActive=false" target="_blank"><img width="120" src="https://opencollective.com/webpack/silversponsor/25/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/silversponsor/26/website?requireActive=false" target="_blank"><img width="120" src="https://opencollective.com/webpack/silversponsor/26/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/silversponsor/27/website?requireActive=false" target="_blank"><img width="120" src="https://opencollective.com/webpack/silversponsor/27/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/silversponsor/28/website?requireActive=false" target="_blank"><img width="120" src="https://opencollective.com/webpack/silversponsor/28/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/silversponsor/29/website?requireActive=false" target="_blank"><img width="120" src="https://opencollective.com/webpack/silversponsor/29/avatar.svg?requireActive=false"></a>

</div>

<h3>Bronze Sponsors</h3>

[Become a bronze sponsor](https://opencollective.com/webpack#sponsor) and get your logo on our README on GitHub with a link to your site.

<div align="center">

<a href="https://opencollective.com/webpack/sponsor/0/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/0/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/1/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/1/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/2/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/2/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/3/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/3/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/4/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/4/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/5/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/5/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/6/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/6/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/7/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/7/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/8/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/8/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/9/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/9/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/10/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/10/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/11/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/11/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/12/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/12/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/13/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/13/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/14/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/14/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/15/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/15/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/16/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/16/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/17/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/17/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/18/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/18/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/19/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/19/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/20/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/20/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/21/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/21/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/22/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/22/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/23/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/23/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/24/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/24/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/25/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/25/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/26/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/26/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/27/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/27/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/28/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/28/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/29/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/29/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/30/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/30/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/31/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/31/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/32/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/32/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/33/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/33/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/34/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/34/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/35/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/35/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/36/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/36/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/37/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/37/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/38/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/38/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/39/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/39/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/40/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/40/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/41/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/41/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/42/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/42/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/43/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/43/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/44/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/44/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/45/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/45/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/46/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/46/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/47/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/47/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/48/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/48/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/49/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/49/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/50/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/50/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/51/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/51/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/52/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/52/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/53/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/53/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/54/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/54/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/55/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/55/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/56/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/56/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/57/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/57/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/58/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/58/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/59/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/59/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/60/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/60/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/61/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/61/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/62/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/62/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/63/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/63/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/64/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/64/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/65/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/65/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/66/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/66/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/67/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/67/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/68/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/68/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/69/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/69/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/70/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/70/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/71/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/71/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/72/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/72/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/73/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/73/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/74/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/74/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/75/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/75/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/76/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/76/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/77/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/77/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/78/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/78/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/79/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/79/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/80/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/80/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/81/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/81/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/82/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/82/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/83/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/83/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/84/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/84/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/85/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/85/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/86/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/86/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/87/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/87/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/88/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/88/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/89/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/89/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/90/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/90/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/91/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/91/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/92/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/92/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/93/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/93/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/94/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/94/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/95/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/95/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/96/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/96/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/97/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/97/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/98/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/98/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/99/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/99/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/sponsor/100/website?requireActive=false" target="_blank"><img width="100" src="https://opencollective.com/webpack/sponsor/100/avatar.svg?requireActive=false"></a>

</div>

<h3>Backers</h3>

[Become a backer](https://opencollective.com/webpack#backer) and get your image on our README on GitHub with a link to your site.

<a href="https://opencollective.com/webpack/backer/0/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/0/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/1/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/1/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/2/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/2/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/3/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/3/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/4/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/4/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/5/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/5/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/6/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/6/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/7/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/7/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/8/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/8/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/9/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/9/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/10/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/10/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/11/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/11/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/12/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/12/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/13/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/13/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/14/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/14/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/15/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/15/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/16/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/16/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/17/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/17/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/18/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/18/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/19/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/19/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/20/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/20/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/21/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/21/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/22/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/22/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/23/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/23/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/24/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/24/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/25/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/25/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/26/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/26/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/27/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/27/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/28/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/28/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/29/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/29/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/30/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/30/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/31/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/31/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/32/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/32/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/33/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/33/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/34/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/34/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/35/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/35/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/36/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/36/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/37/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/37/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/38/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/38/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/39/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/39/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/40/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/40/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/41/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/41/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/42/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/42/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/43/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/43/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/44/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/44/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/45/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/45/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/46/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/46/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/47/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/47/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/48/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/48/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/49/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/49/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/50/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/50/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/51/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/51/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/52/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/52/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/53/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/53/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/54/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/54/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/55/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/55/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/56/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/56/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/57/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/57/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/58/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/58/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/59/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/59/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/60/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/60/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/61/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/61/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/62/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/62/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/63/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/63/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/64/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/64/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/65/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/65/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/66/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/66/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/67/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/67/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/68/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/68/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/69/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/69/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/70/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/70/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/71/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/71/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/72/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/72/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/73/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/73/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/74/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/74/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/75/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/75/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/76/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/76/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/77/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/77/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/78/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/78/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/79/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/79/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/80/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/80/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/81/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/81/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/82/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/82/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/83/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/83/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/84/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/84/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/85/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/85/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/86/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/86/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/87/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/87/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/88/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/88/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/89/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/89/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/90/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/90/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/91/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/91/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/92/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/92/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/93/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/93/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/94/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/94/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/95/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/95/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/96/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/96/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/97/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/97/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/98/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/98/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/99/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/99/avatar.svg?requireActive=false"></a>
<a href="https://opencollective.com/webpack/backer/100/website?requireActive=false" target="_blank"><img width="30" src="https://opencollective.com/webpack/backer/100/avatar.svg?requireActive=false"></a>

<h2>Special Thanks to</h2>
<p>(In chronological order)</p>

- [@google](https://github.com/google) for [Google Web Toolkit (GWT)](http://www.gwtproject.org/), which aims to compile Java to JavaScript. It features a similar [Code Splitting](http://www.gwtproject.org/doc/latest/DevGuideCodeSplitting.html) as webpack.
- [@medikoo](https://github.com/medikoo) for [modules-webmake](https://github.com/medikoo/modules-webmake), which is a similar project. webpack was born because of the desire for code splitting for modules such as Webmake. Interestingly, the [Code Splitting issue is still open](https://github.com/medikoo/modules-webmake/issues/7) (thanks also to @Phoscur for the discussion).
- [@substack](https://github.com/substack) for [browserify](https://browserify.org/), which is a similar project and source for many ideas.
- [@jrburke](https://github.com/jrburke) for [require.js](https://requirejs.org/), which is a similar project and source for many ideas.
- [@defunctzombie](https://github.com/defunctzombie) for the [browser-field spec](https://github.com/defunctzombie/package-browser-field-spec), which makes modules available for node.js, browserify and webpack.
- [@sokra](https://github.com/sokra) for creating webpack.
- Every early webpack user, which contributed to webpack by writing issues or PRs. You influenced the direction.
- All past and current webpack maintainers and collaborators.
- Everyone who has written a loader for webpack. You are the ecosystem...
- Everyone not mentioned here but that has also influenced webpack.

[npm]: https://img.shields.io/npm/v/webpack.svg
[npm-url]: https://npmjs.com/package/webpack
[node]: https://img.shields.io/node/v/webpack.svg
[node-url]: https://nodejs.org
[prs]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg
[prs-url]: https://webpack.js.org/contribute/
[builds1]: https://github.com/webpack/webpack/actions/workflows/test.yml/badge.svg
[builds1-url]: https://github.com/webpack/webpack/actions/workflows/test.yml
[builds2]: https://dev.azure.com/webpack/webpack/_apis/build/status%2Fwebpack.webpack?branchName=main
[builds2-url]: https://dev.azure.com/webpack/webpack/_build/latest?definitionId=3&branchName=main
[dependency-review-url]: https://github.com/webpack/webpack/actions/workflows/dependency-review.yml
[dependency-review]: https://github.com/webpack/webpack/actions/workflows/dependency-review.yml/badge.svg
[cover]: https://codecov.io/gh/webpack/webpack/branch/master/graph/badge.svg?token=mDP3mQJNnn
[cover-url]: https://codecov.io/gh/webpack/webpack


---

# Reporting Security Issues

If you discover a security issue in webpack, please report it by sending an
email to [webpack@opencollective.com](mailto:webpack@opencollective.com).

This will allow us to assess the risk, and make a fix available before we add a
bug report to the GitHub repository.

Thanks for helping make webpack safe for everyone.


---

1.52.0 / 2022-02-21
===================

  * Add extensions from IANA for more `image/*` types
  * Add extension `.asc` to `application/pgp-keys`
  * Add extensions to various XML types
  * Add new upstream MIME types

1.51.0 / 2021-11-08
===================

  * Add new upstream MIME types
  * Mark `image/vnd.microsoft.icon` as compressible
  * Mark `image/vnd.ms-dds` as compressible

1.50.0 / 2021-09-15
===================

  * Add deprecated iWorks mime types and extensions
  * Add new upstream MIME types

1.49.0 / 2021-07-26
===================

  * Add extension `.trig` to `application/trig`
  * Add new upstream MIME types

1.48.0 / 2021-05-30
===================

  * Add extension `.mvt` to `application/vnd.mapbox-vector-tile`
  * Add new upstream MIME types
  * Mark `text/yaml` as compressible

1.47.0 / 2021-04-01
===================

  * Add new upstream MIME types
  * Remove ambigious extensions from IANA for `application/*+xml` types
  * Update primary extension to `.es` for `application/ecmascript`

1.46.0 / 2021-02-13
===================

  * Add extension `.amr` to `audio/amr`
  * Add extension `.m4s` to `video/iso.segment`
  * Add extension `.opus` to `audio/ogg`
  * Add new upstream MIME types

1.45.0 / 2020-09-22
===================

  * Add `application/ubjson` with extension `.ubj`
  * Add `image/avif` with extension `.avif`
  * Add `image/ktx2` with extension `.ktx2`
  * Add extension `.dbf` to `application/vnd.dbf`
  * Add extension `.rar` to `application/vnd.rar`
  * Add extension `.td` to `application/urc-targetdesc+xml`
  * Add new upstream MIME types
  * Fix extension of `application/vnd.apple.keynote` to be `.key`

1.44.0 / 2020-04-22
===================

  * Add charsets from IANA
  * Add extension `.cjs` to `application/node`
  * Add new upstream MIME types

1.43.0 / 2020-01-05
===================

  * Add `application/x-keepass2` with extension `.kdbx`
  * Add extension `.mxmf` to `audio/mobile-xmf`
  * Add extensions from IANA for `application/*+xml` types
  * Add new upstream MIME types

1.42.0 / 2019-09-25
===================

  * Add `image/vnd.ms-dds` with extension `.dds`
  * Add new upstream MIME types
  * Remove compressible from `multipart/mixed`

1.41.0 / 2019-08-30
===================

  * Add new upstream MIME types
  * Add `application/toml` with extension `.toml`
  * Mark `font/ttf` as compressible

1.40.0 / 2019-04-20
===================

  * Add extensions from IANA for `model/*` types
  * Add `text/mdx` with extension `.mdx`

1.39.0 / 2019-04-04
===================

  * Add extensions `.siv` and `.sieve` to `application/sieve`
  * Add new upstream MIME types

1.38.0 / 2019-02-04
===================

  * Add extension `.nq` to `application/n-quads`
  * Add extension `.nt` to `application/n-triples`
  * Add new upstream MIME types
  * Mark `text/less` as compressible

1.37.0 / 2018-10-19
===================

  * Add extensions to HEIC image types
  * Add new upstream MIME types

1.36.0 / 2018-08-20
===================

  * Add Apple file extensions from IANA
  * Add extensions from IANA for `image/*` types
  * Add new upstream MIME types

1.35.0 / 2018-07-15
===================

  * Add extension `.owl` to `application/rdf+xml`
  * Add new upstream MIME types
    - Removes extension `.woff` from `application/font-woff`

1.34.0 / 2018-06-03
===================

  * Add extension `.csl` to `application/vnd.citationstyles.style+xml`
  * Add extension `.es` to `application/ecmascript`
  * Add new upstream MIME types
  * Add `UTF-8` as default charset for `text/turtle`
  * Mark all XML-derived types as compressible

1.33.0 / 2018-02-15
===================

  * Add extensions from IANA for `message/*` types
  * Add new upstream MIME types
  * Fix some incorrect OOXML types
  * Remove `application/font-woff2`

1.32.0 / 2017-11-29
===================

  * Add new upstream MIME types
  * Update `text/hjson` to registered `application/hjson`
  * Add `text/shex` with extension `.shex`

1.31.0 / 2017-10-25
===================

  * Add `application/raml+yaml` with extension `.raml`
  * Add `application/wasm` with extension `.wasm`
  * Add new `font` type from IANA
  * Add new upstream font extensions
  * Add new upstream MIME types
  * Add extensions for JPEG-2000 images

1.30.0 / 2017-08-27
===================

  * Add `application/vnd.ms-outlook`
  * Add `application/x-arj`
  * Add extension `.mjs` to `application/javascript`
  * Add glTF types and extensions
  * Add new upstream MIME types
  * Add `text/x-org`
  * Add VirtualBox MIME types
  * Fix `source` records for `video/*` types that are IANA
  * Update `font/opentype` to registered `font/otf`

1.29.0 / 2017-07-10
===================

  * Add `application/fido.trusted-apps+json`
  * Add extension `.wadl` to `application/vnd.sun.wadl+xml`
  * Add new upstream MIME types
  * Add `UTF-8` as default charset for `text/css`

1.28.0 / 2017-05-14
===================

  * Add new upstream MIME types
  * Add extension `.gz` to `application/gzip`
  * Update extensions `.md` and `.markdown` to be `text/markdown`

1.27.0 / 2017-03-16
===================

  * Add new upstream MIME types
  * Add `image/apng` with extension `.apng`

1.26.0 / 2017-01-14
===================

  * Add new upstream MIME types
  * Add extension `.geojson` to `application/geo+json`

1.25.0 / 2016-11-11
===================

  * Add new upstream MIME types

1.24.0 / 2016-09-18
===================

  * Add `audio/mp3`
  * Add new upstream MIME types

1.23.0 / 2016-05-01
===================

  * Add new upstream MIME types
  * Add extension `.3gpp` to `audio/3gpp`

1.22.0 / 2016-02-15
===================

  * Add `text/slim`
  * Add extension `.rng` to `application/xml`
  * Add new upstream MIME types
  * Fix extension of `application/dash+xml` to be `.mpd`
  * Update primary extension to `.m4a` for `audio/mp4`

1.21.0 / 2016-01-06
===================

  * Add Google document types
  * Add new upstream MIME types

1.20.0 / 2015-11-10
===================

  * Add `text/x-suse-ymp`
  * Add new upstream MIME types

1.19.0 / 2015-09-17
===================

  * Add `application/vnd.apple.pkpass`
  * Add new upstream MIME types

1.18.0 / 2015-09-03
===================

  * Add new upstream MIME types

1.17.0 / 2015-08-13
===================

  * Add `application/x-msdos-program`
  * Add `audio/g711-0`
  * Add `image/vnd.mozilla.apng`
  * Add extension `.exe` to `application/x-msdos-program`

1.16.0 / 2015-07-29
===================

  * Add `application/vnd.uri-map`

1.15.0 / 2015-07-13
===================

  * Add `application/x-httpd-php`

1.14.0 / 2015-06-25
===================

  * Add `application/scim+json`
  * Add `application/vnd.3gpp.ussd+xml`
  * Add `application/vnd.biopax.rdf+xml`
  * Add `text/x-processing`

1.13.0 / 2015-06-07
===================

  * Add nginx as a source
  * Add `application/x-cocoa`
  * Add `application/x-java-archive-diff`
  * Add `application/x-makeself`
  * Add `application/x-perl`
  * Add `application/x-pilot`
  * Add `application/x-redhat-package-manager`
  * Add `application/x-sea`
  * Add `audio/x-m4a`
  * Add `audio/x-realaudio`
  * Add `image/x-jng`
  * Add `text/mathml`

1.12.0 / 2015-06-05
===================

  * Add `application/bdoc`
  * Add `application/vnd.hyperdrive+json`
  * Add `application/x-bdoc`
  * Add extension `.rtf` to `text/rtf`

1.11.0 / 2015-05-31
===================

  * Add `audio/wav`
  * Add `audio/wave`
  * Add extension `.litcoffee` to `text/coffeescript`
  * Add extension `.sfd-hdstx` to `application/vnd.hydrostatix.sof-data`
  * Add extension `.n-gage` to `application/vnd.nokia.n-gage.symbian.install`

1.10.0 / 2015-05-19
===================

  * Add `application/vnd.balsamiq.bmpr`
  * Add `application/vnd.microsoft.portable-executable`
  * Add `application/x-ns-proxy-autoconfig`

1.9.1 / 2015-04-19
==================

  * Remove `.json` extension from `application/manifest+json`
    - This is causing bugs downstream

1.9.0 / 2015-04-19
==================

  * Add `application/manifest+json`
  * Add `application/vnd.micro+json`
  * Add `image/vnd.zbrush.pcx`
  * Add `image/x-ms-bmp`

1.8.0 / 2015-03-13
==================

  * Add `application/vnd.citationstyles.style+xml`
  * Add `application/vnd.fastcopy-disk-image`
  * Add `application/vnd.gov.sk.xmldatacontainer+xml`
  * Add extension `.jsonld` to `application/ld+json`

1.7.0 / 2015-02-08
==================

  * Add `application/vnd.gerber`
  * Add `application/vnd.msa-disk-image`

1.6.1 / 2015-02-05
==================

  * Community extensions ownership transferred from `node-mime`

1.6.0 / 2015-01-29
==================

  * Add `application/jose`
  * Add `application/jose+json`
  * Add `application/json-seq`
  * Add `application/jwk+json`
  * Add `application/jwk-set+json`
  * Add `application/jwt`
  * Add `application/rdap+json`
  * Add `application/vnd.gov.sk.e-form+xml`
  * Add `application/vnd.ims.imsccv1p3`

1.5.0 / 2014-12-30
==================

  * Add `application/vnd.oracle.resource+json`
  * Fix various invalid MIME type entries
    - `application/mbox+xml`
    - `application/oscp-response`
    - `application/vwg-multiplexed`
    - `audio/g721`

1.4.0 / 2014-12-21
==================

  * Add `application/vnd.ims.imsccv1p2`
  * Fix various invalid MIME type entries
    - `application/vnd-acucobol`
    - `application/vnd-curl`
    - `application/vnd-dart`
    - `application/vnd-dxr`
    - `application/vnd-fdf`
    - `application/vnd-mif`
    - `application/vnd-sema`
    - `application/vnd-wap-wmlc`
    - `application/vnd.adobe.flash-movie`
    - `application/vnd.dece-zip`
    - `application/vnd.dvb_service`
    - `application/vnd.micrografx-igx`
    - `application/vnd.sealed-doc`
    - `application/vnd.sealed-eml`
    - `application/vnd.sealed-mht`
    - `application/vnd.sealed-ppt`
    - `application/vnd.sealed-tiff`
    - `application/vnd.sealed-xls`
    - `application/vnd.sealedmedia.softseal-html`
    - `application/vnd.sealedmedia.softseal-pdf`
    - `application/vnd.wap-slc`
    - `application/vnd.wap-wbxml`
    - `audio/vnd.sealedmedia.softseal-mpeg`
    - `image/vnd-djvu`
    - `image/vnd-svf`
    - `image/vnd-wap-wbmp`
    - `image/vnd.sealed-png`
    - `image/vnd.sealedmedia.softseal-gif`
    - `image/vnd.sealedmedia.softseal-jpg`
    - `model/vnd-dwf`
    - `model/vnd.parasolid.transmit-binary`
    - `model/vnd.parasolid.transmit-text`
    - `text/vnd-a`
    - `text/vnd-curl`
    - `text/vnd.wap-wml`
  * Remove example template MIME types
    - `application/example`
    - `audio/example`
    - `image/example`
    - `message/example`
    - `model/example`
    - `multipart/example`
    - `text/example`
    - `video/example`

1.3.1 / 2014-12-16
==================

  * Fix missing extensions
    - `application/json5`
    - `text/hjson`

1.3.0 / 2014-12-07
==================

  * Add `application/a2l`
  * Add `application/aml`
  * Add `application/atfx`
  * Add `application/atxml`
  * Add `application/cdfx+xml`
  * Add `application/dii`
  * Add `application/json5`
  * Add `application/lxf`
  * Add `application/mf4`
  * Add `application/vnd.apache.thrift.compact`
  * Add `application/vnd.apache.thrift.json`
  * Add `application/vnd.coffeescript`
  * Add `application/vnd.enphase.envoy`
  * Add `application/vnd.ims.imsccv1p1`
  * Add `text/csv-schema`
  * Add `text/hjson`
  * Add `text/markdown`
  * Add `text/yaml`

1.2.0 / 2014-11-09
==================

  * Add `application/cea`
  * Add `application/dit`
  * Add `application/vnd.gov.sk.e-form+zip`
  * Add `application/vnd.tmd.mediaflex.api+xml`
  * Type `application/epub+zip` is now IANA-registered

1.1.2 / 2014-10-23
==================

  * Rebuild database for `application/x-www-form-urlencoded` change

1.1.1 / 2014-10-20
==================

  * Mark `application/x-www-form-urlencoded` as compressible.

1.1.0 / 2014-09-28
==================

  * Add `application/font-woff2`

1.0.3 / 2014-09-25
==================

  * Fix engine requirement in package

1.0.2 / 2014-09-25
==================

  * Add `application/coap-group+json`
  * Add `application/dcd`
  * Add `application/vnd.apache.thrift.binary`
  * Add `image/vnd.tencent.tap`
  * Mark all JSON-derived types as compressible
  * Update `text/vtt` data

1.0.1 / 2014-08-30
==================

  * Fix extension ordering

1.0.0 / 2014-08-30
==================

  * Add `application/atf`
  * Add `application/merge-patch+json`
  * Add `multipart/x-mixed-replace`
  * Add `source: 'apache'` metadata
  * Add `source: 'iana'` metadata
  * Remove badly-assumed charset data


---

# mime-db

[![NPM Version][npm-version-image]][npm-url]
[![NPM Downloads][npm-downloads-image]][npm-url]
[![Node.js Version][node-image]][node-url]
[![Build Status][ci-image]][ci-url]
[![Coverage Status][coveralls-image]][coveralls-url]

This is a large database of mime types and information about them.
It consists of a single, public JSON file and does not include any logic,
allowing it to remain as un-opinionated as possible with an API.
It aggregates data from the following sources:

- http://www.iana.org/assignments/media-types/media-types.xhtml
- http://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/conf/mime.types
- http://hg.nginx.org/nginx/raw-file/default/conf/mime.types

## Installation

```bash
npm install mime-db
```

### Database Download

If you're crazy enough to use this in the browser, you can just grab the
JSON file using [jsDelivr](https://www.jsdelivr.com/). It is recommended to
replace `master` with [a release tag](https://github.com/jshttp/mime-db/tags)
as the JSON format may change in the future.

```
https://cdn.jsdelivr.net/gh/jshttp/mime-db@master/db.json
```

## Usage

```js
var db = require('mime-db')

// grab data on .js files
var data = db['application/javascript']
```

## Data Structure

The JSON file is a map lookup for lowercased mime types.
Each mime type has the following properties:

- `.source` - where the mime type is defined.
    If not set, it's probably a custom media type.
    - `apache` - [Apache common media types](http://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/conf/mime.types)
    - `iana` - [IANA-defined media types](http://www.iana.org/assignments/media-types/media-types.xhtml)
    - `nginx` - [nginx media types](http://hg.nginx.org/nginx/raw-file/default/conf/mime.types)
- `.extensions[]` - known extensions associated with this mime type.
- `.compressible` - whether a file of this type can be gzipped.
- `.charset` - the default charset associated with this type, if any.

If unknown, every property could be `undefined`.

## Contributing

To edit the database, only make PRs against `src/custom-types.json` or
`src/custom-suffix.json`.

The `src/custom-types.json` file is a JSON object with the MIME type as the
keys and the values being an object with the following keys:

- `compressible` - leave out if you don't know, otherwise `true`/`false` to
  indicate whether the data represented by the type is typically compressible.
- `extensions` - include an array of file extensions that are associated with
  the type.
- `notes` - human-readable notes about the type, typically what the type is.
- `sources` - include an array of URLs of where the MIME type and the associated
  extensions are sourced from. This needs to be a [primary source](https://en.wikipedia.org/wiki/Primary_source);
  links to type aggregating sites and Wikipedia are _not acceptable_.

To update the build, run `npm run build`.

### Adding Custom Media Types

The best way to get new media types included in this library is to register
them with the IANA. The community registration procedure is outlined in
[RFC 6838 section 5](http://tools.ietf.org/html/rfc6838#section-5). Types
registered with the IANA are automatically pulled into this library.

If that is not possible / feasible, they can be added directly here as a
"custom" type. To do this, it is required to have a primary source that
definitively lists the media type. If an extension is going to be listed as
associateed with this media type, the source must definitively link the
media type and extension as well.

[ci-image]: https://badgen.net/github/checks/jshttp/mime-db/master?label=ci
[ci-url]: https://github.com/jshttp/mime-db/actions?query=workflow%3Aci
[coveralls-image]: https://badgen.net/coveralls/c/github/jshttp/mime-db/master
[coveralls-url]: https://coveralls.io/r/jshttp/mime-db?branch=master
[node-image]: https://badgen.net/npm/node/mime-db
[node-url]: https://nodejs.org/en/download
[npm-downloads-image]: https://badgen.net/npm/dm/mime-db
[npm-url]: https://npmjs.org/package/mime-db
[npm-version-image]: https://badgen.net/npm/v/mime-db


---

2.1.35 / 2022-03-12
===================

  * deps: mime-db@1.52.0
    - Add extensions from IANA for more `image/*` types
    - Add extension `.asc` to `application/pgp-keys`
    - Add extensions to various XML types
    - Add new upstream MIME types

2.1.34 / 2021-11-08
===================

  * deps: mime-db@1.51.0
    - Add new upstream MIME types

2.1.33 / 2021-10-01
===================

  * deps: mime-db@1.50.0
    - Add deprecated iWorks mime types and extensions
    - Add new upstream MIME types

2.1.32 / 2021-07-27
===================

  * deps: mime-db@1.49.0
    - Add extension `.trig` to `application/trig`
    - Add new upstream MIME types

2.1.31 / 2021-06-01
===================

  * deps: mime-db@1.48.0
    - Add extension `.mvt` to `application/vnd.mapbox-vector-tile`
    - Add new upstream MIME types

2.1.30 / 2021-04-02
===================

  * deps: mime-db@1.47.0
    - Add extension `.amr` to `audio/amr`
    - Remove ambigious extensions from IANA for `application/*+xml` types
    - Update primary extension to `.es` for `application/ecmascript`

2.1.29 / 2021-02-17
===================

  * deps: mime-db@1.46.0
    - Add extension `.amr` to `audio/amr`
    - Add extension `.m4s` to `video/iso.segment`
    - Add extension `.opus` to `audio/ogg`
    - Add new upstream MIME types

2.1.28 / 2021-01-01
===================

  * deps: mime-db@1.45.0
    - Add `application/ubjson` with extension `.ubj`
    - Add `image/avif` with extension `.avif`
    - Add `image/ktx2` with extension `.ktx2`
    - Add extension `.dbf` to `application/vnd.dbf`
    - Add extension `.rar` to `application/vnd.rar`
    - Add extension `.td` to `application/urc-targetdesc+xml`
    - Add new upstream MIME types
    - Fix extension of `application/vnd.apple.keynote` to be `.key`

2.1.27 / 2020-04-23
===================

  * deps: mime-db@1.44.0
    - Add charsets from IANA
    - Add extension `.cjs` to `application/node`
    - Add new upstream MIME types

2.1.26 / 2020-01-05
===================

  * deps: mime-db@1.43.0
    - Add `application/x-keepass2` with extension `.kdbx`
    - Add extension `.mxmf` to `audio/mobile-xmf`
    - Add extensions from IANA for `application/*+xml` types
    - Add new upstream MIME types

2.1.25 / 2019-11-12
===================

  * deps: mime-db@1.42.0
    - Add new upstream MIME types
    - Add `application/toml` with extension `.toml`
    - Add `image/vnd.ms-dds` with extension `.dds`

2.1.24 / 2019-04-20
===================

  * deps: mime-db@1.40.0
    - Add extensions from IANA for `model/*` types
    - Add `text/mdx` with extension `.mdx`

2.1.23 / 2019-04-17
===================

  * deps: mime-db@~1.39.0
    - Add extensions `.siv` and `.sieve` to `application/sieve`
    - Add new upstream MIME types

2.1.22 / 2019-02-14
===================

  * deps: mime-db@~1.38.0
    - Add extension `.nq` to `application/n-quads`
    - Add extension `.nt` to `application/n-triples`
    - Add new upstream MIME types

2.1.21 / 2018-10-19
===================

  * deps: mime-db@~1.37.0
    - Add extensions to HEIC image types
    - Add new upstream MIME types

2.1.20 / 2018-08-26
===================

  * deps: mime-db@~1.36.0
    - Add Apple file extensions from IANA
    - Add extensions from IANA for `image/*` types
    - Add new upstream MIME types

2.1.19 / 2018-07-17
===================

  * deps: mime-db@~1.35.0
    - Add extension `.csl` to `application/vnd.citationstyles.style+xml`
    - Add extension `.es` to `application/ecmascript`
    - Add extension `.owl` to `application/rdf+xml`
    - Add new upstream MIME types
    - Add UTF-8 as default charset for `text/turtle`

2.1.18 / 2018-02-16
===================

  * deps: mime-db@~1.33.0
    - Add `application/raml+yaml` with extension `.raml`
    - Add `application/wasm` with extension `.wasm`
    - Add `text/shex` with extension `.shex`
    - Add extensions for JPEG-2000 images
    - Add extensions from IANA for `message/*` types
    - Add new upstream MIME types
    - Update font MIME types
    - Update `text/hjson` to registered `application/hjson`

2.1.17 / 2017-09-01
===================

  * deps: mime-db@~1.30.0
    - Add `application/vnd.ms-outlook`
    - Add `application/x-arj`
    - Add extension `.mjs` to `application/javascript`
    - Add glTF types and extensions
    - Add new upstream MIME types
    - Add `text/x-org`
    - Add VirtualBox MIME types
    - Fix `source` records for `video/*` types that are IANA
    - Update `font/opentype` to registered `font/otf`

2.1.16 / 2017-07-24
===================

  * deps: mime-db@~1.29.0
    - Add `application/fido.trusted-apps+json`
    - Add extension `.wadl` to `application/vnd.sun.wadl+xml`
    - Add extension `.gz` to `application/gzip`
    - Add new upstream MIME types
    - Update extensions `.md` and `.markdown` to be `text/markdown`

2.1.15 / 2017-03-23
===================

  * deps: mime-db@~1.27.0
    - Add new mime types
    - Add `image/apng`

2.1.14 / 2017-01-14
===================

  * deps: mime-db@~1.26.0
    - Add new mime types

2.1.13 / 2016-11-18
===================

  * deps: mime-db@~1.25.0
    - Add new mime types

2.1.12 / 2016-09-18
===================

  * deps: mime-db@~1.24.0
    - Add new mime types
    - Add `audio/mp3`

2.1.11 / 2016-05-01
===================

  * deps: mime-db@~1.23.0
    - Add new mime types

2.1.10 / 2016-02-15
===================

  * deps: mime-db@~1.22.0
    - Add new mime types
    - Fix extension of `application/dash+xml`
    - Update primary extension for `audio/mp4`

2.1.9 / 2016-01-06
==================

  * deps: mime-db@~1.21.0
    - Add new mime types

2.1.8 / 2015-11-30
==================

  * deps: mime-db@~1.20.0
    - Add new mime types

2.1.7 / 2015-09-20
==================

  * deps: mime-db@~1.19.0
    - Add new mime types

2.1.6 / 2015-09-03
==================

  * deps: mime-db@~1.18.0
    - Add new mime types

2.1.5 / 2015-08-20
==================

  * deps: mime-db@~1.17.0
    - Add new mime types

2.1.4 / 2015-07-30
==================

  * deps: mime-db@~1.16.0
    - Add new mime types

2.1.3 / 2015-07-13
==================

  * deps: mime-db@~1.15.0
    - Add new mime types

2.1.2 / 2015-06-25
==================

  * deps: mime-db@~1.14.0
    - Add new mime types

2.1.1 / 2015-06-08
==================

  * perf: fix deopt during mapping

2.1.0 / 2015-06-07
==================

  * Fix incorrectly treating extension-less file name as extension
    - i.e. `'path/to/json'` will no longer return `application/json`
  * Fix `.charset(type)` to accept parameters
  * Fix `.charset(type)` to match case-insensitive
  * Improve generation of extension to MIME mapping
  * Refactor internals for readability and no argument reassignment
  * Prefer `application/*` MIME types from the same source
  * Prefer any type over `application/octet-stream`
  * deps: mime-db@~1.13.0
    - Add nginx as a source
    - Add new mime types

2.0.14 / 2015-06-06
===================

  * deps: mime-db@~1.12.0
    - Add new mime types

2.0.13 / 2015-05-31
===================

  * deps: mime-db@~1.11.0
    - Add new mime types

2.0.12 / 2015-05-19
===================

  * deps: mime-db@~1.10.0
    - Add new mime types

2.0.11 / 2015-05-05
===================

  * deps: mime-db@~1.9.1
    - Add new mime types

2.0.10 / 2015-03-13
===================

  * deps: mime-db@~1.8.0
    - Add new mime types

2.0.9 / 2015-02-09
==================

  * deps: mime-db@~1.7.0
    - Add new mime types
    - Community extensions ownership transferred from `node-mime`

2.0.8 / 2015-01-29
==================

  * deps: mime-db@~1.6.0
    - Add new mime types

2.0.7 / 2014-12-30
==================

  * deps: mime-db@~1.5.0
    - Add new mime types
    - Fix various invalid MIME type entries

2.0.6 / 2014-12-30
==================

  * deps: mime-db@~1.4.0
    - Add new mime types
    - Fix various invalid MIME type entries
    - Remove example template MIME types

2.0.5 / 2014-12-29
==================

  * deps: mime-db@~1.3.1
    - Fix missing extensions

2.0.4 / 2014-12-10
==================

  * deps: mime-db@~1.3.0
    - Add new mime types

2.0.3 / 2014-11-09
==================

  * deps: mime-db@~1.2.0
    - Add new mime types

2.0.2 / 2014-09-28
==================

  * deps: mime-db@~1.1.0
    - Add new mime types
    - Update charsets

2.0.1 / 2014-09-07
==================

  * Support Node.js 0.6

2.0.0 / 2014-09-02
==================

  * Use `mime-db`
  * Remove `.define()`

1.0.2 / 2014-08-04
==================

  * Set charset=utf-8 for `text/javascript`

1.0.1 / 2014-06-24
==================

  * Add `text/jsx` type

1.0.0 / 2014-05-12
==================

  * Return `false` for unknown types
  * Set charset=utf-8 for `application/json`

0.1.0 / 2014-05-02
==================

  * Initial release


---

# mime-types

[![NPM Version][npm-version-image]][npm-url]
[![NPM Downloads][npm-downloads-image]][npm-url]
[![Node.js Version][node-version-image]][node-version-url]
[![Build Status][ci-image]][ci-url]
[![Test Coverage][coveralls-image]][coveralls-url]

The ultimate javascript content-type utility.

Similar to [the `mime@1.x` module](https://www.npmjs.com/package/mime), except:

- __No fallbacks.__ Instead of naively returning the first available type,
  `mime-types` simply returns `false`, so do
  `var type = mime.lookup('unrecognized') || 'application/octet-stream'`.
- No `new Mime()` business, so you could do `var lookup = require('mime-types').lookup`.
- No `.define()` functionality
- Bug fixes for `.lookup(path)`

Otherwise, the API is compatible with `mime` 1.x.

## Install

This is a [Node.js](https://nodejs.org/en/) module available through the
[npm registry](https://www.npmjs.com/). Installation is done using the
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):

```sh
$ npm install mime-types
```

## Adding Types

All mime types are based on [mime-db](https://www.npmjs.com/package/mime-db),
so open a PR there if you'd like to add mime types.

## API

```js
var mime = require('mime-types')
```

All functions return `false` if input is invalid or not found.

### mime.lookup(path)

Lookup the content-type associated with a file.

```js
mime.lookup('json') // 'application/json'
mime.lookup('.md') // 'text/markdown'
mime.lookup('file.html') // 'text/html'
mime.lookup('folder/file.js') // 'application/javascript'
mime.lookup('folder/.htaccess') // false

mime.lookup('cats') // false
```

### mime.contentType(type)

Create a full content-type header given a content-type or extension.
When given an extension, `mime.lookup` is used to get the matching
content-type, otherwise the given content-type is used. Then if the
content-type does not already have a `charset` parameter, `mime.charset`
is used to get the default charset and add to the returned content-type.

```js
mime.contentType('markdown') // 'text/x-markdown; charset=utf-8'
mime.contentType('file.json') // 'application/json; charset=utf-8'
mime.contentType('text/html') // 'text/html; charset=utf-8'
mime.contentType('text/html; charset=iso-8859-1') // 'text/html; charset=iso-8859-1'

// from a full path
mime.contentType(path.extname('/path/to/file.json')) // 'application/json; charset=utf-8'
```

### mime.extension(type)

Get the default extension for a content-type.

```js
mime.extension('application/octet-stream') // 'bin'
```

### mime.charset(type)

Lookup the implied default charset of a content-type.

```js
mime.charset('text/markdown') // 'UTF-8'
```

### var type = mime.types[extension]

A map of content-types by extension.

### [extensions...] = mime.extensions[type]

A map of extensions by content-type.

## License

[MIT](LICENSE)

[ci-image]: https://badgen.net/github/checks/jshttp/mime-types/master?label=ci
[ci-url]: https://github.com/jshttp/mime-types/actions/workflows/ci.yml
[coveralls-image]: https://badgen.net/coveralls/c/github/jshttp/mime-types/master
[coveralls-url]: https://coveralls.io/r/jshttp/mime-types?branch=master
[node-version-image]: https://badgen.net/npm/node/mime-types
[node-version-url]: https://nodejs.org/en/download
[npm-downloads-image]: https://badgen.net/npm/dm/mime-types
[npm-url]: https://npmjs.org/package/mime-types
[npm-version-image]: https://badgen.net/npm/v/mime-types


---

[![npm][npm]][npm-url]
[![node][node]][node-url]
[![tests][tests]][tests-url]
[![downloads][downloads]][downloads-url]

<div align="center">
  <a href="https://github.com/webpack/webpack">
    <img width="200" height="200"
      src="https://webpack.js.org/assets/icon-square-big.svg">
  </a>
  <h1>Webpack Bundle Analyzer</h1>
  <p>Visualize size of webpack output files with an interactive zoomable treemap.</p>
</div>

<h2 align="center">Install</h2>

```bash
# NPM
npm install --save-dev webpack-bundle-analyzer
# Yarn
yarn add -D webpack-bundle-analyzer
```

<h2 align="center">Usage (as a plugin)</h2>

```js
const BundleAnalyzerPlugin = require('webpack-bundle-analyzer').BundleAnalyzerPlugin;

module.exports = {
  plugins: [
    new BundleAnalyzerPlugin()
  ]
}
```

It will create an interactive treemap visualization of the contents of all your bundles.

![webpack bundle analyzer zoomable treemap](https://cloud.githubusercontent.com/assets/302213/20628702/93f72404-b338-11e6-92d4-9a365550a701.gif)

This module will help you:

1. Realize what's *really* inside your bundle
2. Find out what modules make up the most of its size
3. Find modules that got there by mistake
4. Optimize it!

And the best thing is it supports minified bundles! It parses them to get real size of bundled modules.
And it also shows their gzipped sizes!

<h2 align="center">Options (for plugin)</h2>

```js
new BundleAnalyzerPlugin(options?: object)
```

|Name|Type|Description|
|:--:|:--:|:----------|
|**`analyzerMode`**|One of: `server`, `static`, `json`, `disabled`|Default: `server`. In `server` mode analyzer will start HTTP server to show bundle report. In `static` mode single HTML file with bundle report will be generated. In `json` mode single JSON file with bundle report will be generated. In `disabled` mode you can use this plugin to just generate Webpack Stats JSON file by setting `generateStatsFile` to `true`. |
|**`analyzerHost`**|`{String}`|Default: `127.0.0.1`. Host that will be used in `server` mode to start HTTP server.|
|**`analyzerPort`**|`{Number}` or `auto`|Default: `8888`. Port that will be used in `server` mode to start HTTP server. If `analyzerPort` is `auto`, the operating system will assign an arbitrary unused port |
|**`analyzerUrl`**|`{Function}` called with `{ listenHost: string, listenHost: string, boundAddress: server.address}`. [server.address comes from Node.js](https://nodejs.org/api/net.html#serveraddress)| Default: `http://${listenHost}:${boundAddress.port}`. The URL printed to console with server mode.|
|**`reportFilename`**|`{String}`|Default: `report.html`. Path to bundle report file that will be generated in `static` mode. It can be either an absolute path or a path relative to a bundle output directory (which is output.path in webpack config).|
|**`reportTitle`**|`{String\|function}`|Default: function that returns pretty printed current date and time. Content of the HTML `title` element; or a function of the form `() => string` that provides the content.|
|**`defaultSizes`**|One of: `stat`, `parsed`, `gzip`|Default: `parsed`. Module sizes to show in report by default. [Size definitions](#size-definitions) section describes what these values mean.|
|**`openAnalyzer`**|`{Boolean}`|Default: `true`. Automatically open report in default browser.|
|**`generateStatsFile`**|`{Boolean}`|Default: `false`. If `true`, webpack stats JSON file will be generated in bundle output directory|
|**`statsFilename`**|`{String}`|Default: `stats.json`. Name of webpack stats JSON file that will be generated if `generateStatsFile` is `true`. It can be either an absolute path or a path relative to a bundle output directory (which is output.path in webpack config).|
|**`statsOptions`**|`null` or `{Object}`|Default: `null`. Options for `stats.toJson()` method. For example you can exclude sources of your modules from stats file with `source: false` option. [See more options here](https://webpack.js.org/configuration/stats/). |
|**`excludeAssets`**|`{null\|pattern\|pattern[]}` where `pattern` equals to `{String\|RegExp\|function}`|Default: `null`. Patterns that will be used to match against asset names to exclude them from the report. If pattern is a string it will be converted to RegExp via `new RegExp(str)`. If pattern is a function it should have the following signature `(assetName: string) => boolean` and should return `true` to *exclude* matching asset. If multiple patterns are provided asset should match at least one of them to be excluded. |
|**`logLevel`**|One of: `info`, `warn`, `error`, `silent`|Default: `info`. Used to control how much details the plugin outputs.|

<h2 align="center">Usage (as a CLI utility)</h2>

You can analyze an existing bundle if you have a webpack stats JSON file.

You can generate it using `BundleAnalyzerPlugin` with `generateStatsFile` option set to `true` or with this simple
command:

```bash
webpack --profile --json > stats.json
```

If you're on Windows and using PowerShell, you can generate the stats file with this command to [avoid BOM issues](https://github.com/webpack-contrib/webpack-bundle-analyzer/issues/47):

```
webpack --profile --json | Out-file 'stats.json' -Encoding OEM
```

Then you can run the CLI tool.

```
webpack-bundle-analyzer bundle/output/path/stats.json
```

<h2 align="center">Options (for CLI)</h2>

```bash
webpack-bundle-analyzer <bundleStatsFile> [bundleDir] [options]
```

Arguments are documented below:

### `bundleStatsFile`

Path to webpack stats JSON file

### `bundleDir`

Directory containing all generated bundles.

### `options`

```
  -V, --version               output the version number
  -m, --mode <mode>           Analyzer mode. Should be `server`, `static` or `json`.
                              In `server` mode analyzer will start HTTP server to show bundle report.
                              In `static` mode single HTML file with bundle report will be generated.
                              In `json` mode single JSON file with bundle report will be generated. (default: server)
  -h, --host <host>           Host that will be used in `server` mode to start HTTP server. (default: 127.0.0.1)
  -p, --port <n>              Port that will be used in `server` mode to start HTTP server. Should be a number or `auto` (default: 8888)
  -r, --report <file>         Path to bundle report file that will be generated in `static` mode. (default: report.html)
  -t, --title <title>         String to use in title element of html report. (default: pretty printed current date)
  -s, --default-sizes <type>  Module sizes to show in treemap by default.
                              Possible values: stat, parsed, gzip (default: parsed)
  -O, --no-open               Don't open report in default browser automatically.
  -e, --exclude <regexp>      Assets that should be excluded from the report.
                              Can be specified multiple times.
  -l, --log-level <level>     Log level.
                              Possible values: debug, info, warn, error, silent (default: info)
  -h, --help                  output usage information
```

<h2 align="center" id="size-definitions">Size definitions</h2>

webpack-bundle-analyzer reports three values for sizes. `defaultSizes` can be used to control which of these is shown by default. The different reported sizes are:

### `stat`

This is the "input" size of your files, before any transformations like
minification.

It is called "stat size" because it's obtained from Webpack's
[stats object](https://webpack.js.org/configuration/stats/).

### `parsed`

This is the "output" size of your files. If you're using a Webpack plugin such
as Uglify, then this value will reflect the minified size of your code.

### `gzip`

This is the size of running the parsed bundles/modules through gzip compression.

<h2 align="center">Selecting Which Chunks to Display</h2>

When opened, the report displays all of the Webpack chunks for your project. It's possible to filter to a more specific list of chunks by using the sidebar or the chunk context menu.

### Sidebar

The Sidebar Menu can be opened by clicking the `>` button at the top left of the report. You can select or deselect chunks to display under the "Show chunks" heading there.

### Chunk Context Menu

The Chunk Context Menu can be opened by right-clicking or `Ctrl`-clicking on a specific chunk in the report. It provides the following options:

 * **Hide chunk:** Hides the selected chunk
 * **Hide all other chunks:** Hides all chunks besides the selected one
 * **Show all chunks:** Un-hides any hidden chunks, returning the report to its initial, unfiltered view

<h2 align="center">Troubleshooting</h2>

### I don't see `gzip` or `parsed` sizes, it only shows `stat` size

It happens when `webpack-bundle-analyzer` analyzes files that don't actually exist in your file system, for example when you work with `webpack-dev-server` that keeps all the files in RAM. If you use `webpack-bundle-analyzer` as a plugin you won't get any errors, however if you run it via CLI you get the error message in terminal:
```
Error parsing bundle asset "your_bundle_name.bundle.js": no such file
No bundles were parsed. Analyzer will show only original module sizes from stats file.
```
To get more information about it you can read [issue #147](https://github.com/webpack-contrib/webpack-bundle-analyzer/issues/147).

<h2 align="center">Other tools</h2>

- [Statoscope](https://github.com/smelukov/statoscope/blob/master/packages/ui-webpack/README.md) - Webpack bundle analyzing tool to find out why a certain module was bundled (and more features, including interactive treemap)

<h2 align="center">Maintainers</h2>

<table>
  <tbody>
    <tr>
      <td align="center">
        <img width="150" height="150"
        src="https://avatars3.githubusercontent.com/u/302213?v=4&s=150">
        </br>
        <a href="https://github.com/th0r">Yuriy Grunin</a>
      </td>
      <td align="center">
        <img width="150" height="150"
        src="https://avatars3.githubusercontent.com/u/482561?v=4&s=150">
        </br>
        <a href="https://github.com/valscion">Vesa Laakso</a>
      </td>
    </tr>
  <tbody>
</table>


[npm]: https://img.shields.io/npm/v/webpack-bundle-analyzer.svg
[npm-url]: https://npmjs.com/package/webpack-bundle-analyzer

[node]: https://img.shields.io/node/v/webpack-bundle-analyzer.svg
[node-url]: https://nodejs.org

[tests]: http://img.shields.io/travis/webpack-contrib/webpack-bundle-analyzer.svg
[tests-url]: https://travis-ci.org/webpack-contrib/webpack-bundle-analyzer

[downloads]: https://img.shields.io/npm/dt/webpack-bundle-analyzer.svg
[downloads-url]: https://npmjs.com/package/webpack-bundle-analyzer

<h2 align="center">Contributing</h2>

Check out [CONTRIBUTING.md](./CONTRIBUTING.md) for instructions on contributing :tada:


---

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html). (Format adopted after v3.0.0.)

<!-- markdownlint-disable MD024 -->
<!-- markdownlint-disable MD004 -->

## [7.2.0] (2021-03-26)

### Added

- TypeScript typing for `parent` property on `Command` ([#1475])
- TypeScript typing for `.attributeName()` on `Option` ([#1483])
- support information in package ([#1477])

### Changed

- improvements to error messages, README, and tests
- update dependencies

## [7.1.0] (2021-02-15)

### Added

- support for named imports from ECMAScript modules ([#1440])
- add `.cjs` to list of expected script file extensions ([#1449])
- allow using option choices and variadic together ([#1454])

### Fixed

- replace use of deprecated `process.mainModule` ([#1448])
- regression for legacy `command('*')` and call when command line includes options ([#1464])
- regression for `on('command:*', ...)` and call when command line includes unknown options ([#1464])
- display best error for combination of unknown command and unknown option (i.e. unknown command) ([#1464])

### Changed

- make TypeScript typings tests stricter ([#1453])
- improvements to README and tests

## [7.0.0] (2021-01-15)

### Added

- `.enablePositionalOptions()` to let program and subcommand reuse same option ([#1427])
- `.passThroughOptions()` to pass options through to other programs without needing `--` ([#1427])
- `.allowExcessArguments(false)` to show an error message if there are too many command-arguments on command line for the action handler ([#1409])
- `.configureOutput()` to modify use of stdout and stderr or customise display of errors ([#1387])
- use `.addHelpText()` to add text before or after the built-in help, for just current command or also for all subcommands ([#1296])
- enhance Option class ([#1331])
  - allow hiding options from help
  - allow restricting option arguments to a list of choices
  - allow setting how default value is shown in help
- `.createOption()` to support subclassing of automatically created options (like `.createCommand()`) ([#1380])
- refactor the code generating the help into a separate public Help class ([#1365])
  - support sorting subcommands and options in help
  - support specifying wrap width (columns)
  - allow subclassing Help class
  - allow configuring Help class without subclassing

### Changed

- *Breaking:* options are stored safely by default, not as properties on the command ([#1409])
    - this especially affects accessing options on program, use `program.opts()`
    - revert behaviour with `.storeOptionsAsProperties()`
- *Breaking:* action handlers are passed options and command separately ([#1409])
- deprecated callback parameter to `.help()` and `.outputHelp()` (removed from README) ([#1296])
- *Breaking:* errors now displayed using `process.stderr.write()` instead of `console.error()`
- deprecate `.on('--help')` (removed from README) ([#1296])
- initialise the command description to empty string (previously undefined) ([#1365])
- document and annotate deprecated routines ([#1349])

### Fixed

- wrapping bugs in help ([#1365])
  - first line of command description was wrapping two characters early
  - pad width calculation was not including help option and help command
  - pad width calculation was including hidden options and commands
- improve backwards compatibility for custom command event listeners ([#1403])
  
### Deleted

- *Breaking:* `.passCommandToAction()` ([#1409])
    - no longer needed as action handler is passed options and command
- *Breaking:* "extra arguments" parameter to action handler ([#1409])
    - if being used to detect excess arguments, there is now an error available by setting `.allowExcessArguments(false)`

### Migration Tips

The biggest change is the parsed option values. Previously the options were stored by default as properties on the command object, and now the options are stored separately.

If you wish to restore the old behaviour and get running quickly you can call `.storeOptionsAsProperties()`. 
To allow you to move to the new code patterns incrementally, the action handler will be passed the command _twice_,
to match the new "options" and "command" parameters (see below).

**program options**

Use the `.opts()` method to access the options. This is available on any command but is used most with the program.

```js
program.option('-d, --debug');
program.parse();
// Old code before Commander 7
if (program.debug) console.log(`Program name is ${program.name()}`);
```

```js
// New code
const options = program.opts();
if (options.debug) console.log(`Program name is ${program.name()}`);
```

**action handler**

The action handler gets passed a parameter for each command-argument you declared. Previously by default the next parameter was the command object with the options as properties. Now the next two parameters are instead the options and the command. If you
only accessed the options there may be no code changes required.

```js
program
  .command('compress <filename>')
  .option('-t, --trace')
  // Old code before Commander 7
  .action((filename, cmd)) => {
    if (cmd.trace) console.log(`Command name is ${cmd.name()}`);
  });
```

```js
  // New code
  .action((filename, options, command)) => {
    if (options.trace) console.log(`Command name is ${command.name()}`);
  });
```

If you already set `.storeOptionsAsProperties(false)` you may still need to adjust your code.

```js
program
  .command('compress <filename>')
  .storeOptionsAsProperties(false)
  .option('-t, --trace')
  // Old code before Commander 7
  .action((filename, command)) => {
    if (command.opts().trace) console.log(`Command name is ${command.name()}`);
  });
```

```js
   // New code
   .action((filename, options, command)) => {
      if (command.opts().trace) console.log(`Command name is ${command.name()}`);
   });
```

## [7.0.0-2] (2020-12-14)

(Released in 7.0.0)

## [7.0.0-1] (2020-11-21)

(Released in 7.0.0)

## [7.0.0-0] (2020-10-25)

(Released in 7.0.0)

## [6.2.1] (2020-12-13)

### Fixed

- some tests failed if directory path included a space ([1390])

## [6.2.0] (2020-10-25)

### Added

- added 'tsx' file extension for stand-alone executable subcommands ([#1368])
- documented second parameter to `.description()` to describe command arguments ([#1353])
- documentation of special cases with options taking varying numbers of option-arguments ([#1332])
- documentation for terminology ([#1361])
  
### Fixed

- add missing TypeScript definition for `.addHelpCommand()' ([#1375])
- removed blank line after "Arguments:" in help, to match "Options:" and "Commands:" ([#1360])

### Changed

- update dependencies

## [6.1.0] (2020-08-28)

### Added

- include URL to relevant section of README for error for potential conflict between Command properties and option values ([#1306])
- `.combineFlagAndOptionalValue(false)` to ease upgrade path from older versions of Commander ([#1326])
- allow disabling the built-in help option using `.helpOption(false)` ([#1325])
- allow just some arguments in `argumentDescription` to `.description()` ([#1323])

### Changed

- tidy async test and remove lint override ([#1312])

### Fixed

- executable subcommand launching when script path not known ([#1322])

## [6.0.0] (2020-07-21)

### Added

- add support for variadic options ([#1250])
- allow options to be added with just a short flag ([#1256])
  - *Breaking* the option property has same case as flag. e.g. flag `-n` accessed as `opts().n` (previously uppercase)
- *Breaking* throw an error if there might be a clash between option name and a Command property, with advice on how to resolve ([#1275])

### Fixed

- Options which contain -no- in the middle of the option flag should not be treated as negatable. ([#1301])

## [6.0.0-0] (2020-06-20)

(Released in 6.0.0)

## [5.1.0] (2020-04-25)

### Added

- support for multiple command aliases, the first of which is shown in the auto-generated help ([#531], [#1236])
- configuration support in `addCommand()` for `hidden` and `isDefault` ([#1232])

### Fixed

- omit masked help flags from the displayed help ([#645], [#1247])
- remove old short help flag when change help flags using `helpOption` ([#1248])

### Changed

- remove use of `arguments` to improve auto-generated help in editors ([#1235])
- rename `.command()` configuration `noHelp` to `hidden` (but not remove old support) ([#1232])
- improvements to documentation
- update dependencies
- update tested versions of node
- eliminate lint errors in TypeScript ([#1208])

## [5.0.0] (2020-03-14)

### Added

* support for nested commands with action-handlers ([#1] [#764] [#1149])
* `.addCommand()` for adding a separately configured command ([#764] [#1149])
* allow a non-executable to be set as the default command ([#742] [#1149])
* implicit help command when there are subcommands (previously only if executables) ([#1149])
* customise implicit help command with `.addHelpCommand()` ([#1149])
* display error message for unknown subcommand, by default ([#432] [#1088] [#1149])
* display help for missing subcommand, by default ([#1088] [#1149])
* combined short options as single argument may include boolean flags and value flag and value (e.g. `-a -b -p 80` can be written as `-abp80`) ([#1145])
* `.parseOption()` includes short flag and long flag expansions ([#1145])
* `.helpInformation()` returns help text as a string, previously a private routine ([#1169])
* `.parse()` implicitly uses `process.argv` if arguments not specified ([#1172])
* optionally specify where `.parse()` arguments "from", if not following node conventions ([#512] [#1172])
* suggest help option along with unknown command error ([#1179])
* TypeScript definition for `commands` property of `Command` ([#1184])
* export `program` property ([#1195])
* `createCommand` factory method to simplify subclassing ([#1191])

### Fixed

* preserve argument order in subcommands ([#508] [#962] [#1138])
* do not emit `command:*` for executable subcommands ([#809] [#1149])
* action handler called whether or not there are non-option arguments ([#1062] [#1149])
* combining option short flag and value in single argument now works for subcommands ([#1145])
* only add implicit help command when it will not conflict with other uses of argument ([#1153] [#1149])
* implicit help command works with command aliases ([#948] [#1149])
* options are validated whether or not there is an action handler ([#1149])

### Changed

* *Breaking* `.args` contains command arguments with just recognised options removed ([#1032] [#1138])
* *Breaking* display error if required argument for command is missing ([#995] [#1149])
* tighten TypeScript definition of custom option processing function passed to `.option()` ([#1119])
* *Breaking* `.allowUnknownOption()` ([#802] [#1138])
  * unknown options included in arguments passed to command action handler
  * unknown options included in `.args`
* only recognised option short flags and long flags are expanded (e.g. `-ab` or `--foo=bar`) ([#1145])
* *Breaking* `.parseOptions()` ([#1138])
  * `args` in returned result renamed `operands` and does not include anything after first unknown option
  * `unknown` in returned result has arguments after first unknown option including operands, not just options and values
* *Breaking* `.on('command:*', callback)` and other command events passed (changed) results from `.parseOptions`, i.e. operands and unknown  ([#1138])
* refactor Option from prototype to class ([#1133])
* refactor Command from prototype to class ([#1159])
* changes to error handling ([#1165])
  * throw for author error, not just display message
  * preflight for variadic error
  * add tips to missing subcommand executable
* TypeScript fluent return types changed to be more subclass friendly, return `this` rather than `Command` ([#1180])
* `.parseAsync` returns `Promise<this>` to be consistent with `.parse()` ([#1180])
* update dependencies

### Removed

* removed EventEmitter from TypeScript definition for Command, eliminating implicit peer dependency on `@types/node` ([#1146])
* removed private function `normalize` (the functionality has been integrated into `parseOptions`) ([#1145])
* `parseExpectedArgs` is now private ([#1149])

### Migration Tips

If you use `.on('command:*')` or more complicated tests to detect an unrecognised subcommand, you may be able to delete the code and rely on the default behaviour.

If you use `program.args` or more complicated tests to detect a missing subcommand, you may be able to delete the code and rely on the default behaviour.

If you use `.command('*')` to add a default command, you may be be able to switch to `isDefault:true` with a named command.

If you want to continue combining short options with optional values as though they were boolean flags, set `combineFlagAndOptionalValue(false)`
to expand `-fb` to `-f -b` rather than `-f b`.

## [5.0.0-4] (2020-03-03)

(Released in 5.0.0)

## [5.0.0-3] (2020-02-20)

(Released in 5.0.0)

## [5.0.0-2] (2020-02-10)

(Released in 5.0.0)

## [5.0.0-1] (2020-02-08)

(Released in 5.0.0)

## [5.0.0-0] (2020-02-02)

(Released in 5.0.0)

## Older versions

* [4.x](./changelogs/CHANGELOG-4.md)
* [3.x](./changelogs/CHANGELOG-3.md)
* [2.x](./changelogs/CHANGELOG-2.md)
* [1.x](./changelogs/CHANGELOG-1.md)
* [0.x](./changelogs/CHANGELOG-0.md)

[#1]: https://github.com/tj/commander.js/issues/1
[#432]: https://github.com/tj/commander.js/issues/432
[#508]: https://github.com/tj/commander.js/issues/508
[#512]: https://github.com/tj/commander.js/issues/512
[#531]: https://github.com/tj/commander.js/issues/531
[#645]: https://github.com/tj/commander.js/issues/645
[#742]: https://github.com/tj/commander.js/issues/742
[#764]: https://github.com/tj/commander.js/issues/764
[#802]: https://github.com/tj/commander.js/issues/802
[#809]: https://github.com/tj/commander.js/issues/809
[#948]: https://github.com/tj/commander.js/issues/948
[#962]: https://github.com/tj/commander.js/issues/962
[#995]: https://github.com/tj/commander.js/issues/995
[#1032]: https://github.com/tj/commander.js/issues/1032
[#1062]: https://github.com/tj/commander.js/pull/1062
[#1088]: https://github.com/tj/commander.js/issues/1088
[#1119]: https://github.com/tj/commander.js/pull/1119
[#1133]: https://github.com/tj/commander.js/pull/1133
[#1138]: https://github.com/tj/commander.js/pull/1138
[#1145]: https://github.com/tj/commander.js/pull/1145
[#1146]: https://github.com/tj/commander.js/pull/1146
[#1149]: https://github.com/tj/commander.js/pull/1149
[#1153]: https://github.com/tj/commander.js/issues/1153
[#1159]: https://github.com/tj/commander.js/pull/1159
[#1165]: https://github.com/tj/commander.js/pull/1165
[#1169]: https://github.com/tj/commander.js/pull/1169
[#1172]: https://github.com/tj/commander.js/pull/1172
[#1179]: https://github.com/tj/commander.js/pull/1179
[#1180]: https://github.com/tj/commander.js/pull/1180
[#1184]: https://github.com/tj/commander.js/pull/1184
[#1191]: https://github.com/tj/commander.js/pull/1191
[#1195]: https://github.com/tj/commander.js/pull/1195
[#1208]: https://github.com/tj/commander.js/pull/1208
[#1232]: https://github.com/tj/commander.js/pull/1232
[#1235]: https://github.com/tj/commander.js/pull/1235
[#1236]: https://github.com/tj/commander.js/pull/1236
[#1247]: https://github.com/tj/commander.js/pull/1247
[#1248]: https://github.com/tj/commander.js/pull/1248
[#1250]: https://github.com/tj/commander.js/pull/1250
[#1256]: https://github.com/tj/commander.js/pull/1256
[#1275]: https://github.com/tj/commander.js/pull/1275
[#1296]: https://github.com/tj/commander.js/pull/1296
[#1301]: https://github.com/tj/commander.js/issues/1301
[#1306]: https://github.com/tj/commander.js/pull/1306
[#1312]: https://github.com/tj/commander.js/pull/1312
[#1322]: https://github.com/tj/commander.js/pull/1322
[#1323]: https://github.com/tj/commander.js/pull/1323
[#1325]: https://github.com/tj/commander.js/pull/1325
[#1326]: https://github.com/tj/commander.js/pull/1326
[#1331]: https://github.com/tj/commander.js/pull/1331
[#1332]: https://github.com/tj/commander.js/pull/1332
[#1349]: https://github.com/tj/commander.js/pull/1349
[#1353]: https://github.com/tj/commander.js/pull/1353
[#1360]: https://github.com/tj/commander.js/pull/1360
[#1361]: https://github.com/tj/commander.js/pull/1361
[#1365]: https://github.com/tj/commander.js/pull/1365
[#1368]: https://github.com/tj/commander.js/pull/1368
[#1375]: https://github.com/tj/commander.js/pull/1375
[#1380]: https://github.com/tj/commander.js/pull/1380
[#1387]: https://github.com/tj/commander.js/pull/1387
[#1390]: https://github.com/tj/commander.js/pull/1390
[#1403]: https://github.com/tj/commander.js/pull/1403
[#1409]: https://github.com/tj/commander.js/pull/1409
[#1427]: https://github.com/tj/commander.js/pull/1427
[#1440]: https://github.com/tj/commander.js/pull/1440
[#1448]: https://github.com/tj/commander.js/pull/1448
[#1449]: https://github.com/tj/commander.js/pull/1449
[#1453]: https://github.com/tj/commander.js/pull/1453
[#1454]: https://github.com/tj/commander.js/pull/1454
[#1464]: https://github.com/tj/commander.js/pull/1464
[#1475]: https://github.com/tj/commander.js/pull/1475
[#1477]: https://github.com/tj/commander.js/pull/1477
[#1483]: https://github.com/tj/commander.js/pull/1483

[Unreleased]: https://github.com/tj/commander.js/compare/master...develop
[7.2.0]: https://github.com/tj/commander.js/compare/v7.1.0...v7.2.0
[7.1.0]: https://github.com/tj/commander.js/compare/v7.0.0...v7.1.0
[7.0.0]: https://github.com/tj/commander.js/compare/v6.2.1...v7.0.0
[7.0.0-2]: https://github.com/tj/commander.js/compare/v7.0.0-1...v7.0.0-2
[7.0.0-1]: https://github.com/tj/commander.js/compare/v7.0.0-0...v7.0.0-1
[7.0.0-0]: https://github.com/tj/commander.js/compare/v6.2.0...v7.0.0-0
[6.2.1]: https://github.com/tj/commander.js/compare/v6.2.0..v6.2.1
[6.2.0]: https://github.com/tj/commander.js/compare/v6.1.0..v6.2.0
[6.1.0]: https://github.com/tj/commander.js/compare/v6.0.0..v6.1.0
[6.0.0]: https://github.com/tj/commander.js/compare/v5.1.0..v6.0.0
[6.0.0-0]: https://github.com/tj/commander.js/compare/v5.1.0..v6.0.0-0
[5.1.0]: https://github.com/tj/commander.js/compare/v5.0.0..v5.1.0
[5.0.0]: https://github.com/tj/commander.js/compare/v4.1.1..v5.0.0
[5.0.0-4]: https://github.com/tj/commander.js/compare/v5.0.0-3..v5.0.0-4
[5.0.0-3]: https://github.com/tj/commander.js/compare/v5.0.0-2..v5.0.0-3
[5.0.0-2]: https://github.com/tj/commander.js/compare/v5.0.0-1..v5.0.0-2
[5.0.0-1]: https://github.com/tj/commander.js/compare/v5.0.0-0..v5.0.0-1
[5.0.0-0]: https://github.com/tj/commander.js/compare/v4.1.1..v5.0.0-0


---

# Commander.js

[![Build Status](https://github.com/tj/commander.js/workflows/build/badge.svg)](https://github.com/tj/commander.js/actions?query=workflow%3A%22build%22)
[![NPM Version](http://img.shields.io/npm/v/commander.svg?style=flat)](https://www.npmjs.org/package/commander)
[![NPM Downloads](https://img.shields.io/npm/dm/commander.svg?style=flat)](https://npmcharts.com/compare/commander?minimal=true)
[![Install Size](https://packagephobia.now.sh/badge?p=commander)](https://packagephobia.now.sh/result?p=commander)

The complete solution for [node.js](http://nodejs.org) command-line interfaces.

Read this in other languages: English | [简体中文](./Readme_zh-CN.md)

- [Commander.js](#commanderjs)
  - [Installation](#installation)
  - [Declaring _program_ variable](#declaring-program-variable)
  - [Options](#options)
    - [Common option types, boolean and value](#common-option-types-boolean-and-value)
    - [Default option value](#default-option-value)
    - [Other option types, negatable boolean and boolean|value](#other-option-types-negatable-boolean-and-booleanvalue)
    - [Required option](#required-option)
    - [Variadic option](#variadic-option)
    - [Version option](#version-option)
    - [More configuration](#more-configuration)
    - [Custom option processing](#custom-option-processing)
  - [Commands](#commands)
    - [Specify the argument syntax](#specify-the-argument-syntax)
    - [Action handler](#action-handler)
    - [Stand-alone executable (sub)commands](#stand-alone-executable-subcommands)
  - [Automated help](#automated-help)
    - [Custom help](#custom-help)
    - [Display help from code](#display-help-from-code)
    - [.usage and .name](#usage-and-name)
    - [.helpOption(flags, description)](#helpoptionflags-description)
    - [.addHelpCommand()](#addhelpcommand)
    - [More configuration](#more-configuration-1)
  - [Custom event listeners](#custom-event-listeners)
  - [Bits and pieces](#bits-and-pieces)
    - [.parse() and .parseAsync()](#parse-and-parseasync)
    - [Parsing Configuration](#parsing-configuration)
    - [Legacy options as properties](#legacy-options-as-properties)
    - [TypeScript](#typescript)
    - [createCommand()](#createcommand)
    - [Node options such as `--harmony`](#node-options-such-as---harmony)
    - [Debugging stand-alone executable subcommands](#debugging-stand-alone-executable-subcommands)
    - [Override exit and output handling](#override-exit-and-output-handling)
    - [Additional documentation](#additional-documentation)
  - [Examples](#examples)
  - [Support](#support)
    - [Commander for enterprise](#commander-for-enterprise)

For information about terms used in this document see: [terminology](./docs/terminology.md)

## Installation

```bash
npm install commander
```

## Declaring _program_ variable

Commander exports a global object which is convenient for quick programs.
This is used in the examples in this README for brevity.

```js
const { program } = require('commander');
program.version('0.0.1');
```

For larger programs which may use commander in multiple ways, including unit testing, it is better to create a local Command object to use.

```js
const { Command } = require('commander');
const program = new Command();
program.version('0.0.1');
```

For named imports in ECMAScript modules, import from `commander/esm.mjs`.

```js
// index.mjs
import { Command } from 'commander/esm.mjs';
const program = new Command();
```

And in TypeScript:

```ts
// index.ts
import { Command } from 'commander';
const program = new Command();
```


## Options

Options are defined with the `.option()` method, also serving as documentation for the options. Each option can have a short flag (single character) and a long name, separated by a comma or space or vertical bar ('|').

The parsed options can be accessed by calling `.opts()` on a `Command` object, and are passed to the action handler. Multi-word options such as "--template-engine" are camel-cased, becoming `program.opts().templateEngine` etc.

Multiple short flags may optionally be combined in a single argument following the dash: boolean flags, followed by a single option taking a value (possibly followed by the value).
For example `-a -b -p 80` may be written as `-ab -p80` or even `-abp80`.

You can use `--` to indicate the end of the options, and any remaining arguments will be used without being interpreted.

By default options on the command line are not positional, and can be specified before or after other arguments.

### Common option types, boolean and value

The two most used option types are a boolean option, and an option which takes its value
from the following argument (declared with angle brackets like `--expect <value>`). Both are `undefined` unless specified on command line.  

Example file: [options-common.js](./examples/options-common.js)

```js
program
  .option('-d, --debug', 'output extra debugging')
  .option('-s, --small', 'small pizza size')
  .option('-p, --pizza-type <type>', 'flavour of pizza');

program.parse(process.argv);

const options = program.opts();
if (options.debug) console.log(options);
console.log('pizza details:');
if (options.small) console.log('- small pizza size');
if (options.pizzaType) console.log(`- ${options.pizzaType}`);
```

```bash
$ pizza-options -d
{ debug: true, small: undefined, pizzaType: undefined }
pizza details:
$ pizza-options -p
error: option '-p, --pizza-type <type>' argument missing
$ pizza-options -ds -p vegetarian
{ debug: true, small: true, pizzaType: 'vegetarian' }
pizza details:
- small pizza size
- vegetarian
$ pizza-options --pizza-type=cheese
pizza details:
- cheese
```

`program.parse(arguments)` processes the arguments, leaving any args not consumed by the program options in the `program.args` array. The parameter is optional and defaults to `process.argv`.

### Default option value

You can specify a default value for an option which takes a value.

Example file: [options-defaults.js](./examples/options-defaults.js)

```js
program
  .option('-c, --cheese <type>', 'add the specified type of cheese', 'blue');

program.parse();

console.log(`cheese: ${program.opts().cheese}`);
```

```bash
$ pizza-options
cheese: blue
$ pizza-options --cheese stilton
cheese: stilton
```

### Other option types, negatable boolean and boolean|value

You can define a boolean option long name with a leading `no-` to set the option value to false when used.
Defined alone this also makes the option true by default.

If you define `--foo` first, adding `--no-foo` does not change the default value from what it would
otherwise be. You can specify a default boolean value for a boolean option and it can be overridden on command line.

Example file: [options-negatable.js](./examples/options-negatable.js)

```js
program
  .option('--no-sauce', 'Remove sauce')
  .option('--cheese <flavour>', 'cheese flavour', 'mozzarella')
  .option('--no-cheese', 'plain with no cheese')
  .parse();

const options = program.opts();
const sauceStr = options.sauce ? 'sauce' : 'no sauce';
const cheeseStr = (options.cheese === false) ? 'no cheese' : `${options.cheese} cheese`;
console.log(`You ordered a pizza with ${sauceStr} and ${cheeseStr}`);
```

```bash
$ pizza-options
You ordered a pizza with sauce and mozzarella cheese
$ pizza-options --sauce
error: unknown option '--sauce'
$ pizza-options --cheese=blue
You ordered a pizza with sauce and blue cheese
$ pizza-options --no-sauce --no-cheese
You ordered a pizza with no sauce and no cheese
```

You can specify an option which may be used as a boolean option but may optionally take an option-argument
(declared with square brackets like `--optional [value]`).

Example file: [options-boolean-or-value.js](./examples/options-boolean-or-value.js)

```js
program
  .option('-c, --cheese [type]', 'Add cheese with optional type');

program.parse(process.argv);

const options = program.opts();
if (options.cheese === undefined) console.log('no cheese');
else if (options.cheese === true) console.log('add cheese');
else console.log(`add cheese type ${options.cheese}`);
```

```bash
$ pizza-options
no cheese
$ pizza-options --cheese
add cheese
$ pizza-options --cheese mozzarella
add cheese type mozzarella
```

For information about possible ambiguous cases, see [options taking varying arguments](./docs/options-taking-varying-arguments.md).

### Required option

You may specify a required (mandatory) option using `.requiredOption`. The option must have a value after parsing, usually specified on the command line, or perhaps from a default value (say from environment). The method is otherwise the same as `.option` in format, taking flags and description, and optional default value or custom processing.

Example file: [options-required.js](./examples/options-required.js)

```js
program
  .requiredOption('-c, --cheese <type>', 'pizza must have cheese');

program.parse();
```

```bash
$ pizza
error: required option '-c, --cheese <type>' not specified
```

### Variadic option

You may make an option variadic by appending `...` to the value placeholder when declaring the option. On the command line you
can then specify multiple option-arguments, and the parsed option value will be an array. The extra arguments
are read until the first argument starting with a dash. The special argument `--` stops option processing entirely. If a value
is specified in the same argument as the option then no further values are read.

Example file: [options-variadic.js](./examples/options-variadic.js)

```js
program
  .option('-n, --number <numbers...>', 'specify numbers')
  .option('-l, --letter [letters...]', 'specify letters');

program.parse();

console.log('Options: ', program.opts());
console.log('Remaining arguments: ', program.args);
```

```bash
$ collect -n 1 2 3 --letter a b c
Options:  { number: [ '1', '2', '3' ], letter: [ 'a', 'b', 'c' ] }
Remaining arguments:  []
$ collect --letter=A -n80 operand
Options:  { number: [ '80' ], letter: [ 'A' ] }
Remaining arguments:  [ 'operand' ]
$ collect --letter -n 1 -n 2 3 -- operand
Options:  { number: [ '1', '2', '3' ], letter: true }
Remaining arguments:  [ 'operand' ]
```

For information about possible ambiguous cases, see [options taking varying arguments](./docs/options-taking-varying-arguments.md).

### Version option

The optional `version` method adds handling for displaying the command version. The default option flags are `-V` and `--version`, and when present the command prints the version number and exits.

```js
program.version('0.0.1');
```

```bash
$ ./examples/pizza -V
0.0.1
```

You may change the flags and description by passing additional parameters to the `version` method, using
the same syntax for flags as the `option` method.

```js
program.version('0.0.1', '-v, --vers', 'output the current version');
```

### More configuration

You can add most options using the `.option()` method, but there are some additional features available
by constructing an `Option` explicitly for less common cases.

Example file: [options-extra.js](./examples/options-extra.js)

```js
program
  .addOption(new Option('-s, --secret').hideHelp())
  .addOption(new Option('-t, --timeout <delay>', 'timeout in seconds').default(60, 'one minute'))
  .addOption(new Option('-d, --drink <size>', 'drink size').choices(['small', 'medium', 'large']));
```

```bash
$ extra --help
Usage: help [options]

Options:
  -t, --timeout <delay>  timeout in seconds (default: one minute)
  -d, --drink <size>     drink cup size (choices: "small", "medium", "large")
  -h, --help             display help for command

$ extra --drink huge
error: option '-d, --drink <size>' argument 'huge' is invalid. Allowed choices are small, medium, large.
```

### Custom option processing

You may specify a function to do custom processing of option-arguments. The callback function receives two parameters,
the user specified option-argument and the previous value for the option. It returns the new value for the option.

This allows you to coerce the option-argument to the desired type, or accumulate values, or do entirely custom processing.

You can optionally specify the default/starting value for the option after the function parameter.

Example file: [options-custom-processing.js](./examples/options-custom-processing.js)

```js
function myParseInt(value, dummyPrevious) {
  // parseInt takes a string and a radix
  const parsedValue = parseInt(value, 10);
  if (isNaN(parsedValue)) {
    throw new commander.InvalidOptionArgumentError('Not a number.');
  }
  return parsedValue;
}

function increaseVerbosity(dummyValue, previous) {
  return previous + 1;
}

function collect(value, previous) {
  return previous.concat([value]);
}

function commaSeparatedList(value, dummyPrevious) {
  return value.split(',');
}

program
  .option('-f, --float <number>', 'float argument', parseFloat)
  .option('-i, --integer <number>', 'integer argument', myParseInt)
  .option('-v, --verbose', 'verbosity that can be increased', increaseVerbosity, 0)
  .option('-c, --collect <value>', 'repeatable value', collect, [])
  .option('-l, --list <items>', 'comma separated list', commaSeparatedList)
;

program.parse();

const options = program.opts();
if (options.float !== undefined) console.log(`float: ${options.float}`);
if (options.integer !== undefined) console.log(`integer: ${options.integer}`);
if (options.verbose > 0) console.log(`verbosity: ${options.verbose}`);
if (options.collect.length > 0) console.log(options.collect);
if (options.list !== undefined) console.log(options.list);
```

```bash
$ custom -f 1e2
float: 100
$ custom --integer 2
integer: 2
$ custom -v -v -v
verbose: 3
$ custom -c a -c b -c c
[ 'a', 'b', 'c' ]
$ custom --list x,y,z
[ 'x', 'y', 'z' ]
```

## Commands

You can specify (sub)commands using `.command()` or `.addCommand()`. There are two ways these can be implemented: using an action handler attached to the command, or as a stand-alone executable file (described in more detail later). The subcommands may be nested ([example](./examples/nestedCommands.js)).

In the first parameter to `.command()` you specify the command name and any command-arguments. The arguments may be `<required>` or `[optional]`, and the last argument may also be `variadic...`.

You can use `.addCommand()` to add an already configured subcommand to the program.

For example:

```js
// Command implemented using action handler (description is supplied separately to `.command`)
// Returns new command for configuring.
program
  .command('clone <source> [destination]')
  .description('clone a repository into a newly created directory')
  .action((source, destination) => {
    console.log('clone command called');
  });

// Command implemented using stand-alone executable file (description is second parameter to `.command`)
// Returns `this` for adding more commands.
program
  .command('start <service>', 'start named service')
  .command('stop [service]', 'stop named service, or all if no name supplied');

// Command prepared separately.
// Returns `this` for adding more commands.
program
  .addCommand(build.makeBuildCommand());
```

Configuration options can be passed with the call to `.command()` and `.addCommand()`. Specifying `hidden: true` will 
remove the command from the generated help output. Specifying `isDefault: true` will run the subcommand if no other
subcommand is specified ([example](./examples/defaultCommand.js)).

### Specify the argument syntax

You use `.arguments` to specify the expected command-arguments for the top-level command, and for subcommands they are usually
included in the `.command` call. Angled brackets (e.g. `<required>`) indicate required command-arguments.
Square brackets (e.g. `[optional]`) indicate optional command-arguments.
You can optionally describe the arguments in the help by supplying a hash as second parameter to `.description()`.

Example file: [arguments.js](./examples/arguments.js)

```js
program
  .version('0.1.0')
  .arguments('<username> [password]')
  .description('test command', {
    username: 'user to login',
    password: 'password for user, if required'
  })
  .action((username, password) => {
    console.log('username:', username);
    console.log('environment:', password || 'no password given');
  });
```

 The last argument of a command can be variadic, and only the last argument.  To make an argument variadic you
 append `...` to the argument name. For example:

```js
program
  .version('0.1.0')
  .command('rmdir <dirs...>')
  .action(function (dirs) {
    dirs.forEach((dir) => {
      console.log('rmdir %s', dir);
    });
  });
```

The variadic argument is passed to the action handler as an array.

### Action handler

The action handler gets passed a parameter for each command-argument you declared, and two additional parameters
which are the parsed options and the command object itself. 

Example file: [thank.js](./examples/thank.js)

```js
program
  .arguments('<name>')
  .option('-t, --title <honorific>', 'title to use before name')
  .option('-d, --debug', 'display some debugging')
  .action((name, options, command) => {
    if (options.debug) {
      console.error('Called %s with options %o', command.name(), options);
    }
    const title = options.title ? `${options.title} ` : '';
    console.log(`Thank-you ${title}${name}`);
  });
```

You may supply an `async` action handler, in which case you call `.parseAsync` rather than `.parse`.

```js
async function run() { /* code goes here */ }

async function main() {
  program
    .command('run')
    .action(run);
  await program.parseAsync(process.argv);
}
```

A command's options and arguments on the command line are validated when the command is used. Any unknown options or missing arguments will be reported as an error. You can suppress the unknown option checks with `.allowUnknownOption()`. By default it is not an error to
pass more arguments than declared, but you can make this an error with `.allowExcessArguments(false)`.

### Stand-alone executable (sub)commands

When `.command()` is invoked with a description argument, this tells Commander that you're going to use stand-alone executables for subcommands.
Commander will search the executables in the directory of the entry script (like `./examples/pm`) with the name `program-subcommand`, like `pm-install`, `pm-search`.
You can specify a custom name with the `executableFile` configuration option.

You handle the options for an executable (sub)command in the executable, and don't declare them at the top-level.

Example file: [pm](./examples/pm)

```js
program
  .version('0.1.0')
  .command('install [name]', 'install one or more packages')
  .command('search [query]', 'search with optional query')
  .command('update', 'update installed packages', { executableFile: 'myUpdateSubCommand' })
  .command('list', 'list packages installed', { isDefault: true });

program.parse(process.argv);
```

If the program is designed to be installed globally, make sure the executables have proper modes, like `755`.

## Automated help

The help information is auto-generated based on the information commander already knows about your program. The default
help option is `-h,--help`.

Example file: [pizza](./examples/pizza)

```bash
$ node ./examples/pizza --help
Usage: pizza [options]

An application for pizza ordering

Options:
  -p, --peppers        Add peppers
  -c, --cheese <type>  Add the specified type of cheese (default: "marble")
  -C, --no-cheese      You do not want any cheese
  -h, --help           display help for command
```

A `help` command is added by default if your command has subcommands. It can be used alone, or with a subcommand name to show
further help for the subcommand. These are effectively the same if the `shell` program has implicit help:

```bash
shell help
shell --help

shell help spawn
shell spawn --help
```

### Custom help

You can add extra text to be displayed along with the built-in help. 

Example file: [custom-help](./examples/custom-help)

```js
program
  .option('-f, --foo', 'enable some foo');

program.addHelpText('after', `

Example call:
  $ custom-help --help`);
```

Yields the following help output:

```Text
Usage: custom-help [options]

Options:
  -f, --foo   enable some foo
  -h, --help  display help for command

Example call:
  $ custom-help --help
```

The positions in order displayed are:

- `beforeAll`: add to the program for a global banner or header
- `before`: display extra information before built-in help
- `after`: display extra information after built-in help
- `afterAll`: add to the program for a global footer (epilog)

The positions "beforeAll" and "afterAll" apply to the command and all its subcommands. 

The second parameter can be a string, or a function returning a string. The function is passed a context object for your convenience. The properties are:

- error: a boolean for whether the help is being displayed due to a usage error
- command: the Command which is displaying the help

### Display help from code

`.help()`: display help information and exit immediately. You can optionally pass `{ error: true }` to display on stderr and exit with an error status.

`.outputHelp()`: output help information without exiting. You can optionally pass `{ error: true }` to display on stderr.

`.helpInformation()`: get the built-in command help information as a string for processing or displaying yourself.

### .usage and .name

These allow you to customise the usage description in the first line of the help. The name is otherwise
deduced from the (full) program arguments. Given:

```js
program
  .name("my-command")
  .usage("[global options] command")
```

The help will start with:

```Text
Usage: my-command [global options] command
```

### .helpOption(flags, description)

By default every command has a help option. Override the default help flags and description. Pass false to disable the built-in help option.

```js
program
  .helpOption('-e, --HELP', 'read more information');
```

### .addHelpCommand()

A help command is added by default if your command has subcommands. You can explicitly turn on or off the implicit help command with `.addHelpCommand()` and `.addHelpCommand(false)`.

You can both turn on and customise the help command by supplying the name and description:

```js
program.addHelpCommand('assist [command]', 'show assistance');
```

### More configuration

The built-in help is formatted using the Help class.
You can configure the Help behaviour by modifying data properties and methods using `.configureHelp()`, or by subclassing using `.createHelp()` if you prefer.

The data properties are:

- `helpWidth`: specify the wrap width, useful for unit tests
- `sortSubcommands`: sort the subcommands alphabetically
- `sortOptions`: sort the options alphabetically

There are methods getting the visible lists of arguments, options, and subcommands. There are methods for formatting the items in the lists, with each item having a _term_ and _description_. Take a look at `.formatHelp()` to see how they are used.

Example file: [configure-help.js](./examples/configure-help.js)

```
program.configureHelp({
  sortSubcommands: true,
  subcommandTerm: (cmd) => cmd.name() // Just show the name, instead of short usage.
});
```

## Custom event listeners

You can execute custom actions by listening to command and option events.

```js
program.on('option:verbose', function () {
  process.env.VERBOSE = this.opts().verbose;
});

program.on('command:*', function (operands) {
  console.error(`error: unknown command '${operands[0]}'`);
  const availableCommands = program.commands.map(cmd => cmd.name());
  mySuggestBestMatch(operands[0], availableCommands);
  process.exitCode = 1;
});
```

## Bits and pieces

### .parse() and .parseAsync()

The first argument to `.parse` is the array of strings to parse. You may omit the parameter to implicitly use `process.argv`.

If the arguments follow different conventions than node you can pass a `from` option in the second parameter:

- 'node': default, `argv[0]` is the application and `argv[1]` is the script being run, with user parameters after that
- 'electron': `argv[1]` varies depending on whether the electron application is packaged
- 'user': all of the arguments from the user

For example:

```js
program.parse(process.argv); // Explicit, node conventions
program.parse(); // Implicit, and auto-detect electron
program.parse(['-f', 'filename'], { from: 'user' });
```

### Parsing Configuration

If the default parsing does not suit your needs, there are some behaviours to support other usage patterns.

By default program options are recognised before and after subcommands. To only look for program options before subcommands, use `.enablePositionalOptions()`. This lets you use
an option for a different purpose in subcommands.

Example file: [positional-options.js](./examples/positional-options.js)

With positional options, the `-b` is a program option in the first line and a subcommand option in the second line:

```sh
program -b subcommand
program subcommand -b
```

By default options are recognised before and after command-arguments. To only process options that come
before the command-arguments, use `.passThroughOptions()`. This lets you pass the  arguments and following options through to another program
without needing to use `--` to end the option processing. 
To use pass through options in a subcommand, the program needs to enable positional options.

Example file: [pass-through-options.js](./examples/pass-through-options.js)

With pass through options, the `--port=80` is a program option in the first line and passed through as a command-argument in the second line:

```sh
program --port=80 arg
program arg --port=80
```

By default the option processing shows an error for an unknown option. To have an unknown option treated as an ordinary command-argument and continue looking for options, use `.allowUnknownOption()`. This lets you mix known and unknown options.

By default the argument processing does not display an error for more command-arguments than expected.
To display an error for excess arguments, use`.allowExcessArguments(false)`.

### Legacy options as properties 

Before Commander 7, the option values were stored as properties on the command.
This was convenient to code but the downside was possible clashes with
existing properties of `Command`. You can revert to the old behaviour to run unmodified legacy code by using `.storeOptionsAsProperties()`.

```js
program
  .storeOptionsAsProperties()
  .option('-d, --debug')
  .action((commandAndOptions) => {
    if (commandAndOptions.debug) {
      console.error(`Called ${commandAndOptions.name()}`);
    }
  });
```

### TypeScript

If you use `ts-node` and  stand-alone executable subcommands written as `.ts` files, you need to call your program through node to get the subcommands called correctly. e.g.

```bash
node -r ts-node/register pm.ts
```

### createCommand()

This factory function creates a new command. It is exported and may be used instead of using `new`, like:

```js
const { createCommand } = require('commander');
const program = createCommand();
```

`createCommand` is also a method of the Command object, and creates a new command rather than a subcommand. This gets used internally
when creating subcommands using `.command()`, and you may override it to
customise the new subcommand (example file [custom-command-class.js](./examples/custom-command-class.js)).

### Node options such as `--harmony`

You can enable `--harmony` option in two ways:

- Use `#! /usr/bin/env node --harmony` in the subcommands scripts. (Note Windows does not support this pattern.)
- Use the `--harmony` option when call the command, like `node --harmony examples/pm publish`. The `--harmony` option will be preserved when spawning subcommand process.

### Debugging stand-alone executable subcommands

An executable subcommand is launched as a separate child process.

If you are using the node inspector for [debugging](https://nodejs.org/en/docs/guides/debugging-getting-started/) executable subcommands using `node --inspect` et al,
the inspector port is incremented by 1 for the spawned subcommand.

If you are using VSCode to debug executable subcommands you need to set the `"autoAttachChildProcesses": true` flag in your launch.json configuration.

### Override exit and output handling

By default Commander calls `process.exit` when it detects errors, or after displaying the help or version. You can override
this behaviour and optionally supply a callback. The default override throws a `CommanderError`.

The override callback is passed a `CommanderError` with properties `exitCode` number, `code` string, and `message`. The default override behaviour is to throw the error, except for async handling of executable subcommand completion which carries on. The normal display of error messages or version or help
is not affected by the override which is called after the display.

```js
program.exitOverride();

try {
  program.parse(process.argv);
} catch (err) {
  // custom processing...
}
```

By default Commander is configured for a command-line application and writes to stdout and stderr.
You can modify this behaviour for custom applications. In addition, you can modify the display of error messages.

Example file: [configure-output.js](./examples/configure-output.js)


```js
function errorColor(str) {
  // Add ANSI escape codes to display text in red.
  return `\x1b[31m${str}\x1b[0m`;
}

program
  .configureOutput({
    // Visibly override write routines as example!
    writeOut: (str) => process.stdout.write(`[OUT] ${str}`),
    writeErr: (str) => process.stdout.write(`[ERR] ${str}`),
    // Highlight errors in color.
    outputError: (str, write) => write(errorColor(str))
  });
```

### Additional documentation

There is more information available about:

- [deprecated](./docs/deprecated.md) features still supported for backwards compatibility
- [options taking varying arguments](./docs/options-taking-varying-arguments.md)

## Examples

In a single command program, you might not need an action handler.

Example file: [pizza](./examples/pizza)

```js
const { program } = require('commander');

program
  .description('An application for pizza ordering')
  .option('-p, --peppers', 'Add peppers')
  .option('-c, --cheese <type>', 'Add the specified type of cheese', 'marble')
  .option('-C, --no-cheese', 'You do not want any cheese');

program.parse();

const options = program.opts();
console.log('you ordered a pizza with:');
if (options.peppers) console.log('  - peppers');
const cheese = !options.cheese ? 'no' : options.cheese;
console.log('  - %s cheese', cheese);
```

In a multi-command program, you will have action handlers for each command (or stand-alone executables for the commands).

Example file: [deploy](./examples/deploy)

```js
const { Command } = require('commander');
const program = new Command();

program
  .version('0.0.1')
  .option('-c, --config <path>', 'set config path', './deploy.conf');

program
  .command('setup [env]')
  .description('run setup commands for all envs')
  .option('-s, --setup_mode <mode>', 'Which setup mode to use', 'normal')
  .action((env, options) => {
    env = env || 'all';
    console.log('read config from %s', program.opts().config);
    console.log('setup for %s env(s) with %s mode', env, options.setup_mode);
  });

program
  .command('exec <script>')
  .alias('ex')
  .description('execute the given remote cmd')
  .option('-e, --exec_mode <mode>', 'Which exec mode to use', 'fast')
  .action((script, options) => {
    console.log('read config from %s', program.opts().config);
    console.log('exec "%s" using %s mode and config %s', script, options.exec_mode, program.opts().config);
  }).addHelpText('after', `
Examples:
  $ deploy exec sequential
  $ deploy exec async`
  );
  
program.parse(process.argv);
```

More samples can be found in the [examples](https://github.com/tj/commander.js/tree/master/examples) directory.

## Support

The current version of Commander is fully supported on Long Term Support versions of node, and requires at least node v10.
(For older versions of node, use an older version of Commander. Commander version 2.x has the widest support.)

The main forum for free and community support is the project [Issues](https://github.com/tj/commander.js/issues) on GitHub.

### Commander for enterprise

Available as part of the Tidelift Subscription

The maintainers of Commander and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-commander?utm_source=npm-commander&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)


---

<div align="center">
  <a href="https://github.com/webpack/webpack">
    <img width="200" height="200" src="https://webpack.js.org/assets/icon-square-big.svg">
  </a>
</div>

[![npm][npm]][npm-url]
[![node][node]][node-url]
[![deps][deps]][deps-url]
[![tests][tests]][tests-url]
[![coverage][cover]][cover-url]
[![chat][chat]][chat-url]
[![size][size]][size-url]

# webpack-dev-middleware

An express-style development middleware for use with [webpack](https://webpack.js.org)
bundles and allows for serving of the files emitted from webpack.
This should be used for **development only**.

Some of the benefits of using this middleware include:

- No files are written to disk, rather it handles files in memory
- If files changed in watch mode, the middleware delays requests until compiling
  has completed.
- Supports hot module reload (HMR).

## Getting Started

First thing's first, install the module:

```console
npm install webpack-dev-middleware --save-dev
```

_Note: We do not recommend installing this module globally._

## Usage

```js
const webpack = require("webpack");
const middleware = require("webpack-dev-middleware");
const compiler = webpack({
  // webpack options
});
const express = require("express");
const app = express();

app.use(
  middleware(compiler, {
    // webpack-dev-middleware options
  })
);

app.listen(3000, () => console.log("Example app listening on port 3000!"));
```

See [below](#other-servers) for an example of use with fastify.

## Options

|                    Name                     |           Type            |                    Default                    | Description                                                                                                          |
| :-----------------------------------------: | :-----------------------: | :-------------------------------------------: | :------------------------------------------------------------------------------------------------------------------- |
|          **[`methods`](#methods)**          |          `Array`          |              `[ 'GET', 'HEAD' ]`              | Allows to pass the list of HTTP request methods accepted by the middleware                                           |
|          **[`headers`](#headers)**          | `Array\|Object\|Function` |                  `undefined`                  | Allows to pass custom HTTP headers on each request.                                                                  |
|            **[`index`](#index)**            |     `Boolean\|String`     |                 `index.html`                  | If `false` (but not `undefined`), the server will not respond to requests to the root URL.                           |
|        **[`mimeTypes`](#mimetypes)**        |         `Object`          |                  `undefined`                  | Allows to register custom mime types or extension mappings.                                                          |
|       **[`publicPath`](#publicpath)**       |         `String`          |  `output.publicPath` (from a configuration)   | The public path that the middleware is bound to.                                                                     |
|            **[`stats`](#stats)**            | `Boolean\|String\|Object` |        `stats` (from a configuration)         | Stats options object or preset name.                                                                                 |
| **[`serverSideRender`](#serversiderender)** |         `Boolean`         |                  `undefined`                  | Instructs the module to enable or disable the server-side rendering mode.                                            |
|      **[`writeToDisk`](#writetodisk)**      |    `Boolean\|Function`    |                    `false`                    | Instructs the module to write files to the configured location on disk as specified in your `webpack` configuration. |
| **[`outputFileSystem`](#outputfilesystem)** |         `Object`          | [`memfs`](https://github.com/streamich/memfs) | Set the default file system which will be used by webpack as primary destination of generated files.                 |

The middleware accepts an `options` Object. The following is a property reference for the Object.

### methods

Type: `Array`  
Default: `[ 'GET', 'HEAD' ]`

This property allows a user to pass the list of HTTP request methods accepted by the middleware\*\*.

### headers

Type: `Array|Object|Function`
Default: `undefined`

This property allows a user to pass custom HTTP headers on each request.
eg. `{ "X-Custom-Header": "yes" }`

or

```js
webpackDevMiddleware(compiler, {
  headers: () => {
    return {
      "Last-Modified": new Date(),
    };
  },
});
```

or

```js
webpackDevMiddleware(compiler, {
  headers: (req, res, context) => {
    res.setHeader("Last-Modified", new Date());
  },
});
```

or

```js
webpackDevMiddleware(compiler, {
  headers: [
    {
      key: "X-custom-header"
      value: "foo"
    },
    {
      key: "Y-custom-header",
      value: "bar"
    }
  ]
  },
});
```

or

```js
webpackDevMiddleware(compiler, {
  headers: () => [
    {
      key: "X-custom-header"
      value: "foo"
    },
    {
      key: "Y-custom-header",
      value: "bar"
    }
  ]
  },
});
```

### index

Type: `Boolean|String`
Default: `index.html`

If `false` (but not `undefined`), the server will not respond to requests to the root URL.

### mimeTypes

Type: `Object`  
Default: `undefined`

This property allows a user to register custom mime types or extension mappings.
eg. `mimeTypes: { phtml: 'text/html' }`.

Please see the documentation for [`mime-types`](https://github.com/jshttp/mime-types) for more information.

### publicPath

Type: `String`
Default: `output.publicPath` (from a configuration)

The public path that the middleware is bound to.

_Best Practice: use the same `publicPath` defined in your webpack config. For more information about `publicPath`, please see [the webpack documentation](https://webpack.js.org/guides/public-path)._

### stats

Type: `Boolean|String|Object`
Default: `stats` (from a configuration)

Stats options object or preset name.

### serverSideRender

Type: `Boolean`  
Default: `undefined`

Instructs the module to enable or disable the server-side rendering mode.
Please see [Server-Side Rendering](#server-side-rendering) for more information.

### writeToDisk

Type: `Boolean|Function`  
Default: `false`

If `true`, the option will instruct the module to write files to the configured location on disk as specified in your `webpack` config file.
_Setting `writeToDisk: true` won't change the behavior of the `webpack-dev-middleware`, and bundle files accessed through the browser will still be served from memory._
This option provides the same capabilities as the [`WriteFilePlugin`](https://github.com/gajus/write-file-webpack-plugin/pulls).

This option also accepts a `Function` value, which can be used to filter which files are written to disk.
The function follows the same premise as [`Array#filter`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter) in which a return value of `false` _will not_ write the file, and a return value of `true` _will_ write the file to disk. eg.

```js
const webpack = require("webpack");
const configuration = {
  /* Webpack configuration */
};
const compiler = webpack(configuration);

middleware(compiler, {
  writeToDisk: (filePath) => {
    return /superman\.css$/.test(filePath);
  },
});
```

### outputFileSystem

Type: `Object`  
Default: [memfs](https://github.com/streamich/memfs)

Set the default file system which will be used by webpack as primary destination of generated files.
This option isn't affected by the [writeToDisk](#writeToDisk) option.

You have to provide `.join()` and `mkdirp` method to the `outputFileSystem` instance manually for compatibility with `webpack@4`.

This can be done simply by using `path.join`:

```js
const webpack = require("webpack");
const path = require("path");
const myOutputFileSystem = require("my-fs");
const mkdirp = require("mkdirp");

myOutputFileSystem.join = path.join.bind(path); // no need to bind
myOutputFileSystem.mkdirp = mkdirp.bind(mkdirp); // no need to bind

const compiler = webpack({
  /* Webpack configuration */
});

middleware(compiler, { outputFileSystem: myOutputFileSystem });
```

## API

`webpack-dev-middleware` also provides convenience methods that can be use to
interact with the middleware at runtime:

### `close(callback)`

Instructs `webpack-dev-middleware` instance to stop watching for file changes.

#### Parameters

##### `callback`

Type: `Function`
Required: `No`

A function executed once the middleware has stopped watching.

```js
const express = require("express");
const webpack = require("webpack");
const compiler = webpack({
  /* Webpack configuration */
});
const middleware = require("webpack-dev-middleware");
const instance = middleware(compiler);

const app = new express();

app.use(instance);

setTimeout(() => {
  // Says `webpack` to stop watch changes
  instance.close();
}, 1000);
```

### `invalidate(callback)`

Instructs `webpack-dev-middleware` instance to recompile the bundle, e.g. after a change to the configuration.

#### Parameters

##### `callback`

Type: `Function`
Required: `No`

A function executed once the middleware has invalidated.

```js
const express = require("express");
const webpack = require("webpack");
const compiler = webpack({
  /* Webpack configuration */
});
const middleware = require("webpack-dev-middleware");
const instance = middleware(compiler);

const app = new express();

app.use(instance);

setTimeout(() => {
  // After a short delay the configuration is changed and a banner plugin is added to the config
  new webpack.BannerPlugin("A new banner").apply(compiler);

  // Recompile the bundle with the banner plugin:
  instance.invalidate();
}, 1000);
```

### `waitUntilValid(callback)`

Executes a callback function when the compiler bundle is valid, typically after
compilation.

#### Parameters

##### `callback`

Type: `Function`
Required: `No`

A function executed when the bundle becomes valid.
If the bundle is valid at the time of calling, the callback is executed immediately.

```js
const express = require("express");
const webpack = require("webpack");
const compiler = webpack({
  /* Webpack configuration */
});
const middleware = require("webpack-dev-middleware");
const instance = middleware(compiler);

const app = new express();

app.use(instance);

instance.waitUntilValid(() => {
  console.log("Package is in a valid state");
});
```

### `getFilenameFromUrl(url)`

Get filename from URL.

#### Parameters

##### `url`

Type: `String`
Required: `Yes`

URL for the requested file.

```js
const express = require("express");
const webpack = require("webpack");
const compiler = webpack({
  /* Webpack configuration */
});
const middleware = require("webpack-dev-middleware");
const instance = middleware(compiler);

const app = new express();

app.use(instance);

instance.waitUntilValid(() => {
  const filename = instance.getFilenameFromUrl("/bundle.js");

  console.log(`Filename is ${filename}`);
});
```

## Known Issues

### Multiple Successive Builds

Watching will frequently cause multiple compilations
as the bundle changes during compilation. This is due in part to cross-platform
differences in file watchers, so that webpack doesn't loose file changes when
watched files change rapidly. If you run into this situation, please make use of
the [`TimeFixPlugin`](https://github.com/egoist/time-fix-plugin).

## Server-Side Rendering

_Note: this feature is experimental and may be removed or changed completely in the future._

In order to develop an app using server-side rendering, we need access to the
[`stats`](https://github.com/webpack/docs/wiki/node.js-api#stats), which is
generated with each build.

With server-side rendering enabled, `webpack-dev-middleware` sets the `stats` to `res.locals.webpack.devMiddleware.context.stats`
and the filesystem to `res.locals.webpack.devMiddleware.context.outputFileSystem` before invoking the next middleware,
allowing a developer to render the page body and manage the response to clients.

_Note: Requests for bundle files will still be handled by
`webpack-dev-middleware` and all requests will be pending until the build
process is finished with server-side rendering enabled._

Example Implementation:

```js
const express = require("express");
const webpack = require("webpack");
const compiler = webpack({
  /* Webpack configuration */
});
const isObject = require("is-object");
const middleware = require("webpack-dev-middleware");

const app = new express();

// This function makes server rendering of asset references consistent with different webpack chunk/entry configurations
function normalizeAssets(assets) {
  if (isObject(assets)) {
    return Object.values(assets);
  }

  return Array.isArray(assets) ? assets : [assets];
}

app.use(middleware(compiler, { serverSideRender: true }));

// The following middleware would not be invoked until the latest build is finished.
app.use((req, res) => {
  const { devMiddleware } = res.locals.webpack;
  const outputFileSystem = devMiddleware.context.outputFileSystem;
  const jsonWebpackStats = devMiddleware.context.stats.toJson();
  const { assetsByChunkName, outputPath } = jsonWebpackStats;

  // Then use `assetsByChunkName` for server-side rendering
  // For example, if you have only one main chunk:
  res.send(`
<html>
  <head>
    <title>My App</title>
    <style>
    ${normalizeAssets(assetsByChunkName.main)
      .filter((path) => path.endsWith(".css"))
      .map((path) => outputFileSystem.readFileSync(path.join(outputPath, path)))
      .join("\n")}
    </style>
  </head>
  <body>
    <div id="root"></div>
    ${normalizeAssets(assetsByChunkName.main)
      .filter((path) => path.endsWith(".js"))
      .map((path) => `<script src="${path}"></script>`)
      .join("\n")}
  </body>
</html>
  `);
});
```

## Support

We do our best to keep Issues in the repository focused on bugs, features, and
needed modifications to the code for the module. Because of that, we ask users
with general support, "how-to", or "why isn't this working" questions to try one
of the other support channels that are available.

Your first-stop-shop for support for webpack-dev-server should by the excellent
[documentation][docs-url] for the module. If you see an opportunity for improvement
of those docs, please head over to the [webpack.js.org repo][wjo-url] and open a
pull request.

From there, we encourage users to visit the [webpack Gitter chat][chat-url] and
talk to the fine folks there. If your quest for answers comes up dry in chat,
head over to [StackOverflow][stack-url] and do a quick search or open a new
question. Remember; It's always much easier to answer questions that include your
`webpack.config.js` and relevant files!

If you're twitter-savvy you can tweet [#webpack][hash-url] with your question
and someone should be able to reach out and lend a hand.

If you have discovered a :bug:, have a feature suggestion, or would like to see
a modification, please feel free to create an issue on Github. _Note: The issue
template isn't optional, so please be sure not to remove it, and please fill it
out completely._

## Other servers

Examples of use with other servers will follow here.

### Fastify

Fastify interop will require the use of `fastify-express` instead of `middie` for providing middleware support. As the authors of `fastify-express` recommend, this should only be used as a stopgap while full Fastify support is worked on.

```js
const fastify = require("fastify")();
const webpack = require("webpack");
const webpackConfig = require("./webpack.config.js");
const devMiddleware = require("webpack-dev-middleware");

const compiler = webpack(webpackConfig);
const { publicPath } = webpackConfig.output;

(async () => {
  await fastify.register(require("fastify-express"));
  await fastify.use(devMiddleware(compiler, { publicPath }));
  await fastify.listen(3000);
})();
```

## Contributing

Please take a moment to read our contributing guidelines if you haven't yet done so.

[CONTRIBUTING](./CONTRIBUTING.md)

## License

[MIT](./LICENSE)

[npm]: https://img.shields.io/npm/v/webpack-dev-middleware.svg
[npm-url]: https://npmjs.com/package/webpack-dev-middleware
[node]: https://img.shields.io/node/v/webpack-dev-middleware.svg
[node-url]: https://nodejs.org
[deps]: https://david-dm.org/webpack/webpack-dev-middleware.svg
[deps-url]: https://david-dm.org/webpack/webpack-dev-middleware
[tests]: https://github.com/webpack/webpack-dev-middleware/workflows/webpack-dev-middleware/badge.svg
[tests-url]: https://github.com/webpack/webpack-dev-middleware/actions
[cover]: https://codecov.io/gh/webpack/webpack-dev-middleware/branch/master/graph/badge.svg
[cover-url]: https://codecov.io/gh/webpack/webpack-dev-middleware
[chat]: https://badges.gitter.im/webpack/webpack.svg
[chat-url]: https://gitter.im/webpack/webpack
[size]: https://packagephobia.com/badge?p=webpack-dev-middleware
[size-url]: https://packagephobia.com/result?p=webpack-dev-middleware
[docs-url]: https://webpack.js.org/guides/development/#using-webpack-dev-middleware
[hash-url]: https://twitter.com/search?q=webpack
[middleware-url]: https://github.com/webpack/webpack-dev-middleware
[stack-url]: https://stackoverflow.com/questions/tagged/webpack-dev-middleware
[wjo-url]: https://github.com/webpack/webpack.js.org


---

1.52.0 / 2022-02-21
===================

  * Add extensions from IANA for more `image/*` types
  * Add extension `.asc` to `application/pgp-keys`
  * Add extensions to various XML types
  * Add new upstream MIME types

1.51.0 / 2021-11-08
===================

  * Add new upstream MIME types
  * Mark `image/vnd.microsoft.icon` as compressible
  * Mark `image/vnd.ms-dds` as compressible

1.50.0 / 2021-09-15
===================

  * Add deprecated iWorks mime types and extensions
  * Add new upstream MIME types

1.49.0 / 2021-07-26
===================

  * Add extension `.trig` to `application/trig`
  * Add new upstream MIME types

1.48.0 / 2021-05-30
===================

  * Add extension `.mvt` to `application/vnd.mapbox-vector-tile`
  * Add new upstream MIME types
  * Mark `text/yaml` as compressible

1.47.0 / 2021-04-01
===================

  * Add new upstream MIME types
  * Remove ambigious extensions from IANA for `application/*+xml` types
  * Update primary extension to `.es` for `application/ecmascript`

1.46.0 / 2021-02-13
===================

  * Add extension `.amr` to `audio/amr`
  * Add extension `.m4s` to `video/iso.segment`
  * Add extension `.opus` to `audio/ogg`
  * Add new upstream MIME types

1.45.0 / 2020-09-22
===================

  * Add `application/ubjson` with extension `.ubj`
  * Add `image/avif` with extension `.avif`
  * Add `image/ktx2` with extension `.ktx2`
  * Add extension `.dbf` to `application/vnd.dbf`
  * Add extension `.rar` to `application/vnd.rar`
  * Add extension `.td` to `application/urc-targetdesc+xml`
  * Add new upstream MIME types
  * Fix extension of `application/vnd.apple.keynote` to be `.key`

1.44.0 / 2020-04-22
===================

  * Add charsets from IANA
  * Add extension `.cjs` to `application/node`
  * Add new upstream MIME types

1.43.0 / 2020-01-05
===================

  * Add `application/x-keepass2` with extension `.kdbx`
  * Add extension `.mxmf` to `audio/mobile-xmf`
  * Add extensions from IANA for `application/*+xml` types
  * Add new upstream MIME types

1.42.0 / 2019-09-25
===================

  * Add `image/vnd.ms-dds` with extension `.dds`
  * Add new upstream MIME types
  * Remove compressible from `multipart/mixed`

1.41.0 / 2019-08-30
===================

  * Add new upstream MIME types
  * Add `application/toml` with extension `.toml`
  * Mark `font/ttf` as compressible

1.40.0 / 2019-04-20
===================

  * Add extensions from IANA for `model/*` types
  * Add `text/mdx` with extension `.mdx`

1.39.0 / 2019-04-04
===================

  * Add extensions `.siv` and `.sieve` to `application/sieve`
  * Add new upstream MIME types

1.38.0 / 2019-02-04
===================

  * Add extension `.nq` to `application/n-quads`
  * Add extension `.nt` to `application/n-triples`
  * Add new upstream MIME types
  * Mark `text/less` as compressible

1.37.0 / 2018-10-19
===================

  * Add extensions to HEIC image types
  * Add new upstream MIME types

1.36.0 / 2018-08-20
===================

  * Add Apple file extensions from IANA
  * Add extensions from IANA for `image/*` types
  * Add new upstream MIME types

1.35.0 / 2018-07-15
===================

  * Add extension `.owl` to `application/rdf+xml`
  * Add new upstream MIME types
    - Removes extension `.woff` from `application/font-woff`

1.34.0 / 2018-06-03
===================

  * Add extension `.csl` to `application/vnd.citationstyles.style+xml`
  * Add extension `.es` to `application/ecmascript`
  * Add new upstream MIME types
  * Add `UTF-8` as default charset for `text/turtle`
  * Mark all XML-derived types as compressible

1.33.0 / 2018-02-15
===================

  * Add extensions from IANA for `message/*` types
  * Add new upstream MIME types
  * Fix some incorrect OOXML types
  * Remove `application/font-woff2`

1.32.0 / 2017-11-29
===================

  * Add new upstream MIME types
  * Update `text/hjson` to registered `application/hjson`
  * Add `text/shex` with extension `.shex`

1.31.0 / 2017-10-25
===================

  * Add `application/raml+yaml` with extension `.raml`
  * Add `application/wasm` with extension `.wasm`
  * Add new `font` type from IANA
  * Add new upstream font extensions
  * Add new upstream MIME types
  * Add extensions for JPEG-2000 images

1.30.0 / 2017-08-27
===================

  * Add `application/vnd.ms-outlook`
  * Add `application/x-arj`
  * Add extension `.mjs` to `application/javascript`
  * Add glTF types and extensions
  * Add new upstream MIME types
  * Add `text/x-org`
  * Add VirtualBox MIME types
  * Fix `source` records for `video/*` types that are IANA
  * Update `font/opentype` to registered `font/otf`

1.29.0 / 2017-07-10
===================

  * Add `application/fido.trusted-apps+json`
  * Add extension `.wadl` to `application/vnd.sun.wadl+xml`
  * Add new upstream MIME types
  * Add `UTF-8` as default charset for `text/css`

1.28.0 / 2017-05-14
===================

  * Add new upstream MIME types
  * Add extension `.gz` to `application/gzip`
  * Update extensions `.md` and `.markdown` to be `text/markdown`

1.27.0 / 2017-03-16
===================

  * Add new upstream MIME types
  * Add `image/apng` with extension `.apng`

1.26.0 / 2017-01-14
===================

  * Add new upstream MIME types
  * Add extension `.geojson` to `application/geo+json`

1.25.0 / 2016-11-11
===================

  * Add new upstream MIME types

1.24.0 / 2016-09-18
===================

  * Add `audio/mp3`
  * Add new upstream MIME types

1.23.0 / 2016-05-01
===================

  * Add new upstream MIME types
  * Add extension `.3gpp` to `audio/3gpp`

1.22.0 / 2016-02-15
===================

  * Add `text/slim`
  * Add extension `.rng` to `application/xml`
  * Add new upstream MIME types
  * Fix extension of `application/dash+xml` to be `.mpd`
  * Update primary extension to `.m4a` for `audio/mp4`

1.21.0 / 2016-01-06
===================

  * Add Google document types
  * Add new upstream MIME types

1.20.0 / 2015-11-10
===================

  * Add `text/x-suse-ymp`
  * Add new upstream MIME types

1.19.0 / 2015-09-17
===================

  * Add `application/vnd.apple.pkpass`
  * Add new upstream MIME types

1.18.0 / 2015-09-03
===================

  * Add new upstream MIME types

1.17.0 / 2015-08-13
===================

  * Add `application/x-msdos-program`
  * Add `audio/g711-0`
  * Add `image/vnd.mozilla.apng`
  * Add extension `.exe` to `application/x-msdos-program`

1.16.0 / 2015-07-29
===================

  * Add `application/vnd.uri-map`

1.15.0 / 2015-07-13
===================

  * Add `application/x-httpd-php`

1.14.0 / 2015-06-25
===================

  * Add `application/scim+json`
  * Add `application/vnd.3gpp.ussd+xml`
  * Add `application/vnd.biopax.rdf+xml`
  * Add `text/x-processing`

1.13.0 / 2015-06-07
===================

  * Add nginx as a source
  * Add `application/x-cocoa`
  * Add `application/x-java-archive-diff`
  * Add `application/x-makeself`
  * Add `application/x-perl`
  * Add `application/x-pilot`
  * Add `application/x-redhat-package-manager`
  * Add `application/x-sea`
  * Add `audio/x-m4a`
  * Add `audio/x-realaudio`
  * Add `image/x-jng`
  * Add `text/mathml`

1.12.0 / 2015-06-05
===================

  * Add `application/bdoc`
  * Add `application/vnd.hyperdrive+json`
  * Add `application/x-bdoc`
  * Add extension `.rtf` to `text/rtf`

1.11.0 / 2015-05-31
===================

  * Add `audio/wav`
  * Add `audio/wave`
  * Add extension `.litcoffee` to `text/coffeescript`
  * Add extension `.sfd-hdstx` to `application/vnd.hydrostatix.sof-data`
  * Add extension `.n-gage` to `application/vnd.nokia.n-gage.symbian.install`

1.10.0 / 2015-05-19
===================

  * Add `application/vnd.balsamiq.bmpr`
  * Add `application/vnd.microsoft.portable-executable`
  * Add `application/x-ns-proxy-autoconfig`

1.9.1 / 2015-04-19
==================

  * Remove `.json` extension from `application/manifest+json`
    - This is causing bugs downstream

1.9.0 / 2015-04-19
==================

  * Add `application/manifest+json`
  * Add `application/vnd.micro+json`
  * Add `image/vnd.zbrush.pcx`
  * Add `image/x-ms-bmp`

1.8.0 / 2015-03-13
==================

  * Add `application/vnd.citationstyles.style+xml`
  * Add `application/vnd.fastcopy-disk-image`
  * Add `application/vnd.gov.sk.xmldatacontainer+xml`
  * Add extension `.jsonld` to `application/ld+json`

1.7.0 / 2015-02-08
==================

  * Add `application/vnd.gerber`
  * Add `application/vnd.msa-disk-image`

1.6.1 / 2015-02-05
==================

  * Community extensions ownership transferred from `node-mime`

1.6.0 / 2015-01-29
==================

  * Add `application/jose`
  * Add `application/jose+json`
  * Add `application/json-seq`
  * Add `application/jwk+json`
  * Add `application/jwk-set+json`
  * Add `application/jwt`
  * Add `application/rdap+json`
  * Add `application/vnd.gov.sk.e-form+xml`
  * Add `application/vnd.ims.imsccv1p3`

1.5.0 / 2014-12-30
==================

  * Add `application/vnd.oracle.resource+json`
  * Fix various invalid MIME type entries
    - `application/mbox+xml`
    - `application/oscp-response`
    - `application/vwg-multiplexed`
    - `audio/g721`

1.4.0 / 2014-12-21
==================

  * Add `application/vnd.ims.imsccv1p2`
  * Fix various invalid MIME type entries
    - `application/vnd-acucobol`
    - `application/vnd-curl`
    - `application/vnd-dart`
    - `application/vnd-dxr`
    - `application/vnd-fdf`
    - `application/vnd-mif`
    - `application/vnd-sema`
    - `application/vnd-wap-wmlc`
    - `application/vnd.adobe.flash-movie`
    - `application/vnd.dece-zip`
    - `application/vnd.dvb_service`
    - `application/vnd.micrografx-igx`
    - `application/vnd.sealed-doc`
    - `application/vnd.sealed-eml`
    - `application/vnd.sealed-mht`
    - `application/vnd.sealed-ppt`
    - `application/vnd.sealed-tiff`
    - `application/vnd.sealed-xls`
    - `application/vnd.sealedmedia.softseal-html`
    - `application/vnd.sealedmedia.softseal-pdf`
    - `application/vnd.wap-slc`
    - `application/vnd.wap-wbxml`
    - `audio/vnd.sealedmedia.softseal-mpeg`
    - `image/vnd-djvu`
    - `image/vnd-svf`
    - `image/vnd-wap-wbmp`
    - `image/vnd.sealed-png`
    - `image/vnd.sealedmedia.softseal-gif`
    - `image/vnd.sealedmedia.softseal-jpg`
    - `model/vnd-dwf`
    - `model/vnd.parasolid.transmit-binary`
    - `model/vnd.parasolid.transmit-text`
    - `text/vnd-a`
    - `text/vnd-curl`
    - `text/vnd.wap-wml`
  * Remove example template MIME types
    - `application/example`
    - `audio/example`
    - `image/example`
    - `message/example`
    - `model/example`
    - `multipart/example`
    - `text/example`
    - `video/example`

1.3.1 / 2014-12-16
==================

  * Fix missing extensions
    - `application/json5`
    - `text/hjson`

1.3.0 / 2014-12-07
==================

  * Add `application/a2l`
  * Add `application/aml`
  * Add `application/atfx`
  * Add `application/atxml`
  * Add `application/cdfx+xml`
  * Add `application/dii`
  * Add `application/json5`
  * Add `application/lxf`
  * Add `application/mf4`
  * Add `application/vnd.apache.thrift.compact`
  * Add `application/vnd.apache.thrift.json`
  * Add `application/vnd.coffeescript`
  * Add `application/vnd.enphase.envoy`
  * Add `application/vnd.ims.imsccv1p1`
  * Add `text/csv-schema`
  * Add `text/hjson`
  * Add `text/markdown`
  * Add `text/yaml`

1.2.0 / 2014-11-09
==================

  * Add `application/cea`
  * Add `application/dit`
  * Add `application/vnd.gov.sk.e-form+zip`
  * Add `application/vnd.tmd.mediaflex.api+xml`
  * Type `application/epub+zip` is now IANA-registered

1.1.2 / 2014-10-23
==================

  * Rebuild database for `application/x-www-form-urlencoded` change

1.1.1 / 2014-10-20
==================

  * Mark `application/x-www-form-urlencoded` as compressible.

1.1.0 / 2014-09-28
==================

  * Add `application/font-woff2`

1.0.3 / 2014-09-25
==================

  * Fix engine requirement in package

1.0.2 / 2014-09-25
==================

  * Add `application/coap-group+json`
  * Add `application/dcd`
  * Add `application/vnd.apache.thrift.binary`
  * Add `image/vnd.tencent.tap`
  * Mark all JSON-derived types as compressible
  * Update `text/vtt` data

1.0.1 / 2014-08-30
==================

  * Fix extension ordering

1.0.0 / 2014-08-30
==================

  * Add `application/atf`
  * Add `application/merge-patch+json`
  * Add `multipart/x-mixed-replace`
  * Add `source: 'apache'` metadata
  * Add `source: 'iana'` metadata
  * Remove badly-assumed charset data


---

# mime-db

[![NPM Version][npm-version-image]][npm-url]
[![NPM Downloads][npm-downloads-image]][npm-url]
[![Node.js Version][node-image]][node-url]
[![Build Status][ci-image]][ci-url]
[![Coverage Status][coveralls-image]][coveralls-url]

This is a large database of mime types and information about them.
It consists of a single, public JSON file and does not include any logic,
allowing it to remain as un-opinionated as possible with an API.
It aggregates data from the following sources:

- http://www.iana.org/assignments/media-types/media-types.xhtml
- http://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/conf/mime.types
- http://hg.nginx.org/nginx/raw-file/default/conf/mime.types

## Installation

```bash
npm install mime-db
```

### Database Download

If you're crazy enough to use this in the browser, you can just grab the
JSON file using [jsDelivr](https://www.jsdelivr.com/). It is recommended to
replace `master` with [a release tag](https://github.com/jshttp/mime-db/tags)
as the JSON format may change in the future.

```
https://cdn.jsdelivr.net/gh/jshttp/mime-db@master/db.json
```

## Usage

```js
var db = require('mime-db')

// grab data on .js files
var data = db['application/javascript']
```

## Data Structure

The JSON file is a map lookup for lowercased mime types.
Each mime type has the following properties:

- `.source` - where the mime type is defined.
    If not set, it's probably a custom media type.
    - `apache` - [Apache common media types](http://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/conf/mime.types)
    - `iana` - [IANA-defined media types](http://www.iana.org/assignments/media-types/media-types.xhtml)
    - `nginx` - [nginx media types](http://hg.nginx.org/nginx/raw-file/default/conf/mime.types)
- `.extensions[]` - known extensions associated with this mime type.
- `.compressible` - whether a file of this type can be gzipped.
- `.charset` - the default charset associated with this type, if any.

If unknown, every property could be `undefined`.

## Contributing

To edit the database, only make PRs against `src/custom-types.json` or
`src/custom-suffix.json`.

The `src/custom-types.json` file is a JSON object with the MIME type as the
keys and the values being an object with the following keys:

- `compressible` - leave out if you don't know, otherwise `true`/`false` to
  indicate whether the data represented by the type is typically compressible.
- `extensions` - include an array of file extensions that are associated with
  the type.
- `notes` - human-readable notes about the type, typically what the type is.
- `sources` - include an array of URLs of where the MIME type and the associated
  extensions are sourced from. This needs to be a [primary source](https://en.wikipedia.org/wiki/Primary_source);
  links to type aggregating sites and Wikipedia are _not acceptable_.

To update the build, run `npm run build`.

### Adding Custom Media Types

The best way to get new media types included in this library is to register
them with the IANA. The community registration procedure is outlined in
[RFC 6838 section 5](http://tools.ietf.org/html/rfc6838#section-5). Types
registered with the IANA are automatically pulled into this library.

If that is not possible / feasible, they can be added directly here as a
"custom" type. To do this, it is required to have a primary source that
definitively lists the media type. If an extension is going to be listed as
associateed with this media type, the source must definitively link the
media type and extension as well.

[ci-image]: https://badgen.net/github/checks/jshttp/mime-db/master?label=ci
[ci-url]: https://github.com/jshttp/mime-db/actions?query=workflow%3Aci
[coveralls-image]: https://badgen.net/coveralls/c/github/jshttp/mime-db/master
[coveralls-url]: https://coveralls.io/r/jshttp/mime-db?branch=master
[node-image]: https://badgen.net/npm/node/mime-db
[node-url]: https://nodejs.org/en/download
[npm-downloads-image]: https://badgen.net/npm/dm/mime-db
[npm-url]: https://npmjs.org/package/mime-db
[npm-version-image]: https://badgen.net/npm/v/mime-db


---

2.1.35 / 2022-03-12
===================

  * deps: mime-db@1.52.0
    - Add extensions from IANA for more `image/*` types
    - Add extension `.asc` to `application/pgp-keys`
    - Add extensions to various XML types
    - Add new upstream MIME types

2.1.34 / 2021-11-08
===================

  * deps: mime-db@1.51.0
    - Add new upstream MIME types

2.1.33 / 2021-10-01
===================

  * deps: mime-db@1.50.0
    - Add deprecated iWorks mime types and extensions
    - Add new upstream MIME types

2.1.32 / 2021-07-27
===================

  * deps: mime-db@1.49.0
    - Add extension `.trig` to `application/trig`
    - Add new upstream MIME types

2.1.31 / 2021-06-01
===================

  * deps: mime-db@1.48.0
    - Add extension `.mvt` to `application/vnd.mapbox-vector-tile`
    - Add new upstream MIME types

2.1.30 / 2021-04-02
===================

  * deps: mime-db@1.47.0
    - Add extension `.amr` to `audio/amr`
    - Remove ambigious extensions from IANA for `application/*+xml` types
    - Update primary extension to `.es` for `application/ecmascript`

2.1.29 / 2021-02-17
===================

  * deps: mime-db@1.46.0
    - Add extension `.amr` to `audio/amr`
    - Add extension `.m4s` to `video/iso.segment`
    - Add extension `.opus` to `audio/ogg`
    - Add new upstream MIME types

2.1.28 / 2021-01-01
===================

  * deps: mime-db@1.45.0
    - Add `application/ubjson` with extension `.ubj`
    - Add `image/avif` with extension `.avif`
    - Add `image/ktx2` with extension `.ktx2`
    - Add extension `.dbf` to `application/vnd.dbf`
    - Add extension `.rar` to `application/vnd.rar`
    - Add extension `.td` to `application/urc-targetdesc+xml`
    - Add new upstream MIME types
    - Fix extension of `application/vnd.apple.keynote` to be `.key`

2.1.27 / 2020-04-23
===================

  * deps: mime-db@1.44.0
    - Add charsets from IANA
    - Add extension `.cjs` to `application/node`
    - Add new upstream MIME types

2.1.26 / 2020-01-05
===================

  * deps: mime-db@1.43.0
    - Add `application/x-keepass2` with extension `.kdbx`
    - Add extension `.mxmf` to `audio/mobile-xmf`
    - Add extensions from IANA for `application/*+xml` types
    - Add new upstream MIME types

2.1.25 / 2019-11-12
===================

  * deps: mime-db@1.42.0
    - Add new upstream MIME types
    - Add `application/toml` with extension `.toml`
    - Add `image/vnd.ms-dds` with extension `.dds`

2.1.24 / 2019-04-20
===================

  * deps: mime-db@1.40.0
    - Add extensions from IANA for `model/*` types
    - Add `text/mdx` with extension `.mdx`

2.1.23 / 2019-04-17
===================

  * deps: mime-db@~1.39.0
    - Add extensions `.siv` and `.sieve` to `application/sieve`
    - Add new upstream MIME types

2.1.22 / 2019-02-14
===================

  * deps: mime-db@~1.38.0
    - Add extension `.nq` to `application/n-quads`
    - Add extension `.nt` to `application/n-triples`
    - Add new upstream MIME types

2.1.21 / 2018-10-19
===================

  * deps: mime-db@~1.37.0
    - Add extensions to HEIC image types
    - Add new upstream MIME types

2.1.20 / 2018-08-26
===================

  * deps: mime-db@~1.36.0
    - Add Apple file extensions from IANA
    - Add extensions from IANA for `image/*` types
    - Add new upstream MIME types

2.1.19 / 2018-07-17
===================

  * deps: mime-db@~1.35.0
    - Add extension `.csl` to `application/vnd.citationstyles.style+xml`
    - Add extension `.es` to `application/ecmascript`
    - Add extension `.owl` to `application/rdf+xml`
    - Add new upstream MIME types
    - Add UTF-8 as default charset for `text/turtle`

2.1.18 / 2018-02-16
===================

  * deps: mime-db@~1.33.0
    - Add `application/raml+yaml` with extension `.raml`
    - Add `application/wasm` with extension `.wasm`
    - Add `text/shex` with extension `.shex`
    - Add extensions for JPEG-2000 images
    - Add extensions from IANA for `message/*` types
    - Add new upstream MIME types
    - Update font MIME types
    - Update `text/hjson` to registered `application/hjson`

2.1.17 / 2017-09-01
===================

  * deps: mime-db@~1.30.0
    - Add `application/vnd.ms-outlook`
    - Add `application/x-arj`
    - Add extension `.mjs` to `application/javascript`
    - Add glTF types and extensions
    - Add new upstream MIME types
    - Add `text/x-org`
    - Add VirtualBox MIME types
    - Fix `source` records for `video/*` types that are IANA
    - Update `font/opentype` to registered `font/otf`

2.1.16 / 2017-07-24
===================

  * deps: mime-db@~1.29.0
    - Add `application/fido.trusted-apps+json`
    - Add extension `.wadl` to `application/vnd.sun.wadl+xml`
    - Add extension `.gz` to `application/gzip`
    - Add new upstream MIME types
    - Update extensions `.md` and `.markdown` to be `text/markdown`

2.1.15 / 2017-03-23
===================

  * deps: mime-db@~1.27.0
    - Add new mime types
    - Add `image/apng`

2.1.14 / 2017-01-14
===================

  * deps: mime-db@~1.26.0
    - Add new mime types

2.1.13 / 2016-11-18
===================

  * deps: mime-db@~1.25.0
    - Add new mime types

2.1.12 / 2016-09-18
===================

  * deps: mime-db@~1.24.0
    - Add new mime types
    - Add `audio/mp3`

2.1.11 / 2016-05-01
===================

  * deps: mime-db@~1.23.0
    - Add new mime types

2.1.10 / 2016-02-15
===================

  * deps: mime-db@~1.22.0
    - Add new mime types
    - Fix extension of `application/dash+xml`
    - Update primary extension for `audio/mp4`

2.1.9 / 2016-01-06
==================

  * deps: mime-db@~1.21.0
    - Add new mime types

2.1.8 / 2015-11-30
==================

  * deps: mime-db@~1.20.0
    - Add new mime types

2.1.7 / 2015-09-20
==================

  * deps: mime-db@~1.19.0
    - Add new mime types

2.1.6 / 2015-09-03
==================

  * deps: mime-db@~1.18.0
    - Add new mime types

2.1.5 / 2015-08-20
==================

  * deps: mime-db@~1.17.0
    - Add new mime types

2.1.4 / 2015-07-30
==================

  * deps: mime-db@~1.16.0
    - Add new mime types

2.1.3 / 2015-07-13
==================

  * deps: mime-db@~1.15.0
    - Add new mime types

2.1.2 / 2015-06-25
==================

  * deps: mime-db@~1.14.0
    - Add new mime types

2.1.1 / 2015-06-08
==================

  * perf: fix deopt during mapping

2.1.0 / 2015-06-07
==================

  * Fix incorrectly treating extension-less file name as extension
    - i.e. `'path/to/json'` will no longer return `application/json`
  * Fix `.charset(type)` to accept parameters
  * Fix `.charset(type)` to match case-insensitive
  * Improve generation of extension to MIME mapping
  * Refactor internals for readability and no argument reassignment
  * Prefer `application/*` MIME types from the same source
  * Prefer any type over `application/octet-stream`
  * deps: mime-db@~1.13.0
    - Add nginx as a source
    - Add new mime types

2.0.14 / 2015-06-06
===================

  * deps: mime-db@~1.12.0
    - Add new mime types

2.0.13 / 2015-05-31
===================

  * deps: mime-db@~1.11.0
    - Add new mime types

2.0.12 / 2015-05-19
===================

  * deps: mime-db@~1.10.0
    - Add new mime types

2.0.11 / 2015-05-05
===================

  * deps: mime-db@~1.9.1
    - Add new mime types

2.0.10 / 2015-03-13
===================

  * deps: mime-db@~1.8.0
    - Add new mime types

2.0.9 / 2015-02-09
==================

  * deps: mime-db@~1.7.0
    - Add new mime types
    - Community extensions ownership transferred from `node-mime`

2.0.8 / 2015-01-29
==================

  * deps: mime-db@~1.6.0
    - Add new mime types

2.0.7 / 2014-12-30
==================

  * deps: mime-db@~1.5.0
    - Add new mime types
    - Fix various invalid MIME type entries

2.0.6 / 2014-12-30
==================

  * deps: mime-db@~1.4.0
    - Add new mime types
    - Fix various invalid MIME type entries
    - Remove example template MIME types

2.0.5 / 2014-12-29
==================

  * deps: mime-db@~1.3.1
    - Fix missing extensions

2.0.4 / 2014-12-10
==================

  * deps: mime-db@~1.3.0
    - Add new mime types

2.0.3 / 2014-11-09
==================

  * deps: mime-db@~1.2.0
    - Add new mime types

2.0.2 / 2014-09-28
==================

  * deps: mime-db@~1.1.0
    - Add new mime types
    - Update charsets

2.0.1 / 2014-09-07
==================

  * Support Node.js 0.6

2.0.0 / 2014-09-02
==================

  * Use `mime-db`
  * Remove `.define()`

1.0.2 / 2014-08-04
==================

  * Set charset=utf-8 for `text/javascript`

1.0.1 / 2014-06-24
==================

  * Add `text/jsx` type

1.0.0 / 2014-05-12
==================

  * Return `false` for unknown types
  * Set charset=utf-8 for `application/json`

0.1.0 / 2014-05-02
==================

  * Initial release


---

# mime-types

[![NPM Version][npm-version-image]][npm-url]
[![NPM Downloads][npm-downloads-image]][npm-url]
[![Node.js Version][node-version-image]][node-version-url]
[![Build Status][ci-image]][ci-url]
[![Test Coverage][coveralls-image]][coveralls-url]

The ultimate javascript content-type utility.

Similar to [the `mime@1.x` module](https://www.npmjs.com/package/mime), except:

- __No fallbacks.__ Instead of naively returning the first available type,
  `mime-types` simply returns `false`, so do
  `var type = mime.lookup('unrecognized') || 'application/octet-stream'`.
- No `new Mime()` business, so you could do `var lookup = require('mime-types').lookup`.
- No `.define()` functionality
- Bug fixes for `.lookup(path)`

Otherwise, the API is compatible with `mime` 1.x.

## Install

This is a [Node.js](https://nodejs.org/en/) module available through the
[npm registry](https://www.npmjs.com/). Installation is done using the
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):

```sh
$ npm install mime-types
```

## Adding Types

All mime types are based on [mime-db](https://www.npmjs.com/package/mime-db),
so open a PR there if you'd like to add mime types.

## API

```js
var mime = require('mime-types')
```

All functions return `false` if input is invalid or not found.

### mime.lookup(path)

Lookup the content-type associated with a file.

```js
mime.lookup('json') // 'application/json'
mime.lookup('.md') // 'text/markdown'
mime.lookup('file.html') // 'text/html'
mime.lookup('folder/file.js') // 'application/javascript'
mime.lookup('folder/.htaccess') // false

mime.lookup('cats') // false
```

### mime.contentType(type)

Create a full content-type header given a content-type or extension.
When given an extension, `mime.lookup` is used to get the matching
content-type, otherwise the given content-type is used. Then if the
content-type does not already have a `charset` parameter, `mime.charset`
is used to get the default charset and add to the returned content-type.

```js
mime.contentType('markdown') // 'text/x-markdown; charset=utf-8'
mime.contentType('file.json') // 'application/json; charset=utf-8'
mime.contentType('text/html') // 'text/html; charset=utf-8'
mime.contentType('text/html; charset=iso-8859-1') // 'text/html; charset=iso-8859-1'

// from a full path
mime.contentType(path.extname('/path/to/file.json')) // 'application/json; charset=utf-8'
```

### mime.extension(type)

Get the default extension for a content-type.

```js
mime.extension('application/octet-stream') // 'bin'
```

### mime.charset(type)

Lookup the implied default charset of a content-type.

```js
mime.charset('text/markdown') // 'UTF-8'
```

### var type = mime.types[extension]

A map of content-types by extension.

### [extensions...] = mime.extensions[type]

A map of extensions by content-type.

## License

[MIT](LICENSE)

[ci-image]: https://badgen.net/github/checks/jshttp/mime-types/master?label=ci
[ci-url]: https://github.com/jshttp/mime-types/actions/workflows/ci.yml
[coveralls-image]: https://badgen.net/coveralls/c/github/jshttp/mime-types/master
[coveralls-url]: https://coveralls.io/r/jshttp/mime-types?branch=master
[node-version-image]: https://badgen.net/npm/node/mime-types
[node-version-url]: https://nodejs.org/en/download
[npm-downloads-image]: https://badgen.net/npm/dm/mime-types
[npm-url]: https://npmjs.org/package/mime-types
[npm-version-image]: https://badgen.net/npm/v/mime-types


---

1.2.1 / 2019-05-10
==================

  * Improve error when `str` is not a string

1.2.0 / 2016-06-01
==================

  * Add `combine` option to combine overlapping ranges

1.1.0 / 2016-05-13
==================

  * Fix incorrectly returning -1 when there is at least one valid range
  * perf: remove internal function

1.0.3 / 2015-10-29
==================

  * perf: enable strict mode

1.0.2 / 2014-09-08
==================

  * Support Node.js 0.6

1.0.1 / 2014-09-07
==================

  * Move repository to jshttp

1.0.0 / 2013-12-11
==================

  * Add repository to package.json
  * Add MIT license

0.0.4 / 2012-06-17
==================

  * Change ret -1 for unsatisfiable and -2 when invalid

0.0.3 / 2012-06-17
==================

  * Fix last-byte-pos default to len - 1

0.0.2 / 2012-06-14
==================

  * Add `.type`

0.0.1 / 2012-06-11
==================

  * Initial release


---

# range-parser

[![NPM Version][npm-version-image]][npm-url]
[![NPM Downloads][npm-downloads-image]][npm-url]
[![Node.js Version][node-image]][node-url]
[![Build Status][travis-image]][travis-url]
[![Test Coverage][coveralls-image]][coveralls-url]

Range header field parser.

## Installation

This is a [Node.js](https://nodejs.org/en/) module available through the
[npm registry](https://www.npmjs.com/). Installation is done using the
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):

```sh
$ npm install range-parser
```

## API

<!-- eslint-disable no-unused-vars -->

```js
var parseRange = require('range-parser')
```

### parseRange(size, header, options)

Parse the given `header` string where `size` is the maximum size of the resource.
An array of ranges will be returned or negative numbers indicating an error parsing.

  * `-2` signals a malformed header string
  * `-1` signals an unsatisfiable range

<!-- eslint-disable no-undef -->

```js
// parse header from request
var range = parseRange(size, req.headers.range)

// the type of the range
if (range.type === 'bytes') {
  // the ranges
  range.forEach(function (r) {
    // do something with r.start and r.end
  })
}
```

#### Options

These properties are accepted in the options object.

##### combine

Specifies if overlapping & adjacent ranges should be combined, defaults to `false`.
When `true`, ranges will be combined and returned as if they were specified that
way in the header.

<!-- eslint-disable no-undef -->

```js
parseRange(100, 'bytes=50-55,0-10,5-10,56-60', { combine: true })
// => [
//      { start: 0,  end: 10 },
//      { start: 50, end: 60 }
//    ]
```

## License

[MIT](LICENSE)

[coveralls-image]: https://badgen.net/coveralls/c/github/jshttp/range-parser/master
[coveralls-url]: https://coveralls.io/r/jshttp/range-parser?branch=master
[node-image]: https://badgen.net/npm/node/range-parser
[node-url]: https://nodejs.org/en/download
[npm-downloads-image]: https://badgen.net/npm/dm/range-parser
[npm-url]: https://npmjs.org/package/range-parser
[npm-version-image]: https://badgen.net/npm/v/range-parser
[travis-image]: https://badgen.net/travis/jshttp/range-parser/master
[travis-url]: https://travis-ci.org/jshttp/range-parser


---

<div align="center">
  <a href="https://github.com/webpack/webpack">
    <img width="200" height="200" src="https://webpack.js.org/assets/icon-square-big.svg">
  </a>
</div>

[![npm][npm]][npm-url]
[![node][node]][node-url]
[![tests][tests]][tests-url]
[![coverage][cover]][cover-url]
[![chat][chat]][chat-url]
[![downloads][downloads]][npm-url]
[![contributors][contributors]][contributors-url]

# webpack-dev-server

Use [webpack](https://webpack.js.org) with a development server that provides
live reloading. This should be used for **development only**.

It uses [webpack-dev-middleware][middleware-url] under the hood, which provides
fast in-memory access to the webpack assets.

## Table of Contents

- [Getting Started](#getting-started)
- [Usage](#usage)
  - [With the CLI](#with-the-cli)
  - [With NPM Scripts](#with-npm-scripts)
  - [With the API](#with-the-api)
  - [With TypeScript](#with-typescript)
  - [The Result](#the-result)
- [Browser Support](#browser-support)
- [Support](#support)
- [Contributing](#contributing)
- [Attribution](#attribution)
- [License](#license)

## Getting Started

First things first, install the module:

```console
npm install webpack-dev-server --save-dev
```

or

```console
yarn add -D webpack-dev-server
```

or

```console
pnpm add -D webpack-dev-server
```

_Note: While you can install and run webpack-dev-server globally, we recommend
installing it locally. webpack-dev-server will always use a local installation
over a global one._

## Usage

There are two main, recommended methods of using the module:

### With the CLI

The easiest way to use it is with the [webpack CLI](https://webpack.js.org/api/cli/). In the directory where your
`webpack.config.js` is, run:

```console
npx webpack serve
```

Following options are available with `webpack serve`:

```
Usage: webpack serve|server|s [entries...] [options]

Run the webpack dev server.

Options:
  -c, --config <value...>                             Provide path to a webpack configuration file e.g. ./webpack.config.js.
  --config-name <value...>                            Name of the configuration to use.
  -m, --merge                                         Merge two or more configurations using 'webpack-merge'.
  --env <value...>                                    Environment passed to the configuration when it is a function.
  --node-env <value>                                  Sets process.env.NODE_ENV to the specified value.
  --progress [value]                                  Print compilation progress during build.
  -j, --json [value]                                  Prints result as JSON or store it in a file.
  -d, --devtool <value>                               Determine source maps to use.
  --no-devtool                                        Do not generate source maps.
  --entry <value...>                                  The entry point(s) of your application e.g. ./src/main.js.
  --mode <value>                                      Defines the mode to pass to webpack.
  --name <value>                                      Name of the configuration. Used when loading multiple configurations.
  -o, --output-path <value>                           Output location of the file generated by webpack e.g. ./dist/.
  --stats [value]                                     It instructs webpack on how to treat the stats e.g. verbose.
  --no-stats                                          Disable stats output.
  -t, --target <value...>                             Sets the build target e.g. node.
  --no-target                                         Negative 'target' option.
  --watch-options-stdin                               Stop watching when stdin stream has ended.
  --no-watch-options-stdin                            Do not stop watching when stdin stream has ended.
  --allowed-hosts <value...>                          Allows to enumerate the hosts from which access to the dev server are allowed (useful when you are proxying dev server, by default is 'auto').
  --allowed-hosts-reset                               Clear all items provided in 'allowedHosts' configuration. Allows to enumerate the hosts from which access to the dev server are allowed (useful when you are proxying dev server, by default is 'auto').
  --bonjour                                           Allows to broadcasts dev server via ZeroConf networking on start.
  --no-bonjour                                        Disallows to broadcasts dev server via ZeroConf networking on start.
  --no-client                                         Disables client script.
  --client-logging <value>                            Allows to set log level in the browser.
  --client-overlay                                    Enables a full-screen overlay in the browser when there are compiler errors or warnings.
  --no-client-overlay                                 Disables the full-screen overlay in the browser when there are compiler errors or warnings.
  --client-overlay-errors                             Enables a full-screen overlay in the browser when there are compiler errors.
  --no-client-overlay-errors                          Disables the full-screen overlay in the browser when there are compiler errors.
  --client-overlay-warnings                           Enables a full-screen overlay in the browser when there are compiler warnings.
  --no-client-overlay-warnings                        Disables the full-screen overlay in the browser when there are compiler warnings.
  --client-overlay-trusted-types-policy-name <value>  The name of a Trusted Types policy for the overlay. Defaults to 'webpack-dev-server#overlay'.
  --client-progress                                   Prints compilation progress in percentage in the browser.
  --no-client-progress                                Does not print compilation progress in percentage in the browser.
  --client-reconnect [value]                          Tells dev-server the number of times it should try to reconnect the client.
  --no-client-reconnect                               Tells dev-server to not to try to reconnect the client.
  --client-web-socket-transport <value>               Allows to set custom web socket transport to communicate with dev server.
  --client-web-socket-url <value>                     Allows to specify URL to web socket server (useful when you're proxying dev server and client script does not always know where to connect to).
  --client-web-socket-url-hostname <value>            Tells clients connected to devServer to use the provided hostname.
  --client-web-socket-url-pathname <value>            Tells clients connected to devServer to use the provided path to connect.
  --client-web-socket-url-password <value>            Tells clients connected to devServer to use the provided password to authenticate.
  --client-web-socket-url-port <value>                Tells clients connected to devServer to use the provided port.
  --client-web-socket-url-protocol <value>            Tells clients connected to devServer to use the provided protocol.
  --client-web-socket-url-username <value>            Tells clients connected to devServer to use the provided username to authenticate.
  --compress                                          Enables gzip compression for everything served.
  --no-compress                                       Disables gzip compression for everything served.
  --history-api-fallback                              Allows to proxy requests through a specified index page (by default 'index.html'), useful for Single Page Applications that utilise the HTML5 History API.
  --no-history-api-fallback                           Disallows to proxy requests through a specified index page.
  --host <value>                                      Allows to specify a hostname to use.
  --hot [value]                                       Enables Hot Module Replacement.
  --no-hot                                            Disables Hot Module Replacement.
  --http2                                             Allows to serve over HTTP/2 using SPDY. Deprecated, use the `server` option.
  --no-http2                                          Does not serve over HTTP/2 using SPDY.
  --https                                             Allows to configure the server's listening socket for TLS (by default, dev server will be served over HTTP). Deprecated, use the `server` option.
  --no-https                                          Disallows to configure the server's listening socket for TLS (by default, dev server will be served over HTTP).
  --https-passphrase <value>                          Passphrase for a pfx file. Deprecated, use the `server.options.passphrase` option.
  --https-request-cert                                Request for an SSL certificate. Deprecated, use the `server.options.requestCert` option.
  --no-https-request-cert                             Does not request for an SSL certificate.
  --https-ca <value...>                               Path to an SSL CA certificate or content of an SSL CA certificate. Deprecated, use the `server.options.ca` option.
  --https-ca-reset                                    Clear all items provided in 'https.ca' configuration. Path to an SSL CA certificate or content of an SSL CA certificate. Deprecated, use the `server.options.ca` option.
  --https-cacert <value...>                           Path to an SSL CA certificate or content of an SSL CA certificate. Deprecated, use the `server.options.ca` option.
  --https-cacert-reset                                Clear all items provided in 'https.cacert' configuration. Path to an SSL CA certificate or content of an SSL CA certificate. Deprecated, use the `server.options.ca` option.
  --https-cert <value...>                             Path to an SSL certificate or content of an SSL certificate. Deprecated, use the `server.options.cert` option.
  --https-cert-reset                                  Clear all items provided in 'https.cert' configuration. Path to an SSL certificate or content of an SSL certificate. Deprecated, use the `server.options.cert` option.
  --https-crl <value...>                              Path to PEM formatted CRLs (Certificate Revocation Lists) or content of PEM formatted CRLs (Certificate Revocation Lists). Deprecated, use the `server.options.crl` option.
  --https-crl-reset                                   Clear all items provided in 'https.crl' configuration. Path to PEM formatted CRLs (Certificate Revocation Lists) or content of PEM formatted CRLs (Certificate Revocation Lists). Deprecated, use the `server.options.crl` option.
  --https-key <value...>                              Path to an SSL key or content of an SSL key. Deprecated, use the `server.options.key` option.
  --https-key-reset                                   Clear all items provided in 'https.key' configuration. Path to an SSL key or content of an SSL key. Deprecated, use the `server.options.key` option.
  --https-pfx <value...>                              Path to an SSL pfx file or content of an SSL pfx file. Deprecated, use the `server.options.pfx` option.
  --https-pfx-reset                                   Clear all items provided in 'https.pfx' configuration. Path to an SSL pfx file or content of an SSL pfx file. Deprecated, use the `server.options.pfx` option.
  --ipc [value]                                       Listen to a unix socket.
  --live-reload                                       Enables reload/refresh the page(s) when file changes are detected (enabled by default).
  --no-live-reload                                    Disables reload/refresh the page(s) when file changes are detected (enabled by default).
  --magic-html                                        Tells dev-server whether to enable magic HTML routes (routes corresponding to your webpack output, for example '/main' for 'main.js').
  --no-magic-html                                     Disables magic HTML routes (routes corresponding to your webpack output, for example '/main' for 'main.js').
  --open [value...]                                   Allows to configure dev server to open the browser(s) and page(s) after server had been started (set it to true to open your default browser).
  --no-open                                           Does not open the default browser.
  --open-target <value...>                            Opens specified page in browser.
  --open-app-name <value...>                          Open specified browser.
  --open-app <value...>                               Open specified browser. Deprecated: please use '--open-app-name'.
  --open-reset                                        Clear all items provided in 'open' configuration. Allows to configure dev server to open the browser(s) and page(s) after server had been started (set it to true to open your default browser).
  --open-target-reset                                 Clear all items provided in 'open.target' configuration. Opens specified page in browser.
  --open-app-name-reset                               Clear all items provided in 'open.app.name' configuration. Open specified browser.
  --port <value>                                      Allows to specify a port to use.
  --server-type <value>                               Allows to set server and options (by default 'http').
  --server-options-passphrase <value>                 Passphrase for a pfx file.
  --server-options-request-cert                       Request for an SSL certificate.
  --no-server-options-request-cert                    Does not request for an SSL certificate.
  --server-options-ca <value...>                      Path to an SSL CA certificate or content of an SSL CA certificate.
  --server-options-ca-reset                           Clear all items provided in 'server.options.ca' configuration. Path to an SSL CA certificate or content of an SSL CA certificate.
  --server-options-cacert <value...>                  Path to an SSL CA certificate or content of an SSL CA certificate. Deprecated, use the `server.options.ca` option.
  --server-options-cacert-reset                       Clear all items provided in 'server.options.cacert' configuration. Path to an SSL CA certificate or content of an SSL CA certificate. Deprecated, use the `server.options.ca` option.
  --server-options-cert <value...>                    Path to an SSL certificate or content of an SSL certificate.
  --server-options-cert-reset                         Clear all items provided in 'server.options.cert' configuration. Path to an SSL certificate or content of an SSL certificate.
  --server-options-crl <value...>                     Path to PEM formatted CRLs (Certificate Revocation Lists) or content of PEM formatted CRLs (Certificate Revocation Lists).
  --server-options-crl-reset                          Clear all items provided in 'server.options.crl' configuration. Path to PEM formatted CRLs (Certificate Revocation Lists) or content of PEM formatted CRLs (Certificate Revocation Lists).
  --server-options-key <value...>                     Path to an SSL key or content of an SSL key.
  --server-options-key-reset                          Clear all items provided in 'server.options.key' configuration. Path to an SSL key or content of an SSL key.
  --server-options-pfx <value...>                     Path to an SSL pfx file or content of an SSL pfx file.
  --server-options-pfx-reset                          Clear all items provided in 'server.options.pfx' configuration. Path to an SSL pfx file or content of an SSL pfx file.
  --static [value...]                                 Allows to configure options for serving static files from directory (by default 'public' directory).
  --no-static                                         Disallows to configure options for serving static files from directory.
  --static-directory <value...>                       Directory for static contents.
  --static-public-path <value...>                     The static files will be available in the browser under this public path.
  --static-serve-index                                Tells dev server to use serveIndex middleware when enabled.
  --no-static-serve-index                             Does not tell dev server to use serveIndex middleware.
  --static-watch                                      Watches for files in static content directory.
  --no-static-watch                                   Does not watch for files in static content directory.
  --static-reset                                      Clear all items provided in 'static' configuration. Allows to configure options for serving static files from directory (by default 'public' directory).
  --static-public-path-reset                          Clear all items provided in 'static.publicPath' configuration. The static files will be available in the browser under this public path.
  --watch-files <value...>                            Allows to configure list of globs/directories/files to watch for file changes.
  --watch-files-reset                                 Clear all items provided in 'watchFiles' configuration. Allows to configure list of globs/directories/files to watch for file changes.
  --web-socket-server <value>                         Deprecated: please use '--web-socket-server-type' option. Allows to set web socket server and options (by default 'ws').
  --no-web-socket-server                              Disallows to set web socket server and options.
  --web-socket-server-type <value>                    Allows to set web socket server and options (by default 'ws').

Global options:
  --color                                             Enable colors on console.
  --no-color                                          Disable colors on console.
  -v, --version                                       Output the version number of 'webpack', 'webpack-cli' and 'webpack-dev-server' and commands.
  -h, --help [verbose]                                Display help for commands and options.

To see list of all supported commands and options run 'webpack --help=verbose'.

Webpack documentation: https://webpack.js.org/.
CLI documentation: https://webpack.js.org/api/cli/.
Made with ♥ by the webpack team.
```

> **Note**
>
> _Detailed documentation for above options is available on this [link](https://webpack.js.org/configuration/dev-server/)._

### With NPM Scripts

NPM package.json scripts are a convenient and useful means to run locally installed
binaries without having to be concerned about their full paths. Simply define a
script as such:

```json
{
  "scripts": {
    "serve": "webpack serve"
  }
}
```

And run the following in your terminal/console:

```console
npm run serve
```

NPM will automatically refer to the the binary in `node_modules` for you, and
execute the file or command.

### With the API

While it's recommended to run webpack-dev-server via the CLI, you may also choose to start a server via the API.

See the related [API documentation for `webpack-dev-server`](https://webpack.js.org/api/webpack-dev-server/).

### With TypeScript

If you use TypeScript in the webpack config, you'll need to properly type `devServer` property in order to avoid TS errors (e.g. `'devServer' does not exist in type 'Configuration'`). For that use either:

```ts
/// <reference path="node_modules/webpack-dev-server/types/lib/Server.d.ts"/>
import type { Configuration } from "webpack";

// Your logic
```

Or you can import the type from `webpack-dev-server`, i.e.

```ts
import type { Configuration as DevServerConfiguration } from "webpack-dev-server";
import type { Configuration } from "webpack";

const devServer: DevServerConfiguration = {};
const config: Configuration = { devServer };

// module.exports
export default config;
```

### The Result

Either method will start a server instance and begin listening for connections
from `localhost` on port `8080`.

webpack-dev-server is configured by default to support live-reload of files as
you edit your assets while the server is running.

See [**the documentation**][docs-url] for more use cases and options.

## Browser Support

While `webpack-dev-server` transpiles the client (browser) scripts to an ES5
state, the project only officially supports the _last two versions of major
browsers_. We simply don't have the resources to support every whacky
browser out there.

If you find a bug with an obscure / old browser, we would actively welcome a
Pull Request to resolve the bug.

## Support

We do our best to keep issues in the repository focused on bugs, features, and
needed modifications to the code for the module. Because of that, we ask users
with general support, "how-to", or "why isn't this working" questions to try one
of the other support channels that are available.

Your first-stop-shop for support for webpack-dev-server should be the excellent
[documentation][docs-url] for the module. If you see an opportunity for improvement
of those docs, please head over to the [webpack.js.org repo][wjo-url] and open a
pull request.

From there, we encourage users to visit the [webpack Gitter chat][chat-url] and
talk to the fine folks there. If your quest for answers comes up dry in chat,
head over to [StackOverflow][stack-url] and do a quick search or open a new
question. Remember; It's always much easier to answer questions that include your
`webpack.config.js` and relevant files!

If you're twitter-savvy you can tweet [#webpack][hash-url] with your question
and someone should be able to reach out and lend a hand.

If you have discovered a :bug:, have a feature suggestion, or would like to see
a modification, please feel free to create an issue on Github. _Note: The issue
template isn't optional, so please be sure not to remove it, and please fill it
out completely._

## Contributing

We welcome your contributions! Please have a read of [CONTRIBUTING.md](CONTRIBUTING.md) for more information on how to get involved.

## Attribution

This project is heavily inspired by [peerigon/nof5](https://github.com/peerigon/nof5).

## License

#### [MIT](./LICENSE)

[npm]: https://img.shields.io/npm/v/webpack-dev-server.svg
[npm-url]: https://npmjs.com/package/webpack-dev-server
[node]: https://img.shields.io/node/v/webpack-dev-server.svg
[node-url]: https://nodejs.org
[tests]: https://github.com/webpack/webpack-dev-server/workflows/webpack-dev-server/badge.svg
[tests-url]: https://github.com/webpack/webpack-dev-server/actions?query=workflow%3Awebpack-dev-server
[cover]: https://codecov.io/gh/webpack/webpack-dev-server/branch/master/graph/badge.svg
[cover-url]: https://codecov.io/gh/webpack/webpack-dev-server
[chat]: https://badges.gitter.im/webpack/webpack.svg
[chat-url]: https://gitter.im/webpack/webpack
[docs-url]: https://webpack.js.org/configuration/dev-server/#devserver
[hash-url]: https://twitter.com/search?q=webpack
[middleware-url]: https://github.com/webpack/webpack-dev-middleware
[stack-url]: https://stackoverflow.com/questions/tagged/webpack-dev-server
[uglify-url]: https://github.com/webpack-contrib/uglifyjs-webpack-plugin
[wjo-url]: https://github.com/webpack/webpack.js.org
[downloads]: https://img.shields.io/npm/dm/webpack-dev-server.svg
[contributors-url]: https://github.com/webpack/webpack-dev-server/graphs/contributors
[contributors]: https://img.shields.io/github/contributors/webpack/webpack-dev-server.svg


---

# ws: a Node.js WebSocket library

[![Version npm](https://img.shields.io/npm/v/ws.svg?logo=npm)](https://www.npmjs.com/package/ws)
[![CI](https://img.shields.io/github/actions/workflow/status/websockets/ws/ci.yml?branch=master&label=CI&logo=github)](https://github.com/websockets/ws/actions?query=workflow%3ACI+branch%3Amaster)
[![Coverage Status](https://img.shields.io/coveralls/websockets/ws/master.svg?logo=coveralls)](https://coveralls.io/github/websockets/ws)

ws is a simple to use, blazing fast, and thoroughly tested WebSocket client and
server implementation.

Passes the quite extensive Autobahn test suite: [server][server-report],
[client][client-report].

**Note**: This module does not work in the browser. The client in the docs is a
reference to a backend with the role of a client in the WebSocket communication.
Browser clients must use the native
[`WebSocket`](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)
object. To make the same code work seamlessly on Node.js and the browser, you
can use one of the many wrappers available on npm, like
[isomorphic-ws](https://github.com/heineiuo/isomorphic-ws).

## Table of Contents

- [Protocol support](#protocol-support)
- [Installing](#installing)
  - [Opt-in for performance](#opt-in-for-performance)
    - [Legacy opt-in for performance](#legacy-opt-in-for-performance)
- [API docs](#api-docs)
- [WebSocket compression](#websocket-compression)
- [Usage examples](#usage-examples)
  - [Sending and receiving text data](#sending-and-receiving-text-data)
  - [Sending binary data](#sending-binary-data)
  - [Simple server](#simple-server)
  - [External HTTP/S server](#external-https-server)
  - [Multiple servers sharing a single HTTP/S server](#multiple-servers-sharing-a-single-https-server)
  - [Client authentication](#client-authentication)
  - [Server broadcast](#server-broadcast)
  - [Round-trip time](#round-trip-time)
  - [Use the Node.js streams API](#use-the-nodejs-streams-api)
  - [Other examples](#other-examples)
- [FAQ](#faq)
  - [How to get the IP address of the client?](#how-to-get-the-ip-address-of-the-client)
  - [How to detect and close broken connections?](#how-to-detect-and-close-broken-connections)
  - [How to connect via a proxy?](#how-to-connect-via-a-proxy)
- [Changelog](#changelog)
- [License](#license)

## Protocol support

- **HyBi drafts 07-12** (Use the option `protocolVersion: 8`)
- **HyBi drafts 13-17** (Current default, alternatively option
  `protocolVersion: 13`)

## Installing

```
npm install ws
```

### Opt-in for performance

[bufferutil][] is an optional module that can be installed alongside the ws
module:

```
npm install --save-optional bufferutil
```

This is a binary addon that improves the performance of certain operations such
as masking and unmasking the data payload of the WebSocket frames. Prebuilt
binaries are available for the most popular platforms, so you don't necessarily
need to have a C++ compiler installed on your machine.

To force ws to not use bufferutil, use the
[`WS_NO_BUFFER_UTIL`](./doc/ws.md#ws_no_buffer_util) environment variable. This
can be useful to enhance security in systems where a user can put a package in
the package search path of an application of another user, due to how the
Node.js resolver algorithm works.

#### Legacy opt-in for performance

If you are running on an old version of Node.js (prior to v18.14.0), ws also
supports the [utf-8-validate][] module:

```
npm install --save-optional utf-8-validate
```

This contains a binary polyfill for [`buffer.isUtf8()`][].

To force ws not to use utf-8-validate, use the
[`WS_NO_UTF_8_VALIDATE`](./doc/ws.md#ws_no_utf_8_validate) environment variable.

## API docs

See [`/doc/ws.md`](./doc/ws.md) for Node.js-like documentation of ws classes and
utility functions.

## WebSocket compression

ws supports the [permessage-deflate extension][permessage-deflate] which enables
the client and server to negotiate a compression algorithm and its parameters,
and then selectively apply it to the data payloads of each WebSocket message.

The extension is disabled by default on the server and enabled by default on the
client. It adds a significant overhead in terms of performance and memory
consumption so we suggest to enable it only if it is really needed.

Note that Node.js has a variety of issues with high-performance compression,
where increased concurrency, especially on Linux, can lead to [catastrophic
memory fragmentation][node-zlib-bug] and slow performance. If you intend to use
permessage-deflate in production, it is worthwhile to set up a test
representative of your workload and ensure Node.js/zlib will handle it with
acceptable performance and memory usage.

Tuning of permessage-deflate can be done via the options defined below. You can
also use `zlibDeflateOptions` and `zlibInflateOptions`, which is passed directly
into the creation of [raw deflate/inflate streams][node-zlib-deflaterawdocs].

See [the docs][ws-server-options] for more options.

```js
import WebSocket, { WebSocketServer } from 'ws';

const wss = new WebSocketServer({
  port: 8080,
  perMessageDeflate: {
    zlibDeflateOptions: {
      // See zlib defaults.
      chunkSize: 1024,
      memLevel: 7,
      level: 3
    },
    zlibInflateOptions: {
      chunkSize: 10 * 1024
    },
    // Other options settable:
    clientNoContextTakeover: true, // Defaults to negotiated value.
    serverNoContextTakeover: true, // Defaults to negotiated value.
    serverMaxWindowBits: 10, // Defaults to negotiated value.
    // Below options specified as default values.
    concurrencyLimit: 10, // Limits zlib concurrency for perf.
    threshold: 1024 // Size (in bytes) below which messages
    // should not be compressed if context takeover is disabled.
  }
});
```

The client will only use the extension if it is supported and enabled on the
server. To always disable the extension on the client, set the
`perMessageDeflate` option to `false`.

```js
import WebSocket from 'ws';

const ws = new WebSocket('ws://www.host.com/path', {
  perMessageDeflate: false
});
```

## Usage examples

### Sending and receiving text data

```js
import WebSocket from 'ws';

const ws = new WebSocket('ws://www.host.com/path');

ws.on('error', console.error);

ws.on('open', function open() {
  ws.send('something');
});

ws.on('message', function message(data) {
  console.log('received: %s', data);
});
```

### Sending binary data

```js
import WebSocket from 'ws';

const ws = new WebSocket('ws://www.host.com/path');

ws.on('error', console.error);

ws.on('open', function open() {
  const array = new Float32Array(5);

  for (var i = 0; i < array.length; ++i) {
    array[i] = i / 2;
  }

  ws.send(array);
});
```

### Simple server

```js
import { WebSocketServer } from 'ws';

const wss = new WebSocketServer({ port: 8080 });

wss.on('connection', function connection(ws) {
  ws.on('error', console.error);

  ws.on('message', function message(data) {
    console.log('received: %s', data);
  });

  ws.send('something');
});
```

### External HTTP/S server

```js
import { createServer } from 'https';
import { readFileSync } from 'fs';
import { WebSocketServer } from 'ws';

const server = createServer({
  cert: readFileSync('/path/to/cert.pem'),
  key: readFileSync('/path/to/key.pem')
});
const wss = new WebSocketServer({ server });

wss.on('connection', function connection(ws) {
  ws.on('error', console.error);

  ws.on('message', function message(data) {
    console.log('received: %s', data);
  });

  ws.send('something');
});

server.listen(8080);
```

### Multiple servers sharing a single HTTP/S server

```js
import { createServer } from 'http';
import { WebSocketServer } from 'ws';

const server = createServer();
const wss1 = new WebSocketServer({ noServer: true });
const wss2 = new WebSocketServer({ noServer: true });

wss1.on('connection', function connection(ws) {
  ws.on('error', console.error);

  // ...
});

wss2.on('connection', function connection(ws) {
  ws.on('error', console.error);

  // ...
});

server.on('upgrade', function upgrade(request, socket, head) {
  const { pathname } = new URL(request.url, 'wss://base.url');

  if (pathname === '/foo') {
    wss1.handleUpgrade(request, socket, head, function done(ws) {
      wss1.emit('connection', ws, request);
    });
  } else if (pathname === '/bar') {
    wss2.handleUpgrade(request, socket, head, function done(ws) {
      wss2.emit('connection', ws, request);
    });
  } else {
    socket.destroy();
  }
});

server.listen(8080);
```

### Client authentication

```js
import { createServer } from 'http';
import { WebSocketServer } from 'ws';

function onSocketError(err) {
  console.error(err);
}

const server = createServer();
const wss = new WebSocketServer({ noServer: true });

wss.on('connection', function connection(ws, request, client) {
  ws.on('error', console.error);

  ws.on('message', function message(data) {
    console.log(`Received message ${data} from user ${client}`);
  });
});

server.on('upgrade', function upgrade(request, socket, head) {
  socket.on('error', onSocketError);

  // This function is not defined on purpose. Implement it with your own logic.
  authenticate(request, function next(err, client) {
    if (err || !client) {
      socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
      socket.destroy();
      return;
    }

    socket.removeListener('error', onSocketError);

    wss.handleUpgrade(request, socket, head, function done(ws) {
      wss.emit('connection', ws, request, client);
    });
  });
});

server.listen(8080);
```

Also see the provided [example][session-parse-example] using `express-session`.

### Server broadcast

A client WebSocket broadcasting to all connected WebSocket clients, including
itself.

```js
import WebSocket, { WebSocketServer } from 'ws';

const wss = new WebSocketServer({ port: 8080 });

wss.on('connection', function connection(ws) {
  ws.on('error', console.error);

  ws.on('message', function message(data, isBinary) {
    wss.clients.forEach(function each(client) {
      if (client.readyState === WebSocket.OPEN) {
        client.send(data, { binary: isBinary });
      }
    });
  });
});
```

A client WebSocket broadcasting to every other connected WebSocket clients,
excluding itself.

```js
import WebSocket, { WebSocketServer } from 'ws';

const wss = new WebSocketServer({ port: 8080 });

wss.on('connection', function connection(ws) {
  ws.on('error', console.error);

  ws.on('message', function message(data, isBinary) {
    wss.clients.forEach(function each(client) {
      if (client !== ws && client.readyState === WebSocket.OPEN) {
        client.send(data, { binary: isBinary });
      }
    });
  });
});
```

### Round-trip time

```js
import WebSocket from 'ws';

const ws = new WebSocket('wss://websocket-echo.com/');

ws.on('error', console.error);

ws.on('open', function open() {
  console.log('connected');
  ws.send(Date.now());
});

ws.on('close', function close() {
  console.log('disconnected');
});

ws.on('message', function message(data) {
  console.log(`Round-trip time: ${Date.now() - data} ms`);

  setTimeout(function timeout() {
    ws.send(Date.now());
  }, 500);
});
```

### Use the Node.js streams API

```js
import WebSocket, { createWebSocketStream } from 'ws';

const ws = new WebSocket('wss://websocket-echo.com/');

const duplex = createWebSocketStream(ws, { encoding: 'utf8' });

duplex.on('error', console.error);

duplex.pipe(process.stdout);
process.stdin.pipe(duplex);
```

### Other examples

For a full example with a browser client communicating with a ws server, see the
examples folder.

Otherwise, see the test cases.

## FAQ

### How to get the IP address of the client?

The remote IP address can be obtained from the raw socket.

```js
import { WebSocketServer } from 'ws';

const wss = new WebSocketServer({ port: 8080 });

wss.on('connection', function connection(ws, req) {
  const ip = req.socket.remoteAddress;

  ws.on('error', console.error);
});
```

When the server runs behind a proxy like NGINX, the de-facto standard is to use
the `X-Forwarded-For` header.

```js
wss.on('connection', function connection(ws, req) {
  const ip = req.headers['x-forwarded-for'].split(',')[0].trim();

  ws.on('error', console.error);
});
```

### How to detect and close broken connections?

Sometimes, the link between the server and the client can be interrupted in a
way that keeps both the server and the client unaware of the broken state of the
connection (e.g. when pulling the cord).

In these cases, ping messages can be used as a means to verify that the remote
endpoint is still responsive.

```js
import { WebSocketServer } from 'ws';

function heartbeat() {
  this.isAlive = true;
}

const wss = new WebSocketServer({ port: 8080 });

wss.on('connection', function connection(ws) {
  ws.isAlive = true;
  ws.on('error', console.error);
  ws.on('pong', heartbeat);
});

const interval = setInterval(function ping() {
  wss.clients.forEach(function each(ws) {
    if (ws.isAlive === false) return ws.terminate();

    ws.isAlive = false;
    ws.ping();
  });
}, 30000);

wss.on('close', function close() {
  clearInterval(interval);
});
```

Pong messages are automatically sent in response to ping messages as required by
the spec.

Just like the server example above, your clients might as well lose connection
without knowing it. You might want to add a ping listener on your clients to
prevent that. A simple implementation would be:

```js
import WebSocket from 'ws';

function heartbeat() {
  clearTimeout(this.pingTimeout);

  // Use `WebSocket#terminate()`, which immediately destroys the connection,
  // instead of `WebSocket#close()`, which waits for the close timer.
  // Delay should be equal to the interval at which your server
  // sends out pings plus a conservative assumption of the latency.
  this.pingTimeout = setTimeout(() => {
    this.terminate();
  }, 30000 + 1000);
}

const client = new WebSocket('wss://websocket-echo.com/');

client.on('error', console.error);
client.on('open', heartbeat);
client.on('ping', heartbeat);
client.on('close', function clear() {
  clearTimeout(this.pingTimeout);
});
```

### How to connect via a proxy?

Use a custom `http.Agent` implementation like [https-proxy-agent][] or
[socks-proxy-agent][].

## Changelog

We're using the GitHub [releases][changelog] for changelog entries.

## License

[MIT](LICENSE)

[`buffer.isutf8()`]: https://nodejs.org/api/buffer.html#bufferisutf8input
[bufferutil]: https://github.com/websockets/bufferutil
[changelog]: https://github.com/websockets/ws/releases
[client-report]: http://websockets.github.io/ws/autobahn/clients/
[https-proxy-agent]: https://github.com/TooTallNate/node-https-proxy-agent
[node-zlib-bug]: https://github.com/nodejs/node/issues/8871
[node-zlib-deflaterawdocs]:
  https://nodejs.org/api/zlib.html#zlib_zlib_createdeflateraw_options
[permessage-deflate]: https://tools.ietf.org/html/rfc7692
[server-report]: http://websockets.github.io/ws/autobahn/servers/
[session-parse-example]: ./examples/express-session-parse
[socks-proxy-agent]: https://github.com/TooTallNate/node-socks-proxy-agent
[utf-8-validate]: https://github.com/websockets/utf-8-validate
[ws-server-options]: ./doc/ws.md#new-websocketserveroptions-callback


---

[![Financial Contributors on Open Collective](https://opencollective.com/webpack-merge/all/badge.svg?label=financial+contributors)](https://opencollective.com/webpack-merge) [![Test](https://github.com/survivejs/webpack-merge/actions/workflows/test.yml/badge.svg?branch=develop&event=push)](https://github.com/survivejs/webpack-merge/actions/workflows/test.yml) [![codecov](https://codecov.io/gh/survivejs/webpack-merge/branch/master/graph/badge.svg)](https://codecov.io/gh/survivejs/webpack-merge)

# webpack-merge - Merge designed for Webpack

**webpack-merge** provides a `merge` function that concatenates arrays and merges objects creating a new object. If functions are encountered, it will execute them, run the results through the algorithm, and then wrap the returned values within a function again.

This behavior is particularly useful in configuring webpack although it has uses beyond it. Whenever you need to merge configuration objects, **webpack-merge** can come in handy.

## **`merge(...configuration | [...configuration])`**

`merge` is the core, and the most important idea, of the API. Often this is all you need unless you want further customization.

```javascript
const { merge } = require('webpack-merge');

// Default API
const output = merge(object1, object2, object3, ...);

// You can pass an array of objects directly.
// This works with all available functions.
const output = merge([object1, object2, object3]);

// Keys matching to the right take precedence:
const output = merge(
  { fruit: "apple", color: "red" },
  { fruit: "strawberries" }
);
console.log(output);
// { color: "red", fruit: "strawberries"}
```

### Limitations

Note that `Promise`s are not supported! If you want to return a configuration wrapped within a `Promise`, `merge` inside one. Example: `Promise.resolve(merge({ ... }, { ... }))`.

The same goes for configuration level functions as in the example below:

**webpack.config.js**

```javascript
const commonConfig = { ... };

const productionConfig = { ... };

const developmentConfig = { ... };

module.exports = (env, args) => {
  switch(args.mode) {
    case 'development':
      return merge(commonConfig, developmentConfig);
    case 'production':
      return merge(commonConfig, productionConfig);
    default:
      throw new Error('No matching configuration was found!');
  }
}
```

You can choose the configuration you want by using `webpack --mode development` assuming you are using _webpack-cli_.

## **`mergeWithCustomize({ customizeArray, customizeObject })(...configuration | [...configuration])`**

In case you need more flexibility, `merge` behavior can be customized per field as below:

```javascript
const { mergeWithCustomize } = require('webpack-merge');

const output = mergeWithCustomize(
  {
    customizeArray(a, b, key) {
      if (key === 'extensions') {
        return _.uniq([...a, ...b]);
      }

      // Fall back to default merging
      return undefined;
    },
    customizeObject(a, b, key) {
      if (key === 'module') {
        // Custom merging
        return _.merge({}, a, b);
      }

      // Fall back to default merging
      return undefined;
    }
  }
)(object1, object2, object3, ...);
```

For example, if the previous code was invoked with only `object1` and `object2`
with `object1` as:

```javascript
{
    foo1: ['object1'],
    foo2: ['object1'],
    bar1: { object1: {} },
    bar2: { object1: {} },
}
```

and `object2` as:

```javascript
{
    foo1: ['object2'],
    foo2: ['object2'],
    bar1: { object2: {} },
    bar2: { object2: {} },
}
```

then `customizeArray` will be invoked for each property of `Array` type, i.e:

```javascript
customizeArray(["object1"], ["object2"], "foo1");
customizeArray(["object1"], ["object2"], "foo2");
```

and `customizeObject` will be invoked for each property of `Object` type, i.e:

```javascript
customizeObject({ object1: {} }, { object2: {} }, bar1);
customizeObject({ object1: {} }, { object2: {} }, bar2);
```

## **`customizeArray`** and **`customizeObject`**

`customizeArray` and `customizeObject` provide small strategies to for `mergeWithCustomize`. They support `append`, `prepend`, `replace`, and wildcards for field names.

```javascript
const { mergeWithCustomize, customizeArray, customizeObject } = require('webpack-merge');

const output = mergeWithCustomize({
  customizeArray: customizeArray({
    'entry.*': 'prepend'
  }),
  customizeObject: customizeObject({
    entry: 'prepend'
  })
})(object1, object2, object3, ...);
```

## **`unique(<field>, <fields>, field => field)`**

`unique` is a strategy used for forcing uniqueness within configuration. It's most useful with plugins when you want to make sure there's only one in place.

The first `<field>` is the config property to look through for duplicates.

`<fields>` represents the values that should be unique when you run the field => field function on each duplicate.

When the order of elements of the `<field>` in the first configuration differs from the order in the second configuration, the latter is preserved.

```javascript
const { mergeWithCustomize, unique } = require("webpack-merge");

const output = mergeWithCustomize({
  customizeArray: unique(
    "plugins",
    ["HotModuleReplacementPlugin"],
    (plugin) => plugin.constructor && plugin.constructor.name,
  ),
})(
  {
    plugins: [new webpack.HotModuleReplacementPlugin()],
  },
  {
    plugins: [new webpack.HotModuleReplacementPlugin()],
  },
);

// Output contains only single HotModuleReplacementPlugin now and it's
// going to be the last plugin instance.
```

## **`mergeWithRules`**

To support advanced merging needs (i.e. merging within loaders), `mergeWithRules` includes additional syntax that allows you to match fields and apply strategies to match. Consider the full example below:

```javascript
const a = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [{ loader: "style-loader" }, { loader: "sass-loader" }],
      },
    ],
  },
};
const b = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          {
            loader: "style-loader",
            options: {
              modules: true,
            },
          },
        ],
      },
    ],
  },
};
const result = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          {
            loader: "style-loader",
            options: {
              modules: true,
            },
          },
          { loader: "sass-loader" },
        ],
      },
    ],
  },
};

assert.deepStrictEqual(
  mergeWithRules({
    module: {
      rules: {
        test: "match",
        use: {
          loader: "match",
          options: "replace",
        },
      },
    },
  })(a, b),
  result,
);
```

The way it works is that you should annotate fields to match using `match` (or `CustomizeRule.Match` if you are using TypeScript) matching your configuration structure and then use specific strategies to define how particular fields should be transformed. If a match doesn't exist above a rule, then it will apply the rule automatically.

**Supported annotations:**

- `match` (`CustomizeRule.Match`) - Optional matcher that scopes merging behavior to a specific part based on similarity (think DOM or jQuery selectors)
- `append` (`CustomizeRule.Append`) - Appends items
- `prepend` (`CustomizeRule.Prepend`) - Prepends items
- `replace` (`CustomizeRule.Replace`) - Replaces items
- `merge` (`CustomizeRule.Merge`) - Merges objects (shallow merge)

## Using with TypeScript

**webpack-merge** supports TypeScript out of the box. You should pass `Configuration` type from webpack to it as follows:

```typescript
import { Configuration } from "webpack";
import { merge } from "webpack-merge";

const config = merge<Configuration>({...}, {...});

...
```

## Development

1. `nvm use`
1. `npm i`
1. `npm run build -- --watch` in one terminal
1. `npm t -- --watch` in another one

Before contributing, please [open an issue](https://github.com/survivejs/webpack-merge/issues/new) where to discuss.

## Further Information and Support

Check out [SurviveJS - Webpack 5](http://survivejs.com/) to dig deeper into webpack. The free book uses **webpack-merge** extensively and shows you how to compose your configuration to keep it maintainable.

I am also available as a consultant in case you require specific assistance. I can contribute particularly in terms of improving maintainability of the setup while speeding it up and pointing out better practices. In addition to improving developer productivity, the work has impact on the end users of the product in terms of reduced application size and loading times.

## Contributors

### Code Contributors

This project exists thanks to all the people who contribute. [[Contribute](CONTRIBUTING.md)].
<a href="https://github.com/survivejs/webpack-merge/graphs/contributors"><img src="https://opencollective.com/webpack-merge/contributors.svg?width=890&button=false" /></a>

### Financial Contributors

Become a financial contributor and help us sustain our community. [[Contribute](https://opencollective.com/webpack-merge/contribute)]

#### Individuals

<a href="https://opencollective.com/webpack-merge"><img src="https://opencollective.com/webpack-merge/individuals.svg?width=890"></a>

#### Organizations

Support this project with your organization. Your logo will show up here with a link to your website. [[Contribute](https://opencollective.com/webpack-merge/contribute)]

<a href="https://opencollective.com/webpack-merge/organization/0/website"><img src="https://opencollective.com/webpack-merge/organization/0/avatar.svg"></a>
<a href="https://opencollective.com/webpack-merge/organization/1/website"><img src="https://opencollective.com/webpack-merge/organization/1/avatar.svg"></a>
<a href="https://opencollective.com/webpack-merge/organization/2/website"><img src="https://opencollective.com/webpack-merge/organization/2/avatar.svg"></a>
<a href="https://opencollective.com/webpack-merge/organization/3/website"><img src="https://opencollective.com/webpack-merge/organization/3/avatar.svg"></a>
<a href="https://opencollective.com/webpack-merge/organization/4/website"><img src="https://opencollective.com/webpack-merge/organization/4/avatar.svg"></a>
<a href="https://opencollective.com/webpack-merge/organization/5/website"><img src="https://opencollective.com/webpack-merge/organization/5/avatar.svg"></a>
<a href="https://opencollective.com/webpack-merge/organization/6/website"><img src="https://opencollective.com/webpack-merge/organization/6/avatar.svg"></a>
<a href="https://opencollective.com/webpack-merge/organization/7/website"><img src="https://opencollective.com/webpack-merge/organization/7/avatar.svg"></a>
<a href="https://opencollective.com/webpack-merge/organization/8/website"><img src="https://opencollective.com/webpack-merge/organization/8/avatar.svg"></a>
<a href="https://opencollective.com/webpack-merge/organization/9/website"><img src="https://opencollective.com/webpack-merge/organization/9/avatar.svg"></a>

## License

**webpack-merge** is available under MIT. See LICENSE for more details.


---

# webpack-sources

Contains multiple classes which represent a `Source`. A `Source` can be asked for source code, size, source map and hash.

## `Source`

Base class for all sources.

### Public methods

All methods should be considered as expensive as they may need to do computations.

#### `source`

```typescript
Source.prototype.source() -> String | Buffer
```

Returns the represented source code as string or Buffer (for binary Sources).

#### `buffer`

```typescript
Source.prototype.buffer() -> Buffer
```

Returns the represented source code as Buffer. Strings are converted to utf-8.

#### `size`

```typescript
Source.prototype.size() -> Number
```

Returns the size in bytes of the represented source code.

#### `map`

```typescript
Source.prototype.map(options?: Object) -> Object | null
```

Returns the SourceMap of the represented source code as JSON. May return `null` if no SourceMap is available.

The `options` object can contain the following keys:

- `columns: Boolean` (default `true`): If set to false the implementation may omit mappings for columns.

#### `sourceAndMap`

```typescript
Source.prototype.sourceAndMap(options?: Object) -> {
	source: String | Buffer,
	map: Object | null
}
```

Returns both, source code (like `Source.prototype.source()` and SourceMap (like `Source.prototype.map()`). This method could have better performance than calling `source()` and `map()` separately.

See `map()` for `options`.

#### `updateHash`

```typescript
Source.prototype.updateHash(hash: Hash) -> void
```

Updates the provided `Hash` object with the content of the represented source code. (`Hash` is an object with an `update` method, which is called with string values)

## `RawSource`

Represents source code without SourceMap.

```typescript
new RawSource(sourceCode: String | Buffer)
```

## `OriginalSource`

Represents source code, which is a copy of the original file.

```typescript
new OriginalSource(
	sourceCode: String | Buffer,
	name: String
)
```

- `sourceCode`: The source code.
- `name`: The filename of the original source code.

OriginalSource tries to create column mappings if requested, by splitting the source code at typical statement borders (`;`, `{`, `}`).

## `SourceMapSource`

Represents source code with SourceMap, optionally having an additional SourceMap for the original source.

```typescript
new SourceMapSource(
	sourceCode: String | Buffer,
	name: String,
	sourceMap: Object | String | Buffer,
	originalSource?: String | Buffer,
	innerSourceMap?: Object | String | Buffer,
	removeOriginalSource?: boolean
)
```

- `sourceCode`: The source code.
- `name`: The filename of the original source code.
- `sourceMap`: The SourceMap for the source code.
- `originalSource`: The source code of the original file. Can be omitted if the `sourceMap` already contains the original source code.
- `innerSourceMap`: The SourceMap for the `originalSource`/`name`.
- `removeOriginalSource`: Removes the source code for `name` from the final map, keeping only the deeper mappings for that file.

The `SourceMapSource` supports "identity" mappings for the `innerSourceMap`.
When original source matches generated source for a mapping it's assumed to be mapped char by char allowing to keep finer mappings from `sourceMap`.

## `CachedSource`

Decorates a `Source` and caches returned results of `map`, `source`, `buffer`, `size` and `sourceAndMap` in memory. `updateHash` is not cached.
It tries to reused cached results from other methods to avoid calculations, i. e. when `source` is already cached, calling `size` will get the size from the cached source, calling `sourceAndMap` will only call `map` on the wrapped Source.

```typescript
new CachedSource(source: Source)
new CachedSource(source: Source | () => Source, cachedData?: CachedData)
```

Instead of passing a `Source` object directly one can pass an function that returns a `Source` object. The function is only called when needed and once.

### Public methods

#### `getCachedData()`

Returns the cached data for passing to the constructor. All cached entries are converted to Buffers and strings are avoided.

#### `original()`

Returns the original `Source` object.

#### `originalLazy()`

Returns the original `Source` object or a function returning these.

## `PrefixSource`

Prefix every line of the decorated `Source` with a provided string.

```typescript
new PrefixSource(
	prefix: String,
	source: Source | String | Buffer
)
```

## `ConcatSource`

Concatenate multiple `Source`s or strings to a single source.

```typescript
new ConcatSource(
	...items?: Source | String
)
```

### Public methods

#### `add`

```typescript
ConcatSource.prototype.add(item: Source | String)
```

Adds an item to the source.

## `ReplaceSource`

Decorates a `Source` with replacements and insertions of source code.

The `ReplaceSource` supports "identity" mappings for child source.
When original source matches generated source for a mapping it's assumed to be mapped char by char allowing to split mappings at replacements/insertions.

### Public methods

#### `replace`

```typescript
ReplaceSource.prototype.replace(
	start: Number,
	end: Number,
	replacement: String
)
```

Replaces chars from `start` (0-indexed, inclusive) to `end` (0-indexed, inclusive) with `replacement`.

Locations represents locations in the original source and are not influenced by other replacements or insertions.

#### `insert`

```typescript
ReplaceSource.prototype.insert(
	pos: Number,
	insertion: String
)
```

Inserts the `insertion` before char `pos` (0-indexed).

Location represents location in the original source and is not influenced by other replacements or insertions.

#### `original`

Get decorated `Source`.

## `CompatSource`

Converts a Source-like object into a real Source object.

### Public methods

#### static `from`

```typescript
CompatSource.from(sourceLike: any | Source)
```

If `sourceLike` is a real Source it returns it unmodified. Otherwise it returns it wrapped in a CompatSource.


---

[![npm version][npm-version-src]][npm-version-href]
[![npm downloads][npm-downloads-src]][npm-downloads-href]
[![package phobia][package-phobia-src]][package-phobia-href]
[![github actions][checks-src]][checks-href]

<div align="center">
  <!-- replace with accurate logo e.g from https://worldvectorlogo.com/ -->
  <img width="200" height="200" hspace="25"  src="./assets/logo.svg">
  <a href="https://webpack.js.org/">
    <img width="200" height="200" hspace="25" src="https://cdn.rawgit.com/webpack/media/e7485eb2/logo/icon-square-big.svg">
  </a>
  <p>Elegant ProgressBar and Profiler for Webpack</p>
</div>

✔ Display elegant progress bar while building or watch

✔ Support of multiple concurrent builds (useful for SSR)

✔ Pretty print filename and loaders

✔ Windows compatible

✔ **Fully** customizable using reporters

✔ Advanced build profiler

<div align="center">
<br>
<img src="./assets/screen1.png" width="600px">
<p>Multi progress bars</p>
<br>
</div>

<div align="center">
<br>
<img src="./assets/screen2.png" width="600px">
<p>Build Profiler</p>
<br>
</div>

<h2 align="center">Getting Started</h2>

To begin, you'll need to install `webpackbar`:

Using npm:

```bash
npm install webpackbar -D
```

Using yarn:

```bash
yarn add webpackbar -D
```

Then add the reporter as a plugin to your webpack config.

**webpack.config.js**

```js
const webpack = require("webpack");
const WebpackBar = require("webpackbar");

module.exports = {
  context: path.resolve(__dirname),
  devtool: "source-map",
  entry: "./entry.js",
  output: {
    filename: "./output.js",
    path: path.resolve(__dirname),
  },
  plugins: [new WebpackBar()],
};
```

<h2 align="center">Options</h2>

### `name`

- Default: `webpack`

Name.

### `color`

- Default: `green`

Primary color (can be HEX like `#xxyyzz` or a web color like `green`).

### `profile`

- Default: `false`

Enable profiler.

### `fancy`

- Default: `true` when not in CI or testing mode.

Enable bars reporter.

### `basic`

- Default: `true` when running in minimal environments.

Enable a simple log reporter (only start and end).

### `reporter`

Register a custom reporter.

### `reporters`

- Default: `[]`

Register an Array of your custom reporters. (Same as `reporter` but array)

<h2 align="center">Custom Reporters</h2>

Webpackbar comes with a fancy progress-bar out of the box.
But you may want to show progress somewhere else or provide your own.

For this purpose, you can provide one or more extra reporters using `reporter` and `reporters` options.

**NOTE:** If you plan to provide your own reporter, don't forget to setting `fancy` and `basic` options to false to prevent conflicts.

A reporter should be instance of a class or plain object and functions for special hooks. It is not necessary to implement all functions, webpackbar only calls those that exists.

**Simple logger:**

```js
{
 start(context) {
   // Called when (re)compile is started
 },
 change(context) {
   // Called when a file changed on watch mode
 },
 update(context) {
   // Called after each progress update
 },
 done(context) {
   // Called when compile finished
 },
 progress(context) {
   // Called when build progress updated
 },
 allDone(context) {
   // Called when _all_ compiles finished
 },
 beforeAllDone(context) {
 },
 afterAllDone(context) {
 },
}
```

`context` is the reference to the plugin. You can use `context.state` to access status.

**Schema of `context.state`:**

```js
{
  start, progress, message, details, request, hasErrors;
}
```

<h2 align="center">License</h2>

[MIT](./LICENSE)

<!-- Refs -->

[standard-js-src]: https://flat.badgen.net/badge/code%20style/standard/green
[standard-js-href]: https://standardjs.com
[npm-version-src]: https://flat.badgen.net/npm/v/webpackbar/latest
[npm-version-href]: https://npmjs.com/package/webpackbar
[npm-downloads-src]: https://flat.badgen.net/npm/dm/webpackbar
[npm-downloads-href]: https://npmjs.com/package/webpackbar
[package-phobia-src]: https://flat.badgen.net/packagephobia/install/webpackbar
[package-phobia-href]: https://packagephobia.now.sh/result?p=webpackbar
[checks-src]: https://flat.badgen.net/github/checks/nuxt-contrib/webpackbar/master
[checks-href]: https://github.com/nuxt-contrib/webpackbar/actions


---

# emoji-regex [![Build status](https://travis-ci.org/mathiasbynens/emoji-regex.svg?branch=master)](https://travis-ci.org/mathiasbynens/emoji-regex)

_emoji-regex_ offers a regular expression to match all emoji symbols (including textual representations of emoji) as per the Unicode Standard.

This repository contains a script that generates this regular expression based on [the data from Unicode v12](https://github.com/mathiasbynens/unicode-12.0.0). Because of this, the regular expression can easily be updated whenever new emoji are added to the Unicode standard.

## Installation

Via [npm](https://www.npmjs.com/):

```bash
npm install emoji-regex
```

In [Node.js](https://nodejs.org/):

```js
const emojiRegex = require('emoji-regex');
// Note: because the regular expression has the global flag set, this module
// exports a function that returns the regex rather than exporting the regular
// expression itself, to make it impossible to (accidentally) mutate the
// original regular expression.

const text = `
\u{231A}: ⌚ default emoji presentation character (Emoji_Presentation)
\u{2194}\u{FE0F}: ↔️ default text presentation character rendered as emoji
\u{1F469}: 👩 emoji modifier base (Emoji_Modifier_Base)
\u{1F469}\u{1F3FF}: 👩🏿 emoji modifier base followed by a modifier
`;

const regex = emojiRegex();
let match;
while (match = regex.exec(text)) {
  const emoji = match[0];
  console.log(`Matched sequence ${ emoji } — code points: ${ [...emoji].length }`);
}
```

Console output:

```
Matched sequence ⌚ — code points: 1
Matched sequence ⌚ — code points: 1
Matched sequence ↔️ — code points: 2
Matched sequence ↔️ — code points: 2
Matched sequence 👩 — code points: 1
Matched sequence 👩 — code points: 1
Matched sequence 👩🏿 — code points: 2
Matched sequence 👩🏿 — code points: 2
```

To match emoji in their textual representation as well (i.e. emoji that are not `Emoji_Presentation` symbols and that aren’t forced to render as emoji by a variation selector), `require` the other regex:

```js
const emojiRegex = require('emoji-regex/text.js');
```

Additionally, in environments which support ES2015 Unicode escapes, you may `require` ES2015-style versions of the regexes:

```js
const emojiRegex = require('emoji-regex/es2015/index.js');
const emojiRegexText = require('emoji-regex/es2015/text.js');
```

## Author

| [![twitter/mathias](https://gravatar.com/avatar/24e08a9ea84deb17ae121074d0f17125?s=70)](https://twitter.com/mathias "Follow @mathias on Twitter") |
|---|
| [Mathias Bynens](https://mathiasbynens.be/) |

## License

_emoji-regex_ is available under the [MIT](https://mths.be/mit) license.


---

# markdown-table

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]

Generate fancy [Markdown][fancy] tables.

## Install

[npm][]:

```sh
npm install markdown-table
```

## Use

Typical usage (defaults to align left):

```js
var table = require('markdown-table')

table([
  ['Branch', 'Commit'],
  ['master', '0123456789abcdef'],
  ['staging', 'fedcba9876543210']
])
```

Yields:

```markdown
| Branch  | Commit           |
| ------- | ---------------- |
| master  | 0123456789abcdef |
| staging | fedcba9876543210 |
```

With align:

```js
table(
  [
    ['Beep', 'No.', 'Boop'],
    ['beep', '1024', 'xyz'],
    ['boop', '3388450', 'tuv'],
    ['foo', '10106', 'qrstuv'],
    ['bar', '45', 'lmno']
  ],
  {align: ['l', 'c', 'r']}
)
```

Yields:

```markdown
| Beep |   No.   |   Boop |
| :--- | :-----: | -----: |
| beep |   1024  |    xyz |
| boop | 3388450 |    tuv |
| foo  |  10106  | qrstuv |
| bar  |    45   |   lmno |
```

## API

### `markdownTable(table[, options])`

Turns a given matrix of strings (an array of arrays of strings) into a table.

##### `options`

###### `options.align`

One style for all columns, or styles for their respective columns (`string` or
`Array.<string>`).
Each style is either `'l'` (left), `'r'` (right), or `'c'` (center).
Other values are treated as `''`, which doesn’t place the colon in the alignment
row but does align left.
*Only the lowercased first character is used, so `Right` is fine.*

###### `options.padding`

Whether to add a space of padding between delimiters and cells (`boolean`,
default: `true`).

When `true`, there is padding:

```markdown
| Alpha | B     |
| ----- | ----- |
| C     | Delta |
```

When `false`, there is no padding:

```markdown
|Alpha|B    |
|-----|-----|
|C    |Delta|
```

###### `options.delimiterStart`

Whether to begin each row with the delimiter (`boolean`, default: `true`).

Note: please don’t use this: it could create fragile structures that aren’t
understandable to some Markdown parsers.

When `true`, there are starting delimiters:

```markdown
| Alpha | B     |
| ----- | ----- |
| C     | Delta |
```

When `false`, there are no starting delimiters:

```markdown
Alpha | B     |
----- | ----- |
C     | Delta |
```

###### `options.delimiterEnd`

Whether to end each row with the delimiter (`boolean`, default: `true`).

Note: please don’t use this: it could create fragile structures that aren’t
understandable to some Markdown parsers.

When `true`, there are ending delimiters:

```markdown
| Alpha | B     |
| ----- | ----- |
| C     | Delta |
```

When `false`, there are no ending delimiters:

```markdown
| Alpha | B
| ----- | -----
| C     | Delta
```

###### `options.alignDelimiters`

Whether to align the delimiters (`boolean`, default: `true`).
By default, they are aligned:

```markdown
| Alpha | B     |
| ----- | ----- |
| C     | Delta |
```

Pass `false` to make them staggered:

```markdown
| Alpha | B |
| - | - |
| C | Delta |
```

###### `options.stringLength`

Method to detect the length of a cell (`Function`, default: `s => s.length`).

Full-width characters and ANSI-sequences all mess up delimiter alignment
when viewing the Markdown source.
To fix this, you have to pass in a `stringLength` option to detect the “visible”
length of a cell (note that what is and isn’t visible depends on your editor).

Without such a function, the following:

```js
table([
  ['Alpha', 'Bravo'],
  ['中文', 'Charlie'],
  ['👩‍❤️‍👩', 'Delta']
])
```

Yields:

```markdown
| Alpha | Bravo |
| - | - |
| 中文 | Charlie |
| 👩‍❤️‍👩 | Delta |
```

With [`string-width`][string-width]:

```js
var width = require('string-width')

table(
  [
    ['Alpha', 'Bravo'],
    ['中文', 'Charlie'],
    ['👩‍❤️‍👩', 'Delta']
  ],
  {stringLength: width}
)
```

Yields:

```markdown
| Alpha | Bravo   |
| ----- | ------- |
| 中文  | Charlie |
| 👩‍❤️‍👩    | Delta   |
```

## Inspiration

The original idea and basic implementation was inspired by James Halliday’s
[`text-table`][text-table] library.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://img.shields.io/travis/wooorm/markdown-table.svg

[build]: https://travis-ci.org/wooorm/markdown-table

[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/markdown-table.svg

[coverage]: https://codecov.io/github/wooorm/markdown-table

[downloads-badge]: https://img.shields.io/npm/dm/markdown-table.svg

[downloads]: https://www.npmjs.com/package/markdown-table

[size-badge]: https://img.shields.io/bundlephobia/minzip/markdown-table.svg

[size]: https://bundlephobia.com/result?p=markdown-table

[npm]: https://docs.npmjs.com/cli/install

[license]: license

[author]: https://wooorm.com

[fancy]: https://help.github.com/articles/github-flavored-markdown/#tables

[text-table]: https://github.com/substack/text-table

[string-width]: https://github.com/sindresorhus/string-width


---

# string-width

> Get the visual width of a string - the number of columns required to display it

Some Unicode characters are [fullwidth](https://en.wikipedia.org/wiki/Halfwidth_and_fullwidth_forms) and use double the normal width. [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code) are stripped and doesn't affect the width.

Useful to be able to measure the actual width of command-line output.


## Install

```
$ npm install string-width
```


## Usage

```js
const stringWidth = require('string-width');

stringWidth('a');
//=> 1

stringWidth('古');
//=> 2

stringWidth('\u001B[1m古\u001B[22m');
//=> 2
```


## Related

- [string-width-cli](https://github.com/sindresorhus/string-width-cli) - CLI for this module
- [string-length](https://github.com/sindresorhus/string-length) - Get the real length of a string
- [widest-line](https://github.com/sindresorhus/widest-line) - Get the visual width of the widest line in a string


---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-string-width?utm_source=npm-string-width&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

# wrap-ansi [![Build Status](https://travis-ci.com/chalk/wrap-ansi.svg?branch=master)](https://travis-ci.com/chalk/wrap-ansi) [![Coverage Status](https://coveralls.io/repos/github/chalk/wrap-ansi/badge.svg?branch=master)](https://coveralls.io/github/chalk/wrap-ansi?branch=master)

> Wordwrap a string with [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors_and_Styles)

## Install

```
$ npm install wrap-ansi
```

## Usage

```js
const chalk = require('chalk');
const wrapAnsi = require('wrap-ansi');

const input = 'The quick brown ' + chalk.red('fox jumped over ') +
	'the lazy ' + chalk.green('dog and then ran away with the unicorn.');

console.log(wrapAnsi(input, 20));
```

<img width="331" src="screenshot.png">

## API

### wrapAnsi(string, columns, options?)

Wrap words to the specified column width.

#### string

Type: `string`

String with ANSI escape codes. Like one styled by [`chalk`](https://github.com/chalk/chalk). Newline characters will be normalized to `\n`.

#### columns

Type: `number`

Number of columns to wrap the text to.

#### options

Type: `object`

##### hard

Type: `boolean`\
Default: `false`

By default the wrap is soft, meaning long words may extend past the column width. Setting this to `true` will make it hard wrap at the column width.

##### wordWrap

Type: `boolean`\
Default: `true`

By default, an attempt is made to split words at spaces, ensuring that they don't extend past the configured columns. If wordWrap is `false`, each column will instead be completely filled splitting words as necessary.

##### trim

Type: `boolean`\
Default: `true`

Whitespace on all lines is removed by default. Set this option to `false` if you don't want to trim.

## Related

- [slice-ansi](https://github.com/chalk/slice-ansi) - Slice a string with ANSI escape codes
- [cli-truncate](https://github.com/sindresorhus/cli-truncate) - Truncate a string to a specific width in the terminal
- [chalk](https://github.com/chalk/chalk) - Terminal string styling done right
- [jsesc](https://github.com/mathiasbynens/jsesc) - Generate ASCII-only output from Unicode strings. Useful for creating test fixtures.

## Maintainers

- [Sindre Sorhus](https://github.com/sindresorhus)
- [Josh Junon](https://github.com/qix-)
- [Benjamin Coe](https://github.com/bcoe)

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-wrap_ansi?utm_source=npm-wrap-ansi&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

### 0.7.4 / 2020-05-22

- Avoid crashing if `process.version` does not contain any digits
- Emit `ping` and `pong` events from the `Server` driver
- Require http-parser-js >=0.5.1 which fixes the bug we addressed in 0.7.3

### 0.7.3 / 2019-06-13

- Cap version of http-parser-js below 0.4.11, which introduced a bug that
  prevents us from handling messages that are part of the same input buffer as
  the handshake response if chunked encoding is specified

### 0.7.2 / 2019-06-13

(This version was pulled due to an error when publishing)

### 0.7.1 / 2019-06-10

- Catch any exceptions produced while generating a handshake response and send a
  `400 Bad Request` response to the client
- Pick the RFC-6455 protocol version if the request contains any of the headers
  used by that version
- Use the `Buffer.alloc()` and `Buffer.from()` functions instead of the unsafe
  `Buffer()` constructor
- Handle errors encountered while handling malformed draft-76 requests
- Change license from MIT to Apache 2.0

### 0.7.0 / 2017-09-11

- Add `ping` and `pong` to the set of events users can listen to
- Replace the bindings to Node's HTTP parser with `http-parser-js`

### 0.6.5 / 2016-05-20

- Don't mutate buffers passed in by the application when masking

### 0.6.4 / 2016-01-07

- If a number is given as input for a frame payload, send it as a string

### 0.6.3 / 2015-11-06

- Reject draft-76 handshakes if their Sec-WebSocket-Key headers are invalid
- Throw a more helpful error if a client is created with an invalid URL

### 0.6.2 / 2015-07-18

- When the peer sends a close frame with no error code, emit 1000

### 0.6.1 / 2015-07-13

- Use the `buffer.{read,write}UInt{16,32}BE` methods for reading/writing numbers
  to buffers rather than including duplicate logic for this

### 0.6.0 / 2015-07-08

- Allow the parser to recover cleanly if event listeners raise an error
- Add a `pong` method for sending unsolicited pong frames

### 0.5.4 / 2015-03-29

- Don't emit extra close frames if we receive a close frame after we already
  sent one
- Fail the connection when the driver receives an invalid
  `Sec-WebSocket-Extensions` header

### 0.5.3 / 2015-02-22

- Don't treat incoming data as WebSocket frames if a client driver is closed
  before receiving the server handshake

### 0.5.2 / 2015-02-19

- Fix compatibility with the HTTP parser on io.js
- Use `websocket-extensions` to make sure messages and close frames are kept in
  order
- Don't emit multiple `error` events

### 0.5.1 / 2014-12-18

- Don't allow drivers to be created with unrecognized options

### 0.5.0 / 2014-12-13

- Support protocol extensions via the websocket-extensions module

### 0.4.0 / 2014-11-08

- Support connection via HTTP proxies using `CONNECT`

### 0.3.6 / 2014-10-04

- It is now possible to call `close()` before `start()` and close the driver

### 0.3.5 / 2014-07-06

- Don't hold references to frame buffers after a message has been emitted
- Make sure that `protocol` and `version` are exposed properly by the TCP driver

### 0.3.4 / 2014-05-08

- Don't hold memory-leaking references to I/O buffers after they have been
  parsed

### 0.3.3 / 2014-04-24

- Correct the draft-76 status line reason phrase

### 0.3.2 / 2013-12-29

- Expand `maxLength` to cover sequences of continuation frames and
  `draft-{75,76}`
- Decrease default maximum frame buffer size to 64MB
- Stop parsing when the protocol enters a failure mode, to save CPU cycles

### 0.3.1 / 2013-12-03

- Add a `maxLength` option to limit allowed frame size
- Don't pre-allocate a message buffer until the whole frame has arrived
- Fix compatibility with Node v0.11 `HTTPParser`

### 0.3.0 / 2013-09-09

- Support client URLs with Basic Auth credentials

### 0.2.2 / 2013-07-05

- No functional changes, just updates to package.json

### 0.2.1 / 2013-05-17

- Export the isSecureRequest() method since faye-websocket relies on it
- Queue sent messages in the client's initial state

### 0.2.0 / 2013-05-12

- Add API for setting and reading headers
- Add Driver.server() method for getting a driver for TCP servers

### 0.1.0 / 2013-05-04

- First stable release


---

Copyright 2010-2020 James Coglan

Licensed under the Apache License, Version 2.0 (the "License"); you may not use
this file except in compliance with the License. You may obtain a copy of the
License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed
under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
CONDITIONS OF ANY KIND, either express or implied. See the License for the
specific language governing permissions and limitations under the License.


---

# websocket-driver [![Build Status](https://travis-ci.org/faye/websocket-driver-node.svg)](https://travis-ci.org/faye/websocket-driver-node)

This module provides a complete implementation of the WebSocket protocols that
can be hooked up to any I/O stream. It aims to simplify things by decoupling the
protocol details from the I/O layer, such that users only need to implement code
to stream data in and out of it without needing to know anything about how the
protocol actually works. Think of it as a complete WebSocket system with
pluggable I/O.

Due to this design, you get a lot of things for free. In particular, if you hook
this module up to some I/O object, it will do all of this for you:

- Select the correct server-side driver to talk to the client
- Generate and send both server- and client-side handshakes
- Recognize when the handshake phase completes and the WS protocol begins
- Negotiate subprotocol selection based on `Sec-WebSocket-Protocol`
- Negotiate and use extensions via the
  [websocket-extensions](https://github.com/faye/websocket-extensions-node)
  module
- Buffer sent messages until the handshake process is finished
- Deal with proxies that defer delivery of the draft-76 handshake body
- Notify you when the socket is open and closed and when messages arrive
- Recombine fragmented messages
- Dispatch text, binary, ping, pong and close frames
- Manage the socket-closing handshake process
- Automatically reply to ping frames with a matching pong
- Apply masking to messages sent by the client

This library was originally extracted from the [Faye](http://faye.jcoglan.com)
project but now aims to provide simple WebSocket support for any Node-based
project.


## Installation

```
$ npm install websocket-driver
```


## Usage

This module provides protocol drivers that have the same interface on the server
and on the client. A WebSocket driver is an object with two duplex streams
attached; one for incoming/outgoing messages and one for managing the wire
protocol over an I/O stream. The full API is described below.


### Server-side with HTTP

A Node webserver emits a special event for 'upgrade' requests, and this is where
you should handle WebSockets. You first check whether the request is a
WebSocket, and if so you can create a driver and attach the request's I/O stream
to it.

```js
var http = require('http'),
    websocket = require('websocket-driver');

var server = http.createServer();

server.on('upgrade', function(request, socket, body) {
  if (!websocket.isWebSocket(request)) return;

  var driver = websocket.http(request);

  driver.io.write(body);
  socket.pipe(driver.io).pipe(socket);

  driver.messages.on('data', function(message) {
    console.log('Got a message', message);
  });

  driver.start();
});
```

Note the line `driver.io.write(body)` - you must pass the `body` buffer to the
socket driver in order to make certain versions of the protocol work.


### Server-side with TCP

You can also handle WebSocket connections in a bare TCP server, if you're not
using an HTTP server and don't want to implement HTTP parsing yourself.

The driver will emit a `connect` event when a request is received, and at this
point you can detect whether it's a WebSocket and handle it as such. Here's an
example using the Node `net` module:

```js
var net = require('net'),
    websocket = require('websocket-driver');

var server = net.createServer(function(connection) {
  var driver = websocket.server();

  driver.on('connect', function() {
    if (websocket.isWebSocket(driver)) {
      driver.start();
    } else {
      // handle other HTTP requests
    }
  });

  driver.on('close', function() { connection.end() });
  connection.on('error', function() {});

  connection.pipe(driver.io).pipe(connection);

  driver.messages.pipe(driver.messages);
});

server.listen(4180);
```

In the `connect` event, the driver gains several properties to describe the
request, similar to a Node request object, such as `method`, `url` and
`headers`. However you should remember it's not a real request object; you
cannot write data to it, it only tells you what request data we parsed from the
input.

If the request has a body, it will be in the `driver.body` buffer, but only as
much of the body as has been piped into the driver when the `connect` event
fires.


### Client-side

Similarly, to implement a WebSocket client you just need to make a driver by
passing in a URL. After this you use the driver API as described below to
process incoming data and send outgoing data.


```js
var net = require('net'),
    websocket = require('websocket-driver');

var driver = websocket.client('ws://www.example.com/socket'),
    tcp = net.connect(80, 'www.example.com');

tcp.pipe(driver.io).pipe(tcp);

tcp.on('connect', function() {
  driver.start();
});

driver.messages.on('data', function(message) {
  console.log('Got a message', message);
});
```

Client drivers have two additional properties for reading the HTTP data that was
sent back by the server:

- `driver.statusCode` - the integer value of the HTTP status code
- `driver.headers` - an object containing the response headers


### HTTP Proxies

The client driver supports connections via HTTP proxies using the `CONNECT`
method. Instead of sending the WebSocket handshake immediately, it will send a
`CONNECT` request, wait for a `200` response, and then proceed as normal.

To use this feature, call `driver.proxy(url)` where `url` is the origin of the
proxy, including a username and password if required. This produces a duplex
stream that you should pipe in and out of your TCP connection to the proxy
server. When the proxy emits `connect`, you can then pipe `driver.io` to your
TCP stream and call `driver.start()`.

```js
var net = require('net'),
    websocket = require('websocket-driver');

var driver = websocket.client('ws://www.example.com/socket'),
    proxy  = driver.proxy('http://username:password@proxy.example.com'),
    tcp    = net.connect(80, 'proxy.example.com');

tcp.pipe(proxy).pipe(tcp, { end: false });

tcp.on('connect', function() {
  proxy.start();
});

proxy.on('connect', function() {
  driver.io.pipe(tcp).pipe(driver.io);
  driver.start();
});

driver.messages.on('data', function(message) {
  console.log('Got a message', message);
});
```

The proxy's `connect` event is also where you should perform a TLS handshake on
your TCP stream, if you are connecting to a `wss:` endpoint.

In the event that proxy connection fails, `proxy` will emit an `error`. You can
inspect the proxy's response via `proxy.statusCode` and `proxy.headers`.

```js
proxy.on('error', function(error) {
  console.error(error.message);
  console.log(proxy.statusCode);
  console.log(proxy.headers);
});
```

Before calling `proxy.start()` you can set custom headers using
`proxy.setHeader()`:

```js
proxy.setHeader('User-Agent', 'node');
proxy.start();
```


### Driver API

Drivers are created using one of the following methods:

```js
driver = websocket.http(request, options)
driver = websocket.server(options)
driver = websocket.client(url, options)
```

The `http` method returns a driver chosen using the headers from a Node HTTP
request object. The `server` method returns a driver that will parse an HTTP
request and then decide which driver to use for it using the `http` method. The
`client` method always returns a driver for the RFC version of the protocol with
masking enabled on outgoing frames.

The `options` argument is optional, and is an object. It may contain the
following fields:

- `maxLength` - the maximum allowed size of incoming message frames, in bytes.
  The default value is `2^26 - 1`, or 1 byte short of 64 MiB.
- `protocols` - an array of strings representing acceptable subprotocols for use
  over the socket. The driver will negotiate one of these to use via the
  `Sec-WebSocket-Protocol` header if supported by the other peer.

A driver has two duplex streams attached to it:

- **`driver.io`** - this stream should be attached to an I/O socket like a TCP
  stream. Pipe incoming TCP chunks to this stream for them to be parsed, and
  pipe this stream back into TCP to send outgoing frames.
- **`driver.messages`** - this stream emits messages received over the
  WebSocket.  Writing to it sends messages to the other peer by emitting frames
  via the `driver.io` stream.

All drivers respond to the following API methods, but some of them are no-ops
depending on whether the client supports the behaviour.

Note that most of these methods are commands: if they produce data that should
be sent over the socket, they will give this to you by emitting `data` events on
the `driver.io` stream.

#### `driver.on('open', function(event) {})`

Adds a callback to execute when the socket becomes open.

#### `driver.on('message', function(event) {})`

Adds a callback to execute when a message is received. `event` will have a
`data` attribute containing either a string in the case of a text message or a
`Buffer` in the case of a binary message.

You can also listen for messages using the `driver.messages.on('data')` event,
which emits strings for text messages and buffers for binary messages.

#### `driver.on('error', function(event) {})`

Adds a callback to execute when a protocol error occurs due to the other peer
sending an invalid byte sequence. `event` will have a `message` attribute
describing the error.

#### `driver.on('close', function(event) {})`

Adds a callback to execute when the socket becomes closed. The `event` object
has `code` and `reason` attributes.

#### `driver.on('ping', function(event) {})`

Adds a callback block to execute when a ping is received. You do not need to
handle this by sending a pong frame yourself; the driver handles this for you.

#### `driver.on('pong', function(event) {})`

Adds a callback block to execute when a pong is received. If this was in
response to a ping you sent, you can also handle this event via the
`driver.ping(message, function() { ... })` callback.

#### `driver.addExtension(extension)`

Registers a protocol extension whose operation will be negotiated via the
`Sec-WebSocket-Extensions` header. `extension` is any extension compatible with
the [websocket-extensions](https://github.com/faye/websocket-extensions-node)
framework.

#### `driver.setHeader(name, value)`

Sets a custom header to be sent as part of the handshake response, either from
the server or from the client. Must be called before `start()`, since this is
when the headers are serialized and sent.

#### `driver.start()`

Initiates the protocol by sending the handshake - either the response for a
server-side driver or the request for a client-side one. This should be the
first method you invoke.  Returns `true` if and only if a handshake was sent.

#### `driver.parse(string)`

Takes a string and parses it, potentially resulting in message events being
emitted (see `on('message')` above) or in data being sent to `driver.io`.  You
should send all data you receive via I/O to this method by piping a stream into
`driver.io`.

#### `driver.text(string)`

Sends a text message over the socket. If the socket handshake is not yet
complete, the message will be queued until it is. Returns `true` if the message
was sent or queued, and `false` if the socket can no longer send messages.

This method is equivalent to `driver.messages.write(string)`.

#### `driver.binary(buffer)`

Takes a `Buffer` and sends it as a binary message. Will queue and return `true`
or `false` the same way as the `text` method. It will also return `false` if the
driver does not support binary messages.

This method is equivalent to `driver.messages.write(buffer)`.

#### `driver.ping(string = '', function() {})`

Sends a ping frame over the socket, queueing it if necessary. `string` and the
callback are both optional. If a callback is given, it will be invoked when the
socket receives a pong frame whose content matches `string`. Returns `false` if
frames can no longer be sent, or if the driver does not support ping/pong.

#### `driver.pong(string = '')`

Sends a pong frame over the socket, queueing it if necessary. `string` is
optional. Returns `false` if frames can no longer be sent, or if the driver does
not support ping/pong.

You don't need to call this when a ping frame is received; pings are replied to
automatically by the driver. This method is for sending unsolicited pongs.

#### `driver.close()`

Initiates the closing handshake if the socket is still open. For drivers with no
closing handshake, this will result in the immediate execution of the
`on('close')` driver. For drivers with a closing handshake, this sends a closing
frame and `emit('close')` will execute when a response is received or a protocol
error occurs.

#### `driver.version`

Returns the WebSocket version in use as a string. Will either be `hixie-75`,
`hixie-76` or `hybi-$version`.

#### `driver.protocol`

Returns a string containing the selected subprotocol, if any was agreed upon
using the `Sec-WebSocket-Protocol` mechanism. This value becomes available after
`emit('open')` has fired.


---

### 0.1.4 / 2020-06-02

- Remove a ReDoS vulnerability in the header parser (CVE-2020-7662, reported by
  Robert McLaughlin)
- Change license from MIT to Apache 2.0

### 0.1.3 / 2017-11-11

- Accept extension names and parameters including uppercase letters
- Handle extension names that clash with `Object.prototype` properties

### 0.1.2 / 2017-09-10

- Catch synchronous exceptions thrown when calling an extension
- Fix race condition caused when a message is pushed after a cell has stopped
  due to an error
- Fix failure of `close()` to return if a message that's queued after one that
  produces an error never finishes being processed

### 0.1.1 / 2015-02-19

- Prevent sessions being closed before they have finished processing messages
- Add a callback to `Extensions.close()` so the caller can tell when it's safe
  to close the socket

### 0.1.0 / 2014-12-12

- Initial release


---

Copyright 2014-2020 James Coglan

Licensed under the Apache License, Version 2.0 (the "License"); you may not use
this file except in compliance with the License. You may obtain a copy of the
License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed
under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
CONDITIONS OF ANY KIND, either express or implied. See the License for the
specific language governing permissions and limitations under the License.


---

# websocket-extensions [![Build status](https://secure.travis-ci.org/faye/websocket-extensions-node.svg)](http://travis-ci.org/faye/websocket-extensions-node)

A minimal framework that supports the implementation of WebSocket extensions in
a way that's decoupled from the main protocol. This library aims to allow a
WebSocket extension to be written and used with any protocol library, by
defining abstract representations of frames and messages that allow modules to
co-operate.

`websocket-extensions` provides a container for registering extension plugins,
and provides all the functions required to negotiate which extensions to use
during a session via the `Sec-WebSocket-Extensions` header. By implementing the
APIs defined in this document, an extension may be used by any WebSocket library
based on this framework.

## Installation

```
$ npm install websocket-extensions
```

## Usage

There are two main audiences for this library: authors implementing the
WebSocket protocol, and authors implementing extensions. End users of a
WebSocket library or an extension should be able to use any extension by passing
it as an argument to their chosen protocol library, without needing to know how
either of them work, or how the `websocket-extensions` framework operates.

The library is designed with the aim that any protocol implementation and any
extension can be used together, so long as they support the same abstract
representation of frames and messages.

### Data types

The APIs provided by the framework rely on two data types; extensions will
expect to be given data and to be able to return data in these formats:

#### *Frame*

*Frame* is a structure representing a single WebSocket frame of any type. Frames
are simple objects that must have at least the following properties, which
represent the data encoded in the frame:

| property     | description                                                        |
| ------------ | ------------------------------------------------------------------ |
| `final`      | `true` if the `FIN` bit is set, `false` otherwise                  |
| `rsv1`       | `true` if the `RSV1` bit is set, `false` otherwise                 |
| `rsv2`       | `true` if the `RSV2` bit is set, `false` otherwise                 |
| `rsv3`       | `true` if the `RSV3` bit is set, `false` otherwise                 |
| `opcode`     | the numeric opcode (`0`, `1`, `2`, `8`, `9`, or `10`) of the frame |
| `masked`     | `true` if the `MASK` bit is set, `false` otherwise                 |
| `maskingKey` | a 4-byte `Buffer` if `masked` is `true`, otherwise `null`          |
| `payload`    | a `Buffer` containing the (unmasked) application data              |

#### *Message*

A *Message* represents a complete application message, which can be formed from
text, binary and continuation frames. It has the following properties:

| property | description                                                       |
| -------- | ----------------------------------------------------------------- |
| `rsv1`   | `true` if the first frame of the message has the `RSV1` bit set   |
| `rsv2`   | `true` if the first frame of the message has the `RSV2` bit set   |
| `rsv3`   | `true` if the first frame of the message has the `RSV3` bit set   |
| `opcode` | the numeric opcode (`1` or `2`) of the first frame of the message |
| `data`   | the concatenation of all the frame payloads in the message        |

### For driver authors

A driver author is someone implementing the WebSocket protocol proper, and who
wishes end users to be able to use WebSocket extensions with their library.

At the start of a WebSocket session, on both the client and the server side,
they should begin by creating an extension container and adding whichever
extensions they want to use.

```js
var Extensions = require('websocket-extensions'),
    deflate    = require('permessage-deflate');

var exts = new Extensions();
exts.add(deflate);
```

In the following examples, `exts` refers to this `Extensions` instance.

#### Client sessions

Clients will use the methods `generateOffer()` and `activate(header)`.

As part of the handshake process, the client must send a
`Sec-WebSocket-Extensions` header to advertise that it supports the registered
extensions. This header should be generated using:

```js
request.headers['sec-websocket-extensions'] = exts.generateOffer();
```

This returns a string, for example `"permessage-deflate;
client_max_window_bits"`, that represents all the extensions the client is
offering to use, and their parameters. This string may contain multiple offers
for the same extension.

When the client receives the handshake response from the server, it should pass
the incoming `Sec-WebSocket-Extensions` header in to `exts` to activate the
extensions the server has accepted:

```js
exts.activate(response.headers['sec-websocket-extensions']);
```

If the server has sent any extension responses that the client does not
recognize, or are in conflict with one another for use of RSV bits, or that use
invalid parameters for the named extensions, then `exts.activate()` will
`throw`. In this event, the client driver should fail the connection with
closing code `1010`.

#### Server sessions

Servers will use the method `generateResponse(header)`.

A server session needs to generate a `Sec-WebSocket-Extensions` header to send
in its handshake response:

```js
var clientOffer = request.headers['sec-websocket-extensions'],
    extResponse = exts.generateResponse(clientOffer);

response.headers['sec-websocket-extensions'] = extResponse;
```

Calling `exts.generateResponse(header)` activates those extensions the client
has asked to use, if they are registered, asks each extension for a set of
response parameters, and returns a string containing the response parameters for
all accepted extensions.

#### In both directions

Both clients and servers will use the methods `validFrameRsv(frame)`,
`processIncomingMessage(message)` and `processOutgoingMessage(message)`.

The WebSocket protocol requires that frames do not have any of the `RSV` bits
set unless there is an extension in use that allows otherwise. When processing
an incoming frame, sessions should pass a *Frame* object to:

```js
exts.validFrameRsv(frame)
```

If this method returns `false`, the session should fail the WebSocket connection
with closing code `1002`.

To pass incoming messages through the extension stack, a session should
construct a *Message* object according to the above datatype definitions, and
call:

```js
exts.processIncomingMessage(message, function(error, msg) {
  // hand the message off to the application
});
```

If any extensions fail to process the message, then the callback will yield an
error and the session should fail the WebSocket connection with closing code
`1010`. If `error` is `null`, then `msg` should be passed on to the application.

To pass outgoing messages through the extension stack, a session should
construct a *Message* as before, and call:

```js
exts.processOutgoingMessage(message, function(error, msg) {
  // write message to the transport
});
```

If any extensions fail to process the message, then the callback will yield an
error and the session should fail the WebSocket connection with closing code
`1010`. If `error` is `null`, then `message` should be converted into frames
(with the message's `rsv1`, `rsv2`, `rsv3` and `opcode` set on the first frame)
and written to the transport.

At the end of the WebSocket session (either when the protocol is explicitly
ended or the transport connection disconnects), the driver should call:

```js
exts.close(function() {})
```

The callback is invoked when all extensions have finished processing any
messages in the pipeline and it's safe to close the socket.

### For extension authors

An extension author is someone implementing an extension that transforms
WebSocket messages passing between the client and server. They would like to
implement their extension once and have it work with any protocol library.

Extension authors will not install `websocket-extensions` or call it directly.
Instead, they should implement the following API to allow their extension to
plug into the `websocket-extensions` framework.

An `Extension` is any object that has the following properties:

| property | description                                                                  |
| -------- | ---------------------------------------------------------------------------- |
| `name`   | a string containing the name of the extension as used in negotiation headers |
| `type`   | a string, must be `"permessage"`                                             |
| `rsv1`   | either `true` if the extension uses the RSV1 bit, `false` otherwise          |
| `rsv2`   | either `true` if the extension uses the RSV2 bit, `false` otherwise          |
| `rsv3`   | either `true` if the extension uses the RSV3 bit, `false` otherwise          |

It must also implement the following methods:

```js
ext.createClientSession()
```

This returns a *ClientSession*, whose interface is defined below.

```js
ext.createServerSession(offers)
```

This takes an array of offer params and returns a *ServerSession*, whose
interface is defined below. For example, if the client handshake contains the
offer header:

```
Sec-WebSocket-Extensions: permessage-deflate; server_no_context_takeover; server_max_window_bits=8, \
                          permessage-deflate; server_max_window_bits=15
```

then the `permessage-deflate` extension will receive the call:

```js
ext.createServerSession([
  { server_no_context_takeover: true, server_max_window_bits: 8 },
  { server_max_window_bits: 15 }
]);
```

The extension must decide which set of parameters it wants to accept, if any,
and return a *ServerSession* if it wants to accept the parameters and `null`
otherwise.

#### *ClientSession*

A *ClientSession* is the type returned by `ext.createClientSession()`. It must
implement the following methods, as well as the *Session* API listed below.

```js
clientSession.generateOffer()
// e.g.  -> [
//            { server_no_context_takeover: true, server_max_window_bits: 8 },
//            { server_max_window_bits: 15 }
//          ]
```

This must return a set of parameters to include in the client's
`Sec-WebSocket-Extensions` offer header. If the session wants to offer multiple
configurations, it can return an array of sets of parameters as shown above.

```js
clientSession.activate(params) // -> true
```

This must take a single set of parameters from the server's handshake response
and use them to configure the client session. If the client accepts the given
parameters, then this method must return `true`. If it returns any other value,
the framework will interpret this as the client rejecting the response, and will
`throw`.

#### *ServerSession*

A *ServerSession* is the type returned by `ext.createServerSession(offers)`. It
must implement the following methods, as well as the *Session* API listed below.

```js
serverSession.generateResponse()
// e.g.  -> { server_max_window_bits: 8 }
```

This returns the set of parameters the server session wants to send in its
`Sec-WebSocket-Extensions` response header. Only one set of parameters is
returned to the client per extension. Server sessions that would confict on
their use of RSV bits are not activated.

#### *Session*

The *Session* API must be implemented by both client and server sessions. It
contains two methods, `processIncomingMessage(message)` and
`processOutgoingMessage(message)`.

```js
session.processIncomingMessage(message, function(error, msg) { ... })
```

The session must implement this method to take an incoming *Message* as defined
above, transform it in any way it needs, then return it via the callback. If
there is an error processing the message, this method should yield an error as
the first argument.

```js
session.processOutgoingMessage(message, function(error, msg) { ... })
```

The session must implement this method to take an outgoing *Message* as defined
above, transform it in any way it needs, then return it via the callback. If
there is an error processing the message, this method should yield an error as
the first argument.

Note that both `processIncomingMessage()` and `processOutgoingMessage()` can
perform their logic asynchronously, are allowed to process multiple messages
concurrently, and are not required to complete working on messages in the same
order the messages arrive. `websocket-extensions` will reorder messages as your
extension emits them and will make sure every extension is given messages in the
order they arrive from the driver. This allows extensions to maintain state that
depends on the messages' wire order, for example keeping a DEFLATE compression
context between messages.

```js
session.close()
```

The framework will call this method when the WebSocket session ends, allowing
the session to release any resources it's using.

## Examples

- Consumer: [websocket-driver](https://github.com/faye/websocket-driver-node)
- Provider: [permessage-deflate](https://github.com/faye/permessage-deflate-node)


---

# Extension pipelining

`websocket-extensions` models the extension negotiation and processing pipeline
of the WebSocket protocol. Between the driver parsing messages from the TCP
stream and handing those messages off to the application, there may exist a
stack of extensions that transform the message somehow.

In the parlance of this framework, a *session* refers to a single instance of an
extension, acting on a particular socket on either the server or the client
side. A session may transform messages both incoming to the application and
outgoing from the application, for example the `permessage-deflate` extension
compresses outgoing messages and decompresses incoming messages. Message streams
in either direction are independent; that is, incoming and outgoing messages
cannot be assumed to 'pair up' as in a request-response protocol.

Asynchronous processing of messages poses a number of problems that this
pipeline construction is intended to solve.


## Overview

Logically, we have the following:


    +-------------+  out  +---+     +---+     +---+       +--------+
    |             |------>|   |---->|   |---->|   |------>|        |
    | Application |       | A |     | B |     | C |       | Driver |
    |             |<------|   |<----|   |<----|   |<------|        |
    +-------------+  in   +---+     +---+     +---+       +--------+

                          \                       /
                           +----------o----------+
                                      |
                                   sessions


For outgoing messages, the driver receives the result of

        C.outgoing(B.outgoing(A.outgoing(message)))

    or, [A, B, C].reduce(((m, ext) => ext.outgoing(m)), message)

For incoming messages, the application receives the result of

        A.incoming(B.incoming(C.incoming(message)))

    or, [C, B, A].reduce(((m, ext) => ext.incoming(m)), message)

A session is of the following type, to borrow notation from pseudo-Haskell:

    type Session = {
      incoming :: Message -> Message
      outgoing :: Message -> Message
      close    :: () -> ()
    }

(That `() -> ()` syntax is intended to mean that `close()` is a nullary void
method; I apologise to any Haskell readers for not using the right monad.)

The `incoming()` and `outgoing()` methods perform message transformation in the
respective directions; `close()` is called when a socket closes so the session
can release any resources it's holding, for example a DEFLATE de/compression
context.

However because this is JavaScript, the `incoming()` and `outgoing()` methods
may be asynchronous (indeed, `permessage-deflate` is based on `zlib`, whose API
is stream-based). So their interface is strictly:

    type Session = {
      incoming :: Message -> Callback -> ()
      outgoing :: Message -> Callback -> ()
      close    :: () -> ()
    }

    type Callback = Either Error Message -> ()

This means a message *m2* can be pushed into a session while it's still
processing the preceding message *m1*. The messages can be processed
concurrently but they *must* be given to the next session in line (or to the
application) in the same order they came in. Applications will expect to receive
messages in the order they arrived over the wire, and sessions require this too.
So ordering of messages must be preserved throughout the pipeline.

Consider the following highly simplified extension that deflates messages on the
wire. `message` is a value conforming the type:

    type Message = {
      rsv1   :: Boolean
      rsv2   :: Boolean
      rsv3   :: Boolean
      opcode :: Number
      data   :: Buffer
    }

Here's the extension:

```js
var zlib = require('zlib');

var deflate = {
  outgoing: function(message, callback) {
    zlib.deflateRaw(message.data, function(error, result) {
      message.rsv1 = true;
      message.data = result;
      callback(error, message);
    });
  },

  incoming: function(message, callback) {
    // decompress inbound messages (elided)
  },

  close: function() {
    // no state to clean up
  }
};
```

We can call it with a large message followed by a small one, and the small one
will be returned first:

```js
var crypto = require('crypto'),
    large  = crypto.randomBytes(1 << 14),
    small  = new Buffer('hi');

deflate.outgoing({ data: large }, function() {
  console.log(1, 'large');
});

deflate.outgoing({ data: small }, function() {
  console.log(2, 'small');
});

/* prints:  2 'small'
            1 'large' */
```

So a session that processes messages asynchronously may fail to preserve message
ordering.

Now, this extension is stateless, so it can process messages in any order and
still produce the same output. But some extensions are stateful and require
message order to be preserved.

For example, when using `permessage-deflate` without `no_context_takeover` set,
the session retains a DEFLATE de/compression context between messages, which
accumulates state as it consumes data (later messages can refer to sections of
previous ones to improve compression). Reordering parts of the DEFLATE stream
will result in a failed decompression. Messages must be decompressed in the same
order they were compressed by the peer in order for the DEFLATE protocol to
work.

Finally, there is the problem of closing a socket. When a WebSocket is closed by
the application, or receives a closing request from the other peer, there may be
messages outgoing from the application and incoming from the peer in the
pipeline. If we close the socket and pipeline immediately, two problems arise:

* We may send our own closing frame to the peer before all prior messages we
  sent have been written to the socket, and before we have finished processing
  all prior messages from the peer
* The session may be instructed to close its resources (e.g. its de/compression
  context) while it's in the middle of processing a message, or before it has
  received messages that are upstream of it in the pipeline

Essentially, we must defer closing the sessions and sending a closing frame
until after all prior messages have exited the pipeline.


## Design goals

* Message order must be preserved between the protocol driver, the extension
  sessions, and the application
* Messages should be handed off to sessions and endpoints as soon as possible,
  to maximise throughput of stateless sessions
* The closing procedure should block any further messages from entering the
  pipeline, and should allow all existing messages to drain
* Sessions should be closed as soon as possible to prevent them holding memory
  and other resources when they have no more messages to handle
* The closing API should allow the caller to detect when the pipeline is empty
  and it is safe to continue the WebSocket closing procedure
* Individual extensions should remain as simple as possible to facilitate
  modularity and independent authorship

The final point about modularity is an important one: this framework is designed
to facilitate extensions existing as plugins, by decoupling the protocol driver,
extensions, and application. In an ideal world, plugins should only need to
contain code for their specific functionality, and not solve these problems that
apply to all sessions. Also, solving some of these problems requires
consideration of all active sessions collectively, which an individual session
is incapable of doing.

For example, it is entirely possible to take the simple `deflate` extension
above and wrap its `incoming()` and `outgoing()` methods in two `Transform`
streams, producing this type:

    type Session = {
      incoming :: TransformStream
      outtoing :: TransformStream
      close    :: () -> ()
    }

The `Transform` class makes it easy to wrap an async function such that message
order is preserved:

```js
var stream  = require('stream'),
    session = new stream.Transform({ objectMode: true });

session._transform = function(message, _, callback) {
  var self = this;
  deflate.outgoing(message, function(error, result) {
    self.push(result);
    callback();
  });
};
```

However, this has a negative impact on throughput: it works by deferring
`callback()` until the async function has 'returned', which blocks `Transform`
from passing further input into the `_transform()` method until the current
message is dealt with completely. This would prevent sessions from processing
messages concurrently, and would unnecessarily reduce the throughput of
stateless extensions.

So, input should be handed off to sessions as soon as possible, and all we need
is a mechanism to reorder the output so that message order is preserved for the
next session in line.


## Solution

We now describe the model implemented here and how it meets the above design
goals. The above diagram where a stack of extensions sit between the driver and
application describes the data flow, but not the object graph. That looks like
this:


            +--------+
            | Driver |
            +---o----+
                |
                V
          +------------+      +----------+
          | Extensions o----->| Pipeline |
          +------------+      +-----o----+
                                    |
                    +---------------+---------------+
                    |               |               |
              +-----o----+    +-----o----+    +-----o----+
              | Cell [A] |    | Cell [B] |    | Cell [C] |
              +----------+    +----------+    +----------+


A driver using this framework holds an instance of the `Extensions` class, which
it uses to register extension plugins, negotiate headers and transform messages.
The `Extensions` instance itself holds a `Pipeline`, which contains an array of
`Cell` objects, each of which wraps one of the sessions.


### Message processing

Both the `Pipeline` and `Cell` classes have `incoming()` and `outgoing()`
methods; the `Pipeline` interface pushes messages into the pipe, delegates the
message to each `Cell` in turn, then returns it back to the driver. Outgoing
messages pass through `A` then `B` then `C`, and incoming messages in the
reverse order.

Internally, a `Cell` contains two `Functor` objects. A `Functor` wraps an async
function and makes sure its output messages maintain the order of its input
messages. This name is due to [@fronx](https://github.com/fronx), on the basis
that, by preserving message order, the abstraction preserves the *mapping*
between input and output messages. To use our simple `deflate` extension from
above:

```js
var functor = new Functor(deflate, 'outgoing');

functor.call({ data: large }, function() {
  console.log(1, 'large');
});

functor.call({ data: small }, function() {
  console.log(2, 'small');
});

/*  ->  1 'large'
        2 'small' */
```

A `Cell` contains two of these, one for each direction:


                            +-----------------------+
                      +---->| Functor [A, incoming] |
    +----------+      |     +-----------------------+
    | Cell [A] o------+
    +----------+      |     +-----------------------+
                      +---->| Functor [A, outgoing] |
                            +-----------------------+


This satisfies the message transformation requirements: the `Pipeline` simply
loops over the cells in the appropriate direction to transform each message.
Because each `Cell` will preserve message order, we can pass a message to the
next `Cell` in line as soon as the current `Cell` returns it. This gives each
`Cell` all the messages in order while maximising throughput.


### Session closing

We want to close each session as soon as possible, after all existing messages
have drained. To do this, each `Cell` begins with a pending message counter in
each direction, labelled `in` and `out` below.


                              +----------+
                              | Pipeline |
                              +-----o----+
                                    |
                    +---------------+---------------+
                    |               |               |
              +-----o----+    +-----o----+    +-----o----+
              | Cell [A] |    | Cell [B] |    | Cell [C] |
              +----------+    +----------+    +----------+
                 in: 0           in: 0           in: 0
                out: 0          out: 0          out: 0


When a message *m1* enters the pipeline, say in the `outgoing` direction, we
increment the `pending.out` counter on all cells immediately.


                              +----------+
                        m1 => | Pipeline |
                              +-----o----+
                                    |
                    +---------------+---------------+
                    |               |               |
              +-----o----+    +-----o----+    +-----o----+
              | Cell [A] |    | Cell [B] |    | Cell [C] |
              +----------+    +----------+    +----------+
                 in: 0           in: 0           in: 0
                out: 1          out: 1          out: 1


*m1* is handed off to `A`, meanwhile a second message `m2` arrives in the same
direction. All `pending.out` counters are again incremented.


                              +----------+
                        m2 => | Pipeline |
                              +-----o----+
                                    |
                    +---------------+---------------+
                m1  |               |               |
              +-----o----+    +-----o----+    +-----o----+
              | Cell [A] |    | Cell [B] |    | Cell [C] |
              +----------+    +----------+    +----------+
                 in: 0           in: 0           in: 0
                out: 2          out: 2          out: 2


When the first cell's `A.outgoing` functor finishes processing *m1*, the first
`pending.out` counter is decremented and *m1* is handed off to cell `B`.


                              +----------+
                              | Pipeline |
                              +-----o----+
                                    |
                    +---------------+---------------+
                m2  |           m1  |               |
              +-----o----+    +-----o----+    +-----o----+
              | Cell [A] |    | Cell [B] |    | Cell [C] |
              +----------+    +----------+    +----------+
                 in: 0           in: 0           in: 0
                out: 1          out: 2          out: 2



As `B` finishes with *m1*, and as `A` finishes with *m2*, the `pending.out`
counters continue to decrement.


                              +----------+
                              | Pipeline |
                              +-----o----+
                                    |
                    +---------------+---------------+
                    |           m2  |           m1  |
              +-----o----+    +-----o----+    +-----o----+
              | Cell [A] |    | Cell [B] |    | Cell [C] |
              +----------+    +----------+    +----------+
                 in: 0           in: 0           in: 0
                out: 0          out: 1          out: 2



Say `C` is a little slow, and begins processing *m2* while still processing
*m1*. That's fine, the `Functor` mechanism will keep *m1* ahead of *m2* in the
output.


                              +----------+
                              | Pipeline |
                              +-----o----+
                                    |
                    +---------------+---------------+
                    |               |           m2  | m1
              +-----o----+    +-----o----+    +-----o----+
              | Cell [A] |    | Cell [B] |    | Cell [C] |
              +----------+    +----------+    +----------+
                 in: 0           in: 0           in: 0
                out: 0          out: 0          out: 2


Once all messages are dealt with, the counters return to `0`.


                              +----------+
                              | Pipeline |
                              +-----o----+
                                    |
                    +---------------+---------------+
                    |               |               |
              +-----o----+    +-----o----+    +-----o----+
              | Cell [A] |    | Cell [B] |    | Cell [C] |
              +----------+    +----------+    +----------+
                 in: 0           in: 0           in: 0
                out: 0          out: 0          out: 0


The same process applies in the `incoming` direction, the only difference being
that messages are passed to `C` first.

This makes closing the sessions quite simple. When the driver wants to close the
socket, it calls `Pipeline.close()`. This *immediately* calls `close()` on all
the cells. If a cell has `in == out == 0`, then it immediately calls
`session.close()`. Otherwise, it stores the closing call and defers it until
`in` and `out` have both ticked down to zero. The pipeline will not accept new
messages after `close()` has been called, so we know the pending counts will not
increase after this point.

This means each session is closed as soon as possible: `A` can close while the
slow `C` session is still working, because it knows there are no more messages
on the way. Similarly, `C` will defer closing if `close()` is called while *m1*
is still in `B`, and *m2* in `A`, because its pending count means it knows it
has work yet to do, even if it's not received those messages yet. This concern
cannot be addressed by extensions acting only on their own local state, unless
we pollute individual extensions by making them all implement this same
mechanism.

The actual closing API at each level is slightly different:

    type Session = {
      close :: () -> ()
    }

    type Cell = {
      close :: () -> Promise ()
    }

    type Pipeline = {
      close :: Callback -> ()
    }

This might appear inconsistent so it's worth explaining. Remember that a
`Pipeline` holds a list of `Cell` objects, each wrapping a `Session`. The driver
talks (via the `Extensions` API) to the `Pipeline` interface, and it wants
`Pipeline.close()` to do two things: close all the sessions, and tell me when
it's safe to start the closing procedure (i.e. when all messages have drained
from the pipe and been handed off to the application or socket). A callback API
works well for that.

At the other end of the stack, `Session.close()` is a nullary void method with
no callback or promise API because we don't care what it does, and whatever it
does do will not block the WebSocket protocol; we're not going to hold off
processing messages while a session closes its de/compression context. We just
tell it to close itself, and don't want to wait while it does that.

In the middle, `Cell.close()` returns a promise rather than using a callback.
This is for two reasons. First, `Cell.close()` might not do anything
immediately, it might have to defer its effect while messages drain. So, if
given a callback, it would have to store it in a queue for later execution.
Callbacks work fine if your method does something and can then invoke the
callback itself, but if you need to store callbacks somewhere so another method
can execute them, a promise is a better fit. Second, it better serves the
purposes of `Pipeline.close()`: it wants to call `close()` on each of a list of
cells, and wait for all of them to finish. This is simple and idiomatic using
promises:

```js
var closed = cells.map((cell) => cell.close());
Promise.all(closed).then(callback);
```

(We don't actually use a full *Promises/A+* compatible promise here, we use a
much simplified construction that acts as a callback aggregater and resolves
synchronously and does not support chaining, but the principle is the same.)


### Error handling

We've not mentioned error handling so far but it bears some explanation. The
above counter system still applies, but behaves slightly differently in the
presence of errors.

Say we push three messages into the pipe in the outgoing direction:


                              +----------+
                m3, m2, m1 => | Pipeline |
                              +-----o----+
                                    |
                    +---------------+---------------+
                    |               |               |
              +-----o----+    +-----o----+    +-----o----+
              | Cell [A] |    | Cell [B] |    | Cell [C] |
              +----------+    +----------+    +----------+
                 in: 0           in: 0           in: 0
                out: 3          out: 3          out: 3


They pass through the cells successfully up to this point:


                              +----------+
                              | Pipeline |
                              +-----o----+
                                    |
                    +---------------+---------------+
                m3  |           m2  |           m1  |
              +-----o----+    +-----o----+    +-----o----+
              | Cell [A] |    | Cell [B] |    | Cell [C] |
              +----------+    +----------+    +----------+
                 in: 0           in: 0           in: 0
                out: 1          out: 2          out: 3


At this point, session `B` produces an error while processing *m2*, that is *m2*
becomes *e2*. *m1* is still in the pipeline, and *m3* is queued behind *m2*.
What ought to happen is that *m1* is handed off to the socket, then *m2* is
released to the driver, which will detect the error and begin closing the
socket. No further processing should be done on *m3* and it should not be
released to the driver after the error is emitted.

To handle this, we allow errors to pass down the pipeline just like messages do,
to maintain ordering. But, once a cell sees its session produce an error, or it
receives an error from upstream, it should refuse to accept any further
messages. Session `B` might have begun processing *m3* by the time it produces
the error *e2*, but `C` will have been given *e2* before it receives *m3*, and
can simply drop *m3*.

Now, say *e2* reaches the slow session `C` while *m1* is still present,
meanwhile *m3* has been dropped. `C` will never receive *m3* since it will have
been dropped upstream. Under the present model, its `out` counter will be `3`
but it is only going to emit two more values: *m1* and *e2*. In order for
closing to work, we need to decrement `out` to reflect this. The situation
should look like this:


                              +----------+
                              | Pipeline |
                              +-----o----+
                                    |
                    +---------------+---------------+
                    |               |           e2  | m1
              +-----o----+    +-----o----+    +-----o----+
              | Cell [A] |    | Cell [B] |    | Cell [C] |
              +----------+    +----------+    +----------+
                 in: 0           in: 0           in: 0
                out: 0          out: 0          out: 2


When a cell sees its session emit an error, or when it receives an error from
upstream, it sets its pending count in the appropriate direction to equal the
number of messages it is *currently* processing. It will not accept any messages
after it sees the error, so this will allow the counter to reach zero.

Note that while *e2* is in the pipeline, `Pipeline` should drop any further
messages in the outgoing direction, but should continue to accept incoming
messages. Until *e2* makes it out of the pipe to the driver, behind previous
successful messages, the driver does not know an error has happened, and a
message may arrive over the socket and make it all the way through the incoming
pipe in the meantime. We only halt processing in the affected direction to avoid
doing unnecessary work since messages arriving after an error should not be
processed.

Some unnecessary work may happen, for example any messages already in the
pipeline following *m2* will be processed by `A`, since it's upstream of the
error. Those messages will be dropped by `B`.


## Alternative ideas

I am considering implementing `Functor` as an object-mode transform stream
rather than what is essentially an async function. Being object-mode, a stream
would preserve message boundaries and would also possibly help address
back-pressure. I'm not sure whether this would require external API changes so
that such streams could be connected to the downstream driver's streams.


## Acknowledgements

Credit is due to [@mnowster](https://github.com/mnowster) for helping with the
design and to [@fronx](https://github.com/fronx) for helping name things.


---

# Changes


## 2.0.2

* Rename bin to `node-which`

## 2.0.1

* generate changelog and publish on version bump
* enforce 100% test coverage
* Promise interface

## 2.0.0

* Parallel tests, modern JavaScript, and drop support for node < 8

## 1.3.1

* update deps
* update travis

## v1.3.0

* Add nothrow option to which.sync
* update tap

## v1.2.14

* appveyor: drop node 5 and 0.x
* travis-ci: add node 6, drop 0.x

## v1.2.13

* test: Pass missing option to pass on windows
* update tap
* update isexe to 2.0.0
* neveragain.tech pledge request

## v1.2.12

* Removed unused require

## v1.2.11

* Prevent changelog script from being included in package

## v1.2.10

* Use env.PATH only, not env.Path

## v1.2.9

* fix for paths starting with ../
* Remove unused `is-absolute` module

## v1.2.8

* bullet items in changelog that contain (but don't start with) #

## v1.2.7

* strip 'update changelog' changelog entries out of changelog

## v1.2.6

* make the changelog bulleted

## v1.2.5

* make a changelog, and keep it up to date
* don't include tests in package
* Properly handle relative-path executables
* appveyor
* Attach error code to Not Found error
* Make tests pass on Windows

## v1.2.4

* Fix typo

## v1.2.3

* update isexe, fix regression in pathExt handling

## v1.2.2

* update deps, use isexe module, test windows

## v1.2.1

* Sometimes windows PATH entries are quoted
* Fixed a bug in the check for group and user mode bits. This bug was introduced during refactoring for supporting strict mode.
* doc cli

## v1.2.0

* Add support for opt.all and -as cli flags
* test the bin
* update travis
* Allow checking for multiple programs in bin/which
* tap 2

## v1.1.2

* travis
* Refactored and fixed undefined error on Windows
* Support strict mode

## v1.1.1

* test +g exes against secondary groups, if available
* Use windows exe semantics on cygwin & msys
* cwd should be first in path on win32, not last
* Handle lower-case 'env.Path' on Windows
* Update docs
* use single-quotes

## v1.1.0

* Add tests, depend on is-absolute

## v1.0.9

* which.js: root is allowed to execute files owned by anyone

## v1.0.8

* don't use graceful-fs

## v1.0.7

* add license to package.json

## v1.0.6

* isc license

## 1.0.5

* Awful typo

## 1.0.4

* Test for path absoluteness properly
* win: Allow '' as a pathext if cmd has a . in it

## 1.0.3

* Remove references to execPath
* Make `which.sync()` work on Windows by honoring the PATHEXT variable.
* Make `isExe()` always return true on Windows.
* MIT

## 1.0.2

* Only files can be exes

## 1.0.1

* Respect the PATHEXT env for win32 support
* should 0755 the bin
* binary
* guts
* package
* 1st


---

# which

Like the unix `which` utility.

Finds the first instance of a specified executable in the PATH
environment variable.  Does not cache the results, so `hash -r` is not
needed when the PATH changes.

## USAGE

```javascript
var which = require('which')

// async usage
which('node', function (er, resolvedPath) {
  // er is returned if no "node" is found on the PATH
  // if it is found, then the absolute path to the exec is returned
})

// or promise
which('node').then(resolvedPath => { ... }).catch(er => { ... not found ... })

// sync usage
// throws if not found
var resolved = which.sync('node')

// if nothrow option is used, returns null if not found
resolved = which.sync('node', {nothrow: true})

// Pass options to override the PATH and PATHEXT environment vars.
which('node', { path: someOtherPath }, function (er, resolved) {
  if (er)
    throw er
  console.log('found at %j', resolved)
})
```

## CLI USAGE

Same as the BSD `which(1)` binary.

```
usage: which [-as] program ...
```

## OPTIONS

You may pass an options object as the second argument.

- `path`: Use instead of the `PATH` environment variable.
- `pathExt`: Use instead of the `PATHEXT` environment variable.
- `all`: Return all matches, instead of just the first one.  Note that
  this means the function returns an array of strings instead of a
  single string.


---

# widest-line

> Get the visual width of the widest line in a string - the number of columns required to display it

Some Unicode characters are [fullwidth](https://en.wikipedia.org/wiki/Halfwidth_and_fullwidth_forms) and use double the normal width. [ANSI escape codes](http://en.wikipedia.org/wiki/ANSI_escape_code) are stripped and doesn't affect the width.

Useful to be able to know the maximum width a string will take up in the terminal.

## Install

```sh
npm install widest-line
```

## Usage

```js
import widestLine from 'widest-line';

widestLine('古\n\u001B[1m@\u001B[22m');
//=> 2
```

## Related

- [string-width](https://github.com/sindresorhus/string-width) - Get the visual width of a string


---

# wildcard

Very simple wildcard matching, which is designed to provide the same
functionality that is found in the
[eve](https://github.com/adobe-webplatform/eve) eventing library.

[![NPM](https://nodei.co/npm/wildcard.png)](https://nodei.co/npm/wildcard/)

[![stable](https://img.shields.io/badge/stability-stable-green.svg)](https://github.com/dominictarr/stability#stable)

## Usage

It works with strings:

```js
var wildcard = require('wildcard');

console.log(wildcard('foo.*', 'foo.bar'));
// --> true

console.log(wildcard('foo.*', 'foo'));
// --> true
```

Arrays:

```js
var wildcard = require('wildcard');
var testdata = [
  'a.b.c',
  'a.b',
  'a',
  'a.b.d'
];

console.log(wildcard('a.b.*', testdata));
// --> ['a.b.c', 'a.b', 'a.b.d']
```

Objects (matching against keys):

```js
var wildcard = require('wildcard');
var testdata = {
  'a.b.c' : {},
  'a.b'   : {},
  'a'     : {},
  'a.b.d' : {}
};

console.log(wildcard('a.*.c', testdata));
// --> { 'a.b.c': {} }
```

## Alternative Implementations

* <https://github.com/isaacs/node-glob>

Great for full file-based wildcard matching.

* <https://github.com/sindresorhus/matcher>

A well cared for and loved JS wildcard matcher.

## License(s)

### MIT

Copyright (c) 2023 Damon Oehlman <&#x6d;&#x61;&#105;&#108;&#116;&#x6f;&#x3a;&#x64;&#x61;&#109;&#111;&#110;&#46;&#111;&#101;&#x68;&#108;&#x6d;&#97;&#x6e;&#x40;&#x67;&#x6d;&#x61;&#x69;&#x6c;&#x2e;&#x63;&#111;&#109;>

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
'Software'), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

---

# ansi-regex

> Regular expression for matching [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code)

## Install

```sh
npm install ansi-regex
```

## Usage

```js
import ansiRegex from 'ansi-regex';

ansiRegex().test('\u001B[4mcake\u001B[0m');
//=> true

ansiRegex().test('cake');
//=> false

'\u001B[4mcake\u001B[0m'.match(ansiRegex());
//=> ['\u001B[4m', '\u001B[0m']

'\u001B[4mcake\u001B[0m'.match(ansiRegex({onlyFirst: true}));
//=> ['\u001B[4m']

'\u001B]8;;https://github.com\u0007click\u001B]8;;\u0007'.match(ansiRegex());
//=> ['\u001B]8;;https://github.com\u0007', '\u001B]8;;\u0007']
```

## API

### ansiRegex(options?)

Returns a regex for matching ANSI escape codes.

#### options

Type: `object`

##### onlyFirst

Type: `boolean`\
Default: `false` *(Matches any ANSI escape codes in a string)*

Match only the first ANSI escape.

## FAQ

### Why do you test for codes not in the ECMA 48 standard?

Some of the codes we run as a test are codes that we acquired finding various lists of non-standard or manufacturer specific codes. We test for both standard and non-standard codes, as most of them follow the same or similar format and can be safely matched in strings without the risk of removing actual string content. There are a few non-standard control codes that do not follow the traditional format (i.e. they end in numbers) thus forcing us to exclude them from the test because we cannot reliably match them.

On the historical side, those ECMA standards were established in the early 90's whereas the VT100, for example, was designed in the mid/late 70's. At that point in time, control codes were still pretty ungoverned and engineers used them for a multitude of things, namely to activate hardware ports that may have been proprietary. Somewhere else you see a similar 'anarchy' of codes is in the x86 architecture for processors; there are a ton of "interrupts" that can mean different things on certain brands of processors, most of which have been phased out.

## Maintainers

- [Sindre Sorhus](https://github.com/sindresorhus)
- [Josh Junon](https://github.com/qix-)


---

# ansi-styles

> [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors_and_Styles) for styling strings in the terminal

You probably want the higher-level [chalk](https://github.com/chalk/chalk) module for styling your strings.

![](screenshot.png)

## Install

```sh
npm install ansi-styles
```

## Usage

```js
import styles from 'ansi-styles';

console.log(`${styles.green.open}Hello world!${styles.green.close}`);


// Color conversion between 256/truecolor
// NOTE: When converting from truecolor to 256 colors, the original color
//       may be degraded to fit the new color palette. This means terminals
//       that do not support 16 million colors will best-match the
//       original color.
console.log(`${styles.color.ansi(styles.rgbToAnsi(199, 20, 250))}Hello World${styles.color.close}`)
console.log(`${styles.color.ansi256(styles.rgbToAnsi256(199, 20, 250))}Hello World${styles.color.close}`)
console.log(`${styles.color.ansi16m(...styles.hexToRgb('#abcdef'))}Hello World${styles.color.close}`)
```

## API

### `open` and `close`

Each style has an `open` and `close` property.

### `modifierNames`, `foregroundColorNames`, `backgroundColorNames`, and `colorNames`

All supported style strings are exposed as an array of strings for convenience. `colorNames` is the combination of `foregroundColorNames` and `backgroundColorNames`.

This can be useful if you need to validate input:

```js
import {modifierNames, foregroundColorNames} from 'ansi-styles';

console.log(modifierNames.includes('bold'));
//=> true

console.log(foregroundColorNames.includes('pink'));
//=> false
```

## Styles

### Modifiers

- `reset`
- `bold`
- `dim`
- `italic` *(Not widely supported)*
- `underline`
- `overline` *Supported on VTE-based terminals, the GNOME terminal, mintty, and Git Bash.*
- `inverse`
- `hidden`
- `strikethrough` *(Not widely supported)*

### Colors

- `black`
- `red`
- `green`
- `yellow`
- `blue`
- `magenta`
- `cyan`
- `white`
- `blackBright` (alias: `gray`, `grey`)
- `redBright`
- `greenBright`
- `yellowBright`
- `blueBright`
- `magentaBright`
- `cyanBright`
- `whiteBright`

### Background colors

- `bgBlack`
- `bgRed`
- `bgGreen`
- `bgYellow`
- `bgBlue`
- `bgMagenta`
- `bgCyan`
- `bgWhite`
- `bgBlackBright` (alias: `bgGray`, `bgGrey`)
- `bgRedBright`
- `bgGreenBright`
- `bgYellowBright`
- `bgBlueBright`
- `bgMagentaBright`
- `bgCyanBright`
- `bgWhiteBright`

## Advanced usage

By default, you get a map of styles, but the styles are also available as groups. They are non-enumerable so they don't show up unless you access them explicitly. This makes it easier to expose only a subset in a higher-level module.

- `styles.modifier`
- `styles.color`
- `styles.bgColor`

###### Example

```js
import styles from 'ansi-styles';

console.log(styles.color.green.open);
```

Raw escape codes (i.e. without the CSI escape prefix `\u001B[` and render mode postfix `m`) are available under `styles.codes`, which returns a `Map` with the open codes as keys and close codes as values.

###### Example

```js
import styles from 'ansi-styles';

console.log(styles.codes.get(36));
//=> 39
```

## 16 / 256 / 16 million (TrueColor) support

`ansi-styles` allows converting between various color formats and ANSI escapes, with support for 16, 256 and [16 million colors](https://gist.github.com/XVilka/8346728).

The following color spaces are supported:

- `rgb`
- `hex`
- `ansi256`
- `ansi`

To use these, call the associated conversion function with the intended output, for example:

```js
import styles from 'ansi-styles';

styles.color.ansi(styles.rgbToAnsi(100, 200, 15)); // RGB to 16 color ansi foreground code
styles.bgColor.ansi(styles.hexToAnsi('#C0FFEE')); // HEX to 16 color ansi foreground code

styles.color.ansi256(styles.rgbToAnsi256(100, 200, 15)); // RGB to 256 color ansi foreground code
styles.bgColor.ansi256(styles.hexToAnsi256('#C0FFEE')); // HEX to 256 color ansi foreground code

styles.color.ansi16m(100, 200, 15); // RGB to 16 million color foreground code
styles.bgColor.ansi16m(...styles.hexToRgb('#C0FFEE')); // Hex (RGB) to 16 million color foreground code
```

## Related

- [ansi-escapes](https://github.com/sindresorhus/ansi-escapes) - ANSI escape codes for manipulating the terminal

## Maintainers

- [Sindre Sorhus](https://github.com/sindresorhus)
- [Josh Junon](https://github.com/qix-)

## For enterprise

Available as part of the Tidelift Subscription.

The maintainers of `ansi-styles` and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-ansi-styles?utm_source=npm-ansi-styles&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)


---

# strip-ansi

> Strip [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code) from a string

## Install

```
$ npm install strip-ansi
```

## Usage

```js
import stripAnsi from 'strip-ansi';

stripAnsi('\u001B[4mUnicorn\u001B[0m');
//=> 'Unicorn'

stripAnsi('\u001B]8;;https://github.com\u0007Click\u001B]8;;\u0007');
//=> 'Click'
```

## strip-ansi for enterprise

Available as part of the Tidelift Subscription.

The maintainers of strip-ansi and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-strip-ansi?utm_source=npm-strip-ansi&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)

## Related

- [strip-ansi-cli](https://github.com/chalk/strip-ansi-cli) - CLI for this module
- [strip-ansi-stream](https://github.com/chalk/strip-ansi-stream) - Streaming version of this module
- [has-ansi](https://github.com/chalk/has-ansi) - Check if a string has ANSI escape codes
- [ansi-regex](https://github.com/chalk/ansi-regex) - Regular expression for matching ANSI escape codes
- [chalk](https://github.com/chalk/chalk) - Terminal string styling done right

## Maintainers

- [Sindre Sorhus](https://github.com/sindresorhus)
- [Josh Junon](https://github.com/qix-)



---

# wrap-ansi

> Wordwrap a string with [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors_and_Styles)

## Install

```
$ npm install wrap-ansi
```

## Usage

```js
import chalk from 'chalk';
import wrapAnsi from 'wrap-ansi';

const input = 'The quick brown ' + chalk.red('fox jumped over ') +
	'the lazy ' + chalk.green('dog and then ran away with the unicorn.');

console.log(wrapAnsi(input, 20));
```

<img width="331" src="screenshot.png">

## API

### wrapAnsi(string, columns, options?)

Wrap words to the specified column width.

#### string

Type: `string`

String with ANSI escape codes. Like one styled by [`chalk`](https://github.com/chalk/chalk). Newline characters will be normalized to `\n`.

#### columns

Type: `number`

Number of columns to wrap the text to.

#### options

Type: `object`

##### hard

Type: `boolean`\
Default: `false`

By default the wrap is soft, meaning long words may extend past the column width. Setting this to `true` will make it hard wrap at the column width.

##### wordWrap

Type: `boolean`\
Default: `true`

By default, an attempt is made to split words at spaces, ensuring that they don't extend past the configured columns. If wordWrap is `false`, each column will instead be completely filled splitting words as necessary.

##### trim

Type: `boolean`\
Default: `true`

Whitespace on all lines is removed by default. Set this option to `false` if you don't want to trim.

## Related

- [slice-ansi](https://github.com/chalk/slice-ansi) - Slice a string with ANSI escape codes
- [cli-truncate](https://github.com/sindresorhus/cli-truncate) - Truncate a string to a specific width in the terminal
- [chalk](https://github.com/chalk/chalk) - Terminal string styling done right
- [jsesc](https://github.com/mathiasbynens/jsesc) - Generate ASCII-only output from Unicode strings. Useful for creating test fixtures.

## Maintainers

- [Sindre Sorhus](https://github.com/sindresorhus)
- [Josh Junon](https://github.com/qix-)
- [Benjamin Coe](https://github.com/bcoe)

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-wrap_ansi?utm_source=npm-wrap-ansi&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

# wrappy

Callback wrapping utility

## USAGE

```javascript
var wrappy = require("wrappy")

// var wrapper = wrappy(wrapperFunction)

// make sure a cb is called only once
// See also: http://npm.im/once for this specific use case
var once = wrappy(function (cb) {
  var called = false
  return function () {
    if (called) return
    called = true
    return cb.apply(this, arguments)
  }
})

function printBoo () {
  console.log('boo')
}
// has some rando property
printBoo.iAmBooPrinter = true

var onlyPrintOnce = once(printBoo)

onlyPrintOnce() // prints 'boo'
onlyPrintOnce() // does nothing

// random property is retained!
assert.equal(onlyPrintOnce.iAmBooPrinter, true)
```


---

# 3.0.0

* Implement options.tmpfileCreated callback.
* Drop Node.js 6, modernize code, return Promise from async function.
* Support write TypedArray's like in node fs.writeFile.
* Remove graceful-fs dependency.

# 2.4.3

* Ignore errors raised by `fs.closeSync` when cleaning up after a write
  error.

# 2.4.2

* A pair of patches to fix some fd leaks.  We would leak fds with sync use
  when errors occured and with async use any time fsync was not in use. (#34)

# 2.4.1

* Fix a bug where `signal-exit` instances would be leaked. This was fixed when addressing #35.

# 2.4.0

## Features

* Allow chown and mode options to be set to false to disable the defaulting behavior. (#20)
* Support passing encoding strings in options slot for compat with Node.js API. (#31)
* Add support for running inside of worker threads (#37)

## Fixes

* Remove unneeded call when returning success (#36)


---

write-file-atomic
-----------------

This is an extension for node's `fs.writeFile` that makes its operation
atomic and allows you set ownership (uid/gid of the file).

### var writeFileAtomic = require('write-file-atomic')<br>writeFileAtomic(filename, data, [options], [callback])

* filename **String**
* data **String** | **Buffer**
* options **Object** | **String**
  * chown **Object** default, uid & gid of existing file, if any
    * uid **Number**
    * gid **Number**
  * encoding **String** | **Null** default = 'utf8'
  * fsync **Boolean** default = true
  * mode **Number** default, from existing file, if any
  * tmpfileCreated **Function** called when the tmpfile is created
* callback **Function**

Atomically and asynchronously writes data to a file, replacing the file if it already
exists.  data can be a string or a buffer.

The file is initially named `filename + "." + murmurhex(__filename, process.pid, ++invocations)`.
Note that `require('worker_threads').threadId` is used in addition to `process.pid` if running inside of a worker thread.
If writeFile completes successfully then, if passed the **chown** option it will change
the ownership of the file. Finally it renames the file back to the filename you specified. If
it encounters errors at any of these steps it will attempt to unlink the temporary file and then
pass the error back to the caller.
If multiple writes are concurrently issued to the same file, the write operations are put into a queue and serialized in the order they were called, using Promises. Writes to different files are still executed in parallel.

If provided, the **chown** option requires both **uid** and **gid** properties or else
you'll get an error.  If **chown** is not specified it will default to using
the owner of the previous file.  To prevent chown from being ran you can
also pass `false`, in which case the file will be created with the current user's credentials.

If **mode** is not specified, it will default to using the permissions from
an existing file, if any.  Expicitly setting this to `false` remove this default, resulting
in a file created with the system default permissions.

If options is a String, it's assumed to be the **encoding** option. The **encoding** option is ignored if **data** is a buffer. It defaults to 'utf8'.

If the **fsync** option is **false**, writeFile will skip the final fsync call.

If the **tmpfileCreated** option is specified it will be called with the name of the tmpfile when created.

Example:

```javascript
writeFileAtomic('message.txt', 'Hello Node', {chown:{uid:100,gid:50}}, function (err) {
  if (err) throw err;
  console.log('It\'s saved!');
});
```

This function also supports async/await:

```javascript
(async () => {
  try {
    await writeFileAtomic('message.txt', 'Hello Node', {chown:{uid:100,gid:50}});
    console.log('It\'s saved!');
  } catch (err) {
    console.error(err);
    process.exit(1);
  }
})();
```

### var writeFileAtomicSync = require('write-file-atomic').sync<br>writeFileAtomicSync(filename, data, [options])

The synchronous version of **writeFileAtomic**.


---

# ws: a Node.js WebSocket library

[![Version npm](https://img.shields.io/npm/v/ws.svg?logo=npm)](https://www.npmjs.com/package/ws)
[![CI](https://img.shields.io/github/workflow/status/websockets/ws/CI/master?label=CI&logo=github)](https://github.com/websockets/ws/actions?query=workflow%3ACI+branch%3Amaster)
[![Coverage Status](https://img.shields.io/coveralls/websockets/ws/master.svg?logo=coveralls)](https://coveralls.io/github/websockets/ws)

ws is a simple to use, blazing fast, and thoroughly tested WebSocket client and
server implementation.

Passes the quite extensive Autobahn test suite: [server][server-report],
[client][client-report].

**Note**: This module does not work in the browser. The client in the docs is a
reference to a back end with the role of a client in the WebSocket
communication. Browser clients must use the native
[`WebSocket`](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)
object. To make the same code work seamlessly on Node.js and the browser, you
can use one of the many wrappers available on npm, like
[isomorphic-ws](https://github.com/heineiuo/isomorphic-ws).

## Table of Contents

- [Protocol support](#protocol-support)
- [Installing](#installing)
  - [Opt-in for performance](#opt-in-for-performance)
- [API docs](#api-docs)
- [WebSocket compression](#websocket-compression)
- [Usage examples](#usage-examples)
  - [Sending and receiving text data](#sending-and-receiving-text-data)
  - [Sending binary data](#sending-binary-data)
  - [Simple server](#simple-server)
  - [External HTTP/S server](#external-https-server)
  - [Multiple servers sharing a single HTTP/S server](#multiple-servers-sharing-a-single-https-server)
  - [Client authentication](#client-authentication)
  - [Server broadcast](#server-broadcast)
  - [echo.websocket.org demo](#echowebsocketorg-demo)
  - [Use the Node.js streams API](#use-the-nodejs-streams-api)
  - [Other examples](#other-examples)
- [FAQ](#faq)
  - [How to get the IP address of the client?](#how-to-get-the-ip-address-of-the-client)
  - [How to detect and close broken connections?](#how-to-detect-and-close-broken-connections)
  - [How to connect via a proxy?](#how-to-connect-via-a-proxy)
- [Changelog](#changelog)
- [License](#license)

## Protocol support

- **HyBi drafts 07-12** (Use the option `protocolVersion: 8`)
- **HyBi drafts 13-17** (Current default, alternatively option
  `protocolVersion: 13`)

## Installing

```
npm install ws
```

### Opt-in for performance

There are 2 optional modules that can be installed along side with the ws
module. These modules are binary addons which improve certain operations.
Prebuilt binaries are available for the most popular platforms so you don't
necessarily need to have a C++ compiler installed on your machine.

- `npm install --save-optional bufferutil`: Allows to efficiently perform
  operations such as masking and unmasking the data payload of the WebSocket
  frames.
- `npm install --save-optional utf-8-validate`: Allows to efficiently check if a
  message contains valid UTF-8.

## API docs

See [`/doc/ws.md`](./doc/ws.md) for Node.js-like documentation of ws classes and
utility functions.

## WebSocket compression

ws supports the [permessage-deflate extension][permessage-deflate] which enables
the client and server to negotiate a compression algorithm and its parameters,
and then selectively apply it to the data payloads of each WebSocket message.

The extension is disabled by default on the server and enabled by default on the
client. It adds a significant overhead in terms of performance and memory
consumption so we suggest to enable it only if it is really needed.

Note that Node.js has a variety of issues with high-performance compression,
where increased concurrency, especially on Linux, can lead to [catastrophic
memory fragmentation][node-zlib-bug] and slow performance. If you intend to use
permessage-deflate in production, it is worthwhile to set up a test
representative of your workload and ensure Node.js/zlib will handle it with
acceptable performance and memory usage.

Tuning of permessage-deflate can be done via the options defined below. You can
also use `zlibDeflateOptions` and `zlibInflateOptions`, which is passed directly
into the creation of [raw deflate/inflate streams][node-zlib-deflaterawdocs].

See [the docs][ws-server-options] for more options.

```js
const WebSocket = require('ws');

const wss = new WebSocket.Server({
  port: 8080,
  perMessageDeflate: {
    zlibDeflateOptions: {
      // See zlib defaults.
      chunkSize: 1024,
      memLevel: 7,
      level: 3
    },
    zlibInflateOptions: {
      chunkSize: 10 * 1024
    },
    // Other options settable:
    clientNoContextTakeover: true, // Defaults to negotiated value.
    serverNoContextTakeover: true, // Defaults to negotiated value.
    serverMaxWindowBits: 10, // Defaults to negotiated value.
    // Below options specified as default values.
    concurrencyLimit: 10, // Limits zlib concurrency for perf.
    threshold: 1024 // Size (in bytes) below which messages
    // should not be compressed.
  }
});
```

The client will only use the extension if it is supported and enabled on the
server. To always disable the extension on the client set the
`perMessageDeflate` option to `false`.

```js
const WebSocket = require('ws');

const ws = new WebSocket('ws://www.host.com/path', {
  perMessageDeflate: false
});
```

## Usage examples

### Sending and receiving text data

```js
const WebSocket = require('ws');

const ws = new WebSocket('ws://www.host.com/path');

ws.on('open', function open() {
  ws.send('something');
});

ws.on('message', function incoming(data) {
  console.log(data);
});
```

### Sending binary data

```js
const WebSocket = require('ws');

const ws = new WebSocket('ws://www.host.com/path');

ws.on('open', function open() {
  const array = new Float32Array(5);

  for (var i = 0; i < array.length; ++i) {
    array[i] = i / 2;
  }

  ws.send(array);
});
```

### Simple server

```js
const WebSocket = require('ws');

const wss = new WebSocket.Server({ port: 8080 });

wss.on('connection', function connection(ws) {
  ws.on('message', function incoming(message) {
    console.log('received: %s', message);
  });

  ws.send('something');
});
```

### External HTTP/S server

```js
const fs = require('fs');
const https = require('https');
const WebSocket = require('ws');

const server = https.createServer({
  cert: fs.readFileSync('/path/to/cert.pem'),
  key: fs.readFileSync('/path/to/key.pem')
});
const wss = new WebSocket.Server({ server });

wss.on('connection', function connection(ws) {
  ws.on('message', function incoming(message) {
    console.log('received: %s', message);
  });

  ws.send('something');
});

server.listen(8080);
```

### Multiple servers sharing a single HTTP/S server

```js
const http = require('http');
const WebSocket = require('ws');
const url = require('url');

const server = http.createServer();
const wss1 = new WebSocket.Server({ noServer: true });
const wss2 = new WebSocket.Server({ noServer: true });

wss1.on('connection', function connection(ws) {
  // ...
});

wss2.on('connection', function connection(ws) {
  // ...
});

server.on('upgrade', function upgrade(request, socket, head) {
  const pathname = url.parse(request.url).pathname;

  if (pathname === '/foo') {
    wss1.handleUpgrade(request, socket, head, function done(ws) {
      wss1.emit('connection', ws, request);
    });
  } else if (pathname === '/bar') {
    wss2.handleUpgrade(request, socket, head, function done(ws) {
      wss2.emit('connection', ws, request);
    });
  } else {
    socket.destroy();
  }
});

server.listen(8080);
```

### Client authentication

```js
const http = require('http');
const WebSocket = require('ws');

const server = http.createServer();
const wss = new WebSocket.Server({ noServer: true });

wss.on('connection', function connection(ws, request, client) {
  ws.on('message', function message(msg) {
    console.log(`Received message ${msg} from user ${client}`);
  });
});

server.on('upgrade', function upgrade(request, socket, head) {
  // This function is not defined on purpose. Implement it with your own logic.
  authenticate(request, (err, client) => {
    if (err || !client) {
      socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
      socket.destroy();
      return;
    }

    wss.handleUpgrade(request, socket, head, function done(ws) {
      wss.emit('connection', ws, request, client);
    });
  });
});

server.listen(8080);
```

Also see the provided [example][session-parse-example] using `express-session`.

### Server broadcast

A client WebSocket broadcasting to all connected WebSocket clients, including
itself.

```js
const WebSocket = require('ws');

const wss = new WebSocket.Server({ port: 8080 });

wss.on('connection', function connection(ws) {
  ws.on('message', function incoming(data) {
    wss.clients.forEach(function each(client) {
      if (client.readyState === WebSocket.OPEN) {
        client.send(data);
      }
    });
  });
});
```

A client WebSocket broadcasting to every other connected WebSocket clients,
excluding itself.

```js
const WebSocket = require('ws');

const wss = new WebSocket.Server({ port: 8080 });

wss.on('connection', function connection(ws) {
  ws.on('message', function incoming(data) {
    wss.clients.forEach(function each(client) {
      if (client !== ws && client.readyState === WebSocket.OPEN) {
        client.send(data);
      }
    });
  });
});
```

### echo.websocket.org demo

```js
const WebSocket = require('ws');

const ws = new WebSocket('wss://echo.websocket.org/', {
  origin: 'https://websocket.org'
});

ws.on('open', function open() {
  console.log('connected');
  ws.send(Date.now());
});

ws.on('close', function close() {
  console.log('disconnected');
});

ws.on('message', function incoming(data) {
  console.log(`Roundtrip time: ${Date.now() - data} ms`);

  setTimeout(function timeout() {
    ws.send(Date.now());
  }, 500);
});
```

### Use the Node.js streams API

```js
const WebSocket = require('ws');

const ws = new WebSocket('wss://echo.websocket.org/', {
  origin: 'https://websocket.org'
});

const duplex = WebSocket.createWebSocketStream(ws, { encoding: 'utf8' });

duplex.pipe(process.stdout);
process.stdin.pipe(duplex);
```

### Other examples

For a full example with a browser client communicating with a ws server, see the
examples folder.

Otherwise, see the test cases.

## FAQ

### How to get the IP address of the client?

The remote IP address can be obtained from the raw socket.

```js
const WebSocket = require('ws');

const wss = new WebSocket.Server({ port: 8080 });

wss.on('connection', function connection(ws, req) {
  const ip = req.socket.remoteAddress;
});
```

When the server runs behind a proxy like NGINX, the de-facto standard is to use
the `X-Forwarded-For` header.

```js
wss.on('connection', function connection(ws, req) {
  const ip = req.headers['x-forwarded-for'].split(',')[0].trim();
});
```

### How to detect and close broken connections?

Sometimes the link between the server and the client can be interrupted in a way
that keeps both the server and the client unaware of the broken state of the
connection (e.g. when pulling the cord).

In these cases ping messages can be used as a means to verify that the remote
endpoint is still responsive.

```js
const WebSocket = require('ws');

function noop() {}

function heartbeat() {
  this.isAlive = true;
}

const wss = new WebSocket.Server({ port: 8080 });

wss.on('connection', function connection(ws) {
  ws.isAlive = true;
  ws.on('pong', heartbeat);
});

const interval = setInterval(function ping() {
  wss.clients.forEach(function each(ws) {
    if (ws.isAlive === false) return ws.terminate();

    ws.isAlive = false;
    ws.ping(noop);
  });
}, 30000);

wss.on('close', function close() {
  clearInterval(interval);
});
```

Pong messages are automatically sent in response to ping messages as required by
the spec.

Just like the server example above your clients might as well lose connection
without knowing it. You might want to add a ping listener on your clients to
prevent that. A simple implementation would be:

```js
const WebSocket = require('ws');

function heartbeat() {
  clearTimeout(this.pingTimeout);

  // Use `WebSocket#terminate()`, which immediately destroys the connection,
  // instead of `WebSocket#close()`, which waits for the close timer.
  // Delay should be equal to the interval at which your server
  // sends out pings plus a conservative assumption of the latency.
  this.pingTimeout = setTimeout(() => {
    this.terminate();
  }, 30000 + 1000);
}

const client = new WebSocket('wss://echo.websocket.org/');

client.on('open', heartbeat);
client.on('ping', heartbeat);
client.on('close', function clear() {
  clearTimeout(this.pingTimeout);
});
```

### How to connect via a proxy?

Use a custom `http.Agent` implementation like [https-proxy-agent][] or
[socks-proxy-agent][].

## Changelog

We're using the GitHub [releases][changelog] for changelog entries.

## License

[MIT](LICENSE)

[changelog]: https://github.com/websockets/ws/releases
[client-report]: http://websockets.github.io/ws/autobahn/clients/
[https-proxy-agent]: https://github.com/TooTallNate/node-https-proxy-agent
[node-zlib-bug]: https://github.com/nodejs/node/issues/8871
[node-zlib-deflaterawdocs]:
  https://nodejs.org/api/zlib.html#zlib_zlib_createdeflateraw_options
[permessage-deflate]: https://tools.ietf.org/html/rfc7692
[server-report]: http://websockets.github.io/ws/autobahn/servers/
[session-parse-example]: ./examples/express-session-parse
[socks-proxy-agent]: https://github.com/TooTallNate/node-socks-proxy-agent
[ws-server-options]:
  https://github.com/websockets/ws/blob/master/doc/ws.md#new-websocketserveroptions-callback


---

# xdg-basedir

> Get [XDG Base Directory](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) paths

This package is meant for Linux. You should not use XDG on macOS or Windows. Instead, you should follow their platform conventions. You can use [`env-paths`](https://github.com/sindresorhus/env-paths) for that.

## Install

```
$ npm install xdg-basedir
```

## Usage

```js
import {xdgData, xdgConfig, xdgDataDirectories} from 'xdg-basedir';

console.log(xdgData);
//=> '/home/sindresorhus/.local/share'

console.log(xdgConfig);
//=> '/home/sindresorhus/.config'

console.log(xdgDataDirectories);
//=> ['/home/sindresorhus/.local/share', '/usr/local/share/', '/usr/share/']
```

## API

The exports `xdgData`, `xdgConfig`, `xdgCache`, `xdgRuntime` will return `undefined` in the uncommon case that both the XDG environment variable is not set and the users home directory can't be found. You need to handle this case. A common solution is to [fall back to a temporary directory](https://github.com/yeoman/configstore/blob/b82690fc401318ad18dcd7d151a0003a4898a314/index.js#L15).

### xdgData

Directory for user-specific data files.

### xdgConfig

Directory for user-specific configuration files.

### xdgState

Directory for user-specific state files.

### xdgCache

Directory for user-specific non-essential data files.

### xdgRuntime

Directory for user-specific non-essential runtime files and other file objects (such as sockets, named pipes, etc).

### xdgDataDirectories

Preference-ordered array of base directories to search for data files in addition to `xdgData`.

### xdgConfigDirectories

Preference-ordered array of base directories to search for configuration files in addition to `xdgConfig`.

---

<div align="center">
	<b>
		<a href="https://tidelift.com/subscription/pkg/npm-xdg-basedir?utm_source=npm-xdg-basedir&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
	</b>
	<br>
	<sub>
		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
	</sub>
</div>


---

![XML ⇔ JS/JSON](http://nashwaan.github.io/xml-js/images/logo.svg)

Convert XML text to Javascript object / JSON text (and vice versa).

[![Build Status](https://ci.appveyor.com/api/projects/status/0ky9f115m0f0r0gf?svg=true)](https://ci.appveyor.com/project/nashwaan/xml-js)
[![Build Status](https://travis-ci.org/nashwaan/xml-js.svg?branch=master)](https://travis-ci.org/nashwaan/xml-js)
[![Build Status](https://img.shields.io/circleci/project/nashwaan/xml-js.svg)](https://circleci.com/gh/nashwaan/xml-js)
<!-- [![pipeline status](https://gitlab.com/nashwaan/xml-js/badges/master/pipeline.svg)](https://gitlab.com/nashwaan/xml-js/commits/master) -->

[![Coverage Status](https://coveralls.io/repos/github/nashwaan/xml-js/badge.svg?branch=master)](https://coveralls.io/github/nashwaan/xml-js?branch=master)
[![codecov](https://codecov.io/gh/nashwaan/xml-js/branch/master/graph/badge.svg)](https://codecov.io/gh/nashwaan/xml-js)
[![Codacy Badge](https://api.codacy.com/project/badge/Grade/f6ed5dd79a5b4041bfd2732963c4d09b)](https://www.codacy.com/app/ysf953/xml-js?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=nashwaan/xml-js&amp;utm_campaign=Badge_Grade)
[![Code Climate](https://codeclimate.com/github/nashwaan/xml-js/badges/gpa.svg)](https://codeclimate.com/github/nashwaan/xml-js)

[![npm](http://img.shields.io/npm/v/xml-js.svg)](https://www.npmjs.com/package/xml-js)
[![License](https://img.shields.io/npm/l/xml-js.svg)](LICENSE)
[![Downloads/month](https://img.shields.io/npm/dm/xml-js.svg)](http://www.npmtrends.com/xml-js)
[![Dependency Status](https://david-dm.org/nashwaan/xml-js.svg)](https://david-dm.org/nashwaan/xml-js)
[![Package Quality](http://npm.packagequality.com/shield/xml-js.svg)](http://packagequality.com/#?package=xml-js)

# Synopsis

![Convert XML ↔ JS/JSON as compact or non-compact](http://nashwaan.github.io/xml-js/images/synopsis.svg)
<!---![Convert XML ↔ JS/JSON as compact or non-compact](/synopsis.png?raw=true "Synopsis Diagram")-->

# Features

* **Maintain Order of Elements**:
Most libraries will convert `<a/><b/><a/>` to `{a:[{},{}],b:{}}` which merges any node of same name into an array. This library can create the following to preserve the order of elements:
`{"elements":[{"type":"element","name":"a"},{"type":"element","name":"b"},{"type":"element","name":"a"}]}`.

This is very important and it is the main reason why this library was created. Read also [Compact vs Non-Compact](#compact-vs-non-compact) for more info.

* **Fully XML Compliant**:
Can parse: elements, attributes, texts, comments, CData, DOCTYPE, XML declarations, and Processing Instructions.

* **Reversible**:
Whether converting xml→json or json→xml, the result can be converted back to its original form.

* **Minimal Dependencies**:
This library depends only on one external npm module.

* **Change Property Key Name**:
Usually output of XML attributes are stored in `@attr`, `_atrr`, `$attr` or `$` in order to avoid conflicting with name of sub-elements.
This library store them in `attributes`, but most importantly, you can change this to whatever you like.

* **Support Upwards Traversal**:
By setting `{addParent: true}` option, an extra property named `parent` will be generated along each element so that its parent can be referenced.
Therefore, anywhere during the traversal of an element, its children **and** its parent can be easily accessed.

* **Support Command Line**:
To quickly convert xml or json files, this module can be installed globally or locally (i.e. use it as [script](https://docs.npmjs.com/misc/scripts) in package.json).

* **Customize Processing using Callback Hooks**:
[Custom functions](#options-for-custom-processing-functions) can be supplied to do additional processing for different parts of xml or json (like cdata, comments, elements, attributes ...etc).

* **Portable Code**:
Written purely in JavaScript which means it can be used in Node environment and **browser** environment (via bundlers like browserify/JSPM/Webpack).

* **Typings Info Included**:
Support type checking and code suggestion via intellisense.
Thanks to the wonderful efforts by [DenisCarriere](https://github.com/DenisCarriere).

## Compact vs Non-Compact

Most XML to JSON converters (including online converters) convert `<a/>` to some compact output like `{"a":{}}`
instead of non-compact output like `{"elements":[{"type":"element","name":"a"}]}`.

While compact output might work in most situations, there are cases when elements of different names are mixed inside a parent element. Lets use `<a x="1"/><b x="2"/><a x="3"/>` as an example.
Most converters will produce compact output like this `{a:[{_:{x:"1"}},{_:{x:"3"}}], b:{_:{x:"2"}}}`,
which has merged both `<a>` elements into an array. If you try to convert this back to xml, you will get `<a x="1"/><a x="3"/><b x="2"/>`
which has not preserved the order of elements!

The reason behind this behavior is due to the inherent limitation in the compact representation. 
Because output like `{a:{_:{x:"1"}}, b:{_:{x:"2"}}, a:{_:{x:"3"}}}` is illegal (same property name `a` should not appear twice in an object). This leaves no option but to use array `{a:[{_:{x:"1"}},{_:{x:"3"}}]`.

The non-compact output, which is supported by this library, will produce more information and always guarantees the order of the elements as they appeared in the XML file.

Another drawback of compact output is the resultant element can be an object or an array and therefore makes the client code a little awkward in terms of the extra check needed on object type before processing.

NOTE: Although non-compact output is more accurate representation of original XML than compact version, the non-compact version is verbose and consumes more space.
This library provides both options. Use `{compact: false}` if you are not sure because it preserves everything;
otherwise use `{compact: true}` if you want to save space and you don't care about mixing elements of same name and losing their order.

Tip: You can reduce the output size by using shorter [key names](#options-for-changing-key-names).

# Usage

## Installation

```
npm install --save xml-js
```

You can also install it globally to use it as a command line convertor (see [Command Line](#command-line)).

```
npm install --global xml-js
```

## Quick start

```js
var convert = require('xml-js');
var xml =
'<?xml version="1.0" encoding="utf-8"?>' +
'<note importance="high" logged="true">' +
'    <title>Happy</title>' +
'    <todo>Work</todo>' +
'    <todo>Play</todo>' +
'</note>';
var result1 = convert.xml2json(xml, {compact: true, spaces: 4});
var result2 = convert.xml2json(xml, {compact: false, spaces: 4});
console.log(result1, '\n', result2);
```

To see the result of this code, see the output above in [Synopsis](#synopsis) section.

Or [run and edit](https://runkit.com/587874e079a2f60013c1f5ac/587874e079a2f60013c1f5ad) this code live in the browser.

## Sample Conversions

| XML | JS/JSON compact | JS/JSON non-compact |
|:----|:----------------|:--------------------|
| `<a/>` | `{"a":{}}` | `{"elements":[{"type":"element","name":"a"}]}` |
| `<a/><b/>` | `{"a":{},"b":{}}` | `{"elements":[{"type":"element","name":"a"},{"type":"element","name":"b"}]}` |
| `<a><b/></a>` | `{"a":{"b":{}}}` | `{"elements":[{"type":"element","name":"a","elements":[{"type":"element","name":"b"}]}]}` |
| `<a> Hi </a>` | `{"a":{"_text":" Hi "}}` | `{"elements":[{"type":"element","name":"a","elements":[{"type":"text","text":" Hi "}]}]}` |
| `<a x="1.234" y="It's"/>` | `{"a":{"_attributes":{"x":"1.234","y":"It's"}}}` | `{"elements":[{"type":"element","name":"a","attributes":{"x":"1.234","y":"It's"}}]}` |
| `<?xml?>` | `{"_declaration":{}}` | `{"declaration":{}}` |
| `<?go there?>` | `{"_instruction":{"go":"there"}}` | `{"elements":[{"type":"instruction","name":"go","instruction":"there"}]}` |
| `<?xml version="1.0" encoding="utf-8"?>` | `{"_declaration":{"_attributes":{"version":"1.0","encoding":"utf-8"}}}` | `{"declaration":{"attributes":{"version":"1.0","encoding":"utf-8"}}}` |
| `<!--Hello, World!-->` | `{"_comment":"Hello, World!"}` | `{"elements":[{"type":"comment","comment":"Hello, World!"}]}` |
| `<![CDATA[<foo></bar>]]>` | `{"_cdata":"<foo></bar>"}` | `{"elements":[{"type":"cdata","cdata":"<foo></bar>"}]}` |

# API Reference

This library provides 4 functions: `js2xml()`, `json2xml()`, `xml2js()`, and `xml2json()`. Here are the usages for each one (see more details in the following sections):
```js
var convert = require('xml-js');
result = convert.js2xml(js, options);     // to convert javascript object to xml text
result = convert.json2xml(json, options); // to convert json text to xml text
result = convert.xml2js(xml, options);    // to convert xml text to javascript object
result = convert.xml2json(xml, options);  // to convert xml text to json text
```

## Convert JS object / JSON → XML

To convert JavaScript object to XML text, use `js2xml()`. To convert JSON text to XML text, use `json2xml()`.

```js
var convert = require('xml-js');
var json = require('fs').readFileSync('test.json', 'utf8');
var options = {compact: true, ignoreComment: true, spaces: 4};
var result = convert.json2xml(json, options);
console.log(result);
```

### Options for Converting JS object / JSON → XML

The below options are applicable for both `js2xml()` and `json2xml()` functions.


| Option                | Default | Description |
|:----------------------|:--------|:------------|
| `spaces`              | `0`     | Number of spaces to be used for indenting XML output. Passing characters like `' '` or `'\t'` are also accepted. |
| `compact`             | `false` | Whether the *input* object is in compact form or not. By default, input is expected to be in non-compact form. |
|                       |         | IMPORTANT: Remeber to set this option `compact: true` if you are supplying normal json (which is likely equivalent to compact form). Otherwise, the function assumes your json input is non-compact form and you will not get a result if it is not in that form. See [Synopsis](#synopsis) to know the difference between the two json forms |
| `fullTagEmptyElement` | `false` | Whether to produce element without sub-elements as full tag pairs `<a></a>` rather than self closing tag `<a/>`. |
| `indentCdata`         | `false` | Whether to write CData in a new line and indent it. Will generate `<a>\n <![CDATA[foo]]></a>` instead of `<a><![CDATA[foo]]></a>`. See [discussion](https://github.com/nashwaan/xml-js/issues/14) |
| `indentAttributes`    | `false` | Whether to print attributes across multiple lines and indent them (when `spaces` is not `0`). See [example](https://github.com/nashwaan/xml-js/issues/31). |
| `ignoreDeclaration`   | `false` | Whether to ignore writing declaration directives of xml. For example, `<?xml?>` will be ignored. |
| `ignoreInstruction`   | `false` | Whether to ignore writing processing instruction of xml. For example, `<?go there?>` will be ignored. |
| `ignoreAttributes`    | `false` | Whether to ignore writing attributes of the elements. For example, `x="1"` in `<a x="1"></a>` will be ignored |
| `ignoreComment`       | `false` | Whether to ignore writing comments of the elements. That is, no `<!--  -->` will be generated. |
| `ignoreCdata`         | `false` | Whether to ignore writing CData of the elements. That is, no `<![CDATA[ ]]>` will be generated. |
| `ignoreDoctype`       | `false` | Whether to ignore writing Doctype of the elements. That is, no `<!DOCTYPE >` will be generated. |
| `ignoreText`          | `false` | Whether to ignore writing texts of the elements. For example, `hi` text in `<a>hi</a>` will be ignored. |

## Convert XML → JS object / JSON

To convert XML text to JavaScript object, use `xml2js()`. To convert XML text to JSON text, use `xml2json()`.

```js
var convert = require('xml-js');
var xml = require('fs').readFileSync('test.xml', 'utf8');
var options = {ignoreComment: true, alwaysChildren: true};
var result = convert.xml2js(xml, options); // or convert.xml2json(xml, options)
console.log(result);
```

### Options for Converting XML → JS object / JSON

The below options are applicable for both `xml2js()` and `xml2json()` functions.

| Option              | Default | Description |
|:--------------------|:--------|:------------|
| `compact`           | `false` | Whether to produce detailed object or compact object. |
| `trim`              | `false` | Whether to trim whitespace characters that may exist before and after the text. |
| `sanitize` ([Deprecated](https://github.com/nashwaan/xml-js/issues/26)) | `false` | Whether to replace `&` `<` `>` with `&amp;` `&lt;` `&gt;` respectively, in the resultant text. |
| `nativeType`        | `false` | Whether to attempt converting text of numerals or of boolean values to native type. For example, `"123"` will be `123` and `"true"` will be `true` |
| `nativeTypeAttributes` | `false` | Whether to attempt converting attributes of numerals or of boolean values to native type. See also `nativeType` above. |
| `addParent`         | `false` | Whether to add `parent` property in each element object that points to parent object. |
| `alwaysArray`       | `false` | Whether to always put sub element, even if it is one only, as an item inside an array. `<a><b/></a>` will be `a:[{b:[{}]}]` rather than `a:{b:{}}` (applicable for compact output only). If the passed value is an array, only elements with names in the passed array are always made arrays. |
| `alwaysChildren`    | `false` | Whether to always generate `elements` property even when there are no actual sub elements. `<a></a>` will be `{"elements":[{"type":"element","name":"a","elements":[]}]}` rather than `{"elements":[{"type":"element","name":"a"}]}` (applicable for non-compact output). |
| `instructionHasAttributes` | `false` | Whether to parse contents of Processing Instruction as attributes or not. `<?go to="there"?>` will be `{"_instruction":{"go":{"_attributes":{"to":"there"}}}}` rather than `{"_instruction":{"go":"to=\"there\""}}`. See [discussion](https://github.com/nashwaan/xml-js/issues/17). |
| `ignoreDeclaration` | `false` | Whether to ignore parsing declaration property. That is, no `declaration` property will be generated. |
| `ignoreInstruction` | `false` | Whether to ignore parsing processing instruction property. That is, no `instruction` property will be generated. |
| `ignoreAttributes`  | `false` | Whether to ignore parsing attributes of elements.That is, no `attributes` property will be generated. |
| `ignoreComment`     | `false` | Whether to ignore parsing comments of the elements. That is, no `comment` will be generated. |
| `ignoreCdata`       | `false` | Whether to ignore parsing CData of the elements. That is, no `cdata` will be generated. |
| `ignoreDoctype`     | `false` | Whether to ignore parsing Doctype of the elements. That is, no `doctype` will be generated. |
| `ignoreText`        | `false` | Whether to ignore parsing texts of the elements. That is, no `text` will be generated. |

The below option is applicable only for `xml2json()` function.

| Option              | Default | Description |
|:--------------------|:--------|:------------|
| `spaces`            | `0`     | Number of spaces to be used for indenting JSON output. Passing characters like `' '` or `'\t'` are also accepted. |

## Options for Changing Key Names

To change default key names in the output object or the default key names assumed in the input JavaScript object / JSON, use the following options:

| Option              | Default | Description |
|:--------------------|:--------|:------------|
| `declarationKey`    | `"declaration"` or `"_declaration"` | Name of the property key which will be used for the declaration. For example, if `declarationKey: '$declaration'` then output of `<?xml?>` will be `{"$declaration":{}}` *(in compact form)* |
| `instructionKey`    | `"instruction"` or `"_instruction"` | Name of the property key which will be used for the processing instruction. For example, if `instructionKey: '$instruction'` then output of `<?go there?>` will be `{"$instruction":{"go":"there"}}` *(in compact form)* |
| `attributesKey`     | `"attributes"` or `"_attributes"` | Name of the property key which will be used for the attributes. For example, if `attributesKey: '$attributes'` then output of `<a x="hello"/>` will be `{"a":{$attributes:{"x":"hello"}}}` *(in compact form)* |
| `textKey`           | `"text"` or `"_text"` | Name of the property key which will be used for the text. For example, if `textKey: '$text'` then output of `<a>hi</a>` will be `{"a":{"$text":"Hi"}}` *(in compact form)* |
| `cdataKey`          | `"cdata"` or `"_cdata"` | Name of the property key which will be used for the cdata. For example, if `cdataKey: '$cdata'` then output of `<![CDATA[1 is < 2]]>` will be `{"$cdata":"1 is < 2"}` *(in compact form)* |
| `doctypeKey`        | `"doctype"` or `"_doctype"` | Name of the property key which will be used for the doctype. For example, if `doctypeKey: '$doctype'` then output of `<!DOCTYPE foo>` will be `{"$doctype":" foo}` *(in compact form)* |
| `commentKey`        | `"comment"` or `"_comment"` | Name of the property key which will be used for the comment. For example, if `commentKey: '$comment'` then output of `<!--note-->` will be `{"$comment":"note"}` *(in compact form)* |
| `parentKey`         | `"parent"` or `"_parent"` | Name of the property key which will be used for the parent. For example, if `parentKey: '$parent'` then output of `<a></b></a>` will be `{"a":{"b":{$parent:_points_to_a}}}` *(in compact form)* |
| `typeKey`           | `"type"` | Name of the property key which will be used for the type. For example, if `typeKey: '$type'` then output of `<a></a>` will be `{"elements":[{"$type":"element","name":"a"}]}` *(in non-compact form)* |
| `nameKey`           | `"name"` | Name of the property key which will be used for the name. For example, if `nameKey: '$name'` then output of `<a></a>` will be `{"elements":[{"type":"element","$name":"a"}]}` *(in non-compact form)* |
| `elementsKey`       | `"elements"` | Name of the property key which will be used for the elements. For example, if `elementsKey: '$elements'` then output of `<a></a>` will be `{"$elements":[{"type":"element","name":"a"}]}` *(in non-compact form)* |

Two default values mean the first is used for *non-compact* output and the second is for *compact* output.

> **TIP**: In compact mode, you can further reduce output result by using fewer characters for key names `{textKey: '_', attributesKey: '$', commentKey: 'value'}`. This is also applicable to non-compact mode.

> **TIP**: In non-compact mode, you probably want to set `{textKey: 'value', cdataKey: 'value', commentKey: 'value'}` 
> to make it more consistent and easier for your client code to go through the contents of text, cdata, and comment.

## Options for Custom Processing Functions

For XML → JS object / JSON, following custom callback functions can be supplied:

```js
var convert = require('xml-js');
var xml = '<foo:Name>Ali</Name> <bar:Age>30</bar:Age>';
var options = {compact: true, elementNameFn: function(val) {return val.replace('foo:','').toUpperCase();}};
var result = convert.xml2json(xml, options);
console.log(result); // {"NAME":{"_text":"Ali"},"BAR:AGE":{"_text":"30"}}
```

| Option              | Signature | Description |
|:--------------------|:----------|:------------|
| `doctypeFn` | `(value, parentElement)` | To perform additional processing for DOCTYPE. For example, `{doctypeFn: function(val) {return val.toUpperCase();}}` |
| `instructionFn` | `(instructionValue, instructionName, parentElement)` | To perform additional processing for content of Processing Instruction value. For example, `{instructionFn: function(val) {return val.toUpperCase();}}`. Note: `instructionValue` will be an object if `instructionHasAttributes` is enabled. |
| `cdataFn` | `(value, parentElement)` | To perform additional processing for CData. For example, `{cdataFn: function(val) {return val.toUpperCase();}}`. |
| `commentFn` | `(value, parentElement)` | To perform additional processing for comments. For example, `{commentFn: function(val) {return val.toUpperCase();}}`. |
| `textFn` | `(value, parentElement)` | To perform additional processing for texts inside elements. For example, `{textFn: function(val) {return val.toUpperCase();}}`. |
| `instructionNameFn` | `(instructionName, instructionValue, parentElement)` | To perform additional processing for Processing Instruction name. For example, `{instructionNameFn: function(val) {return val.toUpperCase();}}`. Note: `instructionValue` will be an object if `instructionHasAttributes` is enabled. |
| `elementNameFn` | `(value, parentElement)` | To perform additional processing for element name. For example, `{elementNameFn: function(val) {return val.toUpperCase();}}`. |
| `attributeNameFn` | `(attributeName, attributeValue, parentElement)` | To perform additional processing for attribute name. For example, `{attributeNameFn: function(val) {return val.toUpperCase();}}`. |
| `attributeValueFn` | `(attributeValue, attributeName, parentElement)` | To perform additional processing for attributeValue. For example, `{attributeValueFn: function(val) {return val.toUpperCase();}}`. |
| `attributesFn` | `(value, parentElement)` | To perform additional processing for attributes object. For example, `{attributesFn: function(val) {return val.toUpperCase();}}`. |

For JS object / JSON → XML, following custom callback functions can be supplied:

```js
var convert = require('xml-js');
var json = '{"name":{"_text":"Ali"},"age":{"_text":"30"}}';
var options = {compact: true, textFn: function(val, elementName) {return elementName === 'age'? val + '';}};
var result = convert.json2xml(json, options);
console.log(result); // <foo:Name>Ali</Name> <bar:Age>30</bar:Age>
```

| Option              | Signature | Description |
|:--------------------|:----------|:------------|
| `doctypeFn` | `(value, currentElementName, currentElementObj)` | To perform additional processing for DOCTYPE. For example, `{doctypeFn: function(val) {return val.toUpperCase();}`. |
| `instructionFn` | `(instructionValue, instructionName, currentElementName, currentElementObj)` | To perform additional processing for content of Processing Instruction value. For example, `{instructionFn: function(val) {return val.toUpperCase();}}`. Note: `instructionValue` will be an object if `instructionHasAttributes` is enabled. |
| `cdataFn` | `(value, currentElementName, currentElementObj)` | To perform additional processing for CData. For example, `{cdataFn: function(val) {return val.toUpperCase();}}`. |
| `commentFn` | `(value, currentElementName, currentElementObj)` | To perform additional processing for comments. For example, `{commentFn: function(val) {return val.toUpperCase();}}`. |
| `textFn` | `(value, currentElementName, currentElementObj)` | To perform additional processing for texts inside elements. For example, `{textFn: function(val) {return val.toUpperCase();}}`. |
| `instructionNameFn` | `(instructionName, instructionValue, currentElementName, currentElementObj)` | To perform additional processing for Processing Instruction name. For example, `{instructionNameFn: function(val) {return val.toUpperCase();}}`. Note: `instructionValue` will be an object if `instructionHasAttributes` is enabled. |
| `elementNameFn` | `(value, currentElementName, currentElementObj)` | To perform additional processing for element name. For example, `{elementNameFn: function(val) {return val.toUpperCase();}}`. |
| `attributeNameFn` | `(attributeName, attributeValue, currentElementName, currentElementObj)` | To perform additional processing for attribute name. For example, `{attributeNameFn: function(val) {return val.toUpperCase();}}`. |
| `attributeValueFn` | `(attributeValue, attributeName, currentElementName, currentElementObj)` | To perform additional processing for attributeValue. For example, `{attributeValueFn: function(val) {return val.toUpperCase();}}`. |
| `attributesFn` | `(value, currentElementName, currentElementObj)` | To perform additional processing for attributes object. For example, `{attributesFn: function(val) {return val.toUpperCase();}}`. |
| `fullTagEmptyElementFn` | `(currentElementName, currentElementObj)` | Whether to generate full tag or just self closing tag for elements that has no sub elements. For example, `{fullTagEmptyElementFn: function(val) {return val === 'foo'}}`. |

# Command Line

Because any good library should support command line usage, this library is no different.

## As Globally Accessible Command

```
npm install -g xml-js                       // install this library globally
xml-js test.json --spaces 4                 // xml result will be printed on screen
xml-js test.json --spaces 4 --out test.xml  // xml result will be saved to test.xml
xml-js test.xml --spaces 4                  // json result will be printed on screen
xml-js test.xml --spaces 4 --out test.json  // json result will be saved to test.json
```

## As Locally Accessible Command

If you want to use it as script in package.json (can also be helpful in [task automation via npm scripts](http://blog.keithcirkel.co.uk/how-to-use-npm-as-a-build-tool/))

```
npm install --save xml-js   // no need to install this library globally
```

In package.json, write a script:
```json
...
  "dependencies": {
    "xml-js": "latest"
  },
  "scripts": {
    "convert": "xml-js test.json --spaces 4"
  }
```

Now in the command line, you can run this script by typing:
```
npm run convert             // task 'scripts.convert' will be executed
```

## CLI Arguments

```
Usage: xml-js src [options]

  src                  Input file that need to be converted.
                       Conversion type xml->json or json->xml will be inferred from file extension.

Options:
  --help, -h           Display this help content.
  --version, -v        Display version number of this module.
  --out                Output file where result should be written.
  --spaces             Specifies amount of space indentation in the output.
  --full-tag           XML elements will always be in <a></a> form.
  --no-decl            Declaration directive <?xml?> will be ignored.
  --no-inst            Processing instruction <?...?> will be ignored.
  --no-attr            Attributes of elements will be ignored.
  --no-text            Texts of elements will be ignored.
  --no-cdata           CData of elements will be ignored.
  --no-doctype         DOCTYPE of elements will be ignored.
  --no-comment         Comments of elements will be ignored.
  --trim               Any whitespaces surrounding texts will be trimmed.
  --compact            JSON is in compact form.
  --native-type        Numbers and boolean will be converted (coerced) to native type instead of text.
  --always-array       Every element will always be an array type (applicable if --compact is set).
  --always-children    Every element will always contain sub-elements (applicable if --compact is not set).
  --text-key           To change the default 'text' key.
  --cdata-key          To change the default 'cdata' key.
  --doctype-key        To change the default 'doctype' key.
  --comment-key        To change the default 'comment' key.
  --attributes-key     To change the default 'attributes' key.
  --declaration-key    To change the default 'declaration' key.
  --instruction-key    To change the default 'processing instruction' key.
  --type-key           To change the default 'type' key (applicable if --compact is not set).
  --name-key           To change the default 'name' key (applicable if --compact is not set).
  --elements-key       To change the default 'elements' key (applicable if --compact is not set).
```

# Contribution

## Testing

To perform tests on this project, download the full repository from GitHub (not from npm) and then do the following:

```
cd xml-js
npm install
npm test
```
For live testing, use `npm start` instead of `npm test`.

## Reporting

Use [this link](https://github.com/nashwaan/xml-js/issues) to report an issue or bug. Please include a sample code where the code is failing.

# License

[MIT](https://github.com/nashwaan/xml-js/blob/master/LICENSE)


---

# yallist

Yet Another Linked List

There are many doubly-linked list implementations like it, but this
one is mine.

For when an array would be too big, and a Map can't be iterated in
reverse order.


[![Build Status](https://travis-ci.org/isaacs/yallist.svg?branch=master)](https://travis-ci.org/isaacs/yallist) [![Coverage Status](https://coveralls.io/repos/isaacs/yallist/badge.svg?service=github)](https://coveralls.io/github/isaacs/yallist)

## basic usage

```javascript
var yallist = require('yallist')
var myList = yallist.create([1, 2, 3])
myList.push('foo')
myList.unshift('bar')
// of course pop() and shift() are there, too
console.log(myList.toArray()) // ['bar', 1, 2, 3, 'foo']
myList.forEach(function (k) {
  // walk the list head to tail
})
myList.forEachReverse(function (k, index, list) {
  // walk the list tail to head
})
var myDoubledList = myList.map(function (k) {
  return k + k
})
// now myDoubledList contains ['barbar', 2, 4, 6, 'foofoo']
// mapReverse is also a thing
var myDoubledListReverse = myList.mapReverse(function (k) {
  return k + k
}) // ['foofoo', 6, 4, 2, 'barbar']

var reduced = myList.reduce(function (set, entry) {
  set += entry
  return set
}, 'start')
console.log(reduced) // 'startfoo123bar'
```

## api

The whole API is considered "public".

Functions with the same name as an Array method work more or less the
same way.

There's reverse versions of most things because that's the point.

### Yallist

Default export, the class that holds and manages a list.

Call it with either a forEach-able (like an array) or a set of
arguments, to initialize the list.

The Array-ish methods all act like you'd expect.  No magic length,
though, so if you change that it won't automatically prune or add
empty spots.

### Yallist.create(..)

Alias for Yallist function.  Some people like factories.

#### yallist.head

The first node in the list

#### yallist.tail

The last node in the list

#### yallist.length

The number of nodes in the list.  (Change this at your peril.  It is
not magic like Array length.)

#### yallist.toArray()

Convert the list to an array.

#### yallist.forEach(fn, [thisp])

Call a function on each item in the list.

#### yallist.forEachReverse(fn, [thisp])

Call a function on each item in the list, in reverse order.

#### yallist.get(n)

Get the data at position `n` in the list.  If you use this a lot,
probably better off just using an Array.

#### yallist.getReverse(n)

Get the data at position `n`, counting from the tail.

#### yallist.map(fn, thisp)

Create a new Yallist with the result of calling the function on each
item.

#### yallist.mapReverse(fn, thisp)

Same as `map`, but in reverse.

#### yallist.pop()

Get the data from the list tail, and remove the tail from the list.

#### yallist.push(item, ...)

Insert one or more items to the tail of the list.

#### yallist.reduce(fn, initialValue)

Like Array.reduce.

#### yallist.reduceReverse

Like Array.reduce, but in reverse.

#### yallist.reverse

Reverse the list in place.

#### yallist.shift()

Get the data from the list head, and remove the head from the list.

#### yallist.slice([from], [to])

Just like Array.slice, but returns a new Yallist.

#### yallist.sliceReverse([from], [to])

Just like yallist.slice, but the result is returned in reverse.

#### yallist.toArray()

Create an array representation of the list.

#### yallist.toArrayReverse()

Create a reversed array representation of the list.

#### yallist.unshift(item, ...)

Insert one or more items to the head of the list.

#### yallist.unshiftNode(node)

Move a Node object to the front of the list.  (That is, pull it out of
wherever it lives, and make it the new head.)

If the node belongs to a different list, then that list will remove it
first.

#### yallist.pushNode(node)

Move a Node object to the end of the list.  (That is, pull it out of
wherever it lives, and make it the new tail.)

If the node belongs to a list already, then that list will remove it
first.

#### yallist.removeNode(node)

Remove a node from the list, preserving referential integrity of head
and tail and other nodes.

Will throw an error if you try to have a list remove a node that
doesn't belong to it.

### Yallist.Node

The class that holds the data and is actually the list.

Call with `var n = new Node(value, previousNode, nextNode)`

Note that if you do direct operations on Nodes themselves, it's very
easy to get into weird states where the list is broken.  Be careful :)

#### node.next

The next node in the list.

#### node.prev

The previous node in the list.

#### node.value

The data the node contains.

#### node.list

The list to which this node belongs.  (Null if it does not belong to
any list.)


---

# YAML <a href="https://www.npmjs.com/package/yaml"><img align="right" src="https://badge.fury.io/js/yaml.svg" title="npm package" /></a>

`yaml` is a JavaScript parser and stringifier for [YAML](http://yaml.org/), a human friendly data serialization standard. It supports both parsing and stringifying data using all versions of YAML, along with all common data schemas. As a particularly distinguishing feature, `yaml` fully supports reading and writing comments and blank lines in YAML documents.

The library is released under the ISC open source license, and the code is [available on GitHub](https://github.com/eemeli/yaml/). It has no external dependencies and runs on Node.js 6 and later, and in browsers from IE 11 upwards.

For the purposes of versioning, any changes that break any of the endpoints or APIs documented here will be considered semver-major breaking changes. Undocumented library internals may change between minor versions, and previous APIs may be deprecated (but not removed).

For more information, see the project's documentation site: [**eemeli.org/yaml/v1**](https://eemeli.org/yaml/v1/)

To install:

```sh
npm install yaml
```

**Note:** This is `yaml@1`. You may also be interested in the next version, currently available as [`yaml@next`](https://www.npmjs.com/package/yaml/v/next).

## API Overview

The API provided by `yaml` has three layers, depending on how deep you need to go: [Parse & Stringify](https://eemeli.org/yaml/v1/#parse-amp-stringify), [Documents](https://eemeli.org/yaml/#documents), and the [CST Parser](https://eemeli.org/yaml/#cst-parser). The first has the simplest API and "just works", the second gets you all the bells and whistles supported by the library along with a decent [AST](https://eemeli.org/yaml/#content-nodes), and the third is the closest to YAML source, making it fast, raw, and crude.

```js
import YAML from 'yaml'
// or
const YAML = require('yaml')
```

### Parse & Stringify

- [`YAML.parse(str, options): value`](https://eemeli.org/yaml/v1/#yaml-parse)
- [`YAML.stringify(value, options): string`](https://eemeli.org/yaml/v1/#yaml-stringify)

### YAML Documents

- [`YAML.createNode(value, wrapScalars, tag): Node`](https://eemeli.org/yaml/v1/#creating-nodes)
- [`YAML.defaultOptions`](https://eemeli.org/yaml/v1/#options)
- [`YAML.Document`](https://eemeli.org/yaml/v1/#yaml-documents)
  - [`constructor(options)`](https://eemeli.org/yaml/v1/#creating-documents)
  - [`defaults`](https://eemeli.org/yaml/v1/#options)
  - [`#anchors`](https://eemeli.org/yaml/v1/#working-with-anchors)
  - [`#contents`](https://eemeli.org/yaml/v1/#content-nodes)
  - [`#errors`](https://eemeli.org/yaml/v1/#errors)
- [`YAML.parseAllDocuments(str, options): YAML.Document[]`](https://eemeli.org/yaml/v1/#parsing-documents)
- [`YAML.parseDocument(str, options): YAML.Document`](https://eemeli.org/yaml/v1/#parsing-documents)

```js
import { Pair, YAMLMap, YAMLSeq } from 'yaml/types'
```

- [`new Pair(key, value)`](https://eemeli.org/yaml/v1/#creating-nodes)
- [`new YAMLMap()`](https://eemeli.org/yaml/v1/#creating-nodes)
- [`new YAMLSeq()`](https://eemeli.org/yaml/v1/#creating-nodes)

### CST Parser

```js
import parseCST from 'yaml/parse-cst'
```

- [`parseCST(str): CSTDocument[]`](https://eemeli.org/yaml/v1/#parsecst)
- [`YAML.parseCST(str): CSTDocument[]`](https://eemeli.org/yaml/v1/#parsecst)

## YAML.parse

```yaml
# file.yml
YAML:
  - A human-readable data serialization language
  - https://en.wikipedia.org/wiki/YAML
yaml:
  - A complete JavaScript implementation
  - https://www.npmjs.com/package/yaml
```

```js
import fs from 'fs'
import YAML from 'yaml'

YAML.parse('3.14159')
// 3.14159

YAML.parse('[ true, false, maybe, null ]\n')
// [ true, false, 'maybe', null ]

const file = fs.readFileSync('./file.yml', 'utf8')
YAML.parse(file)
// { YAML:
//   [ 'A human-readable data serialization language',
//     'https://en.wikipedia.org/wiki/YAML' ],
//   yaml:
//   [ 'A complete JavaScript implementation',
//     'https://www.npmjs.com/package/yaml' ] }
```

## YAML.stringify

```js
import YAML from 'yaml'

YAML.stringify(3.14159)
// '3.14159\n'

YAML.stringify([true, false, 'maybe', null])
// `- true
// - false
// - maybe
// - null
// `

YAML.stringify({ number: 3, plain: 'string', block: 'two\nlines\n' })
// `number: 3
// plain: string
// block: >
//   two
//
//   lines
// `
```

---

Browser testing provided by:

<a href="https://www.browserstack.com/open-source">
<img width=200 src="https://eemeli.org/yaml/images/browserstack.svg" />
</a>


---

# yocto-queue [![](https://badgen.net/bundlephobia/minzip/yocto-queue)](https://bundlephobia.com/result?p=yocto-queue)

> Tiny queue data structure

You should use this package instead of an array if you do a lot of `Array#push()` and `Array#shift()` on large arrays, since `Array#shift()` has [linear time complexity](https://medium.com/@ariel.salem1989/an-easy-to-use-guide-to-big-o-time-complexity-5dcf4be8a444#:~:text=O(N)%E2%80%94Linear%20Time) *O(n)* while `Queue#dequeue()` has [constant time complexity](https://medium.com/@ariel.salem1989/an-easy-to-use-guide-to-big-o-time-complexity-5dcf4be8a444#:~:text=O(1)%20%E2%80%94%20Constant%20Time) *O(1)*. That makes a huge difference for large arrays.

> A [queue](https://en.wikipedia.org/wiki/Queue_(abstract_data_type)) is an ordered list of elements where an element is inserted at the end of the queue and is removed from the front of the queue. A queue works based on the first-in, first-out ([FIFO](https://en.wikipedia.org/wiki/FIFO_(computing_and_electronics))) principle.

## Install

```sh
npm install yocto-queue
```

## Usage

```js
import Queue from 'yocto-queue';

const queue = new Queue();

queue.enqueue('🦄');
queue.enqueue('🌈');

console.log(queue.size);
//=> 2

console.log(...queue);
//=> '🦄 🌈'

console.log(queue.dequeue());
//=> '🦄'

console.log(queue.dequeue());
//=> '🌈'
```

## API

### `queue = new Queue()`

The instance is an [`Iterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols), which means you can iterate over the queue front to back with a “for…of” loop. Using the iterator will not remove the items from the queue. If you want that, use [`drain()`](#drain) instead.

You can also use spreading to convert the queue to an array. Don't do this unless you really need to though, since it's slow.

#### `.enqueue(value)`

Add a value to the queue.

#### `.dequeue()`

Remove the next value in the queue.

Returns the removed value or `undefined` if the queue is empty.

#### `.peek()`

Get the next value in the queue without removing it.

Returns the value or `undefined` if the queue is empty.

#### `.drain()`

Returns an iterator that dequeues items as you consume it.

This allows you to empty the queue while processing its items.

If you want to not remove items as you consume it, use the `Queue` object as an iterator.

#### `.clear()`

Clear the queue.

#### `.size`

The size of the queue.

## Related

- [quick-lru](https://github.com/sindresorhus/quick-lru) - Simple “Least Recently Used” (LRU) cache


---

# zwitch

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]

Handle values based on a field.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`zwitch(key[, options])`](#zwitchkey-options)
    *   [`one(value[, rest…])`](#onevalue-rest)
    *   [`function handler(value[, rest…])`](#function-handlervalue-rest)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Related](#related)
*   [Contribute](#contribute)
*   [Security](#security)
*   [License](#license)

## What is this?

This is a tiny package that lets you `switch` between some field on objects.

## When should I use this?

This package is very useful when mapping one AST to another.
It’s a lot like a `switch` statement on one field, but it’s extensible.

## Install

This package is [ESM only][esm].
In Node.js (version 14.14+, 16.0+), install with [npm][]:

```sh
npm install zwitch
```

In Deno with [`esm.sh`][esmsh]:

```js
import {zwitch} from 'https://esm.sh/zwitch@2'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {zwitch} from 'https://esm.sh/zwitch@2?bundle'
</script>
```

## Use

```js
import {zwitch} from 'zwitch'

const handle = zwitch('type', {invalid, unknown, handlers: {alpha: handleAlpha}})

handle({type: 'alpha'})

function handleAlpha() { /* … */ }
```

Or, with a `switch` statement:

```js
const field = 'type'

function handle(value) {
  let fn = invalid

  if (value && typeof value === 'object' && field in value) {
    switch (value[field]) {
      case 'alpha':
        fn = handleAlpha
        break
      default:
        fn = unknown
        break
    }
  }

  return fn.apply(this, arguments)
}

handle({type: 'alpha'})

function handleAlpha() { /* … */ }
function unknown() { /* … */ }
function invalid() { /* … */ }
```

## API

This package exports the identifier `zwitch`.
There is no default export.

### `zwitch(key[, options])`

Create a switch, based on a `key` (`string`).

##### `options`

Options can be omitted and added later to `one`.

###### `options.handlers`

Handlers to use, stored on `one.handlers` (`Record<string, Function>`,
optional).

###### `options.unknown`

Handler to use for unknown values, stored on `one.unknown` (`Function`,
optional).

###### `options.invalid`

Handler to use for invalid values, stored on `one.invalid` (`Function`,
optional).

###### Returns

See [`one`][one] (`Function`).

### `one(value[, rest…])`

Handle one value.
Based on the bound `key`, a respective handler will be called.
If `value` is not an object, or doesn’t have a `key` property, the special
“invalid” handler will be called.
If `value` has an unknown `key`, the special “unknown” handler will be called.

All arguments, and the context object (`this`), are passed through to the
[handler][], and it’s result is returned.

###### `one.handlers`

Map of [handler][]s (`Record<string, Function>`).

###### `one.invalid`

Special [`handler`][handler] called if a value doesn’t have a `key` property.
If not set, `undefined` is returned for invalid values.

###### `one.unknown`

Special [`handler`][handler] called if a value does not have a matching
handler.
If not set, `undefined` is returned for unknown values.

### `function handler(value[, rest…])`

Handle one value.

## Types

This package is fully typed with [TypeScript][].
It exports the types `Handler`, `UnknownHandler`, `InvalidHandler`, and
`Options`.

## Compatibility

This package is at least compatible with all maintained versions of Node.js.
As of now, that is Node.js 14.14+ and 16.0+.
It also works in Deno and modern browsers.

## Related

*   [`mapz`](https://github.com/wooorm/mapz)
    — functional map

## Contribute

Yes please!
See [How to Contribute to Open Source][contribute].

## Security

This package is safe.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->

[build-badge]: https://github.com/wooorm/zwitch/workflows/main/badge.svg

[build]: https://github.com/wooorm/zwitch/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/zwitch.svg

[coverage]: https://codecov.io/github/wooorm/zwitch

[downloads-badge]: https://img.shields.io/npm/dm/zwitch.svg

[downloads]: https://www.npmjs.com/package/zwitch

[size-badge]: https://img.shields.io/bundlephobia/minzip/zwitch.svg

[size]: https://bundlephobia.com/result?p=zwitch

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[typescript]: https://www.typescriptlang.org

[contribute]: https://opensource.guide/how-to-contribute/

[license]: license

[author]: https://wooorm.com

[one]: #onevalue-rest

[handler]: #function-handlervalue-rest


---

# Scraper

This directory contains the config to run the Typesense Docsearch scraper.

First you need to copy the `.env.example` file and fill in the values for your Typesense instance.

```bash

### Local usage

To populate a locally-running Typesense instance, change the `config.json` file to point to the locally-running docs site:

```json
{
  "start_urls": [
    "http://host.docker.internal:3000/"
  ],
  "sitemap_urls": [
    "http://host.docker.internal:3000/sitemap.xml"
  ],
  "allowed_domains": [
    "host.docker.internal"
  ]
}
```

Then run:

```bash
docker run -it --env-file=.env -e "CONFIG=$(cat config.json | jq -r tostring)" typesense/docsearch-scraper:0.7.0
```